create-raredays-app 0.1.0

package/templates/full-stack/app/api/widgets/route.ts

@@ -0,0 +1,10 @@
+// Demo endpoint paired with `/demo/widgets`. Returns an empty list by
+// default so a fresh scaffold renders the Empty slot — flip MOCKS on
+// to see canned data via MSW. Replace this handler with a real query
+// once you have a backing store.
+
+import { NextResponse } from "next/server";
+
+export function GET(): NextResponse {
+  return NextResponse.json({ widgets: [], total: 0 });
+}

package/templates/full-stack/app/demo/widgets/page.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+// Demo of `defineAsyncLoad` + MSW.
+//
+// Without mocks (`pnpm dev`): /api/widgets returns an empty list, so the
+// Empty slot renders with a nudge toward `pnpm dev:mocks`. With mocks
+// on, MSW intercepts before the route fires and the Success slot
+// renders canned data.
+//
+// Delete this `/demo` subtree once you have your own pages.
+
+import { asyncSource, defineAsyncLoad } from "@raredays/core";
+
+interface Widget {
+  id: string;
+  name: string;
+  inventory: number;
+}
+
+interface WidgetsData {
+  widgets: Widget[];
+  total: number;
+}
+
+const Widgets = defineAsyncLoad<WidgetsData>({
+  source: asyncSource(async () => {
+    const r = await fetch("/api/widgets");
+    if (!r.ok) throw new Error(`/api/widgets responded ${r.status}`);
+    return (await r.json()) as WidgetsData;
+  }),
+  Loading: () => <p data-testid="widgets-state">Loading widgets…</p>,
+  Empty: ({ retry }) => (
+    <div data-testid="widgets-state">
+      <p>No widgets yet.</p>
+      <p className="mt-1 text-sm text-neutral-600">
+        Run <code>pnpm dev:mocks</code> to see canned data, or add real ones via the API route at{" "}
+        <code>app/api/widgets/route.ts</code>.
+      </p>
+      <button
+        type="button"
+        onClick={retry}
+        className="mt-3 rounded border border-neutral-300 px-3 py-1 text-sm"
+      >
+        Reload
+      </button>
+    </div>
+  ),
+  Success: ({ widgets, total }) => (
+    <ul data-testid="widgets-state" className="mt-2 space-y-1">
+      <li className="text-sm text-neutral-600" data-testid="widgets-total">
+        {total} widget{total === 1 ? "" : "s"}
+      </li>
+      {widgets.map((w) => (
+        <li key={w.id} data-testid="widget-row">
+          <span className="font-medium">{w.name}</span>
+          <span className="ml-2 text-sm text-neutral-600">({w.inventory} in stock)</span>
+        </li>
+      ))}
+    </ul>
+  ),
+  Failure: ({ error, retry }) => (
+    <div data-testid="widgets-state">
+      <p className="text-red-700">Failed to load widgets: {error.message}</p>
+      <button
+        type="button"
+        onClick={retry}
+        className="mt-3 rounded border border-neutral-300 px-3 py-1 text-sm"
+      >
+        Retry
+      </button>
+    </div>
+  ),
+});
+
+export default function WidgetsDemoPage(): React.ReactElement {
+  return (
+    <main className="mx-auto max-w-2xl p-8 font-sans">
+      <h1 className="text-2xl font-bold">Widgets demo</h1>
+      <p className="mt-2 text-sm text-neutral-600">
+        <code>defineAsyncLoad</code> against <code>/api/widgets</code>. MSW intercepts in dev when{" "}
+        <code>NEXT_PUBLIC_MOCKS=on</code>.
+      </p>
+      <Widgets />
+    </main>
+  );
+}

package/templates/full-stack/app/globals.css

@@ -0,0 +1,22 @@
+/* CSS @import lines must precede all other rules. If you add a remote-font
+ * import (e.g. @import url("https://rsms.me/inter/inter.css")), it MUST go
+ * BEFORE the lines below — @raredays/style inlines ~6800 lines of CSS,
+ * after which any further @import is mid-document and rejected by Lightning
+ * CSS / PostCSS / browsers per the CSS spec. */
+@import "@raredays/style";
+@import "./theme.override.css";
+
+/* Scan compiled output from @raredays/* packages so Tailwind emits
+ * the arbitrary utilities used inside their components (e.g. underline
+ * positions, data-attribute variants). The relative `@source` paths in
+ * @raredays/style/index.css don't resolve under pnpm's strict
+ * node_modules layout — each @raredays/* package gets its own
+ * .pnpm/<pkg>/node_modules/<pkg>/ directory, so style's
+ * `../components/dist` points nowhere. These directives are relative
+ * to THIS file (`app/globals.css`), which is the consumer's cwd —
+ * resolves correctly.
+ *
+ * Add `@source "../node_modules/@raredays/<pkg>/dist"` for any
+ * additional @raredays/* package whose component utilities you use. */
+@source "../node_modules/@raredays/components/dist";
+@source "../node_modules/@raredays/core/dist";

package/templates/full-stack/app/home-auth-controls.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+export function HomeAuthControls(): React.ReactElement {
+  return (
+    <div className="mt-6 flex flex-wrap gap-2">
+      <button
+        type="button"
+        onClick={async () => {
+          await fetch("/api/dev/login", { method: "POST" });
+          window.location.href = "/protected";
+        }}
+        className="rounded-md bg-brand-primary px-4 py-2 text-white hover:bg-brand-secondary"
+      >
+        Sign in as Alice → /protected
+      </button>
+      <button
+        type="button"
+        onClick={async () => {
+          await fetch("/api/dev/logout", { method: "POST" });
+          window.location.reload();
+        }}
+        className="rounded-md border border-neutral-300 px-4 py-2 hover:bg-neutral-50"
+      >
+        Sign out
+      </button>
+    </div>
+  );
+}

package/templates/full-stack/app/layout.tsx

@@ -0,0 +1,38 @@
+import { ThemeProvider, Toaster } from "@raredays/components";
+import { RaredaysProvider } from "@raredays/core";
+import type { Metadata, Viewport } from "next";
+import type { ReactNode } from "react";
+import { StartMocks } from "../mocks/browser";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "RareDays App",
+  description: "A RareDays Next.js application.",
+};
+
+export const viewport: Viewport = {
+  width: "device-width",
+  initialScale: 1,
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <StartMocks>
+          <RaredaysProvider>
+            <ThemeProvider
+              attribute="class"
+              defaultTheme="system"
+              enableSystem
+              disableTransitionOnChange
+            >
+              {children}
+              <Toaster position="bottom-center" />
+            </ThemeProvider>
+          </RaredaysProvider>
+        </StartMocks>
+      </body>
+    </html>
+  );
+}

package/templates/full-stack/app/lib/runtime.test.ts

@@ -0,0 +1,38 @@
+// @vitest-environment node
+// Runs in the Node environment (not happy-dom) because the WHATWG `Request`
+// in happy-dom strips the `cookie` header on construction (browsers forbid
+// setting it from script). Server-side identity tests need the real Node
+// `Request`, which preserves arbitrary headers.
+
+import { describe, expect, it } from "vitest";
+import { app, SEEDED } from "./runtime.js";
+
+// Sample test demonstrating how to test app code against the framework's
+// port contracts. The composition root provides the wired ports; tests
+// drive them directly. For deeper testing of your own custom adapters,
+// import the framework's conformance harnesses (e.g.
+// `identityProviderConformance` from `@raredays/identity/testing`) and
+// pass your factory.
+
+describe("identity flow (in-memory provider)", () => {
+  it("resolves the seeded session when the dev cookie is present", async () => {
+    const provider = app.require("identityProvider");
+    const req = new Request("https://example.com/", {
+      headers: { cookie: `rd-dev-session=${SEEDED.sessionId}` },
+    });
+    const session = await provider.getSession(req);
+    expect(session).not.toBeNull();
+    expect(session?.user.id).toBe(SEEDED.user.id);
+  });
+
+  it("returns null when no session cookie is present", async () => {
+    const provider = app.require("identityProvider");
+    const session = await provider.getSession(new Request("https://example.com/"));
+    expect(session).toBeNull();
+  });
+
+  it("seeded user has content.read but not content.manage", () => {
+    expect(SEEDED.user.hasPermission("content.read")).toBe(true);
+    expect(SEEDED.user.hasPermission("content.manage")).toBe(false);
+  });
+});

package/templates/full-stack/app/lib/runtime.ts

@@ -0,0 +1,54 @@
+// Composition root. Every port the framework knows wires here; routes and
+// helpers read ports from the resulting `RaredaysApp` instance.
+//
+// Default uses the in-memory IdentityProvider so `pnpm dev` runs out of the
+// box. To go to production:
+//   1. Install `@raredays/identity-better-auth`, configure Better Auth
+//      against your Drizzle database.
+//   2. Replace `createInMemoryProvider(...)` below with
+//      `createBetterAuthProvider({ auth })`.
+//   3. Mount Better Auth's handler at `app/api/auth/[...all]/route.ts`.
+
+import { createRaredaysApp, definePermissions, Session, User } from "@raredays/core";
+import { createInMemoryProvider } from "@raredays/identity/testing";
+// CRDA:imports
+
+// — Authorization (what each role can do) ─────────────────────────────────
+definePermissions({
+  rolePermissions: {
+    member: ["content.read"],
+    admin: ["content.read", "content.manage"],
+  },
+});
+
+// — Seeded dev user (replace with Better Auth in production) ──────────────
+const ALICE = User.from({
+  id: "u_alice",
+  email: "alice@example.com",
+  organizationId: "default",
+  roles: ["member"],
+  emailVerifiedAt: new Date("2026-01-01T00:00:00Z"),
+});
+
+const ALICE_SESSION = Session.from({
+  id: "s_alice",
+  userId: ALICE.id,
+  user: ALICE.toJSON(),
+  expiresAt: new Date(Date.now() + 1000 * 60 * 60 * 24),
+});
+
+const identityProvider = createInMemoryProvider({
+  users: [ALICE],
+  sessions: [ALICE_SESSION],
+});
+
+export const SEEDED = { user: ALICE, sessionId: ALICE_SESSION.id };
+
+// CRDA:config
+
+export const app = createRaredaysApp({
+  identityProvider,
+  // CRDA:ports
+});
+
+// CRDA:exports

package/templates/full-stack/app/protected/page.tsx

@@ -0,0 +1,31 @@
+import { redirect } from "next/navigation";
+import { UnauthenticatedError } from "@raredays/core";
+import { getServerSession } from "@raredays/identity/server";
+import { app } from "@/lib/runtime";
+
+export default async function ProtectedPage(): Promise<React.ReactElement> {
+  const session = await getServerSession(app);
+  if (!session) {
+    redirect("/");
+  }
+
+  try {
+    // Framework-owned authz: gate on a permission, not a role string.
+    session.user.requirePermission("content.read");
+  } catch (err) {
+    if (err instanceof UnauthenticatedError) redirect("/");
+    throw err;
+  }
+
+  return (
+    <main data-testid="protected" className="p-8 font-sans">
+      <h1 className="text-2xl font-bold">Protected</h1>
+      <p className="mt-3" data-testid="signed-in-as">
+        Signed in as {session.user.email}
+      </p>
+      <p className="mt-1 text-sm text-neutral-600" data-testid="user-id">
+        User id: {session.user.id}
+      </p>
+    </main>
+  );
+}

package/templates/full-stack/app/theme.override.css

@@ -0,0 +1,9 @@
+/*
+ * Auto-generated by @raredays/theme-build. Do not edit by hand.
+ * Source: site.spec.ts
+ * To regenerate: pnpm theme:build
+ */
+
+@theme {
+  /* No spec overrides — defaults from @raredays/tokens apply. */
+}

package/templates/full-stack/db/check.ts

@@ -0,0 +1,46 @@
+/**
+ * Validate that pending migrations apply cleanly without committing changes.
+ * Invoked by `pnpm db:check` — designed for CI pull-request gates.
+ *
+ * Strategy: redirect Drizzle's bookkeeping table to a scratch schema, run
+ * the migrations against it, then `DROP SCHEMA ... CASCADE`. The check
+ * verifies the migration SQL parses + the bookkeeping plumbing works. For
+ * full destructive-change preview (does the SQL still apply against the
+ * current production data?), run against an ephemeral clone separately.
+ *
+ * Uses PGlite when `DATABASE_URL` is unset so CI runners can validate
+ * migrations without provisioning Postgres.
+ */
+import { resolve } from "node:path";
+import { dryRun } from "@raredays/postgres/migrations";
+import * as appSchema from "./schema.js";
+
+const migrationsFolder = resolve(import.meta.dirname, "migrations");
+const databaseUrl = process.env.DATABASE_URL;
+
+async function main(): Promise<void> {
+  if (databaseUrl) {
+    const { createDb } = await import("@raredays/postgres-neon");
+    const { migrate } = await import("drizzle-orm/neon-http/migrator");
+    const db = createDb(databaseUrl, { schema: appSchema });
+    await dryRun({ db, migrate, migrationsFolder });
+    return;
+  }
+
+  console.warn(
+    "[db:check] DATABASE_URL is not set — validating against in-process PGlite.",
+  );
+  const { createPglite } = await import("@raredays/postgres-pglite");
+  const { migrate } = await import("drizzle-orm/pglite/migrator");
+  const handle = await createPglite({ schema: appSchema });
+  try {
+    await dryRun({ db: handle.db, migrate, migrationsFolder });
+  } finally {
+    await handle.close();
+  }
+}
+
+main().catch((err) => {
+  console.error("[db:check] failed:", err);
+  process.exit(1);
+});

package/templates/full-stack/db/index.ts

@@ -0,0 +1,109 @@
+// Database client — branches on environment.
+//
+// Production path: `@raredays/postgres-neon` (HTTP, edge-runtime
+// compatible). Set `DATABASE_URL` and the lazy Proxy below resolves to a
+// Neon client on first property access. To swap providers (Supabase /
+// RDS / self-hosted via `@raredays/postgres-js`, or any other
+// `@raredays/postgres-*` driver):
+//
+//   1. Edit `site.spec.ts` and set `deploy.database.provider` accordingly.
+//   2. `pnpm remove @raredays/postgres-neon && pnpm add @raredays/postgres-js`
+//   3. Replace the `@raredays/postgres-neon` static import below.
+//
+// Dev path (NODE_ENV !== "production" AND no DATABASE_URL): a fresh
+// in-process `@raredays/postgres-pglite` is booted eagerly so
+// Drizzle-backed providers (state-machine, engagement, audit, future
+// cms-drizzle) can register their tables at composition root without
+// provisioning Postgres. PGlite resets every time the dev server
+// restarts; set `DATABASE_URL` to opt into a persistent database in dev.
+//
+// Why eager in dev and lazy in prod? Drizzle providers materialize
+// tables at `registerMachine` / `registerTable` time — i.e. during
+// composition root eval. The dev runtime needs the db handle ready
+// before `createRaredaysApp` is called. The prod runtime can stay
+// lazy: the Neon client is cheap to construct, and lazy construction
+// means a build that never queries (e.g. SSG-only marketing routes)
+// doesn't require DATABASE_URL.
+import { createDb, type RaredaysDatabase as NeonDb } from "@raredays/postgres-neon";
+import { createPglite, type RaredaysDatabase as PgliteDb } from "@raredays/postgres-pglite";
+import * as appSchema from "./schema.js";
+
+export type Db = NeonDb<typeof appSchema> | PgliteDb<typeof appSchema>;
+
+const isProduction = process.env.NODE_ENV === "production";
+const hasDatabaseUrl = Boolean(process.env.DATABASE_URL);
+
+// Dev fallback: bootstrap PGlite eagerly so providers can register
+// tables at composition-root eval. In prod, or when DATABASE_URL is
+// set, leave this null and fall through to the lazy Proxy below.
+const eagerPglite: Db | null =
+  !isProduction && !hasDatabaseUrl ? await bootstrapPglite() : null;
+
+let cached: Db | undefined = eagerPglite ?? undefined;
+
+function buildNeon(): Db {
+  const connectionString = process.env.DATABASE_URL;
+  if (!connectionString) {
+    throw new Error(
+      "DATABASE_URL is not set. Provision a Postgres database (Neon, Supabase, etc.) and add it to the environment before running queries.",
+    );
+  }
+  return createDb(connectionString, { schema: appSchema }) as Db;
+}
+
+async function bootstrapPglite(): Promise<Db> {
+  const handle = await createPglite({ schema: appSchema });
+  // Minimal CREATE TABLE statements mirroring the schemas exported by
+  // `@raredays/postgres`. Kept tight on purpose — Drizzle-provider tests
+  // exercise the real conformance suite; this is purely so a fresh
+  // `pnpm dev` doesn't crash on first query against substrate tables. If
+  // you need the full migration set in dev, point DATABASE_URL at a
+  // local Postgres and run `pnpm db:migrate`.
+  const statements: readonly string[] = [
+    `CREATE TABLE IF NOT EXISTS audit_events (
+       id text PRIMARY KEY,
+       organization_id text NOT NULL,
+       actor_id text,
+       action text NOT NULL,
+       resource_type text NOT NULL,
+       resource_id text,
+       payload jsonb NOT NULL DEFAULT '{}'::jsonb,
+       created_at timestamptz NOT NULL DEFAULT now()
+     )`,
+    `CREATE TABLE IF NOT EXISTS webhook_deliveries (
+       id text PRIMARY KEY,
+       organization_id text NOT NULL,
+       endpoint text NOT NULL,
+       event_type text NOT NULL,
+       payload jsonb NOT NULL DEFAULT '{}'::jsonb,
+       status text NOT NULL DEFAULT 'pending',
+       attempts integer NOT NULL DEFAULT 0,
+       last_error text,
+       created_at timestamptz NOT NULL DEFAULT now(),
+       updated_at timestamptz NOT NULL DEFAULT now()
+     )`,
+    `CREATE TABLE IF NOT EXISTS job_executions (
+       id text PRIMARY KEY,
+       organization_id text NOT NULL,
+       job_name text NOT NULL,
+       status text NOT NULL DEFAULT 'pending',
+       payload jsonb NOT NULL DEFAULT '{}'::jsonb,
+       result jsonb,
+       error text,
+       scheduled_at timestamptz NOT NULL DEFAULT now(),
+       started_at timestamptz,
+       completed_at timestamptz
+     )`,
+  ];
+  for (const stmt of statements) {
+    await handle.client.query(stmt);
+  }
+  return handle.db as Db;
+}
+
+export const db: Db = new Proxy({} as Db, {
+  get(_target, prop) {
+    if (!cached) cached = buildNeon();
+    return Reflect.get(cached, prop);
+  },
+}) as Db;

package/templates/full-stack/db/migrate.ts

@@ -0,0 +1,66 @@
+/**
+ * Apply pending Drizzle migrations against the configured Postgres provider.
+ *
+ * Invoked by `pnpm db:migrate`. Branches on environment:
+ *
+ * - **Production / staging** (`DATABASE_URL` set, NODE_ENV=production): uses
+ *   `@raredays/postgres-neon` by default. Swap the import if you've migrated
+ *   to `@raredays/postgres-js`.
+ * - **Dev with persistent Postgres** (`DATABASE_URL` set, any NODE_ENV):
+ *   same path as production — connects to the URL.
+ * - **Dev fallback** (no `DATABASE_URL`): boots PGlite in-process so the
+ *   command always exits cleanly. PGlite is ephemeral, so migrations against
+ *   it only validate that the SQL parses; nothing is persisted.
+ *
+ * Wraps Drizzle's `migrate()` with `@raredays/postgres/migrations`'s
+ * `safeMigrate` to acquire an advisory lock (preventing concurrent
+ * migration runs) and emit structured logs.
+ *
+ * Exit codes: 0 on success, 1 on any failure.
+ */
+import { resolve } from "node:path";
+import { safeMigrate } from "@raredays/postgres/migrations";
+import * as appSchema from "./schema.js";
+
+const migrationsFolder = resolve(import.meta.dirname, "migrations");
+const appKey = process.env.npm_package_name ?? "raredays-app";
+const databaseUrl = process.env.DATABASE_URL;
+
+async function main(): Promise<void> {
+  if (databaseUrl) {
+    // Neon HTTP path. If you've swapped to @raredays/postgres-js, change
+    // both imports below to match.
+    const { createDb } = await import("@raredays/postgres-neon");
+    const { migrate } = await import("drizzle-orm/neon-http/migrator");
+    const db = createDb(databaseUrl, { schema: appSchema });
+    await safeMigrate({ db, migrate, migrationsFolder, appKey });
+    return;
+  }
+
+  // Dev fallback: PGlite in-process. Migrations apply against an ephemeral
+  // database so this command never fails for missing config.
+  console.warn(
+    "[db:migrate] DATABASE_URL is not set — falling back to in-process PGlite. " +
+      "Set DATABASE_URL to persist migrations.",
+  );
+  const { createPglite } = await import("@raredays/postgres-pglite");
+  const { migrate } = await import("drizzle-orm/pglite/migrator");
+  const handle = await createPglite({ schema: appSchema });
+  try {
+    await safeMigrate({
+      db: handle.db,
+      migrate,
+      migrationsFolder,
+      appKey,
+      // PGlite supports advisory locks but they're meaningless in-process.
+      useAdvisoryLock: false,
+    });
+  } finally {
+    await handle.close();
+  }
+}
+
+main().catch((err) => {
+  console.error("[db:migrate] failed:", err);
+  process.exit(1);
+});

package/templates/full-stack/db/schema.ts

@@ -0,0 +1,20 @@
+/**
+ * App-side schema barrel. Re-exports the framework's substrate tables and is
+ * the place to declare app-specific tables. The drizzle-kit config in
+ * `drizzle.config.ts` points at this file, so any table declared here gets
+ * generated into a migration when you run `pnpm db:generate`.
+ */
+export * from "@raredays/postgres/schema";
+
+// Declare app-specific tables here. Use the column helpers from
+// @raredays/postgres so every table stays multi-tenancy-ready. Example:
+//
+// import { pgTable, text, uuid } from "drizzle-orm/pg-core";
+// import { tenantColumns, timestampColumns } from "@raredays/postgres";
+//
+// export const widgets = pgTable("widgets", {
+//   id: uuid("id").primaryKey().defaultRandom(),
+//   ...tenantColumns(),
+//   ...timestampColumns(),
+//   name: text("name").notNull(),
+// });

package/templates/full-stack/drizzle.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "drizzle-kit";
+
+// `drizzle-kit generate` reads the schema only and does NOT need a
+// connection string; `drizzle-kit push` / `studio` / `migrate` do. We
+// therefore allow the URL to be absent at config eval time and let the
+// individual drizzle-kit commands surface their own clearer errors.
+const url = process.env.DATABASE_URL ?? "postgres://placeholder@localhost:5432/placeholder";
+
+export default defineConfig({
+  dialect: "postgresql",
+  schema: "./db/schema.ts",
+  out: "./db/migrations",
+  dbCredentials: { url },
+  strict: true,
+  verbose: true,
+});

package/templates/full-stack/instrumentation.ts

@@ -0,0 +1,10 @@
+// Next.js calls `register()` early in the server boot, before any route
+// handler runs. The Node-runtime guard avoids starting MSW in edge
+// runtimes where setupServer isn't compatible.
+
+export async function register(): Promise<void> {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+  if (process.env.MOCKS !== "on") return;
+  const { mockServer } = await import("./mocks/node");
+  mockServer.start();
+}

package/templates/full-stack/mocks/browser.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+// Browser-side mock worker. Wraps the app so that no in-page fetch fires
+// until the Service Worker has claimed the page — otherwise the very
+// first request races the SW registration and slips through unmocked.
+//
+// When `NEXT_PUBLIC_MOCKS` is unset (production), the wrapper renders
+// children synchronously with zero overhead. Requires
+// `public/mockServiceWorker.js` — shipped by the scaffold and pinned
+// to the same `msw` version as this template. Regenerate with
+// `npx msw init public/ --save` only if you bump the `msw` dep.
+
+import { useEffect, useState, type ReactNode } from "react";
+import { enableMockWorker } from "@raredays/mocks/browser";
+import { handlers } from "./handlers";
+
+const ENABLED = process.env.NEXT_PUBLIC_MOCKS === "on";
+const worker = ENABLED ? enableMockWorker(handlers) : null;
+
+export function StartMocks({ children }: { children: ReactNode }): ReactNode {
+  const [ready, setReady] = useState(!ENABLED);
+  useEffect(() => {
+    if (!worker) return;
+    void worker.start().then(() => setReady(true));
+    return () => worker.stop();
+  }, []);
+  return ready ? children : null;
+}

package/templates/full-stack/mocks/handlers.ts

@@ -0,0 +1,34 @@
+// Mock composition root. Imported by `mocks/node.ts`, `mocks/browser.tsx`,
+// and the vitest setup file — same handlers, three environments.
+//
+// To enable per-vendor canonical mocks, install the corresponding
+// `@raredays/*` packages (already in your deps if you selected the module)
+// and uncomment the relevant import + spread below.
+//
+// Per-app handlers go in the trailing array; later handlers win on equal
+// URL specificity, so app-specific overrides should come after vendor sets.
+
+import { defineMocks, type RequestHandler } from "@raredays/mocks";
+import { http, HttpResponse } from "msw";
+// CRDA:mocks-imports
+
+// Explicit annotation — TS2742 otherwise points at MSW's internal
+// HttpResponse-*.mjs path which isn't portable across consumer apps.
+export const handlers: RequestHandler[] = defineMocks(
+  // CRDA:mocks-spread
+  [
+    // App-local handlers — the demo at /demo/widgets calls /api/widgets,
+    // which by default returns []. With MOCKS on, MSW intercepts here and
+    // returns canned data so you can design UI against realistic responses.
+    http.get("/api/widgets", () =>
+      HttpResponse.json({
+        widgets: [
+          { id: "w_1", name: "Mock Widget A", inventory: 12 },
+          { id: "w_2", name: "Mock Widget B", inventory: 7 },
+          { id: "w_3", name: "Mock Widget C", inventory: 0 },
+        ],
+        total: 3,
+      }),
+    ),
+  ],
+);