Add workspace components architecture documentation for #108 by cubap · Pull Request #502 · CenterForDigitalHumanities/TPEN-interfaces

cubap · 2026-03-09T20:25:28Z

No description provided.

github-actions · 2026-03-09T20:26:12Z

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

cubap · 2026-03-09T20:26:18Z

closes #108

thehabes · 2026-03-10T16:37:04Z

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.

Copilot

Pull request overview

Adds a dedicated architecture document describing the “workspace region” components that power line-by-line transcription workflows in TPEN interfaces (tracked under #108).

Changes:

Introduces WORKSPACE_COMPONENTS_ARCHITECTURE.md documenting responsibilities, layout, data flow, and event contracts for workspace components.
Captures cross-component communication patterns (attributes, events, setters, postMessage) and operational considerations (performance, accessibility, error handling).

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

Copilot · 2026-03-12T20:51:05Z

+   - Placeholder or error message displayed
+   - Graceful degradation if canvas-panel unavailable
+   - Fallback to static image if region rendering fails


The "Image Loading Failures" section describes placeholder/error UI and fallback behavior if canvas-panel is unavailable, but tpen-line-image currently always injects the canvas-panel script from a CDN and doesn't implement a fallback/placeholder path. Please either adjust this section to match current behavior or add the described degradation handling in the component.

Suggested change

- Placeholder or error message displayed

- Graceful degradation if canvas-panel unavailable

- Fallback to static image if region rendering fails

- `tpen-line-image` injects `canvas-panel` from a CDN and currently treats it as a required dependency

- If `canvas-panel` or the line image fails to load, image functionality may be unavailable and the browser's default broken-image/script error behavior is shown

- No explicit placeholder UI or static-image fallback is implemented at this time (potential enhancement for future iterations)

Copilot · 2026-03-12T20:51:05Z

+- [Transcription Interface Architecture](../simple-transcription/ARCHITECTURE.md)
+- [Splitscreen Tools Architecture](../workspace-tools/SPLITSCREEN_TOOLS_ARCHITECTURE.md)
+- [Transcription Interface Diagrams](../simple-transcription/DIAGRAMS.md)


The "Related Documentation" section links to ../simple-transcription/ARCHITECTURE.md, ../simple-transcription/DIAGRAMS.md, and ../workspace-tools/SPLITSCREEN_TOOLS_ARCHITECTURE.md, but those files don't appear to exist in the repo (the referenced directories only contain index.js). Please update these links to the correct existing docs/paths or add the missing documents so the links aren't broken.

Suggested change

- [Transcription Interface Architecture](../simple-transcription/ARCHITECTURE.md)

- [Splitscreen Tools Architecture](../workspace-tools/SPLITSCREEN_TOOLS_ARCHITECTURE.md)

- [Transcription Interface Diagrams](../simple-transcription/DIAGRAMS.md)

- Transcription Interface Architecture (documentation path TBD)

- Splitscreen Tools Architecture (documentation path TBD)

- Transcription Interface Diagrams (documentation path TBD)

Copilot · 2026-03-12T20:51:05Z

+
+4. **Draft Storage**
+   - localStorage used for persistence
+   - Storage key format: `tpen-drafts:{projectID}:{pageID}:{userID}`


The documented localStorage key format includes a userID segment (tpen-drafts:{projectID}:{pageID}:{userID}), but the component currently builds the key as tpen-drafts:${projectID}:${pageID} (no user ID). Please correct the documented key format (or adjust the implementation if per-user separation is intended).

Suggested change

- Storage key format: `tpen-drafts:{projectID}:{pageID}:{userID}`

- Storage key format: `tpen-drafts:{projectID}:{pageID}`

…RE.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Add workspace components architecture documentation for #108

a8662fd

thehabes assigned cubap Mar 10, 2026

Update WORKSPACE_COMPONENTS_ARCHITECTURE.md

0862d2c

cubap requested a review from Copilot March 12, 2026 20:46

Copilot started reviewing on behalf of cubap March 12, 2026 20:47 View session

Copilot AI reviewed Mar 12, 2026

View reviewed changes

cubap and others added 2 commits March 12, 2026 15:58

Update components/transcription-block/WORKSPACE_COMPONENTS_ARCHITECTU…

4a445d8

…RE.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update components/transcription-block/WORKSPACE_COMPONENTS_ARCHITECTU…

fd89b44

…RE.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

cubap merged commit 2926be8 into main Mar 12, 2026
2 checks passed

cubap deleted the 108-transcription-workspace-components branch March 12, 2026 20:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add workspace components architecture documentation for #108#502

Add workspace components architecture documentation for #108#502
cubap merged 4 commits intomainfrom
108-transcription-workspace-components

cubap commented Mar 9, 2026

Uh oh!

github-actions bot commented Mar 9, 2026 •

edited

Loading

Uh oh!

cubap commented Mar 9, 2026

Uh oh!

thehabes commented Mar 10, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 12, 2026

Uh oh!

Copilot AI Mar 12, 2026

Uh oh!

Copilot AI Mar 12, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	- Storage key format: `tpen-drafts:{projectID}:{pageID}:{userID}`
	- Storage key format: `tpen-drafts:{projectID}:{pageID}`

Conversation

cubap commented Mar 9, 2026

Uh oh!

github-actions bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cubap commented Mar 9, 2026

Uh oh!

thehabes commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Static Review Comments

Major Issues 🟠

Issue 1: Incorrect permission check for transcription-block

Issue 2: splitscreen-toggle event source misattributed

Minor Issues 🟡

Issue 3: Keyboard navigation description is inaccurate

Issue 4: Draft storage key omits user component

Issue 5: Missing events from the Event Contracts table

Suggestions 🔵

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

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Mar 9, 2026 •

edited

Loading

thehabes commented Mar 10, 2026 •

edited

Loading

Issue 2: `splitscreen-toggle` event source misattributed

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