@stacksjs/defaults 0.70.357 → 0.70.362

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

@@ -100,20 +100,24 @@ Extracts headings, links (`text -> href`), buttons, forms (action + field count)
 ```bash
 bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts scenario <url> \
   --step '{"action":"click","selector":"button[data-open]"}' \
+  --step '{"action":"focus","selector":"input[name=name]"}' \
   --step '{"action":"fill","selector":"input[name=name]","value":"Example"}' \
   --step '{"action":"click","selector":"button[type=submit]"}' \
   --step '{"action":"assert","selector":"main","text":"Saved"}' \
+  --step '{"action":"assert","selector":"[role=dialog]","absent":true}' \
   --out storage/framework/runtime/shots/scenario.png
 ```
 
-Steps run in order within one isolated browser page, preserving reactive STX state and SPA navigation. Supported actions are `click`, `fill`, `press`, `wait`, and `assert`. Each step is a JSON object passed through a repeatable `--step` flag. A click step may include `text` to select the matching control from its CSS selector. The command reports every completed step, the final URL and page text, console exceptions, failed requests, and an optional screenshot. It exits nonzero when the scenario assertion, browser console, or network fails.
+Steps run in order within one isolated browser page, preserving reactive STX state and SPA navigation. Supported actions are `click`, `fill`, `focus`, `press`, `wait`, and `assert`. Each step is a JSON object passed through a repeatable `--step` flag. Click and focus steps may include `text` to select the matching control from their CSS selector. The command reports every completed step, the final URL and page text, console messages, console exceptions, failed requests, and an optional screenshot. It exits nonzero when the scenario assertion, browser console, or network fails.
+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.
 
 ### Crawl (whole-site browser audit)
 ```bash
-bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts crawl <url> [--viewport 1280x900] [--max 500] [--path /extra-route] [--settle 350] [--progress]
+bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts crawl <url> [--viewport 1280x900] [--max 500] [--path /extra-route] [--settle 350] [--progress] [--summary]
 ```
-Uses a fresh isolated page target per route, relaunching Chromium if its DevTools
-session exits during a long audit, while
+Uses a fresh isolated page target per route, waits for each target to fully close,
+and relaunches Chromium if its DevTools session or target lifecycle fails during a long audit, while
 following every same-origin link it discovers.
 The viewport is deterministic and defaults to `1280x900`; pass `--viewport 768x1024`
 to repeat the same route audit at a tablet breakpoint.
@@ -121,7 +125,8 @@ Each page is checked for a non-200 document, console exceptions, failed
 requests, and horizontal overflow. Repeat `--path` to seed routes that are not
 linked from the starting page. The command prints every crawled path and exits
 nonzero when any page fails. Add `--progress` to stream each completed page
-during a long audit.
+during a long audit. Add `--summary` to report totals and compact failure
+diagnostics without printing every visited path or overflowing element.
 
 ## Stacks-Specific QA
 

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

@@ -264,12 +264,38 @@ async function createPage(port: number): Promise<BrowserPage> {
   }
 }
 
-async function closePage(port: number, page: BrowserPage): Promise<void> {
-  page.cdp.close()
+async function closePage(port: number, page: BrowserPage): Promise<boolean> {
   try {
-    await fetch(`http://127.0.0.1:${port}/json/close/${encodeURIComponent(page.targetId)}`)
+    const response = await fetch(`http://127.0.0.1:${port}/json/close/${encodeURIComponent(page.targetId)}`)
+    if (!response.ok) {
+      page.cdp.close()
+      return false
+    }
+  }
+  catch {
+    page.cdp.close()
+    return false
+  }
+  page.cdp.close()
+
+  // Chromium acknowledges target closure before every renderer/helper has
+  // actually left the target list. Creating the next target immediately can
+  // accumulate closing renderers across a large crawl, eventually dropping
+  // Network and Runtime events. Wait for the target to disappear so each route
+  // starts with the isolation the command promises.
+  for (let attempt = 0; attempt < 40; attempt++) {
+    try {
+      const targets = await (await fetch(`http://127.0.0.1:${port}/json/list`)).json() as any[]
+      if (!targets.some(target => target.id === page.targetId))
+        return true
+    }
+    catch {
+      return false
+    }
+    await Bun.sleep(25)
   }
-  catch { /* the target or browser may already have closed */ }
+
+  return false
 }
 
 function kill(s: Session): void {
@@ -497,12 +523,14 @@ function parseViewport(value: string | undefined): { w: number, h: number } {
   return { w, h }
 }
 
-type ScenarioAction = 'assert' | 'click' | 'fill' | 'press' | 'wait'
+type ScenarioAction = 'assert' | 'click' | 'fill' | 'focus' | 'press' | 'wait'
 
 interface ScenarioStep {
   action: ScenarioAction
   selector?: string
   text?: string
+  absent?: boolean
+  focused?: boolean
   value?: string
   key?: string
   ms?: number
@@ -522,14 +550,18 @@ function parseScenarioStep(value: string): ScenarioStep {
     throw new TypeError('Each scenario step must be a JSON object.')
 
   const step = parsed as Record<string, unknown>
-  if (!['assert', 'click', 'fill', 'press', 'wait'].includes(String(step.action)))
+  if (!['assert', 'click', 'fill', 'focus', 'press', 'wait'].includes(String(step.action)))
     throw new TypeError(`Unsupported scenario action: ${String(step.action)}`)
 
   const action = step.action as ScenarioAction
-  if (['assert', 'click', 'fill'].includes(action) && typeof step.selector !== 'string')
+  if (['assert', 'click', 'fill', 'focus'].includes(action) && typeof step.selector !== 'string')
     throw new TypeError(`Scenario action "${action}" requires a selector.`)
   if (action === 'fill' && typeof step.value !== 'string')
     throw new TypeError('Scenario action "fill" requires a string value.')
+  if (step.absent !== undefined && (action !== 'assert' || typeof step.absent !== 'boolean'))
+    throw new TypeError('Scenario "absent" is a boolean supported only by assert actions.')
+  if (step.focused !== undefined && (action !== 'assert' || typeof step.focused !== 'boolean'))
+    throw new TypeError('Scenario "focused" is a boolean supported only by assert actions.')
   if (action === 'press' && typeof step.key !== 'string')
     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))
@@ -557,23 +589,36 @@ async function runScenarioStep(cdp: Cdp, step: ScenarioStep): Promise<Record<str
       const step = ${JSON.stringify(step)}
       const candidates = Array.from(document.querySelectorAll(step.selector))
       const normalizedText = (element) => (element.innerText || element.textContent || '').replace(/\\s+/g, ' ').trim()
-      const element = step.action === 'click' && step.text !== undefined
+      const element = (step.action === 'click' || step.action === 'focus' || step.action === 'assert') && step.text !== undefined
         ? candidates.find(candidate => normalizedText(candidate) === step.text)
           || candidates.find(candidate => normalizedText(candidate).includes(step.text))
         : candidates[0]
+      if (!element && step.action === 'assert' && step.absent)
+        return { ok: true, action: step.action, selector: step.selector, absent: true }
       if (!element)
         return { ok: false, error: 'Element not found', selector: step.selector }
 
       const rect = element.getBoundingClientRect()
       const style = getComputedStyle(element)
       const visible = rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden' && style.display !== 'none'
+      if (step.action === 'assert' && step.absent) {
+        if (visible)
+          return { ok: false, error: 'Expected element to be absent', selector: step.selector }
+        return { ok: true, action: step.action, selector: step.selector, absent: true }
+      }
       if (!visible)
         return { ok: false, error: 'Element is not visible', selector: step.selector }
 
       if (step.action === 'click') {
         if (element.disabled || element.getAttribute('aria-disabled') === 'true')
           return { ok: false, error: 'Element is disabled', selector: step.selector }
-        element.click()
+      }
+      else if (step.action === 'focus') {
+        if (typeof element.focus !== 'function')
+          return { ok: false, error: 'Element cannot receive focus', selector: step.selector }
+        element.focus()
+        if (document.activeElement !== element)
+          return { ok: false, error: 'Element did not receive focus', selector: step.selector }
       }
       else if (step.action === 'fill') {
         if (!('value' in element))
@@ -593,12 +638,19 @@ async function runScenarioStep(cdp: Cdp, step: ScenarioStep): Promise<Record<str
           return { ok: false, error: 'Expected text was not found', selector: step.selector, expected: step.text, actual: content.slice(0, 240) }
       }
 
+      if (step.action === 'assert' && step.focused !== undefined) {
+        const focused = document.activeElement === element
+        if (focused !== step.focused)
+          return { ok: false, error: step.focused ? 'Expected element to be focused' : 'Expected element not to be focused', selector: step.selector }
+      }
+
       return {
         ok: true,
         action: step.action,
         selector: step.selector,
         tag: element.tagName.toLowerCase(),
         text: normalizedText(element).slice(0, 160),
+        clickPoint: step.action === 'click' ? { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 } : undefined,
       }
     })()`,
     returnByValue: true,
@@ -606,6 +658,12 @@ async function runScenarioStep(cdp: Cdp, step: ScenarioStep): Promise<Record<str
   const value = result.result?.value as Record<string, unknown> | undefined
   if (!value?.ok)
     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 })
+    await cdp.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: point.x, y: point.y, button: 'left', clickCount: 1 })
+    delete value.clickPoint
+  }
   return value
 }
 
@@ -741,6 +799,20 @@ async function main() {
       const viewport = parseViewport(typeof flags.viewport === 'string' ? flags.viewport : undefined)
       const state = await gotoAndInstrument(cdp, url, { viewport, cookies, settleMs, scheme })
       const results: Record<string, unknown>[] = []
+      await cdp.send('Page.bringToFront')
+      await cdp.send('Runtime.evaluate', {
+        expression: `(() => {
+          window.__browseFocusHistory = []
+          const describe = (element) => element ? {
+            tag: element.tagName?.toLowerCase() || null,
+            role: element.getAttribute?.('role') || null,
+            ariaLabel: element.getAttribute?.('aria-label') || null,
+            text: (element.innerText || element.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 80),
+          } : null
+          document.addEventListener('focusin', event => window.__browseFocusHistory.push({ event: 'focusin', target: describe(event.target) }), true)
+          document.addEventListener('focusout', event => window.__browseFocusHistory.push({ event: 'focusout', target: describe(event.target), related: describe(event.relatedTarget) }), true)
+        })()`,
+      })
 
       for (const step of steps) {
         results.push(await runScenarioStep(cdp, step))
@@ -752,7 +824,15 @@ async function main() {
         expression: `({
           url: location.href,
           title: document.title,
-          activeElement: document.activeElement?.tagName?.toLowerCase() || null,
+          focusHistory: window.__browseFocusHistory || [],
+          activeElement: document.activeElement ? {
+            tag: document.activeElement.tagName?.toLowerCase() || null,
+            id: document.activeElement.id || null,
+            role: document.activeElement.getAttribute?.('role') || null,
+            ariaLabel: document.activeElement.getAttribute?.('aria-label') || null,
+            ref: document.activeElement.getAttribute?.('data-stx-ref') || null,
+            text: (document.activeElement.innerText || document.activeElement.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 120),
+          } : null,
           bodyText: (document.body.innerText || '').replace(/\\s+/g, ' ').trim().slice(0, 500),
         })`,
         returnByValue: true,
@@ -770,6 +850,7 @@ async function main() {
         steps: results,
         final: finalState.result?.value,
         screenshot,
+        consoleMessages: state.console,
         consoleErrors: state.consoleErrors,
         failedRequests,
       }, null, 2))
@@ -809,7 +890,11 @@ async function main() {
         }
       }
       const replacePage = async (): Promise<void> => {
-        await closePage(session.port, browserPage)
+        const closed = await closePage(session.port, browserPage)
+        if (!closed) {
+          kill(session)
+          session = await launch()
+        }
         browserPage = await createReplacementPage()
         cdp = browserPage.cdp
       }
@@ -964,6 +1049,16 @@ async function main() {
         || page.consoleErrors.length > 0
         || page.failedRequests.length > 0
         || page.horizontalOverflowPx > 0)
+      const summaryOnly = Boolean(flags.summary)
+      const reportedFailures = summaryOnly
+        ? failures.map(page => ({
+            path: page.path,
+            status: page.status,
+            consoleErrorCount: page.consoleErrors.length,
+            failedRequestCount: page.failedRequests.length,
+            horizontalOverflowPx: page.horizontalOverflowPx,
+          }))
+        : failures
       console.log(JSON.stringify({
         start: start.href,
         browser: session.browser,
@@ -971,8 +1066,9 @@ async function main() {
         crawled: pages.length,
         remaining: queue.length,
         max,
-        paths: pages.map(page => page.path),
-        failures,
+        failureCount: failures.length,
+        ...(!summaryOnly ? { paths: pages.map(page => page.path) } : {}),
+        failures: reportedFailures,
       }, null, 2))
       if (failures.length > 0)
         process.exitCode = 1

package/app/Actions/AI/AskAction.ts

@@ -1,16 +1,15 @@
+import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { ask } from '@stacksjs/ai'
+import { log } from '@stacksjs/logging'
+import { response } from '@stacksjs/router'
 import { schema } from '@stacksjs/validation'
 
-// TODO: this should have been auto-generated
-interface Request {
-  question: string
-}
-
 export default new Action({
   name: 'AiAskAction',
   description: 'Ask AI',
   method: 'POST',
+  apiResponse: true,
 
   validations: {
     question: {
@@ -19,22 +18,18 @@ export default new Action({
     },
   },
 
-  async handle(request: Request) {
-    try {
-      const question = request.question
-
-      console.log(`Question received: ${question}`)
+  async handle(request: RequestInstance) {
+    await request.validate()
+    const question = String(request.get('question') || '').trim()
 
-      return {
+    try {
+      return response.json({
         data: await ask(question),
-      }
+      })
     }
     catch (error) {
-      console.error('Error:', error)
-
-      return {
-        error: 'An error occurred while processing your request.',
-      }
+      log.error('[ai] Ask request failed', { error })
+      return response.json({ message: 'The AI provider could not answer the question.' }, 502)
     }
   },
 })

package/app/Actions/AI/SummaryAction.ts

@@ -1,16 +1,15 @@
+import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { summarize } from '@stacksjs/ai'
+import { log } from '@stacksjs/logging'
+import { response } from '@stacksjs/router'
 import { schema } from '@stacksjs/validation'
 
-// TODO: this should have been auto-generated
-interface Request {
-  text: string
-}
-
 export default new Action({
   name: 'AiSummaryAction',
   description: 'Summary AI',
   method: 'POST',
+  apiResponse: true,
 
   validations: {
     text: {
@@ -19,22 +18,18 @@ export default new Action({
     },
   },
 
-  async handle(request: Request) {
-    try {
-      const text = request.text
-
-      console.log(`Text received: ${text}`)
+  async handle(request: RequestInstance) {
+    await request.validate()
+    const text = String(request.get('text') || '').trim()
 
-      return {
+    try {
+      return response.json({
         data: await summarize(text),
-      }
+      })
     }
     catch (error) {
-      console.error('Error:', error)
-
-      return {
-        error: 'An error occurred while processing your request.',
-      }
+      log.error('[ai] Summary request failed', { error })
+      return response.json({ message: 'The AI provider could not summarize the text.' }, 502)
     }
   },
 })

package/app/Actions/Dashboard/Actions/GetActions.ts

@@ -1,22 +1,28 @@
 import { Action } from '@stacksjs/actions'
 import process from 'node:process'
 import { discoverActionSources } from '../Source/source-inventory'
+import { dashboardOperationalError } from '../dashboard-response'
 
 export default new Action({
   name: 'GetActions',
   description: 'Lists application and framework Actions from their native source files.',
   method: 'GET',
   async handle() {
-    const items = await discoverActionSources(process.cwd())
+    try {
+      const items = await discoverActionSources(process.cwd())
 
-    return {
-      items,
-      stats: {
-        total: items.length,
-        application: items.filter(item => item.origin === 'Application').length,
-        framework: items.filter(item => item.origin === 'Framework').length,
-        writes: items.filter(item => !['ANY', 'GET', 'HEAD', 'OPTIONS'].includes(item.method || 'ANY')).length,
-      },
+      return {
+        items,
+        stats: {
+          total: items.length,
+          application: items.filter(item => item.origin === 'Application').length,
+          framework: items.filter(item => item.origin === 'Framework').length,
+          writes: items.filter(item => !['ANY', 'GET', 'HEAD', 'OPTIONS'].includes(item.method || 'ANY')).length,
+        },
+      }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Action sources could not be loaded.', 'GetActions')
     }
   },
 })

package/app/Actions/Dashboard/Analytics/EventStoreAction.ts

@@ -1,7 +1,8 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
-import { AnalyticsEvent } from '@stacksjs/orm'
+import { AnalyticsEvent, ModelValidationError } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 
 function token(value: unknown, fallback: string): string {
   const normalized = String(value || '')
@@ -46,14 +47,25 @@ export default new Action({
     if (properties.length > 10_000)
       return response.json({ message: 'Properties must be 10,000 characters or fewer.' }, 422)
 
-    await AnalyticsEvent.create({
-      name,
-      category,
-      path,
-      value,
-      currency,
-      properties,
-    })
+    try {
+      await AnalyticsEvent.create({
+        name,
+        category,
+        path,
+        value,
+        currency,
+        properties,
+      })
+    }
+    catch (error) {
+      if (error instanceof ModelValidationError) {
+        return response.json({
+          message: 'Validation failed.',
+          errors: error.errors,
+        }, 422)
+      }
+      return dashboardOperationalError(error, 'Analytics event could not be recorded.', 'EventStoreAction', 500)
+    }
 
     return response.json({ success: true }, 201)
   },

package/app/Actions/Dashboard/Commerce/ProductUnitDefaultAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { products } from '@stacksjs/commerce'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 
 export default new Action({
   name: 'ProductUnitDefaultAction',
@@ -11,11 +12,19 @@ export default new Action({
 
   async handle(request: RequestInstance) {
     const id = Number(request.getParam('id'))
+    if (!Number.isSafeInteger(id) || id <= 0)
+      return response.json({ error: 'A valid product unit id is required.' }, 400)
+    if (typeof request.get('isDefault') !== 'boolean')
+      return response.json({ error: 'isDefault must be a boolean.' }, 422)
     const isDefault = request.boolean('isDefault')
-    if (!Number.isFinite(id) || id <= 0)
-      return response.notFound({ error: 'Product unit not found' })
 
-    const updated = await products.units.updateDefaultStatus(id, isDefault)
+    let updated
+    try {
+      updated = await products.units.updateDefaultStatus(id, isDefault)
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Product unit default could not be updated.', 'ProductUnitDefaultAction', 500)
+    }
     if (!updated)
       return response.notFound({ error: 'Product unit not found' })
 

package/app/Actions/Dashboard/Commerce/TaxRateDefaultAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { tax } from '@stacksjs/commerce'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 
 export default new Action({
   name: 'TaxRateDefaultAction',
@@ -11,11 +12,19 @@ export default new Action({
 
   async handle(request: RequestInstance) {
     const id = Number(request.getParam('id'))
+    if (!Number.isSafeInteger(id) || id <= 0)
+      return response.json({ error: 'A valid tax rate id is required.' }, 400)
+    if (typeof request.get('isDefault') !== 'boolean')
+      return response.json({ error: 'isDefault must be a boolean.' }, 422)
     const isDefault = request.boolean('isDefault')
-    if (!Number.isFinite(id) || id <= 0)
-      return response.notFound({ error: 'Tax rate not found' })
 
-    const updated = await tax.updateDefaultStatus(id, isDefault)
+    let updated
+    try {
+      updated = await tax.updateDefaultStatus(id, isDefault)
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Tax rate default could not be updated.', 'TaxRateDefaultAction', 500)
+    }
     if (!updated)
       return response.notFound({ error: 'Tax rate not found' })
 

package/app/Actions/Dashboard/DashboardHealthAction.ts

@@ -1,6 +1,7 @@
 import process from 'node:process'
 import { Action } from '@stacksjs/actions'
 import { checkApplicationHealth } from '@stacksjs/router'
+import { dashboardOperationalError, dashboardOperationalIssue } from './dashboard-response'
 
 export default new Action({
   name: 'DashboardHealthAction',
@@ -10,21 +11,40 @@ export default new Action({
 
   async handle() {
     const startedAt = performance.now()
-    const health = await checkApplicationHealth()
-    const memory = process.memoryUsage()
+    try {
+      const health = await checkApplicationHealth()
+      const memory = process.memoryUsage()
+      const checks = Object.fromEntries(Object.entries(health.checks).map(([name, check]) => {
+        if (!check.ok) {
+          dashboardOperationalIssue(
+            check.message,
+            'Dependency probe failed.',
+            `DashboardHealthAction.${name}`,
+          )
+        }
+        return [name, {
+          ...check,
+          message: check.ok ? undefined : 'Dependency probe failed.',
+        }]
+      }))
 
-    return {
-      ...health,
-      durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
-      runtime: {
-        bunVersion: process.versions.bun || '',
-        nodeVersion: process.versions.node || '',
-        platform: process.platform,
-        architecture: process.arch,
-        uptimeSeconds: Math.max(0, Math.floor(process.uptime())),
-        residentMemoryBytes: memory.rss,
-        heapUsedBytes: memory.heapUsed,
-      },
+      return {
+        ...health,
+        checks,
+        durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
+        runtime: {
+          bunVersion: process.versions.bun || '',
+          nodeVersion: process.versions.node || '',
+          platform: process.platform,
+          architecture: process.arch,
+          uptimeSeconds: Math.max(0, Math.floor(process.uptime())),
+          residentMemoryBytes: memory.rss,
+          heapUsedBytes: memory.heapUsed,
+        },
+      }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'System health could not be loaded.', 'DashboardHealthAction')
     }
   },
 })

package/app/Actions/Dashboard/DashboardHomeAction.test.ts

@@ -28,7 +28,7 @@ describe('dashboard HTTP metrics', () => {
       name: 'Cache',
       status: 'critical',
       latency: '1500ms',
-      detail: 'timeout',
+      detail: 'Dependency probe failed.',
     })
   })