Skip to content

The VS Code of video editing, built for agents.

TypeScript

Add `dapi check` command for structural analysis of nodes

konstantin-paulusaea37e16ce57
diff --git a/README.md b/README.md
index dcdd6ce4..7cddabc7 100644
--- a/README.md
+++ b/README.md
@@ -189,6 +189,7 @@ dapi node render -o hero.mp4 # encode the scene to disk
| `dapi open` | Launch the app and open (or create) a project folder, anywhere on disk |
| `dapi context` | Summary of app state |
| `dapi capture` | Render a node in isolation to a labelled contact sheet, or one PNG per position |
+| `dapi check` | Check a node's subtree for structural mistakes (black-frame gaps, never-visible nodes, failed sources) and report subtree stats |
| `dapi media …` | Inspect a file by id or path: `probe`, `grab`, `filmstrip`, `waveform`, `transcribe`, `listen` |
| `dapi models` / `dapi voices` / `dapi fonts` | Discover generation models, speech voices, local fonts |
| `dapi screenshot` / `dapi logs` | The app itself: capture the window, read recent console output |
diff --git a/apps/cli/src/cli-channels.ts b/apps/cli/src/cli-channels.ts
index f2c2d2c5..efe25124 100644
--- a/apps/cli/src/cli-channels.ts
+++ b/apps/cli/src/cli-channels.ts
@@ -83,6 +83,42 @@ export type MediaWaveformResult = {
export type MediaListenRequest = AssetRef & { prompt?: string; start?: number; end?: number; stripVideo?: boolean };
export type MediaListenResult = { result?: string; start?: number; end?: number };
+export type CheckRequest = { id: string };
+
+export type CheckIssueCode =
+ | "black-frames"
+ | "no-visuals"
+ | "never-visible"
+ | "zero-duration"
+ | "transparent"
+ | "source-error";
+
+/**
+ * One structural finding. `ranges` (where present) are seconds relative to
+ * the checked node's start — the same clock `capture --time` uses.
+ */
+export type CheckIssue = {
+ code: CheckIssueCode;
+ severity: "error" | "warning";
+ message: string;
+ /** Source stamp of the offending node; absent when the issue is about the subtree as a whole. */
+ node?: string;
+ ranges?: Array<{ start: number; end: number }>;
+};
+
+export type CheckResult = {
+ stats: {
+ /** Nodes in the subtree, the checked node included. */
+ nodes: number;
+ byKind: Record<string, number>;
+ /** Deepest nesting level below the checked node (0 = no children). */
+ depth: number;
+ /** Seconds the checked node plays (its workarea, when one is set). */
+ duration: number;
+ };
+ issues: CheckIssue[];
+};
+
export type GeneratedAsset = { id: string; name: string; type: string };
export type ModelsRequest = { type?: "image" | "video" | "audio" };
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 2f0a6906..8a5c3fa4 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -302,6 +302,17 @@ async function captureNode(id: string, opts: CaptureOptions): Promise<void> {
}
}
+async function checkNode(id: string): Promise<void> {
+ try {
+ const result = await editor.check.query({ id });
+ console.log(JSON.stringify(result));
+ // Linter convention: issues found is a different failure than "could not run".
+ if (result.issues.some((issue) => issue.severity === "error")) process.exitCode = 1;
+ } catch (e) {
+ handleSocketError(e);
+ }
+}
+
type OpenOptions = { background?: boolean };
/** `open -a` on a running app only activates it, so this is safe to always run. */
@@ -613,6 +624,14 @@ program
.option("-o, --output <dir>", "directory to write the PNGs into (default: a fresh dir in the system temp dir)")
.action((id: string, opts: CaptureOptions) => captureNode(id, opts));
+program
+ .command("check")
+ .description(
+ `Check a node's subtree for obvious structural mistakes, without rendering (local analysis, no credits): spans where no visual is scheduled (likely black frames), children that never become visible, zero-duration or fully transparent nodes, and assets that failed to load or generate — plus subtree stats (node count by kind, nesting depth, played duration). Prints one JSON object; times in issue ranges are seconds relative to the node's start, the same clock \`capture --time\` uses. Exits 1 when an error-severity issue is found. Structural only: a scheduled clip can still render black (dark footage, content smaller than the canvas), so confirm suspicious spans visually with \`capture\`.`,
+ )
+ .argument("<id>", 'node id to check or `file:id` when two files use the same id')
+ .action((id: string) => checkNode(id));
+
const media = program
.command("media")
.alias("m")
diff --git a/apps/web/src/context/dapi/api.tsx b/apps/web/src/context/dapi/api.tsx
index d0697101..71a70e6b 100644
--- a/apps/web/src/context/dapi/api.tsx
+++ b/apps/web/src/context/dapi/api.tsx
@@ -13,6 +13,7 @@ import { editorSession, requireEditorSession, setEditorSession } from "./session
import { handleContextGet } from "./context";
import { createAssetResolver, handleMediaProbe, handleMediaFrame, handleMediaTranscribe, handleMediaFilmstrip, handleMediaWaveform, handleMediaListen } from "./media";
import { handleCapture } from "./capture";
+import { handleCheck } from "./check";
import { handleLogs } from "./logs";
import { handleModels } from "./models";
import { handleVoices } from "./voices";
@@ -115,6 +116,7 @@ function createAppRouter({ navigate, getUser, requireAuth }: AppRouterDeps) {
whoami: t.procedure.query(() => getUser()),
context: q0(handleContextGet(editorSession)),
capture: q(handleCapture(requireEditorSession)),
+ check: q(handleCheck(requireEditorSession)),
models: q(handleModels()),
logs: q(handleLogs()),
screenshot: q0(handleWindowScreenshot()),
diff --git a/apps/web/src/context/dapi/capture.ts b/apps/web/src/context/dapi/capture.ts
index 024515fd..eca0624b 100644
--- a/apps/web/src/context/dapi/capture.ts
+++ b/apps/web/src/context/dapi/capture.ts
@@ -2,8 +2,6 @@
* 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, Source } from "@diffusionstudio/runtime";
-import { parseSource } from "@diffusionstudio/jsx";
import {
composeSheet,
createImageEncoder,
@@ -14,53 +12,11 @@ import {
} from "@diffusionstudio/encoder";
import { createCapture } from "@/engine/capture";
+import { resolveNode } from "./nodes";
import type { CaptureRequest, CaptureResult, TimecodedImage } from "@diffusionstudio/cli/channels";
-import type { Entity, World } from "koota";
import type { EditorSession } from "./session";
-// Scenes are nodes too, so capture accepts them alongside geometry, groups,
-// and adjustment layers.
-function isNode(entity: Entity): boolean {
- return entity.has(Geometry)
- || entity.has(Group)
- || entity.has(AdjustmentLayer)
- || entity.has(Scene);
-}
-
-/**
- * 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: 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`);
- }
-
- 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.
const SHEET_CAPTURE_HEIGHT = 1080;
diff --git a/apps/web/src/context/dapi/check.ts b/apps/web/src/context/dapi/check.ts
new file mode 100644
index 00000000..15a59505
--- /dev/null
+++ b/apps/web/src/context/dapi/check.ts
@@ -0,0 +1,211 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * 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, Audio, Cache, Caption, Computed, FrameRate, Geometry,
+ Group, Hidden, IsMask, Opacity, PaintType, Scene, Sequential, Source,
+ SourceError, Workarea, framesToSeconds, getIntrinsicPaint, isText,
+} from "@diffusionstudio/runtime";
+
+import { resolveNode } from "./nodes";
+
+import type { CheckIssue, CheckRequest, CheckResult } from "@diffusionstudio/cli/channels";
+import type { Entity } from "koota";
+import type { EditorSession } from "./session";
+
+// Absolute frames, [start, end).
+type Interval = { start: number; end: number };
+
+function kindOf(entity: Entity): string {
+ if (entity.has(IsMask)) return "mask";
+ if (entity.has(Scene)) return "scene";
+ if (entity.has(Group)) return entity.has(Sequential) ? "sequence" : "group";
+ if (entity.has(AdjustmentLayer)) return "adjustment-layer";
+ if (entity.has(Audio)) return "audio";
+ if (entity.has(Caption)) return "caption";
+ if (isText(entity)) return "text";
+ switch (getIntrinsicPaint(entity)) {
+ case PaintType.VIDEO: return "video";
+ case PaintType.IMAGE: return "image";
+ case PaintType.HTML: return "html";
+ default: return "shape";
+ }
+}
+
+// Whether the node itself puts pixels on screen. Containers don't (their
+// leaves do), adjustment layers and masks only shape what others draw, and a
+// scene's implicit background is exactly what a "black frame" looks like —
+// so none of those count as coverage.
+function drawsPixels(entity: Entity): boolean {
+ return entity.has(Geometry)
+ && !entity.has(Scene)
+ && !entity.has(Group)
+ && !entity.has(AdjustmentLayer)
+ && !entity.has(IsMask)
+ && !entity.has(Audio);
+}
+
+type WalkState = {
+ nodes: number;
+ byKind: Record<string, number>;
+ depth: number;
+ issues: CheckIssue[];
+ coverage: Interval[];
+ /** Frames→seconds on the checked node's own clock (capture --time's). */
+ rel: (frames: number) => number;
+};
+
+/**
+ * One pass over the subtree: count, classify, surface per-node issues, and
+ * collect the intervals where something actually draws. `window` is the
+ * intersection of every ancestor's visible span — null once an ancestor is
+ * hidden, transparent, or out of window, at which point nothing below can
+ * contribute pixels (but still counts toward stats and per-node issues).
+ */
+function visit(entity: Entity, window: Interval | null, depth: number, state: WalkState): void {
+ state.nodes += 1;
+ const kind = kindOf(entity);
+ state.byKind[kind] = (state.byKind[kind] ?? 0) + 1;
+ if (depth > state.depth) state.depth = depth;
+
+ const stamp = entity.get(Source)?.value;
+ const failure = entity.get(SourceError);
+ if (failure) {
+ state.issues.push({
+ code: "source-error",
+ severity: "error",
+ node: stamp,
+ message: `Source failed to ${failure.generated ? "generate" : "load"}: ${failure.value}`,
+ });
+ }
+
+ const computed = entity.get(Computed)!;
+ let visible = window;
+
+ if (computed.duration === 0) {
+ state.issues.push({
+ code: "zero-duration",
+ severity: "warning",
+ node: stamp,
+ message: "Zero duration — the node never renders",
+ });
+ visible = null;
+ }
+
+ if (entity.has(Hidden)) visible = null;
+
+ // A keyframed node may animate its opacity up from 0, so only a static 0
+ // is called out (and dropped from coverage).
+ const animated = (entity.get(Cache)?.keyframeTracks.length ?? 0) > 0;
+ if (entity.get(Opacity)?.value === 0 && !animated) {
+ state.issues.push({
+ code: "transparent",
+ severity: "warning",
+ node: stamp,
+ message: "Opacity is 0 — the node renders fully transparent",
+ });
+ visible = null;
+ }
+
+ if (visible !== null) {
+ const start = Math.max(visible.start, computed.start);
+ const end = Math.min(visible.end, computed.end);
+ if (start >= end) {
+ state.issues.push({
+ code: "never-visible",
+ severity: "warning",
+ node: stamp,
+ message: `Never visible — plays ${state.rel(computed.start)}s to ${state.rel(computed.end)}s, outside the window its ancestors play`,
+ });
+ visible = null;
+ } else {
+ visible = { start, end };
+ }
+ }
+
+ if (visible !== null && drawsPixels(entity)) state.coverage.push(visible);
+
+ const cache = entity.get(Cache);
+ for (const child of cache?.children ?? []) visit(child, visible, depth + 1, state);
+ // Masks are nodes worth counting and checking, but they add no pixels.
+ for (const mask of cache?.masks ?? []) visit(mask, null, depth + 1, state);
+}
+
+/** The spans of `window` no coverage interval touches. */
+function findGaps(window: Interval, coverage: Interval[]): Interval[] {
+ const sorted = [...coverage].sort((a, b) => a.start - b.start);
+ const gaps: Interval[] = [];
+ let cursor = window.start;
+ for (const { start, end } of sorted) {
+ if (start > cursor) gaps.push({ start: cursor, end: Math.min(start, window.end) });
+ cursor = Math.max(cursor, end);
+ if (cursor >= window.end) break;
+ }
+ if (cursor < window.end) gaps.push({ start: cursor, end: window.end });
+ // Sub-frame slivers are rounding, not black frames.
+ return gaps.filter((gap) => gap.end - gap.start >= 1);
+}
+
+export function handleCheck(session: () => EditorSession) {
+ return async ({ id }: CheckRequest): Promise<CheckResult> => {
+ const { world } = session();
+ const target = resolveNode(world, id);
+ const fps = world.get(FrameRate)?.value ?? 30;
+
+ const computed = target.get(Computed)!;
+
+ // The span the node actually plays: its bounds, narrowed by a workarea
+ // when one is set (workarea frames count from the node's start, the way
+ // the encoder and playback read them).
+ let window: Interval = { start: computed.start, end: computed.end };
+ const workarea = target.get(Workarea);
+ if (workarea) {
+ const start = Math.min(computed.end, computed.start + Math.max(0, workarea.start));
+ const end = Math.max(start, Math.min(computed.end, workarea.end ? computed.start + workarea.end : computed.end));
+ window = { start, end };
+ }
+
+ const rel = (frames: number) => Math.round(framesToSeconds(frames - computed.start, fps) * 1000) / 1000;
+ const state: WalkState = { nodes: 0, byKind: {}, depth: 0, issues: [], coverage: [], rel };
+ visit(target, window, 0, state);
+
+ const issues: CheckIssue[] = [];
+ if (window.end > window.start) {
+ if (state.coverage.length === 0) {
+ // A group of only audio clips is a legitimate thing to check; an
+ // empty visual subtree is not.
+ const audioOnly = (state.byKind["audio"] ?? 0) > 0;
+ issues.push({
+ code: "no-visuals",
+ severity: audioOnly ? "warning" : "error",
+ message: audioOnly
+ ? "No visual content in the subtree — fine for audio-only nodes, black frames otherwise"
+ : "No visual content anywhere in the subtree — every frame renders empty",
+ });
+ } else {
+ const gaps = findGaps(window, state.coverage);
+ if (gaps.length > 0) {
+ const total = gaps.reduce((sum, gap) => sum + (gap.end - gap.start), 0);
+ issues.push({
+ code: "black-frames",
+ severity: "error",
+ message: `No visuals scheduled in ${gaps.length} span${gaps.length === 1 ? "" : "s"} totaling ${rel(computed.start + total)}s — likely black frames`,
+ ranges: gaps.map((gap) => ({ start: rel(gap.start), end: rel(gap.end) })),
+ });
+ }
+ }
+ }
+ issues.push(...state.issues);
+
+ return {
+ stats: {
+ nodes: state.nodes,
+ byKind: state.byKind,
+ depth: state.depth,
+ duration: rel(computed.start + (window.end - window.start)),
+ },
+ issues,
+ };
+ };
+}
diff --git a/apps/web/src/context/dapi/nodes.ts b/apps/web/src/context/dapi/nodes.ts
new file mode 100644
index 00000000..690fb67d
--- /dev/null
+++ b/apps/web/src/context/dapi/nodes.ts
@@ -0,0 +1,50 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * 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, Source } from "@diffusionstudio/runtime";
+import { parseSource } from "@diffusionstudio/jsx";
+
+import type { Entity, World } from "koota";
+
+// Scenes are nodes too, so node-targeting endpoints accept them alongside
+// geometry, groups, and adjustment layers.
+export function isNode(entity: Entity): boolean {
+ return entity.has(Geometry)
+ || entity.has(Group)
+ || entity.has(AdjustmentLayer)
+ || entity.has(Scene);
+}
+
+/**
+ * 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.
+ */
+export 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`);
+ }
+
+ const nodes = matches.filter(isNode);
+ if (!nodes.length) {
+ throw new Error(`"${id}" is not a node; target 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) — target its scene instead`);
+ }
+ throw new Error(`"${id}" is ambiguous between ${stamps.map((stamp) => `"${stamp}"`).join(", ")} — use the file:id form`);
+ }
+ return nodes[0]!;
+}
diff --git a/reference/README.md b/reference/README.md
index fd3420e7..df15fcad 100644
--- a/reference/README.md
+++ b/reference/README.md
@@ -8,7 +8,7 @@ A project is a folder of that JSX, and **the source is the document**: the app c
## Groups
-**Top-level:** [`whoami`](./whoami.md), [`logs`](./logs.md), [`screenshot`](./screenshot.md), [`report`](./report.md), [`context`](./context.md) (alias `ctx`), [`capture`](./capture.md), [`models`](./models.md), [`voices`](./voices.md), [`fonts`](./fonts.md), [`fetch`](./fetch.md).
+**Top-level:** [`whoami`](./whoami.md), [`logs`](./logs.md), [`screenshot`](./screenshot.md), [`report`](./report.md), [`context`](./context.md) (alias `ctx`), [`capture`](./capture.md), [`check`](./check.md), [`models`](./models.md), [`voices`](./voices.md), [`fonts`](./fonts.md), [`fetch`](./fetch.md).
| Group | Alias | Scope |
| ----- | ----- | ----- |
@@ -33,6 +33,7 @@ How the surface is divided:
- [`dapi open`](./open.md): launch the app and open (or create) a project folder, anywhere on disk
- [`dapi context`](./context.md): which project the app has open, where its playhead sits, its registered fonts, and where its generations stand
- [`dapi capture`](./capture.md): render a node in isolation to a labelled contact sheet, or one PNG per position
+- [`dapi check`](./check.md): check a node's subtree for structural mistakes (black-frame gaps, never-visible nodes, failed sources) and report subtree stats
### Media
diff --git a/reference/check.md b/reference/check.md
new file mode 100644
index 00000000..f448deda
--- /dev/null
+++ b/reference/check.md
@@ -0,0 +1,50 @@
+# `dapi check <id>`
+
+Checks a node's subtree for obvious structural mistakes, without rendering: spans of the node's play window where **no visual is scheduled** (likely black frames), children that never become visible, zero-duration or fully transparent nodes, and assets that failed to load or generate. Alongside the issues it reports subtree stats — node count by kind, nesting depth, and played duration — so it doubles as a quick structural summary of a scene.
+
+The analysis is structural, from the resolved timeline alone, so it is instant and costs no credits — and it can only say *nothing is scheduled*, not *the frame is black*. A scheduled clip can still render black (dark footage, content smaller than the canvas, a transparent asset); confirm suspicious spans visually with [`capture`](./capture.md) at a time inside the range.
+
+## Input
+
+- `<id>`: node id to check (required) — the element's `id` attribute in the project's JSX, or `file:id` when two files use the same id. Same resolution rules as [`capture`](./capture.md).
+
+## What counts as visual coverage
+
+Video, image, HTML, shape, text, and caption nodes draw pixels; their scheduled spans cover the timeline. Groups and scenes are covered only where their descendants draw — a scene's background alone is exactly what a black frame looks like, so it never counts. Audio nodes, masks, and adjustment layers add no pixels; neither does anything hidden, fully transparent, or scheduled outside the window its ancestors play. When a scene has a workarea, coverage is judged against the workarea instead of the full span.
+
+## Output
+
+One JSON object:
+
+```ts
+{
+ stats: {
+ nodes: number; // nodes in the subtree, the checked node included
+ byKind: Record<string, number>; // "scene" | "sequence" | "group" | "video" | "image" | "html" | "shape" | "text" | "caption" | "audio" | "mask" | "adjustment-layer"
+ depth: number; // deepest nesting level below the checked node (0 = no children)
+ duration: number; // seconds the checked node plays (its workarea, when one is set)
+ };
+ issues: Array<{
+ code: "black-frames" | "no-visuals" | "never-visible" | "zero-duration" | "transparent" | "source-error";
+ severity: "error" | "warning";
+ message: string;
+ node?: string; // source stamp of the offending node; absent for subtree-wide issues
+ ranges?: Array<{ start: number; end: number }>; // seconds relative to the node's start — the clock `capture --time` uses
+ }>;
+}
+```
+
+## Issues
+
+| Code | Severity | Meaning |
+|---|---|---|
+| `black-frames` | error | Spans of a frame or more where nothing visual is scheduled; `ranges` lists them |
+| `no-visuals` | error* | Nothing in the subtree draws at all (*warning when the subtree holds audio nodes — an audio-only group is legitimate) |
+| `never-visible` | warning | A node scheduled entirely outside the window its ancestors play |
+| `zero-duration` | warning | A node that spans no frames |
+| `transparent` | warning | A node with static opacity 0 (nodes with keyframes are given the benefit of the doubt) |
+| `source-error` | error | An asset that failed to load or generate, with the failure message |
+
+## Exit code
+
+`0` when no error-severity issue is found (warnings alone stay `0`), `1` when one is — or when the check itself can't run (no project open, unknown id).