fix(superdoc): hide internal fields at source + repair node16 Config resolution (SD-2886) (#3056)

After SD-2880 published Config and SuperDocLayoutEngineOptions, two
fields the source explicitly marks as internal became reachable on the
public surface:

  - Config.socket. 'Internal: ... do not pass from outside.' Set by
    SuperDoc when modules.collaboration.providerType is 'hocuspocus';
    a consumer who passes it from outside breaks the collaboration
    setup.
  - SuperDocLayoutEngineOptions.semanticOptions. 'Internal-only ...
    intentionally not a stable public API in v1.' A consumer who
    pins a shape couples themselves to behavior we may break.

Earlier attempts and why they were wrong:

  1. stripInternal: true in superdoc's tsconfig. Review pass found
     this would silently strip 100+ pre-existing @internal-tagged
     fields across super-editor (ImageAttrs.id, ParagraphAttrs.paraId,
     TableAttrs.sdBlockId, etc.) — a worse regression than the one
     this PR closes.

  2. Omit<...> at the typedef alias boundary in superdoc/src/index.js.
     Review pass found this only narrowed the standalone Config alias.
     The nested Config.layoutEngineOptions still reached the un-Omitted
     SuperDocLayoutEngineOptions, and the SuperDoc constructor signature
     still took the un-Omitted Config — so `new SuperDoc({ socket })`
     and `{ layoutEngineOptions: { semanticOptions } }` still type-
     checked.

This patch removes both fields from the source `Config` and
`SuperDocLayoutEngineOptions` interfaces in core/types/index.ts and
adds InternalConfig / InternalSuperDocLayoutEngineOptions extensions
for the runtime callsites that need the augmented shape (SuperDoc.js's
this.config.socket assignments, etc.). Public surface no longer carries
either field anywhere it can be reached.

Side fix surfaced by the same review: the JSDoc `@typedef
{import('./types').X}` form in core/SuperDoc.js and core/surface-manager.js
did not resolve under TypeScript's node16 module resolution. The published
constructor signature decayed to `any` for node16 consumers, and the
constructor probe (`new SuperDoc({ socket: undefined })`) silently
type-checked. Switched all 11 `import('./types')` usages to
`import('./types/index.js')` so the path resolves under both bundler
and node16.

The regression-net fixture under tests/consumer-typecheck/ now covers
all four reachable surfaces: standalone Config alias, standalone
SuperDocLayoutEngineOptions alias, nested Config.layoutEngineOptions,
and the SuperDoc constructor parameter. Each uses @ts-expect-error so
a regression on any path fails CI with TS2578 ("Unused @ts-expect-error
directive").

Verified: matrix passes 31/31; declaration audit reports no FAIL
findings; published .d.ts no longer references socket or
semanticOptions on any reachable public path.

Author: caio-pizzol

packages/superdoc/src/core/SuperDoc.js

@@ -57,17 +57,17 @@ const DEFAULT_AWARENESS_PALETTE = Object.freeze([
   '#F39C12',
 ]);
 
-/** @typedef {import('./types').User} User */
-/** @typedef {import('./types').Document} Document */
-/** @typedef {import('./types').Modules} Modules */
-/** @typedef {import('./types').Editor} Editor */
-/** @typedef {import('./types').DocumentMode} DocumentMode */
-/** @typedef {import('./types').Config} Config */
-/** @typedef {import('./types').ExportParams} ExportParams */
-/** @typedef {import('./types').UpgradeToCollaborationOptions} UpgradeToCollaborationOptions */
-/** @typedef {import('./types').SurfaceRequest} SurfaceRequest */
-/** @typedef {import('./types').SurfaceHandle} SurfaceHandle */
-/** @typedef {import('./types').NavigableAddress} NavigableAddress */
+/** @typedef {import('./types/index.js').User} User */
+/** @typedef {import('./types/index.js').Document} Document */
+/** @typedef {import('./types/index.js').Modules} Modules */
+/** @typedef {import('./types/index.js').Editor} Editor */
+/** @typedef {import('./types/index.js').DocumentMode} DocumentMode */
+/** @typedef {import('./types/index.js').Config} Config */
+/** @typedef {import('./types/index.js').ExportParams} ExportParams */
+/** @typedef {import('./types/index.js').UpgradeToCollaborationOptions} UpgradeToCollaborationOptions */
+/** @typedef {import('./types/index.js').SurfaceRequest} SurfaceRequest */
+/** @typedef {import('./types/index.js').SurfaceHandle} SurfaceHandle */
+/** @typedef {import('./types/index.js').NavigableAddress} NavigableAddress */
 
 /**
  * SuperDoc class
@@ -585,7 +585,7 @@ export class SuperDoc extends EventEmitter {
    * or explicitly after this call during construction.
    *
    * @param {import('yjs').Doc} ydoc
-   * @param {import('./types').CollaborationProvider} provider
+   * @param {import('./types/index.js').CollaborationProvider} provider
    */
   #attachExternalCollaboration(ydoc, provider) {
     this.isCollaborative = true;
@@ -750,7 +750,7 @@ export class SuperDoc extends EventEmitter {
    * underlying ref objects.
    *
    * @param {import('yjs').Doc | null} ydoc
-   * @param {import('./types').CollaborationProvider | null} provider
+   * @param {import('./types/index.js').CollaborationProvider | null} provider
    */
   #setStoreDocumentCollaboration(ydoc, provider) {
     const storeDocs = this.superdocStore?.documents;
@@ -862,7 +862,7 @@ export class SuperDoc extends EventEmitter {
    * provider that exposes on/off but never emits sync cannot hang forever.
    * destroy() can abort this wait early via #abortUpgrade.
    *
-   * @param {import('./types').CollaborationProvider} provider
+   * @param {import('./types/index.js').CollaborationProvider} provider
    * @returns {Promise<void>}
    */
   #waitForProviderSync(provider) {

packages/superdoc/src/core/surface-manager.js

@@ -1,12 +1,12 @@
 import { shallowRef } from 'vue';
 
-/** @typedef {import('./types').SurfaceMode} SurfaceMode */
-/** @typedef {import('./types').SurfaceRequest} SurfaceRequest */
-/** @typedef {import('./types').SurfaceResolution} SurfaceResolution */
-/** @typedef {import('./types').SurfaceHandle} SurfaceHandle */
-/** @typedef {import('./types').SurfaceOutcome} SurfaceOutcome */
-/** @typedef {import('./types').SurfacesModuleConfig} SurfacesModuleConfig */
-/** @typedef {import('./types').ExternalSurfaceRenderContext} ExternalSurfaceRenderContext */
+/** @typedef {import('./types/index.js').SurfaceMode} SurfaceMode */
+/** @typedef {import('./types/index.js').SurfaceRequest} SurfaceRequest */
+/** @typedef {import('./types/index.js').SurfaceResolution} SurfaceResolution */
+/** @typedef {import('./types/index.js').SurfaceHandle} SurfaceHandle */
+/** @typedef {import('./types/index.js').SurfaceOutcome} SurfaceOutcome */
+/** @typedef {import('./types/index.js').SurfacesModuleConfig} SurfacesModuleConfig */
+/** @typedef {import('./types/index.js').ExternalSurfaceRenderContext} ExternalSurfaceRenderContext */
 
 /**
  * @typedef {Object} ActiveSurface

packages/superdoc/src/core/types/index.ts

@@ -1086,11 +1086,6 @@ export interface SuperDocLayoutEngineOptions {
    * - 'semantic': continuous semantic flow without visible pagination boundaries
    */
   flowMode?: 'paginated' | 'semantic';
-  /**
-   * Internal-only semantic mode tuning options. This shape is intentionally
-   * not a stable public API in v1.
-   */
-  semanticOptions?: object;
   /**
    * Deprecated. Use `modules.trackChanges` instead. Optional override for
    * paginated track-changes rendering (e.g., `{ mode: 'original' }` or
@@ -1313,14 +1308,41 @@ export interface Config {
    * back, warn, or block printing on unsupported faces.
    */
   onFontsResolved?: (payload: FontsResolvedPayload) => void;
+}
+
+/**
+ * Internal augmentation of `Config` for runtime-only fields that must not
+ * appear on the published consumer surface. The `Config` interface above is
+ * the public contract; this type adds the fields SuperDoc sets/reads
+ * internally so the implementation can be type-checked without leaking the
+ * fields into customer IDE autocomplete.
+ *
+ * Use this from internal SuperDoc.js callsites that need the augmented shape
+ * (e.g. `/** @type {InternalConfig} *\/ (this.config).socket = ...`).
+ */
+export interface InternalConfig extends Config {
   /**
-   * Internal: the shared websocket instance created by SuperDoc when
+   * The shared websocket instance created by SuperDoc when
    * `modules.collaboration.providerType === 'hocuspocus'`. Set automatically;
-   * do not pass from outside.
+   * not part of the public Config surface.
    */
   socket?: HocuspocusProviderWebsocket;
 }
 
+/**
+ * Internal augmentation of `SuperDocLayoutEngineOptions` for unstable tuning
+ * fields. The public `SuperDocLayoutEngineOptions` interface above is the
+ * customer-facing contract; this type adds fields the implementation may
+ * read but that are intentionally not part of the v1 stable API.
+ */
+export interface InternalSuperDocLayoutEngineOptions extends SuperDocLayoutEngineOptions {
+  /**
+   * Internal-only semantic mode tuning options. Shape may change without
+   * notice; not part of the public surface.
+   */
+  semanticOptions?: object;
+}
+
 export type ProofingStatus = 'idle' | 'checking' | 'disabled' | 'degraded';
 
 export interface ProofingError {

tests/consumer-typecheck/src/internal-fields-stripped.ts

@@ -0,0 +1,54 @@
+/**
+ * Consumer typecheck: internal-only fields must not appear on the
+ * published Config / SuperDocLayoutEngineOptions surface (SD-2886).
+ *
+ * Two fields in `core/types/index.ts` are explicitly internal:
+ *
+ *   - Config.socket. "Internal: ... do not pass from outside" (set
+ *     automatically when modules.collaboration.providerType === 'hocuspocus').
+ *   - SuperDocLayoutEngineOptions.semanticOptions. "Internal-only ...
+ *     intentionally not a stable public API in v1."
+ *
+ * Both are kept off the public surface by removing them from the source
+ * `Config` / `SuperDocLayoutEngineOptions` interfaces in
+ * `packages/superdoc/src/core/types/index.ts`. Internal callsites that need
+ * the augmented shape use the `InternalConfig` /
+ * `InternalSuperDocLayoutEngineOptions` extensions instead.
+ *
+ * The fixture pins both the standalone alias surface AND the nested /
+ * constructor surface that the reviewer caught leaking past an earlier
+ * Omit-at-the-boundary attempt. If a future change reintroduces either
+ * field on the public types, an @ts-expect-error directive becomes unused
+ * and tsc fails with TS2578 ("Unused @ts-expect-error directive").
+ */
+import { SuperDoc } from 'superdoc';
+import type { Config, SuperDocLayoutEngineOptions } from 'superdoc';
+
+declare const config: Config;
+declare const layoutOpts: SuperDocLayoutEngineOptions;
+
+// 1. Top-level Config alias must not expose `socket`.
+// @ts-expect-error - `socket` is internal-only and must not appear on the
+// published Config surface.
+void config.socket;
+
+// 2. Top-level SuperDocLayoutEngineOptions alias must not expose
+// `semanticOptions`.
+// @ts-expect-error - `semanticOptions` is internal-only and must not appear
+// on the published SuperDocLayoutEngineOptions surface.
+void layoutOpts.semanticOptions;
+
+// 3. Nested path: `Config.layoutEngineOptions` must reach the
+// public-surface SuperDocLayoutEngineOptions, not an internal variant. An
+// earlier Omit-at-the-boundary attempt fixed (1) and (2) but left this
+// nested reference resolving to the un-stripped source.
+// @ts-expect-error - `semanticOptions` must not be reachable through
+// `Config.layoutEngineOptions` either.
+void config.layoutEngineOptions?.semanticOptions;
+
+// 4. Constructor path: `new SuperDoc({ socket })` must not type-check. The
+// constructor signature published in SuperDoc.d.ts must reach the same
+// public-surface Config the standalone alias points at.
+// @ts-expect-error - `socket` is not part of the public Config and must
+// not be assignable through the SuperDoc constructor.
+new SuperDoc({ selector: '#x', socket: undefined });

tests/consumer-typecheck/typecheck-matrix.mjs

@@ -402,6 +402,29 @@ const scenarios = [
     files: ['src/modules-config-passthrough.ts'],
     mustPass: true,
   },
+  // SD-2886: internal-only fields on Config / SuperDocLayoutEngineOptions
+  // must not appear on the published surface. They are hidden via
+  // `Omit<...>` re-exports in `packages/superdoc/src/index.js`. The fixture
+  // relies on `@ts-expect-error` markers that stop erroring (TS2578) if a
+  // future change leaks an internal field back onto the public surface.
+  {
+    name: 'bundler / internal fields stripped (SD-2886)',
+    module: 'ESNext',
+    moduleResolution: 'bundler',
+    skipLibCheck: true,
+    strict: true,
+    files: ['src/internal-fields-stripped.ts'],
+    mustPass: true,
+  },
+  {
+    name: 'node16 / internal fields stripped (SD-2886)',
+    module: 'Node16',
+    moduleResolution: 'node16',
+    skipLibCheck: true,
+    strict: true,
+    files: ['src/internal-fields-stripped.ts'],
+    mustPass: true,
+  },
 ];
 
 const tscPath = join(__dirname, 'node_modules', '.bin', 'tsc');