@01.software/init 0.9.2 → 0.10.1

package/dist/create-app-templates/ecommerce/CHANGELOG.md

@@ -0,0 +1,48 @@
+# ecommerce
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [81ef105]
+- Updated dependencies [9789528]
+- Updated dependencies [9b7afab]
+- Updated dependencies [db8bd4b]
+- Updated dependencies [b95f6ac]
+- Updated dependencies [c60ec7f]
+- Updated dependencies [6c71a71]
+- Updated dependencies [3aa6239]
+- Updated dependencies [5d7b26f]
+- Updated dependencies [294b7d1]
+- Updated dependencies [f87fe09]
+- Updated dependencies [4362b14]
+  - @01.software/sdk@0.43.0
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [b011902]
+- Updated dependencies [9d1b632]
+- Updated dependencies [d28ad57]
+- Updated dependencies [9cb8a41]
+- Updated dependencies [a36d724]
+- Updated dependencies [426c3ed]
+- Updated dependencies [9261a15]
+- Updated dependencies [8d8e700]
+- Updated dependencies [9f3186c]
+- Updated dependencies [a2fd60b]
+- Updated dependencies [b1bdd49]
+- Updated dependencies [e3b16a5]
+- Updated dependencies [27a6502]
+- Updated dependencies [5aa136f]
+- Updated dependencies [87da012]
+- Updated dependencies [3f261a6]
+- Updated dependencies [17afb8e]
+- Updated dependencies [a968dfd]
+- Updated dependencies [4a13b7b]
+- Updated dependencies [1d8ee45]
+- Updated dependencies [923b0a2]
+- Updated dependencies [2986732]
+- Updated dependencies [8ded73e]
+  - @01.software/sdk@0.42.0

package/dist/create-app-templates/ecommerce/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/dist/create-app-templates/ecommerce/README.md

@@ -0,0 +1,154 @@
+# Ecommerce Template
+
+Minimal Next.js commerce storefront template with a pluggable payment-adapter
+seam. A single source scaffolds either supported payment provider; the active
+provider for a generated app is recorded in `app-config.ts` and its keys live in
+`.env.local.example`.
+
+## What is included
+
+- App Router storefront routes for product listing, product detail, cart,
+  checkout, and payment success.
+- Adapter boundaries under `lib/commerce` and `lib/payment`.
+- Demo commerce and payment adapters backed by `data/mock-catalog.json`.
+- Automatic `@01.software/sdk/server` commerce adapter when 01.software SDK
+  credentials are present.
+- A payment-adapter registry (`lib/payment/provider.server.ts`) that selects a
+  provider from environment credentials, with first-class adapters for:
+  - **PortOne** — `@portone/browser-sdk/v2` on the client, `@portone/server-sdk`
+    on the server.
+  - **TossPayments** — the TossPayments browser SDK on the client, the
+    TossPayments payment REST API on the server.
+- A theming seam: a CSS-variable token layer in `app/globals.css` plus Tailwind.
+- Server-side order pricing, stock checks, and payment sync invariants.
+- Server-authoritative cart operations through the template's own route handlers,
+  backed by `commerce.cart.*`.
+- An HttpOnly cart cookie containing only the unguessable `cartToken`; client
+  JavaScript receives rendered cart views but never owns the authoritative cart
+  or token, and no cart contents are persisted in localStorage.
+- Checkout through `orders.checkout({ cartId })`, with orders resolved after
+  payment by `orders.getByPaymentId`.
+
+## Scaffolding vs. this in-repo source
+
+This directory is the single in-repo source and intentionally ships **both**
+payment adapters so it builds and tests with every provider present.
+`create-01-software-app` copies it, prunes the unused payment adapter (and its
+dependency), generates `app-config.ts` and `.env.local.example` from
+`templates/registry.json`, and pins the SDK version — producing a self-contained
+single-provider app.
+
+To add a new payment provider, see **Add a payment provider** below.
+
+## Run locally
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Without SDK or payment credentials, the app uses demo providers:
+
+```bash
+# 01.software keys omitted -> demo catalog plus in-memory cart/checkout
+# payment keys omitted -> local demo payment completion
+```
+
+The mock adapter emulates the server cart and checkout flow in memory for
+zero-backend demos. Redirect and success routes resolve the same in-process
+checkout model without writing a local order index.
+
+To use the Console ecommerce SDK adapter, set both SDK keys:
+
+```bash
+NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY=pk_...
+SOFTWARE_SECRET_KEY=sk_...
+SOFTWARE_API_URL=https://your-console-origin.example
+SOFTWARE_SHIPPING_AMOUNT=3000
+SOFTWARE_FREE_SHIPPING_ABOVE_AMOUNT=100000
+```
+
+`SOFTWARE_API_URL`, `SOFTWARE_SHIPPING_AMOUNT`, and
+`SOFTWARE_FREE_SHIPPING_ABOVE_AMOUNT` are optional. The SDK adapter uses Console
+cart and order APIs for the full server-authoritative flow: route handlers call
+`commerce.cart.*`, checkout calls `orders.checkout({ cartId })`, and
+return/webhook/success reconciliation resolves orders by payment id through
+`orders.getByPaymentId`.
+
+## Payment provider keys
+
+### PortOne
+
+```bash
+PORTONE_API_SECRET=...
+NEXT_PUBLIC_PORTONE_STORE_ID=store_...
+NEXT_PUBLIC_PORTONE_CHANNEL_KEY=channel-key-...
+NEXT_PUBLIC_PORTONE_PAY_METHOD=CARD
+PORTONE_WEBHOOK_SECRET=...
+```
+
+`NEXT_PUBLIC_PORTONE_PAY_METHOD` is optional and defaults to `CARD`.
+`PORTONE_WEBHOOK_SECRET` is required in production. For local development without
+signed webhooks, set `PORTONE_ALLOW_UNSIGNED_WEBHOOKS=true`. When the secret is
+present, the webhook route verifies PortOne webhook signatures through
+`@portone/server-sdk`.
+
+### TossPayments
+
+```bash
+TOSSPAYMENTS_SECRET_KEY=test_sk_...
+NEXT_PUBLIC_TOSSPAYMENTS_CLIENT_KEY=test_ck_...
+NEXT_PUBLIC_TOSSPAYMENTS_CUSTOMER_KEY=customer_...
+```
+
+`NEXT_PUBLIC_TOSSPAYMENTS_CUSTOMER_KEY` is optional. If omitted, the browser SDK
+uses TossPayments' anonymous customer key. TossPayments redirects back with
+`paymentKey`, `orderId`, and `amount`; `/api/checkout/payment-return` re-fetches
+the provider payment, rejects a tampered redirect amount, captures with the
+PG-verified amount, then redirects to the success page. Success-page
+reconciliation re-fetches the provider payment again and places the Console
+checkout through `orders.confirmPayment`, where the open checkout quote remains
+the authoritative amount check.
+`TOSSPAYMENTS_API_BASE_URL` is optional and defaults to
+`https://api.tosspayments.com/v1`.
+
+## Add a payment provider
+
+1. Add `lib/payment/adapters/<pg>.ts` implementing the `PaymentProvider` port
+   and exporting `create<Pg>Provider` plus `has<Pg>Credentials`.
+2. Register it in `lib/payment/provider.server.ts` inside a matching pair of
+   `scaffold:provider:<id>` markers (import + registry entry).
+3. Add a `ClientPaymentRequest` union case in `lib/payment/types.ts`.
+4. Add a client branch (and its `scaffold:provider:<id>` markers) in
+   `components/checkout/checkout-form.tsx`.
+5. Add the provider to `templates/registry.json` so the scaffolder offers it.
+
+The template depends on the published `@01.software/sdk` package so it can be
+copied out of this monorepo and installed as a standalone Next.js app.
+
+The starter `software` product listing uses a simple products query followed by
+per-product detail lookups so the UI can share one normalized product-detail
+shape. It isolates individual detail failures with `Promise.allSettled`. For a
+larger storefront, replace that listing path with the Console tenant's preferred
+catalog/listing API shape.
+
+## Verify
+
+```bash
+pnpm test
+pnpm check-types
+pnpm lint
+pnpm build
+```
+
+## Important boundary
+
+The browser never owns the authoritative cart or cart capability tokens. It
+talks to the template's cart route handlers, which keep the cart
+server-authoritative and store only an HttpOnly cart cookie in the browser.
+Client components may keep rendered cart views in memory, but cart mutations and
+checkout always return to the server cart. Checkout attaches customer and
+shipping details to that server cart, converts it with
+`orders.checkout({ cartId })`, and then synchronizes payment state. After
+payment, order lookup uses `orders.getByPaymentId`, so the template does not
+need a file-backed order index.

package/dist/create-app-templates/ecommerce/app/api/auth/login/route.ts

@@ -0,0 +1,30 @@
+import { syncActiveCartCookieOnLogin } from "@/lib/cart/sync-on-login.server.ts";
+import { login } from "@/lib/customer/auth-actions";
+import { assertSameOriginJson } from "@/lib/customer/route-guard.ts";
+import { authErrorResponse, parseLogin } from "@/lib/customer/route-helpers.ts";
+import { setSessionToken } from "@/lib/customer/session";
+
+// Log in: delegate to `client.customer.auth.login`, then stamp the customer JWT
+// into the HttpOnly session cookie and slave the active-cart cookie to the
+// customer's server-owned cart (union a pre-login guest cart, else load theirs).
+// CSRF-guarded (same-origin + JSON).
+export async function POST(request: Request) {
+  try {
+    assertSameOriginJson(request);
+    const input = parseLogin(await request.json());
+    const result = await login(input);
+    if (!result.ok) {
+      return Response.json(
+        { code: "login_failed", message: result.message },
+        { status: result.status },
+      );
+    }
+    if (result.token) {
+      await setSessionToken(result.token);
+      await syncActiveCartCookieOnLogin(result.token);
+    }
+    return Response.json({ customer: result.customer });
+  } catch (error) {
+    return authErrorResponse(error);
+  }
+}

package/dist/create-app-templates/ecommerce/app/api/auth/logout/route.ts

@@ -0,0 +1,18 @@
+import { assertSameOriginJson } from "@/lib/customer/route-guard.ts";
+import { authErrorResponse } from "@/lib/customer/route-helpers.ts";
+import { clearSessionAndCart } from "@/lib/customer/session";
+
+// Log out: clear the HttpOnly session cookie AND the active-cart cookie together.
+// The customer JWT is stateless, so dropping the cookie ends the session
+// client-side; the cart-token handle is slaved to the session, so it is dropped
+// atomically too (no later session inherits this identity's cart). CSRF-guarded
+// (same-origin + JSON) so a cross-site request cannot force-logout the customer.
+export async function POST(request: Request) {
+  try {
+    assertSameOriginJson(request);
+    await clearSessionAndCart();
+    return Response.json({ ok: true });
+  } catch (error) {
+    return authErrorResponse(error);
+  }
+}

package/dist/create-app-templates/ecommerce/app/api/auth/register/route.ts

@@ -0,0 +1,41 @@
+import { syncActiveCartCookieOnLogin } from "@/lib/cart/sync-on-login.server.ts";
+import { login, register } from "@/lib/customer/auth-actions";
+import { assertSameOriginJson } from "@/lib/customer/route-guard.ts";
+import {
+  authErrorResponse,
+  parseRegister,
+} from "@/lib/customer/route-helpers.ts";
+import { setSessionToken } from "@/lib/customer/session";
+
+// Register: delegate to `client.customer.auth.register`, then log the new
+// customer in to mint a session JWT (register returns no token) and stamp it
+// into the HttpOnly session cookie. CSRF-guarded (same-origin + JSON).
+export async function POST(request: Request) {
+  try {
+    assertSameOriginJson(request);
+    const input = parseRegister(await request.json());
+    const created = await register(input);
+    if (!created.ok) {
+      return Response.json(
+        { code: "register_failed", message: created.message },
+        { status: created.status },
+      );
+    }
+
+    // Registration may require verification before login succeeds; if the
+    // follow-up login fails, the account still exists — report success without a
+    // session so the UI can route the customer to the login page.
+    const session = await login({
+      email: input.email,
+      password: input.password,
+    });
+    if (session.ok && session.token) {
+      await setSessionToken(session.token);
+      await syncActiveCartCookieOnLogin(session.token);
+      return Response.json({ customer: session.customer });
+    }
+    return Response.json({ customer: created.customer, requiresLogin: true });
+  } catch (error) {
+    return authErrorResponse(error);
+  }
+}

package/dist/create-app-templates/ecommerce/app/api/cart/clear/route.ts

@@ -0,0 +1,12 @@
+import { clearActiveCart } from "@/lib/cart/server-cart";
+import { cartErrorResponse } from "@/lib/cart/route-helpers.ts";
+
+// Empty the owned cart (no-op when none is owned).
+export async function POST() {
+  try {
+    const cart = await clearActiveCart();
+    return Response.json({ cart });
+  } catch (error) {
+    return cartErrorResponse(error);
+  }
+}

package/dist/create-app-templates/ecommerce/app/api/cart/items/route.ts

@@ -0,0 +1,45 @@
+import {
+  addItemToCart,
+  removeCartItemFromCart,
+  updateCartItemQuantity,
+} from "@/lib/cart/server-cart";
+import {
+  parseAddItem,
+  parseRemoveItem,
+  parseUpdateItem,
+} from "@/lib/cart/parse-cart-request.ts";
+import { cartErrorResponse } from "@/lib/cart/route-helpers.ts";
+
+// Add a line. Creates + stamps the guest cart cookie when none is owned yet.
+export async function POST(request: Request) {
+  try {
+    const cart = await addItemToCart(parseAddItem(await request.json()));
+    return Response.json({ cart });
+  } catch (error) {
+    return cartErrorResponse(error);
+  }
+}
+
+// Update a line quantity by its cart-item handle.
+export async function PATCH(request: Request) {
+  try {
+    const cart = await updateCartItemQuantity(
+      parseUpdateItem(await request.json()),
+    );
+    return Response.json({ cart });
+  } catch (error) {
+    return cartErrorResponse(error);
+  }
+}
+
+// Remove a line by its cart-item handle.
+export async function DELETE(request: Request) {
+  try {
+    const cart = await removeCartItemFromCart(
+      parseRemoveItem(await request.json()),
+    );
+    return Response.json({ cart });
+  } catch (error) {
+    return cartErrorResponse(error);
+  }
+}

package/dist/create-app-templates/ecommerce/app/api/cart/route.ts

@@ -0,0 +1,14 @@
+import { getCartFromCookie } from "@/lib/cart/server-cart";
+import { cartErrorResponse } from "@/lib/cart/route-helpers.ts";
+
+// The cart lives server-side (`commerce.cart.*`); this returns the current
+// guest cart resolved from the HttpOnly ownership cookie, or `{ cart: null }`
+// when none is owned yet.
+export async function GET() {
+  try {
+    const cart = await getCartFromCookie();
+    return Response.json({ cart });
+  } catch (error) {
+    return cartErrorResponse(error);
+  }
+}

package/dist/create-app-templates/ecommerce/app/api/checkout/payment-return/route.ts

@@ -0,0 +1,86 @@
+import { redirect } from "next/navigation";
+import {
+  AmountMismatchError,
+  assertAmountEquals,
+} from "@/lib/payment/amount-gate";
+import { getPaymentProvider } from "@/lib/payment/provider.server";
+
+/**
+ * PG redirect return. For providers that require a server-side capture (e.g.
+ * Toss `/payments/confirm` with the returned `paymentKey`), this runs the shared
+ * amount-equality gate, captures, then hands off to the success page which
+ * reconciles the order via `syncOrderPayment` (server re-fetch →
+ * `orders.confirmPayment`).
+ *
+ * The redirect query is fully client-tamperable, so its `amount` is NEVER
+ * forwarded to the capture. We re-fetch the payment from the PG, assert the
+ * query amount (when present) equals the re-fetched amount (#1544 / I6 amount
+ * gate), and then capture with the PG-verified amount. The order is ultimately
+ * placed against the Console quote, never this query value.
+ */
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const paymentId =
+    searchParams.get("paymentId") ?? searchParams.get("orderId");
+  const orderNumber = searchParams.get("orderNumber") ?? undefined;
+  const providerPaymentId = searchParams.get("paymentKey") ?? undefined;
+  const amountValue = searchParams.get("amount");
+  const clientAmount = amountValue ? Number(amountValue) : undefined;
+
+  if (!paymentId) {
+    return Response.json({ code: "missing_payment_id" }, { status: 400 });
+  }
+  if (amountValue && !Number.isFinite(clientAmount)) {
+    return Response.json({ code: "invalid_amount" }, { status: 400 });
+  }
+
+  // Capture is required only when the provider returns a capture token
+  // (`paymentKey`) or a client amount to validate. Providers without a
+  // return-side capture (PortOne, mock) fall straight through to the success
+  // page, where `syncOrderPayment` re-fetches, gates, and places.
+  if (providerPaymentId || clientAmount != null) {
+    try {
+      const provider = getPaymentProvider();
+      // Re-fetch the authoritative amount from the PG — the trust anchor.
+      const verified = await provider.getPayment(paymentId);
+      if (!verified) {
+        return Response.json(
+          { code: "payment_not_found" },
+          { status: 404 },
+        );
+      }
+      // Amount gate: a tampered redirect query is rejected before any capture.
+      if (clientAmount != null) {
+        assertAmountEquals({
+          context: `return:${provider.provider}:${paymentId}`,
+          expected: verified.amount,
+          actual: clientAmount,
+        });
+      }
+      // Capture with the PG-verified amount, never the client query value.
+      await provider.confirmPayment({
+        paymentId,
+        providerPaymentId,
+        amount: verified.amount,
+      });
+    } catch (error) {
+      if (error instanceof AmountMismatchError) {
+        return Response.json(
+          { code: "amount_mismatch" },
+          { status: 422 },
+        );
+      }
+      const message =
+        error instanceof Error ? error.message : "Payment confirmation failed";
+      return Response.json(
+        { code: "payment_confirmation_failed", message },
+        { status: 422 },
+      );
+    }
+  }
+
+  const params = new URLSearchParams({ paymentId });
+  if (orderNumber) params.set("orderNumber", orderNumber);
+
+  redirect(`/checkout/success?${params.toString()}`);
+}

package/dist/create-app-templates/ecommerce/app/api/checkout/reconcile/route.ts

@@ -0,0 +1,50 @@
+import { getCommerceProvider } from "@/lib/commerce/provider.server";
+import { AmountMismatchError } from "@/lib/payment/amount-gate";
+import { getPaymentProvider } from "@/lib/payment/provider.server";
+import { syncOrderPayment } from "@/lib/payment/sync-order-payment.ts";
+
+/**
+ * Order reconciliation, moved off the success-page RSC render into a route
+ * handler (#1544 / I6). Mutating during Server Component render is unsound
+ * (renders may run more than once); the success page now renders a client
+ * trigger that POSTs here exactly once. `syncOrderPayment` is itself idempotent
+ * — the Console dedups by `pgPaymentId` / `providerEventId` — so a retry or a
+ * concurrent webhook still collapses to a single `paid` transition. The shared
+ * amount-equality gate runs inside `syncOrderPayment` on this success path.
+ */
+export async function POST(request: Request) {
+  let body: { paymentId?: unknown; orderNumber?: unknown };
+  try {
+    body = (await request.json()) as typeof body;
+  } catch {
+    return Response.json({ code: "invalid_request" }, { status: 400 });
+  }
+
+  const paymentId =
+    typeof body.paymentId === "string" ? body.paymentId : undefined;
+  const orderNumber =
+    typeof body.orderNumber === "string" ? body.orderNumber : undefined;
+  if (!paymentId) {
+    return Response.json({ code: "missing_payment_id" }, { status: 400 });
+  }
+
+  try {
+    const result = await syncOrderPayment({
+      paymentId,
+      orderNumber,
+      commerceProvider: getCommerceProvider(),
+      paymentProvider: getPaymentProvider(),
+    });
+    return Response.json(result);
+  } catch (error) {
+    if (error instanceof AmountMismatchError) {
+      return Response.json({ code: "amount_mismatch" }, { status: 422 });
+    }
+    const message =
+      error instanceof Error ? error.message : "Reconciliation failed";
+    return Response.json(
+      { code: "reconciliation_failed", message },
+      { status: 422 },
+    );
+  }
+}

package/dist/create-app-templates/ecommerce/app/api/checkout/route.ts

@@ -0,0 +1,41 @@
+import { getCheckoutCommerceProvider } from "@/lib/checkout/checkout-provider";
+import {
+  getCheckoutErrorMessage,
+  getCheckoutErrorStatus,
+} from "@/lib/checkout/checkout-errors";
+import { startCheckout } from "@/lib/checkout/start-checkout.ts";
+import {
+  dropCartCookie,
+  getCheckoutCartToken,
+} from "@/lib/cart/server-cart";
+import { getPaymentProvider } from "@/lib/payment/provider.server";
+
+export async function POST(request: Request) {
+  const cartToken = await getCheckoutCartToken();
+  if (!cartToken) {
+    return Response.json(
+      { code: "cart_not_found", message: "No active cart to check out" },
+      { status: 409 },
+    );
+  }
+
+  try {
+    const result = await startCheckout({
+      cartToken,
+      payload: await request.json(),
+      commerceProvider: await getCheckoutCommerceProvider(),
+      paymentProvider: getPaymentProvider(),
+    });
+
+    // Checkout consumed the cart (Shopify cart→checkout boundary). Drop the
+    // ownership cookie so the next visit starts a fresh cart.
+    await dropCartCookie();
+
+    return Response.json(result);
+  } catch (error) {
+    const message = getCheckoutErrorMessage(error);
+    const status = getCheckoutErrorStatus(error);
+
+    return Response.json({ code: "checkout_failed", message }, { status });
+  }
+}

package/dist/create-app-templates/ecommerce/app/cart/page.tsx

@@ -0,0 +1,10 @@
+import { CartContent } from "@/components/cart/cart-content";
+import { PageShell } from "@/components/layout/page-shell";
+
+export default function CartPage() {
+  return (
+    <PageShell>
+      <CartContent />
+    </PageShell>
+  );
+}

package/dist/create-app-templates/ecommerce/app/checkout/page.tsx

@@ -0,0 +1,10 @@
+import { CheckoutForm } from "@/components/checkout/checkout-form";
+import { PageShell } from "@/components/layout/page-shell";
+
+export default function CheckoutPage() {
+  return (
+    <PageShell>
+      <CheckoutForm />
+    </PageShell>
+  );
+}

package/dist/create-app-templates/ecommerce/app/checkout/success/page.tsx

@@ -0,0 +1,34 @@
+import { PageShell } from "@/components/layout/page-shell";
+import { CheckoutReconcile } from "@/components/checkout/checkout-reconcile";
+
+/**
+ * Payment return landing. Reconciliation is intentionally NOT performed during
+ * render — a Server Component render must be side-effect free and may run more
+ * than once. The client `CheckoutReconcile` trigger POSTs to the reconcile
+ * route handler once on mount instead (#1544 / I6).
+ */
+export default async function CheckoutSuccessPage({
+  searchParams,
+}: {
+  searchParams: Promise<{ paymentId?: string; orderNumber?: string }>;
+}) {
+  const params = await searchParams;
+  const paymentId = params.paymentId;
+
+  if (!paymentId) {
+    return (
+      <PageShell>
+        <section>
+          <h1>Missing payment</h1>
+          <p>The return URL did not include a payment ID.</p>
+        </section>
+      </PageShell>
+    );
+  }
+
+  return (
+    <PageShell>
+      <CheckoutReconcile paymentId={paymentId} orderNumber={params.orderNumber} />
+    </PageShell>
+  );
+}

package/dist/create-app-templates/ecommerce/app/globals.css

@@ -0,0 +1,67 @@
+@import "tailwindcss";
+
+/*
+ * Theming seam.
+ *
+ * The CSS-variable token layer below is the rebrand surface: change a value in
+ * `:root` and every page that consumes the token re-skins. The `@theme inline`
+ * block exposes the same tokens to Tailwind utilities (e.g. `bg-background`,
+ * `text-brand`) so component styling can be added without leaving this layer.
+ * The storefront keeps its semantic-HTML / a11y baseline; styling is additive.
+ */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-border: var(--border);
+  --color-brand: var(--brand);
+  --color-brand-foreground: var(--brand-foreground);
+  --font-sans: var(--font-sans);
+}
+
+:root {
+  /* Brand */
+  --brand: #1f2937;
+  --brand-foreground: #ffffff;
+
+  /* Surfaces */
+  --background: #ffffff;
+  --foreground: #111827;
+  --muted: #f3f4f6;
+  --muted-foreground: #6b7280;
+  --border: rgba(17, 24, 39, 0.12);
+
+  /* Type */
+  --font-sans:
+    ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue",
+    Arial, sans-serif;
+
+  /* Spacing rhythm shared by page sections */
+  --space-page: 1.5rem;
+  --measure: 72ch;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --brand: #e5e7eb;
+    --brand-foreground: #111827;
+    --background: #0b0f19;
+    --foreground: #f3f4f6;
+    --muted: #161b27;
+    --muted-foreground: #9ca3af;
+    --border: rgba(243, 244, 246, 0.14);
+  }
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: var(--font-sans);
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+}
+
+main {
+  padding: var(--space-page);
+}