@symbiote-native/svelte 0.2.1 → 0.3.0

package/build/modules/animated/create-animated-component.js

@@ -0,0 +1,131 @@
+// createAnimatedComponent: the Svelte twin of the React/Vue/Solid wrapper. Wraps ANY base
+// component so it accepts AnimatedNodes in its props. The framework-agnostic half
+// (reduceProps / readPassthroughStyle / resolveHostNode / the AnimatedProps leaf lifecycle)
+// comes from @symbiote-native/engine, shared verbatim with every other adapter; only the
+// lifecycle below is Svelte's.
+//
+// WHY IT IS PLAIN TS AND NOT A PARAMETRIZED `.svelte` FILE. The generic wrap expresses fine in
+// Svelte — `<Component {...reduced} bind:this={inner} />` over a `component` prop compiles clean
+// — but a `.ts` module that imports a `.svelte` file is unparseable by any tool without the
+// Svelte plugin, which includes this repo's vitest and every consumer smoke test that builds an
+// Animated namespace by hand (packages/navigation's drawer suite). Writing the component body
+// against `svelte/internal/client` keeps `createAnimatedComponent` importable from ordinary TS
+// everywhere, and leaves `modules/animated/` with no `.svelte` file at all. The internals used
+// here are the exact calls the compiler itself emits for the same source — see this package's
+// `svelte-internal-client.d.ts`, and §8 of the svelte-adapter-dom-shim skill for the bump
+// checklist that covers them.
+//
+// TWO WAYS TO THE HOST NODE, because Svelte has no ref fall-through. `bind:this` on a COMPONENT
+// resolves to that component's exports, never to its element:
+//   * a scroll container (ScrollView / FlatList / SectionList) exports an imperative handle, so
+//     resolveHostNode() unwraps it through getScrollNode() — the same call React and Vue make.
+//     Binding the leaf to the handle itself type-checks and then silently animates nothing.
+//   * a plain host primitive (View / Text / Image) exports nothing, so the node arrives through
+//     an `{@attach}` of our own: every Symbiote component forwards attachments onto its host tag
+//     (runes/attachments.ts), which is the adapter's documented seam to a committed node.
+// A base this adapter does not own works if it does either.
+//
+// EVERY OTHER PROP IS FORWARDED UNTOUCHED, including snippets. Svelte snippets — `children` and
+// named scoped ones such as a list's `item` / `sectionHeader` — are ordinary props, so naming any
+// of them here would drop the rest: Vue's wrapper forwarded only its default slot and
+// Animated.FlatList committed empty cells with no error. The only prop this wrapper consumes is
+// `passthroughAnimatedPropExplicitValues`.
+import { createAttachmentKey } from 'svelte/attachments';
+import { derived, get, pop, push, set, spread_props, state, user_effect, } from 'svelte/internal/client';
+import { createAnimatedLeafLifecycle, isNativeAnimatedAvailable, isSymbioteNode, readPassthroughStyle, reduceProps, resolveHostNode, } from '@symbiote-native/engine';
+import { ShimElement } from '../../dom-shim/index.js';
+// RN's prop carrying explicit (already-rasterized) values that override the animated prop in the
+// COMMITTED props (sticky-header passthrough). Named once so reduce and reconcile agree.
+const PASSTHROUGH_PROP = 'passthroughAnimatedPropExplicitValues';
+// The three keys Svelte's own compiled `rest_props` always drops, plus the prop we consume.
+const BASE_EXCLUDES = new Set([
+    '$$slots',
+    '$$events',
+    '$$legacy',
+    PASSTHROUGH_PROP,
+]);
+// The leaf additionally never sees `children`: an AnimatedProps leaf rasterizes its props into
+// setNativeProps on every frame, and a snippet is not a Fabric prop. It still reaches the BASE.
+const LEAF_EXCLUDES = new Set([...BASE_EXCLUDES, 'children']);
+// A fresh plain object each call, never the live props proxy: the leaf lifecycle stores its
+// argument as the previous-props SNAPSHOT and compares the next call against it, so handing it
+// one live object twice compares that object with itself and skips every reconcile forever.
+function collect(props, excludes) {
+    const out = {};
+    for (const key of Object.keys(props)) {
+        if (excludes.has(key))
+            continue;
+        out[key] = Reflect.get(props, key);
+    }
+    return out;
+}
+// Reads the base's display name for the dlog label, without a cast, so a reconcile line in a log
+// dump says which Animated.* it came from — the per-component labels the six hand-authored files
+// used to hardcode.
+function baseName(base) {
+    if (typeof base !== 'function' && typeof base !== 'object')
+        return 'Anonymous';
+    if (base === null)
+        return 'Anonymous';
+    const name = Reflect.get(base, 'name');
+    return typeof name === 'string' && name.length > 0 ? name : 'Anonymous';
+}
+function hostNode(instance, shim) {
+    const unwrapped = resolveHostNode(instance);
+    if (isSymbioteNode(unwrapped))
+        return unwrapped;
+    return shim?.engineNode ?? null;
+}
+export function createAnimatedComponent(Base) {
+    const label = `Animated(${baseName(Base)})`;
+    return function AnimatedComponent(internals, props) {
+        // The compiled twin of a component's own `$props()` scope: without it the `$effect`s below
+        // are created immediately instead of being deferred to mount, and would first run before
+        // the base has rendered anything.
+        push(props, true);
+        const lifecycle = createAnimatedLeafLifecycle(label);
+        // The `$state.raw` twin: the shim is held by IDENTITY (a deep proxy would miss the engine's
+        // WeakMap mirror) and read inside the reconcile effect, so the leaf rebinds when it lands.
+        const hostShim = state(null);
+        // Rasterized props for the declarative bag: every animated node replaced by its current
+        // value, so the first paint already carries concrete values. The per-FRAME path is separate
+        // (AnimatedProps.update -> setNativeProps) and never goes through this.
+        const reduced = derived(() => {
+            const out = reduceProps(collect(props, BASE_EXCLUDES));
+            const passthroughStyle = readPassthroughStyle(Reflect.get(props, PASSTHROUGH_PROP));
+            if (passthroughStyle !== undefined) {
+                out.style =
+                    out.style === undefined
+                        ? passthroughStyle
+                        : [out.style, passthroughStyle];
+            }
+            return out;
+        });
+        // `reduceProps` rebuilds a plain string-keyed Record, so `{@attach}`'s SYMBOL keys do not
+        // survive it. This one is ours and rides as a second spread source; a user's own attachments
+        // are re-collected the same way.
+        const attachments = {
+            [createAttachmentKey()]: (node) => {
+                set(hostShim, node instanceof ShimElement ? node : null);
+                return () => set(hostShim, null);
+            },
+        };
+        for (const key of Object.getOwnPropertySymbols(props)) {
+            attachments[key] = Reflect.get(props, key);
+        }
+        const instance = Base(internals, spread_props(() => get(reduced), attachments));
+        // `props` and the node are read unconditionally before any branch — a guarded read would
+        // drop that dependency from later re-runs. reconcile() itself tolerates a null node.
+        user_effect(() => {
+            const leafProps = collect(props, LEAF_EXCLUDES);
+            const node = hostNode(instance, get(hostShim));
+            const passthrough = Reflect.get(props, PASSTHROUGH_PROP);
+            lifecycle.reconcile(leafProps, node, passthrough != null && isNativeAnimatedAvailable());
+        });
+        user_effect(() => () => lifecycle.teardown());
+        // The base's own exports ARE the wrapper's: a parent's `bind:this` on Animated.FlatList gets
+        // the real scrollToOffset/scrollToIndex/getScrollNode surface, and a method added to the base
+        // later cannot go missing here the way a hand-listed delegation would.
+        return pop(instance);
+    };
+}

package/build/modules/animated/index.d.ts

@@ -1,4 +1,5 @@
 import { AnimatedValue, AnimatedValueXY, AnimatedColor, timing, spring, decay, parallel, sequence, stagger, loop, delay, add, subtract, multiply, divide, modulo, diffClamp, event, forkEvent, unforkEvent } from '@symbiote-native/engine';
+export { createAnimatedComponent } from './create-animated-component';
 export type { IAnimatedComponentProps } from './animated-component-props';
 export declare const Animated: {
     Value: typeof AnimatedValue;
@@ -40,19 +41,28 @@ export declare const Animated: {
     event: typeof event;
     forkEvent: typeof forkEvent;
     unforkEvent: typeof unforkEvent;
-    View: import("svelte").Component<import("./animated-component-props").IAnimatedComponentProps, {}, "">;
-    Text: import("svelte").Component<import("./animated-component-props").IAnimatedComponentProps, {}, "">;
-    Image: import("svelte").Component<import("./animated-component-props").IAnimatedComponentProps, {}, "">;
+    View: import("svelte").Component<import("./animated-component-props").IAnimatedComponentProps, {
+        $on?(type: string, callback: (e: any) => void): () => void;
+        $set?(props: Partial<Record<string, any>>): void;
+    } & Record<string, any>, string>;
+    Text: import("svelte").Component<import("./animated-component-props").IAnimatedComponentProps, {
+        $on?(type: string, callback: (e: any) => void): () => void;
+        $set?(props: Partial<Record<string, any>>): void;
+    } & Record<string, any>, string>;
+    Image: import("svelte").Component<import("./animated-component-props").IAnimatedComponentProps, {
+        $on?(type: string, callback: (e: any) => void): () => void;
+        $set?(props: Partial<Record<string, any>>): void;
+    } & Record<string, any>, string>;
     ScrollView: import("svelte").Component<import("./animated-component-props").IAnimatedComponentProps, {
-        scrollTo: (options?: {
-            x?: number;
-            y?: number;
-            animated?: boolean;
-        }) => void;
-        scrollToEnd: (options?: {
-            animated?: boolean;
-        }) => void;
-        flashScrollIndicators: () => void;
-        getScrollNode: () => import("@symbiote-native/engine").ISymbioteNode | null;
-    }, "">;
+        $on?(type: string, callback: (e: any) => void): () => void;
+        $set?(props: Partial<Record<string, any>>): void;
+    } & Record<string, any>, string>;
+    FlatList: import("svelte").Component<import("./animated-component-props").IAnimatedComponentProps, {
+        $on?(type: string, callback: (e: any) => void): () => void;
+        $set?(props: Partial<Record<string, any>>): void;
+    } & Record<string, any>, string>;
+    SectionList: import("svelte").Component<import("./animated-component-props").IAnimatedComponentProps, {
+        $on?(type: string, callback: (e: any) => void): () => void;
+        $set?(props: Partial<Record<string, any>>): void;
+    } & Record<string, any>, string>;
 };

package/build/modules/animated/index.js

@@ -4,32 +4,26 @@
 // interpolation and drivers come from @symbiote-native/engine (framework-agnostic, JS-driven),
 // spread in verbatim.
 //
-// Unlike Vue/React, there is NO generic `createAnimatedComponent(Component)` here. Vue wraps an
-// arbitrary base component via `h(Component, reducedProps)`; React via `createElement(Component,
-// childProps)` — both are ordinary runtime function calls that work on any component reference.
-// Svelte has no equivalent: a compiled Svelte component is not a plain function you can invoke
-// generically with a fresh prop bag and get back something you can further compose — wrapping
-// one means literally writing `<Component {...props} bind:this={ref}>` inside another `.svelte`
-// file. So each of the four components below (View/Text/Image/ScrollView) is its own hand-
-// authored `.svelte` file sharing only the non-visual reconcile logic
-// (animated-props-runtime.ts). `Animated.createAnimatedComponent` is a genuine, documented scope
-// boundary, not an oversight — see this module's own report for the full reasoning. A consumer
-// wanting to animate their OWN custom component should follow the same four-file pattern (rebuild
-// an AnimatedProps leaf from its props, reconcile on every render into the component's own host
-// node/handle, expose that host node via bind:this) rather than reach for a generic wrapper that
-// does not exist on this adapter.
+// All six components come from ONE generic `createAnimatedComponent(Base)` — the same shape
+// React, Vue and Solid have — applied to the ordinary components. There is no hand-authored
+// `.svelte` file per animated component any more: an earlier revision of this header claimed a
+// generic wrap was impossible on Svelte, and that was simply wrong. See
+// create-animated-component.ts for how the wrap reaches the host node behind a base that exports
+// an imperative handle (ScrollView/FlatList/SectionList) versus one that exports nothing
+// (View/Text/Image), and for why it is plain TS rather than a parametrized `.svelte` file.
 //
-// Animated.FlatList / Animated.SectionList are also NOT implemented in this pass. Vue omits them
-// because it has no FlatList/SectionList base component at all; Svelte DOES have both, so this is
-// a narrower, more honest gap than Vue's — flagged as follow-up work, not silently dropped (see
-// the module's own report). Wrapping them would follow the exact same
-// wrap-the-real-component-via-its-exported-handle shape as AnimatedScrollView, once each exposes
-// (or is confirmed to need) an equivalent handle.
+// A consumer animating their OWN component wraps it the same way: `createAnimatedComponent(Mine)`
+// works as long as Mine either exports `getScrollNode()` or forwards `{@attach}` onto its host
+// tag, which every component in this adapter does.
 import { AnimatedValue, AnimatedValueXY, AnimatedColor, AnimatedMock, Easing, Platform, timing, spring, decay, parallel, sequence, stagger, loop, delay, add, subtract, multiply, divide, modulo, diffClamp, event, forkEvent, unforkEvent, } from '@symbiote-native/engine';
-import AnimatedViewComponent from './AnimatedView.svelte';
-import AnimatedTextComponent from './AnimatedText.svelte';
-import AnimatedImageComponent from './AnimatedImage.svelte';
-import AnimatedScrollViewComponent from './AnimatedScrollView.svelte';
+import View from '../../components/View.svelte';
+import Text from '../../components/Text.svelte';
+import Image from '../../components/image/index.svelte';
+import ScrollView from '../../components/scroll-view/index.svelte';
+import FlatList from '../../components/flat-list/index.svelte';
+import SectionList from '../../components/section-list/index.svelte';
+import { createAnimatedComponent } from './create-animated-component.js';
+export { createAnimatedComponent } from './create-animated-component.js';
 // The live, JS-driven driver namespace (real frames). RN's AnimatedImplementation.
 const liveDrivers = {
     Value: AnimatedValue,
@@ -56,14 +50,20 @@ const liveDrivers = {
 };
 // RN swaps the WHOLE driver namespace for the mock when the host reports isDisableAnimations
 // (reduced motion / test env): the mock keeps the same surface but jumps each animation to its
-// final value synchronously, no frames. The animated COMPONENTS (View/Text/Image/ScrollView) are
-// live in both branches; only the drivers/value/operators/events half is swapped, exactly like
+// final value synchronously, no frames. The animated COMPONENTS (View/Text/Image/ScrollView/
+// FlatList/SectionList) are live in both branches; only the drivers/value/operators/events half
+// is swapped, exactly like
 // RN spreading `...Animated` (impl or mock) over the same component references.
 const drivers = Platform.isDisableAnimations ? AnimatedMock : liveDrivers;
+// Wrapped eagerly, unlike Vue's lazy getters: nothing in the scroll/list chain imports THIS
+// module back (sticky-header builds its own Animated.View straight from the wrap), so there is
+// no half-evaluated cycle to dodge.
 export const Animated = {
-    View: AnimatedViewComponent,
-    Text: AnimatedTextComponent,
-    Image: AnimatedImageComponent,
-    ScrollView: AnimatedScrollViewComponent,
+    View: createAnimatedComponent(View),
+    Text: createAnimatedComponent(Text),
+    Image: createAnimatedComponent(Image),
+    ScrollView: createAnimatedComponent(ScrollView),
+    FlatList: createAnimatedComponent(FlatList),
+    SectionList: createAnimatedComponent(SectionList),
     ...drivers,
 };

package/build/modules/status-bar/index.js

@@ -7,7 +7,7 @@
 // in a plain sibling `.ts` file rather than inside `index.svelte` itself — same pattern as
 // components/image/index.ts.
 import StatusBarComponent from './index.svelte';
-import { statusBarImperative, statusBarCurrentHeight } from '@symbiote-native/engine';
+import { statusBarImperative, statusBarCurrentHeight, } from '@symbiote-native/engine';
 const StatusBarWithStatics = Object.assign(StatusBarComponent, statusBarImperative);
 // Android exposes the bar height as a native constant; undefined on iOS / when absent. Read
 // lazily (getter) so nothing touches native at import time; the Android engine impl resolves

package/build/modules/status-bar/index.svelte

@@ -10,7 +10,10 @@
   // Unlike Vue's twin (status-bar.ts), no untyped-attrs guard layer is needed: Svelte's
   // `$props()` already destructures real typed fields straight from the compiler, so there is
   // no kebab-case-attrs normalization step to run first.
-  import { applyStatusBarProps, type IStatusBarProps } from '@symbiote-native/engine';
+  import {
+    applyStatusBarProps,
+    type IStatusBarProps,
+  } from '@symbiote-native/engine';
 
   let props: IStatusBarProps = $props();
 

package/build/native-view-bridge.d.ts

@@ -1,4 +1,4 @@
 export { mount, unmount } from './render';
-export { mountDescriptorChildren, createDescriptorChildrenSync } from './descriptor-to-svelte';
+export { mountDescriptorChildren, createDescriptorChildrenSync, } from './descriptor-to-svelte';
 export type { IDescriptorChildrenMount } from './descriptor-to-svelte';
 export type { ShimElement } from './dom-shim';

package/build/native-view-bridge.js

@@ -24,4 +24,4 @@
 // 'RNCSlider') that cannot be written as a literal Svelte template tag — see
 // packages/slider/src/svelte/slider/index.svelte's header for the full reasoning.
 export { mount, unmount } from './render.js';
-export { mountDescriptorChildren, createDescriptorChildrenSync } from './descriptor-to-svelte.js';
+export { mountDescriptorChildren, createDescriptorChildrenSync, } from './descriptor-to-svelte.js';

package/build/preprocessor/collapse-text-whitespace.js

@@ -23,12 +23,18 @@
 // a whitespace-only node with a newline gets deleted; a same-line run of 2+ spaces collapses to
 // one and stays, matching HTML's own collapse of an intentional double space.
 //
-// Known gap: a whitespace-only run between two siblings on ONE line with no newline
-// (`<View><A/>  <B/></View>`) isn't caught - indistinguishable from the intentional-space case
-// without knowing whether the parent renders raw text. Rare in practice (§16's own audit found
-// only the wrapped-sentence and cross-line-gap shapes) and still caught by
-// `scripts/audit-svelte-stray-whitespace.mjs`, which walks the compiled output independently of
-// this heuristic.
+// Hazard 2 is no longer THIS file's guarantee. A whitespace-only run between two siblings on
+// ONE line (`<View><A/>  <B/></View>`) is indistinguishable here from an intentional space -
+// the missing fact is whether the parent renders raw text, which source alone cannot say.
+// `dom-shim/text.ts` knows it: by the time a text node goes live its parent's engine node is
+// bound, so it drops whitespace-only text under any non-text parent. That is exact, and it
+// holds even for a consumer who never registers this preprocessor.
+//
+// So deleting the cross-line gap here is now an OPTIMIZATION - the node is never built at all -
+// plus source hygiene for svelte-check. Hazard 1 (a wrapped sentence INSIDE one text node) does
+// still rely on this file: it needs collapsing rather than dropping, and only source can tell an
+// authored newline from one a runtime value carries. `scripts/audit-svelte-stray-whitespace.mjs`
+// still walks compiled output independently of both.
 //
 // Registered in svelte.config.js's `preprocess`, same as forbid-web-only-constructs.ts and
 // scoped-styles.ts, so it covers both svelte-check/the language server and Metro's build.
@@ -72,6 +78,11 @@ function nestedNodes(node) {
     }
     return nested;
 }
+// Narrower than the shim's WHITESPACE_ONLY, on purpose - do NOT "unify" them. This class drives
+// COLLAPSING runs inside real text content, where `&nbsp;` / `&emsp;` are a deliberate character
+// an author typed, not formatting; folding them into a plain space would change what renders.
+// The shim can be wider because it only ever DROPS, and only under a parent that cannot paint
+// text at all. Same reason Svelte's own regex_not_whitespace excludes nbsp.
 const WHITESPACE_RUN = /[ \t\r\n]+/g;
 function collectEdits(nodes, edits) {
     for (const node of nodes) {
@@ -99,7 +110,9 @@ function textEdit(start, end, data) {
     if (collapsed.trim() === '') {
         // Whitespace-only node: delete it only if the original spanned a line break, else leave it
         // as the single collapsed space.
-        return data.includes('\n') ? { start, end, text: '' } : { start, end, text: collapsed };
+        return data.includes('\n')
+            ? { start, end, text: '' }
+            : { start, end, text: collapsed };
     }
     if (collapsed === data)
         return undefined;

package/build/preprocessor/forbid-web-only-constructs.js

@@ -33,8 +33,14 @@ const SPECIAL_ELEMENT_ADVICE = 'has no meaning under React Native and is silentl
     '(Dimensions / AppState / StatusBar / …).';
 const FORBIDDEN = new Map([
     ['SvelteHead', { label: '<svelte:head>', advice: SPECIAL_ELEMENT_ADVICE }],
-    ['SvelteWindow', { label: '<svelte:window>', advice: SPECIAL_ELEMENT_ADVICE }],
-    ['SvelteDocument', { label: '<svelte:document>', advice: SPECIAL_ELEMENT_ADVICE }],
+    [
+        'SvelteWindow',
+        { label: '<svelte:window>', advice: SPECIAL_ELEMENT_ADVICE },
+    ],
+    [
+        'SvelteDocument',
+        { label: '<svelte:document>', advice: SPECIAL_ELEMENT_ADVICE },
+    ],
     ['SvelteBody', { label: '<svelte:body>', advice: SPECIAL_ELEMENT_ADVICE }],
     [
         'HtmlTag',