@webjsdev/cli 0.10.14 → 0.10.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.14",
+  "version": "0.10.15",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/.agents/rules/workflow.md

@@ -144,14 +144,18 @@ self-review loop.
   `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in
   `firstUpdated`) instead of Lit's `classMap` / `styleMap` / `ref` / `when` /
   `choose` / `guard`.
-- Use Context for cross-component data, Task for async data in components.
+- Use Context for cross-component data. For async data in a component, prefer
+  an `async render()` (`const u = await getUser(this.uid)`, awaited at SSR so
+  the data is in the first paint); keep `Task` for genuinely client-only data.
 - **Progressive enhancement is the default.** Pages AND every web component
   are SSR'd to real HTML. Write components so the first paint is the right
   content. Read SSR-meaningful defaults in `constructor()`. `connectedCallback`
   is never called on the server, so anything there only runs after
   hydration. Initial data for components comes from the page function
-  (server-side fetch plus pass as attribute/property), NOT from `fetch` calls
-  in `connectedCallback`. For write-paths, prefer `<form action=...>` plus
+  (server-side fetch plus pass as attribute/property) OR from an `async
+  render()` in the component itself (preferred over prop-drilling;
+  `renderFallback()` is the optional re-fetch loading state, never first
+  paint), NOT from `fetch` calls in `connectedCallback`. For write-paths, prefer `<form action=...>` plus
   server action over `fetch` plus click handler. The framework upgrades plain
   forms to partial-swap submissions automatically.
 - **Client navigation is auto-magic.** Real `<a href>` and `<form action>`

package/templates/.cursorrules

@@ -109,6 +109,6 @@ self-review loop.
 - Components must call customElements.define('tag', Class)
 - Server-only code (@prisma/client, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files.
 - Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported. Use plain template-literal expressions (`class=${cond ? 'a' : 'b'}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead.
-- **Progressive enhancement is the default.** Pages AND every web component are SSR'd to real HTML. Write components so the first paint is the right content. Read SSR-meaningful defaults in `constructor()`. `connectedCallback` is never called on the server, so anything there only runs after hydration. Initial data for components comes from the page function (server-side fetch plus pass as attribute/property), NOT from `fetch` calls in `connectedCallback`. For write-paths, prefer `<form action=...>` plus server action over `fetch` plus click handler. The framework upgrades plain forms to partial-swap submissions automatically.
+- **Progressive enhancement is the default.** Pages AND every web component are SSR'd to real HTML. Write components so the first paint is the right content. Read SSR-meaningful defaults in `constructor()`. `connectedCallback` is never called on the server, so anything there only runs after hydration. Initial data for components comes from the page function (server-side fetch plus pass as attribute/property) OR from an `async render()` in the component itself (`const u = await getUser(this.uid)`, which SSR awaits so the data is in the first paint), NOT from `fetch` calls in `connectedCallback`. Prefer the co-located `async render()` over prop-drilling; `renderFallback()` is the optional re-fetch loading state (never first paint), and a `Task` is for genuinely client-only data. For write-paths, prefer `<form action=...>` plus server action over `fetch` plus click handler. The framework upgrades plain forms to partial-swap submissions automatically.
 - **Client navigation is auto-magic.** Real `<a href>` and `<form action>` get partial-swap behavior with no opt-in. Because layouts persist across navigation, put shared chrome (sidenav, header) in `layout.ts` and page-specific content in `page.ts`. For validation errors, return 4xx HTML from a `route.ts` POST handler; the router renders it in place preserving the user's input. For non-layout swap regions, wrap in `<webjs-frame id="...">`. See "Client navigation patterns" in AGENTS.md.
 - See AGENTS.md for the complete directive decision guide

package/templates/.github/copilot-instructions.md

@@ -102,6 +102,7 @@ each change must include.
 - Tagged template: html`<div>${value}</div>` with css`...` for styles.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css\`...\``) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag. Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`...\`` for scoped CSS; don't use inline `style="..."` there.
 - Components: extend WebComponent, declare `static properties` (and `static styles` for shadow-DOM components), call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field.
+- Async data in a component: prefer an `async render()` (`const u = await getUser(this.uid)`), which SSR awaits so the data is in the first paint, over prop-drilling from the page or fetching in `connectedCallback`. `renderFallback()` is the optional re-fetch loading state (never first paint); error isolation is automatic (`renderError()` customizes it); a `Task` is for genuinely client-only data.
 - Server actions: *.server.ts files with one exported async function each.
 - Server-only code (@prisma/client, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
 - Directives: webjs ships only `unsafeHTML`, `live`, and `repeat`. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported. Use plain template-literal expressions and lifecycle hooks instead.

package/templates/AGENTS.md

@@ -86,7 +86,8 @@ node_modules/@webjsdev/
                     auth, sessions, cache, rate-limit, WebSocket
     src/ssr.js                ← how metadata becomes <head> tags
     src/router.js             ← file convention → route table
-    src/actions.js            ← .server.ts scanner, RPC, expose()
+    src/actions.js            ← .server.ts scanner, RPC stubs, action endpoint
+    src/action-route.js       ← route() adapter (action over REST via route.ts)
     src/auth.js, session.js, cache.js, rate-limit.js, csrf.js
   cli/             webjs CLI (dev / start / build / test / check / create / db)
   intellisense/    tsserver plugin: go-to-definition + diagnostic suppression
@@ -677,7 +678,9 @@ Practical consequences for agents writing webjs code.
 | Lit pattern | What breaks in webjs | Webjs equivalent |
 |---|---|---|
 | Fetch in `connectedCallback` / `firstUpdated` | Empty first paint (neither hook runs in SSR) | Fetch in the page function, pass as props |
-| `Task` for initial-paint data | SSR ships the pending state, flashes to resolved on hydration | Page function fetch, pass as props (`Task` is fine for client-time async) |
+| `Task` for initial-paint data | SSR ships the pending state, flashes to resolved on hydration | Page function fetch, pass as props, OR an `async render()` in the component (`Task` is fine for client-time async) |
+| Expecting a sync `render()` only | webjs allows `async render() { const d = await getData(); ... }`; SSR bakes the data into the first paint | Use it for request-time server data; `renderFallback()` is the re-fetch loading UI (never first paint); error isolation is automatic |
+| Assuming an `async render()` always ships its module | A bare one (no other client signal) is ELIDED, so it costs zero JS and skips the on-hydration re-fetch, first paint unchanged | Rely on it for a fetch-and-display leaf. `static refresh = true` keeps the on-load refresh, `static shadow = true` always ships |
 | `window.X` / `document.X` in constructor or `render()` | SSR crash | Move to `connectedCallback` |
 | Top-level `import` of a browser-only library | SSR crash | Dynamic `import()` inside `connectedCallback` |
 | Class-field initializer for a reactive property (`student: Student = {...}`) | Silently breaks reactivity (overwrites the framework accessor) | `declare student: Student` plus constructor default |
@@ -812,6 +815,14 @@ here is for the "submit → server processes → render new page" flow.)
 
 ### 4. `<webjs-frame id="...">` for non-layout swap regions
 
+`<webjs-frame>` is webjs's take on **Turbo Frames** (Hotwire Turbo), so
+`<turbo-frame>` muscle memory transfers directly: a lazy, URL-addressable
+region that swaps on its own, driven by a link/form targeting its id. Use it
+for a region that loads or refreshes INDEPENDENTLY of a full navigation
+(a self-refreshing widget, a `loading="lazy"` below-the-fold region, a
+URL-addressable panel); it ships zero component JS. Its route can itself use
+`<webjs-suspense>` so a lazy frame's slow data streams in behind a fallback.
+
 For a widget that should swap on click but isn't a route boundary
 (e.g. a tab strip inside a page), wrap it:
 
@@ -880,6 +891,14 @@ over the outcome (e.g. `location.assign(e.detail.url)`).
 
 ### 5. Stream actions for surgical element-level updates
 
+`<webjs-stream>` is webjs's take on **Turbo Streams** (Hotwire Turbo); the
+action set (`append` / `prepend` / `before` / `after` / `replace` / `update` /
+`remove`) mirrors `<turbo-stream>`, so that muscle memory transfers directly.
+It is the ONLY surgical single-element update primitive AND the live-channel
+applier (`connectWS` / `broadcast` -> `renderStream`); a region swap or a
+`<webjs-frame>` reload redraws a whole region, so reach for `<webjs-stream>`
+when only one element changes.
+
 When a region swap is too coarse (append ONE comment, remove ONE row, bump a
 count, insert a toast), a server response can declare per-element actions as
 plain HTML, a `<webjs-stream action target>` wrapping one `<template>`:

package/templates/CONVENTIONS.md

@@ -387,6 +387,7 @@ modules/
 - Components must call `Class.register('tag')`
 - **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** Direct imports of `@prisma/client` or `node:*` from pages, layouts, or components crash the browser at module load. Wrap in a `.server.{js,ts}` file; the framework rewrites that import to an RPC stub on the browser side. `lib/` holds both server-only infra (`lib/prisma.server.ts`) and browser-safe utilities (`lib/utils/cn.ts` with `cn`); the convention is "if a `lib/` file needs Node APIs, only import it from server-only files."
 - Routes (`app/**/page.ts`, `app/**/route.ts`) must be thin: import logic from modules
+- **Fetch server data in the component that needs it, with an `async render()`, not by prop-drilling.** A leaf component can write `const u = await getUser(this.uid)` directly in `render()`; SSR awaits it so the data is in the first paint, and the client uses stale-while-revalidate on a re-fetch. Reach for `renderFallback()` only to show a re-fetch loading state, and `Task` / signals only for genuinely client-only data (a `Task` shows its pending state at SSR, losing first-paint data). Do not put `await getData()` in a page / layout when a leaf component can own it (page fetches run sequentially, a route-level waterfall).
 
 ---
 
@@ -907,27 +908,37 @@ SSR content is visible immediately. Only the JS download is deferred.
 
 ---
 
-## expose(): REST endpoints from server actions
+## REST endpoints from server actions (route.ts)
 
 <!-- OVERRIDE -->
-Tag a server action to also be reachable over HTTP. The file MUST be a `.server.{js,ts}` file: `expose()` is server-only and the bare `@webjsdev/core` specifier resolves to the browser entry which excludes it, so importing from a client-bound file silently reads `undefined`.
+A server action is RPC-callable from components. To ALSO reach the same
+function over plain HTTP (mobile apps, webhooks, third parties), put it behind
+a `route.ts` handler. The action stays a normal `'use server'` function; the
+route imports and calls it.
 
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
-import { expose } from '@webjsdev/core';
-export const createPost = expose('POST /api/posts', async ({ title, body }) => {
+export async function createPost({ title, body }) {
   return prisma.post.create({ data: { title, body } });
-});
+}
+```
+
+```ts
+// app/api/posts/route.ts
+import { route } from '@webjsdev/server';
+import { createPost } from '../../../modules/posts/actions/create-post.server.ts';
+// The route() adapter merges query + route params + JSON body into one input
+// object and JSON-responds the result. Pass { validate } to guard the input.
+export const POST = route(createPost);
 ```
 
-The same function works via RPC (from components) and HTTP (for external
-callers). Use `expose()` when mobile apps, webhooks, or third parties need
-to call your action. For internal-only actions, plain server actions are
-simpler and CSRF-protected.
+A hand-written `route.ts` (a `POST(req)` that reads the body and calls the
+action) is always available for full control (custom headers, streaming).
 
-**Security:** `expose()`d endpoints are NOT CSRF-protected. Authenticate
-via bearer tokens, API keys, or auth middleware.
+**Security:** a `route.ts` REST endpoint is NOT CSRF-protected (only the RPC
+path is). Authenticate every mutating endpoint via bearer tokens, API keys, or
+auth middleware.
 
 ---