@stacksjs/defaults 0.75.97 → 0.75.98

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-dashboard
-description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 410 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
+description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 413 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,7 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Dashboard
 
-The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 410 components, and a multi-section layout.
+The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 413 components, and a multi-section layout.
 
 ## Key Paths
 - Dashboard components: `storage/framework/defaults/resources/components/Dashboard/`

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

@@ -96,6 +96,16 @@ Choose exactly one primary content source:
 Only enable capabilities the product uses. Craft turns enabled capabilities
 into native bridge availability and required iOS privacy descriptions.
 
+The shell's behaviour around the page defaults to a native app's; set only
+what should differ: `swipeBack` (`'router'`, the stx router's interactive
+swipe, or `'webview'` for WebKit's history swipe), `keyboardAccessory` (off),
+`allowsLinkPreview` (off), `disableZoom` (on), `splashMaxSeconds` (3),
+`requestTimeoutSeconds` (10), `backgroundRefresh: { enabled, identifier?,
+minimumIntervalMinutes? }` and `associatedDomains` (universal links). Leave
+`swipeNavigation` unset: WebKit's swipe alongside the router's fights it, and
+`buddy build:ios` warns. The Liquid Glass chrome needs iOS 26 at run time;
+the default `deploymentTarget` stays, older systems drawing classic bars.
+
 ## Device search index
 
 `spotlight` says what of the application's own content a device may index, so
@@ -166,7 +176,33 @@ await withNativeFeedback(() => saveActivity())
 ```
 
 The runtime is browser-safe. Craft-backed operations use the native bridge;
-supported web APIs provide fallback behavior outside a native host.
+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`.
+
+Beyond the services above, each with a web fallback:
+
+```ts
+import { browser, clipboard, confirmAction, contextMenu, db, dialog, files, haptics, orientation, shortcuts, storeKit, symbols, useActionSheet, widgets } from '@stacksjs/mobile'
+
+await dialog.alert({ title: 'Saved' }) // UIAlertController, or an HTML alert
+if (await confirmAction({ title: 'Delete this workout?', confirmLabel: 'Delete', destructive: true })) remove()
+const id = await useActionSheet()({ actions: [{ id: 'skip', title: 'Skip' }] }) // null when cancelled
+await contextMenu.show({ items, anchor }) // UIMenu, or an HTML menu over the blurred page
+await browser.open(url, { mode: 'auth', callbackScheme: 'myapp' }) // ASWebAuthenticationSession
+await symbols.image('heart.fill') // an SF Symbol as a PNG data URL, cached
+await haptics.prepare('impact') // wake the Taptic Engine before a likely tap
+```
+
+Also `statusBar`, `chrome` (under-page colour, keyboard accessory),
+`refresh` (the native UIRefreshControl), `background.complete`, `clipboard`,
+`db` (the app's SQLite), `files` (PDF, screenshot, QR scan, pick, save,
+download), `shortcuts` (home screen quick actions), `widgets`,
+`orientation`, `auth.signInWithApple` and `storeKit`. The phone's events:
+`onAppearance`, `onResume`, `onMemoryWarning`, and `onSilentPush` /
+`onBackgroundRefresh`, which tell iOS the work is done when the handler
+settles.
 
 For a run or ride, `createRouteRecorder({ location, onUpdate })` starts, pauses,
 resumes and stops the native recording, re-attaches to one that outlived the
@@ -176,6 +212,12 @@ which ignores GPS drift, inaccurate fixes and the ground crossed during a pause.
 ## STX components
 
 - `<NativeAppShell>` applies iOS safe-area insets and reserves tab-bar space.
+  In the phone app it sets the system font at the Dynamic Type size (the
+  components size in `em` off `--native-font-size`), drops the tap flash and
+  double-tap delay, gives `data-native-pressable` elements UIKit's pressed
+  state (and wakes the haptics as a finger lands), and keeps the under-page
+  colour, status bar, keyboard bar and Reduce Motion
+  (`data-native-reduce-motion` on the root) in step with the page.
 - `<NativeTabBar>` provides the accessible navigation shell and selection haptics.
 - `<NativeTabItem>` provides each route, active state, label, and Iconify icon.
 - `<NativeShareButton>` opens the native share sheet and reports feedback.
@@ -183,15 +225,29 @@ which ignores GPS drift, inaccurate fixes and the ground crossed during a pause.
 - `<NativePermissionButton>` wraps permission status, requests, haptics, and the native Settings escape hatch.
 - `<NativeHealthButton>` requests the minimal Apple Health or Android Health Connect grants.
 - `<NativeNavBar>` is the iOS navigation bar: a large title that collapses into
-  the bar as the page scrolls, a back button (`back="/parent"`) that goes back
+  the bar with the scroll, a frame at a time (and stretches when pulled past
+  the top), a `chevron.backward` back button (`back="/parent"`) that goes back
   through history when the app pushed the screen, and `leading` / `actions`
   slots. Pass `:large="false"` on a pushed screen; `title` is reactive.
 - `<NativePullToRefresh @refresh="reload">` refreshes the page when pulled from
-  its top. The event carries `done()`: call it when the new data is in.
+  its top: the phone's own UIRefreshControl in the shell, the 12-spoke
+  indicator with the content held down elsewhere. The event carries `done()`:
+  call it when the new data is in. `scrollHost=".list"` for a screen that
+  scrolls in a container.
 - `<NativeSegmentedControl :options="[...]" v-model:value="range">` switches
-  between views of one screen, with selection haptics.
+  between views of one screen, with selection haptics, thumb scrubbing and
+  arrow keys.
 - `<NativeSheet v-model:open="editing" title="…">` raises a bottom sheet for a
-  task that belongs to the screen, above the tab bar.
+  task that belongs to the screen: dragged down from its grabber or header to
+  dismiss, the page behind inert. `detents="medium large"` makes it full
+  height with detents, the page pressed into a card at large.
+- `<NativeContextMenu :items="[...]" @select="…">` opens a menu on a
+  half-second press: UIMenu in the shell, an HTML menu elsewhere.
+- `<NativeActionSheet v-model:open="choosing" :actions="[...]" @select="…">`
+  asks for a choice from the bottom; `confirmAction()` and `useActionSheet()`
+  do it from code.
+- `<NativeSymbol name="heart.fill" icon="i-lucide-heart">` draws an SF Symbol
+  in the text colour, with an Iconify stand-in where there are none.
 - `<NativeProgressRing :value="percent" :size="176">` fills a ring as something
   completes (sets done, a countdown running out), with its content in the
   slot. Colours follow `--native-ring` and `--native-ring-track`.
@@ -205,7 +261,9 @@ which ignores GPS drift, inaccurate fixes and the ground crossed during a pause.
 
 `<NativeTabItem match="/m/workout">` keeps a tab lit on the detail screens
 opened from it. A tab bar is a `<nav>`, where a link is otherwise current only
-on its own page.
+on its own page. Tab links are the stx router's tabs (`data-stx-nav="tab"`):
+each keeps its own screens and history, and choosing the current one again
+scrolls it to the top, then pops it to its root (`stx:tabreselect`).
 
 Use Iconify classes for tab icons. Keep native operations inside reusable
 components or TypeScript composables, never through `window.*` in an STX
@@ -216,8 +274,9 @@ script.
 `ios.appearance: 'system'` follows the phone's Light/Dark setting (and the
 page's `prefers-color-scheme` with it), with a status bar that reads on either;
 `'light'` and `'dark'` pin one. `ios.backgroundColorDark` colours the launch
-screen and webview in Dark Mode. `ios.swipeNavigation: true` lets an edge swipe
-go back through the page's history, pushed routes included.
+screen and webview in Dark Mode. An edge swipe goes back through the stx
+router's own interactive swipe; WebKit's (`ios.swipeBack: 'webview'`) is only
+for an app whose pages are not on the router.
 
 Decide native-only chrome with `await whenNativeMobile()`, not
 `isNativeMobile()` at setup: Craft installs its bridge after the page starts.

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.97",
+  "version": "0.75.98",
   "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.97",
+  "version": "0.75.98",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "^0.75.97",
+    "@stacksjs/mobile": "^0.75.98",
     "@stacksjs/sanitizer": "^0.2.406",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",

package/resources/components/NativeActionSheet.stx

@@ -0,0 +1,44 @@
+<script client>
+import type { DialogAction } from '@stacksjs/mobile'
+import { dialog } from '@stacksjs/mobile'
+
+/**
+ * An action sheet: a choice raised from the bottom of the screen, with Cancel
+ * set apart. In Craft's iOS shell it is the phone's own UIAlertController;
+ * elsewhere the same sheet drawn in HTML.
+ *
+ * Bind it with `v-model:open` and give it `actions`, each `{ id, title,
+ * style? }` where style is `default`, `destructive` (red) or `cancel`. It
+ * emits `select` with the chosen id, and `close` however it ended.
+ *
+ * For a sheet asked from code rather than declared, `useActionSheet()` and
+ * `confirmAction()` from @stacksjs/mobile do the same in one call.
+ */
+const emit = defineEmits()
+const open = useModel('open', { default: false })
+const title = useReactiveProp<string>('title', '')
+const message = useReactiveProp<string>('message', '')
+const actions = useReactiveProp<DialogAction[]>('actions', [])
+const cancelLabel = useReactiveProp<string>('cancelLabel', 'Cancel')
+
+let showing = false
+effect(() => {
+  if (!open() || showing) return
+  showing = true
+  void dialog.actionSheet({
+    title: title() || undefined,
+    message: message() || undefined,
+    actions: actions(),
+    cancelLabel: cancelLabel(),
+  }).then((id) => {
+    showing = false
+    open.set(false)
+    if (id) emit('select', id)
+    emit('close')
+  })
+})
+</script>
+
+<!-- The sheet is the phone's, or drawn over the page when asked for; nothing
+     of it lives here. -->
+<span hidden data-native-action-sheet></span>

package/resources/components/NativeAppShell.stx

@@ -10,7 +10,7 @@ const { tabBar = false } = defineProps<NativeAppShellProps>()
 </script>
 
 <script client>
-import { deepLinks as deepLinkService, device, followDeepLinks, isNativeMobile, splash, whenNativeMobile } from '@stacksjs/mobile'
+import { deepLinks as deepLinkService, device, followDeepLinks, installNativeChrome, installPressables, isNativeMobile, splash, whenNativeMobile } from '@stacksjs/mobile'
 
 const className = useReactiveProp<string>('class', '')
 // A bare attribute arrives as an empty string.
@@ -45,9 +45,34 @@ void whenNativeMobile().then((native) => {
 // One class binding: a second binding on the same element overwrites the
 // first's classes whenever it runs.
 const shellClass = derived(() => `${nativeMobile() ? 'native-mobile ' : ''}${className()}`.trim())
+
+// In the phone app the chrome around the page follows it: the colour iOS
+// shows past its edges, the status bar's text for its colour scheme, no
+// previous/next/Done bar over the keyboard, and the phone's Dynamic Type and
+// Reduce Motion settings as attributes the components read. A finger landing
+// on anything `data-native-pressable` wakes the haptics for the tap to come
+// (and, by listening at all, gives iOS its :active pressed state).
+const shell = useRef('nativeAppShell')
+let stopChrome: (() => void) | null = null
+let stopPressables: (() => void) | null = null
+let destroyed = false
+onMount(() => {
+  const root = shell.current as HTMLElement | null
+  if (!root) return
+  stopPressables = installPressables(root.ownerDocument)
+  void whenNativeMobile().then((native) => {
+    if (native && !destroyed) stopChrome = installNativeChrome(root.ownerDocument)
+  })
+})
+onDestroy(() => {
+  destroyed = true
+  stopChrome?.()
+  stopPressables?.()
+})
 </script>
 
 <div
+  ref="nativeAppShell"
   data-native-app-shell
   class="native-app-shell"
   :class="shellClass()"
@@ -76,6 +101,11 @@ const shellClass = derived(() => `${nativeMobile() ? 'native-mobile ' : ''}${cla
     /* The height a fixed tab bar takes, which content and sticky footers clear. */
     --native-tab-bar-height: 0px;
 
+    /* Dynamic Type. The Native components size their text in em off this,
+       17px (iOS's body size) at the phone's default text size, scaled by the
+       setting the shell reports. */
+    --native-font-size: calc(17px * var(--native-font-scale, var(--craft-font-scale, 1)));
+
     min-height: 100dvh;
     color: inherit;
     background: inherit;
@@ -84,6 +114,45 @@ const shellClass = derived(() => `${nativeMobile() ? 'native-mobile ' : ''}${cla
     padding-left: var(--native-safe-area-left);
   }
 
+  /* The system font at the body size the phone's text setting chooses, as a
+     native screen's text is. An app keeps a brand face with
+     --native-font-family. The line height stays the app's. */
+  .native-app-shell.native-mobile {
+    font: -apple-system-body;
+    font-family: var(--native-font-family, -apple-system, system-ui, sans-serif);
+    line-height: inherit;
+  }
+
+  /* A tap does not flash a grey box over what was tapped, and does not wait
+     300ms to tell a tap from a double-tap zoom. */
+  .native-mobile :is(a, button, [role=button], label, summary),
+  [data-native-pressable] {
+    -webkit-tap-highlight-color: transparent;
+    touch-action: manipulation;
+  }
+
+  /* The press every control shares: dimmed and pressed in at once while the
+     finger is down, eased back on release, as UIKit's buttons are.
+     `data-native-pressable="opacity"` only dims, for a large row a scale
+     would shift. */
+  [data-native-pressable] {
+    transition: opacity 240ms ease-out, transform 240ms cubic-bezier(0.2, 0.9, 0.3, 1.2);
+  }
+
+  [data-native-pressable]:active {
+    opacity: 0.55;
+    transform: scale(0.97);
+    transition: none;
+  }
+
+  [data-native-pressable="opacity"]:active { transform: none; }
+
+  :root[data-native-reduce-motion] [data-native-pressable]:active { transform: none; }
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-native-pressable]:active { transform: none; }
+  }
+
   /* iOS zooms the page into a text field smaller than 16px when it takes
      focus, and inside an app nothing zooms it back out: the whole screen
      stayed magnified and shifted sideways after typing a comment. A field in

package/resources/components/NativeComponents.test.ts

@@ -147,7 +147,166 @@ describe('Native components', () => {
   it('fills a ring to its value, clamped, with its content in the middle', () => {
     const ring = read('NativeProgressRing')
     expect(ring).toContain('Math.max(0, Math.min(100, Number(value()) || 0))')
-    expect(ring).toContain('conic-gradient(var(--native-ring')
     expect(ring).toContain('<slot />')
   })
+
+  it('draws the ring as a stroke with rounded ends that animates to its value', async () => {
+    const ring = read('NativeProgressRing')
+    expect(ring).not.toContain('conic-gradient')
+    expect(ring).toContain('stroke-linecap: round;')
+    expect(ring).toContain('transition: stroke-dashoffset')
+    expect(ring).toContain('stroke-dashoffset:${100 - percent()}')
+    // Its thickness is still the page's --native-ring-width, exactly.
+    expect(ring).toContain('stroke-width: var(--native-ring-width, 5px);')
+    const html = await render('<NativeProgressRing :value="40" :size="120" label="Rest" />')
+    expect(html).toContain('pathLength="100"')
+    expect(html).toContain('r="50%"')
+  })
+})
+
+async function render(template: string): Promise<string> {
+  return processDirectives(
+    template,
+    {},
+    join(import.meta.dir, 'page.stx'),
+    { componentsDir: import.meta.dir, partialsDir: import.meta.dir } as Parameters<typeof processDirectives>[3],
+    new Set<string>(),
+  )
+}
+
+describe('Native components feel native', () => {
+  it('sets the shell in the system font at the phone\'s text size, and sizes the components off it', () => {
+    const shell = read('NativeAppShell')
+    expect(shell).toContain('font: -apple-system-body;')
+    expect(shell).toContain('--native-font-size: calc(17px * var(--native-font-scale, var(--craft-font-scale, 1)));')
+    for (const name of ['NativeNavBar', 'NativeSheet', 'NativeSegmentedControl'])
+      expect(read(name)).toContain('var(--native-font-size, 17px)')
+  })
+
+  it('drops the tap flash and the double-tap delay, and gives pressables one pressed state', () => {
+    const shell = read('NativeAppShell')
+    expect(shell).toContain('-webkit-tap-highlight-color: transparent;')
+    expect(shell).toContain('touch-action: manipulation;')
+    expect(shell).toContain('[data-native-pressable]:active {')
+    // Pressed at once, released with an ease.
+    expect(shell).toMatch(/\[data-native-pressable\]:active \{[^}]*transition: none;/)
+    expect(shell).toContain('stopPressables = installPressables(root.ownerDocument)')
+  })
+
+  it('keeps the native chrome in step with the page once in the phone app', () => {
+    const shell = read('NativeAppShell')
+    expect(shell).toContain('if (native && !destroyed) stopChrome = installNativeChrome(root.ownerDocument)')
+  })
+
+  it('links the bar to the scroll a frame at a time, and stretches the large title past the top', () => {
+    const bar = read('NativeNavBar')
+    expect(bar).toContain('stopScroll = observeLargeTitle(root, {')
+    expect(bar).toContain('opacity: max(0.001, min(1, var(--native-nav-progress) * 1.5));')
+    expect(bar).toContain('transform: scale(var(--native-nav-stretch, 1));')
+    expect(bar).toContain('transform: translateY(calc((1 - var(--native-nav-progress)) * 0.5em));')
+  })
+
+  it('draws the back chevron as the SF Symbol, with its Iconify stand-in in the page', async () => {
+    const html = await render('<NativeNavBar title="Workout" back="/m" />')
+    expect(html).toContain('data-native-symbol="chevron.backward"')
+    // Sized by the bar's class from the first paint.
+    expect(html).toContain('class="native-symbol i-lucide-chevron-left native-nav-back-icon"')
+  })
+
+  it('draws an SF Symbol from the shell, cached, over an Iconify stand-in', async () => {
+    const symbol = read('NativeSymbol')
+    expect(symbol).toContain('symbols.cached(name, options)')
+    expect(symbol).toContain('mask: var(--native-symbol) center / contain no-repeat;')
+    const labelled = await render('<NativeSymbol name="star" label="Favourite" />')
+    expect(labelled).toContain('class="native-symbol i-lucide-star"')
+    expect(labelled).toContain('role="img" aria-label="Favourite"')
+    const own = await render('<NativeSymbol name="figure.run" icon="i-lucide-footprints" />')
+    expect(own).toContain('class="native-symbol i-lucide-footprints"')
+    expect(own).toContain('aria-hidden="true"')
+  })
+
+  it('drags a sheet by its grabber and header, between detents, and away', async () => {
+    const sheet = read('NativeSheet')
+    expect(sheet).toContain('stopDrag = observeSheetDrag({')
+    expect(sheet).toContain('const handles = [grabber.current, header.current]')
+    expect(sheet).toContain("if (to === 'dismiss') close()")
+    expect(sheet).toContain('.native-sheet.is-open.is-medium .native-sheet-panel { transform: translateY(calc(100% - 50dvh)); }')
+    const html = await render('<NativeSheet title="Edit" detents="medium large"><p>Body</p></NativeSheet>')
+    expect(html).toContain('data-stx-ref="nativeSheetGrabber"')
+    expect(html).toContain('data-stx-ref="nativeSheetHeader"')
+  })
+
+  it('opens a sheet without a haptic, holds the page behind it, and keeps focus inside', () => {
+    const sheet = read('NativeSheet')
+    expect(sheet).not.toContain('haptics')
+    expect(sheet).toContain('releaseBackground = lockBackground(element)')
+    expect(sheet).toContain('trapFocus(panel.current as HTMLElement, event)')
+    expect(sheet).toContain('putBack ??= liftToBody(element)')
+  })
+
+  it('presses the page back into a card behind a large sheet, unless motion is reduced', () => {
+    const sheet = read('NativeSheet')
+    expect(sheet).toContain('presentPageAsCard(element.ownerDocument, want)')
+    expect(sheet).toContain(':root[data-native-sheet-card] .native-app-content {')
+    expect(sheet).toContain(':root[data-native-reduce-motion][data-native-sheet-card] .native-app-content { transform: none; border-radius: 0; }')
+  })
+
+  it('refreshes with the native control where the shell has it, and the 12-spoke indicator elsewhere', async () => {
+    const refresh = read('NativePullToRefresh')
+    expect(refresh).toContain('stop = observeNativeRefresh(element, {')
+    expect(refresh).toContain("if (element && !scrollHost() && refresh.isAvailable())")
+    expect(refresh).toContain('host: resolveScrollHost(scrollHost()),')
+    const html = await render('<NativePullToRefresh><p>List</p></NativePullToRefresh>')
+    expect(html.match(/class="native-ptr-spoke"/g)?.length).toBe(12)
+  })
+
+  it('holds the content down while refreshing, and never leaves a transform on it at rest', () => {
+    const refresh = read('NativePullToRefresh')
+    expect(refresh).toContain('const shift = refreshing() ? HOLD : Math.max(0, distance() - bounce())')
+    expect(refresh).toContain('.native-ptr:is(.is-pulling, .is-refreshing) .native-ptr-content {')
+    expect(refresh).not.toMatch(/\n {2}\.native-ptr-content \{[^}]*transform:/)
+  })
+
+  it('opens a context menu on a half-second press, natively or over a blurred page', async () => {
+    const menu = read('NativeContextMenu')
+    expect(menu).toContain("useReactiveProp<number>('delay', 500)")
+    expect(menu).toContain("void haptics.impact('medium')")
+    expect(menu).toContain('showContextMenuFor(element, { items: items(), title: title() || undefined })')
+    expect(menu).toContain("emit('select', id)")
+    expect(menu).toContain('-webkit-touch-callout: none;')
+    const html = await render('<NativeContextMenu :items="[{ id: \'copy\', title: \'Copy\' }]"><p>Row</p></NativeContextMenu>')
+    expect(html).toContain('data-native-context-menu')
+  })
+
+  it('raises an action sheet through the shell, or drawn in HTML', async () => {
+    const sheet = read('NativeActionSheet')
+    expect(sheet).toContain('void dialog.actionSheet({')
+    expect(sheet).toContain("if (id) emit('select', id)")
+    expect(sheet).toContain("useModel('open'")
+    const html = await render('<NativeActionSheet title="Workout" :actions="[{ id: \'skip\', title: \'Skip\' }]" />')
+    expect(html).toContain('data-native-action-sheet')
+  })
+
+  it('scrubs, shrinks under a finger, and moves with the arrow keys', async () => {
+    const control = read('NativeSegmentedControl')
+    expect(control).toContain('stopScrub = observeSegmentScrub(element, {')
+    expect(control).toContain("${pressed() ? ' scale(0.95)' : ''}")
+    expect(control).toContain('const next = segmentForKey(event.key, activeIndex(), options().length)')
+    expect(control).toContain(':tabindex="index === activeIndex() ? \'0\' : \'-1\'"')
+  })
+
+  it('darkens the offline banner with the app\'s theme, not the system\'s', () => {
+    const banner = read('NativeNetworkBanner')
+    expect(banner).not.toContain('prefers-color-scheme')
+    expect(banner).toContain('.dark .native-network-banner {')
+  })
+
+  it('marks each tab for the router, and scrolls a re-selected tab to its top', async () => {
+    const item = read('NativeTabItem')
+    expect(item).toContain('data-stx-nav="tab"')
+    const bar = read('NativeTabBar')
+    expect(bar).toContain('stopReselect = handleTabReselect(nav)')
+    // No haptic for a tap the phone's own bar made.
+    expect(bar).toContain('if (!mirrored) void haptics.selection()')
+  })
 })

package/resources/components/NativeContextMenu.stx

@@ -0,0 +1,83 @@
+<script client>
+import type { ContextMenuItem } from '@stacksjs/mobile'
+import { haptics, observeLongPress, showContextMenuFor } from '@stacksjs/mobile'
+
+/**
+ * A context menu on whatever is inside: a long press (half a second, as on
+ * iOS) presses it in, taps the haptic engine and opens the menu beside it.
+ * In Craft's iOS shell that is the phone's own UIMenu; elsewhere a menu drawn
+ * over the blurred page. The keyboard's context-menu key (or Shift+F10)
+ * opens it too.
+ *
+ * `items` are `{ id, title, symbol?, icon?, destructive?, disabled? }`:
+ * `symbol` an SF Symbol for the native menu, `icon` an Iconify class for the
+ * web one. Listen for `select`, which carries the chosen id.
+ */
+const emit = defineEmits()
+const items = useReactiveProp<ContextMenuItem[]>('items', [])
+const title = useReactiveProp<string>('title', '')
+const delay = useReactiveProp<number>('delay', 500)
+const pressing = state(false)
+const target = useRef('nativeContextMenu')
+let stop: (() => void) | null = null
+
+async function openMenu(element: HTMLElement): Promise<void> {
+  if (items().length === 0) return
+  const id = await showContextMenuFor(element, { items: items(), title: title() || undefined })
+  if (id) emit('select', id)
+}
+
+onMount(() => {
+  const element = target.current as HTMLElement | null
+  if (!element) return
+  stop = observeLongPress(element, {
+    delay: Number(delay()) || 500,
+    onPressStart: () => {
+      pressing.set(true)
+      void haptics.prepare('impact')
+    },
+    onPressEnd: () => pressing.set(false),
+    onLongPress: () => {
+      pressing.set(false)
+      void haptics.impact('medium')
+      void openMenu(element)
+    },
+  })
+})
+onDestroy(() => stop?.())
+
+function onKey(event: KeyboardEvent): void {
+  if (event.key !== 'ContextMenu' && !(event.shiftKey && event.key === 'F10')) return
+  event.preventDefault()
+  const element = target.current as HTMLElement | null
+  if (element) void openMenu(element)
+}
+</script>
+
+<div ref="nativeContextMenu" class="native-context-menu" :class="pressing() ? 'is-pressing' : ''" @keydown="onKey" data-native-context-menu>
+  <slot />
+</div>
+
+<style>
+  /* No text selection, magnifier or link callout on a long press: the press
+     is the menu's. */
+  .native-context-menu {
+    -webkit-touch-callout: none;
+    -webkit-user-select: none;
+    user-select: none;
+    -webkit-tap-highlight-color: transparent;
+    transition: transform 260ms cubic-bezier(0.2, 0.9, 0.3, 1.2);
+  }
+
+  /* Pressed in slowly over the long press, as iOS does before the menu lifts. */
+  .native-context-menu.is-pressing {
+    transform: scale(0.97);
+    transition: transform 500ms cubic-bezier(0.3, 0, 0.6, 1);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .native-context-menu, .native-context-menu.is-pressing { transform: none; transition: none; }
+  }
+
+  :root[data-native-reduce-motion] .native-context-menu.is-pressing { transform: none; }
+</style>