create-octane-xplat 0.16.0 → 0.17.0

package/README.md

@@ -99,7 +99,7 @@ your app as you replace the starter screen.
 
 Platforms added later also receive their test setup. The library template
 includes its component tests and publishing checks.
-See [checking an app](../../docs/verify/testing.md#add-automated-tests) for the
+See [checking an app](../../docs/testing/testing.md#add-automated-tests) for the
 commands, file conventions, and checks that still need a browser or phone.
 
 ## Keep compatible versions

package/compatibility.json

@@ -1,7 +1,7 @@
 {
 	"$comment": "Release compatibility set, shared by create-octane-xplat and xplat doctor/upgrade. Edit external pins here, then run pnpm sync:compatibility. Framework package names are generated from the lockstep release set. Optional packages are managed only when declared; library consumer peer ranges remain app-owned.",
 	"schemaVersion": 1,
-	"frameworkVersion": "0.16.0",
+	"frameworkVersion": "0.17.0",
 	"tools": {
 		"nodeMinimum": "22.18.0",
 		"pnpm": "11.24.0"
@@ -29,6 +29,7 @@
 		"@octane-xplat/image-crop",
 		"@octane-xplat/intersection-observer",
 		"@octane-xplat/jsx",
+		"@octane-xplat/keyboard",
 		"@octane-xplat/lexical",
 		"@octane-xplat/lib",
 		"@octane-xplat/lingui",
@@ -65,7 +66,7 @@
 	],
 	"packages": {
 		"octane": {
-			"version": "0.11.0",
+			"version": "0.14.0",
 			"group": "runtime",
 			"singleton": true
 		},
@@ -108,7 +109,7 @@
 			"group": "bundler"
 		},
 		"@nativescript/vite": {
-			"version": "8.0.17",
+			"version": "8.0.20",
 			"group": "bundler"
 		},
 		"nativescript": {
@@ -160,15 +161,15 @@
 			"group": "plugin"
 		},
 		"@nativescript-community/ui-image": {
-			"version": "5.0.17",
+			"version": "5.0.18",
 			"group": "plugin"
 		},
 		"@valor/nativescript-websockets": {
 			"version": "2.0.3",
 			"group": "plugin"
 		},
-		"@triniwiz/nativescript-masonkit": {
-			"version": "1.0.0-beta.110",
+		"@octane-xplat/nativescript-masonkit": {
+			"version": "1.0.0-beta.126",
 			"group": "runtime"
 		},
 		"jsdom": {

package/dist/scaffold.js

@@ -170,29 +170,6 @@ function composeManifest(ids) {
 }
 var PATCH_ENTRY = /^\s+"?(@?[\w./-]+@[\w.-]+)"?:\s+\S+\s*$/;
 var patchPkg = (key) => key.replace(/@[^@]+$/, "");
-function parsePatchEntries(lines) {
-	const entries = [];
-	let inPatches = false;
-	let pending = [];
-	for (const line of lines) {
-		if (/^\S/.test(line)) {
-			inPatches = line.startsWith("patchedDependencies");
-			pending = [];
-			continue;
-		}
-		if (!inPatches) continue;
-		const m = line.match(PATCH_ENTRY);
-		if (m) {
-			entries.push({
-				name: patchPkg(m[1]),
-				comments: pending,
-				line
-			});
-			pending = [];
-		} else pending.push(line);
-	}
-	return entries;
-}
 /** The pnpm-workspace.yaml a given target set produces. */
 function composeWorkspaceYaml(ids) {
 	const resolved = new Set(resolveTargets(ids));
@@ -237,7 +214,7 @@ function composeWorkspaceYaml(ids) {
 	return String(doc);
 }
 /**
-* Add the patch entries that `enabledIds` owns to the app's
+* Add the patch entries that `enabledIds` owns to the owning workspace's
 * pnpm-workspace.yaml. Entries already present (by package name, any
 * version) are kept. Returns true if the file changed.
 */
@@ -245,31 +222,36 @@ function ensurePatchEntries(appRoot, enabledIds) {
 	const needed = /* @__PURE__ */ new Set();
 	for (const id of enabledIds) for (const name of targets[id].patches ?? []) needed.add(name);
 	if (!needed.size) return false;
-	const yamlPath = join(appRoot, "pnpm-workspace.yaml");
+	let workspace = resolve(appRoot);
+	while (!existsSync(join(workspace, "pnpm-workspace.yaml")) && dirname(workspace) !== workspace) workspace = dirname(workspace);
+	if (!existsSync(join(workspace, "pnpm-workspace.yaml"))) workspace = appRoot;
+	const yamlPath = join(workspace, "pnpm-workspace.yaml");
 	const appText = existsSync(yamlPath) ? readFileSync(yamlPath, "utf8") : "";
-	const present = new Set(parsePatchEntries(appText.split("\n")).map((e) => e.name));
-	const missing = [...needed].filter((name) => !present.has(name));
-	if (!missing.length) return false;
-	const blocks = parsePatchEntries(readFileSync(join(TEMPLATE_DIR, "pnpm-workspace.yaml"), "utf8").split("\n")).filter((e) => missing.includes(e.name)).map((e) => [...e.comments, e.line].join("\n"));
 	if (!appText.trim()) {
 		writeFileSync(yamlPath, composeWorkspaceYaml(enabledIds));
 		return true;
 	}
-	let next = appText;
-	const lines = next.split("\n");
-	const sectionStart = lines.findIndex((l) => l.startsWith("patchedDependencies"));
-	if (sectionStart === -1) next = `${appText.trimEnd()}\npatchedDependencies:\n${blocks.join("\n")}\n`;
-	else {
-		let insertAt = lines.length;
-		for (let i = sectionStart + 1; i < lines.length; i++) if (/^\S/.test(lines[i])) {
-			insertAt = i;
-			break;
+	const doc = parseDocument(appText);
+	if (doc.errors.length) throw new Error(`${yamlPath}: ${doc.errors[0].message}`);
+	const present = new Set(Object.keys(doc.toJS()?.patchedDependencies ?? {}).map(patchPkg));
+	const template = parseDocument(readFileSync(join(TEMPLATE_DIR, "pnpm-workspace.yaml"), "utf8")).toJS();
+	let changed = false;
+	for (const [key, path] of Object.entries(template.patchedDependencies)) {
+		const name = patchPkg(key);
+		if (needed.has(name) && !present.has(name)) {
+			doc.setIn(["patchedDependencies", key], path);
+			changed = true;
 		}
-		lines.splice(insertAt, 0, ...blocks.join("\n").split("\n"));
-		next = lines.join("\n");
 	}
-	writeFileSync(yamlPath, next.endsWith("\n") ? next : next + "\n");
-	return true;
+	for (const [name, spec] of Object.entries(template.configDependencies)) {
+		const prefix = `node_modules/.pnpm-config/${name}/`;
+		if (Object.values(doc.toJS()?.patchedDependencies ?? {}).some((path) => typeof path === "string" && path.startsWith(prefix)) && !doc.hasIn(["configDependencies", name])) {
+			doc.setIn(["configDependencies", name], spec);
+			changed = true;
+		}
+	}
+	if (changed) writeFileSync(yamlPath, String(doc));
+	return changed;
 }
 /**
 * The tsconfig.json a given target set produces. One program covers every

package/library-template/package.json

@@ -73,8 +73,8 @@
 	"peerDependencies": {
 		"@nativescript-community/octane": ">=0.2.1 <1",
 		"@nativescript/core": ">=9.1.0 <10",
-		"@octane-xplat/jsx": "^0.16.0",
-		"@octane-xplat/ui": "^0.16.0",
+		"@octane-xplat/jsx": "^0.17.0",
+		"@octane-xplat/ui": "^0.17.0",
 		"octane": ">=0.6.3 <1"
 	},
 	"peerDependenciesMeta": {

package/library-template/pnpm-workspace.yaml

@@ -9,13 +9,13 @@ catalogs:
     "@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
+    "@octane-xplat/cli": 0.17.0
+    "@octane-xplat/jsx": 0.17.0
+    "@octane-xplat/ui": 0.17.0
     "@octanejs/vite-plugin": 0.1.61
     "@tsrx/oxc": 0.20.0
     "@tsrx/typescript-plugin": 0.4.11
-    octane: 0.11.0
+    octane: 0.14.0
     tsrx-typegen: 0.2.2
     typescript: 5.9.3
     vite: 8.3.0
@@ -25,23 +25,23 @@ overrides:
   "@nativescript-community/vite-octane>esbuild": 0.27.7
   vite>esbuild: 0.27.7
 configDependencies:
-  "@octane-xplat/patches": 0.16.0
+  "@octane-xplat/patches": 0.17.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 0.14.0 still requires 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. Rebased against the registry 0.14.0 tarball,
+  # including local signal-hook registration in the split runtime/hooks modules. Provider
+  # null/undefined descendant cleanup is now upstream and no longer patched. Marks generic
+  # binding bags from bagOf so fragment commit rehomes their DOM parent references,
+  # preventing stale fragment parents, namespace recursion, and invalid insertion during
+  # typeahead updates.
+  octane@0.14.0: node_modules/.pnpm-config/@octane-xplat/patches/patches/octane@0.14.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
@@ -55,58 +55,53 @@ patchedDependencies:
   # _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
+  # Remaining dev-server fixes on @nativescript/vite 8.0.20: collect re-export specifiers in
+  # the .vite/deps rewrite; route outside-roots /@fs paths through /ns/m; probe non-active
+  # platform and native suffixes; redirect bare octane to octane/universal/native in
+  # deps-bundle esbuild passes; add .mobile to tsconfig-paths and generated checker
+  # suffixes; scan the app-local pnpm virtual store for served node_modules URLs; ignore
+  # per-package turbo.json as workspace markers; resolve # package-imports specifiers in
+  # served-module rewrites; preserve, compile, and hot-update virtual stylesheets
+  # (NativeScript#11551); and inspect ESM export declarations/specifiers for native
+  # default-import validation instead of matching comments, strings, or a narrow export
+  # syntax (NativeScript#11566). Shared-source graph and hot-context IDs now use the same
+  # app/workspace/@fs paths as served imports, preserving distinct roots
+  # (NativeScript#11569); extensionless workspace requests probe filesystem-anchored
+  # extension/platform candidates so hot reimports can fetch shared modules
+  # (NativeScript#11570). Linked-checkout discovery and candidate anchoring shipped in
+  # 8.0.20 (NativeScript#11559), so those local hunks are removed.
+  "@nativescript/vite@8.0.20": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript__vite@8.0.20.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.
+  # Synced with PR #14: registered setters are identified before resetting (ordinary fields
+  # never receive the sentinel), inline removal refreshes matching class CSS through the
+  # isolated core 9.1 `_cssState.onChange` hook, CSS variables use public removal, strings
+  # use the core CSS parser, and replacement views capture fresh defaults. 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; foreign native leaves mirror resolved class and inline layout
+  # styles through Style.fromView, observe longhand changes and native recreation, and
+  # explicitly clear removed placement — removal restores the CSS cascade, so a later
+  # sibling attachment cannot resurrect removed tracks. Container alignment uses the core
+  # stretch default without a local style override, allowing class-authored centering.
+  # Inline style resets reapply the matching CSS cascade. Re-exports Octane's ClassValue
+  # unchanged and stringifies truthy numeric class values while omitting 0 and NaN, matching
+  # Octane 0.11.
   "@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.
+  # delivered updates. Includes shared script sources in transaction ordering while
+  # excluding dependencies, tests and declarations. External-source edits use the absolute
+  # source for graph identity and a Vite /@fs transform URL instead of treating
+  # parent-relative paths as app URLs.
   "@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
@@ -130,27 +125,21 @@ patchedDependencies:
   # 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
+  # shaders@4.0.0 inlines TypeGPU 0.12.3 into dist/core/std-ClftfWpF.js, which declares
+  # /\p{XID_Start}/ and /\p{XID_Continue}/ regex literals at module scope (WGSL identifier
+  # validation, external prop-chain matching, minify separator check). NativeScript's
+  # embedded V8 on iOS (@nativescript/ios 9.1.0) and Android (@nativescript/android 9.1.1,
+  # V8 14.9.207.39) is built without ICU — every \p{…} escape is a SyntaxError, even in a
+  # never-called function, so a literal fails the whole module at parse time and any bundled
+  # app importing `shaders/js` dies on boot. Rewriting to \p{ID_Start}/\p{L} would not help
+  # — all property escapes are rejected. The patch builds the regexes via try/catch new
+  # RegExp with ASCII/non-ASCII-range fallbacks — byte-identical .source where ICU exists.
+  # dist/js/bundle.js, react/bundle.js, and cli.js carry the same escapes but are
+  # unreachable from `shaders/js` and left unpatched.
+  shaders@4.0.0: node_modules/.pnpm-config/@octane-xplat/patches/patches/shaders@4.0.0.patch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-octane-xplat",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Scaffold Octane Xplat apps and cross-platform libraries",
   "keywords": [
     "component-library",

package/scaffold.ts

@@ -252,35 +252,6 @@ const PATCH_ENTRY = /^\s+"?(@?[\w./-]+@[\w.-]+)"?:\s+\S+\s*$/
 
 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: any[] = []
-	let inPatches = false
-	let pending: string[] = []
-	for (const line of lines) {
-		if (/^\S/.test(line)) {
-			inPatches = line.startsWith('patchedDependencies')
-			pending = []
-			continue
-		}
-
-		if (!inPatches) {
-			continue
-		}
-
-		const m = line.match(PATCH_ENTRY)
-		if (m) {
-			entries.push({ name: patchPkg(m[1]), comments: pending, line })
-			pending = []
-		} else {
-			pending.push(line)
-		}
-	}
-
-	return entries
-}
-
 /** The pnpm-workspace.yaml a given target set produces. */
 export function composeWorkspaceYaml(ids) {
 	const resolved = new Set(resolveTargets(ids))
@@ -341,7 +312,7 @@ export function composeWorkspaceYaml(ids) {
 }
 
 /**
- * Add the patch entries that `enabledIds` owns to the app's
+ * Add the patch entries that `enabledIds` owns to the owning workspace's
  * pnpm-workspace.yaml. Entries already present (by package name, any
  * version) are kept. Returns true if the file changed.
  */
@@ -357,45 +328,57 @@ function ensurePatchEntries(appRoot, enabledIds) {
 		return false
 	}
 
-	const yamlPath = join(appRoot, 'pnpm-workspace.yaml')
-	const appText = existsSync(yamlPath) ? readFileSync(yamlPath, 'utf8') : ''
-	const present = new Set(parsePatchEntries(appText.split('\n')).map((e) => e.name))
-	const missing = [...needed].filter((name) => !present.has(name))
-	if (!missing.length) {
-		return false
+	// Match catalog ownership: adding a target must not split an existing
+	// monorepo into a new, nested workspace.
+	let workspace = resolve(appRoot)
+	while (!existsSync(join(workspace, 'pnpm-workspace.yaml')) && dirname(workspace) !== workspace) {
+		workspace = dirname(workspace)
 	}
-
-	const tplText = readFileSync(join(TEMPLATE_DIR, 'pnpm-workspace.yaml'), 'utf8')
-	const blocks = parsePatchEntries(tplText.split('\n'))
-		.filter((e) => missing.includes(e.name))
-		.map((e) => [...e.comments, e.line].join('\n'))
-
+	if (!existsSync(join(workspace, 'pnpm-workspace.yaml'))) {
+		workspace = appRoot
+	}
+	const yamlPath = join(workspace, 'pnpm-workspace.yaml')
+	const appText = existsSync(yamlPath) ? readFileSync(yamlPath, 'utf8') : ''
 	if (!appText.trim()) {
 		writeFileSync(yamlPath, composeWorkspaceYaml(enabledIds))
 		return true
 	}
 
-	let next = appText
-	const lines = next.split('\n')
-	const sectionStart = lines.findIndex((l) => l.startsWith('patchedDependencies'))
-	if (sectionStart === -1) {
-		next = `${appText.trimEnd()}\npatchedDependencies:\n${blocks.join('\n')}\n`
-	} else {
-		// Insert before the next top-level key (or at EOF).
-		let insertAt = lines.length
-		for (let i = sectionStart + 1; i < lines.length; i++) {
-			if (/^\S/.test(lines[i])) {
-				insertAt = i
-				break
-			}
+	const doc = parseDocument(appText)
+	if (doc.errors.length) {
+		throw new Error(`${yamlPath}: ${doc.errors[0].message}`)
+	}
+	const present = new Set(Object.keys(doc.toJS()?.patchedDependencies ?? {}).map(patchPkg))
+	const template = parseDocument(
+		readFileSync(join(TEMPLATE_DIR, 'pnpm-workspace.yaml'), 'utf8'),
+	).toJS()
+	let changed = false
+	for (const [key, path] of Object.entries(template.patchedDependencies)) {
+		const name = patchPkg(key)
+		if (needed.has(name) && !present.has(name)) {
+			doc.setIn(['patchedDependencies', key], path)
+			changed = true
 		}
+	}
+
+	// Template paths are relative to the owning workspace. pnpm installs the
+	// config package there before resolving its patch files on the first install.
+	for (const [name, spec] of Object.entries(template.configDependencies)) {
+		const prefix = `node_modules/.pnpm-config/${name}/`
+		const usesPackage = Object.values(doc.toJS()?.patchedDependencies ?? {}).some(
+			(path) => typeof path === 'string' && path.startsWith(prefix),
+		)
 
-		lines.splice(insertAt, 0, ...blocks.join('\n').split('\n'))
-		next = lines.join('\n')
+		if (usesPackage && !doc.hasIn(['configDependencies', name])) {
+			doc.setIn(['configDependencies', name], spec)
+			changed = true
+		}
 	}
 
-	writeFileSync(yamlPath, next.endsWith('\n') ? next : next + '\n')
-	return true
+	if (changed) {
+		writeFileSync(yamlPath, String(doc))
+	}
+	return changed
 }
 
 /**

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

@@ -151,7 +151,7 @@ export function BrowserGreeting() { return <p>Hello</p> }
 - `references/components.md` — the component vocabulary plus per-platform
   divergences and name traps.
 - `references/styling.md` — tokens, the portable CSS subset, dark mode.
-- `references/navigation.md` — route table, links, params, stacks.
+- `references/navigation.md` — file routes, links, params, stacks, modals.
 - `references/platform.md` — device services and writing your own leaf.
 - Current limits and platform boundaries:
   https://octane-xplat.goddardai.org/known-limits

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

@@ -31,6 +31,12 @@ export function Welcome() {
 | Shells                | `Screen`, `Tabs`                                                              |
 | Theme and measurement | `useColorScheme`, `useSafeAreaInsets`, `useMeasure`                           |
 
+Native pages start full-screen: app content extends under the status bar
+and home indicator, and `SafeArea` is the only source of safe-area padding —
+wrap screen content that must stay clear of the system bars. A custom
+NativeScript page needs `prepareFullScreenPage(page)` from
+`@octane-xplat/ui/nativescript` before its content renders.
+
 For images, prefer the `Image` from `@octane-xplat/image` — it has the exact
 same props as `@octane-xplat/ui`'s `Image` but loads through a real image
 engine on native (Glide on Android, SDWebImage on iOS) with a sized memory +

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

@@ -1,87 +1,148 @@
 # Navigation
 
-Register screens once during app startup. A route names a screen and a stack;
-web turns it into a URL, while native presents the screen in the app's navigation.
-Put components in `.tsrx` files.
+Routes are files under `src/app`, not registered lists. A `[param]` segment
+becomes a typed `:param`. Write screens in `.tsrx` files and type callbacks
+with the generated `routes.gen.contracts` module:
 
 ```tsrx
+// src/app/items/[id].tsrx
 import { Text } from '@octane-xplat/ui'
-import { defineRoutes, registerRoutes } from '@octane-xplat/ui/routing'
+import type { RouteProps, RouteLoaderArgs } from '../../routes.gen.contracts'
 
-function Home() { return <Text>Home</Text> }
-function Settings() { return <Text>Settings</Text> }
+export function loader({ params }: RouteLoaderArgs<'/items/:id'>) {
+  return { title: 'Item ' + params.id }
+}
 
-registerRoutes(defineRoutes([
-  { path: '/', screen: Home },
-  { path: '/settings', screen: Settings },
-]))
+export function screen(props: RouteProps<'/items/:id'>) {
+  return <Text>{props.data.title}</Text>
+}
 ```
 
-After registering `settings`, use `NavLink` for a screen link or `pushRoute`
-in an event handler. `Link` accepts a URL, including an external website.
+Regenerate the catalog after adding or renaming route files (the dev and
+build commands also run it):
+
+```sh
+pnpm exec xplat routes --dir src/app
+```
+
+Import the generated client once in your entry module and place `RouteOutlet`
+around the content that forms the home screen — the starter's `App` keeps its
+own content and wraps it:
 
 ```tsrx
-import { HStack, Link, NavLink, Pressable, Text } from '@octane-xplat/ui'
-import { pushRoute } from '@octane-xplat/ui/routing'
+// src/App.tsrx
+import './routes.gen'
+import { NavLink, RouteOutlet, Text } from '@octane-xplat/ui'
+
+export function App() {
+  return <RouteOutlet>
+    <Text>My collection</Text>
+    <NavLink to="/items/:id" params={{ id: 'coat' }}><Text>Open coat</Text></NavLink>
+  </RouteOutlet>
+}
+```
+
+Use `NavLink` for a screen link or `useRouter()` in an event handler.
+Destinations are objects: a declared `to` pattern plus `params`. `Link`
+accepts a URL, including an external website.
+
+```tsrx
+// src/SettingsLinks.tsrx
+import { HStack, Link, Pressable, Text } from '@octane-xplat/ui'
+import { useRouter } from '@octane-xplat/ui/routing'
 
 export function SettingsLinks() {
-  const settings = { stack: 'root', name: 'settings', params: {} }
+  const navigation = useRouter()
   return <HStack>
-    <NavLink route={settings}><Text>Settings</Text></NavLink>
-    <Pressable onPress={() => pushRoute(settings)}><Text>Open settings</Text></Pressable>
+    <Pressable onPress={() => navigation.push({ to: '/items/:id', params: { id: '42' } })}>
+      <Text>Open item</Text>
+    </Pressable>
     <Link href="https://octane-xplat.goddardai.org"><Text>Documentation</Text></Link>
   </HStack>
 }
 ```
 
-Use `useRoute` to read the current screen and `useCanGoBack` to decide whether
-to offer a back button. Pass the same stack name to `popRoute`.
+`router.push` returns a result, not void: check `status === 'committed'`,
+then `await result.finished` only when animation settlement matters.
+`router.back()` pops one entry, `router.dismiss()` closes a modal,
+`useCanGoBack` gates a Back control, and `useRouterState()` reads the current
+route's declared `to` pattern. `router.navigateUrl(url)` admits an incoming
+absolute or relative URL.
 
 ```tsrx
+// src/NavigationStatus.tsrx
 import { Pressable, Text } from '@octane-xplat/ui'
-import { useRoute, useCanGoBack, popRoute } from '@octane-xplat/ui/routing'
+import { useCanGoBack, useRouter, useRouterState } from '@octane-xplat/ui/routing'
 
 export function NavigationStatus() {
-  const route = useRoute('root')
-  const canGoBack = useCanGoBack('root')
+  const navigation = useRouter()
+  const route = useRouterState().route
+  const canGoBack = useCanGoBack()
   return <>
-    <Text>{route?.name ?? 'Home'}</Text>
-    <Pressable disabled={!canGoBack} onPress={() => popRoute('root')}>
+    <Text>{route?.to ?? 'Home'}</Text>
+    <Pressable disabled={!canGoBack} onPress={() => navigation.back()}>
       <Text>Back</Text>
     </Pressable>
   </>
 }
 ```
 
-Prefer string IDs in route params: generated route helpers use string params,
-and IDs make URLs shareable. The low-level router JSON-encodes object params
-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:
+A guard runs in `beforeLoad` before the attempted route commits: return context
+values, `redirect({ to, params, search })`, or throw `RouteForbidden`. Type the
+args with the route's generated `RouteGuardArgs`:
 
-```ts
-import { pushRoute } from '@octane-xplat/ui/routing'
+```tsrx
+// src/app/items/[id].tsrx
+import { redirect } from '@octane-xplat/ui/routing'
+import type { RouteGuardArgs } from '../../routes.gen.contracts'
 
-pushRoute({ stack: 'root', name: 'projects/:id', params: { id: '42' } })
+export function beforeLoad({ params }: RouteGuardArgs<'/items/:id'>) {
+  if (params.id === 'old-coat') redirect({ to: '/items/:id', params: { id: 'coat' } })
+  return { checked: true }
+}
 ```
 
-Named tab stacks keep each tab's navigation separate. `Tabs` renders the tab's
-initial content; pushing a route into that stack opens it inside the tab pane.
-The screen below assumes `settings` is already registered.
+Prefer string IDs in params: generated contracts type params as strings and
+IDs make URLs shareable. Search is validated per route with `validateSearch`
+(return `as const`); screens update it with `useUpdateSearch()` inside a
+component via the route's `getRouteApi` accessor.
+
+```ts
+// src/app/items/[id].tsrx — search schema for the same route file
+export function validateSearch(raw: { tab?: unknown }) {
+  const tab = raw.tab ?? 'details'
+  if (tab !== 'details' && tab !== 'activity') {
+    throw new Error('Invalid tab')
+  }
+  return { tab } as const
+}
+```
 
 ```tsrx
-import { Tabs, Text, Pressable } from '@octane-xplat/ui'
-import { pushRoute } from '@octane-xplat/ui/routing'
-
-export function AppTabs() {
-  return <Tabs tabs={[
-    { title: 'Home', stack: 'home', render: () => <Text>Home</Text> },
-    { title: 'Account', stack: 'account', render: () =>
-      <Pressable onPress={() => pushRoute({ stack: 'account', name: 'settings', params: {} })}>
-        <Text>Settings</Text>
-      </Pressable> },
-  ]} />
+// src/ActivityFilter.tsrx
+import { Button } from '@octane-xplat/ui'
+import { getRouteApi } from '@octane-xplat/ui/routing'
+
+const item = getRouteApi('/items/:id')
+
+export function ActivityFilter() {
+  const updateSearch = item.useUpdateSearch()
+  return <Button label="Show activity" clickAction={() => {
+    void updateSearch(previous => ({ ...previous, tab: 'activity' }))
+  }} />
 }
 ```
 
-For loaders, deep links, route config, and generated route types, see the
-[navigation guide](https://octane-xplat.goddardai.org/navigation).
+Named stacks keep each tab's history separate: declare `"stacks": ["catalog",
+"account"]` in `xplat.routes.json`, render `Tabs`, and address a stack with
+`stack:` in the destination or `router.forStack(name)`:
+
+```ts
+await router.forStack('catalog').push({ to: '/items/:id', params: { id: 'coat' } })
+```
+
+`presentation: 'modal'` on a destination (or a `+modal` route-file suffix)
+opens an owned modal flow the host dismisses as one surface.
+
+For deep links, transitions, file-route details, and generated contracts, see
+the [navigation guide](https://octane-xplat.goddardai.org/navigation).

package/template/AGENTS.md

@@ -53,7 +53,7 @@ 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).
+[testing guide](https://octane-xplat.goddardai.org/testing#add-automated-tests).
 
 ## Stable automation targets
 
@@ -73,11 +73,11 @@ 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).
+promise platform support. See [qualified hosts and mappings](https://octane-xplat.goddardai.org/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)
+and the [qualified local recipe](https://octane-xplat.goddardai.org/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.

package/template/index.html

@@ -2,7 +2,7 @@
 <html lang="en">
 	<head>
 		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
 		<title>octane-xplat app</title>
 	</head>
 	<body>

package/template/package.json

@@ -26,7 +26,7 @@
 		"@octane-xplat/jsx": "catalog:xplat",
 		"@octane-xplat/platform": "catalog:xplat",
 		"@octane-xplat/ui": "catalog:xplat",
-		"@triniwiz/nativescript-masonkit": "catalog:xplat",
+		"@octane-xplat/nativescript-masonkit": "catalog:xplat",
 		"@valor/nativescript-websockets": "catalog:xplat",
 		"octane": "catalog:xplat"
 	},

package/template/pnpm-workspace.yaml

@@ -21,17 +21,17 @@ 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 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 0.14.0 still requires 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. Rebased against the registry 0.14.0 tarball,
+  # including local signal-hook registration in the split runtime/hooks modules. Provider
+  # null/undefined descendant cleanup is now upstream and no longer patched. Marks generic
+  # binding bags from bagOf so fragment commit rehomes their DOM parent references,
+  # preventing stale fragment parents, namespace recursion, and invalid insertion during
+  # typeahead updates.
+  octane@0.14.0: node_modules/.pnpm-config/@octane-xplat/patches/patches/octane@0.14.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
@@ -45,58 +45,53 @@ patchedDependencies:
   # _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
+  # Remaining dev-server fixes on @nativescript/vite 8.0.20: collect re-export specifiers in
+  # the .vite/deps rewrite; route outside-roots /@fs paths through /ns/m; probe non-active
+  # platform and native suffixes; redirect bare octane to octane/universal/native in
+  # deps-bundle esbuild passes; add .mobile to tsconfig-paths and generated checker
+  # suffixes; scan the app-local pnpm virtual store for served node_modules URLs; ignore
+  # per-package turbo.json as workspace markers; resolve # package-imports specifiers in
+  # served-module rewrites; preserve, compile, and hot-update virtual stylesheets
+  # (NativeScript#11551); and inspect ESM export declarations/specifiers for native
+  # default-import validation instead of matching comments, strings, or a narrow export
+  # syntax (NativeScript#11566). Shared-source graph and hot-context IDs now use the same
+  # app/workspace/@fs paths as served imports, preserving distinct roots
+  # (NativeScript#11569); extensionless workspace requests probe filesystem-anchored
+  # extension/platform candidates so hot reimports can fetch shared modules
+  # (NativeScript#11570). Linked-checkout discovery and candidate anchoring shipped in
+  # 8.0.20 (NativeScript#11559), so those local hunks are removed.
+  "@nativescript/vite@8.0.20": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript__vite@8.0.20.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.
+  # Synced with PR #14: registered setters are identified before resetting (ordinary fields
+  # never receive the sentinel), inline removal refreshes matching class CSS through the
+  # isolated core 9.1 `_cssState.onChange` hook, CSS variables use public removal, strings
+  # use the core CSS parser, and replacement views capture fresh defaults. 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; foreign native leaves mirror resolved class and inline layout
+  # styles through Style.fromView, observe longhand changes and native recreation, and
+  # explicitly clear removed placement — removal restores the CSS cascade, so a later
+  # sibling attachment cannot resurrect removed tracks. Container alignment uses the core
+  # stretch default without a local style override, allowing class-authored centering.
+  # Inline style resets reapply the matching CSS cascade. Re-exports Octane's ClassValue
+  # unchanged and stringifies truthy numeric class values while omitting 0 and NaN, matching
+  # Octane 0.11.
   "@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.
+  # delivered updates. Includes shared script sources in transaction ordering while
+  # excluding dependencies, tests and declarations. External-source edits use the absolute
+  # source for graph identity and a Vite /@fs transform URL instead of treating
+  # parent-relative paths as app URLs.
   "@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
@@ -120,32 +115,26 @@ patchedDependencies:
   # 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
+  # shaders@4.0.0 inlines TypeGPU 0.12.3 into dist/core/std-ClftfWpF.js, which declares
+  # /\p{XID_Start}/ and /\p{XID_Continue}/ regex literals at module scope (WGSL identifier
+  # validation, external prop-chain matching, minify separator check). NativeScript's
+  # embedded V8 on iOS (@nativescript/ios 9.1.0) and Android (@nativescript/android 9.1.1,
+  # V8 14.9.207.39) is built without ICU — every \p{…} escape is a SyntaxError, even in a
+  # never-called function, so a literal fails the whole module at parse time and any bundled
+  # app importing `shaders/js` dies on boot. Rewriting to \p{ID_Start}/\p{L} would not help
+  # — all property escapes are rejected. The patch builds the regexes via try/catch new
+  # RegExp with ASCII/non-ASCII-range fallbacks — byte-identical .source where ICU exists.
+  # dist/js/bundle.js, react/bundle.js, and cli.js carry the same escapes but are
+  # unreachable from `shaders/js` and left unpatched.
+  shaders@4.0.0: node_modules/.pnpm-config/@octane-xplat/patches/patches/shaders@4.0.0.patch
 configDependencies:
-  "@octane-xplat/patches": 0.16.0
+  "@octane-xplat/patches": 0.17.0
 catalogs:
   xplat:
     "@nativescript-community/octane": 0.2.5
@@ -155,19 +144,19 @@ catalogs:
     "@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.16.0
-    "@octane-xplat/jsx": 0.16.0
-    "@octane-xplat/platform": 0.16.0
-    "@octane-xplat/ui": 0.16.0
+    "@nativescript/vite": 8.0.20
+    "@octane-xplat/cli": 0.17.0
+    "@octane-xplat/jsx": 0.17.0
+    "@octane-xplat/nativescript-masonkit": 1.0.0-beta.126
+    "@octane-xplat/platform": 0.17.0
+    "@octane-xplat/ui": 0.17.0
     "@octanejs/vite-plugin": 0.1.61
-    "@triniwiz/nativescript-masonkit": 1.0.0-beta.110
     "@tsrx/oxc": 0.20.0
     "@tsrx/typescript-plugin": 0.4.11
     "@valor/nativescript-websockets": 2.0.3
     jsdom: 30.1.1
     nativescript: 9.1.1
-    octane: 0.11.0
+    octane: 0.14.0
     typescript: 5.9.3
     vite: 8.3.0
     vitest: 4.1.11

package/template/src/App.tsrx

@@ -1,5 +1,5 @@
 import { useState } from 'octane';
-import { View, HStack, Text, Pressable, ScrollableArea, useColorScheme } from '@octane-xplat/ui';
+import { View, HStack, Text, Pressable, ScrollableArea, SafeArea, useColorScheme } from '@octane-xplat/ui';
 import { storage } from '@octane-xplat/platform';
 
 const FEATURES = [
@@ -23,26 +23,28 @@ export function App() @{
 	const scheme = useColorScheme();
 	const dark = override ?? scheme === 'dark';
 
-	<View className={['app', dark ? 'dark' : 'light']}>
-		<Text className="title">octane-xplat</Text>
-		<Text className="muted">one codebase — web · iOS · android</Text>
+	<SafeArea>
+		<View className={['app', dark ? 'dark' : 'light']}>
+			<Text className="title">octane-xplat</Text>
+			<Text className="muted">one codebase — web · iOS · android</Text>
 
-		<HStack className="counter">
-			<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>
+			<HStack className="counter">
+				<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>
+			<ScrollableArea>
+				{FEATURES.map((f) => <Text className="chip">{f}</Text>)}
+			</ScrollableArea>
 
-		<Pressable testID="settings.toggle-theme" className="link" onPress={() => {
-			const next = !dark;
-			storage.setString('theme-preference', next ? 'dark' : 'light');
-			setOverride(next);
-		}}>
-			<Text>{dark ? 'light' : 'dark'} mode (system: {scheme})</Text>
-		</Pressable>
-	</View>
+			<Pressable testID="settings.toggle-theme" className="link" onPress={() => {
+				const next = !dark;
+				storage.setString('theme-preference', next ? 'dark' : 'light');
+				setOverride(next);
+			}}>
+				<Text>{dark ? 'light' : 'dark'} mode (system: {scheme})</Text>
+			</Pressable>
+		</View>
+	</SafeArea>
 }

package/template/src/main.ts

@@ -2,18 +2,18 @@
 // different shell: a Frame hosting a Page that renders the universal root.
 import { Application, Frame, Page } from '@nativescript/core'
 import { renderNativeScriptApp } from '@nativescript-community/octane'
+import { prepareFullScreenPage } from '@octane-xplat/ui/nativescript'
 import { App } from './App.tsrx'
 import '@octane-xplat/ui/theme/tokens.css'
 import './style.css'
 
 const entry = {
 	create: () => {
-		// Root is a Frame so pushRoute() can push Pages later — a Frame
-		// window root doubles as the 'root' stack with no registration;
-		// named stacks come from TabSpec.stack or registerStack. Route
-		// pushes also need registerScreens({name: Component}) at boot.
+		// A Frame hosts the root Page. RouteOutlet binds canonical routing
+		// to this Frame when the app adds generated routes.
 		const frame = new Frame()
-		const page = new Page()
+		// Full-screen page: SafeArea owns safe-area padding.
+		const page = prepareFullScreenPage(new Page())
 		page.actionBarHidden = true
 		renderNativeScriptApp(page, App)
 		frame.navigate({ create: () => page })