fix(framework-react-lynx-web): emit lynx static assets at output root

The `.web.bundle` embeds asset references as relative paths like
`static/image/foo.png`. web-core hands those strings to the shadow DOM
unchanged, so the browser resolves them against `iframe.html` —
producing root-level `/static/image/foo.png` requests. Previously we
copied them under `/lynx-bundles/static/image/`, which 404ed once
`storybook-static/` was deployed behind a plain static server.

- Build: `output.copy` now writes `static/**` to the output root
  (alongside storybook's own `static/{js,css,wasm}`, which don't
  overlap with lynx's `static/{image,font,svg}`).
- Dev: proxy `/static/{image,font,svg}` to rspeedy so the same
  resolution works through the in-process dev server.

Also splits `preview.ts` into a sync render entry and an async
`preview-runtime.ts` side-effect entry. `@lynx-js/web-core` uses
top-level await (WASM init), which promotes the importing module to
async — and Storybook's `composeConfigs` reads `render` synchronously
via `__webpack_require__`, yielding a Promise whose `.render` is
undefined. The framework's render then loses to the web-components
default and the story renders as "component annotation is missing".
Keeping the render export in a sync module preserves the fields.

Author: fi3ework

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
   "assist": {
     "includes": ["**", "!**/*.vue"],
     "actions": { "source": { "organizeImports": "on" } }

packages/framework-react-lynx-web/build-config.ts

@@ -11,6 +11,11 @@ const config: BuildEntries = {
         exportEntries: ['./preview'],
         entryPoint: './src/preview.ts',
       },
+      {
+        exportEntries: ['./preview-runtime'],
+        entryPoint: './src/preview-runtime.ts',
+        dts: false,
+      },
     ],
     node: [
       {

packages/framework-react-lynx-web/package.json

@@ -35,7 +35,8 @@
     "./preview": {
       "types": "./dist/preview.d.ts",
       "default": "./dist/preview.js"
-    }
+    },
+    "./preview-runtime": "./dist/preview-runtime.js"
   },
   "files": [
     "dist/**/*",
@@ -70,7 +71,7 @@
     "storybook": "^10.1.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.6.0"
   },
   "publishConfig": {
     "access": "public"
@@ -80,7 +81,8 @@
       "./src/node/index.ts",
       "./src/index.ts",
       "./src/preset.ts",
-      "./src/preview.ts"
+      "./src/preview.ts",
+      "./src/preview-runtime.ts"
     ],
     "platform": "node"
   }

packages/framework-react-lynx-web/src/preset.ts

@@ -1,7 +1,6 @@
 import { existsSync } from 'node:fs'
 import type { ServerResponse } from 'node:http'
-import { createRequire } from 'node:module'
-import { dirname, join, resolve } from 'node:path'
+import { join, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { mergeRsbuildConfig } from '@rsbuild/core'
 import type { PresetProperty } from 'storybook/internal/types'
@@ -12,29 +11,37 @@ import type { FrameworkOptions, StorybookConfig } from './types'
  * own node_modules. This matters because pnpm can install multiple rspeedy
  * variants under different peer-dep contexts; the user's `pluginReactLynx`
  * (and the rest of their lynx.config) is bound to the rspeedy instance in
- * THEIR project. If we import the framework's own copy we get a different
- * module instance and the React Lynx loader/plugin chain silently no-ops
- * (manifesting as JSX parse errors).
+ * THEIR project. If we imported the framework's own copy we would get a
+ * different module instance and the React Lynx loader/plugin chain would
+ * silently no-op (manifesting as JSX parse errors).
+ *
+ * Note: `createRequire(...).resolve('@lynx-js/rspeedy')` would fail with
+ * `ERR_PACKAGE_PATH_NOT_EXPORTED` because the package's `exports."."`
+ * defines only an `import` condition (no `require`). That's why we use the
+ * two-arg form of `import.meta.resolve`, which walks the ESM resolver from
+ * the user's project root — stable since Node 20.6 (engines.node enforces).
  */
 async function importUserRspeedy(
   projectRoot: string,
 ): Promise<typeof import('@lynx-js/rspeedy')> {
-  // `require.resolve('@lynx-js/rspeedy')` fails: the package is pure-ESM
-  // with no CJS `main`. We resolve `./package.json` (which IS in the
-  // package's `exports` field) and then point at the stable ESM entry
-  // `./dist/index.js`. We don't read the exports field at runtime because
-  // it has been stable since 0.10.x and reading + parsing JSON adds nothing
-  // beyond a runtime-detection illusion of safety.
-  const require = createRequire(join(projectRoot, 'package.json'))
-  const pkgJsonPath = require.resolve('@lynx-js/rspeedy/package.json')
-  const entryAbs = join(dirname(pkgJsonPath), 'dist/index.js')
-  return import(pathToFileURL(entryAbs).href)
+  const parentUrl = pathToFileURL(join(projectRoot, 'package.json')).href
+  const entryUrl = import.meta.resolve('@lynx-js/rspeedy', parentUrl)
+  return import(entryUrl)
 }
 
 export const previewAnnotations: PresetProperty<'previewAnnotations'> = async (
   input = [],
 ) => {
-  return [...input, fileURLToPath(import.meta.resolve('./preview'))]
+  // Order matters: `preview-runtime` is async (top-level await from
+  // @lynx-js/web-core's WASM init) and contributes no annotations, while
+  // `preview` is sync and contributes `render` / `renderToCanvas`. Both are
+  // appended AFTER the renderer's defaults so our render wins composeConfigs.
+  // See the long note at the top of src/preview.ts for background.
+  return [
+    ...input,
+    fileURLToPath(import.meta.resolve('./preview-runtime')),
+    fileURLToPath(import.meta.resolve('./preview')),
+  ]
 }
 
 export const core: PresetProperty<'core'> = async (config, options) => {
@@ -84,7 +91,7 @@ export const staticDirs: PresetProperty<'staticDirs'> = async (
   if (lynxConfigPath) return input
 
   const distDir = join(projectRoot, 'dist')
-  const bundlePrefix = frameworkOptions.lynxBundlePrefix ?? '/lynx-bundles'
+  const bundlePrefix = normalizeBundlePrefix(frameworkOptions.lynxBundlePrefix)
   return [...input, { from: distDir, to: bundlePrefix }]
 }
 
@@ -123,6 +130,56 @@ interface RspeedyState {
   setupPromise?: Promise<void>
 }
 
+const CSS_FILE_RE = /\.(?:css|scss|sass|less|styl|stylus)$/i
+
+/**
+ * Normalize a user-supplied URL prefix so downstream code can treat it
+ * consistently: leading slash, no trailing slash (`/lynx-bundles`). The
+ * proxy config needs the leading slash and `pathRewrite` pattern, while
+ * `output.copy.to` wants a relative directory without the leading slash.
+ * Accepting either form from the user keeps the DX forgiving.
+ */
+function normalizeBundlePrefix(raw: string | undefined): string {
+  const value = (raw ?? '/lynx-bundles').trim() || '/lynx-bundles'
+  const withLeading = value.startsWith('/') ? value : `/${value}`
+  return withLeading.endsWith('/') && withLeading.length > 1
+    ? withLeading.slice(0, -1)
+    : withLeading
+}
+
+/**
+ * Return true if the rebuild's modified file set contains at least one
+ * style file. We walk the rspack Stats/MultiStats and collect
+ * `compilation.modifiedFiles` (a `ReadonlySet<string>` of absolute paths
+ * rspack populated from its watcher before the current rebuild ran). Any
+ * source file change that ends in a CSS-family extension counts — TSX/TS
+ * edits alone return `false` and let rsbuild's WebSocket HMR handle them.
+ */
+function hasCssChange(stats: unknown): boolean {
+  // Duck-typed against Rspack.Stats | Rspack.MultiStats to avoid a
+  // framework-level dependency on @rspack/core just for a type.
+  const candidates: unknown[] = []
+  const anyStats = stats as {
+    stats?: unknown[]
+    compilation?: { modifiedFiles?: ReadonlySet<string> }
+  }
+  if (Array.isArray(anyStats.stats)) {
+    candidates.push(...anyStats.stats)
+  } else {
+    candidates.push(anyStats)
+  }
+  for (const s of candidates) {
+    const modified = (
+      s as { compilation?: { modifiedFiles?: ReadonlySet<string> } }
+    ).compilation?.modifiedFiles
+    if (!modified) continue
+    for (const file of modified) {
+      if (CSS_FILE_RE.test(file)) return true
+    }
+  }
+  return false
+}
+
 const RSPEEDY_STATE_KEY = Symbol.for(
   'storybook-react-lynx-web-rsbuild.rspeedy.state',
 )
@@ -181,13 +238,19 @@ async function setupRspeedyDev(
         environment: ['web'],
       })
 
-      // Drive HMR reload broadcasts from rspeedy's compiler hook. We fire on
-      // every non-first rebuild — the lynx web runtime has no per-asset HMR
-      // (pluginReactLynx disables it for the `web` env, see lynx-stack
-      // packages/rspeedy/plugin-react/src/entry.ts), so any source change
-      // requires a full <lynx-view> reload regardless of which file changed.
-      rspeedy.onDevCompileDone(({ isFirstCompile }) => {
+      // Drive dev reload broadcasts from rspeedy's compiler hook, but only
+      // for **CSS-ish** rebuilds. Background-thread JS already has real HMR
+      // via rsbuild's standard WebSocket client embedded in the web bundle
+      // (pluginReactLynx only skips its own HMR prepends for the `web` env
+      // — see lynx-stack packages/rspeedy/plugin-react/src/entry.ts — not
+      // rsbuild's normal ones), so broadcasting on every rebuild would
+      // force-reload <lynx-view> and clobber the JS HMR's state
+      // preservation. CSS edits, on the other hand, have no upstream HMR
+      // path: we still need to ping preview.ts so it force-refetches the
+      // template via the `?t=` cache-bust (see note in preview.ts).
+      rspeedy.onDevCompileDone(({ isFirstCompile, stats }) => {
         if (isFirstCompile) return
+        if (!hasCssChange(stats)) return
         for (const client of state.sseClients) {
           client.write('data: content-changed\n\n')
         }
@@ -242,7 +305,7 @@ export const rsbuildFinal: StorybookConfig['rsbuildFinal'] = async (
     typeof framework === 'string' ? {} : framework.options || {}
 
   const projectRoot = resolveProjectRoot(options.configDir)
-  const bundlePrefix = frameworkOptions.lynxBundlePrefix ?? '/lynx-bundles'
+  const bundlePrefix = normalizeBundlePrefix(frameworkOptions.lynxBundlePrefix)
   const lynxConfig = findLynxConfig(
     projectRoot,
     frameworkOptions.lynxConfigPath,
@@ -269,6 +332,19 @@ export const rsbuildFinal: StorybookConfig['rsbuildFinal'] = async (
             changeOrigin: true,
             pathRewrite: { [`^${bundlePrefix}`]: '' },
           },
+          // Lynx-emitted static assets (images, fonts, svg) are referenced
+          // by the .web.bundle as *relative* URLs like `static/image/foo.png`.
+          // web-core hands those strings to the DOM unchanged, so the browser
+          // resolves them against `iframe.html` (root-absolute), NOT against
+          // the bundle URL. We route those specific subpaths to rspeedy's
+          // dev server to match how build-mode copies them to the root.
+          //
+          // Scoped to subpaths lynx actually uses to avoid colliding with
+          // storybook's own `/static/js`, `/static/css`, `/static/wasm`,
+          // which are served by the rsbuild dev middleware.
+          '/static/image': { target: origin, changeOrigin: true },
+          '/static/font': { target: origin, changeOrigin: true },
+          '/static/svg': { target: origin, changeOrigin: true },
           '/.rspeedy': {
             target: origin,
             changeOrigin: true,
@@ -304,6 +380,18 @@ export const rsbuildFinal: StorybookConfig['rsbuildFinal'] = async (
   // Storybook output as static assets. The source directory comes from
   // `rspeedy.context.distPath` so a user-customized `output.distPath.root`
   // is honored.
+  //
+  // Copy layout:
+  //   - `.web.bundle` files → `lynx-bundles/` (isolated prefix; user's
+  //     `parameters.lynx.url` points here).
+  //   - `static/**` → output root, preserving the `static/` prefix. These
+  //     are referenced from inside the bundle as relative paths like
+  //     `static/image/foo.png`, which the browser resolves against
+  //     `iframe.html` → `/static/image/foo.png`. They MUST land at the
+  //     root, not under `lynx-bundles/`, otherwise image/font lookups 404.
+  //     (The collision surface with storybook's own emitted files is
+  //     empty by construction: storybook uses `static/{js,css,wasm}`
+  //     while lynx uses `static/{image,font,svg}`.)
   if (lynxConfig && !isDev) {
     const rspeedyDistDir = await runRspeedyBuild(projectRoot, lynxConfig)
 
@@ -318,7 +406,7 @@ export const rsbuildFinal: StorybookConfig['rsbuildFinal'] = async (
           {
             from: 'static/**/*',
             context: rspeedyDistDir,
-            to: `${bundlePrefix.slice(1)}/`,
+            to: '',
           },
         ],
       },

packages/framework-react-lynx-web/src/preview-runtime.ts

@@ -0,0 +1,23 @@
+// Side-effect-only preview entry: registers the <lynx-view> custom element
+// (from `@lynx-js/web-core`), pulls in the full `@lynx-js/web-elements`
+// element set, and injects web-elements' layout CSS into document.head so
+// <lynx-view>'s shadow DOM can mirror it via inject-head-links.
+//
+// This file becomes an async module because `@lynx-js/web-core` ships with
+// top-level await (WASM init). That's why the render/renderToCanvas exports
+// live in the sibling `./preview.ts` instead of here — see the long note at
+// the top of that file. Keeping the two responsibilities in separate entries
+// lets the sync preview contribute exports to Storybook's composeConfigs
+// while this async entry runs its side effects independently.
+
+// @ts-expect-error -- ?inline import resolves CSS to a string at build time
+import webElementsCSS from '@lynx-js/web-elements/index.css?inline'
+import '@lynx-js/web-core'
+import '@lynx-js/web-elements/all'
+
+const webElementsLink = document.createElement('link')
+webElementsLink.rel = 'stylesheet'
+webElementsLink.href = URL.createObjectURL(
+  new Blob([webElementsCSS], { type: 'text/css' }),
+)
+document.head.appendChild(webElementsLink)