@weasel-js/headless 1.15.0 → 1.15.1

package/README.md

@@ -1,11 +1,8 @@
 # @weasel-js/headless
 
-Component behavior with no substrate: what a DOM component and a canvas-drawn widget both run,
-each drawing it its own way. Today that is a list's roving highlight and typeahead, keyboard
-focus as one contract, and how a text field's edit ends. No React, no DOM.
-
-each drawing it its own way. Today that is a list's roving highlight and typeahead, a tree's
-expand and collapse keys, and keyboard focus as one contract. No React, no DOM.
+Render a weasel scene to pixels from Node — on a server, in a build script, in a CLI. The host
+runs core's `renderSceneToPixels` in a headless Chromium page, so the pixels come from the same
+WebGL2 renderer a browser draws with. Node itself has no WebGL2 binding the renderer can rely on.
 
 Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
 scene-graph canvas kit for React. See the
@@ -15,83 +12,59 @@ scene-graph canvas kit for React. See the
 
 ```sh
 npm install @weasel-js/headless
+npx playwright install chromium
 ```
 
+The second line downloads the Chromium the host launches. `playwright-core` comes with this
+package; the browser does not.
+
 ## Usage
 
 ```ts
-import { EMPTY_TYPEAHEAD, rovingKey, typeaheadStep } from '@weasel-js/headless';
-
-type Row = { name: string; heading?: boolean };
-const shape = { canStop: (r: Row) => !r.heading, label: (r: Row) => r.name };
-
-let at: number | null = null;
-let typed = EMPTY_TYPEAHEAD;
-
-function onKey(rows: readonly Row[], key: string): void {
-  const r = rovingKey(rows, at, key, shape);      // arrows, Home, End
-  if (r.handled) { at = r.at; return; }
-  if (key.length === 1) {
-    const t = typeaheadStep(rows, at, typed, key, Date.now(), shape);
-    typed = t.buffer;
-    if (t.hit !== null) at = t.hit;
-  }
+import { writeFile } from 'node:fs/promises';
+import { createNodeRasterHost } from '@weasel-js/headless';
+
+const host = createNodeRasterHost();
+try {
+  const { png } = await host.renderPng({
+    scene,                                   // a live Scene, or its toJSON() snapshot
+    sourceRect: { x: 0, y: 0, width: 800, height: 600 },
+    scale: { x: 2, y: 2 },
+    background: '#ffffff',
+  });
+  await writeFile('page.png', png);
+} finally {
+  await host.dispose();
 }
 ```
 
-A list's shape says which items the highlight can land on (`canStop`), which arrows move it
-(`orientation`, vertical by default, or `'both'` for all four), whether Left and Right swap for a
-right-to-left layout (`dir`), and whether it wraps at the ends (`wrap`, on by default).
-`@weasel-js/menu` runs every menu level on these.
-
-## Trees and rows
-
-`treeKey` is a tree's Right and Left, the WAI-ARIA way: Right opens a closed branch or steps to
-its first child, Left closes an open branch or steps to the parent. Its `TreeShape` says which
-items are branches, which are open, and which is whose child.
-
-`rowKey` is every key a list of rows answers, in one place: Cmd/Ctrl+A, the arrows with Home and
-End (Shift extends), a tree's Right and Left, Enter and Space, and typeahead. It returns what the
-key asks for (`selectAll`, `move`, `toggle`, `activate`, `type`) and the caller carries it out.
-`@weasel-js/ui`'s `useRowNavigation` runs on it.
-
-## Focus
-
-`FocusScope<T>` is keyboard focus over a set of targets, whatever draws them: which one is
-focused, whether its ring shows, `focus`, `moveFocus` through a `tabOrder`, and
-`subscribeFocus`. A `@weasel-js/hud` HUD is one over its widgets, and `@weasel-js/ui`'s
-`domFocusScope(root)` is one over the elements under `root`, so code that moves focus is
-written once for both. `tabSort` and `tabStep` are the order and the step both use.
-
-## Steps and sliders
-
-`arrowSteps`, `arrowMove` and `rangeKey` are what an arrow key asks for: one step, or `COARSE_STEPS`
-(ten) with Shift or a Page key, and Home and End for a range's ends. `sliderKey` turns one key into
-a thumb's next value, by step or by whole stops, across an endless end and inside its neighbors;
-`@weasel-js/ui`'s `Slider` runs on it.
+`render` returns the raw raster instead: `{ width, height, data }`, straight RGBA, top-down, the
+bytes `renderSceneToPixels` returns. `renderPng` encodes in the page through a 2D canvas, which
+stores premultiplied color, so a translucent pixel can move by a step; use `render` when the exact
+bytes matter.
 
-## Text fields
+Nothing launches until the first render. Every render after it reuses the page, its WebGL2 context
+and its compiled programs, so open one host for a batch and `dispose` it at the end (or hold it in
+`await using`). `dispose` closes the browser the host launched. Pass `browser` to render in one you
+launched yourself; the host then closes only its own page.
 
-`editEnd(cause, shape)` says how a text field's edit ends: Enter and blur commit, Escape cancels.
-A field's shape can make Escape commit too, and a `multiline` one leaves Shift+Enter to type a
-line break. Caret movement stays with each field: a DOM field gets it from the browser.
+## What crosses into the page
 
-## Reorder
+The scene and the arguments go as JSON. What `renderSceneToPixels` takes as a function stays
+behind: `drawOne`, `resolveImage`, `alphaFor` and `colorOverrides`. Nodes draw through the
+painters registered in the page, which by default are core's built-ins. A path's typed arrays
+are tagged on the way over (`tagTypedArrays` from `@weasel-js/geom`), so a snapshot saved that way
+passes as it is.
 
-Moving items within a list, whether it is drawn in the DOM or on a canvas. A destination is a gap counted before
-anything is taken out: 0 before the first item, `length` after the last. `moveItems(items, at, to)` moves the items at
-indices `at` into gap `to`; `isNoopDrop` says whether that leaves them where they are; `nudgeGap` is the gap a
-one-place move takes them to, and `nudgeOf` reads the Alt+arrow chord that asks for one. A pointer finds its gap by
-`gapByMidpoint`, for items side by side, each split at its middle, or by `nearestGap`, for gaps drawn at places of
-their own.
+The default page registers no fonts, so text draws nothing. To render text, or a paint kind or
+node shape of your own, bundle a page script that registers it and then imports
+`@weasel-js/headless/page`, as one classic script, and pass its source as `pageScript`.
 
-## Hold-to-repeat
+## Pixels and the browser's
 
-`createStepRepeat(step, spent, opts)` is a held stepper: `start(key)` steps once, then after
-`REPEAT_DELAY_MS` once every `REPEAT_EVERY_MS` until `stop()`, or until `spent(key)` says the value
-has nowhere left to go. Time comes from a `Scheduler` (`now`, and `set` returning a cancel), by
-default `timerScheduler`; pass your own to drive it from another clock or a test. `@weasel-js/ui`'s
-number field steppers and `@weasel-js/hud`'s menu number chips both hold through it.
+On one machine, the host's pixels equal the ones a page in Playwright's Chromium draws for the
+same scene: one WebGL2 implementation, given the same commands, draws the same bytes. Across GPUs
+and drivers they need not match, so don't compare a render against committed pixels.
 
 ## License
 

package/dist/chunk-36DNDFOQ.js

@@ -0,0 +1,15 @@
+import { tagTypedArrays, reviveTypedArrays } from '@weasel-js/geom';
+
+// src/protocol.ts
+var PAGE_GLOBAL = "__weaselHeadless";
+function sceneToWire(scene) {
+  const toJSON = scene.toJSON;
+  return tagTypedArrays(typeof toJSON === "function" ? toJSON.call(scene) : scene);
+}
+function sceneFromWire(wire) {
+  return reviveTypedArrays(wire);
+}
+
+export { PAGE_GLOBAL, sceneFromWire, sceneToWire };
+//# sourceMappingURL=chunk-36DNDFOQ.js.map
+//# sourceMappingURL=chunk-36DNDFOQ.js.map

package/dist/chunk-36DNDFOQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocol.ts"],"names":[],"mappings":";;;AAKO,IAAM,WAAA,GAAc;AAsCpB,SAAS,YAAY,KAAA,EAAuB;AACjD,EAAA,MAAM,SAAU,KAAA,CAA+B,MAAA;AAC/C,EAAA,OAAO,cAAA,CAAe,OAAO,MAAA,KAAW,UAAA,GAAa,OAAO,IAAA,CAAK,KAAK,IAAI,KAAK,CAAA;AACjF;AAGO,SAAS,cAAc,IAAA,EAAsB;AAClD,EAAA,OAAO,kBAAkB,IAAI,CAAA;AAC/B","file":"chunk-36DNDFOQ.js","sourcesContent":["// What crosses between Node and the page: JSON only, so pixels travel as base64. Typed here rather\n// than from core, whose types reach React and the DOM, neither of which a Node caller has.\nimport { reviveTypedArrays, tagTypedArrays } from '@weasel-js/geom';\n\n/** The page script's global, set once the script has run. */\nexport const PAGE_GLOBAL = '__weaselHeadless';\n\n/** `renderSceneToPixels`'s arguments that survive JSON: no `drawOne`, `resolveImage`, `alphaFor`\n *  or `colorOverrides`. Each means what it means there. */\nexport interface SerializableRenderArgs {\n  /** Scene-space rect to render. */\n  sourceRect: { x: number; y: number; width: number; height: number };\n  /** Output pixels per scene unit, per axis. */\n  scale: { x: number; y: number };\n  /** Background fill, any CSS color. Default: transparent. */\n  background?: string;\n  /** Max curve-flattening error in output pixels. Default 0.25. */\n  flattenTolerancePx?: number;\n  /** Draw commands over the scene in output-pixel space, as `renderSceneToPixels` takes them. */\n  overlay?: readonly object[];\n  /** Draw the scene's annotation layers. Default `false`. */\n  annotations?: boolean;\n}\n\nexport interface PageRequest extends SerializableRenderArgs {\n  /** A `scene.toJSON()` snapshot. */\n  scene: object;\n  screen?: readonly number[];\n  format: 'rgba' | 'png';\n}\n\nexport interface PageResult {\n  width: number;\n  height: number;\n  base64: string;\n}\n\nexport interface PageApi {\n  render(req: PageRequest): Promise<PageResult>;\n}\n\n/** A live scene or its snapshot, as JSON carries it: a path's typed arrays tagged, as\n *  `tagTypedArrays` writes them. A snapshot already saved that way passes through unchanged. */\nexport function sceneToWire(scene: object): object {\n  const toJSON = (scene as { toJSON?: unknown }).toJSON;\n  return tagTypedArrays(typeof toJSON === 'function' ? toJSON.call(scene) : scene) as object;\n}\n\n/** The snapshot `sceneToWire` sent, its typed arrays restored. */\nexport function sceneFromWire(wire: object): object {\n  return reviveTypedArrays(wire) as object;\n}\n"]}

package/dist/index.d.ts

@@ -1,326 +1,77 @@
-export { COARSE_STEPS } from '@weasel-js/quantity';
+import { Browser, LaunchOptions } from 'playwright-core';
 
-/** How a list that folds is read: which items are branches, which are open, and which item is whose child. */
-interface TreeShape<T> {
-    /** Whether `item` can open, its children shown or not. */
-    isBranch(item: T): boolean;
-    isOpen(item: T): boolean;
-    /** Whether `child` is one of `parent`'s own children. */
-    isChildOf(child: T, parent: T): boolean;
-    /** Whether a branch can open or close now. A disabled one can't. Default: every branch. */
-    canToggle?(item: T): boolean;
-    /** The inline direction the rows read in. Under `'rtl'` Left opens and Right closes. Default `'ltr'`. */
-    dir?: 'ltr' | 'rtl';
+/** `renderSceneToPixels`'s arguments that survive JSON: no `drawOne`, `resolveImage`, `alphaFor`
+ *  or `colorOverrides`. Each means what it means there. */
+interface SerializableRenderArgs {
+    /** Scene-space rect to render. */
+    sourceRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Output pixels per scene unit, per axis. */
+    scale: {
+        x: number;
+        y: number;
+    };
+    /** Background fill, any CSS color. Default: transparent. */
+    background?: string;
+    /** Max curve-flattening error in output pixels. Default 0.25. */
+    flattenTolerancePx?: number;
+    /** Draw commands over the scene in output-pixel space, as `renderSceneToPixels` takes them. */
+    overlay?: readonly object[];
+    /** Draw the scene's annotation layers. Default `false`. */
+    annotations?: boolean;
 }
-/** What Right or Left does on one item of a tree: open or close it, move the highlight, or nothing (`handled` false).
- *  `at` null is a key the tree takes without moving. */
-type TreeKeyResult = {
-    handled: false;
-} | {
-    handled: true;
-    toggle: number;
-} | {
-    handled: true;
-    at: number | null;
-};
-/**
- * Right and Left on the item at `at`, the WAI-ARIA tree way: Right opens a closed branch, else steps to its first
- * child; Left closes an open branch, else steps to the parent. Mirrored under `dir: 'rtl'`. `items` are the rows
- * shown, in drawn order.
- */
-declare function treeKey<T>(items: readonly T[], at: number, key: string, shape: TreeShape<T>): TreeKeyResult;
-
-/** How a list's items are read: which ones the highlight can land on, and which way its arrows run. */
-interface ListShape<T> {
-    /** Whether the highlight can land on `item`. A separator or a heading can't. Default: every item. */
-    canStop?(item: T): boolean;
-    /** Which arrow keys move the highlight. `'both'` answers to all four, the way a radio group does. Default `'vertical'`. */
-    orientation?: 'vertical' | 'horizontal' | 'both';
-    /** The inline direction the items are laid out in. Under `'rtl'` Left steps forward and Right back. Default `'ltr'`. */
-    dir?: 'ltr' | 'rtl';
-    /** An arrow past either end comes round to the other. Default true. */
-    wrap?: boolean;
-}
-/** Index of the first item the highlight can land on, or null for a list with none. */
-declare function firstStop<T>(items: readonly T[], shape?: ListShape<T>): number | null;
-/** The next item the highlight can land on from `from` in direction `dir`; from `null`, the first or last.
- *  Without wrap, an end stays where it is. Null for a list with no such item. */
-declare function stepStop<T>(items: readonly T[], from: number | null, dir: 1 | -1, shape?: ListShape<T>): number | null;
-/** What one key does to a list's highlight. `handled` false for a key that is not the list's to move. */
-type RovingResult = {
-    handled: false;
-} | {
-    handled: true;
-    at: number | null;
-};
-/** Move the highlight `at` by one key: the arrows along the list's orientation, Home and End. */
-declare function rovingKey<T>(items: readonly T[], at: number | null, key: string, shape?: ListShape<T>): RovingResult;
-/** A key as {@link rowKey} reads it: the key and the modifiers held. */
-interface KeyPress {
-    key: string;
-    shiftKey?: boolean;
-    ctrlKey?: boolean;
-    metaKey?: boolean;
-    altKey?: boolean;
-}
-/** A list of rows, and which of the keys past the arrows its caller answers. */
-interface RowKeysShape<T> extends ListShape<T> {
-    /** Set for a list that folds: Right and Left open, close, and walk it ({@link treeKey}). */
-    tree?: TreeShape<T>;
-    /** Cmd/Ctrl+A selects every row. */
-    selectAll?: boolean;
-    /** Enter and Space activate a row. */
-    activate?: boolean;
-    /** Typing a character searches the rows' text. */
-    typeahead?: boolean;
-}
-/** What one key on a row asks for, for the caller to carry out. */
-type RowKeyAction = 
-/** Select every row. */
-{
-    kind: 'selectAll';
-}
-/** Move to row `at`, extending a range from the anchor when `extend`. `at` null takes the key without moving. */
- | {
-    kind: 'move';
-    at: number | null;
-    extend: boolean;
-}
-/** Open or close the branch at `at`. */
- | {
-    kind: 'toggle';
-    at: number;
-} | {
-    kind: 'activate';
-}
-/** Hand the key to typeahead. `held` when the key is the list's whether or not the search finds a row. */
- | {
-    kind: 'type';
-    held: boolean;
-};
-/**
- * What a key on row `at` of a list of rows does, in the order the keys are tried: Cmd/Ctrl+A, the arrows with Home
- * and End (Shift to extend), a tree's Right and Left, a space typed mid-search, Enter or Space to activate, then any
- * other character to search. `searching` says a typeahead search is under way. Null for a key that is not the list's.
- */
-declare function rowKey<T>(items: readonly T[], at: number, press: KeyPress, shape?: RowKeysShape<T>, searching?: boolean): RowKeyAction | null;
-
-/** How typeahead reads a list: its shape, and the text each item is found by. */
-interface TypeaheadShape<T> extends Pick<ListShape<T>, 'canStop'> {
-    label(item: T): string;
-}
-/** How long typing can pause before the typeahead buffer starts over, in milliseconds. */
-declare const TYPEAHEAD_RESET_MS = 500;
-/** What has been typed so far, and when the last key came. */
-interface TypeaheadBuffer {
-    text: string;
-    at: number;
-}
-/** A buffer nothing has been typed into. */
-declare const EMPTY_TYPEAHEAD: TypeaheadBuffer;
-/** The item a typed `query` lands on, searching forward from `from` with
- *  wrap. A one-letter query starts after the highlight so repeating a letter
- *  cycles; a longer one starts at it so typing on keeps the match. */
-declare function typeaheadMatch<T>(items: readonly T[], from: number | null, query: string, shape: TypeaheadShape<T>): number | null;
-/** One typed character: the new buffer and the item it lands on. A key that
- *  repeats the whole buffer searches that one letter, so it cycles. */
-declare function typeaheadStep<T>(items: readonly T[], from: number | null, buffer: TypeaheadBuffer, key: string, now: number, shape: TypeaheadShape<T>, resetMs?: number): {
-    buffer: TypeaheadBuffer;
-    hit: number | null;
-};
 
-/** How a focus change came about. */
-interface FocusScopeOptions {
-    /** Whether the target shows its focus ring: the scope's `:focus-visible`. Keyboard moves show one, a press does
-     *  not. Default `false` for {@link FocusScope.focus}, `true` for {@link FocusScope.moveFocus}. */
-    readonly visible?: boolean;
-}
-/**
- * Keyboard focus over a set of targets, whatever draws them: a HUD's widgets and a DOM subtree's elements both
- * answer it, so code that moves or reads focus is written once for either.
- */
-interface FocusScope<T> {
-    /** The target holding keyboard focus, or null. One per scope. */
-    readonly focused: T | null;
-    /** Whether the focused target shows its focus ring. */
-    readonly focusVisible: boolean;
-    /** Focus `target`, or blur with `null`. Returns whether `target` now holds focus: false when it is not in this
-     *  scope or cannot take focus, and focus is then unchanged. */
-    focus(target: T | null, options?: FocusScopeOptions): boolean;
-    /** Move focus one step through {@link tabOrder}. From nothing, `'next'` lands on the first target and `'prev'` on
-     *  the last; past either end the scope blurs and returns null, which is where focus leaves it. */
-    moveFocus(direction: 'next' | 'prev', options?: FocusScopeOptions): T | null;
-    /** The targets Tab visits, in order. */
-    tabOrder(): T[];
-    /** Run `fn` whenever the focused target changes. Returns an unsubscribe. */
-    subscribeFocus(fn: (focused: T | null) => void): () => void;
-}
-/** Tab order: targets that declare a place come first, ascending, then the rest in the order given. In the DOM a
- *  positive `tabindex` declares one and `0` does not. */
-declare function tabSort<T>(targets: readonly T[], declared: (target: T) => number | undefined): T[];
-/** The target one Tab step from `from` through `order`, or null past either end. From nothing, `'next'` is the
- *  first and `'prev'` the last. A `from` that is out of the order (hidden since it took focus, say) steps from where
- *  it sits, which `isBefore` says; without it, such a `from` steps as nothing does. */
-declare function tabStep<T>(order: readonly T[], from: T | null, direction: 'next' | 'prev', isBefore?: (a: T, b: T) => boolean): T | null;
-
-/** Steps an arrow key asks for along one axis: one, or {@link COARSE_STEPS} with Shift, positive
- *  toward ArrowRight and ArrowUp. Under `'rtl'` ArrowLeft and ArrowRight swap, as a native range
- *  input's do. `null` for any other key. A caller multiplies by its own step. */
-declare function arrowSteps(key: string, shift: boolean, dir?: 'ltr' | 'rtl'): number | null;
-/** Steps an arrow key asks for on a plane, in screen axes: `dy` is positive toward ArrowDown.
- *  One step, or {@link COARSE_STEPS} with Shift; `null` for any other key. */
-declare function arrowMove(key: string, shift: boolean): {
-    dx: number;
-    dy: number;
-} | null;
-/** What a key does along a range: {@link arrowSteps}, the Page keys ({@link COARSE_STEPS} steps),
- *  or Home and End (an end of the range). `null` for any other key. */
-declare function rangeKey(key: string, shift: boolean, dir?: 'ltr' | 'rtl'): number | 'home' | 'end' | null;
-
-/** A value on a slider's track the thumb can come to rest on, with whatever label draws under it. */
-interface SliderStop<L = unknown> {
-    value: number;
-    label?: L;
-}
-/** The stops that are actually reachable: inside the range, deduped, ascending.
- *  A duplicate keeps the first label given for its value. */
-declare function usableStops<L>(stops: readonly (number | SliderStop<L>)[] | undefined, min: number, max: number): SliderStop<L>[];
-/** The stop nearest `v` along the track, or `v` itself when none lies within
- *  `tolerance` (a track fraction). Measured on the track rather than in value
- *  units so evenly spaced stops attract over the same distance. */
-declare function attract(v: number, stops: readonly number[], tolerance: number, toFraction: (v: number) => number): number;
-/** Keep thumb `index` strictly between its neighbors: a step apart, or a thousandth of the span without one. */
-declare function clampOrdered(v: number, thumbs: readonly {
-    value: number;
-}[], index: number, min: number, max: number, step: number | undefined): number;
-/** What a key press on one thumb of a slider reads. */
-interface SliderKeyShape {
-    thumbs: readonly {
-        value: number;
-    }[];
-    /** The thumb the key went to. */
-    index: number;
-    /** The ends of the track. */
-    min: number;
-    max: number;
-    step?: number;
-    /** Usable stops, ascending. With any, a keystroke moves by whole stops rather than by value. */
-    stops?: readonly number[];
-    /** Keep the thumb between its neighbors. */
-    ordered?: boolean;
-    /** The finite range, where the track runs past it to an endless end's stop. Default the track. */
-    range?: readonly [number, number];
-    /** Under `'rtl'` the horizontal arrows are mirrored, as the values run from the right end. */
-    dir?: 'ltr' | 'rtl';
-    /** This thumb's own limits inside the track. Read only for a key the slider answers to. */
-    bounds?(): readonly [number, number];
-    /** Where the thumb lands `steps` presses away, for a track whose values aren't what the user counts in. */
-    keyStep?(steps: number): number;
-}
-/** The value one key moves thumb `index` to: arrows by a step (ten with Shift), the Page keys by ten,
- *  Home and End to the thumb's ends. `null` for a key the slider does not answer to. */
-declare function sliderKey(key: string, shift: boolean, shape: SliderKeyShape): number | null;
-
-/** How a text field's edit ends: `'commit'` writes what was typed, `'cancel'` drops it and puts back what was there. */
-type EditEnd = 'commit' | 'cancel';
-/** What a field varies in how its edit ends: what Escape does (`'cancel'` by default), and whether the field holds
- *  more than one line, which leaves Shift+Enter to type a line break rather than commit. */
-interface EditEndShape {
-    escape?: EditEnd;
-    multiline?: boolean;
-}
-/** What may end an edit: a key, with whether Shift is held, or the field losing focus. A key {@link imeKey} claims is
- *  the caller's to hold back. */
-type EditCause = 'blur' | {
-    key: string;
-    shift?: boolean;
-};
-/** How `cause` ends a text field's edit, or null when it leaves the edit open. Enter and blur commit, Escape cancels
- *  unless `shape` says otherwise. */
-declare function editEnd(cause: EditCause, shape?: EditEndShape): EditEnd | null;
-/** A keydown as the platform reports it, enough to tell whether an input method owns it. */
-interface KeySource {
-    key: string;
-    isComposing?: boolean;
-    keyCode?: number;
-}
-/** Whether a keydown belongs to an input method, which a field must leave alone: Enter there confirms a candidate and
- *  Escape dismisses them. Safari sends the Enter that ends a composition with `isComposing` already false, but with
- *  `keyCode` 229. */
-declare function imeKey(e: KeySource): boolean;
-
-/**
- * Moving items within an ordered list. A destination is a gap, counted before anything is taken out: 0 before the
- * first item, `length` after the last, and `i` between `items[i - 1]` and `items[i]` — the gap a UI marks while it
- * carries something. The items moved are named by their indices, so a selection of several moves in one go.
- */
-/** `items` with the items at indices `at` taken out and put back, in their order, in gap `to`. */
-declare function moveItems<T>(items: readonly T[], at: readonly number[], to: number): T[];
-/** The index the first of the items at `at` holds once {@link moveItems} has put them in gap `to`. */
-declare function movedIndex(at: readonly number[], to: number): number;
-/** Whether putting the items at `at` in gap `to` leaves them where they are: a contiguous run dropped in a gap at
- *  either of its ends or inside it. False for no items. */
-declare function isNoopDrop(at: readonly number[], to: number): boolean;
-/** The gap a one-place move sends the items at `at` to: before the item ahead of the first (`by` -1), or after the
- *  item past the last (`by` 1). Null where that runs off either end of a list `length` long, or for no items. */
-declare function nudgeGap(at: readonly number[], by: -1 | 1, length: number): number | null;
-/**
- * The gap a point `p` along a line of items falls in, where each item splits at its middle: how many of the
- * middles `mids`, given in item order, `p` has reached. A line whose middles run backward, as a right-to-left row
- * does along x, counts the other way. For items that sit side by side — rows, tabs, chips.
- */
-declare function gapByMidpoint(mids: readonly number[], p: number): number;
-/** Which of the gaps at positions `gaps` along a line is nearest `p`, as an index into `gaps`; -1 for none. For
- *  gaps drawn at places of their own, between items set apart however the layout put them: picking the nearest
- *  keeps the gap chosen the one whose mark is drawn closest. */
-declare function nearestGap(gaps: readonly number[], p: number): number;
-/** The keys and modifiers a nudge chord reads off a keystroke. */
-interface NudgeKey {
-    key: string;
-    altKey: boolean;
-    ctrlKey: boolean;
-    metaKey: boolean;
-}
-/** Alt with neither Ctrl nor Cmd held: the chord that moves an item instead of moving focus. */
-declare function isNudgeChord(e: NudgeKey): boolean;
-/** Which way the nudge chord moves an item: `-1` for Alt+`back`, `1` for Alt+`on`, `null` for any other key.
- *  The keys are Up and Down unless named. */
-declare function nudgeOf(e: NudgeKey, back?: string, on?: string): -1 | 1 | null;
-
-/** Clock and timer, injected so tests and hosts control time. */
-interface Scheduler {
-    now(): number;
-    /** Run `fn` after `ms`; returns a cancel. */
-    set(fn: () => void, ms: number): () => void;
-}
-/** The real-time scheduler: `Date.now` and `setTimeout`. */
-declare const timerScheduler: Scheduler;
-
-/** How long a held stepper waits before it repeats, in milliseconds. */
-declare const REPEAT_DELAY_MS = 400;
-/** How often a held stepper steps once it repeats, in milliseconds. */
-declare const REPEAT_EVERY_MS = 60;
-/** The timing of a {@link createStepRepeat}. Each is read when it is next used, so a getter can change it mid-hold. */
-interface StepRepeatOptions {
-    /** Default {@link REPEAT_DELAY_MS}. */
-    delayMs?: number;
-    /** Default {@link REPEAT_EVERY_MS}. */
-    everyMs?: number;
-    /** Default {@link timerScheduler}. */
-    scheduler?: Pick<Scheduler, 'set'>;
-}
-/** A held stepper: {@link createStepRepeat}. */
-interface StepRepeat<K> {
-    /** Step `key` once now, then after the delay once every interval until {@link stop}. Replaces any hold. */
-    start(key: K): void;
-    stop(): void;
-    /** The key being held, or null. */
-    held(): K | null;
+/** Where a {@link NodeRasterHost} renders. */
+interface NodeRasterHostOptions {
+    /** A browser to render in, which the host leaves open on `dispose`. Default: the host launches
+     *  Playwright's Chromium on its first render and closes it on `dispose`. */
+    browser?: Browser;
+    /** Launch options for the Chromium the host starts. Ignored with `browser`. */
+    launch?: LaunchOptions;
+    /** The page script's source: one classic script that imports `@weasel-js/headless/page`.
+     *  Default: that module bundled alone (`dist/page.global.js`). Bundle your own to register
+     *  fonts, paint kinds or node shapes before the first render. */
+    pageScript?: string;
+}
+/** Straight RGBA, top-down, 4 bytes a pixel: core's `RasterImage`. */
+interface RasterImage {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}
+/** One render: `renderSceneToPixels`'s arguments, the scene as JSON and no function-valued fields. */
+interface NodeRenderArgs extends SerializableRenderArgs {
+    /** A live `Scene`, or its `toJSON()` snapshot, raw or saved through `tagTypedArrays`. A scene
+     *  whose nodes name registry functions (`clipFromPose` and the like) cannot be read back in the
+     *  page. */
+    scene: object;
+    /** Screen space → output pixels, as `renderSceneToPixels`'s `screen` (nine numbers, column-major). */
+    screen?: ArrayLike<number>;
+}
+/** A Chromium page holding one raster session, kept across renders. */
+interface NodeRasterHost {
+    /** Render to straight RGBA, top-down, as `renderSceneToPixels` returns it. Rejects once disposed. */
+    render(args: NodeRenderArgs): Promise<RasterImage>;
+    /** Render and encode as PNG. The page encodes through a 2D canvas, which stores premultiplied
+     *  color, so a translucent pixel's color can move by a step; `render` returns the exact bytes. */
+    renderPng(args: NodeRenderArgs): Promise<{
+        width: number;
+        height: number;
+        png: Uint8Array;
+    }>;
+    /** Close the page, and the browser when the host launched it. Idempotent. */
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
 }
 /**
- * Hold-to-repeat stepping, whatever draws the stepper: `step` moves the value by `key`, and `spent` says `key`
- * has nowhere left to go, which ends the hold. Both are called at the moment of each step.
+ * Open a host that renders scenes to pixels from Node, through `renderSceneToPixels` in a headless
+ * Chromium page. Nothing launches until the first render; every render after it reuses the page,
+ * its WebGL2 context and its GPU caches.
  */
-declare function createStepRepeat<K>(step: (key: K) => void, spent: (key: K) => boolean, opts?: StepRepeatOptions): StepRepeat<K>;
+declare function createNodeRasterHost(options?: NodeRasterHostOptions): NodeRasterHost;
 
-export { EMPTY_TYPEAHEAD, type EditCause, type EditEnd, type EditEndShape, type FocusScope, type FocusScopeOptions, type KeyPress, type KeySource, type ListShape, type NudgeKey, REPEAT_DELAY_MS, REPEAT_EVERY_MS, type RovingResult, type RowKeyAction, type RowKeysShape, type Scheduler, type SliderKeyShape, type SliderStop, type StepRepeat, type StepRepeatOptions, TYPEAHEAD_RESET_MS, type TreeKeyResult, type TreeShape, type TypeaheadBuffer, type TypeaheadShape, arrowMove, arrowSteps, attract, clampOrdered, createStepRepeat, editEnd, firstStop, gapByMidpoint, imeKey, isNoopDrop, isNudgeChord, moveItems, movedIndex, nearestGap, nudgeGap, nudgeOf, rangeKey, rovingKey, rowKey, sliderKey, stepStop, tabSort, tabStep, timerScheduler, treeKey, typeaheadMatch, typeaheadStep, usableStops };
+export { type NodeRasterHost, type NodeRasterHostOptions, type NodeRenderArgs, type RasterImage, type SerializableRenderArgs, createNodeRasterHost };