// Add or revise source-level JSDoc for Shift APIs. Use this skill before writing or editing documentation comments for exported classes, methods, constructors, domain data structures, render frames, reactive state, or any API where caller intent, side effects, lifetime, ownership, or nullability are easy to misunderstand.
Update or create DOCS.md files for Shift subsystems. Use this skill whenever the user asks to update docs, refresh documentation, create a DOCS.md, write module documentation, or says "update docs for X". Also trigger after completing a large feature when Claude.md says to update docs — check if any DOCS.md in the affected subsystem needs refreshing.
Canonical rules for writing tests in the Shift codebase. Use whenever you add, rewrite, or review a `.test.ts` file — or any time you're about to mock, stub, or spy your way around a testing problem. This repo has deliberately swept mock-based testing out, and this skill is what keeps it out.
Canonical rules for writing git commits in the Shift codebase. Use whenever the user asks to commit, stage and commit, or "make a commit" — and whenever you're about to draft a commit message. Enforces conventional prefixes, concise subjects, and splitting unrelated changes into separate commits.
Find and remove dead code (unused files, exports, class members) using Knip as a candidate generator, then verify each candidate through AST-level analysis and interface tracing before removing anything. Use when the user asks to clean up unused code, find dead code, or reduce the codebase.
| name | jsdoc |
| description | Add or revise source-level JSDoc for Shift APIs. Use this skill before writing or editing documentation comments for exported classes, methods, constructors, domain data structures, render frames, reactive state, or any API where caller intent, side effects, lifetime, ownership, or nullability are easy to misunderstand. |
Write JSDoc as the stable public contract a caller needs without reading the implementation.
JSDoc comments must sit immediately before the documented symbol and use /** ... */ so tooling can parse them. Follow the standard tag vocabulary from https://jsdoc.app/about-getting-started, adapted for TypeScript source.
@remarks.@param for every public constructor, method, or function parameter, and make the text describe the parameter's role, constraint, ownership, or valid range.@returns when a method returns a value, nullable result, created object, snapshot, or read-only view.@throws {ErrorType} when … for every observable failure mode (custom error class, semantic Error).@returns void; describe the side effect in prose instead.@see {@link OtherSymbol} (one tag per related symbol).@example only when the intended call flow, ordering, or output is not obvious from the signature.Returns…, Applies…, Triggers…), ending with a period. No "This function…".@remarks for the long explanation. If you need more than one sentence of context, demote it under @remarks so the hover summary stays clean.@param name - description documents meaning, not type. For public callable APIs, include the tag and make it earn its place by describing role, constraint, ownership, valid range, or call-order semantics.@returns documents meaning, never "void". Drop the tag entirely for void returns; describe the side effect in the summary instead. Use @returns to clarify ownership ("a fresh array; caller owns it"), nullability semantics ("null when the glyph has no contours, not when it's missing"), or that the result is a snapshot vs a live reactive view.// TODO comments.Document where the type signature is silent. If the type fully encodes the contract, write nothing. Otherwise, prioritize these dimensions:
null / undefined / empty actually means (absent, error, not-yet-loaded, end-of-stream).Pick only the dimensions that apply. Do not force every doc to address all of them.
| Tag | Use it when | Example |
|---|---|---|
@param name - desc | Every public param. Document the constraint, not the type. | @param glyph - must be loaded (not a GlyphRef) |
@returns desc | Nullable / created / snapshot / read-only / non-obvious return. | @returns null when no source is active; never throws. |
@throws {Err} when … | Every observable failure mode. Always type + condition. | @throws {GlyphNotLoadedError} when called on a ref-only glyph. |
@example | Call order, setup, or output carries the lesson. | See below — fenced ts, imports, // Output: line. |
@remarks | Long explanation that would bloat the summary. | One short paragraph; not multi-paragraph essays. |
@see {@link Foo} | One tag per related sibling API. | @see {@link createDraft} |
@deprecated <migration> | Always with replacement or removal reason. | @deprecated Use draft.setPositions instead — avoids NAPI per frame. |
@template T - desc | Generic with a semantic constraint that isn't obvious from the signature. | @template T - coordinate-space tag; controls bound interpretation. |
These re-encode information TS already owns. Including them is noise and risks drift.
@type, @typedef, @property — TS variable annotations, type, and interface are the source of truth.@class, @constructor, @extends, @implements, @function, @method — the declaration shape says this.{Type} annotations inside @param / @returns — never write @param {string} name. Document meaning; TS owns the type.These are doc-generator ceremony for published packages. Shift is not a published package; do not write these in app code.
@since, @public, @beta, @alpha, @experimental, @category@author, @version, @copyright@name/@summary/@description triplesIn TypeScript files, omit JSDoc type annotations. Let TypeScript own the type; let JSDoc own meaning.
/**
* Snapshot of state required to redraw the scene layer.
*
* Building this frame establishes the reactive dependencies for the scene
* output. Drawing code consumes the frame as plain data.
*
* @param dependencies - Values that invalidate or describe one scene redraw.
*/
constructor(dependencies: SceneFrameDependencies) {}
For functions with multiple parameters, document each parameter by role:
/**
* Converts a screen-space pointer into editor coordinate spaces.
*
* @param screen - Pointer position in canvas pixels.
* @param drawOffset - Glyph-local offset applied by the current editor view.
* @returns Coordinates in screen, scene, and glyph-local space.
*/
function resolveCoordinates(
screen: Point2D,
drawOffset: Point2D,
): Coordinates {}
When failure paths are observable, document them with @throws:
/**
* Loads a glyph by handle. Resolves once the source is hydrated.
*
* @param handle - identity returned by {@link glyphHandleForUnicode}.
* @returns the loaded glyph; never a {@link GlyphRef}.
* @throws {GlyphNotFoundError} when the handle does not resolve in the active font.
* @see {@link glyphHandleForUnicode}
*/
async function loadGlyph(handle: GlyphHandle): Promise<Glyph> {}
When deprecating, name the replacement:
/**
* @deprecated Use {@link draft.setPositions} — `bridge.setNodePositions` sends
* one NAPI call per point and causes ~450ms frames on dense glyphs.
*/
function setNodePositions(updates: NodePositionUpdate[]): void {}
Examples must be runnable assertions, not decoration.
```ts. VS Code highlights inside fences.// Output: or // => comment when the value carries the lesson.@example. Multiple @example blocks are fine and better than one mega-block.A good example for a Shift API:
/**
* Begins a JS-only edit of the active glyph. Pair with {@link GlyphDraft.finish}
* to persist, or {@link GlyphDraft.discard} to revert.
*
* @returns a draft scoped to the active glyph; `null` when no glyph is loaded.
*
* @example
* ```ts
* const draft = editor.createDraft();
* if (!draft) return;
*
* for (const update of dragFrame) {
* draft.setPositions(update); // JS-only; no NAPI
* }
*
* draft.finish("translate"); // syncs once, records undo
* ```
*/
createDraft(): GlyphDraft | null {}
When TS inference is non-obvious, annotate the type position inline (Effect pattern):
/**
* @example
* ```ts
* // ┌─── Option<Glyph>
* // ▼
* const result = font.glyphForUnicode(0x41);
* ```
*/
Avoid examples that depend on hidden setup, test fixtures, or implicit globals.
/**
* Resolves a glyph from its Unicode codepoint.
* @param codepoint - the Unicode scalar value.
*/
function glyphFor(codepoint: number): Glyph | null;
/**
* Resolves a glyph from its handle.
* @param handle - identity from a prior lookup; cheaper than codepoint resolution.
*/
function glyphFor(handle: GlyphHandle): Glyph | null;
function glyphFor(arg: number | GlyphHandle): Glyph | null {
/* impl */
}
@returns void// ❌
/** @returns void */
clear(): void {}
// ✅ describe the side effect; drop @returns entirely
/** Clears all queued render frames. Idempotent. */
clear(): void {}
// ❌
/**
* @param glyph - the glyph
* @param index - the index
*/
// ✅ document the constraint
/**
* @param glyph - must be loaded (not a {@link GlyphRef}).
* @param index - zero-based contour index; -1 selects the outer hull.
*/
// ❌ VS Code hover becomes a wall of text
/**
* This function is used to set positions. It is part of the GlyphDraft API and
* is used during drag operations. It does not call NAPI. It must be paired
* with either finish() or discard().
*/
// ✅ one-line contract + @remarks
/**
* Updates JS-side glyph positions; pair with {@link finish} or {@link discard}.
*
* @remarks
* JS-only — does not call NAPI. Use during drag hot path; call `finish()` once
* at gesture end to sync to Rust, or `discard()` to revert.
*/
// ❌ rots fast
/** Called by GlyphSidebar and TransformPanel. */
// ✅ describe what it produces
/** Returns the active glyph's tight bounds, accounting for sidebearings. */
@deprecated// ❌
/** @deprecated */
function oldThing() {}
// ✅ name the replacement or the reason
/** @deprecated Use {@link newThing} — removes the legacy 2D-only path. */
function oldThing() {}
@example for trivial calls// ❌ noise
/**
* @example
* ```ts
* const id = glyph.id;
* ```
*/
get id(): string {}
// ✅ no @example; the name is the whole story
get id(): string {}
// ❌ what is `editor`?
/** @example editor.commit(); */
// ✅ self-contained
/**
* @example
* ```ts
* const editor = createTestEditor();
* await editor.loadGlyph("A");
* editor.commit();
* ```
*/
@param/@returns/@example blocks — a one-line summary is enough.{Type}-style JSDoc with TSDoc tags in the same module; pick one (in TS, drop {Type}).Before saving, scan your doc against this list:
@type, @typedef, or {Type} annotations.@returns void. Side effect described in summary.@throws {Type} when ….@example (if present) has imports, is fenced ```ts, and shows output when it carries the lesson.@since, @public, @category, @author).