Skip to content

The VS Code of video editing, built for agents.

TypeScript

Enhance module import resolution and documentation for userland packages

konstantin-paulusad2c7e27b79f
diff --git a/apps/cli/reference/jsx/module.md b/apps/cli/reference/jsx/module.md
index 3ce26288..d6d76dee 100644
--- a/apps/cli/reference/jsx/module.md
+++ b/apps/cli/reference/jsx/module.md
@@ -16,11 +16,30 @@ The component receives no props; which document node each rendered root maps ont
## Module environment
-- **Provided by the host** (marked external at compile time, resolved in-app so the project shares the editor's reactive runtime): `solid-js`, `solid-js/store`, `@diffusionstudio/jsx`.
-- **Everything else is bundled** by the CLI at compile time: npm dependencies, local imports, JSON, etc. A project folder is an ordinary npm package: install any helper library (`date-fns`, `zod`, `d3-scale`, …) and import it; it is resolved from the project's `node_modules` and baked into the shipped bundle. Libraries must be browser-compatible (no Node builtins); violations surface as compile errors, before the app is contacted.
+Imports resolve by category:
+
+- **Host modules** (marked external at compile time, resolved in-app so the project shares the editor's reactive runtime): `solid-js`, `solid-js/store`, `@diffusionstudio/jsx`. These must be the editor's own instance and never come from anywhere else.
+- **Userland packages** — any other bare specifier (`three`, `gsap`, `d3-scale`, …). These are **not installed and not bundled**: the CLI rewrites them to a CDN URL (default `https://esm.sh/<specifier>`, so `three/examples/jsm/loaders/GLTFLoader.js` becomes `https://esm.sh/three/examples/jsm/loaders/GLTFLoader.js`) and the renderer imports them natively at runtime. Any npm package works without a `node_modules`, so this works in a packaged app too. The package's own transitive deps are resolved by the CDN. Libraries must be browser-compatible (no Node builtins).
+- **Local and URL imports**: relative/absolute paths (`./helper`, local JSON) are resolved on disk and bundled as before; explicit `https://…` imports pass through to the renderer untouched.
- The module executes **inside the editor process**, unsandboxed. This is local tooling with a local trust model, the same trust as running the CLI itself. Only effects made through the JSX runtime are part of the document (and its undo history); anything else the module does is unsupported.
- Solid's control flow (`<For>`, `<Show>`, `<Index>`, `<Switch>`) and primitives (`createSignal`, `createMemo`, …) are fully available during mount. See [lifecycle.md](./lifecycle.md) for what happens after mount.
+### Import map (`dapi.config.json`)
+
+A `dapi.config.json` in the working directory pins versions or redirects userland specifiers — for reproducible mounts, a self-hosted mirror, or a local vendored copy. Exact keys match a specifier; a trailing-slash key maps its subpaths (longest prefix wins):
+
+```json
+{
+ "cdnBase": "https://esm.sh",
+ "imports": {
+ "three": "https://esm.sh/[email protected]",
+ "three/": "https://esm.sh/[email protected]/"
+ }
+}
+```
+
+`cdnBase` overrides the default CDN for anything not in `imports`. The `DAPI_CDN_BASE` and `DAPI_IMPORT_MAP` (a JSON object) env vars override for one-offs. An unpinned specifier resolves to the CDN's latest.
+
## Types and tooling
`@diffusionstudio/jsx` ships the JSX namespace (intrinsic elements and props), `Time`, `AssetRef`, and the `generate` namespace. For editor IntelliSense and typechecking in a project folder:
@@ -35,3 +54,5 @@ The component receives no props; which document node each rendered root maps ont
```
The CLI does not typecheck; types are stripped at compile time. Run `tsc --noEmit` in the project folder for type safety.
+
+Userland packages resolve from a CDN at runtime, so they need no runtime install, but the editor still wants their type declarations. For IntelliSense on a library, install it (or its `@types/…`) as a **dev-only** dependency (`npm i -D three`); it is used purely for typechecking and never bundled or shipped.
diff --git a/apps/cli/src/compile-project.ts b/apps/cli/src/compile-project.ts
index 04af5731..fe7cb987 100644
--- a/apps/cli/src/compile-project.ts
+++ b/apps/cli/src/compile-project.ts
@@ -2,7 +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 { existsSync, readFileSync } from "node:fs";
import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
import { transformAsync } from "@babel/core";
import { build } from "esbuild";
import type { Plugin } from "esbuild";
@@ -10,15 +12,86 @@ import presetSolid from "babel-preset-solid";
import presetTypescript from "@babel/preset-typescript";
/**
- * Compiles a Solid JSX project module into a single-file ESM bundle for `dapi mount`
+ * Compiles a Solid JSX project module into a single-file ESM bundle for `dapi mount`.
+ *
+ * Import resolution splits modules into two worlds:
+ * - Host modules the app must provide as its own instance (the shared Solid
+ * reactive runtime and the JSX runtime) are left external under the
+ * "dapi-host:" prefix and shimmed to the app's namespaces at load time.
+ * - Everything else is userland: bare specifiers (three, gsap, ...) are left
+ * external and rewritten to a CDN URL, so authors never install anything and
+ * any npm package works without us hardcoding a dependency list. An optional
+ * `dapi.config.json` import map pins versions or redirects to a mirror.
*/
// Prefix shared with the app's module loader — a specifier no user code would
// contain by accident, so the app-side rewrite is unambiguous.
export const HOST_MODULE_PREFIX = "dapi-host:";
+// Modules that must be the app's own instance (a second copy of the Solid
+// runtime would not share the reactive graph). These are never userland.
const HOST_MODULES_RE = /^(?:solid-js(?:\/store)?|@diffusionstudio\/jsx)$/;
+// Userland bare imports resolve here at runtime unless the import map overrides
+// them; the renderer imports the URL natively (a blob module can import
+// absolute URLs). esm.sh resolves each package's own transitive deps.
+const DEFAULT_CDN_BASE = "https://esm.sh";
+
+type ResolverConfig = { cdnBase: string; importMap: Record<string, string> };
+
+/**
+ * Config hook. `dapi.config.json` in the cwd may set `cdnBase` and `imports`
+ * (exact keys like "three" or trailing-slash prefixes like "three/"); env vars
+ * override for one-offs. Malformed config is ignored in favour of the defaults.
+ */
+function loadResolverConfig(): ResolverConfig {
+ let cdnBase = process.env.DAPI_CDN_BASE || DEFAULT_CDN_BASE;
+ let importMap: Record<string, string> = {};
+
+ const configPath = resolve(process.cwd(), "dapi.config.json");
+ if (existsSync(configPath)) {
+ try {
+ const cfg = JSON.parse(readFileSync(configPath, "utf8")) as {
+ cdnBase?: string;
+ imports?: Record<string, string>;
+ };
+ if (cfg.cdnBase) cdnBase = cfg.cdnBase;
+ if (cfg.imports) importMap = cfg.imports;
+ } catch {
+ // Ignore a malformed config; fall back to defaults.
+ }
+ }
+
+ if (process.env.DAPI_IMPORT_MAP) {
+ try {
+ importMap = { ...importMap, ...(JSON.parse(process.env.DAPI_IMPORT_MAP) as Record<string, string>) };
+ } catch {
+ // Ignore malformed env override.
+ }
+ }
+
+ return { cdnBase: cdnBase.replace(/\/+$/, ""), importMap };
+}
+
+/**
+ * Maps a bare specifier to a URL: an exact import-map hit wins, then the longest
+ * matching trailing-slash prefix, then the CDN default.
+ */
+function resolveBareSpecifier(spec: string, { cdnBase, importMap }: ResolverConfig): string {
+ const exact = importMap[spec];
+ if (exact) return exact;
+
+ let prefix: string | undefined;
+ for (const key of Object.keys(importMap)) {
+ if (key.endsWith("/") && spec.startsWith(key) && (prefix === undefined || key.length > prefix.length)) {
+ prefix = key;
+ }
+ }
+ if (prefix !== undefined) return importMap[prefix] + spec.slice(prefix.length);
+
+ return `${cdnBase}/${spec}`;
+}
+
async function transformSolidJsx(source: string, filename: string): Promise<string> {
const result = await transformAsync(source, {
filename,
@@ -36,22 +109,41 @@ async function transformSolidJsx(source: string, filename: string): Promise<stri
return result.code;
}
-const solidUniversalPlugin: Plugin = {
- name: "solid-universal",
- setup(pluginBuild) {
- pluginBuild.onResolve({ filter: HOST_MODULES_RE }, (args) => ({
- path: `${HOST_MODULE_PREFIX}${args.path}`,
- external: true,
- }));
-
- // esbuild strips types from .ts natively; only JSX files go through babel
- // so the Solid transform sees the untouched JSX.
- pluginBuild.onLoad({ filter: /\.[jt]sx$/ }, async (args) => ({
- contents: await transformSolidJsx(await readFile(args.path, "utf8"), args.path),
- loader: "js",
- }));
- },
-};
+function resolverPlugin(config: ResolverConfig): Plugin {
+ return {
+ name: "dapi-resolver",
+ setup(pluginBuild) {
+ pluginBuild.onResolve({ filter: /.*/ }, (args) => {
+ const spec = args.path;
+
+ // Let esbuild resolve the entry file itself on disk.
+ if (args.kind === "entry-point") return null;
+
+ // App-provided singletons: externalized and shimmed at load time.
+ if (HOST_MODULES_RE.test(spec)) {
+ return { path: `${HOST_MODULE_PREFIX}${spec}`, external: true };
+ }
+
+ // Explicit URL imports pass through to the renderer untouched.
+ if (/^https?:\/\//.test(spec)) return { external: true };
+
+ // Relative or absolute-path imports resolve on disk as usual (multi-file
+ // samples, local helpers).
+ if (spec.startsWith(".") || isAbsolute(spec)) return null;
+
+ // Anything else is a userland bare specifier -> CDN / import map.
+ return { path: resolveBareSpecifier(spec, config), external: true };
+ });
+
+ // esbuild strips types from .ts natively; only JSX files go through babel
+ // so the Solid transform sees the untouched JSX.
+ pluginBuild.onLoad({ filter: /\.[jt]sx$/ }, async (args) => ({
+ contents: await transformSolidJsx(await readFile(args.path, "utf8"), args.path),
+ loader: "js",
+ }));
+ },
+ };
+}
export type CompileInput = { path: string } | { code: string };
@@ -71,7 +163,7 @@ export async function compileProject(input: CompileInput): Promise<string> {
target: "es2022",
sourcemap: "inline" as const,
logLevel: "silent" as const,
- plugins: [solidUniversalPlugin],
+ plugins: [resolverPlugin(loadResolverConfig())],
};
// Inline --code bypasses esbuild's loader pipeline (stdin skips onLoad), so
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index d608a746..b93c08cc 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -18,6 +18,7 @@ const AUTH_PROTOCOL = "diffusion";
const MACOS_CORNER_RADIUS = 16;
const MACOS_BACKDROP = { blur: 80, red: 0.07, green: 0.07, blue: 0.07, alpha: 0.9 };
+app.setName("Diffusion Studio");
app.commandLine.appendSwitch("enable-blink-features", "CanvasDrawElement");
let setNativeCornerRadius: ((handle: Buffer, radius: number) => void) | null = null;
diff --git a/samples/reconciler/09-three-helmet.tsx b/samples/reconciler/09-three-helmet.tsx
new file mode 100644
index 00000000..ac5827c7
--- /dev/null
+++ b/samples/reconciler/09-three-helmet.tsx
@@ -0,0 +1,103 @@
+/* @jsxImportSource @diffusionstudio/jsx */
+/* Three.js owning a <canvas>: a glTF helmet spun by the playhead.
+ *
+ * dapi mount --live samples/reconciler/09-three-helmet.tsx
+ *
+ * The <canvas> ref hands three.js a detached HTMLCanvasElement to render into;
+ * the engine samples that bitmap into the node's box every frame, so a WebGL
+ * scene composites like any other paint (needs preserveDrawingBuffer so the
+ * per-frame readback doesn't come back blank). One clock drives everything:
+ * useTicker's composition time seeks the helmet's rotation inside a
+ * createEffect, so scrubbing and exports stay frame-accurate, not wall-clock.
+ *
+ * The "Battle Damaged Sci-Fi Helmet" is the Khronos DamagedHelmet sample, a
+ * single-file .glb GLTFLoader fetches directly over the network (useFile is the
+ * host-resolved route for project-local assets). RoomEnvironment bakes an
+ * in-memory PBR reflection map, so the metal reads without shipping an HDR.
+ */
+
+import { createEffect, createSignal, onCleanup } from "solid-js";
+import { useTicker } from "@diffusionstudio/jsx";
+import * as THREE from "three";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
+
+const MODEL_URL =
+ "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/DamagedHelmet/glTF-Binary/DamagedHelmet.glb";
+
+const TURN_SECONDS = 6; // one full revolution per 6s of composition time
+
+export default () => {
+ const { time } = useTicker();
+ const [loaded, setLoaded] = createSignal(false);
+
+ const setup = (el: HTMLCanvasElement) => {
+ const renderer = new THREE.WebGLRenderer({
+ canvas: el,
+ antialias: true,
+ alpha: true,
+ preserveDrawingBuffer: true,
+ });
+ renderer.setSize(el.width, el.height, false);
+ renderer.outputColorSpace = THREE.SRGBColorSpace;
+ renderer.toneMapping = THREE.ACESFilmicToneMapping;
+ renderer.toneMappingExposure = 1.1;
+
+ const scene = new THREE.Scene();
+ const camera = new THREE.PerspectiveCamera(45, el.width / el.height, 0.1, 100);
+ camera.position.set(0, 0.35, 4);
+ camera.lookAt(0, 0, 0);
+
+ // In-memory image-based lighting: gives the PBR metal real reflections
+ // without fetching an external HDR.
+ const pmrem = new THREE.PMREMGenerator(renderer);
+ scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;
+
+ // Key + hemisphere fill, so the helmet reads with shape and highlights.
+ const key = new THREE.DirectionalLight(0xffffff, 2.6);
+ key.position.set(5, 8, 6);
+ scene.add(key);
+ scene.add(new THREE.HemisphereLight(0xbad6ff, 0x1a1a22, 1.1));
+
+ // Rotating around the pivot keeps the model centred as it spins.
+ const pivot = new THREE.Group();
+ scene.add(pivot);
+
+ let disposed = false;
+ new GLTFLoader()
+ .loadAsync(MODEL_URL)
+ .then((gltf) => {
+ if (disposed) return;
+ const model = gltf.scene;
+ // Centre on the pivot and normalise scale so the helmet fills the frame.
+ const box = new THREE.Box3().setFromObject(model);
+ const size = box.getSize(new THREE.Vector3()).length();
+ const center = box.getCenter(new THREE.Vector3());
+ model.position.sub(center);
+ pivot.scale.setScalar(2.6 / size);
+ pivot.add(model);
+ setLoaded(true); // wake the effect so the first frame renders even when paused
+ })
+ .catch((err) => console.error("Helmet model load failed:", err));
+
+ // The playhead is the only clock. Reading time() (and loaded()) subscribes
+ // the effect, so it re-renders every tick and once the model streams in.
+ createEffect(() => {
+ loaded();
+ pivot.rotation.y = time() * ((Math.PI * 2) / TURN_SECONDS);
+ renderer.render(scene, camera);
+ });
+
+ onCleanup(() => {
+ disposed = true;
+ pmrem.dispose();
+ renderer.dispose();
+ });
+ };
+
+ return (
+ <scene key="sample-three" name="Three helmet" width={960} height={540} fill="#0b0d12">
+ <canvas x={0} y={0} width={960} height={540} ref={setup} />
+ </scene>
+ );
+};
diff --git a/samples/reconciler/README.md b/samples/reconciler/README.md
index 052d94ab..aebbc0d5 100644
--- a/samples/reconciler/README.md
+++ b/samples/reconciler/README.md
@@ -13,6 +13,7 @@ Run from the repo root with the editor open:
| [06-anime-timeline.tsx](06-anime-timeline.tsx) | `dapi mount --live samples/reconciler/06-anime-timeline.tsx` | anime.js timeline seeked from useTicker, driving an ECS node and \<html\> content in lockstep |
| [07-anime-mini.tsx](07-anime-mini.tsx) | `dapi mount --live samples/reconciler/07-anime-mini.tsx` | minimal anime.js + useTicker sync, sized for a social post |
| [08-canvas-paint.tsx](08-canvas-paint.tsx) | `dapi mount --live samples/reconciler/08-canvas-paint.tsx` | ref-provided canvas: \<canvas\> element and \<canvasPaint\> child, effect-driven redraws |
+| [09-three-helmet.tsx](09-three-helmet.tsx) | `dapi mount --live samples/reconciler/09-three-helmet.tsx` | three.js WebGL renderer owning a \<canvas\>, glTF model loaded over the network, rotation seeked from useTicker |
Each root scene carries a stable key, so re-mounting a sample replaces its
scene in place. Inspect results with `dapi node tree`; entity ids in sample 03