Snapshot of the Umamo working tree as it is
Uploaded as-is from /home/litruv/dev/vtsmaker/umamo on 2026-11-03. 1347 files. Includes the uncommitted work in progress in :edit, :runtime, and :ui, and the untracked files under module/edit/src/jvmAndroidMain/. History is not carried over. The source repo is https://github.com/umamoorg/umamo.
This commit is contained in:
@@ -0,0 +1,340 @@
|
||||
# CLAUDE.md — Umamo
|
||||
|
||||
## What This Is?
|
||||
|
||||
Umamo is an open-source cross-platform rigging editor for 2D puppet animation, with first class pen and touch support, built as a drop-in replacement for the Live2D Cubism Editor.
|
||||
|
||||
- **Language:** Kotlin, Kotlin Multiplatform (shared core across desktop + Android).
|
||||
- **Package root:** `org.umamo` (reverse-DNS of the `umamo.org` domain). Shared library modules are flat — `org.umamo.format`, `org.umamo.runtime`, `org.umamo.interop`, `org.umamo.render`, `org.umamo.ui`, `org.umamo.reimport`. App code carries product + platform — `org.umamo.editor.desktop`, `org.umamo.editor.android` (a future viewer takes `org.umamo.viewer.*`); the headless diagnostic tool is `org.umamo.cli` (JVM-only). The editor's Android `applicationId` is `org.umamo.editor`, keeping bare `org.umamo` a clean umbrella.
|
||||
- **Platforms:** Windows, macOS, Linux (keyboard/mouse/pen) **and Android tablets** (pen/touch — e.g. Wacom MovinkPad). Rigging is a first-class workflow on **all** of these, not desktop-only.
|
||||
- **Headline workflow:** draw in Clip Studio Paint (or Photoshop), save/export, switch to Umamo, and the rig **refreshes against the updated art** without losing rigging work.
|
||||
- **Compatibility is the product:** read and write the existing Cubism source format so riggers can adopt incrementally and interoperate with the official editor.
|
||||
|
||||
## The Thesis (do not let this drift)
|
||||
|
||||
v1's win condition is **a CMO3-native rigging editor that interoperates with the official Cubism Editor**:
|
||||
|
||||
1. **Read and write `.cmo3`** (editor source) → a rigger can bounce the same project between Umamo and the official Cubism Editor without burning bridges. This bidirectional interop is the primary adoption wedge.
|
||||
2. **Ingest source art** (PSD, CLIP, KRA with robust layer ID matching — see Re-import) and keep the rig live against art changes.
|
||||
3. **GPU-accelerated, trustworthy preview** — the viewport deformation must match what a rigger would see in Cubism so they can trust what they're authoring.
|
||||
|
||||
Runtime concerns (MOC3 emit, SDK/Core replacement) are a work in progress — see Format Support. If a proposed change trades away source-format compatibility or the refresh workflow for internal elegance, it is wrong by definition. Raise it, don't silently take it.
|
||||
|
||||
## Format Support (priority order)
|
||||
|
||||
- **UMA — read AND write, and the app's Open/Save.** Native Umamo format: a ZIP of per-domain JSON entries (the puppet graph with its bulk arrays in a buffer entry, the atlas with its pixel entries, the linked source art) under a manifest whose compatibility rules open a newer file read-only or carry what this reader cannot interpret byte for byte. `object Uma : FormatCodec<UmaModel>` lives in `:format` `uma/`; `UmaDocumentBridge` in `:interop` `uma/` maps a document to and from `PuppetModel`; `UmaDocument` (`:ui` jvmAndroidMain `document/`) is what File > Open loads and `writeUmaDocument` is what Save writes, laid over the file as opened so unknown keys and held tiles survive; the save target lives in a `DocumentFile` beside the session, not on the document. Editor state (`editor/state.json`, never an input to the model) rides each save as a merge patch: per-area view state and cameras through `AreaViewStates` (`:ui` `workspace/`), keyed by the layout's area ids, and the session's pose, selection, mode, cursors, and tool settings through `SessionViewState` (`:edit`), laid into the session's first snapshot so nothing restored is an undo step. Spec: `docs/format/UMA.md`; decisions and roadmap: `docs/plan/uma-format.md`.
|
||||
- **CMO3 — read AND write, with edit-to-CMO3 lowering.** A CMO3 is the native format for the Cubism editor, and an interop boundary for Umamo: the UI offers it as Import/Export (Open/Save is reserved for UMA). `Cmo3.write` round-trips an unedited file's **decompressed `main.xml` byte-for-byte** — not the whole file; see the Fidelity contract. Export is a **state-based reconcile**: `Cmo3Export.apply` (`:interop` jvmAndroidMain) re-imports the retained graph as a baseline, diffs the session's model against it, and patches only what changed — flat fields, base geometry/UVs, the keyform grid web (re-bundled via `refinedToUnion`), blend shapes, and structural create/delete for every entity category. A MOC3-origin document (no retained graph) exports through **fresh-graph synthesis**: `Cmo3Conversion.freshCmo3` builds a blank BareMinimum-shaped skeleton plus a per-page image chain and runs the SAME reconcile against the empty baseline. Anything unrepresentable surfaces as an `ExportNotice`, never a silent drop. See `docs/format/CMO3.md` § Export.
|
||||
- **PSD — read.** Layered-art ingestion. Re-import join key is the lyid layer id when present (Photoshop-written, stable across rename/reorder), else layer name/path + order (lossy; some exporters omit lyid, so CLIP/KRA with always-present stable ids stay more robust). See `docs/format/PSD.md`.
|
||||
- **CLIP (Clip Studio Paint) — read.** Layered-art ingestion, proprietary (SQLite-based container). Implemented: layer tree + raster decode, registered in `FormatRegistry` with corpus-backed tests. See `docs/format/CLIP.md`.
|
||||
- **KRA (Krita) — read.** Layered-art ingestion, open source format. See `docs/format/KRA.md`.
|
||||
- **MOC3 — read AND write.** Serialized C structs (memory-cast, so byte-exact layout). See `docs/format/MOC3.md`.
|
||||
- **JSON family**: `model3` (manifest), `physics3`, `cdi3`, `pose3`, `exp3`, `motion3`, `userdata3`, texture atlas.
|
||||
|
||||
PSD/CLIP/KRA (and flat rasters, wrapped as one layer) come in through **File > Import > Artwork…** (or the Sources space's button — one command, `file.importArtwork`), which ADDS the file's layers to the OPEN document as one undo step, Blender-style, rather than replacing it: the editor always has a document, starting with the empty one it opens into. `SourceArtImport` (`:interop` `org.umamo.interop.art`) is the source-art → `PuppetModel` bridge — one drawable per raster layer over a quad birth mesh, one part per folder, the source-layer binding persisted on the tile (`AtlasTile.source`) with the file and its layer inventory on `PuppetModel.sources`. A rig's FIRST artwork also gives it the file's canvas, the world origin at that canvas's center, and the parameters of the `import.parameterTemplate` setting (Humanoid by default); a later file is placed on that canvas by the import's Align anchor and Offset rows on the operation strip (its record keeps the offset as `ArtSource.offsetX/Z`, x right and z up like the viewport, and every later read of the file is placed by it before the model sees the art), packed into the gaps with existing art held fixed, and redefines neither. A CMO3 export of such a document runs the fresh-graph synthesis with the document's own rasters, so the CMO3 carries the real layers and folders and reopens keyed by lyid (Phase H1); a CMO3-origin document's reloaded and added art is written into its retained graph the same way (H2); a MOC3-origin export still slices its layers out of the pages. See `docs/plan/art-sourcing-pipeline.md` Phase E.
|
||||
|
||||
**Unified codec contract.** Every binary container format presents the same face to the rest of the project: a `FormatCodec<TModel>` in `:format` (`kind`/`matches`/`read(ByteArray)`/`write(TModel)`, tied to `FileKind`), with `FormatRegistry` doing detect-by-magic and resolve-by-kind. CMO3 (`object Cmo3`, in `jvmAndroidMain` — JDOM/reflection are JVM-only) and MOC3 (`object Moc3`, `commonMain`) both implement it; the in-memory model type differs per format and shares no supertype (hence the generic). The **JSON sidecars are `String`-shaped, not bytes**, so they deliberately sit *outside* the codec contract as plain helpers on `Moc3` (`readModel3`/`writeModel3`/…). Add a format by implementing the interface and registering it — never by growing a bespoke read/write facade.
|
||||
|
||||
## Architecture
|
||||
|
||||
### UI: Compose Multiplatform + Embedded GPU Viewport
|
||||
|
||||
The editor UI is **Compose Multiplatform** — Jetpack Compose on Android, Compose Desktop (Skiko) on Win/Mac/Linux. One UI codebase, idiomatic pen/touch/gesture input. **Not ImGui** (desktop/mouse-only, no Android pen story). **Not Swing/JavaFX** as UI.
|
||||
|
||||
The puppet canvas is a **GPU surface composited into Compose**:
|
||||
- Desktop (shipped): LWJGL renders offscreen through a hidden GLFW context; the frame is copied into a Compose `Image` — there is no Swing/AWT interop in this path. See `OffscreenPuppetService` / `:desktop` in the module graph.
|
||||
- Android (not yet implemented): the target is a GLES surface composited the same way; today `:android` mounts the shared shell with a null viewport factory, so viewport areas render placeholders. See `:android` in the module graph.
|
||||
|
||||
**Pen input (design target, not yet implemented):** no stylus/pressure/tilt code exists anywhere in the repo yet. The intended split is Android stylus (`MotionEvent` pressure/tilt/hover) as the easier target, desktop JVM pen as the harder one (plan for JPen or Wintab/Windows Ink).
|
||||
|
||||
### Panels & docking
|
||||
|
||||
**One interface, desktop and tablet.** The same edge-docked UI runs everywhere, modeled on Krita and Clip Studio Paint's desktop mode — both run their full desktop UI on Android tablets, and that is sufficient. There is **no separate slim tablet UI to maintain.** The tablet gets a touch-tuned _skin_ of the same interface, not a second front-end: larger hit targets, more panels collapsed-to-rail by default, the pen radial menu carrying tool switching, and the menubar folded into an overflow rather than a top strip.
|
||||
|
||||
**Blender-style area tree, not free-floating**:
|
||||
- The window content is a **recursive binary-split tree of areas**. Each area hosts exactly one **editor space** — the ten `SpaceKind`s are 2D viewport, UV editor, sources (the source-art linking table), outliner, parameters, keyform sheet, properties, tool details, history (undo stack, click an entry to jump to that state; deformers live in the outliner/parameters, not a separate space), and logs — and the space is **agnostic and switchable at runtime** via a dropdown in the area's top-left header — any area can become any space (turn the outliner into a tiny viewport if you like, exactly like Blender).
|
||||
- Areas split along any edge into nested areas and merge/close; **splitters are draggable** with a min-size clamp; a Blender-style **corner-drag gesture joins two adjacent areas** back into one.
|
||||
- A window holds **multiple named workspaces as tabs** (create/duplicate/rename/reorder/reset), each with its own area tree; a single workspace or the whole layout can be exported/imported as text.
|
||||
- Each area also has a **right-click context menu** mirroring its header actions plus "Change Editor Type."
|
||||
- **Free-floating / tear-off windows remain out of scope** — everything is tiled inside the window; this keeps the layout engine small.
|
||||
- An area's shape does not restrict which space it may host (no "tall panels left/right, wide panels top/bottom" rail constraint).
|
||||
|
||||
Concretely the shell is `org.umamo.ui.workspace`: a sealed `AreaNode` (split/leaf) tree per `Workspace`, rendered by a recursive Compose layout (`AreaTree`/`SplitContainer` + a draggable `Splitter`) — a tractable custom layout, not an IDE-grade free-float dock manager. Row drag-and-drop inside a space (the outliner, the parameters panel, the Sources table) is one shared kit in `org.umamo.ui.workspace.rowdrag`: the drag controller and hit-test, the Escape cancel seam, the long-press pickup, the cursor chip, and the drop-target ring; a space adds only its payload type and its drop rule. The 2D GL viewport stays platform code in the app, injected into a leaf via a `ViewportHost` seam (per-area surface kept alive across tree mutations with `movableContentOf`).
|
||||
|
||||
**Defaults carry the opinion.** Each workspace ships a curated default area tree (Modelling = parameters, a viewport over the keyform sheet, and outliner over properties; Texture = stacked UV editors, a viewport, and a sources/outliner/properties column); user rearrangement is the customization layer on top, persisted to settings `interface.layout`; "reset layout" reseeds the defaults. This is how the tool stays focused while configurable — the workspaces own the good arrangements, so configurability is the escape hatch, not the primary interaction.
|
||||
|
||||
### The tool surface is small and bounded
|
||||
|
||||
2D rigging is not a tool-complex process. So the panel inventory is knowable up front:
|
||||
|
||||
- **Canvas / viewport** — the GPU work surface.
|
||||
- **Parts** — drawable + deformer hierarchy (with a Project view: source-image → model-image binding).
|
||||
- **Parameters** — the rigging cockpit (sliders, multi-key 2D pad, keyform binding).
|
||||
- **Properties** — a tabbed mega-panel over the document and the selected item: Document (canvas, runtime targets), Object (transform, relations), Data (type-specific — mesh/texture/blend, deformer, part), with a header search that filters to matching rows. Tabs come from an extensible `PropertyTabRegistry`, so a section is registered, never wired into a render switch.
|
||||
- **Keyform sheet** — per-(item, channel) tracks over the parameter targeted in the Parameters panel. Its track widgets live in `org.umamo.ui.tracks` and are **domain-agnostic on purpose** (`TrackAxis` is the only place a domain appears), so the later time-based animation dope sheet reuses them; nothing about parameters, keyform grids, or `PuppetModel` may appear in that package. The `dopesheet` serialization key is deliberately left free for that editor.
|
||||
- **Tool details** — context for the active tool.
|
||||
- **History** — undo-history stack; click an entry to jump to that state.
|
||||
- **Sources** — the source-art linking table: artwork file → layer (inventory as of the last read) → tile → drawables, each row tinted by status (present/missing file, bound/bound-by-name/unbound, placed/unplaced) with a filter. Dragging a layer row onto a tile row (or the reverse) rebinds it; Import Artwork…, Reload, Replace Artwork…, and Match Automatically each land as one undo step, with a Match Threshold row on the operation strip where matching applies. An unbound layer's chip can ignore it (a reload then never re-mints it). See § Re-import below for the reconcile/matcher mechanics.
|
||||
- **Logs** — the diagnostic console.
|
||||
|
||||
Animation later adds wide, bottom-docked panels (timeline, keyframe/graph editors). Because the set is small and known, the dock shell can be defined early without churn — but get the core rigging working in the default layout first; freeform rearrangement is a fast follow, not a prerequisite.
|
||||
|
||||
### Commands, key bindings & input
|
||||
|
||||
A central **action registry** is the spine of input: every operation is a named command (`mesh.subdivide`, `param.addKeyform`, `view.fit`, …). Menus, the toolbar, the pen radial menu, and keyboard shortcuts **all dispatch through it** — nothing hardcodes a handler. Design this in early; it's cheap up front and painful to retrofit after handlers are wired directly.
|
||||
|
||||
- **Editable, persisted keymaps** with presets — default, a **Cubism-like** preset (so migrants keep their muscle memory), and a **Blender-like** one (matches the editing model we're borrowing). Detect conflicts; scope bindings per mode/context where a key's meaning differs.
|
||||
- **Bindable inputs are not just the keyboard, in principle:** the design allows stylus barrel buttons, tablet express keys, and mouse buttons to bind to actions too, so a keyboardless tablet can still reach every command. Not yet wired — today only keyboard chords resolve through the keymap.
|
||||
- Store a logical **primary modifier** (→ Cmd on macOS, Ctrl elsewhere), not a literal "Ctrl"; bind by **key position**, not character, so shortcuts survive non-QWERTY layouts.
|
||||
- A searchable **command palette** falls out almost free from the registry — a strong discoverability / onboarding aid for rigging's harder abstractions.
|
||||
- **Pie/radial menus** (`PieMenuKind` — pivot mode, snap, merge-target, …) are a second dispatch mechanism alongside the palette, built for pen/touch reach rather than search.
|
||||
|
||||
Implemented (`:ui`'s `org.umamo.ui.action`): `Command`/`CommandHandler`/`CommandRegistry` (as `LocalCommands`), chords via `KeyChord`/`parseKeyChord` resolved through a `Keymap` (key position + a logical primary modifier). `org.umamo.ui.workspace.commands` holds every command table, one file per domain, each a builder returning `List<Command>` registered through `registerAll` (which returns the matching cleanup, so registration and unregistration can't drift apart). A `Command` also declares the spaces it belongs to (`spaces: CommandSpaces`, read off what its handler's routing really does, never narrower) and an optional short status-bar `hint`; both filter the palette and the status bar only — dispatch and the keymap never read them. A `Command(...)` built anywhere else is a bug — the table is the declaration, the handler just a lambda; that split is why the app's `file.*` tables stay in this commonMain package while the document loader behind them lives in `jvmAndroidMain` (`org.umamo.ui.app`'s controllers); `logs.export` and the `workspace.*` file commands need only a picker, so the settings-backed shell registers them.
|
||||
|
||||
`commands/CommandRouting.kt` is the one place a command resolves "which area does the pointer mean," backed by a single hovered-surface resolver (`Modifier.stampsHoveredSurface`, installed once by `AreaLeaf` so every space kind is covered automatically). There is no viewport-only fallback: a command needing a viewport that finds none does nothing rather than reaching back to one the pointer has left (Blender's hovered-area rule). A request that must execute in one specific area carries that area in its payload instead (`SnapRequest`, `SelectLinkedRequest`, `UvSnapRequest`), so each overlay collector gates on its own id.
|
||||
|
||||
`handleShellKey` is the live dispatch path (`KeyChord` → `Keymap.commandFor` → `registry.invoke`); `CommandPalette` lists `registry.all()`. New operations register a `Command` and bind a chord — never wire a handler into a widget. The keymap itself is editable and persisted via `KeymapPersistence` (`default`/`cubism`/`blender` presets plus per-command overrides, reactive), with a keybindings editor in Settings.
|
||||
|
||||
### Localization (EN/JA/KO)
|
||||
|
||||
The audience is heavily Japanese and the primary developer is bilingual — so **EN + JA are first-class from day one**, not retrofitted. Compose Multiplatform's resources system (`stringResource`, per-locale resources) is the mechanism.
|
||||
|
||||
- **Externalize every UI string** from the start; no hardcoded literals. Build the pipeline for *N* locales, not just two.
|
||||
- **Localize chrome and display names — never format-level identifiers.** Parameter IDs like `ParamAngleX` are part of the CMO3/Cubism data model and stay verbatim for interop; `cdi3.json` display names and the user's own part names are user data, not ours to translate. Two layers: Umamo's UI (we localize) vs the document's names/IDs (we don't).
|
||||
- **CJK gotchas to test deliberately:** Skiko font fallback must cover JA glyphs on desktop *and* Android (bundle a CJK-capable font). Don't assume EN string widths in the dock/panel layout.
|
||||
- RTL is out of scope for v1, but don't structurally preclude it.
|
||||
|
||||
### Settings, storage & the app shell
|
||||
|
||||
The **settings/storage foundation is built first** — it backs keymaps, layout, theme, and recent files, so nothing hardcodes config that has to be ripped out later. Two modules:
|
||||
|
||||
- **`:storage`** — per-OS config/data directories + file IO over **okio** (Kotlin's stdlib has no common `File`; `java.io.File` is JVM-only), and a `FilePicker` open/save-dialog contract backed by **FileKit** — one commonMain `FileKitFilePicker` over each OS's native dialog (Win32 `IFileDialog`, Cocoa, GTK/portal) plus Android SAF, replacing the old desktop-only AWT `FileDialog`. Because FileKit already spans platforms there is no per-platform picker impl: desktop is done, and Android needs only `FileKit.init(activity)` in its `Activity` (it owns the result registry) — no separate SAF implementation. The contract returns FileKit's `PlatformFile`, not an okio `Path`: Android SAF hands back a `content://` URI with no real filesystem path that a `Path` cannot model. Platform factories `desktopAppStorage` / `androidAppStorage` resolve the dirs.
|
||||
- **`:settings`** — a JSON tree of **bundled defaults ← user overrides** (← vendor extension defaults, later), addressed by **dotted keys** (`getString("interface.theme")`). No caller passes a default — `defaultSettings.json` (a Compose-MP resource in `:ui`, shared cross-platform) is the single baseline. Writes hit the *user* layer only, persist via `:storage`, and emit the changed key on a `changes: SharedFlow` (the reactive spine the UI / keymap / undo-History collect). Held as a dynamic `JsonObject`, not typed `@Serializable` classes (settings are open-ended + merged); typed per-domain views layer on later. Namespaces in use today: `interface.*` (theme, the undo-step cap pushed into `EditorSession.historyLimit`, the workspace area-tree layout, window geometry, viewport toolbar/sidebar visibility), `input.keybinding.*` (the keymap preset + overrides), `viewport.*` (zoom steps, selection/warning/pinned colors, grid, the `meshEdit.*` mesh-edit colors), `localization.locale`, and `import.*` (`parameterTemplate`, `alignment`, `watchMode`, `deleteArtIgnoresLayer`, `layerPositionsFromWorldAxes` — see § Re-import). See `defaultSettings.json` for the exact key list; `app.launchCount` and `input.pen.backend` are reserved there but genuinely unread/unwritten today.
|
||||
|
||||
Apps load settings at startup and provide the instance through a `LocalSettings` composition local — the desktop loads **synchronously** so the saved window state is ready before the (unconditional) window opens; `application {}` exits if it ever has zero windows, so an async settings gate would close it. The **app shell is shared in `:ui`** (`org.umamo.ui.app`, jvmAndroidMain - `EditorApp` is wiring only, over one controller per responsibility: save, open, export, artwork, the source watcher): the File / Edit / Workspace / Help menu bar, a Preferences window (`edit.preferences`, holds the keybindings editor and other settings sections), Help Credits/About, the `Document` layer (CMO3/MOC3 import and CMO3 export via FileKit — Open/Save is reserved for UMA — recent files, the dirty-replace confirm, the export report alert), live locale switching, live keymap reload on preset/rebind, and the per-document session wiring. `:desktop` owns the window (geometry persisted to settings, title dirty-marker, the LWJGL offscreen render service); `:android` owns the Activity and mounts the same shell with a null viewport factory until the GLES renderer lands — Android does have renderer groundwork (`GpuRenderer.android.kt`: GLES20/30 grid + axis shaders), just not a puppet-deformation renderer or the Compose-image bridge yet.
|
||||
|
||||
**Use the foundation, don't reinvent it:** new config (a keymap preset, a panel layout, a pen binding) is a settings key under its namespace via `Settings`; file open/save goes through `FilePicker`; app-data paths come from `AppStorage`.
|
||||
|
||||
### Deformation (the core math)
|
||||
|
||||
Parameter-driven morph blending, **not** skeletal: `p = base + Σ wᵢ·Δᵢ`, multilinear interpolation across an N-dimensional grid of keyforms. Warp deformers are FFD lattices; rotation deformers are a nesting pivot-transform hierarchy. Weights are computed CPU-side per frame (cheap; depend only on parameters); the per-vertex weighted delta-sum runs in a vertex shader. None of this maps onto any engine's built-in rig — it is ours.
|
||||
|
||||
### Mesh-editing interaction model
|
||||
|
||||
Mesh and keyform-deformation editing should feel like **sculpting, not CAD**, adopting Blender's UV-editor interactions.
|
||||
|
||||
- **Proportional editing — shipped.** Moving one vertex drags its neighbours within an adjustable radius, with six selectable **falloff curves** (smooth / sphere / root / sharp / linear / constant) plus a geodesic "connected only" mode that follows mesh edges instead of screen-space distance (`module/edit/.../ProportionalEditing.kt`).
|
||||
- **Brush radius for grab / smooth / relax — not yet implemented.** The only existing brush-radius tool today is circle-select, a selection brush, not a vertex-manipulation one; there are no grab/smooth/relax sculpt operators yet.
|
||||
- **Pen-pressure-driven brush radius / falloff strength — not yet implemented.** No pressure/tilt input is wired anywhere in the codebase yet (see the Pen input note above); this stays the target pen-first advantage over Cubism's click-drag-per-vertex model once it lands.
|
||||
|
||||
### Project format & source model
|
||||
|
||||
CMO3 does **not** store the original `.psd`. On import Cubism **decomposes** the PSD into an editable, equivalent representation: a `CLayeredImage` tree of `CLayerGroup`/`CLayer` nodes, each layer's pixels stored as a separate embedded PNG (`CImageResource` → `imageFileBuf*.png`), positionally mapped. PSD is still the privileged *source* throughout the Cubism pipeline (mesh and model-image derive from it). That privilege is incompatible with first-class **CLIP** and **Krita (.kra)** support, so:
|
||||
|
||||
- Umamo's **native project format is source-agnostic.** PSD, CLIP, and KRA are peer sources, each retaining its own **stable layer identity** (CLIP / Krita layer IDs; PSD's lyid layer id when present, else name + order).
|
||||
- **CMO3 is an interop boundary, not the native format.** A shim unwraps CMO3's decomposed layer images (the `CLayeredImage` tree + per-layer PNGs) on import and synthesizes that decomposed, PSD-derived shape on export, so CMO3 round-trip still works.
|
||||
- **Do not shim CLIP/Krita down to PSD on import.** That discards the stable layer IDs that make non-destructive re-import reliable — i.e. it throws away the exact reason CLIP support is worth having. The source-agnostic native model is what preserves them.
|
||||
|
||||
This refines the thesis: CMO3 read/write stays primary (Cubism interop), but it is a *conversion at the boundary* layered over a custom native format — not the format you work in. The container is specified in `docs/format/UMA.md`, and File > Open/Save read and write it — see Format Support.
|
||||
|
||||
### Re-import / source-art binding (the headline feature's hard problem)
|
||||
|
||||
"File refreshes" = **non-destructive re-import keyed on stable layer identity**. Each drawable is bound to a source layer by a stable key (CLIP/Krita layer ID, or PSD's lyid when present; else PSD name/path + heuristics). On a watched-file change, reconcile:
|
||||
- **Matched layer:** update its atlas region; preserve mesh/deformers/keyforms where topology still fits.
|
||||
- **Moved/resized art:** adjust extents/UVs if possible; otherwise flag for re-mesh.
|
||||
- **Added layer:** new unbound drawable.
|
||||
- **Removed/renamed layer:** **never silently delete rig work** — flag, fuzzy-match, and make reconciliation reviewable (a diff/merge step).
|
||||
|
||||
This is where Live2D's own reimport is lossy; doing it well is a competitive feature.
|
||||
|
||||
**Status: Phase F is complete** — the binding is persisted and editable, and the reconcile by key (F1), the watcher (F2), and the fuzzy matcher with its review states (F3) are all built. The identity is ONE representation: the reader's `LayerId.raw` is the key and the reader says how strong it is (`SourceLayer.idIsStable`); it persists on the tile as `AtlasTile.source: SourceLayerRef`, and the document lists its artwork files with their pixel-free layer inventories as `PuppetModel.sources: List<ArtSource>` (the baseline a reconcile diffs against). `:reimport` holds the pipeline: `KeyReconciler` classifies bindings by key and `ArtworkReloadPlanner` turns the matched/added layers into an `ArtworkReload` the session applies and the UI packs and commits — a changed layer's tile is superseded by a new tile rather than mutated (pixels are immutable per tile id, so undo and the CMO3 export both follow the lineage root), and a removed layer is left alone, flagged for review, never dropped. `PollingSourceWatcher` + `SourceWatchCoordinator` (F2) settle a save, hash the file so an unchanged save costs nothing, and dispatch a reload under the `import.watchMode` setting (auto/notify/off); a file edited while the document was closed is reported at open, never auto-reloaded. `InventoryLayerMatcher` (F3) ranks a lost binding's candidates over the inventory (name, folder, bounds, size, content hash, and pixel similarity when the file was read) to drive the Sources space's review chips and Match Automatically. Still absent: a reader and watcher for Android's SAF uris. See `docs/plan/art-sourcing-pipeline.md` § Phase F for the full mechanics.
|
||||
|
||||
### Module graph (Gradle, Kotlin DSL; KMP)
|
||||
|
||||
```
|
||||
:format commonMain — Cubism file family + art I/O. CMO3 (read/write), PSD (read),
|
||||
CLIP (read), KRA (read), MOC3, JSON family.
|
||||
:reimport commonMain — non-destructive reconcile over the model's source bindings: the
|
||||
key reconciler, the reload planner (a changed layer's tile is
|
||||
superseded, never mutated), the okio polling file watcher, the watch
|
||||
coordinator (settle, hash, idle gate), and the inventory matcher with its
|
||||
suggestions (names, folders, bounds, hashes, pixels). All commonMain -
|
||||
nothing JVM-bound.
|
||||
→ :format, :interop, :storage, :runtime (api), kotlinx-coroutines (api)
|
||||
:storage commonMain — app config/data dirs + file IO (okio) + native open/save dialogs
|
||||
(FileKit, one commonMain FilePicker impl); platform factories in
|
||||
jvmMain/androidMain (no expect/actual). → okio, FileKit
|
||||
:settings commonMain — JSON settings engine: bundled defaults ← user overrides, dotted-key
|
||||
get/set, persistence, change-event Flow. → :storage, kotlinx-serialization
|
||||
:runtime commonMain — the pure puppet runtime: the immutable PuppetModel + typed ids, the
|
||||
keyform grid algebra, the sampling eval, and the atlas domain (PuppetAtlas:
|
||||
pages + tiles, each tile's AtlasPlacement, plus the uv-affine algebra that
|
||||
maps between the art's frame and a page's). The placement lives here, not
|
||||
in :render, because it is authored state every consumer needs — including
|
||||
the CMO3 export lowering, whose module deliberately cannot see :render.
|
||||
Zero format knowledge and zero project deps — CMO3/MOC3 conversion lives
|
||||
in :interop.
|
||||
:interop commonMain — format↔runtime conversion: CMO3/MOC3 ingest (Cmo3Import / Moc3Import →
|
||||
PuppetModel), the model diff (diffPuppetModels), export notices, and the
|
||||
RuntimeTarget↔format-version mapping; jvmAndroidMain hosts the CMO3
|
||||
export reconcile (Cmo3Export: diff-driven lowering onto the retained
|
||||
graph) and the fresh-graph synthesis (Cmo3Conversion: blank skeleton +
|
||||
image chain for MOC3-origin export). Future import/export formats and
|
||||
format↔format conversions (each pivoting through PuppetModel) land
|
||||
here too — including each format's atlas-page walk (`cmo3AtlasPages` /
|
||||
`moc3AtlasPages` → a neutral `AtlasPageSet`), so :render never sees a
|
||||
container format. `art/` is the source-art → PuppetModel bridge
|
||||
(`SourceArtImport`: an UNPACKED model the app packs at open, the blend
|
||||
table, the import notices; it seeds the parameter list it is handed and
|
||||
knows no template).
|
||||
→ :format (api), :runtime (api)
|
||||
:edit commonMain — the editing session over the immutable PuppetModel: EditorSession
|
||||
(snapshot-based undo History, selection + mode state, tool latches,
|
||||
request buses), the sealed Change hierarchy, the pure edit ops
|
||||
(mesh topology/transforms, parameter edits, proportional editing), and
|
||||
the seed catalogs a new model starts from (`seed/`: ParameterTemplate +
|
||||
the humanoid standard set).
|
||||
→ :runtime (api), kotlinx-coroutines (api)
|
||||
:render commonMain — deformation eval (CPU) + the puppet renderer + morph-blend shaders,
|
||||
+ GL impl over a `RenderDevice` backend seam. → :runtime (api), :format (api).
|
||||
The whole renderer is backend-neutral commonMain now: the eval, the pure
|
||||
render logic (`puppet/`: glue layout, pose resolve, model diff, delta
|
||||
texels, bounds), the GL-family GLSL (`glsl/`, shared by GL 3.3 + GLES 3.0
|
||||
via a `GlslDialect`), the `RenderDevice` API (`device/`: handles, specs,
|
||||
uniform structs, frame/pass encoders), and `PuppetRenderer` itself, which
|
||||
makes ZERO GL calls — every GPU op goes through `RenderDevice`. A backend
|
||||
is one `RenderDevice` impl: `GlRenderDevice` (jvmMain, LWJGL/GL 3.3 core)
|
||||
ships; GLES 3.0 (android) + Metal (iOS) are ports of it, stubbed. `:render`
|
||||
is zero `expect`/`actual` AND has no jvmAndroidMain — outside the backend
|
||||
impls it is all commonMain. PNG decode goes through :format's `PngCodec`
|
||||
(the old `decodePngToRgba` expect/actual is retired). :format is a
|
||||
direct commonMain api dep — but for the NEUTRAL raster layer only
|
||||
(RasterImage in the RenderDevice upload surface, PngCodec behind the atlas
|
||||
decode). :render knows no CONTAINER format: the CMO3/MOC3 walks that
|
||||
produce a document's atlas pages live in :interop and hand back a neutral
|
||||
`AtlasPageSet` (page bytes + a drawable→page map), which the document
|
||||
loader feeds to `buildPuppetTextures` here with its format's
|
||||
`UndecodablePagePolicy` — CMO3 skips a bad page, MOC3 fails the import.
|
||||
LWJGL is DESKTOP-ONLY.
|
||||
The CPU eval (`eval/`) depends on nothing in :render and would move to
|
||||
:runtime cleanly — it stays here ON PURPOSE, paired with the GPU deform
|
||||
shaders it mirrors and that the differential oracle diffs it against.
|
||||
That is why :ui, not :edit, owns the world-space transform helpers
|
||||
(`org.umamo.ui.transform`): :edit and :render are siblings over :runtime.
|
||||
:ui commonMain — Compose Multiplatform editor UI (panels, tree, timeline, parameter
|
||||
grid) AND the shared app shell: the viewport composables + gizmo overlay
|
||||
(`org.umamo.ui.viewport`, over the `PuppetViewportService` seam) in
|
||||
commonMain, and a jvmAndroidMain (same pattern as :format) hosting the
|
||||
document/file layer + shared `org.umamo.ui.app.EditorApp` — the
|
||||
JDOM-backed CMO3 codec forces those off commonMain.
|
||||
EDITING LOGIC OVER `EditorSession` DOES NOT LIVE HERE — an `EditorSession`
|
||||
extension belongs in `:edit` (that is what the module is), and :ui keeps only
|
||||
the pointer/composition bookkeeping that feeds it plain data. The ONE
|
||||
exception is `org.umamo.ui.transform`, which needs :render's eval and so
|
||||
cannot sit in :edit (see the :render note above). Reference split:
|
||||
`KeyformCommands.kt` (:ui, resolves the hover) over `KeyformAimEdits.kt`
|
||||
(:edit, decides what the edit means).
|
||||
→ :render (api), :runtime, :interop, :edit, :settings, :storage, :format (jvmAndroid).
|
||||
:desktop jvm — thin desktop entrypoint over the shared EditorApp: the window, settings
|
||||
gate, and the LWJGL offscreen `PuppetViewportService` (GLFW hidden
|
||||
context → Compose Image; no SwingPanel/AWTGLCanvas interop remains).
|
||||
:android android — thin Android entrypoint (Activity) over the same shared EditorApp;
|
||||
the GLES `PuppetViewportService` implementation is pending — viewport
|
||||
areas render placeholders until it lands.
|
||||
:cli jvm — headless diagnostic tool: dump / extract / atlas / convert / diff over
|
||||
cmo3, moc3, and source artwork files. An operator's tool, not a
|
||||
shipping app target, so it skips :ui and :edit entirely.
|
||||
→ :interop (api brings :format, :runtime), :render
|
||||
```
|
||||
|
||||
**On disk:** library modules live under `module/`, application targets under `app/` (e.g. `module/format`, `app/desktop`); everything else at the repo root is intentionally non-module. A module's Gradle path (`:format`, `:desktop`) is kept **flat and decoupled from its folder** via `projectDir` in `settings.gradle.kts`, so dependency declarations stay terse (`project(":format")`) and *path ≠ directory ≠ package*. Stretch-phase modules follow the same scheme.
|
||||
|
||||
Keep `:format`, `:reimport`, `:runtime`, `:interop`, `:edit`, `:ui` in `commonMain` so Android and desktop share them verbatim. Platform-specific code (GPU contexts, FFI, pen, windowing) lives in `jvmMain` / `androidMain`.
|
||||
|
||||
**Build logic that more than one module needs is a convention plugin, not a copied block.** `gradle/build-logic` is an included build (not `buildSrc` — the configuration cache is on, and a `buildSrc` edit invalidates the whole build) exposing three plugins a module opts into by id:
|
||||
|
||||
- **`umamo.kmp-jvmandroid`** — creates the `jvmAndroidMain` source-set group shared by the desktop-JVM and Android targets, and wires `androidMain` onto it explicitly (the hierarchy template's `withAndroidTarget()` matches the LEGACY android target, not AGP 9's KMP android-library target, so without the edge Android silently cannot see the group). Applied by `:format`, `:interop`, and `:ui`.
|
||||
- **`umamo.kmp-ios-gate`** — makes `check` depend on `compileKotlinIosArm64` AND `compileTestKotlinIosArm64`. A device target has no runnable test task, so neither compile joins `check` on its own and the commonMain-purity guarantee silently stops firing. Applied by every module with an `iosArm64()` target.
|
||||
- **`umamo.test-corpus`** — the golden-corpus / `-D` forwarding for sample-gated tests, declared per module in a `umamoTestCorpus { }` block. Explicit `-D` wins (resolved against the REPO ROOT, and a path that does not exist fails the build); the local gitignored corpus is the default; absent both, the test self-skips and CI stays green. The shared default table lives in `org.umamo.buildlogic.sharedCorpusDefault` — add a property there only when it means the same thing in every module.
|
||||
|
||||
The failure mode these guard against is the same one throughout: a gated test that cannot find its input prints and returns, so it reports PASSED while covering nothing. Never let a module hand a Test task a sample path by hand.
|
||||
|
||||
## Fidelity contract
|
||||
|
||||
Two tiers — conflating them is the classic mistake.
|
||||
|
||||
- **Semantic validity — CMO3 (v1 primary).** Emit a valid CAFF container whose `main.xml` encodes the same object graph; the official editor's XML deserializer rebuilds it. Whole-file byte-identity is **not** the bar and is not achieved: re-emitting an unedited corpus model differs from the original (one 4-byte field per CAFF entry), and an edit would change the bytes by construction anyway. What IS asserted, and what the tests actually check, is **decompressed-content identity**: `main.xml` inflated out of a re-emitted file is byte-for-byte the `main.xml` inflated out of the original (`Cmo3FacadeTest`, `ModelDocumentTest`, `AllVersionsGateTest`), with zero unmodeled tags (`CoverageGateTest`). Do not "restore" a whole-file byte-identity claim here — it was checked against the corpus and is false. Neither writer is byte-reproducible, ours included, and that is on purpose: the editor stamps a local wall clock into each compressed blob's zip timestamp (the corpus sample reads 2022-06-06 17:03:30) and **we stamp one too**. Pinning that field to a constant would buy us determinism, but the official editor's reader is fragile and does a lot for cross-version compatibility — **when in doubt, write what the editor writes**; a convenience of ours never outranks matching its bytes. See `docs/format/CMO3.md` §1. **Round-trip is the bar:** open a corpus model, re-save, reopen in the official Cubism Editor, assert no semantic loss (mangled physics or a dropped deformer subtree kills the migration promise).
|
||||
- **Preview parity — geometry (v1 primary).** The viewport deformation must visually match the Cubism Editor's own preview within tolerance. Computed geometry is **bounded ULP / visually identical**, never bit-identical (scalar vs SIMD vs GPU diverge by construction).
|
||||
|
||||
Maintain a **golden corpus** of real `.cmo3` (and later `.moc3`) models. Never add a format version to the supported set without a corpus sample exercising it.
|
||||
|
||||
## Tech stack (and why)
|
||||
|
||||
- **Kotlin + Kotlin Multiplatform + Gradle (Kotlin DSL).** Android reuse; large accessible contributor pool; JVM reflection + JDOM make the CMO3 XML serializer (read *and* write) tractable on both desktop and Android.
|
||||
- **Compose Multiplatform** for UI (Android + Desktop, pen/touch native). See Architecture.
|
||||
- **FileKit** for native open/save dialogs — one Kotlin Multiplatform API over each OS's native picker (Win32 `IFileDialog`, Cocoa, GTK/portal) plus Android SAF, behind `:storage`'s `FilePicker` contract.
|
||||
- **GPU:** LWJGL on desktop (GL/Vulkan + GLFW, behind interop); GLES/Vulkan on Android. **Baseline:** GL 3.3 core (desktop, `#version 330 core` shaders, GLFW core-profile context) / GLES 3.0 (Android, needed for VAOs).
|
||||
- **CMO3:** CAFF container codec + reflection-driven XML serializer (JDOM 1.x, Kotlin reflection); JVM-and-Android (`jvmAndroidMain`)
|
||||
- **C++ Core FFI (stretch):** `:core-bridge` behind one interface — Panama (`java.lang.foreign`) on desktop, **JNI/NDK on Android** (Android does NOT ship the FFM API). Never put `java.lang.foreign` in shared/Android code paths.
|
||||
|
||||
## Build & run
|
||||
|
||||
See README.md for build instructions.
|
||||
|
||||
The official Cubism Core/SDK/Editor are **external dependencies of the harness only** — never committed, vendored, or linked into shipping artifacts. Never attempt to reverse engineer the official Cubism Core, SDK, or Editor.
|
||||
|
||||
## Code style
|
||||
|
||||
- **Indentation: tabs.** Set `.editorconfig` `indent_style = tab` and configure ktlint to match (overrides Kotlin's space default).
|
||||
- **Naming:** `lowerCamelCase` functions/values, `PascalCase` types (matches Kotlin convention). Naming for functions and variables (including local variables, function parameters, and loop counters) is verbose and descriptive: `bitFlip`, never `bf` or `bFlip`. Single-letter names are NOT acceptable for loop counters (`i`/`j`/`k`) — use a name that reflects what's being iterated (`pageIndex`, `slotIndex`, `wordIndex`, `lineIndex`). Single-letter dimensions are NOT acceptable: `h` could be `height` or `hue`, so write `width`, `height`. Single-letter aliases for locals inside function bodies are NOT acceptable either (e.g. `b` for `backend`, `s` for `status`, `v` for a register value, `p` for a pointer) — give the local a descriptive name. Some abbreviation is okay as long as it is not ambiguous, such as `rect` for `rectangle`. Permitted short names: `x`, `y`, `z` for coordinates (universal graphics idiom); `r`, `g`, `b` for color channels ONLY when the enclosing function/struct name disambiguates (e.g. `paletteRgbToGrbi(uint8_t r, uint8_t g, uint8_t b, ...)` — the `Rgb` in the name makes the parameters self-documenting). Use US English for spelling, example: "Color", not "Colour".
|
||||
- **World axis names:** the viewport convention is X right, Y forward, Z up, so a name that says it is world space calls its vertical axis Z (`worldOriginZ`, `Cursor2d.worldZ`, `screenToWorldZ`), never `worldY`. Space-agnostic math (`[x, y]` arrays, `MeshBounds`, GLSL `vec2`), canvas / screen / UV / NDC names, and the deform eval's pre-negation space keep y. See `PuppetModel.worldOriginX`.
|
||||
|
||||
- **Comments:** English; about *why*, not *what*.
|
||||
- **Format-citation discipline:** any code reading/writing a format field MUST cite the spec location, e.g. `// CMO3: <className> field <name>` or `// MOC3 v4 §3.2 @ +0x18`. This is the format analogue of register-citation discipline — every byte traceable to docs, and it protects the clean-room story.
|
||||
- Model format versions and deformer kinds as **sealed classes/enums**; match exhaustively so the compiler enforces coverage. No accidental nullability.
|
||||
- Prefer `expect`/`actual` over `if (platform)` for desktop/Android splits.
|
||||
- Braces are MANDATORY on EVERY `if`, `else if`, and `else` — including single-statement bodies. The body always goes on its own line inside `{ }`. The brace-less one-liner form is NOT allowed under any circumstances.
|
||||
|
||||
### Comments & documentation
|
||||
|
||||
- Public API doc comments and any non-obvious logic.
|
||||
- Don't use Markdown bold and italic formating in comments and Docblocks. Purely visual formatting is fine such as spaces, line breaks, indentation, and lists.
|
||||
- Oxford(Serial) comma, two spaces after a period at the end of a sentence.
|
||||
- **Every function gets exactly one docblock**, PHP/PHPDoc-style.
|
||||
- Open with `/**` (two stars) and close with ` */`; every interior line starts with ` * ` (leading space, star, space). This is what distinguishes a docblock from an ordinary `/* ... */` comment — reserve `/**` for documentation, use `/* */` for inline notes.
|
||||
- Structure: a one-line summary sentence, then (optionally) a blank ` *` line and a longer prose description, then the tag block. Order of tags: `@param` (one per parameter, in signature order), `@return`, then any of `@note` / `@warning` / `@see` / `@pre` / `@post` as needed. Omit `@return` for `void` functions. Omit `@param` when there are no parameters (`void`).
|
||||
- `@param type variable description`
|
||||
- Indent with tabs, consistent with the rest of the file.
|
||||
- Example 1:
|
||||
```kotlin
|
||||
/**
|
||||
* Clears the current GL framebuffer to the given color. Assumes a context is current.
|
||||
*
|
||||
* @param Float red Red Color
|
||||
* @param Float green Green Color
|
||||
* @param Float blue Blue Color
|
||||
* @param ByteArray bytes Raw bytes from the file
|
||||
* @return ReturnedVariable
|
||||
*/
|
||||
actual fun clear(red: Float, green: Float, blue: Float, alpha: Float) { }
|
||||
```
|
||||
|
||||
## Guardrails (hard rules — contributors and AI assistants)
|
||||
|
||||
- **Re-import never destroys rig work.** Removals/renames are flagged and reviewable, never silently applied.
|
||||
- **Docking is a Blender-style area tree:** the window is a recursive split tree of areas; each area hosts one editor space and is switchable to any space via its header dropdown; splitters are draggable. No free-floating windows. One shared desktop/tablet interface with a touch-tuned skin — never a second front-end.
|
||||
- **All input dispatches through the action registry** — menus, toolbar, radial menu, and shortcuts never hardcode handlers, so a rebind takes effect everywhere.
|
||||
- **All UI strings externalized; localize chrome/display, never format-level IDs** — `ParamAngleX` and the rest of the CMO3 identifiers stay verbatim for interop.
|
||||
- **CMO3 round-trip must pass before any format-write change merges.** (Open → re-save → reopen in official editor → no semantic loss.)
|
||||
- **Binary formats implement the shared `FormatCodec` contract** (`kind`/`matches`/`read`/`write`, dispatched via `FormatRegistry`); JSON sidecars stay text helpers. No bespoke per-format read/write facade.
|
||||
- **Two fidelity tiers respected:** semantic-validity for CMO3, bounded-ULP for geometry, byte-exact only for MOC3 binary. Never relax format correctness; never chase bit-identical geometry.
|
||||
- **No `java.lang.foreign` in shared/Android paths** (absent on Android). FFI only behind `:core-bridge`.
|
||||
- **No Swing/JavaFX as UI** (Compose only). The desktop GL viewport is not Swing interop either — it renders offscreen via a hidden GLFW context into a Compose `Image`.
|
||||
- **MOC3 version policy:** read v1–v6.
|
||||
|
||||
## Glossary
|
||||
|
||||
- **Drawable / art mesh** — textured triangle mesh with draw/render order, masks, blend mode, opacity, multiply/screen color.
|
||||
- **Warp deformer** — FFD lattice; **Rotation deformer** — nesting pivot transform.
|
||||
- **Parameter** — animation axis (e.g. `ParamAngleX`); **Keyform** — captured state at specific parameter values; runtime blends across the N-D keyform grid.
|
||||
- **Source-art binding** — the stable-identity link from a rig drawable to a source layer; basis of non-destructive re-import.
|
||||
- **File family** — `.cmo3` (editor source: CAFF container + XML-serialized object graph + embedded PNGs) · `.moc3` (runtime, C structs) · `model3/physics3/cdi3/pose3/exp3/motion3/userdata3.json` · texture atlas.
|
||||
Executable
+19
@@ -0,0 +1,19 @@
|
||||
#!/bin/bash
|
||||
# Blocks any Claude Code tool call that touches /mnt
|
||||
|
||||
input=$(cat)
|
||||
|
||||
# Pull out the fields that might contain a path
|
||||
file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
|
||||
command=$(echo "$input" | jq -r '.tool_input.command // empty')
|
||||
notebook_path=$(echo "$input" | jq -r '.tool_input.notebook_path // empty')
|
||||
|
||||
# Check each for /mnt (with or without leading slash variants, and case just in case)
|
||||
for candidate in "$file_path" "$command" "$notebook_path"; do
|
||||
if echo "$candidate" | grep -qE '(^|[[:space:]/])/mnt(/|$| )'; then
|
||||
echo "Blocked: this tool call references /mnt, which is off-limits in this project." >&2
|
||||
exit 2
|
||||
fi
|
||||
done
|
||||
|
||||
exit 0
|
||||
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Read|Write|Edit|Bash|NotebookEdit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/block-mnt.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
description: Sweep a branch's changed files against a base ref and fix comments/docblocks that no longer describe current code — stale claims, leftover planning/phase language, bug-narrative diary comments, irrelevant comparisons to unrelated tools/projects, wrong CMO3/MOC3 field citations, and incomplete docblocks. Batches large branches across parallel background agents. Use when asked to "clean up comments," "fix comments on this branch," or before merging a branch that accumulated debugging-session comment cruft.
|
||||
argument-hint: [base-ref]
|
||||
---
|
||||
|
||||
# Comment cleanup
|
||||
|
||||
Reviews every comment and docblock touched by a branch (compared against `$1`, default `master`)
|
||||
and fixes the ones that no longer tell the truth about the code below them. This is a text-only
|
||||
pass: never change code logic. Suspected actual code bugs get flagged for the user, not silently
|
||||
fixed — this skill's job is the comments, not the implementation, except where explicitly asked
|
||||
to also apply a flagged fix.
|
||||
|
||||
## 1. Scope the diff
|
||||
|
||||
```
|
||||
git merge-base <base-ref> HEAD
|
||||
git diff --name-status -M <base-ref>...HEAD
|
||||
```
|
||||
|
||||
Always pass `-M` (rename detection) — without it, a renamed-with-edits file shows as a spurious
|
||||
delete+add pair, and pathspec-glob queries on the raw file list can double-count or miss renamed
|
||||
paths. Cross-check any manually-assembled file list against `git diff --name-only` with a
|
||||
set-difference (`comm -13`/`comm -23`) before trusting it's complete and non-overlapping.
|
||||
|
||||
If the user says "second round" or references prior cleanup work on the same branch, scope to
|
||||
`<last-cleanup-commit>..HEAD` instead of the whole branch — that's usually a much smaller, more
|
||||
targeted diff, and re-reviewing already-clean content wastes the pass.
|
||||
|
||||
## 2. Decide solo vs. delegated
|
||||
|
||||
- **Under ~30 changed files**: review directly, file by file, using `Read` and `git diff <base>...HEAD -- <path>`
|
||||
per file. Keep a `TodoWrite` list per file cluster so progress survives context compaction.
|
||||
- **Larger** (a big feature branch, a multi-week history sweep): batch by **module/directory
|
||||
boundary**, not by commit range — a file's *final* state is what matters, not which commit last
|
||||
touched it. Dispatch each batch as a background `Agent` (`subagent_type: general-purpose`,
|
||||
`run_in_background: true`) so batches run in parallel. Aim for batches of roughly 5–20 files or
|
||||
~1000–2000 diff lines; split a single very large file (500+ lines) into its own batch if it's
|
||||
dense.
|
||||
- Before delegating, personally read and fix ONE representative example yourself first (see §5) —
|
||||
it gives you a concrete before/after to paste into every agent prompt, which is what keeps
|
||||
agent output consistent instead of six different interpretations of "stale."
|
||||
|
||||
Every delegated agent prompt must include, verbatim or adapted:
|
||||
- The exact file list for its batch (absolute repo-relative paths).
|
||||
- The seven categories from §3, each with the concrete calibration example from §5.
|
||||
- The explicit "what not to do" list from §4.
|
||||
- An instruction to flag suspected real code bugs as `POSSIBLE CODE BUG: file:line — reason`
|
||||
instead of fixing them.
|
||||
- A word budget on the final report (400–700 words depending on batch size) so N parallel reports
|
||||
don't blow the orchestrating session's context on consolidation.
|
||||
|
||||
## 3. What counts as a fix (seven categories)
|
||||
|
||||
**(A) Staleness.** A comment/docblock describes behavior, a signature, a nullability, a module
|
||||
location, or a control-flow path that no longer matches the code beneath it. Includes dangling
|
||||
cross-references (`[FormerName]`, a package that moved to another module, a docblock enumerating
|
||||
fields that no longer match a `when` below it). Fix to describe the code as it stands now.
|
||||
|
||||
**(B) Planning/phase language.** Leftover roadmap-numbering that reads like a project-plan label
|
||||
rather than a description of what a step *does* — `Phase 1` / `Phase 2` inside a function that
|
||||
runs both steps unconditionally every time, `(M2)`/`(M4)` milestone tags, `Slice A`, `Part 2 of`,
|
||||
"placeholder pending a future step" for something that's actually wired, "dedicated follow-up" for
|
||||
work already done in the same branch. Fix by renaming to what the step IS, not by deleting the
|
||||
structure. Example fix applied in this project:
|
||||
|
||||
```
|
||||
- // Phase 1 - set membership: identity shells for creations, source removal for deletions.
|
||||
+ // Structural pass - set membership: identity shells for creations, source removal for deletions.
|
||||
```
|
||||
|
||||
**Do not touch legitimate roadmap citations** — `docs/plan/art-sourcing-pipeline.md § Phase G` is a
|
||||
real, still-open phase in a real design doc; a comment citing it accurately is not planning-language
|
||||
cruft. The test is whether the *cited plan* still exists and is still pending, not whether the word
|
||||
"Phase" appears.
|
||||
|
||||
**(C) Bug-narrative / debugging-diary comments.** Rewrite comments that narrate a bug's discovery
|
||||
story in a way that needs hidden context — "used to X, which caused Y, so now Z," "never showed the
|
||||
bug," "one desync was observed (date) where..." — into either a direct atemporal statement of the
|
||||
current invariant, or counterfactual "would" framing explaining what the guard prevents. Example:
|
||||
|
||||
```
|
||||
- // one desync was observed (2026-08-03) where a second MOC3 exported the first model's rig
|
||||
- // onto the second's atlas pages, which reads as a wall of drawable notices...
|
||||
+ // a session from a stale composition pass would export the PREVIOUS document's rig onto this
|
||||
+ // document's atlas pages, surfacing as a wall of drawable notices...
|
||||
```
|
||||
|
||||
**Exception — test docblocks only:** a regression test MAY reference a historical bug if the
|
||||
mechanism is fully and concretely spelled out in the comment itself (not left as an opaque "the
|
||||
bug"). That's normal regression-test practice, not narrative cruft — don't over-correct it.
|
||||
|
||||
**Exception — dated "KNOWN GAP" / investigative documentation:** a long, precise, dated note that
|
||||
documents a real, currently-open limitation (what's broken, why, what's been ruled out, where the
|
||||
real fix lives) is valuable "why" documentation, not diary cruft — even when it's long and reads
|
||||
like it came out of a debugging session. Only fix it if a claim in it is factually wrong or has
|
||||
been superseded by a later change; never trim it just for length.
|
||||
|
||||
**(D) Format-citation discipline.** Any comment touching a binary/serialized format field must cite
|
||||
it per the project convention (`// CMO3: <ClassName> field <name>`, `// MOC3 §N ...`). Fix a
|
||||
missing/wrong citation only if you can verify the correct one by reading the actual field/class
|
||||
definition — never guess a citation.
|
||||
|
||||
**(E) Docblock completeness.** Per the project's docblock style, an *existing* docblock needs one
|
||||
`@param` per parameter (signature order) and `@return` for non-void functions. If a parameter was
|
||||
added later without updating the docblock, add the tag. **Never add a docblock to a function that
|
||||
never had one** — that's a different task, not this one.
|
||||
|
||||
**(F) Formatting/whitespace artifacts.** Heavy debugging-session editing sometimes leaves stray
|
||||
indentation (a nested function at 4 tabs instead of 1, relative to its scope) or a duplicate
|
||||
comment block sitting next to the new one that replaced it. Cheap to spot with `cat -A` on the
|
||||
touched region; fix as pure whitespace, zero semantic risk.
|
||||
|
||||
**(G) Irrelevant tool/project comparisons.** A comment justifies a file's or function's existence
|
||||
or design by contrasting it with what some unrelated tool or project does or doesn't do — "this is
|
||||
the pipeline node Umamo owns and Blender does not," "unlike Photoshop," "which no other rigging
|
||||
tool does" — where the comparison itself carries no technical information about this code's actual
|
||||
behavior. A comment describes the purpose of the code in front of the reader, not a scorecard
|
||||
against unrelated software. Fix by deleting the comparison and keeping only the real technical
|
||||
rationale; if the comparison was the entire reason given, replace it with the actual reason (read
|
||||
the surrounding code or the relevant `docs/plan/`/`docs/format/` doc to find it) rather than
|
||||
leaving a bare, now-shorter claim. Example fix applied in this project:
|
||||
|
||||
```
|
||||
- * This is the pipeline node Umamo owns and Blender does not - because the 2D source art hands us
|
||||
- * each piece's opaque silhouette before packing, the atlas can be generated rather than authored
|
||||
- * by hand and reconciled.
|
||||
+ * Because the 2D source art hands us each piece's opaque silhouette before packing, the atlas can
|
||||
+ * be generated rather than authored by hand and reconciled.
|
||||
```
|
||||
|
||||
**Do not touch a comparison that names an actual compatibility or fidelity target** — "matches the
|
||||
official Cubism Editor's export ordering," "unlike the CMO3 v3 schema, v4 adds a blend-shape
|
||||
table" — those name a concrete constraint the code is built to satisfy (per the Fidelity contract
|
||||
in CLAUDE.md), not a rhetorical aside about an unrelated project. The test is whether the named
|
||||
project is the thing this code interoperates with or is bounded by (Cubism/CMO3/MOC3 for this
|
||||
codebase), not whether a proper noun appears in the sentence.
|
||||
|
||||
## 4. What not to do
|
||||
|
||||
- No code-logic changes. Comment, docblock, and pure-whitespace text only.
|
||||
- Don't add new comments/docblocks to undocumented functions.
|
||||
- Don't "improve" already-accurate comments for style alone.
|
||||
- Don't shorten legitimate dated investigative documentation just because it's long (see the (C)
|
||||
exception above).
|
||||
- Don't touch files outside the assigned scope/batch.
|
||||
- Don't touch a project's own scratch/notes file above whatever heading marks it off-limits, if the
|
||||
project's memory or CLAUDE.md says so (this repo: `TODO.md` above `# Claude Notes` is Alexia's
|
||||
personal pad).
|
||||
|
||||
## 5. Calibrate before delegating
|
||||
|
||||
Read one file yourself, find one real instance of category (A) or (B), fix it, and keep the exact
|
||||
before/after diff. Paste that verbatim into every batch's agent prompt as "here's a fix I already
|
||||
made for calibration — read the file yourself since it won't show in `git diff` yet." This is what
|
||||
keeps parallel agents from either being too aggressive (rewriting fine comments for style) or too
|
||||
timid (leaving real staleness because it wasn't a 100% textual match to the example).
|
||||
|
||||
## 6. Consolidate and verify
|
||||
|
||||
- Every `POSSIBLE CODE BUG` an agent reports gets personally verified before it goes in the final
|
||||
report — read the actual code, trace the call graph, confirm the claim with `grep`/`git log -L`
|
||||
as needed. Never forward an unverified agent claim as a finding.
|
||||
- Run a final repo-wide sweep for residual patterns the agents might have missed individually:
|
||||
```
|
||||
git diff --name-only <base-ref>...HEAD -- '*.kt' | while read -r f; do
|
||||
grep -noE 'Phase [A-Za-z0-9]+|\(M[0-9]+\)|Step [0-9]+|Slice [A-Z]|for now\b' "$f"
|
||||
done
|
||||
```
|
||||
- Sanity-check the aggregate diff: `git diff --stat` should show a comment-sized insert/delete
|
||||
ratio (roughly 1:1, small numbers) — a large net line-count change means something drifted into
|
||||
code edits.
|
||||
- If a fix touches control flow that a report only weakly implied should change (e.g. a stale
|
||||
comment that was ALSO a real duplicate-notice bug), don't fix the logic unasked — report it, and
|
||||
wait for explicit approval before removing/changing behavior (see the `Cmo3PropertyLowering`
|
||||
redundant-notice example from this project's history: flagged first, fixed only after the user
|
||||
said "go ahead").
|
||||
|
||||
## 7. Report format
|
||||
|
||||
Group findings by theme, not by batch — the user doesn't care which agent found what. Lead with
|
||||
the most consequential fixes (wrong logic implied by a comment, swapped comment blocks, a
|
||||
misleading user-facing string), then the routine staleness/phase-language sweep, then any verified
|
||||
`POSSIBLE CODE BUG` flags left for the user's own triage. Keep it scannable: file references, one
|
||||
line of before → after gist each, no prose padding.
|
||||
Reference in New Issue
Block a user