Add progressive controls and a focused effect workspace

.gitignore

@@ -12,6 +12,7 @@ htmlcov/
 node_modules/
 playwright-report/
 test-results/
+.tmp/
 data/
 build/
 dist/

docs/architecture.md

@@ -58,3 +58,23 @@ and centralized parameter scaling. This separation keeps routes and the video
 loop free of effect-specific timing rules. Smooth variation derives random
 anchors on demand and is independent of processing order; no mutable global RNG
 or previous-frame buffer exists.
+# Progressive control resolution
+
+The progressive layer is upstream of Recipe v2 validation and temporal compilation:
+strict Basic contract → registry profile → canonical Recipe v2 effect fragment. Reverse
+inference is pure and bounded to 101 candidates. Neither path decodes media or adds render
+overhead. UI ownership and disclosure state are deliberately outside persisted contracts.
+
+# Focused workspace state
+
+The focused editor is a Jinja shell enhanced by dependency-free JavaScript. Existing effect
+cards stay inside the upload form so Recipe v1/v2 serialization does not change. In video
+mode the cards are mounted in the inspector and non-selected cards are both hidden and
+inert; in image mode they return to the existing effect grid and temporal controls are
+hidden. This transitional DOM move preserves per-effect values without duplicate IDs.
+
+Selection, mobile view, and disclosure state are client-only. Effect enablement is distinct
+from selection and feeds the existing Recipe v2 `enabled` field. Metadata loads once on
+startup, resolver requests are isolated per effect, and selection causes no API traffic.
+Preview and schedule controllers retain their existing revision guards. A failed preview
+keeps the previous object URL until a successful replacement is available.

docs/interface-system.md

@@ -0,0 +1,64 @@
+# Interface system
+
+GlitchCraft uses a precision-slate interface that keeps media and effect parameters more
+prominent than application chrome. The system borrows the shared family grammar of Web
+Video Optimizer without copying its logo, product language, React components, routes, or
+workflow assumptions.
+
+## Semantic color
+
+- App background: `#080c12`
+- Workspace: `#0e151f`
+- Sidebar: `#090e15`
+- Surface: `#141d29`
+- Elevated surface: `#1a2533`
+- Recessed surface: `#0c121b`
+- Hover surface: `#202c3c`
+- Selected surface: `#1c2440`
+- Iris interaction: `#6a5bcf`
+- Ember transformation: `#f2763f`
+- Success: `#35c981`
+- Warning: `#e8b44d`
+- Danger: `#f06a72`
+
+Iris identifies selection, focus, and primary interaction. Ember identifies transformation
+actions such as pattern regeneration and full processing. Green is reserved for genuine
+completion or valid local status. Status always includes text and never relies on color.
+
+## Workspace layout
+
+At 1180px and above, video mode uses a 230–280px effects rail, a fluid media preview, and a
+320–400px inspector. The render dock spans all three regions. From 800px through 1179px,
+the rail remains beside a preview/inspector stack. Below 800px, an accessible Preview,
+Effects, Inspector, and Render switch exposes one focused region at a time.
+
+The effects list uses separate checkbox and selection controls. Selection has an iris rail
+and `aria-current`; enablement remains independently operable. One effect inspector is
+visible at a time. Non-selected inspectors remain mounted to preserve state but are hidden
+and inert so they cannot receive focus.
+
+## Control hierarchy
+
+Each effect inspector is ordered:
+
+1. Basic intensity, numeric value, burst bounds, duration context, resolved summary, and
+   reset state.
+2. Existing Appearance parameters.
+3. Semantic Advanced disclosure with exact timing, envelope, and variation fields.
+
+The authored `.effect-intensity-slider` has a visible progress track and thumb, a practical
+minimum width of 180px, a 32px hit area, WebKit and Mozilla styling, forced-colors support,
+and an `aria-valuetext` category. Numeric and range controls clamp and synchronize.
+
+## Interaction and failure rules
+
+The shell must render before metadata. Metadata failure is recoverable in the rail and does
+not erase a valid preview. Effects resolve independently with stale-request cancellation
+and per-effect retry. Selection never requests metadata, resolves settings, compiles a
+schedule, uploads media, refreshes a preview, or starts a render. An enabled unresolved
+effect cannot be processed.
+
+Focus rings remain visible, hidden panels are inert, icon-free buttons use explicit action
+labels, reduced motion is honored, and forced-colors mode receives simplified selection and
+slider treatments. Screenshot and geometry review cover 1440 x 900, 1280 x 720,
+1024 x 768, 768 x 1024, 390 x 844, and 360 x 800.

docs/product-direction.md

@@ -5,20 +5,20 @@ GlitchCraft is becoming:
 > A local visual-effects workspace for building reproducible glitch, noise,
 > pixel, scan, distortion, and signal treatments for images and video.
 
-A later interface will align with ColorCraft and Web Video Optimizer through
-shared principles: system typography, semantic design tokens, consistent spacing,
-a related application shell, familiar panels/notices/status/forms, desktop
-workspace and responsive mobile navigation, clear local-processing and readiness
-indicators, and comparable control with progressive disclosure.
+The current focused video interface aligns with Web Video Optimizer through shared
+principles: system typography, semantic design tokens, consistent spacing, a related
+precision-slate shell, familiar panels/notices/status/forms, desktop workspace and
+responsive mobile navigation, clear local-processing and readiness indicators, and
+progressive disclosure. GlitchCraft keeps its own name, mark, effect vocabulary, Flask
+routes, and Recipe behavior.
 
 The family relationship is a shared precision-oriented shell and interaction
 grammar. GlitchCraft will retain its own signal, interference, and transformation
 identity; another application's visual theme will not be copied wholesale.
 
-The current sequence deliberately avoids a final visual redesign. It establishes
-inspectable recipes, deterministic processing, persistent image and video
-identity, bounded cancellable jobs, Craft discovery metadata, truthful
-readiness, and testable boundaries needed by that future workspace. GlitchCraft
+The current sequence establishes inspectable recipes, deterministic processing,
+persistent image and video identity, bounded cancellable jobs, Craft discovery metadata,
+truthful readiness, and a testable focused editor. GlitchCraft
 owns creative treatment; Web Video Optimizer remains the detailed
 delivery-optimization and packaging tool.
 
@@ -38,3 +38,10 @@ 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
 workspace and proposed 5175/4200 frontend/API split are also deferred.
+# Progressive controls milestone
+
+Version 0.3.1 makes the deterministic temporal engine approachable without hiding its exact
+contracts. It is a focused control-resolution layer presented through an effects rail,
+media-first preview, selected-effect inspector, and render dock in the current Flask and
+JavaScript workspace. A full timeline, draggable events, manual-event UI, presets, React,
+stateful temporal feedback, optical flow, and codec datamoshing remain future work.

docs/progressive-controls.md

@@ -0,0 +1,63 @@
+# Progressive effect controls
+
+GlitchCraft 0.3.1 adds a progressive control layer for Recipe v2 video effects. It does
+not add a recipe format. Basic controls resolve immediately to the same exact `intensity`,
+`timing`, `envelope`, and `variation` fields shown by Advanced controls and stored in jobs
+and outputs.
+
+## Basic and Advanced ownership
+
+Basic **Intensity** is an overall effect-amount macro from 0 through 100. Depending on the
+effect profile it changes visual strength, activity, or both. Advanced **Visual Strength**
+is the persisted 0-through-1 severity while active. Advanced activity fields control exact
+frequency and cooldown behavior.
+
+Burst effects expose minimum and maximum lengths in integer decoded frames. The scheduler
+selects each duration deterministically within that range. The UI also shows seconds using
+the uploaded source frame rate. Continuous noise, static, and scan lines keep their natural
+continuous behavior; their duration controls become relevant only after choosing burst
+timing in Advanced controls.
+
+An effect is **Basic-derived** while its canonical fields match the resolver. Editing an
+Advanced value marks it **Custom** and never discards that value when the disclosure closes.
+**Reset to Basic controls** explicitly replaces the custom fields. Moving Basic Intensity
+after customization is also an explicit replacement.
+
+## Contract and profiles
+
+`BasicEffectControlContract` version 1 accepts an effect type, Basic Intensity, duration
+bounds, an optional source range, and an optional regeneration request. The pure
+`POST /api/effects/resolve-basic` endpoint uses Basic effect profile version 1 and performs
+no media access, schedule compilation, FFmpeg work, or persistence.
+
+Profiles are owned by the Python effect registry and returned by `GET /api/effects`.
+Horizontal glitch, frame shift, color bleed, pixelation, and flicker use effect-specific
+nonlinear strength/frequency/cooldown mappings. Noise, static, and scan lines primarily
+map visual strength and remain continuous. The frontend contains no duplicated profile
+numbers.
+
+`POST /api/effects/infer-basic` performs a bounded search over the 101 possible macro
+values and reports `exact`, `approximate`, or `custom`. Approximate inference never rewrites
+the recipe. Advanced configurations outside a profile remain untouched.
+
+## Reproducibility
+
+Persisted Recipe v2 records contain exact resolved values and the root seed, not the Basic
+macro, UI ownership, summaries, schedule output, or profile version. Future profile changes
+therefore cannot alter an existing output. **Regenerate all effect patterns** changes the
+root seed deliberately, refreshes schedule and still preview requests, and affects every
+stochastic effect without re-uploading or rendering a persistent output.
+
+The Flask/Jinja and dependency-free JavaScript interface now presents these controls in a
+focused video workspace. The effect rail separates enablement from selection, and the
+inspector keeps every effect's Basic, Appearance, and Advanced state mounted while exposing
+only the selected effect. Selection and disclosure changes are local UI operations: they do
+not resolve controls, compile a schedule, upload media, request a preview, or render output.
+Disabled effects remain selectable so their preserved settings can be inspected.
+
+Metadata and resolver startup are intentionally independent. The shell renders before
+metadata, each effect reports its own resolver state and retry action, stale resolutions are
+aborted, and `Promise.allSettled` prevents one profile failure from blocking the other seven.
+An unresolved enabled effect cannot be submitted as a valid video recipe. The final editable
+timeline, manual-event UI, presets, React workspace, stateful feedback, and codec datamoshing
+remain deferred.

docs/recipes.md

@@ -1,6 +1,6 @@
 # Effect recipes
 
-GlitchCraft 0.3.0 supports recipe schema versions 1 and 2. Recipe documents are
+GlitchCraft 0.3.1 supports recipe schema versions 1 and 2. Recipe documents are
 independently versioned inside manifest-v2 records, so adding Recipe v2 does not
 change the manifest, storage, or video-job schemas.
 
@@ -84,3 +84,11 @@ may contain Recipe v1 or Recipe v2. Existing files load without migration or
 rewriting. Recipe v2 persists only its portable contract; compiled intervals and
 random-generator state are never stored. Restart recovery recompiles the same
 schedule from the recipe, source timeline, effect ID, and isolated namespaces.
+# Progressive Recipe v2 controls
+
+Basic controls are an authoring convenience, not a persisted schema. Basic Intensity is an
+overall amount macro; Advanced Visual Strength remains the Recipe v2 `intensity` value and
+Advanced Activity remains exact timing frequency/cooldown. Resolution stores only canonical
+Recipe v2 fields. Profile version 1 is not needed to replay an output. Burst lengths are
+deterministically selected inside the stored frame bounds, and changing the root seed
+regenerates every stochastic pattern. See [progressive-controls.md](progressive-controls.md).

docs/service-contract.md

@@ -40,7 +40,7 @@ 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.3.0 advertises video-job contract v2 and the
+Application version 0.3.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
@@ -61,3 +61,13 @@ Temporal capability slugs are `temporal-effect-modulation`,
 events timing; all five envelope curves; and per-frame, per-event, and smooth
 variation. It does not claim feedback, optical flow, datamoshing, keyframes, or
 timeline editing.
+# Progressive-control endpoints
+
+- `POST /api/effects/resolve-basic` resolves strict Basic contract v1 without media or writes.
+- `POST /api/effects/infer-basic` reports exact, approximate, or custom ownership.
+- `GET /api/effects` includes registry-owned Basic profile version 1 metadata.
+- `/metadata` reports the versions, endpoints, supported effects, range 0–100, and Advanced
+  customization availability.
+
+Stable capability slugs are `progressive-effect-controls`, `basic-effect-intensity`,
+`effect-burst-range`, and `effect-pattern-regeneration`.

docs/storage.md

@@ -1,6 +1,6 @@
 # Persistent media storage
 
-GlitchCraft 0.3.0 uses a configurable managed data root:
+GlitchCraft 0.3.1 uses a configurable managed data root:
 
 ```text
 data/
@@ -58,7 +58,7 @@ 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.3.0. Telemetry contract v2 adds only
+Manifest schema remains v2 in application 0.3.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

docs/temporal-effects.md

@@ -129,3 +129,9 @@ Temporal modulation evaluates independent decoded frames. It does not use
 previous-frame feedback, frame echo, motion trails, optical flow, or stateful
 blending. Codec datamoshing changes compressed-frame or motion-vector structures
 and remains a separate future processing domain.
+# Progressive temporal authoring
+
+The Basic control resolver selects existing continuous or sporadic timing, envelope, and
+variation contracts without changing compilation. Exact schedules remain authoritative and
+unchanged for identical canonical Recipe v2 fields and seeds. Basic burst bounds are exact
+frames; the existing isolated RNG namespace selects deterministic event durations.

docs/testing.md

@@ -38,6 +38,7 @@ Playwright workflow:
 npm ci
 npx playwright install chromium
 npm run test:browser
+npm run review:ui-screens
 ```
 
 The browser suite starts the Flask application and generates its image fixture
@@ -77,6 +78,19 @@ It checks concise formatting, keyboard-accessible details, ordered effects,
 previous-result retention, responsive containment, and Axe results without
 requiring a long render.
 
+Focused-workspace browser coverage also checks metadata loading/failure/retry, preview
+retention during metadata failure, one isolated resolver failure, slow and stale resolver
+responses, disabled-effect selection, custom state across effect switches and reset,
+selection/request-count invariants, duplicate IDs, inert hidden panels, range geometry,
+six required viewport sizes, horizontal containment, performance marks, and Axe with no
+serious or critical findings.
+
+`npm run review:ui-screens` generates 14 deterministic Chromium captures in
+`.tmp/ui-review/`: six desktop states at 1440 x 900, one medium state at 1024 x 768, three
+tablet views at 768 x 1024, and four mobile views at 390 x 844. The fixtures have stable
+metadata, source identity, seed, schedule, preview artwork, telemetry, and output state.
+The `.tmp` directory is ignored and screenshots must be inspected manually during UI review.
+
 Recipe v1 golden regressions hash representative frames at indexes 0, 1, and 17
 to prove the legacy RNG namespace and pixels remain exact. Temporal tests cover
 strict Recipe v2 parsing, rational conversion, every timing mode, event sorting
@@ -101,3 +115,15 @@ one-hour 60 fps synthetic schedule containing 5,810 events compiled in 60.33 ms.
 These are diagnostic measurements, not platform guarantees; bounded event
 counts, one compile per job, binary-search lookup, and inactive-operation
 skipping are the enforced properties.
+# Progressive-control validation
+
+Resolver matrices cover all eight effects at Basic Intensity 0, 25, 50, 75, and 100.
+Round-trip inference, custom fields, duration bounds, strict APIs, metadata, accessibility,
+responsive layout, seed regeneration, schedule refresh, and existing Recipe v1/v2
+regressions are covered. Benchmarks resolve and infer all eight profiles 10,000 times.
+
+On the PR development machine, 80,000 individual resolutions completed in 4.454 seconds
+(55.676 µs per effect; 0.445 ms per batch of eight). After bounded candidate-cache warmup,
+80,000 inferences completed in 20.133 seconds (251.658 µs per effect; 2.013 ms per batch of
+eight). Resolution performs no media decoding, FFmpeg work, or schedule compilation, and
+resolved recipes add no render-time overhead.

docs/video-workflow.md

@@ -49,8 +49,10 @@ chapters, attachments, multiple audio tracks, and hardware encoding are not
 preserved or implemented. Detailed delivery optimization remains the
 responsibility of Web Video Optimizer.
 
-Video mode now builds Recipe v2 from `/api/effects` registry metadata. Advanced
-timing disclosures appear only for enabled video effects and expose continuous,
+Video mode now builds Recipe v2 from `/api/effects` registry metadata. The effects rail
+separates enablement from selection. The selected inspector remains available for disabled
+effects and exposes Basic, Appearance, and Advanced controls. Advanced timing disclosures
+expose continuous,
 range, and sporadic modes, bounds, frequency, duration, cooldown, attack,
 release, curve, maximum intensity, and supported variation choices. Image mode
 continues to build Recipe v1.
@@ -62,3 +64,17 @@ active effects. Moving the timestamp never changes the root seed or schedule,
 and the previous valid still remains visible while its replacement loads.
 Manual events are supported by the API contract but do not yet have a full
 editor.
+
+The preview is now the visual center of the focused workspace. Empty, loading, ready, and
+recoverable error states keep the shell geometry stable. Timestamp and active-effect
+feedback remain adjacent to the media, and the previous valid frame is retained while a
+new frame loads or fails. Schedule inspection, pattern regeneration, audio choice,
+processing, cancellation, progress, and completed output are grouped in the render dock.
+# Basic video controls
+
+Enabled video effects show Basic Intensity, burst bounds, and a resolved summary before a
+semantic Advanced disclosure. Advanced edits become Custom until explicitly reset.
+Regenerating changes the shared root seed, not the source or effect fields. Schedule and
+still-preview requests remain abortable and revision guarded; the previous valid preview
+and schedule remain visible while replacements arrive. Jump-to-next uses inspected events
+and does not change the seed or schedule.