create-octane-xplat 0.1.0 → 0.4.0

package/template/patches/@nativescript__vite@8.0.11.patch

@@ -0,0 +1,294 @@
+diff --git a/hmr/server/core-bundle.js b/hmr/server/core-bundle.js
+index 993097b9d861a2a7c477f4e664213efec3eb6293..7a9b95180cbd47e1d9c71180bc4582a450333a7c 100644
+--- a/hmr/server/core-bundle.js
++++ b/hmr/server/core-bundle.js
+@@ -607,17 +607,32 @@ export function buildCoreMainShimCode() {
+  * class/function values. `exportNames` comes from the same disk-based export
+  * discovery the per-module bridge relies on (collectStaticExportNamesFromFile).
+  */
+-const RESERVED_EXPORT_NAMES = new Set(['default', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'let', 'static', 'yield', 'await', 'eval', 'arguments', '__ns_core_sub_ns__']);
++// `default` is emitted separately (below); `__ns_core_sub_ns__` is this shim's
++// own local — a module exporting that name can't collide with it.
++const NON_DECLARABLE_EXPORT_NAMES = new Set(['default', '__ns_core_sub_ns__']);
++// Reserved words can't be declaration bindings (`export const enum` is a
++// syntax error), but they ARE legal export names — the specifier position in
++// `export { x as name }` accepts any IdentifierName. Emit those through a
++// temp + alias so a reserved-word export (zod's `enum`/`catch`/… shapes this
++// same code path) still reaches the bridged namespace.
++const RESERVED_EXPORT_NAMES = new Set(['break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'let', 'static', 'yield', 'await', 'eval', 'arguments']);
+ export function buildCoreSubShimCode(sub, exportNames, hasOwnDefaultExport = false) {
+     const canonical = normalizeCoreSub(sub);
+     const registryKey = `@nativescript/core/${canonical}`;
+-    const names = Array.from(new Set(exportNames)).filter((n) => /^[A-Za-z_$][\w$]*$/.test(n) && !RESERVED_EXPORT_NAMES.has(n));
++    const names = Array.from(new Set(exportNames)).filter((n) => /^[A-Za-z_$][\w$]*$/.test(n) && !NON_DECLARABLE_EXPORT_NAMES.has(n));
+     const lines = [];
+     lines.push(`/* @nativescript/core bridge (bundle mode) — sub: ${canonical} */`);
+     lines.push(`import ${JSON.stringify(CORE_BUNDLE_PATH)};`);
+     lines.push(`const __ns_core_sub_ns__ = (globalThis.__NS_CORE_MODULES__ || {})[${JSON.stringify(registryKey)}];`);
+     lines.push(`if (!__ns_core_sub_ns__) { throw new Error(${JSON.stringify(`[ns-core] core bundle registry missing '${registryKey}' — restart the dev server or set NS_CORE_PER_MODULE=1`)}); }`);
++    let aliasIdx = 0;
+     for (const name of names) {
++        if (RESERVED_EXPORT_NAMES.has(name)) {
++            const alias = `__ns_core_alias_${aliasIdx++}`;
++            lines.push(`const ${alias} = __ns_core_sub_ns__[${JSON.stringify(name)}];`);
++            lines.push(`export { ${alias} as ${name} };`);
++            continue;
++        }
+         lines.push(`export const ${name} = __ns_core_sub_ns__.${name};`);
+     }
+     // Deep-subpath contract (see isDeepCoreSubpath / per-module bridge): a sub
+diff --git a/hmr/server/deps-bundle.js b/hmr/server/deps-bundle.js
+index 50e5abddddf80b35044d45eb108a64dd175bf6e7..799c7257a8a730515633f19f6221ad26ff8678eb 100644
+--- a/hmr/server/deps-bundle.js
++++ b/hmr/server/deps-bundle.js
+@@ -219,8 +219,37 @@ function isPackageRootSpec(spec) {
+         return false;
+     return pkgSub.split('/').length === (pkgSub.startsWith('@') ? 2 : 1);
+ }
+-function resolveSpecToFile(spec, projectRoot, workspaceRoot, platform) {
++/**
++ * `/node_modules/<pkg>/<sub...>` → the exports-mapped file on disk
++ * (`rouzer/http` → `rouzer/dist/http.js`). Without this, non-root specs fall
++ * back to `resolveId` and land on Vite's dep-optimizer artifacts under
++ * `.vite/deps/` — flat bundles whose generated shared chunks
++ * (`foo-<hash>.js`) this pipeline cannot serve to the device.
++ */
++function resolvePackageSubpathFromSpecRoots(spec, roots, platform) {
++    const pkgSub = spec.replace(/^\/node_modules\//, '');
++    const parts = pkgSub.split('/');
++    const nameSegs = parts[0].startsWith('@') ? 2 : 1;
++    if (parts.length <= nameSegs)
++        return null;
++    const subpath = parts.slice(nameSegs).join('/');
++    for (const root of roots) {
++        const pkgDir = path.join(root, 'node_modules', ...parts.slice(0, nameSegs));
++        if (!existsSync(path.join(pkgDir, 'package.json')))
++            continue;
++        const resolved = resolvePackageSubpathEntry(pkgDir, subpath, platform);
++        if (resolved)
++            return resolved;
++    }
++    return null;
++}
++export function resolveSpecToFile(spec, projectRoot, workspaceRoot, platform) {
+     const roots = [projectRoot, ...(workspaceRoot && path.resolve(workspaceRoot) !== path.resolve(projectRoot) ? [workspaceRoot] : [])];
++    // `.vite/` is Vite's dep-optimizer store — generated artifacts with
++    // content-hashed names, not package files. Resolving them here would mint
++    // deps-bundle entries/shims for files whose names churn per optimization.
++    if (spec.includes('/.vite/'))
++        return null;
+     // Package roots honor the declared entry (exports/module/main) FIRST —
+     // matching esbuild's resolution of bare imports inside the bundle. The
+     // index fan-out would otherwise pick stray root files like a shipped
+@@ -236,6 +265,12 @@ function resolveSpecToFile(spec, projectRoot, workspaceRoot, platform) {
+         if (abs)
+             return abs;
+     }
++    // Non-root specs (`rouzer/http`, `qubu/sqlite`): consult the package's
++    // exports map so the real dist file wins — the alternative downstream is
++    // the dep optimizer's `.vite/deps` artifact, whose sibling chunks 404.
++    const subpathEntry = resolvePackageSubpathFromSpecRoots(spec, roots, platform);
++    if (subpathEntry)
++        return subpathEntry;
+     return isPackageRootSpec(spec) ? null : resolvePackageRootEntry(spec, roots, platform);
+ }
+ // Never bundled: `@nativescript/core` belongs to the /ns/core bridge realm,
+@@ -869,7 +904,15 @@ export function collectDepsModuleExportInfo(absPath, platform, seen = new Set())
+     names.delete('default');
+     return { names: Array.from(names).sort(), hasDefault: hasExistingDefaultExport(code) };
+ }
+-const RESERVED_EXPORT_NAMES = new Set(['default', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'let', 'static', 'yield', 'await', 'eval', 'arguments', '__ns_dep_ns__']);
++// `default` is emitted separately (below); `__ns_dep_ns__` is this shim's own
++// local — a package exporting that name can't collide with it.
++const NON_DECLARABLE_EXPORT_NAMES = new Set(['default', '__ns_dep_ns__']);
++// Reserved words can't be declaration bindings (`export const enum` is a
++// syntax error), but they ARE legal export names — the specifier position in
++// `export { x as name }` accepts any IdentifierName. Emit those through a
++// temp + alias so packages like zod (`enum`, `catch`, `function`, …) keep
++// their full surface on the bridged namespace.
++const RESERVED_EXPORT_NAMES = new Set(['break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'let', 'static', 'yield', 'await', 'eval', 'arguments']);
+ /**
+  * Shim served at `/ns/m/node_modules/...` for a bundled module. The static
+  * bundle import guarantees the registry is populated before the body reads it
+@@ -880,13 +923,20 @@ const RESERVED_EXPORT_NAMES = new Set(['default', 'break', 'case', 'catch', 'cla
+ export function buildDepsShimCode(key, exportNames, hasOwnDefaultExport) {
+     // JS_IDENTIFIER_RE (not ASCII \w): Angular exports `ɵɵdefineInjectable`-style
+     // names — dropping them here breaks every `import * as i0` consumer.
+-    const names = Array.from(new Set(exportNames)).filter((n) => JS_IDENTIFIER_RE.test(n) && !RESERVED_EXPORT_NAMES.has(n));
++    const names = Array.from(new Set(exportNames)).filter((n) => JS_IDENTIFIER_RE.test(n) && !NON_DECLARABLE_EXPORT_NAMES.has(n));
+     const lines = [];
+     lines.push(`/* ns-deps bridge (bundle mode) — ${key} */`);
+     lines.push(`import ${JSON.stringify(DEPS_BUNDLE_PATH)};`);
+     lines.push(`const __ns_dep_ns__ = (globalThis.__NS_DEPS_MODULES__ || {})[${JSON.stringify(key)}];`);
+     lines.push(`if (!__ns_dep_ns__) { throw new Error(${JSON.stringify(`[ns-deps] deps bundle registry missing '${key}' — restart the dev server or set NS_DEPS_PER_MODULE=1`)}); }`);
++    let aliasIdx = 0;
+     for (const name of names) {
++        if (RESERVED_EXPORT_NAMES.has(name)) {
++            const alias = `__ns_dep_alias_${aliasIdx++}`;
++            lines.push(`const ${alias} = __ns_dep_ns__[${JSON.stringify(name)}];`);
++            lines.push(`export { ${alias} as ${name} };`);
++            continue;
++        }
+         lines.push(`export const ${name} = __ns_dep_ns__.${name};`);
+     }
+     if (hasOwnDefaultExport) {
+diff --git a/hmr/server/device-transform-helpers.js b/hmr/server/device-transform-helpers.js
+index 9364ce9942b84fffd0e3a6eb6700d8253fa66e7e..93ee2bf2570303277d7b4350018b00fbbb31e2a4 100644
+--- a/hmr/server/device-transform-helpers.js
++++ b/hmr/server/device-transform-helpers.js
+@@ -81,12 +81,18 @@ function bareSpecifierFromFlatDepPath(depPath) {
+         }
+         catch { }
+     }
+-    const bareSpecifier = resolved || candidates[0];
++    // Unverified decode → NOT a package: `depPath` is a generated optimizer
++    // artifact (a hash-named shared chunk like `http-Dm_BQhab.js`, whose
++    // base64url '_' decodes to a bogus '/'). Returning null lets the caller
++    // keep the real `.vite/deps` URL instead of emitting a garbage specifier.
++    if (!resolved) {
++        return null;
++    }
+     if (!warnedVendorMisses.has(depPath)) {
+         warnedVendorMisses.add(depPath);
+-        console.warn(`[ns-vite] vendor-manifest miss: prebundled dep '${depPath}' is not in the vendor bundle — serving '${bareSpecifier}' over HTTP via /ns/m/node_modules/${resolved ? '' : ' (could not verify the package on disk; the specifier is a best-effort decode of the flattened id)'}.`);
++        console.warn(`[ns-vite] vendor-manifest miss: prebundled dep '${depPath}' is not in the vendor bundle — serving '${resolved}' over HTTP via /ns/m/node_modules/${resolved}.`);
+     }
+-    return bareSpecifier;
++    return resolved;
+ }
+ function rewriteVitePrebundleImportsForDevice(code, preserveVendorImports) {
+     const imports = collectTopLevelImportRecords(code);
+@@ -111,6 +117,15 @@ function rewriteVitePrebundleImportsForDevice(code, preserveVendorImports) {
+             if (bareSpecifier) {
+                 replacement = imp.text.replace(source, bareSpecifier);
+             }
++            else {
++                // Generated optimizer chunk (hash-named sibling of an
++                // optimized entry) — not a package and not decodable to one.
++                // Route the real artifact URL back through the bridge: the
++                // /ns/m route serves it from the dep-optimizer store (the
++                // `?v` stamp rides along as forcedVer) or emits an
++                // actionable optimizeDeps.exclude error.
++                replacement = imp.text.replace(source, `/ns/m/node_modules/.vite/deps/${depPath}`);
++            }
+         }
+         edits.push({
+             start: imp.start,
+diff --git a/hmr/server/websocket-ns-m-request.js b/hmr/server/websocket-ns-m-request.js
+index b54aefcc839e95906d76d02e522c052a706ca76f..d49159de94ba05dcfc372aa7a3c513e0f5c0a0d3 100644
+--- a/hmr/server/websocket-ns-m-request.js
++++ b/hmr/server/websocket-ns-m-request.js
+@@ -1,6 +1,9 @@
+ import * as path from 'path';
++import { realpathSync } from 'fs';
+ import { filterExistingNodeModulesTransformCandidates, getBlockedDeviceNodeModulesReason, resolveCandidateFilePath, tryReadRawExplicitJavaScriptModule } from './websocket-module-specifiers.js';
+ import { collapseLegacyNsMTags } from './websocket-ns-m-paths.js';
++import { resolveSpecToFile } from './deps-bundle.js';
++import { resolvePlatform } from '../../helpers/cli-flags.js';
+ function normalizeAbsoluteFilesystemSpec(spec, serverRoot) {
+     const toPosix = (value) => value.replace(/\\/g, '/');
+     const rootPosix = toPosix(serverRoot);
+@@ -93,6 +96,29 @@ export function createNsMRequestContext(requestUrl, serverRoot, appVirtualWithSl
+         return { kind: 'next' };
+     }
+ }
++/**
++ * Canonical request URL for a resolved node_modules file. Project-root files
++ * keep the `/node_modules/...` form so module identity matches the /ns/m
++ * spec space; files outside the project root (hoisted/workspace) use the
++ * `/@fs` form Vite can load directly. Symlinked workspace-source packages
++ * resolve to their realpath so the TS transform applies — same policy as
++ * filterExistingNodeModulesTransformCandidates.
++ */
++function nodeModulesFileToRequestUrl(absPath, serverRoot) {
++    try {
++        const real = realpathSync(absPath);
++        if (real !== absPath && !real.split(path.sep).includes('node_modules')) {
++            return `/@fs${real.replace(/\\/g, '/')}`;
++        }
++    }
++    catch { }
++    const rootPosix = path.resolve(serverRoot).replace(/\\/g, '/').replace(/\/+$/, '');
++    const absPosix = absPath.replace(/\\/g, '/');
++    if (absPosix.startsWith(`${rootPosix}/`)) {
++        return absPosix.slice(rootPosix.length);
++    }
++    return `/@fs${absPosix}`;
++}
+ async function tryTransformRequest(transformRequest, url, timeoutMs) {
+     try {
+         return await transformRequest(url, timeoutMs);
+@@ -146,6 +172,38 @@ export async function resolveNsMTransformedModule(options) {
+             return { transformed, resolvedCandidate };
+         }
+     }
++    // Optimizer-artifact requests (`/node_modules/.vite/deps/<file>`): flat
++    // entries and hash-named shared chunks live in the dep-optimizer's store
++    // (often memory-only), keyed by the `?v=<browserHash>` stamp Vite emits —
++    // captured inbound as `forcedVer`. Replay it so Vite resolves the artifact
++    // as-is; a miss falls through to the route's transform-miss branch, which
++    // names optimizeDeps.exclude as the fix.
++    if (spec.includes('/.vite/deps/')) {
++        const depUrl = context.forcedVer ? `${spec}?v=${context.forcedVer}` : spec;
++        transformed = await tryTransformRequest(transformRequest, depUrl, timeoutMs);
++        if (transformed?.code) {
++            return { transformed, resolvedCandidate: depUrl };
++        }
++        return { transformed: null, resolvedCandidate };
++    }
++    // Bare or subpath node_modules specs (`rouzer/http`, `qubu/sqlite`) that
++    // survive the on-disk candidate fan-out would otherwise hit `resolveId`
++    // and land on Vite's dep-optimizer output: `/node_modules/.vite/deps/
++    // <flat>.js` bundles whose generated sibling chunks (`foo-<hash>.js`)
++    // this pipeline cannot serve — and whose flattened ids decode to bogus
++    // bare specifiers downstream (`http-Dm/BQhab`). Prefer the real package
++    // file (exports-map aware) so the device gets the same per-module source
++    // an `optimizeDeps.exclude` entry produces.
++    if (spec.includes('/node_modules/')) {
++        const realFile = resolveSpecToFile(spec.slice(spec.lastIndexOf('/node_modules/')), serverRoot, workspaceRoot, resolvePlatform() || 'ios');
++        const realUrl = realFile ? nodeModulesFileToRequestUrl(realFile, serverRoot) : null;
++        if (realUrl) {
++            transformed = await tryTransformRequest(transformRequest, realUrl, timeoutMs);
++            if (transformed?.code) {
++                return { transformed, resolvedCandidate: realUrl };
++            }
++        }
++    }
+     const resolvedId = await resolveId(spec);
+     if (resolvedId) {
+         transformed = await tryTransformRequest(transformRequest, resolvedId, timeoutMs);
+diff --git a/hmr/server/websocket-ns-m.js b/hmr/server/websocket-ns-m.js
+index 8eeb51ab59497e7f775da3117c4207e05f1814c7..346b676fbb67ce6bebe81cc379fdbe0d0aeac876 100644
+--- a/hmr/server/websocket-ns-m.js
++++ b/hmr/server/websocket-ns-m.js
+@@ -265,6 +265,30 @@ export function registerNsModuleServerRoute(server, options) {
+             catch { }
+             // If transformRequest failed, handle bare-module vendor shims for 'vue' and 'pinia'
+             if (!transformed?.code) {
++                // Dep-optimizer artifacts (`.vite/deps` entries + generated
++                // shared chunks) aren't package files — when one reaches the
++                // bridge unserved, the fix is keeping that dep out of
++                // optimizeDeps. Name the optimized set so the on-device
++                // error is actionable instead of a generic transform miss.
++                if (spec.includes('/.vite/deps/')) {
++                    const optimizedIds = [];
++                    try {
++                        for (const env of Object.values(server.environments || {})) {
++                            const meta = env?.depsOptimizer?.metadata;
++                            for (const record of [meta?.optimized, meta?.discovered]) {
++                                if (record)
++                                    optimizedIds.push(...Object.keys(record));
++                            }
++                        }
++                    }
++                    catch { }
++                    const hint = optimizedIds.length
++                        ? ` Currently optimized: ${Array.from(new Set(optimizedIds)).join(', ')} — add the package that pulls in this chunk to optimizeDeps.exclude in the native vite config (or restart with NS_DEPS_PER_MODULE=1).`
++                        : ' Add the importing package to optimizeDeps.exclude in the native vite config.';
++                    res.statusCode = 404;
++                    res.end(`throw new Error(${JSON.stringify(`[ns/m] Vite optimizeDeps artifact '${spec}' is not servable on device — its shared chunks are generated files outside the package tree.${hint}`)});\nexport {};\n`);
++                    return;
++                }
+                 const bare = spec.startsWith('/') ? spec.slice(1) : spec;
+                 const isBare = bare && !bare.includes('/') && !/\.(ts|tsx|js|jsx|mjs|mts|cts|vue)$/i.test(bare);
+                 if (isBare && (bare === 'vue' || bare === 'nativescript-vue' || bare === 'pinia')) {

package/template/pnpm-workspace.yaml

@@ -1,7 +1,29 @@
 # pnpm 11 settings live here, not in package.json.
-# esbuild needs its install script to place the platform binary.
-# @nativescript/core lands via optional peers — its scripts are native
-# toolchain prep the ns CLI does itself; skipping keeps installs clean.
+#
+# nodeLinker hoisted: Node ESM resolves package imports relative to the
+# symlink path (node_modules/octane/...), not the realpath — so octane's
+# transitive deps (@tsrx/core etc.) must sit at top-level node_modules.
+# NativeScript's bundler wants a flat tree for the same reason.
+nodeLinker: hoisted
+#
+# esbuild + @parcel/watcher need install scripts to place binaries;
+# nativescript's postinstall sets up the local CLI. @nativescript/core's
+# scripts are native toolchain prep the ns CLI does itself.
 allowBuilds:
   esbuild: true
+  '@parcel/watcher': true
+  nativescript: true
   '@nativescript/core': false
+#
+# vite-octane's octaneServerStrategy early-returns for `.tsrx` files (its
+# SCRIPT_FILE_RE only covers [jt]sx?), so component edits never emit the
+# deferred ns:hmr-delta broadcast — on-device HMR looks dead. The patch also
+# counts open /ns-hmr sockets so `recipients=N` in update logs is real.
+# Drop once a release carries the fix.
+patchedDependencies:
+  '@nativescript-community/vite-octane@0.2.1': patches/@nativescript-community__vite-octane@0.2.1.patch
+  # Dep/core shims dropped reserved-word named exports (zod's `enum`, `catch`,
+  # `function`, …) because `export const enum` is a syntax error — emit them
+  # via temp+alias so bridged namespaces keep their full surface. Without it,
+  # any app importing such a dep fails module eval on boot/graph-reload.
+  '@nativescript/vite@8.0.11': patches/@nativescript__vite@8.0.11.patch

package/template/references.d.ts

@@ -0,0 +1 @@
+/// <reference types="@nativescript/types" />

package/template/src/App.tsrx

@@ -13,10 +13,12 @@ const FEATURES = [
  *  (.web.tsrx / .native.tsrx), never inside a component. */
 export function App() @{
 	const [count, setCount] = useState(0);
-	const [dark, setDark] = useState(false);
+	// null = follow the system; the toggle overrides it for this session.
+	const [override, setOverride] = useState<boolean | null>(null);
 	const scheme = useColorScheme();
+	const dark = override ?? scheme === 'dark';
 
-	<View className={['app', dark ? 'dark' : '']}>
+	<View className={['app', dark ? 'dark' : 'light']}>
 		<Text className="title">octane-xplat</Text>
 		<Text className="muted">one codebase — web · iOS · android</Text>
 
@@ -28,7 +30,7 @@ export function App() @{
 
 		<List items={FEATURES} renderItem={(f) => <Text className="chip">{f}</Text>} />
 
-		<Pressable className="link" onPress={() => setDark(!dark)}>
+		<Pressable className="link" onPress={() => setOverride(!dark)}>
 			<Text>{dark ? 'light' : 'dark'} mode (system: {scheme})</Text>
 		</Pressable>
 	</View>

package/template/src/index.native.ts

@@ -0,0 +1,33 @@
+// Native entry — the iOS/Android twin of main.web.tsrx. Same App.tsrx,
+// 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 { 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.
+		const frame = new Frame()
+		const page = new Page()
+		page.actionBarHidden = true
+		renderNativeScriptApp(page, App)
+		frame.navigate({ create: () => page })
+		return frame
+	},
+}
+
+// Under the vite dev session the placeholder bootstrap has already run
+// Application.run(), and a module-graph reload re-evaluates this entry.
+// Android's run() throws "Application is already started" on re-entry
+// (iOS core handles the placeholder handoff internally); resetRootView is
+// the documented way to swap the root of a running app.
+if (Application.started) {
+	Application.resetRootView(entry)
+} else {
+	Application.run(entry)
+}

package/template/src/style.css

@@ -6,6 +6,25 @@
 body {
 	margin: 0;
 	font-family: system-ui, sans-serif;
+	background-color: var(--color-surface);
+}
+
+/* System-dark before JS mounts — no white flash. Same values tokens.css
+ * sets under .dark; .app.light below is the manual override back. */
+@media (prefers-color-scheme: dark) {
+	:root {
+		--color-surface: #0f172a;
+		--color-text: #f8fafc;
+	}
+	body {
+		background-color: var(--color-surface);
+	}
+}
+
+/* Manual light override when the system is dark (JS adds .light). */
+.app.light {
+	--color-surface: #ffffff;
+	--color-text: #111827;
 }
 
 .app {
@@ -49,6 +68,7 @@ body {
 	color: var(--color-on-primary);
 	padding: 10px 20px;
 	border-radius: 10px;
+	corner-shape: squircle;
 	font-size: 20px;
 }
 
@@ -57,6 +77,7 @@ body {
 	color: var(--color-on-primary);
 	padding: 6px 14px;
 	border-radius: 14px;
+	corner-shape: squircle;
 	font-size: 14px;
 }
 

package/template/tsconfig.json

@@ -10,7 +10,9 @@
 		"customConditions": ["web"],
 		"lib": ["ESNext", "DOM", "DOM.Iterable"],
 		"types": ["vite/client"],
-		"noEmit": true
+		"noEmit": true,
+		"skipLibCheck": true
 	},
-	"include": ["src/**/*"]
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "src/index.native.ts"]
 }

package/template/tsconfig.native.json

@@ -0,0 +1,18 @@
+{
+	"compilerOptions": {
+		"strict": true,
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"jsx": "preserve",
+		"jsxImportSource": "@nativescript-community/octane",
+		"moduleSuffixes": [".ios", ".android", ".native", ""],
+		"customConditions": ["native"],
+		"lib": ["ESNext"],
+		"types": ["@nativescript/types"],
+		"noEmit": true,
+		"skipLibCheck": true
+	},
+	"include": ["src/**/*", "references.d.ts"],
+	"exclude": ["node_modules", "platforms", "**/*.web.*"]
+}

package/template/vite.config.native.mts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vite'
+import { xplatNative } from '@octane-xplat/cli/vite'
+
+// The shared preset owns the renderer rules, octane→universal/native alias,
+// suffix extension chain, deps-bundle plugin exclusions, the HMR watchdog,
+// and the px→dip CSS rewrite. App-specific additions go through the second
+// argument's `extra` (or mergeConfig).
+export default defineConfig(({ mode }) => xplatNative(mode))

package/template/vite.config.ts

@@ -1,5 +1,5 @@
-import { defineConfig } from 'vite';
-import { octane } from '@octanejs/vite-plugin';
+import { defineConfig } from 'vite'
+import { octane } from '@octanejs/vite-plugin'
 
 // The web build. For native (iOS/Android), the same source runs through
 // @nativescript-community/vite-octane with `conditions: ['native']` and the
@@ -12,10 +12,17 @@ export default defineConfig({
 		conditions: ['web'],
 		// Suffix chain (first match wins): .web → shared → fallback.
 		extensions: [
-			'.web.tsrx', '.tsrx',
-			'.web.tsx', '.tsx',
-			'.web.ts', '.mjs', '.mts', '.ts',
-			'.jsx', '.js', '.json',
+			'.web.tsrx',
+			'.tsrx',
+			'.web.tsx',
+			'.tsx',
+			'.web.ts',
+			'.mjs',
+			'.mts',
+			'.ts',
+			'.jsx',
+			'.js',
+			'.json',
 		],
 	},
-});
+})