npm - @pie-players/pie-players-shared - Versions diffs - 0.3.67 → 0.3.69 - Mend

@pie-players/pie-players-shared 0.3.67 → 0.3.69

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (87) hide show

package/README.md +59 -0
package/dist/formative/index.d.ts +16 -0
package/dist/formative/index.js +5 -0
package/dist/formative/mastery.d.ts +16 -0
package/dist/formative/mastery.js +43 -0
package/dist/formative/outcome.d.ts +19 -0
package/dist/formative/outcome.js +90 -0
package/dist/formative/policy.d.ts +37 -0
package/dist/formative/policy.js +86 -0
package/dist/formative/session.d.ts +19 -0
package/dist/formative/session.js +113 -0
package/dist/formative/state.d.ts +60 -0
package/dist/formative/state.js +140 -0
package/dist/formative/types.d.ts +164 -0
package/dist/formative/types.js +13 -0
package/dist/i18n/catalogs.d.ts +38 -0
package/dist/i18n/catalogs.js +47 -0
package/dist/i18n/index.d.ts +28 -4
package/dist/i18n/index.js +34 -3
package/dist/i18n/language-tags.d.ts +51 -0
package/dist/i18n/language-tags.js +84 -0
package/dist/i18n/messages/en-US.d.ts +601 -0
package/dist/i18n/messages/en-US.js +617 -0
package/dist/i18n/messages/nl-NL.d.ts +516 -0
package/dist/i18n/messages/nl-NL.js +516 -0
package/dist/i18n/provider.d.ts +168 -0
package/dist/i18n/provider.js +472 -0
package/dist/i18n/types.d.ts +177 -28
package/dist/i18n/types.js +6 -2
package/dist/index.d.ts +3 -1
package/dist/index.js +2 -0
package/dist/pie/custom-element-define.d.ts +24 -0
package/dist/pie/custom-element-define.js +36 -6
package/dist/pie/index.d.ts +1 -1
package/dist/pie/index.js +1 -1
package/dist/pie/versioned-tag.js +3 -2
package/dist/security/sanitize-forbidden-lists.d.ts +8 -0
package/dist/security/sanitize-forbidden-lists.js +41 -0
package/dist/security/sanitize-item-markup.js +3 -36
package/dist/security/sanitize-svg-icon.js +3 -25
package/dist/security/wrap-overwide-images.d.ts +5 -10
package/dist/security/wrap-overwide-images.js +13 -62
package/dist/security/wrap-overwide-tables.d.ts +5 -10
package/dist/security/wrap-overwide-tables.js +13 -62
package/dist/security/wrap-overwide.d.ts +51 -0
package/dist/security/wrap-overwide.js +91 -0
package/dist/server/npm-auth-env.d.ts +13 -0
package/dist/server/npm-auth-env.js +64 -0
package/dist/timed-media/index.d.ts +17 -0
package/dist/timed-media/index.js +16 -0
package/dist/timed-media/media-element-source.d.ts +36 -0
package/dist/timed-media/media-element-source.js +121 -0
package/dist/timed-media/policy.d.ts +36 -0
package/dist/timed-media/policy.js +297 -0
package/dist/timed-media/session.d.ts +21 -0
package/dist/timed-media/session.js +85 -0
package/dist/timed-media/state.d.ts +66 -0
package/dist/timed-media/state.js +357 -0
package/dist/timed-media/types.d.ts +343 -0
package/dist/timed-media/types.js +12 -0
package/dist/tools/term-lookup.d.ts +189 -0
package/dist/tools/term-lookup.js +284 -0
package/dist/types/index.d.ts +105 -1
package/dist/ui/attribute-coercion.d.ts +1 -0
package/dist/ui/attribute-coercion.js +19 -0
package/dist/ui/first-focusable.d.ts +22 -0
package/dist/ui/first-focusable.js +47 -0
package/dist/ui/focus-trap.js +7 -2
package/dist/ui/pointer-drag.d.ts +30 -0
package/dist/ui/pointer-drag.js +34 -0
package/package.json +38 -6
package/dist/i18n/loader.d.ts +0 -35
package/dist/i18n/loader.js +0 -132
package/dist/i18n/simple-i18n.d.ts +0 -68
package/dist/i18n/simple-i18n.js +0 -198
package/dist/i18n/translations/ar/common.json +0 -36
package/dist/i18n/translations/ar/toolkit.json +0 -48
package/dist/i18n/translations/ar/tools.json +0 -103
package/dist/i18n/translations/en/common.json +0 -36
package/dist/i18n/translations/en/toolkit.json +0 -48
package/dist/i18n/translations/en/tools.json +0 -103
package/dist/i18n/translations/es/common.json +0 -36
package/dist/i18n/translations/es/toolkit.json +0 -48
package/dist/i18n/translations/es/tools.json +0 -103
package/dist/i18n/translations/zh/common.json +0 -36
package/dist/i18n/translations/zh/toolkit.json +0 -48
package/dist/i18n/translations/zh/tools.json +0 -103

package/dist/security/wrap-overwide-images.js CHANGED Viewed

@@ -22,59 +22,30 @@
  *   PIE element paints into its own light DOM (e.g. a `pie-passage`'s
  *   model-driven content) get the same scrollable affordance even though
  *   they never appeared in the authored markup string.
+ *
+ * The wrapping itself lives in `./wrap-overwide.js`, shared with the table
+ * wrapper: only the four values below and the accessible name differ.
  */
-const SCROLL_WRAPPER_CLASS = "pie-image-scroll";
-const PIE_CUSTOM_ELEMENT_TAG_REGEX = /^pie-/i;
-function isInsidePieCustomElement(image, root) {
-    let ancestor = image.parentElement;
-    while (ancestor && ancestor !== root) {
-        if (PIE_CUSTOM_ELEMENT_TAG_REGEX.test(ancestor.tagName)) {
-            return true;
-        }
-        ancestor = ancestor.parentElement;
-    }
-    return false;
-}
+import { wrapOverwideInElement, wrapOverwideMarkup, } from "./wrap-overwide.js";
 function buildAriaLabel(image) {
     const alt = image.getAttribute("alt");
     const trimmed = alt ? alt.trim() : "";
     return trimmed ? `Scrollable image: ${trimmed}` : "Scrollable image";
 }
+const IMAGE_SPEC = {
+    selector: "img",
+    wrapperTag: "span",
+    wrapperClass: "pie-image-scroll",
+    markupProbe: /<img\b/i,
+    buildAriaLabel,
+};
 /**
  * Wrap every unwrapped `<img>` descendant of `root` with the shared
  * horizontal-scroll span. Returns the number of newly-wrapped images so
  * callers can short-circuit when nothing changed. Idempotent.
  */
 export function wrapOverwideImagesInElement(root, options = {}) {
-    const { skipPieDescendants = false } = options;
-    const images = Array.from(root.querySelectorAll("img"));
-    if (images.length === 0)
-        return 0;
-    const ownerDocument = root.ownerDocument;
-    if (!ownerDocument)
-        return 0;
-    let wrapped = 0;
-    for (const image of images) {
-        const parent = image.parentElement;
-        if (!parent)
-            continue;
-        // Idempotency — already wrapped.
-        if (parent.classList && parent.classList.contains(SCROLL_WRAPPER_CLASS)) {
-            continue;
-        }
-        // Authored-markup pass: leave PIE custom-element internals alone.
-        if (skipPieDescendants && isInsidePieCustomElement(image, root))
-            continue;
-        const wrapper = ownerDocument.createElement("span");
-        wrapper.className = SCROLL_WRAPPER_CLASS;
-        wrapper.setAttribute("tabindex", "0");
-        wrapper.setAttribute("role", "region");
-        wrapper.setAttribute("aria-label", buildAriaLabel(image));
-        parent.insertBefore(wrapper, image);
-        wrapper.appendChild(image);
-        wrapped += 1;
-    }
-    return wrapped;
+    return wrapOverwideInElement(root, IMAGE_SPEC, options);
 }
 /**
  * Wrap `<img>` elements in `markup` with a horizontal-scroll container.
@@ -91,25 +62,5 @@ export function wrapOverwideImagesInElement(root, options = {}) {
  *   to wrap element-rendered images.
  */
 export function wrapOverwideImages(markup) {
-    if (!markup)
-        return "";
-    // Fast path: avoid the DOM round-trip entirely when the markup carries no
-    // images. Keeps the sanitize pipeline cheap for the common case.
-    if (!/<img\b/i.test(markup))
-        return markup;
-    if (typeof window === "undefined" || !window.document)
-        return markup;
-    const ParserCtor = typeof DOMParser !== "undefined"
-        ? DOMParser
-        : window.DOMParser;
-    if (!ParserCtor)
-        return markup;
-    const doc = new ParserCtor().parseFromString(`<!DOCTYPE html><html><body>${markup}</body></html>`, "text/html");
-    const body = doc.body;
-    if (!body)
-        return markup;
-    const wrapped = wrapOverwideImagesInElement(body, {
-        skipPieDescendants: true,
-    });
-    return wrapped > 0 ? body.innerHTML : markup;
+    return wrapOverwideMarkup(markup, IMAGE_SPEC);
 }

package/dist/security/wrap-overwide-tables.d.ts CHANGED Viewed

@@ -22,17 +22,12 @@
  *   PIE element paints into its own light DOM (e.g. a `pie-passage`'s
  *   model-driven content) get the same scrollable affordance even though
  *   they never appeared in the authored markup string.
+ *
+ * The wrapping itself lives in `./wrap-overwide.js`, shared with the image
+ * wrapper: only the four values below and the accessible name differ.
  */
-export interface WrapOverwideTablesInElementOptions {
-    /**
-     * When `true`, tables whose nearest `pie-*` ancestor is *strictly between*
-     * the table and `root` are left alone. Used by the string pipeline so the
-     * authored-markup pass doesn't restructure a PIE element's own template.
-     * Defaults to `false` so the live-DOM pass *does* wrap element-rendered
-     * tables.
-     */
-    skipPieDescendants?: boolean;
-}
+import { type WrapOverwideOptions } from "./wrap-overwide.js";
+export type WrapOverwideTablesInElementOptions = WrapOverwideOptions;
 /**
  * Wrap every unwrapped `<table>` descendant of `root` with the shared
  * horizontal-scroll div. Returns the number of newly-wrapped tables so

package/dist/security/wrap-overwide-tables.js CHANGED Viewed

@@ -22,19 +22,11 @@
  *   PIE element paints into its own light DOM (e.g. a `pie-passage`'s
  *   model-driven content) get the same scrollable affordance even though
  *   they never appeared in the authored markup string.
+ *
+ * The wrapping itself lives in `./wrap-overwide.js`, shared with the image
+ * wrapper: only the four values below and the accessible name differ.
  */
-const SCROLL_WRAPPER_CLASS = "pie-table-scroll";
-const PIE_CUSTOM_ELEMENT_TAG_REGEX = /^pie-/i;
-function isInsidePieCustomElement(table, root) {
-    let ancestor = table.parentElement;
-    while (ancestor && ancestor !== root) {
-        if (PIE_CUSTOM_ELEMENT_TAG_REGEX.test(ancestor.tagName)) {
-            return true;
-        }
-        ancestor = ancestor.parentElement;
-    }
-    return false;
-}
+import { wrapOverwideInElement, wrapOverwideMarkup, } from "./wrap-overwide.js";
 function buildAriaLabel(table) {
     // Authors commonly label tables via <caption>, aria-label, or aria-labelledby.
     // Prefer the most explicit signal and fall back to the generic label so
@@ -65,62 +57,21 @@ function buildAriaLabel(table) {
     }
     return "Scrollable table";
 }
+const TABLE_SPEC = {
+    selector: "table",
+    wrapperTag: "div",
+    wrapperClass: "pie-table-scroll",
+    markupProbe: /<table\b/i,
+    buildAriaLabel,
+};
 /**
  * Wrap every unwrapped `<table>` descendant of `root` with the shared
  * horizontal-scroll div. Returns the number of newly-wrapped tables so
  * callers can short-circuit when nothing changed. Idempotent.
  */
 export function wrapOverwideTablesInElement(root, options = {}) {
-    const { skipPieDescendants = false } = options;
-    const tables = Array.from(root.querySelectorAll("table"));
-    if (tables.length === 0)
-        return 0;
-    const ownerDocument = root.ownerDocument;
-    if (!ownerDocument)
-        return 0;
-    let wrapped = 0;
-    for (const table of tables) {
-        const parent = table.parentElement;
-        if (!parent)
-            continue;
-        // Idempotency — already wrapped.
-        if (parent.classList && parent.classList.contains(SCROLL_WRAPPER_CLASS)) {
-            continue;
-        }
-        // Authored-markup pass: leave PIE custom-element internals alone.
-        if (skipPieDescendants && isInsidePieCustomElement(table, root))
-            continue;
-        const wrapper = ownerDocument.createElement("div");
-        wrapper.className = SCROLL_WRAPPER_CLASS;
-        wrapper.setAttribute("tabindex", "0");
-        wrapper.setAttribute("role", "region");
-        wrapper.setAttribute("aria-label", buildAriaLabel(table));
-        parent.insertBefore(wrapper, table);
-        wrapper.appendChild(table);
-        wrapped += 1;
-    }
-    return wrapped;
+    return wrapOverwideInElement(root, TABLE_SPEC, options);
 }
 export function wrapOverwideTables(markup) {
-    if (!markup)
-        return "";
-    // Fast path: avoid the DOM round-trip entirely when the markup carries no
-    // tables. Keeps the sanitize pipeline cheap for the common case.
-    if (!/<table\b/i.test(markup))
-        return markup;
-    if (typeof window === "undefined" || !window.document)
-        return markup;
-    const ParserCtor = typeof DOMParser !== "undefined"
-        ? DOMParser
-        : window.DOMParser;
-    if (!ParserCtor)
-        return markup;
-    const doc = new ParserCtor().parseFromString(`<!DOCTYPE html><html><body>${markup}</body></html>`, "text/html");
-    const body = doc.body;
-    if (!body)
-        return markup;
-    const wrapped = wrapOverwideTablesInElement(body, {
-        skipPieDescendants: true,
-    });
-    return wrapped > 0 ? body.innerHTML : markup;
+    return wrapOverwideMarkup(markup, TABLE_SPEC);
 }

package/dist/security/wrap-overwide.d.ts ADDED Viewed

@@ -0,0 +1,51 @@
+/**
+ * The wrapping engine behind `wrapOverwideImages` and `wrapOverwideTables`.
+ *
+ * Both exist for the same reason — content wider than its column must surface a
+ * scrollbar rather than be clipped by an ancestor `overflow-x: hidden` (PIE-94,
+ * WCAG 1.4.10 Reflow at 400% zoom) — and both wrap the same way: find the
+ * unwrapped nodes, skip a PIE element's own template on the authored-markup pass,
+ * and insert a focusable `role="region"` wrapper carrying the CSS from
+ * `@pie-players/pie-theme`.
+ *
+ * What genuinely differs per content kind is declared in {@link OverwideWrapSpec}
+ * and nothing else: the selector, the wrapper's tag and class, the fast-path probe
+ * on the markup string, and how a region announces itself. Accessible naming is
+ * the real divergence — an image has `alt`, a table has `<caption>`,
+ * `aria-label` and `aria-labelledby` — which is why it is a function rather than
+ * a template.
+ */
+/** What one content kind needs in order to be wrapped. */
+export interface OverwideWrapSpec {
+    /** Selector for the nodes to wrap, e.g. `"img"`. */
+    selector: string;
+    /** Tag of the inserted wrapper — inline for images, block for tables. */
+    wrapperTag: string;
+    /** Class the theme package styles, e.g. `"pie-image-scroll"`. */
+    wrapperClass: string;
+    /** Cheap test for "this markup could contain the nodes at all". */
+    markupProbe: RegExp;
+    /** The wrapper's accessible name for one node. */
+    buildAriaLabel: (node: Element) => string;
+}
+export interface WrapOverwideOptions {
+    /**
+     * When `true`, nodes whose nearest `pie-*` ancestor is *strictly between* the
+     * node and `root` are left alone. Used by the string pipeline so the
+     * authored-markup pass doesn't restructure a PIE element's own template.
+     * Defaults to `false` so the live-DOM pass *does* wrap element-rendered nodes.
+     */
+    skipPieDescendants?: boolean;
+}
+/**
+ * Wrap every unwrapped match under `root`. Returns the number newly wrapped so
+ * callers can short-circuit when nothing changed. Idempotent.
+ */
+export declare function wrapOverwideInElement(root: Element, spec: OverwideWrapSpec, options?: WrapOverwideOptions): number;
+/**
+ * String-in / string-out wrapping, for the post-sanitization step.
+ *
+ * No-ops on empty input, and during SSR (no `window` / `DOMParser`) — the markup
+ * is returned unchanged and the browser re-run on hydrate performs the wrap.
+ */
+export declare function wrapOverwideMarkup(markup: string, spec: OverwideWrapSpec): string;

package/dist/security/wrap-overwide.js ADDED Viewed

@@ -0,0 +1,91 @@
+/**
+ * The wrapping engine behind `wrapOverwideImages` and `wrapOverwideTables`.
+ *
+ * Both exist for the same reason — content wider than its column must surface a
+ * scrollbar rather than be clipped by an ancestor `overflow-x: hidden` (PIE-94,
+ * WCAG 1.4.10 Reflow at 400% zoom) — and both wrap the same way: find the
+ * unwrapped nodes, skip a PIE element's own template on the authored-markup pass,
+ * and insert a focusable `role="region"` wrapper carrying the CSS from
+ * `@pie-players/pie-theme`.
+ *
+ * What genuinely differs per content kind is declared in {@link OverwideWrapSpec}
+ * and nothing else: the selector, the wrapper's tag and class, the fast-path probe
+ * on the markup string, and how a region announces itself. Accessible naming is
+ * the real divergence — an image has `alt`, a table has `<caption>`,
+ * `aria-label` and `aria-labelledby` — which is why it is a function rather than
+ * a template.
+ */
+const PIE_CUSTOM_ELEMENT_TAG_REGEX = /^pie-/i;
+function isInsidePieCustomElement(node, root) {
+    let ancestor = node.parentElement;
+    while (ancestor && ancestor !== root) {
+        if (PIE_CUSTOM_ELEMENT_TAG_REGEX.test(ancestor.tagName)) {
+            return true;
+        }
+        ancestor = ancestor.parentElement;
+    }
+    return false;
+}
+/**
+ * Wrap every unwrapped match under `root`. Returns the number newly wrapped so
+ * callers can short-circuit when nothing changed. Idempotent.
+ */
+export function wrapOverwideInElement(root, spec, options = {}) {
+    const { skipPieDescendants = false } = options;
+    const nodes = Array.from(root.querySelectorAll(spec.selector));
+    if (nodes.length === 0)
+        return 0;
+    const ownerDocument = root.ownerDocument;
+    if (!ownerDocument)
+        return 0;
+    let wrapped = 0;
+    for (const node of nodes) {
+        const parent = node.parentElement;
+        if (!parent)
+            continue;
+        // Idempotency — already wrapped.
+        if (parent.classList?.contains(spec.wrapperClass))
+            continue;
+        // Authored-markup pass: leave PIE custom-element internals alone.
+        if (skipPieDescendants && isInsidePieCustomElement(node, root))
+            continue;
+        const wrapper = ownerDocument.createElement(spec.wrapperTag);
+        wrapper.className = spec.wrapperClass;
+        wrapper.setAttribute("tabindex", "0");
+        wrapper.setAttribute("role", "region");
+        wrapper.setAttribute("aria-label", spec.buildAriaLabel(node));
+        parent.insertBefore(wrapper, node);
+        wrapper.appendChild(node);
+        wrapped += 1;
+    }
+    return wrapped;
+}
+/**
+ * String-in / string-out wrapping, for the post-sanitization step.
+ *
+ * No-ops on empty input, and during SSR (no `window` / `DOMParser`) — the markup
+ * is returned unchanged and the browser re-run on hydrate performs the wrap.
+ */
+export function wrapOverwideMarkup(markup, spec) {
+    if (!markup)
+        return "";
+    // Fast path: avoid the DOM round-trip entirely when the markup carries none of
+    // these nodes. Keeps the sanitize pipeline cheap for the common case.
+    if (!spec.markupProbe.test(markup))
+        return markup;
+    if (typeof window === "undefined" || !window.document)
+        return markup;
+    const ParserCtor = typeof DOMParser !== "undefined"
+        ? DOMParser
+        : window.DOMParser;
+    if (!ParserCtor)
+        return markup;
+    const doc = new ParserCtor().parseFromString(`<!DOCTYPE html><html><body>${markup}</body></html>`, "text/html");
+    const body = doc.body;
+    if (!body)
+        return markup;
+    const wrapped = wrapOverwideInElement(body, spec, {
+        skipPieDescendants: true,
+    });
+    return wrapped > 0 ? body.innerHTML : markup;
+}

package/dist/server/npm-auth-env.d.ts ADDED Viewed

@@ -0,0 +1,13 @@
+/**
+ * Write a temp `.npmrc` carrying a scoped `_authToken` and return an env
+ * object pointing `NPM_CONFIG_USERCONFIG` at it, so a publish subprocess
+ * authenticates without a separate `npm login`. The token comes from
+ * `NPM_TOKEN`/`NODE_AUTH_TOKEN` in `baseEnv` first, falling back to parsing
+ * an `.env`-style file at `envPath` for either key.
+ *
+ * Call `cleanup()` once the subprocess using `env` has exited.
+ */
+export declare const createNpmAuthEnvironment: (envPath?: string, baseEnv?: NodeJS.ProcessEnv) => {
+    env: NodeJS.ProcessEnv;
+    cleanup: () => void;
+};

package/dist/server/npm-auth-env.js ADDED Viewed

@@ -0,0 +1,64 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+if (typeof window !== "undefined") {
+    throw new Error("[npm-auth-env] @pie-players/pie-players-shared/server/npm-auth-env is server-only and cannot be imported in browser code");
+}
+const REGISTRY = "https://registry.npmjs.org/";
+const parseDotEnvToken = (envPath, key) => {
+    try {
+        const content = readFileSync(envPath, "utf8");
+        const pattern = new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=\\s*(.*)\\s*$`, "m");
+        const match = content.match(pattern);
+        if (!match?.[1])
+            return "";
+        const rawValue = match[1].trim();
+        const isWrappedInQuotes = (rawValue.startsWith('"') && rawValue.endsWith('"')) ||
+            (rawValue.startsWith("'") && rawValue.endsWith("'"));
+        return (isWrappedInQuotes ? rawValue.slice(1, -1) : rawValue).trim();
+    }
+    catch {
+        return "";
+    }
+};
+const resolveToken = (envPath, baseEnv) => {
+    const envToken = String(baseEnv.NPM_TOKEN || baseEnv.NODE_AUTH_TOKEN || "").trim();
+    if (envToken)
+        return envToken;
+    if (!envPath)
+        return "";
+    return (parseDotEnvToken(envPath, "NPM_TOKEN") ||
+        parseDotEnvToken(envPath, "NODE_AUTH_TOKEN"));
+};
+/**
+ * Write a temp `.npmrc` carrying a scoped `_authToken` and return an env
+ * object pointing `NPM_CONFIG_USERCONFIG` at it, so a publish subprocess
+ * authenticates without a separate `npm login`. The token comes from
+ * `NPM_TOKEN`/`NODE_AUTH_TOKEN` in `baseEnv` first, falling back to parsing
+ * an `.env`-style file at `envPath` for either key.
+ *
+ * Call `cleanup()` once the subprocess using `env` has exited.
+ */
+export const createNpmAuthEnvironment = (envPath, baseEnv = process.env) => {
+    const token = resolveToken(envPath, baseEnv);
+    if (!token) {
+        return {
+            env: baseEnv,
+            cleanup: () => { },
+        };
+    }
+    const tempDir = mkdtempSync(join(tmpdir(), "pie-npm-auth-"));
+    const npmrcPath = join(tempDir, ".npmrc");
+    writeFileSync(npmrcPath, `registry=${REGISTRY}\n//registry.npmjs.org/:_authToken=${token}\n`, "utf8");
+    return {
+        env: {
+            ...baseEnv,
+            NPM_CONFIG_USERCONFIG: npmrcPath,
+            NODE_AUTH_TOKEN: String(baseEnv.NODE_AUTH_TOKEN || "").trim() || token,
+            NPM_TOKEN: String(baseEnv.NPM_TOKEN || "").trim() || token,
+        },
+        cleanup: () => {
+            rmSync(tempDir, { recursive: true, force: true });
+        },
+    };
+};

package/dist/timed-media/index.d.ts ADDED Viewed

@@ -0,0 +1,17 @@
+/**
+ * Timed-media sections: cue policy, playback policy, and the Media Time Source
+ * port.
+ *
+ * Pure apart from one adapter factory that is inert until called, so the contract
+ * is testable without a browser and an adapter can import it without pulling in a
+ * player. Live cue state belongs to `SectionController` in
+ * `@pie-players/pie-section-player`, which is where the equivalent formative state
+ * lives — one rollup over one item set, in one package.
+ *
+ * Contract: `docs/prds/timed-media-section-contract.md`.
+ */
+export type { MediaTimeRanges, MediaTimeSource, MediaTimeSourceCapabilities, MediaTimeSourceNotification, ResolvedTimedMediaCue, ResolvedTimedMediaSectionData, TimedMediaCue, TimedMediaCueActivation, TimedMediaCuePolicy, TimedMediaDegradation, TimedMediaDeliveryState, TimedMediaEffects, TimedMediaEnforcement, TimedMediaGateCondition, TimedMediaGateView, TimedMediaInput, TimedMediaItemTryBudget, TimedMediaPlaybackPolicy, TimedMediaReduction, TimedMediaScoringPolicy, TimedMediaSectionData, TimedMediaSectionProjection, TimedMediaSectionSessionSlice, TimedMediaUnknownCorrectness, TimedMediaValidationError, TimedMediaValidationResult, } from "./types.js";
+export { TIMED_MEDIA_PLAYBACK_POLICY_DEFAULTS, normalizeTimedMediaSectionData, } from "./policy.js";
+export { TIMED_MEDIA_SLICE_VERSION, createTimedMediaState, reduceTimedMediaState, resolveTimedMediaEnforcement, resolveTimedMediaProjection, timedMediaProjectionSignature, } from "./state.js";
+export { normalizeTimedMediaSectionSlice, toTimedMediaSectionSlice, } from "./session.js";
+export { NATIVE_MEDIA_CAPABILITIES, createMediaElementTimeSource, findMediaElement, type MediaElementTimeSourceOptions, } from "./media-element-source.js";

package/dist/timed-media/index.js ADDED Viewed

@@ -0,0 +1,16 @@
+/**
+ * Timed-media sections: cue policy, playback policy, and the Media Time Source
+ * port.
+ *
+ * Pure apart from one adapter factory that is inert until called, so the contract
+ * is testable without a browser and an adapter can import it without pulling in a
+ * player. Live cue state belongs to `SectionController` in
+ * `@pie-players/pie-section-player`, which is where the equivalent formative state
+ * lives — one rollup over one item set, in one package.
+ *
+ * Contract: `docs/prds/timed-media-section-contract.md`.
+ */
+export { TIMED_MEDIA_PLAYBACK_POLICY_DEFAULTS, normalizeTimedMediaSectionData, } from "./policy.js";
+export { TIMED_MEDIA_SLICE_VERSION, createTimedMediaState, reduceTimedMediaState, resolveTimedMediaEnforcement, resolveTimedMediaProjection, timedMediaProjectionSignature, } from "./state.js";
+export { normalizeTimedMediaSectionSlice, toTimedMediaSectionSlice, } from "./session.js";
+export { NATIVE_MEDIA_CAPABILITIES, createMediaElementTimeSource, findMediaElement, } from "./media-element-source.js";

package/dist/timed-media/media-element-source.d.ts ADDED Viewed

@@ -0,0 +1,36 @@
+/**
+ * The native `<video>` / `<audio>` adapter for the Media Time Source port.
+ *
+ * Short by design. The port is shaped after `HTMLMediaElement` precisely so that
+ * the browser's own media element satisfies it in a few lines, which is what
+ * makes the port testable and the eventual media-player dependency reversible
+ * rather than load-bearing.
+ *
+ * Touches no DOM until called, so this module stays importable in Node beside the
+ * rest of the pure timed-media contract.
+ */
+import type { MediaTimeSource, MediaTimeSourceCapabilities } from "./types.js";
+/**
+ * A native media element can be paused and its position can be written, so both
+ * capabilities hold. A host wrapping something that only *looks* native — an
+ * embed behind a facade, a remote-controlled player — overrides them rather than
+ * letting the section assume control it does not have.
+ */
+export declare const NATIVE_MEDIA_CAPABILITIES: MediaTimeSourceCapabilities;
+export interface MediaElementTimeSourceOptions {
+    capabilities?: Partial<MediaTimeSourceCapabilities>;
+}
+/** The subset of `HTMLMediaElement` this adapter uses. */
+type MediaElementLike = Pick<HTMLMediaElement, "currentTime" | "duration" | "paused" | "seekable" | "play" | "pause" | "addEventListener" | "removeEventListener">;
+export declare function createMediaElementTimeSource(element: MediaElementLike, options?: MediaElementTimeSourceOptions): MediaTimeSource;
+/**
+ * Find the media element a stimulus renderable mounted.
+ *
+ * Deliberately a plain query rather than a contract on what the stimulus is: a
+ * passage config mounting `<pie-video-stimulus>`, and one carrying authored
+ * `<video>` markup, both end up with a media element in the card's subtree, and
+ * the section needs no way to tell them apart. An element that wants to supply its
+ * own port registers one instead.
+ */
+export declare function findMediaElement(root: ParentNode | null): HTMLMediaElement | null;
+export {};

package/dist/timed-media/media-element-source.js ADDED Viewed

@@ -0,0 +1,121 @@
+/**
+ * The native `<video>` / `<audio>` adapter for the Media Time Source port.
+ *
+ * Short by design. The port is shaped after `HTMLMediaElement` precisely so that
+ * the browser's own media element satisfies it in a few lines, which is what
+ * makes the port testable and the eventual media-player dependency reversible
+ * rather than load-bearing.
+ *
+ * Touches no DOM until called, so this module stays importable in Node beside the
+ * rest of the pure timed-media contract.
+ */
+/**
+ * A native media element can be paused and its position can be written, so both
+ * capabilities hold. A host wrapping something that only *looks* native — an
+ * embed behind a facade, a remote-controlled player — overrides them rather than
+ * letting the section assume control it does not have.
+ */
+export const NATIVE_MEDIA_CAPABILITIES = {
+    canPause: true,
+    canRestrictSeeking: true,
+};
+const NOTIFYING_EVENTS = [
+    { name: "timeupdate", type: "time" },
+    // Both halves of a seek are reported. `seeking` is where a clamp can still
+    // land before the frame paints at the new position; `seeked` is the one that
+    // always fires. The reduction is idempotent for an already-legal position, so
+    // reporting twice costs nothing.
+    { name: "seeking", type: "seek" },
+    { name: "seeked", type: "seek" },
+    { name: "play", type: "play" },
+    { name: "pause", type: "pause" },
+    { name: "ended", type: "ended" },
+];
+export function createMediaElementTimeSource(element, options = {}) {
+    const capabilities = {
+        ...NATIVE_MEDIA_CAPABILITIES,
+        ...(options.capabilities ?? {}),
+    };
+    const listeners = new Set();
+    function currentTime() {
+        const value = element.currentTime;
+        return Number.isFinite(value) && value >= 0 ? value : 0;
+    }
+    function notify(type) {
+        const notification = { type, currentTime: currentTime() };
+        for (const listener of Array.from(listeners)) {
+            try {
+                listener(notification);
+            }
+            catch {
+                // A subscriber that throws must not stop the others or break playback:
+                // this runs on every `timeupdate`.
+            }
+        }
+    }
+    const handlers = NOTIFYING_EVENTS.map((entry) => ({
+        name: entry.name,
+        handler: () => notify(entry.type),
+    }));
+    return {
+        get currentTime() {
+            return currentTime();
+        },
+        get duration() {
+            // `NaN` before metadata loads, as on the element itself. Callers that
+            // need a real duration wait for it rather than reading a zero that looks
+            // like a finished video.
+            return element.duration;
+        },
+        get paused() {
+            return element.paused;
+        },
+        get seekable() {
+            return element.seekable ?? null;
+        },
+        capabilities,
+        play() {
+            return element.play();
+        },
+        pause() {
+            element.pause();
+        },
+        seekTo(seconds) {
+            if (!Number.isFinite(seconds) || seconds < 0)
+                return;
+            element.currentTime = seconds;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            if (listeners.size === 1) {
+                for (const entry of handlers) {
+                    element.addEventListener(entry.name, entry.handler);
+                }
+            }
+            return () => {
+                if (!listeners.delete(listener))
+                    return;
+                if (listeners.size > 0)
+                    return;
+                for (const entry of handlers) {
+                    element.removeEventListener(entry.name, entry.handler);
+                }
+            };
+        },
+    };
+}
+/**
+ * Find the media element a stimulus renderable mounted.
+ *
+ * Deliberately a plain query rather than a contract on what the stimulus is: a
+ * passage config mounting `<pie-video-stimulus>`, and one carrying authored
+ * `<video>` markup, both end up with a media element in the card's subtree, and
+ * the section needs no way to tell them apart. An element that wants to supply its
+ * own port registers one instead.
+ */
+export function findMediaElement(root) {
+    if (!root)
+        return null;
+    const found = root.querySelector("video, audio");
+    return found ?? null;
+}

package/dist/timed-media/policy.d.ts ADDED Viewed

@@ -0,0 +1,36 @@
+/**
+ * Validation for authored timed-media section data.
+ *
+ * Authored, wire-facing and untrusted, so every field is checked here and the
+ * caller never hand-parses. Errors are returned rather than thrown: the section
+ * reports them as a framework error and delivers as an ordinary section, which is
+ * loud without costing the learner the content.
+ */
+import type { TimedMediaItemTryBudget, TimedMediaPlaybackPolicy, TimedMediaValidationResult } from "./types.js";
+/**
+ * Applied when `playbackPolicy` is absent entirely. The restrictive values are
+ * the defaults because a timed-media section is authored to sequence: a section
+ * that forgot the policy block reads as one that wanted sequencing, and the
+ * permissive reading would silently deliver an unsequenced video.
+ */
+export declare const TIMED_MEDIA_PLAYBACK_POLICY_DEFAULTS: TimedMediaPlaybackPolicy;
+/**
+ * Validate authored `timedMedia` against the section it belongs to.
+ *
+ * `resolveStimulusRenderableId` is supplied by the caller because the mapping
+ * from an authored `stimulusRef` to a rendered renderable id belongs to the
+ * content service that assigned that id — deriving it twice is two
+ * implementations of one mapping.
+ */
+export declare function normalizeTimedMediaSectionData(args: {
+    timedMedia: unknown;
+    /** Canonical identifiers of the section's item refs. */
+    itemIdentifiers: readonly string[];
+    resolveStimulusRenderableId: (stimulusRef: string) => string | undefined;
+    /**
+     * The Try budget each item's resolved formative policy leaves, so a gate on
+     * correctness can be refused where it would strand the learner. Supplied by the
+     * caller because formative policy resolution is that contract's, not this one's.
+     */
+    resolveItemTryBudget: (itemIdentifier: string) => TimedMediaItemTryBudget;
+}): TimedMediaValidationResult;