@stacksjs/defaults 0.75.301 → 0.75.305

package/ai/AGENTS.md

@@ -78,6 +78,10 @@ review the generated SQL and snapshot, then apply with `./buddy migrate`.
 and `stacks-router` for selection, authentication, ownership, and mount behavior.
 Use `stacks-auto-imports` to distinguish browser bindings from declarations
 and explicit module imports.
+Before adding imports in app code, read the relevant section of
+`storage/framework/auto-imports/RUNTIME.md` and use its listed names directly
+in their stated context. `buddy generate`, `buddy generate:auto-imports` and
+`buddy setup:ai` refresh this inventory from the runtime registries.
 
 **Subsystem reference**, one per area (`stacks-orm`, `stacks-router`,
 `stacks-queue`, ...), each documenting it authoritatively. Read the relevant

package/ai/skills/stacks-auto-imports/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-auto-imports
-description: Use when checking browser/server binding delivery, model globals, registry generation, or the difference between ambient declarations and runtime imports. Covers Stacks auto-imports, stx client delivery, server boot and generated registries (107 models).
+description: Use before adding imports in Stacks app code, checking available runtime functions, browser/server delivery, model globals, or registry generation. Covers Stacks auto-imports, the generated runtime inventory, stx client delivery and server boot (107 models).
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,6 +8,21 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Auto-imports and runtime delivery
 
+## Available names in this project
+
+Before adding imports, read the relevant section of
+`storage/framework/auto-imports/RUNTIME.md` (relative to the project root).
+Use its listed names directly in their stated execution context to avoid
+redundant imports. This compact reference groups server globals by package
+and barrel, and STX client helpers by runtime, macro and demand delivery.
+It is generated from runtime registries, including app helpers and overrides.
+
+`buddy generate`, `buddy generate:types`, `buddy generate:auto-imports` and
+`buddy setup:ai` refresh it. If missing, run `buddy generate:auto-imports`.
+The inventory stays in the project so copied skills read the current app's
+names after subsequent generation. Keep package implementation files and
+standalone scripts self-contained with explicit imports.
+
 A declaration, a delivered client binding, and an initialized server global are
 three different facts. Inspect the relevant runtime rather than inferring all
 three from an ambient type file.
@@ -48,9 +63,10 @@ utilities are imported types; UserRequest/UserRequestModel are not generated
 runtime model variants. Names colliding with built-ins, such as Error/Request,
 need explicit imports and safe local aliases.
 
-Import Action, route, response, schema, path, storage, logging and Auth from their
-packages. An ambient helper declaration alone does not establish its global
-runtime initialization. Follow the built-in action's import pattern.
+The server's primitiveModules registry also injects framework helpers such as
+Action, route, response, schema, path, storage, log and Auth. Use the generated
+inventory to select bare names after Stacks boot. Package internals, standalone
+tools and tests without boot still import their dependencies explicitly.
 
 ## Generation and project overrides
 

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

@@ -28,7 +28,7 @@ The driver finds a browser at runtime in this order, and falls through to the ne
 won't launch:
 
 1. `$BROWSE_BROWSER` (explicit override — set to an absolute browser path)
-2. PATH: `chromium`, `google-chrome`, `brave-browser`, `microsoft-edge`, …
+2. PATH: `google-chrome-stable`, `google-chrome`, `chromium`, `chromium-browser`, `brave-browser`, `microsoft-edge`, …
 3. macOS app bundles (Google Chrome, Chromium, Brave, Edge)
 4. A Chromium binary already cached on disk (e.g. under `~/Library/Caches/ms-playwright`) —
    the **binary only** is borrowed; Playwright is never imported.
@@ -121,6 +121,10 @@ bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts scenari
 Steps run in order within one isolated browser page, preserving reactive STX state and SPA navigation. Supported actions are `click`, `fill`, `focus`, `press`, `wait`, `evaluate`, 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. They scroll matched controls into view before interacting, including controls inside horizontal overflow regions. Evaluate steps run a JavaScript expression in the isolated page and return its serialized value, which is useful for inspecting STX signals and DevTools state between interactions. 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, evaluation, browser console, or network fails.
 On a failed step, execution stops and the report retains its number and error,
 the completed steps, final page state and requested screenshot.
+If final page or screenshot collection fails, the report keeps the completed
+steps and available console/network observations, sets the missing result to
+`null`, and records its phase and error in `collectionErrors`. The command still
+exits nonzero. A missing capture does not qualify an older raster as evidence.
 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.
 `press` sends native virtual key codes for Enter, Escape, Tab, the arrow keys,

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

@@ -45,7 +45,9 @@ function collectCandidates(): string[] {
   if (process.env.BROWSE_BROWSER)
     add(process.env.BROWSE_BROWSER)
 
-  for (const bin of ['chromium', 'chromium-browser', 'google-chrome-stable', 'google-chrome', 'brave-browser', 'microsoft-edge', 'chrome'])
+  // Some distribution Chromium launchers answer --version but cannot open a
+  // DevTools target. Prefer an installed Chrome before spending their bounds.
+  for (const bin of ['google-chrome-stable', 'google-chrome', 'chromium', 'chromium-browser', 'brave-browser', 'microsoft-edge', 'chrome'])
     add(which(bin))
 
   for (const p of [
@@ -703,7 +705,9 @@ export async function runScenarioStep(cdp: Pick<Cdp, 'send'>, step: ScenarioStep
     const key = step.key || ''
     // CDP's key name alone does not perform native navigation or scrolling.
     // Supply the matching virtual key on both events, as a real keyboard does.
-    const keyCode = key.length === 1 ? key.charCodeAt(0) : ({
+    const letter = /^[a-z]$/i.test(key), digit = /^[0-9]$/.test(key)
+    const code = letter ? `Key${key.toUpperCase()}` : digit ? `Digit${key}` : key === ' ' ? 'Space' : key
+    const keyCode = key.length === 1 ? (letter ? key.toUpperCase() : key).charCodeAt(0) : ({
       Backspace: 8, Tab: 9, Enter: 13, Escape: 27,
       PageUp: 33, PageDown: 34, End: 35, Home: 36,
       ArrowLeft: 37, ArrowUp: 38, ArrowRight: 39, ArrowDown: 40,
@@ -712,8 +716,8 @@ export async function runScenarioStep(cdp: Pick<Cdp, 'send'>, step: ScenarioStep
     if (!keyCode) throw new Error(`Unsupported scenario key: ${JSON.stringify(key)}`)
     // Enter's text generates the keypress that activates native buttons/forms.
     const text = key === 'Enter' ? '\r' : undefined
-    await cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', key, code: key, windowsVirtualKeyCode: keyCode, text, unmodifiedText: text })
-    await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key, code: key, windowsVirtualKeyCode: keyCode })
+    await cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', key, code, windowsVirtualKeyCode: keyCode, text, unmodifiedText: text })
+    await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key, code, windowsVirtualKeyCode: keyCode })
     return { action: step.action, key, ok: true }
   }
 
@@ -999,8 +1003,11 @@ async function main() {
           await Bun.sleep(step.settle ?? 250)
       }
 
-      const finalState = await cdp.send('Runtime.evaluate', {
-        expression: `({
+      const collectionErrors: { phase: string, error: string }[] = []
+      let finalState: unknown = null
+      try {
+        const collected = await cdp.send('Runtime.evaluate', {
+          expression: `({
           url: location.href,
           title: document.title,
           focusHistory: window.__browseFocusHistory || [],
@@ -1014,26 +1021,38 @@ async function main() {
           } : null,
           bodyText: (document.body.innerText || '').replace(/\\s+/g, ' ').trim().slice(0, 500),
         })`,
-        returnByValue: true,
-      })
+          returnByValue: true,
+        })
+        finalState = collected.result?.value ?? null
+      }
+      catch (error) {
+        collectionErrors.push({ phase: 'final-state', error: error instanceof Error ? error.message : String(error) })
+      }
       let screenshot: string | null = null
       if (typeof flags.out === 'string') {
-        screenshot = flags.out
-        mkdirSync(screenshot.split('/').slice(0, -1).join('/') || '.', { recursive: true })
-        await Bun.write(screenshot, await captureScreenshot(cdp, { full: !!flags.full }))
+        try {
+          const output = flags.out
+          mkdirSync(output.split('/').slice(0, -1).join('/') || '.', { recursive: true })
+          await Bun.write(output, await captureScreenshot(cdp, { full: !!flags.full }))
+          screenshot = output
+        }
+        catch (error) {
+          collectionErrors.push({ phase: 'screenshot', error: error instanceof Error ? error.message : String(error) })
+        }
       }
       const failedRequests = state.responses.filter(response => response.status >= 400)
       console.log(JSON.stringify({
         url,
         viewport: `${viewport.w}x${viewport.h}`,
         steps: results,
-        final: finalState.result?.value,
+        final: finalState,
         screenshot,
+        collectionErrors,
         consoleMessages: state.console,
         consoleErrors: state.consoleErrors,
         failedRequests,
       }, null, 2))
-      if (scenarioFailed || state.consoleErrors.length || failedRequests.length)
+      if (scenarioFailed || collectionErrors.length || state.consoleErrors.length || failedRequests.length)
         process.exitCode = 1
       state.dispose()
       cdp.close()

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-buddy
-description: Use when working with the Stacks CLI (buddy/bud/stacks/stx) - understanding every command with its flags and options, adding custom commands, the make:* scaffolding commands, development server commands, build commands, deployment commands, email/mail commands, environment management, or domain/DNS commands. Covers @stacksjs/buddy and all CLI command files.
+description: Use when working with the Stacks CLI (buddy/bud/stacks) - understanding every command with its flags and options, adding custom commands, the make:* scaffolding commands, development server commands, build commands, deployment commands, email/mail commands, environment management, or domain/DNS commands. Covers @stacksjs/buddy and all CLI command files.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -22,7 +22,8 @@ The complete CLI runtime for the Stacks framework, lazy-loaded for fast cold sta
 - Make templates: `storage/framework/defaults/`
 
 ## CLI Aliases
-All invoke the same CLI: `./buddy`, `bud`, `stacks`, `stx`
+`./buddy`, `bud`, and `stacks` invoke the Stacks CLI. The `stx` binary belongs
+to the STX template engine; use it for template and native screen compilation.
 
 ## Architecture
 

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

@@ -12,6 +12,10 @@ Choose the execution surface before copying a composable signature. An STX
 client script, an explicitly imported `@stacksjs/composables` module, and a
 server script can expose similarly named functions with different contracts.
 Read [BROWSER.md](BROWSER.md) for template delivery, forms and motion examples.
+For the complete installed client surface, read the STX section of
+`storage/framework/auto-imports/RUNTIME.md` at the project root. Use those
+helpers directly in client scripts; generation refreshes runtime, macro and
+demand names from the installed STX registries.
 
 ## Eager window aliases
 

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) | 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) | 165 |
+| `@stacksjs/buddy` | [`stacks-buddy`](../stacks-buddy/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/src/index.ts) | 166 |
 | `@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) | 11 |
 | `@stacksjs/security` | [`stacks-security`](../stacks-security/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/security/src/index.ts) | 11 |
-| `@stacksjs/server` | [`stacks-server`](../stacks-server/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/index.ts) | 27 |
+| `@stacksjs/server` | [`stacks-server`](../stacks-server/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/index.ts) | 28 |
 | `@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 |
@@ -217,7 +217,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: [165 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: [166 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
 
@@ -765,7 +765,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/response-headers.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/server/src/response-headers.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: [27 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: [28 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/ai/skills/stacks-native/SKILL.md

@@ -48,6 +48,10 @@ the cases that require an action, job, policy, or explicit route.
 
 ## Important boundaries
 
+- Before adding imports in app code, consult the context-specific names in
+  `storage/framework/auto-imports/RUNTIME.md` at the project root. Use listed
+  runtime helpers directly; read `stacks-auto-imports` for initialization and
+  module boundaries. Generation refreshes the inventory for this app.
 - `app/` overrides framework defaults. Use `extendModel` for additive model
   changes; an ordinary override replaces the definition.
 - Generated CRUD defaults to authenticated routes. Ownership and policies

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.301",
+  "version": "0.75.305",
   "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.301",
+  "version": "0.75.305",
   "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.301",
-    "@stacksjs/sanitizer": "0.2.687",
-    "@stacksjs/stx": "0.2.687",
+    "@stacksjs/mobile": "0.75.305",
+    "@stacksjs/sanitizer": "0.2.691",
+    "@stacksjs/stx": "0.2.691",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "ts-qr-codes": "^0.1.8"