techbro 0.0.0-stage → 0.5.0

package/templates/_default/apps/frontend/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.8.0",
+    "@fontsource-variable/geist": "^5.3.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.53.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-router": "^7.18.4",
+    "tailwind-merge": "^3.7.0",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@tailwindcss/vite": "^4.3.3",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
+    "@vitejs/plugin-react": "^6.1.1",
+    "eslint": "^10.12.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.7",
+    "globals": "^17.13.0",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.9.9",
+    "tailwindcss": "^4.3.3",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/templates/_default/apps/frontend/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="46" fill="none" viewBox="0 0 48 46"><path fill="#863bff" d="M25.946 44.938c-.664.845-2.021.375-2.021-.698V33.937a2.26 2.26 0 0 0-2.262-2.262H10.287c-.92 0-1.456-1.04-.92-1.788l7.48-10.471c1.07-1.497 0-3.578-1.842-3.578H1.237c-.92 0-1.456-1.04-.92-1.788L10.013.474c.214-.297.556-.474.92-.474h28.894c.92 0 1.456 1.04.92 1.788l-7.48 10.471c-1.07 1.498 0 3.579 1.842 3.579h11.377c.943 0 1.473 1.088.89 1.83L25.947 44.94z" style="fill:#863bff;fill:color(display-p3 .5252 .23 1);fill-opacity:1"/><mask id="a" width="48" height="46" x="0" y="0" maskUnits="userSpaceOnUse" style="mask-type:alpha"><path fill="#000" d="M25.842 44.938c-.664.844-2.021.375-2.021-.698V33.937a2.26 2.26 0 0 0-2.262-2.262H10.183c-.92 0-1.456-1.04-.92-1.788l7.48-10.471c1.07-1.498 0-3.579-1.842-3.579H1.133c-.92 0-1.456-1.04-.92-1.787L9.91.473c.214-.297.556-.474.92-.474h28.894c.92 0 1.456 1.04.92 1.788l-7.48 10.471c-1.07 1.498 0 3.578 1.842 3.578h11.377c.943 0 1.473 1.088.89 1.832L25.843 44.94z" style="fill:#000;fill-opacity:1"/></mask><g mask="url(#a)"><g filter="url(#b)"><ellipse cx="5.508" cy="14.704" fill="#ede6ff" rx="5.508" ry="14.704" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -4.47 31.516)"/></g><g filter="url(#c)"><ellipse cx="10.399" cy="29.851" fill="#ede6ff" rx="10.399" ry="29.851" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -39.328 7.883)"/></g><g filter="url(#d)"><ellipse cx="5.508" cy="30.487" fill="#7e14ff" rx="5.508" ry="30.487" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.814 -25.913 -14.639)scale(1 -1)"/></g><g filter="url(#e)"><ellipse cx="5.508" cy="30.599" fill="#7e14ff" rx="5.508" ry="30.599" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.814 -32.644 -3.334)scale(1 -1)"/></g><g filter="url(#f)"><ellipse cx="5.508" cy="30.599" fill="#7e14ff" rx="5.508" ry="30.599" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -34.34 30.47)"/></g><g filter="url(#g)"><ellipse cx="14.072" cy="22.078" fill="#ede6ff" rx="14.072" ry="22.078" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="rotate(93.35 24.506 48.493)scale(-1 1)"/></g><g filter="url(#h)"><ellipse cx="3.47" cy="21.501" fill="#7e14ff" rx="3.47" ry="21.501" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.009 28.708 47.59)scale(-1 1)"/></g><g filter="url(#i)"><ellipse cx="3.47" cy="21.501" fill="#7e14ff" rx="3.47" ry="21.501" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.009 28.708 47.59)scale(-1 1)"/></g><g filter="url(#j)"><ellipse cx=".387" cy="8.972" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(39.51 .387 8.972)"/></g><g filter="url(#k)"><ellipse cx="47.523" cy="-6.092" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 47.523 -6.092)"/></g><g filter="url(#l)"><ellipse cx="41.412" cy="6.333" fill="#47bfff" rx="5.971" ry="9.665" style="fill:#47bfff;fill:color(display-p3 .2799 .748 1);fill-opacity:1" transform="rotate(37.892 41.412 6.333)"/></g><g filter="url(#m)"><ellipse cx="-1.879" cy="38.332" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 -1.88 38.332)"/></g><g filter="url(#n)"><ellipse cx="-1.879" cy="38.332" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 -1.88 38.332)"/></g><g filter="url(#o)"><ellipse cx="35.651" cy="29.907" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 35.651 29.907)"/></g><g filter="url(#p)"><ellipse cx="38.418" cy="32.4" fill="#47bfff" rx="5.971" ry="15.297" style="fill:#47bfff;fill:color(display-p3 .2799 .748 1);fill-opacity:1" transform="rotate(37.892 38.418 32.4)"/></g></g><defs><filter id="b" width="60.045" height="41.654" x="-19.77" y="16.149" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="c" width="90.34" height="51.437" x="-54.613" y="-7.533" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="d" width="79.355" height="29.4" x="-49.64" y="2.03" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="e" width="79.579" height="29.4" x="-45.045" y="20.029" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="f" width="79.579" height="29.4" x="-43.513" y="21.178" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="g" width="74.749" height="58.852" x="15.756" y="-17.901" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="h" width="61.377" height="25.362" x="23.548" y="2.284" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="i" width="61.377" height="25.362" x="23.548" y="2.284" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="j" width="56.045" height="63.649" x="-27.636" y="-22.853" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="k" width="54.814" height="64.646" x="20.116" y="-38.415" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="l" width="33.541" height="35.313" x="24.641" y="-11.323" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="m" width="54.814" height="64.646" x="-29.286" y="6.009" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="n" width="54.814" height="64.646" x="-29.286" y="6.009" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="o" width="54.814" height="64.646" x="8.244" y="-2.416" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="p" width="39.409" height="43.623" x="18.713" y="10.588" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter></defs></svg>

package/templates/_default/apps/frontend/src/App.jsx

@@ -0,0 +1,11 @@
+import { Outlet } from "react-router";
+import Layout from "@/components/Layout";
+import { appName } from "@/lib/config";
+
+export default function App() {
+  return (
+    <Layout appName={appName}>
+      <Outlet />
+    </Layout>
+  );
+}

package/templates/_default/apps/frontend/src/App.test.jsx

@@ -0,0 +1,40 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { createMemoryRouter, RouterProvider } from "react-router";
+import { routes } from "./routes";
+
+function renderAt(path) {
+  render(<RouterProvider router={createMemoryRouter(routes, { initialEntries: [path] })} />);
+}
+
+beforeEach(() => {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn((url) =>
+      Promise.resolve(
+        new Response(JSON.stringify(url.startsWith("/api") ? { items: [] } : { status: "ok" })),
+      ),
+    ),
+  );
+});
+afterEach(() => vi.unstubAllGlobals());
+
+describe("routing", () => {
+  it("starts on the welcome page", async () => {
+    renderAt("/");
+    expect(screen.getByRole("heading", { name: "Project Template" })).toBeInTheDocument();
+    expect(await screen.findAllByText("OK")).toHaveLength(2);
+  });
+
+  it("navigates to items via the nav link", async () => {
+    renderAt("/");
+    await userEvent.click(screen.getByRole("link", { name: "Items" }));
+    expect(await screen.findByLabelText("Item name")).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Items" })).toHaveAttribute("aria-current", "page");
+  });
+
+  it("renders items directly at /items", async () => {
+    renderAt("/items");
+    expect(await screen.findByLabelText("Item name")).toBeInTheDocument();
+  });
+});

package/templates/_default/apps/frontend/src/api/client.js

@@ -0,0 +1,50 @@
+/** Error thrown for non-2xx responses; carries the backend error shape. */
+export class ApiError extends Error {
+  /**
+   * @param {number} status HTTP status code
+   * @param {{error?: {code?: string, message?: string, details?: unknown[]}, requestId?: string} | null} body
+   * @param {string | null} [traceId] Correlation ID from the response header
+   */
+  constructor(status, body, traceId = null) {
+    super(body?.error?.message ?? `Request failed with status ${status}`);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = body?.error?.code ?? "UNKNOWN_ERROR";
+    this.details = body?.error?.details ?? [];
+    this.requestId = body?.requestId ?? null;
+    this.traceId = traceId;
+  }
+}
+
+const baseUrl = import.meta.env.VITE_API_BASE_URL ?? "";
+
+/**
+ * Fetch JSON from the backend, generating a per-request trace UUID unless supplied.
+ * @param {string} path Path beginning with "/"
+ * @param {RequestInit & {json?: unknown}} [options]
+ * @returns {Promise<any>} Parsed JSON body, or null for empty responses
+ * @throws {ApiError}
+ */
+export async function apiFetch(path, options = {}) {
+  const { json, headers, ...rest } = options;
+  const requestHeaders = new Headers(headers);
+  if (!requestHeaders.has("Accept")) requestHeaders.set("Accept", "application/json");
+  if (!requestHeaders.has("x-trace-id")) requestHeaders.set("x-trace-id", crypto.randomUUID());
+  const init = { ...rest, headers: requestHeaders };
+  if (json !== undefined) {
+    init.body = JSON.stringify(json);
+    init.headers.set("Content-Type", "application/json");
+  }
+  const response = await fetch(`${baseUrl}${path}`, init);
+  const text = await response.text();
+  let body = null;
+  if (text) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = null;
+    }
+  }
+  if (!response.ok) throw new ApiError(response.status, body, response.headers.get("x-trace-id"));
+  return body;
+}

package/templates/_default/apps/frontend/src/api/client.test.js

@@ -0,0 +1,70 @@
+import { ApiError, apiFetch } from "./client";
+
+afterEach(() => vi.unstubAllGlobals());
+
+function mockFetch(status, body) {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn().mockResolvedValue({
+      ok: status >= 200 && status < 300,
+      status,
+      headers: new Headers({ "x-trace-id": "response-trace" }),
+      text: () => Promise.resolve(body === undefined ? "" : JSON.stringify(body)),
+    }),
+  );
+}
+
+describe("apiFetch", () => {
+  it("generates a separate UUID for each request", async () => {
+    mockFetch(200, {});
+    await apiFetch("/health");
+    await apiFetch("/health");
+    const ids = fetch.mock.calls.map(([, init]) => new Headers(init.headers).get("x-trace-id"));
+    expect(ids[0]).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+    expect(ids[1]).not.toBe(ids[0]);
+  });
+  it.each([
+    { "X-Trace-Id": "caller-trace", Authorization: "Bearer test" },
+    {
+      headers: [
+        ["X-Trace-Id", "caller-trace"],
+        ["Authorization", "Bearer test"],
+      ],
+    },
+    new Headers({ "X-Trace-Id": "caller-trace", Authorization: "Bearer test" }),
+  ])("preserves caller headers in all supported forms", async (form) => {
+    const headers = form.headers ?? form;
+    mockFetch(200, {});
+    await apiFetch("/api/v1/items", { headers, method: "POST", json: { name: "test" } });
+    const init = fetch.mock.calls[0][1];
+    const sent = new Headers(init.headers);
+    expect(sent.get("x-trace-id")).toBe("caller-trace");
+    expect(sent.get("authorization")).toBe("Bearer test");
+    expect(sent.get("accept")).toBe("application/json");
+    expect(sent.get("content-type")).toBe("application/json");
+    expect(init.body).toBe('{"name":"test"}');
+  });
+  it("returns parsed JSON on success", async () => {
+    mockFetch(200, { items: [] });
+    await expect(apiFetch("/api/v1/items")).resolves.toEqual({ items: [] });
+  });
+  it("throws ApiError with the backend error shape", async () => {
+    mockFetch(400, {
+      error: { code: "VALIDATION_ERROR", message: "Invalid input", details: ["name"] },
+      requestId: "req-1",
+    });
+    const err = await apiFetch("/api/v1/items").catch((e) => e);
+    expect(err).toBeInstanceOf(ApiError);
+    expect(err.status).toBe(400);
+    expect(err.code).toBe("VALIDATION_ERROR");
+    expect(err.message).toBe("Invalid input");
+    expect(err.details).toEqual(["name"]);
+    expect(err.requestId).toBe("req-1");
+    expect(err.traceId).toBe("response-trace");
+  });
+  it("falls back when the error body is not JSON-shaped", async () => {
+    mockFetch(500);
+    const err = await apiFetch("/x").catch((e) => e);
+    expect(err.code).toBe("UNKNOWN_ERROR");
+  });
+});

package/templates/_default/apps/frontend/src/api/items.js

@@ -0,0 +1,26 @@
+import { apiFetch } from "./client";
+
+/**
+ * @param {{page?: number, perPage?: number}} [params]
+ * @returns {Promise<{items: Array<{id: string, name: string, createdAt: string}>, pagination: object}>}
+ */
+export function listItems({ page = 1, perPage = 20 } = {}) {
+  const query = new URLSearchParams({ page: String(page), perPage: String(perPage) });
+  return apiFetch(`/api/v1/items?${query}`);
+}
+
+/**
+ * @param {{name: string}} input
+ * @returns {Promise<{id: string, name: string, createdAt: string}>}
+ */
+export function createItem({ name }) {
+  return apiFetch("/api/v1/items", { method: "POST", json: { name } });
+}
+
+/**
+ * @param {string} id
+ * @returns {Promise<{id: string, name: string, createdAt: string}>}
+ */
+export function getItem(id) {
+  return apiFetch(`/api/v1/items/${encodeURIComponent(id)}`);
+}

package/templates/_default/apps/frontend/src/api/system.js

@@ -0,0 +1,11 @@
+import { apiFetch } from "./client";
+
+/** @returns {Promise<object>} Liveness response from `GET /health`. */
+export function getHealth() {
+  return apiFetch("/health");
+}
+
+/** @returns {Promise<object>} Readiness response from `GET /ready` (includes database check). */
+export function getReady() {
+  return apiFetch("/ready");
+}

package/templates/_default/apps/frontend/src/components/ItemList.jsx

@@ -0,0 +1,20 @@
+import { formatCreatedAt } from "@/models/items";
+
+/** @param {{items: Array<{id: string, name: string, createdAt: string}>}} props */
+export default function ItemList({ items }) {
+  if (items.length === 0) {
+    return <p className="text-sm text-muted-foreground">No items yet.</p>;
+  }
+  return (
+    <ul className="divide-y">
+      {items.map((item) => (
+        <li key={item.id} className="flex items-center justify-between py-2 text-sm">
+          <span>{item.name}</span>
+          <time className="text-muted-foreground" dateTime={item.createdAt}>
+            {formatCreatedAt(item.createdAt)}
+          </time>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/templates/_default/apps/frontend/src/components/ItemList.test.jsx

@@ -0,0 +1,18 @@
+import { render, screen } from "@testing-library/react";
+import ItemList from "./ItemList";
+
+describe("ItemList", () => {
+  it("renders item names", () => {
+    const items = [
+      { id: "1", name: "Alpha", createdAt: "2026-10-08T12:00:00Z" },
+      { id: "2", name: "Beta", createdAt: "2026-10-08T13:00:00Z" },
+    ];
+    render(<ItemList items={items} />);
+    expect(screen.getByText("Alpha")).toBeInTheDocument();
+    expect(screen.getByText("Beta")).toBeInTheDocument();
+  });
+  it("renders an empty state", () => {
+    render(<ItemList items={[]} />);
+    expect(screen.getByText("No items yet.")).toBeInTheDocument();
+  });
+});

package/templates/_default/apps/frontend/src/components/Layout.jsx

@@ -0,0 +1,35 @@
+import { NavLink } from "react-router";
+import { buttonVariants } from "@/components/ui/button";
+
+const NAV = [
+  { to: "/", label: "Welcome", end: true },
+  { to: "/items", label: "Items", end: false },
+];
+
+/** @param {{appName: string, children: import("react").ReactNode}} props */
+export default function Layout({ appName, children }) {
+  return (
+    <div className="min-h-svh">
+      <header className="border-b">
+        <div className="mx-auto flex max-w-3xl items-center justify-between p-4">
+          <span className="font-semibold">{appName}</span>
+          <nav aria-label="Main" className="flex gap-1">
+            {NAV.map((entry) => (
+              <NavLink
+                key={entry.to}
+                to={entry.to}
+                end={entry.end}
+                className={({ isActive }) =>
+                  buttonVariants({ variant: isActive ? "secondary" : "ghost" })
+                }
+              >
+                {entry.label}
+              </NavLink>
+            ))}
+          </nav>
+        </div>
+      </header>
+      <main className="mx-auto max-w-3xl p-6">{children}</main>
+    </div>
+  );
+}

package/templates/_default/apps/frontend/src/components/StatusBadge.jsx

@@ -0,0 +1,22 @@
+import { cn } from "@/lib/utils";
+
+const STYLES = {
+  ok: "bg-green-100 text-green-800 dark:bg-green-950 dark:text-green-300",
+  error: "bg-red-100 text-red-800 dark:bg-red-950 dark:text-red-300",
+  pending: "bg-muted text-muted-foreground",
+};
+const LABELS = { ok: "OK", error: "Failed", pending: "Checking..." };
+
+/** @param {{state: "ok" | "error" | "pending"}} props */
+export default function StatusBadge({ state }) {
+  return (
+    <span
+      className={cn(
+        "inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium",
+        STYLES[state],
+      )}
+    >
+      {LABELS[state]}
+    </span>
+  );
+}

package/templates/_default/apps/frontend/src/components/StepList.jsx

@@ -0,0 +1,19 @@
+/** @param {{steps: Array<{label: string, path: string, description: string}>}} props */
+export default function StepList({ steps }) {
+  return (
+    <ol className="space-y-4">
+      {steps.map((step, index) => (
+        <li key={step.label} className="flex gap-3">
+          <span className="flex size-6 shrink-0 items-center justify-center rounded-full bg-muted text-xs font-medium">
+            {index + 1}
+          </span>
+          <div className="min-w-0 space-y-1">
+            <p className="text-sm font-medium">{step.label}</p>
+            <code className="block text-xs break-words text-muted-foreground">{step.path}</code>
+            <p className="text-sm text-muted-foreground">{step.description}</p>
+          </div>
+        </li>
+      ))}
+    </ol>
+  );
+}

package/templates/_default/apps/frontend/src/components/ui/button.jsx

@@ -0,0 +1,52 @@
+import { Button as ButtonPrimitive } from "@base-ui/react/button";
+import { cva } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "group/button inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/80",
+        outline:
+          "border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-[color-mix(in_oklch,var(--secondary),var(--foreground)_5%)] aria-expanded:bg-secondary aria-expanded:text-secondary-foreground",
+        ghost:
+          "hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50",
+        destructive:
+          "bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default:
+          "h-8 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        xs: "h-6 gap-1 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
+        sm: "h-7 gap-1 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+        lg: "h-9 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        icon: "size-8",
+        "icon-xs":
+          "size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
+        "icon-sm":
+          "size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg",
+        "icon-lg": "size-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+function Button({ className, variant = "default", size = "default", ...props }) {
+  return (
+    <ButtonPrimitive
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  );
+}
+
+export { Button, buttonVariants };

package/templates/_default/apps/frontend/src/components/ui/card.jsx

@@ -0,0 +1,83 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+function Card({ className, size = "default", ...props }) {
+  return (
+    <div
+      data-slot="card"
+      data-size={size}
+      className={cn(
+        "group/card flex flex-col gap-(--card-spacing) overflow-hidden rounded-xl bg-card py-(--card-spacing) text-sm text-card-foreground ring-1 ring-foreground/10 [--card-spacing:--spacing(4)] has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:[--card-spacing:--spacing(3)] data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CardHeader({ className, ...props }) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-(--card-spacing) has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-(--card-spacing)",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CardTitle({ className, ...props }) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn(
+        "font-heading text-base leading-snug font-medium group-data-[size=sm]/card:text-sm",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CardDescription({ className, ...props }) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+function CardAction({ className, ...props }) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn("col-start-2 row-span-2 row-start-1 self-start justify-self-end", className)}
+      {...props}
+    />
+  );
+}
+
+function CardContent({ className, ...props }) {
+  return (
+    <div data-slot="card-content" className={cn("px-(--card-spacing)", className)} {...props} />
+  );
+}
+
+function CardFooter({ className, ...props }) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn(
+        "flex items-center rounded-b-xl border-t bg-muted/50 p-(--card-spacing)",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Card, CardHeader, CardFooter, CardTitle, CardAction, CardDescription, CardContent };

package/templates/_default/apps/frontend/src/components/ui/input.jsx

@@ -0,0 +1,19 @@
+import * as React from "react";
+import { Input as InputPrimitive } from "@base-ui/react/input";
+import { cn } from "@/lib/utils";
+
+function Input({ className, type, ...props }) {
+  return (
+    <InputPrimitive
+      type={type}
+      data-slot="input"
+      className={cn(
+        "h-8 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 text-base transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Input };

package/templates/_default/apps/frontend/src/hooks/useBackendStatus.js

@@ -0,0 +1,33 @@
+import { useEffect, useState } from "react";
+import { getHealth, getReady } from "@/api/system";
+
+const PENDING = { state: "pending", body: null, message: null };
+
+function toResult(settled) {
+  if (settled.status === "fulfilled") {
+    return { state: "ok", body: settled.value, message: null };
+  }
+  return { state: "error", body: null, message: settled.reason?.message ?? "Request failed" };
+}
+
+/**
+ * Checks `/health` and `/ready` once on mount.
+ * @returns {{health: StatusResult, ready: StatusResult, unreachable: boolean}}
+ *   where StatusResult is `{state: "pending" | "ok" | "error", body: object | null, message: string | null}`.
+ */
+export function useBackendStatus() {
+  const [status, setStatus] = useState({ health: PENDING, ready: PENDING });
+
+  useEffect(() => {
+    let active = true;
+    Promise.allSettled([getHealth(), getReady()]).then(([health, ready]) => {
+      if (active) setStatus({ health: toResult(health), ready: toResult(ready) });
+    });
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  const unreachable = status.health.state === "error" || status.ready.state === "error";
+  return { ...status, unreachable };
+}

package/templates/_default/apps/frontend/src/hooks/useItems.js

@@ -0,0 +1,47 @@
+import { useCallback, useEffect, useState } from "react";
+import { createItem, listItems } from "@/api/items";
+import { validateItemName } from "@/models/items";
+
+/** Coordinates loading and creating items with loading/error state. */
+export function useItems() {
+  const [items, setItems] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await listItems();
+      setItems(data.items);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    load();
+  }, [load]);
+
+  const create = useCallback(async (name) => {
+    const check = validateItemName(name);
+    if (!check.ok) {
+      setError(check.message);
+      return false;
+    }
+    setError(null);
+    try {
+      const created = await createItem({ name: name.trim() });
+      setItems((current) => [created, ...current]);
+      return true;
+    } catch (err) {
+      setError(err.message);
+      return false;
+    }
+  }, []);
+
+  return { items, loading, error, create, reload: load };
+}