portal-mojo 0.2.8 → 0.2.9

package/src/admin/storage/MediaRenderingPage.tsx

@@ -0,0 +1,258 @@
+// Storage → Media rendering (#7729): edit the three FILEMAN_RENDITIONS_*
+// settings as a form built from django-mojo's rendition descriptor. See
+// docs/admin-media-rendering.md for the contract and the invariants.
+import { useMemo, useState } from 'react';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { Badge, Tabs, modal, toast } from '../../ui';
+import type { SettingRow } from '../settings/model';
+import { renditionRoleLabel } from './file-renditions';
+import {
+    RENDITION_OPTIONS_ENDPOINT, AUTOMATIC_KEY, MP4_ONLY_OPTIONS, coerceFieldValue, draftToValue, fieldType, findCategoryRows,
+    hidesMp4Options, isDefaultValue, orderedCategories, readRenditionOptions, renditionCategoryLabel, resetCategory,
+    routeRenditionError, sameOverride, sameValue, saveCategoryValue, validateDraft, valueToDraft,
+    type CategoryDraft, type RenditionCategory, type RenditionOptions,
+} from './rendition-settings';
+
+const OPTIONS_QUERY_KEY = ['fileman', 'renditions', 'options'] as const;
+const rowQueryKey = (key: string) => ['settings', 'rendition-row', key] as const;
+
+const FIELD_LABELS: Record<string, string> = {
+    width: 'Width', height: 'Height', mode: 'Mode', format: 'Format', quality: 'Quality', time_offset: 'Frame at',
+    bitrate: 'Bitrate', codec: 'Codec', crf: 'CRF', preset: 'Preset', duration: 'Seconds', audio: 'Audio', page: 'Page', max_pages: 'Max pages',
+};
+const PLACEHOLDERS: Record<string, string> = { bitrate: '2000k', time_offset: 'HH:MM:SS' };
+// Display order only — membership always comes from the descriptor's `fields[kind]` (served sorted).
+const FIELD_ORDER = ['width', 'height', 'mode', 'format', 'quality', 'time_offset', 'page', 'max_pages', 'bitrate', 'codec', 'crf', 'preset', 'duration', 'audio'];
+
+function orderFields(names: readonly string[]): string[] {
+    const rank = (name: string) => { const at = FIELD_ORDER.indexOf(name); return at === -1 ? FIELD_ORDER.length : at; };
+    return [...names].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+}
+
+function fieldLabel(name: string): string {
+    return FIELD_LABELS[name] ?? name.replace(/_/g, ' ');
+}
+
+function displayValue(value: unknown): string {
+    if (value === null || value === undefined || value === '') return 'not set';
+    return typeof value === 'boolean' ? (value ? 'on' : 'off') : String(value);
+}
+
+interface FieldProps {
+    category: RenditionCategory;
+    draft: CategoryDraft;
+    role: string;
+    kind: string;
+    name: string;
+    error: string | undefined;
+    disabled: boolean;
+    onChange: (name: string, value: unknown) => void;
+}
+
+function RoleField({ category, draft, role, kind, name, error, disabled, onChange }: FieldProps) {
+    const type = fieldType(category, kind, name);
+    const value = draft.roles[role]?.[name];
+    const fallback = category.defaults[role]?.[name];
+    const effective = category.effective.roles[role]?.[name];
+    const isDefault = isDefaultValue(category, draft, role, name);
+    const inEffect = !sameValue(effective, value) && effective !== undefined ? effective : undefined;
+    const id = `media-rendering-${category.key}-${role}-${name}`;
+    const className = `media-rendering-field${error ? ' is-invalid' : isDefault ? ' is-default' : ' is-changed'}`;
+    const title = `Default: ${displayValue(fallback)}`;
+    const help = error ?? (inEffect !== undefined ? `In effect: ${displayValue(inEffect)} (deployment file)` : undefined);
+    let control;
+    if (type === 'boolean') {
+        control = <span className="media-rendering-field-switch">
+            <input id={id} type="checkbox" role="switch" className="switch" checked={value === true} disabled={disabled} title={title} onChange={(event) => onChange(name, event.target.checked)} />
+            <span className="dim">{value === true ? 'on' : 'off'}</span>
+        </span>;
+    } else if (type === 'choice') {
+        const choices = category.choices[kind]?.[name] ?? [];
+        const current = typeof value === 'string' ? value : '';
+        control = <select id={id} className="input" value={current} disabled={disabled} title={title} onChange={(event) => onChange(name, event.target.value)}>
+            <option value="">{fallback === undefined ? 'renderer default' : 'not set'}</option>
+            {!choices.includes(current) && current !== '' && <option value={current}>{current}</option>}
+            {choices.map((choice) => <option key={choice} value={choice}>{choice}</option>)}
+        </select>;
+    } else if (type === 'number') {
+        const [min, max] = category.limits[name] ?? [undefined, undefined];
+        control = <input id={id} className="input" type="number" inputMode="numeric" min={min} max={max} step={1} disabled={disabled} title={title}
+            placeholder={fallback === undefined ? 'renderer default' : String(fallback)} value={typeof value === 'number' ? value : ''}
+            onChange={(event) => onChange(name, event.target.value)} />;
+    } else {
+        control = <input id={id} className="input" type="text" disabled={disabled} title={title} autoComplete="off" spellCheck={false}
+            placeholder={PLACEHOLDERS[name] ?? (fallback === undefined ? 'renderer default' : String(fallback))} value={typeof value === 'string' ? value : ''}
+            onChange={(event) => onChange(name, event.target.value)} />;
+    }
+    return <div className={className}>
+        <label className="field-label" htmlFor={id}>{fieldLabel(name)}</label>
+        {control}
+        {help && <span className={`field-help${error ? ' text-bad' : ''}`} role={error ? 'alert' : undefined}>{help}</span>}
+    </div>;
+}
+
+function CategoryPanel({ category, categoryKey }: { category: RenditionCategory; categoryKey: string }) {
+    const queryClient = useQueryClient();
+    const rowsQuery = useQuery({ queryKey: rowQueryKey(category.key), queryFn: () => findCategoryRows(category.key), retry: false, refetchOnWindowFocus: false });
+    const rows = rowsQuery.data ?? [];
+    const row: SettingRow | null = rows[0] ?? null;
+    const duplicates = rows.length > 1;
+    const [draft, setDraft] = useState<CategoryDraft>(() => valueToDraft(category, category.override));
+    const [errors, setErrors] = useState<Record<string, string>>({});
+    const [formError, setFormError] = useState('');
+    const [busy, setBusy] = useState(false);
+    const roles = Object.keys(category.defaults);
+    const value = useMemo(() => draftToValue(category, draft), [category, draft]);
+    const dirty = !sameOverride(value, category.override);
+    // Hints wear the same slot and wording as a routed 400: the reason only, the role.field prefix is the label.
+    const hints = useMemo(() => Object.fromEntries(validateDraft(category, draft).map((entry) => [`${entry.role}.${entry.field}`, routeRenditionError(entry.message).message])), [category, draft]);
+    const hasH265 = roles.some((role) => category.defaults[role]?.codec === 'h265');
+
+    const change = (role: string, name: string, raw: unknown) => {
+        const kind = category.role_kinds[role] ?? '';
+        const typed = coerceFieldValue(fieldType(category, kind, name), raw);
+        setDraft((current) => ({ ...current, roles: { ...current.roles, [role]: { ...current.roles[role], [name]: typed } } }));
+        setErrors((current) => { const next = { ...current }; delete next[`${role}.${name}`]; delete next[role]; return next; });
+        setFormError('');
+    };
+    const toggleAutomatic = (role: string, on: boolean) => {
+        setDraft((current) => ({ ...current, automatic: on ? [...current.automatic.filter((entry) => entry !== role), role] : current.automatic.filter((entry) => entry !== role) }));
+        setErrors((current) => { const next = { ...current }; delete next[AUTOMATIC_KEY]; return next; });
+        setFormError('');
+    };
+    const refresh = async () => {
+        await Promise.all([
+            queryClient.invalidateQueries({ queryKey: OPTIONS_QUERY_KEY }),
+            queryClient.invalidateQueries({ queryKey: rowQueryKey(category.key) }),
+        ]);
+    };
+    const fail = (reason: unknown) => {
+        const message = reason instanceof Error ? reason.message : 'The rendition settings could not be saved';
+        const routed = routeRenditionError(message, [...roles, AUTOMATIC_KEY]);
+        if (routed.role === null) { setFormError(routed.message); return; }
+        const key = routed.field ? `${routed.role}.${routed.field}` : routed.role;
+        setErrors((current) => ({ ...current, [key]: routed.message }));
+    };
+    const save = async () => {
+        setBusy(true); setFormError(''); setErrors({});
+        try {
+            await saveCategoryValue(category, row, value);
+            toast.success(`${renditionCategoryLabel(categoryKey)} rendering saved`);
+            await refresh();
+        } catch (reason) {
+            fail(reason);
+        } finally {
+            setBusy(false);
+        }
+    };
+    const reset = async () => {
+        const ok = await modal.confirm({
+            title: `Reset ${renditionCategoryLabel(categoryKey).toLowerCase()} rendering to defaults?`,
+            message: 'Every role goes back to the framework defaults and the default set of roles runs on upload. Existing files are not touched.',
+            confirmText: 'Reset to defaults',
+            danger: true,
+        });
+        if (!ok) return;
+        setBusy(true); setFormError(''); setErrors({});
+        try {
+            await resetCategory(category, row);
+            toast.success(`${renditionCategoryLabel(categoryKey)} rendering reset to defaults`);
+            await refresh();
+        } catch (reason) {
+            fail(reason);
+        } finally {
+            setBusy(false);
+        }
+    };
+
+    const disabled = busy || duplicates || rowsQuery.isPending;
+    return <div className="media-rendering-panel">
+        {hasH265 && <p className="media-rendering-note">
+            <b>H.265 (HEVC)</b> encodes take several times longer than H.264 and do not play in every browser. Keep <code>video_mp4</code> as the H.264 compatibility rendition and enable <code>video_hevc</code> on upload only when the extra encode time is worth it.
+        </p>}
+        {rowsQuery.error && <div className="form-alert" role="alert">The current override could not be read: {rowsQuery.error.message} <button className="btn btn-compact" onClick={() => void rowsQuery.refetch()}>Retry</button></div>}
+        {duplicates && <div className="form-alert" role="alert">
+            More than one global row exists for <code>{category.key}</code> (ids {rows.map((entry) => entry.id).join(', ')}). The server reads an undefined one, so this page will not edit them; remove the duplicates on the server first.
+        </div>}
+        {formError && <div className="form-alert" role="alert">{formError}</div>}
+        <div className="media-rendering-roles">
+            {roles.map((role) => {
+                const kind = category.role_kinds[role] ?? '';
+                const hideMp4 = hidesMp4Options(category, draft, role);
+                const names = orderFields(category.fields[kind] ?? Object.keys(category.defaults[role] ?? {})).filter((name) => !(hideMp4 && (MP4_ONLY_OPTIONS as readonly string[]).includes(name)));
+                const roleError = errors[role];
+                const automatic = draft.automatic.includes(role);
+                const automaticDefault = category.automatic_default.includes(role);
+                const automaticEffective = category.effective.automatic.includes(role);
+                const rowHasError = Boolean(roleError) || names.some((name) => errors[`${role}.${name}`]);
+                return <div key={role} className={`media-rendering-role${rowHasError ? ' has-error' : ''}`}>
+                    <div className="media-rendering-role-head">
+                        <b>{renditionRoleLabel(role)}</b>
+                        <code>{role}</code>
+                        <span><Badge tone="muted">{kind || 'option'}</Badge></span>
+                    </div>
+                    <div className="media-rendering-fields">
+                        {names.map((name) => <RoleField key={name} category={category} draft={draft} role={role} kind={kind} name={name}
+                            error={errors[`${role}.${name}`] ?? hints[`${role}.${name}`]} disabled={disabled} onChange={(field, raw) => change(role, field, raw)} />)}
+                    </div>
+                    <div className="media-rendering-upload">
+                        <label className={automatic === automaticDefault ? 'dim' : undefined}>
+                            <input type="checkbox" role="switch" className="switch" checked={automatic} disabled={disabled} onChange={(event) => toggleAutomatic(role, event.target.checked)} />
+                            Runs on upload
+                        </label>
+                        {automatic !== automaticEffective && <span className="field-help">In effect: {automaticEffective ? 'runs' : 'does not run'} (deployment file)</span>}
+                    </div>
+                    {roleError && <p className="media-rendering-role-error" role="alert">{roleError}</p>}
+                </div>;
+            })}
+        </div>
+        {errors[AUTOMATIC_KEY] && <div className="form-alert" role="alert">Runs on upload: {errors[AUTOMATIC_KEY]}</div>}
+        <div className="media-rendering-actions">
+            <button className="btn btn-primary" disabled={disabled || !dirty} onClick={() => void save()}>{busy ? 'Saving…' : 'Save'}</button>
+            <button className="btn" disabled={disabled || !row || category.override == null} onClick={() => void reset()}>Reset to defaults…</button>
+            <span className="dim">{row ? `Override row #${row.id}` : 'No override row yet — Save creates one.'}</span>
+        </div>
+    </div>;
+}
+
+function MediaRenderingContent({ options }: { options: RenditionOptions }) {
+    const categories = orderedCategories(options);
+    const items = categories.map((categoryKey) => {
+        const category = options.categories[categoryKey]!;
+        return {
+            key: categoryKey,
+            label: renditionCategoryLabel(categoryKey),
+            // Remount the panel whenever the override changes so the draft reseeds from the saved row.
+            panel: <CategoryPanel key={`${category.key}:${JSON.stringify(category.override ?? null)}`} category={category} categoryKey={categoryKey} />,
+        };
+    });
+    if (!items.length) return <div className="panel panel-pad">The backend declares no configurable rendition categories.</div>;
+    return <Tabs items={items} variant="underline" ariaLabel="Media rendering categories" />;
+}
+
+export function MediaRenderingPage() {
+    const query = useQuery({ queryKey: OPTIONS_QUERY_KEY, queryFn: readRenditionOptions, retry: false, refetchOnWindowFocus: false });
+    return <div className="page media-rendering-page">
+        <header className="page-header">
+            <div>
+                <div className="eyebrow">Infrastructure · Storage</div>
+                <h1>Media rendering</h1>
+                <p className="dim media-rendering-hint">
+                    How thumbnails, previews and transcodes are produced, and which run after an upload. Only values that differ from the framework defaults are stored.
+                    Changing these options does not touch existing files — open a file under Storage → Files and use <b>Regenerate renditions</b> to see the result.
+                </p>
+            </div>
+        </header>
+        {query.isPending && <div className="panel panel-pad">Loading rendition options…</div>}
+        {query.error && <div className="panel panel-pad">
+            <div className="form-alert" role="alert">{query.error.message}</div>
+            <button className="btn" onClick={() => void query.refetch()}>Retry</button>
+        </div>}
+        {query.data && <div className="panel panel-pad">
+            <MediaRenderingContent options={query.data} />
+            <p className="dim media-rendering-engine" style={{ marginTop: 14 }}>
+                Video engine: <code>{query.data.engine.effective}</code> ({query.data.engine.key} — edit on the Settings page when another engine exists). Descriptor: <code>{RENDITION_OPTIONS_ENDPOINT}</code>.
+            </p>
+        </div>}
+    </div>;
+}

package/src/admin/storage/file-renditions.ts

@@ -97,3 +97,15 @@ export async function pollRenditionConvergence(args: {
     }
     return 'timeout';
 }
+
+const ROLE_ACRONYMS = new Set(['hevc', 'mp4', 'webm', 'pdf']);
+
+/** `video_hevc` → "Video HEVC", `thumbnail_sm` → "Thumbnail sm". Display only; the role key is the identity. */
+export function renditionRoleLabel(role: string): string {
+    const words = role.split('_').filter(Boolean);
+    if (!words.length) return role;
+    return words.map((word, index) => {
+        if (ROLE_ACRONYMS.has(word)) return word.toUpperCase();
+        return index === 0 ? word.charAt(0).toUpperCase() + word.slice(1) : word;
+    }).join(' ');
+}

package/src/admin/storage/index.ts

@@ -10,5 +10,7 @@ export * from './FileUploadSurface';
 export * from './FileView';
 export * from './FilePreview';
 export * from './storage-dialogs';
+export * from './rendition-settings';
+export * from './MediaRenderingPage';
 
 export { STORAGE_ADMIN_SECTION } from '../domains/infrastructure';

package/src/admin/storage/rendition-settings.ts

@@ -0,0 +1,264 @@
+// Media rendering settings (#7729): the data layer behind the Storage →
+// Media rendering page. Reads django-mojo's rendition descriptor
+// (`GET /api/fileman/renditions/options`, fileman #7728) and writes the three
+// FILEMAN_RENDITIONS_* settings through the ordinary `/api/settings` REST.
+//
+// Everything about roles, fields, choices and limits comes from the
+// descriptor. The ONE rule this module hardcodes is the mp4-only trio
+// (`codec`/`crf`/`preset`), which the server refuses on a non-mp4 role.
+import { mojoCall, mojoList, mojoSave, withFreshAuth } from '../../client/runtime';
+import type { SettingRow } from '../settings/model';
+
+export type RenditionCategoryKey = 'image' | 'video' | 'document';
+export type RenditionFieldType = 'number' | 'boolean' | 'choice' | 'string';
+export type RenditionRoleOptions = Record<string, unknown>;
+
+export interface RenditionCategory {
+    key: string;
+    defaults: Record<string, RenditionRoleOptions>;
+    automatic_default: string[];
+    /** The global DATABASE row, parsed, or null. A deployment-file value is applied but never reported here. */
+    override: Record<string, unknown> | null;
+    effective: { roles: Record<string, RenditionRoleOptions>; automatic: string[] };
+    role_kinds: Record<string, string>;
+    fields: Record<string, string[]>;
+    choices: Record<string, Record<string, string[]>>;
+    limits: Record<string, [number, number]>;
+}
+
+export interface RenditionOptions {
+    categories: Partial<Record<RenditionCategoryKey, RenditionCategory>> & Record<string, RenditionCategory>;
+    engine: { key: string; choices: string[]; effective: string };
+}
+
+export interface CategoryDraft {
+    roles: Record<string, RenditionRoleOptions>;
+    automatic: string[];
+}
+
+export interface RenditionFieldError {
+    role: string;
+    field: string | null;
+    message: string;
+}
+
+/** A routed server refusal: `role` null = panel-level, `_automatic` = the upload switches. */
+export interface RoutedRenditionError {
+    role: string | null;
+    field: string | null;
+    message: string;
+}
+
+export const RENDITION_OPTIONS_ENDPOINT = '/api/fileman/renditions/options';
+export const RENDITION_CATEGORY_ORDER: RenditionCategoryKey[] = ['image', 'video', 'document'];
+export const RENDITION_CATEGORY_LABELS: Record<RenditionCategoryKey, string> = { image: 'Images', video: 'Video', document: 'Documents' };
+export const AUTOMATIC_KEY = '_automatic';
+/** Options only an mp4 transcode accepts; the server refuses them on a webm role (`config.MP4_ONLY_OPTIONS`). */
+export const MP4_ONLY_OPTIONS = ['codec', 'crf', 'preset'] as const;
+const BITRATE_RE = /^\d+[kKmM]?$/;
+const TIME_OFFSET_RE = /^\d{2}:\d{2}:\d{2}(\.\d+)?$/;
+
+export function renditionCategoryLabel(category: string): string {
+    const label = (RENDITION_CATEGORY_LABELS as Record<string, string>)[category];
+    if (label) return label;
+    console.warn(`Media rendering: unknown rendition category "${category}" — rendering its raw key`);
+    return category;
+}
+
+/** The categories to render, in house order, then any the descriptor adds. */
+export function orderedCategories(options: RenditionOptions): string[] {
+    const served = Object.keys(options.categories);
+    const known = RENDITION_CATEGORY_ORDER.filter((category) => served.includes(category));
+    return [...known, ...served.filter((category) => !(RENDITION_CATEGORY_ORDER as string[]).includes(category))];
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export async function readRenditionOptions(): Promise<RenditionOptions> {
+    const body = await mojoCall(RENDITION_OPTIONS_ENDPOINT);
+    const data = body.data as RenditionOptions | undefined;
+    if (!data || !isPlainObject(data.categories)) throw new Error('Rendition options returned an unsupported response');
+    for (const [category, descriptor] of Object.entries(data.categories)) {
+        if (!descriptor || typeof descriptor.key !== 'string' || !isPlainObject(descriptor.defaults) || !isPlainObject(descriptor.role_kinds) || !isPlainObject(descriptor.fields)) {
+            throw new Error(`Rendition options for "${category}" are incomplete`);
+        }
+    }
+    return data;
+}
+
+/**
+ * The global rows for a category key. The options endpoint does not carry a
+ * row id, so one list read finds the row to update. Raw `mojoList` on
+ * purpose: `SettingModel.normalizeListParams` strips `key`.
+ */
+export async function findCategoryRows(key: string): Promise<SettingRow[]> {
+    const { rows } = await mojoList<SettingRow>('/api/settings', { key, group__isnull: true, size: 10 });
+    return rows.filter((row) => row.key === key && row.group == null).sort((a, b) => a.id - b.id);
+}
+
+/** The one typing rule: render, coerce, compare, validate and emit all use it. */
+export function fieldType(category: RenditionCategory, kind: string, name: string): RenditionFieldType {
+    // Choices first: the server lists a limit for every option NAME it bounds anywhere in the
+    // category, so document `quality` (a choice on pdf roles) also appears under `limits`.
+    if (category.choices[kind]?.[name]) return 'choice';
+    if (name in category.limits) return 'number';
+    const boolean = Object.entries(category.defaults).some(([role, options]) => category.role_kinds[role] === kind && typeof options[name] === 'boolean');
+    return boolean ? 'boolean' : 'string';
+}
+
+/** Coerce a raw control value into the draft's typed value (`null` = unset). */
+export function coerceFieldValue(type: RenditionFieldType, raw: unknown): unknown {
+    if (raw === '' || raw == null) return null;
+    if (type === 'number') {
+        const value = typeof raw === 'number' ? raw : Number(String(raw).trim());
+        return Number.isFinite(value) ? value : null;
+    }
+    if (type === 'boolean') return raw === true || raw === 'true';
+    return String(raw);
+}
+
+function isSet(value: unknown): boolean {
+    return value !== null && value !== undefined && value !== '';
+}
+
+/** Draft = defaults shallow-merged with the override. Never seeded from `effective` (see the page docs). */
+export function valueToDraft(category: RenditionCategory, value: Record<string, unknown> | null | undefined): CategoryDraft {
+    const override = isPlainObject(value) ? value : {};
+    const roles: Record<string, RenditionRoleOptions> = {};
+    for (const [role, base] of Object.entries(category.defaults)) {
+        const extra = override[role];
+        roles[role] = { ...base, ...(isPlainObject(extra) ? extra : {}) };
+    }
+    const automatic = override[AUTOMATIC_KEY];
+    return {
+        roles,
+        automatic: Array.isArray(automatic)
+            ? automatic.filter((role): role is string => typeof role === 'string' && role in category.defaults)
+            : [...category.automatic_default],
+    };
+}
+
+export function roleFormat(category: RenditionCategory, draft: CategoryDraft, role: string): string | null {
+    const value = draft.roles[role]?.format ?? category.defaults[role]?.format;
+    return typeof value === 'string' ? value : null;
+}
+
+/** Whether a kind carries the mp4-only trio and this role's format is not mp4. */
+export function hidesMp4Options(category: RenditionCategory, draft: CategoryDraft, role: string): boolean {
+    const kind = category.role_kinds[role];
+    if (!kind || !category.fields[kind]?.includes('codec')) return false;
+    return (roleFormat(category, draft, role) ?? 'mp4') !== 'mp4';
+}
+
+export function sameValue(a: unknown, b: unknown): boolean {
+    if (!isSet(a) && !isSet(b)) return true;
+    return a === b;
+}
+
+/** True when the draft's value for `role.name` is the default (or unset with no default). */
+export function isDefaultValue(category: RenditionCategory, draft: CategoryDraft, role: string, name: string): boolean {
+    return sameValue(draft.roles[role]?.[name], category.defaults[role]?.[name]);
+}
+
+function sameSet(a: readonly string[], b: readonly string[]): boolean {
+    const left = new Set(a);
+    const right = new Set(b);
+    return left.size === right.size && [...left].every((entry) => right.has(entry));
+}
+
+/** `_automatic` as the server should store it: default order first, additions in `defaults` key order. */
+export function orderedAutomatic(category: RenditionCategory, automatic: readonly string[]): string[] {
+    const chosen = new Set(automatic);
+    const kept = category.automatic_default.filter((role) => chosen.has(role));
+    const added = Object.keys(category.defaults).filter((role) => chosen.has(role) && !category.automatic_default.includes(role));
+    return [...kept, ...added];
+}
+
+/**
+ * The override to write: only options that differ from the defaults, the
+ * mp4-only trio dropped on a non-mp4 role, `_automatic` only when the set
+ * differs from `automatic_default`. `{}` means "defaults".
+ */
+export function draftToValue(category: RenditionCategory, draft: CategoryDraft): Record<string, unknown> {
+    const value: Record<string, unknown> = {};
+    for (const role of Object.keys(category.defaults)) {
+        const kind = category.role_kinds[role] ?? '';
+        const names = category.fields[kind] ?? Object.keys(category.defaults[role] ?? {});
+        const hideMp4 = hidesMp4Options(category, draft, role);
+        const changed: RenditionRoleOptions = {};
+        for (const name of names) {
+            if (hideMp4 && (MP4_ONLY_OPTIONS as readonly string[]).includes(name)) continue;
+            const current = draft.roles[role]?.[name];
+            if (!isSet(current)) continue;
+            if (sameValue(current, category.defaults[role]?.[name])) continue;
+            changed[name] = coerceFieldValue(fieldType(category, kind, name), current);
+        }
+        if (Object.keys(changed).length) value[role] = changed;
+    }
+    if (!sameSet(draft.automatic, category.automatic_default)) value[AUTOMATIC_KEY] = orderedAutomatic(category, draft.automatic);
+    return value;
+}
+
+export function sameOverride(a: Record<string, unknown> | null | undefined, b: Record<string, unknown> | null | undefined): boolean {
+    return JSON.stringify(a ?? {}) === JSON.stringify(b ?? {});
+}
+
+/** Client-side mirror of the server's checks, worded identically. Advisory: the server decides. */
+export function validateDraft(category: RenditionCategory, draft: CategoryDraft): RenditionFieldError[] {
+    const errors: RenditionFieldError[] = [];
+    for (const role of Object.keys(category.defaults)) {
+        const kind = category.role_kinds[role] ?? '';
+        const hideMp4 = hidesMp4Options(category, draft, role);
+        for (const name of category.fields[kind] ?? []) {
+            if (hideMp4 && (MP4_ONLY_OPTIONS as readonly string[]).includes(name)) continue;
+            const current = draft.roles[role]?.[name];
+            if (!isSet(current)) continue;
+            const where = `${role}.${name}`;
+            const type = fieldType(category, kind, name);
+            if (type === 'number') {
+                const [low, high] = category.limits[name]!;
+                if (typeof current !== 'number' || !Number.isInteger(current)) errors.push({ role, field: name, message: `${where}: must be a whole number` });
+                else if (current < low || current > high) errors.push({ role, field: name, message: `${where}: must be between ${low} and ${high}` });
+            } else if (type === 'choice') {
+                const allowed = category.choices[kind]?.[name] ?? [];
+                if (typeof current !== 'string' || !allowed.includes(current)) errors.push({ role, field: name, message: `${where}: must be one of ${allowed.join(', ')}` });
+            } else if (type === 'boolean') {
+                if (typeof current !== 'boolean') errors.push({ role, field: name, message: `${where}: must be true or false` });
+            } else if (name === 'bitrate') {
+                if (typeof current !== 'string' || !BITRATE_RE.test(current)) errors.push({ role, field: name, message: `${where}: must look like 2000k or 2M` });
+            } else if (name === 'time_offset') {
+                if (typeof current !== 'string' || !TIME_OFFSET_RE.test(current)) errors.push({ role, field: name, message: `${where}: must look like HH:MM:SS` });
+            }
+        }
+    }
+    return errors;
+}
+
+/**
+ * Route a server refusal to the thing it names. Grammar (`config.validate`):
+ * `<role>.<option>: …`, `<role>: …`, `_automatic: …`, or anything else
+ * (panel-level).
+ */
+export function routeRenditionError(message: string, knownRoles: readonly string[] = []): RoutedRenditionError {
+    const trimmed = message.trim();
+    const match = /^([A-Za-z0-9_]+)(?:\.([A-Za-z0-9_]+))?:\s*(.+)$/s.exec(trimmed);
+    if (!match) return { role: null, field: null, message: trimmed };
+    const [, role, field, rest] = match;
+    if (role === AUTOMATIC_KEY) return { role: AUTOMATIC_KEY, field: null, message: rest! };
+    if (knownRoles.length && !knownRoles.includes(role!)) return { role: null, field: null, message: trimmed };
+    return { role: role!, field: field ?? null, message: rest! };
+}
+
+/** Create or update the category's global row. Imperative; a failure rejects. */
+export async function saveCategoryValue(category: RenditionCategory, row: SettingRow | null, value: Record<string, unknown>): Promise<SettingRow> {
+    const changes: Record<string, unknown> = row ? { value } : { key: category.key, is_secret: false, group: null, value };
+    return withFreshAuth(() => mojoSave<SettingRow>('/api/settings', row?.id ?? null, changes));
+}
+
+/** Reset = write `{}`. The live Setting model refuses DELETE, and `{}` is reported as `override: null`. */
+export async function resetCategory(category: RenditionCategory, row: SettingRow | null): Promise<SettingRow | null> {
+    if (!row) return null;
+    return saveCategoryValue(category, row, {});
+}

package/src/charts/exportChart.ts

@@ -4,7 +4,7 @@
 // or contains an <svg>.
 //
 // Additions over the source, both needed because portal-mojo charts style
-// through theme.css CLASSES (which a serialized clone loses):
+// through portal-mojo/styles.css CLASSES (which a serialized clone loses):
 //   · computed styles are inlined onto the clone (fixed property list), so
 //     token-driven fills/strokes/fonts survive serialization;
 //   · the backdrop defaults to the nearest ancestor's real background color