Use OG-only HIG fonts in docs (bloxwap/hig#115)

.github/workflows/docs.yml

@@ -37,7 +37,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           repository: bloxwap/hig
-          ref: 872906a9071469af8714b3b6fb5cc7bd64d2d6f3
+          ref: e3390bbd0ac12b9d4b371175bd250d01ea866abe
           path: .hig
           sparse-checkout: scripts/drift.mjs
           sparse-checkout-cone-mode: false

apps/docs/app/global.css

@@ -2,6 +2,7 @@
 @import 'fumadocs-ui/css/neutral.css';
 @import 'fumadocs-ui/css/preset.css';
 @import '@bloxwap/hig-tokens/css';
+@import '@bloxwap/hig-react/css/base';
 @import '@bloxwap/hig-react/css';
 
 @theme inline {

apps/docs/lib/og-card.tsx

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
-import { createRequire } from 'node:module';
 import { join } from 'node:path';
+import { readOgFont } from '@bloxwap/hig-og-fonts/node';
 import { tokens } from '@bloxwap/hig-tokens';
 import { ImageResponse } from 'next/og';
 import { socialImageSize } from './social';
@@ -13,12 +13,11 @@ const { colors } = tokens;
 const ink = colors.text.srgb;
 const muted = colors.muted.srgb;
 const bar: [color: string, share: number][] = [[colors.action.srgb, 62], [colors.info.srgb, 14], ['#b300ff', 10], ['#ff479c', 8], ['#fffb38', 6]];
-// Satori reads static TTFs, which @bloxwap/font (WOFF2 only) does not ship. These approved static Bloxwap Sans instances
-// (derived from @bloxwap/font 0.1.2, OFL) come from @bloxwap/hig-native-fonts, a build-time dependency of this renderer.
-const hig = createRequire(join(process.cwd(), 'package.json'));
+// The OG-only build dependency verifies the approved static @bloxwap/font 0.1.2 TTFs.
+// Family names, weights and bytes remain identical to the previous social cards.
 const assets = Promise.all([
-  readFile(hig.resolve('@bloxwap/hig-native-fonts/fonts/BloxwapSans-Bold.ttf')),
-  readFile(hig.resolve('@bloxwap/hig-native-fonts/fonts/BloxwapSans-Black.ttf')),
+  readOgFont('BloxwapSans-Bold.ttf'),
+  readOgFont('BloxwapSans-Black.ttf'),
   readFile(join(process.cwd(), '../../packages/agent-cli/package.json'), 'utf8'),
 ]);
 

apps/docs/package.json

@@ -16,9 +16,9 @@
   },
   "dependencies": {
     "@bloxwap/font": "0.1.2",
-    "@bloxwap/hig-contracts": "file:../../vendor/bloxwap-hig/bloxwap-hig-contracts-0.1.0-candidate.sha872906a9.tgz",
-    "@bloxwap/hig-react": "file:../../vendor/bloxwap-hig/bloxwap-hig-react-0.1.0-candidate.sha872906a9.tgz",
-    "@bloxwap/hig-tokens": "file:../../vendor/bloxwap-hig/bloxwap-hig-tokens-0.1.0-candidate.sha872906a9.tgz",
+    "@bloxwap/hig-contracts": "file:../../vendor/bloxwap-hig/bloxwap-hig-contracts-0.1.0-candidate.shae3390bbd.tgz",
+    "@bloxwap/hig-react": "file:../../vendor/bloxwap-hig/bloxwap-hig-react-0.1.0-candidate.shae3390bbd.tgz",
+    "@bloxwap/hig-tokens": "file:../../vendor/bloxwap-hig/bloxwap-hig-tokens-0.1.0-candidate.shae3390bbd.tgz",
     "fumadocs-core": "16.15.14",
     "fumadocs-mdx": "15.4.5",
     "fumadocs-ui": "16.15.14",
@@ -28,7 +28,7 @@
     "react-dom": "^19.2.0"
   },
   "devDependencies": {
-    "@bloxwap/hig-native-fonts": "file:../../vendor/bloxwap-hig/bloxwap-hig-native-fonts-0.1.0-candidate.sha872906a9.tgz",
+    "@bloxwap/hig-og-fonts": "file:../../vendor/bloxwap-hig/bloxwap-hig-og-fonts-0.1.0-candidate.shae3390bbd.tgz",
     "@tailwindcss/postcss": "^4.2.0",
     "@types/mdx": "^2.0.13",
     "@types/node": "^24.13.6",

apps/docs/scripts/hig-tokens.mjs

@@ -1,10 +1,12 @@
 // Verifies the HIG package install: vendored candidate tarballs match their recorded hashes, the docs and the root
 // overrides depend on exactly those files, the installed packages are the same build, and app/global.css reads HIG
 // values through --hig-* roles instead of copying token numbers or bridging font families.
-import { readFile, stat } from 'node:fs/promises';
+import { readFile, readdir, stat } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import assert from 'node:assert/strict';
 import { tokens } from '@bloxwap/hig-tokens';
+import { ogFonts } from '@bloxwap/hig-og-fonts';
+import { readOgFont } from '@bloxwap/hig-og-fonts/node';
 import { assertNoCopiedHigTokens } from './hig-css-guard.mjs';
 
 const root = new URL('../../../', import.meta.url);
@@ -33,6 +35,17 @@ for (const { package: name, file, sha256 } of provenance.artifacts) {
   assert.equal(installed.version, provenance.version, `${name}: installed ${installed.version}, vendored ${provenance.version}; run npm install`);
 }
 assert.equal(tokens.version, provenance.version.split('-')[0]);
+assert.ok(!manifest.dependencies['@bloxwap/hig-native-fonts'] && !manifest.devDependencies?.['@bloxwap/hig-native-fonts'], 'OG cards must use the OG-only package');
+assert.ok(!(await readdir(vendor)).some(file => file.includes('hig-native-fonts')), 'Do not vendor the native font bundle for OG cards');
+assert.equal(provenance.ogFonts.length, 2, 'The renderer uses only the approved Bold and Black faces');
+for (const face of provenance.ogFonts) {
+  const descriptor = ogFonts.find(font => font.asset === face.asset);
+  assert.ok(descriptor, `${face.asset} must be a packaged OG face`);
+  for (const key of ['name', 'weight', 'style', 'sha256']) assert.equal(descriptor[key], face[key], `${face.asset}: ${key} must preserve the approved card face`);
+  const data = await readOgFont(face.asset);
+  assert.equal(data.length, face.bytes, `${face.asset}: approved byte length changed`);
+  assert.equal(createHash('sha256').update(data).digest('hex'), face.sha256, `${face.asset}: approved font bytes changed`);
+}
 
 const css = await readFile(new URL('app/global.css', docs), 'utf8');
 // Radius, motion, type, density and font families are CSS roles in @bloxwap/hig-tokens/css; a host copy would drift.
@@ -53,4 +66,4 @@ for (const path of ['vendor/hig', 'styles', 'fonts']) {
   await assert.rejects(stat(new URL(path, docs)), `apps/docs/${path} must not exist; use the HIG packages`);
 }
 assert.ok(!/--bloxwap-[\w-]+\s*:/.test(css), 'app/global.css must not define --bloxwap-* aliases; use --hig-* roles');
-console.log(`HIG ${provenance.version}: ${provenance.artifacts.length} vendored tarballs, installed packages and HIG role usage verified.`);
+console.log(`HIG ${provenance.version}: ${provenance.artifacts.length} vendored tarballs, installed packages, exact OG faces and HIG role usage verified.`);

docs/PROGRESS.md

@@ -76,6 +76,22 @@ The validated version-patch workflow prepared 0.2.0, consuming the pending
 changesets and synchronizing package/lock/skill versions and generated docs.
 This is release preparation; public npm installation is still pending.
 
+## HIG OG-font refresh — 2026-10-18
+
+| Issue | State | Notes |
+| --- | --- | --- |
+| bloxwap/hig#115 | partial | Original refresh validated against consumer baseline `76384c49`; current integration checks are recorded below. HIG `0.1.0-candidate.shae3390bbd` replaces the native-fonts dev dependency with the OG-only package. All 13 generated cards and the desktop/mobile comparison captures were byte-identical at that original baseline. |
+
+The clean lock install, root build/lint/typecheck, 103 CLI tests, docs production
+build/check (including two CSS guard tests), all 14 browser smoke checks and the
+pinned HIG drift check (41 files, zero exceptions) pass. The selected Bold/Black
+family, weights and font bytes are unchanged. The vendor set is 3,573,511 bytes
+smaller; the redundant HIG root file overrides are removed, while unrelated
+esbuild/mdast overrides remain. [Local evidence](../evidence/hig/og-font-refresh/README.md).
+
+The draft refresh PR tracks remote CI and central HIG adoption linkage. Package
+publication and deployment are outside this refresh.
+
 ## Testnet harness — 2026-10-18
 
 #39 now supports caller-controlled external wallet approvals alongside the
@@ -88,3 +104,14 @@ Runner shutdown is confirmed before journal export. Nightly CI maps
 `AGENT_CLI_PRIVY_APP_SECRET` from the `testnet` environment onto the harness
 `BLOXWAP_*` variables. Live journals and the independent coding-agent session
 are still not claimed.
+
+## HIG refresh integration — 2026-10-18
+
+Merged current main `bb242b8ef95ae238a65b779d427bff3813e6b267` into the
+existing HIG refresh branch, retaining upstream runner, testnet and npm-token changes.
+The exact four `e3390bbd` archives and dependency lock are unchanged. A fresh install,
+build, lint, types, 232 offline CLI tests, packed-package install, production docs
+build/check, 14 browser smoke checks and pinned drift check pass. Current 13-card
+output matches the historical manifest; earlier screenshot parity remains scoped to its
+original baseline. [Integration evidence](../evidence/hig/og-font-refresh/main-integration/report.json).
+[Draft PR #55](https://github.com/bloxwap/agent-cli/pull/55) tracks remote checks and adoption.

evidence/hig/og-font-refresh/README.md

@@ -0,0 +1,57 @@
+# agent-cli docs: OG-only font candidate refresh (hig#115)
+
+This isolated refresh adopts HIG `0.1.0-candidate.shae3390bbd` from
+[`e3390bbd`](https://github.com/bloxwap/hig/tree/e3390bbd0ac12b9d4b371175bd250d01ea866abe).
+The [candidate release report](candidate-report.json) records a clean source snapshot and no publication.
+
+The OG renderer now reads the approved Bold and Black TTFs with
+`@bloxwap/hig-og-fonts/node` `readOgFont()`. It keeps the `Bloxwap Sans` name, normal style,
+weights 700/900, and the exact prior bytes/SHA-256 values ([before](before.json), [after](after.json)).
+
+At original consumer baseline `76384c4911c9e69fafd17a55d3d004cf51a26ca0`, all **13 generated OG PNGs were byte-identical** to the pre-refresh production export.
+The desktop home/docs and 390 px home captures are also byte-identical, with no page errors or
+horizontal overflow ([browser comparison](browser-comparison.json)). Both builds use the same
+real deployment base path. The explicit `hig-react/css/base` import preserves the previous
+whole-page rules after HIG split them from component CSS.
+
+The vendor set drops from 4,454,889 B to 881,378 B (**−3,573,511B**). The native-fonts archive,
+dev dependency and lock entries are removed; no TTF is included in the static export.
+`vendor/bloxwap-hig/provenance.json` and the docs guard verify all four archive hashes, installed
+candidate versions and the exact selected font faces.
+
+Original refresh validated locally on Node 24.10.0 / npm 11.5.1:
+
+- Fresh lock resolution and `npm ci`, without compatibility flags.
+- Root build, lint, typecheck and **103 tests** ([log](root-gates.log)).
+- Production default-Turbopack docs build: **13 cards** ([log](after-build.log)).
+- Docs provenance/font/type gates ([log](docs-check.log)).
+- Existing Chromium docs smoke: **14 checks** against the local production export ([log](docs-smoke.log)).
+- Before/after browser captures and all-card byte comparison ([report](report.json)).
+- Scoped anti-drift from the same HIG commit: 41 files, 0 exceptions ([log](drift.log)).
+
+The old-lock update attempted to fetch an unpublished transitive candidate. Moving the generated
+install/lock aside and resolving the coherent file dependencies from scratch avoided that fetch.
+The redundant HIG root file overrides also resolved under `apps/docs` on fresh npm resolution;
+they have been removed. The unrelated esbuild/mdast overrides remain.
+
+Package publication and deployment are outside this refresh. Remote CI and the central HIG
+adoption linkage are tracked through the draft refresh PR.
+
+## Current main integration — 2026-10-18
+
+Merged `origin/main` at `bb242b8ef95ae238a65b779d427bff3813e6b267` into the original refresh head
+`a2798c7fd09c4f4efa95dad138ea889937f349d5` without rewriting history. The only conflict was the progress-log
+append; both sections and upstream npm-token publication status are retained. Upstream
+Mac runner, Colima install, testnet and generated skill changes remain intact.
+
+The [integration report](main-integration/report.json) records a fresh frozen install,
+build/lint/types, **232 CLI tests**, packed-package installation, production docs build/check
+(two CSS guard tests), **14 browser smoke checks** and the pinned drift check (41 files,
+zero exceptions). Node 24.15.0 / npm 11.5.1 match the workflow Node 24 major. All four
+`e3390bbd` archives, the lockfile and selected OG font bytes remain unchanged; no
+candidate was regenerated. The current 13-card manifest matches the historical manifest.
+The original screenshot-parity claim above applies only to its recorded baseline; current
+main browser validation uses the production smoke checks, without a new screenshot-parity claim.
+
+[PR #55](https://github.com/bloxwap/agent-cli/pull/55) records current remote checks and
+mergeability. No credentialed testnet run, publication or deployment was performed.

evidence/hig/og-font-refresh/after-browser.json

@@ -0,0 +1,90 @@
+{
+  "engine": "chromium",
+  "browser": "156.0.8078.4",
+  "node": "v24.6.0",
+  "basePath": "/agent-cli",
+  "pages": [
+    {
+      "route": "/",
+      "status": 200,
+      "title": "@bloxwap/agent-cli — Hyperliquid trading for agents",
+      "controls": {
+        "body": {
+          "fontFamily": "BloxwapSans, \"Bloxwap Sans Scripts\", ui-rounded, system-ui, sans-serif, system-ui, sans-serif",
+          "fontSize": "16px",
+          "background": "color(display-p3 0.04 0.04 0.04)",
+          "padding": "0px",
+          "boxSizing": "border-box",
+          "outlineStyle": "none",
+          "outlineWidth": "3px",
+          "width": 1425,
+          "height": 1686.5625
+        },
+        ".hig-button": {
+          "fontFamily": "BloxwapSans, \"Bloxwap Sans Scripts\", ui-rounded, system-ui, sans-serif, system-ui, sans-serif",
+          "fontSize": "16px",
+          "background": "color(display-p3 0 1 0.24)",
+          "padding": "8px 20px",
+          "boxSizing": "border-box",
+          "outlineStyle": "none",
+          "outlineWidth": "3px",
+          "width": 146.203125,
+          "height": 44
+        },
+        "table th": null,
+        "a": {
+          "fontFamily": "BloxwapSans, \"Bloxwap Sans Scripts\", ui-rounded, system-ui, sans-serif, system-ui, sans-serif",
+          "fontSize": "16px",
+          "background": "rgba(0, 0, 0, 0)",
+          "padding": "0px",
+          "boxSizing": "border-box",
+          "outlineStyle": "none",
+          "outlineWidth": "3px",
+          "width": 114.984375,
+          "height": 28
+        }
+      }
+    },
+    {
+      "route": "/docs/",
+      "status": 200,
+      "title": "Overview and installation · @bloxwap/agent-cli",
+      "controls": {
+        "body": {
+          "fontFamily": "BloxwapSans, \"Bloxwap Sans Scripts\", ui-rounded, system-ui, sans-serif, system-ui, sans-serif",
+          "fontSize": "16px",
+          "background": "color(display-p3 0.04 0.04 0.04)",
+          "padding": "0px",
+          "boxSizing": "border-box",
+          "outlineStyle": "none",
+          "outlineWidth": "3px",
+          "width": 1425,
+          "height": 1060.03125
+        },
+        ".hig-button": null,
+        "table th": null,
+        "a": {
+          "fontFamily": "BloxwapSans, \"Bloxwap Sans Scripts\", ui-rounded, system-ui, sans-serif, system-ui, sans-serif",
+          "fontSize": "16px",
+          "background": "rgba(0, 0, 0, 0)",
+          "padding": "0px",
+          "boxSizing": "border-box",
+          "outlineStyle": "none",
+          "outlineWidth": "3px",
+          "width": 0,
+          "height": 0
+        }
+      }
+    }
+  ],
+  "mobile": {
+    "width": 390,
+    "noHorizontalOverflow": true
+  },
+  "ogHome": {
+    "status": 200,
+    "sha256": "9df0ba67da7172bb8700f7cf8e1355709116d0031800e07fb7e74cdbfa9eb33c",
+    "matchesBaseline": true
+  },
+  "errors": []
+}

evidence/hig/og-font-refresh/after-build.log

@@ -0,0 +1,66 @@
+
+> docs:build
+> npm --workspace @bloxwap/agent-cli-docs run build
+
+
+> @bloxwap/[email protected] prebuild
+> npm --workspace @bloxwap/agent-cli run build && node scripts/generate-content.mjs && node scripts/prepare-public.mjs
+
+
+> @bloxwap/[email protected] build
+> node scripts/generate-skill.mjs && tsup src/cli.ts --format esm --clean && node scripts/finalize-build.mjs
+
+CLI Building entry: src/cli.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Target: es2022
+CLI Cleaning output folder
+ESM Build start
+ESM dist/cli.js 131.88 KB
+ESM ⚡️ Build success in 57ms
+Command schemas, skill guide and public SKILL.md synchronized.
+
+> @bloxwap/[email protected] build
+> next build
+
+▲ Next.js 16.3.6 (Turbopack)
+[MDX] generated files in 7.088416999999993ms
+✓ Running next.config.mjs took 204ms
+
+  Creating an optimized production build ...
+✓ Compiled successfully in 1305ms
+  Running TypeScript ...
+  Finished TypeScript in 1396ms ...
+  Collecting page data using 8 workers ...
+  Generating static pages using 8 workers (0/30) ...
+  Generating static pages using 8 workers (7/30) 
+  Generating static pages using 8 workers (14/30) 
+  Generating static pages using 8 workers (22/30) 
+✓ Generating static pages using 8 workers (30/30) in 678ms
+  Finalizing page optimization ...
+
+Route (app)
+┌ ○ /
+├ ○ /_not-found
+├   /docs/[[...slug]]
+│ ├ ● /docs/audit
+│ ├ ● /docs/commands
+│ ├ ● /docs/config
+│ └ ● [+9 more paths]
+├   /og/[...slug]
+│ ├ ● /og/home.png
+│ ├ ● /og/docs/audit.png
+│ ├ ● /og/docs/commands.png
+│ └ ● [+10 more paths]
+├ ○ /search.json
+└ ○ /sitemap.xml
+
+
+○  (Static)  prerendered as static content
+●  (SSG)     prerendered as static HTML (uses generateStaticParams)
+
+
+> @bloxwap/[email protected] postbuild
+> node scripts/check-export.mjs
+
+Static export verified: 16 HTML pages, 598 local links/assets, 13 social cards, basePath "/agent-cli".