Commit Graph
3649 Commits
Author SHA1 Message Date
Miguel Angel Simon Sierra efcf3942f7 refactor(studio): one JSON store behind every persisted setting
Three modules were each re-implementing the same four concerns — reaching a
Storage that can throw, parsing JSON that may be anything, deciding what a bad
value means, and writing without letting a quota error escape — with their own
try/catch and their own answer to each. createJsonStore owns the first, second
and fourth; a caller supplies only its key, its fallback, and how to read its
own shape.

UI preferences, agent drafts and render settings now sit on it. Validation
stays with each caller, since only it knows which fields are meaningful.
2026-08-04 15:57:28 -07:00
Miguel Angel Simon Sierra 6233723a43 fix(studio): keep a half-typed instruction across a reload
The agent edits files, the watcher reloads the preview, and the reload took the
composer's React state with it — an instruction being written while an earlier
run landed disappeared mid-sentence. Drafts are now stored per element, so a
reload (or a trip to another element and back) returns the words, and
submitting clears them.
2026-08-04 15:52:07 -07:00
Miguel Angel Simon Sierra 234c6cd482 fix(studio): keep the agent controls above the motion path
The composer and the ask handle sat at z-20 inside the canvas overlay, but the
overlay's own decorations climb to z-40 — so the motion path and its keyframe
diamonds drew straight through the pill. Both now sit above them, through one
named constant rather than a number picked per component.
2026-08-04 15:48:23 -07:00
Miguel Angel Simon Sierra 21f960cffa refactor(studio): one floating chrome for everything drawn over the canvas
The composer, run tray, both context menus and the ask handle each carried
their own copy of the same surface (layered shadow, hairline ring, blur) and
row treatment, which is how the menus and the tray drifted apart in the first
place. They now share components/ui/floatingSurface.

Also reworks the ask affordance: a mark at rest that widens into "Ask ⌘K" on
hover, in CSS, instead of the native OS tooltip that covered the element it
pointed at.

Selection chrome on a 3D-transformed element: rect + angle cannot describe a
keystoned projection, so the overlay drew a rotated box beside the element and
the crop frame landed somewhere else entirely. A projection that is not a
rotated rectangle now reports its axis-aligned bounds and says so, and crop —
which only exists in the element's own plane — stands down.
2026-08-04 15:41:02 -07:00
Miguel Angel Simon Sierra 4380c7067f fix(studio): offer the agent on the selection instead of opening on it
Auto-opening the composer on every selection put a panel on the canvas whether
or not the user wanted to ask for anything. The entry point is now a small
harness mark pinned to the selection: it sits where the eye already is, opens
the composer on click, and names the ⌘K shortcut in its tooltip — discoverable
without taking the canvas.

Also gives the run tray an inline z-index. It carried a utility class that lost
to the timeline ruler and the panels, so the ruler drew straight through the
tray's rows.
2026-08-04 15:28:02 -07:00
Miguel Angel Simon Sierra 87ad9804f8 feat(studio): composer follows the selection, and speaks for a whole one
Selecting an element now opens the composer on it — the selection was already
the ask, and waiting for a second gesture on the thing just clicked was a step
for nothing. A multi-selection carries through: the prompt names every
co-selected element and widens its guardrail to "change every one of them", and
the field says how many it is talking about.

The harness and model lists are capped and scroll on their own instead of
growing the composer, and they declare they own their wheel so the canvas
underneath stays put.

Adds usage telemetry for the whole surface — composer opened, run submitted,
harness and model chosen, custom harness added — carrying the harness, model
and element count, never the instruction text.
2026-08-04 15:19:15 -07:00
Miguel Angel Simon Sierra c1697c9b50 feat(studio): model beside the harness, and bring your own harness
The model was buried at the bottom of the harness menu, where it read as a
detail of the harness rather than the other half of "who will do this". It is
now its own chip to the right of the harness, with its own list.

Harnesses are no longer limited to the four Studio ships presets for: the
picker can register one, with the same fields a preset carries — command, args
before the stdin prompt, its own mark, and the flag it takes a model on. They
live in <project>/.hyperframes/agents.json, so the choice travels with the work
instead of being an environment variable one machine knows about.

Harness selection is by id now rather than kind, since two custom harnesses can
share the "custom" kind.
2026-08-04 15:07:13 -07:00
Miguel Angel Simon Sierra 3aa6976275 refactor(studio-server): declare JSON boundaries as schemas, not hand guards
The selection route validated its payload with ~75 lines of isRecord /
hasString / isFiniteNumber helpers sitting next to a hand-written interface
describing the same shape — two definitions that could drift, and the pattern
the agent routes were copied from. Both are now one zod schema with the public
types inferred from it, so the validator and the type cannot disagree. The
Google Fonts metadata parse follows.

Net -115 lines, same behaviour: the existing selection route tests pass
unchanged.
2026-08-04 14:51:47 -07:00
Miguel Angel Simon Sierra 6da40a2a14 feat(studio): pick the model per run, defaulting to the cheapest that can run
Models come from the models.dev catalog — the same community index other agent
tools read — filtered to the provider each harness authenticates against and to
models that can actually call tools. Nothing about a model is hardcoded here: a
model released next week shows up without a change to Studio, and the catalog's
own pricing decides the default, which is the cheapest model that can drive a
run rather than whatever the harness would reach for.

The composer's picker gained a model list (cheapest first, with input price),
the choice is remembered per harness in the studio preferences, and each run in
the tray shows the model it actually used.

Payloads that cross a boundary — request bodies, the run log, the catalog — are
now zod schemas with inferred types instead of hand-written `unknown` readers
and casts.
2026-08-04 14:46:12 -07:00
Miguel Angel Simon Sierra fe242efa4e feat(studio): name the harness everywhere, ⌘K to ask, tray out of the canvas
Every agent affordance now names the harness that will actually run — the
context menus, the inspector footer and the empty state read one effective
value, so a picked Codex can never sit behind a menu still offering Claude
Code. ⌘K opens the composer on the current selection.

The marks are the vendors' own: OpenClaw's pixel lobster and the Nous Research
portrait Hermes ships, alongside Claude's and OpenAI's.

The run tray moved off the canvas — it floats over the shell, drags anywhere,
and remembers where it was parked. Harness pick, tray position and collapsed
state all live in the studio preferences file rather than being re-chosen every
session.

Context menu rows were rebuilt as inset items so a hover fill covers the whole
row instead of leaving gutters at the edges.
2026-08-04 14:25:59 -07:00
Miguel Angel Simon Sierra ca3198d8b9 fix(studio): read a run's state from its own row, not a status dot
The dot repeated what the row already said. A run in flight now carries a
progress rail instead — sweeping while the agent works, still while it waits —
and a waiting run says where it sits ("Next up", "#3 in line") rather than
just "Queued".

History written before runs recorded their harness fell back to the neutral
mark; the harness is now recovered from the logged label, so past Claude Code
runs stop rendering as an anonymous spark.
2026-08-04 14:03:20 -07:00
Miguel Angel Simon Sierra ebb38675e9 feat(studio): pick the harness per run, reveal the element it edited
The composer header is now a picker: every harness Studio knows is listed with
whether it is installed, so a queue can mix Claude Code, Codex, Hermes and
OpenClaw instead of taking whatever was auto-detected. Each carries its own
vendor mark, and the tray stacks one mark per harness in play (only when more
than one is).

Each run also carries its session id and the coordinates of the element it
edited: clicking the element name seeks back to that moment and re-selects it.

Fixes a wheel over the run list panning the canvas underneath instead of
scrolling the list — floating overlays now declare that they own their own
scrolling, which the preview checks before it pans or zooms.
2026-08-04 13:58:11 -07:00
Miguel Angel Simon Sierra 88a8ef5924 feat(studio): editable agent queue and a durable run log
The queue was a promise chain, so a waiting run could only be watched. It is
now an explicit list: queued runs can be moved sooner or later, dropped before
they start, and a run already going can be stopped (the tray reveals those
controls on hover).

Every settled run is appended to <project>/.hyperframes/agent-runs.jsonl —
when it ran, which element, the instruction, how long it took and what the
agent reported back. Studio reads that log when a project is first listed, so
the history survives a server restart instead of living only in memory.
2026-08-04 13:37:27 -07:00
Miguel Angel Simon Sierra 28484de469 fix(studio): name the harness in the composer header
The header repeated the selected element, which the field's own placeholder
already says. It now names the agent that will run the instruction (Claude
Code, Codex, …), falling back to the element when no harness is installed.
2026-08-04 13:14:42 -07:00
Miguel Angel Simon Sierra 2fd04398de feat(studio): queue agent runs server-side with a live run tray
Runs become server-owned jobs instead of one blocking request. Submitting
clears the field immediately, so several instructions can be fired at
different elements in a row; per project they execute one at a time, since two
agents rewriting the same composition would clobber each other.

A tray on the canvas lists every run with what the agent is doing right now
(Claude Code runs in stream-json so each tool call surfaces as it happens),
its target, elapsed time and final message. The list is read from the server,
so a page reload lands back on the work still in flight.

Adds Hermes and OpenClaw presets alongside Claude Code and Codex, each with
its own mark, and HYPERFRAMES_AGENT_ICON to point any other harness at a real
icon file.
2026-08-04 13:11:18 -07:00
Miguel Angel Simon Sierra 2db190780c feat(studio): draggable agent composer with the running harness mark
The composer can cover the element it edits, so its header is now a drag
handle. The header also shows which harness is running: the server reports a
kind alongside the label (claude / codex, sniffed from a custom
HYPERFRAMES_AGENT_CMD and defaulting to claude when inconclusive) so the mark
is never blank.
2026-08-04 12:25:29 -07:00
Miguel Angel Simon Sierra 6d48919c12 feat(studio): inline the agent composer on the canvas
Replace the full-screen Ask agent modal with a composer anchored to the
selected element: no backdrop, the composition stays visible while the agent
edits it, and the box stays open between runs so the next instruction is one
keystroke away. Status (working / finished / failed) reports in the composer
itself instead of a toast, and the canvas right-click menu gets the same
entry as the timeline clip menu.

Drops the never-set anchor-point plumbing and the modal's context-preview
builder along with the modal.
2026-08-04 12:19:57 -07:00
Miguel Angel Simon Sierra 0f62ba2950 feat(studio): run the user's agent CLI from Studio
The Ask agent modal could only copy a prompt to the clipboard. Studio now
hands that same prompt to whichever harness CLI is installed (claude, codex,
or HYPERFRAMES_AGENT_CMD), runs it in the project dir, and lets the existing
file watcher reload the preview. Timeline clips get the same entry point via
their context menu, resolved back to the live DOM element so the prompt
carries full element context.
2026-08-04 11:42:24 -07:00
Vance Ingalls f9ec93459f Merge pull request #2945 from heygen-com/ffprobe-6-argv-sweep
fix(cli,core,lint,producer,studio-server): terminate ffprobe options everywhere, pin the contract
2026-08-04 10:43:14 -07:00
Miguel Ángel ac6fd5363b Merge pull request #3009 from heygen-com/release/v0.7.92
chore: release v0.7.92
v0.7.92
2026-08-04 10:43:02 -07:00
Ular Kimsanov 77f95e46e0 Merge pull request #2976 from heygen-com/docs/quality-system
docs: add documentation quality gates
2026-08-04 04:34:20 -07:00
Ular Kimsanov 836426812a Merge pull request #2975 from heygen-com/docs/catalog-presentation
docs: make Catalog visual and reproducible
2026-08-04 03:41:53 -07:00
Vance IngallsandClaude Opus 5 1664fe6ad7 fix(core,producer,skills): unicode paths, non-Error rejections, shell callers
Three R3 findings.

The redactor's segment classes were ASCII `\w`, so `/数据/客户/秘密视频.mp4` and
`/data/客户/secret.mp4` went out verbatim — and the generic redactor also feeds
CLI telemetry and producer observation messages, where no known-path list
compensates. Segments are now defined by their delimiters instead of an
alphabet, which is correct for every script by construction rather than
requiring Unicode classes to be kept correct. The bare-relative lookbehind had
the same ASCII assumption and let a match start mid-token, redacting
`客户/秘密/视频.mp4` to `客户[path]`; it is now a token boundary, and
bare-relative runs before absolute so it claims the whole token.

sanitizeProbeFailure cast the rejection reason to Error and read `.message`.
An injected probe can reject with anything, so `Promise.reject("failed")` gave
`undefined` and threw inside the redactor — converting a returned failure
result into a rejected promise. Normalized at the boundary, and
redactKnownPaths no longer throws on a non-string.

The contract only admitted .ts/.js/.mjs/.cjs, so it missed shipped shell and
Python callers. frame_strip.sh passed a user-controlled path as ffprobe's last
positional with no terminator; render-and-composite.sh had four more. Both
fixed, and the sweep now covers .py/.sh. Python list argvs are bracket
literals so they get the same position check; shell command lines get a
separate presence check, because checking position there needs a shell parser
— stated as the weaker guarantee it is rather than implied to be equal.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 03:18:21 -07:00
ukimsanov da35679bf9 docs: widen the accordion exception to the pattern it actually covers
Rames' first item on #2976. The clause named one page while the tree has 48
accordions across eight files: 20 in the verified-example gallery it means, and
28 under per-page `## Variants` headings — which the component table two lines
above routes to `Tabs`.

That contradiction matters more than usual because this file instructs agents.
The next one asked to bring the docs in line reads 28 compliant blocks as
violations and converts them.

Named by pattern now, with the reason the Tabs row does not reach them: Variants
blocks hold long alternative prompts a reader picks one of to read in full, not
parallel ways to perform the same step. Pre-existing and untouched by this PR —
the fix is the sentence, not the tree.
2026-08-04 03:06:59 -07:00
ukimsanov e94a458fed docs: correct two contributor instructions that the source contradicts
Both P1s from Miguel's review on #2976.

**The weekly changelog command has a fourth output, and it is public.**
`changelog-process.mdx` listed three internal drafts. `outputWeeklyDraft` also
calls `prependDocsUpdate` on `--write` (`scripts/changelog-weekly.ts:236`),
which writes straight into `docs/weekly-updates.mdx`. A contributor following
the page would review three files and push a fourth unread. Now called out as a
warning, with the re-run behaviour, since that is what makes editing the entry
afterwards safe.

The same paragraph also said Weekly updates is "unlisted in the sidebar". That
was true when written and I made it false myself, putting the page back under
Explore in #2978 after Rames found it orphaned. Corrected rather than reverted —
the page belongs in the sidebar.

**Bare `hyperframes lint` cannot validate a registry item.** Both
`contributing.mdx` and `contributing/catalog.mdx` told contributors to run it.
The CLI resolves a project by looking for `index.html`
(`packages/cli/src/utils/project.ts`), and registry items ship as `<name>.html`
or `demo.html`, so it fails with "No composition found". This is not
theoretical: `scripts/lint-registry-items.mjs` exists precisely for this shape
and its header records two `gsap_non_transform_motion` errors that reached main
unlinted because of it.

Both pages now document `bun run lint:registry-items`, and the Catalog page
shows the install-into-a-scratch-project route for the full `check` gate rather
than claiming a bare `check` covers a registry item.

Verified by running the documented command, not just by reading the script.
2026-08-04 03:06:59 -07:00
ukimsanov fd90fd3e72 docs: correct the docs rules and label the Prompt Guide previews
Three things the quality layer asserted but the pages did not support.

changelog-process said "do not recreate docs/weekly-updates.mdx; that empty
public page was retired" while the page exists with a real curated feed. It
describes the page as it is: unlisted, reachable by URL and RSS, with versioned
notes still in the Changelog.

The Related-topics rule read as universal, but three different endings are in
use and each is right for its shape — Related topics on task pages, a single
Next line through the Prompt Guide's numbered sequence, and nothing on
reference and concept pages. The rule now says that, and every section matches
it; color-grading gained the Next line it was missing and no longer points at a
page this stack retired.

The vocabulary previews were 18 DocsVideo players in three unlabelled grids, so
a reader saw several near-identical clips with no way to tell smooth from
snappy. They are now native muted loops with visible captions, which is what
AGENTS.md asks for small preview loops in the first place.
2026-08-04 03:06:58 -07:00
ukimsanov 174bd4e2dc docs: add documentation quality gates 2026-08-04 03:06:58 -07:00
ukimsanov 4ef1511b19 ci: re-run catalog previews when the containment module changes
Rames' non-blocking note on #2975. The paths filter listed the renderer but not
scripts/registry-target-paths.mjs, which it imports — so a future change to the
path-traversal defence alone would never re-run the only job that exercises it.

That is the same shape as the bug the module exists to prevent: the check is
present, the thing that would catch a regression in it is not wired to run.
2026-08-04 03:06:32 -07:00
ukimsanov dc2d1697fe fix(scripts): make registry path containment filesystem-aware
Miguel's second P1 on #2975, and he is right that my first fix only closed half
of it. `resolve()` and `relative()` are string operations and do not follow
links. Registry items are copied in recursively with symlinks preserved, so a
PR shipping `escape -> /tmp/outside` and declaring `target: "escape/pwned.txt"`
passed the lexical check, `mkdirSync` followed the link, and `cpSync` wrote
outside the project.

Reproduced before fixing: the old predicate returned one allowed copy and the
file appeared outside the project. Both directions were exposed — a symlinked
`path` reads a runner file in just as readily.

Containment is now filesystem-aware. No existing component of a candidate may
be a symlink, and the candidate's real location — resolved through its deepest
existing ancestor — has to sit under the project's own real path. A symlink is
refused rather than followed, even one pointing back inside the project:
nothing in the registry needs one, and following it would mean trusting the
target not to change between the check and the copy.

The tests are real fixtures now instead of string cases, because a purely
lexical suite is exactly what stayed green through the bypass. Twelve of them,
covering a symlinked target directory, a symlinked source file, a deeper path
through a symlinked component, an inward-pointing symlink, plus the lexical and
absolute cases from before.
2026-08-04 03:06:32 -07:00
ukimsanov bd7ea5d5ce fix(scripts): contain registry manifest paths in the preview renderer
Miguel's P1 on #2975, and it is real. `catalog-previews.yml` triggers on
`pull_request` for anything under `registry/blocks/**` or
`registry/components/**`, so `registry-item.json` arrives from the pull request
and is untrusted. `mirrorRegistryTargets` joined `files[].path` and
`files[].target` under the temp project and called `cpSync` on the result, and
`join()` walks out of its first argument. A `path` of `../../../../etc/passwd`
reads an arbitrary runner file into the project — which the job then uploads as
an artifact — and a `target` of the same shape writes an arbitrary runner path.

Both sides are now resolved and rejected when `relative(projectDir, candidate)`
is absolute or starts with `..`. Traversal that lands back inside the project
still works, so `nested/../demo.html` is unaffected.

Containment lives in `scripts/registry-target-paths.mjs` rather than inline,
because the traversal cases have to be testable and importing
`generate-catalog-previews.ts` drags in the producer. `existsSync` is injected
so the decision cannot depend on whether the target happens to exist on the
runner. Eight tests, covering traversal on each field separately, absolute
paths on each field, the sibling directory that shares the project's prefix,
and traversal that returns inside.

Verified end to end on a real tree, not only in unit tests: a manifest asking
to read `../secret.txt` and write `../pwned.txt` produces neither file, while
the legitimate entry still copies.

I introduced the wrapper when I extracted this block for a complexity finding
earlier in the stack, and did not look at what it was joining.
2026-08-04 03:06:31 -07:00
ukimsanov 0dcd06ff62 refactor(scripts): extract mirrorRegistryTargets from prepareProjectDir
Inlining the registry-target mirroring pushed prepareProjectDir to cyclomatic
24, the one complexity finding fallow attributes to this branch — the other
eight are inherited and out of scope here.

Same behaviour, expressed as a filter chain in its own named function, so
prepareProjectDir returns to what it was and the new helper stays flat.
2026-08-04 03:06:31 -07:00
ukimsanov 79c4056a3f docs: make Catalog visual and reproducible 2026-08-04 03:06:31 -07:00
Ular Kimsanov 7e5a9b3c24 Merge pull request #2974 from heygen-com/docs/developers-reference
docs: rebuild developer and rendering reference
2026-08-04 02:53:18 -07:00
ukimsanov a99ad218f7 docs: fix the types page subtitle to match its softened claim
Rames' residual on #2974. I softened the body sentence last round and left the
frontmatter saying "All exported types from @hyperframes/sdk". Mintlify renders
description as both the page subtitle and the meta description, so the page went
on promising complete coverage in the two places a reader meets first — and the
one a search engine quotes.

Pre-existing on main, and he did not hold the stamp for it, but leaving it makes
the body fix cosmetic.
2026-08-04 02:45:21 -07:00
ukimsanov 7a91b93dd6 docs: correct four developer-reference claims the source contradicts
Miguel's three P2s and Rames' one finding on #2974, all verified in source
before changing anything.

**`render --json` is not a progress stream.** It prints exactly one
`batch-complete` document at the end (`batchRender.ts:408-418`), asserted as a
single `console.log` in `batchRender.test.ts`. Described as a final result now.

**The iframe drag example never captured the pointer.** `event.target` comes
from `iframe.contentDocument`, so `instanceof Element` against this window's
constructor is always false for a cross-realm node and `setPointerCapture()`
never ran — a pointer leaving the frame then loses `pointerup` and drag state
sticks. Structural feature detection instead, with the reason in a comment so it
does not get "simplified" back.

**The preview adapter example did not compile under strict TypeScript.** `comp`
was captured by the callback before definite assignment (TS2454). Optional, with
`comp?.dispatch(op)`.

**`ORIGIN_APPLY_PATCHES` was imported in a fence that did not use it and used in
fences that did not import it.** Imports do not cross fences, so both examples
were wrong in opposite directions. Rames found the pair in
`open-composition.mdx`; the same shape is in `composition.mdx:630`, which he did
not name. All three fences are self-contained now.

**And `types.mdx` claimed coverage it does not have.** It promised "every type
exported from `@hyperframes/sdk`" while omitting 13 of 42. Eleven are documented
on sibling pages, so the sentence now points at those instead of overclaiming.
The two with no home anywhere — `CompositionVariableType` and
`VariableUsageScan`, both re-exported from the barrel — have entries. The second
is worth having written down: `scanIncomplete` means `usedIds` is a lower bound,
so an id missing from it is unknown rather than unused.
2026-08-04 02:45:21 -07:00
ukimsanov bebaf679d9 docs: rebuild developer and rendering reference 2026-08-04 02:45:21 -07:00
Ular Kimsanov bb416a1413 Merge pull request #2979 from heygen-com/docs/rewrite-guides
docs: rewrite the guides and landing pages
2026-08-04 02:43:37 -07:00
Vance IngallsandClaude Opus 5 6c5403f7cd fix(producer): drop the ReDoS-prone literal-argv regex for a linear scan
CodeQL flagged js/redos on the all-literal argv matcher. It was right: the
`(?:"[^"]*"\s*,?\s*)+` form nests a quantifier inside a quantifier with an
optional separator, so whitespace can be matched two ways and a long
non-matching argv backtracks exponentially.

Replaced with a linear scan — find the spawn head, slice to the closing
bracket, and check the entries — plus small named helpers. Same behaviour: an
all-literal argv is treated as taking no input, an argv with a bare identifier
still has to be understood (verified by adding one and watching the guard fail).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 02:41:39 -07:00
Vance IngallsandClaude Opus 5 c81f68b592 test(producer): treat an all-literal probe argv as taking no input
CI runs the PR merged with main, so it saw a caller my branch predated:
`spawnSync("ffprobe", ["-version"])` in engine/src/utils/ffprobe.test.ts. That
is a capability check with no runtime path, so there is nothing to terminate,
but the unclassified guard flagged it as a caller it could not parse.

An argv whose entries are all string literals carries no input by
construction. Those are dropped before the check; an argv with a bare
identifier still has to be understood, verified by adding one and watching the
guard fail.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 02:29:19 -07:00
Vance IngallsandClaude Opus 5 255cf92915 fix(skills,producer): terminate ffprobe options in shipped skill scripts
The contract test only walked packages/*/src and only .ts, so it could not see
the shipped agent tools under skills/**, which are .mjs/.cjs. 19 call sites
there and in package tests were still missing `--` immediately before the
input while the suite reported the bug class closed — a dash-prefixed filename
is parsed as an option and fails the same way.

Sweeps packages/, skills/ and scripts/ now, including .mjs/.cjs and test
files (dither.test.mjs was one of the broken sites). Excludes only the
contract test itself, which documents the contract with example argvs
including a deliberately misordered one.

Two guards were fixed while widening: the terminator must never be inserted
after `-i`, which consumes the next token (a blind pass hit an ffmpeg input
and a base64 -i), and comment prose describing a spawn is not a spawn.

Also routes every audioPadTrim probe failure through one sanitizer at the
boundary. runFfprobeJson scrubbed its own stderr, but
defaultProbeVideoFrameInfo threw `no video stream in ${videoPath}` raw into
the public PadTrimAudioResult.error, and an injected probe can throw anything.
The redaction unit tests all passed with the caller wiring deleted; the new
public-path regressions fail without it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 02:23:35 -07:00
Vance IngallsandClaude Opus 5 e79ab3ab31 fix(core,producer): redact bare relative paths and the known input path
The generic scrub still missed a relative path with no `./` prefix:
`customer/acme-secret/video.mp4` and `assets/bgm.mp3` reached telemetry
completely unredacted, because the absolute rule needs a leading slash and
the `./` rule needs the dot. Adds a rule for them that still leaves `N/A`,
`24/1` and `48000/1001` alone.

Shape matching is a net with holes by construction, so audioPadTrim now
also redacts the exact path it put in the argv, plus its basename, before
the generic scrub runs. It built the argv, so it does not have to guess.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 02:23:35 -07:00
Vance IngallsandClaude Opus 5 d04569e37f fix(core): redact any path in telemetry, not an allowlist of roots
redactTelemetryString enumerated roots — /Users, /home, /opt, /tmp and a
handful more — so a project on /data, /Volumes, an NFS mount or any root a
user invented reached telemetry verbatim. Relative paths and bare basenames
were never redacted at all, and audioPadTrim routes raw ffprobe stderr
through this on every probe failure.

Now redacts by shape: absolute paths under any root (two or more segments,
so N/A and a 24/1 frame rate are not mistaken for one), relative paths
including dash-prefixed ones, and bare basenames with an asset extension.
URLs still keep their host and drop only the query.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 02:23:35 -07:00
Vance IngallsandClaude Opus 5 91a7cb1f5b test(producer): discover ffprobe callers and pin terminator position
The prior contract test scanned a hardcoded file list for a format flag
followed by a bare identifier, so it only matched the shape it was written
against. Mutation testing showed removing `--` from engine/utils/ffprobe.ts
and cli/commands/init.ts did not fail it.

Now walks packages/*/src and finds callers itself, checks that `--` is
immediately BEFORE the input rather than merely present, and compares
discovery against a manifest so a regex regression cannot silently stop
checking a known caller. A separate guard fails on any file that spawns a
probe binary but builds an argv this test cannot parse.

All 11 seams mutation-tested for both removal and misordering.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 02:23:34 -07:00
Vance IngallsandClaude Opus 5 d0dbf11ef5 fix(producer,studio-server): finish the ffprobe argv sweep, pin the contract
The previous commit claimed "all nine now terminate their options". That
was false: `producer/src/utils/audioRegression.ts:307` still passed the
path bare, and it is production source used by the regression harness.
A repo-wide audit found two more in studio-server
(`mediaValidation.ts`, `mediaMetadata.ts`) — their current callers pass
absolute paths, so they were defence-in-depth rather than live bugs, but
the exhaustiveness claim should be true rather than narrowed.

Eleven sites total, all terminated.

Adds a SOURCE-level contract test, which is the gap that let this
happen twice. #2740 fixed one of ten sites and shipped a regression
asserting the argv of that single site, so CI reported the class closed
while nine invocations still parsed `-intro.mp4` as an option. A
per-site unit test has the same blind spot for site twelve; scanning the
tree does not. The test also asserts its own coverage list has not
shrunk.

Verification: engine 1300, lint 511, core 1431, studio-server 398, cli
init/webmAlphaCheck/whisper 146, producer utils 51, audioPadTrim 18.
Removing any single terminator fails the contract test by name.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 02:23:34 -07:00
Vance IngallsandClaude Opus 5 47564ab94c fix(cli,core,lint,producer): terminate ffprobe options at every call site
#2740 added `--` to one of nine independent ffprobe invocations, so the
bug class it closed stayed open everywhere else while CI reported it
fixed — the regression test asserts the argv of that single site.

Reproduced on ffprobe 8.1.1: an asset named `-intro.mp4` probes fine
through extractMediaMetadata but fails with "Missing argument for option
'intro.mp4'" in audio pad/trim (mid-render), `hyperframes init`, whisper
duration probing and webmAlphaCheck. hevcPreviewLint catches and returns
false, so a dash-prefixed HEVC preview silently passes the lint rule.

Terminated at all of them:
  producer/services/render/audioPadTrim.ts (x2)
  producer/plan-parity-analysis.ts
  cli/commands/init.ts
  cli/utils/webmAlphaCheck.ts
  cli/whisper/transcribe.ts (x2)
  core/mediaGradeAnalyzer.ts
  lint/hevcPreviewLint.ts

audioPadTrim's runFfprobeJson is a near-verbatim clone of the engine's
runFfprobe and structurally cannot add the terminator itself, because
callers bake the input path into `args`. It now asserts the terminator
is present rather than letting a dash-prefixed path through, takes the
same stdio ["ignore", ...] as the engine helper, and redacts its stderr
— it was throwing raw ffprobe output, which echoes the input path, into
logs and telemetry.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 02:23:34 -07:00
ukimsanov f720eb75be docs: lead the Quickstart with a paste-to-agent block, cut the Examples link wall
Two things a non-technical reader hits that the pages did not help with.

**Quickstart made you do it by hand before you could ask.** Install through an
interactive picker, choose the right group, restart the agent, then type a
prompt — four manual terminal steps before anything happens. The copy-to-agent
affordance existed but sat at the bottom of the page, after the step it would
have replaced, and it copied only the prompt.

It leads now, with the whole thing in one visible block: install, make, open the
preview. It uses `hyperframes skills update` rather than the interactive
`skills add`, which is the command the README already says agents should run —
non-interactive, exactly the core set. The manual steps stay below for anyone
who wants to see them.

Plain code fence rather than the AgentAction component, deliberately: that
component renders a Copy button and never shows the request, so a reader copies
something they cannot read. Mintlify fences already carry a copy button and show
the text.

**Examples had four GitHub cards where one belongs.** Brief, Source, Revision,
Checks — two of them pointing into a gate-output report. That is showing
homework, not helping someone who came to see finished work. The render stays,
with one link into the folder.
2026-08-04 02:16:22 -07:00
ukimsanov b36f69a3c0 docs: drop the live embed from the introduction
Removed on request. The demo let a reader change a headline and an accent on a
ten-second composition, which undersold the thing the page is arguing for — the
Showcase wall above it does more for that in less space.

The component and its build apparatus go with it in #2977; nothing else on the
page referenced them.
2026-08-04 02:16:22 -07:00
ukimsanov 3d8db3f44e docs: drop the Source group to two columns
Rames' second item on #2976, fixed here because this is the line that owns it.
It was the only cols={3} in docs/, and all three cards carry body text — the
case docs/AGENTS.md names as hyphenating titles mid-word at this content width.

The rules file is #2976's deliverable, so it should not ship with the tree
beneath it holding the one counter-example.
2026-08-04 02:16:22 -07:00
ukimsanov ac9486980d docs: make the Reference Project links read as links
The four destinations were a single bordered four-column strip, which reads as
a tab bar — a control that switches the panel below it — when every cell is a
link to GitHub. Replaced with a CardGroup, which is what AGENTS.md prescribes
for choosing between destinations, at the two columns it also prescribes.
2026-08-04 02:16:22 -07:00
ukimsanov e60bef3f57 docs: rewrite the guides and landing pages
Rewrites the pages that survive the restructure so they lead with what a reader
can accomplish, and points them at the sections added in the previous commit.
Page set and navigation are unchanged here; only content moves.

Keeps the skill count in README. CLAUDE.md's catalog-maintenance rule requires
the count to live in README and CLAUDE.md, and both now agree with the 19
directories under skills/.
2026-08-04 02:16:22 -07:00