refactor(superdoc): add RuntimeDocument typedef for runtime doc shape (SD-2867 phase B) (#3058)

* refactor(superdoc): type createSuperdocVueApp return shape (SD-2867 phase B)

`createSuperdocVueApp()` returned `Object` per its JSDoc, so the five
fields SuperDoc.js destructures from the call (`app`, `pinia`,
`superdocStore`, `commentsStore`, `highContrastModeStore`) all
resolved to `Object` for any consumer enabling `// @ts-check`. Five
TS2339 'Property does not exist on type Object' errors at SuperDoc.js
line 464 — and inside the SD-2867 ratchet that turns each into a
gate failure.

Promotes the return type to a named `SuperdocVueAppRefs` typedef that
imports `vue.App`, `pinia.Pinia`, and the store types via
`ReturnType<typeof useSuperdocStore>` etc. The shape is internal-only
(this typedef is not on the public Modules / Config surface), so
adding it here doesn't widen the customer-visible surface.

Verified: pnpm --filter superdoc run check:jsdoc passes (3 gated files
clean); the consumer-typecheck matrix passes 31/31; the postbuild
declaration audit reports no FAIL findings; pnpm --filter superdoc
test passes 944/944.

This is groundwork for SD-2867 phase B: closing each cluster of
SuperDoc.js TS errors so the file can eventually enroll in
`CHECKED_FILES`. Five errors closed; ~133 remain across implicit-any
params, strict-null guards, and other type-not-assignable callsites.
Each cluster will land as its own focused commit.

* refactor(superdoc): add RuntimeDocument typedef for runtime doc shape (SD-2867 phase B)

The internal `doc` parameter in SuperDoc.js's private methods (#applyDocumentMode,
#attachExternalCollaboration, etc.) is shaped differently from the
public `Document` interface: SuperDoc attaches a runtime `role`,
`getEditor()`, and `getPresentationEditor()` to each entry during
init. Today those methods are typed `@param {Object} doc`, so any
attempt to enable `// @ts-check` on SuperDoc.js fails with TS2339
errors at every `doc.getEditor()` / `doc.getPresentationEditor()` /
`doc.role` access (~10 sites).

Adds a `RuntimeDocument` typedef in core/types/index.ts that extends
the public `Document` with the runtime-attached fields. Updates
#applyDocumentMode's `@param {Object} doc` to `@param {RuntimeDocument}
doc` as the first call site to migrate.

The typedef is internal-only and not on the public superdoc surface
(not in the public typedef block of packages/superdoc/src/index.js),
so consumers cannot import or pass these fields from outside.

This is groundwork: subsequent SD-2867 phase B PRs will migrate the
remaining `@param {Object} doc` sites and then enable @ts-check on the
methods involved.

Verified: pnpm --filter superdoc run check:jsdoc passes (3 gated files
clean); consumer matrix passes 31/31; declaration audit reports no
FAIL findings; published .d.ts surface unchanged (RuntimeDocument is
not re-exported from the public superdoc entry).

Author: caio-pizzol

packages/superdoc/src/core/SuperDoc.js

@@ -59,6 +59,7 @@ const DEFAULT_AWARENESS_PALETTE = Object.freeze([
 
 /** @typedef {import('./types/index.js').User} User */
 /** @typedef {import('./types/index.js').Document} Document */
+/** @typedef {import('./types/index.js').RuntimeDocument} RuntimeDocument */
 /** @typedef {import('./types/index.js').Modules} Modules */
 /** @typedef {import('./types/index.js').Editor} Editor */
 /** @typedef {import('./types/index.js').DocumentMode} DocumentMode */
@@ -1304,8 +1305,8 @@ export class SuperDoc extends EventEmitter {
   /**
    * Set the document mode on a document's editor (PresentationEditor or Editor).
    * Tries PresentationEditor first, falls back to Editor for backward compatibility.
-   * @param {Object} doc - The document object
-   * @param {string} mode - The document mode ('editing', 'viewing', 'suggesting')
+   * @param {RuntimeDocument} doc - The document object
+   * @param {DocumentMode} mode - The document mode ('editing', 'viewing', 'suggesting')
    */
   #applyDocumentMode(doc, mode) {
     const presentationEditor = typeof doc.getPresentationEditor === 'function' ? doc.getPresentationEditor() : null;

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

@@ -17,6 +17,7 @@ import type { Ref, ComputedRef } from 'vue';
 
 import type {
   Editor as SuperEditor,
+  PresentationEditor as SuperEditorPresentationEditor,
   StoryLocator as SuperEditorStoryLocator,
   BookmarkAddress as SuperEditorBookmarkAddress,
   BlockNavigationAddress as SuperEditorBlockNavigationAddress,
@@ -86,6 +87,50 @@ export interface Document {
  */
 export type CollaborationProvider = SuperEditorCollaborationProvider;
 
+/**
+ * Internal augmentation of `Document` for runtime-only fields that the
+ * SuperDoc instance attaches to each document during initialization. The
+ * public `Document` interface above is what consumers pass in via
+ * `Config.documents`; this type adds the fields SuperDoc itself sets and
+ * reads internally (per-document `role` propagation, the live `getEditor`
+ * and `getPresentationEditor` accessors that the surface manager and
+ * mode-switch helpers walk).
+ *
+ * Internal use only: not part of any public typedef. Consumers cannot
+ * import this through `superdoc` and should not pass any of these fields
+ * into `Config.documents` from outside.
+ */
+export interface RuntimeDocument extends Document {
+  /**
+   * Per-document role. `useDocument()` reads `params.role` from the input
+   * config and exposes it on the smart-doc object; once collaboration
+   * setup runs, SuperDoc unconditionally writes `doc.role = config.role`,
+   * silently replacing whatever was passed. SD-2872 removed this from
+   * the public `Document` interface so consumers stop trying to use it
+   * as a stable per-document override; it lives on `RuntimeDocument`
+   * only so internal SuperDoc.js callsites can type the assignment.
+   */
+  role?: 'editor' | 'viewer' | 'suggester';
+  /**
+   * Returns the body Editor for this document, when the runtime has
+   * created one. Set by the editor-create lifecycle.
+   *
+   * @deprecated Direct editor access will be removed in a future version.
+   * Use the Document API (`editor.doc`) instead. This typedef carries the
+   * deprecation marker forward from the source accessor in
+   * `packages/superdoc/src/composables/use-document.js`.
+   */
+  getEditor?: () => SuperEditor | null | undefined;
+  /**
+   * Returns the PresentationEditor for this document, when the runtime
+   * has created one. Set by the editor-create lifecycle.
+   *
+   * @deprecated Direct editor access will be removed in a future version.
+   * Use the Document API (`editor.doc`) instead.
+   */
+  getPresentationEditor?: () => SuperEditorPresentationEditor | null | undefined;
+}
+
 /** Collaboration module configuration. */
 export interface CollaborationConfig {
   /** External Yjs document (provider-agnostic mode). */