shelving 1.269.0 → 1.271.0

package/extract/FileExtractor.d.ts

@@ -29,15 +29,17 @@ export declare class FileExtractor extends Extractor<BunFile, TreeElement> {
      * Build the file element props from the extracted content.
      * - `name` is the basename without extension (e.g. `"array"`) — display-ready, used by menus, cards, and URL paths.
      * - Override to parse `text` into richer elements (content/children/description) and to set
-     *   `title` if a confident title is available.
+     *   `title` if a confident title is available. Overrides may be async (e.g. `TypescriptExtractor` parses via the native compiler server) — `extract()` awaits the result either way.
      *
      * @param name The basename of the file without extension (e.g. `"array"`).
      * @param content The raw text content of the file.
-     * @returns The element props, always including a `name`; the base implementation stores `content` verbatim.
+     * @returns The element props (or a promise resolving to them), always including a `name`; the base implementation stores `content` verbatim.
      * @example extractProps("notes", "Some text") // { name: "notes", content: "Some text" }
      * @see https://shelving.cc/extract/FileExtractor/extractProps
      */
-    extractProps(name: string, content: string): Partial<TreeElementProps> & {
+    extractProps(name: string, content: string): (Partial<TreeElementProps> & {
         name: string;
-    };
+    }) | Promise<Partial<TreeElementProps> & {
+        name: string;
+    }>;
 }

package/extract/FileExtractor.js

@@ -32,7 +32,7 @@ export class FileExtractor extends Extractor {
         const filename = splitPath(source).at(-1) ?? "unnamed";
         const [base = filename] = splitFileExtension(filename);
         const text = await file.text();
-        const props = { ...this.extractProps(base, text), source };
+        const props = { ...(await this.extractProps(base, text)), source };
         return {
             type: "tree-element",
             key: filename,
@@ -43,11 +43,11 @@ export class FileExtractor extends Extractor {
      * Build the file element props from the extracted content.
      * - `name` is the basename without extension (e.g. `"array"`) — display-ready, used by menus, cards, and URL paths.
      * - Override to parse `text` into richer elements (content/children/description) and to set
-     *   `title` if a confident title is available.
+     *   `title` if a confident title is available. Overrides may be async (e.g. `TypescriptExtractor` parses via the native compiler server) — `extract()` awaits the result either way.
      *
      * @param name The basename of the file without extension (e.g. `"array"`).
      * @param content The raw text content of the file.
-     * @returns The element props, always including a `name`; the base implementation stores `content` verbatim.
+     * @returns The element props (or a promise resolving to them), always including a `name`; the base implementation stores `content` verbatim.
      * @example extractProps("notes", "Some text") // { name: "notes", content: "Some text" }
      * @see https://shelving.cc/extract/FileExtractor/extractProps
      */

package/extract/TypescriptExtractor.d.ts

@@ -2,7 +2,8 @@ import type { TreeElementProps } from "../util/tree.js";
 import { FileExtractor } from "./FileExtractor.js";
 /**
  * File extractor that parses a TypeScript source file into a tree element.
- * - Uses the TypeScript compiler API to parse the AST.
+ * - Uses the native TypeScript compiler's API (`typescript/unstable/async` — TypeScript 7+) to parse the AST.
+ * - Parsing runs on a shared native compiler server, spawned on demand into a virtual filesystem and closed again after a short idle — callers never manage its lifecycle.
  * - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
  * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`. When a function (or constructor) is overloaded, the implementation declaration (the "base definition") is dropped entirely — only the overload signatures are documented.
  * - A `@param name {Type}` (or `@returns {Type}`) whose `{Type}` is given is canonical: it supersedes the inferred type from the base definition and any overloads. Multiple `@param name` tags for one parameter each emit a row, letting a single parameter be documented as several typed variants.
@@ -18,13 +19,13 @@ import { FileExtractor } from "./FileExtractor.js";
  * - Keys are the raw declared `name` (case-preserving) so case-distinct exports like `Collection` and `COLLECTION` stay separate.
  * - The file element itself has no `title` — a TS source file has no confident title source; renderers fall back to `name`.
  *
- * @example const element = new TypescriptExtractor().extractProps("string.ts", sourceText);
+ * @example const element = await new TypescriptExtractor().extractProps("string.ts", sourceText);
  *
  * @see https://shelving.cc/extract/TypescriptExtractor
  */
 export declare class TypescriptExtractor extends FileExtractor {
     /** Parses the TypeScript source into one `tree-documentation` child per exported public declaration. */
-    extractProps(name: string, text: string): Partial<TreeElementProps> & {
+    extractProps(name: string, text: string): Promise<Partial<TreeElementProps> & {
         name: string;
-    };
+    }>;
 }

package/extract/TypescriptExtractor.js

@@ -1,9 +1,13 @@
-import ts from "typescript";
+import { getTextOfJSDocComment, isArrayBindingPattern, isBindingElement, isClassDeclaration, isConstructorDeclaration, isEnumDeclaration, isFunctionDeclaration, isGetAccessorDeclaration, isIdentifier, isInterfaceDeclaration, isJSDoc, isJSDocParameterTag, isJSDocReturnTag, isJSDocSeeTag, isJSDocThrowsTag, isJSDocTypeExpression, isMethodDeclaration, isMethodSignatureDeclaration, isObjectBindingPattern, isPropertyDeclaration, isPropertySignatureDeclaration, isSetAccessorDeclaration, isTypeAliasDeclaration, isTypeLiteralNode, isTypeReferenceNode, isVariableStatement, SyntaxKind, } from "typescript/unstable/ast";
+import { API } from "typescript/unstable/async";
+import { ValueError } from "../error/ValueError.js";
+import { BLACKHOLE } from "../util/function.js";
 import { FileExtractor } from "./FileExtractor.js";
 import { extractMarkdownProps } from "./MarkupExtractor.js";
 /**
  * File extractor that parses a TypeScript source file into a tree element.
- * - Uses the TypeScript compiler API to parse the AST.
+ * - Uses the native TypeScript compiler's API (`typescript/unstable/async` — TypeScript 7+) to parse the AST.
+ * - Parsing runs on a shared native compiler server, spawned on demand into a virtual filesystem and closed again after a short idle — callers never manage its lifecycle.
  * - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
  * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`. When a function (or constructor) is overloaded, the implementation declaration (the "base definition") is dropped entirely — only the overload signatures are documented.
  * - A `@param name {Type}` (or `@returns {Type}`) whose `{Type}` is given is canonical: it supersedes the inferred type from the base definition and any overloads. Multiple `@param name` tags for one parameter each emit a row, letting a single parameter be documented as several typed variants.
@@ -19,25 +23,25 @@ import { extractMarkdownProps } from "./MarkupExtractor.js";
  * - Keys are the raw declared `name` (case-preserving) so case-distinct exports like `Collection` and `COLLECTION` stay separate.
  * - The file element itself has no `title` — a TS source file has no confident title source; renderers fall back to `name`.
  *
- * @example const element = new TypescriptExtractor().extractProps("string.ts", sourceText);
+ * @example const element = await new TypescriptExtractor().extractProps("string.ts", sourceText);
  *
  * @see https://shelving.cc/extract/TypescriptExtractor
  */
 export class TypescriptExtractor extends FileExtractor {
     /** Parses the TypeScript source into one `tree-documentation` child per exported public declaration. */
-    extractProps(name, text) {
-        const source = ts.createSourceFile(name, text, ts.ScriptTarget.Latest, true);
+    async extractProps(name, text) {
+        const source = await _parseSourceFile(text);
         // Names with one or more overload signatures (bodyless function declarations). When a function is overloaded, the
         // implementation declaration (the one with a body — the "base definition") is dropped entirely; only the overloads are documented.
         const overloaded = new Set();
         for (const statement of source.statements)
-            if (ts.isFunctionDeclaration(statement) && !statement.body && statement.name)
+            if (isFunctionDeclaration(statement) && !statement.body && statement.name)
                 overloaded.add(statement.name.text);
         // Collect elements by key, merging overloads (same name) by appending signatures.
         const byKey = new Map();
         for (const statement of source.statements) {
             // Skip the implementation of an overloaded function — overloads supersede the base definition.
-            if (ts.isFunctionDeclaration(statement) && statement.body && statement.name && overloaded.has(statement.name.text))
+            if (isFunctionDeclaration(statement) && statement.body && statement.name && overloaded.has(statement.name.text))
                 continue;
             const element = _extractStatement(statement, source);
             if (!element)
@@ -50,6 +54,114 @@ export class TypescriptExtractor extends FileExtractor {
         return { name, children: Array.from(byKey.values()) };
     }
 }
+// Constants.
+const _DIR = "/shelving-typescript-extractor";
+const _TSCONFIG_PATH = `${_DIR}/tsconfig.json`;
+const _TSCONFIG_JSON = JSON.stringify({ compilerOptions: { noEmit: true }, include: ["**/*.ts"] });
+const _IDLE_CLOSE_MS = 500;
+let _server;
+let _queue = Promise.resolve();
+let _timer;
+let _count = 0;
+let _previous;
+/** Is a path inside the virtual directory the compiler server is rooted in? */
+function _isVirtual(path) {
+    return path === _DIR || path.startsWith(`${_DIR}/`);
+}
+/** Get the shared compiler server, spawning it on demand with a virtual filesystem rooted at `_DIR`. */
+function _getServer() {
+    if (_server)
+        return _server;
+    const files = new Map([[_TSCONFIG_PATH, _TSCONFIG_JSON]]);
+    // Paths outside the virtual directory return `undefined` so the server falls back to the real filesystem (e.g. bundled libs).
+    const fs = {
+        fileExists: f => (_isVirtual(f) ? files.has(f) : undefined),
+        readFile: f => (_isVirtual(f) ? (files.get(f) ?? null) : undefined),
+        directoryExists: d => (d === _DIR ? true : _isVirtual(d) ? false : undefined),
+        getAccessibleEntries: d => d === _DIR
+            ? { files: Array.from(files.keys(), f => f.slice(_DIR.length + 1)), directories: [] }
+            : _isVirtual(d)
+                ? { files: [], directories: [] }
+                : undefined,
+        realpath: p => (_isVirtual(p) ? p : undefined),
+    };
+    _server = { api: new API({ cwd: _DIR, fs }), files };
+    return _server;
+}
+/** Close the shared compiler server after a short idle, so the process can exit without callers managing the lifecycle. */
+function _scheduleClose() {
+    if (_timer)
+        clearTimeout(_timer);
+    _timer = setTimeout(() => {
+        const server = _server;
+        _server = undefined;
+        _previous = undefined;
+        _timer = undefined;
+        try {
+            server?.api.close();
+        }
+        catch {
+            // Closing can reject in-flight bookkeeping requests — harmless on shutdown.
+        }
+    }, _IDLE_CLOSE_MS);
+}
+/**
+ * Parse TypeScript source text into a `SourceFile` via the shared native compiler server.
+ * - Each call writes the text as a fresh virtual file, snapshots the project, and materialises the file's AST.
+ * - Calls are serialised through a queue so concurrent extractions don't interleave snapshot updates.
+ *
+ * @throws `ValueError` If the server fails to produce a source file for the text.
+ */
+function _parseSourceFile(text) {
+    const task = async () => {
+        if (_timer)
+            clearTimeout(_timer);
+        const { api, files } = _getServer();
+        const path = `${_DIR}/${_count++}.ts`;
+        files.set(path, text);
+        // Drop the previous parse's file so the virtual project stays a single file (keeps snapshots cheap).
+        const deleted = _previous;
+        if (deleted)
+            files.delete(deleted);
+        _previous = path;
+        const snapshot = await api.updateSnapshot({
+            openProjects: [_TSCONFIG_PATH],
+            fileChanges: { created: [path], ...(deleted ? { deleted: [deleted] } : {}) },
+        });
+        try {
+            const source = await snapshot.getProject(_TSCONFIG_PATH)?.program.getSourceFile(path);
+            if (!source)
+                throw new ValueError("Unable to parse TypeScript source", { received: text });
+            return source;
+        }
+        finally {
+            snapshot.dispose();
+            _scheduleClose();
+        }
+    };
+    const result = _queue.then(task, task);
+    _queue = result.catch(BLACKHOLE);
+    return result;
+}
+/** Read a node's modifiers (excluding decorators), or `undefined` when it has none. */
+function _getModifiers(node) {
+    const modifiers = node.modifiers;
+    const filtered = modifiers?.filter((m) => m.kind !== SyntaxKind.Decorator);
+    return filtered?.length ? filtered : undefined;
+}
+/** Get a member's declared identifier name, or `undefined` for computed / private / missing names. */
+function _getMemberName(member) {
+    // Class/type member bases don't surface `name` structurally — read it off the node and narrow.
+    const { name } = member;
+    return name && isIdentifier(name) ? name.text : undefined;
+}
+/** Get the text of a JSDoc tag's `{Type}` expression — unwraps a `JSDocTypeExpression` to its inner type. */
+function _getJSDocTypeText(typeExpression, source) {
+    if (!typeExpression)
+        return;
+    const type = isJSDocTypeExpression(typeExpression) ? typeExpression.type : typeExpression;
+    return type.getText(source);
+}
 /** Merge a newly-extracted overload into the existing documentation element with the same key. */
 function _mergeOverloads(existing, next) {
     const a = existing.props;
@@ -146,7 +258,7 @@ function _extractStatement(statement, source) {
 }
 /** Extract the `extends` (single base type) and `implements` (interface list) heritage from a class or interface declaration, as full type text including any generic arguments (e.g. `AbstractStore<string>`, `Omit<StringSchemaOptions, "value">`). */
 function _getHeritage(statement, source) {
-    if (!ts.isClassDeclaration(statement) && !ts.isInterfaceDeclaration(statement))
+    if (!isClassDeclaration(statement) && !isInterfaceDeclaration(statement))
         return;
     let extendsName;
     const implementsNames = [];
@@ -154,9 +266,9 @@ function _getHeritage(statement, source) {
         // Full text — keep generic arguments (`Foo<T>`) and wrappers (`Omit<…>`) intact; render-time lookup trims them to the bare name to resolve a link.
         const names = clause.types.map(t => t.getText(source));
         // `extends` keeps the first base type; an interface extending several still surfaces its primary base.
-        if (clause.token === ts.SyntaxKind.ExtendsKeyword)
+        if (clause.token === SyntaxKind.ExtendsKeyword)
             extendsName ??= names[0];
-        else if (clause.token === ts.SyntaxKind.ImplementsKeyword)
+        else if (clause.token === SyntaxKind.ImplementsKeyword)
             implementsNames.push(...names);
     }
     if (!extendsName && !implementsNames.length)
@@ -170,13 +282,13 @@ function _getHeritage(statement, source) {
  * - Order-preserving and de-duplicated. Unresolved names (builtins like `Record`, externals) simply stay as plain text at render time.
  */
 function _getReferencedTypes(statement, source) {
-    if (!ts.isTypeAliasDeclaration(statement))
+    if (!isTypeAliasDeclaration(statement))
         return;
     const generics = new Set(statement.typeParameters?.map(t => t.name.text) ?? []);
     const names = [];
     const seen = new Set();
     const visit = (node) => {
-        if (ts.isTypeReferenceNode(node)) {
+        if (isTypeReferenceNode(node)) {
             const name = node.typeName.getText(source);
             if (!generics.has(name) && !seen.has(name)) {
                 seen.add(name);
@@ -196,44 +308,45 @@ function _getReferencedTypes(statement, source) {
  * - Getters/setters fold into a single entry per name (the getter's type wins for a get/set pair).
  */
 function _getProperties(statement, source) {
-    const members = ts.isInterfaceDeclaration(statement) || ts.isClassDeclaration(statement)
+    const members = isInterfaceDeclaration(statement) || isClassDeclaration(statement)
         ? statement.members
-        : ts.isTypeAliasDeclaration(statement) && ts.isTypeLiteralNode(statement.type)
+        : isTypeAliasDeclaration(statement) && isTypeLiteralNode(statement.type)
             ? statement.type.members
             : undefined;
     if (!members)
         return;
     const properties = [];
     for (const member of members) {
-        const name = member.name && ts.isIdentifier(member.name) ? member.name.text : undefined;
+        const name = _getMemberName(member);
         if (!name || name.startsWith("_"))
             continue;
-        const modifiers = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined;
+        const modifiers = _getModifiers(member);
         // Skip private/protected (not public API), `override` (documented on the base class), and `declare` (ambient re-declarations).
-        if (modifiers?.some(m => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword))
+        if (modifiers?.some(m => m.kind === SyntaxKind.PrivateKeyword || m.kind === SyntaxKind.ProtectedKeyword))
             continue;
-        if (modifiers?.some(m => m.kind === ts.SyntaxKind.OverrideKeyword || m.kind === ts.SyntaxKind.DeclareKeyword))
+        if (modifiers?.some(m => m.kind === SyntaxKind.OverrideKeyword || m.kind === SyntaxKind.DeclareKeyword))
             continue;
         const jsDoc = _getJSDoc(member, source);
-        if (ts.isPropertySignature(member) || ts.isPropertyDeclaration(member)) {
+        if (isPropertySignatureDeclaration(member) || isPropertyDeclaration(member)) {
             // A class field's initializer is its default; otherwise fall back to an explicit `@default` tag.
-            const def = (ts.isPropertyDeclaration(member) ? member.initializer?.getText(source) : undefined) ?? jsDoc?.default;
+            const def = (isPropertyDeclaration(member) ? member.initializer?.getText(source) : undefined) ?? jsDoc?.default;
             properties.push({
                 name,
                 type: member.type?.getText(source),
                 description: jsDoc?.description,
-                optional: !!member.questionToken,
+                // Optionality is a `?` postfix token (the postfix slot also carries `!` definite-assignment, which isn't optionality).
+                optional: member.postfixToken?.kind === SyntaxKind.QuestionToken,
                 default: def,
-                readonly: modifiers?.some(m => m.kind === ts.SyntaxKind.ReadonlyKeyword) || undefined,
+                readonly: modifiers?.some(m => m.kind === SyntaxKind.ReadonlyKeyword) || undefined,
             });
         }
-        else if (ts.isGetAccessor(member) || ts.isSetAccessor(member)) {
-            const type = ts.isGetAccessor(member) ? member.type?.getText(source) : member.parameters[0]?.type?.getText(source);
+        else if (isGetAccessorDeclaration(member) || isSetAccessorDeclaration(member)) {
+            const type = isGetAccessorDeclaration(member) ? member.type?.getText(source) : member.parameters[0]?.type?.getText(source);
             const index = properties.findIndex(p => p.name === name);
             const found = index >= 0 ? properties[index] : undefined;
             // Fold a get/set pair into one entry: the getter's declared type wins, and the matching setter clears read-only.
             if (found) {
-                properties[index] = { ...found, type: ts.isGetAccessor(member) && type ? type : found.type, readonly: undefined };
+                properties[index] = { ...found, type: isGetAccessorDeclaration(member) && type ? type : found.type, readonly: undefined };
             }
             else {
                 // A lone getter is read-only until a setter is seen; a lone setter is writable.
@@ -243,7 +356,7 @@ function _getProperties(statement, source) {
                     description: jsDoc?.description,
                     optional: false,
                     default: jsDoc?.default,
-                    readonly: ts.isGetAccessor(member) || undefined,
+                    readonly: isGetAccessorDeclaration(member) || undefined,
                 });
             }
         }
@@ -264,59 +377,58 @@ function _buildJSDocContent(description, unhandled) {
 }
 /** Check if a statement has an `export` modifier. */
 function _isExported(statement) {
-    const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
-    return !!modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword);
+    return !!_getModifiers(statement)?.some(m => m.kind === SyntaxKind.ExportKeyword);
 }
 /** Get the declared name of a statement. */
 function _getStatementName(statement) {
-    if (ts.isFunctionDeclaration(statement) ||
-        ts.isClassDeclaration(statement) ||
-        ts.isInterfaceDeclaration(statement) ||
-        ts.isTypeAliasDeclaration(statement) ||
-        ts.isEnumDeclaration(statement)) {
+    if (isFunctionDeclaration(statement) ||
+        isClassDeclaration(statement) ||
+        isInterfaceDeclaration(statement) ||
+        isTypeAliasDeclaration(statement) ||
+        isEnumDeclaration(statement)) {
         return statement.name?.text;
     }
-    if (ts.isVariableStatement(statement)) {
+    if (isVariableStatement(statement)) {
         const declaration = statement.declarationList.declarations[0];
-        if (declaration && ts.isIdentifier(declaration.name))
+        if (declaration && isIdentifier(declaration.name))
             return declaration.name.text;
     }
 }
 /** Map a statement to its documentation kind. */
 function _getKind(statement) {
-    if (ts.isFunctionDeclaration(statement))
+    if (isFunctionDeclaration(statement))
         return "function";
-    if (ts.isClassDeclaration(statement))
+    if (isClassDeclaration(statement))
         return "class";
-    if (ts.isInterfaceDeclaration(statement))
+    if (isInterfaceDeclaration(statement))
         return "interface";
-    if (ts.isTypeAliasDeclaration(statement))
+    if (isTypeAliasDeclaration(statement))
         return "type";
-    if (ts.isVariableStatement(statement))
+    if (isVariableStatement(statement))
         return "constant";
 }
 /** Get the text signature(s) of a statement — complete, name-prefixed declarations usable as headings. */
 function _getSignatures(statement, source, name) {
-    if (ts.isFunctionDeclaration(statement)) {
+    if (isFunctionDeclaration(statement)) {
         const params = statement.parameters.map(p => p.getText(source)).join(", ");
         const ret = statement.type ? statement.type.getText(source) : "void";
         return [`${name}(${params}): ${ret}`];
     }
-    if (ts.isClassDeclaration(statement)) {
+    if (isClassDeclaration(statement)) {
         // Synthesise `new ClassName<…>(…)` constructor signatures so a class page reads like a function's.
         return _getConstructorSignatures(statement, source, name);
     }
-    if (ts.isInterfaceDeclaration(statement)) {
+    if (isInterfaceDeclaration(statement)) {
         // Emit a pretty-printed `{ member; member }` block — the same shape a `type` object body produces, distinguished only by the `kind` badge.
         return [_formatObjectSignature(statement.members, source)];
     }
-    if (ts.isTypeAliasDeclaration(statement)) {
+    if (isTypeAliasDeclaration(statement)) {
         // Pretty-print object-literal aliases multi-line like an interface; emit other bodies (`string | null`, mapped types, …) verbatim. The alias name is already the page title.
-        if (ts.isTypeLiteralNode(statement.type))
+        if (isTypeLiteralNode(statement.type))
             return [_formatObjectSignature(statement.type.members, source)];
         return [statement.type.getText(source)];
     }
-    if (ts.isVariableStatement(statement)) {
+    if (isVariableStatement(statement)) {
         const declaration = statement.declarationList.declarations[0];
         if (declaration?.type)
             return [`${name}: ${declaration.type.getText(source)}`];
@@ -338,7 +450,7 @@ function _getTypeParamNames(statement, source) {
 }
 /** Get a class's constructor declarations in source order — when overloaded, only the overload signatures (the implementation, i.e. the base definition, is dropped). */
 function _getConstructors(statement) {
-    const constructors = statement.members.filter(ts.isConstructorDeclaration);
+    const constructors = statement.members.filter(isConstructorDeclaration);
     // When overload signatures exist, drop the implementation constructor (the one with a body) — overloads supersede the base definition.
     return constructors.some(c => !c.body) ? constructors.filter(c => !c.body) : constructors;
 }
@@ -357,9 +469,9 @@ function _getConstructorSignatures(statement, source, name) {
 }
 /** Extract parameters from a function or class declaration, enriched with JSDoc `@param` descriptions. */
 function _getParams(statement, source, jsDocParams) {
-    if (ts.isClassDeclaration(statement))
+    if (isClassDeclaration(statement))
         return _getConstructorParams(statement, source, jsDocParams);
-    if (!ts.isFunctionDeclaration(statement))
+    if (!isFunctionDeclaration(statement))
         return;
     const params = _buildParams(statement.parameters, source, jsDocParams);
     return params.length ? params : undefined;
@@ -377,7 +489,7 @@ function _buildParams(parameters, source, primaryJsDocParams, fallbackJsDocParam
     // Identifier (non-destructured) parameter names — used to spot "orphan" `@param` tags that name a destructured bag.
     const named = new Set();
     for (const p of parameters)
-        if (ts.isIdentifier(p.name))
+        if (isIdentifier(p.name))
             named.add(p.name.getText(source));
     // Top-level `@param` names not matching any identifier parameter, in declared order (constructor's own first, then class-level), de-duplicated — these let an author name a destructured param (`@param options`). Sub-tags (`options.min`) are excluded.
     const orphans = [];
@@ -386,7 +498,7 @@ function _buildParams(parameters, source, primaryJsDocParams, fallbackJsDocParam
             orphans.push(d.name);
     let orphan = 0;
     for (const p of parameters) {
-        const name = ts.isIdentifier(p.name) ? p.name.getText(source) : (orphans[orphan++] ?? _getBindingName(p, source));
+        const name = isIdentifier(p.name) ? p.name.getText(source) : (orphans[orphan++] ?? _getBindingName(p, source));
         const type = p.type?.getText(source);
         const optional = !!p.questionToken || !!p.initializer;
         const def = p.initializer?.getText(source);
@@ -413,9 +525,9 @@ function _buildParams(parameters, source, primaryJsDocParams, fallbackJsDocParam
  */
 function _getBindingName(p, source) {
     const { name } = p;
-    if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name))
+    if (isObjectBindingPattern(name) || isArrayBindingPattern(name))
         for (const el of name.elements)
-            if (ts.isBindingElement(el) && el.dotDotDotToken && ts.isIdentifier(el.name))
+            if (isBindingElement(el) && el.dotDotDotToken && el.name && isIdentifier(el.name))
                 return el.name.text;
     return p.type?.getText(source).replace(/<.*/s, "").endsWith("Props") ? "props" : "options";
 }
@@ -436,12 +548,12 @@ function _getConstructorParams(statement, source, classJsDocParams) {
 }
 /** Extract return entries — combines the signature return type with any `@returns` descriptions. */
 function _getReturns(statement, source, jsDocReturns, name) {
-    if (ts.isClassDeclaration(statement)) {
+    if (isClassDeclaration(statement)) {
         // A constructor returns an instance of the class, including its generics (e.g. `ChoiceSchema<T>`).
         const type = `${name}${_getTypeParamNames(statement, source)}`;
         return [{ type, description: jsDocReturns?.[0]?.description }];
     }
-    if (!ts.isFunctionDeclaration(statement))
+    if (!isFunctionDeclaration(statement))
         return jsDocReturns;
     const type = statement.type?.getText(source);
     if (jsDocReturns?.length) {
@@ -463,31 +575,31 @@ function _getReturns(statement, source, jsDocReturns, name) {
  * - `static` methods are labelled `static method` so the docs site groups them in their own section, separate from instance `method`s, and their rendered signature is prefixed with the `static ` keyword.
  */
 function _getClassMembers(statement, source, className) {
-    if (!ts.isClassDeclaration(statement) && !ts.isInterfaceDeclaration(statement))
+    if (!isClassDeclaration(statement) && !isInterfaceDeclaration(statement))
         return;
     const members = [];
     for (const member of statement.members) {
         // Skip private, protected, and _-prefixed members.
-        const name = member.name && ts.isIdentifier(member.name) ? member.name.text : undefined;
+        const name = _getMemberName(member);
         if (!name || name.startsWith("_"))
             continue;
-        const modifiers = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined;
-        if (modifiers?.some(m => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword))
+        const modifiers = _getModifiers(member);
+        if (modifiers?.some(m => m.kind === SyntaxKind.PrivateKeyword || m.kind === SyntaxKind.ProtectedKeyword))
             continue;
         // Skip `override` members — the base class already documents them, so a subclass page lists only its newly-introduced API.
-        if (modifiers?.some(m => m.kind === ts.SyntaxKind.OverrideKeyword))
+        if (modifiers?.some(m => m.kind === SyntaxKind.OverrideKeyword))
             continue;
         // Skip `declare` members — ambient type-only re-declarations (e.g. a subclass narrowing an inherited property's type), not new API.
-        if (modifiers?.some(m => m.kind === ts.SyntaxKind.DeclareKeyword))
+        if (modifiers?.some(m => m.kind === SyntaxKind.DeclareKeyword))
             continue;
         // `static` methods are grouped and labelled separately from instance methods (`static method`),
         // and carry the `static ` keyword in their rendered signature.
-        const isStatic = modifiers?.some(m => m.kind === ts.SyntaxKind.StaticKeyword);
+        const isStatic = modifiers?.some(m => m.kind === SyntaxKind.StaticKeyword);
         const staticPrefix = isStatic ? "static " : "";
         const memberJSDoc = _getJSDoc(member, source);
         const content = _buildJSDocContent(memberJSDoc?.description, memberJSDoc?.unhandled);
         const description = extractMarkdownProps(memberJSDoc?.description ?? "").description;
-        if (ts.isMethodDeclaration(member) || ts.isMethodSignature(member)) {
+        if (isMethodDeclaration(member) || isMethodSignatureDeclaration(member)) {
             const params = member.parameters.map(p => p.getText(source)).join(", ");
             const ret = member.type ? member.type.getText(source) : "void";
             const signature = `${staticPrefix}${name}(${params}): ${ret}`;
@@ -524,15 +636,15 @@ function _getClassMembers(statement, source, className) {
  * Extract JSDoc from a node via the TypeScript compiler's parsed JSDoc AST.
  * - Reads the compiler's structured tags rather than re-scanning the raw comment text, so tags are only ever recognised at real tag positions — a `@kind`/`@param`/etc. mentioned inline in prose is left in the description, not parsed.
  * - Multi-line `@param` / `@returns` / `@throws` descriptions and `{Type}` expressions come through whole; `*` margins are already stripped.
- * - `@example` bodies are taken verbatim. Note the compiler treats any whitespace-led `@word` line as a new tag even inside a ``` fence, so an example must not contain a bare at-rule / decorator / pragma line on its own.
+ * - `@example` bodies are taken verbatim. The parser is markdown-fence-aware: an `@word` line inside a balanced triple-backtick fence stays part of the example rather than starting a new tag. The flip side: an unbalanced run of three-plus backticks anywhere in the comment opens a fence that swallows every following tag — never write a bare triple-backtick in docblock prose.
  * - `@see` is recognised only to discard it: it's a VS Code hover affordance (a link back to the docs site), never rendered into the page body.
  */
 function _getJSDoc(node, source) {
     // The compiler attaches every leading `/** */` block here; the last one is the doc comment.
     const jsDoc = node.jsDoc?.at(-1);
-    if (!jsDoc)
+    if (!jsDoc || !isJSDoc(jsDoc))
         return;
-    const description = ts.getTextOfJSDocComment(jsDoc.comment)?.trim();
+    const description = getTextOfJSDocComment(jsDoc.comment)?.trim();
     let kind;
     let def;
     const params = [];
@@ -541,24 +653,24 @@ function _getJSDoc(node, source) {
     const examples = [];
     const unhandled = [];
     for (const tag of jsDoc.tags ?? []) {
-        const comment = ts.getTextOfJSDocComment(tag.comment)?.trim();
-        if (ts.isJSDocParameterTag(tag)) {
+        const comment = getTextOfJSDocComment(tag.comment)?.trim();
+        if (isJSDocParameterTag(tag)) {
             const name = tag.name.getText(source);
-            const type = tag.typeExpression?.type.getText(source);
+            const type = _getJSDocTypeText(tag.typeExpression, source);
             if (name)
                 params.push({ name, type: type || undefined, description: comment || undefined });
         }
-        else if (ts.isJSDocReturnTag(tag)) {
-            const type = tag.typeExpression?.type.getText(source);
+        else if (isJSDocReturnTag(tag)) {
+            const type = _getJSDocTypeText(tag.typeExpression, source);
             if (type || comment)
                 returns.push({ type: type || undefined, description: comment || undefined });
         }
-        else if (ts.isJSDocThrowsTag(tag)) {
-            const type = tag.typeExpression?.type.getText(source);
+        else if (isJSDocThrowsTag(tag)) {
+            const type = _getJSDocTypeText(tag.typeExpression, source);
             if (type || comment)
                 throws.push({ type: type || undefined, description: comment || undefined });
         }
-        else if (ts.isJSDocSeeTag(tag)) {
+        else if (isJSDocSeeTag(tag)) {
             // `@see` is a hover affordance only — strip it, never render it.
         }
         else {

package/markup/rule/fenced.d.ts

@@ -3,7 +3,7 @@
  * - Same as Markdown syntax.
  * - Start when we reach an opening fence on a new line.
  * - Stop when we reach a matching closing fence on a new line, or the end of the string.
- * - Closing fence must be exactly the same as the opening fence, and can be made of three or more "```" backticks, or three or more `~~~` tildes.
+ * - Closing fence must be exactly the same as the opening fence, and can be made of three or more backticks, or three or more `~~~` tildes.
  * - If there's no closing fence the code block will run to the end of the current string.
  * - Markdown-style four-space indent syntax is not supported (only fenced code since it's less confusing and more common).
  *

package/markup/rule/fenced.js

@@ -7,7 +7,7 @@ const FENCE = "`{3,}|~{3,}";
  * - Same as Markdown syntax.
  * - Start when we reach an opening fence on a new line.
  * - Stop when we reach a matching closing fence on a new line, or the end of the string.
- * - Closing fence must be exactly the same as the opening fence, and can be made of three or more "```" backticks, or three or more `~~~` tildes.
+ * - Closing fence must be exactly the same as the opening fence, and can be made of three or more backticks, or three or more `~~~` tildes.
  * - If there's no closing fence the code block will run to the end of the current string.
  * - Markdown-style four-space indent syntax is not supported (only fenced code since it's less confusing and more common).
  *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.269.0",
+	"version": "1.271.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -15,13 +15,12 @@
 		"@types/bun": "^1.3.14",
 		"@types/react": "^19.2.17",
 		"@types/react-dom": "^19.2.3",
-		"@typescript/native-preview": "^7.0.0-dev.20260706.1",
 		"firebase": "^12.15.0",
 		"react": "^19.3.0-canary-fef12a01-20260413",
 		"react-dom": "^19.3.0-canary-fef12a01-20260413",
 		"stylelint": "^17.14.0",
 		"stylelint-config-standard": "^40.0.0",
-		"typescript": "^5.9.3"
+		"typescript": "^7.0.2"
 	},
 	"peerDependencies": {
 		"@google-cloud/firestore": ">=7.0.0",
@@ -69,7 +68,7 @@
 	"scripts": {
 		"test": "bun run --parallel test:*",
 		"test:lint": "biome check .",
-		"test:type": "tsgo --noEmit",
+		"test:type": "tsc --noEmit",
 		"test:style": "stylelint \"modules/**/*.css\"",
 		"test:unit": "bun test ./modules --concurrent --only-failures",
 		"fix": "bun run --sequential fix:*",
@@ -80,7 +79,7 @@
 		"build": "bun run --sequential build:*",
 		"build:0:setup": "rm -rf ./dist && mkdir -p ./dist",
 		"build:1:copy": "cp package.json dist/package.json && cp LICENSE.md dist/LICENSE.md && cp README.md dist/README.md && cp .npmignore dist/.npmignore && cp -r modules/ui dist/ui",
-		"build:2:emit": "tsgo -p tsconfig.build.json",
+		"build:2:emit": "tsc -p tsconfig.build.json",
 		"build:3:syntax": "bun run ./dist/index.js",
 		"build:4:unit": "bun test ./dist/**/*.test.js --concurrent --only-failures --bail"
 	},

package/ui/block/Row.d.ts

@@ -1,4 +1,5 @@
 import type { ReactElement } from "react";
+import { type BlockVariants } from "../style/Block.js";
 import { type FlexVariants } from "../style/Flex.js";
 import type { OptionalChildProps } from "../util/index.js";
 import type { BlockElement } from "./Block.js";
@@ -7,7 +8,7 @@ import type { BlockElement } from "./Block.js";
  *
  * @see https://shelving.cc/ui/RowProps
  */
-export interface RowProps extends FlexVariants, OptionalChildProps {
+export interface RowProps extends BlockVariants, FlexVariants, OptionalChildProps {
     /**
      * Element this `<Row>` renders as, e.g. "header" to output a "<header>"
      * @default "div"

package/ui/block/Row.tsx

@@ -1,5 +1,5 @@
 import type { ReactElement } from "react";
-import { getBlockClass } from "../style/Block.js";
+import { type BlockVariants, getBlockClass } from "../style/Block.js";
 import { type FlexVariants, getFlexClass } from "../style/Flex.js";
 import { getClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/index.js";
@@ -10,7 +10,7 @@ import type { BlockElement } from "./Block.js";
  *
  * @see https://shelving.cc/ui/RowProps
  */
-export interface RowProps extends FlexVariants, OptionalChildProps {
+export interface RowProps extends BlockVariants, FlexVariants, OptionalChildProps {
 	/**
 	 * Element this `<Row>` renders as, e.g. "header" to output a "<header>"
 	 * @default "div"

package/ui/misc/Catcher.d.ts

@@ -2,7 +2,6 @@ import { Component, type ReactElement, type ReactNode } from "react";
 import type { Callback } from "../../util/function.js";
 import type { ChildProps } from "../util/props.js";
 /**
-import { RetryButton, RetryContext } from "../button/RetryButton.js";
  * Props for a component that renders a caught error `reason`.
  *
  * @see https://shelving.cc/ui/ErrorProps

package/ui/misc/Catcher.tsx

@@ -9,7 +9,6 @@ import { Page } from "../page/Page.js";
 import type { ChildProps } from "../util/props.js";
 
 /**
-import { RetryButton, RetryContext } from "../button/RetryButton.js";
  * Props for a component that renders a caught error `reason`.
  *
  * @see https://shelving.cc/ui/ErrorProps