@webjsdev/cli 0.10.35 → 0.10.37

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/counter-card.ts

@@ -24,7 +24,7 @@ export class CounterCard extends WebComponent({
         <slot></slot>
         <div class="flex items-baseline gap-2">
           <span class="text-[2.5rem] font-bold tabular-nums leading-none text-foreground">${this.count.get()}</span>
-          <span class="text-sm text-muted-foreground/70">${this.label}</span>
+          <span class="text-sm text-muted-foreground">${this.label}</span>
         </div>
         <button @click=${() => this.count.set(this.count.get() + 1)}
           class="w-fit px-4 py-2 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]">Increment</button>

package/templates/gallery/modules/components/components/reactive-meter.ts

@@ -0,0 +1,64 @@
+// A shadow-DOM component: `static shadow = true` scopes `static styles = css\`\``
+// to this element (bare selectors do not leak out), the one place the lit reflex
+// to scope CSS is right in webjs. It also shows the rest of the signals API:
+// `computed` (a derived signal), `effect` (a browser-side reaction that runs on
+// change), and `batch` (coalesce several writes into ONE re-render).
+import { WebComponent, html, css, signal, computed, effect, batch } from '@webjsdev/core';
+
+export class ReactiveMeter extends WebComponent {
+  static shadow = true;
+  static styles = css`
+    .row { display: flex; align-items: center; gap: 8px; }
+    button {
+      padding: 6px 12px; border-radius: 10px; border: 1px solid #8883;
+      background: transparent; color: inherit; cursor: pointer; font: inherit;
+    }
+    .val { font-variant-numeric: tabular-nums; font-weight: 600; }
+    .muted { opacity: 0.6; font-size: 13px; }
+  `;
+
+  private count = signal(0);
+  // computed: recomputed lazily when count changes, cached otherwise.
+  private doubled = computed(() => this.count.get() * 2);
+  private lastLogged = signal('');
+  private disposeEffect?: () => void;
+
+  connectedCallback() {
+    super.connectedCallback();
+    // effect: runs now and again whenever a signal it reads changes. Browser-only
+    // (SSR never calls connectedCallback), so it is the place for reactive
+    // side effects.
+    this.disposeEffect = effect(() => {
+      this.lastLogged.set('count is ' + this.count.get());
+    });
+  }
+  disconnectedCallback() {
+    super.disconnectedCallback?.();
+    this.disposeEffect?.();
+  }
+
+  private bump(n: number) {
+    this.count.set(this.count.get() + n);
+  }
+  // batch: both writes commit together, so the component re-renders ONCE.
+  private reset() {
+    batch(() => {
+      this.count.set(0);
+      this.lastLogged.set('reset');
+    });
+  }
+
+  render() {
+    return html`
+      <div class="row">
+        <button @click=${() => this.bump(-1)}>-1</button>
+        <span class="val">${this.count.get()}</span>
+        <button @click=${() => this.bump(1)}>+1</button>
+        <span class="muted">doubled: ${this.doubled.get()}</span>
+        <button @click=${() => this.reset()}>reset</button>
+      </div>
+      <p class="muted">${this.lastLogged.get()}</p>
+    `;
+  }
+}
+ReactiveMeter.register('reactive-meter');

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,10 +1,18 @@
-// 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
-// the signal changes, without re-running the whole template.
+// the signal changes, without re-running the whole template. The second card
+// 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). 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 } 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 }
 
@@ -17,6 +25,65 @@ export class DirectiveDemo extends WebComponent {
     { id: 3, label: 'Charlie' },
   ]);
   private ticks = signal(0);
+  // A controlled value (for `live`) and a key (for `keyed`).
+  private text = signal('type here');
+  private variant = signal(0);
+  // A handle to the input node, attached by `ref` in the browser.
+  private inputRef = createRef<HTMLInputElement>();
+  // 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());
@@ -25,27 +92,102 @@ export class DirectiveDemo extends WebComponent {
     const id = nextId++;
     this.items.set([...this.items.get(), { id, label: 'Item ' + id }]);
   }
+  private focusInput() {
+    this.inputRef.value?.focus();
+  }
+  // A promise that resolves after a tick, so `until` shows its fallback first.
+  private later(): Promise<string> {
+    return new Promise((resolve) => setTimeout(() => resolve('resolved!'), 400));
+  }
 
   render() {
+    const variant = this.variant.get();
     return html`
-      <div class="grid gap-4 max-w-[420px]">
-        <div class="flex gap-2">
-          <button @click=${() => this.reverse()}
-            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]">Reverse</button>
-          <button @click=${() => this.add()}
-            class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">Add</button>
+      <div class="grid gap-6 max-w-[420px]">
+        <div class="grid gap-4">
+          <div class="flex gap-2">
+            <button @click=${() => this.reverse()}
+              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]">Reverse</button>
+            <button @click=${() => this.add()}
+              class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">Add</button>
+          </div>
+          <!-- repeat keyed by item.id: reversing reuses the existing <li> nodes. -->
+          <ul class="grid gap-2 list-none m-0 p-0">
+            ${repeat(this.items.get(), (it: Item) => it.id, (it: Item) => html`
+              <li class="flex items-center gap-2 px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">
+                <span class="text-muted-foreground tabular-nums text-[13px]">#${it.id}</span>${it.label}
+              </li>
+            `)}
+          </ul>
+          <!-- watch(signal) swaps only this node when ticks changes. -->
+          <button @click=${() => this.ticks.set(this.ticks.get() + 1)}
+            class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">ticks: ${watch(this.ticks)}</button>
+        </div>
+
+        <div class="grid gap-3 border-t border-border pt-4">
+          <!-- live keeps the input's DOM value tracking the signal even after the
+               user edits it, so it stays a controlled input. ref hands you the
+               node via inputRef.value once it is attached in the browser. -->
+          <div class="flex gap-2">
+            <input
+              ${ref(this.inputRef)}
+              aria-label="Editable text for the ref focus demo"
+              class="flex-1 px-3 py-1.5 rounded-xl bg-card border border-border text-[15px] text-foreground"
+              .value=${live(this.text.get())}
+              @input=${(e: Event) => this.text.set((e.target as HTMLInputElement).value)}>
+            <button @click=${() => this.focusInput()}
+              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">Focus</button>
+          </div>
+          <!-- until shows the fallback until the promise resolves. -->
+          <p class="text-sm text-muted-foreground">async: ${until(this.asyncValue, 'loading...')}</p>
+          <!-- keyed discards and rebuilds this subtree when the key changes;
+               unsafeHTML injects trusted, author-written HTML (NEVER user input). -->
+          <button @click=${() => this.variant.set(variant + 1)}
+            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>
-        <!-- repeat keyed by item.id: reversing reuses the existing <li> nodes. -->
-        <ul class="grid gap-2 list-none m-0 p-0">
-          ${repeat(this.items.get(), (it: Item) => it.id, (it: Item) => html`
-            <li class="flex items-center gap-2 px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">
-              <span class="text-muted-foreground/70 tabular-nums text-[13px]">#${it.id}</span>${it.label}
-            </li>
-          `)}
-        </ul>
-        <!-- watch(signal) swaps only this node when ticks changes. -->
-        <button @click=${() => this.ticks.set(this.ticks.get() + 1)}
-          class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">ticks: ${watch(this.ticks)}</button>
       </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/rate-limit/components/rate-probe.ts

@@ -38,7 +38,7 @@ export class RateProbe extends WebComponent {
             <li class="flex items-center justify-between px-3 py-2 rounded-xl bg-card border border-border text-sm">
               <span class="text-muted-foreground">#${p.n}</span>
               <span class="font-mono ${p.status === 429 ? 'text-destructive' : 'text-primary'}">${p.status === 429 ? '429 limited' : '200 ok'}</span>
-              <span class="text-muted-foreground/70 text-[13px]">remaining: ${p.remaining}</span>
+              <span class="text-muted-foreground text-[13px]">remaining: ${p.remaining}</span>
             </li>
           `)}
         </ul>

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/server-actions/components/greeter.ts

@@ -18,7 +18,7 @@ export class Greeter extends WebComponent {
         <form @submit=${(e: SubmitEvent) => this.run(e)}
           class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-card border border-border">
           <input name="name" placeholder="your name" autocomplete="off"
-            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground/70 py-1.5" />
+            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground py-1.5" />
           <button type="submit"
             class="shrink-0 px-4 py-2 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]">Greet</button>
         </form>

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 };