@pie-players/pie-tool-line-reader 0.3.63 → 0.3.64

package/README.md

@@ -19,7 +19,7 @@ Tag: `pie-tool-line-reader`
 
 ## Features
 
-- Clear window pane inside an obscuring frame; adjustable frame opacity
+- Clear window pane inside an obscuring frame, at a host-configured opacity
 - Drag anywhere on the frame to reposition
 - Three controls on the frame:
   - **Close** (top right) hides the tool through `ToolCoordinator.hideTool`, which also
@@ -27,8 +27,8 @@ Tag: `pie-tool-line-reader`
   - **Reading-window resize** (bottom centre) changes the pane height
   - **Frame resize** (bottom right) changes the frame band height and the overall width
 - Full keyboard support:
-  - On the tool: arrow keys to move, `+`/`-` to resize the reading window, `[`/`]` to
-    adjust frame opacity, `Escape` to close
+  - On the tool: arrow keys to move, `+`/`-` to resize the reading window, `Escape` to
+    close
   - On the reading-window handle: up/down arrows change the pane height
   - On the frame handle: up/down arrows change the frame band height, left/right arrows
     change the width
@@ -37,34 +37,52 @@ Tag: `pie-tool-line-reader`
 - Screen reader announcements for all state changes
 - Connects to `AssessmentToolkitRuntimeContext` for ToolCoordinator integration
 
-## Theming
+## Configuration
+
+How the frame masks the page — its fill and how strongly it obscures — is a host
+setting, not a student one. It trades reading focus against how much surrounding
+context a test taker can still see, which is a call a programme makes for its whole
+population, so it is configured once per deployment rather than adjusted mid-test.
 
-These are package-private custom properties, not part of the registered host
-token contract in `packages/theme/src/token-registry.json`: they are read as
-`var(--x, fallback)` (or set inline by the component, for the geometry ones), so
-a host can override them, but they carry no compatibility guarantee and may
-change with the tool's internals. Prefer the semantic tokens they derive from.
+```css
+:root {
+  /* Masking strength; the pane is always fully transparent. */
+  --pie-tool-line-reader-frame-opacity: 0.65;
+  /* Fill of the obscuring frame. */
+  --pie-tool-line-reader-frame-color: #10233b;
+}
+```
 
 | Custom property | Default | Description |
 |---|---|---|
+| `--pie-tool-line-reader-frame-opacity` | `0.8` | Masking strength of the frame |
 | `--pie-tool-line-reader-frame-color` | `#000` | Fill of the obscuring frame |
-| `--pie-tool-line-reader-frame-opacity` | `0.8` | Frame opacity; the pane is always fully transparent |
-| `--pie-tool-line-reader-outline-color` | `--pie-text` at 70% | Hairline marking the window boundary |
 | `--pie-tool-line-reader-control-color` | `#fff` | Glyph colour of the close and resize controls |
 
-The frame opacity custom property is set inline by the component from its current
-state, so host overrides need `!important` (or a higher-specificity rule) to win.
-The controls sit on top of the frame rather than inside it, so they stay fully
-opaque whatever the frame opacity is.
+All three are `component-public` entries in
+`packages/theme/src/token-registry.json` and are safe for a host to rely on. The
+component only reads them — it never writes them inline — so a plain host
+declaration wins without `!important`.
 
-### Colour schemes
+Two constraints come with overriding them. Lowering the opacity weakens the masking
+the tool exists to provide, and there is no in-session control for a student to
+recover from a value that masks too little, so check any override against the
+schemes you ship (see [Colour schemes](#colour-schemes) for the figures the
+defaults produce). And `--pie-tool-line-reader-control-color` is a companion to the
+fill rather than a hook worth setting alone: the control glyphs sit on the frame and
+default to white to pair with a dark scrim, so a light fill needs a new glyph colour
+with it, keeping 3:1 against the fill (WCAG 2.2 SC 1.4.11). The controls stay fully
+opaque whatever the frame opacity is, so the fill alone decides that ratio.
+
+## Colour schemes
 
 The frame stays a dark scrim in every PIE colour scheme instead of following
 `--pie-text`. Masking works by collapsing the contrast of whatever it covers, and
 an ink-coloured scrim defeats that on its own scheme — a yellow scrim over
 `yellow-on-blue` text hides nothing, and a white one glares in a dark scheme the
-reader chose to avoid glare. Dimming works in both directions: across all six
-built-in schemes the covered text drops from 10.9–19.3:1 down to 1.09–1.71:1.
+reader chose to avoid glare. Dimming works in both directions: at the default fill
+and opacity, across all six built-in schemes the covered text drops from
+10.9–19.3:1 down to 1.09–1.71:1.
 
 What does follow the scheme is the boundary. On a light page the dark scrim shows
 its own edge against the background (11.7–17.6:1), but on a dark page it blends in,
@@ -72,9 +90,20 @@ so `--pie-tool-line-reader-outline-color` draws an ink hairline that reads again
 the scrim (7.6–9.8:1 in the dark schemes). The drop shadow is ink-derived for the
 same reason, becoming a soft halo rather than disappearing.
 
-Overriding `--pie-tool-line-reader-frame-color` to a light fill means overriding
-`--pie-tool-line-reader-control-color` too — the glyphs are white to pair with the
-dark scrim, not with the page.
+Because the fill is a deployment setting rather than a scheme-derived one, a host
+that overrides it owns these numbers for the schemes it ships.
+
+## Theming
+
+The remaining custom properties are package-private, not part of the registered
+host token contract: they are read as `var(--x, fallback)` (or set inline by the
+component, for the geometry ones), so a host can override them, but they carry no
+compatibility guarantee and may change with the tool's internals. Prefer the
+semantic tokens they derive from.
+
+| Custom property | Default | Description |
+|---|---|---|
+| `--pie-tool-line-reader-outline-color` | `--pie-text` at 70% | Hairline marking the window boundary |
 
 ## Integration