Add workspace components architecture documentation for #108

[cubap]

No description provided.

[github-actions]

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

[cubap]

closes #108

[thehabes]

I'm not sure where you will draw the line, but just make sure things are accurate as you need them to be.

Static Review Comments

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

Major Issues 🟠

Issue 1: Incorrect permission check for transcription-block

File: components/transcription-block/WORKSPACE_COMPONENTS_ARCHITECTURE.md:50
Category: Accuracy

Problem:
The document states:

Permissions: Requires LINE TEXT or LINE CONTENT view access

The actual code at transcription-block/index.js:81 uses:

if (!CheckPermissions.checkViewAccess("ANY", "CONTENT")) {

This checks ANY entity with CONTENT scope — not LINE entity with TEXT or CONTENT scope. Developers relying on this doc to understand permission gates will get the wrong picture.

Suggested Fix:

**Permissions**: Requires ANY CONTENT view access

---

Issue 2: splitscreen-toggle event source misattributed

File: components/transcription-block/WORKSPACE_COMPONENTS_ARCHITECTURE.md:170
Category: Accuracy

Problem:
The Event Contracts table states:

Event	Source	...
splitscreen-toggle	workspace-tools	...

The event is actually dispatched by tpen-splitscreen-tool (components/splitscreen-tool/index.js:56), not by workspace-tools directly. While the event does bubble up through workspace-tools (via bubbles: true, composed: true), attributing the source to the parent is misleading — the workspace-tools component never dispatches this event itself.

Suggested Fix:

| `splitscreen-toggle` | splitscreen-tool (child of workspace-tools) | Interface | `{ selectedTool }` | Activate split-screen tool |

---

Minor Issues 🟡

Issue 3: Keyboard navigation description is inaccurate

File: components/transcription-block/WORKSPACE_COMPONENTS_ARCHITECTURE.md:281
Category: Accuracy

Problem:
The Accessibility section states:

Arrow keys or Tab for previous/next line

The actual keyboard shortcuts in transcription-block/index.js:386-426 are:

• Tab → next line
• Shift+Tab → previous line
• Enter → move remaining text to next line, advance
• Shift+Enter → previous line
• Ctrl+Home → first line
• Ctrl+End → last line

Arrow keys are not used for line navigation. Additionally, Enter and Shift+Enter are missing from the doc entirely, as are the Ctrl+Home/End shortcuts.

Suggested Fix:

1. **Keyboard Navigation**
   - Tab / Enter for next line, Shift+Tab / Shift+Enter for previous line
   - Ctrl+Home to jump to first line, Ctrl+End to jump to last line
   - Enter splits text at cursor position and moves remainder to next line
   - Ctrl+0-9 / Ctrl+Shift+0-9 for QuickType character insertion
   - Focus management between input and buttons
   - Escape key to dismiss tools/overlays

---

Issue 4: Draft storage key omits user component

File: components/transcription-block/WORKSPACE_COMPONENTS_ARCHITECTURE.md:276
Category: Accuracy

Problem:

Storage key based on project + page + user

The actual buildStorageKey() method at transcription-block/index.js:307-311 constructs:

return `tpen-drafts:${projectID}:${pageID}`

There is no user component in the key. This means if two users share a browser, their drafts could collide.

Suggested Fix:

- Storage key based on project + page (format: `tpen-drafts:{projectID}:{pageID}`)

Whether the missing user component is a bug in the code or just a doc inaccuracy — that's worth discussing separately.

---

Issue 5: Missing events from the Event Contracts table

File: components/transcription-block/WORKSPACE_COMPONENTS_ARCHITECTURE.md:163-172
Category: Completeness

Problem:
The "Event Contracts" table lists 5 events as "Primary workspace events" but omits several events that the workspace components dispatch and consume. The following are active in the codebase and relevant to workspace operation:

Event	Source	Purpose
tpen-transcription-line-dirty	transcription-block	Line has unsaved changes
tpen-transcription-line-clean	transcription-block	Line changes saved/reverted
tpen-transcription-line-save-scheduled	transcription-block	Save queued for line
tpen-transcription-line-save-start	transcription-block	API save in progress
tpen-transcription-line-save-success	transcription-block	Line saved successfully
tpen-transcription-line-save-fail	transcription-block	Line save failed
tpen-transcription-flush-all	external → transcription-block	Request to save all dirty lines
tpen-transcription-drafts-recovered	transcription-block	Drafts loaded from localStorage

These are important for understanding how other components (e.g., header indicators, interface shell) can observe save state.

Suggested Fix:
Add a secondary table or subsection for "Save Lifecycle Events" documenting these.

---

Suggestions 🔵

Suggestion 1: Document the window.message external tool communication channel

File: components/transcription-block/WORKSPACE_COMPONENTS_ARCHITECTURE.md
Category: Completeness

The transcription-block listens for window.postMessage events with types RETURN_LINE_ID and UPDATE_LINE_TEXT (lines 159-177). This is a significant communication channel for external tools (e.g., iframes) that is not documented in the "Component Communication Patterns" section. It represents a fourth pattern beyond Attribute-Based, Event-Based, and Setter-Based.