view-anchor 0.1.2 → 0.2.0

package/src/react.ts

@@ -1,171 +1,216 @@
 import { useCallback, useEffect, useRef } from 'react'
-import { createViewAnchor } from './view-anchor.js'
-import type { Bounds, ViewAnchorHandle, 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.)
- */
+import {
+  createPlacementAnchor,
+  createViewAnchor,
+  type PlacementAnchorHandle,
+  type PlacementAnchorOptions,
+} from './view-anchor.js'
+import type {
+  Bounds,
+  ViewAnchorHandle,
+  ViewAnchorOptions,
+} from './types.js'
+
 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>
+}
+
+/** 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>
 }
 
-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 function useViewAnchor(opts: UseViewAnchorOptions): ViewAnchorRef {
-  const handleRef = useRef<ViewAnchorHandle | null>(null)
-  const elRef = useRef<HTMLElement | null>(null)
-  // Latest opts, read by the stable ref callback when it creates the anchor.
-  // Synced render-synchronously (NOT in an effect): the ref callback reads
-  // `optsRef.current` during *commit* (when the element attaches), which runs
-  // before passive effects. An effect-synced ref would be one render stale at
-  // that point, so a hidden→shown remount (`present` flips false→true together
-  // with the element re-mounting, exactly what the debug cell does) would
-  // create the anchor with the old `present:false` and emit a spurious ZERO
-  // before the real rect. A render write keeps it current at commit, and is
-  // idempotent under StrictMode's double render.
-  const optsRef = useRef(opts)
-  // eslint-disable-next-line react-hooks/refs -- see above: must be current at commit, before effects run
-  optsRef.current = opts
-
-  // Baseline for the re-apply effect's change detection. Declared here (before
-  // the ref callback) so the callback can re-seed it on (re)create.
-  const appliedRef = useRef<ReadonlyArray<unknown>>([
-    opts.present,
-    opts.publish,
-    ...(opts.deps ?? []),
-  ])
-
-  // Collapse the native view (publish ZERO) and tear the anchor down. Reuse
-  // the existing, tested `update({ present:false })` path: it synchronously
-  // publishes `{0,0,0,0}` and stops observing (core Contract 5), then
-  // `dispose()` makes the anchor inert. Idempotent via the `handleRef.current`
-  // null-check so the two callers below can never double-emit ZERO.
-  const collapseAndDispose = useRef((): void => {
+/** Callback ref for the explicit-visibility Placement API. */
+export type PlacementAnchorRef = ViewAnchorRef
+
+type AnchorHandle = { dispose(): void }
+
+interface LifecycleAdapter<Options, Handle extends AnchorHandle> {
+  create(target: HTMLElement, options: Options): Handle
+  update(handle: Handle, options: Options): void
+  collapse(handle: Handle, options: Options): void
+  isCollapsed(options: Options): boolean
+}
+
+// Callback refs own the imperative anchor because React invokes them during commit.
+// React 19 may call the cleanup returned from a ref and immediately reattach the
+// same element in development mode. Collapse is deferred by one microtask so that
+// immediate reattachment cancels the collapse.
+function useAnchorRef<Options, Handle extends AnchorHandle>(
+  options: Options,
+  applied: ReadonlyArray<unknown>,
+  adapter: LifecycleAdapter<Options, Handle>,
+): ViewAnchorRef {
+  const handleRef = useRef<Handle | null>(null)
+  const elementRef = useRef<HTMLElement | null>(null)
+  const optionsRef = useRef(options)
+  // eslint-disable-next-line react-hooks/refs
+  optionsRef.current = options
+  const adapterRef = useRef(adapter)
+  // eslint-disable-next-line react-hooks/refs
+  adapterRef.current = adapter
+  const appliedRef = useRef(applied)
+  const currentAppliedRef = useRef(applied)
+  // eslint-disable-next-line react-hooks/refs
+  currentAppliedRef.current = applied
+  // Options handed to the adapter on the last create/update call.
+  // Tracks applied state across renders where the deps array reference changes.
+  const lastAppliedOptionsRef = useRef(options)
+  const detachTokenRef = useRef(0)
+
+  const cancelPendingDetach = (): void => {
+    detachTokenRef.current++
+  }
+
+  const collapseAndDispose = (): void => {
     const handle = handleRef.current
     if (!handle) return
-    handle.update({ present: false, publish: optsRef.current.publish })
-    handle.dispose()
-    handleRef.current = null
-  })
-
-  const ref = useCallback<ViewAnchorRef>((el) => {
-    if (el === elRef.current) return
-    elRef.current = el
+    const adapter = adapterRef.current
+    const alreadyCollapsed = adapter.isCollapsed(lastAppliedOptionsRef.current)
+    try {
+      if (!alreadyCollapsed) adapter.collapse(handle, optionsRef.current)
+    } finally {
+      handleRef.current = null
+      handle.dispose()
+    }
+  }
+
+  const deferDetach = (element: HTMLElement): void => {
+    const token = ++detachTokenRef.current
+    queueMicrotask(() => {
+      if (detachTokenRef.current !== token || elementRef.current !== element) return
+      elementRef.current = null
+      collapseAndDispose()
+    })
+  }
+
+  const ref = useCallback<ViewAnchorRef>((element) => {
+    if (element === elementRef.current) {
+      cancelPendingDetach()
+      return element ? () => deferDetach(element) : undefined
+    }
+
+    cancelPendingDetach()
+    const previous = elementRef.current
     if (handleRef.current) {
-      if (el) {
-        // Swapping to *another* live element: dispose the old anchor without a
-        // ZERO. The new element publishes its real rect immediately below, so
-        // a transient ZERO between the two would only cause a needless
-        // detach/re-attach flicker of the native view.
+      if (element) {
         handleRef.current.dispose()
         handleRef.current = null
-      } else {
-        // Element detached (ref → null): the anchor point is gone, so collapse
-        // the native view (one ZERO) before disposing.
-        collapseAndDispose.current()
+      } else if (previous) {
+        deferDetach(previous)
+        return undefined
       }
     }
-    if (el) {
-      handleRef.current = createViewAnchor(el, {
-        present: optsRef.current.present,
-        publish: optsRef.current.publish,
-      })
-      // The anchor was just created at the current (present, publish, deps), so
-      // seed the re-apply baseline to match. Otherwise the post-commit re-apply
-      // effect would see this fresh state as a change and publish a second time
-      // — on a remount with a changed `present` that is a double-emit.
-      appliedRef.current = [
-        optsRef.current.present,
-        optsRef.current.publish,
-        ...(optsRef.current.deps ?? []),
-      ]
+
+    if (element) {
+      elementRef.current = element
+      handleRef.current = adapterRef.current.create(element, optionsRef.current)
+      appliedRef.current = currentAppliedRef.current
+      lastAppliedOptionsRef.current = optionsRef.current
+      return () => deferDetach(element)
     }
+    return undefined
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- helpers only read stable refs
   }, [])
 
-  // Re-apply on opts/deps change. We must `update` whenever the
-  // (present, publish, …deps) tuple actually changes, but NOT on the mount run
-  // (the ref callback already created the anchor and published once) and NOT on
-  // a StrictMode replay (dev double-fires this effect's setup with the *same*
-  // tuple — a blind `update` then re-publishes the mount rect a second time).
-  // So instead of guessing "is this the first run?", compare against the
-  // last-applied tuple and apply only on a genuine change. The tuple is seeded
-  // with the mount opts, so the mount run and its StrictMode replay both see
-  // "unchanged" and skip — idempotent by construction. `deps` keeps a stable
-  // length across renders (documented above), so positional compare is sound.
   useEffect(() => {
-    const next: ReadonlyArray<unknown> = [
-      opts.present,
-      opts.publish,
-      ...(opts.deps ?? []),
-    ]
-    const prev = appliedRef.current
+    const previous = appliedRef.current
     const changed =
-      next.length !== prev.length || next.some((v, i) => !Object.is(v, prev[i]))
+      applied.length !== previous.length ||
+      applied.some((value, index) => !Object.is(value, previous[index]))
     if (!changed) return
-    appliedRef.current = next
-    handleRef.current?.update({ present: opts.present, publish: opts.publish })
+    appliedRef.current = applied
+    const handle = handleRef.current
+    if (handle) {
+      adapterRef.current.update(handle, optionsRef.current)
+      lastAppliedOptionsRef.current = optionsRef.current
+    }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [opts.present, opts.publish, ...(opts.deps ?? [])])
-
-  // Collapse the native view + dispose on teardown.
-  //
-  // StrictMode-safe lifecycle: this effect's setup/cleanup is double-fired in
-  // dev (setup → cleanup → setup). The anchor itself is created/owned by the
-  // ref callback, which in React 18 fires exactly once on mount and once with
-  // `null` on a real detach — it is NOT replayed by StrictMode. So this effect
-  // must not destroy the ref-owned anchor on a *throwaway* unmount, or the
-  // re-setup would have nothing to restore.
-  //
-  // Discriminator: on a real teardown React detaches the element first
-  // (`ref(null)` → `elRef.current === null`, and that path already emitted the
-  // single ZERO + disposed); on a StrictMode throwaway unmount the element is
-  // still attached (`elRef.current !== null`, ref never fired `null`). So we
-  // only collapse here when the element is genuinely gone, and otherwise leave
-  // the live anchor intact for the immediate re-setup.
-  //
-  // The setup re-establishes the anchor if a prior cleanup ever tore it down
-  // while the element is still attached, keeping setup/cleanup symmetric.
+  }, applied)
+
   useEffect(() => {
-    const collapse = collapseAndDispose.current
-    if (elRef.current && !handleRef.current) {
-      handleRef.current = createViewAnchor(elRef.current, {
-        present: optsRef.current.present,
-        publish: optsRef.current.publish,
-      })
-    }
+    cancelPendingDetach()
     return () => {
-      if (elRef.current === null) collapse()
+      const element = elementRef.current
+      if (element) deferDetach(element)
     }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- helpers only read stable refs
   }, [])
 
   return ref
 }
 
+const viewAdapter: LifecycleAdapter<ViewAnchorOptions, ViewAnchorHandle> = {
+  create: createViewAnchor,
+  update(handle, options) {
+    handle.update(options)
+  },
+  collapse(handle, options) {
+    handle.update({ present: false, publish: options.publish })
+  },
+  isCollapsed(options) {
+    return !options.present
+  },
+}
+
+/** Bind zero-bounds visibility to a DOM element callback ref. */
+export function useViewAnchor(options: UseViewAnchorOptions): ViewAnchorRef {
+  return useAnchorRef(
+    options,
+    [options.present, options.publish, ...(options.deps ?? [])],
+    viewAdapter,
+  )
+}
+
+const placementAdapter: LifecycleAdapter<
+  PlacementAnchorOptions,
+  PlacementAnchorHandle
+> = {
+  create: createPlacementAnchor,
+  update(handle, options) {
+    // In React, an omitted option represents "off" for that render,
+    // rather than keeping the previous value.
+    handle.update({
+      ...options,
+      guardDisplayNone: options.guardDisplayNone ?? false,
+      followScroll: options.followScroll ?? false,
+      followGeometry: options.followGeometry ?? false,
+    })
+  },
+  collapse(handle, options) {
+    handle.update({ ...options, visible: false })
+  },
+  isCollapsed(options) {
+    return !options.visible
+  },
+}
+
+/** Bind the explicit Placement API to a DOM element callback ref. */
+export function usePlacementAnchor(
+  options: UsePlacementAnchorOptions,
+): PlacementAnchorRef {
+  return useAnchorRef(
+    options,
+    [
+      options.visible,
+      options.publish,
+      options.guardDisplayNone,
+      options.followScroll,
+      options.followGeometry,
+      ...(options.deps ?? []),
+    ],
+    placementAdapter,
+  )
+}
+
 export type { Bounds }

package/src/size-advertiser.ts

@@ -1,51 +1,46 @@
 import type {
   AdvertisedSize,
+  Publisher,
   SizeAdvertiserOptions,
   SizeAdvertiserHandle,
 } from './types.js'
 import { createMeasureLoop } from './measure-loop.js'
 
 /**
- * Reverse of `createViewAnchor`: runs in a downstream WebContentsView's own
- * renderer, measures the content's own size on ONE owned axis (from the
- * `ResizeObserver` border-box — no `getBoundingClientRect`, no forced reflow),
- * and advertises it via the injected `publish`. Shares the forward primitive's
- * measure/coalesce/dedupe/dispose engine (`createMeasureLoop`).
+ * Report content size for a single axis back to the host.
  *
- * The extent is `Math.round`ed and clamped to `>= 0`; non-finite measurements
- * drop the frame.
+ * Runs in a downstream document, reads the content size from
+ * `ResizeObserverEntry.borderBoxSize` without triggering reflow, and
+ * publishes updates through an animation frame loop (`createMeasureLoop`).
  *
- * FOOTGUN — `target` must be shrink-to-fit on the owned axis: its owned-axis
- * size must NOT be driven by the host-applied view size, or the cross-process
- * loop (advertise → host resizes view → remeasure) never converges (it
- * oscillates or stays "stable but wrong"). Measuring `<body>`/`<html>` is the
- * classic mistake — their size *is* the view size. See
- * `docs/bidirectional-design.md`'s single-axis-ownership and trust-boundary
- * sections.
+ * Measurements are rounded to integer pixels and clamped to >= 0.
+ *
+ * Note: `target` should be a shrink-to-fit wrapper on the owned axis.
+ * If its size is driven by the host view itself (such as `<body>` or `<html>`),
+ * updates will not shrink back to content size.
  */
 export function createSizeAdvertiser(
   target: HTMLElement,
   opts: SizeAdvertiserOptions,
 ): SizeAdvertiserHandle {
-  const axis = opts.axis // immutable for the advertiser's life
+  const axis = opts.axis
   let publish = opts.publish
   let observer: ResizeObserver | null = null
   let disposed = false
-  // Latest border-box, stashed by the RO callback and read by `produce` in the
-  // RAF body (keep the entry out of the shared, DOM-agnostic loop).
+  // Latest border-box recorded by the ResizeObserver callback.
   let latest: ResizeObserverSize | null = null
 
-  const produce = (): AdvertisedSize | null => {
+  const produce = (): number | null => {
     if (!latest) return null
     const raw = axis === 'block' ? latest.blockSize : latest.inlineSize
     if (!Number.isFinite(raw)) return null
-    return { axis, extent: Math.max(0, Math.round(raw)) }
+    return Math.max(0, Math.round(raw))
   }
 
-  const loop = createMeasureLoop<AdvertisedSize>({
+  const loop = createMeasureLoop<number>({
     produce,
-    same: (a, b) => a.extent === b.extent, // axis is constant
-    sink: (size) => publish(size),
+    same: (a, b) => a === b,
+    sink: (extent) => publish({ axis, extent }),
   })
 
   const onResize: ResizeObserverCallback = (entries) => {
@@ -56,14 +51,13 @@ export function createSizeAdvertiser(
     loop.schedule()
   }
 
-  // One cheap, once-per-advertiser guard for the textbook feedback-loop footgun.
+  // Warn if measuring body or documentElement, whose size matches the view.
   const doc = target.ownerDocument
   if (target === doc.body || target === doc.documentElement) {
     console.warn(
       `[view-anchor] size-advertiser: <${target === doc.body ? 'body' : 'html'}>'s ` +
-        `${axis} size is the host-given view size, not the content size — the ` +
-        `advertiser will never shrink to content. Measure a shrink-to-fit wrapper. ` +
-        `See bidirectional-design.md's single-axis-ownership section.`,
+        `${axis} size is the view size, not content size. The advertiser will ` +
+        `never shrink to content; measure a shrink-to-fit wrapper instead.`,
     )
   }
 
@@ -72,14 +66,13 @@ export function createSizeAdvertiser(
   observer.observe(target)
 
   return {
-    update(nextPublish: (size: AdvertisedSize) => void): void {
+    update(nextPublish: Publisher<AdvertisedSize>): void {
       if (disposed) return
       publish = nextPublish
-      // Re-advertise the current size to the new sink immediately (mirrors the
-      // forward anchor's re-publish on update) so the new channel is not left
-      // sizeless until the next ResizeObserver tick.
+      // Re-publish the current size to the new sink immediately so it is not
+      // empty until the next ResizeObserver tick.
       const cur = produce()
-      if (cur) loop.emitNow(cur)
+      if (cur !== null) loop.emitNow(cur)
     },
     dispose(): void {
       if (disposed) return

package/src/types.ts

@@ -1,23 +1,8 @@
 /**
- * view-anchor — sync a main-process native view's bounds to a DOM element.
- *
- * Self-contained, engine-agnostic primitive. It knows nothing about
- * Electron (the `publish` callback owns the IPC → `setBounds`), nothing
- * about React (the core is imperative; see `react.ts` for the adapter),
- * and nothing about the host layout engine (the `target` element may come
- * from our own `compile`/`FrameTree`, or a dockview panel's
- * `content.element`; the mechanism is identical).
- *
- * It is the modern, alive replacement for the archived
- * `react-electron-browser-view`: the cross-process bridge that DOM layout
- * libraries (dockview included) deliberately do not provide. dockview's
- * internal `OverlayRenderContainer` does the same getBoundingClientRect →
- * RAF → reposition dance, but its follower is a DOM node; ours is a native
- * `WebContentsView` positioned via the injected `publish`.
+ * Core geometry and transport types for view-anchor.
  */
 
-/** A screen-space rectangle, in CSS pixels. Structurally compatible with
- *  the host's `ViewBounds` so a publisher typed against either works. */
+/** A screen-space rectangle in CSS pixels. */
 export interface Bounds {
   x: number
   y: number
@@ -25,16 +10,20 @@ export interface Bounds {
   height: number
 }
 
+/** Returning false declines a value; true and void accept it. */
+export type PublishResult = void | boolean
+
 /**
- * Explicit visibility + geometry for a native view, replacing the legacy
- * magic-`{0,0,0,0}` "hidden" convention (`present:false → ZERO bounds`).
+ * Synchronous publish callback. A batching transport returns true once
+ * the value is queued; subsequent delivery is handled by the transport.
+ */
+export type Publisher<T> = (value: T) => PublishResult
+
+/**
+ * Explicit visibility and bounds for an anchored view.
  *
- * Visibility is a DISCRIMINANT, never inferred from geometry. The whole
- * reason this type exists: a genuinely zero-SIZED but on-screen view
- * (`{ visible:true, bounds:{...,width:0,height:0} }`) is now distinct from a
- * detached/hidden one (`{ visible:false }`, which carries no `bounds` at
- * all). Under the old ZERO convention both collapsed to the same value and
- * were indistinguishable.
+ * Distinguishes an intentionally visible but zero-sized element ({ visible: true, bounds: 0x0 })
+ * from a hidden or detached element ({ visible: false }).
  */
 export type Placement =
   | { visible: true; bounds: Bounds }
@@ -42,82 +31,48 @@ export type Placement =
 
 export interface ViewAnchorOptions {
   /**
-   * Whether the native view should be attached. When `false`, the anchor
-   * publishes zero bounds (`{0,0,0,0}`) — the host treats `width === 0 ||
-   * height === 0` as "detach the child view but keep its WebContents
-   * alive" (detach-but-keep-alive). No DOM measurement is needed in this
-   * state.
+   * Whether the native view should be attached. When false, publishes
+   * zero bounds ({ x: 0, y: 0, width: 0, height: 0 }) so the host can detach
+   * the view while keeping its instance alive.
    */
   present: boolean
-  /** Receives the live rect, or `{0,0,0,0}` when detached. Owns IPC. */
-  publish: (bounds: Bounds) => void
+  /** Receives the live rect, or zero bounds when detached. */
+  publish: Publisher<Bounds>
 }
 
 export interface ViewAnchorHandle {
-  /**
-   * Apply new options. Re-publishes immediately to reflect the new state
-   * (present=true → measure + observe; present=false → zero bounds).
-   */
+  /** Apply new options and re-publish immediately. */
   update(opts: ViewAnchorOptions): void
-  /** Stop observing and remove listeners. After dispose the anchor never
-   *  publishes again (every emit reads `disposed` synchronously, so there is
-   *  no queued frame that could fire late). */
+  /** Stop observing and clean up listeners. After disposal no further values are published. */
   dispose(): void
 }
 
-// ── Reverse direction: size advertiser ───────────────────────────────
+// --- Reverse direction: size advertiser ---
 //
-// The mirror of the forward anchor. Runs in a DOWNSTREAM WebContentsView's own
-// renderer: it measures the content's own size and advertises it to the host,
-// which sizes the placeholder accordingly (and the forward anchor then keeps the
-// view positioned). One advertiser owns exactly ONE axis — the other axis is a
-// host-driven, read-only input — so the cross-process loop stays a one-way DAG.
+// Runs in a downstream document to report content size back to the host,
+// allowing the host's DOM placeholder to match the content.
 
-/** Which axis this advertiser owns. `block` = height, `inline` = width
- *  (logical-property naming, axis-agnostic to writing mode). */
+/** Which axis this advertiser reports: 'block' (height) or 'inline' (width). */
 export type AdvertisedAxis = 'block' | 'inline'
 
-/**
- * One frame of advertised size. A pure scalar plus the owning axis — there is
- * deliberately no field for the *other* axis, so "advertise two axes" is not
- * expressible (single-axis ownership is enforced in the type, not at runtime).
- */
+/** One frame of advertised size on the owned axis. */
 export interface AdvertisedSize {
-  /** Mirrors the factory's `axis`; constant across frames. Lets the host
-   *  whitelist-check the axis it is willing to accept. */
+  /** The axis this advertiser reports ('block' or 'inline'). */
   readonly axis: AdvertisedAxis
-  /** The owned axis's content extent, in CSS px — already rounded and clamped
-   *  to `>= 0`. */
+  /** The content extent in CSS pixels, rounded and non-negative. */
   readonly extent: number
 }
 
 export interface SizeAdvertiserOptions {
-  /** The single axis this advertiser owns. Fixed for the advertiser's life. */
+  /** The single axis this advertiser owns. Fixed for the advertiser's lifetime. */
   axis: AdvertisedAxis
-  /** Receives each advertised size. Owns the IPC/postMessage → host. Mirrors
-   *  the forward `publish` (same role: the injected, transport-owning sink). */
-  publish: (size: AdvertisedSize) => void
+  /** Receives each advertised size. */
+  publish: Publisher<AdvertisedSize>
 }
 
 export interface SizeAdvertiserHandle {
-  /**
-   * Swap the `publish` sink (e.g. a new IPC channel) and immediately
-   * re-advertise the current size to it (mirrors the forward anchor's
-   * re-publish on update), so the new channel is not left sizeless until the
-   * next `ResizeObserver` tick.
-   *
-   * Takes only the new sink — `axis` is immutable by construction, so it is
-   * deliberately not expressible here (you cannot attempt to change it). To
-   * advertise a different axis, dispose and create a new advertiser.
-   */
-  update(publish: (size: AdvertisedSize) => void): void
-  /**
-   * Stop observing, cancel any pending RAF. After dispose nothing is
-   * advertised again. (There is no ZERO/terminal value — collapsing is the
-   * host's policy, unlike the forward anchor's `present:false`.)
-   *
-   * The first advertised value is asynchronous: it awaits the observer's first
-   * frame, and a `display:none` target advertises nothing until shown.
-   */
+  /** Swap the publish callback and re-advertise the current size immediately. */
+  update(publish: Publisher<AdvertisedSize>): void
+  /** Stop observing and cancel any pending animation frame. */
   dispose(): void
 }