@symbiote-native/svelte 0.2.1 → 0.3.0

package/build/components/virtualized-section-list/index.svelte

@@ -13,7 +13,11 @@
     ISection,
   } from './virtualized-section-list-props';
 
-  export type { IVirtualizedSectionListProps, IVirtualizedSectionListHandle, ISection };
+  export type {
+    IVirtualizedSectionListProps,
+    IVirtualizedSectionListHandle,
+    ISection,
+  };
 </script>
 
 <script lang="ts" generics="ItemT">
@@ -30,7 +34,10 @@
   import { Platform, dlog, type ISymbioteNode } from '@symbiote-native/engine';
   import VirtualizedList from '../virtualized-list/index.svelte';
   import { pickAccessibilityProps } from '../virtualized-list/virtualized-list-props';
-  import type { IVirtualizedListHandle, IScrollViewHandle } from '../virtualized-list/virtualized-list-props';
+  import type {
+    IVirtualizedListHandle,
+    IScrollViewHandle,
+  } from '../virtualized-list/virtualized-list-props';
   import type { IVirtualizedSectionListProps as IProps } from './virtualized-section-list-props';
   import { pickAttachmentProps } from '../../runes/attachments';
 
@@ -50,7 +57,11 @@
 
   // RN sticks section headers by default only on iOS; Android does not unless asked.
   const stickyHeaderIndices = $derived(
-    resolveStickySectionHeaders(props.stickySectionHeadersEnabled, headerIndices, Platform.OS),
+    resolveStickySectionHeaders(
+      props.stickySectionHeadersEnabled,
+      headerIndices,
+      Platform.OS,
+    ),
   );
   // DIAGNOSTIC (2026-08-13, tracking why stickyHeaderIndices comes back undefined on Android
   // despite the demo passing the bare `stickySectionHeadersEnabled` shorthand): the previous
@@ -78,11 +89,35 @@
   function getEntryCount(): number {
     return entries.length;
   }
-  function entryKeyExtractor(entry: ISectionEntry<ItemT>, index: number): string {
+  function entryKeyExtractor(
+    entry: ISectionEntry<ItemT>,
+    index: number,
+  ): string {
     return sectionEntryKey(entry, index, props.keyExtractor);
   }
 
-  function entrySeparatorProps(entryProps: ISeparatorProps<ISectionEntry<ItemT>>): ISeparatorProps<ItemT> {
+  // Hand the callback `sections`, not the entries: RN's inner VirtualizedList gets
+  // `data={this.props.sections}` (VirtualizedSectionList.js:216) while ours streams the FLATTENED
+  // entries, so the same user code would otherwise see a different argument here than on RN.
+  //
+  // UPSTREAM-DIVERGENCE(react-native): the flat INDEX matches RN's (two rows per section, header
+  // and footer) only while the `sectionSeparator` snippet is unset. With it, flattenSections emits
+  // an extra 'section-separator' row per boundary that RN renders inside the neighbouring cell, so
+  // indices shift by one per boundary from the second section on. Deliberate - that row is how this
+  // adapter paints the separator; a caller combining the two must account for it.
+  const entryItemLayout = $derived.by(() => {
+    const getItemLayout = props.getItemLayout;
+    if (getItemLayout === undefined) return undefined;
+    return (
+      _entries: unknown,
+      index: number,
+    ): { length: number; offset: number; index: number } =>
+      getItemLayout(props.sections, index);
+  });
+
+  function entrySeparatorProps(
+    entryProps: ISeparatorProps<ISectionEntry<ItemT>>,
+  ): ISeparatorProps<ItemT> {
     return {
       ...entryProps,
       leadingItem: unwrapEntryItem(entryProps.leadingItem),
@@ -100,9 +135,15 @@
     viewPosition?: number;
     animated?: boolean;
   }): void {
-    const flatIndex = scrollLocationToFlatIndex(headerIndices, params.sectionIndex, params.itemIndex);
+    const flatIndex = scrollLocationToFlatIndex(
+      headerIndices,
+      params.sectionIndex,
+      params.itemIndex,
+    );
     if (flatIndex === undefined) {
-      dlog(`VirtualizedSectionList scrollToLocation: section ${params.sectionIndex} out of range`);
+      dlog(
+        `VirtualizedSectionList scrollToLocation: section ${params.sectionIndex} out of range`,
+      );
       return;
     }
     dlog(
@@ -155,7 +196,12 @@
   {:else if entry.kind === 'section-separator'}
     {@render props.sectionSeparator?.()}
   {:else}
-    {@render props.item({ item: entry.item, index: entry.itemIndex, section: entry.section, separators })}
+    {@render props.item({
+      item: entry.item,
+      index: entry.itemIndex,
+      section: entry.section,
+      separators,
+    })}
   {/if}
 {/snippet}
 
@@ -176,7 +222,8 @@
   footer={props.footer}
   empty={props.empty}
   keyExtractor={entryKeyExtractor}
-  stickyHeaderIndices={stickyHeaderIndices}
+  getItemLayout={entryItemLayout}
+  {stickyHeaderIndices}
   inverted={props.inverted}
   extraData={props.extraData}
   onEndReached={props.onEndReached}

package/build/components/virtualized-section-list/index.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { IVirtualizedSectionListProps, IVirtualizedSectionListHandle, ISection } from './virtualized-section-list-props';
-export type { IVirtualizedSectionListProps, IVirtualizedSectionListHandle, ISection };
+export type { IVirtualizedSectionListProps, IVirtualizedSectionListHandle, ISection, };
 import { type ISymbioteNode } from '@symbiote-native/engine';
 import type { IScrollViewHandle } from '../virtualized-list/virtualized-list-props';
 import type { IVirtualizedSectionListProps as IProps } from './virtualized-section-list-props';

package/build/components/virtualized-section-list/virtualized-section-list-props.d.ts

@@ -25,6 +25,11 @@ export interface IVirtualizedSectionListProps<ItemT> extends IAccessibilityProps
     footer?: Snippet;
     empty?: Snippet;
     keyExtractor?: (item: ItemT, index: number) => string;
+    getItemLayout?: (data: ReadonlyArray<ISection<ItemT>> | null, index: number) => {
+        length: number;
+        offset: number;
+        index: number;
+    };
     stickySectionHeadersEnabled?: boolean;
     extraData?: unknown;
     onEndReached?: (info: {

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/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/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,7 +15,10 @@ 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
@@ -28,7 +31,9 @@ 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

@@ -17,12 +17,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';

package/build/index.js

@@ -46,11 +46,17 @@ export { findNodeHandle, hostInstance } from './host-instance.js';
 // (mount/unmount, for a downstream package's own tests).
 // createTunnel: the Svelte twin of adapters/vue/src/create-tunnel (see create-tunnel/tunnel.ts's
 // header for why the API shape — an explicit `tunnel` prop on TunnelIn/TunnelOut, rather than
-// `tunnel.In`/`tunnel.Out` — deliberately differs from React/Vue). NOTE: React's createPortal has
-// no Svelte (or even Vue) twin — it is react-reconciler's own Fiber-level HostPortal primitive,
-// with no equivalent in a framework with no reconciler; createTunnel is the achievable analog,
-// same scope Vue itself settled on.
-export { createTunnel, TunnelIn, TunnelOut } from './create-tunnel/index.js';
+// `tunnel.In`/`tunnel.Out` — deliberately differs from React/Vue).
+export { createTunnel, TunnelIn, TunnelOut, } from './create-tunnel/index.js';
+// Portal: the Svelte twin of React's createPortal / Solid's <Portal mount={…}> / Angular's
+// PortalDirective. It is NOT interchangeable with createTunnel above — the two capabilities do
+// not overlap (create-portal/index.ts's header carries the row-by-row table, each row pinned by a
+// test). Portal uniquely buys a target that renders no outlet — the only route to a container you
+// merely hold a ref to — and call-site `getContext`; the tunnel uniquely buys cross-surface reach.
+// (This barrel used to state that createPortal "has no Svelte twin ... with no equivalent in a
+// framework with no reconciler". That was wrong: a portal needs a retained tree you can move a
+// subtree within, not a reconciler, and this adapter has one.)
+export { Portal } from './create-portal/index.js';
 // useWindowDimensions / useColorScheme: the Svelte twins of React's hooks / Vue's composables —
 // see runes/use-window-dimensions.svelte.ts's header for why this adapter's lifecycle-helper
 // bucket is named `runes/`, not `hooks/`/`composables/`.
@@ -60,7 +66,7 @@ export { useColorScheme } from './runes/use-color-scheme.svelte';
 // `undefined` forever here. Same names, same `.current` shape, engine Dimensions/PixelRatio
 // underneath — see runes/window.ts's header for the two deliberate differences from upstream, and
 // for why `scrollX`/`scrollY`/`screenLeft`/`screenTop` are absent rather than faked.
-export { innerWidth, innerHeight, outerWidth, outerHeight, devicePixelRatio } from './runes/window.js';
+export { innerWidth, innerHeight, outerWidth, outerHeight, devicePixelRatio, } from './runes/window.js';
 // What replaces `MediaQuery` from `svelte/reactivity`: named exports for the media features RN can
 // actually answer, instead of a class taking a CSS query string it would mostly have to answer
 // `false` to. `(prefers-color-scheme)`'s twin is `useColorScheme()` above. See
@@ -70,8 +76,7 @@ export { orientation, createWidthQuery } from './runes/media-query.js';
 // IClassNameValue — plus the normalizer, for a consumer building a class value in its own
 // helper. See class-value.ts's header for the object-is-a-style vs object-is-a-clsx-map rule.
 export { normalizeSvelteClass, resolveSvelteClass, } from './class-value.js';
-// Animated: the Svelte twin of adapters/vue/src/modules/animated (see modules/animated/index.ts's
-// header for why Animated.View/Text/Image/ScrollView are each their own hand-authored .svelte
-// file rather than a generic createAnimatedComponent() wrap — Svelte has no runtime h()/
-// createElement equivalent a factory could target).
-export { Animated } from './modules/animated/index.js';
+// Animated: the Svelte twin of adapters/vue/src/modules/animated. All six RN animated components
+// ship (View/Text/Image/ScrollView/FlatList/SectionList), all of them from the same generic
+// createAnimatedComponent() wrap React, Vue and Solid also export.
+export { Animated, createAnimatedComponent } from './modules/animated/index.js';

package/build/modules/animated/create-animated-component.d.ts

@@ -0,0 +1,5 @@
+import type { Component, ComponentInternals } from 'svelte';
+import type { IAnimatedComponentProps } from './animated-component-props';
+type IAnimatedBase<TExports extends Record<string, unknown>> = (internals: ComponentInternals, props: never) => TExports;
+export declare function createAnimatedComponent<TExports extends Record<string, unknown>>(Base: IAnimatedBase<TExports>): Component<IAnimatedComponentProps, TExports>;
+export {};