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

package/dist/timed-media/types.js

@@ -0,0 +1,12 @@
+/**
+ * Timed-media section vocabulary.
+ *
+ * A **Cue** is a window on a media timeline that activates one or more of the
+ * section's item refs. A **Media Time Source** is the port the section reaches
+ * media through — never a library API, so a host can supply its own media
+ * element without shipping a PIE element.
+ *
+ * See `docs/prds/timed-media-section-contract.md` for the ratified contract and
+ * `docs/architecture/timed-media-section.md` for the layer-ownership record.
+ */
+export {};

package/dist/tools/term-lookup.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Term lookup, shared by the dictionary tools.
+ *
+ * A dictionary and a picture dictionary differ only in what a result carries: one
+ * returns definitions, the other pictures. Everything up to that point is the same
+ * concern — normalising what a text selection dragged in, deciding whether a term is
+ * worth a request, telling "no entry for this word" apart from "the service did not
+ * answer", and not letting a superseded lookup overwrite a newer one's state. That is
+ * the part worth getting right once and testing without a browser, so it lives here
+ * and each tool supplies only its item reader.
+ *
+ * Nothing here names a capability or a service. PIE ships no dictionary endpoint: the
+ * corpus behind one is licensed per programme, so a host supplies either an endpoint
+ * or a resolver of its own.
+ */
+/** What a host's term service is asked for. */
+export interface TermLookupRequest {
+    /** The term, already normalised by {@link normalizeTerm}. */
+    keyword: string;
+    /** BCP-47 tag the learner is reading in, when the host declares one. */
+    language?: string;
+    /** Upper bound on items, so a host cannot be made to return an unbounded page. */
+    max?: number;
+}
+/**
+ * A lookup outcome, as a discriminated union.
+ *
+ * `empty` and `error` are separate states because they need different words in front
+ * of a learner: one means the service has no entry for what they selected, the other
+ * means it did not answer. Collapsing them tells a learner their word is not real
+ * when the network is down.
+ */
+export type TermLookupResult<TItem> = {
+    status: "ok";
+    items: TItem[];
+} | {
+    status: "empty";
+} | {
+    status: "error";
+    reason: string;
+};
+export type TermLookup<TItem> = (request: TermLookupRequest, signal?: AbortSignal) => Promise<TermLookupResult<TItem>>;
+/** Longest term worth sending. Past this it is prose, not a headword. */
+export declare const MAX_LOOKUP_TERM_LENGTH = 80;
+/** Words a term may span. Generous enough for `carbon dioxide` and `mother in law`. */
+export declare const MAX_LOOKUP_TERM_WORDS = 4;
+/**
+ * Collapse whitespace and strip the punctuation a text selection drags along.
+ *
+ * A learner double-clicking a word at the end of a sentence selects `"reason."`, and
+ * a drag across a line break selects `"photo-\nsynthesis"`. Leading and trailing
+ * punctuation goes; internal hyphens and apostrophes stay, because `mother-in-law`
+ * and `don't` are the entries.
+ */
+export declare function normalizeTerm(raw: string): string;
+/**
+ * Whether a normalised term is worth sending.
+ *
+ * A whole sentence is not a lookup, and sending it wastes a request that will miss.
+ */
+export declare function isLookupableTerm(term: string): boolean;
+/**
+ * Read a host payload into a result.
+ *
+ * `keys` are the payload fields to accept the item array under, in order, so a tool
+ * can take more than one spelling of the same field. Unknown extra fields are ignored
+ * rather than rejected, so a host can extend its payload without this package having
+ * to agree first. An item its reader rejects is dropped rather than failing the whole
+ * response: one malformed entry should not cost the learner the others.
+ */
+export declare function readTermLookupPayload<TItem>(payload: unknown, args: {
+    /** Names the service in messages a learner reads, e.g. `"dictionary"`. */
+    serviceLabel: string;
+    keys: readonly string[];
+    toItem: (value: unknown) => TItem | null;
+}): TermLookupResult<TItem>;
+/**
+ * A lookup that POSTs to a host endpoint.
+ *
+ * `credentials: "same-origin"` by default. The endpoint a host names is expected to
+ * sit behind the same session boundary as the assessment itself, so the session
+ * cookie is exactly what authorises it and requiring a host to wire a token to get
+ * its own already-authenticated route to answer is a configuration step it would
+ * reasonably forget. Cross-origin requests still send nothing. A host that authorises
+ * some other way passes `headers`, and one that wants no ambient credentials at all
+ * passes `credentials: "omit"`.
+ */
+export declare function createEndpointTermLookup<TItem>(args: {
+    endpoint: string;
+    /** Names the service in messages a learner reads, e.g. `"dictionary"`. */
+    serviceLabel: string;
+    /** Reads a host payload into a result; usually {@link readTermLookupPayload}. */
+    readResponse: (payload: unknown) => TermLookupResult<TItem>;
+    headers?: () => Promise<Record<string, string>> | Record<string, string>;
+    credentials?: RequestCredentials;
+    fetchImpl?: typeof fetch;
+}): TermLookup<TItem>;
+/** What a term panel is showing. */
+export type TermPanelState<TItem> = {
+    kind: "unconfigured";
+} | {
+    kind: "idle";
+} | {
+    kind: "searching";
+    term: string;
+} | {
+    kind: "results";
+    term: string;
+    items: TItem[];
+} | {
+    kind: "empty";
+    term: string;
+} | {
+    kind: "error";
+    term: string;
+    reason: string;
+};
+/** Shown when the learner sends something that is not a headword. */
+export declare const NOT_A_TERM_REASON = "Look up a single word or short phrase.";
+export interface TermLookupSessionOptions<TItem> {
+    /**
+     * Read at call time rather than captured, so a resolver that arrives after mount —
+     * a host setting `endpoint` on a live element — is picked up without a remount.
+     */
+    resolver: () => TermLookup<TItem> | null;
+    max: number;
+    language?: () => string | undefined;
+    /** Applied on every transition. The component holds the state; this drives it. */
+    onState: (state: TermPanelState<TItem>) => void;
+}
+/**
+ * The lookup half of a term panel: request sequencing and state transitions, with no
+ * framework reactivity of its own.
+ *
+ * Deliberately not a rune module. Rune modules in this package are source-only and
+ * each consumer has to alias them in its own Vite and TypeScript config; a plain
+ * class costs a caller one `$state` field instead, and is unit-testable directly.
+ */
+export declare class TermLookupSession<TItem> {
+    #private;
+    private readonly options;
+    constructor(options: TermLookupSessionOptions<TItem>);
+    get searchedFor(): string;
+    /**
+     * Reconcile the unconfigured notice with whether a resolver exists.
+     *
+     * A tool with nowhere to look words up says so, rather than offering a field that
+     * silently fails: the host has misconfigured it and the learner needs to know it is
+     * not their typing. Called with the current state because it only ever moves
+     * between `idle` and `unconfigured` — a resolver arriving mid-lookup must not
+     * discard results the learner is reading.
+     */
+    syncConfigured(current: TermPanelState<TItem>): void;
+    /**
+     * Run a term handed in from outside, at most once per request.
+     *
+     * Keyed on the request's identity, not on the term or on what was last searched.
+     * Both of the alternatives are wrong in a way a learner meets: keying on the term
+     * means selecting a word, typing another into the field, then selecting the first
+     * word again does nothing, because the incoming term never changed; keying on
+     * {@link searchedFor} means every reopen re-issues the stale selection and discards
+     * the lookup the learner typed. An id that changes per request says what both are
+     * guessing at.
+     *
+     * A request with no id falls back to the term, which is the best available identity
+     * when the caller cannot mint one — a host assigning `term` directly, for instance.
+     *
+     * Returns whether it issued a lookup, so a caller can mirror the term into its own
+     * field only when one ran.
+     */
+    syncRequestedTerm(request: {
+        term: string;
+        requestId?: string | number;
+        visible: boolean;
+    }): boolean;
+    run(raw: string): Promise<void>;
+}
+/**
+ * The panel's live-region text.
+ *
+ * Only the states a learner is waiting on announce. `idle`, `unconfigured` and
+ * `error` are already rendered as visible text in the panel body, and repeating them
+ * here would announce the same sentence twice.
+ */
+export declare function termPanelStatusMessage<TItem>(state: TermPanelState<TItem>, labels: {
+    /** e.g. `2 entries`, `1 picture`. */
+    countLabel: (count: number) => string;
+    emptyLabel: (term: string) => string;
+}): string;

package/dist/tools/term-lookup.js

@@ -0,0 +1,284 @@
+/**
+ * Term lookup, shared by the dictionary tools.
+ *
+ * A dictionary and a picture dictionary differ only in what a result carries: one
+ * returns definitions, the other pictures. Everything up to that point is the same
+ * concern — normalising what a text selection dragged in, deciding whether a term is
+ * worth a request, telling "no entry for this word" apart from "the service did not
+ * answer", and not letting a superseded lookup overwrite a newer one's state. That is
+ * the part worth getting right once and testing without a browser, so it lives here
+ * and each tool supplies only its item reader.
+ *
+ * Nothing here names a capability or a service. PIE ships no dictionary endpoint: the
+ * corpus behind one is licensed per programme, so a host supplies either an endpoint
+ * or a resolver of its own.
+ */
+/** Longest term worth sending. Past this it is prose, not a headword. */
+export const MAX_LOOKUP_TERM_LENGTH = 80;
+/** Words a term may span. Generous enough for `carbon dioxide` and `mother in law`. */
+export const MAX_LOOKUP_TERM_WORDS = 4;
+/**
+ * Collapse whitespace and strip the punctuation a text selection drags along.
+ *
+ * A learner double-clicking a word at the end of a sentence selects `"reason."`, and
+ * a drag across a line break selects `"photo-\nsynthesis"`. Leading and trailing
+ * punctuation goes; internal hyphens and apostrophes stay, because `mother-in-law`
+ * and `don't` are the entries.
+ */
+export function normalizeTerm(raw) {
+    return raw
+        .replace(/\s+/gu, " ")
+        .trim()
+        .replace(/^[^\p{L}\p{N}]+/u, "")
+        .replace(/[^\p{L}\p{N}]+$/u, "");
+}
+/**
+ * Whether a normalised term is worth sending.
+ *
+ * A whole sentence is not a lookup, and sending it wastes a request that will miss.
+ */
+export function isLookupableTerm(term) {
+    if (!term)
+        return false;
+    if (term.length > MAX_LOOKUP_TERM_LENGTH)
+        return false;
+    return term.split(" ").length <= MAX_LOOKUP_TERM_WORDS;
+}
+/**
+ * Read a host payload into a result.
+ *
+ * `keys` are the payload fields to accept the item array under, in order, so a tool
+ * can take more than one spelling of the same field. Unknown extra fields are ignored
+ * rather than rejected, so a host can extend its payload without this package having
+ * to agree first. An item its reader rejects is dropped rather than failing the whole
+ * response: one malformed entry should not cost the learner the others.
+ */
+export function readTermLookupPayload(payload, args) {
+    if (!payload || typeof payload !== "object") {
+        return {
+            status: "error",
+            reason: `The ${args.serviceLabel} returned no data.`,
+        };
+    }
+    const record = payload;
+    let raw = null;
+    for (const key of args.keys) {
+        if (Array.isArray(record[key])) {
+            raw = record[key];
+            break;
+        }
+    }
+    if (!raw) {
+        return {
+            status: "error",
+            reason: `The ${args.serviceLabel} response was unreadable.`,
+        };
+    }
+    const items = raw
+        .map(args.toItem)
+        .filter((item) => item !== null);
+    return items.length > 0 ? { status: "ok", items } : { status: "empty" };
+}
+/**
+ * A lookup that POSTs to a host endpoint.
+ *
+ * `credentials: "same-origin"` by default. The endpoint a host names is expected to
+ * sit behind the same session boundary as the assessment itself, so the session
+ * cookie is exactly what authorises it and requiring a host to wire a token to get
+ * its own already-authenticated route to answer is a configuration step it would
+ * reasonably forget. Cross-origin requests still send nothing. A host that authorises
+ * some other way passes `headers`, and one that wants no ambient credentials at all
+ * passes `credentials: "omit"`.
+ */
+export function createEndpointTermLookup(args) {
+    const doFetch = args.fetchImpl ?? globalThis.fetch;
+    return async (request, signal) => {
+        if (typeof doFetch !== "function") {
+            return {
+                status: "error",
+                reason: "No fetch implementation is available.",
+            };
+        }
+        let headers = {
+            "content-type": "application/json",
+        };
+        try {
+            const extra = await args.headers?.();
+            if (extra)
+                headers = { ...headers, ...extra };
+        }
+        catch {
+            return {
+                status: "error",
+                reason: `The ${args.serviceLabel} could not be authorized.`,
+            };
+        }
+        try {
+            const response = await doFetch(args.endpoint, {
+                method: "POST",
+                headers,
+                credentials: args.credentials ?? "same-origin",
+                body: JSON.stringify(request),
+                signal,
+            });
+            if (!response.ok) {
+                return {
+                    status: "error",
+                    reason: `The ${args.serviceLabel} is unavailable (${response.status}).`,
+                };
+            }
+            return args.readResponse(await response.json());
+        }
+        catch (cause) {
+            // An aborted request is a newer lookup superseding this one, not a failure
+            // the learner should be told about.
+            if (cause instanceof DOMException && cause.name === "AbortError") {
+                return { status: "empty" };
+            }
+            return {
+                status: "error",
+                reason: `The ${args.serviceLabel} could not be reached.`,
+            };
+        }
+    };
+}
+/** Shown when the learner sends something that is not a headword. */
+export const NOT_A_TERM_REASON = "Look up a single word or short phrase.";
+/**
+ * The lookup half of a term panel: request sequencing and state transitions, with no
+ * framework reactivity of its own.
+ *
+ * Deliberately not a rune module. Rune modules in this package are source-only and
+ * each consumer has to alias them in its own Vite and TypeScript config; a plain
+ * class costs a caller one `$state` field instead, and is unit-testable directly.
+ */
+export class TermLookupSession {
+    options;
+    /** Cancels a lookup the learner has already superseded. */
+    #inFlight = null;
+    /** The term the last lookup ran for, so a repeat of it is not re-issued. */
+    #searchedFor = "";
+    /** Identity of the last handed-in term this session acted on. */
+    #handledRequest = null;
+    constructor(options) {
+        this.options = options;
+    }
+    get searchedFor() {
+        return this.#searchedFor;
+    }
+    /**
+     * Reconcile the unconfigured notice with whether a resolver exists.
+     *
+     * A tool with nowhere to look words up says so, rather than offering a field that
+     * silently fails: the host has misconfigured it and the learner needs to know it is
+     * not their typing. Called with the current state because it only ever moves
+     * between `idle` and `unconfigured` — a resolver arriving mid-lookup must not
+     * discard results the learner is reading.
+     */
+    syncConfigured(current) {
+        const resolver = this.options.resolver();
+        if (!resolver && current.kind === "idle") {
+            this.options.onState({ kind: "unconfigured" });
+            return;
+        }
+        if (resolver && current.kind === "unconfigured") {
+            this.options.onState({ kind: "idle" });
+        }
+    }
+    /**
+     * Run a term handed in from outside, at most once per request.
+     *
+     * Keyed on the request's identity, not on the term or on what was last searched.
+     * Both of the alternatives are wrong in a way a learner meets: keying on the term
+     * means selecting a word, typing another into the field, then selecting the first
+     * word again does nothing, because the incoming term never changed; keying on
+     * {@link searchedFor} means every reopen re-issues the stale selection and discards
+     * the lookup the learner typed. An id that changes per request says what both are
+     * guessing at.
+     *
+     * A request with no id falls back to the term, which is the best available identity
+     * when the caller cannot mint one — a host assigning `term` directly, for instance.
+     *
+     * Returns whether it issued a lookup, so a caller can mirror the term into its own
+     * field only when one ran.
+     */
+    syncRequestedTerm(request) {
+        const incoming = normalizeTerm(request.term);
+        // Closed panels spend no request: a selection made while the panel is shut is not
+        // a question, and answering it would burn a lookup the learner never sees.
+        if (!request.visible || !incoming)
+            return false;
+        const identity = request.requestId === undefined
+            ? `term:${incoming}`
+            : `id:${request.requestId}`;
+        if (identity === this.#handledRequest)
+            return false;
+        this.#handledRequest = identity;
+        void this.run(incoming);
+        return true;
+    }
+    async run(raw) {
+        const resolver = this.options.resolver();
+        if (!resolver) {
+            this.options.onState({ kind: "unconfigured" });
+            return;
+        }
+        const keyword = normalizeTerm(raw);
+        if (!isLookupableTerm(keyword)) {
+            this.options.onState({
+                kind: "error",
+                term: keyword,
+                reason: NOT_A_TERM_REASON,
+            });
+            return;
+        }
+        this.#inFlight?.abort();
+        const controller = new AbortController();
+        this.#inFlight = controller;
+        this.#searchedFor = keyword;
+        this.options.onState({ kind: "searching", term: keyword });
+        const result = await resolver({
+            keyword,
+            language: this.options.language?.() || undefined,
+            max: this.options.max,
+        }, controller.signal);
+        // A superseded lookup must not overwrite the newer one's state.
+        if (controller !== this.#inFlight)
+            return;
+        this.#inFlight = null;
+        if (result.status === "ok") {
+            this.options.onState({
+                kind: "results",
+                term: keyword,
+                items: result.items,
+            });
+            return;
+        }
+        if (result.status === "empty") {
+            this.options.onState({ kind: "empty", term: keyword });
+            return;
+        }
+        this.options.onState({
+            kind: "error",
+            term: keyword,
+            reason: result.reason,
+        });
+    }
+}
+/**
+ * The panel's live-region text.
+ *
+ * Only the states a learner is waiting on announce. `idle`, `unconfigured` and
+ * `error` are already rendered as visible text in the panel body, and repeating them
+ * here would announce the same sentence twice.
+ */
+export function termPanelStatusMessage(state, labels) {
+    if (state.kind === "searching")
+        return `Looking up ${state.term}`;
+    if (state.kind === "results") {
+        return `${labels.countLabel(state.items.length)} for ${state.term}`;
+    }
+    if (state.kind === "empty")
+        return labels.emptyLabel(state.term);
+    return "";
+}

package/dist/types/index.d.ts

@@ -7,6 +7,10 @@
  * INCLUDING REFERENCES TO THE DATASTORE PACKAGE INSTEAD WILL MAKE PIEONEER THROW 500
  * EVERYWHERE WITHOUT ANY FURTHER EXPLANATION
  */
+import type { FormativeDeliveryPolicy, FormativeItemPolicy, FormativeSectionSlice } from "../formative/types.js";
+import type { TimedMediaSectionData, TimedMediaSectionSessionSlice } from "../timed-media/types.js";
+export type { FormativeDeliveryPolicy, FormativeItemPolicy };
+export type { TimedMediaSectionData };
 export interface BaseEntity {
     id?: string;
     createdAt?: Date;
@@ -233,6 +237,14 @@ export interface AssessmentItemRef extends SearchMetaDataEntity {
     item?: ItemEntity;
     /** Item-level settings for tool requirements and customization */
     settings?: ItemSettings;
+    /**
+     * Formative delivery override for this item. Every field overrides the
+     * section's `formative` policy independently, which is the order QTI 3 uses
+     * for `qti-item-session-control` on an item ref versus its section.
+     *
+     * See `docs/prds/formative-delivery-contract.md`.
+     */
+    formative?: FormativeItemPolicy;
 }
 export interface AssessmentSection extends SearchMetaDataEntity, SettingsMetaDataEntity {
     id?: string;
@@ -266,6 +278,35 @@ export interface AssessmentSection extends SearchMetaDataEntity, SettingsMetaDat
      * delivered without an enclosing assessment.
      */
     personalNeedsProfile?: PersonalNeedsProfile;
+    /**
+     * Formative delivery policy for this section: how many Tries a learner gets
+     * on each item, when feedback is revealed, and whether the behavior is on at
+     * all. Absent or `enabled: false` delivers exactly as a section without this
+     * field — no control, no state, no env override.
+     *
+     * Individual items override it through `AssessmentItemRef.formative`. See
+     * `docs/prds/formative-delivery-contract.md`.
+     */
+    formative?: FormativeDeliveryPolicy;
+    /**
+     * The section flavor. Absent for every section authored so far, and the only
+     * value is `"timed-media"`, which pairs with `timedMedia` below.
+     *
+     * A discriminator on data, not a renderer selector: the host still picks the
+     * layout tag, as every integration that renders a section already does. See
+     * `docs/prds/timed-media-section-contract.md#delivery-attachment`.
+     */
+    sectionType?: "timed-media";
+    /**
+     * Cue timeline and playback policy for a timed-media section. Carries no media
+     * payload — `stimulusRef` names the `class: "stimulus"` rubric block whose
+     * passage supplies the time source, so the media keeps a Catalog Owner and its
+     * captions, transcript and signed alternates resolve through the
+     * accessibility-catalog rail.
+     *
+     * Ignored unless `sectionType` is `"timed-media"`.
+     */
+    timedMedia?: TimedMediaSectionData;
     sort?: string;
 }
 export interface TestPart {
@@ -275,6 +316,70 @@ export interface TestPart {
     submissionMode: "individual" | "simultaneous";
     sections: AssessmentSection[];
 }
+/**
+ * The host-facing persistence snapshot for one section, returned by
+ * `SectionControllerHandle.getSession()` and accepted by `applySession()`.
+ *
+ * Canonical here rather than in a player or the toolkit: the toolkit is
+ * complementary to a player rather than an alternative to one and sits beneath
+ * both entry paths, so a shape both need belongs alongside `AssessmentSection`.
+ * The delivery slices it carries are defined in this package too, which is what
+ * previously forced them to reference this shape in prose instead of types.
+ */
+export interface SectionControllerSessionState {
+    currentItemIndex?: number;
+    visitedItemIdentifiers?: string[];
+    itemSessions: Record<string, unknown>;
+    /**
+     * Formative delivery state — Try counts and reveal state per item.
+     *
+     * Optional, and its absence is indistinguishable from a snapshot saved
+     * before formative delivery existed, which is what keeps existing persisted
+     * sessions valid. A slice with an unrecognized `version` is rejected whole
+     * and formative state starts clean; `itemSessions` in the same snapshot is
+     * unaffected, so a formative version bump never costs a learner responses.
+     */
+    formative?: FormativeSectionSlice;
+    /**
+     * Timed-media delivery state — media progress, cue visits and completions.
+     *
+     * Same posture as `formative`: optional, absence indistinguishable from a
+     * pre-timed-media snapshot, and an unrecognized `version` rejected whole so
+     * cue progress restarts while item sessions in the same snapshot are applied
+     * untouched.
+     */
+    timedMedia?: TimedMediaSectionSessionSlice;
+}
+export interface AssessmentSessionNavigationState {
+    currentSectionIndex: number;
+    visitedSectionIdentifiers: string[];
+    currentSectionIdentifier?: string;
+}
+export interface AssessmentSessionRealization {
+    seed: string;
+    sectionIdentifiers: string[];
+}
+export interface AssessmentSectionSessionState {
+    sectionIdentifier: string;
+    updatedAt: string;
+    /**
+     * The full section snapshot. Typing this as anything narrower drops the
+     * delivery slices without a compiler error at the point of loss.
+     */
+    session: SectionControllerSessionState | null;
+}
+export interface AssessmentSession {
+    version: 1;
+    assessmentAttemptSessionIdentifier: string;
+    assessmentId: string;
+    startedAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    navigationState: AssessmentSessionNavigationState;
+    realization: AssessmentSessionRealization;
+    sectionSessions: Record<string, AssessmentSectionSessionState>;
+    contextVariables?: Record<string, unknown>;
+}
 export interface ContextDeclaration {
     identifier: string;
     baseType: "boolean" | "integer" | "float" | "string" | "identifier" | "point" | "pair" | "directedPair" | "duration" | "file" | "uri";
@@ -950,4 +1055,3 @@ export interface CmsBlueprintItemEntity extends BaseEntity {
     details?: string;
     assessmentId?: string;
 }
-export {};

package/dist/ui/attribute-coercion.d.ts

@@ -0,0 +1 @@
+export declare function coerceBooleanLike(value: boolean | string | null | undefined, defaultValue?: boolean): boolean;

package/dist/ui/attribute-coercion.js

@@ -0,0 +1,19 @@
+export function coerceBooleanLike(value, defaultValue = false) {
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (value === null || value === undefined) {
+        return defaultValue;
+    }
+    const normalizedValue = String(value).trim().toLowerCase();
+    if (normalizedValue === "") {
+        return defaultValue;
+    }
+    if (["false", "0", "off", "no"].includes(normalizedValue)) {
+        return false;
+    }
+    if (["true", "1", "on", "yes"].includes(normalizedValue)) {
+        return true;
+    }
+    return Boolean(normalizedValue);
+}

package/dist/ui/first-focusable.d.ts

@@ -8,3 +8,25 @@ export declare const FOCUSABLE_SELECTOR: string;
  * not disabled, not inside `inert`, and has a layout box).
  */
 export declare function isProgrammaticFocusTarget(el: HTMLElement): boolean;
+/**
+ * Whether `el` is in the sequential tab order.
+ *
+ * Stricter than {@link isProgrammaticFocusTarget}, which deliberately accepts
+ * `tabindex="-1"`: such an element is a valid `focus()` target — a roving-tabindex
+ * control or a landmark focused after a view change — but is explicitly not tabbable.
+ * A tab order that included it would stop on elements the browser skips.
+ */
+export declare function isTabbable(el: HTMLElement): boolean;
+/**
+ * Focusable descendants of `root` in tab order, descending into open shadow roots.
+ *
+ * `querySelectorAll` stops at a shadow boundary, which makes it the wrong tool for
+ * collecting a tab order in this codebase: every tool renders into `shadow: "open"`,
+ * so a container holding one has focusable content the selector cannot see. A focus
+ * trap built on the flat query traps Tab in the host's own chrome and never reaches
+ * the tool — the tool's controls are then unreachable by keyboard entirely.
+ *
+ * Closed shadow roots are invisible to script and are skipped; nothing can be done
+ * for them from outside.
+ */
+export declare function collectFocusable(root: Element | ShadowRoot): HTMLElement[];