@joewinke/jatui 0.36.3 → 0.38.0

package/dist/artifact-blocks/review/roundLines.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Locked round lines (./rounds.ts `RoundView.history`, newest first) →
+ * jatui RoundHistory `rounds` (media-picker, diff-review).
+ *
+ * RoundHistory keys its list on `round`, so keys must be unique non-empty
+ * strings: a legacy line (round null) becomes "legacy", and a repeated round
+ * (two lines for one round — e.g. a viewer line and an older copy) gets a
+ * `#n` suffix on the LATER line, so the newest keeps the plain key a version
+ * switcher pairs with. The list is handed over oldest first, which is how
+ * RoundHistory reads input order when not every line carries a date.
+ */
+import type { ReviewRound } from "../../components/review/reviewSummary.js";
+import type { RoundLine } from "./rounds.js";
+export declare function historyRounds(lines: readonly RoundLine[], label: (round: string | null) => string): ReviewRound[];

package/dist/artifact-blocks/review/roundLines.js

@@ -0,0 +1,20 @@
+const LEGACY_ROUND_KEY = "legacy";
+export function historyRounds(lines, label) {
+    const seen = new Set();
+    const out = [];
+    for (const l of lines) {
+        const base = l.round ?? LEGACY_ROUND_KEY;
+        let key = base;
+        for (let n = 2; seen.has(key); n++)
+            key = `${base}#${n}`;
+        seen.add(key);
+        out.push({
+            round: key,
+            verdict: l.verdict ?? null,
+            note: l.note ?? null,
+            at: l.at ?? null,
+            label: label(l.round),
+        });
+    }
+    return out.reverse();
+}

package/dist/artifact-blocks/review/rounds.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Review rounds: the shared, block-agnostic round model (mos-lsmve.5, M1).
+ * Design: docs/review-ux/proposal.md → "The round model".
+ *
+ * A ROUND is one thing put in front of the reviewer: a version of the art
+ * (media-picker `currentVersion`) or one "ready to retest" of a checklist row
+ * (its `retestSince`). Each round has its own verdict and its own note.
+ *
+ * Saved shape, backward compatible — the flat fields stay the CURRENT round,
+ * so every existing reader keeps working:
+ *
+ *   { verdict|status, note, at, …block fields,
+ *     round?:   "2026-10-11T15:00:00Z" | "v8",   // the round this answers
+ *     history?: [{ round, verdict, note, at }] }  // locked, newest first
+ *
+ * An entry with no `round` is "round 1 (legacy)". Joe D1 = A: when the round
+ * under review differs from the entry's round, the FIRST save in the new
+ * round moves the old {verdict, note, at} into history and the new round
+ * starts blank. That happens here, on the client, on the owner's own save —
+ * never as a data migration, so stored state is untouched until its owner
+ * acts. Until then `viewEntry()` shows the same split without writing it.
+ *
+ * Pure: no DOM, no Svelte. Every stored value is untrusted JSON.
+ */
+/** One locked line of an item's history. `verdict` holds the block's own
+ * vocabulary (checklist status or media/diff verdict). */
+export type RoundLine = {
+    /** The round this line answered; null = round 1 (legacy). */
+    round: string | null;
+    verdict?: string;
+    note?: string;
+    at?: string;
+    /** Where the line came from: the viewer's own saves, or the publisher's
+     * spec (media-picker `history[]` param). */
+    source?: "viewer" | "publisher";
+};
+/** How one block names its round-scoped fields. */
+export type RoundsConfig = {
+    /** The saved field holding the verdict: "verdict" (media, diff) or
+     * "status" (checklist). */
+    verdictKey: string;
+    /** The block's verdict vocabulary; anything else is dropped as junk. */
+    verdicts: readonly string[];
+    /** A verdict that means "no verdict" (checklist "untested"): it is never
+     * written into history on its own. */
+    emptyVerdict?: string;
+    /** Further fields that belong to a round and start blank in a new one
+     * (checklist `statusAt`, diff `edited`). note/at always do. */
+    roundFields?: readonly string[];
+};
+/** The display label of a round id. */
+declare function roundLabel(round: string | null | undefined): string;
+/**
+ * Do two round ids name the same round? Identity, not ordering — so client
+ * clock skew can never move a verdict. Two ISO strings for the same instant
+ * ("…T15:00Z" vs "…T15:00:00.000Z") are the same round.
+ */
+declare function sameRound(a: string | null | undefined, b: string | null | undefined): boolean;
+/** The round id an entry answers; null = round 1 (legacy) or junk. */
+declare function roundOf(entry: unknown): string | null;
+/** What a block renders for one item: the current round and the locked
+ * history, newest first. Nothing is written. */
+export type RoundView = {
+    /** The round under review (null = the item has no rounds). */
+    round: string | null;
+    /** The current round's fields — blank when the stored entry is stale.
+     * Non-round block fields (media `variant`) are kept either way. */
+    current: Record<string, unknown>;
+    history: RoundLine[];
+    /** True when the stored entry belongs to an earlier round; the first save
+     * will move it into history. */
+    stale: boolean;
+};
+/** Bind a block's config once: `const rounds = useRounds({ verdictKey: "status", … })`. */
+export declare function useRounds(cfg: RoundsConfig, defaults?: {
+    stampKeys?: readonly string[];
+}): {
+    roundOf: typeof roundOf;
+    roundLabel: typeof roundLabel;
+    sameRound: typeof sameRound;
+    isStale: (entry: unknown, current: string | null | undefined) => boolean;
+    parseHistory: (raw: unknown) => RoundLine[];
+    view: (raw: unknown, current: string | null | undefined, publisherHistory?: unknown) => RoundView;
+    save: (stored: unknown, patch: Record<string, unknown>, current: string | null | undefined) => Record<string, unknown>;
+};
+export {};

package/dist/artifact-blocks/review/rounds.js

@@ -0,0 +1,302 @@
+/**
+ * Review rounds: the shared, block-agnostic round model (mos-lsmve.5, M1).
+ * Design: docs/review-ux/proposal.md → "The round model".
+ *
+ * A ROUND is one thing put in front of the reviewer: a version of the art
+ * (media-picker `currentVersion`) or one "ready to retest" of a checklist row
+ * (its `retestSince`). Each round has its own verdict and its own note.
+ *
+ * Saved shape, backward compatible — the flat fields stay the CURRENT round,
+ * so every existing reader keeps working:
+ *
+ *   { verdict|status, note, at, …block fields,
+ *     round?:   "2026-10-11T15:00:00Z" | "v8",   // the round this answers
+ *     history?: [{ round, verdict, note, at }] }  // locked, newest first
+ *
+ * An entry with no `round` is "round 1 (legacy)". Joe D1 = A: when the round
+ * under review differs from the entry's round, the FIRST save in the new
+ * round moves the old {verdict, note, at} into history and the new round
+ * starts blank. That happens here, on the client, on the owner's own save —
+ * never as a data migration, so stored state is untouched until its owner
+ * acts. Until then `viewEntry()` shows the same split without writing it.
+ *
+ * Pure: no DOM, no Svelte. Every stored value is untrusted JSON.
+ */
+/** Cap on stored history lines per item — matches media-picker's param cap. */
+const HISTORY_MAX = 12;
+/** Cap on a stored round id / note in a history line. */
+const ROUND_MAX_CHARS = 200;
+const NOTE_MAX_CHARS = 10_000;
+/** The display label of a round id. */
+function roundLabel(round) {
+    if (round == null || round === "")
+        return "Round 1 (legacy)";
+    const t = isoMs(round);
+    if (t != null) {
+        const d = new Date(t);
+        return `Retest of ${d.toLocaleDateString("en-US", { month: "short", day: "numeric" })}`;
+    }
+    return round;
+}
+function isoMs(s) {
+    // Only ISO-shaped dates count as times; "v8" must never parse as a date.
+    if (!/^\d{4}-\d{2}-\d{2}(T|$)/.test(s))
+        return null;
+    const t = Date.parse(s);
+    return Number.isNaN(t) ? null : t;
+}
+/**
+ * Do two round ids name the same round? Identity, not ordering — so client
+ * clock skew can never move a verdict. Two ISO strings for the same instant
+ * ("…T15:00Z" vs "…T15:00:00.000Z") are the same round.
+ */
+function sameRound(a, b) {
+    const x = a || null;
+    const y = b || null;
+    if (x === y)
+        return true;
+    if (x == null || y == null)
+        return false;
+    const tx = isoMs(x);
+    const ty = isoMs(y);
+    return tx != null && tx === ty;
+}
+function str(v, max) {
+    return typeof v === "string" && v !== "" ? v.slice(0, max) : undefined;
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** The round id an entry answers; null = round 1 (legacy) or junk. */
+function roundOf(entry) {
+    if (!isRecord(entry))
+        return null;
+    return str(entry.round, ROUND_MAX_CHARS) ?? null;
+}
+/** Defensively parse one history line; null when it carries nothing. */
+function parseRoundLine(raw, cfg) {
+    if (!isRecord(raw))
+        return null;
+    const verdictRaw = raw.verdict ?? raw[cfg.verdictKey] ?? raw.status;
+    const verdict = typeof verdictRaw === "string" &&
+        cfg.verdicts.includes(verdictRaw) &&
+        verdictRaw !== cfg.emptyVerdict
+        ? verdictRaw
+        : undefined;
+    const note = str(raw.note, NOTE_MAX_CHARS);
+    if (!verdict && !note)
+        return null;
+    const line = {
+        // media-picker's publisher param names it `version`
+        round: str(raw.round, ROUND_MAX_CHARS) ??
+            str(raw.version, ROUND_MAX_CHARS) ??
+            null,
+    };
+    if (verdict)
+        line.verdict = verdict;
+    if (note)
+        line.note = note;
+    const at = str(raw.at, 64);
+    if (at)
+        line.at = at;
+    if (raw.source === "viewer" || raw.source === "publisher")
+        line.source = raw.source;
+    return line;
+}
+function lineKey(l) {
+    const r = l.round == null ? "" : (isoMs(l.round) ?? l.round);
+    return `${r}\u0000${l.verdict ?? ""}\u0000${l.note ?? ""}\u0000${l.at ?? ""}`;
+}
+/** Defensively parse a stored history array: junk dropped, exact repeats
+ * (a double-open re-move) collapsed, capped at HISTORY_MAX. */
+function parseHistory(raw, cfg) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const item of raw.slice(0, HISTORY_MAX * 4)) {
+        const line = parseRoundLine(item, cfg);
+        if (!line)
+            continue;
+        const k = lineKey(line);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(line);
+        if (out.length >= HISTORY_MAX)
+            break;
+    }
+    return out;
+}
+/** The current round's {verdict, note, at} of an entry, as a history line. */
+function currentAsLine(entry, cfg) {
+    return parseRoundLine({
+        verdict: entry[cfg.verdictKey],
+        note: entry.note,
+        at: entry.at,
+        round: entry.round,
+    }, cfg);
+}
+/**
+ * Is the entry's current verdict/note from a round OTHER than `current`?
+ *
+ * - `current` null (the item has no rounds): never stale.
+ * - Entry with a `round`: identity comparison (`sameRound`).
+ * - Legacy entry (no `round`) against an ISO `current` (a checklist
+ *   retestSince): a save stamped at or after the round opened already
+ *   answered it (the same reading `rowAwaitsViewer` makes); an unstamped or
+ *   earlier save is from before. `stampKeys` names the timestamps to trust,
+ *   most specific first (checklist: ["statusAt", "at"]).
+ * - Legacy entry against a version id ("v8"): NOT stale — it is adopted as
+ *   the current round. Every media-picker save before this module is legacy
+ *   and was made against the version then under review; blanking them all on
+ *   deploy would be a silent data loss. The next save stamps the round.
+ * - An entry that carries no verdict and no note is never stale (there is
+ *   nothing to lock away).
+ */
+function isStale(entry, current, cfg, stampKeys = ["at"]) {
+    if (!current)
+        return false;
+    if (!isRecord(entry))
+        return false;
+    if (!currentAsLine(entry, cfg))
+        return false;
+    const r = roundOf(entry);
+    if (r != null)
+        return !sameRound(r, current);
+    const since = isoMs(current);
+    if (since == null)
+        return false;
+    for (const k of stampKeys) {
+        const s = entry[k];
+        if (typeof s !== "string")
+            continue;
+        const t = Date.parse(s);
+        if (!Number.isNaN(t))
+            return t < since;
+    }
+    return true;
+}
+function blankRound(entry, cfg) {
+    const out = {};
+    const drop = new Set([
+        cfg.verdictKey,
+        "note",
+        "at",
+        "round",
+        "history",
+        ...(cfg.roundFields ?? []),
+    ]);
+    for (const [k, v] of Object.entries(entry))
+        if (!drop.has(k))
+            out[k] = v;
+    return out;
+}
+/** Merge viewer history with publisher-side lines (media-picker `history[]`
+ * param). The viewer's own line for a round wins; a publisher line fills a
+ * round the viewer has no record of. Viewer lines first (newest first as
+ * stored), then the publisher's in the publisher's order. */
+function mergeHistory(viewer, publisher) {
+    const out = viewer.map((l) => ({
+        ...l,
+        source: l.source ?? "viewer",
+    }));
+    for (const p of publisher) {
+        if (out.some((l) => sameRound(l.round, p.round)))
+            continue;
+        out.push({ ...p, source: "publisher" });
+    }
+    return out.slice(0, HISTORY_MAX * 2);
+}
+/**
+ * Read one stored entry for display under round `current`.
+ * `publisherHistory` is the spec's own history (untrusted JSON too).
+ */
+function viewEntry(raw, current, cfg, opts = {}) {
+    const round = current || null;
+    const entry = isRecord(raw) ? raw : {};
+    let history = parseHistory(entry.history, cfg);
+    const stale = isStale(entry, round, cfg, opts.stampKeys);
+    let currentFields;
+    if (stale) {
+        const moved = currentAsLine(entry, cfg);
+        if (moved)
+            history = prependLine(history, moved);
+        currentFields = blankRound(entry, cfg);
+    }
+    else {
+        currentFields = { ...entry };
+        delete currentFields.history;
+    }
+    const publisher = parseHistory(opts.publisherHistory, cfg).filter(
+    // the publisher's line for the round under review is not history
+    (l) => !(round != null && sameRound(l.round, round)));
+    return {
+        round,
+        current: currentFields,
+        history: mergeHistory(history, publisher),
+        stale,
+    };
+}
+function prependLine(history, line) {
+    const k = lineKey(line);
+    const rest = history.filter((l) => lineKey(l) !== k);
+    return [line, ...rest].slice(0, HISTORY_MAX);
+}
+/**
+ * Apply one save by the viewer to the stored entry, under round `current`.
+ *
+ * `patch` is the block's change (e.g. `{ status: "fail", at }`); a key set to
+ * `undefined` deletes that field (Undo). When the stored entry is stale, its
+ * {verdict, note, at} move into `history` first and the round's fields start
+ * blank — the patch then lands on the blank round. The result is stamped with
+ * `round` (omitted when the item has no rounds, so a round-less block's saved
+ * shape is exactly what it was before this module).
+ *
+ * Idempotent across a double-open: applying the same patch twice, or a stale
+ * tab re-applying after another tab already moved the round, never duplicates
+ * a history line.
+ */
+function applySave(stored, patch, current, cfg, opts = {}) {
+    const round = current || null;
+    const entry = isRecord(stored) ? stored : {};
+    let history = parseHistory(entry.history, cfg);
+    let next;
+    if (isStale(entry, round, cfg, opts.stampKeys)) {
+        const moved = currentAsLine(entry, cfg);
+        if (moved)
+            history = prependLine(history, moved);
+        next = blankRound(entry, cfg);
+    }
+    else {
+        next = { ...entry };
+        delete next.history;
+    }
+    for (const [k, v] of Object.entries(patch)) {
+        if (k === "history" || k === "round")
+            continue;
+        if (v === undefined)
+            delete next[k];
+        else
+            next[k] = v;
+    }
+    if (round != null)
+        next.round = round;
+    else
+        delete next.round;
+    if (history.length > 0)
+        next.history = history;
+    return next;
+}
+/** Bind a block's config once: `const rounds = useRounds({ verdictKey: "status", … })`. */
+export function useRounds(cfg, defaults = {}) {
+    return {
+        roundOf,
+        roundLabel,
+        sameRound,
+        isStale: (entry, current) => isStale(entry, current, cfg, defaults.stampKeys),
+        parseHistory: (raw) => parseHistory(raw, cfg),
+        view: (raw, current, publisherHistory) => viewEntry(raw, current, cfg, { ...defaults, publisherHistory }),
+        save: (stored, patch, current) => applySave(stored, patch, current, cfg, defaults),
+    };
+}

package/dist/artifact-blocks/review/saver.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Block-state saver for the review blocks (media-picker, diff-review).
+ *
+ * The blocks used to fire-and-forget `ctx.saveState(...).catch(() => {})`,
+ * so a failed save showed only in the page header (proposal critique #9).
+ * This keeps the block's own "did my last save land?" state: only the LATEST
+ * save's outcome counts (an older failure resolving after a newer success
+ * must not raise a stale alarm), and `retry()` re-sends the last state.
+ *
+ * `save()` rejects on failure so a ReviewNote `onSave` can show its own
+ * "Not saved / Retry"; verdict saves swallow the rejection and let the
+ * block render `failed`.
+ */
+import type { BlockState } from "../types.js";
+type SaveFn = ((next: BlockState) => Promise<void>) | undefined;
+export declare function createStateSaver(getSave: () => SaveFn): {
+    /** True while the most recent save failed. */
+    readonly failed: boolean;
+    save: (next: BlockState) => Promise<void>;
+    /** Re-send the last state (the alert's Retry). */
+    retry(): void;
+};
+export {};

package/dist/artifact-blocks/review/saver.js

@@ -0,0 +1,48 @@
+/* saver.svelte.js generated by Svelte v5.53.11 */
+import * as $ from 'svelte/internal/client';
+
+export function createStateSaver(getSave) {
+	let failed = $.state(false);
+	let last = null;
+	let seq = 0;
+
+	function save(next) {
+		const fn = getSave();
+
+		if (!fn) return Promise.resolve();
+
+		last = next;
+
+		const mine = ++seq;
+		let pending;
+
+		try {
+			pending = Promise.resolve(fn(next));
+		} catch(err) {
+			pending = Promise.reject(err);
+		}
+
+		return pending.then(
+			() => {
+				if (mine === seq) $.set(failed, false);
+			},
+			(err) => {
+				if (mine === seq) $.set(failed, true);
+
+				throw err;
+			}
+		);
+	}
+
+	return {
+		/** True while the most recent save failed. */
+		get failed() {
+			return $.get(failed);
+		},
+		save,
+		/** Re-send the last state (the alert's Retry). */
+		retry() {
+			if (last) save(last).catch(() => {});
+		}
+	};
+}

package/dist/artifact-blocks/review/team.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Item TEAM status for the Gallery (media-picker) and Redline (diff-review)
+ * blocks — decision D7 = A in docs/review-ux/proposal.md: "any item can be
+ * In progress / Ready, and Ready opens a round".
+ *
+ * It is a PUBLISHER param (`items[].team`), never viewer state: the team
+ * updates it by republishing, exactly like the checklist's Team column.
+ *
+ *   team: { status: "in_progress" }                         working on it
+ *   team: { status: "ready", readySince: "2026-10-11T15:00:00Z" }
+ *                                                           fixed — look again
+ *
+ * `ready` REQUIRES `readySince`: the timestamp is the round's identity, so a
+ * second "ready" (a new readySince) opens a new round and a republish that
+ * keeps the same readySince does not. Rounds compare by identity, never by
+ * clock order (see ./rounds.ts).
+ */
+import { z } from "zod";
+declare const ITEM_TEAM_STATUSES: readonly ["in_progress", "ready"];
+export type ItemTeamStatus = (typeof ITEM_TEAM_STATUSES)[number];
+export type ItemTeam = {
+    status: ItemTeamStatus;
+    /** When the team marked the item ready (ISO). Required for `ready`. */
+    readySince?: string | undefined;
+};
+export declare const itemTeamSchema: z.ZodType<ItemTeam>;
+/** The Team chip's words — the same ones the checklist Team column uses. */
+export declare const ITEM_TEAM_LABEL: Record<ItemTeamStatus, string>;
+/** The round a `ready` opens (its readySince), else null. */
+export declare function teamRound(team: ItemTeam | undefined | null): string | null;
+export {};

package/dist/artifact-blocks/review/team.js

@@ -0,0 +1,42 @@
+/**
+ * Item TEAM status for the Gallery (media-picker) and Redline (diff-review)
+ * blocks — decision D7 = A in docs/review-ux/proposal.md: "any item can be
+ * In progress / Ready, and Ready opens a round".
+ *
+ * It is a PUBLISHER param (`items[].team`), never viewer state: the team
+ * updates it by republishing, exactly like the checklist's Team column.
+ *
+ *   team: { status: "in_progress" }                         working on it
+ *   team: { status: "ready", readySince: "2026-10-11T15:00:00Z" }
+ *                                                           fixed — look again
+ *
+ * `ready` REQUIRES `readySince`: the timestamp is the round's identity, so a
+ * second "ready" (a new readySince) opens a new round and a republish that
+ * keeps the same readySince does not. Rounds compare by identity, never by
+ * clock order (see ./rounds.ts).
+ */
+import { z } from "zod";
+const ITEM_TEAM_STATUSES = ["in_progress", "ready"];
+export const itemTeamSchema = z
+    .object({
+    status: z.enum(ITEM_TEAM_STATUSES),
+    readySince: z.iso.datetime({ offset: true }).optional(),
+})
+    .check((ctx) => {
+    if (ctx.value.status === "ready" && !ctx.value.readySince)
+        ctx.issues.push({
+            code: "custom",
+            input: ctx.value,
+            path: ["readySince"],
+            message: 'team status "ready" needs readySince (ISO timestamp) — it opens the new review round',
+        });
+});
+/** The Team chip's words — the same ones the checklist Team column uses. */
+export const ITEM_TEAM_LABEL = {
+    ready: "Ready to retest",
+    in_progress: "In progress",
+};
+/** The round a `ready` opens (its readySince), else null. */
+export function teamRound(team) {
+    return team?.status === "ready" && team.readySince ? team.readySince : null;
+}

package/dist/artifact-blocks/review/visualOrder.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The items jatui `reviewKeys()` walks, in VISUAL order (media-picker,
+ * diff-review).
+ *
+ * Decided cards sink with CSS `order`, so DOM order is not what the reviewer
+ * sees: j must step to the card that is visually next, not jump over one that
+ * moved to the end. Hidden cards (filtered out) are skipped.
+ */
+export declare function visualItems(root: HTMLElement | null): HTMLElement[];
+/** True when a keydown target is a text field (keys are text there). */
+export declare function isTextTarget(t: EventTarget | null): boolean;
+/**
+ * The sort is a SNAPSHOT (mos-lsmve.12). If `order` tracked live verdicts, a
+ * card would jump to the end the moment it was decided and j from it would
+ * walk the NEW order onto an already-decided card (UAT: an Accept on §4.2
+ * was overwritten by a Reject + note meant for §7.4). Blocks take ranks once
+ * at load and again only on a filter change; while the reviewer works,
+ * every card stays where it was.
+ *
+ * CSS `order` per item id from a verdict snapshot. Undecided (or a verdict
+ * with no rank) is 0.
+ */
+export declare function sortRanks(ids: readonly string[], verdictOf: (id: string) => string | null | undefined, rank: Readonly<Partial<Record<string, number>>>): Record<string, number>;
+/**
+ * The first undecided id after `fromId` in `orderedIds`, wrapping, never
+ * `fromId` itself. Null when nothing else is undecided (or `fromId` is not
+ * in the list), so the caller can fall back to the plain next card.
+ */
+export declare function nextUndecided(orderedIds: readonly string[], fromId: string, isDecided: (id: string) => boolean): string | null;

package/dist/artifact-blocks/review/visualOrder.js

@@ -0,0 +1,66 @@
+/**
+ * The items jatui `reviewKeys()` walks, in VISUAL order (media-picker,
+ * diff-review).
+ *
+ * Decided cards sink with CSS `order`, so DOM order is not what the reviewer
+ * sees: j must step to the card that is visually next, not jump over one that
+ * moved to the end. Hidden cards (filtered out) are skipped.
+ */
+export function visualItems(root) {
+    if (!root)
+        return [];
+    return [...root.querySelectorAll("[data-item-id]")]
+        .filter((el) => !el.hidden && !el.closest("[hidden]"))
+        .map((el, i) => ({ el, i, order: Number(el.style.order) || 0 }))
+        .sort((a, b) => a.order - b.order || a.i - b.i)
+        .map((x) => x.el);
+}
+/** True when a keydown target is a text field (keys are text there). */
+export function isTextTarget(t) {
+    if (!(t instanceof HTMLElement))
+        return false;
+    if (t.isContentEditable)
+        return true;
+    if (t.matches("textarea, select"))
+        return true;
+    if (!t.matches("input"))
+        return false;
+    const type = t.type;
+    return !["button", "checkbox", "radio", "range", "submit", "reset"].includes(type);
+}
+/**
+ * The sort is a SNAPSHOT (mos-lsmve.12). If `order` tracked live verdicts, a
+ * card would jump to the end the moment it was decided and j from it would
+ * walk the NEW order onto an already-decided card (UAT: an Accept on §4.2
+ * was overwritten by a Reject + note meant for §7.4). Blocks take ranks once
+ * at load and again only on a filter change; while the reviewer works,
+ * every card stays where it was.
+ *
+ * CSS `order` per item id from a verdict snapshot. Undecided (or a verdict
+ * with no rank) is 0.
+ */
+export function sortRanks(ids, verdictOf, rank) {
+    const out = {};
+    for (const id of ids) {
+        const v = verdictOf(id);
+        out[id] = (v && rank[v]) || 0;
+    }
+    return out;
+}
+/**
+ * The first undecided id after `fromId` in `orderedIds`, wrapping, never
+ * `fromId` itself. Null when nothing else is undecided (or `fromId` is not
+ * in the list), so the caller can fall back to the plain next card.
+ */
+export function nextUndecided(orderedIds, fromId, isDecided) {
+    const n = orderedIds.length;
+    const from = orderedIds.indexOf(fromId);
+    if (from === -1)
+        return null;
+    for (let step = 1; step < n; step++) {
+        const id = orderedIds[(from + step) % n];
+        if (!isDecided(id))
+            return id;
+    }
+    return null;
+}