shelving 1.234.1 → 1.236.0

package/extract/DirectoryExtractor.d.ts

@@ -1,6 +1,6 @@
 import type { ImmutableDictionary } from "../util/dictionary.js";
-import type { DirectoryElement } from "../util/element.js";
 import { type AbsolutePath, type Matchables, type Path } from "../util/index.js";
+import type { TreeElement } from "../util/tree.js";
 import { Extractor } from "./Extractor.js";
 import { FileExtractor } from "./FileExtractor.js";
 /** Options for a directory extractor. */
@@ -21,19 +21,19 @@ export interface DirectoryExtractorOptions {
     readonly ignore?: Matchables;
 }
 /**
- * Extractor that walks a directory on disk and produces a `DirectoryElement` tree.
+ * Extractor that walks a directory on disk and produces a tree of `tree-element` nodes.
  * - Recursively descends into subdirectories.
  * - Dispatches non-ignored files to a matching `FileExtractor` based on extension; files with no matching extractor are silently skipped.
  * - Keys on the produced elements are the verbatim filenames (e.g. `"string.ts"`, `"README.md"`) and directory names (e.g. `"util"`).
  * - This is a pure walker: same-key merging and README absorption are intentionally *not* applied here — wrap with `MergingExtractor`
- *   and/or `IndexFileExtractor` to opt in to those behaviours.
+ *   and/or `IndexExtractor` to opt in to those behaviours.
  */
-export declare class DirectoryExtractor extends Extractor<Path, DirectoryElement> {
+export declare class DirectoryExtractor extends Extractor<Path, TreeElement> {
     private readonly _extractors;
     private readonly _base;
     private readonly _ignore;
     constructor({ extractors, base, ignore }?: DirectoryExtractorOptions);
-    extract(source: Path): Promise<DirectoryElement>;
+    extract(source: Path): Promise<TreeElement>;
     private _extractDirectory;
     private _extractChild;
 }

package/extract/DirectoryExtractor.js

@@ -20,12 +20,12 @@ const DEFAULT_EXTRACTORS = {
  */
 const DEFAULT_IGNORE = [/\.test\.tsx?$/i, /\.spec\.tsx?$/i, /^node_modules$/i, /^[_.]/i];
 /**
- * Extractor that walks a directory on disk and produces a `DirectoryElement` tree.
+ * Extractor that walks a directory on disk and produces a tree of `tree-element` nodes.
  * - Recursively descends into subdirectories.
  * - Dispatches non-ignored files to a matching `FileExtractor` based on extension; files with no matching extractor are silently skipped.
  * - Keys on the produced elements are the verbatim filenames (e.g. `"string.ts"`, `"README.md"`) and directory names (e.g. `"util"`).
  * - This is a pure walker: same-key merging and README absorption are intentionally *not* applied here — wrap with `MergingExtractor`
- *   and/or `IndexFileExtractor` to opt in to those behaviours.
+ *   and/or `IndexExtractor` to opt in to those behaviours.
  */
 export class DirectoryExtractor extends Extractor {
     _extractors;
@@ -52,7 +52,7 @@ export class DirectoryExtractor extends Extractor {
                 children.push(child);
         }
         return {
-            type: "tree-directory",
+            type: "tree-element",
             key: name,
             props: {
                 source,

package/extract/Extractor.d.ts

@@ -1,4 +1,4 @@
-import { type TreeElement } from "../util/element.js";
+import type { TreeElement } from "../util/tree.js";
 /**
  * Base class for an extractor that converts input into a tree element.
  * - Extractors are composable: outer extractors delegate to inner extractors.

package/extract/FileExtractor.d.ts

@@ -1,5 +1,5 @@
 import type { BunFile } from "bun";
-import type { FileElement, FileElementProps } from "../util/element.js";
+import type { TreeElement, TreeElementProps } from "../util/tree.js";
 import { Extractor } from "./Extractor.js";
 /**
  * Base extractor for a file in a tree.
@@ -11,15 +11,15 @@ import { Extractor } from "./Extractor.js";
  * - Does NOT set `title` — `title` is only set by subclasses that have a confident source for one (e.g. `MarkupExtractor` uses the first `<h1>`). Renderers fall back to `name` when missing.
  * - Subclasses (e.g. `MarkupExtractor`, `TypescriptExtractor`) override `extractProps()` to parse the content into richer elements.
  */
-export declare class FileExtractor extends Extractor<BunFile, FileElement> {
-    extract(file: BunFile): Promise<FileElement>;
+export declare class FileExtractor extends Extractor<BunFile, TreeElement> {
+    extract(file: BunFile): Promise<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.
      */
-    extractProps(name: string, content: string): Partial<FileElementProps> & {
+    extractProps(name: string, content: string): Partial<TreeElementProps> & {
         name: string;
     };
 }

package/extract/FileExtractor.js

@@ -22,7 +22,7 @@ export class FileExtractor extends Extractor {
         const text = await file.text();
         const props = { ...this.extractProps(base, text), source };
         return {
-            type: "tree-file",
+            type: "tree-element",
             key: filename,
             props,
         };

package/extract/IndexExtractor.d.ts

@@ -0,0 +1,24 @@
+import { type Matchables } from "../util/regexp.js";
+import type { TreeElement } from "../util/tree.js";
+import type { Extractor } from "./Extractor.js";
+import { ThroughExtractor } from "./ThroughExtractor.js";
+/** Options for an `IndexExtractor`. */
+export interface IndexExtractorOptions {
+    /**
+     * Filename patterns treated as a parent's index. Matched case-insensitively against each child element's `key`.
+     * - Defaults to README and index files: `["readme.txt", "readme.md", "index.md", "index.ts", "index.tsx"]`.
+     */
+    readonly index?: Matchables;
+}
+/**
+ * Through extractor that absorbs each element's index child into the element itself.
+ * - For every element with children: finds the first child whose `key` matches any `index` pattern.
+ * - The matched child's `title`, `description`, `content`, and `children` are folded into the parent.
+ * - The matched child is removed from the parent's children list.
+ * - Purely name-based: it doesn't care whether an element is a directory or a file — any element with children is processed, deepest level first.
+ */
+export declare class IndexExtractor<I> extends ThroughExtractor<I, TreeElement> {
+    private readonly _index;
+    constructor(source: Extractor<I, TreeElement>, { index }?: IndexExtractorOptions);
+    extract(input: I): Promise<TreeElement>;
+}

package/extract/IndexExtractor.js

@@ -0,0 +1,50 @@
+import { mergeElements, walkElements } from "../util/element.js";
+import { notNullish } from "../util/null.js";
+import { anyMatch } from "../util/regexp.js";
+import { ThroughExtractor } from "./ThroughExtractor.js";
+/**
+ * Default index file patterns.
+ * - Matched case-insensitively (all entries stored lowercase).
+ * - The first child that matches any pattern is absorbed.
+ */
+const DEFAULT_INDEX = [/^readme\.txt$/i, /^readme\.md$/i, /^index\.md$/i, /^index\.ts$/i, /^index\.tsx$/i];
+/**
+ * Through extractor that absorbs each element's index child into the element itself.
+ * - For every element with children: finds the first child whose `key` matches any `index` pattern.
+ * - The matched child's `title`, `description`, `content`, and `children` are folded into the parent.
+ * - The matched child is removed from the parent's children list.
+ * - Purely name-based: it doesn't care whether an element is a directory or a file — any element with children is processed, deepest level first.
+ */
+export class IndexExtractor extends ThroughExtractor {
+    _index;
+    constructor(source, { index = DEFAULT_INDEX } = {}) {
+        super(source);
+        this._index = index;
+    }
+    async extract(input) {
+        const root = await this.source.extract(input);
+        return _absorbIndex(root, this._index);
+    }
+}
+/** Recursively absorb the index child in `element` and all of its descendants that have children. */
+function _absorbIndex(element, index) {
+    // Recurse first so nested levels absorb their own indexes before we look at this one.
+    // Only descend into elements that actually have children — leaving childless leaves (e.g. files) untouched, including their `undefined` children.
+    const recursed = Array.from(walkElements(element.props.children)).map(child => notNullish(child.props.children) ? _absorbIndex(child, index) : child);
+    // Find the index child by key.
+    const indexChild = recursed.find(child => anyMatch(child.key, ...index));
+    if (!indexChild)
+        return { ...element, props: { ...element.props, children: recursed } };
+    // Fold the index child into the parent, and drop it from children.
+    const remaining = recursed.filter(child => child !== indexChild);
+    return {
+        ...element,
+        props: {
+            ...element.props,
+            title: element.props.title ?? indexChild.props.title,
+            description: element.props.description ?? indexChild.props.description,
+            content: element.props.content ?? indexChild.props.content,
+            children: mergeElements(indexChild.props.children, remaining),
+        },
+    };
+}

package/extract/MarkupExtractor.d.ts

@@ -1,4 +1,4 @@
-import { type FileElementProps } from "../util/element.js";
+import type { TreeElementProps } from "../util/tree.js";
 import { FileExtractor } from "./FileExtractor.js";
 /**
  * File extractor for Markdown files.
@@ -10,7 +10,7 @@ import { FileExtractor } from "./FileExtractor.js";
  * - Sets `description` to the first prose paragraph as a plain-text summary (used for card listings and `<meta>`).
  */
 export declare class MarkupExtractor extends FileExtractor {
-    extractProps(name: string, text: string): Partial<FileElementProps> & {
+    extractProps(name: string, text: string): Partial<TreeElementProps> & {
         name: string;
     };
 }

package/extract/MergingExtractor.d.ts

@@ -1,5 +1,5 @@
 import type { ImmutableDictionary } from "../util/dictionary.js";
-import { type DirectoryElement } from "../util/element.js";
+import type { TreeElement } from "../util/tree.js";
 import type { Extractor } from "./Extractor.js";
 import { ThroughExtractor } from "./ThroughExtractor.js";
 /** Options for a `MergingExtractor`. */
@@ -8,20 +8,20 @@ export interface MergingExtractorOptions {
      * Templated key pairs that should merge. Each key is a `{base}` template matched against the secondary element's key;
      * each value is an ordered list of `{base}` templates for the primary candidates to merge into.
      * - The first primary candidate that exists in the same directory wins; remaining candidates are ignored.
-     * - If no candidate exists the secondary is left in place as its own tree-file element.
+     * - If no candidate exists the secondary is left in place as its own tree element.
      * - Defaults to `{ "{base}.md": ["{base}.ts", "{base}.tsx", "{base}.js", "{base}.jsx"] }`.
      */
     readonly merges?: ImmutableDictionary<readonly string[]>;
 }
 /**
- * Through extractor that walks a `DirectoryElement` tree and merges sibling tree elements whose keys match a `merges` template pair.
- * - Walks every directory recursively, applying the merge at each level.
+ * Through extractor that walks a tree of `tree-element` nodes and merges sibling tree elements whose keys match a `merges` template pair.
+ * - Purely key-based: it doesn't care whether siblings are directories or files — any element with children is processed, at every level.
  * - The primary (winning) element keeps its `key`, `source`, and `type`; the secondary's `title`, `description`,
  *   `content`, and `children` are folded in via `mergeTreeElements()`.
  * - A secondary with no matching primary is left in place — pure prose files (e.g. `concepts.md` with no `concepts.ts`) stand alone.
  */
-export declare class MergingExtractor<I> extends ThroughExtractor<I, DirectoryElement> {
+export declare class MergingExtractor<I> extends ThroughExtractor<I, TreeElement> {
     private readonly _merges;
-    constructor(source: Extractor<I, DirectoryElement>, { merges }?: MergingExtractorOptions);
-    extract(input: I): Promise<DirectoryElement>;
+    constructor(source: Extractor<I, TreeElement>, { merges }?: MergingExtractorOptions);
+    extract(input: I): Promise<TreeElement>;
 }

package/extract/MergingExtractor.js

@@ -1,4 +1,5 @@
 import { walkElements } from "../util/element.js";
+import { notNullish } from "../util/null.js";
 import { matchTemplate, renderTemplate } from "../util/template.js";
 import { mergeTreeElements } from "./Extractor.js";
 import { ThroughExtractor } from "./ThroughExtractor.js";
@@ -12,8 +13,8 @@ const DEFAULT_MERGES = {
     "{base}.md": ["{base}.ts", "{base}.tsx", "{base}.js", "{base}.jsx"],
 };
 /**
- * Through extractor that walks a `DirectoryElement` tree and merges sibling tree elements whose keys match a `merges` template pair.
- * - Walks every directory recursively, applying the merge at each level.
+ * Through extractor that walks a tree of `tree-element` nodes and merges sibling tree elements whose keys match a `merges` template pair.
+ * - Purely key-based: it doesn't care whether siblings are directories or files — any element with children is processed, at every level.
  * - The primary (winning) element keeps its `key`, `source`, and `type`; the secondary's `title`, `description`,
  *   `content`, and `children` are folded in via `mergeTreeElements()`.
  * - A secondary with no matching primary is left in place — pure prose files (e.g. `concepts.md` with no `concepts.ts`) stand alone.
@@ -26,14 +27,15 @@ export class MergingExtractor extends ThroughExtractor {
     }
     async extract(input) {
         const root = await this.source.extract(input);
-        return _mergeDirectory(root, this._merges);
+        return _mergeElement(root, this._merges);
     }
 }
-/** Recursively merge same-template siblings inside `dir` and all nested directories. */
-function _mergeDirectory(dir, merges) {
-    const children = Array.from(walkElements(dir.props.children));
-    const merged = _mergeChildren(children, merges).map(child => child.type === "tree-directory" ? _mergeDirectory(child, merges) : child);
-    return { ...dir, props: { ...dir.props, children: merged } };
+/** Recursively merge same-template siblings inside `element` and all of its descendants that have children. */
+function _mergeElement(element, merges) {
+    const children = Array.from(walkElements(element.props.children));
+    // Recurse into any child that has its own children; childless leaves (e.g. files) are left untouched.
+    const merged = _mergeChildren(children, merges).map(child => (notNullish(child.props.children) ? _mergeElement(child, merges) : child));
+    return { ...element, props: { ...element.props, children: merged } };
 }
 /** Merge same-template siblings at one directory level. */
 function _mergeChildren(children, merges) {

package/extract/ModuleExtractor.d.ts

@@ -1,4 +1,4 @@
-import { type DirectoryElement, type DocumentationElement, type FileElement } from "../util/element.js";
+import type { DocumentationElement, TreeElement } from "../util/tree.js";
 import { Extractor } from "./Extractor.js";
 /** Input for a `ModuleExtractor`. */
 export interface ModuleExtractorInput {
@@ -6,15 +6,15 @@ export interface ModuleExtractorInput {
     readonly name: string;
     /**
      * The source element this module is built from.
-     * - `FileElement` — the module is backed by a single source file (with its `.md` sibling already merged in by `MergingExtractor`).
-     * - `DirectoryElement` — the module is backed by a directory; its absorbed index file provides the content.
+     * - A file-backed `tree-element` — the module is backed by a single source file (with its `.md` sibling already merged in by `MergingExtractor`).
+     * - A directory-backed `tree-element` — the module is backed by a directory; its absorbed index file provides the content.
      */
-    readonly source: FileElement | DirectoryElement;
+    readonly source: TreeElement;
 }
 /**
  * Extractor that builds a `kind: "module"` `DocumentationElement` from a source file or directory.
  * - The module's `content`, `description`, and `title` are taken from the source element (`MergingExtractor` and
- *   `IndexFileExtractor` are expected to have run upstream so `.md` siblings and `README.md` are already folded in).
+ *   `IndexExtractor` are expected to have run upstream so `.md` siblings and `README.md` are already folded in).
  * - The module's `children` are every `tree-documentation` element found by deep-walking the source — flattened across
  *   files and subdirectories, but never descending into a `tree-documentation`'s own members.
  */

package/extract/ModuleExtractor.js

@@ -4,7 +4,7 @@ import { Extractor } from "./Extractor.js";
 /**
  * Extractor that builds a `kind: "module"` `DocumentationElement` from a source file or directory.
  * - The module's `content`, `description`, and `title` are taken from the source element (`MergingExtractor` and
- *   `IndexFileExtractor` are expected to have run upstream so `.md` siblings and `README.md` are already folded in).
+ *   `IndexExtractor` are expected to have run upstream so `.md` siblings and `README.md` are already folded in).
  * - The module's `children` are every `tree-documentation` element found by deep-walking the source — flattened across
  *   files and subdirectories, but never descending into a `tree-documentation`'s own members.
  */
@@ -33,7 +33,7 @@ function _collectChildren(element) {
         if (treeChild.type === "tree-documentation") {
             result.push(treeChild);
         }
-        else if (treeChild.type === "tree-directory" || treeChild.type === "tree-file") {
+        else if (treeChild.type === "tree-element") {
             result.push(..._collectChildren(treeChild));
         }
     }

package/extract/PackageExtractor.d.ts

@@ -1,20 +1,22 @@
-import { type DirectoryElement } from "../util/element.js";
+import type { ImmutableDictionary } from "../util/dictionary.js";
 import { type AbsolutePath, type Path } from "../util/path.js";
+import type { TreeElement } from "../util/tree.js";
 import { Extractor } from "./Extractor.js";
 import { ModuleExtractor } from "./ModuleExtractor.js";
 /** Options for a `PackageExtractor`. */
 export interface PackageExtractorOptions {
     /**
      * Pre-extracted source tree the `package.json` exports resolve against — typically the result of
-     * `IndexFileExtractor(MergingExtractor(DirectoryExtractor()))` over the source root.
+     * `IndexExtractor(MergingExtractor(DirectoryExtractor()))` over the source root.
      */
-    readonly tree: DirectoryElement;
+    readonly tree: TreeElement;
     /**
-     * Source-file extensions tried when resolving an export's last segment to a source file (e.g. `./util/string` → `string.ts`, `string.tsx`, …).
-     * - Checked in declaration order; first match wins.
-     * - Defaults to `["ts", "tsx", "js", "jsx"]`.
+     * Maps an export *target* file extension (the right-hand side of an `exports` entry) to the *source* extensions to look for, in order.
+     * - Bridges built output and source: `package.json` targets a `.js` file but the tree holds the `.ts` source.
+     * - The first source extension that exists in the tree wins; a target extension with no mapping falls back to itself.
+     * - Defaults to `{ js: ["ts", "tsx", "js", "jsx"] }`.
      */
-    readonly extensions?: readonly string[];
+    readonly extensions?: ImmutableDictionary<readonly string[]>;
     /** `ModuleExtractor` used to build each module element. Defaults to a fresh `new ModuleExtractor()`. */
     readonly module?: ModuleExtractor;
     /** Absolute base path used to resolve a relative `package.json` path passed to `extract()`. */
@@ -24,18 +26,20 @@ export interface PackageExtractorOptions {
  * Extractor that reads a `package.json` and produces a flat tree of modules — one `kind: "module"`
  * `DocumentationElement` per export entry, in declaration order.
  * - Static export keys (e.g. `"./api"`, `"./firestore/client"`) become one module each.
- * - Wildcard export keys (e.g. `"./util/*"`) expand against the source tree — one module per matching child file (with
- *   an extension in `extensions`) or subdirectory.
+ * - Wildcard export keys (e.g. `"./util/*"`) expand against the source tree — one module per matching child file or subdirectory.
+ * - Each export's *target* extension (e.g. the `.js` in `"./util/*.js"`) is mapped to source extensions via `extensions`, so built `.js` paths resolve to their `.ts` sources.
  * - The `"."` root export is skipped — its content is the root tree element itself.
  * - Throws if a static export key has no matching source element in the tree.
  */
-export declare class PackageExtractor extends Extractor<Path, DirectoryElement> {
+export declare class PackageExtractor extends Extractor<Path, TreeElement> {
     private readonly _tree;
     private readonly _extensions;
     private readonly _module;
     private readonly _base;
     constructor({ tree, extensions, module, base }: PackageExtractorOptions);
-    extract(packageJson: Path): Promise<DirectoryElement>;
+    extract(packageJson: Path): Promise<TreeElement>;
+    /** Source extensions to try for an export `target`, derived from the target's own extension via the `extensions` mapping. */
+    private _sourceExtensions;
     /** Resolve a static export subpath (e.g. `"firestore/client"`) to a file or directory element in the tree. */
     private _resolve;
     /** Expand a wildcard export subpath (e.g. `"util/*"`) into one module per matching child. */

package/extract/PackageExtractor.js

@@ -2,14 +2,20 @@ import { walkElements } from "../util/element.js";
 import { requirePath } from "../util/path.js";
 import { Extractor } from "./Extractor.js";
 import { ModuleExtractor } from "./ModuleExtractor.js";
-/** Default source-file extensions used when resolving exports back to source elements. */
-const DEFAULT_EXTENSIONS = ["ts", "tsx", "js", "jsx"];
+/**
+ * Default extension mapping: maps an export *target* file extension to the *source* extensions to resolve against, in order.
+ * - `package.json` targets point at built output (e.g. `./util/*.js`), but the source tree holds source files (e.g. `string.ts`) — this bridges the two.
+ * - A `.js` target finds its `.ts` / `.tsx` / `.js` / `.jsx` source (first match wins).
+ */
+const DEFAULT_EXTENSIONS = {
+    js: ["ts", "tsx", "js", "jsx"],
+};
 /**
  * Extractor that reads a `package.json` and produces a flat tree of modules — one `kind: "module"`
  * `DocumentationElement` per export entry, in declaration order.
  * - Static export keys (e.g. `"./api"`, `"./firestore/client"`) become one module each.
- * - Wildcard export keys (e.g. `"./util/*"`) expand against the source tree — one module per matching child file (with
- *   an extension in `extensions`) or subdirectory.
+ * - Wildcard export keys (e.g. `"./util/*"`) expand against the source tree — one module per matching child file or subdirectory.
+ * - Each export's *target* extension (e.g. the `.js` in `"./util/*.js"`) is mapped to source extensions via `extensions`, so built `.js` paths resolve to their `.ts` sources.
  * - The `"."` root export is skipped — its content is the root tree element itself.
  * - Throws if a static export key has no matching source element in the tree.
  */
@@ -30,23 +36,28 @@ export class PackageExtractor extends Extractor {
         const pkg = (await Bun.file(pkgPath).json());
         const exports = pkg.exports ?? {};
         const modules = [];
-        for (const key of Object.keys(exports)) {
+        for (const [key, value] of Object.entries(exports)) {
             if (key === ".")
                 continue;
+            // `value` is the target (e.g. `"./util/*.js"`); conditional-export objects aren't supported.
+            if (typeof value !== "string")
+                continue;
             const subpath = key.startsWith("./") ? key.slice(2) : key;
+            const sourceExtensions = this._sourceExtensions(value);
             if (subpath.includes("*")) {
-                modules.push(...this._expandWildcard(subpath));
+                modules.push(...this._expandWildcard(subpath, sourceExtensions));
             }
             else {
-                const source = this._resolve(subpath);
+                const source = this._resolve(subpath, sourceExtensions);
                 if (!source)
                     throw new Error(`PackageExtractor: export "${key}" has no matching source in the tree`);
                 modules.push(this._module.extract({ name: subpath, source }));
             }
         }
         const tree = this._tree;
+        // Canonical URL `path`s aren't stamped here — they're derived from tree structure when the tree is flattened (`flattenTree()`) in the UI layer.
         return {
-            type: "tree-directory",
+            type: "tree-element",
             key: pkg.name ?? tree.key,
             props: {
                 source: tree.props.source,
@@ -58,8 +69,14 @@ export class PackageExtractor extends Extractor {
             },
         };
     }
+    /** Source extensions to try for an export `target`, derived from the target's own extension via the `extensions` mapping. */
+    _sourceExtensions(target) {
+        const dot = target.lastIndexOf(".");
+        const ext = dot >= 0 ? target.slice(dot + 1) : "";
+        return this._extensions[ext] ?? (ext ? [ext] : []);
+    }
     /** Resolve a static export subpath (e.g. `"firestore/client"`) to a file or directory element in the tree. */
-    _resolve(subpath) {
+    _resolve(subpath, sourceExtensions) {
         const segments = subpath.split("/");
         let current = this._tree;
         for (let i = 0; i < segments.length; i++) {
@@ -68,15 +85,15 @@ export class PackageExtractor extends Extractor {
             let found;
             for (const child of walkElements(current.props.children)) {
                 const treeChild = child;
-                if (treeChild.type === "tree-directory" && treeChild.key === segment) {
+                // A directory's key is the bare segment name — match at any level.
+                if (treeChild.key === segment) {
                     found = treeChild;
                     break;
                 }
-                if (isLast && treeChild.type === "tree-file") {
-                    if (this._extensions.some(ext => treeChild.key === `${segment}.${ext}`)) {
-                        found = treeChild;
-                        break;
-                    }
+                // A file's key is `${segment}.${ext}` for one of the source extensions — only valid as the final segment.
+                if (isLast && sourceExtensions.some(ext => treeChild.key === `${segment}.${ext}`)) {
+                    found = treeChild;
+                    break;
                 }
             }
             if (!found)
@@ -86,7 +103,7 @@ export class PackageExtractor extends Extractor {
         return current;
     }
     /** Expand a wildcard export subpath (e.g. `"util/*"`) into one module per matching child. */
-    _expandWildcard(subpath) {
+    _expandWildcard(subpath, sourceExtensions) {
         const wildcardIndex = subpath.indexOf("*");
         const prefix = subpath.slice(0, wildcardIndex);
         const suffix = subpath.slice(wildcardIndex + 1);
@@ -94,38 +111,30 @@ export class PackageExtractor extends Extractor {
             throw new Error(`PackageExtractor: wildcard exports with a suffix are not supported ("${subpath}")`);
         if (subpath.indexOf("*", wildcardIndex + 1) >= 0)
             throw new Error(`PackageExtractor: multiple wildcards not supported ("${subpath}")`);
-        // The parent directory of the wildcard.
+        // The parent element of the wildcard.
         const prefixPath = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
         let parent;
         if (!prefixPath) {
             parent = this._tree;
         }
         else {
-            const resolved = this._resolve(prefixPath);
-            if (!resolved || resolved.type !== "tree-directory") {
-                throw new Error(`PackageExtractor: wildcard parent "${prefixPath}" did not resolve to a directory`);
-            }
+            const resolved = this._resolve(prefixPath, sourceExtensions);
+            if (!resolved)
+                throw new Error(`PackageExtractor: wildcard parent "${prefixPath}" did not resolve to an element in the tree`);
             parent = resolved;
         }
-        // One module per qualifying child of the parent directory.
+        // One module per qualifying child. A child's `name` is already its extension-stripped module name (e.g. `string.ts` → `string`, the `util` directory → `util`).
         const modules = [];
         for (const child of walkElements(parent.props.children)) {
             const treeChild = child;
-            let stem;
-            if (treeChild.type === "tree-directory") {
-                stem = treeChild.key;
-            }
-            else if (treeChild.type === "tree-file") {
-                for (const ext of this._extensions) {
-                    if (treeChild.key.endsWith(`.${ext}`)) {
-                        stem = treeChild.key.slice(0, -(ext.length + 1));
-                        break;
-                    }
-                }
-            }
-            if (!stem)
+            if (treeChild.type !== "tree-element")
+                continue;
+            // Include directories (no extension) and source files (extension in the mapped list); skip other files (e.g. a standalone `.md`).
+            const dot = treeChild.key.lastIndexOf(".");
+            const ext = dot >= 0 ? treeChild.key.slice(dot + 1) : "";
+            if (ext && !sourceExtensions.includes(ext))
                 continue;
-            modules.push(this._module.extract({ name: `${prefix}${stem}`, source: treeChild }));
+            modules.push(this._module.extract({ name: `${prefix}${treeChild.props.name}`, source: treeChild }));
         }
         return modules;
     }

package/extract/ThroughExtractor.d.ts

@@ -1,4 +1,4 @@
-import type { TreeElement } from "../util/element.js";
+import type { TreeElement } from "../util/tree.js";
 import { Extractor } from "./Extractor.js";
 /**
  * Base class for an extractor that wraps another extractor.

package/extract/TypescriptExtractor.d.ts

@@ -1,17 +1,21 @@
-import type { FileElementProps } from "../util/element.js";
+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.
  * - 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`.
+ * - Class declarations synthesise their `signatures`, `params`, and `returns` from the constructor — `new ClassName<…>(…)` including generics, one signature per constructor overload, with `returns` set to the class type. Param descriptions come from the constructor's `@param` first, then the class's `@param`.
  * - Top-of-file JSDoc comment becomes the file's `content`.
  * - Sets `description` (a plain-text summary from the first JSDoc paragraph) on the file and every `tree-documentation` child.
- * - Sets `title` on every `tree-documentation` child — `name()` for functions and methods, `name` for other kinds.
+ * - Sets `title` on every `tree-documentation` child — `name()` for functions and methods, bare `name` for other kinds. Parent class context comes from the `class` prop ("member of …" affordance), never the title.
+ * - Records relational metadata as raw strings for render-time linking: `class` (owning class), `readonly`, `extends`, `implements`.
+ * - Members declared with the `override` or `declare` modifier are skipped — the base class already documents overrides, and `declare` members are ambient type-only re-declarations rather than new API.
+ * - 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`.
  */
 export declare class TypescriptExtractor extends FileExtractor {
-    extractProps(name: string, text: string): Partial<FileElementProps> & {
+    extractProps(name: string, text: string): Partial<TreeElementProps> & {
         name: string;
     };
 }