@symbiote-native/sqlite 0.1.0

package/src/react/sqlite-context.tsx

@@ -0,0 +1,244 @@
+// React <SQLiteProvider> + useSQLiteContext(), ported from expo-sqlite's hooks.tsx (sdk-57,
+// .vendors/expo) onto this package's own openDatabaseAsync/SQLiteDatabase. Deliberately excludes
+// `assetSource` (bundling a database from a require()'d asset needs expo-asset, out of scope for
+// this pass — see the README). React 19's built-in `use()` replaces upstream's private
+// Suspense-promise polyfill (~40 LOC of `ReactUsePromise` plumbing, unnecessary now that the
+// peer range is react >=19.0.0). Unlike upstream, `onInit` is NOT invoked here — this package's
+// own `openDatabaseAsync` already runs it internally before resolving (see
+// `IOnInitCallback`'s doc comment in `core/types.ts`), so the provider only has to forward it.
+
+import {
+  createContext,
+  memo,
+  use,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {
+  openDatabaseAsync,
+  type IOnInitCallback,
+  type ISQLiteOpenOptions,
+  type SQLiteDatabase,
+} from '../core';
+
+export type ISQLiteProviderProps = {
+  /** The name of the database file to open. */
+  databaseName: string;
+  /** The directory where the database file is located. @default defaultDatabaseDirectory */
+  directory?: string;
+  /** Open options. */
+  options?: ISQLiteOpenOptions;
+  /** The children to render. */
+  children: ReactNode;
+  /** Run once, right after the native handle opens and before children render. */
+  onInit?: IOnInitCallback;
+  /** Handle errors from SQLiteProvider. @default rethrow the error */
+  onError?: (error: Error) => void;
+  /** Enable React.Suspense integration. @default false */
+  useSuspense?: boolean;
+};
+
+const SQLiteContext = createContext<SQLiteDatabase | null>(null);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/** Structural equality, recursing into plain objects — used only to keep the memo comparator
+ * below from reopening a database when a parent re-passes a deep-equal but new `options` object. */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (!isRecord(a) || !isRecord(b)) return false;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  return (
+    aKeys.length === bKeys.length &&
+    aKeys.every(key => deepEqual(a[key], b[key]))
+  );
+}
+
+function propsAreEqual(
+  prev: ISQLiteProviderProps,
+  next: ISQLiteProviderProps,
+): boolean {
+  return (
+    prev.databaseName === next.databaseName &&
+    deepEqual(prev.options, next.options) &&
+    prev.directory === next.directory &&
+    prev.onInit === next.onInit &&
+    prev.onError === next.onError &&
+    prev.useSuspense === next.useSuspense
+  );
+}
+
+function toError(caught: unknown): Error {
+  return caught instanceof Error ? caught : new Error(String(caught));
+}
+
+/**
+ * Context.Provider component that provides a SQLite database to all children. All descendants
+ * of this component can access the database via `useSQLiteContext`.
+ */
+export const SQLiteProvider = memo(function SQLiteProvider({
+  children,
+  onError,
+  useSuspense = false,
+  ...props
+}: ISQLiteProviderProps): ReactElement | null {
+  if (onError != null && useSuspense) {
+    throw new Error(
+      'Cannot use `onError` with `useSuspense`, use error boundaries instead.',
+    );
+  }
+
+  if (useSuspense) {
+    return (
+      <SQLiteProviderSuspense {...props}>{children}</SQLiteProviderSuspense>
+    );
+  }
+
+  return (
+    <SQLiteProviderNonSuspense {...props} onError={onError}>
+      {children}
+    </SQLiteProviderNonSuspense>
+  );
+}, propsAreEqual);
+
+/** A hook for accessing the SQLite database provided by an ancestor `<SQLiteProvider>`. */
+export function useSQLiteContext(): SQLiteDatabase {
+  const context = useContext(SQLiteContext);
+  if (context == null) {
+    throw new Error('useSQLiteContext must be used within a <SQLiteProvider>');
+  }
+  return context;
+}
+
+//#region Internals
+
+function SQLiteProviderNonSuspense({
+  databaseName,
+  directory,
+  options,
+  children,
+  onInit,
+  onError,
+}: Omit<ISQLiteProviderProps, 'useSuspense'>): ReactElement | null {
+  const databaseRef = useRef<SQLiteDatabase | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    async function setup(): Promise<void> {
+      try {
+        const db = await openDatabaseAsync(
+          databaseName,
+          { ...options, onInit },
+          directory,
+        );
+        databaseRef.current = db;
+        setLoading(false);
+      } catch (caught) {
+        setError(toError(caught));
+      }
+    }
+
+    async function teardown(db: SQLiteDatabase | null): Promise<void> {
+      try {
+        await db?.closeAsync();
+      } catch (caught) {
+        setError(toError(caught));
+      }
+    }
+
+    setup();
+
+    return () => {
+      const db = databaseRef.current;
+      teardown(db);
+      databaseRef.current = null;
+      setLoading(true);
+    };
+  }, [databaseName, directory, options, onInit]);
+
+  if (error != null) {
+    const handler =
+      onError ??
+      ((caught: Error) => {
+        throw caught;
+      });
+    handler(error);
+  }
+  if (loading || databaseRef.current == null) {
+    return null;
+  }
+  return (
+    <SQLiteContext.Provider value={databaseRef.current}>
+      {children}
+    </SQLiteContext.Provider>
+  );
+}
+
+type IDatabaseCacheEntry = {
+  databaseName: string;
+  directory: string | undefined;
+  options: ISQLiteOpenOptions | undefined;
+  onInit: IOnInitCallback | undefined;
+  promise: Promise<SQLiteDatabase>;
+};
+
+// A single module-scope cache entry, mirroring upstream: only ONE suspended database is tracked
+// across the whole app at a time, and a second concurrent <SQLiteProvider useSuspense> for a
+// different database closes the first before opening the next. Faithful to upstream's own
+// `databaseInstance` shape, not a per-provider cache.
+let databaseCache: IDatabaseCacheEntry | null = null;
+
+function getDatabaseAsync(
+  databaseName: string,
+  directory: string | undefined,
+  options: ISQLiteOpenOptions | undefined,
+  onInit: IOnInitCallback | undefined,
+): Promise<SQLiteDatabase> {
+  if (
+    databaseCache != null &&
+    databaseCache.databaseName === databaseName &&
+    databaseCache.directory === directory &&
+    databaseCache.options === options &&
+    databaseCache.onInit === onInit
+  ) {
+    return databaseCache.promise;
+  }
+
+  const previous = databaseCache;
+  const promise =
+    previous != null
+      ? previous.promise
+          .then(db => db.closeAsync())
+          .then(() =>
+            openDatabaseAsync(databaseName, { ...options, onInit }, directory),
+          )
+      : openDatabaseAsync(databaseName, { ...options, onInit }, directory);
+
+  databaseCache = { databaseName, directory, options, onInit, promise };
+  return promise;
+}
+
+function SQLiteProviderSuspense({
+  databaseName,
+  directory,
+  options,
+  children,
+  onInit,
+}: Omit<ISQLiteProviderProps, 'onError' | 'useSuspense'>): ReactElement {
+  const database = use(
+    getDatabaseAsync(databaseName, directory, options, onInit),
+  );
+  return (
+    <SQLiteContext.Provider value={database}>{children}</SQLiteContext.Provider>
+  );
+}
+
+//#endregion

package/src/solid/index.ts

@@ -0,0 +1,2 @@
+export * from '../core';
+export * from './sqlite-context';

package/src/solid/sqlite-context.ts

@@ -0,0 +1,156 @@
+// Solid <SQLiteProvider> + useSQLiteContext(), ported from expo-sqlite's hooks.tsx (sdk-57,
+// .vendors/expo) onto this package's own openDatabaseAsync/SQLiteDatabase — see ../react's
+// sqlite-context.tsx for the React twin this mirrors the OBSERVABLE contract of (the React-only
+// mechanics, useEffect/use()/Suspense, don't transfer).
+//
+// Plain `.ts`, no JSX: this package's tsconfig has no per-directory override and inherits the
+// root `jsx: "react-jsx"` (set for the React entry), so a `.tsx` file here would type-check its
+// JSX against React's JSX namespace, not Solid's — the same trap `solid-jsx-namespace.md`
+// documents for the adapter itself. `createComponent` is called directly instead, exactly as
+// `packages/navigation/src/solid/stack/index.ts` does throughout.
+//
+// createResource is the right tool: it natively models pending/error/ready, and — the load-bearing
+// part — reading an ERRORED resource accessor THROWS SYNCHRONOUSLY on every read (solid-js's own
+// `read()`: `if (err !== undefined && !pr) throw err`), tracked or not. That is Solid's real
+// equivalent of upstream's `handler = (e) => { throw e }` default: no onError -> the throw surfaces
+// wherever `db()` is read (here, inside <Show>'s own tracking), and propagates through Solid's
+// error-context chain exactly like any other component/memo/effect throw in this adapter
+// (adapters/solid/src/render.ts's `catchError` + rethrow at the mount root — the tested,
+// established "unhandled async failure" convention for this Solid adapter). With onError present,
+// the fetcher calls it and resolves to `undefined` instead of throwing, so <Show> simply renders
+// nothing rather than propagating — matching upstream's "loading || !db -> render null" forever.
+//
+// Closing the previous database before opening the next reuses createResource's own
+// ResourceFetcherInfo.value (the last successfully resolved value) rather than a second piece of
+// state — it IS "the database this resource had opened before". `openedDb` is a plain closure
+// variable (not read through the resource accessor) so `onCleanup` never has to read a possibly
+// -errored resource, which would itself throw during teardown.
+//
+// assetSource is deliberately NOT ported: it needs expo-asset, out of scope (see the README).
+// useSuspense is deliberately NOT offered: Solid's own <Suspense> already composes with a plain
+// createResource-backed component with zero extra code (any ancestor <Suspense> defers on this
+// resource for free), so there is no second, opt-in code path to build the way React needs one —
+// <prop_types_split_agnostic_vs_per_adapter>'s "framework-idiom divergence" class of omission.
+
+import {
+  createComponent,
+  createContext,
+  createResource,
+  onCleanup,
+  useContext,
+  type Accessor,
+  type JSX,
+} from 'solid-js';
+import { Show } from 'solid-js';
+import {
+  openDatabaseAsync,
+  type IOnInitCallback,
+  type ISQLiteOpenOptions,
+  type SQLiteDatabase,
+} from '../core';
+
+export type ISQLiteProviderProps = {
+  /** The name of the database file to open. */
+  databaseName: string;
+  /** The directory where the database file is located. @default defaultDatabaseDirectory */
+  directory?: string;
+  /** Open options. */
+  options?: ISQLiteOpenOptions;
+  /** The children to render. */
+  children: JSX.Element;
+  /** Run once, right after the native handle opens and before children render. */
+  onInit?: IOnInitCallback;
+  /** Handle errors from SQLiteProvider. @default rethrow (propagate through Solid's error context) */
+  onError?: (error: Error) => void;
+};
+
+const SQLiteContext = createContext<SQLiteDatabase>();
+
+function toError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+
+type IDbSource = {
+  databaseName: string;
+  directory: string | undefined;
+  options: ISQLiteOpenOptions | undefined;
+  onInit: IOnInitCallback | undefined;
+};
+
+/**
+ * Context.Provider component that provides a SQLite database to all children. All descendants
+ * of this component can access the database via `useSQLiteContext`.
+ */
+export function SQLiteProvider(props: ISQLiteProviderProps): JSX.Element {
+  // The last database THIS provider successfully opened — read only by onCleanup, never through
+  // the resource accessor (which throws when the resource is in its errored state).
+  let openedDb: SQLiteDatabase | undefined;
+
+  const [db] = createResource<SQLiteDatabase | undefined, IDbSource>(
+    () => ({
+      databaseName: props.databaseName,
+      directory: props.directory,
+      options: props.options,
+      onInit: props.onInit,
+    }),
+    async (source, info) => {
+      if (info.value !== undefined) {
+        await info.value.closeAsync();
+      }
+      try {
+        const opened = await openDatabaseAsync(
+          source.databaseName,
+          { ...source.options, onInit: source.onInit },
+          source.directory,
+        );
+        openedDb = opened;
+        return opened;
+      } catch (cause) {
+        openedDb = undefined;
+        const error = toError(cause);
+        if (props.onError !== undefined) {
+          props.onError(error);
+          return undefined;
+        }
+        throw error;
+      }
+    },
+  );
+
+  onCleanup(() => {
+    void openedDb?.closeAsync();
+  });
+
+  function renderReady(database: Accessor<SQLiteDatabase>): JSX.Element {
+    return createComponent(SQLiteContext.Provider, {
+      get value(): SQLiteDatabase {
+        return database();
+      },
+      get children(): JSX.Element {
+        return props.children;
+      },
+    });
+  }
+
+  // A direct call, not createComponent(Show, …): Show is overloaded (keyed vs non-keyed), and
+  // TypeScript resolves an overloaded value against createComponent's generic Component<T> by its
+  // LAST signature only — reporting the non-keyed props object as missing `keyed: true`. Calling
+  // it directly goes through normal overload resolution instead, which picks correctly. Show's own
+  // body needs no extra untrack wrapping (it already wraps every read in its own createMemo), so
+  // nothing behavioral is lost by skipping createComponent here.
+  return Show({
+    get when(): SQLiteDatabase | undefined {
+      return db();
+    },
+    children: renderReady,
+  });
+}
+
+/** A primitive for accessing the SQLite database provided by an ancestor `<SQLiteProvider>`. */
+export function useSQLiteContext(): SQLiteDatabase {
+  const context = useContext(SQLiteContext);
+  if (context === undefined) {
+    throw new Error('useSQLiteContext must be used within a <SQLiteProvider>');
+  }
+  return context;
+}

package/src/svelte/SQLiteProvider.svelte

@@ -0,0 +1,88 @@
+<script lang="ts">
+  // SQLiteProvider: the Svelte equivalent of upstream expo-sqlite's SQLiteProvider/
+  // useSQLiteContext pair (.vendors/expo packages/expo-sqlite/src/hooks.tsx, sdk-57). Opens the
+  // database in an `$effect` (re-running whenever databaseName/directory/options/onInit change —
+  // $effect's own cleanup-then-rerun IS upstream's teardown()-then-setup() dance), renders
+  // nothing until it resolves, and hands the resolved `SQLiteDatabase` to descendants via
+  // `useSQLiteContext` (./sqlite-context).
+  //
+  // Context is provided through a BOXED GETTER set synchronously during init, mirroring
+  // navigation-context.ts: setContext only works at component-init time, but the database
+  // resolves later, so the getter is handed out immediately and its underlying `$state` is
+  // written once the effect settles.
+  //
+  // Deliberately excludes `assetSource` (needs `expo-asset`, out of scope for this package — see
+  // the core layer's own IOnInitCallback doc comment) and `useSuspense` (Svelte has no built-in
+  // Suspense primitive).
+  //
+  // Unlike upstream, `onInit` is not called from here — this package's own `openDatabaseAsync`
+  // already runs it internally before resolving (see `IOnInitCallback`'s doc comment in
+  // `core/types.ts`), so this component only forwards it through `options`.
+  import type { Snippet } from 'svelte';
+  import { openDatabaseAsync } from '../core';
+  import type { IOnInitCallback, ISQLiteOpenOptions, SQLiteDatabase } from '../core';
+  import { setSQLiteContext } from './sqlite-context';
+
+  let {
+    databaseName,
+    directory,
+    options,
+    onInit,
+    onError,
+    children,
+  }: {
+    databaseName: string;
+    directory?: string;
+    options?: ISQLiteOpenOptions;
+    onInit?: IOnInitCallback;
+    onError?: (error: Error) => void;
+    children?: Snippet;
+  } = $props();
+
+  let db = $state<SQLiteDatabase | undefined>(undefined);
+
+  setSQLiteContext({
+    get current(): SQLiteDatabase | undefined {
+      return db;
+    },
+  });
+
+  $effect(() => {
+    const name = databaseName;
+    const dir = directory;
+    const openOptions = options;
+    const init = onInit;
+
+    let cancelled = false;
+    let opened: SQLiteDatabase | undefined;
+
+    openDatabaseAsync(name, { ...openOptions, onInit: init }, dir)
+      .then(database => {
+        if (cancelled) {
+          void database.closeAsync();
+          return;
+        }
+        opened = database;
+        db = database;
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        const err = error instanceof Error ? error : new Error(String(error));
+        // Upstream default: rethrow. Svelte has no error-boundary equivalent to catch a
+        // synchronous throw from here, so "rethrow" surfaces as an unhandled rejection — the
+        // same observable failure (an uncaught error) upstream produces without `onError`.
+        if (onError) onError(err);
+        else throw err;
+      });
+
+    return () => {
+      cancelled = true;
+      db = undefined;
+      if (opened) void opened.closeAsync();
+    };
+  });
+</script>
+
+{#if db}
+  {@render children?.()}
+{/if}

package/src/svelte/index.ts

@@ -0,0 +1,6 @@
+// @symbiote-native/sqlite/svelte: SQLiteProvider + useSQLiteContext over the framework-agnostic
+// core. Mirrors packages/navigation/src/svelte/index.ts's barrel shape for a `.svelte` component.
+
+export * from '../core';
+export { default as SQLiteProvider } from './SQLiteProvider.svelte';
+export * from './sqlite-context';

package/src/svelte/sqlite-context.ts

@@ -0,0 +1,32 @@
+// Svelte context accessor for the database `<SQLiteProvider>` opens. Mirrors
+// packages/navigation/src/svelte/navigation-context.ts's boxed-getter shape: Svelte's
+// setContext only runs synchronously during component init, while the database resolves later
+// (an async openDatabaseAsync), so the provider hands out a getter object up front and mutates
+// the value it reads later instead of calling setContext once resolution finishes.
+
+import { getContext, setContext } from 'svelte';
+import type { SQLiteDatabase } from '../core';
+
+export type ISQLiteContextValue = {
+  readonly current: SQLiteDatabase | undefined;
+};
+
+const SQLITE_CONTEXT_KEY = Symbol('symbiote-sqlite-context');
+
+// Written only from <SQLiteProvider>'s own init, never by app code.
+export function setSQLiteContext(value: ISQLiteContextValue): void {
+  setContext(SQLITE_CONTEXT_KEY, value);
+}
+
+/**
+ * A global function for accessing the SQLite database provided by the nearest ancestor
+ * `<SQLiteProvider>`. Throws if called outside one — matching upstream expo-sqlite's
+ * `useSQLiteContext` (`.vendors/expo` packages/expo-sqlite/src/hooks.tsx, sdk-57).
+ */
+export function useSQLiteContext(): SQLiteDatabase {
+  const value = getContext<ISQLiteContextValue | undefined>(SQLITE_CONTEXT_KEY);
+  if (value === undefined || value.current === undefined) {
+    throw new Error('useSQLiteContext must be used within a <SQLiteProvider>');
+  }
+  return value.current;
+}

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

@@ -0,0 +1,135 @@
+// The compile-and-load harness `SQLiteProvider.smoke.test.ts` uses. Copied verbatim (mechanism,
+// not content — nothing here is navigation-specific) from
+// packages/navigation/src/svelte/svelte-compile.test-helper.ts, which is not part of that
+// package's public exports (a co-located test helper), so it can't be imported across the
+// package boundary.
+//
+// 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 navigation adapter's own smokes:
+//
+//  1. The compiled file must sit NEXT TO the real source, because its own relative imports
+//     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.
+//  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.
+
+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. 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;
+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;
+  cleanup(): void;
+};
+
+export function createSvelteHarness(
+  id: string,
+  aliases: Readonly<Record<string, string>> = {},
+): ISvelteHarness {
+  const written: string[] = [];
+  const compiledBySource = new Map<string, string>();
+
+  function outPathFor(sveltePath: string): string {
+    const stem = basename(sveltePath).replace(/\./g, '-');
+    return join(dirname(sveltePath), `.smoke-compiled-${id}-${stem}.mjs`);
+  }
+
+  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;
+    writeFileSync(outPath, rewrite(code, outPath));
+    return outPath;
+  }
+
+  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);
+    },
+    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> {
+  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/vue/index.ts

@@ -0,0 +1,2 @@
+export * from '../core';
+export * from './sqlite-context';