@pie-players/pie-tool-tts-inline 0.3.73 → 0.3.75

package/README.md

@@ -8,20 +8,20 @@ focuses on the inline custom element API.
 
 ## Overview
 
-`pie-tool-tts-inline` is a web component that renders an inline speaker trigger with an expanded floating control panel for reading controls. Unlike floating modal tools, this component renders at its natural position in the DOM (typically in passage/item headers).
+`pie-tool-tts-inline` is a web component that renders an inline play/pause trigger with an expanded floating control panel for reading controls. Unlike floating modal tools, this component renders at its natural position in the DOM (typically in passage/item headers).
 
 ## Features
 
-- Speaker trigger that toggles an expanded panel
-- Expanded controls: Play/Pause, Stop, Fast-forward, Rewind, configurable Speed options
+- Play/pause trigger that opens the expanded panel when reading starts
+- Expanded controls: configurable Speed options, Rewind, Fast-forward, Stop
 - Play button switches to Pause while reading
 - Panel remains open while reading and closes on Stop
 - Arrow-key navigation within the controls toolbar
-- Registers with `ToolCoordinator` for lifecycle management
+- Takes its services from the toolkit runtime context and its reading scope from the enclosing item or passage shell
 - Integrates with `TTSService` for QTI 3.0 catalog-based TTS
 - Size variants: `sm`, `md`, `lg`
 - Full accessibility support (ARIA labels, `role="toolbar"`, live status updates)
-- Coordinator-controlled visibility via CSS `display` property
+- Four panel layouts through `layout-mode`
 
 ## Installation
 
@@ -31,27 +31,25 @@ bun add @pie-players/pie-tool-tts-inline
 
 ## Usage
 
+The element renders inside `<pie-item-scope>` or `<pie-passage-shell>` under
+`<pie-assessment-toolkit>`. The toolkit runtime context supplies the TTS service,
+the highlight coordinator and the toolkit coordinator, and the shell supplies the
+content to read. Section players provide both; around a plain item player, the
+host writes the toolkit and the scope. The packaged
+`textToSpeech` capability in `@pie-players/pie-default-tool-loaders` creates
+this element in item and passage toolbars, takes `catalog-id`, `language` and
+`size` from the toolbar, and takes `layout-mode`, `speedOptions` and
+`showSingleSpeedOption` from the toolkit's `textToSpeech` tool configuration.
+
 ```javascript
 import '@pie-players/pie-tool-tts-inline';
-import { TTSService, BrowserTTSProvider, ToolCoordinator } from '@pie-players/pie-assessment-toolkit';
-
-// Initialize services
-const ttsService = new TTSService();
-await ttsService.initialize(new BrowserTTSProvider());
-const toolCoordinator = new ToolCoordinator();
 
-// Create element
+// passageHeader: an element inside <pie-passage-shell>
 const ttsButton = document.createElement('pie-tool-tts-inline');
-ttsButton.setAttribute('tool-id', 'tts-passage-1');
 ttsButton.setAttribute('catalog-id', 'passage-1');
 ttsButton.setAttribute('size', 'md');
-
-// Bind services as JavaScript properties (not HTML attributes)
-ttsButton.ttsService = ttsService;
-ttsButton.coordinator = toolCoordinator;
-
-// Coordinator controls visibility
-toolCoordinator.showTool('tts-passage-1');
+ttsButton.setAttribute('layout-mode', 'expanding-row');
+passageHeader.append(ttsButton);
 ```
 
 ### With Svelte
@@ -59,29 +57,14 @@ toolCoordinator.showTool('tts-passage-1');
 ```svelte
 <script>
   import '@pie-players/pie-tool-tts-inline';
-  import { ZIndexLayer } from '@pie-players/pie-assessment-toolkit';
-
-  let ttsToolElement;
-
-  $effect(() => {
-    if (ttsToolElement && toolCoordinator) {
-      ttsToolElement.ttsService = ttsService;
-      ttsToolElement.coordinator = toolCoordinator;
-
-      if (ttsService) {
-        toolCoordinator.showTool('tts-passage-1');
-      }
-    }
-  });
 </script>
 
 <div class="header">
   <h3>Passage Title</h3>
   <pie-tool-tts-inline
-    bind:this={ttsToolElement}
-    tool-id="tts-passage-1"
     catalog-id="passage-1"
     size="md"
+    layout-mode="expanding-row"
   ></pie-tool-tts-inline>
 </div>
 ```
@@ -90,18 +73,25 @@ toolCoordinator.showTool('tts-passage-1');
 
 ### HTML Attributes
 
-- `tool-id` - Unique identifier for tool registration (default: `'tts-inline'`)
 - `catalog-id` - QTI 3.0 accessibility catalog ID for SSML lookup (default: `''`)
-- `language` - Language code for TTS (default: `'en-US'`)
+- `language` - The content language when the markup names none (default: `''`,
+  which falls back to the toolkit's `content-language`). A `lang` attribute
+  between the reading target and its shell wins over it.
 - `size` - Icon size: `'sm'` (1.5rem), `'md'` (2rem), or `'lg'` (2.5rem) (default: `'md'`)
+- `layout-mode` - Panel placement (default: `'left-aligned'`). `'reserved-row'`
+  and `'expanding-row'` drop the panel below the trigger; in the packaged toolbar
+  the first keeps the controls row reserved and the second expands it while the
+  panel is open. `'floating-overlay'` and `'left-aligned'` open the panel as an
+  overlay to the left of the trigger.
 
 ### JavaScript Properties
 
-- `ttsService` - ITTSService instance (required)
-- `coordinator` - IToolCoordinator instance (optional, for visibility management)
 - `speedOptions` - Optional speed options controlling inline speed button rendering
 - `showSingleSpeedOption` - Optional boolean to show a one-option speed group (hidden by default)
 
+Both also read attributes: `speed-options` takes a JSON array, and
+`show-single-speed-option` is true when present.
+
 ### `speedOptions` Configuration
 
 `speedOptions` is intended to be set as a JavaScript property (not as a
@@ -145,19 +135,19 @@ Semantics:
 
 ## Behavior
 
-1. **Tool Registration**: Registers with ToolCoordinator on mount using the provided `tool-id`
-2. **Text Extraction**: Finds nearest `.pie-section-player__passage-content` or `.pie-section-player__item-content` container
-3. **TTS Trigger**: Calls `ttsService.speak(text, { catalogId, language })`
+1. **Services**: Reads `ttsService`, `highlightCoordinator` and `toolkitCoordinator` from the toolkit runtime context; the controls stay disabled until a `ttsService` arrives, and starting playback awaits `toolkitCoordinator.ensureTTSReady()`
+2. **Text Extraction**: Reads the text of the scope element's content region (the region scope, else the shell scope, when it is `[data-region='content']`, else its first `[data-region='content']` descendant, else the scope element itself), including text rendered into open shadow roots
+3. **TTS Trigger**: Calls `ttsService.speak(readingTarget, { catalogId, catalogContext, language })`, where `catalogContext` names the owning item or passage and `language` is the `language` attribute, else the toolkit's `content-language`. `speak` resolves the read's language from it as [TTS language](../../docs/architecture/internationalization.md#tts-language) sets out
 4. **Catalog Resolution**: TTSService checks for SSML in accessibility catalogs (priority order):
    - **Extracted catalogs** (from embedded SSML) - generated before render by hosts that run `SSMLExtractor`
    - **Item-level catalogs** (manually authored)
    - **Assessment-level catalogs** (manually authored)
    - **Plain text fallback** (browser TTS)
 5. **Expanded Controls**:
-   - Trigger button opens/closes the panel
-   - Play/Pause toggles based on playback state
+   - The trigger starts, pauses and resumes reading; starting opens the panel
+   - Starting one instance stops playback another instance owns and closes that instance's panel
    - Stop halts playback and closes the panel
-   - Fast-forward/Rewind invoke sentence-jump seek on `ITTSService`
+   - Fast-forward/Rewind call `seekForward(1)` / `seekBackward(1)` on the TTS service, one sentence per press, and are enabled only while reading
    - Speed buttons call `ttsService.setPlaybackRate(rate)` when available,
      otherwise `ttsService.updateSettings({ rate })`
    - Speed choices render as a named `Playback speed` radio group with
@@ -166,8 +156,9 @@ Semantics:
    - Clicking the currently active speed leaves the selection unchanged
    - If `speedOptions` is `[]`, speed controls are omitted and playback rate is
      reset to `1x` while rewind/forward/stop still render
-6. **Keyboard Interaction**: Arrow keys move between controls; Tab enters/leaves the toolbar
-7. **Cleanup**: Unregisters from coordinator on unmount
+6. **Keyboard Interaction**: Arrow keys, Home and End move focus within one cluster, either the speed radio group or the Rewind/Fast-forward/Stop buttons, and skip disabled controls; arrowing onto a speed also selects it. Every control is a Tab stop except the speed radios, which share one Tab stop on the checked option
+7. **Active State**: Opening or closing the panel dispatches a bubbling, composed `pie-tool-active-change` event with `{ active }` and mirrors the state in the host's `data-active` attribute
+8. **Cleanup**: Releases playback ownership and clears its highlight target resolver provider on unmount
 
 ## SSML Extraction Integration
 
@@ -192,7 +183,7 @@ when a host/import pipeline runs `SSMLExtractor` before render:
 **Tool uses extracted catalog:**
 
 - User clicks TTS button in header
-- Tool calls `ttsService.speak(text, { catalogId: 'auto-prompt-q1-0' })`
+- Tool calls `ttsService.speak(readingTarget, { catalogId: 'auto-prompt-q1-0' })`
 - TTSService finds SSML in extracted catalogs
 - Speaks with proper math pronunciation and pacing
 
@@ -202,8 +193,8 @@ when a host/import pipeline runs `SSMLExtractor` before render:
 
 The component uses scoped styles and doesn't require external CSS. Styling uses `--pie-*` token variables:
 
-- **Trigger**: Circular speaker button that indicates panel open state
-- **Panel**: Floating card with vertically stacked controls
+- **Trigger**: Circular play/pause button that indicates panel open state
+- **Panel**: Floating card with the controls in a row; in the compact `left-aligned` overlay the speed options stack below them
 - **Speed state**: Active speed button receives distinct token-driven styling
 - **Disabled**: Reduced opacity, no pointer
 
@@ -220,7 +211,7 @@ component-scoped variables instead of overriding broad semantic tokens such as
 If unset, the trigger looks the same open as closed: each hook falls back to the
 value the control already resolves to — background through
 `--pie-button-background-color` / `--pie-button-bg` / `--pie-background`, border
-through `--pie-button-border-color` / `--pie-button-border` / `--pie-border`, and
+through `--pie-button-border` / `--pie-border`, and
 foreground through `--pie-button-color` / `--pie-text`. Setting a hook is how a
 host opts into a distinct active/open appearance.
 
@@ -233,10 +224,9 @@ colors.
 
 ### Overlay panel colours
 
-The floating and left-aligned panels take their shape from the Knowledge-Check
-design and their colour from the active theme. Each surface resolves a
-component-scoped hook first, then a canonical token, then a literal that only
-applies when no theme is loaded:
+The floating and left-aligned panels take their colour from the active theme.
+Each surface resolves a component-scoped hook first, then a canonical token,
+then a literal that only applies when no theme is loaded:
 
 ```css
 --pie-tts-button-color        /* media glyphs, selected speed → --pie-button-color */
@@ -270,21 +260,21 @@ Selection reads from the chip fill and the bolder weight instead of from hue. A
 host that wants a branded accent sets `--pie-tts-button-color` and owns the
 contrast, as with the active-trigger hooks above.
 
-Ordinary trigger and control button styling also preserves these legacy aliases:
-`--pie-button-background-color`, `--pie-button-border-color`, and
-`--pie-button-hover-background-color`. They remain supported for host
-compatibility, but fall back through the canonical `--pie-button-bg`,
-`--pie-button-border`, and `--pie-button-hover-bg` tokens before broad surface
-tokens.
+Trigger and control backgrounds read `--pie-button-background-color` ahead of
+the canonical `--pie-button-bg`; borders and hover backgrounds read
+`--pie-button-border` and `--pie-button-hover-bg`. Each falls back to the broad
+surface tokens.
 
 ## Architecture
 
 This tool follows the PIE Assessment Toolkit tool pattern:
 
 - Always rendered in DOM at natural position
-- ToolCoordinator controls visibility via `showTool()`/`hideTool()` (CSS `display` property)
-- Registers with `ZIndexLayer.TOOL` for proper layering
-- Services passed as JavaScript properties (objects can't be HTML attributes)
+- Services arrive through `connectToolRuntimeContext`, and the reading scope
+  through `connectToolShellContext` and `connectToolRegionScopeContext`
+- One instance owns playback at a time across the page
+- Panel state is announced with `pie-tool-active-change`, which the packaged
+  toolbar registration subscribes to
 
 ## Example
 

package/dist/index.d.ts

@@ -1 +1,8 @@
-export { default } from './tool-tts-inline.svelte';
+/**
+ * pie-tool-tts-inline
+ *
+ * Importing this package registers `<pie-tool-tts-inline>`. The build entry is
+ * the component, so this file is the type entry alone and declares nothing: a
+ * runtime export here would not exist in the built bundle.
+ */
+export type {};