Merge pull request #3359 from superdoc-dev/caio-pizzol/SD-3179-public-facade-headless-toolbar

feat(types): legacy headless-toolbar public facade entry (SD-3179)

Author: caio-pizzol

docs/architecture/package-boundaries.md

@@ -109,9 +109,9 @@ The `superdoc` package currently exposes the following entries via `package.json
 | `./super-editor` | Yes | Legacy public compatibility surface | `imports-sub-export.ts` | Was effectively public when no other headless path existed. `Editor`, `PresentationEditor`, `getStarterExtensions`, `Extensions`, `SuperToolbar`, `SuperConverter`, `DocxZipper` and most of the surface are now exported from `superdoc` itself. Kept exported, not advertised, migration target is `superdoc`. See Decision 1. |
 | `./ui` | Yes | Public subpath | `imports-ui.ts` | Stays |
 | `./ui/react` | Yes | Public subpath | `imports-ui-react.ts` | Stays |
-| `./headless-toolbar` | Yes | Public subpath | `imports-headless-toolbar.ts` | Stays |
-| `./headless-toolbar/react` | Yes | Public subpath | `imports-headless-toolbar-react.ts` | Stays |
-| `./headless-toolbar/vue` | Yes | Public subpath | `imports-headless-toolbar-vue.ts` | Stays |
+| `./headless-toolbar` | Yes | Legacy public compatibility surface | `imports-headless-toolbar.ts` | Kept exported, not advertised. New custom UI integrations should use `superdoc/ui`. See Decision 4. |
+| `./headless-toolbar/react` | Yes | Legacy public compatibility surface | `imports-headless-toolbar-react.ts` | Framework helper for the legacy headless toolbar. Migration target is `superdoc/ui/react`. See Decision 4. |
+| `./headless-toolbar/vue` | Yes | Legacy public compatibility surface | `imports-headless-toolbar-vue.ts` | Framework helper for the legacy headless toolbar. New work that needs a Vue UI controller should track that as a separate decision; the legacy entry is kept compiling. See Decision 4. |
 | `./converter` | Yes (SD-2953) | Legacy public compatibility surface | `imports-converter.ts` | DOCX conversion is also reachable through `Editor.open` / `Editor.loadXmlData` / `SuperConverter` exported from `superdoc`. Kept exported, not advertised, migration target is `superdoc`. Types added in SD-2953 to satisfy strict-mode consumers. |
 | `./docx-zipper` | Yes (SD-2953) | Legacy public compatibility surface | `imports-docx-zipper.ts` | `DocxZipper` is exported from `superdoc`. Kept exported, not advertised, migration target is `superdoc`. Types added in SD-2953. |
 | `./file-zipper` | Yes (SD-2953) | Legacy public compatibility surface | `imports-file-zipper.ts` | `createZip` is exported from `superdoc`. Kept exported, not advertised, migration target is `superdoc`. Types added in SD-2953. |
@@ -182,7 +182,20 @@ The relocation pattern is what `superdoc` currently uses for several internal-bu
 
 **Context.** `./converter`, `./docx-zipper`, `./file-zipper` are exported subpaths whose functionality (DOCX conversion, zipping) is also reachable through `superdoc`'s main entry: `Editor.open`, `Editor.loadXmlData`, `SuperConverter`, `DocxZipper`, `createZip` are all exported from `superdoc`.
 
-**Decision.** All three subpaths are classified as **legacy public compatibility surface**. Migration target is `superdoc` itself (the symbols already exist there). We keep them exported, stop advertising them, and point new use at `superdoc`. SD-2953 added `types` fields and matrix fixtures so strict-mode consumers no longer hit TS7016; the export-coverage audit (`check-export-coverage.cjs`) now enforces that every `package.json` exports entry carries types, an asset classification, or a documented runtime-only allowlist entry.
+`./headless-toolbar` is the same shape with a different migration target: the next-generation custom UI story is `superdoc/ui` and `superdoc/ui/react` (the typed UI controller). Existing consumers of the headless-toolbar surface keep compiling; new integrations should use the UI controller entries.
+
+**Decision.** `./converter`, `./docx-zipper`, `./file-zipper`, and the `./headless-toolbar` family (`./headless-toolbar`, `./headless-toolbar/react`, `./headless-toolbar/vue`) are classified as **legacy public compatibility surface**.
+
+| Subpath | Migration target |
+| --- | --- |
+| `./converter` | `SuperConverter` from `superdoc` |
+| `./docx-zipper` | `DocxZipper` from `superdoc` |
+| `./file-zipper` | `createZip` from `superdoc` |
+| `./headless-toolbar` | `superdoc/ui` |
+| `./headless-toolbar/react` | `superdoc/ui/react` |
+| `./headless-toolbar/vue` | Track a Vue UI controller as a separate decision; the legacy entry is kept compiling. |
+
+We keep them exported, stop advertising them, and point new use at the migration target. SD-2953 added `types` fields and matrix fixtures so strict-mode consumers no longer hit TS7016; the export-coverage audit (`check-export-coverage.cjs`) now enforces that every `package.json` exports entry carries types, an asset classification, or a documented runtime-only allowlist entry. SD-3179 lands the source-side facade for `./headless-toolbar` under `packages/superdoc/src/public/legacy/` and extends SD-3176's no-growth snapshot list to cover `./headless-toolbar`, `./headless-toolbar/react`, and `./headless-toolbar/vue` so these subpaths cannot expand silently.
 
 ## Deliverables
 

packages/superdoc/scripts/ensure-types.cjs

@@ -140,6 +140,12 @@ const cjsDeclarationShims = [
     source: path.join(distRoot, 'superdoc/src/public/index.d.ts'),
     target: './index.js',
   },
+  // SD-3179: legacy headless-toolbar facade entry.
+  {
+    file: path.join(distRoot, 'superdoc/src/public/legacy/headless-toolbar.d.cts'),
+    source: path.join(distRoot, 'superdoc/src/public/legacy/headless-toolbar.d.ts'),
+    target: './headless-toolbar.js',
+  },
 ];
 
 function isValidIdentifier(name) {

packages/superdoc/scripts/verify-public-facade-emit.cjs

@@ -1,21 +1,22 @@
 #!/usr/bin/env node
 /**
- * SD-3178 (Phase 3 of SD-3175): verify the explicit public facade emits a
- * declaration tree that is safe to ship.
+ * SD-3178 (Phase 3 of SD-3175): verify the explicit public facade entries
+ * emit declaration trees that are safe to ship.
  *
- * Runs as a postbuild step under `packages/superdoc/`. Loads the emitted
- * `dist/superdoc/src/public/index.d.ts` and `index.d.cts` with the
- * TypeScript compiler API and asserts:
+ * Runs as a postbuild step under `packages/superdoc/`. For each entry in
+ * the `FACADE_ENTRIES` config below, loads the emitted `.d.ts` and `.d.cts`
+ * with the TypeScript compiler API and asserts:
  *
  *   1. The expected symbol set is exported from each declaration file.
  *   2. The ESM and CJS declarations agree on the exported names.
- *   3. The command signature surface survives the facade emit. This is
- *      the SD-2965 regression vector: specific command signatures getting
- *      dropped or failing to flow through the facade. `EditorCommands` is
- *      `CoreCommands & ExtensionCommands & AllCommandSignatures & Record<string, AnyCommand>`,
- *      so the trailing `Record<string, AnyCommand>` makes any indexer
- *      lookup resolve even when the specific signatures are missing.
- *      The probe asserts the RETURN TYPE of two commands (`setBold`,
+ *   3. (Root entry only) The command signature surface survives the
+ *      facade emit. This is the SD-2965 regression vector: specific
+ *      command signatures getting dropped or failing to flow through the
+ *      facade. `EditorCommands` is `CoreCommands & ExtensionCommands &
+ *      AllCommandSignatures & Record<string, AnyCommand>`, so the
+ *      trailing `Record<string, AnyCommand>` makes any indexer lookup
+ *      resolve even when the specific signatures are missing. The probe
+ *      asserts the RETURN TYPE of two commands (`setBold`,
  *      `insertComment`) is `boolean`, not the `AnyCommand` fallback's
  *      `unknown`. Two commands from two signature sources (formatting +
  *      comments) catch partial drops a single-command probe would miss.
@@ -30,6 +31,14 @@
  *      not see the workspace specifier. Later SD-3178 follow-ups reduce
  *      how much the facade depends on that broader declaration graph.
  *
+ * Adding a new facade file:
+ *   - Create `packages/superdoc/src/public/<name>.ts` with named exports.
+ *   - Wire it into `vite.config.js` (`rollupOptions.input`) and the CJS
+ *     shim list in `scripts/ensure-types.cjs`.
+ *   - Append a `FACADE_ENTRIES` entry below with the expected symbol set.
+ *   - If the new entry re-exports `EditorCommands`, set
+ *     `runsCommandSignatureProbe: true`.
+ *
  * Exits non-zero on any failure. Designed to fail loud and early.
  */
 'use strict';
@@ -39,10 +48,7 @@ const path = require('node:path');
 
 const repoRoot = path.resolve(__dirname, '..', '..', '..');
 const distRoot = path.resolve(__dirname, '..', 'dist');
-const FACADE_ESM = path.join(distRoot, 'superdoc', 'src', 'public', 'index.d.ts');
-const FACADE_CJS = path.join(distRoot, 'superdoc', 'src', 'public', 'index.d.cts');
-
-const EXPECTED_NAMES = ['Config', 'Editor', 'EditorCommands', 'SuperDoc'].sort();
+const PUBLIC_DIST = path.join(distRoot, 'superdoc', 'src', 'public');
 
 let ts;
 try {
@@ -52,6 +58,47 @@ try {
   process.exit(1);
 }
 
+// AIDEV-NOTE: Adding or removing an export from a facade file in
+// `packages/superdoc/src/public/**` must update the matching
+// `expectedNames` list below in the same PR. Skipping that step fails
+// this gate. Link the PR to SD-3175 (path-as-contract umbrella) for
+// reviewer sign-off when growth is intentional.
+const FACADE_ENTRIES = [
+  {
+    name: 'root (./index)',
+    esm: path.join(PUBLIC_DIST, 'index.d.ts'),
+    cjs: path.join(PUBLIC_DIST, 'index.d.cts'),
+    expectedNames: ['Config', 'Editor', 'EditorCommands', 'SuperDoc'],
+    runsCommandSignatureProbe: true,
+    ticket: 'SD-3178',
+  },
+  {
+    name: 'legacy/headless-toolbar',
+    esm: path.join(PUBLIC_DIST, 'legacy', 'headless-toolbar.d.ts'),
+    cjs: path.join(PUBLIC_DIST, 'legacy', 'headless-toolbar.d.cts'),
+    expectedNames: [
+      'CreateHeadlessToolbarOptions',
+      'HeadlessToolbarController',
+      'HeadlessToolbarSuperdocHost',
+      'HeadlessToolbarSurface',
+      'PublicToolbarItemId',
+      'ToolbarCommandState',
+      'ToolbarCommandStates',
+      'ToolbarContext',
+      'ToolbarExecuteFn',
+      'ToolbarPayloadMap',
+      'ToolbarSnapshot',
+      'ToolbarTarget',
+      'ToolbarValueMap',
+      'createHeadlessToolbar',
+      'headlessToolbarConstants',
+      'headlessToolbarHelpers',
+    ],
+    runsCommandSignatureProbe: false,
+    ticket: 'SD-3179',
+  },
+];
+
 function loadFile(file) {
   if (!fs.existsSync(file)) {
     console.error(`[verify-public-facade-emit] missing facade declaration: ${file}`);
@@ -75,48 +122,39 @@ function listExportedNames(file) {
   const checker = program.getTypeChecker();
   const src = program.getSourceFile(file);
   const symbol = checker.getSymbolAtLocation(src) ?? (src && src.symbol);
-  if (!symbol) {
-    return { names: [], program, checker };
-  }
-  return {
-    names: [...new Set(checker.getExportsOfModule(symbol).map((s) => s.getName()))].sort(),
-    program,
-    checker,
-  };
+  if (!symbol) return [];
+  return [...new Set(checker.getExportsOfModule(symbol).map((s) => s.getName()))].sort();
 }
 
-let failed = false;
-
-// (1) Symbol set.
-const esm = listExportedNames(FACADE_ESM);
-if (JSON.stringify(esm.names) !== JSON.stringify(EXPECTED_NAMES)) {
-  console.error(`[verify-public-facade-emit] ESM facade exports drifted.`);
-  console.error('  expected: ' + EXPECTED_NAMES.join(', '));
-  console.error('  actual:   ' + esm.names.join(', '));
-  console.error('  If this addition is intentional, update EXPECTED_NAMES in this script and link');
-  console.error('  the PR to SD-3175 (path-as-contract umbrella) for reviewer sign-off.');
-  failed = true;
+function checkSymbolSet(entry) {
+  const expected = [...entry.expectedNames].sort();
+  const actual = listExportedNames(entry.esm);
+  if (JSON.stringify(actual) === JSON.stringify(expected)) {
+    return { ok: true, actual };
+  }
+  console.error(`[verify-public-facade-emit] ${entry.name}: facade exports drifted.`);
+  console.error('  expected: ' + expected.join(', '));
+  console.error('  actual:   ' + actual.join(', '));
+  console.error(`  If this addition is intentional, update FACADE_ENTRIES["${entry.name}"].expectedNames in this script and link`);
+  console.error(`  the PR to ${entry.ticket} / SD-3175 (path-as-contract umbrella) for reviewer sign-off.`);
+  return { ok: false, actual };
 }
 
-// (2) ESM/CJS parity.
-const cjs = listExportedNames(FACADE_CJS);
-if (JSON.stringify(esm.names) !== JSON.stringify(cjs.names)) {
-  const importOnly = esm.names.filter((n) => !cjs.names.includes(n));
-  const requireOnly = cjs.names.filter((n) => !esm.names.includes(n));
-  console.error('[verify-public-facade-emit] ESM/CJS facade declarations disagree on exports.');
+function checkEsmCjsParity(entry, esmNames) {
+  const cjsNames = listExportedNames(entry.cjs);
+  if (JSON.stringify(esmNames) === JSON.stringify(cjsNames)) return true;
+  const importOnly = esmNames.filter((n) => !cjsNames.includes(n));
+  const requireOnly = cjsNames.filter((n) => !esmNames.includes(n));
+  console.error(`[verify-public-facade-emit] ${entry.name}: ESM/CJS facade declarations disagree on exports.`);
   if (importOnly.length) console.error('  ESM-only:  ' + importOnly.join(', '));
   if (requireOnly.length) console.error('  CJS-only:  ' + requireOnly.join(', '));
   console.error('  Fix the CJS shim generator (packages/superdoc/scripts/ensure-types.cjs).');
-  failed = true;
+  return false;
 }
 
-// (3) Command signature survival: assert two commands return `boolean`,
-//     not the `AnyCommand` fallback. See header for why a bare resolution
-//     check is not enough (the `Record<string, AnyCommand>` intersection
-//     always satisfies the indexer).
-{
+function checkCommandSignatureProbe(entry) {
   const probe = `
-    import type { EditorCommands } from ${JSON.stringify(FACADE_ESM)};
+    import type { EditorCommands } from ${JSON.stringify(entry.esm)};
     type ReturnsBoolean<F> = F extends (...args: any[]) => boolean ? true : false;
     // Direct assignment of literal \`true\` to the conditional result. If the
     // signature is missing and the indexer falls back to AnyCommand, the
@@ -150,25 +188,22 @@ if (JSON.stringify(esm.names) !== JSON.stringify(cjs.names)) {
       ...program.getSemanticDiagnostics(),
       ...program.getDeclarationDiagnostics(),
     ];
-    if (diagnostics.length > 0) {
-      console.error('[verify-public-facade-emit] command signature probe failed.');
-      console.error('  A command (setBold or insertComment) does not return `boolean` through the facade.');
-      console.error('  This is the SD-2965 regression vector: specific command signatures were dropped or failed to flow through the facade, and EditorCommands fell back to the `AnyCommand` indexer.');
-      for (const d of diagnostics) {
-        const msg = typeof d.messageText === 'string'
-          ? d.messageText
-          : ts.flattenDiagnosticMessageText(d.messageText, '\n');
-        console.error('  - ' + msg);
-      }
-      failed = true;
+    if (diagnostics.length === 0) return true;
+    console.error(`[verify-public-facade-emit] ${entry.name}: command signature probe failed.`);
+    console.error('  A command (setBold or insertComment) does not return `boolean` through the facade.');
+    console.error('  This is the SD-2965 regression vector: specific command signatures were dropped or failed to flow through the facade, and EditorCommands fell back to the `AnyCommand` indexer.');
+    for (const d of diagnostics) {
+      const msg = typeof d.messageText === 'string'
+        ? d.messageText
+        : ts.flattenDiagnosticMessageText(d.messageText, '\n');
+      console.error('  - ' + msg);
     }
+    return false;
   } finally {
     try { fs.unlinkSync(probePath); } catch (_) {}
   }
 }
 
-// (4) No internal leaks in emitted code (strip JSDoc/line comments first so
-// that comments referencing `@superdoc/super-editor` in prose are not flagged).
 function stripComments(source) {
   return source
     .replace(/\/\*[\s\S]*?\*\//g, '')
@@ -181,16 +216,38 @@ const LEAK_PATTERNS = [
   { name: 'absolute source path', re: /['"][\/\\][^'"\n]*\/(packages|node_modules)\//g },
 ];
 
-for (const file of [FACADE_ESM, FACADE_CJS]) {
-  const code = stripComments(loadFile(file));
-  for (const pattern of LEAK_PATTERNS) {
-    const matches = code.match(pattern.re);
-    if (matches && matches.length > 0) {
-      console.error(`[verify-public-facade-emit] leak in ${path.relative(repoRoot, file)}:`);
-      console.error(`  ${pattern.name}: ${matches.slice(0, 5).join(', ')}`);
-      failed = true;
+function checkLeaks(entry) {
+  let ok = true;
+  for (const file of [entry.esm, entry.cjs]) {
+    const code = stripComments(loadFile(file));
+    for (const pattern of LEAK_PATTERNS) {
+      const matches = code.match(pattern.re);
+      if (matches && matches.length > 0) {
+        console.error(`[verify-public-facade-emit] ${entry.name}: leak in ${path.relative(repoRoot, file)}:`);
+        console.error(`  ${pattern.name}: ${matches.slice(0, 5).join(', ')}`);
+        ok = false;
+      }
     }
   }
+  return ok;
+}
+
+let failed = false;
+const summaryLines = [];
+
+for (const entry of FACADE_ENTRIES) {
+  const symbolResult = checkSymbolSet(entry);
+  if (!symbolResult.ok) failed = true;
+
+  if (!checkEsmCjsParity(entry, symbolResult.actual)) failed = true;
+
+  if (entry.runsCommandSignatureProbe && !checkCommandSignatureProbe(entry)) {
+    failed = true;
+  }
+
+  if (!checkLeaks(entry)) failed = true;
+
+  summaryLines.push(`${entry.name}: ${symbolResult.actual.length} exports`);
 }
 
 if (failed) {
@@ -199,4 +256,4 @@ if (failed) {
   process.exit(1);
 }
 
-console.log(`[verify-public-facade-emit] OK. Facade emits cleanly: ${esm.names.length} exports, ESM/CJS in parity, command signatures survive.`);
+console.log(`[verify-public-facade-emit] OK. Facade emits cleanly across ${FACADE_ENTRIES.length} entries (${summaryLines.join('; ')}).`);

packages/superdoc/src/public/legacy/headless-toolbar.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import {
+  createHeadlessToolbar,
+  headlessToolbarConstants,
+  headlessToolbarHelpers,
+} from './headless-toolbar.js';
+
+/**
+ * Smoke test for the legacy public facade headless-toolbar entry (SD-3179).
+ * The three runtime re-exports need coverage so the facade file does not
+ * show 0% on the unit-test coverage report. Declaration-side validation
+ * (symbol set, ESM/CJS parity, leak grep) lives in
+ * `packages/superdoc/scripts/verify-public-facade-emit.cjs`.
+ */
+describe('public facade (legacy/headless-toolbar)', () => {
+  it('re-exports createHeadlessToolbar as a function', () => {
+    expect(typeof createHeadlessToolbar).toBe('function');
+  });
+
+  it('re-exports headlessToolbarConstants as an object', () => {
+    expect(headlessToolbarConstants).toBeDefined();
+    expect(typeof headlessToolbarConstants).toBe('object');
+  });
+
+  it('re-exports headlessToolbarHelpers as an object', () => {
+    expect(headlessToolbarHelpers).toBeDefined();
+    expect(typeof headlessToolbarHelpers).toBe('object');
+  });
+});