@hachej/boring-feedback 0.0.0-stage → 0.2.5

package/dist/page/picker/picker.js

@@ -0,0 +1,386 @@
+// Pick mode (FEEDBACK.md, "Pointing at elements: the picker"): the element under the pointer is boxed and labelled, ↑ or scrolling up
+// selects the parent and ↓ (or scrolling down) the child again, click pins, Shift-click pins several, Esc cancels; Tab and Enter do the
+// same from the keyboard; on touch a tap selects and the overlay's Parent, Child and Pin buttons replace the keys.
+//
+// Picking never activates the page: while pick mode is on, pointer, click, key and submit events are taken in the capture phase on the
+// window and stopped, so pressing a Save button pins it without pressing it. Only the overlay (its touch toolbar) and subtrees marked
+// `data-feedback-ignore` (the application's own chrome, the agent bar) keep their pointer events. Keys always belong to the picker.
+// When pick mode ends, every listener is removed and focus returns to where it was.
+//
+// Only the given application root is pickable: elements outside it (portals), inside shadow roots or in iframes are never selected.
+//
+// Continuous picking (`onPick`, used by the feedback session): a click or Enter hands the element to `onPick` and pick mode stays on,
+// so the person can pin one element after another. `wheel: false` leaves scrolling to the page, `keys: 'outside-ignored'` lets keys
+// typed inside ignored subtrees (a note bubble) reach them, and `suspend(true)` lets every event through to the page until
+// `suspend(false)` (the session's "hold Alt to use the app"). `tap: 'pick'` (point mode on phones) hands a tap straight to `onPick`
+// with no toolbar: one tap, one pick; a finger that moved (a scroll) is not a tap.
+import { isExcluded } from '../privacy/policy.js';
+import { pickerLabel } from './label.js';
+import { createOverlay } from './overlay.js';
+/** Elements Tab moves between: what people can act on or name, plus marked elements. */
+const TAB_STOPS = 'a[href],button,input,select,textarea,summary,[tabindex],[role],[contenteditable],h1,h2,h3,h4,h5,h6,label,img,table,[data-feedback-id],[data-testid]';
+const POINTER_EVENTS = ['pointerdown', 'pointerup', 'pointercancel', 'mousedown', 'mouseup', 'click', 'dblclick', 'auxclick', 'contextmenu', 'touchstart', 'touchend', 'dragstart', 'selectstart'];
+const KEY_EVENTS = ['keydown', 'keyup', 'keypress'];
+/** How far (CSS px) a finger may move and still tap. */
+const TAP_SLOP = 10;
+/** Why an element cannot be picked, or undefined when it can. */
+export function pickRefusal(element, root) {
+    if (element.ownerDocument !== root.ownerDocument)
+        return 'the element is in another document (an iframe)';
+    if (!element.isConnected)
+        return 'the element is not in the page';
+    if (element.getRootNode() !== element.ownerDocument)
+        return 'the element is inside a shadow root';
+    if (isExcluded(element))
+        return 'the element is inside an ignored subtree or the feedback overlay';
+    if (element !== root && !root.contains(element))
+        return 'the element is outside the application root';
+    return undefined;
+}
+export function createPicker(options) {
+    const { root, policy, onPick, wheel = true, keys = 'all' } = options;
+    const tapPicks = options.tap === 'pick' && onPick !== undefined;
+    const multiple = onPick ? false : options.multiple ?? true;
+    const document = root.ownerDocument;
+    const view = document.defaultView;
+    if (!view)
+        throw new TypeError('The application root must be in a document with a window');
+    const ownsOverlay = options.overlay === undefined;
+    const overlay = options.overlay ?? createOverlay({ document, ...(options.styles !== undefined ? { styles: options.styles } : {}) });
+    const hitTest = options.hitTest ?? ((x, y) => document.elementsFromPoint(x, y));
+    let mode = 'idle';
+    let current;
+    let refusal;
+    let pins = [];
+    let touch = false;
+    let suspended = false;
+    let lastPointer = 'mouse';
+    /** Where the finger went down, and whether this gesture already picked (pointerup and touchend of one tap count once). */
+    let fingerDown;
+    let tapDone = false;
+    /** The finger went further than TAP_SLOP from where it went down at some point of this gesture: a drag, even if it came back. */
+    let dragged = false;
+    const far = (where) => where !== undefined && fingerDown !== undefined && Math.hypot(where.x - fingerDown.x, where.y - fingerDown.y) > TAP_SLOP;
+    /** Children left by ↑, so ↓ returns along the same path. */
+    let trail = [];
+    let focus = null;
+    let settle;
+    const removers = [];
+    const state = () => Object.freeze({
+        mode, pins: Object.freeze([...pins]), touch, suspended,
+        ...(current ? { current, label: pickerLabel(current, policy) } : {}),
+        ...(refusal !== undefined ? { refusal } : {}),
+    });
+    const redraw = () => {
+        const boxes = pins.map(element => ({ element, label: pickerLabel(element, policy), tone: 'pinned' }));
+        if (mode === 'picking' && !suspended && current && !pins.includes(current))
+            boxes.push({ element: current, label: pickerLabel(current, policy), tone: 'hover' });
+        overlay.draw(boxes);
+        overlay.toolbar(mode === 'picking' && !suspended && touch && !tapPicks ? {
+            parent: () => move('up'), child: () => move('down'), pin: () => pin(), cancel: () => end({ kind: 'cancelled' }),
+            ...(pins.length ? { done: () => finish() } : {}),
+        } : undefined);
+    };
+    const changed = () => { redraw(); options.onChange?.(state()); };
+    const pickable = (element) => pickRefusal(element, root) === undefined;
+    const choose = (element, keepTrail = false) => {
+        if (!keepTrail)
+            trail = [];
+        current = element;
+        refusal = undefined;
+        changed();
+    };
+    const select = (element) => {
+        if (mode !== 'picking' || !pickable(element))
+            return false;
+        choose(element);
+        return true;
+    };
+    /** The topmost pickable element at a point, skipping the overlay and ignored subtrees; anything else on top refuses the point. */
+    const at = (x, y) => {
+        for (const element of hitTest(x, y)) {
+            if (element === overlay.host || isExcluded(element))
+                continue;
+            const reason = pickRefusal(element, root);
+            return reason === undefined ? { element } : { refusal: reason };
+        }
+        return {};
+    };
+    const hover = (x, y) => {
+        const found = at(x, y);
+        if (found.element === current && found.refusal === refusal)
+            return;
+        trail = [];
+        current = found.element;
+        refusal = found.refusal;
+        changed();
+    };
+    const move = (direction) => {
+        if (mode !== 'picking' || !current)
+            return;
+        if (direction === 'up') {
+            const parent = current.parentElement;
+            if (!parent || current === root || !pickable(parent))
+                return;
+            trail.push(current);
+            choose(parent, true);
+            return;
+        }
+        const back = trail.pop();
+        const next = back ?? Array.from(current.children).find(pickable);
+        if (next)
+            choose(next, true);
+    };
+    const stops = () => Array.from(root.querySelectorAll(TAB_STOPS)).filter(element => pickable(element) && !element.closest('[hidden]'));
+    const tab = (backward) => {
+        const list = stops();
+        if (!list.length)
+            return;
+        const index = current ? list.indexOf(current) : -1;
+        const next = index < 0 ? (backward ? list.length - 1 : 0) : (index + (backward ? -1 : 1) + list.length) % list.length;
+        choose(list[next]);
+    };
+    const pin = ({ add = false } = {}) => {
+        if (mode !== 'picking' || suspended || !current)
+            return;
+        if (onPick) {
+            onPick(current);
+            return;
+        }
+        if (add && multiple) {
+            pins = pins.includes(current) ? pins.filter(element => element !== current) : [...pins, current];
+            changed();
+            return;
+        }
+        if (!pins.includes(current))
+            pins = [...pins, current];
+        finish();
+    };
+    const finish = () => {
+        if (mode !== 'picking')
+            return;
+        if (!pins.length && current)
+            pins = [current];
+        if (!pins.length) {
+            end({ kind: 'cancelled' });
+            return;
+        }
+        end({ kind: 'pinned', elements: Object.freeze([...pins]) });
+    };
+    const end = (result) => {
+        if (mode !== 'picking')
+            return;
+        mode = 'done';
+        for (const remove of removers.splice(0))
+            remove();
+        if (result.kind === 'cancelled')
+            pins = [];
+        current = undefined;
+        refusal = undefined;
+        touch = false;
+        suspended = false;
+        trail = [];
+        changed();
+        const restore = focus;
+        focus = null;
+        if (restore && restore.isConnected && typeof restore.focus === 'function') {
+            try {
+                restore.focus({ preventScroll: true });
+            }
+            catch { /* not focusable any more */ }
+        }
+        const done = settle;
+        settle = undefined;
+        options.onFinish?.(result);
+        done?.(result);
+    };
+    // --- events -------------------------------------------------------------------------------------------------------------------
+    const stop = (event) => { if (event.cancelable)
+        event.preventDefault(); event.stopPropagation(); event.stopImmediatePropagation(); };
+    /** Pointer events on the overlay's toolbar and in ignored subtrees keep working; everything else is the picker's. */
+    const passes = (event) => event.composedPath().some(target => target === overlay.host || (isElement(target) && target.hasAttribute('data-feedback-ignore')));
+    const point = (event) => {
+        const touches = event.changedTouches;
+        if (touches && touches.length) {
+            const first = touches[0];
+            return { x: first.clientX, y: first.clientY };
+        }
+        const mouse = event;
+        return typeof mouse.clientX === 'number' ? { x: mouse.clientX, y: mouse.clientY } : undefined;
+    };
+    const onPointer = (event) => {
+        if (passes(event))
+            return;
+        const type = event.type;
+        const pointerType = event.pointerType;
+        if (type === 'pointerdown' && pointerType)
+            lastPointer = pointerType;
+        if (type === 'touchstart')
+            lastPointer = 'touch';
+        if ((type === 'pointerdown' && pointerType === 'touch') || type === 'touchstart') {
+            fingerDown = point(event);
+            tapDone = false;
+            dragged = false;
+        }
+        if (type === 'pointercancel')
+            tapDone = true;
+        const tapped = type === 'pointerup' && pointerType === 'touch';
+        if (tapped || (type === 'touchend' && lastPointer === 'touch')) {
+            const where = point(event);
+            if (where && tapPicks) {
+                if (!tapDone && !dragged && !far(where) && !suspended) {
+                    tapDone = true;
+                    touch = true;
+                    const found = at(where.x, where.y);
+                    trail = [];
+                    refusal = found.refusal;
+                    if (found.element) {
+                        current = found.element;
+                        changed();
+                        pin();
+                    }
+                    else
+                        changed();
+                }
+            }
+            else if (where) {
+                touch = true;
+                const found = at(where.x, where.y);
+                trail = [];
+                current = found.element ?? current;
+                refusal = found.refusal;
+                changed();
+            }
+        }
+        else if (type === 'click' && lastPointer !== 'touch') {
+            const where = point(event);
+            const mouse = event;
+            if (where && (mouse.detail > 0 || where.x !== 0 || where.y !== 0)) {
+                const found = at(where.x, where.y);
+                if (found.element && found.element !== current)
+                    choose(found.element);
+            }
+            pin({ add: mouse.shiftKey });
+        }
+        // touchstart is not cancelled, so the page still scrolls under a finger; touchend is, so no click is synthesized.
+        if (type === 'touchstart') {
+            event.stopPropagation();
+            event.stopImmediatePropagation();
+            return;
+        }
+        stop(event);
+    };
+    const inIgnored = (event) => event.composedPath().some(target => isElement(target) && target.hasAttribute('data-feedback-ignore'));
+    const onMove = (event) => {
+        if (passes(event))
+            return;
+        if (event.type === 'touchmove' || event.pointerType === 'touch') {
+            if (tapPicks && far(point(event)))
+                dragged = true;
+            return;
+        }
+        const where = point(event);
+        if (where)
+            hover(where.x, where.y);
+    };
+    const onWheel = (event) => {
+        if (passes(event))
+            return;
+        const delta = event.deltaY;
+        stop(event);
+        if (delta < 0)
+            move('up');
+        else if (delta > 0)
+            move('down');
+    };
+    const onKey = (event) => {
+        const key = event;
+        if (keys === 'outside-ignored' && inIgnored(event))
+            return;
+        stop(event);
+        if (event.type !== 'keydown')
+            return;
+        if (key.key === 'Escape')
+            end({ kind: 'cancelled' });
+        else if (key.key === 'ArrowUp')
+            move('up');
+        else if (key.key === 'ArrowDown')
+            move('down');
+        else if (key.key === 'Tab')
+            tab(key.shiftKey);
+        else if (key.key === 'Enter')
+            pin({ add: key.shiftKey });
+    };
+    const onSubmit = (event) => { stop(event); };
+    const listen = (type, handler, passive = false) => {
+        const listenerOptions = { capture: true, passive };
+        view.addEventListener(type, handler, listenerOptions);
+        removers.push(() => view.removeEventListener(type, handler, listenerOptions));
+    };
+    const listenAll = () => {
+        for (const type of POINTER_EVENTS)
+            listen(type, onPointer);
+        for (const type of ['pointermove', 'mousemove', 'touchmove'])
+            listen(type, onMove, true);
+        for (const type of KEY_EVENTS)
+            listen(type, onKey);
+        if (wheel)
+            listen('wheel', onWheel);
+        listen('submit', onSubmit);
+    };
+    const suspend = (on) => {
+        if (mode !== 'picking' || on === suspended)
+            return;
+        suspended = on;
+        if (on) {
+            for (const remove of removers.splice(0))
+                remove();
+            current = undefined;
+            refusal = undefined;
+            trail = [];
+        }
+        else
+            listenAll();
+        changed();
+    };
+    const start = () => {
+        if (mode === 'picking')
+            return new Promise(resolve => { const previous = settle; settle = result => { previous?.(result); resolve(result); }; });
+        mode = 'picking';
+        pins = [];
+        current = undefined;
+        refusal = undefined;
+        touch = false;
+        suspended = false;
+        trail = [];
+        focus = document.activeElement;
+        listenAll();
+        const promise = new Promise(resolve => { settle = resolve; });
+        changed();
+        return promise;
+    };
+    return {
+        start,
+        cancel: () => end({ kind: 'cancelled' }),
+        finish,
+        parent: () => move('up'),
+        child: () => move('down'),
+        pin,
+        select,
+        state,
+        overlay,
+        highlight: (element, note) => overlay.highlight(element, note),
+        suspend,
+        dispose: () => {
+            end({ kind: 'cancelled' });
+            mode = 'idle';
+            if (ownsOverlay)
+                overlay.dispose();
+            else
+                overlay.clear();
+        },
+    };
+}
+function isElement(target) {
+    return typeof target.hasAttribute === 'function' && target.nodeType === 1;
+}

package/dist/page/privacy/digest.d.ts

@@ -0,0 +1,6 @@
+import type { AppDomSnapshot } from './serialize.js';
+/** JSON with object keys sorted at every level and no whitespace. Only JSON values (no `undefined`, functions or cycles) are accepted. */
+export declare function canonicalJson(value: unknown): string;
+/** Lower-case hex SHA-256 of `canonicalJson(snapshot)`. */
+export declare function pageDigest(snapshot: AppDomSnapshot): Promise<string>;
+//# sourceMappingURL=digest.d.ts.map

package/dist/page/privacy/digest.js

@@ -0,0 +1,24 @@
+// The page digest: SHA-256 (hex) of the snapshot's canonical JSON, through the platform module so it works on insecure origins too.
+import { sha256 } from '@hachej/boring-files/platform';
+/** JSON with object keys sorted at every level and no whitespace. Only JSON values (no `undefined`, functions or cycles) are accepted. */
+export function canonicalJson(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new TypeError('Non-finite number in canonical JSON');
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record).sort().map(key => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+    }
+    throw new TypeError(`Not a JSON value: ${typeof value}`);
+}
+/** Lower-case hex SHA-256 of `canonicalJson(snapshot)`. */
+export async function pageDigest(snapshot) {
+    const digest = await sha256(new TextEncoder().encode(canonicalJson(snapshot)));
+    return Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('');
+}

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

@@ -0,0 +1,6 @@
+export { createPrivacyPolicy, policyRecord, titleFor, maskText, keptValue, keptAttributeValue, SOURCE_LOCATION, inVisibleRegion, isExcluded, isAlwaysMasked, allowedAttributes, DEFAULT_KEPT_ATTRIBUTES, VISIBLE_REGION_ATTRIBUTES, FEEDBACK_VISIBLE_ATTRIBUTE, FEEDBACK_IGNORE_ATTRIBUTE, FEEDBACK_OVERLAY_ATTRIBUTE, MASKED_NAME, type PrivacyPolicy, type PrivacyPolicyOptions, type RouteLocation, } from './policy.js';
+export { serializeElement, serializePage, PAGE_LIMITS, ELEMENT_LIMITS, type AppDomNode, type AppDomSnapshot, type AppDomLimits, type SerializeElementOptions } from './serialize.js';
+export { accessibleNameOf } from './name.js';
+export { routeFor, maskedPath } from './route.js';
+export { pageDigest, canonicalJson } from './digest.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/page/privacy/index.js

@@ -0,0 +1,5 @@
+export { createPrivacyPolicy, policyRecord, titleFor, maskText, keptValue, keptAttributeValue, SOURCE_LOCATION, inVisibleRegion, isExcluded, isAlwaysMasked, allowedAttributes, DEFAULT_KEPT_ATTRIBUTES, VISIBLE_REGION_ATTRIBUTES, FEEDBACK_VISIBLE_ATTRIBUTE, FEEDBACK_IGNORE_ATTRIBUTE, FEEDBACK_OVERLAY_ATTRIBUTE, MASKED_NAME, } from './policy.js';
+export { serializeElement, serializePage, PAGE_LIMITS, ELEMENT_LIMITS } from './serialize.js';
+export { accessibleNameOf } from './name.js';
+export { routeFor, maskedPath } from './route.js';
+export { pageDigest, canonicalJson } from './digest.js';

package/dist/page/privacy/name.d.ts

@@ -0,0 +1,8 @@
+import { type PrivacyPolicy } from './policy.js';
+/**
+ * The element's accessible name, from allowed sources only: `aria-labelledby` and `<label>` targets and the element's own text when
+ * that text is visible, and `aria-label` only inside a visible region. Values, placeholders, `title`, `alt` and masked text are never
+ * used; the result is then `masked`.
+ */
+export declare function accessibleNameOf(element: Element, policy: PrivacyPolicy): string;
+//# sourceMappingURL=name.d.ts.map

package/dist/page/privacy/name.js

@@ -0,0 +1,106 @@
+// Accessible names from allowed sources only. A name is either fully readable or `masked`: one masked piece masks the whole name.
+import { MASKED_NAME, inVisibleRegion, isAlwaysMasked, isExcluded, keptValue, normalizeText } from './policy.js';
+const MAX_NAME = 120;
+const ELEMENT_NODE = 1, TEXT_NODE = 3, CDATA_NODE = 4;
+const SKIPPED = new Set(['head', 'title', 'script', 'style', 'noscript', 'template', 'iframe', 'object', 'embed']);
+const LABELABLE = new Set(['input', 'select', 'textarea', 'button', 'meter', 'output', 'progress']);
+/** Elements whose name comes only from a label, never from their own content or value. */
+const LABEL_ONLY = new Set(['input', 'select', 'textarea', 'output', 'img', 'meter', 'progress']);
+const VALUELESS_INPUTS = new Set(['checkbox', 'radio', 'hidden', 'file', 'image']);
+/** Whether an embedded form control would put its value or content into the enclosing name. */
+function contributesValue(control) {
+    if (control.localName === 'input')
+        return !VALUELESS_INPUTS.has((control.getAttribute('type') ?? 'text').toLowerCase());
+    return control.localName === 'select' || control.localName === 'textarea' || normalizeText(control.textContent ?? '') !== '';
+}
+/** Visible text of a subtree, or `undefined` when any piece of it would be masked. Hidden and excluded subtrees contribute nothing. */
+function readableText(element, policy) {
+    if (SKIPPED.has(element.localName) || isExcluded(element) || element.hasAttribute('hidden') || element.getAttribute('aria-hidden') === 'true')
+        return '';
+    const parts = [];
+    for (const child of Array.from(element.childNodes)) {
+        if (child.nodeType === TEXT_NODE || child.nodeType === CDATA_NODE) {
+            const text = normalizeText(child.nodeValue ?? '');
+            if (!text)
+                continue;
+            if (isAlwaysMasked(element) || !inVisibleRegion(element, policy))
+                return undefined;
+            parts.push(text);
+        }
+        else if (child.nodeType === ELEMENT_NODE) {
+            const inner = child;
+            // A form control inside a label or button contributes its value in the accessibility tree; values are never read.
+            if (isAlwaysMasked(inner)) {
+                if (contributesValue(inner))
+                    return undefined;
+                continue;
+            }
+            const text = readableText(inner, policy);
+            if (text === undefined)
+                return undefined;
+            if (text)
+                parts.push(text);
+        }
+    }
+    return normalizeText(parts.join(' '));
+}
+function labelsOf(element) {
+    const labels = element.labels;
+    if (labels)
+        return Array.from(labels);
+    const found = [];
+    const wrapping = element.parentElement?.closest('label');
+    if (wrapping)
+        found.push(wrapping);
+    const id = element.getAttribute('id');
+    if (id)
+        for (const label of Array.from(element.ownerDocument.querySelectorAll('label[for]')))
+            if (label.getAttribute('for') === id && !found.includes(label))
+                found.push(label);
+    return found;
+}
+function joined(sources, policy) {
+    const parts = [];
+    for (const source of sources) {
+        const text = readableText(source, policy);
+        if (text === undefined)
+            return undefined;
+        if (text)
+            parts.push(text);
+    }
+    return normalizeText(parts.join(' '));
+}
+function bounded(name) {
+    if (!name)
+        return MASKED_NAME;
+    const points = Array.from(name);
+    return points.length > MAX_NAME ? `${points.slice(0, MAX_NAME - 1).join('')}…` : name;
+}
+/**
+ * The element's accessible name, from allowed sources only: `aria-labelledby` and `<label>` targets and the element's own text when
+ * that text is visible, and `aria-label` only inside a visible region. Values, placeholders, `title`, `alt` and masked text are never
+ * used; the result is then `masked`.
+ */
+export function accessibleNameOf(element, policy) {
+    if (isExcluded(element))
+        return MASKED_NAME;
+    const labelledBy = normalizeText(element.getAttribute('aria-labelledby') ?? '');
+    if (labelledBy) {
+        const sources = labelledBy.split(' ').map(id => element.ownerDocument.getElementById(id));
+        if (sources.some(source => source === null || isExcluded(source)))
+            return MASKED_NAME;
+        return bounded(joined(sources, policy));
+    }
+    const label = element.getAttribute('aria-label');
+    if (label !== null && normalizeText(label))
+        return inVisibleRegion(element, policy) && keptValue(label) ? bounded(normalizeText(label)) : MASKED_NAME;
+    const tag = element.localName;
+    if (LABELABLE.has(tag) && !(tag === 'input' && element.getAttribute('type')?.toLowerCase() === 'hidden')) {
+        const labels = labelsOf(element);
+        if (labels.length)
+            return bounded(joined(labels, policy));
+    }
+    if (LABEL_ONLY.has(tag) || isAlwaysMasked(element))
+        return MASKED_NAME;
+    return bounded(readableText(element, policy));
+}

package/dist/page/privacy/policy.d.ts

@@ -0,0 +1,65 @@
+/** Marks a region whose text (and `aria-label`/`aria-description`) may leave the page. Presence counts, whatever its value. */
+export declare const FEEDBACK_VISIBLE_ATTRIBUTE = "data-feedback-visible";
+/** Marks a subtree that is never serialized, named or picked (the application's own chrome, the agent bar). */
+export declare const FEEDBACK_IGNORE_ATTRIBUTE = "data-feedback-ignore";
+/** Marks the picker overlay's host element; it and its subtree are excluded from every snapshot. */
+export declare const FEEDBACK_OVERLAY_ATTRIBUTE = "data-feedback-overlay";
+/** The name returned whenever the accessible name would come from masked or disallowed sources. */
+export declare const MASKED_NAME = "masked";
+/** Attributes kept by default. Values still pass `keptValue`. */
+export declare const DEFAULT_KEPT_ATTRIBUTES: readonly string[];
+/** Kept only inside a visible region. */
+export declare const VISIBLE_REGION_ATTRIBUTES: readonly string[];
+/** What `routeOf` receives: the parts of a `Location` the route is derived from. */
+export interface RouteLocation {
+    readonly pathname: string;
+    readonly search?: string;
+    readonly hash?: string;
+}
+export interface PrivacyPolicyOptions {
+    /** Extra attribute names to keep (lower case). Their values still pass the digit/`@` rule. */
+    readonly allowAttributes?: readonly string[];
+    /** A CSS selector whose matches (and their descendants) count as visible regions, besides `data-feedback-visible`. */
+    readonly visibleSelector?: string;
+    /** The application's route template for a location (`/orders/:id`). Its query and fragment are cut. */
+    readonly routeOf?: (location: RouteLocation) => string;
+    /** A document label supplied by the application; the document title is never read. */
+    readonly label?: string;
+}
+export interface PrivacyPolicy {
+    readonly version: 1;
+    /** Every loosening of the default, in a stable order: `allowAttributes:<name>`, `visibleSelector:<selector>`, `routeOf`, `label`. */
+    readonly widened: readonly string[];
+    readonly allowAttributes: readonly string[];
+    readonly visibleSelector?: string;
+    readonly routeOf?: (location: RouteLocation) => string;
+    readonly label?: string;
+}
+/** Builds the frozen version 1 policy. Throws on attribute names that name an always-masked channel or are malformed. */
+export declare function createPrivacyPolicy(options?: PrivacyPolicyOptions): PrivacyPolicy;
+/** The policy as a report records it (`observed.policy` in `feedback@1`). */
+export declare function policyRecord(policy: PrivacyPolicy): {
+    readonly version: number;
+    readonly widened: readonly string[];
+};
+/** The document title as it may leave the page: only the application's label, never `document.title`. */
+export declare function titleFor(policy: PrivacyPolicy): string | undefined;
+/** `*` of equal length, per code point. */
+export declare function maskText(text: string): string;
+/** Whitespace runs collapse to one space; ends are trimmed. */
+export declare function normalizeText(text: string): string;
+/** A kept attribute value with three or more digits in a row, or an `@`, is dropped. */
+export declare function keptValue(value: string): boolean;
+/** `data-source` is code, not page data: a project-relative `path:line` (WP8's development stamp)
+ * is kept whatever its line number; anything else (absolute, parent, URL, `@`, odd characters) is dropped. */
+export declare const SOURCE_LOCATION: RegExp;
+export declare function keptAttributeValue(name: string, value: string): boolean;
+/** True when the element or an ancestor marks a visible region. */
+export declare function inVisibleRegion(element: Element, policy: PrivacyPolicy): boolean;
+/** True when the element is, or is inside, an ignored subtree or the picker overlay. */
+export declare function isExcluded(element: Element): boolean;
+/** Form values, `textarea` and `contenteditable` content: masked even inside a visible region. */
+export declare function isAlwaysMasked(element: Element): boolean;
+/** The allowed attributes of one element, keys sorted. */
+export declare function allowedAttributes(element: Element, policy: PrivacyPolicy): Readonly<Record<string, string>>;
+//# sourceMappingURL=policy.d.ts.map