@pie-players/pie-section-player 0.3.52 → 0.3.54

package/README.md

@@ -178,9 +178,14 @@ 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`.
+Tab colors, spacing, and track geometry can be themed via CSS variables:
+`--pie-section-player-tab-color`, `--pie-section-player-tab-background`,
+`--pie-section-player-tab-active-color`,
+`--pie-section-player-tab-active-background`,
+`--pie-section-player-tab-gap`,
+`--pie-section-player-tab-track-radius`,
+`--pie-section-player-tab-track-padding`, and
+`--pie-section-player-tab-padding-block`.
 
 ### Card header styling hooks
 
@@ -191,16 +196,23 @@ Passage and item cards share a common header row
 - 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.
+- Card corners default to `8px`. Hosts/themes can override the card radius via
+  `--pie-section-player-card-radius`.
 - 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.
+- When a header fill is provided, header top corners default just inside the
+  card radius. Hosts/themes can override them independently via
+  `--pie-section-player-card-header-radius`.
 
 Example (host CSS):
 
 ```css
 pie-section-player-passage-card,
 pie-section-player-item-card {
+  --pie-section-player-card-radius: 8px;
   --pie-section-player-card-header-background: #c9e5e6;
+  --pie-section-player-card-header-radius: 7px;
 }
 ```
 
@@ -240,6 +252,70 @@ host.hooks = {
 
 Advanced runtime configuration is supplied through the `runtime` object. Set player config, tools, accessibility, coordinator, env, and `createSectionController` on `runtime.<key>`.
 
+### Backend delivery for embedded items
+
+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>`.
+
+```ts
+import type {
+  SectionPlayerRuntimeConfig,
+} from "@pie-players/pie-section-player";
+
+const runtime: SectionPlayerRuntimeConfig = {
+  playerType: "iife",
+  env: {
+    mode: "gather",
+    role: "student",
+  },
+  player: {
+    backend: {
+      delivery: {
+        enabled: true,
+        baseUrl: bffUrl,
+        assignmentId: playerSessionId,
+        endpoints: {
+          load: "/api/player/load",
+          saveSession: "/api/player/save",
+          model: "/api/player/model",
+          score: "/api/player/score",
+        },
+        autosave: { enabled: true, debounceMs: 250 },
+      },
+    },
+  },
+};
+
+sectionPlayer.runtime = runtime;
+```
+
+When `runtime.player.backend.delivery` is enabled, section-player treats
+`itemId` and `sessionId` as per-item delivery identity. It derives them from
+`canonicalItemId || item.id` and the item session before forwarding `backend` to
+each embedded item player. Static delivery fields such as `baseUrl`, `auth`,
+`endpoints`, `assignmentId`, and `autosave` are preserved. Use `assignmentId`
+for shared attempt/player identity.
+
+`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
+only when the backend needs custom per-item identity mapping. The resolver
+receives cloned backend objects, so per-item identity changes do not mutate the
+shared runtime configuration or leak across items.
+
+Section-player only derives the concrete `backend` prop. It does not call
+`loadFromBackend()` on nested item players. Embedded `<pie-item-player>` loads
+automatically when its derived `backend.delivery` config has a load signature,
+so every mounted item player issues one backend load for its own item. Passage
+players do not receive item delivery backend config, but shared non-delivery
+backend config is preserved.
+
+This backend delivery config is separate from the element-loader backend used
+for IIFE/ESM bundle preloading.
+
 ### Host-owned focus
 
 Section-player does not move focus on behalf of host-level affordances such

package/dist/components/shared/section-player-backend-delivery.d.ts

@@ -0,0 +1,32 @@
+import { BackendConfig } from '@pie-players/pie-item-player';
+import { PlayerOverrides, RuntimeConfig } from '@pie-players/pie-assessment-toolkit/runtime/internal';
+import { ItemEntity } from '@pie-players/pie-players-shared/types';
+export type SectionPlayerBackendResolverContext = {
+    itemId: string;
+    canonicalItemId: string;
+    item: ItemEntity;
+    itemIndex: number;
+    itemSession?: Record<string, unknown>;
+    sectionId?: string;
+    env: Record<string, unknown>;
+    baseBackend: BackendConfig;
+};
+export type SectionPlayerBackendResolver = (context: SectionPlayerBackendResolverContext, baseBackend: BackendConfig) => BackendConfig | null | undefined;
+export type SectionPlayerRuntimePlayerConfig = Omit<PlayerOverrides, "backend" | "resolveBackend"> & {
+    backend?: BackendConfig | null;
+    resolveBackend?: SectionPlayerBackendResolver;
+};
+export type SectionPlayerRuntimeConfig = Omit<RuntimeConfig, "player"> & {
+    player?: SectionPlayerRuntimePlayerConfig | null;
+};
+export type ResolveItemPlayerBackendPropsArgs = {
+    resolvedPlayerProps: Record<string, unknown>;
+    item: ItemEntity;
+    canonicalItemId: string;
+    itemSession?: Record<string, unknown>;
+    itemIndex?: number;
+    sectionId?: string;
+    env: Record<string, unknown>;
+};
+export declare function resolveItemPlayerPropsWithBackend(args: ResolveItemPlayerBackendPropsArgs): Record<string, unknown>;
+export declare function stripItemDeliveryBackendProps(resolvedPlayerProps: Record<string, unknown>): Record<string, unknown>;

package/dist/components/shared/section-player-host-runtime.d.ts

@@ -22,6 +22,13 @@ export declare function resolvePlayerRuntime(args: {
             [x: string]: unknown;
         };
         loaderConfig?: import('@pie-players/pie-players-shared').LoaderConfig;
+        hosted: boolean;
+    } | {
+        loaderOptions: {
+            [x: string]: unknown;
+        };
+        loaderConfig?: import('@pie-players/pie-players-shared').LoaderConfig;
+        hosted?: undefined;
     };
     resolvedPlayerEnv: Record<string, unknown>;
     strategy: import('@pie-players/pie-players-shared').ItemPlayerStrategy;
@@ -55,6 +62,13 @@ export declare function resolveSectionPlayerRuntimeState(args: RuntimeInputs): {
                 [x: string]: unknown;
             };
             loaderConfig?: import('@pie-players/pie-players-shared').LoaderConfig;
+            hosted: boolean;
+        } | {
+            loaderOptions: {
+                [x: string]: unknown;
+            };
+            loaderConfig?: import('@pie-players/pie-players-shared').LoaderConfig;
+            hosted?: undefined;
         };
         resolvedPlayerEnv: Record<string, unknown>;
         strategy: import('@pie-players/pie-players-shared').ItemPlayerStrategy;

package/dist/components/shared/section-player-view-state.d.ts

@@ -25,6 +25,7 @@ export declare function getItemPlayerParams(args: {
     resolvedPlayerAttributes: Record<string, string>;
     resolvedPlayerProps: Record<string, unknown>;
     playerStrategy: string;
+    itemIndex?: number;
 }): PlayerElementParams;
 export declare function getCanonicalItemId(args: {
     compositionModel: SectionCompositionModel;

package/dist/pie-section-player.d.ts

@@ -7,3 +7,4 @@ export type { ReadinessPolicyAdapter, SectionPlayerPolicies, SectionPlayerReadin
 export { DEFAULT_SECTION_PLAYER_POLICIES, isPreloadEnabled, isTelemetryEnabled, } from './policies/index.js';
 export type { SectionPlayerCardTitleContext, SectionPlayerCardTitleFormatter, SectionPlayerItemTitleContext, SectionPlayerPassageTitleContext, } from './contracts/card-title-formatters.js';
 export type { SectionPlayerHostHooks } from './contracts/host-hooks.js';
+export type { SectionPlayerBackendResolver, SectionPlayerBackendResolverContext, SectionPlayerRuntimeConfig, SectionPlayerRuntimePlayerConfig, } from './components/shared/section-player-backend-delivery.js';