create-octane-xplat 0.3.0 → 0.5.0

package/README.md

@@ -0,0 +1,25 @@
+# create-octane-xplat
+
+> Scaffolds an Octane xplat app — one codebase targeting web, iOS, and
+> Android via NativeScript.
+>
+> Status: `0.x` — the API surface is still moving. iOS/Android targets need
+> the NativeScript toolchain (Xcode/JDK + `ns`).
+
+```sh
+pnpm create octane-xplat my-app
+# or: npm create octane-xplat my-app
+```
+
+Copies the starter template (vite + nativescript configs, shared `src/`,
+`App_Resources`, pinned workspace deps), installs dependencies with pnpm,
+and starts the web dev server. From there:
+
+```sh
+pnpm dev            # web
+pnpm dev:ios        # iOS simulator — needs the NativeScript toolchain
+pnpm dev:android    # Android — needs the NativeScript toolchain
+pnpm typecheck      # web + native tsconfigs
+```
+
+Docs: [Running and checking an app](https://octane-xplat.goddardai.org/toolchain)

package/index.mjs

@@ -1,28 +1,31 @@
 #!/usr/bin/env node
-import { existsSync, readdirSync, cpSync, renameSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, cpSync, renameSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
 
-const dir = resolve(process.argv[2] ?? 'octane-xplat-app');
+const dir = resolve(process.argv[2] ?? 'octane-xplat-app')
 
 if (existsSync(dir) && readdirSync(dir).length > 0) {
-	console.error(`✗ ${dir} exists and is not empty`);
-	process.exit(1);
+	console.error(`✗ ${dir} exists and is not empty`)
+	process.exit(1)
 }
 
-const template = join(dirname(fileURLToPath(import.meta.url)), 'template');
-cpSync(template, dir, { recursive: true });
+const template = join(dirname(fileURLToPath(import.meta.url)), 'template')
+cpSync(template, dir, { recursive: true })
 // npm packs .gitignore as a renamed file or drops it — ship it undotted.
-try { renameSync(join(dir, 'gitignore'), join(dir, '.gitignore')); } catch {}
-console.log(`\n✓ scaffolded ${dir}`);
+try {
+	renameSync(join(dir, 'gitignore'), join(dir, '.gitignore'))
+} catch {}
 
-const install = spawnSync('pnpm', ['install'], { cwd: dir, stdio: 'inherit' });
+console.log(`\n✓ scaffolded ${dir}`)
+
+const install = spawnSync('pnpm', ['install'], { cwd: dir, stdio: 'inherit' })
 if (install.status !== 0) {
-	console.log(`\nInstall didn't finish (pnpm missing?). To run manually:`);
-	console.log(`  cd ${dir}\n  pnpm install\n  pnpm dev`);
-	process.exit(install.status ?? 1);
+	console.log(`\nInstall didn't finish (pnpm missing?). To run manually:`)
+	console.log(`  cd ${dir}\n  pnpm install\n  pnpm dev`)
+	process.exit(install.status ?? 1)
 }
 
-console.log('\n✓ installed — starting dev server (Ctrl+C to stop)\n');
-spawnSync('pnpm', ['dev'], { cwd: dir, stdio: 'inherit' });
+console.log('\n✓ installed — starting dev server (Ctrl+C to stop)\n')
+spawnSync('pnpm', ['dev'], { cwd: dir, stdio: 'inherit' })

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "create-octane-xplat",
-  "version": "0.3.0",
-  "type": "module",
+  "version": "0.5.0",
   "description": "Scaffold a minimal @octane-xplat/ui app — one Octane codebase for web + iOS + Android",
   "bin": {
     "create-octane-xplat": "./index.mjs"
@@ -10,6 +9,7 @@
     "index.mjs",
     "template"
   ],
+  "type": "module",
   "publishConfig": {
     "access": "public"
   }

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

@@ -0,0 +1,77 @@
+---
+name: xplat
+description: Build and review code in an Octane xplat app — one TypeScript codebase targeting web (DOM) and iOS/Android (NativeScript). Use when writing components, styles, routes, platform leaves, or device-service calls, and when a feature works on one target but not another.
+---
+
+# Octane xplat app
+
+Every `src/*.tsrx` file compiles twice: once to the DOM renderer, once to
+NativeScript views. The common failure mode is **silent divergence** — code
+that compiles and works on web but no-ops or crashes on native. The rules
+below prevent that; `pnpm lint` enforces most of them.
+
+## Non-negotiables
+
+1. **One element vocabulary per file.** Shared code renders only
+   `@octane-xplat/ui` components. Platform divergence lives in whole files
+   — `Foo.web.tsrx`, `Foo.native.tsrx`, `Foo.ios.tsrx`, `Foo.android.tsrx` —
+   chosen by the bundler when something imports `./Foo`. Never branch on
+   platform inside JSX (`Platform.OS`, conditional imports, `typeof
+   document` checks).
+2. **No DOM globals in shared code.** `document`, `window`, `localStorage`,
+   DOM events — all web-only. Device capabilities (clipboard, storage,
+   permissions, connectivity, geolocation, …) come from
+   `@octane-xplat/platform`.
+3. **Styles:** `className` for anything static; `style` objects only for
+   values that change while the app runs. Shared CSS must use the portable
+   subset — the native build warns on declarations it drops
+   (`position: fixed`, `margin: auto`, `box-shadow`, …).
+4. **Hooks and JSX live in `.tsrx` (or `.tsx`).** Plain `.ts` is for
+   non-component code and may not import `.tsrx`. Import `.tsrx` files with
+   the explicit extension: `import { App } from './App.tsrx'`.
+5. **State = `octane/signals`.** `signal$()` for module-level shared state,
+   `useSignal$()` for component-local, `derived$()` for computed, `query$()`
+   for async data. Name signal variables with a `$` suffix (`count$`,
+   `user$`) — the compiler uses the suffix to preserve reactive reads on
+   native. Every module that reads or writes signals needs a runtime
+   `import 'octane/signals'` (or `octane/signals/client`).
+6. **One `octane` per app.** Don't add a second renderer or duplicate the
+   package — two copies break the reconciler without a helpful error.
+
+## Compiler rules that surprise
+
+- `.tsrx` files can't declare `async` top-level functions — the compiler
+  treats them as async components and the native build fails.
+- Literal `@{` in JSX text parses as a code block. Write `{'@'}{expr}` to
+  render a literal `@`.
+- Effect dependencies are inferred from closure reads. An effect that only
+  writes (refs, DOM) and never reads its driving prop won't re-run —
+  declare deps explicitly: `useLayoutEffect(fn, [props.x])`.
+- Input handlers must be idempotent — `onInput`/`onChange` can dispatch
+  more than once per user action on web.
+- `.native.tsrx`/`.ios.tsrx`/`.android.tsrx` files containing JSX must
+  start with `/** @jsxImportSource @nativescript-community/octane */` on
+  line 1 — nothing may precede it.
+
+## Verify
+
+| Command | Catches |
+| --- | --- |
+| `pnpm lint` | vocabulary / DOM-global / style violations — its output is authoritative |
+| `pnpm typecheck` | both web and native TS configs |
+| `pnpm dev` | web behavior |
+| `pnpm dev:ios` / `pnpm dev:android` | the platform where behavior actually differs |
+
+## Read next (only when needed)
+
+- `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/platform.md` — device services and writing your own leaf.
+- Current limits and platform boundaries:
+  https://octane-xplat.goddardai.org/known-limits
+- Full framework docs, one file:
+  https://octane-xplat.goddardai.org/llms-full.txt (index:
+  https://octane-xplat.goddardai.org/llms.txt). The `/notes/*` design
+  record explains *why* a constraint exists — rarely needed for app work.

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

@@ -0,0 +1,49 @@
+# Components — the shared vocabulary
+
+Import everything from `@octane-xplat/ui`. Each component has a web leaf
+(DOM) and a native leaf (NativeScript view) — the JSX is identical on both.
+
+| Need | Component(s) |
+| --- | --- |
+| Layout | `View` (aliased `Column`), `Row`, `Grid`, `Stack`, `Absolute`, `Spacer`, `SafeArea`, `KeyboardAvoiding` |
+| Text | `Text`, `Heading`, `RichText` + `RichTextSpan` |
+| Tap/hover | `Pressable`, `Link`, `NavLink`, `Hoverable` |
+| Input | `TextInput`, `TextArea`, `Switch`, `Slider` |
+| Collections | `List` |
+| Scrolling | `ScrollView`, `ScrollBox` |
+| Media | `Image`, `Icon` (`registerIcon`/`registerIcons` for glyphs) |
+| Feedback | `ActivityIndicator`, `Meter`, `showToast` |
+| Overlays | `Modal`/`openModal`, `Sheet`/`openSheet`/`closeSheet`, `Overlay`, `Popover`, `Drawer`, `openWindow` |
+| Shells | `Screen`, `Tabs` (+ `TabSpec`) |
+| Animation | `useAnimation` → `AnimatedValue` |
+| Theme/measure | `useColorScheme`/`getColorScheme`, `useSafeAreaInsets`, `useMeasure`, `styled()`, `createStore` |
+
+## Divergences that matter
+
+- `ScrollBox` is a **name trap**: on native it's a plain, non-scrolling
+  container (a `List` inside it owns scrolling). Use `ScrollView` when you
+  actually want a scroller.
+- `List` is not virtualized on web. On native it must not sit inside a
+  `ScrollView` — two scrollers fight and the framework throws.
+- `TextArea` `onSubmit`: web fires on Cmd/Ctrl+Enter; native fires only
+  when `returnKeyType` is `"done"` or `"send"` — otherwise every newline
+  reports as a submit.
+- `Modal` on Android: a non-fullscreen modal shows as a centered dialog,
+  not a bottom sheet. Context and theme don't cross overlay roots — read
+  them inside the overlay or pass values down.
+- `Sheet`/`openSheet` is a bottom-anchored sheet on both platforms; on web
+  it renders an in-window portal layer over the app.
+- `Drawer` has an edge-swipe gesture on native only — give web users a
+  visible toggle.
+- `RichTextSpan` children carry their own `className`/`style`/`onPress`;
+  native maps spans to `FormattedString` runs.
+- Accessibility props (`accessible`, label, hint, role, state, live
+  region) share names across targets; native translates roles such as
+  `heading` → `header`.
+
+## Things that look right but aren't
+
+- `PlatformBadge` is an internal probe, not app vocabulary — don't use it.
+- `keyFor` on `List` is web-only.
+- Route `params` must be scalar (see navigation reference) — objects work
+  on native but are silently dropped on web.

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

@@ -0,0 +1,30 @@
+# Navigation
+
+One route table serves both targets. Declare named screens and stacks;
+navigate with `<Link>`/`<NavLink>` in JSX or `pushRoute`/`popRoute`/
+`useRoute`/`useCanGoBack` imperatively. Web maps routes to URLs and
+history; native maps them to Frame pages and the back stack — the same
+call sites drive both.
+
+## Rules
+
+- **Params are scalar.** They serialize as query strings on web — pass
+  strings and numbers. Objects survive on native and are silently dropped
+  on web.
+- **Tabs and named stacks** (`Tabs` + `TabSpec`, `registerStack`) exist on
+  both targets. Use a named stack for overlay-style flows (sheets,
+  sidebars) that shouldn't replace the root page.
+- **Deep links:** web is the URL itself; native parses incoming URLs into
+  the same route names — keep names stable and shareable.
+- **Back** — browser back, hardware back (Android), and swipe-back (iOS)
+  all map to `popRoute` on the current stack.
+
+## Known gap
+
+Pushing into a *named* stack is iOS-only until
+[NativeScript#11444](https://github.com/NativeScript/NativeScript/issues/11444)
+lands — `pushRoute` there warns loudly on Android instead of dropping
+silently. Root-stack navigation works on both platforms.
+
+For loaders, route config, and generated route types, see the navigation
+guide: https://octane-xplat.goddardai.org/navigation

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

@@ -0,0 +1,45 @@
+# Platform services + writing leaves
+
+Two seams cover everything shared code can't reach:
+
+## `@octane-xplat/platform` — device services
+
+One import per capability; each service resolves internally to a `.web` or
+`.native` implementation. Surface: `device`, `appInfo`, `locale`,
+`connectivity`, `useWindowSize`, `useAppState`, `useSafeAreaInsets`, deep
+links, clipboard, `secureStorage`, haptics, notifications, `announce`,
+`systemBars`, geolocation, permissions, media, files, share, `openUrl`,
+`openSettings`, biometrics.
+
+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.
+
+## Leaf files — your own divergence
+
+When a service doesn't exist yet or a visual behavior truly differs,
+split the file, not the JSX:
+
+```text
+src/parts/Scanner.tsrx          shared part — imports './Scanner.impl'
+src/parts/Scanner.impl.web.ts   DOM implementation (camera via getUserMedia)
+src/parts/Scanner.impl.native.ts NativeScript implementation
+```
+
+Import the bare specifier (`./Scanner.impl`); the bundler picks the leaf
+via the suffix chain `.ios` → `.android` → `.native` → shared / `.web` →
+shared.
+
+Leaf rules:
+
+- Inside a leaf, platform APIs are *expected*: DOM globals in `.web.*`,
+  `@nativescript/*` imports in `.native.*`. The lint rules key off the
+  suffix — don't fight them with suppressions.
+- 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.tsrx` files with 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`.

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

@@ -0,0 +1,42 @@
+# Styling
+
+Two channels, chosen by *when the value is known*:
+
+- `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.
+
+## The portable subset
+
+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.
+
+NativeScript limits worth knowing before you design around them:
+
+- 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.
+
+## 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.
+
+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.
+
+## 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
+https://octane-xplat.goddardai.org/styling for the per-target table.

package/template/.oxlintrc.json

@@ -0,0 +1,25 @@
+{
+	"jsPlugins": ["@octane-xplat/lint/oxlint-plugin"],
+	"rules": {
+		"curly": "error",
+		"xplat/spacing": "error",
+		"xplat/no-dom-globals": "error",
+		"xplat/no-web-only-api": "error",
+		"xplat/element-vocabulary": "error",
+		"xplat/no-nativescript-import": "error",
+		"xplat/no-ns-deep-import": "error",
+		"xplat/no-native-dead-style": "error",
+		"xplat/no-line-height-unitless": "error",
+		"xplat/no-style-string": "error",
+		"xplat/no-unknown-class": "warn",
+		"xplat/no-ts-imports-tsrx": "error",
+		"xplat/signal-dollar-suffix": "error",
+		"xplat/require-signals-runtime": "warn",
+		"xplat/no-view-onpress": "error",
+		"xplat/no-console-debug": "error",
+		"xplat/hooks-in-plain-ts": "warn",
+		"xplat/native-pragma-first-line": "error",
+		"xplat/no-jsx-text-breakers": "error",
+		"xplat/no-root-logical-render": "error"
+	}
+}

package/template/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md
+
+Octane xplat app — one TypeScript codebase for web + iOS + Android (Octane
++ NativeScript).
+
+Before writing code, read `.agents/skills/xplat/SKILL.md` (or invoke the
+`xplat` skill). Its invariants are enforced by `pnpm lint` — violations
+usually still compile but silently break on one platform.

package/template/App_Resources/iOS/Assets.xcassets/AppIcon.appiconset/Contents.json

@@ -1,122 +1,122 @@
 {
-  "images" : [
-    {
-      "size" : "20x20",
-      "idiom" : "iphone",
-      "filename" : "icon-20@2x.png",
-      "scale" : "2x"
-    },
-    {
-      "size" : "20x20",
-      "idiom" : "iphone",
-      "filename" : "icon-20@3x.png",
-      "scale" : "3x"
-    },
-    {
-      "size" : "29x29",
-      "idiom" : "iphone",
-      "filename" : "icon-29.png",
-      "scale" : "1x"
-    },
-    {
-      "size" : "29x29",
-      "idiom" : "iphone",
-      "filename" : "icon-29@2x.png",
-      "scale" : "2x"
-    },
-    {
-      "size" : "29x29",
-      "idiom" : "iphone",
-      "filename" : "icon-29@3x.png",
-      "scale" : "3x"
-    },
-    {
-      "size" : "40x40",
-      "idiom" : "iphone",
-      "filename" : "icon-40@2x.png",
-      "scale" : "2x"
-    },
-    {
-      "size" : "40x40",
-      "idiom" : "iphone",
-      "filename" : "icon-40@3x.png",
-      "scale" : "3x"
-    },
-    {
-      "size" : "60x60",
-      "idiom" : "iphone",
-      "filename" : "icon-60@2x.png",
-      "scale" : "2x"
-    },
-    {
-      "size" : "60x60",
-      "idiom" : "iphone",
-      "filename" : "icon-60@3x.png",
-      "scale" : "3x"
-    },
-    {
-      "size" : "20x20",
-      "idiom" : "ipad",
-      "filename" : "icon-20.png",
-      "scale" : "1x"
-    },
-    {
-      "size" : "20x20",
-      "idiom" : "ipad",
-      "filename" : "icon-20@2x.png",
-      "scale" : "2x"
-    },
-    {
-      "size" : "29x29",
-      "idiom" : "ipad",
-      "filename" : "icon-29.png",
-      "scale" : "1x"
-    },
-    {
-      "size" : "29x29",
-      "idiom" : "ipad",
-      "filename" : "icon-29@2x.png",
-      "scale" : "2x"
-    },
-    {
-      "size" : "40x40",
-      "idiom" : "ipad",
-      "filename" : "icon-40.png",
-      "scale" : "1x"
-    },
-    {
-      "size" : "40x40",
-      "idiom" : "ipad",
-      "filename" : "icon-40@2x.png",
-      "scale" : "2x"
-    },
-    {
-      "size" : "76x76",
-      "idiom" : "ipad",
-      "filename" : "icon-76.png",
-      "scale" : "1x"
-    },
-    {
-      "size" : "76x76",
-      "idiom" : "ipad",
-      "filename" : "icon-76@2x.png",
-      "scale" : "2x"
-    },
-    {
-      "size" : "83.5x83.5",
-      "idiom" : "ipad",
-      "filename" : "icon-83.5@2x.png",
-      "scale" : "2x"
-    },
-    {
-      "size" : "1024x1024",
-      "idiom" : "ios-marketing",
-      "filename" : "icon-1024.png",
-      "scale" : "1x"
-    }
-  ],
-  "info" : {
-    "version" : 1,
-    "author" : "xcode"
-  }
-}
+	"images": [
+		{
+			"size": "20x20",
+			"idiom": "iphone",
+			"filename": "icon-20@2x.png",
+			"scale": "2x"
+		},
+		{
+			"size": "20x20",
+			"idiom": "iphone",
+			"filename": "icon-20@3x.png",
+			"scale": "3x"
+		},
+		{
+			"size": "29x29",
+			"idiom": "iphone",
+			"filename": "icon-29.png",
+			"scale": "1x"
+		},
+		{
+			"size": "29x29",
+			"idiom": "iphone",
+			"filename": "icon-29@2x.png",
+			"scale": "2x"
+		},
+		{
+			"size": "29x29",
+			"idiom": "iphone",
+			"filename": "icon-29@3x.png",
+			"scale": "3x"
+		},
+		{
+			"size": "40x40",
+			"idiom": "iphone",
+			"filename": "icon-40@2x.png",
+			"scale": "2x"
+		},
+		{
+			"size": "40x40",
+			"idiom": "iphone",
+			"filename": "icon-40@3x.png",
+			"scale": "3x"
+		},
+		{
+			"size": "60x60",
+			"idiom": "iphone",
+			"filename": "icon-60@2x.png",
+			"scale": "2x"
+		},
+		{
+			"size": "60x60",
+			"idiom": "iphone",
+			"filename": "icon-60@3x.png",
+			"scale": "3x"
+		},
+		{
+			"size": "20x20",
+			"idiom": "ipad",
+			"filename": "icon-20.png",
+			"scale": "1x"
+		},
+		{
+			"size": "20x20",
+			"idiom": "ipad",
+			"filename": "icon-20@2x.png",
+			"scale": "2x"
+		},
+		{
+			"size": "29x29",
+			"idiom": "ipad",
+			"filename": "icon-29.png",
+			"scale": "1x"
+		},
+		{
+			"size": "29x29",
+			"idiom": "ipad",
+			"filename": "icon-29@2x.png",
+			"scale": "2x"
+		},
+		{
+			"size": "40x40",
+			"idiom": "ipad",
+			"filename": "icon-40.png",
+			"scale": "1x"
+		},
+		{
+			"size": "40x40",
+			"idiom": "ipad",
+			"filename": "icon-40@2x.png",
+			"scale": "2x"
+		},
+		{
+			"size": "76x76",
+			"idiom": "ipad",
+			"filename": "icon-76.png",
+			"scale": "1x"
+		},
+		{
+			"size": "76x76",
+			"idiom": "ipad",
+			"filename": "icon-76@2x.png",
+			"scale": "2x"
+		},
+		{
+			"size": "83.5x83.5",
+			"idiom": "ipad",
+			"filename": "icon-83.5@2x.png",
+			"scale": "2x"
+		},
+		{
+			"size": "1024x1024",
+			"idiom": "ios-marketing",
+			"filename": "icon-1024.png",
+			"scale": "1x"
+		}
+	],
+	"info": {
+		"version": 1,
+		"author": "xcode"
+	}
+}

package/template/App_Resources/iOS/Assets.xcassets/Contents.json

@@ -1,6 +1,6 @@
 {
-  "info" : {
-    "version" : 1,
-    "author" : "xcode"
-  }
-}
+	"info": {
+		"version": 1,
+		"author": "xcode"
+	}
+}

package/template/App_Resources/iOS/Assets.xcassets/LaunchScreen.AspectFill.imageset/Contents.json

@@ -1,23 +1,23 @@
 {
-  "images" : [
-    {
-      "idiom" : "universal",
-      "filename" : "LaunchScreen-AspectFill.png",
-      "scale" : "1x"
-    },
-    {
-      "idiom" : "universal",
-      "filename" : "LaunchScreen-AspectFill@2x.png",
-      "scale" : "2x"
-    },
-    {
-      "idiom" : "universal",
-      "filename" : "LaunchScreen-AspectFill@3x.png",
-      "scale" : "3x"
-    }
-  ],
-  "info" : {
-    "version" : 1,
-    "author" : "xcode"
-  }
-}
+	"images": [
+		{
+			"idiom": "universal",
+			"filename": "LaunchScreen-AspectFill.png",
+			"scale": "1x"
+		},
+		{
+			"idiom": "universal",
+			"filename": "LaunchScreen-AspectFill@2x.png",
+			"scale": "2x"
+		},
+		{
+			"idiom": "universal",
+			"filename": "LaunchScreen-AspectFill@3x.png",
+			"scale": "3x"
+		}
+	],
+	"info": {
+		"version": 1,
+		"author": "xcode"
+	}
+}

package/template/App_Resources/iOS/Assets.xcassets/LaunchScreen.Center.imageset/Contents.json

@@ -1,23 +1,23 @@
 {
-  "images" : [
-    {
-      "idiom" : "universal",
-      "filename" : "LaunchScreen-Center.png",
-      "scale" : "1x"
-    },
-    {
-      "idiom" : "universal",
-      "filename" : "LaunchScreen-Center@2x.png",
-      "scale" : "2x"
-    },
-    {
-      "idiom" : "universal",
-      "filename" : "LaunchScreen-Center@3x.png",
-      "scale" : "3x"
-    }
-  ],
-  "info" : {
-    "version" : 1,
-    "author" : "xcode"
-  }
-}
+	"images": [
+		{
+			"idiom": "universal",
+			"filename": "LaunchScreen-Center.png",
+			"scale": "1x"
+		},
+		{
+			"idiom": "universal",
+			"filename": "LaunchScreen-Center@2x.png",
+			"scale": "2x"
+		},
+		{
+			"idiom": "universal",
+			"filename": "LaunchScreen-Center@3x.png",
+			"scale": "3x"
+		}
+	],
+	"info": {
+		"version": 1,
+		"author": "xcode"
+	}
+}

package/template/App_Resources/iOS/Assets.xcassets/octane.imageset/Contents.json

@@ -1,8 +1,8 @@
 {
-  "images" : [
-    { "filename" : "octane.png", "idiom" : "universal", "scale" : "1x" },
-    { "filename" : "octane@2x.png", "idiom" : "universal", "scale" : "2x" },
-    { "filename" : "octane@3x.png", "idiom" : "universal", "scale" : "3x" }
-  ],
-  "info" : { "author" : "xcode", "version" : 1 }
+	"images": [
+		{ "filename": "octane.png", "idiom": "universal", "scale": "1x" },
+		{ "filename": "octane@2x.png", "idiom": "universal", "scale": "2x" },
+		{ "filename": "octane@3x.png", "idiom": "universal", "scale": "3x" }
+	],
+	"info": { "author": "xcode", "version": 1 }
 }

package/template/index.html

@@ -1,12 +1,12 @@
 <!doctype html>
 <html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>octane-xplat app</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.web.tsrx"></script>
-  </body>
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<title>octane-xplat app</title>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="/src/main.web.tsrx"></script>
+	</body>
 </html>

package/template/nativescript.config.ts

@@ -1,13 +1,20 @@
-import { NativeScriptConfig } from '@nativescript/core';
+import { NativeScriptConfig } from '@nativescript/core'
 
 export default {
-  id: 'org.nativescript.octanexplat',
-  appPath: 'src',
-  appResourcesPath: 'App_Resources',
-  android: {
-    v8Flags: '--expose_gc',
-    markingMode: 'none',
-  },
-  bundler: 'vite',
-  bundlerConfigPath: 'vite.config.native.mts',
-} as NativeScriptConfig;
+	id: 'org.nativescript.octanexplat',
+	appPath: 'src',
+	appResourcesPath: 'App_Resources',
+	// The workspace is pnpm-managed — without this the CLI defaults to npm
+	// and spawns the bundler with --preserve-symlinks, which breaks isolated
+	// node_modules resolution (a package's transitive deps never realpath
+	// into the .pnpm store → ERR_MODULE_NOT_FOUND).
+	cli: {
+		packageManager: 'pnpm',
+	},
+	android: {
+		v8Flags: '--expose_gc',
+		markingMode: 'none',
+	},
+	bundler: 'vite',
+	bundlerConfigPath: 'vite.config.native.mts',
+} as NativeScriptConfig

package/template/package.json

@@ -1,37 +1,44 @@
 {
-  "name": "octane-xplat-app",
-  "private": true,
-  "type": "module",
-  "main": "src/native.ts",
-  "scripts": {
-    "xplat": "xplat",
-    "dev": "vite",
-    "dev:ios": "ns run ios",
-    "dev:android": "ns run android",
-    "build": "vite build",
-    "build:ios": "ns build ios",
-    "build:android": "ns build android",
-    "typecheck": "tsrx-tsc --noEmit && tsrx-tsc --noEmit -p tsconfig.native.json"
-  },
-  "dependencies": {
-    "@nativescript-community/octane": "0.2.1",
-    "@nativescript-community/ui-canvas": "4.6.52",
-    "@nativescript/core": "9.1.2",
-    "@octane-xplat/ui": "^0.3.0",
-    "@valor/nativescript-websockets": "2.0.3",
-    "octane": "0.4.0"
-  },
-  "devDependencies": {
-    "@nativescript-community/vite-octane": "0.2.1",
-    "@nativescript/android": "9.1.1",
-    "@nativescript/ios": "9.1.0",
-    "@nativescript/types": "9.0.0",
-    "@nativescript/vite": "8.0.11",
-    "@octane-xplat/cli": "^0.3.0",
-    "@octanejs/vite-plugin": "0.1.58",
-    "@tsrx/typescript-plugin": "0.4.7",
-    "nativescript": "9.1.1",
-    "typescript": "5.9.3",
-    "vite": "8.3.0"
-  }
+	"name": "octane-xplat-app",
+	"private": true,
+	"type": "module",
+	"main": "src/index.native.ts",
+	"scripts": {
+		"xplat": "xplat",
+		"dev": "vite",
+		"dev:ios": "ns run ios",
+		"dev:android": "ns run android",
+		"build": "vite build",
+		"build:ios": "ns build ios",
+		"build:android": "ns build android",
+		"lint": "xplat-lint",
+		"lint:fix": "xplat-lint --fix",
+		"typecheck": "tsrx-tsc --noEmit && tsrx-tsc --noEmit -p tsconfig.native.json"
+	},
+	"dependencies": {
+		"@nativescript-community/gesturehandler": "2.0.45",
+		"@nativescript-community/octane": "0.2.1",
+		"@nativescript-community/ui-canvas": "4.6.52",
+		"@nativescript-community/ui-drawer": "0.1.32",
+		"@nativescript-community/ui-svg": "0.2.24",
+		"@nativescript/core": "9.1.2",
+		"@octane-xplat/ui": "^0.5.0",
+		"@valor/nativescript-websockets": "2.0.3",
+		"octane": "0.4.0"
+	},
+	"devDependencies": {
+		"@nativescript-community/vite-octane": "0.2.1",
+		"@nativescript/android": "9.1.1",
+		"@nativescript/ios": "9.1.0",
+		"@nativescript/types": "9.0.0",
+		"@nativescript/vite": "8.0.11",
+		"@octane-xplat/cli": "^0.5.0",
+		"@octane-xplat/lint": "^0.1.0",
+		"@octanejs/vite-plugin": "0.1.58",
+		"@tsrx/typescript-plugin": "0.4.7",
+		"oxlint": "^1.74.0",
+		"nativescript": "9.1.1",
+		"typescript": "5.9.3",
+		"vite": "8.3.0"
+	}
 }

package/template/src/{native.ts → index.native.ts}

@@ -1,10 +1,10 @@
 // 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';
+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: () => {
@@ -12,14 +12,14 @@ const entry = {
 		// 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;
+		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.
@@ -27,7 +27,7 @@ const 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);
+	Application.resetRootView(entry)
 } else {
-	Application.run(entry);
+	Application.run(entry)
 }

package/template/src/style.css

@@ -65,17 +65,19 @@ body {
 
 .btn {
 	background-color: var(--color-primary);
-	color: var(--color-on-primary);
+	color: var(--color-onprimary);
 	padding: 10px 20px;
 	border-radius: 10px;
+	corner-shape: squircle;
 	font-size: 20px;
 }
 
 .chip {
 	background-color: var(--color-primary);
-	color: var(--color-on-primary);
+	color: var(--color-onprimary);
 	padding: 6px 14px;
 	border-radius: 14px;
+	corner-shape: squircle;
 	font-size: 14px;
 }
 

package/template/tsconfig.json

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

package/template/vite.config.native.mts

@@ -1,85 +1,8 @@
-import { defineConfig, mergeConfig, type Plugin } from 'vite';
-import { octaneConfig } from '@nativescript-community/vite-octane';
-import { nativeScriptRenderer } from '@nativescript-community/octane/config';
+import { defineConfig } from 'vite'
+import { xplatNative } from '@octane-xplat/cli/vite'
 
-/**
- * On-device HMR needs the app's websocket client to attach to /ns-hmr after
- * the HTTP boot. When it never does — the @valor/nativescript-websockets
- * polyfill missing from the bundle, `adb reverse` not covering the vite port,
- * or a boot error before the client import — every save logs `recipients=0`
- * and the device silently stays stale. Warn once when a dev session was
- * fetched but no client ever attached.
- */
-function nsHmrClientWatchdog(): Plugin {
-	return {
-		name: 'ns-hmr-client-watchdog',
-		configureServer(server) {
-			let everConnected = false;
-			let timer: ReturnType<typeof setTimeout> | undefined;
-			// Hook the raw 'request' event — middlewares.use() appends after the
-			// ns plugin's session handler, which ends the response without next(),
-			// so a connect middleware never observes /__ns_dev__/session at all.
-			server.httpServer?.on('request', (req) => {
-				if (!everConnected && req.url?.startsWith('/__ns_dev__/session')) {
-					clearTimeout(timer);
-					timer = setTimeout(() => {
-						if (!everConnected) {
-							console.warn(
-								'[ns-hmr-client-watchdog] the app fetched its dev session ' +
-									'but no /ns-hmr websocket client connected — edits will not ' +
-									'reach the device. Check that @valor/nativescript-websockets ' +
-									'is installed, `adb reverse tcp:<port>` covers this vite port ' +
-									'(physical Android), and the device log for hmr-client errors.',
-							);
-						}
-					}, 15_000);
-				}
-			});
-			server.httpServer?.on('upgrade', (req) => {
-				if (req.url?.startsWith('/ns-hmr')) {
-					everConnected = true;
-					clearTimeout(timer);
-				}
-			});
-		},
-	};
-}
-
-// The native build (iOS/Android). @octane-xplat/ui resolves through the
-// package's `native` export condition → compiled dist/native — no .tsrx
-// leaves needed from node_modules, so the renderer rule covers src/ only.
-export default defineConfig(({ mode }) =>
-	mergeConfig(
-		octaneConfig(
-			{ mode },
-			{
-				octane: {
-					renderers: {
-						registry: { nativescript: nativeScriptRenderer },
-						rules: [
-							{ include: 'src/**/*.{ts,tsx,tsrx}', renderer: 'nativescript' },
-						],
-					},
-				},
-			},
-		),
-		{
-			plugins: [nsHmrClientWatchdog()],
-			resolve: {
-				conditions: ['native'],
-				// The deps-bundle scanner sees source-level 'octane' imports
-				// before the compiler retargets hooks — without this it vendors
-				// the DOM runtime. Exact match only.
-				alias: [{ find: /^octane$/, replacement: 'octane/universal/native' }],
-				preserveSymlinks: false,
-				// Suffix chain (first match wins): .ios/.android → .native → shared.
-				extensions: [
-					'.ios.tsrx', '.android.tsrx', '.native.tsrx', '.tsrx',
-					'.ios.tsx', '.android.tsx', '.native.tsx', '.tsx',
-					'.ios.ts', '.android.ts', '.native.ts', '.mjs', '.mts', '.ts',
-					'.jsx', '.js', '.json',
-				],
-			},
-		},
-	),
-);
+// 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',
 		],
 	},
-});
+})