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

package/dist/i18n/types.d.ts

@@ -1,57 +1,206 @@
 /**
  * I18n Type Definitions
  *
- * Shared types for internationalization system.
- * Defined in players-shared to avoid circular dependencies.
+ * The provider interface and the key/locale types derived from the English
+ * catalog. Defined in `players-shared` to avoid circular dependencies, and kept
+ * free of any runtime value so a tool can reach the whole contract through
+ * `import type` and compile it away entirely.
+ *
+ * @module @pie-players/pie-players-shared/i18n/types
+ */
+import type enUS from "./messages/en-US.js";
+/**
+ * Locale tags this repository ships a catalog for.
+ *
+ * Full BCP-47 rather than bare language subtags. Content producers disagree on
+ * syntax — the Learnosity transform emits POSIX `nl_NL`, QTI catalog cards carry
+ * `xml:lang` — and the resolver normalizes both onto these, so this list is the
+ * set of catalogs, not the set of accepted inputs.
  */
+export type BundledLocaleCode = "en-US" | "nl-NL";
 /**
- * Plural translation forms
- * Follows ICU MessageFormat plural rules
+ * Any locale tag. A host may supply a locale we ship no catalog for and provide
+ * its own messages through {@link I18nConfig.customMessages}, so this is
+ * deliberately open while still autocompleting the bundled set.
+ */
+export type LocaleCode = BundledLocaleCode | (string & {});
+/**
+ * Plural translation forms, keyed by CLDR plural category.
+ *
+ * Only `other` is required. `Intl.PluralRules` selects the category for the
+ * active locale, so a locale with six forms can carry six and a locale with two
+ * carries two; a selected category the catalog lacks resolves to `other`.
  */
 export interface PluralTranslation {
     zero?: string;
-    one: string;
+    one?: string;
+    two?: string;
     few?: string;
     many?: string;
     other: string;
 }
+/** A catalog node: a leaf string, a plural group, or a namespace. */
+export type MessageNode = string | PluralTranslation | {
+    [key: string]: MessageNode;
+};
+/** A whole catalog, as one locale module default-exports it. */
+export type MessageCatalog = {
+    [key: string]: MessageNode;
+};
+type PluralCategoryKey = keyof PluralTranslation;
 /**
- * Translation bundle structure
+ * Dot-notation keys of a catalog shape.
+ *
+ * A plural group terminates the path at the group itself: `plural()` is called
+ * with `tools.textToSpeech.charactersSelected`, never with
+ * `…charactersSelected.other`. A group is recognized by every one of its keys
+ * being a CLDR plural category — the containment has to run this way round,
+ * because a group carrying only `one`/`other` does not contain the whole
+ * category union.
+ */
+type NestedKeys<T> = {
+    [K in keyof T & string]: T[K] extends string ? K : keyof T[K] extends PluralCategoryKey ? K : T[K] extends object ? K | `${K}.${NestedKeys<T[K]>}` : K;
+}[keyof T & string];
+/**
+ * Every key the English catalog defines.
+ *
+ * Derived from the catalog's shape rather than maintained alongside it, so a
+ * mistyped key is a compile error instead of a raw key rendered on screen. This
+ * is what makes the coverage script a completeness check rather than the only
+ * line of defence.
+ */
+export type MessageKey = NestedKeys<typeof enUS>;
+/**
+ * A key assembled at runtime from an id the catalog cannot enumerate — an
+ * element category, a host-authored registration's key. Branded, so the only way
+ * to produce one is `dynamicMessageKey` and a mistyped literal stays a compile
+ * error at every ordinary call site.
+ *
+ * The brand is a named property rather than a `unique symbol`: a module-local
+ * symbol is not identity-compatible across two emitted copies of this
+ * declaration, and packages here resolve `players-shared` to `src` or to `dist`
+ * depending on build order.
+ */
+export type DynamicMessageKey = string & {
+    readonly __pieDynamicMessageKey: true;
+};
+/**
+ * A key argument: a catalog key, or an explicitly-asserted computed one. The
+ * assertion lives in `provider.ts` as `dynamicMessageKey`, so this module stays
+ * type-only.
+ */
+export type MessageKeyInput = MessageKey | DynamicMessageKey;
+/** Interpolation values substituted into `{placeholder}` slots. */
+export type InterpolationValues = Record<string, string | number | boolean | null | undefined>;
+/** Options for {@link I18nProvider.plural}; `count` also interpolates. */
+export interface PluralOptions extends InterpolationValues {
+    count: number;
+}
+/** Writing direction of a locale. */
+export type TextDirection = "ltr" | "rtl";
+/**
+ * Translation bundle structure.
+ *
+ * Retained as the resolved, in-memory form of one locale's catalog.
  */
 export interface TranslationBundle {
     locale: string;
-    translations: Record<string, string | PluralTranslation>;
-    direction: "ltr" | "rtl";
+    translations: MessageCatalog;
+    direction: TextDirection;
 }
 /**
- * I18n configuration
+ * Provider configuration.
  */
 export interface I18nConfig {
-    /** Initial locale (default: browser language) */
-    locale?: string;
-    /** Fallback locale (default: 'en') */
-    fallbackLocale?: string;
-    /** Translation loader function */
-    loadTranslations?: (locale: string) => Promise<TranslationBundle>;
-    /** Bundled translations (for hybrid loading) */
-    bundledTranslations?: Record<string, TranslationBundle>;
-    /** Missing key handler */
+    /** Initial locale. Defaults to `en-US`; never auto-detected. */
+    locale?: LocaleCode;
+    /** Locale every missing key falls back to. Defaults to `en-US`. */
+    fallbackLocale?: LocaleCode;
+    /**
+     * Loader for a locale this repository ships. Omitted, only the statically
+     * bundled English catalog and any `customMessages` are available — which is
+     * exactly what a tool bundle wants, so no locale chunk is emitted into it.
+     */
+    loadCatalog?: (locale: string) => Promise<MessageCatalog>;
+    /** Locale tags {@link loadCatalog} can serve. */
+    availableLocales?: readonly string[];
+    /**
+     * Host-supplied messages, keyed by locale tag. Consulted ahead of the
+     * bundled catalog for the same locale, so a deployment can override one
+     * label without forking a catalog, and can supply a locale we do not ship.
+     */
+    customMessages?: Record<string, MessageCatalog>;
+    /** Called once per missing key per lookup. */
     onMissingKey?: (key: string, locale: string) => void;
-    /** Debug mode */
+    /** Reserved for provider-level diagnostics. */
     debug?: boolean;
 }
 /**
- * I18nService API contract
+ * The contract components resolve against.
+ *
+ * Deliberately small and free of Svelte, DOM and framework types: a component
+ * declares `i18n?: I18nProvider`, and a host is free to implement it over
+ * i18next, ICU MessageFormat or its own catalog rather than take ours.
  */
-export interface I18nServiceApi {
-    initialize(config: I18nConfig): Promise<void>;
-    t(key: string, params?: Record<string, any>): string;
-    tn(key: string, count: number, params?: Record<string, any>): string;
+export interface I18nProvider {
+    /** Active locale tag, canonicalized to the resolved catalog's tag. */
     getLocale(): string;
-    setLocale(locale: string): Promise<void>;
-    getDirection(): "ltr" | "rtl";
+    /**
+     * Switch locale, loading its catalog if a loader is configured.
+     *
+     * Subscribers are notified once the catalog is in place, so a component's
+     * reactive read re-runs against the new locale rather than the old one.
+     */
+    setLocale(locale: LocaleCode): Promise<void> | void;
+    /** Translate a key, interpolating `{placeholder}` slots. */
+    t(key: MessageKeyInput, values?: InterpolationValues): string;
+    /** Translate a plural group, selecting the category for `options.count`. */
+    plural?(key: MessageKeyInput, options: PluralOptions): string;
+    /**
+     * Writing direction of the active locale.
+     *
+     * Components stamp this onto their own host's `dir`. `direction` is an
+     * inherited CSS property, so one attribute on the host crosses a shadow
+     * boundary into the component's content with no per-node wiring.
+     */
+    getDirection?(): TextDirection;
+    /**
+     * A view of this provider fixed to another locale.
+     *
+     * Two players on one page can render different interface locales without either
+     * mutating the other's active locale. A provider that cannot produce a view
+     * omits this, and callers fall back to the provider itself.
+     */
+    withLocale?(locale: LocaleCode): I18nProvider;
+    /** Observe locale and catalog changes. Returns an unsubscribe function. */
+    subscribe?(listener: () => void): () => void;
+    /** Whether a key resolves in the active locale or its fallback chain. */
+    hasKey?(key: MessageKeyInput): boolean;
+    /** Locale tags this provider can serve. */
+    getAvailableLocales?(): string[];
+    /** Whether a locale's catalog is already resident. */
+    isLocaleLoaded?(locale: LocaleCode): boolean;
+    /** Locale-aware number formatting. */
+    formatNumber?(value: number, options?: Intl.NumberFormatOptions): string;
+    /** Locale-aware date formatting. */
+    formatDate?(date: Date, options?: Intl.DateTimeFormatOptions): string;
+}
+/**
+ * The full service surface of the bundled provider.
+ *
+ * `I18nProvider` is what components depend on; this is what the provider and
+ * the toolkit's `I18nService` wrapper implement, so the optional members above
+ * are all present here.
+ */
+export interface I18nServiceApi extends I18nProvider {
+    initialize(config: I18nConfig): Promise<void>;
+    plural(key: MessageKeyInput, options: PluralOptions): string;
+    getDirection(): TextDirection;
     getAvailableLocales(): string[];
-    isLocaleLoaded(locale: string): boolean;
+    isLocaleLoaded(locale: LocaleCode): boolean;
     subscribe(listener: () => void): () => void;
-    hasKey(key: string): boolean;
+    hasKey(key: MessageKeyInput): boolean;
+    addCustomMessages(locale: string, messages: MessageCatalog): void;
+    withLocale(locale: LocaleCode): I18nProvider;
 }
+export {};

package/dist/i18n/types.js

@@ -1,7 +1,11 @@
 /**
  * I18n Type Definitions
  *
- * Shared types for internationalization system.
- * Defined in players-shared to avoid circular dependencies.
+ * The provider interface and the key/locale types derived from the English
+ * catalog. Defined in `players-shared` to avoid circular dependencies, and kept
+ * free of any runtime value so a tool can reach the whole contract through
+ * `import type` and compile it away entirely.
+ *
+ * @module @pie-players/pie-players-shared/i18n/types
  */
 export {};

package/dist/index.d.ts

@@ -6,9 +6,11 @@ export * from "./security/index.js";
 export * from "./loaders/index.js";
 export * from "./object/index.js";
 export * from "./pie/index.js";
-export type { AssessmentEntity, AssessmentItemRef, AssessmentSection, AdvancedItemConfig, ConfigEntity, ConfigResource, Env, ItemConfig, ItemEntity, ItemSession, OutcomeResponse, PassageEntity, PieController, PieContent, PieDefaultModel, PieItemElement, PieModel, QuestionEntity, RubricBlock, TestPart, } from "./types/index.js";
+export type { AssessmentEntity, AssessmentItemRef, AssessmentSection, AdvancedItemConfig, ConfigEntity, ConfigResource, Env, FormativeDeliveryPolicy, FormativeItemPolicy, TimedMediaSectionData, ItemConfig, ItemEntity, ItemSession, OutcomeResponse, PassageEntity, PieController, PieContent, PieDefaultModel, PieItemElement, PieModel, QuestionEntity, RubricBlock, TestPart, } from "./types/index.js";
 export { editorPostFix } from "./types/index.js";
+export * from "./ui/attribute-coercion.js";
 export * from "./ui/content-styles.js";
+export * from "./ui/pointer-drag.js";
 export * from "./ui/focus-trap.js";
 export * from "./ui/first-focusable.js";
 export * from "./ui/debug-panel-persistence.js";

package/dist/index.js

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

package/dist/pie/custom-element-define.d.ts

@@ -3,4 +3,28 @@ export type SafeDefineResult = {
     status: SafeDefineStatus;
     tagName: string;
 };
+export type SafeDefineOutcome = "defined" | "already-defined" | "defined-wrapped" | "error" | "wrapped-error";
+export interface SafeDefineAttempt {
+    outcome: SafeDefineOutcome;
+    tagName: string;
+    error?: unknown;
+}
+export interface AttemptCustomElementDefineOptions {
+    /**
+     * The browser rejects registering a constructor that's already
+     * registered under a different tag name with the same
+     * `NotSupportedError` used for a duplicate *tag* registration. When set,
+     * a collision that isn't actually a same-tag duplicate (`customElements.get`
+     * still doesn't return the tag after the failed define) is retried once
+     * with a distinct wrapper subclass so this tag name still ends up defined.
+     */
+    allowWrappedFallback?: boolean;
+}
+/**
+ * Attempt to define a custom element, classifying the outcome instead of
+ * throwing, so callers with different error-surfacing conventions (throw vs.
+ * record-and-continue) can build their own public behavior on one shared
+ * duplicate-define/collision core.
+ */
+export declare const attemptCustomElementDefine: (tagName: string, elementConstructor: CustomElementConstructor, context?: string, options?: AttemptCustomElementDefineOptions) => SafeDefineAttempt;
 export declare const defineCustomElementSafely: (tagName: string, elementConstructor: CustomElementConstructor, context?: string) => SafeDefineResult;

package/dist/pie/custom-element-define.js

@@ -9,22 +9,52 @@ const isDuplicateDefineError = (error) => {
         : "";
     return maybeName === "NotSupportedError";
 };
-export const defineCustomElementSafely = (tagName, elementConstructor, context = "custom element tag") => {
+/**
+ * Attempt to define a custom element, classifying the outcome instead of
+ * throwing, so callers with different error-surfacing conventions (throw vs.
+ * record-and-continue) can build their own public behavior on one shared
+ * duplicate-define/collision core.
+ */
+export const attemptCustomElementDefine = (tagName, elementConstructor, context = "custom element tag", options = {}) => {
     const validTagName = validateCustomElementTag(tagName, context);
     if (customElements.get(validTagName)) {
-        return { status: "already-defined", tagName: validTagName };
+        return { outcome: "already-defined", tagName: validTagName };
     }
     try {
         customElements.define(validTagName, elementConstructor);
-        return { status: "defined", tagName: validTagName };
+        return { outcome: "defined", tagName: validTagName };
     }
     catch (error) {
         if (!isDuplicateDefineError(error)) {
-            throw error;
+            return { outcome: "error", tagName: validTagName, error };
         }
         if (customElements.get(validTagName)) {
-            return { status: "already-defined", tagName: validTagName };
+            return { outcome: "already-defined", tagName: validTagName };
+        }
+        if (!options.allowWrappedFallback) {
+            return { outcome: "error", tagName: validTagName, error };
+        }
+        try {
+            customElements.define(validTagName, class extends elementConstructor {
+            });
+            return { outcome: "defined-wrapped", tagName: validTagName };
+        }
+        catch (wrappedError) {
+            return {
+                outcome: "wrapped-error",
+                tagName: validTagName,
+                error: wrappedError,
+            };
         }
-        throw error;
     }
 };
+export const defineCustomElementSafely = (tagName, elementConstructor, context = "custom element tag") => {
+    const attempt = attemptCustomElementDefine(tagName, elementConstructor, context);
+    if (attempt.outcome === "error" || attempt.outcome === "wrapped-error") {
+        throw attempt.error;
+    }
+    return {
+        status: attempt.outcome === "already-defined" ? "already-defined" : "defined",
+        tagName: attempt.tagName,
+    };
+};

package/dist/pie/index.d.ts

@@ -36,7 +36,7 @@ export { pieRegistry } from "./registry.js";
 export { findPieController, scorePieItem } from "./scoring.js";
 export type { Entry, EventListeners, EventListenersMap, LoadPieElementsOptions, PieElement, PieRegistry, UpdatePieElementOptions, } from "./types.js";
 export { BundleType, defaultPieElementOptions, isCustomElementConstructor, isPieAvailable, isPieRegistryAvailable, Status, } from "./types.js";
-export { defineCustomElementSafely, type SafeDefineResult, type SafeDefineStatus, } from "./custom-element-define.js";
+export { attemptCustomElementDefine, defineCustomElementSafely, type AttemptCustomElementDefineOptions, type SafeDefineAttempt, type SafeDefineOutcome, type SafeDefineResult, type SafeDefineStatus, } from "./custom-element-define.js";
 export { toPrintHashedTag, toViewTag, validateCustomElementTag, VIEW_TAG_SUFFIX, } from "./tag-names.js";
 export type { PieViewMode } from "./tag-names.js";
 export { updatePieElement, updatePieElements, updatePieElementWithRef, } from "./updates.js";

package/dist/pie/index.js

@@ -37,7 +37,7 @@ export { BundleType, defaultPieElementOptions, isCustomElementConstructor,
 // Type guards (functions)
 isPieAvailable, isPieRegistryAvailable, Status, } from "./types.js";
 // Tag naming helpers
-export { defineCustomElementSafely, } from "./custom-element-define.js";
+export { attemptCustomElementDefine, defineCustomElementSafely, } from "./custom-element-define.js";
 export { toPrintHashedTag, toViewTag, validateCustomElementTag, VIEW_TAG_SUFFIX, } from "./tag-names.js";
 // Updates
 export { updatePieElement, updatePieElements, updatePieElementWithRef, } from "./updates.js";

package/dist/pie/versioned-tag.js

@@ -27,8 +27,9 @@ export function parseVersionedTagName(tagName) {
 export function toPackageVersionedTag(tagName, packageSpec, options = {}) {
     const { version } = parsePackageName(packageSpec);
     if (!version.trim() && options.preserveUnversionedTag) {
-        // aggregateElements historically kept unversioned package specs on their
-        // authored tag. Preserve that caller-specific behavior.
+        // pie-item contract compatibility: aggregateElements historically kept
+        // unversioned package specs on their authored tag; already-authored item
+        // content with no version pinned must keep rendering under that tag.
         return tagName;
     }
     const targetEncodedVersion = encodeVersionForTag(version);

package/dist/security/sanitize-forbidden-lists.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared DOMPurify forbid-lists for every in-repo sanitizer (item/passage
+ * markup, SVG icons). Keeping one canonical list means a newly-identified
+ * dangerous tag or attribute only needs to be added once to cover every
+ * sanitizer instead of drifting between hand-maintained copies.
+ */
+export declare const SANITIZER_FORBIDDEN_TAGS: string[];
+export declare const SANITIZER_FORBIDDEN_ATTRS: string[];

package/dist/security/sanitize-forbidden-lists.js

@@ -0,0 +1,41 @@
+/**
+ * Shared DOMPurify forbid-lists for every in-repo sanitizer (item/passage
+ * markup, SVG icons). Keeping one canonical list means a newly-identified
+ * dangerous tag or attribute only needs to be added once to cover every
+ * sanitizer instead of drifting between hand-maintained copies.
+ */
+export const SANITIZER_FORBIDDEN_TAGS = [
+    "script",
+    "iframe",
+    "object",
+    "embed",
+    "base",
+    "form",
+    "meta",
+    "link",
+    // <foreignObject> inside an <svg> is a well-known escape hatch back into
+    // HTML context.
+    "foreignobject",
+];
+// DOMPurify already strips `on*` handlers via its default block-list; these
+// entries guarantee they stay stripped even if a consumer tweaks defaults,
+// and they cover the common SVG / math sinks.
+export const SANITIZER_FORBIDDEN_ATTRS = [
+    "onerror",
+    "onload",
+    "onclick",
+    "onmouseover",
+    "onmouseout",
+    "onmouseenter",
+    "onmouseleave",
+    "onfocus",
+    "onblur",
+    "onkeydown",
+    "onkeyup",
+    "onkeypress",
+    "onsubmit",
+    "onchange",
+    "onbeforeunload",
+    "formaction",
+    "xlink:href",
+];

package/dist/security/sanitize-item-markup.js

@@ -8,6 +8,7 @@
  * allow-list.
  */
 import DOMPurify from "dompurify";
+import { SANITIZER_FORBIDDEN_ATTRS, SANITIZER_FORBIDDEN_TAGS, } from "./sanitize-forbidden-lists.js";
 import { wrapOverwideImages } from "./wrap-overwide-images.js";
 import { wrapOverwideTables } from "./wrap-overwide-tables.js";
 // Attributes every PIE element / wrapper is allowed to carry.
@@ -28,42 +29,8 @@ const BASE_ALLOWED_ATTRS = [
     "dir",
 ];
 const BASE_URI_SAFE_ATTRS = ["pie-id"];
-const FORBIDDEN_TAGS = [
-    "script",
-    "iframe",
-    "object",
-    "embed",
-    "base",
-    "form",
-    "meta",
-    "link",
-    // <foreignObject> inside an <svg> is a well-known escape hatch back
-    // into HTML context; match the SVG-icon sanitizer and forbid it here
-    // so both sanitizers agree on the surface.
-    "foreignobject",
-];
-// DOMPurify already strips `on*` handlers via its default block-list;
-// these entries guarantee they stay stripped even if a consumer tweaks
-// defaults, and they cover the common SVG / math sinks.
-const FORBIDDEN_ATTRS = [
-    "onerror",
-    "onload",
-    "onclick",
-    "onmouseover",
-    "onmouseout",
-    "onmouseenter",
-    "onmouseleave",
-    "onfocus",
-    "onblur",
-    "onkeydown",
-    "onkeyup",
-    "onkeypress",
-    "onsubmit",
-    "onchange",
-    "onbeforeunload",
-    "formaction",
-    "xlink:href",
-];
+const FORBIDDEN_TAGS = SANITIZER_FORBIDDEN_TAGS;
+const FORBIDDEN_ATTRS = SANITIZER_FORBIDDEN_ATTRS;
 // Any tag that looks like a custom element (contains a hyphen) is permitted
 // provided it starts with `pie-` or is explicitly named in
 // `allowedCustomElements`. This intentionally keeps third-party unknown

package/dist/security/sanitize-svg-icon.js

@@ -10,6 +10,7 @@
  * or the input is not a string.
  */
 import DOMPurify from "dompurify";
+import { SANITIZER_FORBIDDEN_ATTRS, SANITIZER_FORBIDDEN_TAGS, } from "./sanitize-forbidden-lists.js";
 let svgPurifierInstance = null;
 function resolveSvgPurifier() {
     if (svgPurifierInstance)
@@ -23,31 +24,8 @@ function resolveSvgPurifier() {
             : DOMPurify;
     return svgPurifierInstance;
 }
-const FORBIDDEN_TAGS = [
-    "script",
-    "foreignobject",
-    "iframe",
-    "object",
-    "embed",
-    "base",
-    "form",
-];
-const FORBIDDEN_ATTRS = [
-    "onerror",
-    "onload",
-    "onclick",
-    "onmouseover",
-    "onmouseout",
-    "onmouseenter",
-    "onmouseleave",
-    "onfocus",
-    "onblur",
-    "onkeydown",
-    "onkeyup",
-    "onkeypress",
-    "formaction",
-    "xlink:href",
-];
+const FORBIDDEN_TAGS = SANITIZER_FORBIDDEN_TAGS;
+const FORBIDDEN_ATTRS = SANITIZER_FORBIDDEN_ATTRS;
 const stringCache = new Map();
 const STRING_CACHE_MAX = 64;
 export function sanitizeSvgIcon(icon) {

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

@@ -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 table
+ * wrapper: only the four values below and the accessible name differ.
  */
-export interface WrapOverwideImagesInElementOptions {
-    /**
-     * When `true`, images whose nearest `pie-*` ancestor is *strictly between*
-     * the image 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
-     * images.
-     */
-    skipPieDescendants?: boolean;
-}
+import { type WrapOverwideOptions } from "./wrap-overwide.js";
+export type WrapOverwideImagesInElementOptions = WrapOverwideOptions;
 /**
  * Wrap every unwrapped `<img>` descendant of `root` with the shared
  * horizontal-scroll span. Returns the number of newly-wrapped images so