@pie-players/pie-players-shared 0.3.74 → 1.0.0-beta.0

package/dist/ui/scope-css.js

@@ -4,37 +4,34 @@
  * external-style-urls="...">` or `itemConfig.resources.stylesheets[*].url`
  * styles that player's subtree instead of the whole host document.
  *
- * This replaces a single-regex implementation that prefixed every
- * selector-like fragment. That is correct for flat selector rules and wrong for
- * everything else: `@media screen { ... }` became
- * `.scope @media screen { ... }`, an invalid selector, so the browser dropped
- * the whole block and every rule inside it; `@font-face` and `@keyframes` were
- * corrupted the same way; and `:root` became `.scope :root`, which can never
- * match, because `:root` is `<html>` and is not a descendant of the player.
- * At-rules and `:root` custom properties therefore never applied at all.
+ * Walks the stylesheet brace-by-brace. Block at-rules that hold rules
+ * (`@media`, `@supports`, `@container`, `@layer`, `@scope`) keep their prelude
+ * and have their inner rules scoped, every other at-rule passes through, and a
+ * leading `:root`, `html` or `body` is replaced by the scope, since
+ * `.scope :root` can never match: `:root` is `<html>`, which is no descendant
+ * of the player. A regex prefixer fails on exactly these cases: it turned
+ * `@media screen { … }` into the invalid `.scope @media screen { … }`, which the
+ * browser drops with every rule inside, and corrupted `@font-face`,
+ * `@keyframes` and `:root` the same way.
  *
- * The QTI player's `scopeCssRules` (`pie-qti` -
- * `packages/item-player/src/components/utils/stylesheetRender.ts`) is not a
- * drop-in either. Its `:root` handling is the behaviour we want and is adopted
- * here, but it excludes `@` from its selector pattern rather than understanding
- * at-rules, so `@media` and `@supports` lose their condition and their inner
- * rules are hoisted and applied unconditionally — a mobile-only rule then
- * applies at every viewport width, which is a subtler failure than dropping it.
+ * The `:root` handling follows the QTI player's `scopeCssRules` (`pie-qti` -
+ * `packages/item-player/src/components/utils/stylesheetRender.ts`), which is no
+ * drop-in: it excludes `@` from its selector pattern without understanding
+ * at-rules, so `@media` and `@supports` lose their condition and their rules
+ * apply at every viewport width.
  *
- * So this walks the stylesheet brace-by-brace instead of pattern-matching it.
- * A real CSS parser would be the textbook answer and is deliberately not used:
- * `@pie-players/pie-item-player` ships with two workspace dependencies, this
- * runs in the delivery path, and scoping needs to know about rule boundaries
- * only — not about property grammar.
+ * No CSS parser: `@pie-players/pie-item-player` ships with two workspace
+ * dependencies, this runs in the delivery path, and scoping needs rule
+ * boundaries only.
  *
- * Known limits, all preserving existing behaviour rather than adding policy:
+ * Known limits:
  *
- * - `@import` is passed through untouched, exactly as the old regex left it. It
- *   pulls in an unscoped stylesheet, so it defeats scoping, but blocking it is
- *   a security policy decision and not this function's job. Callers gate
- *   stylesheet URLs with `validateExternalStyleUrl` before fetching.
+ * - `@import` is passed through untouched. It pulls in an unscoped stylesheet,
+ *   so it defeats scoping, but blocking it is a security policy decision and
+ *   not this function's job. Callers gate stylesheet URLs with
+ *   `validateExternalStyleUrl` before fetching.
  * - Declaration blocks are emitted verbatim, so `url(...)` references are left
- *   as authored and resolve against the stylesheet's own URL as before.
+ *   as authored and resolve against the stylesheet's own URL.
  * - A style rule's block is never rewritten, which is also what native CSS
  *   nesting needs: nested selectors are relative to a parent that has already
  *   been scoped.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "0.3.74",
+	"version": "1.0.0-beta.0",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -102,6 +102,7 @@
 		"dist"
 	],
 	"dependencies": {
+		"@pie-element/shared-utils": "0.1.3",
 		"@pie-lib/math-rendering-module": "6.0.0",
 		"dompurify": "^3.4.16",
 		"semver": "^7.8.5"
@@ -109,9 +110,9 @@
 	"scripts": {
 		"build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && node scripts/bundle-vendored-modules.mjs && mkdir -p dist/components && cp -R src/components/vendor dist/components/vendor",
 		"dev": "tsc -p tsconfig.json --watch",
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.tests.json",
 		"lint": "biome lint .",
-		"check": "tsc -p tsconfig.json --noEmit",
+		"check": "svelte-check --tsconfig ./tsconfig.svelte-check.json",
 		"test": "bun test",
 		"check-i18n": "bun run src/i18n/scripts/check-coverage.ts",
 		"scan-hardcoded": "bun run src/i18n/scripts/scan-hardcoded.ts"
@@ -119,13 +120,14 @@
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.15",
 		"@happy-dom/global-registrator": "^20.14.5",
-		"@pie-element/shared-math-rendering-mathjax": "0.1.2",
+		"@pie-element/shared-math-rendering-mathjax": "0.1.4",
 		"@playwright/test": "^1.63.0",
 		"@types/semver": "^7.8.0",
 		"es-module-shims": "^2.8.4",
 		"esbuild": "^0.28.2",
 		"glob": "^13.0.0",
 		"svelte": "^5.57.1",
+		"svelte-check": "^4.7.6",
 		"typescript": "^5.9.3"
 	},
 	"homepage": "https://github.com/pie-framework/pie-players/tree/master/packages/players-shared#readme",

package/dist/loaders/mathjax-version-conflict.d.ts

@@ -1,17 +0,0 @@
-/**
- * Forwards the MathJax version-conflict event to instrumentation.
- *
- * The MathJax 4 adapter that browser ESM elements render with dispatches
- * `pie-mathjax-version-conflict` on `window`, once per condition per page, when
- * MathJax 3 runs on the same page — an unsupported page, see
- * docs/item-player/loading-strategies.md#one-mathjax-version-per-page. The
- * event name is repeated here because players do not depend on the element
- * packages.
- */
-import type { InstrumentationProvider } from "../instrumentation/types.js";
-export declare const MATHJAX_VERSION_CONFLICT_EVENT = "pie-mathjax-version-conflict";
-/**
- * Tracks each `pie-mathjax-version-conflict` event on `target` with the
- * provider `getProvider` returns when it fires, once per provider.
- */
-export declare function forwardMathjaxVersionConflicts(target: EventTarget, getProvider: () => InstrumentationProvider | undefined): void;

package/dist/loaders/mathjax-version-conflict.js

@@ -1,51 +0,0 @@
-/**
- * Forwards the MathJax version-conflict event to instrumentation.
- *
- * The MathJax 4 adapter that browser ESM elements render with dispatches
- * `pie-mathjax-version-conflict` on `window`, once per condition per page, when
- * MathJax 3 runs on the same page — an unsupported page, see
- * docs/item-player/loading-strategies.md#one-mathjax-version-per-page. The
- * event name is repeated here because players do not depend on the element
- * packages.
- */
-export const MATHJAX_VERSION_CONFLICT_EVENT = "pie-mathjax-version-conflict";
-// Every ESM backend on a page listens, and each player bundle carries its own
-// copy of this module, so the providers that tracked an event are kept on the
-// page.
-const TRACKED = Symbol.for("@pie-players/pie-players-shared/mathjax-version-conflict-tracked");
-function providersThatTracked(event) {
-    const registry = globalThis;
-    registry[TRACKED] ??= new WeakMap();
-    let providers = registry[TRACKED].get(event);
-    if (!providers) {
-        providers = new WeakSet();
-        registry[TRACKED].set(event, providers);
-    }
-    return providers;
-}
-/**
- * Tracks each `pie-mathjax-version-conflict` event on `target` with the
- * provider `getProvider` returns when it fires, once per provider.
- */
-export function forwardMathjaxVersionConflicts(target, getProvider) {
-    target.addEventListener(MATHJAX_VERSION_CONFLICT_EVENT, (event) => {
-        const provider = getProvider();
-        if (!provider)
-            return;
-        const tracked = providersThatTracked(event);
-        if (tracked.has(provider))
-            return;
-        tracked.add(provider);
-        const detail = event.detail;
-        const { condition, docsUrl } = (detail && typeof detail === "object" ? detail : {});
-        try {
-            provider.trackEvent(MATHJAX_VERSION_CONFLICT_EVENT, {
-                condition,
-                docsUrl,
-            });
-        }
-        catch {
-            // Swallow: instrumentation must never break rendering.
-        }
-    });
-}

package/dist/pie/stage-tracker.d.ts

@@ -1,50 +0,0 @@
-import { type Stage, type StageChangeDetail, type StageSourceCe, type StageStatus } from "./stages.js";
-/**
- * Stage tracker primitive (M6).
- *
- * One tracker per CE instance per cohort. `enter(stage, status?)` is the
- * only mutation; `reset()` rolls the cohort over (e.g. when
- * `(sectionId, attemptId)` changes).
- *
- * The tracker enforces the locked invariants from
- * `m6_ready_vocab_canonical_followup.plan.md` §3.1–§3.6:
- * - Monotonic ordering across `STAGES`. Backward transitions inside one
- *   cohort are rejected (dev) / warned-once (prod) so subscribers never
- *   see a stage regress without an intervening `reset()`.
- * - Per-CE applicability. The post-retro canonical list applies to
- *   every CE shape; the `applicableStages` indirection is kept so a
- *   future shape-specific stage can opt out without rewriting callers.
- *   Non-applicable stages auto-emit `status: "skipped"` when an
- *   applicable later stage is entered, so iteration order stays stable
- *   across CE shapes.
- * - One source for every emit. The injected `emit(detail)` function
- *   drives DOM events, engine subscribers, and coordinator subscribers
- *   from the same call site so no surface drifts.
- *
- * Failure semantics intentionally piggyback on the M3 framework-error
- * contract: `enter(stage, "failed")` records the position; the
- * framework error records the cause.
- */
-export type CreateStageTrackerOptions = {
-    sourceCe: string;
-    sourceCeShape: StageSourceCe;
-    runtimeId: string;
-    sectionId?: string;
-    attemptId?: string;
-    emit: (detail: StageChangeDetail) => void;
-    now?: () => string;
-    onUnexpectedTransition?: (info: {
-        from: Stage | null;
-        to: Stage;
-        reason: "backward" | "duplicate";
-    }) => void;
-};
-export type StageTracker = {
-    enter: (stage: Stage, status?: StageStatus) => void;
-    reset: (next?: {
-        sectionId?: string;
-        attemptId?: string;
-    }) => void;
-    getCurrent: () => Stage | null;
-};
-export declare function createStageTracker(opts: CreateStageTrackerOptions): StageTracker;

package/dist/pie/stage-tracker.js

@@ -1,105 +0,0 @@
-import { STAGES, applicableStages, stageOrdinal, } from "./stages.js";
-let unexpectedTransitionWarned = false;
-function defaultUnexpectedTransitionLogger(info) {
-    if (unexpectedTransitionWarned)
-        return;
-    unexpectedTransitionWarned = true;
-    if (typeof console !== "undefined" && console.warn) {
-        console.warn(`[pie-stage-tracker] Unexpected ${info.reason} stage transition ` +
-            `from \`${info.from ?? "<none>"}\` to \`${info.to}\`. ` +
-            `Stage transitions are expected to be monotonic within a cohort; ` +
-            `call \`reset()\` when \`(sectionId, attemptId)\` changes.`);
-    }
-}
-export function createStageTracker(opts) {
-    const applicable = applicableStages(opts.sourceCeShape);
-    const applicableSet = new Set(applicable);
-    const now = opts.now ?? (() => new Date().toISOString());
-    const onUnexpected = opts.onUnexpectedTransition ?? defaultUnexpectedTransitionLogger;
-    let current = null;
-    let sectionId = opts.sectionId;
-    let attemptId = opts.attemptId;
-    const emitted = new Set();
-    function emitDetail(stage, status) {
-        opts.emit({
-            stage,
-            status,
-            runtimeId: opts.runtimeId,
-            sectionId,
-            attemptId,
-            timestamp: now(),
-            sourceCe: opts.sourceCe,
-        });
-    }
-    function fillSkippedBefore(stage) {
-        const targetIdx = stageOrdinal(stage);
-        const startIdx = current === null ? 0 : stageOrdinal(current) + 1;
-        for (let idx = startIdx; idx < targetIdx; idx += 1) {
-            const skipCandidate = STAGES[idx];
-            if (applicableSet.has(skipCandidate))
-                continue;
-            if (emitted.has(skipCandidate))
-                continue;
-            emitted.add(skipCandidate);
-            emitDetail(skipCandidate, "skipped");
-        }
-    }
-    function enter(stage, status = "entered") {
-        const nextOrdinal = stageOrdinal(stage);
-        const currentOrdinal = current === null ? -1 : stageOrdinal(current);
-        if (status === "entered") {
-            if (emitted.has(stage)) {
-                onUnexpected({ from: current, to: stage, reason: "duplicate" });
-                return;
-            }
-            if (nextOrdinal < currentOrdinal) {
-                onUnexpected({ from: current, to: stage, reason: "backward" });
-                return;
-            }
-            if (!applicableSet.has(stage)) {
-                // A non-applicable stage entered with `entered` is a programming
-                // error: the tracker auto-skips it when a later stage enters.
-                // Treat it as a `skipped` emission and continue.
-                if (emitted.has(stage))
-                    return;
-                emitted.add(stage);
-                emitDetail(stage, "skipped");
-                return;
-            }
-            fillSkippedBefore(stage);
-            emitted.add(stage);
-            current = stage;
-            emitDetail(stage, "entered");
-            return;
-        }
-        // `status === "failed"` records position; do not gate on monotonic
-        // ordering — failure can happen during any transition. Mark the stage
-        // as emitted so a subsequent `entered` for the same stage warns as a
-        // duplicate; downstream recovery should call `reset()` first.
-        if (status === "failed") {
-            fillSkippedBefore(stage);
-            emitted.add(stage);
-            current = stage;
-            emitDetail(stage, "failed");
-            return;
-        }
-        // `status === "skipped"` is reserved for the auto-fill path; explicit
-        // callers shouldn't pass it. Accept it idempotently for robustness.
-        if (emitted.has(stage))
-            return;
-        emitted.add(stage);
-        emitDetail(stage, "skipped");
-    }
-    function reset(next) {
-        current = null;
-        emitted.clear();
-        if (next) {
-            sectionId = next.sectionId;
-            attemptId = next.attemptId;
-        }
-    }
-    function getCurrent() {
-        return current;
-    }
-    return { enter, reset, getCurrent };
-}