The VS Code of video editing, built for agents.
TypeScript
Refactor `<canvas>` to `<surface>` for improved clarity and functionality
konstantin-paulus9feb7badc309
diff --git a/apps/cli/reference/jsx/README.md b/apps/cli/reference/jsx/README.mdindex 9b149046..b7aa8720 100644--- a/apps/cli/reference/jsx/README.md+++ b/apps/cli/reference/jsx/README.md@@ -18,7 +18,7 @@ The pipeline is driven by two commands: [`dapi mount`](../mount.md) renders the| [scene.md](./scene.md), [group.md](./group.md), [rect.md](./rect.md), [text.md](./text.md), [video.md](./video.md), [image.md](./image.md), [audio.md](./audio.md) | Per-element props || [paints.md](./paints.md) | `<solidPaint>`, gradients, `<colorStop>` || [html-paint.md](./html-paint.md) | `<html>`: reactive HTML children drawn into the box |-| [canvas-paint.md](./canvas-paint.md) | `<canvas>`: a ref-provided canvas you draw into, sampled every frame |+| [surface-paint.md](./surface-paint.md) | `<surface>`: a ref-provided canvas you draw into, sampled every frame || [media.md](./media.md) | `src` resolution (paths, URLs, asset ids, `AssetRef`) || [timing.md](./timing.md) | `start` / `end` / `sourceIn` / `sourceOut`, time formats || [keyframes.md](./keyframes.md) | Keyframe animation and easing |diff --git a/apps/cli/reference/jsx/elements.md b/apps/cli/reference/jsx/elements.mdindex 355be01f..496a8a1e 100644--- a/apps/cli/reference/jsx/elements.md+++ b/apps/cli/reference/jsx/elements.md@@ -17,7 +17,7 @@ Lowercase intrinsic elements map 1:1 onto internal node types:| [`<linearGradientPaint>` / `<radialGradientPaint>`](./paints.md) (aliases `<linearGradient>` / `<radialGradient>`) | **Gradient paint** | Paint child; takes `<colorStop>` children. || [`<colorStop>`](./paints.md) (alias `<stop>`) | **Gradient color stop** | Valid only inside gradient paints. || [`<html>`](./html-paint.md) (long form `<htmlPaint>`) | **Html paint** | Paint child whose children are real, reactive HTML drawn by the browser (html-in-canvas, flagged Chromium API). |-| [`<canvas>`](./canvas-paint.md) (long form `<canvasPaint>`) | **Canvas paint** | Paint child whose `ref` hands you a canvas to draw with any context type (2d, webgl, webgpu); sampled every frame. |+| [`<surface>`](./surface-paint.md) (long form `<surfacePaint>`) | **Surface paint** | Paint child whose `ref` hands you a canvas to draw with any context type (2d, webgl, webgpu); sampled every frame. |User-defined components are ordinary Solid components; they compose intrinsics and carry no runtime cost. Only intrinsic elements produce entities.diff --git a/apps/cli/reference/jsx/lifecycle.md b/apps/cli/reference/jsx/lifecycle.mdindex 50ed64c5..c89688ea 100644--- a/apps/cli/reference/jsx/lifecycle.md+++ b/apps/cli/reference/jsx/lifecycle.md@@ -54,7 +54,7 @@ The values respect play, pause, scrubbing, looping, and playback speed, which wa## `useFile`-Resolves a [`src`](./media.md) (path, asset id, URL, or a `generate.*` ref) to its `File`, so effects can read the raw bytes: draw a library image onto a [`<canvas>`](./canvas-paint.md), parse a data file, decode audio. The module is sandboxed and can't fetch a path or asset id itself, so resolution goes through the host, exactly as `src` does.+Resolves a [`src`](./media.md) (path, asset id, URL, or a `generate.*` ref) to its `File`, so effects can read the raw bytes: draw a library image onto a [`<surface>`](./surface-paint.md), parse a data file, decode audio. The module is sandboxed and can't fetch a path or asset id itself, so resolution goes through the host, exactly as `src` does.```tsximport { createSignal, createEffect } from "solid-js";@@ -72,7 +72,7 @@ function Logo() {ctx.drawImage(await createImageBitmap(f), 0, 0, el.width, el.height);});- return <canvas ref={setCanvas} width={640} height={360} />;+ return <surface ref={setCanvas} width={640} height={360} />;}```diff --git a/apps/cli/reference/jsx/paints.md b/apps/cli/reference/jsx/paints.mdindex ffe7e970..da425b43 100644--- a/apps/cli/reference/jsx/paints.md+++ b/apps/cli/reference/jsx/paints.md@@ -20,9 +20,9 @@ Paint elements are valid inside any filled visual element (`<rect>`, `<scene>`,| `<radialGradientPaint>` | `<radialGradient>` | `rotation`, `opacity` | Radial gradient centered in the parent's box. || `<colorStop>` | `<stop>` | `offset` (**required**, `0`-`1`), `color` (**required**), `opacity` | Gradient color stop. Valid only inside gradient paints, which take no other children. || [`<html>`](./html-paint.md) | `<htmlPaint>` | `opacity`, HTML children | Reactive HTML laid out and drawn into the parent's box (flagged Chromium API). |-| [`<canvas>`](./canvas-paint.md) | `<canvasPaint>` | `opacity`, `ref` (**required**) | A canvas your `ref` callback draws into (any context type), sampled into the parent's box every frame. |+| [`<surface>`](./surface-paint.md) | `<surfacePaint>` | `opacity`, `ref` (**required**) | A canvas your `ref` callback draws into (any context type), sampled into the parent's box every frame. |-Both names of a pair work everywhere; names shared with SVG (`<linearGradient>`, `<stop>`) are unambiguous because tags resolve by environment: inside an [`<html>`](./html-paint.md) paint they are the real SVG elements, anywhere else the paints. `<html>` and `<canvas>` themselves are never DOM tags — in a composition they always mean these elements.+Both names of a pair work everywhere; names shared with SVG (`<linearGradient>`, `<stop>`) are unambiguous because tags resolve by environment: inside an [`<html>`](./html-paint.md) paint they are the real SVG elements, anywhere else the paints. `<html>` is never a DOM tag — in a composition it always means the element; `<surface>` doesn't collide with a DOM tag at all.Colors accept any CSS color; alpha is ignored (use `opacity`). `color`, `opacity`, and `offset` are animatable (see [keyframes.md](./keyframes.md)), so gradients can animate. Paints have no spatial or timing props and cannot be document roots.diff --git a/apps/cli/reference/jsx/canvas-paint.md b/apps/cli/reference/jsx/surface-paint.mdsimilarity index 76%rename from apps/cli/reference/jsx/canvas-paint.mdrename to apps/cli/reference/jsx/surface-paint.mdindex af32a180..c96a9f2e 100644--- a/apps/cli/reference/jsx/canvas-paint.md+++ b/apps/cli/reference/jsx/surface-paint.md@@ -1,9 +1,9 @@-# `<canvas>`+# `<surface>`-A paint backed by a **canvas you draw yourself** (long form: `<canvasPaint>`). The `ref` callback receives a detached `HTMLCanvasElement`; draw into it with any context type — 2d, webgl, webgpu — and the engine samples the bitmap every frame, stretching it into the parent geometry's box. Use it for procedural graphics and for external renderers (three.js, p5, chart libraries) that want to own a canvas.+A paint backed by a **canvas you draw yourself** (long form: `<surfacePaint>`). The `ref` callback receives a detached `HTMLCanvasElement`; draw into it with any context type — 2d, webgl, webgpu — and the engine samples the bitmap every frame, stretching it into the parent geometry's box. Use it for procedural graphics and for external renderers (three.js, p5, chart libraries) that want to own a canvas.```tsx-<canvas x={40} y={40} width={640} height={360} cornerRadius={24}+<surface x={40} y={40} width={640} height={360} cornerRadius={24}ref={(el) => {const ctx = el.getContext("2d")!;ctx.fillStyle = "#111";@@ -14,12 +14,12 @@ A paint backed by a **canvas you draw yourself** (long form: `<canvasPaint>`). T}} />```-`<canvasPaint ref={...}>` is the paint child form, valid inside any filled visual element; `<canvas>` is a rectangle carrying one, with all [common props](./elements.md#common-props).+`<surfacePaint ref={...}>` is the paint child form, valid inside any filled visual element; `<surface>` is a rectangle carrying one, with all [common props](./elements.md#common-props).## The ref and the bitmap- The ref runs **once**, when the paint materializes, inside the mount's reactive owner — `createEffect`, `onCleanup`, and [`useTicker`](./lifecycle.md) all work inside it.-- **Callback form only** (`ref={(el) => ...}`). Variable refs (`let el; <canvas ref={el} />`) receive a renderer-internal node, not the canvas.+- **Callback form only** (`ref={(el) => ...}`). Variable refs (`let el; <surface ref={el} />`) receive a renderer-internal node, not the canvas.- The bitmap is allocated at the element's box size (in composition pixels) **before the ref runs**; after that the engine never touches it — the bitmap belongs to your code. Resize it yourself (`el.width = ...`, or an external renderer's own API) for higher resolution; the bitmap is stretched into the box every frame either way, so an animated box scales pixels rather than re-rasterizing.- Unlike [`<html>`](./html-paint.md) no flagged browser API is needed, and the sampled pixels render in exports.@@ -28,7 +28,7 @@ A paint backed by a **canvas you draw yourself** (long form: `<canvasPaint>`). TThe engine samples the canvas every frame, so anything you draw shows up on the next frame. Under [`dapi mount --live`](../mount.md) the reactive graph stays alive: create effects in the ref to redraw from signals, or drive frame-accurate motion from the ticker's composition time:```tsx-<canvas width={400} height={400}+<surface width={400} height={400}ref={(el) => {const ctx = el.getContext("2d")!;const { time } = useTicker();@@ -49,7 +49,7 @@ Because the ticker follows the playhead, ticker-driven drawing stays frame-accurAnything that accepts an existing canvas plugs in directly; a detached canvas is fine for WebGL:```tsx-<canvas width={1280} height={720}+<surface width={1280} height={720}ref={(el) => {const renderer = new THREE.WebGLRenderer({canvas: el,@@ -77,10 +77,10 @@ Anything that accepts an existing canvas plugs in directly; a detached canvas is| `ref` | `(canvas: HTMLCanvasElement) => void` | **required** | Receives the backing canvas at materialization. || `opacity` | `Animatable<number>` | `1` | Paint opacity, `0`-`1`. |-Like all paints it stacks with siblings in document order and clips to the parent's box (including `cornerRadius`). `<canvasPaint>` takes no children.+Like all paints it stacks with siblings in document order and clips to the parent's box (including `cornerRadius`). `<surfacePaint>` takes no children.## Requirements and limitations- The drawing is code, so the content lives only as long as its mount: it is not persisted with the document. Exports and captures started while the mount is alive sample the live canvas.- Only the `ref` attribute form on the element itself is routed; refs inside spread props are not.-- `<canvas>` is not available as a DOM tag inside [`<html>`](./html-paint.md) content — in a composition it is always this element.+- A real DOM `<canvas>` is not available inside [`<html>`](./html-paint.md) content — its pixels don't survive the html-in-canvas rasterization. Use `<surface>` for hand-drawn graphics instead.diff --git a/apps/web/src/components/engine/api/observers.ts b/apps/web/src/components/engine/api/observers.tsindex cd436922..8c250df6 100644--- a/apps/web/src/components/engine/api/observers.ts+++ b/apps/web/src/components/engine/api/observers.ts@@ -482,7 +482,7 @@ export function observeWorld(world: EngineWorld) {utils.reactToChildDetached(world, eid);utils.disposeDecoders(world, eid);utils.disposeHtmlHosts(world, eid);- utils.disposeCanvasHosts(world, eid);+ utils.disposeSurfaceHosts(world, eid);utils.disconnectAudioBus(world, eid);utils.unpersistEntity(world, eid);world.rebuildTimelineIndex();diff --git a/apps/web/src/components/engine/api/query.ts b/apps/web/src/components/engine/api/query.tsindex 85e401de..9b113fcb 100644--- a/apps/web/src/components/engine/api/query.ts+++ b/apps/web/src/components/engine/api/query.ts@@ -75,9 +75,9 @@ export function hasHtmlPaint(world: EngineWorld, eid: number): boolean {return (c.Cache.fills[eid] ?? []).some(fid => c.Paint[fid] === PaintType.HTML);}-export function hasCanvasPaint(world: EngineWorld, eid: number): boolean {+export function hasSurfacePaint(world: EngineWorld, eid: number): boolean {const c = world.components;- return (c.Cache.fills[eid] ?? []).some(fid => c.Paint[fid] === PaintType.CANVAS);+ return (c.Cache.fills[eid] ?? []).some(fid => c.Paint[fid] === PaintType.SURFACE);}export function isMask(world: EngineWorld, eid: number): boolean {diff --git a/apps/web/src/components/engine/api/utils.ts b/apps/web/src/components/engine/api/utils.tsindex bb3e8367..25b1fbc0 100644--- a/apps/web/src/components/engine/api/utils.ts+++ b/apps/web/src/components/engine/api/utils.ts@@ -160,14 +160,14 @@ export function disposeHtmlHosts(world: EngineWorld, eid: number): void {}}-export function disposeCanvasHosts(world: EngineWorld, eid: number): void {- const CanvasHost = world.components.CanvasHost;+export function disposeSurfaceHosts(world: EngineWorld, eid: number): void {+ const SurfaceHost = world.components.SurfaceHost;- CanvasHost[eid]?.dispose();- CanvasHost[eid] = null;+ SurfaceHost[eid]?.dispose();+ SurfaceHost[eid] = null;for (const child of query(world, [ChildOf(eid)])) {- disposeCanvasHosts(world, child);+ disposeSurfaceHosts(world, child);}}diff --git a/apps/web/src/components/engine/components/components.ts b/apps/web/src/components/engine/components/components.tsindex f934507f..9b3d7813 100644--- a/apps/web/src/components/engine/components/components.ts+++ b/apps/web/src/components/engine/components/components.ts@@ -7,7 +7,7 @@ import type { ContainerFormat } from "../encode/types";import type { Token } from "../utils/text";import type { AudioBus as AudioBusInstance } from "../services/audio-bus";import type { HtmlHost as HtmlHostInstance } from "../decoders/html";-import type { CanvasHost as CanvasHostInstance } from "../decoders/canvas";+import type { SurfaceHost as SurfaceHostInstance } from "../decoders/surface";import type { ImageDecoder as ImageDecoderInstance } from "../decoders/image";import type { VideoDecoderInstance } from "../decoders/video";import type { SequenceDecoder as SequenceDecoderInstance } from "../decoders/sequence";@@ -363,7 +363,7 @@ export const Cache = {export const HtmlHost = [] as (HtmlHostInstance | null)[];-export const CanvasHost = [] as (CanvasHostInstance | null)[];+export const SurfaceHost = [] as (SurfaceHostInstance | null)[];export const ImageDecoder = [] as (ImageDecoderInstance | null)[];diff --git a/apps/web/src/components/engine/components/constants.ts b/apps/web/src/components/engine/components/constants.tsindex d5ac573f..281c38fc 100644--- a/apps/web/src/components/engine/components/constants.ts+++ b/apps/web/src/components/engine/components/constants.ts@@ -66,7 +66,7 @@ export enum PaintType {SEQUENCE,WAVEFORM,HTML,- CANVAS,+ SURFACE,}export enum EffectType {diff --git a/apps/web/src/components/engine/decoders/canvas.ts b/apps/web/src/components/engine/decoders/surface.tssimilarity index 83%rename from apps/web/src/components/engine/decoders/canvas.tsrename to apps/web/src/components/engine/decoders/surface.tsindex cca5b62e..44fd19ce 100644--- a/apps/web/src/components/engine/decoders/canvas.ts+++ b/apps/web/src/components/engine/decoders/surface.ts@@ -9,7 +9,7 @@ import type { EngineWorld } from '../api/world';type Ctx2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;/**- * Backing surface for one canvas paint: a detached canvas handed to the+ * Backing store for one surface paint: a detached canvas handed to the* mount's `ref` callback, which draws into it with any context type (2d,* webgl, webgpu). The engine samples the bitmap every frame and stretches it* into the parent geometry's box. After the initial box-sized allocation the@@ -17,7 +17,7 @@ type Ctx2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;* `renderer.setSize`) resize it through their own APIs, so the engine never* touches it again.*/-export class CanvasHost {+export class SurfaceHost {public readonly canvas = document.createElement('canvas');private disposed = false;@@ -43,21 +43,21 @@ export class CanvasHost {}/**- * Shares <canvasPaint> hosts with a cloned (offline) world. The backing+ * Shares <surfacePaint> hosts with a cloned (offline) world. The backing* canvas is runtime state serializeEntity cannot carry, so export/capture* worlds reference the live hosts directly and sample whatever the mount's* ref last drew while encoding. The source world keeps ownership; offline* worlds must not dispose them.*/-export function shareCanvasHosts(+export function shareSurfaceHosts(sourceWorld: EngineWorld,world: EngineWorld,eidMap: Map<number, number>,) {for (const [sourceEid, targetEid] of eidMap) {- const host = sourceWorld.components.CanvasHost[sourceEid];+ const host = sourceWorld.components.SurfaceHost[sourceEid];if (!host) continue;- addComponent(world, targetEid, world.components.CanvasHost, false);- world.components.CanvasHost[targetEid] = host;+ addComponent(world, targetEid, world.components.SurfaceHost, false);+ world.components.SurfaceHost[targetEid] = host;}}diff --git a/apps/web/src/components/engine/encode/encoder.ts b/apps/web/src/components/engine/encode/encoder.tsindex 0ca75544..a4915be6 100644--- a/apps/web/src/components/engine/encode/encoder.ts+++ b/apps/web/src/components/engine/encode/encoder.ts@@ -25,7 +25,7 @@ import { motionSystem } from '../systems/motion';import { transformSystem } from '../systems/transform';import { renderSystem } from '../systems/render';import { shareHtmlHosts } from '../decoders/html';-import { shareCanvasHosts } from '../decoders/canvas';+import { shareSurfaceHosts } from '../decoders/surface';import { cloneFromRecords, serializeEntity } from '../api/serialize';import { getEntityTree } from '../api/query';import { AudioBus } from '../services/audio-bus';@@ -135,7 +135,7 @@ export async function createEncoder(sourceWorld: EngineWorld, config: EncoderConif (videoEnabled) {shareHtmlHosts(sourceWorld, world, eidMap);- shareCanvasHosts(sourceWorld, world, eidMap);+ shareSurfaceHosts(sourceWorld, world, eidMap);}// Set up mediabunny outputdiff --git a/apps/web/src/components/engine/encode/image-encoder.ts b/apps/web/src/components/engine/encode/image-encoder.tsindex 7710dd1c..e55df055 100644--- a/apps/web/src/components/engine/encode/image-encoder.ts+++ b/apps/web/src/components/engine/encode/image-encoder.ts@@ -16,7 +16,7 @@ import { transformSystem } from '../systems/transform';import { renderSystem } from '../systems/render';import { cloneFromRecords, serializeEntity } from '../api/serialize';import { shareHtmlHosts } from '../decoders/html';-import { shareCanvasHosts } from '../decoders/canvas';+import { shareSurfaceHosts } from '../decoders/surface';import { getEntityTree } from '../api/query';import { framesToSeconds, formatTimestamp, stampTimestampLabel } from '../utils';import { assert } from '@/utils';@@ -85,7 +85,7 @@ export async function createImageEncoder(sourceWorld: EngineWorld, config: Imageassert(rootEid !== undefined, 'Failed to clone entity subtree');shareHtmlHosts(sourceWorld, world, eidMap);- shareCanvasHosts(sourceWorld, world, eidMap);+ shareSurfaceHosts(sourceWorld, world, eidMap);const clonedEids = [...eidMap.values()];const c = world.components;diff --git a/apps/web/src/components/engine/systems/render.ts b/apps/web/src/components/engine/systems/render.tsindex cc76f498..fff3452c 100644--- a/apps/web/src/components/engine/systems/render.ts+++ b/apps/web/src/components/engine/systems/render.ts@@ -366,8 +366,8 @@ export function renderFills(world: EngineWorld, eid: number): void {host.draw(ctx, c.Computed.width[eid], c.Computed.height[eid]);ctx.restore();}- } else if (c.Paint[fid] === PaintType.CANVAS) {- const host = c.CanvasHost[fid];+ } else if (c.Paint[fid] === PaintType.SURFACE) {+ const host = c.SurfaceHost[fid];if (host) {ctx.save();diff --git a/apps/web/src/components/engine/timeline/render/clip.ts b/apps/web/src/components/engine/timeline/render/clip.tsindex ea0ec218..6f626c85 100644--- a/apps/web/src/components/engine/timeline/render/clip.ts+++ b/apps/web/src/components/engine/timeline/render/clip.ts@@ -9,7 +9,7 @@ import { CLIP_BREAKPOINTS, CLIP_CORNER_RADIUS, CLIP_FONT, CLIP_LABEL_HEIGHT, CLIimport { renderImageThumbnails } from "./image";import { renderAudioWaveform } from "./audio";import { renderVideoThumbnails } from "./video";-import { getParentEntity, hasCanvasPaint, hasHtmlPaint, isAdjustmentLayer, isCaption, isGroup, isMask, isScene, isText } from "../../api";+import { getParentEntity, hasSurfacePaint, hasHtmlPaint, isAdjustmentLayer, isCaption, isGroup, isMask, isScene, isText } from "../../api";import { renderCaption } from "./caption";import { hasComponent, Not, Or, query } from "bitecs";import { addComponent, clearComponent, removeComponent, setComponent } from "../../api/events";@@ -330,7 +330,7 @@ export function getClipStyle(return timeline.colors.clip.adjustment;}- if (hasHtmlPaint(world, eid) || hasCanvasPaint(world, eid)) {+ if (hasHtmlPaint(world, eid) || hasSurfacePaint(world, eid)) {return timeline.colors.clip.html;}diff --git a/apps/web/src/components/sidebar-right/inspector/fill-row.tsx b/apps/web/src/components/sidebar-right/inspector/fill-row.tsxindex f609d789..58bcc426 100644--- a/apps/web/src/components/sidebar-right/inspector/fill-row.tsx+++ b/apps/web/src/components/sidebar-right/inspector/fill-row.tsx@@ -34,7 +34,7 @@ const FILL_TYPE_LABELS: Record<PaintType, string> = {[PaintType.RADIAL_GRADIENT]: 'Gradient',[PaintType.WAVEFORM]: 'Waveform',[PaintType.HTML]: 'Html',- [PaintType.CANVAS]: 'Canvas',+ [PaintType.SURFACE]: 'Surface',};export function FillRow(props: FillRowProps) {diff --git a/apps/web/src/context/editor-api/selection.ts b/apps/web/src/context/editor-api/selection.tsindex cbd97d06..50f92fe8 100644--- a/apps/web/src/context/editor-api/selection.ts+++ b/apps/web/src/context/editor-api/selection.ts@@ -55,7 +55,7 @@ export function entityType(world: EngineWorld, eid: number): string {case PaintType.IMAGE: return "imagePaint";case PaintType.VIDEO: return "videoPaint";case PaintType.HTML: return "htmlPaint";- case PaintType.CANVAS: return "canvasPaint";+ case PaintType.SURFACE: return "surfacePaint";default: return "paint";}}diff --git a/apps/web/src/utils/jsx.ts b/apps/web/src/utils/jsx.tsindex 55aba7f8..b839c4e8 100644--- a/apps/web/src/utils/jsx.ts+++ b/apps/web/src/utils/jsx.ts@@ -38,7 +38,7 @@ import {transcriptTrim,} from "@/components/engine";import { HtmlHost, isHtmlInCanvasSupported } from "@/components/engine/decoders/html";-import { CanvasHost } from "@/components/engine/decoders/canvas";+import { SurfaceHost } from "@/components/engine/decoders/surface";import { resolveTranscript } from "@/components/engine/decoders/caption/utils";import { ChildOf } from "@/components/engine/components";import { ASPECT_RATIO_DIMENSIONS, findEmptyPlacement } from "@/utils/genai";@@ -66,7 +66,7 @@ type DocumentNode = {eid?: number;dom?: Element | Text;host?: HtmlHost;- canvasHost?: CanvasHost;+ surfaceHost?: SurfaceHost;ref?(target: unknown): void;};@@ -599,25 +599,25 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {appendChild(world, fid, eid);node.host = host;break;- } case "canvasPaint": {- setComponent(world, eid, c.Paint, PaintType.CANVAS);- const host = new CanvasHost();- addComponent(world, eid, c.CanvasHost, false);- c.CanvasHost[eid] = host;- node.canvasHost = host;+ } case "surfacePaint": {+ setComponent(world, eid, c.Paint, PaintType.SURFACE);+ const host = new SurfaceHost();+ addComponent(world, eid, c.SurfaceHost, false);+ c.SurfaceHost[eid] = host;+ node.surfaceHost = host;break;- } case "canvas": {- // A rect carrying a canvas paint; the node's ref receives the- // paint's backing canvas, so `node.canvasHost` points at it.+ } case "surface": {+ // A rect carrying a surface paint; the node's ref receives the+ // paint's backing canvas, so `node.surfaceHost` points at it.setComponent(world, eid, c.Geometry, GeometryType.RECT);- setComponent(world, eid, c.Name, getNextName(world, "Canvas"));+ setComponent(world, eid, c.Name, getNextName(world, "Surface"));const fid = createEntity(world);- setComponent(world, fid, c.Paint, PaintType.CANVAS);- const host = new CanvasHost();- addComponent(world, fid, c.CanvasHost, false);- c.CanvasHost[fid] = host;+ setComponent(world, fid, c.Paint, PaintType.SURFACE);+ const host = new SurfaceHost();+ addComponent(world, fid, c.SurfaceHost, false);+ c.SurfaceHost[fid] = host;appendChild(world, fid, eid);- node.canvasHost = host;+ node.surfaceHost = host;break;} default: {assert(false, `<${node.tag}> is only valid inside <html> content`);@@ -1249,10 +1249,10 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {for (const child of node.children) this.attach(node, child);for (const [name, value] of Object.entries(node.props)) this.applyEcsProperty(node, name, value);- if (node.canvasHost !== undefined) {- const box = this.resolveBoxSize(node.tag === "canvasPaint" ? node.parent ?? node : node);- node.canvasHost.setSize(box.width, box.height);- this.invokeRef(node, node.canvasHost.canvas);+ if (node.surfaceHost !== undefined) {+ const box = this.resolveBoxSize(node.tag === "surfacePaint" ? node.parent ?? node : node);+ node.surfaceHost.setSize(box.width, box.height);+ this.invokeRef(node, node.surfaceHost.canvas);}assert(node.ref === undefined, `\`ref\` is not supported on <${node.tag}>`);}diff --git a/docs/composition.md b/docs/composition.mdindex 7bee956d..5caea9da 100644--- a/docs/composition.md+++ b/docs/composition.md@@ -39,7 +39,7 @@ The first rendered root becomes the active scene. New roots are auto-placed on t| `<sequence>` | Track container for back-to-back clips (positions are explicit); hosts transitions. || `<captions>` | Styled captions: transcribes the scene's audio, or mounts a transcript given via `src`. || `<html>` | A rectangle whose children are HTML/SVG, laid out by the browser at the node's box size and drawn into it. Equivalent to a `<rect>` with an `<htmlPaint>`. |-| `<canvas>` | A rectangle whose `ref` hands you a canvas to draw yourself (2d, webgl, webgpu); the bitmap is sampled into the box every frame. Equivalent to a `<rect>` with a `<canvasPaint>`. |+| `<surface>` | A rectangle whose `ref` hands you a canvas to draw yourself (2d, webgl, webgpu); the bitmap is sampled into the box every frame. Equivalent to a `<rect>` with a `<surfacePaint>`. || `<solidPaint>`, `<linearGradientPaint>`, `<radialGradientPaint>`, `<colorStop>` (aliases `<solid>`, `<linearGradient>`, `<radialGradient>`, `<stop>`) | Fills, declared as children; see [Paints](#paints). |User-defined components are ordinary Solid components; only intrinsic elements produce nodes.@@ -75,7 +75,7 @@ Animatable props also take a keyframe list — see [Animation](#animation).- **`<audio>`**: `src` (required), `volume` (dB; `0` = unity, negative attenuates), `muted`, `syncTo`, timing props.- **`<text>`**: string children (required), `fontFamily` (see `dapi fonts`), `fontSize`, `fontWeight`, `fontStyle`, `fill`, `textAlign`, `textBaseline`.- **`<html>`**: HTML/SVG children. Fully reactive: signals in attributes, styles, and text update the drawn content. Event handlers are dropped (the content is painted, not interactive).-- **`<canvas>`**: `ref` (required, callback form) receives the backing `HTMLCanvasElement` once at materialization; draw with any context type, create effects inside the ref to redraw from signals or the ticker.+- **`<surface>`**: `ref` (required, callback form) receives the backing `HTMLCanvasElement` once at materialization; draw with any context type, create effects inside the ref to redraw from signals or the ticker.These same props are what `dapi node patch` assigns on existing nodes.@@ -88,7 +88,7 @@ These same props are what `dapi node patch` assigns on existing nodes.- an **asset id**: an imported library asset (see `dapi asset tree`)- an **`AssetRef`**: the value returned by a `generate.*` declaration-To read a source's raw bytes inside an effect instead of mounting it as a node, pass the same input to `useFile`, which resolves it to a `File`. It returns Solid's `createResource` tuple (`[file, { mutate, refetch }]`): the `file` accessor reads `undefined` until it resolves, then the `File`. Useful for drawing a library image onto a `<canvas>` or parsing a data file:+To read a source's raw bytes inside an effect instead of mounting it as a node, pass the same input to `useFile`, which resolves it to a `File`. It returns Solid's `createResource` tuple (`[file, { mutate, refetch }]`): the `file` accessor reads `undefined` until it resolves, then the `File`. Useful for drawing a library image onto a `<surface>` or parsing a data file:```tsximport { createSignal, createEffect } from "solid-js";@@ -104,7 +104,7 @@ createEffect(async () => {el.getContext("2d")!.drawImage(await createImageBitmap(f), 0, 0);});-// <canvas ref={setCanvas} width={640} height={360} />+// <surface ref={setCanvas} width={640} height={360} />```## Timing@@ -203,7 +203,7 @@ A node's fill is a **paint child**; the `fill` prop is shorthand for a solid pai</rect>```-`<solidPaint>` takes `color` (required) and `opacity`; gradient paints take `rotation` and `opacity` and only `<colorStop>` children (`offset` and `color` required). Colors are any CSS color; alpha is ignored, use `opacity`. Each paint tag has a short alias (`<solid>`, `<linearGradient>`, `<radialGradient>`, `<stop>`); the SVG name overlap is unambiguous because tags resolve by environment. `<htmlPaint>` draws browser-laid-out HTML/SVG children into the node's box; the `<html>` element is shorthand for a `<rect>` carrying one. `<canvasPaint>` draws a canvas your `ref` callback owns into the node's box; the `<canvas>` element is likewise shorthand for a `<rect>` carrying one.+`<solidPaint>` takes `color` (required) and `opacity`; gradient paints take `rotation` and `opacity` and only `<colorStop>` children (`offset` and `color` required). Colors are any CSS color; alpha is ignored, use `opacity`. Each paint tag has a short alias (`<solid>`, `<linearGradient>`, `<radialGradient>`, `<stop>`); the SVG name overlap is unambiguous because tags resolve by environment. `<htmlPaint>` draws browser-laid-out HTML/SVG children into the node's box; the `<html>` element is shorthand for a `<rect>` carrying one. `<surfacePaint>` draws a canvas your `ref` callback owns into the node's box; the `<surface>` element is likewise shorthand for a `<rect>` carrying one.## Generated assetsdiff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.tsindex 097ddd61..c9183355 100644--- a/packages/jsx/src/index.ts+++ b/packages/jsx/src/index.ts@@ -22,8 +22,6 @@ export type {AnimationSpec,AnimationType,AudioProps,- CanvasPaintProps,- CanvasProps,CaptionPreset,CaptionsProps,ColorStopProps,@@ -40,6 +38,8 @@ export type {SceneProps,SequenceProps,SolidPaintProps,+ SurfacePaintProps,+ SurfaceProps,TextProps,Time,TransitionSpec,diff --git a/packages/jsx/src/jsx-runtime.ts b/packages/jsx/src/jsx-runtime.tsindex 6f2f1f03..d4a38861 100644--- a/packages/jsx/src/jsx-runtime.ts+++ b/packages/jsx/src/jsx-runtime.ts@@ -12,8 +12,6 @@import type { JSX as SolidJSX } from "solid-js";import type {AudioProps,- CanvasPaintProps,- CanvasProps,CaptionsProps,ColorStopProps,GradientPaintProps,@@ -25,13 +23,16 @@ import type {SceneProps,SequenceProps,SolidPaintProps,+ SurfacePaintProps,+ SurfaceProps,TextProps,VideoProps,} from "./types";-// "html" and "canvas" are dropped alongside the media tags: in composition-// context they are node elements, and as DOM tags they are useless inside a-// paint host (a DOM canvas's content doesn't survive drawElementImage).+// "audio", "video" and "html" are dropped because in composition context those+// tags mean the node elements, not DOM tags. "canvas" is dropped for a separate+// reason: a DOM canvas's content doesn't survive drawElementImage, so it is+// useless inside a paint host (draw with <surface> instead).type HtmlElementTags = Omit<SolidJSX.HTMLElementTags, "audio" | "video" | "html" | "canvas">;// SVG vocabulary for <htmlPaint> content. Tags the editor also declares keep@@ -71,7 +72,7 @@ export declare namespace JSX {stop: ColorStopProps;htmlPaint: HtmlPaintProps;html: HtmlProps;- canvasPaint: CanvasPaintProps;- canvas: CanvasProps;+ surfacePaint: SurfacePaintProps;+ surface: SurfaceProps;}}diff --git a/packages/jsx/src/renderer.ts b/packages/jsx/src/renderer.tsindex e57f6784..f8350989 100644--- a/packages/jsx/src/renderer.ts+++ b/packages/jsx/src/renderer.ts@@ -133,7 +133,7 @@ export function useTicker(): Ticker {* if (!el || !f) return;* el.getContext("2d")!.drawImage(await createImageBitmap(f), 0, 0);* });- * // <canvas ref={setCanvas} width={640} height={360} />+ * // <surface ref={setCanvas} width={640} height={360} />* ```*/export function useFile(src: AssetInput): ResourceReturn<File> {diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.tsindex f50dc563..650703f6 100644--- a/packages/jsx/src/types.ts+++ b/packages/jsx/src/types.ts@@ -304,9 +304,9 @@ export type HtmlProps = CommonProps & Pick<HtmlPaintProps, "children">;type HostCanvas = typeof globalThis extends { HTMLCanvasElement: new () => infer T } ? T: { width: number; height: number; getContext(contextId: string, options?: unknown): unknown };-export type CanvasPaintProps = Pick<PatchProps, "opacity"> & {+export type SurfacePaintProps = Pick<PatchProps, "opacity"> & {/**- * Receives the paint's backing canvas once the paint materializes. Draw to+ * Receives the surface's backing canvas once the paint materializes. Draw to* any context type (2d, webgl, webgpu); the engine samples the bitmap every* frame and stretches it into the parent geometry's box. Callback form* only — the renderer has no element to assign to a variable ref.@@ -314,8 +314,8 @@ export type CanvasPaintProps = Pick<PatchProps, "opacity"> & {ref: (canvas: HostCanvas) => void;};-/** `<canvas>` — a rectangle carrying a `<canvasPaint>` with the given ref. */-export type CanvasProps = CommonProps & Pick<CanvasPaintProps, "ref">;+/** `<surface>` — a rectangle carrying a `<surfacePaint>` with the given ref. */+export type SurfaceProps = CommonProps & Pick<SurfacePaintProps, "ref">;export type AudioProps = TimingProps &Required<Pick<PatchProps, "src">> &diff --git a/samples/reconciler/08-canvas-paint.tsx b/samples/reconciler/08-surface-paint.tsxsimilarity index 78%rename from samples/reconciler/08-canvas-paint.tsxrename to samples/reconciler/08-surface-paint.tsxindex 09ac339a..faf63b73 100644--- a/samples/reconciler/08-canvas-paint.tsx+++ b/samples/reconciler/08-surface-paint.tsx@@ -1,13 +1,13 @@/* @jsxImportSource @diffusionstudio/jsx */-/* Ref-provided canvas: the <canvas> element hands its backing bitmap to the+/* Ref-provided canvas: the <surface> element hands its backing bitmap to the* ref callback, which owns it from then on.*- * dapi mount --live samples/reconciler/08-canvas-paint.tsx+ * dapi mount --live samples/reconciler/08-surface-paint.tsx** The ref runs once at materialization, inside the mount's reactive owner:* the effect below redraws from a signal and the playhead ticker, and the* engine samples the bitmap into the node's box every frame. The standalone- * <canvasPaint> on the right stacks over a solid fill inside a plain <rect>.+ * <surfacePaint> on the right stacks over a solid fill inside a plain <rect>.*/import { createEffect, createSignal } from "solid-js";@@ -37,8 +37,8 @@ export default () => {});return (- <scene key="sample-canvas" name="Canvas paint" width={960} height={540} fill="#101014">- <canvas+ <scene key="sample-surface" name="Surface paint" width={960} height={540} fill="#101014">+ <surfacex={40}y={60}width={520}diff --git a/samples/reconciler/09-three-helmet.tsx b/samples/reconciler/09-three-helmet.tsxindex ac5827c7..e3ac1f27 100644--- a/samples/reconciler/09-three-helmet.tsx+++ b/samples/reconciler/09-three-helmet.tsx@@ -1,9 +1,9 @@/* @jsxImportSource @diffusionstudio/jsx */-/* Three.js owning a <canvas>: a glTF helmet spun by the playhead.+/* Three.js owning a <surface>: 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 <surface> 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:@@ -97,7 +97,7 @@ export default () => {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} />+ <surface x={0} y={0} width={960} height={540} ref={setup} /></scene>);};diff --git a/samples/reconciler/README.md b/samples/reconciler/README.mdindex aebbc0d5..3786ce81 100644--- a/samples/reconciler/README.md+++ b/samples/reconciler/README.md@@ -12,8 +12,8 @@ Run from the repo root with the editor open:| [05-html-paint.tsx](05-html-paint.tsx) | `dapi mount --live samples/reconciler/05-html-paint.tsx` | DOM/SVG materialization under \<html\>; needs html-in-canvas || [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 |+| [08-surface-paint.tsx](08-surface-paint.tsx) | `dapi mount --live samples/reconciler/08-surface-paint.tsx` | ref-provided canvas: \<surface\> element and \<surfacePaint\> 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 \<surface\>, 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