Add detailed render telemetry and concise video status

docs/architecture.md

@@ -31,3 +31,16 @@ worker manager; import itself does not start work, and test configurations can
 disable autostart. Processing and muxing poll persisted cancellation state.
 The current Flask process serves the interface and API together on port 5000. A
 future 5175/4200 frontend/API split is a plan, not current behavior.
+
+Runtime render telemetry belongs to the worker manager, not the repository. A
+bounded store holds caller-independent snapshots under a short lock, retains
+only recent speed samples, derives elapsed time from an injectable monotonic
+clock, and publishes UTC timestamps. Frame callbacks may be frequent, but the
+runtime view is limited to about four updates per second and manifest progress
+remains coarse.
+
+Durable job milestones record only meaningful phase transitions. Terminal
+timing summaries survive restart; rolling speed and ETA restart as unknown.
+FFmpeg stdout carries structured program progress while a separate reader drains
+bounded stderr. The polling UI owns one timer and one request, rejects obsolete
+job revisions, and stops on terminal or reset states.

docs/product-direction.md

@@ -22,6 +22,12 @@ readiness, and testable boundaries needed by that future workspace. GlitchCraft
 owns creative treatment; Web Video Optimizer remains the detailed
 delivery-optimization and packaging tool.
 
+The transitional interface explains long video work with concise, progressively
+disclosed telemetry. It truthfully describes applying the enabled stack to each
+frame rather than pretending effects run as separate passes. Advanced temporal
+feedback, optical flow, frame reordering, codec datamosh, signal modeling, and
+new effect algorithms remain intentionally deferred.
+
 A future orchestration dashboard may discover and check GlitchCraft, ColorCraft,
 and Web Video Optimizer through related contracts. It is not implemented here
 and cannot launch or remotely control this service. The family-aligned React

docs/service-contract.md

@@ -39,3 +39,11 @@ Persistent storage covers image/video sources, explicit outputs, and video job
 state. Readiness reports queue capacity, worker concurrency, manifest migration
 or reconciliation state, and both required video tools. Saved recipe management,
 WVO handoff, authentication, and a visible library interface are deferred.
+
+Application version 0.2.1 advertises video-job contract v2 and the
+`video-render-telemetry` capability. `/metadata` publishes supported phase
+codes, the client-polling model, a four-Hz runtime update target, FFmpeg
+program-progress support, and redacted queue totals. The capability is available
+only when persistent video processing and its manager are available. Discovery
+never exposes sample buffers, thread names, executable paths, or raw process
+output.

docs/storage.md

@@ -1,6 +1,6 @@
 # Persistent media storage
 
-GlitchCraft 0.2.0 uses a configurable managed data root:
+GlitchCraft 0.2.1 uses a configurable managed data root:
 
 ```text
 data/
@@ -58,3 +58,8 @@ diagnostics whose values and granularity may vary by platform.
 
 Video completion installs the final MP4 and marks its job completed in one
 manifest mutation. Intermediate job files remain temporary and are never served.
+Manifest schema remains v2 in application 0.2.1. Telemetry contract v2 adds only
+backward-compatible job defaults: a phase, at most 32 durable milestones, a
+terminal timing summary, and coarse last-known frame counters. High-frequency
+FPS, ETA, encoded-time, queue-position, and stale calculations are runtime-only
+and never cause per-frame manifest writes.

docs/testing.md

@@ -22,6 +22,7 @@ python -m pytest tests/test_media.py
 python -m pytest tests/test_image_assets.py tests/test_image_workflow.py
 python -m pytest tests/test_storage_manifest.py tests/test_service_contract.py
 python -m pytest tests/test_video_workflow.py
+python -m pytest tests/test_telemetry.py
 ```
 
 Tests use synthetic NumPy frames and temporary directories. The narrowly marked
@@ -55,3 +56,23 @@ and legacy media locations with test-owned temporary directories.
 The video suite also covers FFprobe translation, finalizer cancellation,
 persistent job transitions/recovery, queue bounds, timestamp previews, and full,
 closed, open-ended, suffix, HEAD, and unsatisfiable byte-range responses.
+
+Telemetry tests use an injectable fake monotonic/UTC clock—never real sleeps—to
+cover rolling and average FPS, ETA gating, unknown totals, stalled/stale work,
+progress clamping, queue repositioning, restart reconstruction, terminal
+summaries, and invalid/nonfinite inputs. A 1,000-callback test confirms runtime
+publication remains near four Hz and the rolling sample deque stays bounded.
+FFmpeg fixtures cover progress blocks, CRLF/LF, malformed fields, time
+fallbacks, interleaved progress/diagnostics, bounded stderr, cancellation,
+failure, and reader shutdown.
+
+A local 10,000-callback microbenchmark on the development machine measured
+approximately 0.66 microseconds of telemetry-store overhead per frame callback.
+This is diagnostic rather than a cross-platform performance guarantee; the
+bounded/throttled behavior is the enforced contract.
+
+The Playwright video fixture walks through queued, processing, stale,
+finalizing, verifying, saving, completed, cancel-pending, and canceled states.
+It checks concise formatting, keyboard-accessible details, ordered effects,
+previous-result retention, responsive containment, and Axe results without
+requiring a long render.

docs/video-jobs.md

@@ -20,3 +20,29 @@ sets `recoveredAfterRestart`, removes partial temporary artifacts through the
 temporary-job lifecycle, and requeues below the attempt limit. Missing source
 media and exhausted attempts produce controlled failures. A completed output
 and job are committed in one manifest mutation.
+
+## Render telemetry contract v2
+
+Application 0.2.1 keeps the persistent states above and adds more precise phase
+codes: `waiting`, `preparing_source`, `applying_effects`,
+`finalizing_output`, `verifying_output`, `saving_output`, `completed`,
+`failed`, and `canceled`.
+
+The individual job endpoint includes a stable `telemetry` object. It reports
+queue position, jobs ahead, active/concurrent workers, enabled effect types,
+frame counters, recent and average processing speed, elapsed time, estimated
+remaining time, normalized FFmpeg progress, output bytes, attempt, and recovery
+status. Unknown values are `null`; frame totals, FPS, ETA, and FFmpeg fields are
+never fabricated. ETA is approximate and unavailable until enough timing data
+exists.
+
+High-frequency values live in a lock-protected runtime store. Elapsed
+calculations use a monotonic clock, public timestamps use UTC, recent-speed
+samples are bounded, and publication is throttled to at most about four updates
+per second. Queue positions are runtime-only and do not rewrite queued records.
+
+The manifest remains schema v2. Jobs created before 0.2.1 load with safe
+defaults. Only bounded phase milestones, coarse frame progress, and a terminal
+timing summary are durable. FFmpeg finalization uses program-progress output and
+separately drains bounded diagnostics. Unknown keys and malformed optional
+values are ignored; neither diagnostics nor reader-thread details enter the API.

docs/video-workflow.md

@@ -17,6 +17,21 @@ cancellation between frames and while FFmpeg runs. Clients poll
 `GET /api/video-jobs/{jobId}` or cancel with
 `POST /api/video-jobs/{jobId}/cancel`.
 
+The interface polls detailed telemetry instead of showing only a generic
+percentage. Its concise line distinguishes waiting, preparation, applying the
+complete enabled effect stack to each frame, finalizing MP4, verification,
+transactional saving, and completion. A semantic “Processing details”
+disclosure contains source, recipe, ordered enabled effects, queue, timing,
+attempt, restart, audio, and output-profile information.
+
+Frame totals may be unavailable for unusual media. FFmpeg builds also vary in
+which progress fields they emit, so missing values remain unknown. ETA is an
+estimate and remains unavailable early or while work is stalled. Telemetry is
+polling-based; GlitchCraft does not use WebSockets or server-sent events.
+Screen readers hear phase changes, meaningful progress thresholds, periodic
+long-running updates, and terminal results rather than every frame. A previous
+valid output stays visible while a new render is pending.
+
 Completed metadata is available at
 `GET /api/video-outputs/{outputId}/metadata`. The output resource supports GET,
 HEAD, and one byte range: closed (`bytes=0-99`), open-ended (`bytes=100-`), or