@orkestrel/workspace 0.0.6 → 0.0.8

package/dist/src/core/index.d.ts

@@ -1,14 +1,20 @@
-import { DriverInterface } from '@orkestrel/database';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { TableInterface } from '@orkestrel/database';
+import type { DriverInterface } from '@orkestrel/database';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { TableInterface } from '@orkestrel/database';
+
+/** Holds the binary arm of a file's immutable content: a base64 payload and its MIME. */
+export declare interface BinaryContent {
+    readonly base64: string;
+    readonly mime: BinaryMIME;
+}
 
-/** The binary MIME labels supported by a binary {@link FileContent} arm. */
+/** Names the MIME labels a binary {@link FileContent} arm supports. */
 export declare type BinaryMIME = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
 
 /**
- * Clamp a position to text bounds.
+ * Clamps a position to text bounds.
  *
  * @param text - The addressed text
  * @param position - The requested position
@@ -22,7 +28,7 @@ export declare type BinaryMIME = 'image/png' | 'image/jpeg' | 'image/gif' | 'ima
 export declare function clampPosition(text: string, position: Position): Position;
 
 /**
- * Clamp both positions in a range to text bounds.
+ * Clamps both positions in a range to text bounds.
  *
  * @param text - The addressed text
  * @param range - The requested range
@@ -36,7 +42,20 @@ export declare function clampPosition(text: string, position: Position): Positio
 export declare function clampRange(text: string, range: Range): Range;
 
 /**
- * Compute the byte size of file content.
+ * Computes the decoded byte length of a base64 string, arithmetically rather than by decoding it.
+ *
+ * @param base64 - The base64 string
+ * @returns The decoded byte count
+ *
+ * @example
+ * ```ts
+ * computeDecodedSize('AAAA') // 3
+ * ```
+ */
+export declare function computeDecodedSize(base64: string): number;
+
+/**
+ * Computes the byte size of file content.
  *
  * @param content - The content to measure
  * @returns UTF-8 bytes for text or decoded bytes for binary content
@@ -49,7 +68,7 @@ export declare function clampRange(text: string, range: Range): Range;
 export declare function computeSize(content: FileContent): number;
 
 /**
- * Count the lines in file content.
+ * Counts the lines in file content.
  *
  * @param content - The content to inspect
  * @returns The text line count, or zero for empty text and binary content
@@ -62,9 +81,10 @@ export declare function computeSize(content: FileContent): number;
 export declare function countLines(content: FileContent): number;
 
 /**
- * Create the binary arm of {@link FileContent}.
+ * Creates the binary arm of {@link FileContent}, returned as {@link BinaryContent} rather than
+ * as the whole union.
  *
- * @param data - The base64 payload
+ * @param base64 - The base64 payload
  * @param mime - The binary MIME
  * @returns Binary file content
  *
@@ -75,12 +95,13 @@ export declare function countLines(content: FileContent): number;
  * createBinaryContent('AAAA', 'image/png')
  * ```
  */
-export declare function createBinaryContent(data: string, mime: BinaryMIME): FileContent;
+export declare function createBinaryContent(base64: string, mime: BinaryMIME): BinaryContent;
 
 /**
- * Create a database-backed workspace snapshot store.
+ * Creates a database-backed workspace snapshot store, over an in-memory driver when the caller
+ * supplies none.
  *
- * @param driver - The database driver; defaults to an in-memory driver
+ * @param driver - The database driver. Default: an in-memory driver.
  * @returns A workspace store backed by the supplied driver
  *
  * @example
@@ -93,22 +114,43 @@ export declare function createBinaryContent(data: string, mime: BinaryMIME): Fil
 export declare function createDatabaseWorkspaceStore(driver?: DriverInterface): WorkspaceStoreInterface;
 
 /**
- * Create an immutable file with derived size and line counts.
+ * Creates an immutable file with derived size and line counts.
  *
  * @param input - The file path, content, and optional state
  * @returns A frozen file record
  *
- * @example
+ * @example Files and content
  * ```ts
- * import { createFile, createTextContent } from '@orkestrel/workspace'
- *
- * createFile({ path: 'a.txt', content: createTextContent('hello', 'text') })
+ * import {
+ * 	computeSize,
+ * 	countLines,
+ * 	createBinaryContent,
+ * 	createFile,
+ * 	createTextContent,
+ * 	inferLanguage,
+ * 	isBinary,
+ * 	isText,
+ * } from '@orkestrel/workspace'
+ *
+ * const note = createFile({
+ * 	path: 'notes.md',
+ * 	content: createTextContent('# Title\nBody', inferLanguage('notes.md')), // 'markdown'
+ * })
+ *
+ * note.size // 12 — UTF-8 bytes, through computeSize
+ * note.lines // 2 — through countLines
+ * note.state // 'created'
+ * isText(note.content) // true
+ *
+ * const icon = createFile({ path: 'icon.png', content: createBinaryContent('AAAA', 'image/png') })
+ * isBinary(icon.content) // true
+ * icon.size // 3 — decoded base64 bytes, through computeDecodedSize
  * ```
  */
 export declare function createFile(input: FileInput): FileInterface;
 
 /**
- * Create an in-memory workspace snapshot store.
+ * Creates an in-memory workspace snapshot store.
  *
  * @returns A process-local workspace store
  *
@@ -122,7 +164,8 @@ export declare function createFile(input: FileInput): FileInterface;
 export declare function createMemoryWorkspaceStore(): WorkspaceStoreInterface;
 
 /**
- * Create the text arm of {@link FileContent}.
+ * Creates the text arm of {@link FileContent}, returned as {@link TextContent} rather than as
+ * the whole union.
  *
  * @param text - The text body
  * @param language - The language tag
@@ -135,10 +178,10 @@ export declare function createMemoryWorkspaceStore(): WorkspaceStoreInterface;
  * createTextContent('hello', 'text')
  * ```
  */
-export declare function createTextContent(text: string, language: string): FileContent;
+export declare function createTextContent(text: string, language: string): TextContent;
 
 /**
- * Create a workspace.
+ * Creates a workspace with the same identity, emitter, and seed options the constructor takes.
  *
  * @param options - Optional identity, emitter configuration, and initial files
  * @returns A working workspace
@@ -154,7 +197,7 @@ export declare function createTextContent(text: string, language: string): FileC
 export declare function createWorkspace(options?: WorkspaceOptions): WorkspaceInterface;
 
 /**
- * Create an empty workspace registry.
+ * Creates an empty workspace registry.
  *
  * @param options - Default event hooks and optional durability
  * @returns A workspace manager
@@ -170,21 +213,27 @@ export declare function createWorkspace(options?: WorkspaceOptions): WorkspaceIn
 export declare function createWorkspaceManager(options?: WorkspaceManagerOptions): WorkspaceManagerInterface;
 
 /**
- * A workspace snapshot store over a database table.
+ * Persists workspace snapshots in a database table.
  *
  * Snapshots occupy one opaque column and are narrowed when read back from the storage boundary.
  *
  * @example
  * ```ts
- * import { createDatabaseWorkspaceStore } from '@orkestrel/workspace'
- *
- * const store = createDatabaseWorkspaceStore()
+ * import { rawShape, stringShape } from '@orkestrel/contract'
+ * import { createDatabase, createMemoryDriver } from '@orkestrel/database'
+ * import { DatabaseWorkspaceStore } from '@orkestrel/workspace'
+ *
+ * const database = createDatabase({
+ * 	driver: createMemoryDriver(),
+ * 	tables: { workspaces: { id: stringShape(), snapshot: rawShape({}) } },
+ * })
+ * const store = new DatabaseWorkspaceStore(database.table('workspaces'))
  * ```
  */
 export declare class DatabaseWorkspaceStore implements WorkspaceStoreInterface {
     #private;
     /**
-     * Wrap a workspace snapshot table.
+     * Wraps a workspace snapshot table.
      *
      * @param table - The table keyed by workspace identifier
      */
@@ -195,20 +244,7 @@ export declare class DatabaseWorkspaceStore implements WorkspaceStoreInterface {
 }
 
 /**
- * Compute the decoded byte length of a base64 string.
- *
- * @param base64 - The base64 data
- * @returns The decoded byte count
- *
- * @example
- * ```ts
- * decodedSize('AAAA') // 3
- * ```
- */
-export declare function decodedSize(base64: string): number;
-
-/**
- * Escape regular-expression metacharacters for literal matching.
+ * Escapes regular-expression metacharacters for literal matching.
  *
  * @param value - The literal text
  * @returns The escaped regular-expression source
@@ -221,32 +257,30 @@ export declare function decodedSize(base64: string): number;
 export declare function escapeRegExp(value: string): string;
 
 /**
- * File extensions mapped to language tags for text content.
+ * Maps file extensions to language tags for text content.
  *
- * Unknown extensions intentionally fall back to `text` in
+ * The table is frozen, and an extension it does not list falls back to `text` in
  * {@link import('./helpers.js').inferLanguage}.
  */
 export declare const EXTENSION_LANGUAGES: Readonly<Record<string, string>>;
 
 /**
- * The immutable content of a file: either text with a language tag or base64 data with a MIME.
+ * Holds a file's immutable content: either text with a language tag or a base64 string with a
+ * MIME. The union carries no discriminant field, so a caller narrows it with a guard.
  */
-export declare type FileContent = {
-    readonly text: string;
-    readonly language: string;
-} | {
-    readonly data: string;
-    readonly mime: BinaryMIME;
-};
+export declare type FileContent = TextContent | BinaryContent;
 
-/** The caller-supplied data used to create an immutable file. */
+/**
+ * Carries the caller-supplied values used to create an immutable file. The byte size and the line
+ * count are derived rather than supplied.
+ */
 export declare interface FileInput {
     readonly path: string;
     readonly content: FileContent;
     readonly state?: FileState;
 }
 
-/** An immutable path-addressed file with derived byte and line counts. */
+/** Represents an immutable path-addressed file with derived byte and line counts. */
 export declare interface FileInterface {
     readonly path: string;
     readonly content: FileContent;
@@ -255,11 +289,14 @@ export declare interface FileInterface {
     readonly lines: number;
 }
 
-/** The edit state of an immutable file value. */
+/**
+ * Names the edit state of an immutable file value: `created` for the first write to a path and
+ * `modified` for every later edit of that path.
+ */
 export declare type FileState = 'created' | 'modified';
 
 /**
- * Infer a language tag from the final file extension.
+ * Infers a language tag from the final file extension.
  *
  * @param path - The file path
  * @returns The mapped language, or `text` when the extension is absent or unknown
@@ -272,26 +309,23 @@ export declare type FileState = 'created' | 'modified';
 export declare function inferLanguage(path: string): string;
 
 /**
- * Determine whether content is the binary arm.
+ * Determines whether content is the binary arm.
  *
  * @param content - The file content
- * @returns Whether the content carries base64 data and a MIME
+ * @returns True if the content carries a base64 string and a MIME; false otherwise
  *
  * @example
  * ```ts
- * isBinary({ data: 'AAAA', mime: 'image/png' }) // true
+ * isBinary({ base64: 'AAAA', mime: 'image/png' }) // true
  * ```
  */
-export declare function isBinary(content: FileContent): content is {
-    readonly data: string;
-    readonly mime: BinaryMIME;
-};
+export declare function isBinary(content: FileContent): content is BinaryContent;
 
 /**
- * Narrow an unknown value to an immutable file record.
+ * Narrows an unknown value to an immutable file record.
  *
  * @param value - The value to inspect
- * @returns Whether the value has the file shape
+ * @returns True if the value has the file shape; false otherwise
  *
  * @example
  * ```ts
@@ -301,26 +335,23 @@ export declare function isBinary(content: FileContent): content is {
 export declare function isFile(value: unknown): value is FileInterface;
 
 /**
- * Determine whether content is the text arm.
+ * Determines whether content is the text arm.
  *
  * @param content - The file content
- * @returns Whether the content carries text and a language
+ * @returns True if the content carries text and a language; false otherwise
  *
  * @example
  * ```ts
  * isText({ text: 'hello', language: 'text' }) // true
  * ```
  */
-export declare function isText(content: FileContent): content is {
-    readonly text: string;
-    readonly language: string;
-};
+export declare function isText(content: FileContent): content is TextContent;
 
 /**
- * Determine whether a 1-based range is structurally valid.
+ * Determines whether a 1-based range is structurally valid.
  *
  * @param range - The range to inspect
- * @returns Whether both positions are positive and ordered
+ * @returns True if both positions are positive and ordered; false otherwise
  *
  * @example
  * ```ts
@@ -330,10 +361,14 @@ export declare function isText(content: FileContent): content is {
 export declare function isValidRange(range: Range): boolean;
 
 /**
- * Narrow a caught value to a {@link WorkspaceError}.
+ * Narrows a caught value to a {@link WorkspaceError}.
+ *
+ * @remarks
+ * The check is one `instanceof` test, so it stays total: every input answers `true` or `false`
+ * and none throws.
  *
  * @param value - The caught value
- * @returns Whether the value is a workspace error
+ * @returns True if the value is a workspace error; false otherwise
  *
  * @example
  * ```ts
@@ -343,10 +378,10 @@ export declare function isValidRange(range: Range): boolean;
 export declare function isWorkspaceError(value: unknown): value is WorkspaceError;
 
 /**
- * Narrow an unknown value to a workspace snapshot.
+ * Narrows an unknown value to a workspace snapshot.
  *
  * @param value - The value read from a persistence boundary
- * @returns Whether the value has the workspace snapshot shape
+ * @returns True if the value has the workspace snapshot shape; false otherwise
  *
  * @example
  * ```ts
@@ -356,7 +391,7 @@ export declare function isWorkspaceError(value: unknown): value is WorkspaceErro
 export declare function isWorkspaceSnapshot(value: unknown): value is WorkspaceSnapshot;
 
 /**
- * A process-local workspace snapshot store.
+ * Holds workspace snapshots in the current process.
  *
  * @example
  * ```ts
@@ -373,7 +408,7 @@ export declare class MemoryWorkspaceStore implements WorkspaceStoreInterface {
 }
 
 /**
- * Convert a 1-based position to a zero-based string offset.
+ * Converts a 1-based position to a zero-based string offset.
  *
  * @param text - The addressed text
  * @param position - The requested position
@@ -386,20 +421,20 @@ export declare class MemoryWorkspaceStore implements WorkspaceStoreInterface {
  */
 export declare function offsetAt(text: string, position: Position): number;
 
-/** A 1-based caret position inside text. */
+/** Locates a 1-based caret inside text. */
 export declare interface Position {
     readonly line: number;
     readonly column: number;
 }
 
-/** A half-open text span whose start is inclusive and end is exclusive. */
+/** Represents a half-open text span whose start is inclusive and end is exclusive. */
 export declare interface Range {
     readonly start: Position;
     readonly end: Position;
 }
 
 /**
- * Assemble a nested range from four 1-based coordinates.
+ * Assembles a nested range from four 1-based coordinates.
  *
  * @param fromLine - The start line
  * @param fromColumn - The start column
@@ -414,19 +449,19 @@ export declare interface Range {
  */
 export declare function rangeOf(fromLine: number, fromColumn: number, toLine: number, toColumn: number): Range;
 
-/** The content and clamped span returned by a ranged read. */
+/** Carries the content and clamped span returned by a ranged read. */
 export declare interface ReadResult {
     readonly content: string;
     readonly range: Range;
 }
 
-/** The tallies produced by a replacement operation. */
+/** Carries the tallies a replacement produced: the occurrences replaced and the files changed. */
 export declare interface ReplaceResult {
     readonly occurrences: number;
     readonly files: number;
 }
 
-/** One 1-based search hit and the full line that contains it. */
+/** Reports one 1-based search hit and the full line that contains it. */
 export declare interface SearchMatch {
     readonly path: string;
     readonly line: number;
@@ -436,11 +471,13 @@ export declare interface SearchMatch {
 }
 
 /**
- * Search and replacement behavior.
+ * Configures search and replacement behavior.
  *
  * @remarks
- * `regex` treats the query as regular-expression source, `sensitive` controls case sensitivity,
- * and `limit` caps the search or replacement count.
+ * If `regex` is `true`, the query is treated as regular-expression source; if `false`, it is
+ * escaped and matched literally. Default: `false`. If `sensitive` is `false`, matching ignores
+ * case; if `true`, it does not. Default: `true`. `limit` caps the search or replacement count.
+ * Default: unlimited.
  */
 export declare interface SearchOptions {
     readonly regex?: boolean;
@@ -449,7 +486,7 @@ export declare interface SearchOptions {
 }
 
 /**
- * Slice a clamped half-open text range.
+ * Slices a clamped half-open text range.
  *
  * @param text - The source text
  * @param range - The requested range
@@ -463,7 +500,7 @@ export declare interface SearchOptions {
 export declare function sliceRange(text: string, range: Range): string;
 
 /**
- * Replace a clamped half-open text range.
+ * Replaces a clamped half-open text range.
  *
  * @param text - The source text
  * @param range - The requested range
@@ -477,12 +514,19 @@ export declare function sliceRange(text: string, range: Range): string;
  */
 export declare function spliceRange(text: string, range: Range, replacement: string): string;
 
+/** Holds the text arm of a file's immutable content: a body and its language tag. */
+export declare interface TextContent {
+    readonly text: string;
+    readonly language: string;
+}
+
 /**
- * A mutable path-keyed editing surface over immutable files.
+ * Implements `WorkspaceInterface` over one insertion-ordered path map the instance owns,
+ * projecting fresh arrays on every read.
  *
  * Whole-file edits create text files, ranged edits operate only on existing text files, and
  * binary files remain available through construction-time hydration. Mutations emit after the
- * registry has changed.
+ * file map has changed.
  *
  * @example
  * ```ts
@@ -497,7 +541,7 @@ export declare function spliceRange(text: string, range: Range, replacement: str
 export declare class Workspace implements WorkspaceInterface {
     #private;
     /**
-     * Create a workspace.
+     * Creates a workspace.
      *
      * @param options - Optional identity, emitter configuration, and initial files
      */
@@ -530,12 +574,15 @@ export declare class Workspace implements WorkspaceInterface {
     destroy(): void;
 }
 
-/** An invalid workspace edit or search operation. */
+/**
+ * Reports an invalid workspace edit or search operation, carrying a {@link WorkspaceErrorCode}
+ * and, when the operation had one, the context it ran under.
+ */
 export declare class WorkspaceError extends Error {
     readonly code: WorkspaceErrorCode;
     readonly context?: Readonly<Record<string, unknown>>;
     /**
-     * Create a workspace error.
+     * Creates a workspace error.
      *
      * @param code - The machine-readable failure code
      * @param message - The human-readable failure message
@@ -544,10 +591,10 @@ export declare class WorkspaceError extends Error {
     constructor(code: WorkspaceErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
 }
 
-/** The machine-readable failure codes raised by the workspace edit surface. */
-export declare type WorkspaceErrorCode = 'MODALITY' | 'PATTERN' | 'RANGE';
+/** Names the machine-readable failure codes raised by the workspace edit surface. */
+export declare type WorkspaceErrorCode = 'MISSING' | 'MODALITY' | 'PATTERN' | 'RANGE';
 
-/** Events emitted after workspace mutations complete. */
+/** Names the events emitted after workspace mutations complete. */
 export declare type WorkspaceEventMap = {
     readonly write: readonly [file: FileInterface];
     readonly remove: readonly [path: string];
@@ -555,38 +602,180 @@ export declare type WorkspaceEventMap = {
     readonly clear: readonly [];
 };
 
-/** A mutable path-keyed editing surface over immutable file values. */
+/** Represents a mutable path-keyed editing surface over immutable file values. */
 export declare interface WorkspaceInterface {
+    /** Reports the registry key, either supplied at construction or minted. */
     readonly id: string;
+    /** Reports the owned emitter that publishes every settled mutation. */
     readonly emitter: EmitterInterface<WorkspaceEventMap>;
+    /** Reports how many files the map holds. */
     readonly count: number;
+    /**
+     * Finds the file value stored at one path.
+     *
+     * @param path - The path to look up
+     * @returns The frozen file value, or `undefined` when the path is absent
+     */
     file(path: string): FileInterface | undefined;
+    /**
+     * Lists every file in insertion order.
+     *
+     * @returns A fresh array of the frozen file values
+     */
     files(): readonly FileInterface[];
+    /**
+     * Reads a text file whole.
+     *
+     * @param path - The path to read
+     * @returns The file's text, or `undefined` when the path is absent or holds binary content
+     */
     read(path: string): string | undefined;
+    /**
+     * Reads a clamped span of a text file.
+     *
+     * @param path - The path to read
+     * @param range - The requested half-open span, clamped to the text's bounds
+     * @returns The span's text and the span actually covered, or `undefined` when the path is absent
+     * @throws Thrown when a range is requested for binary content (`MODALITY`).
+     */
     read(path: string, range: Range): ReadResult | undefined;
+    /**
+     * Reads a batch of text files.
+     *
+     * @param paths - The paths to read
+     * @returns Each present text path mapped to its text, with absent and binary paths omitted
+     */
     read(paths: readonly string[]): Readonly<Record<string, string>>;
+    /**
+     * Checks whether one path is present.
+     *
+     * @param path - The path to test
+     * @returns True if the workspace holds the path; false otherwise
+     */
     has(path: string): boolean;
+    /**
+     * Checks whether every path in a batch is present.
+     *
+     * @param paths - The paths to test
+     * @returns True if every entry succeeded; false otherwise
+     */
     has(paths: readonly string[]): boolean;
+    /**
+     * Scans text files for a query, skipping binary content.
+     *
+     * @param query - The literal text, or regular-expression source under `regex`
+     * @param options - Optional matching controls
+     * @returns Each hit in insertion order across files, then line order within a file
+     * @throws Thrown when the pattern source will not compile (`PATTERN`).
+     */
     search(query: string, options?: SearchOptions): readonly SearchMatch[];
+    /**
+     * Rewrites every match across the text files, skipping binary content.
+     *
+     * @param query - The literal text, or regular-expression source under `regex`
+     * @param replacement - The text each match becomes
+     * @param options - Optional matching controls
+     * @returns The occurrences replaced and the files changed
+     * @throws Thrown when the pattern source will not compile (`PATTERN`).
+     */
     replace(query: string, replacement: string, options?: SearchOptions): ReplaceResult;
+    /**
+     * Writes whole text to a path, creating it when absent and retyping a binary path as text.
+     *
+     * @param path - The path to write
+     * @param content - The text the path holds afterwards
+     */
     write(path: string, content: string): void;
+    /**
+     * Splices a clamped span of an existing text file.
+     *
+     * @param path - The path to edit
+     * @param content - The text the span becomes
+     * @param range - The half-open span to replace, clamped to the text's bounds
+     * @throws Thrown when a ranged write names a missing path (`MISSING`) or binary content
+     * (`MODALITY`), or the range is inverted or has a coordinate below 1 (`RANGE`).
+     */
     write(path: string, content: string, range: Range): void;
+    /**
+     * Writes a record batch, one whole-text write per entry.
+     *
+     * @param files - Each path mapped to the text it holds afterwards
+     */
     write(files: Readonly<Record<string, string>>): void;
+    /**
+     * Puts text before a path's existing content, treating an absent path as empty text.
+     *
+     * @param path - The path to edit
+     * @param content - The text placed before what is there
+     * @throws Thrown when the target path holds binary content (`MODALITY`).
+     */
     prepend(path: string, content: string): void;
+    /**
+     * Puts text before existing content for each entry of a record batch.
+     *
+     * @param files - Each path mapped to the text placed before what is there
+     * @throws Thrown when a target path holds binary content (`MODALITY`).
+     */
     prepend(files: Readonly<Record<string, string>>): void;
+    /**
+     * Puts text after a path's existing content, treating an absent path as empty text.
+     *
+     * @param path - The path to edit
+     * @param content - The text placed after what is there
+     * @throws Thrown when the target path holds binary content (`MODALITY`).
+     */
     append(path: string, content: string): void;
+    /**
+     * Puts text after existing content for each entry of a record batch.
+     *
+     * @param files - Each path mapped to the text placed after what is there
+     * @throws Thrown when a target path holds binary content (`MODALITY`).
+     */
     append(files: Readonly<Record<string, string>>): void;
+    /**
+     * Re-keys one file to a new path, keeping the source's insertion slot.
+     *
+     * @param from - The path to move
+     * @param to - The path the file takes
+     * @returns True if the file moved; false otherwise, which a same-path move also reports
+     */
     move(from: string, to: string): boolean;
+    /**
+     * Re-keys each entry of a mapping batch, moving every source it can.
+     *
+     * @param mapping - Each source path mapped to its target path
+     * @returns True if every entry succeeded; false otherwise
+     */
     move(mapping: Readonly<Record<string, string>>): boolean;
+    /**
+     * Drops one path, leaving an absent path untouched.
+     *
+     * @param path - The path to drop
+     * @returns True if a file was dropped; false otherwise
+     */
     remove(path: string): boolean;
+    /**
+     * Drops each path of a batch, dropping every present path.
+     *
+     * @param paths - The paths to drop
+     * @returns True if every entry succeeded; false otherwise
+     */
     remove(paths: readonly string[]): boolean;
+    /** Empties the workspace and emits one `clear`, never a burst of per-path removals. */
     clear(): void;
+    /**
+     * Projects the identity and a flat file list into a serializable value.
+     *
+     * @returns The JSON-serializable state a store persists
+     */
     snapshot(): WorkspaceSnapshot;
+    /** Releases the owned emitter, leaving the editing surface functional and unobserved. */
     destroy(): void;
 }
 
 /**
- * An insertion-ordered workspace registry with an active selection.
+ * Implements `WorkspaceManagerInterface` over an insertion-ordered id map and one active id
+ * the instance owns, resolving `active` through that map on every read and holding no emitter.
  *
  * A supplied store adds lenient snapshot `open` and `save` operations. Event defaults flow into
  * workspaces created through the registry, while observability remains owned by each workspace.
@@ -603,7 +792,7 @@ export declare interface WorkspaceInterface {
 export declare class WorkspaceManager implements WorkspaceManagerInterface {
     #private;
     /**
-     * Create a registry.
+     * Creates a registry.
      *
      * @param options - Default event hooks and optional snapshot store
      */
@@ -621,24 +810,82 @@ export declare class WorkspaceManager implements WorkspaceManagerInterface {
     clear(): void;
 }
 
-/** An insertion-ordered workspace registry with an active selection and optional durability. */
+/**
+ * Represents an insertion-ordered workspace registry with an active selection and optional
+ * durability.
+ */
 export declare interface WorkspaceManagerInterface {
+    /** Reports how many workspaces the registry holds. */
     readonly count: number;
+    /** Reports the current selection, resolved through the registry on every read. */
     readonly active: WorkspaceInterface | undefined;
+    /**
+     * Finds one registered workspace by id.
+     *
+     * @param id - The workspace identifier
+     * @returns The registered workspace, or `undefined` when the id is unknown
+     */
     workspace(id: string): WorkspaceInterface | undefined;
+    /**
+     * Lists registered workspaces in insertion order.
+     *
+     * @returns A fresh array of the registered workspaces
+     */
     workspaces(): readonly WorkspaceInterface[];
+    /**
+     * Creates and registers a workspace, activating it when no selection is active yet.
+     *
+     * @param options - Optional identity, emitter configuration, and initial files; the registry's
+     * own `on` and `error` supply the defaults
+     * @returns The registered workspace
+     */
     add(options?: WorkspaceOptions): WorkspaceInterface;
+    /**
+     * Re-points the active selection at a registered workspace.
+     *
+     * @param id - The workspace identifier
+     * @returns The newly active workspace, or `undefined` when the id is unknown, which leaves the
+     * selection unchanged
+     */
     switch(id: string): WorkspaceInterface | undefined;
+    /**
+     * Activates a registered workspace, or hydrates one from a stored snapshot on a registry miss.
+     *
+     * @param id - The workspace identifier
+     * @returns The active workspace, or `undefined` when neither the registry nor the store holds
+     * the id
+     */
     open(id: string): Promise<WorkspaceInterface | undefined>;
+    /**
+     * Persists a registered workspace's snapshot under its own id.
+     *
+     * @param id - The workspace identifier
+     * @returns True if the snapshot was written; false otherwise, which an unregistered id and a
+     * registry with no store both report
+     */
     save(id: string): Promise<boolean>;
+    /**
+     * Drops one registered workspace and destroys it.
+     *
+     * @param id - The workspace identifier
+     * @returns True if a workspace was dropped; false otherwise
+     */
     remove(id: string): boolean;
+    /**
+     * Drops each id of a batch, dropping every registered one.
+     *
+     * @param ids - The workspace identifiers
+     * @returns True if every entry succeeded; false otherwise
+     */
     remove(ids: readonly string[]): boolean;
+    /** Empties the registry, destroying each workspace and clearing the selection. */
     clear(): void;
 }
 
 /**
- * Workspace-manager construction options.
+ * Configures a workspace registry at construction.
  *
+ * @remarks
  * `on` and `error` become defaults for created workspaces; `store` supplies optional durability.
  */
 export declare interface WorkspaceManagerOptions {
@@ -648,11 +895,12 @@ export declare interface WorkspaceManagerOptions {
 }
 
 /**
- * Workspace construction options.
+ * Configures a workspace at construction.
  *
  * @remarks
- * `id` supplies the registry key, `on` supplies initial event listeners, `error` receives isolated
- * listener failures, and `seed` hydrates initial immutable files without emitting edits.
+ * `id` supplies the registry key. Default: a minted UUID. `on` supplies initial event listeners,
+ * `error` receives isolated listener failures, and `seed` hydrates initial immutable files without
+ * emitting edits.
  */
 export declare interface WorkspaceOptions {
     readonly id?: string;
@@ -661,36 +909,36 @@ export declare interface WorkspaceOptions {
     readonly seed?: Iterable<FileInterface>;
 }
 
-/** A JSON-serializable workspace snapshot. */
+/** Represents a workspace's stored state in JSON-serializable form. */
 export declare interface WorkspaceSnapshot {
     readonly id: string;
     readonly files: readonly FileInterface[];
 }
 
-/** The database row used to persist one opaque workspace snapshot. */
+/** Represents the database row used to persist one opaque workspace snapshot. */
 export declare interface WorkspaceSnapshotRow {
     readonly id: string;
     readonly snapshot: unknown;
 }
 
-/** The asynchronous point-access persistence contract for workspace snapshots. */
+/** Persists workspace snapshots through an asynchronous point-access contract. */
 export declare interface WorkspaceStoreInterface {
     /**
-     * Resolve a snapshot.
+     * Resolves a snapshot by workspace id.
      *
      * @param id - The workspace identifier
      * @returns The snapshot, or `undefined` when absent
      */
     get(id: string): Promise<WorkspaceSnapshot | undefined>;
     /**
-     * Insert or replace a snapshot under its own identifier.
+     * Inserts or replaces a snapshot under its own identifier.
      *
      * @param snapshot - The snapshot to persist
      * @returns A promise that resolves when persistence completes
      */
     set(snapshot: WorkspaceSnapshot): Promise<void>;
     /**
-     * Delete a snapshot when present.
+     * Deletes a snapshot when present.
      *
      * @param id - The workspace identifier
      * @returns A promise that resolves when deletion completes