Skip to content

The VS Code of video editing, built for agents.

TypeScript

Update `dapi context` command documentation and implementation

konstantin-paulusb9f3aafd96f8
diff --git a/README.md b/README.md
index a84ad74c..c77cc9a9 100644
--- a/README.md
+++ b/README.md
@@ -186,7 +186,7 @@ dapi node render -o hero.mp4 # encode the scene to disk
| Command | Purpose |
| --- | --- |
-| `dapi context` | Summary of the open project: scenes, playhead, fonts |
+| `dapi context` | Summary of app state |
| `dapi capture` | Render a node in isolation to a labelled contact sheet, or one PNG per position |
| `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 |
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index cd716304..ea09d626 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -572,7 +572,7 @@ program
.command("context")
.alias("ctx")
.description(
- `Print essential context about the open project. Call this first to orient: "this" or "here" may refer to the selection (spatial) or workarea (temporal).`,
+ `Print the current app context: which project the app has open (id, display name, folder), where its playhead sits, in seconds, and the registered font families.`,
)
.action(() => context());
diff --git a/apps/desktop/src/projects.ts b/apps/desktop/src/projects.ts
index 5b4b5197..964e4d68 100644
--- a/apps/desktop/src/projects.ts
+++ b/apps/desktop/src/projects.ts
@@ -437,7 +437,7 @@ All of them talk to the running app, except \`fonts\` and \`fetch\`.
| Script | Command | What it does |
| ------ | ------- | ------------ |
-| \`context\` | \`dapi context\` | What is open: scenes, active scene, playhead, work area, selection. |
+| \`context\` | \`dapi context\` | Which project the app has open, where its playhead sits, its fonts. |
| \`capture\` | \`dapi capture <id>\` | Render one node in isolation to labelled PNG contact sheets. |
| \`probe\` | \`dapi media probe <id\\|path>\` | Container and per-track metadata, without decoding. |
| \`transcribe\` | \`dapi media transcribe <id\\|path>\` | Timed speech transcript, word by word. |
diff --git a/apps/web/src/context/dapi/api.tsx b/apps/web/src/context/dapi/api.tsx
index c6b6e6af..706ea5a8 100644
--- a/apps/web/src/context/dapi/api.tsx
+++ b/apps/web/src/context/dapi/api.tsx
@@ -23,6 +23,7 @@ import { useFullscreenState } from "@/hooks/use-fullscreen-state";
import type { JSX, Accessor } from 'solid-js';
import type { User } from '@supabase/supabase-js';
import type { World } from 'koota';
+import type { ProjectContextValue } from '@/context/project';
type EditorApiProviderProps = {
children: JSX.Element;
@@ -56,7 +57,7 @@ export function EditorApiProvider(props: EditorApiProviderProps) {
createEffect(() => {
if (!window.desktop || project.id() !== world.get(Project)?.id) return;
- const router = createAppRouter({ world, getUser, requireAuth });
+ const router = createAppRouter({ world, project, getUser, requireAuth });
onCleanup(cliBridge.register(createRouterCaller(router)));
});
@@ -75,15 +76,16 @@ export function EditorApiProvider(props: EditorApiProviderProps) {
type AppRouterDeps = {
world: World;
+ project: ProjectContextValue;
getUser: () => User;
requireAuth: <I, O>(fn: (data: I) => Promise<O>) => (data: I) => Promise<O>;
};
-function createAppRouter({ world, getUser, requireAuth }: AppRouterDeps) {
+function createAppRouter({ world, project, getUser, requireAuth }: AppRouterDeps) {
return t.router({
ping: t.procedure.query(() => {}),
whoami: t.procedure.query(() => getUser()),
- context: q0(handleContextGet(world)),
+ context: q0(handleContextGet(world, project)),
capture: q(handleCapture(world)),
models: q(handleModels()),
logs: q(handleLogs()),
diff --git a/apps/web/src/context/dapi/capture.ts b/apps/web/src/context/dapi/capture.ts
index 6d40e7a5..e6cad4c2 100644
--- a/apps/web/src/context/dapi/capture.ts
+++ b/apps/web/src/context/dapi/capture.ts
@@ -27,9 +27,8 @@ function isNode(entity: Entity): boolean {
}
/**
- * The entity `id` names. Entities travel to the CLI as their koota values
- * (`dapi context` hands them out), so an id is one straight back — it only
- * has to still be alive and still be something worth drawing.
+ * 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.
*/
function resolveNode(world: World, id: number): Entity {
const entity = id as Entity;
diff --git a/apps/web/src/context/dapi/context.ts b/apps/web/src/context/dapi/context.ts
index dc8ce288..a7193241 100644
--- a/apps/web/src/context/dapi/context.ts
+++ b/apps/web/src/context/dapi/context.ts
@@ -2,36 +2,45 @@
* 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 { Or } from "koota";
-import {
- Active, AdjustmentLayer, Computed, Fonts, FrameRate, Geometry, Group,
- Project, Scene, Selected, Workarea,
-} from "@diffusionstudio/runtime";
+import { Computed, Fonts, FrameRate, getActiveEntity } from "@diffusionstudio/runtime";
import type { World } from "koota";
/**
- * What `dapi context` reports: enough of the open project for a caller with
- * no window onto it to say what to look at next. Entities travel as their
- * koota values, which is what `capture` takes back.
+ * The open project's identity, as the editor knows it. Structural on purpose:
+ * this is the project context's shape, without the handler having to depend on
+ * the Solid context it comes from.
*/
-export function handleContextGet(world: World) {
- return async () => {
- const scenes = [...world.query(Scene)];
- const active = world.queryFirst(Active) ?? null;
+type OpenProject = {
+ id: () => string;
+ dir: () => string;
+ name: () => string;
+};
- const fps = world.get(FrameRate)?.value ?? 30;
- const workarea = active?.get(Workarea);
+/**
+ * What `dapi context` reports: what the project's source cannot say. The JSX is
+ * the composition — its scenes, what is selected, which scene is active, the
+ * work area are all in the file, and a caller that wants them reads it. What is
+ * left over is which project the app has open, where its playhead sits, and
+ * which font families are actually registered in the world drawing it.
+ */
+export function handleContextGet(world: World, project: OpenProject) {
+ return async () => {
+ const frameRate = world.get(FrameRate)?.value || 30;
+ const active = getActiveEntity(world);
return {
- projectId: world.get(Project)?.id ?? '',
- entityCount: world.entities.length,
- scenes,
- activeSceneId: active,
- currentFrame: active?.get(Computed)?.localTime ?? 0,
- workarea: workarea ? { start: workarea.start / fps, end: workarea.end / fps } : null,
+ project: {
+ id: project.id(),
+ name: project.name(),
+ dir: project.dir(),
+ },
+ // Seconds, the unit the source places clips in; null when no scene is
+ // active, which is when there is no playhead to report.
+ currentTime: active ? (active.get(Computed)?.localTime ?? 0) / frameRate : null,
+ // What text can be drawn with right now: registered in the world, not
+ // merely named in the source. The editor default is always among them.
fontFamilies: [...new Set(["Inter", ...(world.get(Fonts)?.list ?? []).map((f) => f.family)])],
- selection: [...world.query(Selected, Or(Geometry, Group, AdjustmentLayer))],
};
}
}
diff --git a/apps/web/src/context/project.tsx b/apps/web/src/context/project.tsx
index f3077454..cf7bb396 100644
--- a/apps/web/src/context/project.tsx
+++ b/apps/web/src/context/project.tsx
@@ -15,7 +15,7 @@ import { getProject, renameProject } from '@/projects';
import type { ProjectInfo } from '@/projects';
-type ProjectContextValue = {
+export type ProjectContextValue = {
/** package.json `projectId`: what the project is, whatever it is called. */
id: Accessor<string>;
/** Absolute project folder. Moves when the project is renamed. */
diff --git a/reference/README.md b/reference/README.md
index 90cc1dee..d48ca86d 100644
--- a/reference/README.md
+++ b/reference/README.md
@@ -28,7 +28,7 @@ How the surface is divided:
### Document
-- [`dapi context`](./context.md): essential context about the open project
+- [`dapi context`](./context.md): which project the app has open, where its playhead sits, and its registered fonts
- [`dapi capture`](./capture.md): render a node in isolation to a labelled contact sheet, or one PNG per position
### Media
diff --git a/reference/context.md b/reference/context.md
index 75c40061..19efeaee 100644
--- a/reference/context.md
+++ b/reference/context.md
@@ -1,6 +1,6 @@
# `dapi context`
-Essential context about the open project. Call this first to understand the canvas situation. Alias: `ctx`.
+Summary of app state. Alias: `ctx`.
## Input
@@ -12,13 +12,22 @@ One JSON object:
```ts
{
- projectId: string; // package.json `projectId`, stable across renames
- entityCount: number;
- scenes: number[]; // ids of the top-level scenes
- activeSceneId: number | null; // null if no scene is active
- currentFrame: number; // current timeline playhead position, in frames
- workarea: { start: number; end: number } | null; // seconds, null if the active scene has none
- fontFamilies: string[];
- selection: number[]; // ids of the selected nodes, empty if nothing is selected
+ project: {
+ id: string; // package.json `projectId`, stable across renames
+ name: string; // package.json `displayName`, what the user calls it
+ dir: string; // absolute project folder — where the JSX being edited lives
+ };
+ currentTime: number | null; // playhead in the active scene, in seconds; null if no scene is active
+ fontFamilies: string[]; // families registered in the running world, valid as `fontFamily`
}
```
+
+`currentTime` is local to the active scene, the same origin a clip's `start`
+and `end` are placed against, and in the same unit.
+
+`project.dir` is the folder the app is editing, which is not necessarily the
+one a command was run from: check it before writing to source files.
+
+`fontFamilies` is what text can be drawn with right now — loaded into the world,
+not merely named in the source — and always includes the editor default. For
+every family installed on the machine, see [`dapi fonts`](./fonts.md).