@twip/web 0.0.0-canary-f16fa12

package/dist/host/dom.d.ts

@@ -0,0 +1,45 @@
+/** What a mount owns: `container > scroller > [canvas, content > layer]`, each marked with `data-twip`. */
+export interface Dom {
+    /** Scrolls natively over the content; the canvas stays in view. */
+    scroller: HTMLDivElement;
+    /** The viewport's pixels. */
+    canvas: HTMLCanvasElement;
+    /** As large as the document at the zoom: it gives the scroller its extent. ContentPoint coordinates. */
+    content: HTMLDivElement;
+    /** Over the content: the input element, the accessibility DOM and the balloon layer. */
+    layer: HTMLDivElement;
+}
+/** What every live ledger holds, and the engine worker (transport/worker.ts), for the tests (`globalThis[resources]()`). */
+export declare const live: {
+    nodes: number;
+    listeners: number;
+    observers: number;
+    timers: number;
+    frames: number;
+    workers: number;
+};
+/** The symbol the resource counts are read through. Internal: for the SDK's tests. */
+export declare const resources: unique symbol;
+/** The resources of one mount. */
+export declare class Ledger {
+    #private;
+    /** `addEventListener`, removed on release. */
+    listen<K extends keyof HTMLElementEventMap>(target: HTMLElement, type: K, listener: (e: HTMLElementEventMap[K]) => void, options?: AddEventListenerOptions): void;
+    listen(target: EventTarget, type: string, listener: (e: Event) => void, options?: AddEventListenerOptions): void;
+    /** An observer, disconnected on release. */
+    observe<T extends {
+        disconnect(): void;
+    }>(observer: T): T;
+    /** A node appended to `parent`, removed on release. */
+    node<T extends Element>(parent: Element, node: T): T;
+    /** A one-shot timer, cleared on release. Returns its cancel. */
+    timeout(run: () => void, ms: number): () => void;
+    /** One animation frame, cancelled on release. Returns its cancel. */
+    frame(run: () => void): () => void;
+    /** Undoes everything, last made first. Idempotent. */
+    release(): void;
+}
+/** Claims `container` for one editor, or throws `unavailable`. Returns the release. */
+export declare function claim(container: HTMLElement): () => void;
+/** Builds the editor's DOM in `container`; the ledger removes it. */
+export declare function createDom(container: HTMLElement, ledger: Ledger): Dom;

package/dist/host/dom.js

@@ -0,0 +1,122 @@
+// The editor's DOM inside the application's container, and the ledger of everything a mount creates: listeners,
+// observers, timers and animation frames are made through it, so destroy (or a failed mount) undoes all of it.
+import { EditorError } from '../errors.js';
+/** What every live ledger holds, and the engine worker (transport/worker.ts), for the tests (`globalThis[resources]()`). */
+export const live = { nodes: 0, listeners: 0, observers: 0, timers: 0, frames: 0, workers: 0 };
+/** The symbol the resource counts are read through. Internal: for the SDK's tests. */
+export const resources = Symbol.for('twip.resources');
+globalThis[resources] = () => ({ ...live });
+/** The resources of one mount. */
+export class Ledger {
+    #undo = [];
+    #timers = new Set();
+    #frames = new Set();
+    #released = false;
+    listen(target, type, listener, options) {
+        const l = listener;
+        target.addEventListener(type, l, options);
+        live.listeners++;
+        this.#undo.push(() => {
+            target.removeEventListener(type, l, options);
+            live.listeners--;
+        });
+    }
+    /** An observer, disconnected on release. */
+    observe(observer) {
+        live.observers++;
+        this.#undo.push(() => {
+            observer.disconnect();
+            live.observers--;
+        });
+        return observer;
+    }
+    /** A node appended to `parent`, removed on release. */
+    node(parent, node) {
+        parent.append(node);
+        live.nodes++;
+        this.#undo.push(() => {
+            node.remove();
+            live.nodes--;
+        });
+        return node;
+    }
+    /** A one-shot timer, cleared on release. Returns its cancel. */
+    timeout(run, ms) {
+        if (this.#released)
+            return () => { };
+        const handle = setTimeout(() => {
+            this.#timers.delete(handle);
+            live.timers--;
+            run();
+        }, ms);
+        this.#timers.add(handle);
+        live.timers++;
+        return () => {
+            if (this.#timers.delete(handle)) {
+                clearTimeout(handle);
+                live.timers--;
+            }
+        };
+    }
+    /** One animation frame, cancelled on release. Returns its cancel. */
+    frame(run) {
+        if (this.#released)
+            return () => { };
+        const handle = requestAnimationFrame(() => {
+            this.#frames.delete(handle);
+            live.frames--;
+            run();
+        });
+        this.#frames.add(handle);
+        live.frames++;
+        return () => {
+            if (this.#frames.delete(handle)) {
+                cancelAnimationFrame(handle);
+                live.frames--;
+            }
+        };
+    }
+    /** Undoes everything, last made first. Idempotent. */
+    release() {
+        this.#released = true;
+        for (const handle of this.#timers)
+            clearTimeout(handle);
+        for (const handle of this.#frames)
+            cancelAnimationFrame(handle);
+        live.timers -= this.#timers.size;
+        live.frames -= this.#frames.size;
+        this.#timers.clear();
+        this.#frames.clear();
+        for (const undo of this.#undo.splice(0).reverse())
+            undo();
+    }
+}
+/** Containers with an editor, or one mounting. */
+const occupied = new WeakSet();
+/** Claims `container` for one editor, or throws `unavailable`. Returns the release. */
+export function claim(container) {
+    if (occupied.has(container) || container.querySelector(':scope > [data-twip]')) {
+        throw new EditorError('unavailable', 'the container already holds an editor');
+    }
+    occupied.add(container);
+    return () => occupied.delete(container);
+}
+function element(tag, name, css) {
+    const e = document.createElement(tag);
+    e.dataset.twip = name;
+    e.style.cssText = css;
+    return e;
+}
+/** Builds the editor's DOM in `container`; the ledger removes it. */
+export function createDom(container, ledger) {
+    // One grid cell holds the canvas and the content: the sticky canvas can then stay in view over the content's whole
+    // extent, in both directions.
+    const scroller = element('div', 'editor', 'position:relative;width:100%;height:100%;overflow:auto;display:grid;outline:none;');
+    const canvas = element('canvas', 'canvas', 'grid-area:1/1;position:sticky;left:0;top:0;align-self:start;justify-self:start;display:block;touch-action:none;');
+    const content = element('div', 'content', 'grid-area:1/1;position:relative;pointer-events:none;');
+    const layer = element('div', 'layer', 'position:absolute;inset:0;overflow:hidden;');
+    content.append(layer);
+    scroller.append(canvas, content);
+    ledger.node(container, scroller);
+    return { scroller, canvas, content, layer };
+}

package/dist/host/frames.d.ts

@@ -0,0 +1,14 @@
+import type { Session } from '../editor.js';
+import { type FrameInfo } from '../transport/protocol.js';
+import type { Dom, Ledger } from './dom.js';
+/** The frame loop of a mounted editor. */
+export interface Frames {
+    /** The last frame's content size. */
+    readonly info: FrameInfo;
+    /** Draws a frame at the next animation frame. */
+    request(): void;
+    /** Resolves once a frame was drawn after this call; at once while the editor has no size. */
+    drawn(): Promise<void>;
+}
+/** Starts the frame loop; `onFrame` runs after each frame drawn. */
+export declare function startFrames(s: Session, dom: Dom, ledger: Ledger, report: (e: unknown) => void, onFrame: (info: FrameInfo) => void): Promise<Frames>;

package/dist/host/frames.js

@@ -0,0 +1,87 @@
+import { Kind } from '../transport/protocol.js';
+/** Starts the frame loop; `onFrame` runs after each frame drawn. */
+export async function startFrames(s, dom, ledger, report, onFrame) {
+    await s.guard(() => s.transport.attachCanvas(s.id, dom.canvas));
+    let info = { contentWidth: 0, contentHeight: 0, pages: 0 };
+    let surface = { width: 0, height: 0, dpr: 0 };
+    let cancel;
+    let busy = false;
+    let again = false;
+    const waiting = [];
+    const settle = () => {
+        for (const resolve of waiting.splice(0))
+            resolve();
+    };
+    const draw = () => {
+        cancel = undefined;
+        if (busy) {
+            again = true;
+            return;
+        }
+        const { width, height, dpr } = surface;
+        if (!width || !height)
+            return settle();
+        busy = true;
+        s.frame(Math.round(width * dpr), Math.round(height * dpr))
+            .then((drawn) => {
+            if (drawn) {
+                info = drawn;
+                onFrame(drawn);
+            }
+        }, report)
+            .finally(() => {
+            busy = false;
+            settle();
+            if (again) {
+                again = false;
+                request();
+            }
+        });
+    };
+    const request = () => {
+        if (!cancel && !s.destroyed)
+            cancel = ledger.frame(draw);
+    };
+    // The viewport's size and density go to the engine as the surface; the canvas covers the viewport.
+    const resize = () => {
+        const next = { width: dom.scroller.clientWidth, height: dom.scroller.clientHeight, dpr: globalThis.devicePixelRatio || 1 };
+        if (next.width !== surface.width || next.height !== surface.height || next.dpr !== surface.dpr) {
+            surface = next;
+            dom.canvas.style.width = `${next.width}px`;
+            dom.canvas.style.height = `${next.height}px`;
+            s.input({ type: 'surface', ...next }).catch(report);
+        }
+        request();
+    };
+    // A density change (browser zoom, another monitor) is a `resolution` media query that stops matching.
+    const watchDensity = () => {
+        const query = matchMedia(`(resolution: ${globalThis.devicePixelRatio || 1}dppx)`);
+        ledger.listen(query, 'change', () => {
+            resize();
+            watchDensity();
+        }, { once: true });
+    };
+    watchDensity();
+    ledger.observe(new ResizeObserver(resize)).observe(dom.scroller);
+    // Shown again (display, visibility, scrolled into the page): draw.
+    ledger.observe(new IntersectionObserver((entries) => entries.some((e) => e.isIntersecting) && resize())).observe(dom.scroller);
+    const onMessage = (message) => {
+        if (message.kind === Kind.RequestFrame)
+            request();
+    };
+    s.hostListeners.add(onMessage);
+    s.disposers.push(() => s.hostListeners.delete(onMessage));
+    resize();
+    return {
+        get info() {
+            return info;
+        },
+        request,
+        drawn: () => {
+            if (!surface.width || !surface.height || s.destroyed)
+                return Promise.resolve();
+            request();
+            return new Promise((resolve) => waiting.push(resolve));
+        },
+    };
+}

package/dist/host/gpu.d.ts

@@ -0,0 +1,58 @@
+import type { TwipModule } from '../transport/module.js';
+/** The parts of a WebGPU device the engine imports. */
+export interface GpuDevice {
+    queue: {
+        writeTexture(destination: {
+            texture: unknown;
+        }, data: Uint8Array, layout: {
+            bytesPerRow: number;
+        }, size: {
+            width: number;
+            height: number;
+        }): void;
+    };
+    /** Settles when the device is lost: destroyed, or the GPU reset. */
+    lost: Promise<unknown>;
+}
+/** The parts of a WebGPU canvas context used here. */
+interface GpuCanvasContext {
+    configure(options: {
+        device: GpuDevice;
+        format: string;
+        alphaMode: string;
+        usage: number;
+    }): void;
+    getCurrentTexture(): unknown;
+}
+/** A canvas configured for WebGPU frames. */
+export interface WebGpuTarget {
+    canvas: HTMLCanvasElement | OffscreenCanvas;
+    context: GpuCanvasContext;
+    bgra: boolean;
+    /** CPU pixels are copied into the texture with this device, which the engine didn't adopt. */
+    cpu?: GpuDevice;
+}
+/** A canvas with the engine's WebGL 2 context. */
+export interface WebGlTarget {
+    canvas: HTMLCanvasElement | OffscreenCanvas;
+    handle: number;
+}
+/** Adopts a WebGPU device for every session of the engine. False if the engine can't use it: use WebGL then. */
+export declare function attachWebGpu(m: TwipModule, device: GpuDevice): boolean;
+/** Configures `canvas` for WebGPU frames with `device`; for CPU pixels copied in, with `cpu`. */
+export declare function webGpuTarget(canvas: HTMLCanvasElement | OffscreenCanvas, device: GpuDevice, cpu?: boolean): WebGpuTarget;
+/** The page's WebGPU device, or null when it has none. */
+export declare function gpuDevice(): Promise<GpuDevice | null>;
+/** Draws a session's frame into the target's current texture; the frame's `TwipFrameInfo` goes to `info`. */
+export declare function frameWebGpu(m: TwipModule, engine: number, session: number, target: WebGpuTarget, info: number): boolean;
+/** Copies CPU pixels (premultiplied RGBA) into a CPU target's current texture. */
+export declare function writeWebGpu(target: WebGpuTarget, pixels: Uint8Array, width: number, height: number): void;
+/** Creates a WebGL 2 context on `canvas` for a session (one per canvas), or null when WebGL 2 is unavailable. */
+export declare function webGlTarget(m: TwipModule, engine: number, session: number, canvas: HTMLCanvasElement | OffscreenCanvas): WebGlTarget | null;
+/** The session's WebGL target again once its lost context is restored: a new context handle, attached anew. */
+export declare function restoreWebGl(m: TwipModule, engine: number, session: number, target: WebGlTarget): WebGlTarget | null;
+/** Keeps a lost WebGL context restorable (by default the browser drops it), calling `lost` then `restored`. */
+export declare function watchWebGl(canvas: HTMLCanvasElement | OffscreenCanvas, lost: () => void, restored: () => void): () => void;
+/** Draws a session's frame into its WebGL canvas; the frame's `TwipFrameInfo` goes to `info`. */
+export declare function frameWebGl(m: TwipModule, engine: number, session: number, target: WebGlTarget, info: number): boolean;
+export {};

package/dist/host/gpu.js

@@ -0,0 +1,79 @@
+/** Adopts a WebGPU device for every session of the engine. False if the engine can't use it: use WebGL then. */
+export function attachWebGpu(m, device) {
+    if (!m.WebGPU)
+        return false;
+    const instance = m._twip_gpu_instance();
+    const imported = m.WebGPU.importJsDevice(device, instance);
+    return m._twip_attach_webgpu(instance, imported, m.WebGPU.importJsQueue(device.queue, instance)) === 0;
+}
+/** Configures `canvas` for WebGPU frames with `device`; for CPU pixels copied in, with `cpu`. */
+export function webGpuTarget(canvas, device, cpu = false) {
+    const context = canvas.getContext('webgpu');
+    if (cpu) {
+        // COPY_DST: the engine's pixels are premultiplied RGBA.
+        context.configure({ device, format: 'rgba8unorm', alphaMode: 'premultiplied', usage: 0x02 });
+        return { canvas, context, bgra: false, cpu: device };
+    }
+    const gpu = globalThis.navigator?.gpu;
+    const format = gpu?.getPreferredCanvasFormat() ?? 'rgba8unorm';
+    // COPY_SRC | COPY_DST | TEXTURE_BINDING | RENDER_ATTACHMENT: what Graphite needs of the canvas texture.
+    context.configure({ device, format, alphaMode: 'premultiplied', usage: 0x01 | 0x02 | 0x04 | 0x10 });
+    return { canvas, context, bgra: format === 'bgra8unorm' };
+}
+/** The page's WebGPU device, or null when it has none. */
+export async function gpuDevice() {
+    const gpu = globalThis.navigator?.gpu;
+    try {
+        return (await (await gpu?.requestAdapter())?.requestDevice()) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Draws a session's frame into the target's current texture; the frame's `TwipFrameInfo` goes to `info`. */
+export function frameWebGpu(m, engine, session, target, info) {
+    if (!m.WebGPU)
+        return false;
+    const texture = m.WebGPU.importJsTexture(target.context.getCurrentTexture());
+    return m._twip_frame_webgpu(engine, session, texture, target.bgra ? 1 : 0, target.canvas.height, info) === 0;
+}
+/** Copies CPU pixels (premultiplied RGBA) into a CPU target's current texture. */
+export function writeWebGpu(target, pixels, width, height) {
+    target.cpu?.queue.writeTexture({ texture: target.context.getCurrentTexture() }, pixels, { bytesPerRow: width * 4 }, { width, height });
+}
+/** Creates a WebGL 2 context on `canvas` for a session (one per canvas), or null when WebGL 2 is unavailable. */
+export function webGlTarget(m, engine, session, canvas) {
+    if (!m.GL)
+        return null;
+    const attributes = { majorVersion: 2, minorVersion: 0, alpha: 1, depth: 0, stencil: 8, antialias: 0, premultipliedAlpha: 1 };
+    const handle = m.GL.createContext(canvas, attributes);
+    if (!handle)
+        return null;
+    m.GL.makeContextCurrent(handle);
+    return m._twip_attach_webgl(engine, session) === 0 ? { canvas, handle } : null;
+}
+/** The session's WebGL target again once its lost context is restored: a new context handle, attached anew. */
+export function restoreWebGl(m, engine, session, target) {
+    m.GL?.deleteContext(target.handle);
+    return webGlTarget(m, engine, session, target.canvas);
+}
+/** Keeps a lost WebGL context restorable (by default the browser drops it), calling `lost` then `restored`. */
+export function watchWebGl(canvas, lost, restored) {
+    const onLost = (e) => {
+        e.preventDefault();
+        lost();
+    };
+    canvas.addEventListener('webglcontextlost', onLost);
+    canvas.addEventListener('webglcontextrestored', restored);
+    return () => {
+        canvas.removeEventListener('webglcontextlost', onLost);
+        canvas.removeEventListener('webglcontextrestored', restored);
+    };
+}
+/** Draws a session's frame into its WebGL canvas; the frame's `TwipFrameInfo` goes to `info`. */
+export function frameWebGl(m, engine, session, target, info) {
+    if (!m.GL)
+        return false;
+    m.GL.makeContextCurrent(target.handle);
+    return m._twip_frame_webgl(engine, session, target.canvas.width, target.canvas.height, info) === 0;
+}

package/dist/host/ime.d.ts

@@ -0,0 +1,3 @@
+import type { Session } from '../editor.js';
+import type { Ledger } from './dom.js';
+export declare function startIme(s: Session, input: HTMLTextAreaElement, ledger: Ledger, report: (e: unknown) => void): void;

package/dist/host/ime.js

@@ -0,0 +1,11 @@
+const Phase = { start: 0, update: 1, end: 2 };
+export function startIme(s, input, ledger, report) {
+    const compose = (phase, text) => s.input({ type: 'composition', phase, text }).catch(report);
+    ledger.listen(input, 'compositionstart', () => compose(Phase.start, ''));
+    ledger.listen(input, 'compositionupdate', (e) => compose(Phase.update, e.data));
+    ledger.listen(input, 'compositionend', (e) => {
+        compose(Phase.end, e.data);
+        // The element only ever holds the composition.
+        input.value = '';
+    });
+}

package/dist/host/input.d.ts

@@ -0,0 +1,12 @@
+import type { Session } from '../editor.js';
+import type { Dom, Ledger } from './dom.js';
+/** The input element of a mounted editor. */
+export interface Input {
+    readonly element: HTMLTextAreaElement;
+    focus(): void;
+}
+/**
+ * Starts keyboard and text input. `claims` says whether a chord is a command's, an application shortcut or a host
+ * key (`shortcuts.lookup`): those keys are the editor's, and their browser defaults (Save, Print, Find) don't run.
+ */
+export declare function startInput(s: Session, dom: Dom, ledger: Ledger, report: (e: unknown) => void, claims: (chord: string) => boolean): Input;

package/dist/host/input.js

@@ -0,0 +1,86 @@
+import { Kind } from '../transport/protocol.js';
+import { keyNumber, modsOf } from './keys.js';
+/** Keys that edit or move, with Ctrl or Shift or neither (not Alt, which the browser keeps): the engine's. */
+const editingKeys = new Set([
+    'Backspace', 'Delete', 'Enter', 'NumpadEnter', 'Tab', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End',
+    'PageUp', 'PageDown', 'Escape',
+]);
+/** The clipboard's keys: the browser turns them into `copy`, `cut` and `paste` events (host/clipboard.ts). */
+const clipboardKeys = new Set(['ctrl+c', 'ctrl+x', 'ctrl+v', 'ctrl+shift+v', 'ctrl+insert', 'shift+insert', 'shift+delete']);
+/** The keys that ask for a dialog (`dialogRequested`): the engine's, though `shortcuts.lookup` names none of them. */
+const dialogKeys = new Set(['ctrl+d']);
+/** The key's names in shortcut strings, by `KeyboardEvent.code`, besides `KeyB` as `B` and `Digit1` as `1`. */
+const names = {
+    Minus: '-', Equal: '=', BracketLeft: '[', BracketRight: ']', Backslash: '\\', Semicolon: ';', Quote: "'", Backquote: '`',
+    Comma: ',', Period: '.', Slash: '/', ArrowLeft: 'Left', ArrowRight: 'Right', ArrowUp: 'Up', ArrowDown: 'Down',
+    NumpadEnter: 'Enter',
+};
+/** A keydown as the shortcut strings spell it: `'Ctrl+Shift+>'`, by the key's code and by the character it made. */
+function chords(e) {
+    // shortcut: Cmd is read as Ctrl, so the Windows shortcut strings serve the Mac too.
+    const mods = `${e.ctrlKey || e.metaKey ? 'Ctrl+' : ''}${e.altKey ? 'Alt+' : ''}${e.shiftKey ? 'Shift+' : ''}`;
+    const keys = new Set([names[e.code] ?? e.code.replace(/^Key|^Digit/, ''), e.code]);
+    if (e.key.length === 1)
+        keys.add(e.key.toUpperCase());
+    return [...keys].map((k) => mods + k);
+}
+/**
+ * Starts keyboard and text input. `claims` says whether a chord is a command's, an application shortcut or a host
+ * key (`shortcuts.lookup`): those keys are the editor's, and their browser defaults (Save, Print, Find) don't run.
+ */
+export function startInput(s, dom, ledger, report, claims) {
+    const input = ledger.node(dom.layer, document.createElement('textarea'));
+    input.dataset.twip = 'input';
+    input.setAttribute('aria-label', 'Document');
+    input.setAttribute('aria-multiline', 'true');
+    input.setAttribute('autocomplete', 'off');
+    input.setAttribute('autocorrect', 'off');
+    input.setAttribute('autocapitalize', 'off');
+    input.spellcheck = false;
+    input.style.cssText =
+        'position:absolute;left:0;top:0;width:1px;height:1em;opacity:0;border:0;padding:0;margin:0;resize:none;overflow:hidden;' +
+            'white-space:pre;outline:none;caret-color:transparent;pointer-events:none;';
+    ledger.listen(input, 'keydown', (e) => {
+        if (e.isComposing || e.keyCode === 229)
+            return;
+        const key = keyNumber(e.code);
+        if (!key)
+            return;
+        const all = chords(e);
+        if (all.some((c) => clipboardKeys.has(c.toLowerCase())))
+            return;
+        // The menu keys open the application's menu only when it listens; otherwise the browser's opens.
+        const menu = e.code === 'ContextMenu' || all.includes('Shift+F10');
+        if (menu && !s.listening('contextMenu'))
+            return;
+        const claimed = all.some((c) => claims(c) || dialogKeys.has(c.toLowerCase()));
+        if (!menu && !(!e.altKey && editingKeys.has(e.code)) && !claimed)
+            return;
+        e.preventDefault();
+        s.input({ type: 'key', key, mods: modsOf(e) }).catch(report);
+    });
+    ledger.listen(input, 'beforeinput', (e) => {
+        if (e.inputType !== 'insertText' && e.inputType !== 'insertReplacementText')
+            return;
+        e.preventDefault();
+        const text = e.data ?? e.dataTransfer?.getData('text/plain');
+        if (text)
+            s.input({ type: 'text', text }).catch(report);
+    });
+    const focused = (focused) => () => s.input({ type: 'focus', focused }).catch(report);
+    ledger.listen(input, 'focus', focused(true));
+    ledger.listen(input, 'blur', focused(false));
+    // The caret request: the input element follows the caret, so the IME's window opens beside it.
+    const onMessage = (m) => {
+        const r = m.payload;
+        if (m.kind !== Kind.HostRequest || r.type !== 'caret')
+            return;
+        input.style.left = `${r.x}px`;
+        input.style.top = `${r.y}px`;
+        input.style.height = `${Math.max(1, r.height)}px`;
+        input.style.fontSize = `${Math.max(1, r.height * 0.8)}px`;
+    };
+    s.hostListeners.add(onMessage);
+    s.disposers.push(() => s.hostListeners.delete(onMessage));
+    return { element: input, focus: () => input.focus({ preventScroll: true }) };
+}

package/dist/host/keys.d.ts

@@ -0,0 +1,16 @@
+/** A key's number for the engine, or 0 when the engine doesn't know it. */
+export declare function keyNumber(code: string): number;
+/** Modifier bits of the C ABI. */
+export declare const Mods: {
+    readonly ctrl: 1;
+    readonly shift: 2;
+    readonly alt: 4;
+    readonly meta: 8;
+};
+/** A keyboard event's modifier bits. */
+export declare function modsOf(e: {
+    shiftKey: boolean;
+    ctrlKey: boolean;
+    altKey: boolean;
+    metaKey: boolean;
+}): number;

package/dist/host/keys.js

@@ -0,0 +1,27 @@
+// Keyboard input as the engine takes it: a key number from KeyboardEvent.code and a modifier bit set.
+/**
+ * The key table of the C ABI (`TwipKey` in `twip.h`), by `KeyboardEvent.code`, so the physical key is what counts and
+ * the layout is the engine's business. 0 is no key. The numbers must match the engine's table exactly.
+ */
+const numbers = {
+    KeyA: 1, KeyB: 2, KeyC: 3, KeyD: 4, KeyE: 5, KeyF: 6, KeyG: 7, KeyH: 8, KeyI: 9, KeyJ: 10, KeyK: 11, KeyL: 12,
+    KeyM: 13, KeyN: 14, KeyO: 15, KeyP: 16, KeyQ: 17, KeyR: 18, KeyS: 19, KeyT: 20, KeyU: 21, KeyV: 22, KeyW: 23,
+    KeyX: 24, KeyY: 25, KeyZ: 26, Digit0: 27, Digit1: 28, Digit2: 29, Digit3: 30, Digit4: 31, Digit5: 32, Digit6: 33,
+    Digit7: 34, Digit8: 35, Digit9: 36, F1: 37, F2: 38, F3: 39, F4: 40, F5: 41, F6: 42, F7: 43, F8: 44, F9: 45,
+    F10: 46, F11: 47, F12: 48, Enter: 61, Tab: 62, Backspace: 63, Delete: 64, Escape: 65, Space: 66, Insert: 67,
+    Home: 68, End: 69, PageUp: 70, PageDown: 71, ArrowLeft: 72, ArrowRight: 73, ArrowUp: 74, ArrowDown: 75,
+    ContextMenu: 76, Minus: 77, Equal: 78, BracketLeft: 79, BracketRight: 80, Backslash: 81, Semicolon: 82, Quote: 83,
+    Backquote: 84, Comma: 85, Period: 86, Slash: 87, IntlBackslash: 88, NumpadEnter: 89, NumpadAdd: 90,
+    NumpadSubtract: 91, NumpadMultiply: 92, NumpadDivide: 93, NumpadDecimal: 94, Numpad0: 95, Numpad1: 96, Numpad2: 97,
+    Numpad3: 98, Numpad4: 99, Numpad5: 100, Numpad6: 101, Numpad7: 102, Numpad8: 103, Numpad9: 104,
+};
+/** A key's number for the engine, or 0 when the engine doesn't know it. */
+export function keyNumber(code) {
+    return Object.hasOwn(numbers, code) ? numbers[code] : 0;
+}
+/** Modifier bits of the C ABI. */
+export const Mods = { ctrl: 1, shift: 2, alt: 4, meta: 8 };
+/** A keyboard event's modifier bits. */
+export function modsOf(e) {
+    return (e.shiftKey ? Mods.shift : 0) | (e.ctrlKey ? Mods.ctrl : 0) | (e.altKey ? Mods.alt : 0) | (e.metaKey ? Mods.meta : 0);
+}

package/dist/host/mount.d.ts

@@ -0,0 +1,11 @@
+import type { MountOptions, Session } from '../editor.js';
+import { type Chrome } from './chrome.js';
+import { type Clipboard } from './clipboard.js';
+/** What a mounted editor gets from its host. */
+export interface Host extends Chrome, Clipboard {
+    focus(): void;
+    /** Resolves once the first viewport is drawn, or at once when the container is hidden or has no size. */
+    ready(): Promise<void>;
+}
+/** Builds the host for `session` in `container`. `claims` is `shortcuts.lookup`, as a yes or no. */
+export declare function mountHost(container: HTMLElement, s: Session, options: MountOptions, claims: (chord: string) => boolean): Promise<Host>;

package/dist/host/mount.js

@@ -0,0 +1,72 @@
+import { EditorError } from '../errors.js';
+import { Method } from '../transport/protocol.js';
+import { startA11y } from './a11y.js';
+import { startChrome } from './chrome.js';
+import { startClipboard } from './clipboard.js';
+import { createDom, Ledger } from './dom.js';
+import { startFrames } from './frames.js';
+import { startIme } from './ime.js';
+import { startInput } from './input.js';
+import { startPointer } from './pointer.js';
+import { startScroll } from './scroll.js';
+/** Builds the host for `session` in `container`. `claims` is `shortcuts.lookup`, as a yes or no. */
+export async function mountHost(container, s, options, claims) {
+    const ledger = new Ledger();
+    s.disposers.push(() => ledger.release());
+    const dom = createDom(container, ledger);
+    const report = (e) => {
+        if (s.destroyed)
+            return;
+        s.emit('error', e instanceof EditorError ? e : new EditorError('internal', String(e), { cause: e }));
+    };
+    // Client points (the API's) to viewport points (the engine's): the canvas covers the viewport.
+    const toViewport = (at) => {
+        const r = dom.canvas.getBoundingClientRect();
+        return { x: at.clientX - r.left, y: at.clientY - r.top };
+    };
+    // The engine's events carry viewport points; the API's are client points.
+    s.adjust = (type, event) => {
+        const r = dom.canvas.getBoundingClientRect();
+        const client = (p) => ({ clientX: p.clientX + r.left, clientY: p.clientY + r.top });
+        if ((type === 'contextMenu' || type === 'gesture') && event)
+            return { ...event, at: client(event.at) };
+        if (type === 'tooltip' && event) {
+            const t = event;
+            return { ...t, at: client(t.at), rect: { ...t.rect, left: t.rect.left + r.left, top: t.rect.top + r.top } };
+        }
+        if (type === 'rulerChanged' && event) {
+            const v = event;
+            return { ...v, horizontal: { ...v.horizontal, origin: v.horizontal.origin + r.left }, vertical: { ...v.vertical, origin: v.vertical.origin + r.top } };
+        }
+        return event;
+    };
+    let chrome;
+    const frames = await startFrames(s, dom, ledger, report, (info) => {
+        scroll.layout(info);
+        chrome?.framed(info);
+    });
+    const scroll = startScroll(s, dom, ledger, frames, report);
+    chrome = startChrome(s, dom, ledger, frames, report, toViewport);
+    const input = startInput(s, dom, ledger, report, claims);
+    startIme(s, input.element, ledger, report);
+    const clipboard = startClipboard(s, dom, input.element, ledger, report, toViewport);
+    const balloons = chrome.balloonLayer;
+    startPointer(s, dom, ledger, scroll, report, input.focus, (t) => t instanceof Node && balloons.contains(t) && t !== balloons);
+    startA11y(s, dom, ledger);
+    await chrome.view.setBackground(options.background ?? '#E6E6E6');
+    if (options.overlayColors)
+        await chrome.view.setOverlayColors(options.overlayColors);
+    if (options.drawLeaders)
+        chrome.drawLeaders(true);
+    if (options.paintBudget) {
+        await s.call(Method.HostSetPaintBudget, { recordings: options.paintBudget.recordings ?? 32 << 20 });
+    }
+    if (options.caretBlink !== undefined || options.caretBlinkStopAfter !== undefined) {
+        await chrome.view.setCaretBlink(options.caretBlink ?? 530, options.caretBlinkStopAfter);
+    }
+    if (options.markupPaneWidth)
+        await chrome.setMarkupPaneWidth(options.markupPaneWidth);
+    if (options.zoom !== undefined && options.zoom !== 100)
+        await s.run({ type: 'setZoom', value: options.zoom });
+    return { ...chrome, ...clipboard, focus: input.focus, ready: () => frames.drawn() };
+}