Play the architecture's history between two commits on the web map

backlog/tasks/task-563 - Play-the-architectures-history-between-two-commits-on-the-web-map.md

@@ -1,10 +1,11 @@
 ---
 id: TASK-563
 title: Play the architecture's history between two commits on the web map
-status: To Do
-assignee: []
+status: Done
+assignee:
+  - '@codex'
 created_date: '2026-10-07 23:16'
-updated_date: '2026-10-08 15:31'
+updated_date: '2026-10-09 08:01'
 labels:
   - senior
 dependencies: []
@@ -18,6 +19,19 @@ references:
   - src-core
   - web-server
   - web-page
+modified_files:
+  - src/viewers/web/revision/history.ts
+  - src/viewers/web/map-session.ts
+  - src/viewers/web/data.ts
+  - src/viewers/web/revision/playback.ts
+  - src/viewers/web/revision/control.ts
+  - src/viewers/web/render.ts
+  - src/viewers/web/revision/view.ts
+  - docs/viewers/web/history-playback.md
+  - groma/systems/groma-md/containers/cli/components/history.md
+  - groma/systems/groma-md/containers/export/components/playback.md
+  - groma/systems/groma-md/containers/cli/components/web-server.md
+  - groma/systems/groma-md/containers/export/components/revision-control.md
 type: feature
 ordinal: 3
 ---
@@ -44,6 +58,20 @@ Build on revisions and snapshots (src/history/revisions.ts, src/history/snapshot
 <!-- DOD:BEGIN -->
 - [ ] #1 Acceptance criteria have objective verification evidence.
 - [ ] #2 Relevant checks pass and changes remain task-scoped.
-- [ ] #3 Public contracts or documentation are updated when behavior changes.
-- [ ] #4 Implementation Plan reflects the final approach; correction history and verification are recorded in Implementation Notes.
+- [x] #3 Public contracts or documentation are updated when behavior changes.
+- [x] #4 Implementation Plan reflects the final approach; correction history and verification are recorded in Implementation Notes.
 <!-- DOD:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a live-only playback controller to the existing two-commit revision selection, with Play/Stop, speed, commit metadata and persistent range URLs. 2. Cache historical snapshots and owned source text in the web session, select compatible commits in existing Git order, and preload upcoming step comparisons. 3. Reuse comparison layout, keyed map morphing and reduced-motion handling for each step; finish with the selected full-range comparison. 4. Update the web guide, inspect the supported flow and task-scoped diff without running builds or tests, then scan and curate new files under their existing responsibilities. No new tests: the user explicitly prohibits running tests; record verification limits rather than claiming performance evidence.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Shared-file coordination: TASK-562 also records data.ts and map-session.ts; TASK-565 records map-session.ts, render.ts and the web index; TASK-568 records map-session.ts. Playback uses separate imports, endpoint and URL hunks and preserves their work. Playback documentation is a separate page to avoid overlapping edits to the web index.
+
+Implemented Play/Stop and 0.5×/1×/2×/4× speed in the live revision control; the selected range remains in the URL and header while a caption identifies each frame. The web session caches architecture and source snapshots; playback filters unreadable revisions in Git list order and preloads the next two comparisons. Completion restores the full-range comparison. Existing comparison layout, keyed map morphing and reduced-motion behavior are reused. Static export and terminal code were not changed. Specification and quality review traced revision selection -> compatible range -> cached snapshots -> prefetched comparison frames -> map application -> final comparison. Type checking (tsc --noEmit), focused Biome lint and git diff --check pass; the one reported complexity warning is in the existing paintDetailsState function, outside this change. No builds or tests were run, as instructed. No browser automation tool is available in this session, so interactive behavior and fifty-commit smoothness remain unverified; acceptance criteria are not checked without that evidence. Architecture scan completed, and history.ts/playback.ts were combined into Web host/Revision selector with their responsibilities documented.
+<!-- SECTION:NOTES:END -->

docs/viewers/web/history-playback.md

@@ -0,0 +1,42 @@
+# Play architecture history
+
+In the live web map, choose a commit, open **compare 2 revisions**, and choose
+an older start commit. **Play** walks the range from oldest to newest. The speed
+selector offers 0.5×, 1×, 2×, and 4×; **Stop** leaves the current step visible.
+The caption shows that step's short commit ID, subject, and local date and time.
+The two revision fields keep the chosen range. Its `from` and `revision` URL
+parameters reopen the range without starting playback automatically.
+
+Only commits readable by the current architecture reader are visited, in the
+same Git order as the revision picker. Both endpoints must be readable. The
+working tree is not a playback endpoint. Playback is available only in the live
+web map; static exports and the terminal viewer keep their existing behavior.
+
+The first frame shows the start snapshot. Each later frame uses the comparison
+from the previous readable commit to the next, including retained removed
+elements and their parent context. The map's existing keyed geometry transition
+moves shared buildings and routes and grows new ones. Reduced motion applies
+each frame immediately. When playback finishes, the original start-to-end
+comparison returns with its changes bar and stepper. A person can pan and zoom
+while playback continues.
+
+[`revision/control.ts`](../../../src/viewers/web/revision/control.ts) owns the
+selected revision and connects the playback controls to the browser session.
+[`revision/playback.ts`](../../../src/viewers/web/revision/playback.ts) owns the
+clock, cancellation, speed, caption, range, and a cache of requested frames. It
+loads the next two frames ahead. Stopping invalidates pending frame applications
+without discarding their cached data.
+
+The live [`map-session.ts`](../../../src/viewers/web/map-session.ts) serves
+`/playback.json?from=<commit>&revision=<commit>` to identify readable frames.
+[`revision/history.ts`](../../../src/viewers/web/revision/history.ts) shares
+in-flight historical reads for that server session: each commit's architecture,
+layout, and owned source text are loaded once. Comparisons reuse those snapshots;
+source files owned only on the other side are read and cached when needed.
+Compatibility checks populate the same cache used by playback. Working-tree
+comparisons continue to read current files.
+
+Playback is transient browser state, not stored architecture knowledge. It adds
+no OKF metadata or C4 element type. Git commits and the existing architecture
+documents remain the portable history; the browser revision selector and web
+host own its playback interpretation.

groma/systems/groma-md/containers/cli/components/web-server.md

@@ -17,11 +17,14 @@ groma:
       symbol: renderSetupPage
     - scanner: typescript
       file: src/viewers/web/startup/scanners.ts
+    - scanner: typescript
+      file: src/viewers/web/revision/history.ts
+      symbol: createRevisionHistory
   group: Browser delivery
 description: Serves the local browser map and live architecture operations
 ---
 
-Starts the local HTTP server. Serves project setup and connects the browser to architecture, scanner, task, and source operations.
+Starts the local HTTP server. Serves project setup and connects the browser to architecture, scanner, task, and source operations. Keeps historical architecture snapshots and source text in a session cache, identifies readable frames for playback, and reuses snapshots for commit comparisons.
 
 ## Relationships
 

groma/systems/groma-md/containers/export/components/revision-control.md

@@ -11,11 +11,14 @@ groma:
       symbol: createRevisionControl
     - scanner: typescript
       file: src/viewers/web/revision/view.ts
+    - scanner: typescript
+      file: src/viewers/web/revision/playback.ts
+      symbol: createRevisionPlayback
   group: Architecture panels
-description: Lists Git architecture revisions and opens a snapshot
+description: Browses, compares and plays readable Git architecture revisions
 ---
 
-Lists available Git revisions and opens the selected architecture snapshot.
+Owns the selected revision or comparison and the commit search fields. Plays a selected commit range in Git order with speed and Stop controls, shows the current commit, preloads upcoming frames, and finishes on the full-range comparison. The browser keeps the selected range in its URL and uses the existing map motion for each step.
 
 ## Relationships
 

src/viewers/web/data.ts

@@ -13,6 +13,8 @@ export interface WebDataSource {
   onScanners?: (state: ScannerSettings) => void
   readWorld(revision?: string, from?: string): Promise<WebPayload>
   readRevisions(): Promise<WebRevision[]>
+  /** Live-only compatible commits, ordered from the selected start to end. */
+  readPlaybackRevisions?(revision: string, from: string): Promise<WebRevision[]>
   readCode(element: string, revision?: string, from?: string): Promise<readonly CodeFile[]>
   readSource(element: string, file: string, revision?: string, from?: string): Promise<SourcePayload>
   readTask(id: string): Promise<WorkItemDetails>
@@ -68,6 +70,9 @@ function liveDataSource(): WebDataSource {
     readRevisions() {
       return responseJson('/revisions.json')
     },
+    readPlaybackRevisions(revision, from) {
+      return responseJson(selected('/playback.json', { revision, from }))
+    },
     readWorld(revision, from) {
       return responseJson(selected('/world.json', { revision, from }))
     },

src/viewers/web/map-session.ts

@@ -15,6 +15,7 @@ import { readComparison } from '../../history/snapshots.ts'
 import { measuredSheetScene } from '../../sheet/scene.ts'
 import { listGitRevisions, withGitRevision } from '../../history/revisions.ts'
 import { renderPage } from './page.ts'
+import { createRevisionHistory } from './revision/history.ts'
 import type { WebMapPayload, WebPayload, WebRevision, WebWorkPayload } from './payload.ts'
 import { bundleRenderer, loadMapRoot } from './runtime.ts'
 import { coverThemes, generateCovers, type CoverImages } from './sharing/images.ts'
@@ -75,6 +76,7 @@ export async function createWebMapSession(
 ): Promise<{ fetch: (request: Request) => Promise<Response>; close: () => Promise<void> }> {
   options.onProgress?.({ phase: 'preparing-viewer' })
   const renderer = await bundleRenderer()
+  const history = createRevisionHistory(repositoryRoot)
   const workSource = options.workSource ?? backlogPlugin.create(repositoryRoot)
   let revisions: WebRevision[] = []
   let revisionRead: Promise<WebRevision[]> | undefined
@@ -120,7 +122,8 @@ export async function createWebMapSession(
     const revision = (await readRevisions()).find(candidate => candidate.id === revisionId)
     if (revision === undefined) return new Response('Unknown Groma revision', { status: 404 })
     try {
-      const snapshot = await loadMap(repositoryRoot, revisions, revision)
+      const { map: stored } = await history.snapshot(revision)
+      const snapshot = { ...stored, revision, revisions }
       if (snapshot.project === null) throw new Error('No Groma architecture in this commit')
       return {
         generation: map.generation,
@@ -157,7 +160,9 @@ export async function createWebMapSession(
 
   /** Both revisions' architecture and the changes between them, without laying out the map. */
   async function compare(from: WebRevision | null, to: WebRevision | null) {
-    const compared = await readComparison(repositoryRoot, from, to)
+    const compared = from !== null && to !== null
+      ? await history.compare(from, to)
+      : await readComparison(repositoryRoot, from, to)
     for (const component of Object.values(compared.comparison.components)) {
       for (const { file } of component.files) sourceFiles.add(file)
     }
@@ -397,6 +402,12 @@ export async function createWebMapSession(
     }],
     ['/render.js', rendererResponse],
     ['/revisions.json', async () => Response.json(await readRevisions())],
+    ['/playback.json', async (_request, url) => {
+      try {
+        return Response.json(await history.range(await readRevisions(),
+          url.searchParams.get('from') ?? '', url.searchParams.get('revision') ?? ''))
+      } catch (error) { return comparisonError(error) }
+    }],
     ['/world.json', worldResponse],
     ['/code.json', selectedSourceResponse],
     ['/source.json', selectedSourceResponse],

src/viewers/web/render.ts

@@ -145,8 +145,8 @@ function zoomStep(factor: number, control: HTMLElement): void {
 
 function syncUrl(): void {
   const query = writeView({
-    ...(revisionControl.selected === undefined ? {} : { revision: revisionControl.selected }),
-    ...(revisionControl.from === undefined ? {} : { from: revisionControl.from }),
+    ...(revisionControl.urlRevision === undefined ? {} : { revision: revisionControl.urlRevision }),
+    ...(revisionControl.urlFrom === undefined ? {} : { from: revisionControl.urlFrom }),
     ...(source.file === undefined ? {} : { file: source.file }),
     ...(source.line === undefined ? {} : { line: source.line }),
     selection, flows: activeFlows,

src/viewers/web/revision/control.ts

@@ -2,6 +2,7 @@ import type { WebDataSource } from '../data.ts'
 import { bindPopover } from '../atoms/popover.ts'
 import type { WebBootPayload, WebPayload, WebWorkPayload } from '../payload.ts'
 import { NARROW_HEADER, pendingPairFields, revisionFields, revisionOptions, snapshotNotice, type RevisionField } from './view.ts'
+import { createRevisionPlayback } from './playback.ts'
 
 interface RevisionControlOptions {
   box: HTMLElement
@@ -100,6 +101,16 @@ export function createRevisionControl(options: RevisionControlOptions) {
   let navigating = false
   let pendingWorld: WebPayload | undefined
   let appliedWork = boot.workGeneration
+  const playback = createRevisionPlayback({
+    root, data, current: () => current, repaint: paint,
+    present(payload, first) {
+      editing = undefined
+      setRevision(payload)
+      if (first) applyRevision(payload)
+      else applyWorld(payload)
+    },
+    error: showError,
+  })
 
   const selected = () => current.revision?.id
   const from = () => current.comparison === undefined ? undefined : current.comparison.from?.id ?? ''
@@ -151,17 +162,23 @@ export function createRevisionControl(options: RevisionControlOptions) {
     if (editing === undefined || singleSnapshot) delete box.dataset.editing
     else box.dataset.editing = editing
     // Live refreshes repaint often; untouched fields keep their focus and do not replay their entrance.
-    const nextFields = starting() ? pendingPairFields(current.revision) : revisionFields(current)
+    const range = playback.range
+    const displayed = range === undefined ? current : {
+      ...current, revision: range.to,
+      comparison: { components: {}, relationships: {}, ...current.comparison, from: range.from },
+    }
+    const nextFields = starting() ? pendingPairFields(current.revision) : revisionFields(displayed)
     if (nextFields !== paintedFields) { fields.innerHTML = nextFields; paintedFields = nextFields }
     search.hidden = !opened || singleSnapshot
     search.placeholder = placeholders[editing ?? 'revision']
     search.setAttribute('aria-label', searchLabels[editing ?? 'revision'])
     paintCompareEntry()
-    end.hidden = current.comparison === undefined && !starting()
+    end.hidden = current.comparison === undefined && !starting() && range === undefined
     end.title = starting() ? 'Cancel comparison' : 'End comparison'
     end.setAttribute('aria-label', end.title)
     menu.hidden = !opened
     placeMenu()
+    playback.paint()
   }
 
   function close(): void {
@@ -219,6 +236,7 @@ export function createRevisionControl(options: RevisionControlOptions) {
   }
 
   function open(field: RevisionField): void {
+    playback.cancel()
     // Widths are read from the closed layout, also when another field is the search right now.
     close()
     const width = (name: RevisionField) => fields.querySelector(`[data-field="${name}"]`)?.getBoundingClientRect().width
@@ -233,6 +251,7 @@ export function createRevisionControl(options: RevisionControlOptions) {
 
   function setRevision(payload: WebPayload): void {
     current = payload
+    playback.remember(payload)
     body.toggleAttribute('data-revision', !live())
     body.toggleAttribute('data-comparison', payload.comparison !== undefined)
     paint()
@@ -250,6 +269,7 @@ export function createRevisionControl(options: RevisionControlOptions) {
   }
 
   async function load(revision?: string, starting?: string, reset = true): Promise<void> {
+    playback.cancel()
     const loading = ++request
     navigating = true
     error.hidden = true
@@ -312,7 +332,12 @@ export function createRevisionControl(options: RevisionControlOptions) {
     const option = event.target.closest<HTMLButtonElement>('.revision-option')
     if (option !== null && !option.disabled) chooseRevision(option.dataset.revision!)
   })
-  end.addEventListener('click', () => { if (starting()) close(); else void load(selected()) })
+  end.addEventListener('click', () => {
+    const destination = playback.range?.to.id ?? selected()
+    playback.cancel()
+    if (starting()) close()
+    else void load(destination)
+  })
   // The list follows its field whenever the header reflows the box.
   new ResizeObserver(placeMenu).observe(box)
 
@@ -340,6 +365,8 @@ export function createRevisionControl(options: RevisionControlOptions) {
   return {
     get selected() { return selected() },
     get from() { return from() },
+    get urlRevision() { return playback.range?.to.id ?? selected() },
+    get urlFrom() { return playback.range?.from.id ?? from() },
     get comparison() { return current.comparison },
     get live() { return live() },
     paintProjectEdit(root: ParentNode) {