Commit Graph
3660 Commits
Author SHA1 Message Date
Miguel Angel Simon Sierra 9752d1dc68 feat(studio): offer ACP harnesses in the picker
Codex and Claude Code both publish ACP adapters, so both appear as their
own entries alongside their native CLIs — same accounts, same models,
same machine, reached over a published contract instead of by reading
stdout. A registered custom agent can declare the transport too, which is
what lets anything in the ACP registry be added without a release here.

Availability cannot be a PATH lookup for an adapter that npx fetches on
demand: finding npx proves nothing and not finding the adapter proves
nothing either. A declared ACP agent is offered, and one that cannot run
says why when it is used, which beats an option silently missing.

That also broke naming a custom agent: every adapter launches through
npx, so sniffing the command for a known harness matched the first ACP
preset and called every npx-run agent Codex. Only presets whose command
IS the harness are sniffed for now.

Verified in a running Studio against @agentclientprotocol/codex-acp: both
entries listed, the model chip filled with the account's real models and
their protocol-reported levels priced cheapest-first, and a run picked
from the picker edited the composition.
2026-08-05 22:56:12 -07:00
Miguel Angel Simon Sierra c932aacf8a feat(studio): read an ACP agent's models over the protocol
An ACP agent reports its models when a session opens, which is the only
answer that reflects the user's own account — the same reason Studio asks
Codex over its app-server rather than filtering a catalog. The existing
rules are unchanged from there: models.dev supplies prices, the harness
owns what each model accepts, and cheapest still wins by default.

ACP has no separate effort knob. The Codex adapter writes the level into
the id (gpt-5.6-sol[high]), so those are folded into one model that
offers levels instead of six models that differ by one word, and the
chosen level is written back the same way via session/set_model. An agent
with plain ids simply has no levels, which is already how Claude Code is
treated.

Asking now needs the whole harness rather than its kind: two ACP adapters
are both "custom" and are two different answers, so the model list, the
default model and the default effort all take how the agent is started.

Verified against @agentclientprotocol/codex-acp: four models with their
real level lists, the account's own default marked, set_model accepted.
2026-08-05 22:46:40 -07:00
Miguel Angel Simon Sierra 18b3caa9dc feat(studio): answer the agent's question from the run tray
A run stopped on a question now shows what it is being asked and the
agent's own options, one button each; clicking one sends that option's id
and the run carries on. The element says so too, in amber and still,
where every working state moves: a run that has stopped must not look
like one getting on with it. Being waited on leads the tray's headline
and outranks working in the canvas badge, because it is the only state
the reader can do something about.

Three files had to come apart first, all of them over the editor's
600-line cap and so uncommittable as they stood:

- the canvas connector moves out of InlineAgentComposer into its own
  file, and the composer's geometry joins the layout module that already
  owned the rest of it (813 -> 551)
- the queue's mutations move out of useAskAgentModal into useAgentQueue,
  which is where answering belongs (653 -> 598)
- useDomEditSession listed all 34 agent fields twice, once to
  destructure and once to return; it spreads them instead (604 -> 540)

Polling also treated a parked run as idle, so an answer took up to eight
seconds to look like it had landed.
2026-08-05 22:39:55 -07:00
Miguel Angel Simon Sierra 233338ddd4 feat(studio): let a run stop and ask before it acts
Over ACP an agent can ask permission before it writes or runs something.
A run that asks parks as `awaiting-permission` carrying the agent's own
question and its own options, keeps holding its element, and resumes the
moment the answer is forwarded. Studio only ever forwards an option the
agent itself offered; anything else is refused with a 409.

The wait is bounded, because a run that has stopped to ask is holding an
element while it does. Running out never means yes: the agent's own
refusal is used when it offered one, and the run fails naming the tool
when it did not.

Real agents ask about a tool call by id and put the title in the update
that announced it, so titles are remembered and the question is shown in
the agent's words rather than as "exec-282be8b3".

Both transports now share one cleanup path instead of two copies.

Verified against @agentclientprotocol/codex-acp in read-only mode: the
agent asked, the question parsed with its refusal option, answering
"Allow Once" ended the turn and the file was edited.
2026-08-05 22:23:26 -07:00
Miguel Angel Simon Sierra afb182059b feat(studio): run an edit as an ACP session
A preset that declares `transport: "acp"` is driven by the protocol
instead of by parsing stdout: the session id comes from `session/new`,
the activity line and the answer come from `session/update`, and the turn
ends with a stop reason rather than an exit code that has to be guessed
at. Everything downstream is unchanged — the same overlay contract, the
same activity shape, the same run log — because it is the same product
behaviour over a different wire. The native path is untouched.

An agent that fails answers with something as terse as "Internal error"
and explains itself on stderr, so stderr is kept and the last line of it
is what the run reports.

Verified against @agentclientprotocol/codex-acp: a real edit ran with
live activity, changed the file, and logged a well-formed line.
2026-08-05 21:48:48 -07:00
Miguel Angel Simon Sierra 94e78e806e feat(studio): talk to coding agents over the Agent Client Protocol
Studio's existing transport spawns a CLI and reads whatever it prints, so
every harness needs its own parser and an agent that wants to ask a
question has nobody to ask. ACP is the published standard for this
boundary: JSON-RPC over stdio, capabilities negotiated up front.

This is the connection half only: open a stream, complete the handshake,
clean the process up. A dead agent reports its exit code rather than the
transport's bare "connection closed", and a silent one fails on a
deadline naming the command instead of hanging.

Verified against @agentclientprotocol/codex-acp: the handshake returns
protocolVersion 1, loadSession, and three auth methods.
2026-08-05 21:36:24 -07:00
Miguel Angel Simon Sierra e8dbbebc1c fix(studio): use Codex's own app icon
The OpenAI wordmark stood in for Codex; this is the icon Codex actually ships,
white plate and gradient mark, so it reads the same in the picker as it does in
the dock.
2026-08-04 16:49:11 -07:00
Miguel Angel Simon Sierra 00ba1382c4 fix(studio): lay the composer and the answer out together
Both belong to the same element, so placed independently they landed on top of
each other. One pass now places both: the composer takes the side it prefers,
the answer takes the other, and where only one side has room the answer stacks
beyond the composer rather than across it. The bubble's tail keeps tracking the
element either way.
2026-08-04 16:38:49 -07:00
Miguel Angel Simon Sierra 688f886156 feat(studio): speak the agent's answer next to the element it is about
Not every instruction is an edit. "Why is this off-centre?" comes back as an
answer, and an answer that only lands in a run list is an answer nobody reads.
A finished run with something to say now surfaces as a bubble on the canvas,
its tail tracking the element's centre so a bubble pushed along by the canvas
edge still points back at what it answered. It can be expanded, dismissed for
good, or carried straight into a follow-up.

Also makes the element name in a run row read as the control it is — a target
glyph, a resting fill and a pointer — instead of looking like the caption
beside it.
2026-08-04 16:33:22 -07:00
Miguel Angel Simon Sierra 051886705f fix(studio): call it Hermes Agent, the name Nous Research ships it under 2026-08-04 16:26:15 -07:00
Miguel Angel Simon Sierra 04c4f6d380 feat(studio): choose reasoning effort beside the model, lowest by default
Effort levels come from the same catalog the models do — a model advertises
what it accepts, and Studio offers exactly that. Anthropic reasons on a token
budget rather than a level, so a Claude Code run carries no effort at all
instead of a knob that does nothing.

The chip sits to the right of the model, because it is the same decision: how
much thinking to buy. A run takes the lowest level the model offers unless the
user picks otherwise, the choice is remembered per harness, and each run in the
tray shows the effort it actually used.

Also drops the OS tooltips from the harness and model chips — they covered the
element they described — and portals the composer and ask handle out of the
canvas overlay. That overlay is a z-10 stacking context whose sibling motion
path sits at z-40, so nothing inside it could ever come out on top, however
high its own z-index was; the keyframe diamonds kept drawing through the pill.
2026-08-04 16:17:37 -07:00
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