@zeix/cause-effect 1.0.0 → 1.0.2

package/skills/tech-writer/workflows/consistency-review.md

@@ -0,0 +1,98 @@
+<required_reading>
+1. references/document-map.md — full index of documents, their scope, and what to verify in each
+</required_reading>
+
+<process>
+## Step 1: Read the source of truth
+
+Read `index.ts` for the complete public API surface. Read `src/graph.ts` for the graph engine
+and internal node shapes. Note the current version in `package.json`.
+
+These are the ground truth. Every document is checked against them, not against each other.
+
+## Step 2: Check each document in turn
+
+Work through the documents in this order. For each one, read the current document alongside
+the relevant source, then record findings before moving to the next.
+
+### REQUIREMENTS.md
+- Signal type table (9 types) matches the exports in `index.ts`
+- Bundle size targets still reflect current library scope
+- Non-goals do not contradict any feature that has since been added
+- Stability section reflects the current version and release status
+
+### ARCHITECTURE.md
+- Concrete Node Types table matches the node shapes in `src/graph.ts`
+- Node Field Mixins table matches `SourceFields`, `SinkFields`, `OwnerFields`, `AsyncFields`
+  as defined in `src/graph.ts`
+- Flag names (`FLAG_CLEAN`, `FLAG_CHECK`, `FLAG_DIRTY`, `FLAG_RUNNING`) match `src/graph.ts`
+- Each signal type subsection describes the correct internal composition and lifecycle
+- No subsection references a removed node type, flag, or function
+
+### CLAUDE.md
+- Internal Node Shapes block matches `src/graph.ts`
+- `activeOwner` / `activeSink` semantics description is accurate
+- Each non-obvious behavior entry is still accurate for the current implementation
+- Mental model analogy covers all 9 signal types
+
+### .github/copilot-instructions.md
+- Signal Types list covers all 9 signal types with accurate one-line descriptions
+- Key Files Structure lists all current `src/` files
+- Code patterns in "Common Code Patterns" compile against current `index.ts`
+  (check factory signatures, option names, parameter order)
+- API Design Principles reflect current conventions
+
+### README.md
+- Every factory function exported from `index.ts` has a documented `### SignalType` section
+- All option names, parameter names, and types match current signatures
+- Code examples in the API section use current factory signatures
+- "Choosing the Right Signal" table covers all 9 signal types
+- "Advanced Usage" examples use current API
+
+### GUIDE.md
+- "The Familiar Core" table references current factory function names
+- "What Works Differently" sections describe current behavior
+- "Beyond the Basics" signal type sections are accurate and use current API
+- Code examples compile against current `index.ts`
+
+### JSDoc in src/ (spot-check)
+- Read `src/nodes/state.ts`, `src/nodes/memo.ts`, and `src/nodes/effect.ts`
+- Verify that `@param` tags match current parameter names and types
+- Verify that `@returns` descriptions are accurate
+- Flag any JSDoc that describes removed or renamed options
+
+## Step 3: Compile findings
+
+Produce a structured report before making any edits:
+
+```
+## Consistency Review — [date]
+
+### Accurate (no changes needed)
+- REQUIREMENTS.md: consistent
+- ...
+
+### Gaps found
+- ARCHITECTURE.md, "Concrete Node Types": [specific claim] is outdated — [what is correct]
+- README.md, "### Task": option `abort` renamed to `signal` in current index.ts
+- ...
+```
+
+Be specific: name the document, section, and the exact discrepancy. Do not summarize vaguely.
+
+## Step 4: Confirm before editing
+
+Present the report and ask: **"Shall I apply all of these updates, or would you like to
+review and select?"**
+
+Do not make any edits until explicitly confirmed. If the user confirms all, follow the
+relevant per-document workflow for each gap identified. If they select a subset, update
+only those.
+</process>
+
+<success_criteria>
+- All seven documents checked against current source (`index.ts`, `src/graph.ts`)
+- Findings reported as a structured list with specific document, section, and discrepancy
+- No edits made before confirmation
+- After confirmation, each gap resolved using the appropriate per-document workflow
+</success_criteria>

package/skills/tech-writer/workflows/update-after-change.md

@@ -0,0 +1,65 @@
+<required_reading>
+1. references/document-map.md — map the change type to affected documents
+</required_reading>
+
+<process>
+## Step 1: Understand the change
+
+Inspect the diff against the main branch:
+
+```bash
+git diff main..HEAD -- src/ index.ts
+```
+
+If no diff is available, ask the user to describe what changed.
+
+## Step 2: Classify the change
+
+Identify which of the following change types apply — more than one may apply:
+
+| Change type | Examples |
+|---|---|
+| **New public API** | New factory function, new export, new type in `index.ts` |
+| **Changed public API** | Modified signature, new option, renamed parameter, changed return type |
+| **Removed public API** | Removed export, removed option, removed type |
+| **New or changed non-obvious behavior** | Graph semantics, propagation edge case, ownership subtlety |
+| **Internal implementation change** | Graph engine logic, flag values, node shapes, propagation algorithm |
+| **Vision or scope change** | New design principle, changed audience, new constraint or non-goal |
+
+## Step 3: Determine affected documents
+
+Use this table to identify which documents need updating:
+
+| Change type | JSDoc | ARCHITECTURE.md | CLAUDE.md + copilot | README.md | GUIDE.md | REQUIREMENTS.md |
+|---|---|---|---|---|---|---|
+| New public API | ✓ | ✓ | ✓ | ✓ | ✓ if conceptually new | ✓ signal type table only |
+| Changed public API | ✓ | if node shape changed | ✓ if behavior changes | ✓ | ✓ if affects mental model | ✗ |
+| Removed public API | ✓ | ✓ if structural | ✓ | ✓ | ✓ if was documented | ✗ |
+| New/changed non-obvious behavior | ✗ | ✓ if graph-level | ✓ | ✓ if affects usage pattern | ✗ | ✗ |
+| Internal implementation change | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ |
+| Vision or scope change | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ |
+
+## Step 4: Update affected documents in order
+
+Follow the corresponding workflow for each affected document. Always work in this order — each layer informs the next:
+
+1. **JSDoc** (`src/`) — closest to code; establishes precise wording
+   → workflows/update-jsdoc.md
+2. **ARCHITECTURE.md** — internal structure; must be consistent with source
+   → workflows/update-architecture.md
+3. **CLAUDE.md + copilot-instructions.md** — agent docs; must be consistent with architecture
+   → workflows/update-agent-docs.md
+4. **README.md + GUIDE.md** — public docs; must be consistent with API and agent docs
+   → workflows/update-public-api.md
+5. **REQUIREMENTS.md** — only if scope changed
+   → workflows/update-requirements.md
+
+Skip any document not identified as affected in Step 3.
+</process>
+
+<success_criteria>
+- Change type(s) correctly identified from the diff or description
+- Only affected documents updated — no speculative edits
+- Documents updated in the prescribed order
+- Each document follows its tone guide
+</success_criteria>

package/skills/tech-writer/workflows/update-agent-docs.md

@@ -0,0 +1,77 @@
+<required_reading>
+1. references/document-map.md — CLAUDE.md and copilot-instructions.md sections
+2. references/tone-guide.md — agent-docs tone rules
+</required_reading>
+
+<process>
+## Step 1: Read the source
+
+Read the relevant `src/nodes/*.ts` file(s) and `src/graph.ts` if the change touches graph
+semantics. Read the current `CLAUDE.md` and `.github/copilot-instructions.md` in full.
+Never update agent docs from memory — subtle inaccuracies are worse than gaps.
+
+## Step 2: Update CLAUDE.md
+
+CLAUDE.md is the inference-time reference for Claude. It covers the mental model, internal
+node shapes, and non-obvious behaviors. Token cost is real — every line must earn its place.
+
+**Mental model section**
+- Update the spreadsheet-cell analogy if a new signal type is added. One line per type,
+  consistent with the existing terse style.
+
+**Internal Node Shapes section**
+- Update the node shape table if `SourceFields`, `SinkFields`, `OwnerFields`, or `AsyncFields`
+  changed in `src/graph.ts`, or if a new node type was added.
+- Update the `activeOwner` / `activeSink` description if their semantics changed.
+
+**Non-Obvious Behaviors section**
+- Add an entry when a behavior is counterintuitive enough that a competent developer would
+  not predict it from the public API alone.
+- Remove or correct an entry when a previously non-obvious behavior has changed.
+
+Each entry must follow this structure exactly:
+1. **Bold statement** of the behavior — one sentence, declarative.
+2. One or two sentences of implication. No padding.
+3. A code example only if the correct pattern is non-obvious from the statement alone.
+   Use the existing before/after style where it adds clarity.
+
+Do NOT add entries for behavior that is obvious from the type signatures or from standard
+reactive library conventions. The bar is: would an experienced reactive developer be
+surprised by this?
+
+## Step 3: Update .github/copilot-instructions.md
+
+copilot-instructions.md drives GitHub Copilot's code generation. Accuracy of the code
+patterns is critical — Copilot uses these as generation templates.
+
+**Core Architecture section**
+- Update the node type list if a new node type was added or an existing one changed role.
+- Update the flag list (`FLAG_CLEAN`, `FLAG_CHECK`, `FLAG_DIRTY`, `FLAG_RUNNING`) if flags
+  were added, renamed, or removed.
+
+**Signal Types section**
+- Add a one-line entry for each new signal type: `**Name** (\`createName\`): description`.
+- Update the description of any signal type whose behavior or options changed.
+
+**Key Files Structure section**
+- Add a new line if a new source file was added.
+
+**Common Code Patterns section**
+- This is the highest-value section. Update the code block under "Creating Signals" to
+  reflect any changed factory signatures or new signal types.
+- Patterns must compile against the current API. Verify each pattern against `index.ts`.
+- Add a new pattern block only if the new usage cannot be inferred from existing patterns.
+
+**Coding Conventions / API Design Principles sections**
+- Update only if a new convention was established or an existing one changed.
+</process>
+
+<success_criteria>
+- Source file(s) read before any edits
+- CLAUDE.md non-obvious behavior entries accurate, terse, and consistently structured
+- CLAUDE.md node shapes consistent with `src/graph.ts`
+- copilot-instructions.md code patterns compile against the current `index.ts`
+- Both documents remain concise — no explanatory padding
+- Tone matches references/tone-guide.md: terse and direct for CLAUDE.md,
+  structured and pattern-focused for copilot-instructions.md
+</success_criteria>

package/skills/tech-writer/workflows/update-architecture.md

@@ -0,0 +1,61 @@
+<required_reading>
+1. references/document-map.md — ARCHITECTURE.md section
+2. references/tone-guide.md — architecture tone rules
+</required_reading>
+
+<process>
+## Step 1: Read the source of truth
+
+Read `src/graph.ts` in full. Read any changed `src/nodes/*.ts` file(s). ARCHITECTURE.md
+describes internals — accuracy requires reading the actual implementation, not inferring
+from public API or documentation.
+
+## Step 2: Identify what changed architecturally
+
+Changes that warrant an ARCHITECTURE.md update:
+
+| Changed | Section to update |
+|---|---|
+| Edge structure (`Edge` type fields) | Core Data Structures → Edges |
+| Node field mixins (`SourceFields`, `SinkFields`, etc.) | Core Data Structures → Node Field Mixins |
+| Concrete node types or their composition | Core Data Structures → Concrete Node Types |
+| `activeSink` protocol or `link()`/`trimSources()`/`unlink()` | Automatic Dependency Tracking |
+| Flag values or `propagate()`/`refresh()`/`setState()` | Change Propagation |
+| `batch()`/`flush()` or effect scheduling | Effect Scheduling |
+| `activeOwner`, cleanup storage, `createScope()` | Ownership and Cleanup |
+| New or changed signal type | Signal Types → relevant subsection |
+
+Do NOT update sections that remain accurate. If only `src/nodes/memo.ts` changed, only
+the Memo subsection under "Signal Types" needs editing.
+
+## Step 3: Update the affected section(s)
+
+For each affected section:
+
+1. Re-read the current section text alongside the new source.
+2. Identify specific claims that are now wrong or incomplete.
+3. Make the minimal edit that makes those claims accurate.
+
+**Node shape changes:** Update the table in "Concrete Node Types" and the corresponding
+mixin table if field composition changed. If a new field mixin was added, add a row.
+
+**Propagation or flag changes:** Update the prose description and any pseudocode or
+inline code that references the changed behavior. If flag names changed, update every
+occurrence.
+
+**New signal type:** Add a new subsection under "Signal Types" following the existing
+pattern: one paragraph describing the node's role in the graph, its internal composition,
+and any non-obvious lifecycle behavior (watched activation, ownership, async cancellation).
+Do not duplicate the public API — describe the internal mechanics only.
+
+**Removed signal type:** Remove its subsection. Check for cross-references in other
+subsections.
+</process>
+
+<success_criteria>
+- `src/graph.ts` read in full before any edits
+- Only sections affected by the change were modified
+- Node shapes, flag names, and function descriptions match the current source exactly
+- New signal type subsection follows the structure and depth of existing subsections
+- Tone is technical and internal-facing per references/tone-guide.md
+</success_criteria>

package/skills/tech-writer/workflows/update-jsdoc.md

@@ -0,0 +1,72 @@
+<required_reading>
+1. references/tone-guide.md — jsdoc tone rules
+</required_reading>
+
+<process>
+## Step 1: Read the implementation first
+
+Read the full source file being updated. JSDoc must describe what the code actually does —
+not what it should do, not what the previous version did.
+
+For public API changes, also read `index.ts` to confirm the exported signature matches
+the implementation.
+
+## Step 2: Identify which JSDoc blocks need updating
+
+A JSDoc block needs updating when any of the following changed:
+
+- The function signature (parameter added, removed, renamed, or retyped)
+- The return type or return value semantics
+- A thrown error condition that a caller must handle
+- The function no longer exists (remove the block with the function)
+
+Do NOT update JSDoc blocks that remain accurate. Read each existing block against the
+current implementation before deciding whether to edit it.
+
+## Step 3: Write or update the JSDoc block
+
+Follow this structure for all public API functions:
+
+```typescript
+/**
+ * One-line summary. No period if it reads as a fragment; period if it reads as a sentence.
+ *
+ * Second paragraph only if the one-liner is genuinely insufficient — e.g. a non-obvious
+ * constraint or a behavioral guarantee that cannot fit on one line. Omit otherwise.
+ *
+ * @param name - What it is. Include constraints (`T extends {}`, valid range, allowed
+ *   values). One line per param; wrap only if a constraint needs explaining.
+ * @param options - Options object, if present. Document only options that are non-obvious;
+ *   skip `equals` and `guard` unless the signal's default behavior for them is unusual.
+ * @returns What is returned and any guarantee about its value (e.g. "Always non-nullish").
+ */
+```
+
+**Constraints on length:**
+- Summary line: one line, no exceptions.
+- `@param` entries: one line each unless a constraint genuinely requires a second.
+- No `@example` blocks — examples live in `README.md`. Add one only if the usage pattern
+  is so non-obvious that a developer would misuse the function without it.
+- No `@throws` unless the error can occur in correct, non-erroneous usage (e.g.
+  `UnsetSignalValueError` on `Sensor.get()` before first value). Do not document
+  programmer-error throws (`RequiredOwnerError`, `InvalidCallbackError`, `CircularDependencyError`).
+
+**Type annotations in JSDoc:**
+- Do NOT repeat TypeScript types in `@param` or `@returns` tags. TypeScript already
+  enforces them. Only describe semantics, not types.
+
+## Step 4: Check consistency across the file
+
+After updating, scan the rest of the file for any JSDoc that cross-references the changed
+function or type. Update those references if they are now stale.
+</process>
+
+<success_criteria>
+- Source file read in full before any edits
+- Every updated block has a one-line summary
+- No `@example` blocks added unless usage is genuinely non-obvious
+- No `@throws` for programmer-error conditions
+- TypeScript types not duplicated in JSDoc prose
+- Updated blocks compile without JSDoc-related errors
+- Unchanged blocks left untouched
+</success_criteria>

package/skills/tech-writer/workflows/update-public-api.md

@@ -0,0 +1,59 @@
+<required_reading>
+1. references/document-map.md — README.md and GUIDE.md sections
+2. references/tone-guide.md — public-api and guide tone rules
+</required_reading>
+
+<process>
+## Step 1: Read the source of truth
+
+Read `index.ts` for the current public API surface. Read the relevant `src/nodes/*.ts`
+file(s) for any changed signal type. Do this before opening either document.
+
+## Step 2: Update README.md
+
+README.md is the authoritative public API reference. Make targeted edits only:
+
+**New signal type**
+- Add a `### SignalType` section under `## API` with: factory signature, all options, and
+  at least one realistic example showing normal usage.
+- Add the type to the "Choosing the Right Signal" table with a one-line description.
+- If the type participates in ownership or has a `watched` lifecycle, add an example to
+  "Advanced Usage → Resource Management".
+
+**Changed option or signature**
+- Update the relevant `### SignalType` section. Update the example if the old pattern no
+  longer compiles or no longer represents idiomatic usage.
+- If the change is a rename or a breaking type change, note the migration inline under the
+  parameter description, not in a separate section.
+
+**Removed API**
+- Remove all mentions. Check: the API section, "Choosing the Right Signal", "Advanced Usage",
+  and any cross-references in other signal type sections.
+
+**New or changed behavior**
+- Update the description in the relevant section. If the behavior is subtle, add or update
+  an example. If it is an advanced pattern, add to "Advanced Usage".
+
+## Step 3: Update GUIDE.md
+
+GUIDE.md explains the library through the lens of developers migrating from React, Vue,
+or Angular. Update it only when the change affects the conceptual picture:
+
+- **"The Familiar Core" table** — update if a core factory name changes.
+- **"What Works Differently"** — update if a fundamental behavioral contract changes
+  (e.g. synchronous vs. async execution, nullability rules, ownership model).
+- **"Beyond the Basics"** — update if a new signal type is added, or if a major signal
+  type changes significantly enough that its comparative explanation is wrong.
+
+Do NOT add every option change or minor signature tweak to GUIDE.md. Only update it when
+a developer's existing mental model from another framework would now lead them astray.
+</process>
+
+<success_criteria>
+- `index.ts` read before any edits were made
+- README.md accurately reflects the current public API: all factories documented, all
+  options current, all examples valid
+- GUIDE.md updated only where the conceptual picture for framework migrants changed
+- Both documents follow their respective tones from references/tone-guide.md
+- No sections rewritten beyond what the change requires
+</success_criteria>

package/skills/tech-writer/workflows/update-requirements.md

@@ -0,0 +1,80 @@
+<required_reading>
+1. references/document-map.md — REQUIREMENTS.md section
+2. references/tone-guide.md — requirements tone rules
+</required_reading>
+
+<process>
+## Step 1: Confirm the update is warranted
+
+REQUIREMENTS.md captures the library's vision, audience, design principles, constraints,
+and non-goals. It is intentionally written to survive version bumps. Do NOT update it for:
+
+- Bug fixes or internal refactors
+- New options on existing signal types
+- Changed implementation details
+- Documentation or tooling changes
+
+Only update REQUIREMENTS.md when one of these applies:
+
+| Trigger | Section affected |
+|---|---|
+| A new signal type is added to the library | "Design Principles → Minimal Surface, Maximum Coverage" table |
+| A signal type is removed | Same table + "Non-Goals" if it was previously out of scope |
+| A runtime environment is added or dropped | "Runtime Environments" |
+| A bundle size target changes | "Size and Performance Constraints" |
+| A design principle is added, changed, or removed | "Design Principles" |
+| The primary or secondary audience shifts | "Audience" |
+| A non-goal is resolved or a new one is added | "Non-Goals" |
+| Stability guarantees change | "Stability" |
+
+If the change does not meet any of these criteria, stop and explain why REQUIREMENTS.md
+does not need updating. Do not edit it speculatively.
+
+## Step 2: Read the full document
+
+Read `REQUIREMENTS.md` in full before touching anything. Identify the single section
+(or at most two) that the change affects. Changes to REQUIREMENTS.md are almost always
+one table row, one list item, or one short paragraph — rarely more.
+
+## Step 3: Make the minimal edit
+
+Make only the change the trigger warrants:
+
+**Signal type table (most common):**
+Add or remove a row. The row format is:
+`| **Type** | Role description | Data structure |`
+Keep the role description to one short phrase. The table reflects the final state
+of the type set — it is not a changelog.
+
+**Runtime environments:**
+Add or remove the environment name from the prose list. One line.
+
+**Bundle size targets:**
+Update the number in the table. If the target changed for a reason that future readers
+should understand, add one sentence of rationale — no more.
+
+**Non-goals:**
+Each non-goal is a bold heading followed by one sentence. Do not expand them into
+paragraphs. If adding a new non-goal, follow the same pattern. If resolving one,
+remove it entirely — do not mark it as resolved inline.
+
+**Stability section:**
+Update only the factual claims (version number, breaking change expectations). Preserve
+the formal register of the surrounding text.
+
+## Step 4: Verify internal consistency
+
+After editing, confirm:
+- The signal type table count matches the count stated in the prose ("9 signal types").
+- The "Non-Goals" section does not contradict anything now present in the codebase.
+- The "Stability" section accurately describes the current version and compatibility stance.
+</process>
+
+<success_criteria>
+- Update was warranted by one of the listed triggers
+- Only the affected section was changed — no rewrites of accurate content
+- Signal type table count consistent with prose and with `index.ts`
+- Formal, strategic tone preserved throughout per references/tone-guide.md
+- No changelog-style language ("previously", "now", "we changed") — state the current
+  truth only
+</success_criteria>

package/src/graph.ts

@@ -590,6 +590,8 @@ function createScope(fn: () => MaybeCleanup): Cleanup {
  * reactive graph.
  *
  * @since 0.18.5
+ * @param fn - The function to execute without an active owner
+ * @returns The return value of `fn`
  */
 function unown<T>(fn: () => T): T {
 	const prev = activeOwner

package/src/nodes/collection.ts

@@ -36,10 +36,24 @@ import { createTask } from './task'
 
 type CollectionSource<T extends {}> = List<T> | Collection<T>
 
+/**
+ * Transformation callback for `deriveCollection` — sync or async.
+ * Sync callbacks produce a `Memo<T>` per item; async callbacks produce a `Task<T>`
+ * with automatic cancellation when the source item changes.
+ *
+ * @template T - The type of derived items
+ * @template U - The type of source items
+ */
 type DeriveCollectionCallback<T extends {}, U extends {}> =
 	| ((sourceValue: U) => T)
 	| ((sourceValue: U, abort: AbortSignal) => Promise<T>)
 
+/**
+ * A read-only reactive keyed collection with per-item reactivity.
+ * Created by `createCollection` (externally driven) or via `.deriveCollection()` on a `List` or `Collection`.
+ *
+ * @template T - The type of items in the collection
+ */
 type Collection<T extends {}> = {
 	readonly [Symbol.toStringTag]: 'Collection'
 	readonly [Symbol.isConcatSpreadable]: true
@@ -59,18 +73,42 @@ type Collection<T extends {}> = {
 	readonly length: number
 }
 
+/**
+ * Granular mutation descriptor passed to the `applyChanges` callback inside a `CollectionCallback`.
+ *
+ * @template T - The type of items in the collection
+ */
 type CollectionChanges<T> = {
+	/** Items to add. Each item is assigned a new key via the configured `keyConfig`. */
 	add?: T[]
+	/** Items whose values have changed. Matched to existing entries by key. */
 	change?: T[]
+	/** Items to remove. Matched to existing entries by key. */
 	remove?: T[]
 }
 
+/**
+ * Configuration options for `createCollection`.
+ *
+ * @template T - The type of items in the collection
+ */
 type CollectionOptions<T extends {}> = {
+	/** Initial items. Defaults to `[]`. */
 	value?: T[]
+	/** Key generation strategy. See `KeyConfig`. Defaults to auto-increment. */
 	keyConfig?: KeyConfig<T>
+	/** Factory for per-item signals. Defaults to `createState`. */
 	createItem?: (value: T) => Signal<T>
 }
 
+/**
+ * Setup callback for `createCollection`. Invoked when the collection gains its first downstream
+ * subscriber; receives an `applyChanges` function to push granular mutations into the graph.
+ *
+ * @template T - The type of items in the collection
+ * @param apply - Call with a `CollectionChanges` object to add, update, or remove items
+ * @returns A cleanup function invoked when the collection loses all subscribers
+ */
 type CollectionCallback<T extends {}> = (
 	apply: (changes: CollectionChanges<T>) => void,
 ) => Cleanup

package/src/nodes/effect.ts

@@ -20,13 +20,22 @@ import {
 
 /* === Types === */
 
+/** A value that is either synchronous or a `Promise` — used for handler return types in `match()`. */
 type MaybePromise<T> = T | Promise<T>
 
+/**
+ * Handlers for all states of one or more signals passed to `match()`.
+ *
+ * @template T - Tuple of `Signal` types being matched
+ */
 type MatchHandlers<T extends readonly Signal<unknown & {}>[]> = {
+	/** Called when all signals have a value. Receives a tuple of resolved values. */
 	ok: (values: {
 		[K in keyof T]: T[K] extends Signal<infer V> ? V : never
 	}) => MaybePromise<MaybeCleanup>
+	/** Called when one or more signals hold an error. Defaults to `console.error`. */
 	err?: (errors: readonly Error[]) => MaybePromise<MaybeCleanup>
+	/** Called when one or more signals are unset (pending). */
 	nil?: () => MaybePromise<MaybeCleanup>
 }
 
@@ -88,10 +97,13 @@ function createEffect(fn: EffectCallback): Cleanup {
 }
 
 /**
- * Runs handlers based on the current values of signals.
+ * Reads one or more signals and dispatches to the appropriate handler based on their state.
  * Must be called within an active owner (effect or scope) so async cleanup can be registered.
  *
  * @since 0.15.0
+ * @param signals - Tuple of signals to read; all must have a value for `ok` to run.
+ * @param handlers - Object with an `ok` branch and optional `err` and `nil` branches.
+ * @returns An optional cleanup function if the active handler returns one.
  * @throws RequiredOwnerError If called without an active owner.
  */
 function match<T extends readonly Signal<unknown & {}>[]>(