@ultimat3/cli 20.1.6 → 20.2.1

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

@@ -0,0 +1,182 @@
+// The `--no-example` dashboard: framework facts and the route table, and no chart — there is no
+// series to draw until the first `x g resource`, and a chart of invented numbers would be the first
+// lie in the app. The route declaration and the 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 barePage = (
+  app: NameSet,
+): string => `// The authed dashboard of an app with no entity yet. Nothing here is invented: the tiles are the
+// framework's own registries — routes, locales, roles, version — and the table is the route table
+// \`x routes\` prints. NO CHART, deliberately: there is no series to draw until the first
+// \`x g resource\`, and a chart of made-up numbers would be the first lie in the app.
+//
+// \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
+${sortedImports([
+  `import { catalogs, useT } from '@${app.kebab}/i18n';`,
+  "import { frameworkVersion } from '@ultimat3/core';",
+  "import { currentLocale } from '@ultimat3/i18n';",
+  "import { defineRoute, island, routeEntries } from '@ultimat3/render';",
+  "import { DataTable, Grid, PageHeader, Section, StatTile, ThemeToggle } from '@ultimat3/ui';",
+])}
+import { roles } from '../../shared/roles';
+import { Shell } from '../../shared/shell';
+import { factsOf, formatCount, type RouteRow, routeRows } from './dashboard-view';
+import styles from './page.module.scss';
+
+${themeIsland}
+
+${routeConfig('')}
+
+export function DashboardPage() {
+  const t = useT();
+  const locale = currentLocale();
+  // Read at render, not at import: the registries are filled by the boot scan, after this module.
+  const entries = routeEntries();
+  const facts = factsOf({
+    routes: entries.length,
+    locales: catalogs.locales.length,
+    roles: Object.keys(roles).length,
+    version: frameworkVersion(),
+  });
+  const rows = routeRows(entries);
+
+  return (
+    <Shell
+      nav="dashboard"
+      actions={
+        ${themeActions}
+      }
+    >
+      <div class={styles.page}>
+        <PageHeader title={t('app.dashboard.title')} description={t('app.dashboard.subtitle')} />
+        {/* 12rem, not the catalog's 16rem default: four tiles pair up two-by-two on a tablet's main
+            column and sit in one row on a desktop, never three and an orphan. */}
+        <Grid minColumn="12rem">
+          <StatTile
+            stat="routes"
+            label={t('app.dashboard.statRoutes')}
+            value={formatCount(facts.routes, locale)}
+            hint={t('app.dashboard.hintRoutes')}
+          />
+          <StatTile
+            stat="locales"
+            label={t('app.dashboard.statLocales')}
+            value={formatCount(facts.locales, locale)}
+            hint={t('app.dashboard.hintLocales')}
+          />
+          <StatTile
+            stat="roles"
+            label={t('app.dashboard.statRoles')}
+            value={formatCount(facts.roles, locale)}
+            hint={t('app.dashboard.hintRoles')}
+          />
+          <StatTile
+            stat="version"
+            label={t('app.dashboard.statVersion')}
+            value={facts.version}
+            hint={t('app.dashboard.hintVersion')}
+          />
+        </Grid>
+        <Section title={t('app.dashboard.routesTitle')}>
+          <DataTable
+            caption={t('app.dashboard.routesCaption')}
+            rowKey={(row: RouteRow) => row.path}
+            rows={rows}
+            columns={[
+              { key: 'path', header: t('app.dashboard.columnPath'), cell: (row) => row.path },
+              {
+                key: 'surface',
+                header: t('app.dashboard.columnSurface'),
+                cell: (row) => row.surface,
+              },
+              { key: 'render', header: t('app.dashboard.columnRender'), cell: (row) => row.render },
+            ]}
+          />
+        </Section>
+      </div>
+    </Shell>
+  );
+}
+`;
+
+const bareView =
+  (): string => `// The dashboard's facts, apart from its markup: pure projections of what the framework registered,
+// so the page and a test read the same shape. No I/O, no \`t()\`, no JSX.
+
+/** The three columns of the route table, as \`x routes\` prints them. */
+export interface RouteRow {
+  readonly path: string;
+  readonly surface: string;
+  readonly render: string;
+}
+
+/** What \`routeEntries()\` hands over, narrowed to the fields the table reads. */
+export interface RouteLike {
+  readonly path: string;
+  readonly surface: string;
+  readonly config: { readonly render: string };
+}
+
+/** Sorted by path in code-unit order — the order \`x routes\` and the manifest both use. */
+export const routeRows = (entries: readonly RouteLike[]): readonly RouteRow[] =>
+  entries
+    .map((entry) => ({ path: entry.path, surface: entry.surface, render: entry.config.render }))
+    .toSorted((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+
+export interface FrameworkFacts {
+  readonly routes: number;
+  readonly locales: number;
+  readonly roles: number;
+  readonly version: string;
+}
+
+/** Counts are never negative, and a blank version is reported as unknown rather than as nothing. */
+export const factsOf = (input: FrameworkFacts): FrameworkFacts => ({
+  routes: Math.max(0, input.routes),
+  locales: Math.max(0, input.locales),
+  roles: Math.max(0, input.roles),
+  version: input.version === '' ? 'unknown' : input.version,
+});
+
+/** 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 bareViewTest = (): string => `// The route table and the fact tiles, pinned on fixed input.
+import { expect, unitTest } from '@ultimat3/testing';
+import { factsOf, formatCount, routeRows } from './dashboard-view';
+
+unitTest('routeRows projects the three columns and sorts by path', () => {
+  const rows = routeRows([
+    { path: '/dashboard', surface: 'app', config: { render: 'ssr' } },
+    { path: '/', surface: 'site', config: { render: 'static' } },
+  ]);
+  expect(rows.map((row) => row.path)).toEqual(['/', '/dashboard']);
+  expect(rows[1]).toEqual({ path: '/dashboard', surface: 'app', render: 'ssr' });
+});
+
+unitTest('factsOf clamps counts and names an unknown version', () => {
+  const facts = factsOf({ routes: -1, locales: 1, roles: 2, version: '' });
+  expect(facts).toEqual({ routes: 0, locales: 1, roles: 2, version: 'unknown' });
+  expect(factsOf({ routes: 3, locales: 1, roles: 2, version: '1.2.3' }).version).toBe('1.2.3');
+});
+
+unitTest('formatCount follows the locale', () => {
+  expect(formatCount(1234, 'en')).toBe('1,234');
+  expect(formatCount(1234, 'de')).toBe('1.234');
+});
+`;
+
+/** The bare dashboard's page, view module and view test. */
+export const bareDashboardFiles = (app: NameSet): readonly GeneratedFile[] => [
+  { path: `${DASHBOARD_DIR}/page.tsx`, contents: barePage(app) },
+  { path: `${DASHBOARD_DIR}/dashboard-view.ts`, contents: bareView() },
+  { path: `${DASHBOARD_DIR}/dashboard-view.test.ts`, contents: bareViewTest() },
+];

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,77 @@
+// 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 34.0kb minified under Bun 1.4.0 (37.0kb under 1.4.2, which honours
+  // \`sideEffects\` and keeps core's declared modules) — solid-js is 15.1kb of it, the catalog's
+  // toggle, provider, the ui runtime they share and the error registry are the rest. It was
+  // 60.9kb before the framework stopped shipping solid-js twice and the i18n catalog with it
+  // (issue #490), which is what put this at 64kb; 60kb is the figure the scaffold budgets held
+  // before that, kept rather than tightened so a Bun patch cannot red a first \`bin/check\`.
+  budget: { js: '60kb' },${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('60kb');
+});
+`;

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() },
+  ];
+}