zz-meridian 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.23.0",
+  "version": "0.24.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,12 @@
 
 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.24.0] · 2026-10-20
+
+### New
+
+- **First-load JS can be held to each route's baseline alone** ([#76](https://github.com/zhixuan312/zz-meridian/issues/76)), as every page's HTML is since 0.19.0. Set `budgets.firstLoadKb: null` in `scripts/verify.config.ts`: a route `scripts/verify.baseline.json` holds is then held to `firstLoadGrowthPct` over its own figure and nothing else, and the 820 KiB cap binds only a route the baseline does not hold yet. A product whose largest page sits near the cap no longer fails `pnpm verify` for a change its own baseline allows, and no longer derives a cap from the baseline to say the same rule twice. Leaving the key out keeps the cap on every route, as before; the size line says which applies (`cap 820 KiB for a route the baseline does not hold`).
+
 ## [0.23.0] · 2026-10-20
 
 ### New

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.23.0",
+  "version": "0.24.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/lib/budgets.ts

@@ -24,7 +24,8 @@ export type NavigationCheck = {
 };
 export type Budgets = {
   navigation: { warm: ReadinessBudget; cold: ReadinessBudget; afterLive: ReadinessBudget };
-  firstLoadKb: number;
+  /** `null`: each route the baseline holds is held to it alone, and the default cap binds only a route it does not. */
+  firstLoadKb: number | null;
   firstLoadGrowthPct: number;
   htmlGrowthPct: number;
   htmlKb: Record<string, number>;
@@ -33,7 +34,7 @@ export type Budgets = {
 export type BudgetsConfig = {
   budgets?: {
     navigation?: { warm?: ReadinessBudget; cold?: ReadinessBudget; afterLive?: ReadinessBudget };
-    firstLoadKb?: number;
+    firstLoadKb?: number | null;
     firstLoadGrowthPct?: number;
     htmlGrowthPct?: number;
     htmlKb?: Record<string, number>;
@@ -47,6 +48,9 @@ const COLD: ReadinessBudget = {
   interactiveMs: { desktop: 2000, phone: 4000 },
 };
 
+/** The first-load cap, in KiB, for a route the baseline does not hold, and for every route unless `firstLoadKb` is null. */
+export const FIRST_LOAD_CAP_KB = 820;
+
 /** Each page's HTML is held to its own baseline; an absolute HTML cap is a project's route, so the defaults set none. */
 export const DEFAULT_BUDGETS: Budgets = {
   navigation: {
@@ -58,7 +62,7 @@ export const DEFAULT_BUDGETS: Budgets = {
     cold: COLD,
     afterLive: COLD,
   },
-  firstLoadKb: 820,
+  firstLoadKb: FIRST_LOAD_CAP_KB,
   firstLoadGrowthPct: 5,
   htmlGrowthPct: 5,
   htmlKb: {},
@@ -92,7 +96,7 @@ export function budgetsOf(config: BudgetsConfig): Budgets {
   const cold = b.navigation?.cold ?? DEFAULT_BUDGETS.navigation.cold;
   return {
     navigation: { warm, cold, afterLive: b.navigation?.afterLive ?? cold },
-    firstLoadKb: b.firstLoadKb ?? DEFAULT_BUDGETS.firstLoadKb,
+    firstLoadKb: b.firstLoadKb === null ? null : b.firstLoadKb ?? DEFAULT_BUDGETS.firstLoadKb,
     firstLoadGrowthPct: b.firstLoadGrowthPct ?? DEFAULT_BUDGETS.firstLoadGrowthPct,
     htmlGrowthPct: b.htmlGrowthPct ?? DEFAULT_BUDGETS.htmlGrowthPct,
     htmlKb: b.htmlKb ?? DEFAULT_BUDGETS.htmlKb,

package/payload/scripts/lib/sizes.ts

@@ -19,16 +19,20 @@ export function firstLoad(
   });
 }
 
-/** Routes over the cap or past their growth allowance over a baseline; without a baseline growth is not configured. */
+/**
+ * Routes over the cap or past their growth allowance over a baseline; without a baseline growth is not configured.
+ * `capUnheldOnly` holds a route the baseline holds to its baseline alone, so the cap binds only a route it does not.
+ */
 export function firstLoadProblems(
   routes: { route: string; bytes: number }[],
-  { capKiB, growthPct, baseline }: { capKiB: number; growthPct: number; baseline: Record<string, number> | null },
+  { capKiB, growthPct, baseline, capUnheldOnly = false }: { capKiB: number; growthPct: number; baseline: Record<string, number> | null; capUnheldOnly?: boolean },
 ): { problems: string[]; growth: 'checked' | 'not-configured' } {
   const problems: string[] = [];
   for (const { route, bytes } of routes) {
-    if (bytes > capKiB * KIB) problems.push(`${route}: first-load JS ${kib(bytes)} KiB over the ${capKiB} KiB cap`);
     const base = baseline?.[route];
-    if (base === undefined || base <= 0) continue;
+    const held = base !== undefined && base > 0;
+    if (!(capUnheldOnly && held) && bytes > capKiB * KIB) problems.push(`${route}: first-load JS ${kib(bytes)} KiB over the ${capKiB} KiB cap`);
+    if (!held) continue;
     const grew = ((bytes - base) / base) * 100;
     if (grew > growthPct) problems.push(`${route}: first-load JS grew ${grew.toFixed(1)}% over its baseline (cap ${growthPct}%)`);
   }

package/payload/scripts/sizes.ts

@@ -6,7 +6,8 @@
  *
  * First-load comes from the build's own `diagnostics/route-bundle-stats.json`, read once, with each chunk's size from
  * disk: every chunk a route loads counted once, uncompressed. It is checked against `budgets.firstLoadKb` and, when
- * `scripts/verify.baseline.json` exists, against `budgets.firstLoadGrowthPct` over it. A page's HTML is what a person
+ * `scripts/verify.baseline.json` exists, against `budgets.firstLoadGrowthPct` over it; with `firstLoadKb: null` a route
+ * the baseline holds is held to it alone, and the default cap binds only a route it does not. A page's HTML is what a person
  * downloads: the complete streamed response from the app running at `--base`, gzipped. Every page in the baseline's
  * `html` is held to `budgets.htmlGrowthPct` over its own figure, and a route in `budgets.htmlKb` also to that absolute
  * cap. Without a baseline a growth check is `not-configured`, a warning and never a pass; without `--base` the HTML is
@@ -28,7 +29,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { gzipSync } from 'node:zlib';
 
-import { budgetsOf, type BudgetsConfig } from './lib/budgets.ts';
+import { FIRST_LOAD_CAP_KB, budgetsOf, type BudgetsConfig } from './lib/budgets.ts';
 import { distDirOf } from './lib/next-config.ts';
 import { firstLoad, firstLoadProblems, htmlGrowthProblems, htmlProblems, htmlRoutes } from './lib/sizes.ts';
 import verifyConfig from './verify.config.ts';
@@ -112,11 +113,12 @@ async function main(): Promise<number> {
 
   const budgets = budgetsOf(verifyConfig as BudgetsConfig);
   const baseline = baselineOf();
-  const size = firstLoadProblems(routes, { capKiB: budgets.firstLoadKb, growthPct: budgets.firstLoadGrowthPct, baseline: baseline?.firstLoad ?? null });
+  const capKiB = budgets.firstLoadKb ?? FIRST_LOAD_CAP_KB;
+  const size = firstLoadProblems(routes, { capKiB, growthPct: budgets.firstLoadGrowthPct, baseline: baseline?.firstLoad ?? null, capUnheldOnly: budgets.firstLoadKb === null });
   const largest = routes.reduce((a, b) => (b.bytes > a.bytes ? b : a), routes[0]);
   const lines: string[] = [];
   const firstStatus: Status = size.problems.length ? 'FAIL' : size.growth === 'not-configured' ? 'warn' : 'ok';
-  lines.push(`${firstStatus === 'FAIL' ? 'FAIL   ' : firstStatus === 'warn' ? 'warn   ' : 'ok     '} first-load ${routes.length} routes, largest ${largest.route} ${kib(largest.bytes)} KiB · cap ${budgets.firstLoadKb} KiB`
+  lines.push(`${firstStatus === 'FAIL' ? 'FAIL   ' : firstStatus === 'warn' ? 'warn   ' : 'ok     '} first-load ${routes.length} routes, largest ${largest.route} ${kib(largest.bytes)} KiB · cap ${capKiB} KiB${budgets.firstLoadKb === null ? ' for a route the baseline does not hold' : ''}`
     + ` · growth ${size.growth === 'checked' ? `within ${budgets.firstLoadGrowthPct}% of the baseline` : 'not-configured (no scripts/verify.baseline.json)'}`);
   for (const p of size.problems) lines.push(`FAIL    ${p}`);
 

package/payload/scripts/verify.config.ts

@@ -101,11 +101,12 @@ type VerifyConfig = {
    * `scripts/verify.baseline.json`, the warm, cold and after-live navigation times, and no prefetch on a closed phone drawer.
    * Every page's HTML, gzipped through the end of the streamed response, is held to `htmlGrowthPct` (5%) over its own
    * figure in the baseline's `html`; `htmlKb` adds an absolute cap in KiB, the same gzipped figure, for a page a project
-   * wants pinned, and has no default.
+   * wants pinned, and has no default. `firstLoadKb: null` holds first-load JS the same way: each route the baseline holds
+   * to its own figure alone, with the default cap binding only a route the baseline does not hold yet.
    */
   budgets?: {
     navigation?: { warm?: ReadinessBudget; cold?: ReadinessBudget; afterLive?: ReadinessBudget };
-    firstLoadKb?: number;
+    firstLoadKb?: number | null;
     firstLoadGrowthPct?: number;
     htmlGrowthPct?: number;
     htmlKb?: Record<string, number>;

package/payload/tests/verify-sizes.test.ts

@@ -22,6 +22,13 @@ describe('first-load JS', () => {
     expect(firstLoadProblems([{ route: '/y', bytes: 535 * KiB }], { capKiB: 820, growthPct: 5, baseline: null })).toEqual({ problems: [], growth: 'not-configured' });
     expect(firstLoadProblems([{ route: '/y', bytes: 535 * KiB }], { capKiB: 1, growthPct: 5, baseline: null }).problems).toHaveLength(1);
   });
+  it('with the cap for unheld routes only, holds a route the baseline holds to its baseline alone (#76)', () => {
+    const routes = [{ route: '/x', bytes: 852 * KiB }, { route: '/y', bytes: 900 * KiB }, { route: '/z', bytes: 700 * KiB }];
+    const got = firstLoadProblems(routes, { capKiB: 820, growthPct: 5, baseline: { '/x': 850 * KiB, '/z': 600 * KiB }, capUnheldOnly: true });
+    expect(got.problems).toEqual(['/y: first-load JS 900 KiB over the 820 KiB cap', '/z: first-load JS grew 16.7% over its baseline (cap 5%)']);
+    expect(budgetsOf({ budgets: { firstLoadKb: null } }).firstLoadKb).toBeNull();
+    expect(budgetsOf({}).firstLoadKb).toBe(820);
+  });
 });
 
 describe('HTML and prefetch', () => {