@pie-players/pie-players-shared 1.0.0-beta.1 → 1.0.0-beta.3

package/dist/instrumentation/providers/CompositeInstrumentationProvider.js

@@ -1,3 +1,4 @@
+import { settleAll } from "../../promise/index.js";
 export class CompositeInstrumentationProvider {
     providerId = "composite";
     providerName = "Composite Provider";
@@ -7,7 +8,7 @@ export class CompositeInstrumentationProvider {
         this.providers = providers.filter(Boolean);
     }
     async initialize(config) {
-        const results = await Promise.allSettled(this.providers.map((provider) => provider.initialize(config)));
+        const results = await settleAll(this.providers.map((provider) => provider.initialize(config)));
         this.initialized = true;
         if (config?.debug) {
             for (const [index, result] of results.entries()) {

package/dist/loaders/element-package-spec.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shape check for the package specs an item config names in `elements`.
+ *
+ * Loaders that build CDN URLs from a spec run it through
+ * `isScopedPackageSpec` first: item configs are authored content, and a
+ * version such as `1.0.0/../../../gh/owner/repo@main` would otherwise
+ * resolve to a path outside the package.
+ */
+/**
+ * A scoped npm package name with an optional semver version or dist-tag, as
+ * item configs store it: `@pie-element/rubric`, `@pie-element/rubric@latest`,
+ * `@pie-element/rubric@8.0.0-hotfix.2`.
+ */
+export declare function isScopedPackageSpec(spec: unknown): spec is string;
+/** Why a loader refused `spec`, for its failure reason. */
+export declare function invalidPackageSpecMessage(spec: unknown): string;

package/dist/loaders/element-package-spec.js

@@ -0,0 +1,30 @@
+/**
+ * Shape check for the package specs an item config names in `elements`.
+ *
+ * Loaders that build CDN URLs from a spec run it through
+ * `isScopedPackageSpec` first: item configs are authored content, and a
+ * version such as `1.0.0/../../../gh/owner/repo@main` would otherwise
+ * resolve to a path outside the package.
+ */
+const SEMVER_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const DIST_TAG = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const SCOPED_PACKAGE_NAME = /^@[a-z0-9~-][a-z0-9._~-]*\/[a-z0-9~-][a-z0-9._~-]*$/;
+/**
+ * A scoped npm package name with an optional semver version or dist-tag, as
+ * item configs store it: `@pie-element/rubric`, `@pie-element/rubric@latest`,
+ * `@pie-element/rubric@8.0.0-hotfix.2`.
+ */
+export function isScopedPackageSpec(spec) {
+    if (typeof spec !== "string")
+        return false;
+    const versionAt = spec.indexOf("@", 1);
+    if (versionAt === -1)
+        return SCOPED_PACKAGE_NAME.test(spec);
+    const version = spec.slice(versionAt + 1);
+    return (SCOPED_PACKAGE_NAME.test(spec.slice(0, versionAt)) &&
+        (SEMVER_VERSION.test(version) || DIST_TAG.test(version)));
+}
+/** Why a loader refused `spec`, for its failure reason. */
+export function invalidPackageSpecMessage(spec) {
+    return `Invalid element package spec ${JSON.stringify(String(spec))}: expected a scoped npm package name with an optional semver version or dist-tag`;
+}

package/dist/loaders/esm-adapter.d.ts

@@ -67,7 +67,8 @@ export declare function createEsmBackend(config: EsmBackendConfig): EsmBackend;
 export declare function mapEsmViewElements(elements: ElementMap, view?: string, viewConfig?: ViewConfig): ElementMap;
 /**
  * URL of a package's `./runtime-support` module on the ESM CDN the players load
- * elements from, or `undefined` when a custom provider names no package root.
+ * elements from, or `undefined` when a custom provider names no package root or
+ * `packageVersion` is not a scoped package spec.
  */
 export declare function resolveEsmRuntimeSupportUrl(packageVersion: string, options: {
     cdnBaseUrl: string;

package/dist/loaders/esm-adapter.js

@@ -21,6 +21,7 @@ import { BundleType, isCustomElementConstructor, Status, } from "../pie/types.js
 import { parsePackageName } from "../pie/utils.js";
 import { AdapterFailure, } from "./element-loader-types.js";
 import { isExactSemver } from "./element-package-policy.js";
+import { invalidPackageSpecMessage, isScopedPackageSpec, } from "./element-package-spec.js";
 import { forwardMathjaxEvents } from "./mathjax-events.js";
 import { isPlainRecord } from "../object/index.js";
 export const BUILT_IN_VIEWS = {
@@ -80,12 +81,30 @@ export function createEsmBackend(config) {
     async function load(elements, context) {
         if (!elements || Object.keys(elements).length === 0)
             return;
+        // Refused before any URL is built from the spec; the other elements load.
+        const reasons = new Map();
+        const loadable = {};
+        for (const [tag, pkg] of Object.entries(elements)) {
+            if (isScopedPackageSpec(pkg)) {
+                loadable[tag] = pkg;
+            }
+            else {
+                reasons.set(tag, {
+                    kind: "backend-rejected",
+                    tag,
+                    cause: invalidPackageSpecMessage(pkg),
+                });
+            }
+        }
+        if (Object.keys(loadable).length === 0) {
+            throw new AdapterFailure(reasons);
+        }
         if (moduleResolution === "import-map") {
             assertImportMapSupported();
         }
         forwardMathjaxEventsOf(context.doc);
         const newEntries = {};
-        for (const [tag, pkg] of Object.entries(elements)) {
+        for (const [tag, pkg] of Object.entries(loadable)) {
             const packageName = parsePackageName(pkg).name;
             if (moduleResolution === "import-map") {
                 const existingVersion = importMappedPackageVersions.get(packageName);
@@ -147,8 +166,7 @@ export function createEsmBackend(config) {
                 await applyImportMap(imports, injectedMap, context.doc);
             }
         }
-        const reasons = new Map();
-        await Promise.all(Object.entries(elements).map(async ([tag, packageVersion]) => {
+        await Promise.all(Object.entries(loadable).map(async ([tag, packageVersion]) => {
             const packageName = parsePackageName(packageVersion).name;
             let actualTag;
             try {
@@ -609,9 +627,12 @@ async function fetchPackageMetadata(packageJsonUrl) {
 const RUNTIME_SUPPORT_PATH = "dist/runtime-support.js";
 /**
  * URL of a package's `./runtime-support` module on the ESM CDN the players load
- * elements from, or `undefined` when a custom provider names no package root.
+ * elements from, or `undefined` when a custom provider names no package root or
+ * `packageVersion` is not a scoped package spec.
  */
 export function resolveEsmRuntimeSupportUrl(packageVersion, options) {
+    if (!isScopedPackageSpec(packageVersion))
+        return undefined;
     const cdnBaseUrl = options.cdnBaseUrl.replace(/\/+$/, "");
     const provider = resolveCdnProvider(options.cdnProvider, cdnBaseUrl);
     if (typeof provider.runtimeSupportUrl === "function") {

package/dist/loaders/index.d.ts

@@ -34,6 +34,7 @@ export type { ElementMap } from "./ElementLoader.js";
 export { aggregateElements } from "./ElementLoader.js";
 export type { ElementPackagePolicy } from "./element-package-policy.js";
 export { assertElementPackagesAllowed, ElementPackagePolicyError, } from "./element-package-policy.js";
+export { isScopedPackageSpec } from "./element-package-spec.js";
 export type { BackendContext, BackendOption, ElementLoaderBackend, ElementTag, EnsureRegisteredOptions, EsmBackendConfig, IifeBackendConfig, RegistrationFailureReason, } from "./element-loader.js";
 export { AdapterFailure, ElementAssertionError, ElementLoaderError, assertRegistered, describeRegistrationFailures, ensureRegistered, } from "./element-loader.js";
 export type { BuiltInEsmCdnProviderName, EsmBackend, EsmCdnProvider, EsmCdnProviderName, EsmCdnProviderOption, ViewConfig, } from "./esm-adapter.js";

package/dist/loaders/index.js

@@ -32,6 +32,7 @@
  */
 export { aggregateElements } from "./ElementLoader.js";
 export { assertElementPackagesAllowed, ElementPackagePolicyError, } from "./element-package-policy.js";
+export { isScopedPackageSpec } from "./element-package-spec.js";
 export { AdapterFailure, ElementAssertionError, ElementLoaderError, assertRegistered, describeRegistrationFailures, ensureRegistered, } from "./element-loader.js";
 export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
 export { forwardMathjaxEvents, MATHJAX_NO_ASSET_ROOT_EVENT, MATHJAX_VERSION_CONFLICT_EVENT, } from "./mathjax-events.js";

package/dist/loaders/preloaded-registration.d.ts

@@ -11,6 +11,11 @@
  * define the ones content names under another base tag
  * (`defineAuthoredPreloadedTags`) and assert them (`assertRegistered`).
  *
+ * pie-elements-ng's `./browser/*` modules export `piePackage`, the
+ * `{ name, version }` of the package they were built from, so an entry can
+ * give its modules alone. A `package` or `version` it also gives must match,
+ * which catches a registration an upgrade left behind.
+ *
  * A hosted player takes models from the server and resolves no controller. A
  * player that is not hosted runs the controller's `model()` in the browser, so
  * it needs the `controller` an entry registers; the item player warns about
@@ -29,13 +34,20 @@ export interface PreloadedElement {
     /**
      * Base tag to register, e.g. `pie-element-multiple-choice`. Content can
      * author another base tag for the package, which the players define from
-     * this registration.
+     * this registration. Defaults to the package name without its `@`, with
+     * `-` for `/`.
+     */
+    tag?: string;
+    /**
+     * npm package name, e.g. `@pie-element/multiple-choice`. Defaults to the
+     * name in the modules' `piePackage`.
+     */
+    package?: string;
+    /**
+     * The installed version, exact, e.g. `13.4.4`. Defaults to the version in
+     * the modules' `piePackage`.
      */
-    tag: string;
-    /** npm package name, e.g. `@pie-element/multiple-choice`. */
-    package: string;
-    /** The installed version, exact, e.g. `13.4.4`. */
-    version: string;
+    version?: string;
     /** The package's `./browser/delivery` module, or its default export. */
     element: CustomElementConstructor | {
         readonly default: CustomElementConstructor;

package/dist/loaders/preloaded-registration.js

@@ -11,6 +11,11 @@
  * define the ones content names under another base tag
  * (`defineAuthoredPreloadedTags`) and assert them (`assertRegistered`).
  *
+ * pie-elements-ng's `./browser/*` modules export `piePackage`, the
+ * `{ name, version }` of the package they were built from, so an entry can
+ * give its modules alone. A `package` or `version` it also gives must match,
+ * which catches a registration an upgrade left behind.
+ *
  * A hosted player takes models from the server and resolves no controller. A
  * player that is not hosted runs the controller's `model()` in the browser, so
  * it needs the `controller` an entry registers; the item player warns about
@@ -23,6 +28,7 @@
 import { defineCustomElementSafely } from "../pie/custom-element-define.js";
 import { mathAssetOptionsError, setMathAssetOptions, } from "../pie/math-assets.js";
 import { writeRegistryEntry } from "../pie/registry.js";
+import { validateCustomElementTag } from "../pie/tag-names.js";
 import { BundleType, isCustomElementConstructor, Status } from "../pie/types.js";
 import { parsePackageName } from "../pie/utils.js";
 import { toPackageVersionedTag } from "../pie/versioned-tag.js";
@@ -69,15 +75,24 @@ export function registerPreloadedElements(elements, options = {}) {
 function resolveElement(element, index) {
     const at = `[registerPreloadedElements] entry ${index}`;
     if (!element || typeof element !== "object") {
-        throw new Error(`${at}: expected { tag, package, version, element }`);
+        throw new Error(`${at}: expected { element, controller?, tag?, package?, version? }`);
+    }
+    const identity = moduleIdentity(element, at);
+    if (!identity && element.package === undefined && element.version === undefined) {
+        throw new Error(`${at}: package and version are required for modules that export no piePackage`);
     }
-    const { package: packageName, version, tag } = element;
+    const packageName = element.package ?? identity?.name;
+    const version = element.version ?? identity?.version;
     if (!isBarePackageName(packageName)) {
         throw new Error(`${at}: package must be a bare package name, got ${JSON.stringify(packageName)}`);
     }
     if (typeof version !== "string" || !isExactSemver(version)) {
         throw new Error(`${at} (${packageName}): version must be the installed version, exact, such as 1.2.3; got ${JSON.stringify(version)}`);
     }
+    if (identity && (identity.name !== packageName || identity.version !== version)) {
+        throw new Error(`${at}: the modules were built from ${identity.name}@${identity.version}, not ${packageName}@${version}`);
+    }
+    const tag = element.tag ?? packageName.replace(/^@/, "").replace("/", "-");
     if (typeof tag !== "string" || !tag) {
         throw new Error(`${at} (${packageName}): tag must be the base tag to register, got ${JSON.stringify(tag)}`);
     }
@@ -95,13 +110,33 @@ function resolveElement(element, index) {
         }
     }
     const spec = `${packageName}@${version}`;
-    return {
-        packageName,
-        spec,
-        tagName: toPackageVersionedTag(tag, spec),
-        elementClass: candidate,
-        controller,
-    };
+    const tagName = validateCustomElementTag(toPackageVersionedTag(tag, spec), element.tag === undefined
+        ? `${at} (${packageName}) tag derived from the package name; give tag`
+        : `${at} (${packageName}) tag`);
+    return { packageName, spec, tagName, elementClass: candidate, controller };
+}
+/** The `piePackage` of the entry's modules, which agree when both export one. */
+function moduleIdentity(element, at) {
+    const fromElement = readPackageIdentity(element.element, `${at}: element`);
+    const fromController = readPackageIdentity(element.controller, `${at}: controller`);
+    if (fromElement &&
+        fromController &&
+        (fromElement.name !== fromController.name ||
+            fromElement.version !== fromController.version)) {
+        throw new Error(`${at}: the element module is ${fromElement.name}@${fromElement.version}, ` +
+            `but the controller module is ${fromController.name}@${fromController.version}`);
+    }
+    return fromElement ?? fromController;
+}
+function readPackageIdentity(module, at) {
+    if (!module || typeof module !== "object" || !("piePackage" in module)) {
+        return undefined;
+    }
+    const identity = module.piePackage;
+    if (typeof identity?.name !== "string" || typeof identity.version !== "string") {
+        throw new Error(`${at} module's piePackage must be { name, version }`);
+    }
+    return { name: identity.name, version: identity.version };
 }
 function resolveController(value) {
     if (!value || typeof value !== "object")

package/dist/promise/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Waits for every value to settle and resolves with each outcome in input
+ * order, as the `allSettled` static does. Built on `Promise.all` and `then` alone:
+ * a host page can replace the global `Promise` with an implementation that
+ * predates `allSettled` (zone.js 0.9.1 does), so published code calls no
+ * `Promise` static beyond `all`, `race`, `resolve` and `reject`.
+ * `bun run check:bundle-safety` enforces that on every built bundle.
+ * @param values The promises or plain values to settle.
+ */
+export declare const settleAll: <T>(values: Iterable<T | PromiseLike<T>>) => Promise<PromiseSettledResult<Awaited<T>>[]>;

package/dist/promise/index.js

@@ -0,0 +1,16 @@
+/**
+ * Waits for every value to settle and resolves with each outcome in input
+ * order, as the `allSettled` static does. Built on `Promise.all` and `then` alone:
+ * a host page can replace the global `Promise` with an implementation that
+ * predates `allSettled` (zone.js 0.9.1 does), so published code calls no
+ * `Promise` static beyond `all`, `race`, `resolve` and `reject`.
+ * `bun run check:bundle-safety` enforces that on every built bundle.
+ * @param values The promises or plain values to settle.
+ */
+export const settleAll = (values) => Promise.all(Array.from(values, (value) => Promise.resolve(value).then((result) => ({
+    status: "fulfilled",
+    value: result,
+}), (reason) => ({
+    status: "rejected",
+    reason,
+}))));

package/dist/security/overwide-regions.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Keeps the image and table scroll wrappers under a live root in step with
+ * whether they scroll. See {@link syncOverwideRegions}.
+ *
+ * Overflow changes without any mutation: zoom and a resized column change the
+ * wrapper's width, an image load or a dropped drag tile changes its content's.
+ * A `ResizeObserver` on each wrapper and its content catches both, and its first
+ * delivery for a newly observed target is the initial sync. A wrapper that is
+ * not laid out measures zero and syncs as non-scrolling; showing it resizes it,
+ * which syncs it again.
+ *
+ * Without `ResizeObserver` nothing is synced, so every wrapper stays a region —
+ * the reachable default.
+ */
+export interface OverwideRegionTracker {
+    /** Starts observing every wrapper under the root not yet observed. */
+    track(): void;
+    disconnect(): void;
+}
+export declare function createOverwideRegionTracker(root: Element): OverwideRegionTracker;

package/dist/security/overwide-regions.js

@@ -0,0 +1,65 @@
+/**
+ * Keeps the image and table scroll wrappers under a live root in step with
+ * whether they scroll. See {@link syncOverwideRegions}.
+ *
+ * Overflow changes without any mutation: zoom and a resized column change the
+ * wrapper's width, an image load or a dropped drag tile changes its content's.
+ * A `ResizeObserver` on each wrapper and its content catches both, and its first
+ * delivery for a newly observed target is the initial sync. A wrapper that is
+ * not laid out measures zero and syncs as non-scrolling; showing it resizes it,
+ * which syncs it again.
+ *
+ * Without `ResizeObserver` nothing is synced, so every wrapper stays a region —
+ * the reachable default.
+ */
+import { IMAGE_SPEC } from "./wrap-overwide-images.js";
+import { TABLE_SPEC } from "./wrap-overwide-tables.js";
+import { syncOverwideRegions } from "./wrap-overwide.js";
+const SPECS = [IMAGE_SPEC, TABLE_SPEC];
+const WRAPPER_SELECTOR = SPECS.map((spec) => `.${spec.wrapperClass}`).join(",");
+export function createOverwideRegionTracker(root) {
+    if (typeof ResizeObserver === "undefined") {
+        return { track() { }, disconnect() { } };
+    }
+    // Wrapper to the content observed with it. Held strongly, as the observer
+    // holds its targets, so each `track()` releases wrappers that have left the
+    // document — an element re-rendering over its subtree drops them every time.
+    const observed = new Map();
+    const observer = new ResizeObserver((entries) => {
+        const wrappers = new Set();
+        for (const { target } of entries) {
+            const wrapper = target.matches(WRAPPER_SELECTOR)
+                ? target
+                : target.parentElement;
+            if (wrapper)
+                wrappers.add(wrapper);
+        }
+        for (const spec of SPECS)
+            syncOverwideRegions(wrappers, spec);
+    });
+    return {
+        track() {
+            for (const [wrapper, content] of observed) {
+                if (wrapper.isConnected)
+                    continue;
+                observer.unobserve(wrapper);
+                if (content)
+                    observer.unobserve(content);
+                observed.delete(wrapper);
+            }
+            for (const wrapper of Array.from(root.querySelectorAll(WRAPPER_SELECTOR))) {
+                if (observed.has(wrapper))
+                    continue;
+                const content = wrapper.firstElementChild;
+                observed.set(wrapper, content);
+                observer.observe(wrapper);
+                if (content)
+                    observer.observe(content);
+            }
+        },
+        disconnect() {
+            observer.disconnect();
+            observed.clear();
+        },
+    };
+}

package/dist/security/wrap-overwide-images.d.ts

@@ -5,7 +5,9 @@
  *
  * The wrapper is rendered as
  * `<span class="pie-image-scroll" tabindex="0" role="region" aria-label="...">`
- * and receives the accompanying CSS from `@pie-players/pie-theme`. The CSS uses
+ * and receives the accompanying CSS from `@pie-players/pie-theme`.
+ * The live player keeps the region attributes only while the wrapper actually
+ * scrolls (see `./overwide-regions.js`), so a image that fits adds no tab stop. The CSS uses
  * `overflow-x: auto` so small images stay visually unchanged: a scrollbar only
  * appears when the image's intrinsic width exceeds the wrapper's available
  * space (including at higher browser-zoom levels, which is the original driver
@@ -26,7 +28,9 @@
  * The wrapping itself lives in `./wrap-overwide.js`, shared with the table
  * wrapper: only the spec below differs.
  */
-import { type WrapOverwideOptions } from "./wrap-overwide.js";
+import { type OverwideWrapSpec, type WrapOverwideOptions } from "./wrap-overwide.js";
+/** Internal: shared with the region tracker, not re-exported. */
+export declare const IMAGE_SPEC: OverwideWrapSpec;
 export type WrapOverwideImagesInElementOptions = WrapOverwideOptions;
 /**
  * Wrap every unwrapped `<img>` descendant of `root` with the shared

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

@@ -5,7 +5,9 @@
  *
  * The wrapper is rendered as
  * `<span class="pie-image-scroll" tabindex="0" role="region" aria-label="...">`
- * and receives the accompanying CSS from `@pie-players/pie-theme`. The CSS uses
+ * and receives the accompanying CSS from `@pie-players/pie-theme`.
+ * The live player keeps the region attributes only while the wrapper actually
+ * scrolls (see `./overwide-regions.js`), so a image that fits adds no tab stop. The CSS uses
  * `overflow-x: auto` so small images stay visually unchanged: a scrollbar only
  * appears when the image's intrinsic width exceeds the wrapper's available
  * space (including at higher browser-zoom levels, which is the original driver
@@ -50,7 +52,8 @@ function imageLayoutClass(image) {
         display !== "contents";
     return blockLevel ? "pie-image-scroll-block" : null;
 }
-const IMAGE_SPEC = {
+/** Internal: shared with the region tracker, not re-exported. */
+export const IMAGE_SPEC = {
     selector: "img",
     wrapperTag: "span",
     wrapperClass: "pie-image-scroll",

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

@@ -5,7 +5,9 @@
  *
  * The wrapper is rendered as
  * `<div class="pie-table-scroll" tabindex="0" role="region" aria-label="...">`
- * and receives the accompanying CSS from `@pie-players/pie-theme`. The CSS uses
+ * and receives the accompanying CSS from `@pie-players/pie-theme`.
+ * The live player keeps the region attributes only while the wrapper actually
+ * scrolls (see `./overwide-regions.js`), so a table that fits adds no tab stop. The CSS uses
  * `overflow-x: auto` so narrow tables stay visually unchanged: a scrollbar only
  * appears when the table's intrinsic width exceeds the wrapper's available
  * space (including at higher browser-zoom levels — WCAG 1.4.10 Reflow at 400%
@@ -26,7 +28,9 @@
  * The wrapping itself lives in `./wrap-overwide.js`, shared with the image
  * wrapper: only the four values below and the accessible name differ.
  */
-import { type WrapOverwideOptions } from "./wrap-overwide.js";
+import { type OverwideWrapSpec, type WrapOverwideOptions } from "./wrap-overwide.js";
+/** Internal: shared with the region tracker, not re-exported. */
+export declare const TABLE_SPEC: OverwideWrapSpec;
 export type WrapOverwideTablesInElementOptions = WrapOverwideOptions;
 /**
  * Wrap every unwrapped `<table>` descendant of `root` with the shared

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

@@ -5,7 +5,9 @@
  *
  * The wrapper is rendered as
  * `<div class="pie-table-scroll" tabindex="0" role="region" aria-label="...">`
- * and receives the accompanying CSS from `@pie-players/pie-theme`. The CSS uses
+ * and receives the accompanying CSS from `@pie-players/pie-theme`.
+ * The live player keeps the region attributes only while the wrapper actually
+ * scrolls (see `./overwide-regions.js`), so a table that fits adds no tab stop. The CSS uses
  * `overflow-x: auto` so narrow tables stay visually unchanged: a scrollbar only
  * appears when the table's intrinsic width exceeds the wrapper's available
  * space (including at higher browser-zoom levels — WCAG 1.4.10 Reflow at 400%
@@ -57,7 +59,8 @@ function buildAriaLabel(table) {
     }
     return "Scrollable table";
 }
-const TABLE_SPEC = {
+/** Internal: shared with the region tracker, not re-exported. */
+export const TABLE_SPEC = {
     selector: "table",
     wrapperTag: "div",
     wrapperClass: "pie-table-scroll",

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

@@ -55,6 +55,19 @@ export interface WrapOverwideOptions {
  * the layout class this pass would have given it.
  */
 export declare function wrapOverwideInElement(root: Element, spec: OverwideWrapSpec, options?: WrapOverwideOptions): number;
+/**
+ * Makes each wrapper a named, focusable region while its content overflows it
+ * horizontally, and a plain container otherwise.
+ *
+ * A wrapper is built as a region, because a wrapper that scrolls must be
+ * reachable by keyboard (WCAG 2.1.1) and markup wrapped off-document cannot be
+ * measured. Most never scroll: a table that fits its column, a drag tile, a
+ * layout table. Left as regions they add a tab stop and a landmark each, so the
+ * live player measures every wrapper and keeps the region only where there is
+ * something to scroll. Measurements are read for every wrapper before the first
+ * write. A wrapper holding focus keeps its region, so a sync never drops focus.
+ */
+export declare function syncOverwideRegions(wrappers: Iterable<Element>, spec: OverwideWrapSpec): void;
 /**
  * String-in / string-out wrapping, for the post-sanitization step.
  *

package/dist/security/wrap-overwide.js

@@ -40,6 +40,29 @@ function isInsidePieCustomElement(node, root) {
     }
     return false;
 }
+const VERTICAL_MARGINS = ["margin-top", "margin-bottom"];
+/**
+ * Moves the node's inline vertical margins onto its wrapper. The wrapper clips
+ * vertically — `overflow-x: auto` forces `overflow-y` off `visible` — so a
+ * negative margin left on the node pulls its edge into the clipped band, and
+ * the wrapper's own block formatting context stops a positive one collapsing
+ * with its neighbours. On the wrapper, both lay out as they did unwrapped.
+ * Horizontal margins stay: `margin: 0 auto` centres the node inside the wrapper.
+ */
+function liftVerticalMargins(node, wrapper) {
+    const style = node.style;
+    if (!style)
+        return;
+    for (const property of VERTICAL_MARGINS) {
+        const value = style.getPropertyValue(property);
+        if (!value)
+            continue;
+        wrapper.style.setProperty(property, value, style.getPropertyPriority(property));
+        style.removeProperty(property);
+    }
+    if (!style.length)
+        node.removeAttribute("style");
+}
 /**
  * Wrappers whose layout class was read from the live cascade. A wrapper built
  * off-document saw only its node's inline style, so the first live pass to meet
@@ -109,17 +132,59 @@ export function wrapOverwideInElement(root, spec, options = {}) {
         wrapper.className = layoutClass
             ? `${spec.wrapperClass} ${layoutClass}`
             : spec.wrapperClass;
-        wrapper.setAttribute("tabindex", "0");
-        wrapper.setAttribute("role", "region");
-        wrapper.setAttribute("aria-label", spec.buildAriaLabel(node));
+        setRegion(wrapper, node, spec);
         if (readsLiveLayout)
             liveLayoutRead.add(wrapper);
+        liftVerticalMargins(node, wrapper);
         parent.insertBefore(wrapper, node);
         wrapper.appendChild(node);
         wrapped += 1;
     }
     return wrapped;
 }
+function setRegion(wrapper, node, spec) {
+    wrapper.setAttribute("tabindex", "0");
+    wrapper.setAttribute("role", "region");
+    wrapper.setAttribute("aria-label", spec.buildAriaLabel(node));
+}
+function clearRegion(wrapper) {
+    wrapper.removeAttribute("tabindex");
+    wrapper.removeAttribute("role");
+    wrapper.removeAttribute("aria-label");
+}
+/**
+ * Makes each wrapper a named, focusable region while its content overflows it
+ * horizontally, and a plain container otherwise.
+ *
+ * A wrapper is built as a region, because a wrapper that scrolls must be
+ * reachable by keyboard (WCAG 2.1.1) and markup wrapped off-document cannot be
+ * measured. Most never scroll: a table that fits its column, a drag tile, a
+ * layout table. Left as regions they add a tab stop and a landmark each, so the
+ * live player measures every wrapper and keeps the region only where there is
+ * something to scroll. Measurements are read for every wrapper before the first
+ * write. A wrapper holding focus keeps its region, so a sync never drops focus.
+ */
+export function syncOverwideRegions(wrappers, spec) {
+    const measured = [];
+    for (const wrapper of wrappers) {
+        if (!wrapper.isConnected)
+            continue;
+        if (!wrapper.classList.contains(spec.wrapperClass))
+            continue;
+        measured.push([wrapper, wrapper.scrollWidth > wrapper.clientWidth]);
+    }
+    for (const [wrapper, scrolls] of measured) {
+        const node = wrapper.firstElementChild;
+        if (scrolls && node?.matches(spec.selector))
+            setRegion(wrapper, node, spec);
+        else if (!scrolls && !isFocused(wrapper))
+            clearRegion(wrapper);
+    }
+}
+function isFocused(element) {
+    const root = element.getRootNode();
+    return root.activeElement === element;
+}
 /**
  * String-in / string-out wrapping, for the post-sanitization step.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "1.0.0-beta.1",
+	"version": "1.0.0-beta.3",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -33,6 +33,10 @@
 			"types": "./dist/object/index.d.ts",
 			"import": "./dist/object/index.js"
 		},
+		"./promise": {
+			"types": "./dist/promise/index.d.ts",
+			"import": "./dist/promise/index.js"
+		},
 		"./types": {
 			"types": "./dist/types/index.d.ts",
 			"import": "./dist/types/index.js"
@@ -121,12 +125,12 @@
 		"@biomejs/biome": "^2.5.15",
 		"@happy-dom/global-registrator": "^20.14.5",
 		"@pie-element/shared-math-rendering-mathjax": "0.1.4",
-		"@playwright/test": "^1.63.0",
+		"@playwright/test": "^1.64.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": "^5.57.2",
 		"svelte-check": "^4.7.6",
 		"typescript": "^5.9.3"
 	},