refactor(types): drain 85 type-bearing JSDoc entries from .ts source (SD-673)

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

@@ -216,8 +216,7 @@ const rangeIsTrackedInsertionOnly = (doc: PmNode, from: number, to: number): boo
 const getSingleTrackedInsertionMarkInRange = (doc: PmNode, from: number, to: number): PmMark | null => {
   if (!rangeIsTrackedInsertionOnly(doc, from, to)) return null;
 
-  /** @type {import('prosemirror-model').Mark[]} */
-  const insertionMarks = [];
+  const insertionMarks: PmMark[] = [];
   const seenIds = new Set<string>();
   doc.nodesBetween(from, to, (node, pos) => {
     if (!node.isInline || !node.isLeaf) return;
@@ -993,7 +992,6 @@ export class Editor extends EventEmitter<EditorEventMap> {
    * This prevents race conditions and ensures the editor is always in a valid state,
    * even when operations fail.
    *
-   * @template T - The return type of the operation
    * @param during - State to set while the operation is running
    * @param success - State to set if the operation succeeds
    * @param failure - State to set if the operation fails

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

@@ -23,7 +23,8 @@ export type EventCallback<Args extends unknown[] = unknown[]> = (...args: Args)
 
 /**
  * EventEmitter class is used to emit and subscribe to events.
- * @template EventMap - Map of event names to their argument types
+ *
+ * @typeParam EventMap - Map of event names to their argument types.
  */
 export class EventEmitter<EventMap extends DefaultEventMap = DefaultEventMap> {
   #events = new Map<keyof EventMap, EventCallback[]>();
@@ -32,7 +33,6 @@ export class EventEmitter<EventMap extends DefaultEventMap = DefaultEventMap> {
    * Subscribe to the event.
    * @param name Event name.
    * @param fn Callback.
-   * @returns {void}
    */
   on<K extends keyof EventMap>(name: K, fn: EventCallback<EventMap[K]>): void {
     const callbacks = this.#events.get(name);
@@ -44,7 +44,6 @@ export class EventEmitter<EventMap extends DefaultEventMap = DefaultEventMap> {
    * Emit event.
    * @param name Event name.
    * @param args Arguments to pass to each listener.
-   * @returns {void}
    */
   emit<K extends keyof EventMap>(name: K, ...args: EventMap[K]): void {
     const callbacks = this.#events.get(name);
@@ -78,7 +77,6 @@ export class EventEmitter<EventMap extends DefaultEventMap = DefaultEventMap> {
    * or all event subscriptions.
    * @param name Event name.
    * @param fn Callback.
-   * @returns {void}
    */
   off<K extends keyof EventMap>(name: K, fn?: EventCallback<EventMap[K]>): void {
     const callbacks = this.#events.get(name);
@@ -94,7 +92,6 @@ export class EventEmitter<EventMap extends DefaultEventMap = DefaultEventMap> {
    * Subscribe to an event that will be called only once.
    * @param name Event name.
    * @param fn Callback.
-   * @returns {void}
    */
   once<K extends keyof EventMap>(name: K, fn: EventCallback<EventMap[K]>): void {
     const wrapper = (...args: EventMap[K]) => {

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

@@ -4,6 +4,9 @@ import type { MaybeGetter } from './utilities/callOrGet.js';
 
 /**
  * Base configuration for extensions.
+ *
+ * @typeParam Options - Type for extension options.
+ * @typeParam Storage - Type for extension storage.
  */
 export interface ExtensionConfig<
   Options extends Record<string, unknown> = Record<string, never>,
@@ -24,8 +27,6 @@ export interface ExtensionConfig<
 
 /**
  * Extension class is used to create extensions.
- * @template Options - Type for extension options
- * @template Storage - Type for extension storage
  */
 export class Extension<
   Options extends Record<string, unknown> = Record<string, never>,

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

@@ -6,9 +6,10 @@ import type { AttributeSpec } from './Attribute.js';
 
 /**
  * Configuration for Mark extensions.
- * @template Options - Type for mark options
- * @template Storage - Type for mark storage
- * @template Attrs - Type for mark attributes (optional, enables typed addAttributes)
+ *
+ * @typeParam Options - Type for mark options.
+ * @typeParam Storage - Type for mark storage.
+ * @typeParam Attrs - Type for mark attributes (optional, enables typed addAttributes).
  */
 export interface MarkConfig<
   Options extends Record<string, unknown> = Record<string, never>,
@@ -39,9 +40,10 @@ export interface MarkConfig<
 
 /**
  * Mark class is used to create Mark extensions.
- * @template Options - Type for mark options
- * @template Storage - Type for mark storage
- * @template Attrs - Type for mark attributes (enables typed attribute access)
+ *
+ * @typeParam Options - Type for mark options.
+ * @typeParam Storage - Type for mark storage.
+ * @typeParam Attrs - Type for mark attributes (enables typed attribute access).
  */
 export class Mark<
   Options extends Record<string, unknown> = Record<string, never>,

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

@@ -69,9 +69,10 @@ export type RenderDOMFn = (props: {
 
 /**
  * Configuration for Node extensions.
- * @template Options - Type for node options
- * @template Storage - Type for node storage
- * @template Attrs - Type for node attributes (optional, enables typed addAttributes)
+ *
+ * @typeParam Options - Type for node options.
+ * @typeParam Storage - Type for node storage.
+ * @typeParam Attrs - Type for node attributes (optional, enables typed addAttributes).
  */
 export interface NodeConfig<
   Options extends Record<string, unknown> = Record<string, never>,
@@ -189,9 +190,10 @@ export interface NodeConfig<
 
 /**
  * Node class is used to create Node extensions.
- * @template Options - Type for node options
- * @template Storage - Type for node storage
- * @template Attrs - Type for node attributes (enables typed attribute access)
+ *
+ * @typeParam Options - Type for node options.
+ * @typeParam Storage - Type for node storage.
+ * @typeParam Attrs - Type for node attributes (enables typed attribute access).
  */
 export class Node<
   Options extends Record<string, unknown> = Record<string, never>,

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

@@ -2,10 +2,11 @@ import { Node } from './Node.js';
 import type { NodeConfig } from './Node.js';
 
 /**
- * Configuration for OXML Node extensions (extends NodeConfig)
- * @template Options - Type for node options
- * @template Storage - Type for node storage
- * @template Attrs - Type for node attributes (optional, enables typed addAttributes)
+ * Configuration for OXML Node extensions (extends NodeConfig).
+ *
+ * @typeParam Options - Type for node options.
+ * @typeParam Storage - Type for node storage.
+ * @typeParam Attrs - Type for node attributes (optional, enables typed addAttributes).
  */
 export interface OxmlNodeConfig<
   Options extends Record<string, unknown> = Record<string, never>,
@@ -21,9 +22,10 @@ export interface OxmlNodeConfig<
 
 /**
  * OxmlNode class extends Node with OXML-specific properties.
- * @template Options - Type for node options
- * @template Storage - Type for node storage
- * @template Attrs - Type for node attributes (enables typed attribute access)
+ *
+ * @typeParam Options - Type for node options.
+ * @typeParam Storage - Type for node storage.
+ * @typeParam Attrs - Type for node attributes (enables typed attribute access).
  */
 export class OxmlNode<
   Options extends Record<string, unknown> = Record<string, never>,

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

@@ -29,13 +29,12 @@
  *
  * @example
  * ```javascript
- * // In a JavaScript file with JSDoc:
+ * // In a JavaScript file with JSDoc: alias the BoldAttrs type at the top
+ * // of the file via a standard `typedef` JSDoc block pointing at
+ * // '@extensions/types/mark-attributes.js', then defineMark picks up the
+ * // attribute shape from there.
  * import { defineMark } from '@core/defineMark.js';
  *
- * /**
- *  * @typedef {import('@extensions/types/mark-attributes.js').BoldAttrs} BoldAttrs
- *  *\/
- *
  * export const Bold = defineMark({
  *   name: 'bold',
  *   // ...
@@ -50,11 +49,11 @@ import { Mark, type MarkConfig } from './Mark.js';
 /**
  * Type-safe factory for creating Mark extensions.
  *
- * @template Options - Extension options type
- * @template Storage - Extension storage type
- * @template Attrs - Mark attributes type
- * @param config - Mark configuration object
- * @returns A new Mark instance with the specified types
+ * @typeParam Options - Extension options type.
+ * @typeParam Storage - Extension storage type.
+ * @typeParam Attrs - Mark attributes type.
+ * @param config - Mark configuration object.
+ * @returns A new Mark instance with the specified types.
  */
 export function defineMark<
   Options extends Record<string, unknown> = Record<string, never>,

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

@@ -28,13 +28,12 @@
  *
  * @example
  * ```javascript
- * // In a JavaScript file with JSDoc:
+ * // In a JavaScript file with JSDoc: alias ParagraphAttrs at the top of
+ * // the file via a standard `typedef` JSDoc block pointing at
+ * // '@extensions/types/node-attributes.js', then defineNode picks up the
+ * // attribute shape from there.
  * import { defineNode } from '@core/defineNode.js';
  *
- * /**
- *  * @typedef {import('@extensions/types/node-attributes.js').ParagraphAttrs} ParagraphAttrs
- *  *\/
- *
  * export const Paragraph = defineNode({
  *   name: 'paragraph',
  *   // ...
@@ -49,11 +48,11 @@ import { Node, type NodeConfig } from './Node.js';
 /**
  * Type-safe factory for creating Node extensions.
  *
- * @template Options - Extension options type
- * @template Storage - Extension storage type
- * @template Attrs - Node attributes type
- * @param config - Node configuration object
- * @returns A new Node instance with the specified types
+ * @typeParam Options - Extension options type.
+ * @typeParam Storage - Extension storage type.
+ * @typeParam Attrs - Node attributes type.
+ * @param config - Node configuration object.
+ * @returns A new Node instance with the specified types.
  */
 export function defineNode<
   Options extends Record<string, unknown> = Record<string, never>,

packages/super-editor/src/editors/v1/core/helpers/getExtensionConfigField.ts

@@ -27,11 +27,12 @@ export interface ExtensionLike {
 /**
  * Get extension config field.
  * If the field is a function, it will be bound to the provided context.
+ *
+ * @typeParam T - The expected return type of the config field.
  * @param extension The Editor extension.
  * @param field The config field name.
  * @param context The context object to bind to function.
  * @returns The config field value or bound function.
- * @template T The expected return type of the config field.
  */
 export function getExtensionConfigField<T = unknown>(
   extension: ExtensionLike,

packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts

@@ -4940,7 +4940,6 @@ export class PresentationEditor extends EventEmitter {
    * This method encapsulates the common focus and blur logic used when
    * selecting both inline and block images.
    * @private
-   * @returns {void}
    */
   #focusEditorAfterImageSelection(): void {
     this.#shouldScrollSelectionIntoView = true;
@@ -6918,7 +6917,6 @@ export class PresentationEditor extends EventEmitter {
    * This method is called after layout completes to ensure cursor positioning
    * is based on stable layout data.
    *
-   * @returns {void}
    *
    * @remarks
    * Edge cases handled:

packages/superdoc/scripts/jsdoc-hygiene-ts-baseline.json

@@ -1,90 +1,4 @@
 {
   "$comment": "Auto-managed by packages/superdoc/scripts/check-jsdoc-hygiene-ts.cjs. Each entry is \"file::enclosingSymbol::tagName::class::occurrenceIndex\"; line numbers are NOT part of the key, so the baseline survives unrelated edits that shift line numbers. The gate grandfathers these and fails on net-new violations. Refresh after intentional cleanup with --write. Goal is to drain to zero, then flip to \"zero allowed\" in a separate PR. See packages/superdoc/scripts/type-hygiene.md.",
-  "knownViolations": [
-    "packages/super-editor/src/editors/v1/core/Editor.ts::#withState::template::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/EventEmitter.ts::EventEmitter::template::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/EventEmitter.ts::emit::returns::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/EventEmitter.ts::off::returns::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/EventEmitter.ts::on::returns::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/EventEmitter.ts::once::returns::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/Extension.ts::Extension::template::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/Extension.ts::Extension::template::declaration-doc-type::1",
-    "packages/super-editor/src/editors/v1/core/Mark.ts::Mark::template::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/Mark.ts::Mark::template::declaration-doc-type::1",
-    "packages/super-editor/src/editors/v1/core/Mark.ts::Mark::template::declaration-doc-type::2",
-    "packages/super-editor/src/editors/v1/core/Mark.ts::MarkConfig::template::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/Mark.ts::MarkConfig::template::declaration-doc-type::1",
-    "packages/super-editor/src/editors/v1/core/Mark.ts::MarkConfig::template::declaration-doc-type::2",
-    "packages/super-editor/src/editors/v1/core/Node.ts::Node::template::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/Node.ts::Node::template::declaration-doc-type::1",
-    "packages/super-editor/src/editors/v1/core/Node.ts::Node::template::declaration-doc-type::2",
-    "packages/super-editor/src/editors/v1/core/Node.ts::NodeConfig::template::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/Node.ts::NodeConfig::template::declaration-doc-type::1",
-    "packages/super-editor/src/editors/v1/core/Node.ts::NodeConfig::template::declaration-doc-type::2",
-    "packages/super-editor/src/editors/v1/core/OxmlNode.ts::OxmlNode::template::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/OxmlNode.ts::OxmlNode::template::declaration-doc-type::1",
-    "packages/super-editor/src/editors/v1/core/OxmlNode.ts::OxmlNode::template::declaration-doc-type::2",
-    "packages/super-editor/src/editors/v1/core/OxmlNode.ts::OxmlNodeConfig::template::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/OxmlNode.ts::OxmlNodeConfig::template::declaration-doc-type::1",
-    "packages/super-editor/src/editors/v1/core/OxmlNode.ts::OxmlNodeConfig::template::declaration-doc-type::2",
-    "packages/super-editor/src/editors/v1/core/defineMark.ts::<inline>::typedef::typedef-style::0",
-    "packages/super-editor/src/editors/v1/core/defineMark.ts::defineMark::template::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/defineMark.ts::defineMark::template::declaration-doc-type::1",
-    "packages/super-editor/src/editors/v1/core/defineMark.ts::defineMark::template::declaration-doc-type::2",
-    "packages/super-editor/src/editors/v1/core/defineNode.ts::<inline>::typedef::typedef-style::0",
-    "packages/super-editor/src/editors/v1/core/defineNode.ts::defineNode::template::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/defineNode.ts::defineNode::template::declaration-doc-type::1",
-    "packages/super-editor/src/editors/v1/core/defineNode.ts::defineNode::template::declaration-doc-type::2",
-    "packages/super-editor/src/editors/v1/core/helpers/getExtensionConfigField.ts::getExtensionConfigField::template::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts::#focusEditorAfterImageSelection::returns::declaration-doc-type::0",
-    "packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts::#updateSelection::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/EventEmitter.ts::EventEmitter::template::declaration-doc-type::0",
-    "packages/superdoc/src/core/EventEmitter.ts::emit::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/EventEmitter.ts::off::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/EventEmitter.ts::on::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/EventEmitter.ts::once::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::#abortUpgrade::type::inline-fake-cast::0",
-    "packages/superdoc/src/core/SuperDoc.ts::#applyDocumentMode::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::#applyDocumentMode::param::declaration-doc-type::1",
-    "packages/superdoc/src/core/SuperDoc.ts::#initCollaboration::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::#log::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::#patchNaiveUIStyles::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::#requireSuperdocStore::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::#resolveSourceEditor::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::#triggerCollaborationSaves::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::#validateUpgradePrerequisites::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::SuperDoc::extends::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::SuperDoc::implements::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::addCommentsList::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::addSharedUser::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::broadcastEditorBeforeCreate::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::broadcastEditorCreate::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::event::type::inline-fake-cast::0",
-    "packages/superdoc/src/core/SuperDoc.ts::export::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::exportEditorsToDOCX::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::getHTML::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::getZoom::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::goToSearchResult::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::goToSearchResult::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::lockSuperdoc::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::lockSuperdoc::param::declaration-doc-type::1",
-    "packages/superdoc/src/core/SuperDoc.ts::navigateTo::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::openSurface::template::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::pendingCollaborationSaves::type::inline-fake-cast::0",
-    "packages/superdoc/src/core/SuperDoc.ts::readyEditors::type::inline-fake-cast::0",
-    "packages/superdoc/src/core/SuperDoc.ts::removeSharedUser::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::requiredNumberOfEditors::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::scrollToComment::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::scrollToComment::param::declaration-doc-type::1",
-    "packages/superdoc/src/core/SuperDoc.ts::scrollToComment::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::scrollToElement::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::scrollToElement::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::search::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::search::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::setActiveEditor::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::setTrackedChangesPreferences::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::setZoom::param::declaration-doc-type::0",
-    "packages/superdoc/src/core/SuperDoc.ts::upgradeToCollaboration::returns::declaration-doc-type::0",
-    "packages/superdoc/src/core/types/index.ts::InternalConfig::type::inline-fake-cast::0"
-  ]
+  "knownViolations": []
 }