@octane-xplat/shaders 0.0.0-nightly.g14544fe

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+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

@@ -0,0 +1,108 @@
+# `@octane-xplat/shaders`
+
+Runs the published [`shaders`](https://www.npmjs.com/package/shaders) WebGPU
+engine (pinned `4.0.0`, used unchanged — no vendoring, no shader port) on an
+Octane Xplat `Canvas` surface from `@octane-xplat/canvas`. Use it for the
+upstream engine's procedural presets — noise, gradients, and other generated
+effects. The adapter deliberately does not create a new shader API; it only
+adds the surface/lifecycle glue Xplat needs. Preset shapes, effect names,
+parameters, options, and the returned instance's methods — `update(id, props)`,
+`resize()`, `pause()`, `resume()`, `destroy()`, `getFailureReason()` — are
+upstream's.
+
+```sh
+pnpm add @octane-xplat/shaders
+```
+
+## Usage
+
+```tsx
+import { Canvas } from '@octane-xplat/canvas'
+import { createShader } from '@octane-xplat/shaders'
+
+;<Canvas
+	width={320}
+	height={180}
+	style={{ width: 320, height: 180 }}
+	onReady={({ canvas }) => {
+		void createShader(canvas, {
+			components: [
+				{
+					id: 'background',
+					type: 'SimplexNoise',
+					props: { colorA: '#0f172a', colorB: '#7c3aed', scale: 2, seed: 7, speed: 0.5 },
+				},
+			],
+		})
+	}}
+/>
+```
+
+Working demo: `ShaderDemo` in `packages/demos` (parameter updates, pause/resume,
+static fallback, reduced-motion still frame, disposal on unmount).
+
+## What the adapter adds
+
+- `createShader(canvas, preset, options?)` — same signature as upstream
+  `shaders/js`'s `createShader`, except `canvas` is the Xplat Canvas surface
+  (`CanvasReady.canvas`) and options add `signal` (abort deferred/in-flight init;
+  a late completion is destroyed, never revived).
+- `disableTelemetry` defaults to `true`. Upstream telemetry stays off unless you
+  pass `disableTelemetry: false`. No hosted account, preset download, or network
+  access is required for local presets.
+- Deferred init: until the surface reports a positive size, nothing touches the
+  GPU. The static content behind your canvas stays put.
+- Host suspension: app backgrounding (NativeScript `suspend`/`resume`), surface
+  detach (`loaded`/`unloaded`), and `document` visibility (web) pause rendering —
+  without overriding an explicit caller `pause()` when the host returns.
+- `createSharedDevice()` — acquire `{ device, adapter }` through the platform
+  entry point (`navigator.gpu` on web, the `@nativescript/canvas` GPU shim on
+  native) for callers that want to own/share the device via `options.gpu`.
+  Instances never destroy a caller-provided or adapter-shared device.
+- `isWebGPUSupported()` / `getWebGPUSupport()` — upstream capability helpers,
+  native-aware.
+- `prefersReducedMotion()` — OS reduced-motion preference; pause after the first
+  frame to hold a still, or keep the static fallback.
+
+## Target status
+
+| Target                            | Status                                                                                                                                                                                                                                                                                                                                                                                  |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Web (DOM)                         | Implemented. Upstream engine on the browser WebGPU canvas; reached ready + submissions in the headless-Chromium spike (SwiftShader). Hardware GPU correctness, sustained lifecycle, and visual output are unverified — a SwiftShader device-loss observed in the spike was reproduced without the library (raw WebGPU loop) and is attributed to the headless backend, not the package. |
+| NativeScript iOS                  | Implemented, experimental. `@nativescript/canvas` WebGPU (wgpu over Metal). Build/bundle/type verified; device execution pending.                                                                                                                                                                                                                                                       |
+| NativeScript Android              | Implemented, experimental. Same native route over Vulkan. Build/type verified; device/driver execution pending.                                                                                                                                                                                                                                                                         |
+| AppKit macOS / desktop native     | Explicitly unsupported. Importing the package is inert (no GPU work, no engine load); `createShader` resolves to a no-op instance with `getFailureReason() === 'unsupported'` so fallback handling is identical.                                                                                                                                                                        |
+| Web code inside a desktop webview | Follows the browser's own WebGPU support; no separate integration.                                                                                                                                                                                                                                                                                                                      |
+
+Adapter-owned native defaults: `navigator.gpu` is bound lazily to the
+`@nativescript/canvas` GPU shim on first use (upstream reads it unconditionally);
+`observeElement` defaults off on native (no DOM observers — the view's
+`layoutChanged` drives `resize()`); frame pacing uses `requestAnimationFrame`
+where the runtime provides it, else upstream's `setTimeout(~16ms)` fallback.
+
+## Limits to know
+
+- **Payload:** the engine is heavy — about **709 KB gzip** (minified browser
+  bundle for the JS host + SimplexNoise; ~705 KB via `shaders/core`). Per-effect
+  imports do not shrink it because the core renderer pulls the full registry.
+  This cost lands only in apps that install this optional package.
+- **Upstream packaging defects:** `shaders@4.0.0` declares 34 export subpaths
+  that point to absent files (e.g. `./core/RadialLines`, `./core/GradientNoise`).
+  `shaders/js`, `shaders/core`, and `shaders/core/SimplexNoise` are intact. Treat
+  other subpaths as unverified until you check the file exists. Upstream `.d.ts`
+  files also use extensionless relative imports, so they do not resolve under
+  `moduleResolution: 'nodenext'` — consumers need bundler-style resolution (all
+  Xplat toolchain paths use it).
+- **Catalog coverage:** only intact procedural effect definitions without
+  browser-only inputs are in the initial native compatibility claim. DOM capture,
+  HTML/text-specific facilities, cursor/mouse-driven effects, media sources,
+  hosted presets, and simulations may fail on native — upstream reports terminal
+  failures via `onError`/`getFailureReason()`; keep the static fallback mounted.
+- **Recovery:** device loss uses upstream's own rebuild path (≤3 attempts); there
+  is no adapter-level retry loop. Terminal reasons stop rendering permanently.
+
+## Publishing
+
+The package joins the automated lockstep release (non-private `packages/*`). The
+one-time npm stub + trusted-publisher setup is still required before the first
+release can ship it — see `.agents/docs/releases.md`.

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@octane-xplat/shaders",
+  "version": "0.0.0-nightly.g14544fe",
+  "description": "Thin adapter that runs the published `shaders` WebGPU library on Octane xplat Canvas surfaces — web (implemented) and NativeScript iOS/Android (experimental, device verification pending)",
+  "keywords": [
+    "canvas",
+    "cross-platform",
+    "gpu",
+    "graphics",
+    "nativescript",
+    "octane",
+    "shader",
+    "webgpu",
+    "wgsl",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/shaders",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
+    "directory": "packages/shaders"
+  },
+  "files": [
+    "types",
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": {
+        "types": "./types/index.macos.d.ts",
+        "default": "./src/index.macos.ts"
+      },
+      "types": "./types/index.d.ts",
+      "web": "./src/index.web.ts",
+      "native": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@octane-xplat/canvas": "0.0.0-nightly.g14544fe",
+    "shaders": "4.0.0"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.5",
+    "@nativescript/core": "9.1.3",
+    "@octanejs/vite-plugin": "0.1.61",
+    "octane": "0.11.0",
+    "tsrx-typegen": "0.3.0",
+    "typescript": "5.9.3",
+    "vite": "8.3.0"
+  },
+  "peerDependencies": {
+    "@nativescript/core": ">=9.1.0 <10"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript/core": {
+      "optional": true
+    }
+  },
+  "nativescript": {
+    "platforms": {
+      "ios": "7.0.0",
+      "android": "7.0.0"
+    }
+  },
+  "scripts": {
+    "typegen": "tsc -p tsconfig.types.json",
+    "check-types": "tsc -p tsconfig.check.json",
+    "test:packed": "node tests/packed-consumer.mjs",
+    "pack:check": "tsrx-typegen --pack-check"
+  }
+}

package/src/host.ts

@@ -0,0 +1,231 @@
+// Native host (iOS/Android via NativeScript) — the Xplat Canvas surface is
+// a `@nativescript/canvas` Canvas view. The engine consumes a DOM-canvas
+// shape (`style`, `getBoundingClientRect`, `width`/`height` buffer
+// writes), so the view is wrapped in a facade that delegates `getContext`
+// and swallows style/buffer writes instead of resizing the view.
+//
+// Adapter-owned native defaults:
+// - `navigator.gpu` is lazily bound to the plugin's GPU shim on first use
+//   (never at import) so upstream's own acquisition, capability checks and
+//   device-loss recovery work unchanged.
+// - `observeElement` defaults off: there is no DOM
+//   ResizeObserver/IntersectionObserver; sizing is driven by the view's
+//   `layoutChanged` event and forwarded to `instance.resize()`.
+// - App suspend/resume and view unload/load map to host suspension.
+//
+// Frame pacing falls back to upstream's `setTimeout(16)` loop when the
+// runtime lacks `requestAnimationFrame`. Experimental: iOS/Android device
+// verification is still pending.
+
+import { Application, View, isAndroid, isIOS } from '@nativescript/core'
+import { getGPU } from '@octane-xplat/canvas'
+import {
+	createShader as upstreamCreateShader,
+	createSharedDevice as upstreamCreateSharedDevice,
+	getWebGPUSupport as upstreamGetWebGPUSupport,
+	isWebGPUSupported as upstreamIsWebGPUSupported,
+} from 'shaders/js'
+
+import type {
+	CreateShaderOptions,
+	PresetConfig,
+	SharedGpu,
+	ShaderInstance,
+	WebGPUSupportInfo,
+} from './types'
+
+import { resolveOptions, throwIfAborted, waitForPositiveSize, wrapInstance } from './shared'
+import type { Size } from './shared'
+
+let gpuShim: any
+let gpuResolved = false
+
+/** The plugin's GPU shim is also installed as `navigator.gpu` — upstream
+ *  (and TypeGPU's `configureContext`) reads it unconditionally. */
+function ensureGpu(): any {
+	if (!gpuResolved) {
+		gpuResolved = true
+		try {
+			gpuShim = getGPU()
+		} catch {
+			gpuShim = null
+		}
+	}
+
+	const gpu = gpuShim
+	if (!gpu) {
+		return null
+	}
+
+	const g = globalThis as any
+	try {
+		if (!g.navigator) {
+			g.navigator = {}
+		}
+
+		if (!g.navigator.gpu) {
+			try {
+				g.navigator.gpu = gpu
+			} catch {
+				Object.defineProperty(g.navigator, 'gpu', { configurable: true, value: gpu })
+			}
+		}
+	} catch {
+		// `navigator` may be a read-only global — injected `gpu` still applies.
+	}
+
+	return gpu
+}
+
+function measure(view: any): Size {
+	const rect = view?.getBoundingClientRect?.()
+	const actual = view?.getActualSize?.()
+	const width = Number(rect?.width) || Number(actual?.width) || Number(view?.width) || 0
+	const height = Number(rect?.height) || Number(actual?.height) || Number(view?.height) || 0
+	return { width, height }
+}
+
+/** DOM-canvas-shaped facade over the plugin view. `width`/`height` writes
+ *  (upstream's drawing-buffer bookkeeping) are stored locally so the
+ *  plugin view's layout size is never mutated by buffer pixel counts. */
+function hostCanvas(view: any): any {
+	const bag = { style: {} as Record<string, string>, width: 0, height: 0 }
+	return {
+		getContext: (kind: string, options?: any) => view.getContext(kind, options),
+		getBoundingClientRect: () => {
+			const { width, height } = measure(view)
+			return { x: 0, y: 0, top: 0, left: 0, right: width, bottom: height, width, height }
+		},
+		get clientWidth() {
+			return measure(view).width
+		},
+		get clientHeight() {
+			return measure(view).height
+		},
+		get width() {
+			return bag.width || measure(view).width
+		},
+		set width(value: number) {
+			bag.width = value
+		},
+		get height() {
+			return bag.height || measure(view).height
+		},
+		set height(value: number) {
+			bag.height = value
+		},
+		get style() {
+			return bag.style
+		},
+		parentElement: null,
+	}
+}
+
+async function acquireInjectedGpu(): Promise<SharedGpu | null> {
+	const gpu = ensureGpu()
+	if (!gpu?.requestAdapter) {
+		return null
+	}
+
+	try {
+		const adapter = await gpu.requestAdapter()
+		if (!adapter) {
+			return null
+		}
+
+		const device = await adapter.requestDevice()
+		return device ? { device, adapter } : null
+	} catch {
+		return null
+	}
+}
+
+export async function createShader(
+	canvas: unknown,
+	preset: PresetConfig,
+	options?: CreateShaderOptions,
+): Promise<ShaderInstance> {
+	const { upstream, signal } = resolveOptions(options, { observeElement: false })
+	throwIfAborted(signal)
+	const host = hostCanvas(canvas)
+	await waitForPositiveSize(() => measure(canvas), signal)
+	// Adapter-acquired device (shared default when the caller supplies no
+	// `gpu`) — never destroyed by the adapter, so one instance's destroy
+	// cannot kill another's shared device.
+	if (!upstream.gpu) {
+		const gpu = await acquireInjectedGpu()
+		if (gpu) {
+			upstream.gpu = gpu
+		}
+	}
+
+	throwIfAborted(signal)
+	const inner = await upstreamCreateShader(host, preset, upstream as any)
+	if (signal?.aborted) {
+		inner.destroy()
+		throwIfAborted(signal)
+	}
+
+	const view = canvas as any
+	const attach = (hide: () => void, show: () => void) => {
+		const onLayout = () => inner.resize()
+		Application.on(Application.suspendEvent, hide)
+		Application.on(Application.resumeEvent, show)
+		view?.on?.(View.unloadedEvent, hide)
+		view?.on?.(View.loadedEvent, show)
+		view?.on?.(View.layoutChangedEvent, onLayout)
+		return () => {
+			Application.off(Application.suspendEvent, hide)
+			Application.off(Application.resumeEvent, show)
+			view?.off?.(View.unloadedEvent, hide)
+			view?.off?.(View.loadedEvent, show)
+			view?.off?.(View.layoutChangedEvent, onLayout)
+		}
+	}
+
+	return wrapInstance(inner, attach)
+}
+
+export async function createSharedDevice(options?: {
+	powerPreference?: string
+}): Promise<SharedGpu | null> {
+	ensureGpu()
+	return upstreamCreateSharedDevice(options as any)
+}
+
+export function isWebGPUSupported(): boolean {
+	ensureGpu()
+	return upstreamIsWebGPUSupported()
+}
+
+export function getWebGPUSupport(): Promise<WebGPUSupportInfo> {
+	ensureGpu()
+	return upstreamGetWebGPUSupport()
+}
+
+export function prefersReducedMotion(): boolean {
+	try {
+		if (isIOS) {
+			const check = (globalThis as any).UIAccessibilityIsReduceMotionEnabled
+			return typeof check === 'function' ? !!check() : false
+		}
+
+		if (isAndroid) {
+			const context = Application.android?.context
+			const settings = (globalThis as any).android?.provider?.Settings
+			if (!context || !settings?.Global) {
+				return false
+			}
+
+			const scale = settings.Global.getFloat(
+				context.getContentResolver(),
+				settings.Global.ANIMATOR_DURATION_SCALE,
+				1,
+			)
+
+			return scale === 0
+		}
+	} catch {}
+
+	return false
+}

package/src/host.web.ts

@@ -0,0 +1,82 @@
+// Web host — the Xplat Canvas surface is already a real
+// HTMLCanvasElement, so it reaches upstream unchanged. The adapter adds:
+// deferred init until positive size, telemetry off by default, abortable
+// init, and document-visibility suspension that composes with caller
+// pause. Offscreen/detach suspension is upstream's own observers
+// (`observeElement`, default on).
+
+import {
+	createShader as upstreamCreateShader,
+	createSharedDevice as upstreamCreateSharedDevice,
+	getWebGPUSupport as upstreamGetWebGPUSupport,
+	isWebGPUSupported as upstreamIsWebGPUSupported,
+} from 'shaders/js'
+
+import type {
+	CreateShaderOptions,
+	PresetConfig,
+	SharedGpu,
+	ShaderInstance,
+	WebGPUSupportInfo,
+} from './types'
+
+import { resolveOptions, throwIfAborted, waitForPositiveSize, wrapInstance } from './shared'
+import type { Size } from './shared'
+
+function measure(canvas: any): Size {
+	const rect = canvas?.getBoundingClientRect?.()
+	const width = Number(rect?.width) || Number(canvas?.width) || 0
+	const height = Number(rect?.height) || Number(canvas?.height) || 0
+	return { width, height }
+}
+
+function attachVisibility(hide: () => void, show: () => void): () => void {
+	const doc = (globalThis as any).document
+	if (!doc?.addEventListener) {
+		return () => {}
+	}
+
+	const onChange = () => (doc.visibilityState === 'hidden' ? hide() : show())
+	doc.addEventListener('visibilitychange', onChange)
+	return () => doc.removeEventListener('visibilitychange', onChange)
+}
+
+export async function createShader(
+	canvas: unknown,
+	preset: PresetConfig,
+	options?: CreateShaderOptions,
+): Promise<ShaderInstance> {
+	const { upstream, signal } = resolveOptions(options, {})
+	throwIfAborted(signal)
+	await waitForPositiveSize(() => measure(canvas), signal)
+	const inner = await upstreamCreateShader(canvas as any, preset, upstream)
+	if (signal?.aborted) {
+		// Unmounted while the async engine was starting — release the late
+		// completion instead of reviving a disposed surface.
+		inner.destroy()
+		throwIfAborted(signal)
+	}
+
+	return wrapInstance(inner, attachVisibility)
+}
+
+export function createSharedDevice(options?: {
+	powerPreference?: string
+}): Promise<SharedGpu | null> {
+	return upstreamCreateSharedDevice(options as any)
+}
+
+export function isWebGPUSupported(): boolean {
+	return upstreamIsWebGPUSupported()
+}
+
+export function getWebGPUSupport(): Promise<WebGPUSupportInfo> {
+	return upstreamGetWebGPUSupport()
+}
+
+export function prefersReducedMotion(): boolean {
+	const matchMedia = (globalThis as any).matchMedia
+	return typeof matchMedia === 'function'
+		? !!matchMedia('(prefers-reduced-motion: reduce)').matches
+		: false
+}

package/src/index.macos.ts

@@ -0,0 +1,49 @@
+// Native-desktop entry — explicitly unsupported. No engine import, no GPU
+// work at module load: this leaf never touches `shaders` at runtime, so
+// importing the package on AppKit is inert. `createShader` resolves to a
+// no-op instance reporting the upstream-style 'unsupported' failure
+// reason so callers keep their static fallback path identical to web's.
+export * from './types'
+import type {
+	CreateShaderOptions,
+	PresetConfig,
+	SharedGpu,
+	ShaderInstance,
+	WebGPUSupportInfo,
+} from './types'
+
+const UNSUPPORTED: ShaderInstance = {
+	getFailureReason: () => 'unsupported',
+	update: () => {},
+	resize: () => {},
+	pause: () => {},
+	resume: () => {},
+	destroy: () => {},
+}
+
+export async function createShader(
+	_canvas: unknown,
+	_preset: PresetConfig,
+	options?: CreateShaderOptions,
+): Promise<ShaderInstance> {
+	options?.onError?.('unsupported')
+	return UNSUPPORTED
+}
+
+export async function createSharedDevice(_options?: {
+	powerPreference?: string
+}): Promise<SharedGpu | null> {
+	return null
+}
+
+export function isWebGPUSupported(): boolean {
+	return false
+}
+
+export async function getWebGPUSupport(): Promise<WebGPUSupportInfo> {
+	return { supported: false, reason: 'unsupported' }
+}
+
+export function prefersReducedMotion(): boolean {
+	return false
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// Native entry (iOS/Android via @nativescript/canvas) — same exports as
+// index.web.ts and index.macos.ts.
+export * from './types'
+export {
+	createShader,
+	createSharedDevice,
+	getWebGPUSupport,
+	isWebGPUSupported,
+	prefersReducedMotion,
+} from './host'

package/src/index.web.ts

@@ -0,0 +1,9 @@
+// Web entry — same exports as index.ts and index.macos.ts.
+export * from './types'
+export {
+	createShader,
+	createSharedDevice,
+	getWebGPUSupport,
+	isWebGPUSupported,
+	prefersReducedMotion,
+} from './host.web'

package/src/shared.ts

@@ -0,0 +1,138 @@
+// Shared adapter internals — platform-free. No DOM globals, no
+// NativeScript imports; each platform leaf injects its measure/attach
+// hooks.
+
+import type { AbortSignalLike, CreateShaderOptions, ShaderInstance } from './types'
+
+export function abortError(): Error {
+	const error = new Error('createShader aborted before initialization completed')
+	error.name = 'AbortError'
+	return error
+}
+
+export function throwIfAborted(signal?: AbortSignalLike): void {
+	if (signal?.aborted) {
+		throw abortError()
+	}
+}
+
+export interface Size {
+	width: number
+	height: number
+}
+
+/** Defer until the surface reports a positive size (surface not attached /
+ *  zero-size layout → wait, don't init). Aborts via `signal`. */
+export function waitForPositiveSize(measure: () => Size, signal?: AbortSignalLike): Promise<void> {
+	const first = measure()
+	if (first.width > 0 && first.height > 0) {
+		return Promise.resolve()
+	}
+
+	return new Promise<void>((resolve, reject) => {
+		let timer: ReturnType<typeof setTimeout> | undefined
+		const stop = () => {
+			if (timer !== undefined) {
+				clearTimeout(timer)
+			}
+
+			signal?.removeEventListener?.('abort', onAbort)
+		}
+
+		const onAbort = () => {
+			stop()
+			reject(abortError())
+		}
+
+		const poll = () => {
+			if (signal?.aborted) {
+				return onAbort()
+			}
+
+			const size = measure()
+			if (size.width > 0 && size.height > 0) {
+				stop()
+				resolve()
+				return
+			}
+
+			timer = setTimeout(poll, 50)
+		}
+
+		signal?.addEventListener?.('abort', onAbort)
+		timer = setTimeout(poll, 50)
+	})
+}
+
+/** Merge caller options with adapter defaults. `disableTelemetry` defaults
+ *  on for this package's local/preset-driven use; callers may re-enable it.
+ *  The adapter-only `signal` key is stripped before reaching upstream. */
+export function resolveOptions(
+	options: CreateShaderOptions | undefined,
+	platformDefaults: Partial<CreateShaderOptions>,
+): { upstream: Omit<CreateShaderOptions, 'signal'>; signal?: AbortSignalLike } {
+	const { signal, ...rest } = options ?? {}
+	return {
+		signal,
+		upstream: {
+			...platformDefaults,
+			...rest,
+			disableTelemetry: options?.disableTelemetry ?? true,
+		},
+	}
+}
+
+/** Subscribe/unsubscribe pair for host hide/show (backgrounding, detach,
+ *  document visibility). */
+export type AttachLifecycle = (hide: () => void, show: () => void) => () => void
+
+/** Wrap the upstream instance so host suspension composes with caller
+ *  pause instead of overriding it: host hide pauses, host show resumes
+ *  only when the caller did not explicitly pause. `destroy` detaches all
+ *  adapter-owned listeners before delegating. */
+export function wrapInstance(inner: ShaderInstance, attach: AttachLifecycle): ShaderInstance {
+	let callerPaused = false
+	let hostSuspended = false
+	let destroyed = false
+	const detach = attach(
+		() => {
+			if (destroyed) {
+				return
+			}
+
+			hostSuspended = true
+			inner.pause()
+		},
+		() => {
+			hostSuspended = false
+			if (!destroyed && !callerPaused) {
+				inner.resume()
+			}
+		},
+	)
+
+	return {
+		getFailureReason: () => inner.getFailureReason(),
+		update: (id, props) => inner.update(id, props),
+		resize: (width?, height?) => inner.resize(width, height),
+		pause: () => {
+			callerPaused = true
+			inner.pause()
+		},
+		resume: () => {
+			callerPaused = false
+			if (!hostSuspended) {
+				inner.resume()
+			}
+		},
+		destroy: () => {
+			if (destroyed) {
+				return
+			}
+
+			destroyed = true
+			detach()
+			inner.destroy()
+		},
+	}
+}

package/src/types.ts

@@ -0,0 +1,86 @@
+// Public contract for @octane-xplat/shaders — re-exports the upstream
+// `shaders` types verbatim and declares the adapter's added surface. Kept
+// platform-free: every platform leaf (web / native / macos stub) exposes
+// exactly these names.
+
+// Upstream types are re-exported as aliases rather than `export type {…}
+// from 'shaders/js'` so they stay unambiguously type-only for the pack
+// check even where the specifier can't be resolved.
+export type ComponentConfig = import('shaders/js').ComponentConfig
+export type GpuFailureReason = import('shaders/js').GpuFailureReason
+export type PresetConfig = import('shaders/js').PresetConfig
+export type ShaderInstance = import('shaders/js').ShaderInstance
+export type ShaderOptions = import('shaders/js').ShaderOptions
+export type WebGPUSupportInfo = import('shaders/js').WebGPUSupportInfo
+
+/** Structural AbortSignal — the real DOM AbortSignal satisfies this; so
+ *  does NativeScript's. Kept structural so shared code never names DOM
+ *  globals. */
+export interface AbortSignalLike {
+	readonly aborted: boolean
+	addEventListener?(type: 'abort', listener: () => void): void
+	removeEventListener?(type: 'abort', listener: () => void): void
+}
+
+/** Externally acquired WebGPU device + adapter pair — the caller owns its
+ *  lifetime. Pass to `createShader` via `options.gpu` to share one device
+ *  across instances. */
+export interface SharedGpu {
+	device: any
+	adapter: any
+}
+
+/** Upstream `ShaderOptions` plus adapter lifecycle glue. Preset, component
+ *  names, parameters, and all other fields keep upstream semantics. */
+export interface CreateShaderOptions extends ShaderOptions {
+	/** Aborts deferred or in-flight initialization — e.g. the surface
+	 *  unmounted while the engine was still starting. A late completion is
+	 *  destroyed, never revived. */
+	signal?: AbortSignalLike
+}
+
+/** Create a shader on an Xplat Canvas surface (the `canvas` from
+ *  `CanvasReady`: HTMLCanvasElement on web, `@nativescript/canvas` view on
+ *  native). Same signature shape and return contract as upstream
+ *  `createShader` — the resolved instance keeps upstream
+ *  `update/resize/pause/resume/destroy/getFailureReason` semantics.
+ *
+ *  Adapter additions, all documented:
+ *  - `disableTelemetry` defaults to true (upstream default is off → on).
+ *  - Init defers until the surface reports a positive size.
+ *  - Host suspension (app background, surface detach, document hidden)
+ *    pauses rendering without overriding an explicit caller `pause()`.
+ *  - `options.signal` cancels before init completes.
+ *  - On native, the canvas is wrapped in a DOM-canvas-shaped facade and
+ *    `navigator.gpu` is lazily bound to the `@nativescript/canvas` GPU
+ *    shim so upstream capability checks and device-loss recovery work.
+ *
+ *  On unsupported hosts (native desktop) the returned promise resolves to
+ *  a no-op instance whose `getFailureReason()` is `'unsupported'`. */
+export declare function createShader(
+	canvas: unknown,
+	preset: PresetConfig,
+	options?: CreateShaderOptions,
+): Promise<ShaderInstance>
+
+/** Acquire a WebGPU `{device, adapter}` through the platform entry point
+ *  (`navigator.gpu` on web, the `@nativescript/canvas` GPU shim on native).
+ *  Resolves null where WebGPU is unavailable — keep the static fallback in
+ *  that case. The caller owns the device; the adapter never destroys it. */
+export declare function createSharedDevice(options?: {
+	powerPreference?: string
+}): Promise<SharedGpu | null>
+
+/** True when a WebGPU entry point exists. On native this reflects the
+ *  `@nativescript/canvas` GPU shim, not actual driver capability — request
+ *  an adapter via `createSharedDevice()`/`getWebGPUSupport()` for a real
+ *  check. */
+export declare function isWebGPUSupported(): boolean
+
+/** Async capability probe — resolves `{supported, reason?}` using upstream
+ *  failure-reason vocabulary ('unsupported', 'no-adapter', …). */
+export declare function getWebGPUSupport(): Promise<WebGPUSupportInfo>
+
+/** OS-level reduced-motion preference. Use it to hold a still frame
+ *  (pause after the first rendered frame) or keep the static fallback. */
+export declare function prefersReducedMotion(): boolean

package/types/index.d.ts

@@ -0,0 +1 @@
+export * from './types.js'

package/types/index.macos.d.ts

@@ -0,0 +1,5 @@
+// Native desktop keeps the same public surface as the other targets —
+// the functions resolve to the unsupported no-op implementations.
+// Re-exports types.d.ts directly: under .macos moduleSuffixes, './index.js'
+// would resolve back to this file.
+export * from './types.js'

package/types/types.d.ts

@@ -0,0 +1,66 @@
+export type ComponentConfig = import('shaders/js').ComponentConfig;
+export type GpuFailureReason = import('shaders/js').GpuFailureReason;
+export type PresetConfig = import('shaders/js').PresetConfig;
+export type ShaderInstance = import('shaders/js').ShaderInstance;
+export type ShaderOptions = import('shaders/js').ShaderOptions;
+export type WebGPUSupportInfo = import('shaders/js').WebGPUSupportInfo;
+/** Structural AbortSignal — the real DOM AbortSignal satisfies this; so
+ *  does NativeScript's. Kept structural so shared code never names DOM
+ *  globals. */
+export interface AbortSignalLike {
+    readonly aborted: boolean;
+    addEventListener?(type: 'abort', listener: () => void): void;
+    removeEventListener?(type: 'abort', listener: () => void): void;
+}
+/** Externally acquired WebGPU device + adapter pair — the caller owns its
+ *  lifetime. Pass to `createShader` via `options.gpu` to share one device
+ *  across instances. */
+export interface SharedGpu {
+    device: any;
+    adapter: any;
+}
+/** Upstream `ShaderOptions` plus adapter lifecycle glue. Preset, component
+ *  names, parameters, and all other fields keep upstream semantics. */
+export interface CreateShaderOptions extends ShaderOptions {
+    /** Aborts deferred or in-flight initialization — e.g. the surface
+     *  unmounted while the engine was still starting. A late completion is
+     *  destroyed, never revived. */
+    signal?: AbortSignalLike;
+}
+/** Create a shader on an Xplat Canvas surface (the `canvas` from
+ *  `CanvasReady`: HTMLCanvasElement on web, `@nativescript/canvas` view on
+ *  native). Same signature shape and return contract as upstream
+ *  `createShader` — the resolved instance keeps upstream
+ *  `update/resize/pause/resume/destroy/getFailureReason` semantics.
+ *
+ *  Adapter additions, all documented:
+ *  - `disableTelemetry` defaults to true (upstream default is off → on).
+ *  - Init defers until the surface reports a positive size.
+ *  - Host suspension (app background, surface detach, document hidden)
+ *    pauses rendering without overriding an explicit caller `pause()`.
+ *  - `options.signal` cancels before init completes.
+ *  - On native, the canvas is wrapped in a DOM-canvas-shaped facade and
+ *    `navigator.gpu` is lazily bound to the `@nativescript/canvas` GPU
+ *    shim so upstream capability checks and device-loss recovery work.
+ *
+ *  On unsupported hosts (native desktop) the returned promise resolves to
+ *  a no-op instance whose `getFailureReason()` is `'unsupported'`. */
+export declare function createShader(canvas: unknown, preset: PresetConfig, options?: CreateShaderOptions): Promise<ShaderInstance>;
+/** Acquire a WebGPU `{device, adapter}` through the platform entry point
+ *  (`navigator.gpu` on web, the `@nativescript/canvas` GPU shim on native).
+ *  Resolves null where WebGPU is unavailable — keep the static fallback in
+ *  that case. The caller owns the device; the adapter never destroys it. */
+export declare function createSharedDevice(options?: {
+    powerPreference?: string;
+}): Promise<SharedGpu | null>;
+/** True when a WebGPU entry point exists. On native this reflects the
+ *  `@nativescript/canvas` GPU shim, not actual driver capability — request
+ *  an adapter via `createSharedDevice()`/`getWebGPUSupport()` for a real
+ *  check. */
+export declare function isWebGPUSupported(): boolean;
+/** Async capability probe — resolves `{supported, reason?}` using upstream
+ *  failure-reason vocabulary ('unsupported', 'no-adapter', …). */
+export declare function getWebGPUSupport(): Promise<WebGPUSupportInfo>;
+/** OS-level reduced-motion preference. Use it to hold a still frame
+ *  (pause after the first rendered frame) or keep the static fallback. */
+export declare function prefersReducedMotion(): boolean;