Difforum 1.0: camera direction layer with timeline Director, video-model bridges and AE/Blender export

.comfyignore

@@ -1,6 +1,7 @@
-# Dev-only files - kept in git, excluded from the published registry package.
+# kept in git, left out of the published registry package
 tests/
-examples/_*
+tools/dev/
+.github/
+docs/media/*.webp
 *.log
-*.log.err
-_e_models.yaml
+__pycache__/

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main, v1]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - name: Install
+        run: |
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install numpy pillow opencv-python-headless imageio-ffmpeg pytest ruff
+      - name: Lint
+        run: ruff check .
+      - name: Tests
+        run: pytest
+      - name: Generated files are current
+        run: |
+          python tools/build_workflows.py --check
+          python tools/build_docs.py --check
+      - name: JS syntax
+        run: node --check js/director_timeline.js

.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to Comfy Registry
+
+# Runs when pyproject.toml changes on main (i.e. a version bump), or by hand.
+# Needs the repository secret REGISTRY_ACCESS_TOKEN (registry.comfy.org).
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths: ["pyproject.toml"]
+
+jobs:
+  publish:
+    if: github.repository_owner == 'chillithebillis'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Comfy-Org/publish-node-action@v1
+        with:
+          personal_access_token: ${{ secrets.REGISTRY_ACCESS_TOKEN }}

.gitignore

@@ -2,22 +2,13 @@ __pycache__/
 *.pyc
 *.pyo
 .pytest_cache/
+.ruff_cache/
 .DS_Store
 *.egg-info/
 build/
 dist/
-
-# local smoke-test artifacts (machine-specific paths / rendered output)
-examples/_render_out/
-examples/_test_model_paths.yaml
-examples/_e_models.yaml
-examples/_promo_frames/
-examples/_palette.png
-examples/_server.log
-examples/_server.log.err
-
-# comfy-cli publish artifact + private notes
 node.zip
 *.zip
+tools/dev/out/
 NEXT_STEPS.md
 REVIEW.md

CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 1.0.0
+
+Difforum becomes a direction layer: a visual timeline drives any renderer.
+
+### New
+- **Director (timeline)**: a multi-track editor with Scenes (prompt + mood), Camera
+  (visual move picker, speed, amount, lens, easing, per-block audio reaction) and
+  Energy (a drawable denoise curve), plus an animated camera preview computed by the
+  render engine. A single `direction` wire feeds the renderers.
+- **Setup** with target model grids: LTX 8k+1, MiniMax H3 17k+5 @ 24 fps, Wan 4k+1.
+- Video model bridges: **Guide Frames**, **Keyframes**, **Camera → Prompt**,
+  **LTX Guides** (core `LTXVAddGuide`), **H3 Guides** (core `MiniMaxH3AddGuide`, multi-keyframe)
+  and **H3 Shot** (first/last frame, segments).
+- **Camera Export** to After Effects (.jsx), Blender (.py) and JSON; **Camera Import**
+  from them, with helper exporters in `tools/`.
+- 7 new moves: tilt up/down, crane up, handheld, drift, breathe, vortex.
+- Feedback Sampler outputs the tracked depth per frame and a run report; its fine-tuning
+  moved to a separate **Render Options** node, so the sampler stays small.
+- 10 templates in ComfyUI's template browser, generated from the node definitions.
+
+### Improved
+- One shared feedback engine behind the Feedback Sampler, Live Sampler and Storyboard.
+- Depth follows the image in 3D, and pseudo-3D replaces the silent freeze without depth.
+- Cadence crossfades between keys. Revealed areas are repainted with extra noise.
+- Colour anchoring per scene. Lazy prompt travel. Ring buffer in the Live Sampler.
+- Deterministic 3D z-buffer on CUDA / MPS / CPU.
+
+### Fixed
+- The pack no longer imports a top-level `core` module (it collided with other packs).
+- The 0.x templates `audio_reactive_video`, `deluxe` and `mesmerize` had camera values
+  in the wrong fields. The v1 templates are generated, so this cannot recur.
+- `feedback_classic` and `hybrid_wan_guides` rendered a static camera (3D move, no depth).
+
+### Removed / deprecated
+- 0.x nodes are kept under Difforum/legacy (hidden, deprecated) until 2.0. See
+  docs/MIGRATION.md.
+- Model Profile / Model Catalog → docs/MODELS.md. Load/Save Video → ComfyUI core
+  nodes. Look, Grade, Glow, Glitch, Datamosh → legacy only.
+- Media moved to `docs/media/` as small WebP files. The published package is ~40 MB lighter.

CONTRIBUTING.md

@@ -4,37 +4,37 @@ Thanks for your interest. Difforum is MIT-licensed and built to be extended.
 
 ## Ground rules
 
-- **Keep dependencies minimal.** Core logic uses numpy and a safe AST evaluator;
-  torch is only used inside nodes that need it. No librosa / numexpr / pandas, so
-  the package keeps installing cleanly on Python 3.12 and the Comfy Registry.
-- **Run the tests** before opening a PR (no GPU needed):
+- **Keep dependencies minimal.** The engine uses numpy and torch (which ship with
+  ComfyUI); OpenCV only where a node needs it, and imported lazily. No librosa,
+  numexpr or pandas.
+- **Engine first.** Put logic in `core/` (pure, testable, no ComfyUI), and keep
+  nodes thin. Import the engine relatively (`from ..core import ...`).
+- **Every node gets a docstring and tooltips.** They become the in-app
+  description and `docs/NODES.md`.
+- **Style:** match the surrounding code, no em dashes, and run `ruff check .`
 
-  ```bash
-  for t in core audio hybrid models warp color effects look video detail shots flow glitch prompt plot integration; do
-    python tests/test_$t.py
-  done
-  ```
-
-- **Match the surrounding style** (naming, comment density, no em dashes).
-- **Regenerate the example workflows** if you change a node's inputs:
-  `python examples/_build_examples.py` then `python examples/_validate_workflows.py`.
-
-## Developer Certificate of Origin (DCO)
-
-To keep the project's licensing clean and flexible, contributions are accepted
-under the [DCO](https://developercertificate.org/): you certify that you wrote
-the patch (or have the right to submit it) and agree it can ship under the
-project's MIT license. Sign off each commit:
+## Before a pull request
 
 ```bash
-git commit -s -m "your message"
+pytest                                      # no GPU or ComfyUI needed
+python tools/build_workflows.py             # if you changed any node inputs
+python tools/build_docs.py                  # if you changed docstrings / tooltips
+ruff check .
 ```
 
-which adds a `Signed-off-by: Your Name <you@example.com>` line.
+CI runs all of these, plus `--check` on the generated files.
+
+## Developer Certificate of Origin
+
+Contributions are accepted under the [DCO](https://developercertificate.org/).
+Sign off each commit with `git commit -s`.
 
-## Scope ideas
+## Good places to extend
 
-Good places to extend: new schedule functions, camera presets, effects (the
-`core/effects.py` and `core/symmetry.py` style), reactive audio modes, model
-catalog recipes, and the realtime path (NDI sink, MIDI/OSC control). See
-[DESIGN.md](DESIGN.md) and [REALTIME.md](REALTIME.md).
+- New camera moves: `core/camera_presets.py`. Add the expressions and a
+  `MOVE_INFO` entry; the Director picks it up automatically, and a glyph in
+  `js/director_timeline.js` is optional.
+- New audio reactions: `REACTIONS` and `_react()` in `core/direction.py`.
+- More bridges: follow `nodes/bridges.py`. Output plain types, or call core
+  nodes through `call_comfy_node()`.
+- Camera interchange for more DCCs (Nuke, Houdini, Unreal): `core/export.py`.