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

package/dist/0-face/fault-lines.js

@@ -0,0 +1,172 @@
+const tolerance = 1;
+const near = (a, b) => Math.abs(a - b) <= tolerance;
+const style = (el) => el.ownerDocument.defaultView.getComputedStyle(el);
+const visible = (el) => {
+    const box = el.getBoundingClientRect();
+    return box.width > 0 && box.height > 0 && style(el).visibility !== 'hidden' && style(el).display !== 'none';
+};
+/** Walk each open shadow tree once; slotted children already occur in the light tree. */
+function elements(root) {
+    return Array.from(root.querySelectorAll('*')).flatMap(el => [el, ...(el.shadowRoot ? elements(el.shadowRoot) : [])]);
+}
+/** Related grids opt in by name; unlabelled card grids are candidates for human review. */
+export function faultLineGrids(root) {
+    return elements(root).flatMap(element => {
+        const family = element.getAttribute('data-ds-fault-lines');
+        if (family === 'off' || !visible(element))
+            return [];
+        const children = Array.from(element.children).filter(visible);
+        if (!children.length)
+            return [];
+        if (family === null && (!/grid/.test(style(element).display) || children.length < 2 ||
+            !children.every(child => child.matches('ds-card, .ds-card, ds-button, button'))))
+            return [];
+        const axis = element.getAttribute('data-ds-fault-axis') === 'y' ? 'y' : 'x';
+        const boxes = children.map(child => child.getBoundingClientRect());
+        const crossStart = (box) => axis === 'x' ? box.top : box.left;
+        const crossEnd = (box) => axis === 'x' ? box.bottom : box.right;
+        const start = (box) => axis === 'x' ? box.left : box.top;
+        const end = (box) => axis === 'x' ? box.right : box.bottom;
+        const bands = [];
+        for (const box of boxes.sort((a, b) => crossStart(a) - crossStart(b))) {
+            const band = bands.find(row => near(crossStart(row[0]), crossStart(box)));
+            if (band)
+                band.push(box);
+            else
+                bands.push([box]);
+        }
+        // The fullest band defines the tracks; an incomplete final row is valid.
+        const band = [...bands].sort((a, b) => b.length - a.length)[0].sort((a, b) => start(a) - start(b));
+        const lines = band.flatMap(box => [start(box), end(box)]);
+        const gaps = band.slice(1).map((box, index) => start(box) - end(band[index]));
+        const crossGaps = bands.slice(1).map((row, index) => Math.min(...row.map(crossStart)) - Math.max(...bands[index].map(crossEnd)));
+        const internalDrift = bands.some(row => row.length === band.length && row.slice().sort((a, b) => start(a) - start(b)).some((box, index) => !near(start(box), lines[index * 2]) || !near(end(box), lines[index * 2 + 1]))) || crossGaps.some(gap => !near(gap, crossGaps[0]));
+        return [{ element, family, axis, lines, gaps, crossGap: crossGaps[0], internalDrift, start: lines[0], end: lines[lines.length - 1] }];
+    });
+}
+function referenceFor(grids, i) {
+    const current = grids[i];
+    return grids.slice(0, i).find(other => {
+        if (other.axis !== current.axis || other.lines.length !== current.lines.length)
+            return false;
+        if (current.family !== null || other.family !== null)
+            return current.family !== null && current.family === other.family;
+        return near(current.start, other.start) && near(current.end, other.end);
+    });
+}
+/** Fault lines compare rendered tracks across separate sections, in the current viewport. */
+export function inspectFaultLines(root) {
+    const grids = faultLineGrids(root);
+    const findings = [];
+    for (let i = 0; i < grids.length; i++) {
+        const current = grids[i];
+        if (current.internalDrift)
+            findings.push({ element: current.element, ...(current.family === null ? { review: true } : {}), message: `Fault lines at ${current.element.ownerDocument.documentElement.clientWidth}px: tracks or repeated gaps drift inside ${current.family || 'this card grid'}. Align its complete rows and repeated spacing.` });
+        const reference = referenceFor(grids, i);
+        if (!reference)
+            continue;
+        const drift = current.lines.map((line, index) => Math.abs(line - reference.lines[index]));
+        const gapDrift = current.gaps.some((gap, index) => !near(gap, reference.gaps[index]));
+        const rowDrift = current.crossGap !== undefined && reference.crossGap !== undefined && !near(current.crossGap, reference.crossGap);
+        if (!drift.some(value => value > tolerance) && !gapDrift && !rowDrift)
+            continue;
+        const width = current.element.ownerDocument.documentElement.clientWidth;
+        const review = current.family === null;
+        findings.push({ element: current.element, ...(review ? { review: true } : {}), message: `Fault lines at ${width}px: ${current.family || 'these card grids'} ${review ? 'may be related but have' : 'have'} misaligned ${current.axis === 'x' ? 'column' : 'row'} edges or unequal gaps (edge drift ${Math.round(Math.max(...drift))}px; gaps ${current.gaps.map(Math.round).join('/')}px versus ${reference.gaps.map(Math.round).join('/')}px${rowDrift ? `; cross-axis gap ${Math.round(current.crossGap)}px versus ${Math.round(reference.crossGap)}px` : ''}). ${review ? 'Name the related groups with data-ds-fault-lines to enforce alignment, or mark an intentional exception off.' : 'Use the same tracks and gap for this family at this viewport.'}` });
+    }
+    return findings;
+}
+/** The same rendered geometry as the checker, painted without affecting layout or hit testing. */
+export function paintFaultLines(root, layer) {
+    const doc = layer.ownerDocument;
+    const width = doc.documentElement.clientWidth;
+    const height = doc.defaultView.innerHeight;
+    layer.setAttribute('viewBox', `0 0 ${width} ${height}`);
+    layer.setAttribute('width', String(width));
+    layer.setAttribute('height', String(height));
+    layer.setAttribute('aria-hidden', 'true');
+    layer.style.cssText = 'position:fixed;inset:0;pointer-events:none;overflow:hidden;z-index:2147483644';
+    layer.replaceChildren();
+    const grids = faultLineGrids(root);
+    const failed = new Set(inspectFaultLines(root).map(finding => finding.element));
+    const drawn = new Set();
+    const referenceInk = '#087ba8';
+    const faultInk = '#de0331';
+    function mark(tag, attributes, title) {
+        const node = doc.createElementNS('http://www.w3.org/2000/svg', tag);
+        for (const [key, value] of Object.entries(attributes))
+            node.setAttribute(key, String(value));
+        if (title) {
+            const tip = doc.createElementNS(node.namespaceURI, 'title');
+            tip.textContent = title;
+            node.appendChild(tip);
+        }
+        layer.appendChild(node);
+        return node;
+    }
+    for (let index = 0; index < grids.length; index++) {
+        const grid = grids[index];
+        const reference = referenceFor(grids, index) ?? grid;
+        for (const edge of reference.lines) {
+            const key = `${grid.axis}:${edge}`;
+            if (drawn.has(key))
+                continue;
+            drawn.add(key);
+            mark('line', { 'data-fault-reference': '', x1: grid.axis === 'x' ? edge : 0, y1: grid.axis === 'y' ? edge : 0,
+                x2: grid.axis === 'x' ? edge : width, y2: grid.axis === 'y' ? edge : height,
+                stroke: referenceInk, 'stroke-width': 1, 'stroke-dasharray': '4 4' }, 'Reference edge');
+        }
+        const broken = failed.has(grid.element);
+        if (!broken)
+            continue;
+        // Draw each actual child so drift inside a later row is visible too.
+        for (const child of Array.from(grid.element.children).filter(visible)) {
+            const box = child.getBoundingClientRect();
+            const edges = grid.axis === 'x' ? [box.left, box.right] : [box.top, box.bottom];
+            for (const edge of edges) {
+                if (reference.lines.some(expected => near(edge, expected)))
+                    continue;
+                mark('line', { 'data-fault-actual': '', x1: grid.axis === 'x' ? edge : box.left, y1: grid.axis === 'y' ? edge : box.top,
+                    x2: grid.axis === 'x' ? edge : box.right, y2: grid.axis === 'y' ? edge : box.bottom,
+                    stroke: faultInk, 'stroke-width': 2 }, 'Actual edge differs from the dashed reference');
+            }
+        }
+        // Row spacing can drift even when every column edge still aligns.
+        const rows = [];
+        for (const child of Array.from(grid.element.children).filter(visible)) {
+            const box = child.getBoundingClientRect();
+            const start = grid.axis === 'x' ? box.top : box.left;
+            const row = rows.find(row => near(grid.axis === 'x' ? row[0].top : row[0].left, start));
+            if (row)
+                row.push(box);
+            else
+                rows.push([box]);
+        }
+        rows.sort((a, b) => grid.axis === 'x' ? a[0].top - b[0].top : a[0].left - b[0].left);
+        const bounds = grid.element.getBoundingClientRect();
+        const crossGap = reference.crossGap ?? grid.crossGap;
+        if (crossGap !== undefined)
+            for (let row = 1; row < rows.length; row++) {
+                const previousEnd = Math.max(...rows[row - 1].map(box => grid.axis === 'x' ? box.bottom : box.right));
+                const actual = Math.min(...rows[row].map(box => grid.axis === 'x' ? box.top : box.left));
+                const expected = previousEnd + crossGap;
+                if (near(actual, expected))
+                    continue;
+                for (const [edge, kind] of [[expected, 'reference'], [actual, 'actual']]) {
+                    mark('line', { [`data-fault-${kind}`]: '', x1: grid.axis === 'x' ? bounds.left : edge, y1: grid.axis === 'x' ? edge : bounds.top,
+                        x2: grid.axis === 'x' ? bounds.right : edge, y2: grid.axis === 'x' ? edge : bounds.bottom,
+                        stroke: kind === 'reference' ? referenceInk : faultInk, 'stroke-width': kind === 'reference' ? 1 : 2,
+                        'stroke-dasharray': kind === 'reference' ? '4 4' : '' }, `Row gap ${Math.round(actual - previousEnd)}px; reference ${Math.round(crossGap)}px`);
+                }
+            }
+        const box = grid.element.getBoundingClientRect();
+        const label = mark('text', { 'data-fault-gap': '', x: Math.max(4, box.left), y: Math.max(16, Math.min(height - 4, box.top + 16)),
+            fill: faultInk, stroke: 'var(--ds-background-color, white)', 'stroke-width': 3, 'paint-order': 'stroke',
+            'font-family': 'var(--ds-typeface-regular, sans-serif)', 'font-size': 12 });
+        const gaps = grid.gaps.map(gap => Math.round(gap)).join('/');
+        const expected = reference.gaps.map(gap => Math.round(gap)).join('/');
+        label.textContent = `Gap ${gaps || '—'}px · reference ${expected || '—'}px` +
+            (grid.crossGap !== undefined && reference.crossGap !== undefined && !near(grid.crossGap, reference.crossGap)
+                ? ` · row gap ${Math.round(grid.crossGap)}px / ${Math.round(reference.crossGap)}px` : '');
+    }
+}

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"}

package/dist/0-face/focus.js

@@ -0,0 +1,196 @@
+/**
+ * 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.
+ */
+export const CENTRE = { x: 0.5, y: 0.5 };
+/** The width a picture is measured at; enough to find a face, and cheap. */
+export const FOCUS_SAMPLE = 64;
+/** Whether a pixel's colour is skin, in YCbCr, for any skin tone. */
+function isSkin(r, g, b) {
+    const y = 0.299 * r + 0.587 * g + 0.114 * b;
+    const cb = 128 - 0.168736 * r - 0.331264 * g + 0.5 * b;
+    const cr = 128 + 0.5 * r - 0.418688 * g - 0.081312 * b;
+    return y > 40 && cb >= 77 && cb <= 127 && cr >= 137 && cr <= 173 && r > g && r > b;
+}
+const clamp = (value) => Math.min(1, Math.max(0, value));
+/**
+ * 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 function focusOf(pixels, width, height, channels = 4) {
+    if (width < 2 || height < 2)
+        return CENTRE;
+    const at = (x, y) => (y * width + x) * channels;
+    const luma = new Float32Array(width * height);
+    const skin = new Uint8Array(width * height);
+    let skinCount = 0;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const i = at(x, y);
+            const r = pixels[i], g = pixels[i + 1], b = pixels[i + 2];
+            luma[y * width + x] = 0.299 * r + 0.587 * g + 0.114 * b;
+            if (isSkin(r, g, b)) {
+                skin[y * width + x] = 1;
+                skinCount++;
+            }
+        }
+    }
+    // A face: skin over at least half a percent of the picture, in a band of rows.
+    if (skinCount >= width * height * 0.005) {
+        const band = Math.max(2, Math.round(height / 10));
+        const rows = new Float32Array(height);
+        for (let y = 0; y < height; y++)
+            for (let x = 0; x < width; x++)
+                rows[y] += skin[y * width + x];
+        let densest = 0;
+        const bands = [];
+        for (let y = 0; y + band <= height; y++) {
+            let sum = 0;
+            for (let k = 0; k < band; k++)
+                sum += rows[y + k];
+            bands.push(sum);
+            densest = Math.max(densest, sum);
+        }
+        const top = bands.findIndex(sum => sum >= densest * 0.45);
+        if (top >= 0) {
+            let sx = 0, sy = 0, n = 0;
+            for (let y = top; y < Math.min(height, top + band * 2); y++) {
+                for (let x = 0; x < width; x++)
+                    if (skin[y * width + x]) {
+                        sx += x;
+                        sy += y;
+                        n++;
+                    }
+            }
+            if (n)
+                return { x: clamp((sx / n + 0.5) / width), y: clamp((sy / n + 0.5) / height) };
+        }
+    }
+    // Otherwise the picture's detail.
+    let sx = 0, sy = 0, total = 0;
+    for (let y = 1; y < height - 1; y++) {
+        for (let x = 1; x < width - 1; x++) {
+            const i = y * width + x;
+            const energy = Math.abs(luma[i + 1] - luma[i - 1]) + Math.abs(luma[i + width] - luma[i - width]);
+            sx += x * energy;
+            sy += y * energy;
+            total += energy;
+        }
+    }
+    if (!total)
+        return CENTRE;
+    const pull = 0.35;
+    return {
+        x: clamp(((sx / total + 0.5) / width) * (1 - pull) + 0.5 * pull),
+        y: clamp(((sy / total + 0.5) / height) * (1 - pull) + 0.5 * pull),
+    };
+}
+/**
+ * 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 function focusFromRegions(found) {
+    const faces = (found.faces ?? []).filter(face => face.w * face.h > 0.0005);
+    if (faces.length) {
+        const biggest = Math.max(...faces.map(face => face.w * face.h));
+        const kept = faces.filter(face => face.w * face.h >= biggest * 0.25);
+        const left = Math.min(...kept.map(face => face.x));
+        const right = Math.max(...kept.map(face => face.x + face.w));
+        const top = Math.min(...kept.map(face => face.y));
+        const height = Math.max(...kept.map(face => face.h));
+        return { x: clamp((left + right) / 2), y: clamp(top - height * 0.35) };
+    }
+    const salient = found.salient ?? [];
+    if (!salient.length)
+        return undefined;
+    const left = Math.min(...salient.map(r => r.x));
+    const right = Math.max(...salient.map(r => r.x + r.w));
+    const top = Math.min(...salient.map(r => r.y));
+    const bottom = Math.max(...salient.map(r => r.y + r.h));
+    return { x: clamp((left + right) / 2), y: clamp((top + bottom) / 2) };
+}
+/** The focus as CSS `object-position`, in whole percents. */
+export function objectPosition(focus) {
+    return `${Math.round(focus.x * 100)}% ${Math.round(focus.y * 100)}%`;
+}
+const KEY = "ds-focus:";
+/** Finds and sets the focus of one picture marked `data-ds-focus="auto"`, once it has loaded. */
+export function focusImage(image) {
+    const chosen = image.dataset.dsFocus;
+    if (chosen && chosen !== "auto") {
+        image.style.objectPosition = chosen;
+        return;
+    }
+    const source = image.currentSrc || image.src;
+    try {
+        const kept = localStorage.getItem(KEY + source);
+        if (kept) {
+            image.style.objectPosition = kept;
+            return;
+        }
+    }
+    catch { /* Storage can be blocked. */ }
+    const measure = () => {
+        if (!image.naturalWidth)
+            return;
+        const width = FOCUS_SAMPLE;
+        const height = Math.max(2, Math.round((image.naturalHeight / image.naturalWidth) * width));
+        const canvas = document.createElement("canvas");
+        canvas.width = width;
+        canvas.height = height;
+        const context = canvas.getContext("2d", { willReadFrequently: true });
+        if (!context)
+            return;
+        try {
+            context.drawImage(image, 0, 0, width, height);
+            const position = objectPosition(focusOf(context.getImageData(0, 0, width, height).data, width, height, 4));
+            image.style.objectPosition = position;
+            try {
+                localStorage.setItem(KEY + source, position);
+            }
+            catch { /* Storage can be blocked. */ }
+        }
+        catch { /* A picture from another host without CORS cannot be read; it keeps its middle. */ }
+    };
+    if (image.complete)
+        measure();
+    else
+        image.addEventListener("load", measure, { once: true });
+}
+/** Sets the focus of every picture marked `data-ds-focus` in `root`. */
+export function startFocus(root = document) {
+    for (const image of root.querySelectorAll("img[data-ds-focus]"))
+        focusImage(image);
+}

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

@@ -1,3 +1,13 @@
-/** Triple G toggles the grid; triple L inspects named layout areas. */
+/** The presses of one key, each within 800ms of the last, that toggle an overlay. */
+export declare const GRID_PRESSES = 5;
+/**
+ * Five presses of G toggle the grid and five of L inspect the layout, on every
+ * page that loads this module and for everyone who reads it: never put them
+ * behind a user, an owner or a development check. Escape hides both. Presses
+ * typed into a field, with a modifier or held down never count, and any other
+ * key starts the count again.
+ * A nested scrolling viewport opts in with data-ds-grid-scroll: its grid follows
+ * its content while the page grid remains aligned outside the viewport.
+ */
 export declare function initGridShortcut(): void;
 //# sourceMappingURL=grid.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"grid.d.ts","sourceRoot":"","sources":["../../DS1/0-face/grid.ts"],"names":[],"mappings":"AAGA,uEAAuE;AACvE,wBAAgB,gBAAgB,IAAI,IAAI,CAoIvC"}
+{"version":3,"file":"grid.d.ts","sourceRoot":"","sources":["../../DS1/0-face/grid.ts"],"names":[],"mappings":"AAIA,qFAAqF;AACrF,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAiLvC"}