transcript-viewer 0.6.0__tar.gz → 0.6.1__tar.gz

transcript_viewer-0.6.0/README.md → transcript_viewer-0.6.1/PKG-INFO

@@ -1,3 +1,16 @@
+Metadata-Version: 2.5
+Name: transcript-viewer
+Version: 0.6.1
+Summary: Browse agent transcripts in a local, dependency-free web viewer.
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: atif-make>=0.5.0
+Provides-Extra: ai
+Requires-Dist: anthropic>=0.40; extra == 'ai'
+Provides-Extra: parquet
+Requires-Dist: atif-make[parquet]>=0.5.0; extra == 'parquet'
+Description-Content-Type: text/markdown
+
 # transcript-viewer
 
 Browse agent transcripts in a local web viewer — what Claude Code, Codex and
@@ -13,9 +26,15 @@ anything to change in the viewer.
 ## Install
 
 ```sh
-uv tool install transcript-viewer        # pulls atif-make automatically
+uv tool install transcript-viewer                    # pulls atif-make automatically
+uv tool install "transcript-viewer[parquet]"         # + datasets published as Parquet
+uv tool install "transcript-viewer[ai,parquet]"      # + the optional Claude features
 ```
 
+The extras are only needed for what they name: `parquet` for a dataset that
+ships as Parquet rather than JSON, `ai` for the summarise and ask features. The
+viewer works without either.
+
 ```sh
 transcript-viewer                        # the library, empty on a first run
 transcript-viewer path/to/session.jsonl  # one log
@@ -395,7 +414,11 @@ The page is a file rather than a string inside `viewer.py`, which is where it
 used to live. Two thirds of that module was CSS and JavaScript typed as though
 it were Python — a template expression once shipped inside static HTML and
 rendered its own source, which is harder to miss in a file that knows what it
-is. It is read once at import and served from memory, and the wheel carries it.
+is. It is re-read whenever it changes, so editing the interface and reloading
+shows the edit — twice it did not, and read as an edit that had failed. The
+cost is a stat per page load, and none on what the page then calls; for an
+installed copy the file never changes and the stat always says so. The wheel
+carries it.
 
 ## Tests
 
@@ -411,7 +434,8 @@ uv run --with-editable ../atif-make pytest
 ```
 
 Add `--extra ai` to either command to exercise the AI paths against a real SDK;
-the tests stub the model call, so this never contacts the API.
+the tests stub the model call, so this never contacts the API. `--extra parquet`
+does the same for the Parquet path, which is otherwise skipped.
 
 The suite starts a real server on an ephemeral port and exercises the endpoints,
 including that it binds loopback only. It is isolated from your own library,

transcript_viewer-0.6.0/PKG-INFO → transcript_viewer-0.6.1/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.5
-Name: transcript-viewer
-Version: 0.6.0
-Summary: Browse agent transcripts in a local, dependency-free web viewer.
-License: MIT
-Requires-Python: >=3.12
-Requires-Dist: atif-make>=0.5.0
-Provides-Extra: ai
-Requires-Dist: anthropic>=0.40; extra == 'ai'
-Provides-Extra: parquet
-Requires-Dist: atif-make[parquet]>=0.5.0; extra == 'parquet'
-Description-Content-Type: text/markdown
-
 # transcript-viewer
 
 Browse agent transcripts in a local web viewer — what Claude Code, Codex and
@@ -26,9 +13,15 @@ anything to change in the viewer.
 ## Install
 
 ```sh
-uv tool install transcript-viewer        # pulls atif-make automatically
+uv tool install transcript-viewer                    # pulls atif-make automatically
+uv tool install "transcript-viewer[parquet]"         # + datasets published as Parquet
+uv tool install "transcript-viewer[ai,parquet]"      # + the optional Claude features
 ```
 
+The extras are only needed for what they name: `parquet` for a dataset that
+ships as Parquet rather than JSON, `ai` for the summarise and ask features. The
+viewer works without either.
+
 ```sh
 transcript-viewer                        # the library, empty on a first run
 transcript-viewer path/to/session.jsonl  # one log
@@ -408,7 +401,11 @@ The page is a file rather than a string inside `viewer.py`, which is where it
 used to live. Two thirds of that module was CSS and JavaScript typed as though
 it were Python — a template expression once shipped inside static HTML and
 rendered its own source, which is harder to miss in a file that knows what it
-is. It is read once at import and served from memory, and the wheel carries it.
+is. It is re-read whenever it changes, so editing the interface and reloading
+shows the edit — twice it did not, and read as an edit that had failed. The
+cost is a stat per page load, and none on what the page then calls; for an
+installed copy the file never changes and the stat always says so. The wheel
+carries it.
 
 ## Tests
 
@@ -424,7 +421,8 @@ uv run --with-editable ../atif-make pytest
 ```
 
 Add `--extra ai` to either command to exercise the AI paths against a real SDK;
-the tests stub the model call, so this never contacts the API.
+the tests stub the model call, so this never contacts the API. `--extra parquet`
+does the same for the Parquet path, which is otherwise skipped.
 
 The suite starts a real server on an ephemeral port and exercises the endpoints,
 including that it binds loopback only. It is isolated from your own library,

{transcript_viewer-0.6.0 → transcript_viewer-0.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "transcript-viewer"
-version = "0.6.0"
+version = "0.6.1"
 description = "Browse agent transcripts in a local, dependency-free web viewer."
 readme = "README.md"
 requires-python = ">=3.12"

{transcript_viewer-0.6.0 → transcript_viewer-0.6.1}/src/transcript_viewer/library.py

@@ -51,17 +51,49 @@ def _now() -> str:
     return datetime.now(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
 
 
-def load(path: Path | None = None) -> dict[str, dict]:
-    """Every annotation, by key. A missing or damaged file reads as empty."""
-    data = store.read_json(path or LIBRARY_PATH)
+# What was parsed, and the state of the file it came from. The library is read
+# far more often than it is written — a page load asks about every session in
+# it — and it grows with the corpus, so parsing a megabyte of JSON per question
+# is the difference between a page appearing and a page taking four seconds.
+_parsed: tuple[int, int, dict[str, dict]] | None = None
+
+
+def _read(path: Path) -> dict[str, dict]:
+    data = store.read_json(path)
     entries = data.get("entries")
     if not isinstance(entries, dict):
         return {}
     return {k: v for k, v in entries.items() if isinstance(v, dict)}
 
 
+def load(path: Path | None = None) -> dict[str, dict]:
+    """Every annotation, by key. A missing or damaged file reads as empty.
+
+    The real library is cached against its own timestamp and size, so a change
+    made by anything — this process or another — is picked up on the next read.
+    A caller gets its own outer dict, since `remove` pops from what it is given
+    and callers should not be able to edit the cache by accident.
+    """
+    global _parsed
+    path = path or LIBRARY_PATH
+    if path != LIBRARY_PATH:
+        return _read(path)
+
+    try:
+        info = path.stat()
+        stamp = (info.st_mtime_ns, info.st_size)
+    except OSError:
+        return _read(path)
+
+    if _parsed is None or (_parsed[0], _parsed[1]) != stamp:
+        _parsed = (stamp[0], stamp[1], _read(path))
+    return dict(_parsed[2])
+
+
 def save(entries: dict[str, dict], path: Path | None = None) -> None:
     """Write the whole library atomically."""
+    global _parsed
+    _parsed = None  # the next read re-stamps against the file just written
     store.write_json(path or LIBRARY_PATH, {"version": VERSION, "entries": entries})
 
 

{transcript_viewer-0.6.0 → transcript_viewer-0.6.1}/src/transcript_viewer/page.html

@@ -430,8 +430,33 @@ pre.json{line-height:1.45}
 .more button{border:1px solid var(--line);background:var(--panel);color:var(--dim);border-radius:999px;
   padding:8px 18px;font:inherit;font-size:12.5px;cursor:pointer}
 .more button:hover{background:var(--sunk);color:var(--ink)}
+
+/* Shown only if opening takes long enough to notice — a library of a few
+   thousand sessions is a couple of megabytes, and a blank window while that
+   arrives reads as broken rather than busy. */
+#boot{position:fixed;inset:0;z-index:60;display:flex;flex-direction:column;
+  align-items:center;justify-content:center;gap:14px;background:var(--bg)}
+#boot[hidden]{display:none}
+#bootbar{width:min(320px,52vw);height:3px;border-radius:3px;background:var(--line);
+  overflow:hidden}
+#bootbar i{display:block;height:100%;width:0;border-radius:3px;background:var(--accent);
+  transition:width .18s ease-out}
+/* Nothing to measure yet: sweep rather than sit at zero, which reads as stuck. */
+#bootbar.waiting i{width:35%;animation:sweep 1.1s ease-in-out infinite}
+@keyframes sweep{0%{transform:translateX(-100%)}100%{transform:translateX(320%)}}
+#boottext{margin:0;font:12px/1.5 var(--font-mono);color:var(--muted);
+  letter-spacing:.02em;text-align:center;padding:0 20px}
+@media (prefers-reduced-motion:reduce){
+  #bootbar i{transition:none}
+  #bootbar.waiting i{animation:none;width:100%;opacity:.5}
+}
 </style>
 
+<div id="boot" hidden>
+  <div id="bootbar"><i></i></div>
+  <p id="boottext">Opening your library…</p>
+</div>
+
 <header id="top">
   <span class="mark">Transcript Viewer</span>
   <div id="crumb"></div>
@@ -932,10 +957,77 @@ addEventListener("keydown",e=>{
   if(e.key==="\\"&&e.target.tagName!=="INPUT"){e.preventDefault();toggleSide()}
 });
 
-fetch("/api/index").then(r=>r.json()).then(d=>{
-  INDEX=d.sessions||[];GROUPS=d.groups||[];TAGS=d.tags||[];AI=d.ai||{};DOWNLOADS=d.downloads||DOWNLOADS;
-  count.textContent=INDEX.length+" sessions";drawList();showLibrary();
-});
+/* Opening the library has three parts worth naming: waiting for the server to
+   answer, reading the answer, and drawing it. Held back briefly so a fast open
+   does not flash a bar at you. */
+const boot={el:null,bar:null,text:null,timer:0};
+
+function bootShow(){
+  boot.el=document.getElementById("boot");
+  boot.bar=document.getElementById("bootbar");
+  boot.text=document.getElementById("boottext");
+  if(!boot.el)return;
+  boot.timer=setTimeout(()=>{if(boot.el.hidden)boot.el.hidden=false},160);
+}
+
+function bootSay(what,done,total){
+  if(boot.text)boot.text.textContent=what;
+  if(!boot.bar)return;
+  if(total>0){
+    boot.bar.classList.remove("waiting");
+    boot.bar.firstElementChild.style.width=Math.min(100,done/total*100)+"%";
+  }else{
+    boot.bar.classList.add("waiting");
+  }
+}
+
+function bootDone(){
+  clearTimeout(boot.timer);
+  if(boot.el)boot.el.hidden=true;
+}
+
+/* Read the response as it arrives, so the bar tracks real bytes rather than
+   guessing at them. Without a length to measure against it sweeps instead of
+   claiming progress it cannot know. */
+async function readIndex(){
+  const response=await fetch("/api/index");
+  if(!response.ok)throw new Error("the server answered "+response.status);
+  const total=Number(response.headers.get("Content-Length")||0);
+  if(!response.body||!total)return response.json();
+
+  const reader=response.body.getReader();
+  const chunks=[];let done=0;
+  for(;;){
+    const piece=await reader.read();
+    if(piece.done)break;
+    chunks.push(piece.value);done+=piece.value.length;
+    bootSay("Reading your library… "+bytes(done)+" of "+bytes(total),done,total);
+  }
+  const joined=new Uint8Array(done);let at=0;
+  for(const chunk of chunks){joined.set(chunk,at);at+=chunk.length}
+  bootSay("Making sense of it…",0,0);
+  return JSON.parse(new TextDecoder().decode(joined));
+}
+
+async function openLibrary(){
+  bootShow();
+  bootSay("Looking for your sessions…",0,0);
+  try{
+    const d=await readIndex();
+    INDEX=d.sessions||[];GROUPS=d.groups||[];TAGS=d.tags||[];AI=d.ai||{};DOWNLOADS=d.downloads||DOWNLOADS;
+    bootSay("Drawing "+INDEX.length+" sessions…",0,0);
+    // Let that line paint before the work that blocks the thread.
+    await new Promise(r=>requestAnimationFrame(()=>requestAnimationFrame(r)));
+    count.textContent=INDEX.length+" sessions";drawList();showLibrary();
+  }catch(err){
+    // Leave it on screen: a blank window would say nothing at all.
+    bootSay("Could not open your library — "+((err&&err.message)||err),0,0);
+    return;
+  }
+  bootDone();
+}
+
+openLibrary();
 q.oninput=drawList;
 
 /* Diwan's collectionTree builds a forest carrying depth, then flattens it

{transcript_viewer-0.6.0 → transcript_viewer-0.6.1}/src/transcript_viewer/viewer.py

@@ -35,7 +35,33 @@ from . import ai, config, fetch, library
 # The page is a real .html file rather than a string in here: it is 2,232 lines
 # of CSS and JavaScript, which is not Python and should not be typed as though
 # it were. Read once at import, and served from memory.
-PAGE = (Path(__file__).parent / "page.html").read_text(encoding="utf-8")
+PAGE_PATH = Path(__file__).parent / "page.html"
+
+# What was read, and the state of the file it was read from.
+_page: tuple[float, int, str] | None = None
+
+
+def page() -> str:
+    """The interface, re-read when the file behind it changes.
+
+    The whole interface is that one file, so editing it and seeing nothing
+    change until the server is restarted reads as the edit not having worked.
+    Twice now it has. The cost is one stat per page load — not per request, and
+    not on anything the page then calls — and for an installed copy, where the
+    file never changes, it is a stat that always says the same thing.
+    """
+    global _page
+    try:
+        info = PAGE_PATH.stat()
+        stamp = (info.st_mtime, info.st_size)
+    except OSError:
+        # If it cannot be stat'd, what was already read is better than nothing.
+        if _page is not None:
+            return _page[2]
+        raise
+    if _page is None or (_page[0], _page[1]) != stamp:
+        _page = (stamp[0], stamp[1], PAGE_PATH.read_text(encoding="utf-8"))
+    return _page[2]
 
 
 def _point_images_at_server(trajectory: Trajectory, index: str) -> None:
@@ -305,7 +331,7 @@ class _Handler(BaseHTTPRequestHandler):
         return {
             e.key
             for e in self.entries
-            if (at := _group(e, library.get(e.key).get("source", "")))
+            if (at := _group(e, library.load().get(e.key, {}).get("source", "")))
             and (at == name or at.startswith(f"{name}/"))
         }
 
@@ -828,10 +854,13 @@ class _Handler(BaseHTTPRequestHandler):
         url = urlparse(self.path)
 
         if url.path == "/":
-            self._send(PAGE.encode(), "text/html; charset=utf-8")
+            self._send(page().encode(), "text/html; charset=utf-8")
             return
 
         if url.path == "/api/index":
+            # Read once. Asking per session made a page load parse the whole
+            # library as many times as there were sessions in it.
+            records = library.load()
             rows = [
                 {
                     "key": e.key,
@@ -845,7 +874,7 @@ class _Handler(BaseHTTPRequestHandler):
                     "size_bytes": e.size_bytes,
                     "subagents": e.subagents,
                     "session_title": e.session_title,
-                    "group": _group(e, library.get(e.key).get("source", "")),
+                    "group": _group(e, records.get(e.key, {}).get("source", "")),
                 }
                 for e in self.entries
                 # A downloaded folder the reader deleted, or a drive not mounted

{transcript_viewer-0.6.0 → transcript_viewer-0.6.1}/tests/page.test.js

@@ -1424,3 +1424,59 @@ test("everything reads as All sessions", () => {
   console.log(`\n${tests.length - failed} passed, ${failed} failed`);
   process.exit(failed ? 1 : 0);
 })();
+
+test("opening the library reports each stage it goes through", async () => {
+  const said = [];
+  const el = { hidden: true };
+  const bar = {
+    classList: { add() {}, remove() {} },
+    firstElementChild: { style: {} },
+  };
+  const text = { textContent: "" };
+  globalThis.__boot = { boot: el, bootbar: bar, boottext: text, said };
+
+  const seen = run(`
+    document.getElementById = id => globalThis.__boot[id] || {textContent:"",style:{},classList:{add(){},remove(){}}};
+    globalThis.requestAnimationFrame = fn => fn();
+    globalThis.fetch = async () => ({
+      ok: true,
+      headers: { get: () => "0" },
+      body: null,
+      json: async () => ({sessions: [], groups: [], tags: [], ai: {}}),
+    });
+    const stages = [];
+    const realSay = bootSay;
+    bootSay = (what) => { stages.push(what); realSay(what, 0, 0); };
+    return openLibrary().then(() => stages);
+  `);
+
+  return seen.then((stages) => {
+    assert.ok(
+      stages.some((s) => /Looking for your sessions/.test(s)),
+      "it should say it is looking before it has anything",
+    );
+    assert.ok(
+      stages.some((s) => /Drawing/.test(s)),
+      "it should say it is drawing once it has the data",
+    );
+  });
+});
+
+test("a failure to open leaves the reason on screen", async () => {
+  const text = { textContent: "" };
+  const el = { hidden: false };
+  globalThis.__boot = {
+    boot: el,
+    bootbar: { classList: { add() {}, remove() {} }, firstElementChild: { style: {} } },
+    boottext: text,
+  };
+
+  await run(`
+    document.getElementById = id => globalThis.__boot[id] || {textContent:"",style:{},classList:{add(){},remove(){}}};
+    globalThis.fetch = async () => ({ ok: false, status: 500 });
+    return openLibrary();
+  `);
+
+  assert.match(text.textContent, /Could not open your library/);
+  assert.strictEqual(el.hidden, false, "a blank window would say nothing at all");
+});

{transcript_viewer-0.6.0 → transcript_viewer-0.6.1}/tests/test_readme.py

@@ -41,6 +41,8 @@ CLAIMS = [
     ("quadratic", "HISTORY_TURNS", "src/transcript_viewer/ai.py"),
     ("links into the transcript", "function jumpToStep", "src/transcript_viewer/page.html"),
     ("--extra ai", "ai = [", "pyproject.toml"),
+    ("re-read whenever it changes", "def page()", "src/transcript_viewer/viewer.py"),
+    ("stat per page load", "PAGE_PATH.stat()", "src/transcript_viewer/viewer.py"),
 ]
 
 
@@ -162,3 +164,25 @@ def test_every_module_appears_in_the_map():
         if path.name.startswith("_") or path.suffix not in {".py", ".html"}:
             continue
         assert f"  {path.name}" in readme, f"{path.name} is missing from the module map"
+
+
+def test_every_extra_offered_in_the_readme_exists():
+    """An install command that names an extra nobody defined simply fails."""
+    project = Path("pyproject.toml").read_text()
+    defined = set(re.findall(r"^([a-z][a-z0-9-]*) = \[", project, re.MULTILINE))
+    readme = Path("README.md").read_text()
+    offered = set()
+    for group in re.findall(r'transcript-viewer\[([a-z,]+)\]', readme):
+        offered.update(group.split(","))
+    missing = offered - defined
+    assert not missing, f"the README offers extras that do not exist: {missing}"
+
+
+def test_every_extra_that_exists_is_mentioned():
+    """An extra nobody is told about may as well not be there."""
+    project = Path("pyproject.toml").read_text()
+    block = project.split("[project.optional-dependencies]")[1].split("\n[")[0]
+    defined = set(re.findall(r"^([a-z][a-z0-9-]*) = \[", block, re.MULTILINE))
+    readme = Path("README.md").read_text()
+    unmentioned = {name for name in defined if name not in readme}
+    assert not unmentioned, f"extras the README never mentions: {unmentioned}"

{transcript_viewer-0.6.0 → transcript_viewer-0.6.1}/tests/test_viewer.py

@@ -911,3 +911,37 @@ def test_clearing_an_empty_library_is_harmless(server):
     _delete(server + "/api/library?all=1")
     status, payload = _delete(server + "/api/library?all=1")
     assert status == 200 and payload["removed"] == 0
+
+
+def test_the_page_is_re_read_when_it_changes(tmp_path, monkeypatch):
+    """Editing the interface and seeing nothing change reads as a broken edit."""
+    from transcript_viewer import viewer
+
+    page_file = tmp_path / "page.html"
+    page_file.write_text("<p>first</p>")
+    monkeypatch.setattr(viewer, "PAGE_PATH", page_file)
+    monkeypatch.setattr(viewer, "_page", None)
+
+    assert viewer.page() == "<p>first</p>"
+
+    # A same-size rewrite is the hard case: only the timestamp separates them.
+    page_file.write_text("<p>secnd</p>")
+    import os
+    stamp = page_file.stat().st_mtime + 10
+    os.utime(page_file, (stamp, stamp))
+
+    assert viewer.page() == "<p>secnd</p>"
+
+
+def test_an_unreadable_page_serves_what_was_already_read(tmp_path, monkeypatch):
+    """A file being written to should not take the interface down mid-save."""
+    from transcript_viewer import viewer
+
+    page_file = tmp_path / "page.html"
+    page_file.write_text("<p>kept</p>")
+    monkeypatch.setattr(viewer, "PAGE_PATH", page_file)
+    monkeypatch.setattr(viewer, "_page", None)
+    assert viewer.page() == "<p>kept</p>"
+
+    page_file.unlink()
+    assert viewer.page() == "<p>kept</p>"

{transcript_viewer-0.6.0 → transcript_viewer-0.6.1}/uv.lock

@@ -388,7 +388,7 @@ wheels = [
 
 [[package]]
 name = "transcript-viewer"
-version = "0.6.0"
+version = "0.6.1"
 source = { editable = "." }
 dependencies = [
     { name = "atif-make" },