@octane-xplat/macos-renderer 0.0.1 → 0.10.0

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

@@ -1,4 +1,233 @@
-# @octane-xplat/macos-renderer
+# Render Octane components in AppKit
 
-This is a placeholder stub published to reserve the package name ahead of the
-first automated release. It has no supported API.
+`@octane-xplat/macos-renderer` mounts Octane components into an existing
+`NSView`. It is the experimental macOS AppKit renderer, using the
+`@nativescript/macos-node-api` runtime and the CLI's JavaScriptCore host.
+The supported packaging target is Apple Silicon with macOS 13.5 or later.
+
+Your application owns startup, windows, menus, host services, and custom font
+assets. The renderer owns views, layout, events, accessibility, and its hosted
+popups and sheets. It does not load web stylesheets or implement every
+NativeScript widget. See the [macOS harness](../../apps/macos/README.md) for
+the current component and service limits. The image-crop integration test compiles and mounts the public UI barrel.
+The full application harness has not been reverified by that test. A raw AppKit button
+`performClick` check also exposes an existing action-selector mismatch. Native
+click delivery needs separate repair and verification; the maintained consumer
+checks direct handler dispatch.
+
+## Configure an app
+
+Declare the renderer, `octane`, and `@nativescript/macos-node-api` as application
+dependencies. The CLI also requires the runtime to be directly declared, even
+though the renderer depends on it. Use one copy of Octane per application.
+Declare `@octane-xplat/cli`, `@octanejs/vite-plugin`, and `vite` as development
+dependencies; the preset resolves these from your app, not from the CLI.
+The maintained consumer uses Octane 0.6.3, the Vite plugin 0.1.61, Vite 8.3.0,
+and the runtime `0.4.4-next.2026-08-09-31292056208`.
+
+Apply the framework's [patch setup](../cli/README.md)
+before building. For TSX checking, install TypeScript; for TSRX source, also
+install `@tsrx/typescript-plugin` and use `tsrx-tsc`.
+
+Use this production Vite config:
+
+```js
+import { defineConfig } from 'vite'
+import { xplatMacOS } from '@octane-xplat/cli/macos/vite'
+
+export default defineConfig(({ mode }) => xplatMacOS(mode))
+```
+
+The async preset bundles `src/main.mjs` into `dist/package-build/main.cjs`,
+selects macOS platform files, registers the universal renderer, aliases
+NativeScript compatibility imports, and externalizes only the native runtime
+and `node:` host imports. Unsupported host imports still fail CLI packaging.
+No repository paths or harness fonts are needed.
+
+```js
+import { xplatMacOS } from '@octane-xplat/cli/macos/vite'
+
+export default await xplatMacOS('production', { entry: 'src/main.mjs' })
+```
+
+Set these TypeScript options:
+
+```json
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "Bundler",
+		"jsx": "react-jsx",
+		"jsxImportSource": "@octane-xplat/macos-renderer",
+		"customConditions": ["macos"],
+		"moduleSuffixes": [".macos", ""],
+		"lib": ["ESNext"],
+		"strict": true,
+		"skipLibCheck": true,
+		"noEmit": true
+	},
+	"include": ["src/**/*"]
+}
+```
+
+JSX runtime subpaths contain compiler typing declarations; use the Octane Vite
+compiler to produce runnable code. The preset compiles reachable TSX/TSRX
+source by default. `rules` can override that selection.
+
+```js
+import { xplatMacOS } from '@octane-xplat/cli/macos/vite'
+
+export default await xplatMacOS('production', {
+	rules: [{ include: '**/*.tsx', renderer: 'macos' }],
+})
+```
+
+## Mount and dispose a root
+
+In your existing host bootstrap, pass its content view to the renderer:
+
+```js
+import { createMacOSRoot } from '@octane-xplat/macos-renderer'
+import App from './App.macos.tsx'
+
+const root = createMacOSRoot(contentView)
+root.render(App, {})
+
+// Call when the owning window or application closes.
+root.unmount()
+```
+
+`contentView` is the `NSView` supplied by your window host. Keep one root for
+that view and call `unmount()` before disposing the host. Root creation does
+not create a window or start the application run loop. The package also
+re-exports Octane's universal native runtime for compiler and hook imports.
+
+Use [the packaging guide](../../docs/start/toolchain.md#experimental-appkit-target)
+for `xplat.targets.macos` metadata, signing, and CLI commands. The
+[independent fixture](test/fixtures/main.mjs) demonstrates a complete host
+entry, including startup and shutdown, without importing the harness.
+
+## Render local images and overlays
+
+Image sources can be base64 data URIs, local file paths, or `file://` URLs.
+An empty or unsupported source clears the old image. Remote URLs require a
+separate download; image loading does not perform synchronous network work.
+For centered contain-fit, pass `style={{ objectFit: 'contain' }}` to `Image`.
+This scales smaller images up while preserving their aspect ratio.
+
+`style={{ pointerEvents: 'none' }}` makes `Image` and `View` (the flexbox host)
+pass hit-testing through to siblings below them. Use it for decorative crop
+source/guide layers; keep gesture controls interactive. The AppKit crop test
+checks those native hit-test boundaries separately from pan handler dispatch.
+
+## Choose fonts
+
+Roots default to Apple's system font. Sizes and CSS numeric or named weights
+map to weighted AppKit fonts. `system-ui`, `-apple-system`, and `sans-serif`
+select the system font; unavailable families fall through the family stack,
+then fall back to the system font.
+
+```tsx
+// Text.macos.tsx — the AppKit renderer is configured above.
+export function Title() {
+	return <label text="Trip notes" style={{ fontFamily: 'system-ui', fontWeight: 'bold' }} />
+}
+```
+
+For an installed family, set `style.fontFamily` on text or choose a root
+default with `createMacOSRoot(contentView, { fontFamily: 'Helvetica Neue' })`.
+Renderer-hosted popups and sheets inherit that root default.
+
+```js
+// contentView is your existing window's NSView, as in the host example above.
+import { createMacOSRoot } from '@octane-xplat/macos-renderer'
+
+const root = createMacOSRoot(contentView, { fontFamily: 'Helvetica Neue' })
+```
+
+For bundled fonts, the application loads its assets and license and creates
+native descriptors. Register those descriptors before mounting:
+
+```js
+import { createMacOSRoot, registerFontFamily } from '@octane-xplat/macos-renderer'
+
+// regularFace and boldFace are NSFontDescriptors created from your font asset.
+registerFontFamily('Acme Sans', [
+	{ weight: 400, descriptor: regularFace },
+	{ weight: 700, descriptor: boldFace },
+])
+const root = createMacOSRoot(contentView, { fontFamily: 'Acme Sans' })
+```
+
+Registration does not change the renderer default. Registered weights resolve
+to the first face at or above the requested weight, or the heaviest face.
+Invalid names, empty face lists, and missing descriptors or invalid weights are
+rejected. The renderer does not read assets, register Geist automatically, or
+write a font cache. The [harness font setup](../../apps/macos/src/fonts.mjs)
+demonstrates app-owned descriptors and packaged font bytes.
+
+```js
+// regularFace is an NSFontDescriptor created by the app from its loaded font.
+registerFontFamily('Acme Sans', [{ weight: 400, descriptor: regularFace }])
+```
+
+## Development bundles
+
+Call `xplatMacOS(mode, { packaged: false, hmr: true, entry: 'src/App.macos.tsx' })`
+for the component bundle. It retains renderer and Octane imports so the
+CLI-managed shell can share their live instances across edits. Build the
+shell with `packaged: true`, and populate `__xplatDevModules` with the renderer
+and Octane modules. The [independent development shell](test/fixtures/dev-shell.mjs)
+shows the module mapping and retained-root HMR lifecycle.
+
+```js
+// vite.component.config.mjs
+import { xplatMacOS } from '@octane-xplat/cli/macos/vite'
+
+export default await xplatMacOS('development', {
+	packaged: false,
+	hmr: true,
+	entry: 'src/App.macos.tsx',
+})
+```
+
+Other preset options are `root` (defaults to cwd), `entry`, `outDir`, and
+`rules`. Packaged output defaults to CommonJS; component output defaults to
+ES modules. Component builds preserve the output directory so they do not
+delete a shell sharing it; shell configurations should also preserve that
+directory when used for development. Applications may override the component format to CommonJS for
+the CLI watcher, as the maintained fixture does.
+
+```js
+import { xplatMacOS } from '@octane-xplat/cli/macos/vite'
+
+const config = await xplatMacOS('development', {
+	root: process.cwd(),
+	entry: 'src/App.macos.tsx',
+	outDir: 'dist/dev',
+	packaged: false,
+})
+config.build = {
+	...config.build,
+	lib: { entry: 'src/App.macos.tsx', formats: ['cjs'], fileName: 'app' },
+}
+export default config
+```
+
+## Verify the package
+
+From this repository:
+
+```sh
+pnpm --filter @octane-xplat/macos-renderer test
+pnpm --filter @octane-xplat/macos-renderer test:packed
+pnpm --filter @xplat/macos test:fonts
+```
+
+The packed check uses the renderer and CLI tarballs in a temporary app outside
+the checkout. It checks declarations and production compilation on every
+host; on Apple Silicon macOS it also packages and launches the app and verifies
+retained-root HMR. Programmatic action dispatch establishes handler behavior,
+not OS input or hit-testing. Publication requires the repository's normal
+[npm bootstrap and trusted-publisher setup](../../.agents/docs/releases.md).

package/package.json

@@ -1,11 +1,46 @@
 {
   "name": "@octane-xplat/macos-renderer",
-  "version": "0.0.1",
-  "description": "Placeholder stub for @octane-xplat/macos-renderer — no supported API yet.",
+  "version": "0.10.0",
+  "description": "Experimental AppKit renderer for Octane on macOS",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/octane-xplat/octane-xplat",
     "directory": "packages/macos-renderer"
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./intrinsics": "./src/intrinsics.d.ts",
+    "./jsx-runtime": {
+      "types": "./src/jsx-runtime.d.ts"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./src/jsx-runtime.d.ts"
+    },
+    "./compat/native-core": "./src/native-core-shim.ts",
+    "./compat/escape-props": "./src/native-escape-props.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nativescript/macos-node-api": "0.4.4-next.2026-08-09-31292056208"
+  },
+  "peerDependencies": {
+    "octane": ">=0.6.3 <1"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:packed": "node test/packed-consumer.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   }
-}
+}

package/src/appkit.d.ts

@@ -0,0 +1,199 @@
+// Ambient host globals injected by @nativescript/macos-node-api and the
+// embedding Node process. The prerelease ships no generated AppKit metadata
+// types, so bridge classes expose members loosely while the type names stay
+// usable in our own signatures.
+
+type NSClass<T> = {
+	new (...args: any[]): T
+	alloc(): T
+	[key: string]: any
+}
+
+// Objective-C classes. Instances expose bridged members as `any`; the type
+// name is real so parameters and node structs can reference them.
+declare class NSObject {
+	[key: string]: any
+	static alloc(): any
+	static new(): any
+	static extend(methods: object, options?: object): any
+}
+
+interface NSAttributedString extends NSObject {}
+declare const NSAttributedString: NSClass<NSAttributedString>
+
+interface NSBundle extends NSObject {}
+declare const NSBundle: NSClass<NSBundle>
+
+interface NSError extends NSObject {}
+declare const NSError: NSClass<NSError>
+
+interface NSURLRequest extends NSObject {}
+declare const NSURLRequest: NSClass<NSURLRequest>
+
+// WebKit is dlopen'd at runtime by the webview leaf.
+interface WKWebView extends NSView {}
+declare const WKWebView: NSClass<WKWebView>
+
+interface WKWebViewConfiguration extends NSObject {}
+declare const WKWebViewConfiguration: NSClass<WKWebViewConfiguration>
+
+interface NSButton extends NSView {}
+declare const NSButton: NSClass<NSButton>
+
+interface NSClickGestureRecognizer extends NSObject {}
+declare const NSClickGestureRecognizer: NSClass<NSClickGestureRecognizer>
+
+interface NSColor extends NSObject {}
+declare const NSColor: NSClass<NSColor>
+
+interface NSColorSpace extends NSObject {}
+declare const NSColorSpace: NSClass<NSColorSpace>
+
+interface NSData extends NSObject {}
+declare const NSData: NSClass<NSData>
+
+interface NSDate extends NSObject {}
+declare const NSDate: NSClass<NSDate>
+
+interface NSDatePicker extends NSView {}
+declare const NSDatePicker: NSClass<NSDatePicker>
+
+interface NSEdgeInsets extends NSObject {}
+declare const NSEdgeInsets: NSClass<NSEdgeInsets>
+
+interface NSEvent extends NSObject {}
+declare const NSEvent: NSClass<NSEvent>
+
+interface NSFont extends NSObject {}
+declare const NSFont: NSClass<NSFont>
+
+interface NSFontDescriptor extends NSObject {}
+declare const NSFontDescriptor: NSClass<NSFontDescriptor>
+
+interface NSFontManager extends NSObject {}
+declare const NSFontManager: NSClass<NSFontManager>
+
+interface NSImage extends NSObject {}
+declare const NSImage: NSClass<NSImage>
+
+interface NSImageView extends NSView {}
+declare const NSImageView: NSClass<NSImageView>
+
+interface NSMenu extends NSObject {}
+declare const NSMenu: NSClass<NSMenu>
+
+interface NSMenuItem extends NSObject {}
+declare const NSMenuItem: NSClass<NSMenuItem>
+
+interface NSMutableParagraphStyle extends NSObject {}
+declare const NSMutableParagraphStyle: NSClass<NSMutableParagraphStyle>
+
+interface NSNotification extends NSObject {}
+declare const NSNotification: NSClass<NSNotification>
+
+interface NSNotificationCenter extends NSObject {}
+declare const NSNotificationCenter: NSClass<NSNotificationCenter>
+
+interface NSNumber extends NSObject {}
+declare const NSNumber: NSClass<NSNumber>
+
+interface NSPanGestureRecognizer extends NSObject {}
+declare const NSPanGestureRecognizer: NSClass<NSPanGestureRecognizer>
+
+interface NSPopover extends NSObject {}
+declare const NSPopover: NSClass<NSPopover>
+
+interface NSScrollView extends NSView {}
+declare const NSScrollView: NSClass<NSScrollView>
+
+interface NSSlider extends NSView {}
+declare const NSSlider: NSClass<NSSlider>
+
+interface NSStackView extends NSView {}
+declare const NSStackView: NSClass<NSStackView>
+
+interface NSTextField extends NSView {}
+declare const NSTextField: NSClass<NSTextField>
+
+interface NSTextView extends NSView {}
+declare const NSTextView: NSClass<NSTextView>
+
+interface NSTrackingArea extends NSObject {}
+declare const NSTrackingArea: NSClass<NSTrackingArea>
+
+interface NSURL extends NSObject {}
+declare const NSURL: NSClass<NSURL>
+
+interface NSView extends NSObject {}
+declare const NSView: NSClass<NSView>
+
+interface NSViewController extends NSObject {}
+declare const NSViewController: NSClass<NSViewController>
+
+interface NSWindow extends NSObject {}
+declare const NSWindow: NSClass<NSWindow>
+
+// Enum containers. Members resolve to `number`, so bitwise masks compose.
+declare const NSBackingStoreType: { [key: string]: number }
+declare const NSBezelStyle: { [key: string]: number }
+declare const NSBorderType: { [key: string]: number }
+declare const NSButtonType: { [key: string]: number }
+declare const NSDatePickerElementFlags: { [key: string]: number }
+declare const NSDatePickerStyle: { [key: string]: number }
+declare const NSLayoutAttribute: { [key: string]: number }
+declare const NSPopoverBehavior: { [key: string]: number }
+declare const NSRectEdge: { [key: string]: number }
+declare const NSStackViewDistribution: { [key: string]: number }
+declare const NSStackViewGravity: { [key: string]: number }
+declare const NSTextAlignment: { [key: string]: number }
+declare const NSTrackingAreaOptions: { [key: string]: number }
+declare const NSUserInterfaceLayoutOrientation: { [key: string]: number }
+declare const NSWindowStyleMask: { [key: string]: number }
+
+// Standalone constants.
+declare const NSImageScaleProportionallyDown: number
+declare const NSImageScaleProportionallyUpOrDown: number
+
+// NSString notification names and attributed-string keys.
+declare const NSPopoverDidCloseNotification: string
+declare const NSViewBoundsDidChangeNotification: string
+declare const NSViewFrameDidChangeNotification: string
+declare const NSFontAttributeName: string
+declare const NSForegroundColorAttributeName: string
+declare const NSParagraphStyleAttributeName: string
+declare const NSURLErrorFailingURLErrorKey: string
+
+// Protocol objects (opaque bridge references used in ObjCProtocols arrays).
+declare const NSTextViewDelegate: any
+declare const NSWindowDelegate: any
+declare const WKNavigationDelegate: any
+
+// Runtime framework loader injected by the bridge host.
+declare function dlopen(path: string, flags: number): unknown
+
+// Cross-package bridge published by this renderer for AppKit-specific leaves
+// (hover, popups, menus, sheets) and the VirtualList offset channel.
+declare var __xplatAppKit: {
+	observeHover?: (view: NSView, handlers: any) => void
+	showAnchoredPopup?: (options: any) => void
+	attachContextMenu?: (view: NSView, options: any, onSelect: any) => void
+	attachDatePicker?: (view: NSView, options: any, onChange: any) => void
+	presentSheet?: (view: NSView, options: any) => void
+	[key: string]: any
+}
+
+declare var __xplatVlistOffsets: { [key: string]: number } | undefined
+
+// Node host globals.
+declare const performance: { now(): number }
+declare function setTimeout(callback: () => void, ms?: number): unknown
+declare function clearTimeout(timer: unknown): void
+declare function queueMicrotask(callback: () => void): void
+declare const console: {
+	log(...args: any[]): void
+	warn(...args: any[]): void
+	error(...args: any[]): void
+	[key: string]: any
+}
+
+declare const process: { env: { [key: string]: string | undefined } }

package/src/fonts.ts

@@ -0,0 +1,100 @@
+interface FontFace {
+	weight: number
+	descriptor: NSFontDescriptor
+}
+
+const families = new Map<string, FontFace[]>()
+const weights = [
+	[100, -0.8, 1],
+	[200, -0.6, 2],
+	[300, -0.4, 3],
+	[400, 0, 5],
+	[500, 0.23, 6],
+	[600, 0.3, 8],
+	[700, 0.4, 9],
+	[800, 0.56, 10],
+	[900, 0.62, 12],
+]
+
+const aliases = new Map([
+	['thin', 100],
+	['extralight', 200],
+	['light', 300],
+	['normal', 400],
+	['regular', 400],
+	['medium', 500],
+	['semibold', 600],
+	['bold', 700],
+	['extrabold', 800],
+	['black', 900],
+])
+
+const systemFamilies = new Set(['system-ui', '-apple-system', 'sans-serif'])
+
+/** Associate an app-owned family with native descriptors, without loading assets. */
+export function registerFontFamily(family: string, faces: readonly FontFace[]) {
+	if (!family?.trim() || !faces?.length) {
+		throw new Error('A font family needs a name and at least one face')
+	}
+
+	const sorted = faces
+		.map(({ weight, descriptor }) => {
+			if (!Number.isFinite(weight) || !descriptor) {
+				throw new Error('A font face needs a finite weight and a native descriptor')
+			}
+
+			return { weight, descriptor }
+		})
+		.sort((left, right) => left.weight - right.weight)
+
+	const name = family.trim().toLowerCase()
+	if (systemFamilies.has(name)) {
+		throw new Error('System font family names cannot be registered')
+	}
+
+	families.set(name, sorted)
+}
+
+/** Resolve an explicit family stack, falling back to the weighted system font. */
+export function resolveFont(size: number, weight: number | string = 400, family?: string): NSFont {
+	const parsed = aliases.get(String(weight).toLowerCase()) ?? Number(weight)
+	const numeric = Number.isFinite(parsed) ? Math.min(900, Math.max(100, parsed)) : 400
+	const [, nativeWeight, managerWeight] = weights.find(([limit]) => numeric <= limit)!
+	const systemFont = () => {
+		const font = NSFont.systemFontOfSizeWeight(Number(size), nativeWeight)
+		if (!font) {
+			throw new Error('Failed to create the AppKit system font face')
+		}
+
+		return font
+	}
+
+	for (const name of String(family ?? '').split(',')) {
+		const trimmed = name.trim().replace(/^['"]|['"]$/g, '')
+		if (!trimmed) {
+			continue
+		}
+
+		if (systemFamilies.has(trimmed.toLowerCase())) {
+			return systemFont()
+		}
+
+		const faces = families.get(trimmed.toLowerCase())
+		if (faces) {
+			const face = faces.find((face) => numeric <= face.weight) ?? faces.at(-1)!
+			const font = NSFont.fontWithDescriptorSize(face.descriptor, Number(size))
+			if (font) {
+				return font
+			}
+		} else {
+			const manager = NSFontManager.sharedFontManager
+			const font = manager.fontWithFamilyTraitsWeightSize(trimmed, 0, managerWeight, Number(size))
+
+			if (font) {
+				return font
+			}
+		}
+	}
+
+	return systemFont()
+}

package/src/image.ts

@@ -0,0 +1,23 @@
+/** Local and embedded sources avoid synchronous network work on AppKit's main thread. */
+export function loadImage(source: unknown): NSImage | null {
+	const src = String(source ?? '')
+	const match = /^data:[^,]*;base64,(.+)$/s.exec(src)
+	if (match) {
+		const data = NSData.alloc().initWithBase64EncodedStringOptions(match[1], 0)
+		return data ? NSImage.alloc().initWithData(data) : null
+	}
+
+	if (src.startsWith('file://')) {
+		return NSImage.alloc().initWithContentsOfURL(NSURL.URLWithString(src))
+	}
+
+	if (src && !/^[a-z][a-z\d+.-]*:/i.test(src)) {
+		return NSImage.alloc().initWithContentsOfFile(src)
+	}
+
+	if (src) {
+		console.warn('[macos-image] Unsupported source; use a base64 data URI or local file')
+	}
+
+	return null
+}

package/src/index.d.ts

@@ -0,0 +1,18 @@
+import '@nativescript/macos-node-api'
+
+export * from 'octane/universal/native'
+export interface MacOSRootOptions {
+	/** Default font family for this root and its renderer-hosted overlays. */
+	fontFamily?: string
+}
+
+/** Map an application-registered family to its weighted native faces. */
+export declare function registerFontFamily(
+	family: string,
+	faces: readonly { weight: number; descriptor: NSFontDescriptor }[],
+): void
+
+export declare function createMacOSRoot(
+	hostView: NSView,
+	options?: MacOSRootOptions,
+): import('octane/universal/native').UniversalRoot