@actis/core 26.3.0 → 26.9.0

package/README.md

@@ -32,7 +32,7 @@ yarn add @actis/core
 Here's a simple example to get you started:
 
 ```tsx
-import WebGLRenderer from '@actis/core'
+import { WebGLRenderer } from '@actis/core'
 import React, { useEffect, useRef } from 'react'
 
 // Main React functional component
@@ -100,7 +100,6 @@ function App() {
           textures: ['bufferB'],
         },
       ],
-      textures: [],
     }
     rendererRef.current.setup(passes) // Setup the renderer with the passes
     requestAnimationFrame(rendererRef.current.render) // Start the rendering loop
@@ -117,6 +116,65 @@ export default App
 
 For more advanced usage, such as adding multiple passes and using textures, refer to the [API documentation](#advanced-usage) ~in a near future~.
 
+### Offscreen rendering (workers)
+
+`createRenderer` runs the same renderer inside a dedicated worker against an
+`OffscreenCanvas`, keeping shader compilation, uniform resolution, and the
+pass loop off the main thread. It is worker-first by default and falls back
+to the main-thread `WebGLRenderer` automatically:
+
+```ts
+import { createRenderer } from '@actis/core'
+
+const renderer = await createRenderer(canvas, {
+  mode: 'auto', // 'auto' | 'worker' | 'main'
+  onFallback: reason => console.info('main-thread fallback:', reason),
+})
+
+renderer.setup({ passes: [/* ... */] }) // same API on both paths
+renderer.play()
+```
+
+When your bundler owns worker bundling (recommended for apps), pass a
+pre-constructed worker instead of a URL — this is correct in both dev and
+prod builds (Vite example):
+
+```ts
+import RendererWorker from './worker-entry.ts?worker' // or an aliased path
+
+const renderer = await createRenderer(canvas, {
+  worker: new RendererWorker(),
+})
+```
+
+Fallback order: worker + WebGL2 → worker + WebGL1 → main thread. The
+`onFallback` reason is one of `no-worker`, `no-offscreen-canvas`, `no-webgl`,
+`worker-spawn-failed`, `worker-handshake-timeout`, `worker-version-mismatch`,
+or `worker-gl-unavailable`. `mode: 'worker'` throws `WorkerUnsupportedError`
+instead of falling back; `mode: 'main'` pins the legacy path (also used
+automatically for pinned CDN builds, where the worker entry cannot be
+resolved reliably). If the worker dies _after_ the canvas was transferred
+(the surface cannot be recovered), creation throws even in `auto` mode and
+`onFallback` reports `worker-transferred-fatal`.
+
+One canvas, one renderer: `transferControlToOffscreen` is irreversible. Mount
+a fresh canvas element per renderer (e.g. on framework remounts/HMR) and
+dispose the previous renderer first — reusing a transferred canvas throws
+`WorkerUnsupportedError` (`canvas-already-bound`) instead of failing obscurely.
+
+Worker-path notes:
+
+- Reads (`getMetrics`, `getPassNames`, `getContextState`) are served from
+  caches the worker pushes — same sync signatures, ≤ ~500ms staleness.
+- `capturePassDataURL` returns the last pushed thumbnail; call
+  `requestPassCapture(name)` first (e.g. on a poll interval) for fresh frames.
+- Uniform providers cross the boundary only as static descriptors:
+  `registerUniformProvider({ id, values })`. Function providers, `Pass`
+  objects (`addPass`/`getPass`/`getPasses`/`forEachPass`), and direct
+  `new WebGLRenderer(canvas)` (deprecated, still supported) require the main
+  thread.
+- Dispose with `renderer.dispose()` to terminate the worker.
+
 ## Contributing
 
 Contributions are welcome! Please open an issue or submit a pull request on GitHub.