@octane-xplat/canvas 0.0.0-nightly.g2e22171

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,100 @@
+# `@octane-xplat/canvas`
+
+```sh
+pnpm add @octane-xplat/canvas
+```
+
+A GPU/canvas surface for Octane xplat apps: the DOM `<canvas>` on web and
+`@nativescript/canvas` on iOS/Android — 2D, WebGL/WebGL2, and
+WebGPU/WGSL context kinds behind one `getContext` contract.
+
+```tsx
+import { Canvas } from '@octane-xplat/canvas'
+
+export function Drawing() {
+	return (
+		<Canvas
+			context="2d"
+			width={640}
+			height={480}
+			onReady={({ context }) => {
+				if (!context) return
+				context.fillStyle = '#2563eb'
+				context.fillRect(0, 0, 80, 80)
+			}}
+		/>
+	)
+}
+```
+
+Pass `context` to have the leaf resolve it before `onReady`, or omit it and
+call `getContext` yourself — one kind per canvas, decided on first call.
+`onReady` fires after mount on web and on the plugin's `ready` event on
+iOS/Android (earlier `getContext` calls can return null). For WebGPU,
+`getGPU()` normalizes adapter/device acquisition across targets.
+
+```tsx
+import { Canvas, getGPU } from '@octane-xplat/canvas'
+
+export function DeferredCanvas() {
+	return (
+		<Canvas
+			onReady={({ canvas }) => {
+				const context = canvas.getContext('2d')
+				if (context) context.fillRect(0, 0, 20, 20)
+			}}
+		/>
+	)
+}
+const gpu = getGPU()
+const adapter = await gpu?.requestAdapter()
+const device = await adapter?.requestDevice()
+```
+
+## Keep a fallback when drawing is unavailable
+
+Native macOS/AppKit imports and mounts safely, but drawing is unsupported.
+`onReady` reports `context: null` after a neutral frame mounts; it does not
+announce a drawing surface. Its unavailable `canvas` handle returns `null`
+from `getContext()` for every kind, including `2d`, `webgl`, `webgl2`,
+`webgpu`, and `bitmaprenderer`. `getGPU()` also returns `null`, so no adapter
+or device can be acquired. Check these results before drawing and keep your
+own static fallback. For example, put this component in your app:
+
+```tsx
+import { Canvas, getGPU } from '@octane-xplat/canvas'
+import { Text, View } from '@octane-xplat/ui'
+import { useState } from 'octane'
+
+export function DrawingWithFallback() {
+	const [drawn, setDrawn] = useState(false)
+	return (
+		<View>
+			{!drawn && <Text>Blue square illustration</Text>}
+			<Canvas
+				context="2d"
+				width={80}
+				height={80}
+				onReady={({ canvas, context }) => {
+					const drawing = context ?? canvas.getContext('2d')
+					if (!drawing) return
+					drawing.fillStyle = '#2563eb'
+					drawing.fillRect(0, 0, 80, 80)
+					setDrawn(true)
+				}}
+			/>
+		</View>
+	)
+}
+
+// AppKit returns null here, before adapter/device acquisition.
+const gpu = getGPU()
+```
+
+The AppKit backend for 2D, WebGL, and WebGPU remains deferred until a concrete
+consumer needs one and the implementation is approved. Native desktop shader
+effects remain unsupported. A DOM webview uses the separate web implementation.
+
+Per-target limits are recorded in
+[known limits](../../docs/verify/known-limits.md). Exercised by
+[`CanvasDemo`](../demos/src/CanvasDemo.tsrx) (including a WGSL path).

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@octane-xplat/canvas",
+  "version": "0.0.0-nightly.g2e22171",
+  "description": "Canvas/GPU surface for Octane xplat — web <canvas> + @nativescript/canvas (2D, WebGL/WebGL2, WebGPU/WGSL)",
+  "keywords": [
+    "canvas",
+    "cross-platform",
+    "gpu",
+    "graphics",
+    "nativescript",
+    "octane",
+    "webgl",
+    "webgl2",
+    "webgpu",
+    "wgsl",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/canvas",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
+    "directory": "packages/canvas"
+  },
+  "files": [
+    "types",
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "web": "./src/index.web.ts",
+      "macos": "./src/index.macos.ts",
+      "native": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nativescript/canvas": "3.0.0-alpha.15"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.5",
+    "@nativescript/core": "9.1.3",
+    "@octane-xplat/macos-renderer": "0.0.0-nightly.g2e22171",
+    "@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-community/octane": ">=0.2.1 <1",
+    "@nativescript/core": ">=9.1.0 <10",
+    "@octane-xplat/macos-renderer": "0.0.0-nightly.g2e22171",
+    "octane": ">=0.6.3 <1"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    },
+    "@octane-xplat/macos-renderer": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "typegen": "tsc -p tsconfig.types.json",
+    "test:packed": "node tests/packed-consumer.mjs",
+    "test:macos-runtime": "node ../../scripts/probe.mjs run tests/unsupported.macos.tsrx --target macos --deps @octane-xplat/canvas",
+    "pack:check": "tsrx-typegen --pack-check"
+  }
+}

package/src/Canvas.macos.tsrx

@@ -0,0 +1,23 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useEffect } from 'octane';
+import type { CanvasContextKind, CanvasProps } from './props';
+
+/** AppKit mounts a neutral frame. No drawing surface or GPU is created. */
+export function Canvas(props: CanvasProps) @{
+	useEffect(() => {
+		// Preserve deferred acquisition without pretending this is a native view.
+		const canvas = Object.freeze({
+			getContext: (_kind: CanvasContextKind, _options?: any): null => null,
+		});
+
+		props.onReady?.({ canvas, context: null });
+	}, []);
+
+	<gridlayout
+		id={props.id}
+		className={props.className}
+		style={props.style}
+		width={props.width}
+		height={props.height}
+	/>;
+}

package/src/Canvas.tsrx

@@ -0,0 +1,39 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { registerElement } from '@nativescript-community/octane';
+import type { Attributes } from '@nativescript-community/octane/intrinsics';
+import { Canvas as NSCanvas } from '@nativescript/canvas';
+import type { CanvasProps } from './props';
+
+declare module '@nativescript-community/octane/intrinsics' {
+	interface NativeScriptElements {
+		nscanvas: Attributes<typeof NSCanvas>;
+	}
+}
+
+// @nativescript/canvas — Skia + wgpu core exposing the DOM Canvas API
+// (2d, webgl, webgl2, webgpu) on iOS + Android. Element name is `nscanvas`
+// rather than `canvas` because `canvas` is DOM vocabulary in the
+// element-vocabulary lint.
+registerElement('nscanvas', NSCanvas);
+
+/** Canvas — DOM Canvas API surface on native. `onReady` wraps the plugin's
+ *  `ready` event: it fires once the GPU surface exists, which is the
+ *  earliest `getContext` may be called. */
+export function Canvas(props: CanvasProps) @{
+	const ready = (event: any) => {
+		const canvas = event.object;
+		props.onReady?.({
+			canvas,
+			context: props.context ? canvas.getContext(props.context) : null,
+		});
+	};
+
+	<nscanvas
+		id={props.id}
+		className={props.className}
+		style={props.style}
+		width={props.width as any}
+		height={props.height as any}
+		onReady={ready}
+	/>;
+}

package/src/Canvas.web.tsrx

@@ -0,0 +1,39 @@
+import { useMemo, useRef } from 'octane';
+import type { CanvasProps } from './props';
+
+/** Canvas — a plain <canvas>. `onReady` fires at mount with the element
+ *  and the resolved context. */
+export function Canvas(props: CanvasProps) @{
+	// Keep the element callback referentially stable — a fresh closure each
+	// render makes the web renderer detach/reattach it, refiring onReady.
+	const propsRef = useRef(props);
+	propsRef.current = props;
+	const canvasRef = useMemo(
+		() => (el: HTMLCanvasElement | null) => {
+			if (!el) {
+				return;
+			}
+
+			propsRef.current.onReady?.({
+				canvas: el,
+				context: propsRef.current.context
+					? el.getContext(propsRef.current.context)
+					: null,
+			});
+		},
+		[],
+	);
+
+	<canvas
+		id={props.id}
+		className={props.className}
+		style={{
+			width: typeof props.width === 'string' ? props.width : undefined,
+			height: typeof props.height === 'string' ? props.height : undefined,
+			...props.style,
+		}}
+		width={typeof props.width === 'number' ? props.width : undefined}
+		height={typeof props.height === 'number' ? props.height : undefined}
+		ref={canvasRef}
+	/>
+}

package/src/gpu.macos.ts

@@ -0,0 +1,4 @@
+/** AppKit has no Canvas WebGPU backend. Returns null before device acquisition. */
+export function getGPU(): any {
+	return null
+}

package/src/gpu.ts

@@ -0,0 +1,8 @@
+import { GPU } from '@nativescript/canvas'
+
+/** getGPU — returns the plugin's GPU shim (wgpu over Metal/Vulkan). Same
+ *  spec-shaped surface as web's `navigator.gpu`: `requestAdapter()` +
+ *  `getPreferredCanvasFormat()`. */
+export function getGPU(): any {
+	return new GPU()
+}

package/src/gpu.web.ts

@@ -0,0 +1,7 @@
+/** getGPU — returns the WebGPU entry point (`navigator.gpu`) or null when
+ *  WebGPU is unavailable (insecure context, unsupported browser). The
+ *  returned object is spec-shaped: `requestAdapter()` +
+ *  `getPreferredCanvasFormat()`. */
+export function getGPU(): any {
+	return (globalThis.navigator as any)?.gpu ?? null
+}

package/src/index.macos.ts

@@ -0,0 +1,3 @@
+export { Canvas } from './Canvas.macos.tsrx'
+export { getGPU } from './gpu.macos'
+export type { CanvasProps, CanvasContextKind, CanvasReady } from './props'

package/src/index.ts

@@ -0,0 +1,5 @@
+// Platform barrels — explicit .tsrx leaf imports (moduleSuffixes don't
+// reach .tsrx; same convention as @octane-xplat/ui index.*.ts).
+export { Canvas } from './Canvas.tsrx'
+export { getGPU } from './gpu'
+export type { CanvasProps, CanvasContextKind, CanvasReady } from './props'

package/src/index.web.ts

@@ -0,0 +1,5 @@
+// Platform barrels — explicit .tsrx leaf imports (moduleSuffixes don't
+// reach .tsrx; same convention as @octane-xplat/ui index.*.ts).
+export { Canvas } from './Canvas.web.tsrx'
+export { getGPU } from './gpu.web'
+export type { CanvasProps, CanvasContextKind, CanvasReady } from './props'

package/src/props.ts

@@ -0,0 +1,31 @@
+export type CanvasContextKind = '2d' | 'webgl' | 'webgl2' | 'webgpu' | 'bitmaprenderer'
+
+export interface CanvasReady {
+	/** HTMLCanvasElement on web, the plugin's Canvas view on iOS/Android.
+	 *  AppKit supplies an unavailable handle whose `getContext()` always
+	 *  returns null; it is not a native drawing surface. */
+	canvas: any
+	/** The resolved context for the `context` prop, or null when that
+	 *  kind is unsupported/unavailable. WebGPU still needs a device —
+	 *  `getGPU()` normalizes adapter/device acquisition. */
+	context: any
+}
+
+export interface CanvasProps {
+	className?: any
+	style?: any
+	id?: string
+	/** Context kind resolved before `onReady` fires. Omit to defer
+	 *  `getContext` to user code (only one kind per canvas — call once). */
+	context?: CanvasContextKind
+	/** Web: after mount. iOS/Android: the plugin's `ready` event (earlier
+	 *  `getContext` calls can return null). AppKit: after the neutral frame
+	 *  mounts, with context null. This callback does not guarantee drawing
+	 *  or GPU readiness; check context or call canvas.getContext first. */
+	onReady?: (ready: CanvasReady) => void
+	/** Numeric values map to the element's width/height — on web that is
+	 *  the canvas *drawing buffer* size (pair with style for display
+	 *  size), on native dip size. */
+	width?: string | number
+	height?: string | number
+}

package/types/index.d.ts

@@ -0,0 +1,14 @@
+// Boundary types for @octane-xplat/canvas — the mechanical wrapper over
+// props.ts (tsrx-tsc can't emit .tsrx declarations; see ui/types/index.d.ts
+// for the same pattern).
+import type { UniversalComponent } from 'octane/universal'
+import type { CanvasProps } from './props.js'
+
+export declare const Canvas: UniversalComponent<CanvasProps>
+
+/** Returns the WebGPU entry point — `navigator.gpu` on web, the plugin's
+ *  GPU shim on iOS/Android — or null where WebGPU is unavailable.
+ *  Native AppKit always returns null. */
+export declare function getGPU(): any
+
+export type { CanvasProps, CanvasContextKind, CanvasReady } from './props.js'

package/types/props.d.ts

@@ -0,0 +1,29 @@
+export type CanvasContextKind = '2d' | 'webgl' | 'webgl2' | 'webgpu' | 'bitmaprenderer';
+export interface CanvasReady {
+    /** HTMLCanvasElement on web, the plugin's Canvas view on iOS/Android.
+     *  AppKit supplies an unavailable handle whose `getContext()` always
+     *  returns null; it is not a native drawing surface. */
+    canvas: any;
+    /** The resolved context for the `context` prop, or null when that
+     *  kind is unsupported/unavailable. WebGPU still needs a device —
+     *  `getGPU()` normalizes adapter/device acquisition. */
+    context: any;
+}
+export interface CanvasProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    /** Context kind resolved before `onReady` fires. Omit to defer
+     *  `getContext` to user code (only one kind per canvas — call once). */
+    context?: CanvasContextKind;
+    /** Web: after mount. iOS/Android: the plugin's `ready` event (earlier
+     *  `getContext` calls can return null). AppKit: after the neutral frame
+     *  mounts, with context null. This callback does not guarantee drawing
+     *  or GPU readiness; check context or call canvas.getContext first. */
+    onReady?: (ready: CanvasReady) => void;
+    /** Numeric values map to the element's width/height — on web that is
+     *  the canvas *drawing buffer* size (pair with style for display
+     *  size), on native dip size. */
+    width?: string | number;
+    height?: string | number;
+}