@stacksjs/defaults 0.75.318 → 0.75.321

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

@@ -26,6 +26,13 @@ bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts <comman
 Every command prints a JSON result. Screenshots are written under `storage/framework/runtime/shots/` by
 default; **Read the PNG** to view it.
 
+Every command accepts `--scale N` for the native device-pixel ratio, defaulting
+to `1`. It must be one positive finite number. The driver applies it before
+navigation, including scenario runs and every responsive or crawl page. To
+qualify Retina behavior, inspect the page's actual `devicePixelRatio`, canvas
+backing dimensions or resolution media query; a requested value alone is not
+evidence. Scenario reports include the requested `scale`.
+
 ## Browser discovery (no install step)
 
 The driver finds a browser at runtime in this order, and falls through to the next if one
@@ -112,6 +119,7 @@ Extracts headings, links (`text -> href`), buttons, forms (action + field count)
 ### Scenario (stateful SPA interactions)
 ```bash
 bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts scenario <url> \
+  --scale 2 \
   --step '{"action":"click","selector":"button[data-open]"}' \
   --step '{"action":"focus","selector":"input[name=name]"}' \
   --step '{"action":"evaluate","expression":"window.__stxDevtools?.stats()"}' \

package/ai/skills/stacks-browse/scripts/browse.ts

@@ -600,6 +600,14 @@ function parseViewport(value: string | undefined): { w: number, h: number } {
   return { w, h }
 }
 
+export function parseDeviceScale(value: string | boolean | Array<string | boolean> | undefined): number {
+  if (value === undefined) return 1
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError('--scale requires one positive finite device-pixel ratio, for example --scale 2.')
+  const scale = Number(value)
+  if (!Number.isFinite(scale) || scale <= 0) throw new TypeError(`Invalid --scale "${value}". Expected a positive finite device-pixel ratio.`)
+  return scale
+}
+
 /** `--scroll-y` on `screenshot`: an explicit document Y to jump to before
  *  capturing just the viewport, for content a full-page capture cannot show
  *  (sticky/fixed elements, scroll-linked animation) at a specific fold. */
@@ -851,6 +859,7 @@ async function main() {
     process.exit(url ? 0 : 1)
   }
 
+  const scale = parseDeviceScale(flags.scale)
   let session = await launch()
   const cookies = flagList(flags.cookie)
   const settleMs = flags.settle ? Number(flags.settle) : undefined
@@ -869,7 +878,7 @@ async function main() {
     if (command === 'navigate' || command === 'go') {
       const cdp = await openPage(session.port)
       const t0 = performance.now()
-      const state = await gotoAndInstrument(cdp, url, { cookies, settleMs, scheme })
+      const state = await gotoAndInstrument(cdp, url, { scale, cookies, settleMs, scheme })
       const loadMs = Math.round(performance.now() - t0)
       console.log(JSON.stringify({
         browser: session.browser,
@@ -887,7 +896,6 @@ async function main() {
     else if (command === 'screenshot') {
       const cdp = await openPage(session.port)
       const viewport = parseViewport(typeof flags.viewport === 'string' ? flags.viewport : undefined)
-      const scale = flags.scale ? Number(flags.scale) : 1
       const scrollY = parseScrollY(flags['scroll-y'])
       const modes = [flags.full && 'full', flags.element && 'element', scrollY != null && 'scroll-y'].filter(Boolean)
       if (modes.length > 1)
@@ -908,7 +916,7 @@ async function main() {
       const results: any[] = []
       for (const bp of BREAKPOINTS) {
         const cdp = await openPage(session.port)
-        const state = await gotoAndInstrument(cdp, url, { viewport: { w: bp.w, h: bp.h }, cookies, settleMs, scheme, reducedMotion: true })
+        const state = await gotoAndInstrument(cdp, url, { viewport: { w: bp.w, h: bp.h }, scale, cookies, settleMs, scheme, reducedMotion: true })
         const overflow = await cdp.send('Runtime.evaluate', {
           // Mobile Chrome may expand innerWidth to fit overflowing content.
           // Compare the page with the requested device width, not that expansion.
@@ -927,7 +935,7 @@ async function main() {
     else if (command === 'monitor') {
       const cdp = await openPage(session.port)
       const ms = flags.ms ? Number(flags.ms) : 5000
-      const state = await gotoAndInstrument(cdp, url, { cookies, settleMs, scheme })
+      const state = await gotoAndInstrument(cdp, url, { scale, cookies, settleMs, scheme })
       await Bun.sleep(ms)
       const failed = state.responses.filter(r => r.status >= 400)
       const slow = state.responses.filter(r => r.ms > 3000)
@@ -950,7 +958,7 @@ async function main() {
       // auto-imported `state` signal factory, which has no `dispose`, so
       // `browse snapshot` threw on its last line and left the CDP listeners
       // attached.
-      const state = await gotoAndInstrument(cdp, url, { cookies, settleMs, scheme })
+      const state = await gotoAndInstrument(cdp, url, { scale, cookies, settleMs, scheme })
       const expr = `(() => {
         const sel = (q) => Array.from(document.querySelectorAll(q));
         const txt = (e) => (e.innerText || e.textContent || '').trim().slice(0, 80);
@@ -976,7 +984,7 @@ async function main() {
 
       const cdp = await openPage(session.port)
       const viewport = parseViewport(typeof flags.viewport === 'string' ? flags.viewport : undefined)
-      const state = await gotoAndInstrument(cdp, url, { viewport, cookies, settleMs, scheme, reducedMotion: !!flags.full })
+      const state = await gotoAndInstrument(cdp, url, { viewport, scale, cookies, settleMs, scheme, reducedMotion: !!flags.full })
       const results: Record<string, unknown>[] = []
       await cdp.send('Page.bringToFront')
       await cdp.send('Runtime.evaluate', {
@@ -1048,6 +1056,7 @@ async function main() {
       console.log(JSON.stringify({
         url,
         viewport: `${viewport.w}x${viewport.h}`,
+        scale,
         steps: results,
         final: finalState,
         screenshot,
@@ -1115,6 +1124,7 @@ async function main() {
           let state: PageState | undefined
           try {
             state = await gotoAndInstrument(cdp, current, {
+              scale,
               cookies,
               settleMs: crawlSettleMs,
               scheme,

package/ai/skills/stacks-browse/scripts/chrome.ts

@@ -115,6 +115,10 @@ export function prepareMacChrome(options: { source?: string, directory?: string
   }
   try {
     run(['/bin/cp', '-cR', sourceApp, staged], 'Cloning Chrome')
+    // The clone keeps the installed app's extended attributes (Finder info,
+    // provenance, quarantine), and codesign refuses to sign over them:
+    // "resource fork, Finder information, or similar detritus not allowed".
+    run(['/usr/bin/xattr', '-cr', staged], 'Clearing extended attributes')
     const stagedInfo = join(staged, 'Contents/Info.plist')
     for (const key of UPDATER_KEYS) plist(stagedInfo, `Delete :${key}`)
     run(['/usr/libexec/PlistBuddy', '-c', `Set :CFBundleIdentifier ${PRIVATE_BUNDLE_ID}`, stagedInfo], 'Renaming the Chrome bundle')

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

@@ -12,7 +12,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 - Database package: `storage/framework/core/database/src/`
 - Configuration: `config/database.ts`
 - QB config: `config/query-builder.ts`
-- Migrations: `database/migrations/` (239 migration files, `.sql` format)
+- Migrations: `database/migrations/` (247 migration files, `.sql` format)
 - QB state: `.qb/`
 - ORM: `storage/framework/orm/`
 

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

@@ -100,6 +100,29 @@ interface Desktop {
 
 ## Local-first apps: owning the launcher
 
+### Model-backed offline native apps
+
+An app created with `buddy new <name> --native` can use `craft.config.ts`'s
+`backend: { entry: 'app/Desktop/api.ts' }` to bundle a Bun backend. The native
+host owns an authenticated ephemeral loopback session and the backend's lifetime.
+The binary does not need an installed Bun, external server or source files.
+
+Define models under `app/Models` with `defineModel` from `@stacksjs/orm/define-model`.
+In the backend, import those models explicitly and use `openNativeDatabase` and
+`createNativeModelApi` from `@stacksjs/orm/native`. Pass an absolute SQLite path
+inside Application Support and an explicit model registry. The same query-builder
+migration planner derives the schema and atomically records its snapshot in the
+database. Additive upgrades preserve rows; destructive changes are refused.
+
+CRUD follows `traits.useApi.uri` and its explicit `routes` list. Native models
+declare `middleware: []` because the transport owns session authorization.
+`createNativeModelApi` requires an `authorize(request, model, ability)` callback
+on every request. Only return true unconditionally when the handler runs solely
+behind stx's authenticated native backend. Never expose that handler through an
+unprotected HTTP server. Web middleware declarations are refused by this native
+adapter instead of silently skipped. Writes use the model's validation, fillable
+allowlist and hidden-field serialization; index requests have bounded pagination.
+
 The launcher Stacks compiles opens a Craft window on the URL in `desktop.json`,
 which is what a hosted Stacks application wants. An app whose subject is the
 machine it runs on - a disk cleaner, a log viewer, a device tool - has no such

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-migrations
-description: Use when working with database migrations in a Stacks application - creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 239 built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
+description: Use when working with database migrations in a Stacks application - creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 247 built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -236,7 +236,7 @@ lossless widenings; reports everything destructive), then
 - Do not commit a second snapshot under `.qb/`; that indicates a missing `snapshotDir` configuration
 - If a generated SQLite migration rebuilds tables, test it against a copy of the current database and run `PRAGMA integrity_check` plus `PRAGMA foreign_key_check`
 - `--seed` flag after `migrate:fresh` seeds the database with factory data
-- 239 migration files exist by default for all framework models
+- 247 migration files exist by default for all framework models
 - SQLite >= 3.47.2 is required (system requirement)
 - For the database API (queries, connections), see the `stacks-database` skill
 

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

@@ -35,7 +35,7 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@stacksjs/composables` | [`stacks-composables`](../stacks-composables/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/composables/src/index.ts) | 18 |
 | `@stacksjs/config` | [`stacks-config`](../stacks-config/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/config/src/index.ts) | 16 |
 | `@stacksjs/cron` | [`stacks-cron`](../stacks-cron/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/cron/src/index.ts) | 4 |
-| `@stacksjs/database` | [`stacks-database`](../stacks-database/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/index.ts) | 132 |
+| `@stacksjs/database` | [`stacks-database`](../stacks-database/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/index.ts) | 135 |
 | `@stacksjs/datetime` | [`stacks-datetime`](../stacks-datetime/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/datetime/src/index.ts) | 13 |
 | `@stacksjs/defaults` | [`stacks-build`](../stacks-build/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/defaults/package.json) | 2 |
 | `@stacksjs/deploy` | [`stacks-deploy`](../stacks-deploy/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/deploy/package.json) | 1 |
@@ -65,7 +65,7 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@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) | 16 |
 | `@stacksjs/objects` | [`stacks-objects`](../stacks-objects/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/objects/src/index.ts) | 4 |
-| `@stacksjs/orm` | [`stacks-orm`](../stacks-orm/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/index.ts) | 72 |
+| `@stacksjs/orm` | [`stacks-orm`](../stacks-orm/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/index.ts) | 73 |
 | `@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) | 13 |
 | `@stacksjs/payments` | [`stacks-payments`](../stacks-payments/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/payments/src/index.ts) | 29 |
@@ -75,7 +75,7 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@stacksjs/realtime` | [`stacks-realtime`](../stacks-realtime/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/realtime/src/index.ts) | 12 |
 | `@stacksjs/registry` | [`stacks-registry`](../stacks-registry/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/registry/src/index.ts) | 1 |
 | `@stacksjs/repl` | [`stacks-repl`](../stacks-repl/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/repl/src/index.ts) | 2 |
-| `@stacksjs/router` | [`stacks-router`](../stacks-router/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/index.ts) | 95 |
+| `@stacksjs/router` | [`stacks-router`](../stacks-router/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/index.ts) | 96 |
 | `@stacksjs/scheduler` | [`stacks-scheduler`](../stacks-scheduler/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/scheduler/src/index.ts) | 14 |
 | `@stacksjs/search-engine` | [`stacks-search-engine`](../stacks-search-engine/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/search-engine/src/index.ts) | 11 |
 | `@stacksjs/security` | [`stacks-security`](../stacks-security/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/security/src/index.ts) | 11 |
@@ -83,7 +83,7 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@stacksjs/shell` | [`stacks-shell`](../stacks-shell/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/shell/src/index.ts) | 1 |
 | `@stacksjs/sites` | [`stacks-sites`](../stacks-sites/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/sites/src/index.ts) | 3 |
 | `@stacksjs/skills` | [`stacks-skills`](../stacks-skills/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/skills/src/index.ts) | 1 |
-| `@stacksjs/slug` | [`stacks-slug`](../stacks-slug/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/slug/src/index.ts) | 4 |
+| `@stacksjs/slug` | [`stacks-slug`](../stacks-slug/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/slug/src/index.ts) | 5 |
 | `@stacksjs/sms` | [`stacks-sms`](../stacks-sms/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/sms/src/index.ts) | 5 |
 | `@stacksjs/socials` | [`stacks-socials`](../stacks-socials/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/socials/src/index.ts) | 17 |
 | `@stacksjs/storage` | [`stacks-storage`](../stacks-storage/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/index.ts) | 42 |
@@ -353,7 +353,7 @@ Declared runtime exports: `Database`, `EntityQueryBuilder`, `__flushAfterCommitN
 
 Local source modules: [src/affected-rows.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/affected-rows.ts), [src/auth-tables.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/auth-tables.ts), [src/custom/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/custom/index.ts), [src/database.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/database.ts), [src/datetime-columns.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/datetime-columns.ts), [src/ddl-constraints.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/ddl-constraints.ts), [src/defaults.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/defaults.ts), [src/dialect.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/dialect.ts), [src/driver-config.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/driver-config.ts), [src/drivers/dynamodb.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/drivers/dynamodb.ts), [src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/drivers/index.ts), [src/ensure-database.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/ensure-database.ts), [src/erd.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/erd.ts), [src/fk-audit.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/fk-audit.ts), [src/framework-renames.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/framework-renames.ts), [src/framework-route-admission.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/framework-route-admission.ts), [src/hand-written-migrations.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/hand-written-migrations.ts), [src/ignored-migrations.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/ignored-migrations.ts), [src/index-shape.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/index-shape.ts), [src/managed-columns.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/managed-columns.ts), [src/migration-dialect.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/migration-dialect.ts), [src/migration-ledger.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/migration-ledger.ts), [src/migration-names.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/migration-names.ts), [src/migration-path.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/migration-path.ts), [src/migrations.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/migrations.ts), [src/model-sources.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/model-sources.ts), [src/notification-tables.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/notification-tables.ts), [src/package-migrations.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/package-migrations.ts), [src/package-models.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/package-models.ts), [src/query-logger.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/query-logger.ts), [src/rbac-tables.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/rbac-tables.ts), [src/relation-columns.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/relation-columns.ts), [src/replicas.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/replicas.ts), [src/row-lock.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/row-lock.ts), [src/safe-migrations.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/safe-migrations.ts), [src/schema-align.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/schema-align.ts), [src/schema-drift.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/schema-drift.ts), [src/seeder.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/seeder.ts), [src/shadowed-models.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/shadowed-models.ts), [src/sql-helpers.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/sql-helpers.ts), [src/trait-tables.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/trait-tables.ts), [src/transaction-context.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/transaction-context.ts), [src/types.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/types.ts), [src/unique-audit.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/unique-audit.ts), [src/utc-defaults.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/utc-defaults.ts), [src/utils.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/utils.ts), [src/uuid-columns.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/uuid-columns.ts), [src/vschema.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/vschema.ts).
 
-Evidence directory: [132 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [135 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/datetime
 
@@ -635,7 +635,7 @@ Declared runtime exports: `Activity`, `AnalyticsEvent`, `Auction`, `AuctionItem`
 
 Local source modules: [src/auto-crud.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/auto-crud.ts), [src/batch-loader.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/batch-loader.ts), [src/db.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/db.ts), [src/define-model.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/define-model.ts), [src/extend-model.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/extend-model.ts), [src/gdpr/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/gdpr/index.ts), [src/generate-database-schema.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/generate-database-schema.ts), [src/locked-row.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/locked-row.ts), [src/messaging.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/messaging.ts), [src/model-types.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/model-types.ts), [src/ownership.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/ownership.ts), [src/paginator-request.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/paginator-request.ts), [src/row-token.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/row-token.ts), [src/subquery.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/subquery.ts), [src/traits/audit.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/traits/audit.ts), [src/traits/billable.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/traits/billable.ts), [src/traits/categorizable.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/traits/categorizable.ts), [src/traits/commentable.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/traits/commentable.ts), [src/traits/likeable.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/traits/likeable.ts), [src/traits/taggable.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/traits/taggable.ts), [src/transaction.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/transaction.ts), [src/types.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/types.ts), [src/utils/encrypted.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/utils/encrypted.ts), [src/utils/prunable.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/utils/prunable.ts).
 
-Evidence directory: [72 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [73 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/pagination
 
@@ -725,7 +725,7 @@ Declared runtime exports: `DASHBOARD_ROUTE_GROUPS`, `DEFAULT_ROUTE_BUNDLE_FEATUR
 
 Local source modules: [src/api-shape.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/api-shape.ts), [src/body.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/body.ts), [src/dashboard-access.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/dashboard-access.ts), [src/encrypted-session-store.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/encrypted-session-store.ts), [src/error-handler.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/error-handler.ts), [src/health.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/health.ts), [src/json.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/json.ts), [src/middleware.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/middleware.ts), [src/path-sanitize.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/path-sanitize.ts), [src/rate-limit.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/rate-limit.ts), [src/request-augmentation.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/request-augmentation.ts), [src/request-context.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/request-context.ts), [src/route-loader.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/route-loader.ts), [src/route-model-binding.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/route-model-binding.ts), [src/security-settings.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/security-settings.ts), [src/session-factory.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/session-factory.ts), [src/signed-url.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/signed-url.ts), [src/stacks-router.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/stacks-router.ts), [src/typed-router.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/src/typed-router.ts).
 
-Evidence directory: [95 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [96 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/router/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/scheduler
 
@@ -803,7 +803,7 @@ Read the entrypoint and package export map for re-exported or type-only surfaces
 
 Local source modules: [src/unique.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/slug/src/unique.ts).
 
-Evidence directory: [4 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/slug/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [5 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/slug/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/sms
 

package/app/Actions/Cms/AuthorUpdateAction.ts

@@ -14,10 +14,10 @@ export default new Action({
       return response.json({ error: 'Author not found' }, 404)
     }
 
-    const result = await author.update({
-      name: request.get('name'),
-      email: request.get('email'),
-    })
+    // Only the fields the request sent: an absent one copied through
+    // request.get() reached the query as undefined, which binds NULL and
+    // erased the stored value (stacksjs/stacks#3010).
+    const result = await author.update(request.only(['name', 'email']))
 
     return response.json(result)
   },

package/app/Actions/Cms/CategorizableUpdateAction.ts

@@ -31,10 +31,10 @@ export default new Action({
 
     const id = Number(request.getParam('id'))
 
-    const data = {
-      name: request.get('name'),
-      description: request.get('description'),
-    }
+    // Only the fields the request sent: an absent one copied through
+    // request.get() reached the query as undefined, which binds NULL and
+    // erased the stored value (stacksjs/stacks#3010).
+    const data = request.only(['name', 'description'])
 
     const model = await categorizable.update({ id, ...data })
 

package/app/Actions/Cms/PostUpdateAction.ts

@@ -16,12 +16,11 @@ export default new Action({
 
     const id = Number(request.getParam('id'))
 
+    // Only the fields the request sent: an absent one copied through
+    // request.get() reached the query as undefined, which binds NULL and
+    // erased the stored value (stacksjs/stacks#3010).
     const data = {
-      title: request.get('title'),
-      excerpt: request.get('excerpt'),
-      content: request.get('content'),
-      status: request.get('status'),
-      poster: request.get('poster'),
+      ...request.only(['title', 'excerpt', 'content', 'status', 'poster']),
       updated_at: formatDate(new Date()),
     }
 

package/app/Actions/Cms/TaggableUpdateAction.ts

@@ -30,10 +30,12 @@ export default new Action({
     })
 
     const id = Number(request.getParam('id'))
+    // Only the fields the request sent: an absent one copied through
+    // request.get() reached the query as undefined, which binds NULL and
+    // erased the stored value (stacksjs/stacks#3010).
     const data = {
       id,
-      name: request.get('name'),
-      description: request.get('description'),
+      ...request.only(['name', 'description']),
     }
 
     const model = await tags.update(data)

package/app/Actions/Commerce/CustomerStoreAction.ts

@@ -14,13 +14,11 @@ export default new Action({
   async handle(request) {
     await request.validate()
 
+    // Only the fields the request sent: an absent one copied through
+    // request.get() reached the query as undefined, which binds NULL and
+    // erased the stored value or the column default (stacksjs/stacks#3010).
     const data = toSnakeCaseKeys({
-      name: request.get('name'),
-      email: request.get('email'),
-      phone: request.get('phone'),
-      totalSpent: request.get('totalSpent'),
-      status: request.get('status'),
-      avatar: request.get('avatar'),
+      ...request.only(['name', 'email', 'phone', 'totalSpent', 'status', 'avatar']),
       uuid: randomUUIDv7(),
       ...(request.get('lastOrder') && { lastOrder: request.get('lastOrder') }),
     })

package/app/Actions/Commerce/CustomerUpdateAction.ts

@@ -18,13 +18,11 @@ export default new Action({
     const { id } = identifier
 
     await request.validate()
+    // Only the fields the request sent: an absent one copied through
+    // request.get() reached the query as undefined, which binds NULL and
+    // erased the stored value or the column default (stacksjs/stacks#3010).
     const data = toSnakeCaseKeys({
-      name: request.get('name'),
-      email: request.get('email'),
-      phone: request.get('phone'),
-      totalSpent: request.get('totalSpent'),
-      status: request.get('status'),
-      avatar: request.get('avatar'),
+      ...request.only(['name', 'email', 'phone', 'totalSpent', 'status', 'avatar']),
       ...(request.get('lastOrder') && { lastOrder: request.get('lastOrder') }),
     })
 

package/app/Actions/Commerce/PaymentStoreAction.ts

@@ -9,15 +9,12 @@ export default new Action({
   async handle(request: RequestInstance) {
     await request.validate()
 
-    const data = {
-      order_id: request.get<number>('order_id'),
-      customer_id: request.get<number>('customer_id'),
-      amount: request.get<number>('amount'),
-      method: request.get('method'),
-      status: request.get('status'),
-    }
+    // Only the fields the request sent: an absent one copied through
+    // request.get() reached the query as undefined, which binds NULL and
+    // erased the stored value or the column default (stacksjs/stacks#3010).
+    const data = request.only(['order_id', 'customer_id', 'amount', 'method', 'status'])
 
-    const model = await payments.store(data)
+    const model = await payments.store(data as Parameters<typeof payments.store>[0])
 
     return response.json(model)
   },

package/app/Actions/Commerce/PaymentUpdateAction.ts

@@ -14,24 +14,27 @@ export default new Action({
     const { id } = identifier
 
     await request.validate()
-    const data = {
-      order_id: request.get<number>('order_id'),
-      customer_id: request.get<number>('customer_id'),
-      amount: request.get<number>('amount'),
-      method: request.get('method'),
-      status: request.get('status'),
-      currency: request.get('currency'),
-      reference_number: request.get('reference_number'),
-      card_last_four: request.get('card_last_four'),
-      card_brand: request.get('card_brand'),
-      billing_email: request.get('billing_email'),
-      transaction_id: request.get('transaction_id'),
-      payment_provider: request.get('payment_provider'),
-      refund_amount: request.get<number>('refund_amount'),
-      notes: request.get('notes'),
-    }
+    // Only the fields the request sent: an absent one copied through
+    // request.get() reached the query as undefined, which binds NULL and
+    // erased the stored value or the column default (stacksjs/stacks#3010).
+    const data = request.only([
+      'order_id',
+      'customer_id',
+      'amount',
+      'method',
+      'status',
+      'currency',
+      'reference_number',
+      'card_last_four',
+      'card_brand',
+      'billing_email',
+      'transaction_id',
+      'payment_provider',
+      'refund_amount',
+      'notes',
+    ])
 
-    const model = await payments.update(id, data)
+    const model = await payments.update(id, data as Parameters<typeof payments.update>[1])
     if (!model)
       return commerceNotFound('Payment', id)
 

package/app/Actions/Dashboard/Commerce/commerce-product-records.test.ts

@@ -15,6 +15,7 @@ describe('dashboard commerce product records', () => {
     const record = normalizeCommerceProductRecord({
       id: 5,
       name: 'Native Kit',
+      slug: 'native-kit',
       price: 125,
       is_available: 1,
       inventory_count: 7,
@@ -29,6 +30,7 @@ describe('dashboard commerce product records', () => {
     expect(record).toMatchObject({
       id: '5',
       name: 'Native Kit',
+      slug: 'native-kit',
       price: 125,
       isAvailable: true,
       inventoryCount: 7,
@@ -72,6 +74,7 @@ describe('dashboard commerce product records', () => {
       normalizeCommerceProductRecord({
         id: 1,
         name: 'Available',
+        slug: 'available',
         price: 100,
         isAvailable: true,
         inventoryCount: 3,
@@ -81,6 +84,7 @@ describe('dashboard commerce product records', () => {
       normalizeCommerceProductRecord({
         id: 2,
         name: 'Unavailable',
+        slug: 'unavailable',
         price: 100,
         isAvailable: false,
         inventoryCount: 0,
@@ -101,6 +105,7 @@ describe('dashboard commerce product records', () => {
     const base = {
       id: 1,
       name: 'Native Kit',
+      slug: 'native-kit',
       price: 125,
       is_available: 1,
       inventory_count: 7,
@@ -132,6 +137,8 @@ describe('dashboard commerce product records', () => {
       new Map(),
       new Map(),
     )).toThrow('references missing Category 99')
+    // An unrated review counts as a review, not as a 0-star one (#2999).
+    expect(summarizeProductReviews([{ rating: null, is_approved: 1 }, { rating: 4, is_approved: 0 }]).averageRating).toBe(4)
     expect(() => summarizeProductReviews([{ rating: 'unknown', is_approved: 1 }]))
       .toThrow('Review 1.rating must be a finite number')
     expect(() => normalizeCommerceCurrency('US')).toThrow('three-letter currency code')

package/app/Actions/Dashboard/Commerce/commerce-product-records.ts

@@ -4,6 +4,8 @@ import { commerceTimestamp } from './commerce-record'
 export interface CommerceProductRecord {
   id: string
   name: string
+  /** The storefront address, /products/{slug} (stacksjs/stacks#3005). */
+  slug: string
   description: string
   /** Integer minor units of the store currency (1999 is $19.99 in USD). */
   price: number
@@ -68,6 +70,7 @@ export interface ProductReviewSummary {
  */
 export interface ProductFormFields {
   name: string
+  slug: string
   description: string
   price: string
   imageUrl: string
@@ -83,6 +86,7 @@ export interface ProductFormFields {
 /** What the dialog sends to `POST`/`PATCH /api/dashboard/commerce/products`. */
 export interface ProductWritePayload {
   name: string
+  slug: string
   description: string
   /** Integer minor units, never a decimal (stacksjs/stacks#2851). */
   price: number
@@ -116,6 +120,7 @@ export function productWritePayload(form: ProductFormFields, currency: string):
   const allergens = form.allergens.split(',').map(item => item.trim()).filter(Boolean)
   return {
     name: form.name.trim(),
+    slug: form.slug.trim(),
     description: form.description.trim(),
     price: parseMoneyInput(form.price, currency, { min: MIN_PRODUCT_PRICE }),
     imageUrl: form.imageUrl.trim(),
@@ -285,6 +290,7 @@ export function normalizeCommerceProductRecord(
   return {
     id,
     name: requiredText(value(product, 'name'), source, 'name'),
+    slug: requiredText(value(product, 'slug'), source, 'slug'),
     description: optionalText(value(product, 'description'), source, 'description'),
     price: number(value(product, 'price'), source, 'price', { min: 0 }),
     imageUrl: optionalText(value(product, 'image_url', 'imageUrl'), source, 'image_url'),
@@ -352,9 +358,14 @@ export function summarizeCommerceProducts(records: CommerceProductRecord[]): Com
 }
 
 export function summarizeProductReviews(records: any[]): ProductReviewSummary {
-  const ratings = records.map((record, index) =>
-    number(value(record, 'rating'), `Review ${index + 1}`, 'rating', { min: 1, max: 5 }),
-  )
+  // A review can be words without stars; it counts toward the total, not the
+  // average.
+  const ratings = records.flatMap((record, index) => {
+    const rating = value(record, 'rating')
+    return rating === null || rating === undefined
+      ? []
+      : [number(rating, `Review ${index + 1}`, 'rating', { min: 1, max: 5 })]
+  })
   const approved = records.filter((record, index) =>
     boolean(value(record, 'is_approved', 'isApproved'), `Review ${index + 1}`, 'is_approved'),
   ).length

package/app/Actions/Dashboard/Commerce/review-records.test.ts

@@ -108,6 +108,18 @@ describe('dashboard review records', () => {
     })
   })
 
+  // A review can be words with no stars (9b8dd223e8), and one unrated review
+  // made the whole list answer 503 (stacksjs/stacks#2999).
+  test('keeps a review without a star rating, and averages only the rated ones', () => {
+    const unrated = normalizeReviewRecord(review({ rating: null }), new Map(), new Map())
+    expect(unrated.rating).toBeNull()
+    expect(() => normalizeReviewRecord(review({ rating: 6 }), new Map(), new Map())).toThrow('rating must be at most 5')
+
+    const rated = normalizeReviewRecord(review({ id: 10, rating: 4 }), new Map(), new Map())
+    expect(summarizeReviews([unrated, rated]).averageRating).toBe(4)
+    expect(summarizeReviews([unrated]).averageRating).toBe(0)
+  })
+
   test('validates Product options and Customer context records', () => {
     expect(normalizeReviewProductOption({ id: 4, name: 'Native Kit' }))
       .toEqual({ id: '4', label: 'Native Kit' })