From 38ed9184dca4c7beac262feaa94fc464e4968b60 Mon Sep 17 00:00:00 2001
From: Caio Pizzol <caio@superdoc.dev>
Date: Thu, 4 Jun 2026 22:02:42 -0300
Subject: [PATCH 1/8] feat(fonts): parse embedding policy from the font OS/2
 table

Reads a font's OS/2 table to decide whether a DOCX-embedded font may be registered for rendering (fsType licensing) and which weight/style FACE it is (usWeightClass + fsSelection italic bit), so embedded fonts can become first-class registry faces with the correct FaceKey instead of filename inference. Restricted-License fonts (fsType bit 1) are non-embeddable; a parse failure returns null so callers skip conservatively. Foundation for registering embedded fonts as providers, stacked on the registered_face ladder.
---
 shared/font-system/src/index.ts    |  3 ++
 shared/font-system/src/os2.test.ts | 87 ++++++++++++++++++++++++++++++
 shared/font-system/src/os2.ts      | 86 +++++++++++++++++++++++++++++
 3 files changed, 176 insertions(+)
 create mode 100644 shared/font-system/src/os2.test.ts
 create mode 100644 shared/font-system/src/os2.ts

diff --git a/shared/font-system/src/index.ts b/shared/font-system/src/index.ts
index b6f620966b..0720addf4d 100644
--- a/shared/font-system/src/index.ts
+++ b/shared/font-system/src/index.ts
@@ -56,6 +56,9 @@ export { setBundledFontAssetBase, getBundledFontAssetBase, DEFAULT_BUNDLED_FONT_
 export type { FontResolutionRecord, UsedFace } from './report';
 export { buildFontReport, buildFaceReport } from './report';
 
+export type { EmbeddingPolicy } from './os2';
+export { parseEmbeddingPolicy } from './os2';
+
 export type { FontSetLike, FontFaceLike, FontFaceCtor, FontRegistryOptions } from './registry';
 export {
   FontRegistry,
diff --git a/shared/font-system/src/os2.test.ts b/shared/font-system/src/os2.test.ts
new file mode 100644
index 0000000000..dd97cfee01
--- /dev/null
+++ b/shared/font-system/src/os2.test.ts
@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import { parseEmbeddingPolicy } from './os2';
+
+/**
+ * Build a minimal SFNT font with a single OS/2 table at a known offset, so the parser can be tested
+ * deterministically without a real font fixture. Layout: 12-byte offset table + one 16-byte table
+ * directory record (tag "OS/2") + the OS/2 table (only usWeightClass/fsType/fsSelection are set).
+ */
+function makeFont(opts: { usWeightClass: number; fsType: number; fsSelection: number; tag?: string }): ArrayBuffer {
+  const tag = opts.tag ?? 'OS/2';
+  const os2Offset = 28; // 12 (offset table) + 16 (one directory record)
+  const os2Length = 64; // through fsSelection @62-63
+  const buf = new ArrayBuffer(os2Offset + os2Length);
+  const dv = new DataView(buf);
+  dv.setUint32(0, 0x00010000); // sfnt version (TrueType)
+  dv.setUint16(4, 1); // numTables
+  for (let i = 0; i < 4; i += 1) dv.setUint8(12 + i, tag.charCodeAt(i));
+  dv.setUint32(16, 0); // checksum
+  dv.setUint32(20, os2Offset); // table offset
+  dv.setUint32(24, os2Length); // table length
+  dv.setUint16(os2Offset + 4, opts.usWeightClass);
+  dv.setUint16(os2Offset + 8, opts.fsType);
+  dv.setUint16(os2Offset + 62, opts.fsSelection);
+  return buf;
+}
+
+describe('parseEmbeddingPolicy (OS/2)', () => {
+  it('reads an installable Regular font: 400/normal, embeddable', () => {
+    expect(parseEmbeddingPolicy(makeFont({ usWeightClass: 400, fsType: 0x0000, fsSelection: 0 }))).toEqual({
+      fsType: 0x0000,
+      face: { weight: '400', style: 'normal' },
+      embeddable: true,
+    });
+  });
+
+  it('reads Bold (usWeightClass 700) and SemiBold (600) as the 700 face; 500 stays 400', () => {
+    expect(parseEmbeddingPolicy(makeFont({ usWeightClass: 700, fsType: 0, fsSelection: 0 }))?.face.weight).toBe('700');
+    expect(parseEmbeddingPolicy(makeFont({ usWeightClass: 600, fsType: 0, fsSelection: 0 }))?.face.weight).toBe('700');
+    expect(parseEmbeddingPolicy(makeFont({ usWeightClass: 500, fsType: 0, fsSelection: 0 }))?.face.weight).toBe('400');
+  });
+
+  it('reads the italic bit from fsSelection', () => {
+    expect(parseEmbeddingPolicy(makeFont({ usWeightClass: 400, fsType: 0, fsSelection: 0x01 }))?.face.style).toBe(
+      'italic',
+    );
+    expect(parseEmbeddingPolicy(makeFont({ usWeightClass: 700, fsType: 0, fsSelection: 0x01 }))?.face).toEqual({
+      weight: '700',
+      style: 'italic',
+    });
+  });
+
+  it('marks a Restricted-License font (fsType bit 1) as NOT embeddable', () => {
+    const policy = parseEmbeddingPolicy(makeFont({ usWeightClass: 400, fsType: 0x0002, fsSelection: 0 }));
+    expect(policy?.embeddable).toBe(false);
+    expect(policy?.fsType).toBe(0x0002);
+  });
+
+  it('treats Preview&Print and Editable as embeddable', () => {
+    expect(parseEmbeddingPolicy(makeFont({ usWeightClass: 400, fsType: 0x0004, fsSelection: 0 }))?.embeddable).toBe(
+      true,
+    );
+    expect(parseEmbeddingPolicy(makeFont({ usWeightClass: 400, fsType: 0x0008, fsSelection: 0 }))?.embeddable).toBe(
+      true,
+    );
+  });
+
+  it('returns null for non-SFNT / truncated bytes and for a font with no OS/2 table', () => {
+    expect(parseEmbeddingPolicy(new ArrayBuffer(4))).toBeNull(); // too short
+    expect(parseEmbeddingPolicy(makeFont({ usWeightClass: 400, fsType: 0, fsSelection: 0, tag: 'cmap' }))).toBeNull();
+  });
+
+  it('honors a typed-array view byteOffset (a subarray into a larger pooled buffer)', () => {
+    const font = makeFont({ usWeightClass: 700, fsType: 0x0002, fsSelection: 0x01 });
+    // Place the font at a non-zero offset inside a bigger buffer, then view it via subarray - the
+    // shape a deobfuscated Node Buffer / Uint8Array.subarray() takes. Reading from buffer offset 0
+    // would parse the leading padding, not the font.
+    const padded = new Uint8Array(font.byteLength + 128);
+    padded.set(new Uint8Array(font), 64);
+    const view = padded.subarray(64, 64 + font.byteLength);
+    expect(view.byteOffset).toBe(64);
+    expect(parseEmbeddingPolicy(view)).toEqual({
+      fsType: 0x0002,
+      face: { weight: '700', style: 'italic' },
+      embeddable: false,
+    });
+  });
+});
diff --git a/shared/font-system/src/os2.ts b/shared/font-system/src/os2.ts
new file mode 100644
index 0000000000..e0ac455071
--- /dev/null
+++ b/shared/font-system/src/os2.ts
@@ -0,0 +1,86 @@
+import type { FaceKey } from './resolver';
+
+/**
+ * The embedding policy + face axis read from a font's OS/2 table.
+ *
+ * Used to decide whether a DOCX-embedded font may be REGISTERED for rendering (its license permits
+ * embedding) and which weight/style FACE it represents - so embedded fonts become first-class
+ * registry faces with the correct {@link FaceKey} instead of being inferred from filenames.
+ */
+export interface EmbeddingPolicy {
+  /** Raw OS/2 `fsType` bit field (the licensing/embedding permissions). */
+  fsType: number;
+  /** The face this font provides, from OS/2 `usWeightClass` + the `fsSelection` italic bit. */
+  face: FaceKey;
+  /**
+   * The minimal RENDER gate: false only when fsType marks the font Restricted-License / no-embedding
+   * (bit 1). This is NOT a complete licensing model - Preview&Print vs Editable vs Installable, the
+   * No-Subsetting (0x0100) and Bitmap-only (0x0200) bits, and re-embedding for EXPORT/EDIT (vs
+   * display) all need their own policy decisions. The raw {@link fsType} is preserved so callers can
+   * apply a stricter policy without re-parsing.
+   */
+  embeddable: boolean;
+}
+
+/** OS/2 fsType: Restricted-License embedding (no embedding permitted). Bits 0-3 are mutually exclusive. */
+const FS_TYPE_RESTRICTED = 0x0002;
+/** OS/2 fsSelection: ITALIC bit. */
+const FS_SELECTION_ITALIC = 0x0001;
+/** Word's Bold is usWeightClass 700; treat >= 600 (SemiBold and up) as the bold face for our 400/700 axis. */
+const BOLD_WEIGHT_THRESHOLD = 600;
+
+/** The SFNT table directory starts after the 12-byte offset table; each record is 16 bytes. */
+const SFNT_TABLE_DIR_OFFSET = 12;
+const SFNT_TABLE_RECORD_SIZE = 16;
+/** OS/2 field offsets within the table: usWeightClass @4, fsType @8, fsSelection @62 (version 0+). */
+const OS2_USWEIGHTCLASS = 4;
+const OS2_FSTYPE = 8;
+const OS2_FSSELECTION = 62;
+/** Bytes we must be able to read past the OS/2 table start (through fsSelection @62-63). */
+const OS2_MIN_LENGTH = OS2_FSSELECTION + 2;
+
+/**
+ * Parse a font's OS/2 embedding policy + face from its raw bytes (a deobfuscated DOCX-embedded TTF/OTF).
+ *
+ * Returns `null` when the bytes are not a parseable SFNT or have no readable OS/2 table - callers MUST
+ * treat a null result conservatively (do NOT register; fall through to the bundled substitute), since
+ * we cannot prove the font is licensed for embedding.
+ */
+export function parseEmbeddingPolicy(bytes: ArrayBuffer | ArrayBufferView): EmbeddingPolicy | null {
+  // Honor a view's byteOffset/byteLength: a Uint8Array.subarray() or a Node Buffer is a window into a
+  // larger (often pooled) ArrayBuffer, so `new DataView(bytes.buffer)` would read the wrong bytes.
+  const view =
+    bytes instanceof ArrayBuffer ? new DataView(bytes) : new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.byteLength < SFNT_TABLE_DIR_OFFSET) return null;
+
+  const numTables = view.getUint16(4);
+  let os2Offset = -1;
+  for (let i = 0; i < numTables; i += 1) {
+    const record = SFNT_TABLE_DIR_OFFSET + i * SFNT_TABLE_RECORD_SIZE;
+    if (record + SFNT_TABLE_RECORD_SIZE > view.byteLength) return null;
+    // Tag is 4 bytes; the OS/2 table tag is the literal "OS/2" (with the slash).
+    const tag = String.fromCharCode(
+      view.getUint8(record),
+      view.getUint8(record + 1),
+      view.getUint8(record + 2),
+      view.getUint8(record + 3),
+    );
+    if (tag === 'OS/2') {
+      os2Offset = view.getUint32(record + 8);
+      break;
+    }
+  }
+  if (os2Offset < 0 || os2Offset + OS2_MIN_LENGTH > view.byteLength) return null;
+
+  const usWeightClass = view.getUint16(os2Offset + OS2_USWEIGHTCLASS);
+  const fsType = view.getUint16(os2Offset + OS2_FSTYPE);
+  const fsSelection = view.getUint16(os2Offset + OS2_FSSELECTION);
+
+  const weight: '400' | '700' = usWeightClass >= BOLD_WEIGHT_THRESHOLD ? '700' : '400';
+  const style: 'normal' | 'italic' = (fsSelection & FS_SELECTION_ITALIC) !== 0 ? 'italic' : 'normal';
+  return {
+    fsType,
+    face: { weight, style },
+    embeddable: (fsType & FS_TYPE_RESTRICTED) === 0,
+  };
+}

From 054fbcc15f418a44c984b1118776b0c61b0b8821 Mon Sep 17 00:00:00 2001
From: Caio Pizzol <caio@superdoc.dev>
Date: Thu, 4 Jun 2026 22:11:54 -0300
Subject: [PATCH 2/8] feat(fonts): extract embedded DOCX fonts as structured
 deobfuscated faces

Adds SuperConverter.getEmbeddedFontFaces(), the architecturally correct replacement for the legacy @font-face CSS injection: it extracts + deobfuscates the embedded fonts and classifies each via the OS/2 parser (weight/style + fsType licensing), returning structured faces with the deobfuscated bytes and the fontTable relationship id. The converter no longer needs to mint object URLs or inject <style>; the document font controller will register these as first-class registry faces (skipping non-embeddable or unreadable ones) so they flow through the registered_face provider ladder. The legacy getFontFaceImportString stays until the registry path renders embedded fonts.
---
 .../v1/core/super-converter/SuperConverter.js | 77 +++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.js b/packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.js
index cb8ee0b0f2..384f186ef0 100644
--- a/packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.js
+++ b/packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.js
@@ -12,6 +12,7 @@ import { normalizeDuplicateBlockIdentitiesInContent } from './v2/importer/normal
 import { preProcessPageFieldsOnly } from './field-references/preProcessPageFieldsOnly.js';
 import { carbonCopy } from '../utilities/carbonCopy.js';
 import { deobfuscateFont, getArrayBufferFromUrl, computeCrc32Hex } from './helpers.js';
+import { parseEmbeddingPolicy } from '@superdoc/font-system';
 import { baseNumbering } from './v2/exporter/helpers/base-list.definitions.js';
 import { DEFAULT_CUSTOM_XML, DEFAULT_DOCX_DEFS } from './exporter-docx-defs.js';
 import {
@@ -1046,6 +1047,82 @@ class SuperConverter {
     };
   }
 
+  /**
+   * Extract the document's embedded fonts as structured, deobfuscated faces for first-class registry
+   * registration (the architecturally correct replacement for the legacy `@font-face` CSS injection in
+   * {@link getFontFaceImportString}). The converter only extracts + deobfuscates + classifies; it does
+   * NOT create object URLs, inject `<style>`, or decide what to register. Each face carries the
+   * deobfuscated bytes, its OS/2-derived weight/style + raw `fsType` licensing, and the `fontTable`
+   * relationship id. The document font controller decides which to register, skipping faces that are
+   * not embeddable (Restricted-License) or whose OS/2 table was unreadable (conservative: no license
+   * proof -> fall through to the bundled substitute).
+   *
+   * @returns {Array<{ family: string, source: Uint8Array, weight: '400'|'700', style: 'normal'|'italic', fsType: number|null, embeddable: boolean, relationshipId: string }>}
+   */
+  getEmbeddedFontFaces() {
+    const fontTable = this.convertedXml['word/fontTable.xml'];
+    if (!fontTable || !Object.keys(this.fonts).length) return [];
+
+    const wFonts = fontTable.elements?.find((el) => el.name === 'w:fonts');
+    const embeddedEntries =
+      wFonts?.elements?.filter((el) =>
+        el.elements?.some((nested) => nested?.attributes?.['r:id'] && nested?.attributes?.['w:fontKey']),
+      ) ?? [];
+    const embedElements = embeddedEntries.flatMap((entry) =>
+      (entry.elements ?? [])
+        .filter((el) => el.name?.startsWith('w:embed'))
+        .map((el) => ({ embed: el, family: entry.attributes?.['w:name'] })),
+    );
+
+    const rels = this.convertedXml['word/_rels/fontTable.xml.rels'];
+    const relElements = rels?.elements?.find((el) => el.name === 'Relationships')?.elements ?? [];
+
+    // Weight/style fallback from the w:embed* element name (w:embedRegular/Bold/Italic/BoldItalic),
+    // used only when the OS/2 table is unreadable.
+    const faceFromEmbedName = (name = '') => ({
+      weight: /bold/i.test(name) ? '700' : '400',
+      style: /italic/i.test(name) ? 'italic' : 'normal',
+    });
+
+    const faces = [];
+    for (const { embed, family } of embedElements) {
+      const relationshipId = embed.attributes?.['r:id'];
+      const fontKey = embed.attributes?.['w:fontKey'];
+      // Skip a malformed embed rather than aborting the whole extraction (one bad font must not drop
+      // every other embedded face).
+      if (!family || !relationshipId || !fontKey) continue;
+      const filePath = relElements.find((el) => el.attributes?.Id === relationshipId)?.attributes?.Target;
+      if (!filePath) continue;
+      const fontUint8Array = this.fonts[`word/${filePath}`];
+      if (!fontUint8Array?.buffer) continue;
+      // Slice the EXACT view bytes into a fresh buffer. fontUint8Array may be a view into a larger
+      // (pooled) buffer, and deobfuscateFont XORs its input IN PLACE and returns the whole buffer -
+      // so passing `.buffer` would deobfuscate the wrong bytes and corrupt the shared `this.fonts`
+      // data. The fresh copy is also the independent buffer the registry will own.
+      const sourceBytes = fontUint8Array.buffer.slice(
+        fontUint8Array.byteOffset,
+        fontUint8Array.byteOffset + fontUint8Array.byteLength,
+      );
+      const ttf = deobfuscateFont(sourceBytes, fontKey);
+      if (!ttf) continue;
+
+      const policy = parseEmbeddingPolicy(ttf);
+      const fallback = faceFromEmbedName(embed.name);
+      faces.push({
+        family,
+        source: ttf,
+        weight: policy?.face.weight ?? fallback.weight,
+        style: policy?.face.style ?? fallback.style,
+        fsType: policy?.fsType ?? null,
+        // Conservative: an unreadable OS/2 table (null policy) is NOT embeddable - we cannot prove the
+        // license permits embedding, so the controller skips it and the bundled substitute renders.
+        embeddable: policy ? policy.embeddable : false,
+        relationshipId,
+      });
+    }
+    return faces;
+  }
+
   getDocumentInternalId() {
     const settingsLocation = 'word/settings.xml';
     if (!this.convertedXml[settingsLocation]) {

From 771ceaa5b51c5daa5faa6eae6be8f1446a5833ae Mon Sep 17 00:00:00 2001
From: Caio Pizzol <caio@superdoc.dev>
Date: Thu, 4 Jun 2026 22:18:26 -0300
Subject: [PATCH 3/8] feat(fonts): document-owned registerOwnedFace with handle
 release

Adds FontRegistry.registerOwnedFace(descriptor) -> disposer for embedded DOCX fonts. The registry is shared per FontFaceSet across editors, so a key-based delete would let one document's swap drop another document's (or a fonts.add) face for the same family|weight|style. Instead each call creates a distinct managed face and returns a disposer that removes EXACTLY that face; a face key collapses (hasFace flips false) only when its last owner releases. Tracks all faces per key in #facesByKey (replacing the one-per-key #managedFaces); register() and registerOwnedFace() share #addManagedFace/#removeManagedFace. Binary embedded faces are never de-duped (two documents can embed the same family with different subset bytes). Returns null with no DOM FontFace constructor so the resolver falls through to the bundled substitute. OwnedFaceDescriptor exported.
---
 shared/font-system/src/index.ts         |   2 +-
 shared/font-system/src/registry.test.ts | 100 ++++++++++++++++++++++
 shared/font-system/src/registry.ts      | 105 +++++++++++++++++++++++-
 3 files changed, 204 insertions(+), 3 deletions(-)

diff --git a/shared/font-system/src/index.ts b/shared/font-system/src/index.ts
index 0720addf4d..1219279aa0 100644
--- a/shared/font-system/src/index.ts
+++ b/shared/font-system/src/index.ts
@@ -59,7 +59,7 @@ export { buildFontReport, buildFaceReport } from './report';
 export type { EmbeddingPolicy } from './os2';
 export { parseEmbeddingPolicy } from './os2';
 
-export type { FontSetLike, FontFaceLike, FontFaceCtor, FontRegistryOptions } from './registry';
+export type { FontSetLike, FontFaceLike, FontFaceCtor, FontRegistryOptions, OwnedFaceDescriptor } from './registry';
 export {
   FontRegistry,
   getFontRegistryFor,
diff --git a/shared/font-system/src/registry.test.ts b/shared/font-system/src/registry.test.ts
index dc6e08693e..180f14d118 100644
--- a/shared/font-system/src/registry.test.ts
+++ b/shared/font-system/src/registry.test.ts
@@ -31,12 +31,19 @@ class FakeFontFace implements FontFaceLike {
 /** Controllable FontFaceSet stand-in: per-family behavior + manual availability. */
 class FakeFontSet implements FontSetLike {
   readonly added: FontFaceLike[] = [];
+  readonly removed: FontFaceLike[] = [];
   readonly behaviors = new Map<string, Behavior>();
   readonly available = new Set<string>();
 
   add(face: FontFaceLike): void {
     this.added.push(face);
   }
+  delete(face: FontFaceLike): boolean {
+    this.removed.push(face);
+    const i = this.added.indexOf(face);
+    if (i >= 0) this.added.splice(i, 1);
+    return i >= 0;
+  }
   load(font: string): Promise<FontFaceLike[]> {
     const family = parseFamily(font);
     switch (this.behaviors.get(family) ?? 'load-empty') {
@@ -307,3 +314,96 @@ describe('FontRegistry face-aware APIs', () => {
     expect(registry.getStatus('Broken')).toBe('failed');
   });
 });
+
+describe('FontRegistry.registerOwnedFace (document-scoped embedded fonts)', () => {
+  it('registers a binary face that hasFace sees, and its disposer removes exactly that face', () => {
+    const fontSet = new FakeFontSet();
+    const { registry } = makeRegistry(fontSet);
+    // Two embedded faces of one family (binary) + an unrelated bundled/customer (URL) face.
+    const releaseReg = registry.registerOwnedFace({
+      family: 'EmbeddedCalibri',
+      source: new ArrayBuffer(8),
+      weight: '400',
+      style: 'normal',
+    });
+    registry.registerOwnedFace({
+      family: 'EmbeddedCalibri',
+      source: new ArrayBuffer(8),
+      weight: '700',
+      style: 'normal',
+    });
+    registry.register({ family: 'Carlito', source: 'url(carlito.woff2)' });
+
+    expect(registry.hasFace('EmbeddedCalibri', '400', 'normal')).toBe(true); // registered_face oracle sees it
+    expect(releaseReg).toBeTypeOf('function');
+
+    expect(releaseReg?.()).toBe(true);
+    expect(registry.hasFace('EmbeddedCalibri', '400', 'normal')).toBe(false); // released
+    expect(registry.hasFace('EmbeddedCalibri', '700', 'normal')).toBe(true); // sibling face untouched
+    expect(registry.hasFace('Carlito', '400', 'normal')).toBe(true); // other family untouched
+    expect(fontSet.removed).toHaveLength(1); // exactly one face deleted from the set
+
+    // A second release is a no-op (idempotent disposer): no further removal.
+    expect(releaseReg?.()).toBe(false);
+    expect(fontSet.removed).toHaveLength(1);
+  });
+
+  it('clears family-level state only when the last owned face is released', () => {
+    const fontSet = new FakeFontSet();
+    const { registry } = makeRegistry(fontSet);
+    const r400 = registry.registerOwnedFace({
+      family: 'Doc',
+      source: new ArrayBuffer(8),
+      weight: '400',
+      style: 'normal',
+    });
+    const r700 = registry.registerOwnedFace({
+      family: 'Doc',
+      source: new ArrayBuffer(8),
+      weight: '700',
+      style: 'normal',
+    });
+
+    r400?.();
+    expect(registry.isManaged('Doc')).toBe(true); // 700 still there
+    r700?.();
+    expect(registry.isManaged('Doc')).toBe(false); // family fully released
+    expect(registry.hasFace('Doc', '700', 'normal')).toBe(false);
+  });
+
+  it('keeps a shared key alive while another owner (a second document) still holds it', () => {
+    // The registry is shared per FontFaceSet, so two documents can each register the SAME
+    // family|weight|style. Releasing one document's face must NOT drop the other's.
+    const fontSet = new FakeFontSet();
+    const { registry } = makeRegistry(fontSet);
+    const releaseDocA = registry.registerOwnedFace({
+      family: 'Calibri',
+      source: new ArrayBuffer(8),
+      weight: '400',
+      style: 'normal',
+    });
+    const releaseDocB = registry.registerOwnedFace({
+      family: 'Calibri',
+      source: new ArrayBuffer(16),
+      weight: '400',
+      style: 'normal',
+    });
+    expect(fontSet.added).toHaveLength(2); // two distinct faces (binary is never de-duped)
+
+    expect(releaseDocA?.()).toBe(true);
+    expect(registry.hasFace('Calibri', '400', 'normal')).toBe(true); // doc B's face still provides it
+    expect(fontSet.removed).toHaveLength(1);
+
+    expect(releaseDocB?.()).toBe(true);
+    expect(registry.hasFace('Calibri', '400', 'normal')).toBe(false); // last owner gone
+    expect(fontSet.removed).toHaveLength(2);
+  });
+
+  it('returns null with no FontFace constructor / font set (embedded bytes cannot render)', () => {
+    const registry = new FontRegistry({});
+    expect(
+      registry.registerOwnedFace({ family: 'X', source: new ArrayBuffer(8), weight: '400', style: 'normal' }),
+    ).toBeNull();
+    expect(registry.hasFace('X', '400', 'normal')).toBe(false); // resolver falls through to the bundled substitute
+  });
+});
diff --git a/shared/font-system/src/registry.ts b/shared/font-system/src/registry.ts
index bccf5e93d1..5d90a79ac2 100644
--- a/shared/font-system/src/registry.ts
+++ b/shared/font-system/src/registry.ts
@@ -26,6 +26,8 @@ const DEFAULT_PROBE_SIZE = '16px';
  */
 export interface FontSetLike {
   add(face: FontFaceLike): void;
+  /** Remove a managed face (DOM `FontFaceSet.delete`). Optional: some sets (domless/tests) omit it. */
+  delete?(face: FontFaceLike): boolean;
   load(font: string, text?: string): Promise<FontFaceLike[]>;
   check(font: string, text?: string): boolean;
 }
@@ -44,6 +46,19 @@ export type FontFaceCtor = new (
   descriptors?: FontFaceDescriptors,
 ) => FontFaceLike;
 
+/**
+ * A document-owned font face registered from raw bytes (a deobfuscated DOCX-embedded font), the input
+ * to {@link FontRegistry.registerOwnedFace}. Carries the bytes plus the OS/2-derived face axis so the
+ * face registers under the document's family name with the correct weight/style and flows through the
+ * resolver's `registered_face` rung. `weight`/`style` are already canonical (no normalization needed).
+ */
+export interface OwnedFaceDescriptor {
+  family: string;
+  source: ArrayBuffer | ArrayBufferView;
+  weight: '400' | '700';
+  style: 'normal' | 'italic';
+}
+
 export interface FontRegistryOptions {
   /** The font set to drive. Defaults to the ambient `document.fonts`. */
   fontSet?: FontSetLike | null;
@@ -140,8 +155,17 @@ export class FontRegistry {
   readonly #scheduleTimeout: (cb: () => void, ms: number) => unknown;
   readonly #cancelTimeout: (handle: unknown) => void;
 
-  /** Faces the registry created, keyed by family. */
+  /** Faces the registry created, keyed by family. Probed only via `isManaged` (the VALUE is never
+   *  read), so a stale entry between multi-owner releases is harmless. */
   readonly #managed = new Map<string, FontFaceLike>();
+  /**
+   * Every managed FontFace object, grouped by face key (family|weight|style). A SET because the
+   * registry is shared per FontFaceSet across editors, so two documents can each register their own
+   * embedded face for the same key; `hasFace` stays true while >=1 remains. A document-owned face is
+   * released by its exact handle ({@link registerOwnedFace}), and the key collapses only when its
+   * last face is gone - so one document's swap never drops another's (or a `fonts.add`) face.
+   */
+  readonly #facesByKey = new Map<string, Set<FontFaceLike>>();
   /** Last known load status per family. */
   readonly #status = new Map<string, FontLoadStatus>();
   /** Registered `url(...)` source(s) per family, to name the failing URL on a load error. */
@@ -209,7 +233,7 @@ export class FontRegistry {
     if (this.#FontFaceCtor && this.#fontSet) {
       const face = new this.#FontFaceCtor(family, source, descriptors);
       this.#fontSet.add(face);
-      this.#managed.set(family, face);
+      this.#addManagedFace(family, key, face);
     }
     if (typeof source === 'string') {
       const list = this.#sources.get(family) ?? [];
@@ -237,6 +261,83 @@ export class FontRegistry {
     return this.#managed.has(family);
   }
 
+  /**
+   * Register a DOCUMENT-OWNED face from raw bytes (a deobfuscated DOCX-embedded font) and return a
+   * disposer that releases EXACTLY this face. Unlike {@link register} - the shared registrar for
+   * bundled and `fonts.add` faces, idempotent by URL source - every call here creates a distinct
+   * managed face, because the registry is shared per FontFaceSet across editors and two documents can
+   * embed the same family|weight|style with different (subset) bytes. Calling the returned disposer
+   * (on a document swap or editor teardown) removes only this face; the key's `hasFace` stays true
+   * while any other owner's face remains, so one document's cleanup never drops another document's or
+   * a customer's face. The face participates in `hasFace`/await like any managed face while it lives.
+   *
+   * Returns null where there is no DOM `FontFace` constructor / font set: embedded bytes cannot render
+   * without one, so the resolver correctly falls through to the bundled substitute. The disposer is
+   * idempotent (a second call returns false).
+   */
+  registerOwnedFace(descriptor: OwnedFaceDescriptor): (() => boolean) | null {
+    const { family, source, weight, style } = descriptor;
+    if (!this.#FontFaceCtor || !this.#fontSet) return null;
+    const key = faceKeyOf(family, weight, style);
+    const face = new this.#FontFaceCtor(family, source, { weight, style });
+    this.#fontSet.add(face);
+    this.#addManagedFace(family, key, face);
+    // Seed family- and face-level status so the gate can await this exact face and `hasFace` reports
+    // it (mirrors the bookkeeping `register` does for URL faces; binary faces have no `#faceSources`).
+    if (!this.#status.has(family)) this.#status.set(family, 'unloaded');
+    this.#trackFace(family, key);
+    if (!this.#faceStatus.has(key)) this.#faceStatus.set(key, 'unloaded');
+    let released = false;
+    return () => {
+      if (released) return false;
+      released = true;
+      return this.#removeManagedFace(family, key, face);
+    };
+  }
+
+  /** Track a created FontFace under its family (`#managed`, last-wins) and its face key
+   *  (`#facesByKey`, all owners). Shared by {@link register} and {@link registerOwnedFace}. */
+  #addManagedFace(family: string, key: string, face: FontFaceLike): void {
+    this.#managed.set(family, face);
+    let set = this.#facesByKey.get(key);
+    if (!set) {
+      set = new Set<FontFaceLike>();
+      this.#facesByKey.set(key, set);
+    }
+    set.add(face);
+  }
+
+  /**
+   * Remove one specific managed face. Drops it from the FontFaceSet and its face-key group; when that
+   * was the LAST face for the key, clears the key's per-face state and removes the key from its
+   * family - and when the family then has no keys left, clears its family-level state too. Returns
+   * false if the face was not tracked under that key (already released / never ours), leaving
+   * everything untouched.
+   */
+  #removeManagedFace(family: string, key: string, face: FontFaceLike): boolean {
+    const set = this.#facesByKey.get(key);
+    if (!set || !set.delete(face)) return false;
+    if (typeof this.#fontSet?.delete === 'function') this.#fontSet.delete(face);
+    if (set.size > 0) return true; // another owner still provides this face; keep key/family state
+    this.#facesByKey.delete(key);
+    this.#faceStatus.delete(key);
+    this.#faceSources.delete(key);
+    const fam = normalizeFamilyKey(family);
+    const keys = this.#facesByFamily.get(fam);
+    if (keys) {
+      keys.delete(key);
+      if (keys.size === 0) {
+        // The family has no managed faces left: drop its family-level state and the `#managed` entry
+        // so `isManaged`/`getStatus` no longer report a now-removed family.
+        this.#facesByFamily.delete(fam);
+        this.#managed.delete(family);
+        this.#status.delete(family);
+        this.#sources.delete(family);
+      }
+    }
+    return true;
+  }
+
   /**
    * Last known status for a family, rolled up from its faces (and any legacy family-path
    * load). Used by declared-font diagnostics (`buildFontReport`).

From 620cbfca577090ab9edd614472f0e1a9eaf63b86 Mon Sep 17 00:00:00 2001
From: Caio Pizzol <caio@superdoc.dev>
Date: Thu, 4 Jun 2026 22:34:44 -0300
Subject: [PATCH 4/8] feat(fonts): register embedded DOCX fonts on the document
 controller

DocumentFontController.applyEmbeddedFaces(faces) registers each embeddable embedded face (from SuperConverter.getEmbeddedFontFaces) as a document-owned registry face before the first measure, so the resolver's registered_face rung renders the document's real font instead of the bundled substitute - no resolver special-casing. Non-embeddable faces (Restricted-License or unreadable OS/2) are skipped and the substitute renders them. Holds a release handle per face and frees them on reset() (document swap) and dispose() (teardown), so a document's embedded fonts never leak into the next or into another editor sharing the FontFaceSet; re-applying replaces the prior set. Like other config-time registrations it invalidates the shared measure caches without a reflow or event. Also corrects the getEmbeddedFontFaces @returns (source is an ArrayBuffer, not a Uint8Array).
---
 .../fonts/DocumentFontController.test.ts      | 150 +++++++++++++++++-
 .../fonts/DocumentFontController.ts           |  78 ++++++++-
 .../v1/core/super-converter/SuperConverter.js |   2 +-
 3 files changed, 225 insertions(+), 5 deletions(-)

diff --git a/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.test.ts b/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.test.ts
index 26888ea524..0361589389 100644
--- a/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.test.ts
+++ b/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
 import { createFontResolver, type FontFaceRequest, type RegisterFaceResult } from '@superdoc/font-system';
 import type { FontRegistry } from '@superdoc/font-system';
-import { DocumentFontController } from './DocumentFontController';
+import { DocumentFontController, type EmbeddedFontFace } from './DocumentFontController';
 import type { FontReadinessGate } from './FontReadinessGate';
 
 class FakeRegistry {
@@ -25,6 +25,33 @@ class FakeRegistry {
     return { family: input.family, status: 'unloaded', changed: true };
   }
 
+  readonly ownedRegistered: Array<{ family: string; weight: string; style: string }> = [];
+  readonly ownedReleased: Array<{ family: string; weight: string; style: string }> = [];
+
+  /** Model the document-owned binary face path: each call registers a distinct face and returns a
+   *  disposer that releases exactly it. Reflected in `hasFace` so the resolver's `registered_face`
+   *  rung sees it. (Refcounting a shared key is the real registry's job, covered in registry.test.ts;
+   *  these controller tests use distinct families.) */
+  registerOwnedFace(input: {
+    family: string;
+    source: ArrayBuffer | ArrayBufferView;
+    weight: '400' | '700';
+    style: 'normal' | 'italic';
+  }): (() => boolean) | null {
+    const record = { family: input.family, weight: input.weight, style: input.style };
+    this.ownedRegistered.push(record);
+    const key = `${input.family.toLowerCase()}|${input.weight}|${input.style}`;
+    this.#sources.set(key, 'owned');
+    let released = false;
+    return () => {
+      if (released) return false;
+      released = true;
+      this.ownedReleased.push(record);
+      this.#sources.delete(key);
+      return true;
+    };
+  }
+
   async awaitFaceRequests(requests: Iterable<FontFaceRequest>): Promise<[]> {
     this.awaited.push([...requests]);
     return [];
@@ -39,8 +66,9 @@ class FakeRegistry {
   }
 }
 
-function makeController() {
-  const registry = new FakeRegistry();
+function makeController(sharedRegistry?: FakeRegistry) {
+  // Pass a shared registry to model two editors on one FontFaceSet (the real per-document sharing).
+  const registry = sharedRegistry ?? new FakeRegistry();
   const notifyDocumentFontConfigChanged = vi.fn();
   const invalidateCachesForConfigRegistration = vi.fn();
   const onDocumentFontConfigApplied = vi.fn();
@@ -303,4 +331,120 @@ describe('DocumentFontController', () => {
     expect(resolver.signature).toBe('');
     expect(notifyDocumentFontConfigChanged).toHaveBeenCalledTimes(2);
   });
+
+  describe('applyEmbeddedFaces (embedded DOCX fonts)', () => {
+    const embed = (over: Partial<EmbeddedFontFace> & { family: string }): EmbeddedFontFace => ({
+      source: new ArrayBuffer(8),
+      weight: '400',
+      style: 'normal',
+      fsType: 0,
+      embeddable: true,
+      relationshipId: 'rId1',
+      ...over,
+    });
+
+    it('registers embeddable faces, skips restricted, and invalidates caches without a reflow/event', () => {
+      const {
+        controller,
+        registry,
+        invalidateCachesForConfigRegistration,
+        notifyDocumentFontConfigChanged,
+        onDocumentFontConfigApplied,
+      } = makeController();
+
+      controller.applyEmbeddedFaces([
+        embed({ family: 'Calibri', weight: '400' }),
+        embed({ family: 'Calibri', weight: '700', relationshipId: 'rId2' }),
+        // Restricted-License (fsType bit 1) / unreadable OS/2: not embeddable -> skipped.
+        embed({ family: 'SecretFont', fsType: 0x0002, embeddable: false, relationshipId: 'rId3' }),
+      ]);
+
+      expect(registry.ownedRegistered).toEqual([
+        { family: 'Calibri', weight: '400', style: 'normal' },
+        { family: 'Calibri', weight: '700', style: 'normal' },
+      ]);
+      expect(registry.hasFace('SecretFont', '400', 'normal')).toBe(false); // restricted never registered
+      // Config-time registration: clears the shared measure caches, but no reflow/event (first measure
+      // has not happened yet).
+      expect(invalidateCachesForConfigRegistration).toHaveBeenCalledTimes(1);
+      expect(onDocumentFontConfigApplied).not.toHaveBeenCalled();
+      expect(notifyDocumentFontConfigChanged).not.toHaveBeenCalled();
+    });
+
+    it('makes the resolver render the embedded real family via registered_face (not the bundled clone)', () => {
+      const { controller, resolver, registry } = makeController();
+      const hasFace = (f: string, w: '400' | '700', s: 'normal' | 'italic') => registry.hasFace(f, w, s);
+      const regular = { weight: '400', style: 'normal' } as const;
+
+      // Before: Calibri falls back to the bundled substitute (Carlito).
+      expect(resolver.resolveFace('Calibri', regular, hasFace).physicalFamily).toBe('Carlito');
+
+      controller.applyEmbeddedFaces([embed({ family: 'Calibri' })]);
+
+      const resolved = resolver.resolveFace('Calibri', regular, hasFace);
+      expect(resolved.physicalFamily).toBe('Calibri'); // the document's real embedded font
+      expect(resolved.reason).toBe('registered_face');
+    });
+
+    it('releases every embedded face on reset (document swap)', () => {
+      const { controller, registry } = makeController();
+      controller.applyEmbeddedFaces([
+        embed({ family: 'Calibri', weight: '400' }),
+        embed({ family: 'Calibri', weight: '700' }),
+      ]);
+      expect(registry.hasFace('Calibri', '400', 'normal')).toBe(true);
+
+      controller.reset();
+
+      expect(registry.ownedReleased).toEqual([
+        { family: 'Calibri', weight: '400', style: 'normal' },
+        { family: 'Calibri', weight: '700', style: 'normal' },
+      ]);
+      expect(registry.hasFace('Calibri', '400', 'normal')).toBe(false);
+    });
+
+    it('releases every embedded face on dispose (teardown)', () => {
+      const { controller, registry } = makeController();
+      controller.applyEmbeddedFaces([embed({ family: 'Calibri' })]);
+
+      controller.dispose();
+
+      expect(registry.ownedReleased).toEqual([{ family: 'Calibri', weight: '400', style: 'normal' }]);
+      expect(registry.hasFace('Calibri', '400', 'normal')).toBe(false);
+    });
+
+    it('replaces the prior embedded set on re-apply (releases old, registers new)', () => {
+      const { controller, registry } = makeController();
+      controller.applyEmbeddedFaces([embed({ family: 'Calibri' })]);
+      controller.applyEmbeddedFaces([embed({ family: 'Cambria' })]);
+
+      expect(registry.ownedReleased).toEqual([{ family: 'Calibri', weight: '400', style: 'normal' }]);
+      expect(registry.hasFace('Calibri', '400', 'normal')).toBe(false);
+      expect(registry.hasFace('Cambria', '400', 'normal')).toBe(true);
+    });
+
+    it('does nothing (no invalidate) when there are no embeddable faces', () => {
+      const { controller, registry, invalidateCachesForConfigRegistration } = makeController();
+      controller.applyEmbeddedFaces([embed({ family: 'SecretFont', embeddable: false })]);
+
+      expect(registry.ownedRegistered).toHaveLength(0);
+      expect(invalidateCachesForConfigRegistration).not.toHaveBeenCalled();
+    });
+
+    it("with a shared registry, one document's swap releases only its own embedded faces", () => {
+      // Two editors on ONE FontFaceSet (shared registry). This is exactly why release is handle-based:
+      // doc A's reset must not drop doc B's face.
+      const registry = new FakeRegistry();
+      const docA = makeController(registry);
+      const docB = makeController(registry);
+      docA.controller.applyEmbeddedFaces([embed({ family: 'Calibri' })]);
+      docB.controller.applyEmbeddedFaces([embed({ family: 'Cambria' })]);
+
+      docA.controller.reset();
+
+      expect(registry.ownedReleased).toEqual([{ family: 'Calibri', weight: '400', style: 'normal' }]);
+      expect(registry.hasFace('Calibri', '400', 'normal')).toBe(false); // doc A released
+      expect(registry.hasFace('Cambria', '400', 'normal')).toBe(true); // doc B intact
+    });
+  });
 });
diff --git a/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.ts b/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.ts
index 67668d5dcb..071c0bf627 100644
--- a/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.ts
+++ b/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.ts
@@ -24,6 +24,25 @@ export interface DocumentFontControllerDeps {
   scheduleMicrotask?: (callback: () => void) => void;
 }
 
+/**
+ * A document's embedded font face, as extracted by the converter (`SuperConverter.getEmbeddedFontFaces`):
+ * the deobfuscated bytes plus the OS/2-derived face axis and raw `fsType` licensing. The controller
+ * registers each {@link embeddable} face under its own family name so the resolver's `registered_face`
+ * rung renders the document's real font instead of the bundled substitute; it skips faces that are not
+ * embeddable (Restricted-License, or an unreadable OS/2 table - no proof the license permits embedding).
+ */
+export interface EmbeddedFontFace {
+  family: string;
+  /** Deobfuscated SFNT bytes (an ArrayBuffer from `deobfuscateFont`). */
+  source: ArrayBuffer | ArrayBufferView;
+  weight: '400' | '700';
+  style: 'normal' | 'italic';
+  /** Raw OS/2 `fsType`, or null when the table was unreadable. Preserved for diagnostics/policy. */
+  fsType: number | null;
+  embeddable: boolean;
+  relationshipId: string;
+}
+
 /**
  * Normalize a public font source (a plain URL like '/fonts/Gelasio.woff2') to the CSS `url(...)`
  * source the FontFace constructor expects. An already-`url(...)` value is left unchanged.
@@ -58,6 +77,13 @@ export class DocumentFontController {
    * the caches would otherwise keep stale fallback widths for a now-loadable family.
    */
   #runtimeAvailabilityChanged = false;
+  /**
+   * Release handles for THIS document's embedded faces, in registration order. The registry is shared
+   * per FontFaceSet across editors, so cleanup must release exactly the faces this document registered
+   * (each disposer removes one specific face); a document swap / teardown calls them all. Emptied on
+   * release; replaced wholesale on each {@link applyEmbeddedFaces}.
+   */
+  readonly #embeddedDisposers: Array<() => void> = [];
 
   constructor(deps: DocumentFontControllerDeps) {
     this.#resolver = deps.resolver;
@@ -92,12 +118,14 @@ export class DocumentFontController {
    */
   reset(): void {
     this.#cancelPendingRuntimeReflow();
+    this.#releaseEmbeddedFaces();
     this.#resolver.reset();
   }
 
-  /** Cancel pending runtime font work on editor teardown. */
+  /** Cancel pending runtime font work and release this document's embedded faces on editor teardown. */
   dispose(): void {
     this.#cancelPendingRuntimeReflow();
+    this.#releaseEmbeddedFaces();
   }
 
   /**
@@ -118,6 +146,47 @@ export class DocumentFontController {
     if (registered) this.#getGate()?.invalidateCachesForConfigRegistration();
   }
 
+  /**
+   * Register the document's embedded fonts (from `SuperConverter.getEmbeddedFontFaces`) as first-class
+   * registry faces, BEFORE the first layout measure. Each {@link EmbeddedFontFace.embeddable} face is
+   * registered under its own family name, so the resolver's `registered_face` rung renders the
+   * document's real font (e.g. its embedded Calibri) instead of the bundled substitute (Carlito) - with
+   * no resolver special-casing. Non-embeddable faces (Restricted-License, or an unreadable OS/2 table)
+   * are skipped: the bundled substitute renders them.
+   *
+   * Document-scoped: the controller holds a release handle per registered face and frees them on
+   * {@link reset} (document swap) / {@link dispose} (teardown), so this document's fonts never leak into
+   * the next or into another editor sharing the FontFaceSet. Re-applying replaces the prior embedded
+   * set. Like a config-time registration it invalidates the shared measure caches (a registration does
+   * not move the resolver signature that would otherwise bust them) but does NOT reflow or emit - the
+   * first/next render measures fresh against the now-registered face.
+   */
+  applyEmbeddedFaces(faces: EmbeddedFontFace[] | null | undefined): void {
+    // Replace any prior embedded set (idempotent re-apply): release before re-registering so a repeated
+    // call cannot double-register or strand handles.
+    this.#releaseEmbeddedFaces();
+    if (!faces?.length) return;
+    // No registry (no DOM / headless): the document still renders with bundled substitutes. Don't throw
+    // here - unlike the user-invoked `fonts.add`, this runs automatically on every document load.
+    const registry = this.#getGate()?.resolveRegistry();
+    if (!registry) return;
+    let registered = false;
+    for (const face of faces) {
+      if (!face?.embeddable) continue;
+      const release = registry.registerOwnedFace({
+        family: face.family,
+        source: face.source,
+        weight: face.weight,
+        style: face.style,
+      });
+      if (release) {
+        this.#embeddedDisposers.push(release);
+        registered = true;
+      }
+    }
+    if (registered) this.#getGate()?.invalidateCachesForConfigRegistration();
+  }
+
   /**
    * Register custom physical font faces (e.g. a customer's Gelasio woff2s) so they become loadable
    * and mappable. Registers only - it does NOT map (call {@link map} for that). Idempotent per
@@ -244,6 +313,13 @@ export class DocumentFontController {
     this.#runtimeReflowQueued = false;
     this.#runtimeReflowToken += 1;
   }
+
+  /** Release every embedded face this document registered (each disposer removes one specific face),
+   *  then clear the list. Safe to call repeatedly; the disposers are idempotent. */
+  #releaseEmbeddedFaces(): void {
+    for (const release of this.#embeddedDisposers) release();
+    this.#embeddedDisposers.length = 0;
+  }
 }
 
 function defaultScheduleMicrotask(callback: () => void): void {
diff --git a/packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.js b/packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.js
index 384f186ef0..b22bb2ba83 100644
--- a/packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.js
+++ b/packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.js
@@ -1057,7 +1057,7 @@ class SuperConverter {
    * not embeddable (Restricted-License) or whose OS/2 table was unreadable (conservative: no license
    * proof -> fall through to the bundled substitute).
    *
-   * @returns {Array<{ family: string, source: Uint8Array, weight: '400'|'700', style: 'normal'|'italic', fsType: number|null, embeddable: boolean, relationshipId: string }>}
+   * @returns {Array<{ family: string, source: ArrayBuffer, weight: '400'|'700', style: 'normal'|'italic', fsType: number|null, embeddable: boolean, relationshipId: string }>}
    */
   getEmbeddedFontFaces() {
     const fontTable = this.convertedXml['word/fontTable.xml'];

From 7998edc10952da0b604f178d2af7a4885f683d17 Mon Sep 17 00:00:00 2001
From: Caio Pizzol <caio@superdoc.dev>
Date: Thu, 4 Jun 2026 22:38:22 -0300
Subject: [PATCH 5/8] feat(fonts): apply embedded document fonts in the
 PresentationEditor lifecycle

PresentationEditor now registers the document's embedded fonts through the controller at config time - on initial load and after a document swap - before the first font plan, so the resolver renders the real embedded font. The swap path already resets the controller (releasing the prior document's faces) before re-applying; teardown disposes it. Reads getEmbeddedFontFaces through a narrow structural cast (not on the converter's typed surface, same pattern as getDocumentFonts).

The legacy <style> object-URL injection still runs in parallel for now; removing it is deferred to a follow-up until CI confirms the registry path renders embedded fonts (no-removal-before-test).
---
 .../presentation-editor/PresentationEditor.ts | 20 ++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts b/packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts
index 6f38dbc4e0..8dec778955 100644
--- a/packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts
+++ b/packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts
@@ -186,7 +186,7 @@ import {
 } from '@superdoc/font-system';
 import { installBundledSubstitutes } from '@superdoc/font-system/bundled';
 import { FontReadinessGate } from './fonts/FontReadinessGate';
-import { DocumentFontController } from './fonts/DocumentFontController';
+import { DocumentFontController, type EmbeddedFontFace } from './fonts/DocumentFontController';
 import { planFontFaces, type FontPlan } from './fonts/font-load-planner';
 import type { FontsChangedPayload } from '../types/EditorEvents';
 import type { FontFamilyConfig } from '../types/EditorConfig';
@@ -1056,6 +1056,7 @@ export class PresentationEditor extends EventEmitter {
         },
       });
       this.#fontController.applyInitialConfig(this.#options.fontAssets);
+      this.#applyEmbeddedDocumentFonts();
       if (typeof this.#options.disableContextMenu === 'boolean') {
         this.setContextMenuDisabled(this.#options.disableContextMenu);
       }
@@ -3078,6 +3079,20 @@ export class PresentationEditor extends EventEmitter {
     await this.#fontController.preload(families);
   }
 
+  /**
+   * Register the current document's embedded fonts (from the converter) as document-owned registry
+   * faces, so the resolver's `registered_face` rung renders the real embedded font instead of the
+   * bundled substitute. Runs at config time - initial load and after a document swap - BEFORE the
+   * first font plan; the controller skips non-embeddable faces and releases these on the next swap
+   * (`reset`) / teardown (`dispose`). `getEmbeddedFontFaces` is not on the converter's typed surface,
+   * so it is read through a narrow structural cast (same pattern as `getDocumentFonts`).
+   */
+  #applyEmbeddedDocumentFonts(): void {
+    const converter = (this.#editor as Editor & { converter?: { getEmbeddedFontFaces?: () => EmbeddedFontFace[] } })
+      .converter;
+    this.#fontController.applyEmbeddedFaces(converter?.getEmbeddedFontFaces?.());
+  }
+
   /**
    * Drop this editor's cached blocks + measures and schedule a full document re-layout. The
    * font-readiness gate calls this (via its requestReflow option) for both a late font load and a
@@ -5248,6 +5263,9 @@ export class PresentationEditor extends EventEmitter {
       // here states the intent and starts the swap from a clean signature.
       this.#layoutFontSignature = '';
       this.#fontController.applyInitialConfig(this.#options.fontAssets);
+      // Register the NEW document's embedded fonts (the swap's `reset()` released the old ones), before
+      // the rerender below runs the first font plan for this document.
+      this.#applyEmbeddedDocumentFonts();
       this.#resetFontReportStateForDocumentChange();
       this.#refreshHeaderFooterStructureThenRerender({ purgeCachedEditors: true });
     };

From e9aac27408445de540d31d26407859b4d7627a7b Mon Sep 17 00:00:00 2001
From: Caio Pizzol <caio@superdoc.dev>
Date: Thu, 4 Jun 2026 22:44:37 -0300
Subject: [PATCH 6/8] test(fonts): unit-test embedded-font extraction from the
 converter

Covers SuperConverter.getEmbeddedFontFaces with a synthetic fontTable.xml + rels and obfuscated SFNT fixtures (XOR round-trip via the same operation deobfuscateFont runs): OS/2-derived weight/style wins over the embed name; Restricted-License fsType is extracted but flagged not embeddable; an unreadable OS/2 table falls back to the embed-name face and not-embeddable; a missing relationship and a non-embedded entry are skipped; the deobfuscated source is a fresh ArrayBuffer that round-trips the SFNT version word; and the pooled converter bytes are not mutated (the slice fix).
---
 .../getEmbeddedFontFaces.test.js              | 173 ++++++++++++++++++
 1 file changed, 173 insertions(+)
 create mode 100644 packages/super-editor/src/editors/v1/core/super-converter/getEmbeddedFontFaces.test.js

diff --git a/packages/super-editor/src/editors/v1/core/super-converter/getEmbeddedFontFaces.test.js b/packages/super-editor/src/editors/v1/core/super-converter/getEmbeddedFontFaces.test.js
new file mode 100644
index 0000000000..8fb366dfb9
--- /dev/null
+++ b/packages/super-editor/src/editors/v1/core/super-converter/getEmbeddedFontFaces.test.js
@@ -0,0 +1,173 @@
+import { describe, it, expect } from 'vitest';
+import { SuperConverter } from './SuperConverter.js';
+
+/**
+ * Build a minimal valid SFNT with a single OS/2 table at a known offset, so the converter's
+ * extraction + OS/2 face classification can be tested without a real font fixture. Mirrors the layout
+ * the OS/2 parser expects: 12-byte offset table + one 16-byte directory record ("OS/2") + the table.
+ */
+function makeSfnt({ usWeightClass, fsType, fsSelection }) {
+  const os2Offset = 28; // 12 (offset table) + 16 (one directory record)
+  const os2Length = 64; // through fsSelection @62-63
+  const buf = new ArrayBuffer(os2Offset + os2Length);
+  const dv = new DataView(buf);
+  dv.setUint32(0, 0x00010000); // sfnt version (TrueType)
+  dv.setUint16(4, 1); // numTables
+  for (let i = 0; i < 4; i += 1) dv.setUint8(12 + i, 'OS/2'.charCodeAt(i));
+  dv.setUint32(16, 0); // checksum
+  dv.setUint32(20, os2Offset); // table offset
+  dv.setUint32(24, os2Length); // table length
+  dv.setUint16(os2Offset + 4, usWeightClass);
+  dv.setUint16(os2Offset + 8, fsType);
+  dv.setUint16(os2Offset + 62, fsSelection);
+  return buf;
+}
+
+const GUID = '{12345678-1234-1234-1234-123456789ABC}';
+
+/**
+ * Obfuscate a font the way Word does, so the converter must deobfuscate it. The DOCX obfuscation XORs
+ * the first 32 bytes with the reversed GUID byte pattern - the SAME operation as deobfuscation (XOR is
+ * symmetric), so this is `deobfuscateFont` run forwards. Returns a Uint8Array (the shape unzip yields).
+ */
+function obfuscate(cleanBuffer, guidHex = GUID) {
+  const dta = new Uint8Array(cleanBuffer.slice(0));
+  const guidStr = guidHex.replace(/[-{}]/g, '');
+  const guidBytes = new Uint8Array(16);
+  for (let i = 0, j = 0; i < 32; i += 2, j += 1) guidBytes[j] = parseInt(guidStr[i] + guidStr[i + 1], 16);
+  for (let i = 0; i < 32; i += 1) dta[i] ^= guidBytes[15 - (i % 16)];
+  return dta;
+}
+
+/** w:font entry with embedded faces (w:embed* children carrying r:id + w:fontKey). */
+function fontEntry(name, embeds) {
+  return {
+    type: 'element',
+    name: 'w:font',
+    attributes: { 'w:name': name },
+    elements: embeds.map(([embedName, rId]) => ({
+      type: 'element',
+      name: embedName,
+      attributes: { 'r:id': rId, 'w:fontKey': GUID },
+    })),
+  };
+}
+
+function makeConverter() {
+  const converter = new SuperConverter();
+  converter.convertedXml['word/fontTable.xml'] = {
+    elements: [
+      {
+        type: 'element',
+        name: 'w:fonts',
+        elements: [
+          fontEntry('Calibri', [
+            ['w:embedRegular', 'rId1'],
+            ['w:embedBold', 'rId2'],
+          ]),
+          // OS/2 (700/italic) must WIN over the "Regular" embed name.
+          fontEntry('Aptos', [['w:embedRegular', 'rId3']]),
+          // Restricted-License (fsType bit 1): extracted but flagged not embeddable.
+          fontEntry('SecretFont', [['w:embedRegular', 'rId4']]),
+          // Unreadable bytes (not an SFNT): null OS/2 policy -> fallback face from the embed NAME,
+          // and conservatively not embeddable.
+          fontEntry('CorruptFont', [['w:embedBold', 'rId5']]),
+          // A font referenced by an embed whose relationship is missing -> skipped (no Target).
+          fontEntry('GhostFont', [['w:embedRegular', 'rId99']]),
+          // A non-embedded entry (no r:id/w:fontKey child) -> ignored entirely.
+          {
+            type: 'element',
+            name: 'w:font',
+            attributes: { 'w:name': 'Arial' },
+            elements: [{ type: 'element', name: 'w:altName', attributes: { 'w:val': 'Arial' } }],
+          },
+        ],
+      },
+    ],
+  };
+  converter.convertedXml['word/_rels/fontTable.xml.rels'] = {
+    elements: [
+      {
+        type: 'element',
+        name: 'Relationships',
+        elements: [
+          { type: 'element', name: 'Relationship', attributes: { Id: 'rId1', Target: 'fonts/font1.odttf' } },
+          { type: 'element', name: 'Relationship', attributes: { Id: 'rId2', Target: 'fonts/font2.odttf' } },
+          { type: 'element', name: 'Relationship', attributes: { Id: 'rId3', Target: 'fonts/font3.odttf' } },
+          { type: 'element', name: 'Relationship', attributes: { Id: 'rId4', Target: 'fonts/font4.odttf' } },
+          { type: 'element', name: 'Relationship', attributes: { Id: 'rId5', Target: 'fonts/font5.odttf' } },
+          // rId99 intentionally absent.
+        ],
+      },
+    ],
+  };
+  converter.fonts = {
+    'word/fonts/font1.odttf': obfuscate(makeSfnt({ usWeightClass: 400, fsType: 0, fsSelection: 0 })),
+    'word/fonts/font2.odttf': obfuscate(makeSfnt({ usWeightClass: 700, fsType: 0, fsSelection: 0 })),
+    'word/fonts/font3.odttf': obfuscate(makeSfnt({ usWeightClass: 700, fsType: 0, fsSelection: 0x01 })),
+    'word/fonts/font4.odttf': obfuscate(makeSfnt({ usWeightClass: 400, fsType: 0x0002, fsSelection: 0 })),
+    'word/fonts/font5.odttf': new Uint8Array([1, 2, 3, 4]), // too short to be an SFNT
+  };
+  return converter;
+}
+
+describe('SuperConverter.getEmbeddedFontFaces', () => {
+  it('extracts + deobfuscates embedded faces with OS/2-derived weight/style and embeddability', () => {
+    const faces = makeConverter().getEmbeddedFontFaces();
+
+    // Drop the binary source for the structural comparison; assert it separately below.
+    const summary = faces.map(({ source: _source, ...rest }) => rest);
+    expect(summary).toEqual([
+      { family: 'Calibri', weight: '400', style: 'normal', fsType: 0, embeddable: true, relationshipId: 'rId1' },
+      { family: 'Calibri', weight: '700', style: 'normal', fsType: 0, embeddable: true, relationshipId: 'rId2' },
+      // OS/2 (700/italic) overrides the "Regular" embed name.
+      { family: 'Aptos', weight: '700', style: 'italic', fsType: 0, embeddable: true, relationshipId: 'rId3' },
+      // Restricted-License: extracted, fsType preserved, not embeddable.
+      {
+        family: 'SecretFont',
+        weight: '400',
+        style: 'normal',
+        fsType: 0x0002,
+        embeddable: false,
+        relationshipId: 'rId4',
+      },
+      // Unreadable OS/2: face from the embed name (Bold -> 700), fsType null, not embeddable.
+      {
+        family: 'CorruptFont',
+        weight: '700',
+        style: 'normal',
+        fsType: null,
+        embeddable: false,
+        relationshipId: 'rId5',
+      },
+      // GhostFont (missing relationship) and Arial (no embed) are absent.
+    ]);
+  });
+
+  it('returns the deobfuscated SFNT bytes as a fresh ArrayBuffer (round-trips the obfuscation)', () => {
+    const faces = makeConverter().getEmbeddedFontFaces();
+    const calibri = faces.find((f) => f.relationshipId === 'rId1');
+
+    expect(calibri.source).toBeInstanceOf(ArrayBuffer);
+    expect(calibri.source.byteLength).toBe(92);
+    // Deobfuscation restored the SFNT version word (0x00010000) the obfuscation had scrambled.
+    expect(new DataView(calibri.source).getUint32(0)).toBe(0x00010000);
+  });
+
+  it('does not mutate the pooled converter font bytes (deobfuscation works on a copy)', () => {
+    const converter = makeConverter();
+    const before = Array.from(converter.fonts['word/fonts/font1.odttf'].slice(0, 4));
+    converter.getEmbeddedFontFaces();
+    const after = Array.from(converter.fonts['word/fonts/font1.odttf'].slice(0, 4));
+    expect(after).toEqual(before); // stored obfuscated bytes untouched
+  });
+
+  it('returns [] when there is no font table or no embedded binaries', () => {
+    const empty = new SuperConverter();
+    expect(empty.getEmbeddedFontFaces()).toEqual([]);
+
+    const noBinaries = makeConverter();
+    noBinaries.fonts = {};
+    expect(noBinaries.getEmbeddedFontFaces()).toEqual([]);
+  });
+});

From 1641f364be32b46a481b7604bfdd9092e3e59997 Mon Sep 17 00:00:00 2001
From: Caio Pizzol <caio@superdoc.dev>
Date: Thu, 4 Jun 2026 23:02:09 -0300
Subject: [PATCH 7/8] feat(fonts): render-isolate embedded fonts via a
 document-unique physical family

The FontFaceSet is shared per page, so registering an embedded font under its logical name (Calibri) let two documents that both embed Calibri cross-render each other's subset bytes - handle-based release fixed cleanup ownership but not RENDER ownership. Each document now registers its embedded faces under a unique physical family (e.g. __superdoc_embedded_3__0_Calibri) and binds logical->physical in its own resolver via mapEmbedded; the face-aware ladder resolves that to registered_face and the paint/measure seam swaps the primary to it, so a document always renders its OWN bytes. The logical name is kept for export and the public font report (the alias is used only for the load-status lookup). reset()/dispose() drop the bindings and release the faces; the signature folds embedded bindings in (document-distinct cache keys) but is unchanged when there are no embedded fonts. A fonts.add real face still resolves to the logical name (physical === logical), so that path is untouched.
---
 .../fonts/DocumentFontController.test.ts      |  98 +++++++++++-----
 .../fonts/DocumentFontController.ts           |  69 +++++++++--
 shared/font-system/src/report.test.ts         |  22 ++++
 shared/font-system/src/report.ts              |   7 +-
 shared/font-system/src/resolver.test.ts       | 109 +++++++++++++++++-
 shared/font-system/src/resolver.ts            | 101 ++++++++++++----
 6 files changed, 342 insertions(+), 64 deletions(-)

diff --git a/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.test.ts b/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.test.ts
index 0361589389..6c7e473ba8 100644
--- a/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.test.ts
+++ b/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.test.ts
@@ -343,14 +343,20 @@ describe('DocumentFontController', () => {
       ...over,
     });
 
-    it('registers embeddable faces, skips restricted, and invalidates caches without a reflow/event', () => {
+    const hasFaceOf = (registry: FakeRegistry) => (f: string, w: '400' | '700', s: 'normal' | 'italic') =>
+      registry.hasFace(f, w, s);
+    const regular = { weight: '400', style: 'normal' } as const;
+
+    it('registers embeddable faces under a unique physical family, skips restricted, invalidates without reflow/event', () => {
       const {
         controller,
+        resolver,
         registry,
         invalidateCachesForConfigRegistration,
         notifyDocumentFontConfigChanged,
         onDocumentFontConfigApplied,
       } = makeController();
+      const hasFace = hasFaceOf(registry);
 
       controller.applyEmbeddedFaces([
         embed({ family: 'Calibri', weight: '400' }),
@@ -359,22 +365,26 @@ describe('DocumentFontController', () => {
         embed({ family: 'SecretFont', fsType: 0x0002, embeddable: false, relationshipId: 'rId3' }),
       ]);
 
+      // Both Calibri faces register under ONE document-unique physical family - never the shared
+      // logical name "Calibri" (which would let another document render these bytes).
+      const phys = resolver.resolveFace('Calibri', regular, hasFace).physicalFamily;
+      expect(phys).toMatch(/^__superdoc_embedded_\d+__\d+_Calibri$/);
       expect(registry.ownedRegistered).toEqual([
-        { family: 'Calibri', weight: '400', style: 'normal' },
-        { family: 'Calibri', weight: '700', style: 'normal' },
+        { family: phys, weight: '400', style: 'normal' },
+        { family: phys, weight: '700', style: 'normal' },
       ]);
+      expect(registry.hasFace(phys, '700', 'normal')).toBe(true);
+      expect(registry.hasFace('Calibri', '400', 'normal')).toBe(false); // logical name NOT in the shared set
       expect(registry.hasFace('SecretFont', '400', 'normal')).toBe(false); // restricted never registered
-      // Config-time registration: clears the shared measure caches, but no reflow/event (first measure
-      // has not happened yet).
+      // Config-time registration: clears the shared measure caches, but no reflow/event.
       expect(invalidateCachesForConfigRegistration).toHaveBeenCalledTimes(1);
       expect(onDocumentFontConfigApplied).not.toHaveBeenCalled();
       expect(notifyDocumentFontConfigChanged).not.toHaveBeenCalled();
     });
 
-    it('makes the resolver render the embedded real family via registered_face (not the bundled clone)', () => {
+    it('resolves the logical family to the unique physical via registered_face, and paint swaps to it', () => {
       const { controller, resolver, registry } = makeController();
-      const hasFace = (f: string, w: '400' | '700', s: 'normal' | 'italic') => registry.hasFace(f, w, s);
-      const regular = { weight: '400', style: 'normal' } as const;
+      const hasFace = hasFaceOf(registry);
 
       // Before: Calibri falls back to the bundled substitute (Carlito).
       expect(resolver.resolveFace('Calibri', regular, hasFace).physicalFamily).toBe('Carlito');
@@ -382,69 +392,93 @@ describe('DocumentFontController', () => {
       controller.applyEmbeddedFaces([embed({ family: 'Calibri' })]);
 
       const resolved = resolver.resolveFace('Calibri', regular, hasFace);
-      expect(resolved.physicalFamily).toBe('Calibri'); // the document's real embedded font
       expect(resolved.reason).toBe('registered_face');
+      expect(resolved.physicalFamily).not.toBe('Calibri'); // NOT the shared logical name
+      expect(resolved.physicalFamily).toMatch(/^__superdoc_embedded_\d+__\d+_Calibri$/);
+      // The paint/measure seam swaps the primary to the unique physical family (fallbacks preserved).
+      expect(resolver.resolvePhysicalFamilyForFace('Calibri, serif', regular, hasFace)).toBe(
+        `${resolved.physicalFamily}, serif`,
+      );
     });
 
-    it('releases every embedded face on reset (document swap)', () => {
-      const { controller, registry } = makeController();
+    it('releases embedded faces and resolver bindings on reset (document swap)', () => {
+      const { controller, resolver, registry } = makeController();
+      const hasFace = hasFaceOf(registry);
       controller.applyEmbeddedFaces([
         embed({ family: 'Calibri', weight: '400' }),
         embed({ family: 'Calibri', weight: '700' }),
       ]);
-      expect(registry.hasFace('Calibri', '400', 'normal')).toBe(true);
+      const phys = resolver.resolveFace('Calibri', regular, hasFace).physicalFamily;
+      expect(registry.hasFace(phys, '400', 'normal')).toBe(true);
 
       controller.reset();
 
       expect(registry.ownedReleased).toEqual([
-        { family: 'Calibri', weight: '400', style: 'normal' },
-        { family: 'Calibri', weight: '700', style: 'normal' },
+        { family: phys, weight: '400', style: 'normal' },
+        { family: phys, weight: '700', style: 'normal' },
       ]);
-      expect(registry.hasFace('Calibri', '400', 'normal')).toBe(false);
+      expect(registry.hasFace(phys, '400', 'normal')).toBe(false);
+      // Resolver reverts: Calibri falls back to the bundled substitute again.
+      expect(resolver.resolveFace('Calibri', regular, hasFace).physicalFamily).toBe('Carlito');
     });
 
-    it('releases every embedded face on dispose (teardown)', () => {
-      const { controller, registry } = makeController();
+    it('releases embedded faces and resolver bindings on dispose (teardown)', () => {
+      const { controller, resolver, registry } = makeController();
+      const hasFace = hasFaceOf(registry);
       controller.applyEmbeddedFaces([embed({ family: 'Calibri' })]);
+      const phys = resolver.resolveFace('Calibri', regular, hasFace).physicalFamily;
 
       controller.dispose();
 
-      expect(registry.ownedReleased).toEqual([{ family: 'Calibri', weight: '400', style: 'normal' }]);
-      expect(registry.hasFace('Calibri', '400', 'normal')).toBe(false);
+      expect(registry.ownedReleased).toEqual([{ family: phys, weight: '400', style: 'normal' }]);
+      expect(resolver.resolveFace('Calibri', regular, hasFace).physicalFamily).toBe('Carlito');
     });
 
-    it('replaces the prior embedded set on re-apply (releases old, registers new)', () => {
-      const { controller, registry } = makeController();
+    it('replaces the prior embedded set on re-apply (releases old, binds new)', () => {
+      const { controller, resolver, registry } = makeController();
+      const hasFace = hasFaceOf(registry);
       controller.applyEmbeddedFaces([embed({ family: 'Calibri' })]);
+      const calibriPhys = resolver.resolveFace('Calibri', regular, hasFace).physicalFamily;
+
       controller.applyEmbeddedFaces([embed({ family: 'Cambria' })]);
 
-      expect(registry.ownedReleased).toEqual([{ family: 'Calibri', weight: '400', style: 'normal' }]);
-      expect(registry.hasFace('Calibri', '400', 'normal')).toBe(false);
-      expect(registry.hasFace('Cambria', '400', 'normal')).toBe(true);
+      expect(registry.ownedReleased).toEqual([{ family: calibriPhys, weight: '400', style: 'normal' }]);
+      expect(resolver.resolveFace('Calibri', regular, hasFace).physicalFamily).toBe('Carlito'); // released -> bundled
+      const cambria = resolver.resolveFace('Cambria', regular, hasFace);
+      expect(cambria.reason).toBe('registered_face');
+      expect(cambria.physicalFamily).toMatch(/^__superdoc_embedded_\d+__\d+_Cambria$/);
     });
 
     it('does nothing (no invalidate) when there are no embeddable faces', () => {
-      const { controller, registry, invalidateCachesForConfigRegistration } = makeController();
+      const { controller, resolver, registry, invalidateCachesForConfigRegistration } = makeController();
+      const hasFace = hasFaceOf(registry);
       controller.applyEmbeddedFaces([embed({ family: 'SecretFont', embeddable: false })]);
 
       expect(registry.ownedRegistered).toHaveLength(0);
       expect(invalidateCachesForConfigRegistration).not.toHaveBeenCalled();
+      expect(resolver.resolveFace('SecretFont', regular, hasFace).reason).toBe('as_requested');
     });
 
-    it("with a shared registry, one document's swap releases only its own embedded faces", () => {
-      // Two editors on ONE FontFaceSet (shared registry). This is exactly why release is handle-based:
-      // doc A's reset must not drop doc B's face.
+    it('gives each document a distinct physical family for the SAME logical name (render isolation)', () => {
+      // Two editors on ONE FontFaceSet, both embedding "Calibri" with different bytes. The unique
+      // physical families keep render ownership document-scoped: neither cleanup nor matching crosses.
       const registry = new FakeRegistry();
       const docA = makeController(registry);
       const docB = makeController(registry);
+      const hasFace = hasFaceOf(registry);
+
       docA.controller.applyEmbeddedFaces([embed({ family: 'Calibri' })]);
-      docB.controller.applyEmbeddedFaces([embed({ family: 'Cambria' })]);
+      docB.controller.applyEmbeddedFaces([embed({ family: 'Calibri' })]); // same logical family, other doc
+
+      const physA = docA.resolver.resolveFace('Calibri', regular, hasFace).physicalFamily;
+      const physB = docB.resolver.resolveFace('Calibri', regular, hasFace).physicalFamily;
+      expect(physA).not.toBe(physB); // distinct physical families for the same logical "Calibri"
 
       docA.controller.reset();
 
-      expect(registry.ownedReleased).toEqual([{ family: 'Calibri', weight: '400', style: 'normal' }]);
-      expect(registry.hasFace('Calibri', '400', 'normal')).toBe(false); // doc A released
-      expect(registry.hasFace('Cambria', '400', 'normal')).toBe(true); // doc B intact
+      expect(registry.hasFace(physA, '400', 'normal')).toBe(false); // doc A released
+      expect(registry.hasFace(physB, '400', 'normal')).toBe(true); // doc B intact
+      expect(docB.resolver.resolveFace('Calibri', regular, hasFace).reason).toBe('registered_face');
     });
   });
 });
diff --git a/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.ts b/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.ts
index 071c0bf627..f3c1a0b550 100644
--- a/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.ts
+++ b/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.ts
@@ -27,9 +27,10 @@ export interface DocumentFontControllerDeps {
 /**
  * A document's embedded font face, as extracted by the converter (`SuperConverter.getEmbeddedFontFaces`):
  * the deobfuscated bytes plus the OS/2-derived face axis and raw `fsType` licensing. The controller
- * registers each {@link embeddable} face under its own family name so the resolver's `registered_face`
- * rung renders the document's real font instead of the bundled substitute; it skips faces that are not
- * embeddable (Restricted-License, or an unreadable OS/2 table - no proof the license permits embedding).
+ * registers each {@link embeddable} face under a document-unique physical family (binding the logical
+ * family to it in the resolver) so the `registered_face` rung renders the document's real font instead
+ * of the bundled substitute; it skips faces that are not embeddable (Restricted-License, or an
+ * unreadable OS/2 table - no proof the license permits embedding).
  */
 export interface EmbeddedFontFace {
   family: string;
@@ -51,6 +52,22 @@ function toCssFontSource(url: string): string {
   return /^\s*url\(/i.test(url) ? url : `url(${JSON.stringify(url)})`;
 }
 
+/**
+ * Monotonic per-page counter giving each document controller a distinct embedded-font namespace, so
+ * the document-unique physical families two controllers mint never collide in the shared FontFaceSet.
+ */
+let embeddedDocumentCounter = 0;
+function nextEmbeddedNamespace(): string {
+  embeddedDocumentCounter += 1;
+  return `__superdoc_embedded_${embeddedDocumentCounter}__`;
+}
+
+/** Reduce a family name to a CSS-identifier-safe token (no spaces/punctuation) for use inside a
+ *  physical family name, so the painted `font-family` is a single valid unquoted token. */
+function sanitizeFamilyToken(family: string): string {
+  return family.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'font';
+}
+
 /**
  * The single writer for a document's font state: `map`/`unmap` change the resolver, `add`
  * registers customer faces through the registry, and `preload` loads them. Runtime
@@ -84,6 +101,16 @@ export class DocumentFontController {
    * release; replaced wholesale on each {@link applyEmbeddedFaces}.
    */
   readonly #embeddedDisposers: Array<() => void> = [];
+  /**
+   * This document's embedded-font namespace, unique per controller, so its physical families never
+   * collide with another editor's in the shared FontFaceSet.
+   */
+  readonly #embeddedNamespace = nextEmbeddedNamespace();
+  /**
+   * Normalized logical family -> this document's unique physical family for it. Dedupes the faces of
+   * one embedded family (e.g. Calibri regular + bold) onto a single physical family. Cleared on release.
+   */
+  readonly #embeddedPhysical = new Map<string, string>();
 
   constructor(deps: DocumentFontControllerDeps) {
     this.#resolver = deps.resolver;
@@ -149,10 +176,13 @@ export class DocumentFontController {
   /**
    * Register the document's embedded fonts (from `SuperConverter.getEmbeddedFontFaces`) as first-class
    * registry faces, BEFORE the first layout measure. Each {@link EmbeddedFontFace.embeddable} face is
-   * registered under its own family name, so the resolver's `registered_face` rung renders the
-   * document's real font (e.g. its embedded Calibri) instead of the bundled substitute (Carlito) - with
-   * no resolver special-casing. Non-embeddable faces (Restricted-License, or an unreadable OS/2 table)
-   * are skipped: the bundled substitute renders them.
+   * registered under a DOCUMENT-UNIQUE physical family (e.g. `__superdoc_embedded_3__0_Calibri`), and the
+   * logical family is bound to it in this document's resolver, so the `registered_face` rung renders the
+   * document's real font instead of the bundled substitute (Carlito) - with no resolver special-casing.
+   * The FontFaceSet is shared per page, so registering under the logical name would let another document
+   * render these bytes; the unique physical name keeps render ownership document-scoped while export and
+   * the font report keep the logical name. Non-embeddable faces (Restricted-License, or an unreadable
+   * OS/2 table) are skipped: the bundled substitute renders them.
    *
    * Document-scoped: the controller holds a release handle per registered face and frees them on
    * {@link reset} (document swap) / {@link dispose} (teardown), so this document's fonts never leak into
@@ -173,20 +203,36 @@ export class DocumentFontController {
     let registered = false;
     for (const face of faces) {
       if (!face?.embeddable) continue;
+      const physicalFamily = this.#physicalFamilyFor(face.family);
       const release = registry.registerOwnedFace({
-        family: face.family,
+        family: physicalFamily,
         source: face.source,
         weight: face.weight,
         style: face.style,
       });
       if (release) {
         this.#embeddedDisposers.push(release);
+        // Bind logical -> this document's unique physical family so the resolver renders THIS document's
+        // bytes (registered_face). Idempotent across the family's faces (regular + bold share it).
+        this.#resolver.mapEmbedded(face.family, physicalFamily);
         registered = true;
       }
     }
     if (registered) this.#getGate()?.invalidateCachesForConfigRegistration();
   }
 
+  /** This document's unique physical family for a logical embedded family, assigned once per family
+   *  (its faces share it). The per-family index guarantees uniqueness even if two names sanitize alike. */
+  #physicalFamilyFor(logicalFamily: string): string {
+    const key = logicalFamily.trim().toLowerCase();
+    let physical = this.#embeddedPhysical.get(key);
+    if (!physical) {
+      physical = `${this.#embeddedNamespace}${this.#embeddedPhysical.size}_${sanitizeFamilyToken(logicalFamily)}`;
+      this.#embeddedPhysical.set(key, physical);
+    }
+    return physical;
+  }
+
   /**
    * Register custom physical font faces (e.g. a customer's Gelasio woff2s) so they become loadable
    * and mappable. Registers only - it does NOT map (call {@link map} for that). Idempotent per
@@ -314,11 +360,14 @@ export class DocumentFontController {
     this.#runtimeReflowToken += 1;
   }
 
-  /** Release every embedded face this document registered (each disposer removes one specific face),
-   *  then clear the list. Safe to call repeatedly; the disposers are idempotent. */
+  /** Release every embedded face this document registered (each disposer removes one specific face) and
+   *  drop the resolver bindings, so neither the FontFaceSet nor the resolver retains this document's
+   *  embedded fonts. Safe to call repeatedly; the disposers are idempotent. */
   #releaseEmbeddedFaces(): void {
     for (const release of this.#embeddedDisposers) release();
     this.#embeddedDisposers.length = 0;
+    this.#embeddedPhysical.clear();
+    this.#resolver.clearEmbedded();
   }
 }
 
diff --git a/shared/font-system/src/report.test.ts b/shared/font-system/src/report.test.ts
index 34f4290d83..de1c5dac08 100644
--- a/shared/font-system/src/report.test.ts
+++ b/shared/font-system/src/report.test.ts
@@ -208,4 +208,26 @@ describe('buildFaceReport (face-level)', () => {
     expect(bold?.loadStatus).toBe('failed');
     expect(bold?.missing).toBe(true); // the bold face failed - reported missing, regular unaffected
   });
+
+  it('hides the internal embedded alias: reports the logical family, but reads status via the alias', () => {
+    const reg = new FaceRegistry();
+    const PHYS = '__superdoc_embedded_3__0_Calibri';
+    reg.setFace(PHYS, '400', 'normal', 'loaded'); // the embedded face is registered under the alias
+    const resolver = createFontResolver();
+    resolver.mapEmbedded('Calibri', PHYS);
+    const [row] = buildFaceReport(
+      [{ logicalFamily: 'Calibri', weight: '400', style: 'normal' }],
+      reg.asRegistry(),
+      resolver,
+    );
+    expect(row).toEqual({
+      logicalFamily: 'Calibri',
+      physicalFamily: 'Calibri', // the real name, NOT __superdoc_embedded_*
+      reason: 'registered_face',
+      loadStatus: 'loaded', // proves the status was looked up via the alias (where the face lives)
+      exportFamily: 'Calibri',
+      missing: false,
+      face: { weight: '400', style: 'normal' },
+    });
+  });
 });
diff --git a/shared/font-system/src/report.ts b/shared/font-system/src/report.ts
index 2acb1e6431..2a76a0369b 100644
--- a/shared/font-system/src/report.ts
+++ b/shared/font-system/src/report.ts
@@ -125,7 +125,12 @@ export function buildFaceReport(
     const missing = reason === 'fallback_face_absent' || (isSettled(loadStatus) && loadStatus !== 'loaded');
     report.push({
       logicalFamily,
-      physicalFamily,
+      // For an embedded font, the resolved physical is a document-unique INTERNAL alias
+      // (`__superdoc_embedded_*`) used only to keep render ownership in the shared FontFaceSet - the
+      // load-status lookup above needs it, but the faithful physical the user sees is the real (logical)
+      // family. Report the logical name for `registered_face` so the alias never leaks into the public
+      // report. (`fonts.add` registered_face already has physical === logical, so this is a no-op there.)
+      physicalFamily: reason === 'registered_face' ? logicalFamily : physicalFamily,
       reason,
       loadStatus,
       exportFamily: logicalFamily,
diff --git a/shared/font-system/src/resolver.test.ts b/shared/font-system/src/resolver.test.ts
index 13046f0467..35fd7942bb 100644
--- a/shared/font-system/src/resolver.test.ts
+++ b/shared/font-system/src/resolver.test.ts
@@ -258,7 +258,9 @@ describe('face-aware resolution (resolveFace / resolvePhysicalFamilyForFace)', (
 
   it('a REGISTERED real face for the logical family wins over the bundled substitute (registered_face)', () => {
     const r = createFontResolver();
-    // A customer fonts.add (later: an embedded document font) registered real Calibri faces.
+    // A customer `fonts.add` registered real Calibri faces under the logical name (document-agnostic, so
+    // the physical IS the logical family). Embedded document fonts take a separate path - a
+    // document-unique physical family via `mapEmbedded` (see the embedded-provider-identity tests below).
     for (const face of FACES) {
       expect(r.resolveFace('Calibri', face, registered('Calibri'))).toEqual({
         logicalFamily: 'Calibri',
@@ -356,3 +358,108 @@ describe('face-aware resolution (resolveFace / resolvePhysicalFamilyForFace)', (
     });
   });
 });
+
+describe('embedded provider identity (mapEmbedded / clearEmbedded)', () => {
+  const norm = (f: string) => f.replace(/^["']|["']$/g, '').toLowerCase();
+  const PHYS = '__superdoc_embedded_7__0_Calibri';
+  const registeredOf =
+    (...families: string[]) =>
+    (f: string) => {
+      const set = new Set(families.map(norm));
+      return set.has(norm(f));
+    };
+  const regular = { weight: '400', style: 'normal' } as const;
+
+  it('binds a logical family to a unique physical family (registered_face), beating the bundled clone', () => {
+    const r = createFontResolver();
+    r.mapEmbedded('Calibri', PHYS);
+    const hasFace = registeredOf(PHYS, 'Carlito'); // embed physical + bundled clone both loadable
+    expect(r.resolveFace('Calibri', regular, hasFace)).toEqual({
+      logicalFamily: 'Calibri',
+      physicalFamily: PHYS, // this document's OWN embedded font, not Carlito and not a shared "Calibri"
+      reason: 'registered_face',
+    });
+    // Paint/measure swaps the primary to the unique physical family (fallbacks preserved).
+    expect(r.resolvePhysicalFamilyForFace('Calibri, sans-serif', regular, hasFace)).toBe(`${PHYS}, sans-serif`);
+  });
+
+  it('beats a same-named registered face (the document embed wins over a global "Calibri")', () => {
+    const r = createFontResolver();
+    r.mapEmbedded('Calibri', PHYS);
+    // Both the unique physical AND a bare "Calibri" (e.g. another document's fonts.add) are loadable.
+    expect(r.resolveFace('Calibri', regular, registeredOf(PHYS, 'Calibri')).physicalFamily).toBe(PHYS);
+  });
+
+  it('is face-aware: a face the embed lacks falls through to the bundled substitute', () => {
+    const r = createFontResolver();
+    r.mapEmbedded('Calibri', PHYS);
+    const hasFace = (f: string, w: '400' | '700', s: 'normal' | 'italic') => {
+      if (norm(f) === norm(PHYS)) return w === '400' && s === 'normal'; // embed: Regular only
+      if (norm(f) === 'carlito') return true; // bundled clone: every face
+      return false;
+    };
+    expect(r.resolveFace('Calibri', { weight: '400', style: 'normal' }, hasFace)).toMatchObject({
+      physicalFamily: PHYS,
+      reason: 'registered_face',
+    });
+    // Bold: the embed lacks it -> bundled substitute, never the embed faux-styled.
+    expect(r.resolveFace('Calibri', { weight: '700', style: 'normal' }, hasFace)).toEqual({
+      logicalFamily: 'Calibri',
+      physicalFamily: 'Carlito',
+      reason: 'bundled_substitute',
+    });
+  });
+
+  it('an explicit fonts.map override still wins over the embedded font', () => {
+    const r = createFontResolver();
+    r.mapEmbedded('Calibri', PHYS);
+    r.map('Calibri', 'Tinos');
+    expect(r.resolveFace('Calibri', regular, registeredOf(PHYS, 'Tinos'))).toMatchObject({
+      physicalFamily: 'Tinos',
+      reason: 'custom_mapping',
+    });
+  });
+
+  it('clearEmbedded reverts the logical family to its bundled substitute', () => {
+    const r = createFontResolver();
+    r.mapEmbedded('Calibri', PHYS);
+    const hasFace = registeredOf(PHYS, 'Carlito');
+    expect(r.resolveFace('Calibri', regular, hasFace).reason).toBe('registered_face');
+    r.clearEmbedded();
+    expect(r.resolveFace('Calibri', regular, hasFace)).toMatchObject({
+      physicalFamily: 'Carlito',
+      reason: 'bundled_substitute',
+    });
+  });
+
+  it('reset() drops embedded bindings as well as fonts.map overrides', () => {
+    const r = createFontResolver();
+    r.mapEmbedded('Calibri', PHYS);
+    r.map('Georgia', 'Gelasio');
+    r.reset();
+    expect(r.resolveFace('Calibri', regular, registeredOf(PHYS, 'Carlito')).reason).toBe('bundled_substitute');
+    expect(r.resolvePrimaryPhysicalFamily('Georgia')).toBe('Georgia');
+    expect(r.signature).toBe('');
+  });
+
+  it('folds embedded bindings into the signature (document-distinct; empty restores cache sharing)', () => {
+    const r = createFontResolver();
+    expect(r.signature).toBe('');
+    r.mapEmbedded('Calibri', PHYS);
+    expect(r.signature).not.toBe(''); // its physical is document-unique -> de-opts shared cache
+    const other = createFontResolver();
+    other.mapEmbedded('Calibri', '__superdoc_embedded_8__0_Calibri');
+    expect(other.signature).not.toBe(r.signature); // two documents, same logical, distinct signatures
+    r.clearEmbedded();
+    expect(r.signature).toBe(''); // back to shared-default identity
+  });
+
+  it('keeps the existing signature format when there are no embedded bindings', () => {
+    const a = createFontResolver();
+    const b = createFontResolver();
+    a.map('Georgia', 'Gelasio');
+    b.map('Georgia', 'Gelasio');
+    expect(a.signature).toBe(b.signature); // same mappings -> same signature (unchanged)
+    expect(a.signature).not.toBe('');
+  });
+});
diff --git a/shared/font-system/src/resolver.ts b/shared/font-system/src/resolver.ts
index 7e0fec10a5..568627fd4d 100644
--- a/shared/font-system/src/resolver.ts
+++ b/shared/font-system/src/resolver.ts
@@ -90,6 +90,11 @@ function normalizeFamilyKey(family: string): string {
     .toLowerCase();
 }
 
+/** Deterministically sort [key, value] pairs by key, for a stable, order-independent signature. */
+function sortPairs(pairs: Array<[string, string]>): Array<[string, string]> {
+  return pairs.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
 /** Split a CSS font-family value into trimmed, non-empty families (primary first). */
 function splitStack(cssFontFamily: string): string[] {
   return cssFontFamily
@@ -109,6 +114,16 @@ function splitStack(cssFontFamily: string): string[] {
 export class FontResolver {
   /** Normalized logical family -> physical family. Takes precedence over the bundled map. */
   readonly #overrides = new Map<string, string>();
+  /**
+   * Normalized logical family -> this document's UNIQUE physical render family for its embedded font
+   * (e.g. `calibri` -> `__superdoc_embedded_3__Calibri`). Document-owned render identity: the browser's
+   * FontFaceSet is shared per page, so two documents that both embed "Calibri" must render under
+   * distinct physical families or one document would paint with the other's (subset) bytes. Resolves
+   * to `registered_face` and beats a same-named customer `fonts.add` face; the logical name is kept for
+   * export/report. Set by the document font controller, which also registers the face under the same
+   * physical name; cleared on a document swap / teardown.
+   */
+  readonly #embedded = new Map<string, string>();
   #version = 0;
   /** Memoized {@link signature}; null = stale, recomputed on next read. Invalidated on every mutation. */
   #cachedSignature: string | null = null;
@@ -153,13 +168,40 @@ export class FontResolver {
   }
 
   /**
-   * Drop all runtime overrides, reverting to the bundled-only map. Call on a document swap
-   * (the same editor instance is reused, so the prior document's `fonts.map` must not leak
-   * into the next). Bumps {@link version} only if something was actually cleared.
+   * Bind a logical family to this document's UNIQUE physical render family for its embedded font, so
+   * the face-aware ladder resolves the logical family to that physical name with reason
+   * `registered_face`. The caller (the document font controller) must register the face under the same
+   * physical name. Render-only: export keeps the logical family. The physical name must be unique to
+   * this document so a shared FontFaceSet cannot cross-render another document's embedded bytes.
+   */
+  mapEmbedded(logicalFamily: string, physicalFamily: string): void {
+    const key = normalizeFamilyKey(logicalFamily);
+    const physical = physicalFamily?.trim();
+    if (!key || !physical) return;
+    if (this.#embedded.get(key) === physical) return;
+    this.#embedded.set(key, physical);
+    this.#version += 1;
+    this.#cachedSignature = null;
+  }
+
+  /** Drop all embedded-family bindings (a document swap / teardown releases this document's embedded
+   *  fonts). Bumps {@link version} only if something was cleared. */
+  clearEmbedded(): void {
+    if (this.#embedded.size === 0) return;
+    this.#embedded.clear();
+    this.#version += 1;
+    this.#cachedSignature = null;
+  }
+
+  /**
+   * Drop all runtime overrides AND embedded bindings, reverting to the bundled-only map. Call on a
+   * document swap (the same editor instance is reused, so the prior document's `fonts.map` and embedded
+   * fonts must not leak into the next). Bumps {@link version} only if something was actually cleared.
    */
   reset(): void {
-    if (this.#overrides.size === 0) return;
+    if (this.#overrides.size === 0 && this.#embedded.size === 0) return;
     this.#overrides.clear();
+    this.#embedded.clear();
     this.#version += 1;
     this.#cachedSignature = null;
   }
@@ -179,14 +221,21 @@ export class FontResolver {
    */
   get signature(): string {
     if (this.#cachedSignature !== null) return this.#cachedSignature;
-    // JSON of sorted [logical, physical] pairs: deterministic and collision-safe even when a
-    // font name contains punctuation (a delimited "logical=physical|..." form would not be).
-    // Empty (no overrides) is '' so all default documents share cache. Memoized until the next
-    // mutation (map/unmap/reset clear the cache), since signature is read several times per render.
-    this.#cachedSignature =
-      this.#overrides.size === 0
-        ? ''
-        : JSON.stringify([...this.#overrides.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    // JSON of sorted [logical, physical] pairs: deterministic and collision-safe even when a font name
+    // contains punctuation (a delimited "logical=physical|..." form would not be). Empty (no overrides
+    // AND no embedded bindings) is '' so all default documents share cache. Embedded physical names are
+    // document-unique, so folding them in gives two embedded-Calibri documents distinct signatures
+    // (cache isolation). Format is unchanged when there are no embedded fonts (the common case keeps its
+    // existing identity). Memoized until the next mutation.
+    if (this.#overrides.size === 0 && this.#embedded.size === 0) {
+      this.#cachedSignature = '';
+    } else {
+      const overridePairs = sortPairs([...this.#overrides.entries()]);
+      this.#cachedSignature =
+        this.#embedded.size === 0
+          ? JSON.stringify(overridePairs)
+          : JSON.stringify({ o: overridePairs, e: sortPairs([...this.#embedded.entries()]) });
+    }
     return this.#cachedSignature;
   }
 
@@ -204,12 +253,14 @@ export class FontResolver {
    * The provider-precedence ladder for a bare PRIMARY family + face, consulting `hasFace` (the
    * registry's registered-face oracle):
    *   1. explicit `fonts.map` override  -> custom_mapping  (if the override provides the face)
-   *   2. a registered real face for the logical family itself (customer `fonts.add` / embedded)
-   *      -> registered_face  (so SuperDoc renders the real family instead of the bundled clone)
+   *   2a. this document's embedded face, under its UNIQUE physical family -> registered_face
+   *       (so a shared FontFaceSet renders THIS document's bytes, not another document's same-named font)
+   *   2b. a registered real face for the logical family itself (customer `fonts.add`) -> registered_face
    *   3. bundled metric-compatible substitute -> bundled_substitute  (if it provides the face)
    *   4. otherwise as_requested (no provider) - or fallback_face_absent when an override/substitute
    *      WAS known but lacked the face, so a single-face clone is never faux-styled.
-   * `physical === primary` (no swap) for registered_face / as_requested / fallback_face_absent.
+   * `physical === primary` (no swap) for 2b / as_requested / fallback_face_absent; an embedded face (2a)
+   * swaps to its unique physical family.
    */
   #resolveFaceLadder(
     primary: string,
@@ -225,7 +276,15 @@ export class FontResolver {
     if (override && hasFace(override, face.weight, face.style)) {
       return { physical: override, reason: 'custom_mapping' };
     }
-    // 2. a registered real face for the logical family itself (customer `fonts.add` / embedded).
+    // 2a. this document's embedded face, under its document-unique physical family. Checked before the
+    //     bare logical name so a document always renders its OWN embedded bytes, never another
+    //     document's same-named (subset) font sharing the page's FontFaceSet. Gated on hasFace so a
+    //     face the document does not embed (e.g. italic) falls through to the bundled substitute.
+    const embedded = this.#embedded.get(key);
+    if (embedded && hasFace(embedded, face.weight, face.style)) {
+      return { physical: embedded, reason: 'registered_face' };
+    }
+    // 2b. a registered real face for the logical family itself (customer `fonts.add`).
     if (hasFace(primary, face.weight, face.style)) {
       return { physical: primary, reason: 'registered_face' };
     }
@@ -295,10 +354,12 @@ export class FontResolver {
     const parts = splitStack(cssFontFamily);
     if (parts.length === 0) return cssFontFamily;
     const { physical, reason } = this.#resolveFaceLadder(parts[0], face, hasFace);
-    // Swap the primary to the physical ONLY when a substitute/override actually applies. For
-    // registered_face / as_requested / fallback_face_absent the physical IS the logical family, so
-    // keep the original stack (the registered real face or the browser fallback renders it).
-    if (reason === 'custom_mapping' || reason === 'bundled_substitute') {
+    // Swap the primary to the physical when a provider applies. For an embedded face, `registered_face`
+    // carries a document-unique physical family that MUST reach paint (else the shared FontFaceSet
+    // renders the wrong document's same-named font); for a `fonts.add` registered_face the physical
+    // equals the primary, so the swap is a harmless no-op. as_requested / fallback_face_absent keep the
+    // original stack (the physical IS the logical family; browser/system fallback renders it).
+    if (reason === 'custom_mapping' || reason === 'bundled_substitute' || reason === 'registered_face') {
       return [physical, ...parts.slice(1)].join(', ');
     }
     return cssFontFamily;

From bebbd4779260eee59f574f8a19dc84b2d2ec45bf Mon Sep 17 00:00:00 2001
From: Caio Pizzol <caio@superdoc.dev>
Date: Fri, 5 Jun 2026 17:37:33 -0300
Subject: [PATCH 8/8] fix(fonts): policy-gate legacy embedded @font-face +
 per-apply family generation

The legacy getFontFaceImportString path injected embedded faces with no embedding check, leaking Restricted-License or unreadable fonts under their logical family even though the registry path skips them. Gate it on the same parseEmbeddingPolicy rule, and skip a malformed embed (missing relationship/bytes/deobfuscation) instead of aborting the whole method, matching the registry path.

Fold a per-apply generation into the embedded physical family name. A same-controller document swap clears the per-family index, so without it the next document re-mints the prior name and aliases its in-flight face on the shared registry.

Update the DocumentFontController fake to report the bundled clone pack as loadable: after the resolver began gating bundled_substitute on hasFace(clone), the fake (which omits the pack) resolved Calibri to identity instead of Carlito.
---
 .../fonts/DocumentFontController.test.ts      | 46 +++++++++++++++++--
 .../fonts/DocumentFontController.ts           | 17 +++++--
 .../v1/core/super-converter/SuperConverter.js | 17 +++++--
 .../getEmbeddedFontFaces.test.js              | 21 +++++++++
 4 files changed, 91 insertions(+), 10 deletions(-)

diff --git a/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.test.ts b/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.test.ts
index 7144938e3e..00bea42bea 100644
--- a/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.test.ts
+++ b/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.test.ts
@@ -358,8 +358,21 @@ describe('DocumentFontController', () => {
       ...over,
     });
 
+    // The bundled substitute pack (Carlito, Caladea, Liberation Sans/Serif/Mono) is registered in
+    // production by installBundledSubstitutes, mirroring BUNDLED_MANIFEST. After #3653 the resolver only
+    // takes the bundled_substitute rung when the clone face is loadable (hasFace-gated), so a fake that
+    // omits the pack resolves e.g. Calibri to identity instead of Carlito. Report the clones as present -
+    // all are four-face, so they supply every weight/style - mirroring resolver.test.ts's clone-aware
+    // hasFace. Deliberately NOT pushed into registry.registered, which other tests assert on.
+    const BUNDLED_CLONE_FAMILIES = new Set([
+      'carlito',
+      'caladea',
+      'liberation sans',
+      'liberation serif',
+      'liberation mono',
+    ]);
     const hasFaceOf = (registry: FakeRegistry) => (f: string, w: '400' | '700', s: 'normal' | 'italic') =>
-      registry.hasFace(f, w, s);
+      registry.hasFace(f, w, s) || BUNDLED_CLONE_FAMILIES.has(f.trim().toLowerCase());
     const regular = { weight: '400', style: 'normal' } as const;
 
     it('registers embeddable faces under a unique physical family, skips restricted, invalidates without reflow/event', () => {
@@ -383,7 +396,7 @@ describe('DocumentFontController', () => {
       // Both Calibri faces register under ONE document-unique physical family - never the shared
       // logical name "Calibri" (which would let another document render these bytes).
       const phys = resolver.resolveFace('Calibri', regular, hasFace).physicalFamily;
-      expect(phys).toMatch(/^__superdoc_embedded_\d+__\d+_Calibri$/);
+      expect(phys).toMatch(/^__superdoc_embedded_\d+__\d+_\d+_Calibri$/);
       expect(registry.ownedRegistered).toEqual([
         { family: phys, weight: '400', style: 'normal' },
         { family: phys, weight: '700', style: 'normal' },
@@ -409,7 +422,7 @@ describe('DocumentFontController', () => {
       const resolved = resolver.resolveFace('Calibri', regular, hasFace);
       expect(resolved.reason).toBe('registered_face');
       expect(resolved.physicalFamily).not.toBe('Calibri'); // NOT the shared logical name
-      expect(resolved.physicalFamily).toMatch(/^__superdoc_embedded_\d+__\d+_Calibri$/);
+      expect(resolved.physicalFamily).toMatch(/^__superdoc_embedded_\d+__\d+_\d+_Calibri$/);
       // The paint/measure seam swaps the primary to the unique physical family (fallbacks preserved).
       expect(resolver.resolvePhysicalFamilyForFace('Calibri, serif', regular, hasFace)).toBe(
         `${resolved.physicalFamily}, serif`,
@@ -461,7 +474,7 @@ describe('DocumentFontController', () => {
       expect(resolver.resolveFace('Calibri', regular, hasFace).physicalFamily).toBe('Carlito'); // released -> bundled
       const cambria = resolver.resolveFace('Cambria', regular, hasFace);
       expect(cambria.reason).toBe('registered_face');
-      expect(cambria.physicalFamily).toMatch(/^__superdoc_embedded_\d+__\d+_Cambria$/);
+      expect(cambria.physicalFamily).toMatch(/^__superdoc_embedded_\d+__\d+_\d+_Cambria$/);
     });
 
     it('does nothing (no invalidate) when there are no embeddable faces', () => {
@@ -495,5 +508,30 @@ describe('DocumentFontController', () => {
       expect(registry.hasFace(physB, '400', 'normal')).toBe(true); // doc B intact
       expect(docB.resolver.resolveFace('Calibri', regular, hasFace).reason).toBe('registered_face');
     });
+
+    it('mints a fresh physical family across a same-controller document swap (no in-flight name reuse)', () => {
+      // One controller, two documents in sequence with reset() between (the real same-controller swap).
+      // The namespace is fixed per controller and reset() clears the per-family index, so WITHOUT a
+      // per-apply generation the second document would re-mint the first's physical name and alias its
+      // (possibly still in-flight) face on the shared registry. The generation keeps the names distinct.
+      const { controller, resolver, registry } = makeController();
+      const hasFace = hasFaceOf(registry);
+
+      controller.applyEmbeddedFaces([embed({ family: 'Calibri' })]);
+      const physFirst = resolver.resolveFace('Calibri', regular, hasFace).physicalFamily;
+
+      controller.reset(); // document swap: releases the face, clears the index
+      controller.applyEmbeddedFaces([embed({ family: 'Calibri' })]);
+      const physSecond = resolver.resolveFace('Calibri', regular, hasFace).physicalFamily;
+
+      expect(physSecond).not.toBe(physFirst); // generation bumped: never a reused name
+      // Same controller -> same namespace; the GENERATION segment is what differs (not the namespace,
+      // unlike the cross-controller test above). Pin that so a regression to namespace-only uniqueness fails.
+      const namespaceOf = (phys: string) => phys.match(/^(__superdoc_embedded_\d+__)/)?.[1];
+      expect(namespaceOf(physSecond)).toBe(namespaceOf(physFirst));
+      // Only the second document's face is live in the shared registry; the first was released on swap.
+      expect(registry.hasFace(physFirst, '400', 'normal')).toBe(false);
+      expect(registry.hasFace(physSecond, '400', 'normal')).toBe(true);
+    });
   });
 });
diff --git a/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.ts b/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.ts
index f3c1a0b550..f4de192b55 100644
--- a/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.ts
+++ b/packages/super-editor/src/editors/v1/core/presentation-editor/fonts/DocumentFontController.ts
@@ -111,6 +111,13 @@ export class DocumentFontController {
    * one embedded family (e.g. Calibri regular + bold) onto a single physical family. Cleared on release.
    */
   readonly #embeddedPhysical = new Map<string, string>();
+  /**
+   * Per-apply generation, bumped on each {@link applyEmbeddedFaces} that registers a set. Folded into
+   * the physical family name: a document swap clears {@link #embeddedPhysical} (resetting the index), so
+   * without the generation the next document's first embedded family would re-mint the previous one's
+   * physical name and collide on the shared registry's in-flight load/status key.
+   */
+  #embeddedGeneration = 0;
 
   constructor(deps: DocumentFontControllerDeps) {
     this.#resolver = deps.resolver;
@@ -176,7 +183,7 @@ export class DocumentFontController {
   /**
    * Register the document's embedded fonts (from `SuperConverter.getEmbeddedFontFaces`) as first-class
    * registry faces, BEFORE the first layout measure. Each {@link EmbeddedFontFace.embeddable} face is
-   * registered under a DOCUMENT-UNIQUE physical family (e.g. `__superdoc_embedded_3__0_Calibri`), and the
+   * registered under a DOCUMENT-UNIQUE physical family (e.g. `__superdoc_embedded_3__1_0_Calibri`), and the
    * logical family is bound to it in this document's resolver, so the `registered_face` rung renders the
    * document's real font instead of the bundled substitute (Carlito) - with no resolver special-casing.
    * The FontFaceSet is shared per page, so registering under the logical name would let another document
@@ -200,6 +207,9 @@ export class DocumentFontController {
     // here - unlike the user-invoked `fonts.add`, this runs automatically on every document load.
     const registry = this.#getGate()?.resolveRegistry();
     if (!registry) return;
+    // New generation per registering apply, so this document's physical families never reuse the prior
+    // document's names (which would alias the shared registry's in-flight load/status on a swap).
+    this.#embeddedGeneration += 1;
     let registered = false;
     for (const face of faces) {
       if (!face?.embeddable) continue;
@@ -222,12 +232,13 @@ export class DocumentFontController {
   }
 
   /** This document's unique physical family for a logical embedded family, assigned once per family
-   *  (its faces share it). The per-family index guarantees uniqueness even if two names sanitize alike. */
+   *  (its faces share it). The per-apply generation + per-family index keep it unique across BOTH a
+   *  document swap (generation) and names that sanitize alike within one document (index). */
   #physicalFamilyFor(logicalFamily: string): string {
     const key = logicalFamily.trim().toLowerCase();
     let physical = this.#embeddedPhysical.get(key);
     if (!physical) {
-      physical = `${this.#embeddedNamespace}${this.#embeddedPhysical.size}_${sanitizeFamilyToken(logicalFamily)}`;
+      physical = `${this.#embeddedNamespace}${this.#embeddedGeneration}_${this.#embeddedPhysical.size}_${sanitizeFamilyToken(logicalFamily)}`;
       this.#embeddedPhysical.set(key, physical);
     }
     return physical;
diff --git a/packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.js b/packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.js
index 67d2ac1a3b..247b9a3700 100644
--- a/packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.js
+++ b/packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.js
@@ -1008,10 +1008,13 @@ class SuperConverter {
     let styleString = '';
     for (const font of fontsToInclude) {
       const filePath = elements.find((el) => el.attributes.Id === font.attributes['r:id'])?.attributes?.Target;
-      if (!filePath) return;
+      // Skip a font with a missing relationship/binary/deobfuscation rather than aborting the whole
+      // method (one malformed embedded font must not drop every other font's @font-face). Matches the
+      // registry path (getEmbeddedFontFaces), which already `continue`s past the same cases.
+      if (!filePath) continue;
 
       const fontUint8Array = this.fonts[`word/${filePath}`];
-      if (!fontUint8Array?.buffer) return;
+      if (!fontUint8Array?.buffer) continue;
       // Copy the EXACT view bytes into a fresh buffer BEFORE deobfuscating. deobfuscateFont XORs its
       // input IN PLACE; passing `this.fonts[...].buffer` would mutate the shared embedded-font bytes,
       // so the later registry extraction (getEmbeddedFontFaces) would double-XOR and corrupt the face.
@@ -1023,7 +1026,15 @@ class SuperConverter {
       );
 
       const ttfBuffer = deobfuscateFont(fontBuffer, font.attributes['w:fontKey']);
-      if (!ttfBuffer) return;
+      if (!ttfBuffer) continue;
+
+      // Honor the embedding policy here too. The registry path (getEmbeddedFontFaces) skips a face whose
+      // OS/2 fsType forbids embedding (or is unreadable), but this legacy @font-face injection would
+      // otherwise still emit the restricted bytes under the logical family. Reuse the SAME rule
+      // (parseEmbeddingPolicy; a null/unreadable policy is conservatively not embeddable) so the policy
+      // gate has one source of truth; skip just this face rather than aborting the rest.
+      const policy = parseEmbeddingPolicy(ttfBuffer);
+      if (!(policy ? policy.embeddable : false)) continue;
 
       // Convert to a blob and inject @font-face
       const blob = new Blob([ttfBuffer], { type: 'font/ttf' });
diff --git a/packages/super-editor/src/editors/v1/core/super-converter/getEmbeddedFontFaces.test.js b/packages/super-editor/src/editors/v1/core/super-converter/getEmbeddedFontFaces.test.js
index d2c1e6d870..70a4d4435d 100644
--- a/packages/super-editor/src/editors/v1/core/super-converter/getEmbeddedFontFaces.test.js
+++ b/packages/super-editor/src/editors/v1/core/super-converter/getEmbeddedFontFaces.test.js
@@ -181,6 +181,27 @@ describe('SuperConverter.getEmbeddedFontFaces', () => {
     expect(new DataView(calibri.source).getUint32(0)).toBe(0x00010000);
   });
 
+  it('legacy @font-face injection honors the embedding policy (restricted + unreadable excluded)', () => {
+    const converter = makeConverter();
+    const originalCreateObjectURL = URL.createObjectURL;
+    URL.createObjectURL = vi.fn(() => 'blob:mock-font');
+    try {
+      const legacy = converter.getFontFaceImportString();
+      // Embeddable fonts still get an @font-face.
+      expect(legacy.fontsImported).toEqual(expect.arrayContaining(['Calibri', 'Aptos']));
+      expect(legacy.styleString).toContain('Calibri');
+      // Restricted (fsType bit 1) and unreadable (null OS/2 policy) must NOT be injected - the same gate
+      // getEmbeddedFontFaces applies, so the legacy path can't leak restricted bytes under the family.
+      expect(legacy.fontsImported).not.toContain('SecretFont');
+      expect(legacy.fontsImported).not.toContain('CorruptFont');
+      expect(legacy.styleString).not.toContain('SecretFont');
+      expect(legacy.styleString).not.toContain('CorruptFont');
+    } finally {
+      if (originalCreateObjectURL) URL.createObjectURL = originalCreateObjectURL;
+      else delete URL.createObjectURL;
+    }
+  });
+
   it('returns [] when there is no font table or no embedded binaries', () => {
     const empty = new SuperConverter();
     expect(empty.getEmbeddedFontFaces()).toEqual([]);