Merge pull request #3484 from superdoc-dev/caio-pizzol/SD-typecheck-user-unification

refactor(superdoc): unify User type and drain 4 user-method obligations (SD-673)

Author: caio-pizzol

packages/superdoc/src/core/SuperDoc.ts

@@ -62,6 +62,7 @@ const DEFAULT_AWARENESS_PALETTE = Object.freeze([
 // declared as interfaces below.
 import type {
   AwarenessState,
+  AwarenessUser,
   CollaborationProvider,
   Config,
   DocumentMode,
@@ -382,7 +383,7 @@ export class SuperDoc extends EventEmitter<SuperDocEventMap> {
   declare superdocId: string;
   declare comments: unknown[];
   declare socket: HocuspocusProviderWebsocket | null;
-  declare user: User;
+  declare user: AwarenessUser;
   declare _cleanupAwareness: (() => void) | null;
   declare _commentsCollabInitialized: boolean;
 

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

@@ -29,6 +29,7 @@ import type {
   FontConfig,
   FontsResolvedPayload,
   ProofingProvider,
+  User,
 } from '@superdoc/super-editor';
 
 import type { SuperDoc as SuperDocClass } from '../SuperDoc.js';
@@ -47,32 +48,37 @@ export type NavigableAddress = SuperEditorNavigableAddress;
 /**
  * The current user of this superdoc.
  *
- * Every field is optional on input. `SuperDoc.#init` normalizes a missing
- * or partial `user` by spreading `DEFAULT_USER` over consumer input, so
- * `name` and `email` always have a value at runtime even when the
- * consumer omits them. The typedef stays open so consumers can pass
- * `{ name: 'Ada' }` without a typecheck failure.
+ * Re-exported directly from `@superdoc/super-editor` so the public
+ * consumer-facing `User` (re-exported again at `src/public/index.ts`)
+ * and the internal `User` referenced by SuperDoc method signatures
+ * (`addSharedUser(user: User)`, `removeSharedUser(...)`, etc.) are
+ * the same symbol — not two structurally-similar declarations.
  *
- * Kept structurally compatible with the publicly re-exported
- * `User` from `@superdoc/super-editor` (also optional name/email).
+ * Every field is optional on input. `SuperDoc.#init` normalizes a
+ * missing or partial `user` by spreading `DEFAULT_USER` over consumer
+ * input, so `name` and `email` always have a value at runtime even
+ * when the consumer omits them.
+ *
+ * `User` does NOT carry the collab-awareness `color` field; that is on
+ * the internal `AwarenessUser` (see below), assigned by SuperDoc's
+ * `#assignUserColor()` after `#init`.
  */
-export interface User {
-  /** The user's name. */
-  name?: string;
-  /**
-   * The user's email. May be `null` when the consumer did not provide an
-   * email and SuperDoc fell back to the built-in default user; the runtime
-   * has always exposed `null` here, so the typedef accepts it explicitly
-   * rather than narrowing to `string`. Consumers must narrow before
-   * performing string operations on this field.
-   */
-  email?: string | null;
-  /** The user's photo. */
-  image?: string | null;
+export type { User } from '@superdoc/super-editor';
+
+/**
+ * Internal post-`#init` shape of the active user. Extends the public
+ * `User` with the collab-awareness `color` field assigned by
+ * `SuperDoc.#assignUserColor()` and read by the presence system. Not
+ * part of the consumer-facing surface; consumers continue to pass
+ * `User` via `Config.user`, and SuperDoc widens to `AwarenessUser`
+ * internally once it has computed the color.
+ */
+export interface AwarenessUser extends User {
   /**
    * Awareness color for collaborative cursors. Auto-assigned from the
-   * configured palette (or a default palette) when omitted, derived from a
-   * hash of the user's identity so the assignment is stable across reloads.
+   * configured palette (or a default palette) by `#assignUserColor`,
+   * derived from a hash of the user's identity so the assignment is
+   * stable across reloads.
    */
   color?: string;
 }
@@ -96,9 +102,11 @@ export interface AwarenessState extends User {
   /** Yjs client identifier for the remote peer. */
   clientId?: number;
   /**
-   * Color assigned by SuperDoc's presence system. Overrides
-   * {@link User.color} when the presence system computes a stable
-   * palette assignment for the remote peer.
+   * Color assigned by SuperDoc's presence system. Spread onto the
+   * awareness entry after the user fields, so it takes precedence
+   * over any color the awareness user carried in (see
+   * {@link AwarenessUser.color}). Used when the presence system
+   * computes a stable palette assignment for the remote peer.
    */
   color?: string;
   /** Application-specific fields spread from the awareness provider. */
@@ -1389,8 +1397,14 @@ export interface Config {
   password?: string;
   /** The documents to load → soon to be deprecated. */
   documents?: Document[];
-  /** The current user of this SuperDoc. */
-  user?: User;
+  /**
+   * The current user of this SuperDoc. Typed as `AwarenessUser` (an
+   * extension of `User` with the optional `color` field) so consumers
+   * can pass an explicit awareness color and have the runtime honor it
+   * as an override - `SuperDoc#assignUserColor()` skips its hash-based
+   * assignment when `user.color` is already set.
+   */
+  user?: AwarenessUser;
   /** All users of this SuperDoc (can be used for "@"-mentions). */
   users?: User[];
   /** Colors to use for user awareness. */
@@ -1608,8 +1622,12 @@ export interface InternalConfig extends Config {
   documents: RuntimeDocument[];
   /** Normalized to `{}` by `#init` if the consumer passes nothing or `undefined`. */
   modules: Modules;
-  /** Spread of `DEFAULT_USER` over consumer input by `#init`; `name` always present. */
-  user: User;
+  /**
+   * Spread of `DEFAULT_USER` over consumer input by `#init`; `name`
+   * always present. Widened to `AwarenessUser` because `#assignUserColor`
+   * runs synchronously during init and writes `color` into this object.
+   */
+  user: AwarenessUser;
   /** Normalized to `{}` by `#init` if the consumer passes nothing or `undefined`. */
   layoutEngineOptions: SuperDocLayoutEngineOptions;
 }

packages/superdoc/src/public/index.ts

@@ -58,6 +58,7 @@ export { createTheme } from '../core/theme/create-theme.js';
 
 // Type source: ./core/types/index.js
 export type { AwarenessState } from '../core/types/index.js';
+export type { AwarenessUser } from '../core/types/index.js';
 export type { BlockNavigationAddress } from '../core/types/index.js';
 export type { BookmarkAddress } from '../core/types/index.js';
 export type { CollaborationConfig } from '../core/types/index.js';

tests/consumer-typecheck/public-method-coverage-debt-snapshot.json

@@ -3,8 +3,6 @@
   "knownUnmet": [
     "addCommentsList:parameters",
     "addCommentsList:returns",
-    "addSharedUser:parameters",
-    "addSharedUser:returns",
     "canPerformPermission:parameters",
     "canPerformPermission:returns",
     "closeSurface:parameters",
@@ -23,8 +21,6 @@
     "openSurface:parameters",
     "openSurface:returns",
     "removeCommentsList:returns",
-    "removeSharedUser:parameters",
-    "removeSharedUser:returns",
     "requiredNumberOfEditors:returns",
     "save:returns",
     "scrollToComment:parameters",

tests/consumer-typecheck/snapshots/superdoc-root-classification.json

@@ -1,15 +1,15 @@
 {
   "generatedAt": "2026-05-19T11:33:50.546Z",
   "summary": {
-    "total": 204,
+    "total": 205,
     "byBucket": {
       "legacy-root": 60,
       "internal-candidate": 8,
-      "supported-root": 136
+      "supported-root": 137
     },
     "byConfidence": {
       "high": 102,
-      "medium": 100,
+      "medium": 101,
       "low": 2
     }
   },
@@ -47,6 +47,17 @@
       "inEsm": false,
       "inCjs": false
     },
+    {
+      "name": "AwarenessUser",
+      "bucket": "supported-root",
+      "rationale": "Collaboration/awareness type defined in core/types/index.ts. Extends User with an optional `color` field for consumer-supplied awareness color; typed on Config.user so the runtime override in SuperDoc#assignUserColor() is consumer-typable.",
+      "confidence": "medium",
+      "source": "collab",
+      "inDts": true,
+      "inDcts": true,
+      "inEsm": false,
+      "inCjs": false
+    },
     {
       "name": "BinaryData",
       "bucket": "supported-root",
@@ -754,7 +765,7 @@
     {
       "name": "FlowBlock",
       "bucket": "legacy-root",
-      "rationale": "In LayoutState.blocks. Layout-engine raw type that must not appear in public .d.ts per package-boundaries.md:64 — already leaks via PE closure.",
+      "rationale": "In LayoutState.blocks. Layout-engine raw type that must not appear in public .d.ts per package-boundaries.md:64 \u2014 already leaks via PE closure.",
       "confidence": "high",
       "source": "locked",
       "inDts": true,
@@ -842,7 +853,7 @@
     {
       "name": "Layout",
       "bucket": "legacy-root",
-      "rationale": "In PE.onLayoutUpdated payload (LayoutState & { layout: Layout; ... }). Layout-engine raw type that must not appear in public .d.ts per package-boundaries.md:64 — already leaks via PE legacy API.",
+      "rationale": "In PE.onLayoutUpdated payload (LayoutState & { layout: Layout; ... }). Layout-engine raw type that must not appear in public .d.ts per package-boundaries.md:64 \u2014 already leaks via PE legacy API.",
       "confidence": "high",
       "source": "locked",
       "inDts": true,

tests/consumer-typecheck/snapshots/superdoc-root-classification.md

@@ -1,26 +1,27 @@
 # SD-3212 A1 — root classification
 
-Generated: 2026-05-19T11:33:50.546Z
-Input: tests/consumer-typecheck/snapshots/superdoc-root-exports.json (200 names, locked baseline)
+Generated: 2026-05-25T00:00:00.000Z
+Input: tests/consumer-typecheck/snapshots/superdoc-root-exports.json (205 names, locked baseline)
 
 ## Summary
 
 | Bucket | Count |
 |---|---|
-| supported-root | 132 |
+| supported-root | 137 |
 | legacy-root | 60 |
 | move-to-subpath | 0 |
 | internal-candidate | 8 |
 | NEEDS-REVIEW | 0 |
-| **total** | **200** |
+| **total** | **205** |
 
-Confidence: high=98, medium=100, needs-review=0.
+Confidence: high=102, medium=101, needs-review=0.
 
-## supported-root (132)
+## supported-root (137)
 
 | Name | Confidence | Source | Rationale |
 |---|---|---|---|
 | `AwarenessState` | medium | collab | Collaboration/awareness type defined in core/types/index.ts. Customer-facing for collab-provider integrations (e.g., AwarenessState types the documented onAwarenessUpdate callback). |
+| `AwarenessUser` | medium | collab | Collaboration/awareness type defined in core/types/index.ts. Extends User with an optional `color` field for consumer-supplied awareness color; typed on Config.user so the runtime override in SuperDoc#assignUserColor() is consumer-typable. |
 | `BinaryData` | high | locked | Shape of binary content used in documented import/export/open/save paths. Type-reachable through documented APIs. |
 | `BlockNavigationAddress` | high | doc-api | Document API navigation/address/selection type. Promoted into the root facade by SD-3185. |
 | `BlocksListResult` | high | doc-api | Document API navigation/address/selection type. Promoted into the root facade by SD-3185. |

tests/consumer-typecheck/snapshots/superdoc-root-exports.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-23T12:40:30.787Z",
+  "generatedAt": "2026-05-25T11:25:51.224Z",
   "ticket": "SD-3212 PR A0",
   "package": "superdoc",
   "rootExport": {
@@ -17,6 +17,7 @@
         "AIWriter",
         "AnnotatorHelpers",
         "AwarenessState",
+        "AwarenessUser",
         "BinaryData",
         "BlankDOCX",
         "BlockNavigationAddress",
@@ -227,6 +228,7 @@
         "AIWriter",
         "AnnotatorHelpers",
         "AwarenessState",
+        "AwarenessUser",
         "BinaryData",
         "BlankDOCX",
         "BlockNavigationAddress",
@@ -527,11 +529,11 @@
     }
   },
   "counts": {
-    "types.import": 204,
-    "types.require": 204,
+    "types.import": 205,
+    "types.require": 205,
     "import": 41,
     "require": 41,
-    "union": 204
+    "union": 205
   },
   "divergences": {
     "typesImportVsRequire": {
@@ -545,6 +547,7 @@
     "typesVsRuntime": {
       "typedOnly": [
         "AwarenessState",
+        "AwarenessUser",
         "BinaryData",
         "BlockNavigationAddress",
         "BlocksListResult",

tests/consumer-typecheck/snapshots/superdoc-root-exports.md

@@ -1,30 +1,31 @@
 # superdoc root export inventory (SD-3212 PR A0)
 
-Generated: 2026-05-23T12:40:30.787Z
+Generated: 2026-05-25T11:25:51.224Z
 Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc`
 
 ## Counts
 
 | Source | Path | Count |
 |---|---|---|
-| types.import | `./dist/superdoc/src/public/index.d.ts` | 204 |
-| types.require | `./dist/superdoc/src/public/index.d.cts` | 204 |
+| types.import | `./dist/superdoc/src/public/index.d.ts` | 205 |
+| types.require | `./dist/superdoc/src/public/index.d.cts` | 205 |
 | import | `./dist/superdoc.es.js` | 41 |
 | require | `./dist/superdoc.cjs` | 41 |
-| **union** |  | **204** |
+| **union** |  | **205** |
 
 ## Divergences
 
 - types.import only (not in types.require): 0
 - types.require only (not in types.import): 0
 - ESM only (not in CJS): 0
 - CJS only (not in ESM): 0
-- typed but no runtime export (phantom risk): 163
+- typed but no runtime export (phantom risk): 164
 - runtime export but not typed (silent shadow on root): 0
 
 ### Type-only names (no runtime)
 
 - `AwarenessState`
+- `AwarenessUser`
 - `BinaryData`
 - `BlockNavigationAddress`
 - `BlocksListResult`
@@ -195,6 +196,7 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc`
 | `AIWriter` | ✓ | ✓ | ✓ | ✓ | 1 |   | 0 | 0 | 4 |   |
 | `AnnotatorHelpers` | ✓ | ✓ | ✓ | ✓ | 1 |   | 0 | 0 | 1 |   |
 | `AwarenessState` | ✓ | ✓ |   |   | 3 | ✓ | 0 | 0 | 0 |   |
+| `AwarenessUser` | ✓ | ✓ |   |   | 0 |   | 0 | 0 | 0 |   |
 | `BinaryData` | ✓ | ✓ |   |   | 3 | ✓ | 0 | 0 | 0 |   |
 | `BlankDOCX` | ✓ | ✓ | ✓ | ✓ | 0 |   | 0 | 0 | 1 |   |
 | `BlockNavigationAddress` | ✓ | ✓ |   |   | 1 | ✓ | 0 | 0 | 0 |   |
@@ -228,7 +230,7 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc`
 | `DirectSurfaceRequest` | ✓ | ✓ |   |   | 1 | ✓ | 0 | 0 | 0 |   |
 | `DocRange` | ✓ | ✓ |   |   | 1 | ✓ | 0 | 0 | 0 |   |
 | `DocumentApi` | ✓ | ✓ |   |   | 3 | ✓ | 0 | 8 | 4 | ✓ |
-| `DocumentMode` | ✓ | ✓ |   |   | 2 | ✓ | 2 | 16 | 3 |   |
+| `DocumentMode` | ✓ | ✓ |   |   | 3 | ✓ | 2 | 16 | 3 |   |
 | `DocumentProtectionState` | ✓ | ✓ |   |   | 1 | ✓ | 1 | 0 | 1 |   |
 | `DocxFileEntry` | ✓ | ✓ |   |   | 3 | ✓ | 0 | 0 | 0 |   |
 | `DocxZipper` | ✓ | ✓ | ✓ | ✓ | 2 |   | 0 | 0 | 1 | ✓ |
@@ -282,7 +284,7 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc`
 | `ListDefinitionsPayload` | ✓ | ✓ |   |   | 1 | ✓ | 0 | 0 | 0 |   |
 | `Measure` | ✓ | ✓ |   |   | 3 | ✓ | 0 | 0 | 1 |   |
 | `Modules` | ✓ | ✓ |   |   | 1 | ✓ | 4 | 0 | 0 |   |
-| `NavigableAddress` | ✓ | ✓ |   |   | 1 | ✓ | 0 | 0 | 0 |   |
+| `NavigableAddress` | ✓ | ✓ |   |   | 2 | ✓ | 0 | 0 | 0 |   |
 | `OpenOptions` | ✓ | ✓ |   |   | 3 | ✓ | 1 | 0 | 0 |   |
 | `PDF` | ✓ | ✓ | ✓ | ✓ | 2 |   | 35 | 0 | 1 | ✓ |
 | `PageMargins` | ✓ | ✓ |   |   | 3 | ✓ | 0 | 0 | 0 |   |
@@ -339,11 +341,11 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc`
 | `SlashMenu` | ✓ | ✓ | ✓ | ✓ | 1 |   | 0 | 0 | 1 |   |
 | `StoryLocator` | ✓ | ✓ |   |   | 1 | ✓ | 116 | 0 | 3 |   |
 | `SuperConverter` | ✓ | ✓ | ✓ | ✓ | 1 |   | 0 | 0 | 3 | ✓ |
-| `SuperDoc` | ✓ | ✓ | ✓ | ✓ | 11 |   | 1014 | 180 | 244 | ✓ |
-| `SuperDocExceptionEditorPayload` | ✓ | ✓ |   |   | 1 |   | 0 | 0 | 0 |   |
-| `SuperDocExceptionPayload` | ✓ | ✓ |   |   | 1 |   | 0 | 0 | 0 |   |
-| `SuperDocExceptionRestorePayload` | ✓ | ✓ |   |   | 0 |   | 0 | 0 | 0 |   |
-| `SuperDocExceptionStorePayload` | ✓ | ✓ |   |   | 1 |   | 0 | 0 | 0 |   |
+| `SuperDoc` | ✓ | ✓ | ✓ | ✓ | 13 |   | 1014 | 180 | 244 | ✓ |
+| `SuperDocExceptionEditorPayload` | ✓ | ✓ |   |   | 2 |   | 0 | 0 | 0 |   |
+| `SuperDocExceptionPayload` | ✓ | ✓ |   |   | 2 |   | 0 | 0 | 0 |   |
+| `SuperDocExceptionRestorePayload` | ✓ | ✓ |   |   | 1 |   | 0 | 0 | 0 |   |
+| `SuperDocExceptionStorePayload` | ✓ | ✓ |   |   | 2 |   | 0 | 0 | 0 |   |
 | `SuperDocLayoutEngineOptions` | ✓ | ✓ |   |   | 2 | ✓ | 0 | 0 | 0 |   |
 | `SuperDocTelemetryConfig` | ✓ | ✓ |   |   | 1 | ✓ | 0 | 0 | 0 |   |
 | `SuperEditor` | ✓ | ✓ | ✓ | ✓ | 1 |   | 16 | 0 | 5 |   |
@@ -371,7 +373,7 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc`
 | `Transaction` | ✓ | ✓ |   |   | 3 | ✓ | 5 | 0 | 0 | ✓ |
 | `UnsupportedContentItem` | ✓ | ✓ |   |   | 3 | ✓ | 0 | 0 | 0 |   |
 | `UpgradeToCollaborationOptions` | ✓ | ✓ |   |   | 1 | ✓ | 0 | 0 | 0 |   |
-| `User` | ✓ | ✓ |   |   | 4 | ✓ | 51 | 8 | 30 |   |
+| `User` | ✓ | ✓ |   |   | 5 | ✓ | 51 | 8 | 30 |   |
 | `ViewLayout` | ✓ | ✓ |   |   | 1 | ✓ | 0 | 0 | 0 |   |
 | `ViewOptions` | ✓ | ✓ |   |   | 1 | ✓ | 2 | 0 | 0 |   |
 | `ViewingVisibilityConfig` | ✓ | ✓ |   |   | 1 | ✓ | 0 | 0 | 0 |   |

tests/consumer-typecheck/src/all-public-types.ts

@@ -101,6 +101,7 @@ import type {
   LinkPopoverResolution,
   LinkPopoverResolver,
   AwarenessState,
+  AwarenessUser,
   ListDefinitionsPayload,
   Measure,
   Modules,
@@ -273,6 +274,7 @@ const _real_LinkPopoverContext: AssertNotAny<LinkPopoverContext> = true;
 const _real_LinkPopoverResolution: AssertNotAny<LinkPopoverResolution> = true;
 const _real_LinkPopoverResolver: AssertNotAny<LinkPopoverResolver> = true;
 const _real_AwarenessState: AssertNotAny<AwarenessState> = true;
+const _real_AwarenessUser: AssertNotAny<AwarenessUser> = true;
 const _real_ListDefinitionsPayload: AssertNotAny<ListDefinitionsPayload> = true;
 const _real_Measure: AssertNotAny<Measure> = true;
 const _real_Modules: AssertNotAny<Modules> = true;