wtd-libreflow-addon/CLAUDE.md

# Melvile Tools: notes for Claude

Blender add-on (Blender 5.2) for the Melvile pipeline at Walking The Dog: Sanity Check,
Rename, Shot Manager and Scene Manager panels in the 3D View sidebar (WTD tab). `README.md`
is the user guide: keep it up to date with every user-visible change.

## Layout and conventions

- `config.py`: every production value (prefixes, formats, patterns, modes). Values are
  read at run time (`config.X`, never copied at import) because a studio JSON file can
  override them (add-on preferences "Config Override", or `WTD_SANITY_CONFIG`).
  New tunable values go here, with a comment, and in the README's Configuration table.
- `ui/panel.py`: all panels. Operators live with their tool (`rename.py`,
  `shot_viewer.py`, `scene_manager/`, `ui/operators.py` for the Sanity Check).
- `checks/`: sanity checks, auto-registered (see README > For developers).
- `__init__.py` deletes cached submodules on reload, so Reload Scripts picks up every file.
- Versions: `blender_manifest.toml` and `bl_info` in `__init__.py` (keep both in sync).
- Style: match the surrounding code; short docstrings, few comments, no heavy abstractions.

## Working with the user

- Commits: when asked, create a branch from `master`, commit there (end with the
  Co-Authored-By line), and give the user the merge / push / branch-delete commands:
  they run them themselves. Only commit straight on `master` when told to.
- Real Blender API facts beat memory: probe in headless Blender before relying on an API.

## Testing

Blender binary: macOS `/Applications/Blender.app/Contents/MacOS/Blender`, Windows
`blender.exe` from the install folder. Import the add-on in tests by putting the folder
that contains this repo on `sys.path` and importing the repo folder name (see
`dev/test_scene_manager.py`).

- Headless: `blender -b --factory-startup --python-exit-code 1 --python <script> -- <args>`.
  Timers do not run in background mode: pump background jobs by hand
  (`scene_manager.ipc._poll()`).
- UI: run Blender with a window (`--factory-startup <file.blend> --python <script>`, a
  .blend argument avoids the splash), drive it with `bpy.app.timers`, take screenshots with
  `bpy.ops.screen.screenshot_area`, quit with `bpy.ops.wm.quit_blender()`. A sidebar tab
  (`region.active_panel_category`) can only be set once the region has been drawn.
- Scene Manager without Libreflow (`dev/`):
  1. `blender -b --factory-startup --python dev/make_test_assets.py -- <workdir>`
  2. `python dev/fake_libreflow.py <workdir>` (keep running; restart for a clean state)
  3. `blender -b --factory-startup --python-exit-code 1 --python dev/test_scene_manager.py -- <workdir>`
     (71 checks, "All checks passed"). `/_test/publish` and `/_test/download` simulate a new
     publish and a requested revision reaching this site.
  The fake server follows the real `wtdcmds` replies; check them against the real
  Libreflow when one is available.

## External pieces

- Libreflow `wtdcmds` extension (commands used by the Scene Manager), on the share:
  `WG/_Dev/GIT/ndemaerschalk/_MELVILE/libreflow_dev_utils/dev/src/wtdcmds/`
  (`src/libreflow/extensions/wtdcmds/wtd_cmds.py`, `BLENDER_ADDON_BRIEF.md`).
  Server address/token: `~/.kabaret/ipc/server.json` (config `LIBREFLOW_SERVER_FILE`).
- Add Camera Rigs extension: `bpy.ops.object.build_camera_rig(mode=...)` builds the
  Shot Manager cameras. It finds its rigs by the `rig_id` custom property, not by name.
- `tools_ops.py` "Get Oid" uses the separate kabaret Blender client (`bpy.ops.kabaret.cmds_call`).

## Design notes (found by testing)

- Shot Manager: shots are timeline markers bound to cameras, in one scene. Setting
  `scene.frame_current` does not switch the camera (only `frame_set` does): set
  `scene.camera` explicitly.
- Scene Manager: tags live on `bpy.types.Library` only. Library overrides lose custom
  properties when they resync, so instances are traced back to their library (empty →
  `instance_collection.library`, override → `override_library.reference.library`).
- `library.reload()` invalidates every Python reference to linked and override data:
  look IDs up again afterwards. In Blender 5.2 it also replaces the Library itself (renamed
  after its file, custom properties gone): `library.update()` finds it by path and restores
  the name and tags.
- Removing a library leaves the libraries it linked indirectly (e.g. Blender's
  `geometry_nodes_essentials.blend`): `remove_unused_libraries()` drops the ones whose data
  is no longer used, never a managed library.
- LODs are child collections of the asset collection (`COL_{asset}_LOD{lod}`, any name,
  ordered by `SCENE_MANAGER_LODS`, then numbers, then names; the first is the default). Overrides
  switch by `hide_viewport`/`hide_render` on the LOD override collections: Blender stores
  them as override properties (kept through save, reload and resync) and hidden LODs are
  not evaluated. Collection instances instance the LOD collection itself. A second override's
  collections are renamed (`.001`): match LODs on `override_library.reference.name`.
- "Shot Manager" is the user-facing name of what the code calls `shot_viewer`
  (module, operators, `SHOT_VIEWER_*` config keys kept for existing override files).
- Background requests (`scene_manager.ipc.run`) hand results back through a timer;
  in callbacks, find scenes by name (`bpy.context.scene` is not reliable in timers).

## Real Libreflow (first run, 2026-10-27)

- Kitsu asset types: `main_character`, `secondary_character`, `tertiary_character`,
  `main_props`, `secondary_props`, `set_props`, `vehicles`, `bg_location`, `bg_set`,
  `skies`, `setdress_bank`. The fake server uses the same names.
- Paths come back as Windows paths with backslashes; `comment` can be `null`.
- Set dressing publishes (`setdress_low`) hold a whole layout scene: the set is the
  `environments` collection, next to `lights`, `cameras`, `characters`, `_unused`.
- Tested live: connection, context, casting, load (instance and override), version switch
  and update, remove, assetize errors, one request (`car_paul` modeling.blend v001 →
  `Requested`). Not tested: an actual assetize publish (it writes to production).
  New wtdcmds commands need every Libreflow session restarted (a running one keeps the
  old code and answers 404).
- Load Publish (2026-10-28) uses only existing commands (`wtd_list_assets`,
  `wtd_get_asset_files`, `wtd_get_revisions`): 309 assets in ~0.1 s, live-tested on
  `car_paul` (loaded twice: `car_paul_01`, `car_paul_02`).
- `/melvile/films/melvile` has no sequences or shots in Libreflow yet; `melvile_test` has 9.
- Deployed Libreflow (Overseer launcher): wtdcmds must be an "extension" entry, so the
  launcher adds `libreflow.extensions.wtdcmds:install_extensions` to
  `KABARET_FLOW_EXT_INSTALLERS`; the package name must stay `libreflow.extensions.wtdcmds`.
  The launcher only rebuilds its env when the project config changes: "Force update".

## Open points

- Override vs instance per asset type (`SCENE_MANAGER_LINK_MODES`), and the file patterns
  of sets (`setdress_low` seen on one asset only): confirm with production.
- The server picks the first file matching a pattern even when it is not on this site,
  while another matching file is (e.g. `car_paul`: `modeling/modeling.blend` v001 not
  available, `modeling/tes_modeling.blend` v002 available).
- Values marked TODO in `config.py` wait for production specs.