@symbiote-native/svelte 3.0.2 → 3.0.4

package/README.md

@@ -1,7 +1,7 @@
 # @symbiote-native/svelte
 
 The **Svelte adapter** for [SymbioteNative](../../README.md) — render real native iOS/Android views
-from Svelte 5, on the _same_ untouched core as React, Vue, and Angular, with React Native's own
+from Svelte 5, on the _same_ untouched core as React, Vue, Solid, and Angular, with React Native's own
 renderer never in the path. Svelte ships no official host-renderer API yet (`createRenderer` is
 still an unmerged PR upstream), so instead of hooking a framework-blessed extension point this
 adapter patches `globalThis`'s DOM classes: stock compiled Svelte client output believes it is
@@ -23,35 +23,84 @@ Svelte is the **sharpest test yet** that the core is genuinely framework-agnosti
 
 ## Install
 
+```bash
+npx @symbiote-native/cli new my-app --framework svelte
+```
+
+One command, nothing to wire by hand: every component here is a `.svelte` SFC with no TSX
+alternative, so the Metro wiring below isn't optional — the generator sets it up, plus
+`@symbiote-native/svelte`/`react-native`/`svelte` as your app's own dependencies.
+
+<details>
+<summary>Manual install (no generator — an existing app, or you want to wire it yourself)</summary>
+
 ```bash
 npm install @symbiote-native/svelte react-native svelte
 ```
 
 `react-native` and `svelte` stay your app's own top-level dependencies — this package only
-replaces the JS renderer that drives them. Every component is a `.svelte` SFC — there's no TSX
-alternative the way Vue offers — so the Metro wiring below isn't optional. `npx @symbiote-native/cli new`
-sets this up for a new app; wiring it into an existing one still follows
-[`examples/svelte`](../../examples/svelte) rather than a generator:
+replaces the JS renderer that drives them. Follow [`examples/svelte`](../../examples/svelte) for
+both pieces of Metro wiring below; there is no wiring script for an existing app:
 
 - `metro.config.js` — point `babelTransformerPath` at
   `@symbiote-native/svelte/metro-svelte-transformer` (compiles `.svelte` on the way into the
   bundle) and disable `inlineRequires` (see [the gotcha
   below](#a-svelte-specific-gotcha--inlinerequires-vs-the-svelte-runtime)).
-- `svelte.config.js` — registers the `forbidWebOnlyConstructs()` and `scopedStyles()`
-  preprocessors, so `svelte-check` and the editor catch the same things Metro's transformer
-  already guards against at build time, and sets `compilerOptions: { fragments: 'tree', css:
-'external' }`.
+- `svelte.config.js` — registers the `forbidWebOnlyConstructs()`, `scopedStyles()`, and
+  `collapseTextWhitespace()` preprocessors, so `svelte-check` and the editor catch the same things
+  Metro's transformer already guards against at build time (the third one matters beyond
+  diagnostics: without it, a sentence wrapped across source lines for readability ships a literal
+  newline into the native text content — Svelte doesn't collapse it the way a browser or Vue's
+  compiler would). Also sets `compilerOptions: { fragments: 'tree', css: 'external' }` and a
+  `warningFilter` that silences `element_invalid_self_closing_tag` for `<pressable />`-style
+  self-closing primitives.
+
+</details>
 
 ---
 
 ## Use it
 
+The app is ordinary Svelte 5 — the native primitives are plain intrinsic tags, no import needed.
+Styling is a CSS class against the component's own `<style>` block — the convention every example
+app here follows. A tap→increment counter, using runes:
+
+```svelte
+<script lang="ts">
+  let count = $state(0);
+</script>
+
+<safe-area-view class="screen">
+  <text>Taps: {count}</text>
+  <pressable onPress={() => count++}>
+    <text>Tap me</text>
+  </pressable>
+</safe-area-view>
+
+<style>
+  .screen {
+    flex: 1;
+    align-items: center;
+    justify-content: center;
+    padding: 24px;
+  }
+</style>
+```
+
+<details>
+<summary>Native entry point (index.js) — already scaffolded by <code>npx @symbiote-native/cli new --framework svelte</code></summary>
+
 The native entry reaches the _same_ seam as every other adapter. `createApp(App).mount(appName)`
 wires the native-host seams and RN's own `AppRegistry`, then mounts via `@symbiote-native/engine` —
 RN's own renderer is never in the path:
 
 ```js
 // index.js
+
+// Registers host behaviors (Image, Pressable, Switch, ...) that /bootstrap alone doesn't
+// reach; deleting this breaks them silently (Metro's production inlineRequires makes a
+// side-effect-only barrel import go lazy, see register.ts).
+import '@symbiote-native/svelte';
 import { createApp } from '@symbiote-native/svelte/bootstrap';
 import App from './App.svelte';
 import { name as appName } from './app.json';
@@ -59,21 +108,7 @@ import { name as appName } from './app.json';
 createApp(App).mount(appName);
 ```
 
-The app is ordinary Svelte 5 — the native primitives are plain intrinsic tags, no import needed.
-A tap→increment counter, using runes:
-
-```svelte
-<script lang="ts">
-  let count = $state(0);
-</script>
-
-<view style={{ padding: 24 }}>
-  <text>Taps: {count}</text>
-  <pressable onPress={() => count++}>
-    <text>Tap me</text>
-  </pressable>
-</view>
-```
+</details>
 
 The full canary is [`examples/svelte`](../../examples/svelte) — a stock RN 0.86 app whose
 [`App.svelte`](../../examples/svelte/App.svelte) exercises the same surface as the React, Vue, and
@@ -84,8 +119,8 @@ Angular reference canaries.
 ## Parity — and the one gap
 
 Svelte reaches the same primitives, runtime modules, `Animated` on both drivers, gestures,
-accessibility, and the `VirtualizedList` family as React, Vue, and Angular, verified on-device on
-iOS and Android. That parity is **structural, not hand-copied**: the component logic (state
+accessibility, and the `VirtualizedList` family as React, Vue, Solid, and Angular, verified
+on-device on iOS and Android. That parity is **structural, not hand-copied**: the component logic (state
 machines + render functions) is written **once** in `@symbiote-native/components`, and Svelte
 supplies only its lifecycle — runes (`$state` / `$derived` / `$effect`) driving hand-authored
 `.svelte` markup that mirrors each `render-*.ts` directly, rather than a generic descriptor bridge
@@ -124,9 +159,9 @@ guarding it.
 
 ## Run it
 
-[`examples/svelte`](../../examples/svelte) is a stock React Native 0.86 app. Requires Node ≥ 22
-and the [RN environment setup](https://reactnative.dev/docs/set-up-your-environment) (Xcode,
-CocoaPods):
+[`examples/svelte`](../../examples/svelte) is a stock React Native 0.86 app. Requires Node ≥ 22.13
+(react-native 0.86's own `package.json#engines`) and the [RN environment
+setup](https://reactnative.dev/docs/set-up-your-environment) (Xcode, CocoaPods):
 
 ```bash
 cd examples/svelte

package/build/components/modal/index.svelte

@@ -35,23 +35,26 @@
 
   let rawProps: IModalProps = $props();
 
-  let state = $state(createInitialModalState(isModalVisible(rawProps.visible)));
+  // Not a $derived candidate despite the $state+$effect shape below: modalReducer folds over the
+  // PREVIOUS `state` (self-referential — $derived can't read the value it's replacing) and must
+  // run POST-render (see the effect's own comment) so the keep-alive frame survives a commit.
+  let localState = $state(createInitialModalState(rawProps.visible === true));
 
   const resolved = $derived(resolveAccessibilityProps(rawProps));
   const isVisible = $derived(isModalVisible(resolved.visible));
-  const shouldRender = $derived(shouldRenderModal(isVisible, state));
+  const shouldRender = $derived(shouldRenderModal(isVisible, localState));
 
   // Arms the iOS keep-alive on show; a hide is left to the native dismiss (state/modal.ts). The
   // reducer is identity-stable, so the mount run triggers no extra render.
   $effect(() => {
     const action = modalVisibilityAction(isVisible);
-    if (action !== undefined) state = modalReducer(state, action);
+    if (action !== undefined) localState = modalReducer(localState, action);
   });
 
   // Modal.js: onDismiss is iOS-only — it drops the keep-alive, then tells the app.
   function handleDismiss(): void {
     if (Platform.OS !== 'ios') return;
-    state = modalReducer(state, { type: 'hide' });
+    localState = modalReducer(localState, { type: 'hide' });
     rawProps.onDismiss?.();
   }
 

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

@@ -12,8 +12,7 @@
   //
   // This file authors the raw `scroll-view` intrinsic directly, and needs to: it walks an indexable
   // `plan.cells` list rather than taking an opaque children Snippet, so it can mark sticky cells
-  // itself. (There is no ScrollView component to render instead — it was deleted 2026-09-10 and an
-  // app writes the tag too.)
+  // itself. (There is no ScrollView component to render instead — an app writes the tag too.)
   //
   // It does NOT author the CONTENT node. `registerScrollViewBehavior()` puts a `buildStructure` on
   // the scroll tags, and exactly one thing may build `RCTScrollContentView` — emitting one here as
@@ -109,6 +108,10 @@
 
   // The one folded state cell — the Svelte twin of Vue's plain listState / React's stateRef.
   const listState: IListState<ItemT> = createInitialListState<ItemT>();
+  // Plain Map by design, like listState above: separatorVersion (below) is the manual
+  // invalidation signal a read tracks — a SvelteMap would double-track and still miss nothing,
+  // but adds reactive overhead this hot path doesn't need.
+  // eslint-disable-next-line svelte/prefer-svelte-reactivity
   const separatorOverrides = new Map<number, Partial<ISeparatorProps<ItemT>>>();
   let viewableTimer: ReturnType<typeof setTimeout> | null = null;
   let batchTimer: ReturnType<typeof setTimeout> | null = null;

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

@@ -63,12 +63,9 @@
       Platform.OS,
     ),
   );
-  // DIAGNOSTIC (2026-08-13, tracking why stickyHeaderIndices comes back undefined on Android
-  // despite the demo passing the bare `stickySectionHeadersEnabled` shorthand): the previous
-  // logging only showed the RESULT (VirtualizedList's own dlog), never the INPUTS this $derived
-  // actually read — isolated verification proved bare-shorthand forwarding through this exact
-  // two-hop generic-component chain works correctly in a standalone repro, so this must show
-  // what differs in the real component tree.
+  // Diagnostic: logs every INPUT this $derived reads, not just VirtualizedList's own result —
+  // `stickyHeaderIndices` can come back undefined on Android with the bare
+  // `stickySectionHeadersEnabled` shorthand, and only the inputs show what differs.
   $effect(() => {
     dlog(
       `VirtualizedSectionList sticky-inputs enabled=${String(props.stickySectionHeadersEnabled)} ` +

package/build/create-portal/index.js

@@ -1,9 +1,6 @@
-// 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.
+// Portal — the Svelte adapter's same-surface portal: the twin of React's `createPortal`, Solid's
+// `<Portal mount={…}>` and Angular's PortalDirective/PortalOutletDirective pair. Does NOT overlap
+// with `createTunnel` (table at the bottom of this header) — the tunnel is not 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

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

@@ -2,9 +2,8 @@
 // (svelte-adapter-dom-shim skill §2, §3a, §6). Must run before `mount()` (§3f) — not
 // necessarily before `svelte` is imported.
 //
-// Single-root only, by design (§10, decided during Svelte adapter planning 2026-08-11): one
-// Symbiote app = one process = one Svelte root, so `restoreGlobals()` needs no ref-counting —
-// `unmount()` calls it unconditionally.
+// Single-root only, by design (§10): one Symbiote app = one process = one Svelte root, so
+// `restoreGlobals()` needs no ref-counting — `unmount()` calls it unconditionally.
 //
 // Deliberately NOT patched, and must stay that way (§6b, §6c, §6d) — both verified against the
 // real vendored RN source (.vendors/react-native/packages/react-native/Libraries/Core/), not
@@ -51,20 +50,9 @@ const PATCHED_KEYS = [
 // with (unlike `navigator`/`requestAnimationFrame`, verified against .vendors/react-native —
 // 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.
+// `get()` returns a TRUTHY stand-in — the whole reason `set_custom_element_data` stays lossless.
+// Falsy selects attributes.js's HEURISTIC path instead of `get_setters`: it stringifies scalars
+// and drops any object-valued prop with no prototype setter.
 const FAKE_CUSTOM_ELEMENT_REGISTRY = {
     get: () => ShimElement,
 };

package/build/index.js

@@ -4,11 +4,9 @@
 // All Fabric clone-on-write lives in the engine, shared cross-adapter. App code names only
 // @symbiote-native/svelte.
 //
-// Full component parity with React/Vue/Angular landed 2026-08-11 (svelte-adapter-dom-shim
-// skill §15): every `core/components` render function has a fixed tree shape, so no
-// `descriptorToSvelte` bridge was ever needed — each component below is hand-authored Svelte
-// markup mirroring its render-*.ts, reusing only the pure state/render logic. See skill §17/§18
-// for the one open async-exception repro and the honest cross-cutting gap list.
+// Full component parity with React/Vue/Angular (svelte-adapter-dom-shim skill §15): every
+// `core/components` render function has a fixed tree shape, so no `descriptorToSvelte` bridge is
+// needed — each component below is hand-authored Svelte markup mirroring its render-*.ts.
 // Bare side-effect import, deliberately NOT a re-export and deliberately not beside one of the
 // same specifier: it registers the press behavior with the engine's host-behavior registry. Any
 // other shape is dropped by Metro's inlineRequires in a release build — see register.ts.
@@ -25,9 +23,8 @@ export { KeyboardAvoidingView, Modal, VirtualizedList, FlatList, VirtualizedSect
 // threaded through this barrel (parity fix, see React's index.ts lines 55-58, 89, 245-250).
 export { setImageSourceResolver } from '@symbiote-native/components';
 // Pure, framework-agnostic runtime modules — same re-export every other adapter does per
-// CLAUDE.md's <runtime_modules_layering>. PanResponder was missing here (present on
-// React/Vue's own barrels) until 2026-08-12 — a pure engine re-export, no framework glue, so
-// adding it is a one-line parity fix, not new adapter work.
+// CLAUDE.md's <runtime_modules_layering>. A pure engine re-export with no framework glue, so
+// adding one is a one-line parity fix, not new adapter work.
 export { Platform, StyleSheet, PlatformColor, DynamicColorIOS, processColor, setNativeViewConfigSource, setColorProcessor, setDeviceEventSource, PixelRatio, PanResponder, dlog, isDebug, } from '@symbiote-native/engine';
 // The two namespaces left behind by primitives that became tags, here rather than in the component
 // block above for one reason: they carry no view. `Image` gets an adapter file only because it

package/build/modules/animated/index.js

@@ -9,10 +9,9 @@
 // between the value graph and the node's Fabric tag, and both of those were already engine-side.
 //
 // Those three were aliases of the wrappers, and the wrappers are gone — a primitive is a tag now,
-// which is not a value `<Animated.X>` can call. `Animated.ScrollView` left the same way on
-// 2026-09-10: `bindAnimatedEvent` (node.ts, from `setEventListener`) attaches a native-driven event
-// on ANY host node, which was the one job a scroll wrapper still looked like it had. The whole API
-// is `<scroll-view style={{ opacity: v }} p={{ onScroll: Animated.event(…) }}>`.
+// which is not a value `<Animated.X>` can call. `Animated.ScrollView` left the same way:
+// `bindAnimatedEvent` (node.ts) attaches a native-driven event on ANY host node.
+// The whole API is `<scroll-view style={{ opacity: v }} p={{ onScroll: Animated.event(…) }}>`.
 //
 // The two below REMAIN because the LIST family is tier 3: a render prop decides their output shape
 // in JS, so there is no tag for `<Animated.X>` to be an alias of.

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

@@ -1,11 +1,8 @@
 // svelte-adapter-dom-shim skill §16: Svelte trims only the leading/trailing whitespace of a
 // fragment's own children - never whitespace INSIDE a single Text node, and never a
-// whitespace-only Text node BETWEEN two siblings. Vue's compiler (and every browser) collapses
-// both; Svelte doesn't. Confirmed against the real compiler (2026-08-17): a Text node authored
-// as `Hello world, this is a\n  long sentence.` compiles verbatim into
-// `$.text('Hello world, this is a\n  long sentence.')` - the newline and indent ship into the
-// native text content and render as a forced line break plus stray leading spaces on device.
-// Reproduced live on an iOS simulator before this file existed; fixed with it registered.
+// whitespace-only Text node BETWEEN two siblings. Vue's compiler (and every browser) collapse both.
+// A Text node authored as `Hello world, this is a\n  long sentence.` compiles verbatim, so the
+// newline and indent ship into native text as a forced line break plus stray leading spaces.
 //
 // Two hazards:
 //   1. Wrapped sentence - a Text node with real content plus an embedded whitespace run

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

@@ -1,4 +1,4 @@
-// §7 of svelte-adapter-dom-shim (DECIDED 2026-08-11): the constructs that compile cleanly and
+// §7 of svelte-adapter-dom-shim: the constructs that compile cleanly and
 // then silently do nothing under the DOM shim. Everything else in the original §4 table is
 // already closed by "app code can't reach it" or "the TS/Svelte compiler already errors on it for
 // free" (see the skill for the full reachability table). This preprocessor is the guard for what

package/build/preprocessor/scoped-styles.js

@@ -127,13 +127,11 @@ export function scopedStyles() {
 // ---------------------------------------------------------------------------------------------
 // The <style> block, located WITHOUT parsing it.
 //
-// This is svelte's own tag regex (src/compiler/preprocess/index.js), which is what its official
-// `preprocess()` style hook uses to hand a block's content to a preprocessor unparsed — and the
-// reason `svelte-preprocess` can compile SCSS at all. Reading `parse().css` instead, as this file
-// did until 2026-08-20, validates the block as CSS whatever `lang` says: `<style lang="scss">$pad:
-// 7px;</style>` threw `css_expected_identifier` before the language table above was ever
-// consulted, so only SCSS that is already valid CSS (nesting) survived. A `<!-- -->` comment is an
-// alternative of the pattern purely so a commented-out block is skipped rather than matched.
+// This is svelte's own tag regex (src/compiler/preprocess/index.js): what its official
+// `preprocess()` style hook uses to hand a block's content unparsed, the reason `svelte-preprocess`
+// can compile SCSS at all — `parse().css` would validate it as CSS whatever `lang` says.
+// A `<!-- -->` comment is an alternative of the pattern purely so a commented-out block is
+// skipped rather than matched.
 const STYLE_TAG_PATTERN = /<!--[^]*?-->|<style((?:\s+[^=>'"/\s]+=(?:"[^"]*"|'[^']*'|[^>\s]+)|\s+[^=>'"/\s]+)*\s*)(?:\/>|>([\S\s]*?)<\/style>)/g;
 const LANG_ATTRIBUTE_PATTERN = /\blang\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/;
 function findStyleBlock(content) {

package/build/render.js

@@ -1,7 +1,7 @@
 // Mount a Svelte app onto a Fabric surface. The native host hands us a rootTag; we create a
 // surface for it, install the DOM shim, and let stock compiled Svelte output drive it while
-// believing it is talking to the real DOM. Decided during Svelte adapter planning
-// (2026-08-11, svelte-adapter-dom-shim skill §10): single root per process, so
+// believing it is talking to the real DOM.
+// Single root per process (svelte-adapter-dom-shim skill §10), so
 // patchGlobals()/restoreGlobals() need no ref-counting.
 import { mount as svelteMount, unmount as svelteUnmount, } from 'svelte';
 import { createSurface, disposeRoot, dlog, reportUncaughtError, } from '@symbiote-native/engine';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/svelte",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "SymbioteNative's Svelte adapter — a DOM shim over stock compiled Svelte output driving real native iOS/Android views through the same engine as every other adapter.",
   "keywords": [
     "react-native",
@@ -73,22 +73,22 @@
   },
   "dependencies": {
     "typescript": "~6.0.0",
-    "@symbiote-native/components": "3.1.0",
-    "@symbiote-native/css-parser": "0.5.0"
+    "@symbiote-native/components": "3.1.2",
+    "@symbiote-native/css-parser": "0.5.2"
   },
   "peerDependencies": {
     "svelte": ">=5.56.0",
     "react-native": ">=0.86",
-    "@symbiote-native/engine": "^1.3.0"
+    "@symbiote-native/engine": "^1.3.1"
   },
   "devDependencies": {
     "@vue/runtime-core": "^3.5.13",
     "react": "19.2.3",
     "svelte": "^5.56.0",
-    "@symbiote-native/engine": "1.3.0",
-    "@symbiote-native/test-utils": "0.4.2",
-    "@symbiote-native/react": "3.0.2",
-    "@symbiote-native/vue": "3.0.2"
+    "@symbiote-native/engine": "1.3.1",
+    "@symbiote-native/react": "3.0.4",
+    "@symbiote-native/test-utils": "0.4.4",
+    "@symbiote-native/vue": "3.0.4"
   },
   "scripts": {
     "typecheck": "tsc --build",