create-octane-xplat 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-octane-xplat",
-  "version": "0.4.0",
+  "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"

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/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/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,7 +32,7 @@
 		"@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",

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;