feat(docs): docs snippet typecheck for editor/superdoc/** + fix stale examples (SD-673)

[caio-pizzol]

Adds a CI-deterministic gate that catches the exact drift class #3503 had to fix manually: docs examples that teach the wrong typed shape. Existing runtime doctest extracts only the onReady body and runs it against a mocked host, so it never sees the destructure bug in the outer config - a typecheck does.

How it works:

• Extracts "Full Example" code blocks from apps/docs/editor/superdoc/** (JS + TS fences) via the existing extractExamples() (extended to keep fence language)
• Writes each snippet to a temp file, JS with // @ts-check, plus a shared placeholders.d.ts for docs idioms
• Runs tsc --noEmit --strict (allowJs + checkJs for JS) against packages/superdoc/dist via tsconfig paths
• Wired as the last stage of check:public:superdoc; also available standalone via pnpm --filter @superdoc/docs run check:types

Coverage delta: real docs API drift fixes across 4 docs files; 47 in-scope Full Example snippets now typecheck clean (was 0 before this PR). 1 example skipped (yjs + y-websocket upgrade-to-collaboration example: consumer BYO, not part of SuperDoc's typed surface - added to SKIP_IMPORTS).

Placeholder stubs (11 ambient declarations)

Pure test-infra; doesn't change any docs. Stubbed in a shared placeholders.d.ts so docs examples can reference common identifiers without inline declarations.

Kind	Identifiers
Files / strings	yourFile, file, doc1, doc2, content
Helper functions	cleanup, autoSave, adjustLayout, showOnlineUsers, updateUserCursors, showLockBanner

Real docs API drift fixes (4 files)

These are the typed-public-surface bugs the gate surfaced. None of them were caught at runtime because the runtime doctest doesn't typecheck.

File	Fix
methods.mdx	onReady: (superdoc) => → onReady: ({ superdoc }) => in 22 examples (typed payload is { superdoc }, not the instance)
methods.mdx	setActiveEditor example rewritten to capture editors via onEditorCreate (was reaching into Document.editor, not on the public type)
methods.mdx	search / goToSearchResult null guards on the optional SearchMatch[] | undefined return
methods.mdx	addCommentsList signature corrected to HTMLElement (was documented as string | HTMLElement; actual is HTMLElement)
methods.mdx	scrollToComment / scrollToElement: superdoc.editor → superdoc.activeEditor with null guards (activeEditor is Editor | null; editor doesn't exist as a public member); narrowed BlockNodeAddress before .nodeId; switched .entityId → .id on DiscoveryItem
methods.mdx	off example: handler annotated with /** @param {import('superdoc').SuperDocReadyPayload} payload */ so the standalone-handler shape pins to the typed payload
import-export.mdx	onReady: (superdoc) => → onReady: ({ superdoc }) => in 5 examples
import-export.mdx	Null guards on superdoc.activeEditor before .getHTML / .getJSON / .getMarkdown / .commands access
events.mdx	Subscribing-events handler now uses JSDoc to type the standalone handler
events.mdx	editor-update: null guard on the optional editor field (EditorUpdateEvent.editor?: Editor)
events.mdx	content-error: removed documentId from destructure (SuperDocContentErrorPayload is { error, editor }; no documentId)
events.mdx	comments-update: { type, data } → { type, comment, changes } (matches SuperDocCommentsUpdatePayload; same drift class as #3503)
events.mdx	awareness-update: { context, states } → { states, added, removed } (runtime emits superdoc not context; same drift class)
events.mdx	locked: added && lockedBy guard before reading .name (lockedBy: User | null)
events.mdx	pagination-update: removed pagination: true from Config example (no such field on the typed Config)
events.mdx	exception: rewrote to take payload and read payload.error, with a comment on narrowing the discriminated union (document/editor only exist on specific variants)
collaboration/configuration.mdx	lockedBy type cell: Object → User | null with a null-check note

Must stay the same: check:public:superdoc keeps passing.

Review:

• The new wrapper stage runs after build and depends on packages/superdoc/dist existing. CI builds dist before this stage; local devs need pnpm --filter superdoc build (or pnpm check:public:superdoc without --skip-build).
• If this fails locally, rebuild packages/superdoc/dist before debugging snippet errors. The gate checks against the built .d.ts, so a stale local dist produces misleading failures unrelated to the docs themselves.
• skipLibCheck: true is intentional in the temp tsconfig: this gate checks docs usage against the public surface, not library declarations (deep-type-audit-supported-root already covers that).

Verified:

• pnpm --filter @superdoc/docs run check:types → OK, 47/47 typechecked clean
• Synthetic regression: re-introducing one onReady: (superdoc) => locally produced the expected failure with correct source file:line
• pnpm check:public:superdoc --skip-build → PASS (12 ran, 1 skipped, 130.8s)

[linear-code]

SD-673

[github-actions]

📖 Docs preview: https://superdoc-caio-pizzol-sd-docs-snippet-typecheck.mintlify.app

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 57383eb0cb

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[cubic-dev-ai]

cubic analysis

No issues found across 9 files

Linked issue analysis

Linked issue: SD-673: TypeScript-first public API: SuperDoc and Document API

Status	Acceptance criteria	Notes
✅	Add a deterministic docs snippet type‑check gate that extracts 'Full Example' code blocks (JS/TS) and runs tsc --noEmit --strict (allowJs+checkJs for JS) against packages/superdoc/dist.	The PR adds apps/docs/__tests__/doctest-types.ts which extracts examples, prepares a temp project with a tsconfig pointing superdoc -> packages/superdoc/dist, and invokes tsc. It also extends extractExamples to record fence language for JS vs TS handling.
✅	Provide shared placeholder ambient declarations so examples can reference common doc identifiers without inlining stubs.	The script writes a shared placeholders.d.ts into the temp project with the declared identifiers used by docs examples.
✅	Fix docs examples so they match the typed public surface for SuperDoc (ex: onReady destructure, activeEditor null guards, corrected parameter/signature and event payload shapes) under apps/docs/editor/superdoc/**.	The PR updates multiple docs files to use the typed shapes (onReady: ({ superdoc }), null guards for activeEditor, corrected comments-list param type, corrected event payload destructures and guards). The diffs show these targeted fixes across the listed files.
✅	Wire the new gate into the public check flow and expose a local script to run the gate.	The PR adds a package script to run the types check and registers a docs-snippet-typecheck stage in the public contract check wrapper, so the gate runs as part of check:public:superdoc and can be run standalone.

_{Re-trigger cubic}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!