@mocanvas/wasm 1.0.0 → 4.0.0

package/README.md

@@ -1,12 +1,12 @@
 # @mocanvas/wasm
 
-The Rust/WebAssembly engine behind [mocanvas](https://github.com/SYMBIO/mocanvas)
+The Rust/WebAssembly engine behind mocanvas
 and its TypeScript bridge. The engine owns the scene: it holds shape geometry,
 maintains a spatial index, hit-tests, culls to the viewport, tessellates and
 batches, and writes vertex/index/batch buffers into linear memory that the host
 uploads to the GPU by pointer — no per-frame copying.
 
-Most applications use `mocanvas` or `@mocanvas/editor` instead of this package
+Most applications use `@mocanvas/mocanvas` or `@mocanvas/editor` instead of this package
 directly. No React, no other dependencies.
 
 ## Install
@@ -99,4 +99,23 @@ ESM only.
 
 ## License
 
-MIT
+**Source-available, not open source.** Free to use for:
+
+- personal, non-commercial projects;
+- non-profit organisations;
+- development, evaluation, testing and staging — including inside a for-profit
+  company, so you can try it and build against it before committing;
+- teaching and academic research.
+
+**Shipping it in a commercial product, service or website needs a written
+agreement with us.** That includes anything sold, anything that earns revenue
+directly or through advertising, and internal tools running a for-profit
+business.
+
+To arrange one, or if you are unsure which side of the line you are on, write to
+**mocanvas@symbio.agency** — we would rather answer the question than have you
+guess.
+
+The full terms are in `LICENSE`, shipped in this package. Versions released
+earlier under MIT stay available under MIT, on the terms they were released
+with.

package/UI.md

@@ -0,0 +1,256 @@
+# The default UI
+
+`<Mocanvas />` ships a small, opinionated interface: a toolbar, a zoom bar, a
+style panel, an optional statistics chip, and the chrome the editor draws on the
+canvas itself. All of it is optional and all of it is themeable from CSS.
+
+Source lives in `packages/mocanvas/src/ui/`:
+
+| File | What it holds |
+| --- | --- |
+| `DefaultUi.tsx` | The toolbar, the zoom bar, the stats chip, and the `DefaultUi` wrapper |
+| `StylePanel.tsx` | The style panel and `getStylePanelSections`, the rule for which rows appear |
+| `icons.tsx` | The whole icon set, plus the geo icons generated from canvas geometry |
+| `overlays.tsx` | The shared tooltip and popover layers, and `placeNear` |
+| `ui.css` | Every design token and every rule |
+| `useKeyboardShortcuts.ts` | The default key bindings |
+
+## Design tokens
+
+Tokens are declared on `.mocanvas` (the editor container), on `.mocanvas-panel`,
+and on `.mocanvas-layer` (the floating tooltip and popover, which sit outside the
+panels in the DOM). Override any of them on `.mocanvas`, on a wrapper, or on a
+single panel.
+
+### Surfaces and colour
+
+| Token | Light | Dark | Used for |
+| --- | --- | --- | --- |
+| `--mocanvas-ui-panel` | `#ffffff` | `#1b1d22` | Panel, popover and picker background |
+| `--mocanvas-ui-panel-border` | `#d6d9e0` | `#3c404a` | Panel hairline, dividers, group separators |
+| `--mocanvas-ui-control` | `rgba(16,24,40,.06)` | `rgba(255,255,255,.08)` | Recessed background of a segmented button |
+| `--mocanvas-ui-text` | `#16181d` | `#eceef3` | Icon and label colour |
+| `--mocanvas-ui-muted` | `#5c6070` | `#a4a9b4` | Row labels, stats text |
+| `--mocanvas-ui-accent` | `#2563eb` | `#6ea8fe` | Selected control, focus ring |
+| `--mocanvas-ui-accent-fg` | `#ffffff` | `#0e1116` | Icon on an accent fill |
+| `--mocanvas-ui-accent-soft` | 12% accent | 18% accent | Hover on a segmented button, open disclosure |
+| `--mocanvas-ui-hover` | 6% ink | 9% white | Hover on a bare button |
+| `--mocanvas-ui-active` | 13% ink | 18% white | Pointer-down on a bare button |
+| `--mocanvas-ui-shadow` | — | — | Panel elevation |
+| `--mocanvas-ui-tip-bg` / `-fg` / `-muted` | — | — | Tooltip pill, its label, its shortcut |
+
+Every text-on-background pair is at or above 4.5:1 in both palettes. Measured on
+the shipped values, the tightest are `accent` on a segmented control (4.58 light,
+5.54 dark) and `muted` on the panel (6.25 light, 7.16 dark). Disabled controls
+render at 35% opacity, which WCAG exempts.
+
+### Metrics
+
+| Token | Value | Meaning |
+| --- | --- | --- |
+| `--mocanvas-ui-btn` | `40px` | Every hit target — buttons, swatches, popover cells |
+| `--mocanvas-ui-icon` | `20px` | Icon size inside a button |
+| `--mocanvas-ui-gap` | `2px` | Gap between adjacent controls |
+| `--mocanvas-ui-pad` | `4px` | Padding of a bar |
+| `--mocanvas-ui-pad-lg` | `10px` | Padding of the style panel, gap between its groups |
+| `--mocanvas-ui-inset` | `12px` | Distance from a panel to the viewport edge |
+| `--mocanvas-ui-radius` / `-sm` | `12px` / `8px` | Panel radius / control radius |
+| `--mocanvas-ui-dock` | `300px` | Width the bottom-left and bottom-right docks reserve beside the centred toolbar |
+| `--mocanvas-ui-bottom-dock` | `62px` (`124px` under 1290px) | Height the bottom edge occupies; the style panel stops above it |
+| `--mocanvas-ui-font` / `-mono` | system stacks | Panel type / stats chip |
+
+`--mocanvas-ui-dock` is the mechanism that keeps the three bottom panels apart:
+the toolbar is centred on the viewport but may not grow into the reservation, so
+it wraps rather than collide. Shrink it if your zoom bar is narrower than the
+default one.
+
+### Canvas chrome
+
+These are read by the editor's indicator layer (`Canvas.tsx`), not by the panels,
+so they apply even with `hideUi`. They are deliberately **not** redefined for the
+dark UI: the canvas keeps its own background, which does not follow
+`prefers-color-scheme`.
+
+| Token | Value | Used for |
+| --- | --- | --- |
+| `--mocanvas-selection` | `#2f6fe4` | Selection and hover outlines, handle strokes, brush border |
+| `--mocanvas-selection-fg` | `#ffffff` | Fill behind a solid handle |
+| `--mocanvas-brush-fill` | 12% selection | Brush rectangle interior |
+| `--mocanvas-snap` | `#cf3fe0` | Snap lines and their end markers |
+
+The two stroke colours clear 3:1 against a light canvas (`#f9fafb`: 4.45 and
+3.69) and against a dark one (`#1b1d22`: 3.63 and 4.37). If you render a dark
+canvas, swap `--mocanvas-selection-fg` for a dark value so handles stay filled
+with the canvas colour rather than white.
+
+Handles are drawn at 9px (corners), 6px (shape handles) and 5.5px (rotate) in
+screen space, with a 1.5px stroke. Their hit radius is a separate editor
+constant, `HANDLE_HIT_RADIUS` in `packages/editor/src/editor/selectionHandles.ts`.
+
+## Icon grid rules
+
+Icons are original artwork on a 24×24 viewBox, painted with `currentColor`.
+
+- **Grid.** 24×24. Ink, stroke included, stays inside it.
+- **Weight.** Stroke 1.75, round caps and joins. Only texture marks deviate and
+  say so at the call site: the fill hatching (1.25), the dotted rule (2.6 with a
+  zero-length dash, so the caps draw the dots), the mono rails (1.4).
+- **Centring.** Ink is optically centred on (12, 12), within half a grid unit.
+  The only exceptions are semantic: `valign-top` and `valign-bottom` sit high and
+  low on purpose.
+- **Extent.** The longest ink dimension lands between 16 and 18.25 units — about
+  17.75 for a full-bleed form — so no icon reads heavier than its neighbour. The
+  `size-*` ramp is exempt: its whole job is to differ in size.
+- **Distinctness.** No two icons may draw the same artwork; `icons.test.tsx`
+  enforces this. It is why the handwriting font is a script `a` rather than a
+  fourth capital A, and why `oval` gets a wider box than `ellipse`.
+- **Geo icons** are generated from `getGeoGeometry`, the same code the canvas
+  draws with, so a toolbar button always matches the shape it creates. Each kind
+  is fitted into the box `getGeoIconBox(kind)` returns: square at `GEO_BOX` (16)
+  by default, and flatter or narrower for kinds whose name implies a proportion
+  (`rectangle`, `oval`, the four arrows). The longest side is always `GEO_BOX`.
+
+Render one with `<Icon name="select" size={20} />`. `size` sets the SVG's
+attributes; buttons additionally take their icon size from `--mocanvas-ui-icon`,
+so inline marks like the "mixed" badge keep the size they ask for.
+
+## Overriding the UI
+
+### Turn it off
+
+```tsx
+<Mocanvas hideUi />
+```
+
+This drops the toolbar, zoom bar, style panel and stats chip. `ui.css` still
+loads, so the canvas chrome tokens above keep working. Default keyboard
+shortcuts are wired by `<Mocanvas />` itself and are unaffected; call
+`useKeyboardShortcuts(editor)` yourself if you build on `<Canvas />` directly.
+
+### Replace the canvas chrome
+
+```tsx
+<Mocanvas components={{ Indicators: MyIndicators, Brush: MyBrush, Background: MyGrid }} />
+```
+
+`components` is forwarded to `<Canvas />`. `Indicators` draws selection and hover
+outlines and handles, `Brush` the marquee, `Background` a layer behind the canvas.
+Each receives `{ editor }` and renders into the SVG overlay (`Background` into a
+plain DOM layer). Omit one to keep the default.
+
+### Rebuild the panels
+
+Compose your own from the exported parts:
+
+```tsx
+import { Mocanvas, Toolbar, ZoomBar, StylePanel, UiTooltip, Icon } from "mocanvas"
+
+<Mocanvas hideUi>
+  <Toolbar />
+  <MyOwnInspector />
+  <UiTooltip />
+</Mocanvas>
+```
+
+`Toolbar`, `ZoomBar`, `StylePanel`, `DebugStats`, `Popover`, `UiTooltip`, `Icon`
+and `TOOLBAR_GROUPS` are all exported. Children of `<Mocanvas>` render above the
+canvas inside the editor container, so the tokens apply to them too.
+
+### Restyle it
+
+```css
+.mocanvas {
+  --mocanvas-ui-accent: #12b886;
+  --mocanvas-ui-radius: 6px;
+  --mocanvas-ui-btn: 44px;
+  --mocanvas-selection: #12b886;
+}
+```
+
+## The panels
+
+### Toolbar — bottom centre
+
+Tools in four groups separated by dividers: select and hand; draw and eraser; the
+five common geo kinds plus a disclosure for the other fifteen; text, note, and
+whichever of arrow, line and frame the app registered. Entries whose tool is not
+registered disappear, so a cut-down `tools` prop yields a cut-down bar. The
+active tool is `aria-pressed`; a geo button is pressed only when its own kind is
+active. The disclosure opens a 5-column popover of the remaining kinds and is
+itself marked pressed when one of them is active. The bar is centred on the
+viewport, wraps to more rows rather than growing into the docks, and moves to a
+row of its own below 1290px.
+
+### Zoom bar — bottom left
+
+Zoom out, the current percentage (a button that resets to 100%), zoom in, zoom to
+fit, then a divider and undo/redo. Undo and redo are `disabled` when there is
+nothing to undo or redo, at 35% opacity and without a tooltip.
+
+### Style panel — top right
+
+Appears when the selection carries at least one style, or when a drawing tool is
+active with nothing selected. Rows are grouped, and separated by a hairline:
+
+1. **Shape** — the geo kind, as one button showing the current shape that opens a
+   20-cell popover.
+2. **Colour** — the stroke colour, and the label colour when the selection can
+   carry one; twelve swatches each, six to a row.
+3. **Stroke and fill** — Fill, Dash and Size, four choices each.
+4. **Text** — Font, then horizontal and vertical alignment sharing one row.
+5. **Opacity** — a slider; only with a selection, since it edits shapes rather
+   than a style.
+
+Which rows appear is decided by `getStylePanelSections(editor)`, which reads
+`editor.getSharedStyles()` for a selection and
+`editor.getStylePropsForType(toolId)` otherwise. A selection of two lines
+therefore shows Colour, Dash and Size and nothing else. A row whose selected
+shapes disagree shows a dashed "mixed" badge beside its label. The panel scrolls
+when it is taller than the space above the bottom dock, with a fade and a shadow
+at whichever edge has more content behind it. Below 560px it spans the width and
+is capped at 42% of the height.
+
+### Statistics chip — bottom right
+
+Shape counts, drawn versus culled, and milliseconds per frame. Toggled with
+`⌥D`, or with the `showStats` prop. It moves above the zoom bar below 560px.
+
+### Tooltip and popover
+
+Both are single, `position: fixed`, viewport-clamped layers (`overlays.tsx`).
+A tooltip labels any element with `data-tooltip`, adding `data-shortcut` in a
+muted weight; it appears after a 500ms rest, immediately on keyboard focus, sits
+above its control so it never covers it, and flips below when there is no room.
+`placeNear` does the arithmetic and is unit-tested. Popovers dismiss on outside
+pointer-down and on Escape, which also returns focus to the button.
+
+## States
+
+| State | Bare button | Segmented button | Swatch |
+| --- | --- | --- | --- |
+| Rest | transparent | `--mocanvas-ui-control` | transparent |
+| Hover | `--mocanvas-ui-hover` | `--mocanvas-ui-accent-soft` | `--mocanvas-ui-hover` |
+| Pointer down | `--mocanvas-ui-active`, scaled 0.94 | as hover, scaled 0.94 | scaled 0.92 |
+| Selected | accent fill, accent-fg icon | accent fill, accent-fg icon | double ring in accent |
+| Selected + hover | accent fill plus an inset ring | same | same |
+| Focus (keyboard) | 2px accent outline, 2px offset | same | same |
+| Disabled | 35% opacity, no tooltip, default cursor | — | — |
+
+The focus ring is offset by 2px so a ring of panel colour separates it from an
+accent-filled button; without that gap, focus would be invisible on the active
+tool. `prefers-reduced-motion` removes every transition.
+
+## Pointer targets
+
+Selection handles use a 24x24 px pointer target (`HANDLE_HIT_RADIUS = 12` in
+`packages/editor/src/editor/selectionHandles.ts`), which is the WCAG 2.2
+minimum. Two rules keep that from swallowing small shapes:
+
+- Edge handles (top, right, bottom, left) only appear once that edge is at
+  least `4 * HANDLE_HIT_RADIUS` long on screen; below that the two corners
+  already cover the whole edge.
+- On a selection smaller than six handles across, `getHandleHitRadius` scales
+  the target down (never below 4 px) so the shape's interior stays draggable.
+
+Both measure the *screen-space* edge lengths of the transformed corners, so a
+rotated selection behaves the same as an upright one.

package/dist/index.d.ts

@@ -15,7 +15,34 @@ declare const OP: {
     readonly SET_STYLE: 4;
     readonly CLEAR: 5;
     readonly SET_TEXTURE: 6;
+    readonly SET_GEO: 7;
+    readonly SET_SPLINE: 8;
+    readonly SET_POLY: 9;
+    readonly SET_DRAW: 10;
 };
+/**
+ * Flag bits for the parametric geometry commands; must match
+ * `crates/mocanvas-wasm/src/lib.rs::geo_flag`.
+ */
+declare const GEO_FLAG: {
+    /** `setGeo`: mirror the silhouette left-to-right inside its own box. */
+    readonly FLIP_X: number;
+    /** `setGeo`: mirror the silhouette top-to-bottom inside its own box. */
+    readonly FLIP_Y: number;
+    /** `setSpline` / `setPoly` / `setDraw`: close the outline. */
+    readonly CLOSED: number;
+    /** `setDraw`, per segment: this run came from a pen, so smooth it. */
+    readonly FREEHAND: number;
+};
+/**
+ * The built-in geo silhouettes the engine can build from parameters, by name.
+ *
+ * The numbers are the indices of `GEO_SHAPE_KINDS`, which is part of the file
+ * format — a kind is only ever appended. A `geo` value that is not in here is a
+ * custom silhouette the engine has no generator for; upload its path with
+ * {@link CommandWriter.setGeometry} instead.
+ */
+declare const GEO_KIND: Readonly<Record<string, number>>;
 /** Path opcodes; must match `mocanvas-geo::PathCmd`. */
 declare const PATH_OP: {
     readonly MOVE: 0;
@@ -51,7 +78,7 @@ interface CameraState {
 /** Floats per vertex in `FrameBuffers.vertices`: `x y u v r g b a`. */
 declare const VERTEX_FLOATS = 8;
 /** `u32` words per record in `FrameBuffers.batches`. */
-declare const BATCH_WORDS = 7;
+declare const BATCH_WORDS = 8;
 /** `u32` words per record in `FrameBuffers.overlay`. */
 declare const OVERLAY_WORDS = 10;
 /** Page-space clip rectangle `[minX, minY, maxX, maxY]`. */
@@ -64,10 +91,11 @@ interface FrameBuffers {
     vertices: Float32Array;
     indices: Uint32Array;
     /**
-     * `BATCH_WORDS` (7) words per batch: `firstIndex indexCount texture clipMinX
-     * clipMinY clipMaxX clipMaxY`. The clip words are f32 bits in page space; all
-     * four zero means unclipped. Texture 0 = solid color. A new batch starts
-     * whenever the texture or the clip rect changes — use `readBatch`.
+     * `BATCH_WORDS` (8) words per batch: `firstIndex indexCount texture clipMinX
+     * clipMinY clipMaxX clipMaxY isolate`. The clip words are f32 bits in page
+     * space; all four zero means unclipped. Texture 0 = solid color. A new batch
+     * starts whenever the texture, the clip rect or the isolation group changes —
+     * use `readBatch`.
      */
     batches: Uint32Array;
     /**
@@ -99,6 +127,16 @@ interface Batch {
     texture: number;
     /** Page-space clip rect, or undefined when unclipped. */
     clip?: ClipRect;
+    /**
+     * Isolation group, or 0 for an ordinary batch.
+     *
+     * Non-zero means the batch is one translucent shape's whole mark, and the
+     * backend has to paint each pixel of it once: the engine bakes opacity into
+     * vertex alpha, so a stroke that crosses itself would otherwise blend twice
+     * and show the crossing as a dark knot. The number is unique per frame and
+     * rises in draw order, which is what lets a backend tell two of them apart.
+     */
+    isolate: number;
 }
 interface OverlayEntry {
     handle: Handle;
@@ -155,6 +193,49 @@ declare class CommandWriter {
     remove(handle: Handle): void;
     /** `pathWords` is the flat f32 path encoding (opcode, args...). */
     setGeometry(handle: Handle, pathWords: ArrayLike<number>): void;
+    /**
+     * Build a built-in geo silhouette in the engine from its parameters.
+     *
+     * This is the fast path behind {@link CommandWriter.setGeometry} for the
+     * shapes the engine knows how to draw itself: five words go over the wire
+     * instead of a whole outline, and the trigonometry runs in WebAssembly. The
+     * resulting path is identical to the one the TypeScript generators produce.
+     *
+     * `kind` is an index from {@link GEO_KIND}. A silhouette that is not in that
+     * table has no generator here — send its path with `setGeometry`.
+     */
+    /**
+     * A built-in geo outline, generated by the engine from `(kind, w, h)`.
+     *
+     * `strokeWidth` reaches only the open marks drawn *inside* an outline — the X
+     * of an x-box — whose ends sit on the outline and would otherwise spike
+     * through it by half a stroke. The outline itself does not move with it.
+     */
+    setGeo(handle: Handle, kind: number, w: number, h: number, flags?: number, strokeWidth?: number): void;
+    /**
+     * A smooth cubic spline through `points` (interleaved `x, y`), built in the
+     * engine. `flags` takes {@link GEO_FLAG}.CLOSED.
+     */
+    setSpline(handle: Handle, points: ArrayLike<number>, flags?: number): void;
+    /**
+     * A polyline through `points` (interleaved `x, y`), or a polygon when
+     * `flags` has {@link GEO_FLAG}.CLOSED.
+     */
+    setPoly(handle: Handle, points: ArrayLike<number>, flags?: number): void;
+    private writePoints;
+    /**
+     * A freehand stroke, as the runs the pen actually made.
+     *
+     * Each segment is `{ points, freehand }` with `points` interleaved `x, y`; a
+     * `freehand` run is smoothed in the engine (one 1-2-1 pass, endpoints fixed)
+     * before the runs are concatenated into one outline. `flags` takes
+     * {@link GEO_FLAG}.CLOSED, which closes the stroke when it has more than two
+     * points.
+     */
+    setDraw(handle: Handle, segments: readonly {
+        points: ArrayLike<number>;
+        freehand: boolean;
+    }[], flags?: number): void;
     setStyle(handle: Handle, s: StyleWords): void;
     /** Set the fill texture of a shape (0 = solid fill). Independent of `setStyle`. */
     setTexture(handle: Handle, texture: number): void;
@@ -220,6 +301,20 @@ declare class EngineBridge {
     bounds(handle: Handle): [number, number, number, number] | null;
     /** Geometry page bounds `[minX, minY, maxX, maxY]` or null: `bounds` without the stroke pad. */
     geometryBounds(handle: Handle): [number, number, number, number] | null;
+    /**
+     * The outline a `dash: "draw"` shape is really drawn with, as path words, or
+     * `null` when the shape is missing or drawn in another style.
+     *
+     * The hand-drawn style strokes a perturbed, corner-rounded sketch rather than
+     * the shape's own geometry, so this is the only way for the host to trace what
+     * is on screen instead of what the maths says. It comes from the same call the
+     * renderer makes, so the two agree exactly.
+     *
+     * Copied out rather than handed over as a view: the engine's buffer is reused
+     * by the next call that writes to it, and a caller holding a view would find
+     * its contents replaced underneath.
+     */
+    sketchPath(handle: Handle): Float32Array | null;
     unionBounds(handles: ArrayLike<number>): [number, number, number, number] | null;
     /** Union of every shape's ink bounds, or null when the scene is empty. */
     allBounds(): [number, number, number, number] | null;
@@ -248,6 +343,15 @@ declare class EngineBridge {
 declare function loadEngine(input?: InitInput): Promise<EngineBridge>;
 /** Synchronous variant for tests / Node: pass the compiled bytes. */
 declare function loadEngineSync(bytes: SyncInitInput): EngineBridge;
+/**
+ * The engine created by the most recent `loadEngine` / `loadEngineSync`, or
+ * `null` if the module has never been loaded in this realm.
+ *
+ * `new Editor({...})` falls back to this when no `engine` is passed, which is
+ * what lets an app construct an editor without threading the bridge through
+ * its own code.
+ */
+declare function getLoadedEngine(): EngineBridge | null;
 declare function engineVersion(): string;
 
-export { BATCH_WORDS, type Batch, type CameraState, type ClipRect, CommandWriter, EngineBridge, FLAG, type FrameBuffers, HIT_FILTER, type Handle, OP, OVERLAY_WORDS, type OverlayEntry, PATH_OP, type StyleWords, VERTEX_FLOATS, bitsf32, engineVersion, f32bits, loadEngine, loadEngineSync, readClip };
+export { BATCH_WORDS, type Batch, type CameraState, type ClipRect, CommandWriter, EngineBridge, FLAG, type FrameBuffers, GEO_FLAG, GEO_KIND, HIT_FILTER, type Handle, OP, OVERLAY_WORDS, type OverlayEntry, PATH_OP, type StyleWords, VERTEX_FLOATS, bitsf32, engineVersion, f32bits, getLoadedEngine, loadEngine, loadEngineSync, readClip };

package/dist/index.js

@@ -8,8 +8,44 @@ var OP = {
   SET_GEOMETRY: 3,
   SET_STYLE: 4,
   CLEAR: 5,
-  SET_TEXTURE: 6
+  SET_TEXTURE: 6,
+  SET_GEO: 7,
+  SET_SPLINE: 8,
+  SET_POLY: 9,
+  SET_DRAW: 10
 };
+var GEO_FLAG = {
+  /** `setGeo`: mirror the silhouette left-to-right inside its own box. */
+  FLIP_X: 1 << 0,
+  /** `setGeo`: mirror the silhouette top-to-bottom inside its own box. */
+  FLIP_Y: 1 << 1,
+  /** `setSpline` / `setPoly` / `setDraw`: close the outline. */
+  CLOSED: 1 << 0,
+  /** `setDraw`, per segment: this run came from a pen, so smooth it. */
+  FREEHAND: 1 << 0
+};
+var GEO_KIND = Object.freeze({
+  rectangle: 0,
+  ellipse: 1,
+  triangle: 2,
+  diamond: 3,
+  pentagon: 4,
+  hexagon: 5,
+  octagon: 6,
+  star: 7,
+  rhombus: 8,
+  "rhombus-2": 9,
+  oval: 10,
+  trapezoid: 11,
+  "arrow-right": 12,
+  "arrow-left": 13,
+  "arrow-up": 14,
+  "arrow-down": 15,
+  "x-box": 16,
+  "check-box": 17,
+  cloud: 18,
+  heart: 19
+});
 var PATH_OP = {
   MOVE: 0,
   LINE: 1,
@@ -33,7 +69,7 @@ var HIT_FILTER = {
   HOLLOW_ONLY: 4
 };
 var VERTEX_FLOATS = 8;
-var BATCH_WORDS = 7;
+var BATCH_WORDS = 8;
 var OVERLAY_WORDS = 10;
 var scratchF32 = new Float32Array(1);
 var scratchU32 = new Uint32Array(scratchF32.buffer);
@@ -113,6 +149,90 @@ var CommandWriter = class {
     for (let k = 0; k < n; k++) v[i++] = f32bits(pathWords[k]);
     this.len = i;
   }
+  /**
+   * Build a built-in geo silhouette in the engine from its parameters.
+   *
+   * This is the fast path behind {@link CommandWriter.setGeometry} for the
+   * shapes the engine knows how to draw itself: five words go over the wire
+   * instead of a whole outline, and the trigonometry runs in WebAssembly. The
+   * resulting path is identical to the one the TypeScript generators produce.
+   *
+   * `kind` is an index from {@link GEO_KIND}. A silhouette that is not in that
+   * table has no generator here — send its path with `setGeometry`.
+   */
+  /**
+   * A built-in geo outline, generated by the engine from `(kind, w, h)`.
+   *
+   * `strokeWidth` reaches only the open marks drawn *inside* an outline — the X
+   * of an x-box — whose ends sit on the outline and would otherwise spike
+   * through it by half a stroke. The outline itself does not move with it.
+   */
+  setGeo(handle, kind, w, h, flags = 0, strokeWidth = 0) {
+    this.ensure(7);
+    const v = this.view;
+    let i = this.len;
+    v[i++] = OP.SET_GEO;
+    v[i++] = handle;
+    v[i++] = kind >>> 0;
+    v[i++] = flags >>> 0;
+    v[i++] = f32bits(w);
+    v[i++] = f32bits(h);
+    v[i++] = f32bits(strokeWidth);
+    this.len = i;
+  }
+  /**
+   * A smooth cubic spline through `points` (interleaved `x, y`), built in the
+   * engine. `flags` takes {@link GEO_FLAG}.CLOSED.
+   */
+  setSpline(handle, points, flags = 0) {
+    this.writePoints(OP.SET_SPLINE, handle, points, flags);
+  }
+  /**
+   * A polyline through `points` (interleaved `x, y`), or a polygon when
+   * `flags` has {@link GEO_FLAG}.CLOSED.
+   */
+  setPoly(handle, points, flags = 0) {
+    this.writePoints(OP.SET_POLY, handle, points, flags);
+  }
+  writePoints(op, handle, points, flags) {
+    const n = points.length >> 1;
+    this.ensure(4 + n * 2);
+    const v = this.view;
+    let i = this.len;
+    v[i++] = op;
+    v[i++] = handle;
+    v[i++] = flags >>> 0;
+    v[i++] = n;
+    for (let k = 0; k < n * 2; k++) v[i++] = f32bits(points[k]);
+    this.len = i;
+  }
+  /**
+   * A freehand stroke, as the runs the pen actually made.
+   *
+   * Each segment is `{ points, freehand }` with `points` interleaved `x, y`; a
+   * `freehand` run is smoothed in the engine (one 1-2-1 pass, endpoints fixed)
+   * before the runs are concatenated into one outline. `flags` takes
+   * {@link GEO_FLAG}.CLOSED, which closes the stroke when it has more than two
+   * points.
+   */
+  setDraw(handle, segments, flags = 0) {
+    let words = 4;
+    for (const seg of segments) words += 2 + (seg.points.length & -2);
+    this.ensure(words);
+    const v = this.view;
+    let i = this.len;
+    v[i++] = OP.SET_DRAW;
+    v[i++] = handle;
+    v[i++] = flags >>> 0;
+    v[i++] = segments.length;
+    for (const seg of segments) {
+      const n = seg.points.length >> 1;
+      v[i++] = seg.freehand ? GEO_FLAG.FREEHAND : 0;
+      v[i++] = n;
+      for (let k = 0; k < n * 2; k++) v[i++] = f32bits(seg.points[k]);
+    }
+    this.len = i;
+  }
   setStyle(handle, s) {
     this.ensure(8);
     const v = this.view;
@@ -229,7 +349,12 @@ var EngineBridge = class _EngineBridge {
   }
   /** Decode one batch record starting at word `offset` (a multiple of `BATCH_WORDS`). */
   static readBatch(batches, offset) {
-    const b = { firstIndex: batches[offset], indexCount: batches[offset + 1], texture: batches[offset + 2] };
+    const b = {
+      firstIndex: batches[offset],
+      indexCount: batches[offset + 1],
+      texture: batches[offset + 2],
+      isolate: batches[offset + 7]
+    };
     const clip = readClip(batches, offset + 3);
     if (clip) b.clip = clip;
     return b;
@@ -282,6 +407,24 @@ var EngineBridge = class _EngineBridge {
   geometryBounds(handle) {
     return this.engine.geometry_bounds(handle) ? this.readBox() : null;
   }
+  /**
+   * The outline a `dash: "draw"` shape is really drawn with, as path words, or
+   * `null` when the shape is missing or drawn in another style.
+   *
+   * The hand-drawn style strokes a perturbed, corner-rounded sketch rather than
+   * the shape's own geometry, so this is the only way for the host to trace what
+   * is on screen instead of what the maths says. It comes from the same call the
+   * renderer makes, so the two agree exactly.
+   *
+   * Copied out rather than handed over as a view: the engine's buffer is reused
+   * by the next call that writes to it, and a caller holding a view would find
+   * its contents replaced underneath.
+   */
+  sketchPath(handle) {
+    const n = this.engine.sketch_path(handle);
+    if (n === 0) return null;
+    return new Float32Array(this.memory.buffer, this.engine.f32_ptr(), n).slice();
+  }
   unionBounds(handles) {
     if (this.cmd.pending > 0) throw new Error("unionBounds called with unflushed commands");
     const n = handles.length;
@@ -354,17 +497,23 @@ async function loadEngine(input) {
     initPromise = input === void 0 ? loadDefault() : init({ module_or_path: input }).then((o) => o.memory);
   }
   const memory = await initPromise;
-  return new EngineBridge(new Engine(), memory);
+  currentEngine = new EngineBridge(new Engine(), memory);
+  return currentEngine;
 }
 function loadEngineSync(bytes) {
   const out = initSync({ module: bytes });
   initPromise = Promise.resolve(out.memory);
-  return new EngineBridge(new Engine(), out.memory);
+  currentEngine = new EngineBridge(new Engine(), out.memory);
+  return currentEngine;
+}
+var currentEngine = null;
+function getLoadedEngine() {
+  return currentEngine;
 }
 function engineVersion() {
   return version();
 }
 
-export { BATCH_WORDS, CommandWriter, EngineBridge, FLAG, HIT_FILTER, OP, OVERLAY_WORDS, PATH_OP, VERTEX_FLOATS, bitsf32, engineVersion, f32bits, loadEngine, loadEngineSync, readClip };
+export { BATCH_WORDS, CommandWriter, EngineBridge, FLAG, GEO_FLAG, GEO_KIND, HIT_FILTER, OP, OVERLAY_WORDS, PATH_OP, VERTEX_FLOATS, bitsf32, engineVersion, f32bits, getLoadedEngine, loadEngine, loadEngineSync, readClip };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map