fix(types): gate public surface without skipLibCheck (#3114)

caio-pizzol · web-flow · commit 03a7b489fecc · 2026-05-04T16:00:32.000-03:00
* fix(types): gate public surface without skipLibCheck SD-2892: add packed-tarball consumer typecheck scenarios that compile the full public fixture set with skipLibCheck=false under bundler, node16, and nodenext. Fix the declaration issues exposed by that gate: publish the public mdast/ws type dependencies, emit NodeNext-safe relative declaration specifiers, keep Vue SFC declarations resolvable, and tighten JSDoc-generated declarations. Vue is published as ^3.5.0 because catalog: cannot survive npm packaging and exact patch installs duplicate Vue global macro declarations in consumers. @types/ws stays a dependency because @hocuspocus/provider peer declarations require it under skipLibCheck=false; @types/mdast is directly referenced by public markdown helper declarations. * fix(track-changes): keep optional and unused params off public d.ts (SD-2892) JSDoc tightening in 56dac0d inadvertently required options.id on markInsertion/markDeletion (the runtime treats it as optional) and required options.tr/options.map on addMarkStep (which never destructures them). Mark id optional with bracket syntax and drop the unused tr/map declarations so the emitted public d.ts matches the runtime contract.
diff --git a/packages/super-editor/src/editors/v1/components/toolbar/super-toolbar.js b/packages/super-editor/src/editors/v1/components/toolbar/super-toolbar.js
@@ -134,6 +134,7 @@ import { markerTextToBulletStyle } from '@helpers/list-numbering-helpers.js';
  * @typedef {Object} CommandItem
  * @property {ToolbarItem} item - The toolbar item
  * @property {*} [argument] - The argument to pass to the command
+ * @property {*} [option] - The selected nested option for option-style commands
  */
 
 /**
diff --git a/packages/super-editor/src/editors/v1/core/commands/backspaceAcrossRuns.js b/packages/super-editor/src/editors/v1/core/commands/backspaceAcrossRuns.js
@@ -12,7 +12,7 @@ import { findPreviousTextDeleteRange } from './findPreviousTextDeleteRange.js';
  * Placed after the specialized handlers (backspaceSkipEmptyRun,
  * backspaceNextToRun) in the keymap chain so it only fires when they bail.
  *
- * @returns {import('@core/commands/types').Command}
+ * @returns {import('./types/index.js').Command}
  */
 export const backspaceAcrossRuns =
   () =>
diff --git a/packages/super-editor/src/editors/v1/core/commands/backspaceEmptyRunParagraph.js b/packages/super-editor/src/editors/v1/core/commands/backspaceEmptyRunParagraph.js
@@ -3,7 +3,7 @@ import { TextSelection } from 'prosemirror-state';
 /**
  * Removes a paragraph that only contains an empty run when backspacing inside it.
  * Prevents deleting the only paragraph in the document.
- * @returns {import('@core/commands/types').Command}
+ * @returns {import('./types/index.js').Command}
  */
 export const backspaceEmptyRunParagraph =
   () =>
diff --git a/packages/super-editor/src/editors/v1/core/commands/backspaceNextToRun.js b/packages/super-editor/src/editors/v1/core/commands/backspaceNextToRun.js
@@ -4,7 +4,7 @@ import { findPreviousTextDeleteRange } from './findPreviousTextDeleteRange.js';
 /**
  * Backspaces a single character when the cursor sits adjacent to a run boundary.
  * Deletes the last character of the previous run (or the previous sibling run) without removing the whole run node.
- * @returns {import('@core/commands/types').Command}
+ * @returns {import('./types/index.js').Command}
  */
 export const backspaceNextToRun =
   () =>
diff --git a/packages/super-editor/src/editors/v1/core/commands/backspaceSkipEmptyRun.js b/packages/super-editor/src/editors/v1/core/commands/backspaceSkipEmptyRun.js
@@ -3,7 +3,7 @@ import { Selection } from 'prosemirror-state';
 /**
  * Backspaces over an empty run to the left of the cursor, deleting the previous character instead.
  * Only triggers when inside a run positioned directly before an empty sibling run.
- * @returns {import('@core/commands/types').Command}
+ * @returns {import('./types/index.js').Command}
  */
 export const backspaceSkipEmptyRun =
   () =>
diff --git a/packages/super-editor/src/editors/v1/core/commands/deleteNextToRun.js b/packages/super-editor/src/editors/v1/core/commands/deleteNextToRun.js
@@ -3,7 +3,7 @@ import { Selection } from 'prosemirror-state';
 /**
  * Deletes a single character in the run immediately after the cursor.
  * Keeps the run node intact and skips empty runs.
- * @returns {import('@core/commands/types').Command}
+ * @returns {import('./types/index.js').Command}
  */
 export const deleteNextToRun =
   () =>
diff --git a/packages/super-editor/src/editors/v1/core/commands/deleteSkipEmptyRun.js b/packages/super-editor/src/editors/v1/core/commands/deleteSkipEmptyRun.js
@@ -3,7 +3,7 @@ import { Selection } from 'prosemirror-state';
 /**
  * Deletes while skipping over an empty run to the right of the cursor.
  * When the cursor is at the end of a run and followed by an empty run, removes the next character beyond it.
- * @returns {import('@core/commands/types').Command}
+ * @returns {import('./types/index.js').Command}
  */
 export const deleteSkipEmptyRun =
   () =>
diff --git a/packages/super-editor/src/editors/v1/core/commands/skipTab.js b/packages/super-editor/src/editors/v1/core/commands/skipTab.js
@@ -3,7 +3,7 @@ import { TextSelection } from 'prosemirror-state';
 /**
  * Moves the cursor across a tab node when inside a run.
  * @param {1|-1} dir Direction to move: forward (1) or backward (-1).
- * @returns {import('@core/commands/types').Command}
+ * @returns {import('./types/index.js').Command}
  */
 export function skipTab(dir) {
   return ({ state, dispatch }) => {
diff --git a/packages/super-editor/src/editors/v1/extensions/run/commands/split-run.js b/packages/super-editor/src/editors/v1/extensions/run/commands/split-run.js
@@ -32,7 +32,7 @@ function clearHeadingStyleId(attrs) {
 
 /**
  * Splits a run node at the current selection into two paragraphs.
- * @returns {import('@core/commands/types').Command}
+ * @returns {import('../../../core/commands/types/index.js').Command}
  */
 export const splitRunToParagraph = () => (props) => {
   const { state, view, tr, editor } = props;
@@ -274,7 +274,7 @@ function applyStyleMarks(state, tr, editor, paragraphAttrs, tableInfo) {
 
 /**
  * Splits the current run node into two sibling runs at the cursor position.
- * @returns {import('@core/commands/types').Command}
+ * @returns {import('../../../core/commands/types/index.js').Command}
  */
 export const splitRunAtCursor = () => (props) => {
   let { state, dispatch, tr } = props;
diff --git a/packages/super-editor/src/editors/v1/extensions/structured-content/document-section/helpers.js b/packages/super-editor/src/editors/v1/extensions/structured-content/document-section/helpers.js
@@ -1,5 +1,10 @@
 import { DOMSerializer } from 'prosemirror-model';
 
+/**
+ * @typedef {import('../../../core/Editor.js').Editor} Editor
+ * @typedef {import('prosemirror-model').Node} ProseMirrorNode
+ */
+
 /**
  * Get all sections in the editor document.
  * This function traverses the document and collects all nodes of the specified section type.
@@ -51,7 +56,7 @@ export const exportSectionsToHTML = (editor) => {
 
 /**
  * Get HTML representation of a ProseMirror node.
- * @param {Node} node - The ProseMirror node to convert.
+ * @param {ProseMirrorNode} node - The ProseMirror node to convert.
  * @param {Editor} editor - The editor instance used for serialization.
  * @returns {String} The HTML representation of the node's content.
  */
diff --git a/packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/addMarkStep.js b/packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/addMarkStep.js
@@ -13,11 +13,10 @@ import { getLiveInlineMarksInRange } from './getLiveInlineMarksInRange.js';
 
 /**
  * Add mark step.
+ * @param {object} options Add mark options.
  * @param {import('prosemirror-state').EditorState} options.state Editor state.
- * @param {import('prosemirror-state').Transaction} options.tr Transaction.
  * @param {import('prosemirror-transform').AddMarkStep} options.step Step.
  * @param {import('prosemirror-state').Transaction} options.newTr New transaction.
- * @param {import('prosemirror-transform').Mapping} options.map Map.
  * @param {import('prosemirror-model').Node} options.doc Doc.
  * @param {object} options.user User object ({ name, email }).
  * @param {string} options.date Date.
diff --git a/packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/markDeletion.js b/packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/markDeletion.js
@@ -6,12 +6,13 @@ import { findTrackedMarkBetween } from './findTrackedMarkBetween.js';
 
 /**
  * Mark deletion.
- * @param {Transaction} options.tr Transaction.
+ * @param {object} options Mark deletion options.
+ * @param {import('prosemirror-state').Transaction} options.tr Transaction.
  * @param {number} options.from From position.
  * @param {number} options.to To position.
  * @param {object} options.user User object ({ name, email }).
  * @param {string} options.date Date.
- * @param {string} options.id Optional ID to use (for replace operations where insertion and deletion share the same ID).
+ * @param {string} [options.id] Optional ID to use (for replace operations where insertion and deletion share the same ID).
  * @returns {Object} Deletion map and deletionMark
  */
 export const markDeletion = ({ tr, from, to, user, date, id: providedId }) => {
diff --git a/packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/markInsertion.js b/packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/markInsertion.js
@@ -4,13 +4,14 @@ import { findTrackedMarkBetween } from './findTrackedMarkBetween.js';
 
 /**
  * Mark insertion.
- * @param {Transaction} options.tr Transaction.
+ * @param {object} options Mark insertion options.
+ * @param {import('prosemirror-state').Transaction} options.tr Transaction.
  * @param {number} options.from From position.
  * @param {number} options.to To position.
  * @param {object} options.user User object ({ name, email }).
  * @param {string} options.date Date.
- * @param {string} options.id Optional ID to use (for replace operations where insertion and deletion share the same ID).
- * @returns {Mark} Insertion mark.
+ * @param {string} [options.id] Optional ID to use (for replace operations where insertion and deletion share the same ID).
+ * @returns {import('prosemirror-model').Mark} Insertion mark.
  */
 export const markInsertion = ({ tr, from, to, user, date, id: providedId }) => {
   tr.removeMark(from, to, tr.doc.type.schema.marks[TrackDeleteMarkName]);
diff --git a/packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/removeMarkStep.js b/packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/removeMarkStep.js
@@ -7,6 +7,7 @@ import { getLiveInlineMarksInRange } from './getLiveInlineMarksInRange.js';
 
 /**
  * Remove mark step.
+ * @param {object} options Remove mark options.
  * @param {import('prosemirror-state').EditorState} options.state Editor state.
  * @param {import('prosemirror-transform').RemoveMarkStep} options.step Step.
  * @param {import('prosemirror-state').Transaction} options.newTr New transaction.
diff --git a/packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/replaceStep.js b/packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/replaceStep.js
@@ -141,6 +141,7 @@ const normalizeReplaceStepSingleCharDelete = ({ step, doc }) => {
 
 /**
  * Replace step.
+ * @param {object} options Replace step options.
  * @param {import('prosemirror-state').EditorState} options.state Editor state.
  * @param {import('prosemirror-state').Transaction} options.tr Transaction.
  * @param {import('prosemirror-transform').ReplaceStep} options.step Step.
@@ -151,6 +152,7 @@ const normalizeReplaceStepSingleCharDelete = ({ step, doc }) => {
  * @param {string} options.date Date.
  * @param {import('prosemirror-transform').ReplaceStep} options.originalStep Original step.
  * @param {number} options.originalStepIndex Original step index.
+ * @param {'paired' | 'independent'} [options.replacements] Replacement id pairing mode.
  */
 export const replaceStep = ({
   state,
diff --git a/packages/superdoc/package.json b/packages/superdoc/package.json
@@ -124,14 +124,16 @@
     "test": "vitest"
   },
   "dependencies": {
+    "@types/mdast": "catalog:",
+    "@types/ws": "catalog:",
     "buffer-crc32": "catalog:",
     "eventemitter3": "catalog:",
     "jsdom": "catalog:",
     "konva": "catalog:",
     "pinia": "catalog:",
     "rollup-plugin-copy": "catalog:",
     "uuid": "catalog:",
-    "vue": "catalog:",
+    "vue": "^3.5.0",
     "y-websocket": "catalog:"
   },
   "peerDependencies": {
diff --git a/packages/superdoc/scripts/ensure-types.cjs b/packages/superdoc/scripts/ensure-types.cjs
@@ -155,12 +155,28 @@ const BAD_ABSOLUTE_PATH_RE = /(['"])packages\/superdoc\/src\/([^'"]+)\1/g;
 
 // vite-plugin-dts incorrectly resolves subpath exports (e.g. @superdoc/super-editor/types)
 // by appending the subpath to the main entry: '../../super-editor/src/index.js/types'
-// Fix: rewrite index.js/<subpath> → <subpath>.js
-const BAD_SUBPATH_RE = /(['"])([^'"]*\/index\.js)(\/[^'"]+)\1/g;
+// or '../../super-editor/src/index.ts/types'
+// Fix: rewrite index.(js|ts)/<subpath> → <subpath>.js
+const BAD_SUBPATH_RE = /(['"])([^'"]*\/index\.(?:js|ts))(\/[^'"]+)\1/g;
 
 let fixedFiles = 0;
 let totalReplacements = 0;
 
+function appendJsExtensionToRelativeSpecifier(specifier, filePath) {
+  if (!specifier.startsWith('./') && !specifier.startsWith('../')) return specifier;
+  if (specifier.includes('?') || specifier.includes('#')) return specifier;
+  const targetBase = path.resolve(path.dirname(filePath), specifier);
+  if (path.posix.extname(specifier) === '.vue') {
+    // `./Foo.vue.js` is the Node16/NodeNext-friendly declaration specifier:
+    // TypeScript strips the trailing `.js` and resolves it to `Foo.vue.d.ts`.
+    return fs.existsSync(`${targetBase}.d.ts`) ? `${specifier}.js` : specifier;
+  }
+  if (path.posix.extname(specifier)) return specifier;
+  if (fs.existsSync(`${targetBase}.d.ts`)) return `${specifier}.js`;
+  if (fs.existsSync(path.join(targetBase, 'index.d.ts'))) return `${specifier}/index.js`;
+  return specifier;
+}
+
 // SD-2815: rewrite `@superdoc/document-api` bare specifiers to point
 // at the document-api dist that vite-plugin-dts now emits at
 // `dist/document-api/`. Without this, packed consumers see the bare
@@ -271,8 +287,8 @@ for (const filePath of dtsFiles) {
   fileContent = fileContent.replace(BAD_SUBPATH_RE, (match, quote, basePath, subpath) => {
     changed = true;
     totalReplacements++;
-    // Replace 'foo/index.js/types' with 'foo/types.js'
-    const dir = basePath.replace(/\/index\.js$/, '');
+    // Replace 'foo/index.js/types' or 'foo/index.ts/types' with 'foo/types.js'
+    const dir = basePath.replace(/\/index\.(?:js|ts)$/, '');
     return `${quote}${dir}${subpath}.js${quote}`;
   });
 
@@ -289,6 +305,21 @@ for (const filePath of dtsFiles) {
     },
   );
 
+  // Node16/NodeNext consumers run stricter ESM declaration resolution than
+  // bundler consumers. vite-plugin-dts and tsup can emit relative imports like
+  // `export * from './foo'` and Vue SFC imports like `./Foo.vue`; rewrite those
+  // to `.js` specifiers that TypeScript maps back to the sibling `.d.ts` file.
+  fileContent = fileContent.replace(
+    /(?<=from\s+['"]|import\(['"])(\.{1,2}\/[^'"]+)(?=['"])/g,
+    (specifier) => {
+      const rewritten = appendJsExtensionToRelativeSpecifier(specifier, filePath);
+      if (rewritten === specifier) return specifier;
+      changed = true;
+      totalReplacements++;
+      return rewritten;
+    },
+  );
+
   if (changed) {
     fs.writeFileSync(filePath, fileContent);
     fixedFiles++;
diff --git a/packages/superdoc/src/components/CommentsLayer/commentsList/super-comments-list.js b/packages/superdoc/src/components/CommentsLayer/commentsList/super-comments-list.js
@@ -1,4 +1,4 @@
-import EventEmitter from 'eventemitter3';
+import { EventEmitter } from 'eventemitter3';
 import { setActivePinia } from 'pinia';
 import { createApp } from 'vue';
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
@@ -41,6 +41,7 @@ catalog:
   '@types/react': ^19.2.6
   '@types/react-dom': ^19.2.3
   '@types/uuid': ^9.0.8
+  '@types/ws': ^8.18.1
   '@typescript-eslint/eslint-plugin': ^8.49.0
   '@typescript-eslint/parser': ^8.49.0
   '@vitejs/plugin-react': ^5.1.1
diff --git a/tests/consumer-typecheck/typecheck-matrix.mjs b/tests/consumer-typecheck/typecheck-matrix.mjs
@@ -4,12 +4,16 @@
  * Tests that superdoc's type declarations work across all common
  * tsconfig combinations consumers might use:
  *   - moduleResolution: bundler, node16, nodenext
- *   - skipLibCheck: true (all scenarios), false (regression check)
+ *   - skipLibCheck: true (targeted compat scenarios), false (public-surface gate)
  *   - strict: true and false
  *   - Import paths: "superdoc", "superdoc/super-editor"
  *   - Node.js headless usage (Buffer return types)
  *   - Guarded public types must not collapse to `any` (SD-2831)
  *
+ * The optional `allowNodeModuleErrors` scenario flag remains available for
+ * documented upstream exceptions, but current public-surface scenarios should
+ * pass with `skipLibCheck: false`.
+ *
  * The fixture installs superdoc from the packed tarball at
  * ../../packages/superdoc/superdoc.tgz, so the matrix tests the
  * customer-visible surface, not the source repo.
@@ -300,19 +304,42 @@ const scenarios = [
     files: ['src/prosemirror-coexistence.ts'],
     mustPass: true,
   },
-  // skipLibCheck=false — informational. Existing dep noise from
-  // node_modules (~30 errors at last count) is expected here; the
-  // `allowNodeModuleErrors` flag opts this scenario into the DEPS
-  // classification rather than INFO so the failure mode stays explicit.
+  // SD-2892: full public-facing surface with skipLibCheck=false. These
+  // scenarios pack SuperDoc, install it into the consumer fixture, and compile
+  // every public consumer assertion under the resolution modes customers use.
+  // SuperDoc-owned declaration leaks surface as node_modules/superdoc errors,
+  // so these scenarios are required gates with no dependency-error allowance.
+  // If this aggregate gate fails, rerun tsc against individual fixture files
+  // to narrow the broken public entry point.
   {
-    name: 'bundler / skipLibCheck=false',
+    name: 'bundler / all public surface / skipLibCheck=false',
     module: 'ESNext',
     moduleResolution: 'bundler',
     skipLibCheck: false,
     strict: true,
-    files: ['src/imports-main.ts'],
-    mustPass: false,
-    allowNodeModuleErrors: true,
+    noPropertyAccessFromIndexSignature: true,
+    files: ['src/**/*.ts'],
+    mustPass: true,
+  },
+  {
+    name: 'node16 / all public surface / skipLibCheck=false',
+    module: 'Node16',
+    moduleResolution: 'node16',
+    skipLibCheck: false,
+    strict: true,
+    noPropertyAccessFromIndexSignature: true,
+    files: ['src/**/*.ts'],
+    mustPass: true,
+  },
+  {
+    name: 'nodenext / all public surface / skipLibCheck=false',
+    module: 'NodeNext',
+    moduleResolution: 'nodenext',
+    skipLibCheck: false,
+    strict: true,
+    noPropertyAccessFromIndexSignature: true,
+    files: ['src/**/*.ts'],
+    mustPass: true,
   },
   // SD-2842: every public type re-exported via `superdoc` must resolve
   // to a real interface, not collapse to `any` and not be missing.

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ import { findPreviousTextDeleteRange } from './findPreviousTextDeleteRange.js';`
`12`	`12`	`* Placed after the specialized handlers (backspaceSkipEmptyRun,`
`13`	`13`	`* backspaceNextToRun) in the keymap chain so it only fires when they bail.`
`14`	`14`	`*`
`15`		`- * @returns {import('@core/commands/types').Command}`
	`15`	`+ * @returns {import('./types/index.js').Command}`
`16`	`16`	`*/`
`17`	`17`	`export const backspaceAcrossRuns =`
`18`	`18`	`() =>`