@stacksjs/defaults 0.75.263 → 0.75.266

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-native/CATALOG.md

@@ -21,7 +21,7 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@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/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 |
@@ -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 |
@@ -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
 
@@ -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.266",
   "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.266",
   "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.266",
+    "@stacksjs/sanitizer": "0.2.663",
+    "@stacksjs/stx": "0.2.663",
     "@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" />

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

@@ -1,3 +1,5 @@
+@import('../UI/Table')
+
 <script client>
 import { dashboardApi } from '../../../../functions/dashboard-api'
 
@@ -44,9 +46,7 @@ const page = derived(() => mode() === 'actions'
       empty: 'No Action modules were found.',
       scaffold: 'buddy make:action MyAction',
       icon: 'i-hugeicons-energy',
-      detailLabel: 'Method',
       note: 'Application files override matching framework defaults.',
-      showOrigin: true,
       stats: [
         { key: 'total', label: 'Total Actions' },
         { key: 'application', label: 'Application Overrides' },
@@ -60,9 +60,7 @@ const page = derived(() => mode() === 'actions'
       empty: 'No command files in app/Commands.',
       scaffold: 'buddy make:command my-command',
       icon: 'i-hugeicons-command-line',
-      detailLabel: 'Aliases and options',
       note: 'Every file in app/Commands is a command. The optional app/Commands.ts only orders, aliases or disables them.',
-      showOrigin: false,
       stats: [
         { key: 'total', label: 'Commands' },
         { key: 'registered', label: 'Registry Entries' },
@@ -90,13 +88,6 @@ function statValue(key: string): number {
   return Number(stats()[key] || 0)
 }
 
-function formatDate(value: string): string {
-  if (!value)
-    return 'Unknown'
-  const date = new Date(value)
-  return Number.isNaN(date.getTime()) ? 'Unknown' : date.toLocaleString()
-}
-
 function formatAliases(item: SourceItem): string {
   return item.aliases?.length ? item.aliases.join(', ') : 'None'
 }
@@ -105,14 +96,67 @@ function formatOptions(item: SourceItem): string {
   return item.options?.length ? item.options.join(', ') : 'None'
 }
 
-function methodClass(method = 'ANY'): string {
+/** Read-only methods, writes, and the catch-all, as the hand-rolled pill coloured them. */
+function methodTone(method = 'ANY'): string {
   if (['GET', 'HEAD', 'OPTIONS'].includes(method))
-    return 'text-blue-700 dark:text-blue-300 bg-blue-50 dark:bg-blue-950/40'
+    return 'read'
   if (method === 'ANY')
-    return 'text-neutral-700 dark:text-neutral-300 bg-neutral-100 dark:bg-neutral-800'
-  return 'text-amber-700 dark:text-amber-300 bg-amber-50 dark:bg-amber-950/40'
+    return 'any'
+  return 'write'
 }
 
+const NAME_COLUMN = { key: 'name', label: 'Name', sortable: true, subtitleKey: 'description', class: 'font-medium text-neutral-900 dark:text-white' }
+const PATH_COLUMN = { key: 'path', label: 'Path', sortable: true, class: 'font-mono text-neutral-600 text-xs dark:text-neutral-300' }
+const MODIFIED_COLUMN = { key: 'modifiedAt', label: 'Modified', type: 'datetime' as const, sortable: true, align: 'right' as const, emptyText: 'Unknown', class: 'whitespace-nowrap' }
+
+/**
+ * Actions show a method and where the file comes from. Commands have one
+ * root, so their second column is what can be typed instead.
+ */
+const COLUMNS_BY_MODE = {
+  actions: [
+    NAME_COLUMN,
+    {
+      key: 'methodTone',
+      label: 'Method',
+      type: 'badge' as const,
+      sortable: true,
+      badgeLabelKey: 'methodLabel',
+      badgeClasses: {
+        read: 'text-blue-700 dark:text-blue-300 bg-blue-50 dark:bg-blue-950/40',
+        any: 'text-neutral-700 dark:text-neutral-300 bg-neutral-100 dark:bg-neutral-800',
+        write: 'text-amber-700 dark:text-amber-300 bg-amber-50 dark:bg-amber-950/40',
+      },
+    },
+    {
+      key: 'origin',
+      label: 'Origin',
+      type: 'badge' as const,
+      sortable: true,
+      badgeClasses: {
+        Application: 'text-green-700 dark:text-green-300 bg-green-50 dark:bg-green-950/40',
+        Framework: 'text-neutral-700 dark:text-neutral-300 bg-neutral-100 dark:bg-neutral-800',
+      },
+    },
+    PATH_COLUMN,
+    MODIFIED_COLUMN,
+  ],
+  commands: [
+    NAME_COLUMN,
+    { key: 'aliasesLabel', label: 'Aliases', sortable: true, subtitleKey: 'optionsLabel', class: 'text-neutral-700 text-xs dark:text-neutral-300' },
+    PATH_COLUMN,
+    MODIFIED_COLUMN,
+  ],
+}
+
+const itemRows = derived(() => filteredItems().map(item => ({
+  ...item,
+  methodTone: methodTone(item.method),
+  methodLabel: item.method || 'ANY',
+  aliasesLabel: `Aliases: ${formatAliases(item)}`,
+  optionsLabel: `Options: ${formatOptions(item)}`,
+})))
+
 async function loadInventory(): Promise<void> {
   loading.set(true)
   loadError.set('')
@@ -205,50 +249,15 @@ onMount(() => {
       </label>
     </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>
-      Reading source files...
-    </div>
-
-    <EmptyState
-      :if="!loading() && !loadError() && filteredItems().length === 0"
-      :icon="page().icon"
-      :title="search() ? 'No matching source files' : page().empty"
-      :description="search() ? 'Try a different name, path, method, or alias.' : 'Use the scaffold command to add one through the native framework workflow.'"
+    <Table
+      :columns="COLUMNS_BY_MODE[mode()]"
+      :data="itemRows()"
+      :loading="loading()"
+      row-key="path"
+      paginated
+      :page-size="25"
+      :empty-title="search() ? 'No matching source files' : page().empty"
+      :empty-description="search() ? 'Try a different name, path, method, or alias.' : 'Use the scaffold command to add one through the native framework workflow.'"
     />
-
-    <div :if="!loading() && filteredItems().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">Name</th>
-            <th class="px-4 py-3 font-semibold text-left text-neutral-500 text-xs tracking-wider uppercase dark:text-neutral-400">{{ page().detailLabel }}</th>
-            <th :if="page().showOrigin" class="px-4 py-3 font-semibold text-left text-neutral-500 text-xs tracking-wider uppercase dark:text-neutral-400">Origin</th>
-            <th class="px-4 py-3 font-semibold text-left text-neutral-500 text-xs tracking-wider uppercase dark:text-neutral-400">Path</th>
-            <th class="pr-5 py-3 font-semibold text-neutral-500 text-right text-xs tracking-wider uppercase dark:text-neutral-400">Modified</th>
-          </tr>
-        </thead>
-        <tbody class="divide-neutral-100 divide-y dark:divide-neutral-700">
-          <tr :for="item in filteredItems()">
-            <td class="pl-5 pr-4 py-3.5">
-              <p class="font-medium text-neutral-900 text-sm dark:text-white">{{ item.name }}</p>
-              <p class="mt-0.5 max-w-md text-neutral-500 text-xs dark:text-neutral-400">{{ item.description }}</p>
-            </td>
-            <td class="px-4 py-3.5">
-              <span :if="mode() === 'actions'" :class="'inline-flex px-2 py-0.5 font-medium text-xs rounded ' + methodClass(item.method)">{{ item.method || 'ANY' }}</span>
-              <div :if="mode() === 'commands'" class="space-y-1 text-xs">
-                <p class="text-neutral-700 dark:text-neutral-300"><span class="text-neutral-500 dark:text-neutral-400">Aliases:</span> {{ formatAliases(item) }}</p>
-                <p class="text-neutral-700 dark:text-neutral-300"><span class="text-neutral-500 dark:text-neutral-400">Options:</span> {{ formatOptions(item) }}</p>
-              </div>
-            </td>
-            <td :if="page().showOrigin" class="px-4 py-3.5">
-              <span :class="'inline-flex px-2 py-0.5 font-medium text-xs rounded ' + (item.origin === 'Application' ? 'text-green-700 dark:text-green-300 bg-green-50 dark:bg-green-950/40' : 'text-neutral-700 dark:text-neutral-300 bg-neutral-100 dark:bg-neutral-800')">{{ item.origin }}</span>
-            </td>
-            <td class="px-4 py-3.5 font-mono text-neutral-600 text-xs dark:text-neutral-300">{{ item.path }}</td>
-            <td class="pr-5 py-3.5 text-neutral-500 text-right text-xs whitespace-nowrap dark:text-neutral-400">{{ formatDate(item.modifiedAt) }}</td>
-          </tr>
-        </tbody>
-      </table>
-    </div>
   </Card>
 </div>