solvecraft/docs/render-interactive.md

# CPU Interactive core

First slice of #8936 under #6201. `job::interactive` prepares bounded CPU
progressive requests and coordinates their lifetime. **It is not yet connected
to the workspace UI.** Entering Render does not start a job. No default,
document format, final export, panel or gizmo is changed by this slice.

`cpu_request` clones an immutable final request. It preserves the camera,
background, shadows, exposure, lighting, resources and transport. Only preview
dimensions and camera/reflection sampling change: maximum 1024 pixels along the
longest edge, rounded to the nearest pixel without enlargement, 16 SPP, seed 0,
one primary and one selected reflection attempt per camera sample. The original
final request stays untouched. Integer aspect rounding is at most half a pixel
(or one pixel for an extreme aspect). Transparent output, another integrator or
unsupported progressive transport returns an error instead of dropping effects.
The existing profile and host still enforce geometry, traversal and memory limits.

## Adapter contract

- Allocate a distinct transient job session for each document's Interactive
  controller. Never recreate a controller with the same session while callbacks
  from its previous instance can arrive. Do not register its jobs in the engine's
  final/export registry. Even its 16-SPP completed image is provisional content.
- Increment `VisualRevision.visual_revision` whenever camera, draft, material,
  visibility, lighting, HDR/resource, method or output intent changes. Include
  changes that leave the document revision unchanged. Capture this counter and
  `scene_generation` atomically with the full request and scene. This core does
  not infer that identity from a setup name or a partial hash.
- Explicit activation calls `enable`; edits call `edit`. Supply monotonic elapsed
  `Duration` values. `capture` issues one ticket after 200 ms without a newer edit.
  Do not evaluate geometry or read files every frame just to compare identity.
- Capture through the existing authoritative engine boundary, prepare the CPU
  request, then admit/submit through the installed CPU host using
  `CaptureTicket::job_id()`. Pass the resulting handle to `attach`
  with the original ticket. Delayed jobs are cancelled, including a wrong serial
  or generation in our dedicated preview session. A foreign session is rejected
  without cancelling its work, even if its handle arrived through a misrouted
  callback. Final jobs must keep their distinct engine session.
  Report a failed capture through `capture_failed`; failure waits for an edit or
  explicit resume, rather than retrying every frame.
- Read only `current()` to publish checkpoint pixels. The existing host provides
  immutable previews, sample counts, sequence and final target bytes. Their job
  and revision must remain attached to the displayed image. A copied handle or
  retained texture is not permission to display it as current after an edit.
- Pause may retain an immutable checkpoint in the adapter, explicitly labelled
  paused and stale after edits. It cancels work. Resume uses the latest revision.
  Leave Render or change documents with `disable`; Drop also cancels owned work.
- Before a manual final starts, call `set_final_active(true)`. This cancels only
  Interactive work and prevents new capture tickets. Call it with false after the
  final finishes; an enabled, unpaused controller then groups the latest edits
  again. No method here cancels a final job or exports an image.

The UI adapter, registered activation/pause commands, current-request identity
capture, retained paused texture and visual acceptance remain a following slice
coordinated with #8000/#7375. This is not a claim that those integration gates or
the installed application's shadow defect are fixed.