@pie-players/pie-section-player 0.3.29 → 0.3.31

package/README.md

@@ -4,6 +4,7 @@ Section rendering package with layout custom elements:
 
 - `pie-section-player-splitpane`
 - `pie-section-player-vertical`
+- `pie-section-player-tabbed`
 
 The package no longer exposes the legacy `pie-section-player` layout orchestration API.
 
@@ -38,6 +39,7 @@ Import the custom-element registration entrypoint in consumers:
 ```ts
 import '@pie-players/pie-section-player/components/section-player-splitpane-element';
 import '@pie-players/pie-section-player/components/section-player-vertical-element';
+import '@pie-players/pie-section-player/components/section-player-tabbed-element';
 import '@pie-players/pie-section-player/components/section-player-item-card-element';
 import '@pie-players/pie-section-player/components/section-player-passage-card-element';
 ```
@@ -60,25 +62,99 @@ Both layout elements support:
 - `debug` (boolean-like): verbose debug logging control (`"true"` enables, `"false"`/`"0"` disables)
 - `toolbar-position` (string): `top|right|bottom|left|none`
 - `narrow-layout-breakpoint` (number, optional): viewport width in px below which the layout collapses (split pane: single column; vertical: toolbar moves to top). Clamped to 400–2000; default 1100.
+- `content-max-width-no-passage` (number, optional): max width in px when no passages exist. Clamped to 320–2200. Unset by default (layout uses available width).
+- `content-max-width-with-passage` (number, optional): max width in px when passages are present. Clamped to 320–2200. Unset by default (layout uses available width).
+- `split-pane-min-region-width` (number, optional): splitpane minimum pane width in px. Clamped to 160–1200. Unset by default (legacy split bounds stay at 20–80). (Ignored by vertical layout; supported for API parity.)
+- `split-pane-collapse-strategy` (string, optional): splitpane stacked-mode strategy. Supported values: `tabbed` (default) and `vertical`. (Ignored by vertical/tabbed layouts; supported for API parity.)
 - `show-toolbar` (boolean-like): accepts `true/false` and common string forms (`"true"`, `"false"`, `"1"`, `"0"`, `"yes"`, `"no"`)
 - Host extension props (JS properties only): `toolRegistry`, `sectionHostButtons`, `itemHostButtons`, `passageHostButtons`, `hooks`
 
-When viewport width is within the collapsed range (~1100px and below), inline section
-toolbar positions (`left`/`right`) normalize to `top` so controls remain horizontally
-laid out and easier to access.
+When viewport width is within the collapsed range (~1100px and below), splitpane and
+vertical layout hosts normalize section toolbar placement to `top`. This includes
+`left`, `right`, `bottom`, and `none` values.
 
 `hooks.cardTitleFormatter` remains active across responsive splitpane transitions (split -> stacked and stacked -> split), because title rendering is provided through shared card context rather than layout-specific state.
 
+To opt into PIE-117 dimensions from a host, configure:
+
+```html
+<pie-section-player-splitpane
+  content-max-width-no-passage="800"
+  content-max-width-with-passage="1200"
+  split-pane-min-region-width="280"
+></pie-section-player-splitpane>
+```
+
+Use the same max-width attributes on `pie-section-player-vertical` when you want the same no-passage/with-passage width behavior in vertical mode.
+
+To force splitpane stacked mode to use vertical rendering:
+
+```html
+<pie-section-player-splitpane
+  narrow-layout-breakpoint="1100"
+  split-pane-collapse-strategy="vertical"
+></pie-section-player-splitpane>
+```
+
+By default, splitpane stacked mode uses tabs. The dedicated `pie-section-player-tabbed` layout also always renders passage/items tabs when passages are present.
+
+### Tab styling hooks
+
+`pie-section-player-tabbed` and splitpane `tabbed` collapse mode expose canonical `pie-*`
+hooks for theming:
+
+- `pie-section-player-tabs`
+- `pie-section-player-tab`
+- `pie-section-player-tab--active`
+- `pie-section-player-tab-panel`
+
+For theme compatibility with existing passage-label patterns, tabs also expose:
+
+- `data-pie-purpose="passage-label"` and alias class `passage-label`
+- `data-pie-purpose="item-label"` and alias class `item-label`
+
+Tab colors/spacing can be themed via CSS variables such as:
+`--pie-section-player-tab-color`, `--pie-section-player-tab-active-color`,
+`--pie-section-player-tab-indicator-color`, and `--pie-section-player-tab-spacing`.
+
+### Card header styling hooks
+
+Passage and item cards share a common header row
+(`.pie-section-player-content-card-header`, with the card-specific aliases
+`.pie-section-player-passage-header` / `.pie-section-player-item-header`).
+
+- Title and toolbar are centered vertically by default. There is no prop or
+  attribute for this — hosts needing a non-standard alignment should override
+  the selector in their own stylesheet.
+- The header fill is transparent by default. Hosts/themes opt into a color
+  via the `--pie-section-player-card-header-background` CSS variable; the
+  framework does not ship a brand palette.
+
+Example (host CSS):
+
+```css
+pie-section-player-passage-card,
+pie-section-player-item-card {
+  --pie-section-player-card-header-background: #c9e5e6;
+}
+```
+
+When both max-width attributes are set, the with-passage cap resolves to the greater
+of the two configured values (after clamp), so with-passage mode never ends up narrower
+than no-passage mode.
+
 ### API direction: CE defaults first, JS customization for advanced cases
 
 The intended usage model is:
 
 - **CE props for default/standard flows (roughly 90% use cases)**:
   - `assessment-id`, `section`, `section-id`, `attempt-id`, `debug`
-  - `show-toolbar`, `toolbar-position`, `narrow-layout-breakpoint`, `enabled-tools`, `item-toolbar-tools`, `passage-toolbar-tools`
+  - `show-toolbar`, `toolbar-position`, `narrow-layout-breakpoint`
+  - `content-max-width-no-passage`, `content-max-width-with-passage`, `split-pane-min-region-width`, `split-pane-collapse-strategy`
+  - `enabled-tools` (per-region tool placement is configured via `tools.placement.{item,passage}`; the `item-toolbar-tools` / `passage-toolbar-tools` aliases were removed in the broad architecture review compat sweep)
 - **JS API for advanced customization**:
-  - Get the controller handle via `getSectionController()` or `waitForSectionController()`
-  - Listen to `section-controller-ready`
+  - Get the controller handle via `getSectionController()` or `waitForSectionController()` (preferred)
+  - Listen for `pie-stage-change` and filter on `detail.stage === "engine-ready"` for an event-driven entry point
   - Apply custom policy/gating in host code (for example, domain-specific `canNext` based on controller events like `section-items-complete-changed`)
   - Compose forward/backward eligibility in host code using `selectNavigation()` + host state; there is intentionally no separate parallel CE gating API for this
   - Inject custom toolbar tooling with `toolRegistry` and optional host button arrays (`sectionHostButtons`, `itemHostButtons`, `passageHostButtons`)
@@ -98,7 +174,99 @@ host.hooks = {
 };
 ```
 
-Advanced CE props are still supported as escape hatches (`runtime`, `coordinator`, `createSectionController`, etc.), but hosts should prefer JS/controller composition for non-standard behavior.
+Advanced CE props are still supported as escape hatches (`runtime`, `coordinator`, etc.), but hosts should prefer JS/controller composition for non-standard behavior. Note: `createSectionController` is **runtime-only** — set it on `runtime.createSectionController` rather than as a top-level CE prop (the prop alias was removed in the broad architecture review compat sweep).
+
+### Focus management
+
+Section-player owns its own focus contract so hosts can integrate a
+"Skip to Main" affordance and keyboard navigation without re-encoding
+the passage-first rule.
+
+**Public focus targets.** Both card custom elements are `tabindex="-1"`
+(programmatically focusable, never in sequential tab order) and expose a
+`:focus-visible` outline:
+
+- `<pie-section-player-passage-card>` (when the section has a passage)
+- `<pie-section-player-item-card>`
+
+The inner `.pie-section-player-content-card[data-section-item-card]`
+selector is an internal back-compat hook and is not part of the public
+contract — prefer querying the custom element tags.
+
+**Declarative control.** The `SectionPlayerFocusPolicy.autoFocus` strategy
+governs focus on every navigation event (Next / Back / `navigateTo`) and is
+also honored by the imperative `focusStart()`:
+
+- `"start-of-content"` *(default)* — focus the passage card when present,
+  otherwise the first item card. Matches the canonical assessment UX where
+  Skip-to-Main and navigation land in the same place. Best for
+  one-item-per-page layouts (splitpane, tabbed).
+- `"current-item"` — focus the newly-active item card (queried as
+  `pie-section-player-item-card[is-current]`). Best for stacked/list
+  layouts where multiple items are visible at once (vertical, custom
+  kernel-host variants). Works in both paginated and keep-together
+  sections — QTI 3 `keep-together` is a pagination hint only and does
+  not disable item-level navigation or current-item tracking.
+- `"none"` — framework never moves focus on navigation; the host owns it
+  entirely. `focusStart()` still moves focus (defaults to
+  start-of-content) because hosts only call it when they *want* focus to
+  move.
+
+```ts
+const host = document.querySelector("pie-section-player-splitpane") as any;
+host.policies = {
+  readiness: { mode: "progressive" },
+  preload: { enabled: true },
+  focus: { autoFocus: "start-of-content" },
+  telemetry: { enabled: true },
+};
+```
+
+**Wired policy toggles.** Each `SectionPlayerPolicies` field has a real
+runtime effect; nothing in this surface is decorative.
+
+- `readiness.mode` (`"progressive"` | `"strict"`) — drives readiness-event
+  emission via `createReadinessDetail` in `SectionPlayerLayoutKernel`.
+- `preload.enabled` — when `false`, `SectionItemsPane` short-circuits the
+  section-level element warmup pipeline (`warmupSectionElements`). Items
+  still mount and item-players register their own elements on demand. Use
+  this to disable section pre-warm when the host already owns element
+  registration end-to-end. Default: `true`.
+- `focus.autoFocus` — focus strategy on navigation; see "Focus management"
+  above.
+- `telemetry.enabled` — when `false`, the layout custom elements skip
+  `attachInstrumentationEventBridge` setup, so no `pie-section-*`
+  telemetry events flow through the bridge. Hosts that want a different
+  shape of opt-out can still override `runtime.player.loaderConfig.instrumentationProvider`.
+  Default: `true`.
+
+The exported `isPreloadEnabled(policies)` and `isTelemetryEnabled(policies)`
+helpers read these toggles with the documented default-true semantics, so
+host code that needs to mirror the same gate (e.g. when composing a custom
+layout host) can call them directly.
+
+**Imperative escape hatch (host-owned focus moments).** Every layout
+element (`pie-section-player-splitpane`, `-vertical`, `-tabbed`,
+`-kernel-host`, and `-base`) exposes a `focusStart(): boolean` method.
+Call it from host-owned affordances the framework cannot observe — most
+commonly a "Skip to Main" button in the host's ribbon:
+
+```ts
+document.querySelector("pie-section-player-splitpane")?.focusStart();
+```
+
+`focusStart()` honors the `autoFocus` strategy so Skip-to-Main lands
+wherever the host has opted in for navigation focus:
+
+- `"start-of-content"` *(default)* → passage card when present, else first
+  item card.
+- `"current-item"` → the item card currently marked `is-current`, falling
+  back to start-of-content if no current item is resolvable.
+- `"none"` → start-of-content (hosts call `focusStart()` precisely
+  because they want focus to move).
+
+For Next / Back / question-number navigation the host does **not** call
+`focusStart()` — the `autoFocus` policy fires automatically.
 
 ### Navigation signals
 
@@ -107,9 +275,9 @@ Advanced CE props are still supported as escape hatches (`runtime`, `coordinator
 
 Runtime precedence is explicit:
 
-- `runtime` values are primary for runtime fields (`assessmentId`, `playerType`, `player`, `lazyInit`, `tools`, `accessibility`, `coordinator`, `createSectionController`, `isolation`, `env`).
+- `runtime` values are primary for runtime fields (`assessmentId`, `playerType`, `player`, `lazyInit`, `tools`, `accessibility`, `coordinator`, `isolation`, `env`). `createSectionController` is exposed only via `runtime.createSectionController`.
 - Top-level runtime-like props remain compatibility inputs and are merged with `runtime` values. For `player`, top-level values are merged first, then `runtime.player` overrides. Nested `loaderOptions` and `loaderConfig` are also merged with the same precedence.
-- Toolbar placement overrides (`enabled-tools`, `item-toolbar-tools`, `passage-toolbar-tools`) are normalized on top of the runtime tools config.
+- The section-level toolbar placement override (`enabled-tools`) is normalized on top of the runtime tools config and merges into `tools.placement.section`. Per-region placement (`tools.placement.item` / `tools.placement.passage`) is configured directly on the canonical `tools` / `runtime.tools` object — the deprecated `item-toolbar-tools` / `passage-toolbar-tools` aliases were removed in the broad architecture review compat sweep.
 - Tool configuration validation is canonical in toolkit initialization (`pie-assessment-toolkit`), including toolbar overlays. Use `runtime.toolConfigStrictness` (`off` | `warn` | `error`) to control warning-only vs fail-fast behavior.
 - TTS provider config must use `tools.providers.textToSpeech` (canonical). `tools.providers.tts` is rejected by validation.
 - Host tool overrides are additive:
@@ -276,20 +444,66 @@ Section-player instrumentation is provider-agnostic and uses the shared
 - Toolkit telemetry forwarding uses the same provider path, so tool/backend
   operational events are visible alongside section events when toolkit is mounted.
 
-Section-player owned canonical stream:
-
-- `pie-section-readiness-change`
-- `pie-section-interaction-ready`
-- `pie-section-ready`
-- `pie-section-controller-ready`
+Canonical lifecycle stream (engine-routed, dispatched on the outer layout CE):
+
+- `pie-stage-change` — single typed transition stream covering
+  `composed` → `engine-ready` → `interactive` → `disposed`. Payload is a
+  `StageChangeDetail`. Replaces the legacy readiness vocabulary.
+- `pie-loading-complete` — fires once per cohort when every item has
+  loaded (kernel-routed; gated on `interactive`).
+- `framework-error` — canonical error event for any failure crossing the
+  framework boundary. Payload is a `FrameworkErrorModel`. The toolkit's
+  package-internal `FrameworkErrorBus` and the `onFrameworkError`
+  callback prop deliver each error exactly once regardless of wrapper
+  depth. The `framework-error` *DOM event* on the outer layout CE
+  also delivers each error exactly once: the kernel listener at
+  `<pie-section-player-base>` intercepts the toolkit's bubbled emit
+  and calls `event.stopPropagation()`, leaving only the canonical
+  engine-bridge emit on the layout host. The single-emit contract is
+  pinned by `tests/section-player-framework-error-dual-emit.test.ts`.
+  Direct listeners attached to `<pie-assessment-toolkit>` itself
+  still see the toolkit's own emit. The previous dual-emit on the
+  layout host was removed in the broad architecture review compat
+  sweep.
+
+Callback-prop mirrors with two-tier precedence (`runtime.<key>` wins over
+the top-level prop):
+
+- `onStageChange(detail)` — on every layout CE, `pie-section-player-base`,
+  and `pie-assessment-toolkit`.
+- `onLoadingComplete(detail)` — on the kernel-backed layout CEs only
+  (split-pane / vertical / tabbed / kernel-host).
+- `onFrameworkError(model)` — on every layout CE and
+  `pie-section-player-base`. Fires exactly once per error regardless of
+  wrapper depth (delivered through the package-internal
+  `FrameworkErrorBus`). The `framework-error` DOM event on the layout
+  CE host is also single-fire post-compat-sweep; consume either.
+
+Section-player owned instrumentation stream:
+
+- `pie-section-stage-change`
+- `pie-section-loading-complete`
 - `pie-section-session-changed`
 - `pie-section-composition-changed`
-- `pie-section-runtime-error`
-
-Framework boundary stream (from toolkit, re-emitted through section-player wrappers):
-
-- `framework-error` (canonical)
-- `runtime-error` (compatibility signal)
+- `pie-section-framework-error`
+
+The deprecated readiness aliases (`readiness-change`,
+`interaction-ready`, `ready`) and their `legacy-event-bridge`, along
+with the deprecated `section-controller-ready` Svelte/DOM event and
+its `pie-section-controller-ready` instrumentation mapping, were
+removed in the broad architecture review compat sweep. Migrate
+consumers as follows:
+
+- `readiness-change` → listen for `pie-stage-change`. The readiness
+  payload is also available via `selectReadiness()` /
+  `getSnapshot().readiness` on the layout CE.
+- `interaction-ready` → `pie-stage-change` filtered on
+  `detail.stage === "interactive"`.
+- `ready` → `pie-loading-complete`.
+- `section-controller-ready` → call
+  `waitForSectionController(timeoutMs)` or `getSectionController()`
+  on the layout CE, or filter `pie-stage-change` for
+  `detail.stage === "engine-ready"`.
 
 If toolkit is mounted, toolkit lifecycle events are emitted on a separate
 `pie-toolkit-*` stream. This separation avoids semantic overlap; bridge dedupe
@@ -335,6 +549,29 @@ await controller?.updateItemSession?.("q1", {
 The same controller snapshot is what the persistence strategy saves/loads.
 When a controller is reused for the same `sectionId`/`attemptId`, `updateInput()` refreshes composition input while preserving in-memory section session data.
 
+## Content trust boundary
+
+Section-player layouts embed `<pie-item-player>` elements for each item.
+Item and passage markup is sanitized by default via DOMPurify; see
+[pie-item-player README](./README.md#content-trust-boundary)
+property. Hosts can forward those settings through the section-player
+`runtime.player` overrides — the runtime flattens these onto the embedded
+`<pie-item-player>` instance, so any field not recognized by the kernel is
+passed straight through as a prop/attribute:
+
+```ts
+const runtime = {
+  playerType: "iife",
+  player: {
+    trustMarkup: false, // default, keeps DOMPurify on
+    // sanitizeMarkup: (html) => myCustomSanitize(html),
+  },
+};
+```
+
+Set `trustMarkup: true` only when the section payload is guaranteed to be
+produced by a trusted pipeline.
+
 ## Exports
 
 Published exports are intentionally minimal:
@@ -342,10 +579,13 @@ Published exports are intentionally minimal:
 - `@pie-players/pie-section-player`
 - `@pie-players/pie-section-player/components/section-player-splitpane-element`
 - `@pie-players/pie-section-player/components/section-player-vertical-element`
+- `@pie-players/pie-section-player/components/section-player-tabbed-element`
 - `@pie-players/pie-section-player/components/section-player-kernel-host-element`
 - `@pie-players/pie-section-player/components/section-player-shell-element`
 - `@pie-players/pie-section-player/components/section-player-item-card-element`
 - `@pie-players/pie-section-player/components/section-player-passage-card-element`
+- `@pie-players/pie-section-player/components/section-player-items-pane-element`
+- `@pie-players/pie-section-player/components/section-player-passages-pane-element`
 - `@pie-players/pie-section-player/contracts/layout-contract`
 - `@pie-players/pie-section-player/contracts/public-events`
 - `@pie-players/pie-section-player/contracts/runtime-host-contract`