One preview per write, and a Refresh on the sequence flipbook

A written sequence came back with TWO previews on the node: the flipbook of the
real frames, and an H.264 proxy of the same frames beside it. Both branches ran,
because the flipbook was added alongside the proxy instead of in front of it.
They do not agree - the proxy is 8-bit and carries no colour conversion, so it
reads darker than the frames it claims to preview - and nothing on the node said
which one was the master. Reading colour off the wrong one is the failure this
pack exists to prevent.

The proxy is now the fallback it was meant to be: it ships only when the frame
range cannot be described. A movie still gets it and no flipbook, because a
container file has no range to scrub. A single frame still gets its own PNG
thumb and nothing that pretends to move.

The flipbook gains the persistent top-left Refresh square OCIO Player already
carries, for when the files on disk change under a preview that is already drawn.
It busts the browser cache, since every frame URL is otherwise byte-identical
from one pass to the next and the button would do nothing visible. A frame that
will not load now replaces the strip with the folder path instead of freezing on
the last good frame.

OV_BASE / OV_STALE move to module scope. They were local to the Player's setup
function, and the flipbook's button - defined hundreds of lines above it - read
them at runtime and would have thrown ReferenceError. node --check passes either
way, because a name is only resolved when the code runs.

tools/test_write_preview_single.py reads the preview counts off a real write of
all three containers. Mutation-checked: forcing the proxy back onto the sequence
branch turns it red on the right assertion, and green again when reverted.

Gate 37 passed / 0 failed (baseline 36/0, +1 the new test).

.gitignore picks up the renders the example graphs produce. The .json workflows
there ship; what comes out of running them does not, and a stray blanket add
would otherwise sweep them into a public repository. Deliberately not *.png:
nyc_skyline.png is a tracked input those graphs load.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: SlavaSextron

.gitignore

@@ -13,3 +13,15 @@ data/
 # local working dirs - never publish (logs and artifacts can carry paths and names from other work)
 scratchpad/
 .agents/
+
+# Renders made while testing the example graphs. The .json workflows in example_workflows/ DO ship; what
+# comes out of running them does not - they are large, anyone who runs the graph regenerates them, and a
+# stray `git add -A` would otherwise sweep them into a public repository.
+#
+# NOT *.png: example_workflows/nyc_skyline.png is a tracked input the example graphs load, and a blanket rule
+# there would read as "we do not ship pictures from this folder", which is false.
+example_workflows/output/
+example_workflows/*.mp4
+example_workflows/*.mov
+example_workflows/*.exr
+probe.mp4

CHANGELOG.md

@@ -79,8 +79,23 @@ even when it fits: 912 s against 60 s over 121 frames at float32. Saved graphs a
 their own value.
 
 A `sequence` write showed one still frame, because every format that branch writes is one a browser cannot
-animate. It now shows a playing clip, and hands the front end the written frames' path and range so a future
-version can flip through the real files rather than an H.264 proxy.
+animate. It now plays back **the written frames themselves**: the node gets their path and range, and the
+front end flips through them the way OCIO Read already does, one server-rendered frame at a time through
+`/ocio/thumb`. `thumb_frame` reads them with `_read_still`, the same reader OCIO Read uses, so every format
+this branch can write is one the flipbook can serve back.
+
+There is a persistent `↻` in the strip's top-left corner, the same square OCIO Player carries, for when the
+frames on disk change under a preview that is already drawn - a re-render into the same folder, a retake from
+another graph. It re-reads them from disk rather than from the browser's cache. If a frame will not load, the
+strip is replaced by the folder path instead of freezing on the last good frame.
+
+**One preview, not two.** The first cut of this shipped the flipbook *and* the H.264 proxy, so a written
+sequence came back with two previews on one node - the real frames, and a darker 8-bit copy of them
+disagreeing about colour, with nothing to say which was the master. An artist reading colour off the wrong one
+is the whole failure this pack exists to prevent. The proxy is now the fallback it was meant to be: it ships
+only when the flipbook cannot be described. A movie still gets the proxy and no flipbook, because a container
+file has no frame range to scrub; a single frame still gets its own PNG thumb and nothing that pretends to
+move. `tools/test_write_preview_single.py` reads the counts off a real write of each of the three.
 
 ## A tool that checks the installed copy against the repository
 

docs/NODES_IO.md

@@ -441,7 +441,18 @@ writes - EXR, DPX, TIFF, PNG - is one a browser either cannot decode or cannot a
 to come back as a single still. It now flips through the written files, each rendered server-side through
 OCIO by the same `/ocio/thumb` route `OCIO Read`'s viewer uses. That matters for a pack whose argument is
 that it does not throw information away: an 8-bit re-encode is a poor way to show frames just written at 16
-or 32 bits. The H.264 proxy stays alongside as the fallback.
+or 32 bits.
+
+The H.264 proxy is the **fallback**, not a companion: it ships only when the frame range cannot be described,
+so exactly one preview appears on the node. Both at once meant two pictures of the same write disagreeing
+about colour, with nothing on the node to say which was the master.
+
+The `↻` in the strip's top-left re-reads the frames from disk, bypassing the browser's cache. Use it when
+something else has written into that folder since - another graph, a retake, a re-render - and you want to be
+sure you are looking at what is there now. The colorspace the strip renders through is the one that was on
+the node when the write ran, so a later widget edit cannot make the picture disagree with the files. If a
+frame cannot be read back, the strip is replaced by the folder path rather than freezing on the last good
+frame.
 
 No audio on the sequence path even when a track is wired, because a frame sequence carries none, and a
 preview that played sound the files do not have would misrepresent what was produced.

io_nodes.py

@@ -4038,28 +4038,36 @@ def tc_text(offset):
             # player. The video branch already solved this for its own case, and the same helper works here: a
             # small H.264 copy in the temp dir, played on the node. The master on disk is untouched.
             #
-            # No audio on this path even when a track is wired: a frame sequence carries none, and a preview that
-            # plays sound the written files do not have would misrepresent what was produced.
-            ui["images"] = self._video_preview(written, fps, saved)
-            ui["animated"] = (True,)
-            # AND THE FILES THEMSELVES, so the front end can flip through the real frames instead of an H.264
-            # proxy. OCIO Read already does this: /ocio/thumb renders ONE frame server-side through OCIO and
-            # the browser runs a Nuke-style flipbook over a blob cache, which is why a colorspace change there
-            # is exact rather than approximate. The proxy above stays as the fallback - it needs no round trip
-            # and works before any of this is wired - but a pack about colour should be able to show the
-            # frames it actually wrote, at their real depth, not a 8-bit copy of them.
+            # THE FRAMES THEMSELVES, so the front end flips through what was written instead of an H.264 copy of
+            # it. OCIO Read already does this: /ocio/thumb renders ONE frame server-side through OCIO and the
+            # browser runs a Nuke-style flipbook over it, which is why a colorspace change there is exact rather
+            # than approximate. A pack about colour should show the frames it actually wrote, at their real
+            # depth. thumb_frame reads them with _read_still, the same reader OCIO Read uses, so every still
+            # format this branch can write is one the flipbook can serve back.
             #
             # The path is the written sequence's own directory pattern, and the range is the frame numbers on
             # disk, so the viewer and the master cannot disagree about which frames exist.
+            flip = False
             try:
                 first_written = paths[0] if paths else None
                 if first_written:
                     ui["seq_src"] = [os.path.dirname(first_written)]
                     ui["seq_first"] = [int(start_number)]
                     ui["seq_last"] = [int(start_number) + int(written.shape[0]) - 1]
                     ui["seq_fps"] = [float(fps) if fps and fps > 0 else 24.0]
+                    flip = True
             except Exception as e:                       # a preview must never take the write down with it
                 logging.warning("OCIO Write: could not describe the sequence for the flipbook: %s", e)
+            if not flip:
+                # Only when the flipbook could NOT be described. Shipping both put TWO previews on one node
+                # (2026-08-15) - the real frames above a darker 8-bit copy of them, disagreeing about colour,
+                # with nothing to say which was the master. The proxy stays as the fallback because it needs no
+                # round trip, but it is a fallback, not a companion.
+                #
+                # No audio on this path even when a track is wired: a frame sequence carries none, and a preview
+                # that plays sound the written files do not have would misrepresent what was produced.
+                ui["images"] = self._video_preview(written, fps, saved)
+                ui["animated"] = (True,)
         else:
             ui["images"] = self._preview(preview)
         return {"ui": ui, "result": (saved,)}

tools/test_write_preview_single.py

@@ -0,0 +1,117 @@
+"""Regression: OCIO Write shows exactly ONE preview per write (run: python tools/test_write_preview_single.py).
+
+A written sequence got TWO previews on the node (2026-08-15): the flipbook of the real frames, and above/below
+it an H.264 proxy of the same frames. They do not agree - the proxy is 8-bit and carries no colour conversion,
+so it reads darker than the frames it claims to preview - and nothing on the node says which one is the master.
+An artist reading colour off the wrong one is the whole failure this pack exists to prevent.
+
+Neither preview was wrong on its own; shipping both was. So the rule under test is a COUNT, not a value:
+
+1. A SEQUENCE ships the flipbook (seq_src + range + fps) and NO proxy. thumb_frame reads the written frames
+   with _read_still, the same reader OCIO Read uses, so every still format this branch writes is one the
+   flipbook can serve back - the proxy has nothing left to add.
+
+2. A VIDEO still ships the proxy, and no flipbook. A movie is one file, not a numbered range; /ocio/thumb can
+   only hand back its FIRST frame, so a flipbook there would be a still pretending to be a clip.
+
+3. A SINGLE-FRAME sequence ships neither. One frame is a still: the node's own thumb already shows it, and an
+   H.264 clip of one frame is a video that cannot move.
+
+The counts are read off the real return of OCIOWrite.write(), not from the source text - a preview key that is
+merely PRESENT in the file proves nothing about which branch sets it.
+"""
+import importlib.util
+import os
+import sys
+import tempfile
+import types
+
+os.environ.setdefault("OPENCV_IO_ENABLE_OPENEXR", "1")
+
+_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def _load_io_nodes(tmp):
+    fp = types.ModuleType("folder_paths")
+    fp.get_output_directory = fp.get_temp_directory = fp.get_input_directory = lambda: tmp
+    fp.get_filename_list = lambda *a, **k: []
+    sys.modules.setdefault("folder_paths", fp)
+    pkg = types.ModuleType("ocio_pkg")
+    pkg.__path__ = [_ROOT]
+    sys.modules["ocio_pkg"] = pkg
+    for name in ("nodes", "io_nodes"):
+        spec = importlib.util.spec_from_file_location(f"ocio_pkg.{name}", os.path.join(_ROOT, f"{name}.py"))
+        mod = importlib.util.module_from_spec(spec)
+        sys.modules[f"ocio_pkg.{name}"] = mod
+        spec.loader.exec_module(mod)
+    return sys.modules["ocio_pkg.io_nodes"]
+
+
+def _write(io, frames, **kw):
+    import torch
+    imgs = torch.zeros((frames, 6, 8, 3))
+    imgs[..., 0], imgs[..., 1], imgs[..., 2] = 0.40, 0.60, 0.10
+    args = dict(profile="none", from_colorspace="sRGB - Display", output_colorspace="ACEScg",
+                container="sequence", still_format="exr", video_codec="prores_4444", bit_depth="16f",
+                auto_range=False, first_frame=1, last_frame=0, start_number=1001, source_start=1,
+                raw_data=False, filename="prev", fps=23.976, images=imgs)
+    args.update(kw)
+    res = io.OCIOWrite().write(**args)
+    return (res or {}).get("ui", {}) or {}
+
+
+def check_sequence_is_flipbook_only(io):
+    """A multi-frame sequence: the real frames, and nothing standing beside them."""
+    ui = _write(io, 3, output_folder="$OUTPUT/seq3")
+    assert "seq_src" in ui, f"a 3-frame sequence lost its flipbook; ui keys were {sorted(ui)}"
+    assert "images" not in ui and "animated" not in ui, (
+        f"TWO previews on one node: the flipbook AND the H.264 proxy; ui keys were {sorted(ui)}")
+    # The range has to describe the files that exist, or the flipbook asks /ocio/thumb for frames it will 404 on.
+    first, last = int(ui["seq_first"][0]), int(ui["seq_last"][0])
+    assert (first, last) == (1001, 1003), f"flipbook range {first}..{last} does not match the 3 frames written"
+    folder = ui["seq_src"][0]
+    on_disk = sorted(f for f in os.listdir(folder) if f.endswith(".exr"))
+    assert len(on_disk) == 3, f"flipbook points at {folder}, which holds {on_disk}"
+    assert float(ui["seq_fps"][0]) > 0, "a flipbook with no rate plays at whatever the browser feels like"
+
+
+def check_video_is_proxy_only(io):
+    """A movie: the proxy, and no flipbook - /ocio/thumb cannot scrub a single container file."""
+    ui = _write(io, 3, container="video", video_codec="h264", output_folder="$OUTPUT/mov")
+    assert "images" in ui and "animated" in ui, f"a movie lost its playable preview; ui keys were {sorted(ui)}"
+    assert "seq_src" not in ui, (
+        f"a movie was handed a frame-range flipbook it cannot serve; ui keys were {sorted(ui)}")
+
+
+def check_single_frame_has_no_clip(io):
+    """One frame is a still: its own PNG thumb, and nothing that pretends to move.
+
+    `images` IS expected here and is not the proxy - it is _preview(), a static PNG of the first written frame.
+    What must not appear is `animated` (an H.264 clip of one frame) or `seq_src` (a range of one).
+    """
+    ui = _write(io, 1, output_folder="$OUTPUT/one")
+    assert "seq_src" not in ui, f"a single frame was described as a flipbook; ui keys were {sorted(ui)}"
+    assert "animated" not in ui, f"a single frame was given a moving preview; ui keys were {sorted(ui)}"
+    assert "images" in ui, f"a single frame lost its still thumb; ui keys were {sorted(ui)}"
+
+
+def main():
+    tmp = tempfile.mkdtemp(prefix="ocio_prev_")
+    io = _load_io_nodes(tmp)
+    failures = []
+    for fn in (check_sequence_is_flipbook_only, check_video_is_proxy_only, check_single_frame_has_no_clip):
+        try:
+            fn(io)
+            print(f"  ok  {fn.__name__}")
+        except AssertionError as e:
+            failures.append(f"{fn.__name__}: {e}")
+            print(f"  FAIL {fn.__name__}: {e}")
+    if failures:
+        print(f"\n{len(failures)} failure(s)")
+        return 1
+    print("\nOCIO Write shows exactly one preview per container: OK")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

web/ocio_io.js

@@ -32,6 +32,12 @@ function setWSilent(node, name, value) {
     w.value = value;
     node.setDirtyCanvas(true, true);
 }
+// Overlay chrome for every persistent Refresh square in this file (OCIO Player's viewport, OCIO Write's
+// flipbook). MODULE level on purpose: these were local to the Player's setup function, and the flipbook's
+// button - defined hundreds of lines above it - read them at runtime and would have thrown ReferenceError.
+// node --check passes either way, because a name is only resolved when the code runs.
+const OV_BASE = "rgba(40,40,64,0.85)", OV_STALE = "rgba(150,95,20,0.92)";
+
 function extOf(name) { return (String(name || "").toLowerCase().split(".").pop() || ""); }
 function isExr(name) { const e = extOf(name); return e === "exr" || e === "hdr"; }
 function shorten(cs) { return String(cs || "").replace(" - Display", "").replace(" - Texture", ""); }
@@ -198,13 +204,18 @@ function crossingOf(enc, fromCs, outCs) {
 // Deliberately simpler than Read's player in two ways. It prefetches nothing: a write has already finished,
 // so the frames are on a local disk and warm, where Read is often scrubbing a 4K plate it has never touched.
 // And it has no scrub bar, because there is nothing to choose - a write shows what it wrote, start to end.
-function writeThumbUrl(seq, frameNo) {
-    return "/ocio/thumb?" + new URLSearchParams({
+function writeThumbUrl(seq, frameNo, bust) {
+    const q = {
         src: seq.src, frame: String(frameNo),
         in_cs: seq.cs,                 // what the FILE holds
         out_cs: CS_SRGB,               // what a browser can show
         raw: "0", full: "0",
-    }).toString();
+    };
+    // Refresh has to reach DISK, and every frame URL here is byte-identical from one pass to the next, so the
+    // browser would serve the whole strip from its own cache and the button would do nothing visible. The
+    // counter changes the URL without changing what is asked for.
+    if (bust) q._ = String(bust);
+    return "/ocio/thumb?" + new URLSearchParams(q).toString();
 }
 
 function startWriteFlipbook(node) {
@@ -213,17 +224,41 @@ function startWriteFlipbook(node) {
     let w = (node.widgets || []).find(x => x.name === "__ocio_flip");
     if (!w) {
         const el = document.createElement("div");
-        el.style.cssText = "width:100%;display:flex;align-items:center;justify-content:center;min-height:80px";
+        el.style.cssText = "position:relative;width:100%;display:flex;align-items:center;justify-content:center;min-height:80px";
         const img = document.createElement("img");
         img.style.cssText = "max-width:100%;max-height:220px;image-rendering:auto";
         el.appendChild(img);
+        // Same persistent top-left square as OCIO Player's viewport, and for the same reason: the frames on
+        // disk can change under a preview that is already drawn (a re-render into the same folder, a retake
+        // from another graph), and the only honest way back is to re-read them.
+        const rf = document.createElement("button");
+        rf.textContent = "↻";
+        rf.title = "Re-read the written frames from disk";
+        rf.style.cssText = "position:absolute;top:6px;left:6px;z-index:5;width:26px;height:26px;padding:0;border:0;border-radius:4px;background:" + OV_BASE + ";color:#cde;cursor:pointer;font:16px/1 sans-serif;box-shadow:0 1px 4px rgba(0,0,0,0.5);";
+        rf.onmouseenter = () => rf.style.background = "rgba(57,57,90,0.95)";
+        rf.onmouseleave = () => rf.style.background = OV_BASE;
+        rf.onclick = () => { node._ocioFlipBust = Date.now(); startWriteFlipbook(node); };
+        el.appendChild(rf);
+        // A note that replaces the strip when a frame will not load, rather than leaving the last good frame up
+        // and the timer running - a preview that silently freezes on a stale frame is worse than no preview.
+        const err = document.createElement("div");
+        err.style.cssText = "display:none;padding:10px;color:#e6a;font:12px sans-serif;text-align:center";
+        el.appendChild(err);
         w = node.addDOMWidget("__ocio_flip", "div", el, { serialize: false });
-        w._img = img;
+        w._img = img; w._err = err;
     }
     if (node._ocioFlipTimer) clearInterval(node._ocioFlipTimer);
+    w._err.style.display = "none"; w._img.style.display = "";
+    w._img.onerror = () => {
+        if (node._ocioFlipTimer) clearInterval(node._ocioFlipTimer);
+        node._ocioFlipTimer = null;
+        w._img.style.display = "none";
+        w._err.textContent = "cannot read the written frames back for preview - they are on disk at " + seq.src;
+        w._err.style.display = "";
+    };
     let i = seq.first;
     const show = () => {
-        w._img.src = writeThumbUrl(seq, i);
+        w._img.src = writeThumbUrl(seq, i, node._ocioFlipBust);
         i = (i >= seq.last) ? seq.first : i + 1;
     };
     show();
@@ -2327,7 +2362,6 @@ function ensurePlayer(node) {
     // so the viewport can be re-pulled anywhere - not just in video mode. Normally slate;
     // turns amber (._stale) when a node was inserted / rewired upstream so the cached frames are stale, until the next
     // render clears it. onClick: video upstream -> re-read the file; else Queue (OCIOPlayer is an OUTPUT_NODE viewer).
-    const OV_BASE = "rgba(40,40,64,0.85)", OV_STALE = "rgba(150,95,20,0.92)";
     const refreshOverlay = document.createElement("button");
     refreshOverlay.textContent = "↻";
     refreshOverlay.title = "Refresh this viewport";