@symbiote-native/svelte 0.1.0

package/build/root-element.d.ts

@@ -0,0 +1,3 @@
+import type { SymbioteSurface } from '@symbiote-native/engine';
+import { ShimElement } from './dom-shim';
+export declare function createRootShimElement(surface: SymbioteSurface): ShimElement;

package/build/root-element.js

@@ -0,0 +1,27 @@
+// The one place a shim node is bound EAGERLY instead of lazily (svelte-adapter-dom-shim skill
+// §9, §10). Every other shim node only gets its ISymbioteNode on first insertion under a live
+// parent; the root has no parent to inherit liveness from — it IS the top of the live tree, so
+// it must be live from the moment it exists. This is what Svelte's `mount(Component, { target })`
+// receives as `target`.
+//
+// `makeLive` already does exactly the right thing generically (create the engine node, replay
+// accumulated state, recurse into children) — it just never appends the result anywhere, since
+// normally an ancestor's `insertOne` does that. For the root there is no ancestor shim node;
+// the surface plays that role, so this file makes the one `surface.appendChild` call directly.
+import { ShimElement } from './dom-shim/index.js';
+const ROOT_INTRINSIC = 'symbiote-view';
+// Unlike Vue/React, whose app root mounts directly onto the surface (its own flex:1
+// class/style reaches the engine's synthetic flex:1 AppContainer with nothing in between),
+// Svelte's compiled output needs a real DOM-like `target` to call appendChild on — this
+// wrapper. Without flex:1 here, a flex:1-styled app root nested one level inside it has no
+// resolved parent height to grow into and the whole tree collapses to 0x0: every prop still
+// commits correctly (nothing throws), so this only shows up as a blank, untappable screen.
+const ROOT_WRAPPER_STYLE = { flex: 1 };
+export function createRootShimElement(surface) {
+    const root = new ShimElement(ROOT_INTRINSIC);
+    root.p = { style: ROOT_WRAPPER_STYLE };
+    const engineNode = root.makeLive(surface);
+    surface.appendChild(engineNode);
+    surface.requestCommit();
+    return root;
+}

package/build/runes/attachments.d.ts

@@ -0,0 +1,5 @@
+import type { ShimElement } from '../dom-shim';
+type IAttachmentSync = (host: ShimElement | null | undefined, props: object) => void;
+export declare function createAttachmentsSync(): IAttachmentSync;
+export declare function pickAttachmentProps(props: object): Record<symbol, unknown>;
+export {};

package/build/runes/attachments.js

@@ -0,0 +1,73 @@
+// `{@attach fn}` support for this adapter's components.
+//
+// WHY IT IS THE ONLY ROUTE. Svelte's compiler rejects `use:` / `transition:` / `class:` /
+// `style:` on a COMPONENT ("This type of directive is not valid on components"), and app code
+// here never authors a host element (skill §7), so a directive is unreachable by construction.
+// Attachments are the exception: `{@attach fn}` compiles on a component, and `fromAction` from
+// `svelte/attachments` converts any third-party action into one. That makes this the single seam
+// through which a Svelte author reaches the committed native node, the twin of Vue's
+// user-defined custom directive (which works untouched in adapters/vue).
+//
+// THE MECHANISM. `{@attach fn}` compiles to a prop whose key is a SYMBOL created by
+// `createAttachmentKey()`, i.e. `Symbol(ATTACHMENT_KEY)`; Svelte's own spread path identifies one
+// by `symbol.description === ATTACHMENT_KEY` (internal/client/dom/elements/attributes.js). Both
+// `rest_props` and `spread_props` expose symbol keys through their `ownKeys` traps, so
+// `Object.getOwnPropertySymbols()` over `$props()` — or over the `...rest` object — finds them.
+//
+// WHY IT DELEGATES TO SVELTE'S OWN `attach()` RATHER THAN CALLING THE FUNCTION DIRECTLY. A
+// DYNAMIC attachment expression does not compile to a changing prop VALUE; the compiler emits a
+// STABLE wrapper and moves the reactivity inside it:
+//
+//   {@attach which === 'first' ? first : second}
+//   ->  [$.attachment()]: ($$node) => ($.get(which) === 'first' ? first : second)($$node)
+//
+// So identity-diffing the prop can never see the swap — the read that changes lives in the
+// attachment BODY. `attach(node, getFn)` (internal/client/dom/elements/attachments.js) is exactly
+// the machinery that handles this: a managed effect around `getFn()` for the identity case, and a
+// branch effect around `fn(node)` so a reactive read inside the body re-runs it with the previous
+// teardown fired first. Reimplementing it would be reimplementing it wrong.
+//
+// WHY A PLAIN `.ts` HERE AND NOT A `.svelte.ts` RUNE. The `$effect` stays at the component call
+// site; this file holds no rune syntax. `.svelte.ts` files are compiled by `compileModule` in
+// Metro (metro-svelte-transformer.cjs) but NOT by vitest, which has no Svelte plugin — so a rune
+// file imported by every component would break every smoke test in this package. Same split, and
+// the same call shape, as `createDescriptorChildrenSync`.
+import { attach } from 'svelte/internal/client';
+import { createAttachmentKey } from 'svelte/attachments';
+// Read off a real key rather than hardcoded: `ATTACHMENT_KEY` lives in svelte/src/constants.js
+// and is not part of the public export surface, so a rename there would otherwise silently
+// disable every attachment. The literal is the fallback for a Svelte build that stops giving the
+// key a description at all.
+const ATTACHMENT_KEY_DESCRIPTION = createAttachmentKey().description ?? '@attach';
+// Call once during component init, then drive it from an `$effect`:
+//
+//   const syncAttachments = createAttachmentsSync();
+//   $effect(() => { syncAttachments(hostShim, rest); });
+//
+// That effect depends ONLY on the host ref — the attachment values are read lazily inside
+// `attach`'s own effects, never in the caller's body — so it re-runs only when the host node
+// itself changes, and Svelte then destroys the previous run's child effects (firing every
+// teardown) before the new node is attached to.
+export function createAttachmentsSync() {
+    return (host, props) => {
+        if (host === null || host === undefined)
+            return;
+        for (const key of attachmentKeys(props)) {
+            attach(host, () => Reflect.get(props, key));
+        }
+    };
+}
+// For a component that delegates to another Symbiote component by naming individual props
+// instead of spreading (the list family, whose wrappers forward ~30 named props, and anything
+// rebuilding its props through a plain string-keyed Record such as Animated's `reduceProps`).
+// Symbol keys do not survive either, so the wrapper re-spreads just the attachment ones.
+export function pickAttachmentProps(props) {
+    const forwarded = {};
+    for (const key of attachmentKeys(props)) {
+        forwarded[key] = Reflect.get(props, key);
+    }
+    return forwarded;
+}
+function attachmentKeys(props) {
+    return Object.getOwnPropertySymbols(props).filter(key => key.description === ATTACHMENT_KEY_DESCRIPTION);
+}

package/build/runes/dimensions-value.d.ts

@@ -0,0 +1,4 @@
+export interface IReactiveValue<TValue> {
+    readonly current: TValue;
+}
+export declare function createDimensionsValue<TValue>(read: () => TValue): IReactiveValue<TValue>;

package/build/runes/dimensions-value.js

@@ -0,0 +1,30 @@
+// The one plumbing piece behind every reactive screen-metric value in this bucket: a `{ get
+// current() }` box whose read is re-run whenever the engine's Dimensions module emits 'change'.
+//
+// `createSubscriber` (svelte/reactivity) rather than hand-rolled bookkeeping: it is pure — no DOM
+// anywhere in its implementation — and is the integration point Svelte itself documents for an
+// external event source (its own `MediaQuery` is built on it). What it buys us over a `$state` +
+// `$effect` pair is the reason every value here is a module-level singleton rather than a
+// `useX()` call:
+//   - `start` runs lazily, on the FIRST reactive read, and the teardown runs when the LAST
+//     reading effect is destroyed. So importing this module attaches no Dimensions listener, and
+//     N components reading `innerWidth.current` share exactly one.
+//   - `.current` is legal OUTSIDE a component too (it just reads through, untracked), whereas
+//     `$effect` throws `effect_orphan` anywhere but a component.
+// That is also why these files are plain `.ts`, not `.svelte.ts`: they contain no rune syntax, so
+// there is nothing for svelte/compiler's compileModule step to do (same as runes/attachments.ts).
+import { createSubscriber } from 'svelte/reactivity';
+import { Dimensions } from '@symbiote-native/engine';
+export function createDimensionsValue(read) {
+    const subscribe = createSubscriber(update => {
+        const subscription = Dimensions.addEventListener('change', update);
+        return () => subscription.remove();
+    });
+    return {
+        get current() {
+            // Registers the dependency when read inside an effect; a no-op read outside one.
+            subscribe();
+            return read();
+        },
+    };
+}

package/build/runes/media-query.d.ts

@@ -0,0 +1,8 @@
+import { type IReactiveValue } from './dimensions-value';
+export type IOrientation = 'portrait' | 'landscape';
+export declare const orientation: IReactiveValue<IOrientation>;
+export interface IWidthQueryBounds {
+    minWidth?: number;
+    maxWidth?: number;
+}
+export declare function createWidthQuery(bounds: IWidthQueryBounds): IReactiveValue<boolean>;

package/build/runes/media-query.js

@@ -0,0 +1,38 @@
+// What replaces `MediaQuery` from `svelte/reactivity` here — and why it is deliberately NOT a
+// `MediaQuery`-shaped class.
+//
+// `new MediaQuery('min-width: 800px')` takes an arbitrary CSS media-query STRING and answers it
+// against `window.matchMedia`, which does not exist in React Native. A faithful-looking port
+// would have to accept the same string and answer whatever it could from RN sources. The CSS
+// media-query grammar has dozens of features; RN can honestly answer three or four of them. Every
+// other one — `hover`, `pointer`, `prefers-reduced-motion`, `print`, `color-gamut`, `aspect-ratio`
+// — would have to come back `false`, which is indistinguishable from a legitimate "no". That is
+// precisely the "works by accident" dependency the symbiote-web-lib-portability-check skill says
+// to reject: the failure is silent, on device, in a value the author already believes.
+//
+// So the surface is narrower and each supported feature is its own named export. An unsupported
+// one is not a `false` — it is a name that does not exist, i.e. a compile error at the import.
+// The three media features people actually reach for on a phone map cleanly:
+//   (orientation: …)          -> `orientation` below
+//   (min-width / max-width)   -> `createWidthQuery` below
+//   (prefers-color-scheme)    -> the existing `useColorScheme()` rune, over Appearance.
+// Dark mode is not re-exposed here: `useColorScheme()` already covers it and a second accessor
+// for one value is duplication, not ergonomics.
+import { Dimensions } from '@symbiote-native/engine';
+import { createDimensionsValue } from './dimensions-value.js';
+// A square window counts as portrait, matching the CSS `(orientation: portrait)` definition
+// (height >= width), not a coin flip.
+export const orientation = createDimensionsValue(() => {
+    const { width, height } = Dimensions.get('window');
+    return height >= width ? 'portrait' : 'landscape';
+});
+export function createWidthQuery(bounds) {
+    return createDimensionsValue(() => {
+        const { width } = Dimensions.get('window');
+        if (bounds.minWidth !== undefined && width < bounds.minWidth)
+            return false;
+        if (bounds.maxWidth !== undefined && width > bounds.maxWidth)
+            return false;
+        return true;
+    });
+}

package/build/runes/use-color-scheme.svelte.d.ts

@@ -0,0 +1,4 @@
+import { type IColorSchemeName } from '@symbiote-native/engine';
+export declare function useColorScheme(): {
+    readonly current: IColorSchemeName | null;
+};

package/build/runes/use-color-scheme.svelte.js

@@ -0,0 +1,25 @@
+// useColorScheme, the Svelte twin of React's hook / Vue's composable
+// (adapters/vue/src/composables/use-color-scheme.ts), over the framework-agnostic Appearance
+// module (@symbiote-native/engine). See use-window-dimensions.svelte.ts's header for why this
+// lives in `runes/` with a `.svelte.ts` extension and returns a boxed getter object instead of a
+// bare `$state` variable.
+import { Appearance, } from '@symbiote-native/engine';
+export function useColorScheme() {
+    let colorScheme = $state(Appearance.getColorScheme());
+    $effect(() => {
+        // Re-read on mount in case the scheme changed between this function's own call and the
+        // effect actually running — this write is the effect's only touch of `colorScheme`
+        // (never a read), so the effect has no dependency on it and runs exactly once on mount,
+        // cleaning up exactly once on unmount.
+        colorScheme = Appearance.getColorScheme();
+        const subscription = Appearance.addChangeListener(preferences => {
+            colorScheme = preferences.colorScheme;
+        });
+        return () => subscription.remove();
+    });
+    return {
+        get current() {
+            return colorScheme;
+        },
+    };
+}

package/build/runes/use-window-dimensions.svelte.d.ts

@@ -0,0 +1,4 @@
+import { type IDisplayMetrics } from '@symbiote-native/engine';
+export declare function useWindowDimensions(): {
+    readonly current: IDisplayMetrics;
+};

package/build/runes/use-window-dimensions.svelte.js

@@ -0,0 +1,43 @@
+// Svelte twin of React's hook / Vue's composable (use-window-dimensions.ts), over the
+// framework-agnostic Dimensions module. Seeds from Dimensions.get('window'), subscribes to
+// 'change', and re-checks right after subscribing to close the gap between this call's read
+// and the effect's mount-time listener attach.
+//
+// `.svelte.ts`: runes ($state/$effect) only work in files with this extension outside a
+// `.svelte` component. `runes/` is this adapter's bucket name for framework-lifecycle helpers
+// (CLAUDE.md's <adapter_src_follows_framework_idioms>) - Svelte calls $state/$effect "runes".
+//
+// Returns a boxed getter, not a bare `$state` variable: Svelte 5 reactivity is lexically
+// scoped to the declaring module, so returning a raw `let dimensions = $state(...)` loses
+// reactivity for the caller. `{ get current() { ... } }` is the sanctioned pattern - read
+// `useWindowDimensions().current` inside `$derived`/template/`$effect`, like unwrapping Vue's
+// `Ref.value`.
+import { Dimensions, } from '@symbiote-native/engine';
+export function useWindowDimensions() {
+    let dimensions = $state(Dimensions.get('window'));
+    // Plain closure variable, not $state: reading `dimensions` here instead would make the
+    // $effect depend on its own write and re-run itself. This keeps the effect's dependency set
+    // empty, so it runs once on mount and cleans up once on unmount.
+    let last = dimensions;
+    $effect(() => {
+        const handleChange = (next) => {
+            if (last.width !== next.width ||
+                last.height !== next.height ||
+                last.scale !== next.scale ||
+                last.fontScale !== next.fontScale) {
+                last = next;
+                dimensions = next;
+            }
+        };
+        const subscription = Dimensions.addEventListener('change', (set) => handleChange(set.window));
+        // Covers an update missed between the call-time `get` and subscribing here; the equality
+        // guard filters the no-op if nothing changed.
+        handleChange(Dimensions.get('window'));
+        return () => subscription.remove();
+    });
+    return {
+        get current() {
+            return dimensions;
+        },
+    };
+}

package/build/runes/window.d.ts

@@ -0,0 +1,6 @@
+import { type IReactiveValue } from './dimensions-value';
+export declare const innerWidth: IReactiveValue<number>;
+export declare const innerHeight: IReactiveValue<number>;
+export declare const outerWidth: IReactiveValue<number>;
+export declare const outerHeight: IReactiveValue<number>;
+export declare const devicePixelRatio: IReactiveValue<number>;

package/build/runes/window.js

@@ -0,0 +1,28 @@
+// The React Native twin of `svelte/reactivity/window`. Upstream reads `window.innerWidth`,
+// `window.outerWidth`, `window.devicePixelRatio` and friends, all of which are absent here — the
+// dom-shim patches only the DOM classes stock compiled Svelte output touches (svelte-adapter-dom-
+// shim skill), never the browser's window-metric properties — so every one of those values would
+// read `undefined` forever and never update. Same names, same `.current` shape, real engine
+// sources underneath.
+//
+// Two deliberate differences from upstream, both improvements:
+//   - the type is `number`, not `number | undefined`. Upstream's `undefined` is its SSR branch;
+//     there is no SSR here, and Dimensions always answers (it falls back to zero metrics when
+//     DeviceInfo is unresolvable), so a consumer never has to unwrap.
+//   - `outerWidth`/`outerHeight` are the physical SCREEN, not a "browser window inside a desktop
+//     window" — the closest honest reading of outer-vs-inner on a device, where an app's window
+//     is the screen minus system chrome (status bar, navigation bar).
+//
+// NOT provided, on purpose: `scrollX` / `scrollY` / `screenLeft` / `screenTop`. There is no
+// window-level scroll offset in React Native (scrolling is per-ScrollView, observed through its
+// own `onScroll`), and an app has no position within a desktop-style window manager. Rather than
+// export a value that is always 0, or one that throws when it is finally read on a device, these
+// are simply absent — the import fails at compile time, which the author sees immediately.
+import { Dimensions, PixelRatio } from '@symbiote-native/engine';
+import { createDimensionsValue } from './dimensions-value.js';
+export const innerWidth = createDimensionsValue(() => Dimensions.get('window').width);
+export const innerHeight = createDimensionsValue(() => Dimensions.get('window').height);
+export const outerWidth = createDimensionsValue(() => Dimensions.get('screen').width);
+export const outerHeight = createDimensionsValue(() => Dimensions.get('screen').height);
+// PixelRatio.get() IS Dimensions.get('window').scale, so the same 'change' event carries it.
+export const devicePixelRatio = createDimensionsValue(() => PixelRatio.get());

package/build/scope-token.d.ts

@@ -0,0 +1,2 @@
+export declare function scopeToken(token: string, localNames: ReadonlySet<string>, scopeId: string): string;
+export declare function kebabToCamel(value: string): string;

package/build/scope-token.js

@@ -0,0 +1,33 @@
+// The `<style>`-scoping rule for ONE class token, and nothing else.
+//
+// WHY THIS IS ITS OWN FILE — it looks like it belongs in `./style-scope`, and it cannot live
+// there. The build-time half (`preprocessor/scoped-styles.ts`) and the runtime half
+// (`./style-scope`) must apply the SAME rule or a static `class="card"` and a dynamic
+// `class={'card'}` would disagree, so it has to be shared. But `svelte.config.js` is loaded
+// DIRECTLY by Node (svelte-check, the language server): Node strips the types off a `.ts` file
+// yet still runs its own ESM resolver over whatever that file imports, where an extensionless
+// relative specifier is a hard `ERR_MODULE_NOT_FOUND`. `./style-scope` imports `./class-value`
+// imports `@symbiote-native/engine` — an entire extensionless graph the preprocessor must never
+// pull in. So the shared rule lives HERE, with ZERO imports of its own, reachable from the
+// preprocessor through the `@symbiote-native/svelte/scope-token` exports subpath (which supplies
+// the extension at both targets, `src` in-workspace and `build` when published).
+//
+// Keep this file import-free. Adding one import to it breaks `svelte-check` for every consuming
+// app, and nothing in this package's own test run would notice.
+const SCOPE_SEPARATOR = '__';
+// A token is matched in its camelCase form because that is the only form the registry is keyed
+// in (@symbiote-native/css-parser's `extractClassName` always camelCases, so `.card-title`
+// registers as `cardTitle`) while markup idiomatically writes the kebab form. A token this file's
+// `<style>` block does NOT define is returned VERBATIM, not camelCased — unlike Vue's rewriter,
+// which camelCases everything it sees. The engine's `resolveOne` already falls back kebab->camel
+// on a miss, so camelCasing here would buy nothing and would silently rename a class the author
+// is forwarding to some other file's global rule.
+export function scopeToken(token, localNames, scopeId) {
+    const camelToken = kebabToCamel(token);
+    return localNames.has(camelToken) ? camelToken + SCOPE_SEPARATOR + scopeId : token;
+}
+// Duplicated from @symbiote-native/css-parser rather than imported, for the same reason
+// core/engine/src/style-registry/index.ts duplicates it — plus the import-free constraint above.
+export function kebabToCamel(value) {
+    return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}

package/build/style-scope.d.ts

@@ -0,0 +1 @@
+export declare function scopeSvelteClass(value: unknown, localNames: ReadonlySet<string>, scopeId: string): unknown;

package/build/style-scope.js

@@ -0,0 +1,29 @@
+// Runtime half of the `<style>` scoping pass. The build-time half — `preprocessor/
+// scoped-styles.ts` — rewrites every STATIC class token in a component's own markup while it
+// still has the source text. A DYNAMIC `class={expr}` has no tokens to read at build time, so
+// its value is wrapped in a call to `scopeSvelteClass` instead. Same split Vue's scoped-style
+// path already uses (`scopeClassName` in @symbiote-native/engine, symbiote-sfc-style-compiler §5).
+// Both halves apply the identical per-token rule by sharing `./scope-token` — see that file for
+// why the rule is not simply declared here.
+//
+// WHY NOT REUSE THE ENGINE'S `scopeClassName` DIRECTLY. Its input surface is Vue's:
+// `string | Record<string, boolean> | Array<those>`. Svelte's is wider — `class={['card', cond &&
+// 'on']}` leaves a literal `false` in the array, which `scopeClassName` hands to `.split()` and
+// throws on. Widening a function the other three adapters depend on, to serve one adapter's
+// syntax, is the trade §22b already refused for `resolveClassName`. Instead this normalizes
+// through the adapter's OWN clsx boundary first (`normalizeSvelteClass`) and only scopes what
+// comes back as a class string; everything else — a resolved style object, `false`, a mixed array
+// holding a style object — is handed on untouched, taking exactly the path it took before.
+import { normalizeSvelteClass } from './class-value.js';
+import { scopeToken } from './scope-token.js';
+const CLASS_SEPARATOR = ' ';
+export function scopeSvelteClass(value, localNames, scopeId) {
+    const normalized = normalizeSvelteClass(value);
+    if (typeof normalized !== 'string')
+        return normalized;
+    return normalized
+        .split(/\s+/)
+        .filter(Boolean)
+        .map(token => scopeToken(token, localNames, scopeId))
+        .join(CLASS_SEPARATOR);
+}

package/metro-css-parser.cjs

@@ -0,0 +1,9 @@
+// Re-exports @symbiote-native/css-parser verbatim from INSIDE this package, so a consuming app's
+// own require('@symbiote-native/svelte/metro-css-parser') resolves css-parser relative to THIS
+// file's location (adapters/svelte/node_modules, where css-parser IS a real dependency — see
+// package.json), not relative to the app's own node_modules. Twin of
+// adapters/vue/metro-css-parser.cjs. Unlike Vue's, this adapter's own metro-svelte-transformer.cjs
+// already handles standalone style files itself (its isStyleFile branch), so this subpath exists
+// only for parity with the other adapters and for a future consumer that wants CSS-only handling
+// without the .svelte transform (e.g. importing a plain .css from non-.svelte source).
+module.exports = require('@symbiote-native/css-parser').createCssMetroTransformer();

package/metro-svelte-transformer.cjs

@@ -0,0 +1,156 @@
+// Metro babel transformer that teaches the bundler to read Svelte components (.svelte). Metro
+// has no Svelte plugin, so we do the single-pass compile here: run svelte/compiler's compile()
+// with this adapter's own compiler options, then hand the generated client JS to RN's own babel
+// transformer. This is the Metro twin of adapters/vue/metro-vue-transformer.cjs.
+//
+// Unlike Vue's transformer, this does NOT rewrite any framework import: the whole
+// svelte-adapter-dom-shim strategy is that STOCK compiled Svelte client output (its own
+// `import * as $ from 'svelte/internal/client'`) runs completely unchanged against a globalThis
+// DOM shim — there is no @symbiote-native/svelte/runtime-helpers retarget the way Vue needs one.
+// Verified against the installed svelte@5.56.8: compiling a trivial component with
+// {fragments:'tree', css:'external', generate:'client'} produces exactly
+// `import * as $ from 'svelte/internal/client'` + `$.from_tree(...)` + `$.set_custom_element_data`
+// calls — the same shape the dom-shim's init_operations patches already target.
+//
+// Ships as a package-level export (`@symbiote-native/svelte/metro-svelte-transformer`) rather
+// than living in each consuming app: a consumer's own metro.config.js just points
+// babelTransformerPath at it.
+
+const { compile, compileModule } = require('svelte/compiler');
+const ts = require('typescript');
+const {
+  compileCssFile,
+  isStyleFile,
+  resolveUpstreamTransformer,
+} = require('@symbiote-native/css-parser');
+
+const upstreamTransformer = resolveUpstreamTransformer();
+
+// Mirrors adapters/svelte/svelte.config.js's own compilerOptions exactly (fragments:'tree' is
+// mandatory per svelte-adapter-dom-shim skill §2 — it makes the compiler emit from_tree(),
+// element-by-element via document.createElement, never from_html()'s innerHTML-on-a-<template>,
+// so the shim needs no HTML parser; css:'external' keeps Svelte from injecting a <style> into a
+// document.head that doesn't meaningfully exist). Duplicated here rather than imported from that
+// file: svelte.config.js is ESM (`export default`, loaded directly by Node-native tooling —
+// svelte-check, the language server, Vite), while this file is `require()`d by Metro directly
+// and must stay pure CommonJS with no build step of its own, exactly like
+// metro-vue-transformer.cjs.
+const COMPILER_OPTIONS = { fragments: 'tree', css: 'external', generate: 'client' };
+
+// The web-only-construct guard (svelte-adapter-dom-shim skill §7/§22) RUNS HERE, on every
+// `.svelte` Metro compiles — not just via svelte-check/the language server. `{@html}` compiles
+// to `$.html()`, which assigns to an `innerHTML` the shim does not define, so the content
+// silently never renders; editor tooling only covers a developer who has it wired up, and a
+// consuming app whose own `svelte.config.js` never registers the preprocessor would still ship
+// the broken bundle. A build-time gate is the only one nobody can be missing.
+//
+// Resolved by package self-reference rather than a relative path so the same line works from
+// `src/*.ts` in this workspace and from `build/*.js` in a published install — `exports` and
+// `publishConfig.exports` each map `./preprocessor` at their own target. Loaded lazily and once:
+// `require()` cannot pull an ESM/TS module, but `transform` is already async.
+let preprocessorPromise;
+function webOnlyConstructGuard() {
+  preprocessorPromise ??= import('@symbiote-native/svelte/preprocessor').then(mod =>
+    mod.forbidWebOnlyConstructs(),
+  );
+  return preprocessorPromise;
+}
+
+// The `<style>` preprocessor, loaded the same lazy way and for the same reason. Unlike the guard
+// above (which only throws and hands the source back untouched), this one REWRITES the source —
+// it compiles the style block into registerStyles() output and scopes every `class` in the
+// component's own markup — so its returned `code` is what compile() must be given. See
+// src/preprocessor/scoped-styles.ts for why Svelte's own `result.css` cannot be used instead.
+let scopedStylesPromise;
+function scopedStylesPreprocessor() {
+  scopedStylesPromise ??= import('@symbiote-native/svelte/scoped-styles').then(mod =>
+    mod.scopedStyles(),
+  );
+  return scopedStylesPromise;
+}
+//
+// Svelte 5's compiler strips <script lang="ts"> types structurally, with no external type
+// resolution needed (unlike @vue/compiler-sfc's compileScript, which needs registerTS + a real
+// `fs` for a type-only import from another file) — so no TypeScript/filesystem wiring is needed
+// here the way metro-vue-transformer.cjs needs it.
+function compileSvelteFile(src, filename) {
+  const { js } = compile(src, { ...COMPILER_OPTIONS, filename });
+  return js.code;
+}
+
+// `.svelte.js`/`.svelte.ts` files (adapters/svelte/src/runes/*.svelte.ts and any package that
+// ships its own runes) carry rune syntax ($state/$effect/...) OUTSIDE a component's markup, so
+// they need svelte/compiler's separate MODULE api, not compile() — compile() expects a
+// component and throws a parse error on a bare module. Uncompiled, a literal `$state(...)` call
+// hits svelte/index-client.js's dev-guard export and throws `rune_outside_svelte` the instant it
+// runs — this filename check was previously MISSING entirely, so every .svelte.ts rune file
+// shipped uncompiled and would crash on first call on a real device.
+//
+// Unlike compile() (which strips <script lang="ts"> types itself via bundled acorn-typescript),
+// compileModule() does NOT parse TypeScript at all — it throws js_parse_error on a bare
+// return-type annotation regardless of the .ts filename passed. So TS has to be stripped BEFORE
+// compileModule() ever sees the source. ts.transpileModule() (isolated-file "strip only" mode,
+// module:ESNext/target:ESNext) does exactly this: drops type-only imports/annotations, keeps
+// every used value import, and leaves $state/$effect call expressions untouched — it does not
+// require full-program type information the way metro-vue-transformer.cjs's registerTS step does.
+function stripTypeScript(src, filename) {
+  const { outputText } = ts.transpileModule(src, {
+    fileName: filename,
+    compilerOptions: { module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ESNext },
+  });
+  return outputText;
+}
+
+function compileSvelteModuleFile(src, filename) {
+  const { js } = compileModule(stripTypeScript(src, filename), { generate: 'client', filename });
+  return js.code;
+}
+
+// Exported separately so tests can assert on the compiled output directly without driving the
+// full upstream RN Babel preset.
+module.exports.compileSvelteFile = compileSvelteFile;
+module.exports.compileSvelteModuleFile = compileSvelteModuleFile;
+
+module.exports.transform = async function transform(params) {
+  if (params.filename.endsWith('.svelte')) {
+    // Throws with a message naming the RN alternative. Deliberately BEFORE compile(), so the
+    // author sees the real diagnosis rather than a downstream symptom.
+    (await webOnlyConstructGuard()).markup({ content: params.src, filename: params.filename });
+    const preprocessed = await (
+      await scopedStylesPreprocessor()
+    ).markup({ content: params.src, filename: params.filename });
+    const code = compileSvelteFile(preprocessed.code, params.filename);
+    // Re-label as .tsx so RN's transformer processes the module exactly like app source; Metro
+    // tracks the real path separately. Matches metro-vue-transformer.cjs's identical trick.
+    return upstreamTransformer.transform({
+      ...params,
+      src: code,
+      filename: params.filename + '.tsx',
+    });
+  }
+  if (params.filename.endsWith('.svelte.ts') || params.filename.endsWith('.svelte.js')) {
+    const code = compileSvelteModuleFile(params.src, params.filename);
+    return upstreamTransformer.transform({
+      ...params,
+      src: code,
+      filename: params.filename + '.tsx',
+    });
+  }
+  // A standalone style file (as opposed to a component's own <style> block, handled by the
+  // preprocessor above) — the framework-agnostic path (core/css-parser's compileCssFile), usable
+  // from this adapter's examples exactly like from any other adapter's. isStyleFile recognizes
+  // .css/.scss/.sass/.less/.styl (+ .module.*).
+  if (isStyleFile(params.filename)) {
+    const { code } = await compileCssFile(params.src, params.filename);
+    return upstreamTransformer.transform({
+      ...params,
+      src: code,
+      filename: params.filename + '.js',
+    });
+  }
+  return upstreamTransformer.transform(params);
+};
+
+// Surface the upstream cache key so RN preset changes still bust Metro's cache. The compile step
+// itself is invalidated by `--reset-cache`.
+module.exports.getCacheKey = upstreamTransformer.getCacheKey;