@pie-players/pie-players-shared 0.3.60 → 0.3.61

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from "./object/index.js";
 export * from "./pie/index.js";
 export type { AssessmentEntity, AssessmentItemRef, AssessmentSection, AdvancedItemConfig, ConfigEntity, ConfigResource, Env, ItemConfig, ItemEntity, ItemSession, OutcomeResponse, PassageEntity, PieController, PieContent, PieDefaultModel, PieItemElement, PieModel, QuestionEntity, RubricBlock, TestPart, } from "./types/index.js";
 export { editorPostFix } from "./types/index.js";
+export * from "./ui/content-styles.js";
 export * from "./ui/focus-trap.js";
 export * from "./ui/first-focusable.js";
 export * from "./ui/debug-panel-persistence.js";

package/dist/index.js

@@ -8,6 +8,7 @@ export * from "./object/index.js";
 // Barrel export for PIE runtime utilities
 export * from "./pie/index.js";
 export { editorPostFix } from "./types/index.js";
+export * from "./ui/content-styles.js";
 export * from "./ui/focus-trap.js";
 export * from "./ui/first-focusable.js";
 export * from "./ui/debug-panel-persistence.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,0CAA0C;AAC1C,cAAc,gBAAgB,CAAC;AAuB/B,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,sBAAsB,CAAC","sourcesContent":["export * from \"./config/profile.js\";\nexport * from \"./instrumentation/index.js\";\nexport * from \"./loader-config.js\";\nexport * from \"./player-strategy.js\";\nexport * from \"./security/index.js\";\nexport * from \"./loaders/index.js\";\nexport * from \"./object/index.js\";\n// Barrel export for PIE runtime utilities\nexport * from \"./pie/index.js\";\nexport type {\n\tAssessmentEntity,\n\tAssessmentItemRef,\n\tAssessmentSection,\n\tAdvancedItemConfig,\n\tConfigEntity,\n\tConfigResource,\n\tEnv,\n\tItemConfig,\n\tItemEntity,\n\tItemSession,\n\tOutcomeResponse,\n\tPassageEntity,\n\tPieController,\n\tPieContent,\n\tPieDefaultModel,\n\tPieItemElement,\n\tPieModel,\n\tQuestionEntity,\n\tRubricBlock,\n\tTestPart,\n} from \"./types/index.js\";\nexport { editorPostFix } from \"./types/index.js\";\nexport * from \"./ui/focus-trap.js\";\nexport * from \"./ui/first-focusable.js\";\nexport * from \"./ui/debug-panel-persistence.js\";\nexport * from \"./ui/safe-storage.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,0CAA0C;AAC1C,cAAc,gBAAgB,CAAC;AAuB/B,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,sBAAsB,CAAC","sourcesContent":["export * from \"./config/profile.js\";\nexport * from \"./instrumentation/index.js\";\nexport * from \"./loader-config.js\";\nexport * from \"./player-strategy.js\";\nexport * from \"./security/index.js\";\nexport * from \"./loaders/index.js\";\nexport * from \"./object/index.js\";\n// Barrel export for PIE runtime utilities\nexport * from \"./pie/index.js\";\nexport type {\n\tAssessmentEntity,\n\tAssessmentItemRef,\n\tAssessmentSection,\n\tAdvancedItemConfig,\n\tConfigEntity,\n\tConfigResource,\n\tEnv,\n\tItemConfig,\n\tItemEntity,\n\tItemSession,\n\tOutcomeResponse,\n\tPassageEntity,\n\tPieController,\n\tPieContent,\n\tPieDefaultModel,\n\tPieItemElement,\n\tPieModel,\n\tQuestionEntity,\n\tRubricBlock,\n\tTestPart,\n} from \"./types/index.js\";\nexport { editorPostFix } from \"./types/index.js\";\nexport * from \"./ui/content-styles.js\";\nexport * from \"./ui/focus-trap.js\";\nexport * from \"./ui/first-focusable.js\";\nexport * from \"./ui/debug-panel-persistence.js\";\nexport * from \"./ui/safe-storage.js\";\n"]}

package/dist/ui/content-styles.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Installs the shared PIE content stylesheet
+ * (`@pie-players/pie-theme/components.css`) into the host document.
+ *
+ * Authored assessment content depends on classes that belong to no single
+ * component: passage markup (`.numbered-paragraph`, `.p-number`,
+ * `div.passage-title`), the legacy `kds-*` families, the `@media print`
+ * `.noprint` rules, and the answer-eliminator classes. Players render into
+ * light DOM, so those rules have to exist as a document-level stylesheet —
+ * there is no shadow root to scope them to.
+ *
+ * Hosts used to be required to import that stylesheet themselves. Nothing
+ * enforced it and nothing failed loudly when they didn't: the item rendered,
+ * the passage was simply unstyled, and it surfaced as a visual bug reported by
+ * hand days later. Players install the stylesheet themselves instead, which
+ * keeps the host contract at "import the player".
+ *
+ * The CSS text is passed in rather than imported here: this package builds with
+ * plain `tsc`, so it cannot inline a stylesheet. Bundler-built player packages
+ * import it with Vite's `?inline` and hand the text over.
+ */
+export type ContentStylesResult = "installed" | "already-installed" | "opted-out" | "no-document";
+/**
+ * True when the host declared `<html data-pie-content-styles="host">`, i.e. it
+ * takes ownership of loading the stylesheet.
+ */
+export declare function contentStylesOptedOut(): boolean;
+/**
+ * True when `components.css` is applied to the document, by any route. Reads the
+ * sentinel custom property the stylesheet declares on `:root`.
+ *
+ * Only meaningful once the document's stylesheets have been applied — a host
+ * that loads CSS via an async `<link>` reads as missing until it lands.
+ */
+export declare function contentStylesPresent(): boolean;
+/**
+ * Installs `cssText` as a document-level stylesheet, once per document.
+ *
+ * The stylesheet is **prepended** to `<head>` and deliberately left out of a
+ * cascade layer. Prepending reproduces the placement hosts were told to use by
+ * hand — first in the entry, before app CSS — so an app rule and a content rule
+ * of equal specificity resolve in the host's favour, exactly as before.
+ *
+ * A cascade layer looks tempting here and is the wrong tool: unlayered author
+ * declarations beat *all* layered ones regardless of specificity, so a host
+ * reset as broad as `p { margin: 0 }` would silently outrank
+ * `.numbered-paragraph { margin-left: 36px }`. That trades a visible missing
+ * stylesheet for a subtler override bug, so ordinary specificity wins instead.
+ *
+ * @param cssText Contents of `@pie-players/pie-theme/components.css`.
+ * @param source Package installing the styles, for diagnostics.
+ */
+export declare function installContentStyles(cssText: string, source: string): ContentStylesResult;
+/**
+ * Reports, once per page, the two ways content styling can go wrong. Neither is
+ * detectable synchronously — a host copy may still be in flight as an async
+ * `<link>` — so the check is deferred.
+ *
+ * - **Missing**: the host opted out and then loaded nothing, so authored content
+ *   renders unstyled. This is the failure the old host-import contract produced
+ *   silently.
+ * - **Duplicated**: the host still imports `components.css` itself *and* the
+ *   player installed a copy. Rendering is correct while the two agree, but the
+ *   host's copy loads later and therefore wins ties at equal specificity — so a
+ *   host copy pinned to an older `@pie-players/pie-theme` silently overrides the
+ *   player's newer rules. Harmless today, a confusing override tomorrow.
+ */
+export declare function auditContentStyles(source: string): void;
+/**
+ * Test-only: clears the once-per-page warning latch and cancels any pending
+ * deferred check, so a timer scheduled by one test cannot warn during the next.
+ */
+export declare function resetContentStylesWarningForTesting(): void;

package/dist/ui/content-styles.js

@@ -0,0 +1,205 @@
+/**
+ * Installs the shared PIE content stylesheet
+ * (`@pie-players/pie-theme/components.css`) into the host document.
+ *
+ * Authored assessment content depends on classes that belong to no single
+ * component: passage markup (`.numbered-paragraph`, `.p-number`,
+ * `div.passage-title`), the legacy `kds-*` families, the `@media print`
+ * `.noprint` rules, and the answer-eliminator classes. Players render into
+ * light DOM, so those rules have to exist as a document-level stylesheet —
+ * there is no shadow root to scope them to.
+ *
+ * Hosts used to be required to import that stylesheet themselves. Nothing
+ * enforced it and nothing failed loudly when they didn't: the item rendered,
+ * the passage was simply unstyled, and it surfaced as a visual bug reported by
+ * hand days later. Players install the stylesheet themselves instead, which
+ * keeps the host contract at "import the player".
+ *
+ * The CSS text is passed in rather than imported here: this package builds with
+ * plain `tsc`, so it cannot inline a stylesheet. Bundler-built player packages
+ * import it with Vite's `?inline` and hand the text over.
+ */
+/** Marks a `<style>` element this module owns, and keeps installs idempotent. */
+const MARKER_ATTRIBUTE = "data-pie-content-styles";
+/**
+ * Declared by `components.css` itself, so it is observable no matter how the
+ * stylesheet arrived — our injection or a host import. Used only to tell a host
+ * that opted out but then shipped nothing.
+ */
+const SENTINEL_PROPERTY = "--pie-content-styles";
+/** `<html data-pie-content-styles="host">` opts a host out of installation. */
+const OPT_OUT_ATTRIBUTE = "data-pie-content-styles";
+const OPT_OUT_VALUE = "host";
+const isBrowser = () => typeof document !== "undefined" && !!document.head;
+/**
+ * True when the host declared `<html data-pie-content-styles="host">`, i.e. it
+ * takes ownership of loading the stylesheet.
+ */
+export function contentStylesOptedOut() {
+    if (!isBrowser())
+        return false;
+    return (document.documentElement.getAttribute(OPT_OUT_ATTRIBUTE) === OPT_OUT_VALUE);
+}
+/**
+ * True when `components.css` is applied to the document, by any route. Reads the
+ * sentinel custom property the stylesheet declares on `:root`.
+ *
+ * Only meaningful once the document's stylesheets have been applied — a host
+ * that loads CSS via an async `<link>` reads as missing until it lands.
+ */
+export function contentStylesPresent() {
+    if (!isBrowser())
+        return false;
+    const value = getComputedStyle(document.documentElement)
+        .getPropertyValue(SENTINEL_PROPERTY)
+        .trim();
+    return value !== "";
+}
+/**
+ * Installs `cssText` as a document-level stylesheet, once per document.
+ *
+ * The stylesheet is **prepended** to `<head>` and deliberately left out of a
+ * cascade layer. Prepending reproduces the placement hosts were told to use by
+ * hand — first in the entry, before app CSS — so an app rule and a content rule
+ * of equal specificity resolve in the host's favour, exactly as before.
+ *
+ * A cascade layer looks tempting here and is the wrong tool: unlayered author
+ * declarations beat *all* layered ones regardless of specificity, so a host
+ * reset as broad as `p { margin: 0 }` would silently outrank
+ * `.numbered-paragraph { margin-left: 36px }`. That trades a visible missing
+ * stylesheet for a subtler override bug, so ordinary specificity wins instead.
+ *
+ * @param cssText Contents of `@pie-players/pie-theme/components.css`.
+ * @param source Package installing the styles, for diagnostics.
+ */
+export function installContentStyles(cssText, source) {
+    if (!isBrowser())
+        return "no-document";
+    if (contentStylesOptedOut())
+        return "opted-out";
+    if (document.querySelector(`style[${MARKER_ATTRIBUTE}]`)) {
+        // Another player package, or a second copy of this one, already installed
+        // the same stylesheet. Duplicating it would be harmless but pointless.
+        return "already-installed";
+    }
+    if (!cssText)
+        return "no-document";
+    const style = document.createElement("style");
+    style.setAttribute(MARKER_ATTRIBUTE, source);
+    style.textContent = cssText;
+    document.head.prepend(style);
+    return "installed";
+}
+/**
+ * Counts content stylesheets in the document that this module did not install —
+ * i.e. copies the host loaded itself. Detected by the sentinel property rather
+ * than by URL, so a copy arriving as a `<link>`, a bundler-injected `<style>`, or
+ * anything else all count the same.
+ *
+ * Cross-origin sheets throw on `cssRules` access and are skipped; a host copy
+ * served from another origin therefore reads as absent. That only costs a
+ * diagnostic, never correctness.
+ */
+const countHostContentStyleSheets = () => {
+    // Walks the owning elements rather than document.styleSheets: the marker
+    // attribute lives on the element, and CSSStyleSheet.ownerNode is not
+    // universally implemented (happy-dom omits it), which would make our own
+    // installed copy look like a host copy.
+    const nodes = document.querySelectorAll(`style:not([${MARKER_ATTRIBUTE}]), link[rel~="stylesheet"]:not([${MARKER_ATTRIBUTE}])`);
+    let count = 0;
+    for (const node of Array.from(nodes)) {
+        let rules;
+        try {
+            rules = node.sheet?.cssRules;
+        }
+        catch {
+            continue;
+        }
+        if (!rules)
+            continue;
+        for (const rule of Array.from(rules)) {
+            if (rule.style?.getPropertyValue(SENTINEL_PROPERTY)) {
+                count += 1;
+                break;
+            }
+        }
+    }
+    return count;
+};
+let auditWarningIssued = false;
+const pendingChecks = [];
+/**
+ * Reports, once per page, the two ways content styling can go wrong. Neither is
+ * detectable synchronously — a host copy may still be in flight as an async
+ * `<link>` — so the check is deferred.
+ *
+ * - **Missing**: the host opted out and then loaded nothing, so authored content
+ *   renders unstyled. This is the failure the old host-import contract produced
+ *   silently.
+ * - **Duplicated**: the host still imports `components.css` itself *and* the
+ *   player installed a copy. Rendering is correct while the two agree, but the
+ *   host's copy loads later and therefore wins ties at equal specificity — so a
+ *   host copy pinned to an older `@pie-players/pie-theme` silently overrides the
+ *   player's newer rules. Harmless today, a confusing override tomorrow.
+ */
+export function auditContentStyles(source) {
+    if (!isBrowser() || auditWarningIssued)
+        return;
+    const check = () => {
+        if (auditWarningIssued)
+            return;
+        if (contentStylesOptedOut()) {
+            if (contentStylesPresent())
+                return;
+            auditWarningIssued = true;
+            console.warn(`[${source}] No PIE content stylesheet found. This document sets ` +
+                `${OPT_OUT_ATTRIBUTE}="${OPT_OUT_VALUE}", so ${source} did not install ` +
+                `one. Authored content that relies on shared classes ` +
+                `(.numbered-paragraph, .p-number, div.passage-title, the kds-* ` +
+                `families, answer-eliminator styles) will render unstyled. Either ` +
+                `import "@pie-players/pie-theme/components.css" in the host app, or ` +
+                `drop the ${OPT_OUT_ATTRIBUTE} attribute to let the player install it.`);
+            return;
+        }
+        if (countHostContentStyleSheets() > 0) {
+            auditWarningIssued = true;
+            console.warn(`[${source}] The PIE content stylesheet is loaded twice: ${source} ` +
+                `installs it, and this host also imports ` +
+                `"@pie-players/pie-theme/components.css". Rendering is unaffected ` +
+                `while both copies match, but the host copy loads later and wins ` +
+                `ties at equal specificity, so a copy pinned to an older ` +
+                `@pie-players/pie-theme will silently override newer player styles. ` +
+                `Remove the host import, or set ` +
+                `${OPT_OUT_ATTRIBUTE}="${OPT_OUT_VALUE}" on <html> to own the ` +
+                `stylesheet deliberately.`);
+        }
+    };
+    // A host stylesheet can land well after the module graph evaluates, and a
+    // bundler-injected <link> is not necessarily parsed by the time `load` fires.
+    // This is advisory output, so it is checked at a few widening points rather
+    // than raced: whichever one first sees a settled document wins, and the latch
+    // keeps the rest quiet. Missing the window costs a diagnostic, not
+    // correctness.
+    if (typeof requestAnimationFrame !== "function") {
+        check();
+        return;
+    }
+    requestAnimationFrame(() => requestAnimationFrame(check));
+    if (typeof window !== "undefined" && document.readyState !== "complete") {
+        window.addEventListener("load", () => check(), { once: true });
+    }
+    if (typeof setTimeout === "function") {
+        pendingChecks.push(setTimeout(check, 1000));
+    }
+}
+/**
+ * Test-only: clears the once-per-page warning latch and cancels any pending
+ * deferred check, so a timer scheduled by one test cannot warn during the next.
+ */
+export function resetContentStylesWarningForTesting() {
+    auditWarningIssued = false;
+    for (const handle of pendingChecks)
+        clearTimeout(handle);
+    pendingChecks.length = 0;
+}
+//# sourceMappingURL=content-styles.js.map

package/dist/ui/content-styles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-styles.js","sourceRoot":"","sources":["../../src/ui/content-styles.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Installs the shared PIE content stylesheet\n * (`@pie-players/pie-theme/components.css`) into the host document.\n *\n * Authored assessment content depends on classes that belong to no single\n * component: passage markup (`.numbered-paragraph`, `.p-number`,\n * `div.passage-title`), the legacy `kds-*` families, the `@media print`\n * `.noprint` rules, and the answer-eliminator classes. Players render into\n * light DOM, so those rules have to exist as a document-level stylesheet —\n * there is no shadow root to scope them to.\n *\n * Hosts used to be required to import that stylesheet themselves. Nothing\n * enforced it and nothing failed loudly when they didn't: the item rendered,\n * the passage was simply unstyled, and it surfaced as a visual bug reported by\n * hand days later. Players install the stylesheet themselves instead, which\n * keeps the host contract at \"import the player\".\n *\n * The CSS text is passed in rather than imported here: this package builds with\n * plain `tsc`, so it cannot inline a stylesheet. Bundler-built player packages\n * import it with Vite's `?inline` and hand the text over.\n */\n\n/** Marks a `<style>` element this module owns, and keeps installs idempotent. */\nconst MARKER_ATTRIBUTE = \"data-pie-content-styles\";\n\n/**\n * Declared by `components.css` itself, so it is observable no matter how the\n * stylesheet arrived — our injection or a host import. Used only to tell a host\n * that opted out but then shipped nothing.\n */\nconst SENTINEL_PROPERTY = \"--pie-content-styles\";\n\n/** `<html data-pie-content-styles=\"host\">` opts a host out of installation. */\nconst OPT_OUT_ATTRIBUTE = \"data-pie-content-styles\";\nconst OPT_OUT_VALUE = \"host\";\n\nexport type ContentStylesResult =\n\t| \"installed\"\n\t| \"already-installed\"\n\t| \"opted-out\"\n\t| \"no-document\";\n\nconst isBrowser = (): boolean =>\n\ttypeof document !== \"undefined\" && !!document.head;\n\n/**\n * True when the host declared `<html data-pie-content-styles=\"host\">`, i.e. it\n * takes ownership of loading the stylesheet.\n */\nexport function contentStylesOptedOut(): boolean {\n\tif (!isBrowser()) return false;\n\treturn (\n\t\tdocument.documentElement.getAttribute(OPT_OUT_ATTRIBUTE) === OPT_OUT_VALUE\n\t);\n}\n\n/**\n * True when `components.css` is applied to the document, by any route. Reads the\n * sentinel custom property the stylesheet declares on `:root`.\n *\n * Only meaningful once the document's stylesheets have been applied — a host\n * that loads CSS via an async `<link>` reads as missing until it lands.\n */\nexport function contentStylesPresent(): boolean {\n\tif (!isBrowser()) return false;\n\tconst value = getComputedStyle(document.documentElement)\n\t\t.getPropertyValue(SENTINEL_PROPERTY)\n\t\t.trim();\n\treturn value !== \"\";\n}\n\n/**\n * Installs `cssText` as a document-level stylesheet, once per document.\n *\n * The stylesheet is **prepended** to `<head>` and deliberately left out of a\n * cascade layer. Prepending reproduces the placement hosts were told to use by\n * hand — first in the entry, before app CSS — so an app rule and a content rule\n * of equal specificity resolve in the host's favour, exactly as before.\n *\n * A cascade layer looks tempting here and is the wrong tool: unlayered author\n * declarations beat *all* layered ones regardless of specificity, so a host\n * reset as broad as `p { margin: 0 }` would silently outrank\n * `.numbered-paragraph { margin-left: 36px }`. That trades a visible missing\n * stylesheet for a subtler override bug, so ordinary specificity wins instead.\n *\n * @param cssText Contents of `@pie-players/pie-theme/components.css`.\n * @param source Package installing the styles, for diagnostics.\n */\nexport function installContentStyles(\n\tcssText: string,\n\tsource: string,\n): ContentStylesResult {\n\tif (!isBrowser()) return \"no-document\";\n\tif (contentStylesOptedOut()) return \"opted-out\";\n\tif (document.querySelector(`style[${MARKER_ATTRIBUTE}]`)) {\n\t\t// Another player package, or a second copy of this one, already installed\n\t\t// the same stylesheet. Duplicating it would be harmless but pointless.\n\t\treturn \"already-installed\";\n\t}\n\tif (!cssText) return \"no-document\";\n\n\tconst style = document.createElement(\"style\");\n\tstyle.setAttribute(MARKER_ATTRIBUTE, source);\n\tstyle.textContent = cssText;\n\tdocument.head.prepend(style);\n\treturn \"installed\";\n}\n\n/**\n * Counts content stylesheets in the document that this module did not install —\n * i.e. copies the host loaded itself. Detected by the sentinel property rather\n * than by URL, so a copy arriving as a `<link>`, a bundler-injected `<style>`, or\n * anything else all count the same.\n *\n * Cross-origin sheets throw on `cssRules` access and are skipped; a host copy\n * served from another origin therefore reads as absent. That only costs a\n * diagnostic, never correctness.\n */\nconst countHostContentStyleSheets = (): number => {\n\t// Walks the owning elements rather than document.styleSheets: the marker\n\t// attribute lives on the element, and CSSStyleSheet.ownerNode is not\n\t// universally implemented (happy-dom omits it), which would make our own\n\t// installed copy look like a host copy.\n\tconst nodes = document.querySelectorAll<HTMLStyleElement | HTMLLinkElement>(\n\t\t`style:not([${MARKER_ATTRIBUTE}]), link[rel~=\"stylesheet\"]:not([${MARKER_ATTRIBUTE}])`,\n\t);\n\tlet count = 0;\n\tfor (const node of Array.from(nodes)) {\n\t\tlet rules: CSSRuleList | undefined;\n\t\ttry {\n\t\t\trules = node.sheet?.cssRules;\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tif (!rules) continue;\n\t\tfor (const rule of Array.from(rules)) {\n\t\t\tif ((rule as CSSStyleRule).style?.getPropertyValue(SENTINEL_PROPERTY)) {\n\t\t\t\tcount += 1;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\treturn count;\n};\n\nlet auditWarningIssued = false;\nconst pendingChecks: ReturnType<typeof setTimeout>[] = [];\n\n/**\n * Reports, once per page, the two ways content styling can go wrong. Neither is\n * detectable synchronously — a host copy may still be in flight as an async\n * `<link>` — so the check is deferred.\n *\n * - **Missing**: the host opted out and then loaded nothing, so authored content\n *   renders unstyled. This is the failure the old host-import contract produced\n *   silently.\n * - **Duplicated**: the host still imports `components.css` itself *and* the\n *   player installed a copy. Rendering is correct while the two agree, but the\n *   host's copy loads later and therefore wins ties at equal specificity — so a\n *   host copy pinned to an older `@pie-players/pie-theme` silently overrides the\n *   player's newer rules. Harmless today, a confusing override tomorrow.\n */\nexport function auditContentStyles(source: string): void {\n\tif (!isBrowser() || auditWarningIssued) return;\n\n\tconst check = () => {\n\t\tif (auditWarningIssued) return;\n\n\t\tif (contentStylesOptedOut()) {\n\t\t\tif (contentStylesPresent()) return;\n\t\t\tauditWarningIssued = true;\n\t\t\tconsole.warn(\n\t\t\t\t`[${source}] No PIE content stylesheet found. This document sets ` +\n\t\t\t\t\t`${OPT_OUT_ATTRIBUTE}=\"${OPT_OUT_VALUE}\", so ${source} did not install ` +\n\t\t\t\t\t`one. Authored content that relies on shared classes ` +\n\t\t\t\t\t`(.numbered-paragraph, .p-number, div.passage-title, the kds-* ` +\n\t\t\t\t\t`families, answer-eliminator styles) will render unstyled. Either ` +\n\t\t\t\t\t`import \"@pie-players/pie-theme/components.css\" in the host app, or ` +\n\t\t\t\t\t`drop the ${OPT_OUT_ATTRIBUTE} attribute to let the player install it.`,\n\t\t\t);\n\t\t\treturn;\n\t\t}\n\n\t\tif (countHostContentStyleSheets() > 0) {\n\t\t\tauditWarningIssued = true;\n\t\t\tconsole.warn(\n\t\t\t\t`[${source}] The PIE content stylesheet is loaded twice: ${source} ` +\n\t\t\t\t\t`installs it, and this host also imports ` +\n\t\t\t\t\t`\"@pie-players/pie-theme/components.css\". Rendering is unaffected ` +\n\t\t\t\t\t`while both copies match, but the host copy loads later and wins ` +\n\t\t\t\t\t`ties at equal specificity, so a copy pinned to an older ` +\n\t\t\t\t\t`@pie-players/pie-theme will silently override newer player styles. ` +\n\t\t\t\t\t`Remove the host import, or set ` +\n\t\t\t\t\t`${OPT_OUT_ATTRIBUTE}=\"${OPT_OUT_VALUE}\" on <html> to own the ` +\n\t\t\t\t\t`stylesheet deliberately.`,\n\t\t\t);\n\t\t}\n\t};\n\n\t// A host stylesheet can land well after the module graph evaluates, and a\n\t// bundler-injected <link> is not necessarily parsed by the time `load` fires.\n\t// This is advisory output, so it is checked at a few widening points rather\n\t// than raced: whichever one first sees a settled document wins, and the latch\n\t// keeps the rest quiet. Missing the window costs a diagnostic, not\n\t// correctness.\n\tif (typeof requestAnimationFrame !== \"function\") {\n\t\tcheck();\n\t\treturn;\n\t}\n\trequestAnimationFrame(() => requestAnimationFrame(check));\n\tif (typeof window !== \"undefined\" && document.readyState !== \"complete\") {\n\t\twindow.addEventListener(\"load\", () => check(), { once: true });\n\t}\n\tif (typeof setTimeout === \"function\") {\n\t\tpendingChecks.push(setTimeout(check, 1000));\n\t}\n}\n\n/**\n * Test-only: clears the once-per-page warning latch and cancels any pending\n * deferred check, so a timer scheduled by one test cannot warn during the next.\n */\nexport function resetContentStylesWarningForTesting(): void {\n\tauditWarningIssued = false;\n\tfor (const handle of pendingChecks) clearTimeout(handle);\n\tpendingChecks.length = 0;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "0.3.60",
+	"version": "0.3.61",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -64,6 +64,10 @@
 		"./ui/zoom-compensation": {
 			"types": "./dist/ui/zoom-compensation.d.ts",
 			"import": "./dist/ui/zoom-compensation.js"
+		},
+		"./ui/content-styles": {
+			"types": "./dist/ui/content-styles.d.ts",
+			"import": "./dist/ui/content-styles.js"
 		}
 	},
 	"files": [
@@ -72,7 +76,7 @@
 	"dependencies": {
 		"@pie-lib/math-rendering-module": "5.1.0",
 		"dompurify": "^3.4.0",
-		"semver": "^7.7.4"
+		"semver": "^7.8.5"
 	},
 	"scripts": {
 		"build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && mkdir -p dist/components && cp -R src/components/vendor dist/components/vendor",