feat: add consolidated loro skill (#923)

Author: zxch3n

skills/loro/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: loro
+description: "Comprehensive guide for using Loro across document modeling, synchronization, versioning, rich text editors, app-state mirroring, performance tradeoffs, and wasm bindings. Use when Codex needs to work with `loro-crdt`, `loro`, `loro-prosemirror`, `loro-mirror`, or `crates/loro-wasm` for: (1) Choosing CRDT container types and document structure, (2) Designing sync, persistence, checkout, or history workflows, (3) Integrating rich-text editors and stable selections, (4) Mirroring app state with schemas and React, (5) Reasoning about versions, events, import status, or Inspector output, or (6) Maintaining the WASM binding layer."
+---
+
+# Loro
+
+Use this skill as the single entry point for all Loro work. Load one primary chapter first. Load a second chapter only when the task clearly crosses domains.
+
+## Select A Chapter
+
+- Read [references/topic-map.md](references/topic-map.md) if the task is broad and you need to route it.
+- Read [references/fit-and-architecture.md](references/fit-and-architecture.md) for CRDT fit, local-first framing, setup, and high-level architecture.
+- Read [references/containers-and-encoding.md](references/containers-and-encoding.md) for container choice, composition, encoding, persistence, shallow snapshots, and redaction.
+- Read [references/sync-versioning-and-events.md](references/sync-versioning-and-events.md) for sync flows, frontiers, version vectors, checkout, import status, timestamps, event timing, and Inspector.
+- Read [references/richtext-and-editors.md](references/richtext-and-editors.md) for `LoroText`, cursors, `applyDelta`, `updateByLine`, `loro-prosemirror`, Tiptap, and CodeMirror.
+- Read [references/mirror-and-react.md](references/mirror-and-react.md) for `loro-mirror`, `$cid`, `idSelector`, validation, selectors, and React integration.
+- Read [references/wasm-maintenance.md](references/wasm-maintenance.md) for `crates/loro-wasm`, `#[wasm_bindgen]`, pending-event flushing, wrapper decoration, and tests.
+- Read [references/performance-and-research.md](references/performance-and-research.md) for benchmarks, Eg-Walker tradeoffs, movable-tree context, rich-text design context, and project history.
+
+## Route Common Tasks
+
+- “Build a collaborative document model / choose data types / persist history”
+  - Start with `containers-and-encoding.md`
+  - Add `sync-versioning-and-events.md` if version/history behavior matters
+- “Debug checkout / detached mode / missing imports / event timing”
+  - Start with `sync-versioning-and-events.md`
+- “Integrate ProseMirror, Tiptap, CodeMirror, or custom rich text”
+  - Start with `richtext-and-editors.md`
+  - Add `sync-versioning-and-events.md` if undo/version/event behavior matters
+- “Model app state with loro-mirror or loro-mirror-react”
+  - Start with `mirror-and-react.md`
+  - Add `containers-and-encoding.md` if schema semantics depend on container choice
+- “Change wasm bindings or debug pending event flushing”
+  - Start with `wasm-maintenance.md`
+- “Decide whether Loro is even the right tool / explain tradeoffs”
+  - Start with `fit-and-architecture.md`
+  - Add `performance-and-research.md` if benchmark or research context matters
+
+## Execute The Task
+
+1. Classify the task before reading everything.
+2. Load one primary chapter.
+3. Load at most one secondary chapter for cross-domain work.
+4. Keep solutions grounded in Loro semantics:
+   - choose data types by merge behavior,
+   - distinguish state version from history version,
+   - keep ephemeral state out of persisted CRDT data,
+   - respect the binding/runtime invariants in `crates/loro-wasm`.
+
+## Keep Guardrails
+
+- Do not assume CRDTs are the right fit for hard invariants, exclusivity, or authorization-at-write-time problems.
+- Do not model editable text as plain strings when user intent requires merged edits.
+- Do not reuse peer IDs across concurrent sessions.
+- Do not confuse detached documents with detached containers.
+- Do not change wasm-exposed mutators without checking pending-event flushing behavior.

skills/loro/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Loro"
+  short_description: "Complete Loro guide for modeling, sync, editors, and wasm"
+  default_prompt: "Use $loro to solve a Loro modeling, sync, editor, mirror, versioning, or wasm-maintenance task."

skills/loro/references/containers-and-encoding.md

@@ -0,0 +1,83 @@
+# Containers And Encoding
+
+## Container Choice
+
+- `LoroMap`: LWW key-value storage. Good for object-like state, coordinates, metadata, URLs, and fields where overwriting is preferable to merging.
+- `LoroList`: ordered sequence with insert/delete semantics.
+- `LoroMovableList`: ordered sequence with native move and set semantics. Prefer for drag-and-drop or reorder-heavy UIs.
+- `LoroTree`: hierarchical moves plus node-local data maps. Prefer for outlines, layers, nested blocks, or parent-child structures.
+- `LoroCounter`: additive numeric CRDT. Use when concurrent increments/decrements must accumulate.
+- `LoroText`: collaborative text. Use `updateByLine(...)` when line-oriented reconciliation is preferable to raw whole-string replacement.
+
+## Behavioral Notes
+
+- `LoroMap` compares concurrent writes by logical time and retains the winning value.
+- Setting a map entry to the same value is a no-op, so it does not create history.
+- `LoroList` and `LoroMovableList` both support stable cursors; use them when positions must survive concurrent edits.
+
+## Choice Pitfalls
+
+- Do not store editable prose as a plain string in a map unless LWW semantics are desired.
+- Do not model coordinates as `[x, y]` in a list. Concurrent delete+insert can create invalid arrays. Use a map.
+- Do not model arbitrary graphs directly. Loro documents compose as trees, not DAGs with shared children.
+
+## Container States And Composition
+
+- Detached containers come from constructors like `new LoroMap()`.
+- Attached containers belong to a document and have stable `ContainerID`s.
+- Adding a detached container to a document returns an attached version; the original object remains detached.
+- Root containers come from `doc.getMap(...)`, `doc.getText(...)`, `doc.getList(...)`, `doc.getTree(...)`, and so on.
+- Use `setContainer(...)` and `insertContainer(...)` for nesting, not plain `set(...)` or `insert(...)`.
+
+## Container ID And Overwrite Hazards
+
+- Root container IDs derive from root name plus type.
+- Child container IDs derive from the operation that created them.
+- Avoid concurrent creation of different child containers under the same map key. Container IDs differ, so one branch can appear overwritten.
+
+## Tree Specifics
+
+- `LoroTree` gives each node an associated `Map` container via `node.data`.
+- Fractional indices order siblings. Use them when child ordering matters.
+- When many peers insert at the same sibling position, peer ID acts as a tiebreaker for equal fractional indices.
+- Fractional index jitter reduces collisions at some encoding-size cost.
+- `getNodes(...)` and node JSON views are useful when a flat inspection of the forest is easier than recursive traversal.
+
+## List Vs Movable List
+
+- Use `LoroList` when delete+insert is acceptable and native move identity is unnecessary.
+- Use `LoroMovableList` for kanban columns, cards, playlist reordering, or any UX where “move this item” is semantically distinct from delete+insert.
+
+## Counter
+
+- `Counter` aggregates applied values from all peers.
+- It is the right choice for additive metrics, not for values with hard invariants.
+
+## Export Modes
+
+- `update`: sync delta payloads.
+- `updates-in-range`: bounded history export.
+- `snapshot`: full state checkpoint.
+- `shallow-snapshot`: current state plus truncated history.
+
+## Import Choices
+
+- `import(...)`: one payload at a time.
+- `importBatch(...)`: preferred for multiple updates or mixed snapshot/update payloads because diffing and event emission are coalesced.
+- Imports can succeed partially when dependencies are missing. Pending ranges mean the document knows about those operations but cannot apply them yet.
+
+## Persistence Pattern
+
+1. Periodically save a snapshot.
+2. Frequently persist updates, often after each local edit or on a debounce.
+3. On load, import the snapshot and outstanding updates.
+4. Recompact by exporting a fresh snapshot and deleting replayed updates.
+
+## Shallow Snapshots And Redaction
+
+- Use shallow snapshots when old history can be archived or discarded.
+- They are often much smaller than full snapshots.
+- Peers can only sync if they have versions after the shallow start point.
+- Archive full history before trimming if old history may still matter.
+- Redaction replaces sensitive payloads while preserving enough structure for future synchronization.
+- If old peers still hold unsanitized history, sensitive data still exists there.

skills/loro/references/fit-and-architecture.md

@@ -0,0 +1,48 @@
+# Fit And Architecture
+
+## When Loro Fits
+
+- Collaborative text and structured documents.
+- Offline-first applications that later synchronize.
+- Multi-device sync where eventual consistency is acceptable.
+- Apps that benefit from complete history, time travel, or version checkpoints.
+
+## When Loro Does Not Fit By Itself
+
+- Financial or accounting invariants.
+- Exclusive ownership or booking/locking semantics.
+- Authorization decisions that must be enforced at write time.
+- Arbitrary graph-shaped or non-JSON-like data without an adaptation layer.
+
+## Conceptual Model
+
+- Loro is a CRDT framework for local-first apps.
+- It trades strict coordination for strong eventual consistency.
+- Under the hood it mixes Fugue-style correctness with Eg-Walker-inspired replay and simple local indexing.
+
+## Document Shape Constraints
+
+- Loro documents are JSON-like.
+- Map keys are strings.
+- The composed document structure is tree-shaped, not a general graph with shared children.
+
+## Entry Points
+
+- JS/TS: `loro-crdt`
+- Rust: `loro`
+- Swift: `loro-swift`
+- Python: `loro-py`
+- Ecosystem integrations include editor bindings, state-mirroring layers, and Inspector.
+
+## Setup Notes
+
+- In JS frontends, install `loro-crdt`.
+- In Vite-based apps, WASM support and top-level-await handling must be configured correctly.
+- Inspector is the quickest interactive tool for browsing state and history during development.
+
+## Read Order Inside This Skill
+
+1. Start here for fit and high-level tradeoffs.
+2. Switch to `containers-and-encoding.md` for concrete data types and storage choices.
+3. Switch to `sync-versioning-and-events.md` for history, events, and sync state.
+4. Switch to `richtext-and-editors.md` or `mirror-and-react.md` for integrations.

skills/loro/references/mirror-and-react.md

@@ -0,0 +1,64 @@
+# Mirror And React
+
+## Mirror Intent
+
+- `loro-mirror` keeps an immutable app-state view in sync with a `LoroDoc`.
+- Local `setState(...)` edits become granular CRDT operations.
+- Remote CRDT events patch the mirrored app state back in.
+- The common mental model is still “immutable app state plus typed actions”, not direct mutation of raw CRDT containers everywhere.
+
+## Root Schema
+
+- Build the root with `schema({...})`.
+- Keep root fields as Loro containers: `LoroMap`, `LoroList`, `LoroMovableList`, `LoroText`.
+- Put primitives inside those containers, not at the root.
+
+## Field Types
+
+- `schema.String`, `schema.Number`, `schema.Boolean`: concrete primitive fields.
+- `schema.Any`: dynamic JSON-like payload when the shape is truly unknown.
+- `schema.Ignore`: local-only or derived fields that should not sync to Loro.
+
+## Maps, Lists, And `$cid`
+
+- `schema.LoroMap({...})`: nested object container.
+- `schema.LoroMap(...).catchall(valueSchema)`: add dynamic keys while preserving known keys.
+- `schema.LoroMapRecord(valueSchema)`: homogeneous record-like map.
+- Every mirrored `LoroMap` includes a read-only `$cid`.
+- `$cid` matches the underlying Loro container ID.
+- Use `$cid` as a stable key or default `idSelector`, especially for list items.
+- Never try to persist or mutate `$cid` from app code.
+- Do not invent a `withCid`-style option; mirrored map values already receive `$cid` automatically.
+
+## Lists
+
+- `LoroList(itemSchema, idSelector?)`: ordered collection. Add `idSelector` for stable add/remove/update/move diffs.
+- `LoroMovableList(itemSchema, idSelector)`: native move semantics, ideal for drag-and-drop.
+- If a list item is a map, `(item) => item.$cid` is often the right `idSelector`.
+
+## Defaults And Validation
+
+- Explicit `defaultValue` wins.
+- Required fields without explicit defaults fall back to built-in defaults.
+- `validateUpdates` is enabled by default in `Mirror`. Keep it on unless a measured hot path proves otherwise.
+- Use `validateSchema(...)` when you need an explicit validation pass during migration or debugging.
+
+## React Patterns
+
+- Create a stable `LoroDoc` instance.
+- Create helpers through `createLoroContext(schema)` or `useLoroStore(...)`.
+- Wrap the tree in `LoroProvider` when using the context pattern.
+- Use the narrowest hook that solves the task:
+  - `useLoroState` for the full mirrored state
+  - `useLoroSelector` for focused subscriptions
+  - `useLoroAction` for write paths
+- Keep the provider `doc` stable across renders.
+- Prefer `useLoroSelector` over pulling the full state into every component.
+- Use mirrored list item `$cid` values as React keys.
+
+## Practical Mental Model
+
+- Subscribe to order at collection boundaries.
+- Subscribe to content at item boundaries.
+- Pass `$cid`s downward and reselect locally instead of passing large mirrored objects through the whole tree.
+- Keep view-local state outside the mirror unless collaborators must share it.

skills/loro/references/performance-and-research.md

@@ -0,0 +1,35 @@
+# Performance And Research
+
+## Performance Interpretation
+
+- Treat benchmarks as tradeoff indicators, not universal rankings.
+- Compare:
+  - encode/decode cost
+  - parse time
+  - document/update size
+  - memory footprint
+  - conflict-heavy vs low-conflict workloads
+
+## Main Performance Topics
+
+- Benchmark framing and methodology.
+- Encoded document size comparisons and shallow snapshot savings.
+- Native Rust benchmark context.
+
+## Main Concept Topic
+
+- Event-graph replay explains why Loro can keep local operations simple while still merging remote history efficiently.
+
+## Stored Knowledge Threads
+
+- Stable encoding and import/export speedups.
+- Movable tree algorithm, unsafe moves, and fractional index tradeoffs.
+- Rich text design, style anchors, overlap, and expansion behavior.
+- Peritext/Fugue background for rich text intent preservation.
+- Mirror motivation, complexity model, and state-to-CRDT mapping.
+- Local-first product vision and project history.
+
+## Practical Rule
+
+- Reach for these topics when the user asks “why does Loro work this way?” or “what tradeoff is Loro making?”.
+- Do not dump benchmark tables into product recommendations without first matching them to the workload.

skills/loro/references/richtext-and-editors.md

@@ -0,0 +1,58 @@
+# Rich Text And Editors
+
+## Rich Text Rules
+
+- Use `LoroText` for collaboratively edited text.
+- Keep rich text style config in sync across peers:
+  - `after`
+  - `before`
+  - `none`
+  - `both`
+- If two peers use different `configTextStyle(...)`, they can interpret the same boundary insert differently.
+
+## Text API Notes
+
+- `update(...)` rewrites based on a target text snapshot.
+- `updateByLine(...)` is useful when line-oriented reconciliation is more appropriate than raw whole-string replacement.
+- `toDelta()` preserves marks and annotations.
+- `toJSON()` / `toString()` return plain text only.
+
+## `applyDelta(...)` Caveat
+
+- `applyDelta(...)` is ideal for editor bindings because it matches event diffs.
+- Delta inserts must include the full attribute set of the inserted range.
+- If CRDT inheritance would add marks but the delta omits them, `applyDelta(...)` removes those attributes.
+- Out-of-range formatting can cause Loro to materialize newlines to satisfy editor assumptions.
+
+## Stable Selections
+
+- Use `text.getCursor(...)` to create stable positions.
+- Use two cursors for selections: anchor and head.
+- Resolve live offsets with `doc.getCursorPos(...)`.
+- Persist updated cursors returned from resolution to reduce replay cost.
+- WASM text offsets are UTF-16 indices.
+
+## ProseMirror And Tiptap
+
+- Start with `loro-prosemirror` for ProseMirror and Tiptap.
+- It already covers document sync, collaborative undo and redo, and cursor presence.
+- The current baseline is `CursorEphemeralStore` plus `LoroEphemeralCursorPlugin`.
+- Give each editor instance its own `containerId` when several editors share one `LoroDoc`.
+- Reuse the same container only if several views intentionally co-edit the exact same content.
+
+## CodeMirror
+
+- Use the official CodeMirror integration when the editor is CM6-based.
+- Keep awareness/presence, undo, and document sync at the Loro layer rather than inventing a separate editor-level protocol.
+
+## Rich Text Internals
+
+- Loro rich text uses style anchors to represent mark boundaries.
+- Overlap and expansion behavior are first-class concerns.
+- Overlappable styles are often best modeled by unique keys with a shared prefix pattern such as `comment:alice` and `comment:bob`.
+
+## Guardrails
+
+- Do not model editable prose as `string` in a `LoroMap`.
+- Do not store collaborative selections as plain indices.
+- Do not mix old and new ProseMirror cursor APIs accidentally; inspect the package version and current codebase first.