fix(superdoc): preserve public Config.user.color typing via AwarenessUser

Pre-PR, the SuperDoc-local public User had color?: string so consumers
could pass { user: { ..., color } } via Config and runtime would honor
it (SuperDoc#assignUserColor() skips hash-assignment when user.color is
already set). After unifying User to the super-editor symbol (which
has no color), Config.user?: User silently narrowed: consumers passing
an explicit color now fail TS typecheck even though runtime still
accepts it.

Fix by typing Config.user against AwarenessUser (which extends User
with the optional color), and adding AwarenessUser to the public
facade + classification snapshot so it's a first-class supported-root
export. addSharedUser / removeSharedUser still accept the narrower
User parameter; only Config.user is widened.

Empirically verified: a consumer fixture passing
{ user: { name, email, color: '#ff0000' } } typechecks against the
packed tarball post-fix; same fixture fails on the previous commit.

Author: caio-pizzol

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

@@ -1397,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. */

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/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;