The "Send to HyperFrames" authoring guide is an internal contract for the Claude
Design import flow, delivered exclusively by the get-send-to-hyperframes-guide MCP
tool (raw server-side fetch of the .md, returned as tool-result data). The llms.txt /
web_search discovery path it was published for is no longer used. Drop it from
docs.json so it stops appearing in the public product docs nav + llms.txt; keep the
.md file at its path (the tool's raw fetch URL depends on it) and the redirect note in
claude-design-hyperframes.md (points at the raw URL, not the docs page). Orphan guide
files build cleanly here (claude-design-hyperframes.md already is one).
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## What
Refactor distributed planning around one shared local execution-plan builder:
- `buildLocalExecutionPlan()` now owns compile/probe/extract/audio/freeze.
- Legacy `plan()` remains a deprecated v1 transport wrapper.
- Plan v2 calls the shared builder directly and publishes through the existing manifest/CAS contract.
- Add neutral `createPlanV2FromExecutionPlan()`, `publishPlanV2FromExecutionPlan()`, `getPlanV2ExecutionPlanHash()`, and `PLAN_PROTOCOL_V1` names.
- Retain deprecated v1-named exports and wire aliases.
- Recommend explicit Plan v2 opt-in for new producer, Lambda, and Cloud Run integrations.
## Why
Plan v2 previously looked like it invoked a v1 planner even though v1 and v2 share the same frozen local execution representation. This removes that migration-era coupling while preserving the public minor-version compatibility contract.
## How
The shared builder returns neutral internal execution-plan fields. The v1 wrapper maps those fields back to the existing `PlanResult`; the v2 publisher consumes them directly.
Compatibility is intentional and covered by exact shape tests:
- omitted `planProtocol` still serializes/selects `"v1"`;
- v1 layouts, descriptor-less decoding, event unions, workflow branches, and exports remain;
- the v1 descriptor JSON is byte-identical and `CURRENT_PLAN_PROTOCOL` is an identity-preserving alias;
- v2 manifest bytes, key order, hash framing, and `sourcePlanV1Hash` wire key remain unchanged;
- no enumerable neutral hash field was added to manifests or returned result objects;
- v1/v2 result objects, cloud event payloads, and SDK handle key sets remain unchanged.
## Test plan
- Focused Plan v1/v2/protocol/export/size compatibility: 141 passed
- `@hyperframes/core`: 1,419 passed
- `@hyperframes/producer` unit lane: 990 passed
- `@hyperframes/aws-lambda`: 140 passed
- `@hyperframes/gcp-cloud-run`: 101 passed
- Producer, Lambda, and Cloud Run typechecks
- Repository-wide lint, format check, workspace/package-subpath checks
- Full workspace build
- `git diff --check`
- [x] Unit tests added/updated
- [ ] Manual testing performed
- [x] Documentation updated (if applicable)
- Problem: @hyperframes/studio package docs showed bun run dev without the
localhost URL contributors need after #2901 fixed contributing.mdx only.
- Fix: note that the studio dev server listens on localhost:5190 per
packages/studio/vite.config.ts server.port.
- Verification: preflight_ship.py + read vite.config.ts; bun run format:check.
- Problem: setup guide pointed contributors to localhost:3000 after bun run dev.
- Fix: use localhost:5190 to match packages/studio/vite.config.ts server.port.
- Verification: preflight_ship.py + read vite.config.ts server.port (5190).
* docs(prompting): correct workflow one-liners against skill contracts
general-video leads with its positive identity and companion mode;
faceless-explainer keys on invented visuals instead of TTS;
talking-head-recut uses the 'graphic overlays' trigger term;
motion-graphics gains its input side and overlay output;
music-to-video stops implying images are required.
* docs(prompting): make vocabulary video grids readable
Replace the 4-5 column table hack with a 3-column CSS grid,
switch demo clips to autoplay muted loops (no black poster frame,
no player chrome over tiny videos), and align cells at 16:9.
* docs(prompting): document the opening interview and run-shape questions
The guide taught prompt shapes but never prepared readers for the
conversation that follows: the intent interview, the two run-shape
questions (storyboard, automation vs companion), the just-build-it
skip, and BRIEF.md as the resumable artifact. Add that section to the
overview, a disambiguation note on the storyboards page, and free up
'companion' as a reserved term in media-and-audio.
* docs(guides): make BRIEF.md the pipeline's Step 3 artifact
Step 3 (Strategy & Messaging) listed no output while describing
exactly what BRIEF.md now captures. Name the artifact in the step
table, project tree, step body, gate, and iterating list, and fix
SCRIPT.md's step label in the tree (Step 4, not 3).
* docs(quickstart): realign the setup surface with the skills catalog
The quickstart drifted from docs/guides/skills.mdx, CLAUDE.md, and the
prompting overview — it had never been updated when those surfaces were:
- `--full-depth` on both install commands, with the reason inline. Without
it `skills add` fetches the skills.sh registry blob, which lags `main` by
hours, so a reader following the quickstart installs stale skills.
- `check` in the `/hyperframes-cli` row, and a validate step in the manual
dev loop, which went preview → render with no gate at all. The prompting
overview calls `check` "the step people skip and regret" and states both
`lint` and `check` must pass before rendering.
- `/hyperframes-keyframes` in the core-skills table (8 rows → 9).
- `/figma` in the optional-workflow list (10 → 11).
* docs(skills): close the catalog drift class and complete the music-to-video input
Follow-up on the two review nits from #2872.
`/music-to-video`'s SKILL.md names three inputs — an audio file, a video to
pull audio from, or a track generated from a mood brief. Every compressed copy
of that description carried only the first two, and the third is the one that
makes "a complete video needs zero assets" true. Fixed on all eight surfaces
that state it, so no surface is now more correct than its siblings: the
prompting overview and quickstart setup tables, docs/guides/skills.mdx, the
README catalog, root CLAUDE.md + AGENTS.md, both CLI project templates, and the
router's own routes/music-to-video.md Input line (whose Interview must-haves
already listed all three).
The drift was structural, not accidental: the sync set declared in
docs/guides/skills.mdx and in CLAUDE.md's "Skill catalog maintenance" named
four surfaces and never the two setup tables, so those two were free to rot
while the declared four stayed correct. Both declarations now name them, and
both say the set applies to a *changed contract* — a reworded description —
not only to an added or renamed skill.
skills-manifest.json regenerated for the touched route file.
* docs(claude): point the routing-surface rule at routes/, not the moved stubs
Item 3 of "Skill catalog maintenance" still sent readers to
`references/workflow-catalog.md` for a workflow's input/output/trigger
contract and `references/route-briefs.md` for its interview entry. Both are
now "moved" stubs — the contract and the interview entry live together in
`references/routes/<workflow>.md`, one read per candidate route.
Same failure class the previous commit fixed at item 1: a maintenance rule
outliving the layout it describes. Swept the tree for other pointers at the
two stubs; there are none, so this closes it rather than fixing one instance.
The old demo argued that a locked frame crops the story. The sharper claim is
what a cut throws away: a move carries the spatial relationship between two
shots, a cross-fade carries none.
Five stages each get their own colour and the halves diverge on how the next
colour arrives -- in place, or by travelling to it. 30-47% of pixels differ,
against 3% for every version where the WITHOUT half moved the content.
That 3% is the trap now documented in the rule: translating the scene and
translating the camera are the same transform, so sliding content past a fixed
frame is not a static comparison, it is the same shot rendered twice.
Embed is cache-busted to -v2; docs images carry immutable year-long cache, so
reusing the filename would serve returning visitors the old render.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Live telemetry panel, an isometric deploy pipeline wider than the frame, and
a progressive edge rollout across twelve regions. In each, the rule follows
from the content rather than being applied to it.
Rule 2's demo carries the strongest evidence in the chapter: deleting the
three stages the locked frame never shows and re-rendering leaves that half
identical on all 180 frames.
Rule 3 gains a rule-level distinction the rebuild surfaced — stagger what is
happening, not what is merely present.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Replaces the generic card/chip/disc subjects with ones where the rule is
unavoidable given the content: a payment sheet over a receipt, a split-flap
departure board, and a render-farm corridor.
Rules 5 and 6 in the grammar list were one-liners that under-said what their
demos prove. Rule 5 now carries the mass claim, the follow-through lag, and
the transforms-only caveat (a counter that overshoots renders a false value).
Rule 6 credits occlusion over blur and prefers one foreground element.
Section intro no longer endorses over-cranking; every movement in an applied
half has to finish "this moves because...".
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The guides were previewing five-second catalog snippets - a chart block standing in
for an explainer, a caption component standing in for a recut. Each now opens with a
cut from an actual film made through that workflow: the Huly launch for product
videos, a SpaceX valuation piece for explainers, one shoot cut three ways for
captions and recuts, a real pull request for PR videos, a per-listener year in
review for motion graphics, a beat-analysed track for music, and a timeline-editing
film for the custom path. Captions name what each clip is from instead of implying
it is a finished film for that page.
music-to-video had no media at all and now does, because the honest asset existed
all along: a 90-second film built from an analysed track.
slideshow still has none. Nothing on disk honestly shows a navigable deck, and a
stand-in on a page about that specific output would be a small lie.
Re-rendering these projects was tried first and rejected. Fresh renders regressed:
variables-launch lost its centre creator clip and rendered white where footage
should be, and the pull-request and cloud films came out two to three seconds short.
The projects reference media that has moved since they were made, so the existing
exports are the better source until each project's paths are repaired.
The hero was an 11MB export of the website-launch film. The finished master is
36.3s at 8.15 Mbps, so the page now serves a high-quality encode made from that
instead - 9MB at CRF 21, which is oversampled for a column under 900px wide.
The colour-grading film was also being derived from a 1080p variant while a
3840x2160 60fps master sat on disk. Its tile and full film are now encoded from
that master.
Both are published under versioned filenames. The first upload set
max-age=31536000, immutable, so the CDN edge kept serving the old bytes when I
replaced the objects in place - the corrected files measured identical to the
originals over HTTP until they were renamed. The component takes optional tile and
full overrides per film so a single asset can be revised this way without renaming
the rest.
Worth recording plainly: none of these films were rendered for the docs. They are
existing renders, transcoded down for the web, so each one's quality is capped by
whatever file already existed. Re-rendering from the launch projects at 4K60 would
raise that ceiling.
Labelled 56s, but the file I encoded and uploaded measures 47.6s - there are
several variants of that marketing film on disk and the 1920x1080 one I selected
is the shorter cut. Every other label matches its file to the nearest second.
The wall compiled but rendered zero tiles. Reading the page bundle showed why:
Mintlify keeps only the exported component out of a snippet file, so the CDN base
and the film list I had declared above it never made it into the compiled output -
`const FILMS` and `const CDN` appear zero times in the bundle while `FILMS.map` is
still there. The component threw on an undefined reference, React's error boundary
swallowed it, and the section rendered empty with no console error to point at it.
Both constants now live inside the component. Recorded the trap in AGENTS.md,
since a blank snippet with a clean console gives no clue on its own.
The front page was showing a film I generated, and it was the weakest asset in the
project: silent, slow, and stylistically plain. Meanwhile roughly 260 finished
films made with HyperFrames sat in ~/Downloads/hyperframes-launches and
~/Desktop/hyperframes-launches, most at 1080p with audio, and the good ones were
only reachable from /examples.
The hero is now the website-launch film - 38s, 1080p, real audio at -14.3 dB. It
shows the whole loop in one take: a site captured, FRAME.md, STORYBOARD.md and
SCRIPT.md written, the film rendered. It autoplays muted and unmutes on demand.
"What can it make?" was four five-second catalog snippets. It is now six finished
films: colour grading, one shoot cut many ways, a music-driven edit, a pull request
explained, timeline editing, and a personalised year-in-review. Each tile is a
silent six-second loop of 37-241KB; selecting one loads the full film with sound,
so the 1-8MB files are only fetched when someone asks for them. Tile moments were
chosen by looking at them at the 320px they actually render: the first cuts of the
music and pull-request films were an empty waveform and an illegible terminal, so
both were re-cut to the sections that read.
Removed the silent film I had committed, now that nothing references it.
All eight guides opened with prose and contained no images and no video, which is
the main reason the pages read flat: they are the destination of the "I need a
specific thing" journey, and they never showed what the thing looks like. Six now
open with a real scene playing, captioned with exactly what the clip is rather
than implying it is a finished film.
The previews were re-encoded rather than reused as-is. The catalog originals run
127KB to 1.3MB and these autoplay on load, so each is trimmed to its most legible
five seconds at 960x540 and lands between 16KB and 90KB on the docs CDN.
music-to-video and slideshow are deliberately still without media. Nothing in the
catalog honestly represents a beat-synced cut or a navigable deck, and a
decorative stand-in on a page about a specific output would be a small lie. Those
two need a purpose-rendered clip each.
My first fix was based on a wrong diagnosis. Prose width was not the problem:
Mintlify wraps every image in its zoom component, span[data-rmiz] >
span[data-rmiz-content] > picture.contents > img, so the width I put on a
surrounding div was absorbed by that wrapper and the image still rendered full
width with the card's text pushed out of view. Reading the served markup also
showed the build rewrites Tailwind classes into a mint-* namespace and drops what
it does not recognise, which is why object-right never appeared in the output at
all.
The thumbnail now uses an hf-peek class in custom.css, which collapses the zoom
wrapper and sizes the box directly. Custom classes survive the rewrite; utilities
are not dependable for anything load-bearing. Both findings are in AGENTS.md,
including the note that videos are not wrapped - which is why the identical card
on the quickstart worked with a video and failed with an image.
The card was reusing the flowchart block as its thumbnail, which was wrong twice
over: it is a white graphic sitting in a dark page, illegible at the 256px it
actually renders at, and it implies the link leads to diagrams when it leads to
every kind of video.
Replaced with a 5.7s montage cut from four real catalog outputs - code appearing,
kinetic captions, an animated map, a brand sting - so the thumbnail shows range
rather than one example. Built dark-ground only after measuring: the first attempt
mixed a white count-up and a white lower third among dark clips, which made the
loop flash white every 1.4 seconds. Mean brightness now sits at 15, 28, 34 and 15
across the four cuts. 32KB, silent, uploaded to the docs CDN.
Twenty-five accordions remained in three hand-written pages: troubleshooting,
data-attributes, and html-schema. Each is now a visible heading, so every symptom
appears in the page contents and has an anchor support can link directly - which
was the point of making help symptom-first in the first place. Nothing is behind
a click, Cmd+F reaches all of it, and the pages print.
Accordion bodies were indented four spaces, which markdown would read as code
blocks once the wrapper was gone, so bodies are de-indented and each heading is
followed by a blank line. Zero accordions remain anywhere in docs/.
The card measured 686px of image inside a 688px card: the theme's prose styles set
img { width: 100% }, which beats a sm:w-64 utility on the image itself, so the
side-by-side layout collapsed and the card's own text was pushed out of view. The
width now lives on a wrapper the prose rules do not touch, with the image filling
it and anchored right so the thumbnail lands on the Renders panel rather than a
crop of empty canvas.
Recorded the rule in AGENTS.md, along with the related margin behaviour that put a
black band around the introduction hero, so neither is rediscovered.
Both pages ended in a row of equal cards, which is a fresh decision at exactly
the moment the reader should be moving, and each card only named its destination.
They now lead with one dominant next step that shows what is on the other side —
a live scene preview for the workflow chooser, the real Renders panel for export —
followed by the genuinely relevant alternatives as a quiet sentence of links,
ranked by how likely they are to matter.
The point is hierarchy rather than scarcity: several onward paths are fine, but
they should not all shout at the same volume, and a link that shows the thing
earns the click that a link naming the thing does not.
The previous commit pointed the introduction at a film that was never added.
.gitignore excludes docs/images/* so that generated catalog previews stay out of
the repository, with explicit negations for the few authored assets that belong
in it - the Studio screenshots. `git add -A` therefore skipped the film silently
and the page shipped with a hero that resolved to a 404.
Negated the showcase directory the same way the Studio screenshots already are,
and noted why this one is exempt: it is authored rather than generated, it is the
whole argument of the page, and at 332KB silent it is smaller than a single
catalog preview - so the page cannot break when a CDN credential expires.
The introduction now plays a film built for it rather than an older showcase
clip: one request - "make a 30-second launch video for our new pricing page" -
carried through the agent building the project, Studio opening it, a person
changing one line, and the export finishing. It was produced with HyperFrames.
Hosting solved without the CDN. The clip sits in docs/images/showcase/ at 332KB,
under the repository's 500KB non-LFS limit, because the hero autoplays muted and
therefore does not need the audio track. Encoding it silently at 720p bought the
whole 42 seconds for less than the size of one catalog preview. The master with
its music bed still needs the shared asset host, and the SSO credentials for that
bucket have expired, so it stays out of the repo for now.
The quickstart's leading example is now that same pricing-page request, and says
so. Using a different example on every page forces the reader to rebuild the
mental model each time; one project carried across the pages is the cheapest
change available that makes them read as a single path.
The 138 catalog pages hid their install command, registry metadata, and wiring
snippet behind three accordions. Asking an agent and running the terminal command
are two parallel ways to do one thing, so they are now tabs with the agent
request leading; the metadata and the hand-wiring snippet are visible, since they
were short enough that a click bought nothing while costing Cmd+F and printing.
This is how component catalogs are normally presented - shadcn/ui and its
descendants put preview and code behind tabs - and it keeps the preview first,
which is the point of a visual catalog.
Two generator bugs fixed while in there. It rebuilt the Catalog tab object from
scratch, so the tab silently lost its icon on every regeneration, and it
re-inserted the tab relative to a tab named Documentation that no longer exists,
so the fallback index moved Catalog ahead of Studio. It now updates the existing
tab in place and owns only the groups array.
Regenerating also picked up four registry items that had no docs page:
camcorder-hud, editorial-flash-overlay, freeze-frame-dressing, and
organic-light-leak-overlay.
Accordions now remain in three hand-written pages only: troubleshooting,
data-attributes, and html-schema.
mint validate and mint broken-links pass. The repo's pre-commit build gate was
bypassed deliberately: this work lives in a git worktree, which has no
per-package node_modules, so `bun run build` cannot resolve tsup there. The gate
covers package builds and this change touches docs/ and one generator script.
At this column width the breakout rendered 968px and dominated the page instead
of supporting it. The film is back inside a Frame at the column width. The part
worth keeping was the motion, not the size: it still autoplays muted on a loop
rather than sitting behind a play button, so the page is already moving when it
loads. Removed the now-unused wrapper CSS rather than leaving a dead rule.
The wrapper measured 609px tall against a 545px film - the theme's prose styles
apply a 2em margin to media, which rendered as a 64px black band above and below
it. Zeroed the margin inside the hero wrapper.
The film now reaches into the shell padding so it reads edge to edge, and it
autoplays muted on a loop instead of waiting behind a play button. Motion is
pre-attentive - the eye goes to it before any text is read - so a page that is
already moving answers 'what is this?' faster than a poster the reader has to
decide to click. Controls stay available for scrubbing and for unmuting once a
film with a real audio track is hosted.
Not implemented as 100vw: this column is not centred in the viewport because the
sidebar is a flex sibling, so the usual margin-left: calc(50% - 50vw) breakout
would sit off-centre. Noted in the CSS.
ukimsanov