@stacksjs/defaults 0.75.263 → 0.75.267

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

@@ -37,6 +37,8 @@ A candidate is validated with `--version` before use, so a dead wrapper (e.g. a
 shim pointing at an uninstalled `.app`) is skipped automatically. If none launch, it tells
 you to `brew install --cask chromium` or set `BROWSE_BROWSER`.
 
+Startup waits up to 15 seconds for the running browser's valid DevTools port. An exited process or expired deadline fails launch; page readiness and scenario assertions have separate budgets.
+
 ## Default Stacks dev URLs
 
 - Frontend: `http://localhost:3000`
@@ -121,6 +123,7 @@ On a failed step, execution stops and the report retains its number and error,
 the completed steps, final page state and requested screenshot.
 Use `{"action":"assert","selector":"...","absent":true}` to verify that an element is missing or hidden after an interaction.
 Use `{"action":"assert","selector":"button","text":"Save","focused":true}` to verify keyboard focus and focus restoration.
+For asynchronous results, use `{"action":"assert","selector":"button","text":"Sound on","timeoutMs":2000}`. This observes the actual visible result until it matches or the bounded budget expires. Ordinary assertions remain immediate. Only assertions accept `timeoutMs`, an integer from 0 to 30000; protocol and evaluation failures are not retried.
 
 ### Crawl (whole-site browser audit)
 ```bash

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

@@ -174,6 +174,28 @@ class Cdp {
 
 interface Session { proc: ReturnType<typeof spawn>, port: number, userDataDir: string, browser: string }
 
+export async function waitForBrowserPort(proc: { exitCode: number | null }, portFile: string, timeoutMs: number): Promise<number | null> {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 30_000)
+    throw new TypeError('Browser startup timeout must be an integer between 1 and 30000.')
+  const deadline = performance.now() + timeoutMs
+  while (performance.now() < deadline && proc.exitCode === null) {
+    try {
+      const line = readFileSync(portFile, 'utf8').split('\n')[0]?.trim()
+      const port = Number(line)
+      if (Number.isInteger(port) && port > 0 && port <= 65535) {
+        if (performance.now() >= deadline || proc.exitCode !== null) return null
+        return port
+      }
+    }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+    const remaining = deadline - performance.now()
+    if (remaining > 0) await Bun.sleep(Math.min(50, remaining))
+  }
+  return null
+}
+
 async function tryLaunch(browser: string): Promise<Session | null> {
   const userDataDir = join(tmpdir(), `stacks-browse-${process.pid}-${Math.floor(Number(process.hrtime.bigint() % 1000000n))}`)
   mkdirSync(userDataDir, { recursive: true })
@@ -196,18 +218,19 @@ async function tryLaunch(browser: string): Promise<Session | null> {
 
   // Chromium writes the chosen port to <user-data-dir>/DevToolsActivePort.
   const portFile = join(userDataDir, 'DevToolsActivePort')
-  for (let i = 0; i < 80; i++) {
-    if (existsSync(portFile)) {
-      const line = readFileSync(portFile, 'utf8').split('\n')[0]?.trim()
-      if (line)
-        return { proc, port: Number(line), userDataDir, browser }
+  let port: number | null = null
+  try {
+    port = await waitForBrowserPort(proc, portFile, 15_000)
+    if (port !== null) return { proc, port, userDataDir, browser }
+  }
+  finally {
+    if (port === null) {
+      try { proc.kill() }
+      catch { /* ignore */ }
+      try { rmSync(userDataDir, { recursive: true, force: true }) }
+      catch { /* a failed launch must not mask the next browser candidate */ }
     }
-    await Bun.sleep(50)
   }
-  try { proc.kill() }
-  catch { /* ignore */ }
-  try { rmSync(userDataDir, { recursive: true, force: true }) }
-  catch { /* a failed launch must not mask the next browser candidate */ }
   return null
 }
 
@@ -600,9 +623,12 @@ interface ScenarioStep {
   key?: string
   ms?: number
   settle?: number
+  timeoutMs?: number
 }
 
-function parseScenarioStep(value: string): ScenarioStep {
+class ScenarioAssertionError extends Error {}
+
+export function parseScenarioStep(value: string): ScenarioStep {
   let parsed: unknown
   try {
     parsed = JSON.parse(value)
@@ -633,11 +659,41 @@ function parseScenarioStep(value: string): ScenarioStep {
     throw new TypeError('Scenario action "press" requires a key.')
   if (action === 'wait' && (!Number.isFinite(step.ms) || Number(step.ms) < 0 || Number(step.ms) > 30_000))
     throw new TypeError('Scenario action "wait" requires ms between 0 and 30000.')
+  if (step.timeoutMs !== undefined && (action !== 'assert' || !Number.isSafeInteger(step.timeoutMs) || Number(step.timeoutMs) < 0 || Number(step.timeoutMs) > 30_000))
+    throw new TypeError('Scenario timeoutMs is supported only by assert actions and must be an integer between 0 and 30000.')
 
   return step as unknown as ScenarioStep
 }
 
-async function runScenarioStep(cdp: Cdp, step: ScenarioStep): Promise<Record<string, unknown>> {
+export async function runScenarioStep(cdp: Pick<Cdp, 'send'>, step: ScenarioStep): Promise<Record<string, unknown>> {
+  if (step.action === 'assert' && step.timeoutMs) {
+    const deadline = performance.now() + step.timeoutMs
+    let last: ScenarioAssertionError | undefined
+    const expired = () => new Error(`${last?.message || `Scenario assert failed (${step.selector || ''})`}; timed out after ${step.timeoutMs}ms`)
+    while (true) {
+      const budget = deadline - performance.now()
+      if (budget <= 0) throw expired()
+      let timeout: ReturnType<typeof setTimeout> | undefined
+      try {
+        const expiry = Promise.withResolvers<never>()
+        timeout = setTimeout(() => expiry.reject(expired()), budget)
+        const answer = await Promise.race([
+          runScenarioStep(cdp, { ...step, timeoutMs: 0 }),
+          expiry.promise,
+        ])
+        if (performance.now() > deadline) throw expired()
+        return answer
+      }
+      catch (error) {
+        if (!(error instanceof ScenarioAssertionError)) throw error
+        last = error
+        const remaining = deadline - performance.now()
+        if (remaining <= 0) throw error
+        await Bun.sleep(Math.min(50, remaining))
+      }
+      finally { if (timeout !== undefined) clearTimeout(timeout) }
+    }
+  }
   if (step.action === 'wait') {
     await Bun.sleep(Number(step.ms))
     return { action: step.action, ms: Number(step.ms), ok: true }
@@ -740,8 +796,11 @@ async function runScenarioStep(cdp: Cdp, step: ScenarioStep): Promise<Record<str
     returnByValue: true,
   })
   const value = result.result?.value as Record<string, unknown> | undefined
-  if (!value?.ok)
+  if (!value?.ok) {
+    if (step.action === 'assert' && value)
+      throw new ScenarioAssertionError(`Scenario assert failed: ${String(value.error || 'unknown error')} (${step.selector || ''})`)
     throw new Error(`Scenario ${step.action} failed: ${String(value?.error || 'unknown error')} (${step.selector || step.key || ''})`)
+  }
   if (step.action === 'click') {
     const point = value.clickPoint as { x: number, y: number }
     await cdp.send('Input.dispatchMouseEvent', { type: 'mousePressed', x: point.x, y: point.y, button: 'left', clickCount: 1 })
@@ -1196,7 +1255,7 @@ async function main() {
   }
 }
 
-main().catch((e) => {
+if (import.meta.main) main().catch((e) => {
   console.error('browse error:', e?.message || e)
   process.exit(1)
 })

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

@@ -508,6 +508,38 @@ History is chronological, with `has_more` and a `before` message-id cursor.
 Receipts acknowledge only messages through the id actually displayed.
 `MessagingError.status` provides safe HTTP statuses for application handlers.
 
+### Attachments
+
+`send(id, body, retryKey, attachments?)` records files the application has
+already stored. The trait keeps a reference, never bytes: `file` is the
+application's own name for the upload (a disk path, a bucket key, an id), and
+`type`, `size`, `width` and `height` are optional. Resolving and authorizing
+the file stays with the application, so a disk, a bucket and a CDN look the
+same from here.
+
+```ts
+import type { DirectMessageAttachment } from '@stacksjs/chat'
+
+const photo: DirectMessageAttachment = { file: upload.key, type: 'image/jpeg', size: upload.size, width: 1200, height: 900 }
+await messenger.send(thread.id, '', retryKey, [photo])
+```
+
+- A photo with no caption is a message: `body` may be empty when there is at
+  least one attachment, and only then.
+- `message.attachments` is always an array, `[]` for text. Rows written before
+  the column existed read as `[]`.
+- A retry key covers the attachments too. The same key with a different file
+  is a different message and returns 409, rather than silently keeping the
+  first photo.
+- At most 10 attachments, 4000 characters once serialised. Keys the trait does
+  not know are dropped, so the column cannot become a second message body.
+- The column is `chat_messages.attachments`, added by `buddy migrate` to a
+  database created before it. A database that has not migrated yet still sends
+  text.
+- Notification previews are the application's to word: `onMessageSent`
+  receives the message with its attachments, so a photo with no caption can
+  read as "Sent a photo" rather than as an empty line.
+
 For the UI, STX ships `ChatInbox`, `ChatMessage`, and `ChatUnreadBadge` in
 `@stacksjs/components`. Browser stores import `createChat` from
 `@stacksjs/components/chat` and inject their authenticated HTTP transport.

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

@@ -18,10 +18,10 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@stacksjs/api` | [`stacks-api`](../stacks-api/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/api/src/index.ts) | 9 |
 | `@stacksjs/arrays` | [`stacks-arrays`](../stacks-arrays/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/arrays/src/index.ts) | 6 |
 | `@stacksjs/audio` | [`stacks-audio`](../stacks-audio/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/audio/src/index.ts) | 2 |
-| `@stacksjs/auth` | [`stacks-auth`](../stacks-auth/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/index.ts) | 119 |
+| `@stacksjs/auth` | [`stacks-auth`](../stacks-auth/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/index.ts) | 120 |
 | `@stacksjs/browser` | [`stacks-browser`](../stacks-browser/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/browser/src/index.ts) | 8 |
 | `@stacksjs/browser-extension` | [`stacks-browser-extension`](../stacks-browser-extension/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/browser-extension/src/index.ts) | 7 |
-| `@stacksjs/buddy` | [`stacks-buddy`](../stacks-buddy/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/src/index.ts) | 161 |
+| `@stacksjs/buddy` | [`stacks-buddy`](../stacks-buddy/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/src/index.ts) | 164 |
 | `@stacksjs/build` | [`stacks-build`](../stacks-build/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/build/src/index.ts) | 3 |
 | `@stacksjs/cache` | [`stacks-cache`](../stacks-cache/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/cache/src/index.ts) | 14 |
 | `@stacksjs/calendar-api` | [`stacks-calendar`](../stacks-calendar/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/calendar-api/src/index.ts) | 2 |
@@ -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) | 71 |
+| `@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/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) | 28 |
@@ -79,7 +79,7 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@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) | 10 |
 | `@stacksjs/security` | [`stacks-security`](../stacks-security/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/security/src/index.ts) | 11 |
-| `@stacksjs/server` | [`stacks-server`](../stacks-server/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/index.ts) | 25 |
+| `@stacksjs/server` | [`stacks-server`](../stacks-server/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/index.ts) | 26 |
 | `@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 |
@@ -185,7 +185,7 @@ Declared runtime exports: `DEFAULT_ROLE_PACKS`, `createBqbRbacStore`, `generateT
 
 Local source modules: [src/authentication.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/authentication.ts), [src/authenticator.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/authenticator.ts), [src/authorizable.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/authorizable.ts), [src/browser-session.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/browser-session.ts), [src/client.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/client.ts), [src/cookie-auth.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/cookie-auth.ts), [src/credential-user.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/credential-user.ts), [src/email-verification.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/email-verification.ts), [src/gate.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/gate.ts), [src/magic-link.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/magic-link.ts), [src/middleware.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/middleware.ts), [src/oauth-authorization-codes.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-authorization-codes.ts), [src/oauth-authorization-endpoint.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-authorization-endpoint.ts), [src/oauth-authorization-requests.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-authorization-requests.ts), [src/oauth-authorization-response.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-authorization-response.ts), [src/oauth-authorization.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-authorization.ts), [src/oauth-browser-session.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-browser-session.ts), [src/oauth-client-registration.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-client-registration.ts), [src/oauth-consent.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-consent.ts), [src/oauth-delegated-access.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-delegated-access.ts), [src/oauth-dynamic-registration.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-dynamic-registration.ts), [src/oauth-grants.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-grants.ts), [src/oauth-introspection.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-introspection.ts), [src/oauth-metadata.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-metadata.ts), [src/oauth-pkce.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-pkce.ts), [src/oauth-protected-resource.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-protected-resource.ts), [src/oauth-provider.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-provider.ts), [src/oauth-pruning.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-pruning.ts), [src/oauth-revocation.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-revocation.ts), [src/oauth-server.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-server.ts), [src/oauth-token-endpoint.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-token-endpoint.ts), [src/oauth-token-exchange.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-token-exchange.ts), [src/oauth-token-request.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-token-request.ts), [src/oauth-token-response.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/oauth-token-response.ts), [src/page-gate.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/page-gate.ts), [src/passkey.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/passkey.ts), [src/passkeys.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/passkeys.ts), [src/password/reset.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/password/reset.ts), [src/permissions.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/permissions.ts), [src/policy.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/policy.ts), [src/rate-limiter.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/rate-limiter.ts), [src/rbac-seed.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/rbac-seed.ts), [src/rbac-store-bqb.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/rbac-store-bqb.ts), [src/rbac.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/rbac.ts), [src/referrals.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/referrals.ts), [src/register.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/register.ts), [src/request-token.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/request-token.ts), [src/session-auth.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/session-auth.ts), [src/session-handoff.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/session-handoff.ts), [src/socials.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/socials.ts), [src/team.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/team.ts), [src/tokens.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/tokens.ts), [src/two-factor.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/two-factor.ts), [src/user.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/src/user.ts).
 
-Evidence directory: [119 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [120 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/browser
 
@@ -215,7 +215,7 @@ Read the entrypoint and package export map for re-exported or type-only surfaces
 
 Local source modules: [src/commands/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/src/commands/index.ts).
 
-Evidence directory: [161 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [164 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/build
 
@@ -633,7 +633,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: [71 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: [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.
 
 ### @stacksjs/pagination
 
@@ -763,7 +763,7 @@ Declared runtime exports: `server`.
 
 Local source modules: [src/config.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/config.ts), [src/controllers/base.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/controllers/base.ts), [src/imports.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/imports.ts), [src/maintenance.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/maintenance.ts), [src/proxy.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/proxy.ts), [src/redirects.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/redirects.ts), [src/rewrites.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/rewrites.ts), [src/security-headers.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/security-headers.ts), [src/shadowed-defaults.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/shadowed-defaults.ts).
 
-Evidence directory: [25 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [26 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/shell
 

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.263",
+  "version": "0.75.267",
   "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.263",
+  "version": "0.75.267",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -45,9 +45,9 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "0.75.263",
-    "@stacksjs/sanitizer": "0.2.661",
-    "@stacksjs/stx": "0.2.661",
+    "@stacksjs/mobile": "0.75.267",
+    "@stacksjs/sanitizer": "0.2.664",
+    "@stacksjs/stx": "0.2.664",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "ts-qr-codes": "^0.1.8"

package/resources/components/Dashboard/App/RequestsOverview.stx

@@ -1,3 +1,5 @@
+@import('../UI/Table')
+
 <script client>
 import { dashboardApi } from '../../../../functions/dashboard-api'
 
@@ -67,29 +69,75 @@ const filteredRequests = derived(() => {
   })
 })
 
-function formatDate(value: string): string {
-  if (!value)
-    return 'Unknown'
-  const date = new Date(value)
-  return Number.isNaN(date.getTime()) ? 'Unknown' : date.toLocaleString()
-}
-
-function statusClass(status: number): string {
+/**
+ * Pill colours by tone rather than by value, so every status code and every
+ * method the table has not named still lands on a colour, as the hand-rolled
+ * pills did.
+ */
+function statusTone(status: number): string {
   if (status >= 500)
-    return 'text-red-700 dark:text-red-300 bg-red-50 dark:bg-red-950/40'
+    return 'server'
   if (status >= 400)
-    return 'text-amber-700 dark:text-amber-300 bg-amber-50 dark:bg-amber-950/40'
+    return 'client'
   if (status >= 300)
-    return 'text-blue-700 dark:text-blue-300 bg-blue-50 dark:bg-blue-950/40'
-  return 'text-green-700 dark:text-green-300 bg-green-50 dark:bg-green-950/40'
+    return 'redirect'
+  return 'ok'
 }
 
-function methodClass(method: string): string {
+function methodTone(method: string): string {
   if (method === 'GET')
-    return 'text-blue-700 dark:text-blue-300 bg-blue-50 dark:bg-blue-950/40'
+    return 'read'
   if (method === 'DELETE')
-    return 'text-red-700 dark:text-red-300 bg-red-50 dark:bg-red-950/40'
-  return 'text-violet-700 dark:text-violet-300 bg-violet-50 dark:bg-violet-950/40'
+    return 'delete'
+  return 'write'
+}
+
+const COLUMNS = [
+  {
+    key: 'methodTone',
+    label: 'Method',
+    type: 'badge' as const,
+    sortable: true,
+    badgeLabelKey: 'method',
+    badgeClasses: {
+      read: 'text-blue-700 dark:text-blue-300 bg-blue-50 dark:bg-blue-950/40',
+      delete: 'text-red-700 dark:text-red-300 bg-red-50 dark:bg-red-950/40',
+      write: 'text-violet-700 dark:text-violet-300 bg-violet-50 dark:bg-violet-950/40',
+    },
+  },
+  { key: 'path', label: 'Path', sortable: true, class: 'max-w-md font-mono text-neutral-800 text-xs truncate dark:text-neutral-200' },
+  {
+    key: 'statusTone',
+    label: 'Status',
+    type: 'badge' as const,
+    sortable: true,
+    badgeLabelKey: 'status',
+    badgeClasses: {
+      server: 'text-red-700 dark:text-red-300 bg-red-50 dark:bg-red-950/40',
+      client: 'text-amber-700 dark:text-amber-300 bg-amber-50 dark:bg-amber-950/40',
+      redirect: 'text-blue-700 dark:text-blue-300 bg-blue-50 dark:bg-blue-950/40',
+      ok: 'text-green-700 dark:text-green-300 bg-green-50 dark:bg-green-950/40',
+    },
+  },
+  { key: 'durationMs', label: 'Duration (ms)', type: 'number' as const, sortable: true, align: 'right' as const, class: 'font-mono whitespace-nowrap' },
+  { key: 'ipAddress', label: 'Client', sortable: true, emptyText: 'Not recorded' },
+  { key: 'createdAt', label: 'Recorded', type: 'datetime' as const, sortable: true, align: 'right' as const, emptyText: 'Unknown', class: 'whitespace-nowrap' },
+]
+
+const ROW_ACTIONS = [
+  { action: 'inspect', label: 'Inspect request', icon: 'i-hugeicons-view' },
+]
+
+const requestRows = derived(() => filteredRequests().map(request => ({
+  ...request,
+  methodTone: methodTone(request.method),
+  statusTone: statusTone(request.status),
+  durationMs: Math.round(request.durationMs * 10) / 10,
+})))
+
+function handleRowAction(payload: { action: string, row: RequestRow }): void {
+  if (payload.action === 'inspect')
+    inspectRequest(payload.row)
 }
 
 function inspectRequest(request: RequestRow): void {
@@ -184,49 +232,18 @@ onMount(() => {
       </div>
     </div>
 
-    <div :if="loading()" class="flex items-center justify-center py-16 text-neutral-500 text-sm dark:text-neutral-400">
-      <span class="mr-2 h-5 w-5 animate-spin i-hugeicons-loading-03"></span>
-      Loading request records...
-    </div>
-
-    <EmptyState
-      :if="!loading() && !loadError() && filteredRequests().length === 0"
-      icon="i-hugeicons-global"
-      :title="search() || methodFilter() !== 'all' || statusFilter() !== 'all' ? 'No matching requests' : 'No requests recorded'"
-      description="Request records appear after the application writes to the Request model."
+    <Table
+      :columns="COLUMNS"
+      :data="requestRows()"
+      :loading="loading()"
+      :row-actions="ROW_ACTIONS"
+      action-label-key="path"
+      paginated
+      :page-size="25"
+      :empty-title="search() || methodFilter() !== 'all' || statusFilter() !== 'all' ? 'No matching requests' : 'No requests recorded'"
+      empty-description="Request records appear after the application writes to the Request model."
+      @row-action="handleRowAction"
     />
-
-    <div :if="!loading() && filteredRequests().length > 0" class="overflow-x-auto">
-      <table class="w-full">
-        <thead class="bg-neutral-50 dark:bg-neutral-800/50">
-          <tr>
-            <th class="pl-5 pr-4 py-3 font-semibold text-left text-neutral-500 text-xs tracking-wider uppercase dark:text-neutral-400">Request</th>
-            <th class="px-4 py-3 font-semibold text-left text-neutral-500 text-xs tracking-wider uppercase dark:text-neutral-400">Status</th>
-            <th class="px-4 py-3 font-semibold text-neutral-500 text-right text-xs tracking-wider uppercase dark:text-neutral-400">Duration</th>
-            <th class="px-4 py-3 font-semibold text-left text-neutral-500 text-xs tracking-wider uppercase dark:text-neutral-400">Client</th>
-            <th class="px-4 py-3 font-semibold text-neutral-500 text-right text-xs tracking-wider uppercase dark:text-neutral-400">Recorded</th>
-            <th class="pr-5 py-3 font-semibold text-neutral-500 text-right text-xs tracking-wider uppercase dark:text-neutral-400">Details</th>
-          </tr>
-        </thead>
-        <tbody class="divide-neutral-100 divide-y dark:divide-neutral-700">
-          <tr :for="request in filteredRequests()">
-            <td class="pl-5 pr-4 py-3.5">
-              <div class="flex gap-2 items-center">
-                <span :class="'inline-flex px-2 py-0.5 font-medium text-xs rounded ' + methodClass(request.method)">{{ request.method }}</span>
-                <code class="max-w-md text-neutral-800 text-xs truncate dark:text-neutral-200">{{ request.path }}</code>
-              </div>
-            </td>
-            <td class="px-4 py-3.5"><span :class="'inline-flex px-2 py-0.5 font-medium text-xs rounded ' + statusClass(request.status)">{{ request.status }}</span></td>
-            <td class="px-4 py-3.5 font-mono text-neutral-600 text-right text-xs whitespace-nowrap dark:text-neutral-300">{{ request.durationMs.toFixed(1) }} ms</td>
-            <td class="px-4 py-3.5 text-neutral-500 text-xs dark:text-neutral-400">{{ request.ipAddress || 'Not recorded' }}</td>
-            <td class="px-4 py-3.5 text-neutral-500 text-right text-xs whitespace-nowrap dark:text-neutral-400">{{ formatDate(request.createdAt) }}</td>
-            <td class="pr-5 py-3.5 text-right">
-              <Button variant="ghost" size="sm" @click="inspectRequest(request)">Inspect</Button>
-            </td>
-          </tr>
-        </tbody>
-      </table>
-    </div>
   </Card>
 
   <RequestDetailsDialog :request="selectedRequest()" @close="closeInspector" />