create-octane-xplat 0.4.0 → 0.6.0

package/README.md

@@ -23,3 +23,8 @@ pnpm typecheck      # web + native tsconfigs
 ```
 
 Docs: [Running and checking an app](https://octane-xplat.goddardai.org/toolchain)
+
+The scaffolded app ships `.agents/skills/xplat/` — a skill with the
+invariants agents need before writing code (element vocabulary, DOM-global
+rules, signal naming, compiler surprises) plus per-domain references.
+Agents: [llms.txt](https://octane-xplat.goddardai.org/llms.txt) indexes the docs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-octane-xplat",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Scaffold a minimal @octane-xplat/ui app — one Octane codebase for web + iOS + Android",
   "bin": {
     "create-octane-xplat": "./index.mjs"

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

@@ -0,0 +1,80 @@
+---
+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). Platform-authentic widgets live behind
+   `@octane-xplat/ui/ios`, `/android`, and `/web` — importing a subpath
+   outside a matching suffix file fails the other platform's build (the
+   `xplat/platform-subpath-import` lint enforces it).
+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,93 @@
+# Components — the vocabulary
+
+Every shared component imports from `@octane-xplat/ui` and owns its pixels —
+same props, same pixels on every target. Platform-authentic widgets (real
+OS chrome) live behind `@octane-xplat/ui/ios` and `@octane-xplat/ui/android`
+under their official OS names — those subpaths resolve only in native
+builds and are the honest opt-in for "I want the platform widget." A shared
+`.tsrx` file that imports them fails the other platform's build on purpose;
+import them inside `.ios.tsrx`/`.android.tsrx`/`.native.tsrx` leaves.
+
+## Shared — `@octane-xplat/ui` (self-drawn, same pixels everywhere)
+
+| Need          | Component(s)                                                                                    |
+| ------------- | ----------------------------------------------------------------------------------------------- |
+| Layout        | `View` (aliased `Column`), `Row`, `Grid`, `Stack`, `Absolute`, `Spacer`, `SafeArea`             |
+| Text          | `Text`, `Heading`, `RichText` + `RichTextSpan`                                                  |
+| Tap           | `Pressable`, `Link`, `NavLink`                                                                  |
+| Input         | `TextInput`, `TextArea`, `Switch`, `Slider`                                                     |
+| Scrolling     | `ScrollView`, `ScrollBox`                                                                       |
+| Media         | `Image`, `Icon` (`registerIcon`/`registerIcons` for glyphs)                                     |
+| Feedback      | `ActivityIndicator`, `Meter`, `showToast`                                                       |
+| Overlays      | `Sheet`/`openSheet`/`closeSheet`, `Overlay`, `Popover`, `Drawer`, `openWindow`                  |
+| Shells        | `Screen`, `Tabs` (+ `TabSpec`)                                                                  |
+| Animation     | `useAnimation` → `AnimatedValue`                                                                |
+| Theme/measure | `useColorScheme`/`getColorScheme`, `useSafeAreaInsets`, `useMeasure`, `styled()`, `createStore` |
+
+`Switch`, `Slider`, `ActivityIndicator`, `Tabs`, and `Drawer` are drawn by
+the framework — the OS widget is deliberately not what you get. For a list,
+compose `ScrollView` + mapped children; there is no shared recycled list.
+
+## Normalized OS widgets (shared, unavoidable platform controls)
+
+`TextInput`, `TextArea`, `ScrollView`/`ScrollBox` render through the real
+OS text/scroll controls — self-drawing them would lose IME, secure entry,
+selection, and autofill. The framework resets their chrome (no platform
+underline/border/padding, normalized font/color/placeholder/focus) so the
+same `className`/`style` lands on the same box. What stays platform-native
+by design: caret and selection UI, autocorrect/IME toolbars, keyboard
+types, scroll physics and overscroll.
+
+## Platform-authentic — `@octane-xplat/ui/ios`
+
+`UISwitch`, `UISlider`, `UIActivityIndicatorView`, `UITableView`,
+`UITabBar`, `UIModal` (+ `openModal`), `SideDrawer` (ui-drawer edge-gesture
+drawer), `LiquidGlass` + `LiquidGlassContainer` (iOS 26+ UIGlassEffect,
+inert layout below it).
+
+## Platform-authentic — `@octane-xplat/ui/android`
+
+`MaterialSwitch`, `SeekBar`, `CircularProgressIndicator`, `RecyclerView`,
+`BottomNavigationView`, `MaterialDialog` (+ `openModal`), `DrawerLayout`.
+
+## Platform-only shared exports
+
+- `KeyboardAvoiding` — native root export only (inert on web).
+- `Hoverable` — `@octane-xplat/ui/web` only. Hover has no touch-platform
+  semantic; the old native leaf's long-press stand-in was fake parity.
+
+## Divergences that matter
+
+- `ScrollBox` is a **name trap**: on native it's a plain, non-scrolling
+  container (a platform list inside it owns scrolling). Use `ScrollView`
+  when you actually want a scroller.
+- A `UITableView`/`RecyclerView` must not sit inside a `ScrollView` on
+  native — two scrollers fight and the framework throws. Wrap it in
+  `ScrollBox` instead.
+- `TextArea` `onSubmit`: web fires on Cmd/Ctrl+Enter; native fires only
+  when `returnKeyType` is `"done"` or `"send"` — otherwise every newline
+  reports as a submit.
+- `MaterialDialog` is a centered dialog when non-fullscreen on Android;
+  `UIModal` is a form sheet there. Context and theme don't cross modal
+  roots — read them inside the modal 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.
+- The shared `Drawer` is self-drawn: a left panel + backdrop on every
+  platform (backdrop fires `onDismiss`). The edge-gesture plugin widget is
+  `DrawerLayout`/`SideDrawer` in the platform subpaths.
+- `RichTextSpan` children carry their own `className`/`style`/`onPress`;
+  native maps spans to `FormattedString` runs.
+- `UITabBar`/`BottomNavigationView` give real per-pane navigation stacks
+  for `TabSpec.stack`; the shared `Tabs` keeps stack history in the route
+  store instead. On Android, Frame-in-TabViewItem is unreliable upstream
+  (NativeScript#11444) — prefer the shared `Tabs` there for stack panes.
+- 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
+
+- There is no shared `Modal`/`openModal` or `List` — import the platform
+  names from the subpaths, or compose `Sheet`/`ScrollView`.
+- 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/AGENTS.md

@@ -0,0 +1,9 @@
+# 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/nativescript.config.ts

@@ -4,6 +4,13 @@ export default {
 	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',

package/template/package.json

@@ -16,11 +16,13 @@
 		"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.4.0",
+		"@octane-xplat/ui": "^0.5.0",
 		"@valor/nativescript-websockets": "2.0.3",
 		"octane": "0.4.0"
 	},
@@ -30,12 +32,12 @@
 		"@nativescript/ios": "9.1.0",
 		"@nativescript/types": "9.0.0",
 		"@nativescript/vite": "8.0.11",
-		"@octane-xplat/cli": "^0.4.0",
+		"@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",
+		"oxlint": "^1.74.0",
 		"typescript": "5.9.3",
 		"vite": "8.3.0"
 	}

package/template/src/App.tsrx

@@ -1,5 +1,5 @@
 import { useState } from 'octane';
-import { View, Row, Text, Pressable, List, useColorScheme } from '@octane-xplat/ui';
+import { View, Row, Text, Pressable, ScrollView, useColorScheme } from '@octane-xplat/ui';
 
 const FEATURES = [
 	'shared components',
@@ -28,7 +28,9 @@ export function App() @{
 			<Pressable className="btn" onPress={() => setCount(count + 1)}><Text>+</Text></Pressable>
 		</Row>
 
-		<List items={FEATURES} renderItem={(f) => <Text className="chip">{f}</Text>} />
+		<ScrollView>
+			{FEATURES.map((f) => <Text className="chip">{f}</Text>)}
+		</ScrollView>
 
 		<Pressable className="link" onPress={() => setOverride(!dark)}>
 			<Text>{dark ? 'light' : 'dark'} mode (system: {scheme})</Text>

package/template/src/style.css

@@ -65,7 +65,7 @@ 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;
@@ -74,7 +74,7 @@ body {
 
 .chip {
 	background-color: var(--color-primary);
-	color: var(--color-on-primary);
+	color: var(--color-onprimary);
 	padding: 6px 14px;
 	border-radius: 14px;
 	corner-shape: squircle;