lecodes-sdk 1.1.0 → 2.0.0

package/README.md

@@ -55,7 +55,7 @@ node.matrix = m
 ```
 
 `Quat`/`Mat4` cover the rest: `Quat.fromEuler/lookRotation/slerp`, `Mat4.compose/decompose/lookAt/
-perspective`. All of it is fuzz-tested against gl-matrix (dev-only oracle) in `tests/math.oracle.test.ts`.
+perspective`. All of it is fuzz-tested against gl-matrix (dev-only oracle) in `tests/math/oracle.test.ts`.
 
 ## Design rules
 
@@ -63,7 +63,7 @@ perspective`. All of it is fuzz-tested against gl-matrix (dev-only oracle) in `t
   `.collider()`, `.clips()/.play()`); reuse is a factory function. Per-frame logic is `setLoop(dt => …)`.
 - **Few globals.** Variants are static factory methods (`Mesh.box()`, `Material.lit()`,
   `Texture2D.load()`), not free functions.
-- **Pure re-skin.** Calls the existing `_creator` / `_creator2d` / `_creatorUI` / `_creatorUtils`
+- **Pure re-skin.** Calls the existing `_creator` / `_creator2d` / `_creatorTree` / `_creatorUtils`
   host bridges — no native engine changes.
 
 ## Layout
@@ -93,6 +93,9 @@ bun test            # compile/parity + math/color + 2D + 3D-runtime + UI tests
 bun run typecheck   # tsc --noEmit
 ```
 
+Tests live in `tests/<area>/`, one folder per `src/<area>` they exercise; [tests/README.md](tests/README.md)
+has the layout, the shared stubs and the one-process rules.
+
 `tests/headless/` holds live WebGL2 render harnesses (manual; need chrome-headless-shell). The 2D
 harness is green: a project compiled through the real `compileProject` renders correct pixels.
 

package/dist/editor.d.ts

@@ -0,0 +1,12 @@
+// AUTO-GENERATED by build-types.ts. The extra globals of an EDITOR bundle (a compile with
+// `editor: true`): the scene editor's contract with the SDK. For the scene-editor harness, beside
+// global.d.ts — a project never includes this file.
+
+import type * as EDITOR from "./types/inject.editor"
+
+declare global {
+  const __sceneEditor: typeof EDITOR.__sceneEditor
+  type SceneEditorApi = EDITOR.SceneEditorApi
+}
+
+export {}

package/dist/global.d.ts

@@ -59,6 +59,7 @@ declare global {
   const Mathf: typeof SDK.Mathf
   const Mesh: typeof SDK.Mesh
   const Model: typeof SDK.Model
+  const MouseEnterEvent: typeof SDK.MouseEnterEvent
   const MoveTo: typeof SDK.MoveTo
   const NativeView: typeof SDK.NativeView
   const NavAgent: typeof SDK.NavAgent
@@ -145,7 +146,6 @@ declare global {
   const Warp: typeof SDK.Warp
   const WebSocket: typeof SDK.WebSocket
   const Wheel: typeof SDK.Wheel
-  const __GizmoBuffer: typeof SDK.__GizmoBuffer
   const __UIBox: typeof SDK.__UIBox
   const __UIButton: typeof SDK.__UIButton
   const __UIColumn: typeof SDK.__UIColumn
@@ -153,17 +153,12 @@ declare global {
   const __UIScreen: typeof SDK.__UIScreen
   const __UIScrollable: typeof SDK.__UIScrollable
   const __UIWidget: typeof SDK.__UIWidget
-  const __applyEditorPose: typeof SDK.__applyEditorPose
-  const __applyMaterialParam: typeof SDK.__applyMaterialParam
-  const __assignMaterialDef: typeof SDK.__assignMaterialDef
   const __channel: typeof SDK.__channel
   const __compOp: typeof SDK.__compOp
   const __compWrite: typeof SDK.__compWrite
-  const __editorPlugins: typeof SDK.__editorPlugins
   const __rpc: typeof SDK.__rpc
   const __serverOnly: typeof SDK.__serverOnly
   const __uiMap: typeof SDK.__uiMap
-  const __withGizmoScope: typeof SDK.__withGizmoScope
   const animate: typeof SDK.animate
   const app: typeof SDK.app
   const audio: typeof SDK.audio
@@ -276,6 +271,7 @@ declare global {
   type DecalTrail = SDK.DecalTrail
   type DecalTrailOptions = SDK.DecalTrailOptions
   type DifferentialMode = SDK.DifferentialMode
+  type DismissOptions = SDK.DismissOptions
   type Displacement = SDK.Displacement
   type DriveLayout = SDK.DriveLayout
   type DynamicBone = SDK.DynamicBone
@@ -378,6 +374,7 @@ declare global {
   type MeshDef = SDK.MeshDef
   type Model = SDK.Model
   type MotionOptions = SDK.MotionOptions
+  type MouseEnterEvent<T = any> = SDK.MouseEnterEvent<T>
   type MoveTo = SDK.MoveTo
   type NativeView = SDK.NativeView
   type NavAgent = SDK.NavAgent
@@ -516,8 +513,8 @@ declare global {
   type Trail = SDK.Trail
   type Transition = SDK.Transition
   type TransitionName = SDK.TransitionName
+  type TransitionPose = SDK.TransitionPose
   type TransitionSpec = SDK.TransitionSpec
-  type TransitionTransform = SDK.TransitionTransform
   type TrianglePick = SDK.TrianglePick
   type Trigger = SDK.Trigger
   type Trigger2D = SDK.Trigger2D
@@ -575,7 +572,6 @@ declare global {
   type Wheel = SDK.Wheel
   type WheelSuspension = SDK.WheelSuspension
   type With<N, A extends Aspect<any, any, any>> = SDK.With<N, A>
-  type __GizmoBuffer = SDK.__GizmoBuffer
   // ---- server globals (available in *.server.ts; using them in client code is a build error) ----
   const ApiError: typeof SERVER.ApiError
   const auth: typeof SERVER.auth

package/dist/host.d.ts

@@ -1,6 +1,5 @@
 // JS-runtime globals provided by the host engine (web viewer / desktop / iOS), NOT by the SDK.
-// Declared only so SDK and user code type-check — never bundled or injected. Mirrors
-// packages/projects/src/global.d.ts.
+// Declared only so SDK and user code type-check — never bundled or injected.
 
 declare global {
   function setTimeout(handler: (...args: any[]) => void, timeout?: number): number
@@ -57,7 +56,7 @@ declare global {
    *  `Style<typeof myButton>`) is what you'd pass to `el.style(...)` — for typing reusable style
    *  presets. Deliberately no `Partial<>` wrapper: every style prop is already optional, and
    *  Partial over ClassStyles' `$`-index signature adds `| undefined`, breaking assignability back
-   *  into `.style(...)`. Round-trip guarded by sdk/tests/ui-types.test.ts. */
+   *  into `.style(...)`. Round-trip guarded by sdk/tests/ui/types.test.ts. */
   type Style<T> = T extends { style: (s: infer S) => any } ? S : never
 }
 

package/dist/types/animate/tween/Animation.d.ts

@@ -29,7 +29,6 @@ export interface Animation {
  *  declarations because `TimelineImpl` extends it — marking it internal (even mentioning the tag in
  *  this comment: the strip is a substring match) drops the timeline's playback members. */
 export declare class TweenAnimation implements Animation {
-    private _id;
     private _started;
     private _endTime;
     private _playing;
@@ -38,7 +37,6 @@ export declare class TweenAnimation implements Animation {
     private _resolve;
     private _settled;
     private _listeners;
-    private _fb?;
     constructor(spec: TweenSpec);
     private _newPromise;
     private _settle;
@@ -64,6 +62,5 @@ export declare class TweenAnimation implements Animation {
     finish(): this;
     cancel(): this;
     onFinish(fn: (done: boolean) => void): this;
-    private _ensureFallback;
 }
 export { CLOCK_UI, CLOCK_GAME };

package/dist/types/animate/tween/animateValue.d.ts

@@ -4,8 +4,10 @@ import type { QuatLike } from "../../math/quat";
 import type { Mat4Like } from "../../math/mat4";
 import type { ColorInput } from "../../core/color";
 import { type TweenMeta } from "./spec";
-/** What `animate()` tweens: a number, a color (string / packed / rgb(a) array — delivered as rgba
- *  0..1), a 2 / 3-vector, a quaternion (slerp), or a 4x4 matrix (position / rotation / scale). */
+/** What `animate()` tweens: a number (a FLOAT, never a packed color), a color (any CSS color string,
+ *  through `Color` — delivered as rgba 0..1; a string that is not a color throws), a 2 / 3-vector (a
+ *  3-array is a vector, not a color), a quaternion (slerp), or a 4x4 matrix (position / rotation /
+ *  scale). */
 export type AnimateValue = number | string | Vec2Like | Vec3Like | QuatLike | Mat4Like | ColorInput;
 /** `onUpdate` receives a number for a number; every other kind arrives as the SAME `Float32Array`
  *  every frame (overwritten in place — copy it if you keep it). A matrix is the 16 floats. */

package/dist/types/animate/tween/easing.d.ts

@@ -19,6 +19,14 @@ export type EasingInput = string | readonly [number, number, number, number] | E
 /** id → (name, formula). The formulas are the standard easings.net set; creator-tween's
  *  `ctweenEaseNamed` implements the same list by id. */
 export declare const NAMED_EASINGS: ReadonlyArray<readonly [string, Easing]>;
+/** The CSS `ease-in-out` curve — also UIKit's default animation curve, and web-lite's transition
+ *  default: what every host tweened with before the keyframe core. */
+export declare const CSS_EASE_IN_OUT: [number, number, number, number];
+export declare const LINEAR: EasingSpec;
+/** The default of every track with a TARGET (`animateTo` / `animateFrom` / `Timeline.add` on an
+ *  element, a 3D / 2D object): `ease-in-out` (2026-09-27; linear before). `animate()` — a raw
+ *  progress the app maps itself — stays linear. Write `easing: "linear"` for uniform motion. */
+export declare const DEFAULT_EASING: EasingSpec;
 /** Sample an `Easing` function into a table. Endpoints are forced exact so a curve that is
  *  numerically 0.9999 at 1 still lands on the keyframe. */
 export declare const sampleEasing: (fn: Easing) => Float32Array;

package/dist/types/animate/tween/spec.d.ts

@@ -89,7 +89,8 @@ export type TweenMeta = {
     delay?: number;
     /** A curve for every prop, or a per-prop map (`{ width: 'outExpo', opacity: 'linear' }`). Names
      *  (`outCubic`, `inOutSine`, `outBack`, …), `cubic-bezier(…)` / a `[x1, y1, x2, y2]` tuple,
-     *  `steps(n)`, or any `Easing` function. Default linear. */
+     *  `steps(n)`, or any `Easing` function. Default `ease-in-out` (cubic-bezier(0.42, 0, 0.58, 1),
+     *  the curve UIKit and CSS transitions ease with); `"linear"` for uniform motion. */
     easing?: EasingInput | Record<string, EasingInput>;
     /** Keyframe offsets 0..1 for array-valued props (default: evenly spaced). */
     times?: number[];
@@ -107,20 +108,27 @@ export type TweenMeta = {
 };
 export declare const DEFAULT_DURATION_MS = 225;
 export declare const warnOnce: (key: string, msg: string) => void;
-/** Resolve the per-prop easing from the bag. */
-export declare const easingFor: (easing: TweenMeta["easing"], prop: string) => EasingSpec;
+/** Resolve the per-prop easing from the bag; nothing given (or no entry for `prop` in a per-prop
+ *  map) = `fallback` — the tracks' DEFAULT_EASING, linear for a value tween. */
+export declare const easingFor: (easing: TweenMeta["easing"], prop: string, fallback?: EasingSpec) => EasingSpec;
 /** Iteration count from `loop`: 1 = one-shot, -1 = forever, n = cycles. */
 export declare const iterationsOf: (loop: TweenMeta["loop"]) => number;
 /** A UI style value: number → FLOAT; "12px" / "50%" → FLOAT_UNIT; other strings → STRING (the host
- *  decides color vs discrete); booleans → DISCRETE. */
+ *  decides color vs discrete); booleans → DISCRETE. The element hands over the WIRE value
+ *  (UINode._tweenChannel): a color key arrives as a string, never a packed number. */
 export declare const uiValue: (v: unknown) => ({
     kind: number;
     sig?: string;
 } & TweenValue) | null;
 /** Parse `"translate(10px, 20px) rotate(45deg) scale(1.2)"` into a signature + lanes, or null when a
  *  function is unknown (the caller falls back to matrix decomposition on the host). `scale(2)` and
- *  `translate(5px)` complete their second argument like CSS. */
-export declare const parseTransformList: (s: string) => {
+ *  `translate(5px)` complete their second argument like CSS.
+ *
+ *  `percent`: a `%` in a translate is a percent of the target's box (`translateX(100%)` →
+ *  `translateX%` [100]; a translate mixing the units splits into its two axes). Without it a `%`
+ *  reads as px, as the style's own parser reads it — with a warning: only a screen transition
+ *  measures a translate in percents. */
+export declare const parseTransformList: (s: string, percent?: boolean) => {
     sig: string;
     lanes: number[];
 } | null;
@@ -173,6 +181,6 @@ export type TweenBlob = {
     strings: string[];
     targets: unknown[];
 };
-/** Flatten a spec for `_creatorUI.tweenCreate`. Tracks whose target has no host id right now are
+/** Flatten a spec for `_creatorTree.tweenCreate`. Tracks whose target has no host id right now are
  *  dropped (the animation still runs its clock, calls and finish). */
 export declare const buildBlob: (spec: TweenSpec) => TweenBlob;

package/dist/types/audio/audio.d.ts

@@ -56,7 +56,8 @@ declare class AudioSystem {
     get supported(): boolean;
     /** HRTF binaural rendering (MIT KEMAR filters on the CPU): sounds get a real up / down / behind in
      *  HEADPHONES. Off by default — on speakers it only smears the image. Applies to the `hrtfVoices`
-     *  nearest 3D voices; the rest keep plain panning. */
+     *  nearest 3D voices; the rest keep plain panning. A host built without the filters (an iOS App
+     *  Clip: they are 184 KB) keeps every voice on the panner — `stats.hrtfVoices` stays 0. */
     get hrtf(): boolean;
     set hrtf(v: boolean);
     /** `Time.scale` also pitches the sfx bus: slow motion drops every effect's tone, like a film. Default

package/dist/types/canvas/Canvas.d.ts

@@ -1,59 +1,26 @@
 import { Texture2D } from "../g2/Texture2D";
 import { File, type FetchResponse } from "../runtime/fetch";
 import type { SvgSourceValue } from "../runtime/misc";
-declare const ALIGN: {
-    readonly left: 0;
-    readonly center: 1;
-    readonly right: 2;
-    readonly start: 3;
-    readonly end: 4;
-};
-declare const BASELINE: {
-    readonly alphabetic: 0;
-    readonly top: 1;
-    readonly middle: 2;
-    readonly bottom: 3;
-    readonly hanging: 4;
-    readonly ideographic: 5;
-};
-declare const JOIN: {
-    readonly miter: 0;
-    readonly round: 1;
-    readonly bevel: 2;
-};
-declare const CAP: {
-    readonly butt: 0;
-    readonly round: 1;
-    readonly square: 2;
-};
-export type TextAlign = keyof typeof ALIGN;
-export type TextBaseline = keyof typeof BASELINE;
-export type LineJoin = keyof typeof JOIN;
-export type LineCap = keyof typeof CAP;
+import { Recorder, Gradient, type ImageRef, type TextAlignName, type TextBaselineName, type LineJoinName, type LineCapName, type FillRuleName } from "./gen/recorder";
+export { Gradient };
+export type TextAlign = TextAlignName;
+export type TextBaseline = TextBaselineName;
+export type LineJoin = LineJoinName;
+export type LineCap = LineCapName;
+export type FillRule = FillRuleName;
 export interface CanvasTextMetrics {
     width: number;
     ascent: number;
     descent: number;
 }
-export declare class Canvas {
+export declare class Canvas extends Recorder {
     /** Brand so `Sprite`/`UIImage`/`Material` can accept a Canvas anywhere a texture source is expected. */
     readonly __canvas: true;
     width: number;
     height: number;
     /** Device-pixel multiplier (draw at 2 for crisp retina text). Applied by the backend. */
     pixelRatio: number;
-    private _cmd;
-    private _refs;
-    private _globalAlpha;
-    private _fillStyle;
-    private _strokeStyle;
-    private _lineWidth;
-    private _lineJoin;
-    private _lineCap;
-    private _font;
-    private _textAlign;
-    private _textBaseline;
-    private _surfaceId;
+    private _drawn?;
     private _tex2d?;
     private _uiBound;
     private _lastBakeLen;
@@ -61,71 +28,32 @@ export declare class Canvas {
     constructor(width: number, height: number, opts?: {
         pixelRatio?: number;
     });
-    private _ref;
-    /** Discard the recorded drawing to start a new one (for dynamic canvases). */
-    reset(): this;
     /** Change the surface size; takes effect on the next bake. */
     resize(width: number, height: number): this;
-    save(): this;
-    restore(): this;
-    translate(x: number, y: number): this;
-    scale(sx: number, sy: number): this;
-    rotate(rad: number): this;
-    get globalAlpha(): number;
-    set globalAlpha(a: number);
-    get fillStyle(): string;
-    set fillStyle(color: string);
-    get strokeStyle(): string;
-    set strokeStyle(color: string);
-    get lineWidth(): number;
-    set lineWidth(w: number);
-    get lineJoin(): LineJoin;
-    set lineJoin(j: LineJoin);
-    get lineCap(): LineCap;
-    set lineCap(c: LineCap);
-    get font(): string;
-    set font(f: string);
-    get textAlign(): TextAlign;
-    set textAlign(a: TextAlign);
-    get textBaseline(): TextBaseline;
-    set textBaseline(b: TextBaseline);
-    beginPath(): this;
-    closePath(): this;
-    moveTo(x: number, y: number): this;
-    lineTo(x: number, y: number): this;
-    quadraticCurveTo(cx: number, cy: number, x: number, y: number): this;
-    bezierCurveTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): this;
-    arc(x: number, y: number, r: number, a0: number, a1: number, ccw?: boolean): this;
-    rect(x: number, y: number, w: number, h: number): this;
-    roundRect(x: number, y: number, w: number, h: number, r: number): this;
-    fill(evenOdd?: boolean): this;
-    stroke(): this;
-    fillRect(x: number, y: number, w: number, h: number): this;
-    strokeRect(x: number, y: number, w: number, h: number): this;
-    clearRect(x: number, y: number, w: number, h: number): this;
-    fillText(text: string, x: number, y: number, maxWidth?: number): this;
-    strokeText(text: string, x: number, y: number, maxWidth?: number): this;
-    /** Blit a `Bitmap` (a snapshot from `toBitmap()`) onto this canvas. All coordinates are LOGICAL —
-     *  including the source sub-rect in the 9-arg form (it's scaled by the bitmap's pixelRatio here).
-     *  Records a DRAW_IMAGE op, so the blit runs at bake time: keep the Bitmap alive until the next
-     *  `update()`/`toBitmap()`/`texture()`. Three browser-style forms:
+    /** Blit a `Bitmap` (a snapshot from `toBitmap()` or `loadImage()`) onto this canvas. All coordinates
+     *  are LOGICAL — including the source sub-rect in the 9-arg form (it's scaled by the bitmap's
+     *  pixelRatio here). Records a DRAW_IMAGE op, so the blit runs at bake time; the canvas keeps the
+     *  Bitmap alive until `reset()` removes the op. Three browser-style forms:
      *    drawImage(bmp, dx, dy)                         — whole bitmap at its natural size
      *    drawImage(bmp, dx, dy, dw, dh)                 — whole bitmap, scaled into dw×dh
      *    drawImage(bmp, sx, sy, sw, sh, dx, dy, dw, dh) — a sub-rect of the bitmap, scaled into dw×dh */
-    drawImage(img: Bitmap, dx: number, dy: number): this;
-    drawImage(img: Bitmap, dx: number, dy: number, dw: number, dh: number): this;
-    drawImage(img: Bitmap, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): this;
+    drawImage(img: Bitmap | ImageRef, dx: number, dy: number): this;
+    drawImage(img: Bitmap | ImageRef, dx: number, dy: number, dw: number, dh: number): this;
+    drawImage(img: Bitmap | ImageRef, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): this;
     /** Decode an image source into a standalone `Bitmap` you can blit with `drawImage()` — either an
-     *  `SvgSource(...)` (rasterized) or a `FetchResponse` holding already-fetched image bytes (decoded).
-     *  This is async because turning SVG markup / encoded bytes into pixels needs a decode step (on the
-     *  web, `createImageBitmap` / an `<img>` load); `await` it ONCE, then `drawImage(bitmap, …)` is
-     *  synchronous and the Bitmap is reusable. The returned Bitmap owns a native surface at the image's
-     *  natural pixel size (`pixelRatio` 1) — `destroy()` it when done. Typical use:
+     *  `SvgSource(...)` (drawn by the core, painted by the host) or a `FetchResponse` holding already-fetched
+     *  image bytes (decoded; an SVG file is detected). This is async because the web host decodes with the
+     *  browser; `await` it ONCE, then `drawImage(bitmap, …)` is synchronous and the Bitmap is reusable. The
+     *  returned Bitmap owns a native surface at the image's natural pixel size (`pixelRatio` 1), freed
+     *  once nothing references the Bitmap (`destroy()` frees it early). Typical use:
      *    const logo = await canvas.loadImage(SvgSource(svg))   // or: await fetch(url) → the response
      *    canvas.drawImage(logo, 0, 0)                          // sync, blit as often as you like */
     loadImage(source: SvgSourceValue | FetchResponse): Promise<Bitmap>;
-    /** Measure `text` in the current font on THIS platform. The one synchronous round-trip. */
+    /** Measure `text` in the current font and letterSpacing on THIS platform. The one synchronous
+     *  round-trip. */
     measureText(text: string): CanvasTextMetrics;
+    /** Discard the recording (and the Bitmaps its drawImage ops kept alive). */
+    reset(): this;
     /** Bake and return the 2D texture (created once, then cached). */
     texture(): Texture2D;
     /** Re-rasterize and re-upload to every texture this canvas produced (call after redrawing) — the
@@ -133,38 +61,42 @@ export declare class Canvas {
     update(): this;
     /** Copy the current pixels into a standalone, immutable `Bitmap` — independent of this canvas, so
      *  later drawing/`reset()` never touches it. Draw it back with `drawImage()`, export it with
-     *  `toDataURL()`, or use it to "flatten" an ever-growing drawing so re-bakes stay O(1):
-     *    const snap = canvas.toBitmap()
-     *    canvas.reset(); canvas.drawImage(snap, 0, 0)   // one op replaces the whole history
-     *    // …keep drawing on top; snap.destroy() once it's been drawn in. */
+     *  `toFile()`, or use it to "flatten" an ever-growing drawing so re-bakes stay O(1):
+     *    const next = canvas.toBitmap()                 // bakes with the previous snapshot still alive
+     *    canvas.reset(); canvas.drawImage(next, 0, 0)   // one op replaces the whole history
+     *  The canvas keeps a drawn Bitmap alive while its drawImage is recorded, and the old snapshot goes
+     *  on its own once reset() dropped it — no destroy() needed. */
     toBitmap(): Bitmap;
     /** Encode the current pixels to an image `File` — 'image/png' (default) or 'image/jpeg'. The File
      *  is an opaque host buffer handle (`name`/`size` only): append it to a FormData to upload, load it
      *  as a texture (`Texture2D.load(file)`), or hand it to a share/save sheet. */
     toFile(name?: string, type?: string): Promise<File>;
+    /** Free the surface now instead of when the canvas is dropped (an image still showing it goes blank).
+     *  The recording stays: a later bake makes a new surface. */
     destroy(): void;
 }
 /** Duck-type guard so consumers can accept a Canvas anywhere a texture source is expected. */
 export declare const isCanvas: (v: unknown) => v is Canvas;
-/** An immutable RGBA8 snapshot of a canvas, produced by `Canvas.toBitmap()`. It owns its own baked
- *  surface (a copy), so the source canvas can keep drawing or `reset()` without affecting it. Use it
- *  to stamp/blit back (`canvas.drawImage(bitmap, …)`), to export (`bitmap.toDataURL()`), or as a
- *  cheap "layer" you composite. Call `destroy()` when done — it holds a native surface. */
+/** An immutable RGBA8 snapshot of a canvas, produced by `Canvas.toBitmap()` / `loadImage()`. It owns its
+ *  own baked surface (a copy), so the source canvas can keep drawing or `reset()` without affecting it.
+ *  Use it to stamp/blit back (`canvas.drawImage(bitmap, …)`), to export (`bitmap.toFile()`), or as a
+ *  cheap "layer" you composite. Its surface is freed once nothing references the Bitmap (a canvas that
+ *  drew it keeps it until `reset()`); `destroy()` frees it early. */
 export declare class Bitmap {
     readonly __bitmap: true;
     /** Logical width, matching the Canvas it was captured from (pixelRatio is crispness, not size). */
     readonly width: number;
     readonly height: number;
     readonly pixelRatio: number;
-    constructor(surfaceId: number, width: number, height: number, pixelRatio: number);
+    constructor(surface: Handle | number | null, width: number, height: number, pixelRatio: number);
     /** Device-pixel dimensions of the stored bitmap (`width * pixelRatio`, rounded). */
     get pixelWidth(): number;
     get pixelHeight(): number;
     /** Encode to an image `File` — 'image/png' (default) or 'image/jpeg'. See `Canvas.toFile`. */
     toFile(name?: string, type?: string): Promise<File>;
-    /** Free the native surface. The bitmap must not be drawn or encoded afterwards. */
+    /** Free the native surface now instead of when the bitmap is dropped. It must not be drawn or encoded
+     *  afterwards (a canvas whose recording still draws it blits nothing). */
     destroy(): void;
 }
 /** Duck-type guard for a Bitmap (see `isCanvas`). */
 export declare const isBitmap: (v: unknown) => v is Bitmap;
-export {};

package/dist/types/canvas/gen/cssColor.d.ts

@@ -0,0 +1,17 @@
+/** A color: straight float32 RGBA, 0..1. */
+export interface CssRgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** The named colors as 0xRRGGBBAA: the 148 CSS Color 4 names, transparent and clear (= transparent). */
+export declare const CSS_COLOR_NAMES: Readonly<Record<string, number>>;
+/** A CSS color → straight float32 RGBA, or null when `input` is not a color. */
+export declare const parseCssColor: (input: string) => CssRgba | null;
+/** A float channel → a byte, as the header's toByte: float32, clamp (NaN → 0), round half up (0.5 → 128). */
+export declare const cssToByte: (v: number) => number;
+/** 0xRRGGBBAA (unsigned). */
+export declare const cssRgba8: (c: CssRgba) => number;
+/** '#rrggbbaa', lower-case. */
+export declare const cssHex8: (c: CssRgba) => string;

package/dist/types/canvas/gen/recorder.d.ts

@@ -0,0 +1,118 @@
+export type FillRuleName = "nonzero" | "evenodd";
+export type LineJoinName = "miter" | "round" | "bevel";
+export type LineCapName = "butt" | "round" | "square";
+export type TextAlignName = "left" | "center" | "right" | "start" | "end";
+export type TextBaselineName = "alphabetic" | "top" | "middle" | "bottom" | "hanging" | "ideographic";
+/** A gradient built by createLinearGradient / createRadialGradient; assign it to fillStyle / strokeStyle. */
+export declare class Gradient {
+    readonly stops: {
+        offset: number;
+        color: string;
+    }[];
+    readonly kind: number;
+    readonly coords: [number, number, number, number, number, number];
+    addColorStop(offset: number, color: string): this;
+}
+/** The recorded stream: the f32 words and the string table the core reads. */
+export interface Stream {
+    cmd: Float32Array;
+    refs: string[];
+}
+/** A surface with its device size, for the short drawImage forms. */
+export interface ImageRef {
+    surface: number;
+    width: number;
+    height: number;
+}
+export declare class Recorder {
+    private cmd;
+    private refs;
+    private refIndex;
+    private _globalAlpha;
+    private _fillStyle;
+    private _strokeStyle;
+    private _lineWidth;
+    private _lineJoin;
+    private _lineCap;
+    private _miterLimit;
+    private _lineDash;
+    private _lineDashOffset;
+    private _font;
+    private _textAlign;
+    private _textBaseline;
+    private _letterSpacing;
+    private _saved;
+    /** The words recorded so far (a copy) + the string table. */
+    stream(): Stream;
+    /** Plain arrays, for a JSON file (the golden tests' input). */
+    toJSON(): {
+        cmd: number[];
+        refs: string[];
+    };
+    /** The number of words recorded. */
+    get length(): number;
+    /** Discard the recording; the shadowed state is reset too (a fresh replay starts from defaults). */
+    reset(): this;
+    private ref;
+    private push;
+    save(): this;
+    restore(): this;
+    translate(x: number, y: number): this;
+    scale(sx: number, sy: number): this;
+    rotate(rad: number): this;
+    transform(a: number, b: number, c: number, d: number, e: number, f: number): this;
+    setTransform(a: number, b: number, c: number, d: number, e: number, f: number): this;
+    resetTransform(): this;
+    get globalAlpha(): number;
+    set globalAlpha(a: number);
+    get fillStyle(): string | Gradient;
+    set fillStyle(v: string | Gradient);
+    get strokeStyle(): string | Gradient;
+    set strokeStyle(v: string | Gradient);
+    private style;
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number): Gradient;
+    createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): Gradient;
+    get lineWidth(): number;
+    set lineWidth(w: number);
+    get lineJoin(): LineJoinName;
+    set lineJoin(j: LineJoinName);
+    get lineCap(): LineCapName;
+    set lineCap(c: LineCapName);
+    get miterLimit(): number;
+    set miterLimit(m: number);
+    setLineDash(segments: number[]): this;
+    getLineDash(): number[];
+    get lineDashOffset(): number;
+    set lineDashOffset(o: number);
+    get font(): string;
+    set font(f: string);
+    get textAlign(): TextAlignName;
+    set textAlign(a: TextAlignName);
+    get textBaseline(): TextBaselineName;
+    set textBaseline(b: TextBaselineName);
+    get letterSpacing(): number;
+    set letterSpacing(px: number);
+    beginPath(): this;
+    closePath(): this;
+    moveTo(x: number, y: number): this;
+    lineTo(x: number, y: number): this;
+    quadraticCurveTo(cx: number, cy: number, x: number, y: number): this;
+    bezierCurveTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): this;
+    arc(x: number, y: number, r: number, a0: number, a1: number, ccw?: boolean): this;
+    arcTo(x1: number, y1: number, x2: number, y2: number, r: number): this;
+    ellipse(x: number, y: number, rx: number, ry: number, rotation: number, a0: number, a1: number, ccw?: boolean): this;
+    rect(x: number, y: number, w: number, h: number): this;
+    roundRect(x: number, y: number, w: number, h: number, r: number): this;
+    fill(rule?: FillRuleName): this;
+    stroke(): this;
+    clip(rule?: FillRuleName): this;
+    fillRect(x: number, y: number, w: number, h: number): this;
+    strokeRect(x: number, y: number, w: number, h: number): this;
+    clearRect(x: number, y: number, w: number, h: number): this;
+    fillText(text: string, x: number, y: number, maxWidth?: number): this;
+    strokeText(text: string, x: number, y: number, maxWidth?: number): this;
+    /** Blit a surface. Three browser-style forms; the source rect is in the surface's device px. */
+    drawImage(img: ImageRef, dx: number, dy: number): this;
+    drawImage(img: ImageRef, dx: number, dy: number, dw: number, dh: number): this;
+    drawImage(img: ImageRef, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): this;
+}