@owlmeans/client 0.1.18-rc.40 → 0.1.18-rc.41

package/build/types.d.ts

@@ -1,9 +1,9 @@
-import type { PropsWithChildren, FC, DependencyList } from 'react';
+import type { PropsWithChildren, FC, DependencyList, ComponentType, ReactNode } from 'react';
 import type { AbstractRequest } from '@owlmeans/entrypoint';
 import type { ClientConfig, ClientContext as BasicClientContext } from '@owlmeans/client-context';
 import type { Criteria, ResourceRecord, Sort } from '@owlmeans/resource';
 import type { StateResourceAppend } from '@owlmeans/state';
-import type { ClientEntrypoint } from '@owlmeans/client-entrypoint';
+import type { ClientEntrypoint, RefedEntrypointHandler } from '@owlmeans/client-entrypoint';
 import type { DebugServiceAppend, ModalServiceAppend } from './components/types.js';
 import type { ConfigResourceAppend } from '@owlmeans/config';
 import type { ConfigRecord, EntrypointReference } from '@owlmeans/context';
@@ -73,4 +73,71 @@ export interface UseStoreListOptions<T extends ResourceRecord = ResourceRecord>
     /** Which state resource to read; the context's default one when omitted. */
     resource?: string;
 }
+/** How `retryImport` retries a rejected dynamic import. */
+export interface RetryImportOptions {
+    /** Loads after the first failure, at most; `0` loads once. Default 2. */
+    attempts?: number;
+    /** The pause before each retry, in order; the last one repeats. Default 500 ms, then 1500 ms. */
+    delaysMs?: readonly number[];
+    /**
+     * Which rejections are retried. Default `isChunkLoadError` — a module that could not be fetched,
+     * never one that was fetched and then failed.
+     */
+    shouldRetry?: (error: unknown) => boolean;
+    /**
+     * Retry a failed chunk from its own URL with a cache-busting `t` parameter when the browser's
+     * error names it (Chromium, Firefox). Default `true`: a browser that remembers a failed module
+     * fetch rejects every later `import()` of the same URL at once, so only a new URL is fetched
+     * again. `false` repeats `load` as is.
+     */
+    bustCache?: boolean;
+    /** How a cache-busted URL is imported; a seam for tests. Default: a dynamic `import()`. */
+    importUrl?: (url: string) => Promise<unknown>;
+}
+/**
+ * What a lazily-loaded piece renders once it failed: the props it was given, the error, and
+ * `retry`, which resets the piece's boundary so its chunk loads again.
+ */
+export type LazyErrorRenderer = (props: any, error: unknown, retry: () => void) => ReactNode;
+/** How a lazily-loaded component behaves while its chunk loads and when the load fails. */
+export interface LazyComponentOptions {
+    /** Shown while the chunk loads: a node, or a function of the props the component was given. */
+    fallback?: ReactNode | ((props: any) => ReactNode);
+    /**
+     * Rendered in place of the component when its chunk fails to load, or it throws: a node, or a
+     * `LazyErrorRenderer`. Omitted, a chunk failure starts the guarded reload
+     * (`recoverFromChunkError`) and leaves `fallback` in place, and any other error propagates to
+     * the nearest boundary above.
+     */
+    error?: ReactNode | LazyErrorRenderer;
+    /**
+     * How a rejected load is retried before it counts as failed — `retryImport`'s options, its
+     * defaults when omitted. `false` loads once.
+     */
+    retry?: false | RetryImportOptions;
+    /**
+     * When a chunk still fails after its retries, start the guarded page reload
+     * (`recoverFromChunkError`, once a minute per tab) before showing `error`; the fallback stays up
+     * while the reload starts, and `error` shows when the guard refuses. Without `error` a chunk
+     * failure always reloads. Default `false` for `lazyComponent` (a piece degrades in place), `true`
+     * for `lazyHandler` (a whole screen). A dev-served app needs it: its modules import themselves by
+     * their own URL (React Fast Refresh), so a browser that remembers the failed fetch can load that
+     * module again only in a new document.
+     */
+    reload?: boolean;
+}
+export interface LazyPreload<P = {}> {
+    /** Start (or join) the chunk load; resolves to the component once it is ready. */
+    preload: () => Promise<ComponentType<P>>;
+}
+/** A lazily-loaded component: renders like the real one, and can be preloaded ahead of use. */
+export type LazyComponent<P = {}> = ComponentType<P> & LazyPreload<P>;
+/** An entrypoint handler over a lazily-loaded component, carrying its `.preload()`. */
+export type LazyHandler<P = {}> = RefedEntrypointHandler<P> & LazyPreload<P>;
+/** Names of a module's exports that are React components. */
+export type ComponentExport<M> = {
+    [K in keyof M]-?: M[K] extends ComponentType<any> ? K : never;
+}[keyof M] & string;
+/** The props of a module's component export. */
+export type ExportProps<M, K extends keyof M> = M[K] extends ComponentType<infer P> ? P : never;
 //# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/client",
-  "version": "0.1.18-rc.40",
+  "version": "0.1.18-rc.41",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 54 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -28,17 +29,17 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.35",
-    "@owlmeans/client-context": "^0.1.18-rc.38",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.37",
-    "@owlmeans/client-resource": "^0.1.18-rc.37",
-    "@owlmeans/config": "^0.1.18-rc.37",
+    "@owlmeans/auth": "^0.1.18-rc.36",
+    "@owlmeans/client-context": "^0.1.18-rc.39",
+    "@owlmeans/client-entrypoint": "^0.1.18-rc.38",
+    "@owlmeans/client-resource": "^0.1.18-rc.38",
+    "@owlmeans/config": "^0.1.18-rc.38",
     "@owlmeans/context": "^0.1.18-rc.32",
-    "@owlmeans/error": "^0.1.18-rc.35",
-    "@owlmeans/entrypoint": "^0.1.18-rc.36",
-    "@owlmeans/resource": "^0.1.18-rc.35",
+    "@owlmeans/error": "^0.1.18-rc.36",
+    "@owlmeans/entrypoint": "^0.1.18-rc.37",
+    "@owlmeans/resource": "^0.1.18-rc.36",
     "@owlmeans/router": "^0.1.18-rc.31",
-    "@owlmeans/state": "^0.1.18-rc.34"
+    "@owlmeans/state": "^0.1.18-rc.35"
   },
   "peerDependencies": {
     "@remix-run/router": "*",
@@ -51,9 +52,15 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/test-ui": "^0.1.18-rc.39",
     "@types/react": "^19.2.17",
+    "@vitejs/plugin-react": "^6.0.3",
     "nodemon": "^3.1.14",
-    "typescript": "^7.0.2"
+    "playwright": "^1.61.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "typescript": "^7.0.2",
+    "vite": "^8.1.2"
   },
   "publishConfig": {
     "access": "public"

package/src/consts.ts

@@ -5,3 +5,13 @@ export const DEF_DEBUG_ALIAS = 'debug'
 export const DEBUGGER_FLAG = 'debugger'
 export const DEBUG_CONFIG_KEY = 'debugger'
 
+/** How many times `retryImport` loads a chunk again after its first failure. */
+export const DEF_IMPORT_RETRY_ATTEMPTS = 2
+/** The pause before each retry, in order; the last one repeats. */
+export const DEF_IMPORT_RETRY_DELAYS_MS: readonly number[] = [500, 1500]
+
+/** The `sessionStorage` key `recoverFromChunkError` keeps the time of its last reload under. */
+export const CHUNK_RELOAD_KEY = 'owlmeans:chunk-reload'
+/** At most one chunk-recovery reload per this window, per tab. */
+export const CHUNK_RELOAD_WINDOW_MS = 60_000
+

package/src/index.ts

@@ -3,6 +3,8 @@ export * from './context.js'
 export * from './components/index.js'
 export * from './services/index.js'
 export * from './helper.js'
+export * from './lazy.js'
+export * from './lazy-retry.js'
 export * from './navigate.js'
 export * from './entrypoint.js'
 export * from './router.js'

package/src/lazy-retry.ts

@@ -0,0 +1,141 @@
+import {
+  CHUNK_RELOAD_KEY, CHUNK_RELOAD_WINDOW_MS, DEF_IMPORT_RETRY_ATTEMPTS, DEF_IMPORT_RETRY_DELAYS_MS
+} from './consts.js'
+import type { RetryImportOptions } from './types.js'
+
+/**
+ * What a browser says when a dynamic `import()` could not fetch its module — Chromium, Safari and
+ * Firefox, in that order — and what Vite's preload helper says when a chunk's stylesheet could not.
+ */
+const CHUNK_FAILURE = /failed to fetch dynamically imported module|importing a module script failed|error loading dynamically imported module|unable to preload css/i
+
+/**
+ * Whether `error` is a chunk that could not be FETCHED: a browser's failed dynamic import, Vite's
+ * stylesheet preload failure, webpack's `ChunkLoadError`, Vite's `vite:preloadError` event, or
+ * the `error` event of the element a loader fetched through. A module that was fetched and then
+ * failed — a missing export, a throw while it evaluated — is not one: loading it again changes
+ * nothing.
+ */
+export const isChunkLoadError = (error: unknown): boolean => {
+  if (error == null || typeof error !== 'object') {
+    return false
+  }
+  if (typeof Event !== 'undefined' && error instanceof Event) {
+    return error.type === 'vite:preloadError' || error.type === 'error'
+  }
+  const { name, message } = error as { name?: unknown, message?: unknown }
+
+  return name === 'ChunkLoadError' || (typeof message === 'string' && CHUNK_FAILURE.test(message))
+}
+
+const pause = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
+
+/** The module URL a Chromium or Firefox import failure names; Safari's message names none. */
+const FAILED_URL = /dynamically imported module:?\s+(\S+)/i
+
+/**
+ * The URL of the chunk a failed dynamic import tried to fetch, when the browser's error names it
+ * and it is an http(s) URL of this page's origin — never an arbitrary URL out of a message. `null`
+ * otherwise (Safari, a non-browser platform, another origin).
+ */
+export const chunkUrlOf = (error: unknown): string | null => {
+  const message = (error as { message?: unknown } | null)?.message
+  const found = typeof message === 'string' ? FAILED_URL.exec(message)?.[1] : undefined
+  if (found == null) {
+    return null
+  }
+  try {
+    const url = new URL(found)
+    const origin = typeof location !== 'undefined' ? location.origin : undefined
+    if ((url.protocol !== 'https:' && url.protocol !== 'http:') || (origin != null && url.origin !== origin)) {
+      return null
+    }
+    return url.href
+  } catch {
+    return null
+  }
+}
+
+/**
+ * `href` with a fresh `t` parameter: a URL the browser has not seen, so it fetches the module
+ * again. `t` is the parameter Vite's dev server already gives module URLs; a static host ignores it.
+ */
+export const cacheBustedUrl = (href: string, now: number = Date.now()): string => {
+  const url = new URL(href)
+  url.searchParams.set('t', String(now))
+  return url.href
+}
+
+const importUrl = (url: string): Promise<unknown> =>
+  import(/* @vite-ignore */ /* webpackIgnore: true */ url)
+
+/**
+ * Run `load` — a dynamic `import()` — and, while it rejects with a chunk-load failure, run it again
+ * after a pause, `attempts` more times at most. Any other rejection is rethrown at once.
+ *
+ * This covers a TRANSIENT failure — a network blip, an edge answering 404 or 5xx for a moment.
+ * A browser remembers a failed module fetch for the document's lifetime (Chromium does) and
+ * rejects every later `import()` of that URL at once, so a retry imports the URL the error names
+ * with a cache-busting parameter instead (`bustCache`, default on): a new URL, fetched again. Where
+ * the error names no URL (Safari), `load` runs again as is; what always recovers is a new
+ * document, which `recoverFromChunkError` starts, once and guarded.
+ */
+export const retryImport = async <M>(load: () => Promise<M>, opts?: RetryImportOptions): Promise<M> => {
+  const attempts = Math.max(0, opts?.attempts ?? DEF_IMPORT_RETRY_ATTEMPTS)
+  const delays = opts?.delaysMs ?? DEF_IMPORT_RETRY_DELAYS_MS
+  const shouldRetry = opts?.shouldRetry ?? isChunkLoadError
+  const bust = opts?.bustCache !== false
+  const importBusted = opts?.importUrl ?? importUrl
+
+  let next: () => Promise<M> = load
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await next()
+    } catch (error) {
+      if (attempt >= attempts || !shouldRetry(error)) {
+        throw error
+      }
+      const url = bust ? chunkUrlOf(error) : null
+      if (url != null) {
+        next = async () => await importBusted(cacheBustedUrl(url)) as M
+      }
+      await pause(delays[Math.min(attempt, delays.length - 1)] ?? 0)
+    }
+  }
+}
+
+/**
+ * Reload the page, at most once per `windowMs` in this tab — the time of the last reload is kept
+ * in `sessionStorage` under `key`. Never while offline (the reload would land on the browser's own
+ * error page), and never without storage: with nowhere to keep the guard, a failure that survives
+ * the reload would reload forever. A platform with no page to reload does nothing. Answers whether
+ * a reload was started.
+ */
+export const reloadOnce = (key: string, windowMs: number): boolean => {
+  const location = typeof window !== 'undefined' ? window.location : undefined
+  if (typeof location?.reload !== 'function') {
+    return false
+  }
+  if (typeof navigator !== 'undefined' && navigator.onLine === false) {
+    return false
+  }
+  try {
+    const now = Date.now()
+    if (now - Number(window.sessionStorage.getItem(key) ?? 0) < windowMs) {
+      return false
+    }
+    window.sessionStorage.setItem(key, String(now))
+  } catch {
+    return false
+  }
+  location.reload()
+
+  return true
+}
+
+/**
+ * The guarded reload a chunk that failed for good ends in: `reloadOnce` under one key every caller
+ * in the tab shares, so a lazy boundary and an application's own `vite:preloadError` listener
+ * never reload twice for one failure.
+ */
+export const recoverFromChunkError = (): boolean => reloadOnce(CHUNK_RELOAD_KEY, CHUNK_RELOAD_WINDOW_MS)

package/src/lazy.tsx

@@ -0,0 +1,161 @@
+import { lazy, Suspense, Component, useState } from 'react'
+import type { ComponentType, ReactNode } from 'react'
+import { handler } from './helper.js'
+import { isChunkLoadError, recoverFromChunkError, retryImport } from './lazy-retry.js'
+import type { HandledRenderer } from './utils/route.js'
+import type {
+  ComponentExport, ExportProps, LazyComponent, LazyComponentOptions, LazyHandler
+} from './types.js'
+
+type Loaded = ComponentType<any>
+type LazyModule = { default: Loaded }
+
+/**
+ * Wrap an async module import as a stable lazily-loaded component with a `.preload()`.
+ *
+ * MUST be called at module scope, never inside a render, a hook body or an entrypoint handler
+ * factory — the OwlMeans route renderer (`utils/route.tsx`) remounts the whole route subtree on
+ * every navigation (a fresh component identity per render), so a lazy object created during
+ * render would re-suspend on every navigation instead of rendering instantly once loaded.
+ *
+ * The `Suspense` boundary sits inside the returned component, so the fallback replaces only this
+ * component — the layout around it stays mounted while the chunk loads.
+ *
+ * Once loaded, later renders resolve synchronously (no re-suspend), so a component whose chunk
+ * was already preloaded never shows its fallback. A load that fails to fetch is retried in place
+ * (`retryImport`, tuned or turned off by `opts.retry`); one that still fails is never cached: the
+ * internal `React.lazy` is recreated, so the next mount, `retry()` or `preload()` loads for real.
+ *
+ * The component always carries its own error boundary, so a chunk that failed for good never
+ * unmounts what is around it: `opts.error` renders in its place, or — without one — the guarded
+ * reload (`recoverFromChunkError`) starts and the fallback stays. Any other error without
+ * `opts.error` goes on to the nearest boundary above, as if there were none.
+ */
+export const lazyComponent = <M, K extends ComponentExport<M>>(
+  load: () => Promise<M>, exportName: K, opts?: LazyComponentOptions
+): LazyComponent<ExportProps<M, K>> => {
+  let loaded: Loaded | undefined
+  let loading: Promise<Loaded> | undefined
+
+  const fetchModule = (): Promise<M> => opts?.retry === false ? load() : retryImport(load, opts?.retry)
+
+  const runLoad = (): Promise<Loaded> => loading ??= fetchModule().then(module => {
+    const Comp = (module as unknown as Record<string, Loaded | undefined>)[exportName]
+    if (Comp == null) {
+      throw new SyntaxError(`Lazy module has no component export "${exportName}"`)
+    }
+    return loaded = Comp
+  }).catch((error: unknown) => {
+    loading = undefined
+    current = createLazy()
+    throw error
+  })
+
+  const preload = (): Promise<Loaded> => loaded != null ? Promise.resolve(loaded) : runLoad()
+
+  const createLazy = () => lazy<Loaded>(() => {
+    const ready = loaded
+    if (ready != null) {
+      // Already resolved: hand React a thenable that settles synchronously, so its lazy
+      // initializer reads the module in the same tick and never suspends.
+      const settled = { then: (resolve: (module: LazyModule) => void) => resolve({ default: ready }) }
+      return settled as unknown as Promise<LazyModule>
+    }
+    return runLoad().then(Comp => ({ default: Comp }))
+  })
+
+  let current = createLazy()
+
+  const Lazy = (props: Record<string, unknown>) => {
+    // The lazy THIS instance renders, taken when it mounts: a failed load stays failed for it
+    // while React re-renders it to recover from the error, until `retry` swaps in the recreated
+    // lazy. A new mount — a navigation back, another place — takes the recreated one at once.
+    const [Current, setCurrent] = useState(() => current)
+    const fallback = (typeof opts?.fallback === 'function' ? opts.fallback(props) : opts?.fallback) ?? null
+
+    return <LazyErrorBoundary error={opts?.error} reload={opts?.reload === true} fallback={fallback} props={props}
+      onRetry={() => setCurrent(() => current)}>
+      <Suspense fallback={fallback}><Current {...props} /></Suspense>
+    </LazyErrorBoundary>
+  }
+  Lazy.displayName = `Lazy(${exportName})`
+
+  return Object.assign(Lazy, { preload }) as unknown as LazyComponent<ExportProps<M, K>>
+}
+
+interface LazyErrorBoundaryProps {
+  error: LazyComponentOptions['error']
+  /** Start the guarded reload for a chunk failure even though `error` is given. */
+  reload: boolean
+  fallback: ReactNode
+  props: Record<string, unknown>
+  /** Swap the failed lazy for the recreated one — batched with the boundary's own reset. */
+  onRetry: () => void
+  children: ReactNode
+}
+
+interface LazyErrorBoundaryState {
+  failed: boolean
+  error: unknown
+  /** A guarded reload has started: keep the fallback up until the new document replaces this one. */
+  reloading?: boolean
+}
+
+class LazyErrorBoundary extends Component<LazyErrorBoundaryProps, LazyErrorBoundaryState> {
+  override state: LazyErrorBoundaryState = { failed: false, error: undefined }
+
+  static getDerivedStateFromError(error: unknown): LazyErrorBoundaryState {
+    return { failed: true, error }
+  }
+
+  override componentDidCatch(error: unknown): void {
+    // A chunk that failed for good is recovered by a new document: always without a surface of its
+    // own, and with one when asked (`reload`) — a whole screen rather than a piece that degrades.
+    // The reload is guarded (once a minute per tab); when the guard refuses, the surface stays.
+    if (isChunkLoadError(error) && (this.props.error === undefined || this.props.reload)) {
+      if (recoverFromChunkError()) {
+        this.setState({ reloading: true })
+      }
+    }
+  }
+
+  /** Render the children again, over the recreated lazy, which loads anew. */
+  readonly retry = (): void => {
+    this.setState({ failed: false, error: undefined, reloading: false })
+    this.props.onRetry()
+  }
+
+  override render() {
+    if (!this.state.failed) {
+      return this.props.children
+    }
+    const { error, fallback, props } = this.props
+    if (this.state.reloading === true) {
+      return fallback
+    }
+    if (error !== undefined) {
+      return typeof error === 'function' ? error(props, this.state.error, this.retry) : error
+    }
+    if (isChunkLoadError(this.state.error)) {
+      return fallback
+    }
+    // Not a chunk failure and no surface for it: the application's own boundary decides.
+    throw this.state.error
+  }
+}
+
+/**
+ * `handler(lazyComponent(...))`, carrying `.preload()` through — bind it to a screen exactly like
+ * `handler(Component)`. The same module-scope rule applies: call it where the entrypoints are
+ * declared, never inside a render. A screen whose chunk still fails after its retries starts the
+ * guarded reload before showing its `error` (`reload` defaults to `true` here): a whole screen has
+ * nothing to degrade to, and in a dev-served app only a new document can load it again.
+ */
+export const lazyHandler = <M, K extends ComponentExport<M>>(
+  load: () => Promise<M>, exportName: K, opts?: LazyComponentOptions
+): LazyHandler<ExportProps<M, K>> => {
+  const LazyComp = lazyComponent(load, exportName, { ...opts, reload: opts?.reload ?? true })
+  const refed = handler(LazyComp as unknown as HandledRenderer<{}>)
+
+  return Object.assign(refed, { preload: LazyComp.preload }) as unknown as LazyHandler<ExportProps<M, K>>
+}

package/src/types.ts

@@ -1,9 +1,9 @@
-import type { PropsWithChildren, FC, DependencyList } from 'react'
+import type { PropsWithChildren, FC, DependencyList, ComponentType, ReactNode } from 'react'
 import type { AbstractRequest } from '@owlmeans/entrypoint'
 import type { ClientConfig, ClientContext as BasicClientContext } from '@owlmeans/client-context'
 import type { Criteria, ResourceRecord, Sort } from '@owlmeans/resource'
 import type { StateResourceAppend } from '@owlmeans/state'
-import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import type { ClientEntrypoint, RefedEntrypointHandler } from '@owlmeans/client-entrypoint'
 import type { DebugServiceAppend, ModalServiceAppend } from './components/types.js'
 import type { ConfigResourceAppend } from '@owlmeans/config'
 import type { ConfigRecord, EntrypointReference } from '@owlmeans/context'
@@ -92,3 +92,78 @@ export interface UseStoreListOptions<T extends ResourceRecord = ResourceRecord>
   /** Which state resource to read; the context's default one when omitted. */
   resource?: string
 }
+
+/** How `retryImport` retries a rejected dynamic import. */
+export interface RetryImportOptions {
+  /** Loads after the first failure, at most; `0` loads once. Default 2. */
+  attempts?: number
+  /** The pause before each retry, in order; the last one repeats. Default 500 ms, then 1500 ms. */
+  delaysMs?: readonly number[]
+  /**
+   * Which rejections are retried. Default `isChunkLoadError` — a module that could not be fetched,
+   * never one that was fetched and then failed.
+   */
+  shouldRetry?: (error: unknown) => boolean
+  /**
+   * Retry a failed chunk from its own URL with a cache-busting `t` parameter when the browser's
+   * error names it (Chromium, Firefox). Default `true`: a browser that remembers a failed module
+   * fetch rejects every later `import()` of the same URL at once, so only a new URL is fetched
+   * again. `false` repeats `load` as is.
+   */
+  bustCache?: boolean
+  /** How a cache-busted URL is imported; a seam for tests. Default: a dynamic `import()`. */
+  importUrl?: (url: string) => Promise<unknown>
+}
+
+/**
+ * What a lazily-loaded piece renders once it failed: the props it was given, the error, and
+ * `retry`, which resets the piece's boundary so its chunk loads again.
+ */
+export type LazyErrorRenderer = (props: any, error: unknown, retry: () => void) => ReactNode
+
+/** How a lazily-loaded component behaves while its chunk loads and when the load fails. */
+export interface LazyComponentOptions {
+  /** Shown while the chunk loads: a node, or a function of the props the component was given. */
+  fallback?: ReactNode | ((props: any) => ReactNode)
+  /**
+   * Rendered in place of the component when its chunk fails to load, or it throws: a node, or a
+   * `LazyErrorRenderer`. Omitted, a chunk failure starts the guarded reload
+   * (`recoverFromChunkError`) and leaves `fallback` in place, and any other error propagates to
+   * the nearest boundary above.
+   */
+  error?: ReactNode | LazyErrorRenderer
+  /**
+   * How a rejected load is retried before it counts as failed — `retryImport`'s options, its
+   * defaults when omitted. `false` loads once.
+   */
+  retry?: false | RetryImportOptions
+  /**
+   * When a chunk still fails after its retries, start the guarded page reload
+   * (`recoverFromChunkError`, once a minute per tab) before showing `error`; the fallback stays up
+   * while the reload starts, and `error` shows when the guard refuses. Without `error` a chunk
+   * failure always reloads. Default `false` for `lazyComponent` (a piece degrades in place), `true`
+   * for `lazyHandler` (a whole screen). A dev-served app needs it: its modules import themselves by
+   * their own URL (React Fast Refresh), so a browser that remembers the failed fetch can load that
+   * module again only in a new document.
+   */
+  reload?: boolean
+}
+
+export interface LazyPreload<P = {}> {
+  /** Start (or join) the chunk load; resolves to the component once it is ready. */
+  preload: () => Promise<ComponentType<P>>
+}
+
+/** A lazily-loaded component: renders like the real one, and can be preloaded ahead of use. */
+export type LazyComponent<P = {}> = ComponentType<P> & LazyPreload<P>
+
+/** An entrypoint handler over a lazily-loaded component, carrying its `.preload()`. */
+export type LazyHandler<P = {}> = RefedEntrypointHandler<P> & LazyPreload<P>
+
+/** Names of a module's exports that are React components. */
+export type ComponentExport<M> = {
+  [K in keyof M]-?: M[K] extends ComponentType<any> ? K : never
+}[keyof M] & string
+
+/** The props of a module's component export. */
+export type ExportProps<M, K extends keyof M> = M[K] extends ComponentType<infer P> ? P : never

package/tests/context.ts

@@ -0,0 +1,33 @@
+import { createServer } from 'vite'
+import react from '@vitejs/plugin-react'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+let url: string | null = null
+
+/**
+ * Boot a Vite dev server serving `tests/harness/` — a real HTTP origin, because a lazily-loaded
+ * piece is a module request of its own and a failed one ends in a real page reload, neither of
+ * which a `data:` URL can host. One server per `bun test` process.
+ */
+export const getHarnessUrl = async (): Promise<string> => {
+  if (url != null) return url
+  const server = await createServer({
+    configFile: false,
+    root: resolve(here, './harness'),
+    plugins: [react()],
+    // Single React instance so hooks work across the workspace-linked packages.
+    resolve: { dedupe: ['react', 'react-dom'] },
+    server: { port: 0 },
+    logLevel: 'warn'
+  })
+  await server.listen()
+  const local = server.resolvedUrls?.local?.[0]
+  if (local == null) throw new Error('vite did not expose a local URL')
+  url = local
+  return url
+}
+
+export const HARNESS_URL = await getHarnessUrl()

package/tests/harness/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>@owlmeans/client lazy harness</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/mount.tsx"></script>
+  </body>
+</html>