create-octane-xplat 0.5.0 → 0.7.0

package/README.md

@@ -1,25 +1,50 @@
 # 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`).
+> Get a TypeScript app running, then build its first useful flow with your
+> coding agent.
+
+xplat's target direction spans web, iOS, Android, macOS, and Windows. This
+starter configures **web, iOS, and Android**. macOS is a separate experiment;
+Windows has a separate experimental scaffold with runtime verification pending. See
+[target support](https://octane-xplat.goddardai.org/spec#choose-your-targets).
+The framework is `0.x` and its API surface is still changing.
+
+With Node.js and pnpm installed:
 
 ```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:
+The creator copies the template, installs dependencies with pnpm, and starts
+the web dev server. Open the printed URL and open `my-app` in your agent.
+Ask it to read `AGENTS.md` and `.agents/skills/xplat/SKILL.md`, then build a
+packing checklist with add, pack, and remove actions using in-memory state.
+Check the result before asking for the next feature: add “Passport” and
+“Charger,” pack Passport, and confirm that one item remains. Reloading should
+clear the list in this in-memory version. The
+[first-flow guide](https://octane-xplat.goddardai.org/toolchain#build-and-check-your-first-flow)
+includes the full prompt and failure checks.
+
+Leave the server running while you edit. After stopping it, restart from the
+app directory:
 
 ```sh
+cd my-app
 pnpm dev            # web
-pnpm dev:ios        # iOS simulator — needs the NativeScript toolchain
-pnpm dev:android    # Android — needs the NativeScript toolchain
+```
+
+From that directory, these commands run other targets or check the app:
+
+```sh
+pnpm dev:ios        # needs macOS, Xcode, and NativeScript setup
+pnpm dev:android    # needs Android SDK, compatible JDK, and NativeScript setup
+pnpm lint
 pnpm typecheck      # web + native tsconfigs
+pnpm build          # web production bundle
 ```
 
-Docs: [Running and checking an app](https://octane-xplat.goddardai.org/toolchain)
+[Get a working app and iterate](https://octane-xplat.goddardai.org/toolchain)
+provides prerequisites, live-update boundaries, and version guidance. The
+starter's xplat skill is included; NativeScript's official skills are optional
+and installed separately. Ask your agent to report checks and targets actually
+run. [llms.txt](https://octane-xplat.goddardai.org/llms.txt) indexes the docs.

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "create-octane-xplat",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Scaffold a minimal @octane-xplat/ui app — one Octane codebase for web + iOS + Android",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octane-xplat/octane-xplat.git",
+    "directory": "packages/create"
+  },
   "bin": {
     "create-octane-xplat": "./index.mjs"
   },

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

@@ -14,10 +14,13 @@ below prevent that; `pnpm lint` enforces most of them.
 
 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` —
+   — `.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).
+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
@@ -34,7 +37,11 @@ below prevent that; `pnpm lint` enforces most of them.
    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`).
+   `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.
 
@@ -49,18 +56,18 @@ below prevent that; `pnpm lint` enforces most of them.
   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
+- `.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.
 
 ## 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 |
+| 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)
 
@@ -74,4 +81,4 @@ below prevent that; `pnpm lint` enforces most of them.
 - 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.
+  record explains _why_ a constraint exists — rarely needed for app work.

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

@@ -1,49 +1,98 @@
-# 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` |
+# 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 `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.
+  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.
-- `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.
+- `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.
-- `Drawer` has an edge-swipe gesture on native only — give web users a
-  visible toggle.
+- 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
 
-- `PlatformBadge` is an internal probe, not app vocabulary — don't use it.
-- `keyFor` on `List` is web-only.
+- 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

@@ -19,12 +19,15 @@ call sites drive both.
 - **Back** — browser back, hardware back (Android), and swipe-back (iOS)
   all map to `popRoute` on the current stack.
 
-## Known gap
+## Named stacks
 
-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.
+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

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

@@ -1,44 +1,44 @@
 # 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`,
+Import a capability through the package barrel. The unsuffixed module is its
+native default, `.web` is the browser implementation, and `.mobile` or an OS
+suffix narrows behavior when needed. Surface: `device`, `appInfo`, `locale`,
 `connectivity`, `useWindowSize`, `useAppState`, `useSafeAreaInsets`, deep
 links, clipboard, `secureStorage`, haptics, notifications, `announce`,
 `systemBars`, geolocation, permissions, media, files, share, `openUrl`,
 `openSettings`, biometrics.
 
-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.
+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:
+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
+src/parts/Scanner.tsrx          native default
+src/parts/Scanner.web.tsrx      browser implementation (camera via getUserMedia)
+src/parts/Scanner.mobile.tsrx   shared iOS/Android implementation
+src/parts/Scanner.ios.tsrx      iOS-only override
 ```
 
-Import the bare specifier (`./Scanner.impl`); the bundler picks the leaf
-via the suffix chain `.ios` → `.android` → `.native` → shared / `.web` →
-shared.
+Import the bare specifier (`./Scanner`); the bundler selects `.web` first on
+web and the most specific native variant on each OS. The `.mobile` variant
+overrides the unsuffixed native default on iOS and Android.
 
 Leaf rules:
 
-- Inside 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.
+- Inside `.web.*`, DOM APIs are expected; NativeScript imports belong in
+  `.mobile.*`, `.ios.*`, `.android.*`, or the unsuffixed native default. If
+  browser code imports that default, add a `.web.*` sibling.
 - Never read app-level NativeScript globals (`Application.android.*`)
-  at module top — read them inside the call. Top-level reads crash cold
-  start before the app exists.
-- `.native.tsrx` files with JSX start with
+  at module top — read them inside the call. Top-level reads crash cold start
+  before the app exists.
+- Native-specific `.tsrx` files containing JSX start with
   `/** @jsxImportSource @nativescript-community/octane */` on line 1.
 - Deep imports under `@nativescript/core/ui/*` bundle as a second module
   instance — import from `@nativescript/core` only.

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

@@ -1,6 +1,6 @@
 # Styling
 
-Two channels, chosen by *when the value is known*:
+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,

package/template/AGENTS.md

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

package/template/App_Resources/iOS/src/ShaderEffectRegistration.swift

@@ -0,0 +1,31 @@
+import SwiftUI
+
+// Registers the app's stitchable shaders (OctaneShaders.metal) by name for
+// @octane-xplat/effects' <ShaderEffect>. Names are runtime strings because
+// ShaderLibrary lookups are compile-time — registration is the dispatch
+// table. Call `OctaneShaderEffects.install()` from JS before rendering a
+// ShaderEffect (`declare const OctaneShaderEffects: any`).
+//
+// Pair-bound: this file + OctaneShaders.metal + the @octane-xplat/effects
+// dependency go together — delete all three if you don't want shader
+// effects.
+@objc(OctaneShaderEffects)
+public final class OctaneShaderEffects: NSObject {
+	@objc public static func install() {
+		XplatShaderEffectRegistry.register("heatHaze", kind: .distortion) { args in
+			ShaderLibrary.octaneHeatHaze(
+				.float(args.f("time")), .float2(args.size), .float(args.f("intensity"))
+			)
+		}
+		XplatShaderEffectRegistry.register("sheen", kind: .color) { args in
+			ShaderLibrary.octaneSheen(
+				.float(args.f("time")), .float2(args.size), .float(args.f("intensity"))
+			)
+		}
+		XplatShaderEffectRegistry.register("shatter", kind: .layer) { args in
+			ShaderLibrary.octaneShatter(
+				.float2(args.size), .float(args.f("progress"))
+			)
+		}
+	}
+}

package/template/package.json

@@ -2,7 +2,7 @@
 	"name": "octane-xplat-app",
 	"private": true,
 	"type": "module",
-	"main": "src/index.native.ts",
+	"main": "src/index.ts",
 	"scripts": {
 		"xplat": "xplat",
 		"dev": "vite",
@@ -18,13 +18,12 @@
 	"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",
+		"@octane-xplat/effects": "^0.7.0",
+		"@octane-xplat/ui": "^0.7.0",
 		"@valor/nativescript-websockets": "2.0.3",
-		"octane": "0.4.0"
+		"octane": "0.6.3"
 	},
 	"devDependencies": {
 		"@nativescript-community/vite-octane": "0.2.1",
@@ -32,12 +31,12 @@
 		"@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",
+		"@octane-xplat/cli": "^0.7.0",
+		"@octane-xplat/lint": "^0.7.0",
+		"@octanejs/vite-plugin": "0.1.61",
 		"@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/patches/@nativescript-community__octane@0.2.1.patch

@@ -0,0 +1,16 @@
+diff --git a/dist/driver.js b/dist/driver.js
+index f485f992282c05c58fed810458303be3141f51c0..9b5a654cf0c32be5fc6da4ae5fec04a58560925f 100644
+--- a/dist/driver.js
++++ b/dist/driver.js
+@@ -83,6 +83,11 @@ function setProp(node, view, name, value) {
+         setRenderItem(view, value ?? null, createNativeScriptRoot);
+         return;
+     }
++    // `undefined` means "prop not supplied" — skip the write. NativeScript
++    // native setters coerce it (e.g. editable → ios.userInteractionEnabled =
++    // NO) leaving dead UI that still has its JS listeners.
++    if (value === undefined)
++        return;
+     // Core raises `<name>Change` for a script write exactly as for a user
+     // edit; a controlled input must not see its own value come back as one.
+     const echo = `${name}Change`;