@stacksjs/defaults 0.75.126 → 0.75.128

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

@@ -8,6 +8,13 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Chat
 
+Native direct messaging accepts an optional `onMessageSent` callback in its
+messenger options. It receives `{ message, actorId, recipientId, scope,
+participantType }` once for each newly saved message, after an enclosing
+transaction commits. Duplicate send retries and rolled-back messages do not
+run it. Connect notification jobs there; a callback failure is logged without
+turning a saved message into a failed send.
+
 Multi-driver chat messaging with Slack, Discord, and Microsoft Teams support. Each driver supports both webhook and bot token modes, with retry logic and structured message formats.
 
 ## Key Paths

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

@@ -106,6 +106,46 @@ minimumIntervalMinutes? }`and`associatedDomains` (universal links). Leave
 `buddy build:ios` warns. The Liquid Glass chrome needs iOS 26 at run time;
 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.
+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;
+read them with `signal()` and update them with `signal.set()` inside scripts.
+Imported helpers used only in bindings are retained in the client setup.
+
+```stx
+<script client>
+const title = state('Today')
+const refreshing = state(false)
+async function refresh() {
+  refreshing.set(true)
+  try {
+    const response = await fetch('https://example.com/api/title')
+    if (!response.ok) throw new Error('Could not refresh')
+    title.set((await response.json()).title)
+  }
+  finally {
+    refreshing.set(false)
+  }
+}
+</script>
+<ScrollView @refresh="refresh()" :refreshing="refreshing">
+  <Text :text="title" />
+</ScrollView>
+```
+
+A single-brace JSX expression such as `{title}` is plain text in STX. Keep
+startup requests and timers in `onMount()`, returning a cleanup for timers so
+leaving a native screen releases them. Test the minified `compileNativeBundle`
+output with the native bridge, including refresh, keyed rows, conditions and
+navigation; compiling a plausible tree alone does not prove it updates.
+
+While an app is in TestFlight before its first public release, keep the iOS
+marketing version at `1.0.0` and run `buddy release:ios --bump build`. Each
+upload needs a new build number, not a patch to the marketing version.
+
 ## Device search index
 
 `spotlight` says what of the application's own content a device may index, so

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

@@ -69,7 +69,7 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@stacksjs/pagination` | [`stacks-pagination`](../stacks-pagination/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/pagination/src/index.ts) | 0 |
 | `@stacksjs/path` | [`stacks-path`](../stacks-path/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/path/src/index.ts) | 9 |
 | `@stacksjs/payments` | [`stacks-payments`](../stacks-payments/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/index.ts) | 20 |
-| `@stacksjs/push` | [`stacks-push`](../stacks-push/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/index.ts) | 5 |
+| `@stacksjs/push` | [`stacks-push`](../stacks-push/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/index.ts) | 6 |
 | `@stacksjs/query-builder` | [`stacks-query-builder`](../stacks-query-builder/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/query-builder/src/index.ts) | 6 |
 | `@stacksjs/queue` | [`stacks-queue`](../stacks-queue/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/queue/src/index.ts) | 48 |
 | `@stacksjs/realtime` | [`stacks-realtime`](../stacks-realtime/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/realtime/src/index.ts) | 11 |
@@ -607,7 +607,7 @@ Evidence directory: [7 retained tests](https://github.com/stacksjs/stacks/blob/m
 
 Guidance: [`stacks-notifications`](../stacks-notifications/SKILL.md). Source: [storage/framework/core/notifications/src/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/index.ts).
 
-Declared runtime exports: `BroadcastNotificationDriver`, `DatabaseNotificationDriver`, `bulkSetPreferences`, `emailParagraphs`, `ensureSuccessfulEmailResult`, `ensureSuccessfulNotificationResults`, `filterChannelsByPreferences`, `getNotificationPreferences`, `makeDeliveryRecord`, `notification`, `notificationEmailHtml`, `notificationEmailText`, `notify`, `recordNotificationDelivery`, `resolveDeliveryRecipient`, `setNotificationPreference`, `useBroadcast`, `useChat`, `useDatabase`, `useEmail`, `useNotification`, `usePush`, `useSMS`, `wherePreferenceCategory`.
+Declared runtime exports: `BroadcastNotificationDriver`, `DatabaseNotificationDriver`, `bulkSetPreferences`, `emailParagraphs`, `ensureSuccessfulEmailResult`, `ensureSuccessfulNotificationResults`, `filterChannelsByPreferences`, `getNotificationPreferences`, `makeDeliveryRecord`, `notification`, `notificationChannel`, `notificationEmailHtml`, `notificationEmailText`, `notify`, `recordNotificationDelivery`, `resolveDeliveryRecipient`, `setNotificationPreference`, `useBroadcast`, `useChat`, `useDatabase`, `useEmail`, `useNotification`, `usePush`, `useSMS`, `wherePreferenceCategory`.
 
 Local source modules: [src/delivery.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/delivery.ts), [src/drivers/broadcast.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/broadcast.ts), [src/drivers/database.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/database.ts), [src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/index.ts), [src/email-body.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/email-body.ts), [src/preferences.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/preferences.ts).
 
@@ -663,11 +663,11 @@ Evidence directory: [20 retained tests](https://github.com/stacksjs/stacks/blob/
 
 Guidance: [`stacks-push`](../stacks-push/SKILL.md). Source: [storage/framework/core/push/src/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/index.ts).
 
-Declared runtime exports: `buildVapidHeaders`, `configureExpo`, `configureFCM`, `encryptPayload`, `expo`, `fcm`, `generateVapidKeys`, `send`, `sendWebPush`.
+Declared runtime exports: `apns`, `buildVapidHeaders`, `configureAPNS`, `configureExpo`, `configureFCM`, `encryptPayload`, `expo`, `fcm`, `generateVapidKeys`, `send`, `sendWebPush`.
 
-Local source modules: [src/drivers/expo.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/drivers/expo.ts), [src/drivers/fcm.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/drivers/fcm.ts), [src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/drivers/index.ts), [src/drivers/web-push.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/drivers/web-push.ts).
+Local source modules: [src/drivers/apns.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/drivers/apns.ts), [src/drivers/expo.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/drivers/expo.ts), [src/drivers/fcm.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/drivers/fcm.ts), [src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/drivers/index.ts), [src/drivers/web-push.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/src/drivers/web-push.ts).
 
-Evidence directory: [5 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [6 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/push/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/query-builder
 

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

@@ -127,3 +127,17 @@ own their persistence; the query builder is bun-query-builder.
 `broadcast.test.ts` and `email-body.test.ts` cover retained behavior.
 For provider status, consult `config/src/capabilities.ts` and each channel
 skill; a constructed send request is not a live delivery assertion.
+
+## Live, retry-safe database notifications
+
+`useDatabase().send()` accepts an optional `idempotencyKey` (1–255 characters).
+Retries for the same user, notification type and producer key return the
+original inbox row, including concurrent retries. It uses the existing uuid
+column and a recipient row lock. Use a stable message/event identifier.
+
+New inbox rows broadcast `notifications.created` with `{ id }` on
+`notificationChannel(userId)` (`private-user.{id}`) when the native realtime
+engine is initialized. Delivery waits for transaction commit and carries no
+message body. Duplicated keys do not emit again. Set `broadcast: false` to
+suppress this invalidation. Serve an authenticated native broadcast stream for
+the server-selected user channel and reconcile the durable inbox on reconnect.

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

@@ -405,3 +405,25 @@ to Expo; explicit FCM selection uses this package's direct send API.
 Evidence: `core/push/tests/web-push.test.ts`,
 `config-credentials.test.ts` and `fcm.test.ts`. These tests do not prove
 live delivery to a registered physical device.
+
+## Native Apple Push Notification Service (APNs)
+
+Use `send(deviceToken, notification, { driver: 'apns' })` for the hexadecimal
+Apple device tokens registered by Craft's iOS bridge. These are not FCM or
+Expo tokens. TestFlight uses production APNs; development builds use sandbox.
+
+`config/services.ts` supports `apns: { teamId, keyId, privateKey, topic,
+sandbox }`, or call `configureAPNS()` with the same fields. Framework defaults
+read APNS_TEAM_ID, APNS_KEY_ID, APNS_PRIVATE_KEY, APNS_TOPIC and
+APNS_ENVIRONMENT (`production` or `sandbox`). Use a key enabled for APNs, not
+an App Store Connect or Sign in with Apple key.
+
+The driver uses HTTP/2, ES256 P-256 provider tokens, raw JOSE signatures and a
+50-minute token cache. Payloads are limited to 4096 bytes. A collapseId can
+coalesce retries of one notification. Structured per-device results include
+Apple's status, reason and request identifier. Success means Apple accepted
+the request; it does not prove an alert appeared on a physical phone.
+
+`notify` accepts `recipient.pushDriver` for explicit native APNs/FCM selection.
+Evidence: `core/push/tests/apns.test.ts` exercises signatures, payloads and
+HTTP/2 success/rejection responses against a local server.

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.126",
+  "version": "0.75.128",
   "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.126",
+  "version": "0.75.128",
   "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.126",
+    "@stacksjs/mobile": "0.75.128",
     "@stacksjs/sanitizer": "^0.2.422",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",