diff --git a/packages/superdoc/AGENTS.md b/packages/superdoc/AGENTS.md index 4009880891..721b5166a8 100644 --- a/packages/superdoc/AGENTS.md +++ b/packages/superdoc/AGENTS.md @@ -238,6 +238,28 @@ superdoc.on('editorCreate', ({ editor }) => { For backend or AI agent workflows, use the [SDK](https://docs.superdoc.dev/document-engine/sdks), [CLI](https://docs.superdoc.dev/document-engine/cli), or [MCP server](https://docs.superdoc.dev/document-engine/ai-agents/mcp-server) instead of browser editor access. +## Contributing to the public surface + +If you're adding, removing, or moving a name on the `superdoc` root entry, the source of truth is `packages/superdoc/src/public/index.ts`. It is organized in three tiers per SD-3212: + +1. **Supported root** — documented public API; first-class root surface. Clean re-exports. +2. **Legacy root** — typed for backward compatibility; not the recommended path. Per-name `@deprecated` JSDoc only where a real replacement exists (e.g. `editor.commands.*` → `editor.doc.*` Document API). Section-level framing carries "legacy compat" intent when no replacement exists. +3. **Internal candidate** — accidental implementation leak. Kept typed under compat re-export with `@internal` so a future major can remove it. Only exists at root because at least one supported/legacy export reaches it transitively. + +When changing the surface, every PR must also update: + +- `tests/consumer-typecheck/snapshots/superdoc-root-classification.json` (bucket + rationale per name). +- `tests/consumer-typecheck/snapshots/superdoc-root-exports.json` (the 4-source no-growth lock). +- `packages/superdoc/scripts/verify-public-facade-emit.cjs` `FACADE_ENTRIES['root (./index)'].expectedNames`. + +Three CI gates enforce consistency and will fail the build if any of these drift: + +- `verify-public-facade-emit.cjs` — symbol set, ESM/CJS parity, leak grep. +- `snapshot-superdoc-root-exports.mjs --check` — 4-source no-growth lock. +- `check-root-classification-closure.mjs` — no supported/legacy export references an internal-candidate type (dependency-closure rule). + +For overrides on the closure gate (rare; only DOM globals / upstream / generic utility types), add an entry to `OVERRIDES` in `check-root-classification-closure.mjs` with a reason string ≥ 20 chars. + ## Knowledge corrections If your training data mentions SuperDoc, note these updates: diff --git a/packages/superdoc/scripts/ensure-types.cjs b/packages/superdoc/scripts/ensure-types.cjs index 8dc51c79b4..cab2a574a8 100644 --- a/packages/superdoc/scripts/ensure-types.cjs +++ b/packages/superdoc/scripts/ensure-types.cjs @@ -250,39 +250,46 @@ if (!hasSuperDocExport) { process.exit(1); } -// @superdoc/common is a private workspace package, so consumers can't -// resolve a bare `from '@superdoc/common'` import. The main entry -// (superdoc/src/index.d.ts) imports runtime values from it — DOCX/PDF/ -// HTML constants, getFileObject, compareVersions, BlankDOCX (the last -// from a Vite `?url` import that vite-plugin-dts can't type). Strip -// that import statement and inline ambient declarations for those -// values. Type-only imports of @superdoc/common from other dist files -// are handled separately by the RELOCATION_RULES rewriter below, which +// @superdoc/common is a private workspace package, so consumers can't resolve +// bare or deep `@superdoc/common` imports from emitted declarations. The root +// entry and the path-as-contract public facade both expose a small set of +// runtime values from common (DOCX/PDF/HTML constants, getFileObject, +// compareVersions, BlankDOCX). Strip those imports and inline declarations for +// the exported names. Type-only imports of @superdoc/common from other dist +// files are handled separately by the RELOCATION_RULES rewriter below, which // maps bare @superdoc/common to dist/shared/common/comments-types.d.ts. -const hadWorkspaceImport = content.includes('@superdoc/common'); -if (hadWorkspaceImport) { - // Replace the @superdoc/common import with inline declarations - content = content.replace( - /import\s*\{[^}]*\}\s*from\s*['"]@superdoc\/common['"];?\s*\n?/g, - '', - ); +function inlineCommonRuntimeDeclarations(filePath) { + let fileContent = fs.readFileSync(filePath, 'utf8'); + if (!fileContent.includes('@superdoc/common')) return false; + + fileContent = fileContent + .replace(/import\s*\{[^}]*\}\s*from\s*['"]@superdoc\/common['"];?\s*\n?/g, '') + .replace(/import\s*\{[^}]*\}\s*from\s*['"]@superdoc\/common\/document-types['"];?\s*\n?/g, '') + .replace(/import\s*\{[^}]*\}\s*from\s*['"]@superdoc\/common\/helpers\/get-file-object['"];?\s*\n?/g, '') + .replace(/import\s*\{[^}]*\}\s*from\s*['"]@superdoc\/common\/helpers\/compare-superdoc-versions['"];?\s*\n?/g, ''); + + const hasExportedBlankDocxDeclaration = /\bexport\s+declare\s+const\s+BlankDOCX\b/.test(fileContent); + const declarations = [ + fileContent.includes('DOCX') && "declare const DOCX: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';", + fileContent.includes('PDF') && "declare const PDF: 'application/pdf';", + fileContent.includes('HTML') && "declare const HTML: 'text/html';", + fileContent.includes('getFileObject') && 'declare function getFileObject(fileUrl: string, name: string, type: string): Promise;', + fileContent.includes('compareVersions') && 'declare function compareVersions(version1: string, version2: string): -1 | 0 | 1;', + fileContent.includes('BlankDOCX') && !hasExportedBlankDocxDeclaration && '/** URL to the blank DOCX template */', + fileContent.includes('BlankDOCX') && !hasExportedBlankDocxDeclaration && 'declare const BlankDOCX: string;', + ].filter(Boolean); + + fs.writeFileSync(filePath, `${declarations.join('\n')}\n${fileContent}`); + return true; +} - // BlankDOCX comes from a Vite ?url import (resolves to a string at runtime) - // Declare it since vite-plugin-dts can't generate types for ?url imports - const inlineDeclarations = [ - '/** Document MIME type constants */', - "declare const DOCX: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';", - "declare const PDF: 'application/pdf';", - "declare const HTML: 'text/html';", - 'declare function getFileObject(fileUrl: string, name: string, type: string): Promise;', - 'declare function compareVersions(version1: string, version2: string): -1 | 0 | 1;', - '/** URL to the blank DOCX template */', - 'declare const BlankDOCX: string;', - ].join('\n'); - - content = inlineDeclarations + '\n' + content; - fs.writeFileSync(indexPath, content); - console.log('[ensure-types] ✓ Inlined @superdoc/common types'); +const commonInlineTargets = [ + path.join(distRoot, 'superdoc/src/index.d.ts'), + path.join(distRoot, 'superdoc/src/public/index.d.ts'), +]; +const inlinedCommonTargets = commonInlineTargets.filter((target) => fs.existsSync(target) && inlineCommonRuntimeDeclarations(target)); +if (inlinedCommonTargets.length) { + console.log(`[ensure-types] ✓ Inlined @superdoc/common runtime declarations in ${inlinedCommonTargets.length} entry point(s)`); } // --------------------------------------------------------------------------- diff --git a/packages/superdoc/scripts/verify-public-facade-emit.cjs b/packages/superdoc/scripts/verify-public-facade-emit.cjs index 4b450596ad..6bd32b0a70 100644 --- a/packages/superdoc/scripts/verify-public-facade-emit.cjs +++ b/packages/superdoc/scripts/verify-public-facade-emit.cjs @@ -77,52 +77,223 @@ try { // this gate. Link the PR to SD-3175 (path-as-contract umbrella) for // reviewer sign-off when growth is intentional. const FACADE_ENTRIES = [ - // SD-3178 + SD-3185: root facade. The supported programmatic surface - // is the Document API (`editor.doc.*`); see `packages/superdoc/AGENTS.md` - // and the @deprecated tags on `editor.commands` in `Editor.ts`. The - // 20 Document API types preserved here mirror the JSDoc @typedef block - // in `packages/superdoc/src/index.js` and the assertions in - // `tests/consumer-typecheck/src/all-public-types.ts` — they were already - // typed via the root entry; this just makes the path-as-contract - // version explicit. - // - // EditorCommands stays in the surface for backward compatibility but is - // tagged @deprecated at the re-export site. The command-signature probe - // continues to run on this entry: it is now a *legacy command-signature - // compatibility check* (catches SD-2965-style augmentation drops on the - // deprecated surface) rather than a guarantee about supported API. + // SD-3212: root facade re-curated from the classification artifact. + // expectedNames intentionally mirrors + // tests/consumer-typecheck/snapshots/superdoc-root-classification.json. + // The root entry keeps supported public API, legacy public compatibility, + // and internal-candidate compat names typed until a major-version cleanup. + // The command-signature probe continues to run on this entry: it is a + // *legacy command-signature compatibility check* (catches SD-2965-style + // augmentation drops on the deprecated surface) rather than a guarantee + // about supported API. { name: 'root (./index)', esm: path.join(PUBLIC_DIST, 'index.d.ts'), cjs: path.join(PUBLIC_DIST, 'index.d.cts'), expectedNames: [ + 'AIWriter', + 'AnnotatorHelpers', + 'assertNodeType', + 'AwarenessState', + 'BinaryData', + 'BlankDOCX', 'BlockNavigationAddress', 'BlocksListResult', 'BookmarkAddress', 'BookmarkInfo', + 'BoundingRect', + 'buildTheme', + 'CanObject', + 'ChainableCommandObject', + 'ChainedCommand', + 'CollaborationConfig', + 'CollaborationProvider', + 'Command', + 'CommandProps', + 'Comment', 'CommentAddress', + 'CommentConfig', + 'CommentElement', + 'CommentLocationsPayload', + 'CommentsPayload', + 'CommentsPluginKey', + 'CommentsType', + 'compareVersions', 'Config', + 'ContextMenu', + 'ContextMenuConfig', + 'ContextMenuContext', + 'ContextMenuItem', + 'ContextMenuSection', + 'CoreCommandMap', + 'createTheme', + 'createZip', + 'defineMark', + 'defineNode', + 'DirectSurfaceRequest', + 'DocRange', 'DocumentApi', + 'DocumentMode', 'DocumentProtectionState', + 'DOCX', + 'DocxFileEntry', + 'DocxZipper', 'Editor', 'EditorCommands', + 'EditorEventMap', + 'EditorExtension', + 'EditorLifecycleState', + 'EditorOptions', + 'EditorState', + 'EditorSurface', + 'EditorTransactionEvent', + 'EditorUpdateEvent', + 'EditorView', 'EntityAddress', + 'ExportDocxParams', + 'ExportFormat', + 'ExportOptions', + 'ExportParams', + 'ExportType', + 'ExtensionCommandMap', + 'Extensions', + 'ExternalPopoverRenderContext', + 'ExternalSurfaceRenderContext', + 'fieldAnnotationHelpers', + 'FieldValue', + 'FindReplaceConfig', + 'FindReplaceContext', + 'FindReplaceHandle', + 'FindReplaceRenderContext', + 'FindReplaceResolution', + 'FlowBlock', + 'FlowMode', + 'FontConfig', + 'FontsResolvedPayload', + 'getActiveFormatting', + 'getAllowedImageDimensions', + 'getFileObject', + 'getMarksFromSelection', + 'getRichTextExtensions', + 'getSchemaIntrospection', + 'getStarterExtensions', + 'HTML', + 'ImageDeselectedEvent', + 'ImageSelectedEvent', + 'IntentSurfaceRequest', + 'isMarkType', + 'isNodeType', + 'Layout', + 'LayoutEngineOptions', + 'LayoutError', + 'LayoutFragment', + 'LayoutMetrics', + 'LayoutMode', + 'LayoutPage', + 'LayoutState', + 'LayoutUpdatePayload', + 'LinkPopoverContext', + 'LinkPopoverResolution', + 'LinkPopoverResolver', + 'ListDefinitionsPayload', + 'Measure', + 'Modules', 'NavigableAddress', + 'OpenOptions', + 'PageMargins', + 'PageSize', + 'PageStyles', + 'PaginationPayload', + 'PaintSnapshot', + 'PartChangedEvent', + 'PartId', + 'PartSectionId', + 'PasswordPromptAttemptResult', + 'PasswordPromptConfig', + 'PasswordPromptContext', + 'PasswordPromptHandle', + 'PasswordPromptRenderContext', + 'PasswordPromptResolution', + 'PDF', + 'PermissionParams', + 'PositionHit', + 'PresenceOptions', + 'PresentationEditor', + 'PresentationEditorOptions', + 'ProofingCapabilities', + 'ProofingCheckRequest', + 'ProofingCheckResult', + 'ProofingConfig', + 'ProofingError', + 'ProofingIssue', + 'ProofingIssueKind', + 'ProofingProvider', + 'ProofingSegment', + 'ProofingSegmentMetadata', + 'ProofingStatus', + 'ProseMirrorJSON', + 'ProtectionChangeSource', + 'RangeRect', + 'registeredHandlers', + 'RemoteCursorsRenderPayload', + 'RemoteCursorState', + 'RemoteUserInfo', + 'ResolvedFindReplaceTexts', + 'ResolvedPasswordPromptTexts', 'ResolveRangeOutput', + 'SaveOptions', + 'Schema', 'ScrollIntoViewInput', 'ScrollIntoViewOutput', + 'SearchMatch', + 'SectionHelpers', + 'SectionMetadata', 'SelectionApi', + 'SelectionCommandContext', 'SelectionCurrentInput', + 'SelectionHandle', 'SelectionInfo', + 'SlashMenu', 'StoryLocator', + 'SuperConverter', 'SuperDoc', + 'SuperDocLayoutEngineOptions', + 'SuperDocTelemetryConfig', + 'SuperEditor', + 'superEditorHelpers', + 'SuperInput', + 'SuperToolbar', + 'SurfaceComponentProps', + 'SurfaceFloatingPlacement', + 'SurfaceHandle', + 'SurfaceMode', + 'SurfaceOutcome', + 'SurfaceRequest', + 'SurfaceResolution', + 'SurfaceResolver', + 'SurfacesModuleConfig', + 'TelemetryEvent', 'TextAddress', 'TextSegment', 'TextTarget', + 'Toolbar', + 'TrackChangesBasePluginKey', + 'trackChangesHelpers', + 'TrackChangesModuleConfig', 'TrackedChangeAddress', + 'TrackedChangesMode', + 'TrackedChangesOverrides', + 'Transaction', + 'UnsupportedContentItem', + 'UpgradeToCollaborationOptions', + 'User', + 'ViewingVisibilityConfig', + 'ViewLayout', + 'ViewOptions', + 'VirtualizationOptions', ], runsCommandSignatureProbe: true, - ticket: 'SD-3185', + ticket: 'SD-3212', }, { name: 'legacy/headless-toolbar', diff --git a/packages/superdoc/src/public/index.ts b/packages/superdoc/src/public/index.ts index 94f4ff9452..c9eb655073 100644 --- a/packages/superdoc/src/public/index.ts +++ b/packages/superdoc/src/public/index.ts @@ -1,96 +1,290 @@ /** * SuperDoc public facade: root entry. * - * SD-3178 + SD-3185 (Phase 3 of SD-3175). The path-as-contract source of - * truth for `superdoc` consumers: anything exported here is part of the - * public contract: either supported public API or explicitly documented - * legacy compatibility. Anything outside is implementation detail. Phase - * 4 (the contract switch) flips `package.json#exports` to point at the - * emitted declarations under this tree. + * SD-3212 PR B (Phase 4b re-curation) under SD-3175. This file mirrors + * the classification artifact at + * tests/consumer-typecheck/snapshots/superdoc-root-classification.json * - * Surface organization: - * - * 1. **Configuration and lifecycle.** `SuperDoc` class + its `Config`. - * Editor instance type (`Editor`) plus the Document API surface - * reachable as `editor.doc.*`. - * 2. **Document API (recommended programmatic surface).** `DocumentApi` - * and the supporting selection / address / range / bookmark / block - * / protection types already typed by today's `superdoc` root entry. - * Per `packages/superdoc/AGENTS.md` and the `@deprecated` tags on - * `editor.commands` in `Editor.ts`: this is the supported way to - * read and mutate document content programmatically. - * - * Caveat: Document API does not cover every legacy editor command - * 1:1 today. Field annotations, document section management, AI - * marks, search-session UI state, and several format/diff helpers - * exist as runtime commands without a direct Document API analogue. - * The legacy command surface is being audited against the Document - * API in a separate ticket; consumers reaching for those features - * should expect to keep using `editor.commands.*` for now. - * 3. **Legacy compat — typed for backward compat, not advertised.** - * `EditorCommands` and the command-augmentation infrastructure - * type the deprecated `editor.commands.*` surface. They remain - * exported so existing TS consumers keep compiling; new code should - * use `editor.doc.*` (Document API). + * Three tiers: + * 1. Supported root: documented public API; first-class root surface. + * 2. Legacy root: typed for backward compatibility; not the recommended + * path. Per-name @deprecated JSDoc only where a replacement exists. + * 3. Internal candidate: accidental implementation leak; kept typed under + * compat re-export with @internal so a future major can remove it. + * Today these only exist at root because at least one supported or + * legacy export reaches them transitively (see closure gate at + * tests/consumer-typecheck/check-root-classification-closure.mjs). * * Rules for this file: - * - AIDEV-NOTE: Named exports only. No `export *` from implementation - * barrels. `export *` re-introduces the leak this facade exists to - * close — see SD-3175 (path-as-contract umbrella) for context. - * - Explicit `.js` source specifiers (the dts plugin emits `.js` - * specifiers; source consistency keeps the two aligned). - * - AIDEV-NOTE: Adding or removing an export here is a deliberate - * public-API decision. In the same PR, update the `expectedNames` - * for the `root (./index)` entry in `FACADE_ENTRIES` inside - * `packages/superdoc/scripts/verify-public-facade-emit.cjs` and - * link to SD-3175 (or a child ticket) for reviewer sign-off. - * Skipping the expectedNames update fails the postbuild gate. - * - AIDEV-NOTE: Document API additions are encouraged (it is the - * supported programmatic contract). Editor-command additions are - * not — that surface is deprecated. New entries that type the - * `editor.commands.*` surface should be flagged in review. + * - AIDEV-NOTE: Named exports only. No `export *`. Changing the surface + * here updates the classification artifact and the + * verify-public-facade-emit.cjs FACADE_ENTRIES['root (./index)'].expectedNames + * in the same PR. Skipping either fails the postbuild gate or the + * consumer-typecheck snapshot. + * - The CI closure gate enforces that no supported-root or legacy-root + * export references an internal-candidate root symbol in its declared + * type. Overrides require a reason string per + * check-root-classification-closure.mjs. + * - Per-name `@deprecated` JSDoc only fires for names with a real + * migration target. Section-level framing carries the "legacy compat" + * intent for names where no replacement exists today (avoids + * "deprecated to nothing" noise in customer IDEs). */ -// (1) Configuration and lifecycle. +// The common package is workspace-private. Source imports stay readable here; +// ensure-types.cjs strips and inlines the emitted declarations so consumers +// never resolve @superdoc/common from the packed package. +import { DOCX, PDF, HTML, getFileObject, compareVersions } from '@superdoc/common'; +// @ts-expect-error Vite resolves DOCX asset URL imports; plain tsc does not. +import BlankDOCXAsset from '@superdoc/common/data/blank.docx?url'; +/** URL to the blank DOCX template. */ +export const BlankDOCX: string = BlankDOCXAsset; +export { DOCX, PDF, HTML, getFileObject, compareVersions }; + +// ============================================================================= +// SUPPORTED ROOT (132) +// First-class public API. Documented, advertised, supported long-term. +// ============================================================================= + +// Source: ./core/SuperDoc.js export { SuperDoc } from '../core/SuperDoc.js'; + +// Source: ./core/theme/create-theme.ts +export { buildTheme } from '../core/theme/create-theme.js'; +export { createTheme } from '../core/theme/create-theme.js'; + +// Type source: ./core/types/index.js +export type { AwarenessState } 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'; +export type { CommentAddress } from '../core/types/index.js'; +export type { CommentsType } from '../core/types/index.js'; export type { Config } from '../core/types/index.js'; +export type { DirectSurfaceRequest } from '../core/types/index.js'; +export type { DocRange } from '../core/types/index.js'; +export type { DocumentMode } from '../core/types/index.js'; +export type { EditorSurface } from '../core/types/index.js'; +export type { EditorTransactionEvent } from '../core/types/index.js'; +export type { EditorUpdateEvent } from '../core/types/index.js'; +export type { ExportParams } from '../core/types/index.js'; +export type { ExportType } from '../core/types/index.js'; +export type { ExternalPopoverRenderContext } from '../core/types/index.js'; +export type { ExternalSurfaceRenderContext } from '../core/types/index.js'; +export type { FindReplaceContext } from '../core/types/index.js'; +export type { FindReplaceHandle } from '../core/types/index.js'; +export type { FindReplaceRenderContext } from '../core/types/index.js'; +export type { FindReplaceResolution } from '../core/types/index.js'; +export type { IntentSurfaceRequest } from '../core/types/index.js'; +export type { Modules } from '../core/types/index.js'; +export type { NavigableAddress } from '../core/types/index.js'; +export type { PasswordPromptAttemptResult } from '../core/types/index.js'; +export type { PasswordPromptConfig } from '../core/types/index.js'; +export type { PasswordPromptContext } from '../core/types/index.js'; +export type { PasswordPromptHandle } from '../core/types/index.js'; +export type { PasswordPromptRenderContext } from '../core/types/index.js'; +export type { PasswordPromptResolution } from '../core/types/index.js'; +export type { ResolvedFindReplaceTexts } from '../core/types/index.js'; +export type { ResolvedPasswordPromptTexts } from '../core/types/index.js'; +export type { SearchMatch } from '../core/types/index.js'; +export type { StoryLocator } from '../core/types/index.js'; +export type { SuperDocLayoutEngineOptions } from '../core/types/index.js'; +export type { SuperDocTelemetryConfig } from '../core/types/index.js'; +export type { SurfaceComponentProps } from '../core/types/index.js'; +export type { SurfaceFloatingPlacement } from '../core/types/index.js'; +export type { SurfaceHandle } from '../core/types/index.js'; +export type { SurfaceMode } from '../core/types/index.js'; +export type { SurfaceOutcome } from '../core/types/index.js'; +export type { SurfaceRequest } from '../core/types/index.js'; +export type { SurfaceResolution } from '../core/types/index.js'; +export type { SurfaceResolver } from '../core/types/index.js'; +export type { SurfacesModuleConfig } from '../core/types/index.js'; +export type { TrackChangesModuleConfig } from '../core/types/index.js'; +export type { TrackedChangeAddress } from '../core/types/index.js'; +export type { UpgradeToCollaborationOptions } from '../core/types/index.js'; +export type { ViewingVisibilityConfig } from '../core/types/index.js'; + +// Source: ./helpers/schema-introspection.js +export { getSchemaIntrospection } from '../helpers/schema-introspection.js'; + +// `compareVersions`, `DOCX`, `getFileObject`, `HTML`, `PDF` and `BlankDOCX` +// from `@superdoc/common` are handled at the top of this file +// (import-then-export pattern; see comment there for rationale). + +// Source: @superdoc/super-editor +export { assertNodeType } from '@superdoc/super-editor'; +export { createZip } from '@superdoc/super-editor'; +export { defineMark } from '@superdoc/super-editor'; +export { defineNode } from '@superdoc/super-editor'; export { Editor } from '@superdoc/super-editor'; +export { Extensions } from '@superdoc/super-editor'; +export { getActiveFormatting } from '@superdoc/super-editor'; +export { getAllowedImageDimensions } from '@superdoc/super-editor'; +export { getMarksFromSelection } from '@superdoc/super-editor'; +export { getRichTextExtensions } from '@superdoc/super-editor'; +export { getStarterExtensions } from '@superdoc/super-editor'; +export { isMarkType } from '@superdoc/super-editor'; +export { isNodeType } from '@superdoc/super-editor'; -// (2) Document API — the recommended programmatic surface (`editor.doc.*`). -// This set mirrors the JSDoc `@typedef` block in `packages/superdoc/src/index.js` -// and is already covered by `tests/consumer-typecheck/src/all-public-types.ts`. -// It is not surface growth; it is preserving the current root type contract -// in the new path-as-contract facade. -export type { - DocumentApi, - SelectionApi, - SelectionInfo, - SelectionCurrentInput, - ScrollIntoViewInput, - ScrollIntoViewOutput, - ResolveRangeOutput, - TextTarget, - TextAddress, - TextSegment, - EntityAddress, - BlocksListResult, - BookmarkInfo, - BookmarkAddress, - BlockNavigationAddress, - CommentAddress, - TrackedChangeAddress, - NavigableAddress, - StoryLocator, - DocumentProtectionState, -} from '@superdoc/super-editor'; - -// (3) Legacy command-augmentation infrastructure — typed for backward -// compat, not advertised. -/** - * @deprecated Editor commands are deprecated and will be removed in a - * future version. Use the Document API via `editor.doc.*` for - * programmatic document reads and mutations. See - * `packages/superdoc/AGENTS.md` and the `@deprecated` tags on - * `editor.commands` in `Editor.ts` (lines 1411, 1597, 1605). - */ +// Type source: @superdoc/super-editor +export type { BinaryData } from '@superdoc/super-editor'; +export type { BlocksListResult } from '@superdoc/super-editor'; +export type { BookmarkInfo } from '@superdoc/super-editor'; +export type { CollaborationProvider } from '@superdoc/super-editor'; +export type { Comment } from '@superdoc/super-editor'; +export type { CommentConfig } from '@superdoc/super-editor'; +export type { CommentElement } from '@superdoc/super-editor'; +export type { CommentLocationsPayload } from '@superdoc/super-editor'; +export type { CommentsPayload } from '@superdoc/super-editor'; +export type { DocumentApi } from '@superdoc/super-editor'; +export type { DocumentProtectionState } from '@superdoc/super-editor'; +export type { DocxFileEntry } from '@superdoc/super-editor'; +export type { EditorEventMap } from '@superdoc/super-editor'; +export type { EditorLifecycleState } from '@superdoc/super-editor'; +export type { EntityAddress } from '@superdoc/super-editor'; +export type { ExportDocxParams } from '@superdoc/super-editor'; +export type { ExportFormat } from '@superdoc/super-editor'; +export type { ExportOptions } from '@superdoc/super-editor'; +export type { FieldValue } from '@superdoc/super-editor'; +export type { FontConfig } from '@superdoc/super-editor'; +export type { FontsResolvedPayload } from '@superdoc/super-editor'; +export type { ImageDeselectedEvent } from '@superdoc/super-editor'; +export type { ImageSelectedEvent } from '@superdoc/super-editor'; +export type { LinkPopoverContext } from '@superdoc/super-editor'; +export type { LinkPopoverResolution } from '@superdoc/super-editor'; +export type { LinkPopoverResolver } from '@superdoc/super-editor'; +export type { OpenOptions } from '@superdoc/super-editor'; +export type { PageMargins } from '@superdoc/super-editor'; +export type { PageSize } from '@superdoc/super-editor'; +export type { PageStyles } from '@superdoc/super-editor'; +export type { PartChangedEvent } from '@superdoc/super-editor'; +export type { PermissionParams } from '@superdoc/super-editor'; +export type { ProofingCapabilities } from '@superdoc/super-editor'; +export type { ProofingCheckRequest } from '@superdoc/super-editor'; +export type { ProofingCheckResult } from '@superdoc/super-editor'; +export type { ProofingConfig } from '@superdoc/super-editor'; +export type { ProofingError } from '@superdoc/super-editor'; +export type { ProofingIssue } from '@superdoc/super-editor'; +export type { ProofingIssueKind } from '@superdoc/super-editor'; +export type { ProofingProvider } from '@superdoc/super-editor'; +export type { ProofingSegment } from '@superdoc/super-editor'; +export type { ProofingSegmentMetadata } from '@superdoc/super-editor'; +export type { ProofingStatus } from '@superdoc/super-editor'; +export type { ProtectionChangeSource } from '@superdoc/super-editor'; +export type { ResolveRangeOutput } from '@superdoc/super-editor'; +export type { SaveOptions } from '@superdoc/super-editor'; +export type { ScrollIntoViewInput } from '@superdoc/super-editor'; +export type { ScrollIntoViewOutput } from '@superdoc/super-editor'; +export type { SelectionApi } from '@superdoc/super-editor'; +export type { SelectionCommandContext } from '@superdoc/super-editor'; +export type { SelectionCurrentInput } from '@superdoc/super-editor'; +export type { SelectionHandle } from '@superdoc/super-editor'; +export type { SelectionInfo } from '@superdoc/super-editor'; +export type { TextAddress } from '@superdoc/super-editor'; +export type { TextSegment } from '@superdoc/super-editor'; +export type { TextTarget } from '@superdoc/super-editor'; +export type { TrackedChangesMode } from '@superdoc/super-editor'; +export type { UnsupportedContentItem } from '@superdoc/super-editor'; +export type { User } from '@superdoc/super-editor'; +export type { ViewLayout } from '@superdoc/super-editor'; +export type { ViewOptions } from '@superdoc/super-editor'; + +// ============================================================================= +// LEGACY ROOT (60) +// Typed for backward compatibility. Not the recommended root story. +// Per-name @deprecated JSDoc applied below where a clear replacement exists. +// ============================================================================= + +// Type source: ./core/types/index.js +export type { ContextMenuConfig } from '../core/types/index.js'; +export type { ContextMenuContext } from '../core/types/index.js'; +export type { ContextMenuItem } from '../core/types/index.js'; +export type { ContextMenuSection } from '../core/types/index.js'; +export type { FindReplaceConfig } from '../core/types/index.js'; + +// BlankDOCX is handled via the import-then-export pattern at the top of this file. + +// Source: @superdoc/super-editor +export { AIWriter } from '@superdoc/super-editor'; +export { CommentsPluginKey } from '@superdoc/super-editor'; +export { ContextMenu } from '@superdoc/super-editor'; +export { DocxZipper } from '@superdoc/super-editor'; +export { fieldAnnotationHelpers } from '@superdoc/super-editor'; +export { PresentationEditor } from '@superdoc/super-editor'; +export { SlashMenu } from '@superdoc/super-editor'; +export { SuperConverter } from '@superdoc/super-editor'; +export { SuperEditor } from '@superdoc/super-editor'; +export { SuperInput } from '@superdoc/super-editor'; +export { SuperToolbar } from '@superdoc/super-editor'; +export { Toolbar } from '@superdoc/super-editor'; +export { TrackChangesBasePluginKey } from '@superdoc/super-editor'; + +// Type source: @superdoc/super-editor +export type { BoundingRect } from '@superdoc/super-editor'; +export type { CanObject } from '@superdoc/super-editor'; +export type { ChainableCommandObject } from '@superdoc/super-editor'; +export type { ChainedCommand } from '@superdoc/super-editor'; +export type { Command } from '@superdoc/super-editor'; +export type { CommandProps } from '@superdoc/super-editor'; +export type { CoreCommandMap } from '@superdoc/super-editor'; export type { EditorCommands } from '@superdoc/super-editor'; +export type { EditorExtension } from '@superdoc/super-editor'; +export type { EditorOptions } from '@superdoc/super-editor'; +export type { EditorState } from '@superdoc/super-editor'; +export type { EditorView } from '@superdoc/super-editor'; +export type { ExtensionCommandMap } from '@superdoc/super-editor'; +export type { FlowBlock } from '@superdoc/super-editor'; +export type { FlowMode } from '@superdoc/super-editor'; +export type { Layout } from '@superdoc/super-editor'; +export type { LayoutEngineOptions } from '@superdoc/super-editor'; +export type { LayoutError } from '@superdoc/super-editor'; +export type { LayoutFragment } from '@superdoc/super-editor'; +export type { LayoutMetrics } from '@superdoc/super-editor'; +export type { LayoutMode } from '@superdoc/super-editor'; +export type { LayoutPage } from '@superdoc/super-editor'; +export type { LayoutState } from '@superdoc/super-editor'; +export type { ListDefinitionsPayload } from '@superdoc/super-editor'; +export type { Measure } from '@superdoc/super-editor'; +export type { PaginationPayload } from '@superdoc/super-editor'; +export type { PaintSnapshot } from '@superdoc/super-editor'; +export type { PartId } from '@superdoc/super-editor'; +export type { PartSectionId } from '@superdoc/super-editor'; +export type { PositionHit } from '@superdoc/super-editor'; +export type { PresenceOptions } from '@superdoc/super-editor'; +export type { PresentationEditorOptions } from '@superdoc/super-editor'; +export type { ProseMirrorJSON } from '@superdoc/super-editor'; +export type { RangeRect } from '@superdoc/super-editor'; +export type { RemoteCursorState } from '@superdoc/super-editor'; +export type { RemoteUserInfo } from '@superdoc/super-editor'; +export type { Schema } from '@superdoc/super-editor'; +export type { SectionMetadata } from '@superdoc/super-editor'; +export type { TrackedChangesOverrides } from '@superdoc/super-editor'; +export type { Transaction } from '@superdoc/super-editor'; +export type { VirtualizationOptions } from '@superdoc/super-editor'; + +// ============================================================================= +// INTERNAL CANDIDATE (8) +// Should not be public long-term. Kept typed under compat re-export because +// at least one supported/legacy export reaches them transitively. Removal +// planned for a major-version cleanup (see SD-3212 follow-ups). +// ============================================================================= + +// Source: @superdoc/super-editor +/** @internal */ +export { AnnotatorHelpers } from '@superdoc/super-editor'; +/** @internal */ +export { registeredHandlers } from '@superdoc/super-editor'; +/** @internal */ +export { SectionHelpers } from '@superdoc/super-editor'; +/** @internal */ +export { helpers as superEditorHelpers } from '@superdoc/super-editor'; +/** @internal */ +export { trackChangesHelpers } from '@superdoc/super-editor'; + +// Type source: @superdoc/super-editor +/** @internal */ +export type { LayoutUpdatePayload } from '@superdoc/super-editor'; +/** @internal */ +export type { RemoteCursorsRenderPayload } from '@superdoc/super-editor'; +/** @internal */ +export type { TelemetryEvent } from '@superdoc/super-editor';