chore(coverage): raise the activity-scan floor to its measured coverage

The floor sat at 64% branches while every run measures 75%, so each
branch's coverage:update raised it and had to revert the change by hand.

.github/workflows/viewerjs-check.yml

@@ -16,9 +16,19 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
+# Timeouts are the measured job time plus at least 50%, and never under 20 minutes for a browser job,
+# because runner speed varies. Before sharding (main 2cecfcf, one worker): frontend coverage 32m10s,
+# page workflows firefox 18m59s, webkit 19m26s. First sharded run (PR #274 run 39712909047, 3 workers,
+# no npm cache, where npm ci stalled for 5m in six of eight jobs): coverage shards 11m19s/10m47s/10m49s
+# (tests 5m20s/4m42s/4m46s), merge 5m52s (report and check 4s), firefox shards 7m53s/9m27s (tests
+# 4m41s/3m29s), webkit shards 12m25s+ (cancelled at the old 12-minute limit after its 267 tests passed in
+# 6m29s) and 4m53s (tests 3m08s). With the npm cache hit (run 39725176320 at cbc8a61, npm ci 0-2s):
+# coverage shards 7m34s/6m04s/5m22s (tests 6m38s/4m53s/4m04s), merge 54s, firefox 7m57s/5m21s (tests
+# 7m08s/4m34s), webkit 8m16s/5m03s (tests 7m26s/3m58s); a cache miss adds up to 5m to npm ci, which
+# the 20-minute limits absorb.
 jobs:
   frontend-coverage:
-    name: frontend coverage (chromium and touch)
+    name: frontend coverage (shard ${{ matrix.shard }}/3)
     runs-on: ubuntu-latest
     # Layout comparisons depend on the fonts each browser falls back to, so browser jobs run in the
     # same pinned Playwright image as local runs (tag = @playwright/test in tools/vendor/package-lock.json;
@@ -26,12 +36,15 @@ jobs:
     container:
       image: mcr.microsoft.com/playwright:v1.64.1-noble
       options: --user 1001
-    # This job runs every page workflow twice (chromium, then touch) on one worker with V8 coverage on, so it
-    # takes about twice a single-browser job. Measured 2026-10-20: whole job 18m26s-24m57s (main 5ded3cf
-    # 22m15s; PR head 6359999 was cancelled at the old 25-minute limit while still passing), coverage step
-    # alone 20m55s-22m17s+, against ~12-15 minutes for the firefox/webkit jobs. 40 minutes leaves headroom
-    # for suite growth while still stopping a hung run; re-measure if a run passes 30 minutes.
-    timeout-minutes: 40
+    timeout-minutes: 20
+    # Public-repo ubuntu-latest runners have 4 vCPUs: three Playwright workers, each with its own test
+    # server, leave one CPU for the servers and the runner.
+    env:
+      PM_TEST_WORKERS: 3
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3]
     steps:
       - uses: actions/checkout@v7
       # The image's own Python 3.12 and Node 24: setup-python/setup-node install the runner's toolcache
@@ -50,24 +63,107 @@ jobs:
           "$venv/bin/python" -m pip install --no-cache-dir -r requirements-dev.txt
           echo "$venv/bin" >> "$GITHUB_PATH"
       - run: python --version && node --version && node --version | grep -q '^v24\.'
+      # npm's download cache, keyed on the lockfile; inside the container ~ is the job's HOME (/github/home),
+      # which npm also uses. node_modules itself is still built fresh by npm ci.
+      - name: Cache npm downloads
+        uses: actions/cache@v6
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-playwright-v1.64.1-${{ hashFiles('tools/vendor/package-lock.json') }}
       - run: npm ci --prefix tools/vendor --ignore-scripts
-      - run: npm run --prefix tools/vendor check
-      - run: npm run --prefix tools/vendor test
-      - name: Frontend unit, viewer, workflow, and coverage checks
-        run: npm run --prefix tools/vendor test:coverage
-      - name: Upload frontend coverage and Chromium traces
+      # Shard 1 also runs the node units and the viewer suite, so the vendor pins and the tooling tests
+      # run on the lightest shard instead.
+      - if: matrix.shard == 3
+        run: npm run --prefix tools/vendor check
+      - if: matrix.shard == 3
+        run: npm run --prefix tools/vendor test
+      - name: Page workflows with coverage, shard ${{ matrix.shard }}/3
+        run: npm run --prefix tools/vendor test:coverage:shard -- ${{ matrix.shard }}/3
+      - name: Upload raw coverage
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-raw-${{ matrix.shard }}
+          path: coverage/js/raw/
+          if-no-files-found: error
+          retention-days: 3
+      - name: Upload Chromium and touch traces
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: frontend-traces-shard-${{ matrix.shard }}
+          path: tools/vendor/test-results/
+          retention-days: 14
+
+  frontend-coverage-merge:
+    name: frontend coverage (merge)
+    needs: frontend-coverage
+    runs-on: ubuntu-latest
+    # Same image as the shards: the raw files name sources by the container's workspace path.
+    container:
+      image: mcr.microsoft.com/playwright:v1.64.1-noble
+      options: --user 1001
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - run: node --version && node --version | grep -q '^v24\.'
+      # npm's download cache, keyed on the lockfile; inside the container ~ is the job's HOME (/github/home),
+      # which npm also uses. node_modules itself is still built fresh by npm ci.
+      - name: Cache npm downloads
+        uses: actions/cache@v6
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-playwright-v1.64.1-${{ hashFiles('tools/vendor/package-lock.json') }}
+      - run: npm ci --prefix tools/vendor --ignore-scripts
+      # Each artifact lands in its own coverage-raw-N directory, so the next step can count them.
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: coverage-raw-*
+          path: ${{ runner.temp }}/coverage-raw
+      # coverage:merge only checks that raw files exist; merging two of three shards would report
+      # partial coverage, so a missing or empty shard artifact fails here.
+      - name: Verify every shard's raw coverage arrived
+        shell: bash
+        env:
+          STAGED_RAW: ${{ runner.temp }}/coverage-raw
+          EXPECTED_SHARDS: 3
+        run: |
+          found=0
+          for shard in $(seq 1 "$EXPECTED_SHARDS"); do
+            directory="$STAGED_RAW/coverage-raw-$shard"
+            count=0
+            if [ -d "$directory" ]; then count=$(find "$directory" -maxdepth 1 -type f -name '*.json' | wc -l); fi
+            echo "coverage-raw-$shard: $count raw files"
+            if [ "$count" -gt 0 ]; then found=$((found + 1)); fi
+          done
+          echo "shard artifacts with raw coverage: $found of $EXPECTED_SHARDS"
+          if [ "$found" -ne "$EXPECTED_SHARDS" ]; then
+            echo "::error::Expected raw coverage from $EXPECTED_SHARDS shards, got $found of $EXPECTED_SHARDS"
+            exit 1
+          fi
+          staged=$(find "$STAGED_RAW" -mindepth 2 -maxdepth 2 -type f -name '*.json' | wc -l)
+          mkdir -p coverage/js/raw
+          # cp -n never overwrites; a clash shows up as fewer merged files than staged ones.
+          find "$STAGED_RAW" -mindepth 2 -maxdepth 2 -type f -name '*.json' -exec cp -n -t coverage/js/raw {} + || true
+          merged=$(find coverage/js/raw -maxdepth 1 -type f -name '*.json' | wc -l)
+          if [ "$merged" -ne "$staged" ]; then
+            echo "::error::Shards wrote clashing raw file names: $staged staged, $merged merged"
+            exit 1
+          fi
+          echo "merged $merged raw files"
+      - name: Frontend coverage report and baseline check
+        run: npm run --prefix tools/vendor coverage:merge
+      - name: Upload frontend coverage report
         if: always()
         uses: actions/upload-artifact@v7
         with:
           name: frontend-test-reports
           path: |
-            tools/vendor/test-results/
             coverage/js/
             !coverage/js/raw/**
           retention-days: 14
 
   browser-workflows:
-    name: page workflows (${{ matrix.browser }})
+    name: page workflows (${{ matrix.browser }}, shard ${{ matrix.shard }}/2)
     runs-on: ubuntu-latest
     # Layout comparisons depend on the fonts each browser falls back to, so browser jobs run in the
     # same pinned Playwright image as local runs (tag = @playwright/test in tools/vendor/package-lock.json;
@@ -75,11 +171,16 @@ jobs:
     container:
       image: mcr.microsoft.com/playwright:v1.64.1-noble
       options: --user 1001
-    timeout-minutes: 25
+    timeout-minutes: 20
+    # Public-repo ubuntu-latest runners have 4 vCPUs: three Playwright workers, each with its own test
+    # server, leave one CPU for the servers and the runner.
+    env:
+      PM_TEST_WORKERS: 3
     strategy:
       fail-fast: false
       matrix:
         browser: [firefox, webkit]
+        shard: [1, 2]
     steps:
       - uses: actions/checkout@v7
       # The image's own Python 3.12 and Node 24: setup-python/setup-node install the runner's toolcache
@@ -98,22 +199,29 @@ jobs:
           "$venv/bin/python" -m pip install --no-cache-dir -r requirements-dev.txt
           echo "$venv/bin" >> "$GITHUB_PATH"
       - run: python --version && node --version && node --version | grep -q '^v24\.'
+      # npm's download cache, keyed on the lockfile; inside the container ~ is the job's HOME (/github/home),
+      # which npm also uses. node_modules itself is still built fresh by npm ci.
+      - name: Cache npm downloads
+        uses: actions/cache@v6
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-playwright-v1.64.1-${{ hashFiles('tools/vendor/package-lock.json') }}
       - run: npm ci --prefix tools/vendor --ignore-scripts
-      - name: Page workflows in ${{ matrix.browser }}
-        run: npm run --prefix tools/vendor test:workflows -- --project ${{ matrix.browser }}
+      - name: Page workflows in ${{ matrix.browser }}, shard ${{ matrix.shard }}/2
+        run: npm run --prefix tools/vendor test:workflows -- --project ${{ matrix.browser }} --shard ${{ matrix.shard }}/2
       - name: Upload browser traces
         if: always()
         uses: actions/upload-artifact@v7
         with:
-          name: browser-traces-${{ matrix.browser }}
+          name: browser-traces-${{ matrix.browser }}-shard-${{ matrix.shard }}
           path: tools/vendor/test-results/
           retention-days: 14
 
   # Branch protection requires the exact context "viewerjs". This job keeps that
-  # name and fails unless every frontend job above succeeded, including when one
-  # was cancelled or skipped.
+  # name and fails unless every frontend job above succeeded (every shard, the
+  # coverage merge and every browser shard), including when one was cancelled or skipped.
   viewerjs:
-    needs: [frontend-coverage, browser-workflows]
+    needs: [frontend-coverage, frontend-coverage-merge, browser-workflows]
     if: always()
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -121,8 +229,10 @@ jobs:
       - name: Require every frontend job to succeed
         env:
           COVERAGE_RESULT: ${{ needs.frontend-coverage.result }}
+          MERGE_RESULT: ${{ needs.frontend-coverage-merge.result }}
           WORKFLOWS_RESULT: ${{ needs.browser-workflows.result }}
         run: |
           echo "frontend-coverage: $COVERAGE_RESULT"
+          echo "frontend-coverage-merge: $MERGE_RESULT"
           echo "browser-workflows: $WORKFLOWS_RESULT"
-          test "$COVERAGE_RESULT" = success && test "$WORKFLOWS_RESULT" = success
+          test "$COVERAGE_RESULT" = success && test "$MERGE_RESULT" = success && test "$WORKFLOWS_RESULT" = success

TESTING.md

@@ -39,9 +39,44 @@ npm run --prefix tools/vendor test:coverage
 npm run --prefix tools/vendor test:workflows -- --project firefox --project webkit
 ```
 
-`PM_TEST_PYTHON` selects the Python executable; `PM_TEST_PORT` selects the local
-port (default 8765). Set these environment variables when Python is outside PATH
-or the port is occupied. Test servers are never reused. On unsupported Linux
+`PM_TEST_PYTHON` selects the Python executable; set it when Python is outside
+PATH. Every Playwright worker starts its own `tests/browser/server.py --port 0`,
+which binds a port the OS picks and prints it as `PM_TEST_SERVER_PORT=<n>`, with
+its own temp root and database (`tests/browser/fixtures.mjs`), so
+parallel workers and concurrent runs never share state. `PM_TEST_WORKERS` sets the
+worker count (default 1 under `CI`, otherwise a quarter of the CPUs, at most 8).
+Test servers are never reused across runs. The launcher holds each server's
+stdin open and the server (`--exit-on-stdin-eof`) shuts down cleanly, removing its
+temp root, when that pipe closes, so a worker killed without teardown leaves no
+server behind. A test that fails gets the stderr its server wrote during the test
+attached to the report as `server-stderr` (an aiohttp traceback behind a 500).
+
+The coverage run can be split the way CI splits it, and each shard keeps the raw
+V8 files it writes under `coverage/js/raw`:
+
+```sh
+PM_TEST_WORKERS=8 npm run --prefix tools/vendor test:coverage            # whole run, one report
+npm run --prefix tools/vendor test:coverage:shard -- 1/3                 # node units, viewer suite, workflows 1/3
+npm run --prefix tools/vendor test:coverage:shard -- 2/3                 # workflows 2/3 (likewise 3/3)
+npm run --prefix tools/vendor coverage:merge                             # report and baseline check of every raw file
+npm run --prefix tools/vendor test:workflows -- --project webkit --shard 2/2
+```
+
+`coverage:merge` refuses an empty raw directory; it does not count shards, so run
+every shard first (CI's merge job checks all three arrived). Measured on a 32-CPU
+machine in the pinned image (2026-10-21): `test:coverage` takes about 5 minutes
+with 8 workers and 24 minutes with 1; all four projects, 8 workers, each test 3
+times (6132 tests), 24 minutes. A CI-sized run (`docker run --cpus=4`,
+`PM_TEST_WORKERS=3`, all four projects once, 2044 tests) takes 25.5 minutes.
+
+Specs must pass beside each other, not only alone. Wait for the page's own
+signal, never for time: a rendering frame (`requestAnimationFrame`) for layout
+work queued by a render or a scroll, a response or a visible state for data. A
+timer that "usually" covers a frame is a race on a loaded runner. Library
+virtualization specs settle with `libraryObservation.settled()` (two consecutive
+frames with no Library frame queued). To look for such races, repeat a spec under
+load (`--workers 8 --repeat-each 10`, and in the image with `--cpus=1` or `2`).
+On unsupported Linux
 distributions, browser system dependencies may need manual installation. For a
 quick browser run, use `test:workflows -- --project chromium`.
 
@@ -109,14 +144,44 @@ the baseline updater. Raise floors with `npm run --prefix tools/vendor
 coverage:update`; it reruns the suites and cannot lower an existing floor.
 Review baseline changes like code changes.
 
+`npm run --prefix tools/vendor coverage:baseline-check` runs in well under a
+second without a browser and fails, naming the files, when a measured
+`web/js` file has no baseline entry or the baseline lists a file that no longer
+exists. It uses the gate's own `discoverSources`, and `npm test` runs the same
+check, so run it before pushing a new or deleted frontend file instead of
+waiting for the `frontend coverage` jobs.
+
 The `viewerjs` check runs on every PR, including backend-only changes. It is an
-aggregate job that passes only when the `frontend coverage (chromium and touch)`
-job and both `page workflows (firefox)` and `page workflows (webkit)` jobs
-succeed; the browsers run on separate runners in parallel. GitHub artifacts
-named `frontend-test-reports` contain HTML coverage, a JSON summary, and the
-Chromium/touch failure screenshots/traces; `browser-traces-firefox` and
-`browser-traces-webkit` hold the other browsers' traces. Open traces with
-Playwright's `show-trace` tool.
+aggregate job that passes only when every frontend job succeeds: the three
+`frontend coverage (shard N/3)` jobs, `frontend coverage (merge)`, and the four
+`page workflows (firefox|webkit, shard N/2)` jobs. A failed, cancelled or skipped
+job fails it. Every browser job runs with `PM_TEST_WORKERS: 3` (the public
+runners have 4 vCPUs). Each coverage shard runs `test:coverage:shard -- N/3`
+(shard 1 also runs the node units and the viewer suite, shard 3 the vendor pins
+and tooling tests) and uploads its raw V8 files as `coverage-raw-N` (kept 3
+days). The merge job downloads them, fails unless all three arrived with raw
+files and without clashing names, then runs `coverage:merge` (report plus
+baseline check). `tests/vendor/ci-workflow.test.mjs` checks this shape. GitHub
+artifacts named `frontend-test-reports` contain the merged HTML coverage and
+JSON summary; `frontend-traces-shard-N` hold the Chromium/touch failure
+screenshots/traces and `browser-traces-<browser>-shard-N` the other browsers'
+traces. Open traces with Playwright's `show-trace` tool.
+
+Every `npm ci` first restores npm's download cache (`~/.npm`), keyed on the vendor
+lockfile and the job's pinned image tag (`tests/vendor/ci-workflow.test.mjs` checks
+the key names the same tag as the job's `container.image`). Without it, `npm ci` stalled for about 300 s
+(npm's fetch timeout) in most of the eight concurrent jobs; with a hit it takes
+0 to 2 s. A lockfile change misses the cache once, so expect one slow run after it.
+Measured on PR #274 (run 39725176320 at cbc8a61, cache hit): the whole workflow
+took 8m38s, against about 33 minutes with one worker and no shards. Jobs: coverage
+shards 7m34s/6m04s/5m22s (tests 6m38s/4m53s/4m04s), merge 54s, firefox shards
+7m57s/5m21s (tests 7m08s/4m34s), webkit shards 8m16s/5m03s (tests 7m26s/3m58s).
+Browser jobs keep a 20-minute limit: the slowest job is about 8.5 minutes, a cache
+miss adds up to 5 to `npm ci`, and runner speed varies (the first sharded run was
+cancelled at a 12-minute limit).
+Playwright shards by test count, whole files at a time, so shard 1 carries the
+slow concept-comparison specs (`*-concept.spec.mjs`, alphabetically first) and
+runs longer; the remedy, if it starts to matter, is more shards, not reordering.
 
 The real-host suite covers both Classic and Nodes 2.0 startup, switching both
 ways, actual database prompt selection, execution-text serialization, workflow
@@ -227,8 +292,9 @@ The shared inline and collection inspector reads the current rooted file's suppo
 embedded records, exact generation facts and recorded or inferred prompt evidence.
 It renders in two concept surfaces (#249 D20–D22, D38). The Images side panel shows
 only the concept content: cover, title, filename, the evidence badge with a category
-chip, the + and − prompt blocks with copy and send, tag chips (the linked positive's
-own tags filter Images, D21), the six facts, and a footer with "Send to ComfyUI" and
+chip, the + and − prompt blocks with copy and send, tag chips (the file's own image
+tags first, D88, then the linked tags; image tags and the linked positive's own tags
+filter Images, D21), the six facts, and a footer with "Send to ComfyUI" and
 "Prompt history" only when prompt roles resolved or a link is saved; the sticky panel
 scrolls inside the window. The viewer's details (`#viewer-details`) repeat that
 content without the cover, then "File & provenance" (the honest file facts, the
@@ -267,7 +333,30 @@ becomes record format `limited` (no raw text, graph `limited`, roles and facts
 unaffected); other text chunks are skipped unread; byte-identical duplicates are
 accepted within a bounded read budget, while differing duplicates (and any duplicate
 role record over that budget) still fail. Other read bounds are unchanged: 8 MiB
-non-PNG header, 10,000 PNG chunks and a three-second ffprobe. Resolution under
+non-PNG header, 10,000 PNG chunks and a three-second ffprobe (per probe, at most two
+probes). Video containers are read through one shared carrier selector
+(`utils/video_metadata.select_video_carrier`, used by the inspector and by the admin
+scan): carriers are, in order, the per-key tags that current savers write (`prompt`,
+`workflow`, `parameters`, `comfyassets_prompt_pairs`, each `original-text`; Matroska
+upper-cased names fold on our side), then the old VideoHelperSuite `comment` JSON
+envelope, then `description` (object values are `reserialized-json`; envelope keys are
+matched exactly, as the legacy readers did, never folded). The first carrier holding a
+role key wins, otherwise the first holding a workflow, and carriers never merge. Two
+per-key tags folding to one key are a duplicate record: byte-identical ones are one
+record, differing ones fail the read. ffprobe is asked for exactly those six tags.
+Its JSON output escapes tag text (at most doubling it), so the stdout bounds are sized
+so that only the decoded per-record budgets above can fail or limit a record, and a
+video reads exactly as the identical PNG: the first probe allows twice the role and
+workflow budgets plus 64 KiB of envelope (12 MiB + 64 KiB); past that the inspector
+probes once more without the `workflow` tag within twice the role budget plus 64 KiB
+(4 MiB + 64 KiB) and the per-key workflow becomes `limited`, while an envelope over
+that bound still fails the read because it cannot be split. The admin scan reads the
+same carrier with the default resolver profile, so a per-key video links like the same
+graph in a PNG; the live monitor processes images only (unchanged, see the follow-up
+below) (`tests/test_utils_video_metadata.py`, `tests/test_api_admin.py`
+`TestScanReadsVideos`, `tests/test_api_prompt_inspector.py` `test_video_*`,
+`tests/test_inspection_response.py` `TestVideoProbeBoundsMatchPngBudgets`; the
+real-container round trips skip without ffmpeg). Resolution under
 `INSPECTION_PROFILE` bounds work, not graph size: 2,000 visits per candidate chain,
 20,000 in total, 64 link/JSON-container levels, 100,000 resolved characters, and a
 two 20,000-node ceilings: one over the top-level entries of the API prompt, and one
@@ -430,10 +519,11 @@ the first nav link and heading button.
 Recorded shell deviations:
 - **D4**: a "Theme" select with Dark, Light and System. System follows the ComfyUI
   palette, then the OS.
-- **D5**: no Activity button or Activity row until an activity center exists.
+- **D5**: retired by Activity (#249 Activity-1). The concept's Activity button and
+  Activity row are shown; their differences are D52 to D54.
 - **D28**: no COLLECTIONS, and no Design review. The bottom nav is
-  System plus the production Overview hub (its own outline home glyph, not the concept's
-  `activity` pulse, and no count).
+  the concept's Activity and System, plus the production Overview hub (its own
+  outline home glyph, not the concept's `activity` pulse, and no count).
   The connection reads "Your library, on your server" with a neutral muted dot.
 - **D49** (saved views, #249 D16): the SAVED VIEWS group label has no "PROPOSED"
   badge, because saved views are persisted (`/prompt_manager/saved-views`). Its rows are
@@ -484,14 +574,208 @@ Recorded shell deviations:
   as deleted. `tests/browser/workspace-saved-views.spec.mjs` covers the row, count,
   route, star updates, Save view on Favorites, Edit, and the failure paths;
   `tests/test_image_favorites.py` covers `favorites=1`.
+- **D52** (Activity, #249 Activity-1): the top-bar `button#activity-open` and the
+  sidebar's Activity row (the concept's `activity` pulse, first in `system-nav`) count
+  this session's *running* jobs. The concept counts
+  every sample job. `span.count#activity-count` is `hidden` at 0 (its text stays "0"),
+  and the row has no `.nav-count` then. The Activity heading has no "Unified activity ·
+  proposed" chip (prototype copy). At `max-width: 700px` the full-width `.top-actions`
+  row may wrap (`flex-wrap: wrap`), so the button, Theme and ComfyUI stay inside a
+  zoomed phone. The shell comparison hides the concept's count at runtime
+  (`#activity-count { display: none }`), so the concept's own CSS lays out its button
+  without it, and maps the row's count to none, the button's count to "0" and the
+  phone row's `flexWrap` to `wrap`.
+- **D53**: while a job runs, the approved Activity mockup's progress pill sits before
+  the Activity button on every page: `a#activity-pill.activity-pill`, "Scanning · 41% ·
+  8,240 / 19,622" (the verb by job kind, the server's floored percentage, and the file
+  counts once the total is known), a 70px mini bar, `href="#/activity/<id>"` and the same
+  text as its `aria-label`. With no running job it is `hidden`, which the shell
+  comparison maps as a hidden item before the button. At `max-width: 700px` it keeps the
+  verb and percentage only; on coarse pointers it is 40px tall like the concept's
+  buttons. Its rules are in `workspace.css` under D53.
+- **D54**: each `.activity-item` is a real job of this session (`GET
+  /prompt_manager/jobs`), running first, then finished newest first. The concept's
+  structure and CSS stay: `.panel-heading` > `h3` "✓ <title>" for a completed job and
+  "○ <title>" otherwise, plus `span.chip`, then `p`, and for a running job `<progress
+  max=100>` ("<title> progress") and `.row-actions`. The chip is green "Completed" or
+  blue "Running", "Cancelled", "Failed" or "Ended". The line reads "Started HH:MM · K
+  output folders · closing this view does not cancel it" while running, "Finished HH:MM
+  · N added · M errors", "Cancelled HH:MM at a file boundary · N added · completed work
+  is kept", "Stopped on an error at HH:MM · N added · M errors", or "This job ended when
+  ComfyUI restarted." The running actions are "Cancel job" only (no "Simulate
+  completion"); a failed cancel toasts "The job could not be cancelled. Try again.". With
+  no job the section says "No jobs have run since ComfyUI started. Scans and other long
+  operations appear here." `#/activity/<id>` is that job's own view (D56). When a job
+  ends while its Cancel job has focus, focus moves to the item's title link.
+
+  The Activity store reads the list once, then follows each running job over
+  `/prompt_manager/jobs/<id>/events`. A dropped stream re-reads the list after 1 s,
+  doubling to at most 30 s; a received event resets the wait, and so does a good list
+  read after failed ones or after any read that was not for a dropped stream. A running
+  job the server no longer lists, or one whose server could not be read twice in a row,
+  is shown as ended, so no pill stays; one failed read (a proxy's 502) changes nothing.
+  A finished job the server no longer lists (it keeps 20) is dropped. Numbers are
+  grouped "en-US", as the server's lines are. While the tab is visible the list is read again every 15 s (and whenever
+  Activity opens), so a job started in another tab or on the legacy admin page appears
+  without a reload. Toasts: "Scan started." after this tab's own start; "Scan finished
+  · N added · M errors", "Scan cancelled · N added" or "Scan failed · N added · M
+  errors" when a job this tab saw running ends (plural helper for "error").
+  `tests/js/workspace-activity-store.test.js` covers the store, its backoff and the
+  copy; `tests/browser/workspace-activity.spec.mjs` covers the list against the
+  concept's own items (`renderActivity` and `startJob`), the pill and counts, a phone,
+  reload and a second tab, Cancel job, a restart and an unreachable server, and the
+  toasts, with fake jobs from `tests/browser/workspace_activity_fixture.py`
+  (`/__test__/jobs/*`, including a simulated restart that drops the job streams).
+- **D55** (Scan for metadata, Activity-1 Task 3): Images → Import keeps Rescan as the
+  quick refresh (D15) and then shows the concept's own "Scan an output folder → Review
+  scan" row as "Scan for metadata" ("Discover and enrich existing files using the
+  configured sources.", button "Review scan"). It opens the concept's `scan-review`,
+  "Review metadata scan": no sample-plan `.demo-note` (prototype copy); Sources and
+  Scope in a `dl.meta-grid` (the concept's maintenance plan uses `dl`; `scan-review`
+  uses a `div`) reading "N output folders" (the discovered sources) and the concept's
+  "New and unresolved files" (the D58 checkbox switches it to "All files"); the
+  concept's sentence; then
+  a backup `.notice` (the concept's System notice box): `h3` "Back up the database first
+  (recommended)", "Downloads a copy of the prompts database before the scan changes any
+  records." and "Back up now", which downloads the existing `/prompt_manager/backup`
+  copy (as the legacy admin page does), reads "Backing up…" while aria-disabled, keeps
+  the dialog open and toasts "Database backup downloaded." or "The database could not be
+  backed up. Try again."; then Cancel / Start scan (primary; the concept's "Simulate
+  scan"). Start scan closes the dialog, starts the session scan job (`POST
+  /prompt_manager/jobs/scan`), toasts "Scan started." and opens `#/activity/<id>`; a
+  failed start toasts "The scan could not start. Try again.". The scan's progress line
+  now groups thousands ("Processing file 8,240 of 19,622"), as the mockup does.
+  `tests/browser/activity-concept.spec.mjs` compares the dialog with the concept's
+  `scan-review` and its box with the concept's System `.notice` (dark and light,
+  Chromium and touch, with a CSS and a DOM mutation check); `images-concept.spec.mjs`
+  maps the Import row; `workspace-images.spec.mjs` covers the dialog, the backup and
+  Cancel.
+- **D56**: one job's view at `#/activity/<id>`, the approved mockup
+  (`activity-scan.html`, "100% spot on"), which the concept does not have. The page
+  heading names the job (h1, document title "<title> · Prompt Manager"; the breadcrumb
+  stays "Activity"), its line is the D54 item line, and its actions are Download report
+  (disabled until Activity-2) and, while the job runs, "Cancel scan" (`.danger`; "Cancel
+  job" for another kind; a failed request toasts the D54 message). Then `section.surface`
+  "Progress": `.panel-heading` (h2, `span.small` with the server's "Processing file N of
+  M · about X min left", or after the end "N of M files processed", "Cancelled after N
+  of M files", the error line, or the restart line), `<progress max=100>` ("Scan
+  progress") and `dl.stat-row` tiles in order: Added to Library (`.added`, green),
+  Already known, Needs review (`.warn`, warning), No usable metadata, Errors (`.bad`,
+  red). Then `section.surface` "Results": `label.search-field` "Filter by file path…"
+  (`aria-label` "Filter results", case-folded match on the root label and path), and
+  `.outcomes` with `.outcome-list` (`button[aria-pressed]` label + count, in the
+  mockup's order Added, Needs review, Errors, No usable metadata, Already known; the
+  view opens on the first with files) beside `.outcome-files`: one `.file-row` (`.path`
+  root-relative, `.why` the server's detail) per listed file. The detail wording is the
+  builder's (approved with Task 1): "Added to the Library as “title”", "Linked to
+  “title”", "Already linked to “title”", "Needs review: …", "Error: …", where the title
+  is the prompt's Library title (its stored title, else its text's first line), not the
+  mockup's sample "→ “title” · new positive + negative". Each log line is "HH:MM:SS
+  <prefix> <root label>/<path> · <detail>" rather than the mockup's "[HH:MM:SS] + path →
+  prompt #4812 (new)". The header's actions sit in the page heading's
+  `.heading-actions`, where the mockup has a `.panel-heading > .row-actions`. An
+  empty outcome shows "No files in this group."
+  or "No listed file matches this filter.", and the note "Showing N of M" when fewer
+  than the counter are shown (the server lists 200 per outcome), with "each row opens
+  the image in the viewer" for Added and Already known. Then `details.term`, collapsed:
+  "● Scan log — raw detail, click to show" and `pre[tabindex=0]` with the raw lines.
+  The summary follows the store and carries `listed` (rows per outcome) and
+  `log_length`; the rows and log are read from `GET /prompt_manager/jobs/<id>` once on
+  opening, then at most once a second only while what it lists changes (or, with the
+  log open, its length), so a job whose lists are capped and whose log is closed is not
+  re-read; opening the log reads its new lines. When the job ends while Cancel scan has
+  focus, focus moves to the job's heading. An unknown id, or a job the store's list no
+  longer has, shows "This job is not in this session’s Activity. Jobs are kept until
+  ComfyUI restarts." and "All activity"; a job lost with a restart keeps what was read.
+  At `max-width: 700px` the tiles take two columns and the outcome list stacks above
+  the files. Each Activity item's title is now a link to its view, in the title's
+  colour. The rules are in `workspace.css` under D56. `activity-concept.spec.mjs`
+  restates the mockup's structure and CSS values and checks them with mutations;
+  `workspace-activity.spec.mjs` covers the counters, live updates, viewer rows, the
+  filter, the 200-row cap, Cancel scan, the busy start and an unknown or lost job.
+- **D57**: rows under Added and Already known are `button.file-row`s that open the
+  existing media viewer on that one file, by the identity Images opens it by
+  (`root_index:path`). Each scan row records its root's listing index (`root_index`,
+  the place in `_get_all_output_dirs`) beside its label. The row's source is that index
+  in `/prompt_manager/gallery/subfolders?mode=workspace` and must still carry the row's
+  label, so a reordered or replaced source never opens another root's file; the
+  workspace listing's new `path` filter (one exact relative path, case-folded, at most
+  1,024 characters, no traversal) returns that file. A row without an index, a changed
+  source or a file the listing no longer has toasts "This file is no longer in Images.
+  Rescan from Import and try again."; other rows are plain text, with no new file
+  route. A start refused because another record-changing job runs toasts "Another job
+  is running: <title>." with the title linking that job's view (the shared toast now
+  accepts link parts). A toast with a link stays 20 s instead of 6.5 s, and any toast
+  stays while the pointer or focus is on it.
+- **D58** (scan scope, Activity-2 Task 4): the concept's `scan-review` states a fixed
+  scope, "New and unresolved files". Production keeps that value as the default and adds
+  the concept's own System toggle after the `dl.meta-grid`: a `.setting-row` with the
+  label "All files", the hint "Also read the files already linked to their prompt
+  again." (the switch's `aria-describedby`) and the Toolkit switch (`label.ca-switch`, a
+  checkbox with `role="switch"`, as the concept's `hydrateSwitches` renders it),
+  unchecked. Checking it switches the Scope value to "All files"; Start scan sends
+  `POST /prompt_manager/jobs/scan {scope: "new" | "all"}` (no body, an empty body or no
+  `scope` is "new"; another value is a 400).
+  - In "new" the scan skips, before reading any metadata, the files the Library already
+    links with a resolved link and that are unchanged on disk: exactly one
+    `generated_images` row for the file, exactly one distinct pair link on it
+    (`image_prompt_pairs`, written only by resolved ingestion), and a stored
+    `file_size` equal to the file's size in this walk. Both paths go through
+    `normalize_image_path` (absolute, normalized, `os.path.normcase`); a row without
+    `file_path` matches by its `image_path`.
+  - Read again: files linked without a pair (the monitor's fallback and FIFO links, the
+    legacy positive-only import), linked to more than one prompt or pair, not linked, a
+    file whose size changed (one replaced at the same path, e.g. a reused ComfyUI
+    counter name, is read and its conflict lands under Needs review), and a row with no
+    stored size (unknown is not known). The scan now stores each file's size when it
+    ingests it, so a file read once is skipped by the next "new" pass; the first pass
+    after the upgrade fills the missing sizes, which reports those files as enriched
+    (Added) instead of unchanged.
+  - The known set is one streamed query that keeps only the scanned paths. If it cannot
+    be read, the scan logs "Known files could not be read · reading every file" and
+    reads every file.
+  - A skipped file counts as processed and unchanged in the legacy counts (not as
+    found) and under Already known, with the detail "Skipped · already linked" and the
+    log line "= <root>/<path> · Skipped · already linked"; the log's first line names
+    the scope ("Scan started · N output folders · new and unresolved files" or "· all
+    files"). A legacy-page scan that attaches to a running "new" job therefore shows
+    the skipped files in its `unchanged` count.
+  - "All files" reads every file, as the scan did in Activity-1, and the legacy
+    `/prompt_manager/scan` route always does when it starts the scan (its SSE payload
+    keys are unchanged).
+  - `activity-concept.spec.mjs` compares the switch with the concept's System → Sources
+    toggle ("Watch for new outputs"), without its place-dependent top margin;
+    `workspace-activity.spec.mjs` covers the Scope value, the description and the
+    request both ways; `tests/test_scan_scope.py` covers the skip, the size rule, the
+    replaced file, the re-read of unresolved files, "all", the legacy route, the
+    fallback, the empty body, the 400 and Windows case folding.
+- **D59** (job report and log, Activity-2 Task 5): the job view's "Download report" is
+  enabled. It fetches `GET /prompt_manager/jobs/<id>/report` through the api-client URL
+  (so a proxy mount works) and saves a JSON attachment named
+  `prompt-manager-<kind>-<YYYYMMDD-HHMM>.json` (server local time), then toasts "Job
+  report downloaded." (or "The report could not be downloaded. Try again."). The report
+  holds the summary, every counter, each outcome group's exact `count`, its listed
+  `rows` (at most 200) and a `truncated` flag, the scope and the log; rows and log lines
+  carry root-relative paths only, never an absolute path (an unknown id is a 404).
+  A job lost with a restart has no report on the server, so its Download report is
+  disabled; a view left while the report downloads still saves it but shows no toast.
+  The scan log opens at its newest line every time it is opened and follows new lines
+  only while the reader is at the bottom; a reader who scrolled up keeps the position
+  while it stays open (checked on Chromium, Firefox and WebKit).
+  `test_report_is_attachment_without_absolute_paths` and the browser tests `download
+  report saves the job JSON` and `log keeps the reader's scroll position` cover it.
 - **D29**: no prototype copy. There is no "Interactive concept" badge and no
   "What changes & why" button. The footer reads "ComfyAssets · Local tools. Your
   library.", and the title has no " concept" suffix. Save view's dialog action reads
   "Save", not "Apply in prototype", and its toast drops the demo's word "Sample".
 - **D31**: at `max-width: 950px` the overlay caps the one-column shell at
   `minmax(0, 1fr)`, so extreme zoom cannot widen it to the sidebar's min-content.
-- **#245 D2**: no "Auto-tag images" on the Tags heading until the image-annotation
-  slice.
+  On the Images cards (#249 C2) a card's info row stacks its text above Info and Tag
+  once the row is narrower than the narrowest bounded card (120px; a list row's info
+  is what its art leaves), and the two buttons wrap when even that row cannot hold
+  them (`stacksCardInfo`, `tests/js/workspace-image-layout.test.js`).
+- **#245 D2 (retired, #249 C2)**: the Tags heading shows the concept's "Auto-tag images";
+  it opens the Tag image dialog (D115 when nothing is selected).
 - **Brand name**: not a deviation. The brand link's accessible name matches the
   concept's, mark included, because production's `.brand-mark` is not `aria-hidden`
   either. The inventory compares `brand.name` and `brand.mark.hidden`.
@@ -514,13 +798,15 @@ zoom, the 2nd card opens the viewer titled "<title> · <filename>", Escape retur
 to it (production only: the concept re-renders its grid and drops focus), Info on the
 3rd card moves `.selected`, searches for "alpine" and for one image, and Load more with
 its toast. `mapImagesConcept` applies D3, D8 (the selection bar's real actions only),
-D9, D10, D14, D15, D17, D29, D32, D35 (singular counts) and D36 (categories
+D10, D14, D15, D17, D29, D32, D35 (singular counts) and D36 (categories
 sorted alphabetically). Removed toolbar and filter-row items flow again from the
 concept's own boxes (`reflow`), checked against the concept page with those items
 removed at runtime. Masonry tops and heights are compared unrounded, within one layout
 unit per card above in the column (D3). `one footer height for the collection (D3)`
-seeds two seedless files (`seedless_images` on `/__test__/concept/reset`) and asserts
-that every row reserves the tallest footer.
+seeds two seedless files (`seedless_images` on `/__test__/concept/reset`, with
+`short_seedless` so their "96 × 72 · PNG" subtitle stays on one line beside Info and
+Tag) and asserts that every row reserves the tallest footer and that their own footer
+is shorter than the row it reserves.
 
 ### Images page controls and recorded deviations (#249 PR C)
 
@@ -570,7 +856,8 @@ Recorded deviations on this page (spec §8):
   footer, masonry tops may differ by sub-pixel snapping (at most one layout unit per
   card above in the column), and a List row's info takes its natural height, centred
   beside the 160×95 art.
-- **D5**, **D29**: no Activity button and no prototype copy (shell).
+- **D29**: no prototype copy (shell). The Activity button and pill are the shell's
+  (D52, D53).
 - **D7**: the star is a real persisted favorite with "Added to favorites." /
   "Removed from favorites." and a rollback toast on failure.
 - **D8**: every Images card has the concept's select checkbox before the star; the
@@ -605,7 +892,9 @@ Recorded deviations on this page (spec §8):
   the concept` compares the bar and the checked card with one card checked; the omitted
   actions flow again from the concept's own boxes, checked against the concept page with
   them removed at runtime.
-- **D9**: no Tag button until the image-annotations slice.
+- **D9 (retired, #249 C2)**: every card shows the concept's Tag (`tagImage`, "Tag or
+  auto-tag <filename>") after Info; it opens the Tag image dialog without selecting
+  the card (see "Tag image dialog" below).
 - **D10**: the card title is the linked positive's display title, else the filename;
   the `h3` keeps the relative path in `title`.
 - **D11**: the subtitle is "W × H · EXT · Seed N" with unknown parts omitted.
@@ -663,6 +952,8 @@ Recorded deviations on this page (spec §8):
   history appear only with resolved prompt roles or a saved link; a video file keeps
   `video.detail-cover`; and only the linked positive's own tags are `button.chip`
   filters, while recipe, recorded-run and embedded tags stay plain `span.chip`.
+  Amended by D88 (#249 PR C): the file's own current image tags lead the same row
+  and are filters too; a linked tag already shown (case-insensitive) is left out.
 - **D22**: an empty positive reads "No positive prompt (explicitly empty)" (the concept
   applies its negative wording to both roles), and a confirmed `p.prompt-text` is
   focusable (`tabindex=0`, marked focus ring) so long prompts stay keyboard-readable.
@@ -769,6 +1060,186 @@ npm run --prefix tools/vendor test:workflows -- images-concept.spec.mjs \
   --project chromium --project touch --project firefox --project webkit
 ```
 
+### Tag image dialog and recorded deviations (#249 PR C)
+
+Every Images card and every Library-embedded gallery card shows Info then the
+concept's Tag (`app.js` mediaCard). Tag opens the concept's **Tag image** dialog
+(`web/js/workspace/image-tagging.mjs` over the C1 controller
+`image-tagging-state.mjs`) in the shared modal shell with the concept's
+`tagging-modal` class, so its `.dialog-actions` stay sticky while the content
+scrolls. Focus starts on × and returns to the Tag button. The preview is the
+capture's own `preview_url` (through `ApiClient.resolveUrl`): an `img`, or a
+`video preload="metadata" muted`. The capture is released on ×, Escape, Cancel,
+Save, a route change (the shell closes its dialog) and `pagehide`, which closes the
+dialog (a page restored from the back/forward cache shows no dead dialog); the
+release `DELETE` and the Save `PUT` are sent with `keepalive` (`ApiClient`'s
+additive option), so they finish while the page unloads. A save still in flight
+when the dialog closes keeps its capture until the `PUT` settles, then releases it
+and still reports the outcome: the saved toast and every page's refresh, or the
+failure as a toast. Generate is explicit and uses the server's real defaults
+(`GET /prompt_manager/autotag/models`), and the fields show exactly those values
+(they are re-rendered when the observation lands and on a model change, never while
+typing); an invalid field reports native validity and sends nothing. A tag conflict
+shows the current set at once: the status line appends "Saved now: <tags>." and the
+manual field holds the current set ahead of the draft (repeats dropped), so the next
+Save sends what is shown against the current revision. Save writes the manual
+names, then the remaining chips, deduplicated case-insensitively (first spelling
+wins), and toasts the mock's copy verbatim, "<n> tags saved for <filename>." even
+for one tag, plus " Prompt association still awaits review." from Needs review.
+Tagging one file never changes another file (an equal-byte copy included), a
+prompt, a pair or a link. States the mock lacks (generating, busy, conflict,
+changed storage or file, expired capture, unconfirmed save, unavailable model,
+video) are text in `#tag-generation-status` only; **Retry** (D116) leads the
+actions while the controller allows it, where the other workspace dialogs place
+their Retry. The Tags
+page re-reads its lists after every confirmed save, so the Images counts follow.
+
+The image-tagging plan's deviation numbers were renumbered by +23 because the
+Inspect plan keeps D60–D66 (plan D60 → D83, D61 → D84, D65 → D88, D68 → D91).
+
+- **D83** (plan D60, ruling T4): the suggestions are removable chips instead of
+  checkbox rows: `span.chip.tag-suggestion` in a `.tags` row, in the concept's
+  checked-row tokens (accent border, `--soft-blue`), each with the name, the
+  confidence (`98%` for WD14, "Suggested" for language models) and a × "Remove
+  <tag>". A chip has the concept `.chip`'s 4px corner (the later `.tag-suggestion`
+  row rule would give 5px) around the row's own 12px text. At most the requested
+  count, all preselected. While chips exist, ruling T4's "Remove anything you do not
+  want to add." (`p.small`) leads them inside `#tag-suggestions`; removing the last
+  chip shows "All suggestions removed. Generate again or enter tags manually." The
+  opening sentence is the concept's on-screen copy, "Generate suggestions with the
+  selected model before approving.": the concept's markup carries another ("Choose a
+  model… Uncheck anything…"), but its `renderTagModelOptions` (a1062–1076) replaces it
+  as soon as the dialog opens, so the opened state is compared unmapped.
+- **D84** (plan D61, rulings T1/T2): the Tagging model options are legacy's four
+  engines in the mock's order with legacy labels and sizes (`WD14 SwinV2 · ~400
+  MB`, `WD14 ViT · ~400 MB`, `GGUF JoyCaption (Recommended) · ~4.5 GB` in the
+  mock's Ollama slot, `HuggingFace JoyCaption · ~16 GB`); the instructions start
+  from the server's `default_prompt`.
+- **D91** (plan D68, ruling T3-bulk): a **Suggestions** number field (1–100) for
+  every model, prefilled from `autotag.defaults.suggestion_limit` (10); a model
+  change keeps it.
+- **D88** (plan D65, ruling T7/C2): the inspector's chip row (side panel and viewer
+  details, after the prompt blocks) shows the file's current image tags first (the
+  B3 envelope's `image_tags`, `state: "current"`, S1), then D21's linked tags not
+  already shown (case-insensitive, the image tag's spelling wins). In the Images
+  panel every image tag is a Tags filter `button.chip` (the filter matches image
+  tags too) and linked tags keep D21's rule; in the viewer, and wherever no Tags
+  filter exists (the Library-embedded gallery, Activity and recorded runs), every
+  chip is a plain `span.chip`. `none` and `unavailable` add no chips and no other
+  chrome; a malformed facet fails the inspection like any malformed field. The
+  concept has one row of the image's own tags (`i.tags`, app.js a402), so with the
+  concept image's tags saved as its image tags production still equals the concept.
+  After a Tag save the selected file's inspection is re-read, so the panel redraws
+  the row without reselecting and the viewer, which shares that inspection, shows it.
+- **D115** (beyond the plan's list): the concept always has a selected image, so
+  its "Auto-tag images" always opens the dialog. Production opens it for the image
+  selected in Images when it was last left; with none it is `aria-disabled` and
+  pressing it toasts "Select an image in Images first." (no new chrome).
+- **D116** (ruling T5): **Retry** leads `.dialog-actions` (before Cancel and the
+  primary) while a failed observation, a failed Generate, an unconfirmed save or an
+  answer that needs a fresh observation (changed storage or file, expired capture)
+  can be retried; the concept has no failure states, so it has no Retry. After a
+  failed Generate it takes Generate's own path (an invalid field reports its
+  validity); an unconfirmed save resends the identical body; after a changed storage,
+  file or expired capture it observes again and keeps the typed draft (when the saved
+  set changed meanwhile, the current set leads the draft and the status line says
+  "The tags of this image changed since the dialog opened. Saved now: <tags>.").
+  Browser tests: "D116: Retry leads the actions after an unconfirmed save…", "D116:
+  Retry after an expired capture observes again and keeps the typed draft (M5)" and
+  the paired `production-unknown-outcome` capture.
+- **D29** (no prototype copy) in the dialog: no "Prototype · suggestions are
+  simulated…" note, the status reads "Suggestions from <model>. Approve tags to save."
+  (not "Sample suggestions from …"), and the toast has no " in this tab".
+
+After a confirmed save the selected file's inspection is re-read quietly: the panel
+and the viewer keep the current details until the new answer lands, with no "Loading
+file details…" in between (`createInspectionController().refresh()`). While a Tags
+filter or a search is active the saved file may start or stop matching, so Images
+re-reads its loaded range in place (`createImageStream().refresh()`: the same query
+from the first page until the loaded count, published once). The cards, the scroll
+position and the selection stay while the selected file still matches; when it no
+longer does, the panel follows the collection (its first file), as after a reload,
+and the selection bar keeps only the checked files still listed, so its count is what
+Set category and Export metadata apply to. A refresh never runs beside a page load
+already in flight: asked during one, it is pending and runs once that page settles
+(success or failure; a reset drops it), and Load more waits for a running refresh
+(it neither loads nor moves focus). The re-read asks for pages as large as the rest of
+the loaded range (at most 200 files, at least one batch), one after another (each
+cursor comes from the page before); a failed re-read toasts "Images could not be
+refreshed after the tag save. Refresh image collection to retry." and keeps the
+cards. A save made while Images is left (Tags › Auto-tag images) marks a saved Images
+visit with a Tags filter or a search stale: returning lists it again with its
+filters instead of restoring the old cards. Browser tests: "the post-save re-read
+keeps the panel content until the new read lands", "a save under a Tags filter
+re-reads the listing: …", "a save under a search keeps the scroll position and the
+loaded range", "a failed listing re-read after a save says so and keeps the cards
+(M2)" and "a tag save from Tags reloads a filtered Images visit instead of restoring
+it (M6)"; the pending refresh and the page sizes are unit-tested.
+
+Concept comparison (`tests/browser/tagging-concept.spec.mjs` with
+`tagging-canonical-comparison.mjs`, plan Task C4): production runs on the concept
+fixture with the concept image's own tags (`cinematic, blue_hour, architecture`)
+saved as its image tags, and the fake model answers the concept's own sample
+(`/__test__/tagging/suggestions`: mountain 0.98, observatory 0.95, snow 0.88,
+blue_hour 0.81), so the dialog's inventory (order, text, field attributes, tokens,
+preview box, chips, status, sticky actions) must equal the concept's at 1600×1100 and
+390×844, dark and light: opened, generated with WD14 and generated with a language
+model, plus the empty result (the concept above its own threshold), the review-scoped
+dialog with its scope note and the card's Info and Tag group (M1). `mapConceptTagging`
+applies only D29, D83, D84 and D91; a mutation check (the model panel's border
+removed, the primary relabelled) shows the comparison notices a change. Every
+production-versus-concept difference of PR C and its record:
+
+| Difference | Record |
+| --- | --- |
+| Removable chips with × instead of checked checkbox rows; "Remove anything…" while chips exist; the all-removed copy | D83 (ruling T4) |
+| Legacy engine labels and values, GGUF in the Ollama slot, server default instructions | D84 (rulings T1/T2) |
+| Suggestions count field | D91 (ruling T3-bulk) |
+| No prototype note, "Suggestions from …", no " in this tab" | D29 |
+| Image tags first in the inspector and viewer chip row | D88 (ruling T7/C2) |
+| Auto-tag images `aria-disabled` without a selected image | D115 |
+| Retry leads the actions when the controller allows it | D116 (ruling T5) |
+| States the concept lacks (busy, conflict, changed storage or file, unconfirmed save, unavailable model, video) | Global Constraints: `#tag-generation-status` text only |
+
+Native image tagging (#249 PR B routes, PR C UI): `POST
+/prompt_manager/image-annotations/observe` (capture one listed file, its saved set and
+`tag_revision`), `GET`/`DELETE /prompt_manager/image-annotations/capture/<token>`
+(the preview and its release), `POST /prompt_manager/image-annotations/suggest` (the
+gated top-N suggestions, at most the requested count) and `PUT
+/prompt_manager/image-annotations/tags` (re-hash, then save one byte record's set).
+Cheap reads follow spec amendment S1 (the verified `(size, mtime_ns)` fingerprint;
+residual risk above, under "Image annotations schema"). No automated test downloads
+or loads a model: the browser server injects `TestModel`, whose `download_model`
+raises, and every tagging spec asserts no `/autotag/download/` request. Capture
+limits are those of the capture store above (256 MiB per file, 8 completed captures,
+512 MiB reserved, 900 s idle, 1800 s hard). The browser fixtures release every capture
+on reset. PR C is HTML, CSS and JS only (no restart); the PR B routes it calls need a
+maintainer ComfyUI restart once.
+
+Test files: `tests/browser/workspace-tagging.spec.mjs` (the fixture is
+`tests/browser/workspace_tagging_fixture.py`: two files sharing one prompt and
+pair, an equal-byte copy, a video, an unlinked file, the fake model with `hf`, and
+no model files; every test asserts no download request),
+`tests/js/workspace-image-tagging.test.js`,
+`tests/js/workspace-image-tagging-state.test.js`,
+`tests/js/workspace-images-lifecycle.test.js`, and for D88
+`tests/js/workspace-file-inspector.test.js`,
+`tests/js/workspace-inspection-state.test.js` and `tests/browser/inspector-concept.spec.mjs`
+("image tags saved on the concept image keep the inspector equal to the concept"), and
+for the comparison `tests/browser/tagging-concept.spec.mjs` and
+`tests/js/workspace-images-state.test.js` (the in-place refresh), and on all four
+projects `tests/browser/workspace-tagging-lifecycle.spec.mjs` (leaving the page with
+the dialog open releases the capture with no console error; closing during a save
+releases it after the save and still reports it).
+
+```sh
+node --test tests/js/workspace-image-tagging*.test.js tests/js/workspace-images-lifecycle.test.js
+npm run --prefix tools/vendor test:workflows -- workspace-tagging.spec.mjs tagging-concept.spec.mjs \
+  workspace-vocabulary.spec.mjs images-concept.spec.mjs --project chromium --project touch
+npm run --prefix tools/vendor test:workflows -- workspace-tagging-lifecycle.spec.mjs tagging-concept.spec.mjs \
+  --project firefox --project webkit
+```
+
 ### Prompt library cards and recorded deviations (#249 PR E)
 
 The shelf uses the shared concept toolbar and caption (E1) and the concept's
@@ -960,6 +1431,160 @@ npm run --prefix tools/vendor test:workflows -- history-concept.spec.mjs \
   workspace-history.spec.mjs --project chromium --project touch --project firefox --project webkit
 ```
 
+### Inspect a file page and recorded deviations (#249 local Inspect, PR L2)
+
+`#/inspect` ("Inspect a file") is a native workspace route; it no longer hands off to
+the legacy metadata page, which stays reachable from Overview's "Open existing metadata
+inspector" card (`/prompt_manager/gallery.html`). The page is the concept's `#metadata`
+(app.js `renderMetadata` a740–748, selection a1715–1729; style.css 709–722, 1180–1194,
+1543–1545, 1559–1564) in the concept's own classes (`.surface`, `.file-drop`,
+`.spaced-20`, `.local-file-preview`, all from the synced `concept.css`), with no
+`workspace.css` override. One local image (PNG/JPEG/WebP) or video (MP4/MOV/M4V/WebM/MKV;
+AVI/WMV preview only), chosen or dropped, previews inline. The heading's one action opens
+the shared viewer with the full inspector on a record read entirely in this browser
+(`web/js/workspace/inspect.mjs`, `local-session.mjs`, `local-inspection.mjs` and the L1
+readers `png-metadata.js`, `local-video.mjs`, `local-projection.mjs`). Nothing is
+uploaded, imported or stored. Only HTML and JS change, so no ComfyUI restart is needed.
+
+Bounds (the server's own budgets, ported by PR L1; see "Follow-up: local Inspect parity"
+under "Chronological Library history" for the known divergences):
+- PNG: at most 10,000 chunks; keyword 1–79 bytes; every chunk range checked against the
+  File's size before slicing. Role records (`prompt`, `parameters`,
+  `comfyassets_prompt_pairs`) share 2 MiB encoded and 2 MiB decoded (over that, the read
+  fails); a workflow over 4 MiB is `limited`; duplicates are capped at 8 MiB (workflow)
+  and 4 MiB (roles, decoded `parameters`). The sum of slices read from any PNG, however
+  large or sparse, is at most 19,794,389 bytes.
+- Video: the same record rule over the container's tags (per-key carrier first, then the
+  `comment` envelope, then `description`); at most 10,000 boxes or elements; no slice
+  inside `mdat` or a Cluster beyond its header.
+- JPEG/WebP: at most 64 KiB, for dimensions only.
+- Response: 8 MiB of actual UTF-8 JSON; omission order workflow graph, prompt graph, all
+  raw. The whole File is never read with `arrayBuffer()`, `text()` or `stream()`.
+
+Privacy, asserted by `local inspection makes no content request or storage write` and
+`local roles send exactly` in `tests/browser/workspace-inspect.spec.mjs`, and by the
+managed-host spec below: no request carries the file's bytes, name or text (fetch, XHR,
+beacon, WebSocket, EventSource); Inspect writes nothing to `localStorage`,
+`sessionStorage` or IndexedDB; only an explicit Send crosses the host bridge, and its
+payload carries neither the `blob:` URL nor the filename; no console message names the
+file or quotes its prompts (asserted on the managed host). The selection's `blob:` URL belongs to one local session and is revoked once,
+on replacement, route change, unmount or `pagehide`, never while an element in the page holds it: the inline preview
+and, when it is open, the viewer drop their media first. The page, not the session, owns `pagehide`: it closes the
+viewer, releases the inline media, then ends the selection and clears the chooser, so a page restored from the
+back-forward cache shows an empty chooser beside the empty selection (`URLs and media end with their owning
+session`, which also leaves with the viewer open).
+
+Recorded deviations on this page (maintainer rulings LI-3, LI-6; plan "Mock inventory and
+mapped differences"):
+- **D60** (heading action, LI-3): "Open file metadata" (`ca-primary`) replaces the
+  concept's "Open sample metadata". It is `aria-disabled="true"` and
+  `aria-describedby="local-file-note"` (the drop note) until a classified selection is
+  ready, then opens the shared viewer on that file.
+- **D61** (copy, LI-3): the surface `p` reads "Read embedded metadata in this browser.
+  The file is not uploaded or added to your library."; the drop note "Your file stays in
+  this browser. Its metadata opens with “Open file metadata”."; the chooser label "Choose
+  an image or video for a local preview"; the toast "Local preview only. No file
+  uploaded; metadata is available above.". The h2 "Inspect without importing" is the
+  concept's, verbatim.
+- **D62** (accept and video): `accept` is the concept's
+  `image/png,image/jpeg,image/webp` plus `video/*,.mp4,.mov,.m4v,.webm,.mkv,.avi,.wmv`. A
+  video previews in the same `#local-preview` slot as `video.local-file-preview` with
+  native `controls`, `playsInline`, `preload="metadata"` and `muted`, never autoplays
+  inline, and is paused, has its `src` removed and is removed from the page on replacement
+  or dispose, before its URL is revoked. Each preview owns its listeners, so the page never
+  pins a released node. A settled video (metadata read, or failed) is then reset with
+  `load()` at once; one still starting is reset only once it reports metadata or an error,
+  because WebKit (GStreamer) blocked the page when such a pipeline was reset (`replacing a
+  video that just started loading never blocks the page`, `a video replaced while still
+  starting is reset once it settles`). A WebKit load cut off by the revoked URL usually
+  stalls and never settles; a fallback then only drops the waiting listeners. The viewer's
+  own video teardown was checked the same way (`closing the viewer on a video that just
+  started never blocks the page`, 15 fresh pages on WebKit) and needed no change.
+  Follow-up: on WebKit, a video released exactly at its `loadstart` sometimes blocks the
+  page, with or without any reset and also before the deferred reset (2 of 24 runs in the
+  pinned image), so the `loadstart` spec is skipped on WebKit until that is investigated.
+- **D63** (status line): one `p.small.spaced-16` in `#local-preview`, for states the
+  concept never shows: "Drop one file at a time.", "Folders cannot be inspected. Choose
+  one image or video file.", "This file type cannot be previewed or inspected here.
+  Choose an image or video file.", "The preview could not be displayed. Metadata and the
+  original remain available in the viewer." and "Embedded metadata could not be read."
+  (the shared inspector's own copy) are `role="alert"`; "Metadata in AVI and WMV files
+  is not read here. The preview and the original remain available." is `role="status"`.
+  A rejected chooser or drop ("Drop one file at a time.", folders, an unsupported drop)
+  keeps the selection and its status line: its alert is a second line after it, removed
+  by the next selection attempt or after the concept's toast interval (6.5 s). The toast
+  "Local preview only…; metadata is available above." shows only for a selection whose
+  status is empty or the AVI/WMV note, never beside an unreadable or failed preview.
+- **D64** (drop, LI-6): `dragover`/`drop` on `.file-drop` accept exactly one File, read
+  only `dataTransfer.files`/`items` (never its strings) and change nothing visually.
+  While the page is mounted, `window` `dragover`/`drop` call `preventDefault`, so a missed
+  drop cannot navigate away. A drop is ignored while a dialog is open.
+- **D65** (no revoke on load): unlike the concept, the preview's `blob:` URL is not
+  revoked on `load`: the viewer and Download original use it until the session ends.
+- **D66** (local rail, in `file-inspector.mjs` for `identity.kind === 'local-file'`): the
+  viewer and rail title is the filename; "File & provenance" opens with "Selected local
+  file · read in this browser", lists Source, Size, Dimensions, Format, Media type and
+  Modified with no Path row and no Show in folder, and ends with "Local file; no saved
+  library association was checked." and Download original. There is no Prompt history
+  action and no category or tag chips.
+
+The chooser keeps naming the chosen file, as the concept's does: it is cleared as the
+picker opens (so choosing the same file again is a new selection), not after `change`,
+and named again with the current File (through a `DataTransfer`, which fires no
+`change`) when the picker is cancelled. An accepted drop names the dropped file, so the
+chooser never names a replaced file and never reads "No file chosen" beside a selection.
+
+Legacy floor (`web/metadata.html`), dispositions:
+- PNG by chooser and by drop: kept (`#local-file`, D64).
+- Positive and negative with Copy: kept, in the shared inspector's prompt blocks.
+- Full text (the old "Show more"): the prompt blocks show the whole text.
+- Raw workflow view and Download workflow JSON: kept, in "Workflow & raw metadata".
+- Copy all summary and filename copy (LI-4): the filename is selectable text in the rail
+  and Download original saves the file under its name. The ruled "Copy settings summary"
+  button after the six facts of the shared full inspector is not part of PR L2; until it
+  lands, the legacy page keeps COPY ALL and stays reachable from Overview.
+- Fully browser-local reading: kept and asserted (privacy above).
+- Case-variant keys `Workflow|comfy|ComfyUI|Prompt|Parameters` (LI-5): a separate
+  backend issue; Inspect follows the server's readers, so the two never disagree.
+
+`tests/browser/inspect-concept.spec.mjs` compares the page with the immutable concept's
+`#metadata` on the concept fixture, at 1600×1100 and 390×844 in both themes, on Chromium
+and touch, in three states: initial, selected (`f02.png` from the parity corpus set into
+both `#local-file` inputs with a real `setInputFiles`) and viewer-open (the heading
+action). `withProductionCopy` applies D60–D62 to the open concept page before it is
+measured (it throws if the concept's own copy changed), so the browser lays the concept
+out with production's words; `mapViewerConcept` applies D66 (title, no tag chips, no
+Prompt history). The diff of the heading, surface, drop area (icon, label, input, note),
+preview and viewer (dialog box, layout below its header, toolbar control order, rail
+section order) must then be empty. Pinned values are asserted on production: surface
+padding 22px and radius 7px; drop area dashed 1px border, radius 7px, min-height 170px,
+gap 12px, padding 22px, margin-top 20px; h2 17px/600; p 12px; input 12px and
+max-width 100%; preview max-height 400px, `object-fit: contain`, margin-top 20px. The
+chooser's displayed name is asserted to be `f02.png` in both documents. `mutation is
+noticed` makes the drop border solid (noticed on all four sides and nowhere else),
+renames the label and removes the note. Paired captures
+(`{concept,production}-{initial,selected,viewer}-{dark,light}-{1600,390}.png`) and
+`inspect-geometry.json` are attached as test artifacts; there are no PNG baselines.
+
+`tests/comfyui/inspect-sender.spec.mjs` (`local file roles send exactly across renderer
+transitions`) runs on the managed CPU host: the Inspect page reads a PNG whose positive
+spans lines and whose negative is a ConditioningZeroOut (explicitly empty) and
+`core-tags.webm`, and sends each pair to a Prompt Manager (+/-) node in Classic and
+Nodes 2.0, switching both ways with a graph reload each time. Each send previews the
+node's current and new roles, writes exactly those roles, and neither queues nor loads a
+workflow. A connected `negative_text` input rejects the whole preview with no change. The
+workspace page makes no non-GET request and logs neither filename nor prompt text.
+Follow-up (pair node, separate investigation): the node's `text` widget ignored a value
+set after a `PrimitiveString` linked `negative_text` (it kept its prior value), so this spec
+and `library-sender.spec.mjs` set the positive before connecting the negative input.
+
+```sh
+node --test tests/js/workspace-local-session.test.js tests/js/workspace-state.test.js
+npm run --prefix tools/vendor test:workflows -- inspect-concept.spec.mjs workspace-inspect.spec.mjs \
+  --project chromium --project touch --project firefox --project webkit
+npm run --prefix tools/vendor test:comfyui -- inspect-sender.spec.mjs
+```
+
 ## Workspace data fields for the concept pages (#249)
 
 These fields are additive. The legacy `/prompt_manager/images/output` listing (no
@@ -1087,6 +1712,83 @@ concept fixture stars the concept's favorites (each other prompt's first image).
   restore. Old backups without the table restore, and backup plus restore keeps
   WAL-resident favorites and closes every handle (`tests/test_database_backup.py`).
 
+Image annotations schema (#249, `database/annotation_schema.py`): the group
+`media_annotation_metadata` (one row: schema version, `image_index_revision`),
+`media_annotation_files` (one private locator per physical file,
+`normcase(join(realpath(root), relative))`, server-side only),
+`media_annotation_bytes` (one record per observed whole-file SHA-256 with the
+`size`/`mtime_ns` verified when those bytes were last seen and the set's
+`tag_revision`) and `media_image_tags` (the ordered tag set of one byte record,
+joined into the global `tags` registry). It installs like favorites: optional in
+old backups, required once current (`annotation_schema_error`, the single
+`require_library_state` flag), validated read-only before and after a SAVEPOINT
+install and on restore, never backfilled and never stat-ing media
+(`tests/test_annotation_schema.py`). Writers (`database/annotations.py`) always
+supply the UUID ids, run in `_pair_transaction` fenced by the storage epoch, and
+replace or union one byte record's set (`tag-conflict` / `tag-limit` with the
+current set, identical retries `replayed`); vocabulary rename, merge and delete
+carry `media_image_tags` through the one `_move_tag_links` loop, and tag rows,
+impact and command receipts report `image_count` / `images` /
+`images_changed` as files (`tests/test_annotations.py`,
+`tests/test_pair_tag_maintenance.py`, `tests/test_vocabulary.py`). Cheap reads
+(spec amendment S1) use a byte record only while the file's current
+`(size, mtime_ns)` equals its verified fingerprint; an in-place rewrite that
+preserves both keeps the old set matching until the file is next observed. The
+Images Tags filter (a file matches when every tag is on its linked positive or
+its current image tag set) and `q` search stream the tagged records once and
+stat only the listed files whose records carry a filter tag or a `q` hit; the
+inspector's `image_tags` facet (`current` / `none` / `unavailable`) uses the
+inspection's own stable stat (`tests/test_api_workspace_images.py`
+`TestWorkspaceImageTags`, `tests/test_api_prompt_inspector.py`). The
+browser fixtures clear `media_image_tags`, `media_annotation_bytes` and
+`media_annotation_files` on reset and never the metadata row.
+
+Capture store (#249, `utils/media_capture.py`, `tests/test_media_capture.py`):
+one explicit action captures one rooted media file into an owner-only
+`prompt-manager-captures-*` temp directory, streaming it in 1 MiB chunks while
+hashing. Identity is compared like with like: the opened descriptor against
+the path only on the API-stable facts (`size`, `mtime_ns`); the full identity
+(`size`, `mtime_ns`, `ctime_ns`, `dev`/`ino` where meaningful) between the
+`fstat` before and after the copy and between the path stats before and after
+(native Windows CI with Python 3.12/3.13 showed `stat` and `fstat` disagreeing
+on `st_ctime_ns`: change time versus creation time; 3.10/3.11 agree). Any
+disagreement is `CaptureChanged` and the copy is removed. Error messages carry
+`strerror` only, never a path. Aliases (a symlinked
+file or directory, even inside the root), escapes, non-media names and
+directories are `CaptureDenied`; the locator is
+`normcase(join(realpath(root), relative))`, so a symlinked root shares the
+listing's identity. Fixed limits: 256 MiB per file (stat and stream), 8
+completed captures, 512 MiB reserved, 2 capture/verify workers, 900 s idle,
+1800 s hard; admission is nonblocking (`CaptureCapacity`) and lifetimes are
+tested with an injected clock. An acquired capture outlives expiry and release
+until its last use ends. Header-only dimensions (4096 px per side,
+16,777,216 px) and video mark Generate unsupported; `verify` re-hashes the
+current file without a copy. Every handle closes before unlink (a patched
+`os.unlink` asserts it, plus `assert_closed`), and files are unlinked outside
+the store lock. Known limit: on Windows before Python 3.13 `fstat` reports the
+creation time, so a same-size rewrite that restores `mtime_ns` during the copy
+window completes there with a digest of the copied bytes; POSIX and Windows on
+3.13+ detect it through the descriptor's change time (native CI, 3.13 only).
+Vocabulary rename, merge and delete bump the `tag_revision` of every image set
+they change (and `image_index_revision`), so a Tag dialog opened before the
+change gets `tag-conflict` on Save (`tests/test_pair_tag_maintenance.py`).
+A case or Unicode spelling of a listed name (`A.PNG` for `a.png`, an NFD name)
+is an alias too: each path part must be spelled as its directory lists it, so a
+case- or normalization-insensitive filesystem (macOS, Windows) cannot store a
+second locator. The capture preview answers one byte range with 206 (416 for
+an unsatisfiable or multi-range header) inside the capture's pin, and a
+cancelled preview, observe or Generate still closes its handle and ends its pin
+or capture (`tests/test_api_annotations.py` `TestCancellation`,
+`tests/test_model_gate.py`).
+
+Follow-ups (tracked, not accepted): the legacy Auto-tag batch's cleanup
+`unload_model()` in `py/api/autotag_routes.py` is not gated against the
+batch's own in-flight inference when the batch coroutine is cancelled (other
+owners are kept out; the thread may log an error); and `py/autotag.py`,
+`py/api/images.py` and `database/operations.py` are over the 800-line ceiling
+(all three were before #249 PR B), with a split of `py/autotag.py` into
+backends and service planned first.
+
 Budgets: `test_filter_work_is_bounded` always runs. It asserts that a plain first
 page makes 1 link SELECT and a plain cursor page none, that every filter shape
 makes exactly 1, the covering-index plan, and that the per-file values are built
@@ -1357,7 +2059,7 @@ bytes at the same path without changing the immutable receipt.
 The focused acceptance command retains all four projects:
 
 ```sh
-PM_TEST_PORT=8766 npm run --prefix tools/vendor test:workflows -- \
+npm run --prefix tools/vendor test:workflows -- \
   workspace-history.spec.mjs workspace-visual.spec.mjs \
   --project chromium --project touch --project firefox --project webkit
 npm run --prefix tools/vendor test:executions
@@ -1390,8 +2092,8 @@ page lifecycle recovery retain their separate behavioral tests.
 Initial production acceptance requires maintainer inspection of paired PNGs and
 geometry; never update snapshots automatically or mask content to bless a gap.
 Data-dependent text/images/counts and the clearly labeled saved/frozen/current
-distinctions are documented in the comparison helper. The Images card tag
-button (#249 D9) remains outside #209; every prompt block now renders the concept's
+distinctions are documented in the comparison helper. The gallery cards carry the
+concept's Tag button beside Info (#249 C2 retired D9); every prompt block now renders the concept's
 `section.prompt-section` (D22), so the shared role-block spacing, padding and glyph
 gap is closed, and only the production-only surfaces above keep their own rules
 (D48). The
@@ -1399,6 +2101,47 @@ responsive production Viewer keeps its toolbar in the media panel and prompt det
 mobile toolbar collision. These are explicit remaining visual differences, not
 a whole-application or full-gallery/Viewer pixel-parity claim.
 
+Follow-up: monitor video support. The live image monitor (`utils/image_monitor.py`,
+`GalleryConfig.SUPPORTED_EXTENSIONS`) processes images only; videos written by
+ComfyUI savers reach the Library through the admin scan, which reads the shared video
+carrier. Accepting `VIDEO_EXTENSIONS` in the monitor and routing them through
+`read_video_metadata` is a separate, issue-linked change.
+
+Follow-up: local Inspect parity (#249 PR L1). The browser readers
+(`web/js/png-metadata.js`, `web/js/workspace/local-video.mjs`,
+`web/js/workspace/local-projection.mjs`) answer as the server does for the same bytes
+and a matching extension (`tests/test_local_inspect_parity.py`; the real-ffprobe cases
+skip without ffmpeg). The remaining known divergences, checked against ffprobe 9.0.2,
+`read_inspection_file` and `_metadata`, are tracked here, not accepted as parity:
+
+- Media kind comes from the bytes locally and from the extension on the server: a PNG
+  named `.mp4` is read as a PNG locally (format and size shown) while the server probes
+  it with ffprobe (no format, no size); MP4 bytes named `.png` read locally as video
+  while Pillow fails them on the server (`unreadable`). Parity is stated for the same
+  bytes with a matching extension.
+- JPEG dimensions: the local header read stops at 64 KiB, so a JPEG whose SOF follows
+  more than 64 KiB of APP segments (camera, Photoshop and EXIF/XMP workflow savers)
+  shows no dimensions, while Pillow reads them within the server's 8 MiB header bound.
+  The fix is a segment-header walk up to 8 MiB, which needs a plan amendment.
+- Classic QuickTime `moov/udta` text atoms (`©cmt`/`desc` with a 16-bit size and
+  language, outside `meta`) are not read locally; ffprobe reports them as
+  `comment`/`description`, so the server can select that envelope while the local
+  read is `absent`. No ComfyUI saver writes them.
+- Tag-size bounds count raw bytes locally and ffprobe's escaped JSON on the server
+  (first probe 12 MiB + 64 KiB, role-only re-probe 4 MiB + 64 KiB): only tag sets near
+  those bounds and dense with quotes or control characters can make one side re-probe
+  or fail while the other reads.
+- More than 10,000 container elements stop the local read (`limited`, metadata
+  `unreadable`); ffprobe reads such files.
+- An EBML DocType other than `matroska`/`webm` is an invalid container locally; ffmpeg
+  only warns and reads it.
+- Envelope JSON deeper than 1,000 levels is refused locally as Python's default
+  recursion limit refuses it; the server's real limit depends on the interpreter and
+  call stack. A duplicate key in an object enclosing a nest deeper than the running
+  Python's json limit is `malformed` locally and `limited` on that Python.
+- Decimal exponent limits assume CPython's C `_decimal`; on a `_pydecimal` interpreter
+  the server would read the over-limit exponents the local projection refuses.
+
 Preserve raw logs, failed traces, paired PNGs, geometry, runtime versions and
 source hashes before later managed commands clear their output directories.
 Frontend baseline updates are additive through `coverage:update` only after
@@ -1450,7 +2193,7 @@ acceptance; a baseline is added only after the maintainer accepts them.
 Focused commands:
 
 ```sh
-PM_TEST_PORT=8766 npm run --prefix tools/vendor test:workflows -- \
+npm run --prefix tools/vendor test:workflows -- \
   workspace-library-editor.spec.mjs library-editor-visual.spec.mjs \
   --project chromium --project touch --project firefox --project webkit
 npm run --prefix tools/vendor test:comfyui   # library-sender.spec.mjs host regression
@@ -1514,7 +2257,7 @@ legacy admin page. The screen consumes only the `/prompt_manager/vocabulary/*` r
 above and adds no route, so PR B needs no ComfyUI restart: a browser refresh is enough.
 
 Screen: a `+ Create tag` heading action, a Tag vocabulary table (columns Tag, Prompts,
-Images shown as "—" with hidden "Not available yet", and Actions with Browse and
+Images counting the files that carry the tag (`image_count`, #249 C2), and Actions with Browse and
 Rename / merge), and a Categories panel whose category rows end with the Manage
 category row (Review). Lists load 100 rows at a time, append when scrolled into view
 and keep `Load more tags` / `Load more categories` while more remain. Prompts counts
@@ -1550,13 +2293,12 @@ mobile, the concept geometry/token/control comparison and its mutation check),
 
 ```sh
 node --test tests/js/workspace-vocabulary-state.test.js tests/js/workspace-state.test.js
-PM_TEST_PORT=8766 npm run --prefix tools/vendor test:workflows -- \
+npm run --prefix tools/vendor test:workflows -- \
   workspace-vocabulary.spec.mjs vocabulary-visual.spec.mjs focused-node.spec.mjs \
   --project chromium --project touch --project firefox --project webkit
 ```
 
-Recorded deviations from the concept (maintainer acceptance): no Auto-tag images
-button and an Images "—" cell until the image-annotation slice; bounded lists with
+Recorded deviations from the concept (maintainer acceptance): bounded lists with
 Load more; title "Tags"; Manage categories adds a Category select and Preview before
 Apply; "Apply" instead of "Apply in prototype"; Delete tag… inside Rename or merge;
 Browse sets the exact filter; singular "1 positive prompt"; the production list appends

__init__.py

@@ -90,6 +90,7 @@ try:
     host_app = getattr(config.server_instance, "app", None)
     if host_app is not None and hasattr(host_app, "on_cleanup"):
         host_app.on_cleanup.append(api.cleanup_history_reads)
+        host_app.on_cleanup.append(api.cleanup_annotation_captures)
 
 except Exception as e:
     # Log to internal logging system without console spam

database/annotation_schema.py

@@ -0,0 +1,290 @@
+"""Image annotation schema group (#249): file locators, byte records, image tags.
+
+The group installs like ``image_favorites`` and ``saved_views``: optional in old
+backups, required once a database is current. It owns
+
+- ``media_annotation_metadata``: one row, the group's schema version and the
+  image index revision;
+- ``media_annotation_files``: one private canonical locator per physical file
+  (``normcase(join(realpath(root), relative))``, server-side only);
+- ``media_annotation_bytes``: one record per observed whole-file SHA-256 of a
+  file, with the size and ``mtime_ns`` verified when those bytes were last seen
+  and the tag set's revision;
+- ``media_image_tags``: the ordered image tag set of one byte record, joined
+  into the global ``tags`` registry so vocabulary maintenance carries image
+  links like prompt and pair links.
+
+Installation never backfills anything from prompt or pair tags and never
+touches the filesystem. Validation reads only: the catalog objects are compared
+after whitespace compaction, columns, foreign keys and indexes through the
+PRAGMAs, and persisted values in single bounded SQL passes.
+"""
+
+import re
+import sqlite3
+from typing import Optional
+
+from .image_favorites import MAX_KEY_LENGTH
+
+SCHEMA_VERSION = 1
+METADATA_TABLE = "media_annotation_metadata"
+FILES_TABLE = "media_annotation_files"
+BYTES_TABLE = "media_annotation_bytes"
+IMAGE_TAGS_TABLE = "media_image_tags"
+TABLES = (METADATA_TABLE, FILES_TABLE, BYTES_TABLE, IMAGE_TAGS_TABLE)
+MAX_LOCATOR_LENGTH = MAX_KEY_LENGTH
+_TIMESTAMP_BYTES = 64
+
+_TABLE_DDL = {
+    METADATA_TABLE: (
+        f"CREATE TABLE {METADATA_TABLE} (singleton_id INTEGER PRIMARY KEY "
+        "CHECK(singleton_id=1), schema_version INTEGER NOT NULL "
+        f"CHECK(schema_version={SCHEMA_VERSION}), "
+        "image_index_revision INTEGER NOT NULL DEFAULT 0 "
+        "CHECK(image_index_revision>=0))"
+    ),
+    FILES_TABLE: (
+        f"CREATE TABLE {FILES_TABLE} (id TEXT PRIMARY KEY CHECK(length(id)=36), "
+        "locator TEXT NOT NULL UNIQUE, created_at TEXT NOT NULL)"
+    ),
+    BYTES_TABLE: (
+        f"CREATE TABLE {BYTES_TABLE} (id TEXT PRIMARY KEY CHECK(length(id)=36), "
+        f"file_id TEXT NOT NULL REFERENCES {FILES_TABLE}(id) ON DELETE CASCADE, "
+        "sha256 TEXT NOT NULL CHECK(length(sha256)=64 AND sha256 NOT GLOB "
+        "'*[^0-9a-f]*'), size INTEGER NOT NULL CHECK(size>=0), "
+        "mtime_ns INTEGER NOT NULL, verified_at TEXT NOT NULL, "
+        "first_seen_at TEXT NOT NULL, tag_revision INTEGER NOT NULL DEFAULT 0 "
+        "CHECK(tag_revision>=0), UNIQUE(file_id, sha256))"
+    ),
+    IMAGE_TAGS_TABLE: (
+        f"CREATE TABLE {IMAGE_TAGS_TABLE} (byte_id TEXT NOT NULL REFERENCES "
+        f"{BYTES_TABLE}(id) ON DELETE CASCADE, tag_id INTEGER NOT NULL "
+        "REFERENCES tags(id) ON DELETE CASCADE, position INTEGER NOT NULL "
+        "CHECK(position>=0), PRIMARY KEY(byte_id, tag_id))"
+    ),
+}
+_INDEX_DDL = {
+    "idx_media_annotation_bytes_fingerprint": (
+        "CREATE INDEX idx_media_annotation_bytes_fingerprint ON "
+        f"{BYTES_TABLE}(file_id, size, mtime_ns)"
+    ),
+    "idx_media_image_tags_tag": (
+        f"CREATE INDEX idx_media_image_tags_tag ON {IMAGE_TAGS_TABLE}(tag_id)"
+    ),
+    "idx_media_image_tags_position": (
+        "CREATE UNIQUE INDEX idx_media_image_tags_position ON "
+        f"{IMAGE_TAGS_TABLE}(byte_id, position)"
+    ),
+}
+# SQLite names the indexes behind TEXT primary keys and UNIQUE constraints
+# ``sqlite_autoindex_<table>_<n>``; their catalog rows carry no SQL.
+_AUTOINDEXES = {FILES_TABLE: 2, BYTES_TABLE: 2, IMAGE_TAGS_TABLE: 1}
+# (name, declared type, not null, default, primary key position)
+_COLUMNS = {
+    METADATA_TABLE: (
+        ("singleton_id", "INTEGER", 0, None, 1),
+        ("schema_version", "INTEGER", 1, None, 0),
+        ("image_index_revision", "INTEGER", 1, "0", 0),
+    ),
+    FILES_TABLE: (
+        ("id", "TEXT", 0, None, 1),
+        ("locator", "TEXT", 1, None, 0),
+        ("created_at", "TEXT", 1, None, 0),
+    ),
+    BYTES_TABLE: (
+        ("id", "TEXT", 0, None, 1),
+        ("file_id", "TEXT", 1, None, 0),
+        ("sha256", "TEXT", 1, None, 0),
+        ("size", "INTEGER", 1, None, 0),
+        ("mtime_ns", "INTEGER", 1, None, 0),
+        ("verified_at", "TEXT", 1, None, 0),
+        ("first_seen_at", "TEXT", 1, None, 0),
+        ("tag_revision", "INTEGER", 1, "0", 0),
+    ),
+    IMAGE_TAGS_TABLE: (
+        ("byte_id", "TEXT", 1, None, 1),
+        ("tag_id", "INTEGER", 1, None, 2),
+        ("position", "INTEGER", 1, None, 0),
+    ),
+}
+# (column, parent table, parent column, on delete)
+_FOREIGN_KEYS = {
+    METADATA_TABLE: set(),
+    FILES_TABLE: set(),
+    BYTES_TABLE: {("file_id", FILES_TABLE, "id", "CASCADE")},
+    IMAGE_TAGS_TABLE: {
+        ("byte_id", BYTES_TABLE, "id", "CASCADE"),
+        ("tag_id", "tags", "id", "CASCADE"),
+    },
+}
+
+
+def _compact(sql: str) -> str:
+    return re.sub(r"\s+", "", sql).lower()
+
+
+def _uuid(column: str) -> str:
+    """SQL: *column* is a lowercase hyphenated 36-character UUID string."""
+    return (
+        f"typeof({column}) = 'text' AND length({column}) = 36 "
+        f"AND substr({column}, 9, 1) = '-' AND substr({column}, 14, 1) = '-' "
+        f"AND substr({column}, 19, 1) = '-' AND substr({column}, 24, 1) = '-' "
+        f"AND length(replace({column}, '-', '')) = 32 "
+        f"AND replace({column}, '-', '') NOT GLOB '*[^0-9a-f]*'"
+    )
+
+
+def _timestamp(column: str) -> str:
+    return (
+        f"typeof({column}) = 'text' "
+        f"AND length(CAST({column} AS BLOB)) <= {_TIMESTAMP_BYTES}"
+    )
+
+
+def _non_negative(column: str) -> str:
+    return f"typeof({column}) = 'integer' AND {column} >= 0"
+
+
+# Every row of a table must satisfy its predicate; one pass each, LIMIT 1.
+_ROW_PREDICATES = {
+    FILES_TABLE: " AND ".join(
+        (
+            _uuid("id"),
+            "typeof(locator) = 'text'",
+            # UTF-8 is at most 4 bytes per character; the decoded length of
+            # the few candidates above the byte bound is checked in Python.
+            f"length(CAST(locator AS BLOB)) <= {MAX_LOCATOR_LENGTH * 4}",
+            _timestamp("created_at"),
+        )
+    ),
+    BYTES_TABLE: " AND ".join(
+        (
+            _uuid("id"),
+            _uuid("file_id"),
+            "typeof(sha256) = 'text' AND length(sha256) = 64 "
+            "AND sha256 NOT GLOB '*[^0-9a-f]*'",
+            _non_negative("size"),
+            "typeof(mtime_ns) = 'integer'",
+            _timestamp("verified_at"),
+            _timestamp("first_seen_at"),
+            _non_negative("tag_revision"),
+        )
+    ),
+    IMAGE_TAGS_TABLE: " AND ".join(
+        (_uuid("byte_id"), "typeof(tag_id) = 'integer'", _non_negative("position"))
+    ),
+}
+
+
+def _expected_catalog() -> set:
+    objects = {("table", name, _compact(sql)) for name, sql in _TABLE_DDL.items()}
+    objects |= {("index", name, _compact(sql)) for name, sql in _INDEX_DDL.items()}
+    objects |= {
+        ("index", f"sqlite_autoindex_{table}_{n}", "")
+        for table, count in _AUTOINDEXES.items()
+        for n in range(1, count + 1)
+    }
+    return objects
+
+
+def _catalog(conn: sqlite3.Connection) -> list:
+    names = TABLES + tuple(_INDEX_DDL)
+    marks = ",".join("?" * len(names))
+    table_marks = ",".join("?" * len(TABLES))
+    return conn.execute(  # only "?" placeholders are interpolated
+        "SELECT type,name,sql FROM sqlite_master "
+        f"WHERE name IN ({marks}) OR tbl_name IN ({table_marks})",  # nosec B608
+        names + TABLES,
+    ).fetchall()
+
+
+def _structure_error(conn: sqlite3.Connection) -> Optional[str]:
+    for table, expected in _COLUMNS.items():
+        columns = tuple(
+            (row[1], row[2].upper(), row[3], row[4], row[5])
+            for row in conn.execute(f"PRAGMA table_info({table})")
+        )
+        if columns != expected:
+            return f"Image annotations table {table} has invalid columns"
+        foreign_keys = {
+            (row[3], row[2], row[4], row[6])
+            for row in conn.execute(f"PRAGMA foreign_key_list({table})")
+        }
+        if foreign_keys != _FOREIGN_KEYS[table]:
+            return f"Image annotations table {table} has invalid foreign keys"
+        if conn.execute(f"PRAGMA foreign_key_check({table})").fetchone():
+            return f"Image annotations table {table} contains foreign key violations"
+    return None
+
+
+def _value_error(conn: sqlite3.Connection) -> Optional[str]:
+    # Only this module's constants are interpolated into the SQL below.
+    rows = conn.execute(
+        "SELECT COUNT(*), MIN(typeof(singleton_id) = 'integer' "  # nosec B608
+        "AND singleton_id = 1 AND typeof(schema_version) = 'integer' "
+        f"AND schema_version = {SCHEMA_VERSION} "
+        f"AND {_non_negative('image_index_revision')}) FROM {METADATA_TABLE}"
+    ).fetchone()
+    if rows[0] != 1 or rows[1] != 1:
+        return "Image annotations metadata is invalid"
+    for table, predicate in _ROW_PREDICATES.items():
+        if conn.execute(
+            f"SELECT 1 FROM {table} WHERE NOT ({predicate}) LIMIT 1"  # nosec B608
+        ).fetchone():
+            return f"Image annotations table {table} contains invalid values"
+    # length() stops at an embedded NUL, so the SQL pass bounds bytes and the
+    # few candidates over the character bound are measured decoded here.
+    for (raw,) in conn.execute(
+        f"SELECT CAST(locator AS BLOB) FROM {FILES_TABLE} "  # nosec B608
+        f"WHERE length(CAST(locator AS BLOB)) > {MAX_LOCATOR_LENGTH}"
+    ):
+        if len(bytes(raw).decode("utf-8", "replace")) > MAX_LOCATOR_LENGTH:
+            return f"Image annotations table {FILES_TABLE} contains invalid values"
+    return None
+
+
+def annotation_schema_error(
+    conn: sqlite3.Connection, *, allow_missing: bool = True
+) -> Optional[str]:
+    """Reject partial or unsupported annotation schemas and invalid rows.
+
+    Reads only: nothing is ever repaired. A database without any of the
+    group's objects is acceptable for backups that predate it unless
+    ``allow_missing`` is false.
+    """
+    objects = _catalog(conn)
+    if not objects:
+        return None if allow_missing else "Missing image annotation schema"
+    present = {name for kind, name, _sql in objects if kind == "table"}
+    if present != set(TABLES):
+        return "Incomplete image annotation schema"
+    actual = {(kind, name, _compact(sql or "")) for kind, name, sql in objects}
+    if actual != _expected_catalog():
+        return "Image annotations has an invalid schema definition"
+    return _structure_error(conn) or _value_error(conn)
+
+
+def migrate_annotation_state(conn: sqlite3.Connection) -> None:
+    """Install the group atomically; validate before and after creating it."""
+    conn.execute("SAVEPOINT media_annotation_schema")
+    try:
+        error = annotation_schema_error(conn)
+        if error:
+            raise sqlite3.DatabaseError(error)
+        for sql in _TABLE_DDL.values():
+            conn.execute(sql.replace("CREATE TABLE", "CREATE TABLE IF NOT EXISTS", 1))
+        for sql in _INDEX_DDL.values():
+            conn.execute(sql.replace("INDEX", "INDEX IF NOT EXISTS", 1))
+        conn.execute(
+            f"INSERT OR IGNORE INTO {METADATA_TABLE} "
+            "(singleton_id, schema_version, image_index_revision) VALUES (1, ?, 0)",
+            (SCHEMA_VERSION,),
+        )
+        error = annotation_schema_error(conn, allow_missing=False)
+        if error:
+            raise sqlite3.DatabaseError(error)
+        conn.execute("RELEASE media_annotation_schema")
+    except BaseException:
+        conn.execute("ROLLBACK TO media_annotation_schema")
+        conn.execute("RELEASE media_annotation_schema")
+        raise

database/annotations.py

@@ -0,0 +1,461 @@
+"""Per-image tag sets (#249): byte-exact storage in the shared vocabulary.
+
+A tag set belongs to one byte record (``media_annotation_bytes``): the
+whole-file SHA-256 of one physical file, owned by the file's private locator
+(``media_annotation_files``). Callers pass verified facts (digest, size,
+``mtime_ns``); nothing here reads the filesystem or resolves an owner through
+prompt links, so tagging one image never changes another image, a prompt or a
+pair.
+
+Commands run in one ``_pair_transaction`` fenced by the storage epoch, like the
+native Library and vocabulary commands. A save is a full replacement guarded
+by the set's ``tag_revision``; the identical set sent again (a lost-response
+retry, or the current set at its own revision) answers ``replayed: true`` and
+writes nothing. ``add_image_tags`` unions into the existing set, keeping the
+stored spelling. Names enter the global ``tags`` registry exactly as spelled,
+so vocabulary rename, merge and delete carry image links with prompt and pair
+links (``PromptDatabase._move_tag_links``).
+
+Cheap reads (spec amendment S1) treat a byte record as *current* only while
+the file's present ``(size, mtime_ns)`` equals the record's verified
+fingerprint; a file without a current record shows no image tags.
+"""
+
+import re
+import sqlite3
+from contextlib import contextmanager
+from typing import Iterator
+from uuid import uuid4
+
+from .annotation_schema import (
+    BYTES_TABLE,
+    FILES_TABLE,
+    IMAGE_TAGS_TABLE,
+    MAX_LOCATOR_LENGTH,
+    METADATA_TABLE,
+)
+from .library_commands import _UUID, LibraryCommandError, _validate_epoch
+from .models import utc_now_iso
+from .vocabulary import validate_vocabulary_tag_name
+
+MAX_IMAGE_TAGS = 100
+_LOOKUP_CHUNK = 500
+_DIGEST = re.compile(r"[0-9a-f]{64}")
+_MAX_INT = 2**63 - 1
+_MIN_INT = -(2**63)
+# Only this module's table constants are interpolated into the SQL below.
+_OWNER = f"SELECT id FROM {FILES_TABLE} WHERE locator=?"  # nosec B608
+_INSERT_OWNER = (
+    f"INSERT INTO {FILES_TABLE}(id,locator,created_at) VALUES(?,?,?)"  # nosec B608
+)
+_BYTE = (
+    f"SELECT id,tag_revision,size,mtime_ns FROM {BYTES_TABLE} "  # nosec B608
+    "WHERE file_id=? AND sha256=?"
+)
+_INSERT_BYTE = (
+    f"INSERT INTO {BYTES_TABLE}(id,file_id,sha256,size,mtime_ns,"  # nosec B608
+    "verified_at,first_seen_at,tag_revision) VALUES(?,?,?,?,?,?,?,0)"
+)
+_REFRESH_BYTE = (
+    f"UPDATE {BYTES_TABLE} SET size=?,mtime_ns=?,verified_at=? WHERE id=?"  # nosec B608
+)
+_REFRESH_BY_LOCATOR = (
+    f"UPDATE {BYTES_TABLE} SET size=?,mtime_ns=?,verified_at=? "  # nosec B608
+    f"WHERE sha256=? AND file_id=({_OWNER})"
+)
+_BYTE_TAGS = (
+    f"SELECT t.name FROM {IMAGE_TAGS_TABLE} mit "  # nosec B608
+    "JOIN tags t ON t.id=mit.tag_id WHERE mit.byte_id=? ORDER BY mit.position"
+)
+_CLEAR_TAGS = f"DELETE FROM {IMAGE_TAGS_TABLE} WHERE byte_id=?"  # nosec B608
+_INSERT_TAG = (
+    f"INSERT INTO {IMAGE_TAGS_TABLE}(byte_id,tag_id,position) "  # nosec B608
+    "VALUES(?,?,?)"
+)
+_BUMP_REVISION = (
+    f"UPDATE {BYTES_TABLE} SET tag_revision=tag_revision+1 WHERE id=?"  # nosec B608
+)
+_REVISION = f"SELECT tag_revision FROM {BYTES_TABLE} WHERE id=?"  # nosec B608
+_BUMP_INDEX = (
+    f"UPDATE {METADATA_TABLE} SET "  # nosec B608
+    "image_index_revision=image_index_revision+1 WHERE singleton_id=1"
+)
+_READ = (
+    "SELECT b.id,b.tag_revision,"  # nosec B608
+    f"(SELECT COUNT(*) FROM {BYTES_TABLE} o WHERE o.file_id=f.id AND o.sha256!=?) "
+    f"FROM {FILES_TABLE} f LEFT JOIN {BYTES_TABLE} b "
+    "ON b.file_id=f.id AND b.sha256=? WHERE f.locator=?"
+)
+_FINGERPRINTS = (
+    "SELECT f.locator,b.id,b.size,b.mtime_ns,b.verified_at "  # nosec B608
+    f"FROM {FILES_TABLE} f JOIN {BYTES_TABLE} b ON b.file_id=f.id "
+    "WHERE f.locator IN ({marks})"
+)
+_TAGS_OF = (
+    f"SELECT mit.byte_id,t.name FROM {IMAGE_TAGS_TABLE} mit "  # nosec B608
+    "JOIN tags t ON t.id=mit.tag_id WHERE mit.byte_id IN ({marks}) "
+    "ORDER BY mit.byte_id,mit.position"
+)
+_RECORDS = (
+    "SELECT f.locator,b.id,b.size,b.mtime_ns,t.name "  # nosec B608
+    f"FROM {FILES_TABLE} f JOIN {BYTES_TABLE} b ON b.file_id=f.id "
+    f"LEFT JOIN {IMAGE_TAGS_TABLE} mit ON mit.byte_id=b.id "
+    "LEFT JOIN tags t ON t.id=mit.tag_id "
+    "ORDER BY f.locator,b.first_seen_at,b.id,mit.position"
+)
+
+
+class AnnotationCommandError(LibraryCommandError):
+    """An image tag command lost a race or hit the set's bound.
+
+    ``code`` is ``tag-conflict`` (the set changed since it was read) or
+    ``tag-limit`` (the union would exceed ``MAX_IMAGE_TAGS``); ``current`` is
+    the stored set ``{sha256, tags, tag_revision}`` read inside the
+    transaction, so the caller can show it.
+    """
+
+    def __init__(self, code: str, epoch: str, current: dict | None = None):
+        super().__init__(code, epoch)
+        self.current = current
+
+
+class ImageTagLimitError(ValueError):
+    """More than ``MAX_IMAGE_TAGS`` distinct names in one set."""
+
+
+def normalize_image_tags(names: object) -> list[str]:
+    """Trim and validate each name, fold case-insensitive repeats, cap at 100.
+
+    The first occurrence keeps its spelling and position. Raises ``ValueError``
+    for anything but a list of valid vocabulary names, and its subclass
+    ``ImageTagLimitError`` for more than ``MAX_IMAGE_TAGS`` distinct names.
+    """
+    if not isinstance(names, list):
+        raise ValueError("tags must be a list of strings")
+    result: list[str] = []
+    seen: set[str] = set()
+    for value in names:
+        name = validate_vocabulary_tag_name(value)
+        key = name.casefold()
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(name)
+    if len(result) > MAX_IMAGE_TAGS:
+        raise ImageTagLimitError(f"An image can carry at most {MAX_IMAGE_TAGS} tags")
+    return result
+
+
+def _validate_locator(locator: object) -> None:
+    if not isinstance(locator, str) or not 0 < len(locator) <= MAX_LOCATOR_LENGTH:
+        raise ValueError(
+            f"locator must be a nonblank path of at most {MAX_LOCATOR_LENGTH} chars"
+        )
+
+
+def _validate_digest(sha256: object) -> None:
+    if not isinstance(sha256, str) or not _DIGEST.fullmatch(sha256):
+        raise ValueError("sha256 must be 64 lowercase hexadecimal characters")
+
+
+def _validate_int(value: object, name: str, minimum: int) -> None:
+    if type(value) is not int or not minimum <= value <= _MAX_INT:
+        raise ValueError(f"{name} must be an integer not below {minimum}")
+
+
+def _validate_target(locator: object, sha256: object, size: object, mtime_ns: object):
+    _validate_locator(locator)
+    _validate_digest(sha256)
+    _validate_int(size, "size", 0)
+    _validate_int(mtime_ns, "mtime_ns", _MIN_INT)
+
+
+def _validate_fingerprint(locator: object, fingerprint: object) -> None:
+    _validate_locator(locator)
+    if (
+        not isinstance(fingerprint, tuple)
+        or len(fingerprint) != 2
+        or any(type(value) is not int for value in fingerprint)
+    ):
+        raise ValueError("stats must map locators to (size, mtime_ns) integer pairs")
+
+
+def _new_id() -> str:
+    """A canonical UUID; the schema's CHECK lets NULL through, this does not."""
+    value = str(uuid4())
+    if not _UUID.fullmatch(value):
+        raise ValueError("Annotation ids must be canonical UUIDs")
+    return value
+
+
+def _receipt(epoch: str, sha256: str, tags: list, revision: int, replayed: bool):
+    return {
+        "library_epoch": epoch,
+        "sha256": sha256,
+        "tags": list(tags),
+        "tag_revision": revision,
+        "replayed": replayed,
+    }
+
+
+class AnnotationOperations:
+    """PromptDatabase mixin: image tag sets, fingerprints and cheap reads.
+
+    ``_`` helpers take the open ``_pair_transaction`` connection.
+    """
+
+    @contextmanager
+    def _annotation_read(self) -> Iterator[sqlite3.Connection]:
+        """One deferred read transaction, so paired SELECTs see one snapshot."""
+        conn = self.model.get_connection()
+        if conn.in_transaction:
+            raise sqlite3.ProgrammingError(
+                "Annotation reads require their own snapshot"
+            )
+        with conn:
+            conn.execute("BEGIN")
+            yield conn
+
+    @staticmethod
+    def _annotation_owner(conn: sqlite3.Connection, locator: str, now: str) -> str:
+        row = conn.execute(_OWNER, (locator,)).fetchone()
+        if row is not None:
+            return row[0]
+        file_id = _new_id()
+        conn.execute(_INSERT_OWNER, (file_id, locator, now))
+        return file_id
+
+    @staticmethod
+    def _annotation_byte(
+        conn: sqlite3.Connection,
+        file_id: str,
+        sha256: str,
+        size: int,
+        mtime_ns: int,
+        now: str,
+    ) -> tuple[str, int, bool, bool]:
+        """The byte record for these bytes, refreshed or created.
+
+        Returns ``(id, tag_revision, created, refingerprinted)``; the last is
+        True when an existing record's verified ``(size, mtime_ns)`` changed,
+        which moves its currency for cheap reads (the caller bumps the index
+        revision when nothing else does).
+        """
+        row = conn.execute(_BYTE, (file_id, sha256)).fetchone()
+        if row is None:
+            byte_id = _new_id()
+            conn.execute(
+                _INSERT_BYTE, (byte_id, file_id, sha256, size, mtime_ns, now, now)
+            )
+            return byte_id, 0, True, False
+        conn.execute(_REFRESH_BYTE, (size, mtime_ns, now, row[0]))
+        return row[0], row[1], False, (row[2], row[3]) != (size, mtime_ns)
+
+    @staticmethod
+    def _byte_tags(conn: sqlite3.Connection, byte_id: str) -> list[str]:
+        return [row[0] for row in conn.execute(_BYTE_TAGS, (byte_id,))]
+
+    def _write_image_tags(
+        self, conn: sqlite3.Connection, byte_id: str, tags: list[str]
+    ) -> int:
+        """Rewrite the junction in order, bump both revisions; return the new one."""
+        tag_ids = self._ensure_tags(conn, tags)
+        conn.execute(_CLEAR_TAGS, (byte_id,))
+        conn.executemany(
+            _INSERT_TAG,
+            [(byte_id, tag_ids[name], position) for position, name in enumerate(tags)],
+        )
+        conn.execute(_BUMP_REVISION, (byte_id,))
+        conn.execute(_BUMP_INDEX)
+        return conn.execute(_REVISION, (byte_id,)).fetchone()[0]
+
+    def _current_set(self, conn, sha256, byte_id, revision) -> dict:
+        return {
+            "sha256": sha256,
+            "tags": self._byte_tags(conn, byte_id),
+            "tag_revision": revision,
+        }
+
+    def read_image_tags(self, locator: str, sha256: str) -> dict:
+        """The stored set of these exact bytes, or an empty set at revision 0.
+
+        ``prior_count`` is the number of other byte records at the locator
+        (earlier or later bytes of the same file).
+        """
+        _validate_locator(locator)
+        _validate_digest(sha256)
+        with self._annotation_read() as conn:
+            row = conn.execute(_READ, (sha256, sha256, locator)).fetchone()
+            if row is None:
+                return {"tags": [], "tag_revision": 0, "prior_count": 0}
+            tags = self._byte_tags(conn, row[0]) if row[0] is not None else []
+            return {"tags": tags, "tag_revision": row[1] or 0, "prior_count": row[2]}
+
+    def replace_image_tags(
+        self,
+        *,
+        locator: str,
+        sha256: str,
+        size: int,
+        mtime_ns: int,
+        expected_epoch: str,
+        expected_tag_revision: int,
+        tags: list,
+    ) -> dict:
+        """Replace the set of these exact bytes, guarded by epoch and revision.
+
+        Creates the owner and byte record when the bytes are new (an explicit
+        empty set is a real save). The identical set at the current revision,
+        or one behind it (a lost-response retry), is ``replayed`` and writes
+        nothing; any other revision mismatch is ``tag-conflict`` with the
+        current set and no writes.
+        """
+        _validate_target(locator, sha256, size, mtime_ns)
+        _validate_epoch(expected_epoch)
+        _validate_int(expected_tag_revision, "expected_tag_revision", 0)
+        tags = normalize_image_tags(tags)
+        with self._pair_transaction() as conn:
+            epoch = self._library_epoch(conn, expected_epoch)
+            now = utc_now_iso()
+            file_id = self._annotation_owner(conn, locator, now)
+            byte_id, revision, created, refingerprinted = self._annotation_byte(
+                conn, file_id, sha256, size, mtime_ns, now
+            )
+            current = self._byte_tags(conn, byte_id)
+            if (
+                not created
+                and current == tags
+                and expected_tag_revision in (revision, revision - 1)
+            ):
+                if refingerprinted:
+                    conn.execute(_BUMP_INDEX)
+                return _receipt(epoch, sha256, current, revision, True)
+            if expected_tag_revision != revision:
+                raise AnnotationCommandError(
+                    "tag-conflict",
+                    epoch,
+                    {"sha256": sha256, "tags": current, "tag_revision": revision},
+                )
+            revision = self._write_image_tags(conn, byte_id, tags)
+            return _receipt(epoch, sha256, tags, revision, False)
+
+    def add_image_tags(
+        self,
+        *,
+        locator: str,
+        sha256: str,
+        size: int,
+        mtime_ns: int,
+        expected_epoch: str,
+        tags: list,
+    ) -> dict:
+        """Union ``tags`` into the set of these exact bytes, keeping stored spelling.
+
+        ``added`` counts the names that were new (case-insensitively). A union
+        over ``MAX_IMAGE_TAGS`` is ``tag-limit`` with the current set and no
+        writes; a union that adds nothing to an existing record is ``replayed``.
+        """
+        _validate_target(locator, sha256, size, mtime_ns)
+        _validate_epoch(expected_epoch)
+        tags = normalize_image_tags(tags)
+        with self._pair_transaction() as conn:
+            epoch = self._library_epoch(conn, expected_epoch)
+            now = utc_now_iso()
+            file_id = self._annotation_owner(conn, locator, now)
+            byte_id, revision, created, refingerprinted = self._annotation_byte(
+                conn, file_id, sha256, size, mtime_ns, now
+            )
+            current = self._byte_tags(conn, byte_id)
+            present = {name.casefold() for name in current}
+            added = [name for name in tags if name.casefold() not in present]
+            merged = current + added
+            if len(merged) > MAX_IMAGE_TAGS:
+                raise AnnotationCommandError(
+                    "tag-limit",
+                    epoch,
+                    {"sha256": sha256, "tags": current, "tag_revision": revision},
+                )
+            if not created and not added:
+                if refingerprinted:
+                    conn.execute(_BUMP_INDEX)
+                return {**_receipt(epoch, sha256, current, revision, True), "added": 0}
+            revision = self._write_image_tags(conn, byte_id, merged)
+            return {
+                **_receipt(epoch, sha256, merged, revision, False),
+                "added": len(added),
+            }
+
+    def refresh_image_fingerprint(
+        self, locator: str, sha256: str, size: int, mtime_ns: int
+    ) -> bool:
+        """Record that these exact bytes were just seen with this stat.
+
+        True when a byte record was refreshed; nothing is created and no tag
+        or tag revision changes. The image index revision moves because the
+        record's currency for cheap reads may have changed.
+        """
+        _validate_target(locator, sha256, size, mtime_ns)
+        with self.model.get_connection() as conn:
+            cursor = conn.execute(
+                _REFRESH_BY_LOCATOR, (size, mtime_ns, utc_now_iso(), sha256, locator)
+            )
+            if cursor.rowcount > 0:
+                conn.execute(_BUMP_INDEX)
+            return cursor.rowcount > 0
+
+    def current_image_tags(self, stats: dict) -> dict:
+        """Image tags of the files whose current ``(size, mtime_ns)`` is verified.
+
+        ``stats`` maps locators to their present fingerprint. A locator is
+        answered (possibly with an empty set) only when a byte record carries
+        exactly that verified fingerprint; the most recently verified record
+        wins when several do. Lookups go in chunks of 500 locators.
+        """
+        if not isinstance(stats, dict):
+            raise ValueError(
+                "stats must map locators to (size, mtime_ns) integer pairs"
+            )
+        for locator, fingerprint in stats.items():
+            _validate_fingerprint(locator, fingerprint)
+        locators = list(stats)
+        chosen: dict[str, tuple[tuple[str, str], str]] = {}
+        result: dict[str, list[str]] = {}
+        with self._annotation_read() as conn:
+            for start in range(0, len(locators), _LOOKUP_CHUNK):
+                chunk = locators[start : start + _LOOKUP_CHUNK]
+                marks = ",".join("?" * len(chunk))
+                for locator, byte_id, size, mtime_ns, verified_at in conn.execute(
+                    _FINGERPRINTS.format(marks=marks), chunk
+                ):
+                    if (size, mtime_ns) != stats[locator]:
+                        continue
+                    key = (verified_at, byte_id)
+                    if locator not in chosen or key > chosen[locator][0]:
+                        chosen[locator] = (key, byte_id)
+            owners = {byte_id: locator for locator, (_key, byte_id) in chosen.items()}
+            result = {locator: [] for locator in chosen}
+            byte_ids = list(owners)
+            for start in range(0, len(byte_ids), _LOOKUP_CHUNK):
+                chunk = byte_ids[start : start + _LOOKUP_CHUNK]
+                marks = ",".join("?" * len(chunk))
+                for byte_id, name in conn.execute(_TAGS_OF.format(marks=marks), chunk):
+                    result[owners[byte_id]].append(name)
+        return result
+
+    def iter_image_tag_records(self) -> Iterator[tuple[str, int, int, list[str]]]:
+        """Stream every byte record as ``(locator, size, mtime_ns, tags)``.
+
+        One SELECT ordered by locator, then by the bytes' first sighting, with
+        each set's names in position order.
+        """
+        conn = self.model.get_connection()
+        current: tuple | None = None
+        for locator, byte_id, size, mtime_ns, name in conn.execute(_RECORDS):
+            if current is None or current[0] != byte_id:
+                if current is not None:
+                    yield current[1]
+                current = (byte_id, (locator, size, mtime_ns, []))
+            if name is not None:
+                current[1][3].append(name)
+        if current is not None:
+            yield current[1]

database/models.py

@@ -17,6 +17,7 @@ from typing import Optional, Set, Tuple
 
 from .library_schema import library_schema_error, migrate_library_state
 from .image_favorites import image_favorites_schema_error, migrate_image_favorites
+from .annotation_schema import annotation_schema_error, migrate_annotation_state
 from .saved_views import migrate_saved_views, saved_views_schema_error
 from .execution_history_schema import (
     history_schema_error,
@@ -302,6 +303,7 @@ class PromptModel:
         migrate_library_state(conn)
         migrate_image_favorites(conn)
         migrate_saved_views(conn)
+        migrate_annotation_state(conn)
 
     def _migrate_prompt_pairs(self, conn: sqlite3.Connection) -> None:
         conn.execute("SAVEPOINT prompt_pair_schema")
@@ -1021,9 +1023,9 @@ class PromptModel:
         Args:
             path: File to inspect
             require_library_state: Also require the tables every current
-                database has (Library state, image favorites and saved
-                views), as a migrated restore stage must; old backups may
-                lack them.
+                database has (Library state, image favorites, saved views
+                and image annotations), as a migrated restore stage must;
+                old backups may lack them.
 
         Returns:
             (ok, reason): reason is "ok" when the file is acceptable, otherwise
@@ -1088,6 +1090,11 @@ class PromptModel:
             )
             if views_error:
                 return False, views_error
+            annotation_error = annotation_schema_error(
+                conn, allow_missing=not require_library_state
+            )
+            if annotation_error:
+                return False, annotation_error
             return True, "ok"
         except sqlite3.Error as e:
             return False, f"Invalid SQLite database: {e}"

database/operations.py

@@ -12,6 +12,7 @@ from .models import PromptModel, normalize_image_path, utc_now_iso
 from .pairs import PairDependencyError, PairOperations
 from .library import LibraryOperations, titled
 from .image_favorites import ImageFavoriteOperations
+from .annotations import AnnotationOperations
 from .saved_views import SavedViewOperations
 from .library_commands import LibraryCommandOperations
 from .vocabulary import VocabularyOperations
@@ -181,6 +182,21 @@ AND p.id NOT IN (SELECT prompt_id FROM live_hint_prompts)
 """
 
 
+# The scan's known set (#249 Activity-2): every image row, with its stored file
+# size and whether its pair link is resolved: exactly one distinct pair, the rule
+# _LINK_SUMMARY_SQL and get_image_prompt_info use. A file is known and resolved
+# when it has exactly one image row, that row is resolved, and the row's stored
+# size equals the file's size now; several rows (one file linked to more than
+# one prompt) are ambiguous, and an unknown (NULL) stored size is not known. The
+# rows are streamed in fetches of KNOWN_PATHS_FETCH_SIZE and only the scanned
+# paths are kept, so memory follows the scan (at most MAX_SCAN_FILES paths), not
+# the table.
+_KNOWN_PATHS_SQL = """SELECT gi.file_path, gi.image_path, gi.file_size,
+       (SELECT COUNT(DISTINCT ip.pair_id) FROM image_prompt_pairs ip
+        WHERE ip.image_id = gi.id) = 1
+FROM generated_images gi"""
+KNOWN_PATHS_FETCH_SIZE = 1000
+
 # One SELECT reads the link summaries of at most this many paths: three bound
 # parameters per path stays under SQLite's historical 999-variable limit.
 LINK_SUMMARY_BATCH = 200
@@ -216,6 +232,23 @@ JOIN prompts p ON p.id = COALESCE(pp.positive_prompt_id, gi.prompt_id)
 WHERE gi.file_path IS NOT NULL AND CASE WHEN {admit} THEN NOT EXISTS (
     SELECT 1 FROM generated_images other
     WHERE other.file_path = gi.file_path AND other.id <> gi.id) ELSE 0 END"""
+# The linked positive of each given path (one unambiguous link, pair scope as
+# in _LINK_FILTER_SQL) with its category; {hit} as in link_filter_query. Used
+# for the few files whose current image tags meet a Tags filter (#249 B3).
+_LINK_FACTS_SQL = """SELECT gi.file_path, p.rating, {hit}, p.id, p.category
+FROM generated_images gi
+LEFT JOIN prompt_pairs pp ON pp.id = (
+    SELECT CASE WHEN COUNT(DISTINCT ip.pair_id) = 1 THEN MIN(ip.pair_id) END
+    FROM image_prompt_pairs ip WHERE ip.image_id = gi.id)
+JOIN prompts p ON p.id = COALESCE(pp.positive_prompt_id, gi.prompt_id)
+WHERE gi.file_path IN ({marks}) AND NOT EXISTS (
+    SELECT 1 FROM generated_images other
+    WHERE other.file_path = gi.file_path AND other.id <> gi.id)"""
+_POSITIVE_TAG_NAMES_SQL = (
+    "SELECT pt.prompt_id, t.name FROM prompt_tags pt JOIN tags t "
+    "ON t.id = pt.tag_id WHERE pt.prompt_id IN ({marks})"
+)
+_FACTS_CHUNK = 500
 # The positive's text, its Library title or one of its tag names contains
 # :pattern (LIKE, so ASCII case is ignored as in Library search). A pair's own
 # title names its negative variant and is never searched (#249 D12).
@@ -307,6 +340,7 @@ class PromptDatabase(
     ExecutionOutputOperations,
     HistoryReadOperations,
     ImageFavoriteOperations,
+    AnnotationOperations,
     SavedViewOperations,
 ):
     """Database operations class for managing prompts."""
@@ -1069,16 +1103,39 @@ class PromptDatabase(
             }
 
     @staticmethod
+    def _bump_image_tag_bytes(conn: sqlite3.Connection, tag_id: int) -> int:
+        """Move the tag revision of every image set that carries *tag_id*.
+
+        Vocabulary rename, merge and delete change what an image's set reads
+        as, so a Tag dialog opened before the change must see ``tag-conflict``
+        on Save instead of recreating the old name. Bumps the image index
+        revision once when any set was affected; returns that count.
+        """
+        cursor = conn.execute(
+            "UPDATE media_annotation_bytes SET tag_revision = tag_revision + 1 "
+            "WHERE id IN (SELECT byte_id FROM media_image_tags WHERE tag_id = ?)",
+            (tag_id,),
+        )
+        if cursor.rowcount > 0:
+            conn.execute(
+                "UPDATE media_annotation_metadata SET "
+                "image_index_revision = image_index_revision + 1 WHERE singleton_id = 1"
+            )
+        return cursor.rowcount
+
+    @classmethod
     def _move_tag_links(
-        conn: sqlite3.Connection, source_id: int, target_id: int
+        cls, conn: sqlite3.Connection, source_id: int, target_id: int
     ) -> None:
-        """Repoint component and pair links from source to target.
+        """Repoint component, pair and image links from source to target.
 
         Owners that already carry the target keep that one link; the source's
-        leftover duplicates are removed. The source registry row is left for the
-        caller to delete.
+        leftover duplicates are removed (an image set keeps the target's
+        position). The source registry row is left for the caller to delete.
+        Image sets that carried the source get a new tag revision first.
         """
-        for junction in ("prompt_tags", "prompt_pair_tags"):
+        cls._bump_image_tag_bytes(conn, source_id)
+        for junction in ("prompt_tags", "prompt_pair_tags", "media_image_tags"):
             conn.execute(
                 f"UPDATE OR IGNORE {junction} SET tag_id = ? WHERE tag_id = ?",
                 (target_id, source_id),
@@ -1131,6 +1188,7 @@ class PromptDatabase(
                 conn.execute("DELETE FROM tags WHERE id = ?", (old_tag_id,))
             else:
                 # Simple rename
+                self._bump_image_tag_bytes(conn, old_tag_id)
                 conn.execute(
                     "UPDATE tags SET name = ? WHERE id = ?", (new_name, old_tag_id)
                 )
@@ -1172,6 +1230,7 @@ class PromptDatabase(
             affected = cursor.fetchone()["c"]
 
             # CASCADE delete handles prompt_tags entries
+            self._bump_image_tag_bytes(conn, tag_id)
             conn.execute("DELETE FROM tags WHERE id = ?", (tag_id,))
             conn.commit()
 
@@ -1224,7 +1283,10 @@ class PromptDatabase(
                 pair_count = conn.execute(
                     "SELECT COUNT(*) FROM prompt_pair_tags WHERE tag_id = ?", (src_id,)
                 ).fetchone()[0]
-                if src_count or pair_count:
+                image_count = conn.execute(
+                    "SELECT COUNT(*) FROM media_image_tags WHERE tag_id = ?", (src_id,)
+                ).fetchone()[0]
+                if src_count or pair_count or image_count:
                     self._move_tag_links(conn, src_id, target_id)
                     tags_merged += 1
                     affected += src_count
@@ -2280,6 +2342,52 @@ class PromptDatabase(
                 "parameters": row[8] if len(row) > 8 else None,
             }
 
+    def get_known_resolved_paths(self, files: Dict[str, Optional[int]]) -> Set[str]:
+        """The paths in ``files`` the Library already links with a resolved link.
+
+        ``files`` maps each scanned path to its size on disk (None when it could
+        not be read). A path qualifies when exactly one ``generated_images`` row
+        claims the file, that row has exactly one pair link
+        (``image_prompt_pairs``, written only by resolved ingestion), and its
+        stored ``file_size`` is not NULL and equals the given size, so a file
+        replaced at the same path is read again. Files linked without a pair
+        (the monitor's fallback and FIFO links, the legacy positive-only
+        import), linked to several prompts or pairs, or not linked at all do
+        not qualify. Both sides go through ``normalize_image_path`` (absolute,
+        normalized, ``os.path.normcase``), so a Windows row stored in another
+        case or spelling still matches. One query, streamed; returns the
+        matching keys of ``files``.
+        """
+        wanted: Dict[str, List[Tuple[str, Optional[int]]]] = {}
+        for path, size in files.items():
+            key = normalize_image_path(str(path))
+            wanted.setdefault(key, []).append((str(path), size))
+        if not wanted:
+            return set()
+        rows_seen: Dict[str, int] = {}
+        stored_sizes: Dict[str, int] = {}
+        with self.model.get_connection() as conn:
+            cursor = conn.execute(_KNOWN_PATHS_SQL)
+            while True:
+                rows = cursor.fetchmany(KNOWN_PATHS_FETCH_SIZE)
+                if not rows:
+                    break
+                for file_path, image_path, file_size, is_resolved in rows:
+                    # image_path is NOT NULL; file_path is NULL only on old rows.
+                    key = normalize_image_path(file_path or image_path)
+                    if key not in wanted:
+                        continue
+                    rows_seen[key] = rows_seen.get(key, 0) + 1
+                    if is_resolved and file_size is not None:
+                        stored_sizes[key] = file_size
+        return {
+            path
+            for key, stored_size in stored_sizes.items()
+            if rows_seen[key] == 1
+            for path, size in wanted[key]
+            if size is not None and size == stored_size
+        }
+
     def get_image_link_summaries(
         self, paths: List[str], allow_filename_fallback: bool = True
     ) -> Dict[str, Dict[str, Any]]:
@@ -2359,6 +2467,46 @@ class PromptDatabase(
                     matches[path] = (bool(matched), rating, positive)
         return matches
 
+    def get_image_link_facts(
+        self, paths: List[str], q: str = ""
+    ) -> Dict[str, Tuple[bool, Optional[int], int, Optional[str], Tuple[str, ...]]]:
+        """Map each normalized path with one unambiguous link to its positive's
+        (hit, rating, positive id, category, tag names).
+
+        The link is resolved as in get_image_link_matches, and ``hit`` says
+        whether *q* occurs in the positive's text, Library title or a tag
+        name (always true without *q*). Paths go in chunks of 500 through the
+        ``file_path`` index; the tag names are read for those positives only.
+        """
+        hit, params = "1", {}
+        if q:
+            hit = _LINK_FILTER_HIT
+            params["pattern"] = f"%{escape_like(q)}%"
+        rows: Dict[str, Tuple[bool, Optional[int], int, Optional[str]]] = {}
+        names: Dict[int, List[str]] = {}
+        unique = list(dict.fromkeys(paths))
+        with self.model.get_connection() as conn:
+            for start in range(0, len(unique), _FACTS_CHUNK):
+                chunk = unique[start : start + _FACTS_CHUNK]
+                bound = {f"path{i}": path for i, path in enumerate(chunk)}
+                marks = ",".join(f":{key}" for key in bound)
+                sql = _LINK_FACTS_SQL.format(hit=hit, marks=marks)
+                for path, rating, matched, positive, category in conn.execute(
+                    sql, {**params, **bound}
+                ):
+                    rows[path] = (bool(matched), rating, positive, category)
+            positives = sorted({row[2] for row in rows.values()})
+            for start in range(0, len(positives), _FACTS_CHUNK):
+                chunk = positives[start : start + _FACTS_CHUNK]
+                marks = ",".join("?" * len(chunk))
+                for positive, name in conn.execute(
+                    _POSITIVE_TAG_NAMES_SQL.format(marks=marks), chunk
+                ):
+                    names.setdefault(positive, []).append(name)
+        return {
+            path: (*row, tuple(names.get(row[2], ()))) for path, row in rows.items()
+        }
+
     def get_image_paths_matching(
         self, q: str, category: Optional[str], tags: List[str]
     ) -> Set[str]:

database/vocabulary.py

@@ -3,6 +3,9 @@
 A count is the number of eligible Library parents that carry the value
 directly or through one active saved pair, which is exactly what
 ``list_library(tags=[name])`` / ``list_library(category=value)`` return.
+A tag row's ``image_count`` is the number of files (private locators) with any
+byte record carrying the tag (#249), so a file counts once however many of its
+byte versions carry it, and equal bytes at two paths count twice.
 
 Tag commands run in one ``_pair_transaction``: the storage epoch is checked
 first, then the exact ``{id, name}`` identity, and the receipt is read on the
@@ -26,6 +29,11 @@ except ImportError:
     from utils.validators import validate_category, validate_tags
 
 _CATEGORY_DOMAIN = "prompt-manager-vocabulary-category:v1\n"
+# Files carrying a tag through any of their byte records (#249 image tags).
+_IMAGE_FILES = (
+    "SELECT mit.tag_id,COUNT(DISTINCT b.file_id) FROM media_image_tags mit "
+    "JOIN media_annotation_bytes b ON b.id=mit.byte_id"
+)
 
 
 def _tag_rows(page: str) -> str:
@@ -40,9 +48,13 @@ def _tag_rows(page: str) -> str:
         "WHERE pt.tag_id IN (SELECT id FROM page) AND " + _ELIGIBLE + " "
         "UNION SELECT ppt.tag_id,pp.positive_prompt_id FROM prompt_pairs pp "
         "JOIN prompt_pair_tags ppt ON ppt.pair_id=pp.id "
-        "WHERE pp.archived=0 AND ppt.tag_id IN (SELECT id FROM page)) "
-        "SELECT page.id,page.name,COUNT(DISTINCT owners.pid) AS prompt_count "
+        "WHERE pp.archived=0 AND ppt.tag_id IN (SELECT id FROM page)),"
+        "images(tag_id,n) AS (" + _IMAGE_FILES + " "
+        "WHERE mit.tag_id IN (SELECT id FROM page) GROUP BY mit.tag_id) "
+        "SELECT page.id,page.name,COUNT(DISTINCT owners.pid) AS prompt_count,"
+        "COALESCE(MAX(images.n),0) AS image_count "
         "FROM page LEFT JOIN owners ON owners.tag_id=page.id "
+        "LEFT JOIN images ON images.tag_id=page.id "
         "GROUP BY page.id ORDER BY page.id"
     )
 
@@ -61,7 +73,10 @@ _TAG_IMPACT = (
     "AS negative_variants,"
     "(SELECT COUNT(*) FROM prompt_pairs pp JOIN prompt_pair_tags ppt "
     "ON ppt.pair_id=pp.id WHERE ppt.tag_id=:tag AND pp.archived!=0) "
-    "AS archived_negative_variants"
+    "AS archived_negative_variants,"
+    "(SELECT COUNT(DISTINCT b.file_id) FROM media_image_tags mit "
+    "JOIN media_annotation_bytes b ON b.id=mit.byte_id WHERE mit.tag_id=:tag) "
+    "AS images"
 )
 _MAX_ID = 2**63 - 1
 
@@ -205,7 +220,16 @@ class VocabularyOperations:
             "SELECT COUNT(DISTINCT pair_id) FROM prompt_pair_tags WHERE tag_id=?",
             (tag_id,),
         ).fetchone()[0]
-        return {"components_changed": components, "pairs_changed": pairs}
+        images = conn.execute(
+            "SELECT COUNT(DISTINCT b.file_id) FROM media_image_tags mit "
+            "JOIN media_annotation_bytes b ON b.id=mit.byte_id WHERE mit.tag_id=?",
+            (tag_id,),
+        ).fetchone()[0]
+        return {
+            "components_changed": components,
+            "pairs_changed": pairs,
+            "images_changed": images,
+        }
 
     def create_vocabulary_tag(self, name: str, *, expected_epoch: str) -> dict:
         """Insert an unused registry row, or reuse the exact existing name."""
@@ -250,6 +274,7 @@ class VocabularyOperations:
                 "SELECT id FROM tags WHERE name=?", (new_name,)
             ).fetchone()
             if target is None:
+                self._bump_image_tag_bytes(conn, tag_id)
                 conn.execute("UPDATE tags SET name=? WHERE id=?", (new_name, tag_id))
                 result_id = tag_id
             else:
@@ -275,6 +300,7 @@ class VocabularyOperations:
             epoch = self._library_epoch(conn, expected_epoch)
             self._vocabulary_identity(conn, epoch, tag_id, name)
             counts = self._tag_owner_counts(conn, tag_id)
+            self._bump_image_tag_bytes(conn, tag_id)
             conn.execute("DELETE FROM tags WHERE id=?", (tag_id,))
             return {"library_epoch": epoch, "deleted": True, **counts}
 

docs/application-redesign.md

@@ -12,6 +12,7 @@ code. This plan proposes implementation order and acceptance gates.
 - The native Prompt Library merged in [#210](https://github.com/ComfyAssets/ComfyUI_PromptManager/pull/210) for [#208](https://github.com/ComfyAssets/ComfyUI_PromptManager/issues/208): one positive parent, saved negative variants, full selected text and a shared filtered image gallery. It does not invent chronological runs from counters or scan dates.
 - [Durable history storage](prompt-history-storage.md) records job attempts and outcomes from [#212](https://github.com/ComfyAssets/ComfyUI_PromptManager/pull/212), frozen prompt contexts from [#213](https://github.com/ComfyAssets/ComfyUI_PromptManager/pull/213), and observed run-owned output locators from [#214](https://github.com/ComfyAssets/ComfyUI_PromptManager/pull/214). Those locators do not verify file bytes or establish gallery-image associations. That association contract and the chronological execution timeline remain pending under [#209](https://github.com/ComfyAssets/ComfyUI_PromptManager/issues/209).
 - [#215](https://github.com/ComfyAssets/ComfyUI_PromptManager/issues/215) brings the shell, Images and natural-height Prompt Library presentation into the approved geometry and themes while retaining their existing operations. [#216](https://github.com/ComfyAssets/ComfyUI_PromptManager/issues/216) adds the shared current-file inspector with exact generation facts, scoped provenance, raw/download evidence and loaded-collection viewer controls, including a slideshow that pauses at native video. This delivery does not establish whole-application parity, change the default entry point or constitute a release. Recorded chronological run/context browsing continues under [#209](https://github.com/ComfyAssets/ComfyUI_PromptManager/issues/209); image tagging/review, System consolidation and remaining organization capabilities continue under #196.
+- Local Inspect (#249, PRs L1–L2) replaces the `#/inspect` handoff with the concept's native "Inspect a file" page: one local image or video previews inline and opens the shared viewer and full inspector on a record read entirely in the browser, with nothing uploaded, imported or stored. The legacy metadata page (`web/metadata.html`, served at `/prompt_manager/gallery.html`) stays reachable from Overview; its capabilities map to the shared inspector, except its one-click COPY ALL summary, whose ruled replacement ("Copy settings summary") is pending. Recorded deviations D60–D66 are in [TESTING.md](../TESTING.md). Local roles equal to the server's resolver follow in PR L3.
 
 ## Scope and compatibility
 

docs/prompt-inspector.md

@@ -29,6 +29,12 @@ Each role has `status` (`resolved`, `absent`, `unresolved`, or `ambiguous`), `te
 (string only when resolved, otherwise null), and `source`. Inspection does not
 index files, alter saved prompts, run scans, or decode image pixels. PNG text and
 video probe output are bounded; unsupported or malformed evidence remains
-unresolved rather than becoming sendable placeholder text.
+unresolved rather than becoming sendable placeholder text. Videos are read from
+one container carrier: the per-key tags written by core SaveVideo/SaveWEBM and
+current VideoHelperSuite (`prompt`, `workflow`, `parameters`,
+`comfyassets_prompt_pairs`), else the old VideoHelperSuite `comment` envelope,
+else `description`. The admin scan reads the same carrier, so Images and
+ingestion agree on a video's prompts (see TESTING.md for the order and budgets;
+the live monitor processes images only).
 
 Python route changes require restarting ComfyUI. Browser assets require a refresh.

py/api/__init__.py

@@ -6,6 +6,7 @@ Split into domain-specific mixins for maintainability:
 - AdminRoutesMixin: duplicates, stats, settings, diagnostics, maintenance, backup, scan
 - LoggingRoutesMixin: log management endpoints
 - AutotagRoutesMixin: auto-tagging model management and tagging
+- JobRoutesMixin: the session job registry behind Activity (py/api/jobs.py)
 """
 
 import asyncio
@@ -25,10 +26,13 @@ from .prompts import PromptRoutesMixin
 from .pairs import PairRoutesMixin
 from .library import LibraryRoutesMixin
 from .vocabulary import VocabularyRoutesMixin
+from .annotations import AnnotationRoutesMixin
 from .saved_views import SavedViewRoutesMixin
 from .history import HistoryRoutesMixin
 from .images import ImageRoutesMixin
 from .admin import AdminRoutesMixin
+from .job_routes import JobRoutesMixin
+from .jobs import JobRegistry
 from .logging_routes import LoggingRoutesMixin
 from .autotag_routes import AutotagRoutesMixin
 from .lora_integration import LoraIntegrationMixin
@@ -249,11 +253,13 @@ class PromptManagerAPI(
     PairRoutesMixin,
     LibraryRoutesMixin,
     VocabularyRoutesMixin,
+    AnnotationRoutesMixin,
     SavedViewRoutesMixin,
     HistoryRoutesMixin,
     PromptRoutesMixin,
     ImageRoutesMixin,
     AdminRoutesMixin,
+    JobRoutesMixin,
     LoggingRoutesMixin,
     AutotagRoutesMixin,
     LoraIntegrationMixin,
@@ -281,6 +287,10 @@ class PromptManagerAPI(
         self.db = db if db is not None else PromptDatabase()
         self._history_read_fence = None
         self._history_reads_closed = False
+        # Private media captures of the annotation routes (py/api/annotations.py),
+        # created on first use with their restore subscription.
+        self._captures = None
+        self._captures_unsubscribe = None
         self._cached_output_dir = None  # Lazy-cached by _find_comfyui_output_dir()
         self._html_cache = {}  # Cached HTML file contents keyed by path
         self._gallery_cache = {}  # dict: path_str -> (files, timestamp)
@@ -299,9 +309,12 @@ class PromptManagerAPI(
         # _acquire_long_job(). Created lazily so no lock binds to an event
         # loop before the server's loop exists.
         self._long_jobs: dict = {}
-        # The current output scan (py/api/scan_job.ScanJob), if one was started.
+        # This session's jobs (py/api/jobs.py): the metadata scan, and later
+        # every other long operation the Activity page tracks.
+        self._jobs = JobRegistry(self.logger)
+        # The latest metadata scan job (also in self._jobs), if one was started.
         self._scan_job = None
-        # The current duplicate scan (also a ScanJob), if one was started.
+        # The current duplicate scan (a py/api/jobs.Job outside the registry).
         self._duplicate_job = None
 
         # Run cleanup on initialization to remove any existing duplicates
@@ -434,11 +447,13 @@ class PromptManagerAPI(
         self._register_pair_routes(routes)
         self._register_library_routes(routes)
         self._register_vocabulary_routes(routes)
+        self._register_annotation_routes(routes)
         self._register_saved_view_routes(routes)
         self._register_history_routes(routes)
         self._register_prompt_routes(routes)
         self._register_image_routes(routes)
         self._register_admin_routes(routes)
+        self._register_job_routes(routes)
         self._register_logging_routes(routes)
         self._register_autotag_routes(routes)
         self._register_lora_routes(routes)

py/api/admin.py

@@ -6,16 +6,25 @@ from contextlib import closing
 import datetime
 import hashlib
 import json
+import math
 import os
 import sqlite3
 import tempfile
 import threading
+import time
 from pathlib import Path
 
 from aiohttp import web
 
 from .prompts import thumbnail_url_for
-from .scan_job import ScanJob
+from .jobs import (
+    DEFAULT_SCAN_SCOPE,
+    SCAN_GROUP_NAMES,
+    SCAN_GROUPS,
+    SCAN_SCOPES,
+    Job,
+    JobBusy,
+)
 
 try:
     from ...utils.parallel import map_parallel
@@ -47,8 +56,10 @@ except ImportError:
 
 
 try:
+    from ...database.library import display_title
     from ...utils.hashing import generate_prompt_hash
 except ImportError:
+    from database.library import display_title
     from utils.hashing import generate_prompt_hash
 
 IMAGE_EXTENSIONS = (".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff")
@@ -138,6 +149,127 @@ def _sse(payload):
     return f"data: {json.dumps(payload)}\n\n"
 
 
+SCAN_JOB_KIND = "scan"
+SCAN_JOB_TITLE = "Scan for metadata"
+# The legacy final event type of a scan and the job state it ends in.
+SCAN_FINAL_STATES = {
+    "complete": "finished",
+    "cancelled": "cancelled",
+    "error": "failed",
+}
+# The scope as the scan log's first line names it (the review dialog's words).
+SCAN_SCOPE_LOG = {"new": "new and unresolved files", "all": "all files"}
+MIN_BATCHES_FOR_ESTIMATE = 2  # "about X min left" waits for this many batches
+# Log line prefix per outcome group (spec: + added, = known, ? review, ! error,
+# - no usable metadata).
+SCAN_LOG_PREFIXES = {
+    "added": "+",
+    "known": "=",
+    "review": "?",
+    "errors": "!",
+    "no_metadata": "-",
+}
+# What an outcome row says about a file: where it went (with the prompt's
+# title) or why it was skipped. "error" is a file whose ingestion raised;
+# None is a file without prompt metadata.
+SCAN_TITLED_DETAILS = {
+    "added": "Added to the Library as “{title}”",
+    "linked": "Linked to “{title}”",
+    "enriched": "Metadata added to “{title}”",
+    "unchanged": "Already linked to “{title}”",
+}
+SCAN_DETAILS = {
+    "added": "Added to the Library",
+    "linked": "Linked to an existing prompt",
+    "enriched": "Metadata added to its prompt",
+    "unchanged": "Already linked to its prompt",
+    "skipped": "Skipped · already linked",
+    "ambiguous": "Needs review: more than one prompt could match",
+    "unresolved": "Needs review: the prompt could not be traced in the workflow",
+    "conflict": "Needs review: already linked to a different prompt",
+    "failed": "Error: the prompt could not be stored",
+    "error": "Error: the file could not be processed (see the server log)",
+    "found": "Metadata found, but no prompt text to store",
+    None: "No prompt metadata in the file",
+}
+
+
+def _plural(count, word):
+    return f"{count} {word}" if count == 1 else f"{count} {word}s"
+
+
+def _scan_status_line(done, total, batches, elapsed):
+    """ "Processing file N of M", with an estimate once enough batches ran."""
+    line = f"Processing file {done:,} of {total:,}"
+    if batches < MIN_BATCHES_FOR_ESTIMATE or done <= 0 or done >= total:
+        return line
+    minutes = max(1, math.ceil(elapsed / done * (total - done) / 60))
+    return f"{line} · about {minutes} min left"
+
+
+def _file_size(path):
+    """``path``'s size on disk, or None when it cannot be read."""
+    try:
+        return os.path.getsize(path)
+    except OSError:
+        return None
+
+
+def _with_file_size(canonical, media_file):
+    """Record the file's size in ``file_info`` unless the metadata carries one.
+
+    Stored as ``generated_images.file_size``; the "new" scan scope skips a known
+    file only while its size is unchanged.
+    """
+    info = canonical.get("file_info")
+    info = dict(info) if isinstance(info, dict) else {}
+    if info.get("size") is None:
+        size = _file_size(media_file)
+        if size is not None:
+            info["size"] = size
+    if info:
+        canonical["file_info"] = info
+
+
+def _scan_roots(output_dirs):
+    """(absolute root, public label, listing index), the most specific first.
+
+    The index is the root's place in ``output_dirs`` (``_get_all_output_dirs``),
+    the ``root_index`` the workspace listing names it by.
+    """
+    public_path, _ = _public_helpers()
+    roots = [
+        (os.path.abspath(str(d)), public_path(d), index)
+        for index, d in enumerate(output_dirs)
+    ]
+    return sorted(roots, key=lambda root: len(root[0]), reverse=True)
+
+
+def _scan_location(media_file, roots):
+    """``media_file`` relative to its output root, that root's label and index."""
+    full = os.path.abspath(str(media_file))
+    folded = os.path.normcase(full)
+    for root, label, index in roots:
+        base = os.path.normcase(root).rstrip("\\/") + os.sep
+        if folded.startswith(base):
+            return Path(os.path.relpath(full, root)).as_posix(), label, index
+    return Path(full).name, "", None
+
+
+def _scan_outcome(media_file, roots, status, title=None):
+    """The (group, row, log line) one scanned file records in its job."""
+    if status in SCAN_GROUPS:
+        group = SCAN_GROUPS[status]
+    else:
+        group = "errors" if status == "error" else "no_metadata"
+    template = SCAN_TITLED_DETAILS.get(status) if title else None
+    detail = template.format(title=title) if template else SCAN_DETAILS[status]
+    path, label, index = _scan_location(media_file, roots)
+    row = {"path": path, "root": label, "root_index": index, "detail": detail}
+    where = f"{label}/{path}" if label else path
+    return group, row, f"{SCAN_LOG_PREFIXES[group]} {where} · {detail}"
+
+
 def _inspect_restore_upload(path):
     """Checks on a restore upload beyond PromptModel.verify_database_file.
 
@@ -437,7 +569,7 @@ class AdminRoutesMixin:
             guard = self._acquire_long_job(self.LONG_JOB_DUPLICATES)
             if guard is None:
                 return self._long_job_busy_response("Duplicate scan or delete")
-            job = ScanJob()
+            job = Job("duplicates", "Duplicate scan")
             self._duplicate_job = job
             job.task = asyncio.ensure_future(self._run_duplicate_job(job, guard))
         return await self._stream_scan_job(request, job)
@@ -1319,14 +1451,18 @@ class AdminRoutesMixin:
     async def scan_images(self, request):
         """Scan ComfyUI output images for prompt metadata and add them to the database.
 
-        The scan runs as a background task that outlives this request, so a
-        closed tab never leaves a half-finished scan. Progress streams as
-        server-sent events; while a scan is running, a new request attaches
-        to it instead of starting another one.
+        The scan runs as the registry's ``scan`` job, which outlives this
+        request, so a closed tab never leaves a half-finished scan. Progress
+        streams as the legacy server-sent events; while a scan is running
+        (started here or from the workspace), a new request attaches to it
+        instead of starting another one.
         """
-        job = self._scan_job
-        if job is None or job.finished:
-            job = self._start_scan_job()
+        job = self._jobs.active(SCAN_JOB_KIND)
+        if job is None:
+            try:
+                job = self._start_scan_job("all")
+            except JobBusy as busy:
+                return self._long_job_busy_response(busy.running.title)
         return await self._stream_scan_job(request, job)
 
     async def cancel_scan(self, request):
@@ -1348,19 +1484,37 @@ class AdminRoutesMixin:
             }
         )
 
-    def _start_scan_job(self):
-        """Create the job record synchronously, then run the scan as a task."""
-        job = ScanJob()
+    def _start_scan_job(self, files=DEFAULT_SCAN_SCOPE):
+        """Register the scan job synchronously; its runner starts on the loop.
+
+        ``files`` is the scope (``SCAN_SCOPES``). Raises JobBusy while another
+        record-changing job runs.
+        """
+        if files not in SCAN_SCOPES:
+            raise ValueError(f"Unknown scan scope: {files!r}")
+        job = self._jobs.start(
+            SCAN_JOB_KIND,
+            SCAN_JOB_TITLE,
+            record_changing=True,
+            scope={"files": files},
+            runner=self._run_scan_job,
+            groups=SCAN_GROUP_NAMES,
+        )
         self._scan_job = job
-        job.task = asyncio.ensure_future(self._run_scan_job(job))
         return job
 
     async def _run_scan_job(self, job):
-        try:
-            async for payload in self._scan_images_events():
-                job.publish(payload)
-        finally:
-            job.finish()
+        final = None
+        async for payload in self._scan_images_events(job):
+            job.publish(payload)
+            final = payload.get("type")
+        state = SCAN_FINAL_STATES.get(final, "finished")
+        if state == "failed":
+            job.log_line(f"Scan failed · {job.status_line}")
+        else:
+            verb = "cancelled" if state == "cancelled" else "finished"
+            job.log_line(f"Scan {verb} · {_plural(job.processed, 'file')} processed")
+        job.finish(state)
 
     async def _stream_scan_job(self, request, job):
         """Stream ``job`` as SSE; stop quietly if the client goes away."""
@@ -1386,21 +1540,31 @@ class AdminRoutesMixin:
             )
         return response
 
-    async def _scan_images_events(self):
-        """Yield progress payloads while scanning every configured output directory."""
+    async def _scan_images_events(self, job):
+        """Yield progress payloads while scanning every configured output directory.
+
+        The payloads are the legacy SSE events, unchanged; ``job`` also gets
+        its status line, totals and one outcome per processed file.
+        """
         try:
             self.logger.info("Starting image scan operation")
             output_dirs = self._get_all_output_dirs()
             if not output_dirs:
                 self.logger.error("No output directories found")
-                yield {
-                    "type": "error",
-                    "message": "No output directories found. "
-                    "Configure scan directories in Settings.",
-                }
+                message = (
+                    "No output directories found. "
+                    "Configure scan directories in Settings."
+                )
+                job.update(status_line=message)
+                yield {"type": "error", "message": message}
                 return
 
             dir_names = [self._public_path(d) for d in output_dirs]
+            folders = _plural(len(output_dirs), "output folder")
+            job.scope["output_folders"] = len(output_dirs)
+            scope = SCAN_SCOPE_LOG[job.scope.get("files", "all")]
+            job.log_line(f"Scan started · {folders} · {scope}")
+            job.update(status_line=f"Looking for media files in {folders}")
             yield self._scan_progress(
                 0, f"Scanning {len(output_dirs)} directory(ies) for media files..."
             )
@@ -1409,11 +1573,21 @@ class AdminRoutesMixin:
                 self._collect_output_media_sync, output_dirs
             )
             counts = dict.fromkeys(SCAN_COUNT_KEYS, 0)
+            job.update(
+                total=len(media_files),
+                status_line=_scan_status_line(0, len(media_files), 0, 0),
+            )
             if media_files:
                 yield self._scan_progress(
                     5, f"Found {len(media_files)} media files to process...", counts
                 )
-            async for event in self._scan_batches(media_files, counts):
+            roots = _scan_roots(output_dirs)
+            known = set()
+            if media_files and job.scope.get("files") != "all":
+                known = await self._known_scan_files(job, media_files)
+            async for event in self._scan_batches(
+                media_files, counts, job, roots, known
+            ):
                 yield event
 
             self.logger.info(
@@ -1421,37 +1595,78 @@ class AdminRoutesMixin:
                 f"found={counts['found']}, new_prompts_added={counts['added']}, "
                 f"images_linked_to_existing={counts['linked']}"
             )
-            job = self._scan_job
-            final_type = "cancelled" if job and job.cancelled else "complete"
+            final_type = "cancelled" if job.cancelled else "complete"
+            if final_type == "complete":
+                job.update(progress=100)
             yield {"type": final_type, **counts, "directories": dir_names}
 
         except Exception:
             self.logger.exception("Scan error")
+            job.update(status_line="The scan stopped on an internal error.")
             yield {
                 "type": "error",
                 "message": "An internal error occurred. Check server logs for details.",
             }
 
-    async def _scan_batches(self, media_files, counts):
+    async def _known_scan_files(self, job, media_files):
+        """The "new" scope's skip set; a failed read falls back to reading all."""
+        try:
+            return await self._run_in_executor(self._known_scan_files_sync, media_files)
+        except Exception:
+            self.logger.warning(
+                "Known files could not be read; the scan reads every file",
+                exc_info=True,
+            )
+            job.log_line("Known files could not be read · reading every file")
+            return set()
+
+    def _known_scan_files_sync(self, media_files):
+        """Stat each scanned file and ask the database which are known (blocking)."""
+        sizes = {str(media_file): _file_size(media_file) for media_file in media_files}
+        return self.db.get_known_resolved_paths(sizes)
+
+    async def _scan_batches(self, media_files, counts, job, roots=(), known=()):
         """Process ``media_files`` in executor batches, updating ``counts`` in place.
 
-        Yields one progress event per batch.
+        Records each file's outcome in ``job`` and yields one progress event
+        per batch. Files in ``known`` (path strings) are not read: they count
+        as processed and unchanged and are recorded as skipped.
         """
         total = len(media_files)
+        started = time.monotonic()
+        batches = 0
         for batch_start in range(0, total, SCAN_BATCH_SIZE):
-            if self._scan_job and self._scan_job.cancelled:
+            if job.cancelled:
                 return
             batch = media_files[batch_start : batch_start + SCAN_BATCH_SIZE]
-            batch_results = await self._run_in_executor(
-                self._extract_batch_metadata_sync, batch
-            )
-            batch_counts = await self._run_in_executor(
-                self._ingest_scan_batch_sync, batch_results
-            )
-            for key in counts:
-                counts[key] += batch_counts[key]
+            skipped = [f for f in batch if str(f) in known]
+            to_read = [f for f in batch if str(f) not in known]
+            outcomes = [_scan_outcome(f, roots, "skipped") for f in skipped]
+            counts["processed"] += len(skipped)
+            counts["unchanged"] += len(skipped)
+            if to_read:
+                batch_results = await self._run_in_executor(
+                    self._extract_batch_metadata_sync, to_read
+                )
+                batch_counts = await self._run_in_executor(
+                    self._ingest_scan_batch_sync,
+                    batch_results,
+                    roots=roots,
+                    outcomes=outcomes,
+                )
+                for key in counts:
+                    counts[key] += batch_counts[key]
+            for group, row, log_line in outcomes:
+                job.record(group, row, log_line)
 
+            batches += 1
             done = min(batch_start + len(batch), total)
+            job.update(
+                processed=counts["processed"],
+                status_line=_scan_status_line(
+                    done, total, batches, time.monotonic() - started
+                ),
+            )
             yield self._scan_progress(
                 int(done / total * 100), f"Processing file {done}/{total}...", counts
             )
@@ -1490,9 +1705,19 @@ class AdminRoutesMixin:
 
         return map_parallel(extract, file_batch, PromptManagerConfig.WORKER_THREADS)
 
-    def _ingest_scan_batch_sync(self, batch_results):
-        """Store the prompts found in a metadata batch (blocking DB work)."""
+    def _ingest_scan_batch_sync(self, batch_results, roots=(), outcomes=None):
+        """Store the prompts found in a metadata batch (blocking DB work).
+
+        Returns the legacy counts. When ``outcomes`` is a list, every processed
+        file appends its ``(group, row, log_line)`` for the scan job, with the
+        path relative to its root in ``roots`` (see ``_scan_roots``).
+        """
         counts = dict.fromkeys(SCAN_COUNT_KEYS, 0)
+
+        def note(media_file, status, title=None):
+            if outcomes is not None:
+                outcomes.append(_scan_outcome(media_file, roots, status, title))
+
         for media_file, metadata in batch_results:
             if self._scan_job and self._scan_job.cancelled:
                 break
@@ -1502,25 +1727,21 @@ class AdminRoutesMixin:
             except Exception as e:
                 self.logger.error(f"Error processing {media_file.name}: {e}")
                 counts["failed"] += 1
+                note(media_file, "error")
                 continue
             if outcome is None:
+                note(media_file, None)
                 continue
             counts["found"] += 1
             status = outcome["status"] if isinstance(outcome, dict) else outcome
-            if status in (
-                "added",
-                "linked",
-                "enriched",
-                "unchanged",
-                "ambiguous",
-                "unresolved",
-                "conflict",
-                "failed",
-            ):
+            if status in SCAN_GROUPS:
                 counts[status] += 1
             if isinstance(outcome, dict):
                 counts["pairs_added"] += outcome.get("pairs_added", 0)
                 counts["pair_links_added"] += outcome.get("links_added", 0)
+                note(media_file, status, outcome.get("title"))
+            else:
+                note(media_file, status)
         return counts
 
     @staticmethod
@@ -1539,7 +1760,13 @@ class AdminRoutesMixin:
         return positive.strip() or None
 
     def _ingest_scanned_file(self, media_file, metadata, detailed=False):
-        """Enrich exact pairs; retain legacy positive-only import for absent pairs."""
+        """Enrich exact pairs; retain legacy positive-only import for absent pairs.
+
+        Returns the file's scan status, or None without prompt metadata. With
+        ``detailed``, a stored or linked file returns a dict instead: its
+        ``status``, the prompt's display ``title`` and, for a resolved pair,
+        the pair counts.
+        """
         if not metadata:
             return None
         canonical = dict(metadata)
@@ -1552,12 +1779,18 @@ class AdminRoutesMixin:
                     pass
         if not canonical.get("prompt") and not canonical.get("parameters"):
             return None
+        _with_file_size(canonical, media_file)
         resolution = resolve_prompt_pair(canonical)
         if resolution["state"] == "resolved":
             result = ingest_resolved_pair(
                 self.db, str(media_file), canonical, resolution
             )
-            return result if detailed else result["status"]
+            if not detailed:
+                return result["status"]
+            return {
+                **result,
+                "title": self._scan_title(media_file, resolution["positive"]["text"]),
+            }
         if canonical.get("prompt") and resolution["state"] in (
             "ambiguous",
             "unresolved",
@@ -1585,6 +1818,25 @@ class AdminRoutesMixin:
                 return "found"
             prompt_text = prompt_text.strip()
 
+        status = self._store_scanned_prompt(media_file, canonical, prompt_text)
+        if not detailed or status not in SCAN_TITLED_DETAILS:
+            return status
+        return {"status": status, "title": self._scan_title(media_file, prompt_text)}
+
+    def _scan_title(self, media_file, text):
+        """The linked prompt's Library title (its stored title, else ``text``'s
+        first line), as the Library and the inspector name it."""
+        try:
+            path = str(media_file)
+            summary = self.db.get_image_link_summaries([path], False).get(path)
+            if summary and summary.get("title"):
+                return summary["title"]
+        except Exception:
+            self.logger.warning("Scan row title could not be read; using its text")
+        return display_title((), text)
+
+    def _store_scanned_prompt(self, media_file, canonical, prompt_text):
+        """Link ``media_file`` to ``prompt_text``'s prompt, saving it when new."""
         prompt_hash = generate_prompt_hash(prompt_text)
         existing = self.db.get_prompt_by_hash(prompt_hash)
         if existing:

py/api/annotation_suggest.py

@@ -0,0 +1,121 @@
+"""Request validation and the worker of the Tag dialog's Generate (#249 B2).
+
+``POST /prompt_manager/image-annotations/suggest`` asks one of legacy's four
+engines for the top N tags of a captured image. Options are validated
+strictly, per engine: WD14 classifiers take two thresholds, the language
+models (GGUF and HuggingFace JoyCaption) take the instructions; every engine
+takes the suggestion count and the GPU switch. Nothing here touches the
+filesystem or the database.
+"""
+
+import math
+
+WD14_MODELS = frozenset({"wd14-swinv2", "wd14-vit"})
+LLM_MODELS = frozenset({"gguf", "hf"})
+MODEL_TYPES = WD14_MODELS | LLM_MODELS
+
+MAX_INSTRUCTION_CHARS = 4000
+MAX_INSTRUCTION_BYTES = 16 * 1024
+
+SUGGEST_FIELDS = frozenset(
+    {"target", "capture_token", "expected_epoch", "model_type", "options"}
+)
+_COMMON = frozenset({"suggestion_limit", "use_gpu"})
+_WD14_REQUIRED = frozenset({"general_threshold", "character_threshold"})
+_LLM_REQUIRED = frozenset({"instructions"})
+
+UNAVAILABLE_HINT = "Download it from the legacy Auto-tag page."
+
+
+class OptionError(ValueError):
+    """A suggest request whose model type or options are not acceptable."""
+
+
+def _threshold(name: str, value) -> float:
+    if type(value) not in (int, float) or not math.isfinite(value):
+        raise OptionError(f"{name} must be a finite number")
+    if not 0 <= value <= 1:
+        raise OptionError(f"{name} must be between 0 and 1")
+    return float(value)
+
+
+def _instructions(value) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise OptionError("instructions must be non-empty text")
+    if len(value) > MAX_INSTRUCTION_CHARS:
+        raise OptionError(
+            f"instructions must be at most {MAX_INSTRUCTION_CHARS} characters"
+        )
+    try:
+        encoded = value.encode("utf-8")
+    except UnicodeEncodeError:
+        raise OptionError("instructions must be valid Unicode text") from None
+    if len(encoded) > MAX_INSTRUCTION_BYTES:
+        raise OptionError("instructions are too long")
+    return value
+
+
+def validate_options(model_type, options, *, default_limit: int, max_limit: int):
+    """Normalised ``(model_type, options)`` or :class:`OptionError`.
+
+    The answer echoes every option the request will run with, the defaults
+    (suggestion count from the settings, GPU on) filled in.
+    """
+    if not isinstance(model_type, str) or model_type not in MODEL_TYPES:
+        raise OptionError("model_type must be one of " + ", ".join(sorted(MODEL_TYPES)))
+    if not isinstance(options, dict):
+        raise OptionError("options must be an object")
+    required = _WD14_REQUIRED if model_type in WD14_MODELS else _LLM_REQUIRED
+    keys = set(options)
+    if not required <= keys or not keys <= required | _COMMON:
+        raise OptionError(
+            f"options for {model_type} take exactly "
+            + ", ".join(sorted(required))
+            + " and optionally "
+            + ", ".join(sorted(_COMMON))
+        )
+    limit = options.get("suggestion_limit", default_limit)
+    if type(limit) is not int or not 1 <= limit <= max_limit:
+        raise OptionError(f"suggestion_limit must be an integer from 1 to {max_limit}")
+    use_gpu = options.get("use_gpu", True)
+    if not isinstance(use_gpu, bool):
+        raise OptionError("use_gpu must be true or false")
+    normalised = {"use_gpu": use_gpu, "suggestion_limit": limit}
+    if model_type in WD14_MODELS:
+        for name in sorted(_WD14_REQUIRED):
+            normalised[name] = _threshold(name, options[name])
+    else:
+        normalised["instructions"] = _instructions(options["instructions"])
+    return model_type, normalised
+
+
+def unavailable_message(model_name: str) -> str:
+    return f"{model_name} is not downloaded. {UNAVAILABLE_HINT}"
+
+
+def run_suggestions(service, capture_path: str, model_type: str, options: dict):
+    """Blocking: load (or swap to) *model_type*, then suggest for the capture.
+
+    The caller holds the model gate for the whole call; nothing is ever
+    downloaded (``load_model`` refuses a model that is not on disk).
+    """
+    if not service.is_model_loaded() or service.get_loaded_model_type() != model_type:
+        service.load_model(model_type, options["use_gpu"])
+    return service.generate_tag_suggestions(
+        capture_path,
+        limit=options["suggestion_limit"],
+        prompt=options.get("instructions"),
+        general_threshold=options.get("general_threshold"),
+        character_threshold=options.get("character_threshold"),
+    )
+
+
+def suggestion_rows(pairs) -> list:
+    """``[{name, confidence}]``; a non-finite score is reported as unknown."""
+    rows = []
+    for name, score in pairs:
+        confidence = None
+        if score is not None and math.isfinite(score):
+            confidence = float(score)
+        rows.append({"name": str(name), "confidence": confidence})
+    return rows

py/api/annotations.py

@@ -0,0 +1,759 @@
+"""Image annotation routes: observe, capture preview and byte-exact tag saves.
+
+Every route names its file through the listing identity ``{root_index,
+root_scope, path}`` and checks the scope against the current gallery roots
+before any file access. Observe copies the file into a private capture (the
+token the preview and Save refer to), Save re-hashes the current file and
+writes only when the bytes are still the captured ones. Responses carry no
+server path and no locator.
+"""
+
+import asyncio
+import datetime
+import functools
+import os
+import re
+from pathlib import Path
+
+from aiohttp import web
+
+from .annotation_suggest import (
+    SUGGEST_FIELDS,
+    OptionError,
+    run_suggestions,
+    suggestion_rows,
+    unavailable_message,
+    validate_options,
+)
+from .autotag_routes import model_busy_response
+from .images import _forbidden, _has_traversal, _unavailable_link, _verified_title
+from .prompts import bad_request
+from .. import model_gate
+
+try:
+    from ...database.annotations import (
+        MAX_IMAGE_TAGS,
+        AnnotationCommandError,
+        ImageTagLimitError,
+        normalize_image_tags,
+    )
+    from ...database.execution_history import subscribe_history_restore
+    from ...database.library_commands import LibraryCommandError
+    from ...utils.media_capture import CAPTURE_EXTENSIONS, CaptureError, CaptureStore
+except ImportError:
+    from database.annotations import (
+        MAX_IMAGE_TAGS,
+        AnnotationCommandError,
+        ImageTagLimitError,
+        normalize_image_tags,
+    )
+    from database.execution_history import subscribe_history_restore
+    from database.library_commands import LibraryCommandError
+    from utils.media_capture import CAPTURE_EXTENSIONS, CaptureError, CaptureStore
+
+# Request bodies of the annotation routes are small (a target plus a tag set).
+MAX_BODY_BYTES = 64 * 1024
+MAX_TARGET_PATH = 1024
+CAPTURE_URL = "/prompt_manager/image-annotations/capture/"
+_PREVIEW_CHUNK = 64 * 1024
+
+_TARGET_FIELDS = frozenset({"root_index", "root_scope", "path"})
+_OBSERVE_FIELDS = frozenset({"target"})
+_SAVE_FIELDS = frozenset(
+    {
+        "target",
+        "capture_token",
+        "sha256",
+        "expected_epoch",
+        "expected_tag_revision",
+        "tags",
+    }
+)
+_HEX64 = re.compile(r"[0-9a-f]{64}")
+_UUID = re.compile(r"[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}")
+# secrets.token_urlsafe(32) is 43 characters; the bound only rejects junk.
+_TOKEN = re.compile(r"[A-Za-z0-9_-]{1,128}")
+
+_PREVIEW_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".bmp": "image/bmp",
+    ".tiff": "image/tiff",
+    ".tif": "image/tiff",
+    ".mp4": "video/mp4",
+    ".m4v": "video/mp4",
+    ".webm": "video/webm",
+    ".mov": "video/quicktime",
+    ".mkv": "video/x-matroska",
+    ".avi": "video/x-msvideo",
+    ".wmv": "video/x-ms-wmv",
+}
+
+_STATUS = {
+    "review-capacity": 429,
+    "unsupported-media": 415,
+    "file-changed": 409,
+    "source-changed": 409,
+    "storage-changed": 409,
+    "tag-conflict": 409,
+    "capture-expired": 409,
+    "model-unavailable": 409,
+    "tag-limit": 400,
+    "metadata-conflict": 409,
+    "vocabulary-conflict": 409,
+}
+_MESSAGES = {
+    "source-changed": (
+        "The source changed. Refresh the image collection before tagging this file."
+    ),
+    "file-changed": "The file changed since it was previewed. Reopen the Tag dialog.",
+    "review-capacity": "Too many previews are open. Close a Tag dialog and try again.",
+    "storage-changed": "Prompt storage was restored; reopen the Tag dialog.",
+    "tag-conflict": (
+        "The tags of this image changed since the dialog opened; review them first."
+    ),
+    "capture-expired": "The preview expired. Open the Tag dialog again.",
+    "tag-limit": f"An image can carry at most {MAX_IMAGE_TAGS} tags.",
+}
+# Any other storage code (a conflict a later command adds) still answers a
+# coded envelope rather than a bare 500.
+_DEFAULT_STATUS = 409
+_DEFAULT_MESSAGE = "The tags could not be saved. Reopen the Tag dialog and try again."
+_OTHER_FILE = "The preview belongs to another file. Open the Tag dialog again."
+
+
+def preview_content_type(extension: str) -> str:
+    """The media type the preview is served as; never sniffed from bytes."""
+    return _PREVIEW_TYPES.get(extension.lower(), "application/octet-stream")
+
+
+def _error(status: int, code: str, message: str, **extra) -> web.Response:
+    return web.json_response(
+        {"success": False, "code": code, "error": message, **extra},
+        status=status,
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+def _coded(code: str, message: str | None = None, **extra) -> web.Response:
+    status = _STATUS.get(code, _DEFAULT_STATUS)
+    return _error(
+        status, code, message or _MESSAGES.get(code, _DEFAULT_MESSAGE), **extra
+    )
+
+
+def _open_capture(path: str):
+    """Worker thread: the capture file opened for reading."""
+    return open(path, "rb")
+
+
+async def _settled(future, cleanup):
+    """Await an executor *future*; a cancelled caller still cleans up after it.
+
+    The future is shielded, so the worker call always runs to its end. When the
+    caller is cancelled first, ``cleanup(result)`` runs once the call is done
+    (``cleanup(None)`` when it failed): a handle is closed, a capture released.
+    """
+    try:
+        return await asyncio.shield(future)
+    except asyncio.CancelledError:
+        future.add_done_callback(functools.partial(_cleanup_result, cleanup))
+        raise
+
+
+def _cleanup_result(cleanup, future) -> None:
+    if future.cancelled() or future.exception() is not None:
+        cleanup(None)
+    else:
+        cleanup(future.result())
+
+
+def _submit(func, *args, **kwargs):
+    return asyncio.get_running_loop().run_in_executor(
+        None, functools.partial(func, *args, **kwargs)
+    )
+
+
+def _capture_error(exc: CaptureError) -> web.Response:
+    """The envelope for a capture outcome; messages never name a path."""
+    if exc.code not in _STATUS:
+        return _error(500, exc.code, "The file could not be captured.")
+    return _coded(exc.code, _MESSAGES.get(exc.code) or str(exc))
+
+
+def _target(data: object):
+    """``((index, scope, relative), None)`` for a target, else ``(None, error)``.
+
+    Only the listing identity is accepted: an int root index, the root's
+    64-hex scope and a bounded root-relative POSIX media path, never an
+    absolute, drive-qualified, backslash or ``..`` path. Nothing here touches
+    the filesystem or the database.
+    """
+    if not isinstance(data, dict) or set(data) != _TARGET_FIELDS:
+        return None, bad_request("target must name root_index, root_scope and path")
+    index, scope, relative = data["root_index"], data["root_scope"], data["path"]
+    if type(index) is not int or index < 0:
+        return None, bad_request("Invalid gallery root")
+    if not isinstance(scope, str) or _HEX64.fullmatch(scope) is None:
+        return None, bad_request("Invalid gallery root scope")
+    if not isinstance(relative, str) or not relative or len(relative) > MAX_TARGET_PATH:
+        return None, bad_request("path must be a relative media path")
+    parts = relative.split("/")
+    if (
+        "\0" in relative
+        or "\\" in relative
+        or relative.startswith("/")
+        or _has_traversal(relative)
+        or any(part in ("", ".", "..") or ":" in part for part in parts)
+    ):
+        return None, _forbidden()
+    if os.path.splitext(parts[-1])[1].lower() not in CAPTURE_EXTENSIONS:
+        return None, _forbidden("Only media files can be tagged")
+    return (index, scope, relative), None
+
+
+def _expires_at(seconds: float | None) -> str:
+    moment = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(
+        seconds=max(0.0, seconds or 0.0)
+    )
+    return moment.replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _capture_info(store: CaptureStore, capture) -> dict:
+    return {
+        "token": capture.token,
+        "expires_at": _expires_at(store.expires_in(capture.token)),
+        "preview_url": CAPTURE_URL + capture.token,
+        "sha256": capture.sha256,
+        "size": capture.size,
+        "width": capture.width,
+        "height": capture.height,
+        "media_type": capture.media_type,
+        "generate": {
+            "supported": capture.inferable,
+            "reason": capture.inferable_reason,
+        },
+    }
+
+
+class AnnotationRoutesMixin:
+    """Observe, capture preview and tag save routes over PR A's storage."""
+
+    def _register_annotation_routes(self, routes: web.RouteTableDef) -> None:
+        routes.post("/prompt_manager/image-annotations/observe")(self.observe_image)
+        routes.get(CAPTURE_URL + "{token}")(self.get_capture_preview)
+        routes.delete(CAPTURE_URL + "{token}")(self.release_capture)
+        routes.put("/prompt_manager/image-annotations/tags")(self.save_image_tags)
+        routes.post("/prompt_manager/image-annotations/suggest")(
+            self.suggest_image_tags
+        )
+
+    # -- capture store lifetime ------------------------------------------------
+
+    def _capture_store(self) -> CaptureStore:
+        """The process's capture store, created on first use.
+
+        Created lazily so an API object that never observes a file (most tests,
+        a server that never opens the Tag dialog) owns no temp directory. A
+        restore of the database dooms every capture (``invalidate_all``).
+        """
+        if self._captures is None:
+            self._captures = CaptureStore()
+        if self._captures_unsubscribe is None:
+            self._captures_unsubscribe = subscribe_history_restore(
+                self.db.model.db_path, self._invalidate_captures
+            )
+        return self._captures
+
+    def _invalidate_captures(self) -> None:
+        store = self._captures
+        if store is not None:
+            store.invalidate_all()
+
+    def close_annotation_captures(self) -> None:
+        """Remove every capture file and the owned directory. Idempotent."""
+        unsubscribe, self._captures_unsubscribe = self._captures_unsubscribe, None
+        if unsubscribe is not None:
+            unsubscribe()
+        store, self._captures = self._captures, None
+        if store is not None:
+            store.close()
+
+    async def cleanup_annotation_captures(self, app: web.Application) -> None:
+        self.close_annotation_captures()
+
+    # -- shared request steps --------------------------------------------------
+
+    async def _annotation_body(self, request: web.Request, fields: frozenset):
+        data, error = await self._read_json_body(request, max_bytes=MAX_BODY_BYTES)
+        if error is not None:
+            return None, error
+        if set(data) != fields:
+            return None, bad_request(
+                "Request must contain exactly " + ", ".join(sorted(fields))
+            )
+        return data, None
+
+    def _scoped_root(self, index: int, scope: str):
+        """``(root, None)`` when the scope names a current root, else an error."""
+        roots = list(self._get_all_output_dirs())
+        error = self._gallery_scope_error(
+            {"root_scope": scope, "root": str(index)}, roots
+        )
+        if error is not None:
+            if error.status == 409:
+                return None, _coded("source-changed")
+            return None, error
+        return roots[index], None
+
+    # -- observe ---------------------------------------------------------------
+
+    async def observe_image(self, request: web.Request) -> web.Response:
+        """POST ``{target}``: capture the file and answer its saved tag set.
+
+        The capture is the byte-exact copy the preview and Save refer to; the
+        tags are those of exactly these bytes (an empty set at revision 0 for
+        unseen bytes). Observing never writes tags; equal bytes refresh the
+        record's verified fingerprint (S1).
+        """
+        data, error = await self._annotation_body(request, _OBSERVE_FIELDS)
+        if error is not None:
+            return error
+        target, error = _target(data["target"])
+        if error is not None:
+            return error
+        index, scope, relative = target
+        root, error = self._scoped_root(index, scope)
+        if error is not None:
+            return error
+        store = self._capture_store()
+        try:
+            epoch = await self._run_in_executor(self.db.get_execution_epoch)
+            capture = await _settled(
+                _submit(
+                    store.capture,
+                    root,
+                    relative,
+                    epoch=epoch,
+                    scope=scope,
+                    root_index=index,
+                ),
+                # A cancelled observe never hands its capture out: release it.
+                lambda made: made is not None and store.release(made.token),
+            )
+        except CaptureError as exc:
+            return _capture_error(exc)
+        except Exception:
+            self.logger.exception("Image observation failed")
+            return _error(500, "observe-failed", "The image could not be observed.")
+        try:
+            stored, title = await self._run_in_executor(
+                self._observe_capture, store, capture, root, relative
+            )
+        except asyncio.CancelledError:
+            store.release(capture.token)
+            raise
+        except Exception:
+            store.release(capture.token)
+            self.logger.exception("Image observation failed")
+            return _error(500, "observe-failed", "The image could not be observed.")
+        return web.json_response(
+            {
+                "success": True,
+                "library_epoch": capture.epoch,
+                "target": {"root_index": index, "root_scope": scope, "path": relative},
+                "capture": _capture_info(store, capture),
+                "title": title,
+                "filename": relative.rsplit("/", 1)[-1],
+                "tags": stored["tags"],
+                "tag_revision": stored["tag_revision"],
+            },
+            headers={"Cache-Control": "no-store"},
+        )
+
+    def _observe_capture(self, store: CaptureStore, capture, root, relative: str):
+        """Blocking part of observe: fingerprint refresh, tag read, title."""
+        self.db.refresh_image_fingerprint(
+            capture.locator, capture.sha256, capture.size, capture.mtime_ns
+        )
+        stored = self.db.read_image_tags(capture.locator, capture.sha256)
+        return stored, self._observed_title(store, capture, root, relative)
+
+    def _observed_title(self, store: CaptureStore, capture, root, relative: str):
+        """The dialog's title under the card and inspector rule (``_verified_title``).
+
+        A stored Library title always shows; a first-line title only when the
+        captured bytes' own records confirm it. An ambiguous association has no
+        title. Videos read no card metadata, so only a stored title shows.
+        """
+        path = str(Path(root) / relative)
+        summary = self._workspace_link_summaries([path]).get(path)
+        if summary is None:
+            summary = _unavailable_link()
+        positive_title = None
+        if (
+            capture.media_type != "video"
+            and summary.get("title_source") == "text"
+            and store.acquire(capture.token) is not None
+        ):
+            try:
+                facts = self._read_card_facts(Path(capture.path), parse=True)
+            finally:
+                store.release_use(capture.token)
+            positive_title = facts.positive_title if facts is not None else None
+        return _verified_title(summary, positive_title)
+
+    # -- capture preview -------------------------------------------------------
+
+    async def get_capture_preview(self, request: web.Request) -> web.StreamResponse:
+        """GET the captured bytes; the token is pinned while they stream."""
+        token = request.match_info["token"]
+        store = self._captures
+        if store is None or _TOKEN.fullmatch(token) is None:
+            return _error(404, "capture-expired", _MESSAGES["capture-expired"])
+        capture = store.acquire(token)
+        if capture is None:
+            return _error(404, "capture-expired", _MESSAGES["capture-expired"])
+        pinned = True
+        try:
+            _root, error = self._scoped_root(capture.root_index, capture.scope)
+            if error is not None:
+                # The roots changed under the token: it is no longer usable.
+                store.release(token)
+                return error
+            try:
+                handle = await _settled(
+                    _submit(_open_capture, capture.path),
+                    functools.partial(_close_then_release, store, token),
+                )
+            except asyncio.CancelledError:
+                # Cancelled while the file opens: the pin ends only after the
+                # handle closes (Windows cannot unlink an open file).
+                pinned = False
+                raise
+            except OSError:
+                store.release(token)
+                return _error(404, "capture-expired", _MESSAGES["capture-expired"])
+            try:
+                return await self._stream_capture(request, capture, handle)
+            finally:
+                handle.close()
+        finally:
+            if pinned:
+                store.release_use(token)
+
+    @staticmethod
+    async def _stream_capture(request, capture, handle) -> web.StreamResponse:
+        """The capture's bytes, or the one byte range a ``Range`` header asks for.
+
+        The response is written here, inside the caller's pin, so the handle
+        is closed and the pin ended only after the last byte is sent.
+        """
+        size = capture.size
+        headers = {
+            "Content-Type": preview_content_type(Path(capture.path).suffix),
+            "Accept-Ranges": "bytes",
+            "Cache-Control": "no-store",
+            "X-Content-Type-Options": "nosniff",
+        }
+        status, start, end = 200, 0, size
+        if "Range" in request.headers:
+            wanted = _byte_range(request, size)
+            if wanted is None:
+                return web.Response(
+                    status=416,
+                    headers={**headers, "Content-Range": f"bytes */{size}"},
+                )
+            status, (start, end) = 206, wanted
+            headers["Content-Range"] = f"bytes {start}-{end - 1}/{size}"
+        headers["Content-Length"] = str(end - start)
+        response = web.StreamResponse(status=status, headers=headers)
+        await response.prepare(request)
+        loop = asyncio.get_running_loop()
+        if start:
+            await loop.run_in_executor(None, handle.seek, start)
+        remaining = end - start
+        while remaining > 0 and request.method != "HEAD":
+            chunk = await loop.run_in_executor(
+                None, handle.read, min(_PREVIEW_CHUNK, remaining)
+            )
+            if not chunk:
+                break
+            remaining -= len(chunk)
+            await response.write(chunk)
+        await response.write_eof()
+        return response
+
+    async def release_capture(self, request: web.Request) -> web.Response:
+        """DELETE a capture token; releasing an unknown token is a success."""
+        token = request.match_info["token"]
+        store = self._captures
+        if store is not None and _TOKEN.fullmatch(token) is not None:
+            store.release(token)
+        return web.json_response(
+            {"success": True}, headers={"Cache-Control": "no-store"}
+        )
+
+    # -- save ------------------------------------------------------------------
+
+    async def save_image_tags(self, request: web.Request) -> web.Response:
+        """PUT the tag set of the previewed bytes, re-hashing the current file.
+
+        Writes only when the file still holds the captured bytes
+        (``file-changed`` with zero writes otherwise), under the storage epoch
+        and the tag revision the dialog read; an identical retry is
+        ``replayed``. The hash never runs inside a database transaction.
+        """
+        data, error = await self._annotation_body(request, _SAVE_FIELDS)
+        if error is not None:
+            return error
+        target, error = _target(data["target"])
+        if error is not None:
+            return error
+        guards, error = _save_guards(data)
+        if error is not None:
+            return error
+        token, sha256, expected_epoch, revision, tags = guards
+        index, scope, relative = target
+        root, error = self._scoped_root(index, scope)
+        if error is not None:
+            return error
+        store = self._captures
+        capture = store.get(token) if store is not None else None
+        if capture is None:
+            return _coded("capture-expired")
+        if capture.root_index != index or capture.scope != scope:
+            return _coded("capture-expired", _OTHER_FILE)
+        if sha256 != capture.sha256:
+            return bad_request("sha256 does not match the preview")
+        if expected_epoch != capture.epoch:
+            current = await self._run_in_executor(self.db.get_execution_epoch)
+            return _coded("storage-changed", library_epoch=current)
+        try:
+            facts = await self._run_in_executor(
+                _verify_captured_file, store, capture, root, relative
+            )
+        except CaptureError as exc:
+            return _capture_error(exc)
+        if facts is None or facts.locator != capture.locator:
+            return _coded("capture-expired", _OTHER_FILE)
+        if facts.sha256 != capture.sha256:
+            return _coded("file-changed")
+        try:
+            receipt = await self._run_in_executor(
+                self.db.replace_image_tags,
+                locator=facts.locator,
+                sha256=facts.sha256,
+                size=facts.size,
+                mtime_ns=facts.mtime_ns,
+                expected_epoch=expected_epoch,
+                expected_tag_revision=revision,
+                tags=tags,
+            )
+        except AnnotationCommandError as exc:
+            current = exc.current or {}
+            return _coded(
+                exc.code,
+                library_epoch=exc.epoch,
+                tags=current.get("tags", []),
+                tag_revision=current.get("tag_revision", 0),
+            )
+        except LibraryCommandError as exc:
+            return _coded(exc.code, library_epoch=exc.epoch)
+        except ValueError as exc:
+            return bad_request(str(exc))
+        except Exception:
+            self.logger.exception("Image tag save failed")
+            return _error(500, "save-failed", "The tags could not be saved.")
+        return web.json_response(
+            {"success": True, **receipt}, headers={"Cache-Control": "no-store"}
+        )
+
+    # -- suggest ---------------------------------------------------------------
+
+    async def suggest_image_tags(self, request: web.Request) -> web.Response:
+        """POST: the top N tags of the captured bytes from one legacy engine.
+
+        Runs only on the private capture (pinned for the whole inference),
+        under the shared model gate (``model-busy`` while anything else holds
+        it, including a legacy batch), never downloads (``model-unavailable``)
+        and never writes.
+        """
+        from ..autotag import MODELS, get_autotag_service
+        from ..config import MAX_SUGGESTION_LIMIT, AutotagConfig
+
+        data, error = await self._annotation_body(request, SUGGEST_FIELDS)
+        if error is not None:
+            return error
+        target, error = _target(data["target"])
+        if error is not None:
+            return error
+        try:
+            model_type, options = validate_options(
+                data["model_type"],
+                data["options"],
+                default_limit=AutotagConfig.suggestion_limit(),
+                max_limit=MAX_SUGGESTION_LIMIT,
+            )
+        except OptionError as exc:
+            return bad_request(str(exc))
+        token, epoch = data["capture_token"], data["expected_epoch"]
+        if not isinstance(token, str) or _TOKEN.fullmatch(token) is None:
+            return bad_request("Invalid capture token")
+        if not isinstance(epoch, str) or _UUID.fullmatch(epoch) is None:
+            return bad_request("expected_epoch must be a canonical UUID")
+        index, scope, relative = target
+        root, error = self._scoped_root(index, scope)
+        if error is not None:
+            return error
+        store = self._captures
+        capture = store.acquire(token) if store is not None else None
+        if capture is None:
+            return _coded("capture-expired")
+        started = False
+        try:
+            error = await self._suggest_guards(capture, target, root, epoch)
+            if error is not None:
+                return error
+            service = get_autotag_service()
+            status = await self._run_in_executor(service.get_models_status)
+            if not status.get(model_type, {}).get("downloaded"):
+                name = MODELS.get(model_type, {}).get("name", model_type)
+                return _coded("model-unavailable", unavailable_message(name))
+            owner = model_gate.new_owner("image-annotations")
+            if not model_gate.try_acquire(owner):
+                return model_busy_response()
+            try:
+                # From here the pin is the gate's to end: the worker ends it,
+                # or ``on_skipped`` does when the worker never starts.
+                started = True
+                pairs = await model_gate.run(
+                    owner,
+                    _pinned_suggestions,
+                    store,
+                    token,
+                    service,
+                    capture,
+                    model_type,
+                    options,
+                    on_skipped=functools.partial(store.release_use, token),
+                )
+            except Exception:
+                self.logger.exception("Tag suggestion failed")
+                return _error(
+                    500,
+                    "suggest-failed",
+                    "Auto-tagging failed. Check server logs for details.",
+                )
+            finally:
+                model_gate.release(owner)
+        finally:
+            if not started:
+                store.release_use(token)
+        return web.json_response(
+            {
+                "success": True,
+                "model_type": model_type,
+                "options": options,
+                "suggestions": suggestion_rows(pairs),
+            },
+            headers={"Cache-Control": "no-store"},
+        )
+
+    async def _suggest_guards(self, capture, target, root, epoch):
+        """The capture must be this target's, of this epoch, and inferable."""
+        index, scope, relative = target
+        expected = os.path.normcase(
+            os.path.join(os.path.realpath(root), *relative.split("/"))
+        )
+        if (
+            capture.root_index != index
+            or capture.scope != scope
+            or capture.locator != expected
+        ):
+            return _coded("capture-expired", _OTHER_FILE)
+        if epoch != capture.epoch:
+            current = await self._run_in_executor(self.db.get_execution_epoch)
+            return _coded("storage-changed", library_epoch=current)
+        if not capture.inferable:
+            return _coded("unsupported-media", capture.inferable_reason)
+        return None
+
+
+def _close_then_release(store: CaptureStore, token: str, handle) -> None:
+    """Close a preview handle a cancelled request opened, then end its pin."""
+    try:
+        if handle is not None:
+            handle.close()
+    finally:
+        store.release_use(token)
+
+
+def _byte_range(request: web.Request, size: int):
+    """``(start, end)`` of the one satisfiable byte range asked for, else None.
+
+    A malformed, multi-range or unsatisfiable header is None (416), as
+    aiohttp's own file responses answer it.
+    """
+    try:
+        wanted = request.http_range
+    except ValueError:
+        return None
+    start, stop = wanted.start, wanted.stop
+    if start is None:
+        return None
+    if start < 0:  # a suffix: the last -start bytes
+        start = max(0, size + start)
+        stop = size
+    stop = size if stop is None else min(stop, size)
+    if start >= size or stop <= start:
+        return None
+    return start, stop
+
+
+def _pinned_suggestions(store, token, service, capture, model_type, options):
+    """Worker thread: infer on the capture, then end its pin (even on error)."""
+    try:
+        return run_suggestions(service, capture.path, model_type, options)
+    finally:
+        store.release_use(token)
+
+
+def _verify_captured_file(store: CaptureStore, capture, root, relative: str):
+    """Re-hash the current file, or None when the token names another file.
+
+    The cheap locator comparison runs first, so a token sent for another
+    target never costs a whole-file hash.
+    """
+    expected = os.path.normcase(
+        os.path.join(os.path.realpath(root), *relative.split("/"))
+    )
+    if expected != capture.locator:
+        return None
+    return store.verify(root, relative)
+
+
+def _save_guards(data: dict):
+    """Validated ``(token, sha256, epoch, revision, tags)`` or ``(None, error)``."""
+    token = data["capture_token"]
+    if not isinstance(token, str) or _TOKEN.fullmatch(token) is None:
+        return None, bad_request("Invalid capture token")
+    sha256 = data["sha256"]
+    if not isinstance(sha256, str) or _HEX64.fullmatch(sha256) is None:
+        return None, bad_request("sha256 must be 64 lowercase hexadecimal characters")
+    epoch = data["expected_epoch"]
+    if not isinstance(epoch, str) or _UUID.fullmatch(epoch) is None:
+        return None, bad_request("expected_epoch must be a canonical UUID")
+    revision = data["expected_tag_revision"]
+    if type(revision) is not int or revision < 0:
+        return None, bad_request("expected_tag_revision must be a non-negative integer")
+    try:
+        tags = normalize_image_tags(data["tags"])
+    except ImageTagLimitError as exc:
+        return None, _error(400, "tag-limit", str(exc))
+    except ValueError as exc:
+        return None, bad_request(str(exc))
+    return (token, sha256, epoch, revision, tags), None

py/api/autotag_routes.py

@@ -9,11 +9,24 @@ from typing import Optional
 from urllib.parse import quote
 
 from .prompts import thumbnail_url_for
+from .. import model_gate
 
 from aiohttp import web
 
 _INTERNAL_ERROR = "An internal error occurred. Check server logs for details."
 _BUSY_ERROR = "Auto-tagging is already running"
+MODEL_BUSY_ERROR = (
+    "A tagging model is busy with another operation. Try again when it finishes."
+)
+
+
+def model_busy_response() -> web.Response:
+    """``409 model-busy``: another operation holds the shared model gate."""
+    return web.json_response(
+        {"success": False, "code": "model-busy", "error": MODEL_BUSY_ERROR},
+        status=409,
+    )
+
 
 # Only these may be handed to the tagging engine or listed by the scanner.
 _MEDIA_EXTENSIONS = frozenset(
@@ -86,6 +99,7 @@ class AutotagRoutesMixin:
         """Get status of available AutoTag models."""
         try:
             from ..autotag import get_autotag_service
+            from ..config import AutotagConfig
 
             service = get_autotag_service()
             models_status = service.get_models_status()
@@ -99,6 +113,7 @@ class AutotagRoutesMixin:
                     "loaded_model_type": service.get_loaded_model_type(),
                     "wd14_general_threshold": service.wd14_general_threshold,
                     "wd14_character_threshold": service.wd14_character_threshold,
+                    "suggestion_limit": AutotagConfig.suggestion_limit(),
                 }
             )
 
@@ -138,6 +153,7 @@ class AutotagRoutesMixin:
     async def download_autotag_model(self, request):
         """Download an AutoTag model with streaming progress (POST only)."""
         model_type = request.match_info.get("model_type")
+        owner = model_gate.new_owner("legacy-download")
 
         async def events():
             try:
@@ -160,8 +176,8 @@ class AutotagRoutesMixin:
                 def progress_callback(status: str, progress: float):
                     pass
 
-                success = await self._run_in_executor(
-                    service.download_model, model_type, progress_callback
+                success = await model_gate.run(
+                    owner, service.download_model, model_type, progress_callback
                 )
                 if success:
                     yield {
@@ -178,7 +194,12 @@ class AutotagRoutesMixin:
                     "message": _INTERNAL_ERROR,
                 }
 
-        return await self._stream_sse(request, events())
+        if not model_gate.try_acquire(owner):
+            return model_busy_response()
+        try:
+            return await self._stream_sse(request, events())
+        finally:
+            model_gate.release(owner)
 
     async def _read_start_params(self, request) -> Optional[dict]:
         """Merge query-string and optional JSON-body parameters for autotag/start.
@@ -239,8 +260,9 @@ class AutotagRoutesMixin:
             return
 
         yield {"type": "progress", "progress": 0, "status": "Loading model..."}
+        run = self._gated_runner(opts.get("gate_owner"))
         try:
-            await self._run_in_executor(service.load_model, model_type, True)
+            await run(service.load_model, model_type, True)
         except Exception:
             self.logger.exception("Failed to load model")
             yield {
@@ -338,7 +360,7 @@ class AutotagRoutesMixin:
                     continue
 
                 try:
-                    tags = await self._run_in_executor(
+                    tags = await run(
                         service.generate_tags,
                         allowed_path,
                         general_threshold=opts["general_threshold"],
@@ -423,10 +445,26 @@ class AutotagRoutesMixin:
                 {"success": False, "error": _BUSY_ERROR}, status=409
             )
         try:
-            return await self._stream_sse(request, events())
+            opts["gate_owner"] = model_gate.new_owner("legacy-batch")
+            if not model_gate.try_acquire(opts["gate_owner"]):
+                return model_busy_response()
+            try:
+                return await self._stream_sse(request, events())
+            finally:
+                model_gate.release(opts["gate_owner"])
         finally:
             _autotag_batch_lock.release()
 
+    def _gated_runner(self, owner):
+        """Executor calls under the model gate *owner* holds (plain when None)."""
+        if owner is None:
+            return self._run_in_executor
+
+        async def run(func, *args, **kwargs):
+            return await model_gate.run(owner, func, *args, **kwargs)
+
+        return run
+
     def _resolve_allowed_image_path(self, raw_path: str) -> Optional[str]:
         """Return the real path when it is a media file inside an output directory."""
         if Path(str(raw_path)).suffix.lower() not in _MEDIA_EXTENSIONS:
@@ -549,22 +587,28 @@ class AutotagRoutesMixin:
             from ..autotag import get_autotag_service
 
             service = get_autotag_service()
+            owner = model_gate.new_owner("legacy-single")
+            if not model_gate.try_acquire(owner):
+                return model_busy_response()
+            try:
+                if (
+                    not service.is_model_loaded()
+                    or service.get_loaded_model_type() != model_type
+                ):
+                    await model_gate.run(owner, service.load_model, model_type, use_gpu)
 
-            if (
-                not service.is_model_loaded()
-                or service.get_loaded_model_type() != model_type
-            ):
-                await self._run_in_executor(service.load_model, model_type, use_gpu)
+                if custom_prompt:
+                    service.custom_prompt = custom_prompt
 
-            if custom_prompt:
-                service.custom_prompt = custom_prompt
-
-            tags = await self._run_in_executor(
-                service.generate_tags,
-                image_path,
-                general_threshold=general_threshold,
-                character_threshold=character_threshold,
-            )
+                tags = await model_gate.run(
+                    owner,
+                    service.generate_tags,
+                    image_path,
+                    general_threshold=general_threshold,
+                    character_threshold=character_threshold,
+                )
+            finally:
+                model_gate.release(owner)
 
             return web.json_response(
                 {
@@ -636,14 +680,19 @@ class AutotagRoutesMixin:
             from ..autotag import get_autotag_service
 
             service = get_autotag_service()
+            owner = model_gate.new_owner("legacy-unload")
+            if not model_gate.try_acquire(owner):
+                return model_busy_response()
+            try:
+                if not service.is_model_loaded():
+                    return web.json_response(
+                        {"success": True, "message": "No model was loaded"}
+                    )
 
-            if not service.is_model_loaded():
-                return web.json_response(
-                    {"success": True, "message": "No model was loaded"}
-                )
-
-            model_type = service.get_loaded_model_type()
-            service.unload_model()
+                model_type = service.get_loaded_model_type()
+                service.unload_model()
+            finally:
+                model_gate.release(owner)
 
             return web.json_response(
                 {

py/api/images.py

@@ -14,7 +14,7 @@ import urllib.parse
 from bisect import bisect_left, bisect_right
 from collections.abc import Mapping
 from pathlib import Path
-from typing import NamedTuple
+from typing import Callable, NamedTuple
 
 from aiohttp import web
 from PIL import Image, UnidentifiedImageError
@@ -74,6 +74,7 @@ IMAGE_EXTENSIONS = _IMAGE_EXTENSIONS
 # The header records the card parses (see utils.card_seed.header_params).
 _CARD_RECORDS = ("prompt", "workflow")
 _PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+_LISTING_FAILED = "The image list could not be filtered. Check server logs for details."
 
 
 def _card_header(path: Path) -> tuple:
@@ -418,6 +419,29 @@ def _listed(path: Path, mtime: float, root: Path, index: int) -> _Listed:
     )
 
 
+class _ImageTagMatch(NamedTuple):
+    """How one listed file's current image tags meet the filters (#249 B3)."""
+
+    tags: bool  # every filter tag is in its image tags or linked positive tags
+    query: bool  # ``q`` is a case-folded substring of one image tag name
+    link: tuple | None  # (hit, rating, positive id) of its unambiguous link
+
+
+def _current_fingerprint(path: Path) -> tuple[int, int] | None:
+    """The file's present ``(st_size, st_mtime_ns)``; None when it is gone."""
+    try:
+        observed = os.stat(path)
+    except OSError:
+        return None
+    return observed.st_size, observed.st_mtime_ns
+
+
+def _image_tags_relevant(names: list, wanted: set, query: str) -> bool:
+    if wanted and not wanted.isdisjoint(names):
+        return True
+    return bool(query) and any(query in name.casefold() for name in names)
+
+
 def _workspace_key(entry: tuple, order: str) -> tuple:
     """The keyset sort key of *entry* (a _Listed or a 4-tuple entry)."""
     if not isinstance(entry, _Listed):
@@ -705,6 +729,8 @@ def _workspace_filters(query: Mapping) -> dict:
     media = query.get("media", "all")
     order = query.get("sort", "newest")
     folder = query.get("subfolder", "").strip().replace("\\", "/")
+    # ``path``: one exact relative path (Activity opens a scan row by it, D57).
+    exact = query.get("path", "").strip().replace("\\", "/")
     category = query.get("category", "").strip() or None
     tags = sorted(
         {tag.strip() for tag in query.get("tags", "").split(",") if tag.strip()}
@@ -723,12 +749,15 @@ def _workspace_filters(query: Mapping) -> dict:
         raise ValueError("Invalid gallery filters")
     if folder and (_has_traversal(folder) or len(folder) > 1024):
         raise ValueError("Invalid gallery folder")
+    if exact and (_has_traversal(exact) or len(exact) > 1024):
+        raise ValueError("Invalid gallery path")
     return {
         "text": text,
         "query": folded,
         "media": media,
         "order": order,
         "folder": folder,
+        "path": exact.casefold(),
         "category": category,
         "tags": tags,
         "favorites": favorites == "1",
@@ -747,6 +776,7 @@ def _filtered_page(
     filters: dict,
     links: dict | None,
     favorites: frozenset | None = None,
+    image_tags: dict | None = None,
 ) -> tuple[int, list, int | None]:
     """Count the *entries* the filters admit and take *size* from *start* on.
 
@@ -756,13 +786,19 @@ def _filtered_page(
     or a linked-positive hit. Returns the total, the page and the number of
     distinct linked positives among all admitted entries (None without links).
     *favorites*, when given, admits only those listed paths (``favorites=1``).
+    *image_tags* maps normalized paths to their _ImageTagMatch: a tag filter
+    also admits a file whose current image tags (with its linked positive's
+    tags) carry every tag, and ``q`` also admits an image tag name hit.
     """
     query, media, folder = filters["query"], filters["media"], filters["folder"]
     members_only = filters["category"] is not None or bool(filters["tags"])
     native_folder = folder.replace("/", os.sep)
     nested = native_folder + os.sep
     total, page, positives = 0, [], set()
+    exact = filters.get("path", "")
     for position, entry in enumerate(entries):
+        if exact and entry.folded != exact:
+            continue
         if folder and not (
             entry.folder == native_folder or entry.folder.startswith(nested)
         ):
@@ -772,9 +808,15 @@ def _filtered_page(
         if favorites is not None and entry.path not in favorites:
             continue
         match = None if links is None else links.get(entry.normalized)
-        if members_only and match is None:
+        image = None if image_tags is None else image_tags.get(entry.normalized)
+        if members_only and match is None and not (image and image.tags):
             continue
-        if query and query not in entry.folded and not (match and match[0]):
+        if (
+            query
+            and query not in entry.folded
+            and not (match and match[0])
+            and not (image and image.query)
+        ):
             continue
         total += 1
         if match is not None:
@@ -1132,7 +1174,7 @@ class ImageRoutesMixin:
                 }
             )
         except Exception as e:
-            self.logger.error(f"Output images error: {e}")
+            self.logger.error(f"Output images error: {e}", exc_info=True)
             return web.json_response(
                 {"success": False, "error": _safe_error(e)}, status=500
             )
@@ -1155,6 +1197,7 @@ class ImageRoutesMixin:
                         filters["media"],
                         filters["order"],
                         filters["folder"],
+                        filters["path"],
                         root_index,
                         [str(root) for root in output_dirs],
                         filters["category"],
@@ -1175,11 +1218,27 @@ class ImageRoutesMixin:
             for index, root in enumerate(output_dirs)
             if root_index is None or index == root_index
         ]
-        page, total, has_more, next_cursor, positive_count = (
-            await self._run_in_executor(
-                self._select_workspace_page, listings, filters, after, limit, scope
+        try:
+            page, total, has_more, next_cursor, positive_count = (
+                await self._run_in_executor(
+                    self._select_workspace_page, listings, filters, after, limit, scope
+                )
+            )
+        except Exception:
+            # A filter that needs the prompt links or the image tags cannot be
+            # served without them. Never echo the exception: it can carry SQL
+            # or database text. The traceback goes to the server log.
+            self.logger.error(
+                "Workspace image list could not be filtered", exc_info=True
+            )
+            return web.json_response(
+                {
+                    "success": False,
+                    "code": "listing-failed",
+                    "error": _LISTING_FAILED,
+                },
+                status=500,
             )
-        )
         images = await self._run_in_executor(self._format_workspace_page, page)
         result = {
             "success": True,
@@ -1267,6 +1326,80 @@ class ImageRoutesMixin:
                 )
         return orders[order]
 
+    def _workspace_locators(self, listings: list[tuple]) -> dict:
+        """The selected listing's private locators -> _Listed (cached).
+
+        A locator is ``normcase(join(realpath(root), relative))``, the key
+        image tags are stored under (database/annotations.py); the listing
+        never follows symlinks, so it equals the listed file's own locator.
+        """
+        orders = self._workspace_orders(listings)
+        reals = tuple(os.path.realpath(root) for _index, root, _files in listings)
+        key = ("locators", reals)
+        if key not in orders:
+            located = {}
+            for (index, root, files), real in zip(listings, reals):
+                prefix = os.path.join(str(root), "")
+                for entry in self._workspace_listed(index, root, files):
+                    text = str(entry.path)
+                    relative = (
+                        text[len(prefix) :]
+                        if text.startswith(prefix)
+                        else str(entry.path.relative_to(root))
+                    )
+                    located[os.path.normcase(os.path.join(real, relative))] = entry
+            orders[key] = located
+        return orders[key]
+
+    def _image_tag_matches(self, listings: list[tuple], filters: dict) -> dict:
+        """Normalized path -> _ImageTagMatch for files whose image tags count.
+
+        Streams the tagged byte records once and keeps only listed locators
+        carrying a filter tag or a ``q`` hit; only those candidates are
+        stat'ed (never every listed file), and a candidate's tags count only
+        while a byte record is verified at its present ``(size, mtime_ns)``
+        (spec amendment S1). Under a Tags filter the candidates' linked
+        positives are read too, so their tags and category combine.
+        """
+        tags, query, category = filters["tags"], filters["query"], filters["category"]
+        wanted = set(tags)
+        located = self._workspace_locators(listings)
+        candidates = {}
+        records = self.db.iter_image_tag_records()
+        try:
+            for locator, _size, _mtime_ns, names in records:
+                entry = located.get(locator)
+                if entry is not None and locator not in candidates:
+                    if _image_tags_relevant(names, wanted, query):
+                        candidates[locator] = entry
+        finally:
+            records.close()
+        stats = {}
+        for locator, entry in candidates.items():
+            fingerprint = _current_fingerprint(entry.path)
+            if fingerprint is not None:
+                stats[locator] = fingerprint
+        current = self.db.current_image_tags(stats) if stats else {}
+        facts = {}
+        if wanted and current:
+            facts = self.db.get_image_link_facts(
+                [candidates[locator].normalized for locator in current],
+                filters["text"],
+            )
+        matches = {}
+        for locator, names in current.items():
+            entry = candidates[locator]
+            link = facts.get(entry.normalized)
+            carried = set(names).union(link[4] if link else ())
+            matches[entry.normalized] = _ImageTagMatch(
+                bool(wanted)
+                and wanted <= carried
+                and (category is None or (link is not None and link[3] == category)),
+                bool(query) and any(query in name.casefold() for name in names),
+                link[:3] if link else None,
+            )
+        return matches
+
     def _select_workspace_page(
         self,
         listings: list[tuple],
@@ -1319,6 +1452,30 @@ class ImageRoutesMixin:
                     ),
                     exc_info=True,
                 )
+        image_tags = None
+        if filters["query"] or tags:
+            try:
+                image_tags = self._image_tag_matches(listings, filters)
+            except Exception:
+                # A Tags filter cannot be served without them (as without the
+                # links); a search then matches without image tags.
+                if tags:
+                    raise
+                self.logger.warning(
+                    "Workspace image tags could not be read; searching without "
+                    "image tags",
+                    exc_info=True,
+                )
+        if image_tags and links is not None:
+            # A linked file admitted through its image tags keeps its rating
+            # and counts its positive.
+            admitted = {
+                path: match.link
+                for path, match in image_tags.items()
+                if match.tags and match.link is not None and path not in links
+            }
+            if admitted:
+                links = {**links, **admitted}
         if order == "rating":
 
             def rank(entry):
@@ -1351,7 +1508,7 @@ class ImageRoutesMixin:
             self._workspace_favorite_paths(listings) if filters["favorites"] else None
         )
         total, page, positive_count = _filtered_page(
-            entries, start, limit + 1, filters, links, favorites
+            entries, start, limit + 1, filters, links, favorites, image_tags
         )
         if not needed and after is not None:
             positive_count = _COUNT_OMITTED
@@ -2458,6 +2615,9 @@ class ImageRoutesMixin:
                         library=self._inspection_library(
                             saved, unavailable=unavailable
                         ),
+                        image_tags=self._inspection_image_tags(
+                            roots[index], Path(relative).parts
+                        ),
                     )
                 except CurrentFileChanged:
                     return None
@@ -2496,6 +2656,30 @@ class ImageRoutesMixin:
                 {"success": False, "error": "Prompt inspection failed"}, status=500
             )
 
+    def _inspection_image_tags(self, root: Path, parts: tuple) -> Callable:
+        """The inspector's ``image_tags`` reader for one rooted file (S1).
+
+        The returned function takes the inspection's own stable stat and
+        answers ``current`` only for a byte record verified at exactly that
+        ``(size, mtime_ns)``; a failed read is ``unavailable``, never an error.
+        """
+        locator = os.path.normcase(os.path.join(os.path.realpath(root), *parts))
+
+        def read(size: int, mtime_ns: int) -> dict:
+            try:
+                found = self.db.current_image_tags({locator: (size, mtime_ns)})
+            except Exception:
+                self.logger.warning(
+                    "Inspection image tags could not be read", exc_info=True
+                )
+                return {"state": "unavailable", "tags": []}
+            tags = found.get(locator)
+            if tags is None:
+                return {"state": "none", "tags": []}
+            return {"state": "current", "tags": list(tags)}
+
+        return read
+
     def _inspection_library(self, saved: dict | None, *, unavailable: bool) -> dict:
         """The inspector's Library facts; the route sets the title afterwards."""
         result = {

py/api/inspection_service.py

@@ -3,6 +3,7 @@
 import os
 import stat
 from pathlib import Path
+from typing import Callable
 
 try:
     from ...utils.prompt_inspector import (
@@ -93,8 +94,19 @@ def _in_host_temp(path: Path) -> bool:
 
 
 def inspect_current_file(
-    path: Path, *, source_label: str, saved: dict | None, library: dict
+    path: Path,
+    *,
+    source_label: str,
+    saved: dict | None,
+    library: dict,
+    image_tags: Callable[[int, int], dict] | None = None,
 ) -> dict:
+    """Current-file evidence read between two equal stats of *path*.
+
+    *image_tags*, when given, is called once with that stable
+    ``(st_size, st_mtime_ns)`` and its facet is returned as ``image_tags``
+    (spec amendment S1: tags of a byte record verified at exactly that stat).
+    """
     before = _current_file_facts(path)
     try:
         inspection = read_inspection_file(path)
@@ -104,6 +116,9 @@ def inspect_current_file(
     fields = ("st_dev", "st_ino", "st_mode", "st_size", "st_mtime_ns", "st_ctime_ns")
     if any(getattr(before, key) != getattr(after, key) for key in fields):
         raise CurrentFileChanged
+    facets = {}
+    if image_tags is not None:
+        facets["image_tags"] = image_tags(before.st_size, before.st_mtime_ns)
     if inspection is None:
         evidence = unreadable_evidence()
     else:
@@ -132,4 +147,5 @@ def inspect_current_file(
         **evidence,
         "inspection": inspection,
         "library": library,
+        **facets,
     }

py/api/job_routes.py

@@ -0,0 +1,161 @@
+"""Session job routes (Activity): list, inspect, follow and cancel jobs.
+
+The registry itself is ``py/api/jobs.py``; the scan job's runner is in
+``py/api/admin.py``. Every response leaves out absolute server paths: job
+rows already carry root-relative paths and public root labels.
+"""
+
+import contextlib
+import json
+
+from aiohttp import web
+
+from .jobs import DEFAULT_SCAN_SCOPE, SCAN_SCOPES, JobBusy
+
+
+def _not_found():
+    return web.json_response({"success": False, "error": "Job not found"}, status=404)
+
+
+def _bad_request(message):
+    return web.json_response({"success": False, "error": message}, status=400)
+
+
+async def _scan_scope(request):
+    """The requested scan scope ("new" or "all"), or None when the body is invalid.
+
+    An empty body (also a chunked one with no bytes), or one without
+    ``scope``, asks for the default.
+    """
+    if not request.can_read_body:
+        return DEFAULT_SCAN_SCOPE
+    text = await request.text()
+    if not text.strip():  # e.g. a chunked POST that sent no bytes
+        return DEFAULT_SCAN_SCOPE
+    try:
+        body = json.loads(text)
+    except ValueError:
+        return None
+    if not isinstance(body, dict):
+        return None
+    scope = body.get("scope", DEFAULT_SCAN_SCOPE)
+    return scope if scope in SCAN_SCOPES else None
+
+
+def _summary_event(job):
+    return f"data: {json.dumps(job.summary())}\n\n".encode("utf-8")
+
+
+class JobRoutesMixin:
+    """Mixin providing the /prompt_manager/jobs endpoints."""
+
+    def _register_job_routes(self, routes):
+        @routes.get("/prompt_manager/jobs")
+        async def list_jobs_route(request):
+            return await self.list_jobs(request)
+
+        @routes.post("/prompt_manager/jobs/scan")
+        async def start_scan_job_route(request):
+            return await self.start_scan_job(request)
+
+        @routes.get("/prompt_manager/jobs/{job_id}")
+        async def job_detail_route(request):
+            return await self.job_detail(request)
+
+        @routes.get("/prompt_manager/jobs/{job_id}/report")
+        async def job_report_route(request):
+            return await self.job_report(request)
+
+        @routes.get("/prompt_manager/jobs/{job_id}/events")
+        async def job_events_route(request):
+            return await self.job_events(request)
+
+        @routes.post("/prompt_manager/jobs/{job_id}/cancel")
+        async def cancel_job_route(request):
+            return await self.cancel_job(request)
+
+    async def list_jobs(self, request):
+        """This session's jobs: running first, then finished, newest first."""
+        jobs = [job.summary() for job in self._jobs.list()]
+        return web.json_response({"success": True, "jobs": jobs})
+
+    async def job_detail(self, request):
+        job = self._jobs.get(request.match_info["job_id"])
+        if job is None:
+            return _not_found()
+        return web.json_response({"success": True, "job": job.detail()})
+
+    async def job_report(self, request):
+        """The job's whole record as a JSON attachment (no absolute paths)."""
+        job = self._jobs.get(request.match_info["job_id"])
+        if job is None:
+            return _not_found()
+        body = json.dumps(job.report(), indent=2)
+        disposition = f'attachment; filename="{job.report_filename()}"'
+        return web.Response(
+            text=body,
+            content_type="application/json",
+            headers={
+                "Content-Disposition": disposition,
+                "Cache-Control": "no-store",
+            },
+        )
+
+    async def cancel_job(self, request):
+        """Stop a job at its next file boundary; a finished job is a no-op."""
+        job_id = request.match_info["job_id"]
+        if self._jobs.get(job_id) is None:
+            return _not_found()
+        requested = self._jobs.cancel(job_id)
+        return web.json_response({"success": True, "cancellation_requested": requested})
+
+    async def start_scan_job(self, request):
+        """Start the metadata scan as a job (202), or 409 naming the busy job.
+
+        The body's ``scope`` is "new" (the default: new and unresolved files)
+        or "all"; anything else is a 400.
+        """
+        files = await _scan_scope(request)
+        if files is None:
+            return _bad_request('The scan scope must be "new" or "all"')
+        try:
+            job = self._start_scan_job(files)
+        except JobBusy as busy:
+            running = busy.running
+            return web.json_response(
+                {
+                    "success": False,
+                    "code": "busy",
+                    "error": str(busy),
+                    "running": {"id": running.id, "title": running.title},
+                },
+                status=409,
+            )
+        return web.json_response({"success": True, "job": job.summary()}, status=202)
+
+    async def job_events(self, request):
+        """Stream the job's summary as SSE: now, after each event, and at the end."""
+        job = self._jobs.get(request.match_info["job_id"])
+        if job is None:
+            return _not_found()
+        response = web.StreamResponse(
+            status=200,
+            reason="OK",
+            headers={
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+            },
+        )
+        await response.prepare(request)
+        try:
+            await response.write(_summary_event(job))
+            async with contextlib.aclosing(job.events()) as events:
+                async for _payload in events:
+                    await response.write(_summary_event(job))
+            # The last event is published before the job takes its final state.
+            await response.write(_summary_event(job))
+            await response.write_eof()
+        except Exception as e:  # the socket closed under us; the job goes on
+            self.logger.info(f"Job progress client disconnected ({e})")
+        return response

py/api/jobs.py

@@ -0,0 +1,359 @@
+"""The session job registry: every long operation as one tracked job.
+
+A job runs as an asyncio task that outlives the HTTP request that started it,
+so an accidental tab close never abandons half-finished work. Each job keeps
+its counters, a capped list of file outcomes per outcome group and a capped
+log, and fans its progress out to SSE subscribers: the request that started
+it, a reconnecting page, a second tab. A subscriber receives the latest event
+as a snapshot and then every event published after it, until the job ends.
+
+Jobs live only in server memory and are gone after a restart. The registry
+keeps the running jobs and this session's last ``MAX_FINISHED_JOBS`` finished
+ones. Record-changing jobs (the metadata scan, and later maintenance, cleanup
+and restore) never run together, and one job of a kind runs at a time.
+"""
+
+import asyncio
+import itertools
+import logging
+import re
+import time
+import uuid
+from pathlib import PurePosixPath, PureWindowsPath
+
+logger = logging.getLogger(__name__)
+# Start and finish order: wall-clock times can tie (coarse Windows clocks).
+_sequence = itertools.count()
+
+JOB_STATES = ("running", "finished", "cancelled", "failed")
+FINAL_STATES = JOB_STATES[1:]
+MAX_OUTCOME_ROWS = 200  # rows listed per outcome group; counters stay exact
+MAX_LOG_LINES = 2000
+LOG_CAP_LINE = "[Log capped at 2,000 lines]"
+MAX_FINISHED_JOBS = 20  # finished jobs this session keeps
+
+# The metadata scan's outcome groups, in counter-tile order of the spec's
+# mapping, and the per-file scan status each group collects. Files without
+# usable metadata have no status and go to "no_metadata".
+# Which files a scan reads (#249 Activity-2): "new" skips the files the Library
+# already links with a resolved link (get_known_resolved_paths) before reading
+# them, so new, unlinked, unresolved and ambiguous files are read; "all" reads
+# every file again. The workspace job defaults to "new"; legacy /scan is "all".
+SCAN_SCOPES = ("new", "all")
+DEFAULT_SCAN_SCOPE = "new"
+SCAN_GROUP_NAMES = ("added", "known", "review", "no_metadata", "errors")
+SCAN_GROUPS = {
+    "added": "added",
+    "linked": "added",
+    "enriched": "added",
+    "unchanged": "known",
+    "skipped": "known",  # "new" scope: known and resolved, not read again
+    "ambiguous": "review",
+    "conflict": "review",
+    "unresolved": "review",
+    "failed": "errors",
+}
+
+
+def _relative_path(path) -> str:
+    """``path`` as a root-relative POSIX path; an absolute one keeps its name."""
+    text = str(path or "")
+    if (
+        PurePosixPath(text).is_absolute()
+        or PureWindowsPath(text).is_absolute()
+        or PureWindowsPath(text).drive
+    ):
+        return re.split(r"[\\/]", text)[-1]
+    return text.replace("\\", "/")
+
+
+class JobBusy(Exception):
+    """A job could not start because ``running`` holds its slot."""
+
+    def __init__(self, running):
+        super().__init__(f"{running.title} is already running")
+        self.running = running
+
+
+class Job:
+    """One tracked operation: state, counters, outcomes, log and subscribers."""
+
+    def __init__(
+        self, kind, title, *, record_changing=False, scope=None, groups=(), clock=None
+    ):
+        self._clock = clock or time.time
+        self.id = uuid.uuid4().hex
+        self.kind = kind
+        self.title = title
+        self.record_changing = record_changing
+        self.scope = dict(scope or {})
+        self.state = "running"
+        self.started_at = self._clock()
+        self._started_seq = next(_sequence)
+        self._finished_seq = None
+        self.finished_at = None
+        self.progress = 0
+        self.status_line = ""
+        self.processed = 0
+        self.total = 0
+        self.counters = dict.fromkeys(groups, 0)
+        self.outcomes = {group: [] for group in groups}
+        self.log = []
+        self.cancelled = False
+        self.last_event = None
+        self.task = None
+        self._subscribers = set()
+
+    @property
+    def running(self):
+        return self.state == "running"
+
+    @property
+    def finished(self):
+        return not self.running
+
+    @property
+    def subscriber_count(self):
+        return len(self._subscribers)
+
+    # ── progress ──────────────────────────────────────────────────────
+
+    def update(self, *, progress=None, status_line=None, processed=None, total=None):
+        """Set the summary's progress fields; ``None`` leaves one unchanged."""
+        if progress is not None:
+            self.progress = max(0, min(100, int(progress)))
+        if status_line is not None:
+            self.status_line = status_line
+        if processed is not None:
+            self.processed = processed
+        if total is not None:
+            self.total = total
+
+    def publish(self, payload):
+        """Record ``payload`` as the latest event and hand it to every subscriber."""
+        if isinstance(payload.get("progress"), (int, float)):
+            self.update(progress=payload["progress"])
+        self.last_event = payload
+        for queue in list(self._subscribers):
+            queue.put_nowait(payload)
+
+    def log_line(self, text):
+        """Append a timestamped log line, up to MAX_LOG_LINES and one cap line."""
+        if len(self.log) > MAX_LOG_LINES:
+            return
+        if len(self.log) == MAX_LOG_LINES:
+            self.log.append(LOG_CAP_LINE)
+            return
+        stamp = time.strftime("%H:%M:%S", time.localtime(self._clock()))
+        self.log.append(f"{stamp} {text}")
+
+    def record(self, group, row, log_line):
+        """Count one file outcome in ``group``, list its row and log it.
+
+        ``row`` is ``{path, root, root_index, detail}``: the path relative to
+        its output root, the root's public label and its listing index (the
+        identity Images opens it by; None when unknown). An absolute path is
+        cut to its file name, so a row never reveals the server's layout.
+        """
+        if group not in self.counters:
+            raise ValueError(f"Unknown outcome group {group!r} for {self.kind}")
+        self.counters[group] += 1
+        raw = str(row.get("path") or "")
+        path = _relative_path(raw)
+        if raw and raw != path:
+            log_line = log_line.replace(raw, path)
+        rows = self.outcomes[group]
+        index = row.get("root_index")
+        if isinstance(index, bool) or not isinstance(index, int) or index < 0:
+            index = None
+        if len(rows) < MAX_OUTCOME_ROWS:
+            rows.append(
+                {
+                    "path": path,
+                    "root": str(row.get("root") or ""),
+                    "root_index": index,
+                    "detail": str(row.get("detail") or ""),
+                }
+            )
+        self.log_line(log_line)
+
+    def finish(self, state="finished"):
+        """End the job in ``state`` and release every subscriber.
+
+        Each subscriber still gets the events queued before the release. A
+        second finish is a no-op, so the first final state stands.
+        """
+        if state not in FINAL_STATES:
+            raise ValueError(f"{state!r} is not a final job state")
+        if self.finished:
+            return
+        self.state = state
+        self.finished_at = self._clock()
+        self._finished_seq = next(_sequence)
+        for queue in list(self._subscribers):
+            queue.put_nowait(None)
+
+    async def events(self):
+        """Yield the latest event, then each later one, until the job finishes.
+
+        Consume it under ``contextlib.aclosing`` so a consumer that stops early
+        (a closed socket) drops its queue at once instead of at garbage collection.
+        """
+        queue = asyncio.Queue()
+        self._subscribers.add(queue)
+        try:
+            if self.last_event is not None:
+                yield self.last_event
+            if self.finished:
+                return
+            while True:
+                payload = await queue.get()
+                if payload is None:
+                    return
+                yield payload
+        finally:
+            self._subscribers.discard(queue)
+
+    # ── views ─────────────────────────────────────────────────────────
+
+    def summary(self):
+        """The job as the Activity list and pill show it."""
+        return {
+            "id": self.id,
+            "kind": self.kind,
+            "title": self.title,
+            "state": self.state,
+            "started_at": self.started_at,
+            "finished_at": self.finished_at,
+            "progress": self.progress,
+            "status_line": self.status_line,
+            "processed": self.processed,
+            "total": self.total,
+            "counters": dict(self.counters),
+            "scope": dict(self.scope),
+            # What detail() lists, so a view re-reads it only when it changed.
+            "listed": {group: len(rows) for group, rows in self.outcomes.items()},
+            "log_length": len(self.log),
+        }
+
+    def detail(self):
+        """The summary plus the listed outcome rows and the log."""
+        return {
+            **self.summary(),
+            "outcomes": {
+                group: [dict(row) for row in rows]
+                for group, rows in self.outcomes.items()
+            },
+            "log": list(self.log),
+        }
+
+    def report(self):
+        """The downloadable report: the summary, every outcome group and the log.
+
+        Each group carries its exact count, its listed rows (at most
+        MAX_OUTCOME_ROWS) and whether the list is cut short. Rows and log lines
+        already hold root-relative paths only.
+        """
+        summary = self.summary()
+        summary.pop("listed", None)
+        summary.pop("log_length", None)
+        return {
+            "report_version": 1,
+            "generated_at": self._clock(),
+            "job": summary,
+            "outcomes": {
+                group: {
+                    "count": self.counters.get(group, len(rows)),
+                    "rows": [dict(row) for row in rows],
+                    "truncated": self.counters.get(group, len(rows)) > len(rows),
+                }
+                for group, rows in self.outcomes.items()
+            },
+            "log": list(self.log),
+        }
+
+    def report_filename(self):
+        """The download name: prompt-manager-KIND-YYYYMMDD-HHMM.json (local time)."""
+        stamp = time.strftime("%Y%m%d-%H%M", time.localtime(self._clock()))
+        return f"prompt-manager-{self.kind}-{stamp}.json"
+
+
+class JobRegistry:
+    """Every job of this server session, running and recently finished."""
+
+    def __init__(self, logger_=None):
+        self._logger = logger_ or logger
+        self._jobs = {}
+
+    def start(self, kind, title, *, record_changing, scope, runner, groups=()) -> Job:
+        """Create a job and run ``runner(job)`` as a task.
+
+        Raises JobBusy, naming the job in the way, when a job of ``kind`` is
+        running or when ``record_changing`` and another record-changing job
+        runs. Must be called from the event loop.
+        """
+        same_kind = self.active(kind)
+        if same_kind is not None:
+            raise JobBusy(same_kind)
+        if record_changing:
+            for job in self._jobs.values():
+                if job.running and job.record_changing:
+                    raise JobBusy(job)
+        self._prune()
+        job = Job(
+            kind, title, record_changing=record_changing, scope=scope, groups=groups
+        )
+        self._jobs[job.id] = job
+        job.task = asyncio.ensure_future(self._run(job, runner))
+        return job
+
+    async def _run(self, job, runner):
+        try:
+            await runner(job)
+        except asyncio.CancelledError:
+            job.finish("cancelled")
+            raise
+        except Exception:
+            self._logger.exception(f"Job {job.kind} failed")
+            job.finish("failed")
+        finally:
+            if job.running:
+                job.finish("cancelled" if job.cancelled else "finished")
+
+    def _prune(self):
+        """Drop the oldest finished jobs so a new one keeps the cap."""
+        finished = [job for job in self._jobs.values() if job.finished]
+        finished.sort(key=lambda job: job._finished_seq)
+        for job in finished[: max(0, len(finished) - MAX_FINISHED_JOBS + 1)]:
+            del self._jobs[job.id]
+
+    def get(self, job_id):
+        return self._jobs.get(job_id)
+
+    def active(self, kind):
+        """The running job of ``kind``, or None."""
+        for job in self._jobs.values():
+            if job.kind == kind and job.running:
+                return job
+        return None
+
+    def list(self):
+        """Running jobs first, then the last finished ones, newest first."""
+        jobs = list(self._jobs.values())
+        running = [job for job in jobs if job.running]
+        finished = [job for job in jobs if job.finished]
+        running.sort(key=lambda job: job._started_seq, reverse=True)
+        finished.sort(key=lambda job: job._finished_seq, reverse=True)
+        return running + finished[:MAX_FINISHED_JOBS]
+
+    def cancel(self, job_id) -> bool:
+        """Ask a running job to stop at its next safe boundary.
+
+        Returns whether a cancellation was requested: False for a finished or
+        unknown job, so a cancel after the end is a no-op.
+        """
+        job = self._jobs.get(job_id)
+        if job is None or job.finished:
+            return False
+        job.cancelled = True
+        return True

py/api/scan_job.py

@@ -1,62 +0,0 @@
-"""Progress fan-out for the background output scan.
-
-The scan runs as an asyncio task that outlives the HTTP request that started
-it, so an accidental tab close does not abandon a half-finished scan. Every
-SSE subscriber (the request that started the scan, a reconnecting page, a
-second tab) receives the latest event as a snapshot and then every event
-published after it, until the job finishes.
-"""
-
-import asyncio
-
-
-class ScanJob:
-    """One scan run: its latest event, completion flag and live subscribers."""
-
-    def __init__(self):
-        self.last_event = None
-        self.finished = False
-        self.cancelled = False
-        self.task = None
-        self._subscribers = set()
-
-    @property
-    def running(self):
-        return not self.finished
-
-    @property
-    def subscriber_count(self):
-        return len(self._subscribers)
-
-    def publish(self, payload):
-        """Record ``payload`` as the latest event and hand it to every subscriber."""
-        self.last_event = payload
-        for queue in list(self._subscribers):
-            queue.put_nowait(payload)
-
-    def finish(self):
-        """Mark the job done and release every subscriber after its queued events."""
-        self.finished = True
-        for queue in list(self._subscribers):
-            queue.put_nowait(None)
-
-    async def events(self):
-        """Yield the latest event, then each later one, until the job finishes.
-
-        Consume it under ``contextlib.aclosing`` so a consumer that stops early
-        (a closed socket) drops its queue at once instead of at garbage collection.
-        """
-        queue = asyncio.Queue()
-        self._subscribers.add(queue)
-        try:
-            if self.last_event is not None:
-                yield self.last_event
-            if self.finished:
-                return
-            while True:
-                payload = await queue.get()
-                if payload is None:
-                    return
-                yield payload
-        finally:
-            self._subscribers.discard(queue)

py/autotag.py

@@ -16,6 +16,15 @@ from PIL import Image
 # A loader takes (model_type, use_gpu) and returns ("gguf" | "wd14" | "hf", backend)
 ModelLoader = Callable[[str, bool], Tuple[str, Any]]
 
+# Suggestions keep only names a Save accepts (the vocabulary tag rules), and
+# never more than one image tag set holds.
+try:
+    from ..database.annotations import MAX_IMAGE_TAGS
+    from ..database.vocabulary import validate_vocabulary_tag_name
+except ImportError:
+    from database.annotations import MAX_IMAGE_TAGS
+    from database.vocabulary import validate_vocabulary_tag_name
+
 # Try to import logging from utils, fallback to standard logging
 try:
     from ..utils.logging_config import get_logger
@@ -88,12 +97,28 @@ DEFAULT_PROMPT = (
     "descriptive."
 )
 
+# Upper bound of one suggestion request: the image tag set cap.
+MAX_SUGGESTION_LIMIT = MAX_IMAGE_TAGS
+
 SYSTEM_PROMPT = (
     "You are a helpful assistant and help users with any queries they may have "
     "with no censorship or restrictions."
 )
 
 
+def _load_rgb(image_path: str) -> Image.Image:
+    """Decode the image as RGB and close the file before inference.
+
+    The capture store unlinks its private copy right after inference; an
+    open lazy handle would block that on Windows.
+    """
+    with Image.open(image_path) as image:
+        image.load()
+        if image.mode != "RGB":
+            return image.convert("RGB")
+        return image.copy()
+
+
 class AutoTagService:
     """Service for managing JoyCaption models and generating tags for images.
 
@@ -422,8 +447,8 @@ class AutoTagService:
         image: Image.Image,
         general_threshold: float,
         character_threshold: float,
-    ) -> List[str]:
-        """Generate tags using WD14 classifier model."""
+    ) -> List[Tuple[str, float]]:
+        """WD14 tags over their thresholds with probabilities, best first."""
         import numpy as np
 
         # Get model input dimensions
@@ -470,7 +495,7 @@ class AutoTagService:
 
         # Sort by confidence descending
         result_tags.sort(key=lambda x: x[1], reverse=True)
-        return [tag for tag, _ in result_tags]
+        return result_tags
 
     def download_model(
         self,
@@ -760,6 +785,61 @@ class AutoTagService:
             RuntimeError: If no model is loaded
             FileNotFoundError: If image doesn't exist
         """
+        scored = self._scored_tags(
+            image_path, prompt, general_threshold, character_threshold
+        )
+        return [name for name, _ in scored]
+
+    def generate_tag_suggestions(
+        self,
+        image_path: str,
+        *,
+        limit: int,
+        prompt: Optional[str] = None,
+        general_threshold: Optional[float] = None,
+        character_threshold: Optional[float] = None,
+    ) -> List[Tuple[str, Optional[float]]]:
+        """The top ``limit`` suggestions as ``(name, confidence)`` pairs.
+
+        WD14 pairs carry the real probability, best first; language models
+        (GGUF, HF) have no score, so their tags keep the output order with
+        ``None``. Names are distinct case-insensitively (first one wins).
+        A name Save would reject (over 50 characters, a control character
+        such as a newline, a comma) is skipped before the dedupe and the
+        ``limit`` count. ``prompt`` is used for this call only;
+        ``custom_prompt`` is never changed.
+        """
+        if type(limit) is not int or not 1 <= limit <= MAX_SUGGESTION_LIMIT:
+            raise ValueError(
+                f"limit must be an integer from 1 to {MAX_SUGGESTION_LIMIT}"
+            )
+        scored = self._scored_tags(
+            image_path, prompt, general_threshold, character_threshold
+        )
+        suggestions: List[Tuple[str, Optional[float]]] = []
+        seen = set()
+        for raw, score in scored:
+            try:
+                name = validate_vocabulary_tag_name(raw)
+            except ValueError:
+                continue
+            key = name.casefold()
+            if key in seen:
+                continue
+            seen.add(key)
+            suggestions.append((name, score))
+            if len(suggestions) == limit:
+                break
+        return suggestions
+
+    def _scored_tags(
+        self,
+        image_path: str,
+        prompt: Optional[str],
+        general_threshold: Optional[float],
+        character_threshold: Optional[float],
+    ) -> List[Tuple[str, Optional[float]]]:
+        """Run the loaded model: WD14 ``(name, probability)``, LLM ``(name, None)``."""
         if self._tagger is None:
             raise RuntimeError("No model loaded. Call load_model() first.")
 
@@ -767,18 +847,14 @@ class AutoTagService:
             raise FileNotFoundError(errno.ENOENT, "Image not found", str(image_path))
 
         use_prompt = prompt or self._custom_prompt
-
-        # Load image
-        image = Image.open(image_path)
-        if image.mode != "RGB":
-            image = image.convert("RGB")
+        image = _load_rgb(image_path)
 
         # Generate based on model type
         model_type, tagger_obj = self._tagger
 
         if model_type == "gguf":
             raw_tags = self._generate_gguf(tagger_obj, image, use_prompt)
-            return self._parse_tags(raw_tags)
+            return [(tag, None) for tag in self._parse_tags(raw_tags)]
         elif model_type == "wd14":
             session, tags_list = tagger_obj
             gen_thresh = (
@@ -799,7 +875,7 @@ class AutoTagService:
             raw_tags = self._generate_hf(
                 model, processor, device, compute_dtype, image, use_prompt
             )
-            return self._parse_tags(raw_tags)
+            return [(tag, None) for tag in self._parse_tags(raw_tags)]
 
     def _generate_gguf(self, model, image: Image.Image, prompt: str) -> str:
         """Generate tags using GGUF model."""

py/config.py

@@ -465,6 +465,59 @@ class IntegrationConfig:
             cls.CIVITAI_API_KEY = lora["civitai_api_key"]
 
 
+# Number of tag suggestions the Tag dialogs request by default (D68). The cap
+# is the image tag set limit: more suggestions could never all be kept.
+DEFAULT_SUGGESTION_LIMIT = 10
+MAX_SUGGESTION_LIMIT = 100  # pinned to MAX_IMAGE_TAGS by tests/test_config.py
+
+
+class AutotagConfig:
+    """Persisted tagging defaults under ``autotag.defaults`` in config.json.
+
+    ``suggestion_limit`` is how many suggestions Generate returns (the top N
+    by score), an integer in ``1..MAX_SUGGESTION_LIMIT``. A hand-edited value
+    outside that range, or of another type, falls back to the default with a
+    warning rather than failing the load.
+    """
+
+    SUGGESTION_LIMIT = DEFAULT_SUGGESTION_LIMIT
+
+    @classmethod
+    def suggestion_limit(cls) -> int:
+        return cls.SUGGESTION_LIMIT
+
+    @staticmethod
+    def valid_suggestion_limit(value: Any) -> bool:
+        return (
+            type(value) is int and 1 <= value <= MAX_SUGGESTION_LIMIT
+        )  # bool, float and str are rejected
+
+    @classmethod
+    def get_config(cls) -> Dict[str, Any]:
+        return {"defaults": {"suggestion_limit": cls.SUGGESTION_LIMIT}}
+
+    @classmethod
+    def update_config(cls, new_config: Any) -> None:
+        if not isinstance(new_config, dict):
+            config_logger.warning("Ignoring autotag settings that are not an object")
+            return
+        defaults = new_config.get("defaults", {})
+        if not isinstance(defaults, dict):
+            config_logger.warning("Ignoring autotag.defaults that is not an object")
+            return
+        if "suggestion_limit" not in defaults:
+            return
+        value = defaults["suggestion_limit"]
+        if cls.valid_suggestion_limit(value):
+            cls.SUGGESTION_LIMIT = value
+            return
+        config_logger.warning(
+            "autotag.defaults.suggestion_limit must be an integer from 1 to "
+            f"{MAX_SUGGESTION_LIMIT}; using {DEFAULT_SUGGESTION_LIMIT}"
+        )
+        cls.SUGGESTION_LIMIT = DEFAULT_SUGGESTION_LIMIT
+
+
 class PromptManagerConfig:
     """Main configuration class for PromptManager core functionality.
 
@@ -566,6 +619,7 @@ class PromptManagerConfig:
             },
             "gallery": GalleryConfig.get_config(),
             "integrations": IntegrationConfig.get_config(),
+            "autotag": AutotagConfig.get_config(),
         }
 
     @classmethod
@@ -706,6 +760,9 @@ class PromptManagerConfig:
         if "integrations" in new_config:
             IntegrationConfig.update_config(new_config["integrations"])
 
+        if "autotag" in new_config:
+            AutotagConfig.update_config(new_config["autotag"])
+
 
 # Load configuration on import
 try:

py/model_gate.py

@@ -0,0 +1,177 @@
+"""One process-wide, non-blocking gate around the tagging models (#249 B2).
+
+Loading, swapping, running, downloading and unloading a tagging model all
+happen under this gate, whether the caller is a legacy Auto-tag route, the
+Tag dialog's Generate or (later) a bulk job. A caller that cannot take the
+gate is refused at once (``409 model-busy``), never queued.
+
+Work that runs in a worker thread is admitted with :meth:`ModelGate.run`. A
+release requested while such work still runs (a client disconnect cancels
+the waiting coroutine, not the thread) takes effect only when the last
+admitted call really exits, so nobody can swap the model under a running
+inference.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import uuid
+from typing import Any, Callable, Optional
+
+
+class GateNotHeld(RuntimeError):
+    """Raised when work is admitted for an owner that does not hold the gate."""
+
+
+class ModelGate:
+    """A single-owner gate whose release waits for admitted worker calls."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._holder: Optional[str] = None
+        self._inflight = 0
+        self._releasing = False
+
+    def try_acquire(self, owner: str) -> bool:
+        """Take the gate for *owner*; False at once when anyone holds it."""
+        with self._lock:
+            if self._holder is not None:
+                return False
+            self._holder = owner
+            self._inflight = 0
+            self._releasing = False
+            return True
+
+    def release(self, owner: str) -> None:
+        """Let go; deferred until admitted work of *owner* has exited."""
+        with self._lock:
+            if self._holder != owner:
+                return
+            if self._inflight:
+                self._releasing = True
+            else:
+                self._clear_locked()
+
+    def holder(self) -> Optional[str]:
+        with self._lock:
+            return self._holder
+
+    def begin(self, owner: str) -> None:
+        """Admit one worker call; the holder must still hold the gate."""
+        with self._lock:
+            if self._holder != owner or self._releasing:
+                raise GateNotHeld(f"{owner} does not hold the model gate")
+            self._inflight += 1
+
+    def end(self, owner: str) -> None:
+        """One admitted call exited; completes a deferred release."""
+        with self._lock:
+            self._end_locked(owner)
+
+    async def run(
+        self,
+        owner: str,
+        func: Callable[..., Any],
+        *args,
+        on_skipped: Optional[Callable[[], None]] = None,
+        **kwargs,
+    ):
+        """Run ``func`` in the default executor while *owner* holds the gate.
+
+        The executor future is shielded: cancelling the caller never cancels
+        a call that has not started yet (which would leave it admitted
+        forever) and never ends the admission of a call that is running.
+        ``on_skipped`` runs once when ``func`` never starts (the gate is not
+        held, the executor refuses the call, or a loop shutdown drops it), so
+        a caller can free what ``func`` would have freed.
+        """
+        try:
+            self.begin(owner)
+        except GateNotHeld:
+            if on_skipped is not None:
+                on_skipped()
+            raise
+        state = {"started": False, "finished": False}
+
+        def finish() -> None:
+            with self._lock:
+                if not state["finished"]:
+                    state["finished"] = True
+                    self._end_locked(owner)
+
+        def work():
+            with self._lock:
+                if state["finished"]:
+                    # Already declared skipped (the future was cancelled as
+                    # the thread picked the call up): never run it twice over.
+                    return None
+                state["started"] = True
+            try:
+                return func(*args, **kwargs)
+            finally:
+                finish()
+
+        def never_ran(future) -> None:
+            # Only a loop shutdown cancels the shielded future; a call that
+            # never started must still give its admission back.
+            if future.cancelled():
+                with self._lock:
+                    skipped = not state["started"] and not state["finished"]
+                    if skipped:
+                        state["finished"] = True
+                        self._end_locked(owner)
+                if skipped and on_skipped is not None:
+                    on_skipped()
+
+        try:
+            future = asyncio.get_running_loop().run_in_executor(None, work)
+        except BaseException:
+            finish()
+            if on_skipped is not None:
+                on_skipped()
+            raise
+        future.add_done_callback(never_ran)
+        return await asyncio.shield(future)
+
+    def _end_locked(self, owner: str) -> None:
+        if self._holder != owner or self._inflight == 0:
+            return
+        self._inflight -= 1
+        if self._releasing and self._inflight == 0:
+            self._clear_locked()
+
+    def _clear_locked(self) -> None:
+        self._holder = None
+        self._inflight = 0
+        self._releasing = False
+
+
+_GATE = ModelGate()
+
+
+def new_owner(kind: str) -> str:
+    """A unique owner name such as ``legacy-single:<uuid>``."""
+    return f"{kind}:{uuid.uuid4()}"
+
+
+def try_acquire(owner: str) -> bool:
+    return _GATE.try_acquire(owner)
+
+
+def release(owner: str) -> None:
+    _GATE.release(owner)
+
+
+def holder() -> Optional[str]:
+    return _GATE.holder()
+
+
+async def run(
+    owner: str,
+    func: Callable[..., Any],
+    *args,
+    on_skipped: Optional[Callable[[], None]] = None,
+    **kwargs,
+):
+    return await _GATE.run(owner, func, *args, on_skipped=on_skipped, **kwargs)

tests/browser/activity-concept.spec.mjs

@@ -0,0 +1,296 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { THEMES, seedConcept, openConcept, openProduction, diffInventory, mutate } from './concept-inventory.mjs';
+
+// Activity-1 Task 3. The review dialog is compared with the concept's own `scan-review` ("Review metadata scan",
+// app.js 1428–1432) and its backup box with the concept's System `.notice`; the differences are D55. The job view
+// has no concept counterpart: it is compared with the approved mockup `activity-scan.html` (a local, ignored file),
+// whose structure and CSS values are restated below (D56). Each comparison is shown to notice a mutation.
+const workspace = '/prompt_manager/workspace';
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    page.conceptErrors = [];
+    page.on('pageerror', error => page.conceptErrors.push(error.message));
+});
+
+test.afterEach(async ({ page, request, browserName }) => {
+    await saveCoverage(page, browserName);
+    expect(page.conceptErrors).toEqual([]);
+    await request.post('/__test__/jobs/restart');
+});
+
+/** The open review dialog: its body's element sequence, the meta grid, the sentence, the notice and the actions. */
+function measureReview() {
+    const dialog = document.querySelector('dialog#modal[open]');
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const grid = dialog.querySelector('#modal-body > .meta-grid');
+    const sentence = dialog.querySelector('#modal-body > p.small');
+    const actions = dialog.querySelector('#modal-body > .dialog-actions');
+    return {
+        title: dialog.querySelector('#modal-title').textContent,
+        body: [...dialog.querySelector('#modal-body').children].map(name),
+        grid: {
+            tag: grid.localName,
+            ...css(grid, 'display', 'gridTemplateColumns', 'columnGap', 'rowGap', 'marginTop', 'marginBottom', 'fontSize'),
+            entries: [...grid.children].map(entry => ({
+                tag: entry.localName, dt: entry.querySelector('dt').textContent, dd: entry.querySelector('dd').textContent,
+                dtStyle: css(entry.querySelector('dt'), 'color', 'fontSize'),
+                ddStyle: css(entry.querySelector('dd'), 'marginTop', 'marginLeft', 'fontSize', 'color'),
+            })),
+        },
+        sentence: { text: sentence.textContent, ...css(sentence, 'fontSize', 'color', 'lineHeight', 'marginTop') },
+        actions: {
+            ...css(actions, 'display', 'justifyContent', 'columnGap', 'marginTop'),
+            buttons: [...actions.children].map(button => ({ text: button.textContent, className: button.className,
+                ...css(button, 'backgroundColor', 'color', 'fontSize', 'paddingTop', 'paddingLeft', 'borderTopLeftRadius') })),
+        },
+    };
+}
+
+/** A `.notice` box: its frame and its text and actions columns, without the copy. */
+function measureNotice(selector) {
+    const notice = document.querySelector(selector);
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    return {
+        frame: css(notice, 'display', 'alignItems', 'justifyContent', 'columnGap', 'borderTopWidth', 'borderTopStyle',
+            'borderTopColor', 'backgroundColor', 'borderTopLeftRadius', 'paddingTop', 'paddingLeft'),
+        columns: [...notice.children].map(node => node.localName + (node.className ? `.${node.className}` : '')),
+        text: css(notice.querySelector(':scope > div > p'), 'fontSize', 'color', 'marginTop'),
+        actions: css(notice.querySelector(':scope > .row-actions'), 'display', 'flexShrink'),
+    };
+}
+
+/** A concept `.setting-row` switch: its frame, its label and hint, and its checkbox (not its place-dependent margin). */
+function measureToggle(selector) {
+    const row = document.querySelector(selector);
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    return {
+        children: [...row.children].map(node => [node.localName, ...node.classList].join('.')),
+        frame: css(row, 'display', 'alignItems', 'justifyContent', 'columnGap', 'paddingTop', 'paddingBottom',
+            'borderTopWidth', 'borderTopStyle', 'borderTopColor'),
+        label: css(row.querySelector('label'), 'fontSize', 'fontWeight', 'color'),
+        hint: css(row.querySelector('p'), 'fontSize', 'color', 'marginTop'),
+        box: css(row.querySelector('input[type="checkbox"]'), 'accentColor', 'width', 'height', 'appearance',
+            'backgroundColor', 'borderTopLeftRadius'),
+        role: row.querySelector('input').getAttribute('role'),
+        labelled: row.querySelector('label').htmlFor === row.querySelector('input').id,
+    };
+}
+
+/** D55 and D58: the concept's dialog with the production differences applied. */
+function mapReviewConcept(reference) {
+    return {
+        ...reference,
+        // No sample-plan note (prototype copy); the D58 "All files" toggle follows the grid; the backup box sits
+        // before the actions.
+        body: [...reference.body.filter(item => item !== 'p.demo-note').slice(0, -1), 'div.notice', reference.body.at(-1)]
+            .flatMap(item => item === 'div.meta-grid' ? ['dl.meta-grid', 'div.setting-row'] : [item]),
+        // A `dl`, as in the concept's maintenance plan; real sources. The scope keeps the concept's
+        // "New and unresolved files" until "All files" is checked.
+        grid: { ...reference.grid, tag: 'dl', entries: reference.grid.entries.map(entry => ({ ...entry,
+            dd: { Sources: '2 output folders', Scope: 'New and unresolved files' }[entry.dt] })) },
+        actions: { ...reference.actions, buttons: reference.actions.buttons.map(button => button.text === 'Simulate scan'
+            ? { ...button, text: 'Start scan' } : button) },
+    };
+}
+
+async function conceptReview(page, theme) {
+    await openConcept(page, 'images', theme);
+    await page.locator('#main .heading-actions').getByRole('button', { name: 'Import', exact: true }).click();
+    await page.locator('dialog#modal[open] .operation').filter({ hasText: 'Scan an output folder' })
+        .getByRole('button', { name: 'Review scan', exact: true }).click();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Review metadata scan');
+    await page.mouse.move(0, 0);
+    const review = await page.evaluate(measureReview);
+    await page.keyboard.press('Escape');
+    // The concept's System → Sources notice ("Bring older images into your prompt history").
+    await page.goto(`/__test__/canonical/workspace#system`);
+    await page.getByRole('combobox', { name: 'Theme', exact: true }).selectOption(theme);
+    await page.locator('#main').getByRole('button', { name: 'Manage sources', exact: true }).click();
+    await expect(page.locator('#main .notice')).toBeVisible();
+    return { review, notice: await page.evaluate(measureNotice, '#main .notice'),
+        toggle: await page.evaluate(measureToggle, '#main .setting-row:has(input[type="checkbox"])') };
+}
+
+async function productionReview(page, theme) {
+    await openProduction(page, 'images', theme);
+    await page.locator('#workspace-main .heading-actions').getByRole('button', { name: 'Import', exact: true }).click();
+    await page.locator('dialog#modal[open] .operation').filter({ hasText: 'Scan for metadata' })
+        .getByRole('button', { name: 'Review scan', exact: true }).click();
+    await expect(page.locator('dialog#modal[open] #modal-title')).toHaveText('Review metadata scan');
+    // The swapped dialog can open under the pointer that pressed Review scan; measure it at rest.
+    await page.mouse.move(0, 0);
+    const review = await page.evaluate(measureReview);
+    const notice = await page.evaluate(measureNotice, 'dialog#modal[open] .notice');
+    // The concept's switch is on; compare ours on too, then turn it off again (the default).
+    const allFiles = page.getByRole('switch', { name: 'All files', exact: true });
+    await allFiles.check();
+    await page.mouse.move(0, 0);
+    const toggle = await page.evaluate(measureToggle, 'dialog#modal[open] .setting-row');
+    await allFiles.uncheck();
+    await page.mouse.move(0, 0);
+    return { review, notice, toggle };
+}
+
+for (const theme of THEMES) test(`review dialog matches the concept scan-review ${theme}`, async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await seedConcept(request);
+    const concept = await conceptReview(page, theme);
+    expect(concept.review.body).toEqual(['p.demo-note', 'div.meta-grid', 'p.small', 'div.dialog-actions']);
+    const production = await productionReview(page, theme);
+    expect(diffInventory(mapReviewConcept(concept.review), production.review)).toEqual([]);
+    expect(diffInventory(concept.notice, production.notice)).toEqual([]);
+    expect(diffInventory(concept.toggle, production.toggle)).toEqual([]);
+    await expect(page.locator('dialog#modal[open] .setting-row > div > label')).toHaveText('All files');
+    await expect(page.locator('dialog#modal[open] .setting-row input')).not.toBeChecked();
+    await expect(page.getByRole('switch', { name: 'All files', exact: true })).toBeVisible();
+    await expect(page.locator('dialog#modal[open] .notice h3')).toHaveText('Back up the database first (recommended)');
+    await expect(page.locator('dialog#modal[open] .notice .row-actions button')).toHaveText(['Back up now']);
+
+    // Mutation check: one CSS change and one removed element are both noticed, then undone to an exact match again.
+    const undoCss = await mutate(page, { css: '#modal .meta-grid { gap: 3px; } #modal .notice { padding: 2px; } #modal .setting-row { gap: 3px; }' });
+    const cssMutated = await page.evaluate(measureReview);
+    const noticeMutated = await page.evaluate(measureNotice, 'dialog#modal[open] .notice');
+    await page.getByRole('switch', { name: 'All files', exact: true }).check();
+    await page.mouse.move(0, 0);
+    const toggleMutated = await page.evaluate(measureToggle, 'dialog#modal[open] .setting-row');
+    await page.getByRole('switch', { name: 'All files', exact: true }).uncheck();
+    await page.mouse.move(0, 0);
+    expect(diffInventory(concept.toggle, toggleMutated).map(item => item.path)).toEqual(['frame.columnGap']);
+    expect(diffInventory(mapReviewConcept(concept.review), cssMutated).map(item => item.path)).toEqual(expect.arrayContaining(['grid.columnGap', 'grid.rowGap']));
+    expect(diffInventory(concept.notice, noticeMutated).map(item => item.path)).toEqual(['frame.paddingTop', 'frame.paddingLeft']);
+    await undoCss();
+    const undoDom = await mutate(page, { remove: ['#modal-body > p.small'] });
+    const domMutated = await page.evaluate(() => [...document.querySelectorAll('#modal-body > *')].map(node => node.localName));
+    expect(domMutated).toEqual(['dl', 'div', 'div', 'div']);
+    await undoDom();
+    expect(diffInventory(mapReviewConcept(concept.review), await page.evaluate(measureReview))).toEqual([]);
+});
+
+// The approved mockup's job view, restated: structure first, then the values of its CSS rules.
+const MOCKUP_TREE = ['div.heading', 'section.surface', 'section.surface', 'details.term'];
+const MOCKUP_PROGRESS = ['div.panel-heading(h2,span.small)', 'progress', 'dl.stat-row(div.added.stat,div.stat,div.stat.warn,div.stat,div.bad.stat)'];
+const MOCKUP_RESULTS = ['div.panel-heading(h2,label.search-field)', 'div.outcomes(div.outcome-list,div.outcome-files)'];
+const MOCKUP_STYLES = {
+    statRow: { display: 'grid', columnGap: '10px', columns: 5, marginTop: '16px', marginBottom: '16px' },
+    stat: { borderTopWidth: '1px', borderTopLeftRadius: '7px', paddingTop: '12px', paddingLeft: '14px' },
+    dt: { fontSize: '11px' },
+    dd: { fontSize: '20px', fontWeight: '600', marginTop: '6px', marginLeft: '0px' },
+    outcomes: { display: 'grid', columnGap: '16px', first: '220px', marginTop: '6px' },
+    outcomeButton: { display: 'flex', justifyContent: 'space-between', marginBottom: '6px', textAlign: 'left' },
+    fileRow: { display: 'grid', columnGap: '12px', paddingTop: '9px', paddingLeft: '4px', borderBottomWidth: '1px', fontSize: '12px' },
+    path: { monospace: true, overflowWrap: 'anywhere' },
+    search: { maxWidth: '320px' },
+    term: { marginTop: '16px', borderTopWidth: '1px', borderTopLeftRadius: '7px', overflow: 'hidden' },
+    summary: { paddingTop: '11px', paddingLeft: '14px', fontSize: '12px', cursor: 'pointer' },
+    pre: { marginTop: '0px', paddingTop: '12px', paddingLeft: '14px', maxHeight: '180px', fontSize: '11px', lineHeight: '18.7px', overflow: 'auto' },
+};
+
+function measureJobView() {
+    const main = document.querySelector('#workspace-main');
+    const css = (node, ...keys) => Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]]));
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    // The rows and sections the mockup nests are listed with their children.
+    const shape = node => node.matches('.panel-heading, .outcomes, dl.stat-row')
+        ? `${name(node)}(${[...node.children].map(name).join(',')})` : name(node);
+    const [progress, results] = main.querySelectorAll(':scope > section.surface');
+    const statRow = progress.querySelector('dl.stat-row');
+    const stat = statRow.querySelector('.stat');
+    const outcomes = results.querySelector('.outcomes');
+    const button = outcomes.querySelector('.outcome-list > button');
+    const row = outcomes.querySelector('.file-row');
+    const term = main.querySelector(':scope > details.term');
+    const pre = term.querySelector('pre');
+    const columns = getComputedStyle(statRow).gridTemplateColumns.split(' ');
+    return {
+        tree: [...main.children].map(name),
+        progress: [...progress.children].map(shape),
+        results: [...results.children].map(shape),
+        h2: [...main.querySelectorAll(':scope > section.surface > .panel-heading > h2')].map(node => node.textContent),
+        summary: term.querySelector('summary').textContent,
+        styles: {
+            statRow: { ...css(statRow, 'display', 'columnGap', 'marginTop', 'marginBottom'), columns: columns.length },
+            stat: css(stat, 'borderTopWidth', 'borderTopLeftRadius', 'paddingTop', 'paddingLeft'),
+            dt: css(stat.querySelector('dt'), 'fontSize'),
+            dd: css(stat.querySelector('dd'), 'fontSize', 'fontWeight', 'marginTop', 'marginLeft'),
+            outcomes: { ...css(outcomes, 'display', 'columnGap', 'marginTop'), first: getComputedStyle(outcomes).gridTemplateColumns.split(' ')[0] },
+            outcomeButton: css(button, 'display', 'justifyContent', 'marginBottom', 'textAlign'),
+            fileRow: css(row, 'display', 'columnGap', 'paddingTop', 'paddingLeft', 'borderBottomWidth', 'fontSize'),
+            path: { monospace: /monospace/.test(getComputedStyle(row.querySelector('.path')).fontFamily),
+                overflowWrap: getComputedStyle(row.querySelector('.path')).overflowWrap },
+            search: css(results.querySelector('.search-field'), 'maxWidth'),
+            term: css(term, 'marginTop', 'borderTopWidth', 'borderTopLeftRadius', 'overflow'),
+            summary: css(term.querySelector('summary'), 'paddingTop', 'paddingLeft', 'fontSize', 'cursor'),
+            // WebKit reports the 1.7 line height of 11px as 18.700001px; compare it to the hundredth of a pixel.
+            pre: { ...css(pre, 'marginTop', 'paddingTop', 'paddingLeft', 'maxHeight', 'fontSize', 'overflow'),
+                lineHeight: `${Math.round(parseFloat(getComputedStyle(pre).lineHeight) * 100) / 100}px` },
+        },
+        // Mockup colours: the pressed outcome takes the accent border on the soft blue, the tiles their tone.
+        pressed: (() => {
+            const probe = document.createElement('span');
+            main.append(probe);
+            const tone = name => { probe.style.color = `var(${name})`; return getComputedStyle(probe).color; };
+            const values = { accent: tone('--ca-accent'), soft: tone('--soft-blue'), green: tone('--green'), red: tone('--red'), warning: tone('--warning') };
+            probe.remove();
+            const on = outcomes.querySelector('.outcome-list > button[aria-pressed="true"]');
+            const dd = selector => getComputedStyle(statRow.querySelector(`${selector} dd`)).color;
+            return { border: getComputedStyle(on).borderTopColor === values.accent, background: getComputedStyle(on).backgroundColor === values.soft,
+                added: dd('.stat.added') === values.green, bad: dd('.stat.bad') === values.red, warn: dd('.stat.warn') === values.warning };
+        })(),
+    };
+}
+
+const EXPECTED_JOB_VIEW = {
+    tree: MOCKUP_TREE, progress: MOCKUP_PROGRESS, results: MOCKUP_RESULTS, h2: ['Progress', 'Results'],
+    summary: '● Scan log — raw detail, click to show', styles: MOCKUP_STYLES,
+    pressed: { border: true, background: true, added: true, bad: true, warn: true },
+};
+
+async function openRunningJob(page, request, theme, viewport = { width: 1600, height: 1100 }) {
+    await page.setViewportSize(viewport);
+    const started = await request.post('/__test__/jobs/start', { data: { total: 19622 } });
+    await expect(started).toBeOK();
+    const { job } = await started.json();
+    await expect(await request.post(`/__test__/jobs/${job.id}/step`, { data: { processed: 8240,
+        counters: { known: 6511, review: 37, no_metadata: 254, errors: 18 },
+        records: [{ group: 'added', path: 'CCC/mabes9sans-dataset-v1/IMG_GEN_00369_.png', detail: 'Added to the Library as “Mabes portrait”' }] } })).toBeOK();
+    await openProduction(page, `activity/${job.id}`, theme);
+    await expect(page.locator('#workspace-main .file-row')).toHaveCount(1);
+    return job;
+}
+
+for (const theme of THEMES) test(`job view follows the approved mockup ${theme}`, async ({ page, request }) => {
+    await seedConcept(request);
+    await openRunningJob(page, request, theme);
+    expect(await page.evaluate(measureJobView)).toEqual(EXPECTED_JOB_VIEW);
+
+    // Mutation check: a CSS change (tile gap) and a removed element (the outcome list) are both noticed.
+    const undoCss = await mutate(page, { css: '#workspace-main .stat-row { gap: 3px; }' });
+    expect(diffInventory(EXPECTED_JOB_VIEW, await page.evaluate(measureJobView)).map(item => item.path)).toEqual(['styles.statRow.columnGap']);
+    await undoCss();
+    const undoDom = await mutate(page, { remove: ['#workspace-main details.term'] });
+    expect(await page.evaluate(() => [...document.querySelector('#workspace-main').children].map(node => node.localName)))
+        .toEqual(['div', 'section', 'section']);
+    await undoDom();
+    expect(await page.evaluate(measureJobView)).toEqual(EXPECTED_JOB_VIEW);
+});
+
+test('job view fits a phone without page scroll', async ({ page, request }) => {
+    await seedConcept(request);
+    await openRunningJob(page, request, 'dark', { width: 390, height: 844 });
+    const layout = await page.evaluate(() => {
+        const main = document.querySelector('#workspace-main');
+        const columns = node => getComputedStyle(node).gridTemplateColumns.split(' ').length;
+        return {
+            scroll: document.documentElement.scrollWidth <= document.documentElement.clientWidth,
+            tiles: columns(main.querySelector('dl.stat-row')),
+            outcomes: columns(main.querySelector('.outcomes')),
+            inside: [...main.querySelectorAll('.stat, .outcome-list button, .file-row, .search-field')]
+                .every(node => node.getBoundingClientRect().right <= main.getBoundingClientRect().right + 0.5),
+        };
+    });
+    expect(layout).toEqual({ scroll: true, tiles: 2, outcomes: 1, inside: true });
+});

tests/browser/classic-node.spec.mjs

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { test, expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import { test, expect } from './fixtures.mjs';
 import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
 
 test.beforeEach(async ({page, browserName}) => {
@@ -57,7 +57,8 @@ test('Classic keeps immediate selection, search query and metadata serialization
 });
 
 test('Classic detaches native text synchronization on removal',async({page})=>{
-    await page.waitForTimeout(60);
+    // The page installs the text sync (serializeValue and its listeners) in a 50 ms timer; wait for it, not for time.
+    await expect.poll(()=>page.evaluate(()=>typeof node.widgets.find(item=>item.name==='text').serializeValue)).toBe('function');
     const values=await page.evaluate(()=>{
         const widget=node.widgets.find(item=>item.name==='text');
         widget.inputEl.value='Before removal';widget.inputEl.dispatchEvent(new Event('input'));

tests/browser/concept-inventory.mjs

@@ -2,7 +2,7 @@
 // same concept selectors in the immutable concept (/__test__/canonical/workspace) and in production, which now renders
 // the concept's classes. The concept is never rewritten: each page's map<Page>Concept(reference) applies only the
 // recorded spec-§8 deviations, each commented with its D-number, and diffInventory must then report nothing.
-import {expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {expect} from './fixtures.mjs';
 export {diffInventory} from './library-editor-canonical-comparison.mjs';
 
 export const CONCEPT_URL='/__test__/canonical/workspace';
@@ -78,6 +78,23 @@ export async function seedConcept(request,data={}) {
     return response.json();
 }
 
+/**
+ * Save `tags` as the current image tag set of the listed file at `path` (root 0) through the real observe and tag
+ * routes (#249 PR C), releasing the capture afterwards; returns the receipt's saved names.
+ */
+export async function saveImageTags(request,path,tags) {
+    const listing=await (await request.get('/prompt_manager/images/output?mode=workspace&limit=40')).json();
+    const target={root_index:0,root_scope:listing.images.find(item=>item.root_index===0).root_scope,path};
+    const observed=await (await request.post('/prompt_manager/image-annotations/observe',{data:{target}})).json();
+    expect(observed.success).toBe(true);
+    try {
+        const receipt=await (await request.put('/prompt_manager/image-annotations/tags',{data:{target,capture_token:observed.capture.token,
+            sha256:observed.capture.sha256,expected_epoch:observed.library_epoch,expected_tag_revision:observed.tag_revision,tags}})).json();
+        expect(receipt.success).toBe(true);
+        return receipt.tags;
+    } finally {await request.delete(`/prompt_manager/image-annotations/capture/${observed.capture.token}`);}
+}
+
 async function selectTheme(page,theme) {
     await page.getByRole('combobox',{name:'Theme',exact:true}).selectOption(theme);
 }

tests/browser/fixtures.mjs

@@ -0,0 +1,33 @@
+// Shared `test` for the page workflows: every Playwright worker owns one
+// tests/browser/server.py process on a port the OS chose for it, with its own temp root
+// and database. `baseURL` (and so `page`, `request` and `browser.newContext`)
+// points at that worker's server. A server that dies fails the running test
+// with its stderr tail, and the next test in the worker gets a fresh server.
+// A test that fails gets the stderr its server wrote during it attached as
+// `server-stderr`.
+import { test as base, expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import { attachServerStderr, createServerSupervisor, startBrowserServer } from '../../tools/vendor/start-browser-server.mjs';
+
+const SERVER_FIXTURE_TIMEOUT_MS = 90_000;
+
+export const test = base.extend({
+    testServer: [async ({}, use) => {
+        const supervisor = createServerSupervisor({ start: () => startBrowserServer() });
+        try {
+            await use(supervisor);
+        } finally {
+            await supervisor.stop();
+        }
+    }, { scope: 'worker', timeout: SERVER_FIXTURE_TIMEOUT_MS }],
+    workerServer: [async ({ testServer }, use, testInfo) => {
+        const server = await testServer.ensure();
+        const mark = server.stderrMark();
+        await use(server);
+        await attachServerStderr(testInfo, server, mark);
+        const crash = testServer.crash(server);
+        if (crash) throw crash;
+    }, { auto: true, timeout: SERVER_FIXTURE_TIMEOUT_MS }],
+    baseURL: async ({ workerServer }, use) => use(workerServer.url),
+});
+
+export { expect };

tests/browser/focused-node.spec.mjs

@@ -1,5 +1,5 @@
 import {readFileSync} from 'node:fs';
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 import {startCoverage,saveCoverage} from '../../tools/vendor/browser-coverage.mjs';
 
 for (const variant of ['Focused', 'Split']) {

tests/browser/full-inspector.spec.mjs

@@ -1,5 +1,5 @@
 import {startCoverage,saveCoverage} from '../../tools/vendor/browser-coverage.mjs';
-import { test, expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import { test, expect } from './fixtures.mjs';
 import { seedConcept, openConcept, openProduction, SIZES } from './concept-inventory.mjs';
 // D10/D20: the heading is the linked positive's title (its confirmed first line here), never the pair's
 // "Inspector recipe", which names the negative variant.
@@ -92,7 +92,7 @@ test('inspection wire preserves exact rooted envelope', async ({ request }) => {
 const inspector=page=>page.locator('.detail-panel');
 /** D19: the selected card's image opens the viewer (the side panel has no full-preview cover). */
 const openSelected=page=>page.locator('.media-card.selected .image-open').click();
-const selectFile=async(page,name,root=0)=>page.locator(`article[data-image-key="${root}:inspector/${name}"] .image-card-actions button`).click();
+const selectFile=async(page,name,root=0)=>page.locator(`article[data-image-key="${root}:inspector/${name}"] .image-card-actions button:first-child`).click();
 async function fullFixture(page,request) {
     await expect(await request.post('/__test__/reset',{data:{full_inspector:true}})).toBeOK();
     await page.goto('/prompt_manager/workspace#/images');await selectFile(page,'complete.png');
@@ -460,7 +460,7 @@ test('full inspector labels container representations and releases action URLs',
 test('full inspector distinguishes missing, limited and legacy unknown generation facts',async({page,request})=>{
     await fullFixture(page,request);const panel=inspector(page);
     await selectFile(page,'empty.png');await expect(panel.locator('.meta-grid dd')).toHaveText(Array(6).fill('Not recorded'));
-    await page.locator('article[data-image-key="0:architecture/study-01.png"] .image-card-actions button').click();await expect(panel.locator('.meta-grid dd')).toHaveText(Array(6).fill('Not recorded'));
+    await page.locator('article[data-image-key="0:architecture/study-01.png"] .image-card-actions button:first-child').click();await expect(panel.locator('.meta-grid dd')).toHaveText(Array(6).fill('Not recorded'));
     await selectFile(page,'control-heavy.png');
     const explanation='Configuration exceeds inspection limits; download the original file to inspect it locally.';
     await expect(panel.getByText(explanation,{exact:true})).toHaveCount(1);await expect(panel.getByText(explanation,{exact:true})).toBeVisible();
@@ -637,7 +637,7 @@ test('collection viewer follows filtered loaded order beyond mounted cards',asyn
     // #249 D26: the whole positive's images are in the All images dialog's own embedded gallery.
     await page.getByRole('button',{name:'All images for this positive',exact:true}).click();
     const listing=page.getByRole('dialog',{name:'All images for this positive',exact:true});
-    await listing.locator('article[data-image-key="0:inspector/complete.png"] .image-card-actions button').click();
+    await listing.locator('article[data-image-key="0:inspector/complete.png"] .image-card-actions button:first-child').click();
     await listing.locator('.media-card.selected .image-open').click();await expect(mediaDialog(page).locator('.viewer-canvas img')).toBeVisible();
     await expect(position(page)).toContainText('of 2 loaded:');
 });
@@ -804,6 +804,7 @@ test('slideshow preference failures leave native playback usable',async({page,re
 });
 
 test('full inspector attaches matched theme and mobile evidence with reachable content',async({page,request},testInfo)=>{
+    test.setTimeout(120_000); // 32 evidence captures across four viewports, like the concept comparisons
     await expect(await request.post('/__test__/reset',{data:{full_inspector:true,include_video:true}})).toBeOK();
     await page.goto('/prompt_manager/workspace#/images');
     const measurements=[];
@@ -929,7 +930,7 @@ test('collection viewer matches approved responsive frame',async({page,request},
     await page.screenshot({path:testInfo.outputPath('viewer-mobile-wider-font-2x.png')});
     await modal.getByRole('button',{name:'Close image viewer',exact:true}).click();await page.evaluate(()=>{document.documentElement.style.zoom='1';});await settleViewport(390);
     const longFiles=await(await request.get('/prompt_manager/images/output?mode=workspace&q=a-very-long&limit=40')).json();const long=longFiles.images[0];
-    await page.locator(`article[data-image-key="${long.root_index}:${long.path}"] .image-card-actions button`).click();await openCollection(page);
+    await page.locator(`article[data-image-key="${long.root_index}:${long.path}"] .image-card-actions button:first-child`).click();await openCollection(page);
     await page.evaluate(()=>{document.documentElement.style.zoom='2';});await settleViewport(390);await modal.evaluate(node=>{node.scrollTop=0;});
     await expect(modal.getByRole('button',{name:'Close image viewer',exact:true})).toBeInViewport();
 });

tests/browser/history-canonical-comparison.mjs

@@ -1,5 +1,5 @@
 import { writeFile } from 'node:fs/promises';
-import { expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import { expect } from './fixtures.mjs';
 
 // Content, row counts, and image bytes come from independent synthetic datasets.
 // Saved choices and actual executions are separate production sections. The concept's
@@ -17,7 +17,6 @@ export const canonicalDifferences = {
     // Closed by #249: the gallery's checkbox is Images-only (#259) and the role blocks are the concept's (PR D, F); the
     // exact history comparison is tests/browser/history-concept.spec.mjs.
     remainingApplicationPolish: [
-        'Gallery card tag button (#249 D9, image-annotations slice) remains outside #209',
         'Production keeps mobile toolbar inside media panel and readable scrolling details; the concept toolbar collision is not reproduced',
     ],
 };

tests/browser/history-concept.spec.mjs

@@ -1,5 +1,5 @@
 import {writeFile} from 'node:fs/promises';
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 import {captureCanonicalState} from './history-canonical-comparison.mjs';
 import {SIZES,THEMES,MOTIONS,seedConcept,openConcept,openProduction,inventoryOf,diffInventory,mutate,stripExact} from './concept-inventory.mjs';
 

tests/browser/images-concept.spec.mjs

@@ -1,5 +1,5 @@
 import {writeFile} from 'node:fs/promises';
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 import {captureCanonicalState} from './history-canonical-comparison.mjs';
 import {SIZES,THEMES,MOTIONS,seedConcept,openConcept,openProduction,inventoryOf,diffInventory,mutate,stripExact,countCopy,reflow,withoutItems} from './concept-inventory.mjs';
 
@@ -7,7 +7,7 @@ import {SIZES,THEMES,MOTIONS,seedConcept,openConcept,openProduction,inventoryOf,
 // images of the concept's six prompts, its seeds, sizes and favorites). Heading, toolbar, filter row, caption, grid,
 // the first six cards, the continuation and the panel box are compared at 1600x1100 and 390x844 in both themes, and the
 // page's behaviors under normal and reduced motion; grid, cards and panel also at 1200x900 and 1800x1100 (2 and 4
-// columns, the 275px and 310px panel). The topbar and sidebar (D5, D28, D29) are the shell spec's.
+// columns, the 275px and 310px panel). The topbar and sidebar (D28, D29, D52, D53) are the shell spec's.
 // Paired captures are artifacts only; there are no PNG baselines.
 test.use({locale:'en-US',timezoneId:'UTC'});
 
@@ -59,12 +59,12 @@ function mapBulkbar(bulkbar,rise) {
 }
 
 /**
- * A list row's info once D9 narrows its actions to `actionsWidth`, from the concept's boxes:
+ * A list row's info with its actions `actionsWidth` wide, from the concept's boxes:
  * - D3 (the measurable list row, `.list-grid .media-info` in the overlay): the info fills the row beside the art and may
  *   shrink below a long nowrap title (`min-width: 0`), so it is the card's inner width less the art, and the actions
  *   end at its right padding; it keeps its own height (text or actions plus padding), centred in the row the concept
  *   stretches it across, so the text, centred in either, moves only by half the lines it lost;
- * - D9: the wider text column fits a subtitle the concept wrapped when its one-line width (`maxContent`) now fits.
+ * - the text column fits a subtitle the concept wrapped when its one-line width (`maxContent`) now fits.
  */
 function listInfo(card,actionsWidth) {
     const {info}=card,{copy,p}=info;
@@ -109,21 +109,16 @@ export function mapImagesConcept(reference,{manifest,now=new Date()}) {
     const cards=reference.cards.map(card=>{
         const filename=card.open.label.replace(/^Open /,'');
         const actions=card.info.actions;
-        const tag=actions.buttons.find(button=>button.label?.startsWith('Tag or auto-tag '));
-        // D9: no Tag button until the image-annotations slice; the actions group narrows by its box and gap.
-        const freed=tag?tag.width+parseFloat(actions.columnGap):0;
         // D3: a list row's info keeps its own height (text or actions plus its padding) so bounded rendering can measure
         // it, centred in the row the concept stretches it across; the text and the actions keep their place.
-        const actionsWidth=actions.width-freed;
-        const listRow=list?listInfo(card,actionsWidth):{};
+        const listRow=list?listInfo(card,actions.width):{};
         return {...card,
             // D29: the concept's alt adds its demo-only " · sample illustration N" to the card title.
             img:{...card.img,alt:card.img.alt.replace(/ · sample illustration \d+$/,'')},
             info:{...card.info,...listRow.info,copy:{...card.info.copy,...listRow.copy},p:{...card.info.p,...listRow.p},
                 // D10: the title keeps the file's relative path (the fixture manifest's) in `title`.
                 h3:{...card.info.h3,title:paths.get(filename)??null},
-                actions:{...actions,width:actionsWidth,left:listRow.actionsLeft??actions.left+freed,
-                    buttons:actions.buttons.filter(button=>button!==tag)}}};
+                actions:{...actions,left:listRow.actionsLeft??actions.left}}};
     });
     // D17: the right-hand date is the newest result's day under Recently added, here the fixture's newest mtime.
     // D35: the count line uses the singular for one.
@@ -149,12 +144,15 @@ function compareLoadingRow(reference,actual,count) {
     return diffInventory(unplaced(mapContinuation(reference,{loaded,total})),unplaced(actual));
 }
 
-/** D15: the Import dialog's two real operations, with the ruled intro and the Rescan wording. */
+/**
+ * D15: the Import dialog's real operations, with the ruled intro and the Rescan wording. D55: the concept's own "Scan an
+ * output folder → Review scan" row follows Rescan as "Scan for metadata", opening the concept's "Review metadata scan".
+ */
 function mapImportConcept(reference) {
     return {...reference,
         intro:{...reference.intro,text:'Image inspection and output scanning have different effects. Choose the workflow you want.'},
-        rows:reference.rows.filter(row=>row.title!=='Import portable recipes').map(row=>row.title==='Scan an output folder'
-            ?{...row,description:'Find files added or removed in the output folders.',buttons:['Rescan']}:row)};
+        rows:reference.rows.filter(row=>row.title!=='Import portable recipes').flatMap(row=>row.title==='Scan an output folder'
+            ?[{...row,description:'Find files added or removed in the output folders.',buttons:['Rescan']},{...row,title:'Scan for metadata'}]:[row])};
 }
 
 const SECTIONS=['heading','toolbar','filterRow','bulkbar','caption','grid','cards','continuation','panel','noPageScroll'];
@@ -535,8 +533,9 @@ test('one image appended by scrolling reads in the singular',async({page,request
 });
 
 // D3 (one footer height for the collection): bounded rendering cannot measure unrendered cards, so every row reserves
-// the tallest measured footer. Two seedless files (D11 "W × H · PNG", one line) form the first row at 390px, where
-// every concept subtitle wraps: their row is as tall as the wrapped rows, and every concept row moves down by one.
+// the tallest measured footer. Two seedless files (D11 "W × H · PNG", one line: a short "96 × 72" beside Info and Tag)
+// form the first row at 390px, where every concept subtitle wraps: their row is as tall as the wrapped rows, and every
+// concept row moves down by one.
 test('one footer height for the collection (D3)',async({page,request})=>{
     // A second fixture seed (dozens of PNGs and their thumbnails) runs inside the test.
     test.setTimeout(120_000);
@@ -545,7 +544,7 @@ test('one footer height for the collection (D3)',async({page,request})=>{
     const reference=await inventoryOf(page,'#main');
     expect(reference.grid.columns).toBe(2);
     expect(reference.cards.every(card=>card.info.p.height>parseFloat(card.info.p.lineHeight))).toBe(true);
-    const manifest=await seedConcept(request,{seedless_images:2});
+    const manifest=await seedConcept(request,{seedless_images:2,short_seedless:true});
     await openProductionLoaded(page,'dark','no-preference',FIXTURE_IMAGES+2);
     const actual=await inventoryOf(page,'#workspace-main');
     const box=card=>({left:card.left,top:card.top,width:card.width,height:card.height});
@@ -554,7 +553,10 @@ test('one footer height for the collection (D3)',async({page,request})=>{
         ...reference.cards.slice(0,4).map(card=>({...box(card),top:card.top+pitch}))]);
     const seedless=actual.cards.slice(0,2);
     expect(seedless.map(card=>card.open.label)).toEqual(manifest.seedless.map(image=>`Open ${image.filename}`));
-    expect(seedless.map(card=>card.info.p.text)).toEqual(['1536 × 1152 · PNG','1536 × 1152 · PNG']);
+    expect(seedless.map(card=>card.info.p.text)).toEqual(['96 × 72 · PNG','96 × 72 · PNG']);
     // Their own footer is one line shorter than the row it reserves.
-    for(const card of seedless)expect(card.info.height).toBeLessThan(reference.cards[0].info.height);
+    for(const card of seedless) {
+        expect(card.info.p.height).toBeLessThanOrEqual(parseFloat(card.info.p.lineHeight)+0.5);
+        expect(card.info.height).toBeLessThan(reference.cards[0].info.height);
+    }
 });

tests/browser/inspect-concept.spec.mjs

@@ -0,0 +1,307 @@
+import { writeFile } from 'node:fs/promises';
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { captureCanonicalState } from './history-canonical-comparison.mjs';
+import { SIZES, THEMES, seedConcept, openConcept, openProduction, diffInventory, mutate } from './concept-inventory.mjs';
+import { parityPng } from './local-inspect-files.mjs';
+
+// PR L2 Task 7 of the local-Inspect plan (#249): the native "Inspect a file" page against the immutable concept's
+// `#metadata` (docs/concepts/workspace/app.js renderMetadata 740–748, selection 1715–1729, style.css 709–722,
+// 1180–1194, 1543–1545, 1559–1564), at 1600x1100 and 390x844 in both themes, in three states: initial, selected (the
+// same synthetic PNG set into both `#local-file` inputs) and viewer-open. The concept is never edited: the recorded
+// differences D60–D66 (TESTING.md) are applied to its measurement, and, where they change copy, to its page before it
+// is measured, so the browser lays the concept out with production's words. After that the diff must be empty.
+// Paired captures are artifacts only; there are no PNG baselines.
+test.use({ locale: 'en-US', timezoneId: 'UTC', reducedMotion: 'reduce' });
+
+const FILE = 'f02.png';
+/** D60 and D61, the maintainer's LI-3 copy, keyed by the concept's own copy. */
+const COPY = {
+    action: ['Open sample metadata', 'Open file metadata'],
+    intro: ['Keep the existing local-file inspection workflow. Only add the file to your library when you choose to import it.',
+        'Read embedded metadata in this browser. The file is not uploaded or added to your library.'],
+    chooser: ['Choose an image for a local preview', 'Choose an image or video for a local preview'],
+    note: ['This mock previews your file locally. Sample metadata is available with “Open sample metadata”.',
+        'Your file stays in this browser. Its metadata opens with “Open file metadata”.'],
+    toast: ['Local preview only. No file uploaded; sample metadata is available above.',
+        'Local preview only. No file uploaded; metadata is available above.'],
+};
+/** D62: the concept's image list plus the videos the local readers support. */
+const ACCEPT = ['image/png,image/jpeg,image/webp', 'image/png,image/jpeg,image/webp,video/*,.mp4,.mov,.m4v,.webm,.mkv,.avi,.wmv'];
+
+test.beforeEach(async ({ page, browserName }) => {
+    await startCoverage(page, browserName);
+    page.conceptErrors = [];
+    page.on('pageerror', error => page.conceptErrors.push(error.message));
+});
+
+test.afterEach(async ({ page, browserName }) => {
+    await saveCoverage(page, browserName);
+    expect(page.conceptErrors).toEqual([]);
+});
+
+/** Runs in the page: the Inspect surface below the heading, and the heading's actions. Self-contained. */
+function measureInspect(scope) {
+    const main = document.querySelector(scope);
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const name = node => [node.localName, ...[...node.classList].sort()].join('.');
+    const font = node => css(node, 'fontFamily', 'fontSize', 'fontWeight', 'lineHeight', 'color');
+    const origin = main.querySelector(':scope > section.surface');
+    const box = node => {
+        if (!node || !origin) return null;
+        const a = node.getBoundingClientRect(), b = origin.getBoundingClientRect();
+        return { left: Math.round(a.left - b.left), top: Math.round(a.top - b.top), width: Math.round(a.width), height: Math.round(a.height) };
+    };
+    const text = node => node ? node.textContent.replace(/\s+/g, ' ').trim() : null;
+    const heading = main.querySelector(':scope > .heading');
+    const surface = origin;
+    const drop = surface?.querySelector(':scope > .file-drop');
+    const input = drop?.querySelector('input#local-file');
+    const preview = surface?.querySelector(':scope > #local-preview');
+    const media = preview?.querySelector('.local-file-preview');
+    return {
+        heading: {
+            title: text(heading?.querySelector('h1')),
+            description: text(heading?.querySelector('p')),
+            actions: [...(heading?.querySelectorAll('.heading-actions > *') ?? [])].map(node => ({ name: name(node), text: text(node),
+                ...css(node, 'backgroundColor', 'color', 'fontSize', 'paddingTop', 'paddingLeft', 'borderTopLeftRadius'), box: box(node) })),
+        },
+        surface: surface && {
+            children: [...surface.children].map(name), box: box(surface),
+            ...css(surface, 'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft', 'borderTopWidth', 'borderTopStyle',
+                'borderTopColor', 'borderTopLeftRadius', 'backgroundColor'),
+            h2: { text: text(surface.querySelector(':scope > h2')), ...font(surface.querySelector(':scope > h2')), box: box(surface.querySelector(':scope > h2')) },
+            p: { text: text(surface.querySelector(':scope > p')), ...font(surface.querySelector(':scope > p')),
+                ...css(surface.querySelector(':scope > p'), 'marginTop'), box: box(surface.querySelector(':scope > p')) },
+        },
+        drop: drop && {
+            children: [...drop.children].map(name), box: box(drop),
+            ...css(drop, 'display', 'placeItems', 'textAlign', 'minHeight', 'rowGap', 'columnGap', 'marginTop', 'paddingTop',
+                'paddingRight', 'paddingBottom', 'paddingLeft', 'borderTopWidth', 'borderTopStyle', 'borderTopColor',
+                'borderBottomStyle', 'borderLeftStyle', 'borderRightStyle', 'borderTopLeftRadius', 'backgroundColor'),
+            icon: { box: box(drop.querySelector(':scope > svg.icon')), viewBox: drop.querySelector(':scope > svg.icon')?.getAttribute('viewBox'),
+                d: drop.querySelector(':scope > svg.icon path')?.getAttribute('d') ?? null,
+                ...css(drop.querySelector(':scope > svg.icon'), 'color', 'strokeWidth') },
+            label: { text: text(drop.querySelector(':scope > label')), for: drop.querySelector(':scope > label')?.htmlFor ?? null,
+                ...font(drop.querySelector(':scope > label')), box: box(drop.querySelector(':scope > label')) },
+            input: input && { type: input.type, accept: input.accept, multiple: input.multiple, ...css(input, 'maxWidth', 'fontSize', 'color'),
+                box: box(input) },
+            note: { text: text(drop.querySelector(':scope > span.small')), ...font(drop.querySelector(':scope > span.small')),
+                box: box(drop.querySelector(':scope > span.small')) },
+        },
+        preview: preview && {
+            children: [...preview.children].map(name), box: box(preview),
+            media: media && { tag: media.localName, alt: media.getAttribute('alt'), blob: media.src.startsWith('blob:'),
+                ...css(media, 'width', 'maxHeight', 'objectFit', 'marginTop', 'display'), box: box(media) },
+        },
+        // The chooser's displayed name: a file input shows the last path segment of its value.
+        chosen: input ? { name: input.value.split(/[\\/]/).pop(), files: [...input.files].map(file => file.name) } : null,
+    };
+}
+
+/** Runs in the page: the open viewer's dialog box, its toolbar controls in order and its rail's sections in order. */
+function measureViewer() {
+    const dialog = document.querySelector('dialog#viewer-dialog[open]');
+    if (!dialog) return null;
+    const css = (node, ...keys) => node ? Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]])) : null;
+    const rect = node => { const b = node.getBoundingClientRect(); return { left: Math.round(b.left), top: Math.round(b.top), width: Math.round(b.width), height: Math.round(b.height) }; };
+    const text = node => node.textContent.replace(/\s+/g, ' ').trim();
+    const rail = dialog.querySelector('#viewer-details');
+    // The rail's sections in document order, whatever wraps them.
+    const SECTIONS = [
+        ['.panel-heading', () => 'heading'],
+        ['.panel-heading + p.small', () => 'filename'],
+        ['.tags', node => node.querySelector('button.chip') ? 'tag chips' : 'badges'],
+        ['section.prompt-section.positive', () => 'positive'],
+        ['section.prompt-section.negative', () => 'negative'],
+        ['dl.meta-grid', node => node.closest('details') ? null : 'facts'],
+        ['details > summary', node => text(node)],
+        ['button.send', node => node.closest('.prompt-section') ? `send ${node.closest('.prompt-section').matches('.positive') ? 'positive' : 'negative'}` : 'send pair'],
+        ['button', node => /Prompt history/.test(node.textContent) ? 'Prompt history' : null],
+    ];
+    const sections = [...rail.querySelectorAll('*')].map(node => {
+        for (const [selector, label] of SECTIONS) if (node.matches(selector)) return label(node);
+        return null;
+    }).filter(Boolean);
+    return {
+        dialog: rect(dialog),
+        // The layout below the header; the header's height follows the title (D66) and the rail's height its content.
+        layout: (() => {
+            const header = dialog.querySelector('.dialog-header').getBoundingClientRect().bottom;
+            const left = rect(dialog.querySelector('.viewer-left')), side = rect(rail);
+            return { left: { ...left, top: Math.round(left.top - header) }, rail: { left: side.left, width: side.width },
+                ...css(dialog.querySelector('.viewer-layout'), 'display', 'gridTemplateColumns') };
+        })(),
+        title: text(dialog.querySelector('#viewer-title')),
+        subtitle: text(dialog.querySelector('.dialog-header p')),
+        toolbar: [...dialog.querySelectorAll('#viewer-toolbar > button, #viewer-toolbar > a')].map(text),
+        railTitle: text(rail.querySelector('.panel-heading h2')),
+        sections,
+    };
+}
+
+/**
+ * D60–D62 applied to the open concept page before it is measured: production's action label, copy and accept list,
+ * so the browser lays out what follows them. The concept file itself is never touched.
+ */
+async function withProductionCopy(page) {
+    await page.evaluate(({ COPY, ACCEPT }) => {
+        const main = document.querySelector('#main');
+        const swap = (node, [from, to]) => { if (node.textContent !== from) throw new Error(`concept copy changed: ${node.textContent}`); node.textContent = to; };
+        swap(main.querySelector('.heading-actions > button'), COPY.action);
+        swap(main.querySelector('section.surface > p'), COPY.intro);
+        swap(main.querySelector('.file-drop > label'), COPY.chooser);
+        swap(main.querySelector('.file-drop > span.small'), COPY.note);
+        const input = main.querySelector('#local-file');
+        if (input.accept !== ACCEPT[0]) throw new Error(`concept accept changed: ${input.accept}`);
+        input.accept = ACCEPT[1];
+    }, { COPY, ACCEPT });
+}
+
+/** D66: the viewer of a local file is titled by its filename and has no tag chips and no Prompt history. */
+function mapViewerConcept(reference) {
+    return {
+        ...reference,
+        title: FILE,
+        railTitle: FILE,
+        sections: reference.sections.filter(section => section !== 'tag chips' && section !== 'Prompt history'),
+    };
+}
+
+// Two frames, then every running transition finished.
+const settle = page => page.evaluate(async () => {
+    await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+    await Promise.all(document.getAnimations().map(animation => animation.finished.catch(() => {})));
+});
+
+async function conceptStates(page, theme, testInfo, tag) {
+    await openConcept(page, 'metadata', theme);
+    await page.mouse.move(0, 0);
+    await withProductionCopy(page);
+    await settle(page);
+    const initial = await page.evaluate(measureInspect, '#main');
+    await captureCanonicalState(page, testInfo, `concept-initial-${tag}`);
+    await page.locator('#main #local-file').setInputFiles(parityPng(FILE));
+    await expect(page.locator('#main #local-preview img.local-file-preview')).toBeVisible();
+    await page.locator('#main #local-preview img').evaluate(image => image.decode().catch(() => {}));
+    await expect(page.locator('#toast')).toHaveText(COPY.toast[0]);
+    await settle(page);
+    const selected = await page.evaluate(measureInspect, '#main');
+    await captureCanonicalState(page, testInfo, `concept-selected-${tag}`);
+    await page.locator('#main .heading-actions > button').click();
+    await expect(page.locator('dialog#viewer-dialog[open] #viewer-details .panel-heading')).toBeVisible();
+    await page.mouse.move(0, 0);
+    await settle(page);
+    const viewer = await page.evaluate(measureViewer);
+    await captureCanonicalState(page, testInfo, `concept-viewer-${tag}`);
+    return { initial, selected, viewer };
+}
+
+async function productionStates(page, theme, testInfo, tag) {
+    await openProduction(page, 'inspect', theme);
+    await page.mouse.move(0, 0);
+    const action = page.locator('#workspace-main .heading-actions').getByRole('button', { name: COPY.action[1], exact: true });
+    // D60: unavailable, and described by the drop note, until a classified file is chosen.
+    await expect(action).toHaveAttribute('aria-disabled', 'true');
+    await expect(action).toHaveAttribute('aria-describedby', 'local-file-note');
+    await settle(page);
+    const initial = await page.evaluate(measureInspect, '#workspace-main');
+    await captureCanonicalState(page, testInfo, `production-initial-${tag}`);
+    await page.locator('#workspace-main #local-file').setInputFiles(parityPng(FILE));
+    await expect(page.locator('#workspace-main #local-preview img.local-file-preview')).toBeVisible();
+    await page.locator('#workspace-main #local-preview img').evaluate(image => image.decode().catch(() => {}));
+    await expect(page.locator('#workspace-toast')).toHaveText(COPY.toast[1]);
+    await expect(action).toHaveAttribute('aria-disabled', 'false');
+    // D63: a readable PNG shows no status line.
+    await expect(page.locator('#workspace-main #local-preview p.small')).toHaveCount(0);
+    await settle(page);
+    const selected = await page.evaluate(measureInspect, '#workspace-main');
+    await captureCanonicalState(page, testInfo, `production-selected-${tag}`);
+    await action.click();
+    await expect(page.locator('dialog#viewer-dialog[open] #viewer-details .panel-heading')).toBeVisible();
+    await expect(page.locator('dialog#viewer-dialog[open] #viewer-details .meta-grid').first()).toBeVisible();
+    await page.mouse.move(0, 0);
+    await settle(page);
+    const viewer = await page.evaluate(measureViewer);
+    await captureCanonicalState(page, testInfo, `production-viewer-${tag}`);
+    return { initial, selected, viewer };
+}
+
+/** The concept's fixed CSS values (style.css 709–722, 1180–1194, 1543–1545, 1559–1564), restated as the plan pins them. */
+function expectPinnedValues(state) {
+    expect(state.surface).toMatchObject({ paddingTop: '22px', paddingLeft: '22px', borderTopLeftRadius: '7px', borderTopStyle: 'solid' });
+    expect(state.surface.h2).toMatchObject({ fontSize: '17px', fontWeight: '600' });
+    expect(state.surface.p).toMatchObject({ fontSize: '12px' });
+    expect(state.drop).toMatchObject({ display: 'grid', textAlign: 'center', minHeight: '170px', rowGap: '12px', columnGap: '12px',
+        marginTop: '20px', paddingTop: '22px', paddingLeft: '22px', borderTopStyle: 'dashed', borderBottomStyle: 'dashed',
+        borderLeftStyle: 'dashed', borderRightStyle: 'dashed', borderTopWidth: '1px', borderTopLeftRadius: '7px' });
+    expect(state.drop.input).toMatchObject({ maxWidth: '100%', fontSize: '12px' });
+}
+
+for (const [width, height] of SIZES) for (const theme of THEMES) {
+    test(`inspect surface matches the concept ${width}x${height} ${theme}`, async ({ page, request }, testInfo) => {
+        await page.setViewportSize({ width, height });
+        await seedConcept(request);
+        const tag = `${theme}-${width}`;
+        const concept = await conceptStates(page, theme, testInfo, tag);
+        const production = await productionStates(page, theme, testInfo, tag);
+        const mappedViewer = mapViewerConcept(concept.viewer);
+        const diff = {
+            initial: diffInventory(concept.initial, production.initial),
+            selected: diffInventory(concept.selected, production.selected),
+            viewer: diffInventory(mappedViewer, production.viewer),
+        };
+        const path = testInfo.outputPath('inspect-geometry.json');
+        await writeFile(path, JSON.stringify({ concept, production, diff }, null, 2));
+        await testInfo.attach('inspect-geometry', { path, contentType: 'application/json' });
+
+        // The concept is what this comparison assumes: its structure, its own copy (swapped above) and its chooser.
+        expect(concept.initial.surface.children).toEqual(['h2', 'p', 'div.file-drop.spaced-20', 'div']);
+        expect(concept.initial.drop.children).toEqual(['svg.icon', 'label', 'input', 'span.small']);
+        expect(concept.selected.preview.children).toEqual(['img.local-file-preview']);
+        expect(concept.selected.chosen).toEqual({ name: FILE, files: [FILE] });
+        expect(concept.viewer.toolbar).toEqual(['← Previous', '−', '+', 'Fit', 'Rotate', 'Flip', 'Play', 'Download', 'Next →']);
+
+        expect(diff).toEqual({ initial: [], selected: [], viewer: [] });
+        for (const state of [production.initial, production.selected]) expectPinnedValues(state);
+        expect(production.selected.preview.media).toMatchObject({ tag: 'img', alt: 'Local file preview', blob: true,
+            maxHeight: '400px', objectFit: 'contain', marginTop: '20px' });
+        // The chooser names the chosen file after a real setInputFiles, as the concept's does.
+        expect(production.initial.chosen).toEqual({ name: '', files: [] });
+        expect(production.selected.chosen).toEqual({ name: FILE, files: [FILE] });
+        // D66 in the rail: no tag chips and no Prompt history; the title is the filename.
+        expect(production.viewer.sections).toEqual(['heading', 'filename', 'badges', 'positive', 'send positive', 'negative',
+            'send negative', 'facts', 'File & provenance', 'Workflow & raw metadata', 'send pair']);
+    });
+}
+
+test('mutation is noticed', async ({ page, request }, testInfo) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await seedConcept(request);
+    await openConcept(page, 'metadata', 'dark');
+    await withProductionCopy(page);
+    const concept = await page.evaluate(measureInspect, '#main');
+    await openProduction(page, 'inspect', 'dark');
+    await page.mouse.move(0, 0);
+    expect(diffInventory(concept, await page.evaluate(measureInspect, '#workspace-main'))).toEqual([]);
+
+    // A solid border on the drop area is noticed on every side and nowhere else.
+    const undoCss = await mutate(page, { css: '#workspace-main .file-drop { border-style: solid; }' });
+    expect(diffInventory(concept, await page.evaluate(measureInspect, '#workspace-main')).map(item => item.path))
+        .toEqual(['drop.borderTopStyle', 'drop.borderBottomStyle', 'drop.borderLeftStyle', 'drop.borderRightStyle']);
+    await undoCss();
+    // A renamed label is noticed (its text; its box only if the new words lay out differently).
+    const label = page.locator('#workspace-main .file-drop > label');
+    await label.evaluate(node => { node.dataset.original = node.textContent; node.textContent = 'Choose a file'; });
+    const renamed = diffInventory(concept, await page.evaluate(measureInspect, '#workspace-main')).map(item => item.path);
+    expect(renamed).toContain('drop.label.text');
+    expect(renamed.every(path => path.startsWith('drop.label.'))).toBe(true);
+    await label.evaluate(node => { node.textContent = node.dataset.original; delete node.dataset.original; });
+    // A removed note is noticed by its path.
+    const undoDom = await mutate(page, { remove: ['#workspace-main .file-drop > span.small'] });
+    expect(diffInventory(concept, await page.evaluate(measureInspect, '#workspace-main')).map(item => item.path))
+        .toEqual(expect.arrayContaining(['drop.children.3', 'drop.note.text']));
+    await undoDom();
+    expect(diffInventory(concept, await page.evaluate(measureInspect, '#workspace-main'))).toEqual([]);
+    await captureCanonicalState(page, testInfo, 'production-after-mutations');
+});

tests/browser/inspector-concept.spec.mjs

@@ -1,7 +1,7 @@
 import {writeFile} from 'node:fs/promises';
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 import {captureCanonicalState} from './history-canonical-comparison.mjs';
-import {SIZES,THEMES,seedConcept,openConcept,openProduction,inspectorOf,diffInventory,mutate,countCopy} from './concept-inventory.mjs';
+import {SIZES,THEMES,seedConcept,openConcept,openProduction,inspectorOf,diffInventory,mutate,countCopy,saveImageTags} from './concept-inventory.mjs';
 
 // Task D4 of #249: the Images side panel (app.js imageDetails a400–414) and the viewer's full details (imageDetails(i,
 // true)) against the immutable concept, on the concept-shaped real fixture, at 1600x1100 and 390x844 in both themes.
@@ -319,6 +319,27 @@ test('a recipe-linked image without recipe metadata shows its positive prompt me
     await expect(panelOf(page).locator('.detail-footer button')).toHaveText(['Send to ComfyUI','Prompt history']);
 });
 
+// Task C3 (D88, #249 PR C): the concept's chip row is the image's own tags (`i.tags`, app.js a402). With those names
+// saved as the file's current image tags, production draws the row from them (Tags filter buttons in the panel, plain
+// in the viewer, the linked positive's equal tags not repeated) and still equals the concept, in both sizes.
+for(const [width,height] of SIZES)test(`image tags saved on the concept image keep the inspector equal to the concept ${width}x${height} (D88)`,async({page,request},testInfo)=>{
+    test.setTimeout(120_000);
+    const viewport={width,height};await page.setViewportSize(viewport);
+    await openConceptPanel(page,'dark');
+    const names=await panelOf(page).locator('.detail-inner > .tags').last().locator('button.chip').allTextContents();
+    expect(names).toEqual(['cinematic','blue_hour','architecture']);
+    await captureCanonicalState(page,testInfo,`concept-image-tags-${width}`,'#image-inspector');
+    const reference=await inventory(page,true);
+    const {path}=testInfo.manifest.images.find(item=>item.filename==='alpine_00001.png');
+    expect(await saveImageTags(request,path,names)).toEqual(names);
+    const read=page.waitForResponse(item=>new URL(item.url()).pathname===`/prompt_manager/images/inspect/${path}`);
+    await openProductionPanel(page,'dark');
+    expect((await (await read).json()).image_tags).toEqual({state:'current',tags:names});
+    await expect(panelOf(page).locator('.detail-inner > .tags').last().locator('.chip')).toHaveText(names);
+    await captureCanonicalState(page,testInfo,`production-image-tags-${width}`,'#image-inspector');
+    assertInspectorMatch(reference,await inventory(page),viewport);
+});
+
 // The comparison is only worth something if it notices a change (spec §7 mutation check): on the panel one CSS
 // mutation (the role label's letter spacing) and one DOM mutation (the footer removed); in the viewer (final review m5)
 // its pair actions removed and D38's Show in folder removed; each applied after an exact match.

tests/browser/library-concept.spec.mjs

@@ -1,5 +1,5 @@
 import {writeFile} from 'node:fs/promises';
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 import {captureCanonicalState} from './history-canonical-comparison.mjs';
 import {SIZES,THEMES,MOTIONS,seedConcept,openConcept,openProduction,inventoryOf,diffInventory,mutate,stripExact,countCopy,reflow} from './concept-inventory.mjs';
 

tests/browser/library-editor-visual.spec.mjs

@@ -1,4 +1,4 @@
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 import {captureCanonicalState} from './history-canonical-comparison.mjs';
 
 // Artifact-only captures of the editor states that have no concept counterpart (archive confirmation, Show archived,

tests/browser/local-inspect-files.mjs

@@ -0,0 +1,66 @@
+// Files for the Inspect page workflows, as Playwright `setInputFiles` payloads ({name, mimeType, buffer}) or as the
+// bytes a page builds a File or DataTransfer from. Built from the committed fixtures and the byte-exact PNG builders
+// the node tests use (tests/js/helpers/png-bytes.mjs), so the browser reads exactly what the unit tests pin.
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { fileURLToPath } from 'node:url';
+import { raw, ihdr, idat, iend, tEXt } from '../js/helpers/png-bytes.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURES = path.join(here, '..', 'fixtures');
+const read = (...parts) => fs.readFileSync(path.join(FIXTURES, ...parts));
+const file = (name, mimeType, buffer) => ({ name, mimeType, buffer: Buffer.from(buffer) });
+
+/** One committed parity PNG (tests/fixtures/inspection_parity), e.g. f02.png. */
+export const parityPng = (name, as = name) => file(as, 'image/png', read('inspection_parity', name));
+/** One committed local-inspect fixture (tests/fixtures/local-inspect). */
+export const localFixture = (name, mimeType, as = name) => file(as, mimeType, read('local-inspect', name));
+/** The committed CC0 VP8 clip with no generation metadata. */
+export const tinyWebm = () => file('tiny.webm', 'video/webm', read('tiny.webm'));
+
+/** One decodable 2×2 opaque pixel row set, so a synthetic PNG previews. */
+function pixels(width = 2, height = 2) {
+    const row = [0, ...Array.from({ length: width }, () => [40, 120, 200, 255]).flat()];
+    return zlib.deflateSync(Buffer.from(Array.from({ length: height }, () => row).flat()));
+}
+
+/**
+ * A previewable PNG whose positive spans lines and whose negative is a ConditioningZeroOut: the legacy fill shows the
+ * positive exactly and the ZeroOut guard makes the negative explicitly empty.
+ */
+export const POSITIVE_LINES = 'a lighthouse at dusk\nsoft rain, long exposure';
+export function sendablePng(name = 'send-me.png') {
+    const prompt = JSON.stringify({
+        3: { class_type: 'KSampler', inputs: { seed: 11, steps: 12, cfg: 5, sampler_name: 'euler', scheduler: 'normal', denoise: 1, model: ['4', 0], positive: ['6', 0], negative: ['8', 0], latent_image: ['5', 0] } },
+        4: { class_type: 'CheckpointLoaderSimple', inputs: { ckpt_name: 'local.safetensors' } },
+        5: { class_type: 'EmptyLatentImage', inputs: { width: 512, height: 512, batch_size: 1 } },
+        6: { class_type: 'CLIPTextEncode', inputs: { text: POSITIVE_LINES, clip: ['4', 1] } },
+        8: { class_type: 'ConditioningZeroOut', inputs: { conditioning: ['6', 0] } },
+    });
+    return file(name, 'image/png', raw(ihdr(2, 2), idat(pixels()), tEXt('prompt', prompt), iend()));
+}
+
+/** A PNG whose text chunk fails its CRC: the reader reports the metadata unreadable; the bytes stay downloadable. */
+export const corruptPng = (name = 'corrupt.png') =>
+    file(name, 'image/png', raw(ihdr(2, 2), idat(pixels()), tEXt('prompt', '{"3":{}}', { crc: 1 }), iend()));
+
+/** Bytes no reader claims, under an image or video name. */
+export const disguised = () => [
+    file('notes.png', 'image/png', Buffer.from('plain text, not an image')),
+    file('page.png', 'image/png', Buffer.from('<!doctype html><title>x</title><p>hi')),
+    file('vector.png', 'image/png', Buffer.from('<svg xmlns="http://www.w3.org/2000/svg" width="4" height="4"/>')),
+    file('stream.mp4', 'video/mp4', Buffer.from('#EXTM3U\n#EXT-X-VERSION:3\n')),
+];
+
+/**
+ * core-faststart.mp4 with its video sample entry renamed from `avc1` to `zzzz`: the container and its tags read as
+ * before, but no browser has a decoder for the stream, so the preview fails deterministically on every engine.
+ */
+export function undecodableMp4(name = 'undecodable.mp4') {
+    const bytes = Buffer.from(read('local-inspect', 'core-faststart.mp4'));
+    const at = bytes.indexOf(Buffer.from('avc1', 'latin1'), bytes.indexOf(Buffer.from('stsd', 'latin1')));
+    if (at < 0) throw new Error('core-faststart.mp4 has no avc1 sample entry');
+    bytes.write('zzzz', at, 'latin1');
+    return file(name, 'video/mp4', bytes);
+}

tests/browser/pair-node.spec.mjs

@@ -1,5 +1,5 @@
 import {readFileSync} from 'node:fs';
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 import {startCoverage,saveCoverage} from '../../tools/vendor/browser-coverage.mjs';
 
 const pair={id:4,positive_text:'Library positive',negative_text:'Library negative',category:'Portrait',tags:['studio']};

tests/browser/prompt-bridge.spec.mjs

@@ -1,4 +1,4 @@
-import { test, expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import { test, expect } from './fixtures.mjs';
 import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
 
 const moduleUrl = '/prompt_manager/js/shared/toolkit/prompt-bridge.js';

tests/browser/prompt-inspector.spec.mjs

@@ -1,5 +1,5 @@
 import {startCoverage,saveCoverage} from '../../tools/vendor/browser-coverage.mjs';
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 
 const workspace='/prompt_manager/workspace#/images';
 const details=page=>page.getByRole('complementary',{name:'Selected image details',exact:true});

tests/browser/server.py

@@ -1,19 +1,24 @@
 """Serve production pages and API routes with disposable state for browser tests."""
 
 import argparse
+import asyncio
 import json
 import os
 import shutil
+import socket
 from pathlib import Path
 import sys
 import tempfile
+import threading
 import time
 import types
 
 from aiohttp import web
+from aiohttp.web_runner import GracefulExit
 from PIL import Image
 from PIL.PngImagePlugin import PngInfo
 
+from tests.browser.workspace_activity_fixture import register_activity_commands
 from tests.browser.workspace_concept_fixture import (
     MAX_EXTRA_IMAGES as CONCEPT_MAX_EXTRA_IMAGES,
     MAX_SEEDLESS_IMAGES as CONCEPT_MAX_SEEDLESS_IMAGES,
@@ -30,6 +35,7 @@ from tests.browser.workspace_library_editor_fixture import (
     register_library_editor_commands,
 )
 from tests.browser.workspace_vocabulary_fixture import register_vocabulary_commands
+from tests.browser.workspace_tagging_fixture import register_tagging_commands
 
 CANONICAL_ROOT = Path(__file__).resolve().parents[2]
 CANONICAL_ASSETS = {
@@ -52,11 +58,19 @@ class TestModel:
     wd14_character_threshold = 0.85
     custom_prompt = ""
     loaded = None
+    # Models the Tag image dialog workflows mark as not downloaded.
+    unavailable: set = set()
+    # Scored names the concept comparisons answer instead of the fixed list
+    # (``/__test__/tagging/suggestions``); None keeps the fixed list.
+    suggestions: list | None = None
 
     def get_models_status(self) -> dict:
         return {
-            name: {"downloaded": True, "loaded": self.loaded == name}
-            for name in ("gguf", "wd14-vit", "wd14-convnext", "wd14-swinv2")
+            name: {
+                "downloaded": name not in self.unavailable,
+                "loaded": self.loaded == name,
+            }
+            for name in ("gguf", "hf", "wd14-vit", "wd14-convnext", "wd14-swinv2")
         }
 
     def is_model_loaded(self) -> bool:
@@ -75,6 +89,26 @@ class TestModel:
     def generate_tags(self, image_path: str, **kwargs: object) -> list[str]:
         return ["generated", Path(image_path).parent.parent.name]
 
+    def generate_tag_suggestions(
+        self, image_path: str, *, limit: int, **kwargs: object
+    ) -> list[tuple[str, float | None]]:
+        """Fixed scored suggestions (WD14) or unscored ones (language models)."""
+        scored = self.loaded is not None and self.loaded.startswith("wd14")
+        if self.suggestions is not None:
+            return [
+                (name, confidence if scored else None)
+                for name, confidence in self.suggestions[:limit]
+            ]
+        names = ["sandstone", "desert", "arch", "sky", "rock", "dune", "canyon"]
+        names += [f"tag_{index:02d}" for index in range(100)]
+        return [
+            (name, round(0.98 - index * 0.008, 3) if scored else None)
+            for index, name in enumerate(names[:limit])
+        ]
+
+    def download_model(self, model_type: str, progress_callback=None) -> bool:
+        raise AssertionError("browser tests never download a model")
+
 
 REVEAL_OUTCOMES = ("opened", "unavailable", "fail")
 
@@ -158,7 +192,9 @@ def create_app(root: Path) -> web.Application:
     history_commands = register_workspace_history_commands(routes, api, root)
     library_editor_commands = register_library_editor_commands(routes, api, root)
     register_vocabulary_commands(routes, api, root)
+    register_tagging_commands(routes, api, root, model)
     reveal_stub = register_reveal_stub(routes, api, root)
+    register_activity_commands(app, routes, api)
 
     async def canonical_asset(request: web.Request) -> web.Response:
         filename, content_type = CANONICAL_ASSETS[request.path]
@@ -183,6 +219,9 @@ def create_app(root: Path) -> web.Application:
             for table in (
                 "saved_views",
                 "image_favorites",
+                "media_image_tags",
+                "media_annotation_bytes",
+                "media_annotation_files",
                 "image_prompt_pairs",
                 "prompt_pair_tags",
                 "prompt_pairs",
@@ -447,7 +486,8 @@ def create_app(root: Path) -> web.Application:
         if (
             request.query
             or not isinstance(data, dict)
-            or set(data) - set(limits)
+            or set(data) - set(limits) - {"short_seedless"}
+            or not isinstance(data.get("short_seedless", False), bool)
             or any(
                 isinstance(data.get(key, 0), bool)
                 or not isinstance(data.get(key, 0), int)
@@ -466,6 +506,7 @@ def create_app(root: Path) -> web.Application:
                 root,
                 extra_images=data.get("extra_images", 0),
                 seedless_images=data.get("seedless_images", 0),
+                short_seedless=data.get("short_seedless", False),
             )
         )
         return web.json_response({"success": True, **manifest})
@@ -500,6 +541,33 @@ def create_app(root: Path) -> web.Application:
         shutil.copyfile(root / "output" / "shared" / "same.png", destination)
         return web.json_response({"success": True})
 
+    @routes.post("/__test__/add-local-inspect-file")
+    async def add_local_inspect_file(request: web.Request) -> web.Response:
+        """Serve one committed Inspect fixture from the output folder.
+
+        The local Inspect page reads a chosen file in the browser; its page
+        workflow compares that rail with the Images viewer for the same bytes.
+        Only a committed fixture name is accepted.
+        """
+        data = await request.json() if request.can_read_body else None
+        fixtures = CANONICAL_ROOT / "tests" / "fixtures"
+        allowed = {
+            path.name: path
+            for folder in ("inspection_parity", "local-inspect")
+            for path in (fixtures / folder).iterdir()
+            if path.suffix.lower() in {".png", ".jpg", ".webp", ".webm", ".mp4"}
+        }
+        if (
+            not isinstance(data, dict)
+            or set(data) != {"name"}
+            or data["name"] not in allowed
+        ):
+            raise web.HTTPBadRequest()
+        destination = root / "output" / "local-inspect" / data["name"]
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(allowed[data["name"]], destination)
+        return web.json_response({"success": True})
+
     @routes.get("/api/settings/Comfy.ColorPalette")
     async def palette(request: web.Request) -> web.Response:
         return web.json_response("dark")
@@ -513,14 +581,77 @@ def create_app(root: Path) -> web.Application:
     return app
 
 
-def main() -> None:
+HOST = "127.0.0.1"
+PORT_ANNOUNCEMENT = "PM_TEST_SERVER_PORT="
+
+
+def bind_listener(port: int) -> socket.socket:
+    """Bind the server's socket before the app is built.
+
+    ``port`` 0 lets the OS choose a free port, which this process then holds,
+    so parallel launchers never race for one between choosing and binding.
+    """
+    listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        if port and os.name != "nt":
+            # aiohttp's own default on POSIX; on Windows it would let a
+            # second process share the port.
+            listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        listener.bind((HOST, port))
+        listener.listen(128)
+    except OSError:
+        listener.close()
+        raise
+    return listener
+
+
+def _graceful_exit() -> None:
+    raise GracefulExit()
+
+
+def exit_when_stdin_closes(loop: asyncio.AbstractEventLoop) -> threading.Thread:
+    """Stop the app gracefully once stdin reaches end of file.
+
+    The launcher keeps the write end of this process's stdin pipe, and the OS
+    closes it however the launcher dies, SIGKILL included. GracefulExit runs
+    aiohttp's cleanup (closing the database) and lets the temp root be removed,
+    on every OS, where a signal from a dead parent would not.
+    """
+
+    def watch() -> None:
+        while sys.stdin.buffer.read(65536):
+            pass
+        loop.call_soon_threadsafe(_graceful_exit)
+
+    thread = threading.Thread(target=watch, name="stdin-eof", daemon=True)
+    thread.start()
+    return thread
+
+
+def main(argv: list[str] | None = None) -> None:
     parser = argparse.ArgumentParser()
-    parser.add_argument("--port", type=int, default=8765)
-    args = parser.parse_args()
+    parser.add_argument(
+        "--port", type=int, default=8765, help="0 binds an OS-chosen free port"
+    )
+    parser.add_argument(
+        "--exit-on-stdin-eof",
+        action="store_true",
+        help="shut down when stdin closes (the launcher's parent-death guard)",
+    )
+    args = parser.parse_args(argv)
+    listener = bind_listener(args.port)
+    # One machine-readable line tells the launcher which port this process holds.
+    print(f"{PORT_ANNOUNCEMENT}{listener.getsockname()[1]}", flush=True)
+    loop = asyncio.new_event_loop()
+    if args.exit_on_stdin_eof:
+        exit_when_stdin_closes(loop)
+    original_cwd = os.getcwd()
     with tempfile.TemporaryDirectory(prefix="pm-browser-") as directory:
-        web.run_app(
-            create_app(Path(directory).resolve()), host="127.0.0.1", port=args.port
-        )
+        try:
+            web.run_app(create_app(Path(directory).resolve()), sock=listener, loop=loop)
+        finally:
+            # create_app works inside the root; Windows cannot remove a process's cwd.
+            os.chdir(original_cwd)
 
 
 if __name__ == "__main__":

tests/browser/shell-concept.spec.mjs

@@ -1,7 +1,7 @@
 import {writeFile} from 'node:fs/promises';
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 import {captureCanonicalState} from './history-canonical-comparison.mjs';
-import {SIZES,THEMES,MOTIONS,seedConcept,openConcept,openProduction,inventoryOf,diffInventory,focusRingOf,hoverStateOf,mutate} from './concept-inventory.mjs';
+import {SIZES,THEMES,MOTIONS,seedConcept,openConcept as openConceptPage,openProduction,inventoryOf,diffInventory,focusRingOf,hoverStateOf,mutate} from './concept-inventory.mjs';
 
 // Task A6 of #249: the production shell (sidebar, topbar, heading, footer) against the immutable concept, with the
 // concept-shaped real fixture so the sidebar counts are the concept's own (24 images, 6 prompts, 15 tags). Both themes,
@@ -16,7 +16,16 @@ const FULL_HEADING=new Set(['tags']);
 
 const rowNamed=(nav,text)=>nav.rows.find(row=>row.text===text);
 
-const removedItem=item=>String(item.className).includes('concept-badge')||(item.tag==='button'&&item.text.startsWith('Activity'));
+const removedItem=item=>String(item.className).includes('concept-badge');
+
+/**
+ * The concept with its Activity count hidden (D52): production counts running jobs only and hides the count at 0, as
+ * the comparison fixture has none. The concept's own CSS then lays out its button without the count.
+ */
+async function openConcept(page,route,theme,motion) {
+    await openConceptPage(page,route,theme,motion);
+    await mutate(page,{css:'#activity-count { display: none }'});
+}
 
 /** Left offsets of flex items packed along a row of `width` by its `justify-content` and `gap`. */
 function packedLefts(items,width,justify,gap) {
@@ -37,10 +46,12 @@ function remainingTopActions(actions) {
     const gap=parseFloat(actions.columnGap);
     // A full-width row (<=700px) keeps its width; otherwise it shrinks to its remaining items.
     const width=actions.fullWidth?actions.width:shown.reduce((sum,item)=>sum+item.width,0)+gap*(shown.length-1);
-    // At <=700px the concept spreads three items with `space-between`, so its Theme select sits in the middle; with
-    // Activity removed (D5) the same rule puts Theme at the row's start. Offsets come from the concept's own sizes.
+    // At <=700px the concept spreads its shown items with `space-between`; the hidden pill (D53) takes no place.
+    // Offsets come from the concept's own sizes.
     const lefts=new Map(shown.map((item,index)=>[item,packedLefts(shown,width,actions.justifyContent,gap)[index]]));
     return {...actions,height,width,
+        // D52: the full-width row (<=700px) wraps its items when a zoomed phone is narrower than they are.
+        flexWrap:actions.fullWidth?'wrap':actions.flexWrap,
         items:kept.map(item=>item.shown?{...item,top:Math.round((height-item.height)/2),left:lefts.get(item)}:item)};
 }
 
@@ -53,7 +64,7 @@ function remainingFooter(footer,spans) {
 }
 
 // D28 ruling (final review A, Minor 1): Overview gets a distinct outline home glyph. The concept has no home icon, and
-// its `activity` pulse stays reserved for the Activity row D5 omits, so the two entries never share one glyph.
+// its `activity` pulse belongs to the Activity row, so the two entries never share one glyph.
 const OVERVIEW_GLYPH='M3 11 12 4l9 7M5 10v10h14V10M10 20v-6h4v6';
 
 /**
@@ -76,7 +87,9 @@ function mapShellConcept(reference) {
             if(nav.id!=='system-nav')return nav;
             const system=rowNamed(nav,'System');
             return {...nav,rows:[
-                // D5: no Activity row until an activity center exists. D28: no Design review (prototype page).
+                // D52: the Activity row counts running jobs only, so with none it has no count.
+                {...rowNamed(nav,'Activity'),count:null},
+                // D28: no Design review (prototype page).
                 system,
                 // D28: the production Overview hub follows System, as a concept nav row without a count. Its icon is
                 // the ruling's own outline home glyph (OVERVIEW_GLYPH), never the concept's `activity` pulse.
@@ -95,19 +108,18 @@ function mapShellConcept(reference) {
             small:'Your library, on your server',
             // D28: no fake connection state, so the dot is the neutral muted token (the concept's label color).
             dot:{...chrome.connection.dot,backgroundColor:chrome.labels[0].color}},
-        // D29: no "Interactive concept" badge. D5: no Activity button. The row's size and the remaining items'
-        // centered offsets follow from the concept's own item sizes.
-        topActions:remainingTopActions(chrome.topActions),
+        // D29: no "Interactive concept" badge. D53: the progress pill before the Activity button, hidden with no running
+        // job. D52: the button's count is hidden at 0. The row's size and the remaining items' centered offsets follow
+        // from the concept's own item sizes.
+        topActions:remainingTopActions({...chrome.topActions,items:chrome.topActions.items.flatMap(item=>
+            item.tag==='button'&&item.text==='Activity'?[{tag:'a',className:'activity-pill',shown:false},{...item,count:'0'}]:[item])}),
         footer:(()=>{
             // D29: production footer copy (one line, as the concept's own copy is), and no "What changes & why"
             // (a prototype review page); the footer then holds only its span.
             const spans=chrome.footer.spans.map(span=>({...span,text:'ComfyAssets · Local tools. Your library.'}));
             return {...chrome.footer,spans,buttons:[],height:remainingFooter(chrome.footer,spans)};
         })(),
-    },
-    heading:reference.heading&&{...reference.heading,actions:reference.heading.actions&&{...reference.heading.actions,
-        // #245 vocabulary ruling D2 (mapVocabularyConcept): Auto-tag images is omitted until the image-annotation slice.
-        buttons:reference.heading.actions.buttons.filter(item=>item.text!=='Auto-tag images')}}};
+    }};
 }
 
 /** The heading without its page-owned description copy and actions; the h1 text is the shell's and stays compared. */

tests/browser/tagging-canonical-comparison.mjs

@@ -0,0 +1,142 @@
+// Concept-vs-production inventory of the Tag image dialog (plan Mock inventory M2: docs/concepts/workspace/app.js
+// tagReview a1037–1061, renderTagModelOptions a1062–1076, generateTags a1077–1135; style.css s1598–1694) and of the
+// card's Info and Tag group (M1: app.js mediaCard a398, style.css s1589–1597). The *Of functions run in the page.
+// The concept is never rewritten: mapConceptTagging applies only the recorded deviations, each named with its D-number
+// or ruling; everything else must be equal.
+export {diffInventory as diffTaggingInventory} from './library-editor-canonical-comparison.mjs';
+
+/** The open Tag image dialog (`dialog#modal`), its controls in order with their concept tokens. */
+export function taggingInventory(dialog) {
+    const css=(node,...keys)=>{const style=getComputedStyle(node);return Object.fromEntries(keys.map(key=>[key,style[key]]));};
+    const px=value=>Math.round(value*2)/2;
+    const box=node=>{const rect=node.getBoundingClientRect();return {width:px(rect.width),height:px(rect.height)};};
+    const font=node=>css(node,'fontSize','fontWeight','lineHeight','color','marginTop','marginBottom');
+    const edges=node=>css(node,'paddingTop','paddingRight','paddingBottom','paddingLeft','borderTopWidth','borderTopStyle','borderTopColor',
+        'borderTopLeftRadius','backgroundColor');
+    const buttonOf=node=>({text:node.textContent.trim(),label:node.getAttribute('aria-label'),primary:node.classList.contains('ca-primary'),
+        icon:node.querySelector('svg')!==null,disabled:node.getAttribute('aria-disabled')==='true'||node.disabled,
+        ...css(node,'minHeight','fontSize','color','backgroundColor','borderTopColor','borderTopLeftRadius')});
+    const controlOf=node=>({tag:node.tagName.toLowerCase(),id:node.id,type:node.type??null,value:node.value,
+        min:node.getAttribute('min'),max:node.getAttribute('max'),step:node.getAttribute('step'),
+        describedBy:node.getAttribute('aria-describedby'),
+        options:node.tagName==='SELECT'?[...node.options].map(option=>[option.value,option.textContent]):null,
+        ...css(node,'fontSize','minHeight','backgroundColor','color','borderTopColor','borderTopLeftRadius','paddingLeft')});
+    const fieldOf=field=>{const label=field.querySelector('label'),control=field.querySelector('input,textarea,select');
+        return {label:label.textContent,labelled:label.htmlFor===control.id,...css(field,'display','rowGap','marginTop','marginBottom'),control:controlOf(control)};};
+    const header=dialog.querySelector('.dialog-header'),title=header.querySelector('h2'),close=header.querySelector('button');
+    const body=dialog.querySelector('#modal-body');
+    const heading=body.querySelector('.tag-image-heading');
+    const preview=heading.querySelector('.tag-image-preview'),copy=heading.querySelector(':scope > div');
+    const sizeChip=copy.querySelector('.chip');
+    const note=body.querySelector('.tag-scope-note');
+    const manual=body.querySelector('#manual-image-tags'),manualField=manual.closest('.field'),help=body.querySelector('#manual-tags-help');
+    const panel=body.querySelector('.tag-model-panel'),options=panel.querySelector('#image-tag-model-options');
+    const generate=[...panel.querySelectorAll('button')].at(-1);
+    const suggestions=body.querySelector('section.tag-suggestion-panel');
+    const list=suggestions.querySelector('#tag-suggestions'),status=suggestions.querySelector('#tag-generation-status');
+    const count=suggestions.querySelector('#suggestion-count');
+    const actions=body.querySelector('.dialog-actions');
+    // A suggestion is a concept checkbox row (`label.tag-suggestion`) or a production chip (`span.chip.tag-suggestion`).
+    const rows=[...list.querySelectorAll('.tag-suggestion')].map(row=>{
+        const name=row.querySelector('span:not(.tag-confidence)'),confidence=row.querySelector('.tag-confidence');
+        const checkbox=row.querySelector('input[type=checkbox]'),remove=row.querySelector('button');
+        return {name:name.textContent,confidence:confidence.textContent,
+            control:checkbox?{kind:'checkbox',checked:checkbox.checked}:remove?{kind:'remove',label:remove.getAttribute('aria-label')}:null,
+            ...css(row,'display','alignItems','borderTopColor','backgroundColor','borderTopWidth','borderTopStyle','borderTopLeftRadius','fontSize','paddingTop','paddingLeft'),
+            confidenceToken:css(confidence,'color','fontSize')};
+    });
+    return {
+        dialog:{...css(dialog,'paddingTop','paddingRight','paddingBottom','paddingLeft','borderTopLeftRadius','backgroundColor','color','overflowY'),
+            width:px(dialog.getBoundingClientRect().width),modal:dialog.matches(':modal'),tagging:dialog.classList.contains('tagging-modal'),
+            labelledBy:document.getElementById(dialog.getAttribute('aria-labelledby'))===title,
+            noHorizontalOverflow:dialog.scrollWidth<=dialog.clientWidth+1},
+        header:{title:{text:title.textContent,...font(title)},close:{label:close.getAttribute('aria-label'),text:close.textContent.trim()}},
+        demo:body.querySelector('.demo-note')?.textContent??null,
+        order:[...body.children].map(node=>node.className),
+        heading:{...css(heading,'display','columnGap','alignItems','marginBottom'),
+            preview:{tag:preview.tagName.toLowerCase(),alt:preview.getAttribute('alt'),...box(preview),...css(preview,'objectFit','borderTopLeftRadius','borderTopWidth','borderTopStyle','borderTopColor','flexShrink')},
+            h3:{text:copy.querySelector('h3').textContent,...font(copy.querySelector('h3'))},
+            filename:{text:copy.querySelector('p.small').textContent,...font(copy.querySelector('p.small'))},
+            size:sizeChip?{text:sizeChip.textContent,...css(sizeChip,'marginTop','fontSize','borderTopColor','borderTopLeftRadius','paddingLeft')}:null},
+        scopeNote:note?{text:note.textContent,...edges(note),...css(note,'borderLeftWidth','borderLeftStyle','borderLeftColor','fontSize','color')}:null,
+        manual:{...fieldOf(manualField),help:{text:help.textContent,...font(help)},described:help.id===manual.getAttribute('aria-describedby')},
+        modelPanel:{...edges(panel),...css(panel,'marginTop'),h3:{text:panel.querySelector('h3').textContent,...font(panel.querySelector('h3'))},
+            fields:[...panel.querySelectorAll('.field')].map(fieldOf),
+            twoCol:options.querySelector('.two-col')?{columns:getComputedStyle(options.querySelector('.two-col')).gridTemplateColumns.split(' ').length,
+                ...css(options.querySelector('.two-col'),'display','columnGap')}:null,
+            generate:buttonOf(generate)},
+        suggestions:{labelled:suggestions.getAttribute('aria-labelledby')===suggestions.querySelector('h3').id,...css(suggestions,'marginTop'),
+            title:{text:suggestions.querySelector('h3').textContent,...font(suggestions.querySelector('h3'))},
+            count:{text:count.textContent,...font(count)},
+            copy:list.querySelector(':scope > p.small')?.textContent??null,
+            rows,
+            status:{text:status.textContent,role:status.getAttribute('role'),...css(status,'marginTop','fontSize','color')}},
+        actions:{...css(actions,'position','bottom','marginLeft','marginRight','marginBottom','paddingTop','paddingLeft','backgroundColor',
+            'borderTopWidth','borderTopStyle','borderTopColor','zIndex','display','justifyContent','columnGap'),
+            buttons:[...actions.querySelectorAll('button')].map(buttonOf)},
+        noPageScroll:document.documentElement.scrollWidth<=innerWidth+1,
+    };
+}
+
+/** The first image card's Info and Tag group (M1), with its card's filename. */
+export function cardActionsInventory(card) {
+    const css=(node,...keys)=>{const style=getComputedStyle(node);return Object.fromEntries(keys.map(key=>[key,style[key]]));};
+    const info=card.querySelector('.media-info'),actions=info.querySelector(':scope > .image-card-actions');
+    return {
+        info:css(info,'display','justifyContent','alignItems','columnGap'),
+        actions:{...css(actions,'display','alignItems','columnGap','flexShrink','minWidth'),lastInInfo:info.lastElementChild===actions},
+        buttons:[...actions.querySelectorAll(':scope > button')].map(node=>{const rect=node.getBoundingClientRect();return {
+            className:node.className,label:node.getAttribute('aria-label'),icon:node.querySelector('svg')?.innerHTML.replace(/\s+/g,' ').trim()??null,
+            width:Math.round(rect.width),height:Math.round(rect.height),
+            ...css(node,'minWidth','minHeight','paddingLeft','paddingTop','borderTopLeftRadius','borderTopColor','backgroundColor','color')};}),
+    };
+}
+
+// D84 (plan D61): the legacy engines' values, labels and sizes, GGUF JoyCaption in the concept's Ollama slot.
+const MODEL_LABELS=Object.freeze({'wd14-swinv2':['wd14-swinv2','WD14 SwinV2 · ~400 MB'],'wd14-vit':['wd14-vit','WD14 ViT · ~400 MB'],
+    ollama:['gguf','GGUF JoyCaption (Recommended) · ~4.5 GB'],huggingface:['hf','HuggingFace JoyCaption · ~16 GB']});
+const CONCEPT_LABELS=Object.freeze({'WD14 SwinV2 · fast classifier':'WD14 SwinV2 · ~400 MB','WD14 ViT · visual tags':'WD14 ViT · ~400 MB',
+    'Ollama · local language model':'GGUF JoyCaption (Recommended) · ~4.5 GB','HuggingFace · language model':'HuggingFace JoyCaption · ~16 GB'});
+
+/**
+ * The concept inventory with the recorded deviations applied:
+ * - no prototype note (Global Constraints: `Prototype · suggestions are simulated…` is not shipped);
+ * - D83 (ruling T4): while suggestions exist, "Remove anything you do not want to add." leads them, and every
+ *   suggestion is a chip with a `Remove <name>` × instead of a checked checkbox row: the concept's own `.chip` corner
+ *   (`chip`: a concept `.chip` inventory, the heading's size chip) around the row's own text (12px) in the checked
+ *   row's colours (accent border, `--soft-blue`);
+ * - D84 (plan D61): the legacy engine labels and values, and the server's default instructions (`instructions`);
+ * - D91 (plan D68): a Suggestions count field after the model's own fields, on the concept's number field tokens
+ *   (`numberField`: the concept's General confidence field) with the configured count (`limit`);
+ * - D29: the prototype's "Sample suggestions from …" status reads "Suggestions from …".
+ * The opened state is compared unmapped: both show the concept's on-screen "Generate suggestions with the selected
+ * model before approving." (its renderTagModelOptions, a1062–1076, replaces the markup's sentence at once).
+ */
+export function mapConceptTagging(reference,{instructions,limit=10,chip,numberField}) {
+    const [select,...own]=reference.modelPanel.fields;
+    const suggestionsField={...numberField,label:'Suggestions',control:{...numberField.control,id:'image-suggestion-limit',
+        value:String(limit),min:'1',max:'100',step:'1'}};
+    const mappedOwn=own.map(field=>field.control.id==='image-tag-instructions'?{...field,control:{...field.control,value:instructions}}:field);
+    const rows=reference.suggestions.rows.map(row=>({...row,
+        control:row.control?.kind==='checkbox'&&row.control.checked?{kind:'remove',label:`Remove ${row.name}`}:row.control,
+        borderTopLeftRadius:chip.borderTopLeftRadius}));
+    const copy=rows.length&&reference.suggestions.copy===null?'Remove anything you do not want to add.':reference.suggestions.copy;
+    const status=reference.suggestions.status.text.replace(/^Sample suggestions from (.+)\. Approve tags to save\.$/,
+        (_,label)=>`Suggestions from ${CONCEPT_LABELS[label]??label}. Approve tags to save.`);
+    return {...reference,
+        demo:null,
+        order:reference.order.filter(name=>name!=='demo-note'),
+        modelPanel:{...reference.modelPanel,
+            fields:[{...select,control:{...select.control,value:MODEL_LABELS[select.control.value]?.[0]??select.control.value,
+                options:select.control.options.map(([value])=>MODEL_LABELS[value])}},...mappedOwn,suggestionsField]},
+        suggestions:{...reference.suggestions,copy,rows,status:{...reference.suggestions.status,text:status}},
+    };
+}
+
+/**
+ * Production's own chip geometry beyond the concept's `.chip` (D83): the chip's padding hugs its × button. Only the
+ * leaves D83 replaces are dropped from both sides; names, confidences, colours, radius and font stay compared.
+ */
+export function withoutChipGeometry(inventory) {
+    return {...inventory,suggestions:{...inventory.suggestions,rows:inventory.suggestions.rows.map(({paddingTop,paddingLeft,alignItems,...row})=>row)}};
+}

tests/browser/tagging-concept.spec.mjs

@@ -0,0 +1,307 @@
+// The Tag image dialog and the card's Info and Tag group against the approved concept (#249 PR C, plan Task C4, Mock
+// inventory M1 and M2). Production runs on the concept-shaped fixture with the concept image's own tags saved as its
+// image tags and the injected fake model answering the concept's own sample (alpine: mountain 98%, observatory 95%,
+// snow 88%, blue_hour 81%), so every remaining difference is a recorded deviation applied by mapConceptTagging
+// (D29, D83, D84, D91) or a test failure. No model is ever downloaded: every test checks no download request was sent.
+import { test, expect } from './fixtures.mjs';
+import { seedConcept, openConcept, openProduction, saveImageTags, mutate, SIZES, THEMES } from './concept-inventory.mjs';
+import { taggingInventory, cardActionsInventory, mapConceptTagging, diffTaggingInventory, withoutChipGeometry } from './tagging-canonical-comparison.mjs';
+
+const MODULE = '/prompt_manager/js/workspace/image-tagging.mjs';
+// The concept's first image (app.js images[0]) and its sample suggestions (generateTags, scene "alpine").
+const CONCEPT_FILE = 'alpine_00001.png';
+const CONCEPT_TAGS = ['cinematic', 'blue_hour', 'architecture'];
+const ALPINE = [['mountain', 0.98], ['observatory', 0.95], ['snow', 0.88], ['blue_hour', 0.81]];
+// The fake model's server default instructions (tests/browser/server.py TestModel.default_prompt), D84.
+const INSTRUCTIONS = 'Describe the image';
+const CONCEPT_MODEL = { gguf: 'ollama' };
+
+const tagDialog = page => page.getByRole('dialog', { name: 'Tag image', exact: true });
+const firstCard = (page, side) => page.locator(side === 'concept' ? '#image-grid > article.media-card' : '#workspace-main article[data-image-key]').first();
+
+test.beforeEach(async ({ page, request }) => {
+    const manifest = await seedConcept(request);
+    expect(manifest).toBeTruthy();
+    await expect(await request.post('/__test__/tagging/suggestions', { data: { scored: ALPINE } })).toBeOK();
+    page.downloads = [];
+    page.on('request', item => { if (/\/autotag\/download\//.test(item.url())) page.downloads.push(item.url()); });
+    page.errors = [];
+    page.on('pageerror', error => page.errors.push(error.message));
+});
+test.afterEach(async ({ page, request }) => {
+    await leave(page);
+    expect(page.downloads).toEqual([]);
+    expect(page.errors).toEqual([]);
+    await request.post('/__test__/tagging/suggestions', { data: { scored: null } });
+});
+
+async function conceptPath(request) {
+    const listing = await (await request.get('/prompt_manager/images/output?mode=workspace&limit=40')).json();
+    const image = listing.images.find(item => item.filename === CONCEPT_FILE);
+    expect(image).toBeTruthy();
+    return image.path;
+}
+
+/**
+ * Close an open Tag dialog before opening the next page, so each comparison starts from a settled page. Leaving with
+ * the dialog open is covered on its own (workspace-tagging-lifecycle.spec.mjs: the keepalive release on pagehide).
+ */
+async function leave(page) {
+    if (await tagDialog(page).count()) {
+        await page.keyboard.press('Escape');
+        await expect(tagDialog(page)).toHaveCount(0);
+    }
+}
+/** Open `side`'s Tag image dialog from its first card, settled (production: the capture preview and saved tags). */
+async function openTagDialog(page, side, theme) {
+    await leave(page);
+    if (side === 'concept') await openConcept(page, 'images', theme);
+    else await openProduction(page, 'images', theme);
+    await firstCard(page, side).getByRole('button', { name: `Tag or auto-tag ${CONCEPT_FILE}`, exact: true }).click();
+    await expect(tagDialog(page)).toBeVisible();
+    await settled(page, side);
+}
+async function settled(page, side) {
+    if (side === 'production') {
+        await expect(tagDialog(page).locator('img.tag-image-preview')).toHaveAttribute('src', /\/image-annotations\/capture\//);
+        await expect(tagDialog(page).locator('#manual-image-tags')).toHaveValue(CONCEPT_TAGS.join(', '));
+    }
+    await page.evaluate(async () => {
+        await document.fonts.ready;
+        await Promise.all([...document.querySelectorAll('#modal img')].map(image => image.decode().catch(() => {})));
+    });
+}
+async function generateWith(page, side, model) {
+    const select = tagDialog(page).getByRole('combobox', { name: 'Tagging model', exact: true });
+    if (model) await select.selectOption(side === 'concept' ? CONCEPT_MODEL[model] ?? model : model);
+    await tagDialog(page).getByRole('button', { name: 'Generate suggestions', exact: true }).click();
+    await expect(tagDialog(page).locator('#suggestion-count')).not.toHaveText('Not generated');
+}
+// The pointer rests outside the dialog, so no control is measured in its hover state.
+const inventory = async page => {
+    await page.mouse.move(0, 0);
+    return page.locator('dialog#modal').evaluate(taggingInventory);
+};
+
+/** The concept and production inventories of one dialog state, the concept mapped (D29, D83, D84, D91). */
+async function compareState(page, { theme, act = async () => {} }) {
+    await openTagDialog(page, 'concept', theme);
+    const conceptOpened = await inventory(page);
+    await act(page, 'concept');
+    const concept = await inventory(page);
+    await openTagDialog(page, 'production', theme);
+    await act(page, 'production');
+    const actual = await inventory(page);
+    const numberField = conceptOpened.modelPanel.fields.find(field => field.control.id === 'image-general-threshold');
+    const reference = mapConceptTagging(concept, { instructions: INSTRUCTIONS, chip: concept.heading.size, numberField });
+    return { reference: withoutChipGeometry(reference), actual: withoutChipGeometry(actual) };
+}
+
+for (const [width, height] of SIZES) for (const theme of THEMES) {
+    test(`concept and production Tag dialog match at ${width}x${height} ${theme}`, async ({ page, request }) => {
+        test.setTimeout(90_000);
+        await saveImageTags(request, await conceptPath(request), CONCEPT_TAGS);
+        await page.setViewportSize({ width, height });
+        // Opened, generated with WD14 (the concept's default), then generated with a language model.
+        for (const [state, act] of [
+            ['opened', async () => {}],
+            ['generated WD14', (page, side) => generateWith(page, side)],
+            ['generated GGUF', (page, side) => generateWith(page, side, 'gguf')],
+        ]) {
+            const { reference, actual } = await compareState(page, { theme, act });
+            expect(diffTaggingInventory(reference, actual), `${state} at ${width}x${height} ${theme}`).toEqual([]);
+        }
+        // Pinned concept geometry (M2), so a mapping mistake on both sides cannot pass unseen.
+        const { actual } = await compareState(page, { theme, act: (page, side) => generateWith(page, side) });
+        const small = width <= 700;
+        expect([actual.heading.preview.width, actual.heading.preview.height]).toEqual(small ? [86, 86] : [112, 100]);
+        expect(actual.heading.columnGap).toBe('16px');
+        expect([actual.modelPanel.paddingTop, actual.modelPanel.borderTopLeftRadius]).toEqual(['16px', '6px']);
+        expect(actual.actions.position).toBe('sticky');
+        expect(actual.suggestions.rows.map(row => [row.name, row.confidence, row.control.label])).toEqual(
+            ALPINE.map(([name, confidence]) => [name, `${Math.round(confidence * 100)}%`, `Remove ${name}`]));
+        const accent = await page.evaluate(() => {
+            const probe = document.createElement('i');
+            probe.style.cssText = 'border-top:1px solid var(--ca-accent);background:var(--soft-blue)';
+            document.body.append(probe);
+            const style = getComputedStyle(probe), tokens = [style.borderTopColor, style.backgroundColor];
+            probe.remove();
+            return tokens;
+        });
+        for (const row of actual.suggestions.rows) expect([row.borderTopColor, row.backgroundColor]).toEqual(accent);
+        expect(actual.dialog.noHorizontalOverflow).toBe(true);
+        expect(actual.noPageScroll).toBe(true);
+    });
+}
+
+test('an empty result matches the concept below its threshold', async ({ page, request }) => {
+    await saveImageTags(request, await conceptPath(request), CONCEPT_TAGS);
+    await expect(await request.post('/__test__/tagging/suggestions', { data: { scored: [] } })).toBeOK();
+    const { reference, actual } = await compareState(page, { theme: 'dark', act: async (page, side) => {
+        // The concept filters its sample by the General confidence; above every sample nothing is shown.
+        if (side === 'concept') await tagDialog(page).getByRole('spinbutton', { name: 'General confidence', exact: true }).fill('1');
+        await generateWith(page, side);
+        if (side === 'concept') await tagDialog(page).getByRole('spinbutton', { name: 'General confidence', exact: true }).fill('0.35');
+    } });
+    expect(actual.suggestions.copy).toBe('No suggestions met this threshold. Adjust it or enter tags manually.');
+    expect(diffTaggingInventory(reference, actual)).toEqual([]);
+});
+
+test('review-scoped dialog shows the scope note', async ({ page, request }) => {
+    const path = await conceptPath(request);
+    await saveImageTags(request, path, CONCEPT_TAGS);
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await openConcept(page, 'review', 'dark');
+    await page.locator('#main section.surface').getByRole('button', { name: 'Tag image', exact: true }).click();
+    await expect(tagDialog(page)).toBeVisible();
+    await settled(page, 'concept');
+    const opened = await inventory(page);
+    // Needs review ships with PR F; until then the review source opens the same dialog from the module.
+    await leave(page);
+    await openProduction(page, 'images', 'dark');
+    await page.evaluate(async ({ module, path }) => {
+        const { openImageTagging } = await import(module);
+        const { createScope } = await import('/prompt_manager/js/shared/toolkit/core.js');
+        const api = window.ApiClient.createApiClient();
+        const listing = await api.get('/prompt_manager/images/output?mode=workspace&limit=40');
+        openImageTagging({ api, scope: createScope(), image: listing.images.find(item => item.path === path), source: 'review' });
+    }, { module: MODULE, path });
+    await expect(tagDialog(page)).toBeVisible();
+    await settled(page, 'production');
+    const actual = await inventory(page);
+    expect(actual.scopeNote.text).toBe('Tags belong to this image. Resolve its prompt association separately in Needs review.');
+    expect(actual.order).toEqual(['tag-image-heading', 'tag-scope-note small', 'field', 'tag-model-panel', 'tag-suggestion-panel', 'dialog-actions']);
+    const numberField = opened.modelPanel.fields.find(field => field.control.id === 'image-general-threshold');
+    const reference = mapConceptTagging(opened, { instructions: INSTRUCTIONS, chip: opened.heading.size, numberField });
+    expect(diffTaggingInventory(reference, actual)).toEqual([]);
+});
+
+for (const [width, height] of SIZES) test(`card action group matches M1 at ${width}x${height}`, async ({ page }) => {
+    await page.setViewportSize({ width, height });
+    await openConcept(page, 'images', 'dark');
+    const reference = await firstCard(page, 'concept').evaluate(cardActionsInventory);
+    await openProduction(page, 'images', 'dark');
+    const actual = await firstCard(page, 'production').evaluate(cardActionsInventory);
+    expect(actual.buttons.map(button => button.label)).toEqual([`Inspect ${CONCEPT_FILE}`, `Tag or auto-tag ${CONCEPT_FILE}`]);
+    expect(diffTaggingInventory(reference, actual)).toEqual([]);
+});
+
+test('the comparison notices a changed panel border or primary label', async ({ page, request }) => {
+    await saveImageTags(request, await conceptPath(request), CONCEPT_TAGS);
+    const { reference, actual } = await compareState(page, { theme: 'dark' });
+    expect(diffTaggingInventory(reference, actual)).toEqual([]);
+    const undo = await mutate(page, { css: '.tag-model-panel { border: 0 !important; }' });
+    const borderless = withoutChipGeometry(await inventory(page));
+    expect(diffTaggingInventory(reference, borderless).map(item => item.path)).toEqual(
+        expect.arrayContaining(['modelPanel.borderTopWidth', 'modelPanel.borderTopStyle']));
+    await undo();
+    await tagDialog(page).locator('.dialog-actions .ca-primary').evaluate(node => { node.textContent = 'Save'; });
+    const relabelled = withoutChipGeometry(await inventory(page));
+    expect(diffTaggingInventory(reference, relabelled).map(item => item.path)).toEqual(['actions.buttons.1.text']);
+});
+
+// Paired captures for the PR (no screenshot baselines): every production state beside the concept's nearest one. The
+// states the concept lacks (unavailable model, saving, conflict, file changed) pair with the concept's opened dialog.
+test('paired Tag dialog captures', async ({ page, request }, testInfo) => {
+    test.setTimeout(120_000);
+    const path = await conceptPath(request);
+    await saveImageTags(request, path, CONCEPT_TAGS);
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const shot = async name => {
+        await page.evaluate(async () => { await document.fonts.ready; await Promise.all([...document.images].map(image => image.decode().catch(() => {}))); });
+        const file = testInfo.outputPath(`${name}.png`);
+        await page.screenshot({ path: file });
+        await testInfo.attach(name, { path: file, contentType: 'image/png' });
+    };
+    const both = async (name, act) => {
+        for (const side of ['concept', 'production']) {
+            await openTagDialog(page, side, 'dark');
+            await act(page, side);
+            await shot(`${side}-${name}`);
+        }
+    };
+    await both('opened', async () => {});
+    await both('generated-wd14', (page, side) => generateWith(page, side));
+    await both('generated-gguf', (page, side) => generateWith(page, side, 'gguf'));
+    await expect(await request.post('/__test__/tagging/suggestions', { data: { scored: [] } })).toBeOK();
+    await both('empty', async (page, side) => {
+        if (side === 'concept') await tagDialog(page).getByRole('spinbutton', { name: 'General confidence', exact: true }).fill('1');
+        await generateWith(page, side);
+    });
+    await expect(await request.post('/__test__/tagging/suggestions', { data: { scored: ALPINE } })).toBeOK();
+    const save = () => tagDialog(page).locator('.dialog-actions .ca-primary').click();
+    const status = () => tagDialog(page).locator('#tag-generation-status');
+
+    // Unavailable model.
+    await expect(await request.post('/__test__/tagging/models', { data: { unavailable: ['wd14-swinv2'] } })).toBeOK();
+    await openTagDialog(page, 'production', 'dark');
+    await generateWith(page, 'production').catch(() => {});
+    await expect(status()).toHaveText('WD14 SwinV2 is not downloaded. Download it from the legacy Auto-tag page.');
+    await shot('production-unavailable');
+    await expect(await request.post('/__test__/tagging/models', { data: { unavailable: [] } })).toBeOK();
+
+    // Saving: the write is held until the capture is taken.
+    let release;
+    const held = new Promise(resolve => { release = resolve; });
+    const writes = url => url.pathname === '/prompt_manager/image-annotations/tags';
+    await page.route(writes, async route => { await held; await route.continue(); });
+    await openTagDialog(page, 'production', 'dark');
+    const sent = page.waitForRequest(item => writes(new URL(item.url())));
+    await save();
+    await sent;
+    await expect(tagDialog(page).locator('.dialog-actions .ca-primary')).toHaveAttribute('aria-disabled', 'true');
+    await shot('production-saving');
+    release();
+    await expect(tagDialog(page)).toHaveCount(0);
+    await page.unroute(writes);
+
+    // Conflict: another writer saved this file's set after the dialog observed it.
+    await openTagDialog(page, 'production', 'dark');
+    await saveImageTags(request, path, ['changed_elsewhere']);
+    await save();
+    await expect(status()).not.toHaveText('');
+    await shot('production-conflict');
+    await page.keyboard.press('Escape');
+
+    // File changed: the server's own envelope for bytes replaced after the preview (B1 `file-changed`).
+    await page.route(writes, route => route.fulfill({ status: 409, contentType: 'application/json',
+        body: JSON.stringify({ success: false, code: 'file-changed', error: 'The file changed since it was previewed. Reopen the Tag dialog.' }) }));
+    await saveImageTags(request, path, CONCEPT_TAGS);
+    await openTagDialog(page, 'production', 'dark');
+    await save();
+    await expect(status()).not.toHaveText('');
+    await shot('production-file-changed');
+    await page.unroute(writes);
+    await page.keyboard.press('Escape');
+
+    // Unconfirmed save (a 504): D116's Retry leads the actions, before Cancel and the disabled primary.
+    await page.route(writes, route => route.fulfill({ status: 504, body: 'Gateway Timeout' }));
+    await openTagDialog(page, 'production', 'dark');
+    await save();
+    await expect(status()).toHaveText('The save could not be confirmed. Retry sends the same tags again.');
+    expect((await inventory(page)).actions.buttons.map(button => [button.text, button.primary, button.disabled])).toEqual(
+        [['Retry', false, false], ['Cancel', false, false], ['Save manual tags', true, true]]);
+    await shot('production-unknown-outcome');
+    await page.unroute(writes);
+    await page.keyboard.press('Escape');
+
+    // Review scope: the concept's Needs review dialog and production's review-sourced dialog.
+    await leave(page);
+    await openConcept(page, 'review', 'dark');
+    await page.locator('#main section.surface').getByRole('button', { name: 'Tag image', exact: true }).click();
+    await expect(tagDialog(page)).toBeVisible();
+    await shot('concept-review');
+    await leave(page);
+    await openProduction(page, 'images', 'dark');
+    await page.evaluate(async ({ module, path }) => {
+        const { openImageTagging } = await import(module);
+        const { createScope } = await import('/prompt_manager/js/shared/toolkit/core.js');
+        const api = window.ApiClient.createApiClient();
+        const listing = await api.get('/prompt_manager/images/output?mode=workspace&limit=40');
+        openImageTagging({ api, scope: createScope(), image: listing.images.find(item => item.path === path), source: 'review' });
+    }, { module: MODULE, path });
+    await expect(tagDialog(page).locator('.tag-scope-note')).toBeVisible();
+    await settled(page, 'production');
+    await shot('production-review');
+    await leave(page);
+});

tests/browser/vocabulary-canonical-comparison.mjs

@@ -64,12 +64,10 @@ export function pageInventoryOf(main) {
 // Recorded deviations only (plan "Mock inventory" + decisions D1-D15 + ledger rulings). Everything else must be equal.
 export function mapVocabularyConcept(reference) {
     return {...reference,
-        heading:{...reference.heading,actions:{...reference.heading.actions,
-            // D2: Auto-tag images is omitted until the image-annotation slice owns image tags.
-            buttons:reference.heading.actions.buttons.filter(item=>item.text!=='Auto-tag images')}},
         table:{...reference.table,rows:reference.table.rows.map(row=>({...row,
-            // D3: no image-tag owner yet, so the Images cell shows "—" with a visually hidden "Not available yet".
-            images:'—',imagesHidden:'Not available yet'}))},
+            // Data, not a deviation: the concept tags each sample image with its prompt's tags; the vocabulary fixture
+            // tags no image, so every Images count is 0 (#249 C2 retired #245 D3).
+            images:'0'}))},
         operations:reference.operations.map(row=>({...row,p:{...row.p,
             // Ledger ruling: "1 positive prompts" -> singular, consistent with the shared plural helper (#238/#243).
             text:row.p.text.replace(/^1 positive prompts$/,'1 positive prompt')}})),

tests/browser/vocabulary-visual.spec.mjs

@@ -1,4 +1,4 @@
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 import {captureCanonicalState} from './history-canonical-comparison.mjs';
 
 // Artifact-only captures of Tags & categories states that have no concept counterpart: the Manage categories

tests/browser/worker-server.spec.mjs

@@ -0,0 +1,35 @@
+// Each Playwright worker owns its server: `request`, `page` and manual
+// `browser.newContext()` all reach it through `baseURL`, and another server
+// process never sees its database.
+import { test, expect } from './fixtures.mjs';
+import { startBrowserServer } from '../../tools/vendor/start-browser-server.mjs';
+
+const search = text => `/prompt_manager/search?text=${encodeURIComponent(text)}`;
+
+test('every fixture reaches this worker\'s own server and another server keeps its own database', async ({ request, page, browser, baseURL, workerServer }, testInfo) => {
+    expect(baseURL).toBe(workerServer.url);
+    await expect(await request.post('/__test__/reset')).toBeOK();
+    const marker = `worker ${testInfo.workerIndex} isolation ${testInfo.project.name} ${testInfo.repeatEachIndex}`;
+    await expect(await request.post('/prompt_manager/save', { data: { text: marker } })).toBeOK();
+    expect((await (await request.get(search(marker))).json()).count).toBe(1);
+
+    const viaPage = await page.request.get(search(marker));
+    expect(viaPage.url().startsWith(`${baseURL}/`)).toBe(true);
+    expect((await viaPage.json()).count).toBe(1);
+    const context = await browser.newContext();
+    try {
+        const response = await (await context.newPage()).goto(search(marker));
+        expect(response.url().startsWith(`${baseURL}/`)).toBe(true);
+        expect((await response.json()).count).toBe(1);
+    } finally {
+        await context.close();
+    }
+
+    const other = await startBrowserServer();
+    try {
+        expect(other.url).not.toBe(baseURL);
+        expect((await (await fetch(`${other.url}${search(marker)}`)).json()).count).toBe(0);
+    } finally {
+        await other.stop();
+    }
+});

tests/browser/workflows.spec.mjs

@@ -1,5 +1,5 @@
 import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
-import { test, expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import { test, expect } from './fixtures.mjs';
 
 test.beforeEach(async ({ request, page, browserName }) => {
     await startCoverage(page, browserName);
@@ -64,11 +64,16 @@ test('actual Tags page reloads the selected filter and opens its image viewer',
     await page.goto('/prompt_manager/admin#/tags');
     await page.locator('[data-tag-name="cats"]').click();
     await expect(page.locator('#tagPromptsGrid')).toContainText('Cat portrait');
+    const dogs = page.waitForResponse(response => response.url().includes('/tags/dogs/prompts?'));
     await page.locator('[data-tag-name="dogs"]').click();
+    const [shown] = (await (await dogs).json()).prompts[0].images;
     await expect(page.locator('#tagPromptsGrid')).toContainText('Dog landscape');
     await expect(page.locator('#tagPromptsGrid')).not.toContainText('Cat portrait');
     await page.locator('#tagPromptsGrid img').first().click();
     await expect(page.locator('.viewer-canvas img')).toBeVisible();
+    // The viewer's title names the shown image through the page's title callback. ViewerJS renders it only once the
+    // image is viewed, so closing at "visible" alone left the callback unrun on slower hosts (CI coverage missed it).
+    await expect(page.locator('.viewer-title')).toHaveText(shown.filename);
     await page.locator('.viewer-container').getByRole('button', { name: 'Close', exact: true }).click();
     await expect(page.locator('.viewer-container')).toHaveCount(0);
 });

tests/browser/workspace-activity.spec.mjs

@@ -0,0 +1,801 @@
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { seedConcept, openConcept, openProduction } from './concept-inventory.mjs';
+
+// Activity (#249 Activity-1): the concept's Activity page (app.js renderActivity 732–738), its top-bar button
+// (index.html 51–52) and sidebar row (app.js ~341), with the recorded D52 (counts of running jobs), D53 (the progress
+// pill) and D54 (real job items). Fake jobs come from tests/browser/workspace_activity_fixture.py.
+const workspace = '/prompt_manager/workspace';
+const main = page => page.locator('#workspace-main');
+const pill = page => page.locator('.top-actions #activity-pill');
+const activityButton = page => page.locator('.top-actions button#activity-open');
+const topCount = page => page.locator('#activity-count');
+const navRow = page => page.locator('#system-nav a[data-route="activity"]');
+const toast = page => page.locator('#workspace-toast');
+const items = page => main(page).locator('section.surface > .activity-item');
+const LOST = 'This job ended when ComfyUI restarted.';
+// The job view (Task 3, D56): the page heading, then the Progress and Results surfaces and the Scan log.
+const heading = page => main(page).locator(':scope > .heading');
+const progressSection = page => main(page).getByRole('region', { name: 'Progress', exact: true });
+const resultsSection = page => main(page).getByRole('region', { name: 'Results', exact: true });
+const tiles = page => progressSection(page).locator('dl.stat-row > div.stat');
+const outcomeButtons = page => resultsSection(page).locator('.outcome-list > button');
+const fileRows = page => resultsSection(page).locator('.outcome-files > .file-row');
+const resultsNote = page => resultsSection(page).locator('.outcome-files > p.small');
+const filter = page => resultsSection(page).getByRole('searchbox', { name: 'Filter results', exact: true });
+const scanLog = page => main(page).locator('details.term');
+const TILE_LABELS = ['Added to Library', 'Already known', 'Needs review', 'No usable metadata', 'Errors'];
+const VIEWER_HINT = 'each row opens the image in the viewer';
+
+async function tileValues(page) {
+    return tiles(page).evaluateAll(nodes => nodes.map(node => [node.className, node.querySelector('dt').textContent,
+        node.querySelector('dd').textContent]));
+}
+
+async function openJob(page, id) {
+    await page.goto(`${workspace}#/activity/${id}`);
+    await expect(progressSection(page)).toBeVisible();
+}
+
+async function startJob(request, data = {}) {
+    const response = await request.post('/__test__/jobs/start', { data: { total: 19622, ...data } });
+    await expect(response).toBeOK();
+    return (await response.json()).job;
+}
+
+async function step(request, id, data) {
+    await expect(await request.post(`/__test__/jobs/${id}/step`, { data })).toBeOK();
+}
+
+async function finish(request, id, state = 'finished') {
+    const response = await request.post(`/__test__/jobs/${id}/finish`, { data: { state } });
+    await expect(response).toBeOK();
+    return (await response.json()).job;
+}
+
+async function listed(request) {
+    const response = await request.get('/prompt_manager/jobs');
+    await expect(response).toBeOK();
+    return (await response.json()).jobs;
+}
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    await expect(await request.post('/__test__/reset')).toBeOK();
+    page.activityErrors = [];
+    page.on('pageerror', error => page.activityErrors.push(error.message));
+});
+
+test.afterEach(async ({ page, request, browserName }) => {
+    // The store's own reads can meet a route handler at teardown; that must not fail the test it outlived.
+    await page.unrouteAll({ behavior: 'ignoreErrors' });
+    await saveCoverage(page, browserName);
+    expect(page.activityErrors).toEqual([]);
+    await request.post('/__test__/jobs/restart');
+});
+
+/** The concept's item structure and the computed styles its CSS gives it, measured the same way in both documents. */
+function measureItems(selector) {
+    return [...document.querySelectorAll(selector)].map(item => {
+        const css = (node, ...keys) => node && Object.fromEntries(keys.map(key => [key, getComputedStyle(node)[key]]));
+        const tree = node => ({ tag: node.localName, className: [...node.classList].sort().join(' '), children: [...node.children].map(tree) });
+        const progress = item.querySelector('progress');
+        return {
+            tree: tree(item),
+            title: item.querySelector('h3').textContent,
+            chip: item.querySelector('.chip').textContent,
+            buttons: [...item.querySelectorAll('.row-actions button')].map(button => button.textContent),
+            styles: {
+                item: css(item, 'paddingTop', 'paddingBottom', 'borderBottomWidth', 'borderBottomStyle', 'borderBottomColor'),
+                heading: css(item.querySelector('.panel-heading'), 'display', 'justifyContent', 'alignItems', 'columnGap'),
+                h3: css(item.querySelector('h3'), 'fontSize', 'fontWeight', 'color', 'marginTop', 'marginBottom'),
+                chip: css(item.querySelector('.chip'), 'fontSize', 'color', 'backgroundColor', 'paddingTop', 'paddingLeft', 'borderTopLeftRadius'),
+                p: css(item.querySelector('p'), 'fontSize', 'color', 'marginTop', 'lineHeight'),
+                progress: progress && { ...css(progress, 'height', 'marginTop', 'marginBottom', 'accentColor'),
+                    fills: Math.abs(progress.getBoundingClientRect().width - item.getBoundingClientRect().width) < 1,
+                    max: progress.max, label: Boolean(progress.getAttribute('aria-label')) },
+                actions: css(item.querySelector('.row-actions'), 'display', 'columnGap', 'marginTop'),
+                button: css(item.querySelector('.row-actions button'), 'fontSize', 'paddingTop', 'paddingLeft', 'minHeight', 'borderTopLeftRadius'),
+            },
+        };
+    });
+}
+
+/** D56: an item tree whose `h3` holds the link to the job's view. */
+function withTitleLink(tree) {
+    const [heading, ...rest] = tree.children;
+    const link = { tag: 'a', className: '', children: [] };
+    return { ...tree, children: [{ ...heading, children: heading.children.map(node => node.tag === 'h3' ? { ...node, children: [link] } : node) }, ...rest] };
+}
+
+function measurePage(mainSelector) {
+    const root = document.querySelector(mainSelector);
+    const section = root.querySelector(':scope > section.surface');
+    return {
+        h1: root.querySelector('.heading h1').textContent,
+        description: root.querySelector('.heading p.muted').textContent,
+        actions: [...root.querySelector('.heading .heading-actions').children].map(node => node.textContent),
+        h2: section.querySelector(':scope > h2').textContent,
+        surface: Object.fromEntries(['paddingTop', 'borderTopWidth', 'backgroundColor', 'borderTopLeftRadius']
+            .map(key => [key, getComputedStyle(section)[key]])),
+    };
+}
+
+for (const theme of ['dark', 'light']) test(`activity page matches the concept list markup ${theme}`, async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await seedConcept(request);
+    // The concept: its finished sample, then a running job started from System (startJob, app.js 940–952).
+    await openConcept(page, 'activity', theme);
+    const conceptPage = await page.evaluate(measurePage, '#main');
+    const [conceptDone] = await page.evaluate(measureItems, '#main .activity-item');
+    await page.goto('/__test__/canonical/workspace#system');
+    await page.getByRole('combobox', { name: 'Theme', exact: true }).selectOption(theme);
+    await page.getByRole('button', { name: 'Review thumbnails', exact: true }).click();
+    await expect(page.locator('#main .activity-item progress')).toHaveCount(1);
+    const [conceptRunning] = await page.evaluate(measureItems, '#main .activity-item');
+
+    const done = await startJob(request);
+    await step(request, done.id, { processed: 19622, counters: { added: 1420, errors: 18 } });
+    await finish(request, done.id);
+    const running = await startJob(request);
+    await step(request, running.id, { processed: 8240 });
+    await openProduction(page, 'activity', theme);
+    await expect(items(page)).toHaveCount(2);
+    const productionPage = await page.evaluate(measurePage, '#workspace-main');
+    const [productionRunning, productionDone] = await page.evaluate(measureItems, '#workspace-main .activity-item');
+
+    // D52: no "Unified activity · proposed" chip (prototype copy); the rest of the heading and the section are the concept's.
+    expect(conceptPage.actions).toEqual(['Unified activity · proposed']);
+    expect(productionPage).toEqual({ ...conceptPage, actions: [] });
+    // A completed job is the concept's completed item; D56: its title is a link to the job's view, in the title's colour.
+    expect(conceptDone.title).toBe('✓ Library metadata enriched');
+    expect(productionDone).toEqual({ ...conceptDone, tree: withTitleLink(conceptDone.tree), title: '✓ Scan for metadata' });
+    const links = await items(page).locator('h3 > a').evaluateAll(nodes => nodes.map(node => [node.getAttribute('href'),
+        getComputedStyle(node).color === getComputedStyle(node.parentElement).color, getComputedStyle(node).textDecorationLine]));
+    expect(links).toEqual([[`#/activity/${running.id}`, true, 'none'], [`#/activity/${done.id}`, true, 'none']]);
+    // D54: a running job's chip names its state ("Running", where the concept's sample reads "Needs attention"), and
+    // its actions are Cancel job only (no "Simulate completion").
+    expect(conceptRunning.buttons).toEqual(['Simulate completion', 'Cancel job']);
+    const [, ...cancelOnly] = conceptRunning.tree.children.at(-1).children;
+    const conceptActions = { ...conceptRunning.tree.children.at(-1), children: cancelOnly };
+    expect(productionRunning).toEqual({ ...conceptRunning,
+        tree: withTitleLink({ ...conceptRunning.tree, children: [...conceptRunning.tree.children.slice(0, -1), conceptActions] }),
+        title: '○ Scan for metadata', chip: 'Running', buttons: ['Cancel job'] });
+    await expect(items(page).nth(1).locator('p')).toHaveText(/^Finished \d\d:\d\d · 1,420 added · 18 errors$/);
+    await expect(items(page).first().locator('p')).toHaveText(/^Started \d\d:\d\d · 2 output folders · closing this view does not cancel it$/);
+    await expect(items(page).first().locator('progress')).toHaveAttribute('aria-label', 'Scan for metadata progress');
+    expect(await items(page).first().locator('progress').evaluate(node => node.value)).toBe(41);
+});
+
+test('pill shows while a job runs and opens its view', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await page.goto(`${workspace}#/images`);
+    // D52: no running job, so neither count shows; the button is the concept's.
+    await expect(activityButton(page)).toHaveAccessibleName('Activity');
+    await expect(topCount(page)).toBeHidden();
+    await expect(navRow(page)).toHaveText('Activity');
+    await expect(navRow(page).locator('.nav-count')).toHaveCount(0);
+    await expect(pill(page)).toBeHidden();
+
+    const job = await startJob(request);
+    // The list is read again on its own (15 s), or at once on a reload or when Activity opens.
+    await page.reload();
+    await expect(pill(page)).toBeVisible();
+    await expect(pill(page)).toHaveText('Scanning · 0% · 0 / 19,622');
+    await step(request, job.id, { processed: 8240 });
+    const text = 'Scanning · 41% · 8,240 / 19,622';
+    await expect(pill(page)).toHaveText(text);
+    await expect(pill(page)).toHaveAttribute('aria-label', text);
+    await expect(pill(page)).toHaveAttribute('href', `#/activity/${job.id}`);
+    expect(await pill(page).locator('.activity-pill-bar i').evaluate(node => node.style.width)).toBe('41%');
+    // The pill sits before the button, in the mockup's place, and both counts read 1.
+    expect(await page.locator('.top-actions > *').evaluateAll(nodes => nodes.map(node => node.id || node.className)))
+        .toEqual(['activity-pill', 'activity-open', 'theme-label', 'canvas-link']);
+    await expect(topCount(page)).toBeVisible();
+    await expect(topCount(page)).toHaveText('1');
+    await expect(navRow(page).locator('.nav-count')).toHaveText('1');
+
+    // The pill opens the job's own view (Task 3, D56), named by the job.
+    await pill(page).click();
+    await expect(page).toHaveURL(new RegExp(`#/activity/${job.id}$`));
+    await expect(main(page).getByRole('heading', { level: 1 })).toHaveText('Scan for metadata');
+    await expect(page.locator('#workspace-breadcrumb')).toHaveText('Activity');
+    await expect(page).toHaveTitle('Scan for metadata · Prompt Manager');
+    await expect(navRow(page)).toHaveAttribute('aria-current', 'page');
+    await expect(progressSection(page).locator('progress')).toHaveJSProperty('value', 41);
+
+    // The Activity button opens the list itself from any page.
+    await page.locator('nav [data-route="library"]').click();
+    await activityButton(page).click();
+    await expect(page).toHaveURL(/#\/activity$/);
+    await expect(items(page)).toHaveCount(1);
+
+    await finish(request, job.id);
+    await expect(pill(page)).toBeHidden();
+    await expect(topCount(page)).toBeHidden();
+    await expect(navRow(page).locator('.nav-count')).toHaveCount(0);
+    await expect(items(page).first().locator('.chip.green')).toHaveText('Completed');
+    await expect(items(page).first().locator('progress, .row-actions')).toHaveCount(0);
+    // A finished job's title still opens its view (D56).
+    await items(page).first().locator('h3 > a').click();
+    await expect(page).toHaveURL(new RegExp(`#/activity/${job.id}$`));
+    await expect(heading(page).locator('p.muted')).toHaveText(/^Finished \d\d:\d\d · 0 added · 0 errors$/);
+});
+
+test('a phone keeps the pill and its controls inside the topbar', async ({ page, request }) => {
+    await page.setViewportSize({ width: 390, height: 844 });
+    const job = await startJob(request);
+    await step(request, job.id, { processed: 8240 });
+    await page.goto(`${workspace}#/images`);
+    await expect(pill(page)).toHaveText('Scanning · 41% · 8,240 / 19,622');
+    await expect(pill(page)).toHaveAttribute('aria-label', 'Scanning · 41% · 8,240 / 19,622');
+    await expect(pill(page).locator('.activity-pill-files, .activity-pill-bar')).toHaveCount(2);
+    await expect(pill(page).locator('.activity-pill-files')).toBeHidden();
+    const layout = await page.locator('.top-actions').evaluate(row => ({
+        scroll: document.documentElement.scrollWidth <= document.documentElement.clientWidth,
+        inside: [...row.children].filter(node => node.getBoundingClientRect().width)
+            .every(node => node.getBoundingClientRect().right <= row.getBoundingClientRect().right + 0.5
+                && node.getBoundingClientRect().left >= row.getBoundingClientRect().left - 0.5),
+    }));
+    expect(layout).toEqual({ scroll: true, inside: true });
+});
+
+test('reload during a scan reattaches to the running job', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request);
+    await step(request, job.id, { processed: 1000 });
+    await page.goto(`${workspace}#/activity`);
+    await expect(items(page)).toHaveCount(1);
+    await expect(pill(page)).toHaveText('Scanning · 5% · 1,000 / 19,622');
+    await page.reload();
+    await expect(pill(page)).toHaveText('Scanning · 5% · 1,000 / 19,622');
+    // The reloaded page follows the same job live and started nothing.
+    await step(request, job.id, { processed: 9811 });
+    await expect(pill(page)).toHaveText('Scanning · 50% · 9,811 / 19,622');
+    expect(await items(page).first().locator('progress').evaluate(node => node.value)).toBe(50);
+    await expect(items(page)).toHaveCount(1);
+    expect((await listed(request)).map(item => [item.id, item.state])).toEqual([[job.id, 'running']]);
+
+    // A second tab attaches to the same job and sees the same progress.
+    const other = await page.context().newPage();
+    await other.goto(`${workspace}#/activity`);
+    await expect(pill(other)).toHaveText('Scanning · 50% · 9,811 / 19,622');
+    await expect(other.locator('#workspace-main .activity-item')).toHaveCount(1);
+    await other.close();
+    expect((await listed(request)).length).toBe(1);
+
+    // Cancel job asks the server to stop at a file boundary; the job ends cancelled with its partial counts.
+    await step(request, job.id, { counters: { added: 7 } });
+    await items(page).first().getByRole('button', { name: 'Cancel job', exact: true }).focus();
+    await page.keyboard.press('Enter');
+    await expect(toast(page)).toHaveText('Scan cancelled · 7 added');
+    // The removed Cancel job hands its focus to the item's title link (review M4).
+    await expect(items(page).first().locator('h3 > a')).toBeFocused();
+    await expect(items(page).first().locator('.chip.blue')).toHaveText('Cancelled');
+    await expect(items(page).first().locator('p')).toHaveText(/^Cancelled \d\d:\d\d at a file boundary · 7 added · completed work is kept$/);
+    await expect(pill(page)).toBeHidden();
+});
+
+test('lost server clears the pill and marks jobs ended', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request);
+    await step(request, job.id, { processed: 4000 });
+    await page.goto(`${workspace}#/activity`);
+    await expect(pill(page)).toBeVisible();
+    await expect(topCount(page)).toHaveText('1');
+    const reads = [];
+    page.on('request', item => { if (new URL(item.url()).pathname === '/prompt_manager/jobs') reads.push(Date.now()); });
+    // ComfyUI restarts: the stream drops without a final event and the new registry is empty.
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    await expect(pill(page)).toBeHidden();
+    await expect(topCount(page)).toBeHidden();
+    await expect(items(page).first().locator('.chip.blue')).toHaveText('Ended');
+    await expect(items(page).first().locator('p')).toHaveText(LOST);
+    await expect(items(page).first().locator('progress, .row-actions')).toHaveCount(0);
+    await expect(navRow(page).locator('.nav-count')).toHaveCount(0);
+    // One re-read found the restart; there is no retry storm and no finish toast for a job that only vanished.
+    await page.waitForTimeout(2500);
+    expect(reads.length).toBeLessThanOrEqual(2);
+    await expect(toast(page)).toHaveText('');
+
+    // A server that cannot be read at all also ends the running job, then is read again with a growing backoff.
+    const second = await startJob(request);
+    await page.reload();
+    await expect(pill(page)).toBeVisible();
+    const failed = [];
+    await page.route('**/prompt_manager/jobs**', route => { failed.push(Date.now()); return route.abort(); });
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    await expect(pill(page)).toBeHidden();
+    await expect(items(page).filter({ hasText: LOST })).toHaveCount(1);
+    await page.waitForTimeout(3500);
+    // 1 s, then 2 s: at most two re-reads in 3.5 s.
+    expect(failed.length).toBeLessThanOrEqual(2);
+    await page.unroute('**/prompt_manager/jobs**');
+    expect(second.id).not.toBe(job.id);
+});
+
+test('start and finish toasts', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request);
+    await page.goto(`${workspace}#/images`);
+    await expect(pill(page)).toBeVisible();
+    await step(request, job.id, { processed: 19622, counters: { added: 1420, errors: 18 } });
+    await finish(request, job.id);
+    await expect(toast(page)).toHaveText('Scan finished · 1,420 added · 18 errors');
+    await expect(pill(page)).toBeHidden();
+
+    const single = await startJob(request);
+    await page.reload();
+    await expect(pill(page)).toBeVisible();
+    await step(request, single.id, { processed: 19622, counters: { added: 1, errors: 1 } });
+    await finish(request, single.id, 'failed');
+    await expect(toast(page)).toHaveText('Scan failed · 1 added · 1 error');
+
+    // The store's own start: the real metadata scan over this server's outputs, announced, followed and finished.
+    await page.goto(`${workspace}#/activity`);
+    const started = await page.evaluate(async () => {
+        const { createActivityStore } = await import('/prompt_manager/js/workspace/activity-store.mjs');
+        const controller = new AbortController();
+        const store = createActivityStore({ api: window.ApiClient.createApiClient(), pollMs: 0,
+            scope: { signal: controller.signal, cleanup: () => {} } });
+        const result = await store.start('scan');
+        // Read before the busy attempt: its list read may already see the small scan finished and toast that.
+        const toast = document.getElementById('workspace-toast').textContent;
+        const busy = await store.start('scan').catch(error => ({ error: error.message }));
+        return { id: result.job.id, title: result.job.title, toast, busy: busy.busy?.id ?? null, message: busy.message ?? null };
+    });
+    expect(started.title).toBe('Scan for metadata');
+    expect(started.toast).toBe('Scan started.');
+    // A second start while the scan runs is refused and names it (unless the small fixture scan already ended).
+    if (started.busy !== null) expect(started.busy).toBe(started.id);
+    await expect(toast(page)).toHaveText(/^Scan (started\.|finished · \d+ added · \d+ errors?)$/);
+    await expect.poll(async () => (await listed(request)).find(item => item.id === started.id)?.state, { timeout: 15000 }).toBe('finished');
+});
+
+// ── Task 3: Scan for metadata, its review dialog and the job view ─────────────────────────────
+
+async function startFromImport(page) {
+    await page.goto(`${workspace}#/images`);
+    await page.getByRole('button', { name: 'Import', exact: true }).click();
+    const importDialog = page.getByRole('dialog', { name: 'Import & inspect', exact: true });
+    const row = importDialog.locator('.operation').filter({ hasText: 'Scan for metadata' });
+    await row.getByRole('button', { name: 'Review scan', exact: true }).click();
+    const review = page.getByRole('dialog', { name: 'Review metadata scan', exact: true });
+    await expect(review).toBeVisible();
+    await review.getByRole('button', { name: 'Start scan', exact: true }).click();
+    await expect(review).toHaveCount(0);
+}
+
+test('start scan creates a job, toasts, and opens its view', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const posted = [];
+    page.on('request', item => { if (item.method() === 'POST' && new URL(item.url()).pathname === '/prompt_manager/jobs/scan') posted.push(item); });
+    await startFromImport(page);
+    await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+    const id = page.url().split('/').at(-1);
+    expect(posted).toHaveLength(1);
+    // The fixture scan is small and may already have finished; the start toast came first either way.
+    await expect(toast(page)).toHaveText(/^Scan (started\.|finished · \d+ added · \d+ errors?)$/);
+    await expect(heading(page).locator('h1')).toHaveText('Scan for metadata');
+    await expect(heading(page).locator('h1')).toBeFocused();
+    expect((await listed(request)).map(item => item.id)).toEqual([id]);
+    await expect.poll(async () => (await listed(request))[0].state, { timeout: 15000 }).toBe('finished');
+    await expect(heading(page).locator('p.muted')).toHaveText(/^Finished \d\d:\d\d · \d+ added · \d+ errors?$/);
+    // The finished scan's tiles add up to the files it processed, and its log is there to open.
+    const job = (await listed(request))[0];
+    const values = await tileValues(page);
+    expect(values.map(([, label]) => label)).toEqual(TILE_LABELS);
+    expect(values.reduce((sum, [, , value]) => sum + Number(value.replaceAll(',', '')), 0)).toBe(job.processed);
+    // Opening the log reads its last lines (review M12).
+    await scanLog(page).locator('summary').click();
+    await expect(scanLog(page).locator('pre')).toContainText('Scan finished');
+});
+
+// ── Task 4 (Activity-2): scan scope, new and unresolved files by default ─────────────────────
+
+test('all files checkbox changes the scope line and the request', async ({ page }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const bodies = [];
+    page.on('request', item => {
+        if (item.method() === 'POST' && new URL(item.url()).pathname === '/prompt_manager/jobs/scan') bodies.push(item.postDataJSON());
+    });
+    const review = page.getByRole('dialog', { name: 'Review metadata scan', exact: true });
+    const scopeValue = review.locator('.meta-grid > div').filter({ has: page.locator('dt', { hasText: 'Scope' }) }).locator('dd');
+    // The concept's switch: a checkbox with role=switch.
+    const allFiles = review.getByRole('switch', { name: 'All files', exact: true });
+    const openReview = async () => {
+        await page.goto(`${workspace}#/images`);
+        await page.getByRole('button', { name: 'Import', exact: true }).click();
+        await page.getByRole('dialog', { name: 'Import & inspect', exact: true }).locator('.operation')
+            .filter({ hasText: 'Scan for metadata' }).getByRole('button', { name: 'Review scan', exact: true }).click();
+        await expect(review).toBeVisible();
+    };
+
+    // The default: the concept's "New and unresolved files", the box unchecked; the request asks for "new".
+    await openReview();
+    await expect(scopeValue).toHaveText('New and unresolved files');
+    await expect(allFiles).not.toBeChecked();
+    await expect(review.locator('.setting-row p')).toHaveText('Also read the files already linked to their prompt again.');
+    await expect(allFiles).toHaveAccessibleDescription('Also read the files already linked to their prompt again.');
+    // Checking and unchecking switches the Scope value both ways.
+    await allFiles.check();
+    await expect(scopeValue).toHaveText('All files');
+    await allFiles.uncheck();
+    await expect(scopeValue).toHaveText('New and unresolved files');
+    await review.getByRole('button', { name: 'Start scan', exact: true }).click();
+    await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+    await expect.poll(() => bodies.length).toBe(1);
+    expect(bodies[0]).toEqual({ scope: 'new' });
+    await expect(heading(page).locator('h1')).toHaveText('Scan for metadata');
+    // Wait for the first scan to end so the second is not refused as busy.
+    await scanLog(page).locator('summary').click();
+    await expect(scanLog(page).locator('pre')).toContainText('Scan finished', { timeout: 15000 });
+    await expect(scanLog(page).locator('pre')).toContainText('new and unresolved files');
+
+    // Checked: "All files", and the request asks for "all".
+    await openReview();
+    await allFiles.check();
+    await expect(scopeValue).toHaveText('All files');
+    await review.getByRole('button', { name: 'Start scan', exact: true }).click();
+    await expect.poll(() => bodies.length).toBe(2);
+    expect(bodies[1]).toEqual({ scope: 'all' });
+    await scanLog(page).locator('summary').click();
+    await expect(scanLog(page).locator('pre')).toContainText('Scan started · ', { timeout: 15000 });
+    await expect(scanLog(page).locator('pre')).toContainText('all files');
+});
+
+test('job view counters follow the mapping and update live', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request);
+    await step(request, job.id, { processed: 8240, counters: { added: 1420, known: 6511, review: 37, no_metadata: 254, errors: 18 } });
+    await openJob(page, job.id);
+    // The header: the title, the detail line, then Download report (enabled in Task 5) and Cancel scan (danger).
+    await expect(heading(page).locator('h1')).toHaveText('Scan for metadata');
+    await expect(heading(page).locator('p.muted')).toHaveText(/^Started \d\d:\d\d · 2 output folders · closing this view does not cancel it$/);
+    await expect(heading(page).locator('.heading-actions > button')).toHaveText(['Download report', 'Cancel scan']);
+    await expect(heading(page).getByRole('button', { name: 'Download report', exact: true })).toBeEnabled();
+    await expect(heading(page).getByRole('button', { name: 'Cancel scan', exact: true })).toHaveClass(/danger/);
+    // Progress: the bar, the server's line and the five tiles in order and colour.
+    await expect(progressSection(page).locator('.panel-heading > span.small')).toHaveText('Processing file 8,240 of 19,622');
+    await expect(progressSection(page).locator('progress')).toHaveAttribute('aria-label', 'Scan progress');
+    await expect(progressSection(page).locator('progress')).toHaveJSProperty('value', 41);
+    expect(await tileValues(page)).toEqual([
+        ['stat added', 'Added to Library', '1,420'], ['stat', 'Already known', '6,511'], ['stat warn', 'Needs review', '37'],
+        ['stat', 'No usable metadata', '254'], ['stat bad', 'Errors', '18'],
+    ]);
+    const colours = await tiles(page).evaluateAll(nodes => nodes.map(node => getComputedStyle(node.querySelector('dd')).color));
+    const expected = await page.evaluate(() => ['--green', '--ca-text', '--warning', '--ca-text', '--red'].map(name => {
+        const probe = document.createElement('span');
+        probe.style.color = `var(${name})`;
+        document.querySelector('#workspace-main').append(probe);
+        const colour = getComputedStyle(probe).color;
+        probe.remove();
+        return colour;
+    }));
+    expect([colours[0], colours[2], colours[4]]).toEqual([expected[0], expected[2], expected[4]]);
+    expect(colours[1]).toBe(colours[3]);
+    // The outcome list follows the mockup's order with the same counts.
+    await expect(outcomeButtons(page)).toHaveText(['Added to Library1,420', 'Needs review37', 'Errors18', 'No usable metadata254', 'Already known6,511']);
+
+    // Live: the next step updates the bar, the line and the tiles without a reload.
+    await step(request, job.id, { processed: 9811, counters: { added: 1500, errors: 19 }, records: [
+        { group: 'added', path: 'live/new.png', detail: 'Added to the Library as “Live”' },
+    ] });
+    await expect(progressSection(page).locator('.panel-heading > span.small')).toHaveText('Processing file 9,811 of 19,622');
+    await expect(progressSection(page).locator('progress')).toHaveJSProperty('value', 50);
+    await expect(tiles(page).first().locator('dd')).toHaveText('1,500');
+    await expect(tiles(page).last().locator('dd')).toHaveText('19');
+    await expect(fileRows(page)).toHaveCount(1);
+    // A focused row keeps its focus while later reads append rows.
+    await fileRows(page).first().focus();
+    await step(request, job.id, { records: [{ group: 'added', path: 'live/next.png', detail: 'Added' }] });
+    await expect(fileRows(page)).toHaveCount(2);
+    await expect(fileRows(page).first()).toBeFocused();
+    // The log is collapsed by default and holds the raw timestamped lines.
+    await expect(scanLog(page)).not.toHaveAttribute('open', '');
+    await expect(scanLog(page).locator('summary')).toContainText('Scan log');
+    await scanLog(page).locator('summary').click();
+    await expect(scanLog(page).locator('pre')).toHaveAttribute('tabindex', '0');
+    await expect(scanLog(page).locator('pre')).toHaveText(/^\d\d:\d\d:\d\d \+ live\/new\.png · Added to the Library as “Live”\n\d\d:\d\d:\d\d \+ live\/next\.png · Added$/);
+
+    // Finished: the header says so, Cancel scan is gone and the counters stay.
+    await finish(request, job.id);
+    await expect(heading(page).locator('p.muted')).toHaveText(/^Finished \d\d:\d\d · 1,501 added · 19 errors$/);
+    await expect(heading(page).locator('.heading-actions > button')).toHaveText(['Download report']);
+    await expect(tiles(page).first().locator('dd')).toHaveText('1,501');
+});
+
+test('added rows open the viewer, error rows are plain', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request);
+    // The fixture's two listed files share a name in the output and input roots; the row's root label tells them apart.
+    await step(request, job.id, { processed: 3, records: [
+        { group: 'added', path: 'shared/same.png', root: 'output', detail: 'Added to the Library as “Cat portrait”' },
+        { group: 'known', path: 'shared/same.png', root: 'input', detail: 'Already linked to “Dog portrait”' },
+        { group: 'errors', path: 'broken/truncated.png', root: 'output', detail: 'Error: the file could not be processed (see the server log)' },
+    ] });
+    await openJob(page, job.id);
+    await expect(outcomeButtons(page).first()).toHaveAttribute('aria-pressed', 'true');
+    await expect(fileRows(page)).toHaveCount(1);
+    const added = fileRows(page).first();
+    expect(await added.evaluate(node => node.localName)).toBe('button');
+    await expect(added.locator('.path')).toHaveText('shared/same.png');
+    await expect(added.locator('.why')).toHaveText('Added to the Library as “Cat portrait”');
+    await expect(resultsNote(page)).toHaveText('Each row opens the image in the viewer.');
+    await added.click();
+    const viewer = page.locator('dialog#viewer-dialog[open]');
+    await expect(viewer).toBeVisible();
+    await expect(viewer.locator('#viewer-title')).toContainText('same.png');
+    await expect(viewer.locator('#viewer-stage img').first()).toHaveAttribute('src', /[?&]root=0(&|$)/);
+    await page.keyboard.press('Escape');
+    await expect(viewer).toHaveCount(0);
+    await expect(added).toBeFocused();
+
+    // Already known opens the input root's file.
+    await outcomeButtons(page).filter({ hasText: 'Already known' }).click();
+    await expect(outcomeButtons(page).filter({ hasText: 'Already known' })).toHaveAttribute('aria-pressed', 'true');
+    await fileRows(page).first().click();
+    await expect(page.locator('dialog#viewer-dialog[open] #viewer-stage img').first()).toHaveAttribute('src', /[?&]root=1(&|$)/);
+    await page.keyboard.press('Escape');
+
+    // Errors: plain text rows, no viewer hint.
+    await outcomeButtons(page).filter({ hasText: 'Errors' }).click();
+    await expect(fileRows(page)).toHaveCount(1);
+    expect(await fileRows(page).first().evaluate(node => node.localName)).toBe('div');
+    await expect(fileRows(page).first().locator('.path')).toHaveText('broken/truncated.png');
+    await expect(resultsNote(page)).toHaveCount(0);
+    // An empty group says so.
+    await outcomeButtons(page).filter({ hasText: 'Needs review' }).click();
+    await expect(resultsSection(page).locator('.outcome-files > p.empty-state')).toHaveText('No files in this group.');
+
+    // A listed row whose file has left the listing toasts instead of opening an empty viewer.
+    await step(request, job.id, { records: [{ group: 'added', path: 'gone/missing.png', root: 'output', detail: 'Added' }] });
+    await outcomeButtons(page).first().click();
+    await expect(fileRows(page)).toHaveCount(2);
+    await fileRows(page).nth(1).click();
+    await expect(toast(page)).toHaveText('This file is no longer in Images. Rescan from Import and try again.');
+    await expect(page.locator('dialog#viewer-dialog')).toHaveCount(0);
+    // A row opens only its own root's file: a root whose label no longer matches (a replaced source) never opens the
+    // other root's same path, and a row without a root index opens nothing (review M8, M9).
+    const lookups = [];
+    page.on('request', item => { const url = new URL(item.url()); if (url.pathname === '/prompt_manager/images/output' && url.searchParams.get('path')) lookups.push(url.search); });
+    await step(request, job.id, { records: [
+        { group: 'added', path: 'shared/same.png', root: 'output', root_index: 1, detail: 'Added' },
+        { group: 'added', path: 'shared/same.png', root: 'output', root_index: null, detail: 'Added' },
+    ] });
+    await expect(fileRows(page)).toHaveCount(4);
+    for (const index of [2, 3]) {
+        await fileRows(page).nth(index).click();
+        await expect(toast(page)).toHaveText('This file is no longer in Images. Rescan from Import and try again.');
+        await expect(page.locator('dialog#viewer-dialog')).toHaveCount(0);
+    }
+    expect(lookups).toEqual([]);
+    // The lookup is the exact identity, not a name search.
+    await fileRows(page).first().click();
+    await expect(page.locator('dialog#viewer-dialog[open]')).toBeVisible();
+    expect(lookups).toEqual(['?mode=workspace&root=0&path=shared%2Fsame.png&limit=5']);
+    await page.keyboard.press('Escape');
+});
+
+test('filter narrows the selected outcome', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request);
+    await step(request, job.id, { processed: 4, records: [
+        { group: 'added', path: 'CCC/portrait_0001.png', detail: 'Added' },
+        { group: 'added', path: 'CCC/portrait_0002.png', detail: 'Added' },
+        { group: 'added', path: 'forest/pines_0008.png', detail: 'Added' },
+        { group: 'errors', path: 'CCC/broken.png', detail: 'Error' },
+    ] });
+    await openJob(page, job.id);
+    await expect(fileRows(page)).toHaveCount(3);
+    await expect(filter(page)).toHaveAttribute('placeholder', 'Filter by file path…');
+    await filter(page).fill('ccc/');
+    await expect(fileRows(page).locator('.path')).toHaveText(['CCC/portrait_0001.png', 'CCC/portrait_0002.png']);
+    await expect(resultsNote(page)).toHaveText(`Showing 2 of 3 · ${VIEWER_HINT}`);
+    // The filter stays while another outcome is chosen.
+    await outcomeButtons(page).filter({ hasText: 'Errors' }).click();
+    await expect(fileRows(page).locator('.path')).toHaveText(['CCC/broken.png']);
+    await filter(page).fill('pines');
+    await expect(fileRows(page)).toHaveCount(0);
+    await expect(resultsSection(page).locator('.outcome-files > p.empty-state')).toHaveText('No listed file matches this filter.');
+    await outcomeButtons(page).first().click();
+    await expect(fileRows(page).locator('.path')).toHaveText(['forest/pines_0008.png']);
+    await filter(page).fill('');
+    await expect(fileRows(page)).toHaveCount(3);
+});
+
+test('job view renders 200-row cap note', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request);
+    await step(request, job.id, { processed: 260, bulk: { group: 'added', count: 250 }, records: [
+        ...Array.from({ length: 10 }, (_, index) => ({ group: 'no_metadata', path: `misc/plain_${index}.png`, detail: 'No prompt metadata in the file' })),
+    ] });
+    // Every detail read of this job: in flight, and whether one has returned the full listing.
+    const detailUrl = `/prompt_manager/jobs/${job.id}`;
+    const isDetail = item => new URL(item.url()).pathname === detailUrl;
+    const detailReads = { inFlight: 0, full: false };
+    page.on('request', item => { if (isDetail(item)) detailReads.inFlight += 1; });
+    page.on('requestfailed', item => { if (isDetail(item)) detailReads.inFlight -= 1; });
+    page.on('response', async response => {
+        if (!isDetail(response)) return;
+        const body = await response.json().catch(() => null);
+        const outcomes = body?.job?.outcomes ?? {};
+        if (outcomes.added?.length === 200 && outcomes.no_metadata?.length === 10) detailReads.full = true;
+        detailReads.inFlight -= 1;
+    });
+    await openJob(page, job.id);
+    await expect(tiles(page).first().locator('dd')).toHaveText('250');
+    await expect(fileRows(page)).toHaveCount(200);
+    await expect(resultsNote(page)).toHaveText(`Showing 200 of 250 · ${VIEWER_HINT}`);
+    await outcomeButtons(page).filter({ hasText: 'No usable metadata' }).click();
+    await expect(fileRows(page)).toHaveCount(10);
+    await expect(resultsNote(page)).toHaveCount(0);
+    // Every listed row is in the page and it stays responsive: a filter answers at once.
+    await outcomeButtons(page).first().click();
+    await filter(page).fill('file_00199');
+    await expect(fileRows(page)).toHaveCount(1);
+    await expect(resultsNote(page)).toHaveText(`Showing 1 of 250 · ${VIEWER_HINT}`);
+
+    // Review M12: with the list capped and the log closed, more files only update the counters; the detail is read
+    // again only when the log opens with new lines.
+    // The reads from opening the view have settled: one returned the full listing and none is in flight. The view
+    // re-reads only while what the summary lists differs from the last read, so no further read is due.
+    await expect.poll(() => detailReads.full && detailReads.inFlight === 0).toBe(true);
+    const reads = [];
+    page.on('request', item => { if (new URL(item.url()).pathname === `/prompt_manager/jobs/${job.id}`) reads.push(Date.now()); });
+    await step(request, job.id, { processed: 300, bulk: { group: 'added', count: 40 } });
+    await expect(tiles(page).first().locator('dd')).toHaveText('290');
+    await page.waitForTimeout(1500);
+    expect(reads).toEqual([]);
+    await scanLog(page).locator('summary').click();
+    await expect.poll(() => reads.length).toBe(1);
+    await expect(scanLog(page).locator('pre')).toContainText('bulk/file_00039.png');
+});
+
+test('cancel scan ends cancelled with partial counts', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request);
+    await step(request, job.id, { processed: 9, counters: { added: 7, errors: 2 } });
+    await openJob(page, job.id);
+    // From the keyboard: when the job ends and Cancel scan goes away, focus moves to the job's heading (review M4).
+    await heading(page).getByRole('button', { name: 'Cancel scan', exact: true }).focus();
+    await page.keyboard.press('Enter');
+    await expect(toast(page)).toHaveText('Scan cancelled · 7 added');
+    await expect(heading(page).locator('h1')).toBeFocused();
+    await expect(heading(page).locator('p.muted')).toHaveText(/^Cancelled \d\d:\d\d at a file boundary · 7 added · completed work is kept$/);
+    await expect(heading(page).getByRole('button', { name: 'Cancel scan', exact: true })).toHaveCount(0);
+    await expect(progressSection(page).locator('.panel-heading > span.small')).toHaveText('Cancelled after 9 of 19,622 files');
+    expect((await tileValues(page)).map(([, , value]) => value)).toEqual(['7', '0', '0', '0', '2']);
+    expect((await listed(request))[0].state).toBe('cancelled');
+
+    // A failed cancel request keeps the button and says so.
+    const second = await startJob(request);
+    await openJob(page, second.id);
+    await page.route('**/cancel', route => route.fulfill({ status: 500, json: { success: false, error: 'nope' } }));
+    await heading(page).getByRole('button', { name: 'Cancel scan', exact: true }).click();
+    await expect(toast(page)).toHaveText('The job could not be cancelled. Try again.');
+    await expect(heading(page).getByRole('button', { name: 'Cancel scan', exact: true })).not.toHaveAttribute('aria-disabled', 'true');
+});
+
+test('busy start names the running job', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const running = await startJob(request, { title: 'Database maintenance', kind: 'maintenance' });
+    await startFromImport(page);
+    await expect(toast(page)).toHaveText('Another job is running: Database maintenance.');
+    await expect(toast(page).getByRole('link', { name: 'Database maintenance', exact: true })).toHaveAttribute('href', `#/activity/${running.id}`);
+    await expect(page).toHaveURL(/#\/images$/);
+    expect((await listed(request)).map(item => item.id)).toEqual([running.id]);
+    // Review M14: a toast with a link outlasts the plain 6.5 s, so the link stays reachable.
+    await page.waitForTimeout(7000);
+    await expect(toast(page).getByRole('link', { name: 'Database maintenance', exact: true })).toBeVisible();
+    await toast(page).getByRole('link', { name: 'Database maintenance', exact: true }).click();
+    await expect(heading(page).locator('h1')).toHaveText('Database maintenance');
+    // A job of another kind cancels as "Cancel job".
+    await expect(heading(page).locator('.heading-actions > button')).toHaveText(['Download report', 'Cancel job']);
+});
+
+test('an unknown or restarted job view says so', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await page.goto(`${workspace}#/activity/${'0'.repeat(32)}`);
+    await expect(main(page).locator('section.surface p.empty-state')).toHaveText('This job is not in this session’s Activity. Jobs are kept until ComfyUI restarts.');
+    await expect(main(page).getByRole('link', { name: 'All activity', exact: true })).toHaveAttribute('href', '#/activity');
+
+    const job = await startJob(request);
+    await step(request, job.id, { processed: 5, records: [{ group: 'added', path: 'kept/row.png', detail: 'Added' }] });
+    await openJob(page, job.id);
+    await expect(fileRows(page)).toHaveCount(1);
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    await expect(heading(page).locator('p.muted')).toHaveText(LOST);
+    await expect(heading(page).getByRole('button', { name: 'Cancel scan', exact: true })).toHaveCount(0);
+    // A lost job has no report on the server (review M9): Download report is disabled rather than failing.
+    await expect(heading(page).getByRole('button', { name: 'Download report', exact: true })).toBeDisabled();
+    // What was read before the restart stays on the page.
+    await expect(fileRows(page)).toHaveCount(1);
+    await expect(pill(page)).toBeHidden();
+});
+
+// Review M3: a finished job the server no longer lists is gone from this tab too, and its open view says so.
+test('a finished job the server pruned leaves its open view honest', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request);
+    await step(request, job.id, { processed: 1, records: [{ group: 'added', path: 'kept/row.png', detail: 'Added' }] });
+    await finish(request, job.id);
+    await openJob(page, job.id);
+    await expect(fileRows(page)).toHaveCount(1);
+    await filter(page).focus();
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    // The next periodic list read (15 s) no longer has the finished job.
+    test.slow();
+    await expect(main(page).locator('section.surface p.empty-state')).toHaveText('This job is not in this session’s Activity. Jobs are kept until ComfyUI restarts.', { timeout: 20000 });
+    await expect(progressSection(page)).toHaveCount(0);
+    await expect(heading(page).locator('h1')).toHaveText('Activity');
+    await expect(heading(page).locator('h1')).toBeFocused();
+    await expect(page).toHaveTitle('Activity · Prompt Manager');
+});
+
+// Activity-2 Task 5 (D59): Download report and the log's scroll position.
+test('download report saves the job JSON', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request);
+    await step(request, job.id, { processed: 2, records: [
+        { group: 'added', path: 'sub/a.png', root: 'output', detail: 'Added' },
+        { group: 'errors', path: 'broken/b.png', root: 'output', detail: 'Error' },
+    ] });
+    await finish(request, job.id);
+    await openJob(page, job.id);
+    const button = heading(page).getByRole('button', { name: 'Download report', exact: true });
+    await expect(button).toBeEnabled();
+    const [download] = await Promise.all([page.waitForEvent('download'), button.click()]);
+    expect(download.suggestedFilename()).toMatch(/^prompt-manager-scan-\d{8}-\d{4}\.json$/);
+    const path = await download.path();
+    const report = JSON.parse(await (await import('node:fs/promises')).readFile(path, 'utf8'));
+    expect(report.job.id).toBe(job.id);
+    expect(report.outcomes.added.rows.map(row => row.path)).toEqual(['sub/a.png']);
+    expect(report.outcomes.errors.truncated).toBe(false);
+    expect(report.log.length).toBeGreaterThan(0);
+    await expect(toast(page)).toHaveText('Job report downloaded.');
+});
+
+test('log keeps the reader\'s scroll position', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request);
+    const more = (from, count) => Array.from({ length: count }, (_, index) => ({ group: 'known', path: `log/f_${from + index}.png`,
+        root: 'output', detail: 'Known' }));
+    await step(request, job.id, { processed: 60, records: more(0, 60) });
+    await openJob(page, job.id);
+    await scanLog(page).locator('summary').click();
+    const pre = scanLog(page).locator('pre');
+    await expect(pre).toContainText('log/f_59.png');
+    const metrics = () => pre.evaluate(node => ({ top: node.scrollTop, max: node.scrollHeight - node.clientHeight }));
+    // Opening starts at the newest line.
+    await expect.poll(async () => { const m = await metrics(); return m.max > 0 && m.top >= m.max - 2; }).toBe(true);
+    // Pinned to the bottom: new lines are followed.
+    await step(request, job.id, { processed: 90, records: more(60, 30) });
+    await expect(pre).toContainText('log/f_89.png');
+    await expect.poll(async () => { const m = await metrics(); return m.top >= m.max - 2; }).toBe(true);
+    // Scrolled up: the position stays while more lines arrive.
+    await pre.evaluate(node => { node.scrollTop = 40; });
+    await step(request, job.id, { processed: 120, records: more(90, 30) });
+    await expect(pre).toContainText('log/f_119.png');
+    expect((await metrics()).top).toBe(40);
+    // Closed and opened again (review M6): every open starts at the newest line, also after lines arrived meanwhile.
+    await scanLog(page).locator('summary').click();
+    await expect(scanLog(page)).not.toHaveAttribute('open', '');
+    await step(request, job.id, { processed: 150, records: more(120, 30) });
+    await scanLog(page).locator('summary').click();
+    await expect(pre).toContainText('log/f_149.png');
+    await expect.poll(async () => { const m = await metrics(); return m.max > 0 && m.top >= m.max - 2; }).toBe(true);
+});
+
+test('a failed report download says so and leaves the button usable', async ({ page, request }) => {
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    const job = await startJob(request);
+    await finish(request, job.id);
+    await openJob(page, job.id);
+    await page.route(`**/prompt_manager/jobs/${job.id}/report`, route => route.fulfill({ status: 500, body: 'no' }));
+    const button = heading(page).getByRole('button', { name: 'Download report', exact: true });
+    await button.click();
+    await expect(toast(page)).toHaveText('The report could not be downloaded. Try again.');
+    await expect(button).not.toHaveAttribute('aria-disabled', 'true');
+});

tests/browser/workspace-history.spec.mjs

@@ -1,5 +1,5 @@
 import {startCoverage,saveCoverage} from '../../tools/vendor/browser-coverage.mjs';
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 import {readFile,writeFile} from 'node:fs/promises';
 import {createHash} from 'node:crypto';
 
@@ -317,6 +317,19 @@ test('marker labels disclose exact observed dequeue and outcome including times
     }
 });
 
+// A timeline scroll re-renders the markers on the next frame. On a slow runner that frame lands between the press and
+// the release of a marker tap (Playwright's own scroll-into-view scrolls the timeline first); the re-render must leave
+// the pressed marker's nodes alone, or Chromium touch drops the click. The scroll event is dispatched so the marker
+// stays under the pointer, and the two frames are the re-render itself.
+test('a timeline re-render between press and release keeps the marker tap',async({page})=>{
+    const f=page.fixture;await open(page,f.detail_id);
+    const target=marker(page,f.runs.shared,'z');await expect(target).toHaveAttribute('aria-disabled','false');await target.scrollIntoViewIfNeeded();
+    const box=await target.boundingBox();await page.mouse.move(box.x+box.width/2,box.y+box.height/2);await page.mouse.down();
+    await recorded(page).locator('.history-timeline').evaluate(timeline=>{timeline.dispatchEvent(new Event('scroll'));return new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)));});
+    await page.mouse.up();
+    await expect(dialog(page).locator('[data-receipt]')).toHaveCount(5);
+});
+
 test('same-epoch refresh retains recorded context mode and exact receipt after fresh candidate reads',async({page})=>{
     const f=page.fixture;await open(page,f.detail_id);await marker(page,f.runs.shared,'z').click();await expect(dialog(page).locator('[data-receipt]')).toHaveCount(5);
     await dialog(page).getByRole('button',{name:'Effective',exact:true}).click();
@@ -1006,7 +1019,7 @@ test('shared gallery uses concept cards, image opens the viewer, empty copy',asy
     await expect(star).toHaveAccessibleName(`Favorite ${filename}`);await expect(star).toHaveAttribute('aria-pressed',String(image.favorite));
     await expect(star).toHaveText(image.favorite?'★':'☆');
     await expect(first.locator('.media-info h3')).toHaveCount(1);
-    await expect(first.locator('.image-card-actions > button.icon-btn')).toHaveAccessibleName(`Inspect ${filename}`);
+    await expect(first.locator('.image-card-actions > button.icon-btn:first-child')).toHaveAccessibleName(`Inspect ${filename}`);
     // C3 activation: the image opens the viewer and Escape returns focus to it.
     const openButton=first.locator('.image-open');await openButton.click();
     const viewer=page.locator('dialog#viewer-dialog');await expect(viewer).toBeVisible();

tests/browser/workspace-images.spec.mjs

@@ -1,5 +1,5 @@
 import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
-import { test, expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import { test, expect } from './fixtures.mjs';
 import { seedConcept, openConcept, openProduction } from './concept-inventory.mjs';
 
 const workspace = '/prompt_manager/workspace#/images';
@@ -545,7 +545,7 @@ async function staleSourceRecovery(page, request, roots) {
     await expect(await request.post('/prompt_manager/settings', { data: { gallery_root_paths: roots } })).toBeOK();
     const selected = initial.images.at(-1), key = `${selected.root_index}:${selected.path}`;
     const stale = page.waitForResponse(response => response.url().includes('/images/inspect/') && response.status() === 409);
-    await page.locator(`article[data-image-key="${key}"] .image-card-actions button`).click();expect((await stale).status()).toBe(409);
+    await page.locator(`article[data-image-key="${key}"] .image-card-actions button:first-child`).click();expect((await stale).status()).toBe(409);
     await expect(details(page)).toContainText('The source changed. Refresh the image collection before inspecting this file.');
     await page.locator(`article[data-image-key="${key}"] .image-open`).click();
     const viewer = page.locator('dialog#viewer-dialog');await expect(viewer).toContainText('The source changed.');
@@ -1028,8 +1028,7 @@ async function cardInventory(page, concept) {
         const walk = new Function(`return (${walkSource})()`)();
         return nodes.map(card => {
             const copy = card.cloneNode(true);
-            // D9: no tag button until image annotations. The D8 checkbox and the D7 star are compared.
-            if (concept) for (const node of copy.querySelectorAll('[aria-label^="Tag or auto-tag "]')) node.remove();
+            // Info then Tag (#249 C2 retired D9). The D8 checkbox and the D7 star are compared.
             const open = card.querySelector('.image-open'), img = open.querySelector('img');
             const star = card.querySelector('.image-overlays > button.star-button');
             const box = card.querySelector('.image-overlays > label > input');
@@ -1039,7 +1038,7 @@ async function cardInventory(page, concept) {
                 size: [img.getAttribute('width'), img.getAttribute('height')],
                 title: card.querySelector('.media-info h3').textContent, subtitle: card.querySelector('.media-info p').textContent,
                 ratio: card.style.getPropertyValue('--media-ratio').replace(/\s/g, ''),
-                inspect: card.querySelector('.image-card-actions > button').getAttribute('aria-label'),
+                actions: [...card.querySelectorAll('.image-card-actions > button')].map(button => button.getAttribute('aria-label')),
                 star: star && { text: star.textContent, pressed: star.getAttribute('aria-pressed'), label: star.getAttribute('aria-label') },
                 select: box && { type: box.type, checked: box.checked, label: box.getAttribute('aria-label') },
                 paths: walk(copy, `article.${[...card.classList].filter(value => value !== 'selected').sort().join('.')}`, []) };
@@ -1209,7 +1208,7 @@ async function zoomedGallery(page, request, { cssZoom }) {
     await page.keyboard.press('Tab');
     await expect(page.locator(`article[aria-posinset="${columns + 1}"] .image-overlays .star-button`)).toBeFocused();
     await page.keyboard.press('Tab');
-    await expect(page.locator(`article[aria-posinset="${columns + 1}"] .image-card-actions button`)).toBeFocused();
+    await expect(page.locator(`article[aria-posinset="${columns + 1}"] .image-card-actions button:first-child`)).toBeFocused();
     await page.evaluate(() => {
         const card = document.querySelector('article[aria-posinset="1"]');
         const grid = document.querySelector('.image-grid');
@@ -1512,6 +1511,25 @@ test('Refine opened before discovery settles lists the discovered sources and fo
 });
 
 // #249 final review m1: as in the old field row, a Source offers only its own folders.
+test('a search reload keeps the Filters label node, so a click landing during the reload is not lost', async ({ page, request }) => {
+    // WebKit drops a click whose mousedown hit a text node that was replaced before mouseup; the reload reports the
+    // (unchanged) active count, so the label must keep its node.
+    await expect(await request.post('/__test__/reset', { data: { extra_images: 80 } })).toBeOK();
+    await page.goto(workspace);
+    const button = filtersButton(page);
+    await button.click();await expect(refineDialog(page).getByLabel('Folder', { exact: true }).locator('option[value="bulk"]')).toHaveCount(1);await page.keyboard.press('Escape');
+    await refine(page, { Source: '0', Folder: 'bulk' });
+    await expect(button).toHaveText('Filters · 2');
+    const label = await button.evaluateHandle(node => node.firstChild);
+    const reloaded = page.waitForResponse(response => {
+        const url = new URL(response.url());return imagePages(url) && url.searchParams.get('q') === 'png';
+    });
+    await search(page).fill('png');
+    await reloaded;
+    await expect(button).toHaveText('Filters · 2');
+    expect(await button.evaluate((node, text) => node.firstChild === text && text.isConnected, label)).toBe(true);
+});
+
 test('Refine offers only the chosen source folders', async ({ page, request }) => {
     await expect(await request.post('/__test__/add-nested-image')).toBeOK();
     await page.goto(workspace);
@@ -2037,3 +2055,50 @@ test('Set category limits the field to the server length, shows the server count
     await expect(bulkbar(page)).toBeEmpty();
     expect(answers).toHaveLength(0);
 });
+
+// Activity-1 Task 3 (D55): Import → "Scan for metadata" → Review scan opens the concept's "Review metadata scan".
+const scanReview = page => page.getByRole('dialog', { name: 'Review metadata scan', exact: true });
+async function openScanReview(page) {
+    await page.getByRole('button', { name: 'Import', exact: true }).click();
+    const row = importDialog(page).locator('.operation').filter({ has: page.getByRole('heading', { name: 'Scan for metadata', exact: true }) });
+    await row.getByRole('button', { name: 'Review scan', exact: true }).click();
+    await expect(scanReview(page)).toBeVisible();
+}
+
+test('scan for metadata opens the review dialog from Import', async ({ page, request }) => {
+    await expect(await request.post('/__test__/jobs/restart')).toBeOK();
+    await page.setViewportSize({ width: 1600, height: 1100 });
+    await page.goto(workspace);
+    await expect(cards(page)).toHaveCount(2);
+    // Rescan stays the quick refresh; the metadata scan is its own row under it.
+    await page.getByRole('button', { name: 'Import', exact: true }).click();
+    await expect(importDialog(page).locator('.operation h3')).toHaveText(['Inspect a local image', 'Scan an output folder', 'Scan for metadata']);
+    await expect(importDialog(page).locator('.operation').nth(2).locator('p')).toHaveText('Discover and enrich existing files using the configured sources.');
+    await page.keyboard.press('Escape');
+    await openScanReview(page);
+    const dialog = scanReview(page);
+    await expect(dialog.locator('dl.meta-grid > div > dt')).toHaveText(['Sources', 'Scope']);
+    await expect(dialog.locator('dl.meta-grid > div > dd')).toHaveText(['2 output folders', 'New and unresolved files']);
+    await expect(dialog.locator('#modal-body > p.small')).toHaveText('Enrich positive / negative associations, reuse canonical text and report unchanged files. Do not inflate run counts or recreate existing thumbnails.');
+    await expect(dialog.locator('.notice h3')).toHaveText('Back up the database first (recommended)');
+    await expect(dialog.locator('.dialog-actions button')).toHaveText(['Cancel', 'Start scan']);
+    await expect(dialog.getByRole('button', { name: 'Start scan', exact: true })).toHaveClass(/ca-primary/);
+
+    // Back up now downloads the existing backup, toasts, and keeps the dialog open for the scan.
+    const download = page.waitForEvent('download');
+    await dialog.getByRole('button', { name: 'Back up now', exact: true }).click();
+    expect((await download).suggestedFilename()).toMatch(/^prompts_backup_\d{8}_\d{6}\.db$/);
+    await expect(toast(page)).toHaveText('Database backup downloaded.');
+    await expect(dialog).toBeVisible();
+    // A failed backup says so and downloads nothing.
+    await page.route('**/prompt_manager/backup', route => route.fulfill({ status: 500, json: { success: false, error: 'disk full' } }));
+    await dialog.getByRole('button', { name: 'Back up now', exact: true }).click();
+    await expect(toast(page)).toHaveText('The database could not be backed up. Try again.');
+
+    // Cancel closes it and starts nothing.
+    await dialog.getByRole('button', { name: 'Cancel', exact: true }).click();
+    await expect(scanReview(page)).toHaveCount(0);
+    await expect(page.getByRole('button', { name: 'Import', exact: true })).toBeFocused();
+    const jobs = await (await request.get('/prompt_manager/jobs')).json();
+    expect(jobs.jobs).toEqual([]);
+});

tests/browser/workspace-inspect.spec.mjs

@@ -0,0 +1,687 @@
+// The native "Inspect a file" page (#249 local Inspect, PR L2 Task 6): one chosen or dropped local file previews
+// inline, and the heading's one action opens the shared viewer with the full inspector on a record read entirely in
+// this browser. The concept is docs/concepts/workspace/app.js renderMetadata (740–748) and its selection (1715–1729);
+// the production differences are D60–D66 in TESTING.md.
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { parityPng, localFixture, tinyWebm, sendablePng, corruptPng, disguised, undecodableMp4, POSITIVE_LINES } from './local-inspect-files.mjs';
+
+const workspace = '/prompt_manager/workspace';
+const TOAST = 'Local preview only. No file uploaded; metadata is available above.';
+const ACTION = 'Open file metadata';
+const COPY = {
+    intro: 'Read embedded metadata in this browser. The file is not uploaded or added to your library.',
+    note: 'Your file stays in this browser. Its metadata opens with “Open file metadata”.',
+    chooser: 'Choose an image or video for a local preview',
+    multiple: 'Drop one file at a time.',
+    directory: 'Folders cannot be inspected. Choose one image or video file.',
+    unsupported: 'This file type cannot be previewed or inspected here. Choose an image or video file.',
+    previewFailed: 'The preview could not be displayed. Metadata and the original remain available in the viewer.',
+};
+
+test.use({ locale: 'en-US', timezoneId: 'UTC', reducedMotion: 'reduce' });
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await expect(await request.post('/__test__/reset')).toBeOK();
+    page.inspectErrors = [];
+    page.on('pageerror', error => page.inspectErrors.push(error.message));
+});
+
+test.afterEach(async ({ page, browserName }) => {
+    await page.unrouteAll({ behavior: 'ignoreErrors' });
+    await saveCoverage(page, browserName);
+    expect(page.inspectErrors).toEqual([]);
+});
+
+const main = page => page.locator('#workspace-main');
+const action = page => main(page).locator('.heading-actions').getByRole('button', { name: ACTION, exact: true });
+const chooser = page => page.locator('#local-file');
+const preview = page => page.locator('#local-preview');
+const status = page => preview(page).locator('p.small');
+const viewer = page => page.locator('dialog#viewer-dialog');
+const rail = page => viewer(page).locator('#viewer-details');
+
+async function openInspect(page) {
+    await page.goto(`${workspace}#/inspect`);
+    await expect(main(page).getByRole('heading', { level: 1, name: 'Inspect a file', exact: true })).toBeVisible();
+    await expect(chooser(page)).toBeAttached();
+}
+
+/** Selects through the real chooser, then waits for the page to classify the file. */
+async function choose(page, file) {
+    await chooser(page).setInputFiles(file);
+}
+
+async function openViewer(page) {
+    await expect(action(page)).toHaveAttribute('aria-disabled', 'false');
+    await action(page).click();
+    await expect(viewer(page)).toBeVisible();
+    await expect(rail(page).locator('.panel-heading')).toBeVisible();
+}
+
+/** Dispatches dragover + drop on `selector` with Files built in the page (and optional string items). */
+function drop(page, selector, { files = [], strings = [] } = {}) {
+    return page.evaluate(async ({ selector, files, strings }) => {
+        const transfer = new DataTransfer();
+        for (const file of files) transfer.items.add(new File([new Uint8Array(file.bytes)], file.name, { type: file.mimeType }));
+        for (const [type, value] of strings) transfer.items.add(value, type);
+        const target = document.querySelector(selector);
+        const over = new DragEvent('dragover', { bubbles: true, cancelable: true, dataTransfer: transfer });
+        const dropped = new DragEvent('drop', { bubbles: true, cancelable: true, dataTransfer: transfer });
+        target.dispatchEvent(over);
+        target.dispatchEvent(dropped);
+        return { over: over.defaultPrevented, drop: dropped.defaultPrevented };
+    }, { selector, files: files.map(file => ({ name: file.name, mimeType: file.mimeType, bytes: [...file.buffer] })), strings });
+}
+
+/** The rail's comparable content: prompts, the six facts, the raw records and the two downloads (D66 aside). */
+const railContent = locator => locator.evaluate(node => {
+    const raw = [...node.querySelectorAll('details')].find(item => item.querySelector('summary')?.textContent === 'Workflow & raw metadata');
+    const facts = node.querySelector(':scope .meta-grid:not(details .meta-grid)');
+    return {
+        positive: node.querySelector('.prompt-section.positive p.prompt-text')?.textContent ?? null,
+        negative: node.querySelector('.prompt-section.negative p.prompt-text')?.textContent ?? null,
+        facts: facts ? [...facts.querySelectorAll(':scope > div')].map(item => [item.querySelector('dt').textContent, item.querySelector('dd').textContent]) : null,
+        raw: raw ? [...raw.querySelectorAll('p.small, pre')].map(item => item.textContent) : null,
+        downloads: raw ? [...raw.querySelectorAll('button')].map(item => [item.textContent, item.getAttribute('aria-disabled')]) : null,
+    };
+});
+
+/** Counts storage writes and object URLs created and revoked for Files (download blobs are not the session's). */
+async function instrument(page) {
+    await page.addInitScript(() => {
+        window.__inspect = { writes: [], created: [], revoked: [], files: new Set() };
+        for (const name of ['setItem', 'removeItem', 'clear']) {
+            const original = Storage.prototype[name];
+            Storage.prototype[name] = function (...args) { window.__inspect.writes.push([name, args[0]]); return original.apply(this, args); };
+        }
+        const open = indexedDB.open.bind(indexedDB);
+        indexedDB.open = (...args) => { window.__inspect.writes.push(['indexedDB.open', args[0]]); return open(...args); };
+        const create = URL.createObjectURL, revoke = URL.revokeObjectURL;
+        URL.createObjectURL = object => {
+            const url = create(object);
+            if (object instanceof File) { window.__inspect.created.push(url); window.__inspect.files.add(url); }
+            return url;
+        };
+        URL.revokeObjectURL = url => { if (window.__inspect.files.has(url)) window.__inspect.revoked.push(url); return revoke(url); };
+    });
+}
+const urls = page => page.evaluate(() => ({ created: [...window.__inspect.created], revoked: [...window.__inspect.revoked], writes: [...window.__inspect.writes] }));
+
+test('chooser opens the shared full inspector without a second read', async ({ page, request }) => {
+    // The Images viewer's rail for the same bytes, served from the output folder.
+    await expect(await request.post('/__test__/add-local-inspect-file', { data: { name: 'f02.png' } })).toBeOK();
+    await page.goto(`${workspace}#/images`);
+    await page.locator('article[data-image-key="0:local-inspect/f02.png"] .image-open').click();
+    await expect(rail(page).locator('.prompt-section.positive p.prompt-text')).toBeVisible();
+    const served = await railContent(rail(page));
+    await page.keyboard.press('Escape');
+    await expect(viewer(page)).toHaveCount(0);
+
+    await page.locator('aside.sidebar nav').getByRole('link', { name: 'Inspect a file', exact: true }).click();
+    await expect(main(page).getByRole('heading', { level: 1, name: 'Inspect a file', exact: true })).toBeVisible();
+    await expect(main(page).locator('.heading p.muted')).toHaveText('A standalone file uses the same image viewer and prompt actions.');
+    // The concept DOM: one surface, the drop area with its icon, label, input and note, then the preview slot.
+    const surface = main(page).locator('section.surface');
+    await expect(surface).toHaveCount(1);
+    await expect(surface.locator('h2')).toHaveText('Inspect without importing');
+    await expect(surface.locator(':scope > p')).toHaveText(COPY.intro);
+    const area = surface.locator('div.file-drop.spaced-20');
+    await expect(area.locator(':scope > svg')).toHaveCount(1);
+    await expect(area.locator('label[for="local-file"]')).toHaveText(COPY.chooser);
+    await expect(chooser(page)).toHaveAttribute('type', 'file');
+    await expect(chooser(page)).toHaveAttribute('accept', 'image/png,image/jpeg,image/webp,video/*,.mp4,.mov,.m4v,.webm,.mkv,.avi,.wmv');
+    await expect(chooser(page)).not.toHaveAttribute('multiple', /.*/);
+    await expect(area.locator('span.small#local-file-note')).toHaveText(COPY.note);
+    await expect(surface.locator(':scope > #local-preview')).toBeEmpty();
+    // D60: the one heading action is described by the note until a file is chosen.
+    await expect(main(page).locator('.heading-actions button')).toHaveCount(1);
+    await expect(action(page)).toHaveClass(/\bca-primary\b/);
+    await expect(action(page)).toHaveAttribute('aria-disabled', 'true');
+    await expect(action(page)).toHaveAccessibleDescription(COPY.note);
+    await action(page).dispatchEvent('click');
+    await expect(viewer(page)).toHaveCount(0);
+
+    await choose(page, parityPng('f02.png'));
+    const image = preview(page).locator('img.local-file-preview');
+    await expect(image).toHaveAttribute('alt', 'Local file preview');
+    await expect(image).toHaveJSProperty('complete', true);
+    expect(await image.evaluate(node => node.naturalWidth)).toBe(64);
+    expect(await image.getAttribute('src')).toMatch(/^blob:/);
+    const box = await image.evaluate(node => ({ height: node.getBoundingClientRect().height, fit: getComputedStyle(node).objectFit, margin: getComputedStyle(node).marginTop }));
+    expect(box.height).toBeLessThanOrEqual(400);
+    expect(box).toMatchObject({ fit: 'contain', margin: '20px' });
+    await expect(page.locator('#workspace-toast')).toHaveText(TOAST);
+    await expect(action(page)).toHaveAttribute('aria-disabled', 'false');
+    await expect(action(page)).not.toHaveAttribute('aria-describedby', /.*/);
+
+    await openViewer(page);
+    await expect(viewer(page).locator('#viewer-title')).toHaveText('f02.png');
+    const position = viewer(page).locator('.media-position');
+    await expect(position).toHaveText('1 of 1 loaded: f02.png');
+    for (const name of ['Previous media', 'Next media', 'Play slideshow']) {
+        await expect(viewer(page).getByRole('button', { name, exact: true })).toHaveAttribute('aria-disabled', 'true');
+    }
+    await expect(viewer(page).locator('.viewer-canvas img')).toBeVisible();
+    for (const name of ['Fit image', 'Rotate image 90 degrees', 'Flip image horizontally']) {
+        await expect(viewer(page).getByRole('button', { name, exact: true })).toHaveAttribute('aria-disabled', 'false');
+    }
+    const canvas = viewer(page).locator('.viewer-canvas img');
+    await viewer(page).getByRole('button', { name: 'Rotate image 90 degrees', exact: true }).click();
+    await expect(canvas).toHaveAttribute('style', /rotate\(90deg\)/);
+    await viewer(page).getByRole('button', { name: 'Flip image horizontally', exact: true }).click();
+    await expect(canvas).toHaveAttribute('style', /scaleX\(-1\)/);
+    await viewer(page).getByRole('button', { name: 'Fit image', exact: true }).click();
+    await expect(canvas).not.toHaveAttribute('style', /rotate\(90deg\)/);
+
+    // The same rail as Images for the same bytes, except the D66 provenance.
+    const local = await railContent(rail(page));
+    expect(local).toEqual(served);
+    expect(local.positive).toBe('a red fox in snow, detailed fur');
+    expect(local.negative).toBe('blurry, lowres');
+    expect(local.facts.map(([label]) => label)).toEqual(['Seed', 'Steps', 'CFG', 'Sampler', 'Scheduler', 'Model']);
+    expect(local.downloads).toEqual([['Download metadata JSON', null], ['Download workflow JSON', null]]);
+    const provenance = rail(page).locator('details').filter({ has: page.locator('summary', { hasText: 'File & provenance' }) });
+    await expect(provenance).toContainText('Selected local file · read in this browser');
+    await expect(provenance).toContainText('Local file; no saved library association was checked.');
+    await expect(provenance.locator('dt', { hasText: /^Path$/ })).toHaveCount(0);
+    await expect(rail(page).getByRole('button', { name: 'Show in folder', exact: true })).toHaveCount(0);
+    await expect(rail(page).getByRole('button', { name: /Prompt history/ })).toHaveCount(0);
+    await expect(rail(page).locator('.chip-row button.chip')).toHaveCount(0);
+    const original = viewer(page).getByRole('link', { name: 'Download original', exact: true });
+    await expect(original).toHaveAttribute('href', /^blob:/);
+    await expect(original).toHaveAttribute('download', 'f02.png');
+
+    await page.keyboard.press('Escape');
+    await expect(viewer(page)).toHaveCount(0);
+    await expect(action(page)).toBeFocused();
+    // Opening the viewer again shows the same record without reading the File a second time.
+    await page.evaluate(() => {
+        window.__slices = 0;
+        const slice = Blob.prototype.slice;
+        Blob.prototype.slice = function (...args) { if (this.name === 'f02.png') window.__slices++; return slice.apply(this, args); };
+    });
+    await openViewer(page);
+    expect(await railContent(rail(page))).toEqual(served);
+    expect(await page.evaluate(() => window.__slices)).toBe(0);
+});
+
+test('Import → Inspect a local image lands here', async ({ page }) => {
+    await page.goto(`${workspace}#/images`);
+    await page.getByRole('button', { name: 'Import', exact: true }).click();
+    const dialog = page.getByRole('dialog', { name: 'Import & inspect', exact: true });
+    await dialog.getByRole('button', { name: 'Open inspector', exact: true }).click();
+    await expect(page).toHaveURL(/#\/inspect$/);
+    await expect(main(page).getByRole('heading', { level: 1, name: 'Inspect a file', exact: true })).toBeVisible();
+    await expect(chooser(page)).toBeAttached();
+    await expect(main(page).locator('.handoff')).toHaveCount(0);
+    await expect(page.getByRole('dialog')).toHaveCount(0);
+});
+
+test('drop accepts exactly one File and never navigates', async ({ page }) => {
+    await openInspect(page);
+    // A drop that misses the area is cancelled, so the browser never opens the file in place of the page.
+    expect(await drop(page, 'body', { files: [parityPng('f02.png')] })).toEqual({ over: true, drop: true });
+    await expect(preview(page)).toBeEmpty();
+    expect(await drop(page, '.file-drop', { files: [parityPng('f02.png')] })).toEqual({ over: true, drop: true });
+    await expect(preview(page).locator('img.local-file-preview')).toBeVisible();
+    await expect(page.locator('#workspace-toast')).toHaveText(TOAST);
+    // The chooser names the dropped file, never the one it replaced and never "No file chosen".
+    expect(await chooser(page).evaluate(node => [...node.files].map(file => file.name))).toEqual(['f02.png']);
+    const first = await preview(page).locator('img').getAttribute('src');
+    // Two files, a link and markup keep the selection and say why.
+    await drop(page, '.file-drop', { files: [parityPng('f02.png'), parityPng('f03.png')] });
+    await expect(status(page)).toHaveText(COPY.multiple);
+    await expect(status(page)).toHaveAttribute('role', 'alert');
+    await expect(preview(page).locator('img')).toHaveAttribute('src', first);
+    for (const strings of [[['text/uri-list', 'https://example.invalid/a.png']], [['text/html', '<img src="https://example.invalid/a.png">']]]) {
+        await drop(page, '.file-drop', { strings });
+        await expect(status(page)).toHaveText(COPY.unsupported);
+        await expect(preview(page).locator('img')).toHaveAttribute('src', first);
+    }
+    await expect(action(page)).toHaveAttribute('aria-disabled', 'false');
+    await openViewer(page);
+    await expect(viewer(page).locator('#viewer-title')).toHaveText('f02.png');
+    await expect(page).toHaveURL(/#\/inspect$/);
+});
+
+test('cancel and same-file reselect', async ({ page }) => {
+    await instrument(page);
+    await openInspect(page);
+    await choose(page, parityPng('f02.png'));
+    await expect(preview(page).locator('img.local-file-preview')).toBeVisible();
+    const first = await preview(page).locator('img').getAttribute('src');
+    // The chooser still names the chosen file, as in the concept; a cancel (no files) keeps the page as it is.
+    expect(await chooser(page).evaluate(node => node.files[0]?.name)).toBe('f02.png');
+    await chooser(page).setInputFiles([]);
+    await expect(preview(page).locator('img')).toHaveAttribute('src', first);
+    await expect(status(page)).toHaveCount(0);
+    await expect(action(page)).toHaveAttribute('aria-disabled', 'false');
+    // Opening the picker and cancelling it keeps naming the live selection (modern engines fire `cancel`, not `change`).
+    await chooser(page).dispatchEvent('click');
+    await chooser(page).dispatchEvent('cancel');
+    expect(await chooser(page).evaluate(node => [...node.files].map(file => file.name))).toEqual(['f02.png']);
+    await expect(preview(page).locator('img')).toHaveAttribute('src', first);
+    await expect(action(page)).toHaveAttribute('aria-disabled', 'false');
+    // The same file again is a new selection with its own URL; the old one is released. Opening the picker clears
+    // the chooser, so the browser reports the same file as a change.
+    // (Read in the same task: a picker the click opens is cancelled by the harness, which names the file again.)
+    expect(await chooser(page).evaluate(node => { node.dispatchEvent(new MouseEvent('click')); return node.value; })).toBe('');
+    await choose(page, parityPng('f02.png'));
+    await expect(preview(page).locator('img')).not.toHaveAttribute('src', first);
+    await expect(preview(page).locator('img.local-file-preview')).toBeVisible();
+    const state = await urls(page);
+    expect(state.created).toHaveLength(2);
+    expect(state.revoked).toEqual([first]);
+    await openViewer(page);
+    await expect(viewer(page).locator('.media-position')).toHaveText('1 of 1 loaded: f02.png');
+});
+
+test('preview does not imply metadata support', async ({ page }) => {
+    await instrument(page);
+    await openInspect(page);
+    // JPEG and WebP preview and report no supported metadata, exactly as Images reports them.
+    for (const [file, format] of [[localFixture('tiny.jpg', 'image/jpeg'), 'JPEG'], [localFixture('tiny.webp', 'image/webp'), 'WEBP']]) {
+        await choose(page, file);
+        await expect(preview(page).locator('img.local-file-preview')).toBeVisible();
+        await openViewer(page);
+        await expect(rail(page)).toContainText('No supported embedded metadata was recorded in this file.');
+        await expect(rail(page).locator('details').first()).toContainText(format);
+        await page.keyboard.press('Escape');
+        await expect(viewer(page)).toHaveCount(0);
+    }
+    // A PNG whose text chunk fails its CRC: unreadable metadata, the original still downloads.
+    await choose(page, corruptPng());
+    await expect(action(page)).toHaveAttribute('aria-disabled', 'false');
+    await openViewer(page);
+    await expect(rail(page)).toContainText('Embedded metadata could not be read.');
+    const [download] = await Promise.all([page.waitForEvent('download'), viewer(page).getByRole('link', { name: 'Download original', exact: true }).click()]);
+    expect(download.suggestedFilename()).toBe('corrupt.png');
+    await page.keyboard.press('Escape');
+    await expect(viewer(page)).toHaveCount(0);
+    // Text, markup, SVG and a playlist under media names are unsupported and never get a URL.
+    const before = (await urls(page)).created.length;
+    for (const file of disguised()) {
+        await choose(page, file);
+        await expect(status(page)).toHaveText(COPY.unsupported);
+        await expect(status(page)).toHaveAttribute('role', 'alert');
+        await expect(preview(page).locator('img, video')).toHaveCount(0);
+        await expect(action(page)).toHaveAttribute('aria-disabled', 'true');
+    }
+    expect((await urls(page)).created).toHaveLength(before);
+});
+
+test('local video plays inline and in the viewer with real tags', async ({ page, browserName }) => {
+    await openInspect(page);
+    await choose(page, localFixture('core-tags.webm', 'video/webm'));
+    const video = preview(page).locator('video.local-file-preview');
+    await expect(video).toBeVisible();
+    expect(await video.evaluate(node => ({ controls: node.controls, playsInline: node.playsInline, preload: node.preload, muted: node.muted, autoplay: node.autoplay, paused: node.paused })))
+        .toEqual({ controls: true, playsInline: true, preload: 'metadata', muted: true, autoplay: false, paused: true });
+    // WebKit may not decode VP8: whichever state it reports, metadata is still read.
+    await expect.poll(() => video.evaluate(node => node.readyState >= 1 || !!node.error)).toBe(true);
+    await openViewer(page);
+    await expect(rail(page).locator('.prompt-section.positive p.prompt-text')).toHaveText('a red fox in snow, detailed fur');
+    await expect(rail(page).locator('.meta-grid').first().locator('dd').first()).toHaveText('7');
+    await expect(viewer(page).locator('#viewer-stage video')).toHaveCount(1);
+    await page.keyboard.press('Escape');
+    await choose(page, tinyWebm());
+    await expect(preview(page).locator('video.local-file-preview')).toBeVisible();
+    await openViewer(page);
+    await expect(rail(page)).toContainText('No supported embedded metadata was recorded in this file.');
+    if (browserName !== 'webkit') await expect.poll(() => viewer(page).locator('#viewer-stage video').evaluate(node => node.readyState >= 1)).toBe(true);
+});
+
+test('the toast and a rejected drop never contradict the status line', async ({ page }) => {
+    // A file whose bytes are gone after choosing: the status says its metadata cannot be read, so no toast says it is
+    // available.
+    await page.addInitScript(() => {
+        const slice = Blob.prototype.slice;
+        Blob.prototype.slice = function (...args) {
+            if (this.name === 'gone.png') return { arrayBuffer: () => Promise.reject(new DOMException('The file is gone', 'NotReadableError')) };
+            return slice.apply(this, args);
+        };
+    });
+    await openInspect(page);
+    await choose(page, parityPng('f02.png', 'gone.png'));
+    await expect(status(page)).toHaveText('Embedded metadata could not be read.');
+    await expect(action(page)).toHaveAttribute('aria-disabled', 'false');
+    await expect(page.locator('#workspace-toast')).toHaveText('');
+    // A rejected drop is its own alert beside the selection's status, which it never replaces, and it ends with the
+    // concept's toast interval.
+    await choose(page, undecodableMp4());
+    const failed = status(page).filter({ hasText: COPY.previewFailed });
+    await expect(failed).toHaveCount(1);
+    await drop(page, '.file-drop', { files: [parityPng('f02.png'), parityPng('f03.png')] });
+    const rejected = status(page).filter({ hasText: COPY.multiple });
+    await expect(rejected).toHaveAttribute('role', 'alert');
+    await expect(failed).toHaveCount(1);
+    await expect(rejected).toHaveCount(0, { timeout: 15000 });
+    await expect(status(page)).toHaveText([COPY.previewFailed]);
+    // The next selection attempt ends a rejection at once.
+    await drop(page, '.file-drop', { files: [parityPng('f02.png'), parityPng('f03.png')] });
+    await expect(rejected).toHaveCount(1);
+    await chooser(page).dispatchEvent('click');
+    await chooser(page).dispatchEvent('cancel');
+    await expect(status(page)).toHaveText([COPY.previewFailed]);
+});
+
+test('undecodable video keeps container metadata', async ({ page }) => {
+    await openInspect(page);
+    // A real MP4 whose sample entry names a codec no engine decodes; its container tags are intact.
+    await choose(page, undecodableMp4());
+    await expect(status(page)).toHaveText(COPY.previewFailed);
+    await expect(status(page)).toHaveAttribute('role', 'alert');
+    await expect(preview(page).locator('video')).toHaveCount(0);
+    await openViewer(page);
+    await expect(rail(page).locator('.prompt-section.positive p.prompt-text')).toHaveText('a red fox in snow, detailed fur');
+    await expect(rail(page).locator('.meta-grid').first().locator('dd').first()).toHaveText('7');
+});
+
+/** Records, for each revoked URL, how many elements (inline or in the viewer) still held it, and counts resets. */
+const trackReleases = page => page.evaluate(() => {
+    window.__released = [];
+    const revoke = URL.revokeObjectURL;
+    URL.revokeObjectURL = url => {
+        const live = [...document.querySelectorAll('img, video')].filter(node => node.getAttribute('src') === url);
+        window.__released.push({ url, live: live.length });
+        return revoke(url);
+    };
+    const load = HTMLMediaElement.prototype.load;
+    window.__loads = 0;
+    HTMLMediaElement.prototype.load = function () { if (!this.hasAttribute('src')) window.__loads++; return load.call(this); };
+});
+
+test('URLs and media end with their owning session', async ({ page }) => {
+    await instrument(page);
+    await openInspect(page);
+    // Every release pauses the media and drops its src before the URL is revoked.
+    await trackReleases(page);
+    await choose(page, localFixture('core-tags.webm', 'video/webm'));
+    await expect(preview(page).locator('video')).toBeVisible();
+    // A settled video (metadata read, or failed) is reset with load() when it is released.
+    await expect.poll(() => preview(page).locator('video').evaluate(node => node.readyState >= 1 || !!node.error)).toBe(true);
+    // Replacement.
+    await choose(page, parityPng('f02.png'));
+    await expect(preview(page).locator('img.local-file-preview')).toBeVisible();
+    let state = await urls(page);
+    expect(state.revoked).toEqual([state.created[0]]);
+    expect(await page.evaluate(() => window.__loads)).toBeGreaterThanOrEqual(1);
+    // Route change.
+    await page.locator('aside.sidebar nav').getByRole('link', { name: 'Overview', exact: true }).click();
+    await expect(main(page).getByRole('heading', { level: 1, name: 'Overview', exact: true })).toBeVisible();
+    state = await urls(page);
+    expect(state.revoked).toEqual(state.created);
+    // Five mount/unmount cycles with a selection and an opened viewer leave no live URL and no dialog.
+    for (let cycle = 0; cycle < 5; cycle++) {
+        await page.locator('aside.sidebar nav').getByRole('link', { name: 'Inspect a file', exact: true }).click();
+        await choose(page, parityPng('f02.png', `cycle-${cycle}.png`));
+        await openViewer(page);
+        // The modal viewer makes the sidebar inert, so the route changes underneath it.
+        await page.evaluate(() => { location.hash = '#/overview'; });
+        await expect(main(page).getByRole('heading', { level: 1, name: 'Overview', exact: true })).toBeVisible();
+    }
+    state = await urls(page);
+    expect(state.created).toHaveLength(7);
+    expect([...state.revoked].sort()).toEqual([...state.created].sort());
+    expect(new Set(state.revoked).size).toBe(state.revoked.length);
+    expect((await page.evaluate(() => window.__released)).every(entry => entry.live === 0)).toBe(true);
+    await expect(page.locator('dialog')).toHaveCount(0);
+    // Page leave releases the selection once.
+    await page.locator('aside.sidebar nav').getByRole('link', { name: 'Inspect a file', exact: true }).click();
+    await choose(page, parityPng('f02.png', 'leave.png'));
+    await expect(preview(page).locator('img.local-file-preview')).toBeVisible();
+    await page.evaluate(() => window.dispatchEvent(new PageTransitionEvent('pagehide', { persisted: false })));
+    state = await urls(page);
+    expect(state.created).toHaveLength(8);
+    expect(state.revoked.filter(url => url === state.created[7])).toHaveLength(1);
+    // Page leave with the viewer open, on a page loaded at Inspect (so its listeners precede the shell's): the viewer
+    // closes and releases its media before the URL is revoked, and a page restored from the back-forward cache shows
+    // an empty chooser beside the empty selection.
+    await page.reload();
+    await expect(chooser(page)).toBeAttached();
+    await trackReleases(page);
+    await choose(page, parityPng('f02.png', 'leave-open.png'));
+    await openViewer(page);
+    await expect(viewer(page).getByRole('button', { name: 'Zoom in', exact: true })).toHaveAttribute('aria-disabled', 'false');
+    await page.evaluate(() => window.dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true })));
+    await expect(page.locator('dialog')).toHaveCount(0);
+    state = await urls(page);
+    expect(state.created).toHaveLength(1);
+    expect(state.revoked).toEqual(state.created);
+    expect(await page.evaluate(() => window.__released)).toEqual([{ url: state.created[0], live: 0 }]);
+    await page.evaluate(() => window.dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true })));
+    await expect(chooser(page)).toBeAttached();
+    expect(await chooser(page).evaluate(node => ({ value: node.value, files: node.files.length }))).toEqual({ value: '', files: 0 });
+    await expect(preview(page).locator('img, video')).toHaveCount(0);
+    await expect(action(page)).toHaveAttribute('aria-disabled', 'true');
+});
+
+test('replacing a video that just started loading never blocks the page', async ({ context, browserName }) => {
+    test.setTimeout(120000);
+    // WebKit (GStreamer) blocked the page when a video whose pipeline was still starting was reset with load(): the
+    // next chooser selection, or the steps after it, never completed. Each fresh page replaces its first video as
+    // soon as it shows.
+    for (let attempt = 0; attempt < 15; attempt++) {
+        const page = await context.newPage();
+        try {
+            if (attempt === 0) await startCoverage(page, browserName);
+            await openInspect(page);
+            await choose(page, localFixture('core-tags.webm', 'video/webm'));
+            await expect(preview(page).locator('video.local-file-preview')).toBeVisible();
+            await chooser(page).setInputFiles(parityPng('f02.png'), { timeout: 8000 });
+            await expect(preview(page).locator('img.local-file-preview')).toBeVisible();
+            await expect(preview(page).locator('video')).toHaveCount(0);
+            if (attempt === 0) await saveCoverage(page, browserName);
+        } finally {
+            await page.close();
+        }
+    }
+});
+
+test('a video replaced while still starting is reset once it settles', async ({ context, browserName }) => {
+    // A WebKit (GStreamer) video released exactly at its `loadstart` sometimes blocks the page, with or without any
+    // reset and also with the code before the deferred reset (2 of 24 runs); tracked in TESTING.md (D62). WebKit's
+    // no-hang guard is `replacing a video that just started loading never blocks the page`.
+    test.skip(browserName === 'webkit', 'WebKit release at loadstart is a tracked follow-up (D62)');
+    test.setTimeout(120000);
+    // The video is replaced from its own `loadstart` (readyState HAVE_NOTHING). It leaves the page with no src before
+    // its URL is revoked, and is reset (load() with no src, which frees its decoder) only once it reports metadata or
+    // an error, so the page never blocks. Fresh pages share one browser process.
+    for (let attempt = 0; attempt < 5; attempt++) {
+        const page = await context.newPage();
+        try {
+            if (attempt === 0) await startCoverage(page, browserName);
+            await page.addInitScript(() => {
+                const load = HTMLMediaElement.prototype.load;
+                HTMLMediaElement.prototype.load = function () { if (!this.hasAttribute('src')) this.__resets = (this.__resets ?? 0) + 1; return load.call(this); };
+                const revoke = URL.revokeObjectURL;
+                URL.revokeObjectURL = url => {
+                    const starting = window.__starting;
+                    if (url === starting?.url) starting.revoked = { src: starting.node.hasAttribute('src'), connected: starting.node.isConnected, resets: starting.node.__resets ?? 0 };
+                    return revoke(url);
+                };
+            });
+            await openInspect(page);
+            await page.evaluate(() => {
+                const input = document.querySelector('#local-file'), slot = document.querySelector('#local-preview');
+                new MutationObserver((records, observer) => {
+                    const video = slot.querySelector('video');
+                    if (!video) return;
+                    observer.disconnect();
+                    video.addEventListener('loadstart', () => {
+                        window.__starting = { node: video, url: video.getAttribute('src'), readyState: video.readyState };
+                        input.files = window.__pngFiles; input.dispatchEvent(new Event('change', { bubbles: true }));
+                    }, { once: true });
+                }).observe(slot, { childList: true });
+            });
+            const png = parityPng('f02.png');
+            await page.evaluate(bytes => {
+                const transfer = new DataTransfer();
+                transfer.items.add(new File([new Uint8Array(bytes)], 'f02.png', { type: 'image/png' }));
+                window.__pngFiles = transfer.files;
+            }, [...png.buffer]);
+            await choose(page, localFixture('core-tags.webm', 'video/webm'));
+            await expect(preview(page).locator('img.local-file-preview')).toBeVisible({ timeout: 8000 });
+            await expect(preview(page).locator('video')).toHaveCount(0);
+            // Released while starting, and never reset synchronously: the URL went once the node had no src.
+            expect(await page.evaluate(() => ({ readyState: window.__starting.readyState, revoked: window.__starting.revoked })))
+                .toEqual({ readyState: 0, revoked: { src: false, connected: false, resets: 0 } });
+            await expect.poll(() => page.evaluate(() => window.__starting.node.__resets ?? 0), { timeout: 15000 }).toBe(1);
+            // The page still answers.
+            await chooser(page).setInputFiles(parityPng('f02.png', 'after.png'), { timeout: 8000 });
+            await expect(preview(page).locator('img.local-file-preview')).toBeVisible({ timeout: 8000 });
+            if (attempt === 0) await saveCoverage(page, browserName);
+        } finally {
+            await page.close();
+        }
+    }
+});
+
+test('closing the viewer on a video that just started never blocks the page', async ({ context, browserName }) => {
+    test.setTimeout(180000);
+    // The viewer's video teardown resets its element; on WebKit a reset of a still-starting pipeline blocked the page.
+    for (let attempt = 0; attempt < 15; attempt++) {
+        const page = await context.newPage();
+        try {
+            if (attempt === 0) await startCoverage(page, browserName);
+            await openInspect(page);
+            await choose(page, localFixture('core-tags.webm', 'video/webm'));
+            await openViewer(page);
+            await page.keyboard.press('Escape');
+            await expect(viewer(page)).toHaveCount(0, { timeout: 8000 });
+            await chooser(page).setInputFiles(parityPng('f02.png'), { timeout: 8000 });
+            await expect(preview(page).locator('img.local-file-preview')).toBeVisible({ timeout: 8000 });
+            if (attempt === 0) await saveCoverage(page, browserName);
+        } finally {
+            await page.close();
+        }
+    }
+});
+
+test('replacing a file mid-read never shows or sends the old record', async ({ page, context }) => {
+    const host = await bridgeHost(context);
+    try {
+        await openInspect(page);
+        // Hold every read of held.png after its classification prefix.
+        await page.evaluate(() => {
+            let release;
+            window.__gate = new Promise(resolve => { release = resolve; });
+            window.__releaseGate = release;
+            window.__held = 0;
+            const slice = Blob.prototype.slice;
+            Blob.prototype.slice = function (...args) {
+                const part = slice.apply(this, args);
+                if (this.name !== 'held.png' || (args[0] ?? 0) === 0 && (args[1] ?? this.size) <= 32) return part;
+                const read = part.arrayBuffer.bind(part);
+                part.arrayBuffer = async () => { window.__held++; await window.__gate; return read(); };
+                return part;
+            };
+        });
+        await choose(page, parityPng('f03.png', 'held.png'));
+        await expect.poll(() => page.evaluate(() => window.__held)).toBeGreaterThan(0);
+        await choose(page, sendablePng('fresh.png'));
+        await expect(preview(page).locator('img.local-file-preview')).toBeVisible();
+        await page.evaluate(() => window.__releaseGate());
+        await openViewer(page);
+        await expect(viewer(page).locator('#viewer-title')).toHaveText('fresh.png');
+        await expect(rail(page).locator('.prompt-section.positive p.prompt-text')).toHaveText(POSITIVE_LINES);
+        await sendPair(page);
+        expect(await host.evaluate(() => window.inspectApplied)).toEqual([{ positive: POSITIVE_LINES, negative: '' }]);
+    } finally {
+        await host.evaluate(() => window.inspectHost.dispose());
+        await host.close();
+    }
+});
+
+/** A second tab acting as a ComfyUI host with one Prompt Manager pair destination. */
+async function bridgeHost(context) {
+    const host = await context.newPage();
+    await host.goto(`${workspace}#/overview`);
+    await host.evaluate(async () => {
+        const { createBridgeHost } = await import('/prompt_manager/js/shared/toolkit/prompt-bridge.js');
+        const target = { id: 'pair-1', label: 'Inspect destination', type: 'PromptManagerPair', roles: ['positive', 'negative'] };
+        window.inspectApplied = [];
+        window.inspectPreviews = [];
+        window.inspectHost = createBridgeHost({ origin: location.origin, namespace: '/', label: 'Inspect ComfyUI', adapter: {
+            listTargets: () => [target],
+            preview: (_id, roles) => {
+                window.inspectPreviews.push(roles);
+                return { preview: { target, fields: Object.entries(roles).map(([role, after]) => ({ role, before: `Previous ${role}`, after })),
+                    composition: { prepend: '', append: '', prependConnected: false, appendConnected: false, before: 'Previous positive', after: roles.positive ?? 'Previous positive' } }, snapshot: roles };
+            },
+            apply: roles => { window.inspectApplied.push(roles); return { targetId: target.id, values: roles }; },
+        } });
+    });
+    return host;
+}
+
+async function sendPair(page) {
+    await rail(page).getByRole('button', { name: /^Send prompt pair to ComfyUI: / }).click();
+    const sender = page.getByRole('dialog', { name: 'Send to ComfyUI', exact: true });
+    await sender.getByRole('combobox', { name: 'ComfyUI window', exact: true }).selectOption({ label: 'Inspect ComfyUI' });
+    await sender.getByRole('combobox', { name: 'Destination node', exact: true }).selectOption({ label: 'Inspect destination' });
+    await sender.getByRole('button', { name: 'Preview changes', exact: true }).click();
+    await sender.getByRole('button', { name: 'Apply to ComfyUI', exact: true }).click();
+    await expect(sender).toContainText('Sent to ComfyUI.');
+    await sender.getByRole('button', { name: 'Close', exact: true }).click();
+}
+
+test('local roles send exactly', async ({ page, context }) => {
+    const host = await bridgeHost(context);
+    try {
+        await openInspect(page);
+        await choose(page, sendablePng());
+        await openViewer(page);
+        await expect(rail(page).locator('.prompt-section.positive p.prompt-text')).toHaveText(POSITIVE_LINES);
+        await expect(rail(page).locator('.prompt-section.negative p.prompt-text')).toHaveText('No negative prompt (explicitly empty)');
+        await sendPair(page);
+        const applied = await host.evaluate(() => window.inspectApplied);
+        expect(applied).toEqual([{ positive: POSITIVE_LINES, negative: '' }]);
+        const payload = JSON.stringify([applied, await host.evaluate(() => window.inspectPreviews)]);
+        expect(payload).not.toContain('blob:');
+        expect(payload).not.toContain('send-me');
+        // The viewer is still open, focus came back to the send action.
+        await expect(viewer(page)).toBeVisible();
+    } finally {
+        await host.evaluate(() => window.inspectHost.dispose());
+        await host.close();
+    }
+});
+
+test('local inspection makes no content request or storage write', async ({ page }) => {
+    await instrument(page);
+    await openInspect(page);
+    // The shell's own reads (counts, Activity) settle before the baseline.
+    await expect(page.locator('aside.sidebar nav [data-route="images"] .nav-count')).toBeAttached();
+    const baseline = (await urls(page)).writes.length;
+    const requests = [];
+    page.on('request', request => requests.push({ url: request.url(), method: request.method(), body: request.postData() }));
+    page.on('websocket', socket => requests.push({ url: socket.url(), method: 'WS', body: null }));
+    for (const file of [sendablePng('private-name.png'), localFixture('core-tags.webm', 'video/webm', 'private-clip.webm')]) {
+        await choose(page, file);
+        await openViewer(page);
+        await rail(page).locator('summary', { hasText: 'Workflow & raw metadata' }).click();
+        await page.keyboard.press('Escape');
+        await expect(viewer(page)).toHaveCount(0);
+    }
+    const network = requests.filter(entry => !entry.url.startsWith('blob:') && !entry.url.startsWith('data:'));
+    expect(network.filter(entry => /private|lighthouse|fox/.test(`${entry.url} ${entry.body ?? ''}`))).toEqual([]);
+    expect(network.filter(entry => entry.method !== 'GET')).toEqual([]);
+    expect(network.filter(entry => !/\/prompt_manager\/(activity|images\/output|library|vocabulary)/.test(entry.url))).toEqual([]);
+    expect((await urls(page)).writes.slice(baseline)).toEqual([]);
+});
+
+test('touch layout at 390 has no horizontal overflow at 200% zoom', async ({ page }) => {
+    await page.setViewportSize({ width: 390, height: 844 });
+    await openInspect(page);
+    await choose(page, parityPng('f02.png'));
+    await expect(preview(page).locator('img.local-file-preview')).toBeVisible();
+    for (const zoom of ['1', '2']) {
+        await page.evaluate(value => { document.documentElement.style.zoom = value; }, zoom);
+        await expect.poll(() => page.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth)).toBe(true);
+        const area = await page.locator('.file-drop').evaluate(node => node.getBoundingClientRect().right <= document.documentElement.clientWidth + 0.5);
+        expect(area).toBe(true);
+    }
+});

tests/browser/workspace-library-editor.spec.mjs

@@ -1,6 +1,6 @@
 import {writeFile} from 'node:fs/promises';
 import {startCoverage,saveCoverage} from '../../tools/vendor/browser-coverage.mjs';
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 import {captureCanonicalState} from './history-canonical-comparison.mjs';
 import {inventoryOf,mapConcept,diffInventory} from './library-editor-canonical-comparison.mjs';
 

tests/browser/workspace-library.spec.mjs

@@ -1,5 +1,5 @@
 import {startCoverage,saveCoverage} from '../../tools/vendor/browser-coverage.mjs';
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 
 const route='/prompt_manager/workspace#/library';
 const cards=page=>page.locator('article[data-prompt-id]');
@@ -25,6 +25,8 @@ async function loadShelfPages(page,more,pages) {
         await more.evaluate(node=>node.click());await response;await expect(more).toHaveAttribute('aria-disabled','false');
     }
 }
+/** Resolves in the rendering frame after every frame callback the page had already queued (callbacks run in request order). */
+const nextFrame=page=>page.evaluate(()=>new Promise(resolve=>requestAnimationFrame(()=>resolve())));
 async function openHistory(page,text='Cat portrait') {
     await cards(page).filter({has:page.getByText(text,{exact:true})}).getByRole('button',{name:'Explore history',exact:true}).click();
     await expect(history(page)).toBeVisible();
@@ -103,7 +105,8 @@ test('library infinite loading keeps unique parents and keyboard-accessible hist
         const appended=await (await nextPage).json();expect(appended.items.length).toBeGreaterThan(0);hasMore=appended.has_more;
         if(hasMore)await expect(more).toHaveAttribute('aria-disabled','false');
     }
-    await expect(more).toBeHidden();expect(await cards(page).count()).toBeLessThan(80);
+    // The last page's render queued the window update for the next frame; count after that frame, not before it.
+    await expect(more).toBeHidden();await nextFrame(page);expect(await cards(page).count()).toBeLessThan(80);
     const ids=await cards(page).evaluateAll(nodes=>nodes.map(node=>node.dataset.promptId));expect(new Set(ids).size).toBe(ids.length);
     await expect(page.getByRole('button',{name:/next page|previous page/i})).toHaveCount(0);
     const firstId=await cards(page).first().getAttribute('data-prompt-id');
@@ -253,6 +256,19 @@ test('returning from history restores library context and mobile content stays i
     await expect(history(page)).toHaveCount(0);await expect(page.locator('dialog[open]')).toHaveCount(0);
 });
 
+test('leaving the shelf before its first page answers and returning reads page one without a page error',async({page})=>{
+    // Hold the first shelf page so the route changes while the shelf is still loading (a slow CI runner's natural order).
+    let reached;const firstRead=new Promise(resolve=>{reached=resolve;});
+    await page.route(url=>url.pathname==='/prompt_manager/library'&&!url.searchParams.has('cursor'),route=>{reached();});
+    await page.goto(route);await firstRead;await expect(page.locator('.library-status')).toHaveText('Loading prompt library…');
+    await page.evaluate(()=>{window.location.hash='#/tags';});
+    await expect(page.locator('#workspace-main > .heading h1')).toHaveText('Tags & categories');
+    await page.unrouteAll({behavior:'ignoreErrors'});
+    await page.evaluate(()=>{window.location.hash='#/library';});
+    await expect(page.locator('#workspace-main > .heading h1')).toHaveText('Prompt library');
+    await expect(cards(page)).toHaveCount(3);await expect(page.locator('.section-caption')).toContainText('3 positive prompts');
+    expect(page.libraryErrors).toEqual([]);
+});
 test('empty shelf visits restore saved scroll without inventing a parent anchor',async({page})=>{
     await page.setViewportSize({width:1600,height:300});await page.goto(route);
     await page.getByRole('searchbox',{name:'Search workspace',exact:true}).fill('No matching saved positive');
@@ -376,14 +392,18 @@ async function observeLibrary(page, hold=false) {
             holdFrames(){holdingFrames=true;},
             releaseFrames(){holdingFrames=false;const callbacks=[...heldFrames.values()];heldFrames.clear();for(const callback of callbacks)callback();},
             equal(){for(const record of records){const entries=[...record.latest.values()].filter(entry=>record.targets.has(entry.target));if(entries.length)record.callback(entries,record.native);}},
+            // Resolves once two consecutive rendering frames find no Library frame queued. Each check runs inside a native
+            // frame callback, so a frame the page queues later in that update (a scroll event, a ResizeObserver delivery) is
+            // still pending there. A timer is not a frame: under CPU load a 60 ms wait could end before the scroll's frame.
+            // A frame that never drains (a rAF loop, or settling while frames are held) fails after `limit` frames with the stats.
+            settled(limit=600){return new Promise((resolve,reject)=>{let quiet=0,frames=0;const check=()=>{frames++;quiet=pending.size?0:quiet+1;
+                if(quiet>=2)resolve();else if(frames>=limit)reject(new Error(`Library never settled within ${limit} frames: ${JSON.stringify(window.libraryObservation.stats())}`));else raf(check);};raf(check);});},
             stats(){return {requested,pending:pending.size,heldFrames:heldFrames.size,measurements:records.reduce((sum,record)=>sum+record.entries.size,0),mutations,unmounted,targets:records.reduce((sum,record)=>sum+record.targets.size,0)};},
         };
     },{hold});
 }
 async function settleLibrary(page) {
-    await expect.poll(async()=>page.evaluate(()=>window.libraryObservation.stats().pending)).toBe(0);
-    await page.evaluate(()=>new Promise(resolve=>setTimeout(resolve,60)));
-    await expect.poll(async()=>page.evaluate(()=>window.libraryObservation.stats().pending)).toBe(0);
+    await page.evaluate(()=>window.libraryObservation.settled());
 }
 async function firstVisibleParent(page) {
     return cards(page).evaluateAll(nodes=>{
@@ -683,6 +703,17 @@ test('title and Explore history are buttons that open history',async({page,reque
     await page.keyboard.press('ArrowLeft');await expect(cards(page).nth(1).locator('.card-title > button')).toBeFocused();
 });
 
+test('settling fails with the observation stats when a Library frame stays queued',async({page,request})=>{
+    await request.post('/__test__/reset',{data:{native_library:true,extra_prompts:200}});
+    await observeLibrary(page);await page.addInitScript(()=>{window.IntersectionObserver=undefined;});
+    await page.goto(route);await expect(cards(page).first()).toBeVisible();await settleLibrary(page);
+    await page.evaluate(()=>{window.libraryObservation.holdFrames();dispatchEvent(new Event('scroll'));});
+    await expect.poll(()=>page.evaluate(()=>window.libraryObservation.stats().heldFrames)).toBeGreaterThan(0);
+    const failure=await page.evaluate(()=>window.libraryObservation.settled(30).then(()=>'settled',error=>error.message));
+    expect(failure).toMatch(/^Library never settled within 30 frames: \{.*"heldFrames":[1-9]/);
+    await page.evaluate(()=>window.libraryObservation.releaseFrames());await settleLibrary(page);
+});
+
 test('virtualized rows keep measured heights with the clamp',async({page,request,isMobile})=>{
     await request.post('/__test__/reset',{data:{native_library:true,extra_prompts:200}});
     await observeLibrary(page);await page.addInitScript(()=>{window.IntersectionObserver=undefined;});

tests/browser/workspace-saved-views.spec.mjs

@@ -1,5 +1,5 @@
 import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
-import { test, expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import { test, expect } from './fixtures.mjs';
 
 // Saved views (#249 D16, maintainer ruling 2026-10-21): the toolbar's Save view (concept app.js a359, a1330–1346),
 // the sidebar SAVED VIEWS rows (a331–335) and `#/saved/<id>` (a1158–1162), on Images and the Prompt library.

tests/browser/workspace-tagging-lifecycle.spec.mjs

@@ -0,0 +1,71 @@
+// The Tag image dialog's capture lifetime when the page or the dialog goes away mid-flight (#249 PR C final review I4,
+// I5), run on all four projects: leaving the page with the dialog open releases the capture (a `keepalive` DELETE sent
+// on `pagehide`, which also closes the dialog), and closing the dialog while its save is in flight keeps the capture
+// until the save settles, then still reports the save. The fixture is tests/browser/workspace_tagging_fixture.py.
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+
+const images = '/prompt_manager/workspace#/images';
+const FIRST = 'tagging/dunes_00001.png';
+const TAGS_URL = '**/prompt_manager/image-annotations/tags';
+const dialog = page => page.getByRole('dialog', { name: 'Tag image', exact: true });
+const manual = page => dialog(page).getByRole('textbox', { name: 'Image tags · edit manually', exact: true });
+const tagButton = page => page.locator(`article[data-image-key="0:${FIRST}"]`).getByRole('button', { name: 'Tag or auto-tag dunes_00001.png', exact: true });
+const openCaptures = async request => (await (await request.get('/__test__/tagging/captures')).json()).captures;
+
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    await expect(await request.post('/__test__/tagging/reset', { data: {} })).toBeOK();
+    page.problems = [];
+    page.on('pageerror', error => page.problems.push(`pageerror: ${error.message}`));
+    page.on('console', message => { if (message.type() === 'error') page.problems.push(`console: ${message.text()}`); });
+});
+test.afterEach(async ({ page, browserName }) => {
+    await saveCoverage(page, browserName);
+    expect(page.problems).toEqual([]);
+});
+
+async function openTag(page) {
+    await page.goto(images);
+    const observed = page.waitForResponse(item => item.url().endsWith('/image-annotations/observe'));
+    await tagButton(page).click();
+    await expect(dialog(page)).toBeVisible();
+    expect((await observed).status()).toBe(200);
+    await expect(manual(page)).toBeEditable();
+}
+
+test('leaving the page with the dialog open releases its capture without a console error (I4)', async ({ page, request }) => {
+    await openTag(page);
+    expect(await openCaptures(request)).toBe(1);
+    // Another document: the old one's pagehide closes the dialog and sends the release with keepalive.
+    await page.goto('/prompt_manager/workspace?left=1#/tags');
+    await expect(page.locator('#workspace-main h1')).toHaveText('Tags & categories');
+    await expect.poll(() => openCaptures(request)).toBe(0);
+    await expect(dialog(page)).toHaveCount(0);
+});
+
+test('closing the dialog during a save releases the capture after the save and still reports it (I5)', async ({ page, request }) => {
+    await openTag(page);
+    await manual(page).fill('saved_after_close');
+    const order = [];
+    page.on('response', item => { if (item.url().endsWith('/image-annotations/tags')) order.push(`PUT ${item.status()}`); });
+    page.on('request', item => { if (item.url().includes('/image-annotations/capture/') && item.method() === 'DELETE') order.push('DELETE'); });
+    let release;
+    const held = new Promise(resolve => { release = resolve; });
+    const sent = new Promise(resolve => {
+        page.route(TAGS_URL, async route => { resolve(); await held; await route.continue(); });
+    });
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await sent;
+    await page.keyboard.press('Escape');
+    await expect(dialog(page)).toHaveCount(0);
+    expect(await openCaptures(request)).toBe(1);
+    expect(order).toEqual([]);
+    release();
+    await expect(page.locator('#workspace-toast')).toHaveText('1 tags saved for dunes_00001.png.');
+    await expect.poll(() => order).toEqual(['PUT 200', 'DELETE']);
+    await expect.poll(() => openCaptures(request)).toBe(0);
+    // The page followed the late save: the selected file's details show the new image tag.
+    await expect(page.getByRole('complementary', { name: 'Selected image details', exact: true }).getByText('saved_after_close', { exact: true })).toBeVisible();
+    await page.unroute(TAGS_URL);
+});

tests/browser/workspace-tagging.spec.mjs

@@ -0,0 +1,749 @@
+// The Tag image dialog, the card Tag button and the Tags page hooks (#249 PR C, plan Task C2, Mock inventory M1, M2, M5)
+// against the real routes and the injected fake model (tests/browser/workspace_tagging_fixture.py). No model is ever
+// downloaded or loaded: the fake answers, and every test checks that no download request was sent.
+import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
+import { test, expect } from './fixtures.mjs';
+import { saveImageTags } from './concept-inventory.mjs';
+import { taggingInventory } from './tagging-canonical-comparison.mjs';
+
+const images = '/prompt_manager/workspace#/images';
+const MODULE = '/prompt_manager/js/workspace/image-tagging.mjs';
+const MODEL_LABELS = ['WD14 SwinV2 · ~400 MB', 'WD14 ViT · ~400 MB', 'GGUF JoyCaption (Recommended) · ~4.5 GB', 'HuggingFace JoyCaption · ~16 GB'];
+// The concept's on-screen opening sentence (its renderTagModelOptions replaces the markup's at once, D83).
+const MODEL_CHANGED = 'Generate suggestions with the selected model before approving.';
+const CHIP_HINT = 'Remove anything you do not want to add.';
+const ALL_REMOVED = 'All suggestions removed. Generate again or enter tags manually.';
+const card = (page, path) => page.locator(`article[data-image-key="0:${path}"]`);
+const tagButton = (page, path) => card(page, path).getByRole('button', { name: `Tag or auto-tag ${path.split('/').pop()}`, exact: true });
+const dialog = page => page.getByRole('dialog', { name: 'Tag image', exact: true });
+const manual = page => dialog(page).getByRole('textbox', { name: 'Image tags · edit manually', exact: true });
+const model = page => dialog(page).getByRole('combobox', { name: 'Tagging model', exact: true });
+const generate = page => dialog(page).getByRole('button', { name: 'Generate suggestions', exact: true });
+const chips = page => dialog(page).locator('#tag-suggestions .chip.tag-suggestion');
+const status = page => dialog(page).locator('#tag-generation-status');
+const toast = page => page.locator('#workspace-toast');
+const nav = (page, label) => page.locator('aside.sidebar nav').getByRole('link', { name: new RegExp(`^${label}(?:\\s*[\\d,]+)?$`) });
+const FIRST = 'tagging/dunes_00001.png', SECOND = 'tagging/dunes_00002.png', COPY = 'copies/dunes_00001.png';
+const VIDEO = 'tagging/clip.webm', UNLINKED = 'loose/unlinked.png';
+
+let manifest;
+test.beforeEach(async ({ page, request, browserName }) => {
+    await startCoverage(page, browserName);
+    const response = await request.post('/__test__/tagging/reset', { data: {} });
+    await expect(response).toBeOK();
+    manifest = await response.json();
+    page.taggingErrors = [];
+    page.on('pageerror', error => page.taggingErrors.push(error.message));
+    page.downloads = [];
+    page.on('request', item => { if (/\/autotag\/download\//.test(item.url())) page.downloads.push(item.url()); });
+});
+test.afterEach(async ({ page, browserName }) => {
+    await saveCoverage(page, browserName);
+    expect(page.taggingErrors).toEqual([]);
+    expect(page.downloads).toEqual([]);
+});
+
+/** Images, then the Tag dialog of `path`, settled on its observation (the manual field holds the saved tags). */
+async function openTag(page, path = FIRST, { goto = true } = {}) {
+    if (goto) await page.goto(images);
+    const observed = page.waitForResponse(item => item.url().endsWith('/image-annotations/observe'));
+    await tagButton(page, path).click();
+    await expect(dialog(page)).toBeVisible();
+    expect((await observed).status()).toBe(200);
+    await expect(dialog(page).locator('img.tag-image-preview, video.tag-image-preview')).toHaveAttribute('src', /\/prompt_manager\/image-annotations\/capture\//);
+}
+async function generated(page) {
+    const answer = page.waitForResponse(item => item.url().endsWith('/image-annotations/suggest'));
+    await generate(page).click();
+    return answer;
+}
+/** Read the saved tags of `path` through the real observe route, then release that capture. */
+async function savedTags(request, path) {
+    const target = { root_index: 0, root_scope: await scopeOf(request), path };
+    const observed = await (await request.post('/prompt_manager/image-annotations/observe', { data: { target } })).json();
+    expect(observed.success).toBe(true);
+    await request.delete(`/prompt_manager/image-annotations/capture/${observed.capture.token}`);
+    return observed.tags;
+}
+async function scopeOf(request) {
+    const listing = await (await request.get('/prompt_manager/images/output?mode=workspace&limit=40')).json();
+    return listing.images[0].root_scope;
+}
+
+test('tag dialog control inventory and order match M2', async ({ page }) => {
+    await openTag(page);
+    await expect(page.locator('dialog#modal')).toHaveClass(/(^| )tagging-modal( |$)/);
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Tag image');
+    const body = dialog(page).locator('#modal-body');
+    expect(await body.evaluate(node => [...node.children].map(child => child.className))).toEqual(
+        ['tag-image-heading', 'field', 'tag-model-panel', 'tag-suggestion-panel', 'dialog-actions']);
+    const heading = body.locator('.tag-image-heading');
+    await expect(heading.locator('h3')).toHaveText(manifest.title);
+    await expect(heading.locator('p.small')).toHaveText('dunes_00001.png');
+    await expect(heading.locator('span.chip')).toHaveText('96 × 64');
+    await expect(heading.locator('img.tag-image-preview')).toHaveAttribute('alt', manifest.title);
+    await expect(body.locator('.tag-scope-note')).toHaveCount(0);
+    await expect(manual(page)).toHaveAttribute('id', 'manual-image-tags');
+    await expect(manual(page)).toHaveValue('');
+    await expect(manual(page)).toHaveAccessibleDescription('Comma-separated. Generated suggestions are added only after you approve them.');
+    const panel = body.locator('.tag-model-panel');
+    await expect(panel.locator('h3')).toHaveText('Auto-tag this image');
+    await expect(model(page).locator('option')).toHaveText(MODEL_LABELS);
+    expect(await model(page).locator('option').evaluateAll(nodes => nodes.map(node => node.value))).toEqual(['wd14-swinv2', 'wd14-vit', 'gguf', 'hf']);
+    await expect(model(page)).toHaveValue('wd14-swinv2');
+    const options = panel.locator('#image-tag-model-options');
+    const general = options.getByRole('spinbutton', { name: 'General confidence', exact: true });
+    const character = options.getByRole('spinbutton', { name: 'Character confidence', exact: true });
+    const limit = options.getByRole('spinbutton', { name: 'Suggestions', exact: true });
+    await expect(options.locator('.two-col .field')).toHaveCount(2);
+    await expect(general).toHaveValue('0.35');
+    await expect(character).toHaveValue('0.85');
+    await expect(limit).toHaveValue('10');
+    for (const [input, attributes] of [[general, ['0', '1', '0.05']], [character, ['0', '1', '0.05']], [limit, ['1', '100', '1']]]) {
+        expect(await input.evaluate(node => [node.min, node.max, node.step])).toEqual(attributes);
+    }
+    await expect(generate(page)).toHaveClass(/ca-primary/);
+    await expect(generate(page).locator('svg.icon')).toHaveCount(1);
+    const suggestions = body.locator('section.tag-suggestion-panel');
+    await expect(suggestions).toHaveAttribute('aria-labelledby', 'tag-suggestions-title');
+    await expect(suggestions.locator('h3#tag-suggestions-title')).toHaveText('Review suggestions');
+    await expect(suggestions.locator('#suggestion-count')).toHaveText('Not generated');
+    await expect(suggestions.locator('#tag-suggestions > p.small')).toHaveText(MODEL_CHANGED);
+    await expect(status(page)).toHaveAttribute('role', 'status');
+    await expect(status(page)).toHaveText('');
+    await expect(body.locator('.dialog-actions button')).toHaveText(['Cancel', 'Save manual tags']);
+    await expect(body.locator('.dialog-actions button').last()).toHaveClass(/ca-primary/);
+    await model(page).selectOption('gguf');
+    await expect(options.getByRole('textbox', { name: 'Tagging instructions', exact: true })).toHaveValue('Describe the image');
+    await expect(options.getByRole('spinbutton', { name: 'Suggestions', exact: true })).toHaveValue('10');
+    await expect(options.locator('.two-col')).toHaveCount(0);
+});
+
+test('generate shows real fixture percentages for WD14 and Suggested for GGUF, at most ten chips', async ({ page }) => {
+    await openTag(page);
+    const answer = await generated(page);
+    expect(answer.request().postDataJSON()).toMatchObject({ model_type: 'wd14-swinv2', options: { general_threshold: 0.35, character_threshold: 0.85, suggestion_limit: 10 } });
+    await expect(chips(page)).toHaveCount(10);
+    // D83: ruling T4's instruction leads the chips, only while chips exist.
+    await expect(dialog(page).locator('#tag-suggestions > *')).toHaveCount(2);
+    await expect(dialog(page).locator('#tag-suggestions > p.small')).toHaveText(CHIP_HINT);
+    await expect(chips(page).first().locator(':scope > span').first()).toHaveText('sandstone');
+    await expect(chips(page).locator('.tag-confidence').first()).toHaveText('98%');
+    await expect(chips(page).nth(1).locator('.tag-confidence')).toHaveText('97%');
+    await expect(chips(page).first().getByRole('button', { name: 'Remove sandstone', exact: true })).toBeVisible();
+    await expect(dialog(page).locator('#suggestion-count')).toHaveText('10 suggestions');
+    await expect(status(page)).toHaveText('Suggestions from WD14 SwinV2 · ~400 MB. Approve tags to save.');
+    await expect(dialog(page).locator('.dialog-actions .ca-primary')).toHaveText('Approve selected tags');
+    for (const id of ['gguf', 'hf']) {
+        await model(page).selectOption(id);
+        await expect(chips(page)).toHaveCount(0);
+        await generated(page);
+        await expect(chips(page)).toHaveCount(10);
+        await expect(chips(page).locator('.tag-confidence')).toHaveText(Array(10).fill('Suggested'));
+        await expect(status(page)).toHaveText(`Suggestions from ${MODEL_LABELS[id === 'gguf' ? 2 : 3]}. Approve tags to save.`);
+    }
+    await dialog(page).getByRole('spinbutton', { name: 'Suggestions', exact: true }).fill('3');
+    const fewer = await generated(page);
+    expect(fewer.request().postDataJSON().options).toEqual({ instructions: 'Describe the image', suggestion_limit: 3 });
+    await expect(chips(page)).toHaveCount(3);
+    await expect(dialog(page).locator('#suggestion-count')).toHaveText('3 suggestions');
+});
+
+test('removing chips and editing manually then approving persists across reload', async ({ page, request }) => {
+    await openTag(page);
+    await manual(page).fill('Minimal, sky_blue');
+    await dialog(page).getByRole('spinbutton', { name: 'Suggestions', exact: true }).fill('3');
+    await generated(page);
+    await expect(chips(page)).toHaveCount(3);
+    const remove = dialog(page).getByRole('button', { name: 'Remove desert', exact: true });
+    await remove.click();
+    await expect(chips(page)).toHaveCount(2);
+    // Focus moves to the next chip's ×.
+    await expect(dialog(page).getByRole('button', { name: 'Remove arch', exact: true })).toBeFocused();
+    const saved = page.waitForResponse(item => item.url().endsWith('/image-annotations/tags') && item.request().method() === 'PUT');
+    await dialog(page).getByRole('button', { name: 'Approve selected tags', exact: true }).click();
+    expect((await saved).request().postDataJSON().tags).toEqual(['Minimal', 'sky_blue', 'sandstone', 'arch']);
+    await expect(dialog(page)).toHaveCount(0);
+    await expect(toast(page)).toHaveText('4 tags saved for dunes_00001.png.');
+    await expect(tagButton(page, FIRST)).toBeFocused();
+    expect(await savedTags(request, FIRST)).toEqual(['Minimal', 'sky_blue', 'sandstone', 'arch']);
+    await page.reload();
+    await openTag(page, FIRST, { goto: false });
+    await expect(manual(page)).toHaveValue('Minimal, sky_blue, sandstone, arch');
+    // Removing every chip shows the all-removed copy; the manual set still saves.
+    await dialog(page).getByRole('spinbutton', { name: 'Suggestions', exact: true }).fill('2');
+    await generated(page);
+    for (const name of ['sandstone', 'desert']) await dialog(page).getByRole('button', { name: `Remove ${name}`, exact: true }).click();
+    await expect(dialog(page).locator('#tag-suggestions > p.small')).toHaveText(ALL_REMOVED);
+    await expect(generate(page)).toBeFocused();
+    await dialog(page).getByRole('button', { name: 'Approve selected tags', exact: true }).click();
+    await expect(toast(page)).toHaveText('4 tags saved for dunes_00001.png.');
+});
+
+test('cancel escape and close write nothing', async ({ page, request }) => {
+    const writes = [];
+    page.on('request', item => { if (item.url().endsWith('/image-annotations/tags')) writes.push(item.method()); });
+    await page.goto(images);
+    for (const dismiss of [
+        () => dialog(page).getByRole('button', { name: 'Cancel', exact: true }).click(),
+        () => page.keyboard.press('Escape'),
+        () => dialog(page).getByRole('button', { name: 'Close dialog', exact: true }).click(),
+    ]) {
+        const released = page.waitForResponse(item => item.url().includes('/image-annotations/capture/') && item.request().method() === 'DELETE');
+        await openTag(page, FIRST, { goto: false });
+        await manual(page).fill('never_saved');
+        await dismiss();
+        await expect(dialog(page)).toHaveCount(0);
+        expect((await released).ok()).toBe(true);
+        await expect(tagButton(page, FIRST)).toBeFocused();
+        await expect(page.locator('dialog#modal.tagging-modal')).toHaveCount(0);
+    }
+    expect(writes).toEqual([]);
+    expect(await savedTags(request, FIRST)).toEqual([]);
+});
+
+test('model change discards suggestions and relabels primary', async ({ page }) => {
+    await openTag(page);
+    await manual(page).fill('kept');
+    await generated(page);
+    await expect(dialog(page).locator('.dialog-actions .ca-primary')).toHaveText('Approve selected tags');
+    await dialog(page).getByRole('spinbutton', { name: 'General confidence', exact: true }).fill('0.5');
+    await model(page).selectOption('wd14-vit');
+    await expect(chips(page)).toHaveCount(0);
+    await expect(dialog(page).locator('#tag-suggestions > p.small')).toHaveText(MODEL_CHANGED);
+    await expect(dialog(page).locator('#suggestion-count')).toHaveText('Not generated');
+    await expect(status(page)).toHaveText('');
+    await expect(dialog(page).locator('.dialog-actions .ca-primary')).toHaveText('Save manual tags');
+    await expect(manual(page)).toHaveValue('kept');
+    // Like the concept, the new model's fields start from the defaults.
+    await expect(dialog(page).getByRole('spinbutton', { name: 'General confidence', exact: true })).toHaveValue('0.35');
+});
+
+test('invalid threshold reports validity without request', async ({ page }) => {
+    const sent = [];
+    page.on('request', item => { if (item.url().endsWith('/image-annotations/suggest')) sent.push(item.url()); });
+    await openTag(page);
+    const general = dialog(page).getByRole('spinbutton', { name: 'General confidence', exact: true });
+    await general.fill('1.5');
+    await generate(page).click();
+    await expect(general).toBeFocused();
+    expect(await general.evaluate(node => node.validity.rangeOverflow)).toBe(true);
+    await general.fill('');
+    await generate(page).click();
+    await expect.poll(() => general.evaluate(node => node.validationMessage)).toBe('Enter a confidence from 0 to 1.');
+    await general.fill('0.35');
+    expect(await general.evaluate(node => node.validity.valid)).toBe(true);
+    await model(page).selectOption('gguf');
+    const instructions = dialog(page).getByRole('textbox', { name: 'Tagging instructions', exact: true });
+    await instructions.fill('   ');
+    await generate(page).click();
+    await expect.poll(() => instructions.evaluate(node => node.validationMessage)).toBe('Enter tagging instructions of at most 4000 characters.');
+    await expect(status(page)).toHaveText('');
+    expect(sent).toEqual([]);
+});
+
+test('unavailable model shows inline status and never downloads', async ({ page, request }) => {
+    await expect(await request.post('/__test__/tagging/models', { data: { unavailable: ['wd14-swinv2'] } })).toBeOK();
+    await openTag(page);
+    expect((await generated(page)).status()).toBe(409);
+    await expect(status(page)).toHaveText('WD14 SwinV2 is not downloaded. Download it from the legacy Auto-tag page.');
+    await expect(chips(page)).toHaveCount(0);
+    await expect(dialog(page).locator('#suggestion-count')).toHaveText('Not generated');
+    // D116: Retry leads the actions while the controller allows it, and generates again.
+    await expect(dialog(page).locator('.dialog-actions button')).toHaveText(['Retry', 'Cancel', 'Save manual tags']);
+    await expect(await request.post('/__test__/tagging/models', { data: { unavailable: [] } })).toBeOK();
+    const again = page.waitForResponse(item => item.url().endsWith('/image-annotations/suggest'));
+    await dialog(page).getByRole('button', { name: 'Retry', exact: true }).click();
+    expect((await again).status()).toBe(200);
+    await expect(chips(page)).toHaveCount(10);
+    await expect(dialog(page).locator('.dialog-actions button')).toHaveText(['Cancel', 'Approve selected tags']);
+    await expect(dialog(page).locator('.dialog-actions .ca-primary')).toBeFocused();
+});
+
+test('video tag is manual only', async ({ page, request }) => {
+    await openTag(page, VIDEO);
+    const preview = dialog(page).locator('video.tag-image-preview');
+    await expect(preview).toHaveAttribute('preload', 'metadata');
+    expect(await preview.evaluate(node => node.muted)).toBe(true);
+    await expect(dialog(page).locator('.tag-image-heading span.chip')).toHaveCount(0);
+    await expect(generate(page)).toHaveAttribute('aria-disabled', 'true');
+    await expect(status(page)).toHaveText('Auto-tagging is available for supported still images only.');
+    let suggested = false;
+    page.on('request', item => { if (item.url().endsWith('/image-annotations/suggest')) suggested = true; });
+    // Pressing the aria-disabled Generate sends nothing.
+    await generate(page).focus();
+    await page.keyboard.press('Enter');
+    await manual(page).fill('clip_tag');
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await expect(toast(page)).toHaveText('1 tags saved for clip.webm.');
+    expect(suggested).toBe(false);
+    expect(await savedTags(request, VIDEO)).toEqual(['clip_tag']);
+});
+
+test('sticky footer reachable at 390x844 while content scrolls', async ({ page }) => {
+    await page.setViewportSize({ width: 390, height: 844 });
+    await openTag(page);
+    await model(page).selectOption('gguf');
+    await generated(page);
+    await expect(chips(page)).toHaveCount(10);
+    const shell = page.locator('dialog#modal');
+    const actions = dialog(page).locator('.dialog-actions');
+    expect(await actions.evaluate(node => getComputedStyle(node).position)).toBe('sticky');
+    expect(await shell.evaluate(node => node.scrollHeight > node.clientHeight)).toBe(true);
+    for (const top of [0, 10_000]) {
+        await shell.evaluate((node, value) => { node.scrollTop = value; }, top);
+        const box = await actions.boundingBox(), frame = await shell.boundingBox();
+        expect(box.y + box.height).toBeLessThanOrEqual(frame.y + frame.height + 1);
+        expect(box.y).toBeGreaterThanOrEqual(frame.y);
+        await expect(dialog(page).getByRole('button', { name: 'Approve selected tags', exact: true })).toBeInViewport();
+    }
+    expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth + 1)).toBe(true);
+});
+
+test('focus starts on close and returns to the Tag trigger', async ({ page }) => {
+    await openTag(page, SECOND);
+    await expect(dialog(page).getByRole('button', { name: 'Close dialog', exact: true })).toBeFocused();
+    await page.keyboard.press('Escape');
+    await expect(dialog(page)).toHaveCount(0);
+    await expect(tagButton(page, SECOND)).toBeFocused();
+});
+
+test('every Images and Library gallery card has Info then Tag with mock labels', async ({ page }) => {
+    const expectCards = async locator => {
+        const labels = await locator.evaluateAll(nodes => nodes.map(node => {
+            const buttons = [...node.querySelectorAll('.media-info > .image-card-actions > button')];
+            return { file: node.querySelector('.image-open').getAttribute('aria-label').replace(/^Open /, ''),
+                buttons: buttons.map(button => [button.className, button.getAttribute('aria-label'), button.querySelector('svg.icon') !== null]) };
+        }));
+        expect(labels.length).toBeGreaterThan(0);
+        for (const { file, buttons } of labels) {
+            expect(buttons).toEqual([['icon-btn', `Inspect ${file}`, true], ['icon-btn', `Tag or auto-tag ${file}`, true]]);
+        }
+        return labels.map(({ file }) => file);
+    };
+    await page.goto(images);
+    await expect(page.locator('article[data-image-key]')).toHaveCount(manifest.files.length);
+    expect(await expectCards(page.locator('article[data-image-key]'))).toEqual(manifest.files.map(file => file.filename));
+    await page.goto(`/prompt_manager/workspace#/library/${manifest.positive_id}`);
+    const gallery = page.locator('.library-history .history-gallery article[data-image-key]');
+    await expect(gallery.first()).toBeVisible();
+    await expectCards(gallery);
+    const observed = page.waitForResponse(item => item.url().endsWith('/image-annotations/observe'));
+    await gallery.first().getByRole('button', { name: /^Tag or auto-tag / }).click();
+    await expect(dialog(page)).toBeVisible();
+    expect((await observed).status()).toBe(200);
+    await dialog(page).getByRole('button', { name: 'Cancel', exact: true }).click();
+    await expect(gallery.first().getByRole('button', { name: /^Tag or auto-tag / })).toBeFocused();
+});
+
+test('Tag opens the dialog without selecting the card', async ({ page }) => {
+    const panel = page.getByRole('complementary', { name: 'Selected image details', exact: true });
+    await page.goto(images);
+    await expect(card(page, FIRST)).toHaveClass(/\bselected\b/);
+    const before = await panel.innerText();
+    await openTag(page, SECOND, { goto: false });
+    await page.keyboard.press('Escape');
+    await expect(card(page, SECOND)).not.toHaveClass(/\bselected\b/);
+    await expect(card(page, FIRST)).toHaveClass(/\bselected\b/);
+    expect(await panel.innerText()).toBe(before);
+});
+
+test('tagging one of two cards sharing a prompt leaves the other card, the prompt and the pair unchanged', async ({ page, request }) => {
+    const before = await (await request.get('/__test__/tagging/snapshot')).json();
+    expect(await savedTags(request, SECOND)).toEqual([]);
+    expect(await savedTags(request, COPY)).toEqual([]);
+    const pairBefore = await (await request.get(`/prompt_manager/library/${manifest.positive_id}`)).json();
+    await openTag(page, FIRST);
+    await manual(page).fill('only_this_file');
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await expect(toast(page)).toHaveText('1 tags saved for dunes_00001.png.');
+    expect(await savedTags(request, FIRST)).toEqual(['only_this_file']);
+    expect(await savedTags(request, SECOND)).toEqual([]);
+    expect(await savedTags(request, COPY)).toEqual([]);
+    expect(await (await request.get('/__test__/tagging/snapshot')).json()).toEqual(before);
+    const pairAfter = await (await request.get(`/prompt_manager/library/${manifest.positive_id}`)).json();
+    expect(pairAfter.success).toBe(true);
+    expect({ ...pairAfter, library_epoch: null }).toEqual({ ...pairBefore, library_epoch: null });
+});
+
+test('Tags page Auto-tag images opens the dialog for the selected image and is disabled without one', async ({ page }) => {
+    await page.goto('/prompt_manager/workspace#/tags');
+    const autoTag = page.locator('#workspace-main .heading-actions').getByRole('button', { name: 'Auto-tag images', exact: true });
+    await expect(page.locator('#workspace-main .heading-actions button')).toHaveText(['+ Create tag', 'Auto-tag images']);
+    await expect(autoTag).toHaveClass(/ca-primary/);
+    await expect(autoTag).toHaveAttribute('aria-disabled', 'true');
+    // An aria-disabled control still takes a press; it only explains.
+    await autoTag.focus();
+    await page.keyboard.press('Enter');
+    await expect(toast(page)).toHaveText('Select an image in Images first.');
+    await expect(dialog(page)).toHaveCount(0);
+    await nav(page, 'Images').click();
+    await card(page, SECOND).getByRole('button', { name: 'Inspect dunes_00002.png', exact: true }).click();
+    await expect(card(page, SECOND)).toHaveClass(/selected/);
+    await nav(page, 'Tags & categories').click();
+    await expect(autoTag).not.toHaveAttribute('aria-disabled', 'true');
+    const observed = page.waitForResponse(item => item.url().endsWith('/image-annotations/observe'));
+    await autoTag.click();
+    expect((await observed).request().postDataJSON().target.path).toBe(SECOND);
+    await expect(dialog(page).locator('.tag-image-heading p.small')).toHaveText('dunes_00002.png');
+    await page.keyboard.press('Escape');
+    await expect(autoTag).toBeFocused();
+});
+
+test('Images column shows image_count and updates after save', async ({ page }) => {
+    await page.goto(images);
+    await card(page, FIRST).getByRole('button', { name: 'Inspect dunes_00001.png', exact: true }).click();
+    await nav(page, 'Tags & categories').click();
+    const row = name => page.locator('#workspace-main table tbody tr').filter({ has: page.locator('td:first-child').getByText(name, { exact: true }) });
+    await expect(row('minimal').locator('td:nth-child(3)')).toHaveText('0');
+    await expect(row('editorial').locator('td:nth-child(3)')).toHaveText('0');
+    await page.locator('#workspace-main .heading-actions').getByRole('button', { name: 'Auto-tag images', exact: true }).click();
+    await expect(manual(page)).toBeVisible();
+    await expect(dialog(page).locator('img.tag-image-preview')).toHaveAttribute('src', /capture/);
+    await manual(page).fill('minimal, editorial');
+    const reread = page.waitForResponse(item => item.url().includes('/prompt_manager/vocabulary/tags'));
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await reread;
+    await expect(row('minimal').locator('td:nth-child(3)')).toHaveText('1');
+    await expect(row('editorial').locator('td:nth-child(3)')).toHaveText('1');
+    await expect(row('warm_light').locator('td:nth-child(3)')).toHaveText('0');
+});
+
+test('virtualized cards release listeners on unmount', async ({ page, request }) => {
+    const extra = 140;
+    await expect(await request.post('/__test__/tagging/reset', { data: { extra_images: extra } })).toBeOK();
+    const count = () => page.evaluate(async url => (await import(url)).imageTagsListenerCount(), MODULE);
+    await page.goto(images);
+    await expect(card(page, FIRST)).toBeVisible();
+    const mounted = await count();
+    // Leaving and returning to Images several times keeps one subscription per mounted page.
+    for (let round = 0; round < 3; round += 1) {
+        await nav(page, 'Tags & categories').click();
+        await expect(page.locator('#workspace-main h1')).toHaveText('Tags & categories');
+        await nav(page, 'Images').click();
+        await expect(card(page, FIRST)).toBeVisible();
+    }
+    expect(await count()).toBe(mounted);
+    // Cards scrolled out are unmounted; the delegated Tag still works on a card rendered again.
+    const continuation = page.locator('#gallery-continuation');
+    await expect(async () => {
+        await continuation.scrollIntoViewIfNeeded();
+        await expect(continuation).toContainText('You’re all caught up', { timeout: 1000 });
+    }).toPass();
+    await continuation.scrollIntoViewIfNeeded();
+    await expect(card(page, FIRST)).toHaveCount(0);
+    expect(await count()).toBe(mounted);
+    await page.evaluate(() => window.scrollTo(0, 0));
+    await expect(card(page, FIRST)).toBeVisible();
+    await openTag(page, FIRST, { goto: false });
+    await page.keyboard.press('Escape');
+    await expect(tagButton(page, FIRST)).toBeFocused();
+    expect(await count()).toBe(mounted);
+});
+
+// Task C3 (D88): the side panel and the viewer details draw the file's own current image tags first, then D21's linked
+// tags not already shown (case-insensitive). Panel image tags are Tags filter buttons; the viewer's chips are plain.
+const panel = page => page.getByRole('complementary', { name: 'Selected image details', exact: true });
+const tagRow = page => panel(page).locator('.detail-inner > .tags').last();
+const inspected = (page, path) => page.waitForResponse(item => new URL(item.url()).pathname === `/prompt_manager/images/inspect/${path}`);
+const infoButton = (page, path) => card(page, path).getByRole('button', { name: `Inspect ${path.split('/').pop()}`, exact: true });
+
+test('inspector shows saved image tags after Save without reselecting', async ({ page }) => {
+    await page.goto(images);
+    await expect(card(page, FIRST)).toHaveClass(/\bselected\b/);
+    // D21/D39: the linked recipe's own tag, plain.
+    await expect(tagRow(page).locator('.chip')).toHaveText(manifest.pair_tags);
+    await expect(tagRow(page).locator('button.chip')).toHaveCount(0);
+    await openTag(page, FIRST, { goto: false });
+    await manual(page).fill('dunes_tag, Editorial');
+    const reread = inspected(page, FIRST);
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    expect((await (await reread).json()).image_tags).toEqual({ state: 'current', tags: ['dunes_tag', 'Editorial'] });
+    // The image tags lead as filter buttons; the recipe's "editorial" is already shown as "Editorial".
+    await expect(tagRow(page).locator('.chip')).toHaveText(['dunes_tag', 'Editorial']);
+    await expect(tagRow(page).locator('button.chip')).toHaveText(['dunes_tag', 'Editorial']);
+    await expect(card(page, FIRST)).toHaveClass(/\bselected\b/);
+    await expect(panel(page).locator('.panel-heading h2')).toHaveText(manifest.title);
+});
+
+test('clicking an image tag chip filters Images to the tagged unlinked file', async ({ page, request }) => {
+    expect(await saveImageTags(request, UNLINKED, ['loose_tag'])).toEqual(['loose_tag']);
+    await page.goto(images);
+    const read = inspected(page, UNLINKED);
+    await infoButton(page, UNLINKED).click();
+    await read;
+    await expect(panel(page).locator('.panel-heading h2')).toHaveText('unlinked.png');
+    await expect(tagRow(page).locator('.chip')).toHaveText(['loose_tag']);
+    const listing = page.waitForRequest(item => item.url().includes('/images/output?') && new URL(item.url()).searchParams.get('tags') === 'loose_tag');
+    await tagRow(page).getByRole('button', { name: 'loose_tag', exact: true }).click();
+    await listing;
+    await expect(page.locator('.gallery-body article[data-image-key]')).toHaveCount(1);
+    await expect(card(page, UNLINKED)).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Filters · 1', exact: true })).toBeVisible();
+});
+
+test('viewer details show the same chips', async ({ page, request }) => {
+    await saveImageTags(request, FIRST, ['dunes_tag', 'Editorial', 'sunlit']);
+    await page.goto(images);
+    await expect(tagRow(page).locator('button.chip')).toHaveText(['dunes_tag', 'Editorial', 'sunlit']);
+    await card(page, FIRST).locator('.image-open').click();
+    const details = page.locator('#viewer-dialog[open] #viewer-details');
+    await expect(details.locator('.panel-heading h2')).toHaveText(manifest.title);
+    const row = details.locator('.tags').last();
+    await expect(row.locator('.chip')).toHaveText(['dunes_tag', 'Editorial', 'sunlit']);
+    await expect(row.locator('span.chip')).toHaveCount(3);
+    await expect(row.locator('button')).toHaveCount(0);
+    // A file without image tags: the viewer shows only D21's linked tags.
+    await page.getByRole('button', { name: 'Next media', exact: true }).click();
+    await expect(page.locator('#viewer-dialog[open] #viewer-title')).toHaveText(`${manifest.title} · dunes_00002.png`);
+    await expect(details.locator('.tags').last().locator('.chip')).toHaveText(manifest.pair_tags);
+});
+
+test('search finds an image by its image tag', async ({ page, request }) => {
+    await saveImageTags(request, UNLINKED, ['Loose_Tag']);
+    await page.goto(images);
+    await expect(page.locator('.gallery-body article[data-image-key]')).toHaveCount(manifest.files.length);
+    const listing = page.waitForRequest(item => item.url().includes('/images/output?') && new URL(item.url()).searchParams.get('q') === 'loose_t');
+    await page.getByRole('searchbox', { name: 'Search workspace', exact: true }).fill('loose_t');
+    await listing;
+    await expect(page.locator('.gallery-body article[data-image-key]')).toHaveCount(1);
+    await expect(card(page, UNLINKED)).toBeVisible();
+});
+
+// Task C4 rulings: a save re-reads the selected file's details without a loading flash, and under a Tags filter or a
+// search the loaded listing is re-read in place (scroll and selection kept while the file still matches).
+const cards = page => page.locator('.gallery-body article[data-image-key]');
+const listingOf = (page, check) => page.waitForResponse(item => item.url().includes('/images/output?') && check(new URL(item.url()).searchParams));
+
+test('the post-save re-read keeps the panel content until the new read lands', async ({ page }) => {
+    await page.goto(images);
+    await expect(card(page, FIRST)).toHaveClass(/\bselected\b/);
+    await expect(tagRow(page).locator('.chip')).toHaveText(manifest.pair_tags);
+    await page.evaluate(() => {
+        const node = document.querySelector('aside[aria-label="Selected image details"]');
+        window.__loadingSeen = false;
+        window.__loadingWatch = new MutationObserver(() => { if (node.textContent.includes('Loading file details')) window.__loadingSeen = true; });
+        window.__loadingWatch.observe(node, { childList: true, subtree: true, characterData: true });
+    });
+    let release;
+    const held = new Promise(resolve => { release = resolve; });
+    const matcher = url => url.pathname === `/prompt_manager/images/inspect/${FIRST}`;
+    await page.route(matcher, async route => { await held; await route.continue(); });
+    await openTag(page, FIRST, { goto: false });
+    await manual(page).fill('held_tag');
+    const reread = page.waitForRequest(item => new URL(item.url()).pathname === `/prompt_manager/images/inspect/${FIRST}`);
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await reread;
+    await expect(toast(page)).toHaveText('1 tags saved for dunes_00001.png.');
+    // While the re-read is held, the panel still shows the file's details.
+    await expect(panel(page).locator('.panel-heading h2')).toHaveText(manifest.title);
+    await expect(tagRow(page).locator('.chip')).toHaveText(manifest.pair_tags);
+    expect(await page.evaluate(() => window.__loadingSeen)).toBe(false);
+    const landed = inspected(page, FIRST);
+    release();
+    await landed;
+    await expect(tagRow(page).locator('.chip')).toHaveText(['held_tag', ...manifest.pair_tags]);
+    expect(await page.evaluate(() => { window.__loadingWatch.disconnect(); return window.__loadingSeen; })).toBe(false);
+    await page.unroute(matcher);
+});
+
+test('a save under a Tags filter re-reads the listing: the selection stays while it matches and follows when it leaves', async ({ page, request }) => {
+    await saveImageTags(request, UNLINKED, ['shared']);
+    await saveImageTags(request, SECOND, ['shared']);
+    await page.goto(images);
+    const read = inspected(page, SECOND);
+    await infoButton(page, SECOND).click();
+    await read;
+    const filtered = listingOf(page, query => query.get('tags') === 'shared');
+    await tagRow(page).getByRole('button', { name: 'shared', exact: true }).click();
+    await filtered;
+    await expect(cards(page)).toHaveCount(2);
+    // The newest match (SECOND) is selected once the filter applies.
+    await expect(card(page, SECOND)).toHaveClass(/\bselected\b/);
+    // Both matches checked: the selection bar keeps only what the refreshed result still lists (I7).
+    for (const path of [SECOND, UNLINKED]) await card(page, path).getByRole('checkbox', { name: `Select ${path.split('/').pop()}`, exact: true }).check();
+    const bulkbar = page.locator('#bulkbar .bulkbar');
+    await expect(bulkbar.locator('strong')).toHaveText('2 selected');
+    // Tagging the other match keeps both cards and SECOND selected; the listing is re-read.
+    await openTag(page, UNLINKED, { goto: false });
+    await manual(page).fill('shared, extra');
+    let reread = listingOf(page, query => query.get('tags') === 'shared' && !query.has('cursor'));
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await reread;
+    await expect(cards(page)).toHaveCount(2);
+    await expect(card(page, SECOND)).toHaveClass(/\bselected\b/);
+    await expect(tagButton(page, UNLINKED)).toBeFocused();
+    // SECOND loses the filter tag: it leaves the result and the panel follows the remaining match.
+    await openTag(page, SECOND, { goto: false });
+    await manual(page).fill('');
+    reread = listingOf(page, query => query.get('tags') === 'shared' && !query.has('cursor'));
+    const next = inspected(page, UNLINKED);
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await reread;
+    await next;
+    await expect(cards(page)).toHaveCount(1);
+    await expect(card(page, SECOND)).toHaveCount(0);
+    await expect(card(page, UNLINKED)).toHaveClass(/\bselected\b/);
+    await expect(panel(page).locator('.panel-heading h2')).toHaveText('unlinked.png');
+    await expect(page.getByText('1 of 1 image', { exact: false }).first()).toBeVisible();
+    await expect(bulkbar.locator('strong')).toHaveText('1 selected');
+    await expect(card(page, UNLINKED).getByRole('checkbox')).toBeChecked();
+    // Export metadata acts on exactly the one file the bar counts.
+    const exported = [];
+    page.on('request', item => { if (item.url().includes('/prompt_manager/images/inspect/')) exported.push(new URL(item.url()).pathname); });
+    const download = page.waitForEvent('download');
+    await bulkbar.getByRole('button', { name: 'Export metadata', exact: true }).click();
+    await download;
+    expect(exported).toEqual([`/prompt_manager/images/inspect/${UNLINKED}`]);
+});
+
+test('a save under a search keeps the scroll position and the loaded range', async ({ page, request }) => {
+    await expect(await request.post('/__test__/tagging/reset', { data: { extra_images: 140 } })).toBeOK();
+    await page.goto(images);
+    const searched = listingOf(page, query => query.get('q') === 'bulk');
+    await page.getByRole('searchbox', { name: 'Search workspace', exact: true }).fill('bulk');
+    await searched;
+    const continuation = page.locator('#gallery-continuation');
+    // Load at least two pages (the search lists 40 a page), then rest a third of the way down.
+    const loadedCount = async () => {
+        const text = await continuation.textContent();
+        return /caught up/.test(text) ? 140 : Number(/^(\d+) of 140/.exec(text)?.[1] ?? 0);
+    };
+    await expect.poll(async () => { await continuation.scrollIntoViewIfNeeded(); return loadedCount(); }).toBeGreaterThanOrEqual(80);
+    await page.evaluate(() => window.scrollTo(0, Math.round(document.documentElement.scrollHeight / 3)));
+    await expect(continuation).not.toBeInViewport();
+    const loaded = await continuation.textContent();
+    await expect.poll(() => continuation.textContent()).toBe(loaded);
+    const y = await page.evaluate(() => window.scrollY);
+    expect(y).toBeGreaterThan(0);
+    const visible = await cards(page).evaluateAll(nodes => nodes.find(node => { const box = node.getBoundingClientRect(); return box.top > 80 && box.bottom < innerHeight; })?.dataset.imageKey);
+    expect(visible).toBeTruthy();
+    const path = visible.slice(2);
+    await openTag(page, path, { goto: false });
+    await manual(page).fill('kept_in_place');
+    const reread = listingOf(page, query => query.get('q') === 'bulk' && !query.has('cursor'));
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await reread;
+    await expect(tagButton(page, path)).toBeFocused();
+    await expect(continuation).toHaveText(loaded);
+    expect(Math.abs(await page.evaluate(() => window.scrollY) - y)).toBeLessThanOrEqual(1);
+});
+
+// Final review round (I1, I2, I9, M5, M6).
+test('the option fields show the server defaults that Generate sends (I1)', async ({ page, request }) => {
+    await expect(await request.post('/__test__/tagging/defaults', { data: { general: 0.5, character: 0.9, limit: 7 } })).toBeOK();
+    await openTag(page);
+    const field = name => dialog(page).getByRole('spinbutton', { name, exact: true });
+    await expect(field('General confidence')).toHaveValue('0.5');
+    await expect(field('Character confidence')).toHaveValue('0.9');
+    await expect(field('Suggestions')).toHaveValue('7');
+    const answer = await generated(page);
+    expect(answer.request().postDataJSON().options).toEqual({ general_threshold: 0.5, character_threshold: 0.9, suggestion_limit: 7 });
+    await expect(chips(page)).toHaveCount(7);
+    // A model change re-renders the new model's fields from the server defaults, and keeps the count (D91).
+    await field('Suggestions').fill('4');
+    await model(page).selectOption('wd14-vit');
+    await expect(field('General confidence')).toHaveValue('0.5');
+    await expect(field('Suggestions')).toHaveValue('4');
+});
+
+test('a tag conflict shows the other writer\'s tags before Save, and a second Save keeps them (I2)', async ({ page, request }) => {
+    await openTag(page);
+    await manual(page).fill('mine');
+    // Another writer (a second tab, the legacy page) saves while the dialog is open.
+    expect(await saveImageTags(request, FIRST, ['changed_elsewhere'])).toEqual(['changed_elsewhere']);
+    const conflict = page.waitForResponse(item => item.url().endsWith('/image-annotations/tags') && item.request().method() === 'PUT');
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    expect((await conflict).status()).toBe(409);
+    await expect(status(page)).toContainText('Saved now: changed_elsewhere.');
+    await expect(manual(page)).toHaveValue('changed_elsewhere, mine');
+    await expect(dialog(page)).toBeVisible();
+    const second = page.waitForResponse(item => item.url().endsWith('/image-annotations/tags') && item.request().method() === 'PUT');
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    expect((await second).request().postDataJSON().tags).toEqual(['changed_elsewhere', 'mine']);
+    await expect(toast(page)).toHaveText('2 tags saved for dunes_00001.png.');
+    expect(await savedTags(request, FIRST)).toEqual(['changed_elsewhere', 'mine']);
+});
+
+test('D116: Retry leads the actions after an unconfirmed save and resends the same tags', async ({ page, request }) => {
+    await openTag(page);
+    await manual(page).fill('retried');
+    let lost = true;
+    await page.route('**/prompt_manager/image-annotations/tags', route => (lost ? (lost = false, route.fulfill({ status: 504, body: 'Gateway Timeout' })) : route.continue()));
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await expect(status(page)).toHaveText('The save could not be confirmed. Retry sends the same tags again.');
+    const inventory = await page.locator('dialog#modal').evaluate(taggingInventory);
+    expect(inventory.actions.buttons.map(button => [button.text, button.primary, button.disabled])).toEqual(
+        [['Retry', false, false], ['Cancel', false, false], ['Save manual tags', true, true]]);
+    expect(inventory.actions.buttons[0].minHeight).toBe(inventory.actions.buttons[1].minHeight);
+    const resent = page.waitForResponse(item => item.url().endsWith('/image-annotations/tags') && item.request().method() === 'PUT');
+    await dialog(page).getByRole('button', { name: 'Retry', exact: true }).click();
+    expect((await resent).request().postDataJSON().tags).toEqual(['retried']);
+    await expect(toast(page)).toHaveText('1 tags saved for dunes_00001.png.');
+    expect(await savedTags(request, FIRST)).toEqual(['retried']);
+    await page.unroute('**/prompt_manager/image-annotations/tags');
+});
+
+test('D116: Retry after an expired capture observes again and keeps the typed draft (M5)', async ({ page, request }) => {
+    await openTag(page);
+    await manual(page).fill('kept_draft');
+    // The store forgets every capture (as its idle sweep would), so Save answers capture-expired.
+    await expect(await request.post('/__test__/tagging/suggestions', { data: { scored: null } })).toBeOK();
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await expect(dialog(page).locator('.dialog-actions .ca-primary')).toHaveAttribute('aria-disabled', 'true');
+    const observed = page.waitForResponse(item => item.url().endsWith('/image-annotations/observe'));
+    await dialog(page).getByRole('button', { name: 'Retry', exact: true }).click();
+    expect((await observed).status()).toBe(200);
+    await expect(dialog(page).locator('.dialog-actions button')).toHaveText(['Cancel', 'Save manual tags']);
+    await expect(manual(page)).toHaveValue('kept_draft');
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await expect(toast(page)).toHaveText('1 tags saved for dunes_00001.png.');
+    expect(await savedTags(request, FIRST)).toEqual(['kept_draft']);
+});
+
+test('a tag save from Tags reloads a filtered Images visit instead of restoring it (M6)', async ({ page, request }) => {
+    await saveImageTags(request, SECOND, ['shared']);
+    await saveImageTags(request, UNLINKED, ['shared']);
+    await page.goto(images);
+    await infoButton(page, SECOND).click();
+    const filtered = listingOf(page, query => query.get('tags') === 'shared');
+    await tagRow(page).getByRole('button', { name: 'shared', exact: true }).click();
+    await filtered;
+    await expect(cards(page)).toHaveCount(2);
+    await expect(card(page, SECOND)).toHaveClass(/\bselected\b/);
+    // Tags › Auto-tag images tags the selected SECOND without the filter tag.
+    await nav(page, 'Tags & categories').click();
+    await page.locator('#workspace-main .heading-actions').getByRole('button', { name: 'Auto-tag images', exact: true }).click();
+    await expect(manual(page)).toHaveValue('shared');
+    await manual(page).fill('other');
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    await expect(toast(page)).toHaveText('1 tags saved for dunes_00002.png.');
+    const reloaded = listingOf(page, query => query.get('tags') === 'shared' && !query.has('cursor'));
+    await nav(page, 'Images').click();
+    await reloaded;
+    await expect(cards(page)).toHaveCount(1);
+    await expect(card(page, UNLINKED)).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Filters · 1', exact: true })).toBeVisible();
+});
+
+test('a failed listing re-read after a save says so and keeps the cards (M2)', async ({ page, request }) => {
+    await saveImageTags(request, SECOND, ['shared']);
+    await saveImageTags(request, UNLINKED, ['shared']);
+    await page.goto(images);
+    await infoButton(page, SECOND).click();
+    const filtered = listingOf(page, query => query.get('tags') === 'shared');
+    await tagRow(page).getByRole('button', { name: 'shared', exact: true }).click();
+    await filtered;
+    await expect(cards(page)).toHaveCount(2);
+    await openTag(page, SECOND, { goto: false });
+    await manual(page).fill('');
+    const failing = url => url.pathname === '/prompt_manager/images/output' && url.searchParams.get('tags') === 'shared';
+    await page.route(failing, route => route.fulfill({ status: 500, contentType: 'application/json', body: '{"success":false,"error":"down"}' }));
+    const reread = page.waitForResponse(item => failing(new URL(item.url())));
+    await dialog(page).getByRole('button', { name: 'Save manual tags', exact: true }).click();
+    expect((await reread).status()).toBe(500);
+    await expect(toast(page)).toHaveText('Images could not be refreshed after the tag save. Refresh image collection to retry.');
+    await expect(cards(page)).toHaveCount(2);
+    await expect(page.locator('#gallery-continuation [aria-disabled="true"]')).toHaveCount(0);
+    await page.unroute(failing);
+});

tests/browser/workspace-visual.spec.mjs

@@ -3,12 +3,12 @@ import { readFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { captureCanonicalState, historyGeometry, compareCanonicalHistory, nativeDialogState, exerciseCurrentPairSend, assertRecordedHistory } from './history-canonical-comparison.mjs';
 import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
-import { test, expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import { test, expect } from './fixtures.mjs';
 
 test.use({ locale: 'en-US', timezoneId: 'UTC', reducedMotion: 'reduce' });
 const workspace = '/prompt_manager/workspace';
 const primary = ['images', 'library', 'tags', 'inspect'];
-const tools = ['system', 'overview'];
+const tools = ['activity', 'system', 'overview'];
 
 async function noOverflow(page) {
     expect(await page.evaluate(() => document.documentElement.scrollWidth - document.documentElement.clientWidth)).toBeLessThanOrEqual(1);
@@ -107,7 +107,7 @@ for (const [width, height] of [[1600, 1100], [390, 844]]) for (const theme of ['
         await expect(roles.getByRole('button', { name: 'Send prompt pair', exact: true })).toHaveCount(0);
         await expect(page.locator('#workspace-main > .heading button.send')).toBeEnabled();
         await expect(page.locator('.library-history .history-gallery article[data-image-key]')).toHaveCount(2);
-        await page.locator('.library-history .history-gallery .image-card-actions button').first().click();
+        await page.locator('.library-history .history-gallery .image-card-actions button:first-child').first().click();
         await expect(page.getByRole('complementary', { name: 'Selected image details', exact: true })).toContainText('canonical-alt.png');
         await page.locator('.library-history .history-gallery .media-card.selected .image-open').click();
         await expect(page.locator('dialog#viewer-dialog')).toBeVisible();await page.keyboard.press('Escape');
@@ -296,7 +296,7 @@ async function containedImageContent(page) {
         const failures = [];
         for (const card of nodes) {
             const outer = card.getBoundingClientRect();
-            for (const selector of ['.media-info', '.media-info h3', '.media-info p', '.image-card-actions button']) {
+            for (const selector of ['.media-info', '.media-info h3', '.media-info p', '.image-card-actions']) {
                 const node = card.querySelector(selector), box = node.getBoundingClientRect();
                 if (box.width <= 0 || box.height <= 0 || box.left < outer.left - 1 || box.right > outer.right + 1 ||
                     box.top < outer.top - 1 || box.bottom > outer.bottom + 1 ||
@@ -306,7 +306,7 @@ async function containedImageContent(page) {
                         content: { left: box.left, right: box.right, top: box.top, bottom: box.bottom } });
                 }
             }
-            const action = card.querySelector('.image-card-actions button').getBoundingClientRect();
+            const action = card.querySelector('.image-card-actions').getBoundingClientRect();
             const range = document.createRange(); range.selectNodeContents(card.querySelector('.media-info p'));
             for (const text of range.getClientRects()) {
                 if (Math.min(text.right, action.right) - Math.max(text.left, action.left) > .5 &&
@@ -351,7 +351,7 @@ for (const [width, height] of [[390, 844], [1600, 1100]]) for (const layout of [
             const filename = (await longCard.locator('.image-open').getAttribute('aria-label')).replace(/^Open /, '');
             expect(filename).toMatch(/layered-context-.*\.png/);
             // D19: Info selects into the panel; the image itself opens the viewer.
-            await longCard.locator('.image-card-actions button').focus(); await page.keyboard.press('Enter');
+            await longCard.locator('.image-card-actions button:first-child').focus(); await page.keyboard.press('Enter');
             await expect(page.locator('.detail-panel .panel-heading h2')).toHaveText(filename);
             // D19: the card image, not the panel, opens the viewer.
             const fullPreview = longCard.locator('.image-open');
@@ -420,7 +420,7 @@ test('supplemental extreme zoom grows real footers preserves the visible anchor
     await page.evaluate(() => { document.documentElement.style.zoom = '2'; });
     await expect.poll(() => cards.nth(1).evaluate(node => node.offsetLeft)).toBe(0);
     const selected = cards.nth(16), key = await selected.getAttribute('data-image-key');
-    await selected.locator('.image-card-actions button').click(); await selected.locator('.image-open').focus();
+    await selected.locator('.image-card-actions button:first-child').click(); await selected.locator('.image-open').focus();
     const filename = (await selected.locator('.image-open').getAttribute('aria-label')).replace(/^Open /, '');
     await selected.evaluate(node => scrollBy(0, node.getBoundingClientRect().top - 120));
     await page.evaluate(() => {
@@ -497,7 +497,7 @@ test('supplemental wrapped real footer reservation survives append without movin
     await page.setViewportSize({ width: 390, height: 844 }); await page.goto(`${workspace}#/images`);
     const cards = page.locator('article[data-image-key]'), grid = page.locator('.image-grid');
     await expect(cards).toHaveCount(40);
-    await cards.first().locator('.image-card-actions button').click();
+    await cards.first().locator('.image-card-actions button:first-child').click();
     const selectedKey = await cards.first().getAttribute('data-image-key');
     await page.evaluate(() => { document.documentElement.style.zoom = '4'; });
     await expect.poll(() => grid.evaluate(node => Number.parseFloat(node.style.getPropertyValue('--image-footer-height')))).toBeGreaterThan(54);
@@ -556,7 +556,7 @@ test('approved icons are decorative safe SVGs and reject unknown vocabulary', as
     await page.goto(`${workspace}#/images`);
     const icons = await page.evaluate(async () => {
         const { createWorkspaceIcon } = await import('/prompt_manager/js/workspace/icons.mjs');
-        const names = ['images', 'library', 'tags', 'upload', 'overview', 'settings', 'grid', 'list', 'masonry', 'search', 'info', 'copy', 'branch', 'star', 'tagImage', 'folder', 'history', 'review'];
+        const names = ['images', 'library', 'tags', 'upload', 'overview', 'activity', 'settings', 'grid', 'list', 'masonry', 'search', 'info', 'copy', 'branch', 'star', 'tagImage', 'folder', 'history', 'review'];
         const otherDocument = document.implementation.createHTMLDocument();
         const rendered = names.map(name => {
             const icon = createWorkspaceIcon(name, otherDocument);
@@ -575,7 +575,8 @@ test('approved icons are decorative safe SVGs and reject unknown vocabulary', as
         expect(icon).toMatchObject({ svg: true, className: 'icon', owner: true, viewBox: '0 0 24 24', hidden: 'true', focusable: 'false', fill: 'none', stroke: 'currentColor', width: '1.65', children: 1 });
         expect(icon.path.length).toBeGreaterThan(10);
     }
-    // D28 ruling: Overview's own outline home glyph, not the concept's `activity` pulse ('M3 12h4l3-8 4 16 3-8h4').
+    // D28 ruling: Overview's own outline home glyph; the concept's `activity` pulse is the Activity row's.
+    expect(icons.rendered.find(icon => icon.name === 'activity').path).toBe('M3 12h4l3-8 4 16 3-8h4');
     expect(icons.rendered.find(icon => icon.name === 'overview').path).toBe('M3 11 12 4l9 7M5 10v10h14V10M10 20v-6h4v6');
     expect(new Set(icons.rendered.map(icon => icon.path)).size).toBe(icons.rendered.length);
 });
@@ -608,7 +609,7 @@ test('Images visual layouts retain real delayed media long filenames and loaded
         await page.setViewportSize({width,height});
         for (const theme of ['dark','light']) {
             await page.getByRole('combobox',{name:'Theme',exact:true}).selectOption(theme);
-            await page.locator('.media-card .image-card-actions button').first().click();
+            await page.locator('.media-card .image-card-actions button:first-child').first().click();
             await expect(page.locator('.detail-panel .panel-heading h2')).toHaveText('study-01.png');
             for (const layout of ['Grid','List','Masonry']) {
                 await page.getByRole('button',{name:layout,exact:true}).click();await page.evaluate(()=>scrollTo(0,0));
@@ -620,7 +621,7 @@ test('Images visual layouts retain real delayed media long filenames and loaded
             const longCard=page.locator('article[data-image-key]').filter({has:page.locator('[aria-label^="Open a-very-long-geometric-composition-"]')});
             const longName=(await longCard.locator('.image-open').getAttribute('aria-label')).replace(/^Open /,'');
             expect(longName).toMatch(/layered-context-.*\.png/);
-            await longCard.locator('.image-card-actions button').click();
+            await longCard.locator('.image-card-actions button:first-child').click();
             await expect(page.locator('.detail-panel .panel-heading h2')).toHaveText(longName);
             await orderedMedia(page);
             await attachEvidence(page,testInfo,`after-images-loaded-scroll-${width}-${theme}`,false);

tests/browser/workspace-vocabulary.spec.mjs

@@ -1,6 +1,6 @@
 import {startCoverage,saveCoverage} from '../../tools/vendor/browser-coverage.mjs';
 import {writeFile} from 'node:fs/promises';
-import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {test,expect} from './fixtures.mjs';
 import {captureCanonicalState} from './history-canonical-comparison.mjs';
 import {pageInventoryOf,inventoryOf,diffInventory,mapVocabularyConcept,mapVocabularyDialog} from './vocabulary-canonical-comparison.mjs';
 
@@ -50,9 +50,12 @@ test('tags route renders the concept composition without a legacy handoff',async
     await expect(main(page).getByRole('heading',{level:1})).toHaveText('Tags & categories');
     await expect(main(page).locator(':scope > .heading p.muted')).toHaveText('Organize once. Reuse everywhere.');
     const actions=main(page).locator(':scope > .heading > .heading-actions button');
-    await expect(actions).toHaveText(['+ Create tag']);
+    // The concept's heading actions (#249 C2 retired #245 D2): Auto-tag images is primary; with no image selected in
+    // Images it is aria-disabled (D115).
+    await expect(actions).toHaveText(['+ Create tag','Auto-tag images']);
     await expect(actions.first()).not.toHaveClass(/ca-primary/);
-    await expect(main(page).getByRole('button',{name:'Auto-tag images'})).toHaveCount(0);
+    await expect(actions.last()).toHaveClass(/ca-primary/);
+    await expect(actions.last()).toHaveAttribute('aria-disabled','true');
     await expect(surfaces(page)).toHaveCount(2);
     await expect(surfaces(page).locator('h2')).toHaveText(['Tag vocabulary','Categories']);
     await expect(surfaces(page).locator(':scope > p:visible')).toHaveText(['Category/tag autocomplete uses this same vocabulary across nodes and dialogs.',
@@ -65,9 +68,9 @@ test('tags route renders the concept composition without a legacy handoff',async
     expect(manifest.tags).toEqual(expected.map(([name])=>name));
     await expect(rows(page).locator('td:nth-child(1)')).toHaveText(expected.map(([name])=>name));
     await expect(rows(page).locator('td:nth-child(2)')).toHaveText(expected.map(([,count])=>String(count)));
-    const images=await rows(page).locator('td:nth-child(3)').evaluateAll(cells=>cells.map(cell=>[cell.querySelector('[aria-hidden="true"]')?.textContent,cell.querySelector('.ca-visually-hidden')?.textContent]));
-    expect(images).toEqual(expected.map(()=>['—','Not available yet']));
-    await expect(rows(page).first().locator('td:nth-child(3)')).toHaveAccessibleName('Not available yet');
+    // Images counts the files carrying each tag (#249 C2 retired #245 D3); this fixture tags no image.
+    await expect(rows(page).locator('td:nth-child(3)')).toHaveText(expected.map(()=>'0'));
+    await expect(rows(page).locator('td:nth-child(3) .ca-visually-hidden')).toHaveCount(0);
     const labels=await rows(page).evaluateAll(nodes=>nodes.map(row=>[...row.querySelectorAll('td:nth-child(4) .row-actions button')].map(button=>button.textContent)));
     expect(labels).toEqual(expected.map(()=>['Browse','Rename / merge']));
     const operations=surfaces(page).nth(1).locator('.operation');

tests/browser/workspace.spec.mjs

@@ -1,5 +1,5 @@
 import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
-import { test, expect } from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import { test, expect } from './fixtures.mjs';
 
 const workspace = '/prompt_manager/workspace';
 const statistic = (page, label) => page.locator('#workspace-main dt')
@@ -16,10 +16,13 @@ const routes = [
     // #249 E3: the shelf no longer links the legacy Library; Overview's tool card still does.
     ['library', 'Prompt library', null],
     ['tags', 'Tags & categories', null],
-    ['inspect', 'Inspect a file', '/prompt_manager/gallery.html'],
+    // #249 local Inspect: the native Inspect a file page; Overview's tool card still links the legacy metadata page.
+    ['inspect', 'Inspect a file', null],
     ['system', 'System', '/prompt_manager/admin'],
     // #249 D51: SAVED VIEWS' Favorites, Images filtered to favorites.
     ['favorites', 'Favorites', null],
+    // #249 Activity-1: the concept's Activity page in the tools-and-system group.
+    ['activity', 'Activity', null],
 ];
 
 async function countThemeWrites(page) {
@@ -46,6 +49,8 @@ test.beforeEach(async ({ page, request, browserName }) => {
 });
 
 test.afterEach(async ({ page, browserName }) => {
+    // A route handler still running at teardown must not fail the test it outlived.
+    await page.unrouteAll({ behavior: 'ignoreErrors' });
     await saveCoverage(page, browserName);
     expect(page.workspaceErrors).toEqual([]);
 });
@@ -76,7 +81,8 @@ test('all shell destinations deep-link, reload and expose working existing appli
         const main = page.locator('#workspace-main');
         await expect(main.getByRole('heading', { level: 1, name: label, exact: true })).toBeVisible();
         await expect(sidebarLink(page, label)).toHaveAttribute('aria-current', 'page');
-        if (route === 'tags') await expect(main.locator('.handoff')).toHaveCount(0);
+        if (route === 'tags' || route === 'inspect') await expect(main.locator('.handoff')).toHaveCount(0);
+        if (route === 'inspect') await expect(main.locator('#local-file')).toBeAttached();
         if (legacy) {
             await expect(main.locator(`a[href="${legacy}"]`)).toBeVisible();
             await expect(await request.get(legacy.split('#')[0])).toBeOK();
@@ -89,6 +95,10 @@ test('all shell destinations deep-link, reload and expose working existing appli
     const library = page.locator('#workspace-main').getByRole('link', { name: 'Open existing prompt library', exact: true });
     await expect(library).toHaveAttribute('href', '/prompt_manager/admin');
     await expect(await request.get('/prompt_manager/admin')).toBeOK();
+    // The legacy metadata page stays reachable from Overview beside the native Inspect page.
+    const metadata = page.locator('#workspace-main').getByRole('link', { name: 'Open existing metadata inspector', exact: true });
+    await expect(metadata).toHaveAttribute('href', '/prompt_manager/gallery.html');
+    await expect(await request.get('/prompt_manager/gallery.html')).toBeOK();
     const gallery = page.locator('#workspace-main').getByRole('link', { name: 'Open existing image gallery', exact: true });
     await expect(gallery).toHaveAttribute('href', '/prompt_manager/gallery');
     await expect(await request.get('/prompt_manager/gallery')).toBeOK();
@@ -176,7 +186,8 @@ test('theme System follows ComfyUI and persists an explicit light or dark prefer
     await expect(theme).toHaveAttribute('data-ca-theme', 'light');
 });
 
-// Task A4 (D4, D5): the concept topbar (index.html 45-63, style.css 225-277) without the prototype badge or Activity.
+// Task A4 (D4, D29): the concept topbar (index.html 45-63, style.css 225-277) without the prototype badge; Activity
+// (D52, D53) shows its button, and its pill only while a job runs.
 test('topbar matches the concept actions', async ({ page }) => {
     await page.setViewportSize({ width: 1600, height: 1100 });
     await page.goto(`${workspace}#/images`);
@@ -204,7 +215,7 @@ test('topbar matches the concept actions', async ({ page }) => {
     expect(shape).toEqual({
         children: ['div.breadcrumbs', 'div.top-actions'],
         crumbs: ['ComfyAssets', 'span:/', 'span#workspace-breadcrumb:Images'],
-        actions: ['label.theme-label', 'a.canvas-link'],
+        actions: ['a.activity-pill', 'button.', 'label.theme-label', 'a.canvas-link'],
         label: 'Theme', labelFor: 'theme',
         options: [['dark', 'Dark'], ['light', 'Light'], ['system', 'System']],
         arrow: [['↗', 'true']],
@@ -218,11 +229,12 @@ test('topbar matches the concept actions', async ({ page }) => {
     await expect(link).toHaveAttribute('href', '/');
     expect(await link.evaluate(node => node.href === `${location.origin}/`)).toBe(true);
     await expect(page.getByRole('combobox', { name: 'Appearance' })).toHaveCount(0);
-    await expect(page.getByRole('button', { name: /^Activity/ })).toHaveCount(0);
-    await expect(page.locator('.concept-badge, #activity-open')).toHaveCount(0);
+    await expect(page.getByRole('button', { name: 'Activity', exact: true })).toHaveCount(1);
+    await expect(page.locator('#activity-pill')).toBeHidden();
+    await expect(page.locator('.concept-badge')).toHaveCount(0);
     await page.locator('nav [data-route="library"]').click();
     await expect(page.locator('#workspace-breadcrumb')).toHaveText('Prompt library');
-    await expect(topbar.locator('.top-actions > *')).toHaveCount(2);
+    await expect(topbar.locator('.top-actions > *')).toHaveCount(4);
 });
 
 // Concept style.css 1375-1391: at <=700px the breadcrumbs hide, the actions spread across the bar and the Theme
@@ -242,13 +254,18 @@ test('mobile topbar hides breadcrumbs and spreads actions', async ({ page }) =>
             expected: bar.width - 28,
             label: getComputedStyle(node.querySelector('.theme-label')).fontSize,
             select: getComputedStyle(node.querySelector('#theme')).fontSize,
-            labelLeft: box(node.querySelector('.theme-label')).left - bar.left,
+            activityLeft: box(node.querySelector('#activity-open')).left - bar.left,
+            actionsGap: [box(node.querySelector('#activity-open')).right, box(node.querySelector('.theme-label')).left,
+                box(node.querySelector('.theme-label')).right, box(node.querySelector('.canvas-link')).left],
             linkRight: bar.right - box(node.querySelector('.canvas-link')).right,
         };
     });
     expect(layout).toMatchObject({ padding: '14px', actions: { justify: 'space-between', gap: '8px' }, label: '0px', select: '11px' });
     expect(Math.abs(layout.actions.width - layout.expected)).toBeLessThanOrEqual(1);
-    expect(Math.abs(layout.labelLeft - 14)).toBeLessThanOrEqual(1);
+    // The concept's three items spread with space-between: Activity first, Theme between equal gaps, ComfyUI last.
+    expect(Math.abs(layout.activityLeft - 14)).toBeLessThanOrEqual(1);
+    const [activityRight, themeLeft, themeRight, linkLeft] = layout.actionsGap;
+    expect(Math.abs((themeLeft - activityRight) - (linkLeft - themeRight))).toBeLessThanOrEqual(1);
     expect(Math.abs(layout.linkRight - 14)).toBeLessThanOrEqual(1);
     await expect(page.getByRole('link', { name: 'ComfyUI', exact: true })).toBeVisible();
     await theme.selectOption('light');
@@ -506,18 +523,18 @@ test('a slow Images count does not delay the Library and Tags badges', async ({
     await expect(navCount(page, 'images')).toHaveText(String(totals.images));
 });
 
-test('sidebar bottom holds System and Overview with a neutral connection', async ({ page }) => {
+test('sidebar bottom holds Activity, System and Overview with a neutral connection', async ({ page }) => {
     await page.goto(`${workspace}#/system`);
     const bottom = page.locator('aside.sidebar > .sidebar-bottom');
     expect(await childShape(bottom)).toEqual(['nav#system-nav', 'div.connection']);
     const system = page.locator('nav#system-nav');
     await expect(system).toHaveAttribute('aria-label', 'Tools and system');
     expect(await system.locator(':scope > a').evaluateAll(nodes => nodes.map(node => [node.getAttribute('href'), node.textContent]))).toEqual([
-        ['#/system', 'System'], ['#/overview', 'Overview'],
+        ['#/activity', 'Activity'], ['#/system', 'System'], ['#/overview', 'Overview'],
     ]);
     await expect(system.locator('.nav-count')).toHaveCount(0);
     await expect(system.locator('a[href="#/system"]')).toHaveAttribute('aria-current', 'page');
-    await expect(system.locator('svg.icon')).toHaveCount(2);
+    await expect(system.locator('svg.icon')).toHaveCount(3);
     const connection = bottom.locator('.connection');
     expect(await childShape(connection)).toEqual(['i', 'div']);
     await expect(connection.locator(':scope > div')).toHaveText('ComfyUI workspaceYour library, on your server');
@@ -679,8 +696,14 @@ async function serveUnderProxyMount(page) {
     await page.route(url => url.pathname.startsWith(`${PROXY_MOUNT}/`), async route => {
         const url = new URL(route.request().url());
         url.pathname = url.pathname.slice(PROXY_MOUNT.length);
-        const response = await route.fetch({ url: url.href });
-        await route.fulfill({ response });
+        // A request still in flight when the test ends (a thumbnail the last route started) meets a page that is
+        // closing: its fetched response is disposed under it. Only that teardown error is ignored.
+        try {
+            const response = await route.fetch({ url: url.href });
+            await route.fulfill({ response });
+        } catch (error) {
+            if (!/has been disposed|has been closed|Target page, context or browser has been closed/.test(String(error?.message))) throw error;
+        }
     });
     return escaped;
 }

tests/browser/workspace_activity_fixture.py

@@ -0,0 +1,194 @@
+"""Fake Activity jobs for the browser tests (#249 Activity-1).
+
+A fake job is a real registry job whose runner waits for commands instead of
+reading files, so a test sets its progress and counters exactly:
+
+- ``POST /__test__/jobs/start`` starts one (``kind``, ``title``, ``total``,
+  ``output_folders``) and returns its summary, or 409 while one runs;
+- ``POST /__test__/jobs/{id}/step`` records ``records`` (``{group, path,
+  root, root_index, detail}`` file outcomes, counted, listed and logged as the scan
+  records them) and ``bulk`` (``{group, count, root}``: ``count`` numbered
+  rows), sets ``processed`` (and ``total``) and ``counters``, then publishes
+  the progress to every subscriber;
+- ``POST /__test__/jobs/{id}/finish`` ends it as ``finished``, ``cancelled``
+  or ``failed``; a cancel through the real route ends it ``cancelled``;
+- ``POST /__test__/jobs/restart`` acts out a ComfyUI restart: the open job
+  streams drop without a final event and the registry starts empty.
+"""
+
+import asyncio
+import re
+
+from aiohttp import web
+
+EVENTS_PATH = re.compile(r"^/prompt_manager/jobs/[0-9a-f]{32}/events$")
+FINAL_STATES = {"finished", "cancelled", "failed"}
+POLL_SECONDS = 0.02
+
+
+PREFIXES = {"added": "+", "known": "=", "review": "?", "errors": "!"}
+PREFIXES["no_metadata"] = "-"
+ROOT_INDEXES = {"output": 0, "input": 1}
+
+
+def outcome_records(data):
+    """The step's file outcomes: its ``records``, then its ``bulk`` rows."""
+    records = data.get("records", [])
+    bulk = data.get("bulk")
+    if not isinstance(records, list):
+        raise web.HTTPBadRequest()
+    rows = []
+    for record in records:
+        if not isinstance(record, dict) or record.get("group") not in PREFIXES:
+            raise web.HTTPBadRequest()
+        root = str(record.get("root", "output"))
+        rows.append(
+            {
+                "group": record["group"],
+                "path": str(record.get("path", "")),
+                "root": root,
+                # The fixture's listing order: output is root 0, input root 1.
+                "root_index": record.get("root_index", ROOT_INDEXES.get(root)),
+                "detail": str(record.get("detail", "")),
+            }
+        )
+    if bulk is not None:
+        if not isinstance(bulk, dict) or bulk.get("group") not in PREFIXES:
+            raise web.HTTPBadRequest()
+        total = bulk.get("count")
+        if isinstance(total, bool) or not isinstance(total, int) or total < 0:
+            raise web.HTTPBadRequest()
+        rows.extend(
+            {
+                "group": bulk["group"],
+                "path": f"bulk/file_{index:05d}.png",
+                "root": str(bulk.get("root", "output")),
+                "root_index": 0,
+                "detail": f"Bulk row {index}",
+            }
+            for index in range(total)
+        )
+    return rows
+
+
+def register_activity_commands(app, routes, api):
+    from py.api.jobs import SCAN_GROUP_NAMES, JobBusy, JobRegistry
+
+    streams = set()
+    endings = {}
+
+    @web.middleware
+    async def track_streams(request, handler):
+        if not EVENTS_PATH.match(request.path):
+            return await handler(request)
+        transport = request.transport
+        streams.add(transport)
+        try:
+            return await handler(request)
+        finally:
+            streams.discard(transport)
+
+    app.middlewares.append(track_streams)
+
+    def fake_runner(ending):
+        async def run(job):
+            while not ending.done() and not job.cancelled:
+                await asyncio.sleep(POLL_SECONDS)
+            state = ending.result() if ending.done() else "cancelled"
+            job.publish({"type": "complete", "progress": job.progress})
+            job.finish(state)
+
+        return run
+
+    def job_or_404(request):
+        job = api._jobs.get(request.match_info["job_id"])
+        if job is None or job.id not in endings:
+            raise web.HTTPNotFound()
+        return job
+
+    async def body(request):
+        data = await request.json() if request.can_read_body else {}
+        if not isinstance(data, dict):
+            raise web.HTTPBadRequest()
+        return data
+
+    def count(value, default=0):
+        if value is None:
+            return default
+        if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+            raise web.HTTPBadRequest()
+        return value
+
+    @routes.post("/__test__/jobs/start")
+    async def start_job(request):
+        data = await body(request)
+        ending = asyncio.get_running_loop().create_future()
+        try:
+            job = api._jobs.start(
+                str(data.get("kind", "scan")),
+                str(data.get("title", "Scan for metadata")),
+                record_changing=True,
+                scope={
+                    "files": str(data.get("files", "new")),
+                    "output_folders": count(data.get("output_folders"), 2),
+                },
+                runner=fake_runner(ending),
+                groups=SCAN_GROUP_NAMES,
+            )
+        except JobBusy:
+            raise web.HTTPConflict()
+        job.update(total=count(data.get("total")))
+        endings[job.id] = ending
+        return web.json_response({"success": True, "job": job.summary()})
+
+    @routes.post("/__test__/jobs/{job_id}/step")
+    async def step_job(request):
+        job = job_or_404(request)
+        data = await body(request)
+        total = count(data.get("total"), job.total)
+        processed = count(data.get("processed"), job.processed)
+        counters = data.get("counters", {})
+        if not isinstance(counters, dict) or set(counters) - set(job.counters):
+            raise web.HTTPBadRequest()
+        for record in outcome_records(data):
+            group = record["group"]
+            path = record["path"]
+            detail = record["detail"]
+            job.record(group, record, f"{PREFIXES[group]} {path} · {detail}")
+        for key, value in counters.items():
+            job.counters[key] = count(value)
+        progress = processed * 100 // total if total else 0
+        job.update(
+            progress=progress,
+            processed=processed,
+            total=total,
+            status_line=f"Processing file {processed:,} of {total:,}",
+        )
+        job.publish({"type": "progress", "progress": progress})
+        return web.json_response({"success": True, "job": job.summary()})
+
+    @routes.post("/__test__/jobs/{job_id}/finish")
+    async def finish_job(request):
+        job = job_or_404(request)
+        state = (await body(request)).get("state", "finished")
+        if state not in FINAL_STATES:
+            raise web.HTTPBadRequest()
+        ending = endings[job.id]
+        if not ending.done():
+            ending.set_result(state)
+        while job.running:
+            await asyncio.sleep(POLL_SECONDS)
+        return web.json_response({"success": True, "job": job.summary()})
+
+    @routes.post("/__test__/jobs/restart")
+    async def restart(request):
+        old = api._jobs
+        api._jobs = JobRegistry(api.logger)
+        endings.clear()
+        for transport in list(streams):
+            transport.close()
+        tasks = [job.task for job in old.list() if job.task and not job.task.done()]
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        return web.json_response({"success": True})

tests/browser/workspace_concept_fixture.py

@@ -158,6 +158,9 @@ MAX_EXTRA_IMAGES = 120
 # Unlinked, seedless images (D11 "W × H · PNG") newer than the concept's, for D3 checks.
 MAX_SEEDLESS_IMAGES = 2
 SEEDLESS_SIZE = (1536, 1152)
+# The same 4:3 shape with a short "96 × 72 · PNG" subtitle that stays on one line at
+# 390px beside the card's Info and Tag (the D3 footer check).
+SHORT_SEEDLESS_SIZE = (96, 72)
 SESSION = "5c1f9a7e-3f0b-4a55-9d0e-2b8c4f6a7d10"
 _TABLES = (
     "execution_run_outputs",
@@ -170,6 +173,9 @@ _TABLES = (
     "execution_context_texts",
     "saved_views",
     "image_favorites",
+    "media_image_tags",
+    "media_annotation_bytes",
+    "media_annotation_files",
     "image_prompt_pairs",
     "prompt_pair_tags",
     "prompt_pairs",
@@ -323,9 +329,9 @@ def _record_run(
     return start.run_id
 
 
-def _write_seedless_png(path: Path) -> None:
+def _write_seedless_png(path: Path, size: tuple[int, int] = SEEDLESS_SIZE) -> None:
     """A plain PNG with no metadata: no prompt, no seed, no link."""
-    with Image.new("RGB", SEEDLESS_SIZE, "#2b3442") as image:
+    with Image.new("RGB", size, "#2b3442") as image:
         image.save(path)
 
 
@@ -342,13 +348,17 @@ def seed_workspace_concept(
     *,
     extra_images: int = 0,
     seedless_images: int = 0,
+    short_seedless: bool = False,
 ) -> dict:
     """Replace this server's disposable rows and files with the concept's data.
 
     ``extra_images`` continues the concept's rounds (same prompts, dimensions and
     seed rule) after its 24 images, for bounded-rendering and Load more checks.
-    ``seedless_images`` adds unlinked PNGs without metadata, newest of all.
+    ``seedless_images`` adds unlinked PNGs without metadata, newest of all;
+    ``short_seedless`` makes them ``SHORT_SEEDLESS_SIZE`` instead.
     """
+    if not isinstance(short_seedless, bool):
+        raise TypeError("short_seedless must be a boolean")
     _bounded("extra_images", extra_images, MAX_EXTRA_IMAGES)
     _bounded("seedless_images", seedless_images, MAX_SEEDLESS_IMAGES)
     _clear(api, root)
@@ -456,7 +466,9 @@ def seed_workspace_concept(
     for number in range(seedless_images):
         name = f"seedless_{number + 1:05}.png"
         path = folder / name
-        _write_seedless_png(path)
+        _write_seedless_png(
+            path, SHORT_SEEDLESS_SIZE if short_seedless else SEEDLESS_SIZE
+        )
         stamp = now - 10 - number * 10
         os.utime(path, (stamp, stamp))
         seedless.append({"filename": name, "path": f"concepts/{name}"})

tests/browser/workspace_library_editor_fixture.py

@@ -28,6 +28,9 @@ EDITOR_METADATA = {
 _TABLES = (
     "saved_views",
     "image_favorites",
+    "media_image_tags",
+    "media_annotation_bytes",
+    "media_annotation_files",
     "image_prompt_pairs",
     "prompt_pair_tags",
     "prompt_pairs",

tests/browser/workspace_tagging_fixture.py

@@ -0,0 +1,313 @@
+"""Owned, deterministic files for the Tag image dialog workflows (#249 PR C).
+
+Two files share one positive prompt and one saved pair, an equal-byte copy of
+the first sits at another path, and a video and an unlinked file follow. The
+injected fake model (``tests/browser/server.py`` ``TestModel``) answers
+Generate; no model file exists and nothing is ever downloaded.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import shutil
+import time
+from typing import TYPE_CHECKING
+
+from aiohttp import web
+from PIL import Image
+from PIL.PngImagePlugin import PngInfo
+
+if TYPE_CHECKING:
+    from py.api import PromptManagerAPI
+
+POSITIVE = (
+    "Monolithic sandstone pavilion in a vast desert, sweeping dunes, warm "
+    "terracotta, late afternoon sun, architectural photography, quiet geometry"
+)
+NEGATIVE = "plastic, harsh shadows, noise, watermark"
+TITLE = "Quiet geometry"
+PROMPT_TAGS = ["minimal", "warm_light"]
+PAIR_TAGS = ["editorial"]
+# Newest first, so the Images order (Recently added) is the manifest's.
+FILES = (
+    ("tagging/dunes_00001.png", "linked"),
+    ("tagging/dunes_00002.png", "linked"),
+    ("copies/dunes_00001.png", "copy"),
+    ("tagging/clip.webm", "video"),
+    ("loose/unlinked.png", "unlinked"),
+)
+MODELS = ("wd14-swinv2", "wd14-vit", "gguf", "hf")
+# Unlinked copies enough to virtualize the Images grid (it renders all up to 120).
+MAX_EXTRA_IMAGES = 160
+_TABLES = (
+    "saved_views",
+    "image_favorites",
+    "media_image_tags",
+    "media_annotation_bytes",
+    "media_annotation_files",
+    "image_prompt_pairs",
+    "prompt_pair_tags",
+    "prompt_pairs",
+    "generated_images",
+    "prompt_tags",
+    "tags",
+    "prompt_library_state",
+    "prompts",
+)
+# Every prompt-side owner row a Tag save could touch, for before/after
+# comparisons: tagging one image never changes a prompt, a pair or a link.
+_SNAPSHOT = {
+    "prompts": "SELECT id, text, category, tags, updated_at FROM prompts ORDER BY id",
+    "prompt_tags": "SELECT prompt_id, tag_id FROM prompt_tags ORDER BY 1, 2",
+    "prompt_pairs": "SELECT id, positive_prompt_id, negative_prompt_id, category,"
+    " archived, updated_at FROM prompt_pairs ORDER BY id",
+    "prompt_pair_tags": "SELECT pair_id, tag_id FROM prompt_pair_tags ORDER BY 1, 2",
+    "generated_images": "SELECT id, prompt_id, image_path FROM generated_images"
+    " ORDER BY id",
+    "image_prompt_pairs": "SELECT id, image_id, pair_id FROM image_prompt_pairs"
+    " ORDER BY id",
+}
+
+
+def _png(path: Path, colour: tuple[int, int, int], size=(96, 64)) -> None:
+    graph = {
+        "1": {"class_type": "CLIPTextEncode", "inputs": {"text": POSITIVE}},
+        "2": {"class_type": "CLIPTextEncode", "inputs": {"text": NEGATIVE}},
+        "3": {
+            "class_type": "KSampler",
+            "inputs": {"positive": ["1", 0], "negative": ["2", 0], "seed": 7},
+        },
+        "4": {"class_type": "SaveImage", "inputs": {"images": ["3", 0]}},
+    }
+    info = PngInfo()
+    info.add_text("prompt", json.dumps(graph))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with Image.new("RGB", size, colour) as image:
+        image.save(path, pnginfo=info)
+
+
+def seed_tagging(api: PromptManagerAPI, root: Path, extra_images: int = 0) -> dict:
+    """Replace this server's disposable rows and files with the tagging set."""
+    db = api.db
+    with db.model.get_connection() as conn:
+        for table in _TABLES:
+            conn.execute(f"DELETE FROM {table}")
+    for name in ("output", "input"):
+        shutil.rmtree(root / name)
+        (root / name).mkdir()
+    output = root / "output"
+    _png(output / FILES[0][0], (196, 140, 92))
+    _png(output / FILES[1][0], (150, 110, 80))
+    (output / FILES[2][0]).parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(output / FILES[0][0], output / FILES[2][0])
+    shutil.copyfile(
+        Path(__file__).resolve().parents[1] / "fixtures" / "tiny.webm",
+        output / FILES[3][0],
+    )
+    _png(output / FILES[4][0], (60, 70, 90), size=(64, 64))
+    now = time.time()
+    for index, (relative, _) in enumerate(FILES):
+        stamp = now - 60 - index * 10
+        os.utime(output / relative, (stamp, stamp))
+    for number in range(extra_images):
+        extra = output / "bulk" / f"bulk_{number:04}.png"
+        extra.parent.mkdir(exist_ok=True)
+        shutil.copyfile(output / FILES[4][0], extra)
+        stamp = now - 600 - number
+        os.utime(extra, (stamp, stamp))
+
+    receipt = db.create_library_recipe(
+        POSITIVE,
+        NEGATIVE,
+        expected_epoch=db.get_execution_epoch(),
+        parent_metadata={
+            "title": TITLE,
+            "category": "Architecture",
+            "tags": list(PROMPT_TAGS),
+        },
+    )
+    positive_id = receipt["positive"]["id"]
+    pair_id = receipt["pair"]["id"]
+    with db.model.get_connection() as conn:
+        tag_ids = []
+        for name in PAIR_TAGS:
+            conn.execute("INSERT OR IGNORE INTO tags (name) VALUES (?)", (name,))
+            tag_ids.append(
+                conn.execute("SELECT id FROM tags WHERE name=?", (name,)).fetchone()[0]
+            )
+        conn.executemany(
+            "INSERT INTO prompt_pair_tags (pair_id, tag_id) VALUES (?, ?)",
+            [(pair_id, tag_id) for tag_id in tag_ids],
+        )
+    for relative, kind in FILES:
+        if kind in {"linked", "video"}:
+            image_id = db.link_image_to_prompt(positive_id, str(output / relative))
+            if kind == "linked":
+                db.link_image_to_pair(pair_id, image_id, {"source": "fixture"})
+    api._generate_gallery_thumbnails_sync(api._get_all_output_dirs(), (150, 150))
+    api.invalidate_gallery_cache()
+    return {
+        "positive_id": positive_id,
+        "pair_id": pair_id,
+        "title": TITLE,
+        "prompt_tags": list(PROMPT_TAGS),
+        "pair_tags": list(PAIR_TAGS),
+        "files": [
+            {"path": relative, "filename": Path(relative).name, "kind": kind}
+            for relative, kind in FILES
+        ],
+    }
+
+
+def tagging_snapshot(api: PromptManagerAPI) -> dict:
+    """Plain rows of every prompt, pair and link table."""
+    with api.db.model.get_connection() as conn:
+        return {
+            name: [list(row) for row in conn.execute(query)]
+            for name, query in _SNAPSHOT.items()
+        }
+
+
+def register_tagging_commands(
+    routes: web.RouteTableDef, api: PromptManagerAPI, root: Path, model
+) -> None:
+    """Register fixed seed, snapshot and fake-model commands; no paths or SQL input."""
+
+    @routes.post("/__test__/tagging/reset")
+    async def reset(request: web.Request) -> web.Response:
+        data = await request.json() if request.can_read_body else {}
+        if request.query or not isinstance(data, dict) or set(data) - {"extra_images"}:
+            raise web.HTTPBadRequest()
+        extra = data.get("extra_images", 0)
+        if isinstance(extra, bool) or not isinstance(extra, int):
+            raise web.HTTPBadRequest()
+        if not 0 <= extra <= MAX_EXTRA_IMAGES:
+            raise web.HTTPBadRequest()
+        model.unavailable = set()
+        model.suggestions = None
+        model.loaded = None
+        _set_defaults(model, DEFAULTS)
+        # A test that ends with the dialog open leaves its capture behind; drop
+        # every capture so the next test starts below the store's limits.
+        await api._run_in_executor(api.close_annotation_captures)
+        manifest = await api._run_in_executor(seed_tagging, api, root, extra)
+        return web.json_response({"success": True, **manifest})
+
+    @routes.get("/__test__/tagging/snapshot")
+    async def snapshot(request: web.Request) -> web.Response:
+        if request.query:
+            raise web.HTTPBadRequest()
+        return web.json_response(await api._run_in_executor(tagging_snapshot, api))
+
+    @routes.post("/__test__/tagging/models")
+    async def models(request: web.Request) -> web.Response:
+        """Mark fake models as not downloaded (``{"unavailable": [...]}``)."""
+        data = await request.json() if request.can_read_body else None
+        if (
+            request.query
+            or not isinstance(data, dict)
+            or set(data) != {"unavailable"}
+            or not isinstance(data["unavailable"], list)
+            or any(name not in MODELS for name in data["unavailable"])
+        ):
+            raise web.HTTPBadRequest()
+        model.unavailable = set(data["unavailable"])
+        return web.json_response({"success": True})
+
+    @routes.post("/__test__/tagging/suggestions")
+    async def suggestions(request: web.Request) -> web.Response:
+        """Answer Generate with fixed scored names (the concept's own sample).
+
+        ``{"scored": [[name, confidence], ...]}`` (at most 100, confidence in
+        [0, 1]) or ``{"scored": null}`` for the default list. Every capture is
+        released too, so a concept comparison starts below the store's limits
+        whatever the previous test left open.
+        """
+        data = await request.json() if request.can_read_body else None
+        scored = data.get("scored") if isinstance(data, dict) else None
+        if (
+            request.query
+            or not isinstance(data, dict)
+            or set(data) != {"scored"}
+            or not (scored is None or _valid_scored(scored))
+        ):
+            raise web.HTTPBadRequest()
+        model.suggestions = (
+            None if scored is None else [(name, float(value)) for name, value in scored]
+        )
+        model.unavailable = set()
+        await api._run_in_executor(api.close_annotation_captures)
+        return web.json_response({"success": True})
+
+    @routes.post("/__test__/tagging/defaults")
+    async def defaults(request: web.Request) -> web.Response:
+        """Serve other tagging defaults from ``GET /autotag/models``.
+
+        ``{"general": g, "character": c, "limit": n}``: the WD14 thresholds
+        (in [0, 1]) and the persisted suggestion count (1..100), so a test can
+        tell the server's values from the dialog's built-in ones. Reset
+        restores the standard 0.35 / 0.85 / 10.
+        """
+        data = await request.json() if request.can_read_body else None
+        if request.query or not _valid_defaults(data):
+            raise web.HTTPBadRequest()
+        _set_defaults(model, (data["general"], data["character"], data["limit"]))
+        return web.json_response({"success": True})
+
+    @routes.get("/__test__/tagging/captures")
+    async def captures(request: web.Request) -> web.Response:
+        """How many captures the store holds (a released capture is gone)."""
+        if request.query:
+            raise web.HTTPBadRequest()
+        store = api._captures
+        count = store.stats()["captures"] if store is not None else 0
+        return web.json_response({"captures": count})
+
+
+# The standard tagging defaults: WD14 general and character thresholds, and
+# the suggestion count (``AutotagConfig``).
+DEFAULTS = (0.35, 0.85, 10)
+
+
+def _set_defaults(model, values) -> None:
+    from py.config import AutotagConfig
+
+    general, character, limit = values
+    model.wd14_general_threshold = general
+    model.wd14_character_threshold = character
+    AutotagConfig.SUGGESTION_LIMIT = limit
+
+
+def _valid_defaults(data: object) -> bool:
+    unit = (
+        lambda value: isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and 0 <= value <= 1
+    )
+    return (
+        isinstance(data, dict)
+        and set(data) == {"general", "character", "limit"}
+        and unit(data["general"])
+        and unit(data["character"])
+        and type(data["limit"]) is int
+        and 1 <= data["limit"] <= 100
+    )
+
+
+def _valid_scored(scored: object) -> bool:
+    return (
+        isinstance(scored, list)
+        and len(scored) <= 100
+        and all(
+            isinstance(row, list)
+            and len(row) == 2
+            and isinstance(row[0], str)
+            and 0 < len(row[0]) <= 50
+            and isinstance(row[1], (int, float))
+            and not isinstance(row[1], bool)
+            and 0 <= row[1] <= 1
+            for row in scored
+        )
+    )

tests/browser/workspace_visual_fixture.py

@@ -114,6 +114,9 @@ def seed_workspace_visual(api: PromptManagerAPI, root: Path) -> None:
         for table in (
             "saved_views",
             "image_favorites",
+            "media_image_tags",
+            "media_annotation_bytes",
+            "media_annotation_files",
             "image_prompt_pairs",
             "prompt_pair_tags",
             "prompt_pairs",

tests/browser/workspace_vocabulary_fixture.py

@@ -81,6 +81,9 @@ MAX_EXTRA_CATEGORIES = 200
 _TABLES = (
     "saved_views",
     "image_favorites",
+    "media_image_tags",
+    "media_annotation_bytes",
+    "media_annotation_files",
     "image_prompt_pairs",
     "prompt_pair_tags",
     "prompt_pairs",

tests/comfyui/inspect-sender.spec.mjs

@@ -0,0 +1,126 @@
+import {test,expect} from '../../tools/vendor/node_modules/@playwright/test/index.mjs';
+import {installHostHooks} from './host-fixture.mjs';
+import {sendablePng,localFixture,POSITIVE_LINES} from '../browser/local-inspect-files.mjs';
+
+// PR L2 Task 7 of the local-Inspect plan (#249): a file read entirely in the browser by the native Inspect page sends
+// its exact roles into a real Prompt Manager (+/-) node, in Classic and Nodes 2.0, switching both ways and reloading
+// the graph each time. Nothing queues or loads a workflow, and a connected destination input rejects the whole send.
+installHostHooks(test,['PromptManagerPair']);
+
+// The PNG's positive spans lines and its negative is a ConditioningZeroOut (explicitly empty); the WebM carries the
+// committed core video's per-key tags.
+const FILES=[
+    {file:()=>sendablePng('host-send.png'),positive:POSITIVE_LINES,negative:'',shown:'No negative prompt (explicitly empty)'},
+    {file:()=>localFixture('core-tags.webm','video/webm','host-send.webm'),positive:'a red fox in snow, detailed fur',negative:'blurry, lowres',shown:'blurry, lowres'},
+];
+
+async function nodeState(page,id) {
+    return page.evaluate(async id=>{
+        const {app}=await import('/scripts/app.js');const node=app.graph.getNodeById(id);const serialized=node.serialize();
+        return {inputs:(await app.graphToPrompt()).output[String(id)].inputs,widgets:Object.fromEntries(node.widgets.map(widget=>[widget.name,widget.value])),
+            serialized:Object.fromEntries(node.widgets.map((widget,index)=>[widget.name,serialized.widgets_values[index]])),effects:window.inspectEffects};
+    },id);
+}
+
+/**
+ * Counts every queue or workflow load until `restore` runs; with `reset`, first sets the destination's roles back to
+ * known values (the connected-input case sets them itself, before it links the input, as library-sender.spec does).
+ */
+async function watchHost(page,id,reset=true) {
+    await page.evaluate(async ({id,reset})=>{
+        const {app}=await import('/scripts/app.js');const node=app.graph.getNodeById(id);
+        if(reset){node.widgets.find(widget=>widget.name==='text').value='Before positive';node.widgets.find(widget=>widget.name==='negative_text').value='Before negative';}
+        window.inspectEffects={queue:0,load:0};window.inspectOriginals={};
+        for(const [method,key] of [['queuePrompt','queue'],['loadGraphData','load']]){const original=app[method];window.inspectOriginals[method]=original;app[method]=function(...args){window.inspectEffects[key]++;return original.apply(this,args);};}
+    },{id,reset});
+}
+const restore=page=>page.evaluate(async()=>{const {app}=await import('/scripts/app.js');Object.assign(app,window.inspectOriginals);});
+
+/** Chooses `file` on the Inspect page and opens the shared viewer on its local record. */
+async function inspect(workspace,{file,positive,shown}) {
+    await workspace.locator('#local-file').setInputFiles(file());
+    const open=workspace.locator('#workspace-main .heading-actions').getByRole('button',{name:'Open file metadata',exact:true});
+    await expect(open).toHaveAttribute('aria-disabled','false');await open.click();
+    const rail=workspace.locator('dialog#viewer-dialog[open] #viewer-details');
+    await expect(rail.locator('.prompt-section.positive p.prompt-text')).toHaveText(positive);
+    await expect(rail.locator('.prompt-section.negative p.prompt-text')).toHaveText(shown);
+    return rail;
+}
+
+/** The rail's pair send, through to a previewed destination; returns the sender dialog. */
+async function preview(workspace,rail) {
+    await rail.getByRole('button',{name:/^Send prompt pair to ComfyUI: /}).click();
+    const sender=workspace.getByRole('dialog',{name:'Send to ComfyUI',exact:true});
+    const hosts=sender.getByRole('combobox',{name:'ComfyUI window',exact:true});await expect(hosts.locator('option')).toHaveCount(2);await hosts.selectOption({index:1});
+    await sender.getByRole('combobox',{name:'Destination node',exact:true}).selectOption({index:1});
+    await sender.getByRole('button',{name:'Preview changes',exact:true}).click();
+    return sender;
+}
+
+async function closeViewer(workspace,sender) {
+    await sender.getByRole('button',{name:'Close',exact:true}).click();await expect(sender).toHaveCount(0);
+    await workspace.keyboard.press('Escape');await expect(workspace.locator('dialog#viewer-dialog[open]')).toHaveCount(0);
+}
+
+test('local file roles send exactly across renderer transitions',async({page,context},testInfo)=>{
+    test.setTimeout(180000);
+    const id=await page.evaluate(async()=>{
+        const {app}=await import('/scripts/app.js');const node=LiteGraph.createNode('PromptManagerPair');app.graph.add(node);
+        node.setSize([700,1000]);app.canvas.ds.scale=.8;app.canvas.centerOnNode(node);return node.id;
+    });
+    const workspace=await context.newPage();const errors=[];workspace.on('pageerror',error=>errors.push(error.message));
+    const requests=[];workspace.on('request',request=>{if(request.method()!=='GET')requests.push(`${request.method()} ${request.url()}`);});
+    const logged=[];workspace.on('console',message=>logged.push(message.text()));
+    try {
+        await workspace.goto('/prompt_manager/workspace#/inspect');
+        await expect(workspace.locator('#workspace-main h1')).toHaveText('Inspect a file');
+        const initial=testInfo.project.metadata.initialRenderer;
+        for(const renderer of [initial,!initial,initial]) {
+            // The renderer switch reloads the graph, as a workflow reload does.
+            await page.evaluate(async renderer=>{const {app}=await import('/scripts/app.js');await app.ui.settings.setSettingValue('Comfy.VueNodes.Enabled',renderer);await app.loadGraphData(app.graph.serialize());app.canvas.centerOnNode(app.graph._nodes[0]);},renderer);
+            await expect.poll(()=>page.evaluate(()=>LiteGraph.vueNodesMode)).toBe(renderer);
+            for(const entry of FILES) {
+                await watchHost(page,id);
+                try {
+                    const rail=await inspect(workspace,entry);
+                    const sender=await preview(workspace,rail);
+                    for(const text of ['Before positive','Before negative',...entry.positive.split('\n'),entry.negative||'(empty)'])await expect(sender).toContainText(text);
+                    await sender.getByRole('button',{name:'Apply to ComfyUI',exact:true}).click();await expect(sender).toContainText('Sent to ComfyUI.');
+                    const state=await nodeState(page,id);
+                    expect(state.effects).toEqual({queue:0,load:0});
+                    for(const field of ['inputs','serialized'])expect(state[field]).toMatchObject({text:entry.positive,negative_text:entry.negative});
+                    await closeViewer(workspace,sender);
+                } finally {await restore(page);}
+            }
+        }
+        // A connected destination input rejects the whole preview: neither role changes, nothing queues or loads.
+        const link=await page.evaluate(async id=>{
+            const {app}=await import('/scripts/app.js');const {convertToInput}=await import('/extensions/core/widgetInputs.js');
+            const node=app.graph.getNodeById(id);const widget=node.widgets.find(item=>item.name==='negative_text');
+            if(!node.inputs.some(input=>input.name==='negative_text'))convertToInput(node,widget);
+            node.widgets.find(item=>item.name==='text').value='Before positive';widget.value='Before negative';
+            const source=LiteGraph.createNode('PrimitiveString');app.graph.add(source);source.widgets.find(item=>item.name==='value').value='Upstream negative';
+            source.connect(0,node,node.inputs.findIndex(input=>input.name==='negative_text'));
+            return [String(source.id),0];
+        },id);
+        await watchHost(page,id,false);
+        try {
+            const before=await nodeState(page,id);
+            expect(before.widgets).toMatchObject({text:'Before positive',negative_text:'Before negative'});
+            const rail=await inspect(workspace,FILES[1]);
+            const sender=await preview(workspace,rail);
+            await expect(sender.getByRole('alert')).toContainText(/connected/i);
+            await expect(sender.getByRole('button',{name:'Apply to ComfyUI',exact:true})).toBeDisabled();
+            const rejected=await nodeState(page,id);
+            expect(rejected.effects).toEqual({queue:0,load:0});
+            expect(rejected.inputs.negative_text).toEqual(link);
+            for(const field of ['widgets','serialized'])expect(rejected[field]).toMatchObject({text:'Before positive',negative_text:'Before negative'});
+            await closeViewer(workspace,sender);
+        } finally {await restore(page);}
+        // The workspace page sent nothing to the server (the only crossing is the host bridge) and logged nothing of
+        // the files: no name and no prompt text.
+        expect(requests).toEqual([]);
+        expect(logged.filter(text=>/host-send|lighthouse|long exposure|red fox|lowres/.test(text))).toEqual([]);
+        expect(errors).toEqual([]);
+    } finally {await workspace.close();}
+});

tests/fixtures/README.md

@@ -13,6 +13,75 @@ ffmpeg -f lavfi -i testsrc=size=32x32:rate=4:duration=1 \
 
 Browser tests use the committed file; FFmpeg is not required to run them.
 
+# Local Inspect header fixtures
+
+`local-inspect/tiny.jpg` (48x32) and `local-inspect/tiny.webp` (40x24) are original
+synthetic FFmpeg color test patterns, under 4 KB, dedicated to the public domain
+under CC0-1.0. `tests/js/png-local-reader.test.js` reads their dimensions with the
+browser header reader and `tests/test_local_inspect_parity.py` checks the same two
+files against Pillow.
+
+Reproduce with FFmpeg:
+
+```sh
+ffmpeg -f lavfi -i testsrc=size=48x32:rate=1 -frames:v 1 -q:v 10 tiny.jpg
+ffmpeg -f lavfi -i testsrc=size=40x24:rate=1 -frames:v 1 -c:v libwebp -quality 40 tiny.webp
+```
+
+# Local Inspect video fixtures
+
+`local-inspect/core-faststart.mp4`, `core-moov-end.mp4`, `core.mov`, `core.m4v`,
+`core.mkv`, `core-tags.webm`, `legacy-comment.mp4` and `legacy-comment.webm` are
+0.2-second 16x16 black clips (each under 4 KB) carrying an original synthetic
+ComfyUI graph in their container tags, dedicated to the public domain under
+CC0-1.0. The `core-*` files carry one tag per key as core SaveVideo/SaveWEBM write
+them (MP4/MOV/M4V through `-movflags use_metadata_tags`; Matroska upper-cases the
+names); `core-faststart.mp4` also carries `parameters` and
+`comfyassets_prompt_pairs`. The `legacy-comment.*` files carry the old
+VideoHelperSuite `comment` JSON envelope (an ilst `©cmt` atom in MP4, a `COMMENT`
+tag in WebM). `video-tags-v1.json` records `ffprobe -show_entries format_tags -of
+json` for each file (ffmpeg 9.0.2); `tests/test_utils_video_metadata.py`
+`VideoFixtureFfprobeTests` re-checks it when ffprobe is installed, and
+`tests/js/workspace-local-video.test.js` plus `tests/test_local_inspect_parity.py`
+hold the browser video reader to the same maps.
+
+Reproduce with FFmpeg, from `tests/fixtures/local-inspect`:
+
+```sh
+PROMPT='{"3":{"class_type":"KSampler","inputs":{"seed":7,"steps":20,"cfg":8.0,"sampler_name":"euler","scheduler":"normal","denoise":1.0,"model":["4",0],"positive":["6",0],"negative":["7",0],"latent_image":["5",0]}},"4":{"class_type":"CheckpointLoaderSimple","inputs":{"ckpt_name":"synthetic-v1.safetensors"}},"5":{"class_type":"EmptyLatentImage","inputs":{"width":512,"height":512,"batch_size":1}},"6":{"class_type":"CLIPTextEncode","inputs":{"text":"a red fox in snow, detailed fur","clip":["4",1]}},"7":{"class_type":"CLIPTextEncode","inputs":{"text":"blurry, lowres","clip":["4",1]}},"8":{"class_type":"VAEDecode","inputs":{"samples":["3",0],"vae":["4",2]}},"9":{"class_type":"SaveVideo","inputs":{"filename_prefix":"video/synthetic","video":["8",0]}}}'
+WORKFLOW='{"last_node_id":9,"nodes":[{"id":3,"type":"KSampler","widgets_values":[7,"fixed",20,8.0,"euler","normal",1.0]},{"id":6,"type":"CLIPTextEncode","widgets_values":["a red fox in snow, detailed fur"]},{"id":7,"type":"CLIPTextEncode","widgets_values":["blurry, lowres"]}],"links":[],"version":0.4}'
+PARAMETERS=$'a red fox in snow, detailed fur\nNegative prompt: blurry, lowres\nSteps: 20, Sampler: Euler, CFG scale: 8.0, Seed: 7, Size: 512x512'
+PAIRS='{"version":1,"nodes":{"6":{"records":[{"positive_text":"a red fox in snow, detailed fur","negative_text":"blurry, lowres","negative_effective_text":"blurry, lowres","prepend_text":"","append_text":""}]}}}'
+COMMENT=$(PROMPT="$PROMPT" WORKFLOW="$WORKFLOW" python3 -c 'import json,os; print(json.dumps({"prompt": os.environ["PROMPT"], "workflow": json.loads(os.environ["WORKFLOW"])}))')
+SRC=(-v quiet -y -f lavfi -i "color=c=black:s=16x16:d=0.2")
+ffmpeg "${SRC[@]}" -movflags use_metadata_tags+faststart -metadata prompt="$PROMPT" -metadata workflow="$WORKFLOW" -metadata parameters="$PARAMETERS" -metadata comfyassets_prompt_pairs="$PAIRS" core-faststart.mp4
+ffmpeg "${SRC[@]}" -movflags use_metadata_tags -metadata prompt="$PROMPT" -metadata workflow="$WORKFLOW" core-moov-end.mp4
+ffmpeg "${SRC[@]}" -movflags use_metadata_tags -metadata prompt="$PROMPT" -metadata workflow="$WORKFLOW" core.mov
+ffmpeg "${SRC[@]}" -movflags use_metadata_tags -metadata prompt="$PROMPT" -metadata workflow="$WORKFLOW" core.m4v
+ffmpeg "${SRC[@]}" -metadata prompt="$PROMPT" -metadata workflow="$WORKFLOW" core.mkv
+ffmpeg "${SRC[@]}" -c:v libvpx -metadata prompt="$PROMPT" -metadata workflow="$WORKFLOW" core-tags.webm
+ffmpeg "${SRC[@]}" -metadata comment="$COMMENT" legacy-comment.mp4
+ffmpeg "${SRC[@]}" -c:v libvpx -metadata comment="$COMMENT" legacy-comment.webm
+for f in core-faststart.mp4 core-moov-end.mp4 core.mov core.m4v core.mkv core-tags.webm legacy-comment.mp4 legacy-comment.webm; do
+  ffprobe -v quiet -show_entries format_tags -of json "$f"   # -> video-tags-v1.json "fixtures"[f] = .format.tags
+done
+```
+
+# Local Inspect projection cases
+
+`local-inspect/projection-cases.json` holds synthetic record sets (prompt, workflow,
+parameters and pair-record texts, optional `record_formats`, a video `carrier_text`
+and `limited` records) that exercise every branch of the server's inspection
+projection: Python's Decimal spellings and exact-construction limits, the 4300-digit
+integer limit, duplicate keys, NaN/Infinity, the depth-64 and node ceilings, prompt
+node key filtering and the carrier rule. `records: null` stands for an unreadable
+file. `expect` pins both graph statuses; `needs` names an interpreter feature a case
+depends on. `tests/js/workspace-local-projection.test.js` runs them through
+`web/js/workspace/local-projection.mjs`, and `tests/test_local_inspect_parity.py`
+asserts that its answer equals `utils.inspection_response._metadata` byte for byte.
+All texts are original synthetic content, dedicated to the public domain under
+CC0-1.0.
+
 # Inspection parity fixtures
 
 `inspection_parity/` holds small synthetic PNGs (`f01b.png` ... `f24.png`, each

tests/fixtures/local-inspect/projection-cases.json

@@ -0,0 +1,849 @@
+{
+ "version": 1,
+ "about": "Synthetic record sets for utils/inspection_response.py _metadata parity with web/js/workspace/local-projection.mjs projectMetadata. records null = an unreadable file. record_formats default to original-text for each record. expect pins both graph statuses; needs names an interpreter feature the Python side must have.",
+ "cases": [
+  {
+   "name": "unreadable_read",
+   "records": null,
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "absent_records",
+   "records": {},
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_and_workflow_parsed",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "all_four_records",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "{\"nodes\":[],\"version\":0.4}",
+    "parameters": "cat\nNegative prompt: dog\nSteps: 20, Sampler: Euler, Seed: 7",
+    "comfyassets_prompt_pairs": "{\"version\":1,\"nodes\":{}}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "parameters_only",
+   "records": {
+    "parameters": "cat\nSteps: 20"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "number_spellings",
+   "records": {
+    "workflow": "{\"nodes\":[],\"a\":[1e3,1e0,-0.0,6.50,0.0100,1.0e2,0e5,0.0000001,0.000001,1E+3,1e-0,0.5e1,0.05e1,0.0e0,1.5e+300,123e-8,2.5e-3,1.0,-1.50,0.0,100.0,1234567e-6,0.5E-6,0.5E-5,1e22,0.000000,-0.000000e-3,7.0e-6,7.0e-7,12345678901234567890.123,9007199254740992.0]}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "integer_spellings",
+   "records": {
+    "workflow": "{\"a\":[9007199254740991,-9007199254740991,9007199254740992,-9007199254740992,10000000000000000,123456789012345678901234567890,0,-0,42,-7,100]}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "nonfinite_literals_are_null",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"n\":NaN,\"i\":Infinity,\"m\":-Infinity},\"_meta\":{\"n\":NaN}}}",
+    "workflow": "{\"a\":[NaN,Infinity,-Infinity],\"b\":NaN}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "exponent_edges_valid",
+   "records": {
+    "workflow": "{\"a\":[1e999999999999999999,1e-1999999999999999997,0.0e1000000000000000000,1.5e999999999999999999,0.1e-1999999999999999996]}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_1e1000000000000000000",
+   "records": {
+    "workflow": "{\"a\":1e1000000000000000000}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_15e999999999999999999",
+   "records": {
+    "workflow": "{\"a\":15e999999999999999999}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_1e_1999999999999999998",
+   "records": {
+    "workflow": "{\"a\":1e-1999999999999999998}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_1_5e_1999999999999999997",
+   "records": {
+    "workflow": "{\"a\":1.5e-1999999999999999997}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_0e1000000000000000000",
+   "records": {
+    "workflow": "{\"a\":0e1000000000000000000}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_1e9223372036854775808",
+   "records": {
+    "workflow": "{\"a\":1e9223372036854775808}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_0_0e1000000000000000001",
+   "records": {
+    "workflow": "{\"a\":0.0e1000000000000000001}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "exponent_edge_invalid_1e99999999999999999999999999",
+   "records": {
+    "workflow": "{\"a\":1e99999999999999999999999999}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "int_4300_digits_kept",
+   "records": {
+    "workflow": "{\"a\":7777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "int_4301_digits_malformed",
+   "records": {
+    "workflow": "{\"a\":77777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777}"
+   },
+   "needs": "int-max-str-digits",
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "int_negative_4301_digits_malformed",
+   "records": {
+    "workflow": "{\"a\":-77777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777}"
+   },
+   "needs": "int-max-str-digits",
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "string_escapes",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"t\":\"é😀\\u0000\\u001f/\\\\\\\"\\b\\f\\n\\r\\t\",\"raw\":\"é😀 — 
\"}}}",
+    "workflow": "{\"s\":\"\\u00E9\\uD83D\\uDE00\\uD800\\uDC00x\\u0000\\u001f\\/\\\\\\\"\\b\\f\\n\\r\\t\\uD800\\u0041\\uDC00\"}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "lone_surrogate_in_raw_text",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"t\":\"𐏿\\udc00\"}}}",
+    "parameters": "\ud800 lone\nSteps: 1"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "keys_with_escapes_proto_and_order",
+   "records": {
+    "prompt": "{\"10\":{\"class_type\":\"B\",\"inputs\":{}},\"3\":{\"class_type\":\"A\",\"inputs\":{}},\"__proto__\":{\"class_type\":\"P\",\"inputs\":{\"constructor\":1}},\"constructor\":{\"class_type\":\"C\",\"inputs\":{}},\"\\u0000\":5,\"\":[]}",
+    "workflow": "{\"10\":1,\"3\":2,\"b\":3,\"a\":4,\"__proto__\":{\"x\":1},\"\":{}}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "duplicate_key_top_level",
+   "records": {
+    "workflow": "{\"a\":1,\"a\":2}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "duplicate_key_nested",
+   "records": {
+    "workflow": "{\"a\":{\"b\":[{\"c\":1,\"c\":1}]}}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "duplicate_key_in_dropped_prompt_meta",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"a\":1},\"_meta\":{\"t\":1,\"t\":2}}}"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "duplicate_key_in_prompt_inputs",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"a\":1,\"a\":1}}}"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "duplicate_key_after_deep_nest",
+   "records": {
+    "workflow": "{\"x\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]],\"a\":1,\"a\":2}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "workflow_depth_64_kept",
+   "records": {
+    "workflow": "{\"a\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "workflow_depth_65_limited",
+   "records": {
+    "workflow": "{\"a\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "limited"
+   }
+  },
+  {
+   "name": "prompt_inputs_depth_64_kept",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"v\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}}}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_inputs_depth_65_limited",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"v\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}}}"
+   },
+   "expect": {
+    "prompt_graph": "limited",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_dropped_meta_depth_65_limited",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{},\"_meta\":{\"v\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}}}"
+   },
+   "expect": {
+    "prompt_graph": "limited",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_non_object_nodes_kept",
+   "records": {
+    "prompt": "{\"1\":5,\"2\":[1,2.50,\"x\",null,true],\"3\":\"s\",\"4\":null,\"5\":{\"inputs\":[1],\"class_type\":null,\"other\":{\"deep\":[NaN]}}}"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_root_array_malformed",
+   "records": {
+    "prompt": "[]"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_root_string_malformed",
+   "records": {
+    "prompt": "\"{}\""
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_root_number_malformed",
+   "records": {
+    "prompt": "5"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "prompt_root_null_malformed",
+   "records": {
+    "prompt": "null"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "workflow_root_array_malformed",
+   "records": {
+    "workflow": "[1,2]"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "workflow_root_nan_malformed",
+   "records": {
+    "workflow": "NaN"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "empty_text_malformed",
+   "records": {
+    "prompt": "",
+    "workflow": "   "
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "bom_malformed",
+   "records": {
+    "workflow": "{}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "trailing_data_malformed",
+   "records": {
+    "workflow": "{\"a\":1} x",
+    "prompt": "{}\u0000"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "python_whitespace_only",
+   "records": {
+    "workflow": " \t\r\n{\n\t\"a\" :\r 1 }\n",
+    "prompt": "\u000b{}"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "syntax_errors",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{},}}",
+    "workflow": "[1,]"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "bad_escape_and_control_char",
+   "records": {
+    "prompt": "{\"1\":\"\\x\"}",
+    "workflow": "{\"a\":\"\u0001\"}"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "number_grammar",
+   "records": {
+    "prompt": "{\"1\":01}",
+    "workflow": "{\"a\":1.,\"b\":.5}"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "nodes_not_list_counts_zero",
+   "records": {
+    "workflow": "{\"nodes\":{\"a\":1},\"definitions\":{\"subgraphs\":[{\"nodes\":5},7,{\"nodes\":[1,2]}]}}"
+   },
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "limited_workflow_record",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "limited": [
+    "workflow"
+   ],
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "limited"
+   }
+  },
+  {
+   "name": "limited_workflow_without_text",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "limited": [
+    "workflow"
+   ],
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "limited"
+   }
+  },
+  {
+   "name": "invalid_workflow_format",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "record_formats": {
+    "prompt": "original-text",
+    "workflow": "invalid"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "reserialized_without_carrier_is_limited",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "record_formats": {
+    "prompt": "reserialized-json",
+    "workflow": "reserialized-json"
+   },
+   "expect": {
+    "prompt_graph": "limited",
+    "workflow_graph": "limited"
+   }
+  },
+  {
+   "name": "unknown_format_dropped_but_projected",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "record_formats": {
+    "prompt": "weird"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "non_text_record_dropped",
+   "records": {
+    "prompt": 5,
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "record_formats": {
+    "prompt": "original-text",
+    "workflow": "original-text"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "format_without_text_is_malformed",
+   "records": {},
+   "record_formats": {
+    "prompt": "original-text"
+   },
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "unknown_record_keys_ignored",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "Software": "ComfyUI",
+    "WORKFLOW": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "record_formats": {
+    "prompt": "original-text",
+    "Software": "original-text",
+    "WORKFLOW": "original-text"
+   },
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_prompt_string_workflow_object",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "{\"nodes\": [], \"v\": 1}"
+   },
+   "record_formats": {
+    "prompt": "original-text",
+    "workflow": "reserialized-json"
+   },
+   "carrier_text": "{\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"x\\\":1}}}\",\"workflow\":{\"nodes\":[],\"v\":1}}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "carrier_prompt_object_projected",
+   "records": {
+    "prompt": "{\"1\": {\"class_type\": \"A\", \"inputs\": {\"x\": 8.0}, \"_meta\": {\"t\": \"x\"}}}",
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "record_formats": {
+    "prompt": "reserialized-json",
+    "workflow": "original-text"
+   },
+   "carrier_text": "{\"prompt\":{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":8.0},\"_meta\":{\"t\":\"x\"}}},\"workflow\":{\"nodes\":[],\"version\":0.4},\"title\":\"n\",\"extra\":[1e3]}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "carrier_root_array_fails_all",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "carrier_text": "[1]",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "carrier_duplicate_key_fails_all",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "carrier_text": "{\"prompt\":\"{}\",\"prompt\":\"{}\"}",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_other_member_too_deep_limited",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "carrier_text": "{\"title\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]],\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"x\\\":1}}}\"}",
+   "expect": {
+    "prompt_graph": "limited",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_other_member_depth_64_kept",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "carrier_text": "{\"title\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]],\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"x\\\":1}}}\"}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_prompt_object_depth_shift",
+   "records": {
+    "prompt": "x"
+   },
+   "record_formats": {
+    "prompt": "reserialized-json"
+   },
+   "carrier_text": "{\"prompt\":{\"1\":{\"class_type\":\"A\",\"inputs\":{\"v\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}}}}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_prompt_object_depth_shift_limited",
+   "records": {
+    "prompt": "x"
+   },
+   "record_formats": {
+    "prompt": "reserialized-json"
+   },
+   "carrier_text": "{\"prompt\":{\"1\":{\"class_type\":\"A\",\"inputs\":{\"v\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}}}}",
+   "expect": {
+    "prompt_graph": "limited",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_prompt_string_invalid_json",
+   "records": {
+    "prompt": "{",
+    "workflow": "{\"nodes\":[],\"version\":0.4}"
+   },
+   "carrier_text": "{\"prompt\":\"{\",\"workflow\":\"{\\\"nodes\\\":[],\\\"version\\\":0.4}\"}",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "parsed"
+   }
+  },
+  {
+   "name": "carrier_prompt_string_too_deep",
+   "records": {
+    "prompt": "x"
+   },
+   "carrier_text": "{\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"v\\\":[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]}}}\"}",
+   "expect": {
+    "prompt_graph": "limited",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_workflow_number_malformed",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}",
+    "workflow": "5"
+   },
+   "record_formats": {
+    "prompt": "original-text",
+    "workflow": "original-text"
+   },
+   "carrier_text": "{\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"x\\\":1}}}\",\"workflow\":5}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "carrier_prompt_nonfinite_malformed",
+   "records": {
+    "prompt": "NaN"
+   },
+   "carrier_text": "{\"prompt\":NaN}",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_prompt_bigint_malformed",
+   "records": {
+    "prompt": "123456789012345678901"
+   },
+   "carrier_text": "{\"prompt\":123456789012345678901}",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_prompt_decimal_malformed",
+   "records": {
+    "prompt": "1.5"
+   },
+   "carrier_text": "{\"prompt\":1.5}",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_missing_member_malformed",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "carrier_text": "{\"workflow\":{}}",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_without_graph_records",
+   "records": {
+    "parameters": "cat"
+   },
+   "carrier_text": "{\"parameters\":\"cat\"}",
+   "expect": {
+    "prompt_graph": "absent",
+    "workflow_graph": "absent"
+   }
+  },
+  {
+   "name": "carrier_with_limited_workflow",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "limited": [
+    "workflow"
+   ],
+   "carrier_text": "{\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"x\\\":1}}}\"}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "limited"
+   }
+  },
+  {
+   "name": "carrier_invalid_workflow_format",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "record_formats": {
+    "prompt": "original-text",
+    "workflow": "invalid"
+   },
+   "carrier_text": "{\"prompt\":\"{\\\"1\\\":{\\\"class_type\\\":\\\"A\\\",\\\"inputs\\\":{\\\"x\\\":1}}}\",\"workflow\":null}",
+   "expect": {
+    "prompt_graph": "parsed",
+    "workflow_graph": "malformed"
+   }
+  },
+  {
+   "name": "carrier_non_string_text_malformed",
+   "records": {
+    "prompt": "{\"1\":{\"class_type\":\"A\",\"inputs\":{\"x\":1}}}"
+   },
+   "carrier_text": "",
+   "expect": {
+    "prompt_graph": "malformed",
+    "workflow_graph": "absent"
+   }
+  }
+ ]
+}

tests/fixtures/local-inspect/video-tags-v1.json

@@ -0,0 +1,60 @@
+{
+  "generator": "ffmpeg -show_entries format_tags -of json over tests/fixtures/local-inspect, see tests/fixtures/README.md",
+  "fixtures": {
+    "core-faststart.mp4": {
+      "major_brand": "isom",
+      "minor_version": "512",
+      "compatible_brands": "isomiso2avc1mp41",
+      "prompt": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"seed\":7,\"steps\":20,\"cfg\":8.0,\"sampler_name\":\"euler\",\"scheduler\":\"normal\",\"denoise\":1.0,\"model\":[\"4\",0],\"positive\":[\"6\",0],\"negative\":[\"7\",0],\"latent_image\":[\"5\",0]}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"synthetic-v1.safetensors\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"width\":512,\"height\":512,\"batch_size\":1}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"a red fox in snow, detailed fur\",\"clip\":[\"4\",1]}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"blurry, lowres\",\"clip\":[\"4\",1]}},\"8\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"samples\":[\"3\",0],\"vae\":[\"4\",2]}},\"9\":{\"class_type\":\"SaveVideo\",\"inputs\":{\"filename_prefix\":\"video/synthetic\",\"video\":[\"8\",0]}}}",
+      "workflow": "{\"last_node_id\":9,\"nodes\":[{\"id\":3,\"type\":\"KSampler\",\"widgets_values\":[7,\"fixed\",20,8.0,\"euler\",\"normal\",1.0]},{\"id\":6,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"a red fox in snow, detailed fur\"]},{\"id\":7,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"blurry, lowres\"]}],\"links\":[],\"version\":0.4}",
+      "parameters": "a red fox in snow, detailed fur\nNegative prompt: blurry, lowres\nSteps: 20, Sampler: Euler, CFG scale: 8.0, Seed: 7, Size: 512x512",
+      "comfyassets_prompt_pairs": "{\"version\":1,\"nodes\":{\"6\":{\"records\":[{\"positive_text\":\"a red fox in snow, detailed fur\",\"negative_text\":\"blurry, lowres\",\"negative_effective_text\":\"blurry, lowres\",\"prepend_text\":\"\",\"append_text\":\"\"}]}}}",
+      "encoder": "Lavf63.1.102"
+    },
+    "core-moov-end.mp4": {
+      "major_brand": "isom",
+      "minor_version": "512",
+      "compatible_brands": "isomiso2avc1mp41",
+      "prompt": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"seed\":7,\"steps\":20,\"cfg\":8.0,\"sampler_name\":\"euler\",\"scheduler\":\"normal\",\"denoise\":1.0,\"model\":[\"4\",0],\"positive\":[\"6\",0],\"negative\":[\"7\",0],\"latent_image\":[\"5\",0]}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"synthetic-v1.safetensors\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"width\":512,\"height\":512,\"batch_size\":1}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"a red fox in snow, detailed fur\",\"clip\":[\"4\",1]}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"blurry, lowres\",\"clip\":[\"4\",1]}},\"8\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"samples\":[\"3\",0],\"vae\":[\"4\",2]}},\"9\":{\"class_type\":\"SaveVideo\",\"inputs\":{\"filename_prefix\":\"video/synthetic\",\"video\":[\"8\",0]}}}",
+      "workflow": "{\"last_node_id\":9,\"nodes\":[{\"id\":3,\"type\":\"KSampler\",\"widgets_values\":[7,\"fixed\",20,8.0,\"euler\",\"normal\",1.0]},{\"id\":6,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"a red fox in snow, detailed fur\"]},{\"id\":7,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"blurry, lowres\"]}],\"links\":[],\"version\":0.4}",
+      "encoder": "Lavf63.1.102"
+    },
+    "core.mov": {
+      "major_brand": "qt  ",
+      "minor_version": "512",
+      "compatible_brands": "qt  ",
+      "prompt": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"seed\":7,\"steps\":20,\"cfg\":8.0,\"sampler_name\":\"euler\",\"scheduler\":\"normal\",\"denoise\":1.0,\"model\":[\"4\",0],\"positive\":[\"6\",0],\"negative\":[\"7\",0],\"latent_image\":[\"5\",0]}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"synthetic-v1.safetensors\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"width\":512,\"height\":512,\"batch_size\":1}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"a red fox in snow, detailed fur\",\"clip\":[\"4\",1]}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"blurry, lowres\",\"clip\":[\"4\",1]}},\"8\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"samples\":[\"3\",0],\"vae\":[\"4\",2]}},\"9\":{\"class_type\":\"SaveVideo\",\"inputs\":{\"filename_prefix\":\"video/synthetic\",\"video\":[\"8\",0]}}}",
+      "workflow": "{\"last_node_id\":9,\"nodes\":[{\"id\":3,\"type\":\"KSampler\",\"widgets_values\":[7,\"fixed\",20,8.0,\"euler\",\"normal\",1.0]},{\"id\":6,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"a red fox in snow, detailed fur\"]},{\"id\":7,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"blurry, lowres\"]}],\"links\":[],\"version\":0.4}",
+      "encoder": "Lavf63.1.102"
+    },
+    "core.m4v": {
+      "major_brand": "M4V ",
+      "minor_version": "512",
+      "compatible_brands": "M4V isomiso2avc1",
+      "prompt": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"seed\":7,\"steps\":20,\"cfg\":8.0,\"sampler_name\":\"euler\",\"scheduler\":\"normal\",\"denoise\":1.0,\"model\":[\"4\",0],\"positive\":[\"6\",0],\"negative\":[\"7\",0],\"latent_image\":[\"5\",0]}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"synthetic-v1.safetensors\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"width\":512,\"height\":512,\"batch_size\":1}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"a red fox in snow, detailed fur\",\"clip\":[\"4\",1]}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"blurry, lowres\",\"clip\":[\"4\",1]}},\"8\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"samples\":[\"3\",0],\"vae\":[\"4\",2]}},\"9\":{\"class_type\":\"SaveVideo\",\"inputs\":{\"filename_prefix\":\"video/synthetic\",\"video\":[\"8\",0]}}}",
+      "workflow": "{\"last_node_id\":9,\"nodes\":[{\"id\":3,\"type\":\"KSampler\",\"widgets_values\":[7,\"fixed\",20,8.0,\"euler\",\"normal\",1.0]},{\"id\":6,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"a red fox in snow, detailed fur\"]},{\"id\":7,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"blurry, lowres\"]}],\"links\":[],\"version\":0.4}",
+      "encoder": "Lavf63.1.102"
+    },
+    "core.mkv": {
+      "WORKFLOW": "{\"last_node_id\":9,\"nodes\":[{\"id\":3,\"type\":\"KSampler\",\"widgets_values\":[7,\"fixed\",20,8.0,\"euler\",\"normal\",1.0]},{\"id\":6,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"a red fox in snow, detailed fur\"]},{\"id\":7,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"blurry, lowres\"]}],\"links\":[],\"version\":0.4}",
+      "PROMPT": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"seed\":7,\"steps\":20,\"cfg\":8.0,\"sampler_name\":\"euler\",\"scheduler\":\"normal\",\"denoise\":1.0,\"model\":[\"4\",0],\"positive\":[\"6\",0],\"negative\":[\"7\",0],\"latent_image\":[\"5\",0]}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"synthetic-v1.safetensors\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"width\":512,\"height\":512,\"batch_size\":1}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"a red fox in snow, detailed fur\",\"clip\":[\"4\",1]}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"blurry, lowres\",\"clip\":[\"4\",1]}},\"8\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"samples\":[\"3\",0],\"vae\":[\"4\",2]}},\"9\":{\"class_type\":\"SaveVideo\",\"inputs\":{\"filename_prefix\":\"video/synthetic\",\"video\":[\"8\",0]}}}",
+      "ENCODER": "Lavf63.1.102"
+    },
+    "core-tags.webm": {
+      "WORKFLOW": "{\"last_node_id\":9,\"nodes\":[{\"id\":3,\"type\":\"KSampler\",\"widgets_values\":[7,\"fixed\",20,8.0,\"euler\",\"normal\",1.0]},{\"id\":6,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"a red fox in snow, detailed fur\"]},{\"id\":7,\"type\":\"CLIPTextEncode\",\"widgets_values\":[\"blurry, lowres\"]}],\"links\":[],\"version\":0.4}",
+      "PROMPT": "{\"3\":{\"class_type\":\"KSampler\",\"inputs\":{\"seed\":7,\"steps\":20,\"cfg\":8.0,\"sampler_name\":\"euler\",\"scheduler\":\"normal\",\"denoise\":1.0,\"model\":[\"4\",0],\"positive\":[\"6\",0],\"negative\":[\"7\",0],\"latent_image\":[\"5\",0]}},\"4\":{\"class_type\":\"CheckpointLoaderSimple\",\"inputs\":{\"ckpt_name\":\"synthetic-v1.safetensors\"}},\"5\":{\"class_type\":\"EmptyLatentImage\",\"inputs\":{\"width\":512,\"height\":512,\"batch_size\":1}},\"6\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"a red fox in snow, detailed fur\",\"clip\":[\"4\",1]}},\"7\":{\"class_type\":\"CLIPTextEncode\",\"inputs\":{\"text\":\"blurry, lowres\",\"clip\":[\"4\",1]}},\"8\":{\"class_type\":\"VAEDecode\",\"inputs\":{\"samples\":[\"3\",0],\"vae\":[\"4\",2]}},\"9\":{\"class_type\":\"SaveVideo\",\"inputs\":{\"filename_prefix\":\"video/synthetic\",\"video\":[\"8\",0]}}}",
+      "ENCODER": "Lavf63.1.102"
+    },
+    "legacy-comment.mp4": {
+      "major_brand": "isom",
+      "minor_version": "512",
+      "compatible_brands": "isomiso2avc1mp41",
+      "encoder": "Lavf63.1.102",
+      "comment": "{\"prompt\": \"{\\\"3\\\":{\\\"class_type\\\":\\\"KSampler\\\",\\\"inputs\\\":{\\\"seed\\\":7,\\\"steps\\\":20,\\\"cfg\\\":8.0,\\\"sampler_name\\\":\\\"euler\\\",\\\"scheduler\\\":\\\"normal\\\",\\\"denoise\\\":1.0,\\\"model\\\":[\\\"4\\\",0],\\\"positive\\\":[\\\"6\\\",0],\\\"negative\\\":[\\\"7\\\",0],\\\"latent_image\\\":[\\\"5\\\",0]}},\\\"4\\\":{\\\"class_type\\\":\\\"CheckpointLoaderSimple\\\",\\\"inputs\\\":{\\\"ckpt_name\\\":\\\"synthetic-v1.safetensors\\\"}},\\\"5\\\":{\\\"class_type\\\":\\\"EmptyLatentImage\\\",\\\"inputs\\\":{\\\"width\\\":512,\\\"height\\\":512,\\\"batch_size\\\":1}},\\\"6\\\":{\\\"class_type\\\":\\\"CLIPTextEncode\\\",\\\"inputs\\\":{\\\"text\\\":\\\"a red fox in snow, detailed fur\\\",\\\"clip\\\":[\\\"4\\\",1]}},\\\"7\\\":{\\\"class_type\\\":\\\"CLIPTextEncode\\\",\\\"inputs\\\":{\\\"text\\\":\\\"blurry, lowres\\\",\\\"clip\\\":[\\\"4\\\",1]}},\\\"8\\\":{\\\"class_type\\\":\\\"VAEDecode\\\",\\\"inputs\\\":{\\\"samples\\\":[\\\"3\\\",0],\\\"vae\\\":[\\\"4\\\",2]}},\\\"9\\\":{\\\"class_type\\\":\\\"SaveVideo\\\",\\\"inputs\\\":{\\\"filename_prefix\\\":\\\"video/synthetic\\\",\\\"video\\\":[\\\"8\\\",0]}}}\", \"workflow\": {\"last_node_id\": 9, \"nodes\": [{\"id\": 3, \"type\": \"KSampler\", \"widgets_values\": [7, \"fixed\", 20, 8.0, \"euler\", \"normal\", 1.0]}, {\"id\": 6, \"type\": \"CLIPTextEncode\", \"widgets_values\": [\"a red fox in snow, detailed fur\"]}, {\"id\": 7, \"type\": \"CLIPTextEncode\", \"widgets_values\": [\"blurry, lowres\"]}], \"links\": [], \"version\": 0.4}}"
+    },
+    "legacy-comment.webm": {
+      "COMMENT": "{\"prompt\": \"{\\\"3\\\":{\\\"class_type\\\":\\\"KSampler\\\",\\\"inputs\\\":{\\\"seed\\\":7,\\\"steps\\\":20,\\\"cfg\\\":8.0,\\\"sampler_name\\\":\\\"euler\\\",\\\"scheduler\\\":\\\"normal\\\",\\\"denoise\\\":1.0,\\\"model\\\":[\\\"4\\\",0],\\\"positive\\\":[\\\"6\\\",0],\\\"negative\\\":[\\\"7\\\",0],\\\"latent_image\\\":[\\\"5\\\",0]}},\\\"4\\\":{\\\"class_type\\\":\\\"CheckpointLoaderSimple\\\",\\\"inputs\\\":{\\\"ckpt_name\\\":\\\"synthetic-v1.safetensors\\\"}},\\\"5\\\":{\\\"class_type\\\":\\\"EmptyLatentImage\\\",\\\"inputs\\\":{\\\"width\\\":512,\\\"height\\\":512,\\\"batch_size\\\":1}},\\\"6\\\":{\\\"class_type\\\":\\\"CLIPTextEncode\\\",\\\"inputs\\\":{\\\"text\\\":\\\"a red fox in snow, detailed fur\\\",\\\"clip\\\":[\\\"4\\\",1]}},\\\"7\\\":{\\\"class_type\\\":\\\"CLIPTextEncode\\\",\\\"inputs\\\":{\\\"text\\\":\\\"blurry, lowres\\\",\\\"clip\\\":[\\\"4\\\",1]}},\\\"8\\\":{\\\"class_type\\\":\\\"VAEDecode\\\",\\\"inputs\\\":{\\\"samples\\\":[\\\"3\\\",0],\\\"vae\\\":[\\\"4\\\",2]}},\\\"9\\\":{\\\"class_type\\\":\\\"SaveVideo\\\",\\\"inputs\\\":{\\\"filename_prefix\\\":\\\"video/synthetic\\\",\\\"video\\\":[\\\"8\\\",0]}}}\", \"workflow\": {\"last_node_id\": 9, \"nodes\": [{\"id\": 3, \"type\": \"KSampler\", \"widgets_values\": [7, \"fixed\", 20, 8.0, \"euler\", \"normal\", 1.0]}, {\"id\": 6, \"type\": \"CLIPTextEncode\", \"widgets_values\": [\"a red fox in snow, detailed fur\"]}, {\"id\": 7, \"type\": \"CLIPTextEncode\", \"widgets_values\": [\"blurry, lowres\"]}], \"links\": [], \"version\": 0.4}}",
+      "ENCODER": "Lavf63.1.102"
+    }
+  }
+}

tests/host_stubs.py

@@ -0,0 +1,29 @@
+"""One stand-in for ComfyUI's ``folder_paths`` module, shared by every test.
+
+Test modules that import the API standalone need a ``folder_paths`` module.
+It must be a real module, not a ``MagicMock``: ``patch("folder_paths.x",
+create=True)`` then adds and removes plain attributes, while a mock would
+hand a later test an auto-created child (or lose the attribute on exit), so
+the outcome depended on which test module discovery imported first.
+"""
+
+import sys
+import tempfile
+import types
+
+
+def install_folder_paths_stub() -> types.ModuleType:
+    """Install the shared ``folder_paths`` stub unless a real module is there.
+
+    A test that installs its own stand-in for a while (and restores it) is
+    left alone; a ``MagicMock`` left behind by older code is replaced.
+    """
+    current = sys.modules.get("folder_paths")
+    if isinstance(current, types.ModuleType):
+        return current
+    stub = types.ModuleType("folder_paths")
+    stub.models_dir = tempfile.gettempdir()
+    stub.base_path = tempfile.gettempdir()
+    stub.get_output_directory = tempfile.gettempdir
+    sys.modules["folder_paths"] = stub
+    return stub

tests/js/api-client.test.js

@@ -296,3 +296,33 @@ test("get forwards an explicit cache mode and keeps the default request otherwis
     fetch.calls[2].resolve(jsonResponse(200, { success: true }));
     await writes;
 });
+
+test("ApiError exposes only a validated current tag set from a tag-conflict body", async () => {
+    const permitted = [{ tags: [], tag_revision: 0 }, { tags: ["warm", "Dune"], tag_revision: 7 }];
+    const denied = [undefined, null, { tags: ["a"] }, { tag_revision: 1 }, { tags: "a", tag_revision: 1 },
+        { tags: [1], tag_revision: 1 }, { tags: ["a"], tag_revision: -1 }, { tags: ["a"], tag_revision: 1.5 },
+        { tags: ["a"], tag_revision: true }, { tags: Array(101).fill("a"), tag_revision: 1 }];
+    assert.equal(new ApiError(409, "old caller").current, null);
+    for (const current of permitted.concat(denied)) {
+        const api = createApiClient(async () => jsonResponse(409, {
+            success: false, error: "changed", code: "tag-conflict", ...(current || {}),
+        }));
+        await assert.rejects(api.put("/x", {}), error => {
+            assert.ok(error instanceof ApiError);
+            assert.deepEqual(error.current, permitted.includes(current) ? current : null);
+            if (permitted.includes(current)) assert.notEqual(error.current.tags, current.tags, "server arrays must be copied");
+            return true;
+        });
+    }
+});
+
+test("keepalive is forwarded only when asked, so a request can outlive its page", async () => {
+    const fetch = fakeFetch();
+    const api = createApiClient(fetch);
+    const writes = [api.del("/x", { keepalive: true }), api.put("/x", {}, { keepalive: true }), api.post("/x", {}, { keepalive: true }),
+        api.del("/x"), api.put("/x", {}), api.get("/x")];
+    assert.deepEqual(fetch.calls.map(call => call.init.keepalive), [true, true, true, undefined, undefined, undefined]);
+    assert.equal("keepalive" in fetch.calls[3].init, false);
+    for (const call of fetch.calls) call.resolve(jsonResponse(200, { success: true }));
+    await Promise.all(writes);
+});

tests/js/helpers/mounted-dom.mjs

@@ -0,0 +1,40 @@
+// A minimal DOM for mounting the workspace viewer and inspector in Node: elements with
+// children, attributes, listeners (fire() dispatches), dialogs and media methods.
+export function mountedDom() {
+    class Node {
+        constructor(tag) {this.tagName=tag;this.children=[];this.dataset={};this.attributes={};this.listeners=new Map();this._text='';this.classList={add(){},remove(){}};}
+        get textContent(){return this._text+this.children.map(c=>c.textContent).join('');}
+        set textContent(value){this._text=String(value);this.children=[];}
+        get childNodes(){return this.children;}
+        get isConnected(){return this.root || !!this.parent?.isConnected;}
+        // As in the DOM, a string argument becomes a text node.
+        static wrap(node){if(typeof node!=='string')return node;const text=new Node('#text');text.textContent=node;return text;}
+        append(...nodes){for(const node of nodes.map(Node.wrap)){node.parent=this;this.children.push(node);}}
+        prepend(...nodes){nodes=nodes.map(Node.wrap);for(const node of nodes)node.parent=this;this.children.unshift(...nodes);}
+        replaceChildren(...nodes){for(const child of this.children)child.parent=null;this.children=[];this._text='';this.append(...nodes);}
+        remove(){if(this.parent)this.parent.children=this.parent.children.filter(c=>c!==this);this.parent=null;}
+        setAttribute(key,value){this.attributes[key]=String(value);}
+        getAttribute(key){return this.attributes[key]??null;}
+        removeAttribute(key){delete this.attributes[key];}
+        addEventListener(type,callback,options={}){const list=this.listeners.get(type)||[];list.push({callback,signal:options.signal});this.listeners.set(type,list);}
+        removeEventListener(type,callback){this.listeners.set(type,(this.listeners.get(type)||[]).filter(e=>e.callback!==callback));}
+        fire(type,event={}){for(const e of [...(this.listeners.get(type)||[])])if(!e.signal?.aborted)e.callback({target:this,preventDefault(){},...event});}
+        focus(){this.focused=true;}
+        showModal(){this.open=true;}
+        close(){this.open=false;this.fire('close');}
+        contains(node){return node===this||this.children.some(c=>c.contains(node));}
+        closest(selector){if(selector==='section'&&this.tagName==='section')return this;if(selector==='[data-send-role]'&&this.dataset.sendRole)return this;if(selector==='[data-copy-role]'&&this.dataset.copyRole)return this;return this.parent?.closest(selector)||null;}
+        querySelector(selector){return walk(this,n=>n.tagName===selector)[0]||null;}
+        pause(){this.paused=true;}
+        load(){this.loaded=true;}
+        play(){this.played=true;return Promise.resolve();}
+    }
+    const walk=(node,predicate)=>[...(predicate(node)?[node]:[]),...node.children.flatMap(child=>walk(child,predicate))];
+    const oldDocument=globalThis.document,oldWindow=globalThis.window;
+    const container=new Node('main');container.root=true;
+    const doc=new Node('document');doc.createElement=tag=>new Node(tag);doc.createElementNS=(_,tag)=>new Node(tag);
+    doc.querySelectorAll=()=>walk(container,n=>n.tagName==='dialog'&&n.open);doc.activeElement=new Node('button');doc.activeElement.root=true;
+    const win=new Node('window');win.location={href:'http://localhost/prompt_manager/workspace'};win.getSelection=()=>({isCollapsed:true});
+    globalThis.document=doc;globalThis.window=win;
+    return {container,doc,win,walk,Node,restore(){globalThis.document=oldDocument;globalThis.window=oldWindow;}};
+}

tests/js/helpers/png-bytes.mjs

@@ -0,0 +1,148 @@
+// Byte-exact PNG builders for the local reader tests (real CRC32 and zlib), and
+// File-like blobs: one that records every [start, end) slice over a sparse layout
+// that is never allocated, one that answers slowly, one that fails or shrinks.
+import zlib from "node:zlib";
+
+export const SIGNATURE = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+export function u32(n) {
+    return Uint8Array.from([(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff]);
+}
+
+export function latin1(text) {
+    return Buffer.from(text, "latin1");
+}
+
+export function utf8(text) {
+    return Buffer.from(text, "utf8");
+}
+
+export function concat(...parts) {
+    return Uint8Array.from(Buffer.concat(parts.map((part) => Buffer.from(part))));
+}
+
+/**
+ * One chunk with a real CRC32 over type + data. `crc` overrides the checksum and
+ * `declaredLength` the length field (to declare more data than is present).
+ */
+export function chunk(type, data, { crc, declaredLength } = {}) {
+    const typeBytes = latin1(type);
+    const body = Buffer.from(data);
+    const sum = crc ?? zlib.crc32(Buffer.concat([typeBytes, body]));
+    return concat(u32(declaredLength ?? body.length), typeBytes, body, u32(sum));
+}
+
+export function ihdr(width = 1, height = 1, options) {
+    return chunk("IHDR", concat(u32(width), u32(height), [8, 6, 0, 0, 0]), options);
+}
+
+export function idat(data = [0]) {
+    return chunk("IDAT", data);
+}
+
+export function iend(options) {
+    return chunk("IEND", [], options);
+}
+
+/** tEXt: keyword NUL text, Latin-1 (text may be a string or raw bytes). */
+export function tEXt(keyword, text, options) {
+    const body = typeof text === "string" ? latin1(text) : Buffer.from(text);
+    return chunk("tEXt", concat(latin1(keyword), [0], body), options);
+}
+
+/** zTXt: keyword NUL method zlib(text). `compressed` replaces the deflated body. */
+export function zTXt(keyword, text, { method = 0, compressed, level = 6 } = {}) {
+    const body = compressed ?? zlib.deflateSync(typeof text === "string" ? latin1(text) : Buffer.from(text), { level });
+    return chunk("zTXt", concat(latin1(keyword), [0, method], body));
+}
+
+/** iTXt: keyword NUL flag method lang NUL translated NUL text (UTF-8, deflated when flag). */
+export function iTXt(keyword, text, { flag = 0, method = 0, lang = "", translated = "", compressed } = {}) {
+    const raw = typeof text === "string" ? utf8(text) : Buffer.from(text);
+    const body = compressed ?? (flag ? zlib.deflateSync(raw) : raw);
+    const langBytes = typeof lang === "string" ? latin1(lang) : Buffer.from(lang);
+    const translatedBytes = typeof translated === "string" ? utf8(translated) : Buffer.from(translated);
+    return concat(chunk("iTXt", concat(latin1(keyword), [0, flag, method], langBytes, [0], translatedBytes, [0], body)));
+}
+
+/** A whole PNG: signature, IHDR, IDAT, the given chunks, IEND. */
+export function png(...chunks) {
+    return concat(SIGNATURE, ihdr(), idat(), ...chunks, iend());
+}
+
+/** Signature plus exactly the given chunks (no implied IHDR/IDAT/IEND). */
+export function raw(...chunks) {
+    return concat(SIGNATURE, ...chunks);
+}
+
+export function blobOf(bytes) {
+    return new Blob([bytes]);
+}
+
+/**
+ * A File-like object over a sparse layout: `parts` are [{offset, bytes}] placed in a
+ * file of `size` bytes, zero everywhere else; nothing of `size` is allocated. Every
+ * slice is recorded in `ranges` as [start, end).
+ */
+export function sparseBlob(parts, size) {
+    const ranges = [];
+    function bytesOf(start, end) {
+        const out = new Uint8Array(end - start);
+        for (const part of parts) {
+            const from = Math.max(start, part.offset);
+            const to = Math.min(end, part.offset + part.bytes.length);
+            if (from < to) out.set(part.bytes.subarray(from - part.offset, to - part.offset), from - start);
+        }
+        return out;
+    }
+    return {
+        size,
+        ranges,
+        slice(start, end) {
+            ranges.push([start, end]);
+            return { arrayBuffer: async () => bytesOf(start, end).buffer };
+        },
+    };
+}
+
+/** A recording blob over real bytes. */
+export function recordingBlob(bytes) {
+    return sparseBlob([{ offset: 0, bytes }], bytes.length);
+}
+
+/** Every slice resolves after `delayMs`. */
+export function slowBlob(bytes, delayMs) {
+    return {
+        size: bytes.length,
+        slice(start, end) {
+            return {
+                arrayBuffer: () => new Promise((resolve) => setTimeout(() => resolve(bytes.slice(start, end).buffer), delayMs)),
+            };
+        },
+    };
+}
+
+/** Slices fail (as a browser does when the file vanished). */
+export function failingBlob(size) {
+    return {
+        size,
+        slice() {
+            return { arrayBuffer: () => Promise.reject(new Error("NotReadableError")) };
+        },
+    };
+}
+
+/** Reports `size` but every slice beyond `actual` bytes comes back short. */
+export function shrunkBlob(bytes, size) {
+    return {
+        size,
+        slice(start, end) {
+            return { arrayBuffer: async () => bytes.slice(start, Math.min(end, bytes.length)).buffer };
+        },
+    };
+}
+
+/** An A1111 `parameters` record with one settings footer carrying a batch index. */
+export function parametersText(positive, batchIndex, { seedField = "Seed: 1" } = {}) {
+    return `${positive}\nNegative prompt: blurry\nSteps: 20, Sampler: Euler, Batch index: ${batchIndex}, ${seedField}`;
+}

tests/js/helpers/video-bytes.mjs

@@ -0,0 +1,277 @@
+// Byte-exact ISO-BMFF (MP4/MOV/M4V) and Matroska (MKV/WebM) builders for the local
+// video tag reader tests, laid out as ffmpeg's muxers write them (see the dumps in
+// tests/fixtures/local-inspect). The File-like blobs come from png-bytes.mjs.
+import { concat, u32, utf8, latin1 } from "./png-bytes.mjs";
+
+export { concat, u32, utf8, latin1 };
+export { sparseBlob, recordingBlob, slowBlob, failingBlob, blobOf } from "./png-bytes.mjs";
+
+const toBytes = (part) => (typeof part === "string" ? utf8(part) : Buffer.from(part));
+
+function u64(n) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, BigInt(n));
+    return out;
+}
+
+// ---------------------------------------------------------------- ISO-BMFF
+
+/** A box: 32-bit size, 4-byte type (string or raw bytes), payload. `size` overrides the field. */
+export function box(type, ...parts) {
+    const options = parts.length && parts[parts.length - 1] && parts[parts.length - 1].__options ? parts.pop() : {};
+    const payload = concat(...parts.map(toBytes));
+    const typeBytes = typeof type === "string" ? latin1(type) : Buffer.from(type);
+    const total = 8 + payload.length;
+    if (options.largesize) return concat(u32(1), typeBytes, u64(options.largesize === true ? total + 8 : options.largesize), payload);
+    return concat(u32(options.size ?? total), typeBytes, payload);
+}
+
+/** Marker for `box` options: box('ftyp', ..., opts({size: 3})). */
+export function opts(options) {
+    return { __options: true, ...options };
+}
+
+export function fullBox(type, ...parts) {
+    return box(type, u32(0), ...parts);
+}
+
+export function ftyp(brand = "isom", compatible = "isomiso2avc1mp41") {
+    return box("ftyp", latin1(brand), u32(512), latin1(compatible));
+}
+
+export function mdat(payload = [0, 0, 0, 0]) {
+    return box("mdat", payload);
+}
+
+export const moov = (...children) => box("moov", ...children);
+export const udta = (...children) => box("udta", ...children);
+export const free = (count = 0) => box("free", new Uint8Array(count));
+
+/** `meta` as ffmpeg writes it: a FullBox (version/flags) whose first child is hdlr. */
+export function meta(...children) {
+    return fullBox("meta", ...children);
+}
+
+export function hdlr(handler = "mdta") {
+    return fullBox("hdlr", u32(0), latin1(handler), new Uint8Array(12), [0]);
+}
+
+/** `keys`: one mdta entry per name (an entry may be [name, namespace]); `count` overrides the count field. */
+export function keys(names, { count } = {}) {
+    const entries = names.map((entry) => {
+        const [name, namespace] = Array.isArray(entry) ? entry : [entry, "mdta"];
+        const bytes = toBytes(name);
+        return concat(u32(8 + bytes.length), latin1(namespace), bytes);
+    });
+    return fullBox("keys", u32(count ?? names.length), ...entries);
+}
+
+export const ilst = (...items) => box("ilst", ...items);
+
+/** A `data` atom: type indicator (1 = UTF-8), locale, payload. */
+export function data(payload, { type = 1, locale = 0, size } = {}) {
+    return box("data", u32(type), u32(locale), toBytes(payload), ...(size === undefined ? [] : [opts({ size })]));
+}
+
+/** An ilst item addressed by its 1-based `keys` index. */
+export function item(index, ...children) {
+    return box(u32(index), ...children);
+}
+
+/** An ilst item addressed by a legacy fourcc such as "©cmt" (Latin-1 bytes). */
+export function legacyItem(fourcc, ...children) {
+    return box(latin1(fourcc), ...children);
+}
+
+/** `moov/udta/meta` carrying per-key mdta tags, as core SaveVideo writes through ffmpeg. */
+export function mdtaUdta(tags) {
+    const names = Object.keys(tags);
+    return udta(meta(hdlr("mdta"), keys(names), ilst(...names.map((name, index) => item(index + 1, data(tags[name]))))));
+}
+
+/** `moov/udta/meta` with legacy ilst atoms: {comment, description} → ©cmt / desc. */
+export function legacyUdta({ comment, description, tool = "Lavf" } = {}) {
+    const items = [legacyItem("©too", data(tool))];
+    if (comment !== undefined) items.push(legacyItem("©cmt", data(comment)));
+    if (description !== undefined) items.push(legacyItem("desc", data(description)));
+    return udta(meta(hdlr("mdir"), ilst(...items)));
+}
+
+/** A whole MP4: ftyp, (moov first when faststart), mdat, moov with the given udta. */
+export function mp4(udtaBox, { brand = "isom", faststart = false, extraMoov = [], payload } = {}) {
+    const movie = moov(...extraMoov, udtaBox);
+    const media = mdat(payload);
+    return faststart ? concat(ftyp(brand), movie, media) : concat(ftyp(brand), free(), media, movie);
+}
+
+export function perKeyMp4(tags, options) {
+    return mp4(mdtaUdta(tags), options);
+}
+
+/** Top-level boxes of `bytes` as [{type, start, end}]. */
+export function topLevelBoxes(bytes) {
+    const out = [];
+    let offset = 0;
+    while (offset + 8 <= bytes.length) {
+        const view = new DataView(bytes.buffer, bytes.byteOffset + offset);
+        let size = view.getUint32(0);
+        if (size === 1) size = Number(view.getBigUint64(8));
+        if (size === 0) size = bytes.length - offset;
+        out.push({ type: latin1Of(bytes.subarray(offset + 4, offset + 8)), start: offset, end: offset + size });
+        offset += size;
+    }
+    return out;
+}
+
+function latin1Of(bytes) {
+    return Buffer.from(bytes).toString("latin1");
+}
+
+// ---------------------------------------------------------------- Matroska
+
+export const ID = {
+    EBML: 0x1a45dfa3,
+    EBMLVersion: 0x4286,
+    DocType: 0x4282,
+    DocTypeVersion: 0x4287,
+    Segment: 0x18538067,
+    SeekHead: 0x114d9b74,
+    Seek: 0x4dbb,
+    SeekID: 0x53ab,
+    SeekPosition: 0x53ac,
+    Void: 0xec,
+    CRC32: 0xbf,
+    Info: 0x1549a966,
+    Tracks: 0x1654ae6b,
+    Tags: 0x1254c367,
+    Tag: 0x7373,
+    Targets: 0x63c0,
+    TargetTypeValue: 0x68ca,
+    TagTrackUID: 0x63c5,
+    SimpleTag: 0x67c8,
+    TagName: 0x45a3,
+    TagString: 0x4487,
+    TagLanguage: 0x447a,
+    TagDefault: 0x4484,
+    TagBinary: 0x4485,
+    Cluster: 0x1f43b675,
+    Timestamp: 0xe7,
+    Cues: 0x1c53bb6b,
+};
+
+/** The ID's bytes (EBML IDs carry their own length marker). */
+export function idBytes(id) {
+    const out = [];
+    let value = id;
+    while (value > 0) {
+        out.unshift(value & 0xff);
+        value = Math.floor(value / 256);
+    }
+    return Uint8Array.from(out);
+}
+
+/** A size VINT: minimal width unless `width` is given; `unknown` writes all ones. */
+export function vint(value, { width, unknown = false } = {}) {
+    let length = width;
+    if (!length) {
+        length = 1;
+        while (length < 8 && value >= 2 ** (7 * length) - 1) length += 1;
+    }
+    const out = new Uint8Array(length);
+    if (unknown) {
+        out.fill(0xff);
+        out[0] = 0xff >> (length - 1);
+        return out;
+    }
+    let rest = BigInt(value);
+    for (let index = length - 1; index >= 0; index -= 1) {
+        out[index] = Number(rest & 0xffn);
+        rest >>= 8n;
+    }
+    out[0] |= 0x80 >> (length - 1);
+    return out;
+}
+
+/** An element: ID, size VINT, payload. `size`/`width`/`unknown` shape the size field. */
+export function el(id, ...parts) {
+    const options = parts.length && parts[parts.length - 1] && parts[parts.length - 1].__options ? parts.pop() : {};
+    const payload = concat(...parts.map(toBytes));
+    const size = vint(options.size ?? payload.length, { width: options.width, unknown: options.unknown });
+    return concat(idBytes(id), size, payload);
+}
+
+export function uint(value, width) {
+    const out = [];
+    let rest = BigInt(value);
+    do {
+        out.unshift(Number(rest & 0xffn));
+        rest >>= 8n;
+    } while (rest > 0n);
+    while (width && out.length < width) out.unshift(0);
+    return Uint8Array.from(out);
+}
+
+export function ebmlHeader(docType = "matroska") {
+    return el(ID.EBML, el(ID.EBMLVersion, [1]), el(ID.DocType, docType), el(ID.DocTypeVersion, [4]));
+}
+
+/** Segment with an 8-byte size field as ffmpeg writes it; `unknown` makes it unknown-sized. */
+export function segment(children, { unknown = false } = {}) {
+    return el(ID.Segment, ...children, opts({ width: 8, unknown }));
+}
+
+/** SeekHead entries: [[id, position]] with positions relative to the Segment payload. */
+export function seekHead(entries) {
+    return el(ID.SeekHead, ...entries.map(([id, position]) => el(ID.Seek, el(ID.SeekID, idBytes(id)), el(ID.SeekPosition, uint(position)))));
+}
+
+export function voidEl(count = 4) {
+    return el(ID.Void, new Uint8Array(count));
+}
+
+/** A SimpleTag with TagName and TagString (`value` undefined omits the string). */
+export function simpleTag(name, value, { lang, def, binary, nested = [], extra = [] } = {}) {
+    const children = [el(ID.TagName, name)];
+    if (lang !== undefined) children.push(el(ID.TagLanguage, lang));
+    if (def !== undefined) children.push(el(ID.TagDefault, [def]));
+    if (value !== undefined) children.push(el(ID.TagString, value));
+    if (binary !== undefined) children.push(el(ID.TagBinary, binary));
+    return el(ID.SimpleTag, ...children, ...nested, ...extra);
+}
+
+/** A Tag whose Targets carry the given track UID (none → global). */
+export function tag(simpleTags, { trackUid, targetType } = {}) {
+    const targets = [];
+    if (targetType !== undefined) targets.push(el(ID.TargetTypeValue, uint(targetType)));
+    if (trackUid !== undefined) targets.push(el(ID.TagTrackUID, uint(trackUid, 8)));
+    return el(ID.Tag, el(ID.Targets, ...targets), ...simpleTags);
+}
+
+export function tagsEl(...tagElements) {
+    return el(ID.Tags, ...tagElements);
+}
+
+/** A Cluster of `size` payload bytes (zeros); `unknown` makes its size unknown. */
+export function cluster(size = 8, { unknown = false, payload } = {}) {
+    return el(ID.Cluster, payload ?? new Uint8Array(size), opts({ unknown }));
+}
+
+/** A Cluster header only, declaring `size` payload bytes (for sparse layouts). */
+export function clusterHeader(size) {
+    return concat(idBytes(ID.Cluster), vint(size, { width: 8 }));
+}
+
+/** A whole Matroska file: EBML header + Segment(children). */
+export function mkv(children, { docType = "matroska", unknown = false } = {}) {
+    return concat(ebmlHeader(docType), segment(children, { unknown }));
+}
+
+/** A global Tags element from {name: value} (ffmpeg upper-cases names at mux time). */
+export function globalTags(tags, options) {
+    return tagsEl(tag(Object.entries(tags).map(([name, value]) => simpleTag(name, value)), options));
+}
+
+/** A Matroska file whose global Tags hold {name: value}, ffmpeg layout. */
+export function perKeyMkv(tags, { docType = "matroska" } = {}) {
+    return mkv([el(ID.Info, new Uint8Array(4)), globalTags(tags), cluster()], { docType });
+}

tests/js/png-local-reader.test.js

@@ -0,0 +1,549 @@
+// Run with: node --test tests/js/
+// The browser PNG File reader is a port of utils/prompt_inspector.py's bounded
+// reader (_png_metadata, _PngRecords, _png_text, _inflate, _batch_normalized). Each
+// rule below names the Python branch it mirrors; tests/test_local_inspect_parity.py
+// proves the two agree on the committed parity corpus.
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const zlib = require("node:zlib");
+const { classifyPrefix, readPngMetadataFile, readImageHeader } = require("../../web/js/png-metadata.js");
+const bytes = require("./helpers/png-bytes.mjs");
+
+const { png, raw, ihdr, idat, iend, tEXt, zTXt, iTXt, chunk, blobOf, sparseBlob, recordingBlob, slowBlob, failingBlob, shrunkBlob, concat, u32, latin1, parametersText } = bytes;
+
+const MiB = 1024 * 1024;
+const ROLE_BUDGET = 2 * MiB;
+const WORKFLOW_BUDGET = 4 * MiB;
+const PNG_READ_CEILING = 19794389;
+const FIXTURES = path.join(__dirname, "..", "fixtures", "local-inspect");
+
+async function read(fileBytes, options) {
+    return readPngMetadataFile(blobOf(fileBytes), options);
+}
+
+function fill(byte, count) {
+    return Buffer.alloc(count, byte);
+}
+
+test("contract: the reader, classifier and header reader are exported", () => {
+    assert.equal(typeof readPngMetadataFile, "function");
+    assert.equal(typeof classifyPrefix, "function");
+    assert.equal(typeof readImageHeader, "function");
+});
+
+test("reads the four retained records and the IHDR size from a core SaveImage PNG", async () => {
+    const result = await read(raw(
+        ihdr(640, 480),
+        idat(),
+        tEXt("prompt", '{"1":{"class_type":"KSampler"}}'),
+        iTXt("workflow", '{"nodes":[]}'),
+        tEXt("parameters", "cat\nSteps: 20, Seed: 1"),
+        zTXt("comfyassets_prompt_pairs", '{"pairs":[]}'),
+        tEXt("Software", "ComfyUI"),
+        iend(),
+    ));
+    assert.deepEqual(result, {
+        status: "complete",
+        records: {
+            prompt: '{"1":{"class_type":"KSampler"}}',
+            workflow: '{"nodes":[]}',
+            parameters: "cat\nSteps: 20, Seed: 1",
+            comfyassets_prompt_pairs: '{"pairs":[]}',
+        },
+        limited: [],
+        width: 640,
+        height: 480,
+    });
+});
+
+test("local PNG skips sparse pixels and reads post-IDAT text", async () => {
+    // Two 1.5 GiB IDAT chunks (each under the 0x7FFFFFFF chunk ceiling) with the
+    // prompt after them: nothing of the 3 GiB is read or allocated.
+    const half = 1.5 * 1024 * 1024 * 1024;
+    const head = concat(bytes.SIGNATURE, ihdr(8192, 8192), u32(half), latin1("IDAT"));
+    const idat1 = { start: bytes.SIGNATURE.length + ihdr().length, end: bytes.SIGNATURE.length + ihdr().length + 8 + half + 4 };
+    const idat2 = { start: idat1.end, end: idat1.end + 8 + half + 4 };
+    const between = concat(u32(0), u32(half), latin1("IDAT"));
+    const tail = concat(u32(0), tEXt("prompt", '{"3":{"class_type":"KSampler"}}'), iend());
+    const size = idat2.end - 4 + tail.length;
+    const file = sparseBlob([
+        { offset: 0, bytes: head },
+        { offset: idat1.end - 4, bytes: between },
+        { offset: idat2.end - 4, bytes: tail },
+    ], size);
+
+    const result = await readPngMetadataFile(file);
+
+    assert.equal(result.status, "complete");
+    assert.deepEqual(result.records, { prompt: '{"3":{"class_type":"KSampler"}}' });
+    assert.deepEqual([result.width, result.height], [8192, 8192]);
+    const insideIdat = file.ranges.filter(([start, end]) => [idat1, idat2].some((region) => start >= region.start && end <= region.end));
+    assert.ok(insideIdat.length >= 2, "the IDAT headers were read");
+    for (const [start, end] of insideIdat) assert.ok(end - start <= 12, `range inside IDAT longer than 12: [${start}, ${end})`);
+    const total = file.ranges.reduce((sum, [start, end]) => sum + (end - start), 0);
+    assert.ok(total <= PNG_READ_CEILING, `read ${total} bytes`);
+});
+
+test("serves the retained prefix without slicing it again", async () => {
+    const whole = png(tEXt("prompt", "p"));
+    const file = recordingBlob(whole);
+    const result = await readPngMetadataFile(file, { prefix: whole.subarray(0, 32) });
+    assert.equal(result.status, "complete");
+    assert.ok(file.ranges.every(([start]) => start >= 32), JSON.stringify(file.ranges));
+    assert.deepEqual(result.records, { prompt: "p" });
+});
+
+test("unknown text keys are skipped by length without reading their body", async () => {
+    const body = fill(0x41, 1000);
+    const whole = png(tEXt("Software", body), tEXt("prompt", "p"));
+    const softwareStart = bytes.SIGNATURE.length + ihdr().length + idat().length;
+    const bodyStart = softwareStart + 8 + "Software".length + 1;
+    const bodyEnd = bodyStart + body.length + 4;
+    const file = recordingBlob(whole);
+    const result = await readPngMetadataFile(file);
+    assert.equal(result.status, "complete");
+    const insideBody = file.ranges.filter(([start, end]) => start < bodyEnd && end > softwareStart + 8 + 80);
+    assert.deepEqual(insideBody, [], "the body past the 80-byte keyword prefix was sliced");
+});
+
+const WF_OVER = WORKFLOW_BUDGET + 1;
+const bigWorkflow = () => tEXt("workflow", fill(0x7b, WF_OVER - "workflow".length - 1));
+
+// One row per Python branch (prompt_inspector.py:91-260).
+const RULES = [
+    { name: "bad IHDR CRC", file: () => raw(ihdr(1, 1, { crc: 1 }), idat(), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "bad text CRC", file: () => png(tEXt("prompt", "p", { crc: 1 })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "bad IEND CRC", file: () => raw(ihdr(), idat(), iend({ crc: 1 })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "first chunk not IHDR", file: () => raw(idat(), ihdr(), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "IHDR not 13 bytes", file: () => raw(chunk("IHDR", concat(u32(1), u32(1), [8, 6, 0, 0])), idat(), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "second IHDR", file: () => raw(ihdr(), idat(), ihdr(), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "zero width", file: () => raw(ihdr(0, 1), idat(), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "zero height", file: () => raw(ihdr(1, 0), idat(), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "length 0x80000000", file: () => raw(ihdr(), idat(), chunk("tEXt", latin1("k\0v"), { declaredLength: 0x80000000 }), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "end past size", file: () => raw(ihdr(), idat(), chunk("tEXt", latin1("k\0v"), { declaredLength: 100 }), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "file ends inside a chunk header", file: () => raw(ihdr(), idat(), u32(5)), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "file ends before any chunk", file: () => raw(), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "too short for a signature", file: () => bytes.SIGNATURE.subarray(0, 5), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "not a PNG", file: () => latin1("GIF89a................................."), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "IEND without IDAT", file: () => raw(ihdr(), tEXt("prompt", "p"), iend()), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "nonzero IEND length", file: () => raw(ihdr(), idat(), chunk("IEND", [1])), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "duplicate key with a different length", file: () => png(tEXt("prompt", "one"), tEXt("prompt", "other")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "duplicate key, same length, different bytes", file: () => png(tEXt("prompt", "one"), tEXt("prompt", "two")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "duplicate key, same bytes, different chunk type", file: () => png(tEXt("prompt", "one"), chunk("zTXt", latin1("prompt\0one"))), expect: { status: "unreadable", reason: "invalid-png" } },
+    {
+        name: "byte-identical duplicate kept once",
+        file: () => png(tEXt("prompt", "same"), tEXt("prompt", "same"), tEXt("prompt", "same")),
+        expect: { status: "complete", records: { prompt: "same" }, limited: [], width: 1, height: 1 },
+    },
+    {
+        name: "parameters copies differing only in Batch index keep the last",
+        file: () => png(tEXt("parameters", parametersText("cat", 0)), tEXt("parameters", parametersText("cat", 1)), tEXt("parameters", parametersText("cat", 12))),
+        expect: { status: "complete", records: { parameters: parametersText("cat", 12) }, limited: [], width: 1, height: 1 },
+    },
+    { name: "parameters copies with any other difference", file: () => png(tEXt("parameters", parametersText("cat", 0)), tEXt("parameters", parametersText("dog", 1))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "parameters copies without a settings footer", file: () => png(tEXt("parameters", "cat"), tEXt("parameters", "dog")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "parameters copies with two footers", file: () => png(tEXt("parameters", `${parametersText("cat", 0)}\nSteps: 1, x`), tEXt("parameters", `${parametersText("cat", 1)}\nSteps: 1, x`)), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "parameters copies with two batch indexes", file: () => png(tEXt("parameters", parametersText("cat", 0, { seedField: "Batch index: 0" })), tEXt("parameters", parametersText("cat", 1, { seedField: "Batch index: 1" }))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "parameters copies whose batch index is not a whole settings field", file: () => png(tEXt("parameters", "Steps: 20, Batch index: 0 trailing"), tEXt("parameters", "Steps: 20, Batch index: 1 trailing")), expect: { status: "unreadable", reason: "invalid-png" } },
+    {
+        name: "workflow 4 MiB + 1 encoded is limited, other records intact",
+        file: () => png(tEXt("prompt", "p"), bigWorkflow(), tEXt("parameters", "cat\nSteps: 1, x")),
+        expect: { status: "complete", records: { prompt: "p", parameters: "cat\nSteps: 1, x" }, limited: ["workflow"], width: 1, height: 1 },
+    },
+    {
+        name: "a duplicate of a limited workflow is skipped",
+        file: () => png(bigWorkflow(), bigWorkflow(), tEXt("prompt", "p")),
+        expect: { status: "complete", records: { prompt: "p" }, limited: ["workflow"], width: 1, height: 1 },
+    },
+    {
+        name: "workflow over 4 MiB decoded (zTXt) is limited",
+        file: () => png(zTXt("workflow", fill(0x7b, WORKFLOW_BUDGET + 1), { level: 9 }), tEXt("prompt", "p")),
+        expect: { status: "complete", records: { prompt: "p" }, limited: ["workflow"], width: 1, height: 1 },
+    },
+    {
+        name: "workflow at exactly 4 MiB decoded is kept",
+        file: () => png(zTXt("workflow", fill(0x7b, WORKFLOW_BUDGET), { level: 9 })),
+        check: (result) => {
+            assert.equal(result.status, "complete");
+            assert.equal(result.records.workflow.length, WORKFLOW_BUDGET);
+            assert.deepEqual(result.limited, []);
+        },
+    },
+    {
+        name: "workflow under 4 MiB inflated but over 4 MiB as UTF-8 is limited",
+        file: () => png(zTXt("workflow", fill(0xe9, WORKFLOW_BUDGET - 10), { level: 9 }), tEXt("prompt", "p")),
+        expect: { status: "complete", records: { prompt: "p" }, limited: ["workflow"], width: 1, height: 1 },
+    },
+    { name: "roles 2 MiB + 1 encoded", file: () => png(tEXt("prompt", fill(0x41, ROLE_BUDGET + 1 - "prompt".length - 1))), expect: { status: "unreadable", reason: "metadata-limit" } },
+    { name: "roles summed over 2 MiB encoded", file: () => png(tEXt("prompt", fill(0x41, 1.5 * MiB)), tEXt("parameters", fill(0x41, 0.5 * MiB))), expect: { status: "unreadable", reason: "metadata-limit" } },
+    { name: "roles 2 MiB + 1 decoded via zTXt", file: () => png(zTXt("prompt", fill(0x41, ROLE_BUDGET + 1), { level: 9 })), expect: { status: "unreadable", reason: "metadata-limit" } },
+    { name: "roles over 2 MiB as UTF-8 from Latin-1 high bytes", file: () => png(tEXt("prompt", fill(0xe9, MiB + 1))), expect: { status: "unreadable", reason: "metadata-limit" } },
+    {
+        name: "roles share the decoded budget across records",
+        file: () => png(zTXt("prompt", fill(0x41, 1.5 * MiB), { level: 9 }), zTXt("parameters", fill(0x41, 0.5 * MiB + 1), { level: 9 })),
+        expect: { status: "unreadable", reason: "metadata-limit" },
+    },
+    {
+        name: "roles at exactly 2 MiB decoded are kept",
+        file: () => png(zTXt("prompt", fill(0x41, 1.5 * MiB), { level: 9 }), zTXt("parameters", fill(0x41, 0.5 * MiB), { level: 9 })),
+        check: (result) => {
+            assert.equal(result.status, "complete");
+            assert.equal(result.records.prompt.length + result.records.parameters.length, ROLE_BUDGET);
+        },
+    },
+    {
+        name: "duplicate workflow bytes capped at 8 MiB: the workflow becomes limited",
+        file: () => {
+            const workflow = tEXt("workflow", fill(0x7b, 3 * MiB));
+            return png(workflow, workflow, workflow, workflow, tEXt("prompt", "p"));
+        },
+        expect: { status: "complete", records: { prompt: "p" }, limited: ["workflow"], width: 1, height: 1 },
+    },
+    {
+        name: "duplicate workflow bytes within 8 MiB keep the workflow",
+        file: () => {
+            const workflow = tEXt("workflow", fill(0x7b, 3 * MiB));
+            return png(workflow, workflow, workflow);
+        },
+        check: (result) => {
+            assert.equal(result.status, "complete");
+            assert.equal(result.records.workflow.length, 3 * MiB);
+            assert.deepEqual(result.limited, []);
+        },
+    },
+    {
+        name: "duplicate role bytes capped at 4 MiB",
+        file: () => {
+            const prompt = tEXt("prompt", fill(0x41, 1.5 * MiB));
+            return png(prompt, prompt, prompt, prompt);
+        },
+        expect: { status: "unreadable", reason: "metadata-limit" },
+    },
+    {
+        name: "duplicate decoded parameters capped at 4 MiB",
+        file: () => {
+            const copy = (index) => zTXt("parameters", parametersText(fill(0x41, 1.5 * MiB).toString("latin1"), index), { level: 9 });
+            return png(copy(0), copy(1), copy(2), copy(3));
+        },
+        expect: { status: "unreadable", reason: "metadata-limit" },
+    },
+    {
+        name: "a longer batch copy draws the growth from the role budget",
+        file: () => {
+            const base = parametersText("", 9);
+            const positive = fill(0x41, ROLE_BUDGET - base.length - 1).toString("latin1");
+            return png(zTXt("parameters", parametersText(positive, 9), { level: 9 }), zTXt("parameters", parametersText(positive, 100), { level: 9 }));
+        },
+        expect: { status: "unreadable", reason: "metadata-limit" },
+    },
+    {
+        name: "a longer batch copy within the role budget is kept",
+        file: () => {
+            const base = parametersText("", 9);
+            const positive = fill(0x41, ROLE_BUDGET - base.length - 2).toString("latin1");
+            return png(zTXt("parameters", parametersText(positive, 9), { level: 9 }), zTXt("parameters", parametersText(positive, 10), { level: 9 }));
+        },
+        check: (result) => {
+            assert.equal(result.status, "complete");
+            assert.ok(result.records.parameters.endsWith("Batch index: 10, Seed: 1"));
+        },
+    },
+    {
+        name: "a batch copy inflating past the role budget",
+        file: () => png(tEXt("parameters", parametersText("cat", 0)), zTXt("parameters", parametersText(fill(0x41, ROLE_BUDGET).toString("latin1"), 1), { level: 9 })),
+        expect: { status: "unreadable", reason: "metadata-limit" },
+    },
+    {
+        name: "10,000 chunks without IEND",
+        file: () => concat(bytes.SIGNATURE, ihdr(), idat(), ...Array.from({ length: 9999 }, () => chunk("xxXx", [])), iend()),
+        expect: { status: "unreadable", reason: "metadata-limit" },
+    },
+    {
+        name: "IEND as the 10,000th chunk is read",
+        file: () => concat(bytes.SIGNATURE, ihdr(), idat(), ...Array.from({ length: 9997 }, () => chunk("xxXx", [])), iend()),
+        expect: { status: "complete", records: {}, limited: [], width: 1, height: 1 },
+    },
+    { name: "zTXt method not 0", file: () => png(zTXt("prompt", "p", { method: 1 })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "zTXt without a method byte", file: () => png(chunk("zTXt", latin1("prompt\0"))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt flag 2", file: () => png(iTXt("prompt", "p", { flag: 2 })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt compressed with method 1", file: () => png(iTXt("prompt", "p", { flag: 1, method: 1 })), expect: { status: "unreadable", reason: "invalid-png" } },
+    {
+        name: "iTXt uncompressed ignores the method byte",
+        file: () => png(iTXt("prompt", "p", { flag: 0, method: 7 })),
+        expect: { status: "complete", records: { prompt: "p" }, limited: [], width: 1, height: 1 },
+    },
+    { name: "iTXt shorter than flag and method", file: () => png(chunk("iTXt", latin1("prompt\0\0"))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt missing the translated keyword separator", file: () => png(chunk("iTXt", concat(latin1("prompt\0"), [0, 0], latin1("en\0text")))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt non-ASCII language tag", file: () => png(iTXt("prompt", "p", { lang: [0xc3, 0xa9] })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt invalid UTF-8 translated keyword", file: () => png(iTXt("prompt", "p", { translated: [0xff] })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt invalid UTF-8 text", file: () => png(iTXt("prompt", [0xc3, 0x28])), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "iTXt encoded surrogate", file: () => png(iTXt("prompt", [0xed, 0xa0, 0x80])), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "NUL in tEXt text", file: () => png(tEXt("prompt", "a\0b")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "NUL in inflated zTXt text", file: () => png(zTXt("prompt", "a\0b")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "NUL in iTXt text", file: () => png(iTXt("prompt", "a\0b")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "keyword of 0 bytes", file: () => png(chunk("tEXt", latin1("\0v"))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "keyword of 80 bytes", file: () => png(tEXt("k".repeat(80), "v")), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "keyword without a NUL", file: () => png(chunk("tEXt", latin1("nonul"))), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "empty text chunk", file: () => png(chunk("tEXt", [])), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "malformed keyword on an unknown key still fails", file: () => png(tEXt("prompt", "p"), chunk("tEXt", latin1("x".repeat(100)))), expect: { status: "unreadable", reason: "invalid-png" } },
+    {
+        name: "keyword of 79 bytes is read",
+        file: () => png(tEXt("k".repeat(79), "v"), tEXt("prompt", "p")),
+        expect: { status: "complete", records: { prompt: "p" }, limited: [], width: 1, height: 1 },
+    },
+    {
+        name: "Latin-1 0xE9 is an e-acute in tEXt and zTXt",
+        file: () => png(tEXt("prompt", [0xe9]), zTXt("parameters", [0xe9, 0x0a, 0x53, 0x74, 0x65, 0x70, 0x73, 0x3a, 0x20, 0x31])),
+        expect: { status: "complete", records: { prompt: "é", parameters: "é\nSteps: 1" }, limited: [], width: 1, height: 1 },
+    },
+    {
+        name: "iTXt BOM is preserved, compressed and not",
+        file: () => png(iTXt("prompt", "{}"), iTXt("workflow", "[]", { flag: 1, lang: "en", translated: "wörkflow" })),
+        expect: { status: "complete", records: { prompt: "{}", workflow: "[]" }, limited: [], width: 1, height: 1 },
+    },
+    { name: "truncated zlib data", file: () => png(zTXt("prompt", "x".repeat(500), { compressed: zlib.deflateSync(latin1("x".repeat(500))).subarray(0, 8) })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "trailing bytes after the zlib stream", file: () => png(zTXt("prompt", "p", { compressed: concat(zlib.deflateSync(latin1("p")), [1, 2, 3]) })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "empty zlib data", file: () => png(zTXt("prompt", "p", { compressed: [] })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "garbage zlib data", file: () => png(zTXt("prompt", "p", { compressed: [1, 2, 3, 4, 5, 6, 7, 8] })), expect: { status: "unreadable", reason: "invalid-png" } },
+    { name: "truncated compressed iTXt", file: () => png(iTXt("prompt", "p", { flag: 1, compressed: zlib.deflateSync(latin1("x".repeat(500))).subarray(0, 8) })), expect: { status: "unreadable", reason: "invalid-png" } },
+    {
+        name: "chunks after IEND are ignored",
+        file: () => concat(png(tEXt("prompt", "p")), tEXt("workflow", "w")),
+        expect: { status: "complete", records: { prompt: "p" }, limited: [], width: 1, height: 1 },
+    },
+    {
+        name: "non-ASCII chunk types are skipped",
+        file: () => png(chunk("\xff\xfe\x80\x81", [1, 2, 3]), tEXt("prompt", "p")),
+        expect: { status: "complete", records: { prompt: "p" }, limited: [], width: 1, height: 1 },
+    },
+];
+
+for (const rule of RULES) {
+    test(`server rules, one by one: ${rule.name}`, async () => {
+        const result = await read(rule.file());
+        if (rule.check) rule.check(result);
+        else assert.deepEqual(result, rule.expect);
+    });
+}
+
+test("decompress: undefined with zTXt is decompression-unavailable and yields no records", async () => {
+    const result = await read(png(tEXt("prompt", "p"), zTXt("workflow", "w")), { decompress: undefined });
+    assert.deepEqual(result, { status: "unreadable", reason: "decompression-unavailable" });
+    const plain = await read(png(tEXt("prompt", "p"), zTXt("Comment", "skipped")), { decompress: undefined });
+    assert.deepEqual(plain.records, { prompt: "p" });
+});
+
+function instrumentedStream(transform) {
+    const stats = { writes: [], inFlight: 0, maxInFlight: 0 };
+    return {
+        stats,
+        Stream: class {
+            constructor() {
+                const stream = new TransformStream({
+                    async transform(chunk, controller) {
+                        stats.writes.push(chunk.byteLength);
+                        stats.inFlight += 1;
+                        stats.maxInFlight = Math.max(stats.maxInFlight, stats.inFlight);
+                        await transform(chunk, controller);
+                        stats.inFlight -= 1;
+                    },
+                });
+                this.writable = stream.writable;
+                this.readable = stream.readable;
+            }
+        },
+    };
+}
+
+test("inflation keeps one <=256-byte write in flight", async () => {
+    const body = fill(0x41, 3000);
+    const { stats, Stream } = instrumentedStream(async (chunk, controller) => {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+        controller.enqueue(chunk);
+    });
+    // The fake "inflates" by passing bytes through, so the stored body is the text.
+    const result = await read(png(chunk("zTXt", concat(latin1("prompt\0"), [0], body))), { decompress: Stream });
+    assert.equal(result.status, "complete");
+    assert.equal(result.records.prompt, body.toString("latin1"));
+    assert.ok(stats.writes.every((size) => size <= 256), JSON.stringify(stats.writes));
+    assert.equal(stats.writes.reduce((sum, size) => sum + size, 0), body.length);
+    assert.equal(stats.maxInFlight, 1);
+});
+
+test("inflation settles once on abort with an AbortError and no unhandled rejection", async () => {
+    const unhandled = [];
+    const onUnhandled = (reason) => unhandled.push(reason);
+    process.on("unhandledRejection", onUnhandled);
+    try {
+        const { stats, Stream } = instrumentedStream(() => new Promise(() => {}));
+        const controller = new AbortController();
+        const pending = readPngMetadataFile(blobOf(png(zTXt("prompt", "p".repeat(1000)))), { decompress: Stream, signal: controller.signal });
+        let settled = 0;
+        pending.then(() => settled++, () => settled++);
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        assert.equal(settled, 0, "the read waits on the stream");
+        controller.abort();
+        await assert.rejects(pending, (error) => error.name === "AbortError");
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        assert.equal(settled, 1);
+        assert.equal(stats.maxInFlight, 1);
+        assert.deepEqual(unhandled, []);
+    } finally {
+        process.off("unhandledRejection", onUnhandled);
+    }
+});
+
+test("a stream error under a live signal is still invalid-png, not an abort", async () => {
+    const controller = new AbortController();
+    const result = await read(png(zTXt("prompt", "p", { compressed: [1, 2, 3, 4, 5, 6, 7, 8] })), { signal: controller.signal });
+    assert.deepEqual(result, { status: "unreadable", reason: "invalid-png" });
+    assert.equal(controller.signal.aborted, false);
+});
+
+test("an already aborted signal rejects before any slice", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const file = recordingBlob(png(tEXt("prompt", "p")));
+    await assert.rejects(readPngMetadataFile(file, { signal: controller.signal }), (error) => error.name === "AbortError");
+    assert.deepEqual(file.ranges, []);
+});
+
+test("aborting between slices rejects with an AbortError", async () => {
+    const controller = new AbortController();
+    const whole = png(tEXt("prompt", "p"));
+    let slices = 0;
+    const file = {
+        size: whole.length,
+        slice(start, end) {
+            return {
+                arrayBuffer: async () => {
+                    if (++slices === 3) controller.abort();
+                    return whole.slice(start, end).buffer;
+                },
+            };
+        },
+    };
+    await assert.rejects(readPngMetadataFile(file, { signal: controller.signal }), (error) => error.name === "AbortError");
+});
+
+test("aborting while inflating a real deflate stream rejects with an AbortError", async () => {
+    const controller = new AbortController();
+    let inflating = false;
+    class Tracked extends DecompressionStream {
+        constructor(format) {
+            super(format);
+            inflating = true;
+        }
+    }
+    // The slow slices make the pacer yield inside the inflater's feed loop; that
+    // yield aborts, so the real stream is torn down mid-inflation.
+    const yieldControl = async () => {
+        if (inflating) controller.abort();
+    };
+    const slow = slowBlob(png(zTXt("prompt", "p", { compressed: require("node:crypto").randomBytes(5000) })), 10);
+    await assert.rejects(readPngMetadataFile(slow, { signal: controller.signal, yieldControl, decompress: Tracked }), (error) => error.name === "AbortError");
+    assert.equal(inflating, true);
+});
+
+test("yields control about every 8 ms while the file answers slowly", async () => {
+    let yields = 0;
+    const yieldControl = async () => {
+        yields += 1;
+    };
+    const result = await readPngMetadataFile(slowBlob(png(tEXt("prompt", "p")), 10), { yieldControl });
+    assert.equal(result.status, "complete");
+    assert.ok(yields >= 1, `yielded ${yields} times`);
+});
+
+test("the default yield lets the event loop turn", async () => {
+    const result = await readPngMetadataFile(slowBlob(png(tEXt("prompt", "p")), 10));
+    assert.deepEqual(result.records, { prompt: "p" });
+});
+
+test("a slice that fails is a read failure", async () => {
+    assert.deepEqual(await readPngMetadataFile(failingBlob(100)), { status: "unreadable", reason: "read-failure" });
+    assert.deepEqual(await readPngMetadataFile(null), { status: "unreadable", reason: "read-failure" });
+});
+
+test("a file that shrank under the reader is a read failure", async () => {
+    const whole = png(tEXt("prompt", "p"));
+    assert.deepEqual(await readPngMetadataFile(shrunkBlob(whole.subarray(0, 40), whole.length)), { status: "unreadable", reason: "read-failure" });
+});
+
+test("classifier", () => {
+    assert.deepEqual(classifyPrefix(bytes.SIGNATURE), { media: "image", kind: "png" });
+    assert.deepEqual(classifyPrefix(Uint8Array.from([0xff, 0xd8, 0xff, 0xe0])), { media: "image", kind: "jpeg" });
+    assert.deepEqual(classifyPrefix(latin1("RIFF\0\0\0\0WEBPVP8 ")), { media: "image", kind: "webp" });
+    assert.deepEqual(classifyPrefix(latin1("\0\0\0\x18ftypisom\0\0\0\0")), { media: "video", kind: "iso-bmff" });
+    assert.deepEqual(classifyPrefix(latin1("\0\0\0\x14ftypqt  ")), { media: "video", kind: "iso-bmff" });
+    assert.deepEqual(classifyPrefix(Uint8Array.from([0x1a, 0x45, 0xdf, 0xa3, 0x01])), { media: "video", kind: "matroska" });
+    assert.deepEqual(classifyPrefix(latin1("RIFF\0\0\0\0AVI LIST")), { media: "video", kind: "avi" });
+    const asf = Uint8Array.from([0x30, 0x26, 0xb2, 0x75, 0x8e, 0x66, 0xcf, 0x11, 0xa6, 0xd9, 0x00, 0xaa, 0x00, 0x62, 0xce, 0x6c, 0, 0]);
+    assert.deepEqual(classifyPrefix(asf), { media: "video", kind: "asf" });
+    assert.deepEqual(classifyPrefix(asf.buffer), { media: "video", kind: "asf" });
+    for (const text of ["plain text file", "<!DOCTYPE html><html>", '<?xml version="1.0"?><svg', "#EXTM3U\n#EXT-X-VERSION:3", "RIFF\0\0\0\0WAVEfmt ", "\0\0\0\x18moov", ""]) {
+        assert.equal(classifyPrefix(latin1(text)), null, text);
+    }
+    assert.equal(classifyPrefix(bytes.SIGNATURE.subarray(0, 7)), null);
+    assert.equal(classifyPrefix(Uint8Array.from([0xff, 0xd8])), null);
+    assert.equal(classifyPrefix("not bytes"), null);
+    assert.equal(classifyPrefix(null), null);
+});
+
+test("image header: JPEG and WebP fixtures match Pillow's dimensions", async () => {
+    // tests/test_local_inspect_parity.py asserts the same two files against Pillow.
+    const jpeg = blobOf(fs.readFileSync(path.join(FIXTURES, "tiny.jpg")));
+    assert.deepEqual(await readImageHeader(jpeg, "jpeg"), { format: "JPEG", width: 48, height: 32 });
+    const webp = blobOf(fs.readFileSync(path.join(FIXTURES, "tiny.webp")));
+    assert.deepEqual(await readImageHeader(webp, "webp"), { format: "WEBP", width: 40, height: 24 });
+});
+
+test("image header: JPEG marker walk skips padding, junk, standalone markers and tables", async () => {
+    const segment = (marker, body) => concat([0xff, marker], u32(body.length + 2).subarray(2), body);
+    const sof = (marker, width, height) => segment(marker, concat([8], u32(height).subarray(2), u32(width).subarray(2), [3]));
+    const sized = concat([0xff, 0xd8], segment(0xe1, fill(0, 20)), [0xff, 0xff, 0xff, 0x00, 0x00, 0x11], [0xff, 0xd0], [0xff, 0x01], segment(0xc4, fill(0, 4)), segment(0xc8, []), segment(0xcc, [1]), sof(0xc2, 300, 200));
+    assert.deepEqual(await readImageHeader(blobOf(sized), "jpeg"), { format: "JPEG", width: 300, height: 200 });
+    for (const marker of [0xc0, 0xc1, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf]) {
+        assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], sof(marker, 7, 9))), "jpeg"), { format: "JPEG", width: 7, height: 9 }, marker.toString(16));
+    }
+    const none = { format: "JPEG", width: null, height: null };
+    assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], segment(0xda, [1]))), "jpeg"), none, "SOS before SOF");
+    assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], [0xff])), "jpeg"), none, "ends on a marker byte");
+    assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], [0xff, 0xe1, 0x00])), "jpeg"), none, "ends inside a length");
+    assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], [0xff, 0xc0, 0x00, 0x08, 8, 0])), "jpeg"), none, "ends inside SOF");
+    assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], segment(0xe1, []))), "jpeg"), none, "no SOF at all");
+    assert.deepEqual(await readImageHeader(blobOf(Uint8Array.from([0xff])), "jpeg"), none, "too short");
+    assert.deepEqual(await readImageHeader(blobOf(latin1("RIFF")), "jpeg"), none, "not a JPEG");
+    // A SOF past the 64 KiB read gives no dimensions rather than reading on.
+    assert.deepEqual(await readImageHeader(blobOf(concat([0xff, 0xd8], segment(0xe1, fill(0, 65000)), segment(0xe2, fill(0, 1000)), sof(0xc0, 5, 5))), "jpeg"), none, "SOF beyond 64 KiB");
+});
+
+test("image header: WebP VP8, VP8L and VP8X headers", async () => {
+    const riff = (...rest) => concat(latin1("RIFF"), u32(0), latin1("WEBP"), ...rest);
+    const chunkHeader = (type, size) => concat(latin1(type), Uint8Array.from([size & 0xff, (size >>> 8) & 0xff, (size >>> 16) & 0xff, 0]));
+    const vp8 = riff(chunkHeader("VP8 ", 100), [0x30, 0x0b, 0x00, 0x9d, 0x01, 0x2a], [40, 0x40], [24, 0x80], fill(0, 20));
+    assert.deepEqual(await readImageHeader(blobOf(vp8), "webp"), { format: "WEBP", width: 40, height: 24 }, "scale bits are masked");
+    // 14-bit width-1 = 63 and height-1 = 47, little-endian bit-packed after the 0x2f signature.
+    const vp8l = riff(chunkHeader("VP8L", 100), [0x2f], [0x3f, 0xc0, 0x0b, 0x00, 0x00], fill(0, 20));
+    assert.deepEqual(await readImageHeader(blobOf(vp8l), "webp"), { format: "WEBP", width: 64, height: 48 });
+    const vp8x = riff(chunkHeader("VP8X", 10), [0x10, 0, 0, 0], [0xff, 0x00, 0x01], [0x2f, 0x00, 0x00], fill(0, 20));
+    assert.deepEqual(await readImageHeader(blobOf(vp8x), "webp"), { format: "WEBP", width: 65792, height: 48 });
+    const none = { format: "WEBP", width: null, height: null };
+    assert.deepEqual(await readImageHeader(blobOf(riff(chunkHeader("VP8 ", 100), [0x30, 0x0b, 0x00, 0x00, 0x01, 0x2a], fill(0, 24))), "webp"), none, "bad start code");
+    assert.deepEqual(await readImageHeader(blobOf(riff(chunkHeader("VP8L", 100), [0x00], fill(0, 24))), "webp"), none, "bad VP8L signature");
+    assert.deepEqual(await readImageHeader(blobOf(riff(chunkHeader("ALPH", 100), fill(0, 24))), "webp"), none, "unknown first chunk");
+    assert.deepEqual(await readImageHeader(blobOf(riff(chunkHeader("VP8 ", 100))), "webp"), none, "too short");
+    assert.deepEqual(await readImageHeader(blobOf(latin1("RIFF\0\0\0\0WAVEfmt ".padEnd(40, "\0"))), "webp"), none, "not WebP");
+});
+
+test("image header: other kinds give no format and the read stays within 64 KiB", async () => {
+    assert.deepEqual(await readImageHeader(blobOf(bytes.SIGNATURE), "png"), { format: null, width: null, height: null });
+    const file = recordingBlob(concat([0xff, 0xd8], fill(0, 200000)));
+    await readImageHeader(file, "jpeg");
+    assert.deepEqual(file.ranges, [[0, 65536]]);
+    const small = recordingBlob(concat([0xff, 0xd8, 0xff]));
+    await readImageHeader(small, "jpeg");
+    assert.deepEqual(small.ranges, [[0, 3]]);
+});

tests/js/support-module-urls.test.js

@@ -0,0 +1,39 @@
+// The Node oracles that Python drives (tests/js/support/*.mjs) import product
+// modules dynamically. A dynamic import takes a URL or a bare/relative specifier,
+// never a filesystem path: on Windows `D:\...\x.mjs` parses as the `d:` scheme
+// (ERR_UNSUPPORTED_ESM_URL_SCHEME). Every such import goes through moduleUrl, and
+// this test proves the Windows form on any host so Linux catches a regression.
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const support = path.join(here, "support");
+const m = await import("./support/module-url.mjs").catch((error) => {
+    if (error.code !== "ERR_MODULE_NOT_FOUND") throw error;
+    return {};
+});
+
+test("moduleUrl turns a filesystem path into a file: URL on every platform", async () => {
+    assert.equal(typeof m.moduleUrl, "function", "moduleUrl is exported");
+    assert.equal(m.moduleUrl("D:\\x\\y z.mjs", { windows: true }), "file:///D:/x/y%20z.mjs");
+    assert.equal(m.moduleUrl("C:\\repo\\web\\js\\workspace\\local-video.mjs", { windows: true }), "file:///C:/repo/web/js/workspace/local-video.mjs");
+    assert.equal(m.moduleUrl("/repo/web/js/a b.mjs", { windows: false }), "file:///repo/web/js/a%20b.mjs");
+    const own = m.moduleUrl(path.join(here, "support", "module-url.mjs"));
+    assert.ok(own.startsWith("file:///"), own);
+    assert.equal((await import(own)).moduleUrl, m.moduleUrl, "the URL imports the same module instance");
+});
+
+test("every dynamic import in the Node oracles is a file URL, never a path", () => {
+    const scripts = fs.readdirSync(support).filter((name) => name.endsWith(".mjs"));
+    assert.ok(scripts.includes("local-inspect-oracle.mjs"));
+    for (const name of scripts) {
+        const source = fs.readFileSync(path.join(support, name), "utf8").split("\n").filter((line) => !line.trim().startsWith("//")).join("\n");
+        for (const match of source.matchAll(/\bimport\(\s*([^)]*?)[,)]/g)) {
+            const argument = match[1].trim();
+            assert.ok(/^(moduleUrl\(|pathToFileURL\(|["'`]\.{1,2}\/)/.test(argument), `${name}: import(${argument}) must be a file URL or a relative specifier`);
+        }
+    }
+});

tests/js/support/local-inspect-oracle.mjs

@@ -0,0 +1,59 @@
+// The browser's local readers and projection run over files on disk, for
+// tests/test_local_inspect_parity.py, which compares every answer with the server's
+// utils.prompt_inspector.read_inspection_file and utils.inspection_response._metadata
+// on the same file. Each file is opened as a Blob (fs.openAsBlob) so the reader
+// slices it exactly as it slices a File.
+// stdin: [{name, path} | {name, tags, limited?} | {name, records, record_formats?, carrier_text?, limited?}]
+// stdout: {name: {classified, result, metadata}} where result is readPngMetadataFile's
+//         answer for a PNG, readImageHeader's for another image, for a video
+//         {read: readVideoTags(...), selection: selectVideoCarrier(read.tags, {limited})}
+//         (selection null unless the read completed), else null; metadata is
+//         projectMetadata(...) of the local read (the server's _metadata) for every
+//         classified file, else null.
+//         A {tags} entry answers {classified: null, result: {selection}, metadata} for
+//         the carrier rule alone, as the server selects from ffprobe's tag map.
+//         A {records} entry (records null = an unreadable file) answers
+//         {classified: null, result: null, metadata} for the projection alone.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { moduleUrl } from './module-url.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const pngMetadata = require(path.join(here, '..', '..', '..', 'web', 'js', 'png-metadata.js'));
+const web = path.join(here, '..', '..', '..', 'web', 'js', 'workspace');
+// ES modules import by file URL (a Windows path would parse as a URL scheme).
+const { selectVideoCarrier } = await import(moduleUrl(path.join(web, 'local-video.mjs')));
+const { projectMetadata } = await import(moduleUrl(path.join(web, 'local-projection.mjs')));
+const { readLocalFile, toInspectionRead } = await import(moduleUrl(path.join(web, 'local-inspection.mjs')));
+
+const selectionRead = (selection) => selection.status === 'complete' ?
+    { records: selection.records, record_formats: selection.record_formats, carrierText: selection.carrierText, limited: selection.limited } : null;
+
+const chunks = [];
+for await (const chunk of process.stdin) chunks.push(chunk);
+const output = {};
+for (const entry of JSON.parse(Buffer.concat(chunks).toString('utf8'))) {
+    const { name } = entry;
+    if (entry.records !== undefined) {
+        const read = entry.records === null ? null : {
+            records: entry.records,
+            record_formats: entry.record_formats ?? Object.fromEntries(Object.keys(entry.records).map((key) => [key, 'original-text'])),
+            carrierText: entry.carrier_text ?? null, limited: entry.limited ?? [],
+        };
+        output[name] = { classified: null, result: null, metadata: projectMetadata(read) };
+        continue;
+    }
+    if (entry.path === undefined) {
+        const selection = selectVideoCarrier(entry.tags, { limited: entry.limited || [] });
+        output[name] = { classified: null, result: { selection }, metadata: projectMetadata(selectionRead(selection)) };
+        continue;
+    }
+    const file = await fs.openAsBlob(entry.path);
+    const { classification, result } = await readLocalFile(file, { pngMetadata });
+    const metadata = classification === null ? null : projectMetadata(toInspectionRead(classification, result).read);
+    output[name] = { classified: classification, result, metadata };
+}
+process.stdout.write(JSON.stringify(output));

tests/js/support/module-url.mjs

@@ -0,0 +1,9 @@
+// A dynamic import() takes a URL, never a filesystem path: on Windows a path such
+// as D:\repo\x.mjs parses as the "d:" scheme (ERR_UNSUPPORTED_ESM_URL_SCHEME).
+// Every oracle in this directory imports product modules through moduleUrl.
+import { pathToFileURL } from 'node:url';
+
+/** The file: URL for a filesystem path; `windows` forces the Windows form on any host (for tests). */
+export function moduleUrl(filePath, { windows = process.platform === 'win32' } = {}) {
+    return pathToFileURL(filePath, { windows }).href;
+}

tests/js/workspace-activity-store.test.js

@@ -0,0 +1,371 @@
+// Activity (#249 Activity-1): the session job store behind the top-bar button and pill and the Activity page.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const source = import('../../web/js/workspace/activity-store.mjs');
+
+const ID_A = 'a'.repeat(32);
+const ID_B = 'b'.repeat(32);
+const ID_C = 'c'.repeat(32);
+
+function summary(overrides = {}) {
+    return { id: ID_A, kind: 'scan', title: 'Scan for metadata', state: 'running', started_at: 1000, finished_at: null,
+        progress: 0, status_line: '', processed: 0, total: 0,
+        counters: { added: 0, known: 0, review: 0, no_metadata: 0, errors: 0 }, scope: { files: 'new', output_folders: 2 },
+        ...overrides };
+}
+
+function apiError(status, message, code) {
+    return Object.assign(new Error(message), { status, code });
+}
+
+/** A fake world: the API's answers, every opened stream, the pending timers and the toasts. */
+function harness() {
+    const world = { list: [], listError: null, posts: [], postResult: null, postError: null, streams: [], timers: [],
+        toasts: [], gets: 0 };
+    const cleanups = [];
+    const controller = new AbortController();
+    const scope = { signal: controller.signal, cleanup: fn => cleanups.push(fn) };
+    const api = {
+        async get(url, options) {
+            assert.equal(url, '/prompt_manager/jobs');
+            assert.equal(options.cache, 'no-store');
+            world.gets += 1;
+            if (world.listError) throw world.listError;
+            return { success: true, jobs: world.list };
+        },
+        async post(url, body) {
+            world.posts.push([url, body]);
+            if (world.postError) throw world.postError;
+            return world.postResult;
+        },
+    };
+    const connect = url => {
+        const stream = { url, closed: false, onmessage: null, onerror: null, close() { this.closed = true; } };
+        world.streams.push(stream);
+        return stream;
+    };
+    const timers = {
+        setTimeout(fn, delay) { const timer = { fn, delay, cleared: false }; world.timers.push(timer); return timer; },
+        clearTimeout(timer) { timer.cleared = true; },
+    };
+    world.dispose = () => { controller.abort(); cleanups.forEach(fn => fn()); };
+    world.fire = async () => {
+        const timer = world.timers.find(item => !item.cleared && !item.fired);
+        timer.fired = true;
+        timer.fn();
+        await new Promise(resolve => setImmediate(resolve));
+        return timer.delay;
+    };
+    world.open = () => world.streams.filter(stream => !stream.closed);
+    return { world, api, scope, connect, timers, pollMs: 0, notify: message => world.toasts.push(message) };
+}
+
+const send = (stream, job) => stream.onmessage({ data: JSON.stringify(job) });
+
+test('store merges list and SSE updates and caps backoff', async () => {
+    const { createActivityStore, BACKOFF_MAX_MS, LOST_DETAIL } = await source;
+    const { world, ...deps } = harness();
+    world.list = [summary(), summary({ id: ID_B, state: 'finished', finished_at: 900, counters: { added: 3, errors: 0 } })];
+    const store = createActivityStore(deps);
+    let changes = 0;
+    store.subscribe(() => { changes += 1; });
+    await store.load();
+    assert.equal(store.status, 'ready');
+    assert.deepEqual(store.jobs().map(job => [job.id, job.state]), [[ID_A, 'running'], [ID_B, 'finished']]);
+    assert.deepEqual(store.running().map(job => job.id), [ID_A]);
+    // One stream per running job only; a finished job is not followed.
+    assert.deepEqual(world.streams.map(stream => stream.url), [`/prompt_manager/jobs/${ID_A}/events`]);
+    assert.ok(changes >= 1);
+
+    // An SSE summary replaces the listed one; garbage and another job's summary are ignored.
+    const [stream] = world.streams;
+    send(stream, summary({ progress: 42, processed: 8240, total: 19622 }));
+    stream.onmessage({ data: 'not json' });
+    send(stream, summary({ id: ID_B, progress: 99 }));
+    assert.equal(store.find(ID_A).progress, 42);
+    assert.equal(store.find(ID_B).state, 'finished');
+    assert.deepEqual(world.toasts, []);
+
+    // The end of the job: the finish toast, and the stream is closed.
+    send(stream, summary({ state: 'finished', progress: 100, finished_at: 2000, counters: { added: 1420, errors: 18 } }));
+    assert.deepEqual(world.toasts, ['Scan finished · 1,420 added · 18 errors']);
+    assert.equal(stream.closed, true);
+    assert.deepEqual(store.running(), []);
+
+    // A new running job from another tab, then the server goes away: every re-read waits longer, up to 30 s.
+    world.list = [summary({ id: ID_C, state: 'running' })];
+    await store.load();
+    const second = world.open()[0];
+    assert.equal(second.url, `/prompt_manager/jobs/${ID_C}/events`);
+    world.listError = new Error('connection refused');
+    second.onerror();
+    assert.equal(second.closed, true);
+    const delays = [];
+    for (let index = 0; index < 8; index += 1) delays.push(await world.fire());
+    assert.deepEqual(delays, [1000, 2000, 4000, 8000, 16000, 30000, 30000, 30000]);
+    assert.ok(delays.every(delay => delay <= BACKOFF_MAX_MS));
+    // While the server cannot be read the running job shows as ended, so no pill stays.
+    assert.equal(store.status, 'error');
+    assert.equal(store.find(ID_C).state, 'lost');
+    assert.deepEqual(store.running(), []);
+    assert.equal(typeof LOST_DETAIL, 'string');
+
+    // The server is back without the job (a restart): it stays ended; finished jobs the server no longer lists are
+    // dropped, so the list never outgrows the server's (review M3).
+    world.listError = null;
+    world.list = [];
+    await world.fire();
+    assert.equal(store.status, 'ready');
+    assert.deepEqual(store.jobs().map(job => [job.id, job.state]), [[ID_C, 'lost']]);
+    assert.equal(world.timers.filter(timer => !timer.cleared && !timer.fired).length, 0, 'no retry after a good read');
+    assert.equal(world.toasts.length, 1, 'an ended job has no finish toast');
+    world.dispose();
+});
+
+test('a dropped stream of a still running job reattaches after the backoff, then resets it', async () => {
+    const { createActivityStore } = await source;
+    const { world, ...deps } = harness();
+    world.list = [summary()];
+    const store = createActivityStore(deps);
+    await store.load();
+    world.streams[0].onerror();
+    assert.equal(await world.fire(), 1000);
+    const again = world.open();
+    assert.equal(again.length, 1);
+    assert.equal(store.find(ID_A).state, 'running');
+    again[0].onerror();
+    assert.equal(await world.fire(), 2000);
+    send(world.open()[0], summary({ progress: 5 }));
+    world.open()[0].onerror();
+    assert.equal(await world.fire(), 1000, 'a received message resets the backoff');
+    // A second drop while a re-read is already scheduled does not schedule another.
+    world.open()[0].onerror();
+    store.load();
+    assert.equal(world.timers.filter(timer => !timer.cleared && !timer.fired).length, 1);
+    await new Promise(resolve => setImmediate(resolve));
+    world.dispose();
+    assert.ok(world.streams.every(stream => stream.closed), 'dispose closes every stream');
+    assert.ok(world.timers.every(timer => timer.cleared || timer.fired), 'dispose clears the pending re-read');
+});
+
+test('start returns busy with the running job', async () => {
+    const { createActivityStore } = await source;
+    const { world, ...deps } = harness();
+    const store = createActivityStore(deps);
+    world.postResult = { success: true, job: summary() };
+    const started = await store.start('scan');
+    assert.equal(started.job.id, ID_A);
+    assert.deepEqual(world.posts, [['/prompt_manager/jobs/scan', {}]]);
+    assert.deepEqual(world.toasts, ['Scan started.']);
+    assert.equal(world.open().length, 1, 'the started job is followed');
+
+    world.postError = apiError(409, 'Scan for metadata is already running', 'busy');
+    world.list = [summary()];
+    const busy = await store.start('scan');
+    assert.equal(busy.busy.id, ID_A);
+    assert.equal(busy.busy.title, 'Scan for metadata');
+    assert.equal(busy.message, 'Scan for metadata is already running');
+    assert.equal(world.toasts.length, 1, 'a refused start has no start toast');
+
+    world.postError = apiError(500, 'boom', null);
+    await assert.rejects(store.start('scan'), /boom/);
+    world.postError = null;
+    world.postResult = { success: true, job: { id: 'nope' } };
+    await assert.rejects(store.start('scan'), /Invalid job/);
+
+    world.postResult = { success: true, cancellation_requested: true };
+    assert.equal(await store.cancel(ID_A), true);
+    assert.deepEqual(world.posts.at(-1), [`/prompt_manager/jobs/${ID_A}/cancel`, {}]);
+    world.postResult = { success: true, cancellation_requested: false };
+    assert.equal(await store.cancel(ID_A), false);
+    world.dispose();
+});
+
+test('a list that is not a job list counts as a failed read', async () => {
+    const { createActivityStore } = await source;
+    const { world, api, ...deps } = harness();
+    const store = createActivityStore({ ...deps, api: { ...api, get: async () => ({ success: true }) } });
+    await store.load();
+    assert.equal(store.status, 'error');
+    assert.equal(world.timers.length, 1);
+    world.dispose();
+    await store.load();
+    assert.equal(store.status, 'error', 'a disposed store reads nothing');
+});
+
+test('a visible tab reads the list again every 15 s; a hidden one skips its turn', async () => {
+    const { createActivityStore, POLL_MS } = await source;
+    const { world, ...deps } = harness();
+    let visible = true;
+    const store = createActivityStore({ ...deps, pollMs: POLL_MS, isVisible: () => visible });
+    await store.load();
+    assert.equal(world.gets, 1);
+    // A job started in another tab appears on the next read.
+    world.list = [summary()];
+    assert.equal(await world.fire(), 15000);
+    assert.equal(world.gets, 2);
+    assert.deepEqual(store.running().map(job => job.id), [ID_A]);
+    visible = false;
+    assert.equal(await world.fire(), 15000);
+    assert.equal(world.gets, 2, 'a hidden tab does not read');
+    visible = true;
+    await world.fire();
+    assert.equal(world.gets, 3);
+    // A manual read replaces the pending poll rather than adding one.
+    await store.load();
+    assert.equal(world.timers.filter(timer => !timer.cleared && !timer.fired).length, 1);
+    world.dispose();
+    assert.ok(world.timers.every(timer => timer.cleared || timer.fired));
+});
+
+test('a late or older answer never brings an ended job back, so it is announced once', async () => {
+    const { createActivityStore } = await source;
+    const { world, api, ...deps } = harness();
+    const answers = [];
+    const slowApi = { ...api, get: () => new Promise(resolve => answers.push(resolve)) };
+    const store = createActivityStore({ ...deps, api: slowApi });
+    const first = store.load();
+    const second = store.load();
+    // The newer read answers first; the older one, answering later with stale data, is dropped.
+    answers[1]({ success: true, jobs: [summary()] });
+    await second;
+    answers[0]({ success: true, jobs: [] });
+    await first;
+    assert.deepEqual(store.jobs().map(job => job.state), ['running']);
+    send(world.open()[0], summary({ state: 'finished', counters: { added: 2, errors: 0 } }));
+    assert.deepEqual(world.toasts, ['Scan finished · 2 added · 0 errors']);
+    // A list read sent before the end still says running: the job stays finished and no stream reopens.
+    const third = store.load();
+    answers[2]({ success: true, jobs: [summary()] });
+    await third;
+    assert.equal(store.find(ID_A).state, 'finished');
+    assert.equal(world.open().length, 0);
+    assert.equal(world.toasts.length, 1);
+    // A stale failure is dropped too.
+    const failing = store.load();
+    const newest = store.load();
+    answers[4]({ success: true, jobs: [] });
+    await newest;
+    answers[3](Promise.reject(new Error('late failure')));
+    await failing;
+    assert.equal(store.status, 'ready');
+    world.dispose();
+});
+
+test('summaries are validated and the copy follows the spec', async () => {
+    const { parseJob, finishToast, startToast, pillParts, outcomeLine, backoffDelay } = await source;
+    for (const raw of [null, [], { id: 'x', state: 'running' }, summary({ state: 'lost' }), summary({ id: ID_A.toUpperCase() })]) {
+        assert.equal(parseJob(raw), null);
+    }
+    const loose = parseJob({ id: ID_A, state: 'running', progress: 140.4, processed: -1, total: 1.5, counters: { added: 'x', errors: 2 },
+        title: '  ', started_at: 'x', scope: [] });
+    assert.deepEqual(loose, { id: ID_A, kind: '', title: 'Background job', state: 'running', started_at: null, finished_at: null,
+        progress: 100, status_line: '', processed: 0, total: 0, counters: { added: 0, errors: 2 }, scope: {}, listed: {}, log_length: 0 });
+    assert.equal(parseJob(summary({ progress: -3 })).progress, 0);
+
+    const scan = parseJob(summary({ progress: 42, processed: 8240, total: 19622, counters: { added: 1, errors: 1 } }));
+    assert.deepEqual(pillParts(scan), { label: 'Scanning · 42%', files: ' · 8,240 / 19,622', text: 'Scanning · 42% · 8,240 / 19,622' });
+    assert.equal(pillParts({ ...scan, total: 0 }).text, 'Scanning · 42%');
+    assert.equal(pillParts({ ...scan, kind: 'thumbnails', title: 'Thumbnails' }).text, 'Thumbnails · 42% · 8,240 / 19,622');
+    assert.equal(finishToast({ ...scan, state: 'finished' }), 'Scan finished · 1 added · 1 error');
+    assert.equal(finishToast({ ...scan, state: 'cancelled' }), 'Scan cancelled · 1 added');
+    assert.equal(finishToast({ ...scan, state: 'failed' }), 'Scan failed · 1 added · 1 error');
+    assert.equal(finishToast({ ...scan, counters: {}, state: 'finished' }), 'Scan finished · 0 added · 0 errors');
+    const other = { ...scan, kind: 'backup', title: 'Backup' };
+    assert.equal(finishToast({ ...other, state: 'finished' }), 'Backup finished.');
+    assert.equal(finishToast({ ...other, state: 'cancelled' }), 'Backup was cancelled.');
+    assert.equal(finishToast({ ...other, state: 'failed' }), 'Backup failed.');
+    assert.equal(startToast(scan), 'Scan started.');
+    assert.equal(startToast(other), 'Backup started.');
+    assert.equal(outcomeLine(scan), '1 added · 1 error');
+    assert.equal(outcomeLine(other), '');
+    assert.deepEqual([-1, 0, 1, 4, 5, 6, 1e9, 0.5].map(backoffDelay), [1000, 1000, 2000, 16000, 30000, 30000, 30000, 1000]);
+});
+
+test('pagehide stops polling, closes streams and aborts the in-flight read; pageshow resumes', async () => {
+    const { createActivityStore } = await source;
+    const { world, api, ...deps } = harness();
+    const lifecycle = new EventTarget();
+    const signals = [];
+    let answer = null;
+    const pendingApi = { ...api, get: (url, options) => {
+        signals.push(options.signal);
+        world.gets += 1;
+        if (world.gets === 1) return Promise.resolve({ success: true, jobs: [summary()] });
+        return new Promise((resolve, reject) => {
+            answer = resolve;
+            options.signal.addEventListener('abort', () => reject(Object.assign(new Error('aborted'), { name: 'AbortError' })));
+        });
+    } };
+    const store = createActivityStore({ ...deps, api: pendingApi, pollMs: 15000, lifecycle });
+    await store.load();
+    assert.equal(world.open().length, 1);
+    const poll = world.timers.find(timer => !timer.cleared && timer.delay === 15000);
+    assert.ok(poll, 'a visible tab polls');
+    // A read in flight when the page goes away (a closed tab, a test teardown) is aborted, nothing is scheduled again.
+    const read = store.load();
+    lifecycle.dispatchEvent(new Event('pagehide'));
+    await read;
+    assert.equal(signals.at(-1).aborted, true);
+    assert.equal(world.open().length, 0);
+    assert.ok(world.timers.every(timer => timer.cleared || timer.fired));
+    assert.equal(store.find(ID_A).state, 'running', 'a hidden page marks nothing lost');
+    await store.load();
+    assert.equal(world.gets, 2, 'a suspended store reads nothing');
+    // Back from the cache, it reads the list again and follows the job.
+    const resumed = Object.assign(new Event('pageshow'), { persisted: true });
+    lifecycle.dispatchEvent(resumed);
+    await new Promise(resolve => setImmediate(resolve));
+    assert.equal(world.gets, 3);
+    answer({ success: true, jobs: [summary()] });
+    await new Promise(resolve => setImmediate(resolve));
+    assert.equal(world.open().length, 1);
+    world.dispose();
+    assert.equal(signals.at(-1).aborted, true, 'disposing aborts the store reads');
+    assert.equal(world.open().length, 0);
+});
+
+test('one failed read is not a restart; two in a row are, and a good read resets the backoff', async () => {
+    const { createActivityStore } = await source;
+    const { world, ...deps } = harness();
+    world.list = [summary(), summary({ id: ID_B, state: 'finished', finished_at: 900 })];
+    const store = createActivityStore(deps);
+    await store.load();
+    // A single failed read (a proxy's 502) keeps the job running and its stream open (review M1).
+    world.listError = apiError(502, 'Bad gateway', null);
+    await store.load();
+    assert.equal(store.status, 'error');
+    assert.equal(store.find(ID_A).state, 'running');
+    assert.equal(world.open().length, 1);
+    assert.equal(await world.fire(), 1000);
+    // The second failure in a row: the server is gone, so the running job ended with it.
+    assert.equal(store.find(ID_A).state, 'lost');
+    assert.equal(world.open().length, 0);
+    for (let index = 0; index < 3; index += 1) await world.fire();
+    // The server is back with a new running job: the backoff starts again at 1 s (review M2).
+    world.listError = null;
+    world.list = [summary({ id: ID_C })];
+    await world.fire();
+    assert.equal(store.status, 'ready');
+    assert.deepEqual(store.jobs().map(job => [job.id, job.state]), [[ID_C, 'running'], [ID_A, 'lost']]);
+    world.open()[0].onerror();
+    assert.equal(await world.fire(), 1000);
+    // A summary carries what its detail lists, for the job view's reads (review M12).
+    send(world.open()[0], summary({ id: ID_C, listed: { added: 3, errors: -1 }, log_length: 7 }));
+    assert.deepEqual([store.find(ID_C).listed, store.find(ID_C).log_length], [{ added: 3, errors: 0 }, 7]);
+    world.dispose();
+});
+
+test('numbers group the way the server writes them, whatever the browser locale', async () => {
+    const { pillParts, finishToast, parseJob } = await source;
+    const original = Number.prototype.toLocaleString;
+    Number.prototype.toLocaleString = function (locale, ...rest) { return original.call(this, locale ?? 'de-DE', ...rest); };
+    try {
+        const job = parseJob(summary({ progress: 41, processed: 8240, total: 19622, counters: { added: 1420, errors: 18 } }));
+        assert.equal(pillParts(job).text, 'Scanning · 41% · 8,240 / 19,622');
+        assert.equal(finishToast({ ...job, state: 'finished' }), 'Scan finished · 1,420 added · 18 errors');
+    } finally {
+        Number.prototype.toLocaleString = original;
+    }
+});

tests/js/workspace-file-inspector.test.js

@@ -86,3 +86,132 @@ test('Show in folder outcomes use the D38 toasts',async()=>{
     for(const error of [{status:403,code:null},{status:409,code:'source-changed'},{status:415,code:'unsupported-media-type'},{status:429,code:null},{status:500},new TypeError('offline')])
         assert.equal(revealOutcome(error),'The folder could not be opened. Try again.');
 });
+
+// PR L2 Task 4(c): a record read in this browser renders the D66 local rail.
+const {mountedDom} = await import('./helpers/mounted-dom.mjs');
+const {createScope} = await import('../../web/js/shared/toolkit/core.js');
+const {createRequire} = await import('node:module');
+const fs = await import('node:fs');
+const require = createRequire(import.meta.url);
+const PngMetadata = require('../../web/js/png-metadata.js'), ComfyMetadata = require('../../web/js/comfy-metadata.js');
+const {raw:pngRaw, ihdr, idat, iend, tEXt} = await import('./helpers/png-bytes.mjs');
+const LOCAL_PROMPT = '{"3":{"class_type":"KSampler","inputs":{"seed":7,"steps":20,"cfg":8.0,"sampler_name":"euler","scheduler":"normal","denoise":1.0,"model":["4",0],"positive":["6",0],"negative":["7",0],"latent_image":["5",0]}},"4":{"class_type":"CheckpointLoaderSimple","inputs":{"ckpt_name":"synthetic-v1.safetensors"}},"5":{"class_type":"EmptyLatentImage","inputs":{"width":512,"height":512,"batch_size":1}},"6":{"class_type":"CLIPTextEncode","inputs":{"text":"a red fox in snow, detailed fur","clip":["4",1]}},"7":{"class_type":"CLIPTextEncode","inputs":{"text":"blurry, lowres","clip":["4",1]}}}';
+const LOCAL_URL = 'blob:http://localhost/11111111-2222-3333-4444-555555555555';
+const PARITY = new URL('../fixtures/inspection_parity/', import.meta.url);
+
+async function localRecord(file) {
+    const local = await import('../../web/js/workspace/local-inspection.mjs');
+    const previous = {png:globalThis.PngMetadata, comfy:globalThis.ComfyMetadata};
+    globalThis.PngMetadata = PngMetadata; globalThis.ComfyMetadata = ComfyMetadata;
+    try {
+        const classification = PngMetadata.classifyPrefix(new Uint8Array(await file.slice(0, 32).arrayBuffer()));
+        const handle = local.createLocalFileHandle({file, url:LOCAL_URL, classification});
+        return local.localFileAdapter.toRecord(await local.localFileAdapter.read(handle), handle, ComfyMetadata.extractGenerationFacts);
+    } finally {
+        if (previous.png === undefined) delete globalThis.PngMetadata; else globalThis.PngMetadata = previous.png;
+        if (previous.comfy === undefined) delete globalThis.ComfyMetadata; else globalThis.ComfyMetadata = previous.comfy;
+    }
+}
+const localPng = name => new File([pngRaw(ihdr(640, 480), idat(), tEXt('prompt', LOCAL_PROMPT), iend())], name, {type:'image/png', lastModified:1_700_000_000_000});
+function renderFull(record) {
+    const f = mountedDom(), scope = createScope();
+    const forbidden = new Proxy({}, {get(_, key) {assert.fail(`api.${String(key)} touched by a local record`);}});
+    const view = mountFileInspector(f.container, {api:forbidden, sender:{open() {}}, parentScope:scope, variant:'full'});
+    view.setState({loading:false, error:false, record});
+    const texts = predicate => f.walk(f.container, predicate).map(node => node.textContent);
+    return {f, texts, done() {view.dispose(); scope.dispose(); f.restore();}};
+}
+const {mountFileInspector} = await load();
+
+test('local record renders local provenance', async () => {
+    const record = await localRecord(localPng('Fox Render.png'));
+    const {f, texts, done} = renderFull(record);
+    try {
+        const section = f.walk(f.container, n => n.tagName === 'details' && n.children[0]?.textContent === 'File & provenance')[0];
+        assert.ok(section, 'the full variant has File & provenance');
+        const lines = f.walk(section, n => n.tagName === 'p').map(n => n.textContent);
+        assert.equal(lines[0], 'Selected local file · read in this browser');
+        assert.ok(lines.includes('Local file; no saved library association was checked.'));
+        assert.ok(!lines.some(line => /historical bytes|saved positive prompt|Saved association/.test(line)));
+        assert.deepEqual(f.walk(section, n => n.tagName === 'dt').map(n => n.textContent), ['Source', 'Size', 'Dimensions', 'Format', 'Media type', 'Modified']);
+        const values = Object.fromEntries(f.walk(section, n => n.tagName === 'dl')[0].children.map(row => [row.children[0].textContent, row.children[1].textContent]));
+        assert.equal(values.Source, 'Selected local file');
+        assert.equal(values.Dimensions, '640 × 480');
+        assert.equal(values.Format, 'PNG');
+        assert.equal(values['Media type'], 'image');
+        assert.equal(texts(n => n.tagName === 'button' && /Show .* in folder|Show in folder/.test(n.textContent)).length, 0);
+        assert.equal(f.walk(f.container, n => n.tagName === 'button' && n.textContent.includes('Prompt history')).length, 0);
+        const original = f.walk(section, n => n.tagName === 'a' && n.textContent === 'Download original')[0];
+        assert.ok(original, 'Download original is present');
+        assert.equal(original.href, LOCAL_URL);
+        assert.equal(original.download, 'Fox Render.png');
+        // The heading names the file itself; no library title replaces it.
+        assert.equal(f.walk(f.container, n => n.tagName === 'h2')[0].textContent, 'Fox Render.png');
+    } finally { done(); }
+});
+
+test('local record shows no image-tag chips', async () => {
+    const record = await localRecord(localPng('a.png'));
+    assert.equal(record.library.status, 'unavailable');
+    // A local payload carries no image_tags facet (#281), so the record has none and only linked chips could show.
+    assert.equal(record.imageTags, null);
+    const {inspectorTagChips} = await load();
+    assert.deepEqual(inspectorTagChips(record, {filterable:true}), []);
+    const {f, done} = renderFull(record);
+    try {
+        // Only the format chip and the D21 evidence badge: no category, saved tag or image-tag chips.
+        const chips = f.walk(f.container, n => /(^| )chip( |$)/.test(n.className ?? '')).map(n => n.textContent);
+        assert.deepEqual(chips, ['PNG', 'Workflow inferred']);
+        assert.equal(f.walk(f.container, n => n.tagName === 'button' && /^Tag/.test(n.textContent)).length, 0);
+    } finally { done(); }
+});
+
+test('legacy fill applies to local records', async () => {
+    // f09: the server's inspection is ambiguous; the local record shows the legacy parse, labelled as inferred.
+    const ambiguous = await localRecord(new File([fs.readFileSync(new URL('f09.png', PARITY))], 'f09.png'));
+    const graphs = {prompt:ambiguous.metadata.prompt_graph.value, workflow:ambiguous.metadata.workflow_graph.status === 'parsed' ? ambiguous.metadata.workflow_graph.value : null};
+    const legacy = ComfyMetadata.extractGenerationParams(graphs);
+    assert.deepEqual(ambiguous.prompts.positive, {status:'resolved', text:legacy.positivePrompt, source:'graph-inferred'});
+    assert.deepEqual(ambiguous.prompts.negative, {status:'resolved', text:legacy.negativePrompt, source:'graph-inferred'});
+    assert.equal(ambiguous.prompts.positive.text, 'a red fox in snow, detailed fur');
+    const view = renderFull(ambiguous);
+    try {
+        assert.deepEqual(view.texts(n => n.className === 'chip blue'), ['Workflow inferred']);
+        assert.ok(view.texts(n => n.tagName === 'p').includes('Prompt evidence: workflow inferred'));
+    } finally { view.done(); }
+    // f01b: the legacy parse would read the positive text through ConditioningZeroOut; the guard shows the zeroed negative.
+    const zeroed = await localRecord(new File([fs.readFileSync(new URL('f01b.png', PARITY))], 'f01b.png'));
+    assert.deepEqual(zeroed.prompts.negative, {status:'resolved', text:'', source:'zeroed-conditioning'});
+    assert.notEqual(zeroed.prompts.positive.text, '');
+});
+
+// #249 PR C Task C3 (D88): one chip row, the file's current image tags first, then D21's linked tags not already shown.
+function tagged(imageTags, library = {status:'linked', tags:['Minimal', 'warm_light', 'editorial'], tags_scope:'positive'}) {
+    return {...record(), imageTags, library};
+}
+test('renders current image tags before linked tags without duplicates', async () => {
+    const {inspectorTagChips} = await load();
+    assert.equal(typeof inspectorTagChips, 'function', 'inspectorTagChips is exported');
+    assert.deepEqual(inspectorTagChips(tagged({state:'current', tags:['dunes', 'minimal']}), {filterable:true}),
+        [{name:'dunes', filter:true}, {name:'minimal', filter:true}, {name:'warm_light', filter:true}, {name:'editorial', filter:true}]);
+    // D21's rule still decides the linked chips: a recipe's own tags stay plain, an image tag stays a filter.
+    assert.deepEqual(inspectorTagChips(tagged({state:'current', tags:['Editorial']}, {status:'linked', tags:['editorial', 'cover'], tags_scope:'pair'}), {filterable:true}),
+        [{name:'Editorial', filter:true}, {name:'cover', filter:false}]);
+    // An unlinked file shows only its own tags; a facet-less record (history, local) only the linked ones.
+    assert.deepEqual(inspectorTagChips(tagged({state:'current', tags:['loose']}, {status:'none', tags:[], tags_scope:null}), {filterable:true}), [{name:'loose', filter:true}]);
+    assert.deepEqual(inspectorTagChips(tagged(null), {filterable:true}).map(chip => chip.name), ['Minimal', 'warm_light', 'editorial']);
+    assert.deepEqual(inspectorTagChips(tagged({state:'current', tags:[]}, {status:'ambiguous', tags:['x'], tags_scope:'positive'}), {filterable:true}), []);
+});
+test('image tag chips filter in the panel and are plain in the viewer', async () => {
+    const {inspectorTagChips} = await load();
+    const source = tagged({state:'current', tags:['dunes']});
+    assert.deepEqual(inspectorTagChips(source, {filterable:true}).map(chip => chip.filter), [true, true, true, true]);
+    assert.deepEqual(inspectorTagChips(source, {filterable:false}).map(chip => chip.filter), [false, false, false, false]);
+});
+test('none and unavailable render no image chips', async () => {
+    const {inspectorTagChips} = await load();
+    for (const state of ['none', 'unavailable']) {
+        assert.deepEqual(inspectorTagChips(tagged({state, tags:[]}), {filterable:true}).map(chip => chip.name), ['Minimal', 'warm_light', 'editorial']);
+        assert.deepEqual(inspectorTagChips(tagged({state, tags:[]}, {status:'none', tags:[], tags_scope:null}), {filterable:true}), []);
+    }
+});

tests/js/workspace-image-layout.test.js

@@ -149,3 +149,15 @@ test('a narrow gallery caps the concept columns at the smallest readable card',
     }
     assert.equal(layoutImages([{}], 990, 'list', {columns:3}).columns, 1);
 });
+
+test('the card info stacks below the narrowest bounded card, a list row beside its art too (D31)', async () => {
+    const {stacksCardInfo} = await source;
+    assert.equal(typeof stacksCardInfo, 'function', 'stacksCardInfo is not implemented');
+    assert.equal(stacksCardInfo(119, 'grid'), true);
+    assert.equal(stacksCardInfo(120, 'grid'), false);
+    assert.equal(stacksCardInfo(119, 'masonry'), true);
+    // A list row's info is what its art (160px, at most 45%) leaves: 195px at 200% zoom on a phone leaves 107px.
+    assert.equal(stacksCardInfo(195, 'list'), true);
+    assert.equal(stacksCardInfo(280, 'list'), false);
+    assert.equal(stacksCardInfo(358, 'list'), false);
+});

tests/js/workspace-image-tagging-state.test.js

@@ -0,0 +1,769 @@
+// Run with: node --test tests/js/workspace-image-tagging-state.test.js
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createApiClient } = require('../../web/js/api-client.js');
+
+// Only an absent module is tolerated, so RED is an assertion failure, not a crash.
+const source = import('../../web/js/workspace/image-tagging-state.mjs').catch(error => {
+    if (error.code !== 'ERR_MODULE_NOT_FOUND') throw error;
+    return {};
+});
+async function load() {
+    const module = await source;
+    assert.equal(typeof module.createImageTaggingController, 'function', 'image-tagging-state.mjs is not implemented');
+    return module;
+}
+
+const EPOCH = '11111111-1111-4111-8111-111111111111';
+const SCOPE = 'c'.repeat(64);
+const SHA = 'd'.repeat(64);
+const TOKEN = 'capture-token_1';
+const TOKEN2 = 'capture-token_2';
+const TARGET = Object.freeze({ root_index: 0, root_scope: SCOPE, path: 'dunes/dunes_00001.png' });
+const OBSERVE = '/prompt_manager/image-annotations/observe';
+const SUGGEST = '/prompt_manager/image-annotations/suggest';
+const TAGS = '/prompt_manager/image-annotations/tags';
+const MODELS = '/prompt_manager/autotag/models';
+const CAPTURE = '/prompt_manager/image-annotations/capture/';
+const DEFAULT_PROMPT = 'Generate only comma-separated Danbooru tags (lowercase_underscores, no spaces).';
+
+const flush = () => new Promise(resolve => setImmediate(resolve));
+async function settle(times = 8) { for (let i = 0; i < times; i++) await flush(); }
+function deferred() {
+    let resolve, reject;
+    const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+    return { promise, resolve, reject };
+}
+function response(status, body) {
+    return { ok: status >= 200 && status < 300, status, statusText: `Status ${status}`, json: async () => body };
+}
+const fail = (status, code, error = `failure ${code}`, extra = {}) => response(status, { success: false, code, error, ...extra });
+
+function captureInfo(overrides = {}) {
+    return {
+        token: TOKEN, expires_at: '2026-10-22T12:00:00+00:00', preview_url: CAPTURE + (overrides.token || TOKEN),
+        sha256: SHA, size: 1234, width: 832, height: 1216, media_type: 'image',
+        generate: { supported: true, reason: null }, ...overrides,
+    };
+}
+function observed(overrides = {}, capture = {}) {
+    return {
+        success: true, library_epoch: EPOCH, target: { ...TARGET }, capture: captureInfo(capture),
+        title: 'Desert pavilion', filename: 'dunes_00001.png', tags: ['Minimal', 'warm_light'], tag_revision: 3,
+        ...overrides,
+    };
+}
+const models = (overrides = {}) => ({
+    success: true, models: { 'wd14-swinv2': { downloaded: true } }, default_prompt: DEFAULT_PROMPT,
+    wd14_general_threshold: 0.35, wd14_character_threshold: 0.85, suggestion_limit: 10, ...overrides,
+});
+const SANDSTONE = [
+    { name: 'minimal', confidence: 0.99 }, { name: 'editorial', confidence: 0.97 },
+    { name: 'sandstone', confidence: 0.981 }, { name: 'Editorial', confidence: 0.5 },
+];
+const suggested = (rows = SANDSTONE, overrides = {}) => ({ success: true, model_type: 'wd14-swinv2', options: {}, suggestions: rows, ...overrides });
+const receipt = (tags, overrides = {}) => ({ success: true, library_epoch: EPOCH, sha256: SHA, tags, tag_revision: 4, replayed: false, ...overrides });
+
+/** Real createApiClient over a fetch whose answers come from routes[METHOD URL](call). */
+function harness(routes = {}) {
+    const calls = [];
+    const fetch = (url, init = {}) => {
+        const call = { url, method: init.method, init, body: init.body === undefined ? undefined : JSON.parse(init.body), aborted: false, signal: init.signal };
+        calls.push(call);
+        return new Promise((resolve, reject) => {
+            init.signal?.addEventListener('abort', () => {
+                call.aborted = true;
+                reject(new DOMException('The operation was aborted.', 'AbortError'));
+            });
+            const key = `${call.method} ${url.startsWith(CAPTURE) ? CAPTURE : url}`;
+            const route = routes[key];
+            Promise.resolve().then(() => {
+                if (!route) return response(200, { success: true });
+                return route(call);
+            }).then(resolve, reject);
+        });
+    };
+    return {
+        api: createApiClient(fetch), calls,
+        of: (method, url) => calls.filter(call => call.method === method && (url === CAPTURE ? call.url.startsWith(CAPTURE) : call.url === url)),
+    };
+}
+function defaultRoutes(extra = {}) {
+    return {
+        [`POST ${OBSERVE}`]: () => response(200, observed()),
+        [`GET ${MODELS}`]: () => response(200, models()),
+        [`POST ${SUGGEST}`]: () => response(200, suggested()),
+        [`PUT ${TAGS}`]: call => response(200, receipt(call.body.tags)),
+        ...extra,
+    };
+}
+async function opened(routes, options = {}) {
+    const { createImageTaggingController } = await load();
+    const h = harness(defaultRoutes(routes));
+    const c = createImageTaggingController({ api: h.api, target: TARGET, source: 'images', ...options });
+    await c.open();
+    await settle();
+    return { c, h };
+}
+
+test('MODEL_OPTIONS lists legacy engines in mock order with D84 labels', async () => {
+    const { MODEL_OPTIONS } = await load();
+    assert.deepEqual(MODEL_OPTIONS.map(option => [option.id, option.label]), [
+        ['wd14-swinv2', 'WD14 SwinV2 · ~400 MB'],
+        ['wd14-vit', 'WD14 ViT · ~400 MB'],
+        ['gguf', 'GGUF JoyCaption (Recommended) · ~4.5 GB'],
+        ['hf', 'HuggingFace JoyCaption · ~16 GB'],
+    ]);
+    assert.ok(Object.isFrozen(MODEL_OPTIONS) && Object.isFrozen(MODEL_OPTIONS[0]));
+});
+
+test('dedupeTags trims, drops blanks and keeps the first spelling case-insensitively', async () => {
+    const { dedupeTags, parseManualTags } = await load();
+    const input = [' Minimal ', 'minimal', '', 'warm_light', 'WARM_LIGHT', 7, 'dune'];
+    assert.deepEqual(dedupeTags(input), ['Minimal', 'warm_light', 'dune']);
+    assert.deepEqual(input[0], ' Minimal ', 'input is not mutated');
+    assert.deepEqual(dedupeTags(undefined), []);
+    assert.deepEqual(parseManualTags(' a, ,B , b,c '), ['a', 'B', 'c']);
+    assert.deepEqual(parseManualTags(null), []);
+});
+
+test('the controller rejects a malformed target, source or api', async () => {
+    const { createImageTaggingController } = await load();
+    const { api } = harness();
+    assert.throws(() => createImageTaggingController({ api, target: { ...TARGET, root_index: true } }), TypeError);
+    assert.throws(() => createImageTaggingController({ api, target: { ...TARGET, root_scope: 'x' } }), TypeError);
+    assert.throws(() => createImageTaggingController({ api, target: { ...TARGET, path: '' } }), TypeError);
+    assert.throws(() => createImageTaggingController({ api, target: TARGET, source: 'elsewhere' }), TypeError);
+    assert.throws(() => createImageTaggingController({ api: {}, target: TARGET }), TypeError);
+    assert.throws(() => createImageTaggingController(), TypeError);
+});
+
+test('opens with saved tags joined by comma-space', async () => {
+    const { createImageTaggingController } = await load();
+    const h = harness(defaultRoutes());
+    const c = createImageTaggingController({ api: h.api, target: TARGET, source: 'images' });
+    const seen = [];
+    const unsubscribe = c.subscribe(state => seen.push(state.phase));
+    assert.equal(c.state.phase, 'observing');
+    const pending = c.open();
+    assert.equal(c.state.phase, 'observing');
+    await pending;
+    await settle();
+    assert.equal(c.state.phase, 'ready');
+    assert.equal(c.state.manual, 'Minimal, warm_light');
+    assert.deepEqual(c.state.savedTags, ['Minimal', 'warm_light']);
+    assert.equal(c.state.image.filename, 'dunes_00001.png');
+    assert.equal(c.state.image.title, 'Desert pavilion');
+    assert.equal(c.state.image.dimensions, '832 × 1216');
+    assert.equal(c.state.image.previewUrl, CAPTURE + TOKEN);
+    assert.equal(c.state.model, 'wd14-swinv2');
+    assert.equal(c.state.countText, 'Not generated');
+    assert.equal(c.state.primaryLabel, 'Save manual tags');
+    assert.equal(c.state.suggestionsText, 'Generate suggestions with the selected model before approving.');
+    assert.equal(c.state.showScopeNote, false);
+    assert.equal(c.state.canSave, true);
+    assert.equal(c.state.canGenerate, true);
+    assert.ok(Object.isFrozen(c.state));
+    assert.deepEqual(h.of('POST', OBSERVE)[0].body, { target: { ...TARGET } });
+    assert.ok(seen.includes('ready'));
+    unsubscribe();
+    c.setManual('x');
+    assert.equal(seen.at(-1), 'ready', 'an unsubscribed listener is not called');
+    assert.throws(() => c.subscribe('nope'), TypeError);
+});
+
+test('an image without known dimensions shows none and an unseen file starts empty', async () => {
+    const { c } = await opened({
+        [`POST ${OBSERVE}`]: () => response(200, observed({ tags: [], tag_revision: 0, title: null }, { width: null, height: null })),
+    });
+    assert.equal(c.state.image.dimensions, null);
+    assert.equal(c.state.manual, '');
+    assert.equal(c.state.image.title, null);
+});
+
+test('instructions default to the server prompt', async () => {
+    const { c } = await opened({
+        [`GET ${MODELS}`]: () => response(200, models({ suggestion_limit: 7, wd14_general_threshold: 0.5 })),
+    });
+    assert.equal(c.state.options.instructions, DEFAULT_PROMPT);
+    assert.equal(c.state.options.suggestion_limit, 7);
+    assert.equal(c.state.options.general_threshold, 0.5);
+    assert.equal(c.state.options.character_threshold, 0.85);
+    c.setModel('gguf');
+    assert.equal(c.state.options.instructions, DEFAULT_PROMPT);
+    c.setOption('instructions', 'only colours');
+    c.setModel('hf');
+    assert.equal(c.state.options.instructions, DEFAULT_PROMPT, 'a model change re-renders the defaults like the mock');
+    assert.equal(c.state.options.suggestion_limit, 7, 'the suggestion count survives a model change');
+});
+
+test('an unreadable or malformed models read falls back to the documented defaults', async () => {
+    for (const route of [() => fail(500, null), () => response(200, models({ default_prompt: 4, suggestion_limit: 0, wd14_general_threshold: 2, wd14_character_threshold: 'x' }))]) {
+        const { c } = await opened({ [`GET ${MODELS}`]: route });
+        assert.equal(c.state.phase, 'ready');
+        assert.deepEqual({ ...c.state.options }, { general_threshold: 0.35, character_threshold: 0.85, instructions: '', suggestion_limit: 10 });
+    }
+});
+
+test('observe failures and malformed answers end in observe-error and retry observes again', async () => {
+    const { createImageTaggingController } = await load();
+    let answer = () => fail(409, 'source-changed', 'The source changed. Refresh the image collection before tagging this file.');
+    const h = harness(defaultRoutes({ [`POST ${OBSERVE}`]: () => answer() }));
+    const c = createImageTaggingController({ api: h.api, target: TARGET });
+    await c.open();
+    assert.equal(c.state.phase, 'observe-error');
+    assert.equal(c.state.statusText, 'The source changed. Refresh the image collection before tagging this file.');
+    assert.equal(c.state.canSave, false);
+    assert.equal(c.state.canGenerate, false);
+    assert.equal(c.state.canRetry, true);
+    answer = () => response(200, observed({ tag_revision: -1 }));
+    await c.retry();
+    assert.equal(c.state.phase, 'observe-error');
+    assert.equal(c.state.statusText, 'The image could not be opened for tagging.');
+    assert.equal(h.of('DELETE', CAPTURE).length, 1, 'a malformed answer still releases its capture');
+    answer = () => Promise.reject(new TypeError('Failed to fetch'));
+    await c.retry();
+    assert.equal(c.state.statusText, 'The image could not be opened for tagging.');
+    answer = () => response(200, observed());
+    await c.retry();
+    await settle();
+    assert.equal(c.state.phase, 'ready');
+    assert.equal(h.of('POST', OBSERVE).length, 4);
+});
+
+test('model change clears suggestions count and status but keeps manual', async () => {
+    const { c } = await opened();
+    c.setManual('Minimal, dune');
+    await c.generate();
+    assert.equal(c.state.countText, '3 suggestions');
+    c.setModel('wd14-vit');
+    assert.deepEqual(c.state.suggestions, []);
+    assert.equal(c.state.countText, 'Not generated');
+    assert.equal(c.state.statusText, '');
+    assert.equal(c.state.suggestionsText, 'Generate suggestions with the selected model before approving.');
+    assert.equal(c.state.manual, 'Minimal, dune');
+    assert.equal(c.state.model, 'wd14-vit');
+    c.setModel('wd14-vit');
+    assert.equal(c.state.model, 'wd14-vit');
+    assert.throws(() => c.setModel('ollama'), TypeError);
+    assert.throws(() => c.setOption('model', 1), TypeError);
+});
+
+test('generate sends the model options and stages scored chips', async () => {
+    const { c, h } = await opened();
+    c.setOption('general_threshold', '0.4');
+    c.setOption('suggestion_limit', '3');
+    assert.equal(await c.generate(), true);
+    const sent = h.of('POST', SUGGEST)[0].body;
+    assert.deepEqual(sent, {
+        target: { ...TARGET }, capture_token: TOKEN, expected_epoch: EPOCH, model_type: 'wd14-swinv2',
+        options: { general_threshold: 0.4, character_threshold: 0.85, suggestion_limit: 3 },
+    });
+    assert.deepEqual(c.state.suggestions.map(row => [row.name, row.label]), [['minimal', '99%'], ['editorial', '97%'], ['sandstone', '98%']]);
+    assert.equal(c.state.statusText, 'Suggestions from WD14 SwinV2 · ~400 MB. Approve tags to save.');
+    assert.equal(c.state.suggestionsText, '');
+    c.setModel('gguf');
+    await c.generate();
+    assert.deepEqual(h.of('POST', SUGGEST)[1].body.options, { instructions: DEFAULT_PROMPT, suggestion_limit: 3 });
+});
+
+test('language models label chips Suggested and the count is capped at the requested limit', async () => {
+    const rows = Array.from({ length: 12 }, (_, i) => ({ name: `tag${i}`, confidence: null }));
+    const { c } = await opened({ [`POST ${SUGGEST}`]: () => response(200, suggested(rows, { model_type: 'gguf' })) });
+    c.setModel('gguf');
+    await c.generate();
+    assert.equal(c.state.suggestions.length, 10);
+    assert.ok(c.state.suggestions.every(row => row.label === 'Suggested' && row.confidence === null));
+    assert.equal(c.state.countText, '10 suggestions');
+});
+
+test('an empty result shows the threshold copy and a malformed one is a generate error', async () => {
+    let answer = () => response(200, suggested([]));
+    const { c } = await opened({ [`POST ${SUGGEST}`]: () => answer() });
+    await c.generate();
+    assert.equal(c.state.suggestionsText, 'No suggestions met this threshold. Adjust it or enter tags manually.');
+    assert.equal(c.state.countText, '0 suggestions');
+    assert.equal(c.state.primaryLabel, 'Approve selected tags');
+    answer = () => response(200, suggested([{ name: 4, confidence: 2 }]));
+    await c.generate();
+    assert.equal(c.state.phase, 'generate-error');
+    assert.equal(c.state.statusText, 'Auto-tagging failed. Check server logs for details.');
+    answer = () => response(200, suggested([{ name: 'one', confidence: 1 }]));
+    assert.equal(await c.retry(), true, 'retry after a generate error generates again');
+    assert.equal(c.state.countText, '1 suggestion');
+    assert.equal(c.state.suggestions[0].label, '100%');
+});
+
+test('invalid options send nothing', async () => {
+    const { c, h } = await opened();
+    const { optionError } = await load();
+    for (const [key, value] of [['general_threshold', '1.5'], ['general_threshold', ''], ['character_threshold', 'abc'], ['suggestion_limit', '0'], ['suggestion_limit', '2.5'], ['suggestion_limit', '101']]) {
+        c.setOption('general_threshold', 0.35);
+        c.setOption('character_threshold', 0.85);
+        c.setOption('suggestion_limit', 10);
+        c.setOption(key, value);
+        assert.equal(await c.generate(), false, `${key}=${value}`);
+        assert.equal(optionError(c.state.model, c.state.options).field, key);
+    }
+    c.setModel('gguf');
+    c.setOption('instructions', '   ');
+    assert.equal(await c.generate(), false);
+    c.setOption('instructions', 'x'.repeat(4001));
+    assert.equal(await c.generate(), false);
+    assert.equal(optionError('gguf', c.state.options).field, 'instructions');
+    assert.equal(h.of('POST', SUGGEST).length, 0);
+    assert.equal(optionError('wd14-vit', { general_threshold: 0, character_threshold: 1, suggestion_limit: 100 }), null);
+});
+
+test('late generation for an old serial, closed or expired dialog is ignored', async () => {
+    const pending = [];
+    const { c, h } = await opened({ [`POST ${SUGGEST}`]: () => { const d = deferred(); pending.push(d); return d.promise; } });
+    const first = c.generate();
+    assert.equal(c.state.phase, 'generating');
+    assert.equal(c.state.statusText, 'Generating suggestions…');
+    assert.equal(c.state.canSave, false);
+    c.setModel('wd14-vit');
+    assert.equal(c.state.phase, 'ready');
+    assert.equal(h.of('POST', SUGGEST)[0].aborted, true);
+    await settle();
+    pending[0].resolve(response(200, suggested()));
+    assert.equal(await first, false);
+    assert.equal(c.state.phase, 'ready', 'the superseded request neither stages chips nor reports its abort');
+    assert.equal(c.state.statusText, '');
+    assert.deepEqual(c.state.suggestions, []);
+    assert.equal(c.state.countText, 'Not generated');
+
+    const second = c.generate();
+    c.cancel();
+    await settle();
+    pending[1].resolve(response(200, suggested()));
+    assert.equal(await second, false);
+    assert.deepEqual(c.state.suggestions, []);
+    assert.equal(c.state.closed, true);
+    assert.equal(await c.generate(), false, 'a closed dialog never generates');
+
+    const expired = await opened({ [`POST ${SUGGEST}`]: () => fail(409, 'capture-expired', 'The preview expired. Open the Tag dialog again.') });
+    await expired.c.generate();
+    assert.equal(expired.c.state.phase, 'capture-expired');
+    assert.equal(expired.c.state.canSave, false);
+    assert.equal(expired.c.state.canGenerate, false);
+});
+
+test('a reopen while observing ignores the older observation and releases its capture', async () => {
+    const { createImageTaggingController } = await load();
+    const answers = [deferred(), deferred()];
+    let n = 0;
+    const h = harness(defaultRoutes({ [`POST ${OBSERVE}`]: () => answers[n++].promise }));
+    const c = createImageTaggingController({ api: h.api, target: TARGET });
+    const one = c.open();
+    const two = c.open();
+    answers[1].resolve(response(200, observed({}, { token: TOKEN2 })));
+    await two;
+    answers[0].resolve(response(200, observed()));
+    await one;
+    await settle();
+    assert.equal(c.state.image.previewUrl, CAPTURE + TOKEN2);
+    assert.deepEqual(h.of('DELETE', CAPTURE).map(call => call.url), [CAPTURE + TOKEN]);
+    c.dispose();
+    assert.deepEqual(h.of('DELETE', CAPTURE).map(call => call.url), [CAPTURE + TOKEN, CAPTURE + TOKEN2]);
+});
+
+test('primary label toggles Save manual tags / Approve selected tags', async () => {
+    const { c } = await opened();
+    assert.equal(c.state.primaryLabel, 'Save manual tags');
+    await c.generate();
+    assert.equal(c.state.primaryLabel, 'Approve selected tags'); c.setModel('wd14-vit'); assert.equal(c.state.primaryLabel, 'Save manual tags');
+    assert.equal(c.state.countText, 'Not generated');
+});
+
+test('remove drops one chip and the last removal shows the all-removed copy', async () => {
+    const { c } = await opened();
+    await c.generate();
+    c.remove('editorial');
+    assert.deepEqual(c.state.suggestions.map(row => row.name), ['minimal', 'sandstone']);
+    assert.equal(c.state.countText, '2 suggestions');
+    c.remove('missing');
+    assert.equal(c.state.suggestions.length, 2);
+    c.remove('minimal');
+    c.remove('sandstone');
+    assert.deepEqual(c.state.suggestions, []);
+    assert.equal(c.state.suggestionsText, 'All suggestions removed. Generate again or enter tags manually.');
+    assert.equal(c.state.primaryLabel, 'Approve selected tags');
+});
+
+test('save sends manual then remaining chips deduplicated case-insensitively keeping the manual spelling', async () => {
+    const { createImageTaggingController } = await load();
+    const h = harness(defaultRoutes({
+        [`POST ${SUGGEST}`]: () => response(200, suggested([
+            { name: 'minimal', confidence: 0.99 }, { name: 'editorial', confidence: 0.97 },
+            { name: 'sandstone', confidence: 0.96 }, { name: 'desert', confidence: 0.9 },
+        ])),
+    }));
+    const c = createImageTaggingController({ api: h.api, target: TARGET, source: 'review' });
+    await c.open();
+    await settle();
+    assert.equal(c.state.showScopeNote, true);
+    await c.generate();
+    c.remove('desert');
+    assert.equal(c.state.primaryLabel, 'Approve selected tags');
+    assert.equal(await c.save(), true);
+    const sent = h.of('PUT', TAGS)[0].body;
+    assert.deepEqual(sent.tags, ['Minimal', 'warm_light', 'editorial', 'sandstone']); // manual "Minimal", chip "minimal" dropped
+    assert.deepEqual(sent, {
+        target: { ...TARGET }, capture_token: TOKEN, sha256: SHA, expected_epoch: EPOCH,
+        expected_tag_revision: 3, tags: sent.tags,
+    });
+    assert.equal(c.state.phase, 'saved');
+    assert.deepEqual(c.state.savedTags, sent.tags);
+    assert.equal(c.state.tagRevision, 4);
+    assert.equal(c.state.toast, '4 tags saved for dunes_00001.png. Prompt association still awaits review.');
+    assert.equal(c.state.canSave, false);
+    assert.equal(await c.save(), false, 'a saved dialog does not save twice');
+});
+
+test('toast matches the mock with the review suffix', async () => {
+    const { c } = await opened({ [`PUT ${TAGS}`]: () => response(200, receipt(['one'])) });
+    c.setManual('one');
+    await c.save();
+    assert.equal(c.state.toast, '1 tags saved for dunes_00001.png.', 'the mock always says "tags"');
+    const many = await opened({}, { source: 'library' });
+    await many.c.save();
+    assert.equal(many.c.state.toast, '2 tags saved for dunes_00001.png.');
+});
+
+test('empty manual and no chips sends the acknowledged empty set', async () => {
+    const { c, h } = await opened({ [`PUT ${TAGS}`]: () => response(200, receipt([])) });
+    c.setManual('  ,  ');
+    await c.save();
+    assert.deepEqual(h.of('PUT', TAGS)[0].body.tags, []);
+    assert.equal(c.state.toast, '0 tags saved for dunes_00001.png.');
+});
+
+test('conflict keeps draft and exposes current saved tags', async () => {
+    let answer = () => fail(409, 'tag-conflict', 'The tags of this image changed since the dialog opened; review them first.',
+        { tags: ['night', 'rain'], tag_revision: 5 });
+    const { c, h } = await opened({ [`PUT ${TAGS}`]: call => answer(call) });
+    await c.generate();
+    c.setManual('Minimal, dune');
+    await c.save();
+    assert.equal(c.state.phase, 'conflict');
+    assert.deepEqual(c.state.currentTags, ['night', 'rain']);
+    assert.equal(c.state.manual, 'night, rain, Minimal, dune');
+    assert.equal(c.state.suggestions.length, 3);
+    assert.equal(c.state.statusText, 'The tags of this image changed since the dialog opened; review them first. Saved now: night, rain.');
+    assert.equal(c.state.canSave, true);
+    answer = call => response(200, receipt(call.body.tags, { tag_revision: 6 }));
+    await c.save();
+    assert.equal(h.of('PUT', TAGS)[1].body.expected_tag_revision, 5, 'the second save is against the revision the user has seen');
+    assert.equal(c.state.phase, 'saved');
+    assert.equal(c.state.currentTags, null);
+});
+
+test('lost response keeps draft and retry resends the identical body once', async () => {
+    const answers = [() => Promise.reject(new TypeError('Failed to fetch')), () => fail(504, null, 'Gateway Timeout'),
+        () => response(200, { success: true, tags: 'broken' })];
+    for (const lost of answers) {
+        let answer = lost;
+        const { c, h } = await opened({ [`PUT ${TAGS}`]: call => answer(call) });
+        c.setManual('Minimal, dune');
+        await c.save();
+        assert.equal(c.state.phase, 'unknown-outcome');
+        assert.equal(c.state.statusText, 'The save could not be confirmed. Retry sends the same tags again.');
+        assert.equal(c.state.canRetry, true);
+        assert.equal(c.state.canSave, false);
+        assert.equal(c.state.manual, 'Minimal, dune');
+        c.setManual('changed meanwhile');
+        const gate = deferred();
+        answer = call => gate.promise.then(() => response(200, receipt(call.body.tags, { replayed: true })));
+        const retried = c.retry();
+        assert.equal(await c.retry(), false, 'a retry in flight is not sent twice');
+        gate.resolve();
+        assert.equal(await retried, true);
+        const puts = h.of('PUT', TAGS);
+        assert.equal(puts.length, 2);
+        assert.deepEqual(puts[1].body, puts[0].body);
+        assert.equal(c.state.phase, 'saved');
+        assert.equal(await c.retry(), false);
+    }
+});
+
+test('write errors keep the draft and allow another save', async () => {
+    const { c } = await opened({ [`PUT ${TAGS}`]: () => fail(400, 'tag-limit', 'An image can carry at most 100 tags.') });
+    await c.save();
+    assert.equal(c.state.phase, 'write-error');
+    assert.equal(c.state.statusText, 'An image can carry at most 100 tags.');
+    assert.equal(c.state.canSave, true);
+    assert.equal(c.state.canRetry, false);
+    const generic = await opened({ [`PUT ${TAGS}`]: () => fail(500, 'save-failed', '') });
+    await generic.c.save();
+    assert.equal(generic.c.state.phase, 'write-error');
+    assert.equal(generic.c.state.statusText, 'The tags could not be saved.');
+});
+
+test('storage-changed and file-changed disable save until reopen', async () => {
+    for (const [code, phase] of [['storage-changed', 'storage-changed'], ['file-changed', 'file-changed'], ['source-changed', 'file-changed'], ['capture-expired', 'capture-expired']]) {
+        const message = `server says ${code}`;
+        let answer = () => fail(409, code, message);
+        const { c, h } = await opened({ [`PUT ${TAGS}`]: () => answer() });
+        c.setManual('kept draft');
+        await c.save();
+        assert.equal(c.state.phase, phase);
+        assert.equal(c.state.statusText, message);
+        assert.equal(c.state.canSave, false);
+        assert.equal(c.state.canGenerate, false);
+        assert.equal(await c.save(), false);
+        assert.equal(h.of('PUT', TAGS).length, 1);
+        await c.open();
+        await settle();
+        assert.equal(c.state.phase, 'ready', 'reopen observes again');
+        assert.equal(c.state.manual, 'Minimal, warm_light');
+        assert.equal(h.of('DELETE', CAPTURE).length, 1, 'reopen releases the old capture');
+    }
+});
+
+test('video disables generate with the still-image message', async () => {
+    const reason = 'Auto-tagging is available for supported still images only.';
+    const { c, h } = await opened({
+        [`POST ${OBSERVE}`]: () => response(200, observed({ filename: 'clip.mp4' }, { media_type: 'video', generate: { supported: false, reason } })),
+    });
+    assert.equal(c.state.image.mediaType, 'video');
+    assert.equal(c.state.canGenerate, false);
+    assert.equal(c.state.canSave, true);
+    assert.equal(c.state.statusText, reason);
+    c.setModel('gguf');
+    assert.equal(c.state.statusText, reason, 'the reason survives a model change');
+    assert.equal(await c.generate(), false);
+    assert.equal(h.of('POST', SUGGEST).length, 0);
+});
+
+test('model-unavailable and model-busy set the status line only', async () => {
+    let answer = () => response(200, suggested());
+    const { c } = await opened({ [`POST ${SUGGEST}`]: () => answer() });
+    await c.generate();
+    const before = c.state;
+    for (const [code, message] of [
+        ['model-unavailable', 'WD14 SwinV2 is not downloaded. Download it from the legacy Auto-tag page.'],
+        ['model-busy', 'A tagging model is busy with another operation. Try again when it finishes.'],
+        ['unsupported-media', 'Images larger than 4096 px per side or 16,777,216 px are not supported.'],
+    ]) {
+        answer = () => fail(409, code, message);
+        assert.equal(await c.generate(), false);
+        assert.equal(c.state.statusText, message);
+        assert.deepEqual(c.state.suggestions, before.suggestions);
+        assert.equal(c.state.countText, before.countText);
+        assert.equal(c.state.primaryLabel, before.primaryLabel);
+        assert.equal(c.state.manual, before.manual);
+        assert.equal(c.state.canSave, true);
+        assert.equal(c.state.canGenerate, true);
+    }
+    answer = () => Promise.reject(new TypeError('Failed to fetch'));
+    await c.generate();
+    assert.equal(c.state.statusText, 'Auto-tagging failed. Check server logs for details.');
+    c.setModel('wd14-vit');
+    assert.equal(c.state.phase, 'ready');
+});
+
+test('a storage restore during generate requires a reopen', async () => {
+    const { c } = await opened({ [`POST ${SUGGEST}`]: () => fail(409, 'storage-changed', 'Prompt storage was restored; reopen the Tag dialog.') });
+    c.setManual('kept');
+    await c.generate();
+    assert.equal(c.state.phase, 'storage-changed');
+    assert.equal(c.state.canSave, false);
+    assert.equal(c.state.canGenerate, false);
+    await c.retry();
+    await settle();
+    assert.equal(c.state.phase, 'ready', 'Retry observes again (D116)');
+    assert.equal(c.state.manual, 'kept');
+});
+
+test('dispose aborts requests and releases the capture once', async () => {
+    const pending = deferred();
+    const { c, h } = await opened({ [`POST ${SUGGEST}`]: () => pending.promise });
+    const token = TOKEN;
+    const releases = [];
+    const generating = c.generate();
+    let notified = 0;
+    c.subscribe(() => { notified += 1; });
+    c.dispose();
+    c.dispose();
+    c.cancel();
+    for (const call of h.of('DELETE', CAPTURE)) releases.push(decodeURIComponent(call.url.slice(CAPTURE.length)));
+    assert.deepEqual(releases, [token]);
+    assert.equal(h.of('POST', SUGGEST)[0].aborted, true);
+    pending.resolve(response(200, suggested()));
+    assert.equal(await generating, false);
+    assert.equal(notified, 0, 'a disposed controller never notifies');
+    c.setManual('ignored');
+    c.remove('x');
+    assert.notEqual(c.state.manual, 'ignored');
+    assert.equal(await c.save(), false);
+    assert.equal(await c.open(), undefined);
+    assert.equal(h.of('POST', OBSERVE).length, 1);
+});
+
+test('dispose while observing aborts the models read and releases a late capture', async () => {
+    const { createImageTaggingController } = await load();
+    const late = deferred();
+    const h = harness(defaultRoutes({ [`POST ${OBSERVE}`]: () => late.promise, [`GET ${MODELS}`]: () => new Promise(() => {}) }));
+    const c = createImageTaggingController({ api: h.api, target: TARGET });
+    const opening = c.open();
+    c.dispose();
+    assert.equal(h.of('GET', MODELS)[0].aborted, true);
+    late.resolve(response(200, observed()));
+    await opening;
+    await settle();
+    assert.deepEqual(h.of('DELETE', CAPTURE).map(call => call.url), [CAPTURE + TOKEN]);
+    assert.equal(c.state.phase, 'observing');
+});
+
+test('a failing capture release is not reported as a dialog error', async () => {
+    const { c, h } = await opened({ [`DELETE ${CAPTURE}`]: () => Promise.reject(new TypeError('offline')) });
+    c.dispose();
+    await settle();
+    assert.equal(h.of('DELETE', CAPTURE).length, 1);
+    assert.equal(c.state.phase, 'ready');
+});
+
+test('the opening sentence is the concept on-screen copy and the chip hint shows only with chips (D83)', async () => {
+    const { createImageTaggingController } = await load();
+    const h = harness(defaultRoutes());
+    const c = createImageTaggingController({ api: h.api, target: TARGET });
+    assert.equal(c.state.suggestionsText, 'Generate suggestions with the selected model before approving.');
+    assert.equal(c.state.chipHint, '');
+    await c.open();
+    await settle();
+    assert.equal(c.state.suggestionsText, 'Generate suggestions with the selected model before approving.');
+    assert.equal(c.state.chipHint, '');
+    await c.generate();
+    assert.equal(c.state.chipHint, 'Remove anything you do not want to add.');
+    for (const row of [...c.state.suggestions]) c.remove(row.name);
+    assert.equal(c.state.chipHint, '');
+});
+
+test('the option fields follow the server defaults: open and a model change bump the revision, typing does not', async () => {
+    const { c, h } = await opened({
+        [`GET ${MODELS}`]: () => response(200, models({ suggestion_limit: 7, wd14_general_threshold: 0.5, wd14_character_threshold: 0.9 })),
+    });
+    const opening = c.state.optionsRevision;
+    assert.ok(opening > 0, 'the observation that applies the server defaults bumps the revision');
+    assert.deepEqual({ ...c.state.options }, { general_threshold: 0.5, character_threshold: 0.9, instructions: DEFAULT_PROMPT, suggestion_limit: 7 });
+    c.setOption('general_threshold', '0.6');
+    assert.equal(c.state.optionsRevision, opening, 'typing never re-renders the fields');
+    c.setModel('wd14-vit');
+    assert.equal(c.state.optionsRevision, opening + 1);
+    assert.equal(c.state.options.general_threshold, 0.5);
+    await c.generate();
+    assert.deepEqual(h.of('POST', SUGGEST)[0].body.options, { general_threshold: 0.5, character_threshold: 0.9, suggestion_limit: 7 });
+});
+
+test('a conflict shows the current set and merges it ahead of the draft, so a second Save never drops it unseen', async () => {
+    let answer = () => fail(409, 'tag-conflict', 'The tags of this image changed since the dialog opened; review them first.',
+        { tags: ['changed_elsewhere', 'Minimal'], tag_revision: 5 });
+    const { c, h } = await opened({ [`PUT ${TAGS}`]: call => answer(call) });
+    const draft = c.state.draftRevision;
+    c.setManual('minimal, dune');
+    await c.save();
+    assert.equal(c.state.phase, 'conflict');
+    assert.equal(c.state.statusText,
+        'The tags of this image changed since the dialog opened; review them first. Saved now: changed_elsewhere, Minimal.');
+    assert.equal(c.state.manual, 'changed_elsewhere, Minimal, dune', 'the current set leads, the draft follows, repeats dropped');
+    assert.equal(c.state.draftRevision, draft + 1, 'the dialog rewrites its field');
+    answer = call => response(200, receipt(call.body.tags, { tag_revision: 6 }));
+    await c.save();
+    const second = h.of('PUT', TAGS)[1].body;
+    assert.deepEqual(second.tags, ['changed_elsewhere', 'Minimal', 'dune']);
+    assert.equal(second.expected_tag_revision, 5);
+    const empty = await opened({ [`PUT ${TAGS}`]: () => fail(409, 'tag-conflict', 'Changed.', { tags: [], tag_revision: 9 }) });
+    empty.c.setManual('a');
+    await empty.c.save();
+    assert.equal(empty.c.state.statusText, 'Changed. Saved now: no tags.');
+    assert.equal(empty.c.state.manual, 'a');
+});
+
+test('the capture release and the save survive leaving the page (keepalive)', async () => {
+    const { c, h } = await opened();
+    await c.save();
+    assert.equal(h.of('PUT', TAGS)[0].init.keepalive, true);
+    const other = await opened();
+    other.c.dispose();
+    const [release] = other.h.of('DELETE', CAPTURE);
+    assert.equal(release.init.keepalive, true);
+    assert.equal(h.of('POST', OBSERVE)[0].init.keepalive, undefined, 'reads are not kept alive');
+});
+
+test('closing during a save releases the capture only after the PUT settles and reports the outcome', async () => {
+    const outcomes = [];
+    const gate = deferred();
+    const { c, h } = await opened({ [`PUT ${TAGS}`]: call => gate.promise.then(() => response(200, receipt(call.body.tags))) },
+        { onLateSave: outcome => outcomes.push(outcome) });
+    c.setManual('dune');
+    const saving = c.save();
+    c.dispose();
+    await settle();
+    assert.equal(h.of('DELETE', CAPTURE).length, 0, 'the capture stays while its save is in flight');
+    gate.resolve();
+    assert.equal(await saving, true);
+    await settle();
+    const order = h.calls.filter(call => call.method !== 'GET').map(call => call.method);
+    assert.deepEqual(order, ['POST', 'PUT', 'DELETE']);
+    assert.deepEqual(outcomes, [{ saved: true, filename: 'dunes_00001.png', tags: ['dune'], toast: '1 tags saved for dunes_00001.png.' }]);
+    assert.equal(c.state.closed, true);
+
+    for (const [route, message] of [
+        [() => fail(409, 'tag-conflict', 'Changed elsewhere.', { tags: ['x'], tag_revision: 5 }), 'Changed elsewhere.'],
+        [() => fail(400, 'tag-limit', 'Too many.'), 'Too many.'],
+        [() => Promise.reject(new TypeError('Failed to fetch')), 'The tag save could not be confirmed. Open Tag image again to check the saved tags.'],
+    ]) {
+        const late = [];
+        const held = deferred();
+        const run = await opened({ [`PUT ${TAGS}`]: () => held.promise.then(route) }, { onLateSave: outcome => late.push(outcome) });
+        const pending = run.c.save();
+        run.c.cancel();
+        held.resolve();
+        assert.equal(await pending, false);
+        await settle();
+        assert.deepEqual(late, [{ saved: false, message }]);
+        assert.equal(run.h.of('DELETE', CAPTURE).length, 1);
+    }
+    const quiet = await opened();
+    quiet.c.dispose();
+    assert.equal(quiet.h.of('DELETE', CAPTURE).length, 1, 'with no save in flight the capture is released at once');
+    const { createImageTaggingController } = await load();
+    assert.throws(() => createImageTaggingController({ api: h.api, target: TARGET, onLateSave: 'x' }), TypeError);
+});
+
+test('retry after a changed storage, file or expired capture observes again and keeps the draft', async () => {
+    for (const code of ['storage-changed', 'file-changed', 'capture-expired']) {
+        let revision = 3;
+        const { c, h } = await opened({
+            [`PUT ${TAGS}`]: () => fail(409, code, `server says ${code}`),
+            [`POST ${OBSERVE}`]: () => response(200, observed({ tag_revision: revision, tags: revision === 3 ? ['Minimal', 'warm_light'] : ['night'] })),
+        });
+        c.setManual('kept draft');
+        await c.save();
+        assert.equal(c.state.canRetry, true);
+        const draft = c.state.draftRevision;
+        await c.retry();
+        await settle();
+        assert.equal(c.state.phase, 'ready');
+        assert.equal(c.state.manual, 'kept draft', 'an unchanged tag set keeps the draft as typed');
+        assert.equal(c.state.draftRevision, draft + 1);
+        assert.equal(h.of('POST', OBSERVE).length, 2);
+        revision = 4;
+        await c.save();
+        await c.retry();
+        await settle();
+        assert.equal(c.state.manual, 'night, kept draft', 'a set changed meanwhile is shown ahead of the draft');
+        assert.equal(c.state.statusText, 'The tags of this image changed since the dialog opened. Saved now: night.');
+        assert.equal(c.state.tagRevision, 4);
+    }
+    // A first observation that failed has no draft to keep: its retry fills the saved tags.
+    const { createImageTaggingController } = await load();
+    let first = true;
+    const h = harness(defaultRoutes({ [`POST ${OBSERVE}`]: () => (first ? (first = false, fail(500, 'observe-failed')) : response(200, observed())) }));
+    const c = createImageTaggingController({ api: h.api, target: TARGET });
+    await c.open();
+    await c.retry();
+    await settle();
+    assert.equal(c.state.manual, 'Minimal, warm_light');
+});

tests/js/workspace-image-tagging.test.js

@@ -0,0 +1,28 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+// Guarded: before the dialog module exists every test fails on an assertion, not on the import.
+const loaded = await import('../../web/js/workspace/image-tagging.mjs').catch(() => null);
+const module = () => { assert.ok(loaded, 'image-tagging.mjs is not implemented'); return loaded; };
+const SCOPE = 'a'.repeat(64);
+
+test('a listed file gives its tagging target, anything else none', () => {
+    const { imageTarget } = module();
+    assert.deepEqual(imageTarget({ root_index: 1, root_scope: SCOPE, path: 'a/b.png', filename: 'b.png' }),
+        { root_index: 1, root_scope: SCOPE, path: 'a/b.png' });
+    for (const image of [null, {}, { root_index: -1, root_scope: SCOPE, path: 'a.png' }, { root_index: 0, path: 'a.png' },
+        { root_index: 0, root_scope: 'A'.repeat(64), path: 'a.png' }, { root_index: 0, root_scope: SCOPE, path: '' },
+        { root_index: 1.5, root_scope: SCOPE, path: 'a.png' }]) {
+        assert.equal(imageTarget(image), null);
+    }
+});
+
+test('tag save listeners subscribe and unsubscribe once', () => {
+    const { onImageTagsSaved, imageTagsListenerCount } = module();
+    const before = imageTagsListenerCount();
+    const off = onImageTagsSaved(() => {});
+    assert.equal(imageTagsListenerCount(), before + 1);
+    off(); off();
+    assert.equal(imageTagsListenerCount(), before);
+    assert.throws(() => onImageTagsSaved('nope'), TypeError);
+});

tests/js/workspace-images-lifecycle.test.js

@@ -21,3 +21,12 @@ test('Images mounted after its parent is aborted creates no DOM, requests or obs
         for(const [key,descriptor] of originals) {if(descriptor) Object.defineProperty(globalThis,key,descriptor);else delete globalThis[key];}
     }
 });
+
+test('Images mounted after its parent is aborted follows no tag saves', async () => {
+    const tagging = await import('../../web/js/workspace/image-tagging.mjs').catch(() => null);
+    assert.ok(tagging, 'image-tagging.mjs is not implemented');
+    const before = tagging.imageTagsListenerCount();
+    const parent = createScope(); parent.dispose();
+    mountImages({}, {get() { assert.fail('Request started after parent disposal'); }}, parent, {embedded: true, fetchPage() {}}).dispose();
+    assert.equal(tagging.imageTagsListenerCount(), before);
+});

tests/js/workspace-images-state.test.js

@@ -352,3 +352,129 @@ test('selectionLabel counts the selected images as the concept bar does', async
     assert.equal(selectionLabel(2), '2 selected');
     assert.equal(selectionLabel(1234), '1,234 selected');
 });
+
+test('refresh re-reads the loaded range in place and publishes once, replacing the items', async () => {
+    const {createImageStream,imageKey}=await source;const requests=[];const states=[];
+    const stream=createImageStream({api:{get:(url,{signal})=>{const d=deferred();requests.push({...d,url,signal});return d.promise;}},onChange:(s,hint)=>states.push([s,hint]),batchSize:2});
+    assert.equal(typeof stream.refresh,'function','refresh is part of the stream');
+    const first=stream.reset({q:'tag'});requests[0].resolve(page([image('a'),image('b')],5,'c1'));await first;
+    const second=stream.loadMore();requests[1].resolve(page([image('c'),image('d')],5,'c2'));await second;
+    const before=stream.state;const published=states.length;
+    const refresh=stream.refresh();
+    // The current collection stays shown while the re-read runs; Load more waits for it.
+    assert.equal(stream.state,before);assert.equal(states.length,published);
+    assert.equal(await stream.loadMore(),0);assert.equal(requests.length,3);
+    const query=new URL(requests[2].url,'http://local').searchParams;
+    // The loaded range is re-read in pages as large as it (at most 200), not in the listing's batches (M2).
+    assert.equal(query.get('q'),'tag');assert.equal(query.has('cursor'),false);assert.equal(query.get('limit'),'4');
+    requests[2].resolve(page([image('a'),image('new'),image('c')],6,'n1'));
+    await new Promise(resolve=>setImmediate(resolve));
+    const next=new URL(requests[3].url,'http://local').searchParams;
+    assert.equal(next.get('cursor'),'n1');assert.equal(next.get('limit'),'2','the rest, at least one batch');
+    assert.equal(stream.state,before);
+    requests[3].resolve(page([image('d')],6,'n2'));
+    assert.equal(await refresh,4);
+    assert.deepEqual(stream.state.items.map(imageKey),['0:a','0:new','0:c','0:d']);
+    assert.deepEqual([stream.state.total,stream.state.cursor,stream.state.hasMore,stream.state.loaded,stream.state.loading],[6,'n2',true,4,false]);
+    assert.equal(states.length,published+1);assert.deepEqual(states.at(-1)[1],{replaced:true});
+    // Load more continues from the refreshed cursor.
+    const more=stream.loadMore();assert.equal(new URL(requests[4].url,'http://local').searchParams.get('cursor'),'n2');
+    requests[4].resolve(page([image('e')],6));await more;
+    assert.deepEqual(stream.state.items.map(imageKey),['0:a','0:new','0:c','0:d','0:e']);
+});
+
+test('refresh stops early when the result shrank, and a reset or failure leaves the collection as it was', async () => {
+    const {createImageStream,imageKey}=await source;const requests=[];
+    const stream=createImageStream({api:{get:(url,{signal})=>{const d=deferred();requests.push({...d,url,signal});return d.promise;}},batchSize:2});
+    assert.equal(typeof stream.refresh,'function','refresh is part of the stream');
+    const first=stream.reset({tags:['x']});requests[0].resolve(page([image('a'),image('b')],4,'c1'));await first;
+    const shrink=stream.refresh();requests[1].resolve(page([image('b')],1));
+    assert.equal(await shrink,1);assert.deepEqual(stream.state.items.map(imageKey),['0:b']);assert.equal(stream.state.hasMore,false);
+    const before=stream.state;
+    const failing=stream.refresh();requests[2].reject(new Error('offline'));
+    await assert.rejects(failing,/offline/,'a failed re-read is reported to the page');assert.equal(stream.state,before);
+    const stale=stream.refresh();const fresh=stream.reset({tags:['y']});
+    assert.equal(requests[3].signal.aborted,true);
+    requests[4].resolve(page([image('y')]));await fresh;
+    requests[3].resolve(page([image('stale')]));assert.equal(await stale,0);
+    assert.deepEqual(stream.state.items.map(imageKey),['0:y']);
+    stream.dispose();assert.equal(await stream.refresh(),0);
+});
+
+test('a refresh asked while a page loads runs once that page settles (I6)', async () => {
+    const {createImageStream,imageKey}=await source;const requests=[];const states=[];
+    const stream=createImageStream({api:{get:(url,{signal})=>{const d=deferred();requests.push({...d,url,signal});return d.promise;}},onChange:(s,hint)=>states.push(hint),batchSize:2});
+    const first=stream.reset({tags:['x']});requests[0].resolve(page([image('a'),image('b')],4,'c1'));await first;
+    for (const settle of ['resolve','reject']) {
+        const more=stream.loadMore();const sent=requests.length;
+        assert.equal(await stream.refresh(),0,'nothing is read beside the page in flight');
+        assert.equal(await stream.refresh(),0);
+        assert.equal(requests.length,sent);
+        if (settle==='resolve') requests[sent-1].resolve(page([image('c'),image('d')],4,'c2'));
+        else requests[sent-1].reject(new Error('offline'));
+        await more;
+        await new Promise(resolve=>setImmediate(resolve));
+        assert.equal(requests.length,sent+1,'exactly one pending refresh follows');
+        assert.equal(new URL(requests[sent].url,'http://local').searchParams.has('cursor'),false);
+        requests[sent].resolve(page([image('a'),image('b'),image('c'),image('d')],6,'r1'));
+        await new Promise(resolve=>setImmediate(resolve));
+        assert.deepEqual(states.at(-1),{replaced:true});
+        assert.equal(states.filter(hint=>hint?.replaced).length,settle==='resolve'?1:2);
+    }
+    // A reset drops a pending refresh.
+    const more=stream.loadMore();const sent=requests.length;
+    assert.equal(await stream.refresh(),0);
+    const fresh=stream.reset({tags:['y']});
+    requests[sent].resolve(page([image('y')]));await fresh;
+    requests[sent-1].resolve(page([image('late')],1));await more;
+    await new Promise(resolve=>setImmediate(resolve));
+    assert.equal(requests.length,sent+1);assert.deepEqual(stream.state.items.map(imageKey),['0:y']);
+    assert.equal(stream.refreshing,false);
+});
+
+test('refresh reads a long loaded range in at most 200-file pages and exposes refreshing (M2, M3)', async () => {
+    const {createImageStream}=await source;const requests=[];
+    const stream=createImageStream({api:{get:(url,{signal})=>{const d=deferred();requests.push({...d,url,signal});return d.promise;}},batchSize:150});
+    const many=(prefix,n)=>Array.from({length:n},(_,i)=>image(`${prefix}${i}`));
+    const first=stream.reset({q:'x'});requests[0].resolve(page(many('a',150),1000,'c1'));await first;
+    const second=stream.loadMore();requests[1].resolve(page(many('b',150),1000,'c2'));await second;
+    const refresh=stream.refresh();
+    assert.equal(stream.refreshing,true);
+    assert.equal(new URL(requests[2].url,'http://local').searchParams.get('limit'),'200');
+    requests[2].resolve(page(many('r',200),1000,'n1'));
+    await new Promise(resolve=>setImmediate(resolve));
+    assert.equal(new URL(requests[3].url,'http://local').searchParams.get('limit'),'150');
+    requests[3].resolve(page(many('s',150),1000,'n2'));
+    assert.equal(await refresh,350);assert.equal(requests.length,4);
+    assert.equal(stream.refreshing,false);
+});
+
+test('a second refresh supersedes the first, repeats in a re-read are dropped, and dispose abandons one in flight', async () => {
+    const {createImageStream,imageKey}=await source;const requests=[];const states=[];
+    const stream=createImageStream({api:{get:(url,{signal})=>{const d=deferred();requests.push({...d,url,signal});return d.promise;}},onChange:(s,hint)=>states.push(hint),batchSize:2});
+    const first=stream.reset({q:'x'});requests[0].resolve(page([image('a'),image('b')],2));await first;
+    const older=stream.refresh();const newer=stream.refresh();
+    assert.equal(requests[1].signal.aborted,true,'the older re-read is aborted');
+    requests[2].resolve(page([image('b'),image('b'),image('a')],2));
+    assert.equal(await newer,2);
+    requests[1].resolve(page([image('old')],1));assert.equal(await older,0);
+    assert.deepEqual(stream.state.items.map(imageKey),['0:b','0:a']);
+    assert.equal(states.filter(hint=>hint?.replaced).length,1);
+    const pending=stream.refresh();
+    stream.dispose();
+    assert.equal(requests[3].signal.aborted,true);
+    requests[3].resolve(page([image('late')],1));
+    assert.equal(await pending,0);assert.deepEqual(stream.state.items.map(imageKey),['0:b','0:a']);
+});
+
+test('a refresh deferred behind a page load is dropped when the stream is disposed meanwhile', async () => {
+    const {createImageStream}=await source;const requests=[];
+    const stream=createImageStream({api:{get:(url,{signal})=>{const d=deferred();requests.push({...d,url,signal});return d.promise;}},batchSize:2});
+    const first=stream.reset({q:'x'});requests[0].resolve(page([image('a'),image('b')],4,'c1'));await first;
+    const more=stream.loadMore();
+    assert.equal(await stream.refresh(),0);
+    stream.dispose();
+    requests[1].resolve(page([image('c')],4,'c2'));await more;
+    await new Promise(resolve=>setImmediate(resolve));
+    assert.equal(requests.length,2,'no refresh runs after dispose');
+});

tests/js/workspace-inspection-state.test.js

@@ -702,3 +702,126 @@ test('a workflow the legacy parser throws on keeps the server result instead of
     assert.deepEqual(record.prompts.positive, { status: 'resolved', text: 'exact\npositive', source: 'execution' });
     assert.equal(record.prompts.negative.status, 'ambiguous');
 });
+
+// PR L2 Task 4(a): an adapter that reads by itself (the local file adapter) never reaches the API.
+test('controller prefers adapter.read and never touches api', async () => {
+    const createController = contract('createInspectionController');
+    const forbidden = new Proxy({}, { get(_, key) { assert.fail(`api.${String(key)} touched`); } });
+    const reads = [], records = [];
+    const adapter = {
+        validate(item) { if (!item?.key) throw new TypeError('bad'); }, key: item => item.key, scope: () => 'own', inspectionPath: item => `own:${item.key}`,
+        read(item, options) { const pending = {}; reads.push({ item, options, pending }); return new Promise((resolve, reject) => Object.assign(pending, { resolve, reject })); },
+        toRecord(result, item) { records.push([result, item.key]); return { identity: { kind: 'own', key: item.key }, prompts: result.prompts }; },
+    };
+    for (const api of [forbidden, null]) {
+        reads.length = 0; records.length = 0;
+        const controller = createController({ api, adapter, extractFacts: extractGenerationFacts });
+        const first = controller.select({ key: 'a' });
+        assert.equal(reads.length, 1);
+        assert.equal(reads[0].item.key, 'a');
+        assert.ok(reads[0].options.signal instanceof AbortSignal);
+        assert.equal(controller.state.loading, true);
+        const second = controller.select({ key: 'b' });
+        assert.equal(reads[0].options.signal.aborted, true, 'a new selection aborts the previous read');
+        reads[0].pending.resolve({ prompts: { positive: { status: 'resolved', text: 'late' } } });
+        await first;
+        assert.equal(controller.state.record, null, 'a superseded read never publishes');
+        reads[1].pending.resolve({ prompts: { positive: { status: 'resolved', text: 'current' } } });
+        await second;
+        assert.deepEqual(records.map(([, key]) => key), ['b']);
+        assert.equal(controller.state.record.prompts.positive.text, 'current');
+        const retry = controller.retry();
+        reads[2].pending.reject(new Error('read failed'));
+        await retry;
+        assert.equal(controller.state.error, true);
+        assert.equal(controller.state.message, 'Could not read details from this file.');
+        controller.dispose();
+    }
+});
+
+test('rooted and history adapters are unchanged', async () => {
+    const createController = contract('createInspectionController');
+    const { reportedLocationAdapter } = await import('../../web/js/workspace/history-media.mjs');
+    for (const adapter of [module.rootedFileAdapter, reportedLocationAdapter]) {
+        assert.equal(adapter.read, undefined, 'server adapters read through the API');
+        assert.equal(adapter.mediaUrl, undefined, 'server adapters keep the cache-busted original');
+    }
+    const { api, requests } = pendingApi();
+    const rooted = createController({ api, extractFacts: extractGenerationFacts });
+    rooted.select(image());
+    assert.deepEqual(requests.map(request => request.url), [`/prompt_manager/images/inspect/folder/a%20%23%25.png?root=0&root_scope=${scopeA}`]);
+    rooted.dispose();
+    const run = '22222222-2222-2222-2222-222222222222', epoch = '11111111-1111-1111-1111-111111111111';
+    const query = new URLSearchParams({ node: '1', ordinal: '1', epoch, current_scope: scopeA }), base = `/prompt_manager/history/runs/${run}/output/current`;
+    const target = { kind: 'reported-location', location_key: 'c'.repeat(64), history_epoch: epoch, current_scope: scopeA, occurrence: { run_id: run, output_node_id: '1', image_ordinal: 1 },
+        reference: { folder_type: 'output', subfolder: '', filename: 'a.png', path_style: 'posix', root_key: scopeB }, filename: 'a.png', is_video: false,
+        url: `${base}/media?${query}`, thumbnail_url: `${base}/thumbnail?${query}`, inspection_url: `${base}/inspection?${query}` };
+    const history = pendingApi(), recorded = createController({ api: history.api, adapter: reportedLocationAdapter, extractFacts: extractGenerationFacts });
+    recorded.select(target);
+    assert.deepEqual(history.requests.map(request => request.url), [target.inspection_url]);
+    recorded.dispose();
+});
+
+test('fileFor rejects selected-local-file for rooted identity', () => {
+    const entry = image(), data = envelope(entry);
+    data.file = { ...data.file, observation: 'selected-local-file', source_label: 'Selected local file' };
+    assert.throws(() => contract('toInspectionRecord')(data, entry, extractGenerationFacts), /Invalid inspection file/);
+    const project = contract('projectInspectionPayload');
+    assert.throws(() => project(data, { kind: 'rooted-file', key: 'k', path: 'a.png' }, null, extractGenerationFacts), /Invalid inspection file/);
+    assert.throws(() => project(envelope(entry), { kind: 'local-file', key: 'local:1', path: 'a.png' }, null, extractGenerationFacts), /Invalid inspection file/);
+    assert.equal(project(data, { kind: 'local-file', key: 'local:1', path: 'a.png' }, null, extractGenerationFacts).file.observation, 'selected-local-file');
+});
+
+// #249 PR C Task C3: the B3 envelope's `image_tags` facet, the file's own current tags (S1).
+test('image_tags facet is kept exactly and absent stays null', () => {
+    const entry = image(), project = contract('toInspectionRecord');
+    assert.equal(project(envelope(entry), entry, extractGenerationFacts).imageTags, null);
+    for (const facet of [{ state: 'current', tags: ['dunes', 'warm_light'] }, { state: 'current', tags: [] }, { state: 'none', tags: [] }, { state: 'unavailable', tags: [] }]) {
+        const data = { ...envelope(entry), image_tags: facet };
+        const record = project(data, entry, extractGenerationFacts);
+        assert.deepEqual(record.imageTags, facet);
+        assert.notEqual(record.imageTags.tags, facet.tags);
+    }
+    const hundred = Array.from({ length: 100 }, (_, index) => `tag_${index}`);
+    assert.deepEqual(project({ ...envelope(entry), image_tags: { state: 'current', tags: hundred } }, entry, extractGenerationFacts).imageTags.tags, hundred);
+});
+
+test('rejects a malformed image_tags facet', () => {
+    const entry = image();
+    for (const facet of [null, [], 'current', { state: 'current' }, { tags: [] }, { state: 'current', tags: ['a'], extra: 1 },
+        { state: 'stale', tags: [] }, { state: 'none', tags: ['a'] }, { state: 'unavailable', tags: ['a'] }, { state: 'current', tags: 'a' },
+        { state: 'current', tags: [1] }, { state: 'current', tags: [''] }, { state: 'current', tags: [' a'] }, { state: 'current', tags: ['a,b'] },
+        { state: 'current', tags: ['a\nb'] }, { state: 'current', tags: ['x'.repeat(51)] },
+        { state: 'current', tags: Array.from({ length: 101 }, (_, index) => `tag_${index}`) }]) {
+        assert.throws(() => module.toInspectionRecord({ ...envelope(entry), image_tags: facet }, entry, extractGenerationFacts), TypeError, JSON.stringify(facet));
+    }
+    assert.equal(module.toInspectionRecord({ ...envelope(entry), image_tags: { state: 'current', tags: ['é'.repeat(50)] } }, entry, extractGenerationFacts).imageTags.tags[0].length, 50);
+});
+
+test('refresh re-reads the selected file and keeps the shown record until the new read lands', async () => {
+    const { api, requests } = pendingApi(), updates = [];
+    const controller = contract('createInspectionController')({ api, extractFacts: extractGenerationFacts });
+    assert.equal(typeof controller.refresh, 'function', 'refresh is part of the controller');
+    controller.subscribe(state => updates.push(state));
+    const load = controller.select(image()); requests[0].resolve(envelope()); await load;
+    const shown = controller.state, count = updates.length;
+    const refresh = controller.refresh();
+    assert.equal(requests.length, 2);
+    // No loading state is published: the panel keeps its content.
+    assert.equal(controller.state, shown); assert.equal(updates.length, count);
+    requests[1].resolve({ ...envelope(), image_tags: { state: 'current', tags: ['fresh'] } }); await refresh;
+    assert.deepEqual(controller.state.record.imageTags, { state: 'current', tags: ['fresh'] });
+    assert.equal(controller.state.loading, false); assert.equal(updates.length, count + 1);
+    // A failed quiet re-read reports the failure as a read would.
+    const failing = controller.refresh(); requests[2].reject(new Error('offline')); await failing;
+    assert.equal(controller.state.error, true);
+    // Without a shown record a refresh is an ordinary retry (loading published).
+    const again = controller.refresh(); assert.equal(controller.state.loading, true);
+    requests[3].resolve(envelope()); await again; assert.equal(controller.state.error, false);
+    // A newer selection supersedes a refresh in flight.
+    const stale = controller.refresh(); const other = controller.select({ ...image(), path: 'folder/b.png', filename: 'b.png', url: image().url.replace('a%20%23%25', 'b') });
+    requests[5].resolve(envelope({ ...image(), path: 'folder/b.png', filename: 'b.png', url: image().url.replace('a%20%23%25', 'b') })); await other;
+    requests[4].resolve(envelope()); await stale;
+    assert.equal(controller.state.record.identity.path, 'folder/b.png');
+    controller.dispose(); assert.equal(await controller.refresh(), undefined);
+});

tests/js/workspace-library-state.test.js

@@ -47,6 +47,22 @@ test('restored shelves keep filters, loaded parents and continuation without a f
  const next=createLibraryStream({api:{get:async url=>{urls.push(url);return page([item(2)]);}},restore:{filters:{text:'retained',sort:'name'},state:old.state}});assert.equal(next.state.items.length,1);await next.loadMore();assert.match(urls[0],/text=retained/);assert.match(urls[0],/cursor=next/);assert.equal(next.state.items.length,2);next.dispose();
  assert.throws(()=>createLibraryStream({api:{},restore:{filters:{},state:{items:[item(1),item(1)],total:2,variantTotal:0,cursor:null,hasMore:false}}}));
 });
+test('a shelf left before its first page answered or after it failed restores and reads page one',async()=>{
+ const {createLibraryStream}=await source;
+ // The shelf saves whatever state it holds when the route changes; a first page still pending or failed has no variant total yet.
+ let pending;const left=createLibraryStream({api:{get:()=>new Promise(resolve=>{pending=resolve;})}});const first=left.reset({text:'kept'});
+ assert.equal(left.state.loading,true);assert.equal(left.state.variantTotal,null);const saved=left.state;left.dispose();pending(page([item(9)]));await first;
+ const failed=createLibraryStream({api:{get:async()=>{throw Error('offline');}}});await failed.reset();assert.ok(failed.state.error);failed.dispose();
+ for(const state of [saved,failed.state]) {
+  const urls=[];const next=createLibraryStream({api:{get:async url=>{urls.push(url);return page([item(1)]);}},restore:{filters:{text:'kept'},state}});
+  assert.deepEqual([next.state.items.length,next.state.loading,next.state.error,next.state.variantTotal,next.state.hasMore],[0,false,null,null,true]);
+  assert.equal(await next.loadMore(),1);assert.equal(new URL(urls[0],'https://x').searchParams.get('text'),'kept');assert.equal(new URL(urls[0],'https://x').searchParams.has('cursor'),false);
+  assert.equal(next.state.variantTotal,6);next.dispose();
+ }
+ // A pending first page is only the empty, cursorless state: anything else without a variant total stays invalid.
+ for(const state of [{items:[item(1)],total:1,variantTotal:null,cursor:null,hasMore:false},{items:[],total:0,variantTotal:null,cursor:'next',hasMore:true},{items:[],total:3,variantTotal:null,cursor:null,hasMore:true},{items:[],total:0,variantTotal:null,cursor:null,hasMore:false}])
+  assert.throws(()=>createLibraryStream({api:{},restore:{filters:{},state}}),/Invalid library page/);
+});
 test('parent shelf window bounds DOM and pins focused rows without changing logical order',async()=>{
  const {libraryWindow}=await source;const first=libraryWindow(500,2,0,900);assert.equal(first[0],0);assert.ok(first.length<24);
  const middle=libraryWindow(500,2,50000,900,0);assert.equal(middle[0],0);assert.ok(middle.some(index=>index>150));assert.ok(middle.length<24);assert.deepEqual(middle,[...middle].sort((a,b)=>a-b));assert.deepEqual(libraryWindow(3,2,0,900),[0,1,2]);

tests/js/workspace-local-inspection.test.js

@@ -0,0 +1,309 @@
+// web/js/workspace/local-inspection.mjs turns one chosen File's local reads into
+// the inspection wire the workspace already renders, fits it into the 8 MiB
+// response budget exactly as the server does, and plugs into the shared
+// inspection controller, inspector and viewer through localFileAdapter.
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { raw, ihdr, idat, iend, tEXt, iTXt, utf8 } from "./helpers/png-bytes.mjs";
+import { createInspectionController, toInspectionRecord, projectInspectionPayload } from "../../web/js/workspace/inspection-state.mjs";
+import { inspectionDownloads } from "../../web/js/workspace/file-inspector.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const PngMetadata = require("../../web/js/png-metadata.js");
+const ComfyMetadata = require("../../web/js/comfy-metadata.js");
+const { extractGenerationFacts } = ComfyMetadata;
+// The page loads both as scripts; the legacy fill and the PNG reader find them on the global.
+globalThis.PngMetadata = PngMetadata;
+globalThis.ComfyMetadata = ComfyMetadata;
+const m = await import("../../web/js/workspace/local-inspection.mjs").catch((error) => {
+    if (error.code !== "ERR_MODULE_NOT_FOUND") throw error;
+    return {};
+});
+
+const FIXTURES = path.join(here, "..", "fixtures", "local-inspect");
+const PARITY = path.join(here, "..", "fixtures", "inspection_parity");
+const PROMPT = '{"3":{"class_type":"KSampler","inputs":{"seed":7,"steps":20,"cfg":8.0,"sampler_name":"euler","scheduler":"normal","denoise":1.0,"model":["4",0],"positive":["6",0],"negative":["7",0],"latent_image":["5",0]}},"4":{"class_type":"CheckpointLoaderSimple","inputs":{"ckpt_name":"synthetic-v1.safetensors"}},"5":{"class_type":"EmptyLatentImage","inputs":{"width":512,"height":512,"batch_size":1}},"6":{"class_type":"CLIPTextEncode","inputs":{"text":"a red fox in snow, detailed fur","clip":["4",1]}},"7":{"class_type":"CLIPTextEncode","inputs":{"text":"blurry, lowres","clip":["4",1]}}}';
+const WORKFLOW = '{"last_node_id":7,"nodes":[{"id":3,"type":"KSampler","widgets_values":[7,"fixed",20,8.0,"euler","normal",1.0]}],"links":[],"version":0.4}';
+const CONTAINER_WORKFLOW = "Original workflow JSON text is unavailable for this container record. Download metadata or the original file.";
+const LIMIT = 8388608;
+const plain = (value) => JSON.parse(JSON.stringify(value));
+const bytes = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
+
+function pngFile(name, chunks, { lastModified = 1_700_000_000_123 } = {}) {
+    return new File([raw(ihdr(640, 480), idat(), ...chunks, iend())], name, { type: "image/png", lastModified });
+}
+const fixtureFile = (name, directory = FIXTURES) => new File([fs.readFileSync(path.join(directory, name))], name, { lastModified: 1_700_000_000_000 });
+const classify = async (file) => PngMetadata.classifyPrefix(new Uint8Array(await file.slice(0, 32).arrayBuffer()));
+async function handleFor(file, { url = "blob:http://host.test/11111111-2222-3333-4444-555555555555", filename } = {}) {
+    return m.createLocalFileHandle({ file, url, classification: await classify(file), filename });
+}
+async function recordFor(file, options) {
+    const handle = await handleFor(file, options);
+    const wire = await m.localFileAdapter.read(handle);
+    return { handle, wire, record: m.localFileAdapter.toRecord(wire, handle, extractGenerationFacts) };
+}
+
+test("contract", () => {
+    for (const name of ["buildLocalPayload", "fitLocalPayload", "createLocalFileHandle", "readLocalFile", "toInspectionRead", "sanitizeLocalFilename"]) {
+        assert.equal(typeof m[name], "function", `${name} is exported`);
+    }
+    assert.equal(typeof m.localFileAdapter, "object");
+    for (const name of ["validate", "key", "scope", "inspectionPath", "read", "toRecord", "originalDownload", "mediaUrl"]) {
+        assert.equal(typeof m.localFileAdapter[name], "function", `adapter.${name}`);
+    }
+    assert.ok(Object.isFrozen(m.localFileAdapter));
+});
+
+test("a PNG File becomes the server-shaped wire with local provenance", async () => {
+    const file = pngFile("Fox Render.PNG", [tEXt("prompt", PROMPT), tEXt("workflow", WORKFLOW)]);
+    const { wire, record, handle } = await recordFor(file);
+    assert.deepEqual(wire.file, { observation: "selected-local-file", source_label: "Selected local file", media_type: "image", extension: ".png", format: "PNG",
+        size: file.size, width: 640, height: 480, modified_time: 1_700_000_000.123 });
+    assert.equal(wire.success, true);
+    assert.equal(wire.inspection_version, 1);
+    assert.deepEqual(wire.prompts, { positive: { status: "unresolved" }, negative: { status: "unresolved" } });
+    assert.deepEqual(wire.resolution, { state: "unresolved", sampler_id: null, reason: "Resolved in this browser from the workflow.", reason_code: null, node: null });
+    assert.deepEqual(wire.library, { status: "unavailable", scope: "saved-library", tags: [], category_scope: null, tags_scope: null });
+    assert.equal(wire.metadata.status, "available");
+    assert.deepEqual(wire.metadata.raw, { prompt: PROMPT, workflow: WORKFLOW });
+    assert.deepEqual(wire.metadata.record_formats, { prompt: "original-text", workflow: "original-text" });
+    assert.equal(wire.metadata.prompt_graph.status, "parsed");
+    assert.equal(plain(wire.metadata.prompt_graph.value)["3"].inputs.cfg, "8.0");
+    assert.equal(wire.metadata.workflow_graph.status, "parsed");
+    assert.equal(wire.metadata.parameters, null);
+    for (const key of Object.keys(wire)) assert.ok(["success", "inspection_version", "file", "prompts", "resolution", "metadata", "library"].includes(key), key);
+    // The existing projection renders it: facts from the API graph, legacy fill for the roles, no library link.
+    assert.deepEqual(record.identity, { kind: "local-file", key: handle.key, path: "Fox Render.PNG" });
+    assert.equal(record.file.observation, "selected-local-file");
+    assert.equal(record.generation.seed.value, "7");
+    assert.equal(record.generation.cfg.value, "8.0");
+    assert.equal(record.prompts.positive.text, "a red fox in snow, detailed fur");
+    assert.equal(record.prompts.positive.source, "graph-inferred");
+    assert.equal(record.prompts.negative.text, "blurry, lowres");
+    assert.equal(record.historyTarget, null);
+    assert.deepEqual(record.download, { url: "blob:http://host.test/11111111-2222-3333-4444-555555555555", filename: "Fox Render.PNG" });
+    const downloads = inspectionDownloads(record);
+    assert.equal(downloads.metadata.available, true);
+    assert.equal(downloads.workflow.bodyText, WORKFLOW);
+    assert.equal(downloads.metadata.filename, "Fox Render.metadata.json");
+    const exported = JSON.parse(downloads.metadata.bodyText);
+    assert.equal(exported.identity.kind, "local-file");
+    assert.equal(exported.file.source_label, "Selected local file");
+});
+
+test("file facts follow the server: extension like Path.suffix, null when unknown", async () => {
+    const cases = [["a.b.PnG", ".png"], [".hidden", ""], ["noext", ""], ["dot.", ""], ["x.tar.gz", ".gz"]];
+    for (const [name, extension] of cases) {
+        const wire = m.buildLocalPayload({ read: { status: "complete", records: {}, limited: [], width: 2, height: 3 }, file: { name, size: 10, lastModified: 0 }, classification: { media: "image", kind: "png" } });
+        assert.equal(wire.file.extension, extension, name);
+        assert.equal(wire.file.modified_time, 0);
+    }
+    const sparse = m.buildLocalPayload({ read: { status: "complete", records: {}, limited: [], width: 2, height: 3 }, file: { name: "a.png" }, classification: { media: "image", kind: "png" } });
+    assert.deepEqual([sparse.file.size, sparse.file.modified_time], [null, null]);
+    assert.equal(m.buildLocalPayload({ read: { status: "complete", records: {}, limited: [], width: 2, height: 3 }, file: { name: "a.png", size: -1, lastModified: NaN }, classification: { media: "image", kind: "png" } }).file.size, null);
+    assert.throws(() => m.buildLocalPayload({ read: null, file: { name: "a" }, classification: null }), TypeError);
+    assert.throws(() => m.buildLocalPayload({ read: null, file: { name: "a" }, classification: { media: "text", kind: "svg" } }), TypeError);
+});
+
+test("sanitized filenames carry no separators or control characters", () => {
+    assert.equal(m.sanitizeLocalFilename("../a/b\\c\u0000\u001f\u007f.png"), ".._a_b_c.png");
+    assert.equal(m.sanitizeLocalFilename("  spaced .png  "), "spaced .png");
+    assert.equal(m.sanitizeLocalFilename(""), "file");
+    assert.equal(m.sanitizeLocalFilename(undefined), "file");
+    assert.equal(m.sanitizeLocalFilename("\u0000"), "file");
+    assert.equal([...m.sanitizeLocalFilename("😀".repeat(300))].length, 255);
+});
+
+test("unreadable PNG metadata is unreadable, not absent", async () => {
+    const { wire, record } = await recordFor(pngFile("bad.png", [tEXt("prompt", PROMPT, { crc: 0 })]));
+    assert.equal(wire.metadata.status, "unreadable");
+    assert.deepEqual([wire.file.format, wire.file.width, wire.file.height], [null, null, null]);
+    assert.equal(record.generation.seed.reason, "metadata-unreadable");
+    assert.equal(record.prompts.positive.status, "unresolved");
+    assert.equal(JSON.parse(inspectionDownloads(record).metadata.bodyText).metadata.status, "unreadable");
+    const limited = await recordFor(pngFile("big.png", [tEXt("prompt", PROMPT), tEXt("workflow", "[" + "0,".repeat(2_097_153) + "]")]));
+    assert.deepEqual(limited.wire.metadata.record_formats, { prompt: "original-text", workflow: "limited" });
+    assert.equal(limited.wire.metadata.workflow_graph.status, "limited");
+    assert.equal(limited.record.metadata.record_formats.workflow, "limited");
+});
+
+test("JPEG and WebP previews have header facts and absent metadata", async () => {
+    for (const [name, format, width, height] of [["tiny.jpg", "JPEG", 48, 32], ["tiny.webp", "WEBP", 40, 24]]) {
+        const { wire, record } = await recordFor(fixtureFile(name));
+        assert.deepEqual([wire.file.format, wire.file.width, wire.file.height, wire.file.media_type], [format, width, height, "image"], name);
+        assert.equal(wire.metadata.status, "absent");
+        assert.equal(record.generation.seed.status, "not-recorded");
+    }
+});
+
+test("video payloads", async () => {
+    const legacy = await recordFor(fixtureFile("legacy-comment.mp4"));
+    assert.deepEqual([legacy.wire.file.media_type, legacy.wire.file.format, legacy.wire.file.width, legacy.wire.file.extension], ["video", null, null, ".mp4"]);
+    assert.equal(legacy.wire.metadata.record_formats.workflow, "reserialized-json");
+    assert.equal(legacy.wire.metadata.record_formats.prompt, "original-text");
+    assert.equal(legacy.wire.metadata.workflow_graph.status, "parsed");
+    assert.equal(inspectionDownloads(legacy.record).workflow.available, false);
+    assert.equal(inspectionDownloads(legacy.record).workflow.reason, CONTAINER_WORKFLOW);
+    assert.equal(legacy.record.prompts.positive.text, "a red fox in snow, detailed fur");
+    // Ruling M1: a Matroska COMMENT tag is not the exact-case `comment` envelope, so it is absent, as Images reports it.
+    const webm = await recordFor(fixtureFile("legacy-comment.webm"));
+    assert.equal(webm.wire.metadata.status, "absent");
+    const tags = await recordFor(fixtureFile("core-tags.webm"));
+    assert.deepEqual(tags.wire.metadata.record_formats, { prompt: "original-text", workflow: "original-text" });
+    assert.equal(tags.record.generation.seed.value, "7");
+    // AVI and ASF are recognised, previewable, and never read.
+    const avi = new File([utf8("RIFF"), new Uint8Array([0, 0, 0, 0]), utf8("AVI LIST"), new Uint8Array(64)], "clip.avi");
+    const aviRecord = await recordFor(avi);
+    assert.equal(aviRecord.wire.metadata.status, "unreadable");
+    assert.equal(aviRecord.wire.file.media_type, "video");
+    assert.equal(aviRecord.record.generation.seed.reason, "metadata-unreadable");
+    const asf = new File([new Uint8Array([0x30, 0x26, 0xb2, 0x75, 0x8e, 0x66, 0xcf, 0x11, 0xa6, 0xd9, 0x00, 0xaa, 0x00, 0x62, 0xce, 0x6c]), new Uint8Array(64)], "clip.wmv");
+    assert.equal((await recordFor(asf)).wire.metadata.status, "unreadable");
+    // A pre-classified video needs no PNG reader; an image without one is an error, not a silent absence.
+    const clip = fixtureFile("core.mkv");
+    assert.equal((await m.readLocalFile(clip, { classification: { media: "video", kind: "matroska" }, pngMetadata: null })).result.read.status, "complete");
+    await assert.rejects(m.readLocalFile(clip, { pngMetadata: null }), /PNG reader/);
+    await assert.rejects(m.readLocalFile(fixtureFile("tiny.jpg"), { classification: { media: "image", kind: "jpeg" }, pngMetadata: null }), /PNG reader/);
+    await assert.rejects(m.readLocalFile("not a blob"), TypeError);
+    assert.deepEqual(await m.readLocalFile(new File([utf8("<svg/>")], "x.png"), { pngMetadata: PngMetadata }), { classification: null, result: null });
+    // A container that fails to parse is unreadable too.
+    const broken = new File([utf8("\0\0\0\x08ftypisom"), utf8("\0\0\0\x01moov")], "broken.mp4");
+    assert.equal((await recordFor(broken)).wire.metadata.status, "unreadable");
+});
+
+test("local cap measures escaped UTF-8 atomically", async () => {
+    // A 1 MiB Latin-1 prompt of 'é' (2 UTF-8 bytes, 1 code unit each) and a 4 MiB UTF-8 workflow of
+    // emoji (4 bytes, 2 units): the UTF-16 length of the wire is well under the limit while its UTF-8
+    // size is not, so a cap counting code units would keep too much.
+    const prompt = `{"1":{"class_type":"A","inputs":{"t":"${"é".repeat(1_000_000)}"}}}`;
+    const workflow = `{"nodes":[],"u":"${"😀".repeat(1_000_000)}"}`;
+    const file = pngFile("wide.png", [iTXt("workflow", workflow), tEXt("prompt", prompt)]);
+    const handle = await handleFor(file);
+    const raw = await m.readLocalFile(handle.file, { classification: handle.classification, pngMetadata: PngMetadata });
+    assert.equal(raw.result.status, "complete");
+    const wire = m.buildLocalPayload({ read: raw.result, file: { name: file.name, size: file.size, lastModified: file.lastModified }, classification: handle.classification });
+    const text = JSON.stringify(wire);
+    assert.ok(text.length < LIMIT && bytes(wire) > LIMIT, `${text.length} code units, ${bytes(wire)} bytes`);
+    const fitted = await m.fitLocalPayload(wire);
+    assert.ok(bytes(fitted) <= LIMIT);
+    assert.equal(fitted.metadata.workflow_graph.status, "limited", "the workflow graph goes first");
+    assert.equal(fitted.metadata.prompt_graph.status, "parsed");
+    assert.deepEqual(Object.keys(fitted.metadata.raw).sort(), ["prompt", "workflow"], "raw is kept");
+    const record = m.localFileAdapter.toRecord(fitted, handle, extractGenerationFacts);
+    assert.equal(inspectionDownloads(record).metadata.available, true);
+    assert.equal(inspectionDownloads(record).workflow.available, false);
+    // Whole-raw omission is atomic and marks the response-size limit; the inspector offers no metadata download.
+    const squeezed = await m.fitLocalPayload(wire, bytes(fitted) - 1);
+    assert.deepEqual([squeezed.metadata.workflow_graph.status, squeezed.metadata.prompt_graph.status], ["limited", "limited"]);
+    const tiny = await m.fitLocalPayload(wire, 2000);
+    assert.equal(tiny.metadata.status, "limited");
+    assert.equal(tiny.metadata.omitted_reason, "response-size-limit");
+    assert.deepEqual(tiny.metadata.raw, {});
+    assert.equal(tiny.metadata.parameters, null);
+    assert.ok(bytes(tiny) <= 2000);
+    const omitted = m.localFileAdapter.toRecord(tiny, handle, extractGenerationFacts);
+    assert.equal(inspectionDownloads(omitted).metadata.available, false);
+    assert.equal(omitted.generation.seed.reason, "projection-limited");
+    await assert.rejects(m.fitLocalPayload(wire, 100), /exceeds/);
+    assert.equal(wire.metadata.status, "available", "the input wire is not mutated");
+    assert.equal((await m.localFileAdapter.read(handle)).metadata.workflow_graph.status, "limited", "adapter.read returns the fitted wire");
+});
+
+test("adapter rejects foreign blob URLs and never resolves owned ones", async () => {
+    const file = pngFile("a.png", [tEXt("prompt", PROMPT)]);
+    const classification = await classify(file);
+    const owned = m.createLocalFileHandle({ file, url: "blob:http://host.test/0b0e", classification });
+    assert.ok(Object.isFrozen(owned));
+    assert.deepEqual(m.localFileAdapter.originalDownload(owned), { url: "blob:http://host.test/0b0e", filename: "a.png" });
+    assert.equal(m.localFileAdapter.mediaUrl(owned), "blob:http://host.test/0b0e");
+    // The controller and the viewer session spread-copy descriptors: a copy is the same selection.
+    const copy = { ...owned, occurrence: {}, reference: {} };
+    assert.equal(m.localFileAdapter.key(copy), owned.key);
+    assert.equal(m.localFileAdapter.mediaUrl(copy), "blob:http://host.test/0b0e");
+    // A tampered URL, key, File or name, or a descriptor this module never made, is foreign.
+    const tampered = [{ ...owned, url: "blob:http://host.test/other" }, { ...owned, key: "local:1" }, { ...owned, file: new File([], "x.png") }, { ...owned, filename: "other.png" },
+        { kind: "local-file", key: owned.key, filename: owned.filename, url: owned.url, file, is_video: false, classification }, null, "local:1"];
+    for (const foreign of tampered) {
+        for (const method of ["validate", "originalDownload", "mediaUrl", "key", "scope", "inspectionPath"]) assert.throws(() => m.localFileAdapter[method](foreign), TypeError, method);
+        await assert.rejects(m.localFileAdapter.read(foreign), TypeError);
+        assert.throws(() => m.localFileAdapter.toRecord({ success: true, inspection_version: 1 }, foreign, extractGenerationFacts), TypeError);
+    }
+    for (const url of ["http://host.test/x.png", "/prompt_manager/images/serve/a.png", "javascript:alert(1)", "data:image/png;base64,AA==", "", 5]) {
+        assert.throws(() => m.createLocalFileHandle({ file, url, classification }), TypeError, String(url));
+    }
+    assert.throws(() => m.createLocalFileHandle({ file: "not a blob", url: "blob:http://host.test/1", classification }), TypeError);
+    assert.throws(() => m.createLocalFileHandle({ file, url: "blob:http://host.test/1", classification: null }), TypeError);
+    assert.throws(() => m.createLocalFileHandle({ file, url: "blob:http://host.test/1", classification: { media: "text", kind: "svg" } }), TypeError);
+    // A proxy-mounted host resolves API URLs; blob URLs are session-owned and bypass it.
+    const before = Object.getOwnPropertyDescriptor(globalThis, "window");
+    Object.defineProperty(globalThis, "window", { configurable: true, value: { location: { href: "https://example.test/proxy/prompt_manager/workspace" }, ApiClient: { resolveUrl: (url) => `/proxy${url}` } } });
+    try {
+        assert.equal(m.localFileAdapter.mediaUrl(owned), "blob:http://host.test/0b0e");
+        assert.equal(m.localFileAdapter.originalDownload(owned).url, "blob:http://host.test/0b0e");
+    } finally {
+        if (before) Object.defineProperty(globalThis, "window", before); else delete globalThis.window;
+    }
+    // Without an object URL the record has no download and the viewer cannot show the original.
+    const previewless = m.createLocalFileHandle({ file, url: null, classification });
+    assert.equal(m.localFileAdapter.mediaUrl(previewless), null);
+    assert.throws(() => m.localFileAdapter.originalDownload(previewless), TypeError);
+    const record = m.localFileAdapter.toRecord(await m.localFileAdapter.read(previewless), previewless, extractGenerationFacts);
+    assert.equal(record.download, null);
+    assert.equal(inspectionDownloads(record).metadata.filename, "a.metadata.json");
+});
+
+test("select reuses the same local key", async () => {
+    const file = pngFile("a.png", [tEXt("prompt", PROMPT)]);
+    const classification = await classify(file);
+    const first = m.createLocalFileHandle({ file, url: "blob:http://host.test/1", classification });
+    const second = m.createLocalFileHandle({ file, url: "blob:http://host.test/2", classification });
+    assert.notEqual(first.key, second.key, "the same bytes chosen twice are two selections");
+    assert.equal(m.localFileAdapter.scope(first), "local");
+    assert.equal(m.localFileAdapter.inspectionPath(first), `local-file:${first.key}`);
+    assert.equal(m.localFileAdapter.key(first), first.key);
+    const reads = [];
+    // The controller calls adapter.read itself (PR L2 Task 4); the API is never reached.
+    const api = new Proxy({}, { get: (_, key) => assert.fail(`api.${String(key)} touched`) });
+    const adapter = { ...m.localFileAdapter, read: (handle, options) => { reads.push(m.localFileAdapter.inspectionPath(handle)); return m.localFileAdapter.read(handle, options); } };
+    const controller = createInspectionController({ api, extractFacts: extractGenerationFacts, adapter });
+    const pending = controller.select(first);
+    assert.equal(controller.select(first), pending, "the same handle returns the pending read");
+    await pending;
+    assert.deepEqual(reads, [`local-file:${first.key}`]);
+    assert.equal(controller.state.record.identity.key, first.key);
+    assert.equal(controller.state.record.prompts.positive.text, "a red fox in snow, detailed fur");
+    await controller.select(second);
+    assert.equal(reads.length, 2);
+    assert.equal(controller.state.record.identity.key, second.key);
+    await controller.select({ ...second, occurrence: {}, reference: {} });
+    assert.equal(reads.length, 2, "the controller's own copy is the same selection");
+    await controller.select({ ...second, url: "blob:http://host.test/evil" });
+    assert.equal(controller.state.error, true, "a foreign handle is published as an error, never read");
+    assert.equal(reads.length, 2);
+    controller.dispose();
+});
+
+test("fileFor admits selected-local-file only for a local identity", async () => {
+    const file = pngFile("a.png", [tEXt("prompt", PROMPT)]);
+    const { wire, handle } = await recordFor(file);
+    const rooted = { root_index: 0, path: "folder/a.png", filename: "a.png", url: "/prompt_manager/images/serve/folder/a.png?root=0" };
+    assert.throws(() => toInspectionRecord({ ...wire, image: { root_index: 0, path: "folder/a.png", filename: "a.png" } }, rooted, extractGenerationFacts), /Invalid inspection file/);
+    assert.throws(() => projectInspectionPayload({ ...wire, file: { ...wire.file, observation: "current-file" } }, { kind: "local-file", key: handle.key, path: "a.png" }, null, extractGenerationFacts), /Invalid inspection file/);
+    assert.throws(() => m.localFileAdapter.toRecord({ ...wire, success: false }, handle, extractGenerationFacts), TypeError);
+    assert.throws(() => m.localFileAdapter.toRecord({ ...wire, inspection_version: 2 }, handle, extractGenerationFacts), TypeError);
+    assert.throws(() => m.localFileAdapter.toRecord(null, handle, extractGenerationFacts), TypeError);
+});
+
+test("the parity corpus PNGs read into renderable records", async () => {
+    for (const name of ["f02.png", "f06a.png", "f23.png"]) {
+        const { wire, record } = await recordFor(fixtureFile(name, PARITY));
+        assert.equal(wire.metadata.status, "available", name);
+        assert.equal(record.file.format, "PNG");
+        assert.ok(["parsed", "limited", "malformed"].includes(wire.metadata.prompt_graph.status));
+    }
+});

tests/js/workspace-local-projection.test.js

@@ -0,0 +1,249 @@
+// web/js/workspace/local-projection.mjs ports utils/inspection_response.py: the
+// strict Decimal/duplicate-key parse, the prompt/workflow/carrier projection, the
+// depth and node ceilings, _metadata and the 8 MiB omission steps. These units pin
+// the rules the plan names; tests/test_local_inspect_parity.py proves byte parity
+// with the server over the committed corpus.
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const m = await import("../../web/js/workspace/local-projection.mjs").catch((error) => {
+    if (error.code !== "ERR_MODULE_NOT_FOUND") throw error;
+    return {};
+});
+const CASES = JSON.parse(fs.readFileSync(path.join(here, "..", "fixtures", "local-inspect", "projection-cases.json"), "utf8")).cases;
+
+const plain = (value) => JSON.parse(JSON.stringify(value));
+const bytes = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
+const graphOf = (text, kind = "workflow") => plain(m.projectGraph(text, kind));
+const nested = (depth, close = "]", open = "[") => open.repeat(depth) + close.repeat(depth);
+const nodes = (count) => `{${Array.from({ length: count }, (_, i) => `"${i}":{"class_type":"A","inputs":{}}`).join(",")}}`;
+
+test("contract", () => {
+    for (const name of ["projectGraph", "projectMetadata", "fitInspectionPayload", "inspectionBytes", "parseStrictJson"]) {
+        assert.equal(typeof m[name], "function", `${name} is exported`);
+    }
+    assert.equal(m.MAX_RESPONSE_BYTES, 8388608);
+    assert.equal(m.MAX_PROJECTION_DEPTH, 64);
+    assert.equal(m.GRAPH_NODE_CEILING, 20000);
+});
+
+test("projection spells numbers like the server", () => {
+    // literal -> Python str(Decimal(literal)) (or the int when it is a safe integer)
+    const table = [
+        ["1e3", "1E+3"], ["1e0", "1"], ["-0.0", "-0.0"], ["6.50", "6.50"], ["0.0100", "0.0100"], ["1.0e2", "1.0E+2"],
+        ["0e5", "0E+5"], ["0.0000001", "1E-7"], ["0.000001", "0.000001"], ["1E+3", "1E+3"], ["1e-0", "1"], ["0.5e1", "5"],
+        ["0.05e1", "0.5"], ["0.0e0", "0.0"], ["1.5e+300", "1.5E+300"], ["123e-8", "0.00000123"], ["2.5e-3", "0.0025"],
+        ["1.0", "1.0"], ["-1.50", "-1.50"], ["0.0", "0.0"], ["100.0", "100.0"], ["1234567e-6", "1.234567"], ["0.5E-6", "5E-7"],
+        ["0.5E-5", "0.000005"], ["1e22", "1E+22"], ["0.000000", "0.000000"], ["-0.000000e-3", "-0E-9"], ["7.0e-6", "0.0000070"],
+        ["7.0e-7", "7.0E-7"], ["12345678901234567890.123", "12345678901234567890.123"], ["9007199254740992.0", "9007199254740992.0"],
+        ["1e999999999999999999", "1E+999999999999999999"], ["1e-1999999999999999997", "1E-1999999999999999997"],
+        ["0.0e1000000000000000000", "0E+999999999999999999"], ["1.5e999999999999999999", "1.5E+999999999999999999"],
+        ["0.1e-1999999999999999996", "1E-1999999999999999997"],
+        ["9007199254740991", 9007199254740991], ["-9007199254740991", -9007199254740991], ["9007199254740992", "9007199254740992"],
+        ["-9007199254740992", "-9007199254740992"], ["10000000000000000", "10000000000000000"], ["123456789012345678901234567890", "123456789012345678901234567890"],
+        ["0", 0], ["-0", 0], ["42", 42], ["-7", -7],
+    ];
+    for (const [literal, expected] of table) {
+        const graph = graphOf(`{"n":${literal}}`);
+        assert.equal(graph.status, "parsed", literal);
+        assert.deepEqual(graph.value, { n: expected }, literal);
+    }
+    assert.deepEqual(graphOf('{"n":[NaN,Infinity,-Infinity]}').value, { n: [null, null, null] });
+    // A 4300-digit integer is Python's int() limit; one more digit fails the parse.
+    assert.deepEqual(graphOf(`{"n":${"1".repeat(4300)}}`).value, { n: "1".repeat(4300) });
+    assert.equal(graphOf(`{"n":${"1".repeat(4301)}}`).status, "malformed");
+    assert.equal(graphOf(`{"n":-${"1".repeat(4301)}}`).status, "malformed");
+    // Exact Decimal construction fails past the C library's exponent range.
+    for (const literal of ["1e1000000000000000000", "15e999999999999999999", "1e-1999999999999999998", "1.5e-1999999999999999997",
+        "0e1000000000000000000", "1e9223372036854775808", "0.0e1000000000000000001", "1e99999999999999999999999999"]) {
+        assert.equal(graphOf(`{"n":${literal}}`).status, "malformed", literal);
+    }
+    // Escapes: surrogate pairs join, lone surrogates stay, control characters decode.
+    const text = graphOf('{"s":"\\u00E9\\uD83D\\uDE00\\uD800\\u0000\\u001f\\/\\\\\\"\\b\\f\\n\\r\\t\\uD800\\u0041"}').value.s;
+    assert.equal(text, "é\u{1f600}\ud800\u0000\u001f/\\\"\b\f\n\r\t\ud800A");
+    assert.equal(JSON.stringify(m.projectGraph('{"s":"\\ud800"}', "workflow").value), '{"s":"\\ud800"}');
+});
+
+test("projection rejects what Python's json rejects and nothing else", () => {
+    const rejected = ["{}", "\f1", "  1", '{"a":1,}', "[1,]", "{'a':1}", '{"a"}', "[1 2]", "tru", "nul", "-NaN", "1.", ".5", "01", "+1",
+        "1e", "-", '"\\x"', '"abc', "", "  ", '"\u0001"', '{"a":1}x', '"\\u12"', '{"a":1,"a":2}', '{"a":{"b":1,"b":1}}', "[1,[2,{\"k\":1,\"k\":2}]]",
+        '{"a":1 "b":2}', "[,1]", "{,}", '{"a":}', "[1}", "{1:2}", "
[]", "[]\u000b", "0x10", "1_000", "--1", "1e+", "1E-", '"\\uD800\\uDC"'];
+    for (const text of rejected) assert.equal(graphOf(text).status, "malformed", JSON.stringify(text));
+    for (const text of [" \t\r\n{}\n\t ", '{"a":[1,{"b":null}],"c":"d"}', '{"\\u0000":1}', '{"a":1,"A":1}', '{"":[]}']) {
+        assert.equal(graphOf(text).status, "parsed", JSON.stringify(text));
+    }
+    // Top-level values that are not objects parse but are not graphs.
+    for (const text of ["[]", '"x"', "1", "null", "true", "NaN", "1.5", "-Infinity"]) assert.equal(graphOf(text).status, "malformed", text);
+    assert.equal(graphOf(undefined).status, "malformed");
+    assert.equal(graphOf(null).status, "malformed");
+});
+
+test("projection limits", () => {
+    // A workflow's root is depth 1; the 64th nested container is kept, the 65th is limited.
+    assert.equal(graphOf(`{"a":${nested(63)}}`).status, "parsed");
+    assert.equal(graphOf(`{"a":${nested(64)}}`).status, "limited");
+    // Prompt: root 1, node 2, inputs 3; a value chain reaching depth 64 is kept, 65 is limited.
+    assert.equal(graphOf(`{"1":{"class_type":"A","inputs":{"v":${nested(61)}}}}`, "prompt").status, "parsed");
+    assert.equal(graphOf(`{"1":{"class_type":"A","inputs":{"v":${nested(62)}}}}`, "prompt").status, "limited");
+    // Dropped node keys are still validated for depth.
+    assert.equal(graphOf(`{"1":{"class_type":"A","inputs":{},"_meta":{"v":${nested(61)}}}}`, "prompt").status, "parsed");
+    assert.equal(graphOf(`{"1":{"class_type":"A","inputs":{},"_meta":{"v":${nested(62)}}}}`, "prompt").status, "limited");
+    // A workflow is normalized before its shape is checked, so a deep non-object is limited; a
+    // prompt checks its root first. Depth never overflows the parser (100,000 nested arrays).
+    assert.equal(graphOf(nested(10)).status, "malformed");
+    assert.equal(graphOf(nested(5000)).status, "limited");
+    assert.equal(graphOf(nested(5000), "prompt").status, "malformed");
+    assert.equal(graphOf(`{"a":${nested(100000)}}`).status, "limited");
+    // Node ceilings: 20,000 API nodes parse, 20,001 are limited.
+    assert.equal(graphOf(nodes(20000), "prompt").status, "parsed");
+    assert.equal(graphOf(nodes(20001), "prompt").status, "limited");
+    const list = (count) => `[${Array.from({ length: count }, () => "{}").join(",")}]`;
+    assert.equal(graphOf(`{"nodes":${list(20000)}}`).status, "parsed");
+    assert.equal(graphOf(`{"nodes":${list(20001)}}`).status, "limited");
+    assert.equal(graphOf(`{"nodes":${list(10001)},"definitions":{"subgraphs":[{"nodes":${list(10000)}},5,{"nodes":3}]}}`).status, "limited");
+    assert.equal(graphOf(`{"nodes":${list(10000)},"definitions":{"subgraphs":[{"nodes":${list(10000)}}]}}`).status, "parsed");
+    assert.equal(graphOf(`{"nodes":{"${"x".repeat(5)}":1},"definitions":[]}`).status, "parsed");
+    // Duplicate keys anywhere are malformed, including inside dropped node keys.
+    assert.equal(graphOf('{"1":{"class_type":"A","inputs":{},"_meta":{"t":1,"t":2}}}', "prompt").status, "malformed");
+    assert.equal(graphOf('{"1":{"class_type":"A","inputs":{"a":1,"a":1}}}', "prompt").status, "malformed");
+});
+
+test("prompt nodes keep only class_type and inputs on null-prototype objects", () => {
+    const text = '{"3":{"class_type":"KSampler","inputs":{"seed":9007199254740993,"cfg":8.0,"n":NaN},"_meta":{"title":"x"},"is_changed":[1]},"4":5,"5":[1,2.50],"__proto__":{"class_type":"P","inputs":{}},"constructor":"c"}';
+    const graph = m.projectGraph(text, "prompt");
+    assert.equal(graph.status, "parsed");
+    assert.equal(Object.getPrototypeOf(graph.value), null);
+    assert.equal(Object.getPrototypeOf(graph.value["3"]), null);
+    assert.equal(Object.getPrototypeOf(graph.value["3"].inputs), null);
+    // JSON.parse, like the projection, makes "__proto__" an own key; an object literal would not.
+    assert.deepEqual(plain(graph.value), JSON.parse('{"3":{"class_type":"KSampler","inputs":{"seed":"9007199254740993","cfg":"8.0","n":null}},"4":5,"5":[1,"2.50"],"__proto__":{"class_type":"P","inputs":{}},"constructor":"c"}'));
+    assert.ok(Object.hasOwn(graph.value, "__proto__"));
+    assert.deepEqual(plain(graph.value["__proto__"]), { class_type: "P", inputs: {} });
+    assert.equal(graph.value.constructor, "c");
+    for (const text of ["[]", '"3"', "5", "null", '{"nodes":[]}x']) assert.equal(m.projectGraph(text, "prompt").status, text === '{"nodes":[]}x' ? "malformed" : "malformed", text);
+    // A workflow keeps everything, normalized.
+    assert.deepEqual(graphOf('{"nodes":[{"id":1,"widgets_values":[7,"fixed",8.0,1e3]}],"links":[],"version":0.4}').value,
+        { nodes: [{ id: 1, widgets_values: [7, "fixed", "8.0", "1E+3"] }], links: [], version: "0.4" });
+});
+
+test("projectMetadata mirrors _metadata for records, formats and carriers", () => {
+    const prompt = '{"1":{"class_type":"A","inputs":{"x":1.0}}}', workflow = '{"nodes":[],"version":0.4}';
+    const read = (records, record_formats, carrierText = null, limited = []) => ({ records, record_formats, carrierText, limited });
+    assert.deepEqual(plain(m.projectMetadata(null)), { status: "unreadable", omitted_reason: null, raw: {}, record_formats: {}, parameters: null,
+        prompt_graph: { status: "absent", value: null }, workflow_graph: { status: "absent", value: null } });
+    assert.deepEqual(plain(m.projectMetadata(read({}, {}))), { status: "absent", omitted_reason: null, raw: {}, record_formats: {}, parameters: null,
+        prompt_graph: { status: "absent", value: null }, workflow_graph: { status: "absent", value: null } });
+    const full = plain(m.projectMetadata(read({ prompt, workflow, parameters: "cat\nSteps: 1", comfyassets_prompt_pairs: "{}", other: "x" },
+        { prompt: "original-text", workflow: "original-text", parameters: "original-text", comfyassets_prompt_pairs: "original-text", other: "original-text" })));
+    assert.deepEqual(full, { status: "available", omitted_reason: null,
+        raw: { prompt, workflow, parameters: "cat\nSteps: 1", comfyassets_prompt_pairs: "{}" },
+        record_formats: { prompt: "original-text", workflow: "original-text", parameters: "original-text", comfyassets_prompt_pairs: "original-text" },
+        parameters: "cat\nSteps: 1", prompt_graph: { status: "parsed", value: { 1: { class_type: "A", inputs: { x: "1.0" } } } },
+        workflow_graph: { status: "parsed", value: { nodes: [], version: "0.4" } } });
+    // limited records lose their text; invalid is malformed; reserialized without a carrier is limited.
+    const limited = plain(m.projectMetadata(read({ prompt, workflow }, { prompt: "original-text" }, null, ["workflow"])));
+    assert.deepEqual(limited.raw, { prompt });
+    assert.deepEqual(limited.record_formats, { prompt: "original-text", workflow: "limited" });
+    assert.equal(limited.workflow_graph.status, "limited");
+    assert.equal(plain(m.projectMetadata(read({ prompt }, { prompt: "original-text", workflow: "invalid" }))).workflow_graph.status, "malformed");
+    assert.equal(plain(m.projectMetadata(read({ workflow }, { workflow: "reserialized-json" }))).workflow_graph.status, "limited");
+    assert.equal(plain(m.projectMetadata(read({ prompt: "{" }, { prompt: "original-text" }))).prompt_graph.status, "malformed");
+    // Unknown formats are dropped from record_formats but the raw text still projects.
+    const odd = plain(m.projectMetadata(read({ prompt }, { prompt: "weird" })));
+    assert.deepEqual(odd.record_formats, {});
+    assert.equal(odd.prompt_graph.status, "parsed");
+    // A non-text record vanishes from raw and its named graph is malformed.
+    assert.equal(plain(m.projectMetadata(read({ prompt: 5 }, { prompt: "original-text" }))).prompt_graph.status, "malformed");
+    // Carriers: strings re-parse by kind, objects were projected at depth 2; a bad carrier fails every present graph.
+    const envelope = JSON.stringify({ prompt, workflow: { nodes: [], v: 1 } });
+    const carried = plain(m.projectMetadata(read({ prompt, workflow: '{"nodes": [], "v": 1}' }, { prompt: "original-text", workflow: "reserialized-json" }, envelope)));
+    assert.deepEqual(carried.prompt_graph, { status: "parsed", value: { 1: { class_type: "A", inputs: { x: "1.0" } } } });
+    assert.deepEqual(carried.workflow_graph, { status: "parsed", value: { nodes: [], v: 1 } });
+    const broken = plain(m.projectMetadata(read({ prompt, workflow }, { prompt: "original-text", workflow: "original-text" }, "[1]")));
+    assert.deepEqual([broken.prompt_graph.status, broken.workflow_graph.status], ["malformed", "malformed"]);
+    const deep = plain(m.projectMetadata(read({ prompt }, { prompt: "original-text" }, `{"title":${nested(70)},"prompt":${JSON.stringify(prompt)}}`)));
+    assert.equal(deep.prompt_graph.status, "limited");
+    const partial = plain(m.projectMetadata(read({ prompt, workflow }, { prompt: "original-text", workflow: "original-text" }, '{"prompt":"{","workflow":5}')));
+    assert.deepEqual([partial.prompt_graph.status, partial.workflow_graph.status], ["malformed", "malformed"]);
+    const missing = plain(m.projectMetadata(read({ prompt }, { prompt: "original-text" }, '{"workflow":{}}')));
+    assert.deepEqual([missing.prompt_graph.status, missing.workflow_graph.status], ["malformed", "absent"]);
+    // The carrier's own prompt object is projected: depth 2, node keys filtered.
+    const objectPrompt = plain(m.projectMetadata(read({ prompt: "x" }, { prompt: "reserialized-json" }, '{"prompt":{"1":{"class_type":"A","inputs":{},"_meta":{}}}}')));
+    assert.deepEqual(objectPrompt.prompt_graph, { status: "parsed", value: { 1: { class_type: "A", inputs: {} } } });
+});
+
+test("fitInspectionPayload omits the workflow graph, then the prompt graph, then all raw atomically", async () => {
+    const payload = {
+        success: true, inspection_version: 1, metadata: {
+            status: "available", omitted_reason: null, raw: { prompt: "é".repeat(100), workflow: "{}" }, record_formats: { prompt: "original-text", workflow: "original-text" },
+            parameters: null, prompt_graph: { status: "parsed", value: { 1: { class_type: "A", inputs: { t: "\ud800".repeat(50) } } } },
+            workflow_graph: { status: "parsed", value: { nodes: Array.from({ length: 50 }, (_, i) => ({ id: i })) } },
+        },
+    };
+    const text = JSON.stringify(payload);
+    // UTF-8 bytes, not UTF-16 code units: 'é' is 2 bytes, an escaped lone surrogate 6.
+    assert.equal(m.inspectionBytes(payload), Buffer.byteLength(text, "utf8"));
+    assert.ok(m.inspectionBytes(payload) > text.length);
+    // Measured in bounded chunks: pairs and 2-byte characters across every chunk edge count once.
+    for (const shift of [0, 1, 2, 3]) {
+        const wide = { s: "x".repeat(shift) + "é😀".repeat(200000) + "\ud800", t: "a😀".repeat(70000) };
+        assert.equal(m.inspectionBytes(wide), Buffer.byteLength(JSON.stringify(wide), "utf8"), `shift ${shift}`);
+    }
+    const whole = await m.fitInspectionPayload(payload, bytes(payload));
+    assert.equal(whole, payload, "a payload within the limit is returned as is");
+    const first = await m.fitInspectionPayload(payload, bytes(payload) - 1);
+    assert.equal(first.metadata.workflow_graph.status, "limited");
+    assert.equal(first.metadata.prompt_graph.status, "parsed");
+    assert.deepEqual(first.metadata.raw, payload.metadata.raw);
+    assert.ok(bytes(first) <= bytes(payload) - 1);
+    const second = await m.fitInspectionPayload(payload, bytes(first) - 1);
+    assert.deepEqual([second.metadata.workflow_graph.status, second.metadata.prompt_graph.status], ["limited", "limited"]);
+    assert.equal(second.metadata.status, "available");
+    assert.deepEqual(second.metadata.raw, payload.metadata.raw);
+    const third = await m.fitInspectionPayload(payload, bytes(second) - 1);
+    assert.deepEqual(third.metadata, { ...second.metadata, raw: {}, parameters: null, status: "limited", omitted_reason: "response-size-limit" });
+    assert.ok(bytes(third) <= bytes(second) - 1);
+    await assert.rejects(m.fitInspectionPayload(payload, bytes(third) - 1), /exceeds/);
+    // The caller's payload is never mutated and absent graphs are left alone.
+    assert.equal(JSON.stringify(payload), text);
+    const absent = { ...payload, metadata: { ...payload.metadata, workflow_graph: { status: "absent", value: null } } };
+    const fitted = await m.fitInspectionPayload(absent, bytes(absent) - 1);
+    assert.equal(fitted.metadata.workflow_graph.status, "absent");
+    assert.equal(fitted.metadata.prompt_graph.status, "limited");
+    assert.equal((await m.fitInspectionPayload(payload)).metadata.status, "available", "the default limit is 8 MiB");
+    // Every omission step after the first measure hands the event loop a turn, and an
+    // abort between steps rejects with AbortError; the answer itself is unchanged.
+    let turns = 0;
+    const counted = await m.fitInspectionPayload(payload, bytes(second) - 1, { yieldControl: async () => { turns += 1; } });
+    assert.equal(JSON.stringify(counted), JSON.stringify(third));
+    assert.equal(turns, 3);
+    assert.equal(await m.fitInspectionPayload(payload, bytes(payload), { yieldControl: async () => { turns += 1; } }), payload);
+    assert.equal(turns, 3, "a payload within the limit is measured once, without a turn");
+    const controller = new AbortController();
+    await assert.rejects(m.fitInspectionPayload(payload, bytes(second) - 1, { signal: controller.signal, yieldControl: async () => controller.abort() }), { name: "AbortError" });
+});
+
+test("the committed projection corpus has every outcome and parses with the oracle entry shape", () => {
+    assert.ok(CASES.length >= 40);
+    const names = new Set(), statuses = new Set(), graphs = new Set();
+    for (const entry of CASES) {
+        assert.equal(typeof entry.name, "string");
+        assert.ok(!names.has(entry.name), `duplicate case ${entry.name}`);
+        names.add(entry.name);
+        const read = entry.records === null ? null : { records: entry.records, record_formats: entry.record_formats ?? Object.fromEntries(Object.keys(entry.records).map((key) => [key, "original-text"])),
+            carrierText: entry.carrier_text ?? null, limited: entry.limited ?? [] };
+        const metadata = m.projectMetadata(read);
+        statuses.add(metadata.status);
+        graphs.add(metadata.prompt_graph.status);
+        graphs.add(metadata.workflow_graph.status);
+        if (entry.expect) {
+            for (const [field, status] of Object.entries(entry.expect)) assert.equal(metadata[field].status, status, `${entry.name} ${field}`);
+        }
+    }
+    assert.deepEqual([...statuses].sort(), ["absent", "available", "unreadable"]);
+    assert.deepEqual([...graphs].sort(), ["absent", "limited", "malformed", "parsed"]);
+});