nimiq-branding-cli 1.2.0 → 1.3.0

package/LINT.md

@@ -36,6 +36,12 @@ These are the "make us not do AI things" set.
 | borders on inputs | skill rule 1 | manual (inset box-shadow) |
 | off-palette colors | skill rule 13 | manual |
 | low-contrast blue/navy text on dark | skill rule 20 | manual → `#0CA6FE` / white |
+| generic icon set (Lucide / Font Awesome / Material / Feather / Bootstrap…) | skill Icons | manual → `nq-icon` SVGs |
+| duplicate gradient id with **differing** stops | skill rule 3 | manual → unique ids |
+| pure-black surface (all channels ≤12, ≥4000px²) | skill rule 6 | manual → navy `#1F2348` |
+| one-sided accent stripe on a card | skill rule 19 | manual → uniform border |
+
+**Generic icon set** is a class-signature match (`lucide-`, `fa-solid`, `material-icons`, `bi-`, `ph-`, `data-lucide`, a `material-icons` ligature span, …) — verified zero hits in Nimiq's own components, so any hit is someone dropping in a foreign icon library. **Duplicate gradient id** only fires when two `<linearGradient>`/`<radialGradient>` defs share an id but have **different stops** — the real "later SVG paints the wrong fill" bug. nimiq.com repeats *identical* icon gradients under one id (Figma export) and renders fine, so raw id-collision is deliberately not flagged.
 
 **Blue/navy on dark (rule 20)** is the headline a11y+brand check. A blue-family foreground (hue
 195–245°) sitting on a dark surface (luminance < 0.12) below the AA floor — **4.5:1 normal, 3.0:1
@@ -73,6 +79,44 @@ to flag *"this is getting busy, is it justified?"* — the deterministic half of
 | underlined links | a body `<a>` with `text-decoration: underline` (links are bold, no underline) |
 | NIM address not in Fira Mono | a 4-char-grouped address rendered in a proportional font |
 | gold-tinted UI icon | a non-logo icon tinted gold (gold = brand mark only) |
+| feather/lucide-style stroke icon | an inlined SVG with `viewBox 0 0 24 24` + every path `stroke-width: 2` + `fill: none` (the generic-set default Nimiq never ships — its 24×24 `close` is a *filled* path) |
+| green action/retry button | a button labelled retry/continue/submit/get-started filled green (green = success only, rule 5) |
+| baked-color icon | an icon-role SVG (small, square, not identicon/flag/chart/logo, no gradient def) with a literal hex `fill`/`stroke` instead of `currentColor` |
+| black-outline duotone icon | an icon-role SVG with a near-black layer *and* a colored layer (duotone = the same color at `opacity: 0.4`, never a black outline) |
+| colored glow shadow | a `box-shadow`/`drop-shadow` whose color is saturated and bright (lum > 0.15) — Nimiq elevation is dark navy/black, so its real shadows are excluded |
+| black modal overlay | a full-viewport `position: fixed` translucent scrim that's near-neutral black (navy `b≫r` excluded) — rule 11 |
+| flat-fill navy/colored section | a full-width band (≥0.7vw, ≥220px) solid-filled in a brand color with **no** gradient — colored bands use the bottom-right radial (rule 7) |
+
+**Accessibility**
+
+| Check | Threshold |
+|---|---|
+| focus outline removed w/o `:focus-visible` | a stylesheet rule kills `outline` on a focusable/global selector and **no** `:focus-visible` rule anywhere restores a ring (cross-origin sheets are skipped, never guessed) |
+| Mulish not loaded | a declared `Mulish` `@font-face` that didn't load (`document.fonts.check` false) → the page silently falls back to a system font |
+
+**Headline typography & line breaks** (closes the "lint passes ≠ brand-correct" gap)
+
+The deterministic checks above read color, spacing and shape — but a heading can satisfy all of
+them and still read as generic SaaS through *weight* and *tracking*, the exact "faux-weight or
+tightly-tracked black headlines" the skill blacklist names. These read the rendered type instead.
+Measured on nimiq.com: every heading renders at weight **600/700**, `letter-spacing: 0`, and
+`text-wrap: balance`; nothing on the page strands a single word. So:
+
+| Check | Threshold | Why |
+|---|---|---|
+| faux-black headline weight | heading ≥ 24px at `font-weight ≥ 800` | nimiq.com tops out at 700; 800+ "black" is the generic tell |
+| tight negative heading tracking | heading ≥ 24px with `letter-spacing ≤ -0.01em` | nimiq.com headings are `0`; negative tracking cramps the headline |
+| wrapping heading w/o `text-wrap: balance` | a heading ≥ 20px that wraps to ≥ 2 lines without `balance`/`pretty` | how nimiq.com keeps every headline evenly split |
+| orphaned last word | any text ≥ 20px that wraps with a **single word alone** on the last line | nimiq.com has **zero**; a stranded word (the circled "verified") is the defect |
+| heading line-height off | heading ≥ 24px with `line-height/font-size ≤ 1.05` or `≥ 1.5` | nimiq.com headings render **1.25–1.3**; 1.0 cramps, 1.6 floats |
+| cramped body line-height | body copy with `line-height/font-size < 1.35` | nimiq.com body is **1.5–1.56**; tighter hurts readability |
+| non-brand font on text | a text element whose first font family isn't Mulish/Muli/Fira (≥3 uses) | nimiq.com is **Mulish** + Fira Mono for data; an Inter/Roboto headline reads instantly off |
+
+`--fix` also **injects the `text-wrap` rule** (`h1–h4 { balance } p,li { pretty }`) once, before `</head>` — the mechanical cure for orphaned titles, applying the exact technique nimiq.com uses on every heading.
+
+Weight/tracking are heading-scoped (buttons and bold body labels are legitimately heavy). The
+orphan check is general (it caught a body banner, not a heading) but gated at ≥ 20px so calibrated
+fine-print under 20px — which wasn't measured on the reference — is never flagged.
 
 **Mobile (a second pass at 390px)**
 
@@ -122,7 +166,8 @@ same "measure reality" method that proved the no-em-dash rule. Verified outcome:
 
 | Page | ERRORS | Note |
 |---|---|---|
-| nimiq.com home (reference) | **0** | the gate must never flag the brand's own site, even with the rule-20 contrast + depth/motion checks |
+| nimiq.com home (reference) | **0** | the gate must never flag the brand's own site, even with the rule-20 contrast, depth/motion + headline-typography checks |
+| nimiq.com headline type | **0** | measured directly: weights 600/700, `letter-spacing: 0`, every heading `text-wrap: balance`, zero stranded words |
 | nimiq.com/about | 0 | — |
 | nimiq.tech | real findings | catches genuine em-dashes + a "Phase 2 · preview" colored eyebrow + 3 dense bands |
 | positive control | **2** | a deliberate `#0582CA`/`#265DD7`-on-navy page errors at 3.63/2.61:1; `#0CA6FE` + white pass |

package/align/canonical.json

@@ -38,7 +38,8 @@
   "settlementPackage": "nimiq-settlement",
   "lightClient": {
     "forbiddenImports": ["@nimiq/core/web"],
-    "forbiddenCalls": ["Client.create(", "waitForConsensusEstablished("],
+    "forbiddenCalls": ["Client.create("],
+    "note": "forbiddenCalls is intentionally ONLY `Client.create(` (constructing the @nimiq/core light client). `waitForConsensusEstablished(` is NOT forbidden: the canonical rpc-block-scan client implements it as a NimiqClientLike interface method (RPC poll of isConsensusEstablished), so flagging it would punish the correct pattern.",
     "reason": "The @nimiq/core light client never reaches consensus on our hosts (WASM addEventListener bug, hangs in Bun/Node through 2.7.0). Chain reads MUST use the rpc-block-scan path via the nimiq-settlement package; @nimiq/core is offline-crypto-only (key/tx signing)."
   }
 }

package/bin/nq.js

@@ -33,6 +33,12 @@ Usage:
       --no-chain                chainApp:false (skip settlement + styling parity)
       --settlement mock|rpc|noop    settlement client (default mock)
       --deploy fly|none         deploy kit (default fly)
+  nq check [path]               Run the FULL per-project alignment gate in one shot:
+                                align (--fail-on=settlement,styling) + 800-line file
+                                guard + bun test (if present) + nq lint (if Playwright).
+                                Prints a PASS/FAIL/SKIP summary; exits nonzero on any
+                                FAIL (SKIP is fine). --json for machine output. This is
+                                what a nightly loop / pre-push hook should run.
   nq align [path]               Grade an app's stack vs the canonical fleet baseline.
       --all <dir>               Grade every app dir under <dir>
       --fix                     Safe autofixes only (write/repair nimiq-stack.json)
@@ -41,7 +47,8 @@ Usage:
                                 SETTLEMENT is load-bearing: any @nimiq/core/web import or
                                 Client.create( / waitForConsensusEstablished( in src HARD FAILS.
   nq hooks install [repo]       Install the drift hooks: git pre-commit (align --fail-on),
-                                SessionStart banner, weekly GH Action (--write drops the workflow)
+                                git pre-push (the fuller nq check gate), SessionStart banner,
+                                weekly GH Action (--write drops the workflow)
   nq verify <component|all>     Render the html variant and diff against the reference PNG
   nq lint <file.html|url>       Render a page and enforce the brand rules + breathability.
       --fix                     Auto-fix the safe text violations in a local file (dashes, title periods)
@@ -382,8 +389,10 @@ async function cmdHooks(sub, flags) {
   }
   if (sub === 'show' || !sub) {
     console.log('# git pre-commit (.git/hooks/pre-commit):\n');
-    const { PRE_COMMIT } = await import(join(ROOT, 'scripts', 'hooks.mjs'));
+    const { PRE_COMMIT, PRE_PUSH } = await import(join(ROOT, 'scripts', 'hooks.mjs'));
     console.log(PRE_COMMIT);
+    console.log('# git pre-push (.git/hooks/pre-push):\n');
+    console.log(PRE_PUSH);
     console.log('# SessionStart advisory:\n');
     console.log(SESSION_START);
     console.log('# weekly GH Action (.github/workflows/stack-align.yml):\n');
@@ -422,6 +431,11 @@ try {
     case 'new':
     case 'new-component': await cmdNewComponent(rest[0], flags); break;
     case 'new-app': await cmdNew(rest[0], flags); break;
+    case 'check': {
+      const { run } = await import(join(ROOT, 'scripts', 'check.mjs'));
+      await run(rest, flags);
+      break;
+    }
     case 'align': {
       const { run } = await import(join(ROOT, 'scripts', 'align.mjs'));
       await run(rest, flags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nimiq-branding-cli",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "nq — pixel-verified Nimiq UI component registry + CLI. 39 components (Vue 3 + plain HTML) diffed against the real Nimiq apps, plus the team's real asset library. Unofficial community tool.",
   "type": "module",
   "bin": {

package/scripts/_browser.mjs

@@ -0,0 +1,27 @@
+// Shared browser bootstrap for `nq lint` and `nq verify`.
+// Playwright is intentionally NOT a runtime dependency (it pulls a ~hundreds-of-MB browser),
+// so we load it lazily and, if it's missing, print a one-line fix instead of a raw stack
+// trace. Exit code 2 = "setup needed", distinct from lint's 1 = violations / 0 = clean.
+export async function launchChromium(cmd = 'this command') {
+  let chromium;
+  try {
+    ({ chromium } = await import('playwright'));
+  } catch {
+    console.error(
+      `\nnq: ${cmd} needs Playwright (a headless browser) to render pages.\n` +
+      `It isn't bundled, to keep installs light. One-time setup:\n\n` +
+      `  npm i -g playwright && npx playwright install chromium\n\n` +
+      `Then re-run. Only \`nq lint\` and \`nq verify\` need it — the rest of nq works without it.\n`,
+    );
+    process.exit(2);
+  }
+  try {
+    return await chromium.launch();
+  } catch (e) {
+    if (/Executable doesn't exist|playwright install|please run the following/i.test(String(e))) {
+      console.error(`\nnq: Playwright is installed but its browser isn't. Run:\n\n  npx playwright install chromium\n`);
+      process.exit(2);
+    }
+    throw e;
+  }
+}

package/scripts/align.mjs

@@ -70,6 +70,9 @@ async function scanLightClient(appDir, canonical) {
       const full = join(dir, e.name);
       if (e.isDirectory()) { await walk(full); continue; }
       if (!CODE_EXT.test(e.name)) continue;
+      // Test/spec files legitimately reference the forbidden strings (fixtures, mocks, the
+      // detector's own cases) and are not shipped runtime code — never grade them.
+      if (/\.(test|spec)\./.test(e.name)) continue;
       let text;
       try { text = await readFile(full, 'utf8'); } catch { continue; }
       const rel = full.slice(appDir.length + 1);

package/scripts/hooks.mjs

@@ -2,6 +2,8 @@
 //
 //   git pre-commit   → `nq align --fail-on=settlement,styling`  (blocks a commit that
 //                       introduces the broken light-client path or off-brand styling)
+//   git pre-push     → `nq check --fail-on=settlement,styling`  (the fuller gate — align
+//                       + 800-line guard + bun test + lint — run before code leaves the box)
 //   SessionStart     → `nq align --quiet` advisory drift banner (one line)
 //   weekly GH Action → `nq align --all` → PR safe fixes / file a rolling drift issue,
 //                       reusing the existing nq audit weekly machinery.
@@ -29,6 +31,19 @@ else
 fi
 `;
 
+export const PRE_PUSH = `#!/usr/bin/env bash
+# nq check pre-push gate — installed by \`nq hooks install\`.
+# Runs the FULL per-project gate before code leaves the box: align
+# (settlement/styling) + the 800-line file guard + bun test + nq lint.
+# Blocks the push on any FAIL (SKIPs — e.g. no Playwright — are fine).
+set -euo pipefail
+if command -v nq >/dev/null 2>&1; then
+  nq check --fail-on=settlement,styling
+else
+  npx -y github:Andjroo111/nimiq-branding-cli check --fail-on=settlement,styling
+fi
+`;
+
 export const SESSION_START = `# nq align — SessionStart advisory drift banner.
 # Add to .claude/settings.json hooks.SessionStart, or run at the top of a session.
 nq align --quiet 2>/dev/null || true
@@ -124,8 +139,14 @@ export async function installHooks(target, opts = {}) {
     await writeFile(hookPath, PRE_COMMIT);
     await chmod(hookPath, 0o755);
     out.wrote.push(hookPath);
+
+    // pre-push: the fuller `nq check` gate before code leaves the box
+    const pushPath = join(hookDir, 'pre-push');
+    await writeFile(pushPath, PRE_PUSH);
+    await chmod(pushPath, 0o755);
+    out.wrote.push(pushPath);
   } else {
-    out.printed.push(`(no .git in ${repo} — skipped pre-commit; init git then re-run)`);
+    out.printed.push(`(no .git in ${repo} — skipped pre-commit + pre-push; init git then re-run)`);
   }
 
   // 2) weekly workflow (write only with --write)
@@ -146,6 +167,8 @@ export async function emitArtifacts() {
   await mkdir(dir, { recursive: true });
   await writeFile(join(dir, 'pre-commit'), PRE_COMMIT);
   await chmod(join(dir, 'pre-commit'), 0o755);
+  await writeFile(join(dir, 'pre-push'), PRE_PUSH);
+  await chmod(join(dir, 'pre-push'), 0o755);
   await writeFile(join(dir, 'session-start.sh'), SESSION_START);
   await writeFile(join(dir, 'stack-align.yml'), WEEKLY_WORKFLOW);
   return dir;

package/scripts/lint.mjs

@@ -85,12 +85,35 @@ function pageProbe({ SPACING_SCALE, ANCHORS, RADIUS_SCALE }) {
   const visible = (el) => { const cs = getComputedStyle(el); if (cs.display === 'none' || cs.visibility === 'hidden' || +cs.opacity === 0) return false; const r = el.getBoundingClientRect(); return r.width > 1 && r.height > 1; };
   const directText = (el) => [...el.childNodes].filter((n) => n.nodeType === 3).map((n) => n.textContent).join('').trim();
   const matchAny = (el, sel) => { try { return el.closest(sel); } catch { return null; } };
+  // rendered line geometry of an element's own text — Range over each word, group by line-top.
+  // returns [lineCount, wordsOnLastLine] so callers can detect both wraps and orphaned words.
+  const lineInfo = (el) => {
+    const node = [...el.childNodes].find((n) => n.nodeType === 3 && n.textContent.trim());
+    if (!node) return [1, 1];
+    const words = node.textContent.trim().split(/\s+/);
+    if (words.length < 2) return [1, 1];
+    const range = document.createRange(); const tops = []; let idx = 0;
+    for (const w of words) {
+      const start = node.textContent.indexOf(w, idx); if (start < 0) continue;
+      range.setStart(node, start); range.setEnd(node, start + w.length);
+      const rr = range.getClientRects()[0]; if (rr) tops.push(Math.round(rr.top));
+      idx = start + w.length;
+    }
+    if (!tops.length) return [1, 1];
+    const uniq = [...new Set(tops)].sort((a, b) => a - b);
+    const last = uniq[uniq.length - 1];
+    return [uniq.length, tops.filter((t) => Math.abs(t - last) <= 2).length];
+  };
 
   const o = {
     dashes: [], titlePeriods: [], glass: [], inputBorders: [], uppercase: [], offPalette: {},
     wideText: [], offScale: {}, onScaleN: 0, scaleN: 0, denseSections: [], fontSizes: {}, foldColors: new Set(),
     blueOnDark: [], nonPill: [], flatColorBtn: [], wrongAnchor: [], wrongEase: [],
     offRadius: {}, harshShadow: [], linkUnderline: [], addrNotMono: [], goldIcon: [],
+    fauxWeight: [], tightTrack: [], headingNoBalance: [], orphanLine: [],
+    tightLeadingH: [], tightLeadingBody: [], offFont: {},
+    blackBg: [], accentStripe: [], greenAction: [], dupGradIds: [], genericIcon: [], featherIcon: [],
+    bakedIcon: [], duotoneBlack: [], modalBlack: [], flatNavySection: [], glowShadow: [], fontsNotLoaded: false, noFocusRing: false,
   };
 
   for (const el of document.querySelectorAll('body *')) {
@@ -107,7 +130,37 @@ function pageProbe({ SPACING_SCALE, ANCHORS, RADIUS_SCALE }) {
     if (txt && !inCode && /[—–]/.test(txt)) o.dashes.push(txt.slice(0, 70));
 
     const isTitle = /^h[1-4]$/.test(tag) || el.matches('button,.nq-button,[class*="title" i],[class*="heading" i],[class*="headline" i]');
-    if (isTitle && txt && /[a-z0-9)]\.$/i.test(txt) && !/\.\.\.$/.test(txt) && !/\.[a-z]?\.$/i.test(txt)) o.titlePeriods.push(`<${tag}> ${txt.slice(0, 60)}`);
+    // a display title / CTA ends clean; exempt full sentences (comma/colon/semicolon = descriptive
+    // lead marked as a heading, which nimiq.com/about does and ends with a period legitimately).
+    if (isTitle && txt && /[a-z0-9)]\.$/i.test(txt) && !/\.\.\.$/.test(txt) && !/\.[a-z]?\.$/i.test(txt) && !/[,:;]/.test(txt)) o.titlePeriods.push(`<${tag}> ${txt.slice(0, 60)}`);
+
+    // HEADLINE TYPOGRAPHY — faux-black weight, tight negative tracking, orphaned wraps.
+    // Calibrated to nimiq.com: every heading renders at weight 600/700, letter-spacing 0,
+    // and text-wrap:balance. So weight ≥800, any meaningful negative tracking, or a multi-line
+    // heading that DIDN'T opt into balance/pretty is off-brand. Buttons excluded (legit bold).
+    const isHeadingEl = /^h[1-4]$/.test(tag) || el.matches('[class*="title" i],[class*="heading" i],[class*="headline" i]');
+    if (isHeadingEl && txt) {
+      const fs = px(cs.fontSize);
+      if (fs >= 24 && +cs.fontWeight >= 800) o.fauxWeight.push(`<${tag}> weight ${cs.fontWeight} @ ${fs}px "${txt.slice(0, 28)}"`);
+      if (fs >= 24 && cs.lineHeight !== 'normal') { const lhR = px(cs.lineHeight) / fs; if (lhR <= 1.05 || lhR >= 1.5) o.tightLeadingH.push(`<${tag}> line-height ${lhR.toFixed(2)} @ ${fs}px "${txt.slice(0, 22)}"`); }
+      if (fs >= 24 && cs.textTransform !== 'uppercase') {
+        const lsRaw = parseFloat(cs.letterSpacing);
+        if (!Number.isNaN(lsRaw) && lsRaw / fs <= -0.01) o.tightTrack.push(`<${tag}> ${(lsRaw / fs).toFixed(3)}em @ ${fs}px "${txt.slice(0, 24)}"`);
+      }
+      if (fs >= 20) {
+        const tw = cs.textWrap || cs.textWrapStyle || cs.textWrapMode || '';
+        const lc = lineInfo(el)[0];
+        if (!/balance|pretty/.test(tw) && lc >= 2) o.headingNoBalance.push(`<${tag}> ${lc} lines, no text-wrap:balance "${txt.slice(0, 24)}"`);
+      }
+    }
+
+    // ORPHAN — any prominent text block (≥20px) that wraps and strands a single word on its last
+    // line. nimiq.com has ZERO of these (headings use text-wrap:balance; nothing orphans), so this
+    // is calibrated to 0 on the reference. Leaf elements only = measure the real text-painter.
+    if (txt && el.children.length === 0 && !inCode && px(cs.fontSize) >= 20) {
+      const [lc, lw] = lineInfo(el);
+      if (lc >= 2 && lw === 1) o.orphanLine.push(`<${tag}> ${lc} lines, last word alone "${txt.slice(0, 38)}"`);
+    }
 
     // glassmorphism = a TRANSLUCENT surface with a backdrop blur (the frosted-glass card).
     if (cs.backdropFilter && cs.backdropFilter !== 'none' && /blur\(/.test(cs.backdropFilter)) {
@@ -150,6 +203,12 @@ function pageProbe({ SPACING_SCALE, ANCHORS, RADIUS_SCALE }) {
       const bgRgb = toRGB(cs.backgroundColor); const bgA = toRGBA(cs.backgroundColor)?.[3] ?? 0;
       const brandFill = bgRgb && bgA > 0.5 && !gray(bgRgb) && nearest(bgRgb, ANCHORS).d < 60 && relLum(bgRgb) < 0.7 && nearest(bgRgb, ANCHORS).name !== 'white';
       if (brandFill && cs.backgroundImage === 'none') o.flatColorBtn.push(`<${tag}> flat ${cs.backgroundColor} "${txt.slice(0, 20)}"`);
+      // green = success ONLY (rule 5): an action/retry button must not be green-filled
+      if (/\b(retry|try again|reload|continue|next|get started|submit|sign ?up|learn more)\b/i.test(txt) && !/\b(success|done|paid|complete|confirm)\b/i.test(txt)) {
+        const grads = (cs.backgroundImage.match(/rgba?\([^)]+\)|#[0-9a-fA-F]{3,8}/g) || []).map(toRGB).filter(Boolean);
+        const fill = (bgA > 0.5 ? bgRgb : null) || grads[0];
+        if (fill && (dist(fill, ANCHORS.green) < 55 || dist(fill, ANCHORS.greenGrad) < 55)) o.greenAction.push(`<${tag}> green "${txt.slice(0, 22)}"`);
+      }
       if (/gradient/.test(cs.backgroundImage)) {
         if (/linear-gradient/.test(cs.backgroundImage)) o.wrongAnchor.push(`<${tag}> linear-gradient (use radial)`);
         else if (!/(bottom right|100% 100%|100%100%|at 100%)/.test(cs.backgroundImage)) o.wrongAnchor.push(`<${tag}> radial not bottom-right`);
@@ -172,6 +231,28 @@ function pageProbe({ SPACING_SCALE, ANCHORS, RADIUS_SCALE }) {
       const m = cs.boxShadow.match(/rgba\(0,\s*0,\s*0,\s*([0-9.]+)\)/);
       if (m && parseFloat(m[1]) > 0.22) o.harshShadow.push(`<${tag}> rgba(0,0,0,${m[1]})`);
     }
+    // colored "glow" shadow (slop): Nimiq elevation is navy/black low-alpha, never a saturated glow.
+    // The luminance gate (>0.15) excludes the brand's dark navy shadow (lum ≈ 0.02) so only a bright
+    // gold/green/blue glow trips it.
+    for (const shadowProp of [cs.boxShadow, /drop-shadow/.test(cs.filter) ? cs.filter : '']) {
+      if (!shadowProp || shadowProp === 'none') continue;
+      for (const c of shadowProp.match(/rgba?\([^)]+\)|#[0-9a-fA-F]{3,8}/g) || []) {
+        const rgb = toRGB(c); if (rgb && !gray(rgb) && sat(rgb) > 0.4 && relLum(rgb) > 0.15 && nearest(rgb, ANCHORS).d < 80) { o.glowShadow.push(`<${tag}> ${c} glow`); break; }
+      }
+    }
+    // modal/overlay scrim must be navy, not black (rule 11): a full-viewport fixed translucent layer
+    // whose base is near-neutral black (r≈g≈b, all low) — navy (b≫r) is excluded.
+    if (cs.position === 'fixed') { const a = toRGBA(cs.backgroundColor); if (a && a[3] > 0.1 && a[3] < 0.95 && r.width >= innerWidth * 0.9 && r.height >= innerHeight * 0.9 && Math.max(a[0], a[1], a[2]) <= 40 && Math.abs(a[0] - a[2]) < 12) o.modalBlack.push(`<${tag}> overlay rgba(${a.slice(0, 3).map((x) => Math.round(x)).join(',')},${a[3].toFixed(2)})`); }
+    // pure-black surface (rule 6): Nimiq dark is navy #1F2348 / #171D2E, never #000 / near-black
+    if (!inCode) { const bgA2 = toRGBA(cs.backgroundColor); if (bgA2 && bgA2[3] >= 0.5 && r.width * r.height > 4000 && Math.max(bgA2[0], bgA2[1], bgA2[2]) <= 12) o.blackBg.push(`<${tag}> rgb(${bgA2.slice(0, 3).map((x) => Math.round(x)).join(',')})`); }
+    // one-sided vertical accent stripe on a card (rule 19): left/right edge ≥3px colored, opposite 0
+    if (r.width * r.height > 5000 && (toRGBA(cs.backgroundColor)?.[3] > 0.05 || cs.boxShadow !== 'none')) {
+      for (const [side, opp] of [['Left', 'Right'], ['Right', 'Left']]) {
+        if (px(cs[`border${side}Width`]) >= 3 && px(cs[`border${opp}Width`]) === 0) {
+          const bc = toRGB(cs[`border${side}Color`]); if (bc && !gray(bc) && nearest(bc, ANCHORS).d < 90) { o.accentStripe.push(`<${tag}> border-${side.toLowerCase()} ${px(cs[`border${side}Width`])}px`); break; }
+        }
+      }
+    }
     // link styling — underlined body anchors (Nimiq links are bold, no underline)
     if (tag === 'a' && txt && !matchAny(el, 'nav,header,footer') && cs.textDecorationLine.includes('underline')) o.linkUnderline.push(`"${txt.slice(0, 30)}"`);
     // data formatting — NIM-address-looking text not in a mono font
@@ -183,8 +264,11 @@ function pageProbe({ SPACING_SCALE, ANCHORS, RADIUS_SCALE }) {
     if ((tag === 'p' || el.matches('[class*="text" i],[class*="body" i],[class*="desc" i]')) && txt.length > 60 && el.children.length === 0) {
       const fs = px(cs.fontSize) || 16; const ch = Math.round(r.width / (fs * 0.5));
       if (ch > 88) o.wideText.push({ ch, snippet: txt.slice(0, 50) });
+      if (cs.lineHeight !== 'normal' && px(cs.lineHeight) / fs < 1.35) o.tightLeadingBody.push(`${(px(cs.lineHeight) / fs).toFixed(2)} @ ${fs}px "${txt.slice(0, 38)}"`);
     }
     if (txt) { const fs = px(cs.fontSize); if (fs) o.fontSizes[fs] = (o.fontSizes[fs] || 0) + 1; }
+    // font-family — Nimiq text is Mulish (+ Fira Mono for data). A named third-party face is off-brand.
+    if (txt && !inCode) { const fam = cs.fontFamily.split(',')[0].replace(/["']/g, '').trim().toLowerCase(); if (fam && !/^(mulish|muli|fira mono|fira code|fira sans|inherit)$/.test(fam)) o.offFont[fam] = (o.offFont[fam] || 0) + 1; }
     if (r.top < 1024 && r.bottom > 0 && txt && !inCode) o.foldColors.add(cs.color);
   }
 
@@ -194,19 +278,89 @@ function pageProbe({ SPACING_SCALE, ANCHORS, RADIUS_SCALE }) {
     if (matchAny(el, '[class*="logo" i],[class*="brand" i],[class*="hex" i],[class*="pay" i],[class*="badge" i],[aria-label*="nimiq" i]')) continue;
     const cs = getComputedStyle(el);
     for (const c of [cs.color, cs.fill]) { const rgb = toRGB(c); if (rgb && dist(rgb, ANCHORS.gold) < 42) { o.goldIcon.push(`<${el.tagName.toLowerCase()}> gold-tinted icon`); break; } }
+    // Lucide/Feather/Tabler fingerprint: a 24×24 viewBox where EVERY path is 2px stroke + fill:none.
+    // Nimiq's own 24×24 icon (close.svg) is a FILLED path, so it can't match this composite.
+    if (el.tagName.toLowerCase() === 'svg' && el.getAttribute('viewBox') === '0 0 24 24' && cs.fill === 'none') {
+      const draw = [...el.querySelectorAll('path,line,polyline,polygon,circle,rect')];
+      if (draw.length >= 2 && draw.every((p) => getComputedStyle(p).strokeWidth === '2px')) o.featherIcon.push('<svg> 24×24 + uniform 2px stroke + fill:none (Lucide/Feather default)');
+    }
+    // baked-color + black-outline duotone — Nimiq mono icons paint via `currentColor`, never a
+    // literal hex (skill Icons). Icon-role = small square SVG, not an identicon/flag/chart/logo and
+    // with no gradient/image def (those are meant to be multi-colored).
+    if (el.tagName.toLowerCase() === 'svg') {
+      const ir = el.getBoundingClientRect();
+      const small = ir.width <= 130 && ir.height <= 130 && Math.abs(ir.width - ir.height) < Math.max(ir.width, ir.height, 1) * 0.5;
+      const decorative = matchAny(el, '[class*="identicon" i],[class*="flag" i],[class*="qr" i],[class*="chart" i],[class*="honeycomb" i],[class*="avatar" i]') || el.querySelector('linearGradient,radialGradient,image,pattern');
+      if (small && !decorative) {
+        const isLit = (v) => { v = (v || '').trim().toLowerCase(); return v && v !== 'none' && v !== 'currentcolor' && v !== 'inherit' && v !== 'transparent' && !/^url\(/.test(v) && !/^(#fff|#ffffff|white|rgb\(255,\s*255,\s*255\))$/.test(v); };
+        let baked = false, hasBlack = false, hasColor = false;
+        for (const p of [el, ...el.querySelectorAll('path,circle,rect,line,polyline,polygon,ellipse')]) {
+          for (const attr of ['fill', 'stroke']) {
+            const v = p.getAttribute && p.getAttribute(attr);
+            if (isLit(v)) { baked = true; const rgb = toRGB(v); if (rgb) { if (Math.max(...rgb) <= 40) hasBlack = true; else if (!gray(rgb)) hasColor = true; } }
+          }
+        }
+        if (baked) o.bakedIcon.push(`<svg ${(el.getAttribute('class') || '').slice(0, 22)}> baked fill (use currentColor)`);
+        if (hasBlack && hasColor) o.duotoneBlack.push('<svg> black layer on a colored icon (duotone = same color @0.4)');
+      }
+    }
+  }
+
+  // generic / off-brand icon SETS (Lucide, Feather, Font Awesome, Material, Bootstrap, Tabler…).
+  // Nimiq ships its own SVGs under `nq-icon`; it never emits a library class (verified 0 in registry).
+  const ICON_LIB = /(^|\s)(lucide|feather|fa-(solid|regular|light|thin|brands|duotone)|fas|far|fal|fab|fad|bi-|mdi-|ph-|tabler|ti-|ion-|ionicon|remixicon|ri-|material-icons|material-symbols|octicon|glyphicon)(\b|-)/i;
+  const ICON_OK = /\b(nq-icon|flag-icon|flag-icons|fi-)\b/;
+  const seenGeneric = new Set();
+  for (const el of document.querySelectorAll('svg,i,span,[class*="icon" i],[data-lucide],[data-feather],[data-icon]')) {
+    if (!visible(el)) continue;
+    const cls = `${el.getAttribute('class') || ''}`;
+    const libClass = ICON_LIB.test(cls) && !ICON_OK.test(cls);
+    const libData = el.hasAttribute('data-lucide') || el.hasAttribute('data-feather');
+    const ligature = /material-icons|material-symbols/i.test(cls) && el.children.length === 0 && /^[a-z][a-z_]{1,}$/i.test((el.textContent || '').trim());
+    if (libClass || libData || ligature) { const key = cls || el.tagName; if (!seenGeneric.has(key)) { seenGeneric.add(key); o.genericIcon.push(`<${el.tagName.toLowerCase()} class="${cls.slice(0, 28)}">`); } }
   }
 
+  // duplicate gradient ids — only a REAL bug when defs sharing one id have DIFFERENT stops (then a
+  // later SVG paints the first def's gradient). nimiq.com repeats IDENTICAL icon gradients under the
+  // same id (Figma export) and renders fine, so compare stop colors+offsets, not raw id counts.
+  const gradById = {};
+  for (const g of document.querySelectorAll('linearGradient[id],radialGradient[id]')) {
+    const sig = [...g.querySelectorAll('stop')].map((s) => `${getComputedStyle(s).stopColor || s.getAttribute('stop-color') || ''}@${s.getAttribute('offset') || ''}`).join(',');
+    (gradById[g.id] ??= new Set()).add(sig);
+  }
+  o.dupGradIds = Object.entries(gradById).filter(([, sigs]) => sigs.size > 1).map(([id, sigs]) => `#${id} (${sigs.size} differing defs)`);
+
   // per-section text-ink ratio (full-width bands)
   const vw = innerWidth;
   const leaves = [...document.querySelectorAll('body *')].filter((el) => !matchAny(el, 'svg') && visible(el) && el.children.length === 0 && directText(el)).map((el) => el.getBoundingClientRect());
   for (const el of document.querySelectorAll('section,main > div,body > div,[class*="section" i],[class*="band" i]')) {
     if (matchAny(el, 'svg') || !visible(el)) continue;
     const r = el.getBoundingClientRect(); if (r.width < vw * 0.7 || r.height < 220) continue;
+    // flat-fill navy/colored section (rule 7): a full-width band solid-filled in a brand color with
+    // NO gradient — Nimiq colored bands use the bottom-right radial. Grey/white cards are exempt.
+    const scs = getComputedStyle(el); const sbg = toRGB(scs.backgroundColor); const sbgA = toRGBA(scs.backgroundColor)?.[3] ?? 0;
+    if (sbgA > 0.85 && sbg && !gray(sbg) && relLum(sbg) < 0.5 && scs.backgroundImage === 'none') { const nb = nearest(sbg, ANCHORS); if (nb.d < 60 && nb.name !== 'white') o.flatNavySection.push(`<${el.tagName.toLowerCase()}> flat ${scs.backgroundColor}`); }
     let ink = 0; for (const lr of leaves) { const cx = lr.left + lr.width / 2, cy = lr.top + lr.height / 2; if (cx >= r.left && cx <= r.right && cy >= r.top && cy <= r.bottom) ink += lr.width * lr.height; }
     const pct = Math.round((ink / (r.width * r.height)) * 1000) / 10;
     if (pct > 18) o.denseSections.push({ pct, tag: el.tagName.toLowerCase(), cls: (el.className || '').toString().trim().split(/\s+/)[0]?.slice(0, 24) || '', h: Math.round(r.height) });
   }
   o.foldColors = o.foldColors.size;
+
+  // Mulish must actually load (rule 9) — a declared family that 404s falls back to a system font.
+  o.fontsNotLoaded = !document.fonts.check('1em Mulish') && !document.fonts.check('1em Muli');
+  // focus ring removed without a :focus-visible restore (a11y). Scan accessible stylesheets only;
+  // cross-origin CDN sheets throw on .cssRules and are skipped (so we never guess).
+  let killsOutline = false, restoresFocus = false;
+  for (const sheet of document.styleSheets) {
+    let rules; try { rules = sheet.cssRules; } catch { continue; }
+    if (!rules) continue;
+    for (const rule of rules) {
+      const sel = rule.selectorText, st = rule.style; if (!sel || !st) continue;
+      if (/:focus(-visible)?\b/.test(sel) && ((st.outlineStyle && st.outlineStyle !== 'none') || parseFloat(st.outlineWidth) > 0 || (st.boxShadow && st.boxShadow !== 'none') || st.borderColor || st.border)) restoresFocus = true;
+      if (/(^|[\s,])(a|button|input|select|textarea|\*|\[tabindex\]|:focus)([\s,:>[]|$)/i.test(sel) && /outline\s*:\s*(none|0)/i.test(st.cssText)) killsOutline = true;
+    }
+  }
+  o.noFocusRing = killsOutline && !restoresFocus;
   return o;
 }
 
@@ -237,6 +391,13 @@ function fixSource(src) {
   let out = src;
   out = replaceText(out, (t) => t.replace(/\s*[—–]\s*/g, () => { fixes.push('dash→comma'); return ', '; }));
   out = out.replace(/(<h[1-4][^>]*>)([\s\S]*?[a-z0-9)])\.(\s*<\/h[1-4]>)/gi, (m, a, b, c) => { fixes.push('title-period'); return a + b + c; });
+  // Inject the balance/pretty rule nimiq.com applies to EVERY heading — the mechanical cure for
+  // orphaned-title line breaks. Non-destructive (only affects wrapping), and only added once.
+  if (!/text-wrap\s*:\s*(balance|pretty)/i.test(out)) {
+    const block = '\n<style>/* nq --fix: nimiq balances headings + prettifies body so no line strands a lone word */\nh1,h2,h3,h4{text-wrap:balance}\np,li,blockquote,figcaption{text-wrap:pretty}</style>\n';
+    if (/<\/head>/i.test(out)) { out = out.replace(/<\/head>/i, block + '</head>'); fixes.push('text-wrap:balance'); }
+    else if (/<body[^>]*>/i.test(out)) { out = out.replace(/(<body[^>]*>)/i, `$1${block}`); fixes.push('text-wrap:balance'); }
+  }
   return { out, fixes };
 }
 
@@ -247,8 +408,8 @@ export async function lint(target, opts = {}) {
   if (!isUrl && !existsSync(filePath)) throw new Error(`no such file: ${target}`);
   const url = isUrl ? target : pathToFileURL(filePath).href;
 
-  const { chromium } = await import('playwright');
-  const browser = await chromium.launch();
+  const { launchChromium } = await import('./_browser.mjs');
+  const browser = await launchChromium('nq lint');
   const out = (s = '') => console.log(s);
   let errorCount = 0, warnCount = 0;
   try {
@@ -277,6 +438,10 @@ export async function lint(target, opts = {}) {
       ['borders on inputs', r.inputBorders.length, r.inputBorders[0], 'inset box-shadow'],
       ['off-palette colors', offPal.length, offPal[0] && `${offPal[0][0]} (≈${offPal[0][1].near}, Δ${offPal[0][1].d})`, 'manual'],
       ['low-contrast blue/navy text on dark', r.blueOnDark.length, r.blueOnDark[0] && `${r.blueOnDark[0].fg} on ${r.blueOnDark[0].bg} = ${r.blueOnDark[0].ratio}:1 "${r.blueOnDark[0].snippet}"`, 'white / #0CA6FE'],
+      ['generic icon set (Lucide / FA / Material…)', r.genericIcon.length, r.genericIcon[0], 'use nq-icon SVGs'],
+      ['duplicate gradient id (SVGs misrender)', r.dupGradIds.length, r.dupGradIds[0], 'unique ids'],
+      ['pure-black surface (rule 6)', r.blackBg.length, r.blackBg[0], 'navy #1F2348'],
+      ['one-sided accent stripe (rule 19)', r.accentStripe.length, r.accentStripe[0], 'uniform border'],
     ];
     errorCount = errs.reduce((n, e) => n + e[1], 0);
 
@@ -284,11 +449,19 @@ export async function lint(target, opts = {}) {
     const topOff = Object.entries(r.offScale).sort((a, b) => b[1] - a[1]).slice(0, 6);
     const topRad = Object.entries(r.offRadius).sort((a, b) => b[1] - a[1]).slice(0, 5);
     const sizes = Object.keys(r.fontSizes).map(Number).sort((a, b) => a - b);
+    const offFont = Object.entries(r.offFont).filter(([, n]) => n >= 3).sort((a, b) => b[1] - a[1]);
     const warns = [
       ['body text wider than ~88ch', r.wideText.length, r.wideText.length && `worst ${Math.max(...r.wideText.map((w) => w.ch))}ch`],
       ['dense sections (>18% text ink)', r.denseSections.length, r.denseSections.slice(0, 4).map((d) => `${d.pct}% <${d.tag}.${d.cls}>`).join('  ')],
       ['off-scale spacing (snap to scale)', topOff.length, `${scalePct}% on-scale · ${topOff.map(([v, n]) => `${v}px×${n}`).join(' ')}`],
       ['type-scale sprawl', sizes.length > FONT_SPRAWL_WARN ? sizes.length : 0, `${sizes.length} sizes [${sizes.join(',')}]`],
+      ['faux-black headline weight (≥800; nimiq ≤700)', r.fauxWeight.length, r.fauxWeight[0]],
+      ['tight negative heading tracking (nimiq = 0)', r.tightTrack.length, r.tightTrack[0]],
+      ['wrapping heading w/o text-wrap: balance', r.headingNoBalance.length, r.headingNoBalance[0]],
+      ['orphaned last word (1-word final line)', r.orphanLine.length, r.orphanLine[0]],
+      ['heading line-height off (nimiq 1.25–1.3)', r.tightLeadingH.length, r.tightLeadingH[0]],
+      ['cramped body line-height (<1.35; nimiq 1.5)', r.tightLeadingBody.length, r.tightLeadingBody[0]],
+      ['non-brand font on text (Mulish / Fira only)', offFont.length, offFont.map(([f, n]) => `${f}×${n}`).join(' ')],
       ['uppercase eyebrow (colored / long / pill)', r.uppercase.length, r.uppercase[0]],
       ['non-pill action buttons', r.nonPill.length, r.nonPill[0]],
       ['flat-fill colored button (needs gradient)', r.flatColorBtn.length, r.flatColorBtn[0]],
@@ -299,6 +472,15 @@ export async function lint(target, opts = {}) {
       ['underlined links (use bold, no underline)', r.linkUnderline.length, r.linkUnderline[0]],
       ['NIM address not in Fira Mono', r.addrNotMono.length, r.addrNotMono[0]],
       ['gold-tinted UI icon (gold = logo only)', r.goldIcon.length, r.goldIcon[0]],
+      ['feather/lucide-style stroke icon (inlined)', r.featherIcon.length, r.featherIcon[0]],
+      ['baked-color icon (use currentColor)', r.bakedIcon.length, r.bakedIcon[0]],
+      ['black-outline duotone icon', r.duotoneBlack.length, r.duotoneBlack[0]],
+      ['green action / retry button (green = success)', r.greenAction.length, r.greenAction[0]],
+      ['colored glow shadow (navy elevation only)', r.glowShadow.length, r.glowShadow[0]],
+      ['black modal overlay (use navy rgba)', r.modalBlack.length, r.modalBlack[0]],
+      ['flat-fill navy/colored section (use radial)', r.flatNavySection.length, r.flatNavySection[0]],
+      ['focus outline removed w/o :focus-visible', r.noFocusRing ? 1 : 0, r.noFocusRing ? 'add a :focus-visible ring' : ''],
+      ['Mulish not loaded (system-font fallback)', r.fontsNotLoaded ? 1 : 0, r.fontsNotLoaded ? 'load Mulish' : ''],
       ['mobile horizontal overflow @390px', mob.overflowPx > 4 ? 1 : 0, `${mob.overflowPx}px`],
       ['mobile tap targets < 36px', mob.smallTargetN, mob.smallTargets[0]],
       ['text smaller than 12px @390px', mob.tinyText, `${mob.tinyText} element type(s)`],

package/scripts/verify.mjs

@@ -18,7 +18,7 @@ export async function verify(name) {
   if (!existsSync(demo)) return { status: 'skip', reason: 'no html/demo.html' };
   if (!existsSync(ref)) return { status: 'skip', reason: 'no reference.png' };
 
-  const { chromium } = await import('playwright');
+  const { launchChromium } = await import('./_browser.mjs');
   const { PNG } = await import('pngjs');
   const pixelmatch = (await import('pixelmatch')).default;
 
@@ -26,7 +26,7 @@ export async function verify(name) {
   const viewport = v.viewport ?? { width: 800, height: 600 };
   const threshold = v.maxDiffPct ?? 1.0; // percent of pixels allowed to differ
 
-  const browser = await chromium.launch();
+  const browser = await launchChromium('nq verify');
   try {
     const page = await browser.newPage({ viewport, deviceScaleFactor: v.scale ?? 2 });
     await page.goto('file://' + demo);

package/test/align.test.mjs

@@ -62,7 +62,7 @@ test('HARD FAIL: @nimiq/core/web import in src → settlement risky-fail', async
   await rm(dir, { recursive: true, force: true });
 });
 
-test('HARD FAIL: Client.create( and waitForConsensusEstablished( in src', async () => {
+test('HARD FAIL: Client.create( in src → settlement risky-fail (Client.create is the light-client tell)', async () => {
   const dir = await tmpApp({
     'nimiq-stack.json': canonicalManifest(),
     'Dockerfile': 'x', 'fly.toml': 'x', '.github/workflows/ci.yml': 'x',
@@ -71,7 +71,31 @@ test('HARD FAIL: Client.create( and waitForConsensusEstablished( in src', async
   const r = await alignApp(dir);
   assert.equal(r.axes.settlement.verdict, RISKY);
   assert.ok(r.axes.settlement.lines.some(l => l.includes('Client.create(')));
-  assert.ok(r.axes.settlement.lines.some(l => l.includes('waitForConsensusEstablished(')));
+  // waitForConsensusEstablished( is a legit NimiqClientLike interface / rpc-client method — NOT forbidden.
+  assert.ok(!r.axes.settlement.lines.some(l => l.includes('waitForConsensusEstablished(')), 'waitForConsensusEstablished must not be flagged');
+  await rm(dir, { recursive: true, force: true });
+});
+
+test('the canonical rpc-block-scan client (implements waitForConsensusEstablished) is NOT flagged', async () => {
+  const dir = await tmpApp({
+    'nimiq-stack.json': canonicalManifest(),
+    'Dockerfile': 'x', 'fly.toml': 'x', '.github/workflows/ci.yml': 'x',
+    'src/payments/nimiq-rpc-client.ts': 'export class RpcNimiqClient {\n  async waitForConsensusEstablished() { /* RPC poll of isConsensusEstablished */ }\n}\n',
+    'src/payments/nimiq-provider.ts': 'export interface NimiqClientLike {\n  waitForConsensusEstablished(): Promise<void>;\n}\n',
+  });
+  const r = await alignApp(dir);
+  assert.notEqual(r.axes.settlement.verdict, RISKY, 'the canonical rpc client + interface must stay clean');
+  await rm(dir, { recursive: true, force: true });
+});
+
+test('forbidden light-client strings inside a *.test.* file are ignored', async () => {
+  const dir = await tmpApp({
+    'nimiq-stack.json': canonicalManifest(),
+    'Dockerfile': 'x', 'fly.toml': 'x', '.github/workflows/ci.yml': 'x',
+    'src/chain.test.ts': "import x from '@nimiq/core/web';\nconst c = Client.create(cfg);\n",
+  });
+  const r = await alignApp(dir);
+  assert.notEqual(r.axes.settlement.verdict, RISKY, 'test/spec files are excluded from the light-client scan');
   await rm(dir, { recursive: true, force: true });
 });
 

package/test/check.test.mjs

@@ -0,0 +1,125 @@
+// Tests for `nq check` — the per-project alignment gate, and the pre-push hook.
+// node:test style, matching test/align.test.mjs.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { existsSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const { check } = await import(join(ROOT, 'scripts', 'check.mjs'));
+const hooks = await import(join(ROOT, 'scripts', 'hooks.mjs'));
+
+async function tmpApp(files) {
+  const dir = await mkdtemp(join(tmpdir(), 'nq-check-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const full = join(dir, rel);
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, typeof content === 'string' ? content : JSON.stringify(content, null, 2));
+  }
+  return dir;
+}
+
+// a clean, canonical chain app manifest (mirrors test/align.test.mjs)
+const canonicalManifest = (over = {}) => ({
+  schemaVersion: 1, name: 'app', chainApp: true, exempt: false, exemptReason: null,
+  stack: { framework: 'vanilla-pwa', server: 'hono@^4.7', runtime: 'bun', build: 'none', packageManager: 'bun' },
+  styling: { source: 'nimiq-ui' },
+  settlement: { pattern: 'rpc-block-scan', lib: 'inline', coreRole: 'offline-crypto-only' },
+  deploy: { target: 'fly' },
+  config: { tsconfig: 'local-strict', lint: 'none', fileSizeGuard: 800, ci: true },
+  canonicalVersion: '0.1.0',
+  ...over,
+});
+
+test('a clean canonical app → check passes (exit 0), align PASS', async () => {
+  const dir = await tmpApp({
+    'nimiq-stack.json': canonicalManifest(),
+    'Dockerfile': 'FROM oven/bun:1\n', 'fly.toml': 'app="x"\n',
+    '.github/workflows/ci.yml': 'name: ci\n',
+    // no package.json test script + no index.html → those sections SKIP, never FAIL
+    'src/server.ts': 'export const x = 1;\n',
+  });
+  const r = await check(dir);
+  assert.equal(r.ok, true, JSON.stringify(r.sections, null, 2));
+  assert.equal(r.sections.align.verdict, 'pass');
+  assert.equal(r.sections.filesize.verdict, 'pass');
+  // no test script → SKIP, no index.html → SKIP (skips don't fail the gate)
+  assert.ok(['skip', 'pass'].includes(r.sections.test.verdict));
+  assert.equal(r.sections.lint.verdict, 'skip');
+  await rm(dir, { recursive: true, force: true });
+});
+
+test('a dir with @nimiq/core/web + Client.create + chainApp manifest → check FAILS', async () => {
+  const dir = await tmpApp({
+    'nimiq-stack.json': canonicalManifest(),
+    'Dockerfile': 'x', 'fly.toml': 'x', '.github/workflows/ci.yml': 'x',
+    'src/boot.ts': "import { Client } from '@nimiq/core/web';\nconst c = Client.create(cfg);\n",
+  });
+  const r = await check(dir);
+  assert.equal(r.ok, false);
+  assert.equal(r.sections.align.verdict, 'fail');
+  assert.ok(r.sections.align.lines.some(l => l.includes('@nimiq/core/web')));
+  await rm(dir, { recursive: true, force: true });
+});
+
+test('an oversized first-party src file → filesize section FAILS the gate', async () => {
+  const big = Array.from({ length: 850 }, (_, i) => `const l${i} = ${i};`).join('\n') + '\n';
+  const dir = await tmpApp({
+    'nimiq-stack.json': canonicalManifest(),
+    'Dockerfile': 'x', 'fly.toml': 'x', '.github/workflows/ci.yml': 'x',
+    'src/huge.ts': big,
+  });
+  const r = await check(dir);
+  assert.equal(r.sections.filesize.verdict, 'fail');
+  assert.ok(r.sections.filesize.lines.some(l => l.includes('src/huge.ts')));
+  assert.equal(r.ok, false);
+  await rm(dir, { recursive: true, force: true });
+});
+
+test('filesize honors per-repo fileSizeGuardExclude in the manifest', async () => {
+  const big = Array.from({ length: 850 }, (_, i) => `const l${i} = ${i};`).join('\n') + '\n';
+  const dir = await tmpApp({
+    'nimiq-stack.json': canonicalManifest({
+      config: { tsconfig: 'local-strict', lint: 'none', fileSizeGuard: 800, ci: true, fileSizeGuardExclude: ['src/generated.ts'] },
+    }),
+    'Dockerfile': 'x', 'fly.toml': 'x', '.github/workflows/ci.yml': 'x',
+    'src/generated.ts': big,
+    'src/app.ts': 'export const ok = 1;\n', // a real, in-scope file so the scan isn't empty
+  });
+  const r = await check(dir);
+  assert.equal(r.sections.filesize.verdict, 'pass', JSON.stringify(r.sections.filesize, null, 2));
+  await rm(dir, { recursive: true, force: true });
+});
+
+test('lint section SKIPs (never FAILs) when there is no index.html', async () => {
+  const dir = await tmpApp({
+    'nimiq-stack.json': canonicalManifest(),
+    'Dockerfile': 'x', 'fly.toml': 'x', '.github/workflows/ci.yml': 'x',
+    'src/server.ts': 'export const x = 1;\n',
+  });
+  const r = await check(dir);
+  assert.equal(r.sections.lint.verdict, 'skip');
+  await rm(dir, { recursive: true, force: true });
+});
+
+test('hooks install writes an executable pre-push that runs the check/align gate', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'nq-prepush-'));
+  const { execFileSync } = await import('node:child_process');
+  execFileSync('git', ['init', '-q'], { cwd: dir });
+  const r = await hooks.installHooks(dir);
+  const pushPath = join(dir, '.git', 'hooks', 'pre-push');
+  assert.ok(r.wrote.includes(pushPath), 'pre-push should be in wrote[]');
+  assert.ok(existsSync(pushPath));
+  assert.ok(statSync(pushPath).mode & 0o100, 'pre-push must be executable');
+  const { readFile } = await import('node:fs/promises');
+  const body = await readFile(pushPath, 'utf8');
+  assert.ok(/nq (check|align) --fail-on=settlement,styling/.test(body), 'pre-push must run the gate');
+  await rm(dir, { recursive: true, force: true });
+});
+
+test('PRE_PUSH artifact contains the check/align gate command', () => {
+  assert.ok(/nq (check|align) --fail-on=settlement,styling/.test(hooks.PRE_PUSH));
+});