@atolljs/islands 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/islands",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Atoll islands — MonoWorker/PolyWorker hosts rendering framework islands (React/Vue/Svelte/Solid/Angular) over a proxy-DOM op protocol",
   "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",
@@ -19,7 +19,7 @@
     "htmlparser2": "^12.0.0"
   },
   "peerDependencies": {
-    "@atolljs/core": "0.1.10"
+    "@atolljs/core": "0.1.12"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -49,6 +49,7 @@ export type {
   EventPayload,
   EventRef,
   IslandWorkerMethods,
+  MeasuredRect,
   Op,
   WireProps,
 } from './ops';

package/src/island.ts

@@ -36,6 +36,7 @@ import {
   isEventRef,
   type EventPayload,
   type IslandWorkerMethods,
+  type MeasuredRect,
   type Op,
   type WireProps,
 } from './ops';
@@ -82,20 +83,40 @@ export interface ConnectIslandWorkerConfig extends IslandWorkerOptions {
    * polling and the page needs no special headers.
    */
   doorbell?: boolean;
+  /**
+   * Default false — when true, the last island to destroy on this client
+   * leaves the worker ALIVE but idle: the instance still unmounts (dispose
+   * hooks run, timers clear, ops stop, driver state releases) but the
+   * thread, its module graph, and any worker-side caches stay resident, so
+   * the next `mount` on this client is a warm start. Nothing runs while
+   * idle — the instance is gone; only the process survives.
+   */
+  keepAlive?: boolean;
 }
 
+/* Clients opted out of idle-termination by `keepAlive` — a WeakSet so the
+ * flag never pins a client that would otherwise collect. */
+const keepAliveClients = new WeakSet<object>();
+
+/** True when this client stays resident after its last island destroys. */
+export const isKeepAliveClient = (client: object): boolean => keepAliveClients.has(client);
+
 /** One island client: one dedicated worker, one doorbell buffer. */
 export const connectIslandWorker = <W extends IslandWorkerDefinition = IslandWorkerDefinition>({
   worker,
   doorbell,
+  keepAlive,
   ...options
-}: ConnectIslandWorkerConfig): WorkerClient<W, DoorbellSpec> =>
-  connectWorker<W, DoorbellSpec>({
+}: ConnectIslandWorkerConfig): WorkerClient<W, DoorbellSpec> => {
+  const client = connectWorker<W, DoorbellSpec>({
     ...options,
     sharedMemory: doorbell === false ? undefined : makeDoorbell(),
     worker,
     workers: 1,
   });
+  if (keepAlive) keepAliveClients.add(client);
+  return client;
+};
 
 interface MountIslandBaseOptions {
   /**
@@ -512,6 +533,69 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
   /** instance id → slot name, for elements carrying `data-atoll-slot`. */
   const slotNodes = new Map<number, string>();
 
+  /* ── Per-element measure channel (measure ops → setRects pushes) ──────────
+   *
+   * Declared before applyOp's first run: a mount batch may already carry
+   * `measure` ops (an app calling doc.observeSize / reading geometry during
+   * mount), and every reference below is initialized by the time the first
+   * op applies. The pushes themselves defer to a macrotask — islandCall is
+   * initialized by then regardless of which op batch requested them. The
+   * ~100ms throttle matches the container-size channel (leading + trailing). */
+  /** ids the worker asked to be measured — RO targets + unmeasure/remove hygiene. */
+  const measuredIds = new Set<number>();
+  /** instance id → rect awaiting the next setRects flush. */
+  const pendingRects = new Map<number, MeasuredRect>();
+  /** Shared observer for every measured element — created on first use so
+   *  islands that never measure pay nothing (and environments without
+   *  ResizeObserver just get the one-time initial rect per element). */
+  let rectObserver: ResizeObserver | null = null;
+  let rectTimer: number | null = null;
+  let rectLastPush = -Infinity;
+
+  function flushRects(): void {
+    rectTimer = null;
+    if (pendingRects.size === 0 || destroyed) return;
+    rectLastPush = Date.now();
+    const batch = [...pendingRects.values()];
+    pendingRects.clear();
+    void islandCall('setRects', client.setRects(instance, batch)).then((ops) =>
+      applyOps(ops, 'setRects'),
+    );
+  }
+
+  function scheduleRectFlush(): void {
+    if (rectTimer !== null) return;
+    const elapsed = Date.now() - rectLastPush;
+    rectTimer = window.setTimeout(flushRects, elapsed >= 100 ? 0 : 100 - elapsed);
+  }
+
+  const queueRect = (id: number, node: Element): void => {
+    // getBoundingClientRect (not the RO entry's contentRect) so x/y are
+    // viewport-relative — the coordinates getBoundingClientRect reads
+    // worker-side must match.
+    const r = node.getBoundingClientRect();
+    pendingRects.set(id, { id, x: r.x, y: r.y, w: r.width, h: r.height });
+    scheduleRectFlush();
+  };
+
+  const ensureRectObserver = (): void => {
+    if (rectObserver === null && typeof ResizeObserver === 'function') {
+      rectObserver = new ResizeObserver((entries) => {
+        for (const entry of entries) {
+          const id = nodeIds.get(entry.target as Node);
+          if (id !== undefined) queueRect(id, entry.target as Element);
+        }
+      });
+    }
+  };
+
+  const unmeasure = (id: number): void => {
+    if (!measuredIds.delete(id)) return;
+    pendingRects.delete(id);
+    const node = nodes.get(id);
+    if (node !== undefined) rectObserver?.unobserve(node as Element);
+  };
+
   /** Hand a live element to its slot mount callback (or drop it silently). */
   const mountSlot = (node: HTMLElement, id: number, name: string): void => {
     // Always set the attribute — nested-remove detection below finds slot
@@ -549,6 +633,90 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
     }
   };
 
+  /* ── Detached-node tombstones ─────────────────────────────────────────────
+   * A `remove` op detaches the real node, but the worker may re-append the
+   * same id later (renderers reorder siblings: zrender restacks displayables,
+   * list libraries shuffle rows, `clear`+`append` remounts reuse their ids).
+   * Entries move into `detached` instead of vanishing so a later `append`
+   * can restore them; the cap bounds churn from create/remove cycles
+   * (tooltip text, transient overlays) that never comes back. Lookups
+   * promote on demand via nodeById — an op may reference a tombstoned
+   * descendant before its ancestor's re-append lands. */
+  const DETACHED_CAP = 1024;
+  interface Tombstone {
+    node: Node;
+    props?: WireProps;
+    listeners?: Map<string, EventListener>;
+    slot?: string;
+  }
+  const detached = new Map<number, Tombstone>();
+  /** tombstoned node → id — promote walks find subtree ids without nodeIds. */
+  const detachedIds = new Map<Node, number>();
+
+  const tombstoneId = (id: number, node: Node): void => {
+    // Drop the RO observation while the live map still resolves the node —
+    // after nodes.delete the unobserve would be a silent no-op and the
+    // observer would pin the detached element.
+    unmeasure(id);
+    detachedIds.set(node, id);
+    detached.set(id, {
+      node,
+      props: prevProps.get(id),
+      listeners: nodeListeners.get(id),
+      // The slot name survives unmountSlot's slotNodes.delete only on the
+      // element's marker attribute — read it from the DOM, not the map.
+      slot: isElementNode(node) ? (node.getAttribute('data-atoll-slot') ?? undefined) : undefined,
+    });
+    nodes.delete(id);
+    nodeIds.delete(node);
+    prevProps.delete(id);
+    nodeListeners.delete(id);
+    if (detached.size > DETACHED_CAP) {
+      // Map order is insertion order — evict the oldest tombstone. A later
+      // op referencing an evicted id takes the normal missing-node path.
+      const oldest = detached.keys().next().value;
+      if (oldest !== undefined) {
+        const dead = detached.get(oldest);
+        detached.delete(oldest);
+        if (dead !== undefined) detachedIds.delete(dead.node);
+      }
+    }
+  };
+
+  /** Move a node AND its whole subtree into tombstones. */
+  const tombstoneSubtree = (rootId: number, root: Node): void => {
+    const walk = (node: Node): void => {
+      const id = node === root ? rootId : nodeIds.get(node);
+      if (id !== undefined && id !== 0) tombstoneId(id, node);
+      for (const child of Array.from(node.childNodes)) walk(child);
+    };
+    walk(root);
+  };
+
+  /** Restore a tombstoned node + descendants (re-append after remove). */
+  const promoteSubtree = (id: number): Node | undefined => {
+    const tomb = detached.get(id);
+    if (tomb === undefined) return nodes.get(id);
+    detached.delete(id);
+    detachedIds.delete(tomb.node);
+    nodes.set(id, tomb.node);
+    nodeIds.set(tomb.node, id);
+    if (tomb.props !== undefined) prevProps.set(id, tomb.props);
+    if (tomb.listeners !== undefined) nodeListeners.set(id, tomb.listeners);
+    if (tomb.slot !== undefined) {
+      slotNodes.set(id, tomb.slot);
+      opts.slots?.[tomb.slot]?.(tomb.node as HTMLElement);
+    }
+    for (const child of Array.from(tomb.node.childNodes)) {
+      const cid = detachedIds.get(child);
+      if (cid !== undefined) promoteSubtree(cid);
+    }
+    return tomb.node;
+  };
+
+  /** nodes.get that promotes tombstoned entries on demand. */
+  const nodeById = (id: number): Node | undefined => nodes.get(id) ?? promoteSubtree(id);
+
   let opsApplied = 0;
   let flushCalls = 0;
   let mode: Mode = initialMode ?? 'push';
@@ -556,8 +724,42 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
   let pollTimer: number | null = null;
   let destroyed = false;
 
+  /* ── Dispatch queue ───────────────────────────────────────────────────────
+   * Every real event used to fire its own postMessage the moment it landed:
+   * a pointer sweep queues round-trips faster than the worker drains them,
+   * and each in-flight call pins its payload + the island's maps. The queue
+   * preserves DOM order while bounding in-flight calls. Move-type events
+   * coalesce — a queued move superseded by a newer one for the same
+   * (handler, type) is dropped before it hits the wire; only the freshest
+   * position matters for pointer tracking. Boundary events (out/over/down/
+   * up/wheel) never merge and never overtake a queued move, so enter/leave
+   * edges stay ordered after the moves they coalesce past. */
+  const COALESCE_EVENTS = new Set(['mousemove', 'pointermove', 'touchmove', 'drag', 'dragover']);
+  const MAX_IN_FLIGHT_DISPATCH = 4;
+  /* How long destroy() waits for the worker's unmount batch before force-
+   * tearing down. Generous enough for a busy worker draining real tasks;
+   * short enough that a wedged worker is visibly gone soon. */
+  const UNMOUNT_GRACE_MS = 1500;
+  const dispatchQueue: Array<{ handlerId: number; key: string | null; payload: EventPayload }> = [];
+  let inFlightDispatches = 0;
+
+  const pumpDispatches = (): void => {
+    while (!destroyed && inFlightDispatches < MAX_IN_FLIGHT_DISPATCH && dispatchQueue.length > 0) {
+      const next = dispatchQueue.shift()!;
+      inFlightDispatches++;
+      void islandCall('dispatch', client.dispatch(next.handlerId, next.payload))
+        .then((ops) => applyOps(ops, 'dispatch'))
+        .catch((err) => console.error(`[island ${instance}] dispatch failed`, err))
+        .finally(() => {
+          inFlightDispatches--;
+          pumpDispatches();
+        });
+    }
+  };
+
   function listenerFor(handlerId: number): EventListener {
     return (e: Event) => {
+      if (destroyed) return;
       const target = e.target;
       const payload = buildEventPayload(
         e,
@@ -565,11 +767,13 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
         target !== null ? nodeIds.get(target as Node) : undefined,
         nodeIds.get((e as MouseEvent).relatedTarget as Node),
       );
-      // The whole point: an event = one postMessage round-trip. The worker
-      // re-renders, we apply whatever ops come back.
-      void islandCall('dispatch', client.dispatch(handlerId, payload))
-        .then((ops) => applyOps(ops, 'dispatch'))
-        .catch((err) => console.error(`[island ${instance}] dispatch failed`, err));
+      const key = COALESCE_EVENTS.has(e.type) ? `${handlerId}:${e.type}` : null;
+      if (key !== null) {
+        const stale = dispatchQueue.findIndex((q) => q.key === key);
+        if (stale !== -1) dispatchQueue.splice(stale, 1);
+      }
+      dispatchQueue.push({ handlerId, key, payload });
+      pumpDispatches();
     };
   }
 
@@ -742,6 +946,10 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
   function mergeStyle(node: Element, id: number, changes: Record<string, string>): void {
     const elStyle = (node as HTMLElement).style;
     const elStyleMap = elStyle as unknown as Record<string, string>;
+    // Real DOM keeps the (now-empty) style attribute after the last property
+    // clears; happy-dom drops it. Preserve the distinction a never-styled
+    // element has — absence only when the attribute never existed.
+    const hadStyleAttr = node.hasAttribute('style');
     const prev = prevProps.get(id) ?? {};
     const merged = { ...((prev.style ?? {}) as Record<string, string>) };
     for (const [k, v] of Object.entries(changes)) {
@@ -760,6 +968,7 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
       }
       merged[k] = v;
     }
+    if (hadStyleAttr && !node.hasAttribute('style')) node.setAttribute('style', '');
     prev.style = merged;
     prevProps.set(id, prev);
   }
@@ -794,8 +1003,8 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
         break;
       }
       case 'append': {
-        let parent = nodes.get(op.parent);
-        const child = nodes.get(op.child);
+        let parent = nodeById(op.parent);
+        const child = nodeById(op.child);
         if (!parent || !child) {
           console.error(`[island] append skipped: parent=${op.parent}→${String(parent)} child=${op.child}→${String(child)}`);
           break;
@@ -807,18 +1016,24 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
         if (isElementNode(parent) && parent.tagName === 'TEMPLATE') {
           parent = (parent as HTMLTemplateElement).content;
         }
-        const before = op.before !== undefined ? (nodes.get(op.before) ?? null) : null;
+        const before = op.before !== undefined ? (nodeById(op.before) ?? null) : null;
         parent.insertBefore(child, before);
         break;
       }
       case 'remove': {
-        const child = nodes.get(op.child);
-        if (child !== undefined) unmountSlotSubtree(child);
+        const child = nodeById(op.child);
+        if (child !== undefined) {
+          unmountSlotSubtree(child);
+          // unmeasure + every map eviction happens inside tombstoneSubtree:
+          // descendants get no remove op of their own, so the walk is the
+          // only place they can leave nodes/prevProps/nodeListeners.
+          tombstoneSubtree(op.child, child);
+        }
         child?.parentNode?.removeChild(child);
         break;
       }
       case 'update': {
-        const node = nodes.get(op.id);
+        const node = nodeById(op.id);
         if (!isElementNode(node)) break;
         const prev = prevProps.get(op.id) ?? {};
         applyProps(node, op.id, prev, op.props);
@@ -826,24 +1041,24 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
         break;
       }
       case 'utext': {
-        const node = nodes.get(op.id);
+        const node = nodeById(op.id);
         if (node) node.textContent = op.text;
         break;
       }
       case 'attr': {
-        const node = nodes.get(op.id);
+        const node = nodeById(op.id);
         if (!isElementNode(node)) break;
         setAttr(node, op.id, op.name, op.value);
         break;
       }
       case 'style': {
-        const node = nodes.get(op.id);
+        const node = nodeById(op.id);
         if (!isElementNode(node)) break;
         mergeStyle(node, op.id, op.props);
         break;
       }
       case 'listen': {
-        const node = nodes.get(op.id);
+        const node = nodeById(op.id);
         if (!isElementNode(node)) break;
         // Keyed by type + handler id so proxy listeners can't collide with
         // the React-prop listener for the same event name, and so unlisten
@@ -861,7 +1076,7 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
         break;
       }
       case 'unlisten': {
-        const node = nodes.get(op.id);
+        const node = nodeById(op.id);
         if (!isElementNode(node)) break;
         const key = `${op.type}#${op.handler}`;
         const listener = nodeListeners.get(op.id)?.get(key);
@@ -881,6 +1096,12 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
         // like a `remove` op would so slots callbacks see null and
         // slotNodes doesn't leak.
         unmountSlotSubtree(el);
+        // Children detach with their ids tombstoned — a remount's following
+        // `append` re-promotes them rather than leaking map entries.
+        for (const child of Array.from(el.childNodes)) {
+          const id = nodeIds.get(child);
+          if (id !== undefined) tombstoneSubtree(id, child);
+        }
         el.replaceChildren();
         break;
       }
@@ -901,10 +1122,26 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
         onEvent?.(op.name, op.payload);
         break;
       }
+      case 'measure': {
+        const node = nodeById(op.id);
+        if (!isElementNode(node)) break;
+        measuredIds.add(op.id);
+        ensureRectObserver();
+        rectObserver?.observe(node);
+        // The initial rect ships immediately — ResizeObserver only ticks on
+        // later resizes (and on mount for a detached-then-appended node),
+        // so without it a read-heavy mount would wait a frame for nothing.
+        queueRect(op.id, node);
+        break;
+      }
+      case 'unmeasure': {
+        unmeasure(op.id);
+        break;
+      }
     }
   }
 
-  function applyOps(ops: Op[], via: 'mount' | 'updateProps' | 'dispatch' | 'setSize' | 'flush'): void {
+  function applyOps(ops: Op[], via: 'mount' | 'updateProps' | 'dispatch' | 'setSize' | 'setRects' | 'flush' | 'unmount'): void {
     opsApplied += ops.length;
     onActivity?.();
     const t0 = performance.now();
@@ -923,7 +1160,7 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
 
   /** Times a main→worker round-trip for the devtools inspector. */
   const islandCall = <T>(
-    method: 'mount' | 'whoami' | 'dispatch' | 'setSize' | 'updateProps' | 'flush' | 'unmount',
+    method: 'mount' | 'whoami' | 'dispatch' | 'setSize' | 'setRects' | 'updateProps' | 'flush' | 'unmount',
     p: Promise<T>,
   ): Promise<T> => {
     const t0 = performance.now();
@@ -1101,32 +1338,47 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
       emitDevtools({ type: 'island:unmount', instance });
       unsubscribe?.();
       resizeObserver?.disconnect();
+      rectObserver?.disconnect();
       if (pollTimer !== null) clearInterval(pollTimer);
       if (sizeTimer !== null) clearTimeout(sizeTimer);
+      if (rectTimer !== null) clearTimeout(rectTimer);
+      pendingRects.clear();
+      measuredIds.clear();
       const remaining = (clientMounts.get(client) ?? 1) - 1;
       clientMounts.set(client, remaining);
-      if (remaining > 0) {
-        // The worker still serves sibling mounts — hand this one back. The
-        // detach ops are irrelevant if our element is already gone, so the
-        // return batch is dropped. Best-effort: the instance map and its
-        // handlers release regardless.
-        void islandCall('unmount', client.unmount(instance)).catch(() => {});
-      } else {
-        // Last island — still run the instance's teardown first so the app's
-        // dispose hook cancels deferred work (library timers, animation
-        // loops) and the proxy doc unwinds. In a real worker terminate may
-        // kill the thread before unmount lands — equally fine, process
-        // death is teardown — but in-process workers need this or the
-        // instance zombies on and its pending callbacks mutate foreign docs.
-        void islandCall('unmount', client.unmount(instance))
-          .catch(() => {})
-          .finally(() => {
-            // A remount may have registered while teardown was in flight
-            // (app/client input swap does destroy → mount back-to-back) —
-            // terminate only when the client is still truly idle.
-            if ((clientMounts.get(client) ?? 0) === 0) client.terminate();
-          });
-      }
+      /* One bounded teardown for both cases. The worker's unmount batch is
+       * still awaited so the app's dispose hook cancels deferred work and
+       * the `clear` op can fire slots[name](null) for slot anchors — but
+       * the wait is capped by UNMOUNT_GRACE_MS. A wedged worker (a task
+       * that never settles) must not pin the worker, this island's driver
+       * state, or the pending-call closures forever. finish() releases the
+       * maps eagerly so ops arriving late replay against empty maps (all
+       * lookups miss → no-ops), and on the last mount it terminates the
+       * worker unconditionally — as long as no remount registered while
+       * teardown was in flight (app/client swap does destroy → mount
+       * back-to-back; terminate only when the client is truly idle). */
+      let finished = false;
+      const finish = () => {
+        if (finished) return;
+        finished = true;
+        nodes.clear();
+        detached.clear();
+        detachedIds.clear();
+        prevProps.clear();
+        nodeListeners.clear();
+        cbTable.clear();
+        slotNodes.clear();
+        dispatchQueue.length = 0;
+        // keepAlive clients stay resident — the instance is unmounted but
+        // the thread idles so the next mount is a warm start.
+        if (remaining <= 0 && !isKeepAliveClient(client) && (clientMounts.get(client) ?? 0) === 0)
+          client.terminate();
+      };
+      void islandCall('unmount', client.unmount(instance))
+        .then((ops) => applyOps(ops, 'unmount'))
+        .catch(() => {})
+        .finally(finish);
+      setTimeout(finish, UNMOUNT_GRACE_MS);
     },
   };
   // Dashboard commands (`island.*`) — registered only while devtools is on.

package/src/ops.ts

@@ -84,7 +84,39 @@ export type Op =
    * `onEvent(name, payload)` instead of mutating the DOM. Payloads must be
    * structured-cloneable — same rule as props.
    */
-  | { t: 'emit'; name: string; payload?: unknown };
+  | { t: 'emit'; name: string; payload?: unknown }
+  /**
+   * Request real geometry for `id` — the worker-side proxy DOM emits this
+   * when `doc.observeSize(el, cb)` registers (and once, lazily, when an
+   * unmarked element's geometry is read). The driver measures the real
+   * node, observes it with a ResizeObserver, and pushes rects back through
+   * the `setRects` task. Fire-and-forget: reads keep returning the honest 0
+   * until the first push lands. Older drivers ignore the op; the reads stay
+   * 0 — same degradation as an element that never gets measured.
+   */
+  | { t: 'measure'; id: number }
+  /**
+   * Cancel a `measure` request — emitted when the last `observeSize`
+   * observer for `id` detaches. Elements auto-requested by a geometry read
+   * stay observed for the element's lifetime (the driver also unobserves
+   * on `remove`/`clear`).
+   */
+  | { t: 'unmeasure'; id: number };
+
+/**
+ * One measured box, pushed main→worker by the `setRects` task. `x`/`y` are
+ * the node's viewport-relative position (getBoundingClientRect), `w`/`h`
+ * its size — worker-side reads derive top/left/right/bottom from these.
+ * Updates fire on element RESIZE (the driver's ResizeObserver); position-only
+ * moves don't retrigger, matching what chart/map libraries actually consume.
+ */
+export interface MeasuredRect {
+  id: number;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
 
 /**
  * Wire-serialized props. Functions named `on*` (onClick, onInput, …) cross as
@@ -220,16 +252,25 @@ export type IslandWorkerMethods = {
   /** Invoke the worker handler a `__evt` ref or `listen` op points at. */
   dispatch(handlerId: number, payload: EventPayload): Op[];
   /**
-   * Push the island container's measured box into the instance — the ONLY
-   * geometry channel that exists. The driver observes the island's `el`
-   * with a ResizeObserver and calls this once at mount and on resizes
-   * (throttled ~100ms). The instance stores {w,h}; proxy-DOM geometry reads on
-   * `doc.body`/`documentElement` and on elements marked via
-   * `doc.markContainer(el)` then return it — deeper elements keep the
-   * honest 0. Handlers registered via `doc.onResize` re-run on each push;
-   * their ops ride back in this method's return batch.
+   * Push the island container's measured box into the instance — the
+   * always-on geometry channel (per-element rects additionally flow through
+   * `setRects` for elements that requested measurement). The driver observes
+   * the island's `el` with a ResizeObserver and calls this once at mount and
+   * on resizes (throttled ~100ms). The instance stores {w,h}; proxy-DOM
+   * geometry reads on `doc.body`/`documentElement` and on elements marked via
+   * `doc.markContainer(el)` then return it. Handlers registered via
+   * `doc.onResize` re-run on each push; their ops ride back in this method's
+   * return batch.
    */
   setSize(instance: string, width: number, height: number): Op[];
+  /**
+   * Push freshly measured element rects — the answer to `measure` ops and
+   * the driver's per-element ResizeObserver ticks. Each rect updates the
+   * instance's per-element store and fires the element's `observeSize`
+   * callbacks inside the instance's scope, so their ops ride back in this
+   * method's return batch like `setSize`'s onResize handlers.
+   */
+  setRects(instance: string, rects: MeasuredRect[]): Op[];
   /** Drain ops committed outside a task (passive effects, timers). */
   flush(instance: string): Op[];
   /**

package/src/worker/defineWorkers.ts

@@ -79,9 +79,11 @@ import {
   setDoorbellContract,
   setInstanceContract,
   setInstanceSize,
+  setInstanceRect,
+  clearInstanceRects,
   takeOps,
 } from './instance';
-import type { EventPayload, IslandWorkerMethods, Op } from '../ops';
+import type { EventPayload, IslandWorkerMethods, MeasuredRect, Op } from '../ops';
 
 /**
  * Registry value shapes:
@@ -573,6 +575,31 @@ function createIslandRuntime(
         });
       },
 
+      /**
+       * The measured-element channel: rects the driver pushed in answer to
+       * `measure` ops. Stored in the instance-level map FIRST so geometry
+       * reads answer even for mounts without a materialized proxy document
+       * (a React element adopted later sees its rect immediately); then
+       * per-element observeSize callbacks fire inside the instance's scope,
+       * their ops riding back in the batch like onResize handlers.
+       */
+      setRects(instance: string, rects: MeasuredRect[]): Op[] {
+        const mounted = mounts.get(instance);
+        const doc =
+          mounted !== undefined && isImperativeInstance(mounted)
+            ? mounted.imperative.doc
+            : peekInstanceDoc(instance);
+        if (doc === undefined) {
+          // No doc yet — store rects raw so adopted elements still answer.
+          for (const rect of rects) setInstanceRect(instance, rect);
+          return takeOps(instance);
+        }
+        return runInInstance(mounted?.key ?? instance, () => {
+          (doc as InternalDocument)._notifyRects(rects);
+          return takeOps(instance);
+        });
+      },
+
       /**
        * Tear down ONE instance while the worker keeps serving its others —
        * the multi-island-per-worker counterpart to process death: disposes
@@ -585,6 +612,7 @@ function createIslandRuntime(
         if (mounted === undefined) return [];
         mounts.delete(instance);
         setInstanceContract(instance, undefined);
+        clearInstanceRects(instance);
         return runInInstance(instance, () => {
           if (isImperativeInstance(mounted)) {
             // The app's dispose hook cancels deferred work (library timers,

package/src/worker/dom/css.ts

@@ -89,6 +89,7 @@ export function styleProxyFor(el: ProxyElement): CSSStyleDeclaration {
           };
         if (prop === 'cssText') {
           return Object.entries(t)
+            .filter(([, v]) => v !== '')
             .map(([k, v]) => `${hyphenate(k)}: ${v};`)
             .join(' ');
         }
@@ -96,7 +97,8 @@ export function styleProxyFor(el: ProxyElement): CSSStyleDeclaration {
         return undefined;
       },
       set: (_t, prop, v) => {
-        if (typeof prop === 'string') el._writeStyle(prop, String(v));
+        if (prop === 'cssText') el._replaceStyleText(String(v));
+        else if (typeof prop === 'string') el._writeStyle(prop, String(v));
         return true;
       },
       deleteProperty: (_t, prop) => {