fix(types): add Comment, FontConfig, exportDocx overloads, and missing PresentationEditor types (#2675)

* fix(types): add Comment, FontConfig, exportDocx overloads, and missing PresentationEditor types

- Replace thin Comment type with full runtime shape (commentId, elements, etc.)
- Add CommentElement type for comment body nodes
- Add FontConfig type for toolbar font picker options
- Add exportDocx overloads for narrowed return types per flag
- Add loadXmlData overloads accepting ArrayBuffer, narrowing out undefined
- Add replaceFile ArrayBuffer support
- Make User.name/email/image optional to match runtime behavior
- Fix Toolbar interface removing index signature for SuperToolbar compat
- Add ToolbarConfig fonts/hideButtons/pagination to JSDoc typedef
- Export LayoutState, ImageSelectedEvent, ImageDeselectedEvent, TelemetryEvent,
  RemoteCursorsRenderPayload, FlowMode, ExportDocxParams, and all proofing types
- Add JSDoc re-exports in superdoc barrel for all new types
- Update consumer typecheck tests with new type imports and usage

* ci: add PR preview publish to release workflow

Adds optional `pr_number` input to workflow_dispatch. When provided,
checks out the PR branch, sets version to `<base>-pr.<number>.<timestamp>`,
builds, publishes with dist-tag `pr-<number>`, and comments on the PR
with install instructions. Normal semantic-release flow is skipped.

Also fixes replaceFile ArrayBuffer handling for fileSource assignment.

* fix(types): inject command type augmentations into dist for TS4111 compat

Consumers with noPropertyAccessFromIndexSignature get TS4111 errors on
commands like insertComment, removeComment, etc. because they fall through
to the EditorCommands index signature.

The augmentation files (comment-commands.ts, formatting-commands.ts, etc.)
already exist and extend ExtensionCommandMap, but vite-plugin-dts strips
the side-effect imports that load them.

Fix: inject /// <reference> directives into the dist index.d.ts via the
ensure-types.cjs postbuild script, so augmentations are always loaded
when consumers import from the package.

* fix(types): restore unintentionally removed code from diff application

- Restore `this.options.fragment = null` in replaceFile() collaboration
  path — without it, #generatePmData() reuses the stale Yjs fragment
  instead of the new file content
- Restore documentModeChange event emission in Editor.setDocumentMode()
  and DocumentModeChangePayload type — SuperEditor.vue subscribes to
  this for viewing-mode UI cleanup
- Fix exportDocx overload ordering — specific overloads must come before
  the generic catch-all so TypeScript resolves them correctly

* refactor(types): use explicit imports for command types instead of reference directives

Replace /// <reference> directive injection (via ensure-types.cjs postbuild)
with direct import of command interfaces into ChainedCommands.ts. EditorCommands
is now composed as an explicit intersection of CoreCommandSignatures + all 9
extension command interfaces.

Export CoreCommandSignatures from core-command-map.d.ts so core commands
(insertContent, toggleMark, selectAll, etc.) are also explicitly typed.

* test(types): add consumer type compatibility test with noPropertyAccessFromIndexSignature

Comprehensive test covering the full public API surface:
- Type shapes (Comment, FontConfig, ProofingConfig, layout types, events)
- Editor/PresentationEditor constructor options with optional User fields
- Command dot-access (core + extension commands) under strict index sig
- exportDocx overloads with narrowed return types
- loadXmlData/replaceFile with ArrayBuffer
- PresentationEditor methods (layout, selection, scrolling, hit testing)
- Selection handle API
- Event handlers with typed payloads
- SuperToolbar assignable to setToolbar
- Proofing provider contract

Also fixes Toolbar.setActiveEditor param type for strict function compat.

* fix(types): expose type re-exports via superdoc/super-editor sub-export

The super-editor facade (.d.ts) only re-exported from the v1 runtime
barrel, so types like Comment, FontConfig, EditorCommands were only
available from the root 'superdoc' import, not 'superdoc/super-editor'.

Add re-export of the type-enriched index.ts barrel to the facade so
both entry points expose the full type surface.

* ci: add consumer typecheck step to CI pipeline

Packs the built superdoc package, installs it in tests/consumer-typecheck,
and runs tsc --noEmit with noPropertyAccessFromIndexSignature enabled.
Catches type regressions that source-level typechecking misses (e.g.
missing exports, broken augmentations, index signature fallbacks).

* fix(types): review fixes — track-changes fallbacks, test consolidation, CI hardening

- Add || '' fallbacks for user.name/email/image in track-changes mark
  creation to prevent undefined author metadata when User fields are
  optional
- Consolidate overlapping consumer typecheck files: merge unique tests
  from index.ts into customer-scenario.ts, strip imports-main.ts to
  imports-only, delete redundant index.ts
- Pin PR preview checkout to exact SHA instead of branch ref
- Restore missing Editor import in EditorTypes.ts (lost during rebase)

Author: caio-pizzol

.github/workflows/ci-superdoc.yml

@@ -72,6 +72,13 @@ jobs:
       - name: Typecheck
         run: pnpm run type-check
 
+      - name: Consumer typecheck
+        run: |
+          cd packages/superdoc && pnpm pack --pack-destination .
+          cd ../../tests/consumer-typecheck
+          npm install ../../packages/superdoc/superdoc-*.tgz --no-save
+          npx tsc --noEmit
+
   unit-tests:
     needs: build
     runs-on: ubuntu-latest

.github/workflows/release-superdoc.yml

@@ -1,6 +1,7 @@
 # Auto-releases on push to:
 # - main (@next channel)
 # - stable (@latest channel)
+# Manual PR preview: dispatch with pr_number to publish @pr-<number>
 name: 📦 Release superdoc
 
 on:
@@ -18,10 +19,16 @@ on:
       - 'pnpm-workspace.yaml'
       - '!**/*.md'
   workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'PR number to publish a preview package for (leave empty for normal release)'
+        required: false
+        type: number
 
 permissions:
   contents: write
   packages: write
+  pull-requests: write
 
 concurrency:
   group: ${{ github.ref_name == 'stable' && 'release-stable-writeback' || format('{0}-{1}', github.workflow, github.ref) }}
@@ -38,13 +45,25 @@ jobs:
           app-id: ${{ secrets.APP_ID }}
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
 
+      # PR preview: check out the PR branch
+      - name: Get PR head ref
+        if: inputs.pr_number
+        id: pr
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          PR_DATA=$(gh api repos/${{ github.repository }}/pulls/${{ inputs.pr_number }} --jq '{ref: .head.ref, sha: .head.sha}')
+          echo "ref=$(echo $PR_DATA | jq -r .ref)" >> $GITHUB_OUTPUT
+          echo "sha=$(echo $PR_DATA | jq -r .sha)" >> $GITHUB_OUTPUT
+
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          ref: ${{ steps.pr.outputs.sha || '' }}
           token: ${{ steps.generate_token.outputs.token }}
 
       - name: Refresh stable branch head
-        if: github.ref_name == 'stable'
+        if: github.ref_name == 'stable' && !inputs.pr_number
         run: |
           git fetch origin "${{ github.ref_name }}" --tags
           git checkout -B "${{ github.ref_name }}" "origin/${{ github.ref_name }}"
@@ -81,10 +100,48 @@ jobs:
       - name: Install dependencies
         run: pnpm install
 
+      # PR preview: set version before build so it's baked into the package
+      - name: Set preview version
+        if: inputs.pr_number
+        id: version
+        run: |
+          BASE_VERSION=$(node -p "require('./packages/superdoc/package.json').version")
+          PREVIEW_VERSION="${BASE_VERSION}-pr.${{ inputs.pr_number }}.$(date +%s)"
+          echo "version=$PREVIEW_VERSION" >> $GITHUB_OUTPUT
+          cd packages/superdoc
+          npm version "$PREVIEW_VERSION" --no-git-tag-version
+
       - name: Build packages
         run: pnpm run build
 
+      # PR preview: publish with pr-<number> dist-tag
+      - name: Publish PR preview
+        if: inputs.pr_number
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          node scripts/publish-superdoc.cjs \
+            --dist-tag pr-${{ inputs.pr_number }} \
+            --skip-build
+
+      - name: Comment on PR
+        if: inputs.pr_number
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh pr comment ${{ inputs.pr_number }} --body "$(cat <<'EOF'
+          📦 **Preview published:** `superdoc@${{ steps.version.outputs.version }}`
+
+          ```bash
+          npm install superdoc@pr-${{ inputs.pr_number }}
+          ```
+          EOF
+          )"
+
+      # Normal release: semantic-release (only when NOT a PR preview)
       - name: Release
+        if: ${{ !inputs.pr_number }}
         env:
           GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

packages/super-editor/src/editors/v1/components/toolbar/super-toolbar.js

@@ -38,6 +38,9 @@ import { NodeSelection } from 'prosemirror-state';
  * @property {string} [role='editor'] - Role of the toolbar ('editor' or 'viewer')
  * @property {Object} [icons] - Custom icons for toolbar items
  * @property {Object} [texts] - Custom texts for toolbar items
+ * @property {import('../../core/types/EditorConfig.js').FontConfig[]} [fonts] - Font options for the font picker dropdown
+ * @property {boolean} [hideButtons=true] - Whether to hide buttons when the editor is not focused
+ * @property {boolean} [pagination=false] - Whether to show pagination controls
  * @property {string} [mode='docx'] - Editor mode
  * @property {string[]} [excludeItems=[]] - Items to exclude from the toolbar
  * @property {Object} [groups=null] - Custom groups configuration

packages/super-editor/src/editors/v1/core/Editor.ts

@@ -213,7 +213,7 @@ export interface SaveOptions {
   commentsType?: string;
 
   /** Comments to include in export */
-  comments?: Array<{ id: string; [key: string]: unknown }>;
+  comments?: Comment[];
 
   /** Highlight color for fields */
   fieldsHighlightColor?: string | null;
@@ -2235,7 +2235,22 @@ export class Editor extends EventEmitter<EditorEventMap> {
    *   - [3] fonts - Object containing font files from the DOCX
    */
   static async loadXmlData(
-    fileSource: File | Blob | Buffer,
+    fileSource: File | Blob | Buffer | ArrayBuffer,
+    isNode?: boolean,
+    options?: { password?: string },
+  ): Promise<
+    [DocxFileEntry[], Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, Uint8Array | null]
+  >;
+  static async loadXmlData(
+    fileSource: File | Blob | Buffer | ArrayBuffer | null | undefined,
+    isNode?: boolean,
+    options?: { password?: string },
+  ): Promise<
+    | [DocxFileEntry[], Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, Uint8Array | null]
+    | undefined
+  >;
+  static async loadXmlData(
+    fileSource: File | Blob | Buffer | ArrayBuffer | null | undefined,
     isNode: boolean = false,
     options?: { password?: string },
   ): Promise<
@@ -3707,11 +3722,11 @@ export class Editor extends EventEmitter<EditorEventMap> {
   /**
    * Replace the current file
    */
-  async replaceFile(newFile: File | Blob | Buffer, options?: { password?: string }): Promise<void> {
+  async replaceFile(newFile: File | Blob | Buffer | ArrayBuffer, options?: { password?: string }): Promise<void> {
     this.setOptions({ annotations: true });
     const [docx, media, mediaFiles, fonts, decryptedData] = (await Editor.loadXmlData(newFile, false, options))!;
     this.setOptions({
-      fileSource: decryptedData ?? newFile,
+      fileSource: decryptedData ?? (newFile instanceof ArrayBuffer ? new Blob([newFile]) : newFile),
       content: docx,
       media,
       mediaFiles,

packages/super-editor/src/editors/v1/core/commands/core-command-map.d.ts

@@ -55,7 +55,7 @@ type CoreCommandNames =
   | 'insertTableAt'
   | 'getSelectionMarks';
 
-type CoreCommandSignatures = {
+export type CoreCommandSignatures = {
   [K in CoreCommandNames]: ExtractCommandSignature<(typeof CoreCommandExports)[K]>;
 };
 

packages/super-editor/src/editors/v1/core/types/ChainedCommands.ts

@@ -2,29 +2,29 @@ import type { Transaction, EditorState } from 'prosemirror-state';
 import type { EditorView } from 'prosemirror-view';
 import type { Editor } from '../Editor.js';
 
+// Command interfaces — imported directly for reliable cross-package typing.
+// Module augmentation doesn't survive the npm package boundary, so we
+// compose EditorCommands as an explicit intersection of all command interfaces.
+import type { CoreCommandSignatures } from '../commands/core-command-map.js';
+import type { CommentCommands } from '../../extensions/types/comment-commands.js';
+import type { FormattingCommandAugmentations } from '../../extensions/types/formatting-commands.js';
+import type { HistoryLinkTableCommandAugmentations } from '../../extensions/types/history-link-table-commands.js';
+import type { SpecializedCommandAugmentations } from '../../extensions/types/specialized-commands.js';
+import type { ParagraphCommands } from '../../extensions/types/paragraph-commands.js';
+import type { BlockNodeCommands } from '../../extensions/types/block-node-commands.js';
+import type { ImageCommands } from '../../extensions/types/image-commands.js';
+import type { MiscellaneousCommands } from '../../extensions/types/miscellaneous-commands.js';
+import type { TrackChangesCommands } from '../../extensions/types/track-changes-commands.js';
+
 /**
  * Map of built-in command names to their parameter signatures.
- * Extensions can augment this interface to add more precise types.
- * Currently empty because built-in focus/blur are exposed directly on Editor,
- * not via `editor.commands`. Populate here when core commands are added.
+ * Populated via core-command-map.d.ts module augmentation.
  */
 export interface CoreCommandMap {}
 
 /**
  * Map of extension command names to their parameter signatures.
- * Each extension should augment this interface when adding typed commands.
- */
-/**
- * Map of extension command names to their parameter signatures.
- * Extensions should augment this interface via module augmentation, e.g.:
- *
- * ```ts
- * declare module '@core/types/ChainedCommands.js' {
- *   interface ExtensionCommandMap {
- *     setFontSize: (fontSize: string | number) => boolean;
- *   }
- * }
- * ```
+ * Kept for backward compat with any external module augmentations.
  */
 export interface ExtensionCommandMap {}
 
@@ -98,9 +98,25 @@ export type CoreCommands = Pick<KnownCommandRecord, keyof CoreCommandMap>;
 export type ExtensionCommands = Pick<KnownCommandRecord, keyof ExtensionCommandMap>;
 
 /**
- * All available editor commands
+ * All available editor commands.
+ *
+ * Composed from explicit imports of each command interface for reliable
+ * cross-package typing (module augmentation doesn't survive the npm boundary).
+ * The Record<string, AnyCommand> fallback allows dynamic/plugin commands.
  */
-export type EditorCommands = CoreCommands & ExtensionCommands & Record<string, AnyCommand>;
+export type EditorCommands = CoreCommands &
+  ExtensionCommands &
+  CoreCommandSignatures &
+  CommentCommands &
+  FormattingCommandAugmentations &
+  HistoryLinkTableCommandAugmentations &
+  SpecializedCommandAugmentations &
+  ParagraphCommands &
+  BlockNodeCommands &
+  ImageCommands &
+  MiscellaneousCommands &
+  TrackChangesCommands &
+  Record<string, AnyCommand>;
 
 /**
  * Command props made available to every command handler.

packages/super-editor/src/editors/v1/core/types/EditorConfig.ts

@@ -84,18 +84,39 @@ export type LinkPopoverResolution =
  */
 export type LinkPopoverResolver = (ctx: LinkPopoverContext) => LinkPopoverResolution | null | undefined;
 
+/**
+ * Configuration for a font option in the toolbar font picker.
+ *
+ * Each entry represents a selectable font that appears in the toolbar dropdown.
+ * The `props.style.fontFamily` value is applied to text when the font is selected.
+ */
+export interface FontConfig {
+  /** Unique key identifying this font */
+  key: string;
+  /** Display label shown in the font picker dropdown */
+  label: string;
+  /** Font weight (e.g. 400 for normal, 700 for bold) */
+  fontWeight?: number;
+  /** CSS properties applied when this font is selected */
+  props?: {
+    style?: {
+      fontFamily?: string;
+    };
+  };
+}
+
 /**
  * User information for collaboration
  */
 export interface User {
   /** The user's name */
-  name: string;
+  name?: string;
 
   /** The user's email */
-  email: string;
+  email?: string;
 
   /** The user's photo URL */
-  image: string | null;
+  image?: string | null;
 
   /**
    * Explicit permission-range principal identifiers for this user.

packages/super-editor/src/editors/v1/core/types/EditorEvents.ts

@@ -16,10 +16,63 @@ export interface FontsResolvedPayload {
 }
 
 /**
- * Comment data structure
+ * A structured element within a comment body.
+ *
+ * Comment bodies are stored as an array of elements, each representing
+ * a paragraph or nested content node. This mirrors ProseMirror-style
+ * node structure used throughout SuperDoc.
+ */
+export interface CommentElement {
+  /** Node type (e.g. 'paragraph', 'text') */
+  type: string;
+  /** Text content for leaf nodes */
+  text?: string;
+  /** Nested child elements */
+  content?: CommentElement[];
+  /** Additional element properties */
+  [key: string]: unknown;
+}
+
+/**
+ * A comment object as emitted through editor events and accepted by `exportDocx()`.
+ *
+ * This is the canonical comment shape used across SuperDoc:
+ * - Emitted via `commentsLoaded` and `commentsUpdate` events
+ * - Accepted by `exportDocx({ comments })` for saving
+ * - Produced by DOCX import in SuperConverter
  */
 export interface Comment {
-  id: string;
+  /** Unique identifier for this comment */
+  commentId: string;
+  /** Timestamp when the comment was created (ms since epoch) */
+  createdTime: number | null;
+  /** Display name of the comment author */
+  creatorName: string | null;
+  /** Email address of the comment author */
+  creatorEmail: string | null;
+  /** Avatar URL of the comment author */
+  creatorImage?: string | null;
+  /** Structured body content of the comment */
+  elements: CommentElement[];
+  /** Whether the comment thread is resolved/done */
+  isDone: boolean;
+  /** Parent comment ID for threaded replies */
+  parentCommentId?: string | null;
+  /** Original ID from the imported DOCX (used for round-trip fidelity) */
+  importedId?: string | null;
+  /** ProseMirror JSON representation of the comment body */
+  commentJSON?: unknown;
+  /** Plain text content of the comment */
+  commentText?: string | null;
+  /** Whether this is an internal/private comment */
+  isInternal?: boolean;
+  /** Whether this comment is associated with a tracked change */
+  trackedChange?: boolean;
+  /** The document/file ID this comment belongs to */
+  fileId?: string | null;
+  /** The document ID this comment belongs to */
+  documentId?: string | null;
+  /** Additional fields from the host application */
   [key: string]: unknown;
 }
 
@@ -51,6 +104,9 @@ export interface PaginationPayload {
   [key: string]: unknown;
 }
 
+/**
+ * Payload for document mode change events
+ */
 export interface DocumentModeChangePayload {
   editor: Editor;
   documentMode: 'editing' | 'viewing' | 'suggesting';

packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/addMarkStep.js

@@ -105,9 +105,9 @@ export const addMarkStep = ({ state, step, newTr, doc, user, date }) => {
         const newFormatMark = state.schema.marks[TrackFormatMarkName].create({
           id: wid,
           sourceId: formatChangeMark?.attrs?.sourceId || '',
-          author: user.name,
-          authorEmail: user.email,
-          authorImage: user.image,
+          author: user.name || '',
+          authorEmail: user.email || '',
+          authorImage: user.image || '',
           date,
           before,
           after,

packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/markDeletion.js

@@ -44,9 +44,9 @@ export const markDeletion = ({ tr, from, to, user, date, id: providedId }) => {
 
   const deletionMark = tr.doc.type.schema.marks[TrackDeleteMarkName].create({
     id,
-    author: user.name,
-    authorEmail: user.email,
-    authorImage: user.image,
+    author: user.name || '',
+    authorEmail: user.email || '',
+    authorImage: user.image || '',
     date,
   });