create-octane-xplat 0.15.0 → 0.16.0

package/library-template/pnpm-workspace.yaml

@@ -4,14 +4,153 @@ allowBuilds:
   esbuild: true
   '@parcel/watcher': true
   '@nativescript/core': false
-# Shared version pins — bump these here, every dependency field reads them.
-catalog:
-  octane: 0.11.0
-  '@nativescript-community/octane': 0.2.4
-  '@nativescript/core': 9.1.3
-  '@nativescript/types': 9.1.4
-  typescript: 5.9.3
-  vite: 8.3.0
-  '@octanejs/vite-plugin': 0.1.61
-  '@tsrx/typescript-plugin': 0.4.11
-  vitest: 4.1.11
+catalogs:
+  xplat:
+    "@nativescript-community/octane": 0.2.5
+    "@nativescript/core": 9.1.3
+    "@nativescript/types": 9.1.4
+    "@octane-xplat/cli": 0.16.0
+    "@octane-xplat/jsx": 0.16.0
+    "@octane-xplat/ui": 0.16.0
+    "@octanejs/vite-plugin": 0.1.61
+    "@tsrx/oxc": 0.20.0
+    "@tsrx/typescript-plugin": 0.4.11
+    octane: 0.11.0
+    tsrx-typegen: 0.2.2
+    typescript: 5.9.3
+    vite: 8.3.0
+    vitest: 4.1.11
+overrides:
+  "@nativescript/vite>esbuild": 0.27.7
+  "@nativescript-community/vite-octane>esbuild": 0.27.7
+  vite>esbuild: 0.27.7
+configDependencies:
+  "@octane-xplat/patches": 0.16.0
+allowUnusedPatches: true
+# Framework patches are supplied by the @octane-xplat/patches config dependency and
+# 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 0.11.0 still ships none of the retained fixes: it adds the document guard
+  # context around installDefaultSignalOwner and reflows the compile.js hook-classification
+  # sites, but every patched feature remains absent upstream. 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, the
+  # complete universal imperative-ref lifecycle, the Descriptor declaring-owner reader
+  # fallback, and the signal-owner/enclosingOwner chain so child reads reuse instance
+  # declarations. Verified against the registry 0.11.0 tarball; all hunks re-anchored to the
+  # rewritten compile.js and document-owner call sites. Disposes DOM provider descendants
+  # when children become null or undefined, releasing their refs and effects.
+  octane@0.11.0: node_modules/.pnpm-config/@octane-xplat/patches/patches/octane@0.11.0.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
+  # transitive dep — no app declares it directly.
+  css@3.0.0: node_modules/.pnpm-config/@octane-xplat/patches/patches/css@3.0.0.patch
+  # Dev-server fixes still missing after @nativescript/vite 8.0.17 added percent decoding
+  # for path-style /ns/m and Vue /ns/sfc requests (NativeScript#11483): collect re-export
+  # specifiers in the .vite/deps rewrite, route /@fs paths outside both roots through /ns/m
+  # (linked checkouts bypass the device transform upstream), and probe the non-active
+  # platform + `native` suffix tags in module candidates. The deps-bundle esbuild passes
+  # ignore vite resolve.alias, so a dep importing bare `octane` bundles the DOM runtime
+  # beside the universal one (hooks crash on boot, octane-xplat#3) — an onResolve plugin
+  # redirects `octane` → `octane/universal/native`. tsconfig-paths and the generated
+  # build-time checker moduleSuffixes also need the `.mobile` tier for iOS/Android/visionOS
+  # so `.mobile` leaves resolve under mapped imports and `ns build`. Served `/node_modules/`
+  # tails now also scan pnpm's `.pnpm` store and `link:`/`file:`/`portal:` dep roots — a
+  # linked package's transitive deps (e.g. @iconify/utils under @octane-xplat/icons) resolve
+  # nowhere else and 404 the dev session. findMonorepoWorkspaceRoot no longer treats a lone
+  # turbo.json as a workspace root — Turborepo's per-package task configs marked apps/* as
+  # roots, masking the real pnpm root so served `/node_modules/` tails never reached the
+  # `.pnpm` store scan and non-hoisted transitive deps like source-map-js 404'd dev boot.
+  # Linked dependency fallbacks also discover each linked package's enclosing workspace and
+  # reuse the cached, bounded workspace node_modules scan so transitive workspace siblings
+  # (auth to secure-storage to a private native plugin) resolve without the consumer
+  # supplying that workspace root. Transform candidates now keep root-relative URLs only
+  # when they identify the discovered file; nested linked-dependency and pnpm-store matches
+  # inside the app root use their actual filesystem paths, preserving query suffixes. The
+  # /ns/m import rewriter now resolves `#`-prefixed package `imports` specifiers through the
+  # importer's own package.json — raw-read node_modules files (e.g. octane's
+  # dist/signals/graph.js importing `#octane/dist/signal-actions/graph`) otherwise reach the
+  # device verbatim and the HTTP loader throws `Cannot find module`, deadlocking dev boot
+  # before any boot recording can bundle the dep. NativeScript#11551: preserve user virtual
+  # stylesheet imports while retaining browser-helper filtering, route virtual CSS through
+  # the native inline compiler/registration path before the generic virtual-module shortcut,
+  # and relay Vite virtual stylesheet updates as tagged native CSS updates through the same
+  # adapted-text endpoint. Empty sheets clear previous rules; CSS compilation failures
+  # return HTTP 500 instead of raw CSS.
+  "@nativescript/vite@8.0.17": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript__vite@8.0.17.patch
+  # Retains the workspace's NativeScript driver fixes when upgrading to 0.2.5 for portal
+  # support: a prop dropped from an update's complete prop bag — or set to
+  # `undefined`/`null` — is a removal that restores the documented default
+  # (Property/CssProperty setters get `unsetValue`, plain fields the captured pre-prop
+  # value, `style` keys diff per key); a never-applied `undefined` still skips the write.
+  # Also advertises the implemented visibility capability, carries Octane callback ref
+  # types, and preserves authored Grid row/col/span metadata. Hosts custom-layout containers
+  # (e.g. MasonKit ViewBase) that own child lists via
+  # insertChild/removeChild/getChildrenCount without subclassing LayoutBase. Additionally,
+  # the masonry cutover: masonview resolves to MasonKit View and scrollview to MasonKit
+  # Scroll as the only layout containers, with zero layout props — every former prop name
+  # warns-and-drops and all CSS semantics arrive through the style bag; style keys on a
+  # mason child route to its leaf (stashed pre-attach, replayed at attach) via
+  # Style.fromView.
+  "@nativescript-community/octane@0.2.5": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript-community__octane@0.2.5.patch
+  # octaneServerStrategy's SCRIPT_FILE_RE only covers [jt]sx? — .tsrx edits never emit the
+  # deferred ns:hmr-delta broadcast, so component HMR silently never reaches the device.
+  # Also counts open /ns-hmr sockets so the update summary stops reporting recipients=0 for
+  # delivered updates.
+  "@nativescript-community/vite-octane@0.2.1": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript-community__vite-octane@0.2.1.patch
+  # Enables `resolveHiddenExtensions` on the language plugin's typescript facet so
+  # extensionless specifiers (e.g. './Text') probe `.tsrx` after moduleSuffixes — required
+  # for a single extensionless shared barrel to resolve per-platform leaves under tsrx-tsc
+  # and the IDE plugin.
+  "@tsrx/typescript-plugin@0.4.11": node_modules/.pnpm-config/@octane-xplat/patches/patches/@tsrx__typescript-plugin@0.4.11.patch
+  # linkifyjs declares /\p{L}/u and /\p{Emoji}/u as regex literals at module scope;
+  # NativeScript's embedded V8 builds without ICU, so the literals throw SyntaxError at
+  # parse time and poison the whole bundle (any bundled app importing @tiptap/extension-link
+  # dies on boot). Rewrites them as try/catch new RegExp builds with ASCII-range fallbacks —
+  # same behavior where ICU exists, graceful degradation where it doesn't.
+  linkifyjs@4.3.3: node_modules/.pnpm-config/@octane-xplat/patches/patches/linkifyjs@4.3.3.patch
+  # useEditor.ts reads bare process.env.NODE_ENV — no node global exists in the harness
+  # typecheck program. Adds a module-local process declaration for typecheck. (The
+  # './Context' self-import half of the 0.0.51 patch shipped upstream in 0.0.52 via
+  # octanejs/octane#1502.)
+  "@octanejs/tiptap@0.0.52": node_modules/.pnpm-config/@octane-xplat/patches/patches/@octanejs__tiptap@0.0.52.patch
+  # @lexical/link declares a /\p{L}\p{N}/u URL matcher as a regex literal at module scope;
+  # NativeScript's embedded V8 builds without ICU, so the literal throws SyntaxError at
+  # parse time and poisons the whole bundle (any bundled app importing @lexical/link dies on
+  # boot). Same fix as linkifyjs: try/catch new RegExp with an ASCII-range fallback — the
+  # matcher only feeds autolink, which native doesn't use.
+  "@lexical/link@0.51.0": node_modules/.pnpm-config/@octane-xplat/patches/patches/@lexical__link@0.51.0.patch
+  # ui-image 5.x regressed two iOS prefetch behaviors the 4.x line shipped (still present in
+  # 4.6.20): prefetchToCacheType ignores its cacheType argument — SDWebImagePrefetcher's
+  # default context stores to disk+memory either way, so a 'disk' prefetch also decodes and
+  # warms memory, diverging from Android's bytes-only Glide downloadOnly — and
+  # getContextFromOptions drops PrefetchOptions.headers because it never sets
+  # SDWebImageContextDownloadRequestModifier, so prefetch({headers}) silently sends no
+  # headers on iOS while Android's CustomGlideUrl forwards them. Ports upstream's own 4.x
+  # implementation — SDWebImageContextStoreCacheType on the prefetch context plus the
+  # request-modifier branch in getContextFromOptions — and additionally sets
+  # SDWebImageContextOriginalStoreCacheType so a memory prefetch does not spill original
+  # 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
+  # @nativescript/doctor's Android runtime check reads the app's raw devDependencies
+  # specifier and npm dist-tag resolves anything that isn't a semver range — a pnpm
+  # `catalog:` pin throws 'The determined Android runtime version ... is not valid' and
+  # kills `ns build android` before toolchain checks. Resolve catalog specifiers through the
+  # installed package's manifest, reusing the existing tgz-branch mechanism.
+  "@nativescript/doctor@2.0.18": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript__doctor@2.0.18.patch
+  # list/index.ios.js assigns `ObjCProtocols = [MasonListDelegate]` at module scope.
+  # MasonListDelegate is declared in Mason-Swift.h, which the app's metadata generation does
+  # not surface as a runtime global — importing masonkit on iOS throws `MasonListDelegate is
+  # not defined` during bundle eval and kills the app at boot. Guard the binding; actual
+  # List delegate conformance when the protocol is absent is a separate gap.
+  "@triniwiz/nativescript-masonkit@1.0.0-beta.110": node_modules/.pnpm-config/@octane-xplat/patches/patches/@triniwiz__nativescript-masonkit@1.0.0-beta.110.patch

package/library-template/src/Badge.tsx

@@ -1,4 +1,4 @@
-/** @jsxImportSource @nativescript-community/octane */
+/** @jsxImportSource @octane-xplat/jsx */
 import { Text, View } from '@octane-xplat/ui'
 import { normalizeBadgeLabel } from './normalizeBadgeLabel'
 import type { BadgeProps } from './props'

package/library-template/src/Badge.web.tsx

@@ -1,4 +1,4 @@
-/** @jsxImportSource octane */
+/** @jsxImportSource @octane-xplat/jsx/dom */
 import { Text, View } from '@octane-xplat/ui'
 import { normalizeBadgeLabel } from './normalizeBadgeLabel'
 import type { BadgeProps } from './props'

package/library-template/tests/packed-consumer.mjs

@@ -67,6 +67,7 @@ try {
 			installDirectory(packed, sourceManifest.name, consumer)
 			for (const dependency of [
 				'octane',
+				'@octane-xplat/jsx',
 				'@octane-xplat/ui',
 				...(target === 'native'
 					? ['@nativescript-community/octane', '@nativescript/core', '@nativescript/types']
@@ -105,7 +106,7 @@ void element; void missing; void invalid
 							module: mode === 'bundler' ? 'esnext' : 'nodenext',
 							moduleResolution: mode,
 							jsx: 'react-jsx',
-							jsxImportSource: target === 'native' ? '@nativescript-community/octane' : 'octane',
+							jsxImportSource: target === 'native' ? '@octane-xplat/jsx' : '@octane-xplat/jsx/dom',
 							customConditions: [target],
 							moduleSuffixes: target === 'web' ? ['.web', ''] : ['.mobile', ''],
 						},

package/library-template/tsconfig.envs.json

@@ -1,5 +1,8 @@
 {
 	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"jsxImportSource": "@octane-xplat/jsx"
+	},
 	"environments": {
 		"web": {
 			"include": ["src/**/*.{ts,tsx,tsrx}"]

package/library-template/tsconfig.json

@@ -5,7 +5,7 @@
 		"module": "esnext",
 		"moduleResolution": "bundler",
 		"jsx": "react-jsx",
-		"jsxImportSource": "octane",
+		"jsxImportSource": "@octane-xplat/jsx",
 		"moduleSuffixes": [
 			"",
 			".web",

package/library-template/tsrx-typegen.json

@@ -1,7 +1,7 @@
 {
 	"targets": {
 		"octane": {
-			"renderer": "octane",
+			"renderer": "@octane-xplat/jsx",
 			"project": "tsconfig.types.json",
 			"outDir": "types",
 			"entrypoints": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-octane-xplat",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Scaffold Octane Xplat apps and cross-platform libraries",
   "keywords": [
     "component-library",
@@ -21,22 +21,39 @@
     "directory": "packages/create"
   },
   "bin": {
-    "create-octane-xplat": "./index.mjs"
+    "create-octane-xplat": "./dist/index.js"
   },
   "files": [
-    "index.mjs",
-    "scaffold.mjs",
+    "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,7 +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 app dep
-// versions and script bodies; library-template/package.json owns the library
-// starter. The release bump script updates both manifests.
+// 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,29 +13,38 @@ import {
 
 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')
-export const LIBRARY_TEMPLATE_DIR = join(
-	dirname(fileURLToPath(import.meta.url)),
-	'library-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',
 	},
@@ -44,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',
 	},
@@ -68,22 +76,15 @@ export const targets = {
 			'vite.config.native.mts',
 			'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',
 			'src/native-runtime.spec.ts',
 			'src/failure-reporting.spec.ts',
-			'vitest.config.mts',
 		],
 		deps: [
-			'@nativescript-community/gesturehandler',
 			'@nativescript-community/octane',
-			'@nativescript-community/ui-drawer',
 			'@nativescript/core',
-			'@octane-xplat/effects',
-			'@octane-xplat/image',
 			'@valor/nativescript-websockets',
 		],
 		devDeps: [
@@ -92,7 +93,6 @@ export const targets = {
 			'@nativescript/unit-test-runner',
 			'@nativescript/vite',
 			'nativescript',
-			'vitest',
 		],
 		typecheck: 'xplat typecheck',
 	},
@@ -111,7 +111,7 @@ 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) {
@@ -150,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
@@ -168,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}"`)
@@ -187,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)
@@ -219,7 +219,7 @@ 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)
@@ -255,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')
@@ -284,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 ?? []) {
@@ -294,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)
@@ -326,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)
 }
 
 /**
@@ -407,7 +418,7 @@ export function composeTsconfig(ids) {
 	return JSON.stringify(config, null, '\t') + '\n'
 }
 
-/** Write a scaffold for `ids` into `dir` (must not exist or be empty). */
+/** 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 })
@@ -488,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
@@ -543,9 +554,9 @@ function enableNativeInTsconfig(appRoot) {
 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: [],
@@ -620,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,16 +119,24 @@ 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                                                                  |

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/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 ""