@stacksjs/defaults 0.75.226 → 0.75.227

package/ai/skills/stacks-mobile/SKILL.md

@@ -49,10 +49,19 @@ platform-specific commands when iterating on only one native target. The same
 targets are available through `buddy build mobile`, `buddy build ios`, and
 `buddy build android`.
 
-The build validates `config/mobile.ts`, initializes a Craft iOS project,
-selects either a remote application URL or bundled web assets, generates the
-Xcode project with xcodegen, and records source, capability, and Craft builder
-revision provenance in `stacks-mobile.json`.
+The build validates `config/mobile.ts`, compiles configured STX native screens,
+initializes the Craft platform project and records source, capability and builder
+revision provenance in `stacks-mobile.json`. With `renderer: 'native'`, Craft
+draws platform controls from the compiled bundle without a WebView. The same STX
+components and TypeScript behavior can also serve browser routes; keep browser
+route adapters thin and share the component implementation. Native capabilities
+still depend on the host, OS, hardware and permission.
+
+With `renderer: 'web'`, Craft loads a remote page or bundled web assets. This is
+a separate renderer configuration. A native renderer's `url` supplies its API
+and fallback browser origin; it does not fetch the native UI from that URL at
+launch. Changes to bundled screens, native code or capabilities require a new
+app build. API data refreshes independently.
 
 xcodegen comes from Pantry, never from `PATH`: the version is
 `iosDependencies` in `config/deps.ts` (beside `androidDependencies`; the
@@ -93,10 +102,12 @@ import type { MobileConfig } from '@stacksjs/types'
 
 export default {
   ios: {
+    renderer: 'native',
+    nativeScreens: { '/m/': 'Home' },
+    nativeScreensDir: 'resources/components',
     appName: 'My App',
     bundleId: 'com.example.app',
     url: 'https://example.com',
-    fallbackWebAssets: 'dist',
     deploymentTarget: '16.0',
     orientations: ['portrait'],
     urlSchemes: ['myapp'],
@@ -108,10 +119,12 @@ export default {
     },
   },
   android: {
+    renderer: 'native',
+    nativeScreens: { '/m/': 'Home' },
+    nativeScreensDir: 'resources/components',
     appName: 'My App',
     packageName: 'com.example.app',
     url: 'https://example.com',
-    fallbackWebAssets: 'dist',
     capabilities: {
       haptics: true,
       share: true,
@@ -122,13 +135,21 @@ export default {
 } satisfies MobileConfig
 ```
 
-Choose exactly one primary content source:
+For the native renderer, every app-owned route must map to an STX screen in
+`nativeScreens` on both platforms. The example maps `/m/` to
+`resources/components/Home.stx`; browser routes should render that same shared
+component rather than duplicate it. Compile and test the actual screen bundle
+for both targets. External authorization or checkout routes may use the system
+browser with an explicit return path.
+
+For the web renderer, choose a primary content source:
 
 - `url`: load the deployed Stacks application and keep server-rendered routes.
 - `webAssets`: bundle a static distribution containing `index.html` and every
   referenced asset.
-- `fallbackWebAssets`: with `url`, bundle a static distribution that Craft
-  loads when the remote application is unreachable on cold start.
+- `fallbackWebAssets`: optionally pair with `url` to load bundled web assets
+  when the remote page is unreachable on cold start. This does not supply an
+  offline native UI; native screens are already in their compiled bundle.
 
 Only enable capabilities the product uses. Craft turns enabled capabilities
 into native bridge availability and required iOS privacy descriptions.
@@ -145,7 +166,9 @@ the default `deploymentTarget` stays, older systems drawing classic bars.
 
 ## Native screen bindings
 
-Screens under `resources/native/` use the same STX client syntax as web views.
+Screens in `nativeScreensDir` (default `resources/native/`) use the same STX
+client syntax as web views. Point it at the shared component directory when
+those components also serve browser routes.
 Declare reactive data in `<script client>` and bind text with `:text`, props
 with `:prop`, and native presses with `@click`. Pull-to-refresh uses `@refresh`
 and a boolean `:refreshing` signal. Bare signals auto-unwrap in bindings;
@@ -394,9 +417,14 @@ The runtime is browser-safe. Craft-backed operations use the native bridge;
 supported web APIs provide fallback behavior outside a native host. Inside a
 native host whose bridge is still loading (an older shell installs it after
 the page loads), a call waits for it briefly instead of taking the web path.
-Nothing throws for being unsupported: it resolves `null` or `false`.
+Unsupported behavior belongs to each service's contract: some availability
+queries return `false`, while permission requests, writes and operations that
+must enforce identity may reject. Check the documented capability predicate
+and handle typed errors; never treat a missing native method as success or
+silently replace a guarded operation with an unguarded fallback.
 
-Beyond the services above, each with a web fallback:
+Other services include the following; browser behavior and native support vary
+by operation:
 
 ```ts
 import { browser, clipboard, confirmAction, contextMenu, db, dialog, files, haptics, orientation, shortcuts, storeKit, symbols, useActionSheet, widgets } from '@stacksjs/mobile'
@@ -421,12 +449,20 @@ settles.
 
 For a run or ride, `createRouteRecorder({ location, onUpdate })` starts, pauses,
 resumes and stops the native recording, re-attaches to one that outlived the
-app (`attach()`), and reports live distance and pace from `routeStats(fixes)`,
+app (`attach({ expectedId })` with the ID saved in the account's draft), and reports live distance and pace from `routeStats(fixes)`,
 which ignores GPS drift, inaccurate fixes and the ground crossed during a pause.
 Recorder operations serialize; repeated `stop()` returns the same recording.
 Call `dispose()` when the owning page is destroyed to stop polling without
 stopping the native recording. Refreshes coalesce and cannot overwrite a final
-recording with a stale read.
+recording with a stale read. Persist `recordingId` (and `heartRateRecordingId`
+when bundled) under the account and workout that started it. Never adopt the
+current native slot without its saved ID. Guarded metadata, reads and stop
+recover that ID's completed archive even if another recording is now active.
+Only after durably checkpointing its result, or committing its discard, call
+`location.acknowledgeRecording({ expectedId })` and the matching heart-rate
+acknowledgement. A storage failure must retain the native copy. Ownership
+operations require support from both the SDK adapter and the native host;
+unsupported hosts reject with `RECORDING_OWNERSHIP_UNSUPPORTED`.
 
 For timestamp-based timers use `startSessionClock(now)`,
 `pauseSessionClock(clock, now)`, `resumeSessionClock(clock, now)` and

package/ai/skills/stacks-native/CATALOG.md

@@ -60,7 +60,7 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@stacksjs/image` | [`stacks-image`](../stacks-image/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/image/src/index.ts) | 2 |
 | `@stacksjs/lint` | [`stacks-lint`](../stacks-lint/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/lint/src/index.ts) | 3 |
 | `@stacksjs/logging` | [`stacks-logging`](../stacks-logging/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/logging/src/index.ts) | 14 |
-| `@stacksjs/mobile` | [`stacks-mobile`](../stacks-mobile/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/index.ts) | 18 |
+| `@stacksjs/mobile` | [`stacks-mobile`](../stacks-mobile/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/index.ts) | 22 |
 | `@stacksjs/model-meta` | [`stacks-models`](../stacks-models/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/model-meta/src/index.ts) | 1 |
 | `@stacksjs/newsletter` | [`stacks-newsletter`](../stacks-newsletter/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/newsletter/src/index.ts) | 7 |
 | `@stacksjs/notifications` | [`stacks-notifications`](../stacks-notifications/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/index.ts) | 15 |
@@ -583,9 +583,9 @@ Guidance: [`stacks-mobile`](../stacks-mobile/SKILL.md). Source: [storage/framewo
 
 Declared runtime exports: `appReview`, `biometrics`, `brightness`, `camera`, `deepLinks`, `device`, `getNativeMobileBridge`, `haptics`, `health`, `heartRate`, `isNativeMobile`, `keepAwake`, `lifecycle`, `liveActivities`, `location`, `mobile`, `music`, `network`, `normalizeDeepLinkURL`, `notifications`, `onMobileReady`, `permissions`, `pushNotifications`, `secureStorage`, `share`, `snapshots`, `speech`, `splash`, `watchConnectivity`, `whenNativeMobile`, `withNativeFeedback`.
 
-Local source modules: [src/bridge.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/bridge.ts), [src/controls.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/controls.ts), [src/crash-reporting.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/crash-reporting.ts), [src/events.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/events.ts), [src/gestures.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/gestures.ts), [src/indoor.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/indoor.ts), [src/native.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/native.ts), [src/navigation.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/navigation.ts), [src/refresh-control.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/refresh-control.ts), [src/route.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/route.ts), [src/scheduled-workouts.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/scheduled-workouts.ts), [src/session-clock.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/session-clock.ts), [src/sheet-gesture.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/sheet-gesture.ts), [src/sheets.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/sheets.ts), [src/shell.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/shell.ts), [src/spotlight.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/spotlight.ts), [src/tab-bar.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/tab-bar.ts), [src/types.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/types.ts).
+Local source modules: [src/bridge.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/bridge.ts), [src/controls.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/controls.ts), [src/crash-reporting.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/crash-reporting.ts), [src/crypto.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/crypto.ts), [src/events.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/events.ts), [src/gestures.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/gestures.ts), [src/indoor.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/indoor.ts), [src/native.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/native.ts), [src/navigation.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/navigation.ts), [src/refresh-control.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/refresh-control.ts), [src/route.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/route.ts), [src/scheduled-workouts.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/scheduled-workouts.ts), [src/session-clock.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/session-clock.ts), [src/sheet-gesture.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/sheet-gesture.ts), [src/sheets.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/sheets.ts), [src/shell.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/shell.ts), [src/spotlight.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/spotlight.ts), [src/storage.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/storage.ts), [src/tab-bar.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/tab-bar.ts), [src/types.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/types.ts).
 
-Evidence directory: [18 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [22 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/model-meta
 

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.226",
+  "version": "0.75.227",
   "description": "Stacks, built into VS Code: stx templates, pickier linting and formatting, encrypted env files, the dev server preview and every buddy command. No other extensions required.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.226",
+  "version": "0.75.227",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -44,7 +44,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "0.75.226",
+    "@stacksjs/mobile": "0.75.227",
     "@stacksjs/sanitizer": "^0.2.534",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",