@satinhq/kit 0.0.0-stage → 0.1.0-beta.0

package/dist/glass/presentationFrame.js

@@ -0,0 +1,82 @@
+/** How glass reads a presentation that is held for its first glass or travelling on screen.
+ *
+ * Hold: a presentation waiting for its first glass is hidden by one stylesheet rule keyed on
+ * `data-satin-glass-hold`, never by inline styles. The rule clips the held node to nothing: no
+ * paint and no hit testing, while layout and computed visibility stay exactly as they will show.
+ * Source preparation therefore reads a held presentation directly, with no style change (toggling
+ * a stylesheet restyles the whole document: about 216 ms per read on an iPad behind a long thread),
+ * and content an author hid inside the presentation stays hidden.
+ *
+ * Travel: a sheet or cover moves as one rigid layer (its entrance, drag and dismissal are a
+ * translation of the presentation's glass layer). Glass nested in the presentation and the
+ * presentation's own content planes are placed in that layer's resting frame. The compositor moves
+ * them together, so nested glass keeps its pixels while the surface travels, as native glass in a
+ * sheet does. The presentation's own material is not nested: it samples the screen below it live. */
+const HOLD_ATTRIBUTE = 'data-satin-glass-hold';
+const SOURCE_ATTRIBUTE = 'data-satin-glass-source';
+const HOLD_RULE = `[${HOLD_ATTRIBUTE}] { clip-path: inset(50%) !important; }`;
+const holdSheets = new WeakMap();
+function holdSheet(document) {
+    let sheet = holdSheets.get(document);
+    if (sheet)
+        return sheet;
+    const style = document.createElement('style');
+    style.dataset.satinGlassHoldStyle = 'true';
+    style.textContent = HOLD_RULE;
+    document.head.append(style);
+    sheet = style.sheet ?? undefined;
+    if (!sheet)
+        throw Error('The presentation glass hold has no stylesheet');
+    holdSheets.set(document, sheet);
+    return sheet;
+}
+/** Hide `node` until `releaseHold` (or a later hold of another generation). */
+export function hold(node, generation) {
+    holdSheet(node.ownerDocument);
+    node.setAttribute(HOLD_ATTRIBUTE, generation);
+}
+/** End this generation's hold; a newer generation keeps its own. */
+export function releaseHold(node, generation) {
+    if (node.getAttribute(HOLD_ATTRIBUTE) !== generation)
+        return;
+    node.removeAttribute(HOLD_ATTRIBUTE);
+    if (node.getAttribute(SOURCE_ATTRIBUTE) === generation)
+        node.removeAttribute(SOURCE_ATTRIBUTE);
+}
+/** The held presentations a source preparation is about to measure, with their generations. */
+export function heldPresentations(document = globalThis.document) {
+    return [...document.querySelectorAll(`[${HOLD_ATTRIBUTE}]`)].map(node => [node, node.getAttribute(HOLD_ATTRIBUTE)]);
+}
+/** The renderer holds a backdrop measured during these holds: each still-current hold may now
+ * wait for its glass to be drawn over it (holdPresentationForGlass). */
+export function confirmHeldSources(held) {
+    for (const [node, generation] of held)
+        if (node.isConnected && node.getAttribute(HOLD_ATTRIBUTE) === generation)
+            node.setAttribute(SOURCE_ATTRIBUTE, generation);
+}
+const AT_REST = { x: 0, y: 0 };
+/** The current travel of the sheet or cover that `element` is nested in (zero when it is the
+ * presentation's own surface, outside any presentation, or at rest). */
+export function presentationTravel(element) {
+    if (typeof element.closest !== 'function')
+        return AT_REST;
+    const layer = element.closest('[data-satin-glass-layer]');
+    const surface = element.parentElement?.closest('.satin-presentation-surface');
+    if (!layer || !surface || !layer.contains(surface))
+        return AT_REST;
+    const dialog = layer.closest('dialog');
+    const kind = dialog?.getAttribute('data-satin-presentation');
+    if (kind !== 'sheet' && kind !== 'cover')
+        return AT_REST;
+    const transform = getComputedStyle(layer).transform;
+    if (!transform || transform === 'none')
+        return AT_REST;
+    const matrix = new DOMMatrixReadOnly(transform);
+    if (!matrix.e && !matrix.f)
+        return AT_REST;
+    return { x: matrix.e, y: matrix.f, layer };
+}
+/** A viewport rectangle of something inside the travelling layer, in the layer's resting frame. */
+export function atRest(rect, travel) {
+    return { x: rect.x - travel.x, y: rect.y - travel.y, width: rect.width, height: rect.height };
+}

package/dist/glass/pressHighlight.d.ts

@@ -0,0 +1,9 @@
+import { type GlassContactKind } from './contactPhysics.js';
+type Target = {
+    host: HTMLElement;
+    labels: readonly Element[];
+};
+export declare function glassPressHighlight({ host, labels }: Target, phase: 'pressed' | 'releasing' | 'rest', epoch?: number, kind?: GlassContactKind): void;
+/** Current uniform scale of a pressed glass button (the renderer's spring, replayed). */
+export declare function glassPressScale(host: HTMLElement, at?: number): number;
+export {};

package/dist/glass/pressHighlight.js

@@ -0,0 +1,158 @@
+import { GLASS_CONTACT_PHYSICS } from './contactPhysics.js';
+import { INTERACTIVE_GLASS_PRESS, InteractivePress } from './lens/interactivePress.js';
+/**
+ * The label half of a pressed interactive glass button (the renderer grows and whitens the glass
+ * in the same frame). Labels stay live DOM above the glass; each kind's label response is a row
+ * of GLASS_CONTACT_PHYSICS (native iPad): a content button's label holds full strength, a bar
+ * button's light label washes out into its white glass and its dark label dips for a frame.
+ *
+ * The label grows with its glass: native iPad scales a held button's label by the glass's own
+ * growth (the composer + glyph, "Actions", the toolbar "Save"), and it springs back with the
+ * glass. The label replays the renderer's press spring (InteractivePress) about the glass's
+ * centre.
+ *
+ * Opacity and `scale` Web Animations only: no layout, no renderer round trip.
+ */
+const GPU_LATENCY_MS = 1000 / 60;
+const running = new WeakMap();
+const scaling = new WeakMap();
+const FRAME_MS = 1000 / 60;
+/** Long enough for the release spring's ringing to fall under a hundredth of a point. */
+const SETTLE_MS = 1200;
+const presses = new WeakMap();
+const motionSubscriptions = new WeakMap();
+const reducedMotion = () => matchMedia('(prefers-reduced-motion: reduce)').matches;
+/** Dark glass carries light labels: the label's own colour decides the fitted response. */
+function appearanceOf(labels, host) {
+    const colour = getComputedStyle(labels[0] ?? host)
+        .color.match(/[\d.]+/g)
+        ?.slice(0, 3)
+        .map(Number) ?? [0, 0, 0];
+    return (colour[0] * 0.2126 + colour[1] * 0.7152 + colour[2] * 0.0722) / 255 > 0.5
+        ? 'dark'
+        : 'light';
+}
+/** The glass release of this kind and appearance, which the label returns over. */
+function releaseMs(kind, appearance) {
+    const light = GLASS_CONTACT_PHYSICS[kind].light;
+    return light.kind === 'whole' ? light.releaseMs[appearance] : 0;
+}
+export function glassPressHighlight({ host, labels }, phase, epoch = performance.timeOrigin + performance.now(), kind = 'button') {
+    let press = presses.get(host);
+    if (phase === 'rest') {
+        presses.delete(host);
+    }
+    else {
+        if (!press) {
+            press = new InteractivePress();
+            presses.set(host, press);
+        }
+        if (reducedMotion())
+            press.reset();
+        else if (phase === 'pressed')
+            press.down(epoch);
+        else
+            press.up(epoch);
+    }
+    if (typeof host.animate !== 'function')
+        return;
+    scaleLabels(host, labels, kind, epoch, phase);
+    const current = labels.map(label => Number(getComputedStyle(label).opacity));
+    for (const animation of running.get(host) ?? [])
+        animation.cancel();
+    const appearance = appearanceOf(labels, host);
+    if (phase === 'pressed') {
+        const curve = GLASS_CONTACT_PHYSICS[kind].label[appearance];
+        if (curve === 'steady') {
+            running.set(host, []);
+            return;
+        }
+        const duration = curve.at(-1)[0];
+        const frames = curve.map(([ms, opacity]) => ({ offset: ms / duration, opacity }));
+        // The glass's white arrives from the worker ~1 frame after a DOM animation starts (measured):
+        // a light label washes out with it, not before it. A dark label dips first (native).
+        const delay = appearance === 'light' ? GPU_LATENCY_MS : 0;
+        running.set(host, labels.map(label => label.animate(frames, { duration, delay, fill: 'forwards', easing: 'linear' })));
+        return;
+    }
+    const duration = phase === 'rest' ? 0 : releaseMs(kind, appearance);
+    running.set(host, labels.map((label, i) => label.animate([{ opacity: current[i] }, { opacity: 1 }], {
+        duration,
+        fill: 'forwards',
+        easing: 'linear',
+    })));
+}
+/** Current uniform scale of a pressed glass button (the renderer's spring, replayed). */
+export function glassPressScale(host, at = performance.timeOrigin + performance.now()) {
+    const record = presses.get(host), width = host.getBoundingClientRect().width;
+    if (!record || !width || reducedMotion())
+        return 1;
+    const press = record.copy();
+    const pressKind = host.dataset.satinGlassPressKind;
+    const kind = pressKind === 'menu' || pressKind === 'bar' ? pressKind : 'button';
+    return 1 + (INTERACTIVE_GLASS_PRESS.growthPt[kind] / width) * press.sample(at);
+}
+/** The press growth of this glass, as a uniform scale of its layout width at press `amount`. */
+function growth(host, kind) {
+    const width = host.offsetWidth;
+    return (amount) => width ? 1 + (INTERACTIVE_GLASS_PRESS.growthPt[kind] / width) * amount : 1;
+}
+/** Scales the labels with the glass: the press spring from now until it settles (or holds). */
+function scaleLabels(host, labels, kind, epoch, phase) {
+    motionSubscriptions.get(host)?.();
+    motionSubscriptions.delete(host);
+    for (const animation of scaling.get(host) ?? [])
+        animation.cancel();
+    const record = presses.get(host);
+    if (!record) {
+        scaling.set(host, []);
+        return;
+    }
+    const press = record.copy();
+    const reduced = reducedMotion();
+    const scale = growth(host, kind);
+    const frames = [];
+    for (let ms = 0; ms <= SETTLE_MS; ms += FRAME_MS) {
+        const amount = press.sample(epoch + ms, reduced);
+        frames.push({ scale: String(scale(amount)) });
+        if (ms > 0 && !press.needsFrame)
+            break;
+    }
+    const duration = Math.max(FRAME_MS, (frames.length - 1) * FRAME_MS);
+    const centre = host.getBoundingClientRect();
+    const animations = labels
+        .filter((label) => label instanceof HTMLElement)
+        .map(label => {
+        // Grow about the glass's centre, as the glass does, not the label's own.
+        const box = label.getBoundingClientRect();
+        label.style.transformOrigin = `${centre.left + centre.width / 2 - box.left}px ${centre.top + centre.height / 2 - box.top}px`;
+        return label.animate(frames, { duration, fill: 'forwards', easing: 'linear' });
+    });
+    scaling.set(host, animations);
+    if (reducedMotion())
+        return;
+    const query = matchMedia('(prefers-reduced-motion: reduce)');
+    const stop = () => query.removeEventListener('change', changed);
+    const changed = () => {
+        if (!query.matches)
+            return;
+        // Match the worker's live preference change: retire growth, keep its light response.
+        record.reset();
+        for (const animation of animations)
+            animation.cancel();
+        scaling.set(host, []);
+        stop();
+        motionSubscriptions.delete(host);
+    };
+    query.addEventListener('change', changed);
+    motionSubscriptions.set(host, stop);
+    if (phase === 'releasing') {
+        const finished = animations.map(animation => animation.finished?.catch(() => { }));
+        void Promise.all(finished).then(() => {
+            if (motionSubscriptions.get(host) !== stop)
+                return;
+            stop();
+            motionSubscriptions.delete(host);
+        });
+    }
+}

package/dist/glass/regionRegistry.d.ts

@@ -0,0 +1,93 @@
+import type { GlassInteraction, GlassRegionEvent } from './rendererContract.js';
+import { type GlassRegion } from './regions.js';
+export type GlassRegionRegistration = Readonly<{
+    id: string;
+    element: HTMLElement;
+    canvas: HTMLCanvasElement;
+    overlay?: HTMLCanvasElement;
+    descriptor: Omit<GlassRegion, 'frame' | 'layer'> & {
+        layer?: GlassRegion['layer'];
+    };
+}>;
+/** DOM ownership stays here. Only GlassRegion snapshots cross a worker boundary. */
+export declare class GlassRegionRegistry {
+    readonly interactions: Map<string, Readonly<{
+        regionId: string;
+        phase: 'rest' | 'pressed' | 'dragging' | 'releasing';
+        epoch: number;
+        contact?: Readonly<{
+            x: number;
+            y: number;
+        }>;
+    }>>;
+    private inputListeners;
+    subscribeInput: (listener: (input: GlassInteraction) => void) => () => void;
+    private contentObservers;
+    private contentListeners;
+    subscribeContent: (listener: (element: HTMLElement) => void) => () => void;
+    private contentChanged;
+    interact(input: GlassInteraction): void;
+    readonly containers: Map<string, {
+        element: HTMLElement;
+        canvas: HTMLCanvasElement;
+        continuous: boolean;
+    }>;
+    registerContainer(id: string, element: HTMLElement, canvas: HTMLCanvasElement): () => void;
+    private entries;
+    /** Monotonic ownership boundary for asynchronous captures and queued scenes. */
+    private retired;
+    get retirementVersion(): number;
+    private snapshotRevision;
+    /** Async captures and parked scenes must match both ownership and menu motion state. */
+    get snapshotVersion(): number;
+    private settleListeners;
+    /** The renderer finished a region's close morph (GlassEffect emerge). */
+    onEmergeSettled(id: string, listener: (generation?: number) => void): () => void;
+    emergeSettled(id: string, generation?: number): void;
+    /** Retained aperture metadata; morph menus do not bind this property to CSS clipping. */
+    emergeAperture(event: {
+        type: 'emerge-aperture';
+        regionId: string;
+        generation?: number;
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+        radius: number;
+    }): void;
+    /** Synchronize retained foreground with the worker's submitted field spring. */
+    fieldMotion(event: Extract<GlassRegionEvent, {
+        type: 'field-motion';
+    }>): void;
+    private inkListeners;
+    /** The glass moved a menu's rows between its ink and the page's live DOM. */
+    onEmergeInk(id: string, listener: (phase: 'open-settled' | 'close-started', generation?: number) => void): () => void;
+    emergeInk(event: Extract<GlassRegionEvent, {
+        type: 'emerge-ink';
+    }>): void;
+    private listeners;
+    get size(): number;
+    values(): Readonly<{
+        id: string;
+        element: HTMLElement;
+        canvas: HTMLCanvasElement;
+        overlay?: HTMLCanvasElement;
+        descriptor: Omit<GlassRegion, 'frame' | 'layer'> & {
+            layer?: GlassRegion['layer'];
+        };
+    }>[];
+    subscribe: (listener: () => void) => () => void;
+    private presentationListeners;
+    /** A committed drop transition already has layout; do not wait for another display tick. */
+    subscribePresentation: (listener: () => void) => () => void;
+    invalidatePresentation: () => void;
+    invalidate: () => void;
+    /** Update a persistent navigation item's presentation without replacing its registration. */
+    updateShape(id: string, shape: GlassRegion['shape']): void;
+    updatePresentation(id: string, presentation: Pick<GlassRegion, 'material' | 'shape'>): void;
+    /** Move a region's segmented selection (the scope bar's thumb); the renderer slides it. */
+    updateSelection(id: string, selection: GlassRegion['selection']): void;
+    /** Keep the canvas, observer and contact while the existing menu motion changes generation. */
+    updateEmerge(id: string, emerge: GlassRegion['emerge']): void;
+    register(entry: GlassRegionRegistration): () => void;
+}

package/dist/glass/regionRegistry.js

@@ -0,0 +1,313 @@
+import { animateElement } from '../motion/animate.js';
+import { sampleFieldAxis } from './fieldMotion.js';
+import { glassIdentityKey } from './morphField.js';
+import { GLASS_REGION_LIMIT, isPlainMenuSource } from './regions.js';
+/** DOM ownership stays here. Only GlassRegion snapshots cross a worker boundary. */
+export class GlassRegionRegistry {
+    interactions = new Map();
+    inputListeners = new Set();
+    subscribeInput = (listener) => {
+        this.inputListeners.add(listener);
+        return () => {
+            this.inputListeners.delete(listener);
+        };
+    };
+    contentObservers = new Map();
+    contentListeners = new Set();
+    subscribeContent = (listener) => {
+        this.contentListeners.add(listener);
+        return () => {
+            this.contentListeners.delete(listener);
+        };
+    };
+    contentChanged(entry, records) {
+        const changed = records.some(record => {
+            const target = record.target instanceof Element ? record.target : record.target.parentElement;
+            // Presenter sizing/visibility belongs to the renderer, not the captured content.
+            return (target &&
+                target.tagName !== 'CANVAS' &&
+                (record.type !== 'attributes' ||
+                    record.attributeName !== 'style' ||
+                    (target !== entry.element && !target.hasAttribute('data-satin-glass-field-content'))));
+        });
+        if (!changed)
+            return;
+        this.snapshotRevision++;
+        for (const listener of this.contentListeners)
+            listener(entry.element);
+        this.invalidate();
+    }
+    interact(input) {
+        // A React commit and DOWN may share a task, before MutationObserver delivery.
+        const entry = this.entries.get(input.regionId);
+        const observer = this.contentObservers.get(input.regionId);
+        if (entry && observer)
+            this.contentChanged(entry, observer.takeRecords());
+        const descriptor = this.entries.get(input.regionId)?.descriptor;
+        const material = descriptor?.material;
+        // A segmented glass (the search scope bar) takes the finger for its thumb and its own press,
+        // though its material is not an interactive button's.
+        if (!material?.interactive && !material?.touchLight && !descriptor?.selection)
+            return;
+        this.interactions.set(input.regionId, input);
+        for (const listener of this.inputListeners)
+            listener(input);
+    }
+    containers = new Map();
+    registerContainer(id, element, canvas) {
+        const container = { element, canvas, continuous: false };
+        this.containers.set(id, container);
+        let frame;
+        let disposed = false;
+        const sampleLayout = () => {
+            frame = undefined;
+            if (disposed)
+                return;
+            // CSS owns these trajectories. Foreground WAAPI springs must not keep this loop alive.
+            const moving = element
+                .getAnimations({ subtree: true })
+                .some(animation => (typeof CSSTransition !== 'undefined' && animation instanceof CSSTransition) ||
+                (typeof CSSAnimation !== 'undefined' && animation instanceof CSSAnimation));
+            container.continuous = moving;
+            this.invalidate();
+            if (moving)
+                frame = requestAnimationFrame(sampleLayout);
+        };
+        const schedule = () => {
+            if (frame === undefined)
+                frame = requestAnimationFrame(sampleLayout);
+        };
+        const observer = new MutationObserver(records => {
+            if (records.some(record => !(record.target instanceof Element) ||
+                !record.target.closest('[data-satin-glass-field-content]')))
+                schedule();
+        });
+        observer.observe(element, {
+            attributes: true,
+            attributeFilter: ['style', 'class'],
+            subtree: true,
+            childList: true,
+        });
+        element.addEventListener('transitionrun', schedule);
+        element.addEventListener('animationstart', schedule);
+        this.invalidate();
+        return () => {
+            disposed = true;
+            observer.disconnect();
+            element.removeEventListener('transitionrun', schedule);
+            element.removeEventListener('animationstart', schedule);
+            if (frame !== undefined)
+                cancelAnimationFrame(frame);
+            this.containers.delete(id);
+            this.invalidate();
+        };
+    }
+    entries = new Map();
+    /** Monotonic ownership boundary for asynchronous captures and queued scenes. */
+    retired = 0;
+    get retirementVersion() {
+        return this.retired;
+    }
+    snapshotRevision = 0;
+    /** Async captures and parked scenes must match both ownership and menu motion state. */
+    get snapshotVersion() {
+        return this.snapshotRevision;
+    }
+    settleListeners = new Map();
+    /** The renderer finished a region's close morph (GlassEffect emerge). */
+    onEmergeSettled(id, listener) {
+        const set = this.settleListeners.get(id) ?? new Set();
+        set.add(listener);
+        this.settleListeners.set(id, set);
+        return () => {
+            set.delete(listener);
+            if (!set.size)
+                this.settleListeners.delete(id);
+        };
+    }
+    emergeSettled(id, generation) {
+        for (const listener of [...(this.settleListeners.get(id) ?? [])])
+            listener(generation);
+    }
+    /** Retained aperture metadata; morph menus do not bind this property to CSS clipping. */
+    emergeAperture(event) {
+        const entry = this.entries.get(event.regionId);
+        if (!entry ||
+            entry.descriptor.emerge?.closing ||
+            entry.descriptor.emerge?.generation !== event.generation)
+            return;
+        const edges = [event.top, event.right, event.bottom, event.left]
+            .map(value => `calc(${value}px - var(--satin-glass-content-inset, 0px))`)
+            .join(' ');
+        entry.element.style.setProperty('--satin-glass-emerge-clip', `inset(${edges} round max(0px, calc(${event.radius}px - var(--satin-glass-content-inset, 0px))))`);
+    }
+    /** Synchronize retained foreground with the worker's submitted field spring. */
+    fieldMotion(event) {
+        const content = this.entries
+            .get(event.regionId)
+            ?.element.querySelector('[data-satin-glass-field-content]');
+        if (!content)
+            return;
+        for (const animation of content.getAnimations())
+            animation.cancel();
+        if (!event.duration)
+            return;
+        // A composer commits its editing viewport before caret reveal. The material
+        // may interpolate its height, but scaling that live viewport again compresses
+        // glyphs and moves WebKit's independently painted caret. Keep editable ink at
+        // its settled geometry during a vertical field resize.
+        if (Math.abs(event.scaleY - 1) > 0.0001 &&
+            content.querySelector('input, textarea, [contenteditable="true"]'))
+            return;
+        const frames = Array.from({ length: 121 }, (_, index) => {
+            const elapsed = (index / 120) * event.duration;
+            const axis = (from, to, velocity = 0) => index === 120 ? to : sampleFieldAxis(from, to, velocity, elapsed).value;
+            return {
+                offset: index / 120,
+                transform: `translate(${axis(event.offsetX, 0, event.velocityX)}px, ${axis(event.offsetY, 0, event.velocityY)}px) ` +
+                    `scale(${axis(event.scaleX, 1, event.velocityScaleX)}, ${axis(event.scaleY, 1, event.velocityScaleY)})`,
+            };
+        });
+        const animation = animateElement(content, frames, {
+            duration: event.duration,
+            easing: 'linear',
+        });
+        animation.currentTime = Math.max(0, performance.timeOrigin + performance.now() - event.start);
+    }
+    inkListeners = new Map();
+    /** The glass moved a menu's rows between its ink and the page's live DOM. */
+    onEmergeInk(id, listener) {
+        const set = this.inkListeners.get(id) ?? new Set();
+        set.add(listener);
+        this.inkListeners.set(id, set);
+        return () => {
+            set.delete(listener);
+            if (!set.size)
+                this.inkListeners.delete(id);
+        };
+    }
+    emergeInk(event) {
+        for (const listener of [...(this.inkListeners.get(event.regionId) ?? [])])
+            listener(event.phase, event.generation);
+    }
+    listeners = new Set();
+    get size() {
+        return this.entries.size;
+    }
+    values() {
+        return [...this.entries.values()];
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    presentationListeners = new Set();
+    /** A committed drop transition already has layout; do not wait for another display tick. */
+    subscribePresentation = (listener) => {
+        this.presentationListeners.add(listener);
+        return () => {
+            this.presentationListeners.delete(listener);
+        };
+    };
+    invalidatePresentation = () => {
+        for (const listener of this.presentationListeners)
+            listener();
+    };
+    invalidate = () => {
+        for (const listener of this.listeners)
+            listener();
+    };
+    /** Update a persistent navigation item's presentation without replacing its registration. */
+    updateShape(id, shape) {
+        const entry = this.entries.get(id);
+        if (entry)
+            this.updatePresentation(id, { material: entry.descriptor.material, shape });
+    }
+    updatePresentation(id, presentation) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return;
+        if (JSON.stringify([entry.descriptor.material, entry.descriptor.shape]) ===
+            JSON.stringify([presentation.material, presentation.shape]))
+            return;
+        Object.assign(entry, { descriptor: { ...entry.descriptor, ...presentation } });
+        this.invalidate();
+    }
+    /** Move a region's segmented selection (the scope bar's thumb); the renderer slides it. */
+    updateSelection(id, selection) {
+        const entry = this.entries.get(id);
+        if (!entry || JSON.stringify(entry.descriptor.selection) === JSON.stringify(selection))
+            return;
+        Object.assign(entry, { descriptor: { ...entry.descriptor, selection } });
+        this.invalidate();
+    }
+    /** Keep the canvas, observer and contact while the existing menu motion changes generation. */
+    updateEmerge(id, emerge) {
+        const entry = this.entries.get(id);
+        if (!entry || JSON.stringify(entry.descriptor.emerge) === JSON.stringify(emerge))
+            return;
+        const previous = entry.descriptor.emerge;
+        Object.assign(entry, { descriptor: { ...entry.descriptor, emerge } });
+        // Replacing a descriptor used to unregister it. Preserve that stale-work boundary without
+        // publishing a transient missing region or discarding its active contact.
+        this.snapshotRevision++;
+        this.invalidate();
+        if (isPlainMenuSource(previous?.sourceKind) ||
+            previous?.recognitionEpoch !== undefined ||
+            isPlainMenuSource(emerge?.sourceKind) ||
+            emerge?.recognitionEpoch !== undefined)
+            this.invalidatePresentation();
+    }
+    register(entry) {
+        if (this.entries.has(entry.id))
+            throw new Error(`Duplicate glass registration: ${entry.id}`);
+        if (this.entries.size >= GLASS_REGION_LIMIT)
+            throw new Error(`Glass supports at most ${GLASS_REGION_LIMIT} app regions.`);
+        const identity = glassIdentityKey(entry.descriptor);
+        if (identity && this.values().some(value => glassIdentityKey(value.descriptor) === identity))
+            throw Error(`Duplicate active glassEffectID: ${identity}`);
+        this.entries.set(entry.id, entry);
+        const observer = typeof MutationObserver === 'undefined'
+            ? undefined
+            : new MutationObserver(records => this.contentChanged(entry, records));
+        observer?.observe(entry.element, {
+            subtree: true,
+            childList: true,
+            characterData: true,
+            attributes: true,
+            attributeFilter: [
+                'class',
+                'style',
+                'src',
+                'srcset',
+                'sizes',
+                'd',
+                'viewBox',
+                'fill',
+                'stroke',
+            ],
+        });
+        if (observer)
+            this.contentObservers.set(entry.id, observer);
+        this.invalidate();
+        if (isPlainMenuSource(entry.descriptor.emerge?.sourceKind) ||
+            entry.descriptor.emerge?.recognitionEpoch !== undefined)
+            this.invalidatePresentation();
+        return () => {
+            if (this.entries.get(entry.id) === entry) {
+                observer?.disconnect();
+                this.contentObservers.delete(entry.id);
+                this.entries.delete(entry.id);
+                this.retired++;
+                this.snapshotRevision++;
+                this.interactions.delete(entry.id);
+                this.invalidate();
+                if (isPlainMenuSource(entry.descriptor.emerge?.sourceKind) ||
+                    entry.descriptor.emerge?.recognitionEpoch !== undefined)
+                    this.invalidatePresentation();
+            }
+        };
+    }
+}