@symbiote-native/svelte 0.2.1 → 1.0.0

package/build/create-portal/index.d.ts

@@ -0,0 +1,22 @@
+import type { Component, Snippet } from 'svelte';
+import { SymbioteSurface, type ISymbioteNode } from '@symbiote-native/engine';
+import { ShimElement } from '../dom-shim';
+/**
+ * Where portaled content lands. React's `IPortalContainer` carries two members
+ * (`ISymbioteNode | SymbioteSurface`); this carries three, because Svelte's OWN handle on a
+ * mounted host node is the `ShimElement` a `bind:this` / `{@attach}` hands back — the same
+ * capability, one wrapper further out. `ISymbioteNode` stays accepted so a raw engine node
+ * (what `hostInstance()` returns, and what a third-party native-view package holds) is a target
+ * here exactly as it is on React.
+ */
+export type IPortalTarget = ShimElement | ISymbioteNode | SymbioteSurface;
+export interface IPortalProps {
+    /**
+     * An already-mounted node in this surface, or the surface itself. Reactive: pointing it at a
+     * different target MOVES the content, it does not re-create it.
+     */
+    mount: IPortalTarget;
+    /** The content to relocate. `<Portal mount={x}>…</Portal>` fills this in implicitly. */
+    children: Snippet;
+}
+export declare const Portal: Component<IPortalProps>;

package/build/create-portal/index.js

@@ -0,0 +1,160 @@
+// Portal — the Svelte adapter's same-surface portal: the twin of React's `createPortal`
+// (adapters/react/src/create-portal/index.ts), Solid's `<Portal mount={…}>`
+// (adapters/solid/src/create-portal/index.tsx) and Angular's PortalDirective/PortalOutletDirective
+// pair. This adapter shipped `createTunnel` and no portal in any spelling until 2026-08-20; the
+// two do NOT overlap (see the table at the bottom of this header), so the tunnel was never a
+// substitute.
+//
+// WHY IT IS A COMPONENT (`<Portal mount={…}>`) AND NOT A CALL (`createPortal(content, target)`).
+// NOT for Solid's reason. Solid had to avoid the call form because Solid evaluates JSX eagerly at
+// the position it is written, so a call would BUILD the content before anything could relocate it.
+// That argument does not transfer: probed against the installed svelte 5.56.8, `{#snippet
+// children()}…{/snippet}` compiles to `const children = ($$anchor) => {…}` — a lazy closure that
+// runs only when something calls it with an anchor, exactly like React's `children`. Svelte's
+// reason is simpler and harder: **Svelte has no expression form for markup at all.** There is no
+// `h()`, no JSX value; markup exists only inside a template, and the only way to hand a block of
+// template to something else is a snippet prop. A `createPortal(snippet, target)` called from
+// `<script>` would still have to be given a snippet — and would then need to invent its own
+// lifetime, teardown and reactive ownership, all of which a component gets from the framework.
+// `<Portal mount={node}>` is also the shape solid-js/web ships and the shape every community
+// Svelte portal action ends up approximating, so a Svelte author already reads it.
+//
+// WHY THE BODY IS HAND-WRITTEN TS AND NOT A `.svelte` FILE — forced, not preferred. A `.svelte`
+// template cannot express this component at all: `{@render children()}` always renders at the
+// component's OWN anchor position, and the template language has no "render into node X" form.
+// Choosing the destination means calling the snippet with an anchor of our own, which is
+// precisely what the compiler's own `{@render}` does. Probed:
+//
+//     {@render children()}   ->   $.snippet(node, () => $$props.children)
+//
+// So this file makes the SAME call the compiler emits and substitutes ONE argument: the anchor.
+// The precedent for a hand-written component body in this adapter is
+// modules/animated/create-animated-component.ts (see its header, and svelte-internal-client.d.ts
+// for the narrowed declarations); the adapter is by design coupled to Svelte's private internals
+// — the whole DOM shim is (svelte-adapter-dom-shim skill §0). A welcome side effect: `Portal` is
+// plain TS, so it imports from ordinary TS and from vitest with no Svelte plugin in the way.
+//
+// SCOPE — same-surface only, matching React's boundary exactly, neither widened nor narrowed.
+// `mount` must be an already-mounted node WITHIN THE SAME SURFACE as the Portal's call site
+// (typically a host element you hold via `bind:this` or `{@attach}`), or that surface itself. It
+// is not a route into a second, independently mount()ed surface: React's `resetAfterCommit` fires
+// only for the primary root's own container, and here the equivalent is that a foreign surface
+// would never be told to re-commit — a silent no-paint, not a crash. Cross-surface content
+// sharing is a different mechanism: `createTunnel` (../create-tunnel).
+//
+// PORTAL vs TUNNEL — every row is pinned by a test, in this file's suite and the tunnel's:
+//
+//   Reach            | same surface only          | any surface, incl. a separately mount()ed one
+//   Target must      | no — any mounted node,     | yes — a <TunnelOut/> must be rendered there
+//   cooperate        |   incl. one you hold a ref |
+//   Placement        | the target's exact slot,   | one collection point, registration order
+//                    |   interleaved with its own |
+//                    |   children                 |
+//   Content's        | the CALL SITE (getContext  | the OUT SITE (getContext resolves there)
+//   reactive owner   |   resolves there)          |
+//   Node identity    | nodes are MOVED (the old   | content is re-created per TunnelOut
+//                    |   parent empties)          |
+import { pop, push, snippet, user_effect } from 'svelte/internal/client';
+import { appendChild as engineAppendChild, removeChild as engineRemoveChild, dlog, isSymbioteNode, SymbioteSurface, } from '@symbiote-native/engine';
+import { ShimComment, ShimElement, ShimNode } from '../dom-shim/index.js';
+// The Svelte flavour of React's `isSymbioteNode` guard, and it needs its own wording: React tells
+// the caller to check for a forgotten `.current`, which does not exist here. A Svelte host ref is
+// populated by an EFFECT, so it is still `null` while the template that reads it first runs —
+// gating the Portal behind `{#if target}` is the idiomatic fix (the twin of React's callback-ref
+// gotcha and Solid's `<Show when={…}>`).
+function assertPortalTarget(target) {
+    if (target instanceof ShimElement ||
+        target instanceof SymbioteSurface ||
+        isSymbioteNode(target)) {
+        return target;
+    }
+    throw new Error('Portal `mount` must be an already-mounted host node (a `bind:this` / `{@attach}` ref off a rendered component) or a surface — got something else. Is the ref still null because the template ran before the effect that fills it (gate the Portal behind `{#if target}`), or did you pass a CSS-selector-style string?');
+}
+function targetLabel(target) {
+    if (target instanceof SymbioteSurface)
+        return `surface#${target.rootTag}`;
+    if (target instanceof ShimElement)
+        return target.tagName;
+    return target.component;
+}
+// Attach the fragment host under `target` and hand back the matching detach. Three branches
+// because the three target kinds sit at different layers:
+//
+//  * ShimElement — attach in the SHIM tree and let it do the rest. Liveness is lazy there
+//    (shim-node.ts's makeLive), so this is the one branch that works whether or not the target
+//    has reached its first commit yet, and the host's surface arrives with it.
+//  * SymbioteSurface — no shim node exists above it, so the host is made live against the
+//    surface directly and appended as a top-level child, the same branch React's
+//    `appendChildToContainer` takes for `isSurfaceContainer`.
+//  * ISymbioteNode — a raw engine node carries no surface back-pointer, so the surface comes
+//    from the Portal's OWN call-site anchor. That is correct by construction for the only
+//    supported case: same-surface targets.
+function attachHost(target, host, callSiteAnchor) {
+    if (target instanceof ShimElement) {
+        target.appendChild(host);
+        return () => {
+            target.removeChild(host);
+        };
+    }
+    if (target instanceof SymbioteSurface) {
+        const node = host.makeLive(target);
+        target.appendChild(node);
+        target.requestCommit();
+        return () => {
+            target.removeChild(node);
+            target.requestCommit();
+        };
+    }
+    const surface = callSiteAnchor?.surface;
+    if (surface === undefined) {
+        throw new Error('Portal `mount` was given a raw engine node, but the Portal itself is not mounted on a surface yet, so there is nothing to commit it to. Pass the `bind:this` / `{@attach}` value itself (a host element) rather than unwrapping it, or pass the surface.');
+    }
+    const node = host.makeLive(surface);
+    engineAppendChild(target, node);
+    surface.requestCommit();
+    return () => {
+        engineRemoveChild(target, node);
+        surface.requestCommit();
+    };
+}
+export const Portal = function Portal(internals, props) {
+    // The compiled twin of a component's own `$props()` scope. Without it `user_effect` below is
+    // created immediately instead of being deferred to mount, and would run before the call site
+    // has finished rendering — the same reason create-animated-component.ts opens one.
+    push(props, true);
+    // ONE engine anchor per Portal instance, as a fragment host. It is a real retained node, so
+    // the content has a stable exclusive parent to be reconciled under, and the commit walk
+    // FLATTENS an anchor's children into its parent (renderableChildren, core/engine/src/commit.ts)
+    // so the anchor itself never paints. That is what keeps portaled content a DIRECT Fabric child
+    // of the target — matching React's createPortal, and unlike a DOM portal, which always leaves
+    // its container element in the tree.
+    //
+    // It is also what makes relocation and teardown one call each: the whole subtree travels with
+    // the anchor, so nothing has to track which nodes the snippet produced.
+    const host = new ShimComment('symbiote-portal');
+    // The anchor `$.snippet` renders BEFORE — a child of the host, so the content lands inside the
+    // host rather than wherever the host currently sits. Also an engine anchor: flattened away too.
+    const renderAnchor = new ShimComment('');
+    host.appendChild(renderAnchor);
+    // A component's first argument IS its anchor node, which in this adapter is a shim node — so
+    // the Portal can read its own surface off it. Guarded rather than cast: `ComponentInternals` is
+    // an opaque branded type, and a future Svelte could hand something else.
+    const callSiteAnchor = internals instanceof ShimNode ? internals : undefined;
+    // Render FIRST, relocate second — that order is the whole reason context, error boundaries and
+    // ownership resolve from the call site: the snippet runs inside THIS component's context, and
+    // `<Portal>` is written at the call site. Only host nodes move afterwards.
+    snippet(renderAnchor, () => props.children);
+    // `props.mount` is read inside the effect, not destructured at the top: a prop arrives as a
+    // getter (probed — the compiler emits `get mount() { return $.get(x); }`), so reading it here
+    // would freeze the first target. Returning the detach as the effect's cleanup covers both
+    // cases at once — a `mount` change (fired before the effect re-attaches elsewhere) and the
+    // Portal's own teardown.
+    user_effect(() => {
+        const target = assertPortalTarget(props.mount);
+        dlog(`svelte portal -> ${targetLabel(target)}`);
+        return attachHost(target, host, callSiteAnchor);
+    });
+    // Nothing paints at the call site — React's createPortal returns a ReactPortal that renders
+    // nothing there for the same reason. A component's return value is its exports; there are none.
+    return pop({});
+};

package/build/descriptor-to-svelte.js

@@ -19,12 +19,12 @@
 // function's actual output changed shape, which this bridge's whole cost-free model assumes
 // never happens. If this ever fires for real, the render fn genuinely stopped being
 // shape-stable and needs its own fix, not a workaround here.
+import { createDescriptorShapeGuard } from '@symbiote-native/components';
 import { getShimDocument } from './dom-shim/index.js';
-function shapeChangedMessage(detail) {
-    return (`descriptorToSvelte: Descriptor shape changed between renders (${detail}) — a ` +
-        `render-*.ts fn is expected to produce a CONSTANT tree shape (svelte-adapter-dom-shim ` +
-        `skill §15/§19); only prop values may vary between calls.`);
-}
+// The predicates live in @symbiote-native/components, next to the Descriptor whose contract they
+// guard (skill §15/§19 for why this bridge depends on it at all). Solid's bridge had grown a
+// private copy of the same checks with different coverage; one owner ends that.
+const shape = createDescriptorShapeGuard('descriptorToSvelte');
 function buildChild(child) {
     const document = getShimDocument();
     if (typeof child === 'string') {
@@ -40,22 +40,17 @@ function buildChild(child) {
     return { kind: 'element', shim, children };
 }
 function syncChild(cached, child) {
-    if (typeof child === 'string') {
-        if (cached.kind !== 'text')
-            throw new Error(shapeChangedMessage('text/element'));
-        if (cached.shim.data !== child)
-            cached.shim.data = child;
+    if (cached.kind === 'text') {
+        const text = shape.asText(child);
+        if (cached.shim.data !== text)
+            cached.shim.data = text;
         return;
     }
-    if (cached.kind !== 'element' || cached.shim.tagName !== child.type) {
-        const was = cached.kind === 'element' ? cached.shim.tagName : 'text';
-        throw new Error(shapeChangedMessage(`${was} -> ${child.type}`));
-    }
-    cached.shim.p = child.props;
-    if (cached.children.length !== child.children.length) {
-        throw new Error(shapeChangedMessage('child count'));
-    }
-    cached.children.forEach((c, index) => syncChild(c, child.children[index]));
+    const element = shape.asElement(child);
+    shape.assertType(cached.shim.tagName, element.type);
+    cached.shim.p = element.props;
+    shape.assertChildCount(cached.children.length, element.children.length);
+    cached.children.forEach((c, index) => syncChild(c, element.children[index]));
 }
 // Materializes `descriptor.children` onto an already-live `parent` ONCE, then reuses the same
 // shim nodes by position on every `update()`. `parent` is expected to already be live (has an
@@ -70,8 +65,7 @@ export function mountDescriptorChildren(parent, children) {
     });
     return {
         update(next) {
-            if (cached.length !== next.length)
-                throw new Error(shapeChangedMessage('root child count'));
+            shape.assertChildCount(cached.length, next.length);
             cached.forEach((c, index) => syncChild(c, next[index]));
         },
     };

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

@@ -1,14 +1,20 @@
 import { type ISymbioteNode } from '@symbiote-native/engine';
 import { ShimNode } from './shim-node';
 export type IShimPropBag = Record<string, unknown>;
-export declare class ShimElement extends ShimNode {
+export declare abstract class ShimElementBase extends ShimNode {
+}
+export declare class ShimElement extends ShimElementBase {
     readonly tagName: string;
     readonly namespaceURI: string | undefined;
-    private readonly attributes;
-    private readonly domListeners;
+    private attributes;
+    private domListeners;
     private lastBag;
     constructor(tagName: string, namespaceURI?: string);
     get nodeName(): string;
+    private styleSlot;
+    get style(): {
+        cssText: string;
+    };
     get p(): IShimPropBag;
     set p(bag: IShimPropBag | undefined);
     setAttribute(name: string, value: string): void;

package/build/dom-shim/element.js

@@ -10,10 +10,15 @@
 // 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, isDebug, routeProp, setEventListener, toPublicInstance, } from '@symbiote-native/engine';
+import { createElement, dlog, routeProp, setEventListener, 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 { ShimNode } from './shim-node.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.
+const EMPTY_BAG = Object.freeze({});
 // Diagnostic-only: a process-wide sequence so every `set p` call across every shim element in a
 // log dump is individually orderable against AnimatedProps reconcile#N / AnimatedView reduced#N
 // / hostShim identity-change#N, to see which one is driving which.
@@ -21,12 +26,26 @@ let globalSetPSeq = 0;
 // `on<Name>` handlers ride inside the prop bag (idiomatic Svelte 5 callback props — see the
 // skill's §3g(c) "most of §5 collapses" note) — they are not addEventListener-style DOM
 // listeners, so they are diffed and routed exactly like any other bag key, through routeProp.
-export class ShimElement extends ShimNode {
+// An empty layer that exists to be what `globalThis.Element` points at, and it is load-bearing.
+// Svelte's `get_setters` (internal/client/dom/elements/attributes.js) walks from the ELEMENT
+// INSTANCE up and STOPS when it reaches `Element.prototype`. While `Element` was `ShimElement`
+// itself, the first prototype step was already the stop, so the walk collected nothing and `p` —
+// which lives on `ShimElement.prototype`, one step past it — was invisible. `set_attributes` then
+// fell through to `setAttribute`, which writes an inert Map, and every prop vanished with nothing
+// red. The rule is therefore that `Element` must be a proper ANCESTOR of the class owning the
+// setters, never that class: `.claude/rules/svelte-shim-element-global-must-be-an-ancestor.md`.
+export class ShimElementBase extends ShimNode {
+}
+export class ShimElement extends ShimElementBase {
     tagName;
     namespaceURI;
-    attributes = new Map();
-    domListeners = new Map();
-    lastBag = {};
+    // 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;
+    lastBag = EMPTY_BAG;
     constructor(tagName, namespaceURI) {
         super();
         this.tagName = tagName;
@@ -35,66 +54,85 @@ export class ShimElement extends ShimNode {
     get nodeName() {
         return this.tagName;
     }
+    // `set_style` writes `dom.style.cssText`, so a shim with no `.style` THROWS rather than
+    // 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;
+    get style() {
+        return (this.styleSlot ??= { cssText: '' });
+    }
     // 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.
     get p() {
         return this.lastBag;
     }
     set p(bag) {
-        const next = normalizeBagClasses(bag ?? {});
+        // 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 ?? {}));
         const prev = this.lastBag;
         this.lastBag = next;
-        const changedKeys = diffKeys(prev, next);
-        dlog(`ShimElement set-p#${++globalSetPSeq} tag=${this.tagName} live=${this.engineNode !== undefined} ` +
-            `changedKeys=${changedKeys.join(',')}`);
+        // THUNK, not a string (see debug.ts's header): this setter runs once per element per create
+        // and the changed-key list is diagnostic only. Built eagerly it cost a Set, two key arrays, a
+        // join and a template literal on every one of 9 002 elements, with logging off.
+        dlog(() => `ShimElement set-p#${++globalSetPSeq} tag=${this.tagName} live=${this.engineNode !== undefined} ` +
+            `changedKeys=${diffKeys(prev, next).join(',')}`);
         if (this.engineNode === undefined)
             return; // not live yet — onMadeLive() replays `next` in full
         applyBagDiff(this.engineNode, prev, next);
         this.surface?.requestCommit();
     }
     setAttribute(name, value) {
-        this.attributes.set(name, value);
+        (this.attributes ??= new Map()).set(name, value);
     }
     getAttribute(name) {
-        return this.attributes.get(name) ?? null;
+        return this.attributes?.get(name) ?? null;
     }
     removeAttribute(name) {
-        this.attributes.delete(name);
+        this.attributes?.delete(name);
     }
     addEventListener(name, handler) {
-        this.domListeners.set(name, handler);
+        (this.domListeners ??= new Map()).set(name, handler);
         if (this.engineNode !== undefined)
             setEventListener(this.engineNode, name, handler);
     }
     removeEventListener(name) {
-        this.domListeners.delete(name);
+        this.domListeners?.delete(name);
         if (this.engineNode !== undefined)
             setEventListener(this.engineNode, name, undefined);
     }
     cloneNode(deep) {
         const clone = new ShimElement(this.tagName, this.namespaceURI);
-        for (const [key, value] of this.attributes)
-            clone.attributes.set(key, value);
+        if (this.attributes !== undefined)
+            clone.attributes = new Map(this.attributes);
         if (deep === true) {
             for (const child of this.children)
                 clone.appendChild(child.cloneNode(true));
         }
         return clone;
     }
-    // toPublicInstance grafts measure/measureInWindow/measureLayout/setNativeProps/focus/blur
-    // onto the node — the imperative API a `bind:this` host ref hands back, the same augmentation
-    // Vue's renderer applies at its own commit point (renderer/index.ts) and React gets from
-    // getPublicInstance. Mutates in place and returns the SAME node, so this is a safe drop-in for
-    // the previously-bare createElement() call.
+    // measure/measureInWindow/measureLayout/setNativeProps/focus/blur — the imperative API a
+    // `bind:this` host ref hands back — ride on the engine node's prototype, so toPublicInstance is
+    // the identity and this reads the same as Vue's renderer (renderer/index.ts) and React's
+    // getPublicInstance.
     createEngineNode() {
         const descriptor = descriptorFor(this.tagName);
-        return toPublicInstance(createElement(descriptor.component, descriptor.isText));
+        // 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
+        // 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));
     }
     onMadeLive() {
         const engineNode = this.engineNode;
         if (engineNode === undefined)
             return;
-        applyBagDiff(engineNode, {}, this.lastBag);
+        applyBagDiff(engineNode, EMPTY_BAG, this.lastBag);
+        if (this.domListeners === undefined)
+            return;
         for (const [name, handler] of this.domListeners)
             setEventListener(engineNode, name, handler);
     }
@@ -120,11 +158,25 @@ function normalizeBagClasses(bag) {
     }
     return next;
 }
+// Diagnostic only — the one caller is the `dlog` thunk above. The allocation-free twin below is
+// what the hot path uses; keep them in step.
 function diffKeys(prev, next) {
     const keys = new Set([...Object.keys(prev), ...Object.keys(next)]);
     return [...keys].filter(key => prev[key] !== next[key]);
 }
+// Deliberately NOT `for (const key of diffKeys(...))`: that materialized a Set, two key arrays,
+// a spread and a filtered array per element. Two direct passes route exactly the same keys —
+// changed-or-added from `next`, then dropped keys from `prev` as `undefined`, which is what
+// `next[key]` evaluated to in the old shape.
 function applyBagDiff(engineNode, prev, next) {
-    for (const key of diffKeys(prev, next))
-        routeProp(engineNode, key, next[key]);
+    for (const key of Object.keys(next)) {
+        if (prev[key] !== next[key])
+            routeProp(engineNode, key, next[key]);
+    }
+    if (prev === EMPTY_BAG)
+        return;
+    for (const key of Object.keys(prev)) {
+        if (!(key in next))
+            routeProp(engineNode, key, undefined);
+    }
 }

package/build/dom-shim/fold-host-bag.d.ts

@@ -0,0 +1 @@
+export { foldHostBag, FOLD_PLAN_BY_TAG as BY_TAG, type IHostBag, } from '@symbiote-native/components/fold-host-bag';

package/build/dom-shim/fold-host-bag.js

@@ -0,0 +1,7 @@
+// Moved to `@symbiote-native/components/fold-host-bag` (2026-09-01) and kept here as a re-export.
+//
+// It left this adapter the moment a SECOND adapter needed it: React's wrappers are being replaced
+// by bare intrinsic tags, and a bare tag has no wrapper to fold in — the same "third path" this
+// file was written for, arriving in an adapter that has no lowering transform either. A per-adapter
+// copy of a fold driven by a shared spec is the duplication `<adapters_stay_thin>` exists to stop.
+export { foldHostBag, FOLD_PLAN_BY_TAG as BY_TAG, } from '@symbiote-native/components/fold-host-bag';

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

@@ -1,5 +1,6 @@
 export { patchGlobals, restoreGlobals } from './patch-globals';
 export { ShimElement } from './element';
+export { ShimComment } from './comment';
 export { ShimNode } from './shim-node';
 export { ShimText } from './text';
 export { getShimDocument } from './document';

package/build/dom-shim/index.js

@@ -2,6 +2,9 @@
 // never sees a shim class or a `symbiote-*` tag; see the adapter's own index.ts).
 export { patchGlobals, restoreGlobals } from './patch-globals.js';
 export { ShimElement } from './element.js';
+// ShimComment is the anchor path (engine createAnchor, flattened away by the commit walk) — the
+// only shim node create-portal can use as a non-painting fragment host.
+export { ShimComment } from './comment.js';
 export { ShimNode } from './shim-node.js';
 export { ShimText } from './text.js';
 export { getShimDocument } from './document.js';

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

@@ -24,7 +24,7 @@
 //
 // `customElements` IS patched, unlike the three above — see its own comment below.
 import { dlog } from '@symbiote-native/engine';
-import { ShimElement } from './element.js';
+import { ShimElement, ShimElementBase } from './element.js';
 import { ShimText } from './text.js';
 import { ShimComment } from './comment.js';
 import { ShimDocumentFragment } from './document-fragment.js';
@@ -70,7 +70,9 @@ export function patchGlobals() {
         customElements: g.customElements,
     };
     g.Node = ShimNode;
-    g.Element = ShimElement;
+    // ShimElementBase, NOT ShimElement: `get_setters` stops AT `Element.prototype`, so pointing this
+    // at the class that owns `p` hides `p` from every `set_attributes` caller. See element.ts.
+    g.Element = ShimElementBase;
     // Svelte's mandatory paths never distinguish HTMLElement/SVGElement from Element (we have
     // no `<svg>` primitives), so both alias the same class — real, extensible prototypes either
     // way, which is all `init_operations()` requires (§3a).

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

@@ -69,12 +69,23 @@ export class ShimNode {
         for (const node of nodes)
             this.appendChild(node);
     }
+    // The fragment branch is the rare one — every ordinary insert is a single node — but
+    // `normalizeInsertable` allocated a one-element array for it regardless, 23 006 of them on a
+    // 1 000-row create. Test the flag first and hand the node straight to insertOne.
     appendChild(node) {
+        if (!node.isDocumentFragment) {
+            this.insertOne(node, null);
+            return node;
+        }
         for (const single of normalizeInsertable(node))
             this.insertOne(single, null);
         return node;
     }
     insertBefore(node, ref) {
+        if (!node.isDocumentFragment) {
+            this.insertOne(node, ref);
+            return node;
+        }
         for (const single of normalizeInsertable(node))
             this.insertOne(single, ref);
         return node;

package/build/dom-shim/text.js

@@ -18,6 +18,39 @@
 // 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 { 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
+// through things like ` `". For Svelte the character IS the discriminator, so it must keep
+// an author's deliberate nbsp. For us the PARENT is the discriminator, and it has already proved
+// the node is unrenderable - a raw text under a non-text parent cannot paint whatever character
+// it holds. So ` `, ` `, \f, \v, U+2028, U+3000 and the zero-width family (which `\s`
+// misses) all drop here, while a deliberate nbsp INSIDE a <Text> is kept by the parent check.
+// Measured: each of these arrives as its own text node in the from_tree template.
+const WHITESPACE_ONLY = /^[\s\u200b-\u200d\ufeff]+$/;
+// Whitespace-only text under a parent that cannot hold raw text is FORMATTING, not content: the
+// gap Svelte leaves between two sibling tags written on separate lines. Svelte collapses every
+// such run to a single ' ' but never deletes it — in the DOM that space separates inline words
+// and only CSS decides whether it paints. Fabric has no such layer, so a raw text outside a
+// <Text> is simply invalid: the same invariant the engine enforces at commit time.
+//
+// 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
+//
+// 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
+// admits it cannot catch (two siblings, one line, no newline): by here Svelte has already
+// normalized that form to the very same single space.
+//
+// makeLive() binds a parent before its children, so the parent's engine node is always present
+// by the time this runs; a fragment is unwrapped into the real parent before insertion.
+function isFormattingWhitespace(value, parent) {
+    if (!WHITESPACE_ONLY.test(value))
+        return false;
+    return parent?.engineNode?.isText !== true;
+}
 export class ShimText extends ShimNode {
     value;
     constructor(value) {
@@ -92,6 +125,10 @@ export class ShimText extends ShimNode {
         return new ShimText(this.value);
     }
     createEngineNode() {
-        return this.value === '' ? createAnchor() : createRawText(this.value);
+        if (this.value === '')
+            return createAnchor();
+        if (isFormattingWhitespace(this.value, this.parent))
+            return createAnchor();
+        return createRawText(this.value);
     }
 }

package/build/host-instance.js

@@ -15,20 +15,24 @@ import { getNativeTag, isSymbioteNode, toPublicInstance, dlog, } from '@symbiote
 // and none of those is a host ref an interop library can hand back. `tagName` is ShimElement's
 // own field, so checking it makes the predicate mean what its name says.
 function isShimElement(value) {
-    return typeof value === 'object' && value !== null && 'engineNode' in value && 'tagName' in value;
+    return (typeof value === 'object' &&
+        value !== null &&
+        'engineNode' in value &&
+        'tagName' in value);
 }
 // The typed imperative handle (measure/measureInWindow/measureLayout/setNativeProps/focus/blur)
 // a `bind:this` host ref carries — the Svelte twin of a React `ref.current`/Vue template ref
-// already being an `IHostInstance`. `dom-shim/element.ts`'s `createEngineNode()` grafts
-// toPublicInstance onto every host node AT CREATION, so this call is idempotent (its own
-// isHostInstance guard short-circuits); this helper exists only to give app code a correctly
+// already being an `IHostInstance`. Every engine node carries those methods on its prototype, so
+// 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.
 export function hostInstance(shim) {
     if (shim === null || shim === undefined)
         return undefined;
     const node = shim.engineNode;
-    return node !== undefined && isSymbioteNode(node) ? toPublicInstance(node) : undefined;
+    return node !== undefined && isSymbioteNode(node)
+        ? toPublicInstance(node)
+        : undefined;
 }
 export function findNodeHandle(componentOrHandle) {
     if (componentOrHandle === null || componentOrHandle === undefined)

package/build/index.d.ts

@@ -1,3 +1,4 @@
+import './register';
 export { mount, unmount } from './render';
 export { AppRegistry, setHostRegistrar } from './modules/app-registry';
 export type { IComponentProvider, IWrapperComponentProvider, IAppParameters, IRunnable, IHostRegistrar, IRegistry, IHeadlessTask, ITaskProvider, ITaskCanceller, ITaskCancelProvider, } from './modules/app-registry';
@@ -17,12 +18,14 @@ export type { IAccessibilityChangeEvent, IAccessibilityChangeEventName, IAccessi
 export { findNodeHandle, hostInstance } from './host-instance';
 export type { IHostInstance } from './host-instance';
 export type { ShimElement } from './dom-shim';
-export { createTunnel, TunnelIn, TunnelOut, type ITunnel } from './create-tunnel';
+export { createTunnel, TunnelIn, TunnelOut, type ITunnel, } from './create-tunnel';
+export { Portal, type IPortalProps, type IPortalTarget } from './create-portal';
 export { useWindowDimensions } from './runes/use-window-dimensions.svelte';
 export { useColorScheme } from './runes/use-color-scheme.svelte';
-export { innerWidth, innerHeight, outerWidth, outerHeight, devicePixelRatio } from './runes/window';
+export { innerWidth, innerHeight, outerWidth, outerHeight, devicePixelRatio, } from './runes/window';
 export { orientation, createWidthQuery } from './runes/media-query';
 export type { IOrientation, IWidthQueryBounds } from './runes/media-query';
 export type { IReactiveValue } from './runes/dimensions-value';
 export { normalizeSvelteClass, resolveSvelteClass, type ISvelteClassValue, type IClassMap, type IClassEntry, } from './class-value';
-export { Animated } from './modules/animated';
+export { Animated, createAnimatedComponent } from './modules/animated';
+export type { IAnimatedComponentProps } from './modules/animated';