Skip to content

The VS Code of video editing, built for agents.

TypeScript

Update package descriptions and remove unused files

konstantin-paulus2bcad215a97b
diff --git a/packages/jsx/README.md b/packages/jsx/README.md
index 59639593..b3fd4c4a 100644
--- a/packages/jsx/README.md
+++ b/packages/jsx/README.md
@@ -1,8 +1,9 @@
# @diffusionstudio/jsx
The editor supplies the runtime when a project is mounted, so this package is
-needed for **types and tooling** — IntelliSense, `tsc --noEmit`, and testing
-components outside the editor.
+needed for **types and tooling** — IntelliSense and `tsc --noEmit`. It carries
+no renderer: `useTicker` and `useFile` are declarations that throw outside a
+mount, and elements only become a composition once the editor renders them.
```sh
npm install --save-dev @diffusionstudio/jsx solid-js
diff --git a/packages/jsx/package.json b/packages/jsx/package.json
index 907a0f1f..026b6fdf 100644
--- a/packages/jsx/package.json
+++ b/packages/jsx/package.json
@@ -1,7 +1,7 @@
{
"name": "@diffusionstudio/jsx",
"version": "0.1.0",
- "description": "JSX runtime, types, and declarative generated assets (`generate.*`) for authoring Diffusion Studio compositions — mounted into the editor via `dapi mount`.",
+ "description": "Types and authoring API for Diffusion Studio compositions: the JSX element vocabulary, declarative generated assets (`generate.*`), and the hooks the editor implements when a project is mounted via `dapi mount`.",
"license": "MPL-2.0",
"type": "module",
"sideEffects": false,
diff --git a/packages/jsx/src/hooks.ts b/packages/jsx/src/hooks.ts
new file mode 100644
index 00000000..3788c987
--- /dev/null
+++ b/packages/jsx/src/hooks.ts
@@ -0,0 +1,66 @@
+/* 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/. */
+
+/**
+ * The authoring hooks, as signatures. Both read the host a project is mounted
+ * into, which only exists inside the editor: when a project is mounted, the
+ * renderer substitutes its own "@diffusionstudio/jsx" module (see
+ * @diffusionstudio/reconciler) and these implementations are replaced by ones
+ * bound to the live host. This package carries the declarations so project
+ * sources type-check and get IntelliSense; calling them outside a mount
+ * throws rather than silently returning a dead value.
+ */
+
+import type { Accessor, ResourceReturn } from "solid-js";
+import type { AssetInput } from "./generate";
+
+export type Ticker = {
+ time: Accessor<number>;
+ frame: Accessor<number>;
+ delta: Accessor<number>;
+ playing: Accessor<boolean>;
+};
+
+function hostOnly(name: string): never {
+ throw new Error(
+ `${name} is implemented by the editor's renderer and only works inside a mounted project.`,
+ );
+}
+
+/**
+ * Subscribes to the project's timeline: the playhead of the scene the mount's
+ * root lives in (or is), pushed by the host once per playback tick. Each
+ * accessor only propagates when its value changes, so a paused scene re-runs
+ * nothing and `frame()` consumers update at most once per frame. Values move
+ * while the reactive graph is alive: a mount stays live, and export, capture,
+ * and reload each re-execute the module and drive the ticker themselves.
+ */
+export function useTicker(): Ticker {
+ return hostOnly("useTicker");
+}
+
+/**
+ * Resolves a source (path, asset id, URL, or a `generate.*` ref) to its `File`,
+ * for reading raw bytes inside effects. Returns Solid's `createResource` tuple
+ * unchanged: the resource accessor reads `undefined` until it resolves, then
+ * the `File` (with `.loading` / `.error`), plus `mutate` / `refetch`.
+ * Resolution is async (fetch a URL, read a path or library asset, await a
+ * `generate.*` ref) and, like `src`, needs the host — a sandboxed module can't
+ * fetch a path or asset id itself.
+ *
+ * ```tsx
+ * const [canvas, setCanvas] = createSignal<HTMLCanvasElement>();
+ * const [file] = useFile("/assets/logo.png");
+ * createEffect(async () => {
+ * const el = canvas();
+ * const f = file();
+ * if (!el || !f) return;
+ * el.getContext("2d")!.drawImage(await createImageBitmap(f), 0, 0);
+ * });
+ * // <surface ref={setCanvas} width={640} height={360} />
+ * ```
+ */
+export function useFile(_src: AssetInput): ResourceReturn<File> {
+ return hostOnly("useFile");
+}
diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.ts
index 5da0c8d6..3aefc22e 100644
--- a/packages/jsx/src/index.ts
+++ b/packages/jsx/src/index.ts
@@ -2,7 +2,14 @@
* 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/. */
-// Public authoring API (used by project modules).
+/**
+ * The authoring surface: the types project sources are written against, the
+ * pure helpers they may call, and the hooks the editor implements. The
+ * renderer that turns this vocabulary into a composition is not here — the
+ * editor supplies it when a project is mounted (see
+ * @diffusionstudio/reconciler), so nothing in this package touches a host.
+ */
+
export { generate, AssetRef, isAssetRef, getAssetSpec } from "./generate";
export type {
AspectRatio,
@@ -13,29 +20,9 @@ export type {
GenerateVideoOptions,
GenerateVoiceOptions,
} from "./generate";
-export { PATCH_PROP_KEYS } from "./types";
export { parseTime, TIME_FPS } from "./time";
-export {
- Audio,
- Captions,
- ColorStop,
- Group,
- Html,
- HtmlPaint,
- Image,
- LinearGradientPaint,
- RadialGradientPaint,
- Rect,
- Sequence,
- ShaderPaint,
- SolidPaint,
- Surface,
- SurfacePaint,
- Text,
- Video,
-} from "./elements";
-export { useTicker, useFile } from "./renderer";
-export type { Ticker } from "./renderer";
+export { useTicker, useFile } from "./hooks";
+export type { Ticker } from "./hooks";
export type {
Animatable,
AnimationSpec,
@@ -66,23 +53,3 @@ export type {
TransitionType,
VideoProps,
} from "./types";
-
-// Renderer runtime — compiled project modules import these (babel-preset-solid
-// universal mode, moduleName "@diffusionstudio/jsx").
-export {
- render,
- effect,
- memo,
- createComponent,
- createElement,
- createTextNode,
- insertNode,
- insert,
- spread,
- setProp,
- mergeProps,
- use,
- renderProject,
-} from "./renderer";
-
-export type { ProjectDocument, ProjectTick } from "./document";
diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.ts
index 918f8ae3..9e3f679d 100644
--- a/packages/jsx/src/types.ts
+++ b/packages/jsx/src/types.ts
@@ -237,48 +237,6 @@ export type PatchProps = {
seed?: number;
};
-/** Every PatchProps key, at runtime — the patch-command allowlist. */
-export const PATCH_PROP_KEYS = Object.keys({
- key: true,
- scene: true,
- name: true,
- x: true,
- y: true,
- offsetX: true,
- offsetY: true,
- width: true,
- height: true,
- rotation: true,
- opacity: true,
- cornerRadius: true,
- start: true,
- end: true,
- sourceIn: true,
- sourceOut: true,
- syncTo: true,
- transition: true,
- animations: true,
- fill: true,
- src: true,
- objectFit: true,
- wgsl: true,
- uniforms: true,
- volume: true,
- muted: true,
- fontFamily: true,
- fontSize: true,
- fontWeight: true,
- fontStyle: true,
- color: true,
- textAlign: true,
- textBaseline: true,
- offset: true,
- preset: true,
- colors: true,
- verticalAlign: true,
- seed: true,
-} satisfies Record<keyof PatchProps, true>) as ReadonlyArray<keyof PatchProps>;
-
type TimingProps = Pick<PatchProps, "start" | "end" | "sourceIn" | "sourceOut">;
type CommonProps = TimingProps &
diff --git a/packages/reconciler/package.json b/packages/reconciler/package.json
index 51a739da..dcc4a9c7 100644
--- a/packages/reconciler/package.json
+++ b/packages/reconciler/package.json
@@ -1,7 +1,7 @@
{
"name": "@diffusionstudio/reconciler",
"version": "0.1.0",
- "description": "Renders compiled project JSX (babel-preset-solid universal, via @diffusionstudio/jsx) into a @diffusionstudio/runtime world: evaluates the bundle and reconciles its element tree onto runtime entities.",
+ "description": "The JSX runtime and host behind @diffusionstudio/jsx: evaluates a compiled project bundle (babel-preset-solid universal), binds it to Solid's universal renderer, and reconciles its element tree onto @diffusionstudio/runtime entities.",
"license": "MPL-2.0",
"type": "module",
"sideEffects": false,
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index 9bd489df..2b3619d5 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -31,7 +31,7 @@ import {
} from '@diffusionstudio/runtime';
import type { Entity, World } from 'koota';
-import type { ProjectDocument } from '@diffusionstudio/jsx';
+import type { ProjectDocument } from './host';
/**
* A host node: a handle around an element's entity. Koota entities are plain
diff --git a/packages/jsx/src/elements.ts b/packages/reconciler/src/elements.ts
similarity index 98%
rename from packages/jsx/src/elements.ts
rename to packages/reconciler/src/elements.ts
index fa9792a7..22a38f08 100644
--- a/packages/jsx/src/elements.ts
+++ b/packages/reconciler/src/elements.ts
@@ -34,7 +34,7 @@ import type {
SurfaceProps,
TextProps,
VideoProps,
-} from "./types";
+} from "@diffusionstudio/jsx";
/**
* A component wrapping one host element: creates the node, routes `ref`
diff --git a/packages/reconciler/src/evaluate.ts b/packages/reconciler/src/evaluate.ts
index 0b1193b2..bf4987b9 100644
--- a/packages/reconciler/src/evaluate.ts
+++ b/packages/reconciler/src/evaluate.ts
@@ -4,15 +4,17 @@
import * as solid from 'solid-js';
import * as solidStore from 'solid-js/store';
-import * as jsx from '@diffusionstudio/jsx';
+
+import { JSX_RUNTIME } from './runtime';
// What the desktop compile step marks external is what is handed out here,
// so a project shares the app's solid-js instance (one reactive graph) and
-// its JSX runtime.
+// its JSX runtime — the authoring package's exports bound to this host, not
+// the host-less copy in the project's node_modules.
const MODULES: Record<string, unknown> = {
'solid-js': solid,
'solid-js/store': solidStore,
- '@diffusionstudio/jsx': jsx,
+ '@diffusionstudio/jsx': JSX_RUNTIME,
};
/** Evaluates a compiled CommonJS bundle and returns its default export. */
diff --git a/packages/jsx/src/document.ts b/packages/reconciler/src/host.ts
similarity index 96%
rename from packages/jsx/src/document.ts
rename to packages/reconciler/src/host.ts
index a0e7b924..1d225b9e 100644
--- a/packages/jsx/src/document.ts
+++ b/packages/reconciler/src/host.ts
@@ -10,7 +10,7 @@
* opaque to the renderer.
*/
-import type { AssetInput } from "./generate";
+import type { AssetInput } from "@diffusionstudio/jsx";
/**
* One reading of the host's timeline clock, local to the mounted project:
diff --git a/packages/reconciler/src/index.ts b/packages/reconciler/src/index.ts
index 7c7ef61e..21dd0062 100644
--- a/packages/reconciler/src/index.ts
+++ b/packages/reconciler/src/index.ts
@@ -5,3 +5,7 @@
export { RuntimeDocument, type SceneNode } from './document';
export { evaluate } from './evaluate';
export { mount, type Mount } from './mount';
+export { PATCH_PROP_KEYS } from './patch';
+export { renderProject } from './renderer';
+export { JSX_RUNTIME } from './runtime';
+export type { ProjectDocument, ProjectTick } from './host';
diff --git a/packages/reconciler/src/mount.ts b/packages/reconciler/src/mount.ts
index 12a00504..87898733 100644
--- a/packages/reconciler/src/mount.ts
+++ b/packages/reconciler/src/mount.ts
@@ -2,10 +2,9 @@
* 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 { renderProject } from '@diffusionstudio/jsx';
-
import { RuntimeDocument } from './document';
import { evaluate } from './evaluate';
+import { renderProject } from './renderer';
import type { World } from 'koota';
diff --git a/packages/reconciler/src/patch.ts b/packages/reconciler/src/patch.ts
new file mode 100644
index 00000000..39e589b2
--- /dev/null
+++ b/packages/reconciler/src/patch.ts
@@ -0,0 +1,52 @@
+/* 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 type { PatchProps } from '@diffusionstudio/jsx';
+
+/**
+ * Every `PatchProps` key, at runtime — the patch-command allowlist. Host-side:
+ * a project never enumerates its own props, but anything applying a patch has
+ * to reject unknown keys. The `satisfies` guard keeps the list exhaustive as
+ * `PatchProps` grows.
+ */
+export const PATCH_PROP_KEYS = Object.keys({
+ key: true,
+ scene: true,
+ name: true,
+ x: true,
+ y: true,
+ offsetX: true,
+ offsetY: true,
+ width: true,
+ height: true,
+ rotation: true,
+ opacity: true,
+ cornerRadius: true,
+ start: true,
+ end: true,
+ sourceIn: true,
+ sourceOut: true,
+ syncTo: true,
+ transition: true,
+ animations: true,
+ fill: true,
+ src: true,
+ objectFit: true,
+ wgsl: true,
+ uniforms: true,
+ volume: true,
+ muted: true,
+ fontFamily: true,
+ fontSize: true,
+ fontWeight: true,
+ fontStyle: true,
+ color: true,
+ textAlign: true,
+ textBaseline: true,
+ offset: true,
+ preset: true,
+ colors: true,
+ verticalAlign: true,
+ seed: true,
+} satisfies Record<keyof PatchProps, true>) as ReadonlyArray<keyof PatchProps>;
diff --git a/packages/jsx/src/renderer.ts b/packages/reconciler/src/renderer.ts
similarity index 71%
rename from packages/jsx/src/renderer.ts
rename to packages/reconciler/src/renderer.ts
index 9ba4b9f6..f0e9ba94 100644
--- a/packages/jsx/src/renderer.ts
+++ b/packages/reconciler/src/renderer.ts
@@ -5,9 +5,9 @@
import { createContext, createMemo, createResource, useContext } from "solid-js";
import { createRenderer } from "solid-js/universal";
-import type { Accessor, JSX, ResourceReturn } from "solid-js";
-import type { AssetInput } from "./generate";
-import type { ProjectDocument } from "./document";
+import type { JSX, ResourceReturn } from "solid-js";
+import type { AssetInput, Ticker } from "@diffusionstudio/jsx";
+import type { ProjectDocument } from "./host";
// Compiled project modules call the static runtime exports below
// (babel-preset-solid in `universal` mode with a fixed moduleName), so the
@@ -86,20 +86,11 @@ export function use(fn: (target: unknown, arg?: unknown) => void, node: unknown,
return renderer.use(fn, node, arg);
}
-export type Ticker = {
- time: Accessor<number>;
- frame: Accessor<number>;
- delta: Accessor<number>;
- playing: Accessor<boolean>;
-};
-
/**
- * Subscribes to the project's timeline: the playhead of the scene the mount's
- * root lives in (or is), pushed by the host once per playback tick. Each
- * accessor only propagates when its value changes, so a paused scene re-runs
- * nothing and `frame()` consumers update at most once per frame. Values move
- * while the reactive graph is alive: a mount stays live, and export, capture,
- * and reload each re-execute the module and drive the ticker themselves.
+ * The live `useTicker` — substituted for the throwing declaration in
+ * @diffusionstudio/jsx (see "./runtime"), so a mounted project's import
+ * resolves to this one. Each accessor only propagates when its value changes,
+ * so a paused scene re-runs nothing.
*/
export function useTicker(): Ticker {
const document = doc();
@@ -117,25 +108,10 @@ export function useTicker(): Ticker {
}
/**
- * Resolves a source (path, asset id, URL, or a `generate.*` ref) to its `File`,
- * for reading raw bytes inside effects. Returns Solid's `createResource` tuple
- * unchanged: the resource accessor reads `undefined` until it resolves, then
- * the `File` (with `.loading` / `.error`), plus `mutate` / `refetch`.
- * Resolution is async (fetch a URL, read a path or library asset, await a
- * `generate.*` ref) and, like `src`, needs the host — a sandboxed module can't
- * fetch a path or asset id itself.
- *
- * ```tsx
- * const [canvas, setCanvas] = createSignal<HTMLCanvasElement>();
- * const [file] = useFile("/assets/logo.png");
- * createEffect(async () => {
- * const el = canvas();
- * const f = file();
- * if (!el || !f) return;
- * el.getContext("2d")!.drawImage(await createImageBitmap(f), 0, 0);
- * });
- * // <surface ref={setCanvas} width={640} height={360} />
- * ```
+ * The live `useFile` — substituted for the throwing declaration in
+ * @diffusionstudio/jsx (see "./runtime"). Resolution is async (fetch a URL,
+ * read a path or library asset, await a `generate.*` ref) and needs the host,
+ * so it is a `createResource` over the document's `loadFile`.
*/
export function useFile(src: AssetInput): ResourceReturn<File> {
const document = doc();
diff --git a/packages/reconciler/src/runtime.ts b/packages/reconciler/src/runtime.ts
new file mode 100644
index 00000000..2a8d8e6e
--- /dev/null
+++ b/packages/reconciler/src/runtime.ts
@@ -0,0 +1,57 @@
+/* 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/. */
+
+/**
+ * What a compiled bundle sees as "@diffusionstudio/jsx".
+ *
+ * The npm package under that name is authoring-only — types, pure helpers, and
+ * hooks that throw because they have no host to read. A project never resolves
+ * it from node_modules at runtime: the desktop compile marks the specifier
+ * external (`moduleName` for babel-preset-solid's universal transform), and
+ * `evaluate` binds it to this object instead. So the module a project imports
+ * is the authoring surface with the host-bound implementations layered over
+ * it: the renderer's element operations, the compile-target components, and
+ * live `useTicker` / `useFile` in place of the throwing declarations.
+ *
+ * Order matters — the renderer bindings must come last so they win.
+ */
+
+import * as authoring from '@diffusionstudio/jsx';
+
+import * as elements from './elements';
+import {
+ createComponent,
+ createElement,
+ createTextNode,
+ effect,
+ insert,
+ insertNode,
+ memo,
+ mergeProps,
+ render,
+ setProp,
+ spread,
+ use,
+ useFile,
+ useTicker,
+} from './renderer';
+
+export const JSX_RUNTIME = {
+ ...authoring,
+ ...elements,
+ render,
+ effect,
+ memo,
+ createComponent,
+ createElement,
+ createTextNode,
+ insertNode,
+ insert,
+ spread,
+ setProp,
+ mergeProps,
+ use,
+ useTicker,
+ useFile,
+};