tutuca 0.9.40 → 0.9.41

package/dist/tutuca-cli.js

@@ -10378,24 +10378,53 @@ __export(exports_install_skill, {
   run: () => run,
   describe: () => describe
 });
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
-import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
-function findSkillDir() {
+import { parseArgs } from "node:util";
+function findSkillsRoot() {
   const here = dirname(fileURLToPath(import.meta.url));
   const candidates = [resolve(here, "..", "..", "..", "skill"), resolve(here, "..", "skill")];
   for (const c of candidates) {
-    if (existsSync(resolve(c, "SKILL.md")))
+    if (existsSync(resolve(c, "tutuca", "SKILL.md")))
       return c;
   }
   return null;
 }
-function targetDir(scope) {
-  if (scope === "user")
-    return resolve(homedir(), ".claude/skills/tutuca");
-  return resolve(process.cwd(), ".claude/skills/tutuca");
+function targetDir(scope, name) {
+  const base = scope === "user" ? homedir() : process.cwd();
+  return resolve(base, ".claude/skills", name);
+}
+function targetHasSkillFiles(dir) {
+  if (!existsSync(dir))
+    return false;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith(".md"))
+      return true;
+    if (entry.isDirectory() && targetHasSkillFiles(resolve(dir, entry.name)))
+      return true;
+  }
+  return false;
+}
+function installSkill(skill, root, scope, force) {
+  const src = resolve(root, skill.srcSubdir);
+  if (!existsSync(resolve(src, "SKILL.md"))) {
+    process.stderr.write(`tutuca: missing skill assets for ${skill.name} at ${src}
+`);
+    process.exit(1);
+  }
+  const target = targetDir(scope, skill.name);
+  if (targetHasSkillFiles(target) && !force) {
+    process.stderr.write(`tutuca: ${target} already contains skill files. Re-run with --force to overwrite.
+`);
+    process.exit(1);
+  }
+  mkdirSync(target, { recursive: true });
+  cpSync(src, target, { recursive: true });
+  const rel = scope === "project" ? `.claude/skills/${skill.name}` : target;
+  process.stdout.write(`installed ${skill.name} skill → ${rel}
+`);
 }
 async function run(argv) {
   const parsed = parseArgs({
@@ -10403,62 +10432,68 @@ async function run(argv) {
     options: {
       user: { type: "boolean", default: false },
       project: { type: "boolean", default: false },
+      "margaui-skill": { type: "boolean", default: false },
+      "immutable-skill": { type: "boolean", default: false },
+      all: { type: "boolean", default: false },
       force: { type: "boolean", short: "f", default: false },
       help: { type: "boolean", short: "h", default: false }
     },
     allowPositionals: false
   });
   if (parsed.values.help) {
-    process.stdout.write(`tutuca install-skill [--user | --project] [--force]
+    process.stdout.write(`tutuca install-skill [--user | --project] [--margaui-skill | --immutable-skill | --all] [--force]
+` + `
+` + `  Installs Claude Code skill assets into .claude/skills/<name>/.
+` + `  Defaults to --project (cwd); --user installs at ~/.claude/skills/.
+` + `
+` + `  Selection:
+` + `    (default)         install the tutuca skill
+` + `    --margaui-skill   install the margaui skill instead
+` + `    --immutable-skill install the immutable-js skill instead
+` + `    --all             install every bundled skill (tutuca + margaui + immutable-js)
 ` + `
-` + `  Copies SKILL.md + core.md + cli.md + advanced.md into
-` + `  .claude/skills/tutuca/. Defaults to --project (cwd).
-` + `  --user installs at ~/.claude/skills/tutuca/.
 ` + `  --force overwrites existing files.
 `);
     return;
   }
   if (parsed.values.user && parsed.values.project) {
     process.stderr.write(`tutuca: --user and --project are mutually exclusive
+`);
+    process.exit(1);
+  }
+  const selectionFlags = ["margaui-skill", "immutable-skill", "all"].filter((k) => parsed.values[k]);
+  if (selectionFlags.length > 1) {
+    process.stderr.write(`tutuca: ${selectionFlags.map((f) => `--${f}`).join(", ")} are mutually exclusive
 `);
     process.exit(1);
   }
   const scope = parsed.values.user ? "user" : "project";
-  const target = targetDir(scope);
-  const src = findSkillDir();
-  if (!src) {
+  const root = findSkillsRoot();
+  if (!root) {
     process.stderr.write(`tutuca: skill assets not found alongside this CLI.
 ` + "If you're running from a checkout, run `bun scripts/build-skill.js` first.\n");
     process.exit(1);
   }
-  if (existsSync(target) && !parsed.values.force) {
-    const existing = readdirSync(target).filter((n) => SKILL_FILES.includes(n));
-    if (existing.length > 0) {
-      process.stderr.write(`tutuca: ${target} already contains skill files. Re-run with --force to overwrite.
-`);
-      process.exit(1);
-    }
+  let selected;
+  if (parsed.values.all) {
+    selected = SKILLS;
+  } else {
+    const selFlag = SKILLS.find((s) => s.flag && parsed.values[s.flag]);
+    selected = selFlag ? [selFlag] : SKILLS.filter((s) => s.name === "tutuca");
   }
-  mkdirSync(target, { recursive: true });
-  for (const name of SKILL_FILES) {
-    const from = resolve(src, name);
-    if (!existsSync(from)) {
-      process.stderr.write(`tutuca: missing skill asset: ${from}
-`);
-      process.exit(1);
-    }
-    const buf = readFileSync(from);
-    writeFileSync(resolve(target, name), buf);
+  for (const skill of selected) {
+    installSkill(skill, root, scope, parsed.values.force);
   }
-  const rel = scope === "project" ? ".claude/skills/tutuca" : target;
-  process.stdout.write(`installed tutuca skill → ${rel}
-`);
   process.stdout.write(`Open a Claude Code session in this directory to use it.
 `);
 }
-var describe = "Install the tutuca Claude Code skill into .claude/skills/tutuca/.", SKILL_FILES;
+var describe = "Install Claude Code skills (tutuca, margaui, immutable-js) into .claude/skills/.", SKILLS;
 var init_install_skill = __esm(() => {
-  SKILL_FILES = ["SKILL.md", "core.md", "cli.md", "advanced.md"];
+  SKILLS = [
+    { name: "tutuca", srcSubdir: "tutuca", flag: null },
+    { name: "margaui", srcSubdir: "margaui", flag: "margaui-skill" },
+    { name: "immutable-js", srcSubdir: "immutable-js", flag: "immutable-skill" }
+  ];
 });
 
 // tools/tutuca.js
@@ -10670,7 +10705,7 @@ async function loadAndNormalize(modulePath) {
 }
 
 // tools/cli/output.js
-import { writeFileSync as writeFileSync2 } from "node:fs";
+import { writeFileSync } from "node:fs";
 
 // tools/format/cli.js
 var exports_cli = {};
@@ -11191,7 +11226,7 @@ async function formatResult(formatName, result, options = {}) {
 async function emit(result, { format: format5, pretty, output }) {
   const text = await formatResult(format5, result, { pretty });
   if (output) {
-    writeFileSync2(output, text);
+    writeFileSync(output, text);
   } else {
     process.stdout.write(text);
     if (!text.endsWith(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.40",
+  "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.