@jini-ai/admin 0.3.10 → 0.4.1

package/dist/media/controllers/library.controller.d.ts

@@ -0,0 +1,47 @@
+import { countMediaTabs } from '../rules.js';
+import type { MediaApiPort } from '../ports.js';
+import type { MediaAsset, MediaQuery, UploadInput } from '../models.js';
+export interface LibraryState {
+    readonly items: readonly MediaAsset[] | null;
+    readonly query: MediaQuery;
+    readonly loading: boolean;
+    readonly busy: boolean;
+    readonly pendingIds: readonly string[];
+    readonly error: string | null;
+    readonly pendingPurge: MediaAsset | null;
+    readonly hasUntyped: boolean;
+    readonly counts: ReturnType<typeof countMediaTabs> | null;
+}
+export declare function createLibraryController({ api }: {
+    api: MediaApiPort;
+}, { query }?: {
+    query?: MediaQuery;
+}): {
+    getSnapshot: () => Readonly<LibraryState>;
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }) => () => void;
+    load: (_required?: Record<string, never>, _optional?: Record<string, never>) => Promise<void>;
+    setQuery({ query }: {
+        query: MediaQuery;
+    }, _optional?: Record<string, never>): Promise<void>;
+    upload({ input, alt }: {
+        input: UploadInput;
+        alt?: string;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+    trash({ id }: {
+        id: string;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+    restore({ id }: {
+        id: string;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+    requestPurge({ item }: {
+        item: MediaAsset;
+    }, _optional?: Record<string, never>): void;
+    cancelPurge(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+    confirmPurge({ confirmed }: {
+        confirmed: boolean;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+    dispose(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+};
+//# sourceMappingURL=library.controller.d.ts.map

package/dist/media/controllers/library.controller.js

@@ -0,0 +1,173 @@
+import { createControllerStore } from '../../core/module/controller-store.js';
+import { queryMedia, countMediaTabs, canRestoreMedia, isRetryableMediaError } from '../rules.js';
+export function createLibraryController({ api }, { query = {} } = {}) {
+    const store = createControllerStore({
+        initial: {
+            items: null,
+            query,
+            loading: false,
+            busy: false,
+            pendingIds: [],
+            error: null,
+            pendingPurge: null,
+            hasUntyped: false,
+            counts: null,
+        },
+    });
+    let library = null;
+    let readFailed = false, retryAttempt = 0;
+    let retryTimer = null;
+    function cancelRetry() {
+        if (retryTimer !== null)
+            clearTimeout(retryTimer);
+        retryTimer = null;
+    }
+    let readAbort = null, generation = 0;
+    async function load(_required = {}, _optional = {}) {
+        if (store.signal.aborted)
+            return;
+        cancelRetry();
+        readAbort?.abort();
+        const abort = new AbortController();
+        readAbort = abort;
+        const ticket = ++generation;
+        store.set({ patch: { loading: true, error: null } });
+        try {
+            const all = await api.list({}, { signal: abort.signal });
+            const items = queryMedia({ media: all, query: store.getSnapshot().query });
+            if (ticket === generation) {
+                readFailed = false;
+                retryAttempt = 0;
+                library = all;
+                store.set({
+                    patch: {
+                        items: Object.freeze(items.map((item) => Object.freeze({ ...item }))),
+                        counts: countMediaTabs({ media: all }),
+                        hasUntyped: all.some((item) => item.contentType === null),
+                        error: null,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            // A later background failure must not blank an already-rendered screen.
+            if (!abort.signal.aborted && ticket === generation) {
+                readFailed = true;
+                store.set({
+                    patch: { loading: false, error: error instanceof Error ? error.message : 'Failed to load media' },
+                });
+                // Retry reads only, never destructive writes. Keep trying at a capped delay so
+                // recovery needs no manual repair, while an offline service isn't hammered.
+                if (isRetryableMediaError({ error })) {
+                    const delay = Math.min(1000 * 2 ** Math.min(retryAttempt++, 5), 30000);
+                    retryTimer = setTimeout(() => { retryTimer = null; void load(); }, delay);
+                }
+            }
+        }
+        finally {
+            if (ticket === generation)
+                store.set({ patch: { loading: false } });
+        }
+    }
+    let writes = Promise.resolve();
+    let exclusiveWrite = false;
+    function write(run, id) {
+        if (store.signal.aborted || exclusiveWrite || (id === undefined ? store.getSnapshot().busy : store.getSnapshot().pendingIds.includes(id)))
+            return Promise.resolve(false);
+        if (id === undefined)
+            exclusiveWrite = true;
+        // Serialize accepted writes rather than dropping another card's click. Reserve
+        // each id immediately so a double click on the same asset cannot enqueue twice.
+        store.set({ patch: { busy: true, pendingIds: id === undefined ? store.getSnapshot().pendingIds : [...store.getSnapshot().pendingIds, id] } });
+        const operation = writes.then(async () => {
+            if (store.signal.aborted)
+                return false;
+            // Starting a write clears other writes' failures, so a stale failure from one must
+            // not survive past the start of an unrelated one.
+            generation++;
+            readAbort?.abort();
+            cancelRetry();
+            store.set({ patch: { loading: false, error: null } });
+            try {
+                await run();
+                if (store.signal.aborted)
+                    return false;
+                await load();
+                return true;
+            }
+            catch (error) {
+                if (!store.signal.aborted)
+                    store.set({ patch: { loading: false, error: error instanceof Error ? error.message : 'Media write failed' } });
+                return false;
+            }
+            finally {
+                if (id === undefined)
+                    exclusiveWrite = false;
+                const pendingIds = store.getSnapshot().pendingIds.filter(value => value !== id);
+                store.set({ patch: { busy: pendingIds.length > 0, pendingIds } });
+            }
+        });
+        writes = operation.catch(() => undefined);
+        return operation;
+    }
+    return {
+        getSnapshot: store.getSnapshot,
+        subscribe: store.subscribe,
+        load,
+        async setQuery({ query }, _optional = {}) {
+            // Already-fetched full library owns display order/filtering. Tab/search/order changes
+            // never spend another request or flash a loading zero badge.
+            store.set({ patch: { query, ...(library ? { items: queryMedia({ media: library, query }) } : {}) } });
+            if (!library || readFailed)
+                await load();
+        },
+        async upload({ input, alt = '' }, _optional = {}) {
+            return write(() => api.upload(input, { alt, signal: store.signal }));
+        },
+        // Trashing (the reversible first rung of the ladder) has no confirm step — only
+        // the irreversible purge step gates on the dialog, matching the original asymmetry.
+        async trash({ id }, _optional = {}) {
+            return write(() => api.trash({ id }, { signal: store.signal }), id);
+        },
+        async restore({ id }, _optional = {}) {
+            if (!canRestoreMedia({ api })) {
+                store.set({ patch: { error: 'Restoring media is unavailable' } });
+                return false;
+            }
+            return write(() => api.restore({ id }, { signal: store.signal }), id);
+        },
+        requestPurge({ item }, _optional = {}) {
+            if (!store.getSnapshot().busy && item.status === 'trashed')
+                store.set({ patch: { pendingPurge: item } });
+        },
+        cancelPurge(_required = {}, _optional = {}) {
+            if (!store.getSnapshot().busy)
+                store.set({ patch: { pendingPurge: null } });
+        },
+        async confirmPurge({ confirmed }, _optional = {}) {
+            const item = store.getSnapshot().pendingPurge;
+            if (!confirmed || !item)
+                return false;
+            const saved = await write(async () => {
+                const result = await api.delete({ id: item.id }, { signal: store.signal });
+                if (!result.purged)
+                    throw new Error('The file was not permanently deleted');
+                // A failed follow-up read must not leave a permanently deleted card focusable.
+                if (library) {
+                    library = library.filter(row => row.id !== item.id);
+                    store.set({ patch: { items: queryMedia({ media: library, query: store.getSnapshot().query }), counts: countMediaTabs({ media: library }) } });
+                }
+            });
+            if (saved)
+                store.set({ patch: { pendingPurge: null } });
+            return saved;
+        },
+        dispose(_required = {}, _optional = {}) {
+            generation++;
+            cancelRetry();
+            readAbort?.abort();
+            store.dispose();
+        },
+    };
+}
+//# sourceMappingURL=library.controller.js.map

package/dist/media/controllers/providers.controller.d.ts

@@ -0,0 +1,30 @@
+import type { MediaProvidersPort } from '../ports.js';
+import type { MediaProvider } from '../models.js';
+export declare function createProvidersController({ api }: {
+    api: MediaProvidersPort;
+}, _optional?: Record<string, never>): {
+    getSnapshot: () => Readonly<{
+        items: readonly MediaProvider[];
+        loading: boolean;
+        saving: boolean;
+        error: string | null;
+    }>;
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }) => () => void;
+    load: (_required?: Record<string, never>, _optional?: Record<string, never>) => Promise<void>;
+    save({ id, credential }: {
+        id: string;
+        credential: string;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+    saveSettings({ id, baseUrl, model }: {
+        id: string;
+        baseUrl: string;
+        model: string;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+    remove({ id }: {
+        id: string;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+    dispose(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+};
+//# sourceMappingURL=providers.controller.d.ts.map

package/dist/media/controllers/providers.controller.js

@@ -0,0 +1,76 @@
+import { createControllerStore } from '../../core/module/controller-store.js';
+export function createProvidersController({ api }, _optional = {}) {
+    const store = createControllerStore({
+        initial: {
+            items: [],
+            loading: false,
+            saving: false,
+            error: null,
+        },
+    });
+    let generation = 0;
+    async function load(_required = {}, _optional = {}) {
+        if (store.signal.aborted)
+            return;
+        const ticket = ++generation;
+        store.set({ patch: { loading: true } });
+        try {
+            const items = await api.list({}, { signal: store.signal });
+            // null leaves local edits untouched; [] is an authoritative empty answer.
+            if (ticket === generation)
+                store.set({
+                    patch: items === null
+                        ? { error: 'Provider service unavailable' }
+                        : { items: Object.freeze([...items]), error: null },
+                });
+        }
+        catch {
+            if (ticket === generation)
+                store.set({ patch: { error: 'Provider service unavailable' } });
+        }
+        finally {
+            if (ticket === generation)
+                store.set({ patch: { loading: false } });
+        }
+    }
+    async function write(run) {
+        if (store.signal.aborted || store.getSnapshot().saving)
+            return false;
+        store.set({ patch: { saving: true, error: null } });
+        try {
+            await run();
+            if (store.signal.aborted)
+                return false;
+            await load();
+            return true;
+        }
+        catch {
+            store.set({ patch: { error: 'Failed to save provider credentials' } });
+            return false;
+        }
+        finally {
+            store.set({ patch: { saving: false } });
+        }
+    }
+    return {
+        getSnapshot: store.getSnapshot,
+        subscribe: store.subscribe,
+        load,
+        save({ id, credential }, _optional = {}) {
+            return write(() => api.saveCredential({ id, credential }, { signal: store.signal }));
+        },
+        saveSettings({ id, baseUrl, model }, _optional = {}) {
+            if (!api.saveSettings)
+                return Promise.resolve(false);
+            return write(() => api.saveSettings({ id, baseUrl, model }, { signal: store.signal }));
+        },
+        remove({ id }, _optional = {}) {
+            return write(() => api.removeCredential({ id }, { signal: store.signal }));
+        },
+        dispose(_required = {}, _optional = {}) {
+            generation++;
+            store.dispose();
+        },
+    };
+}
+//# sourceMappingURL=providers.controller.js.map

package/dist/media/html-attributes.d.ts

@@ -0,0 +1,82 @@
+/** Browser-only live metadata hint, separate from server validation across the browser/Node
+ * boundary. The server must enforce the same policy on writes and rendering independently.
+ * Hints never gate Save: an invalid attribute once silently blocked saving unrelated title/alt/
+ * caption/credit/class changes. Rejections must instead reach the authoritative atomic write.
+ * One flat allowlist includes global and image/video extras: per-element name filtering is
+ * unnecessary because an unused loading attribute on a wrapper is harmless. Extend the list,
+ * not the tokenizer, when adding an allowed name. data-/aria- families remain open-ended. */
+export declare const MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES: readonly ["class", "id", "style", "title", "role", "tabindex", "lang", "dir", "hidden", "translate", "draggable", "loading", "decoding", "playsinline", "muted", "loop", "autoplay", "poster"];
+/** Whether `name` is on the allowlist — a well-formed attribute name
+ *  ({@link MEDIA_HTML_ATTRIBUTE_NAME_PATTERN}) that is either an exact match against
+ *  {@link MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES} or carries a `data-`/`aria-` prefix (both open-ended
+ *  families with no fixed suffix list). Case-insensitive: HTML attribute names are themselves
+ *  case-insensitive, and an operator typing `DATA-FOO` should not slip past a lowercase-only check.
+ *
+ * @complexity O(n) in the name's length (one anchored regex test), then O(1) — one prefix check,
+ * one fixed-length array lookup.
+ */
+export declare function isAllowedMediaHtmlAttributeName({ name }: {
+    name: string;
+}, _optional?: Record<string, never>): boolean;
+/** Why one parsed attribute token was rejected — see {@link parseMediaHtmlAttributes}'s own doc for
+ *  why `event-handler`/`unsafe-url` are checked, and reported, ahead of plain allowlist membership.
+ *  `unsafe-url` replaces the old `javascript-url` name (2026-09-23: it now also covers
+ *  `vbscript:`/`data:` schemes, not just `javascript:`) — the i18n message key for it is unchanged.
+ *  `unsafe-style` is new: a `style` value carrying a known CSS injection/escape vector. */
+export type MediaHtmlAttributeRejectionReason = "disallowed-name" | "event-handler" | "unsafe-url" | "unsafe-style" | "malformed";
+export interface MediaHtmlAttributeError {
+    reason: MediaHtmlAttributeRejectionReason;
+    /** The exact attribute name (or, for `malformed`, the unparsable fragment) the caller's error
+     *  message must name — never a generic "invalid input" (owner requirement: a visible, specific
+     *  error naming the rejected attribute). */
+    attribute: string;
+}
+export interface ParsedMediaHtmlAttributes {
+    /** Lowercased attribute name -> value, for every token that WAS accepted. Never all-or-nothing
+     *  except on `malformed` (see {@link parseMediaHtmlAttributes}'s own header): a rejected token
+     *  (2026-09-23) is simply absent here while every other accepted token in the same string still
+     *  lands. A boolean attribute (`muted`, written with no `="..."`) maps to `""`. */
+    attributes: Record<string, string>;
+    /** Every rejection found, in the order encountered — zero or more (2026-09-23). Unlike
+     *  `attributes`, this is never reset to empty except that a `malformed` entry is always the last
+     *  one recorded (parsing stops there). */
+    errors: MediaHtmlAttributeError[];
+    /** The FIRST rejection in {@link errors}, or `null` when every token was accepted — kept as its
+     *  own field for the existing single-reason hint consumers (`MediaEditDialog.hooks.tsx`,
+     *  `use-edit-media-panel.hooks.ts`) that only ever show one reason at a time. */
+    error: MediaHtmlAttributeError | null;
+}
+/**
+ * Parses the `HTML attributes` field's free text (`name="value" name2="value2"`, or a bare
+ * boolean `name`) into a validated attribute map, per-token (ported 2026-09-23 from the shared
+ * server parser, `html-attributes.ts`'s `parseEmbedHtmlAttributes`): an accepted token lands in
+ * `attributes`, a rejected one lands in `errors` and is simply omitted — this string never fails
+ * closed as a whole EXCEPT when the tokenizer itself loses sync (a stray quote or other unparseable
+ * fragment), in which case `attributes` is `{}` and the sole entry in `errors` has
+ * `reason: "malformed"` (token boundaries downstream of a sync loss cannot be trusted — value text
+ * could re-parse as a name — so that one case still discards everything).
+ *
+ * This is a SECURITY boundary, not a syntax convenience: media metadata is authored in this admin
+ * but rendered on the public site, so a free-text HTML-attribute passthrough is a stored-XSS vector
+ * (`onerror`, `onclick`, `href="javascript:"`, any `on*` handler, an unsafe `style` value) the
+ * moment it reaches a public page. The allowlist in {@link isAllowedMediaHtmlAttributeName} is
+ * therefore the ONLY path to acceptance — nothing here tries to sanitize or escape an otherwise-
+ * disallowed name or value into something safe; it is rejected outright, and the caller must show
+ * the reason (not silently drop it) so an operator can tell a typo from a hard "no". NOTE: this
+ * validator runs in the admin only — see this repo's media-admin-ui report for where the write and
+ * render paths that would actually persist and emit this attribute still need the SAME allowlist
+ * enforced server-side (a client-only check is not a control, since the API accepts whatever a
+ * caller sends).
+ *
+ * @complexity Time O(n) in `text`'s length (one regex pass over it), space O(k) for k accepted
+ *   attributes plus O(e) for e rejected tokens.
+ */
+export declare function parseMediaHtmlAttributes({ text }: {
+    text: string;
+}, _optional?: Record<string, never>): ParsedMediaHtmlAttributes;
+/** The hint names the rejected token so operators can distinguish a typo from a hard no.
+ * This is client feedback only; the server must independently enforce write/render policy. */
+export declare function describeMediaHtmlAttributeError({ error }: {
+    error: MediaHtmlAttributeError;
+}, _optional?: Record<string, never>): string;
+//# sourceMappingURL=html-attributes.d.ts.map

package/dist/media/html-attributes.js

@@ -0,0 +1,204 @@
+/** Browser-only live metadata hint, separate from server validation across the browser/Node
+ * boundary. The server must enforce the same policy on writes and rendering independently.
+ * Hints never gate Save: an invalid attribute once silently blocked saving unrelated title/alt/
+ * caption/credit/class changes. Rejections must instead reach the authoritative atomic write.
+ * One flat allowlist includes global and image/video extras: per-element name filtering is
+ * unnecessary because an unused loading attribute on a wrapper is harmless. Extend the list,
+ * not the tokenizer, when adding an allowed name. data-/aria- families remain open-ended. */
+export const MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES = [
+    // Global attributes (2026-09-23).
+    "class",
+    "id",
+    "style",
+    "title",
+    "role",
+    "tabindex",
+    "lang",
+    "dir",
+    "hidden",
+    "translate",
+    "draggable",
+    // Pre-existing <img>/<video> extras, kept everywhere (one list, not one per element).
+    "loading",
+    "decoding",
+    "playsinline",
+    "muted",
+    "loop",
+    "autoplay",
+    "poster",
+];
+/**
+ * The shape EVERY accepted attribute name must have, checked before allowlist membership
+ * (2026-09-07 stored-XSS fix; keep identical in `@jini-ai/cms/media`'s `html-attributes.ts` — see
+ * that file's copy of this comment for the full incident).
+ *
+ * The `data-`/`aria-` families below are open-ended by design — no fixed suffix list — so the
+ * prefix check alone accepted whatever characters {@link HTML_ATTRIBUTE_TOKEN}'s name class
+ * (`[^\s="']+`, which excludes only whitespace, `=` and quotes) let through. `<`, `>` and `/` are
+ * all legal in that class, and the server renderer templating a name into ` name="value"` escapes
+ * only the VALUE — so a stored `data-x><svg/onload=alert(1)` closed the `<img>` and opened a live
+ * `<svg onload>` on the public page. Constraining the NAME to the characters a real HTML attribute
+ * name can contain is what makes "the value is escaped" sufficient.
+ */
+const MEDIA_HTML_ATTRIBUTE_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** Whether `name` is on the allowlist — a well-formed attribute name
+ *  ({@link MEDIA_HTML_ATTRIBUTE_NAME_PATTERN}) that is either an exact match against
+ *  {@link MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES} or carries a `data-`/`aria-` prefix (both open-ended
+ *  families with no fixed suffix list). Case-insensitive: HTML attribute names are themselves
+ *  case-insensitive, and an operator typing `DATA-FOO` should not slip past a lowercase-only check.
+ *
+ * @complexity O(n) in the name's length (one anchored regex test), then O(1) — one prefix check,
+ * one fixed-length array lookup.
+ */
+export function isAllowedMediaHtmlAttributeName({ name }, _optional = {}) {
+    const lower = name.toLowerCase();
+    if (!MEDIA_HTML_ATTRIBUTE_NAME_PATTERN.test(lower))
+        return false;
+    if (lower.startsWith("data-") || lower.startsWith("aria-"))
+        return true;
+    return MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES.includes(lower);
+}
+/** Matches one `name`, or one `name="value"`/`name='value'`/`name=value` pair — the same loose
+ *  shape real HTML attribute syntax allows, since that is the syntax an operator typing this field
+ *  would naturally reach for. */
+const HTML_ATTRIBUTE_TOKEN = /([^\s="']+)(?:=(?:"([^"]*)"|'([^']*)'|([^\s"']+)))?/g;
+/** The highest ASCII code point {@link isUnsafeMediaUrlValue} strips: every C0 control character
+ *  plus the ordinary space, i.e. code points `0`-`32` inclusive. Named rather than written as an
+ *  inline regex control-character range so the linter never has to reason about a literal control
+ *  character inside a pattern. Ported from the shared server parser, `html-attributes.ts`. */
+const ASCII_WHITESPACE_OR_CONTROL_MAX_CODE_POINT = 0x20;
+/**
+ * Whether `value`'s scheme, once every ASCII whitespace/control character (code points `0`-`32`) is
+ * stripped and the result lowercased, starts with `javascript:`, `vbscript:` or `data:` — the three
+ * schemes a browser will still execute or navigate to even when the URL carries interior whitespace
+ * a naive end-trim (the old `.trim()`-only check) would miss, e.g. `java\tscript:x`: browsers strip
+ * tabs and newlines from inside a URL before parsing its scheme, so this check must too. Ported
+ * 2026-09-23 from the shared server parser's `isUnsafeUrlValue` (`html-attributes.ts`).
+ *
+ * @complexity O(n) in the value's length (one filter pass, one prefix test).
+ */
+function isUnsafeMediaUrlValue(value) {
+    let stripped = "";
+    for (const char of value) {
+        if ((char.codePointAt(0) ?? 0) > ASCII_WHITESPACE_OR_CONTROL_MAX_CODE_POINT)
+            stripped += char;
+    }
+    stripped = stripped.toLowerCase();
+    return stripped.startsWith("javascript:") || stripped.startsWith("vbscript:") || stripped.startsWith("data:");
+}
+/**
+ * Whether a `style` value carries a known CSS injection or CSS-escape-bypass vector:
+ * `expression(...)` (legacy IE script-in-CSS), a `javascript:`/`vbscript:` value inside a CSS
+ * `url(...)`, `-moz-binding`/`behavior:` (XBL/HTC script bindings), `@import` (pulls in a second,
+ * unvetted stylesheet), or ANY backslash — a CSS escape sequence (`\65` is `e`) can respell any of
+ * the above past a plain substring check, so a backslash anywhere in the value is rejected outright.
+ * Plain `url(...)` values (background images) are otherwise allowed. Ported 2026-09-23 from the
+ * shared server parser's `isUnsafeStyleValue` (`html-attributes.ts`).
+ *
+ * @complexity O(n) in the value's length (one regex test).
+ */
+const UNSAFE_MEDIA_STYLE_PATTERN = /expression\(|javascript:|vbscript:|-moz-binding|behavior:|@import|\\/i;
+function isUnsafeMediaStyleValue(value) {
+    return UNSAFE_MEDIA_STYLE_PATTERN.test(value);
+}
+/** Classifies one already-tokenized `name`/`value` pair. Split out of {@link parseMediaHtmlAttributes}
+ *  so each rejection reason is its own directly testable branch, and so the loop below reads as
+ *  "tokenize, then classify" rather than one function doing both.
+ *
+ * Order matters (ported 2026-09-23 from the shared server parser's `classifyEmbedHtmlAttributeToken`):
+ * `on*` is checked FIRST (so an `onerror` always reports as `event-handler`, the more actionable
+ * reason, never the generic `disallowed-name`), then the URL-scheme check runs against EVERY value
+ * regardless of name (matching the pre-existing `javascript:` check this is ported from), then
+ * allowlist membership, then — only for an already-allowed `style` — the CSS-specific unsafe-value
+ * check.
+ *
+ * @complexity O(1) — four fixed checks against one already-extracted token; each check's own O(n) in
+ * the token's length is linear, not nested.
+ */
+function classifyMediaHtmlAttributeToken(name, value) {
+    if (name.startsWith("on"))
+        return { reason: "event-handler", attribute: name };
+    if (isUnsafeMediaUrlValue(value))
+        return { reason: "unsafe-url", attribute: name };
+    if (!isAllowedMediaHtmlAttributeName({ name }))
+        return { reason: "disallowed-name", attribute: name };
+    if (name === "style" && isUnsafeMediaStyleValue(value))
+        return { reason: "unsafe-style", attribute: name };
+    return null;
+}
+/**
+ * Parses the `HTML attributes` field's free text (`name="value" name2="value2"`, or a bare
+ * boolean `name`) into a validated attribute map, per-token (ported 2026-09-23 from the shared
+ * server parser, `html-attributes.ts`'s `parseEmbedHtmlAttributes`): an accepted token lands in
+ * `attributes`, a rejected one lands in `errors` and is simply omitted — this string never fails
+ * closed as a whole EXCEPT when the tokenizer itself loses sync (a stray quote or other unparseable
+ * fragment), in which case `attributes` is `{}` and the sole entry in `errors` has
+ * `reason: "malformed"` (token boundaries downstream of a sync loss cannot be trusted — value text
+ * could re-parse as a name — so that one case still discards everything).
+ *
+ * This is a SECURITY boundary, not a syntax convenience: media metadata is authored in this admin
+ * but rendered on the public site, so a free-text HTML-attribute passthrough is a stored-XSS vector
+ * (`onerror`, `onclick`, `href="javascript:"`, any `on*` handler, an unsafe `style` value) the
+ * moment it reaches a public page. The allowlist in {@link isAllowedMediaHtmlAttributeName} is
+ * therefore the ONLY path to acceptance — nothing here tries to sanitize or escape an otherwise-
+ * disallowed name or value into something safe; it is rejected outright, and the caller must show
+ * the reason (not silently drop it) so an operator can tell a typo from a hard "no". NOTE: this
+ * validator runs in the admin only — see this repo's media-admin-ui report for where the write and
+ * render paths that would actually persist and emit this attribute still need the SAME allowlist
+ * enforced server-side (a client-only check is not a control, since the API accepts whatever a
+ * caller sends).
+ *
+ * @complexity Time O(n) in `text`'s length (one regex pass over it), space O(k) for k accepted
+ *   attributes plus O(e) for e rejected tokens.
+ */
+export function parseMediaHtmlAttributes({ text }, _optional = {}) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return { attributes: {}, errors: [], error: null };
+    const attributes = {};
+    const errors = [];
+    HTML_ATTRIBUTE_TOKEN.lastIndex = 0;
+    let consumed = 0;
+    // A `for` loop (rather than `while ((match = …exec(trimmed)) !== null)`) keeps every assignment
+    // to `match` in statement position, never inside the loop's own test expression.
+    for (let match = HTML_ATTRIBUTE_TOKEN.exec(trimmed); match !== null; match = HTML_ATTRIBUTE_TOKEN.exec(trimmed)) {
+        // Non-whitespace text between the previous match and this one is a fragment the token pattern
+        // could not parse as a name (e.g. a stray quote) — the tokenizer has lost sync, so everything
+        // parsed so far is discarded rather than trusted.
+        const skipped = trimmed.slice(consumed, match.index);
+        if (skipped.trim() !== "") {
+            const malformed = { reason: "malformed", attribute: skipped.trim() };
+            errors.push(malformed);
+            return { attributes: {}, errors, error: malformed };
+        }
+        consumed = match.index + match[0].length;
+        const name = match[1].toLowerCase();
+        const value = match[2] ?? match[3] ?? match[4] ?? "";
+        const rejection = classifyMediaHtmlAttributeToken(name, value);
+        if (rejection) {
+            errors.push(rejection);
+            continue;
+        }
+        attributes[name] = value;
+    }
+    const trailing = trimmed.slice(consumed);
+    if (trailing.trim() !== "") {
+        const malformed = { reason: "malformed", attribute: trailing.trim() };
+        errors.push(malformed);
+        return { attributes: {}, errors, error: malformed };
+    }
+    return { attributes, errors, error: errors[0] ?? null };
+}
+/** The hint names the rejected token so operators can distinguish a typo from a hard no.
+ * This is client feedback only; the server must independently enforce write/render policy. */
+export function describeMediaHtmlAttributeError({ error }, _optional = {}) {
+    const name = error.attribute;
+    switch (error.reason) {
+        case 'event-handler': return `Event handler attributes like '${name}' are not allowed.`;
+        case 'unsafe-url': return `'${name}' cannot use a javascript: value.`;
+        case 'unsafe-style': return `'${name}' cannot use an unsafe style value.`;
+        case 'malformed': return `Could not parse HTML attributes near '${name}'.`;
+        default: return `'${name}' is not an allowed HTML attribute.`;
+    }
+}
+//# sourceMappingURL=html-attributes.js.map

package/dist/media/index.d.ts

@@ -0,0 +1,12 @@
+export { mediaModule } from './media.module.js';
+export { mediaApiToken, mediaProvidersToken } from './ports.js';
+export type { MediaApiPort, MediaProvidersPort, MediaEventsPort } from './ports.js';
+export type { MediaAsset, MediaQuery, UploadInput, MediaMetadataPatch, MediaRequestOptions, MediaProvider, MediaProviderOption, MediaProviderConfiguration, MediaProviderConfigurationMap, MediaTabId, MediaContentTabId, MediaOrderBy, } from './models.js';
+export { mediaMessagesEn } from './messages.en.js';
+export { filterMediaByTab, resolveActiveTab, queryMedia, diffMediaMetadata, acceptsMedia, safeMediaUrl, canReplaceMedia, canRestoreMedia, isRetryableMediaError, parseOptionalPixelSize, formatByteSize, formatUploadDate, countMediaTabs, mediaEmbedSnippet, mediaRowHandles, } from './rules.js';
+export { createLibraryController } from './controllers/library.controller.js';
+export type { LibraryState } from './controllers/library.controller.js';
+export { createEditMediaController } from './controllers/edit-media.controller.js';
+export { createProvidersController } from './controllers/providers.controller.js';
+export { parseMediaHtmlAttributes, describeMediaHtmlAttributeError, isAllowedMediaHtmlAttributeName, MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES } from './html-attributes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/media/index.js

@@ -0,0 +1,9 @@
+export { mediaModule } from './media.module.js';
+export { mediaApiToken, mediaProvidersToken } from './ports.js';
+export { mediaMessagesEn } from './messages.en.js';
+export { filterMediaByTab, resolveActiveTab, queryMedia, diffMediaMetadata, acceptsMedia, safeMediaUrl, canReplaceMedia, canRestoreMedia, isRetryableMediaError, parseOptionalPixelSize, formatByteSize, formatUploadDate, countMediaTabs, mediaEmbedSnippet, mediaRowHandles, } from './rules.js';
+export { createLibraryController } from './controllers/library.controller.js';
+export { createEditMediaController } from './controllers/edit-media.controller.js';
+export { createProvidersController } from './controllers/providers.controller.js';
+export { parseMediaHtmlAttributes, describeMediaHtmlAttributeError, isAllowedMediaHtmlAttributeName, MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES } from './html-attributes.js';
+//# sourceMappingURL=index.js.map