@pie-players/pie-section-player 0.3.73 → 0.3.75

package/README.md

@@ -6,7 +6,9 @@ Section rendering package with layout custom elements:
 - `pie-section-player-vertical`
 - `pie-section-player-tabbed`
 
-Use the layout custom elements listed above for section rendering.
+A host that arranges the section itself builds its layout from
+`pie-section-player-kernel-host` and the two panes; see
+[Custom layout authoring](#custom-layout-authoring).
 
 ## Install
 
@@ -33,11 +35,16 @@ opt-out.
 import "@pie-players/pie-section-player";
 ```
 
-If hosts need explicit registration control, keep using documented component
-entrypoints under `@pie-players/pie-section-player/components/*`.
+The entrypoints under `@pie-players/pie-section-player/components/*` load one
+element each, together with every element it renders: a layout entry also
+registers the cards, panes and shell. They choose which layouts a host loads; the
+tag names stay fixed.
 
-Standalone browser variants for this package are intentionally deferred; the
-current supported contract is the default bundler entrypoints under `dist`.
+The entries are bundler-only: they import `@pie-players/pie-item-player`,
+`@pie-players/pie-default-tool-loaders` and `speech-rule-engine`, with the
+engine's JSON locale tables, by bare specifier and without import attributes.
+Items render through the host's one `@pie-players/pie-item-player`, which this
+package depends on at its own version.
 
 ## SectionController
 
@@ -59,17 +66,40 @@ the per-method contract.
 
 ```ts
 const host = document.querySelector("pie-section-player-splitpane") as any;
-const controller = await host.waitForSectionController?.(5000);
+const controller = await host.waitForSectionController(5000);
 ```
 
 `waitForSectionController(timeoutMs)` resolves when the layout CE has wired
 its controller (the same anchor `pie-stage-change` reaches with
-`detail.stage === "engine-ready"`). Use `getSectionController()` if you've
-already passed the readiness anchor synchronously.
+`detail.stage === "engine-ready"`), or with `null` once `timeoutMs` passes.
+Use `getSectionController()` if you've already passed the readiness anchor
+synchronously.
+
+The layout elements define their host methods from the moment they are
+created, so a host can call them before the element mounts. Until it mounts,
+`waitForSectionController` waits, `getSectionController()` returns `null`, the
+navigation methods return `false`, and `getSnapshot()` and the `select*` reads
+return `null` (`pie-section-player-kernel-host` returns its bootstrapping
+snapshot).
 
 ### Session lifecycle
 
-A typical host flow:
+Set `session` with `section` to restore a section. The controller created for
+that section applies it in replace mode in place of hydrating from the
+persistence strategy, before the controller is published, so the first
+composition, `engine-ready` and every reader see it. The strategy still receives
+every `persist()`.
+
+A later assignment applies through `applySession(value, { mode: "replace" })`
+under the rules `<pie-item-player>` applies to its `session`: a value equal to
+the current session is a no-op, so echoing `session-changed` back is safe, and an
+item session with neither a response value nor a response field leaves one that
+holds responses in place. `null` after creation is a no-op. A `section` change
+without a `session` assignment hydrates the new controller from the strategy.
+Reading `session` returns the assigned value until the controller is published,
+and a fresh `getSession()` snapshot after.
+
+Driving the controller directly:
 
 ```ts
 controller?.configureSessionPersistence?.({ context, strategy });
@@ -97,11 +127,25 @@ policy](#js-api-example-for-advanced-host-policy). Key event types:
 
 - `item-selected` — item navigation within the current section.
 - `item-session-data-changed` / `item-session-meta-changed` — per-item
-  session updates the persistence layer should observe.
-- `content-loaded` — passage / item / rubric finished loading.
+  session updates the persistence layer should observe. `sectionId` names the
+  section. `elementId` names the reporting element when the change carries one,
+  and `complete` is then that element's own. A commit carries
+  `sessionCommitReason` (see [Commit at a section
+  boundary](#commit-at-a-section-boundary)).
+- `item-complete-changed` — an item's completion flipped. An item is complete
+  when every element that has reported its completion is complete. A report
+  without `elementId`, and a restored session's item-level `complete`, set the
+  item's completion directly. A session restored through `applySession`
+  without `complete` is complete when it holds a response. A passage's own
+  `session-changed` stays inside its shell: a passage holds no response.
+- `content-loaded` — passage / item / rubric finished loading. Carries
+  `contentKind`, `itemId`, and `canonicalItemId`.
 - `section-loading-complete` — every renderable in the section finished
   loading.
 - `section-items-complete-changed` — aggregate completion flip.
+- `section-error` — an item player failed (`source: "item-player"`), or the
+  section runtime did (`source: "section-runtime"`), a rejected element warmup
+  included, which leaves the items unmounted.
 - `section-navigation-change` — the controller's section identity changed.
 - `formative-try-recorded` — a learner checked an answer.
 - `formative-reveal-changed` — the reveal state changed without a Try: a learner
@@ -119,6 +163,20 @@ policy](#js-api-example-for-advanced-host-policy). Key event types:
 - `timed-media-invalid` — authored `timedMedia` that cannot be delivered; the
   section renders without cue behavior.
 
+The helpers' default event sets leave out `formative-try-recorded`,
+`formative-reveal-changed`, `section-mastery-changed` and
+`timed-media-audio-started`. Name them in `subscribeItemEvents({ eventTypes })`,
+or subscribe through `subscribeSectionEvents`.
+
+Item-scoped events carry both id forms, and both are always populated.
+`itemId` is the bare `item.id` — the form the map returned by
+`getItemSessionsByItemId()` is keyed by, and the form `applySession` expects.
+`canonicalItemId` is that item's adapter identifier, and falls back to `itemId`
+when the section was not built from an adapter or no adapter ref matches it.
+Correlate with formative policy and `runtime.player.resolveBackend` by
+`canonicalItemId`; reach the session by `itemId`. `content-loaded` and
+`item-player-error` both carry the pair.
+
 ### Formative delivery
 
 Set `formative` on the section and the player renders a check-answer control per
@@ -145,12 +203,12 @@ projected over the section env — with `role: "instructor"` under
 `feedback: "solution"` — and the element draws the rest. Only that item's env
 changes; its neighbours stay editable. A retry withdraws the projection.
 
-Read the resolved state from `getFormativeProjection()`, or off
-`compositionModel.formative` in a custom layout. Drive it from a host through the
-same handle:
+Read the resolved state from `getFormativeProjection()`, or from
+`composition.formative` in a `composition-changed` event's detail. Drive it from a
+host through the same handle:
 
 ```ts
-const controller = await host.waitForSectionController?.(5000);
+const controller = await host.waitForSectionController(5000);
 // The learner's actions, budget-respecting.
 controller?.recordFormativeTry?.({ itemId, outcomes }); // outcomes from provideScore()
 controller?.retryFormativeItem?.({ itemId });
@@ -225,7 +283,7 @@ with its own player registers its own port instead, and that port outranks the
 card's discovery for as long as it is attached:
 
 ```ts
-const controller = await host.waitForSectionController?.(5000);
+const controller = await host.waitForSectionController(5000);
 // No `renderableId`: a host is asserting its own port, where a renderable's adapter
 // has to name itself and is ignored unless it is the resolved stimulus.
 controller?.attachMediaTimeSource?.(myThirdPartyPort);
@@ -264,14 +322,10 @@ for the contract and the decision record.
 
 ## Usage
 
-Import the custom-element registration entrypoint in consumers:
+Import the package root, which registers every section-player element:
 
 ```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';
+import '@pie-players/pie-section-player';
 ```
 
 Render in HTML/Svelte/JSX:
@@ -280,29 +334,51 @@ Render in HTML/Svelte/JSX:
 <pie-section-player-splitpane></pie-section-player-splitpane>
 ```
 
-Set complex values (`runtime`, `section`, `env`) as JS properties.
+Set complex values (`runtime`, `section`, `session`) as JS properties. `env` is a
+`runtime` field (`runtime.env`); the layout elements have no `env` property.
+
+Set `runtime` no later than `section`. When the player builds its own
+coordinator, the section's arrival rebuilds that coordinator from the current
+`runtime`, so both can be set a tick after the element mounts. Once the section
+has initialized, a change to `runtime.tools`, `runtime.assessmentId`,
+`runtime.accessibility`, `runtime.lazyInit`, `tool-config-strictness` or
+`toolRegistry` is reported once in the console and does not reach that
+coordinator; `runtime.tools.pnpEnforcement` still applies. Change a running
+coordinator through the one `toolkit-ready` carries, with
+`updateToolConfig(...)` or `updateToolsPlacement(...)`, or pass your own as
+`runtime.coordinator`.
 
 ## Runtime Inputs
 
-Both layout elements support:
+The layout elements (`pie-section-player-splitpane`,
+`pie-section-player-vertical`, `pie-section-player-tabbed`) support:
 
 - `runtime` (object): primary coordinator/tools/player runtime bundle
 - `section` (object): assessment section payload
-- `env` (object): optional top-level override for `{ mode, role }`
+- `session` (object, JS property only): the section's session, a `SectionControllerSessionState`; see [Session lifecycle](#session-lifecycle)
+- `assessment` (object, JS property only): the `AssessmentEntity` whose `personalNeedsProfile` and `settings` tool policy reads, forwarded to the coordinator the player builds. A coordinator passed in `runtime` is the host's to bind with `updateAssessment`. A section's own `personalNeedsProfile` is not read, and the player warns once when it finds one
 - `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 (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.)
+- `split-pane-min-region-width` (number, optional): splitpane minimum pane width in px. Clamped to 160–1200. Unset by default (split bounds stay at 20–80). Splitpane only.
+- `split-pane-collapse-strategy` (string, optional): splitpane stacked-mode strategy. Supported values: `tabbed` (default) and `vertical`. Splitpane only.
 - `base-heading-level` (number, optional): the heading level this player's card headings occupy, and the level every descendant's outline derives from. Clamped to 1–6; default 2. See [Heading structure](#heading-structure).
-- `show-toolbar` (boolean-like): accepts `true/false` and common string forms (`"true"`, `"false"`, `"1"`, `"0"`, `"yes"`, `"no"`)
+- `show-toolbar` (boolean-like): accepts `true/false` and common string forms (`"true"`, `"false"`, `"1"`, `"0"`, `"yes"`, `"no"`); default `false`, so tools placed at `section` level render only when it is `true`
+- `locale` (string, optional): BCP-47 locale for the player's own interface text. Unset renders `en-US`.
+- `runtime.contentLanguage` (string, optional, `runtime` only): BCP-47 language of the content where its markup names none, which read-aloud speaks in and picks catalog cards by. A `lang` between the content and its card wins; unset reads `en-US`. `locale` never sets it.
+- `nds-icons` (boolean): opt in to NDS icon buttons.
+- `tool-config-strictness` (string, optional): `off|warn|error` for tool-config validation; default `error`.
+- `split-pane-initial-passage-width` (number, optional): splitpane passage pane width in percent at mount. Clamped to 20–80; default 50. Splitpane only.
+- `iife-bundle-host` (string, optional): bundle host for the IIFE element pre-warm when `runtime.player.loaderOptions.bundleHost` is unset.
 - Host extension props (JS properties only): `toolRegistry`, `sectionHostButtons`, `itemHostButtons`, `passageHostButtons`, `hooks`
 
-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.
+When the viewport is no wider than `narrow-layout-breakpoint` (default 1100px),
+splitpane and vertical layout hosts normalize section toolbar placement to `top`.
+This includes `left`, `right`, `bottom`, and `none` values. Separately, the shell
+moves a `left` or `right` toolbar to `top` at a fixed 1100px, so with a smaller
+breakpoint side toolbars still move to the top from 1100px down.
 
 `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.
 
@@ -384,10 +460,7 @@ hooks for theming:
 - `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`
+Tabs also carry `data-pie-purpose="passage-label"` and `data-pie-purpose="item-label"`.
 
 Tab colors, spacing, and track geometry can be themed via CSS variables:
 `--pie-section-player-tab-color`, `--pie-section-player-tab-background`,
@@ -503,14 +576,14 @@ mountable-but-unoccupied result, not an error.
 The intended usage model is:
 
 - **CE props for default/standard flows (roughly 90% use cases)**:
-  - `assessment-id`, `section`, `section-id`, `attempt-id`, `debug`
+  - `section`, `section-id`, `attempt-id`, `debug`, `locale`, `nds-icons`, `tool-config-strictness`
   - `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`
+  - `content-max-width-no-passage`, `content-max-width-with-passage`, and on splitpane `split-pane-min-region-width`, `split-pane-collapse-strategy`
 - **JS API for advanced customization**:
   - 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
+  - Compose forward/backward eligibility in host code using `getSnapshot().navigation` + 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`)
   - Register host callbacks via `hooks` (for example `hooks.cardTitleFormatter`)
 
@@ -534,9 +607,9 @@ Advanced runtime configuration is supplied through the `runtime` object. Set pla
 
 Hosts can configure item-player backend delivery once at the section-player
 runtime level. Section-player derives a concrete `backend` prop for each
-embedded item player before it renders the item. This is intended for hosts such
-as Quiz Engine that need server-processed PIE models and server scoring without
-querying every nested `<pie-item-player>`.
+embedded item player before it renders the item. This is intended for hosts
+that need server-processed PIE models and server scoring without querying every
+nested `<pie-item-player>`.
 
 ```ts
 import type {
@@ -577,6 +650,10 @@ each embedded item player. Static delivery fields such as `baseUrl`, `auth`,
 `endpoints`, `assignmentId`, and `autosave` are preserved. Use `assignmentId`
 for shared attempt/player identity.
 
+An enabled `backend.delivery` also sets `hosted: true` on each embedded item
+player unless `runtime.player.hosted` is set, so the item players load no
+element controllers and render the models the server returns.
+
 `runtime.player.resolveBackend` is a section-player-reserved key. It is called
 with `{ itemId, canonicalItemId, item, itemIndex, itemSession, sectionId, env,
 baseBackend }` and is stripped before props reach `<pie-item-player>`. Use it
@@ -594,12 +671,73 @@ backend config is preserved.
 This backend delivery config is separate from the element-loader backend used
 for IIFE/ESM bundle preloading.
 
+### Preloaded elements
+
+With `runtime.playerType: "preloaded"` the section player loads no element
+code. Its pre-warm asserts that every tag the section's items and passages name
+is registered, so the host registers the elements first:
+
+```ts
+import { registerPreloadedElements } from "@pie-players/pie-item-player/preloaded";
+import * as delivery from "@pie-element/multiple-choice/browser/delivery";
+import * as controller from "@pie-element/multiple-choice/browser/controller";
+import manifest from "../package.json"; // pins "@pie-element/multiple-choice" exactly
+
+registerPreloadedElements(
+  [
+    {
+      tag: "pie-element-multiple-choice",
+      package: "@pie-element/multiple-choice",
+      version: manifest.dependencies["@pie-element/multiple-choice"],
+      element: delivery,
+      controller,
+    },
+  ],
+  { math: { assetRoot: "https://assets.example.com/npm" } },
+);
+
+sectionPlayer.runtime = { ...sectionPlayer.runtime, playerType: "preloaded" };
+```
+
+- Register before the section player mounts. A tag missing at pre-warm leaves
+  the items unmounted and raises a non-recoverable `element-preload` framework
+  error.
+- Install element packages with `npm install --save-exact`. npm otherwise saves
+  a caret range, which registration rejects as a `version`, and which a fresh
+  install can resolve to another release line: `^13.4.0-next.15` resolves to
+  the legacy `13.4.4`, which has no `./browser/*` modules.
+- Install every pie-elements-ng package from one release, in one install from
+  the same dist-tag, and upgrade them together. Elements whose `./browser/*`
+  builds typeset on `window.MathJax` share the MathJax the first of them loads,
+  in the build and configuration of that element's release, so in a mixed set
+  an element can typeset with a MathJax it was not built for. Elements that
+  bundle their own MathJax share none
+  ([One MathJax version per page](../../docs/item-player/loading-strategies.md#one-mathjax-version-per-page)).
+- Pass `math.assetRoot`, an npm root serving the fonts and speech the elements'
+  bundled MathJax loads, or `math.assetUrls`, each file's URL; without either,
+  elements on adapter 0.1.3 or later render without web fonts and speech
+  ([MathJax assets](../../docs/item-player/loading-strategies.md#mathjax-assets)).
+- Register one version per package. The players align every authored version
+  of a package to the registered one, and registering a second version throws.
+- Register each package's `controller` unless the item players are hosted
+  (`runtime.player.hosted`, or an enabled `runtime.player.backend.delivery`).
+  A player that is not hosted runs `model()` in the browser and warns for each
+  tag registered without one.
+- Only `@pie-element/*` builds from pie-elements-ng publish
+  `./browser/delivery` and `./browser/controller`.
+- Under TypeScript, the `package.json` import needs `resolveJsonModule`, and a
+  package version that ships no declarations for `./browser/*` needs a
+  `declare module` shim for those subpaths.
+
+See [`strategy="preloaded"`](../../docs/item-player/loading-strategies.md#strategypreloaded)
+for the registration contract.
+
 ### Host-owned focus
 
 Section-player does not move focus on behalf of host-level affordances such
 as "Skip to Main", nor does it make passage/question containers tab stops.
 Hosts own page chrome, skip links, landmarks, and any special focus placement.
-For example, Quiz Engine's Fixed Player shell can focus its own
+For example, a host shell can focus its own
 `main#main-content`; the next Tab then follows the browser's natural order
 into the first actionable control rendered inside the section player.
 
@@ -615,11 +753,16 @@ sequential keyboard navigation.
 </main>
 ```
 
-**Wired policy toggles.** Each `SectionPlayerPolicies` field has a real
-runtime effect; nothing in this surface is decorative.
+**Policy fields.** The layout accepts a partial `policies` object: every
+unset field, a missing section included, takes its value from
+`DEFAULT_SECTION_PLAYER_POLICIES`.
 
-- `readiness.mode` (`"progressive"` | `"strict"`) — drives readiness-event
-  emission via `createReadinessDetail` in `SectionPlayerLayoutKernel`.
+- `readiness.mode` (`"progressive"` | `"strict"`) — the mode the layout
+  kernel gates readiness by. Both modes
+  hold the `interactive` stage and `pie-loading-complete` until the section's
+  element pre-warm resolves and the item cards can mount. The kernel has no
+  later loading signal, so the two modes currently emit the same sequence.
+  Default: `"progressive"`.
 - `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
@@ -631,10 +774,8 @@ runtime effect; nothing in this surface is decorative.
   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.
+`resolveSectionPlayerPolicies(policies)` returns the filled-in object, for
+host code that needs the same gates.
 
 ### Navigation signals
 
@@ -643,20 +784,20 @@ layout host) can call them directly.
 
 Runtime configuration is explicit:
 
-- `runtime` owns runtime fields (`assessmentId`, `playerType`, `player`, `lazyInit`, `tools`, `accessibility`, `coordinator`, `isolation`, `env`, `createSectionController`).
+- `runtime` owns runtime fields (`assessmentId`, `playerType`, `player`, `lazyInit`, `tools`, `toolContextResolvers`, `accessibility`, `coordinator`, `createSectionController`, `isolation`, `env`, `contentLanguage` and the `on*` callbacks). `locale`, `nds-icons` and `tool-config-strictness` are attributes only.
 - Tool placement is configured through `runtime.tools.placement.section`, `runtime.tools.placement.item`, and `runtime.tools.placement.passage`.
-- 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.
+- Tool configuration validation is canonical in toolkit initialization (`pie-assessment-toolkit`), including toolbar overlays. Use the `tool-config-strictness` attribute (`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:
-  - `toolRegistry` overrides the default toolbar registry when provided
+- Host tool overrides:
+  - `toolRegistry` replaces the default toolbar registry when provided. Build it with `createPackagedToolRegistry({ toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS })` and register custom tools on it, since toolbars load each tool's element through the registry's loaders. A player that builds its own coordinator gives it this registry; a coordinator passed as `runtime.coordinator` keeps its own, which decides policy, so build that coordinator with the same registry
   - host buttons are appended per toolbar scope via `sectionHostButtons`, `itemHostButtons`, `passageHostButtons`
 
-Debug logging can be controlled per section-player host:
+Debug logging is page-wide. A layout's `debug` attribute writes `window.PIE_DEBUG`, the flag every PIE logger on the page reads, so the last host to set it decides for all of them:
 
 - Enable: `<pie-section-player-splitpane debug="true">`
 - Disable: `<pie-section-player-splitpane debug="false">` (or `debug="0"`)
 
-You can also disable globally via `window.PIE_DEBUG = false`.
+Without a `debug` attribute a layout follows `window.PIE_DEBUG`, which a host can set directly.
 
 See the progressive demo routes in `apps/section-demos/src/routes/(demos)` (for example `single-question/+page.svelte` and `session-hydrate-db/+page.svelte`) for end-to-end host integrations.
 
@@ -685,49 +826,138 @@ Structural composition changes (new/removed/reordered entities) may legitimately
 
 ## Custom layout authoring
 
-For section layout authors, `pie-section-player-shell` is the primary abstraction:
-
-- Use `pie-section-player-shell` to place the section toolbar around your layout body.
-- Keep your custom layout logic focused on passages/items and layout UI.
-- Treat `pie-section-player-base` as internal runtime plumbing that wraps the shell.
-- Use `pie-section-player-item-card` and `pie-section-player-passage-card` as reusable card primitives.
-- Prefer shared context for cross-cutting card render plumbing (resolved player tag/action) over repeated prop drilling.
-
-Minimal pattern for package layout components:
-
-```svelte
-<pie-section-player-base runtime={effectiveRuntime} {section} section-id={sectionId} attempt-id={attemptId}>
-  <pie-section-player-shell
-    show-toolbar={showToolbar}
-    toolbar-position={toolbarPosition}
-    toolRegistry={toolRegistry}
-    sectionHostButtons={sectionHostButtons}
-  >
-    <!-- layout-specific body -->
-    <pie-section-player-passage-card
-      passage={passage}
-      playerParams={passagePlayerParams}
-      passageToolbarTools={passageToolbarTools}
-      toolRegistry={toolRegistry}
-      hostButtons={passageHostButtons}
-    ></pie-section-player-passage-card>
-    <pie-section-player-item-card
-      item={item}
-      canonicalItemId={canonicalItemId}
-      playerParams={itemPlayerParams}
-      itemToolbarTools={itemToolbarTools}
-      toolRegistry={toolRegistry}
-      hostButtons={itemHostButtons}
-    ></pie-section-player-item-card>
-  </pie-section-player-shell>
-</pie-section-player-base>
+A host builds its own section layout from `pie-section-player-kernel-host` and the
+two panes. The kernel host runs the section: toolkit, section controller,
+readiness, element pre-warm and the section toolbar. Its element children are the
+layout, and the panes inside them render the section's items and passages. The
+stock layouts are built from the same panes.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <style>
+      body { margin: 0; }
+      pie-section-player-kernel-host { display: block; height: 100vh; }
+      .columns { display: grid; grid-template-columns: 3fr 2fr; height: 100%; }
+      .column { min-height: 0; overflow: auto; }
+    </style>
+    <script type="module">
+      import "https://cdn.jsdelivr.net/npm/@pie-players/pie-section-player@x.y.z/dist/browser/pie-section-player.js";
+
+      const player = document.querySelector("pie-section-player-kernel-host");
+      player.addEventListener("pie-loading-complete", () => {
+        console.log("ready", player.getSnapshot().navigation);
+      });
+      player.runtime = { env: { mode: "gather", role: "student" } };
+      player.section = {
+        identifier: "water-cycle",
+        rubricBlocks: [
+          {
+            identifier: "passage-1",
+            class: "stimulus",
+            view: ["candidate"],
+            passage: {
+              id: "passage-1",
+              config: {
+                markup: "<p>Water evaporates, condenses into clouds and falls as rain.</p>",
+                elements: {},
+                models: [],
+              },
+            },
+          },
+        ],
+        assessmentItemRefs: [
+          {
+            identifier: "item-1",
+            item: {
+              id: "item-1",
+              config: {
+                markup: "<p>Name the stage in which water vapour forms clouds.</p>",
+                elements: {},
+                models: [],
+              },
+            },
+          },
+        ],
+      };
+    </script>
+  </head>
+  <body>
+    <pie-section-player-kernel-host section-id="water-cycle" attempt-id="attempt-1">
+      <div class="columns">
+        <div class="column"><pie-section-player-items-pane></pie-section-player-items-pane></div>
+        <div class="column"><pie-section-player-passages-pane></pie-section-player-passages-pane></div>
+      </div>
+    </pie-section-player-kernel-host>
+  </body>
+</html>
 ```
 
+The example loads the [browser build](../../docs/setup/cdn_usage.md#section-player-browser-build).
+A bundled host imports `@pie-players/pie-section-player`, which defines the
+kernel host and the panes too. An item with PIE elements names them in
+`config.elements` and carries their `config.models`, as in any section. The
+`/custom-layout` route of `apps/section-demos`
+([source](../../apps/section-demos/src/routes/%28demos%29/custom-layout/+page.svelte))
+builds the same two columns in Svelte.
+
+### Kernel host
+
+- **Inputs and host methods.** Those of the layout elements in
+  [Runtime Inputs](#runtime-inputs), without the layout dimensions
+  (`narrow-layout-breakpoint`, `content-max-width-*`, `split-pane-*`).
+- **DOM.** The open shadow root holds the toolkit and the section toolbar around
+  one default slot; `show-toolbar` and `toolbar-position` place the toolbar around
+  the layout. The children, the panes and the content they render stay in light
+  DOM, where page styles and the content stylesheet reach them. The element has
+  no styles of its own, so the host gives it `display` and a height.
+- **Stock body.** With no element children it renders its own layout, the
+  passages pane above the items pane, and places the passages pane only for a
+  section with passages. The stock body leaves when the first element child
+  arrives and returns when the last one leaves. Text and comment children do not
+  count, so markup whitespace and a framework's placeholder comments leave it in
+  place.
+- **Navigation and state.** The host methods (`navigateNext`, `navigatePrevious`,
+  `navigateTo`, `getSnapshot`, `getSectionController`, `waitForSectionController`)
+  and the events (`pie-stage-change`, `pie-loading-complete`,
+  `composition-changed`, `session-changed`, `framework-error`, `toolkit-ready`)
+  are those of the stock layouts. `detail.sourceCe` on its `pie-stage-change`
+  and `pie-loading-complete` events reads `pie-section-player-kernel-host`.
+
+### Panes
+
+`<pie-section-player-items-pane>` renders the item cards of the current
+composition, with their toolbars, and runs the element pre-warm;
+`<pie-section-player-passages-pane>` renders the passage cards. A pane takes no
+attributes or properties, and its pre-warm failures arrive as the section
+player's `framework-error` and `element-preload-error` events. It reads the
+section player it belongs to from a context the kernel publishes, so it renders
+at any depth below the kernel host, and outside a section player it renders
+nothing.
+
+- **One pane of each kind renders**: the first connected. A second pane of a
+  kind renders nothing and takes over when the first disconnects; the player
+  reports the duplicate once in the console.
+- **Readiness follows the rendering items pane.** `interactive` and
+  `pie-loading-complete` wait for its element pre-warm, and reports from any
+  other pane are ignored. A section with items and no items pane never reaches
+  either; the player reports it once in the console a task after
+  `section-ready`.
+- **The passages pane is optional.** A section without passages needs none, and
+  readiness does not wait for it.
+- **Scrolling belongs to the layout.** The items pane's scroll hint follows the
+  nearest ancestor with `overflow-y: auto` or `scroll`, so the layout gives each
+  pane's container that overflow and a bounded height. The stock layouts' pane backdrops and margins
+  stay with those layouts; the cards keep their tags and
+  [styling hooks](#card-header-styling-hooks).
+
 ### JS API example for advanced host policy
 
 ```ts
 const host = document.querySelector("pie-section-player-splitpane") as any;
-const controller = await host.waitForSectionController?.(5000);
+const controller = await host.waitForSectionController(5000);
 let sectionComplete = false;
 
 const unsubscribe = controller?.subscribe?.((event: any) => {
@@ -737,7 +967,7 @@ const unsubscribe = controller?.subscribe?.((event: any) => {
 });
 
 function canAdvance() {
-  const nav = host.selectNavigation?.();
+  const nav = host.getSnapshot?.()?.navigation;
   return Boolean(nav?.canNext && sectionComplete);
 }
 ```
@@ -758,7 +988,7 @@ const unsubscribeSection = coordinator.subscribeSectionLifecycleEvents({
 });
 ```
 
-Subscribe **after** the first `getOrCreateSectionController(...)` resolves (or after `toolkit-ready` once the section player has fully wired its controller — typically the safest anchor in host code is `toolkit-ready` followed by the first controller-resolve). Calling subscribe before any cohort exists throws.
+Subscribe **after** the first `getOrCreateSectionController(...)` resolves (or after `toolkit-ready` once the section player has fully wired its controller — typically the safest anchor in host code is `toolkit-ready` followed by the first controller-resolve). Calling subscribe before the first `getOrCreateSectionController(...)` call throws; a listener added while a section is starting binds when that section becomes active.
 
 Use `subscribeSectionEvents(...)` only for advanced mixed filtering requirements.
 
@@ -810,52 +1040,41 @@ 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.
 
-Canonical lifecycle stream (engine-routed, dispatched on the outer layout CE):
+Canonical lifecycle stream (engine-routed, dispatched on the outer layout CE,
+bubbling and composed):
 
 - `pie-stage-change` — single typed transition stream covering
   `composed` → `engine-ready` → `interactive` → `disposed`. Payload is a
-  `StageChangeDetail`.
-- `pie-loading-complete` — fires once per cohort when every item has
-  loaded (kernel-routed; gated on `interactive`).
+  `StageChangeDetail`. A non-recoverable framework error before
+  `interactive` emits the current stage `failed` and each stage it never
+  reached `skipped`.
+- `pie-loading-complete` — fires once per cohort, when the section's element
+  pre-warm resolves for the current composition and the item cards can mount
+  (kernel-routed).
 - `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.
-
-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; consume either.
+  framework boundary. Payload is a `FrameworkErrorModel`. The toolkit
+  dispatches it once per error, bubbling and composed, so it reaches the
+  layout CE and `document`; errors from a coordinator the host passes as
+  `runtime.coordinator` arrive the same way.
+  `tests/section-player-event-delivery.spec.ts` pins these counts.
+
+Callbacks on `runtime`:
+
+- `runtime.onStageChange(detail)` and `runtime.onLoadingComplete(detail)`.
+- `runtime.onFrameworkError(model)` fires once per error regardless of
+  wrapper depth, like the `framework-error` DOM event; 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-framework-error`
+- `pie-section-element-preload-retry`
+- `pie-section-element-preload-error`
 
 Build consumers against these canonical lifecycle events:
 
-- `readiness-change` → listen for `pie-stage-change`. The readiness
-  payload is also available via `selectReadiness()` /
-  `getSnapshot().readiness` on the layout CE.
+- `readiness-change` → listen for `pie-stage-change`.
 - `interaction-ready` → `pie-stage-change` filtered on
   `detail.stage === "interactive"`.
 - `ready` → `pie-loading-complete`.
@@ -880,7 +1099,7 @@ Section session data can be managed either through persistence hooks or directly
 
 ```ts
 const host = document.querySelector("pie-section-player-splitpane") as any;
-const controller = await host.waitForSectionController?.(5000);
+const controller = await host.waitForSectionController(5000);
 
 // Read current section session snapshot.
 const currentSession = controller?.getSession?.();
@@ -905,9 +1124,34 @@ await controller?.updateItemSession?.("q1", {
 });
 ```
 
-The same controller snapshot is what the persistence strategy saves/loads.
+The same controller snapshot is what the persistence strategy saves/loads, and
+what the layout's `session` property takes.
 When a controller is reused for the same `sectionId`/`attemptId`, `updateInput()` refreshes composition input while preserving in-memory section session data.
 
+### One item as a section
+
+`sectionFromItem` wraps one item config, in the shape `<pie-item-player config>`
+takes, and optionally its session, in the `section` and `session` the layouts
+take. It is exported from the package root and from
+`@pie-players/pie-section-player/item-section`, which defines no custom element
+and imports in Node.
+
+```ts
+import { sectionFromItem } from "@pie-players/pie-section-player/item-section";
+
+const { section, session } = sectionFromItem(itemConfig, { session: itemSession });
+player.setAttribute("section-id", section.identifier);
+player.section = section;
+player.session = session;
+```
+
+The item ref's `identifier` and the item's `id` are the config's `id`, so every
+`itemId` the section reports is the id the host already holds. An advanced
+config's `passage` becomes the item's passage, and its `instructorResources` and
+`defaultExtraModels` stay on the item's config. The section carries no `baseId`
+or `version`; `options.sectionId` names the section, which defaults to the
+config's `id`.
+
 ### Commit at a section boundary
 
 A delivery element coalesces its `session-changed` dispatch, so a response the
@@ -917,13 +1161,23 @@ controller commits pending element sessions before item navigation, before
 The player also commits when an item shell tears down and when the page goes
 hidden.
 
-The commit reaches the controller, and the controller's own
-`PIE_ITEM_SESSION_CHANGED_EVENT` is what reaches a host. A raw `session-changed`
-does not leave a section: `<pie-item-shell>` stops it and re-dispatches the
-normalized event, so a host listening on `document` for `session-changed`
-receives nothing from inside a section player, before this change or after it.
+A committed response travels like any other. A raw element `session-changed`
+does not leave its `<pie-item-scope>`, which re-dispatches it as the normalized
+`item-session-changed` (`PIE_ITEM_SESSION_CHANGED_EVENT`); the toolkit then
+publishes the section's canonical `session-changed`. Both bubble through the
+layout element to `document`, and a listener on either receives each dispatch
+once.
 Host code persists from the controller's events or from its session snapshot.
 
+Each of those events marks a commit with `sessionCommitReason`
+(`"teardown" | "navigate" | "page-hidden"`): `item-session-changed`, the
+toolkit's `session-changed`, and the controller's `item-session-data-changed`
+and `item-session-meta-changed`. A commit at a section swap or item navigation
+reports the item being left, which the host may already have moved past, so a
+handler that sets its current item or navigation state from these events leaves
+that state alone on a commit and persists the commit's session as usual. The
+controller's events also carry `sectionId`, the section the item belongs to.
+
 Navigation inside a section keeps every item mounted, so nothing is discarded
 and the element's own debounce would complete on its own. The commit still runs
 there because the response belongs to the item being left: a host that persists
@@ -941,8 +1195,9 @@ pending response at those boundaries.
 ## 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)
+Item and passage markup is sanitized by default via DOMPurify; see the
+[pie-item-player README](../item-player/README.md#content-trust-boundary)
+for the allow-list, the `trust-markup` opt-out and the `sanitizeMarkup`
 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
@@ -966,21 +1221,12 @@ produced by a trusted pipeline.
 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/browser`, the self-contained browser build ([CDN usage](../../docs/setup/cdn_usage.md#section-player-browser-build))
+- `@pie-players/pie-section-player/components/section-player-splitpane-element`, which resolves to the package root
 - `@pie-players/pie-section-player/contracts/runtime-host-contract`
-- `@pie-players/pie-section-player/contracts/layout-parity-metadata`
 - `@pie-players/pie-section-player/contracts/host-hooks`
 - `@pie-players/pie-section-player/policies`
+- `@pie-players/pie-section-player/item-section`
 
 ## Development