create-octane-xplat 0.14.0 → 0.16.0

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "create-octane-xplat",
-  "version": "0.14.0",
-  "description": "Scaffold a minimal @octane-xplat/ui app — one Octane codebase for web + iOS + Android",
+  "version": "0.16.0",
+  "description": "Scaffold Octane Xplat apps and cross-platform libraries",
   "keywords": [
+    "component-library",
     "create",
     "cross-platform",
     "init",
@@ -20,21 +21,39 @@
     "directory": "packages/create"
   },
   "bin": {
-    "create-octane-xplat": "./index.mjs"
+    "create-octane-xplat": "./dist/index.js"
   },
   "files": [
-    "index.mjs",
-    "scaffold.mjs",
-    "template"
+    "index.ts",
+    "scaffold.ts",
+    "compatibility.ts",
+    "compatibility.json",
+    "dist",
+    "template",
+    "library-template"
   ],
   "type": "module",
   "exports": {
-    "./scaffold": "./scaffold.mjs"
+    "./scaffold": "./dist/scaffold.js",
+    "./compatibility": {
+      "types": "./compatibility.ts",
+      "default": "./dist/compatibility.js"
+    },
+    "./compatibility.json": "./compatibility.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@clack/prompts": "1.8.1"
+    "@clack/prompts": "1.8.1",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "vite": "8.3.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc -p tsconfig.json"
   }
 }

package/{scaffold.mjs → scaffold.ts}

@@ -1,9 +1,6 @@
 // Scaffold manifest + compose/apply shared by create-octane-xplat and the
-// CLI's `xplat add`. template/package.json is the canonical store for dep
-// versions and script bodies — targets name which keys they own; unclaimed
-// files, deps, and scripts are part of the base scaffold. Keeping versions in
-// template/package.json means scripts/bump-versions.mjs keeps working
-// unchanged at release time.
+// CLI's `xplat add`. compatibility.json owns version pins; the generated
+// templates own script bodies and the dependency set for each starter.
 import {
 	cpSync,
 	existsSync,
@@ -14,27 +11,40 @@ import {
 	writeFileSync,
 } from 'node:fs'
 
-import { dirname, join } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { parseDocument } from 'yaml'
+import { ensureCompatibilityCatalog } from './compatibility.ts'
 
-export const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'template')
+const moduleDir = dirname(fileURLToPath(import.meta.url))
+// dist/ emit sits one level deeper than the root sources it mirrors.
+const pkgRoot = basename(moduleDir) === 'dist' ? join(moduleDir, '..') : moduleDir
+export const TEMPLATE_DIR = join(pkgRoot, 'template')
+export const LIBRARY_TEMPLATE_DIR = join(pkgRoot, 'library-template')
 
 /** Scaffoldable targets. `files` entries are template-relative paths —
  *  directories copy recursively. `deps`/`devDeps`/`scripts` name keys whose
  *  values come from template/package.json. `typecheck` contributes one clause
  *  to the generated typecheck script. */
-export const targets = {
+export const targets: Record<string, any> = {
 	web: {
 		label: 'Web (Vite)',
-		files: ['index.html', 'vite.config.ts', 'src/main.web.tsrx'],
-		scripts: ['dev', 'build'],
-		devDeps: ['@octanejs/vite-plugin'],
+		files: [
+			'index.html',
+			'vite.config.ts',
+			'src/main.web.tsrx',
+			'vitest.web.config.mts',
+			'src/app.web.test.tsx',
+			'src/test-setup.web.ts',
+		],
+		scripts: ['dev', 'build', 'test', 'test:web'],
+		devDeps: ['@octanejs/vite-plugin', 'jsdom'],
 	},
 	ios: {
 		label: 'iOS (NativeScript)',
 		requires: ['native-shared'],
 		files: ['App_Resources/iOS'],
-		scripts: ['dev:ios', 'test:ios', 'build:ios'],
+		scripts: ['dev:ios', 'build:ios', 'test:ios'],
 		devDeps: ['@nativescript/ios'],
 		note: 'needs macOS + Xcode — `pnpm xplat doctor` checks the toolchain',
 	},
@@ -42,7 +52,7 @@ export const targets = {
 		label: 'Android (NativeScript)',
 		requires: ['native-shared'],
 		files: ['App_Resources/Android'],
-		scripts: ['dev:android', 'test:android', 'build:android'],
+		scripts: ['dev:android', 'build:android', 'test:android'],
 		devDeps: ['@nativescript/android'],
 		note: 'needs Android SDK + a compatible JDK — `pnpm xplat doctor` checks the toolchain',
 	},
@@ -64,23 +74,17 @@ export const targets = {
 		files: [
 			'nativescript.config.ts',
 			'vite.config.native.mts',
-			'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.
+			'vitest.config.mts',
 			'src/test.ts',
 			'src/app.spec.tsrx',
-			'vitest.config.mts',
+			'src/native-runtime.spec.ts',
+			'src/failure-reporting.spec.ts',
 		],
 		deps: [
-			'@nativescript-community/gesturehandler',
 			'@nativescript-community/octane',
-			'@nativescript-community/ui-drawer',
 			'@nativescript/core',
-			'@octane-xplat/effects',
-			'@octane-xplat/image',
 			'@valor/nativescript-websockets',
 		],
 		devDeps: [
@@ -89,9 +93,8 @@ export const targets = {
 			'@nativescript/unit-test-runner',
 			'@nativescript/vite',
 			'nativescript',
-			'vitest',
 		],
-		typecheck: 'tsrx-tsc --noEmit -p tsconfig.native.json',
+		typecheck: 'xplat typecheck',
 	},
 }
 
@@ -100,15 +103,15 @@ export const selectableTargets = Object.keys(targets).filter((id) => !targets[id
 /** `pnpm create` without --targets and `xplat add`'s prompt default. */
 export const defaultTargets = ['web', 'ios', 'android']
 
-const BASE_TYPECHECK = 'tsrx-tsc --noEmit'
+const BASE_TYPECHECK = 'xplat typecheck'
 
 // package.json keys every scaffolded app keeps regardless of target set —
 // the targets' `scripts` lists own the rest.
-const BASE_SCRIPTS = ['xplat', 'lint', 'lint:fix']
+const BASE_SCRIPTS = ['xplat', 'lint', 'lint:fix', 'format']
 
 /** Expand `requires` edges, dependencies first. Throws on unknown ids. */
 export function resolveTargets(ids) {
-	const resolved = []
+	const resolved: string[] = []
 	const visit = (id) => {
 		const t = targets[id]
 		if (!t) {
@@ -147,7 +150,7 @@ function ownerOf(path) {
 }
 
 function walk(dir, prefix = '') {
-	const out = []
+	const out: string[] = []
 	for (const name of readdirSync(dir)) {
 		if (name === 'node_modules') {
 			continue
@@ -165,7 +168,7 @@ function walk(dir, prefix = '') {
 }
 
 function pickKeys(source, names, label) {
-	const out = {}
+	const out: Record<string, string> = {}
 	for (const name of names) {
 		if (source[name] === undefined) {
 			throw new Error(`template/package.json has no ${label} entry "${name}"`)
@@ -184,11 +187,11 @@ function pickKeys(source, names, label) {
 export function composeManifest(ids) {
 	const resolved = resolveTargets(ids)
 	const tpl = templateManifest()
-	const manifest = { ...tpl }
+	const manifest: Record<string, any> = { ...tpl }
 
 	for (const section of ['dependencies', 'devDependencies']) {
 		const key = section === 'dependencies' ? 'deps' : 'devDeps'
-		const wanted = new Set()
+		const wanted = new Set<string>()
 		for (const id of resolved) {
 			for (const name of targets[id][key] ?? []) {
 				wanted.add(name)
@@ -216,14 +219,14 @@ export function composeManifest(ids) {
 	}
 
 	const scripts = pickKeys(tpl.scripts ?? {}, [...wantedScripts].sort(), 'script')
-	const typecheck = [BASE_TYPECHECK]
+	const typecheck: string[] = [BASE_TYPECHECK]
 	for (const id of resolved) {
 		if (targets[id].typecheck) {
 			typecheck.push(targets[id].typecheck)
 		}
 	}
 
-	scripts.typecheck = typecheck.join(' && ')
+	scripts.typecheck = [...new Set(typecheck)].join(' && ')
 	// Keep the template's key order: scripts sit where they were.
 	manifest.scripts = {}
 	for (const name of Object.keys(tpl.scripts ?? {})) {
@@ -252,9 +255,9 @@ const patchPkg = (key) => key.replace(/@[^@]+$/, '')
 // Split a pnpm-workspace.yaml into per-package patch blocks (leading comment
 // lines included) so compose can drop entries and apply can transplant them.
 function parsePatchEntries(lines) {
-	const entries = []
+	const entries: any[] = []
 	let inPatches = false
-	let pending = []
+	let pending: string[] = []
 	for (const line of lines) {
 		if (/^\S/.test(line)) {
 			inPatches = line.startsWith('patchedDependencies')
@@ -281,7 +284,7 @@ function parsePatchEntries(lines) {
 /** The pnpm-workspace.yaml a given target set produces. */
 export function composeWorkspaceYaml(ids) {
 	const resolved = new Set(resolveTargets(ids))
-	const drop = new Set()
+	const drop = new Set<string>()
 	for (const [id, t] of Object.entries(targets)) {
 		if (!resolved.has(id)) {
 			for (const name of t.patches ?? []) {
@@ -291,9 +294,9 @@ export function composeWorkspaceYaml(ids) {
 	}
 
 	const lines = readFileSync(join(TEMPLATE_DIR, 'pnpm-workspace.yaml'), 'utf8').split('\n')
-	const out = []
+	const out: string[] = []
 	let inPatches = false
-	let pending = []
+	let pending: string[] = []
 	for (const line of lines) {
 		if (/^\S/.test(line)) {
 			out.push(...pending, line)
@@ -323,7 +326,18 @@ export function composeWorkspaceYaml(ids) {
 	}
 
 	out.push(...pending)
-	return out.join('\n')
+	const doc = parseDocument(out.join('\n'))
+	const manifest = composeManifest(ids)
+	const used = new Set([
+		...Object.keys(manifest.dependencies),
+		...Object.keys(manifest.devDependencies),
+	])
+	for (const name of Object.keys(doc.toJS().catalogs?.xplat ?? {})) {
+		if (!used.has(name)) {
+			doc.deleteIn(['catalogs', 'xplat', name])
+		}
+	}
+	return String(doc)
 }
 
 /**
@@ -384,13 +398,33 @@ function ensurePatchEntries(appRoot, enabledIds) {
 	return true
 }
 
-/** Write a scaffold for `ids` into `dir` (must not exist or be empty). */
+/**
+ * The tsconfig.json a given target set produces. One program covers every
+ * platform suffix (moduleSuffixes is the fixed precedence order); a web-only
+ * scaffold just drops the native ambient root and entrypoint.
+ */
+export function composeTsconfig(ids) {
+	const resolved = new Set(resolveTargets(ids))
+	const config = JSON.parse(readFileSync(join(TEMPLATE_DIR, 'tsconfig.json'), 'utf8'))
+	if (!resolved.has('native-shared')) {
+		delete config.files
+		config.compilerOptions.types = (config.compilerOptions.types ?? []).filter(
+			(t) => t !== '@nativescript/types',
+		)
+
+		config.exclude = [...new Set([...(config.exclude ?? []), 'src/main.ts'])]
+	}
+
+	return JSON.stringify(config, null, '\t') + '\n'
+}
+
+/** Write a scaffold with tests for `ids` into `dir` (must not exist or be empty). */
 export function composeTargets(ids, dir) {
 	const resolved = new Set(resolveTargets(ids))
 	mkdirSync(dir, { recursive: true })
 
 	for (const rel of walk(TEMPLATE_DIR)) {
-		if (rel === 'package.json' || rel === 'pnpm-workspace.yaml') {
+		if (rel === 'package.json' || rel === 'pnpm-workspace.yaml' || rel === 'tsconfig.json') {
 			continue // generated below
 		}
 
@@ -406,9 +440,43 @@ export function composeTargets(ids, dir) {
 
 	writeFileSync(join(dir, 'package.json'), JSON.stringify(composeManifest(ids), null, '\t') + '\n')
 	writeFileSync(join(dir, 'pnpm-workspace.yaml'), composeWorkspaceYaml(ids))
+	writeFileSync(join(dir, 'tsconfig.json'), composeTsconfig(ids))
 	return [...resolved]
 }
 
+/** Write the cross-platform library starter into `dir`. */
+export function composeLibrary(dir, packageName = basename(resolve(dir))) {
+	if (
+		packageName.length > 214 ||
+		!/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(packageName)
+	) {
+		throw new Error(
+			`invalid npm package name "${packageName}" — use lowercase letters, numbers, dots, underscores, or hyphens`,
+		)
+	}
+
+	mkdirSync(dir, { recursive: true })
+	for (const rel of walk(LIBRARY_TEMPLATE_DIR)) {
+		if (rel === 'package.json') {
+			continue
+		}
+
+		const dest = join(dir, rel === 'gitignore' ? '.gitignore' : rel)
+		mkdirSync(dirname(dest), { recursive: true })
+		const source = join(LIBRARY_TEMPLATE_DIR, rel)
+		if (/\.(?:md|ts|tsx|mjs|json)$/.test(rel)) {
+			const content = readFileSync(source, 'utf8').replaceAll('octane-xplat-library', packageName)
+			writeFileSync(dest, content)
+		} else {
+			cpSync(source, dest, { recursive: true })
+		}
+	}
+
+	const manifest = JSON.parse(readFileSync(join(LIBRARY_TEMPLATE_DIR, 'package.json'), 'utf8'))
+	manifest.name = packageName
+	writeFileSync(join(dir, 'package.json'), JSON.stringify(manifest, null, '\t') + '\n')
+}
+
 const readJson = (file) => {
 	try {
 		return JSON.parse(readFileSync(file, 'utf8'))
@@ -431,7 +499,7 @@ export function targetEnabled(appRoot, id) {
 
 	// ios/android: declared runtime devDep is the canonical signal — App_Resources
 	// alone doesn't reach the bundler config.
-	const manifest = readJson(join(appRoot, 'package.json')) ?? {}
+	const manifest: Record<string, any> = readJson(join(appRoot, 'package.json')) ?? {}
 	const declared = { ...manifest.dependencies, ...manifest.devDependencies }
 	const runtime = { ios: '@nativescript/ios', android: '@nativescript/android' }[id]
 	return runtime ? typeof declared[runtime] === 'string' : false
@@ -451,6 +519,33 @@ function copyMissing(rel, appRoot, report) {
 	report.copied.push(rel)
 }
 
+/**
+ * Fold a native-capable app's sources into the one tsconfig program: the
+ * manifest (tsconfig.envs.json) is gone — one program covers every platform
+ * suffix — so enabling native means wiring the ambient declaration file and
+ * the entrypoint into the app's own config.
+ */
+function enableNativeInTsconfig(appRoot) {
+	const path = join(appRoot, 'tsconfig.json')
+	const text = existsSync(path) ? readFileSync(path, 'utf8') : ''
+	const config = readJson(path)
+	if (!config || typeof config !== 'object') {
+		return false
+	}
+
+	const indent = text.match(/\n(\s+)"/)?.[1] ?? '\t'
+	config.files = [...new Set(['references.d.ts', ...(config.files ?? [])])]
+	config.exclude = (config.exclude ?? []).filter((e) => e !== 'src/main.ts')
+
+	const types = config.compilerOptions?.types
+	if (config.compilerOptions && Array.isArray(types) && !types.includes('@nativescript/types')) {
+		config.compilerOptions.types = [...types, '@nativescript/types']
+	}
+
+	writeFileSync(path, JSON.stringify(config, null, indent) + '\n')
+	return true
+}
+
 /**
  * Enable `id` (plus unmet `requires`) inside an existing app at `appRoot`.
  * Additive only: existing files, scripts, and dep entries are skipped, never
@@ -459,9 +554,9 @@ function copyMissing(rel, appRoot, report) {
 export function applyTarget(appRoot, id) {
 	const manifestPath = join(appRoot, 'package.json')
 	const raw = readFileSync(manifestPath, 'utf8')
-	const manifest = JSON.parse(raw)
+	const manifest: Record<string, any> = JSON.parse(raw)
 	const tpl = templateManifest()
-	const report = {
+	const report: Record<string, any> = {
 		enabled: [],
 		already: [],
 		copied: [],
@@ -515,8 +610,15 @@ export function applyTarget(appRoot, id) {
 			}
 		}
 
-		if (tid === 'native-shared' && manifest.main === undefined) {
-			manifest.main = tpl.main
+		if (tid === 'native-shared') {
+			if (manifest.main === undefined) {
+				manifest.main = tpl.main
+			}
+
+			// Native sources join the app's single typecheck program — pull the
+			// ambient declaration entry into the roots and un-exclude the
+			// NativeScript entry that a web-only scaffold skips.
+			report.tsconfigUpdated = enableNativeInTsconfig(appRoot)
 		}
 
 		touched = true
@@ -529,12 +631,12 @@ export function applyTarget(appRoot, id) {
 	if (ensurePatchEntries(appRoot, [...report.enabled, ...report.already])) {
 		report.patchesAdded = true
 	}
+	ensureCompatibilityCatalog(appRoot, manifest)
 
 	if (touched) {
 		// Match the file's existing indent so diffs stay minimal.
 		const indent = raw.match(/\n(\s+)"/)?.[1] ?? '\t'
 		writeFileSync(manifestPath, JSON.stringify(manifest, null, indent) + '\n')
 	}
-
 	return report
 }

package/template/.agents/skills/xplat/SKILL.md

@@ -119,22 +119,30 @@ export function NameField() {
 ```
 
 - `.mobile.tsrx`/`.ios.tsrx`/`.android.tsrx` files and unsuffixed native-default files containing JSX must
-  start with `/** @jsxImportSource @nativescript-community/octane */` on
+  start with `/** @jsxImportSource @octane-xplat/jsx */` on
   line 1 — nothing may precede it:
 
 ```tsrx
-/** @jsxImportSource @nativescript-community/octane */
+/** @jsxImportSource @octane-xplat/jsx */
 import { Text } from '@octane-xplat/ui'
 
 export function NativeGreeting() { return <Text>Hello</Text> }
 ```
 
+- Browser JSX leaves select DOM types explicitly on line 1. These pragmas
+  select types; the build keeps the existing web and native renderers:
+
+```tsx
+/** @jsxImportSource @octane-xplat/jsx/dom */
+export function BrowserGreeting() { return <p>Hello</p> }
+```
+
 ## Verify
 
 | Command                             | Catches                                                                  |
 | ----------------------------------- | ------------------------------------------------------------------------ |
 | `pnpm lint`                         | vocabulary / DOM-global / style violations — its output is authoritative |
-| `pnpm typecheck`                    | both web and native TS configs                                           |
+| `pnpm typecheck`                    | `tsconfig.json` + every environment declared in `tsconfig.envs.json`     |
 | `pnpm dev`                          | web behavior                                                             |
 | `pnpm dev:ios` / `pnpm dev:android` | the platform where behavior actually differs                             |
 

package/template/.agents/skills/xplat/references/components.md

@@ -141,7 +141,7 @@ Choose platform widgets when you want the OS's own controls. Import them only
 in the matching platform file. This iOS example belongs in `Preference.ios.tsrx`:
 
 ```tsrx
-/** @jsxImportSource @nativescript-community/octane */
+/** @jsxImportSource @octane-xplat/jsx */
 import { useState } from 'octane'
 import { UISwitch } from '@octane-xplat/ui/ios'
 
@@ -154,7 +154,7 @@ export function Preference() {
 The Android equivalent belongs in `Preference.android.tsrx`:
 
 ```tsrx
-/** @jsxImportSource @nativescript-community/octane */
+/** @jsxImportSource @octane-xplat/jsx */
 import { useState } from 'octane'
 import { MaterialSwitch } from '@octane-xplat/ui/android'
 

package/template/.agents/skills/xplat/references/navigation.md

@@ -5,7 +5,8 @@ web turns it into a URL, while native presents the screen in the app's navigatio
 Put components in `.tsrx` files.
 
 ```tsrx
-import { defineRoutes, registerRoutes, Text } from '@octane-xplat/ui'
+import { Text } from '@octane-xplat/ui'
+import { defineRoutes, registerRoutes } from '@octane-xplat/ui/routing'
 
 function Home() { return <Text>Home</Text> }
 function Settings() { return <Text>Settings</Text> }
@@ -20,7 +21,8 @@ After registering `settings`, use `NavLink` for a screen link or `pushRoute`
 in an event handler. `Link` accepts a URL, including an external website.
 
 ```tsrx
-import { HStack, Link, NavLink, Pressable, Text, pushRoute } from '@octane-xplat/ui'
+import { HStack, Link, NavLink, Pressable, Text } from '@octane-xplat/ui'
+import { pushRoute } from '@octane-xplat/ui/routing'
 
 export function SettingsLinks() {
   const settings = { stack: 'root', name: 'settings', params: {} }
@@ -36,7 +38,8 @@ Use `useRoute` to read the current screen and `useCanGoBack` to decide whether
 to offer a back button. Pass the same stack name to `popRoute`.
 
 ```tsrx
-import { Pressable, Text, useRoute, useCanGoBack, popRoute } from '@octane-xplat/ui'
+import { Pressable, Text } from '@octane-xplat/ui'
+import { useRoute, useCanGoBack, popRoute } from '@octane-xplat/ui/routing'
 
 export function NavigationStatus() {
   const route = useRoute('root')
@@ -56,7 +59,7 @@ on web with a warning; do not rely on it to carry application state. With a
 registered `/projects/:id` screen, navigate using the project ID:
 
 ```ts
-import { pushRoute } from '@octane-xplat/ui'
+import { pushRoute } from '@octane-xplat/ui/routing'
 
 pushRoute({ stack: 'root', name: 'projects/:id', params: { id: '42' } })
 ```
@@ -66,7 +69,8 @@ initial content; pushing a route into that stack opens it inside the tab pane.
 The screen below assumes `settings` is already registered.
 
 ```tsrx
-import { Tabs, Text, Pressable, pushRoute } from '@octane-xplat/ui'
+import { Tabs, Text, Pressable } from '@octane-xplat/ui'
+import { pushRoute } from '@octane-xplat/ui/routing'
 
 export function AppTabs() {
   return <Tabs tabs={[

package/template/.agents/skills/xplat/references/platform.md

@@ -61,13 +61,13 @@ import { Scanner } from './parts/Scanner'
 export function ScanScreen() { return <Scanner /> }
 ```
 
-Native JSX files start with the NativeScript pragma on line 1. Import native
+Native JSX files start with the shared JSX facade pragma on line 1. Import native
 APIs from `@nativescript/core`, and read app lifecycle state inside the call
 rather than during module initialization. This example belongs in
 `Status.mobile.tsrx`:
 
 ```tsrx
-/** @jsxImportSource @nativescript-community/octane */
+/** @jsxImportSource @octane-xplat/jsx */
 import { Application } from '@nativescript/core'
 import { Pressable, Text } from '@octane-xplat/ui'
 

package/template/AGENTS.md

@@ -8,6 +8,53 @@ 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.
 
+## Framework versions
+
+Keep framework/compiler/native tool pins in the supplied `catalog:xplat`.
+Upgrade the version set and patches together, then run the app's checks.
+Within a multi-package workspace, upgrade covers all packages. Preserve
+app-specific dependencies and reconcile custom-patch conflicts before retrying:
+
+```sh
+pnpm dlx @octane-xplat/cli@latest upgrade --check
+pnpm dlx @octane-xplat/cli@latest upgrade
+pnpm xplat doctor
+pnpm typecheck
+```
+
+## JSX types
+
+The app's `tsconfig.json` selects shared native JSX types. Browser JSX leaves
+select DOM types on their first line; keep runtime imports from `octane`:
+
+```tsx
+/** @jsxImportSource @octane-xplat/jsx/dom */
+export function BrowserMessage() {
+	return <p>Ready</p>
+}
+```
+
+Native leaves can explicitly select the same default with
+`/** @jsxImportSource @octane-xplat/jsx */`. Do not replace it with a renderer
+pragma. The facade supplies types; Vite still selects the platform renderer.
+
+## App testing
+
+The starter includes managed runners, sample tests, configuration, and scripts
+for its enabled platforms. Adapt the samples to the app and run the relevant
+commands:
+
+```sh
+pnpm test:web
+pnpm test:ios -- --device DEVICE_UDID
+pnpm test:android -- --device DEVICE_SERIAL
+```
+
+Only commands for enabled platforms are added. Web tests use jsdom; phone
+tests need a selected simulator or device. Report targets actually run and
+distinguish document checks from browser layout or OS input checks. See the
+[testing guide](https://octane-xplat.goddardai.org/verify/testing#add-automated-tests).
+
 ## Stable automation targets
 
 ```tsx

package/template/App_Resources/Android/app.gradle

@@ -4,7 +4,7 @@ dependencies {
 }
 
 android {
-  compileSdkVersion 35
+  compileSdkVersion 36
   buildToolsVersion "35"
   // ndkVersion ""