view-anchor 0.1.2 → 0.2.0

package/dist/measure-loop.js

@@ -1,39 +1,60 @@
+/**
+ * Internal helper: animation-frame scheduling and deduplication loop for
+ * `createSizeAdvertiser`.
+ *
+ * Coalesces resize triggers into a single requestAnimationFrame, drops
+ * duplicate measurements, and manages disposal.
+ */
 export function createMeasureLoop(cfg) {
     const { produce, same, sink } = cfg;
     let rafId = null;
     let active = false;
     let disposed = false;
     let last = null;
+    let publicationRevision = 0;
+    const deliver = (value) => {
+        const previous = last;
+        const attempt = ++publicationRevision;
+        last = value;
+        try {
+            const accepted = sink(value) !== false;
+            if (!accepted && publicationRevision === attempt)
+                last = previous;
+            return accepted;
+        }
+        catch (error) {
+            if (publicationRevision === attempt)
+                last = previous;
+            throw error;
+        }
+    };
     const cancel = () => {
         if (rafId !== null) {
             cancelAnimationFrame(rafId);
             rafId = null;
         }
     };
+    const frame = () => {
+        rafId = null;
+        if (disposed || !active)
+            return;
+        const value = produce();
+        if (value === null)
+            return;
+        if (last !== null && same(value, last))
+            return;
+        deliver(value);
+    };
     return {
         schedule() {
             if (disposed || !active || rafId !== null)
                 return;
-            rafId = requestAnimationFrame(() => {
-                rafId = null;
-                if (disposed || !active)
-                    return;
-                const value = produce();
-                if (value === null)
-                    return; // producer declined this frame
-                // last-value dedupe: a frame whose produced value equals the last one
-                // we emitted costs nothing (no IPC / setBounds).
-                if (last !== null && same(value, last))
-                    return;
-                last = value;
-                sink(value);
-            });
+            rafId = requestAnimationFrame(frame);
         },
         emitNow(value) {
             if (disposed)
                 return;
-            last = value;
-            sink(value);
+            deliver(value);
         },
         setActive(on) {
             active = on;

package/dist/protocol-publisher.d.ts

@@ -0,0 +1,41 @@
+import type { AdvertisedSize, Placement, Publisher } from './types.js';
+import { type GeometryAddress, type GeometryBatch, type GeometryMessage } from './protocol-types.js';
+export type GeometrySend = Publisher<GeometryMessage>;
+export type GeometryBatchSend = Publisher<GeometryBatch>;
+export interface GeometryBatcherOptions {
+    /** Observes every batch-delivery error, including explicit flushes; it must not throw. */
+    onError?: (error: unknown) => void;
+}
+export interface GeometryBatcher {
+    /** Queues one message. Returns false after disposal. */
+    publish(message: GeometryMessage): boolean;
+    /** Attempts delivery of the current latest-value snapshot; delivery errors return false. */
+    flush(): boolean;
+    /** Forgets one anchor's state, or every anchor when omitted. */
+    clear(anchorId?: string): void;
+    /** Clears pending state; already scheduled microtasks become inert. */
+    dispose(): void;
+}
+/**
+ * Wraps placement updates in a versioned protocol message. Sequence numbers
+ * start at 1 and increment with each attempted delivery.
+ *
+ * Keep one publisher per `{ anchorId, generation }` (e.g. via `useMemo` or `useRef`).
+ * Batchers and sequence guards drop messages with older sequence numbers, so
+ * recreating a publisher for the same address causes its messages to be dropped.
+ * Increment `generation` when intentionally resetting the publisher.
+ */
+export declare function createPlacementMessagePublisher(address: GeometryAddress, send: GeometrySend): (placement: Placement) => boolean;
+/**
+ * Wraps size updates in a versioned protocol message.
+ * Follows the same stability rule: keep one publisher per `{ anchorId, generation }`,
+ * and increment `generation` when resetting.
+ */
+export declare function createSizeMessagePublisher(address: GeometryAddress, send: GeometrySend): (size: AdvertisedSize) => boolean;
+/**
+ * Coalesces same-task messages without adding a rendering-frame delay. It owns
+ * no authorization policy: callers must associate addresses with trusted IPC
+ * senders before accepting a delivered batch.
+ */
+export declare function createGeometryBatcher(send: GeometryBatchSend, options?: GeometryBatcherOptions): GeometryBatcher;
+//# sourceMappingURL=protocol-publisher.d.ts.map

package/dist/protocol-publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-publisher.d.ts","sourceRoot":"","sources":["../src/protocol-publisher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtE,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EAGrB,MAAM,qBAAqB,CAAA;AAE5B,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,eAAe,CAAC,CAAA;AACrD,MAAM,MAAM,iBAAiB,GAAG,SAAS,CAAC,aAAa,CAAC,CAAA;AAExD,MAAM,WAAW,sBAAsB;IACrC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAA;IAC1C,4FAA4F;IAC5F,KAAK,IAAI,OAAO,CAAA;IAChB,gEAAgE;IAChE,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,uEAAuE;IACvE,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,YAAY,GACjB,CAAC,SAAS,EAAE,SAAS,KAAK,OAAO,CAcnC;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,YAAY,GACjB,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAcnC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAkJjB"}

package/dist/protocol-publisher.js

@@ -0,0 +1,191 @@
+import { GEOMETRY_PROTOCOL_VERSION, } from './protocol-types.js';
+/**
+ * Wraps placement updates in a versioned protocol message. Sequence numbers
+ * start at 1 and increment with each attempted delivery.
+ *
+ * Keep one publisher per `{ anchorId, generation }` (e.g. via `useMemo` or `useRef`).
+ * Batchers and sequence guards drop messages with older sequence numbers, so
+ * recreating a publisher for the same address causes its messages to be dropped.
+ * Increment `generation` when intentionally resetting the publisher.
+ */
+export function createPlacementMessagePublisher(address, send) {
+    let seq = 0;
+    return (placement) => {
+        const message = {
+            v: GEOMETRY_PROTOCOL_VERSION,
+            kind: 'placement',
+            anchorId: address.anchorId,
+            generation: address.generation,
+            seq: ++seq,
+            placement,
+        };
+        return send(message) !== false;
+    };
+}
+/**
+ * Wraps size updates in a versioned protocol message.
+ * Follows the same stability rule: keep one publisher per `{ anchorId, generation }`,
+ * and increment `generation` when resetting.
+ */
+export function createSizeMessagePublisher(address, send) {
+    let seq = 0;
+    return (size) => {
+        const message = {
+            v: GEOMETRY_PROTOCOL_VERSION,
+            kind: 'size',
+            anchorId: address.anchorId,
+            generation: address.generation,
+            seq: ++seq,
+            size,
+        };
+        return send(message) !== false;
+    };
+}
+/**
+ * Coalesces same-task messages without adding a rendering-frame delay. It owns
+ * no authorization policy: callers must associate addresses with trusted IPC
+ * senders before accepting a delivered batch.
+ */
+export function createGeometryBatcher(send, options = {}) {
+    const anchors = new Map();
+    const pendingAnchors = new Set();
+    let disposed = false;
+    let scheduled = false;
+    let flushing = false;
+    function report(error) {
+        try {
+            options.onError?.(error);
+        }
+        catch {
+            // Error reporting must not turn scheduled delivery into an unhandled error.
+        }
+    }
+    function flush() {
+        if (disposed || flushing)
+            return false;
+        const messages = [];
+        const snapshotStates = [];
+        for (const state of pendingAnchors) {
+            if (state.p !== undefined) {
+                messages.push(state.p);
+                snapshotStates.push(state);
+            }
+            if (state.s !== undefined) {
+                messages.push(state.s);
+                snapshotStates.push(state);
+            }
+        }
+        if (messages.length === 0)
+            return false;
+        const batch = {
+            v: GEOMETRY_PROTOCOL_VERSION,
+            kind: 'batch',
+            messages,
+        };
+        flushing = true;
+        try {
+            let accepted;
+            try {
+                accepted = send(batch) !== false;
+            }
+            catch (error) {
+                report(error);
+                return false;
+            }
+            if (!accepted)
+                return false;
+            for (let index = 0; index < messages.length; index++) {
+                const message = messages[index];
+                const state = anchors.get(message.anchorId);
+                // A reentrant clear or generation upgrade replaces the state object.
+                if (state === undefined || state !== snapshotStates[index])
+                    continue;
+                if (message.kind === 'placement') {
+                    if (state.pSeq === undefined || message.seq > state.pSeq) {
+                        state.pSeq = message.seq;
+                    }
+                    // Reentrant publishing may have replaced this message while send ran.
+                    if (state.p === message)
+                        state.p = undefined;
+                }
+                else {
+                    if (state.sSeq === undefined || message.seq > state.sSeq) {
+                        state.sSeq = message.seq;
+                    }
+                    if (state.s === message)
+                        state.s = undefined;
+                }
+                if (state.p === undefined && state.s === undefined) {
+                    pendingAnchors.delete(state);
+                }
+            }
+            return true;
+        }
+        finally {
+            flushing = false;
+        }
+    }
+    function schedule() {
+        if (scheduled || disposed)
+            return;
+        scheduled = true;
+        queueMicrotask(() => {
+            scheduled = false;
+            if (!disposed)
+                flush();
+        });
+    }
+    return {
+        publish(message) {
+            if (disposed)
+                return false;
+            let state = anchors.get(message.anchorId);
+            if (state !== undefined && message.generation < state.g)
+                return true;
+            if (state === undefined || message.generation > state.g) {
+                if (state !== undefined)
+                    pendingAnchors.delete(state);
+                state = {
+                    g: message.generation,
+                    p: undefined,
+                    s: undefined,
+                    pSeq: undefined,
+                    sSeq: undefined,
+                };
+                anchors.set(message.anchorId, state);
+            }
+            if (message.kind === 'placement') {
+                if ((state.p === undefined || message.seq > state.p.seq) &&
+                    (state.pSeq === undefined || message.seq > state.pSeq)) {
+                    state.p = message;
+                    pendingAnchors.add(state);
+                    schedule();
+                }
+            }
+            else if ((state.s === undefined || message.seq > state.s.seq) &&
+                (state.sSeq === undefined || message.seq > state.sSeq)) {
+                state.s = message;
+                pendingAnchors.add(state);
+                schedule();
+            }
+            return true;
+        },
+        flush,
+        clear(anchorId) {
+            if (anchorId === undefined) {
+                anchors.clear();
+                pendingAnchors.clear();
+                return;
+            }
+            const state = anchors.get(anchorId);
+            if (state !== undefined)
+                pendingAnchors.delete(state);
+            anchors.delete(anchorId);
+        },
+        dispose() {
+            disposed = true;
+            anchors.clear();
+            pendingAnchors.clear();
+        },
+    };
+}

package/dist/protocol-types.d.ts

@@ -0,0 +1,36 @@
+import type { AdvertisedSize, Placement } from './types.js';
+/**
+ * Leaf module for the wire-format shapes shared by `protocol.ts` (decode/guard)
+ * and `protocol-publisher.ts` (encode/batch). Keeping them here — rather than
+ * in either of those two — avoids a value import cycle: `protocol.ts`
+ * re-exports `protocol-publisher.ts`'s functions, and those functions need
+ * `GEOMETRY_PROTOCOL_VERSION`, so neither of those two files can be the
+ * source of it without the other importing back from it.
+ */
+/** Current wire format version for geometry messages. */
+export declare const GEOMETRY_PROTOCOL_VERSION: 1;
+/** Identifies one logical anchor instance within a transport session. */
+export interface GeometryAddress {
+    anchorId: string;
+    generation: number;
+}
+export interface PlacementMessage extends GeometryAddress {
+    v: typeof GEOMETRY_PROTOCOL_VERSION;
+    kind: 'placement';
+    seq: number;
+    placement: Placement;
+}
+export interface SizeMessage extends GeometryAddress {
+    v: typeof GEOMETRY_PROTOCOL_VERSION;
+    kind: 'size';
+    seq: number;
+    size: AdvertisedSize;
+}
+export type GeometryMessage = PlacementMessage | SizeMessage;
+export interface GeometryBatch {
+    v: typeof GEOMETRY_PROTOCOL_VERSION;
+    kind: 'batch';
+    messages: readonly GeometryMessage[];
+}
+export type GeometryWireValue = GeometryMessage | GeometryBatch;
+//# sourceMappingURL=protocol-types.d.ts.map

package/dist/protocol-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-types.d.ts","sourceRoot":"","sources":["../src/protocol-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3D;;;;;;;GAOG;AAEH,yDAAyD;AACzD,eAAO,MAAM,yBAAyB,EAAG,CAAU,CAAA;AAEnD,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,CAAC,EAAE,OAAO,yBAAyB,CAAA;IACnC,IAAI,EAAE,WAAW,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,SAAS,CAAA;CACrB;AAED,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,CAAC,EAAE,OAAO,yBAAyB,CAAA;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,cAAc,CAAA;CACrB;AAED,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,WAAW,CAAA;AAE5D,MAAM,WAAW,aAAa;IAC5B,CAAC,EAAE,OAAO,yBAAyB,CAAA;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;CACrC;AAED,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,aAAa,CAAA"}

package/dist/protocol-types.js

@@ -0,0 +1,10 @@
+/**
+ * Leaf module for the wire-format shapes shared by `protocol.ts` (decode/guard)
+ * and `protocol-publisher.ts` (encode/batch). Keeping them here — rather than
+ * in either of those two — avoids a value import cycle: `protocol.ts`
+ * re-exports `protocol-publisher.ts`'s functions, and those functions need
+ * `GEOMETRY_PROTOCOL_VERSION`, so neither of those two files can be the
+ * source of it without the other importing back from it.
+ */
+/** Current wire format version for geometry messages. */
+export const GEOMETRY_PROTOCOL_VERSION = 1;

package/dist/protocol.d.ts

@@ -0,0 +1,35 @@
+import { GEOMETRY_PROTOCOL_VERSION, type GeometryAddress, type GeometryBatch, type GeometryMessage, type GeometryWireValue, type PlacementMessage, type SizeMessage } from './protocol-types.js';
+export { GEOMETRY_PROTOCOL_VERSION };
+export type { GeometryAddress, GeometryBatch, GeometryMessage, GeometryWireValue, PlacementMessage, SizeMessage, };
+export type GeometryDecodeResult = {
+    ok: true;
+    value: GeometryWireValue;
+} | {
+    ok: false;
+    error: string;
+};
+export interface GeometryDecodeOptions {
+    /** Required caller-owned resource limit for a received batch. */
+    maxMessages: number;
+}
+/**
+ * Decodes untrusted transport data without throwing. `maxMessages` is required
+ * so each receiver, rather than this library, chooses its own batch limit.
+ */
+export declare function decodeGeometryWireValue(value: unknown, options: GeometryDecodeOptions): GeometryDecodeResult;
+export interface GeometrySequenceGuard {
+    /** Returns whether this message is newer than the last accepted equivalent. */
+    accept(message: GeometryMessage): boolean;
+    /** Forgets state for one anchor, or every anchor when omitted. */
+    clear(anchorId?: string): void;
+}
+/**
+ * Keeps one generation floor per anchor and a sequence high-water mark per
+ * message kind within that generation. Ordering metadata is not authority:
+ * receivers must still authorize anchor IDs from their trusted transport
+ * context before passing a message here.
+ */
+export declare function createGeometrySequenceGuard(): GeometrySequenceGuard;
+export { createGeometryBatcher, createPlacementMessagePublisher, createSizeMessagePublisher, } from './protocol-publisher.js';
+export type { GeometryBatcher, GeometryBatcherOptions, GeometryBatchSend, GeometrySend, } from './protocol-publisher.js';
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AACA,OAAO,EACL,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,yBAAyB,EAAE,CAAA;AACpC,YAAY,EACV,eAAe,EACf,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,GACZ,CAAA;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,GACtC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhC,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAA;CACpB;AAkED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,qBAAqB,GAC7B,oBAAoB,CA0BtB;AAED,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAA;IACzC,kEAAkE;IAClE,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AASD;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,qBAAqB,CA+BnE;AAED,OAAO,EACL,qBAAqB,EACrB,+BAA+B,EAC/B,0BAA0B,GAC3B,MAAM,yBAAyB,CAAA;AAChC,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,iBAAiB,EACjB,YAAY,GACb,MAAM,yBAAyB,CAAA"}

package/dist/protocol.js

@@ -0,0 +1,131 @@
+import { GEOMETRY_PROTOCOL_VERSION, } from './protocol-types.js';
+export { GEOMETRY_PROTOCOL_VERSION };
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isSafeInteger = (value) => typeof value === 'number' && Number.isSafeInteger(value);
+const isNonNegativeSafeInteger = (value) => isSafeInteger(value) && value >= 0;
+function error(message) {
+    return { ok: false, error: message };
+}
+function decodePlacement(value) {
+    if (!isRecord(value) || typeof value.visible !== 'boolean')
+        return undefined;
+    if (!value.visible)
+        return { visible: false };
+    if (!isRecord(value.bounds))
+        return undefined;
+    const { x, y, width, height } = value.bounds;
+    if (!isSafeInteger(x) ||
+        !isSafeInteger(y) ||
+        !isNonNegativeSafeInteger(width) ||
+        !isNonNegativeSafeInteger(height)) {
+        return undefined;
+    }
+    return { visible: true, bounds: { x, y, width, height } };
+}
+function decodeSize(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (value.axis !== 'block' && value.axis !== 'inline')
+        return undefined;
+    if (!isNonNegativeSafeInteger(value.extent))
+        return undefined;
+    return { axis: value.axis, extent: value.extent };
+}
+function decodeMessage(value) {
+    if (!isRecord(value) || value.v !== GEOMETRY_PROTOCOL_VERSION)
+        return undefined;
+    if (typeof value.anchorId !== 'string' || value.anchorId.length === 0)
+        return undefined;
+    if (!isNonNegativeSafeInteger(value.generation) ||
+        !isNonNegativeSafeInteger(value.seq)) {
+        return undefined;
+    }
+    const address = {
+        v: GEOMETRY_PROTOCOL_VERSION,
+        anchorId: value.anchorId,
+        generation: value.generation,
+        seq: value.seq,
+    };
+    if (value.kind === 'placement') {
+        const placement = decodePlacement(value.placement);
+        return placement === undefined
+            ? undefined
+            : { ...address, kind: 'placement', placement };
+    }
+    if (value.kind === 'size') {
+        const size = decodeSize(value.size);
+        return size === undefined ? undefined : { ...address, kind: 'size', size };
+    }
+    return undefined;
+}
+/**
+ * Decodes untrusted transport data without throwing. `maxMessages` is required
+ * so each receiver, rather than this library, chooses its own batch limit.
+ */
+export function decodeGeometryWireValue(value, options) {
+    try {
+        if (!isNonNegativeSafeInteger(options?.maxMessages) || options.maxMessages === 0) {
+            return error('maxMessages must be a positive safe integer');
+        }
+        const message = decodeMessage(value);
+        if (message !== undefined)
+            return { ok: true, value: message };
+        if (!isRecord(value) || value.v !== GEOMETRY_PROTOCOL_VERSION || value.kind !== 'batch') {
+            return error('invalid geometry message');
+        }
+        if (!Array.isArray(value.messages) || value.messages.length > options.maxMessages) {
+            return error('invalid geometry batch');
+        }
+        const messages = [];
+        for (const item of value.messages) {
+            const decoded = decodeMessage(item);
+            if (decoded === undefined)
+                return error('invalid geometry batch member');
+            messages.push(decoded);
+        }
+        return {
+            ok: true,
+            value: { v: GEOMETRY_PROTOCOL_VERSION, kind: 'batch', messages },
+        };
+    }
+    catch {
+        return error('invalid geometry message');
+    }
+}
+/**
+ * Keeps one generation floor per anchor and a sequence high-water mark per
+ * message kind within that generation. Ordering metadata is not authority:
+ * receivers must still authorize anchor IDs from their trusted transport
+ * context before passing a message here.
+ */
+export function createGeometrySequenceGuard() {
+    const latest = new Map();
+    return {
+        accept(message) {
+            const current = latest.get(message.anchorId);
+            if (current === undefined || message.generation > current[0]) {
+                latest.set(message.anchorId, [
+                    message.generation,
+                    message.kind === 'placement' ? message.seq : -1,
+                    message.kind === 'size' ? message.seq : -1,
+                ]);
+                return true;
+            }
+            if (message.generation < current[0])
+                return false;
+            const sequenceIndex = message.kind === 'placement' ? 1 : 2;
+            if (message.seq <= current[sequenceIndex])
+                return false;
+            current[sequenceIndex] = message.seq;
+            return true;
+        },
+        clear(anchorId) {
+            if (anchorId === undefined) {
+                latest.clear();
+                return;
+            }
+            latest.delete(anchorId);
+        },
+    };
+}
+export { createGeometryBatcher, createPlacementMessagePublisher, createSizeMessagePublisher, } from './protocol-publisher.js';

package/dist/react.d.ts

@@ -1,38 +1,26 @@
+import { type PlacementAnchorOptions } from './view-anchor.js';
 import type { Bounds, ViewAnchorOptions } from './types.js';
-/**
- * React adapter over the imperative `createViewAnchor` core.
- *
- * (React lint forces the `use` prefix on any hook returning a ref
- * callback; the library's identity is still the `ViewAnchor` core — this is
- * just the React binding.)
- */
 export interface UseViewAnchorOptions extends ViewAnchorOptions {
     /**
-     * Non-DOM dependencies that move the target's rect and must force a
-     * re-publish (layout signature, project path, a tab toggle's
-     * `display:none`, …). A `ResizeObserver` covers pure geometry; `deps`
-     * covers state it cannot see. Keep the array length stable across
-     * renders (React effect-deps rule).
+     * Values that re-apply the anchor when changed. Keep this array's length
+     * stable across renders.
      */
     deps?: ReadonlyArray<unknown>;
 }
-export type ViewAnchorRef = (el: HTMLElement | null) => void;
-/**
- * Bind a native view's bounds to whichever DOM element the returned ref
- * callback is attached to. On attach → `createViewAnchor(el, opts)`; on
- * detach (`null`) → publish ZERO then `dispose()`; on `opts`/`deps` change →
- * `update`; on unmount → publish ZERO then `dispose`.
- *
- * Why ZERO on disappearance: the anchor's follower is a *main-process*
- * `WebContentsView`, not a DOM node. When the anchored element vanishes, core
- * `dispose()` only stops observing — it deliberately never publishes again
- * (its Contract 6/7). But the host only collapses the native view when it
- * receives `{0,0,0,0}` (isHidden). In production the debug cell is *unmounted*
- * (not `display:none`) when hidden, so the ref goes to `null` and the native
- * view would otherwise stay frozen at its last bounds, floating on
- * top and occluding content. So the adapter (not core) must emit one ZERO via
- * the already-tested `update({ present:false })` path before disposing.
- */
-export declare function useViewAnchor(opts: UseViewAnchorOptions): ViewAnchorRef;
+/** Compatible with React 18's null callback and React 19's ref cleanup. */
+export type ViewAnchorRef = (el: HTMLElement | null) => void | (() => void);
+export interface UsePlacementAnchorOptions extends PlacementAnchorOptions {
+    /**
+     * Values that re-apply the anchor when changed. Keep this array's length
+     * stable across renders.
+     */
+    deps?: ReadonlyArray<unknown>;
+}
+/** Callback ref for the explicit-visibility Placement API. */
+export type PlacementAnchorRef = ViewAnchorRef;
+/** Bind zero-bounds visibility to a DOM element callback ref. */
+export declare function useViewAnchor(options: UseViewAnchorOptions): ViewAnchorRef;
+/** Bind the explicit Placement API to a DOM element callback ref. */
+export declare function usePlacementAnchor(options: UsePlacementAnchorOptions): PlacementAnchorRef;
 export type { Bounds };
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAoB,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE7E;;;;;;GAMG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAC9B;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAA;AAE5D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,aAAa,CAgIvE;AAED,YAAY,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EACV,MAAM,EAEN,iBAAiB,EAClB,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAC9B;AAED,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAA;AAE3E,MAAM,WAAW,yBAA0B,SAAQ,sBAAsB;IACvE;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAC9B;AAED,8DAA8D;AAC9D,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAA;AAoI9C,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAM1E;AAyBD,qEAAqE;AACrE,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,kBAAkB,CAapB;AAED,YAAY,EAAE,MAAM,EAAE,CAAA"}