fix(superdoc): make Document API and layout contract types resolvable for consumers (SD-2842) (#3022)

* fix(superdoc): make Document API and layout contract types resolvable for consumers (SD-2842)

Three changes that, together, eliminate the remaining type-collapse class:

1. Add the Document API surface that customers reach for to the public re-export list. DocumentApi, BlocksListResult and BookmarkInfo are re-exported from super-editor; superdoc's JSDoc typedef block adds the matching entries so `import type { DocumentApi } from 'superdoc'` resolves to the real interface. Previously these names triggered TS2305 from a strict-mode consumer because they were not on the flat re-export list, even though `editor.doc: DocumentApi` worked through the existing relocation pipeline.

2. Copy hand-written `.d.ts` files from super-editor source into dist before the rewrite passes run. The dts plugin only generates declarations from `.ts`/`.js` and silently skips standalone `.d.ts` files, so paths like `core/commands/core-command-map.d.ts` (used by the command-map type augmentation) were missing in dist. That broke the EditorCommands and CanObject types, which compiled against a missing module reference and fell through to any.

3. Extend the SD-2815 relocation pattern to @superdoc/contracts. Layout, LayoutPage, FlowBlock and friends now emit into superdoc's published dist, the bare specifier in emitted declarations rewrites to a relative path the consumer can resolve, and the package no longer appears in the internal shim file. Same pattern as document-api: tsconfig include, vite-plugin-dts include, ensure-types rewrite plus shim-skip list.

Verified via a fresh strict-mode consumer (skipLibCheck:false, strict:true) importing 18 representative public types and asserting via @ts-expect-error that none collapse to any. Before: 3 missing exports, 5 collapses. After: zero of either. Positive test confirms `editor.doc.blocks.list()` returns a real BlocksListResult and FlowBlock is a real union with discriminant.

* fix(superdoc): relocate layout/painter types and add full public-surface typecheck (SD-2842)

Generalizes the relocation pattern introduced for `@superdoc/document-api` and `@superdoc/contracts` so it scales: a small `RELOCATION_RULES` table in the postbuild script drives both the rewrite logic and the shim-skip predicate. Adds two more entries that close the remaining type leaks on the public surface: `@superdoc/layout-bridge` (PositionHit) and `@superdoc/painter-dom` (PaintSnapshot, LayoutMode). Their declarations now emit into `dist/layout-engine/...`, the bare specifiers in published `.d.ts` rewrite to local relative paths, and the internal shim file no longer carries blocks for these packages.

Adds a permanent `tests/consumer-typecheck/src/all-public-types.ts` test that exercises every public type mined from `superdoc/src/index.js`'s `@typedef` block (105 types). Each type passes through an `AssertNotAny<T>` check that resolves to `never` when the type is `any`, so the assertion fails to compile if a regression collapses one of them. Two matrix scenarios (bundler + node16) wire it as `mustPass: true`. Together with the SD-2832 audit gate, this closes the loop: the audit catches private specifiers in declarations; this test catches when a private type is removed but the consumer-facing alias still resolves to `any`.

The new strict types surfaced six pre-existing bugs in template-builder where the previous `any`-typed editor.commands API silently allowed wrong arguments. Three call sites passed `id: string | number` to commands that take `string` (coerced via `String(id)`). Two call sites passed a `text` field to `insertStructuredContentBlock` that the runtime ignores (block insert uses `html`/`json`/selection content, not `text`). One call site passed a loosely-typed `presetContent.json` to a parameter that requires a real `ProseMirrorJSON` (cast at the boundary). All six were silent failures before; the strict types make them visible.

Verified with the full repo type-check, the consumer matrix (14 scenarios, all green), superdoc unit tests (931 tests, all pass), super-editor unit tests (12,064 tests, all pass), and downstream package builds (react type-check, template-builder build, both clean).

* test(consumer-typecheck): assert shim-leak regression net + add editor.doc smoke (SD-2842)

Two small additions strengthening the regression net around the type relocation work.

The postbuild script now asserts at the end of the run that no relocated package (currently `@superdoc/document-api`, `@superdoc/contracts`, `@superdoc/layout-bridge`, `@superdoc/painter-dom`) appears in `_internal-shims.d.ts`. If a future change breaks the include glob, the rewrite rule, or the shim-skip predicate for one of these packages, the build fails with a clear message pointing at where to look. Runs every time someone packs, so the regression cannot land silently.

Adds an end-to-end smoke test on the runtime entry point: `editor.doc` is typed `DocumentApi` (not any), `editor.doc.blocks.list()` returns a real `BlocksListResult`, calling a method that does not exist on the API is rejected at compile time, and passing the wrong shape to `doc.bookmarks.get(...)` fails type-checking. The flat all-public-types test catches type-level regressions; this catches getter-level regressions where a named export still resolves but the live API surface is typed loosely.

Matrix is now 15/15 required (was 14/14).

* test(consumer-typecheck): use selection-based track-changes variants in customer scenario (SD-2842)

The `customer-scenario.ts` test was calling `acceptTrackedChange()` and `rejectTrackedChange()` with no arguments. Both commands take a required `TrackedChangeOptions` payload at runtime (the runtime destructures `{ trackedChange }` from the first arg), so this was a silent crash waiting to happen, allowed only because the previous `EditorCommands` type was `any`. The new strict types catch it at compile time.

Switched to the `acceptTrackedChangeBySelection` / `rejectTrackedChangeOnSelection` variants, which need no arguments and are what consumer code typically reaches for in toolbar / context-menu flows.

* test(template-builder): drop assertion of no-op text fallback for block insert (SD-2842)

The previous test asserted that a `text: defaultValue` field was passed to `insertStructuredContentBlock`, but `StructuredContentBlockInsert` does not accept `text` and the runtime never used it. The block-insert API takes its content from `html`, `json`, or the current selection. The mock-based test had been passing because it only verified the call argument, not the visible result; a real customer using this code path saw an empty block regardless of `defaultValue`.

The strict types now reject the unknown property, so the call site no longer passes it. Updated the test to assert the new (and only honored) shape: no `text` field on a block-insert call without presetContent. The test name now describes what is actually checked.

Inline insertion is unaffected; `StructuredContentInlineInsert` does accept `text`.

Author: caio-pizzol

packages/super-editor/src/index.ts

@@ -28,6 +28,8 @@ export type {
   TextTarget,
   TextSegment,
   EntityAddress,
+  BlocksListResult,
+  BookmarkInfo,
 } from '@superdoc/document-api';
 
 // Selection handle types

packages/superdoc/scripts/ensure-types.cjs

@@ -6,6 +6,46 @@ const path = require('node:path');
 // Verify that vite-plugin-dts generated the expected type entry points.
 // Path aliases are resolved by vite-plugin-dts via tsconfig.json paths.
 const distRoot = path.resolve(__dirname, '..', 'dist');
+const repoRoot = path.resolve(__dirname, '..', '..', '..');
+
+// SD-2842: vite-plugin-dts skips hand-written `.d.ts` files in its include
+// glob (it only emits declarations from `.ts`/`.js`). When a file like
+// `core-command-map.d.ts` is referenced via a relative import from another
+// emitted `.d.ts`, the consumer hits an unresolved-module error. Copy
+// every hand-written `.d.ts` from the source trees we publish into the
+// matching dist location so those imports resolve.
+function copyHandwrittenDtsFiles(srcDir, destDir) {
+  let copied = 0;
+  function walk(currentSrc, currentDest) {
+    if (!fs.existsSync(currentSrc)) return;
+    for (const entry of fs.readdirSync(currentSrc, { withFileTypes: true })) {
+      if (entry.name === 'node_modules' || entry.name === '__tests__' || entry.name === 'tests') continue;
+      const srcPath = path.join(currentSrc, entry.name);
+      const destPath = path.join(currentDest, entry.name);
+      if (entry.isDirectory()) {
+        walk(srcPath, destPath);
+        continue;
+      }
+      if (!entry.name.endsWith('.d.ts')) continue;
+      // Skip if the dist already has this file (vite-plugin-dts may have
+      // generated its own version from a co-located .ts file)
+      if (fs.existsSync(destPath)) continue;
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.copyFileSync(srcPath, destPath);
+      copied++;
+    }
+  }
+  walk(srcDir, destDir);
+  return copied;
+}
+
+const handwrittenCopiedSuperEditor = copyHandwrittenDtsFiles(
+  path.join(repoRoot, 'packages/super-editor/src'),
+  path.join(distRoot, 'super-editor/src'),
+);
+if (handwrittenCopiedSuperEditor > 0) {
+  console.log(`[ensure-types] ✓ Copied ${handwrittenCopiedSuperEditor} hand-written .d.ts files from super-editor/src`);
+}
 
 const requiredEntryPoints = [
   'superdoc/src/index.d.ts',
@@ -124,6 +164,40 @@ function rewriteDocApiPaths(fileContent, filePath) {
   });
 }
 
+// SD-2842: relocate workspace packages whose types appear on the
+// public surface. Same idea as the document-api rewrite above: emit
+// their declarations into superdoc's dist (via vite-plugin-dts include)
+// and redirect bare specifiers in emitted .d.ts files to relative
+// paths the consumer can resolve.
+const RELOCATION_RULES = [
+  { pkg: '@superdoc/contracts',     distEntry: 'layout-engine/contracts/src/index.d.ts' },
+  { pkg: '@superdoc/layout-bridge', distEntry: 'layout-engine/layout-bridge/src/index.d.ts' },
+  { pkg: '@superdoc/painter-dom',   distEntry: 'layout-engine/painters/dom/src/index.d.ts' },
+];
+
+function makeRelocationRewriter({ pkg, distEntry }) {
+  // Match the package name with optional subpath, e.g. `@superdoc/contracts` or
+  // `@superdoc/contracts/engines/tabs.js`. Anchored to either side of the
+  // package segment so `@superdoc/contracts-something` is not matched.
+  const escaped = pkg.replace(/\//g, '\\/');
+  const re = new RegExp(`(['"])${escaped}(\\/[^'"]+)?\\1`, 'g');
+  return (fileContent, filePath) => {
+    return fileContent.replace(re, (_match, quote, subpath = '') => {
+      const target = path.join(distRoot, distEntry);
+      let rel = path.relative(path.dirname(filePath), target).split(path.sep).join('/');
+      if (!rel.startsWith('.')) rel = './' + rel;
+      rel = rel.replace(/\.d\.ts$/, '.js');
+      if (subpath) rel = rel.replace(/\/index\.js$/, subpath);
+      return `${quote}${rel}${quote}`;
+    });
+  };
+}
+
+const RELOCATION_REWRITERS = RELOCATION_RULES.map((rule) => ({
+  pkg: rule.pkg,
+  rewrite: makeRelocationRewriter(rule),
+}));
+
 const dtsFiles = findDtsFiles(distRoot);
 for (const filePath of dtsFiles) {
   let fileContent = fs.readFileSync(filePath, 'utf8');
@@ -139,6 +213,17 @@ for (const filePath of dtsFiles) {
     totalReplacements++;
   }
 
+  // SD-2842: apply each relocation rewriter in turn. Each one redirects
+  // its own private-package specifier to a relative path in the local dist.
+  for (const { rewrite } of RELOCATION_REWRITERS) {
+    const before = fileContent;
+    fileContent = rewrite(fileContent, filePath);
+    if (fileContent !== before) {
+      changed = true;
+      totalReplacements++;
+    }
+  }
+
   // Fix pnpm node_modules paths → bare specifiers
   fileContent = fileContent.replace(PNPM_PATH_RE, (match, quote, _fullPath, packageName) => {
     changed = true;
@@ -240,7 +325,7 @@ for (const filePath of dtsFiles) {
     const mod = m[2];
 
     // Skip relative imports and already-handled packages
-    if (mod.startsWith('.') || mod.startsWith('@superdoc/common') || mod.startsWith('@superdoc/super-editor') || mod.startsWith('@superdoc/document-api')) continue;
+    if (mod.startsWith('.') || mod.startsWith('@superdoc/common') || mod.startsWith('@superdoc/super-editor') || mod.startsWith('@superdoc/document-api') || RELOCATION_RULES.some((r) => mod === r.pkg || mod.startsWith(r.pkg + '/'))) continue;
 
     if (mod.startsWith('@superdoc/')) {
       if (!workspaceImports.has(mod)) workspaceImports.set(mod, new Set());
@@ -253,7 +338,7 @@ for (const filePath of dtsFiles) {
   const dynamicImports = fileContent.matchAll(/import\(['"]([^'"]+)['"]\)\.(\w+)/g);
   for (const m of dynamicImports) {
     const mod = m[1];
-    if (mod.startsWith('.') || mod.startsWith('@superdoc/common') || mod.startsWith('@superdoc/super-editor') || mod.startsWith('@superdoc/document-api')) continue;
+    if (mod.startsWith('.') || mod.startsWith('@superdoc/common') || mod.startsWith('@superdoc/super-editor') || mod.startsWith('@superdoc/document-api') || RELOCATION_RULES.some((r) => mod === r.pkg || mod.startsWith(r.pkg + '/'))) continue;
 
     if (mod.startsWith('@superdoc/')) {
       if (!workspaceImports.has(mod)) workspaceImports.set(mod, new Set());
@@ -268,7 +353,7 @@ for (const filePath of dtsFiles) {
     // Skip @superdoc/super-editor (consumer-facing, not internal)
     // Skip @superdoc/common root module (inlined separately), but allow subpath
     // imports like @superdoc/common/components/BasicUpload.vue to be shimmed
-    if (mod === '@superdoc/common' || mod.startsWith('@superdoc/super-editor') || mod.startsWith('@superdoc/document-api')) continue;
+    if (mod === '@superdoc/common' || mod.startsWith('@superdoc/super-editor') || mod.startsWith('@superdoc/document-api') || RELOCATION_RULES.some((r) => mod === r.pkg || mod.startsWith(r.pkg + '/'))) continue;
     if (!workspaceImports.has(mod)) workspaceImports.set(mod, new Set());
   }
 }
@@ -331,4 +416,20 @@ for (const entry of requiredEntryPoints) {
 }
 
 console.log(`[ensure-types] ✓ Generated ambient shims for ${wsCount} workspace modules`);
+
+// SD-2842 regression net: assert that no relocated package leaked back
+// into the shim file. If one shows up, a future change broke the
+// rewrite or include for that package and customers would see `any`
+// for those types again.
+const shimContent = fs.readFileSync(shimPath, 'utf8');
+const SHIM_FORBIDDEN = ['@superdoc/document-api', ...RELOCATION_RULES.map((r) => r.pkg)];
+for (const pkg of SHIM_FORBIDDEN) {
+  const re = new RegExp(`declare module '${pkg.replace(/\//g, '\\/')}(\\/[^']+)?'`);
+  if (re.test(shimContent)) {
+    console.error(`[ensure-types] ✗ ${pkg} appears in _internal-shims.d.ts. Its types should resolve via the relocation rewrite, not via an ambient any shim. Investigate the include glob, the rewrite rule, and the shim-skip predicate for this package.`);
+    process.exit(1);
+  }
+}
+console.log(`[ensure-types] ✓ Verified ${SHIM_FORBIDDEN.length} relocated packages do not appear in shim file`);
+
 console.log('[ensure-types] ✓ Verified type entry points');

packages/superdoc/src/index.js

@@ -116,6 +116,9 @@ import { getSchemaIntrospection } from './helpers/schema-introspection.js';
  * @typedef {import('@superdoc/super-editor').TextAddress} TextAddress
  * @typedef {import('@superdoc/super-editor').TextSegment} TextSegment
  * @typedef {import('@superdoc/super-editor').EntityAddress} EntityAddress
+ * @typedef {import('@superdoc/super-editor').DocumentApi} DocumentApi
+ * @typedef {import('@superdoc/super-editor').BlocksListResult} BlocksListResult
+ * @typedef {import('@superdoc/super-editor').BookmarkInfo} BookmarkInfo
  * @typedef {import('@superdoc/super-editor').LayoutUpdatePayload} LayoutUpdatePayload
  * @typedef {import('@superdoc/super-editor').CoreCommandMap} CoreCommandMap
  * @deprecated Editor commands will be removed in a future version. Use the Document API instead.

packages/superdoc/tsconfig.json

@@ -22,5 +22,12 @@
       "@shared/*": ["shared/*"]
     }
   },
-  "include": ["src", "../super-editor/src", "../document-api/src"]
+  "include": [
+    "src",
+    "../super-editor/src",
+    "../document-api/src",
+    "../layout-engine/contracts/src",
+    "../layout-engine/layout-bridge/src",
+    "../layout-engine/painters/dom/src"
+  ]
 }

packages/superdoc/vite.config.js

@@ -121,7 +121,18 @@ export default defineConfig(({ mode, command }) => {
       // generates for every unshipped `@superdoc/*` package. Without
       // this, packed consumers see `any` for those public types and
       // the new re-export surface adds no actual checking.
-      include: ['src/**/*', '../super-editor/src/**/*', '../document-api/src/**/*'],
+      include: [
+        'src/**/*',
+        '../super-editor/src/**/*',
+        '../document-api/src/**/*',
+        // SD-2842: relocate workspace packages whose types appear on the
+        // public surface so they emit into superdoc's dist and the
+        // rewrite step in ensure-types can redirect bare specifiers to
+        // local relative paths. Same pattern as @superdoc/document-api.
+        '../layout-engine/contracts/src/**/*',
+        '../layout-engine/layout-bridge/src/**/*',
+        '../layout-engine/painters/dom/src/**/*',
+      ],
       outDir: 'dist',
       // vite-plugin-dts still gathers diagnostics for this mixed JS/Vue source
       // tree, but we do not use this build as the authoritative type-check gate.

packages/template-builder/src/index.tsx

@@ -1,5 +1,5 @@
 import { useRef, useState, useEffect, useCallback, useMemo, forwardRef, useImperativeHandle } from 'react';
-import type { SuperDoc } from 'superdoc'; // requires superdoc >=1.24.2 for correct types
+import type { SuperDoc, ProseMirrorJSON } from 'superdoc'; // requires superdoc >=1.24.2 for correct types
 import type * as Types from './types';
 import { FieldMenu, FieldList } from './defaults';
 import {
@@ -187,9 +187,10 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
               ? editor.commands.insertStructuredContentBlock?.({
                   attrs,
                   ...(field.presetContent.html ? { html: field.presetContent.html } : {}),
-                  ...(field.presetContent.json ? { json: field.presetContent.json } : {}),
+                  ...(field.presetContent.json ? { json: field.presetContent.json as ProseMirrorJSON } : {}),
                 })
-              : editor.commands.insertStructuredContentBlock?.({ attrs, text: field.defaultValue || field.alias })
+              : // Block insert ignores `text` at runtime; drop it to match the real type.
+                editor.commands.insertStructuredContentBlock?.({ attrs })
         ) as boolean | undefined;
 
         if (success) {
@@ -217,7 +218,7 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
         if (!superdocRef.current?.activeEditor) return false;
 
         const editor = superdocRef.current.activeEditor;
-        const success = editor.commands.updateStructuredContentById?.(id, {
+        const success = editor.commands.updateStructuredContentById?.(String(id), {
           attrs: updates,
         }) as boolean | undefined;
 
@@ -264,7 +265,7 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
 
         let commandResult = false;
         try {
-          commandResult = (editor.commands.deleteStructuredContentById?.(id) as boolean | undefined) ?? false;
+          commandResult = (editor.commands.deleteStructuredContentById?.(String(id)) as boolean | undefined) ?? false;
         } catch (err) {
           console.warn('[TemplateBuilder] Failed to delete structured content:', id, err);
           commandResult = false;
@@ -282,7 +283,7 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
 
           if (remainingFieldsInGroup.length === 1) {
             const lastField = remainingFieldsInGroup[0];
-            editor.commands.updateStructuredContentById?.(lastField.id, {
+            editor.commands.updateStructuredContentById?.(String(lastField.id), {
               attrs: { tag: undefined },
             });
             documentFields = getTemplateFieldsFromEditor(editor);
@@ -594,7 +595,11 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
         const success =
           mode === 'inline'
             ? editor.commands.insertStructuredContentInline?.({ attrs, text: field.alias })
-            : editor.commands.insertStructuredContentBlock?.({ attrs, text: field.alias });
+            : // Block insert ignores `text` at runtime (the visible content comes
+              // from `html`, `json`, or the active selection). Previously this call
+              // also passed `text: field.alias` but it was a no-op silently allowed
+              // by `any`-typed commands. Drop the field to match the real type.
+              editor.commands.insertStructuredContentBlock?.({ attrs });
 
         if (success) {
           if (!field.group) {

packages/template-builder/src/tests/insertFieldPresetContent.test.tsx

@@ -120,7 +120,7 @@ describe('SuperDocTemplateBuilder presetContent insertion', () => {
     expect(firstBlockCallArg).not.toHaveProperty('text');
   });
 
-  it('keeps text fallback for block fields without presetContent', async () => {
+  it('omits text on block insert without presetContent (runtime ignores it)', async () => {
     const ref = await renderBuilder();
     let result = false;
 
@@ -131,13 +131,21 @@ describe('SuperDocTemplateBuilder presetContent insertion', () => {
       });
     });
 
+    // The block-insert API uses `html` / `json` / current selection for
+    // its content; `text` is not part of `StructuredContentBlockInsert`
+    // and was always silently ignored at runtime. Now that the typed
+    // surface rejects unknown fields, the call site no longer passes
+    // `text` for block insertion, matching what the runtime actually
+    // honored. Inline insertion still accepts `text` (handled by the
+    // separate inline test below).
     expect(result).toBe(true);
     expect(insertStructuredContentBlockMock).toHaveBeenCalledTimes(1);
-    expect(insertStructuredContentBlockMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        text: 'Default signature content',
-      }),
-    );
+    const firstBlockCallArg = (
+      insertStructuredContentBlockMock as unknown as {
+        mock: { calls: Array<Array<Record<string, unknown>>> };
+      }
+    ).mock.calls[0]?.[0];
+    expect(firstBlockCallArg).not.toHaveProperty('text');
   });
 
   it('ignores presetContent for inline insertion', async () => {

tests/consumer-typecheck/.gitignore

@@ -0,0 +1,6 @@
+# Build artifact: written per-scenario by typecheck-matrix.mjs
+tsconfig.matrix.json
+
+# pnpm install --ignore-workspace generates this; the fixture's
+# package-lock.json is the committed lockfile of record.
+pnpm-lock.yaml