@pie-players/pie-players-shared 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/pie/math-rendering.d.ts

@@ -13,6 +13,16 @@ export interface MathRenderingAPI {
     unWrapMath?: (wrapped: string) => string;
     mmlToLatex?: (mathml: string) => string;
 }
+/** How the default renderer `initializeMathRendering` installs loads its assets. */
+export interface MathRenderingOptions {
+    /**
+     * The npm root the renderer's speech rules load from when the page's math
+     * options set no `assetRoot`. With neither, jsDelivr. A page that names the
+     * rules' directory itself, in `SREfeature.json` or a `text/x-sre-config`
+     * block, keeps it.
+     */
+    assetRoot?: string;
+}
 /**
  * The page's renderer: the one `initializeMathRendering` installed, or a
  * host's. IIFE elements render with it, and so do ESM elements when the page
@@ -27,6 +37,8 @@ export declare const getMathRenderer: () => MathRenderingAPI | null;
  * - window["@pie-lib/math-rendering"] (standard key)
  * - window["_dll_pie_lib__math_rendering"] (SystemJS/DLL key for IIFE bundles)
  *
+ * The first call installs the renderer for the page, so its `options` apply.
+ *
  * @example
  * ```typescript
  * // Default MathJax
@@ -37,7 +49,7 @@ export declare const getMathRenderer: () => MathRenderingAPI | null;
  * await initializeMathRendering();
  * ```
  */
-export declare function initializeMathRendering(): Promise<void>;
+export declare function initializeMathRendering(options?: MathRenderingOptions): Promise<void>;
 /**
  * Set custom math renderer programmatically
  *

package/dist/pie/math-rendering.js

@@ -8,6 +8,7 @@
  */
 /// <reference path="../shims.d.ts" />
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
+import { pageMathAssetRoot } from "./math-assets.js";
 const GLOBAL_KEY = "@pie-lib/math-rendering";
 const GLOBAL_DLL_KEY = "_dll_pie_lib__math_rendering";
 // Every copy of @pie-lib/math-rendering on a page typesets through the MathJax
@@ -15,6 +16,52 @@ const GLOBAL_DLL_KEY = "_dll_pie_lib__math_rendering";
 const SHARED_INSTANCE_KEY = "@pie-lib/math-rendering@2";
 let initPromise = null;
 const logger = createPieLogger("math-rendering", () => isGlobalDebugEnabled());
+/**
+ * The speech-rule-engine version the default renderer bundles, whose rules it
+ * loads from `speech-rule-engine@<version>/lib/mathmaps` under an npm root. A
+ * test pins it to the module.
+ * @internal
+ */
+export const DEFAULT_RENDERER_SRE_VERSION = "4.1.2";
+const SRE_FEATURE_KEY = "SREfeature";
+const pageNamesSpeechRules = () => {
+    const feature = window[SRE_FEATURE_KEY];
+    if (feature && typeof feature === "object" && feature.json)
+        return true;
+    return Array.from(document.querySelectorAll('script[type="text/x-sre-config"]')).some((block) => {
+        try {
+            return !!JSON.parse(block.textContent || "")?.json;
+        }
+        catch {
+            return false;
+        }
+    });
+};
+/**
+ * Points the module's speech-rule-engine at the rules under `root` and returns
+ * the undo. SRE reads `SREfeature` as it sets up, synchronously while the
+ * module evaluates, and its later setups keep the path, so the global is
+ * restored afterwards: another copy of SRE on the page, as a legacy bundle
+ * carries, keeps the rules of its own version.
+ */
+const pointSpeechRulesAt = (root) => {
+    if (!root || typeof document === "undefined" || pageNamesSpeechRules()) {
+        return () => { };
+    }
+    const host = window;
+    const had = Object.hasOwn(host, SRE_FEATURE_KEY);
+    const previous = host[SRE_FEATURE_KEY];
+    host[SRE_FEATURE_KEY] = {
+        ...(previous && typeof previous === "object" ? previous : {}),
+        json: `${root.replace(/\/+$/, "")}/speech-rule-engine@${DEFAULT_RENDERER_SRE_VERSION}/lib/mathmaps`,
+    };
+    return () => {
+        if (had)
+            host[SRE_FEATURE_KEY] = previous;
+        else
+            delete host[SRE_FEATURE_KEY];
+    };
+};
 /**
  * The page's renderer: the one `initializeMathRendering` installed, or a
  * host's. IIFE elements render with it, and so do ESM elements when the page
@@ -66,6 +113,8 @@ const createSharedInstance = (renderer) => {
  * - window["@pie-lib/math-rendering"] (standard key)
  * - window["_dll_pie_lib__math_rendering"] (SystemJS/DLL key for IIFE bundles)
  *
+ * The first call installs the renderer for the page, so its `options` apply.
+ *
  * @example
  * ```typescript
  * // Default MathJax
@@ -76,7 +125,7 @@ const createSharedInstance = (renderer) => {
  * await initializeMathRendering();
  * ```
  */
-export async function initializeMathRendering() {
+export async function initializeMathRendering(options = {}) {
     // Only run in browser
     if (typeof window === "undefined") {
         return;
@@ -90,6 +139,7 @@ export async function initializeMathRendering() {
         return;
     }
     initPromise = (async () => {
+        const restoreSpeechRules = pointSpeechRulesAt(pageMathAssetRoot() ?? options.assetRoot);
         try {
             // The package has no exports map, so the file is named in full for
             // resolvers that do not complete a directory, such as webpack's
@@ -112,6 +162,9 @@ export async function initializeMathRendering() {
             logger.error("Failed to initialize math rendering:", error);
             throw error;
         }
+        finally {
+            restoreSpeechRules();
+        }
     })();
     try {
         await initPromise;

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/dist/types/index.d.ts

@@ -557,6 +557,10 @@ export interface ToolParameterMap {
         pitch?: number;
         volume?: number;
     };
+    /** `zoom` is the lens's starting magnification, 2 meaning twice the size. */
+    magnification: {
+        zoom?: number;
+    };
 }
 /** The parameter shape of tool `K`: its {@link ToolParameterMap} entry, else open. */
 export type ToolParametersFor<K extends string> = K extends keyof ToolParameterMap ? ToolParameterMap[K] : Record<string, unknown>;
@@ -582,6 +586,14 @@ export interface Env {
     mode: PlayerMode;
     role: PlayerRole;
     partialScoring?: boolean;
+    /**
+     * BCP 47 tag of the language the item's content is written in, when the
+     * delivery knows it. The player reflects it onto the content subtree as
+     * `lang`/`dir`; a host that emits nothing leaves the content unstamped.
+     * The interface locale never travels here — it is the player's `locale`
+     * attribute and the `pie.interfaceLocale` context.
+     */
+    locale?: string;
 }
 /** The `detail` of the `player-error` event `pie-item-player` dispatches. */
 export interface PieItemPlayerErrorDetail {

package/dist/ui/focus-trap.d.ts

@@ -24,4 +24,16 @@ type FocusTrapOptions = {
  * and restores prior focus when the trap is removed.
  */
 export declare function createFocusTrap(container: HTMLElement, options?: FocusTrapOptions): () => void;
+/**
+ * Returns focus to where it was before a tool took it, for a tool that closes
+ * itself: the tool's element leaves the DOM on close, which drops focus to the
+ * document body. `capture` runs as the tool takes focus and `restore` as it
+ * closes, before its element goes.
+ */
+export declare function createFocusReturn(): {
+    /** Records the focused element, unless focus is already inside `container`. */
+    capture: (container: Node) => void;
+    /** Focuses the recorded element, if it is still in the document. */
+    restore: () => void;
+};
 export {};

package/dist/ui/focus-trap.js

@@ -44,7 +44,11 @@ export function createFocusTrap(container, options = {}) {
     const wrap = options.wrap ?? true;
     const onKeydown = (event) => {
         if (event.key === "Escape") {
-            options.onEscape?.();
+            if (!options.onEscape)
+                return;
+            // Claimed, so a page-wide Escape listener does not also act on it.
+            event.preventDefault();
+            options.onEscape();
             return;
         }
         if (event.key !== "Tab")
@@ -94,3 +98,37 @@ export function createFocusTrap(container, options = {}) {
         }
     };
 }
+/**
+ * Returns focus to where it was before a tool took it, for a tool that closes
+ * itself: the tool's element leaves the DOM on close, which drops focus to the
+ * document body. `capture` runs as the tool takes focus and `restore` as it
+ * closes, before its element goes.
+ */
+export function createFocusReturn() {
+    let opener = null;
+    return {
+        capture(container) {
+            if (typeof document === "undefined")
+                return;
+            const active = getDeepActiveElement(document);
+            if (active && container.contains(active))
+                return;
+            opener =
+                active instanceof HTMLElement && active !== document.body
+                    ? active
+                    : null;
+        },
+        restore() {
+            const target = opener;
+            opener = null;
+            if (!target?.isConnected)
+                return;
+            try {
+                target.focus();
+            }
+            catch {
+                // ignore
+            }
+        },
+    };
+}

package/dist/ui/overlay-containment.d.ts

@@ -17,6 +17,11 @@ export interface Point {
     x: number;
     y: number;
 }
+/** A box on screen: its top-left corner and its extent, as a `DOMRect` gives them. */
+export interface ScreenBox extends Size {
+    left: number;
+    top: number;
+}
 /**
  * The box `element` resolves its `left`/`top` against: its containing block, or
  * the viewport when that is the initial containing block.
@@ -77,3 +82,11 @@ export declare function uprightDockCentre(box: Size, strip: Size, degrees: numbe
  * where a box exceeds its block and centres on the offending axis.
  */
 export declare function clampPointWithinBlock(point: Point, box: Size, block: Size, gutter?: number): Point;
+/**
+ * The top-left corner, in viewport coordinates, of a control strip docked
+ * beside an upright `tool`: centred below it, or above it when only the space
+ * above holds the strip, and slid along the tool's edge to stay inside the
+ * block. A strip that fits on neither side takes the roomier one; a strip wider
+ * than the block centres on it.
+ */
+export declare function uprightDockCorner(tool: ScreenBox, strip: Size, block: ScreenBox, gap: number, gutter?: number): Point;

package/dist/ui/overlay-containment.js

@@ -126,3 +126,26 @@ export function clampPointWithinBlock(point, box, block, gutter = DEFAULT_CONTAI
     const offset = clampOffsetWithinBlock({ x: point.x - centre.x, y: point.y - centre.y }, box, block, gutter);
     return { x: centre.x + offset.x, y: centre.y + offset.y };
 }
+/**
+ * The top-left corner, in viewport coordinates, of a control strip docked
+ * beside an upright `tool`: centred below it, or above it when only the space
+ * above holds the strip, and slid along the tool's edge to stay inside the
+ * block. A strip that fits on neither side takes the roomier one; a strip wider
+ * than the block centres on it.
+ */
+export function uprightDockCorner(tool, strip, block, gap, gutter = DEFAULT_CONTAINMENT_GUTTER) {
+    const top = block.top + gutter;
+    const bottom = block.top + block.height - gutter;
+    const below = tool.top + tool.height + gap;
+    const above = tool.top - gap - strip.height;
+    const roomBelow = bottom - below;
+    const roomAbove = tool.top - gap - top;
+    const y = roomBelow >= strip.height || (roomAbove < strip.height && roomBelow >= roomAbove)
+        ? below
+        : above;
+    const travel = block.width - gutter * 2 - strip.width;
+    const x = travel <= 0
+        ? block.left + (block.width - strip.width) / 2
+        : Math.max(block.left + gutter, Math.min(block.left + gutter + travel, tool.left + (tool.width - strip.width) / 2));
+    return { x, y };
+}

package/dist/ui/overlay-placement.d.ts

@@ -53,6 +53,34 @@ export type OverlayPlacementNudge = keyof typeof OVERLAY_PLACEMENT_NUDGES;
 export type OverlayPlacementAnnouncement = (typeof OVERLAY_PLACEMENT_NUDGES)[OverlayPlacementNudge]["announceKey"] | "toolkit.announce.rotatedTo";
 /** The tap controls' rotations, the keyboard's two steps each way. */
 export declare const OVERLAY_PLACEMENT_ROTATIONS: readonly [number, number, 1, 5];
+/**
+ * What the tap controls drive: a step for each arrow, and a turn for a tool
+ * that rotates. An `OverlayPlacementController` is one; an upright tool that
+ * keeps its own position supplies `nudge` alone.
+ */
+export interface OverlayTapTarget {
+    nudge: (direction: OverlayPlacementNudge) => void;
+    rotateBy?: (degrees: number) => void;
+}
+/** A shrink-and-grow pair on the tap controls, labelled by the tool. */
+export interface OverlaySizeControl {
+    shrink: {
+        glyph: string;
+        label: string;
+    };
+    grow: {
+        glyph: string;
+        label: string;
+    };
+    step: (direction: 1 | -1) => void;
+}
+/**
+ * Docks an upright tool's tap controls beside it, as `uprightDockCorner`
+ * places them. `OverlayPlacementControls` lays the controls out at the tool's
+ * top-left corner, so the offset is taken from there. A strip wider than the
+ * block wraps onto more rows, so a phone-width pane does not clip it.
+ */
+export declare function dockUprightControls(element: HTMLElement, controls: HTMLElement): void;
 export interface OverlayPlacementOptions {
     /** The tool's positioned element, which receives the transform. */
     getElement: () => HTMLElement | undefined;

package/dist/ui/overlay-placement.js

@@ -4,7 +4,7 @@
  * its `style.transform`, so a drag, an arrow key and a tap control always agree
  * about where the tool is.
  */
-import { clampOffsetOverlappingBlock, resolveContainingBlockRect, rotatedExtent, rotationCentreShift, uprightDockCentre, } from "./overlay-containment.js";
+import { clampOffsetOverlappingBlock, DEFAULT_CONTAINMENT_GUTTER, resolveContainingBlockRect, rotatedExtent, rotationCentreShift, uprightDockCentre, uprightDockCorner, } from "./overlay-containment.js";
 import { createPointerDragController } from "./pointer-drag.js";
 import { createPointerGesture } from "./pointer-gesture.js";
 import { createPointerRotateController } from "./pointer-rotate.js";
@@ -60,8 +60,23 @@ const ARROW_KEYS = {
 };
 /** Pixels of the tool kept inside its containing block on each axis. */
 const MIN_VISIBLE = 100;
-/** Space between the tool's bottom edge and its tap controls. */
+/** Space between the tool and its tap controls. */
 const CONTROLS_GAP = 8;
+/**
+ * Docks an upright tool's tap controls beside it, as `uprightDockCorner`
+ * places them. `OverlayPlacementControls` lays the controls out at the tool's
+ * top-left corner, so the offset is taken from there. A strip wider than the
+ * block wraps onto more rows, so a phone-width pane does not clip it.
+ */
+export function dockUprightControls(element, controls) {
+    const block = resolveContainingBlockRect(element);
+    if (!block)
+        return;
+    controls.style.maxWidth = `${Math.max(0, block.width - DEFAULT_CONTAINMENT_GUTTER * 2)}px`;
+    const tool = element.getBoundingClientRect();
+    const corner = uprightDockCorner(tool, { width: controls.offsetWidth, height: controls.offsetHeight }, block, CONTROLS_GAP);
+    controls.style.transform = `translate(${corner.x - tool.left - element.clientLeft}px, ${corner.y - tool.top - element.clientTop}px)`;
+}
 export function createOverlayPlacement(options) {
     let placement = { x: 0, y: 0, rotation: 0 };
     const sizeOf = (element) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "1.0.0-beta.2",
+	"version": "1.0.0-beta.4",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -106,9 +106,9 @@
 		"dist"
 	],
 	"dependencies": {
-		"@pie-element/shared-utils": "0.1.3",
+		"@pie-element/shared-utils": "0.1.4",
 		"@pie-lib/math-rendering-module": "6.0.0",
-		"dompurify": "^3.4.16",
+		"dompurify": "^3.4.17",
 		"semver": "^7.8.5"
 	},
 	"scripts": {
@@ -125,7 +125,7 @@
 		"@biomejs/biome": "^2.5.15",
 		"@happy-dom/global-registrator": "^20.14.5",
 		"@pie-element/shared-math-rendering-mathjax": "0.1.4",
-		"@playwright/test": "^1.64.0",
+		"@playwright/test": "^1.64.1",
 		"@types/semver": "^7.8.0",
 		"es-module-shims": "^2.8.4",
 		"esbuild": "^0.28.2",