@symbiote-native/svelte 1.0.0 → 3.0.0

package/build/dom-shim/element.js

@@ -1,20 +1,33 @@
-// The workhorse of the shim. Every Symbiote intrinsic (`symbiote-view`, `symbiote-text`, …)
-// is a hyphenated tag, so Svelte compiles it down the CUSTOM-ELEMENT codegen path (§3g):
-// attributes go through `set_custom_element_data`, which stringifies scalars and hard-excludes
-// `style`. The resolution (§3g(c)) is a single object-bag PROPERTY, not a spread of
-// attributes — an object always satisfies `value && typeof value === 'object'`, so it lands as
-// a real property SET (`node.p = bag`), untouched by stringification. `p`'s setter (below)
-// unpacks the bag into `routeProp`, the same entry point React's flat bag and Vue's patchProp
-// already use.
+// The workhorse of the shim, and it has FIVE doors, not one — svelte decides which by tag name,
+// by compiled namespace and by whether the attribute starts with `on`, so an element cannot
+// choose its own:
+//
+//   set_custom_element_data   hyphenated tags (`text-input`, …). Stringifies a scalar; an OBJECT
+//                             lands as a real property set, which is what makes `p={{…}}` work.
+//   set_attribute             every other tag, and the hyphenated ones for a non-string value.
+//   set_class                 -> `setAttribute('class')` in the svg namespace, `dom.className`
+//                             in html. Both spellings land in the same bag key.
+//   set_style                 -> `dom.style.cssText`, STRINGIFIED, plus the authored value under
+//                             a private Symbol. See `style-cache.ts`.
+//   addEventListener          any `on<Name>` attribute, via `$.event()`, with the `on` stripped.
+//
+// All five converge on one folded bag and out through `routeProp`, the entry point React's flat
+// bag and Vue's patchProp already use — because only `routeProp` knows which `on*` names the
+// node's ViewConfig declares as events and which are ordinary callback props a behavior reads.
+// `p` is ours to name (§3g(c)); a component forwarding a whole bag emits it, app code need not.
+//
+// They converge, they do not merge: `p` owns its key SET, since a key dropped from the bag has to
+// reset the prop, while the other four own a key each. Hence `doorBag` / `pBag` below.
 //
 // A per-key diff in the setter is MANDATORY (§3g(c)), not an optimization: Svelte's
 // `set_custom_element_data` has no early-out guard and runs on every effect re-fire, so
 // without the diff every prop gets rewritten whenever any one of them changes.
-import { createElement, dlog, routeProp, setEventListener, toPublicInstance, } from '@symbiote-native/engine';
+import { createElement, dlog, routeProp, toPublicInstance, } from '@symbiote-native/engine';
 import { descriptorFor } from '@symbiote-native/components';
 import { normalizeSvelteClass } from '../class-value.js';
-import { foldHostBag } from './fold-host-bag.js';
+import { CANONICAL_BY_LOWER, CANONICAL_PROP_NAMES, } from './canonical-prop-names.js';
 import { ShimNode } from './shim-node.js';
+import { discoverStyleCacheKey } from './style-cache.js';
 // The bag a not-yet-live element is diffed against in onMadeLive. A module constant rather than a
 // fresh `{}` per node: it is only ever read, and the identity lets applyBagDiff skip its second
 // pass outright on the create path.
@@ -39,13 +52,27 @@ export class ShimElementBase extends ShimNode {
 export class ShimElement extends ShimElementBase {
     tagName;
     namespaceURI;
-    // Both LAZY, and that is a measured decision, not a style one. A lowered primitive carries its
-    // whole prop surface in the `p` bag, so neither map is ever written on the create path — but an
-    // eager field allocated two Maps per element regardless, 18 004 of them on a 1 000-row create,
-    // in a window where GC is the largest single bucket (29%).
-    attributes;
-    domListeners;
+    // LAZY, and that is a measured decision, not a style one. A primitive carrying its whole prop
+    // surface in the `p` bag never writes this on the create path — but an eager field allocated a
+    // Map per element regardless, 9 002 of them on a 1 000-row create, in a window where GC is the
+    // largest single bucket (29%).
+    attributes = undefined;
+    // The four attribute doors write `doorBag`, `set p` writes `pBag`, `lastBag` is the folded merge.
+    // Held in ONE object, `set p` deleted the `class` `from_tree` had written at clone time, so
+    // `<view p={handlers} class="x">` committed with no style at all and nothing was red. Unreachable
+    // while an element used one door, which nearly every element does.
+    // Both LAZY: an element touching one door still allocates one object.
+    doorBag = undefined;
+    pBag = undefined;
     lastBag = EMPTY_BAG;
+    // COPY-ON-WRITE ownership of `doorBag`. `true` only while THIS element is the sole holder of the
+    // object `doorBag` points at, which lets `writeBagKey` mutate it in place instead of re-copying it
+    // on every one of an element's own sequential door writes. `cloneNode` hands the SAME object to a
+    // second element (§ below) and must clear this on both sides the moment it does, or a write on
+    // one clone would mutate the bag a sibling clone still reads — see
+    // `prop-bag-diff.test.ts`'s "a write to one clone does not leak into a sibling clone" for the
+    // isolation this exists to preserve.
+    ownsDoorBag = false;
     constructor(tagName, namespaceURI) {
         super();
         this.tagName = tagName;
@@ -58,13 +85,27 @@ export class ShimElement extends ShimElementBase {
     // no-opping — a `style` attribute on a bare tag crashed the mount. LAZY, for the reason
     // `.claude/rules/svelte-shim-is-the-per-node-create-path.md` records about the two Maps below it:
     // an eager field is one object per element, ~9 000 per create, in the window where GC is the
-    // largest bucket. Only `set_style` touches this, and no lowered element takes that path.
-    styleSlot;
+    // largest bucket. Only `set_style` touches this, and a bag-carrying element never takes it.
+    styleSlot = undefined;
     get style() {
         return (this.styleSlot ??= { cssText: '' });
     }
+    // The real `style` seam, reached from the Symbol accessor below rather than from `.style`: that
+    // slot only ever sees `String(value)`. Not part of the DOM surface.
+    writeStyleValue(value) {
+        this.writeBagKey('style', value);
+    }
+    // `set_class`'s html-namespace exit. Without the setter it lands as a plain JS property, and the
+    // failure is half-silent: a static `class="card"` rides the template through `setAttribute` and
+    // keeps working, so only the dynamic spelling stops styling.
+    get className() {
+        return this.lastBag.class;
+    }
+    set className(value) {
+        this.writeBagKey('class', value);
+    }
     // The single object-bag prop. The literal name is ours to choose (§3g(c)) — the adapter's
-    // own View.svelte/Text.svelte/… emit `<symbiote-view p={bag}>`; app code never sees it.
+    // own View.svelte/Text.svelte/… emit `<view p={bag}>`; app code never sees it.
     get p() {
         return this.lastBag;
     }
@@ -72,7 +113,8 @@ export class ShimElement extends ShimElementBase {
         // The fold runs HERE rather than at element creation because an alias can arrive on an update
         // (`id` bound to a signal), and it runs before the diff so `lastBag` is always the folded shape
         // — otherwise a seeded default would look like a change on every single set.
-        const next = foldHostBag(this.tagName, normalizeBagClasses(bag ?? {}));
+        this.pBag = bag;
+        const next = this.foldedBag();
         const prev = this.lastBag;
         this.lastBag = next;
         // THUNK, not a string (see debug.ts's header): this setter runs once per element per create
@@ -85,29 +127,122 @@ export class ShimElement extends ShimElementBase {
         applyBagDiff(this.engineNode, prev, next);
         this.surface?.requestCommit();
     }
+    // A tag's props arrive here one key at a time, and they used to stop here: an inert Map, nothing
+    // routed, nothing committed, nothing red. Routing the key is what makes `<view testID="x">` and
+    // `<view p={{ testID: 'x' }}>` the same commit — the bag spelling is an optimisation, not the
+    // only way to reach the engine.
+    //
+    // `value` is `unknown`, not `string`: Svelte's `set_attribute` hands the raw value straight
+    // through for a name with no prototype setter, so an object `style` or a number arrives
+    // unstringified. The DOM would coerce it; we must not — `routeProp` wants the real value.
+    //
+    // The Map stays, and is not redundant: `getAttribute` must answer with the name the caller
+    // wrote, while the bag has been folded (`id` -> `nativeID`) by the time it is stored.
+    // `name` arrives LOWERCASED for every static attribute on every tag, and for a dynamic one on any
+    // tag whose name is not also an SVG element — the compiler settles that, so the repair has to
+    // happen here. One Map lookup per attribute write, no allocation; a name already canonical (or
+    // one we do not know) is handed on untouched. See `canonical-prop-names.ts`.
     setAttribute(name, value) {
         (this.attributes ??= new Map()).set(name, value);
+        this.writeBagKey(CANONICAL_BY_LOWER.get(name) ?? name, value);
     }
     getAttribute(name) {
         return this.attributes?.get(name) ?? null;
     }
     removeAttribute(name) {
         this.attributes?.delete(name);
+        // Same repair as the write, or a removal clears a key nothing ever set.
+        this.writeBagKey(CANONICAL_BY_LOWER.get(name) ?? name, undefined);
     }
+    // One key into the same bag `set p` writes, so the three spellings cannot drift into three
+    // representations. Folded on every write because the fold is idempotent by construction
+    // (`fold-host-bag.ts` states and tests that) — a bare tag has no other pass that could do it.
+    //
+    // Not `private`: the prototype accessors installed at the bottom of this file are the third
+    // writer, and they are defined from module scope because there are ~290 of them.
+    writeBagKey(name, value) {
+        // COW: reuse `doorBag` in place only while this element is its SOLE owner (never cloned since
+        // its last write) — `cloneNode` clears the flag on both sides the instant a bag becomes shared
+        // (§ above). A fresh `{}` is `own`ed immediately: nothing else can reach it yet.
+        // Narrowed through a LOCAL, not through `owned`: TypeScript discards an aliased condition
+        // whose operands include a mutable property (`this.ownsDoorBag`), so the `!== undefined` leg
+        // never reached `this.doorBag` at the use site and this line did not compile.
+        const reusable = this.doorBag !== undefined && this.ownsDoorBag ? this.doorBag : undefined;
+        const owned = reusable !== undefined;
+        const door = reusable ?? { ...this.doorBag };
+        this.ownsDoorBag = true;
+        const prevValue = door[name];
+        if (value === undefined)
+            delete door[name];
+        else
+            door[name] = value;
+        this.doorBag = door;
+        const prev = this.lastBag;
+        const next = this.foldedBag();
+        this.lastBag = next;
+        if (this.engineNode === undefined)
+            return; // not live yet — onMadeLive() replays in full
+        // `foldedBag()` hands `door` straight back, BY REFERENCE, whenever there is no `p` bag to merge
+        // it with (its own "no `pBag`" branch) — so when `door` was mutated IN PLACE above (`owned`),
+        // `next` and `door` are the same object post-mutation, and a full `prev`-vs-`next` diff would
+        // be comparing that object against itself and finding nothing changed. The one key just written
+        // is the whole diff in that shape, by construction, so route it directly and skip the diff loop
+        // — this is what makes the COW above safe rather than merely silent (see
+        // `prop-bag-diff.test.ts`'s "commits an attribute written after it is live" style cases, which
+        // caught the alternative — a no-op write — the first time this was tried without this branch).
+        if (owned && this.pBag === undefined) {
+            const nextValue = next[name];
+            if (prevValue !== nextValue)
+                routeProp(this.engineNode, name, nextValue);
+            this.surface?.requestCommit();
+            return;
+        }
+        applyBagDiff(this.engineNode, prev, next);
+        this.surface?.requestCommit();
+    }
+    // A door key WINS over the same name inside `p`: fixed precedence, so the committed value does
+    // not depend on which setter svelte called last. Branched to keep a one-door element at one fold.
+    foldedBag() {
+        const door = this.doorBag;
+        const bag = this.pBag;
+        if (door === undefined)
+            return normalizeBagClasses(bag ?? {});
+        if (bag === undefined)
+            return normalizeBagClasses(door);
+        return normalizeBagClasses({ ...bag, ...door });
+    }
+    // THE FIFTH DOOR, and it converges on the same bag as the other four. Svelte turns EVERY
+    // `on<Name>` attribute into `$.event()`, whatever the name means to us — so this receives both
+    // `Press`, which the node's ViewConfig declares as an event, and `ValueChange`, which no config
+    // declares and which `behaviors/{switch,text-input}.ts` read as `node.props.onValueChange`.
+    // Calling `setEventListener` directly answered "event" for both and stashed the second under a
+    // name nothing dispatches to: the toggle moved natively and the app's callback never ran.
+    // Only `routeProp` knows which is which, so the handler goes back through the bag under the name
+    // the author wrote.
     addEventListener(name, handler) {
-        (this.domListeners ??= new Map()).set(name, handler);
-        if (this.engineNode !== undefined)
-            setEventListener(this.engineNode, name, handler);
+        this.writeBagKey(propNameForEvent(name), handler);
     }
     removeEventListener(name) {
-        this.domListeners?.delete(name);
-        if (this.engineNode !== undefined)
-            setEventListener(this.engineNode, name, undefined);
+        this.writeBagKey(propNameForEvent(name), undefined);
     }
     cloneNode(deep) {
         const clone = new ShimElement(this.tagName, this.namespaceURI);
         if (this.attributes !== undefined)
             clone.attributes = new Map(this.attributes);
+        // The bag, not just the Map — `from_tree` builds each template ONCE, writes its static
+        // attributes onto that master, and then clones per instance, so without this every attribute
+        // an app spells statically (`<view testID="x" class="card">`) is dropped from every instance.
+        // A reference copy is safe because `writeBagKey` and `set p` both publish a fresh object.
+        // `doorBag` too, or a `set p` on the CLONE re-folds without the master's static attributes.
+        clone.doorBag = this.doorBag;
+        clone.pBag = this.pBag;
+        clone.lastBag = this.lastBag;
+        // `doorBag` (if any) now has TWO owners. Neither may mutate it in place from here — the next
+        // write on either side must copy first and only then reclaims exclusive ownership of ITS OWN
+        // copy. Without this a clone's first `setAttribute` would mutate the master's (and every other
+        // sibling clone's) committed props in place.
+        this.ownsDoorBag = false;
+        clone.ownsDoorBag = false;
         if (deep === true) {
             for (const child of this.children)
                 clone.appendChild(child.cloneNode(true));
@@ -121,22 +256,89 @@ export class ShimElement extends ShimElementBase {
     createEngineNode() {
         const descriptor = descriptorFor(this.tagName);
         // The INTRINSIC TAG as the third argument, and this is the only place the tag alphabet still
-        // exists: `descriptor.component` is the Fabric view name (`symbiote-view` -> `RCTView`), so a
+        // exists: `descriptor.component` is the Fabric view name (`view` -> `RCTView`), so a
         // host-behavior registry keyed by tag can only be reached from here. The argument defaults to
         // `component`, so passing it changes nothing until a behavior is registered.
         return toPublicInstance(createElement(descriptor.component, descriptor.isText, this.tagName));
     }
+    // One replay, because a handler is an ordinary bag key now — it arrives before the node is live
+    // exactly like `class` or `style` does, and leaves through the same diff.
     onMadeLive() {
         const engineNode = this.engineNode;
         if (engineNode === undefined)
             return;
         applyBagDiff(engineNode, EMPTY_BAG, this.lastBag);
-        if (this.domListeners === undefined)
-            return;
-        for (const [name, handler] of this.domListeners)
-            setEventListener(engineNode, name, handler);
     }
 }
+// Svelte hands `addEventListener` the authored name minus its `on`, so `onPress` arrives as
+// `Press`. Putting it back is what lets the handler re-enter through the ordinary prop bag, where
+// `routeProp` decides event-vs-prop from the node's ViewConfig — the one decision this layer
+// cannot make. A name that was already lowercase (`onclick` -> `click`) rebuilds as `onclick`,
+// which no config declares and which therefore lands inertly in `node.props`, exactly as a DOM
+// event name should on a native host.
+//
+// A charCode test rather than `name[0] !== name[0].toUpperCase()`: this runs per handler per
+// element on the create path, and the comparison spelling allocates two strings to answer it.
+function propNameForEvent(name) {
+    const first = name.charCodeAt(0);
+    if (first >= 65 /* A */ && first <= 90 /* Z */)
+        return `on${name}`;
+    return `on${name[0].toUpperCase()}${name.slice(1)}`;
+}
+// The seam `set_style` writes the authored value to. Discovered once, at module load, because
+// svelte's key is a module-private Symbol — see `style-cache.ts` for the whole mechanism.
+Object.defineProperty(ShimElement.prototype, discoverStyleCacheKey(), {
+    get() {
+        return this.p.style;
+    },
+    set(value) {
+        this.writeStyleValue(value);
+    },
+});
+// The setters `get_setters` has to find, so `set_custom_element_data` stops guessing. Its
+// heuristic branch — reached whenever no real setter exists for the name — hands a scalar on as
+// `String(value)` and assigns an object to a plain JS property the shim never reads, so a
+// hyphenated tag committed `"false"` for `multiline={false}` and nothing at all for an object.
+// With a setter present the raw value lands in the same folded bag `set p` and `setAttribute`
+// write, and the three doors agree.
+//
+// ONE-TIME, at module load: ~290 defineProperty calls, nothing per node
+// (`svelte-shim-is-the-per-node-create-path.md`). The instance shape does not move — these live on
+// the prototype — so no element pays for them.
+//
+// A name the shim ALREADY owns is skipped rather than overwritten, and it is owned in TWO places
+// that need two different tests. On the PROTOTYPE: `style` is a `{cssText}` slot `set_style`
+// writes through, `className` is `set_class`'s html exit, `p` is the bag itself — an `in` test
+// covers those, and covers a future member of the chain the day it is added.
+//
+// On the INSTANCE is the one that cost a device crash. `children` is a canonical prop name AND
+// ShimNode's own field — the tree itself — and `in` cannot see it, because a class field lives on
+// the instance and the prototype is empty at module load. Installing an accessor over it is
+// harmless under vitest, where `useDefineForClassFields` makes `this.children = []` a
+// `defineProperty` that shadows the accessor, and FATAL under Metro, whose loose class fields
+// compile it to an assignment that the prototype setter swallows — so `this.children` read back
+// `this.p.children`, i.e. undefined, and `makeLive` died iterating it on the app's ROOT node.
+// Every one of the 328 headless tests passed.
+//
+// The probe is a real instance built before the loop, so it answers with whatever fields the
+// ACTIVE transform materialises rather than a list someone has to keep. Its fields carry explicit
+// `= undefined` initializers for the same reason: a bare declaration emits nothing under Metro and
+// the probe would not see it.
+const SHAPE_PROBE = new ShimElement('view');
+for (const name of CANONICAL_PROP_NAMES) {
+    if (name in ShimElement.prototype)
+        continue;
+    if (Object.hasOwn(SHAPE_PROBE, name))
+        continue;
+    Object.defineProperty(ShimElement.prototype, name, {
+        get() {
+            return this.p[name];
+        },
+        set(value) {
+            this.writeBagKey(name, value);
+        },
+    });
+}
 // Both spellings route through the engine's shared class+style merge (routeProp's
 // CLASS_PROP_KEYS), so both get the same clsx normalization here.
 const CLASS_BAG_KEYS = ['class', 'className'];

package/build/dom-shim/patch-globals.js

@@ -40,6 +40,7 @@ const PATCHED_KEYS = [
     'DocumentFragment',
     'document',
     'customElements',
+    'HTMLMediaElement',
 ];
 // Real DOM's `CustomElementRegistry`. `set_custom_element_data` (svelte's
 // dom/elements/attributes.js) reads the BARE global `customElements` unconditionally, with no
@@ -48,11 +49,34 @@ const PATCHED_KEYS = [
 // pipeline (mount-pipeline.smoke.test.ts); `tsc --build` has no way to catch a missing global
 // a compiled Svelte bundle reads. RN/Hermes has no Custom Elements API of its own to collide
 // with (unlike `navigator`/`requestAnimationFrame`, verified against .vendors/react-native —
-// see the header comment above), so patching this is safe. `get()` always returns `undefined`
-// since we never call `customElements.define()`, which is exactly what steers
-// `set_custom_element_data` down the object-bag "set as property" branch every `p={bag}` prop
-// needs (skill §3g(c)).
-const FAKE_CUSTOM_ELEMENT_REGISTRY = { get: () => undefined };
+// see the header comment above), so patching this is safe.
+//
+// `get()` returns a TRUTHY stand-in, and that is the whole reason `set_custom_element_data` can be
+// made lossless. Its condition (attributes.js:245-265) is a ternary, not a fallback:
+//
+//   setters_cache.has(nodeName) || !customElements || customElements.get(nodeName)
+//     ? get_setters(node).includes(prop)     <- a real setter decides; the value passes through
+//     : value && typeof value === 'object'   <- a HEURISTIC: an object is set as a property and
+//                                               every scalar is handed on as String(value)
+//
+// Returning `undefined` — which it did until 2026-09-07 — selects the heuristic, so
+// `<text-input multiline={false}>` committed the STRING "false" and an object-valued prop with no
+// prototype setter was assigned to a plain JS property and silently lost. Anything truthy steers
+// it to `get_setters`, which reaches `ShimElement.prototype`'s accessors (see
+// `svelte-shim-element-global-must-be-an-ancestor.md` for why that walk terminates where it does).
+// One reader in the whole client runtime, so nothing else is affected.
+const FAKE_CUSTOM_ELEMENT_REGISTRY = {
+    get: () => ShimElement,
+};
+// Same class of trap as `customElements` above, found the same way — by running the pipeline
+// rather than by reading. Svelte's `event()` (dom/elements/events.js) ends its teardown check with
+// a BARE `dom instanceof HTMLMediaElement`, no `typeof` guard, so an undeclared global throws
+// ReferenceError instead of yielding `undefined`. It is reached by every `on<Name>={fn}` an app
+// writes on a bare tag, which is why nothing hit it while every handler went through the `p` bag.
+// Nothing of ours ever derives from it, so an empty class is enough:
+// `instanceof` only has to answer false.
+class FakeHTMLMediaElement {
+}
 let previous;
 export function patchGlobals() {
     if (previous !== undefined)
@@ -68,6 +92,7 @@ export function patchGlobals() {
         DocumentFragment: g.DocumentFragment,
         document: g.document,
         customElements: g.customElements,
+        HTMLMediaElement: g.HTMLMediaElement,
     };
     g.Node = ShimNode;
     // ShimElementBase, NOT ShimElement: `get_setters` stops AT `Element.prototype`, so pointing this
@@ -83,6 +108,7 @@ export function patchGlobals() {
     g.DocumentFragment = ShimDocumentFragment;
     g.document = getShimDocument();
     g.customElements = FAKE_CUSTOM_ELEMENT_REGISTRY;
+    g.HTMLMediaElement = FakeHTMLMediaElement;
     dlog('svelte dom-shim: patchGlobals installed');
 }
 export function restoreGlobals() {

package/build/dom-shim/shim-node.d.ts

@@ -3,6 +3,10 @@ type IDocumentLike = {
     createTextNode(value: string): ShimNode;
 };
 export declare function registerShimDocumentFactory(factory: () => IDocumentLike): void;
+export declare function takeShimScanStats(): {
+    calls: number;
+    scanned: number;
+};
 export declare abstract class ShimNode {
     parent: ShimNode | null;
     children: ShimNode[];
@@ -25,6 +29,8 @@ export declare abstract class ShimNode {
     remove(): void;
     removeChild<T extends ShimNode>(child: T): T;
     set textContent(value: string);
+    private indexNearEnd;
+    private scannedIndexOf;
     private insertOne;
 }
 export {};

package/build/dom-shim/shim-node.js

@@ -25,6 +25,31 @@ function shimDocument() {
     }
     return documentFactory();
 }
+// How many insertBefore ref lookups fell through `indexNearEnd`'s bounded window into the full,
+// unbounded `children.indexOf` scan, and how much of the array each one walked. Read-and-zeroed
+// through `takeShimScanStats`, same shape as `core/engine/src/node.ts`'s `propStats`. This is the
+// JS-side twin of a question F-80 already answered for the engine's own `OP_INSERT_BEFORE`
+// (`std::find` over `siblings`, exonerated as too small): before `indexNearEnd` existed, Svelte's
+// OWN reconciler paid the identical linear scan a second time, one layer up, on every keyed
+// `{#each}` append — measured at 1.5M comparisons for a 1 000-row Append onto 1 000 standing
+// (`each-append-scan-cost.probe.test.ts`). A zero reading here now means every ref this run
+// needed was found in the tail window; a nonzero one means something inserts against a ref
+// further from the end than `TAIL_SCAN_WINDOW` covers, which is real work this counter still
+// prices honestly rather than hiding behind the fast path.
+const shimScanStats = { calls: 0, scanned: 0 };
+// Covers the measured case (a trailing block/component boundary anchor, one small constant hop
+// from the true end) with room to spare, without making the fallback-miss case pay a meaningfully
+// bigger constant before it gives up and scans properly.
+const TAIL_SCAN_WINDOW = 8;
+export function takeShimScanStats() {
+    const snapshot = {
+        calls: shimScanStats.calls,
+        scanned: shimScanStats.scanned,
+    };
+    shimScanStats.calls = 0;
+    shimScanStats.scanned = 0;
+    return snapshot;
+}
 export class ShimNode {
     parent = null;
     children = [];
@@ -131,6 +156,28 @@ export class ShimNode {
             this.appendChild(shimDocument().createTextNode(value));
         }
     }
+    // Bounded backward scan, O(TAIL_SCAN_WINDOW) not O(children.length). Covers the case that
+    // dominates a real Append: a keyed `{#each}` growing at the tail inserts every new row via
+    // `newRow.before(ref)` where `ref` is the block's own closing boundary anchor — measured
+    // (`each-append-scan-cost.probe.test.ts`) sitting a SMALL, constant distance from the true end
+    // (one extra trailing anchor from the component's own root fragment in the measured case, not
+    // necessarily always exactly one — hence a window, not a hardcoded offset). Returns `undefined`
+    // on a miss so the caller falls back to the full, always-correct scan; this never changes the
+    // result, only how cheaply the common case finds it.
+    indexNearEnd(ref) {
+        const { children } = this;
+        const start = Math.max(0, children.length - TAIL_SCAN_WINDOW);
+        for (let i = children.length - 1; i >= start; i -= 1) {
+            if (children[i] === ref)
+                return i;
+        }
+        return undefined;
+    }
+    scannedIndexOf(ref) {
+        shimScanStats.calls += 1;
+        shimScanStats.scanned += this.children.length;
+        return this.children.indexOf(ref);
+    }
     insertOne(node, ref) {
         detachFromParent(node);
         node.parent = this;
@@ -138,7 +185,7 @@ export class ShimNode {
             this.children.push(node);
         }
         else {
-            const index = this.children.indexOf(ref);
+            const index = this.indexNearEnd(ref) ?? this.scannedIndexOf(ref);
             this.children.splice(index < 0 ? this.children.length : index, 0, node);
         }
         if (this.engineNode !== undefined && this.surface !== undefined) {

package/build/dom-shim/style-cache.d.ts

@@ -0,0 +1 @@
+export declare function discoverStyleCacheKey(): symbol;

package/build/dom-shim/style-cache.js

@@ -0,0 +1,27 @@
+// Where a `style={…}` attribute really goes, and why the shim cannot read it off `cssText`.
+//
+// Every tag name takes the same path: the compiler emits `$.set_style(node, value)` for `style`,
+// on a short tag and a hyphenated one alike. `set_style` then STRINGIFIES —
+// `to_style(value, undefined)` is `String(value)` — so a React Native style object arrives at
+// `dom.style.cssText` as the literal `"[object Object]"`. Nothing downstream can recover it.
+//
+// One line later `set_style` writes the ORIGINAL value onto the element under a module-private
+// `Symbol('style')` (svelte's `internal/client/constants.js`), which it also reads back as the
+// change guard. That symbol is the only surviving copy, so intercepting it is the only way a
+// bare `<view style={obj}>` reaches `routeProp`.
+//
+// The symbol is not exported, so it is DISCOVERED by running svelte's own `set_style` against a
+// probe and reading the one own symbol it leaves behind — once per process, never per node. A
+// version that changes the shape fails loudly here rather than silently dropping every style.
+import { set_style } from 'svelte/internal/client';
+export function discoverStyleCacheKey() {
+    const probe = { style: { cssText: '' } };
+    // A non-null string: `to_style` returns it unchanged, so the probe stays on the assignment
+    // branch and never reaches `removeAttribute`, which it does not implement.
+    set_style(probe, 'probe');
+    const symbols = Object.getOwnPropertySymbols(probe);
+    if (symbols.length !== 1)
+        throw new Error(`svelte's set_style left ${symbols.length} own symbols on a probe; ` +
+            'the style-cache key cannot be identified and `style` would be dropped');
+    return symbols[0];
+}

package/build/dom-shim/text.js

@@ -16,7 +16,7 @@
 // Fabric (the reason Vue's renderer maps it to an anchor rather than an empty text); and a raw
 // text child of a non-Text parent is the invalid "text outside <Text>" shape. Found by
 // native-node-parity.test.ts, which diffs committed native trees against the Vue adapter.
-import { appendChild as engineAppendChild, createAnchor, createRawText, insertBefore as engineInsertBefore, isAnchor, removeChild as engineRemoveChild, setText, } from '@symbiote-native/engine';
+import { isTextContainer, appendChild as engineAppendChild, createAnchor, createRawText, insertBefore as engineInsertBefore, isAnchor, removeChild as engineRemoveChild, setText, } from '@symbiote-native/engine';
 import { ShimNode } from './shim-node.js';
 // Deliberately WIDER than Svelte's own whitespace class. `svelte/src/compiler/phases/patterns.js`
 // uses /[^ \t\r\n]/ and says why: "Not \S because that also removes explicit whitespace defined
@@ -36,8 +36,8 @@ const WHITESPACE_ONLY = /^[\s\u200b-\u200d\ufeff]+$/;
 // The PARENT is what makes this exact rather than a heuristic. Measured on svelte 5.56.8, a
 // stray gap and an {#each} text placeholder are the same ' ' string in the from_tree template:
 //
-//   stray gap    ['symbiote-view', null, [...], ' ', [...]]   parent takes no raw text -> drop
-//   placeholder  ['symbiote-text', null, ' ']                 parent IS a <Text>       -> keep
+//   stray gap    ['view', null, [...], ' ', [...]]   parent takes no raw text -> drop
+//   placeholder  ['text', null, ' ']                 parent IS a <Text>       -> keep
 //
 // So `<Text><Text>a</Text> <Text>b</Text></Text>` keeps its separator, correctly — there the
 // space really is a word boundary. This also covers the one shape the source preprocessor
@@ -49,7 +49,8 @@ const WHITESPACE_ONLY = /^[\s\u200b-\u200d\ufeff]+$/;
 function isFormattingWhitespace(value, parent) {
     if (!WHITESPACE_ONLY.test(value))
         return false;
-    return parent?.engineNode?.isText !== true;
+    const engineNode = parent?.engineNode;
+    return engineNode === undefined || !isTextContainer(engineNode);
 }
 export class ShimText extends ShimNode {
     value;

package/build/host-instance.d.ts

@@ -1,5 +1,4 @@
 import { type IHostInstance } from '@symbiote-native/engine';
-import type { ShimElement } from './dom-shim';
 export type { IHostInstance } from '@symbiote-native/engine';
-export declare function hostInstance(shim: ShimElement | null | undefined): IHostInstance | undefined;
-export declare function findNodeHandle(componentOrHandle: ShimElement | number | null | undefined): number | null;
+export declare function hostInstance(shim: unknown): IHostInstance | undefined;
+export declare function findNodeHandle(componentOrHandle: unknown): number | null;

package/build/host-instance.js

@@ -9,7 +9,7 @@
 // RN's own findNodeHandle has). The node -> tag resolution itself belongs to the engine
 // (getNativeTag, keyed on the raw node in the commit mirror); this only adapts the
 // Svelte-shaped input (a ShimElement) onto it.
-import { getNativeTag, isSymbioteNode, toPublicInstance, dlog, } from '@symbiote-native/engine';
+import { componentOf, getNativeTag, isSymbioteNode, toPublicInstance, dlog, } from '@symbiote-native/engine';
 // `engineNode` alone does NOT identify a ShimElement: it is declared on the shared ShimNode base
 // (dom-shim/shim-node.ts), so a ShimText / ShimComment / ShimDocumentFragment satisfies it too,
 // and none of those is a host ref an interop library can hand back. `tagName` is ShimElement's
@@ -26,8 +26,14 @@ function isShimElement(value) {
 // the toPublicInstance call below is the identity; this helper exists only to give app code a correctly
 // TYPED accessor off the SHIM value (`ShimElement`) instead of the bare `.engineNode` field,
 // with no `as` cast at the call site.
+// `unknown` rather than `ShimElement`, and the guard is what makes that sound. svelte2tsx bakes a
+// `bind:this` return type out of `lib.dom`'s tag maps — an SVG element type for `view`/`text`/
+// `image`/`switch`, `any` for the other seventeen — and neither map accepts augmentation
+// (`src/intrinsic-elements.ts` records the measurement). So an app CANNOT declare its ref as
+// `ShimElement` without a cast, and this is the accessor that exists to keep casts out of app
+// code. Declaring the parameter `unknown` moves the narrowing where it can actually be checked.
 export function hostInstance(shim) {
-    if (shim === null || shim === undefined)
+    if (!isShimElement(shim))
         return undefined;
     const node = shim.engineNode;
     return node !== undefined && isSymbioteNode(node)
@@ -44,7 +50,7 @@ export function findNodeHandle(componentOrHandle) {
     const node = componentOrHandle.engineNode;
     if (node !== undefined && isSymbioteNode(node)) {
         const tag = getNativeTag(node) ?? null;
-        dlog(`findNodeHandle: component=${node.component} tag=${tag}`);
+        dlog(`findNodeHandle: component=${componentOf(node)} tag=${tag}`);
         return tag;
     }
     dlog('findNodeHandle: hostShim not live yet (engineNode undefined)');