@octane-xplat/canvas 0.14.0 → 0.15.0

package/README.md

@@ -30,7 +30,7 @@ export function Drawing() {
 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
-native (earlier `getContext` calls can return null). For WebGPU,
+iOS/Android (earlier `getContext` calls can return null). For WebGPU,
 `getGPU()` normalizes adapter/device acquisition across targets.
 
 ```tsx
@@ -51,6 +51,50 @@ 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

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/canvas",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Canvas/GPU surface for Octane xplat — web <canvas> + @nativescript/canvas (2D, WebGL/WebGL2, WebGPU/WGSL)",
   "keywords": [
     "canvas",
@@ -23,17 +23,19 @@
     "directory": "packages/canvas"
   },
   "files": [
-    "dist",
     "types",
-    "src"
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
   ],
   "type": "module",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
-      "web": "./dist/web/index.js",
-      "native": "./dist/native/index.js",
-      "default": "./dist/native/index.js"
+      "web": "./src/index.web.ts",
+      "macos": "./src/index.macos.ts",
+      "native": "./src/index.ts",
+      "default": "./src/index.ts"
     }
   },
   "publishConfig": {
@@ -43,17 +45,19 @@
     "@nativescript/canvas": "3.0.0-alpha.15"
   },
   "devDependencies": {
-    "@nativescript-community/octane": "0.2.4",
+    "@nativescript-community/octane": "0.2.5",
     "@nativescript/core": "9.1.3",
+    "@octane-xplat/macos-renderer": "0.15.0",
     "@octanejs/vite-plugin": "0.1.61",
     "octane": "0.11.0",
-    "tsrx-typegen": "0.2.2",
+    "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.15.0",
     "octane": ">=0.6.3 <1"
   },
   "peerDependenciesMeta": {
@@ -62,12 +66,15 @@
     },
     "@nativescript/core": {
       "optional": true
+    },
+    "@octane-xplat/macos-renderer": {
+      "optional": true
     }
   },
   "scripts": {
-    "build": "vite build && vite build --mode native && pnpm typegen && node ../../scripts/check-native-dist.mjs",
     "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.web.tsrx

@@ -1,23 +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) @{
-	<canvas
-		id={props.id}
-		className={props.className}
-		style={props.style}
-		width={typeof props.width === 'number' ? props.width : undefined}
-		height={typeof props.height === 'number' ? props.height : undefined}
-		ref={(el: HTMLCanvasElement | null) => {
+	// 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;
 			}
 
-			props.onReady?.({
+			propsRef.current.onReady?.({
 				canvas: el,
-				context: props.context ? el.getContext(props.context) : null,
+				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/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/props.ts

@@ -1,8 +1,9 @@
 export type CanvasContextKind = '2d' | 'webgl' | 'webgl2' | 'webgpu' | 'bitmaprenderer'
 
 export interface CanvasReady {
-	/** HTMLCanvasElement on web, the plugin's Canvas view on native —
-	 *  both expose `getContext()`. */
+	/** 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 —
@@ -17,8 +18,10 @@ export interface CanvasProps {
 	/** 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. Native: the plugin's `ready` event (fires when the
-	 *  GPU surface exists — earlier `getContext` calls can return null). */
+	/** 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

package/types/index.d.ts

@@ -7,7 +7,8 @@ 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 native — or null where WebGPU is unavailable. */
+ *  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

@@ -1,7 +1,8 @@
 export type CanvasContextKind = '2d' | 'webgl' | 'webgl2' | 'webgpu' | 'bitmaprenderer';
 export interface CanvasReady {
-    /** HTMLCanvasElement on web, the plugin's Canvas view on native —
-     *  both expose `getContext()`. */
+    /** 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 —
@@ -15,8 +16,10 @@ export interface CanvasProps {
     /** 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. Native: the plugin's `ready` event (fires when the
-     *  GPU surface exists — earlier `getContext` calls can return null). */
+    /** 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

package/dist/native/Canvas.tsrx.js

@@ -1,35 +0,0 @@
-import { defineUniversalComponent, registerElement, universalPlan, universalValue } from "@nativescript-community/octane";
-import { Canvas } from "@nativescript/canvas";
-//#region src/Canvas.tsrx
-var __octaneUniversalPlan0 = universalPlan("nativescript", {
-	"kind": "host",
-	"type": "nscanvas",
-	"bindings": [
-		["id", 0],
-		["className", 1],
-		["style", 2],
-		["width", 3],
-		["height", 4],
-		["onReady", 5]
-	]
-});
-registerElement("nscanvas", Canvas);
-var Canvas$1 = defineUniversalComponent("nativescript", function Canvas(props) {
-	const ready = (event) => {
-		const canvas = event.object;
-		props.onReady?.({
-			canvas,
-			context: props.context ? canvas.getContext(props.context) : null
-		});
-	};
-	return universalValue(__octaneUniversalPlan0, [
-		props.id,
-		props.className,
-		props.style,
-		props.width,
-		props.height,
-		ready
-	]);
-}, { "module": "@nativescript-community/octane" });
-//#endregion
-export { Canvas$1 as Canvas };

package/dist/native/gpu.js

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

package/dist/native/index.js

@@ -1,3 +0,0 @@
-import { Canvas } from "./Canvas.tsrx.js";
-import { getGPU } from "./gpu.js";
-export { Canvas, getGPU };

package/dist/native/octane-client-build.json

@@ -1,8 +0,0 @@
-{
-  "version": 1,
-  "buildId": "1e4d34bf-eb79-4940-8b5c-3b5fef84dd1e",
-  "mode": "production",
-  "capabilities": {
-    "independentHydration": false
-  }
-}

package/dist/web/Canvas.web.tsrx.js

@@ -1,48 +0,0 @@
-import { __s, bag7, clone, queueRefAttach, queueRefDetach, setStyle, template } from "octane";
-import { replaceRef, setClassNameIfChanged, setPlainAttributeIfChanged } from "octane/internal/client";
-//#region src/Canvas.web.tsrx
-var _t$0 = /* @__PURE__ */ template("<canvas></canvas>");
-var _rm$0 = [
-	"r",
-	"g",
-	"b"
-];
-var Canvas = /* @__PURE__ */ __s(function Canvas(props, __s, __extra) {
-	let _b = __s.slots[0];
-	if (_b === void 0) {
-		let _m6;
-		const _root = clone(_t$0);
-		queueRefAttach(__s, _m6 = (el) => {
-			if (!el) return;
-			props.onReady?.({
-				canvas: el,
-				context: props.context ? el.getContext(props.context) : null
-			});
-		}, _root);
-		(__s.cleanups ??= []).push(() => _b && queueRefDetach(_b.g, _b.b));
-		_b = bag7(__s, _root, void 0, _root, void 0, void 0, void 0, void 0, _m6);
-		__s.refFields = _rm$0;
-	} else {
-		const _r = (el) => {
-			if (!el) return;
-			props.onReady?.({
-				canvas: el,
-				context: props.context ? el.getContext(props.context) : null
-			});
-		};
-		if (_r !== _b.g) _b.g = replaceRef(__s, _b.g, _r, _b.b);
-	}
-	_b.a = setPlainAttributeIfChanged(props.id, _b.a, _b.b, "id");
-	_b.c = setClassNameIfChanged(props.className, _b.c, _b.b);
-	{
-		const _v = props.style;
-		if (_b.d !== _v) {
-			setStyle(_b.b, _v, _b.d);
-			_b.d = _v;
-		}
-	}
-	_b.e = setPlainAttributeIfChanged(typeof props.width === "number" ? props.width : void 0, _b.e, _b.b, "width");
-	_b.f = setPlainAttributeIfChanged(typeof props.height === "number" ? props.height : void 0, _b.f, _b.b, "height");
-});
-//#endregion
-export { Canvas };

package/dist/web/gpu.web.js

@@ -1,10 +0,0 @@
-//#region src/gpu.web.ts
-/** 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()`. */
-function getGPU() {
-	return globalThis.navigator?.gpu ?? null;
-}
-//#endregion
-export { getGPU };

package/dist/web/index.js

@@ -1,3 +0,0 @@
-import { Canvas } from "./Canvas.web.tsrx.js";
-import { getGPU } from "./gpu.web.js";
-export { Canvas, getGPU };

package/dist/web/octane-client-build.json

@@ -1,8 +0,0 @@
-{
-  "version": 1,
-  "buildId": "2d603450-70e6-42b6-9dd0-f2c0cd432389",
-  "mode": "production",
-  "capabilities": {
-    "independentHydration": false
-  }
-}