@atolljs/islands 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/islands",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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.9"
+    "@atolljs/core": "0.1.11"
   },
   "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';
@@ -227,6 +228,7 @@ function buildEventPayload(
   e: Event,
   target: EventTarget | null,
   targetId: number | undefined,
+  relatedTargetId?: number,
 ): EventPayload {
   const input = target as HTMLInputElement | null;
   const mouse = e as MouseEvent;
@@ -243,6 +245,18 @@ function buildEventPayload(
   const coord = (v: unknown): number | undefined =>
     num(v) ?? (pointerFam ? 0 : undefined);
   const button = num(mouse.button) ?? (pointerFam ? 0 : undefined);
+  // currentTarget is the element this listener was attached to — the exact
+  // element hit-testing libraries normalize pointer coords against
+  // (zrender's `normalizeEvent(this.dom, e)`). Checked structurally, not
+  // via `instanceof Element`: in in-process embeddings the worker-side
+  // dispatcher may point the global at ProxyElement.
+  const ct = e.currentTarget as Element | null;
+  const localRect =
+    ct && typeof ct.getBoundingClientRect === 'function'
+      ? ct.getBoundingClientRect()
+      : null;
+  const local = (v: number | undefined, origin: number): number | undefined =>
+    localRect && typeof v === 'number' ? v - origin : undefined;
   return {
     type: e.type,
     value: input && 'value' in input ? input.value : undefined,
@@ -252,6 +266,8 @@ function buildEventPayload(
     clientY: coord(mouse.clientY),
     screenX: coord(mouse.screenX),
     screenY: coord(mouse.screenY),
+    zrX: local(mouse.clientX, localRect?.left ?? 0),
+    zrY: local(mouse.clientY, localRect?.top ?? 0),
     button,
     which:
       typeof mouse.which === 'number' && mouse.which !== 0
@@ -273,6 +289,7 @@ function buildEventPayload(
     pointerType: typeof pointer.pointerType === 'string' ? pointer.pointerType : undefined,
     scrollTop: input instanceof HTMLElement ? input.scrollTop : undefined,
     targetId,
+    relatedTargetId,
   };
 }
 
@@ -496,6 +513,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
@@ -533,6 +613,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';
@@ -540,19 +704,52 @@ 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;
+  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,
         target,
         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();
     };
   }
 
@@ -725,6 +922,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)) {
@@ -743,6 +944,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);
   }
@@ -777,8 +979,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;
@@ -790,18 +992,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);
@@ -809,24 +1017,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
@@ -844,7 +1052,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);
@@ -864,6 +1072,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;
       }
@@ -884,10 +1098,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();
@@ -906,7 +1136,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();
@@ -1084,16 +1314,23 @@ 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(() => {});
+        // The worker still serves sibling mounts — hand this one back, but
+        // replay the teardown batch anyway: the `clear` op unmounts slot
+        // anchors inside our tree, firing slots[name](null) so slot render
+        // roots come down. Dropping it would leave a slot-hosted sibling
+        // mounted on this client and pin the worker alive.
+        void islandCall('unmount', client.unmount(instance))
+          .then((ops) => applyOps(ops, 'unmount'))
+          .catch(() => {});
       } else {
         // Last island — still run the instance's teardown first so the app's
         // dispose hook cancels deferred work (library timers, animation
@@ -1102,6 +1339,7 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
         // 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))
+          .then((ops) => applyOps(ops, 'unmount'))
           .catch(() => {})
           .finally(() => {
             // A remount may have registered while teardown was in flight

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
@@ -124,6 +156,19 @@ export interface EventPayload {
   clientY?: number;
   screenX?: number;
   screenY?: number;
+  /**
+   * Pointer coords in the LISTENER element's local space:
+   * `clientX/Y − event.currentTarget.getBoundingClientRect()` computed
+   * main-thread where real rects exist. The proxy DOM has no measurement
+   * channel, so worker-side hit-testing libraries cannot derive local
+   * coords themselves: zrender's four-marker getBoundingClientRect
+   * transform degenerates, and e.offsetX is absent anyway. zrender's
+   * normalizeEvent early-returns on `e.zrX != null`, which is why the
+   * fields carry its names — charts (echarts SVG renderer) get working
+   * axis pointers/tooltips, any library can read them the same way.
+   */
+  zrX?: number;
+  zrY?: number;
   button?: number;
   /**
    * UIEvent.which — non-standard but set by every browser (1 = left button,
@@ -153,6 +198,15 @@ export interface EventPayload {
   scrollTop?: number;
   /** The worker instance id of `event.target`, when it maps to one. */
   targetId?: number;
+  /**
+   * The worker instance id of `event.relatedTarget` (MouseEvent/FocusEvent),
+   * when it maps to an op-created node. Lets over/out/leave/enter handlers
+   * distinguish "moved to a child" from "actually left the element" —
+   * zrender's mouseout gate (`toElement || relatedTarget` → isLocalEl walk)
+   * is the canonical consumer; without it every child transition looks like
+   * a real leave and charts flicker as tooltips hide/show.
+   */
+  relatedTargetId?: number;
   /**
    * The proxy-DOM node for `targetId` — SYNTHESIZED worker-side by the proxy
    * DOM when it wraps a listener (it never crosses the wire). Lets delegated
@@ -162,6 +216,13 @@ export interface EventPayload {
    * same proxy document.
    */
   target?: unknown;
+  /**
+   * The proxy-DOM node for `relatedTargetId` — SYNTHESIZED worker-side like
+   * `target` (never crosses the wire). Handler code can walk
+   * `relatedTarget.parentNode` — e.g. zrender's isLocalEl — to test
+   * whether the pointer moved within the listener's subtree.
+   */
+  relatedTarget?: unknown;
   /**
    * Synthesized NO-OPS — added worker-side by the proxy DOM when it wraps a
    * listener's payload (they never cross the wire). They exist so library
@@ -191,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) => {