@webjsdev/cli 0.10.36 → 0.10.38

package/templates/gallery/modules/client-router/components/router-controls.ts

@@ -1,22 +1,50 @@
 // Programmatic client navigation. `navigate(url)` does the same soft, in-place
 // swap an <a> click does, but from an event handler (after a save, a wizard
 // step, etc.). `revalidate(url?)` evicts the browser snapshot cache so the next
-// visit refetches fresh HTML instead of the cached page. Both are client-only
-// (they run in the browser), so a component is the right home; a page/layout
-// never hydrates. With JS off this component is inert, so keep real navigation
-// on plain <a href> and use navigate() only for JS-driven flows.
-import { WebComponent, html, navigate, revalidate } from '@webjsdev/core';
+// visit refetches fresh HTML instead of the cached page. `disableClientRouter()`
+// / `enableClientRouter()` turn soft navigation off / back on at runtime (for a
+// moment where you want a full page load, e.g. handing off to a third-party
+// flow). disableClientRouter() removes the document-level <a>/<form> click
+// interception, so PLAIN links start doing full page loads again. It does NOT
+// affect navigate(), which is an explicit programmatic swap the toggle never
+// intercepts, so the plain link below is what visibly changes when you toggle.
+// All are client-only (they run in the browser), so a component is the right
+// home; a page/layout never hydrates. With JS off the plain link still works
+// (progressive enhancement), while the buttons are inert.
+import { WebComponent, html, signal, navigate, revalidate, disableClientRouter, enableClientRouter } from '@webjsdev/core';
 
 export class RouterControls extends WebComponent {
+  // Instance signal mirroring whether soft navigation is currently on.
+  private soft = signal(true);
+
+  private toggleRouter() {
+    if (this.soft.get()) disableClientRouter();
+    else enableClientRouter();
+    this.soft.set(!this.soft.get());
+  }
+
   render() {
+    const soft = this.soft.get();
     return html`
-      <div class="flex gap-3 items-center">
-        <button
-          @click=${() => navigate('/features/client-router/second')}
-          class="inline-flex items-center px-4 py-2 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">navigate() to page two</button>
-        <button
-          @click=${() => revalidate()}
-          class="text-muted-foreground font-medium text-sm cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">revalidate() the snapshot cache</button>
+      <div class="grid gap-3">
+        <div class="flex flex-wrap gap-3 items-center">
+          <button
+            @click=${() => navigate('/features/client-router/second')}
+            class="inline-flex items-center px-4 py-2 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">navigate() to page two</button>
+          <button
+            @click=${() => revalidate()}
+            class="text-muted-foreground font-medium text-sm cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">revalidate() the snapshot cache</button>
+          <button
+            @click=${() => this.toggleRouter()}
+            class="text-muted-foreground font-medium text-sm cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">${soft ? 'disableClientRouter()' : 'enableClientRouter()'} (soft nav: ${soft ? 'on' : 'off'})</button>
+        </div>
+        <p class="text-sm text-muted-foreground">
+          Plain link:
+          <a href="/features/client-router/second" class="text-primary underline">/features/client-router/second</a>.
+          ${soft
+            ? html`The router is on, so this soft-navigates (no full reload). Toggle it off, then click again to watch the browser do a full page load.`
+            : html`The router is off, so this now does a FULL page load. The navigate() button still soft-navigates (it is explicit and ignores the toggle).`}
+        </p>
       </div>
     `;
   }

package/templates/gallery/modules/components/components/browser/counter-card.test.js

@@ -9,7 +9,7 @@
 //     REAL SSR output and the client interactivity, not a jsdom approximation.
 // It lives NEXT TO the component (a `browser/` dir inside the module), the
 // co-located default; the runner discovers browser tests under any browser dir.
-import { html } from '@webjsdev/core';
+import { html, render } from '@webjsdev/core';
 import { ssrFixture } from '@webjsdev/core/testing';
 import '../counter-card.ts';
 
@@ -22,6 +22,26 @@ suite('<counter-card>', () => {
     assert(el.textContent.includes('Clicks'), 'the default label renders');
   });
 
+  test('render() mounts a template imperatively into a container', async () => {
+    // render(value, container) is the client-side imperative render: mount a
+    // WebJs template into any DOM node (a portal, a plain page). Components
+    // render themselves, so reach for this only when you need to drive the
+    // mount point yourself. The container must be CONNECTED to the document, or
+    // the custom element never upgrades (connectedCallback, and so its first
+    // render, only fire on connection).
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    try {
+      render(html`<counter-card label="Imperative"></counter-card>`, container);
+      const el = container.querySelector('counter-card');
+      assert(el, 'the element mounts into the container');
+      await el.updateComplete; // wait for the component's first client render
+      assert(container.textContent.includes('Imperative'), 'the label renders');
+    } finally {
+      container.remove();
+    }
+  });
+
   test('reads the label reactive prop', async () => {
     const el = await ssrFixture(html`<counter-card label="Taps"></counter-card>`);
     assert(el.textContent.includes('Taps'), 'the provided label renders');

package/templates/gallery/modules/components/components/server-render.test.ts

@@ -0,0 +1,20 @@
+// A node unit test (webjs test --server): `renderToString` server-renders an
+// html`` template to a string, with Declarative Shadow DOM for shadow-DOM
+// components. Import it from `@webjsdev/core/server` (NOT the root), so the test
+// stays explicit about which side it runs on. Use it to assert SSR output and
+// escaping without a browser; for a full request through the pipeline, use the
+// handle() harness from @webjsdev/server/testing instead (see the testing docs).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { html } from '@webjsdev/core';
+import { renderToString } from '@webjsdev/core/server';
+
+test('renderToString renders interpolated text and escapes it', async () => {
+  const out = await renderToString(html`<p>${'hello'}</p>`);
+  assert.match(out, /hello/);
+});
+
+test('renderToString escapes an interpolated angle bracket (no injection)', async () => {
+  const out = await renderToString(html`<p>${'<script>'}</p>`);
+  assert.doesNotMatch(out, /<script>/);
+});

package/templates/gallery/modules/components/components/task-loader.ts

@@ -0,0 +1,48 @@
+// `Task` runs an async function and exposes its state (via `TaskStatus`:
+// INITIAL / PENDING / COMPLETE / ERROR) so render() can show a spinner, the
+// value, or an error without hand-rolling the bookkeeping. Use it for
+// genuinely CLIENT-only async data (a browser-driven fetch, a retry-on-click
+// load). For request-time server data that should be in the first paint, prefer
+// `async render()` instead, which blocks SSR so the data is server-rendered;
+// a Task shows its PENDING state at SSR, so the value is not in the first paint.
+import { WebComponent, html } from '@webjsdev/core';
+import { Task, TaskStatus } from '@webjsdev/core/task';
+
+export class TaskLoader extends WebComponent {
+  // Bumped on each reload so args change and the task re-runs.
+  private attempt = 0;
+
+  // Task calls task(...args(), { signal }), so the args() array is SPREAD into
+  // positional parameters (not passed as one array). One arg here, so read it
+  // directly as `attempt`.
+  private task = new Task<string>(this, {
+    task: async (attempt: number) => {
+      await new Promise((r) => setTimeout(r, 600));
+      if (attempt % 3 === 2) throw new Error('unlucky attempt');
+      return `loaded on attempt #${attempt}`;
+    },
+    args: () => [this.attempt],
+  });
+
+  private reload() {
+    this.attempt += 1;
+    this.task.run();
+  }
+
+  render() {
+    const t = this.task;
+    const body =
+      t.status === TaskStatus.PENDING ? html`<span class="text-muted-foreground">loading…</span>`
+      : t.status === TaskStatus.ERROR ? html`<span class="text-red-500">error: ${String((t.error as Error)?.message ?? t.error)}</span>`
+      : t.status === TaskStatus.COMPLETE ? html`<span class="text-foreground">${t.value}</span>`
+      : html`<span class="text-muted-foreground">idle</span>`;
+    return html`
+      <div class="flex items-center gap-3 text-[15px]">
+        <button @click=${() => this.reload()}
+          class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">reload</button>
+        ${body}
+      </div>
+    `;
+  }
+}
+TaskLoader.register('task-loader');

package/templates/gallery/modules/components/components/theme-context.ts

@@ -0,0 +1,67 @@
+// The context API: pass a value down to descendant components WITHOUT threading
+// it through every level as an attribute. `createContext(name)` mints a typed
+// key; a `ContextProvider` on an ancestor holds the value; a `ContextConsumer`
+// on any descendant reads it (and, with `subscribe: true`, re-renders when it
+// changes). Under the hood a consumer dispatches a `ContextRequestEvent` that
+// bubbles up to the nearest provider, which is the low-level protocol the two
+// controllers automate. All light DOM, so the provider's <slot> projects its
+// children normally.
+import { WebComponent, html, signal } from '@webjsdev/core';
+import { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from '@webjsdev/core/context';
+
+type Theme = 'light' | 'dark';
+
+// One shared key. Descendants that read `themeContext` get the provider's value.
+export const themeContext = createContext<Theme>('demo-theme');
+
+export class ThemeProvider extends WebComponent {
+  // The provider holds the value. setValue() pushes it to every subscribing
+  // consumer in one shot.
+  private provider = new ContextProvider<Theme>(this, { context: themeContext, initialValue: 'light' });
+
+  private toggle() {
+    this.provider.setValue(this.provider.value === 'light' ? 'dark' : 'light');
+    this.requestUpdate(); // re-render the provider's own button label too
+  }
+
+  render() {
+    return html`
+      <div class="grid gap-3 p-3 rounded-xl bg-card border border-border max-w-[420px]">
+        <button @click=${() => this.toggle()}
+          class="w-fit px-3.5 py-1.5 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">
+          provider theme: ${this.provider.value} (toggle)
+        </button>
+        <slot></slot>
+      </div>
+    `;
+  }
+}
+ThemeProvider.register('theme-provider');
+
+export class ThemeConsumer extends WebComponent {
+  // subscribe: true re-renders this element whenever the provider calls setValue.
+  private consumer = new ContextConsumer<Theme>(this, { context: themeContext, subscribe: true });
+  private lastRead = signal<Theme | 'not read yet'>('not read yet');
+
+  // The imperative escape hatch: dispatch a ContextRequestEvent yourself to
+  // grab the current value ONCE without subscribing. It bubbles up to the
+  // nearest provider, which answers via the callback.
+  private readOnce() {
+    this.dispatchEvent(
+      new ContextRequestEvent<Theme>(themeContext, (value) => this.lastRead.set(value), false),
+    );
+  }
+
+  render() {
+    const theme = this.consumer.value ?? 'light';
+    return html`
+      <div class="flex items-center gap-3 text-[15px] text-foreground">
+        <span>child sees: <strong>${theme}</strong></span>
+        <button @click=${() => this.readOnce()}
+          class="px-3 py-1 rounded-lg text-sm bg-card border border-border text-foreground cursor-pointer transition-colors hover:border-border-strong">read once</button>
+        <span class="text-muted-foreground text-sm">last one-shot: ${this.lastRead.get()}</span>
+      </div>
+    `;
+  }
+}
+ThemeConsumer.register('theme-consumer');

package/templates/gallery/modules/directives/components/directive-demo.ts

@@ -1,4 +1,4 @@
-// The lit-html directive set webjs re-exports (from '@webjsdev/core/directives').
+// The lit-html directive set WebJs re-exports (from '@webjsdev/core/directives').
 // `repeat` keys a list so DOM nodes are REUSED across reorders instead of being
 // recreated (use it for keyed lists that reorder; plain `.map()` is fine for
 // static lists). `watch(signal)` does a fine-grained DOM swap of ONE node when
@@ -6,9 +6,13 @@
 // shows more of the set: `live` (a controlled input), `ref` + `createRef` (a
 // handle to a DOM node), `until` (a pending fallback for a promise),
 // `unsafeHTML` (trusted raw HTML, NEVER user input), and `keyed` (force a fresh
-// subtree when a key changes).
+// subtree when a key changes). The third card shows the rest: `guard` (skip a
+// re-render when its deps are unchanged), `cache` (keep an inactive branch's
+// DOM around while you toggle), `templateContent` (stamp an existing template's
+// HTML), and `asyncAppend` / `asyncReplace` (stream values from an async
+// iterable, appending each or replacing with the latest).
 import { WebComponent, signal, html } from '@webjsdev/core';
-import { repeat, watch, live, until, keyed, unsafeHTML, ref, createRef } from '@webjsdev/core/directives';
+import { repeat, watch, live, until, keyed, unsafeHTML, ref, createRef, guard, cache, templateContent, asyncAppend, asyncReplace } from '@webjsdev/core/directives';
 
 interface Item { id: number; label: string }
 
@@ -29,6 +33,57 @@ export class DirectiveDemo extends WebComponent {
   // Created ONCE (not per render), so `until` keeps the resolved value across
   // re-renders instead of flashing back to the fallback each time.
   private asyncValue: Promise<string> = this.later();
+  // Which cached branch is showing (for `cache`), and a counter that lets us
+  // prove `guard` skips its recompute unless its dep actually changes.
+  private tab = signal<'a' | 'b'>('a');
+  private guardBumps = signal(0);
+  // Async iterables consumed on the client (both render empty at SSR). The
+  // generators are lazy, so the field initializer just creates the iterator
+  // without running the body. Both are FINITE and run ONCE: they animate on
+  // first paint, then settle on their final value. restartStreams() swaps in
+  // fresh iterables to replay them (a new iterable identity makes asyncAppend /
+  // asyncReplace tear down and re-subscribe). streamRun is read in render() so
+  // the swap triggers a re-render.
+  private logIter: AsyncIterable<string> = this.log();
+  private countIter: AsyncIterable<number> = this.countdown();
+  private streamRun = signal(0);
+
+  private restartStreams() {
+    this.logIter = this.log();
+    this.countIter = this.countdown();
+    this.streamRun.set(this.streamRun.get() + 1);
+  }
+  // For `templateContent`: a real <template> element on the CLIENT (the client
+  // directive clones its `.content`), and a plain { innerHTML } object at SSR
+  // (there is no document to build a template with, and the server directive
+  // emits innerHTML directly). The real template is built in connectedCallback,
+  // which SSR never calls, so the two paths agree on the output.
+  private stampTpl: HTMLTemplateElement | { innerHTML: string } = {
+    innerHTML: '<strong>stamped</strong> from a template',
+  };
+
+  connectedCallback() {
+    super.connectedCallback();
+    const tpl = document.createElement('template');
+    tpl.innerHTML = '<strong>stamped</strong> from a template';
+    this.stampTpl = tpl;
+  }
+
+  // A finite async iterable: asyncAppend adds each line as it arrives.
+  private async *log(): AsyncGenerator<string> {
+    for (const line of ['connecting', 'authenticated', 'ready']) {
+      await new Promise((r) => setTimeout(r, 500));
+      yield line;
+    }
+  }
+  // A finite async iterable: asyncReplace shows only the latest value, counting
+  // down 5 -> 0 one step at a time.
+  private async *countdown(): AsyncGenerator<number> {
+    for (let n = 5; n >= 0; n--) {
+      yield n;
+      await new Promise((r) => setTimeout(r, 500));
+    }
+  }
 
   private reverse() {
     this.items.set(this.items.get().slice().reverse());
@@ -91,6 +146,48 @@ export class DirectiveDemo extends WebComponent {
             class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">rekey</button>
           ${keyed(variant, html`<div class="text-[15px] text-foreground">${unsafeHTML('<em>fresh subtree</em>')} #${variant}</div>`)}
         </div>
+
+        <div class="grid gap-3 border-t border-border pt-4">
+          <!-- guard([deps], fn) only re-runs fn when a dep changes. Bumping the
+               guard counter re-renders it; the OTHER counter (ticks above) does
+               not, so the guarded value stays put. -->
+          <button @click=${() => this.guardBumps.set(this.guardBumps.get() + 1)}
+            class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">bump guard dep</button>
+          <p class="text-sm text-foreground">guarded: ${guard([this.guardBumps.get()], () => html`computed at bump #${this.guardBumps.get()}`)}</p>
+
+          <!-- cache(value) keeps the inactive tab's DOM alive while you toggle,
+               so switching back is instant and preserves any element state. -->
+          <div class="flex gap-2">
+            <button @click=${() => this.tab.set('a')}
+              class="px-3 py-1 rounded-lg text-sm border cursor-pointer transition-colors ${this.tab.get() === 'a' ? 'bg-primary text-primary-foreground border-transparent' : 'bg-card border-border text-foreground hover:border-border-strong'}">Tab A</button>
+            <button @click=${() => this.tab.set('b')}
+              class="px-3 py-1 rounded-lg text-sm border cursor-pointer transition-colors ${this.tab.get() === 'b' ? 'bg-primary text-primary-foreground border-transparent' : 'bg-card border-border text-foreground hover:border-border-strong'}">Tab B</button>
+          </div>
+          <div class="text-[15px] text-foreground">${cache(
+            this.tab.get() === 'a'
+              ? html`<span>Panel A content</span>`
+              : html`<span>Panel B content</span>`,
+          )}</div>
+
+          <!-- templateContent stamps a <template> element's content (see
+               stampTpl: a real template on the client, a plain { innerHTML } at
+               SSR, so first paint and hydration match). -->
+          <div class="text-[15px] text-foreground">${templateContent(this.stampTpl)}</div>
+
+          <!-- asyncAppend appends each value from an async iterable as it
+               arrives; asyncReplace shows only the latest. Both render empty at
+               SSR, stream in on the client, and finish (the log stops at
+               "ready", the countdown at 0). Restart swaps in fresh iterables so
+               you can watch them replay. The run counter forces the re-render. -->
+          <div class="flex items-center gap-3">
+            <button @click=${() => this.restartStreams()}
+              class="w-fit px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">restart streams</button>
+            <span class="text-sm text-muted-foreground">run #${this.streamRun.get()}</span>
+          </div>
+          <div class="text-sm text-muted-foreground">log (asyncAppend, one row per value):</div>
+          <ul class="grid gap-1 list-none m-0 p-0 text-sm text-muted-foreground min-h-[1.25rem]">${asyncAppend(this.logIter, (line: string) => html`<li>· ${line}</li>`)}</ul>
+          <p class="text-sm text-foreground">countdown (asyncReplace, latest value only): ${asyncReplace(this.countIter)}</p>
+        </div>
       </div>
     `;
   }

package/templates/gallery/modules/file-storage/actions/store-upload.server.ts

@@ -7,6 +7,9 @@
 // whitelisted extension.
 'use server';
 import { getFileStore, generateKey } from '@webjsdev/server';
+// Importing the config module runs setFileStore(diskStore(...)) once at load,
+// so uploads land in the configured store. See ../store.server.ts.
+import '../store.server.ts';
 
 export async function storeUpload(file: File) {
   if (!(file instanceof File) || file.size === 0) {

package/templates/gallery/modules/file-storage/store.server.ts

@@ -0,0 +1,29 @@
+// Server-only file-store configuration (no 'use server': a plain server
+// utility, imported by the upload action and the serve route). `setFileStore()`
+// swaps the active store; `diskStore()` is the built-in local-disk store
+// (streaming, traversal-safe), the drop-in slot for an S3 / R2 / GCS adapter of
+// the same shape. `signedUrl(key, { secret })` mints a time-limited,
+// tamper-proof download URL and `verifySignedUrl(input, secret)` checks it, so a
+// private file can be shared by link without making the serve route public.
+import { setFileStore, diskStore, signedUrl, verifySignedUrl } from '@webjsdev/server';
+
+// Configure the store once at module load. This mirrors the framework default
+// (a local diskStore under .webjs/uploads); in production swap diskStore for an
+// S3/R2 adapter with the same put/get/delete shape.
+setFileStore(diskStore({ dir: '.webjs/uploads' }));
+
+const URL_SECRET = process.env.FILE_URL_SECRET || 'dev-file-url-secret-change-me';
+
+// A 1-hour signed link to the serve route for a given key.
+export function signedDownloadUrl(key: string): string {
+  return signedUrl(key, {
+    secret: URL_SECRET,
+    base: `/features/file-storage/file/${encodeURIComponent(key)}`,
+    expiresIn: 3600,
+  });
+}
+
+// True when a request's ?key&exp&sig params are a valid, unexpired signature.
+export function isValidSignedRequest(url: string): boolean {
+  return verifySignedUrl(url, URL_SECRET).valid;
+}

package/templates/gallery/modules/route-handler/components/rich-data.ts

@@ -0,0 +1,31 @@
+// `richFetch(url, init?)` is a drop-in `fetch` for your own API routes that
+// preserves rich types: it sends Accept: application/vnd.webjs+json, and when
+// the route answered with `json(...)` it decodes the WebJs wire, so a `Date`
+// comes back as a real Date (not an ISO string), and Map / Set / BigInt / Blob
+// round-trip too. A plain-object `body` is encoded the same way. Client-only
+// (it runs in the browser), so it lives in a component; with JS off this button
+// is inert and the page still reads.
+import { WebComponent, signal, html, richFetch } from '@webjsdev/core';
+
+interface RichPayload { at: Date; ip: string; requestId: string; cookieCount: number }
+
+export class RichData extends WebComponent {
+  private line = signal('click to fetch');
+
+  private async load() {
+    const data = await richFetch<RichPayload>('/features/route-handler/data');
+    // data.at is a Date, so Date methods work with no manual parsing.
+    this.line.set(`at ${data.at.toLocaleTimeString()} · id ${data.requestId} · ${data.cookieCount} cookie(s)`);
+  }
+
+  render() {
+    return html`
+      <div class="flex items-center gap-3 text-[15px]">
+        <button @click=${() => this.load()}
+          class="px-3.5 py-1.5 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">richFetch() the route</button>
+        <span class="text-muted-foreground">${this.line.get()}</span>
+      </div>
+    `;
+  }
+}
+RichData.register('rich-data');

package/templates/gallery/modules/server-actions/actions/greet.server.ts

@@ -3,10 +3,18 @@
 // stub POSTing to the server. It may use server-only utilities (they run here,
 // server-side), which is why the util above stays off the client.
 import { shout } from '../utils/format.server.ts';
+import { actionContext, actionSignal } from '@webjsdev/server';
 import type { ActionResult } from '@webjsdev/server';
 
 export async function greet(input: { name: string }): Promise<ActionResult<{ message: string }>> {
-  const name = String(input?.name ?? '').trim();
+  // actionSignal() is the request's AbortSignal (fires on client disconnect or a
+  // superseded render); bail early on long work instead of finishing wasted work.
+  if (actionSignal().aborted) return { success: false, error: 'Request cancelled.', status: 499 };
+  // actionContext() is the per-action middleware context (e.g. actionContext().user
+  // set by an auth middleware via `export const middleware`). Empty here, no middleware.
+  const who = (actionContext().user as { name?: string } | undefined)?.name;
+
+  const name = String(input?.name ?? who ?? '').trim();
   if (!name) return { success: false, error: 'Name required.', status: 400 };
   return { success: true, data: { message: shout('hello ' + name) } };
 }

package/templates/gallery/modules/server-actions/actions/greet.test.ts

@@ -0,0 +1,37 @@
+// Example node test for the documented test helpers (from @webjsdev/server).
+// Run it with node --test (or webjs test after moving it under test/). The
+// handle() harness drives the FULL request pipeline: createRequestHandler({
+// appDir }) builds it, and rawActionRequest() fires a 'use server' action
+// through it (CSRF + the rich serializer included), returning the raw Response.
+// buildRouteTable(appDir) parses the file router; matchPage / matchApi resolve a
+// URL against it, params included. See the testing docs.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequestHandler, buildRouteTable, matchPage, matchApi, rawActionRequest } from '@webjsdev/server';
+
+const appDir = process.cwd();
+
+test('buildRouteTable + matchPage resolve a dynamic route with its params', async () => {
+  const table = await buildRouteTable(appDir);
+  const m = matchPage(table, '/features/routing/42');
+  assert.ok(m, 'the [id] route matches');
+  assert.equal(m.params.id, '42');
+});
+
+test('matchApi resolves the route-handler endpoint', async () => {
+  const table = await buildRouteTable(appDir);
+  const m = matchApi(table, '/features/route-handler/data');
+  assert.ok(m, 'the route.ts endpoint matches');
+});
+
+test('rawActionRequest fires the greet action through the pipeline', async () => {
+  const app = await createRequestHandler({ appDir, dev: true });
+  if (app.warmup) await app.warmup();
+  const res = await rawActionRequest(
+    app,
+    'modules/server-actions/actions/greet.server.ts',
+    'greet',
+    [{ name: 'Ada' }],
+  );
+  assert.equal(res.status, 200);
+});

package/templates/gallery/modules/sessions/session-config.server.ts

@@ -0,0 +1,31 @@
+// The session helpers. `session(opts)` builds session MIDDLEWARE; its storage is
+// pluggable. `cookieSessionStorage()` (alias `cookieSession`) keeps the whole
+// session in a signed cookie (stateless, the default). `storeSessionStorage()`
+// (alias `storeSession`) persists the session in the active store (memoryStore
+// in dev, Redis in prod via setStore()) and keeps only an id in the cookie, for
+// larger or server-held sessions. `getSession(req)` reads the current session
+// inside a route or middleware the session wraps.
+import { session, getSession, cookieSession, cookieSessionStorage, storeSession, storeSessionStorage } from '@webjsdev/server';
+
+// A dev fallback keeps a fresh scaffold booting; set SESSION_SECRET in .env for
+// any real deployment (and fail fast in production).
+const trimmed = process.env.SESSION_SECRET?.trim();
+if (process.env.NODE_ENV === 'production' && !trimmed) {
+  throw new Error('SESSION_SECRET must be set in production');
+}
+const secret = trimmed || 'dev-insecure-session-secret-change-me';
+
+// Cookie-backed session middleware (all state in a signed cookie): the default
+// this demo applies. cookieSession() is the alias for cookieSessionStorage().
+export const cookieSessions = session({ secret, storage: cookieSession() });
+
+// Store-backed alternative (session in the active store, id in the cookie).
+// storeSession() is the alias for storeSessionStorage(); swap it in above for
+// larger sessions. Kept here to show both strategies.
+export const storeSessions = session({ secret, storage: storeSession() });
+
+// Equivalent explicit spellings (the aliases just name the storage factories):
+export const cookieStorageExplicit = cookieSessionStorage();
+export const storeStorageExplicit = storeSessionStorage();
+
+export { getSession };

package/templates/gallery/modules/websockets/components/ws-echo.ts

@@ -4,7 +4,7 @@
 // it never runs during SSR) and closed in disconnectedCallback. At SSR the
 // component renders its disconnected state, so with JS off the page still reads
 // (a live socket has no no-JS equivalent, which is the honest fallback here).
-import { WebComponent, signal, html, connectWS } from '@webjsdev/core';
+import { WebComponent, signal, html, connectWS, renderStream } from '@webjsdev/core';
 
 export class WsEcho extends WebComponent {
   private connected = signal(false);
@@ -36,6 +36,19 @@ export class WsEcho extends WebComponent {
     input.value = '';
   }
 
+  #streamN = 0;
+  // renderStream() applies a <webjs-stream> payload with native DOM methods:
+  // the SAME element-level applier a connectWS onMessage handler (or a
+  // broadcast() push) uses for surgical live updates, so a chat / presence /
+  // toast reuses it instead of hand-written DOM code. Here a button drives it
+  // locally; over a channel the server would send this HTML string.
+  private applyStreamUpdate() {
+    this.#streamN += 1;
+    renderStream(
+      `<webjs-stream action="append" target="ws-stream-log"><template><li class="px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">streamed row #${this.#streamN}</li></template></webjs-stream>`,
+    );
+  }
+
   render() {
     const on = this.connected.get();
     return html`
@@ -55,6 +68,11 @@ export class WsEcho extends WebComponent {
             <li class="px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground font-mono">${line}</li>
           `)}
         </ul>
+        <div class="grid gap-2 border-t border-border pt-4">
+          <button @click=${() => this.applyStreamUpdate()}
+            class="w-fit px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground text-sm cursor-pointer transition-colors hover:border-border-strong">renderStream() an element-level update</button>
+          <ul id="ws-stream-log" class="grid gap-1.5 list-none m-0 p-0"></ul>
+        </div>
       </div>
     `;
   }

package/templates/gallery/modules/websockets/echo.test.ts

@@ -0,0 +1,21 @@
+// Example node test for booting the app in-process (from @webjsdev/server).
+// startServer({ appDir, port }) boots the whole app and resolves to
+// { server, close } (the same entry `webjs start` uses; port 0 picks a free
+// port, so a test never collides). Close it in a finally so the port is
+// released. This is the realistic way to smoke-test that the app boots and
+// listens; for asserting on responses without a socket, use the handle()
+// harness (see modules/server-actions/actions/greet.test.ts and the docs).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { startServer } from '@webjsdev/server';
+
+const appDir = process.cwd();
+
+test('startServer boots the app in-process on an ephemeral port', async () => {
+  const { server, close } = await startServer({ appDir, dev: true, port: 0 });
+  try {
+    assert.ok(server.address(), 'the server is listening');
+  } finally {
+    await close();
+  }
+});

package/templates/instrumentation.ts

@@ -0,0 +1,16 @@
+// Optional boot-time hook (app root, sibling of app/). register() runs once at
+// server start, the place to wire APM / logging / tracing. setOnError(fn) (from
+// @webjsdev/server) registers a sink for every request error the framework
+// catches (an SSR render crash, a thrown server action, a 500), so you can
+// forward it to Sentry / a logger with the request context. Call setOnError
+// INSIDE register() so it runs within the instrumentation context (a top-level
+// call has no context yet and is a no-op). Delete this file if you do not need
+// the hook.
+import { setOnError } from '@webjsdev/server';
+
+export function register() {
+  setOnError((error, ctx) => {
+    // Replace with your APM. `ctx` carries request context (e.g. a correlation id).
+    console.error('[instrumentation] request error:', error, ctx ?? '');
+  });
+}