@stacksjs/defaults 0.72.56 → 0.72.57

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

@@ -340,9 +340,96 @@ route.get('/admin', handler).middleware('abilities:admin,write')
 // Params accessible in middleware via: (request as any)._middlewareParams.abilities === 'admin,write'
 ```
 
+## Which client to reach for
+
+Stacks has three, and they answer different questions. Pick by who is calling.
+
+| Caller | Client | Why |
+|---|---|---|
+| TypeScript in this repo or a workspace package | **Typed client** (below) | Full input/output inference with **no generation step**. Change a route, the call site stops compiling. |
+| Anything that is not TypeScript here - native iOS/Android via the Craft bridge, third-party integrators, Swagger UI | **Generated REST client** (`buddy generate:openapi`) | Needs a real spec. That pipeline is unchanged and permanent. |
+| One-off calls to any URL | **`Fetcher`** (below) | No route awareness, and none intended. |
+
+The first two are both permanent. This is not a migration off REST.
+
+## Typed client (zero generation)
+
+Register routes with `createTypedRouter()` and the compiler can see both ends —
+no `buddy generate:openapi`, no committed file to go stale.
+
+```typescript
+// routes/api.ts
+import IndexAction from '../app/Actions/Project/IndexAction'
+import StoreAction from '../app/Actions/Project/StoreAction'
+import { createTypedRouter } from '@stacksjs/router'
+
+export const api = createTypedRouter()
+  .get('/v1/projects', IndexAction)
+  .get('/v1/projects/{id}', ShowAction)
+  .post('/v1/projects', StoreAction, { middleware: 'auth' })
+
+export type AppRoutes = typeof api
+```
+
+```typescript
+// any TypeScript consumer
+import type { AppRoutes } from '../routes/api'
+import { createTypedClient } from '@stacksjs/router'
+
+const client = createTypedClient<AppRoutes>({ baseUrl: 'https://api.example.com' })
+
+const projects = await client.get('/v1/projects')
+const one = await client.get('/v1/projects/{id}', { params: { id: '42' } })
+const created = await client.post('/v1/projects', { name: 'apollo', budget: 1200 })
+```
+
+An unknown path is a compile error. A body that does not match the action's
+`validations` is a compile error. The result is the action's own return type.
+
+**How it infers.** Input comes from the action's `validations` — the same object
+the validator runs, so the two cannot drift. Output comes from `handle`'s return
+type. An action returning a `Response` or a stream is typed `unknown`, honestly:
+it took over the wire format.
+
+**Per-route settings are an argument**, not a chained call — chaining
+`.middleware()` would return the route and lose the accumulated type:
+
+```typescript
+.post('/v1/projects', StoreAction, {
+  middleware: ['auth', 'can:create,project'],
+  name: 'projects.store',
+  skipCsrf: true,
+  rateLimit: { max: 10, window: 'minute' },
+})
+```
+
+**No `.group()`.** A prefix applied only at runtime makes every accumulated path
+type wrong; one applied only in the type is a second place for the URL to live.
+Write the full path.
+
+**The string form is untouched.** `route.get('/x', 'Actions/Foo')` stays exactly
+as it is — lazy import, hot-reload friendly — and simply produces no inferred
+types. A route wanting inference opts in by using the builder instead. Routes
+registered either way still land in the generated OpenAPI document.
+
+**Generated CRUD.** A `useApi` model's endpoints are describable too, without
+touching them:
+
+```typescript
+import type { ApiRoutesFor } from '@stacksjs/orm'
+import type Product from '../app/Models/Product'
+
+type AppRoutes = RoutesOf<typeof api> & ApiRoutesFor<typeof Product>
+await client.get('/api/products')  // typed listing envelope
+```
+
+The builder, the client and the route-map contract all live in
+`@stacksjs/bun-router` and are re-exported by `@stacksjs/router`. Import
+`createTypedClient` from `@stacksjs/bun-router` directly in a browser bundle.
+
 ## Fetcher (HTTP Client)
 
-A fluent HTTP client for making API requests:
+A fluent HTTP client for ad hoc requests, with no route awareness:
 
 ```typescript
 import { fetcher } from '@stacksjs/api'

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

@@ -313,7 +313,7 @@ interface PageState {
   mainStatus: number | null
 }
 
-async function gotoAndInstrument(cdp: Cdp, url: string, opts: { viewport?: { w: number, h: number }, scale?: number, timeoutMs?: number, cookies?: string[], settleMs?: number, scheme?: string } = {}): Promise<PageState> {
+async function gotoAndInstrument(cdp: Cdp, url: string, opts: { viewport?: { w: number, h: number }, scale?: number, timeoutMs?: number, cookies?: string[], settleMs?: number, scheme?: string, reducedMotion?: boolean } = {}): Promise<PageState> {
   let unsubscribe = () => {}
   const state: PageState = {
     consoleErrors: [],
@@ -356,12 +356,29 @@ async function gotoAndInstrument(cdp: Cdp, url: string, opts: { viewport?: { w:
   }
 
   // Emulate light/dark so prefers-color-scheme pages can be QA'd in both
-  // schemes without flipping the host OS setting.
-  if (opts.scheme === 'light' || opts.scheme === 'dark') {
-    await cdp.send('Emulation.setEmulatedMedia', {
-      features: [{ name: 'prefers-color-scheme', value: opts.scheme }],
-    })
-  }
+  // schemes without flipping the host OS setting. `reducedMotion` rides the
+  // same call (a second `setEmulatedMedia` would replace this one's features
+  // rather than add to them) - it's set for `--full`/`--element` captures,
+  // which paint beyond the current viewport via `captureBeyondViewport`.
+  // That API paints pixels beyond the viewport WITHOUT moving `scrollY`, so
+  // a scroll-driven CSS reveal (`animation-timeline: view()`) never
+  // resolves past its initial (typically invisible) keyframe for anything
+  // that was never really scrolled past - a `--full` capture would silently
+  // screenshot every such section as blank. `prefers-reduced-motion: reduce`
+  // sidesteps that instead of fighting it with a scroll trick that would
+  // itself misplace `position: sticky`/`fixed` elements: this project's own
+  // marketing CSS already turns every scroll/entrance animation off and
+  // leaves elements at their plain (opaque) resting state under reduced
+  // motion (`@media (prefers-reduced-motion: reduce)`), which is exactly
+  // the already-shipped, already-tested fallback a real accessibility user
+  // gets - reusing it here means nothing new to prove correct.
+  const features: { name: string, value: string }[] = []
+  if (opts.scheme === 'light' || opts.scheme === 'dark')
+    features.push({ name: 'prefers-color-scheme', value: opts.scheme })
+  if (opts.reducedMotion)
+    features.push({ name: 'prefers-reduced-motion', value: 'reduce' })
+  if (features.length)
+    await cdp.send('Emulation.setEmulatedMedia', { features })
 
   unsubscribe = cdp.on((e) => {
     if (e.method === 'Runtime.consoleAPICalled') {
@@ -404,23 +421,11 @@ async function title(cdp: Cdp): Promise<string> {
 }
 
 /**
- * Scroll the real page to `y` and let one frame settle before the caller
- * screenshots it.
- *
- * `--full` captures the whole document through `captureBeyondViewport`,
- * which paints content at its full-page layout position without ever
- * moving `scrollY` - correct for a top-to-bottom review, but useless for
- * checking anything that depends on an actual mid-scroll viewport: a
- * `position: sticky` nav overlapping content beneath it, a CSS
- * `animation-timeline: view()` reveal mid-transition, or simply "what does
- * the fold look like 800px down". `window.scrollTo(..., { behavior:
- * 'instant' })` forces the jump synchronously even when the page sets
- * `scroll-behavior: smooth`, which would otherwise animate the scroll and
- * leave a screenshot taken immediately after mid-flight. The two rAF
- * round-trips that follow give the compositor one full frame to repaint
- * sticky/fixed layers and any scroll-driven animation at the new offset
- * before `Page.captureScreenshot` reads back pixels, which
- * `Runtime.evaluate` returning does not by itself guarantee.
+ * Scroll the real page to `y` and let two animation-frame round-trips settle
+ * before the caller reads pixels back - `behavior: 'instant'` forces the
+ * jump synchronously even when the page sets `scroll-behavior: smooth`,
+ * which would otherwise animate the scroll and leave a screenshot taken
+ * immediately after mid-flight.
  */
 async function scrollTo(cdp: Cdp, y: number): Promise<void> {
   const r = await cdp.send('Runtime.evaluate', {
@@ -753,7 +758,7 @@ async function main() {
     console.log('Usage: bun browse.ts <navigate|screenshot|responsive|monitor|snapshot|scenario|crawl> <url> [flags]')
     console.log('  --cookie "name=value"   repeatable; pre-seeds cookies (e.g. coming-soon bypass)')
     console.log('  --settle 1500           ms to wait after load before acting (default 700; stretch for entrance animations)')
-    console.log('  --scheme dark           emulate prefers-color-scheme (light|dark) for QA of theme-aware pages')
+    console.log('  --scheme dark           emulate prefers-color-scheme (light|dark); defaults to light when omitted')
     console.log('  --scroll-y 800          screenshot: jump to this document Y first, then capture just the viewport')
     console.log('                          (--full renders beyond-viewport without ever scrolling, so it cannot show a')
     console.log('                          position:sticky/fixed element overlapping content, or a scroll-linked')
@@ -764,7 +769,17 @@ async function main() {
   let session = await launch()
   const cookies = flagList(flags.cookie)
   const settleMs = flags.settle ? Number(flags.settle) : undefined
-  const scheme = typeof flags.scheme === 'string' ? flags.scheme : undefined
+  // Defaults to 'light' rather than leaving prefers-color-scheme unset:
+  // headless Chromium's own default for that media feature isn't
+  // documented or guaranteed, and was observed reporting 'dark' matches
+  // with nothing here asking for it - every screenshot taken without
+  // --scheme would silently show this site's dark theme instead of its
+  // actual 'colored' (light) default. Forcing 'light' makes an unflagged
+  // capture deterministic and representative of what a visitor with no
+  // saved choice and no OS dark-mode preference actually sees.
+  if (flags.scheme !== undefined && flags.scheme !== 'light' && flags.scheme !== 'dark')
+    throw new TypeError(`Invalid --scheme "${String(flags.scheme)}". Expected "light" or "dark".`)
+  const scheme = typeof flags.scheme === 'string' ? flags.scheme : 'light'
   try {
     if (command === 'navigate' || command === 'go') {
       const cdp = await openPage(session.port)
@@ -794,7 +809,7 @@ async function main() {
         throw new TypeError(`--full, --element, and --scroll-y are mutually exclusive; got ${modes.join(', ')}.`)
       const out = (flags.out as string) || `storage/framework/runtime/shots/${new URL(url).pathname.replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '') || 'home'}.png`
       mkdirSync(out.split('/').slice(0, -1).join('/') || '.', { recursive: true })
-      const state = await gotoAndInstrument(cdp, url, { viewport, scale, cookies, settleMs, scheme })
+      const state = await gotoAndInstrument(cdp, url, { viewport, scale, cookies, settleMs, scheme, reducedMotion: !!flags.full || !!flags.element })
       const png = await captureScreenshot(cdp, { full: !!flags.full, element: flags.element as string | undefined, scrollY: scrollY ?? undefined })
       await Bun.write(out, png)
       console.log(JSON.stringify({ url, out, viewport: `${viewport.w}x${viewport.h}`, scale, full: !!flags.full, element: flags.element ?? null, scrollY: scrollY ?? null, bytes: png.length }, null, 2))
@@ -808,7 +823,7 @@ async function main() {
       const results: any[] = []
       for (const bp of BREAKPOINTS) {
         const cdp = await openPage(session.port)
-        const state = await gotoAndInstrument(cdp, url, { viewport: { w: bp.w, h: bp.h }, cookies, settleMs, scheme })
+        const state = await gotoAndInstrument(cdp, url, { viewport: { w: bp.w, h: bp.h }, cookies, settleMs, scheme, reducedMotion: true })
         const overflow = await cdp.send('Runtime.evaluate', {
           expression: 'document.body.scrollWidth > window.innerWidth ? document.body.scrollWidth - window.innerWidth : 0',
           returnByValue: true,
@@ -874,7 +889,7 @@ async function main() {
 
       const cdp = await openPage(session.port)
       const viewport = parseViewport(typeof flags.viewport === 'string' ? flags.viewport : undefined)
-      const state = await gotoAndInstrument(cdp, url, { viewport, cookies, settleMs, scheme })
+      const state = await gotoAndInstrument(cdp, url, { viewport, cookies, settleMs, scheme, reducedMotion: !!flags.full })
       const results: Record<string, unknown>[] = []
       await cdp.send('Page.bringToFront')
       await cdp.send('Runtime.evaluate', {

package/ai/skills/stacks-new-feature/SKILL.md

@@ -121,6 +121,33 @@ route.group({ prefix: '/articles', middleware: ['auth'] }, () => {
 
 Or rely on auto-generated routes from `useApi` trait — they're created automatically.
 
+### When a TypeScript client will call these
+
+Register through `createTypedRouter()` instead, and the client gets full
+input/output inference with no `buddy generate:openapi` step in between:
+
+```typescript
+// routes/api.ts
+import CreateArticle from '../app/Actions/CreateArticle'
+import ListArticles from '../app/Actions/ListArticles'
+import { createTypedRouter } from '@stacksjs/router'
+
+export const api = createTypedRouter()
+  .get('/articles', ListArticles, { middleware: 'auth' })
+  .post('/articles', CreateArticle, { middleware: 'auth' })
+
+export type AppRoutes = typeof api
+```
+
+```typescript
+const client = createTypedClient<AppRoutes>({ baseUrl })
+const created = await client.post('/articles', { title: 'x', content: 'y' })
+```
+
+Same runtime path, same middleware, same OpenAPI document — the difference is
+entirely at compile time. Keep the string form for routes no TypeScript consumer
+calls; it stays lazily imported. See the `stacks-api` and `stacks-router` skills.
+
 ## Step 5: Add Event Listeners (Optional)
 
 ```typescript

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

@@ -47,10 +47,103 @@ route.group({ prefix: '/api/v1', middleware: ['auth', 'throttle'] }, () => {
 ```
 
 ### Handler Types
-- Function: `(req: EnhancedRequest) => Response | Promise<Response>`
-- Action string: `'Actions/CreateUser'` — auto-loads action
+- Function: `(req) => …` — return a `Response`, or any value `formatResult`
+  handles: an object/array becomes JSON, a string becomes text, `null` becomes
+  204, a `ReadableStream` streams. `req.params` is narrowed to the path's own
+  placeholders, so `req.params.slugTypo` is a compile error rather than
+  `undefined` at runtime.
+- Action string: `'Actions/CreateUser'` — auto-loads action, lazily
+- Action object: an imported action, passed directly — see typed routes below
 - Controller: `'Controllers/UserController@index'` — calls controller method
 
+## The strings are typed (run `buddy generate:types`)
+
+Action paths, middleware aliases and route names are all checked at compile
+time against what this application actually has. `buddy generate:types`
+discovers them and writes them into the router's type registry
+(`storage/framework/types/actions.d.ts`); nothing is maintained by hand.
+
+```typescript
+route.get('/login', 'Actions/Auth/LogniAction')   // ✗ no such action
+route.get('/admin', handler).middleware('atuh')   // ✗ no such middleware alias
+url('email.unsubscrbe', { token })                // ✗ no such route name
+url('user.post', { id: 42 })                      // params come from the path
+```
+
+The middleware one is the one that matters most: a typo'd alias used to serve
+the route **without** the protection, silently.
+
+Notes:
+- Controllers stay a pattern (`'Controllers/X@method'`) — the method half is a
+  member name, not a filename.
+- Negated (`'!auth'`) and parameterised (`'throttle:60,1'`) middleware forms are
+  both accepted.
+- Regenerate after adding an action, a middleware alias, or a `.name()`. A stale
+  file rejects code that is correct.
+- `resource()` takes a BASE, and composes `Actions/<Base><Kind>Action` from it.
+  `route.resource('posts', 'Post')` → `Actions/PostIndexAction`, matching where
+  `buddy make:crud` writes. The base is checked against the actions that exist;
+  which of the five siblings you need depends on `only`/`except`, so that part
+  is settled when the route is hit.
+
+### Path params arrive decoded
+
+`/users/{name}` given `/users/caf%C3%A9` hands the handler `café`, and `%2F`
+becomes a real `/`. Decoded exactly once, in bun-router — do NOT decode again in
+an action or middleware: two passes turn `%2520` into a space, which is how a
+filter that rejects `../` gets walked past. A malformed escape (`%ZZ`) passes
+through raw rather than failing the request.
+
+A decoded param can contain `/`, so anything joining one into a filesystem path
+still has to sanitise. Decoding makes the value correct, not safe.
+
+## Typed Routes (zero generation)
+
+`route.get('/x', 'Actions/Foo')` resolves its action by a dynamic `import()` of a
+string. Good for the runtime — lazy, hot-reload friendly — and completely opaque
+to the compiler, so no client can be typed from it without a generation step.
+
+`createTypedRouter()` registers through the same router while accumulating a
+route map into its own type:
+
+```typescript
+import IndexAction from '../app/Actions/Project/IndexAction'
+import StoreAction from '../app/Actions/Project/StoreAction'
+import { createTypedRouter } from '@stacksjs/router'
+
+export const api = createTypedRouter()
+  .get('/v1/projects', IndexAction)
+  .post('/v1/projects', StoreAction, { middleware: 'auth', rateLimit: { max: 10 } })
+
+export type AppRoutes = typeof api
+```
+
+Any TypeScript consumer then gets full inference with **no CLI step**:
+
+```typescript
+import { createTypedClient } from '@stacksjs/router'
+
+const client = createTypedClient<AppRoutes>({ baseUrl })
+const projects = await client.get('/v1/projects')   // typed from the action
+```
+
+Facts worth knowing before using it:
+
+- **One runtime path.** A directly-registered action goes through the same
+  `wrapAction` as a string-registered one — validation, `authorize`, `before`,
+  `formatResult`, error reporting. Only the compile-time story differs.
+- **Input from `validations`, output from `handle`'s return type.** An action
+  returning a `Response` is typed `unknown`; it took over the wire format.
+- **Options are an argument**, not chained — chaining would return the route and
+  lose the accumulated type.
+- **No `.group()`.** A runtime-only prefix makes every path type wrong; a
+  type-only prefix is a second place for the URL to live.
+- **Both forms feed OpenAPI.** Directly-registered actions are reported by
+  `listRegisteredRoutes()`, so the generator reads their schema with no file
+  path to import.
+- The builder, the client and the contract live in `@stacksjs/bun-router` and
+  are re-exported here. See the `stacks-api` skill for the full client story.
+
 ## Route Registry (app/Routes.ts)
 
 ```typescript

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.72.56",
+  "version": "0.72.57",
   "description": "A modern Stacks development environment.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.72.56",
+  "version": "0.72.57",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -51,7 +51,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.27",
-    "@stacksjs/mobile": "^0.72.56",
+    "@stacksjs/mobile": "^0.72.57",
     "@stacksjs/sanitizer": "^0.2.113"
   },
   "scripts": {