create-octane-xplat 0.11.1 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-octane-xplat",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Scaffold a minimal @octane-xplat/ui app — one Octane codebase for web + iOS + Android",
   "keywords": [
     "create",

package/scaffold.mjs

@@ -34,7 +34,7 @@ export const targets = {
 		label: 'iOS (NativeScript)',
 		requires: ['native-shared'],
 		files: ['App_Resources/iOS'],
-		scripts: ['dev:ios', 'build:ios'],
+		scripts: ['dev:ios', 'test:ios', 'build:ios'],
 		devDeps: ['@nativescript/ios'],
 		note: 'needs macOS + Xcode — `pnpm xplat doctor` checks the toolchain',
 	},
@@ -42,7 +42,7 @@ export const targets = {
 		label: 'Android (NativeScript)',
 		requires: ['native-shared'],
 		files: ['App_Resources/Android'],
-		scripts: ['dev:android', 'build:android'],
+		scripts: ['dev:android', 'test:android', 'build:android'],
 		devDeps: ['@nativescript/android'],
 		note: 'needs Android SDK + a compatible JDK — `pnpm xplat doctor` checks the toolchain',
 	},
@@ -67,6 +67,12 @@ export const targets = {
 			'tsconfig.native.json',
 			'references.d.ts',
 			'src/main.ts',
+			// On-device Vitest lane — `ns test` builds src/test.ts under
+			// --env.unitTesting and runs every src/**/*.spec file on a
+			// simulator/emulator through the upstream runner.
+			'src/test.ts',
+			'src/app.spec.tsrx',
+			'vitest.config.mts',
 		],
 		deps: [
 			'@nativescript-community/gesturehandler',
@@ -80,8 +86,10 @@ export const targets = {
 		devDeps: [
 			'@nativescript-community/vite-octane',
 			'@nativescript/types',
+			'@nativescript/unit-test-runner',
 			'@nativescript/vite',
 			'nativescript',
+			'vitest',
 		],
 		typecheck: 'tsrx-tsc --noEmit -p tsconfig.native.json',
 	},

package/template/AGENTS.md

@@ -7,3 +7,32 @@ Octane Xplat app — one TypeScript codebase for web + iOS + Android (Octane
 Before writing code, read `.agents/skills/xplat/SKILL.md` (or invoke the
 `xplat` skill). Its invariants are enforced by `pnpm lint` — violations
 usually still compile but silently break on one platform.
+
+## Stable automation targets
+
+```tsx
+import { Button } from '@octane-xplat/ui'
+
+export function AddItem() {
+	return <Button testID="packing.add-item" label="Add item" accessibilityLabel="Add item" />
+}
+```
+
+Assign optional semantic `testID` names to meaningful controls and asserted
+state as you build: `packing.add-item`, `profile.name`,
+`packing.item.${item.key}.open`. Keep names unique among mounted targets,
+stable across localization, and based on durable repeated-item keys rather
+than array positions. Preserve `id` values, useful accessibility labels and
+roles. Do not put IDs on every decorative child or expose personal data.
+Inputs target their editable host; overlays target mounted content. Verify
+forwarding when composing another component; inherited types alone do not
+promise platform support. See [qualified hosts and mappings](https://octane-xplat.goddardai.org/verify/test-identifiers).
+
+Argent is optional AI-agent device/browser control through MCP, with no app
+runtime dependency. Use [official setup](https://docs.swmansion.com/argent/docs/fundamentals/installation/)
+and the [qualified local recipe](https://octane-xplat.goddardai.org/verify/argent)
+(version 0.27.0). Prefer stable IDs for reliable targeting while keeping
+spoken accessibility semantics. Discovery and replay have different native
+prerequisites. Chromium prefers DOM `id` over `data-testid` when both exist.
+The recipe states the actual iOS/Android/Chromium scope and limits; do not
+infer AppKit, physical-device, or arbitrary typing support.

package/template/App_Resources/iOS/Info.plist

@@ -48,5 +48,13 @@
 		<string>UIInterfaceOrientationLandscapeLeft</string>
 		<string>UIInterfaceOrientationLandscapeRight</string>
 	</array>
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<!-- Loopback WebSocket for `ns test` (@nativescript/unit-test-runner):
+		     the on-device coordinator reaches the host Vitest session at
+		     ws://127.0.0.1:<port>. Scoped to local networking only. -->
+		<key>NSAllowsLocalNetworking</key>
+		<true/>
+	</dict>
 </dict>
 </plist>

package/template/package.json

@@ -8,6 +8,8 @@
 		"dev": "vite",
 		"dev:ios": "ns run ios",
 		"dev:android": "ns run android",
+		"test:ios": "ns test ios",
+		"test:android": "ns test android",
 		"build": "vite build",
 		"build:ios": "ns build ios",
 		"build:android": "ns build android",
@@ -19,28 +21,31 @@
 		"@nativescript-community/gesturehandler": "2.0.45",
 		"@nativescript-community/octane": "0.2.4",
 		"@nativescript-community/ui-drawer": "0.1.32",
-		"@nativescript/core": "9.1.2",
-		"@octane-xplat/effects": "^0.11.1",
-		"@octane-xplat/image": "^0.11.1",
-		"@octane-xplat/platform": "^0.11.1",
-		"@octane-xplat/ui": "^0.11.1",
+		"@nativescript/core": "9.1.3",
+		"@octane-xplat/effects": "^0.12.0",
+		"@octane-xplat/image": "^0.12.0",
+		"@octane-xplat/platform": "^0.12.0",
+		"@octane-xplat/ui": "^0.12.0",
 		"@valor/nativescript-websockets": "2.0.3",
-		"octane": "0.6.3"
+		"octane": "0.10.2"
 	},
 	"devDependencies": {
 		"@nativescript-community/vite-octane": "0.2.1",
 		"@nativescript/android": "9.1.1",
 		"@nativescript/ios": "9.1.0",
 		"@nativescript/types": "9.1.4",
+		"@nativescript/unit-test-runner": "5.0.0",
 		"@nativescript/vite": "8.0.17",
-		"@octane-xplat/cli": "^0.11.1",
-		"@octane-xplat/lint": "^0.11.1",
+		"@octane-xplat/cli": "^0.12.0",
+		"@octane-xplat/lint": "^0.12.0",
 		"@octanejs/vite-plugin": "0.1.61",
+		"@tsrx/oxc": "0.16.0",
 		"@tsrx/typescript-plugin": "0.4.11",
 		"nativescript": "9.1.1",
 		"oxlint": "^1.74.0",
 		"typescript": "5.9.3",
-		"vite": "8.3.0"
+		"vite": "8.3.0",
+		"vitest": "4.1.11"
 	},
 	"packageManager": "pnpm@11.24.0"
 }

package/template/pnpm-workspace.yaml

@@ -21,35 +21,24 @@ allowUnusedPatches: true
 # applied via pnpm patchedDependencies. Managed upstream by @octane-xplat/cli (`xplat
 # patches apply` refreshes, `xplat patches check` verifies); do not edit by hand.
 patchedDependencies:
-  # Published octane 0.6.3 lacks live signal reads under universal renderers. Adds signal
-  # ownership, read tracking, and local signal hooks; JSX prop lowering and __methodDep
-  # already ship upstream. Routes uncaught universal event-handler errors to onUncaughtError
-  # when configured. Pins instance signal/query declarations to their declaring owner so
-  # child reads and event handlers share one request. Makes universal useImperativeHandle
-  # honor optional refs, ref replacement, nested ref arrays, and callback cleanup. Also
-  # allows async and generator helpers that are not components in universal compiler
-  # modules, while preserving errors when those functions are used as components
-  # (octanejs/octane#1469). Adds renderer-owned Children.toArray/map for transparent
-  # deferred JSX groups, plan ranges/slots and arrays, preserving keyed wrapper identity
-  # while leaving scoped owners intact.
-  octane@0.6.3: node_modules/.pnpm-config/@octane-xplat/patches/patches/octane@0.6.3.patch
-  # FlexboxLayout getChildMeasureSpec subtracts the child's own padding where AOSP subtracts
-  # parent padding + child margins — a column-stretched row re-measurement clamps padded
-  # children (37→17 dip, squished controls). Adds squircle (continuous) corner clipping for
-  # iOS backgrounds and CSS @layer cascade support to the native css-tree adapter (layer
-  # nodes, first-seen layerPath ordinals, layer rank ahead of specificity with unlayered
-  # last — sans !important). Ports the runtime half of NativeScript PR #11446 (fixes
-  # #11444): TabView onItemsChanged keeps retained items attached instead of
-  # unloading/re-adding them (the churn that left TabViewItem-hosted Frames isLoaded=false
-  # on iOS and detached from their tab fragment on Android), iOS items writes load the
-  # selected item's view once controllers exist, and Frame._pushInFrameStack only promotes
-  # frames whose ancestors present them (Frame.topmost stops returning hidden preloaded tab
-  # frames). Also maps CSS font-weight to the OpenType wght axis for custom Android fonts on
-  # API 26+, preserves explicit variation settings, and falls back to the prior file load
-  # when the axis is unsupported. Carries NativeScript PR #11481: preserves percentage
-  # translate values through parsing and resolves each axis against the view's own
-  # dimensions, including native views and animations.
-  "@nativescript/core@9.1.2": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript__core@9.1.2.patch
+  # Published 0.10.2 ships async/generator non-component helper compilation and Descriptor
+  # lexical/ancestor ownership, so the helper hunks are removed and the old four-hunk
+  # instance ownership fix becomes one declaring-owner reader fallback per distribution.
+  # Retains renderer-owned Children.toArray/map with explicit universal-native re-exports
+  # for older runtimes, universal signal-read tracking and local hooks, root event-error
+  # forwarding, and the complete universal imperative-ref lifecycle. Connects universal
+  # signal-owner identities to the upstream enclosingOwner chain so child reads reuse
+  # instance declarations. Verified against the registry 0.10.2 tarball and the patched
+  # 0.6.3 output.
+  octane@0.10.2: node_modules/.pnpm-config/@octane-xplat/patches/patches/octane@0.10.2.patch
+  # Published 9.1.3 ships the #11446 nested-tab-frame lifecycle fix and iOS explicit-size
+  # flex alignment, so those hunks are removed. Retains the unshipped parent-padding
+  # measure-spec fix and Android explicit-size flex alignment, iOS continuous corner
+  # clipping, CSS @layer cascade support, custom Android variable-font weight mapping, and
+  # percentage translate parsing, native view, and animation support. Verified against the
+  # registry 9.1.3 tarball; it has no Windows implementation, so the separate Windows
+  # preview patch remains.
+  "@nativescript/core@9.1.3": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript__core@9.1.3.patch
   # @nativescript/vite serializes bundled CSS and dev app.css through reworkcss `css`@3.0.0,
   # which mis-parses @layer into garbage selectors — rules die before reaching
   # _populateRules. Adds atlayer() covering block and statement forms. Applies to a
@@ -118,4 +107,4 @@ patchedDependencies:
   # bytes to disk.
   "@nativescript-community/ui-image@5.0.17": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript-community__ui-image@5.0.17.patch
 configDependencies:
-  "@octane-xplat/patches": 0.11.1
+  "@octane-xplat/patches": 0.12.0

package/template/references.d.ts

@@ -1 +1,2 @@
 /// <reference types="@nativescript/types" />
+/// <reference types="vite/client" />

package/template/src/App.tsrx

@@ -28,16 +28,16 @@ export function App() @{
 		<Text className="muted">one codebase — web · iOS · android</Text>
 
 		<HStack className="counter">
-			<Pressable className="btn" onPress={() => setCount(count - 1)}><Text>−</Text></Pressable>
-			<Text className="count">{count}</Text>
-			<Pressable className="btn" onPress={() => setCount(count + 1)}><Text>+</Text></Pressable>
+			<Pressable testID="counter.decrement" accessibilityLabel="Decrease count" className="btn" onPress={() => setCount(count - 1)}><Text>−</Text></Pressable>
+			<Text testID="counter.value" className="count">{count}</Text>
+			<Pressable testID="counter.increment" accessibilityLabel="Increase count" className="btn" onPress={() => setCount(count + 1)}><Text>+</Text></Pressable>
 		</HStack>
 
 		<ScrollableArea>
 			{FEATURES.map((f) => <Text className="chip">{f}</Text>)}
 		</ScrollableArea>
 
-		<Pressable className="link" onPress={() => {
+		<Pressable testID="settings.toggle-theme" className="link" onPress={() => {
 			const next = !dark;
 			storage.setString('theme-preference', next ? 'dark' : 'light');
 			setOverride(next);

package/template/src/app.spec.tsrx

@@ -0,0 +1,132 @@
+// Starter spec — `pnpm test:ios` runs this inside the real iOS runtime
+// (same renderer, native views, and services your app uses).
+//
+// mountXplat() renders a component onto the test host page and unmounts it
+// when the test finishes; tap()/enterText() dispatch through the same
+// gesture observers as real touches — that proves your wiring, not OS
+// hit-testing (device journeys like that belong to Maestro).
+import { describe, expect, it } from 'vitest'
+import { useEffect, useState } from 'octane'
+import { Pressable, Text, TextInput, View } from '@octane-xplat/ui'
+import {
+	type TextInputView,
+	enterText,
+	findByTestId,
+	mountXplat,
+	nextRenderPass,
+	tap,
+	viewText,
+	waitUntil,
+} from '@octane-xplat/platform/testing'
+
+import { App } from './App.tsrx'
+
+// Controlled input — typing flows up through onChange and back down as the
+// rendered value, and parent writes reach the native field.
+function NameForm() @{
+	const [name, setName] = useState('')
+
+	<View>
+		<TextInput
+			testID="greeting.name"
+			value={name}
+			onChange={setName}
+			placeholder="Your name"
+		/>
+		<Pressable testID="greeting.reset" onPress={() => setName('Bob')}>
+			<Text>set bob</Text>
+		</Pressable>
+		<Text>{'greeting: ' + (name || 'stranger')}</Text>
+	</View>
+}
+
+// Conditional mount — a subtree exists only while its state says so.
+function Details() @{
+	const [open, setOpen] = useState(false)
+
+	<View>
+		<Pressable testID="details.toggle" onPress={() => setOpen(!open)}>
+			<Text>toggle</Text>
+		</Pressable>
+		@if (open) {
+			<Text>detail: open</Text>
+		}
+	</View>
+}
+
+// Async states — loading first, then a settled value or an error. The
+// cleanup flag keeps a late timer from writing into an unmounted tree.
+function FetchLabel(props: { fail?: boolean }) @{
+	const [state, setState] = useState('loading')
+	useEffect(() => {
+		let live = true
+		const timer = setTimeout(() => {
+			if (live) setState(props.fail ? 'error' : 'ready')
+		}, 30)
+
+		return () => {
+			live = false
+			clearTimeout(timer)
+		}
+	}, [])
+
+	<Text>{'fetch: ' + state}</Text>
+}
+
+describe('starter app on device', () => {
+	it('mounts, reacts to a tap, and unmounts cleanly', async () => {
+		const { view, host, unmount } = await mountXplat(App)
+
+		const increment = findByTestId(view, 'counter.increment')
+		const count = findByTestId<TextInputView>(view, 'counter.value')
+		expect(increment?.isLoaded, 'counter.increment resolves to a loaded native view').toBe(true)
+
+		await tap(increment!)
+		await waitUntil(() => count?.text === '1', {
+			message: 'tap did not reach the increment Pressable',
+		})
+
+		await unmount()
+		await nextRenderPass()
+		expect(host.content).toBe(null)
+	})
+
+	it('round-trips a controlled TextInput', async () => {
+		const { view } = await mountXplat(NameForm)
+		const field = findByTestId<TextInputView>(view, 'greeting.name')
+		expect(field?.isLoaded).toBe(true)
+
+		await enterText(field!, 'Ada')
+		await waitUntil(() => viewText(view).includes('greeting: Ada'), {
+			message: 'onChange did not deliver the typed text',
+		})
+
+		await tap(findByTestId(view, 'greeting.reset')!)
+		await waitUntil(() => field?.text === 'Bob', {
+			message: 'parent write did not reach the native field',
+		})
+	})
+
+	it('mounts and unmounts a conditional subtree', async () => {
+		const { view } = await mountXplat(Details)
+		expect(viewText(view).includes('detail: open')).toBe(false)
+
+		await tap(findByTestId(view, 'details.toggle')!)
+		await waitUntil(() => viewText(view).includes('detail: open'))
+
+		await tap(findByTestId(view, 'details.toggle')!)
+		await waitUntil(() => !viewText(view).includes('detail: open'))
+	})
+
+	it('settles async loading and error states', async () => {
+		const ready = await mountXplat(FetchLabel)
+		await waitUntil(() => viewText(ready.view).includes('fetch: ready'), {
+			message: 'loading state never settled',
+		})
+
+		const failed = await mountXplat(FetchLabel, { fail: true })
+		await waitUntil(() => viewText(failed.view).includes('fetch: error'), {
+			message: 'error state never surfaced',
+		})
+	})
+})

package/template/src/test.ts

@@ -0,0 +1,22 @@
+// Test bundle entry — `ns test` builds with --env.unitTesting, and the
+// xplatNative preset swaps the app entry (src/main.ts) for this file, so the
+// device boots the Vitest coordinator instead of the app.
+import '@valor/nativescript-websockets'
+import { Application } from '@nativescript/core'
+import {
+	NativeScriptVitestCoordinator,
+	createNativeScriptTestRegistry,
+} from '@nativescript/unit-test-runner/runtime'
+
+import { createVitestHostPage } from '@nativescript/unit-test-runner/testing'
+
+const coordinator = new NativeScriptVitestCoordinator({
+	// Every spec matched by vitest.config.mts `include` must also match this
+	// glob — vite statically bundles each as a lazily imported chunk that the
+	// registry loads on demand.
+	registry: createNativeScriptTestRegistry(import.meta.glob('./**/*.spec.{ts,tsx,tsrx}')),
+})
+
+void coordinator.start()
+// The host page keeps the screen free as a mountXplat() surface for UI specs.
+Application.run({ create: () => createVitestHostPage(coordinator) })

package/template/vitest.config.mts

@@ -0,0 +1,30 @@
+import { defineConfig } from 'vitest/config'
+import { nativeScript } from '@nativescript/unit-test-runner'
+
+// `pnpm test:ios` / `pnpm test:android` (ns test) drive this config: the
+// plugin launches `ns run <platform> --no-hmr --env.unitTesting` and
+// orchestrates spec execution on-device over a loopback WebSocket — Vitest
+// stays the orchestrator on the host.
+//
+// On hosts without Simulator.app (Xcode 27+), `ns run` can only target an
+// already-booted simulator: `xcrun simctl boot <udid>` first, then pass
+// `--device <udid>` (or NS_DEVICE).
+export default defineConfig({
+	plugins: [
+		nativeScript({
+			platform: process.env.NS_PLATFORM || 'ios', // 'android' | 'ios' | 'visionos'
+			device: process.env.NS_DEVICE || undefined,
+			// Keep this in sync with the import.meta.glob in src/test.ts —
+			// the device can only run files that made it into the bundle.
+			include: ['src/**/*.spec.{ts,tsx,tsrx}'],
+			// The connect clock starts when the host session opens and covers
+			// `ns run`'s native build + install + boot — a cold build easily
+			// exceeds the 120s default.
+			connectTimeout: 600_000,
+		}),
+	],
+	test: {
+		// Device runs include app startup and real layout passes.
+		testTimeout: 30_000,
+	},
+})