create-octane-xplat 0.7.3 → 0.10.0

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

@@ -1,9 +1,9 @@
 ---
 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.
+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
+# 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
@@ -12,53 +12,122 @@ 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
-   — `.web` for browser code, `.mobile` for shared iOS/Android variants, OS-specific suffixes, and the unsuffixed native default —
-   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`). `query$` reads
-   suspend — put `.get()` under `@try`/`@pending`/`@catch`, or use
-   `.snapshot()`/`.latest()` for non-suspending reads. Never write to a
-   shared signal during render — screen-scoped data keyed by route params
-   gets a component-local `query$`, not a shared selector signal.
-6. **One `octane` per app.** Don't add a second renderer or duplicate the
-   package — two copies break the reconciler without a helpful error.
+**One element vocabulary per file.** Shared code renders only
+`@octane-xplat/ui` components. Platform divergence lives in whole files
+— `.web` for browser code, `.mobile` for shared iOS/Android variants, OS-specific suffixes, and the unsuffixed native default —
+chosen by the bundler when something imports `./Foo`. Never branch on
+platform inside JSX (`Platform.OS`, conditional imports, checks for browser globals). 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).
+**No DOM globals in shared code.** `document`, `window`, `localStorage`,
+DOM events — all web-only. Device capabilities (clipboard, storage,
+permissions, connectivity) come from
+`@octane-xplat/platform`; plugin-backed features use their leaf packages.
+**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`, …).
+**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'`.
+**Keep signal names suffixed with `$`.** Use `useSignal$` for state owned
+by a component. Runtime signal imports let the compiler track reads.
+
+```tsrx
+import { useSignal$ } from 'octane/signals/client'
+import { Pressable, Text } from '@octane-xplat/ui'
+
+export function Counter() {
+  const count$ = useSignal$(0)
+  return <Pressable onPress={() => count$.set((value) => value + 1)}>
+    <Text>{count$.get()}</Text>
+  </Pressable>
+}
+```
+
+Use `signal$` for shared module state and `derived$` for a computed value.
+Write from event handlers, not while rendering.
+
+```ts
+import { signal$, derived$ } from 'octane/signals'
+
+export const travelers$ = signal$(1)
+export const seatsRemaining$ = derived$(() => 4 - travelers$.get())
+export function addTraveler() {
+	travelers$.set((count) => count + 1)
+}
+```
+
+`query$` loads asynchronous data. A screen-owned query keeps its selection
+local to the screen. `.latest()` reads without suspending; use the data
+guide's boundary pattern when reading with `.get()`.
+
+```tsrx
+import { query$ } from 'octane/signals'
+import { Text } from '@octane-xplat/ui'
+
+export function TripTitle(props: { id: string; loadTitle: (id: string) => Promise<string> }) {
+  const title$ = query$(() => props.id, (id) => props.loadTitle(id))
+  return <Text>{title$.latest() ?? 'Loading trip…'}</Text>
+}
+```
+
+**One `octane` per app.** Don't add a second renderer or duplicate the
+package — two copies break the reconciler without a helpful error.
+
+For component, routing, service, and styling usage, use the references below.
+They show the supported names and matching code examples.
 
 ## 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 `@`.
+- Literal `@{` in JSX text parses as a code block. Render the sign separately:
+
+```tsrx
+import { Text } from '@octane-xplat/ui'
+
+export function Handle() { return <Text>{'@'}{'traveler'}</Text> }
+```
+
 - 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.
+  declare dependencies explicitly when needed:
+
+```tsrx
+import { useLayoutEffect } from 'octane'
+import { Text } from '@octane-xplat/ui'
+
+export function Progress(props: { percent: number }) {
+  useLayoutEffect(() => { console.log('Progress changed') }, [props.percent])
+  return <Text>{props.percent}%</Text>
+}
+```
+
+- Input handlers must be idempotent: store the supplied value rather than
+  incrementing a counter for each input event. Web may dispatch more than once.
+
+```tsrx
+import { useState } from 'octane'
+import { TextInput } from '@octane-xplat/ui'
+
+export function NameField() {
+  const [name, setName] = useState('')
+  return <TextInput value={name} onChange={setName} accessibilityLabel="Name" />
+}
+```
+
 - `.mobile.tsrx`/`.ios.tsrx`/`.android.tsrx` files and unsuffixed native-default files containing JSX must
   start with `/** @jsxImportSource @nativescript-community/octane */` on
-  line 1 — nothing may precede it.
+  line 1 — nothing may precede it:
+
+```tsrx
+/** @jsxImportSource @nativescript-community/octane */
+import { Text } from '@octane-xplat/ui'
+
+export function NativeGreeting() { return <Text>Hello</Text> }
+```
 
 ## Verify
 

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

@@ -1,98 +1,151 @@
 # 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`/`.mobile.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` — shared root export; web avoids via the
-  `visualViewport` inset, iOS/Android via OS keyboard events, macOS leaf
-  is an inert column.
-- `Hoverable`, `Tooltip` — shared root exports; pointer platforms (web,
-  macOS) mount the hint layer, touch targets render only the trigger —
-  keep essential information out of `card`/`content`.
-
-## 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 platform-authentic tab chrome for
-  `TabSpec.stack`; pushed screens render inside the pane either way —
-  through a real per-pane `Frame` on iOS, and through the route store on
-  Android (Frame-in-TabViewItem bookkeeping is unreliable upstream,
-  NativeScript#11444). The shared `Tabs` uses the same route-store pane on
-  both.
-- 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.
+Use shared components for screens that work across targets. Put these examples
+in `.tsrx` files; style their classes in the app's CSS.
+
+```tsrx
+import { VStack, HStack, Text, Pressable } from '@octane-xplat/ui'
+
+export function Welcome() {
+  return <VStack className="welcome">
+    <Text>Plan your next trip</Text>
+    <HStack><Pressable onPress={() => console.log('Start planning')}>
+      <Text>Start planning</Text>
+    </Pressable></HStack>
+  </VStack>
+}
+```
+
+## Shared component inventory
+
+| Need                  | Component(s)                                                                  |
+| --------------------- | ----------------------------------------------------------------------------- |
+| Layout                | `View`, `VStack`, `HStack`, `Grid`, `Stack`, `Absolute`, `Spacer`, `SafeArea` |
+| Text                  | `Text`, `Heading`, `RichText`, `RichTextSpan`                                 |
+| Tap                   | `Pressable`, `Button`, `Link`, `NavLink`                                      |
+| Input                 | `TextInput`, `TextArea`, `Switch`, `Slider`                                   |
+| Scrolling             | `ScrollableArea`, `VirtualList`                                               |
+| Media                 | `Image`, `Icon`                                                               |
+| Feedback              | `Spinner`, `Meter`, `showToast`                                               |
+| Overlays              | `BottomSheet`, `Overlay`, `Popover`, `Drawer`, `HoverCard`, `Tooltip`         |
+| Shells                | `Screen`, `Tabs`                                                              |
+| Theme and measurement | `useColorScheme`, `useSafeAreaInsets`, `useMeasure`                           |
+
+`ScrollableArea` scrolls a bounded set of children. For a long list, use
+`VirtualList` so the app does not mount every row at once.
+
+```tsrx
+import { ScrollableArea, VirtualList, Text } from '@octane-xplat/ui'
+
+const destinations = [{ id: 'oslo', name: 'Oslo' }, { id: 'rome', name: 'Rome' }]
+
+export function Destinations() {
+  return <>
+    <ScrollableArea><Text>Choose your next destination</Text></ScrollableArea>
+    <VirtualList items={destinations} keyExtractor={(item) => item.id}
+      renderItem={(item) => <Text>{item.name}</Text>} />
+  </>
+}
+```
+
+Text fields keep the platform's keyboard, caret, selection, and input methods.
+Use `onChange` to store the new value. `KeyboardAvoiding` helps keep the field
+visible when the keyboard opens.
+
+```tsrx
+import { useState } from 'octane'
+import { KeyboardAvoiding, TextInput } from '@octane-xplat/ui'
+
+export function TravelerName() {
+  const [name, setName] = useState('')
+  return <KeyboardAvoiding>
+    <TextInput accessibilityLabel="Traveler name" placeholder="Your name"
+      value={name} onChange={setName} />
+  </KeyboardAvoiding>
+}
+```
+
+`TextArea` supports multiline text. Its submit shortcut is Cmd/Ctrl+Enter on
+web; native submits with `returnKeyType="done"` or `"send"`.
+
+```tsrx
+import { useState } from 'octane'
+import { TextArea } from '@octane-xplat/ui'
+
+export function TravelNotes() {
+  const [notes, setNotes] = useState('')
+  return <TextArea value={notes} onChange={setNotes} returnKeyType="done"
+    onSubmit={() => console.log(notes)} accessibilityLabel="Travel notes" />
+}
+```
+
+`BottomSheet` opens above the current screen. Keep its open state in your
+component and give it a label that explains its purpose.
+
+```tsrx
+import { useState } from 'octane'
+import { BottomSheet, Pressable, Text } from '@octane-xplat/ui'
+
+export function TripHelp() {
+  const [open, setOpen] = useState(false)
+  return <>
+    <Pressable onPress={() => setOpen(true)}><Text>Trip help</Text></Pressable>
+    <BottomSheet label="Trip help" isOpen={open} onOpenChange={setOpen}>
+      <Text>You can change your destination later.</Text>
+    </BottomSheet>
+  </>
+}
+```
+
+`RichTextSpan` gives individual text runs their own style or press handler.
+Native uses formatted text runs for these spans.
+
+```tsrx
+import { RichText, RichTextSpan } from '@octane-xplat/ui'
+
+export function TripStatus() {
+  return <RichText>
+    <RichTextSpan text="Your trip is " />
+    <RichTextSpan text="ready" className="status-ready"
+      onPress={() => console.log('Show trip')} />
+  </RichText>
+}
+```
+
+## Platform widgets
+
+Choose platform widgets when you want the OS's own controls. Import them only
+in the matching platform file. This iOS example belongs in `Preference.ios.tsrx`:
+
+```tsrx
+/** @jsxImportSource @nativescript-community/octane */
+import { useState } from 'octane'
+import { UISwitch } from '@octane-xplat/ui/ios'
+
+export function Preference() {
+  const [checked, setChecked] = useState(false)
+  return <UISwitch checked={checked} onCheckedChange={setChecked} />
+}
+```
+
+The Android equivalent belongs in `Preference.android.tsrx`:
+
+```tsrx
+/** @jsxImportSource @nativescript-community/octane */
+import { useState } from 'octane'
+import { MaterialSwitch } from '@octane-xplat/ui/android'
+
+export function Preference() {
+  const [checked, setChecked] = useState(false)
+  return <MaterialSwitch checked={checked} onCheckedChange={setChecked} />
+}
+```
+
+| Platform | Additional widget names                                                                                                          |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| iOS      | `UISlider`, `UIActivityIndicatorView`, `UITableView`, `UITabBar`, `UIModal`, `SideDrawer`, `LiquidGlass`, `LiquidGlassContainer` |
+| Android  | `SeekBar`, `CircularProgressIndicator`, `RecyclerView`, `BottomNavigationView`, `MaterialDialog`, `DrawerLayout`                 |
+
+Keep platform lists outside other scrolling containers. Use a layout container
+around the list; see the [components guide](https://octane-xplat.goddardai.org/components)
+for overlay, hover, tab, and accessibility examples and their platform limits.

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

@@ -1,33 +1,83 @@
 # 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.
-
-## Named stacks
-
-Pushing into a named stack (`{ into: 'stackName' }`) works on all three
-targets: web pushes into the nested outlet, iOS navigates a real `Frame`
-when the platform `UITabBar` registered one (and uses the route store
-under the shared `Tabs`), and Android always uses the router-owned
-swap-pane — pushed screens render inside the active tab pane.
-`popRoute(stack)`/`useRoute(stack)` behave the same either way, so app
-code never sees which mechanism ran.
-
-For loaders, route config, and generated route types, see the navigation
-guide: https://octane-xplat.goddardai.org/navigation
+Register screens once during app startup. A route names a screen and a stack;
+web turns it into a URL, while native presents the screen in the app's navigation.
+Put components in `.tsrx` files.
+
+```tsrx
+import { defineRoutes, registerRoutes, Text } from '@octane-xplat/ui'
+
+function Home() { return <Text>Home</Text> }
+function Settings() { return <Text>Settings</Text> }
+
+registerRoutes(defineRoutes([
+  { path: '/', screen: Home },
+  { path: '/settings', screen: Settings },
+]))
+```
+
+After registering `settings`, use `NavLink` for a screen link or `pushRoute`
+in an event handler. `Link` accepts a URL, including an external website.
+
+```tsrx
+import { HStack, Link, NavLink, Pressable, Text, pushRoute } from '@octane-xplat/ui'
+
+export function SettingsLinks() {
+  const settings = { stack: 'root', name: 'settings', params: {} }
+  return <HStack>
+    <NavLink route={settings}><Text>Settings</Text></NavLink>
+    <Pressable onPress={() => pushRoute(settings)}><Text>Open settings</Text></Pressable>
+    <Link href="https://octane-xplat.goddardai.org"><Text>Documentation</Text></Link>
+  </HStack>
+}
+```
+
+Use `useRoute` to read the current screen and `useCanGoBack` to decide whether
+to offer a back button. Pass the same stack name to `popRoute`.
+
+```tsrx
+import { Pressable, Text, useRoute, useCanGoBack, popRoute } from '@octane-xplat/ui'
+
+export function NavigationStatus() {
+  const route = useRoute('root')
+  const canGoBack = useCanGoBack('root')
+  return <>
+    <Text>{route?.name ?? 'Home'}</Text>
+    <Pressable disabled={!canGoBack} onPress={() => popRoute('root')}>
+      <Text>Back</Text>
+    </Pressable>
+  </>
+}
+```
+
+Prefer string IDs in route params: generated route helpers use string params,
+and IDs make URLs shareable. The low-level router JSON-encodes object params
+on web with a warning; do not rely on it to carry application state. With a
+registered `/projects/:id` screen, navigate using the project ID:
+
+```ts
+import { pushRoute } from '@octane-xplat/ui'
+
+pushRoute({ stack: 'root', name: 'projects/:id', params: { id: '42' } })
+```
+
+Named tab stacks keep each tab's navigation separate. `Tabs` renders the tab's
+initial content; pushing a route into that stack opens it inside the tab pane.
+The screen below assumes `settings` is already registered.
+
+```tsrx
+import { Tabs, Text, Pressable, pushRoute } from '@octane-xplat/ui'
+
+export function AppTabs() {
+  return <Tabs tabs={[
+    { title: 'Home', stack: 'home', render: () => <Text>Home</Text> },
+    { title: 'Account', stack: 'account', render: () =>
+      <Pressable onPress={() => pushRoute({ stack: 'account', name: 'settings', params: {} })}>
+        <Text>Settings</Text>
+      </Pressable> },
+  ]} />
+}
+```
+
+For loaders, deep links, route config, and generated route types, see the
+[navigation guide](https://octane-xplat.goddardai.org/navigation).