create-octane-xplat 0.6.0 → 0.7.0

package/README.md

@@ -1,30 +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
-pnpm typecheck      # web + native tsconfigs
 ```
 
-Docs: [Running and checking an app](https://octane-xplat.goddardai.org/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
+```
 
-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.
+[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.6.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,7 +14,7 @@ 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). Platform-authentic widgets live behind
@@ -37,7 +37,11 @@ document` checks). Platform-authentic widgets live behind
    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.
 
@@ -52,7 +56,7 @@ document` checks). Platform-authentic widgets live behind
   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.
 

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

@@ -6,7 +6,7 @@ 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.
+import them inside `.ios.tsrx`/`.android.tsrx`/`.mobile.tsrx` leaves.
 
 ## Shared — `@octane-xplat/ui` (self-drawn, same pixels everywhere)
 
@@ -52,9 +52,12 @@ inert layout below it).
 
 ## 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.
+- `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
 
@@ -77,10 +80,12 @@ inert layout below it).
   `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.
+- `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`.

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/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,9 +31,9 @@
 		"@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",
 		"nativescript": "9.1.1",
 		"oxlint": "^1.74.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`;