@crossworks/client-types 0.230.43

package/src/display-fonts.ts

@@ -0,0 +1,483 @@
+/**
+ * Font registry — the SINGLE source of truth for every user-selectable face
+ * (Settings → Appearance).
+ *
+ * One list drives everything: the `@font-face` block (generated by
+ * `displayFontFaceCss`, injected once in the root layout and in the server-
+ * rendered share/print shell), the selection modal, and the runtime CSS-var
+ * overrides in `FontProvider`. There are FOUR slots that pick from it — the
+ * interface, the wordmark, the peer name, and Pages/Notes prose — and one
+ * library behind all four, because "which faces exist" and "where a face is
+ * used" are different questions and only the second one varies per slot.
+ *
+ * ── Every face here is a VARIABLE font with at least two axes ────────────────
+ *
+ * The ranges below are not typed by hand. They are read out of each file's
+ * `fvar` table by `scripts/fonts-import.mjs`, which also converts to woff2 and
+ * installs into both apps. That matters more than it sounds: a variable face
+ * declared as a single weight makes the browser SYNTHESISE bold, which shows up
+ * across the interface as smeared headings and buttons. Add a face by running
+ * the importer and pasting its row, never by editing a range by eye.
+ *
+ * Three axes have real `@font-face` descriptors and are declared per face:
+ * `wght` → font-weight, `wdth` → font-stretch, `slnt` → font-style: oblique.
+ * A face with a `slnt` axis therefore needs NO italic file: the one file leans
+ * on demand. Everything else a face carries (opsz, GRAD, WONK, SOFT, ROND, the
+ * Roboto Flex zoo) is recorded in `axes` as documentation only — `opsz` the
+ * browser applies on its own, the rest sit at their defaults because nothing
+ * sets font-variation-settings. They are listed so the next person can see what
+ * a face is capable of before wiring a control to it.
+ *
+ * Loading is lazy by construction: a browser fetches a font file only when it
+ * actually paints text in that family, so declaring ~20 `@font-face` rules costs
+ * nothing until a face is *selected* (or previewed while the modal is open). The
+ * runtime cost is the chosen faces, not the library. This is why we can ship
+ * variety without eager-bundling everything (unlike `next/font`, which is right
+ * for the always-loaded default UI face and wrong for an opt-in library).
+ *
+ * Two entries carry no library file. `inherit` means "follow the interface
+ * font", which is the sane default for the peer name and for prose. `inter` is
+ * the always-loaded next/font face (client/web/lib/fonts.ts, served from
+ * public/Inter) — it stays out of the library so its ~700K of roman+italic is
+ * not shipped twice.
+ */
+
+export type FontFallback = 'sans-serif' | 'serif' | 'monospace';
+
+/** Which shelf of the selection modal a face sits on. */
+export type FontShelf = 'sans' | 'serif' | 'mono' | 'display';
+
+export type FontFace = {
+  /** Stable slug stored in preferences + used as the file basename. */
+  key: string;
+  /** Human label shown in the modal. */
+  label: string;
+  /** CSS `font-family` name declared by our `@font-face` (null for the two
+   *  entries that resolve to an existing family instead). */
+  family: string | null;
+  /** Generic fallback appended after the family. */
+  fallback: FontFallback;
+  /** The modal's grouping. */
+  shelf: FontShelf;
+  /** Public path to the upright face file, or null for `inherit` / `inter`. */
+  file: string | null;
+  /** Public path to a real italic file, when the family ships one and the face
+   *  is one you would set a document in. A face with a `slnt` axis needs none
+   *  (see `style`); a face with neither leaves the browser to synthesise. */
+  italicFile?: string;
+  /** `font-weight` descriptor — the file's real `wght` range. */
+  weight?: string;
+  /** `font-stretch` descriptor — the file's real `wdth` range. The older
+   *  spelling of `font-width`, and the one every browser that can render Mantle
+   *  already accepts. */
+  stretch?: string;
+  /** `font-style` descriptor for a `slnt` axis, as an oblique range. Note the
+   *  sign flip the importer applies: OpenType measures slant counter-clockwise,
+   *  CSS measures it clockwise. */
+  style?: string;
+  /** Axes with no CSS descriptor, for documentation. */
+  axes?: string[];
+};
+
+const LIB = '/fonts/library';
+
+/** The default for each of the four slots. "Default" is the ABSENCE of the
+ *  stored value and of the CSS var — see resolveFontVars. */
+export const DEFAULT_UI_FONT = 'inter';
+export const DEFAULT_LOGO_FONT = 'bricolage-grotesque';
+export const DEFAULT_TITLE_FONT = 'inherit';
+export const DEFAULT_PROSE_FONT = 'inherit';
+
+/**
+ * Keys that used to exist and no longer do resolve to nothing, which every
+ * caller already treats as "fall back to the default" — trimming the library
+ * has always been safe. `sans` is the one exception worth mapping rather than
+ * dropping: it was the old name for "follow the interface font" and was the
+ * shipped default for the peer name, so a brain that stored it explicitly
+ * should keep the behaviour it chose, not silently acquire a concrete face.
+ */
+const LEGACY_KEYS: Record<string, string> = { sans: 'inherit' };
+
+export const FONT_LIBRARY: FontFace[] = [
+  // ── the two that resolve to an existing family ────────────────────────────
+  {
+    key: 'inherit',
+    label: 'Same as interface',
+    family: null,
+    fallback: 'sans-serif',
+    shelf: 'sans',
+    file: null,
+  },
+  {
+    key: 'inter',
+    label: 'Inter',
+    family: null,
+    fallback: 'sans-serif',
+    shelf: 'sans',
+    file: null,
+  },
+  // ── sans ──────────────────────────────────────────────────────────────────
+  {
+    key: 'afacad-flux',
+    label: 'Afacad Flux',
+    family: 'Afacad Flux',
+    fallback: 'sans-serif',
+    shelf: 'sans',
+    file: `${LIB}/afacad-flux.woff2`,
+    weight: '100 1000',
+    // Leans BOTH ways: the slnt axis runs -14 to +14, so this one file covers
+    // upright, italic, and a backslant nothing in the UI asks for.
+    style: 'oblique -14deg 14deg',
+  },
+  {
+    key: 'bricolage-grotesque',
+    label: 'Bricolage Grotesque',
+    family: 'Bricolage Grotesque',
+    fallback: 'sans-serif',
+    shelf: 'sans',
+    file: `${LIB}/bricolage-grotesque.woff2`,
+    weight: '200 800',
+    stretch: '75% 100%',
+    axes: ['opsz'],
+  },
+  {
+    key: 'dm-sans',
+    label: 'DM Sans',
+    family: 'DM Sans',
+    fallback: 'sans-serif',
+    shelf: 'sans',
+    file: `${LIB}/dm-sans.woff2`,
+    italicFile: `${LIB}/dm-sans-italic.woff2`,
+    weight: '100 1000',
+    axes: ['opsz'],
+  },
+  {
+    key: 'google-sans-flex',
+    label: 'Google Sans Flex',
+    family: 'Google Sans Flex',
+    fallback: 'sans-serif',
+    shelf: 'sans',
+    // By far the heaviest face in the library (~1.9M packed, six axes). It is
+    // here because it is genuinely the most flexible one, and lazy loading
+    // means only a brain that selects it ever pays for it.
+    file: `${LIB}/google-sans-flex.woff2`,
+    weight: '1 1000',
+    stretch: '25% 151%',
+    style: 'oblique 0deg 10deg',
+    axes: ['opsz', 'GRAD', 'ROND'],
+  },
+  {
+    key: 'instrument-sans',
+    label: 'Instrument Sans',
+    family: 'Instrument Sans',
+    fallback: 'sans-serif',
+    shelf: 'sans',
+    file: `${LIB}/instrument-sans.woff2`,
+    italicFile: `${LIB}/instrument-sans-italic.woff2`,
+    // A genuinely narrow weight range. Declared honestly rather than padded to
+    // 100-900: a range wider than the file's own is clamped, but a caller
+    // reading this row should see what it can actually do.
+    weight: '400 700',
+    stretch: '75% 100%',
+  },
+  {
+    key: 'nunito-sans',
+    label: 'Nunito Sans',
+    family: 'Nunito Sans',
+    fallback: 'sans-serif',
+    shelf: 'sans',
+    file: `${LIB}/nunito-sans.woff2`,
+    italicFile: `${LIB}/nunito-sans-italic.woff2`,
+    weight: '200 1000',
+    stretch: '75% 125%',
+    axes: ['opsz', 'YTLC'],
+  },
+  {
+    key: 'roboto-flex',
+    label: 'Roboto Flex',
+    family: 'Roboto Flex',
+    fallback: 'sans-serif',
+    shelf: 'sans',
+    file: `${LIB}/roboto-flex.woff2`,
+    weight: '100 1000',
+    stretch: '25% 151%',
+    style: 'oblique 0deg 10deg',
+    axes: ['opsz', 'GRAD', 'XOPQ', 'YOPQ', 'XTRA', 'YTUC', 'YTLC', 'YTAS', 'YTDE', 'YTFI'],
+  },
+  {
+    key: 'saira',
+    label: 'Saira',
+    family: 'Saira',
+    fallback: 'sans-serif',
+    shelf: 'sans',
+    file: `${LIB}/saira.woff2`,
+    italicFile: `${LIB}/saira-italic.woff2`,
+    weight: '100 900',
+    stretch: '50% 125%',
+  },
+  {
+    key: 'signika',
+    label: 'Signika',
+    family: 'Signika',
+    fallback: 'sans-serif',
+    shelf: 'sans',
+    file: `${LIB}/signika.woff2`,
+    weight: '300 700',
+    axes: ['GRAD'],
+  },
+  // ── serif ─────────────────────────────────────────────────────────────────
+  {
+    key: 'playfair',
+    label: 'Playfair',
+    family: 'Playfair',
+    fallback: 'serif',
+    shelf: 'serif',
+    file: `${LIB}/playfair.woff2`,
+    italicFile: `${LIB}/playfair-italic.woff2`,
+    weight: '300 900',
+    stretch: '87.5% 112.5%',
+    axes: ['opsz'],
+  },
+  {
+    key: 'fraunces',
+    label: 'Fraunces',
+    family: 'Fraunces',
+    fallback: 'serif',
+    shelf: 'serif',
+    file: `${LIB}/fraunces.woff2`,
+    italicFile: `${LIB}/fraunces-italic.woff2`,
+    weight: '100 900',
+    // SOFT and WONK are real axes on this face — the reason it is in the
+    // library at all. Unwired for now; see the note at the top of the file.
+    axes: ['opsz', 'SOFT', 'WONK'],
+  },
+  // ── mono ──────────────────────────────────────────────────────────────────
+  {
+    key: 'inconsolata',
+    label: 'Inconsolata',
+    family: 'Inconsolata',
+    fallback: 'monospace',
+    shelf: 'mono',
+    file: `${LIB}/inconsolata.woff2`,
+    weight: '200 900',
+    stretch: '50% 200%',
+  },
+  // ── display ───────────────────────────────────────────────────────────────
+  // Condensed and high-contrast faces: right for a wordmark or a peer name,
+  // wrong for a 13px table cell. They stay selectable for every slot anyway —
+  // the modal groups them so the choice is informed, and refusing a choice
+  // outright is not our job.
+  {
+    key: 'advent-pro',
+    label: 'Advent Pro',
+    family: 'Advent Pro',
+    fallback: 'sans-serif',
+    shelf: 'display',
+    file: `${LIB}/advent-pro.woff2`,
+    weight: '100 900',
+    // The wdth axis STARTS at its narrow default and only widens, so this face
+    // has no condensed end below 100%.
+    stretch: '100% 200%',
+  },
+  {
+    key: 'big-shoulders',
+    label: 'Big Shoulders',
+    family: 'Big Shoulders',
+    fallback: 'sans-serif',
+    shelf: 'display',
+    file: `${LIB}/big-shoulders.woff2`,
+    weight: '100 900',
+    axes: ['opsz'],
+  },
+  {
+    key: 'fredoka',
+    label: 'Fredoka',
+    family: 'Fredoka',
+    fallback: 'sans-serif',
+    shelf: 'display',
+    file: `${LIB}/fredoka.woff2`,
+    weight: '300 700',
+    stretch: '75% 125%',
+  },
+];
+
+/** Modal shelf order + labels. Keys are the `shelf` values. */
+export const FONT_SHELVES: Array<{ id: FontShelf; label: string }> = [
+  { id: 'sans', label: 'Sans' },
+  { id: 'serif', label: 'Serif' },
+  { id: 'mono', label: 'Mono' },
+  { id: 'display', label: 'Display' },
+];
+
+/**
+ * ── Size ────────────────────────────────────────────────────────────────────
+ *
+ * One vocabulary for all four slots, applied two different ways.
+ *
+ * The INTERFACE size scales the ROOT font-size, and because the shell is
+ * rem-based (h-16 header, rem paddings, rem control heights) the whole
+ * interface scales rather than just the letters — the same thing OS display
+ * scaling does. Percentages, not px, so a visitor who has raised their
+ * browser's default font size keeps that as the baseline; hard-coding 18px
+ * would quietly OVERRIDE an accessibility setting with our own.
+ *
+ * The other three are local multipliers on one element's own size, published as
+ * CSS vars. A wordmark that scaled the shell would be a bug, not a feature.
+ */
+export type FontSize = 'xsmall' | 'small' | 'medium' | 'large';
+
+export const FONT_SIZES: Array<{ id: FontSize; label: string; hint: string }> = [
+  { id: 'xsmall', label: 'Extra small', hint: 'Densest' },
+  { id: 'small', label: 'Small', hint: 'Denser — more on screen' },
+  { id: 'medium', label: 'Medium', hint: 'Default' },
+  { id: 'large', label: 'Large', hint: 'Roomier — easier to read' },
+];
+
+export const DEFAULT_FONT_SIZE: FontSize = 'medium';
+
+/**
+ * All four sizes travel as `<html>` ATTRIBUTES, never as resolved numbers.
+ * app.css owns the multipliers, exactly as it already owned the root font-size
+ * percentages, so there is one place holding the scale and no chance of a TS
+ * copy drifting from the CSS that actually paints. "Default" is the absence of
+ * the attribute.
+ */
+export function resolveFontSize(v: string | null | undefined): FontSize {
+  return v === 'xsmall' || v === 'small' || v === 'large' || v === 'medium' ? v : DEFAULT_FONT_SIZE;
+}
+
+// ── lookup ──────────────────────────────────────────────────────────────────
+
+/** How many variable axes a face carries: the CSS-addressable descriptors
+ *  (weight/stretch/style) plus the descriptorless axes. The dialog's "· N axes"
+ *  label and the test's two-axis-floor assertion both count through here, so
+ *  the number users see is the same one the invariant enforces. */
+export function axisCount(f: FontFace): number {
+  return [f.weight, f.stretch, f.style].filter(Boolean).length + (f.axes?.length ?? 0);
+}
+
+const BY_KEY = new Map(FONT_LIBRARY.map((f) => [f.key, f]));
+
+export function fontByKey(key: string | null | undefined): FontFace | undefined {
+  if (!key) return undefined;
+  return BY_KEY.get(LEGACY_KEYS[key] ?? key);
+}
+
+/**
+ * CSS `font-family` value for a font key. Unknown keys → null (caller keeps its
+ * default).
+ */
+export function fontFamilyValue(key: string | null | undefined): string | null {
+  const f = fontByKey(key);
+  if (!f) return null;
+  // 'inherit' means "follow the interface font, whatever it is", so it resolves
+  // through the var the interface choice overrides.
+  if (f.key === 'inherit') return 'var(--font-sans, ui-sans-serif, sans-serif)';
+  // 'inter' is a CONCRETE face, not "the current one". It must NOT resolve
+  // through --font-sans: that var is what the interface choice overrides, so an
+  // Inter row would preview in whichever face is selected — Saira under a label
+  // saying Inter. `--font-sans-base` always holds the next/font Inter family,
+  // set unconditionally in the root layout precisely so this stays truthful.
+  if (f.key === DEFAULT_UI_FONT) return 'var(--font-sans-base, ui-sans-serif, sans-serif)';
+  if (!f.family) return null;
+  return `"${f.family}", ${f.fallback}`;
+}
+
+/**
+ * `@font-face` rules for every library face, injected once server-side (root
+ * layout + the share/print shell) so the declarations are present on first
+ * paint (no FOUT wait) yet the files stay lazily fetched. Deterministic (no
+ * runtime state) so it is safe to render into a <style>.
+ */
+export function displayFontFaceCss(): string {
+  const rules: string[] = [];
+  for (const f of FONT_LIBRARY) {
+    if (!f.file || !f.family) continue;
+    rules.push(face(f, f.file, f.style ?? 'normal'));
+    // A real italic file is a SECOND face on the same family, distinguished
+    // only by font-style — that is how the browser picks it for italic text.
+    // Faces with a slnt axis get nothing extra: their one rule already
+    // declares an oblique range, which covers italic.
+    if (f.italicFile) rules.push(face(f, f.italicFile, 'italic'));
+  }
+  return rules.join('\n');
+}
+
+function face(f: FontFace, file: string, style: string): string {
+  return (
+    `@font-face{font-family:"${f.family}";` +
+    `src:url("${file}") format("${fileFormat(file)}");` +
+    `font-display:swap;` +
+    `font-style:${style};` +
+    (f.weight ? `font-weight:${f.weight};` : '') +
+    (f.stretch ? `font-stretch:${f.stretch};` : '') +
+    `}`
+  );
+}
+
+/** `format()` hint for a face file. A wrong hint makes the browser skip the
+ *  face entirely, so it is derived from the filename, never assumed. */
+function fileFormat(file: string): string {
+  if (file.endsWith('.woff2')) return 'woff2';
+  if (file.endsWith('.woff')) return 'woff';
+  if (file.endsWith('.otf')) return 'opentype';
+  return 'truetype';
+}
+
+/**
+ * Resolve the four stored font keys to their CSS `font-family` values, dropping
+ * defaults and unknown keys — the shared projection behind the server-rendered
+ * `<html>` appearance attributes (see appearance.ts). Values land as inline
+ * style on the root element; "default" is the absence of the var, so the
+ * elements' var() fallbacks win. There is deliberately NO localStorage /
+ * before-paint-script path: the document arrives correct, and the client
+ * providers read the rendered attributes back as their initial state.
+ */
+export type ResolvedFontVars = {
+  wordmark?: string;
+  pageTitle?: string;
+  ui?: string;
+  prose?: string;
+};
+
+export function resolveFontVars(
+  logo: string | null | undefined,
+  title: string | null | undefined,
+  ui?: string | null | undefined,
+  prose?: string | null | undefined,
+): ResolvedFontVars {
+  const out: ResolvedFontVars = {};
+  if (logo && fontByKey(logo)?.key !== DEFAULT_LOGO_FONT) {
+    const v = fontFamilyValue(logo);
+    if (v) out.wordmark = v;
+  }
+  if (title && fontByKey(title)?.key !== DEFAULT_TITLE_FONT) {
+    const v = fontFamilyValue(title);
+    if (v) out.pageTitle = v;
+  }
+  // The UI font overrides `--font-sans` itself rather than introducing a var of
+  // its own, so everything that already resolves it — the `font-sans` utility
+  // and every element inheriting from the root — follows the choice with no
+  // further wiring. Custom properties inherit, so setting it once at the root
+  // is the whole mechanism.
+  //
+  // 'inherit' (and the legacy 'sans' that aliases to it) must be REJECTED for
+  // this slot, not resolved: its value is `var(--font-sans, …)`, and stamping
+  // that as --font-sans is a self-referential custom property — invalid at
+  // computed-value time regardless of the fallback, which drops the ENTIRE
+  // interface to the browser default font. The dialog never offers it for this
+  // slot, but the PUT route is shape-only validation, so the stored value can
+  // be anything.
+  if (ui) {
+    const key = fontByKey(ui)?.key;
+    if (key !== DEFAULT_UI_FONT && key !== 'inherit') {
+      const v = fontFamilyValue(ui);
+      if (v) out.ui = v;
+    }
+  }
+  if (prose && fontByKey(prose)?.key !== DEFAULT_PROSE_FONT) {
+    const v = fontFamilyValue(prose);
+    if (v) out.prose = v;
+  }
+  return out;
+}

package/src/docs-labels.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { docLabelFromRelPath, prettifyDocLabel } from './docs-labels';
+
+describe('prettifyDocLabel', () => {
+  it('strips ordering prefixes and title-cases', () => {
+    expect(prettifyDocLabel('00-index.md')).toBe('Index');
+    expect(prettifyDocLabel('02-concepts')).toBe('Concepts');
+    expect(prettifyDocLabel('the-brain.md')).toBe('The Brain');
+  });
+
+  it('keeps a version number whole (changelog entries)', () => {
+    // Without the version guard the prefix strip would mangle these: `0.100.0` → "100.0".
+    expect(prettifyDocLabel('0.100.0.md')).toBe('v0.100.0');
+    expect(prettifyDocLabel('0.20.68.md')).toBe('v0.20.68');
+    expect(prettifyDocLabel('v1.2.3.md')).toBe('v1.2.3');
+  });
+
+  it('does not treat prefixed doc names as versions', () => {
+    expect(prettifyDocLabel('01-getting-started.md')).toBe('Getting Started');
+  });
+});
+
+describe('docLabelFromRelPath', () => {
+  it('labels from the last path segment', () => {
+    expect(docLabelFromRelPath('guide/00-index.md')).toBe('Index');
+    expect(docLabelFromRelPath('0.109.0.md')).toBe('v0.109.0');
+  });
+});

package/src/docs-labels.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure label helpers for the docs reader, shared by the server data layer
+ * (prev/next labels) and the client nav (folder/file labels). No 'server-only'
+ * marker — safe to import from client components.
+ */
+
+/** Prettify a filename or folder segment for display:
+ *  strip a leading `NN-`/`NN_`/`NN.` ordering prefix, drop the `.md` extension,
+ *  turn dashes/underscores into spaces, and title-case.
+ *  `00-index.md` → "Index", `02-concepts` → "Concepts", `the-brain.md` → "The Brain".
+ *  A pure version number (a changelog entry) is kept whole — the ordering-prefix
+ *  strip would otherwise mangle it (`0.100.0` → "100.0"): `0.100.0.md` → "v0.100.0". */
+export function prettifyDocLabel(name: string): string {
+  const base = name.replace(/\.(md|markdown)$/i, '');
+  if (/^v?\d+(\.\d+)+$/.test(base)) return base.startsWith('v') ? base : `v${base}`;
+  const noPrefix = base.replace(/^\d+[-_.]/, '');
+  const spaced = noPrefix.replace(/[-_]+/g, ' ').trim();
+  return spaced.replace(/\b\w/g, (c) => c.toUpperCase()) || base;
+}
+
+/** Display label for a doc, from the last segment of its collection-relative path. */
+export function docLabelFromRelPath(relPath: string): string {
+  const last = relPath.split('/').pop() ?? relPath;
+  return prettifyDocLabel(last);
+}

package/src/highlight-colors.ts

@@ -0,0 +1,19 @@
+/**
+ * Themed highlight palette. We store a TOKEN KEY (e.g. `chart-2`) on the
+ * highlight mark, never a raw colour, so highlights track the active theme +
+ * light/dark like the rest of the document. A null/unknown colour = the default
+ * highlight (primary tint, styled in globals.css). Pure (no React) → safe to
+ * import in the server-side public renderer.
+ */
+export const HIGHLIGHT_TOKENS = ['chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5'] as const;
+export type HighlightToken = (typeof HIGHLIGHT_TOKENS)[number];
+
+export function isHighlightToken(v: unknown): v is HighlightToken {
+  return typeof v === 'string' && (HIGHLIGHT_TOKENS as readonly string[]).includes(v);
+}
+
+/** CSS `background-color` for a highlight token, or null for the default tint. */
+export function highlightColor(token: unknown): string | null {
+  if (!isHighlightToken(token)) return null;
+  return `color-mix(in oklab, var(--${token}) 30%, transparent)`;
+}