Add transcription architecture and diagrams

[cubap]

closes #98

Add ARCHITECTURE.md and DIAGRAMS.md for the simple-transcription component. These docs describe component composition, visual regions, data ownership and truth locations, minimal knowledge boundaries, and core event contracts. DIAGRAMS.md provides mermaid diagrams for composition, data ownership, and event flow to aid integration with TPEN (interfaces/transcription/index.html, components/simple-transcription/index.js, components/projects/project-header.js).

[github-actions]

🚀 Deployed on https://69b328c11884b62237825aeb--tpen-interfaces-preview.netlify.app

[thehabes]

For this one confirm you mean tpen-simple-transcription. I think it might actually be tpen-transcription-interface which helps smooth out a few things at once.

Static Review Comments

Category	Issues Found
🔴 Critical	0
🟠 Major	2
🟡 Minor	2
🔵 Suggestions	1

Major Issues 🟠

Issue 1: tpen-line-image and tpen-image-fragment are not part of tpen-simple-transcription

File: components/simple-transcription/ARCHITECTURE.md:19-20
Category: Accuracy — incorrect component inventory

Problem:
The Component Inventory lists tpen-line-image and tpen-image-fragment as top-level composition elements of tpen-simple-transcription. The Composition Diagram in DIAGRAMS.md:21-22 also shows them as children of the Workspace Left Pane.

In reality, tpen-simple-transcription does not use these web components. Its render() method creates raw <img> elements inside #imgTop and #imgBottom divs, with a custom adjustImages() method handling all image positioning logic.

These two components (tpen-line-image / tpen-image-fragment) are used in the other transcription interface at interfaces/transcription/index.js (tpen-transcription-interface), but not in the simple one being documented here.

Current Code (ARCHITECTURE.md):

Top-level composition:

1. tpen-simple-transcription
2. tpen-project-header
3. tpen-line-image
4. tpen-transcription-block
5. tpen-workspace-tools
6. tpen-image-fragment

Suggested Fix:

Top-level composition:

1. tpen-simple-transcription
2. tpen-project-header
3. tpen-transcription-block
4. tpen-workspace-tools

The "Workspace composition" section should also be updated to reflect what actually exists:

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 rest of canvas)

And the Composition Diagram in DIAGRAMS.md should replace tpen-line-image and tpen-image-fragment with the actual DOM structure:

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)"]

Loading

How to Verify:
Read components/simple-transcription/index.js:158-364 (the render() method) and confirm no tpen-line-image or tpen-image-fragment elements exist. Then search for tpen-line-image usage in interfaces/transcription/index.js:213 to see where it's actually used.

---

Issue 2: Event Flow Diagram misattributes line navigation event origins

File: components/simple-transcription/DIAGRAMS.md:57-58
Category: Accuracy — incorrect event flow direction

Problem:
The Event Flow Diagram shows:

S -- tpen-transcription-next-line / previous-line --> H

This implies tpen-simple-transcription dispatches these events to tpen-project-header. In reality:

1. tpen-transcription-block dispatches tpen-transcription-previous-line and tpen-transcription-next-line via TPEN.eventDispatcher (see components/transcription-block/index.js:482-484)
2. Both tpen-simple-transcription and tpen-project-header independently listen for these events on eventDispatcher
3. tpen-simple-transcription dispatches tpen-active-line-updated (correctly shown), but NOT the next/previous-line events

The diagram is missing tpen-transcription-block as an event emitter entirely.

Current Code (DIAGRAMS.md):

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

    S -- tpen-active-line-updated --> H[tpen-project-header]
    S -- tpen-transcription-next-line / previous-line --> H
    H -- URL pageID updates --> U[Browser URL]

Loading

Suggested Fix:

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]

    S -- tpen-active-line-updated --> H
    H -- URL pageID updates --> U[Browser URL]

Loading

How to Verify:
Search for tpen-transcription-previous-line dispatches in components/transcription-block/index.js:482-484 (the emitter) and the listeners in components/simple-transcription/index.js:52-54 and components/projects/project-header.js:58-63.

---

Minor Issues 🟡

Issue 3: Data Truth Locations table omits tpen-transcription-block as a mutator of activeLineIndex

File: components/simple-transcription/ARCHITECTURE.md:58
Category: Completeness

Problem:
The "Active line index" row lists the "Mutated by" column as "line navigation events." While technically true at a high level, it obscures the fact that tpen-transcription-block is the primary mutator — its moveToLine() method directly sets TPEN.activeLineIndex and dispatches the navigation events. Understanding this is important for anyone working on the transcription interface.

Suggested Fix:
Update the "Mutated by" column for Active line index:

| Active line index | TPEN.activeLineIndex | header line indicator, interface, tools | tpen-transcription-block (moveToLine), column selector |

---

Issue 4: "Workspace Components" boundary section references tpen-line-image and tpen-image-fragment

File: components/simple-transcription/ARCHITECTURE.md:88-89
Category: Consistency with Issue 1

Problem:
The Minimal Knowledge Boundaries section describes responsibilities for tpen-line-image and tpen-image-fragment, which (per Issue 1) are not part of this component. These bullets should describe the actual image handling — which is inline within tpen-simple-transcription itself via adjustImages(), highlightActiveLine(), and resetImagePositions().

Suggested Fix:

### 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.

---

Suggestions 🔵

Suggestion 1: Add tpen-transcription-block to the Component Inventory

File: components/simple-transcription/ARCHITECTURE.md:15-21

tpen-transcription-block is already listed in the top-level composition (good), but it's absent from the Event Contracts discussion and the Minimal Knowledge Boundaries doesn't call out its critical role as the event emitter for line navigation. Consider adding a boundary entry:

### Transcription Block (tpen-transcription-block)

- Owns line input rendering and text editing.
- Emits line navigation events (tpen-transcription-previous-line, tpen-transcription-next-line).
- Mutates TPEN.activeLineIndex directly.
- Does not manage image positioning or split-screen state.

[Copilot]

Pull request overview

This PR adds two new documentation files (ARCHITECTURE.md and DIAGRAMS.md) for the simple-transcription component, addressing issue #98. The docs describe the transcription interface's component composition, data ownership, minimal knowledge boundaries, event contracts, and include Mermaid diagrams for visual reference.

Changes:

• Added ARCHITECTURE.md documenting component inventory, visual regions, data truth locations, minimal knowledge boundaries, and event contracts.
• Added DIAGRAMS.md with Mermaid flowcharts for composition, data ownership, and event flow.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
components/simple-transcription/ARCHITECTURE.md	New architecture doc describing component structure, data ownership, and event contracts
components/simple-transcription/DIAGRAMS.md	New diagrams doc with Mermaid flowcharts for composition, data ownership, and event flow

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.