@bycrux/editor 1.2.0 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bycrux/editor",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "private": false,
   "type": "module",
   "exports": {
@@ -17,7 +17,7 @@
     "lint": "eslint src"
   },
   "dependencies": {
-    "@bycrux/timeline-core": "^0.2.1",
+    "@bycrux/timeline-core": "^0.2.2",
     "class-variance-authority": "^0.7",
     "clsx": "^2",
     "lucide-react": "^0.400",

package/src/engine/__tests__/scheduler.test.ts

@@ -514,6 +514,41 @@ describe('transportEndFor', () => {
     })
     expect(transportEndFor(p)).toBe(6)
   })
+
+  it('falls back to the audio end when NOTHING visual sets a ceiling', () => {
+    // Audio-only timeline: the shape an animations-workflow project has while
+    // the music is wired but no overlay exists yet. The ceiling was 0, so the
+    // transport started and stopped on the same tick and play did nothing at
+    // all — with no feedback saying why.
+    const p = project([], [], {
+      audio: { tracks: [{ id: 'm', src: '/m.wav', start: 0, end: 15 }] },
+    })
+    expect(transportEndFor(p)).toBe(15)
+  })
+
+  it('resolves an audio-only track carrying no explicit end to its natural length', () => {
+    const p = project([], [], {
+      // `AudioTrack` types `start`/`end` as required, but project.json files on
+      // disk routinely omit them — `resolveAudioWindow` exists precisely to cope
+      // at runtime. That gap between the type and the real shape is what this
+      // test pins, so the under-specified track is the point, not a shortcut.
+      // @ts-expect-error — deliberately the under-specified on-disk shape
+      audio: { tracks: [{ id: 'm', src: '/m.wav', sourceDuration: 15 }] },
+    })
+    expect(transportEndFor(p)).toBe(15)
+  })
+
+  it('skips muted tracks in the audio-only fallback', () => {
+    const p = project([], [], {
+      audio: {
+        tracks: [
+          { id: 'a', src: '/a.wav', start: 0, end: 30, muted: true },
+          { id: 'b', src: '/b.wav', start: 0, end: 15 },
+        ],
+      },
+    })
+    expect(transportEndFor(p)).toBe(15)
+  })
 })
 
 describe('engineSrcFor — proxy-only playback is structural', () => {

package/src/engine/scheduler.ts

@@ -83,7 +83,7 @@ import type { ItemCrossfade, Scene, SourceWindow } from '@bycrux/timeline-core'
 import type { EditorProject as Project, VisualItem, VisualTrack } from '../schema'
 import type { ClipTimebase, MasterClock } from './audio-clock'
 import type { FrameServer } from './frame-server'
-import { effectiveItemAudio, enabledTrackItems, enabledTracks, withEnabledItemTracks } from '../video/timeline/timeline-model'
+import { audioEnd, effectiveItemAudio, enabledTrackItems, enabledTracks, withEnabledItemTracks } from '../video/timeline/timeline-model'
 
 // ── Tuning constants ────────────────────────────────────────────────────────
 
@@ -548,7 +548,15 @@ export function transportEndFor(project: Project): number {
     (m: number, s) => Math.max(m, s.end ?? 0),
     0,
   )
-  return Math.max(visualEnd, captionEnd)
+  const ceiling = Math.max(visualEnd, captionEnd)
+  if (ceiling > 0) return ceiling
+  // Nothing visual sets a ceiling: an audio-only timeline. Returning 0 here
+  // started the transport and stopped it in the same tick, so play did nothing
+  // at all. Audio is otherwise deliberately kept out of the ceiling (the
+  // canvas/video divergence over the audio tail, above) — this is the last
+  // resort that only fires when there is no visual content to measure.
+  // Mirrored in `canvasMaxEndRef` (video/preview/useVideoPlayback.ts).
+  return audioEnd(project)
 }
 
 /**

package/src/index.ts

@@ -37,6 +37,7 @@ export type {
   RenderPhase,
   CaptionEvent,
   GenerateCaptionsOptions,
+  CaptionProfileDefaults,
   MediaScope,
   MediaItem,
   GlobalOverlay,
@@ -169,6 +170,38 @@ export {
   FontSizePicker,
 } from './text/FontPicker'
 export type { FontOption } from './text/FontPicker'
+// Two independent Google Fonts base-URL setters, one per loader — see each
+// file's own header for why there are two. `setFontsBaseUrl` (from
+// `lib/google-fonts.ts`) covers the broader surface: captions, overlays and
+// the timeline/overlay preview. `setPickerFontsBaseUrl` (renamed at this
+// export boundary only — the source file still calls it `setFontsBaseUrl`,
+// same as the other loader) covers just the font-family picker's own
+// preview list. A host must call BOTH to eliminate Google Fonts egress
+// entirely; calling only one still leaves the other loader fetching from
+// fonts.googleapis.com.
+//
+// Both take the same two arguments: `(url, families)`. `families` is the list
+// of families the stylesheet at `url` declares — the host reads its own
+// `families.json` (or equivalent) ONCE at app init and passes the result to
+// both setters. It is deliberately not fetched inside the loaders: they are
+// synchronous and called from effects, and a pending fetch would leave them
+// unable to decide the partition at the moment they have to act on it.
+//
+// **Passing a url with no families means NOTHING is treated as vendored** —
+// the vendored stylesheet is not linked and every family is fetched from
+// Google. That is the safe direction: glyphs stay correct and preview and
+// render still agree, at the cost of the egress the base exists to remove.
+// Assuming the stylesheet covers everything would instead preview unvendored
+// families as a system fallback while the renderer — reading its own manifest
+// off local disk — got them right, and nothing on screen would say so.
+//
+// `vendoredFamiliesDigest()` returns a short fingerprint of the family list in
+// force. The renderers log the same digest for the manifest they read; two
+// different strings mean the two sides are partitioning against different
+// vendored sets, and captions will differ between editing and export.
+export { setFontsBaseUrl, vendoredFamiliesDigest } from './lib/google-fonts'
+export { setFontsBaseUrl as setPickerFontsBaseUrl } from './text/FontPicker'
+export { fontFamilyKey, familiesDigest, partitionFontSpecs, vendoredKeySet } from './lib/font-families'
 export { InlineTextEditor } from './text/InlineTextEditor'
 export type { InlineTextEditorProps } from './text/InlineTextEditor'
 export {

package/src/lib/__tests__/font-faces.test.ts

@@ -0,0 +1,244 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { ensureGoogleFontsLoaded, setFontsBaseUrl } from '../google-fonts'
+import { requiredFaces, specFacesAvailable, vendoredFaceIndex } from '../font-families'
+
+// THE FACE-LEVEL PARTITION (L1).
+//
+// 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. A
+// family-level partition therefore gets two shapes silently wrong:
+//
+//   Playfair+Display:ital@1  — family vendored, no italic face exists, so the
+//                              browser synthesises an oblique from the upright.
+//   Inter:wght@300           — family vendored, no 300 face exists, so the
+//                              browser synthesises a light weight from the 400.
+//
+// Neither produces a failed request or a console error, and both change what
+// the user sees. `skills/write-overlay/SKILL.md` uses the first as its own
+// documented example.
+//
+// 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 caption laid out in one face while editing and
+// another at export is the Syne bug that case study documents.
+
+const N = (weight: number) => ({ style: 'normal', weight })
+const I = (weight: number) => ({ style: 'italic', weight })
+
+describe('requiredFaces: a spec resolves to the faces it asks Google for', () => {
+  for (const [spec, want] of [
+    // No axis list — Google serves the family default, which is normal 400.
+    ['Anton', [N(400)]],
+    ['Playfair Display', [N(400)]],
+    ['Inter:wght@400;700', [N(400), N(700)]],
+    ['Inter:wght@300', [N(300)]],
+    ['Playfair+Display:ital@1', [I(400)]],
+    ['Playfair+Display:ital@0', [N(400)]],
+    // The axes are named in one list and their values in another, positionally.
+    ['Playfair+Display:ital,wght@1,700', [I(700)]],
+    ['Playfair+Display:ital,wght@0,400;1,700', [N(400), I(700)]],
+    ['Baloo+2:wght@400;500;600;700;800', [N(400), N(500), N(600), N(700), N(800)]],
+  ] as [string, ReturnType<typeof N>[]][]) {
+    it(`${spec} → ${JSON.stringify(want)}`, () => {
+      expect(requiredFaces(spec)).toEqual(want)
+    })
+  }
+
+  // `null` means "I cannot parse this confidently" and the caller must fall
+  // through. Fetching a font we happen to have costs one request; silently
+  // dropping one we lack costs the author a wrong face in a finished export.
+  for (const spec of [
+    'Inter:',                  // a colon with no axis list
+    'Inter:wght',              // an axis with no '@'
+    'Inter:wght@',             // an '@' with no value
+    'Inter:wght@400;',         // a trailing ';' leaves an empty tuple
+    'Inter:wght@100..900',     // a variable RANGE is not a face
+    'Inter:ital@0..1',
+    'Inter:opsz@14',           // an axis we do not model
+    'Inter:slnt@-10',
+    'Inter:GRAD@150',
+    'Inter:wght,opsz@400,14',  // one modelled axis, one not
+    'Inter:wght,wght@400,700', // a duplicated axis
+    'Inter:ital,wght@1',       // arity mismatch: two axes, one value
+    'Inter:wght@400@700',      // two '@'
+    'Inter:ital@2',            // ital is 0 or 1, nothing else
+    'Inter:wght@0',            // out of range
+    'Inter:wght@abc',
+    'Inter:@400',              // an empty axis name
+  ]) {
+    it(`${spec} → null, so the caller falls through`, () => {
+      expect(requiredFaces(spec)).toBeNull()
+    })
+  }
+})
+
+describe('vendoredFaceIndex: `faces` and `requested` together say what is available', () => {
+  it('merges both maps — a weight in either one counts as available', () => {
+    // Bebas Neue publishes no 700, so we asked for it and got only the 400.
+    // Falling through would fetch a stylesheet that omits it identically.
+    const index = vendoredFaceIndex(
+      { 'Bebas Neue': { normal: [400] } },
+      { 'Bebas Neue': { normal: [400, 700] } },
+    )!
+    expect(specFacesAvailable('Bebas+Neue:wght@400;700', index)).toBe(true)
+    expect(specFacesAvailable('Bebas+Neue:wght@500', index)).toBe(false)
+  })
+
+  it('distinguishes NO face information from face information covering nothing', () => {
+    // Nothing supplied at all: the partition has nothing to refine against and
+    // must stay at family level, which the loader signals with `undefined`.
+    expect(vendoredFaceIndex(undefined, undefined)).toBeUndefined()
+    // An empty map IS information: it says nothing is available.
+    const empty = vendoredFaceIndex({}, undefined)
+    expect(empty).toBeInstanceOf(Map)
+    expect(specFacesAvailable('Inter', empty!)).toBe(false)
+  })
+
+  it('normalises family keys the way the family list does', () => {
+    const index = vendoredFaceIndex({ 'Open+Sans': { normal: [400] } })!
+    expect(specFacesAvailable('Open+Sans', index)).toBe(true)
+    expect(specFacesAvailable('OPEN SANS', index)).toBe(true)
+  })
+
+  it('skips malformed entries rather than throwing inside a font load', () => {
+    const index = vendoredFaceIndex({
+      Inter: { normal: [400, 'x' as unknown as number, null as unknown as number] },
+      Bad: null as unknown as { normal: number[] },
+      Worse: { normal: 'nope' as unknown as number[] },
+    })!
+    expect(specFacesAvailable('Inter', index)).toBe(true)
+    expect(specFacesAvailable('Bad', index)).toBe(false)
+    expect(specFacesAvailable('Worse', index)).toBe(false)
+  })
+
+  it('a family with no index entry is not covered', () => {
+    const index = vendoredFaceIndex({ Inter: { normal: [400] } })!
+    expect(specFacesAvailable('Anton', index)).toBe(false)
+  })
+
+  it('a spec it cannot parse is not covered, however complete the index', () => {
+    const index = vendoredFaceIndex({ Inter: { normal: [100, 200, 300, 400, 700, 900] } })!
+    expect(specFacesAvailable('Inter:wght@100..900', index)).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Through the loader
+// ---------------------------------------------------------------------------
+
+function injectedHrefs(): string[] {
+  return Array.from(document.head.querySelectorAll('link[rel="stylesheet"]')).map(
+    (l) => (l as HTMLLinkElement).href,
+  )
+}
+
+// The injected-URL Set is module state that outlives a single test, so every
+// base and every unvendored family below must be unique or a later test is
+// served a suppressed <link> and passes for the wrong reason.
+const B = (name: string) => `https://example.com/faces/${name}`
+
+const REAL = {
+  faces: {
+    'Playfair Display': { normal: [400, 700] },
+    Inter: { normal: [400, 700] },
+    'Bebas Neue': { normal: [400] },
+  },
+  requested: {
+    'Playfair Display': { normal: [400, 700] },
+    Inter: { normal: [400, 700] },
+    'Bebas Neue': { normal: [400, 700] },
+  },
+}
+const FAMILIES = ['Playfair Display', 'Inter', 'Bebas Neue']
+
+beforeEach(() => {
+  document.head.querySelectorAll('link[rel="stylesheet"]').forEach((l) => l.remove())
+  vi.spyOn(console, 'info').mockImplementation(() => {})
+  vi.spyOn(console, 'warn').mockImplementation(() => {})
+})
+afterEach(() => {
+  setFontsBaseUrl(undefined)
+  vi.restoreAllMocks()
+})
+
+describe('ensureGoogleFontsLoaded: the face refinement', () => {
+  for (const [spec, vendored, why] of [
+    ['Playfair+Display:ital@1', false, 'no italic face is vendored'],
+    ['Playfair+Display:ital,wght@1,700', false, 'italic 700 is not on disk either'],
+    ['Playfair+Display:ital@0', true, 'ital@0 is normal 400, which IS on disk'],
+    ['Inter:wght@300', false, '300 was never vendored'],
+    ['Inter:wght@400;700', true, 'both weights are on disk'],
+    ['Bebas+Neue:wght@400;700', true, 'Google publishes no 700, so asking again cannot help'],
+    ['Bebas+Neue:wght@500', false, '500 was neither vendored nor asked for'],
+  ] as [string, boolean, string][]) {
+    it(`${spec} is ${vendored ? 'served locally' : 'fetched from Google'} — ${why}`, () => {
+      const base = B(spec.replace(/\W/g, ''))
+      setFontsBaseUrl(base, FAMILIES, REAL)
+      ensureGoogleFontsLoaded([spec])
+      const hrefs = injectedHrefs()
+      if (vendored) {
+        expect(hrefs).toEqual([`${base}/fonts.css`])
+      } else {
+        expect(hrefs).toEqual([`https://fonts.googleapis.com/css2?family=${spec}&display=swap`])
+      }
+    })
+  }
+
+  it('a partially vendored spec falls through WHOLE, exactly as the author wrote it', () => {
+    // Splitting would mean synthesising a new spec string, and a spec is the
+    // author's — ours to honour or pass on untouched, never to rewrite.
+    const base = B('partial')
+    setFontsBaseUrl(base, FAMILIES, REAL)
+    ensureGoogleFontsLoaded(['Inter:wght@400;300'])
+    expect(injectedHrefs()).toEqual([
+      'https://fonts.googleapis.com/css2?family=Inter:wght@400;300&display=swap',
+    ])
+  })
+
+  it('a MIX puts each spec on exactly one side, by face and not by family', () => {
+    const base = B('mix')
+    setFontsBaseUrl(base, FAMILIES, REAL)
+    // Same family on both sides: the 700 is vendored, the italic is not.
+    //
+    // The italic spec here is spelled `ital,wght@1,400` rather than `ital@1`
+    // — the same FACE, a different URL. `__injectedFontUrls` dedupes on the
+    // full URL and is module state outliving a single test, so reusing the
+    // spelling an earlier case already injected would suppress this <link>
+    // and the assertion would fail for a reason that has nothing to do with
+    // the partition.
+    ensureGoogleFontsLoaded(['Playfair+Display:wght@700', 'Playfair+Display:ital,wght@1,400'])
+    const hrefs = injectedHrefs()
+    expect(hrefs).toEqual([
+      `${base}/fonts.css`,
+      'https://fonts.googleapis.com/css2?family=Playfair+Display:ital,wght@1,400&display=swap',
+    ])
+  })
+
+  it('omitting face data leaves the partition at family level', () => {
+    // A manifest vendored before the refinement existed carries no face
+    // information. That is a real shape, and it must degrade to the previous
+    // behaviour rather than treating every face as missing.
+    const base = B('nofaces')
+    setFontsBaseUrl(base, FAMILIES)
+    ensureGoogleFontsLoaded(['Playfair+Display:ital@1'])
+    expect(injectedHrefs()).toEqual([`${base}/fonts.css`])
+  })
+
+  it('faces cannot promote a family the list does not declare', () => {
+    const base = B('narrowing')
+    setFontsBaseUrl(base, ['Inter'], { faces: { Inter: { normal: [400] }, Zilch: { normal: [400] } } })
+    ensureGoogleFontsLoaded(['Zilch'])
+    expect(injectedHrefs()).toEqual(['https://fonts.googleapis.com/css2?family=Zilch&display=swap'])
+  })
+
+  it('names the fallen-through spec in the warning, and not the vendored one', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const base = B('logged')
+    setFontsBaseUrl(base, FAMILIES, REAL)
+    ensureGoogleFontsLoaded(['Inter:wght@400', 'Quire:ital@1'])
+    expect(warn).toHaveBeenCalledOnce()
+    expect(warn.mock.calls[0][0]).toContain('Quire:ital@1')
+    expect(warn.mock.calls[0][0]).not.toContain('Inter')
+  })
+})

package/src/lib/__tests__/font-loader-parity.test.tsx

@@ -0,0 +1,236 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { render, cleanup } from '@testing-library/react'
+import { FontFamilyPicker, setFontsBaseUrl as setPickerBase } from '../../text/FontPicker'
+import { ensureGoogleFontsLoaded, setFontsBaseUrl as setOverlayBase } from '../google-fonts'
+
+// ---------------------------------------------------------------------------
+// TWO LOADERS, ONE PARTITION
+// ---------------------------------------------------------------------------
+//
+// This package ships two independent Google Fonts loaders — `lib/google-fonts`
+// (captions, overlays, the timeline/overlay preview) and `text/FontPicker`
+// (the picker's own preview list). They keep separate bases and separate
+// injection state on purpose. They must NOT keep separate opinions about which
+// families a vendored stylesheet covers: one loader serving a family locally
+// while the other fetches it from Google is a caption in one face in the
+// picker and another on the canvas, with nothing on screen to explain it.
+//
+// The render package pins its two duplicated copies as identical SOURCE TEXT,
+// because its two renderers are separate CLI entry points that cannot import
+// each other. These two can import, and do — both partition through
+// `lib/font-families`. Textual parity would therefore be a test that cannot
+// fail. So this pins the property that actually matters instead: given the
+// same family list, the two loaders put the same families on the same side.
+//
+// Driving them is asymmetric because their inputs are: the overlay loader
+// takes the specs it is asked for, while the picker always requests its own
+// fixed FONT_OPTIONS set. So feed the picker's specs to the overlay loader and
+// compare what each one emits.
+
+function injectedHrefs(): string[] {
+  return Array.from(document.head.querySelectorAll('link[rel="stylesheet"]')).map(
+    (l) => (l as HTMLLinkElement).href,
+  )
+}
+
+/** The googleapis URL a loader emitted, reduced to its `family=` specs. */
+function googleSpecs(hrefs: string[]): string[] {
+  const url = hrefs.find((h) => h.includes('fonts.googleapis.com'))
+  if (!url) return []
+  return [...url.matchAll(/family=([^&]+)/g)].map((m) => decodeURIComponent(m[1]))
+}
+
+/** Whether a loader linked the vendored stylesheet. */
+const linkedVendored = (hrefs: string[]) => hrefs.some((h) => h.endsWith('/fonts.css'))
+
+// The picker's own spec list, read out of the module rather than restated, so
+// a change to FONT_OPTIONS cannot leave this comparing a stale set.
+async function pickerSpecs(): Promise<string[]> {
+  const { FONT_OPTIONS } = await import('../../text/FontPicker')
+  return FONT_OPTIONS.filter((f) => f.isGoogleFont).map(
+    (f) => f.spec ?? `${f.label.replace(/ /g, '+')}:wght@400;700`,
+  )
+}
+
+beforeEach(() => {
+  document.head.querySelectorAll('link[rel="stylesheet"]').forEach((l) => l.remove())
+  vi.spyOn(console, 'info').mockImplementation(() => {})
+  vi.spyOn(console, 'warn').mockImplementation(() => {})
+})
+afterEach(() => {
+  cleanup()
+  setPickerBase(undefined)
+  setOverlayBase(undefined)
+  vi.restoreAllMocks()
+})
+
+// Each case uses a base unique to itself: both loaders dedupe on the URLs they
+// have already injected, and that state outlives a test, so a repeated base
+// would make a loader look silent when it had merely already spoken.
+describe('the picker loader and the overlay loader partition identically', () => {
+  const CASES: [string, (all: string[]) => string[]][] = [
+    ['every picker family vendored', (all) => all.map(familyOf)],
+    ['none vendored', () => []],
+    ['one family missing from the vendored list', (all) => all.slice(1).map(familyOf)],
+    ['half vendored', (all) => all.slice(0, 10).map(familyOf)],
+    ['vendored list spelled Google-style, with +', (all) => all.map((s) => s.split(':')[0])],
+    ['vendored list in a different case', (all) => all.map((s) => familyOf(s).toUpperCase())],
+  ]
+
+  function familyOf(spec: string) {
+    return spec.split(':')[0].replace(/\+/g, ' ')
+  }
+
+  for (const [label, listFor] of CASES) {
+    it(label, async () => {
+      const specs = await pickerSpecs()
+      const families = listFor(specs)
+      const base = `https://example.com/fonts/parity-${label.replace(/[^a-z]+/gi, '-')}`
+
+      setPickerBase(base, families)
+      render(<FontFamilyPicker value="" onChange={() => {}} />)
+      const picker = injectedHrefs()
+
+      document.head.querySelectorAll('link[rel="stylesheet"]').forEach((l) => l.remove())
+
+      setOverlayBase(base, families)
+      ensureGoogleFontsLoaded(specs)
+      const overlay = injectedHrefs()
+
+      expect(googleSpecs(overlay)).toEqual(googleSpecs(picker))
+      expect(linkedVendored(overlay)).toBe(linkedVendored(picker))
+    })
+  }
+
+  it('and a host that sets only ONE of the two setters still leaves the other on Google', () => {
+    // Not a defect to fix here — it is the documented contract on
+    // `src/index.ts` — but it is the mistake a host will actually make, so
+    // pin that it stays visible rather than silently half-working.
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    setPickerBase('https://example.com/fonts/only-picker', ['Inter'])
+    // The overlay loader was never pointed anywhere, so it has no base at all.
+    ensureGoogleFontsLoaded(['Inter:wght@400'])
+    const hrefs = injectedHrefs()
+    expect(hrefs.some((h) => h.includes('fonts.googleapis.com'))).toBe(true)
+    // ...and the picker's own setter said out loud what it was given.
+    expect(warn.mock.calls.flat().join(' ')).not.toContain('treating NOTHING as vendored')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ...AND THEY AGREE AT FACE LEVEL TOO
+// ---------------------------------------------------------------------------
+//
+// The partition is family-level AND face-level: a spec is vendored only when
+// its family is declared and every face it requires is available. That second
+// half is the one that can disagree quietly, because both loaders can name the
+// same family while resolving different weights of it — and the picker is the
+// loader that requests `Bebas+Neue:wght@400;700`, the one shipped spec whose
+// answer depends on the `requested` map rather than on what is on disk.
+//
+// This is the TS half's parity mechanism. It is behavioural on purpose: both
+// loaders import `lib/font-families`, so there is no second copy to compare
+// textually and such a test could not fail. What can still diverge is how each
+// loader WIRES that shared code — which argument it passes, and whether it
+// passes the face index at all — and only running both can catch that.
+describe('the two loaders agree on the FACE partition, not just the family one', () => {
+  function familyOf(spec: string) {
+    return spec.split(':')[0].replace(/\+/g, ' ')
+  }
+
+  /** The faces the picker's own specs resolve to, with `broken` letting a case
+   *  remove something and check both loaders react the same way. */
+  function faceDataFor(specs: string[], broken?: (f: Record<string, { normal: number[] }>) => void) {
+    const faces: Record<string, { normal: number[] }> = {}
+    const requested: Record<string, { normal: number[] }> = {}
+    for (const spec of specs) {
+      const family = familyOf(spec)
+      const axes = spec.split(':')[1]
+      const weights = axes ? axes.slice('wght@'.length).split(';').map(Number) : [400]
+      requested[family] = { normal: weights }
+      // Bebas Neue publishes no 700, so it received only the 400 it asked for.
+      faces[family] = { normal: family === 'Bebas Neue' ? [400] : weights }
+    }
+    broken?.(faces)
+    return { faces, requested }
+  }
+
+  type Faces = Record<string, { normal: number[] }>
+  const CASES: [string, (specs: string[]) => { faces: Faces; requested?: Faces }][] = [
+    // Every picker spec satisfied — including Bebas Neue, and only because
+    // `requested` says Google was asked for the 700 and declined.
+    ['the real shipped manifest', (s) => faceDataFor(s)],
+    // Drop `requested` and Bebas Neue's missing 700 sends that spec to Google.
+    // Both loaders must send it, or neither.
+    ['faces only, no requested — Bebas Neue crosses to Google', (s) => ({ faces: faceDataFor(s).faces })],
+    // A weight removed from a family every picker spec asks for at 700.
+    ['a weight missing from Inter', (s) => faceDataFor(s, (f) => { f.Inter = { normal: [400] } })],
+    // Face information that covers nothing at all.
+    ['an empty faces map', () => ({ faces: {} })],
+  ]
+
+  for (const [label, dataFor] of CASES) {
+    it(label, async () => {
+      const specs = await pickerSpecs()
+      const families = specs.map(familyOf)
+      const faceData = dataFor(specs)
+      const base = `https://example.com/fonts/faceparity-${label.replace(/[^a-z]+/gi, '-')}`
+
+      setPickerBase(base, families, faceData)
+      render(<FontFamilyPicker value="" onChange={() => {}} />)
+      const picker = injectedHrefs()
+
+      document.head.querySelectorAll('link[rel="stylesheet"]').forEach((l) => l.remove())
+
+      setOverlayBase(base, families, faceData)
+      ensureGoogleFontsLoaded(specs)
+      const overlay = injectedHrefs()
+
+      expect(googleSpecs(overlay)).toEqual(googleSpecs(picker))
+      expect(linkedVendored(overlay)).toBe(linkedVendored(picker))
+    })
+  }
+
+  // The property the whole feature is for, asserted on the real shape: with
+  // the shipped manifest neither loader touches Google at all.
+  it('with the shipped manifest, NEITHER loader reaches Google', async () => {
+    const specs = await pickerSpecs()
+    const families = specs.map(familyOf)
+    const faceData = faceDataFor(specs)
+    const base = 'https://example.com/fonts/faceparity-zero-egress'
+
+    setPickerBase(base, families, faceData)
+    render(<FontFamilyPicker value="" onChange={() => {}} />)
+    expect(googleSpecs(injectedHrefs())).toEqual([])
+    expect(linkedVendored(injectedHrefs())).toBe(true)
+
+    document.head.querySelectorAll('link[rel="stylesheet"]').forEach((l) => l.remove())
+
+    setOverlayBase(base, families, faceData)
+    ensureGoogleFontsLoaded(specs)
+    expect(googleSpecs(injectedHrefs())).toEqual([])
+    expect(linkedVendored(injectedHrefs())).toBe(true)
+  })
+
+  // Both loaders log the same digest for the same manifest — the value that
+  // pins the TS↔JS seam. If one passed the face index and the other did not,
+  // the two lines would differ and this is where it would show.
+  it('both setters log the same digest for the same manifest', async () => {
+    const info = vi.spyOn(console, 'info').mockImplementation(() => {})
+    const specs = await pickerSpecs()
+    const families = specs.map(familyOf)
+    const faceData = faceDataFor(specs)
+
+    setPickerBase('https://example.com/fonts/digest-picker', families, faceData)
+    setOverlayBase('https://example.com/fonts/digest-overlay', families, faceData)
+
+    const digests = info.mock.calls
+      .map((c) => String(c[0]).match(/vendored set ([0-9a-f]{8})/)?.[1])
+      .filter(Boolean)
+    expect(digests).toHaveLength(2)
+    expect(digests[0]).toBe(digests[1])
+    // The same literal the render suite pins, so a divergence between the two
+    // languages surfaces here as well as there.
+    expect(digests[0]).toBe('1fcf41c1')
+  })
+})