one 2.10.0 → 2.11.1

package/src/cli/iosLinkSetAnalysis.ts

@@ -0,0 +1,411 @@
+// which names of the One api a module reads, for the ios link set. the production
+// bundle's modules are parsed and every read of the `One` namespace, of `One.iOS`
+// and of a `one` entry point's exports is recorded. the apps this serves use no eval
+// and build no names at runtime, so a name that is read statically is the whole story
+// and a computed read keeps every group.
+import { parseSync } from 'oxc-parser'
+
+export type LinkSetCatalog = {
+  groups: Record<
+    string,
+    {
+      components: string[]
+      hybrids: string[]
+      uses?: string[]
+      modifiers?: string[]
+      slots?: string[]
+      values?: string[]
+    }
+  >
+}
+
+export type LinkSetUsage = {
+  // names read off the `One` namespace, `One.iOS` or an entry point's exports
+  names: Set<string>
+  // modifier, slot and value keys written as a string or a property name
+  keys: Set<string>
+  // the namespace was used in a way the analysis cannot follow
+  all: boolean
+}
+
+export const emptyUsage = (): LinkSetUsage => ({ names: new Set(), keys: new Set(), all: false })
+
+// what a binding holds: the exports of a `one` entry point, the One object or One.iOS
+type Held = 'module' | 'one' | 'ios'
+
+type Node = { type: string; [key: string]: any }
+
+const oneSource = /^one(?:\/.*)?$/
+
+// ts nodes that hold values; every other ts node is a type and is not read
+const valueTs = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSNonNullExpression',
+  'TSTypeAssertion',
+  'TSInstantiationExpression',
+  'TSParameterProperty',
+  'TSEnumDeclaration',
+  'TSEnumBody',
+  'TSEnumMember',
+  'TSModuleDeclaration',
+  'TSModuleBlock',
+  'TSExportAssignment',
+  'TSImportEqualsDeclaration',
+])
+
+// the property names a group's features are reached by, and the keys that name them
+export function catalogNames(catalog: LinkSetCatalog) {
+  const names = new Map<string, string[]>()
+  const keys = new Map<string, string[]>()
+  const add = (map: Map<string, string[]>, name: string, group: string) =>
+    map.set(name, [...(map.get(name) ?? []), group])
+  for (const [group, entry] of Object.entries(catalog.groups)) {
+    for (const component of entry.components) add(names, component.replace(/^OneNative/, ''), group)
+    for (const use of entry.uses ?? []) add(names, use, group)
+    for (const key of [
+      ...(entry.modifiers ?? []),
+      ...(entry.slots ?? []),
+      ...(entry.values ?? []),
+      ...entry.hybrids,
+      ...entry.components,
+    ])
+      add(keys, key, group)
+  }
+  return { names, keys }
+}
+
+// a module that names neither a `one` entry point nor a group key cannot use a group
+export function mightUseGroups(code: string, keys: Iterable<string>, pattern = keyPattern(keys)) {
+  return /['"]one(?:\/[^'"]*)?['"]/.test(code) || pattern.test(code)
+}
+
+export function keyPattern(keys: Iterable<string>) {
+  const list = [...keys]
+  return list.length ? new RegExp(`(?<![\\w$])(?:${list.join('|')})(?![\\w$])`) : /(?!)/
+}
+
+function isNode(value: unknown): value is Node {
+  return typeof value === 'object' && value !== null && typeof (value as Node).type === 'string'
+}
+
+// reads one module into the usage. a module that does not parse counts every group
+// when it names a `one` entry point, and otherwise only its textual keys.
+export function analyzeModule(
+  code: string,
+  filename: string,
+  keys: ReadonlySet<string>,
+  usage: LinkSetUsage
+) {
+  const lang = /\.tsx$/.test(filename) ? 'tsx' : /\.[cm]?ts$/.test(filename) ? 'ts' : 'jsx'
+  let program: Node
+  try {
+    const parsed = parseSync(filename, code, { lang, sourceType: 'unambiguous' })
+    if (parsed.errors.length) throw new Error(parsed.errors[0].message)
+    program = parsed.program as Node
+  } catch {
+    if (/['"]one(?:\/[^'"]*)?['"]/.test(code)) usage.all = true
+    for (const key of keys) if (new RegExp(`(?<![\\w$])${key}(?![\\w$])`).test(code)) usage.keys.add(key)
+    return
+  }
+
+  const bindings = new Map<string, Held>()
+
+  const unwrap = (node: Node): Node => {
+    let current = node
+    while (
+      current.type === 'ParenthesizedExpression' ||
+      current.type === 'ChainExpression' ||
+      current.type === 'TSAsExpression' ||
+      current.type === 'TSSatisfiesExpression' ||
+      current.type === 'TSNonNullExpression' ||
+      current.type === 'TSTypeAssertion'
+    )
+      current = current.expression
+    return current
+  }
+
+  const staticName = (node: Node): string | undefined => {
+    if (node.computed) {
+      if (node.property.type === 'Literal' && typeof node.property.value === 'string') return node.property.value
+      if (node.property.type === 'TemplateLiteral' && !node.property.expressions.length)
+        return node.property.quasis[0].value.cooked
+      return undefined
+    }
+    return node.property.name
+  }
+
+  // the move one read makes: One.iOS enters the iOS object, a read of the module's
+  // `One` enters One, and any other name is a feature that is recorded elsewhere
+  const step = (held: Held, name: string): Held | undefined =>
+    held === 'module' && name === 'One' ? 'one' : held === 'one' && name === 'iOS' ? 'ios' : undefined
+
+  const heldBy = (raw: Node): Held | undefined => {
+    const node = unwrap(raw)
+    switch (node.type) {
+      case 'Identifier':
+        return bindings.get(node.name)
+      case 'MemberExpression': {
+        const object = heldBy(node.object)
+        const name = staticName(node)
+        return object && name !== undefined ? step(object, name) : undefined
+      }
+      case 'AwaitExpression':
+        return node.argument.type === 'ImportExpression' && importedOne(node.argument) ? 'module' : undefined
+      case 'ImportExpression':
+        return undefined
+      case 'CallExpression': {
+        const callee = unwrap(node.callee)
+        return callee.type === 'Identifier' &&
+          callee.name === 'require' &&
+          node.arguments.length === 1 &&
+          node.arguments[0].type === 'Literal' &&
+          oneSource.test(String(node.arguments[0].value))
+          ? 'module'
+          : undefined
+      }
+      default:
+        return undefined
+    }
+  }
+
+  const importedOne = (node: Node) =>
+    node.source.type === 'Literal' && oneSource.test(String(node.source.value))
+
+  // a destructuring pattern against something that holds a namespace
+  const bindPattern = (pattern: Node, held: Held, record: boolean) => {
+    switch (pattern.type) {
+      case 'Identifier':
+        bindings.set(pattern.name, held)
+        return
+      case 'AssignmentPattern':
+        bindPattern(pattern.left, held, record)
+        return
+      case 'ObjectPattern':
+        for (const property of pattern.properties) {
+          if (property.type === 'RestElement') {
+            bindPattern(property.argument, held, record)
+            continue
+          }
+          let name: string | undefined
+          if (!property.computed && property.key.type === 'Identifier') name = property.key.name
+          else if (property.key.type === 'Literal') name = String(property.key.value)
+          if (name === undefined) {
+            if (record) usage.all = true
+            continue
+          }
+          if (record) usage.names.add(name)
+          const next = step(held, name)
+          if (next) bindPattern(property.value, next, record)
+        }
+        return
+      default:
+        // an array pattern or anything else cannot take apart a namespace
+        if (record) usage.all = true
+    }
+  }
+
+  // aliases first, until none are left to find: a use can precede its declaration
+  const sites: Node[] = []
+  const collect = (node: Node) => {
+    if (node.type === 'ImportDeclaration' && importedOne(node)) {
+      for (const specifier of node.specifiers) {
+        if (specifier.type === 'ImportNamespaceSpecifier') bindings.set(specifier.local.name, 'module')
+        else if (specifier.type === 'ImportDefaultSpecifier') bindings.set(specifier.local.name, 'one')
+        else {
+          const imported = specifier.imported.name ?? String(specifier.imported.value)
+          if (imported === 'One') bindings.set(specifier.local.name, 'one')
+          else usage.names.add(imported)
+        }
+      }
+    } else if (
+      (node.type === 'ExportNamedDeclaration' || node.type === 'ExportAllDeclaration') &&
+      node.source &&
+      importedOne(node)
+    ) {
+      if (node.type === 'ExportAllDeclaration') usage.all = true
+      else for (const specifier of node.specifiers) usage.names.add(specifier.local.name ?? String(specifier.local.value))
+    } else if (node.type === 'VariableDeclarator' && node.init) sites.push(node)
+    else if (node.type === 'AssignmentExpression' && node.operator === '=') sites.push(node)
+  }
+  const visitAll = (node: Node, enter: (node: Node) => void) => {
+    enter(node)
+    for (const [key, value] of Object.entries(node)) {
+      if (key === 'typeAnnotation' || key === 'returnType' || key === 'typeParameters' || key === 'typeArguments')
+        continue
+      for (const child of Array.isArray(value) ? value : [value])
+        if (isNode(child) && (!child.type.startsWith('TS') || valueTs.has(child.type))) visitAll(child, enter)
+    }
+  }
+  visitAll(program, collect)
+  for (let size = -1; size !== bindings.size; ) {
+    size = bindings.size
+    for (const site of sites) {
+      const target = site.type === 'VariableDeclarator' ? site.id : site.left
+      const source = site.type === 'VariableDeclarator' ? site.init : site.right
+      const held = heldBy(source)
+      if (!held) continue
+      if (target.type === 'Identifier') bindings.set(target.name, held)
+      else bindPattern(target, held, false)
+    }
+  }
+
+  // what stands between a namespace and the code that holds it
+  const safeParent = (node: Node, parent: Node | undefined, key: string) =>
+    !parent ||
+    parent.type === 'ParenthesizedExpression' ||
+    parent.type === 'ChainExpression' ||
+    parent.type === 'TSAsExpression' ||
+    parent.type === 'TSSatisfiesExpression' ||
+    parent.type === 'TSNonNullExpression' ||
+    parent.type === 'TSTypeAssertion' ||
+    parent.type === 'AwaitExpression' ||
+    (parent.type === 'MemberExpression' && key === 'object') ||
+    (parent.type === 'VariableDeclarator' && key === 'init') ||
+    (parent.type === 'AssignmentExpression' && key === 'right' && parent.operator === '=' && unwrap(parent.left).type === 'Identifier') ||
+    (parent.type === 'ExpressionStatement' && key === 'expression')
+
+  const visit = (node: Node, parent: Node | undefined, key: string) => {
+    if (node.type.startsWith('TS') && !valueTs.has(node.type)) return
+    switch (node.type) {
+      case 'ImportDeclaration':
+        return
+      case 'ExportNamedDeclaration':
+        if (node.source) return
+        break
+      case 'ExportSpecifier':
+        // `export { One }` hands the namespace to whoever imports this module
+        if (bindings.has(node.local.name)) usage.all = true
+        return
+      case 'ExportAllDeclaration':
+        return
+      case 'VariableDeclarator': {
+        const held = node.init ? heldBy(node.init) : undefined
+        if (held && node.id.type !== 'Identifier') bindPattern(node.id, held, true)
+        else visitPattern(node.id)
+        if (node.init) visit(node.init, node, 'init')
+        return
+      }
+      case 'AssignmentExpression': {
+        const held = heldBy(node.right)
+        if (held && node.operator === '=' && node.left.type !== 'Identifier' && node.left.type !== 'MemberExpression')
+          bindPattern(node.left, held, true)
+        else visitPattern(node.left)
+        visit(node.right, node, 'right')
+        return
+      }
+      case 'MemberExpression': {
+        const object = heldBy(node.object)
+        const name = staticName(node)
+        if (object) {
+          if (name === undefined) usage.all = true
+          else usage.names.add(name)
+        }
+        if (!node.computed) {
+          visit(node.object, node, 'object')
+          return
+        }
+        break
+      }
+      case 'JSXOpeningElement': {
+        let name = node.name
+        const path: string[] = []
+        while (name.type === 'JSXMemberExpression') {
+          path.unshift(name.property.name)
+          name = name.object
+        }
+        let held = name.type === 'JSXIdentifier' ? bindings.get(name.name) : undefined
+        for (const part of path) {
+          if (!held) break
+          usage.names.add(part)
+          held = step(held, part)
+        }
+        for (const attribute of node.attributes) visit(attribute, node, 'attributes')
+        return
+      }
+      case 'JSXAttribute':
+        if (node.name.type === 'JSXIdentifier' && keys.has(node.name.name)) usage.keys.add(node.name.name)
+        if (node.value) visit(node.value, node, 'value')
+        return
+      case 'JSXMemberExpression':
+      case 'JSXIdentifier':
+      case 'JSXNamespacedName':
+        return
+      case 'Property':
+      case 'PropertyDefinition':
+      case 'MethodDefinition':
+      case 'TSAbstractPropertyDefinition': {
+        if (!node.computed) {
+          const name = node.key.type === 'Identifier' ? node.key.name : node.key.type === 'Literal' ? String(node.key.value) : undefined
+          if (name !== undefined && keys.has(name)) usage.keys.add(name)
+        } else visit(node.key, node, 'key')
+        if (node.value) visit(node.value, node, 'value')
+        return
+      }
+      case 'Literal':
+        if (typeof node.value === 'string' && keys.has(node.value)) usage.keys.add(node.value)
+        break
+      case 'TemplateLiteral':
+        if (!node.expressions.length && keys.has(node.quasis[0].value.cooked)) usage.keys.add(node.quasis[0].value.cooked)
+        break
+      case 'Identifier':
+        // a use that is neither a read nor an alias hands the namespace elsewhere
+        if (bindings.has(node.name) && !safeParent(node, parent, key)) usage.all = true
+        return
+      case 'ImportExpression':
+        if (importedOne(node) && !(parent?.type === 'AwaitExpression')) usage.all = true
+        break
+      case 'CallExpression':
+        if (heldBy(node) && !safeParent(node, parent, key)) usage.all = true
+        break
+    }
+    if (node.type === 'MemberExpression' && !node.computed) return
+    for (const [childKey, value] of Object.entries(node)) {
+      if (childKey === 'typeAnnotation' || childKey === 'returnType' || childKey === 'typeParameters' || childKey === 'typeArguments')
+        continue
+      for (const child of Array.isArray(value) ? value : [value])
+        if (isNode(child)) visit(child, node, childKey)
+    }
+  }
+
+  // binding positions hold no reads, but a default value or a computed key can
+  function visitPattern(pattern: Node) {
+    switch (pattern.type) {
+      case 'AssignmentPattern':
+        visitPattern(pattern.left)
+        visit(pattern.right, pattern, 'right')
+        return
+      case 'ObjectPattern':
+        for (const property of pattern.properties) {
+          if (property.type === 'RestElement') visitPattern(property.argument)
+          else {
+            if (property.computed) visit(property.key, property, 'key')
+            else if (property.key.type === 'Identifier' && keys.has(property.key.name)) usage.keys.add(property.key.name)
+            visitPattern(property.value)
+          }
+        }
+        return
+      case 'ArrayPattern':
+        for (const element of pattern.elements) if (element) visitPattern(element)
+        return
+      case 'RestElement':
+        visitPattern(pattern.argument)
+        return
+      case 'MemberExpression':
+        visit(pattern, undefined, '')
+        return
+    }
+  }
+
+  visit(program, undefined, '')
+}
+
+// the groups whose features a usage reaches
+export function groupsForUsage(usage: LinkSetUsage, catalog: LinkSetCatalog): string[] {
+  if (usage.all) return Object.keys(catalog.groups)
+  const { names, keys } = catalogNames(catalog)
+  const reached = new Set<string>()
+  for (const name of usage.names) for (const group of names.get(name) ?? []) reached.add(group)
+  for (const key of usage.keys) for (const group of keys.get(key) ?? []) reached.add(group)
+  return Object.keys(catalog.groups).filter((group) => reached.has(group))
+}

package/src/cli/prebuild.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { validateNativeApp } from '../native/appManifest'
+import { writeIosLinkSet } from './iosLinkSet'
 import { loadUserOneOptions } from '../vite/loadConfig'
 
 // default react-native config: xcodebuild's bundle phase and gradle's react
@@ -76,7 +77,13 @@ export async function run(args: { platform?: string; 'no-install'?: boolean }) {
     root: process.cwd(),
     ...args,
     app,
-    beforeInstall: args.platform === 'android' ? undefined : () => writeIosSdk(root),
+    beforeInstall:
+      args.platform === 'android'
+        ? undefined
+        : async () => {
+            await writeIosSdk(root)
+            writeIosLinkSet(root)
+          },
   })
 }
 

package/src/cli/updatesPublish.ts

@@ -14,6 +14,7 @@ import {
 import { createRequire } from 'node:module'
 import { tmpdir } from 'node:os'
 import { join, relative, resolve, sep } from 'node:path'
+import { resolveNpmHermesc } from 'vxrn'
 import { validateNativeApp } from '../native/appManifest'
 import { loadUserOneOptions } from '../vite/loadConfig'
 
@@ -96,23 +97,6 @@ function resolveCliJs(root: string): string {
   return join(packageJson.slice(0, -'package.json'.length), 'cli.js')
 }
 
-function resolveNpmHermesc(root: string): string {
-  // through react-native's own dependency graph: it pins the compiler whose
-  // bytecode its hermes vm runs.
-  const require = createRequire(join(root, 'package.json'))
-  const reactNativeJson = require.resolve('react-native/package.json')
-  const nested = createRequire(reactNativeJson)
-  const compilerJson = nested.resolve('hermes-compiler/package.json')
-  const dir = compilerJson.slice(0, -'package.json'.length)
-  const bin =
-    process.platform === 'darwin'
-      ? 'osx-bin'
-      : process.platform === 'win32'
-        ? 'win64-bin'
-        : 'linux64-bin'
-  return join(dir, 'hermesc', bin, process.platform === 'win32' ? 'hermesc.exe' : 'hermesc')
-}
-
 function resolveHermesc(root: string, platform: string): string {
   // the embedded ios build compiles with the hermes-engine pod's own
   // hermesc when it exists, because the pod's vm train can differ from the
@@ -281,23 +265,36 @@ export async function runUpdatesPublish(args: PublishArgs): Promise<void> {
         { cwd: root, stdio: 'inherit' }
       )
       writeFileSync(join(intermediatesOut, 'bundle.js'), readFileSync(bundleJs))
-      writeFileSync(join(intermediatesOut, 'main.jsbundle.map'), readFileSync(composedMap))
+      writeFileSync(
+        join(intermediatesOut, 'main.jsbundle.map'),
+        readFileSync(composedMap)
+      )
     }
 
-    // the assets tree the bundler laid out is already the update layout:
-    // React Native resolves each asset at its relative path next to a
-    // bundle loaded from a file url. every served file is content-named.
+    // asset paths install next to the selected bundle loaded from a file url.
+    // every served file is content-named.
     const bundleHash = sha256Base64Url(bytecode)
     writeFileSync(join(assetsOut, bundleHash), readFileSync(bytecode))
     const assets: Array<{ hash: string; url: string; path: string }> = []
-    for (const file of collectFiles(assetsDir)) {
+    const assetFiles = collectFiles(assetsDir).map((file) => ({
+      file,
+      path: relative(assetsDir, file).split(sep).join('/'),
+    }))
+    // android's bundle command places DOM pages beside JS, separate from its
+    // drawable resource tree. both install at paths beneath the update root.
+    if (platform === 'android') {
+      for (const file of collectFiles(join(work, 'one-dom'))) {
+        assetFiles.push({ file, path: relative(work, file).split(sep).join('/') })
+      }
+    }
+    for (const { file, path } of assetFiles) {
       const hash = sha256Base64Url(file)
       const target = join(assetsOut, hash)
       if (!existsSync(target)) writeFileSync(target, readFileSync(file))
       assets.push({
         hash,
         url: `assets/${hash}`,
-        path: relative(assetsDir, file).split(sep).join('/'),
+        path,
       })
     }
     assets.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
@@ -305,7 +302,11 @@ export async function runUpdatesPublish(args: PublishArgs): Promise<void> {
       id: randomUUID(),
       createdAt: new Date().toISOString(),
       runtimeVersion,
-      launchAsset: { hash: bundleHash, url: `assets/${bundleHash}`, path: 'main.jsbundle' },
+      launchAsset: {
+        hash: bundleHash,
+        url: `assets/${bundleHash}`,
+        path: 'main.jsbundle',
+      },
       assets,
       metadata,
     }

package/src/cli.ts

@@ -129,7 +129,7 @@ const buildCommand = defineCommand({
     },
     platform: {
       type: 'string',
-      description: `One of: web, ios, android`,
+      description: `One of: web, ios, android, macos, linux`,
       default: 'web',
       required: false,
     },
@@ -146,6 +146,8 @@ const buildCommand = defineCommand({
       ios: 'ios',
       web: 'web',
       android: 'android',
+      macos: 'macos',
+      linux: 'linux',
     } as const
 
     if (args.platform && !platforms[args.platform]) {

package/src/createApp.tsx

@@ -2,12 +2,15 @@ import './setup'
 
 import { cloneElement } from 'react'
 import { resolveClientLoader } from './clientLoaderResolver'
+import { loaderResponseToModule } from './loaderResponseToModule'
+import { prepareSsrLoaderProps } from './loaderSearchParams'
 import { Root } from './Root'
 import { render } from './render'
 import { initClientMatches } from './router/router'
 import { registerPreloadedRoute } from './router/useViteRoutes'
 import { setupSkewProtection } from './skewProtection'
 import { handleSkewError, isChunkLoadError } from './utils/dynamicImport'
+import { readLoaderSearch } from './utils/cleanUrl'
 import { findRootLayout } from './utils/findRootLayout'
 import type { RenderAppProps } from './types'
 import type { OneLinkingConfig } from './link/getLinking'
@@ -40,6 +43,8 @@ export function createApp(options: CreateAppProps) {
 
     return {
       options,
+      // shared with the generated vercel function, which builds loader props itself
+      loaderRequest: { loaderResponseToModule, prepareSsrLoaderProps, readLoaderSearch },
       render: async (props: RenderAppProps) => {
         // set render mode env before setup so users can conditionally skip setup in ssg/spa
         const renderMode = props.mode === 'spa-shell' ? 'spa' : props.mode

package/src/createHandleRequest.ts

@@ -1,8 +1,10 @@
 import { LOADER_JS_POSTFIX_UNCACHED } from './constants'
+import { loaderResponseToModule } from './loaderResponseToModule'
 import type { Middleware, MiddlewareContext } from './createMiddleware'
 import type { RouteNode } from './router/Route'
 import type { RouteInfoCompiled } from './server/createRoutesManifest'
 import type { LoaderProps } from './types'
+import { readLoaderSearch } from './utils/cleanUrl'
 import { isResponse } from './utils/isResponse'
 import { resolveAPIEndpoint, resolveResponse } from './vite/resolveResponse'
 import type { RouteInfo } from './vite/types'
@@ -209,7 +211,9 @@ export async function resolveLoaderRoute(
           url,
           loaderProps: {
             path: url.pathname,
-            search: url.search,
+            // an ssr route's loader gets the query of the page, which the client
+            // sends under a reserved key apart from the loader request's own
+            search: route.type === 'ssr' ? readLoaderSearch(url) : url.search,
             subdomain: getSubdomain(url),
             request: route.type === 'ssr' ? request : undefined,
             params: getLoaderParams(url, route),
@@ -238,37 +242,7 @@ export async function resolveLoaderRoute(
     })
   })
 
-  // transform redirect responses into js modules so the client can detect
-  // and handle them during client-side navigation (instead of the browser
-  // silently following the 302 and trying to parse HTML as javascript)
-  if (response.status >= 300 && response.status < 400) {
-    const location = response.headers.get('location')
-    if (location) {
-      const redirectUrl = new URL(location, url.origin)
-      const redirectPath = redirectUrl.pathname + redirectUrl.search + redirectUrl.hash
-      const data = `{__oneRedirect:${JSON.stringify(redirectPath)},__oneRedirectStatus:${response.status}}`
-      const body = isNativeRequest
-        ? `exports.loader=function(){return ${data}}`
-        : `export function loader(){return${data}}`
-      return new Response(body, {
-        headers: { 'Content-Type': 'text/javascript' },
-      })
-    }
-  }
-
-  // transform auth error responses (401/403) into js modules so the client
-  // gets a clean error signal instead of a parse failure
-  if (response.status === 401 || response.status === 403) {
-    const data = `{__oneError:${response.status},__oneErrorMessage:${JSON.stringify(response.statusText || 'Unauthorized')}}`
-    const body = isNativeRequest
-      ? `exports.loader=function(){return ${data}}`
-      : `export function loader(){return${data}}`
-    return new Response(body, {
-      headers: { 'Content-Type': 'text/javascript' },
-    })
-  }
-
-  return response
+  return loaderResponseToModule(response, url, isNativeRequest)
 }
 
 /**

package/src/dom/README.md

@@ -0,0 +1,27 @@
+# DOM component runtime
+
+The native transform calls `createDOMComponent(stableId)` from `one/dom/native`. A browser entry calls `mountDOMComponent(Component, stableId)` from `one/dom/client`. Ordinary web imports render the original component with the existing SSR rules. `one/dom` exports `DOMProps`, the supported data and action types, and `useDOMImperativeHandle(ref, factory, deps)`. Imperative methods return promises on both platforms. The hook supports one handle per hosted component and reserves the method name `then`. Factory dependency changes replace the committed method table without rejecting already running calls. Retained handles dispatch new calls to the latest committed methods; removed methods reject new calls while their already running calls may finish. Unmount or document disposal rejects outstanding calls.
+
+The component's optional `dom` prop configures the native container: style, scrollEnabled, matchContents, onLoad and onError. Container options never enter component data. onLoad reports the host document's completion; the imperative ref becomes available when the browser hook commits. matchContents applies the measured browser height at the native container's width. Providers, router state, native modules, children and React elements cannot cross this boundary. Navigation that needs native behavior uses an explicit parent callback action.
+
+Host load errors and browser process termination invalidate the document and reject its outstanding calls. Errors reach `dom.onError` when supplied; otherwise the proxy logs the error detail without throwing from the native event callback. Recovery starts a fresh document and ref. A valid browser `error` message can arrive before `ready`, retaining its serialized name, message and optional code and development stack. Reporting that error leaves the peer waiting for readiness, so a recovered entry can still mount. Other pre-ready messages retain their normal protocol checks.
+
+`protocol.ts` defines the shared versioned wire contract. Values are finite numbers, strings, booleans, null, arrays and plain objects. Undefined object fields are omitted recursively, including optional top-level props. Array holes and undefined entries, nested functions, classes, Date, Error, symbols, BigInt and cycles are rejected with paths. Only top-level function props become actions. Value, void and error responses are distinct. Error stacks travel only in development.
+
+`DOMNativeBridge.prepare` produces a prospective native bootstrap snapshot without changing the committed callback table. A layout effect commits the snapshot and latest handlers. Unchanged data and action names send no state messages even when handlers change. Each native document starts a separate peer, epoch and pending map. A ready message carries its captured revision; later committed revisions reconcile in order. Old epochs are ignored, reused native epochs are rejected, and malformed messages invalidate the peer before dispatch. Disposal rejects pending calls once and suppresses replies from actions that finish after disposal.
+
+## Native host seam
+
+`OneDOMHostNativeComponent.ts` defines the Fabric host. Props are entryId, developmentURL, bootstrapState, scrollEnabled and ViewProps. Its only command is ordered `post(ref, JSONString)`. Events carry document start with epoch/revision, message, document completion, errors and process termination. A revision is a nonnegative JavaScript safe integer.
+
+For every new document, native captures its latest committed bootstrapState `{version,revision,props,actions}`, assigns a unique epoch across instances and documents, adds entryId and os (`ios` or `android`), and injects `globalThis.__oneDOM` before application scripts. The shim exposes `bootstrap`, `postMessage(string)` and `subscribe(listener):unsubscribe`. It queues writes until the platform transport is available. Native enqueues onDocumentStart before any page events from that document. Updating bootstrapState never recreates a page. Updates committed after the capture reconcile after ready; document-start does not promise globally latest props without a round trip.
+
+The native shim reports window errors and unhandled rejections from document start through the first transport subscription using the same versioned `error` envelope. The first subscription removes those early listeners as the browser client takes over reporting. Script and stylesheet load failures must retain the failing resource URL. Stacks are omitted from production documents.
+
+Native owns main-frame and origin checks, action/navigation policy, selected immutable production build/update resource identity, asset root, process recovery and platform availability. It must dispose the browser while its realm is alive, through a versioned dispose message or pagehide. Native teardown and process death release old document resources; recovery captures a fresh committed snapshot and epoch. Commands and replies cannot be delivered across views or epochs. Development uses the existing dev-server origin at `/_one/dom/<id>/`; production looks up a stable ID in the selected protocolVersion 1 manifest.
+
+The browser HTML provides `#one-dom-root` with natural height, `display:flow-root`, `width:100%`, `min-width:0` and body margin zero. ResizeObserver schedules one measurement per animation frame; rounded finite sizes suppress unchanged reports. Browser disposal removes its sole transport subscription, global listeners, observer and animation frame.
+
+The focused JavaScript probes cover serialization, callbacks, document races and React commit ordering with a simulated host. Native transport, owned resource loading, navigation checks, device layout/keyboard behavior and performance require independent native and device validation.
+
+The native host source is `host.native.tsx`; `one/dom/native` selects its native build. A bare `native.tsx` filename collides with the package builder platform suffix recognition and loses its ESM output.