create-octane-xplat 0.7.3 → 0.10.0

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

@@ -1,45 +1,84 @@
-# Platform services + writing leaves
+# Platform services and platform files
 
-## `@octane-xplat/platform` — device services
+Use `@octane-xplat/platform` for common device services such as storage,
+clipboard, permissions, connectivity, app lifecycle, URLs, and screen size.
+Clipboard operations can fail or be unavailable; show a useful result.
 
-Import a capability through the package barrel. The unsuffixed module is its
-native default, `.web` is the browser implementation, and `.mobile` or an OS
-suffix narrows behavior when needed. Surface: `device`, `appInfo`, `locale`,
-`connectivity`, `useWindowSize`, `useAppState`, `useSafeAreaInsets`, deep
-links, clipboard, `secureStorage`, haptics, notifications, `announce`,
-`systemBars`, geolocation, permissions, media, files, share, `openUrl`,
-`openSettings`, biometrics.
+```tsrx
+import { useState } from 'octane'
+import { clipboard } from '@octane-xplat/platform'
+import { Pressable, Text } from '@octane-xplat/ui'
 
-Services report honestly — `biometrics` returns `unsupported` on web rather
-than faking a result. Handle the tier your app can fall back to instead of
-assuming success.
+export function CopyTrip() {
+  const [message, setMessage] = useState('Copy trip link')
+  return <Pressable onPress={async () => {
+    const copied = await clipboard.writeText('https://example.com/trips/42')
+    setMessage(copied ? 'Copied' : 'Copy unavailable')
+  }}><Text>{message}</Text></Pressable>
+}
+```
+
+Features with additional native dependencies live in separate packages:
+`@octane-xplat/share`, `files`, `media`, `biometrics`, `geolocation`,
+`notifications`, `secure-storage`, and `haptics`. Install the package for the
+feature you need. Biometrics, for example, reports `unsupported` on web;
+check permission and availability before trying to verify someone.
 
-## Leaf files — your own divergence
+```tsrx
+import { useState } from 'octane'
+import { biometrics } from '@octane-xplat/biometrics'
+import { Pressable, Text } from '@octane-xplat/ui'
+
+export function UnlockTrip() {
+  const [message, setMessage] = useState('Unlock trip')
+  return <Pressable onPress={async () => {
+    const status = await biometrics.ensure()
+    if (status !== 'granted' || !biometrics.impl) {
+      setMessage('Use your password instead')
+      return
+    }
+    const verified = await biometrics.impl.verify('Unlock your trip')
+    setMessage(verified ? 'Unlocked' : 'Try again')
+  }}><Text>{message}</Text></Pressable>
+}
+```
 
-When a service doesn't exist yet or a visual behavior truly differs, split the
-file, not the JSX:
+## Write a platform file when behavior differs
+
+Split the file when a feature needs browser or OS APIs. Import the component
+without a suffix; the bundler selects the matching implementation.
 
 ```text
-src/parts/Scanner.tsrx          native default
-src/parts/Scanner.web.tsrx      browser implementation (camera via getUserMedia)
+src/parts/Scanner.web.tsrx      browser implementation
 src/parts/Scanner.mobile.tsrx   shared iOS/Android implementation
-src/parts/Scanner.ios.tsrx      iOS-only override
+src/parts/Scanner.ios.tsrx      iOS override
+src/parts/Scanner.tsrx          native default
+```
+
+```tsrx
+import { Scanner } from './parts/Scanner'
+
+export function ScanScreen() { return <Scanner /> }
+```
+
+Native JSX files start with the NativeScript 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 */
+import { Application } from '@nativescript/core'
+import { Pressable, Text } from '@octane-xplat/ui'
+
+export function Status() {
+  return <Pressable onPress={() => console.log(Application.hasLaunched())}>
+    <Text>Check app status</Text>
+  </Pressable>
+}
 ```
 
-Import the bare specifier (`./Scanner`); the bundler selects `.web` first on
-web and the most specific native variant on each OS. The `.mobile` variant
-overrides the unsuffixed native default on iOS and Android.
-
-Leaf rules:
-
-- Inside `.web.*`, DOM APIs are expected; NativeScript imports belong in
-  `.mobile.*`, `.ios.*`, `.android.*`, or the unsuffixed native default. If
-  browser code imports that default, add a `.web.*` sibling.
-- Never read app-level NativeScript globals (`Application.android.*`)
-  at module top — read them inside the call. Top-level reads crash cold start
-  before the app exists.
-- Native-specific `.tsrx` files containing JSX start with
-  `/** @jsxImportSource @nativescript-community/octane */` on line 1.
-- Deep imports under `@nativescript/core/ui/*` bundle as a second module
-  instance — import from `@nativescript/core` only.
-- `console.debug` doesn't exist on device — use `console.log`.
+Keep browser globals and DOM events in `.web.*` files. Do not import a second
+renderer or deep-import NativeScript UI modules. Use `console.log` for device
+logging. See the [platform services guide](https://octane-xplat.goddardai.org/platform-services)
+when choosing a service or fallback.

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

@@ -1,42 +1,95 @@
 # Styling
 
-Two channels, chosen by _when the value is known_:
+Use classes for static styling and inline style objects for values that change
+while the app runs. Put the CSS in `src/style.css` and the component in a
+`.tsrx` file.
 
-- `className` → CSS classes and design tokens. Use for anything static.
-- `style={{ ... }}` → inline object for runtime values: animated offsets,
-  measured sizes, state-driven opacity. Don't put static styles here.
+```css
+.trip-card {
+	padding: 16px;
+	border-radius: 12px;
+}
+```
 
-## The portable subset
+```tsrx
+import { View, Text } from '@octane-xplat/ui'
 
-Shared CSS compiles for both targets. The native build rewrites `px` →
-`dip` and warns on declarations it can't honor — `position: fixed`/`sticky`,
-`margin-*: auto`, `float`, `box-shadow`, `white-space: pre-wrap`. A warning
-means the property does nothing on native: restructure (flex alignment,
-`Absolute`, transforms) instead of suppressing it.
+export function TripCard(props: { opacity: number }) {
+  return <View className="trip-card" style={{ opacity: props.opacity }}>
+    <Text>Your next adventure</Text>
+  </View>
+}
+```
 
-NativeScript limits worth knowing before you design around them:
+## Shared CSS
 
-- A scroll container can't clip children to a parent's rounded corners —
-  inset separators/padding instead.
-- CSS transforms reach native views only through the `transform:`
-  shorthand — `transform: translateX(16) scaleX(0.95)`. For motion, prefer
-  `useAnimation`, which composes this per platform.
+Shared CSS compiles for web and native. Prefer flex layouts, padding, and
+supported transforms. The native build warns when it drops declarations such
+as `position: fixed`, `margin: auto`, or `box-shadow`; resolve the warning
+before depending on that style.
+
+```css
+.trip-card {
+	display: flex;
+	flex-direction: column;
+	padding: 16px;
+}
+.trip-actions {
+	display: flex;
+	flex-direction: row;
+	justify-content: center;
+}
+```
 
 ## Tokens and dark mode
 
-`import '@octane-xplat/ui/theme/tokens.css'` (already in `main.web.tsrx`)
-provides color/spacing tokens and `--font-sans`/`--font-mono` fallbacks.
-The shipped utility classes (`flex-1`, `items-center`, `gap-*`, `rounded`,
-`text-*`, …) mirror Tailwind v4 names and scales — write them as you would
-Tailwind utilities.
+The starter imports the framework's tokens. They provide shared layout rules; the starter
+defines its app palette in `src/style.css`. Use the palette tokens in your CSS.
+
+```ts
+import '@octane-xplat/ui/theme/tokens.css'
+```
+
+```css
+.trip-card {
+	background-color: var(--color-surface);
+	color: var(--color-text);
+}
+```
+
+Use `useColorScheme()` to follow the system theme. Apply the matching class to
+the root so the token colors follow the theme; a user preference can override
+this in the starter's `src/App.tsrx`.
 
-Dark mode: `useColorScheme()` reads the system; the app's override pattern
-is in `src/App.tsrx` — hold `boolean | null` state, apply a `dark`/`light`
-class on the root, and let tokens switch underneath.
+```tsrx
+import { View, Text, useColorScheme } from '@octane-xplat/ui'
+
+export function ThemePreview() {
+  const scheme = useColorScheme()
+  return <View className={scheme === 'dark' ? 'dark' : 'light'}>
+    <Text>Ready for your next trip</Text>
+  </View>
+}
+```
 
 ## Fonts
 
-Family names differ per target (web face name, iOS PostScript name,
-Android filename). Ship the font file in the app, register per platform,
-and set the `--font-*` tokens in `style.css`. See the styling guide at
+System fonts are the default. Add a custom font when your app needs one.
+
+`pnpm xplat fonts add <file>` registers a font everywhere: stages a `.ttf`
+into `src/fonts` (iOS/Android pick it up from there; `.woff`/`.woff2` inputs
+are converted), writes the web `@font-face` into `src/fonts.css`, and wires
+`--font-sans` (or another token via `--token mono|none|<name>`) in
+`style.css`. Fontsource packages work too —
+`pnpm xplat fonts add @fontsource-variable/inter --install` imports the
+package's own CSS on web and stages its converted files natively (upright
+faces only — italic files are skipped). Variable
+fonts carry their weight range — `font-weight` on `Text` selects the matching
+instance. Family names differ per target; the command reads them from the
+file itself. See the styling guide at
 https://octane-xplat.goddardai.org/styling for the per-target table.
+
+```sh
+pnpm xplat fonts add ./Inter.ttf
+pnpm xplat fonts add @fontsource-variable/inter --install
+```

package/template/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-Octane xplat app — one TypeScript codebase for web + iOS + Android (Octane
+Octane Xplat app — one TypeScript codebase for web + iOS + Android (Octane
 
 - NativeScript).
 

package/template/package.json

@@ -2,7 +2,7 @@
 	"name": "octane-xplat-app",
 	"private": true,
 	"type": "module",
-	"main": "src/index.ts",
+	"main": "src/main.ts",
 	"scripts": {
 		"xplat": "xplat",
 		"dev": "vite",
@@ -17,11 +17,12 @@
 	},
 	"dependencies": {
 		"@nativescript-community/gesturehandler": "2.0.45",
-		"@nativescript-community/octane": "0.2.1",
+		"@nativescript-community/octane": "0.2.4",
 		"@nativescript-community/ui-drawer": "0.1.32",
 		"@nativescript/core": "9.1.2",
-		"@octane-xplat/effects": "^0.7.3",
-		"@octane-xplat/ui": "^0.7.3",
+		"@octane-xplat/effects": "^0.10.0",
+		"@octane-xplat/platform": "^0.10.0",
+		"@octane-xplat/ui": "^0.10.0",
 		"@valor/nativescript-websockets": "2.0.3",
 		"octane": "0.6.3"
 	},
@@ -30,14 +31,15 @@
 		"@nativescript/android": "9.1.1",
 		"@nativescript/ios": "9.1.0",
 		"@nativescript/types": "9.0.0",
-		"@nativescript/vite": "8.0.11",
-		"@octane-xplat/cli": "^0.7.3",
-		"@octane-xplat/lint": "^0.7.3",
+		"@nativescript/vite": "8.0.17",
+		"@octane-xplat/cli": "^0.10.0",
+		"@octane-xplat/lint": "^0.10.0",
 		"@octanejs/vite-plugin": "0.1.61",
-		"@tsrx/typescript-plugin": "0.4.7",
+		"@tsrx/typescript-plugin": "0.4.11",
 		"nativescript": "9.1.1",
 		"oxlint": "^1.74.0",
 		"typescript": "5.9.3",
 		"vite": "8.3.0"
-	}
+	},
+	"packageManager": "pnpm@11.24.0"
 }

package/template/pnpm-workspace.yaml

@@ -14,14 +14,25 @@ allowBuilds:
   '@parcel/watcher': true
   nativescript: true
   '@nativescript/core': false
-# Framework patch set required by the octane-xplat toolchain — applied via pnpm
-# patchedDependencies. Managed upstream by @octane-xplat/cli (`xplat patches apply`
-# refreshes, `xplat patches check` verifies); do not edit by hand.
+# The patch set covers optional leaf deps (tiptap, linkifyjs, …) the starter
+# doesn't install — tolerate entries that apply to nothing.
+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 octane 0.6.3 lacks live signal reads under universal renderers. Adds signal
   # ownership, read tracking, and local signal hooks; JSX prop lowering and __methodDep
-  # already ship upstream.
-  octane@0.6.3: patches/octane@0.6.3.patch
+  # already ship upstream. Routes uncaught universal event-handler errors to onUncaughtError
+  # when configured. Pins instance signal/query declarations to their declaring owner so
+  # child reads and event handlers share one request. Makes universal useImperativeHandle
+  # honor optional refs, ref replacement, nested ref arrays, and callback cleanup. Also
+  # allows async and generator helpers that are not components in universal compiler
+  # modules, while preserving errors when those functions are used as components
+  # (octanejs/octane#1469). Adds renderer-owned Children.toArray/map for transparent
+  # deferred JSX groups, plan ranges/slots and arrays, preserving keyed wrapper identity
+  # while leaving scoped owners intact.
+  octane@0.6.3: node_modules/.pnpm-config/@octane-xplat/patches/patches/octane@0.6.3.patch
   # FlexboxLayout getChildMeasureSpec subtracts the child's own padding where AOSP subtracts
   # parent padding + child margins — a column-stretched row re-measurement clamps padded
   # children (37→17 dip, squished controls). Adds squircle (continuous) corner clipping for
@@ -35,45 +46,67 @@ patchedDependencies:
   # frames whose ancestors present them (Frame.topmost stops returning hidden preloaded tab
   # frames). Also maps CSS font-weight to the OpenType wght axis for custom Android fonts on
   # API 26+, preserves explicit variation settings, and falls back to the prior file load
-  # when the axis is unsupported.
-  "@nativescript/core@9.1.2": patches/@nativescript__core@9.1.2.patch
+  # when the axis is unsupported. Carries NativeScript PR #11481: preserves percentage
+  # translate values through parsing and resolves each axis against the view's own
+  # dimensions, including native views and animations.
+  "@nativescript/core@9.1.2": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript__core@9.1.2.patch
+  # @nativescript/types@9.0.0 omits ambient declarations for the native URL and
+  # URLSearchParams globals, so projects without DOM libraries cannot typecheck valid native
+  # URL code. Adds runtime-aligned declarations that merge with DOM declarations when both
+  # libraries are present.
+  "@nativescript/types@9.0.0": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript__types@9.0.0.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: patches/css@3.0.0.patch
-  # Dev-server /ns/m fixes: resolve pnpm-isolated transitive deps and platform-suffixed
-  # entries, inline workspace CSS through /@fs (including the node:path import required to
-  # resolve workspace files), route vendor-excluded plugins through HTTP, decode bracketed
-  # paths, and ignore comments during export-star expansion. Deps-bundle alias: the dev
-  # payload's esbuild passes never see 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
-  # resolver also probes the .mobile suffix tier (ios/android) between the os qualifier and
-  # unsuffixed default — .mobile-only modules behind paths-mapped imports failed bundle-mode
-  # resolution.
-  "@nativescript/vite@8.0.11": patches/@nativescript__vite@8.0.11.patch
+  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.
+  "@nativescript/vite@8.0.17": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript__vite@8.0.17.patch
   # Driver setProp skips `undefined` writes — NativeScript native setters coerce it (e.g.
   # editable → ios.userInteractionEnabled = NO), leaving dead UI that still has its JS
-  # listeners.
-  "@nativescript-community/octane@0.2.1": patches/@nativescript-community__octane@0.2.1.patch
+  # listeners. Aligns intrinsic ref types with Octane callback cleanup and nested arrays
+  # with optional entries. Advertises the implemented visibility capability so committed
+  # suspense bodies can be retained while pending.
+  "@nativescript-community/octane@0.2.4": node_modules/.pnpm-config/@octane-xplat/patches/patches/@nativescript-community__octane@0.2.4.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": patches/@nativescript-community__vite-octane@0.2.1.patch
-  # Same dev-server fixes as the 8.0.11 patch, ported to the @11468 pkg.pr.new preview the
-  # windows target uses (apps/windows): /ns/m re-export records, vendor-manifest gating for
-  # plugin-patterned packages, percent-decoded specifiers, and the .mobile-aware
-  # tsconfig-paths probing.
-  "@nativescript/vite@8.0.13": patches/@nativescript__vite@8.0.13.patch
-  # Windows spike: the shared-file subset of the 9.1.2 patch — @layer cascade machinery
-  # (css-tree parser, css-selector, style-scope), the #11446 frame/tab-view common fixes,
-  # and the flexbox common measure-spec — applied to the @11468 preview. iOS/Android
-  # impl-file hunks are dead code on windows and were dropped.
-  "@nativescript/core@9.1.3-next.2": patches/@nativescript__core@9.1.3-next.2.patch
+  "@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": patches/@tsrx__typescript-plugin@0.4.11.patch
+  "@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
+  # Two bundler-visible issues: useEditor.ts reads bare process.env.NODE_ENV (no node global
+  # in the harness typecheck program) and './Context' resolves to Context.tsrx — a
+  # self-import — under suffix-first resolution, so EditorContext/useCurrentEditor were
+  # unreachable. Adds a module-local process declaration for typecheck and merges the
+  # Context.ts definitions into Context.tsrx.
+  "@octanejs/tiptap@0.0.51": node_modules/.pnpm-config/@octane-xplat/patches/patches/@octanejs__tiptap@0.0.51.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
+configDependencies:
+  "@octane-xplat/patches": 0.10.0

package/template/src/App.tsrx

@@ -1,5 +1,6 @@
 import { useState } from 'octane';
-import { View, Row, Text, Pressable, ScrollView, useColorScheme } from '@octane-xplat/ui';
+import { View, HStack, Text, Pressable, ScrollableArea, useColorScheme } from '@octane-xplat/ui';
+import { storage } from '@octane-xplat/platform';
 
 const FEATURES = [
 	'shared components',
@@ -13,8 +14,12 @@ const FEATURES = [
  *  (.web.tsrx / .mobile.tsrx), never inside a component. */
 export function App() @{
 	const [count, setCount] = useState(0);
-	// null = follow the system; the toggle overrides it for this session.
-	const [override, setOverride] = useState<boolean | null>(null);
+	// null = follow the system until the user chooses a mode.
+	const [override, setOverride] = useState<boolean | null>(() => {
+		const saved = storage.getString('theme-preference');
+		return saved === 'light' ? false : saved === 'dark' ? true : null;
+	});
+
 	const scheme = useColorScheme();
 	const dark = override ?? scheme === 'dark';
 
@@ -22,17 +27,21 @@ export function App() @{
 		<Text className="title">octane-xplat</Text>
 		<Text className="muted">one codebase — web · iOS · android</Text>
 
-		<Row className="counter">
+		<HStack className="counter">
 			<Pressable className="btn" onPress={() => setCount(count - 1)}><Text>−</Text></Pressable>
 			<Text className="count">{count}</Text>
 			<Pressable className="btn" onPress={() => setCount(count + 1)}><Text>+</Text></Pressable>
-		</Row>
+		</HStack>
 
-		<ScrollView>
+		<ScrollableArea>
 			{FEATURES.map((f) => <Text className="chip">{f}</Text>)}
-		</ScrollView>
+		</ScrollableArea>
 
-		<Pressable className="link" onPress={() => setOverride(!dark)}>
+		<Pressable 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>

package/template/src/process.d.ts

@@ -0,0 +1,7 @@
+// npm deps (upstream octane packages included) read `process.env.NODE_ENV`
+// bare — the npm convention where the consumer bundler statically replaces
+// the member expression (vite `define`; see xplatNodeEnvDefine). tsc still
+// needs the name declared in a program with no Node types. Kept narrow on
+// purpose: `process.env.FOO` reads stay type errors because the bundler
+// define cannot rewrite them either.
+declare const process: { env: { NODE_ENV?: string } }

package/template/src/style.css

@@ -1,7 +1,21 @@
-/* App chrome — everything here is inside the web∩native CSS grammar
- * (see docs/css-support-matrix.md in the framework repo). Design tokens
- * (--color-*) come from @octane-xplat/ui/theme/tokens.css; .dark re-themes
- * the same vars — no JS color values anywhere. */
+/* This starter leaves the optional UI chrome stylesheet out. Define this
+ * app's palette here; the required tokens.css supplies layout structure. */
+
+:root,
+.ns-root {
+	--color-primary: #171717;
+	--color-onprimary: #fafafa;
+	--color-surface: #ffffff;
+	--color-text: #0a0a0a;
+}
+
+.dark,
+.ns-dark {
+	--color-primary: #ededed;
+	--color-onprimary: #171717;
+	--color-surface: #0a0a0a;
+	--color-text: #ededed;
+}
 
 body {
 	margin: 0;
@@ -9,10 +23,12 @@ body {
 	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. */
+/* System-dark before JS mounts — no white flash. .app.light below is the
+ * manual override back. */
 @media (prefers-color-scheme: dark) {
 	:root {
+		--color-primary: #ededed;
+		--color-onprimary: #171717;
 		--color-surface: #0f172a;
 		--color-text: #f8fafc;
 	}
@@ -23,6 +39,8 @@ body {
 
 /* Manual light override when the system is dark (JS adds .light). */
 .app.light {
+	--color-primary: #171717;
+	--color-onprimary: #fafafa;
 	--color-surface: #ffffff;
 	--color-text: #111827;
 }

package/template/tsconfig.json

@@ -14,5 +14,5 @@
 		"skipLibCheck": true
 	},
 	"include": ["src/**/*"],
-	"exclude": ["node_modules", "src/index.ts"]
+	"exclude": ["node_modules", "src/main.ts"]
 }

package/template/vite.config.native.mts

@@ -3,6 +3,7 @@ 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).
+// the px→dip CSS rewrite, and fs.allow widening for link:/file: dep roots.
+// App-specific additions go through the second argument's `extra` (or
+// mergeConfig).
 export default defineConfig(({ mode }) => xplatNative(mode))

package/template/vite.config.ts

@@ -1,12 +1,14 @@
 import { defineConfig } from 'vite'
 import { octane } from '@octanejs/vite-plugin'
+import { xplatBoundary, xplatNodeEnvDefine } from '@octane-xplat/cli/vite'
 
 // The web build. For native (iOS/Android), the same source runs through
 // @nativescript-community/vite-octane with `conditions: ['native']`, the
 // .ios/.android/.mobile suffix chain, and the unsuffixed native default — see
 // the octane-xplat repo's apps/mobile/vite.config.mts.
-export default defineConfig({
-	plugins: [...octane()],
+export default defineConfig(({ mode }) => ({
+	plugins: [...octane(), xplatBoundary('web')],
+	define: xplatNodeEnvDefine(mode),
 	server: { port: 5200 },
 	resolve: {
 		conditions: ['web'],
@@ -25,4 +27,4 @@ export default defineConfig({
 			'.json',
 		],
 	},
-})
+}))