zz-meridian 0.30.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Bring ZZ Meridian, a dashboard design system, into a Next.js project, or start a new dashboard on it. Copies the files in; nothing depends on this package at runtime.",
   "license": "MIT",
   "type": "module",

package/payload/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 Every release of ZZ Meridian, newest first. Versions follow semver: a removed or renamed token, prop or card is major; a new card, token or variant is minor; a corrected value is a patch. Each entry says what breaks and what to do instead.
 
+## [0.31.0] · 2026-10-26
+
+### New
+
+- **`EmptyState` names its kind on its root: `data-empty="first-run"`, `"filtered"`, `"error"` or `"no-access"`.** Navigation readiness reads it (below), and a product's own empty state carries the same attribute to be read the same way.
+
+### Fixed
+
+- **A rail route that redirects to a page under it is followed there** ([#97](https://github.com/zhixuan312/zz-meridian/issues/97)). A rail item at `/things` whose page sends the person to `/things/<slug>` failed its journey with `still on /things/a … after pressing /things`, so the page the person actually opens was never measured. The press has now arrived once the address is the route or a page under it, the entry's `title`, data and control are that page's, and the line says `landed on /things/a`. A press that lands anywhere else says where: `pressing /things led to /elsewhere, which is neither /things nor a page under it`.
+  - An entry of `navigationChecks` for a path the rail does not draw now says why it is refused: a journey times a press on the rail's link, so it names the rail route a redirect starts from, and a page reached from a list belongs in `detailRoutes`. Checking such paths against the build's route list instead was declined: they would pass the check and then have no link to press.
+- **A list whose data arrived empty is not a page that never got ready** (#97). A list page with a row-link probe and no rows failed `interactive never-ready: the control … was not pressable in 10000 ms`. When the page draws its first-run `EmptyState` where the rows would be and nothing in `main` is still loading, that is its data, ready (the line says `data is the first-run state`), and the control it does not have is reported `interactive not measured: the page shows its first-run state (…)`, a warning and never a pass, as soon as the empty state shows rather than after the wait. The error state stays a failure, and its line now says `the page shows its error state`.
+- **A schema change behind a role that may not change the schema has a recipe** ([#98](https://github.com/zhixuan312/zz-meridian/issues/98)). `references/existing-project.md` told an adopter both to migrate on start and to ship the schema as a one-off file, which agrees only for a schema that never changes. It now names the two roads for every later migration: a `MIGRATION_DATABASE_URL` for the owner's role that the start-up migrator prefers, or a release step that migrates with the owner's role before the new version serves. The health route names a refused migration (`SQLSTATE 42501`) and the role that can run it.
+- **`brand --hex` keeps the step that fixed the accent.** Since 0.30.0 a brand colour whose white label failed contrast on its fill at first and passed one step darker was refused with the first step's failure, which no longer held: `zz-meridian brand --hex '#0E8A5F'` exited 1 with `the accent still fails contrast after 8 steps`. What `brand` reports now is the last contrast run's, and the eighth step's tokens are measured too.
+- **A live page is not read as not live because it was still hydrating.** `scripts/perf.ts` decided which rail routes register live data by sending one `online` event as each page loaded. A page that had not hydrated yet had no listener, the event was lost, and on a loaded runner a different route each week had no live route to start its after-live journey from (`no other rail route registers live data to start from`). The event is now sent again every 250 ms until a resync starts, and a route has 8 s to start one, not 4 s, so the probe costs up to 8 s for each rail route that is not live. The after-live journey uses the same rule.
+- **A dropped frame names the control whose gap it explains.** `scripts/vitals.ts` printed the last control that dropped a frame beside the cause of the longest gap, which another control had dropped.
+- **HTML that grew with the data has a reading** (#98). `references/validation.md` says how to tell a page's HTML growing with its database (`noLiveApi`) from growing with its code, and when re-recording the baseline is the answer.
+
+### Known issues
+
+- **Home and Revenue can drop a frame when the period changes to 7D on a slow phone.** At 7D the year is 52 windows, and Home draws them in two column charts and a trend: about a thousand new elements committed in one frame. On a quiet laptop at the emulated phone that frame's longest gap is 50 ms, the floor exactly (style and layout 36 ms); on the 4-CPU runner of the weekly run it is 67 to 83 ms (style and layout 62 to 69 ms), so the timed suite's vitals fail there. Making it cheaper is a decision about what a year draws at phone width, or about how a chart commits its marks, and is open for the next release.
+
 ## [0.30.0] · 2026-10-25
 
 ### Breaking

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "private": true,
   "license": "MIT",
   "description": "ZZ Meridian: a dashboard design system and starter. Six layers, from DTCG tokens through four layers of React components to product workspaces, and a Design Atlas, in a light and a dark theme.",

package/payload/scripts/brand.ts

@@ -132,20 +132,22 @@ if (hue !== undefined) {
 
   // Hold contrast: lower a theme's fill lightness where white text on it fails, a step at a time. A hue that still fails
   // after the last step stops the command: a brand that ships a failing pair in tokens.css is not a brand that worked.
+  // What remains is the last run's: a step that fixed the pair clears it (#0E8A5F passed after one step and was refused
+  // with the first step's failure), and the eighth step's tokens are measured too.
   const base = { light: 0.52, dark: 0.56 };
   let remaining: string[] = [];
-  for (let step = 0; step < 8; step++) {
+  for (let step = 0; step <= 8; step++) {
     execFileSync('node', ['scripts/tokens.ts'], { cwd: ROOT, stdio: 'ignore' });
     let out = '';
     let why = '';
-    try { out = execFileSync('node', ['scripts/contrast.ts'], { cwd: ROOT, encoding: 'utf8' }); break; }
+    try { out = execFileSync('node', ['scripts/contrast.ts'], { cwd: ROOT, encoding: 'utf8' }); remaining = []; break; }
     catch (e) { out = String((e as { stdout?: unknown }).stdout ?? ''); why = String((e as { stderr?: unknown }).stderr ?? '').trim(); }
     // A run with no summary did not measure anything: its exit code is a crash, and reading its empty output as "no
     // failures" passed a brand nobody had checked.
     if (!/^contrast: .*failures$/m.test(out)) throw new Error(`scripts/contrast.ts did not run to its summary: ${why || out.trim() || 'no output'}`);
-    const fails = out.split('\n').filter((l) => l.startsWith('FAIL') && l.includes(` ${id} `));
-    if (!fails.length) break;
-    remaining = fails;
+    remaining = out.split('\n').filter((l) => l.startsWith('FAIL') && l.includes(` ${id} `));
+    if (!remaining.length || step === 8) break;
+    const fails = remaining;
     const t = JSON.parse(read(tokenFile));
     for (const theme of ['light', 'dark'] as const) {
       if (!fails.some((l) => l.includes(`FAIL ${theme}`) && /on-accent on accent/.test(l))) continue;

package/payload/scripts/lib/coverage.ts

@@ -56,7 +56,9 @@ export function selectSmokeRoutes({ smokeRoutes, nav, landing }: { smokeRoutes?:
 
 function mappingErrors(check: NavigationCheck, routes: string[]): string[] {
   const errors: string[] = [];
-  if (!routes.includes(check.path)) errors.push(`${check.path}: navigation check names a path that is not a route`);
+  // A journey presses the rail's link to the route, so a path the rail does not draw has no press to time (#97). A rail route
+  // that redirects is followed under it; a page reached from a list is a detail route, pressed and walked by the others.
+  if (!routes.includes(check.path)) errors.push(`${check.path}: a navigation check names a rail route, and this is not one: a journey times a press on the rail's link to it. For a rail route that redirects to a page under it (/things to /things/a), name the rail route: the journey follows it there. A page reached from a list belongs in detailRoutes`);
   for (const key of ['title', 'readySelector', 'controlSelector', 'resultSelector'] as const) {
     if (typeof check[key] !== 'string' || !check[key].trim()) errors.push(`${check.path}: navigation check has an empty ${key}`);
   }

package/payload/scripts/lib/journey.ts

@@ -33,9 +33,17 @@ export class Fail extends Error {
   kind: Kind;
   constructor(kind: Kind, message: string) { super(message); this.kind = kind; }
 }
-export type Measured = { ms: number } | { fail: Fail };
-/** `prefetched`, on a journey through the workspace menu: how many prefetches of the destination the page made before the press. */
-export type Sample = { shell: Measured; data: Measured | null; interactive: Measured | null; drawerMs?: number; prefetchCapped: boolean; refused?: number; prefetched?: number };
+/** A time, a failure, or `absent`: nothing on the page to measure, and why (a first-run page has no row to press). */
+export type Measured = { ms: number } | { fail: Fail } | { absent: string };
+/**
+ * `prefetched`, on a journey through the workspace menu: how many prefetches of the destination the page made before the
+ * press. `landed`, when the press arrived under the route rather than at it (a rail route that redirects): where it did.
+ * `empty`, when the data was the page's first-run state rather than `readySelector`.
+ */
+export type Sample = { shell: Measured; data: Measured | null; interactive: Measured | null; drawerMs?: number; prefetchCapped: boolean; refused?: number; prefetched?: number; landed?: string; empty?: boolean };
+
+/** What a first-run EmptyState draws (`data-empty`): the data arrived and holds nothing yet (#97). */
+export const FIRST_RUN = '[data-empty="first-run"]';
 
 // ---- in the page ----
 
@@ -65,6 +73,9 @@ const INSTRUMENT = `${DEEP_SOURCE}\n${DEEP_MATCHES}\n(() => {
   const nav = window.__nav = { prefetches: [], spec: null, t0: undefined, res: {}, expect: null, snap: ${SNAP} };
   const KEY = '__nav_journey';
   try { const kept = JSON.parse(sessionStorage.getItem(KEY) ?? 'null'); if (kept) { nav.spec = kept.spec; nav.t0 = kept.t0; } } catch { /* a fresh journey */ }
+  // The press arrived: at the route, or under it for a route that redirects to a child (/things to /things/a, #97), once
+  // the address is no longer the start's.
+  nav.arrived = () => { const s = nav.spec, p = location.pathname; return !!s && (p === s.route || (p !== s.from && p.startsWith(s.route + '/'))); };
   nav.arm = (spec) => { nav.before = document.querySelector('h1')?.textContent.trim(); nav.spec = spec; nav.t0 = undefined; nav.res = {}; nav.expect = null; try { sessionStorage.setItem(KEY, JSON.stringify({ spec, t0: null })); } catch { /* kept in memory */ } };
   document.addEventListener('pointerdown', (e) => {
     if (!nav.spec || nav.t0 != null) return;
@@ -76,7 +87,7 @@ const INSTRUMENT = `${DEEP_SOURCE}\n${DEEP_MATCHES}\n(() => {
     if (s && nav.t0 != null) {
       const at = Math.max(0, Math.round(performance.timeOrigin + ts - nav.t0));
       const r = nav.res;
-      if (r.shell === undefined && location.pathname === s.route) {
+      if (r.shell === undefined && nav.arrived()) {
         const h = document.querySelector('h1');
         const text = h ? h.textContent.trim() : '';
         // Without a title, a heading that differs from the one on screen at the press is the target's.
@@ -87,7 +98,11 @@ const INSTRUMENT = `${DEEP_SOURCE}\n${DEEP_MATCHES}\n(() => {
         // Only what is on screen and real counts as the data. The router keeps routes it has shown mounted and hidden
         // (Cache Components: display none), so the previous page's rows are still in the document; and a loading.tsx
         // draws rows shaped like the real ones, which would hide the time React holds a shown fallback (300 ms or more).
-        if (s.ready && r.data === undefined && location.pathname === s.route && deepMatches(s.ready).some((el) => el.getClientRects().length > 0 && el.textContent.toLowerCase().includes(s.text) && !el.querySelector('.shimmer') && !el.closest('.shimmer, [aria-busy="true"]'))) r.data = at;
+        if (s.ready && r.data === undefined && nav.arrived() && deepMatches(s.ready).some((el) => el.getClientRects().length > 0 && el.textContent.toLowerCase().includes(s.text) && !el.querySelector('.shimmer') && !el.closest('.shimmer, [aria-busy="true"]'))) r.data = at;
+        // A page whose data arrived empty shows its first-run state instead of the rows: that is its data, ready. Only once
+        // nothing in main is still loading, so a side card's empty state cannot stand in for a table on its way.
+        else if (s.ready && r.data === undefined && nav.arrived() && deepMatches('${FIRST_RUN}').some((el) => el.getClientRects().length > 0)
+          && !Array.from(document.querySelectorAll('main .shimmer, main [aria-busy="true"]')).some((el) => el.getClientRects().length > 0)) { r.data = at; r.empty = true; }
         // A link probe leaves the route: its result is the address changing.
         if (nav.expect && r.interactive === undefined && nav.snap(nav.expect.selector) !== nav.expect.before) r.interactive = at;
       }
@@ -267,13 +282,20 @@ async function awaitPrefetch(page: Page, route: string): Promise<boolean> {
 const REFRESH_WAIT = 15_000;
 /** How long the router's read may take to start once the action has answered. */
 const REFRESH_START_WAIT = 3000;
+/** How often the `online` event is sent again while no resync has started: the provider may not be listening yet. */
+const ONLINE_EVERY = 250;
 
 /**
  * Resyncs the tab's live provider without writing anything: the provider listens for `online`, reads the collections again
  * through `refreshCollections` and then refreshes the router. Resolves only when an action started after the event answered
  * `{ ok: true }` and the router read that followed it has its whole body, and throws never-ready otherwise.
+ *
+ * The provider listens only once the page has hydrated and registered its collections, and an event sent before that is
+ * lost: on a loaded runner one sent at once made a live page read as not live, a different route each week. So the event is
+ * sent again every `ONLINE_EVERY` ms until a resync starts, for at most `startWait`; a page that starts none in that time
+ * is not live. A resync that started then has `REFRESH_WAIT` to answer.
  */
-export async function liveRefresh(page: Page, wait = REFRESH_WAIT): Promise<void> {
+export async function liveRefresh(page: Page, startWait = REFRESH_WAIT): Promise<void> {
   const state = `(() => { const n = window.__nav; return { started: n.act.started, results: n.act.results, arrivedAt: n.act.arrivedAt, inFlight: n.act.inFlight, reads: n.rsc.reads }; })()`;
   type State = { started: number; results: (boolean | null)[]; arrivedAt: number[]; inFlight: number; reads: { start: number; done: boolean }[] };
   // The provider's own opening resync may still be running; the refresh that counts starts after it.
@@ -281,15 +303,24 @@ export async function liveRefresh(page: Page, wait = REFRESH_WAIT): Promise<void
   if (quiet === null) throw new Fail('never-ready', `a live refresh was still running ${REFRESH_WAIT} ms after the page loaded`);
   await page.eval(`window.__nav.track = true`);
   const from = (await page.eval<State>(state)).started;
-  await page.eval(`window.dispatchEvent(new Event('online'))`);
+  let sent = 0;
+  const begun = await poll(async () => {
+    if ((await page.eval<State>(state)).started > from) return true;
+    if (Date.now() - sent >= ONLINE_EVERY) { sent = Date.now(); await page.eval(`window.dispatchEvent(new Event('online'))`); }
+    return false;
+  }, Date.now() + startWait);
+  if (!begun) {
+    await page.eval(`window.__nav.track = false`);
+    throw new Fail('never-ready', `no refresh action started within ${startWait} ms of sending the page online events (is the starting page live?)`);
+  }
   const verified = await poll(async () => {
     const v = await page.eval<State>(state);
     const at = v.results.findIndex((r, i) => i >= from && r === true);
     return at >= 0 && v.inFlight === 0 ? { arrivedAt: v.arrivedAt[at] } : false;
-  }, Date.now() + wait);
+  }, Date.now() + REFRESH_WAIT);
   if (!verified) {
     await page.eval(`window.__nav.track = false`);
-    throw new Fail('never-ready', `no refresh action answered { ok: true } within ${wait} ms of the page's online event (is the starting page live?)`);
+    throw new Fail('never-ready', `no refresh action answered { ok: true } within ${REFRESH_WAIT} ms of starting (is the starting page live?)`);
   }
   // The router's read is the first one to begin after the answer; it is finished when its whole body is in.
   const refreshed = await poll(async () => {
@@ -408,17 +439,20 @@ export async function journey(page: Page, device: Device, start: string, route:
     const reached = await page.eval<string[]>(`performance.getEntriesByType('resource').filter((e) => new URL(e.name).pathname === ${JSON.stringify(route)}).map((e) => e.name)`);
     if (reached.length) throw new Fail('prefetched', `${reached.length} request(s) for ${route} had already been made before the press (${reached[0]})`);
   }
-  const spec = { route, title: check?.title ?? '', ready: check?.readySelector ?? '', text: (check?.readyText ?? '').toLowerCase() };
+  const spec = { route, from: start, title: check?.title ?? '', ready: check?.readySelector ?? '', text: (check?.readyText ?? '').toLowerCase() };
   await page.eval(`window.__nav.arm(${JSON.stringify(spec)})`);
   const t0 = await press(page, at);
 
   // The shell: the path and the target heading.
   const shellMs = await result(page, 'shell', t0 + cap);
   if (shellMs === null) {
-    const now = await page.eval<{ p: string; h: string }>(`({ p: location.pathname, h: document.querySelector('h1')?.textContent.trim() ?? '' })`);
-    const wrong = now.p === route;
+    const now = await page.eval<{ p: string; h: string; there: boolean }>(`({ p: location.pathname, h: document.querySelector('h1')?.textContent.trim() ?? '', there: window.__nav.arrived() })`);
+    // A press that left for an address neither the route nor under it says where it went: a redirect the journey cannot follow.
+    const why = now.there ? `${now.p} shows the heading "${now.h}", not "${check?.title}"`
+      : now.p === start ? `still on ${now.p} ${cap} ms after pressing ${route}`
+      : `pressing ${route} led to ${now.p}, which is neither ${route} nor a page under it`;
     return {
-      shell: { fail: new Fail(wrong ? 'wrong-result' : 'never-ready', wrong ? `${route} shows the heading "${now.h}", not "${check?.title}"` : `still on ${now.p} ${cap} ms after pressing ${route}`) },
+      shell: { fail: new Fail(now.there ? 'wrong-result' : 'never-ready', why) },
       data: check ? { fail: new Fail('never-ready', 'the shell was never reached') } : null,
       interactive: check ? { fail: new Fail('never-ready', 'the shell was never reached') } : null,
       drawerMs,
@@ -428,7 +462,9 @@ export async function journey(page: Page, device: Device, start: string, route:
     };
   }
   const shell = { ms: shellMs };
-  if (!check) return { shell, data: null, interactive: null, drawerMs, prefetchCapped, refused, prefetched };
+  const where = await page.eval<string>('location.pathname');
+  const landed = where === route ? undefined : where;
+  if (!check) return { shell, data: null, interactive: null, drawerMs, prefetchCapped, refused, prefetched, landed };
 
   // Data and interaction run side by side: a control that is there at once does not wait for a body that is not. A link probe
   // is the exception: its press leaves the route, and the data counts only on the route, so it is pressed once the data is
@@ -439,8 +475,9 @@ export async function journey(page: Page, device: Device, start: string, route:
     data = await measureData(page, route, check, t0, cap);
     interactive = await measureInteraction(page, route, check, t0, cap, RESULT_WAIT[device]);
   } else [data, interactive] = await Promise.all([measureData(page, route, check, t0, cap), measureInteraction(page, route, check, t0, cap, RESULT_WAIT[device])]);
+  const empty = await page.eval<boolean>('window.__nav.res.empty === true');
   if (check.probe === 'dialog') await page.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Escape', code: 'Escape', windowsVirtualKeyCode: 27 });
-  return { shell, data, interactive, drawerMs, prefetchCapped, refused, prefetched };
+  return { shell, data, interactive, drawerMs, prefetchCapped, refused, prefetched, landed, empty };
 }
 
 /** The page's own time for `name`, in ms since the press, once it has one; null when `until` (a clock time) passes first. */
@@ -451,7 +488,9 @@ async function measureData(page: Page, route: string, check: NavigationCheck, t0
   const ms = await result(page, 'data', t0 + cap);
   if (ms !== null) return { ms };
   const there = await page.eval<boolean>(`!!deepQuery(${JSON.stringify(check.readySelector)})`);
-  return { fail: new Fail(there ? 'wrong-result' : 'never-ready', there ? `${check.readySelector} is there but never shows "${check.readyText}"` : `${check.readySelector} did not appear in ${cap} ms`) };
+  // The data failing to load is a failure whichever state the page draws for it; the error state says so on the line.
+  const failed = !there && (await page.eval<boolean>(`!!document.querySelector('[data-empty="error"]')`));
+  return { fail: new Fail(there ? 'wrong-result' : 'never-ready', there ? `${check.readySelector} is there but never shows "${check.readyText}"` : `${check.readySelector} did not appear in ${cap} ms${failed ? '; the page shows its error state' : ''}`) };
 }
 
 /** Selectors already reported, so a note appears once per run, not once per sample. */
@@ -465,7 +504,16 @@ async function noteIfSeveral(page: Page, selector: string): Promise<void> {
 }
 
 async function measureInteraction(page: Page, route: string, check: NavigationCheck, t0: number, cap: number, wait: number): Promise<Measured> {
-  const where = await poll(async () => (await page.eval<boolean>(`location.pathname === ${JSON.stringify(route)}`)) && point(page, check.controlSelector), t0 + cap);
+  // The control, or a page whose data arrived empty: a first-run page has no row to press, which is not a page that never got
+  // ready (#97). It is reported as not measured, never as a pass, and only once the data is there.
+  const found = await poll(async () => {
+    if (!(await page.eval<boolean>('window.__nav.arrived()'))) return null;
+    const at = await point(page, check.controlSelector);
+    if (at) return at;
+    return (await page.eval<boolean>('window.__nav.res.empty === true')) ? 'empty' : null;
+  }, t0 + cap);
+  if (found === 'empty') return { absent: `not measured: the page shows its first-run state (${FIRST_RUN}), so it has no ${check.controlSelector} to press` };
+  const where = found;
   if (!where) return { fail: new Fail('never-ready', `the control ${check.controlSelector} was not pressable in ${cap} ms`) };
   await noteIfSeveral(page, check.controlSelector);
   const isInput = await page.eval<boolean>(`(() => { const el = ${pickable(check.controlSelector)}; return !!el && el.tagName === 'INPUT' && ['text', 'search'].includes(el.type); })()`);

package/payload/scripts/navigate.ts

@@ -82,6 +82,10 @@ type Line = {
   workspace?: string;
   /** Through the menu: how many prefetches of the destination the starting page had made before the press. */
   prefetched?: number;
+  /** Where the press arrived, when it was under the route rather than at it. */
+  landed?: string;
+  /** The data was the page's first-run state, not `readySelector`. */
+  empty?: boolean;
 };
 
 const value = (m: Measured | null): number | null => (m && 'ms' in m ? m.ms : null);
@@ -96,13 +100,16 @@ async function measure(page: Page, device: Device, start: From, route: string, c
     if ('fail' in m) {
       line[name] = { ms: null, limit: limits[name], verdict: 'fail', reason: `${m.fail.kind}: ${m.fail.message}` };
       line.problems.push(`${name} ${m.fail.kind}: ${m.fail.message}`);
-    } else line[name] = { ms: m.ms, limit: limits[name], verdict: 'pass' };
+    } else if ('absent' in m) line[name] = { ms: null, verdict: 'not-configured', reason: m.absent };
+    else line[name] = { ms: m.ms, limit: limits[name], verdict: 'pass' };
   };
   const run = { origin: base, condition: 'warm' as const, menu: start.menu };
   const first = await journey(page, device, start.from, route, check, run);
   line.drawerMs = first.drawerMs;
   line.prefetchCapped = first.prefetchCapped;
   line.prefetched = first.prefetched;
+  line.landed = first.landed;
+  line.empty = first.empty;
   for (const name of METRICS) fill(name, first[name]);
   // A wrong result, a never-ready page or a dead control is the answer: no retake can replace it.
   if (line.problems.length || timing === 'off') return finish(line);
@@ -138,6 +145,9 @@ const cell = (r: Reported): string => (r.verdict === 'not-configured' ? 'not-con
 const text = (l: Line): string =>
   `${l.status.padEnd(7)} ${l.route} ${l.device} shell ${cell(l.shell)} · data ${cell(l.data)} · interactive ${cell(l.interactive)}`
   + (l.noisy ? ' · noisy' : '')
+  + (l.landed ? ` · landed on ${l.landed}` : '')
+  + (l.empty ? ' · data is the first-run state' : '')
+  + METRICS.flatMap((name) => (l[name].verdict === 'not-configured' && l[name].reason ? [` · ${name} ${l[name].reason}`] : [])).join('')
   + (l.prefetchCapped ? ` · prefetch not idle after ${PREFETCH_WAIT / 1000} s` : '')
   + (l.drawerMs !== undefined ? ` · drawer ${l.drawerMs} ms` : '')
   + (l.via === 'menu' ? ` · through the workspace menu (${l.workspace})` : '')
@@ -309,7 +319,7 @@ async function main(): Promise<number> {
     status,
     routes,
     warnings: coverage.warnings,
-    lines: lines.map(({ route, device, status: s, shell, data, interactive, drawerMs, prefetchCapped, noisy, problems: p, via, workspace, prefetched }) => ({ route, device, status: s, via, workspace, prefetched, shell, data, interactive, drawerMs, prefetchCapped, noisy, problems: p })),
+    lines: lines.map(({ route, device, status: s, shell, data, interactive, drawerMs, prefetchCapped, noisy, problems: p, via, workspace, prefetched, landed, empty }) => ({ route, device, status: s, via, workspace, prefetched, landed, empty, shell, data, interactive, drawerMs, prefetchCapped, noisy, problems: p })),
     prefetch: prefetch && { ...prefetch, problems },
   });
   return failed ? 1 : 0;

package/payload/scripts/perf.ts

@@ -50,8 +50,8 @@ const args = process.argv.slice(2);
 const opt = (k: string) => { const i = args.indexOf(k); return i >= 0 ? args[i + 1] : undefined; };
 const base = (opt('--base') ?? process.env.BASE ?? 'http://localhost:3000').replace(/\/$/, '');
 const PROTOCOL_SAMPLES = 20;
-/** How long a rail route has to answer a live resync before it is called not live. */
-const PROBE_WAIT = 4000;
+/** How long a rail route has to start a live resync, while it is sent online events, before it is called not live. */
+const PROBE_WAIT = 8000;
 const CONDITIONS: Condition[] = ['warm', 'cold', 'afterLive'];
 const started = Date.now();
 
@@ -219,7 +219,7 @@ async function main(): Promise<number> {
               for (const name of METRICS) {
                 const m = sample[name];
                 if (m && 'fail' in m) problems.push(`sample ${i + 1} ${name} ${m.fail.kind}: ${m.fail.message}`);
-                else if (m) series[name].push(m.ms);
+                else if (m && 'ms' in m) series[name].push(m.ms);
               }
             } catch (e) {
               // The tab may be in any state after an error that is not a verdict: start the shared one again.

package/payload/scripts/verify.config.ts

@@ -7,7 +7,10 @@ type DeviceBudget = { desktop: number; phone: number };
 type ReadinessBudget = { shellMs: DeviceBudget; dataMs: DeviceBudget; interactiveMs: DeviceBudget };
 /** What "this route is ready" means, and one harmless control to press on it. */
 type NavigationCheck = {
-  /** The rail route this describes. */
+  /**
+   * The rail route this describes. A rail route that redirects to a page under it (`/things` to `/things/<slug>`) is
+   * followed there, and `title`, `readySelector` and the control are the page it lands on's.
+   */
   path: string;
   /** Text the page's heading shows as soon as the shell has arrived. */
   title: string;

package/payload/scripts/vitals.ts

@@ -114,10 +114,11 @@ async function measure(route: string): Promise<Measured> {
     const here = gaps.filter((f) => f > 50).length;
     frames += gaps.length;
     dropped += here;
+    // The control a line names is the one whose gap it explains: naming the last tap that dropped beside the worst gap's
+    // cause sent a reader to the drawer for a frame the period select had dropped.
     if (here) {
-      droppedBy = name;
       const gap = Math.max(...gaps);
-      if (gap > worst) { worst = gap; cause = frameCause(Math.round(gap), loafs.map(loafOf)); }
+      if (gap > worst) { worst = gap; droppedBy = name; cause = frameCause(Math.round(gap), loafs.map(loafOf)); }
     }
     // Close whatever the tap opened; its own events and its own frames are not counted.
     await page.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Escape', code: 'Escape', windowsVirtualKeyCode: 27 });

package/payload/skills/zz-meridian/references/existing-project.md

@@ -210,8 +210,20 @@ Meridian's sample serves fixtures; a product's collections read a database. What
   migrator's bookkeeping in a schema the role may write (`public`); never stop the server on a failure, and report the
   outcome at a health route so a deploy can read it. A build has no database to migrate and must not need one.
 - **A role that may read and write but not create.** Deployed roles often lack `CREATE`, and a migrator that starts with
-  `CREATE SCHEMA` is refused even where tables may be created. Ship the schema as a one-off SQL file a person with the
-  owner's role runs once, and let the application role only migrate within what it may do.
+  `CREATE SCHEMA` is refused even where tables may be created. The first schema can ship as a one-off SQL file a person
+  with the owner's role runs once, but that settles only a schema that never changes: every later migration that adds a
+  table or a column is refused to the application role on each start, rolls back, and the server keeps serving the old
+  schema (issue #98). A release with a schema change takes one of two roads, and the project says which in its README:
+  - **A migration role the start-up migrator prefers.** Give the deployment a second connection string,
+    `MIGRATION_DATABASE_URL`, for a role that owns the schema, on the direct endpoint (not the transaction pooler). The
+    migrator in `instrumentation.ts` connects with it when it is set and with the application's otherwise; the pages
+    never read it. This suits a host that may hold the owner's credential.
+  - **A release step before the new version serves.** Where the running app must not hold the owner's credential, the
+    release runs the product's own migrate command with the owner's role, then switches traffic to the
+    new version. The start-up migrator then finds nothing pending.
+  Either way, read the health route after the deploy, and have it name the cause: a migration refused for permission
+  (Postgres `SQLSTATE 42501`, `insufficient_privilege`) reports which migration and says "the application role may not
+  change the schema: run the pending migrations with the owner's role", not a bare failure.
 
 ## Route A2: a static HTML page (data fetched as JSON)
 

package/payload/skills/zz-meridian/references/validation.md

@@ -39,7 +39,15 @@ line naming the command that runs them. Steps in order:
    a page is followed. A workspace's home that no other route's rail links to (the only destination of its workspace) is
    reached through the workspace menu: from the nearest rail route before it, by the menu's item for its workspace, from
    that press, and its line says `through the workspace menu (<workspace>)`. Any other destination no rail links to is
-   reported as a problem, never as a pass.
+   reported as a problem, never as a pass. A `navigationChecks` entry names a rail route, since the journey presses the
+   rail's link to it. A rail route that redirects to a page under it (`/things` to `/things/<slug>` for the person
+   signed in) is followed there: the press has arrived once the address is the route or under it, the entry's `title`
+   is the page it lands on, and the line says `landed on <path>`. A page reached from a list is not a rail route: name
+   it in `detailRoutes`, where the audit, the presses, the keyboard walk and the vitals open it. A page whose data arrived empty
+   draws its first-run `EmptyState` (`data-empty="first-run"`) where the rows would be: once nothing in `main` is still
+   loading, that is its data, ready, the line says `data is the first-run state`, and a
+   control the empty page does not have is reported `interactive not measured: the page shows its first-run state`, a
+   warning and never a pass. The error state (`data-empty="error"`) stays a failure.
 1. **The gate** (`node scripts/gate.ts`): tokens regenerate to the same CSS; the card registry is fresh; every card and
    page specification follows the anatomy; the product's own rules in `optional:scripts/check.local.ts`, when the file exists;
    contrast holds for every pair in every theme and accent, and the chart palette passes the colour-vision checks;
@@ -156,7 +164,7 @@ and supply-chain check before a script runs; that is pnpm, not an install, and n
 
 ## Lines that are not about the page
 
-Two lines say something about what the suites could see, not about a defect in a page's own styles.
+Three lines are not about a defect in a page's own styles: two say what the suites could see, and one what the data did.
 
 - **`unmeasured: <element> (no open shadow root|not defined)`** is the audit saying it did not measure that element, and
   it fails like any other finding so that a custom element is never passed unseen. The fix is in the element, as in the
@@ -168,6 +176,14 @@ Two lines say something about what the suites could see, not about a defect in a
   control you meant, write a more specific selector. A descendant combinator does not cross a shadow boundary, so name an
   element inside a root with a selector written for that root.
 
+- **`<route>: HTML grew <n>% over its baseline (cap 5%)`** with no change to the code means the page renders data that
+  changed. Under a `fakeApi` the data is fixed and the figure measures code; a project whose pages read its own
+  database (`noLiveApi`) measures whatever rows the database held at the build. Tell the two apart by building the
+  commit the baseline was recorded on against the same data: when it grows by the same amount, the growth is the
+  data's. Then re-record with `node scripts/sizes.ts --write-baseline --base <url>` and say in the commit that the data
+  moved; the lasting fix is a fixed data set for verify (a seeded database), so the figure measures code again. Growth
+  the old commit does not show is the code's, and is fixed in the page.
+
 ## Asking the agent's questions: `scripts/ask.ts`
 
 verify proves the assistant works with a stand-in model; it cannot say whether the real model answers a page's own

package/payload/src/components/ui/empty-state/README.md

@@ -54,6 +54,7 @@ When an agent's query finds nothing, the view shows the filtered state with the
 
 - The error kind is `role="alert"`.
 - No access is not an alert: nothing failed. Its root carries `data-no-access`, and the title and sentence carry the meaning.
+- Every kind's root carries `data-empty` with its kind. `pnpm verify`'s navigation journey reads `data-empty="first-run"` as data that arrived empty, and `data-empty="error"` as data that failed, so an empty list is not reported as a page that never got ready. A product's own empty state carries the same attribute.
 - The disc is decorative; the title carries the meaning.
 - Title `ink` on `surface` 18.5:1; sentence `ink-2` 7.1:1 (light, cobalt).
 

package/payload/src/components/ui/empty-state/index.tsx

@@ -60,7 +60,7 @@ export function EmptyState({
   );
   if (layout === 'inline')
     return (
-      <div data-no-access={kind === 'no-access' ? '' : undefined} role={kind === 'error' ? 'alert' : undefined} className={cn('flex items-center gap-3.5 py-2', className)}>
+      <div data-empty={kind} data-no-access={kind === 'no-access' ? '' : undefined} role={kind === 'error' ? 'alert' : undefined} className={cn('flex items-center gap-3.5 py-2', className)}>
         {disc}
         <div className="min-w-0 flex-1">
           <p className="text-sm font-medium text-ink">{title}</p>
@@ -70,7 +70,7 @@ export function EmptyState({
       </div>
     );
   return (
-    <div data-no-access={kind === 'no-access' ? '' : undefined} role={kind === 'error' ? 'alert' : undefined} className={cn('flex flex-col items-center px-6 py-14 text-center', className)}>
+    <div data-empty={kind} data-no-access={kind === 'no-access' ? '' : undefined} role={kind === 'error' ? 'alert' : undefined} className={cn('flex flex-col items-center px-6 py-14 text-center', className)}>
       {art && !icon ? <span aria-hidden className="grid place-items-center">{art}</span> : disc}
       <p className={cn('t-card max-w-sm text-balance', art && !icon ? 'mt-5' : 'mt-8')}>{title}</p>
       {children ? <p className="t-small mt-1.5 max-w-sm text-pretty text-ink-2">{children}</p> : null}