@symbiote-native/navigation 2.0.3 → 2.1.0

package/src/svelte/stack/index.svelte

@@ -0,0 +1,224 @@
+<script lang="ts" module>
+  // Stack, the Svelte lifecycle half. The route-stack transitions (navigator-state) and the
+  // options/props folds (screen-options, render-stack) live in @symbiote-native/navigation core,
+  // shared verbatim with the React/Vue/Angular entries; here Svelte supplies the lifecycle -
+  // `$state.raw` for the pushed-route stack (its twin of useReducer: reassign from the same pure
+  // reducer), a module counter for route-key generation, `export function`s for the push/pop/
+  // replace navigator handle (Svelte's twin of Vue's expose(), reachable via `bind:this`) - plus
+  // the react-native-screens chrome per route (stack-screen.svelte). Pushing/popping a route is
+  // an ordinary child mount/unmount: RNSScreenStack diffs its RNSScreen children natively, so no
+  // imperative native command is needed here at all. Neither this nor the Screen marker imports
+  // react-native-screens' own React components (ScreenStack.tsx et al - hooks, crashes a
+  // non-React adapter); the native views are driven directly through the ViewConfig ../../register
+  // registers. See CLAUDE.md <third_party_rn_packages_are_react_only>.
+  //
+  // HOW SCREENS ARE DISCOVERED: not by reading `children`, which Svelte hands over as an opaque
+  // Snippet - the markers register themselves through the context collector (../screen-registry.ts)
+  // while the snippet renders, and the route list derives from that. The snippet is rendered
+  // inside a collapsed `symbiote-text` (../registry-host.ts) so whitespace between two markers
+  // can never become an illegal raw-text child of a native view.
+
+  // Route keys must be unique per Stack INSTANCE (Svelte has no useId); a module counter is the
+  // same mechanism the Angular entry uses.
+  let stackInstanceCounter = 0;
+
+  const STACK_ROOT_PROPS: Record<string, unknown> = { style: { flex: 1 } };
+</script>
+
+<script lang="ts">
+  import type { Component } from 'svelte';
+  import { dlog } from '@symbiote-native/engine';
+  import {
+    NAVIGATION_EVENT_STATE,
+    RNS_SCREEN_STACK_VIEW_NAME,
+    STACK_ON_FINISH_TRANSITIONING,
+    createInitialNavigatorState,
+    createNavigationEmitter,
+    navigatorReducer,
+    reconcileStackRoutes,
+    resolveStackProps,
+  } from '../../core';
+  import type {
+    INavigationEmitter,
+    INavigatorAction,
+    INavigatorHandle,
+    INavigatorState,
+    IRoute,
+  } from '../../core';
+  import { hostProps } from '../attachments';
+  import { getNavigationScope } from '../navigation-context';
+  import { SCREEN_REGISTRY_HOST_PROPS } from '../registry-host';
+  import { setScreenCollector, toRegistry, withoutScreen } from '../screen-registry';
+  import type { IRegisteredScreen } from '../screen-registry';
+  import type { IScreenProps, ISvelteScreenOptions } from '../screen-props';
+  import StackScreen from './stack-screen.svelte';
+  import type { IStackProps } from './stack-props';
+
+  let { initialRouteName, screenOptions, children }: IStackProps = $props();
+
+  // Read BEFORE this Stack establishes its own per-screen NavigationScope - becomes the `parent`
+  // link a nested screen's useNavigation().getParent() walks (e.g. this Stack rendered as a Tab
+  // screen's content reaches that Tab via this value). undefined when this Stack is the nesting
+  // root. Kept as the BOX, not its unwrapped value, so every read below sees the current one.
+  const parentScope = getNavigationScope();
+
+  const routeIdPrefix = `stack-${(stackInstanceCounter += 1)}`;
+
+  // `$state.raw` + reassignment, never a mutated array: an entry holds a component reference (a
+  // plain function) behind live getters, and a deep reactive proxy would wrap both.
+  let screens = $state.raw<IRegisteredScreen<IScreenProps['options']>[]>([]);
+  setScreenCollector<IScreenProps['options']>({
+    kind: 'stack',
+    register: screen => {
+      screens = [...screens, screen];
+    },
+    unregister: screen => {
+      screens = withoutScreen(screens, screen);
+    },
+  });
+
+  const registry = $derived(toRegistry(screens));
+
+  let routeSequence = 0;
+  function createRoute(name: string, params: unknown): IRoute<unknown> {
+    routeSequence += 1;
+    return { key: `${routeIdPrefix}-${name}-${routeSequence}`, name, params };
+  }
+
+  // The pushed stack only exists once something has dispatched; until then the state derives from
+  // whatever the markers registered. `seededState` is a PLAIN local (not `$state`), so memoizing
+  // it inside the derivation below is not a state write during a derivation - it just makes the
+  // one route-key-allocating call happen exactly once, no matter how often the derivation re-runs
+  // as markers register.
+  let pushedState = $state.raw<INavigatorState | null>(null);
+  let seededState: INavigatorState | undefined;
+
+  function seedState(): INavigatorState {
+    if (seededState !== undefined) return seededState;
+    const startRouteName = initialRouteName ?? registry.keys().next().value;
+    if (startRouteName === undefined) {
+      dlog('Stack: no <Stack.Screen> children registered');
+      // Deliberately NOT memoized: markers may still be registering, and the next derivation run
+      // should get a real initial route rather than being stuck on this placeholder.
+      return createInitialNavigatorState({ key: routeIdPrefix, name: '', params: undefined });
+    }
+    seededState = createInitialNavigatorState(
+      createRoute(startRouteName, registry.get(startRouteName)?.initialParams),
+    );
+    return seededState;
+  }
+
+  // A `<Stack.Screen>` marker can unregister while its route is still in the pushed history (a
+  // marker behind an `{#if}`, a data-driven screen list), which would leave that entry with nothing
+  // for componentFor() to mount (reconcileStackRoutes' header). The reconciliation belongs in the
+  // derivation because it is PURE - it hands back the same state reference when nothing changed, so
+  // it writes no state and cannot re-trigger itself; `dispatch` below then persists the pruned
+  // history, since it reduces over this value rather than over `pushedState`.
+  const state = $derived(reconcileStackRoutes(pushedState ?? seedState(), [...registry.keys()]));
+
+  function dispatch(action: INavigatorAction): void {
+    pushedState = navigatorReducer(state, action);
+  }
+
+  // One emitter per route.key, created lazily the first time a route is rendered and pruned once
+  // it is popped off the stack (the broadcast effect below).
+  const emitters = new Map<string, INavigationEmitter>();
+  function emitterFor(routeKey: string): INavigationEmitter {
+    let emitter = emitters.get(routeKey);
+    if (emitter === undefined) {
+      emitter = createNavigationEmitter();
+      emitters.set(routeKey, emitter);
+    }
+    return emitter;
+  }
+
+  export function push(name: string, params?: unknown): void {
+    dispatch({ type: 'push', route: createRoute(name, params) });
+  }
+  export function pop(count?: number): void {
+    dispatch({ type: 'pop', count });
+  }
+  export function popToTop(): void {
+    dispatch({ type: 'popToTop' });
+  }
+  export function popTo(key: string): void {
+    dispatch({ type: 'popTo', key });
+  }
+  export function replace(name: string, params?: unknown): void {
+    dispatch({ type: 'replace', route: createRoute(name, params) });
+  }
+  export function setParams(params: unknown, key?: string): void {
+    dispatch({ type: 'setParams', key, params });
+  }
+  export function reset(nextState: INavigatorState): void {
+    dispatch({ type: 'reset', state: nextState });
+  }
+  export function canGoBack(): boolean {
+    return state.routes.length > 1;
+  }
+
+  // The same handle, as a value, for everything that needs it INSIDE this component (the options
+  // fold's `navigation` argument, every route's NavigationScope). `bind:this` exposes the
+  // `export function`s above; this object is the internal twin of that surface.
+  const handle: INavigatorHandle = {
+    push,
+    pop,
+    popToTop,
+    popTo,
+    replace,
+    setParams,
+    reset,
+    canGoBack,
+  };
+
+  function popOne(): void {
+    dispatch({ type: 'pop', count: 1 });
+  }
+
+  // Broadcasts the router state to every still-live route's emitter (useNavigationState's source)
+  // after each commit, and prunes emitters for routes popped off the stack. Runs as an $effect
+  // rather than inline in the render path (Vue's shape), so the first broadcast lands AFTER the
+  // initial route's own screen has mounted and subscribed.
+  $effect(() => {
+    const current = state;
+    for (const route of current.routes) {
+      emitterFor(route.key).emit(NAVIGATION_EVENT_STATE, current);
+    }
+    for (const routeKey of [...emitters.keys()]) {
+      if (!current.routes.some(route => route.key === routeKey)) emitters.delete(routeKey);
+    }
+  });
+
+  // Investigation instrumentation (flicker-on-focus bug): STACK_ON_FINISH_TRANSITIONING is the
+  // native signal that the WHOLE push/pop animation has finished (as opposed to onAppear/
+  // onDisappear, which are per-screen) - logging it lets the per-screen appear/disappear
+  // timestamps be checked against the actual transition-complete moment. Kept behind DEBUG,
+  // never removed.
+  const stackProps = resolveStackProps({
+    passthrough: {
+      [STACK_ON_FINISH_TRANSITIONING]: () => dlog(`Stack: onFinishTransitioning at t=${Date.now()}`),
+    },
+  });
+
+  function optionsFor(route: IRoute<unknown>): ISvelteScreenOptions {
+    const entry = registry.get(route.name);
+    const own =
+      entry === undefined
+        ? undefined
+        : typeof entry.options === 'function'
+          ? entry.options({ route, navigation: handle })
+          : entry.options;
+    return { ...screenOptions, ...own };
+  }
+
+  function componentFor(route: IRoute<unknown>): Component | undefined {
+    const entry = registry.get(route.name);
+    if (entry === undefined) {
+      dlog(`Stack: no screen registered for route name "${route.name}"`);
+      return undefined;
+    }
+    return entry.component;
+  }
+</script>
+
+<symbiote-view p={STACK_ROOT_PROPS}><symbiote-text p={SCREEN_REGISTRY_HOST_PROPS}>{@render children?.()}</symbiote-text><svelte:element this={RNS_SCREEN_STACK_VIEW_NAME} {@attach hostProps(stackProps)}>{#each state.routes as route, index (route.key)}{@const screenComponent = componentFor(route)}{#if screenComponent !== undefined}<StackScreen {route} {index} routeCount={state.routes.length} options={optionsFor(route)} navigation={handle} emitter={emitterFor(route.key)} parentScope={parentScope?.current} component={screenComponent} onPopRequested={popOne} />{/if}{/each}</svelte:element></symbiote-view>

package/src/svelte/stack/index.ts

@@ -0,0 +1,11 @@
+// `Stack.Screen` alongside the standalone `Screen` export, matching React's and Vue's barrels.
+// A compiled Svelte component is an ordinary function object, so attaching the marker to it is
+// the same Object.assign the other entries do - and `<Stack.Screen />` resolves through Svelte's
+// member-expression component tags (verified against the real compiler).
+import StackImpl from './index.svelte';
+import Screen from '../screen.svelte';
+
+export const Stack = Object.assign(StackImpl, { Screen });
+
+export type { INavigatorHandle } from '../../core';
+export type { IStackProps } from './stack-props';

package/src/svelte/stack/stack-props.ts

@@ -0,0 +1,31 @@
+// Stack's own public prop surface, and the internal per-route prop surface stack-screen.svelte
+// takes. Both live in a plain `.ts` file for the tsc-cannot-see-a-`.svelte`-named-export reason
+// ../screen-props.ts documents.
+
+import type { Component, Snippet } from 'svelte';
+import type { INavigationEmitter, INavigatorHandle, IRoute } from '../../core';
+import type { INavigationScopeValue } from '../navigation-context';
+import type { ISvelteScreenOptions } from '../screen-props';
+
+// React's `children?: ReactNode` / Vue's default slot become a Svelte Snippet holding the
+// `<Stack.Screen>` markers.
+export type IStackProps = {
+  initialRouteName?: string;
+  screenOptions?: ISvelteScreenOptions;
+  children?: Snippet;
+};
+
+export type IStackScreenProps = {
+  route: IRoute<unknown>;
+  index: number;
+  routeCount: number;
+  options: ISvelteScreenOptions;
+  navigation: INavigatorHandle;
+  emitter: INavigationEmitter;
+  // The ambient scope the Stack itself read on mount (undefined at the nesting root) - becomes
+  // the `parent` link a nested screen's useNavigation().getParent() walks.
+  parentScope: INavigationScopeValue | undefined;
+  component: Component;
+  // Fired by RNSScreen's own onDismissed / header back button; the Stack pops one route.
+  onPopRequested: () => void;
+};

package/src/svelte/stack/stack-screen.svelte

@@ -0,0 +1,148 @@
+<script lang="ts" module>
+  import type { INavigatorPlatform } from '../../core';
+
+  // backTitleVisible defaults to `true` on both platforms per the codegen spec's own default
+  // (CT.WithDefault<boolean, 'true'>) - no ios/android divergence in v1 scope, so a single
+  // constant stands in for the per-platform injection point ISliderPlatform-style adapters use
+  // elsewhere.
+  const NAVIGATOR_PLATFORM: INavigatorPlatform = { defaultHeaderBackTitleVisible: true };
+
+  // react-native-screens' RNSScreenStackHeaderConfig.mm requires every header child to be an
+  // RNSScreenStackHeaderSubview; `type: 'searchBar'` is how it knows which slot this one fills.
+  const HEADER_SUBVIEW_PROPS: Record<string, unknown> = { type: 'searchBar' };
+</script>
+
+<script lang="ts">
+  // One mounted route's native chrome. Split out of index.svelte so each route owns its own plan
+  // derivation and its own attachments, torn down by an ordinary component unmount when the route
+  // is popped - the Svelte equivalent of Vue's per-route render-loop closure.
+  //
+  // Every react-native-screens view here goes through `<svelte:element this={'RNSScreen'}>`
+  // rather than a literal tag: their Fabric names are capitalized and un-hyphenated, so a literal
+  // tag would parse as a COMPONENT reference in a Svelte template. Their props ride an
+  // `{@attach hostProps(...)}` attachment rather than an attribute, because a dynamic tag
+  // compiles through Svelte's generic setAttribute path and never the custom-element property-SET
+  // path the object bag depends on - see ../attachments.ts for the full reasoning.
+  //
+  // The whole per-route tree is packed edge-to-edge with zero whitespace between sibling tags:
+  // svelte-adapter-dom-shim skill §16, where a stray space would become a real RCTRawText child
+  // of a react-native-screens view.
+  import { Platform, dlog } from '@symbiote-native/engine';
+  import {
+    NAVIGATION_EVENT_BLUR,
+    NAVIGATION_EVENT_FOCUS,
+    RNS_SCREEN_CONTENT_WRAPPER_VIEW_NAME,
+    RNS_SCREEN_STACK_HEADER_CONFIG_VIEW_NAME,
+    RNS_SCREEN_STACK_HEADER_SUBVIEW_VIEW_NAME,
+    RNS_SCREEN_STACK_VIEW_NAME,
+    RNS_SCREEN_VIEW_NAME,
+    RNS_SEARCH_BAR_VIEW_NAME,
+    SCREEN_ON_APPEAR,
+    SCREEN_ON_DISAPPEAR,
+    SCREEN_ON_DISMISSED,
+    SCREEN_ON_HEADER_BACK_BUTTON_CLICKED,
+    SCREEN_ON_WILL_APPEAR,
+    SCREEN_ON_WILL_DISAPPEAR,
+    buildSearchBarPassthrough,
+    resolveScreenRenderPlan,
+  } from '../../core';
+  import type { IScreenRenderPlan } from '../../core';
+  import { hostProps, searchBarRef } from '../attachments';
+  import NavigationScope from '../navigation-scope.svelte';
+  import type { INavigationScopeValue } from '../navigation-context';
+  import type { IStackScreenProps } from './stack-props';
+
+  let {
+    route,
+    index,
+    routeCount,
+    options,
+    navigation,
+    emitter,
+    parentScope,
+    // Destructured under a capitalized name because a Svelte template resolves a component tag
+    // only from a capitalized identifier.
+    component: ScreenComponent,
+    onPopRequested,
+  }: IStackScreenProps = $props();
+
+  const searchBarOptions = $derived(options.headerSearchBarOptions);
+
+  const plan = $derived.by<IScreenRenderPlan>(() =>
+    resolveScreenRenderPlan({
+      screenId: route.key,
+      index,
+      routeCount,
+      options,
+      platform: NAVIGATOR_PLATFORM,
+      isAndroid: Platform.OS === 'android',
+      screenPassthrough: {
+        [SCREEN_ON_DISMISSED]: onPopRequested,
+        [SCREEN_ON_HEADER_BACK_BUTTON_CLICKED]: onPopRequested,
+        // onAppear/onDisappear are the definitive visibility boundary (post-transition-
+        // animation), so 'focus'/'blur' fire exactly once per transition; onWillAppear/
+        // onWillDisappear fire BEFORE the animation runs, so wiring them to emit() too would
+        // double-invoke useFocusEffect per transition - they only get a debug log here.
+        [SCREEN_ON_WILL_APPEAR]: () =>
+          dlog(`Stack: route "${route.name}" will appear at t=${Date.now()}`),
+        [SCREEN_ON_APPEAR]: () => {
+          dlog(`Stack: route "${route.name}" appeared (focus) at t=${Date.now()}`);
+          emitter.emit(NAVIGATION_EVENT_FOCUS);
+        },
+        [SCREEN_ON_WILL_DISAPPEAR]: () =>
+          dlog(`Stack: route "${route.name}" will disappear at t=${Date.now()}`),
+        [SCREEN_ON_DISAPPEAR]: () => {
+          dlog(`Stack: route "${route.name}" disappeared (blur) at t=${Date.now()}`);
+          emitter.emit(NAVIGATION_EVENT_BLUR);
+        },
+      },
+      // The imperative SearchBarCommands ref rides its OWN attachment on the RNSSearchBar leaf
+      // below (../attachments.ts), never this passthrough map - same split Angular uses, so no
+      // `ref` key can leak through to Fabric as a real prop.
+      searchBarPassthrough: searchBarOptions
+        ? buildSearchBarPassthrough(searchBarOptions, message =>
+            dlog(`Stack: route "${route.name}" ${message}`),
+          )
+        : undefined,
+    }),
+  );
+
+  // Investigation instrumentation (flicker-on-focus bug): the actual timing/z-order-relevant
+  // values resolved onto the native RNSScreen, once per mounted route - rules a stackAnimation/
+  // transitionDuration mismatch against react-native-screens' own native default in or out. Kept
+  // behind DEBUG, never removed.
+  let hasLoggedScreenProps = false;
+  $effect(() => {
+    const screenProps = plan.screenProps;
+    if (hasLoggedScreenProps) return;
+    hasLoggedScreenProps = true;
+    dlog(
+      `Stack: route "${route.name}" resolved screen props ` +
+        `stackAnimation=${String(screenProps.stackAnimation)} ` +
+        `stackPresentation=${String(screenProps.stackPresentation)} ` +
+        `transitionDuration=${String(screenProps.transitionDuration)} ` +
+        `gestureEnabled=${String(screenProps.gestureEnabled)} at t=${Date.now()}`,
+    );
+  });
+
+  // A modal/formSheet screen has no UINavigationController of its own on iOS - nest an inner
+  // RNSScreenStack/RNSScreen purely to host the native header bar (see isHeaderInModal's comment
+  // in core/render-stack.ts). Skipping this leaves RNSScreenStackHeaderConfig with no navigation
+  // controller to attach to, so the header silently never renders. activityState mirrors the
+  // outer screen's own value - RNSScreen.mm treats an unset/inactive nested screen as not yet
+  // pushed, leaving it parked at its pre-push transition position.
+  const innerStackProps = $derived<Record<string, unknown>>({ style: plan.innerStackStyle });
+  const innerScreenProps = $derived<Record<string, unknown>>({
+    style: plan.innerScreenStyle,
+    activityState: plan.activityState,
+  });
+
+  const scopeValue = $derived<INavigationScopeValue>({
+    route,
+    navigation,
+    emitter,
+    parent: parentScope,
+  });
+</script>
+
+{#snippet chrome()}<svelte:element this={RNS_SCREEN_STACK_HEADER_CONFIG_VIEW_NAME} {@attach hostProps(plan.headerConfig.props)}>{#if plan.searchBarProps !== undefined}<svelte:element this={RNS_SCREEN_STACK_HEADER_SUBVIEW_VIEW_NAME} {@attach hostProps(HEADER_SUBVIEW_PROPS)}><svelte:element this={RNS_SEARCH_BAR_VIEW_NAME} {@attach hostProps(plan.searchBarProps)} {@attach searchBarRef(searchBarOptions?.ref)}></svelte:element></svelte:element>{/if}</svelte:element><svelte:element this={RNS_SCREEN_CONTENT_WRAPPER_VIEW_NAME} {@attach hostProps(plan.contentWrapperProps)}><NavigationScope value={scopeValue}><ScreenComponent /></NavigationScope></svelte:element>{/snippet}<svelte:element this={plan.screenViewName} {@attach hostProps(plan.screenProps)}>{#if plan.inModal}<svelte:element this={RNS_SCREEN_STACK_VIEW_NAME} {@attach hostProps(innerStackProps)}><svelte:element this={RNS_SCREEN_VIEW_NAME} {@attach hostProps(innerScreenProps)}>{@render chrome()}</svelte:element></svelte:element>{:else}{@render chrome()}{/if}</svelte:element>

package/src/svelte/svelte-ambient.d.ts

@@ -0,0 +1,6 @@
+// Pulls in svelte's ambient global declarations ($state/$effect/...) for this package's tsc
+// program. adapters/svelte gets these for free because render.ts does a real value import from
+// 'svelte' (any file in a program importing a module loads its ambient globals for the whole
+// program); this package has no such import, so a triple-slash reference does the same job
+// explicitly rather than relying on an incidental side-effect.
+/// <reference types="svelte" />

package/src/svelte/svelte-compile.test-helper.ts

@@ -0,0 +1,143 @@
+// The compile-and-load harness every `*.smoke.test.ts` in this folder uses.
+//
+// There is no `.svelte`-aware bundler wired into this repo's vitest (svelte-adapter-dom-shim
+// skill §15, a deliberate choice), so a test that needs to RUN a component compiles the real
+// source with `svelte/compiler` itself and dynamic-`import()`s the output. Three rules fall out
+// of that, all of them learned the hard way in the adapter's own smokes:
+//
+//  1. The compiled file must sit NEXT TO the real source, because its own relative imports
+//     (`./stack-screen.svelte`, `../navigation-context`) resolve from wherever the compiled FILE
+//     lives, not from where the source did.
+//  2. Every `.svelte` specifier inside the compiled output has to be rewritten to the compiled
+//     twin, recursively - a navigator pulls in stack-screen.svelte, which pulls in
+//     navigation-scope.svelte.
+//  3. Node's `import()` caches by path, so re-writing new content to a path a previous test
+//     already imported hands back the STALE module. Every harness instance therefore stamps its
+//     own id into the filenames.
+//
+// `aliases` covers the one case relative rewriting cannot: `@symbiote-native/svelte`'s main
+// barrel re-exports real `.svelte` sources, which Vite's plain (svelte-plugin-free) transform
+// cannot parse at all - so a test that needs something from it points the specifier at a module
+// it compiled itself instead.
+
+import { compile } from 'svelte/compiler';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+// The real Metro pipeline's own `.svelte.ts` compile step (TS-strip, then `compileModule` to
+// desugar the runes). Reused rather than reimplemented, so the runes in ./runes are exercised
+// through the ACTUAL shipped compile path - a bare, uncompiled `$state`/`$effect` call throws
+// `rune_outside_svelte` at runtime. Default-imported because it is a `.cjs` module.
+import metroSvelteTransformer from '@symbiote-native/svelte/metro-svelte-transformer';
+
+const {
+  compileSvelteModuleFile,
+}: {
+  compileSvelteModuleFile: (source: string, filename: string) => string;
+} = metroSvelteTransformer;
+
+const COMPILE_OPTIONS = { generate: 'client', fragments: 'tree', css: 'external' } as const;
+// The §16 tell: a single-space text entry inside a compiled `from_tree([...])` array, i.e. real
+// whitespace between two sibling nodes that became a real RCTRawText engine node.
+const STRAY_WHITESPACE_PATTERN = /,\s*'\s+'\s*,/g;
+const SVELTE_SPECIFIER_PATTERN = /(['"])(\.{1,2}\/[^'"]*\.svelte)\1/g;
+
+export type ISvelteHarness = {
+  // Compile a real `.svelte` file plus everything it imports; returns the compiled entry path.
+  compileFile(sveltePath: string): string;
+  // Compile an inline fixture written into `dir`, so its own relative imports resolve from there.
+  compileSource(dir: string, name: string, source: string): string;
+  // The number of stray single-space text entries across everything compiled so far - must be 0.
+  strayWhitespaceCount(): number;
+  cleanup(): void;
+};
+
+export function createSvelteHarness(
+  id: string,
+  aliases: Readonly<Record<string, string>> = {},
+): ISvelteHarness {
+  const written: string[] = [];
+  const compiledBySource = new Map<string, string>();
+  let strayWhitespace = 0;
+
+  function outPathFor(sveltePath: string): string {
+    const stem = basename(sveltePath).replace(/\./g, '-');
+    return join(dirname(sveltePath), `.smoke-compiled-${id}-${stem}.mjs`);
+  }
+
+  // `./` is prepended unless the path already walks up: every compiled file's basename STARTS
+  // with a dot (`.smoke-compiled-...`), so a bare "starts with '.'" check would leave it looking
+  // like a bare package specifier to the resolver.
+  function relativeSpecifier(fromFile: string, target: string): string {
+    const specifier = relative(dirname(fromFile), target);
+    return specifier.startsWith('..') ? specifier : `./${specifier}`;
+  }
+
+  function rewrite(code: string, outPath: string): string {
+    let rewritten = code.replace(
+      SVELTE_SPECIFIER_PATTERN,
+      (_match, quote: string, spec: string) => {
+        const childSource = resolve(dirname(outPath), spec);
+        const childOut = compileFile(childSource);
+        return `${quote}${relativeSpecifier(outPath, childOut)}${quote}`;
+      },
+    );
+    for (const [specifier, target] of Object.entries(aliases)) {
+      rewritten = rewritten.split(`'${specifier}'`).join(`'${relativeSpecifier(outPath, target)}'`);
+      rewritten = rewritten.split(`"${specifier}"`).join(`"${relativeSpecifier(outPath, target)}"`);
+    }
+    return rewritten;
+  }
+
+  function emit(sveltePath: string, source: string, isRuneModule: boolean): string {
+    const outPath = outPathFor(sveltePath);
+    // Registered BEFORE compiling so a cycle between two components terminates.
+    compiledBySource.set(sveltePath, outPath);
+    written.push(outPath);
+    const filename = basename(sveltePath);
+    const code = isRuneModule
+      ? compileSvelteModuleFile(source, `${filename}.ts`)
+      : compile(source, { ...COMPILE_OPTIONS, filename }).js.code;
+    strayWhitespace += (code.match(STRAY_WHITESPACE_PATTERN) ?? []).length;
+    writeFileSync(outPath, rewrite(code, outPath));
+    return outPath;
+  }
+
+  // A `./x.svelte` specifier is a COMPONENT when `x.svelte` exists on disk and a rune MODULE
+  // when `x.svelte.ts` does - the same two-way split the Metro transformer makes on the real
+  // filename.
+  function compileFile(sveltePath: string): string {
+    const cached = compiledBySource.get(sveltePath);
+    if (cached !== undefined) return cached;
+    const runeModulePath = `${sveltePath}.ts`;
+    if (!existsSync(sveltePath) && existsSync(runeModulePath)) {
+      return emit(sveltePath, readFileSync(runeModulePath, 'utf8'), true);
+    }
+    return emit(sveltePath, readFileSync(sveltePath, 'utf8'), false);
+  }
+
+  return {
+    compileFile,
+    compileSource(dir, name, source) {
+      return emit(join(dir, `${name}.svelte`), source, false);
+    },
+    strayWhitespaceCount: () => strayWhitespace,
+    cleanup() {
+      for (const file of written) rmSync(file, { force: true });
+      written.length = 0;
+      compiledBySource.clear();
+    },
+  };
+}
+
+// The compiled module's default export, narrowed without a cast so a test never silently mounts
+// `undefined`.
+export async function loadComponent(compiledPath: string): Promise<unknown> {
+  // pathToFileURL rather than a `file://${...}` template: the literal form makes Vite's import
+  // analyzer log an "Invalid file URL" warning for the un-substituted placeholder.
+  const mod: unknown = await import(pathToFileURL(compiledPath).href);
+  if (mod === null || typeof mod !== 'object' || !('default' in mod)) {
+    throw new Error(`${compiledPath} produced no default export`);
+  }
+  return mod.default;
+}

package/src/svelte/tab-screen-props.ts

@@ -0,0 +1,20 @@
+// Tab.Screen's public prop surface - mirrors screen-props.ts minus the stack-only concepts (no
+// push/pop lifecycle, no header search bar). Split out of `tab-screen.svelte` for the same
+// tsc-cannot-see-a-`.svelte`-named-export reason screen-props.ts documents.
+
+import type { Component } from 'svelte';
+import type { IRoute, ITabNavigatorHandle, ITabOptions } from '../core';
+
+export type ITabScreenOptionsArgs = {
+  route: IRoute<unknown>;
+  navigation: ITabNavigatorHandle;
+};
+
+export type ITabScreenOptionsResolver = (args: ITabScreenOptionsArgs) => ITabOptions;
+
+export type ITabScreenProps = {
+  name: string;
+  component: Component;
+  options?: ITabOptions | ITabScreenOptionsResolver;
+  initialParams?: unknown;
+};

package/src/svelte/tab-screen.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+  // Tab.Screen: a declarative marker that paints nothing, registered through the same
+  // context-based collector Stack.Screen uses (screen-registry.ts). The `'tab'` kind tag is what
+  // stops it from silently registering with an ancestor Stack/Drawer when it is written in the
+  // wrong place. See CLAUDE.md <third_party_rn_packages_are_react_only> - this and Tab import
+  // nothing from react-native.
+  import { collectScreen } from './screen-registry';
+  import type { ITabScreenProps } from './tab-screen-props';
+
+  let { name, component, options, initialParams }: ITabScreenProps = $props();
+
+  collectScreen('tab', {
+    get name(): ITabScreenProps['name'] {
+      return name;
+    },
+    get component(): ITabScreenProps['component'] {
+      return component;
+    },
+    get options(): ITabScreenProps['options'] {
+      return options;
+    },
+    get initialParams(): unknown {
+      return initialParams;
+    },
+  });
+</script>