refactor(superdoc): type #initCollaboration param as Modules (SD-2867 phase B)

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 */
@@ -511,9 +512,11 @@ export class SuperDoc extends EventEmitter {
   }
 
   /**
-   * Initialize collaboration if configured
-   * @param {Object} config
-   * @returns {Promise<Object[]>} The processed documents with collaboration enabled
+   * Initialize collaboration if configured. Accepts the full
+   * `Config.modules` block so it can read both the collaboration
+   * subkey and the comments subkey at once.
+   * @param {Modules} [modules]
+   * @returns {Promise<Document[] | undefined>} The processed documents with collaboration enabled. Caller awaits for side effects; the return value is informational.
    */
   async #initCollaboration({ collaboration: collaborationModuleConfig, comments: commentsConfig = {} } = {}) {
     if (!collaborationModuleConfig) return this.config.documents;
@@ -1304,8 +1307,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/create-app.js

@@ -301,12 +301,24 @@ const setPiniaDevtoolsSuppressedForApp = (app, isSuppressed) => {
   };
 };
 
+/**
+ * Result of `createSuperdocVueApp()`. Internal-only: the shape is consumed
+ * by `SuperDoc.#initVueApp` and is not part of the public surface.
+ *
+ * @typedef {Object} SuperdocVueAppRefs
+ * @property {import('vue').App} app The Vue 3 app instance
+ * @property {import('pinia').Pinia} pinia The Pinia store instance attached to `app`
+ * @property {ReturnType<typeof useSuperdocStore>} superdocStore The SuperDoc Pinia store
+ * @property {ReturnType<typeof useCommentsStore>} commentsStore The Comments Pinia store
+ * @property {ReturnType<typeof useHighContrastMode>} highContrastModeStore The high-contrast mode composable refs (`isHighContrastMode`, `setHighContrastMode`). Named `*Store` for historical reasons; this is a plain Vue composable, not a Pinia store.
+ */
+
 /**
  * Generate the superdoc vue app
  *
  * @param {Object} [options]
  * @param {boolean} [options.disablePiniaDevtools=false] Disable Pinia devtools registration for this app instance
- * @returns {Object} An object containing the vue app, the pinia reference, and the superdoc store
+ * @returns {SuperdocVueAppRefs} An object containing the vue app, the pinia reference, the superdoc/comments Pinia stores, and the high-contrast mode composable
  */
 export const createSuperdocVueApp = ({ disablePiniaDevtools = false } = {}) => {
   const app = createApp(App);

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). */