view-anchor 0.1.2 → 0.2.1

package/src/protocol-publisher.ts

@@ -0,0 +1,254 @@
+import type { AdvertisedSize, Placement, Publisher } from './types.js'
+import {
+  GEOMETRY_PROTOCOL_VERSION,
+  type GeometryAddress,
+  type GeometryBatch,
+  type GeometryMessage,
+  type PlacementMessage,
+  type SizeMessage,
+} 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 function createPlacementMessagePublisher(
+  address: GeometryAddress,
+  send: GeometrySend,
+): (placement: Placement) => boolean {
+  let seq = 0
+
+  return (placement) => {
+    const message: PlacementMessage = {
+      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: GeometryAddress,
+  send: GeometrySend,
+): (size: AdvertisedSize) => boolean {
+  let seq = 0
+
+  return (size) => {
+    const message: SizeMessage = {
+      v: GEOMETRY_PROTOCOL_VERSION,
+      kind: 'size',
+      anchorId: address.anchorId,
+      generation: address.generation,
+      seq: ++seq,
+      size,
+    }
+    return send(message) !== false
+  }
+}
+
+// Terminal-state stand-in for `send` so a retained, disposed batcher does not
+// keep the caller's transport closure (and whatever it captured) alive.
+const NOOP_SEND: GeometryBatchSend = () => 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: GeometryBatchSend,
+  options: GeometryBatcherOptions = {},
+): GeometryBatcher {
+  /** State is indexed by anchor so upgrades and clear(anchor) are O(1). */
+  interface AnchorState {
+    /** Generation, pending placement/size, and their accepted sequence marks. */
+    g: number
+    p?: PlacementMessage
+    s?: SizeMessage
+    pSeq?: number
+    sSeq?: number
+  }
+
+  const anchors = new Map<string, AnchorState>()
+  const pendingAnchors = new Set<AnchorState>()
+  let disposed = false
+  let scheduled = false
+  let flushing = false
+
+  // `activeOptions` lets a caller keep reporting to the options object that
+  // was live when its flush() call started, even if a reentrant dispose()
+  // during send() has since cleared the instance-level `options` reference.
+  function report(activeOptions: GeometryBatcherOptions, error: unknown): void {
+    try {
+      activeOptions.onError?.(error)
+    } catch {
+      // Error reporting must not turn scheduled delivery into an unhandled error.
+    }
+  }
+
+  function flush(): boolean {
+    if (disposed || flushing) return false
+    const messages: GeometryMessage[] = []
+    const snapshotStates: AnchorState[] = []
+    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: GeometryBatch = {
+      v: GEOMETRY_PROTOCOL_VERSION,
+      kind: 'batch',
+      messages,
+    }
+
+    // Captured before send() runs so a reentrant dispose() (which clears the
+    // instance-level `options`) cannot blind this call's own error report.
+    const activeOptions = options
+
+    flushing = true
+    try {
+      let accepted: boolean
+      try {
+        accepted = send(batch) !== false
+      } catch (error) {
+        report(activeOptions, 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(): void {
+    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()
+      // Callers may still mutate the original options object after
+      // construction (e.g. reassigning onError); flush() captures its own
+      // reference before send() runs, so an in-flight error report keeps
+      // reading that object even though dispose() drops the instance's
+      // long-lived reference here.
+      options = {}
+      send = NOOP_SEND
+    },
+  }
+}

package/src/protocol-types.ts

@@ -0,0 +1,43 @@
+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 const GEOMETRY_PROTOCOL_VERSION = 1 as const
+
+/** 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

package/src/protocol.ts

@@ -0,0 +1,181 @@
+import type { AdvertisedSize, Placement } from './types.js'
+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
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const isSafeInteger = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isSafeInteger(value)
+
+const isNonNegativeSafeInteger = (value: unknown): value is number =>
+  isSafeInteger(value) && value >= 0
+
+function error(message: string): GeometryDecodeResult {
+  return { ok: false, error: message }
+}
+
+function decodePlacement(value: unknown): Placement | undefined {
+  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: unknown): AdvertisedSize | undefined {
+  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: unknown): GeometryMessage | undefined {
+  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: unknown,
+  options: GeometryDecodeOptions,
+): GeometryDecodeResult {
+  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: GeometryMessage[] = []
+    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')
+  }
+}
+
+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
+}
+
+// -1 means that this generation has not seen the corresponding message kind.
+type GeometrySequenceState = [generation: number, placementSeq: number, sizeSeq: number]
+
+/**
+ * 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(): GeometrySequenceGuard {
+  const latest = new Map<string, GeometrySequenceState>()
+
+  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'
+export type {
+  GeometryBatcher,
+  GeometryBatcherOptions,
+  GeometryBatchSend,
+  GeometrySend,
+} from './protocol-publisher.js'