@octane-xplat/macos-renderer 0.13.0 → 0.15.0

package/README.md

@@ -105,6 +105,47 @@ 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.
 
+## Preserve context through portals
+
+`createPortal` can place content into an AppKit `NSView` while keeping it in
+the declaring Octane tree. The host application still owns the target view;
+the renderer inserts and removes only the portal's child views. Use a
+caller-owned view or a view from the same Octane root; targets owned by another
+Octane root are rejected.
+
+```tsx
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { createContext, createPortal, useContext, useEffect, useRef, useState } from 'octane'
+
+const AccountName = createContext('Guest')
+const AccountNameProvider: any = AccountName
+
+function AccountLabel() {
+	return <label text={'Account: ' + useContext(AccountName)} />
+}
+
+export function AccountPage() {
+	const targetRef = useRef<any>(null)
+	const [target, setTarget] = useState<any>(null)
+
+	useEffect(() => {
+		setTarget(targetRef.current)
+	}, [])
+
+	return (
+		<AccountNameProvider value="Avery">
+			<rootlayout ref={targetRef} style={{ width: 280, height: 120 }} />
+			{target ? createPortal(<AccountLabel />, target) : null}
+		</AccountNameProvider>
+	)
+}
+```
+
+The label renders `Account: Avery` inside the `rootlayout` and reads the same
+provider value as its declaring tree. Run the maintained portal fixture with
+`pnpm --filter @octane-xplat/macos-renderer test:portals` to check context,
+provider updates, and native child cleanup.
+
 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.ts) demonstrates a complete host
@@ -249,14 +290,20 @@ vertically centered content. The renderer recognizes these inputs on
 ```tsx
 /** @jsxImportSource @octane-xplat/macos-renderer */
 export function Rows() {
-	return <stack>
-		<flexboxlayout flexDirection="row" gap={12} alignItems="center" justifyContent="start">
-			<label text="Name" /><label text="Value" />
-		</flexboxlayout>
-		<flexboxlayout style={{ flexDirection: 'row', gap: 12, alignItems: 'center', justifyContent: 'start' }}>
-			<label text="Name" /><label text="Value" />
-		</flexboxlayout>
-	</stack>
+	return (
+		<stack>
+			<flexboxlayout flexDirection="row" gap={12} alignItems="center" justifyContent="start">
+				<label text="Name" />
+				<label text="Value" />
+			</flexboxlayout>
+			<flexboxlayout
+				style={{ flexDirection: 'row', gap: 12, alignItems: 'center', justifyContent: 'start' }}
+			>
+				<label text="Name" />
+				<label text="Value" />
+			</flexboxlayout>
+		</stack>
+	)
 }
 ```
 
@@ -269,10 +316,16 @@ restores `gap-2` (8 points); removing the class then restores `gap={4}`.
 ```tsx
 /** @jsxImportSource @octane-xplat/macos-renderer */
 export function ConflictingRow({ inlineGap }: { inlineGap?: number }) {
-	return <flexboxlayout gap={4} className="flex-row gap-2 items-center justify-end"
-		style={{ gap: inlineGap }}>
-		<label text="Name" /><label text="Value" />
-	</flexboxlayout>
+	return (
+		<flexboxlayout
+			gap={4}
+			className="flex-row gap-2 items-center justify-end"
+			style={{ gap: inlineGap }}
+		>
+			<label text="Name" />
+			<label text="Value" />
+		</flexboxlayout>
+	)
 }
 ```
 
@@ -287,9 +340,12 @@ The class forms are `flex-row`/`flex-col`, `gap-1/2/3/4/6`,
 ```tsx
 /** @jsxImportSource @octane-xplat/macos-renderer */
 export function AxisGap() {
-	return <flexboxlayout style={{ flexDirection: 'row', gap: 4, columnGap: 12 }}>
-		<label text="Name" /><label text="Value" />
-	</flexboxlayout>
+	return (
+		<flexboxlayout style={{ flexDirection: 'row', gap: 4, columnGap: 12 }}>
+			<label text="Name" />
+			<label text="Value" />
+		</flexboxlayout>
+	)
 }
 ```
 
@@ -303,11 +359,18 @@ placement into styles. Keep those values on the child host.
 ```tsx
 /** @jsxImportSource @octane-xplat/macos-renderer */
 export function PositionedRow() {
-	return <absolutelayout>
-		<flexboxlayout left={20} top={12} style={{ width: 240, height: 40, flexDirection: 'row', gap: 12 }}>
-			<label text="Name" /><label text="Value" />
-		</flexboxlayout>
-	</absolutelayout>
+	return (
+		<absolutelayout>
+			<flexboxlayout
+				left={20}
+				top={12}
+				style={{ width: 240, height: 40, flexDirection: 'row', gap: 12 }}
+			>
+				<label text="Name" />
+				<label text="Value" />
+			</flexboxlayout>
+		</absolutelayout>
+	)
 }
 ```
 
@@ -361,6 +424,7 @@ From this repository:
 ```sh
 pnpm --filter @octane-xplat/macos-renderer test
 pnpm --filter @octane-xplat/macos-renderer test:overflow
+pnpm --filter @octane-xplat/macos-renderer test:portals
 pnpm --filter @octane-xplat/macos-renderer test:packed
 pnpm --filter @xplat/macos test:fonts
 pnpm --filter @xplat/macos test:layout-channels
@@ -375,3 +439,14 @@ 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.
+
+## Press and swipe callbacks
+
+See [macOS gesture callbacks](../ui/changes/macos-gestures.md) for shared
+Pressable and View examples, swipe directions, and verification limits.
+The maintained nonvisual fixture checks Objective-C gesture target dispatch;
+physical OS input remains a separate manual check.
+
+```sh
+goddard-agent resource run --json '{"resources":{"native_builds":1},"purpose":"AppKit gesture verification"}' -- pnpm --filter @octane-xplat/macos-renderer test:gestures
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/macos-renderer",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Experimental AppKit renderer for Octane on macOS",
   "license": "MIT",
   "repository": {
@@ -10,6 +10,7 @@
   },
   "files": [
     "src",
+    "types",
     "LICENSE"
   ],
   "type": "module",
@@ -26,6 +27,12 @@
     "./jsx-dev-runtime": {
       "types": "./src/jsx-runtime.d.ts"
     },
+    "./types": {
+      "types": "./types/index.d.ts"
+    },
+    "./types/*": {
+      "types": "./types/*.d.ts"
+    },
     "./compat/native-core": "./src/native-core-shim.ts",
     "./compat/escape-props": "./src/native-escape-props.ts"
   },
@@ -33,13 +40,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@nativescript/macos-node-api": "0.4.4-next.2026-08-09-31292056208"
+    "@nativescript/macos-node-api": "0.4.4-next.2026-08-09-31292056208",
+    "@nativescript/objc-node-api": "1.0.0-alpha.7",
+    "@octane-xplat/platform": "0.15.0",
+    "acorn": "8.15.0",
+    "saxes": "6.0.0"
   },
   "peerDependencies": {
     "octane": ">=0.6.3 <1"
   },
   "scripts": {
     "test": "node --experimental-strip-types --test test/*.test.ts",
+    "test:gestures": "node ../../scripts/probe.mjs run test/fixtures/gestures.macos.tsrx --target macos",
+    "test:portals": "node ../../scripts/probe.mjs run test/fixtures/portal-lifecycle.macos.tsrx --target macos",
     "test:overflow": "node ../../scripts/probe.mjs run test/fixtures/text-overflow.macos.tsrx --target macos",
     "test:packed": "node --experimental-strip-types test/packed-consumer.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json"

package/src/appearance.ts

@@ -1,5 +1,7 @@
 /** App-wide effective appearance. AppKit resolves both system mode and an
  * explicit NSApplication.appearance override; colors remain app-owned. */
+
+import { NSApplication, NSObject } from '@octane-xplat/platform/macos'
 export function installAppearanceBridge(bridge: Record<string, any>): void {
 	// Preserve an installed producer across module reloads and host customization.
 	if (bridge.getColorScheme && bridge.onAppearanceChange) {

package/src/fonts.ts

@@ -1,3 +1,5 @@
+import { NSFont, NSFontDescriptor, NSFontManager } from '@octane-xplat/platform/macos'
+
 interface FontFace {
 	weight: number
 	descriptor: NSFontDescriptor

package/src/formatted-text.ts

@@ -0,0 +1,147 @@
+/** Viewless text composition. No AppKit object is allocated for a logical node. */
+interface TextNode {
+	type: string
+	props: Record<string, any>
+	text: string
+	children: TextNode[]
+}
+
+const TEXT_STYLE_KEYS = [
+	'fontFamily',
+	'fontSize',
+	'fontWeight',
+	'fontStyle',
+	'textDecoration',
+	'color',
+	'backgroundColor',
+] as const
+
+export function validateTextStyle(props: Record<string, any>, color: (value: any) => any) {
+	if (props.style != null && (typeof props.style !== 'object' || Array.isArray(props.style))) {
+		throw new Error('AppKit formatted text expects a style object')
+	}
+
+	for (const source of [props, props.style ?? {}]) {
+		if (source.fontSize != null && (!Number.isFinite(source.fontSize) || source.fontSize <= 0)) {
+			throw new Error('AppKit formatted text fontSize must be positive and finite')
+		}
+
+		if (source.fontFamily != null && typeof source.fontFamily !== 'string') {
+			throw new Error('AppKit formatted text fontFamily must be a string')
+		}
+
+		if (source.fontStyle != null && !['normal', 'italic', 'oblique'].includes(source.fontStyle)) {
+			throw new Error('AppKit formatted text fontStyle supports normal, italic and oblique')
+		}
+
+		if (
+			source.textDecoration != null &&
+			![
+				'none',
+				'underline',
+				'line-through',
+				'underline line-through',
+				'line-through underline',
+			].includes(source.textDecoration)
+		) {
+			throw new Error('AppKit formatted text has an unsupported textDecoration')
+		}
+
+		for (const key of ['color', 'backgroundColor']) {
+			if (source[key] != null) {
+				color(source[key])
+			}
+		}
+	}
+}
+
+/** Fold inherited values without mutating authored props. Removed values fall
+ * through to the ancestor; style wins over the direct property. */
+export function textRuns(
+	node: TextNode,
+	inherited: Record<string, any> = {},
+): Array<{ text: string; style: Record<string, any> }> {
+	const style = { ...inherited }
+	for (const key of TEXT_STYLE_KEYS) {
+		const value = node.props.style?.[key] ?? node.props[key]
+		if (value != null) {
+			style[key] = value
+		}
+	}
+
+	const own =
+		node.type === '#text'
+			? node.text
+			: node.type === 'span'
+				? String(node.props.text ?? '')
+						.replace('\\n', '\n')
+						.replace('\\t', '\t')
+				: ''
+
+	return [
+		...(own ? [{ text: own, style }] : []),
+		...node.children.flatMap((child) => textRuns(child, style)),
+	]
+}
+
+export function composeAttributedText(
+	children: TextNode[],
+	view: any,
+	props: Record<string, any>,
+	font: (size: number, weight: number | string, family?: string) => any,
+	color: (value: any) => any,
+	defaults: Record<string, any>,
+) {
+	const native = globalThis as any
+	const result = native.NSMutableAttributedString.alloc().initWithString('')
+	const paragraph = native.NSMutableParagraphStyle.alloc().init()
+	paragraph.alignment = view.alignment ?? 0
+	paragraph.lineBreakMode = view.cell?.lineBreakMode ?? native.NSLineBreakMode.WordWrapping
+	const lineHeight = Number(props.style?.lineHeight)
+	if (Number.isFinite(lineHeight) && lineHeight > 0) {
+		paragraph.minimumLineHeight = lineHeight
+		paragraph.maximumLineHeight = lineHeight
+	}
+
+	for (const run of children.flatMap((child) => textRuns(child, defaults))) {
+		const style = run.style
+		let face = font(style.fontSize, style.fontWeight, style.fontFamily)
+		if (style.fontStyle === 'italic' || style.fontStyle === 'oblique') {
+			face = native.NSFontManager.sharedFontManager.convertFontToHaveTrait(
+				face,
+				native.NSFontTraitMask.Italic,
+			)
+		}
+
+		const attributes: Record<string, any> = {
+			[native.NSFontAttributeName]: face,
+			[native.NSParagraphStyleAttributeName]: paragraph,
+		}
+
+		if (style.color != null) {
+			attributes[native.NSForegroundColorAttributeName] =
+				typeof style.color === 'object' ? style.color : color(style.color)
+		}
+
+		if (style.backgroundColor != null) {
+			attributes[native.NSBackgroundColorAttributeName] =
+				typeof style.backgroundColor === 'object'
+					? style.backgroundColor
+					: color(style.backgroundColor)
+		}
+
+		if (String(style.textDecoration).includes('underline')) {
+			attributes[native.NSUnderlineStyleAttributeName] = 1
+		}
+
+		if (String(style.textDecoration).includes('line-through')) {
+			attributes[native.NSStrikethroughStyleAttributeName] = 1
+		}
+
+		result.appendAttributedString(
+			native.NSAttributedString.alloc().initWithStringAttributes(run.text, attributes),
+		)
+	}
+
+	return result
+}

package/src/gestures.ts

@@ -0,0 +1,196 @@
+/** Gesture ownership stays on the renderer's original NSView, including when
+ * layout inserts a margin wrapper. No window-wide input monitor is needed. */
+
+import {
+	NSClickGestureRecognizer,
+	NSEvent,
+	NSGestureRecognizer,
+	NSGestureRecognizerDelegate,
+	NSObject,
+	NSPressGestureRecognizer,
+	NSView,
+	NativeClass,
+	interop,
+} from '@octane-xplat/platform/macos'
+
+interface GestureNode {
+	view: NSView | null
+	props: Record<string, any>
+	container: { root: { eventScope(kind: 'discrete', fn: () => void): void } | null }
+	[key: string]: any
+}
+
+const nodes = new WeakMap<object, GestureNode>()
+const owned = new WeakSet<object>()
+
+function dispatch(node: GestureNode | undefined, name: string, event?: any) {
+	if (!node || node.props.disabled || typeof node.props[name] !== 'function') {
+		return
+	}
+
+	try {
+		node.container.root!.eventScope('discrete', () => node.props[name](event))
+	} catch (error) {
+		console.error('[macos-event] ' + name + ' handler failed', error)
+	}
+}
+
+/** The JSC host's native property enumeration sees enumerable keys only.
+ * Make these renderer-owned methods visible before NativeScript registers them. */
+export function registerGestureClass(ctor: any) {
+	for (const name of Object.getOwnPropertyNames(ctor.prototype)) {
+		if (name === 'constructor') {
+			continue
+		}
+
+		const descriptor = Object.getOwnPropertyDescriptor(ctor.prototype, name)!
+		Object.defineProperty(ctor.prototype, name, { ...descriptor, enumerable: true })
+	}
+
+	NativeClass(ctor)
+}
+
+class GestureDelegate extends NSObject {
+	static ObjCProtocols = [NSGestureRecognizerDelegate]
+	static {
+		registerGestureClass(this)
+	}
+	gestureRecognizerShouldRecognizeSimultaneouslyWithGestureRecognizer(
+		a: NSGestureRecognizer,
+		b: NSGestureRecognizer,
+	) {
+		// Do not change arbitration with child controls or hosted engines.
+		return a.view === b.view && owned.has(a) && owned.has(b)
+	}
+}
+
+const delegate = GestureDelegate.new()
+
+export function configureGesture(recognizer: NSGestureRecognizer) {
+	owned.add(recognizer)
+	recognizer.delegate = delegate
+	recognizer.delaysPrimaryMouseButtonEvents = false
+	return recognizer
+}
+
+/** AppKit has no down/up recognizer. This passive mouse observer never claims
+ * the sequence from click/pan, and balances down with up or reset/cancel. */
+class TouchGestureRecognizer extends NSGestureRecognizer {
+	active = false
+	static {
+		registerGestureClass(this)
+	}
+	mouseDown(_event: NSEvent) {
+		this.active = true
+		dispatch(nodes.get(this.view), 'onTouch', { action: 'down', view: this.view })
+	}
+	mouseDragged(_event: NSEvent) {
+		if (!this.active) {
+			return
+		}
+
+		dispatch(nodes.get(this.view), 'onTouch', { action: 'move', view: this.view })
+	}
+	mouseUp(_event: NSEvent) {
+		if (!this.active) {
+			return
+		}
+
+		this.active = false
+		dispatch(nodes.get(this.view), 'onTouch', { action: 'up', view: this.view })
+	}
+	reset() {
+		if (this.active) {
+			this.active = false
+			dispatch(nodes.get(this.view), 'onTouch', { action: 'cancel', view: this.view })
+		}
+
+		super.reset()
+	}
+}
+
+class GestureTarget extends NSObject {
+	static ObjCExposedMethods = {
+		'longPressed:': { params: [NSObject], returns: interop.types.void },
+		'doublePressed:': { params: [NSObject], returns: interop.types.void },
+	}
+	static {
+		registerGestureClass(this)
+	}
+	['longPressed:'](sender: NSGestureRecognizer) {
+		this.longPressed(sender)
+	}
+	['doublePressed:'](sender: NSGestureRecognizer) {
+		this.doublePressed(sender)
+	}
+	longPressed(sender: NSGestureRecognizer) {
+		if (Number(sender.state) === 3) {
+			dispatch(nodes.get(sender.view), 'onLongPress')
+		}
+	}
+	doublePressed(sender: NSGestureRecognizer) {
+		if (Number(sender.state) === 3) {
+			dispatch(nodes.get(sender.view), 'onDoubleTap')
+		}
+	}
+}
+
+const target = GestureTarget.new()
+
+export function setPressGesture(node: GestureNode, name: string) {
+	nodes.set(node.view!, node)
+	const key = name + 'GestureRecognizer'
+	let recognizer = node[key] as NSGestureRecognizer | undefined
+	if (!recognizer && typeof node.props[name] === 'function') {
+		if (name === 'onTouch') {
+			recognizer = TouchGestureRecognizer.new() as NSGestureRecognizer
+		} else if (name === 'onLongPress') {
+			const press = NSPressGestureRecognizer.alloc().initWithTargetAction(target, 'longPressed:')
+			press.minimumPressDuration = 0.5
+			recognizer = press
+		} else {
+			const click = NSClickGestureRecognizer.alloc().initWithTargetAction(target, 'doublePressed:')
+			click.numberOfClicksRequired = 2
+			recognizer = click
+		}
+
+		node[key] = configureGesture(recognizer)
+		node.view!.addGestureRecognizer(recognizer)
+	}
+
+	if (recognizer) {
+		recognizer.enabled = !node.props.disabled && typeof node.props[name] === 'function'
+	}
+}
+
+export function disposePressGestures(node: GestureNode) {
+	if (!node.view) {
+		return
+	}
+
+	// Forget callbacks before AppKit resets a recognizer during teardown.
+	nodes.delete(node.view)
+	for (const name of ['onTouch', 'onLongPress', 'onDoubleTap']) {
+		const recognizer = node[name + 'GestureRecognizer']
+		if (recognizer) {
+			recognizer.enabled = false
+			node.view.removeGestureRecognizer(recognizer)
+		}
+	}
+}
+
+/** NativeScript SwipeDirection values. Only completed drags of at least 30
+ * layout points count; cancelled/failed pans never produce a swipe. */
+export function swipeDirection(event: { state: number; deltaX: number; deltaY: number }) {
+	if (event.state !== 3 || Math.max(Math.abs(event.deltaX), Math.abs(event.deltaY)) < 30) {
+		return null
+	}
+
+	return Math.abs(event.deltaX) >= Math.abs(event.deltaY)
+		? event.deltaX > 0
+			? 1
+			: 2
+		: event.deltaY < 0
+			? 4
+			: 8
+}

package/src/host-globals.d.ts

@@ -0,0 +1,55 @@
+// Ambient host globals injected by @nativescript/macos-node-api and the
+// embedding Node process — runtime loader, the renderer's __xplatAppKit bridge
+// channel, and the Node-ish globals the macOS host provides.
+// Runtime framework loader injected by the bridge host.
+// `declare global` member types resolve ambiently — module imports don't bind
+// inside the global block — so AppKit names use inline import() types.
+declare global {
+	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.
+	var __xplatAppKit: {
+		observeHover?: (view: import('@octane-xplat/platform/macos').NSView, handlers: any) => void
+		showAnchoredPopup?: (options: any) => void
+		showLayer?: (options: any) => any
+		attachContextMenu?: (
+			view: import('@octane-xplat/platform/macos').NSView,
+			options: any,
+			onSelect: any,
+		) => void
+		attachDatePicker?: (
+			view: import('@octane-xplat/platform/macos').NSView,
+			options: any,
+			onChange: any,
+		) => void
+		presentSheet?: (view: import('@octane-xplat/platform/macos').NSView, options: any) => any
+		presentSurface?: (options: any) => any
+		setSurfaceAppearance?: (
+			view: import('@octane-xplat/platform/macos').NSView,
+			dark: boolean,
+		) => void
+		[key: string]: any
+	}
+
+	var __xplatVlistOffsets: { [key: string]: number } | undefined
+
+	// Node host globals.
+	const performance: { now(): number }
+	function setTimeout(callback: () => void, ms?: number): unknown
+	function clearTimeout(timer: unknown): void
+	function queueMicrotask(callback: () => void): void
+	const console: {
+		log(...args: any[]): void
+		warn(...args: any[]): void
+		error(...args: any[]): void
+		[key: string]: any
+	}
+
+	// The macOS host embeds Node — process.env reads and cwd() are real.
+	// Other programs may declare a narrower process ambient; duplicate ambient
+	// consts merge loosely under skipLibCheck, so keep both members here.
+	const process: { env: { [key: string]: string | undefined }; cwd(): string }
+}
+
+export {}