@hachej/boring-feedback 0.0.0-stage → 0.2.4

package/dist/page/canaries.d.ts

@@ -0,0 +1,46 @@
+import type { RouteLocation } from './privacy/policy.js';
+/** Every planted channel. `visible-*` channels sit inside a `data-feedback-visible` region and must stay masked there too. */
+export declare const CANARY_CHANNELS: readonly ["text", "text-entity", "text-percent", "labelled-by", "id", "class", "title", "title-entity", "alt", "aria-label", "aria-description", "data-attribute", "kept-digits", "kept-at", "style", "event-handler", "href-path", "href-percent", "href-query", "href-fragment", "src", "form-action", "input-value", "input-live-value", "placeholder", "button-value", "textarea", "textarea-live-value", "select-value", "select-text", "contenteditable", "visible-input-value", "visible-placeholder", "visible-textarea", "visible-select-text", "visible-contenteditable", "document-title", "route-segment", "route-percent", "route-query", "route-fragment"];
+export type CanaryChannel = (typeof CANARY_CHANNELS)[number];
+/** The marker on the planted section, so callers and tests can find it. */
+export declare const CANARY_SECTION_ATTRIBUTE = "data-feedback-canaries";
+/** Default tokens: unique per channel, none a prefix of another, no digit run or `@` (so the digit rule never hides a leak). */
+export declare function defaultCanaries(): Readonly<Record<CanaryChannel, string>>;
+export interface CanaryPage {
+    readonly document: Document;
+    /** Where the canary section is appended; defaults to `document.body`. Put it where the application's data would live. */
+    readonly root?: Element;
+}
+export interface CanaryRun {
+    readonly document: Document;
+    /** The planted section. */
+    readonly root: Element;
+    /** A location with canaries in path segments, query and fragment, for the route channel. */
+    readonly location: RouteLocation;
+}
+export interface CanaryHit {
+    readonly channel: CanaryChannel;
+    readonly token: string;
+    /** Where in the output it was found, as a JSON-path-like string (`$.report.observed.subject.route`). */
+    readonly output: string;
+}
+export interface CanaryResult {
+    /** False when any canary was found. */
+    readonly ok: boolean;
+    readonly hits: readonly CanaryHit[];
+    readonly channels: readonly CanaryChannel[];
+    readonly scanned: number;
+}
+export interface PrivacyCanaryOptions {
+    readonly page: CanaryPage;
+    /** Token per channel; defaults to `defaultCanaries()`. Tokens must be fictional. */
+    readonly canaries?: Partial<Readonly<Record<CanaryChannel, string>>>;
+    /** The caller's real path (serializer, picker label, report, Copy...). Its return value is scanned; so are strings it passes to `emit`. */
+    readonly run: (context: CanaryRun, emit: (label: string, output: unknown) => void) => unknown;
+}
+/**
+ * Plants canaries under `page.root`, sets the document title to a canary, runs `run` with a canary location, then restores the page and
+ * scans the returned value and every emitted output. Each hit names its channel and the output it appeared in.
+ */
+export declare function runPrivacyCanaries({ page, canaries, run }: PrivacyCanaryOptions): Promise<CanaryResult>;
+//# sourceMappingURL=canaries.d.ts.map

package/dist/page/canaries.js

@@ -0,0 +1,142 @@
+import { FEEDBACK_VISIBLE_ATTRIBUTE } from './privacy/policy.js';
+/** Every planted channel. `visible-*` channels sit inside a `data-feedback-visible` region and must stay masked there too. */
+export const CANARY_CHANNELS = Object.freeze([
+    'text', 'text-entity', 'text-percent', 'labelled-by',
+    'id', 'class', 'title', 'title-entity', 'alt', 'aria-label', 'aria-description', 'data-attribute', 'kept-digits', 'kept-at', 'style', 'event-handler',
+    'href-path', 'href-percent', 'href-query', 'href-fragment', 'src', 'form-action',
+    'input-value', 'input-live-value', 'placeholder', 'button-value', 'textarea', 'textarea-live-value', 'select-value', 'select-text', 'contenteditable',
+    'visible-input-value', 'visible-placeholder', 'visible-textarea', 'visible-select-text', 'visible-contenteditable',
+    'document-title', 'route-segment', 'route-percent', 'route-query', 'route-fragment',
+]);
+/** The marker on the planted section, so callers and tests can find it. */
+export const CANARY_SECTION_ATTRIBUTE = 'data-feedback-canaries';
+/** Default tokens: unique per channel, none a prefix of another, no digit run or `@` (so the digit rule never hides a leak). */
+export function defaultCanaries() {
+    return Object.freeze(Object.fromEntries(CANARY_CHANNELS.map(channel => [channel, `xq${channel.replace(/-/g, '')}vz`])));
+}
+const percentEncode = (token) => `%${token.charCodeAt(0).toString(16)}${token.slice(1)}`;
+// Hexadecimal entity and two-digit percent forms: a three-digit decimal entity would be hidden by the digit rule, not by the policy.
+const entityEncode = (token) => `&#x${token.charCodeAt(0).toString(16)};${token.slice(1)}`;
+function plant(document, tokens) {
+    const make = (tag, attributes = {}, text) => {
+        const element = document.createElement(tag);
+        for (const [name, value] of Object.entries(attributes))
+            element.setAttribute(name, value);
+        if (text !== undefined)
+            element.append(document.createTextNode(text));
+        return element;
+    };
+    const t = tokens;
+    const section = make('section', { [CANARY_SECTION_ATTRIBUTE]: '', role: 'region' });
+    const text = make('p', { 'data-testid': 'canary-text' }, `Fictional ${t.text} record`);
+    text.setAttribute('id', t.id);
+    section.append(text, make('p', {}, entityEncode(t['text-entity'])), make('p', {}, percentEncode(t['text-percent'])), make('span', { id: 'feedback-canary-labelled' }, t['labelled-by']), make('button', { type: 'button', 'aria-labelledby': 'feedback-canary-labelled' }), make('div', {
+        class: `card ${t.class}`, title: t.title, 'aria-label': t['aria-label'], 'aria-description': t['aria-description'], 'data-record': t['data-attribute'],
+        'data-testid': `${t['kept-digits']}-4711`, 'data-feedback-id': `${t['kept-at']}@fictional.invalid`, style: `background:url(${t.style})`, onclick: `alert('${t['event-handler']}')`,
+    }, 'Card'), make('span', { title: entityEncode(t['title-entity']) }, 'Entity title'), make('img', { src: `/images/${t.src}.png`, alt: t.alt }), make('a', { href: `/records/${t['href-path']}?q=${t['href-query']}#${t['href-fragment']}` }, 'Open'), make('a', { href: `/records/${percentEncode(t['href-percent'])}` }, 'Open encoded'));
+    const form = make('form', { action: `/submit/${t['form-action']}` });
+    const input = make('input', { type: 'text', value: t['input-value'], placeholder: t.placeholder });
+    const live = make('input', { type: 'text' });
+    live.value = t['input-live-value'];
+    const textarea = make('textarea', {}, t.textarea);
+    const liveArea = make('textarea', {});
+    liveArea.value = t['textarea-live-value'];
+    const select = make('select');
+    select.append(make('option', { value: t['select-value'], selected: '' }, t['select-text']));
+    form.append(input, live, make('input', { type: 'submit', value: t['button-value'] }), textarea, liveArea, select, make('div', { contenteditable: 'true' }, t.contenteditable));
+    const visible = make('div', { [FEEDBACK_VISIBLE_ATTRIBUTE]: '' });
+    const visibleSelect = make('select', { 'aria-label': 'Fictional choice' });
+    visibleSelect.append(make('option', {}, t['visible-select-text']));
+    visible.append(make('h3', {}, 'Visible fictional region'), make('label', { for: 'feedback-canary-visible-input' }, 'Visible label'), make('input', { id: 'feedback-canary-visible-input', type: 'text', value: t['visible-input-value'], placeholder: t['visible-placeholder'] }), make('textarea', { 'aria-label': 'Fictional notes' }, t['visible-textarea']), visibleSelect, make('div', { contenteditable: 'plaintext-only' }, t['visible-contenteditable']));
+    section.append(form, visible);
+    return section;
+}
+const NAMED = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+function decodeOnce(value) {
+    const entities = value
+        .replace(/&#x([0-9a-f]+);?/gi, (_, hex) => String.fromCodePoint(Math.min(parseInt(hex, 16), 0x10ffff)))
+        .replace(/&#(\d+);?/g, (_, dec) => String.fromCodePoint(Math.min(parseInt(dec, 10), 0x10ffff)))
+        .replace(/&([a-z]+);/gi, (match, name) => NAMED[name.toLowerCase()] ?? match);
+    const percent = value.replace(/%([0-9a-f]{2})/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+    return [entities, percent];
+}
+/** The string and its HTML-entity and percent decodings (combined, up to three rounds), lower-cased. */
+function decodings(value) {
+    let frontier = new Set([value]);
+    const all = new Set([value.toLowerCase()]);
+    for (let round = 0; round < 3 && frontier.size; round++) {
+        const next = new Set();
+        for (const item of frontier)
+            for (const decoded of decodeOnce(item))
+                if (!all.has(decoded.toLowerCase())) {
+                    all.add(decoded.toLowerCase());
+                    next.add(decoded);
+                }
+        frontier = next;
+    }
+    return all;
+}
+function strings(value, path, out, seen) {
+    if (typeof value === 'string') {
+        out.push({ path, value });
+        return;
+    }
+    if (value === null || typeof value !== 'object' || seen.has(value))
+        return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => strings(item, `${path}[${index}]`, out, seen));
+        return;
+    }
+    if (value instanceof Map) {
+        for (const [key, item] of value) {
+            strings(key, `${path}.<key>`, out, seen);
+            strings(item, `${path}.${String(key)}`, out, seen);
+        }
+        return;
+    }
+    for (const [key, item] of Object.entries(value)) {
+        out.push({ path: `${path}.<key ${key}>`, value: key });
+        strings(item, `${path}.${key}`, out, seen);
+    }
+}
+/**
+ * Plants canaries under `page.root`, sets the document title to a canary, runs `run` with a canary location, then restores the page and
+ * scans the returned value and every emitted output. Each hit names its channel and the output it appeared in.
+ */
+export async function runPrivacyCanaries({ page, canaries, run }) {
+    const tokens = { ...defaultCanaries(), ...canaries };
+    const { document } = page;
+    const parent = page.root ?? document.body;
+    const section = plant(document, tokens);
+    const title = document.title;
+    const location = Object.freeze({
+        pathname: `/records/${tokens['route-segment']}/${percentEncode(tokens['route-percent'])}`,
+        search: `?q=${tokens['route-query']}`,
+        hash: `#${tokens['route-fragment']}`,
+    });
+    const outputs = [];
+    const emit = (label, output) => strings(output, `$${label ? `.${label}` : ''}`, outputs, new Set());
+    parent.append(section);
+    document.title = tokens['document-title'];
+    try {
+        emit('result', await run(Object.freeze({ document, root: section, location }), emit));
+    }
+    finally {
+        section.remove();
+        document.title = title;
+    }
+    const hits = [];
+    for (const { path, value } of outputs) {
+        const decoded = decodings(value);
+        for (const channel of CANARY_CHANNELS) {
+            const token = tokens[channel].toLowerCase();
+            for (const candidate of decoded)
+                if (candidate.includes(token)) {
+                    hits.push(Object.freeze({ channel, token: tokens[channel], output: path }));
+                    break;
+                }
+        }
+    }
+    return Object.freeze({ ok: hits.length === 0, hits: Object.freeze(hits), channels: CANARY_CHANNELS, scanned: outputs.length });
+}

package/dist/page/index.d.ts

@@ -0,0 +1,6 @@
+export * from './privacy/index.js';
+export { runPrivacyCanaries, defaultCanaries, CANARY_CHANNELS, CANARY_SECTION_ATTRIBUTE, type CanaryChannel, type CanaryPage, type CanaryRun, type CanaryHit, type CanaryResult, type PrivacyCanaryOptions, } from './canaries.js';
+export { anchorOf, rangeOf, resolveAppElement, revealElement, fallbackOf, appElementResolution, appElementSchema, APP_ELEMENT_KIND, type AppElementAnchor, type AppElementSignals, type AppElementIdentity, type AppElementRange, type AppElementCapture, type AnchorOfOptions, type RevealResult, } from './app-element.js';
+export * from './picker/index.js';
+export * from './voice/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/page/index.js

@@ -0,0 +1,8 @@
+// @hachej/boring-feedback/page: browser-side privacy policy, the `app.dom@1` serializer and the privacy canary kit (WP3); `app.element@1` pins (WP5);
+// the picker and its overlay (WP6); voice capture and speech-to-pointer alignment.
+export * from './privacy/index.js';
+export { runPrivacyCanaries, defaultCanaries, CANARY_CHANNELS, CANARY_SECTION_ATTRIBUTE, } from './canaries.js';
+export { anchorOf, rangeOf, resolveAppElement, revealElement, fallbackOf, appElementResolution, appElementSchema, APP_ELEMENT_KIND, } from './app-element.js';
+export * from './picker/index.js';
+// Voice capture and speech-to-pointer alignment.
+export * from './voice/index.js';

package/dist/page/picker/index.d.ts

@@ -0,0 +1,4 @@
+export { createPicker, pickRefusal, type Picker, type PickerOptions, type PickerResult, type PickerState, type PickerMode } from './picker.js';
+export { createOverlay, type PickerOverlay, type OverlayBox, type OverlayOptions, type OverlayToolbar, type OverlayTone } from './overlay.js';
+export { pickerLabel, componentOf, elementAt } from './label.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/page/picker/index.js

@@ -0,0 +1,4 @@
+// The element picker and its overlay (WP6).
+export { createPicker, pickRefusal } from './picker.js';
+export { createOverlay } from './overlay.js';
+export { pickerLabel, componentOf, elementAt } from './label.js';

package/dist/page/picker/label.d.ts

@@ -0,0 +1,16 @@
+import { type AppElementRange } from '../app-element.js';
+import { type PrivacyPolicy } from '../privacy/policy.js';
+import { type AppDomSnapshot } from '../privacy/serialize.js';
+/** `src/settings/SaveBar.tsx:42` → `SaveBar`; an `index` file is named by its folder. */
+export declare function componentOf(source: string): string | undefined;
+/**
+ * The overlay label of an element: `SaveBar · button «Save»` with a development source location, `button «Save»` without one, and
+ * `button · masked` when the policy masks its name. Excluded elements are only ever `masked`.
+ */
+export declare function pickerLabel(element: Element, policy: PrivacyPolicy): string;
+/**
+ * The live element at a range of a snapshot of `root`, following tags and same-tag positions, without scrolling or re-checking it.
+ * For drawing numbered candidates only; revealing one goes through `revealElement`, which re-checks it against the snapshot.
+ */
+export declare function elementAt(range: AppElementRange, root: Element, snapshot: AppDomSnapshot): Element | undefined;
+//# sourceMappingURL=label.d.ts.map

package/dist/page/picker/label.js

@@ -0,0 +1,58 @@
+// Picker labels and live lookups. Every word of a label comes through the privacy policy (FEEDBACK-8): the component name from a kept
+// `data-source`, the role from kept structure, and the accessible name only when the policy allows it; otherwise "masked".
+import { roleOf } from '../app-element.js';
+import { accessibleNameOf } from '../privacy/name.js';
+import { MASKED_NAME, isExcluded } from '../privacy/policy.js';
+import { serializeElement } from '../privacy/serialize.js';
+/** `src/settings/SaveBar.tsx:42` → `SaveBar`; an `index` file is named by its folder. */
+export function componentOf(source) {
+    const file = source.replace(/:\d+$/, '');
+    const parts = file.split('/');
+    const base = (parts.at(-1) ?? '').replace(/\.[cm]?[jt]sx?$/, '');
+    const name = base === 'index' && parts.length > 1 ? parts.at(-2) : base;
+    return name || undefined;
+}
+/**
+ * The overlay label of an element: `SaveBar · button «Save»` with a development source location, `button «Save»` without one, and
+ * `button · masked` when the policy masks its name. Excluded elements are only ever `masked`.
+ */
+export function pickerLabel(element, policy) {
+    if (isExcluded(element))
+        return MASKED_NAME;
+    const node = serializeElement(element, policy, { subtreeLimit: 1 }).root;
+    if (!node)
+        return MASKED_NAME;
+    const source = node.attrs['data-source'];
+    const component = source === undefined ? undefined : componentOf(source);
+    const role = roleOf(node) ?? node.tag;
+    const name = accessibleNameOf(element, policy);
+    const what = name === MASKED_NAME ? `${role} · ${MASKED_NAME}` : `${role} «${name}»`;
+    return component ? `${component} · ${what}` : what;
+}
+/**
+ * The live element at a range of a snapshot of `root`, following tags and same-tag positions, without scrolling or re-checking it.
+ * For drawing numbered candidates only; revealing one goes through `revealElement`, which re-checks it against the snapshot.
+ */
+export function elementAt(range, root, snapshot) {
+    let node = snapshot.root;
+    if (!node || node.tag !== root.localName)
+        return undefined;
+    let live = root;
+    for (const step of range) {
+        const child = node.children[step];
+        if (child === undefined)
+            return undefined;
+        let seen = 0, found;
+        for (const candidate of Array.from(live.children)) {
+            if (candidate.localName === child.tag && seen++ === child.index) {
+                found = candidate;
+                break;
+            }
+        }
+        if (found === undefined)
+            return undefined;
+        live = found;
+        node = child;
+    }
+    return isExcluded(live) ? undefined : live;
+}

package/dist/page/picker/overlay.d.ts

@@ -0,0 +1,42 @@
+/** How a box is drawn: the element under the pointer, a pinned element, a revealed element, or a numbered candidate to choose from. */
+export type OverlayTone = 'hover' | 'pinned' | 'reveal' | 'candidate';
+export interface OverlayBox {
+    readonly element: Element;
+    /** Label text. The picker builds it from the privacy policy only (`pickerLabel`). */
+    readonly label: string;
+    readonly tone: OverlayTone;
+}
+/** The touch toolbar: a tap selects, these buttons replace the keys. Absent actions are not shown. */
+export interface OverlayToolbar {
+    readonly parent: () => void;
+    readonly child: () => void;
+    readonly pin: () => void;
+    readonly cancel: () => void;
+    /** Shown when several elements are pinned. */
+    readonly done?: () => void;
+}
+export interface PickerOverlay {
+    /** The host element (light DOM, outside the application root). */
+    readonly host: HTMLElement;
+    readonly draw: (boxes: readonly OverlayBox[]) => void;
+    /** Draws one revealed element with a note (Show). */
+    readonly highlight: (element: Element, note?: string) => void;
+    readonly toolbar: (actions: OverlayToolbar | undefined) => void;
+    readonly clear: () => void;
+    /** What is drawn now, for tests and journeys: each box's label and tone. */
+    readonly drawn: () => readonly {
+        readonly label: string;
+        readonly tone: OverlayTone;
+    }[];
+    readonly dispose: () => void;
+}
+export interface OverlayOptions {
+    readonly document: Document;
+    /** Extra CSS for the shadow root (the registry's `PickerOverlay` styles). The parts are `box`, `label` and `toolbar`. */
+    readonly styles?: string;
+    /** Where the host is appended; defaults to `document.body`. Never inside the application root. */
+    readonly mount?: Element;
+}
+/** Creates the overlay host and its shadow root. Nothing is drawn until `draw` or `highlight`. */
+export declare function createOverlay({ document, styles, mount }: OverlayOptions): PickerOverlay;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/page/picker/overlay.js

@@ -0,0 +1,126 @@
+// The picker overlay (FEEDBACK.md, "Pointing at elements: the picker"). One host element marked `data-feedback-overlay`, so every
+// snapshot and the picker skip it, with its own shadow root. The layer never takes pointer events and changes no layout, style or event
+// of the page; only the touch toolbar inside it is interactive. Text is set with `textContent` only.
+import { FEEDBACK_OVERLAY_ATTRIBUTE } from '../privacy/policy.js';
+const BASE_STYLES = `
+:host { all: initial; position: fixed; inset: 0; z-index: 2147483647; pointer-events: none; contain: layout style; }
+.layer { position: absolute; inset: 0; pointer-events: none; }
+.box { position: fixed; box-sizing: border-box; border: 2px solid var(--boring-feedback-accent, var(--primary, #2563eb)); border-radius: 3px;
+  background: color-mix(in srgb, var(--boring-feedback-accent, var(--primary, #2563eb)) 12%, transparent); pointer-events: none; }
+.box[data-tone="pinned"] { border-style: solid; border-width: 3px; }
+.box[data-tone="reveal"] { border-color: var(--boring-feedback-reveal, var(--ring, #d97706)); background: color-mix(in srgb, var(--boring-feedback-reveal, var(--ring, #d97706)) 14%, transparent); }
+.box[data-tone="candidate"] { border-style: dashed; }
+.label { position: fixed; max-width: min(28rem, 90vw); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; padding: 2px 6px;
+  border-radius: 4px; background: var(--boring-feedback-label-background, var(--foreground, #111827)); color: var(--boring-feedback-label-foreground, var(--background, #f9fafb));
+  font: 500 12px/1.5 ui-sans-serif, system-ui, sans-serif; pointer-events: none; }
+.label[data-tone="candidate"] { min-width: 1.5em; text-align: center; font-weight: 700; }
+.toolbar { position: fixed; left: 50%; bottom: max(16px, env(safe-area-inset-bottom)); transform: translateX(-50%); display: flex; gap: 6px; padding: 6px;
+  border-radius: 12px; background: var(--boring-feedback-label-background, var(--foreground, #111827)); pointer-events: auto; }
+.toolbar[hidden] { display: none; }
+.toolbar button { min-width: 44px; min-height: 44px; padding: 0 12px; border: 0; border-radius: 8px; background: transparent;
+  color: var(--boring-feedback-label-foreground, var(--background, #f9fafb)); font: 600 14px/1 ui-sans-serif, system-ui, sans-serif; cursor: pointer; }
+.toolbar button:focus-visible { outline: 2px solid var(--boring-feedback-accent, var(--primary, #2563eb)); }
+`;
+const LABEL_HEIGHT = 22;
+/** Creates the overlay host and its shadow root. Nothing is drawn until `draw` or `highlight`. */
+export function createOverlay({ document, styles, mount }) {
+    const host = document.createElement('div');
+    host.setAttribute(FEEDBACK_OVERLAY_ATTRIBUTE, '');
+    host.setAttribute('data-boring', 'feedback');
+    const shadow = host.attachShadow({ mode: 'open' });
+    const style = document.createElement('style');
+    style.textContent = BASE_STYLES + (styles ?? '');
+    const layer = document.createElement('div');
+    layer.className = 'layer';
+    layer.setAttribute('aria-hidden', 'true');
+    layer.setAttribute('part', 'layer');
+    const bar = document.createElement('div');
+    bar.className = 'toolbar';
+    bar.setAttribute('role', 'toolbar');
+    bar.setAttribute('aria-label', 'Pick an element');
+    bar.setAttribute('part', 'toolbar');
+    bar.hidden = true;
+    shadow.append(style, layer, bar);
+    (mount ?? document.body).append(host);
+    const view = document.defaultView;
+    let boxes = [];
+    let frame;
+    let following = false;
+    const render = () => {
+        frame = undefined;
+        layer.replaceChildren();
+        const height = view?.innerHeight ?? 0;
+        for (const item of boxes) {
+            if (!item.element.isConnected)
+                continue;
+            const rect = item.element.getBoundingClientRect();
+            const box = document.createElement('div');
+            box.className = 'box';
+            box.dataset['tone'] = item.tone;
+            box.setAttribute('part', `box box-${item.tone}`);
+            box.style.cssText = `top:${rect.top}px;left:${rect.left}px;width:${rect.width}px;height:${rect.height}px`;
+            const label = document.createElement('div');
+            label.className = 'label';
+            label.dataset['tone'] = item.tone;
+            label.setAttribute('part', `label label-${item.tone}`);
+            label.textContent = item.label;
+            const above = rect.top - LABEL_HEIGHT - 2;
+            const top = above >= 0 ? above : Math.min(rect.bottom + 2, Math.max(0, height - LABEL_HEIGHT));
+            label.style.cssText = `top:${top}px;left:${Math.max(0, rect.left)}px`;
+            layer.append(box, label);
+        }
+    };
+    const schedule = () => {
+        if (frame !== undefined)
+            return;
+        if (view && typeof view.requestAnimationFrame === 'function')
+            frame = view.requestAnimationFrame(render);
+        else
+            render();
+    };
+    const follow = (on) => {
+        if (!view || on === following)
+            return;
+        following = on;
+        const method = on ? 'addEventListener' : 'removeEventListener';
+        view[method]('scroll', schedule, { capture: true });
+        view[method]('resize', schedule);
+    };
+    const draw = (next) => {
+        boxes = Object.freeze([...next]);
+        follow(boxes.length > 0);
+        if (frame !== undefined && view) {
+            view.cancelAnimationFrame(frame);
+            frame = undefined;
+        }
+        render();
+    };
+    const toolbar = (actions) => {
+        bar.replaceChildren();
+        bar.hidden = actions === undefined;
+        if (!actions)
+            return;
+        const entries = [
+            ['parent', 'Parent', actions.parent], ['child', 'Child', actions.child], ['pin', 'Pin', actions.pin], ['done', 'Done', actions.done], ['cancel', 'Cancel', actions.cancel],
+        ];
+        for (const [name, text, run] of entries) {
+            if (!run)
+                continue;
+            const button = document.createElement('button');
+            button.type = 'button';
+            button.dataset['action'] = name;
+            button.textContent = text;
+            button.addEventListener('click', event => { event.preventDefault(); run(); });
+            bar.append(button);
+        }
+    };
+    return {
+        host,
+        draw,
+        highlight: (element, note) => draw([{ element, label: note ?? 'Here', tone: 'reveal' }]),
+        toolbar,
+        clear: () => draw([]),
+        drawn: () => boxes.filter(item => item.element.isConnected).map(({ label, tone }) => ({ label, tone })),
+        dispose: () => { draw([]); toolbar(undefined); host.remove(); },
+    };
+}

package/dist/page/picker/picker.d.ts

@@ -0,0 +1,72 @@
+import { type PrivacyPolicy } from '../privacy/policy.js';
+import { type PickerOverlay } from './overlay.js';
+export type PickerMode = 'idle' | 'picking' | 'done';
+export interface PickerState {
+    readonly mode: PickerMode;
+    /** The element the next pin takes. */
+    readonly current?: Element;
+    /** Its label, from the privacy policy. */
+    readonly label?: string;
+    readonly pins: readonly Element[];
+    /** True once a touch selected: the overlay shows its Parent, Child and Pin buttons. */
+    readonly touch: boolean;
+    /** Why the element under the pointer cannot be picked (outside the application root). */
+    readonly refusal?: string;
+    /** Pick mode is on but every event currently reaches the page (`suspend`). */
+    readonly suspended: boolean;
+}
+export type PickerResult = {
+    readonly kind: 'pinned';
+    readonly elements: readonly Element[];
+} | {
+    readonly kind: 'cancelled';
+};
+export interface PickerOptions {
+    /** The application root: only elements inside it (light DOM, same document) are pickable. */
+    readonly root: Element;
+    readonly policy: PrivacyPolicy;
+    /** A shared overlay; otherwise the picker creates one (with `styles`) and disposes it with itself. */
+    readonly overlay?: PickerOverlay;
+    readonly styles?: string;
+    /** Shift-click and Shift-Enter pin several elements. Default true. */
+    readonly multiple?: boolean;
+    /** Elements at a viewport point, topmost first. Defaults to `document.elementsFromPoint`. */
+    readonly hitTest?: (x: number, y: number) => readonly Element[];
+    readonly onChange?: (state: PickerState) => void;
+    readonly onFinish?: (result: PickerResult) => void;
+    /** Continuous picking: a click, Enter or the touch Pin hands the element here and pick mode stays on. Shift has no effect. */
+    readonly onPick?: (element: Element) => void;
+    /** The wheel selects the parent and the child (default). False leaves wheel events, and so scrolling, to the page. */
+    readonly wheel?: boolean;
+    /** `'all'` (default): every key belongs to the picker. `'outside-ignored'`: keys inside ignored subtrees reach them. */
+    readonly keys?: 'all' | 'outside-ignored';
+    /** `'select'` (default): a tap selects and the touch toolbar pins. `'pick'`, with `onPick`: a tap picks at once and no toolbar shows. */
+    readonly tap?: 'select' | 'pick';
+}
+export interface Picker {
+    /** Enters pick mode. Resolves when the person pins (Click, Enter, Done) or cancels (Esc, Cancel, `dispose`). */
+    readonly start: () => Promise<PickerResult>;
+    readonly cancel: () => void;
+    /** Ends with the pins so far, or the current element when nothing is pinned yet. */
+    readonly finish: () => void;
+    readonly parent: () => void;
+    readonly child: () => void;
+    /** Pins the current element; with `add`, keeps picking for more. */
+    readonly pin: (options?: {
+        readonly add?: boolean;
+    }) => void;
+    /** Makes an element current (refused when it is not pickable). */
+    readonly select: (element: Element) => boolean;
+    readonly state: () => PickerState;
+    readonly overlay: PickerOverlay;
+    /** Draws one element with a note on the same overlay (Show). */
+    readonly highlight: (element: Element, note?: string) => void;
+    /** While suspended, pick mode stays on but no event is taken: the page works as usual. Resuming takes them again. */
+    readonly suspend: (suspended: boolean) => void;
+    /** Cancels pick mode if it is on and removes an overlay the picker created. */
+    readonly dispose: () => void;
+}
+/** Why an element cannot be picked, or undefined when it can. */
+export declare function pickRefusal(element: Element, root: Element): string | undefined;
+export declare function createPicker(options: PickerOptions): Picker;
+//# sourceMappingURL=picker.d.ts.map