@0001-labs/design-system-1 0.3.0-alpha.28 → 0.3.0

package/dist/0-face/cut-fade.js

@@ -0,0 +1,274 @@
+/**
+ * Cut words fade, never an ellipsis. Wherever Design system 1 cuts words that do
+ * not fit (a row's name, a tag, a menu entry, a calendar's title), they fade out
+ * over their last square (`var(--ds-unit)`), a mask on the words, so they fade
+ * into whatever is behind them. Words that fit stay crisp: the fade is drawn
+ * only while an element is marked `data-cut="end"`, and this module is what
+ * measures and marks it.
+ *
+ * Every stylesheet writes the fade the same way: the element clips
+ * (`text-overflow: clip`), and only under `[data-cut="end"]` takes
+ * `mask-image: linear-gradient(to right, #000 calc(100% - var(--ds-unit)), transparent)`,
+ * the gradient running to the left in a right-to-left page.
+ *
+ * - `watchCuts()` is the watcher a component owns: it marks the elements it
+ *   watches while `scrollWidth > clientWidth + 1`, measures again when they
+ *   resize, when `measure()` is called (after a render, since words can change
+ *   without the box resizing), once the page's fonts have loaded and, with
+ *   `text: true`, when the words inside them change. `disconnect()` lets go.
+ * - Every watcher measures in the next frame, together with every other one:
+ *   all widths are read, then all marks written, so a page building a few
+ *   hundred words lays itself out once for them rather than once each. Read
+ *   one by one, after each element connected or updated, the words of Ezo's
+ *   landing page laid it out again two hundred times, over half a second.
+ *   Elements that resize are measured the same way, in one pass for all.
+ * - `CutFades` is the same watcher as a Lit reactive controller: it starts when
+ *   its element connects, measures after every update and stops when it
+ *   disconnects.
+ * - `startCutFades()` is for a page without Lit: it marks DS1's native classes
+ *   (`.ds-row__name`, `.ds-sidebar__label`, `.ds-menu__item`, …) in the page,
+ *   and keeps marking them as the page changes. It returns a function that
+ *   stops it.
+ */
+/** The attribute a cut element carries: `data-cut="end"`. */
+export const CUT_ATTRIBUTE = "data-cut";
+/**
+ * The native classes DS1's stylesheets fade when they are marked cut, for
+ * `startCutFades()` on a page without Lit.
+ */
+export const CUT_FADE_SELECTOR = [
+    ".ds-row__name",
+    ".ds-sidebar__label",
+    ".ds-menu__item",
+    ".ds-badge__label",
+    ".ds-notice__title",
+    ".ds-notice__text",
+    ".ds-progress__label",
+    ".ds-stat__figure",
+    ".ds-document__toc-list a",
+    ".ds-footer__links a",
+    ".item-text",
+].join(", ");
+/** Whether an element's words are wider than its box. */
+export function isCut(element) {
+    return element.scrollWidth > element.clientWidth + 1;
+}
+/** Marks an element `data-cut="end"` while its words do not fit, and takes the mark off when they do. Returns whether it is cut. */
+export function markCut(element) {
+    const cut = isCut(element);
+    const mark = element.getAttribute(CUT_ATTRIBUTE);
+    if (cut) {
+        if (mark !== "end")
+            element.setAttribute(CUT_ATTRIBUTE, "end");
+    }
+    else if (mark === "end")
+        element.removeAttribute(CUT_ATTRIBUTE);
+    return cut;
+}
+/** Reads every element's widths first, then writes every mark, so the page is laid out once for all of them. */
+function markAll(elements) {
+    const cuts = [];
+    for (const element of elements)
+        if (element.isConnected)
+            cuts.push([element, isCut(element)]);
+    hookFonts();
+    for (const [element, cut] of cuts) {
+        const mark = element.getAttribute(CUT_ATTRIBUTE);
+        if (cut) {
+            if (mark !== "end")
+                element.setAttribute(CUT_ATTRIBUTE, "end");
+        }
+        else if (mark === "end")
+            element.removeAttribute(CUT_ATTRIBUTE);
+    }
+}
+const live = new Set();
+const queued = new Set();
+let frame = false;
+const nextFrame = (run) => {
+    if (typeof requestAnimationFrame === "function")
+        requestAnimationFrame(run);
+    else
+        setTimeout(run, 0);
+};
+function flush() {
+    frame = false;
+    const watchers = [...queued];
+    queued.clear();
+    const elements = new Set();
+    for (const watcher of watchers) {
+        if (watcher.stopped)
+            continue;
+        for (const element of watcher.refresh())
+            elements.add(element);
+    }
+    markAll(elements);
+}
+/** Measures this watcher in the next frame, with every other watcher waiting for it. */
+function schedule(watcher) {
+    if (watcher.stopped)
+        return;
+    queued.add(watcher);
+    if (frame)
+        return;
+    frame = true;
+    nextFrame(flush);
+}
+// One observer for every watched element: the sizes of a frame arrive in one
+// call, read in one pass. An element two watchers hold (a row's name, which the
+// row and its ds-text both watch) is let go when the last one does.
+let sizes;
+const holders = new Map();
+function observe(element) {
+    if (typeof ResizeObserver === "undefined")
+        return;
+    sizes ?? (sizes = new ResizeObserver(entries => markAll(entries.map(entry => entry.target))));
+    const held = holders.get(element) ?? 0;
+    if (!held)
+        sizes.observe(element);
+    holders.set(element, held + 1);
+}
+function unobserve(element) {
+    const held = holders.get(element);
+    if (!held)
+        return;
+    if (held > 1) {
+        holders.set(element, held - 1);
+        return;
+    }
+    holders.delete(element);
+    sizes?.unobserve(element);
+}
+// Words drawn in a fallback face are narrower or wider once the page's fonts
+// arrive. Asking for `document.fonts.ready` lays out a page that has changed,
+// so it is asked once, while a measure has just laid the page out anyway.
+let fontsHooked = false;
+function hookFonts() {
+    if (fontsHooked || typeof document === "undefined")
+        return;
+    fontsHooked = true;
+    const again = () => { for (const watcher of live)
+        schedule(watcher); };
+    const fonts = document.fonts;
+    fonts?.ready?.then(again, () => { });
+    fonts?.addEventListener?.("loadingdone", again);
+}
+/** A watcher that marks the elements it watches `data-cut="end"` while their words do not fit. */
+export function watchCuts(options = {}) {
+    const sources = [];
+    let watched = new Set();
+    const words = options.text && typeof MutationObserver !== "undefined"
+        ? new MutationObserver(() => schedule(self))
+        : undefined;
+    const collect = () => {
+        const found = new Set();
+        for (const source of sources) {
+            const elements = typeof source === "function" ? source() : source instanceof Element ? [source] : source;
+            for (const element of elements)
+                found.add(element);
+        }
+        return found;
+    };
+    const self = {
+        stopped: false,
+        refresh() {
+            const next = collect();
+            let changed = next.size !== watched.size;
+            for (const element of watched) {
+                if (!next.has(element)) {
+                    unobserve(element);
+                    changed = true;
+                }
+            }
+            for (const element of next) {
+                if (!watched.has(element)) {
+                    observe(element);
+                    changed = true;
+                }
+            }
+            // A MutationObserver cannot let one element go, so it starts again when the set changes.
+            if (words && changed) {
+                words.disconnect();
+                for (const element of next)
+                    words.observe(element, { childList: true, characterData: true, subtree: true });
+            }
+            watched = next;
+            return watched;
+        },
+    };
+    live.add(self);
+    return {
+        watch(source) { sources.push(source); schedule(self); },
+        select(root, selector) { sources.push(() => root.querySelectorAll(selector)); schedule(self); },
+        measure() { schedule(self); },
+        disconnect() {
+            self.stopped = true;
+            live.delete(self);
+            queued.delete(self);
+            for (const element of watched)
+                unobserve(element);
+            words?.disconnect();
+            watched = new Set();
+            sources.length = 0;
+        },
+    };
+}
+/**
+ * The cut-words watcher as a Lit reactive controller:
+ * `protected readonly cuts = new CutFades(this, { selector: ".label" })`. It watches from
+ * when the element connects to when it disconnects, and measures after every
+ * update; call `measure()` when words change outside an update.
+ */
+export class CutFades {
+    constructor(host, options) {
+        this.host = host;
+        this.options = options;
+        host.addController(this);
+    }
+    hostConnected() {
+        this.hostDisconnected();
+        const watcher = watchCuts();
+        const { selector, targets, text } = this.options;
+        if (selector)
+            watcher.watch(() => (this.host.renderRoot ?? this.host).querySelectorAll(selector));
+        if (targets)
+            watcher.watch(targets);
+        this.watcher = watcher;
+        // Words slotted into the element can change without an update or a resize.
+        if (text && typeof MutationObserver !== "undefined") {
+            this.words = new MutationObserver(() => this.measure());
+            this.words.observe(this.host, { childList: true, characterData: true, subtree: true });
+        }
+    }
+    hostUpdated() { this.measure(); }
+    hostDisconnected() {
+        this.words?.disconnect();
+        this.words = undefined;
+        this.watcher?.disconnect();
+        this.watcher = undefined;
+    }
+    /** Measures again, as after an update. */
+    measure() { this.watcher?.measure(); }
+}
+/**
+ * Marks DS1's native classes cut on a page without Lit, so their words fade
+ * where they are cut, and keeps marking them as the page changes. Returns a
+ * function that stops it.
+ *
+ * @example
+ * // A module script on the page, beside one.css and controls.css (Sync 1 `root` `"modules": ["cut-fade"]`):
+ * startCutFades();
+ */
+export function startCutFades(root = document, selector = CUT_FADE_SELECTOR) {
+    const watcher = watchCuts();
+    watcher.select(root, selector);
+    // The page is marked as it starts, in one pass; its changes are measured in the frame after them.
+    markAll(root.querySelectorAll(selector));
+    const changes = typeof MutationObserver === "undefined" ? undefined : new MutationObserver(() => watcher.measure());
+    const node = root instanceof Document ? root.documentElement : root;
+    changes?.observe(node, { childList: true, characterData: true, subtree: true });
+    return () => {
+        changes?.disconnect();
+        watcher.disconnect();
+    };
+}

package/dist/0-face/define.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../DS1/0-face/define.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAG5E"}
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../DS1/0-face/define.ts"],"names":[],"mappings":"AASA,gFAAgF;AAChF,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAsB5E"}

package/dist/0-face/define.js

@@ -1,7 +1,28 @@
 /** Register a shared element once; a fresh page picks up changes during HMR. */
 export function define(name, element) {
-    if (typeof customElements === "undefined")
+    if (typeof customElements === 'undefined' || customElements.get(name))
         return;
-    if (!customElements.get(name))
-        customElements.define(name, element);
+    const type = element;
+    const prototype = element.prototype;
+    const original = prototype.createRenderRoot;
+    if (original) {
+        const definingDocument = document;
+        prototype.createRenderRoot = function () {
+            var _a;
+            if (this.ownerDocument === definingDocument || !type.elementStyles?.length)
+                return original.call(this);
+            // Constructed sheets cannot cross documents. The exact finalized component
+            // styles can, as ordinary style nodes in the owning document's shadow root.
+            const root = this.shadowRoot ?? this.attachShadow(type.shadowRootOptions ?? { mode: 'open' });
+            for (const sheet of type.elementStyles) {
+                const style = this.ownerDocument.createElement('style');
+                style.textContent = sheet.cssText ?? Array.from(sheet.cssRules ?? [], rule => rule.cssText).join('\n');
+                root.append(style);
+            }
+            if (this.renderOptions)
+                (_a = this.renderOptions).renderBefore ?? (_a.renderBefore = root.firstChild);
+            return root;
+        };
+    }
+    customElements.define(name, element);
 }

package/dist/0-face/face-correction.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A face Design system 1 did not draw, set on the sixteen: its `@font-face` corrected once so that at 14px on a
+ * 16px line its capitals are 10px tall and its baseline stands 3px above the square's foot, as GT America's do
+ * (https://designsystem1.com/1-root/constraints/#a-face-you-add). Plain TypeScript with no imports, for the
+ * browser and for a build script alike.
+ *
+ * A face's metrics are fractions of its em: the ascent and descent the browser sets a line with and the height
+ * of its capitals (`readFaceMetrics` takes them from a TrueType or OpenType file). `google-face-metrics.json`
+ * beside this module holds them for the Google faces 0001's products offer; `scripts/face-metrics.mjs` measures
+ * more. Correct the face, never its words: no padding, `top` or transform in a component.
+ */
+/** A face's vertical metrics, each over its em. */
+export interface FaceMetrics {
+    ascent: number;
+    descent: number;
+    capHeight: number;
+}
+/** GT America's: capitals 0.71 of the em, and its ascent less its descent, which places the baseline in a line. */
+export declare const SIXTEEN_FACE: {
+    readonly capHeight: 0.71;
+    readonly baseline: 0.742;
+};
+/** The four `@font-face` descriptors that put a face on the sixteen, as CSS values. */
+export interface FaceDescriptors {
+    sizeAdjust: string;
+    ascentOverride: string;
+    descentOverride: string;
+    lineGapOverride: string;
+}
+/**
+ * The descriptors for a face: `size-adjust` makes its capitals 0.71 of the em, and the overrides make its ascent
+ * less its descent 0.742 while it keeps its own height of ascent and descent. `size-adjust` scales the overrides
+ * too, so they are given before it.
+ */
+export declare function faceDescriptors({ ascent, descent, capHeight }: FaceMetrics): FaceDescriptors;
+/** The descriptors as declarations for an `@font-face` rule. */
+export declare function faceCorrection(metrics: FaceMetrics): string;
+/**
+ * A stylesheet of `@font-face` rules (Google's css2 answer, say) with every face corrected in its own rule,
+ * without comments or spaces. A face with no metrics stops it: an uncorrected face would stand off the sixteen.
+ */
+export declare function correctFaces(css: string, metrics: Readonly<Record<string, FaceMetrics>>): string;
+/** Google's css2 stylesheet at `href`, read and corrected. css2 answers with woff2 to the browser asking. */
+export declare function correctedGoogleFonts(href: string, metrics: Readonly<Record<string, FaceMetrics>>, init?: RequestInit): Promise<string>;
+/**
+ * The metrics a browser sets a line of the face with, from its TrueType or OpenType file (not woff2): `hhea`'s
+ * ascent and descent, or `OS/2`'s typographic ones when the face asks for them (USE_TYPO_METRICS), and `OS/2`'s
+ * cap height, each over `head`'s units per em, to four places.
+ */
+export declare function readFaceMetrics(file: Uint8Array): FaceMetrics;
+//# sourceMappingURL=face-correction.d.ts.map

package/dist/0-face/face-correction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-correction.d.ts","sourceRoot":"","sources":["../../DS1/0-face/face-correction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mHAAmH;AACnH,eAAO,MAAM,YAAY;;;CAAgD,CAAC;AAE1E,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,WAAW,GAAG,eAAe,CAW5F;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAG3D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,GAAG,MAAM,CAMhG;AAED,6GAA6G;AAC7G,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAI5I;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,CAiB7D"}

package/dist/0-face/face-correction.js

@@ -0,0 +1,80 @@
+/**
+ * A face Design system 1 did not draw, set on the sixteen: its `@font-face` corrected once so that at 14px on a
+ * 16px line its capitals are 10px tall and its baseline stands 3px above the square's foot, as GT America's do
+ * (https://designsystem1.com/1-root/constraints/#a-face-you-add). Plain TypeScript with no imports, for the
+ * browser and for a build script alike.
+ *
+ * A face's metrics are fractions of its em: the ascent and descent the browser sets a line with and the height
+ * of its capitals (`readFaceMetrics` takes them from a TrueType or OpenType file). `google-face-metrics.json`
+ * beside this module holds them for the Google faces 0001's products offer; `scripts/face-metrics.mjs` measures
+ * more. Correct the face, never its words: no padding, `top` or transform in a component.
+ */
+/** GT America's: capitals 0.71 of the em, and its ascent less its descent, which places the baseline in a line. */
+export const SIXTEEN_FACE = { capHeight: 0.71, baseline: 0.742 };
+/**
+ * The descriptors for a face: `size-adjust` makes its capitals 0.71 of the em, and the overrides make its ascent
+ * less its descent 0.742 while it keeps its own height of ascent and descent. `size-adjust` scales the overrides
+ * too, so they are given before it.
+ */
+export function faceDescriptors({ ascent, descent, capHeight }) {
+    if (!(capHeight > 0) || !(ascent + descent > 0))
+        throw new Error('A face needs a cap height and a line height');
+    const size = SIXTEEN_FACE.capHeight / capHeight;
+    const height = Math.max((ascent + descent) * size, SIXTEEN_FACE.baseline);
+    const percent = (value) => `${+(value * 100).toFixed(2)}%`;
+    return {
+        sizeAdjust: percent(size),
+        ascentOverride: percent((height + SIXTEEN_FACE.baseline) / 2 / size),
+        descentOverride: percent((height - SIXTEEN_FACE.baseline) / 2 / size),
+        lineGapOverride: '0%',
+    };
+}
+/** The descriptors as declarations for an `@font-face` rule. */
+export function faceCorrection(metrics) {
+    const { sizeAdjust, ascentOverride, descentOverride, lineGapOverride } = faceDescriptors(metrics);
+    return `size-adjust:${sizeAdjust};ascent-override:${ascentOverride};descent-override:${descentOverride};line-gap-override:${lineGapOverride}`;
+}
+/**
+ * A stylesheet of `@font-face` rules (Google's css2 answer, say) with every face corrected in its own rule,
+ * without comments or spaces. A face with no metrics stops it: an uncorrected face would stand off the sixteen.
+ */
+export function correctFaces(css, metrics) {
+    return css.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\s*([{};:,])\s*/g, '$1').trim().replace(/@font-face{([^}]*)}/g, (_, body) => {
+        const family = body.match(/font-family:(['"]?)([^;'"]+)\1(?:;|$)/)?.[2];
+        if (!family || !Object.hasOwn(metrics, family))
+            throw new Error(`No metrics for the face ${family ?? '(unnamed)'}`);
+        return `@font-face{${body}${body.endsWith(';') ? '' : ';'}${faceCorrection(metrics[family])}}`;
+    });
+}
+/** Google's css2 stylesheet at `href`, read and corrected. css2 answers with woff2 to the browser asking. */
+export async function correctedGoogleFonts(href, metrics, init) {
+    const response = await fetch(href, init);
+    if (!response.ok)
+        throw new Error(`Google Fonts answered ${response.status} for ${href}`);
+    return correctFaces(await response.text(), metrics);
+}
+/**
+ * The metrics a browser sets a line of the face with, from its TrueType or OpenType file (not woff2): `hhea`'s
+ * ascent and descent, or `OS/2`'s typographic ones when the face asks for them (USE_TYPO_METRICS), and `OS/2`'s
+ * cap height, each over `head`'s units per em, to four places.
+ */
+export function readFaceMetrics(file) {
+    const view = new DataView(file.buffer, file.byteOffset, file.byteLength);
+    const tables = new Map();
+    for (let i = 0, count = view.getUint16(4); i < count; i++) {
+        const at = 12 + i * 16;
+        tables.set(String.fromCharCode(...file.subarray(at, at + 4)), view.getUint32(at + 8));
+    }
+    const head = tables.get('head'), hhea = tables.get('hhea'), os2 = tables.get('OS/2');
+    if (head === undefined || hhea === undefined || os2 === undefined)
+        throw new Error('Not a TrueType or OpenType face');
+    const em = view.getUint16(head + 18);
+    const typo = (view.getUint16(os2 + 62) & 0x80) !== 0;
+    const ascent = typo ? view.getInt16(os2 + 68) : view.getInt16(hhea + 4);
+    const descent = -(typo ? view.getInt16(os2 + 70) : view.getInt16(hhea + 6));
+    const capHeight = view.getUint16(os2) >= 2 ? view.getInt16(os2 + 88) : 0;
+    if (!capHeight)
+        throw new Error('The face has no cap height in OS/2');
+    const fraction = (value) => Math.round((value / em) * 10000) / 10000;
+    return { ascent: fraction(ascent), descent: fraction(descent), capHeight: fraction(capHeight) };
+}

package/dist/0-face/failures.d.ts

@@ -0,0 +1,16 @@
+/** A real operation failure, separate from validation, warnings and message colour.
+ * Applications subscribe to `ds-failure`; this module never sends network requests.
+ * Use an authored, stable code and summary, never user content or a server response.
+ */
+export interface Failure {
+    code: string;
+    message: string;
+    /** Original caught error; only its stack frames enter the diagnostic. */
+    error?: unknown;
+    /** Captured at reporting time so startup handoff keeps the original call site. */
+    stack?: string;
+}
+export declare const FAILURE_EVENT = "ds-failure";
+/** Report a failed operation. Safe during server rendering; no DOM text is read. */
+export declare function reportFailure(failure: Failure): void;
+//# sourceMappingURL=failures.d.ts.map

package/dist/0-face/failures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failures.d.ts","sourceRoot":"","sources":["../../DS1/0-face/failures.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,eAAO,MAAM,aAAa,eAAe,CAAC;AAI1C,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAcpD"}

package/dist/0-face/failures.js

@@ -0,0 +1,21 @@
+export const FAILURE_EVENT = "ds-failure";
+/** A bounded handoff for failures shown before the application reporter starts. */
+const PENDING = Symbol.for("design-system-1.pending-failures");
+/** Report a failed operation. Safe during server rendering; no DOM text is read. */
+export function reportFailure(failure) {
+    if (typeof window === "undefined" || typeof failure?.code !== "string" || typeof failure.message !== "string" || !/^[a-z][a-z0-9_.-]{0,79}$/.test(failure.code) || !failure.message.trim())
+        return;
+    const source = failure.error instanceof Error ? failure.error : new Error();
+    const stack = (failure.stack ?? source.stack ?? "").split("\n")
+        .filter(line => /^\s*at\s/.test(line) || /@.*:\d+/.test(line))
+        .slice(0, 8).join("\n").trim().slice(0, 500);
+    const detail = { code: failure.code, message: failure.message.trim().slice(0, 200), ...(stack ? { stack } : {}) };
+    // A reporter acknowledges by preventing the default: queueing for later.
+    if (window.dispatchEvent(new CustomEvent(FAILURE_EVENT, { detail, cancelable: true }))) {
+        const scope = globalThis;
+        const pending = scope[PENDING] ?? (scope[PENDING] = []);
+        pending.push(detail);
+        if (pending.length > 20)
+            pending.shift();
+    }
+}

package/dist/0-face/feedback-overlays.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feedback-overlays.d.ts","sourceRoot":"","sources":["../../DS1/0-face/feedback-overlays.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kHAAkH;IAClH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mHAAmH;IACnH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsID,uFAAuF;AACvF,wBAAgB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAInE;AAED,qFAAqF;AACrF,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI1E;AAED,sFAAsF;AACtF,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQ9E"}
+{"version":3,"file":"feedback-overlays.d.ts","sourceRoot":"","sources":["../../DS1/0-face/feedback-overlays.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kHAAkH;IAClH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mHAAmH;IACnH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAwID,uFAAuF;AACvF,wBAAgB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAInE;AAED,qFAAqF;AACrF,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI1E;AAED,sFAAsF;AACtF,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQ9E"}

package/dist/0-face/feedback-overlays.js

@@ -3,7 +3,7 @@
  * `confirm()` and `prompt()`, for pages without Lit or any other framework.
  *
  * Each is drawn on the native `dialog.ds-overlay` frame from `1-root/controls.css`
- * (which the page loads) with its native buttons, `.ds-button--primary`,
+ * (which the page loads), as a sheet from the screen's foot on a phone, with its native buttons, `.ds-button--primary`,
  * `--secondary` and `--danger`, and opened with `showModal()`, so the browser
  * keeps the rest of the page inert behind it. Their words default to the
  * shared words (OK, Cancel) in the page's language where the page loads the
@@ -59,8 +59,10 @@ function show(spec) {
     return new Promise(resolve => {
         const id = `ds-feedback-${++count}`;
         const opener = focused();
+        // A sheet from the foot of a phone's screen, never a modal there (Joachim, 20 October 2026).
+        const phone = typeof matchMedia === "function" && matchMedia("(max-width: 768px)").matches;
         const dialog = element("dialog", {
-            class: "ds-overlay",
+            class: phone ? "ds-overlay ds-overlay--sheet" : "ds-overlay",
             role: spec.kind === "prompt" ? "dialog" : "alertdialog",
             "aria-labelledby": `${id}-title`,
             "data-ds-feedback": spec.kind,
@@ -88,7 +90,7 @@ function show(spec) {
         }
         const footer = element("div", { "data-ds-overlay": "footer" });
         const cancel = spec.cancel === undefined ? undefined : element("button", { type: "button", class: "ds-button ds-button--secondary", value: "cancel" }, spec.cancel);
-        const confirm = element("button", { type: "button", class: spec.danger ? "ds-button ds-button--secondary ds-button--danger" : "ds-button ds-button--primary", value: "confirm" }, spec.confirm);
+        const confirm = element("button", { type: "button", class: spec.danger ? "ds-button ds-button--danger" : "ds-button ds-button--primary", value: "confirm" }, spec.confirm);
         if (cancel)
             footer.appendChild(cancel);
         footer.appendChild(confirm);

package/dist/0-face/feedback.d.ts

@@ -38,4 +38,6 @@ export { copyText } from "./copy-text";
 export type { CopyTextOptions } from "./copy-text";
 export { setFeedbackWords } from "./feedback-words";
 export type { FeedbackWord, FeedbackWords } from "./feedback-words";
+export { reportFailure, FAILURE_EVENT } from "./failures";
+export type { Failure } from "./failures";
 //# sourceMappingURL=feedback.d.ts.map

package/dist/0-face/feedback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../DS1/0-face/feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACjE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACnI,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../DS1/0-face/feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACjE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACnI,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEpE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC1D,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/dist/0-face/feedback.js

@@ -33,3 +33,4 @@ export { configureToaster, pageToaster, toast } from "./toaster";
 export { alert, confirm, prompt } from "./feedback-overlays";
 export { copyText } from "./copy-text";
 export { setFeedbackWords } from "./feedback-words";
+export { reportFailure, FAILURE_EVENT } from "./failures";

package/dist/0-face/focus.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Image focus: where a photo's subject is, so a picture cut to its box
+ * (`object-fit: cover`) keeps it in view instead of its middle. A person's
+ * face first, then whatever in the picture holds the most detail. Plain
+ * TypeScript with no imports, for the browser and for a build script alike.
+ *
+ * The focus is a point of the picture, across and down from 0 to 1, and it is
+ * written as the picture's `object-position` (`objectPosition()`), so a
+ * cover crop of any shape keeps that point in view. Work it out once, where
+ * the page is built, and write it into the markup, so the first paint is
+ * already cut right. On a Mac, `focus-vision.swift` finds the faces and the
+ * salient part with Apple's Vision framework, and `focusFromRegions()` turns
+ * them into the focus; elsewhere, or where it finds nothing, `focusOf()`
+ * reads the pixels:
+ *
+ * ```ts
+ * // swift 0-face/focus-vision.swift *.jpg > regions.json
+ * import { focusFromRegions, focusOf, objectPosition } from "./0-face/focus.ts";
+ * const focus = focusFromRegions(regions[name]) ?? focusOf(data, info.width, info.height, info.channels);
+ * // <img src="…" style="object-position: 50% 18%">
+ * ```
+ *
+ * A page with no build step marks a picture `data-ds-focus="auto"` and calls
+ * `startFocus()`: once the picture has loaded, its focus is found and kept in
+ * the browser, so it is right from the first paint on the next visit. A
+ * picture whose focus a person chose says so, `data-ds-focus="40% 20%"`, and
+ * is never measured. A picture from another host without CORS cannot be read
+ * and keeps its middle.
+ */
+/** A point of a picture, across (`x`) and down (`y`), each from 0 to 1. */
+export interface Focus {
+    x: number;
+    y: number;
+}
+export declare const CENTRE: Focus;
+/** The width a picture is measured at; enough to find a face, and cheap. */
+export declare const FOCUS_SAMPLE = 64;
+/**
+ * The focus of a picture from its pixels (RGB or RGBA, row by row), measured
+ * small (about `FOCUS_SAMPLE` across). Skin that gathers into a face wins:
+ * the highest band of rows dense with skin, since a face stands above hands
+ * and arms. Without one, the centre of the picture's detail (where neighbouring
+ * pixels differ most), drawn a little towards the middle so a busy edge does
+ * not take the crop.
+ */
+export declare function focusOf(pixels: ArrayLike<number>, width: number, height: number, channels?: number): Focus;
+/** A part of a picture, as fractions of it from its top left corner. */
+export interface Region {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * The focus from what a detector found (`focus-vision.swift`: Apple's face
+ * detection and attention-based saliency), or `undefined` when it found
+ * nothing. Faces win: the point between them across, and down a little above
+ * the top of the highest, so a crop keeps the heads whole with room above
+ * them. Otherwise the middle of everything salient.
+ */
+export declare function focusFromRegions(found: {
+    faces?: Region[];
+    salient?: Region[];
+}): Focus | undefined;
+/** The focus as CSS `object-position`, in whole percents. */
+export declare function objectPosition(focus: Focus): string;
+/** Finds and sets the focus of one picture marked `data-ds-focus="auto"`, once it has loaded. */
+export declare function focusImage(image: HTMLImageElement): void;
+/** Sets the focus of every picture marked `data-ds-focus` in `root`. */
+export declare function startFocus(root?: ParentNode): void;
+//# sourceMappingURL=focus.d.ts.map

package/dist/0-face/focus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../../DS1/0-face/focus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IAAG,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE;AAE/C,eAAO,MAAM,MAAM,EAAE,KAA0B,CAAC;AAEhD,4EAA4E;AAC5E,eAAO,MAAM,YAAY,KAAK,CAAC;AAY/B;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,KAAK,CAqDrG;AAED,wEAAwE;AACxE,MAAM,WAAW,MAAM;IAAG,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE;AAEtE;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,KAAK,GAAG,SAAS,CAkBnG;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAEnD;AAID,iGAAiG;AACjG,wBAAgB,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CA0BxD;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAE5D"}