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.mdindex 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.tsindex 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<strireturn 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), sodiff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.tsindex 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.tsxnew file mode 100644index 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.mdindex 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 itsscene in place. Inspect results with `dapi node tree`; entity ids in sample 03