Add transcription architecture and diagrams

components/simple-transcription/ARCHITECTURE.md

@@ -0,0 +1,115 @@
+# Transcription Interface Architecture
+
+This document explains the current TPEN transcription interface structure, ownership boundaries, and data/event flow.
+
+## Scope
+
+This describes the interface loaded from:
+
+- interfaces/transcription/index.html
+- components/simple-transcription/index.js
+- components/projects/project-header.js
+
+## Component Inventory
+
+Top-level composition:
+
+1. tpen-simple-transcription
+2. tpen-project-header
+3. tpen-transcription-block
+4. tpen-workspace-tools
+
+**Note**: `tpen-line-image` and `tpen-image-fragment` are used by `tpen-transcription-interface` (`interfaces/transcription/index.js`), not by `tpen-simple-transcription`. This component handles image display inline via raw `<img>` elements and the `adjustImages()` method.
+
+Header composition:
+
+1. project title display
+2. canvas selector (select)
+3. tpen-layer-selector
+4. tpen-column-selector
+5. line indicator
+6. navigation controls (home, manage project, profile)
+
+Workspace composition:
+
+1. focused line image viewport (`#imgTop` — raw `<img>` with custom zoom/pan via `adjustImages()`)
+2. transcription input workspace (`tpen-transcription-block`)
+3. workspace tools launcher/controls (`tpen-workspace-tools`)
+4. remaining image fragment panel (`#imgBottom` — raw `<img>` showing the rest of the canvas)
+
+## Visual Regions
+
+The interface is intentionally split into 3 regions:
+
+1. Header: navigation and context controls
+2. Workspace: line-focused transcription work area
+3. Split-screen tools panel: optional right-pane tools
+
+See the diagram reference in DIAGRAMS.md for detailed flow diagrams.
+
+## Data Truth Locations
+
+The table below defines ownership for key state.
+
+| Data | Source of truth | Primary readers | Mutated by |
+| --- | --- | --- | --- |
+| Active project graph (layers/pages/columns) | TPEN.activeProject | header, selectors, interface shell | project load/update flows |
+| Current page selection | URL query pageID and TPEN.screen.pageInQuery | header, interface, selectors | header canvas selector, page navigation |
+| Active line index | TPEN.activeLineIndex | header line indicator, interface, tools | tpen-transcription-block (`moveToLine()`), column selector |
+| Interface UI mode (split-screen/tool selection) | tpen-simple-transcription local state | interface shell and tool pane | splitscreen events and UI interactions |
+| Annotation page items for column ordering | component-local cached page object | column selector, transcription logic | vault fetch + ordering utility |
+
+## Minimal Knowledge Boundaries
+
+### Page Shell
+
+- Knows which top-level interface element to mount.
+- Does not own transcription state.
+
+### Interface Shell (tpen-simple-transcription)
+
+- Owns orchestration state: active page data, active line, split-screen status.
+- Coordinates events among header, workspace, and tools.
+- Does not implement selector internals or tool internals.
+
+### Header (tpen-project-header)
+
+- Owns navigation controls and contextual display (project title, line indicator).
+- Emits navigation changes through URL/event interactions.
+- Does not render transcription content.
+
+### Selectors (layer, column, page/canvas)
+
+- Convert user input into selection events.
+- Do not manage rendering of line content.
+
+### Workspace Components
+
+- tpen-transcription-block handles line transcription interactions.
+- Image display (`#imgTop`, `#imgBottom`) is handled directly by tpen-simple-transcription via `adjustImages()`, `highlightActiveLine()`, and `resetImagePositions()`.
+- tpen-workspace-tools handles tool launch and workspace actions.
+- These components should not own global routing.
+
+### Transcription Block (tpen-transcription-block)
+
+- Owns line input rendering and text editing.
+- Primary mutator of `TPEN.activeLineIndex` via `moveToLine()`.
+- Emits line navigation events (`tpen-transcription-previous-line`, `tpen-transcription-next-line`) via `TPEN.eventDispatcher`.
+- Does not manage image positioning or split-screen state.
+
+## Event Contracts (Core)
+
+Common orchestration events in the current implementation:
+
+- tpen-layer-changed
+- tpen-column-selected
+- tpen-transcription-previous-line
+- tpen-transcription-next-line
+- tpen-active-line-updated
+- tools-dismiss
+- splitscreen-toggle
+
+## Notes
+
+- Current header implementation includes layer and column selectors plus a canvas selector.
+- The standalone tpen-page-selector exists as a reusable component but is not the primary selector in this specific header implementation.

components/simple-transcription/DIAGRAMS.md

@@ -0,0 +1,71 @@
+# Transcription Interface Diagrams
+
+This file contains diagram-first references for external linking.
+
+## Composition Diagram
+
+```mermaid
+flowchart TD
+    A[interfaces/transcription/index.html] --> B[tpen-simple-transcription]
+
+    B --> C[tpen-project-header]
+    B --> D[Workspace Left Pane]
+    B --> E[Split-screen Right Pane]
+
+    C --> C1[tpen-layer-selector]
+    C --> C2[tpen-column-selector]
+    C --> C3[Canvas selector]
+    C --> C4[Line indicator]
+
+    D --> D1["#imgTop (focused line image)"]
+    D --> D2[tpen-transcription-block]
+    D --> D3[tpen-workspace-tools]
+    D --> D4["#imgBottom (remaining canvas)"]
+```
+
+## Data Ownership Diagram
+
+```mermaid
+flowchart LR
+    P[TPEN.activeProject] --> H[tpen-project-header]
+    P --> L[tpen-layer-selector]
+    P --> C[tpen-column-selector]
+    P --> S[tpen-simple-transcription]
+
+    U[URL pageID and TPEN.screen.pageInQuery] --> H
+    U --> S
+    U --> C
+
+    A[TPEN.activeLineIndex] --> H
+    A --> S
+
+    SSTATE[Interface local state: split-screen and active tool] --> S
+
+    V[vault annotation/page cache] --> C
+    V --> S
+```
+
+## Event Flow Diagram
+
+```mermaid
+flowchart TD
+    L[tpen-layer-selector] -- tpen-layer-changed --> S[tpen-simple-transcription]
+    C[tpen-column-selector] -- tpen-column-selected --> S
+    W[tpen-workspace-tools] -- splitscreen-toggle --> S
+    W -- tools-dismiss --> S
+
+    T[tpen-transcription-block] -- tpen-transcription-next-line / previous-line --> S
+    T -- tpen-transcription-next-line / previous-line --> H[tpen-project-header]
+
+    H -- URL pageID updates --> U[Browser URL]
+```
+
+## External Link Target
+
+Recommended issue link target:
+
+- components/simple-transcription/ARCHITECTURE.md
+
+Secondary diagram-only link:
+
+- components/simple-transcription/DIAGRAMS.md