diff --git a/components/workspace-tools/SPLITSCREEN_TOOLS_ARCHITECTURE.md b/components/workspace-tools/SPLITSCREEN_TOOLS_ARCHITECTURE.md new file mode 100644 index 00000000..fbd3e3c7 --- /dev/null +++ b/components/workspace-tools/SPLITSCREEN_TOOLS_ARCHITECTURE.md @@ -0,0 +1,250 @@ +# Splitscreen Tools Architecture + +Issue: #107 + +This document explains the splitscreen tools system in TPEN transcription interfaces: tool types, lifecycle, event communication, and integration patterns. + +## Purpose + +Provide a pluggable system for transcription-adjacent tools that appear alongside the main workspace without disrupting the core workflow. + +## Scope + +In scope: + +1. Tool types and their visual/behavioral characteristics +2. Tool activation and dismissal lifecycle +3. Event communication between tools and interface +4. Tool configuration via TPEN.activeProject.tools +5. Integration points with the transcription interface shell + +Out of scope: + +1. Individual tool implementation details (covered in component-specific docs) +2. Tool authentication/authorization beyond project-level permissions +3. Non-transcription interface tool usage patterns + +## Tool Types + +The system supports four distinct tool presentation modes: + +### 1. Split Pane Tools + +**Visual behavior**: Appear to the right of the main interface, creating a resizable horizontal division. + +**Use cases**: Full-featured tools that need substantial space (dictionaries, references, image viewers). + +**Current implementation**: +- Managed by tpen-simple-transcription interface state +- Activated via splitscreen-toggle event +- Location identifier: `"pane"` + +**References**: +- [components/simple-transcription/index.js](../simple-transcription/index.js) (interface orchestration) +- [components/splitscreen-tool/index.js](../splitscreen-tool/index.js) (tool selector dropdown) + +### 2. Sidebar Tools + +**Visual behavior**: Fixed-width panel that slides in from the right, non-resizable. + +**Use cases**: Compact tools, configuration panels, quick reference materials. + +**Current implementation**: +- Location identifier: `"sidebar"` +- Shares activation mechanism with pane tools + +### 3. Drawer Tools + +**Visual behavior**: Floating tray that slides over content, dismissible without losing context. + +**Use cases**: Magnifier, inspector, temporary overlays. + +**Current implementation**: +- [components/magnifier-tool/index.js](../magnifier-tool/index.js) +- Activated via specific tool buttons or shortcuts +- Does not use split-screen layout + +### 4. Dialog Tools + +**Visual behavior**: Modal overlay that interrupts workflow until dismissed. + +**Use cases**: Critical actions requiring full attention, configuration wizards. + +**Current implementation**: +- Uses GUI confirm/alert system +- Not directly tied to project.tools array + +## Tool Configuration + +Tools are defined in `TPEN.activeProject.tools` array with this structure: + +```javascript +{ + toolName: "dictionary", // Unique identifier + label: "Dictionary", // Display name + location: "pane", // Type: "pane" | "sidebar" | "drawer" | "dialog" + url: "https://example.com/tool.js", // Optional: URL for module script or iframe src + custom: { + enabled: true, // Optional: defaults to true if omitted + tagName: "tpen-dictionary", // Optional: custom element tag name (requires url) + // Tool-specific configuration + } +} +``` + +The rendering path is determined by these two properties: + +1. If `custom.tagName` AND `url` → load `url` as a module script, then render `` +2. If `url` AND no `tagName` AND `location === 'pane'` → render as `