Comfyui-Workflow-Snapshot-Manager/docs/plans/2026-06-29-nondestructive-timeline-research-and-plan.md

Non-Destructive Timeline — Research Report & Implementation Plan

Date: 2026-06-29 Goal: Make the Snapshot Manager timeline behave like Autodesk Fusion 360's parametric timeline — jumping back and forth is easy, fast, and non-destructive — while fixing the three reported pain points: (1) weak "what changed" info, (2) spammy autosave, (3) workflow switching spams "now save".

This document has two parts:

• Part 1 — Research report (web research, 25 claims survived 3-vote adversarial verification).
• Part 2 — Implementation plan (each recommendation mapped to concrete changes in js/snapshot_manager.js).

---

Part 1 — Research Report

Executive summary

Across Fusion 360 (CAD), Houdini (node graph), Unreal (Blueprint diff), Final Cut Pro (NLE), Figma and Google Docs (history panels), the tools that feel non-destructive share four moves: (a) jumping back never deletes later work — it disables and recomputes it (Fusion) or keeps the live state untouched while you preview (Final Cut Pro skimmer); (b) preview is decoupled from commit — you can hover/scrub other states and still "return to where you were"; (c) a restore/jump records the pre-jump state once as a checkpoint (Figma) rather than spamming checkpoints; and (d) "what changed" is shown semantically (named parameters, fixed color-coded change types — Unreal's red/green/cyan/grey), with trivial moves de-emphasized and auto-history coalesced by time or by filtering out streaming/cosmetic edits (Figma's 30-min cadence; redux-undo's filter/excludeAction/groupBy; Houdini's explicit warning against over-automatic capture). These map cleanly onto a snapshot-per-state model and onto all three pain points.

Findings

F1 — Non-destructive "jump back" = disable + recompute, never delete (Fusion 360) — HIGH

Fusion records every step in creation order and lets you "go back in time" to edit earlier decisions without starting over. Mechanically, editing/rolling to a past feature rolls the history marker to just before it and disables (not deletes) all downstream nodes, then recomputes them forward when you roll back to the end — "all the features that were after that point are preserved and will reappear." Rolling the marker back "has not deleted the features in front of the marker." This is the load-bearing property: navigating history is a reversible editing surface, not a destructive log. Sources: autodesk.com Fusion blog (timeline-edits, beginners-guide-part-4) — primary; help.autodesk.com Fusion-360-API CustomFeatures_UM — primary; productdesignonline.com; Ace Makerspace. Votes 3-0 (×5), 2-1 (×1).

F2 — Navigation gesture == edit gesture, plus a draggable marker with playback controls (Fusion) — HIGH

A past step is edited in place by double-clicking it, or right-click → Edit Sketch/Edit Feature. Pure navigation is a draggable history-marker slider ("rolling back the design") with playback controls (move-to-beginning, previous step, play, next step, move-to-end) and a right-click "Roll History Marker Here" to jump the marker directly to any step. So back/forth is a one-gesture, low-friction interaction distinct from editing. Sources: autodesk.com Fusion blog — primary; productdesignonline.com (blog); Noble Desktop. Votes 3-0.

F3 — Decouple preview from committed position — the skimmer pattern (Final Cut Pro) — HIGH

Final Cut Pro uses two indicators: a persistent playhead (your committed position, fixed unless you move it) and a transient skimmer (a preview cursor that follows the pointer). The skimmer "lets you preview clips… without affecting the playhead position," so you can "skim to see what's in other clips but still keep your playhead position." This is the canonical "scrub-to-preview, keep your place / return to where I was" pattern — non-destructive preview decoupled from the committed edit position. Sources: support.apple.com Final Cut Pro (skimmer, intro-to-playback) — primary; Larry Jordan; Ripple Training. Votes 3-0 (×3), 2-1 (×1).

F4 — Semantic, color-coded "what changed" + difference navigation (Unreal Blueprint diff) — HIGH

Unreal's Blueprint Diff Tool communicates change type visually with a fixed legend: red = removed, green = added, cyan = changed, grey = moved nodes/comments. It provides Next/Previous buttons to cycle differences one at a time and a clickable navigation tree to jump to a specific difference. The lesson: show the kind of change semantically (not raw indices), and explicitly give moves their own subdued category (grey). Sources: dev.epicgames.com UE Diff Tool docs (UE 5.7) — primary. Votes 2-1 (color legend), 3-0 (navigation).

F5 — Scope change capture explicitly; warn against over-automatic capture (Houdini takes) — HIGH

Houdini "takes" are hierarchically overlaid sets of parameter changes: any parameter you don't explicitly change is inherited from the parent, enabling non-destructive parallel variations that preserve the original. Only explicitly included parameters are editable in a take (others appear disabled), and the takes pane shows which parameters changed for the selected take. Critically, SideFX explicitly warns against overusing Auto-take mode because it "makes it easy to unintentionally include parameters… which… can make diagnosing problems difficult" — a first-party anti-pattern for automatic change capture that mirrors this tool's autosave spam. Sources: sidefx.com/docs/houdini takes + ref/panes/takes — primary. Votes 3-0.

F6 — Restore/jump is non-destructive because it checkpoints the pre-jump state once (Figma) — HIGH

Restoring a previous version in Figma "is a non-destructive action, so you can still access the current version." It works by adding two autosave checkpoints: one preserving the current/pre-restore state, one marking the restored version. So later work is never silently lost — it's captured as a checkpoint exactly once at the moment of restore. Sources: help.figma.com version-history — primary. Votes 3-0.

F7 — Coalesce auto-history by time; separate viewing from restoring; named vs auto (Figma, Google Docs) — HIGH

Figma records an auto checkpoint every 30 minutes (time-based coalescing) while keeping the live "current version" continuously up to date — it does not snapshot on every edit. Google Docs separates viewing an earlier version (read-only; a "Back" control returns you to current, no state change) from restoring it (explicit "Restore this version"). It also supports named versions distinct from auto-saved revisions, with an "Only show named versions" filter to cut noise (caps: 40 named/doc, 15/spreadsheet). Sources: help.figma.com; support.google.com/docs/answer/190843 — primary. Votes 3-0.

F8 — History-noise control patterns: filter, exclude streaming actions, group into chunks (redux-undo) — HIGH

A filter keeps intermediate state changes out of history (state.past) without affecting the live state. For drag-like continuous edits, excludeAction(['MOVE_CURSOR','UPDATE_OBJECT_POS']) records only the final committed state. And undo/redo in "reasonable chunks" needs deliberate custom filters + groupBy rather than recording every micro-action. This is the concrete recipe for de-noising autosave: gate out cosmetic/streaming edits, coalesce a burst into one entry. Sources: redux-undo.js.org/main/faq — primary; GitHub README. Votes 3-0 (×2), 2-1 (×1).

Confidence & caveats

• High confidence on every finding above (primary vendor docs; mostly unanimous 3-0 votes).
• Vendor-doc framing: Fusion's "non-destructive" language partly comes from Autodesk marketing blogs, but the mechanism (disable + recompute, marker preserves downstream) is independently corroborated by API docs and third parties — solid.
• Edge cases noted but not refuting: editing a far-upstream Fusion feature can break downstream dependency references (inherent to any dependency graph; the design is still never destroyed); Figma history retention is tier-bounded (30 days on free); redux-undo filter is technically a warning-context API, not an endorsement (the pattern still holds).
• Coverage gaps: DAW (Ableton/Logic), DaVinci/Premiere timeline scrubbing, Photoshop history, and Git-GUI detached-HEAD UX were searched but produced no separately verified surviving claims beyond what Final Cut Pro / Figma / Google Docs already cover. The FCP skimmer is the strongest scrubbing-ergonomics result.

Open questions

1. For a snapshot-per-state model (vs Fusion's parametric feature graph), should "jump back and edit" create a branch automatically, or keep the linear list and rely on non-destructive "Current" checkpoints? (Branching is currently hard-disabled in the build.)
2. What's the right auto-snapshot cadence — pure event-debounce (today: 3 s), a Figma-style time floor (e.g. ≥1 per N minutes), or both?
3. Should scrub/preview load the graph at all (expensive), or only show the SVG/thumbnail preview until the user explicitly commits — to keep back/forth instant on large graphs?

---

Part 2 — Implementation Plan

Each workstream cites concrete code in js/snapshot_manager.js. Ordered by impact; Must-have → Should-have → Nice-to-have.

Implementation status (2026-06-29)

Done (all four batches landed, 19/19 unit tests on the extracted diff logic pass):

• C1 + C2 — seedWorkflowBaseline() + suppressAutoCapture(SWITCH_GUARD_MS) on openWorkflow; scheduleCaptureSnapshot honours the suppression window.
• B1 — detectChangeType now classifies move/resize/collapse(+pin) as "cosmetic" and never lets a cosmetic flag escalate a real edit; mode (mute/bypass) treated as meaningful. _captureCore skips changeType==="cosmetic" for auto-captures (skipCosmetic).
• A1 + A3 — getLiveWidgetNames()/widgetNameFor() map widgets_values indices → names at capture; computeDetailedDiff/computeCaptureMetaDiff carry names; diff modal shows seed:/text: (meaningful first) and collapses position/size into one muted "Layout: moved, resized" line; tooltips read KSampler (seed, cfg).
• D1 + D3 — non-destructive jump confirmed (swap re-seeds hash + dedup → repeat steps are storage no-ops); stepToSnapshot() + Alt+◀ / Alt+▶ keyboard step nav with a quiet swap and a N/total · label position toast.

Deferred (nice-to-have, not yet built): A2 full Unreal-style color legend per change type; B2 time-based checkpoint floor; B3 Google-Docs "only show manual/named" filter; D2 drag-scrub skimmer mode (hover preview already exists); D4 explicit "return to where I was" affordance.

Pain-point ↔ finding map

Pain point	Backed by	Workstreams
Weak "what changed" info	F4, F5, F7	A
Spammy autosave	F5, F7, F8	B
WF-switch spams "now save"	(codebase bug) F6	C
Fusion-360 non-destructive feel	F1, F2, F3, F6	D

---

Workstream A — Semantic "what changed" (MUST) — F4, F5, F7

Problem (code): computeDetailedDiff (:565) compares widgets_values positionally and emits Value[6]: "a cat" → "a dog" (:1370). getGraphData() is app.graph.serialize() (:438), so at capture time the live app.graph._nodes[i].widgets[] array — each with a .name in the same order as widgets_values — is available but never used. detectChangeType (:454) only yields a coarse single bucket.

A1. Capture a widget index→name map (MUST). At capture in _captureCore (:1574), walk app.graph._nodes, build {nodeId: [widgetName,…]}, and use it so diffs read text:, seed:, cfg:, sampler_name: instead of Value[i]. Store a compact, named captureDiff (extend computeCaptureMetaDiff :697). Persisted per snapshot so old snapshots without it degrade gracefully to the current Value[i] form.

A2. Semantic change classification + Unreal-style legend (SHOULD). Replace the single changeType with a small set the user cares about: prompt, param (seed/cfg/sampler/steps/…), model (checkpoint/LoRA names), connection, node_add/node_remove, and a subordinate cosmetic (move/resize/collapse). Reuse CHANGE_TYPE_ICONS (:2755) with the red=removed / green=added / cyan=changed / grey=cosmetic palette (F4). Moves/resizes get the grey, de-emphasized treatment — exactly what you asked for.

A3. De-noise the diff modal + tooltip (SHOULD). In showDiffModal (:1232) and formatCaptureDiffLines (:720), put position/size/move rows in a collapsed "Cosmetic" section and surface prompt/param/model/connection changes first with their widget names. The hover tooltip headline should read e.g. ~ KSampler (seed, cfg) · + CLIPTextEncode rather than ~ 2 values.

Workstream B — Tame autosave noise (MUST) — F5, F7, F8

Problem (code): every graphChanged schedules a capture (:4236→scheduleCaptureSnapshot :1671, 3 s debounce). _captureCore only skips changeType === "move" (:1589), so resize and collapse/expand fall through as "unknown" and ARE saved as snapshots — pure visual noise. No floor on auto-snapshot frequency.

B1. Cosmetic-change gate (MUST). Generalize skipMove → skipCosmetic: skip auto-capture when the only changes are position/size/collapse/pin (redux-undo filter/excludeAction; Houdini Auto-take warning F5/F8). Manual snapshots (Ctrl+S :4297, Snapshot button :3901) and node-trigger captures still save everything. This alone removes most of the spam.

B2. Coalesce bursts; optional time floor (SHOULD). Keep the 3 s event-debounce (already coalesces a typing burst). Add an optional minimum interval between auto snapshots and/or a Figma-style time-based fallback checkpoint (F7), configurable via the existing settings (debounceSeconds lives at :4130).

B3. Make auto vs manual legible + filterable (NICE). Auto-snapshots already carry labels; borrow Google Docs' "Only show named/manual versions" filter (F7) in the sidebar so the auto stream can be hidden. The existing search/filter UI (:2934+) is the natural home.

Workstream C — Fix workflow-switch "now save" spam (MUST) — codebase bug, F6

Root cause (code): the openWorkflow handler (:4252) resets state and seeds lastCapturedIdMap for the new tab but never seeds lastCapturedHashMap / lastGraphData for it. ComfyUI's loadGraphData for the freshly-opened workflow then fires graphChanged → scheduleCaptureSnapshot → 3 s later captureSnapshot("Auto") runs, finds no seeded hash, can't dedupe, and saves a redundant snapshot of a workflow you only just opened.

C1. Re-seed hash on switch (MUST). In the openWorkflow after() block (:4255), after the new graph is live, set lastCapturedHashMap/setLastGraphData for newKey (mirror the setup seeding at :4309-4322). The post-load graphChanged then dedupes to a no-op.

C2. Programmatic-load suppression window (MUST). Add a short-lived loadingLock flag (sibling to restoreLock :35/:1170) set around tab switches and snapshot loads so scheduleCaptureSnapshot (:1671) ignores the graphChanged events that we caused. Belt-and-suspenders with C1.

Workstream D — Fusion-360 non-destructive navigation (SHOULD) — F1, F2, F3, F6

Problem (code): every timeline marker click calls swapSnapshot(rec) (:3955), which captureSnapshot("Current") before loading (:1728). So navigating is what generates "now save" and it feels destructive. There's no prev/next step nav and the current-position indicator is subtle.

D1. Non-destructive jump = checkpoint-once-then-load (SHOULD). Adopt Figma's model (F6): when leaving a dirty live state, capture the pre-jump state once (already hash-deduped, so browsing between saved states is a no-op), then load the target. Confirm/tighten that repeated back/forth between existing snapshots creates zero new "Current" snapshots. Never delete later snapshots (we already don't) — that's the non-destructive guarantee (F1).

D2. Preview vs commit — skimmer pattern (SHOULD). The hover tooltip already previews via SVG/thumbnail (:3793). Lean into it: hovering = preview (skimmer), clicking = commit (playhead) (F3). Optionally a "scrub" mode where dragging along the timeline updates only the preview, and you commit on release — keeps back/forth instant on big graphs (open question 3).

D3. Prev/Next step + clear current marker (SHOULD). Add keyboard step navigation ([ / ] or arrow keys) and Fusion-style playback buttons (begin/prev/next/end) to the timeline (buildTimeline :3869), cycling snapshots one at a time (Unreal Next/Prev F4; Fusion controls F2). Strengthen the current-position indicator (marker-current/marker-active :3940) so "where am I" is obvious.

D4. "Return to where I was" (NICE). Remember the snapshot you were on before scrubbing and offer a one-click jump back (FCP playhead F3; Houdini go-back-and-forth F5). Lightweight: a single preScrubSnapshotId + a "↩ return" affordance.

---

Suggested sequencing

1. C1 + C2 (kill wf-switch spam) — small, isolated, immediate relief.
2. B1 (cosmetic gate) — biggest reduction in autosave noise, low risk.
3. A1 + A3 (named semantic diffs) — the "what changed" payoff you asked for.
4. D1 + D3 (non-destructive jump + step nav) — the Fusion-360 feel.
5. A2, B2/B3, D2, D4 — polish / configurable refinements.

Risks

• Widget-name mapping (A1) depends on live _nodes/widgets internals — guard for nodes whose widget count ≠ widgets_values length and for headless/serialize-only paths.
• The cosmetic gate (B1) must not swallow a meaningful change that co-occurs with a move — gate only when changes are exclusively cosmetic.
• Suppression window (C2) must auto-release even if a load throws (mirror withRestoreLock :1170).