@driftengine/ui2d 3.62.0 → 4.0.0

package/NOTICE

@@ -7,3 +7,23 @@ This product includes software developed at Drift Technologies
 Licensed under the Apache License, Version 2.0. Section 4(d) of that licence
 requires this NOTICE to be reproduced in any derivative work you distribute,
 in the source, the documentation, or a display generated by the work.
+
+Models run by DriftCapture
+--------------------------
+DriftCapture runs the models below. Their weights are not in this repository
+and are not distributed with it: tools/capture-weights/ fetches each at the
+revision its manifest pins, verifies it, and converts it, and a game that
+ships one ships it under that model's own licence. Each model's definition in
+this engine is written from its project's published code.
+
+- Depth Anything 3 Small and Depth Anything 3 Base. Apache License 2.0.
+  Copyright (c) 2025 ByteDance Ltd. and/or its affiliates.
+- Depth Anything V2 Small. Apache License 2.0. The University of Hong Kong
+  and TikTok; converted to the Transformers layout by The HuggingFace Team.
+- MobileSAM. Apache License 2.0. Its image encoder is TinyViT, Copyright (c)
+  2022 Microsoft; its prompt encoder and mask decoder are Segment Anything's,
+  Copyright (c) Meta Platforms, Inc. and affiliates.
+- SAM 2.1 tiny. Apache License 2.0. Copyright (c) Meta Platforms, Inc. and
+  affiliates.
+- OWLv2 base patch16. Apache License 2.0. Copyright 2023 Google AI and The
+  HuggingFace Team.

package/README.md

@@ -2,7 +2,7 @@
 
 The 2D layer: quads with a texture on them, batched, in the order you drew them.
 
-**Cost: 8.4 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it
+**Cost: 8.7 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it
 drifts more than 3% — the number is derived from the same floors that gate asserts, so a README
 quoting a stale one is a red suite rather than a thing somebody notices.
 
@@ -119,6 +119,33 @@ decodes and the pass's own output transform re-encodes, so the blend happens in
 `filter` defaults to `nearest`, because a sheet is usually pixel art and linear filtering is the
 thing that makes pixel art look wrong.
 
+### Type in an atlas wants `mipmap: true`
+
+`mipmap` defaults to false, which is right for pixel art: a chain is memory nothing samples, and at
+a distance it dissolves art whose whole point is the pixel. **A glyph page is the sheet where that
+default is wrong.** Bake one page at 96 px, draw body copy at 11, and that is a 7x minification:
+`linear` reads four texels out of a footprint covering dozens, so a `t` crossbar two texels tall
+lands on about a quarter of a pixel and survives or not depending on where the sample falls. A
+player reported it as `Step-In Uppercut` reading `Slep-In Uppercul`, with the same letter surviving
+in one word and not the next, so the line looked unevenly spaced as well as misread.
+
+```ts
+sprites.setTexture(0, glyphPage, { filter: 'linear', mipmap: true });
+```
+
+Measured on `demo/dev/glyphMip.ts`, twelve copies of one glyph at different subpixel offsets: the
+ink varies between copies with a standard deviation of **0.0130** plain and **0.0020** mipmapped, so
+**6.6x less** copy-to-copy disagreement, identical on both backends. `scripts/glyph-mip-check.mjs`
+is that measurement as a gate.
+
+With `filter: 'linear'` this is trilinear. With `filter: 'nearest'` the levels are still blended,
+because that is minification and `filter` is about magnification.
+
+**Pad the cells yourself.** A lower level mixes texels the packer put next to each other, so a sheet
+whose frames touch shows its neighbours once the chain is deep enough to reach them. How much
+padding depends on how far down the sheet is ever sampled, which is a fact about the sheet rather
+than about the sampler — the engine cannot size it for you.
+
 **Neither backend flips the image.** `surfaceTexture.ts` in core carries the whole argument and the
 bug it came from: WebGL2 ignores `UNPACK_FLIP_Y_WEBGL` for an `ImageBitmap` and honours it for a
 canvas, so a pipeline checked with one source type is half checked. `scripts/sprite-check.mjs`

package/dist/a11y.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The interface tree in the shape assistive technology needs, and the seam that publishes it.
+ *
+ * **A seam, because whether anything can receive this is the host's business.** A browser host can
+ * mirror the tree into a hidden structure that a screen reader walks. A native host may have a
+ * platform accessibility service, or may have nothing — and `createNullA11yHost` is the honest
+ * answer in that case rather than an absence nobody noticed.
+ */
+import type { UiNode } from './uiNode.ts';
+export interface A11yNode {
+    role: string;
+    label: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    focused: boolean;
+}
+export interface A11yHost {
+    publish(nodes: readonly A11yNode[], count: number): void;
+}
+/** A host that accepts a tree and does nothing with it. See the header. */
+export declare function createNullA11yHost(): A11yHost;
+/** Fill `out` with every node worth describing, in tree order. Returns how many. */
+export declare function a11yTree(root: UiNode, out: A11yNode[]): number;

package/dist/a11y.js

@@ -0,0 +1,48 @@
+/** A host that accepts a tree and does nothing with it. See the header. */
+export function createNullA11yHost() {
+    return { publish() { } };
+}
+/**
+ * What role this node plays, derived rather than declared.
+ *
+ * Derived, because a role a caller has to set is a role most callers will not set, and an
+ * accessibility tree that is mostly unlabelled is worse than none: it reads as though the interface
+ * has been described when it has not.
+ */
+function roleOf(node) {
+    if (node.focusable && node.children.length === 0)
+        return 'button';
+    if (node.clip && (node.contentSpanX > node.rect.w || node.contentSpanY > node.rect.h)) {
+        return 'scrollable';
+    }
+    return 'text';
+}
+function contributes(node) {
+    return node.interactive || node.focusable || node.text.length > 0;
+}
+function gather(node, out, at) {
+    if (node.hidden)
+        return at;
+    let next = at;
+    if (contributes(node)) {
+        const slot = out[next] ?? { role: '', label: '', x: 0, y: 0, w: 0, h: 0, focused: false };
+        slot.role = roleOf(node);
+        slot.label = node.text;
+        slot.x = node.rect.x;
+        slot.y = node.rect.y;
+        slot.w = node.rect.w;
+        slot.h = node.rect.h;
+        slot.focused = false;
+        out[next] = slot;
+        next += 1;
+    }
+    for (const child of node.children)
+        next = gather(child, out, next);
+    return next;
+}
+/** Fill `out` with every node worth describing, in tree order. Returns how many. */
+export function a11yTree(root, out) {
+    const count = gather(root, out, 0);
+    out.length = count;
+    return count;
+}

package/dist/index.d.ts

@@ -28,3 +28,24 @@ export type { UiContentSink } from './uiDraw.ts';
 export { uiFocusNext, uiFocusOrder, uiFocusPrevious, uiHitTest } from './uiFocus.ts';
 export { createUiInput, resetUiInput, routeUiKey, routeUiPointer, setUiFocus } from './uiInput.ts';
 export type { UiInput } from './uiInput.ts';
+export { clipRectFor, intersectClip } from './uiClip.ts';
+export { clampScroll, routeScrollWheel, scrollBy, scrollExtent } from './uiScroll.ts';
+export { layerOrder } from './uiLayer.ts';
+export { SLICE_STRIDE, sliceInto } from './uiSlice.ts';
+export type { SliceInset } from './uiSlice.ts';
+export { createTextModel, deleteBackward, deleteForward, insertText, moveCaret, moveToLineEdge, selectAll, selectedText, selectionRange, } from './textModel.ts';
+export type { TextModel } from './textModel.ts';
+export { applyComposition, createNullTextHost } from './textHost.ts';
+export type { TextHost } from './textHost.ts';
+export { runsFor } from './richText.ts';
+export type { TextRun } from './richText.ts';
+export { visibleRange, visibleRangeVariable } from './virtualList.ts';
+export type { RowWindow } from './virtualList.ts';
+export { createTheme, deriveTheme, themeColour, themeRgba, themeSize, unpackRgba, } from './theme.ts';
+export type { Theme } from './theme.ts';
+export { clearDirty, createDirtyTracker, diffTree, dirtyBounds, markDirty } from './uiDirty.ts';
+export type { DirtyTracker } from './uiDirty.ts';
+export { beginDrag, capturePointer, createPointerState, dropTarget, endDrag, pointerTarget, releasePointer, } from './uiPointer.ts';
+export type { PointerState } from './uiPointer.ts';
+export { a11yTree, createNullA11yHost } from './a11y.ts';
+export type { A11yHost, A11yNode } from './a11y.ts';

package/dist/index.js

@@ -19,3 +19,22 @@ export { layoutUiTree } from './uiLayout.js';
 export { drawUiTree } from './uiDraw.js';
 export { uiFocusNext, uiFocusOrder, uiFocusPrevious, uiHitTest } from './uiFocus.js';
 export { createUiInput, resetUiInput, routeUiKey, routeUiPointer, setUiFocus } from './uiInput.js';
+/*
+ * The interface framework: what an editor needs from a 2D layer and a game's interface wants too.
+ *
+ * Every platform touch below is a capability the caller supplies — `TextHost` for composition and
+ * the clipboard, `A11yHost` for assistive technology — because this has to run under a host with
+ * no document object model. That is the same rule `AGENTS.md` already applies to persistence.
+ */
+export { clipRectFor, intersectClip } from './uiClip.js';
+export { clampScroll, routeScrollWheel, scrollBy, scrollExtent } from './uiScroll.js';
+export { layerOrder } from './uiLayer.js';
+export { SLICE_STRIDE, sliceInto } from './uiSlice.js';
+export { createTextModel, deleteBackward, deleteForward, insertText, moveCaret, moveToLineEdge, selectAll, selectedText, selectionRange, } from './textModel.js';
+export { applyComposition, createNullTextHost } from './textHost.js';
+export { runsFor } from './richText.js';
+export { visibleRange, visibleRangeVariable } from './virtualList.js';
+export { createTheme, deriveTheme, themeColour, themeRgba, themeSize, unpackRgba, } from './theme.js';
+export { clearDirty, createDirtyTracker, diffTree, dirtyBounds, markDirty } from './uiDirty.js';
+export { beginDrag, capturePointer, createPointerState, dropTarget, endDrag, pointerTarget, releasePointer, } from './uiPointer.js';
+export { a11yTree, createNullA11yHost } from './a11y.js';

package/dist/richText.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Overlapping style runs, normalised into disjoint ones that cover every character once.
+ *
+ * **The normalisation is the whole job.** A syntax highlighter emits overlapping runs — a rule for
+ * the string, a more specific one for the escape inside it — and a renderer needs disjoint runs in
+ * order with no gaps. Every consumer that skips this step draws a character twice or not at all,
+ * and both look like a font problem.
+ *
+ * **Later wins the overlap**, because a later rule is the more specific one in every highlighter
+ * that emits them in that order.
+ */
+export interface TextRun {
+    from: number;
+    to: number;
+    colour: number;
+    bold: boolean;
+    italic: boolean;
+}
+/**
+ * Fill `out` with disjoint, ordered, gap-free runs covering `[0, text.length)`.
+ *
+ * Returns how many were written. With no input runs the answer is one run covering everything,
+ * which is what a plain string is.
+ */
+export declare function runsFor(text: string, runs: readonly TextRun[], out: TextRun[]): number;

package/dist/richText.js

@@ -0,0 +1,49 @@
+/* Reused across calls: this runs per frame for a visible document. */
+const BOUNDS = [];
+/**
+ * Fill `out` with disjoint, ordered, gap-free runs covering `[0, text.length)`.
+ *
+ * Returns how many were written. With no input runs the answer is one run covering everything,
+ * which is what a plain string is.
+ */
+export function runsFor(text, runs, out) {
+    const end = text.length;
+    if (end === 0)
+        return 0;
+    BOUNDS.length = 0;
+    BOUNDS.push(0, end);
+    for (const run of runs) {
+        const from = Math.max(0, Math.min(end, run.from));
+        const to = Math.max(0, Math.min(end, run.to));
+        if (to > from)
+            BOUNDS.push(from, to);
+    }
+    BOUNDS.sort((a, b) => a - b);
+    let count = 0;
+    let previous = -1;
+    for (let i = 0; i < BOUNDS.length - 1; i += 1) {
+        const from = BOUNDS[i];
+        const to = BOUNDS[i + 1];
+        if (from === to || from === previous)
+            continue;
+        previous = from;
+        /* Last covering run wins; none covering means the default, which is what index -1 encodes. */
+        let chosen = -1;
+        for (let r = 0; r < runs.length; r += 1) {
+            const run = runs[r];
+            if (run.from <= from && run.to >= to)
+                chosen = r;
+        }
+        const style = chosen === -1 ? null : runs[chosen];
+        const slot = out[count] ?? { from: 0, to: 0, colour: 0xffffffff, bold: false, italic: false };
+        slot.from = from;
+        slot.to = to;
+        slot.colour = style?.colour ?? 0xffffffff;
+        slot.bold = style?.bold ?? false;
+        slot.italic = style?.italic ?? false;
+        out[count] = slot;
+        count += 1;
+    }
+    out.length = count;
+    return count;
+}

package/dist/spriteGl.js

@@ -97,9 +97,21 @@ export function setWebgl2SpriteTexture(gl, sprites, slot, source, options) {
     gl.bindTexture(gl.TEXTURE_2D, texture);
     const internal = options.colorSpace === 'linear' ? gl.RGBA : gl.SRGB8_ALPHA8;
     gl.texImage2D(gl.TEXTURE_2D, 0, internal, gl.RGBA, gl.UNSIGNED_BYTE, source);
-    const filter = options.filter === 'linear' ? gl.LINEAR : gl.NEAREST;
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+    const linear = options.filter === 'linear';
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, linear ? gl.LINEAR : gl.NEAREST);
+    /*
+     * **Minification is the chain's question and magnification is `filter`'s**, which is why the two
+     * are set apart here. A mipmapped sheet blends *between* levels whichever filter was asked for:
+     * that is what stops a stroke disappearing on the way down, and `filter` still decides whether
+     * the texels inside a level are blended. `SurfaceTexture` splits it the same way.
+     */
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, options.mipmap === true
+        ? linear
+            ? gl.LINEAR_MIPMAP_LINEAR
+            : gl.NEAREST_MIPMAP_LINEAR
+        : linear
+            ? gl.LINEAR
+            : gl.NEAREST);
     /*
      * Clamped on both axes, and it is a correctness rule rather than a default. A sheet frame's
      * edge texel is adjacent to the *next* frame's, so a repeating wrap bleeds one sprite into
@@ -107,6 +119,10 @@ export function setWebgl2SpriteTexture(gl, sprites, slot, source, options) {
      */
     gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
     gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    /* After the upload, which is the only order that works: the chain is built from level 0, and a
+       driver that has not been given one yet builds nothing from it. */
+    if (options.mipmap === true)
+        gl.generateMipmap(gl.TEXTURE_2D);
     gl.bindTexture(gl.TEXTURE_2D, null);
     gl.activeTexture(gl.TEXTURE0);
     sprites.textures[slot] = texture;

package/dist/spriteGpu.d.ts

@@ -1,5 +1,6 @@
 /** The WebGPU half of the sprite pass: one pipeline, one instance buffer, a bind group per slot. */
 import type { SpriteBatch } from './spriteBatch.ts';
+import { type MipPipelines } from '@driftengine/core';
 import type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
 export interface GpuSpriteSlot {
     readonly texture: GPUTexture;
@@ -14,7 +15,11 @@ export interface GpuSprites {
     readonly samplers: {
         readonly nearest: GPUSampler;
         readonly linear: GPUSampler;
+        readonly nearestMip: GPUSampler;
+        readonly linearMip: GPUSampler;
     };
+    /** One mip-blit pipeline per format, built on first use. See `generateMipChain`. */
+    readonly mipPipelines: MipPipelines;
     readonly slots: (GpuSpriteSlot | null)[];
     readonly vertexScratch: ArrayBuffer;
     readonly vertexFloats: Float32Array;

package/dist/spriteGpu.js

@@ -1,6 +1,16 @@
 /** The WebGPU half of the sprite pass: one pipeline, one instance buffer, a bind group per slot. */
 import { SPRITE_BINDINGS, SPRITE_FRAG_WGSL, SPRITE_VERT_WGSL, } from './shaders/generated/sprite.wgsl.js';
 import { SPRITE_FLOATS } from './spriteBatch.js';
+/*
+ * **The first runtime import this package takes from the engine, and it was measured before it was
+ * taken.** Everything else here is `import type`, which erases, so `ui2d` has had no runtime edge
+ * to `core` at all — and a value import from a barrel is how a package quietly acquires the whole
+ * of another one. Bundled alone, with the import and with it stubbed out: **32,801 against 31,031
+ * raw and 11,777 against 11,163 gzipped**, so 614 gzipped bytes, which is the blit and its shader
+ * and nothing else. The alternative was a second copy of the mip blit living here, and the second
+ * copy is the one that ends up disagreeing about the colour space.
+ */
+import { generateMipChain, mipLevelCount } from '@driftengine/core';
 const VERT = SPRITE_BINDINGS.SPRITE_VERT;
 const FRAG = SPRITE_BINDINGS.SPRITE_FRAG;
 const STRIDE = SPRITE_FLOATS * 4;
@@ -104,7 +114,23 @@ export function createGpuSprites(device, format, depthFormat, samples, capacity,
                 magFilter: 'linear',
                 minFilter: 'linear',
             }),
+            /*
+             * The mipmapped pair. `mipmapFilter` is the level blend and is `linear` in both, because
+             * that is minification; `magFilter` is what `filter` was asked about. Four samplers rather
+             * than two because the questions are independent, and the same split `SurfaceTexture` makes.
+             */
+            nearestMip: device.createSampler({
+                label: `${label}.nearestMip`,
+                mipmapFilter: 'linear',
+            }),
+            linearMip: device.createSampler({
+                label: `${label}.linearMip`,
+                magFilter: 'linear',
+                minFilter: 'linear',
+                mipmapFilter: 'linear',
+            }),
         },
+        mipPipelines: mipPipelineCache(device),
         slots: new Array(slots).fill(null),
         vertexScratch,
         vertexFloats: new Float32Array(vertexScratch),
@@ -113,14 +139,39 @@ export function createGpuSprites(device, format, depthFormat, samples, capacity,
         fragmentInts: new Int32Array(fragmentScratch),
     };
 }
+/**
+ * One pipeline per format, kept on the sprite pass rather than in the renderer's cache.
+ *
+ * The renderer's `PipelineCache` is not reachable from a contributed pass, and the chain builder
+ * takes an interface for exactly that reason. A `Map` is the whole of what is needed: there are at
+ * most two formats here, and they are built once each.
+ */
+function mipPipelineCache(device) {
+    const built = new Map();
+    return {
+        get(key, describe) {
+            const existing = built.get(key);
+            if (existing !== undefined)
+                return existing;
+            const pipeline = device.createRenderPipeline(describe());
+            built.set(key, pipeline);
+            return pipeline;
+        },
+    };
+}
 export function setGpuSpriteTexture(device, sprites, slot, source, options) {
     const previous = sprites.slots[slot];
     if (previous !== null && previous !== undefined)
         previous.texture.destroy();
+    const format = options.colorSpace === 'linear' ? 'rgba8unorm' : 'rgba8unorm-srgb';
+    /* One level unless a chain was asked for. `TEXTURE_USAGE` already carries RENDER_ATTACHMENT,
+       which is what the blit needs to draw into each level. */
+    const levels = options.mipmap === true ? mipLevelCount(source.width, source.height) : 1;
     const texture = device.createTexture({
         label: `ui2d.sprite.${slot}`,
         size: [source.width, source.height],
-        format: options.colorSpace === 'linear' ? 'rgba8unorm' : 'rgba8unorm-srgb',
+        format,
+        mipLevelCount: levels,
         usage: TEXTURE_USAGE,
     });
     /*
@@ -130,7 +181,17 @@ export function setGpuSpriteTexture(device, sprites, slot, source, options) {
      * the source type most callers use.
      */
     device.queue.copyExternalImageToTexture({ source: source, flipY: false }, { texture }, [source.width, source.height]);
-    const sampler = options.filter === 'linear' ? sprites.samplers.linear : sprites.samplers.nearest;
+    /* After the copy, which is the only order that works: every level is rendered from the one above
+       it, and level 0 has to hold the image before the chain can be built from it. */
+    generateMipChain(device, sprites.mipPipelines, texture, format, levels);
+    const linear = options.filter === 'linear';
+    const sampler = levels > 1
+        ? linear
+            ? sprites.samplers.linearMip
+            : sprites.samplers.nearestMip
+        : linear
+            ? sprites.samplers.linear
+            : sprites.samplers.nearest;
     const bindGroup = device.createBindGroup({
         label: `ui2d.sprite.${slot}.bindGroup`,
         layout: sprites.layout,

package/dist/spriteTexture.d.ts

@@ -32,5 +32,35 @@ export interface SpriteTextureOptions {
      * and saves the sharp case from a blur nobody asked for.
      */
     readonly filter?: 'nearest' | 'linear';
+    /**
+     * Whether to build a mip chain and sample it. `false` by default, which is the sheet above.
+     *
+     * **The case it exists for is type baked into an atlas.** The comment on `filter` says a sheet
+     * that is not pixel art "is normally drawn near its authored size, where the two filters differ
+     * by very little" — a glyph page is the sheet where that is not true. A consumer baking one page
+     * per weight at 96 px and drawing body copy at 11 is minifying **7x**, and `linear` reads four
+     * texels of a footprint that covers dozens: a `t` crossbar two texels tall lands on about a
+     * quarter of a pixel, and whether it survives depends on where the sample falls. Reported by a
+     * player as `Step-In Uppercut` reading `Slep-In Uppercul`, with different strokes lost per
+     * glyph and per position, so the line looks unevenly spaced as well as misread.
+     *
+     * Neither workaround available to a consumer is good: baking nearer the drawn size blurs the
+     * headings, because one atlas cannot serve an 8x range of sizes, and baking a second atlas for
+     * small text doubles the pages and the uploads and moves a sampling decision into the game where
+     * it has to be re-tuned whenever a size changes.
+     *
+     * **Off by default because the chain is wrong for pixel art**, which is what most sheets are: it
+     * is memory nothing samples, and at a distance it dissolves art whose whole point is the pixel.
+     *
+     * With `filter: 'linear'` this is trilinear — blended within a level and between levels. With
+     * `filter: 'nearest'` the levels are still blended, because that is minification and `filter` is
+     * about magnification; `SurfaceTexture` makes the same split and for the same reason.
+     *
+     * **Padding cells against bleed is the caller's problem**, and it has to be: a lower level mixes
+     * texels the atlas packer put next to each other, so a sheet whose frames touch will show its
+     * neighbours. How much padding depends on how far the chain is allowed to go, which is a fact
+     * about the sheet rather than about the sampler.
+     */
+    readonly mipmap?: boolean;
 }
 export declare const DEFAULT_SPRITE_TEXTURE_OPTIONS: SpriteTextureOptions;

package/dist/spriteTexture.js

@@ -2,4 +2,5 @@
 export const DEFAULT_SPRITE_TEXTURE_OPTIONS = {
     colorSpace: 'srgb',
     filter: 'nearest',
+    mipmap: false,
 };

package/dist/textHost.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The platform services text entry needs, taken as a parameter.
+ *
+ * **Composition — the multi-keystroke entry every language that is not typed one character at a
+ * time depends on — is a platform service.** The browser has one, a native host has a different
+ * one, and a test has none. `AGENTS.md` requires a capability be taken as a parameter with a
+ * browser implementation shipped as the default; this is that rule applied to text, and it is why
+ * this package can run under a host with no document object model at all.
+ */
+import type { TextModel } from './textModel.ts';
+export interface TextHost {
+    /** Tell the host a field is focused at this rectangle, so it can place a composition window. */
+    focusField(x: number, y: number, w: number, h: number): void;
+    /** Tell the host nothing is focused. */
+    blurField(): void;
+    /** Read the clipboard, if the host has one. Asynchronous everywhere one exists. */
+    readClipboard(): Promise<string>;
+    /** Write the clipboard, if the host has one. */
+    writeClipboard(text: string): Promise<void>;
+}
+/**
+ * A host that focuses nothing and whose clipboard is empty.
+ *
+ * What a test uses, and what a headless build uses. **An empty clipboard rather than a missing
+ * one**, so a caller never has to branch on whether it has a host.
+ */
+export declare function createNullTextHost(): TextHost;
+/**
+ * Fold one composition update into the model.
+ *
+ * An update replaces whatever the previous update of this composition put there, rather than the
+ * whole field — which is what makes a five-keystroke entry produce one word instead of five.
+ *
+ * **`done` clears the range, and that is the step everyone forgets.** A finished composition that
+ * leaves its range set means the *next* keystroke overwrites the text that was just committed,
+ * which presents as characters vanishing one word behind the caret.
+ */
+export declare function applyComposition(model: TextModel, state: {
+    text: string;
+    done: boolean;
+}): void;

package/dist/textHost.js

@@ -0,0 +1,44 @@
+import { selectionRange } from './textModel.js';
+/**
+ * A host that focuses nothing and whose clipboard is empty.
+ *
+ * What a test uses, and what a headless build uses. **An empty clipboard rather than a missing
+ * one**, so a caller never has to branch on whether it has a host.
+ */
+export function createNullTextHost() {
+    return {
+        focusField() { },
+        blurField() { },
+        readClipboard: async () => '',
+        writeClipboard: async () => { },
+    };
+}
+/**
+ * Fold one composition update into the model.
+ *
+ * An update replaces whatever the previous update of this composition put there, rather than the
+ * whole field — which is what makes a five-keystroke entry produce one word instead of five.
+ *
+ * **`done` clears the range, and that is the step everyone forgets.** A finished composition that
+ * leaves its range set means the *next* keystroke overwrites the text that was just committed,
+ * which presents as characters vanishing one word behind the caret.
+ */
+export function applyComposition(model, state) {
+    if (model.composeFrom === -1) {
+        const { from, to } = selectionRange(model);
+        model.text = model.text.slice(0, from) + state.text + model.text.slice(to);
+        model.composeFrom = from;
+        model.composeTo = from + state.text.length;
+    }
+    else {
+        model.text =
+            model.text.slice(0, model.composeFrom) + state.text + model.text.slice(model.composeTo);
+        model.composeTo = model.composeFrom + state.text.length;
+    }
+    model.caret = model.composeTo;
+    model.anchor = model.caret;
+    if (state.done) {
+        model.composeFrom = -1;
+        model.composeTo = -1;
+    }
+}

package/dist/textModel.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A caret, a selection, and the operations that move them.
+ *
+ * **Pure, and it is pure on purpose.** Every editing defect anybody has met lives here rather than
+ * in the platform: a caret inside a character, a right-to-left selection that deletes the wrong
+ * end, a backspace that removes half an emoji. Pure, each of those is a test that runs in under a
+ * millisecond. Wired to a host, none of them is.
+ *
+ * **Offsets are into the string and are always on a code-point boundary.** JavaScript strings are
+ * UTF-16, so an astral character is two units and a caret between them is a caret inside a
+ * character — which renders as a replacement glyph and deletes as a lone surrogate. Every move and
+ * every delete steps over the pair.
+ *
+ * `anchor` is where a selection started and `caret` is where it is now, so `anchor > caret` is an
+ * ordinary right-to-left selection rather than an error. `selectionRange` is the only thing that
+ * orders them and everything else goes through it.
+ */
+export interface TextModel {
+    text: string;
+    /** Where the caret is, as a UTF-16 offset on a code-point boundary. */
+    caret: number;
+    /** Where the current selection began. Equal to `caret` when nothing is selected. */
+    anchor: number;
+    /**
+     * The range an in-progress composition occupies, or -1 when none is in progress.
+     *
+     * Written only by `applyComposition` in `textHost.ts`. It lives on the model rather than in the
+     * host because the range is a property of the text, and a host that crashed mid-composition
+     * would otherwise leave the field permanently convinced it was still composing.
+     */
+    composeFrom: number;
+    composeTo: number;
+}
+export declare function createTextModel(text?: string): TextModel;
+export declare function selectionRange(model: TextModel): {
+    from: number;
+    to: number;
+};
+export declare function selectedText(model: TextModel): string;
+export declare function insertText(model: TextModel, s: string): void;
+export declare function deleteBackward(model: TextModel): void;
+export declare function deleteForward(model: TextModel): void;
+export declare function moveCaret(model: TextModel, delta: number, select: boolean): void;
+export declare function moveToLineEdge(model: TextModel, forward: boolean, select: boolean): void;
+export declare function selectAll(model: TextModel): void;