tutuca 0.9.39 → 0.9.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.39",
+  "version": "0.9.41",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",
@@ -20,9 +20,11 @@
     "dist": "bun scripts/dist.js",
     "dist-immutable": "bun scripts/dist-immutable.js",
     "dist-all": "bun run dist-immutable && bun run dist",
-    "release": "bun run dist-all && bun run build-skill && npm publish --access public",
-    "release-dry": "bun run dist-all && bun run build-skill && npm publish --dry-run",
+    "release": "bun run dist-all && bun run build-skill && bun run build-margaui-skill && bun run build-immutable-skill && npm publish --access public",
+    "release-dry": "bun run dist-all && bun run build-skill && bun run build-margaui-skill && bun run build-immutable-skill && npm publish --dry-run",
     "build-skill": "bun scripts/build-skill.js",
+    "build-margaui-skill": "bun scripts/build-margaui-skill.js",
+    "build-immutable-skill": "bun scripts/build-immutable-skill.js",
     "test": "bun test test/*.test.js",
     "test-watch": "bun test --watch test/*.test.js",
     "format": "bunx @biomejs/biome format --write src test/*.js docs/src/*.js docs/examples/*.js tools/*.js tools/*/*.js",
@@ -42,10 +44,7 @@
     "dist/tutuca-extra.js",
     "dist/tutuca-extra.min.js",
     "dist/tutuca-cli.js",
-    "skill/SKILL.md",
-    "skill/core.md",
-    "skill/cli.md",
-    "skill/advanced.md"
+    "skill"
   ],
   "dependencies": {
     "jsdom": "^28.0.0 || ^29.0.0"

package/skill/immutable-js/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: immutable-js
+description: Reference for the Immutable.js API organized by datatype (List, Map, Set, OrderedMap, OrderedSet, Stack, Record, Seq, Collection, Range, Repeat) and by topic (deep updates, equality, type predicates, JS conversion). Use when the user asks how to use a specific Immutable.js datatype or method, when writing or reviewing code in this repository, or when explaining Immutable.js semantics like persistent updates, value equality, or lazy evaluation.
+---
+
+# Immutable.js
+
+Persistent immutable data structures for JavaScript. All operations return a
+new collection rather than mutating the original; structural sharing keeps
+this efficient. Treat collections as **values**, not objects — compare with
+`is(a, b)` or `a.equals(b)`, never `===`.
+
+```js
+import { Map } from 'immutable';
+const m1 = Map({ a: 1, b: 2 });
+const m2 = m1.set('b', 50);
+m1.get('b'); // 2  — m1 is unchanged
+m2.get('b'); // 50
+```
+
+## Inheritance cheatsheet
+
+```
+Collection ─┬─ Collection.Keyed   ─┬─ Map ── OrderedMap
+            │                      └─ Record (object-like, fixed keys)
+            │
+            ├─ Collection.Indexed ─┬─ List
+            │                      └─ Stack
+            │
+            └─ Collection.Set     ─┬─ Set ── OrderedSet
+                                   └─ (OrderedCollection marker)
+
+Seq mirrors the hierarchy lazily:
+  Seq ─┬─ Seq.Keyed   ─ keyed lazy sequence
+       ├─ Seq.Indexed ─ indexed lazy sequence
+       └─ Seq.Set     ─ set-like lazy sequence
+```
+
+## Datatypes
+
+Read the reference for a specific datatype when answering questions about
+its constructors, methods, or semantics.
+
+- [List](references/list.md) — ordered indexed collection (push/pop/get/set/etc.)
+- [Map](references/map.md) — keyed collection with value-equality keys; covers OrderedMap
+- [Set](references/set.md) — unique values with value equality; covers OrderedSet
+- [Stack](references/stack.md) — LIFO; fast push/pop/peek at the front
+- [Record](references/record.md) — fixed-shape, named, typed record; class-like
+- [Seq](references/seq.md) — lazy sequence (Keyed / Indexed / Set variants)
+- [Collection](references/collection.md) — abstract base; methods shared by all collections
+- [Range, Repeat](references/range-repeat.md) — lazy generator factories
+
+## Operations and topics
+
+Cross-cutting topics. Load these alongside (or instead of) a datatype reference
+when the question is about an operation rather than a single type.
+
+- [Deep updates](references/deep-updates.md) — `getIn`, `setIn`, `updateIn`, `removeIn`, `hasIn`, `merge`, `mergeWith`, `mergeDeep`, `mergeDeepWith`
+- [Shallow functional helpers](references/shallow-functional.md) — top-level `get`, `set`, `has`, `update`, `remove` that work on any collection or plain JS object
+- [JS conversions](references/conversions.md) — `fromJS`, `toJS`, plain-JS interop, reviver patterns
+- [Equality and hashing](references/equality.md) — `is`, `hash`, `ValueObject`, `isValueObject`, value vs reference semantics
+- [Type predicates](references/predicates.md) — `isList`, `isMap`, `isSet`, `isOrderedMap`, `isOrderedSet`, `isStack`, `isRecord`, `isSeq`, `isCollection`, `isKeyed`, `isIndexed`, `isAssociative`, `isOrdered`, `isImmutable`
+
+## Cross-cutting semantics worth knowing up front
+
+- **Value equality**: keys in `Map`/`Set` and elements in `Set` compare by `is()`, not `===`. Two distinct `Map({a:1})` instances are equal as keys.
+- **Identity preservation**: an operation that produces an equal collection returns the original (`===`-identical), so memoization with `===` is sound.
+- **Mutation batching**: `withMutations(c => { c.set(...).push(...) })` builds a transient copy; cheaper than chained calls when doing many updates.
+- **Lazy `Seq`**: chained `map`/`filter`/etc. on a `Seq` doesn't run until something pulls values (e.g. `toList()`, `forEach`, iteration). See [seq.md](references/seq.md).
+- **Path-based updates**: `setIn`/`updateIn`/`mergeDeep` create missing intermediate `Map`s by default. See [deep-updates.md](references/deep-updates.md).
+- **`fromJS` is shallow-recursive**: arrays become `List`, plain objects become `Map`. Customize with the `reviver`. See [conversions.md](references/conversions.md).
+
+## Authoritative sources in this repo
+
+When a reference here is ambiguous or you need an exact signature, fall back to:
+
+- `type-definitions/immutable.d.ts` — canonical TypeScript signatures for the entire public API
+- `website/docs/<Name>.mdx` — the original long-form docs each reference here distills
+- `README.md` — top-level rationale and worked examples

package/skill/immutable-js/references/collection.md

@@ -0,0 +1,346 @@
+`Collection<K, V>` is the abstract base interface for every immutable iterable in immutable-js. You never construct a `Collection` directly — you construct one of the concrete types (`List`, `Map`, `Set`, `Stack`, `Seq`, `Record`) and use the methods documented here, all of which they inherit. Three sub-interfaces tailor the iteration shape: `Collection.Keyed<K, V>` yields `[K, V]` tuples, `Collection.Indexed<T>` yields values in numeric-index order, and `Collection.Set<T>` yields values (value-unique on concrete `Set`/`OrderedSet`). The `Collection(...)` factory is also a conversion function: returns an existing `Collection` unchanged, wraps an array-like as `Collection.Indexed`, wraps a plain object as `Collection.Keyed<string, V>`.
+
+## Class hierarchy summary
+
+```
+Collection
+├─ Collection.Keyed   → Map, OrderedMap, Record  (and Seq.Keyed)
+├─ Collection.Indexed → List, Stack              (and Seq.Indexed)
+└─ Collection.Set     → Set, OrderedSet          (and Seq.Set)
+```
+
+`OrderedCollection<T>` is a marker interface (no own behaviour) mixed into every type with stable iteration order: `List`, `Stack`, `OrderedMap`, `OrderedSet`, every `Collection.Indexed`/`Seq.Indexed`, and any `Seq.Keyed` built from an ordered source. Detect at runtime with `isOrdered()`. There is no `OrderedCollection` value to construct.
+
+## Reading
+
+### size
+
+```ts
+readonly size: number | undefined;
+```
+
+Element count. Always defined on concrete types; may be `undefined` on a lazy `Seq` whose source has not been evaluated. Use `count()` for a guaranteed number.
+
+### get
+
+```ts
+get(key: K): V | undefined;
+get<NSV>(key: K, notSetValue: NSV): V | NSV;
+```
+
+Returns the value for `key`, or `notSetValue` (or `undefined`) if absent. On `Collection.Indexed`, `key` is a numeric index and negative values count from the end (`get(-1)` is last). Because a stored value may itself be `undefined`, prefer the two-arg form to disambiguate "missing" from "set to undefined".
+
+### has / includes / contains
+
+```ts
+has(key: K): boolean;
+includes(value: V): boolean;
+contains(value: V): boolean; // alias of includes
+```
+
+`has` checks key membership; `includes`/`contains` check value membership. Both use `Immutable.is` (deep value equality).
+
+### first / last
+
+```ts
+first(): V | undefined;
+first<NSV>(notSetValue: NSV): V | NSV;
+last():  V | undefined;
+last<NSV>(notSetValue: NSV):  V | NSV;
+```
+
+First/last value in iteration order, or the optional default if empty.
+
+### getIn / hasIn
+
+```ts
+getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown;
+hasIn(searchKeyPath: Iterable<unknown>): boolean;
+```
+
+Walk a path of keys/indices through nested Immutable collections (and plain JS objects/arrays). See `nested-updates.md`.
+
+## Sequence algorithms (return same kind of collection)
+
+Most return a Collection of the same variant (`this`-typed where possible). For `Map`/`Set`, sorting/reversing returns the ordered counterpart (`OrderedMap`/`OrderedSet`).
+
+### map / flatMap
+
+```ts
+map<M>(mapper: (value: V, key: K, iter: this) => M, context?: unknown): Collection<K, M>;
+flatMap<M>(mapper: (value: V, key: K, iter: this) => Iterable<M>, context?: unknown): Collection<K, M>;
+flatMap<KM, VM>(mapper: (value: V, key: K, iter: this) => Iterable<[KM, VM]>, context?: unknown): Collection<KM, VM>;
+```
+
+Always returns a new instance. `flatMap` is `map(...).flatten(true)`. On `Collection.Set` callbacks, `key === value`.
+
+### filter / filterNot
+
+```ts
+filter(predicate: (value: V, key: K, iter: this) => unknown, context?: unknown): this;
+filter<F extends V>(predicate: (value: V, key: K, iter: this) => value is F, context?: unknown): Collection<K, F>;
+filterNot(predicate: (value: V, key: K, iter: this) => boolean, context?: unknown): this;
+```
+
+`filter` keeps truthy entries; `filterNot` keeps falsy ones. Type guards narrow the result.
+
+### reverse / sort / sortBy
+
+```ts
+reverse(): this;
+sort(comparator?: Comparator<V>): this;
+sortBy<C>(mapper: (value: V, key: K, iter: this) => C, comparator?: Comparator<C>): this;
+```
+
+`comparator(a, b)` returns negative/zero/positive (or a `PairSorting` enum value) and must be pure. Sort is stable. On unordered collections (`Map`, `Set`), the result is the ordered counterpart. Always eager.
+
+### slice / rest / butLast
+
+```ts
+slice(begin?: number, end?: number): this;
+rest():    this;   // all but first
+butLast(): this;   // all but last
+```
+
+Negative slice indices count from the end. Returns the same instance if the slice is the whole collection.
+
+### skip / skipLast / skipWhile / skipUntil / take / takeLast / takeWhile / takeUntil
+
+```ts
+skip(amount: number):     this;
+skipLast(amount: number): this;
+skipWhile(predicate: (value: V, key: K, iter: this) => boolean, context?: unknown): this;
+skipUntil(predicate: (value: V, key: K, iter: this) => boolean, context?: unknown): this;
+take(amount: number):     this;
+takeLast(amount: number): this;
+takeWhile(predicate: (value: V, key: K, iter: this) => boolean, context?: unknown): this;
+takeUntil(predicate: (value: V, key: K, iter: this) => boolean, context?: unknown): this;
+```
+
+`*While` keeps taking/skipping while predicate is true; `*Until` until it becomes true.
+
+### concat / flatten
+
+```ts
+concat(...valuesOrCollections: Array<unknown>): Collection<unknown, unknown>;
+flatten(depth?: number):   Collection<unknown, unknown>;
+flatten(shallow?: boolean): Collection<unknown, unknown>;
+```
+
+Concrete variants narrow `concat`'s return type — see the per-variant sections below. `flatten()` (no args) flattens deeply; `flatten(true)` flattens one level; `flatten(0)` flattens deeply. Only flattens nested Immutable Collections, not arrays/objects.
+
+### groupBy / partition
+
+```ts
+groupBy<G>(grouper: (value: V, key: K, iter: this) => G, context?: unknown): Map<G, this>;
+partition(predicate, context?): [this, this]; // [falsy, truthy]
+partition<F extends V, C>(predicate: (...) => value is F, context?: C): [Collection<K, V>, Collection<K, F>];
+```
+
+`groupBy` is eager and returns a `Map` of group key → Collection of the same variant. `partition` returns `[notMatching, matching]` in one pass.
+
+## Side effects and reductions
+
+### forEach
+
+```ts
+forEach(sideEffect: (value: V, key: K, iter: this) => unknown, context?: unknown): number;
+```
+
+Returns the number of iterations executed. Unlike `Array#forEach`, returning `false` from `sideEffect` aborts iteration.
+
+### reduce / reduceRight
+
+```ts
+reduce<R>(reducer: (acc: R, value: V, key: K, iter: this) => R, initialReduction: R, context?: unknown): R;
+reduce<R>(reducer): R; // first item is the initial reduction
+reduceRight<R>(reducer, initialReduction: R, context?: unknown): R;
+reduceRight<R>(reducer): R;
+```
+
+`reduceRight` is `reverse().reduce(...)`.
+
+### every / some / find* / keyOf*
+
+```ts
+every(predicate, context?: unknown): boolean;
+some(predicate,  context?: unknown): boolean;
+
+find(predicate, context?, notSetValue?: V):          V | undefined;
+findLast(predicate, context?, notSetValue?: V):      V | undefined;
+findEntry(predicate, context?, notSetValue?: V):     [K, V] | undefined;
+findLastEntry(predicate, context?, notSetValue?: V): [K, V] | undefined;
+findKey(predicate,    context?): K | undefined;
+findLastKey(predicate, context?): K | undefined;
+
+keyOf(searchValue: V):     K | undefined;
+lastKeyOf(searchValue: V): K | undefined;
+```
+
+`*Last` variants iterate in reverse. `keyOf`/`lastKeyOf` look up by `Immutable.is` value equality; on `Collection.Indexed` prefer `indexOf`/`lastIndexOf` for clarity.
+
+### max / maxBy / min / minBy
+
+```ts
+max(comparator?: Comparator<V>): V | undefined;
+maxBy<C>(mapper: (value, key, iter) => C, comparator?: Comparator<C>): V | undefined;
+min(comparator?: Comparator<V>): V | undefined;
+minBy<C>(mapper: (value, key, iter) => C, comparator?: Comparator<C>): V | undefined;
+```
+
+Default comparator is `>` / `<`. On ties, the first encountered wins.
+
+### count / countBy / isEmpty / join
+
+```ts
+count(): number;
+count(predicate, context?): number;
+countBy<G>(grouper, context?): Map<G, number>;
+isEmpty(): boolean;
+join(separator?: string): string; // default ","
+```
+
+`count()` always returns the actual size, even for a lazy `Seq` (forcing evaluation). `isEmpty` may iterate at most once on a lazy `Seq`.
+
+### isSubset / isSuperset
+
+```ts
+isSubset(iter:   Iterable<V>): boolean; // every value in this is in iter
+isSuperset(iter: Iterable<V>): boolean; // every value in iter is in this
+```
+
+## Conversion
+
+```ts
+toArray():       Array<V> | Array<[K, V]>;
+toObject():      { [key: string]: V };
+toJS():          Array<DeepCopy<V>> | { [key: PropertyKey]: DeepCopy<V> };
+toJSON():        Array<V> | { [key: PropertyKey]: V };
+
+toList():        List<V>;
+toMap():         Map<K, V>;
+toOrderedMap():  OrderedMap<K, V>;
+toSet():         Set<V>;
+toOrderedSet():  OrderedSet<V>;
+toStack():       Stack<V>;
+
+toSeq():         Seq<K, V>;
+toKeyedSeq():    Seq.Keyed<K, V>;
+toIndexedSeq():  Seq.Indexed<V>;
+toSetSeq():      Seq.Set<V>;
+```
+
+`toJS` is deep (recursively converts nested Immutable structures); `toJSON`/`toArray`/`toObject` are shallow. `Collection.Keyed#toArray` returns `Array<[K, V]>`; `Collection.Indexed`/`Collection.Set#toArray` return `Array<V>`. `to{List,Set,OrderedSet,Stack}` discard keys; `toMap`/`toOrderedMap` throw if keys are not hashable. See `conversions.md`.
+
+## Comparison
+
+```ts
+equals(other: unknown): boolean;
+hashCode(): number;
+```
+
+`equals` is `Immutable.is(this, other)` — deep value equality. `hashCode` is a stable Uint32; equal collections must produce equal hashes. See `equality.md`.
+
+## Iteration
+
+```ts
+keys():    IterableIterator<K>;
+values():  IterableIterator<V>;
+entries(): IterableIterator<[K, V]>;
+[Symbol.iterator](): IterableIterator<unknown>;
+
+keySeq():   Seq.Indexed<K>;
+valueSeq(): Seq.Indexed<V>;
+entrySeq(): Seq.Indexed<[K, V]>;
+```
+
+Default iteration shape per variant: `Keyed` yields `[K, V]` tuples; `Indexed` yields `V` in index order; `Set` yields `V` (value-unique on concrete `Set`). The `keys()`/`values()`/`entries()` methods return ES iterators (no chainable Immutable methods); `keySeq()`/`valueSeq()`/`entrySeq()` return `Seq.Indexed`s that you can chain.
+
+### update
+
+```ts
+update<R>(updater: (value: this) => R): R;
+```
+
+Pipe the collection through a function — useful for chaining (`coll.update(fn).map(...)`). RxJS calls this `let`, lodash calls it `thru`.
+
+## Variant-specific methods
+
+### Collection.Keyed
+
+```ts
+flip(): Collection.Keyed<V, K>;
+mapKeys<M>(mapper: (key: K, value: V, iter: this) => M, context?: unknown): Collection.Keyed<M, V>;
+mapEntries<KM, VM>(
+  mapper: (entry: [K, V], index: number, iter: this) => [KM, VM] | undefined,
+  context?: unknown,
+): Collection.Keyed<KM, VM>;
+
+concat<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): Collection.Keyed<K | KC, V | VC>;
+concat<C>(...collections: Array<{ [key: string]: C }>):    Collection.Keyed<K | string, V | C>;
+```
+
+`flip` swaps keys and values. `mapEntries` may return `undefined` to drop that entry. Inherited `keyOf` returns the key associated with a value (not an index). When iterated, yields `[K, V]`.
+
+### Collection.Indexed
+
+Indices are 0-based and dense ("unset" and `undefined` are indistinguishable; iteration visits every index `0..size`). Negative indices count from the end.
+
+```ts
+indexOf(searchValue: T):     number; // -1 if absent
+lastIndexOf(searchValue: T): number;
+findIndex(predicate, context?):     number;
+findLastIndex(predicate, context?): number;
+
+interpose(separator: T): this;                                     // T, sep, T, sep, T
+interleave(...collections: Array<Collection<unknown, T>>): this;   // round-robin; stops at shortest
+splice(index: number, removeNum: number, ...values: Array<T>): this;
+
+zip<U>(other: Collection<unknown, U>):    Collection.Indexed<[T, U]>;
+zip(...collections):                       Collection.Indexed<unknown>;
+zipAll<U>(other: Collection<unknown, U>): Collection.Indexed<[T, U]>; // pads shorter with undefined
+zipWith<U, Z>(zipper: (value: T, otherValue: U) => Z, other: Collection<unknown, U>): Collection.Indexed<Z>;
+
+concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Collection.Indexed<T | C>;
+fromEntrySeq(): Seq.Keyed<unknown, unknown>; // when T is [K, V], reinterpret as keyed
+```
+
+`splice`, `interleave`, and other reindexing operations are `O(N)` and cannot be used inside `withMutations`. All `Collection.Indexed` methods return re-indexed Collections — to preserve original indices as keys, call `toKeyedSeq()`.
+
+### Collection.Set
+
+Iterates values; on the concrete `Set`/`OrderedSet`, values are unique (`Immutable.is`). On lazy `Seq.Set`, duplicates may be present. In callbacks, `key === value`.
+
+```ts
+concat<U>(...collections: Array<Iterable<U>>):     Collection.Set<T | U>;
+map<M>(mapper: (value: T, key: T, iter: this) => M, context?: unknown):     Collection.Set<M>;
+flatMap<M>(mapper: (value: T, key: T, iter: this) => Iterable<M>, context?: unknown): Collection.Set<M>;
+filter<F extends T>(predicate: (value: T, key: T, iter: this) => value is F, context?: unknown): Collection.Set<F>;
+filter(predicate, context?): this;
+partition(predicate, context?): [this, this];
+```
+
+`union`, `intersect`, and `subtract` are NOT on `Collection.Set` — they live on the concrete `Set`/`OrderedSet`. See `set.md`.
+
+## OrderedCollection
+
+`OrderedCollection<T>` is a marker interface — it adds nothing beyond `toArray()` and `[Symbol.iterator]()` that every collection already has. Its purpose is purely type-level: it identifies collections whose iteration order is deterministic and stable across operations.
+
+Implementers: `List`, `Stack`, `OrderedMap`, `OrderedSet`, every `Collection.Indexed` (so every `Seq.Indexed`), and any `Seq.Keyed` constructed from an ordered source. `Map` and `Set` are NOT ordered. Detect at runtime:
+
+```ts
+function isOrdered<T>(maybeOrdered: Collection<unknown, T>): maybeOrdered is OrderedCollection<T>;
+function isOrdered(maybeOrdered: unknown):                    maybeOrdered is OrderedCollection<unknown>;
+```
+
+`KeyPath<K>` (used by `getIn`/`setIn`/etc.) is typed as `OrderedCollection<K> | ArrayLike<K>` — so any ordered Collection is a valid key path.
+
+## See also
+
+- `list.md`, `stack.md`  — concrete `Collection.Indexed` types
+- `map.md`, `record.md`  — concrete `Collection.Keyed` types
+- `set.md`               — concrete `Collection.Set` types (`union`/`intersect`/`subtract` live here)
+- `seq.md`               — lazy `Seq.Keyed`/`Seq.Indexed`/`Seq.Set`
+- `equality.md`          — `equals`, `hashCode`, `Immutable.is`
+- `conversions.md`       — `toJS`/`fromJS`, `toArray`, cross-type `to*`
+- `predicates.md`        — `isCollection`, `isOrdered`, `isKeyed`, etc.

package/skill/immutable-js/references/conversions.md

@@ -0,0 +1,99 @@
+Immutable.js conversions go in two directions: PARSE plain JS into Immutable with `fromJS`, and PROJECT Immutable back to plain JS with `toJS` / `toJSON` / `toArray` / `toObject` / specific-type converters (`toList`, `toMap`, `toSet`, ...). Reach for `fromJS` when you receive JSON or other plain data at a boundary. Reach for `toJS` only at boundaries (serialization, debugging, libraries that don't speak Immutable) — passing Immutable values around inside your code is preferred since `toJS` is recursive and allocates a fresh deep copy.
+
+## fromJS
+
+```ts
+fromJS(jsValue, reviver?: (key, sequence, path) => unknown): unknown
+```
+
+Default behavior:
+- Plain `Array` → `List`
+- Plain `Object` (no custom prototype, own enumerable string keys) → `Map`
+- Recurses into both
+- Numbers, strings, booleans, `null`, `Date`, `RegExp`, JS `Map`/`Set`, custom class instances pass through unchanged
+
+```js
+import { fromJS } from 'immutable';
+fromJS({ a: { b: [10, 20, 30] }, c: 40 });
+// Map { a: Map { b: List [ 10, 20, 30 ] }, c: 40 }
+```
+
+The optional `reviver` is called bottom-up (deepest collection first) with each level wrapped as a `Seq.Keyed` (for objects) or `Seq.Indexed` (for arrays). It must return an Immutable Collection. The default reviver is effectively:
+
+```js
+(key, value) => (isKeyed(value) ? value.toMap() : value.toList());
+```
+
+Override it to choose different bucket types — e.g. `OrderedMap` + `List`:
+
+```js
+import { fromJS, isKeyed } from 'immutable';
+fromJS(payload, (_, value) =>
+  isKeyed(value) ? value.toOrderedMap() : value.toList()
+);
+```
+
+The reviver also receives a `path` array (sequence of keys from the root) — useful for selectively converting only certain branches (e.g. leave `events` as a `List` but turn `index` into an `OrderedMap`).
+
+## toJS / toJSON
+
+- `toJS()` — recursively converts an Immutable value into plain JS. `Map`/`Record`/Keyed → object (string keys), `List`/`Stack`/Indexed → array, `Set`/`OrderedSet` → array.
+- `toJSON()` — SHALLOW one-level conversion. The same shape (object vs array) but the values are still Immutable.
+- `JSON.stringify(immutableValue)` works out of the box: each node's `toJSON` is invoked recursively by the serializer, so the resulting JSON string IS deeply plain.
+- `Record#toJSON()` returns a plain object with the record's defined keys (no prototype).
+
+```js
+import { Map, List } from 'immutable';
+const m = Map({ items: List([1, 2, 3]) });
+m.toJS(); // { items: [1, 2, 3] }            (deep)
+m.toJSON(); // { items: List [ 1, 2, 3 ] }   (shallow)
+JSON.stringify(m); // '{"items":[1,2,3]}'    (deep, via toJSON recursion)
+```
+
+## Per-type converters
+
+Shallow conversions to plain JS containers:
+
+```ts
+toArray(): Array<V> | Array<[K, V]>   // Keyed → entries; Indexed/Set → values
+toObject(): { [key: string]: V }      // Keyed only; coerces keys to strings
+```
+
+Re-bucket into another Immutable collection (the source's keys may or may not survive — see notes):
+
+```ts
+toList(): List<V>           // discards keys (Map → values only)
+toMap(): Map<K, V>          // requires hashable keys; throws otherwise
+toOrderedMap(): OrderedMap<K, V>  // preserves iteration order
+toSet(): Set<V>             // discards keys; requires hashable values
+toOrderedSet(): OrderedSet<V>     // preserves iteration order
+toStack(): Stack<V>         // discards keys
+```
+
+Lazy `Seq` variants (no work until iterated):
+
+```ts
+toSeq(): Seq<K, V>          // same kind as the source
+toKeyedSeq(): Seq.Keyed<K, V>     // for Indexed: indices become keys
+toIndexedSeq(): Seq.Indexed<V>    // discards keys
+toSetSeq(): Seq.Set<V>            // discards keys
+```
+
+These are equivalent to passing the collection to the corresponding constructor (`List(coll)`, `Map(coll)`, ...) but read better in chains and have one important difference: `List(map)` produces a list of `[key, value]` entry tuples, while `map.toList()` produces a list of values only.
+
+## Gotchas
+
+- `fromJS` does NOT convert `Date`, JS `Map`/`Set`, `RegExp`, typed arrays, or custom class instances — they pass through. Use a `reviver` if you need to convert them.
+- `fromJS` only treats objects with the default `Object.prototype` as plain — anything with a custom prototype is left alone. This is usually what you want, but means subclasses of `Object` won't be deepened.
+- `toJS` is recursive and allocates a fresh deep copy on every call. On large structures it is expensive — iterate Immutable values directly rather than calling `.toJS()` in render paths or hot loops.
+- `Map#toList()` discards keys (values-only). If you want pairs, use `map.entrySeq().toList()` or `map.toIndexedSeq()` over `entrySeq`.
+- `Map#toArray()` (and other Keyed `toArray()`) returns `[key, value]` tuples, not values — use `valueSeq().toArray()` for a flat values array.
+- Round-tripping `fromJS(value).toJS()` produces a structurally similar object but not necessarily identical: property iteration order may change, and any non-plain instances on the input round-trip as the same reference (since `fromJS` left them alone).
+- `JSON.stringify(immutable)` works without explicit conversion — `toJSON` is wired up on every collection. No need to call `.toJS()` first.
+- `toMap()` and `toSet()` throw at runtime if the values/keys are not hashable (e.g. mutable JS objects). `toOrderedMap`/`toOrderedSet` have the same constraint but preserve insertion order.
+
+## See also
+
+- `references/deep-updates.md` — `getIn`/`setIn`/`updateIn`/`mergeDeep` for working without converting back to JS.
+- `references/list.md`, `references/map.md`, `references/set.md` — per-type construction and method details.
+- `references/predicates.md` — `isImmutable`, `isKeyed`, `isIndexed` (used in `fromJS` revivers).