@forgebook/react-native-web 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ensiria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
+# @forgebook/react-native-web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React Native for [Forgebook](https://www.npmjs.com/package/forgebook): a React Native project's components drawn in the
+browser through [react-native-web](https://necolas.github.io/react-native-web/), on Vite, their props read from their
+TypeScript types as React's are.
+
+**Requirements:** React 18.2 or 19 · `react-native` 0.76 or later (its types; 0.88 is the one tested) ·
+`react-native-web` 0.21 · `forgebook` · Vite 8 · [MIT licence](https://github.com/ensiria/forgebook/blob/develop/packages/react-native-web/LICENSE)
+
+```sh
+npm install --save-dev forgebook @forgebook/react-native-web react-native-web
+```
+
+`react-native` and `react-native-web` are peers: the project's own versions are the ones drawn.
+
+## A first catalogue
+
+```ts
+// forgebook.config.ts
+import { reactNativeWeb } from "@forgebook/react-native-web/vite";
+import { defineConfig } from "forgebook";
+
+export default defineConfig({
+  framework: reactNativeWeb(),
+  title: "My app",
+  stories: ["src/**/*.stories.tsx"]
+});
+```
+
+A story file is a React story file; the types come from this package:
+
+```tsx
+import type { Meta, Story } from "@forgebook/react-native-web";
+
+import { ProfileCard } from "./ProfileCard";
+
+export default { title: "Crew/Profile card", component: ProfileCard } satisfies Meta<typeof ProfileCard>;
+
+/** A member online. */
+export const Online: Story<typeof ProfileCard> = { args: { name: "Ada", role: "First mate", isOnline: true } };
+```
+
+The app's root providers go in the preview, around every story:
+
+```tsx
+// forgebook.preview.tsx
+import type { Preview } from "@forgebook/react-native-web";
+import { initialWindowMetrics, SafeAreaProvider } from "react-native-safe-area-context";
+
+export default {
+  decorators: [
+    (Story) => (
+      <SafeAreaProvider initialMetrics={initialWindowMetrics}>
+        <Story />
+      </SafeAreaProvider>
+    )
+  ]
+} satisfies Preview;
+```
+
+A project on Storybook writes this configuration with `npx forgebook init --from storybook`: it reads
+`@storybook/react-native-web-vite` (its `modulesToTranspile` and `pluginReactOptions` become the options below), the
+older `@storybook/addon-react-native-web`, and on-device Storybook (`.rnstorybook`, or `.storybook` in a project on
+`@storybook/react-native`).
+
+## What it does
+
+What Metro does for a phone, Vite does for the catalogue:
+
+| | |
+|---|---|
+| `react-native` | resolved to `react-native-web`, exactly: `react-native-svg` and the others keep their name |
+| `.web.tsx`, `.web.ts`, `.web.jsx`, `.web.js`, `.web.mjs` | read before the plain file, as Metro does for the web; `.native` and `.ios` files are never read |
+| JSX in `.js` files, Flow types | compiled in the project's own files and in the packages written for React Native (`react-native-*`, `@react-native/*`, `expo`, `expo-*`, `@expo/*`, and those named in `nativePackages`), on the dev server and in a build |
+| `require("./logo.png")`, `require("./Font.ttf")` | the asset's address, which `Image` and Expo's `useFonts` take, in an ES module (a file that imports or exports; a CommonJS file keeps its `require`); the file is copied into a built catalogue |
+| `__DEV__`, `process.env.EXPO_OS`, `global` | defined as Metro and Expo's Babel preset define them |
+| `Platform.OS` | `"web"`, from react-native-web; `Platform.select` picks `web` |
+| A screen's `flex: 1` | each story is drawn in a root laid out as React Native's root view (a flex column): with `parameters.layout: "fullscreen"`, a screen fills the frame |
+| Props | read from the component's TypeScript types as React's: its own props, not those it takes from React Native (`ViewProps`, `PressableProps`) |
+| Agents | `forgebook story`, `forgebook mcp` and the other commands read React Native stories as React's: the packages written for React Native are pre-bundled on the dev server's Node side too, where Node would otherwise load the real `react-native` |
+
+Fonts and icons work as in an Expo web app: `useFonts` and `@expo/vector-icons` load their font files through
+`expo-font`, which runs in the browser.
+
+## Options
+
+`reactNativeWeb()` takes Storybook's React Native Web options, under these names:
+
+| Option | Storybook's | What it does |
+|---|---|---|
+| `nativePackages` | `modulesToTranspile` | Packages outside the families above that import `react-native` or ship JSX in `.js` or Flow |
+| `jsxImportSource` | `pluginReactOptions.jsxImportSource` | The JSX runtime of the project's files: `"nativewind"` for NativeWind. Forgebook's own pages keep React's |
+| `babel` | `pluginReactOptions.babel` | `{ plugins, presets }`, by module name (and options): run on the project's files, as Metro runs them. Needs `@rolldown/plugin-babel` and `@babel/core` |
+| `include`, `exclude` | `pluginReactOptions.include`, `.exclude` | The files React's plugin (Fast Refresh) and Babel apply to; the project's scripts outside `node_modules` by default |
+
+A project's `postcss.config` is run on its style sheets, as Expo does on the web (Forgebook otherwise compiles CSS
+with Lightning CSS alone); `postcss` is then the project's to install, and `jiti` or `tsx` too for a
+`postcss.config.ts`.
+
+### Reanimated
+
+```sh
+npm install --save-dev @rolldown/plugin-babel @babel/core
+```
+
+```ts
+reactNativeWeb({ babel: { plugins: ["react-native-worklets/plugin"] } }); // Reanimated 4; 3 names "react-native-reanimated/plugin"
+```
+
+The plugin compiles the project's worklets (`useAnimatedStyle`, `useDerivedValue`…), and Reanimated runs them in the
+browser, as its web support does. On the dev server's Node side, where the agents read the stories, Reanimated gets
+an animation frame from a timer, since Node draws none.
+
+### NativeWind
+
+NativeWind 4 on Tailwind 3, as its web setup asks: a `tailwind.config.js` with its preset, a `postcss.config.js`
+naming `tailwindcss`, a style sheet with Tailwind's directives imported by the preview, and its JSX runtime:
+
+```ts
+reactNativeWeb({ jsxImportSource: "nativewind" });
+```
+
+NativeWind's Babel preset (`nativewind/babel`), which Metro needs, is not needed here and is best left out: it
+compiles JSX itself, for Forgebook's own linked files too, and adds Reanimated's plugin a second time.
+
+```tsx
+// forgebook.preview.tsx
+import "./global.css";
+```
+
+`dark:` classes follow the catalogue's theme when Tailwind's `darkMode` is `"class"` and the theme switch sets a
+class on the frame: `switches: [{ ...themeSwitch(), apply: { kind: "class", prefix: "" } }]` (`themeSwitch` from
+`forgebook/switches`). With `darkMode: "media"`, NativeWind refuses the theme switch's changes.
+
+### A native module in a story
+
+Native code cannot run in a browser, so a story stands in for the module its component calls, as Storybook advises
+for its on-device version. react-native-web's `NativeModules` is a plain object: a story's `beforeEach` puts the
+stand-in there and returns what takes it away.
+
+```tsx
+import { NativeModules } from "react-native";
+
+export const Charged: Story<typeof BatteryBadge> = {
+  beforeEach: () => {
+    NativeModules["HarbourBattery"] = { getLevel: async () => 0.82 };
+    return () => {
+      Reflect.deleteProperty(NativeModules, "HarbourBattery");
+    };
+  }
+};
+```
+
+For every story, the same goes in the preview's `beforeEach`. An Expo module of the app's own
+(`requireNativeModule("HarbourBattery")`) throws on the web unless the module has a web file, as Expo's modules
+do: `HarbourBatteryModule.web.ts`, exporting `registerWebModule(...)` of a class that answers in the browser, which
+the catalogue reads before the native file. On the dev server's Node side, where the agents read the stories,
+Expo's `requireNativeModule` gives an empty object rather than throwing, so a missing stand-in fails there at the
+first call. A component whose web version differs more than a stand-in can cover
+gets a `.web.tsx` file the same way.
+
+## What does not work in a browser
+
+react-native-web draws React Native's components with the DOM; what needs the phone itself does not draw:
+
+- **Native modules.** A component that calls a module of native code (the camera, Bluetooth, a native SDK) through
+  `NativeModules`, TurboModules or Expo's `requireNativeModule` throws or gets nothing: native code cannot run in a
+  browser. Stand in for the module in its stories (above), or give the component a `.web.tsx` file.
+- **What needs the phone's UI thread.** Reanimated's animations run, as its web support runs them, on the page's
+  thread; what has no web version (`react-native-gesture-handler`'s native gestures, a worklet run on another thread
+  with `runOnRuntime`) does not.
+- **React Native's own files** (`react-native/Libraries/…`): they have no web version, and an import of one fails with
+  a message naming it.
+- **A project's `babel.config.js` and `metro.config.js`** are not read: the catalogue names its Babel plugins and JSX
+  source (above); Metro's resolver options have no counterpart. `jsxRuntime: "classic"` is not offered.
+- **What react-native-web leaves out**: the older `accessibilityState` is not drawn (write `aria-checked`,
+  `aria-disabled`… as React Native 0.71 and later accept), and the components and APIs its
+  [compatibility table](https://necolas.github.io/react-native-web/docs/react-native-compatibility/) marks as missing.
+- **Safe areas** are zero in a browser window: a story that reads them gets what its `SafeAreaProvider`'s
+  `initialMetrics` say.
+- **Expo's packages** compiled from TypeScript file by file import types as modules: those imports are let be
+  `undefined`, as Metro does, and a build names each (`SHIMMED_EXPORT`). This holds for the whole catalogue: an
+  export missing anywhere is `undefined` with that warning, not a failed build.
+
+| Import | What it is |
+|---|---|
+| `@forgebook/react-native-web` | `Meta`, `Story`, `Decorator`, `Preview`, `LogicMeta`, `LogicStory`: React's story types |
+| `@forgebook/react-native-web/vite` | `reactNativeWeb()`, the framework adapter of `forgebook.config.ts` |
+
+The rest of its exports are what the catalogue loads itself. Getting started, the catalogue's features and its
+commands: [Forgebook's README](https://github.com/ensiria/forgebook/blob/develop/packages/forgebook/README.md).

package/dist/src/mountFrame.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The frame page of a React Native catalogue: Forgebook's frame, drawing its stories with React through
+ * react-native-web, each in a root laid out as React Native's. Called by the page the plugin generates from the
+ * catalogue's configuration, not by an app.
+ *
+ * @module
+ */
+import { type FrameConfig } from "forgebook/frame";
+/**
+ * Shows the story the address names in the given element, drawn with React Native's components.
+ *
+ * @param container - the element the story renders into.
+ * @param config - the sources and the languages, as the shell's configuration gives them.
+ */
+export declare const mountFrame: (container: HTMLElement, config: Omit<FrameConfig, "renderer">) => Promise<void>;

package/dist/src/mountFrame.js

@@ -0,0 +1,16 @@
+/**
+ * The frame page of a React Native catalogue: Forgebook's frame, drawing its stories with React through
+ * react-native-web, each in a root laid out as React Native's. Called by the page the plugin generates from the
+ * catalogue's configuration, not by an app.
+ *
+ * @module
+ */
+import { mountFrame as mountForgebookFrame } from "forgebook/frame";
+import { nativeFrameRenderer } from "./nativeFrameRenderer.js";
+/**
+ * Shows the story the address names in the given element, drawn with React Native's components.
+ *
+ * @param container - the element the story renders into.
+ * @param config - the sources and the languages, as the shell's configuration gives them.
+ */
+export const mountFrame = (container, config) => mountForgebookFrame(container, { ...config, renderer: nativeFrameRenderer });

package/dist/src/nativeFrameRenderer.d.ts

@@ -0,0 +1,5 @@
+import type { FrameRenderer } from "forgebook/renderer";
+/** The root's attribute, which the tests and a catalogue's style sheet can find it by. */
+export declare const NATIVE_ROOT_ATTRIBUTE = "data-forgebook-native-root";
+/** React Native, through react-native-web, as the frame draws with it. */
+export declare const nativeFrameRenderer: FrameRenderer;

package/dist/src/nativeFrameRenderer.js

@@ -0,0 +1,54 @@
+/**
+ * Forgebook's renderer for React Native in the browser, as the frame draws with it: React's frame renderer, each story
+ * drawn inside a root that lays out as React Native's root view does.
+ *
+ * @remarks
+ * On a phone every screen sits in a root view that is a flex column filling the window, so a screen written
+ * `style={{ flex: 1 }}` fills it. A canvas of the frame is a plain block, where `flex: 1` means nothing and the screen
+ * collapses to its content. The root is that column: the whole frame's height in a `fullscreen` story, its content's
+ * height otherwise, so a `centered` story is still centred in its canvas. It is an element of the renderer's own inside the canvas, so the
+ * frame's canvas stays as the frame made it.
+ *
+ * The server render is in `nativeRenderer.ts`, which the frame page does not import, so React's server renderer never
+ * reaches it.
+ *
+ * @module
+ */
+import { reactFrameRenderer } from "@forgebook/react/frame-renderer";
+/** The root's attribute, which the tests and a catalogue's style sheet can find it by. */
+export const NATIVE_ROOT_ATTRIBUTE = "data-forgebook-native-root";
+/**
+ * A root for a story, as React Native's root view lays out: a flex column, as tall as the frame for a full-screen
+ * story.
+ *
+ * @param canvas - the canvas it goes in.
+ * @param layout - the story's layout.
+ */
+const nativeRoot = (canvas, layout) => {
+    const root = canvas.ownerDocument.createElement("div");
+    root.setAttribute(NATIVE_ROOT_ATTRIBUTE, "");
+    root.style.display = "flex";
+    root.style.flexDirection = "column";
+    root.style.flex = "1 1 auto";
+    // a fullscreen canvas is as tall as the frame: the root takes that height for a screen's `flex: 1` to fill. Only
+    // there: a centred canvas's own minimum is room to centre the story in, which the root must leave free
+    if (layout === "fullscreen")
+        root.style.minHeight = "inherit";
+    canvas.append(root);
+    return root;
+};
+/** React Native, through react-native-web, as the frame draws with it. */
+export const nativeFrameRenderer = {
+    mount: (canvas, drawing, onError) => {
+        const root = nativeRoot(canvas, drawing.story.layout);
+        const mounted = reactFrameRenderer.mount(root, drawing, onError);
+        return {
+            drawn: mounted.drawn,
+            update: mounted.update,
+            unmount: () => {
+                mounted.unmount();
+                root.remove();
+            }
+        };
+    }
+};

package/dist/src/nativeRenderer.d.ts

@@ -0,0 +1,3 @@
+import type { StoryRenderer } from "forgebook/renderer";
+/** React Native, through react-native-web, as the frame draws with it and the server tests render with it. */
+export declare const nativeRenderer: StoryRenderer;

package/dist/src/nativeRenderer.js

@@ -0,0 +1,16 @@
+/**
+ * Forgebook's renderer for React Native in the browser, whole: the frame's drawing (`nativeFrameRenderer.ts`) and
+ * React's server render, for the generated server tests, which draws no root: a server has no frame to lay out.
+ *
+ * @remarks
+ * The frame page imports `nativeFrameRenderer.ts` alone, so React's server renderer never reaches it.
+ *
+ * @module
+ */
+import { reactRenderer } from "@forgebook/react/renderer";
+import { nativeFrameRenderer } from "./nativeFrameRenderer.js";
+/** React Native, through react-native-web, as the frame draws with it and the server tests render with it. */
+export const nativeRenderer = {
+    ...nativeFrameRenderer,
+    renderToString: reactRenderer.renderToString
+};

package/dist/src/stories.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The story types for a React Native project (`import type { Meta, Story } from "@forgebook/react-native-web"`):
+ * React's, since a React Native component is a React component and its story is a React story.
+ *
+ * @remarks
+ * Named here so a project installs one package and its story files name the platform they are written for; each is
+ * React's type under the same name, so a story file can move between the two without a change. Types only.
+ *
+ * @module
+ */
+import type { AnyComponent, AnyFunction, NoComponent, Decorator as ReactDecorator, LogicMeta as ReactLogicMeta, LogicStory as ReactLogicStory, Meta as ReactMeta, Preview as ReactPreview, Story as ReactStory } from "@forgebook/react";
+/** A React Native story file's default export: `{ title, component, args… } satisfies Meta<typeof Card>`. */
+export type Meta<TComponent extends AnyComponent = NoComponent> = ReactMeta<TComponent>;
+/** A React Native story: a named export of a story file. */
+export type Story<TComponent extends AnyComponent = NoComponent> = ReactStory<TComponent>;
+/** The default export of a story file about a hook, written `satisfies LogicMeta<typeof useCart>`. */
+export type LogicMeta<TFunction extends AnyFunction> = ReactLogicMeta<TFunction>;
+/** A story about a hook: a `render` that draws a scene using it. */
+export type LogicStory = ReactLogicStory;
+/** Wraps a React Native story: a provider (safe areas, a theme), a container of a given size. */
+export type Decorator<TArgs> = ReactDecorator<TArgs>;
+/**
+ * A React Native catalogue's preview (`forgebook.preview.tsx`): decorators around every story (the providers the app
+ * puts at its root, a `SafeAreaProvider` among them), parameters under every meta's, a setup before any story.
+ */
+export type Preview = ReactPreview;

package/dist/src/vite/assetRequires.d.ts

@@ -0,0 +1,24 @@
+/**
+ * React Native's way of naming an image or a font, `require("./logo.png")`, written as the import a web bundler reads:
+ * the asset's address. Pure: the plugin (`nativePlugin.ts`) parses a module and applies it, the tests call it.
+ *
+ * @remarks
+ * Metro turns `require("./logo.png")` into an asset's number; react-native-web's `Image` and Expo's font loader take
+ * an address as well, so the call becomes the asset's default import, which Vite makes its address (and copies the
+ * file into a built catalogue). Only a module that is already an ES module is rewritten, since an import in a
+ * CommonJS file would change what it is; a module's own code keeps its lines and columns: each call is replaced by a
+ * name padded to the call's length and the imports go at the end (imports are hoisted), so its source map needs no
+ * change.
+ *
+ * @module
+ */
+/** The files a `require` names as an asset rather than a module: images, fonts, sounds and videos. */
+export declare const ASSET_FILE: RegExp;
+/**
+ * A module's `require`s of assets written as imports of their addresses.
+ *
+ * @param code - the module's code.
+ * @param program - its tree, as the parser gives it.
+ * @returns the code, or none when nothing is rewritten (no asset is required, or the module is CommonJS).
+ */
+export declare const importedAssets: (code: string, program: unknown) => string | undefined;

package/dist/src/vite/assetRequires.js

@@ -0,0 +1,141 @@
+/**
+ * React Native's way of naming an image or a font, `require("./logo.png")`, written as the import a web bundler reads:
+ * the asset's address. Pure: the plugin (`nativePlugin.ts`) parses a module and applies it, the tests call it.
+ *
+ * @remarks
+ * Metro turns `require("./logo.png")` into an asset's number; react-native-web's `Image` and Expo's font loader take
+ * an address as well, so the call becomes the asset's default import, which Vite makes its address (and copies the
+ * file into a built catalogue). Only a module that is already an ES module is rewritten, since an import in a
+ * CommonJS file would change what it is; a module's own code keeps its lines and columns: each call is replaced by a
+ * name padded to the call's length and the imports go at the end (imports are hoisted), so its source map needs no
+ * change.
+ *
+ * @module
+ */
+import { codeLiteral } from "forgebook/code-literal";
+/** The files a `require` names as an asset rather than a module: images, fonts, sounds and videos. */
+export const ASSET_FILE = /\.(?:png|jpe?g|gif|webp|bmp|svg|ttf|otf|woff2?|mp3|wav|m4a|aac|mp4|webm|mov)$/i;
+/** The statements that make a module an ES module. */
+const MODULE_STATEMENTS = new Set([
+    "ImportDeclaration",
+    "ExportNamedDeclaration",
+    "ExportDefaultDeclaration",
+    "ExportAllDeclaration"
+]);
+/** Whether a value is a syntax node. */
+const isNode = (value) => typeof value === "object" &&
+    value !== null &&
+    "type" in value &&
+    typeof value.type === "string" &&
+    "start" in value &&
+    typeof value.start === "number" &&
+    "end" in value &&
+    typeof value.end === "number";
+/** A node's property, by name: the children are read without knowing each node's shape. */
+const propertyOf = (node, name) => Object.entries(node).find(([key]) => key === name)?.[1];
+/**
+ * The asset a call requires: `require("./logo.png")` with one text naming an asset.
+ *
+ * @param node - a call.
+ * @returns the asset's specifier, or none for any other call.
+ */
+const requiredAsset = (node) => {
+    const callee = propertyOf(node, "callee");
+    const args = propertyOf(node, "arguments");
+    if (!isNode(callee) || callee.type !== "Identifier" || propertyOf(callee, "name") !== "require")
+        return undefined;
+    if (!Array.isArray(args) || args.length !== 1)
+        return undefined;
+    const [argument] = args;
+    if (!isNode(argument) || argument.type !== "Literal")
+        return undefined;
+    const value = propertyOf(argument, "value");
+    return typeof value === "string" && ASSET_FILE.test(value) ? value : undefined;
+};
+/**
+ * The nodes under a node, in the order the module writes them: its properties that are nodes or lists of nodes.
+ *
+ * @param node - the node.
+ */
+const childrenOf = (node) => Object.entries(node)
+    .filter(([key]) => key !== "type")
+    .flatMap(([, child]) => (Array.isArray(child) ? child : [child]))
+    .filter(isNode);
+/**
+ * Every `require` of an asset in a tree, in the order the module writes them.
+ *
+ * @param root - the module's tree.
+ */
+const assetRequires = (root) => {
+    const found = [];
+    const pending = [root];
+    for (let node = pending.pop(); node !== undefined; node = pending.pop()) {
+        const specifier = node.type === "CallExpression" ? requiredAsset(node) : undefined;
+        if (specifier === undefined)
+            pending.push(...childrenOf(node));
+        else
+            found.push({ start: node.start, end: node.end, specifier });
+    }
+    return found.sort((left, right) => left.start - right.start);
+};
+/**
+ * Whether a module is an ES module: it imports or exports.
+ *
+ * @param program - the module's tree.
+ */
+const isEsModule = (program) => {
+    const body = propertyOf(program, "body");
+    return (Array.isArray(body) &&
+        body.some((statement) => isNode(statement) && MODULE_STATEMENTS.has(statement.type)));
+};
+/**
+ * The start of the names the imports take: one the module does not use, so no name it declares is taken twice.
+ *
+ * @param code - the module's code.
+ */
+const namePrefix = (code) => {
+    let prefix = "__fbAsset";
+    while (code.includes(prefix))
+        prefix = `_${prefix}`;
+    return prefix;
+};
+/**
+ * A name in place of a call, keeping its line breaks, so every later line stays where it was: the name padded to the
+ * call's first line, spaces on its others (a first line shorter than the name, `require(` alone, moves only what
+ * follows the call on its last line).
+ *
+ * @param call - the call's text.
+ * @param name - the name.
+ */
+const inPlaceOf = (call, name) => {
+    const [first = "", ...rest] = call.split("\n");
+    // the shortest call, `require("a.png")`, is longer than any name up to a hundred thousand assets
+    const firstLine = first.length >= name.length ? name.padEnd(first.length, " ") : name;
+    return [firstLine, ...rest.map((line) => " ".repeat(line.length))].join("\n");
+};
+/**
+ * A module's `require`s of assets written as imports of their addresses.
+ *
+ * @param code - the module's code.
+ * @param program - its tree, as the parser gives it.
+ * @returns the code, or none when nothing is rewritten (no asset is required, or the module is CommonJS).
+ */
+export const importedAssets = (code, program) => {
+    if (!isNode(program) || !code.includes("require") || !isEsModule(program))
+        return undefined;
+    const calls = assetRequires(program);
+    if (calls.length === 0)
+        return undefined;
+    const prefix = namePrefix(code);
+    const names = new Map();
+    let rewritten = "";
+    let at = 0;
+    for (const call of calls) {
+        const name = names.get(call.specifier) ?? `${prefix}${names.size}`;
+        names.set(call.specifier, name);
+        rewritten += code.slice(at, call.start) + inPlaceOf(code.slice(call.start, call.end), name);
+        at = call.end;
+    }
+    const imports = [...names].map(([specifier, name]) => `import ${name} from ${codeLiteral(specifier)};`);
+    return `${rewritten}${code.slice(at)}\n${imports.join("\n")}\n`;
+};

package/dist/src/vite/babelPlugins.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The Babel plugins and presets a React Native catalogue names (Reanimated's worklets plugin, NativeWind's preset), run
+ * by `@rolldown/plugin-babel`, loaded only when the catalogue names some.
+ *
+ * @remarks
+ * Metro runs Babel on every file; Vite runs none. Most of what Babel does for React Native, Vite does faster
+ * (`nativePlugin.ts`), but a library's own Babel plugin rewrites code no other tool understands: Reanimated's turns a
+ * function into a worklet. So the catalogue names the plugins it needs, as Storybook's React Native Web framework asks
+ * (`pluginReactOptions.babel`), and they run on the scripts outside `node_modules` by default: the project's, and
+Forgebook's own only where they are linked rather than installed (a monorepo that develops Forgebook), where a plugin
+meant for the project's code reads them too. `@babel/core` and
+ * `@rolldown/plugin-babel` are optional peers: a catalogue without Babel installs neither.
+ *
+ * @module
+ */
+import type { PluginOption } from "vite";
+import type { ReactNativeWebOptions } from "./reactNativeWeb.ts";
+/**
+ * The Babel plugin of a catalogue's options: none without `babel`.
+ *
+ * @param options - the adapter's options.
+ * @throws when `babel` names plugins but `@rolldown/plugin-babel` is not installed, saying what to install.
+ */
+export declare const babelPlugins: (options: ReactNativeWebOptions) => Promise<PluginOption[]>;

package/dist/src/vite/babelPlugins.js

@@ -0,0 +1,35 @@
+/**
+ * A plugin or preset as Babel takes it: its name, or its name and options.
+ *
+ * @param item - the item.
+ */
+const babelItem = (item) => typeof item === "string" ? item : [item[0], item[1]];
+/**
+ * The Babel plugin of a catalogue's options: none without `babel`.
+ *
+ * @param options - the adapter's options.
+ * @throws when `babel` names plugins but `@rolldown/plugin-babel` is not installed, saying what to install.
+ */
+export const babelPlugins = async (options) => {
+    const { babel } = options;
+    const plugins = (babel?.plugins ?? []).map(babelItem);
+    const presets = (babel?.presets ?? []).map(babelItem);
+    if (plugins.length === 0 && presets.length === 0)
+        return [];
+    let load;
+    try {
+        load = await import("@rolldown/plugin-babel");
+    }
+    catch {
+        throw new Error("reactNativeWeb({ babel }) runs Babel through @rolldown/plugin-babel: install it with @babel/core " +
+            "(npm install --save-dev @rolldown/plugin-babel @babel/core)");
+    }
+    return [
+        await load.default({
+            plugins,
+            presets,
+            ...(options.include === undefined ? {} : { include: [options.include].flat() }),
+            ...(options.exclude === undefined ? {} : { exclude: [options.exclude].flat() })
+        })
+    ];
+};

package/dist/src/vite/extractDocs.d.ts

@@ -0,0 +1,7 @@
+import type { ExtractFileComponent, ExtractStoryComponent } from "forgebook/vite/adapter";
+/** The module a new story file imports its types from. */
+export declare const storyTypesModule = "@forgebook/react-native-web";
+/** Reads a story file's component, as React's adapter reads it. */
+export declare const extractStoryComponent: ExtractStoryComponent;
+/** Reads a component a file exports, as React's adapter reads it. */
+export declare const extractFileComponent: ExtractFileComponent;

package/dist/src/vite/extractDocs.js

@@ -0,0 +1,17 @@
+/**
+ * The docs module of a React Native catalogue: React's, since a React Native component is a React component, with the
+ * story types a new story file imports being this package's (`forgebook new` writes `@forgebook/react-native-web`).
+ *
+ * @remarks
+ * React's reader lists the props the project declares and leaves out those it takes from `node_modules`: a component
+ * whose props extend `ViewProps` or `PressableProps` shows its own, not React Native's hundred.
+ *
+ * @module
+ */
+import { extractFileComponent as extractReactFileComponent, extractStoryComponent as extractReactStoryComponent } from "@forgebook/react/docs";
+/** The module a new story file imports its types from. */
+export const storyTypesModule = "@forgebook/react-native-web";
+/** Reads a story file's component, as React's adapter reads it. */
+export const extractStoryComponent = (storyFile) => extractReactStoryComponent(storyFile);
+/** Reads a component a file exports, as React's adapter reads it. */
+export const extractFileComponent = (file, exportName) => extractReactFileComponent(file, exportName);

package/dist/src/vite/forgebookFiles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether a file is in one of Forgebook's packages.
+ *
+ * @param file - the file's path, absolute, its query left out.
+ */
+export declare const isForgebookFile: (file: string) => boolean;