@webjsdev/cli 0.10.30 → 0.10.32

package/templates/gallery/app/features/forms/page.ts

@@ -0,0 +1,78 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/forms route), then delete this marker line. webjs check fails while the marker remains.
+// forms: the no-JS write path. A real <form method="post"> posts to this page's
+// `action` export, and the framework re-renders the SAME page with the result on
+// `actionData`. WHY it matters: the form works with JS OFF (server round-trip),
+// and with JS the client router applies the response in place (no full reload).
+// Never reach for fetch() + a click handler where a <form> + page action does.
+// On failure the framework re-renders at 422 with the result; on success it
+// does a 303 Post-Redirect-Get, so we redirect to ?sent=1 to show a confirmation.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Forms (no-JS PE) | features' };
+
+interface Result {
+  success: boolean;
+  fieldErrors?: Record<string, string>;
+  values?: Record<string, string>;
+  redirect?: string;
+}
+
+const field = (label: string, name: string, input: unknown, error?: string) => html`
+  <div class="grid gap-1.5">
+    <label for=${name} class="text-[13px] font-medium text-muted-foreground">${label}</label>
+    ${input}
+    ${error ? html`<p class="m-0 text-[12.5px] text-destructive">${error}</p>` : ''}
+  </div>
+`;
+
+const inputCls = 'w-full bg-background border border-border rounded-xl px-3 py-2 text-[15px] text-foreground outline-none transition-colors focus:border-primary placeholder:text-muted-foreground/70';
+
+export default function FormsFeature({ searchParams, actionData }: { searchParams: Record<string, string | undefined>; actionData?: Result }) {
+  if (searchParams.sent) {
+    return html`
+      <h1 class="text-h2 font-bold mb-4">Forms</h1>
+      <div class="max-w-[460px] grid gap-3 p-6 rounded-2xl bg-card border border-border text-center">
+        <span class="mx-auto grid place-items-center w-12 h-12 rounded-2xl bg-primary/15 text-primary">
+          <svg viewBox="0 0 24 24" class="w-6 h-6 stroke-current fill-none" style="stroke-width:2.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
+        </span>
+        <p class="m-0 text-lg font-semibold text-foreground">Message sent</p>
+        <p class="m-0 text-sm text-muted-foreground">Thanks, we got it. <a class="text-primary" href="/features/forms">Send another</a>.</p>
+      </div>
+    `;
+  }
+  const errs = actionData?.fieldErrors ?? {};
+  const v = actionData?.values ?? {};
+  return html`
+    <h1 class="text-h2 font-bold mb-2">Forms</h1>
+    <p class="text-muted-foreground mb-5 max-w-[460px]">A real <code>&lt;form&gt;</code> posting to this page's <code>action</code>. It works with JS off; validation errors come back on <code>actionData</code>.</p>
+    <form method="post" action="" class="max-w-[460px] grid gap-4 p-5 rounded-2xl bg-card border border-border">
+      ${field('Name', 'name', html`<input id="name" name="name" value=${v.name ?? ''} class=${inputCls} placeholder="Ada Lovelace" />`, errs.name)}
+      ${field('Email', 'email', html`<input id="email" name="email" type="email" value=${v.email ?? ''} class=${inputCls} placeholder="ada@example.com" />`, errs.email)}
+      ${field('Message', 'message', html`<textarea id="message" name="message" rows="3" class=${inputCls} placeholder="Say hello...">${v.message ?? ''}</textarea>`, errs.message)}
+      <button type="submit" class="justify-self-start 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]">Send message</button>
+    </form>
+  `;
+}
+
+// The page action runs on a non-GET submission to this URL (the no-JS write
+// path). Validate, then return a failure (re-renders at 422 with fieldErrors +
+// values) or a success with a same-site `redirect` (a 303 PRG to the confirmation).
+//
+// FOOTGUN: to redirect on success, RETURN `{ success: true, redirect: '/path' }`
+// (a 303 See Other, so the browser follows with a GET). Do NOT THROW `redirect()`
+// from a page action, that is a 307 which PRESERVES the POST method and body, so
+// the browser re-POSTs to the target and re-runs the mutation (a duplicate write).
+// Throw `redirect()` only from a page render / GET context, never a page action.
+export async function action({ formData }: { formData: FormData }): Promise<Result> {
+  const name = String(formData.get('name') ?? '').trim();
+  const email = String(formData.get('email') ?? '').trim();
+  const message = String(formData.get('message') ?? '').trim();
+  const fieldErrors: Record<string, string> = {};
+  if (!name) fieldErrors.name = 'Your name is required.';
+  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) fieldErrors.email = 'A valid email is required.';
+  if (message.length < 5) fieldErrors.message = 'Message must be at least 5 characters.';
+  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors, values: { name, email, message } };
+  // A real app would persist / email here. We just confirm.
+  return { success: true, redirect: '/features/forms?sent=1' };
+}

package/templates/gallery/app/features/metadata/page.ts

@@ -0,0 +1,55 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/metadata route), then delete this marker line. webjs check fails while the marker remains.
+// Metadata: how a page declares its <title>, description, and Open Graph tags.
+// A static `metadata` export is read as-is. `generateMetadata(ctx)` takes
+// precedence and can read the request (params, searchParams, url) to compute
+// the tags, and may be async. Both run only on the server, so the tags are in
+// the first paint (no JS, crawler-friendly). Whole-page metadata ROUTES
+// (sitemap.ts, robots.ts, opengraph-image.ts, ...) live at the app root.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+// generateMetadata wins over a static `metadata` export when both exist. Here
+// it derives the title from a ?topic= query param to show the dynamic form;
+// with no param it falls back to a default. Change the URL to ?topic=webjs and
+// view source: the <title> follows.
+export function generateMetadata({
+  searchParams,
+}: {
+  searchParams: Record<string, string | undefined>;
+}): Metadata {
+  const topic = (searchParams.topic || '').trim();
+  return {
+    title: topic ? topic + ' | metadata' : 'Metadata (generateMetadata) | features',
+    description: 'How a webjs page declares title, description, and Open Graph tags.',
+    openGraph: { title: topic || 'Metadata', type: 'article' },
+  };
+}
+
+export default function MetadataExample({
+  searchParams,
+}: {
+  searchParams: Record<string, string | undefined>;
+}) {
+  const topic = (searchParams.topic || '').trim();
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Metadata</h1>
+    <p class="text-muted-foreground mb-4">
+      <code>generateMetadata(ctx)</code> runs on the server and can read the
+      request, so the <code>&lt;title&gt;</code> is computed per URL. View source
+      to see the tag this page produced.
+    </p>
+    <p class="mb-4">
+      Current title source:
+      <code class="font-mono text-sm">${topic ? '?topic=' + topic : '(default, no ?topic=)'}</code>
+    </p>
+    <ul class="list-disc pl-5 mb-4">
+      <li><a class="text-primary" href="/features/metadata?topic=webjs">?topic=webjs</a></li>
+      <li><a class="text-primary" href="/features/metadata?topic=Routing">?topic=Routing</a></li>
+      <li><a class="text-primary" href="/features/metadata">clear the param</a></li>
+    </ul>
+    <p class="text-muted-foreground text-sm">
+      Site-wide metadata (sitemap, robots, Open Graph images) lives in metadata
+      ROUTES at the app root, e.g. <code class="font-mono">app/sitemap.ts</code>.
+    </p>
+  `;
+}

package/templates/gallery/app/features/optimistic-ui/page.ts

@@ -0,0 +1,14 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/optimistic-ui route AND modules/optimistic-ui), then delete this marker line. webjs check fails while the marker remains.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/optimistic-ui/components/like-button.ts';
+
+export const metadata: Metadata = { title: 'Optimistic UI (imperative flip) | features' };
+
+export default function OptimisticUiFeature() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Optimistic UI</h1>
+    <p class="text-muted-foreground mb-4">The imperative <code>optimistic(signal, value, action)</code> form: the UI flips instantly and rolls back if the action fails. For the declarative list form (add / remove with rollback) in a full app, see <a class="text-primary" href="/examples/todo">/examples/todo</a>.</p>
+    <like-button></like-button>
+  `;
+}

package/templates/gallery/app/features/rate-limit/page.ts

@@ -0,0 +1,29 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/rate-limit route AND modules/rate-limit), then delete this marker line. webjs check fails while the marker remains.
+// Rate limiting: rateLimit() from '@webjsdev/server' is a middleware. It lives in
+// a middleware.ts scoped to the endpoint it protects (here app/features/
+// rate-limit/ping/middleware.ts, so it limits /features/rate-limit/ping WITHOUT
+// touching this page). It is backed by the pluggable cache store, in-memory by
+// default; point the store at Redis to share the window across instances.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/rate-limit/components/rate-probe.ts';
+
+export const metadata: Metadata = { title: 'Rate limiting (rateLimit middleware) | features' };
+
+export default function RateLimitExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Rate limiting</h1>
+    <p class="text-muted-foreground mb-4">
+      The <code class="font-mono">/ping</code> endpoint is limited to five
+      requests per ten seconds by a scoped <code class="font-mono">middleware.ts</code>.
+      Ping past the limit to get a <code class="font-mono">429</code> with a
+      <code class="font-mono">Retry-After</code> header.
+    </p>
+    <rate-probe></rate-probe>
+    <p class="text-muted-foreground text-sm mt-4">
+      With JavaScript off, hit
+      <a class="text-primary" href="/features/rate-limit/ping">/features/rate-limit/ping</a>
+      directly (refresh past five times in ten seconds).
+    </p>
+  `;
+}

package/templates/gallery/app/features/rate-limit/ping/middleware.ts

@@ -0,0 +1,8 @@
+// Per-segment middleware. It sits in the ping/ folder, so it applies ONLY to
+// /features/rate-limit/ping (its route.ts), not to the demo page one level up.
+// rateLimit() returns a standard webjs middleware: return a Response to
+// short-circuit (the 429), or call next() to continue. Keyed by client IP by
+// default; pass `key` to key by user id, API key, etc.
+import { rateLimit } from '@webjsdev/server';
+
+export default rateLimit({ window: '10s', max: 5, message: 'Slow down: five requests per ten seconds.' });

package/templates/gallery/app/features/rate-limit/ping/route.ts

@@ -0,0 +1,7 @@
+// The rate-limited endpoint. A plain GET route handler: it just reports success.
+// The rateLimit() middleware in this folder runs BEFORE it and stamps the
+// X-RateLimit-* headers onto the response (and returns a 429 once the window is
+// exhausted, so this handler never runs on a limited request).
+export function GET() {
+  return Response.json({ ok: true, at: new Date().toISOString() });
+}

package/templates/gallery/app/features/route-handler/data/route.ts

@@ -0,0 +1,8 @@
+// A route.ts is a server-only HTTP handler (named GET / POST / PUT / PATCH /
+// DELETE exports). It is NOT isomorphic and never ships to the client, the webjs
+// equivalent of a Next route handler. Each handler returns a Response (a plain
+// value auto-JSONs). A folder cannot have BOTH page.ts and route.ts, so this
+// endpoint lives one segment deeper, at /features/route-handler/data.
+export async function GET() {
+  return Response.json({ ok: true, at: new Date().toISOString() });
+}

package/templates/gallery/app/features/route-handler/page.ts

@@ -0,0 +1,13 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/route-handler route, including its data/route.ts handler), then delete this marker line. webjs check fails while the marker remains.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Route handlers (route.ts) | features' };
+
+export default function RouteHandlerExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Route handlers</h1>
+    <p class="text-muted-foreground mb-4">A <code>route.ts</code> is a server-only HTTP endpoint (named <code>GET</code>/<code>POST</code>/... exports), the webjs equivalent of a Next route handler. It never ships to the client.</p>
+    <p><a class="text-primary" href="/features/route-handler/data">GET /features/route-handler/data</a> returns JSON.</p>
+  `;
+}

package/templates/gallery/app/features/routing/[id]/page.ts

@@ -0,0 +1,25 @@
+// A dynamic route: `params.id` is the URL segment. The default export is a
+// (possibly async) function receiving { params, searchParams, url }; it runs
+// ONLY on the server. Throw notFound() / redirect() to short-circuit.
+//
+// Type-safe routes: instead of hand-typing `{ params: { id: string } }`, type
+// the props with PageProps<'<route>'>. `webjs types` (run automatically by
+// `webjs dev`) generates .webjs/routes.d.ts with a Route union and per-route
+// params, so PageProps<'/features/routing/[id]'>['params'] narrows to
+// { id: string } automatically. Rename the folder and the type follows; pass a
+// route literal that does not exist and it is a compile error.
+import { html } from '@webjsdev/core';
+import type { PageProps } from '@webjsdev/core';
+
+export default function RoutingParam({ params }: PageProps<'/features/routing/[id]'>) {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Route param</h1>
+    <p>The <code>[id]</code> segment is: <strong>${params.id}</strong></p>
+    <p class="text-muted-foreground text-sm mt-3">
+      Typed with <code class="font-mono">PageProps&lt;'/features/routing/[id]'&gt;</code>,
+      so <code class="font-mono">params.id</code> is a checked
+      <code class="font-mono">string</code> from the generated route union.
+    </p>
+    <p class="mt-3"><a class="text-primary" href="/features/routing">Back</a></p>
+  `;
+}

package/templates/gallery/app/features/routing/page.ts

@@ -0,0 +1,47 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/routing route), then delete this marker line. webjs check fails while the marker remains.
+// Routing basics: a static page that links to a dynamic route. app/ is routing
+// only; a folder maps to a URL segment, and [id] is a dynamic segment read from
+// `params`. See app/features/routing/[id]/page.ts.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Routing (dynamic params) | features' };
+
+export default function RoutingExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Routing</h1>
+    <p class="text-muted-foreground mb-4">A folder is a URL segment; a <code>[id]</code> folder is a dynamic param.</p>
+    <ul class="list-disc pl-5 mb-4">
+      <li><a class="text-primary" href="/features/routing/42">/features/routing/42</a></li>
+      <li><a class="text-primary" href="/features/routing/hello">/features/routing/hello</a></li>
+    </ul>
+    <p class="text-muted-foreground text-sm mb-2">
+      Routes are type-safe: <code class="font-mono">webjs types</code> (run by
+      <code class="font-mono">webjs dev</code>) generates a
+      <code class="font-mono">Route</code> union, and the
+      <code class="font-mono">[id]</code> page types its props with
+      <code class="font-mono">PageProps&lt;'/features/routing/[id]'&gt;</code>
+      so <code class="font-mono">params</code> is checked against the real routes.
+    </p>
+    <p class="text-muted-foreground text-sm mb-2">
+      Programmatic navigation is checked too:
+      <code class="font-mono">navigate(url)</code> takes that
+      <code class="font-mono">Route</code> union, so
+      <code class="font-mono">navigate('/random/42')</code> is a compile error in
+      your editor and <code class="font-mono">webjs typecheck</code>. (Plain
+      <code class="font-mono">&lt;a href&gt;</code> strings are not checked, so
+      prefer <code class="font-mono">navigate()</code> for internal links you want
+      verified.)
+    </p>
+    <p class="text-muted-foreground text-sm">
+      Changing route in code, two sides:
+      <code class="font-mono">navigate(url)</code> runs in the browser (a soft,
+      in-place client-router nav from an event handler, no reload), while
+      <code class="font-mono">redirect(url)</code> runs on the server (throw it in
+      a page or an <code class="font-mono">action</code> to bail before render and
+      return an HTTP 3xx). Throw
+      <code class="font-mono">redirect()</code> on the server, call
+      <code class="font-mono">navigate()</code> on the client.
+    </p>
+  `;
+}

package/templates/gallery/app/features/server-actions/page.ts

@@ -0,0 +1,14 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/server-actions route AND modules/server-actions), then delete this marker line. webjs check fails while the marker remains.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/server-actions/components/greeter.ts';
+
+export const metadata: Metadata = { title: 'Server actions (.server vs use server) | features' };
+
+export default function ServerActionsExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Server actions</h1>
+    <p class="text-muted-foreground mb-4">A 'use server' action is RPC-callable from the client; a plain .server.ts is a server-only utility you never import into a component.</p>
+    <server-greeter></server-greeter>
+  `;
+}

package/templates/gallery/app/features/service-worker/page.ts

@@ -0,0 +1,36 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/service-worker route), then delete this marker line. webjs check fails while the marker remains.
+// Service worker: opt-in progressive enhancement. webjs does NOT register one by
+// default (an active SW caches aggressively and would confuse dev). You opt in
+// by adding public/sw.js and registering it from a component's connectedCallback
+// (browser-only). This page is a guided reference, not an active registration,
+// so the scaffold stays predictable until you deliberately turn it on. See
+// agent-docs/service-worker.md for the full recipe.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Service worker (opt-in) | features' };
+
+export default function ServiceWorkerExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Service worker</h1>
+    <p class="text-muted-foreground mb-4">
+      Opt-in offline/caching enhancement. Nothing is registered until you add
+      <code class="font-mono">public/sw.js</code> and register it from a
+      browser-only lifecycle hook.
+    </p>
+    <p class="mb-2 text-sm font-medium">Register inside a component (never in a page or layout):</p>
+    <pre class="bg-card border border-border rounded-xl p-4 overflow-x-auto text-sm font-mono mb-4"><code>connectedCallback() {
+  super.connectedCallback();
+  if ('serviceWorker' in navigator) {
+    // The framework serves your public/sw.js at the site root /sw.js (with a
+    // Service-Worker-Allowed: / header), so the worker's scope is the whole origin.
+    navigator.serviceWorker.register('/sw.js');
+  }
+}</code></pre>
+    <p class="text-muted-foreground text-sm">
+      Registration lives in a component because it is browser-only work.
+      A page or layout never hydrates, so it is the wrong home for it. Full
+      recipe: <code class="font-mono">agent-docs/service-worker.md</code>.
+    </p>
+  `;
+}

package/templates/gallery/app/features/websockets/echo/route.ts

@@ -0,0 +1,19 @@
+// The WebSocket endpoint for the websockets feature demo. A route.ts is a
+// server-only HTTP file; exporting WS(ws, req, ctx) upgrades it to a WebSocket
+// endpoint. `ws` is a standard ws-library socket: listen with ws.on('message'),
+// reply with ws.send(). In dev the module is re-imported per connection, so keep
+// shared state on globalThis if you need it (this echo endpoint is stateless).
+
+// Structural type for the socket, so the demo needs no `@types/ws` dependency.
+type WSLike = {
+  on(event: 'message' | 'close', cb: (data: Buffer) => void): void;
+  send(msg: string): void;
+};
+
+export function WS(ws: WSLike) {
+  ws.on('message', (data) => {
+    // Echo the text back to just this client. For a fan-out to ALL connected
+    // clients, use broadcast() from '@webjsdev/server' (see the broadcast demo).
+    ws.send('echo: ' + data.toString());
+  });
+}

package/templates/gallery/app/features/websockets/page.ts

@@ -0,0 +1,25 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/websockets route AND modules/websockets), then delete this marker line. webjs check fails while the marker remains.
+// WebSockets: a route.ts exports WS(ws, req) for the server endpoint, and a
+// component uses connectWS() to talk to it. WebSockets are inherently JS-only
+// (there is no no-JS fallback for a live socket), so the component degrades to a
+// clear "requires JavaScript" note at SSR and enhances on hydration. The echo
+// endpoint lives at app/features/websockets/echo/route.ts (a sibling folder, so
+// it does not collide with this page).
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/websockets/components/ws-echo.ts';
+
+export const metadata: Metadata = { title: 'WebSockets (connectWS + WS) | features' };
+
+export default function WebSocketsExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">WebSockets</h1>
+    <p class="text-muted-foreground mb-4">
+      A <code class="font-mono">WS(ws, req)</code> export in
+      <code class="font-mono">route.ts</code> is the server endpoint;
+      <code class="font-mono">connectWS()</code> (auto-reconnect, JSON
+      encode/decode, queued sends) is the client. This echoes each message back.
+    </p>
+    <ws-echo></ws-echo>
+  `;
+}

package/templates/gallery/modules/async-render/components/server-clock.ts

@@ -0,0 +1,26 @@
+// async render() awaits server data directly in the leaf component. Three
+// decoupled concerns to know (see AGENTS.md "Async render"):
+//   1. SSR always BLOCKS, so the resolved data is in the first paint with no
+//      fallback markup (progressive-enhancement safe, readable with JS off).
+//   2. The client re-fetch default is stale-while-revalidate (old content stays
+//      until the new render resolves, no blank flash).
+//   3. renderFallback() is the OPTIONAL re-fetch loading UI, never first paint.
+// Reach for async render() when request-time SERVER data belongs in the first
+// paint; reach for a Task / signals for genuinely client-only data.
+import { WebComponent, html } from '@webjsdev/core';
+import { serverGreeting } from '../queries/server-greeting.server.ts';
+
+export class ServerClock extends WebComponent {
+  // A bare async-render component (no other client signal) is ELIDED, since its
+  // SSR'd HTML is already the complete output. `static refresh = true` opts into
+  // keeping the on-load re-fetch so the module ships (drop it for request-stable
+  // data you are happy to leave server-rendered).
+  static refresh = true;
+
+  async render() {
+    const info = await serverGreeting();
+    return html`<p class="font-mono text-sm">server rendered this at
+      <strong>${info.at}</strong> (pid ${info.pid})</p>`;
+  }
+}
+ServerClock.register('server-clock');

package/templates/gallery/modules/async-render/queries/server-greeting.server.ts

@@ -0,0 +1,9 @@
+'use server';
+// A GET 'use server' query a component awaits directly inside `async render()`.
+// It returns request-time SERVER data the client cannot know, which is exactly
+// what async render() is for (the resolved value lands in the first paint).
+export const method = 'GET';
+
+export async function serverGreeting(): Promise<{ at: string; pid: number }> {
+  return { at: new Date().toISOString(), pid: process.pid };
+}

package/templates/gallery/modules/broadcast/components/broadcast-feed.ts

@@ -0,0 +1,61 @@
+// A shared broadcast room. Same connectWS() client as the websockets demo, but
+// the server fans each message out to all connected sockets, so every open tab
+// shows the same feed. The socket opens in connectedCallback (browser-only) and
+// closes in disconnectedCallback. At SSR it renders the disconnected state, so
+// the page still reads with JS off (a live feed has no no-JS equivalent).
+import { WebComponent, signal, html, connectWS } from '@webjsdev/core';
+
+export class BroadcastFeed extends WebComponent {
+  private connected = signal(false);
+  private lines = signal<string[]>([]);
+  #conn: ReturnType<typeof connectWS> | null = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#conn = connectWS('/features/broadcast/feed', {
+      onOpen: () => this.connected.set(true),
+      onClose: () => this.connected.set(false),
+      onMessage: (msg: unknown) => this.lines.set([...this.lines.get(), String(msg)]),
+    });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#conn?.close();
+    this.#conn = null;
+  }
+
+  private send(e: SubmitEvent) {
+    e.preventDefault();
+    const form = e.target as HTMLFormElement;
+    const input = form.elements.namedItem('msg') as HTMLInputElement;
+    const text = input.value.trim();
+    if (!text) return;
+    this.#conn?.send(text);
+    input.value = '';
+  }
+
+  render() {
+    const on = this.connected.get();
+    return html`
+      <div class="grid gap-4 max-w-[420px]">
+        <div class="flex items-center gap-2 text-sm">
+          <span class="w-2 h-2 rounded-full ${on ? 'bg-primary' : 'bg-muted-foreground/40'}"></span>
+          <span class="text-muted-foreground">${on ? 'in the room' : 'connecting (the live room needs JavaScript)'}</span>
+        </div>
+        <form @submit=${(e: SubmitEvent) => this.send(e)} class="flex gap-2">
+          <input name="msg" autocomplete="off" placeholder="Message everyone"
+            class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
+          <button type="submit"
+            class="px-3.5 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]">Send</button>
+        </form>
+        <ul class="grid gap-1.5 list-none m-0 p-0">
+          ${this.lines.get().map((line) => html`
+            <li class="px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">${line}</li>
+          `)}
+        </ul>
+      </div>
+    `;
+  }
+}
+BroadcastFeed.register('broadcast-feed');

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

@@ -0,0 +1,36 @@
+// Co-located browser test for the <counter-card> component. This is the webjs
+// component-test SHAPE, so copy it for your own components:
+//   - It runs in REAL Chromium (webjs test --browser, or npx wtr), not jsdom. If
+//     the browser binary is missing, install it once: npx playwright install chromium.
+//   - The runner's mocha UI is `tdd`, so use suite() / test(), NOT describe / it().
+//   - There is NO assertion library in the importmap (no chai, no expect). Throw
+//     to fail. A tiny inline `assert` is plenty.
+//   - `ssrFixture` server-renders AND hydrates the component, so you exercise the
+//     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 { ssrFixture } from '@webjsdev/core/testing';
+import '../counter-card.ts';
+
+const assert = (cond, msg) => { if (!cond) throw new Error(msg || 'assertion failed'); };
+
+suite('<counter-card>', () => {
+  test('SSRs its initial state and the default label', async () => {
+    const el = await ssrFixture(html`<counter-card></counter-card>`);
+    assert(el.textContent.includes('0'), 'the count starts at 0');
+    assert(el.textContent.includes('Clicks'), 'the default label renders');
+  });
+
+  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');
+  });
+
+  test('increments on click (hydrated interactivity)', async () => {
+    const el = await ssrFixture(html`<counter-card></counter-card>`);
+    el.querySelector('button').click();
+    await el.updateComplete;
+    assert(el.textContent.includes('1'), 'the count becomes 1 after one click');
+  });
+});

package/templates/gallery/modules/components/components/counter-card.ts

@@ -0,0 +1,35 @@
+// Demonstrates the WebComponent essentials: the declare-free reactive-prop
+// factory, an instance signal for local state, a lifecycle hook, and a <slot>
+// for content projection (works in light DOM, the default). This is the core
+// component authoring shape. Styling is crafted Tailwind on the app's design
+// tokens so it stays visually coherent with the rest of the app.
+import { WebComponent, prop, signal, html } from '@webjsdev/core';
+
+export class CounterCard extends WebComponent({
+  // A reactive prop rides an HTML attribute / SSR hydration. Declared ONLY here
+  // (no `static properties`, no class-field `label = ''` which would clobber the
+  // accessor). Set defaults in the constructor.
+  label: prop(String),
+}) {
+  private count = signal(0); // instance signal: component-local state
+
+  constructor() {
+    super();
+    this.label = this.label || 'Clicks';
+  }
+
+  render() {
+    return html`
+      <div class="grid gap-4 p-5 rounded-2xl bg-card border border-border max-w-[320px]">
+        <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>
+        </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>
+      </div>
+    `;
+  }
+}
+CounterCard.register('counter-card');

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

@@ -0,0 +1,53 @@
+// 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.
+import { WebComponent, signal, html } from '@webjsdev/core';
+import { repeat, watch } from '@webjsdev/core/directives';
+
+interface Item { id: number; label: string }
+
+let nextId = 4;
+
+export class DirectiveDemo extends WebComponent {
+  private items = signal<Item[]>([
+    { id: 1, label: 'Alpha' },
+    { id: 2, label: 'Bravo' },
+    { id: 3, label: 'Charlie' },
+  ]);
+  private ticks = signal(0);
+
+  private reverse() {
+    this.items.set(this.items.get().slice().reverse());
+  }
+  private add() {
+    const id = nextId++;
+    this.items.set([...this.items.get(), { id, label: 'Item ' + id }]);
+  }
+
+  render() {
+    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>
+        <!-- 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>
+    `;
+  }
+}
+DirectiveDemo.register('directive-demo');