@ultimat3/cli 20.1.5 → 20.2.0

package/src/templates/scaffold-dashboard-example.ts

@@ -0,0 +1,326 @@
+// The `--example` dashboard: the seeded `post` slice from above. Real rows through the slice's own
+// repo, aggregated by a pure view module this file also emits, so the numbers are testable without
+// a database. The page's route declaration and its island come from `scaffold-dashboard-shared.ts`.
+
+import { sortedImports } from './imports';
+import type { GeneratedFile, NameSet } from './naming';
+import { DASHBOARD_DIR, routeConfig, themeActions, themeIsland } from './scaffold-dashboard-shared';
+
+// Plain strings for the framework lines, never template literals: the workspace-dependency scanner
+// blanks a string's contents but not a nested template's, so a template here would bill the CLI
+// for the imports of the app it writes.
+const examplePage = (
+  app: NameSet,
+): string => `// The authed dashboard: what the seeded \`post\` slice looks like from above. Real rows, read
+// through the slice's own repo and aggregated by \`dashboard-view.ts\`, which is pure so the numbers
+// are testable without a database.
+//
+// \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  "import { isUltimateError } from '@ultimat3/core';",
+  "import { seedId } from '@ultimat3/entity';",
+  "import { currentLocale } from '@ultimat3/i18n';",
+  "import { defineRoute, island } from '@ultimat3/render';",
+  [
+    'import {',
+    '  BarChart,',
+    '  DataTable,',
+    '  Grid,',
+    '  PageHeader,',
+    '  RelativeTime,',
+    '  Section,',
+    '  StatTile,',
+    '  ThemeToggle,',
+    "} from '@ultimat3/ui';",
+  ].join('\n'),
+])}
+import { Shell } from '../../shared/shell';
+import * as repo from '../post/repo';
+import {
+  bucketByDay,
+  CHART_DAYS,
+  formatCount,
+  type PostRow,
+  postStats,
+  toPostRow,
+} from './dashboard-view';
+import styles from './page.module.scss';
+
+/**
+ * Whose posts. The route's policy decides who may open this page; which org's rows it aggregates
+ * is a decision the load makes, and until this app issues sessions the only org with rows is the
+ * one \`packages/db/src/seed.ts\` writes. The day sessions exist, this becomes the actor's org and
+ * the read becomes \`postList.as(actor, …)\` — the query already declares the tenancy rule.
+ */
+const DEMO_ORG = seedId('org:demo');
+
+/** The stat row counts what it can see. Past this many posts, write an aggregate query. */
+const ROW_LIMIT = 500;
+
+/** How many of the newest posts the table shows. */
+const TABLE_ROWS = 10;
+
+export interface DashboardData {
+  /** Newest first, as the repo orders them. */
+  readonly rows: readonly PostRow[];
+  /** The instant the windows were cut at, so server and test agree on "the last 7 days". */
+  readonly now: string;
+}
+
+async function load(): Promise<DashboardData> {
+  const now = new Date().toISOString();
+  try {
+    const rows = await repo.listByOrg(DEMO_ORG, ROW_LIMIT);
+    return { rows: rows.map(toPostRow), now };
+  } catch (error) {
+    // \`x build --target static\` renders every route once to measure its JS budget, with no
+    // database wired — so this is that measurement pass, not a request. Empty rows render the
+    // real empty branches, which measure the same markup. Any other failure still propagates.
+    if (isUltimateError(error) && error.code === 'X_DB_UNAVAILABLE') return { rows: [], now };
+    throw error;
+  }
+}
+
+${themeIsland}
+
+${routeConfig('\n  load,')}
+
+export interface DashboardPageProps {
+  readonly data: DashboardData;
+}
+
+export function DashboardPage(props: DashboardPageProps) {
+  const t = useT();
+  const locale = currentLocale();
+  const now = new Date(props.data.now);
+  const stats = postStats(props.data.rows, now);
+  const points = bucketByDay(props.data.rows, now, CHART_DAYS);
+  const latest = props.data.rows.slice(0, TABLE_ROWS);
+
+  return (
+    <Shell
+      nav="dashboard"
+      actions={
+        ${themeActions}
+      }
+    >
+      <div class={styles.page}>
+        <PageHeader title={t('app.dashboard.title')} description={t('app.dashboard.subtitle')} />
+        {/* 10rem, not the catalog's 16rem default: three tiles fit across a tablet's main column
+            instead of leaving one alone on a second row. */}
+        <Grid minColumn="10rem">
+          <StatTile
+            stat="posts-total"
+            label={t('app.dashboard.statTotal')}
+            value={formatCount(stats.total, locale)}
+            hint={t('app.dashboard.hintTotal')}
+          />
+          <StatTile
+            stat="posts-week"
+            label={t('app.dashboard.statWeek')}
+            value={formatCount(stats.lastWeek, locale)}
+            delta={stats.delta}
+            hint={t('app.dashboard.hintVsPriorWeek')}
+          />
+          <StatTile
+            stat="posts-today"
+            label={t('app.dashboard.statToday')}
+            value={formatCount(stats.today, locale)}
+            hint={t('app.dashboard.hintToday')}
+          />
+        </Grid>
+        <Section title={t('app.dashboard.chartTitle')} description={t('app.dashboard.chartRange')}>
+          <BarChart label={t('app.dashboard.chartLabel')} points={points} />
+        </Section>
+        <Section title={t('app.dashboard.tableTitle')}>
+          <DataTable
+            caption={t('app.dashboard.tableCaption')}
+            rowKey={(row: PostRow) => row.id}
+            rows={latest}
+            emptyTitle={t('app.dashboard.emptyTitle')}
+            columns={[
+              { key: 'title', header: t('app.dashboard.columnTitle'), cell: (row) => row.title },
+              {
+                key: 'createdAt',
+                header: t('app.dashboard.columnCreated'),
+                cell: (row) => (
+                  <RelativeTime value={row.createdAt} now={props.data.now} locale={locale} />
+                ),
+              },
+            ]}
+          />
+        </Section>
+      </div>
+    </Shell>
+  );
+}
+`;
+
+const exampleView =
+  (): string => `// The dashboard's numbers, apart from its markup: pure functions over the rows the page loaded,
+// so the server render and a test cannot disagree about a figure. No I/O, no \`t()\`, no JSX.
+
+import { type ChartPoint, deltaOf, type StatDelta } from '@ultimat3/ui';
+
+/** Days of history the chart shows, oldest first. */
+export const CHART_DAYS = 14;
+
+const DAY_MS = 86_400_000;
+
+/** One post as the page reads it. \`createdAt\` is ISO text: a \`Date\` cannot cross a JSON seam. */
+export interface PostRow {
+  readonly id: string;
+  readonly title: string;
+  readonly createdAt: string;
+}
+
+/**
+ * Duck-typed rather than the entity's own row: the page only ever reads these three columns.
+ *
+ * BOTH spellings of the timestamp, and that is a measured fact rather than caution: the repo's
+ * \`select *\` hands back column names as Postgres has them (\`created_at\`) while its row type
+ * says \`createdAt\`, so the typed property is \`undefined\` on a real row. Until the repo aliases
+ * its columns — dz-showcase's does — the page reads whichever one arrived.
+ */
+export function toPostRow(row: {
+  readonly id: string;
+  readonly title: string;
+  readonly createdAt?: Date | string | undefined;
+  readonly created_at?: Date | string | undefined;
+}): PostRow {
+  const at = row.createdAt ?? row.created_at ?? '';
+  return {
+    id: row.id,
+    title: row.title,
+    createdAt: at instanceof Date ? at.toISOString() : at,
+  };
+}
+
+export interface PostStats {
+  readonly total: number;
+  /** Created in the seven days ending at \`now\`. */
+  readonly lastWeek: number;
+  /** \`lastWeek\` against the seven days before it; absent when that baseline is zero. */
+  readonly delta: StatDelta | undefined;
+  /** Created in the UTC day \`now\` falls in — a partial day, so it carries no delta. */
+  readonly today: number;
+}
+
+const createdAtOf = (row: PostRow): number => Date.parse(row.createdAt);
+
+const within = (rows: readonly PostRow[], from: number, to: number): number =>
+  rows.filter((row) => {
+    const at = createdAtOf(row);
+    return Number.isFinite(at) && at > from && at <= to;
+  }).length;
+
+export function postStats(rows: readonly PostRow[], now: Date): PostStats {
+  const end = now.getTime();
+  const weekAgo = end - 7 * DAY_MS;
+  const dayStart = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  const lastWeek = within(rows, weekAgo, end);
+  return {
+    total: rows.length,
+    lastWeek,
+    delta: deltaOf(lastWeek, within(rows, weekAgo - 7 * DAY_MS, weekAgo)),
+    today: within(rows, dayStart - 1, end),
+  };
+}
+
+/** \`MM-DD\` of a UTC day. ISO, never \`toLocaleDateString\`: the chart's axis is data, not prose. */
+const dayKey = (at: number): string => new Date(at).toISOString().slice(5, 10);
+
+/**
+ * One bucket per UTC day, the last one being the day \`now\` falls in, oldest first — the shape
+ * \`BarChart\` draws. Every day is present even when nothing was created on it: a chart with the
+ * quiet days removed reads as busier than the app is.
+ */
+export function bucketByDay(
+  rows: readonly PostRow[],
+  now: Date,
+  days: number,
+): readonly ChartPoint[] {
+  const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  const start = today - (days - 1) * DAY_MS;
+  const counts: number[] = Array.from({ length: days }, () => 0);
+  for (const row of rows) {
+    const at = createdAtOf(row);
+    if (!Number.isFinite(at)) continue;
+    const index = Math.floor((at - start) / DAY_MS);
+    if (index >= 0 && index < days) counts[index] = (counts[index] ?? 0) + 1;
+  }
+  return counts.map((value, index) => ({ key: dayKey(start + index * DAY_MS), value }));
+}
+
+/** A figure for a tile, in the page's locale. \`Intl.NumberFormat\` needs no time zone. */
+export const formatCount = (value: number, locale: string): string =>
+  new Intl.NumberFormat(locale).format(value);
+`;
+
+const exampleViewTest =
+  (): string => `// The numbers the dashboard shows, pinned against a fixed clock. The interesting cases are the
+// window edges: a post from eight days ago is in the prior week, not this one, and a day with no
+// posts is still a bar.
+import { expect, unitTest } from '@ultimat3/testing';
+import { bucketByDay, formatCount, type PostRow, postStats, toPostRow } from './dashboard-view';
+
+const NOW = new Date('2026-03-15T12:00:00.000Z');
+const DAY_MS = 86_400_000;
+
+const row = (id: string, daysAgo: number): PostRow => ({
+  id,
+  title: \`post \${id}\`,
+  createdAt: new Date(NOW.getTime() - daysAgo * DAY_MS).toISOString(),
+});
+
+const rows = [row('a', 1), row('b', 3), row('c', 8)];
+
+unitTest('postStats counts the week, compares it with the prior one, and counts today', () => {
+  const stats = postStats(rows, NOW);
+  expect(stats.total).toBe(3);
+  expect(stats.lastWeek).toBe(2);
+  // Two this week against one the week before: +100%, and the chip says so.
+  expect(stats.delta).toEqual({ text: '+100%', trend: 'up' });
+  // 'a' is yesterday and nothing was created on 03-15 itself.
+  expect(stats.today).toBe(0);
+  expect(postStats([...rows, row('d', 0.25)], NOW).today).toBe(1);
+});
+
+unitTest('a zero baseline yields no delta, and no rows count nothing', () => {
+  expect(postStats([row('a', 1)], NOW).delta).toBeUndefined();
+  expect(postStats([], NOW)).toEqual({ total: 0, lastWeek: 0, delta: undefined, today: 0 });
+});
+
+unitTest('bucketByDay is one bar per day, oldest first, quiet days included', () => {
+  const points = bucketByDay(rows, NOW, 14);
+  expect(points).toHaveLength(14);
+  expect(points.at(-1)?.key).toBe('03-15');
+  expect(points[0]?.key).toBe('03-02');
+  expect(points.reduce((sum, point) => sum + point.value, 0)).toBe(3);
+  // Eight days ago is 03-07: inside a 14-day window, so the bar is there.
+  expect(points.find((point) => point.key === '03-07')?.value).toBe(1);
+  expect(bucketByDay([], NOW, 3).map((point) => point.value)).toEqual([0, 0, 0]);
+});
+
+unitTest('toPostRow serialises a Date, passes ISO text through, and reads the raw column', () => {
+  const at = new Date('2026-01-02T03:04:05.000Z');
+  expect(toPostRow({ id: 'x', title: 't', createdAt: at }).createdAt).toBe(at.toISOString());
+  expect(toPostRow({ id: 'x', title: 't', createdAt: '2026-01-01' }).createdAt).toBe('2026-01-01');
+  // What \`select *\` really returns: the snake_case column, and no \`createdAt\` at all.
+  expect(toPostRow({ id: 'x', title: 't', created_at: at }).createdAt).toBe(at.toISOString());
+  expect(toPostRow({ id: 'x', title: 't' }).createdAt).toBe('');
+});
+
+unitTest('formatCount follows the locale', () => {
+  expect(formatCount(1234, 'en')).toBe('1,234');
+  expect(formatCount(1234, 'de')).toBe('1.234');
+});
+`;
+
+/** The example dashboard's page, view module and view test. */
+export const exampleDashboardFiles = (app: NameSet): readonly GeneratedFile[] => [
+  { path: `${DASHBOARD_DIR}/page.tsx`, contents: examplePage(app) },
+  { path: `${DASHBOARD_DIR}/dashboard-view.ts`, contents: exampleView() },
+  { path: `${DASHBOARD_DIR}/dashboard-view.test.ts`, contents: exampleViewTest() },
+];

package/src/templates/scaffold-dashboard-shared.ts

@@ -0,0 +1,74 @@
+// What both dashboards share — `scaffold-dashboard.ts` picks one of `scaffold-dashboard-example.ts`
+// and `scaffold-dashboard-bare.ts` per invocation, and everything the two must agree on lives here:
+// the route declaration, the theme island, the stylesheet and the config test.
+
+export const DASHBOARD_DIR = 'apps/web/app/dashboard';
+
+export const routeConfig = (load: string): string => `export const config = defineRoute({
+  // 'ssr', not 'stream', and this is not a downgrade: 'stream' needs a boundary to stream into,
+  // and the framework has no hole marker yet. Solid's <Suspense> is not it — it throws outside a
+  // Solid renderer, and the server JSX factory is inert on purpose. A scaffolded 'stream' route
+  // therefore failed x routes with X_ROUTE_MODE_INVALID on the first run, printing a fix nobody
+  // could follow. Ship the mode that works. Async data needs no boundary: await it in the page.
+  render: 'ssr',
+  // 'visible' for the one island on this page, the theme toggle in the header.
+  hydrate: 'visible',
+  offline: 'runtime',
+  // Auth is a policy, never a route-local flag: one authz system, evaluated everywhere.
+  policy: { permission: 'dashboard:read' },
+  // Only the toggle island hydrates; the tiles, the chart and the table are server markup. The
+  // island measured 60.9kb minified under Bun 1.4.2 — solid-js is 12.6kb of it, the catalog's
+  // toggle, provider and the ui runtime they share are the rest — so 64kb is that figure plus
+  // the few hundred bytes the minifier moves between Bun patch versions, not headroom to spend.
+  budget: { js: '64kb' },${load}
+  meta: ({ t }) => ({
+    title: t('app.dashboard.title'),
+    description: t('app.dashboard.description'),
+  }),
+});`;
+
+/** Declared ABOVE `defineRoute`: the route drains the island declarations made before it. */
+export const themeIsland = `// Named by SPECIFIER, never by import (axiom 6): a string has no import edge, so the page's
+// bundle graph stays the page's. \`props\` is the exact contract of \`ThemeToggleIslandProps\`.
+const ThemeSwitch = island({ src: '../../shared/theme-toggle.island.tsx', props: ['locale'] });`;
+
+/**
+ * The pre-hydration shell: the catalog's toggle renders from server markup alone, so the served
+ * document already shows the control the island takes over. `initial="dark"` is this app's
+ * `theme.defaultMode`, stated once more here because the server has no browser to ask.
+ */
+export const themeActions = `<ThemeSwitch locale={locale}>
+          <ThemeToggle mode="toggle" initial="dark" />
+        </ThemeSwitch>`;
+
+export const dashboardStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
+
+.page {
+  display: flex;
+  flex-direction: column;
+  gap: tokens.space(6);
+  // A measure, not the full monitor: past ~80rem a table row is too long to read across.
+  max-inline-size: 80rem;
+  margin-inline: auto;
+  color: tokens.role('fg');
+}
+`;
+
+export const dashboardPageTest =
+  (): string => `// The dashboard renders per request, is gated by a policy, hydrates its one island, and stays
+// under its budget. Losing the policy is the interesting regression: the page still renders, to
+// anyone.
+import { expect, unitTest } from '@ultimat3/testing';
+import { config } from './page';
+
+unitTest('the dashboard renders on the server, is gated, and has an offline strategy', () => {
+  expect(config.render).toBe('ssr');
+  expect(config.policy?.permission).toBe('dashboard:read');
+  expect(config.offline).toBe('runtime');
+});
+
+unitTest('the dashboard hydrates its one island inside a stated budget', () => {
+  expect(config.hydrate).toBe('visible');
+  expect(config.budget.js).toBe('64kb');
+});
+`;

package/src/templates/scaffold-dashboard.ts

@@ -0,0 +1,27 @@
+// The generated dashboard — `apps/web/app/dashboard/` — moved out of `scaffold-app.ts` because it
+// stopped being an `<h1>` in a panel. Two shapes, one per `x new` invocation, and both show only
+// what is true of the app that was just written:
+//
+//   --example     the seeded `post` slice: a stat row, a bar chart of posts per day, the latest
+//                 posts in a table. Real rows from the app's own repo, aggregated by a pure view
+//                 module this file also emits.
+//   --no-example  no entity, so no rows to count and nothing honest to chart. Framework facts
+//                 instead — routes, locales, roles, version — and the route table. A chart of
+//                 invented numbers would teach the wrong thing to every app that starts here.
+//
+// One island on the page, the theme toggle (`scaffold-shell.ts`); the tiles, chart and table are
+// server markup, which is what keeps the route inside its 60kb budget.
+
+import type { GeneratedFile, NameSet } from './naming';
+import { bareDashboardFiles } from './scaffold-dashboard-bare';
+import { exampleDashboardFiles } from './scaffold-dashboard-example';
+import { DASHBOARD_DIR, dashboardPageTest, dashboardStyle } from './scaffold-dashboard-shared';
+
+/** `apps/web/app/dashboard/`, in the shape the invocation earns. */
+export function dashboardFiles(app: NameSet, example: boolean): readonly GeneratedFile[] {
+  return [
+    ...(example ? exampleDashboardFiles(app) : bareDashboardFiles(app)),
+    { path: `${DASHBOARD_DIR}/page.module.scss`, contents: dashboardStyle() },
+    { path: `${DASHBOARD_DIR}/page.test.ts`, contents: dashboardPageTest() },
+  ];
+}

package/src/templates/scaffold-errors.ts

@@ -0,0 +1,128 @@
+// The two error pages `x new` writes — `apps/web/site/errors/404.html` and `500.html`, the files
+// `packages/cli/src/error-pages.ts` serves verbatim for those statuses and the static export
+// carries as `404.html`. Self-contained documents by construction: a 500 is answered when the app's
+// own stylesheet may be the thing that failed, so nothing here links a bundle, loads a font or runs
+// a script. The `<style>` body is hashed into `style-src` at boot (`error-page-csp.ts`), which is
+// what lets the enforced policy a container sends admit it.
+
+import type { GeneratedFile, NameSet } from './naming';
+import { titleCase } from './naming';
+
+/**
+ * The same two hex values `app.config.ts`'s `pwa.colors` declares — one source, read by both
+ * templates, so the splash a browser paints before any stylesheet and the page it shows when the
+ * stylesheet never arrives agree. Raw hex is legal in these two places and nowhere else in an app:
+ * the raw-colour guard scans `.scss` (a page with no stylesheet has no token to read), and an
+ * install prompt has no stylesheet either.
+ */
+export const PWA_COLORS = {
+  themeColor: '#1b1f3b',
+  lightBackground: '#ffffff',
+  darkBackground: '#0b0d1a',
+} as const;
+
+/** One page per status, English only: the file is served as bytes, so no translator runs. */
+interface ErrorCopy {
+  readonly status: number;
+  readonly title: string;
+  readonly body: string;
+}
+
+const COPY: readonly ErrorCopy[] = [
+  {
+    status: 404,
+    title: 'Page not found',
+    body: 'There is nothing at this address. The link may be old, or the page may have moved.',
+  },
+  {
+    status: 500,
+    title: 'Something went wrong',
+    body: 'The server could not finish this request. It has been recorded; try again in a moment.',
+  },
+];
+
+/**
+ * `prefers-color-scheme` rather than `data-theme`: the theme boot script is inlined by the
+ * framework into documents it RENDERS, and this file is served as-is, so the OS preference is the
+ * only signal it has. The dark palette is the default and the light one is the media override,
+ * matching the `theme.defaultMode` the scaffold sets.
+ */
+const style = (): string => `
+      :root {
+        color-scheme: dark light;
+        --bg: ${PWA_COLORS.darkBackground};
+        --fg: #e6e8f0;
+        --muted: #9aa0b5;
+        --accent: #8b93ff;
+        --line: #262a45;
+      }
+      @media (prefers-color-scheme: light) {
+        :root {
+          --bg: ${PWA_COLORS.lightBackground};
+          --fg: ${PWA_COLORS.themeColor};
+          --muted: #5d6280;
+          --accent: #3b46d6;
+          --line: #dfe2ee;
+        }
+      }
+      * { box-sizing: border-box; margin: 0; }
+      html, body { min-height: 100%; }
+      body {
+        display: grid;
+        place-items: center;
+        padding: 2rem;
+        background: var(--bg);
+        color: var(--fg);
+        font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
+        line-height: 1.5;
+      }
+      main { max-width: 32rem; }
+      .status {
+        font-family: ui-monospace, 'SFMono-Regular', Menlo, monospace;
+        font-size: 0.75rem;
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+        color: var(--accent);
+      }
+      h1 { margin-top: 0.5rem; font-size: 2rem; font-weight: 600; letter-spacing: -0.02em; }
+      p { margin-top: 0.75rem; color: var(--muted); }
+      a {
+        display: inline-block;
+        margin-top: 1.5rem;
+        padding: 0.6rem 1rem;
+        border: 1px solid var(--line);
+        border-radius: 0.5rem;
+        color: var(--fg);
+        text-decoration: none;
+      }
+      a:hover { border-color: var(--accent); }
+      a:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+    `;
+
+const page = (app: NameSet, copy: ErrorCopy): string => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="robots" content="noindex">
+    <meta name="theme-color" content="${PWA_COLORS.themeColor}">
+    <title>${copy.title} · ${titleCase(app.raw)}</title>
+    <style>${style()}</style>
+  </head>
+  <body>
+    <main>
+      <p class="status">${String(copy.status)}</p>
+      <h1>${copy.title}</h1>
+      <p>${copy.body}</p>
+      <a href="/">Back to ${titleCase(app.raw)}</a>
+    </main>
+  </body>
+</html>
+`;
+
+/** `apps/web/site/errors/404.html` and `500.html`, in status order. */
+export const errorPageFiles = (app: NameSet): readonly GeneratedFile[] =>
+  COPY.map((copy) => ({
+    path: `apps/web/site/errors/${String(copy.status)}.html`,
+    contents: page(app, copy),
+  }));

package/src/templates/scaffold-i18n.ts

@@ -108,9 +108,55 @@ const i18nCatalog = (app: NameSet): string =>
   catalogJson({
     'site.home.title': app.pascal,
     'site.home.description': 'Everything you need, one command from shippable.',
+    'site.home.eyebrow': 'Built on Ultimate',
+    'site.home.headline': 'Ship the whole product, not a prototype.',
+    'site.home.lede':
+      'Typed routes, actions and queries, one authz system, budgets that fail the build, and a dark, designed shell — all from one command.',
     'site.home.cta': 'Open the dashboard',
+    'site.home.secondary': 'Open the admin',
+    'site.home.f1Title': 'One command to a running app',
+    'site.home.f1Body':
+      'bin/setup installs, migrates and seeds; bin/dev runs every role in one process.',
+    'site.home.f2Title': 'Policies, not flags',
+    'site.home.f2Body':
+      'Every route, action and query declares who may call it, and one system decides.',
+    'site.home.f3Title': 'Budgets that fail the build',
+    'site.home.f3Body':
+      'This page ships zero JavaScript, and the gate refuses the first byte over it.',
+    'shell.brand': app.pascal,
+    'shell.nav.dashboard': 'Dashboard',
+    'shell.nav.posts': 'Posts',
+    'shell.footer': 'Built with Ultimate',
     'app.dashboard.title': 'Dashboard',
     'app.dashboard.description': 'Your workspace.',
+    'app.dashboard.subtitle': 'What this app looks like from above.',
+    'app.dashboard.statTotal': 'Posts',
+    'app.dashboard.hintTotal': 'in the seeded org',
+    'app.dashboard.statWeek': 'Created this week',
+    'app.dashboard.hintVsPriorWeek': 'vs the week before',
+    'app.dashboard.statToday': 'Created today',
+    'app.dashboard.hintToday': 'so far, UTC',
+    'app.dashboard.chartTitle': 'Posts per day',
+    'app.dashboard.chartRange': 'Last 14 days, UTC',
+    'app.dashboard.chartLabel': 'Posts created per day over the last 14 days',
+    'app.dashboard.tableTitle': 'Latest posts',
+    'app.dashboard.tableCaption': 'The ten newest posts',
+    'app.dashboard.columnTitle': 'Title',
+    'app.dashboard.columnCreated': 'Created',
+    'app.dashboard.emptyTitle': 'No posts yet',
+    'app.dashboard.statRoutes': 'Routes',
+    'app.dashboard.hintRoutes': 'registered at boot',
+    'app.dashboard.statLocales': 'Locales',
+    'app.dashboard.hintLocales': 'in the catalog',
+    'app.dashboard.statRoles': 'Roles',
+    'app.dashboard.hintRoles': 'declared in shared/roles.ts',
+    'app.dashboard.statVersion': 'Ultimate',
+    'app.dashboard.hintVersion': 'framework version',
+    'app.dashboard.routesTitle': 'Route table',
+    'app.dashboard.routesCaption': 'Every route this app registers',
+    'app.dashboard.columnPath': 'Path',
+    'app.dashboard.columnSurface': 'Surface',
+    'app.dashboard.columnRender': 'Render',
     'app.offline.title': 'You are offline',
     'app.offline.description': 'This page will refresh itself when the connection returns.',
     'admin.home.title': 'Admin',

package/src/templates/scaffold-repo.ts

@@ -14,6 +14,7 @@ import { dbPackageFiles } from './scaffold-db-package';
 import { docsFiles } from './scaffold-docs';
 import { domainPackageFiles } from './scaffold-domain-package';
 import { envExampleSource, envSchemaSource } from './scaffold-env';
+import { PWA_COLORS } from './scaffold-errors';
 import { scaffoldGuardFiles } from './scaffold-guards';
 import { i18nFiles } from './scaffold-i18n';
 import { mcpPackageFiles } from './scaffold-mcp-package';
@@ -213,10 +214,14 @@ export const config = defineConfig({
     offline: { fallback: '/offline' },
     name: '${titleCase(app.raw)}',
     colors: {
-      light: { themeColor: '#1b1f3b', backgroundColor: '#ffffff' },
-      dark: { themeColor: '#1b1f3b', backgroundColor: '#0b0d1a' },
+      light: { themeColor: '${PWA_COLORS.themeColor}', backgroundColor: '${PWA_COLORS.lightBackground}' },
+      dark: { themeColor: '${PWA_COLORS.themeColor}', backgroundColor: '${PWA_COLORS.darkBackground}' },
     },
   },
+  // The theme a first visit opens in; the framework inlines the no-flash boot script that reads
+  // it, and a choice stored by the theme toggle wins over it on every later visit; 'system' follows
+  // the OS.
+  theme: { defaultMode: 'dark' },
   ai: { mcp: { expose: true, path: '/mcp' } },
 });
 `;