@fairgarden/design 0.1.0-alpha.1 → 0.1.0-alpha.2

package/utils/docs/createTypes.js

@@ -0,0 +1,27 @@
+import { createMultipleTypesFactory as createEngineMultipleTypesFactory, createTypesFactory as createEngineTypesFactory, } from '@fairgarden/docs/abstractCreateTypes';
+import { TypePre } from '../../content/types-table/TypePre';
+import { TypesTable } from '../../content/types-table/TypesTable';
+function typesOptions(options) {
+    return {
+        TypesTable: TypesTable,
+        TypePre,
+        ...options,
+    };
+}
+/** The engine's `createTypesFactory` with `TypesTable` and `TypePre`; `options` override either. */
+export function createTypesFactory(options = {}) {
+    return createEngineTypesFactory(typesOptions(options));
+}
+/** As `createTypesFactory`, over the engine's `createMultipleTypesFactory`. */
+export function createMultipleTypesFactory(options = {}) {
+    return createEngineMultipleTypesFactory(typesOptions(options));
+}
+/**
+ * The API table for one export, extracted from TypeScript at build time.
+ * @param url `import.meta.url` of the page's `types.ts`.
+ * @param component The export to document.
+ */
+export const createTypes = /* @__PURE__ */ createTypesFactory();
+/** API tables for several related exports, rendered as `<TypesX.Part />`. */
+export const createMultipleTypes = /* @__PURE__ */ createMultipleTypesFactory();
+//# sourceMappingURL=createTypes.js.map

package/utils/docs/createTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTypes.js","sourceRoot":"","sources":["../../src/utils/docs/createTypes.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,IAAI,gCAAgC,EAC9D,kBAAkB,IAAI,wBAAwB,GAE/C,MAAM,sCAAsC,CAAA;AAE7C,OAAO,EAAE,OAAO,EAAE,MAAM,mCAAmC,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAA;AAmBjE,SAAS,YAAY,CAAC,OAAqC;IACzD,OAAO;QACL,UAAU,EAAE,UAA+C;QAC3D,OAAO;QACP,GAAG,OAAO;KACX,CAAA;AACH,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,kBAAkB,CAAC,UAAwC,EAAE;IAC3E,OAAO,wBAAwB,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAA;AACxD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,0BAA0B,CACxC,UAAwC,EAAE;IAE1C,OAAO,gCAAgC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAA;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,eAAe,CAAC,kBAAkB,EAAE,CAAA;AAE/D,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC,0BAA0B,EAAE,CAAA"}

package/utils/docs/index.d.ts

@@ -0,0 +1,8 @@
+export * from './createDemo';
+export * from './createTypes';
+export * from './createMdxComponents';
+export * from './DemoTitle';
+export * from './Pre';
+export * from './serverSourceEnhancers';
+export * from './toSidebarItems';
+//# sourceMappingURL=index.d.ts.map

package/utils/docs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/docs/index.ts"],"names":[],"mappings":"AAQA,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,uBAAuB,CAAA;AACrC,cAAc,aAAa,CAAA;AAC3B,cAAc,OAAO,CAAA;AACrB,cAAc,yBAAyB,CAAA;AACvC,cAAc,kBAAkB,CAAA"}

package/utils/docs/index.js

@@ -0,0 +1,16 @@
+/*
+ * @fairgarden/design/utils/docs: factories for a docs site built on
+ * `@fairgarden/docs` (an optional peer), pre-wired with the design system's
+ * Code Block, Demo and Types Table, and the mapping from the engine's
+ * sitemap to the Sidebar Navigation. Server-safe; each also has its own
+ * deep path (`…/utils/docs/createDemo`, `…/createTypes`,
+ * `…/createMdxComponents`, `…/serverSourceEnhancers`, `…/toSidebarItems`).
+ */
+export * from './createDemo';
+export * from './createTypes';
+export * from './createMdxComponents';
+export * from './DemoTitle';
+export * from './Pre';
+export * from './serverSourceEnhancers';
+export * from './toSidebarItems';
+//# sourceMappingURL=index.js.map

package/utils/docs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/docs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,uBAAuB,CAAA;AACrC,cAAc,aAAa,CAAA;AAC3B,cAAc,OAAO,CAAA;AACrB,cAAc,yBAAyB,CAAA;AACvC,cAAc,kBAAkB,CAAA"}

package/utils/docs/mdx.module.css

@@ -0,0 +1,201 @@
+/*
+ * The MDX map's prose (createMdxComponents) and the demo title (DemoTitle),
+ * set in the design system's own type roles (§3.3, §3.5). Parts: `h1`,
+ * `h2`, `h3`, `h4`, `anchor` (a heading's self-link), `p`, `list`, `code`
+ * (inline code), `tableWrap`, `table`, `blockquote`, `hr`, `demoTitle`.
+ *
+ * Headings: H1 type-display and H2 type-h2 in --role-heading, H3
+ * type-subhead in --primary12. Gaps are visual (half-leading trimmed) on the
+ * px series. Colors are role variables only; nothing is transparent,
+ * shadowed or graded [D12].
+ */
+
+/* Composition sits in top-level rules, outside the layers: Lightning CSS
+ * (Next.js with Turbopack) rejects `composes` inside @layer or any nesting.
+ * The composed classes keep their own layers. */
+.h1 {
+  composes: typeDisplay from '../type.module.css';
+}
+
+.h2 {
+  composes: typeH2 from '../type.module.css';
+}
+
+.h3,
+.demoTitle {
+  composes: typeSubhead from '../type.module.css';
+}
+
+.h4 {
+  composes: typeRunin from '../type.module.css';
+}
+
+.p,
+.list {
+  composes: typeBody from '../type.module.css';
+}
+
+.table,
+.blockquote {
+  composes: typeBodyUi from '../type.module.css';
+}
+
+.code {
+  composes: syntax from '../syntax.module.css';
+}
+
+@layer base {
+  .h1 {
+    margin-block: 0 var(--size-px-7-5);
+    color: var(--role-heading);
+  }
+
+  .h2 {
+    margin-block: var(--size-px-8-5) var(--size-px-5);
+    padding-block-end: var(--size-px-3);
+    border-block-end: var(--border-size-1) solid var(--role-hairline);
+    color: var(--role-heading);
+  }
+
+  .h3,
+  .demoTitle {
+    margin-block: var(--size-px-7-5) var(--size-px-3);
+    color: var(--primary12);
+  }
+
+  .h4 {
+    margin-block: var(--size-px-5) var(--size-px-2);
+  }
+
+  /* A heading's self-link: the heading's own ink, the bare-text underline on hover [D181]. */
+  .anchor {
+    color: inherit;
+    text-decoration-line: none;
+    text-decoration-color: var(--role-accent);
+    text-decoration-thickness: var(--border-size-2);
+    text-underline-offset: var(--size-px-1);
+  }
+
+  .p {
+    max-inline-size: var(--fgd-measure-reading);
+    margin-block: 0 var(--size-px-3);
+  }
+
+  /* The first paragraph after the H1 is the page's description: type-lead. */
+  .h1 + .p {
+    margin-block-end: var(--size-px-7-5);
+    font-family: var(--fgd-font-ui);
+    font-size: var(--fgd-font-size-lead);
+    font-weight: var(--font-weight-4);
+    line-height: var(--font-lineheight-3);
+  }
+
+  .list {
+    max-inline-size: var(--fgd-measure-reading);
+    margin-block: 0 var(--size-px-3);
+    padding-inline-start: var(--size-px-5);
+  }
+
+  .list > li + li {
+    margin-block-start: var(--size-px-1);
+  }
+
+  /* Inline code: highlighted in the Code Block's syntax tiers. */
+  .code {
+    font-family: var(--fgd-font-mono);
+    font-size: 0.9em;
+    color: var(--primary12);
+  }
+
+  .tableWrap {
+    margin-block: var(--size-px-5);
+    overflow-x: auto;
+  }
+
+  /* Table frame [D83]: rule top and bottom, hairline body rows. */
+  .table {
+    inline-size: 100%;
+    border-collapse: collapse;
+    border-block: var(--border-size-1) solid var(--role-rule);
+  }
+
+  .table th {
+    padding: var(--size-px-2) var(--size-px-2-5);
+    border-block-end: var(--border-size-1) solid var(--role-rule);
+    color: var(--role-muted);
+    font-family: var(--fgd-font-ui);
+    font-size: var(--fgd-font-size-label);
+    font-weight: var(--font-weight-6);
+    line-height: var(--font-lineheight-1);
+    letter-spacing: var(--font-letterspacing-3);
+    text-align: start;
+    text-transform: uppercase;
+  }
+
+  .table td {
+    padding: var(--size-px-2-5);
+    border-block-end: var(--border-size-1) solid var(--role-hairline);
+    vertical-align: top;
+  }
+
+  .table tr:last-child td {
+    border-block-end: none;
+  }
+
+  /* Callouts: a block edge in --role-rule, never a tinted fill alone [D84]. */
+  .blockquote {
+    max-inline-size: var(--fgd-measure-reading);
+    margin: var(--size-px-5) 0;
+    padding: var(--size-px-3) var(--size-px-5);
+    border-inline-start: var(--border-size-2-25) solid var(--role-rule);
+    background-color: var(--primary2);
+  }
+
+  .blockquote p {
+    margin: 0;
+  }
+
+  .hr {
+    margin-block: var(--size-px-7-5);
+    border: none;
+    border-block-start: var(--border-size-1) solid var(--role-hairline);
+  }
+}
+
+@layer states {
+  .anchor:hover {
+    text-decoration-line: underline;
+  }
+
+  .anchor:focus-visible {
+    outline: var(--fgd-focus-width) solid var(--primary12);
+    outline-offset: var(--fgd-focus-offset);
+  }
+}
+
+@layer print {
+  @media print {
+    /* Headings stay with what follows; tables and callouts never split. */
+    .h1,
+    .h2,
+    .h3,
+    .h4,
+    .demoTitle {
+      break-after: avoid;
+    }
+
+    .tableWrap {
+      overflow: visible;
+    }
+
+    .table tr,
+    .blockquote {
+      break-inside: avoid;
+    }
+
+    /* Fills drop on paper; the edge carries the callout. */
+    .blockquote {
+      background: none;
+    }
+  }
+}

package/utils/docs/serverSourceEnhancers.d.ts

@@ -0,0 +1,26 @@
+import type { SourceEnhancers } from '@fairgarden/docs/CodeHighlighter/types';
+/**
+ * The source enhancers CodeHighlighter runs on the server: the engine's
+ * emphasis enhancer (`enhanceCodeEmphasis`) with its default options. Pass
+ * it as CodeHighlighter's `sourceEnhancers` wherever a page renders code
+ * the build didn't precompute, such as inline `code` or a string child;
+ * `Pre` and `createMdxComponents` default to it.
+ *
+ * On the server it frames the code and records its name on the tree, so
+ * the HTML arrives with the emphasis frames and the collapsed window, the
+ * loading state paints the same lines as the loaded block, and
+ * `CodeProviderLazy`'s own emphasis enhancer, which has the same name,
+ * skips the tree instead of windowing it after hydration. Nothing changes
+ * size once the page is interactive, and hydration never depends on which
+ * side has loaded the lazy enhancer. Highlighting stays at the engine's
+ * default `highlightAfter`.
+ *
+ * The options are the ones demos get from the build and
+ * `CodeProviderLazy` loads: the enhancer's defaults, which
+ * `withFairGardenDocs` uses when it has no `demoEmphasisOptions`. An app
+ * that sets `demoEmphasisOptions` passes
+ * `[createEnhanceCodeEmphasis(sameOptions)]` instead, so inline code and
+ * demos window alike.
+ */
+export declare const serverSourceEnhancers: SourceEnhancers;
+//# sourceMappingURL=serverSourceEnhancers.d.ts.map

package/utils/docs/serverSourceEnhancers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverSourceEnhancers.d.ts","sourceRoot":"","sources":["../../src/utils/docs/serverSourceEnhancers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAU7E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,qBAAqB,EAAE,eAAuC,CAAA"}

package/utils/docs/serverSourceEnhancers.js

@@ -0,0 +1,32 @@
+import { enhanceCodeEmphasis } from '@fairgarden/docs/pipeline/enhanceCodeEmphasis';
+/*
+ * serverSourceEnhancers: the source enhancers for code the server parses
+ * through CodeHighlighter (inline `code`, a string child, a `Pre`), so its
+ * emphasis window is in the server HTML. Size-determining state belongs in
+ * the first paint; colours may arrive late [D201].
+ */
+/**
+ * The source enhancers CodeHighlighter runs on the server: the engine's
+ * emphasis enhancer (`enhanceCodeEmphasis`) with its default options. Pass
+ * it as CodeHighlighter's `sourceEnhancers` wherever a page renders code
+ * the build didn't precompute, such as inline `code` or a string child;
+ * `Pre` and `createMdxComponents` default to it.
+ *
+ * On the server it frames the code and records its name on the tree, so
+ * the HTML arrives with the emphasis frames and the collapsed window, the
+ * loading state paints the same lines as the loaded block, and
+ * `CodeProviderLazy`'s own emphasis enhancer, which has the same name,
+ * skips the tree instead of windowing it after hydration. Nothing changes
+ * size once the page is interactive, and hydration never depends on which
+ * side has loaded the lazy enhancer. Highlighting stays at the engine's
+ * default `highlightAfter`.
+ *
+ * The options are the ones demos get from the build and
+ * `CodeProviderLazy` loads: the enhancer's defaults, which
+ * `withFairGardenDocs` uses when it has no `demoEmphasisOptions`. An app
+ * that sets `demoEmphasisOptions` passes
+ * `[createEnhanceCodeEmphasis(sameOptions)]` instead, so inline code and
+ * demos window alike.
+ */
+export const serverSourceEnhancers = [enhanceCodeEmphasis];
+//# sourceMappingURL=serverSourceEnhancers.js.map

package/utils/docs/serverSourceEnhancers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverSourceEnhancers.js","sourceRoot":"","sources":["../../src/utils/docs/serverSourceEnhancers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAA;AAEnF;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAoB,CAAC,mBAAmB,CAAC,CAAA"}

package/utils/docs/toSidebarItems.d.ts

@@ -0,0 +1,23 @@
+import type { Sitemap } from '@fairgarden/docs/createSitemap/types';
+import type { SidebarNavItem } from '../../navigation/sidebar-nav';
+/**
+ * A sitemap page's route: its `path` (`./button/page.mdx`) under its
+ * section's `prefix` (`/actions/`), without `page.mdx` or a trailing slash
+ * (`/actions/button`); the section itself with no path (`/actions`).
+ */
+export declare function sitemapHref(prefix: string, path?: string): string;
+/** Options for toSidebarItems. */
+export interface ToSidebarItemsOptions {
+    /** Builds each route from a section prefix and a page path. Default `sitemapHref`. */
+    toHref?: (prefix: string, path?: string) => string;
+    /** Link each group heading to its section's index page. Default `true`. */
+    groupLinks?: boolean;
+}
+/**
+ * The sitemap's sections, in sitemap order, as SidebarNav groups: each
+ * section's title over its pages, in the section index's order, the
+ * heading linking to the section's index page. Pages without a title use
+ * their slug.
+ */
+export declare function toSidebarItems(sitemap: Sitemap | undefined, options?: ToSidebarItemsOptions): SidebarNavItem[];
+//# sourceMappingURL=toSidebarItems.d.ts.map

package/utils/docs/toSidebarItems.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toSidebarItems.d.ts","sourceRoot":"","sources":["../../src/utils/docs/toSidebarItems.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sCAAsC,CAAA;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAYlE;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,MAAM,CAG7D;AAED,kCAAkC;AAClC,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;IAClD,2EAA2E;IAC3E,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,OAAO,GAAE,qBAA0B,GAClC,cAAc,EAAE,CAUlB"}

package/utils/docs/toSidebarItems.js

@@ -0,0 +1,36 @@
+/*
+ * toSidebarItems: the docs engine's sitemap as the Sidebar Navigation's
+ * page tree (§11.15) [D202]. Server-safe plain data: build it where the
+ * sitemap is imported (a layout) and hand it to the client SidebarNav.
+ *
+ * Planned beside it (§11.15, "Wiring plan"): `toTableOfContents(page)`,
+ * the page's headings as TableOfContents items, once the engine records
+ * each heading's rendered id and level.
+ */
+/**
+ * A sitemap page's route: its `path` (`./button/page.mdx`) under its
+ * section's `prefix` (`/actions/`), without `page.mdx` or a trailing slash
+ * (`/actions/button`); the section itself with no path (`/actions`).
+ */
+export function sitemapHref(prefix, path = '') {
+    const href = (prefix + path.replace(/^\.\//, '').replace(/\/?page\.mdx$/, '')).replace(/\/$/, '');
+    return href || '/';
+}
+/**
+ * The sitemap's sections, in sitemap order, as SidebarNav groups: each
+ * section's title over its pages, in the section index's order, the
+ * heading linking to the section's index page. Pages without a title use
+ * their slug.
+ */
+export function toSidebarItems(sitemap, options = {}) {
+    const { toHref = sitemapHref, groupLinks = true } = options;
+    return Object.values(sitemap?.data ?? {}).map((section) => ({
+        title: section.title,
+        href: groupLinks ? toHref(section.prefix) : undefined,
+        items: section.pages.map((page) => ({
+            title: page.title ?? page.slug,
+            href: toHref(section.prefix, page.path),
+        })),
+    }));
+}
+//# sourceMappingURL=toSidebarItems.js.map

package/utils/docs/toSidebarItems.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toSidebarItems.js","sourceRoot":"","sources":["../../src/utils/docs/toSidebarItems.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,IAAI,GAAG,EAAE;IACnD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IACjG,OAAO,IAAI,IAAI,GAAG,CAAA;AACpB,CAAC;AAUD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,OAA4B,EAC5B,UAAiC,EAAE;IAEnC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,UAAU,GAAG,IAAI,EAAE,GAAG,OAAO,CAAA;IAC3D,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC1D,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;QACrD,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAClC,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI;YAC9B,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC;SACxC,CAAC,CAAC;KACJ,CAAC,CAAC,CAAA;AACL,CAAC"}

package/utils/font-fallbacks.css

@@ -0,0 +1,176 @@
+/*
+ * Metric-matched fallback faces for the four webfonts (§1.5.5) [D159, D201].
+ * Each wraps a system face that ships everywhere with the same widths
+ * (Arial, Times New Roman and Courier New; their metric twins Liberation
+ * and Arimo, Tinos and Cousine on Linux) and scales and re-sets it so its
+ * lines take the webfont's widths and heights. Text laid out before the
+ * webfont arrives then keeps its line breaks, its line boxes and its `ch`
+ * measures when the webfont swaps in, so the swap moves nothing (or almost
+ * nothing). The type-family tokens name each fallback right after its
+ * webfont (utils/tokens.css).
+ *
+ * Measured 2026-09-27 against the shipped woff2 files: vertical metrics from
+ * each file's hhea table (equal to OS/2 typo, USE_TYPO_METRICS set); widths
+ * in Chromium at 400 px (so no pixel rounding), kerning off, at the roles'
+ * weights and optical sizes (text 'opsz' 18, display 'opsz' 28 with 'SOFT' 0,
+ * 'WONK' 0), over the average-width string Next.js uses for its own
+ * fallbacks. Overrides are the webfont's metric divided by size-adjust, so
+ * the scaled face lands on the webfont's own ascent and descent.
+ *
+ * Two faces per weight. The text face covers the Latin range the webfonts'
+ * `latin` files cover, less the digit zero, and matches the average width.
+ * The zero face covers only U+0030 and matches the webfont's "0", because
+ * `ch` (the reading measure is 66ch) is the advance of the face that renders
+ * "0": a uniform scale can't match both, since each webfont's "0" and its
+ * lowercase stand in a different proportion from its fallback's. The
+ * proportional families take a regular pair (weights up to 549) and a bold
+ * pair (from 550, the 600 and 700 roles); mono widths don't vary with
+ * weight or glyph, so it takes one face. Any other script keeps the rest of
+ * the family stack.
+ */
+
+/* Figtree Variable (UI): Arial and its twins. */
+@font-face {
+  font-family: 'Figtree Fallback';
+  src: local('Arial'), local('ArialMT'), local('Liberation Sans'), local('LiberationSans'), local('Arimo');
+  font-weight: 100 549;
+  size-adjust: 101.24%;
+  ascent-override: 93.83%;
+  descent-override: 24.69%;
+  line-gap-override: 0%;
+  unicode-range: U+0000-002F, U+0031-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+@font-face {
+  font-family: 'Figtree Fallback';
+  src: local('Arial'), local('ArialMT'), local('Liberation Sans'), local('LiberationSans'), local('Arimo');
+  font-weight: 100 549;
+  size-adjust: 115.08%;
+  ascent-override: 82.55%;
+  descent-override: 21.72%;
+  line-gap-override: 0%;
+  unicode-range: U+0030;
+}
+
+@font-face {
+  font-family: 'Figtree Fallback';
+  src: local('Arial Bold'), local('Arial-BoldMT'), local('Liberation Sans Bold'), local('LiberationSans-Bold'), local('Arimo Bold');
+  font-weight: 550 900;
+  size-adjust: 96.75%;
+  ascent-override: 98.19%;
+  descent-override: 25.84%;
+  line-gap-override: 0%;
+  unicode-range: U+0000-002F, U+0031-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+@font-face {
+  font-family: 'Figtree Fallback';
+  src: local('Arial Bold'), local('Arial-BoldMT'), local('Liberation Sans Bold'), local('LiberationSans-Bold'), local('Arimo Bold');
+  font-weight: 550 900;
+  size-adjust: 116.42%;
+  ascent-override: 81.60%;
+  descent-override: 21.47%;
+  line-gap-override: 0%;
+  unicode-range: U+0030;
+}
+
+/* Source Serif 4 Variable (text): Times New Roman and its twins. */
+@font-face {
+  font-family: 'Source Serif 4 Fallback';
+  src: local('Times New Roman'), local('TimesNewRomanPSMT'), local('Liberation Serif'), local('LiberationSerif'), local('Tinos');
+  font-weight: 100 549;
+  size-adjust: 113.27%;
+  ascent-override: 91.46%;
+  descent-override: 29.57%;
+  line-gap-override: 0%;
+  unicode-range: U+0000-002F, U+0031-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+@font-face {
+  font-family: 'Source Serif 4 Fallback';
+  src: local('Times New Roman'), local('TimesNewRomanPSMT'), local('Liberation Serif'), local('LiberationSerif'), local('Tinos');
+  font-weight: 100 549;
+  size-adjust: 102%;
+  ascent-override: 101.57%;
+  descent-override: 32.84%;
+  line-gap-override: 0%;
+  unicode-range: U+0030;
+}
+
+@font-face {
+  font-family: 'Source Serif 4 Fallback';
+  src: local('Times New Roman Bold'), local('TimesNewRomanPS-BoldMT'), local('Liberation Serif Bold'), local('LiberationSerif-Bold'), local('Tinos Bold');
+  font-weight: 550 900;
+  size-adjust: 110.28%;
+  ascent-override: 93.94%;
+  descent-override: 30.38%;
+  line-gap-override: 0%;
+  unicode-range: U+0000-002F, U+0031-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+@font-face {
+  font-family: 'Source Serif 4 Fallback';
+  src: local('Times New Roman Bold'), local('TimesNewRomanPS-BoldMT'), local('Liberation Serif Bold'), local('LiberationSerif-Bold'), local('Tinos Bold');
+  font-weight: 550 900;
+  size-adjust: 110%;
+  ascent-override: 94.18%;
+  descent-override: 30.45%;
+  line-gap-override: 0%;
+  unicode-range: U+0030;
+}
+
+/* Fraunces Variable (display): Times New Roman and its twins. */
+@font-face {
+  font-family: 'Fraunces Fallback';
+  src: local('Times New Roman'), local('TimesNewRomanPSMT'), local('Liberation Serif'), local('LiberationSerif'), local('Tinos');
+  font-weight: 100 549;
+  size-adjust: 113.75%;
+  ascent-override: 85.98%;
+  descent-override: 22.42%;
+  line-gap-override: 0%;
+  unicode-range: U+0000-002F, U+0031-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+@font-face {
+  font-family: 'Fraunces Fallback';
+  src: local('Times New Roman'), local('TimesNewRomanPSMT'), local('Liberation Serif'), local('LiberationSerif'), local('Tinos');
+  font-weight: 100 549;
+  size-adjust: 129%;
+  ascent-override: 75.81%;
+  descent-override: 19.77%;
+  line-gap-override: 0%;
+  unicode-range: U+0030;
+}
+
+@font-face {
+  font-family: 'Fraunces Fallback';
+  src: local('Times New Roman Bold'), local('TimesNewRomanPS-BoldMT'), local('Liberation Serif Bold'), local('LiberationSerif-Bold'), local('Tinos Bold');
+  font-weight: 550 900;
+  size-adjust: 114.21%;
+  ascent-override: 85.63%;
+  descent-override: 22.33%;
+  line-gap-override: 0%;
+  unicode-range: U+0000-002F, U+0031-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+@font-face {
+  font-family: 'Fraunces Fallback';
+  src: local('Times New Roman Bold'), local('TimesNewRomanPS-BoldMT'), local('Liberation Serif Bold'), local('LiberationSerif-Bold'), local('Tinos Bold');
+  font-weight: 550 900;
+  size-adjust: 139.5%;
+  ascent-override: 70.11%;
+  descent-override: 18.28%;
+  line-gap-override: 0%;
+  unicode-range: U+0030;
+}
+
+/* IBM Plex Mono (data and code): Courier New and its twins. */
+@font-face {
+  font-family: 'IBM Plex Mono Fallback';
+  src: local('Courier New'), local('CourierNewPSMT'), local('Liberation Mono'), local('LiberationMono'), local('Cousine');
+  size-adjust: 99.98%;
+  ascent-override: 102.52%;
+  descent-override: 27.5%;
+  line-gap-override: 0%;
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}

package/utils/fonts.d.ts

@@ -7,5 +7,6 @@ import '@fontsource-variable/figtree/wght-italic.css';
 import '@fontsource/ibm-plex-mono/400.css';
 import '@fontsource/ibm-plex-mono/500.css';
 import '@fontsource/ibm-plex-mono/700.css';
+import './font-fallbacks.css';
 export {};
 //# sourceMappingURL=fonts.d.ts.map

package/utils/fonts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../src/utils/fonts.ts"],"names":[],"mappings":"AAEA,OAAO,wCAAwC,CAAA;AAC/C,OAAO,+CAA+C,CAAA;AACtD,OAAO,8CAA8C,CAAA;AACrD,OAAO,qDAAqD,CAAA;AAC5D,OAAO,uCAAuC,CAAA;AAC9C,OAAO,8CAA8C,CAAA;AACrD,OAAO,mCAAmC,CAAA;AAC1C,OAAO,mCAAmC,CAAA;AAC1C,OAAO,mCAAmC,CAAA;AAE1C,OAAO,EAAE,CAAA"}
+{"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../src/utils/fonts.ts"],"names":[],"mappings":"AAaA,OAAO,wCAAwC,CAAA;AAC/C,OAAO,+CAA+C,CAAA;AACtD,OAAO,8CAA8C,CAAA;AACrD,OAAO,qDAAqD,CAAA;AAC5D,OAAO,uCAAuC,CAAA;AAC9C,OAAO,8CAA8C,CAAA;AACrD,OAAO,mCAAmC,CAAA;AAC1C,OAAO,mCAAmC,CAAA;AAC1C,OAAO,mCAAmC,CAAA;AAC1C,OAAO,sBAAsB,CAAA;AAE7B,OAAO,EAAE,CAAA"}

package/utils/fonts.js

@@ -1,5 +1,16 @@
 // Self-hosted SIL OFL webfonts (§1.5.5) [D159]. Import once in the app shell;
 // listed in package.json sideEffects so bundlers keep it.
+//
+// No layout shift at the swap [D201]: the metric-matched fallback faces
+// (font-fallbacks.css) hold every line's width and height until a webfont
+// arrives, and the app shell preloads the four core faces, the Latin files
+// the first screen needs, so they usually arrive before the first paint:
+//   @fontsource-variable/figtree/files/figtree-latin-wght-normal.woff2
+//   @fontsource-variable/source-serif-4/files/source-serif-4-latin-opsz-normal.woff2
+//   @fontsource-variable/fraunces/files/fraunces-latin-full-normal.woff2
+//   @fontsource/ibm-plex-mono/files/ibm-plex-mono-latin-400-normal.woff2
+// (`<link rel="preload" as="font" type="font/woff2" crossorigin>`, at the URL
+// the app's bundler gives each file; the docs app's root layout shows how).
 import '@fontsource-variable/fraunces/full.css';
 import '@fontsource-variable/fraunces/full-italic.css';
 import '@fontsource-variable/source-serif-4/opsz.css';
@@ -9,4 +20,5 @@ import '@fontsource-variable/figtree/wght-italic.css';
 import '@fontsource/ibm-plex-mono/400.css';
 import '@fontsource/ibm-plex-mono/500.css';
 import '@fontsource/ibm-plex-mono/700.css'; // bold mono: Pagination's page number
+import './font-fallbacks.css';
 //# sourceMappingURL=fonts.js.map

package/utils/fonts.js.map

@@ -1 +1 @@
-{"version":3,"file":"fonts.js","sourceRoot":"","sources":["../src/utils/fonts.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0DAA0D;AAC1D,OAAO,wCAAwC,CAAA;AAC/C,OAAO,+CAA+C,CAAA;AACtD,OAAO,8CAA8C,CAAA;AACrD,OAAO,qDAAqD,CAAA;AAC5D,OAAO,uCAAuC,CAAA;AAC9C,OAAO,8CAA8C,CAAA;AACrD,OAAO,mCAAmC,CAAA;AAC1C,OAAO,mCAAmC,CAAA;AAC1C,OAAO,mCAAmC,CAAA,CAAC,sCAAsC"}
+{"version":3,"file":"fonts.js","sourceRoot":"","sources":["../src/utils/fonts.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0DAA0D;AAC1D,EAAE;AACF,wEAAwE;AACxE,0EAA0E;AAC1E,2EAA2E;AAC3E,yEAAyE;AACzE,uEAAuE;AACvE,qFAAqF;AACrF,yEAAyE;AACzE,yEAAyE;AACzE,8EAA8E;AAC9E,4EAA4E;AAC5E,OAAO,wCAAwC,CAAA;AAC/C,OAAO,+CAA+C,CAAA;AACtD,OAAO,8CAA8C,CAAA;AACrD,OAAO,qDAAqD,CAAA;AAC5D,OAAO,uCAAuC,CAAA;AAC9C,OAAO,8CAA8C,CAAA;AACrD,OAAO,mCAAmC,CAAA;AAC1C,OAAO,mCAAmC,CAAA;AAC1C,OAAO,mCAAmC,CAAA,CAAC,sCAAsC;AACjF,OAAO,sBAAsB,CAAA"}

package/utils/frame.d.ts

@@ -0,0 +1,4 @@
+import * as React from 'react';
+/** `true` inside a page frame that renders the page's skip link (the docs layout). */
+export declare const SkipLinkContext: React.Context<boolean>;
+//# sourceMappingURL=frame.d.ts.map

package/utils/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/utils/frame.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAS9B,sFAAsF;AACtF,eAAO,MAAM,eAAe,wBAA6B,CAAA"}

package/utils/frame.js

@@ -0,0 +1,11 @@
+import * as React from 'react';
+/*
+ * What a page frame tells the parts it composes (§11) [D202]. The docs
+ * layout renders the page's skip link itself, first in the page and aimed
+ * at its own `main`, so the Navigation Bar in its header renders none and
+ * the page has exactly one.
+ */
+/** `true` inside a page frame that renders the page's skip link (the docs layout). */
+export const SkipLinkContext = React.createContext(false);
+SkipLinkContext.displayName = 'SkipLinkContext';
+//# sourceMappingURL=frame.js.map

package/utils/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../src/utils/frame.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B;;;;;GAKG;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAA;AACzD,eAAe,CAAC,WAAW,GAAG,iBAAiB,CAAA"}