@pie-players/pie-assessment-toolkit 0.3.73 → 0.3.75

package/dist/runtime/section-runtime-engine-host-context.js

@@ -1,95 +0,0 @@
-/**
- * Cross-Custom-Element context for the section runtime engine (M7 PR 6).
- *
- * The toolkit CE renders inside its own Shadow DOM, so Svelte's native
- * `setContext`/`getContext` (used by `engine-context.ts`) cannot bridge
- * the kernel-provided engine reference to the toolkit's component tree.
- * This module exposes a `@pie-players/pie-context` based context that
- * does cross the CE boundary via DOM events:
- *
- *   - The kernel (`SectionPlayerLayoutKernel.svelte`) installs a
- *     `ContextProvider` for `sectionRuntimeEngineHostContext` on its
- *     `host` (the layout CE). The provider value carries a narrow
- *     lifecycle handle for the engine owned by that kernel mount.
- *   - The toolkit CE installs a `ContextConsumer` on its own host. When
- *     wrapped by a section player layout, the consumer resolves to the
- *     kernel's lifecycle handle and suppresses its standalone lifecycle
- *     DOM emits in favor of the section-player host. Controller-side
- *     calls (`register`, `handleContent*`, `initialize`, etc.) remain
- *     owned by the toolkit's locally-constructed engine. When
- *     standalone, no host provider responds and the toolkit keeps using
- *     its standalone lifecycle path.
- *
- * The two engine-context surfaces (`SECTION_RUNTIME_ENGINE_KEY` and
- * this one) are deliberately distinct:
- *   - `SECTION_RUNTIME_ENGINE_KEY` (Svelte context) stays scoped to a
- *     single component tree (kernel + descendants in the same shadow
- *     root) and is the right hook for in-tree consumers.
- *   - `sectionRuntimeEngineHostContext` (DOM-event context) is the
- *     bridge for cross-CE consumers and only carries data that is safe
- *     to share across CE boundaries (a stable lifecycle handle).
- *
- * **Stability.** This export is part of the stable runtime/engine
- * surface; the symbol identity and value shape are part of the
- * cross-CE contract. Renaming or replacing the symbol is a major
- * breaking change. Adding optional fields to the value shape is
- * allowed; required fields are not.
- */
-import { ContextConsumer, createContext, } from "@pie-players/pie-context";
-/**
- * `pie-context` context key for the cross-CE engine bridge. Uses a
- * `Symbol.for(...)` registry key so providers and consumers in
- * separately-bundled CEs see the same identity.
- */
-export const sectionRuntimeEngineHostContext = createContext(Symbol.for("pie.sectionRuntimeEngineHostContext"));
-/**
- * Connect a DOM host to the cross-CE engine context with the same
- * provider-retry semantics used elsewhere in the toolkit (initial
- * synchronous request + `context-provider` re-request + 50 ms polling
- * fallback up to 200 attempts ≈ 10 s).
- *
- * The retry mirrors the existing
- * `connectAssessmentToolkitHostRuntimeContext` infrastructure so the
- * timing characteristics of cross-CE handshakes stay consistent across
- * the toolkit's contexts.
- *
- * Returns a cleanup function that disconnects the consumer and clears
- * the retry interval. Standalone toolkits naturally exhaust the retry
- * window without ever resolving and continue using their local
- * engine — that is by design and is not an error.
- */
-export function connectSectionRuntimeEngineHostContext(host, onValue) {
-    let hasValue = false;
-    const consumer = new ContextConsumer(host, {
-        context: sectionRuntimeEngineHostContext,
-        subscribe: true,
-        onValue: (value) => {
-            hasValue = true;
-            onValue(value);
-        },
-    });
-    consumer.connect();
-    const onContextProvider = (event) => {
-        if (event.context !==
-            sectionRuntimeEngineHostContext) {
-            return;
-        }
-        consumer.requestValue();
-    };
-    host.addEventListener("context-provider", onContextProvider);
-    let attempts = 0;
-    const maxAttempts = 200;
-    const retryTimer = globalThis.setInterval(() => {
-        if (hasValue || attempts >= maxAttempts) {
-            globalThis.clearInterval(retryTimer);
-            return;
-        }
-        attempts += 1;
-        consumer.requestValue();
-    }, 50);
-    return () => {
-        globalThis.clearInterval(retryTimer);
-        host.removeEventListener("context-provider", onContextProvider);
-        consumer.disconnect();
-    };
-}

package/dist/runtime/stage-emit-gate.d.ts

@@ -1,92 +0,0 @@
-/**
- * Stage-emit suppression gate (M7 PR 6).
- *
- * `PieAssessmentToolkit.svelte` builds a `createStageTracker(...)` whose
- * `emit` callback dispatches the toolkit CE's `pie-stage-change` DOM
- * event and invokes the runtime-tier `onStageChange` callback. PR 6
- * introduces the wrapped/standalone branch:
- *
- *   - **Standalone** (no host lifecycle provider on
- *     the layout CE host): emit + `onStageChange` fire as before.
- *   - **Wrapped** (kernel publishes its lifecycle handle via
- *     `sectionRuntimeEngineHostContext` and the toolkit consumer
- *     resolves it): emit + `onStageChange` are suppressed on the
- *     toolkit CE, because the kernel's engine already emits the
- *     canonical `pie-stage-change` chain on the layout CE host and
- *     invokes the runtime-tier callback. Without suppression the
- *     toolkit CE would also dispatch its own event, which bubbles
- *     through `composed: true` to the layout CE host and produces a
- *     duplicate emission for outside listeners.
- *
- * The internal `stageTracker` latch state advances **before** this
- * helper is reached (the latch is updated inside
- * `createStageTracker.enter` prior to `opts.emit(...)`), so suppression
- * here only short-circuits the externally-visible side effects. The
- * toolkit's own readiness path (`waitUntilReady` / `engine-ready` /
- * `interactive`) keeps working in standalone mode and degenerates into
- * a series of suppressed emits in wrapped mode without losing any
- * latch transitions.
- *
- * Splitting this helper out of the inline `emit:` closure in
- * `PieAssessmentToolkit.svelte` lets us pin the suppression branch in a
- * unit test without mounting the toolkit CE — see
- * `tests/runtime/stage-emit-gate.test.ts`. The closure in the toolkit
- * passes thunks for `isSuppressed` and `getOnStageChange` so the live
- * Svelte reactive variables (`hostLifecycleEngine`, `onStageChange`) are
- * read at emit time, not captured at construction time. This keeps the
- * pre-PR-6 behavior of always reading the latest `onStageChange` prop
- * value (cohort change, host swap, etc.) intact.
- *
- * NOT a public surface: this helper is internal to the toolkit and is
- * not exported from `runtime/engine.ts`. It only exists to make the
- * gate testable.
- */
-import type { StageChangeDetail } from "@pie-players/pie-players-shared/pie";
-export type StageOnChangeHandler = (detail: StageChangeDetail) => void;
-export interface StageEmitGateContext {
-    /**
-     * Reads the current suppression flag. Implemented as a thunk so
-     * the reactive Svelte `$state(hostLifecycleEngine)` is read at emit
-     * time. Return `true` to suppress; `false` to fire.
-     */
-    isSuppressed: () => boolean;
-    /**
-     * Dispatches the `pie-stage-change` DOM event on the toolkit's
-     * CE host. In `PieAssessmentToolkit.svelte` this is the
-     * Svelte-generated `emit("pie-stage-change", detail)` helper.
-     */
-    dispatchDomEvent: (detail: StageChangeDetail) => void;
-    /**
-     * Reads the current `onStageChange` runtime-tier callback. Thunk
-     * so the latest reassigned handler is invoked, not whichever
-     * handler was current at construction time.
-     */
-    getOnStageChange: () => StageOnChangeHandler | null | undefined;
-    /**
-     * Optional logger for handler errors. Defaults to `console.error`
-     * with the same prefix the toolkit used pre-PR-6 so test output
-     * matches production logs.
-     */
-    logHandlerError?: (error: unknown) => void;
-}
-/**
- * Run the toolkit's stage emit pipeline with the suppression gate
- * applied.
- *
- *   - When `isSuppressed()` returns `true`, the helper returns
- *     immediately with neither side effect.
- *   - Otherwise it dispatches the `pie-stage-change` DOM event first,
- *     then invokes `onStageChange(detail)` (preserving the
- *     "DOM-event-then-callback" ordering pre-PR-6 consumers depend
- *     on).
- *   - A throwing `onStageChange` handler does not interrupt the DOM
- *     event (already fired) and does not propagate up to
- *     `stageTracker.enter` (latch state already advanced); the error
- *     is logged and swallowed, matching pre-PR-6 behavior.
- *
- * Returns `true` if the emit pipeline ran (i.e. it was not
- * suppressed); `false` if it was suppressed. Tests use the return
- * value to assert the gate's decision in isolation from the side
- * effects.
- */
-export declare function runStageEmitWithSuppression(context: StageEmitGateContext, detail: StageChangeDetail): boolean;

package/dist/runtime/stage-emit-gate.js

@@ -1,82 +0,0 @@
-/**
- * Stage-emit suppression gate (M7 PR 6).
- *
- * `PieAssessmentToolkit.svelte` builds a `createStageTracker(...)` whose
- * `emit` callback dispatches the toolkit CE's `pie-stage-change` DOM
- * event and invokes the runtime-tier `onStageChange` callback. PR 6
- * introduces the wrapped/standalone branch:
- *
- *   - **Standalone** (no host lifecycle provider on
- *     the layout CE host): emit + `onStageChange` fire as before.
- *   - **Wrapped** (kernel publishes its lifecycle handle via
- *     `sectionRuntimeEngineHostContext` and the toolkit consumer
- *     resolves it): emit + `onStageChange` are suppressed on the
- *     toolkit CE, because the kernel's engine already emits the
- *     canonical `pie-stage-change` chain on the layout CE host and
- *     invokes the runtime-tier callback. Without suppression the
- *     toolkit CE would also dispatch its own event, which bubbles
- *     through `composed: true` to the layout CE host and produces a
- *     duplicate emission for outside listeners.
- *
- * The internal `stageTracker` latch state advances **before** this
- * helper is reached (the latch is updated inside
- * `createStageTracker.enter` prior to `opts.emit(...)`), so suppression
- * here only short-circuits the externally-visible side effects. The
- * toolkit's own readiness path (`waitUntilReady` / `engine-ready` /
- * `interactive`) keeps working in standalone mode and degenerates into
- * a series of suppressed emits in wrapped mode without losing any
- * latch transitions.
- *
- * Splitting this helper out of the inline `emit:` closure in
- * `PieAssessmentToolkit.svelte` lets us pin the suppression branch in a
- * unit test without mounting the toolkit CE — see
- * `tests/runtime/stage-emit-gate.test.ts`. The closure in the toolkit
- * passes thunks for `isSuppressed` and `getOnStageChange` so the live
- * Svelte reactive variables (`hostLifecycleEngine`, `onStageChange`) are
- * read at emit time, not captured at construction time. This keeps the
- * pre-PR-6 behavior of always reading the latest `onStageChange` prop
- * value (cohort change, host swap, etc.) intact.
- *
- * NOT a public surface: this helper is internal to the toolkit and is
- * not exported from `runtime/engine.ts`. It only exists to make the
- * gate testable.
- */
-const defaultLogHandlerError = (error) => {
-    console.error("[pie-assessment-toolkit] onStageChange handler threw", error);
-};
-/**
- * Run the toolkit's stage emit pipeline with the suppression gate
- * applied.
- *
- *   - When `isSuppressed()` returns `true`, the helper returns
- *     immediately with neither side effect.
- *   - Otherwise it dispatches the `pie-stage-change` DOM event first,
- *     then invokes `onStageChange(detail)` (preserving the
- *     "DOM-event-then-callback" ordering pre-PR-6 consumers depend
- *     on).
- *   - A throwing `onStageChange` handler does not interrupt the DOM
- *     event (already fired) and does not propagate up to
- *     `stageTracker.enter` (latch state already advanced); the error
- *     is logged and swallowed, matching pre-PR-6 behavior.
- *
- * Returns `true` if the emit pipeline ran (i.e. it was not
- * suppressed); `false` if it was suppressed. Tests use the return
- * value to assert the gate's decision in isolation from the side
- * effects.
- */
-export function runStageEmitWithSuppression(context, detail) {
-    if (context.isSuppressed()) {
-        return false;
-    }
-    context.dispatchDomEvent(detail);
-    const handler = context.getOnStageChange();
-    if (handler) {
-        try {
-            handler(detail);
-        }
-        catch (error) {
-            (context.logHandlerError ?? defaultLogHandlerError)(error);
-        }
-    }
-    return true;
-}

package/dist/services/I18nService.d.ts

@@ -1,47 +0,0 @@
-/**
- * I18nService
- *
- * The toolkit's view of the shared i18n provider: a delegating wrapper over
- * `SimpleI18n` from `players-shared` that adds toolkit-scoped logging and wires
- * the lazy catalog loaders.
- *
- * It was once a near-verbatim second copy of that class — same fields, same
- * lookup, same plural selection. Duplicate implementations of one contract drift
- * silently, because nothing fails when only one of them is fixed. Keep this a
- * wrapper.
- *
- * Part of PIE Assessment Toolkit.
- */
-import type { I18nConfig, I18nProvider, I18nServiceApi, InterpolationValues, LocaleCode, MessageCatalog, MessageKeyInput, PluralOptions, TextDirection } from "@pie-players/pie-players-shared/i18n";
-export type { I18nConfig, I18nProvider, I18nServiceApi, InterpolationValues, LocaleCode, MessageCatalog, MessageKeyInput, PluralOptions, TextDirection, };
-/**
- * Toolkit-scoped i18n service.
- *
- * Serves every locale this repository ships, English resident and the rest
- * lazily loaded.
- */
-export declare class I18nService implements I18nServiceApi {
-    private readonly i18n;
-    constructor(config?: I18nConfig);
-    /**
-     * Set the locale, loading its catalog first.
-     *
-     * Never falls back to the browser locale: a rendered-string change reaches a
-     * host's live delivery on their next install with no build signal on their
-     * side, so the locale has to be something the host asked for.
-     */
-    initialize(config: I18nConfig): Promise<void>;
-    t(key: MessageKeyInput, values?: InterpolationValues): string;
-    plural(key: MessageKeyInput, options: PluralOptions): string;
-    getLocale(): string;
-    setLocale(locale: LocaleCode): Promise<void>;
-    getDirection(): TextDirection;
-    getAvailableLocales(): string[];
-    isLocaleLoaded(locale: LocaleCode): boolean;
-    subscribe(listener: () => void): () => void;
-    hasKey(key: MessageKeyInput): boolean;
-    addCustomMessages(locale: string, messages: MessageCatalog): void;
-    withLocale(locale: LocaleCode): I18nProvider;
-    formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
-    formatDate(date: Date, options?: Intl.DateTimeFormatOptions): string;
-}

package/dist/services/I18nService.js

@@ -1,84 +0,0 @@
-/**
- * I18nService
- *
- * The toolkit's view of the shared i18n provider: a delegating wrapper over
- * `SimpleI18n` from `players-shared` that adds toolkit-scoped logging and wires
- * the lazy catalog loaders.
- *
- * It was once a near-verbatim second copy of that class — same fields, same
- * lookup, same plural selection. Duplicate implementations of one contract drift
- * silently, because nothing fails when only one of them is fixed. Keep this a
- * wrapper.
- *
- * Part of PIE Assessment Toolkit.
- */
-import { createPieI18n } from "@pie-players/pie-players-shared/i18n";
-import { createLogger } from "../utils/logger.js";
-const log = createLogger("I18nService");
-/**
- * Toolkit-scoped i18n service.
- *
- * Serves every locale this repository ships, English resident and the rest
- * lazily loaded.
- */
-export class I18nService {
-    i18n;
-    constructor(config = {}) {
-        this.i18n = createPieI18n(config);
-        log("I18nService created", {
-            locale: this.i18n.getLocale(),
-            fallbackLocale: config.fallbackLocale ?? "en-US",
-        });
-    }
-    /**
-     * Set the locale, loading its catalog first.
-     *
-     * Never falls back to the browser locale: a rendered-string change reaches a
-     * host's live delivery on their next install with no build signal on their
-     * side, so the locale has to be something the host asked for.
-     */
-    async initialize(config) {
-        log(`Initializing with locale: ${config.locale ?? this.i18n.getLocale()}`);
-        await this.i18n.initialize(config);
-    }
-    t(key, values) {
-        return this.i18n.t(key, values);
-    }
-    plural(key, options) {
-        return this.i18n.plural(key, options);
-    }
-    getLocale() {
-        return this.i18n.getLocale();
-    }
-    async setLocale(locale) {
-        log(`Setting locale to: ${locale}`);
-        await this.i18n.setLocale(locale);
-    }
-    getDirection() {
-        return this.i18n.getDirection();
-    }
-    getAvailableLocales() {
-        return this.i18n.getAvailableLocales();
-    }
-    isLocaleLoaded(locale) {
-        return this.i18n.isLocaleLoaded(locale);
-    }
-    subscribe(listener) {
-        return this.i18n.subscribe(listener);
-    }
-    hasKey(key) {
-        return this.i18n.hasKey(key);
-    }
-    addCustomMessages(locale, messages) {
-        this.i18n.addCustomMessages(locale, messages);
-    }
-    withLocale(locale) {
-        return this.i18n.withLocale(locale);
-    }
-    formatNumber(value, options) {
-        return this.i18n.formatNumber?.(value, options) ?? String(value);
-    }
-    formatDate(date, options) {
-        return this.i18n.formatDate?.(date, options) ?? date.toISOString();
-    }
-}

package/dist/services/ThemeProvider.d.ts

@@ -1,95 +0,0 @@
-/**
- * ThemeProvider
- *
- * Applies consistent accessibility theming across items and tools.
- * Uses CSS custom properties and classes for framework-agnostic theming.
- *
- * Features:
- * - High contrast mode
- * - Font size scaling (small, normal, large, xlarge)
- * - Color customization (background, foreground, accent)
- * - Consistent theming across shadow DOM boundaries
- * - No framework dependencies
- *
- * Part of PIE Assessment Toolkit.
- */
-import type { ThemeProviderApi } from "./interfaces.js";
-/**
- * Font size options
- */
-export type FontSize = "small" | "normal" | "large" | "xlarge";
-/**
- * Theme configuration
- */
-export interface ThemeConfig {
-    highContrast?: boolean;
-    fontSize?: FontSize;
-    backgroundColor?: string;
-    foregroundColor?: string;
-    accentColor?: string;
-    linkColor?: string;
-    errorColor?: string;
-    successColor?: string;
-    warningColor?: string;
-}
-export declare class ThemeProvider implements ThemeProviderApi {
-    private currentTheme;
-    private styleElement;
-    private rootElement;
-    private styleContainer;
-    constructor(rootElement?: HTMLElement | null);
-    /**
-     * Initialize theme styles
-     */
-    private initializeStyles;
-    /**
-     * Apply theme configuration
-     *
-     * @param config Partial theme configuration (merged with current theme)
-     */
-    applyTheme(config: ThemeConfig): void;
-    /**
-     * Apply CSS custom properties to root element
-     */
-    private applyCSSVariables;
-    /**
-     * Apply CSS classes to root element
-     */
-    private applyCSSClasses;
-    /**
-     * Update global theme styles
-     */
-    private updateGlobalStyles;
-    /**
-     * Set high contrast mode
-     */
-    setHighContrast(enabled: boolean): void;
-    /**
-     * Set font size
-     */
-    setFontSize(size: FontSize): void;
-    /**
-     * Set color scheme
-     */
-    setColors(colors: {
-        backgroundColor?: string;
-        foregroundColor?: string;
-        accentColor?: string;
-    }): void;
-    /**
-     * Get current theme configuration
-     */
-    getCurrentTheme(): Required<ThemeConfig>;
-    /**
-     * Reset to default theme
-     */
-    reset(): void;
-    /**
-     * Adjust color opacity (helper)
-     */
-    private adjustOpacity;
-    /**
-     * Cleanup - remove theme styles
-     */
-    destroy(): void;
-}