@quillmark/svelte 0.0.0

package/dist/core/codec/table.d.ts

@@ -0,0 +1,85 @@
+import type { Content, TableCell, TableProps } from '@quillmark/wasm';
+import type { Node as PMNode } from 'prosemirror-model';
+/** One column's alignment, read off the boundary rather than restated. */
+export type TableAlign = TableProps['aligns'][number];
+/** The alignments a column can take: the four the content declares, `none` first
+ *  because it is what a column arrives at and what a set is cleared back to. */
+export declare const ALIGNS: readonly TableAlign[];
+/** The zero cell: empty text, no marks. */
+export declare function emptyCell(): TableCell;
+/**
+ * The row index space the chrome and the ops share: **0 is the header**, 1…n the
+ * body rows. A table always has a header (`header` is a separate field, and a
+ * header-less table is not expressible), so the header is a row that never
+ * deletes rather than a toggle.
+ */
+export declare function rowCount(props: TableProps): number;
+/** The cells of row `r` in that space. */
+export declare function rowCells(props: TableProps, r: number): TableCell[];
+/** The cell at `(row, column)`, or the zero cell where the rectangle does not reach. */
+export declare function cellAt(props: TableProps, r: number, c: number): TableCell;
+/** The table's column count: the one number `header`, every row and `aligns` share. */
+export declare function columnCount(props: TableProps): number;
+/**
+ * The rectangularizing constructor: one column count across `header`, every row and
+ * `aligns`, padding with empty cells and `none`. The column count is the widest
+ * thing present, so a caller that appended to one axis alone still gets a rectangle
+ * back, and a table is never narrower than one column.
+ */
+export declare function normalizeTable(props: TableProps): TableProps;
+/** A fresh table: a header plus `bodyRows` empty rows, every column unaligned.
+ *  Growth is cheap (Tab at the last cell appends a row), so the default is small. */
+export declare function newTable(cols?: number, bodyRows?: number): TableProps;
+/** `props` with the cell at `(r, c)` replaced. */
+export declare function withCell(props: TableProps, r: number, c: number, cell: TableCell): TableProps;
+/** A new empty body row below row `r` (row 0, the header, opens the first body row). */
+export declare function insertRow(props: TableProps, r: number): TableProps;
+/** Drop body row `r`. The header (`r === 0`) has no delete: `header: []` is not a
+ *  table, so the asymmetry is the model's rather than a guard's. */
+export declare function deleteRow(props: TableProps, r: number): TableProps;
+/** A new empty column after column `c`. */
+export declare function insertColumn(props: TableProps, c: number): TableProps;
+/** Drop column `c`; a no-op at one column (a table has at least one). */
+export declare function deleteColumn(props: TableProps, c: number): TableProps;
+/** Body row `r` moved by `by` places, clamped: a drag that leaves the rectangle is a
+ *  no-op rather than an error, since the drop target is geometry and geometry runs
+ *  past the last row. The header is refused because it has no destination: it is a
+ *  separate field, not row 0 of one array. */
+export declare function moveRow(props: TableProps, r: number, by: number): TableProps;
+/** Column `c` moved by `by` places, clamped. `aligns` travels with the column: an
+ *  alignment is the column's property, so a move that left it behind would retint the
+ *  column that took the index. */
+export declare function moveColumn(props: TableProps, c: number, by: number): TableProps;
+/** Column `c` with every cell emptied, alignment kept: what a delete gesture means at
+ *  the LAST column, which the model keeps. There is no row analogue: the header is the
+ *  only row a delete is refused for, and it carries no handle to select it from. */
+export declare function clearColumn(props: TableProps, c: number): TableProps;
+/** Set column `c`'s alignment: the one table capability the content round-trips
+ *  today and nothing in the editor could reach. */
+export declare function setAlign(props: TableProps, c: number, align: TableAlign): TableProps;
+/**
+ * A cell as a one-line `Content`: what `decode` takes under the inline schema. The
+ * cell's marks ARE that content's marks, because both are offsets into the same
+ * text: the cell-local coordinate space is a `Content`'s coordinate space with
+ * one line in it.
+ */
+export declare function cellContent(cell: TableCell): Content;
+/**
+ * The cell a nested PM doc projects, carrying `prior`'s identity anchors through.
+ *
+ * Anchors inside a cell are **preserved verbatim, never minted**: they are not in
+ * the field plugin's coordinate space (the field's position map holds one `atom`
+ * run for the whole table), so nothing here can mint one and the popover withholds
+ * its `anchor` button while the caret is in a cell. Preserving them still means
+ * rebasing: a cell edit is a splice like any other, so each held anchor maps through
+ * the cell's own text delta by the rule `applyChange` uses on a field's
+ * (start-assoc `after`), and a mark the splice deleted through lands where the
+ * splice left it rather than pointing past the text.
+ */
+export declare function cellFromDoc(doc: PMNode, prior: TableCell): TableCell;
+/** Whether two cells are the same value: what tells an own edit (the projection the
+ *  view just produced) from an external one (an undo, a re-hydrate) without a flag. */
+export declare function cellEqual(a: TableCell, b: TableCell): boolean;
+/** Whether two tables have the same rectangle and alignment: the change that forces
+ *  a rebuild rather than a per-cell reseed. */
+export declare function shapeEqual(a: TableProps, b: TableProps): boolean;

package/dist/core/codec/table.js

@@ -0,0 +1,224 @@
+// The table island's model: the cell codec (a `TableCell` ↔ one inline-schema PM
+// doc) and the rectangularizing constructors every row and column op goes through
+// (CODEC §Islands, §"The table island").
+//
+// `TableProps` normalizes to ONE column count shared by `header`, every row, and
+// `aligns`, so a ragged table is not a state the content can hold. The editor keeps
+// its optimistic PM and re-hydrates only on an EXTERNAL change (CODEC
+// §Reconciliation), so an op that emitted a ragged table would leave the store
+// rectangularized and PM ragged with no error channel and no repair. Every
+// constructor here therefore ends in {@link normalizeTable}, and a caller reaches
+// the shape only through them.
+//
+// A cell is its own content unit: `marks` are USV offsets into that cell's `text`,
+// not into `Content.text`. That is the second coordinate space, and the inline mode
+// the codec already runs (one paragraph, no containers, no islands) is exactly its
+// shape, so a cell decodes and projects through the same machinery a
+// `richtext(inline)` field does.
+import { isAnchorMark, mapPos } from '@quillmark/wasm';
+import { contentEdit, pmToContent } from './encode.js';
+/** The alignments a column can take: the four the content declares, `none` first
+ *  because it is what a column arrives at and what a set is cleared back to. */
+export const ALIGNS = ['none', 'left', 'center', 'right'];
+/** The zero cell: empty text, no marks. */
+export function emptyCell() {
+    return { text: '', marks: [] };
+}
+/**
+ * The row index space the chrome and the ops share: **0 is the header**, 1…n the
+ * body rows. A table always has a header (`header` is a separate field, and a
+ * header-less table is not expressible), so the header is a row that never
+ * deletes rather than a toggle.
+ */
+export function rowCount(props) {
+    return props.rows.length + 1;
+}
+/** The cells of row `r` in that space. */
+export function rowCells(props, r) {
+    return r === 0 ? props.header : (props.rows[r - 1] ?? []);
+}
+/** The cell at `(row, column)`, or the zero cell where the rectangle does not reach. */
+export function cellAt(props, r, c) {
+    return rowCells(props, r)[c] ?? emptyCell();
+}
+/** The table's column count: the one number `header`, every row and `aligns` share. */
+export function columnCount(props) {
+    return props.aligns.length;
+}
+/**
+ * The rectangularizing constructor: one column count across `header`, every row and
+ * `aligns`, padding with empty cells and `none`. The column count is the widest
+ * thing present, so a caller that appended to one axis alone still gets a rectangle
+ * back, and a table is never narrower than one column.
+ */
+export function normalizeTable(props) {
+    const cols = Math.max(1, props.header.length, props.aligns.length, ...props.rows.map((row) => row.length));
+    const fit = (cells) => Array.from({ length: cols }, (_, c) => cells[c] ?? emptyCell());
+    return {
+        header: fit(props.header),
+        rows: props.rows.map(fit),
+        aligns: Array.from({ length: cols }, (_, c) => props.aligns[c] ?? 'none')
+    };
+}
+/** A fresh table: a header plus `bodyRows` empty rows, every column unaligned.
+ *  Growth is cheap (Tab at the last cell appends a row), so the default is small. */
+export function newTable(cols = 3, bodyRows = 2) {
+    return normalizeTable({
+        header: Array.from({ length: cols }, emptyCell),
+        rows: Array.from({ length: bodyRows }, () => Array.from({ length: cols }, emptyCell)),
+        aligns: Array.from({ length: cols }, () => 'none')
+    });
+}
+/** `props` with the cell at `(r, c)` replaced. */
+export function withCell(props, r, c, cell) {
+    const replace = (cells) => cells.map((old, i) => (i === c ? cell : old));
+    return normalizeTable({
+        header: r === 0 ? replace(props.header) : props.header,
+        rows: props.rows.map((row, i) => (i === r - 1 ? replace(row) : row)),
+        aligns: props.aligns
+    });
+}
+/** A new empty body row below row `r` (row 0, the header, opens the first body row). */
+export function insertRow(props, r) {
+    const at = Math.max(0, Math.min(r, props.rows.length));
+    const fresh = Array.from({ length: columnCount(props) }, emptyCell);
+    return normalizeTable({
+        ...props,
+        rows: [...props.rows.slice(0, at), fresh, ...props.rows.slice(at)]
+    });
+}
+/** Drop body row `r`. The header (`r === 0`) has no delete: `header: []` is not a
+ *  table, so the asymmetry is the model's rather than a guard's. */
+export function deleteRow(props, r) {
+    if (r === 0)
+        return normalizeTable(props);
+    return normalizeTable({ ...props, rows: props.rows.filter((_, i) => i !== r - 1) });
+}
+/** A new empty column after column `c`. */
+export function insertColumn(props, c) {
+    const at = Math.max(0, Math.min(c + 1, columnCount(props)));
+    const splice = (cells) => [...cells.slice(0, at), emptyCell(), ...cells.slice(at)];
+    return normalizeTable({
+        header: splice(props.header),
+        rows: props.rows.map(splice),
+        aligns: [...props.aligns.slice(0, at), 'none', ...props.aligns.slice(at)]
+    });
+}
+/** Drop column `c`; a no-op at one column (a table has at least one). */
+export function deleteColumn(props, c) {
+    if (columnCount(props) <= 1)
+        return normalizeTable(props);
+    const drop = (xs) => xs.filter((_, i) => i !== c);
+    return normalizeTable({
+        header: drop(props.header),
+        rows: props.rows.map(drop),
+        aligns: drop(props.aligns)
+    });
+}
+/** One element moved within an array, out of place. The whole of what both move ops
+ *  do to their axis, which is why they can only disagree about the index. */
+function move(xs, from, to) {
+    const next = [...xs];
+    const [moved] = next.splice(from, 1);
+    next.splice(to, 0, moved);
+    return next;
+}
+/** Body row `r` moved by `by` places, clamped: a drag that leaves the rectangle is a
+ *  no-op rather than an error, since the drop target is geometry and geometry runs
+ *  past the last row. The header is refused because it has no destination: it is a
+ *  separate field, not row 0 of one array. */
+export function moveRow(props, r, by) {
+    const from = r - 1;
+    const to = Math.max(0, Math.min(from + by, props.rows.length - 1));
+    if (r === 0 || from === to || from >= props.rows.length)
+        return normalizeTable(props);
+    return normalizeTable({ ...props, rows: move(props.rows, from, to) });
+}
+/** Column `c` moved by `by` places, clamped. `aligns` travels with the column: an
+ *  alignment is the column's property, so a move that left it behind would retint the
+ *  column that took the index. */
+export function moveColumn(props, c, by) {
+    const to = Math.max(0, Math.min(c + by, columnCount(props) - 1));
+    if (c === to || c < 0 || c >= columnCount(props))
+        return normalizeTable(props);
+    const shift = (xs) => move(xs, c, to);
+    return normalizeTable({
+        header: shift(props.header),
+        rows: props.rows.map(shift),
+        aligns: shift(props.aligns)
+    });
+}
+/** Column `c` with every cell emptied, alignment kept: what a delete gesture means at
+ *  the LAST column, which the model keeps. There is no row analogue: the header is the
+ *  only row a delete is refused for, and it carries no handle to select it from. */
+export function clearColumn(props, c) {
+    const blank = (cells) => cells.map((cell, i) => (i === c ? emptyCell() : cell));
+    return normalizeTable({
+        header: blank(props.header),
+        rows: props.rows.map(blank),
+        aligns: props.aligns
+    });
+}
+/** Set column `c`'s alignment: the one table capability the content round-trips
+ *  today and nothing in the editor could reach. */
+export function setAlign(props, c, align) {
+    return normalizeTable({
+        ...props,
+        aligns: props.aligns.map((a, i) => (i === c ? align : a))
+    });
+}
+// ── The cell codec ──────────────────────────────────────────────────────────
+/**
+ * A cell as a one-line `Content`: what `decode` takes under the inline schema. The
+ * cell's marks ARE that content's marks, because both are offsets into the same
+ * text: the cell-local coordinate space is a `Content`'s coordinate space with
+ * one line in it.
+ */
+export function cellContent(cell) {
+    return {
+        text: cell.text,
+        lines: [{ containers: [], kind: 'para' }],
+        marks: cell.marks,
+        islands: []
+    };
+}
+/**
+ * The cell a nested PM doc projects, carrying `prior`'s identity anchors through.
+ *
+ * Anchors inside a cell are **preserved verbatim, never minted**: they are not in
+ * the field plugin's coordinate space (the field's position map holds one `atom`
+ * run for the whole table), so nothing here can mint one and the popover withholds
+ * its `anchor` button while the caret is in a cell. Preserving them still means
+ * rebasing: a cell edit is a splice like any other, so each held anchor maps through
+ * the cell's own text delta by the rule `applyChange` uses on a field's
+ * (start-assoc `after`), and a mark the splice deleted through lands where the
+ * splice left it rather than pointing past the text.
+ */
+export function cellFromDoc(doc, prior) {
+    const projected = pmToContent(doc);
+    const text = projected.text;
+    const anchors = prior.marks.filter(isAnchorMark);
+    if (!anchors.length)
+        return { text, marks: projected.marks };
+    const delta = contentEdit(cellContent(prior), cellContent({ text, marks: [] })).delta;
+    const rebased = anchors.map((a) => {
+        const pos = delta ? mapPos(delta, a.start, 'after') : a.start;
+        return { ...a, start: pos, end: pos };
+    });
+    return {
+        text,
+        marks: [...projected.marks, ...rebased].sort((a, b) => a.start - b.start || a.end - b.end)
+    };
+}
+/** Whether two cells are the same value: what tells an own edit (the projection the
+ *  view just produced) from an external one (an undo, a re-hydrate) without a flag. */
+export function cellEqual(a, b) {
+    return a.text === b.text && JSON.stringify(a.marks) === JSON.stringify(b.marks);
+}
+/** Whether two tables have the same rectangle and alignment: the change that forces
+ *  a rebuild rather than a per-cell reseed. */
+export function shapeEqual(a, b) {
+    return (a.rows.length === b.rows.length &&
+        a.aligns.length === b.aligns.length &&
+        a.aligns.every((x, i) => x === b.aligns[i]));
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,73 @@
+import type { DocPath } from './address.js';
+/**
+ * What failed. Stable strings rather than an enum: a consumer switches on them,
+ * and a new surface adds a code without moving the ones an app already handles.
+ */
+export type EditorErrorCode = 
+/** A scalar/array/object write the boundary refused. Also pinned as a
+ *  diagnostic on its own field; editing continues, the value is unwritten. */
+'commit-refused'
+/** A prose commit whose op path the boundary refused: the leaf overwrote
+ *  the whole projection instead, so the store is correct and this field's
+ *  identity anchors were paid. */
+ | 'commit-fallback'
+/** The overwrite fallback ALSO failed: the optimistic PM state stands and the
+ *  store is stale for this field. The one code here that leaves damage. */
+ | 'commit-lost'
+/** A card operation (add, move, remove, retype) that threw. The document is
+ *  unchanged; the boundary's mutators are transactional. */
+ | 'card-op-failed'
+/** `quill.validate` threw: this derive contributes no validation diagnostics. */
+ | 'validate-failed'
+/** `quill.resolve` threw: ghosted `default:`s fall back to none for this derive. */
+ | 'resolve-failed'
+/** A page paint the backend refused. The preview shows its error message state. */
+ | 'paint-failed'
+/** A tip's markdown did not render: the tip shows as literal text. */
+ | 'tip-render-failed'
+/**
+ * A prop a surface binds ONCE was swapped in place, and the surface neither
+ * re-keyed on it nor observed it. The mounted surface still names the previous
+ * handle. `dev` throughout: the fix is a remount at the call site, so this is
+ * aimed at whoever wired it and never at a running app's telemetry.
+ */
+ | 'rebind-ignored'
+/**
+ * An instance verb named a card or a field the surface does not hold: a `cardId`
+ * from a previous session or an already-removed card, a `DocPath` naming no
+ * mounted leaf. The call is a no-op and the document is untouched. `dev`: the
+ * editor's own chrome cannot mint a bad target, so this only ever reports a host
+ * driving the verbs from outside.
+ */
+ | 'target-unknown';
+/** A failure a surface recovered from. */
+export interface EditorError {
+    code: EditorErrorCode;
+    /**
+     * `error` is a runtime failure an app routes to telemetry; `dev` is a contract
+     * violation aimed at whoever is building against the package. Without the
+     * split every consumer's sink filters the dev codes by hand.
+     */
+    severity: 'error' | 'dev';
+    /** English, for a log. Not for display: nothing here has a place on screen. */
+    message: string;
+    /** Whatever was thrown, unwrapped: a `QuillmarkError` arrives intact. */
+    cause?: unknown;
+    /** The field the failure belongs to, where it has one. */
+    path?: DocPath;
+    /** The page a paint failed on. */
+    page?: number;
+}
+/** The `onError` hook every surface takes. */
+export type EditorErrorHandler = (err: EditorError) => void;
+/**
+ * Report `err`, or log it when nothing is listening: a failure the package
+ * recovered from is worth seeing in a console.
+ *
+ * A throwing handler is the consumer's bug and must not become the package's: it
+ * is caught, because every call site sits on a recovery path where a second throw
+ * would undo the recovery.
+ */
+export declare function reportError(handler: EditorErrorHandler | undefined, err: EditorError): void;
+/** A thrown value's message, for the `message` field. */
+export declare function errorMessage(e: unknown): string;

package/dist/core/errors.js

@@ -0,0 +1,24 @@
+/**
+ * Report `err`, or log it when nothing is listening: a failure the package
+ * recovered from is worth seeing in a console.
+ *
+ * A throwing handler is the consumer's bug and must not become the package's: it
+ * is caught, because every call site sits on a recovery path where a second throw
+ * would undo the recovery.
+ */
+export function reportError(handler, err) {
+    if (!handler) {
+        console.error(`[quillmark/ui] ${err.code}: ${err.message}`, err.cause);
+        return;
+    }
+    try {
+        handler(err);
+    }
+    catch (e) {
+        console.error(`[quillmark/ui] onError handler threw while reporting ${err.code}`, e);
+    }
+}
+/** A thrown value's message, for the `message` field. */
+export function errorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/core/index.d.ts

@@ -0,0 +1,5 @@
+import './theme.css';
+export { init } from './lifecycle.js';
+export type { DocPath, Place } from './address.js';
+export { fieldPathForAddr, addrForFieldPath } from './address.js';
+export type { EditorError, EditorErrorCode, EditorErrorHandler } from './errors.js';

package/dist/core/index.js

@@ -0,0 +1,19 @@
+// The theme derivation: the public dials → the private `--_qm-*` scale, applied
+// to every `data-qm-root` element. Imported HERE because `core/` is the one module
+// both `preview/` and `visual/` already pull, so a consumer cannot forget it and
+// the derivation is minted once rather than re-declared per detached root
+// (THEMING.md).
+import './theme.css';
+// `@quillmark/svelte/core`: what this package OWNS at the substrate seam.
+//
+// The `@quillmark/wasm` API is not re-exported: import it straight from the peer
+// dependency, the single source of truth (quiver states the same rule). The
+// handles cross this package's surfaces untouched (no wrapper types, per
+// DOCUMENT_MODEL §What the editor owns), so the boundary needs no second door
+// here. What earns a line is what more than one surface speaks and no other
+// package declares: the address vocabulary and the error channel, plus the WASM
+// init gate.
+export { init } from './lifecycle.js';
+// The hop between that vocabulary and the `Addr` the document verbs take, both
+// directions: a host handed a path by a hook and holding a mutator needs it.
+export { fieldPathForAddr, addrForFieldPath } from './address.js';

package/dist/core/lifecycle.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Instantiate the core WASM build. Await once before any other boundary verb,
+ * from any surface's setup path; the promise is memoized, so concurrent callers
+ * share one instantiation and repeat calls are free. A failed init clears the
+ * memo, leaving a retry possible.
+ */
+export declare function init(): Promise<void>;

package/dist/core/lifecycle.js

@@ -0,0 +1,21 @@
+// `@quillmark/wasm` ships wasm-bindgen's web target: the core build is
+// instantiated by an explicit `await init()`, and every export throws
+// `runtime::not_initialized` until it resolves. Instantiation carries the panic
+// hook on its start section, so a Rust panic reaches JS as a stack trace.
+import { init as initWasm } from '@quillmark/wasm';
+let started;
+/**
+ * Instantiate the core WASM build. Await once before any other boundary verb,
+ * from any surface's setup path; the promise is memoized, so concurrent callers
+ * share one instantiation and repeat calls are free. A failed init clears the
+ * memo, leaving a retry possible.
+ */
+export function init() {
+    if (started)
+        return started;
+    started = initWasm().catch((err) => {
+        started = undefined;
+        throw err;
+    });
+    return started;
+}

package/dist/core/rebind.svelte.d.ts

@@ -0,0 +1,18 @@
+import { type EditorErrorHandler } from './errors.js';
+/** The once-bound props by name, `onError` among them. */
+export type Bound = Record<string, unknown> & {
+    onError?: EditorErrorHandler;
+};
+/**
+ * Report `rebind-ignored` once, at `dev`, when any prop `snapshot` names is swapped
+ * in place. `remount` closes the message with the surface's own remount spelling
+ * (`Remount the preview ({#key session}) to rebind.`).
+ *
+ * Mounted identities are recorded on the effect's FIRST run, the flush the surface
+ * binds in; every later comparison reads them through the same `snapshot`.
+ *
+ * The report goes to the SNAPSHOT's `onError`: every other error these surfaces
+ * report reaches the handler they bound, and a swapped `onError` is itself one of
+ * the reports.
+ */
+export declare function guardRebind(snapshot: () => Bound, remount: string): void;

package/dist/core/rebind.svelte.js

@@ -0,0 +1,44 @@
+// The remount contract, enforced. `Preview` binds its props ONCE, in `onMount`, and
+// observes nothing after: the vanilla core below it owns scroll position, mounted
+// slots and observer sets that a remount would discard on every apply. So a prop
+// swapped in place is reported, not dropped in silence.
+//
+// A guard over ONE prop of a set is worse than none: a consumer who learns the
+// surface complains when it ignores a prop reads silence on the rest as reactivity.
+// The snapshot is every once-bound prop, and one report names whichever went stale.
+import { reportError } from './errors.js';
+/**
+ * Report `rebind-ignored` once, at `dev`, when any prop `snapshot` names is swapped
+ * in place. `remount` closes the message with the surface's own remount spelling
+ * (`Remount the preview ({#key session}) to rebind.`).
+ *
+ * Mounted identities are recorded on the effect's FIRST run, the flush the surface
+ * binds in; every later comparison reads them through the same `snapshot`.
+ *
+ * The report goes to the SNAPSHOT's `onError`: every other error these surfaces
+ * report reaches the handler they bound, and a swapped `onError` is itself one of
+ * the reports.
+ */
+export function guardRebind(snapshot, remount) {
+    let mounted;
+    let reported = false;
+    $effect(() => {
+        const live = snapshot();
+        if (mounted === undefined) {
+            mounted = live;
+            return;
+        }
+        if (reported)
+            return;
+        const bound = mounted;
+        const stale = Object.keys(bound).filter((k) => live[k] !== bound[k]);
+        if (stale.length === 0)
+            return;
+        reported = true;
+        reportError(bound.onError, {
+            code: 'rebind-ignored',
+            severity: 'dev',
+            message: `${stale.join(', ')} swapped in place; the mounted surface still holds what it bound at mount. ${remount}`
+        });
+    });
+}

package/dist/core/teardown.d.ts

@@ -0,0 +1,20 @@
+/** A surface's lifespan: alive from construction until {@link Lifespan.end}. */
+export interface Lifespan {
+    /** False once the span has ended. */
+    readonly alive: boolean;
+    /**
+     * Register work to undo at the end: a registry entry to drop, a timer or frame
+     * to cancel, a handle to free. Cancellers run in REGISTRATION order, which is
+     * where the order lives. Registering on an ended span runs the canceller at
+     * once: there is no later run to hold it for.
+     */
+    onEnd(cancel: () => void): void;
+    /**
+     * Await `pending`, then report whether the surface survived the window. `false`
+     * is a continuation to drop: what it captured before the await is gone.
+     */
+    resumes(pending: Promise<unknown>): Promise<boolean>;
+    /** Run the cancellers once and end the span. Idempotent. */
+    end(): void;
+}
+export declare function createLifespan(): Lifespan;

package/dist/core/teardown.js

@@ -0,0 +1,37 @@
+// The teardown order every surface holds: unregister, cancel, then free.
+//
+// An order rather than a list, because work is deferred: a surface that frees
+// first leaves a scheduled continuation holding what nobody owns, and one that
+// cancels first but stays registered still takes the next event.
+//
+// `Lifespan` carries it. A surface builds one, registers its cancellers in the
+// order they must run, and ends the span once; continuations that cross an await
+// ask `resumes()` rather than a flag they captured before it.
+export function createLifespan() {
+    let alive = true;
+    const cancels = [];
+    return {
+        get alive() {
+            return alive;
+        },
+        onEnd(cancel) {
+            if (!alive)
+                return void cancel();
+            cancels.push(cancel);
+        },
+        async resumes(pending) {
+            await pending;
+            return alive;
+        },
+        end() {
+            if (!alive)
+                return;
+            // Dead BEFORE the cancellers run: one of them may synchronously reach
+            // something that asks, and a span mid-teardown is not alive.
+            alive = false;
+            for (const cancel of cancels)
+                cancel();
+            cancels.length = 0;
+        }
+    };
+}