@bycrux/editor 1.2.0 → 1.2.2

package/src/lib/__tests__/google-fonts.test.ts

@@ -1,5 +1,6 @@
-import { describe, it, expect, beforeEach } from 'vitest'
-import { ensureGoogleFontsLoaded } from '../google-fonts'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { ensureGoogleFontsLoaded, setFontsBaseUrl, vendoredFamiliesDigest } from '../google-fonts'
+import { fontFamilyKey, familiesDigest, partitionFontSpecs, vendoredFaceIndex, vendoredKeySet } from '../font-families'
 
 // Each test injects fonts that have not been requested by any prior test so the
 // module-level dedupe Set never short-circuits the <link> append we assert on.
@@ -11,7 +12,21 @@ function injectedHrefs(): string[] {
 
 beforeEach(() => {
   document.head.querySelectorAll('link[rel="stylesheet"]').forEach((l) => l.remove())
+  // The setters log a line per call; individual tests that assert on logging
+  // install their own spies.
+  vi.spyOn(console, 'info').mockImplementation(() => {})
+  vi.spyOn(console, 'warn').mockImplementation(() => {})
 })
+afterEach(() => {
+  setFontsBaseUrl(undefined)
+  vi.restoreAllMocks()
+})
+
+// A base per test. The injected-URL Set is module state that outlives a single
+// test (only document.head is reset in beforeEach), so two tests producing the
+// same URL would see the second one suppressed — and it would pass for the
+// wrong reason. Keep every base, and every unvendored family, unique.
+const B = (name: string) => `https://example.com/fonts/${name}`
 
 describe('ensureGoogleFontsLoaded', () => {
   it('accepts a proper string[] and appends one <link> with each family', () => {
@@ -54,3 +69,305 @@ describe('ensureGoogleFontsLoaded', () => {
     expect(hrefs[0]).toContain('family=Inter')
   })
 })
+
+// The loader is FULLY SYNCHRONOUS and must stay that way. It is called from
+// effects and has to decide the partition before it can act, so the vendored
+// family list is passed into the setter by the host rather than fetched here:
+// a pending fetch would leave the loader with no good move — it cannot block,
+// guessing is silently wrong, and re-injecting once the answer lands leaves
+// two competing stylesheets with the stale one never pruned.
+describe('setFontsBaseUrl', () => {
+  it('unset produces exactly the default per-family googleapis URL', () => {
+    ensureGoogleFontsLoaded(['Syne:wght@800'])
+    expect(injectedHrefs()).toEqual(['https://fonts.googleapis.com/css2?family=Syne:wght@800&display=swap'])
+  })
+
+  it('never fetches — there is no network call anywhere in this loader', () => {
+    const fetchSpy = vi.fn()
+    vi.stubGlobal('fetch', fetchSpy)
+    try {
+      setFontsBaseUrl(B('no-fetch'), ['Karla'])
+      ensureGoogleFontsLoaded(['Karla:wght@800'])
+      expect(fetchSpy).not.toHaveBeenCalled()
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('a vendored family produces <base>/fonts.css ONLY — no googleapis link, no preconnect, no egress', () => {
+    const base = B('all-vendored')
+    setFontsBaseUrl(base, ['Syne', 'Inter'])
+    ensureGoogleFontsLoaded(['Syne:wght@800'])
+    expect(injectedHrefs()).toEqual([`${base}/fonts.css`])
+  })
+
+  it('setting a base after a prior injection still injects — a stale guard must not suppress it', () => {
+    ensureGoogleFontsLoaded(['Zilla:wght@800'])
+    expect(injectedHrefs()).toHaveLength(1)
+
+    const base = B('another-base')
+    setFontsBaseUrl(base, ['Zilla'])
+    ensureGoogleFontsLoaded(['Zilla:wght@800'])
+
+    const hrefs = injectedHrefs()
+    expect(hrefs).toHaveLength(2)
+    expect(hrefs).toContain(`${base}/fonts.css`)
+  })
+
+  it('logs the vendored set digest once per setter call', () => {
+    const info = vi.spyOn(console, 'info').mockImplementation(() => {})
+    const base = B('digest-logged')
+    setFontsBaseUrl(base, ['Inter', 'Baloo 2'])
+    expect(info).toHaveBeenCalledOnce()
+    expect(info.mock.calls[0][0]).toContain(vendoredFamiliesDigest())
+    expect(info.mock.calls[0][0]).toContain('2 families')
+  })
+
+  it('vendoredFamiliesDigest is empty with no base, and stable across equivalent spellings', () => {
+    expect(vendoredFamiliesDigest()).toBe('')
+    setFontsBaseUrl(B('digest-a'), ['Baloo 2', 'Inter'])
+    const a = vendoredFamiliesDigest()
+    // Same set, different order and spelling — the digest sorts and normalises.
+    setFontsBaseUrl(B('digest-b'), ['inter', 'Baloo+2'])
+    expect(vendoredFamiliesDigest()).toBe(a)
+    expect(a).not.toBe('')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// The partition (L1 fall-through)
+// ---------------------------------------------------------------------------
+//
+// The vendored stylesheet declares the editor's twenty picker families and
+// nothing else, but `googleFonts` comes out of project data and
+// skills/write-overlay documents arbitrary Google families as first-class —
+// its own worked example is `["Anton", "Playfair+Display:ital@1"]`, and Anton
+// is not a picker family. Linking the vendored sheet and dropping the
+// requested entries renders those in a fallback face with nothing on screen
+// to say so, which is what this partition exists to stop.
+//
+// Every assertion here has a twin on the render side
+// (`montaj_assets/render/test/fonts-fallthrough.test.mjs`). The two sides MUST
+// partition identically: a family loaded locally while editing and from
+// Google at export time — or vice versa — is the caption-shifts-between-
+// preview-and-export bug the Syne case study documents.
+describe('ensureGoogleFontsLoaded: unvendored families fall through to Google', () => {
+  it('an unvendored family gets a googleapis link alongside the vendored stylesheet', () => {
+    const base = B('mix-basic')
+    setFontsBaseUrl(base, ['Inter', 'Baloo 2'])
+    ensureGoogleFontsLoaded(['Inter:wght@400', 'Anton', 'Syne:wght@800'])
+    expect(injectedHrefs()).toEqual([
+      `${base}/fonts.css`,
+      'https://fonts.googleapis.com/css2?family=Anton&family=Syne:wght@800&display=swap',
+    ])
+  })
+
+  it('a MIX splits: vendored families stay local, unvendored ones go to Google, and neither list leaks into the other', () => {
+    const base = B('mixed')
+    setFontsBaseUrl(base, ['Baloo 2', 'Playfair Display', 'Inter'])
+    ensureGoogleFontsLoaded(['Baloo+2:wght@400;500', 'Bitter', 'Playfair+Display:ital@1'])
+
+    const hrefs = injectedHrefs()
+    expect(hrefs).toHaveLength(2)
+    expect(hrefs[0]).toBe(`${base}/fonts.css`)
+    // Only Bitter crosses to Google. Baloo 2 and Playfair Display are vendored,
+    // so their specs must NOT appear in the googleapis URL — a regression that
+    // fell everything through would still look right and would silently
+    // restore the egress this feature removes.
+    expect(hrefs[1]).toBe('https://fonts.googleapis.com/css2?family=Bitter&display=swap')
+    expect(hrefs[1]).not.toContain('Baloo')
+    expect(hrefs[1]).not.toContain('Playfair')
+  })
+
+  it('all-unvendored does not link the vendored stylesheet at all — it would serve nothing', () => {
+    const base = B('all-unvendored')
+    setFontsBaseUrl(base, ['Inter', 'Baloo 2'])
+    ensureGoogleFontsLoaded(['Amiri', 'Cabin:wght@400'])
+    expect(injectedHrefs()).toEqual([
+      'https://fonts.googleapis.com/css2?family=Amiri&family=Cabin:wght@400&display=swap',
+    ])
+  })
+
+  it('logs which families were fetched from Google, and not the ones that were not', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const base = B('logged')
+    setFontsBaseUrl(base, ['Inter'])
+    ensureGoogleFontsLoaded(['Inter:wght@400', 'Cantata+One'])
+    expect(warn).toHaveBeenCalledOnce()
+    expect(warn.mock.calls[0][0]).toContain('Cantata+One')
+    expect(warn.mock.calls[0][0]).toContain('fonts.googleapis.com')
+    expect(warn.mock.calls[0][0]).not.toContain('Inter')
+  })
+
+  it('does not re-log per overlay', () => {
+    const base = B('repeat')
+    setFontsBaseUrl(base, ['Inter'])
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    ensureGoogleFontsLoaded(['Eczar'])
+    ensureGoogleFontsLoaded(['Eczar'])
+    expect(warn).toHaveBeenCalledOnce()
+    expect(injectedHrefs()).toHaveLength(1)
+  })
+
+  it('the defensive string coercion still holds with a base set', () => {
+    const base = B('coercion')
+    setFontsBaseUrl(base, ['Inter'])
+    // A bare string used to throw "n.map is not a function" and surface as
+    // "overlay error: <file>.jsx", taking the whole overlay layer with it.
+    expect(() => ensureGoogleFontsLoaded('Dosis,Inter:wght@400' as unknown as string[])).not.toThrow()
+    expect(injectedHrefs()).toEqual([
+      `${base}/fonts.css`,
+      'https://fonts.googleapis.com/css2?family=Dosis&display=swap',
+    ])
+  })
+})
+
+// THE FAILURE MODE, and it is deliberate in this direction.
+//
+// A base with no family list means NOTHING is vendored: no vendored <link>,
+// every family from Google. The tempting opposite — assume the sheet covers
+// what was asked for — is the SILENT-wrong option: an unvendored family would
+// get no stylesheet at all and preview as a system fallback, while the render
+// (reading its manifest off local disk, where it cannot fail independently)
+// fetched that same family from Google and got it right. Preview and export
+// would disagree with nothing on screen to say so — the Syne bug exactly.
+// This way is loud-wrong: glyphs correct, both sides agreeing, cost is egress,
+// and egress is the one failure the logging already detects.
+describe('setFontsBaseUrl: a base with no family list', () => {
+  for (const [label, families] of [
+    ['omitted', undefined],
+    ['empty', []],
+    ['not an array', 'Inter'],
+    ['all non-strings', [7, null]],
+  ] as [string, unknown][]) {
+    it(`${label}: nothing is vendored, the stylesheet is not linked, everything goes to Google`, () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const base = B(`nolist-${label.replace(/\s/g, '-')}`)
+      setFontsBaseUrl(base, families as string[] | undefined)
+      ensureGoogleFontsLoaded([`Q${label.replace(/\s/g, '')}`, 'Inter:wght@400'])
+
+      const hrefs = injectedHrefs()
+      expect(hrefs).toHaveLength(1)
+      expect(hrefs[0]).toContain('fonts.googleapis.com')
+      expect(hrefs[0]).toContain('family=Inter:wght@400')
+      expect(hrefs[0]).not.toContain('fonts.css')
+      expect(warn.mock.calls[0][0]).toContain('treating NOTHING as vendored')
+    })
+  }
+})
+
+// ---------------------------------------------------------------------------
+// The shared partition primitives
+// ---------------------------------------------------------------------------
+describe('fontFamilyKey: a spec normalises to the family name fonts.css declares', () => {
+  for (const [spec, key] of [
+    ['Baloo+2:wght@400;500', 'baloo 2'],
+    ['Playfair+Display:ital@1', 'playfair display'],
+    ['Anton', 'anton'],
+    ['Source+Serif+4:wght@400;700', 'source serif 4'],
+    ['Inter:wght@400;600;700;800', 'inter'],
+    ['Playfair Display', 'playfair display'],   // a literal space, not '+'
+    ['  Anton  ', 'anton'],
+    ['DM+SANS', 'dm sans'],                     // CSS family matching is case-insensitive
+  ]) {
+    it(`${JSON.stringify(spec)} → ${JSON.stringify(key)}`, () => {
+      expect(fontFamilyKey(spec)).toBe(key)
+    })
+  }
+})
+
+describe('partitionFontSpecs', () => {
+  it('preserves the caller order within each side', () => {
+    const keys = vendoredKeySet(['Inter', 'Baloo 2'])
+    expect(partitionFontSpecs(['Anton', 'Inter:wght@400', 'Syne', 'Baloo+2'], keys)).toEqual({
+      vendored: ['Inter:wght@400', 'Baloo+2'],
+      fellThrough: ['Anton', 'Syne'],
+    })
+  })
+
+  it('an empty vendored set falls everything through', () => {
+    expect(partitionFontSpecs(['Anton', 'Inter'], new Set())).toEqual({
+      vendored: [],
+      fellThrough: ['Anton', 'Inter'],
+    })
+  })
+
+  it('drops non-string list entries rather than coercing them into families', () => {
+    // String(7) would otherwise become a "family" named "7".
+    expect(vendoredKeySet(['Inter', 7, null, 'Baloo 2'] as unknown[])).toEqual(
+      new Set(['inter', 'baloo 2']),
+    )
+  })
+})
+
+// THE CROSS-LANGUAGE GATE. The renderers carry this same algorithm in plain
+// JS; a textual parity test cannot span TypeScript and JavaScript, so both
+// suites pin the SAME literal digest for the SAME family list instead. If this
+// value and the one in `montaj_assets/render/test/fonts-fallthrough.test.mjs`
+// ever disagree, the editor and the renderers are fingerprinting differently
+// and the digest stops being able to prove they agree — which is the only job
+// it has. Change one, change the other, and only ever deliberately.
+describe('familiesDigest', () => {
+  const PRODUCTION_20 = [
+    'Baloo 2', 'Bebas Neue', 'DM Sans', 'Fredoka', 'Inter', 'JetBrains Mono', 'Lato',
+    'Merriweather', 'Montserrat', 'Nunito', 'Open Sans', 'Oswald', 'Playfair Display',
+    'Poppins', 'Raleway', 'Roboto', 'Rubik', 'Sniglet', 'Source Serif 4', 'Work Sans',
+  ]
+
+  // The faces those twenty actually resolve to, as `families.json` records
+  // them. Bebas Neue is the one family whose `faces` and `requested` differ:
+  // it publishes no 700, so we asked for one and received only the 400.
+  const W: Record<string, number[]> = {
+    'Baloo 2': [400, 500, 600, 700, 800], Fredoka: [300, 400, 500, 600, 700], Sniglet: [400, 800],
+  }
+  const faces: Record<string, { normal: number[] }> = {}
+  const requested: Record<string, { normal: number[] }> = {}
+  for (const f of PRODUCTION_20) {
+    requested[f] = { normal: W[f] ?? [400, 700] }
+    faces[f] = { normal: f === 'Bebas Neue' ? [400] : (W[f] ?? [400, 700]) }
+  }
+  const INDEX = vendoredFaceIndex(faces, requested)
+
+  it('the shipped manifest has the digest the render suite also pins', () => {
+    expect(familiesDigest(vendoredKeySet(PRODUCTION_20), INDEX)).toBe('1fcf41c1')
+  })
+
+  // Unchanged from before faces existed, which is the point: a manifest
+  // carrying no face information still digests exactly as an older renderer
+  // would, so the two stay comparable.
+  it('a manifest with no face information keeps its original digest', () => {
+    expect(familiesDigest(vendoredKeySet(PRODUCTION_20))).toBe('63d7e733')
+  })
+
+  // The reason the digest had to grow: same twenty family NAMES, one weight
+  // fewer. A families-only fingerprint reports a match here, which is exactly
+  // the silent drift it exists to make loud.
+  it('dropping a single WEIGHT moves the digest, though every family name is unchanged', () => {
+    const thinner = vendoredFaceIndex(
+      { ...faces, Inter: { normal: [400] } },
+      { ...requested, Inter: { normal: [400] } },
+    )
+    expect(familiesDigest(vendoredKeySet(PRODUCTION_20), thinner)).toBe('7b42f0b4')
+    expect(familiesDigest(vendoredKeySet(PRODUCTION_20), thinner))
+      .not.toBe(familiesDigest(vendoredKeySet(PRODUCTION_20), INDEX))
+  })
+
+  it('gaining an ITALIC face moves the digest — the style axis is in the input too', () => {
+    const italic = vendoredFaceIndex(
+      { ...faces, 'Playfair Display': { normal: [400, 700], italic: [400] } },
+      requested,
+    )
+    expect(familiesDigest(vendoredKeySet(PRODUCTION_20), italic))
+      .not.toBe(familiesDigest(vendoredKeySet(PRODUCTION_20), INDEX))
+  })
+
+  it('is order- and spelling-independent, and changes when the set changes', () => {
+    const a = familiesDigest(vendoredKeySet(['Inter', 'Baloo 2']))
+    expect(familiesDigest(vendoredKeySet(['Baloo+2', 'inter']))).toBe(a)
+    expect(familiesDigest(vendoredKeySet(['Inter']))).not.toBe(a)
+  })
+
+  it('is eight hex characters', () => {
+    expect(familiesDigest(vendoredKeySet(PRODUCTION_20))).toMatch(/^[0-9a-f]{8}$/)
+  })
+})

package/src/lib/font-families.ts

@@ -0,0 +1,286 @@
+// The vendored-font partition, shared by the package's two Google Fonts
+// loaders (`lib/google-fonts.ts` and `text/FontPicker.tsx`).
+//
+// The two loaders stay independent — separate setters, separate injection
+// state, neither imports the other — but they must reach the SAME answer about
+// which families a vendored stylesheet covers. That is not a style preference:
+// a family served locally by one and from Google by the other is a caption
+// laid out in one face while editing and a different one at export, which is
+// the bug `skills/write-overlay/SKILL.md`'s Syne case study exists to document.
+//
+// The two renderers (`montaj_assets/render/bundle.js`,
+// `render-carousel.js`) keep hand-copied versions of these same three
+// functions, textually pinned against each other by `shim-bake.test.mjs`. They
+// have to copy: they are separate CLI entry points that share no module and
+// cannot import this package. These two loaders CAN import, so they do —
+// a copy that cannot drift beats a copy pinned not to.
+
+/** A `googleFonts` entry is a SPEC, not a family name: "Baloo+2:wght@400;500",
+ *  "Playfair+Display:ital@1", "Anton". Everything from the first ':' is the
+ *  axis list, and '+' is how Google's API encodes the space in a family name —
+ *  strip the one, undo the other, and what is left is the family exactly as
+ *  `fonts.css` spells it in its `font-family` declarations, which is what the
+ *  vendored family list holds.
+ *
+ *  Case-folded because CSS font-family matching is case-insensitive: a spec
+ *  that differs from the list only in case names a family the vendored
+ *  stylesheet genuinely serves, and treating it as unvendored would buy
+ *  nothing but a fetch from Google. */
+export function fontFamilyKey(spec: string): string {
+  return String(spec).split(':')[0].replace(/\+/g, ' ').trim().toLowerCase()
+}
+
+/** Normalise a host-supplied family list into the comparison set.
+ *
+ *  List entries go through `fontFamilyKey` too, not just the requested specs.
+ *  Deliberate leniency: a host that passes Google's '+'-encoded spelling
+ *  ("Open+Sans") rather than the `fonts.css` one still matches, and the
+ *  failure it avoids is silent egress for a family sitting right there on
+ *  disk. Non-strings are dropped rather than coerced — a number in the list
+ *  is a host bug, and `String(7)` would silently become a "family". */
+export function vendoredKeySet(families: readonly unknown[] | undefined): Set<string> {
+  if (!Array.isArray(families)) return new Set()
+  return new Set(families.filter((f): f is string => typeof f === 'string').map(fontFamilyKey))
+}
+
+/** Split requested specs into the ones the vendored stylesheet covers and the
+ *  ones that must still come from Google. Order within each list is the
+ *  caller's original order, so the googleapis URL reads the way the project
+ *  declared it. */
+export function partitionFontSpecs(
+  specs: readonly string[],
+  vendoredKeys: Set<string>,
+  faceIndex?: FaceIndex,
+): { vendored: string[]; fellThrough: string[] } {
+  const vendored: string[] = []
+  const fellThrough: string[] = []
+  for (const spec of specs) {
+    const covered =
+      vendoredKeys.has(fontFamilyKey(spec)) && (!faceIndex || specFacesAvailable(spec, faceIndex))
+    ;(covered ? vendored : fellThrough).push(spec)
+  }
+  return { vendored, fellThrough }
+}
+
+// ---------------------------------------------------------------------------
+// Faces: the family list is not precise enough on its own
+// ---------------------------------------------------------------------------
+//
+// The vendored set is family + STYLE + WEIGHT, not family. `fonts.css` carries
+// only the faces the vendoring pass actually received — every face is
+// `font-style: normal`, and the weights are only the ones it asked for. So a
+// family-level partition gets `Playfair+Display:ital@1` wrong: the family
+// matches, the spec is treated as vendored, the real italic is never fetched,
+// and the browser synthesises an oblique from the upright. `Inter:wght@300` is
+// the same shape one axis over. Both are silent — no failed request, nothing
+// on screen — and both change what the user sees, which is the entire defect
+// this refinement removes.
+//
+// The face index REFINES the family partition and can only ever move a spec
+// from "vendored" to "fell through", never the reverse. Passing no index means
+// no refinement, which is the family-level behaviour that predates this.
+
+export type FaceList = { normal?: readonly number[]; italic?: readonly number[] }
+export type FaceMap = Readonly<Record<string, FaceList>>
+export type FaceIndex = Map<string, { normal: Set<number>; italic: Set<number> }>
+
+/** Resolve a `googleFonts` SPEC to the concrete faces it asks Google for, or
+ *  `null` for "I cannot parse this confidently".
+ *
+ *  `null` MUST be treated as a fall-through by the caller. That is the safe
+ *  direction and it is this feature's established philosophy: fetching a font
+ *  we happen to have costs one request, while silently dropping one we lack
+ *  costs the author a wrong face in a finished export with no visible cause.
+ *
+ *  A spec is `Family[:axes@tuples]`, where the axes are named in one
+ *  comma-separated list and their values in another, POSITIONALLY:
+ *
+ *    Anton                                   → normal 400  (Google's default)
+ *    Inter:wght@400;700                      → normal 400, normal 700
+ *    Playfair+Display:ital@1                 → italic 400
+ *    Playfair+Display:ital,wght@1,700        → italic 700
+ *    Playfair+Display:ital,wght@0,400;1,700  → normal 400, italic 700
+ *
+ *  `ital@0` is normal and `ital@1` is italic. Any other axis (`opsz`, `slnt`,
+ *  a custom one like `GRAD`), any variable RANGE (`wght@100..900`), a
+ *  duplicated axis, or a tuple whose arity does not match the axis list all
+ *  return `null` rather than a guess. */
+export function requiredFaces(spec: string): { style: 'normal' | 'italic'; weight: number }[] | null {
+  const s = String(spec)
+  const colon = s.indexOf(':')
+  // No axis list: Google serves the family's default face, which is normal 400.
+  if (colon === -1) return [{ style: 'normal', weight: 400 }]
+
+  const axisPart = s.slice(colon + 1)
+  const at = axisPart.indexOf('@')
+  // `Family:` with no '@' at all, or more than one — not a shape we model.
+  if (at === -1 || axisPart.indexOf('@', at + 1) !== -1) return null
+
+  const axes = axisPart.slice(0, at).split(',')
+  const tuples = axisPart.slice(at + 1).split(';')
+  const iItal = axes.indexOf('ital')
+  const iWght = axes.indexOf('wght')
+  // Every axis must be one we model. An unmodelled, duplicated or empty axis
+  // name makes the face set unknowable, and a guess here is the silent-wrong
+  // answer this whole refinement exists to delete.
+  for (let i = 0; i < axes.length; i++) if (i !== iItal && i !== iWght) return null
+
+  const faces: { style: 'normal' | 'italic'; weight: number }[] = []
+  for (const tuple of tuples) {
+    const values = tuple.split(',')
+    if (values.length !== axes.length) return null
+    let style: 'normal' | 'italic' = 'normal'
+    let weight = 400
+    if (iItal !== -1) {
+      const v = values[iItal]
+      if (v === '0') style = 'normal'
+      else if (v === '1') style = 'italic'
+      else return null // an `ital` range (0..1), or junk
+    }
+    if (iWght !== -1) {
+      const v = values[iWght]
+      if (!/^\d{1,4}$/.test(v)) return null // a `wght` range (100..900), or junk
+      weight = Number(v)
+      if (weight < 1 || weight > 1000) return null
+    }
+    faces.push({ style, weight })
+  }
+  return faces
+}
+
+/** Build the face index from the manifest's `faces` and `requested` maps.
+ *
+ *  A face counts as AVAILABLE if it is in `faces` (we have the file) or in
+ *  `requested` (we asked Google for it and were refused). The second half is
+ *  not a special case: the gap between the two maps is exactly "weights Google
+ *  does not publish", and falling through for one of those fetches a
+ *  stylesheet that declines identically — a guaranteed-useless request rather
+ *  than a probably-useless one. `Bebas+Neue:wght@400;700` is the only spec
+ *  that exercises it today; Bebas Neue ships no 700 face at all.
+ *
+ *  Family keys go through `fontFamilyKey`, matching `vendoredKeySet`'s
+ *  leniency, so a manifest written with Google's '+'-encoded spelling still
+ *  matches. Malformed entries are skipped rather than thrown on: a manifest
+ *  this code cannot read must degrade to "no information", never to a crash
+ *  inside a fire-and-forget font load. */
+export function vendoredFaceIndex(faces?: FaceMap, requested?: FaceMap): FaceIndex | undefined {
+  const usable = [faces, requested].filter((m) => m && typeof m === 'object' && !Array.isArray(m))
+  // NO face information at all is different from face information that covers
+  // nothing. The first leaves the partition at family level (the behaviour
+  // that predates this refinement, for a manifest or a host that predates it
+  // too); the second says every requested face is genuinely absent. Returning
+  // an empty Map for both would silently turn an old manifest into "nothing is
+  // vendored", which is safe but wrong to do without saying so.
+  if (!usable.length) return undefined
+
+  const index: FaceIndex = new Map()
+  for (const source of usable as FaceMap[]) {
+    for (const [family, styles] of Object.entries(source)) {
+      if (!styles || typeof styles !== 'object') continue
+      const key = fontFamilyKey(family)
+      let entry = index.get(key)
+      if (!entry) index.set(key, (entry = { normal: new Set(), italic: new Set() }))
+      for (const style of ['normal', 'italic'] as const) {
+        const weights = styles[style]
+        if (!Array.isArray(weights)) continue
+        for (const w of weights) if (Number.isInteger(w)) entry[style].add(w as number)
+      }
+    }
+  }
+  return index
+}
+
+/** Whether every face `spec` requires is available locally.
+ *
+ *  A family with no entry in the index is NOT covered — the index is built
+ *  from the same manifest as the family list, so a family present in one and
+ *  absent from the other means the two disagree, and the safe reading of a
+ *  disagreement is "fall through".
+ *
+ *  A PARTIALLY vendored spec falls through WHOLE. `Inter:wght@400;300` goes to
+ *  Google as one spec rather than being split into a vendored half and a
+ *  fetched half. Splitting would mean synthesising a new spec string, and a
+ *  spec is the author's — ours to honour or to pass on untouched, never to
+ *  rewrite. */
+export function specFacesAvailable(spec: string, index: FaceIndex): boolean {
+  const entry = index.get(fontFamilyKey(spec))
+  if (!entry) return false
+  const required = requiredFaces(spec)
+  if (!required) return false
+  return required.every((f) => entry[f.style].has(f.weight))
+}
+
+/** A short, stable fingerprint of a vendored set, logged once by each loader
+ *  and once per render by each renderer. It turns an invisible divergence into
+ *  two visibly different strings: if the editor's digest and the render's
+ *  digest disagree, the two sides are partitioning against different vendored
+ *  sets and captions WILL differ between editing and export. QA compares two
+ *  hashes instead of trying to observe a partition.
+ *
+ *  **It fingerprints the FACES, not just the families, when face information
+ *  is available.** A families-only digest would report a match across a set
+ *  that materially changed — re-vendor at a different weight, or drop one, and
+ *  every family name is still identical while what the stylesheet can actually
+ *  resolve is not. That is precisely the silent drift this exists to make
+ *  loud, so the weights and styles go into the input too.
+ *
+ *  With NO face index the input is byte-for-byte what it was before faces
+ *  existed, so a family-only manifest keeps producing its old digest and stays
+ *  comparable against an older renderer. A face index therefore changes the
+ *  value exactly when there is new information to report, never incidentally.
+ *
+ *  FNV-1a over the sorted lines, not a crypto hash, and that is deliberate: it
+ *  must be computable synchronously in a browser (`crypto.subtle` is async),
+ *  and it is a comparison token, never a security primitive.
+ *
+ *  The renderers carry the same algorithm in plain JS. The gate that keeps the
+ *  two languages honest is a literal digest pinned in BOTH test suites for the
+ *  same manifest — this TS↔JS seam is the one place a textual comparison
+ *  cannot reach, which is why the literal is the pin. */
+export function familiesDigest(keys: Iterable<string>, faceIndex?: FaceIndex): string {
+  const lines = [...keys].sort().map((key) => {
+    const entry = faceIndex ? faceIndex.get(key) : undefined
+    if (!entry) return key
+    const axis = (style: 'normal' | 'italic') =>
+      `${style}:${[...entry[style]].sort((a, b) => a - b).join(',')}`
+    return `${key}\t${axis('normal')}\t${axis('italic')}`
+  })
+  let h = 0x811c9dc5
+  for (const ch of lines.join('\n')) {
+    h = Math.imul(h ^ (ch.codePointAt(0) as number), 0x01000193) >>> 0
+  }
+  return h.toString(16).padStart(8, '0')
+}
+
+/** One line naming the vendored set a loader is about to partition against,
+ *  or — when a base was set without one — the loud warning that nothing will
+ *  be treated as vendored.
+ *
+ *  "No list" means every requested family goes to Google and the vendored
+ *  stylesheet is not linked at all. The tempting opposite, assuming the sheet
+ *  covers what was asked for, is the SILENT-wrong option: an unvendored family
+ *  would get no stylesheet at all and preview as a system fallback, while the
+ *  render — reading its own manifest off local disk, where it cannot fail
+ *  independently — would fetch that same family from Google and get it right.
+ *  Preview and export would disagree with nothing on screen to say so. This
+ *  way is loud-wrong instead: every glyph is correct, both sides agree, and
+ *  the only cost is egress, which is the one failure this logging detects. */
+export function reportVendoredSet(base: string, vendoredKeys: Set<string>, faceIndex?: FaceIndex): void {
+  if (!vendoredKeys.size) {
+    console.warn(
+      `[montaj] fonts: a base was set (${base}) with no vendored family list — treating NOTHING as vendored, `
+        + 'so the vendored stylesheet is not linked and every requested family is fetched from fonts.googleapis.com',
+    )
+    return
+  }
+  console.info(`[montaj] fonts: vendored set ${familiesDigest(vendoredKeys, faceIndex)} (${vendoredKeys.size} families) at ${base}`)
+}
+
+/** Name the families that crossed to Google. An author who names a family the
+ *  vendored set does not carry should learn it while editing, not by noticing
+ *  the wrong face in a finished export. Mirrors the renderers' line of the
+ *  same text so a log from either side reads identically. */
+export function reportUnvendoredFonts(fellThrough: readonly string[]): void {
+  if (!fellThrough.length) return
+  console.warn(`[montaj] fonts: not in the vendored set, fetching from fonts.googleapis.com: ${fellThrough.join(', ')}`)
+}