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.mdindex 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.tsindex 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.tsindex 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.tsxindex 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 "./sessionimport { 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdindex 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### Mediadiff --git a/reference/check.md b/reference/check.mdnew file mode 100644index 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).