The VS Code of video editing, built for agents.
TypeScript
Update capture functionality and documentation for node IDs
konstantin-paulus8eafe46f1696
diff --git a/README.md b/README.mdindex a3fd0c1c..dcdd6ce4 100644--- a/README.md+++ b/README.md@@ -171,7 +171,7 @@ dapi media filmstrip clip.mp4 # grid of video framesdapi media waveform track.mp3 # audio waveform, silence flaggeddapi media transcribe interview.wav # timed, word-level transcriptdapi media listen interview.mp4 -p "what is said in the intro?" # ask a multimodal model-dapi capture 42 # see the canvas itself+dapi capture intro # see the canvas itself, by the node's id in the JSX```## CLI at a glancediff --git a/apps/cli/src/cli-channels.ts b/apps/cli/src/cli-channels.tsindex e6a7943e..5b6161bf 100644--- a/apps/cli/src/cli-channels.ts+++ b/apps/cli/src/cli-channels.ts@@ -58,7 +58,7 @@ export type TimecodedImage = { timecode: string; base64: string };export type MediaFrameResult = TimecodedImage[];export type CaptureRequest = {- id: number;+ id: string;frames?: number[];combine?: boolean;perSheet?: number;diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.tsindex ffe2c5ae..89aff7f5 100644--- a/apps/cli/src/index.ts+++ b/apps/cli/src/index.ts@@ -283,22 +283,9 @@ async function mediaWaveform(ref: string, opts: MediaPreviewOptions): Promise<vo}}-// Node ids are entity ids — integers. argv is always string, so the-// conversion belongs here, at the one boundary, with a strict check. Coercing-// app-side with Number() would silently accept "0x1f", "1e3", " 7 ", "" → 0.-function parseNodeId(id: string): number {- if (!/^\d+$/.test(id)) {- console.error(`Invalid node id: ${JSON.stringify(id)} (expected a non-negative integer)`);- process.exit(1);- }- return Number(id);-}-type CaptureOptions = { time?: string[]; output?: string; separate?: boolean; perSheet?: string };async function captureNode(id: string, opts: CaptureOptions): Promise<void> {- const eid = parseNodeId(id);-const times = (opts.time ?? ["0"]).map((t) => parseTimeArg(t, "--time"));const frames = times.map((t) => Math.round(t * TIME_FPS));const perSheet = parsePerSheet(opts.perSheet, opts.separate);@@ -307,7 +294,7 @@ async function captureNode(id: string, opts: CaptureOptions): Promise<void> {mkdirSync(dir, { recursive: true });try {const images = await editor.capture.query(- { id: eid, frames, combine: !opts.separate, perSheet },+ { id, frames, combine: !opts.separate, perSheet },GENERATE,);writeImages(images, dir);@@ -620,7 +607,7 @@ program.description(`Render a node in isolation to PNGs. By default the positions are merged into contact sheets: up to 12 per image, each cell labelled with its timecode (\`08s10f\`, zero segments dropped) and rendered as large as fits, so a few positions arrive as one high-resolution picture instead of a directory to open one by one (\`--separate\` writes a PNG per position, at 720p height, keeping the alpha channel). The node is drawn offscreen, tightly framed to its own bounds on a transparent background; siblings and overlapping scene content are not included, so capture a scene id to check composition ("what plays at time T": layout, overlaps, text, timing). For a video asset's own full-resolution pixels use \`media grab\`.`,)- .argument("<id>", "node id to capture")+ .argument("<id>", 'node id to capture or `file:id` when two files use the same id').option("-t, --time <time...>", `one or more positions to capture, relative to the node's start (0 = its first visible frame) — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: 0, the node's first visible frame)`).option("-S, --separate", "write one PNG per position instead of merging them into contact sheets").option("--per-sheet <n>", "positions per contact sheet, 1-12; fewer means a larger cell each (default: as many as fit)")diff --git a/apps/web/src/context/dapi/capture.ts b/apps/web/src/context/dapi/capture.tsindex d3fb2e4e..a5a623ef 100644--- a/apps/web/src/context/dapi/capture.ts+++ b/apps/web/src/context/dapi/capture.ts@@ -2,7 +2,8 @@* License, v. 2.0. If a copy of the MPL was not distributed with this* file, You can obtain one at http://mozilla.org/MPL/2.0/. */-import { AdjustmentLayer, Geometry, Group, Scene } from "@diffusionstudio/runtime";+import { AdjustmentLayer, Geometry, Group, Scene, Source } from "@diffusionstudio/runtime";+import { parseSource } from "@diffusionstudio/jsx";import {composeSheet,createImageEncoder,@@ -28,15 +29,36 @@ function isNode(entity: Entity): boolean {}/**- * The entity `id` names. An id is a koota entity value handed straight back,- * so it only has to still be alive and still be something worth drawing.+ * The entity `id` names. An id is a source id — the durable name an element+ * carries in the project's JSX — not a koota entity number, which is minted+ * anew on every recompile and so names nothing across calls. The bare id is+ * enough while it names one element; `file:id` settles a tie between files,+ * and a positional stamp (`index.tsx:12`) addresses elements that have no id.*/-function resolveNode(world: World, id: number): Entity {- const entity = id as Entity;- if (!Number.isInteger(id) || id < 0 || !world.has(entity) || !isNode(entity)) {- throw new Error(`No such node: ${id}`);+function resolveNode(world: World, id: string): Entity {+ const matches = world.query(Source).filter((entity) => {+ const stamp = entity.get(Source)!.value;+ if (stamp === id) return true;+ const parsed = parseSource(stamp);+ return parsed !== undefined && String(parsed.locator) === id;+ });+ if (!matches.length) {+ throw new Error(`No such node: "${id}" — node ids are the id attributes in the project's JSX`);}- return entity;++ const nodes = matches.filter(isNode);+ if (!nodes.length) {+ throw new Error(`"${id}" is not a renderable node; capture a scene, group, clip, or adjustment layer`);+ }+ if (nodes.length > 1) {+ const stamps = [...new Set(nodes.map((node) => node.get(Source)!.value))];+ if (stamps.length === 1) {+ // One element, many entities: a loop renders its body once per item.+ throw new Error(`"${id}" renders ${nodes.length} times (it sits in a loop) — capture its scene instead`);+ }+ throw new Error(`"${id}" is ambiguous between ${stamps.map((stamp) => `"${stamp}"`).join(", ")} — use the file:id form`);+ }+ return nodes[0]!;}// Ceiling on the height a sheet cell renders a node at.diff --git a/reference/capture.md b/reference/capture.mdindex 910c1240..6bbc5073 100644--- a/reference/capture.md+++ b/reference/capture.md@@ -4,7 +4,7 @@ Renders a node in isolation at one or more timeline positions and merges them in## Input-- `<id>`: node id to capture (required)+- `<id>`: node id to capture (required) — the element's `id` attribute in the project's JSX (e.g. `hero`), or its position in the file for elements that have none. When two files use the same id, the `file:id` form (`index.tsx:hero`) settles it. Entity numbers are not accepted; they change on every recompile.- `-t, --time <time...>`: one or more positions to capture, relative to the node's start (`0` = its first visible frame), each a `Time` value (optional; default `0`)- `-S, --separate`: write one PNG per position instead of merging them into contact sheets (optional). Each is rendered at 720p height on a transparent background and named after its timecode (e.g. `01s12f.png`). The way to keep the alpha channel.- `--per-sheet <n>`: positions per contact sheet, 1 to 12 (optional; default as many as fit). Fewer positions per sheet means a larger cell each. Sheets are balanced, so 13 positions become 7 + 6 rather than 12 + 1.@@ -39,4 +39,4 @@ A sheet's timecode is the span it covers; a single position's is its own. Sheets## Errors-Exits non-zero if the id is unknown, the node has no timeline clock of its own (capture its scene instead), the node is not visible at any requested position, `--per-sheet` is outside 1 to 12, or a PNG can't be written.+Exits non-zero if the id is unknown, the id is ambiguous (two files use it — pass `file:id`), the id names an element inside a loop (capture its scene instead), the node has no timeline clock of its own (capture its scene instead), the node is not visible at any requested position, `--per-sheet` is outside 1 to 12, or a PNG can't be written.diff --git a/reference/report.md b/reference/report.mdindex c3c73632..bcbb4703 100644--- a/reference/report.md+++ b/reference/report.md@@ -15,7 +15,7 @@ Does not require the app to be running. If the app is down or unreachable, the r## Options- `-b, --body <text>`: what happened, in markdown: what you expected, what you got, and anything the diagnostics won't show.-- `-c, --command <cmd...>`: the `dapi` command(s) that reproduce it, in order. Repeatable (`-c "dapi context" -c "dapi capture 5"`); rendered as a shell block under `## Repro`.+- `-c, --command <cmd...>`: the `dapi` command(s) that reproduce it, in order. Repeatable (`-c "dapi context" -c "dapi capture intro"`); rendered as a shell block under `## Repro`.- `--logs <n>`: trailing app log entries to attach (default: 50). `--logs 0` omits the section, and then the app is not contacted at all.## Output@@ -38,7 +38,7 @@ The title is the issue title; the body is assembled from the options and the dia## Repro```sh-dapi capture 42+dapi capture intro```## Environment