portal-mojo 0.1.0

package/src/ui/FormWizard.tsx

@@ -0,0 +1,336 @@
+import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import type { Field, FormData } from '../client/types';
+import { modal, type ModalSize } from './modal';
+import { firstErrorName, SchemaFieldGrid, useSchemaFormState } from './schema-form-core';
+import { Tabs, type TabVariant } from './Tabs';
+
+export interface FormWizardSection {
+    key: string;
+    label: ReactNode;
+    fields: Field[];
+    description?: ReactNode;
+    optional?: boolean;
+    /** Custom content shares the same draft as schema fields. */
+    content?: ReactNode | ((context: FormWizardSectionContext) => ReactNode);
+    /** Removes a step without discarding its draft. */
+    eligible?: (data: FormData) => boolean;
+    /** Runs after validation and before advancing. Rejections stay on this step. */
+    onNext?: (data: FormData) => void | Promise<void>;
+    /** A receipt/status step with no Back/Next/Finish action row. */
+    terminal?: boolean;
+}
+
+export interface FormWizardSectionContext {
+    data: FormData;
+    busy: boolean;
+    setValue: (name: string, value: FormData[string]) => void;
+    patchValues: (patch: FormData) => void;
+}
+
+export interface FormWizardProps {
+    sections: FormWizardSection[];
+    initial?: FormData;
+    resetKey?: unknown;
+    mode: 'wizard' | 'tabs';
+    tabVariant?: TabVariant | 'buttongroup' | 'btngroup' | (string & {});
+    backText?: string;
+    nextText?: string;
+    finishText?: string;
+    saveText?: string;
+    cancelText?: string;
+    busyText?: string;
+    validateAllOnFinish?: boolean;
+    onStepChange?: (sectionKey: string) => void;
+    onBusyChange?: (busy: boolean) => void;
+    onCancel?: () => void;
+    /** Return the authoritative owner row when a section contains File relations. */
+    onFinish: (data: FormData) => unknown | Promise<unknown>;
+    className?: string;
+}
+
+const warnedWizard = new Set<string>();
+function warnWizardOnce(key: string, message: string): void {
+    if (warnedWizard.has(key)) return;
+    warnedWizard.add(key);
+    console.warn(message);
+}
+
+export function normalizeWizardMode(mode: string): 'wizard' | 'tabs' {
+    if (mode === 'wizard' || mode === 'tabs') return mode;
+    warnWizardOnce(`mode:${mode}`, `FormWizard: unknown mode "${mode}" — falling back to "tabs"`);
+    return 'tabs';
+}
+
+export function normalizeWizardSections(sections: FormWizardSection[]): FormWizardSection[] {
+    const sectionKeys = new Set<string>();
+    const fieldNames = new Set<string>();
+    const result: FormWizardSection[] = [];
+    for (const section of sections) {
+        if (!section.key || sectionKeys.has(section.key)) {
+            warnWizardOnce(`section:${section.key || '<empty>'}`, `FormWizard: ${section.key ? `duplicate section key "${section.key}"` : 'empty section key'} ignored`);
+            continue;
+        }
+        sectionKeys.add(section.key);
+        const fields = section.fields.filter((field) => {
+            if (!field.name || fieldNames.has(field.name)) {
+                warnWizardOnce(`field:${field.name || '<empty>'}`, `FormWizard: ${field.name ? `duplicate field name "${field.name}"` : 'empty field name'} ignored`);
+                return false;
+            }
+            fieldNames.add(field.name);
+            return true;
+        });
+        result.push({ ...section, fields });
+    }
+    return result;
+}
+
+export function healWizardSection(activeKey: string | null, sections: FormWizardSection[]): string | null {
+    return sections.some((section) => section.key === activeKey) ? activeKey : sections[0]?.key ?? null;
+}
+
+export function createWizardSingleFlight() {
+    let pending = false;
+    return {
+        get pending() { return pending; },
+        async run<T>(task: () => T | Promise<T>): Promise<T | undefined> {
+            if (pending) return undefined;
+            pending = true;
+            try {
+                return await task();
+            } finally {
+                pending = false;
+            }
+        },
+    };
+}
+
+export function FormWizard(props: FormWizardProps) {
+    const {
+        sections: rawSections,
+        initial = {},
+        resetKey,
+        tabVariant,
+        onStepChange,
+        onCancel,
+        onFinish,
+        className,
+    } = props;
+    const normalizedSections = useMemo(() => normalizeWizardSections(rawSections), [rawSections]);
+    const fields = useMemo(() => normalizedSections.flatMap((section) => section.fields), [normalizedSections]);
+    const mode = normalizeWizardMode(props.mode as string);
+    const [activeKey, setActiveKey] = useState<string | null>(() => normalizedSections[0]?.key ?? null);
+    const activeKeyRef = useRef(activeKey);
+    activeKeyRef.current = activeKey;
+    const [busy, setBusy] = useState(false);
+    const setWizardBusy = (next: boolean) => {
+        props.onBusyChange?.(next);
+        setBusy(next);
+    };
+    const finishFlight = useRef(createWizardSingleFlight());
+    const transitionFlight = useRef(createWizardSingleFlight());
+    const generation = useRef(0);
+    const mounted = useRef(true);
+    const resetRef = useRef(resetKey);
+    const form = useSchemaFormState({ fields, initial, profile: 'wizard', reconcile: true, resetKey, deferReconcile: busy });
+    const sections = normalizedSections.filter((section) => section.eligible?.(form.values) !== false);
+    const locked = busy || form.uploadPending;
+
+    useEffect(() => props.onBusyChange?.(locked), [locked, props.onBusyChange]);
+
+    useEffect(() => {
+        generation.current += 1;
+        transitionFlight.current = createWizardSingleFlight();
+        if (busy) setWizardBusy(false);
+        // resetKey is the generation boundary; busy changes must not create one.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [resetKey]);
+
+    useEffect(() => () => {
+        mounted.current = false;
+        generation.current += 1;
+    }, []);
+
+    useEffect(() => {
+        if (busy) return;
+        const resetChanged = !Object.is(resetRef.current, resetKey);
+        const healed = resetChanged ? sections[0]?.key ?? null : healWizardSection(activeKey, sections);
+        resetRef.current = resetKey;
+        if (healed !== activeKeyRef.current) {
+            activeKeyRef.current = healed;
+            setActiveKey(healed);
+            if (!resetChanged && healed) onStepChange?.(healed);
+        }
+    }, [activeKey, busy, onStepChange, resetKey, sections]);
+
+    const activeIndex = Math.max(0, sections.findIndex((section) => section.key === activeKey));
+    const activeSection = sections[activeIndex] ?? null;
+
+    const go = (key: string) => {
+        if (locked || key === activeKeyRef.current || !sections.some((section) => section.key === key)) return;
+        activeKeyRef.current = key;
+        setActiveKey(key);
+        onStepChange?.(key);
+    };
+
+    const validateAndFocus = (targetFields: Field[], sectionPool: FormWizardSection[]): boolean => {
+        const errors = form.validate(targetFields);
+        const firstName = firstErrorName(targetFields, errors);
+        if (!firstName) return true;
+        const targetSection = sectionPool.find((section) => section.fields.some((field) => field.name === firstName));
+        if (targetSection && targetSection.key !== activeKey) setActiveKey(targetSection.key);
+        form.focusField(firstName);
+        return false;
+    };
+
+    const next = async () => {
+        if (form.uploadPending) return;
+        if (transitionFlight.current.pending) return;
+        if (!activeSection || !validateAndFocus(activeSection.fields, [activeSection])) return;
+        const following = sections[activeIndex + 1];
+        if (!following) return;
+        const acceptedGeneration = generation.current;
+        if (!activeSection.onNext) {
+            go(following.key);
+            return;
+        }
+        setWizardBusy(true);
+        form.setFormError('');
+        try {
+            await transitionFlight.current.run(() => activeSection.onNext!(form.payload(fields)));
+            if (mounted.current && generation.current === acceptedGeneration) go(following.key);
+        } catch (error) {
+            if (mounted.current && generation.current === acceptedGeneration) {
+                form.setFormError(error instanceof Error ? error.message : 'Could not continue');
+            }
+        } finally {
+            if (mounted.current && generation.current === acceptedGeneration) setWizardBusy(false);
+        }
+    };
+
+    const finish = async () => {
+        if (form.uploadPending) return;
+        if (finishFlight.current.pending || !activeSection) return;
+        const validationSections = props.validateAllOnFinish === false ? [activeSection] : sections;
+        const validationFields = validationSections.flatMap((section) => section.fields);
+        if (!validateAndFocus(validationFields, validationSections)) return;
+
+        // Capture the accepted roster and payload before any parent update.
+        const acceptedFields = [...fields];
+        const payload = form.payload(acceptedFields);
+        const acceptedGeneration = generation.current;
+        setWizardBusy(true);
+        form.setFormError('');
+        try {
+            const row = await finishFlight.current.run(() => onFinish(payload));
+            form.settleOwnerSave(row, false, payload);
+        } catch (error) {
+            form.settleOwnerSave(undefined, true, payload);
+            if (mounted.current && generation.current === acceptedGeneration) form.setFormError(error instanceof Error ? error.message : 'Save failed');
+        } finally {
+            if (mounted.current && generation.current === acceptedGeneration) setWizardBusy(false);
+        }
+    };
+
+    if (!sections.length) {
+        return <div className={className ? `form-wizard ${className}` : 'form-wizard'}><div className="form-wizard-empty">No sections available.</div></div>;
+    }
+
+    const sectionPanel = (section: FormWizardSection) => (
+        <div className="form-wizard-section">
+            {section.description && <div className="form-wizard-description">{section.description}</div>}
+            <SchemaFieldGrid fields={section.fields} state={form} disabled={busy} />
+            {typeof section.content === 'function' ? section.content({
+                data: form.values, busy: locked, setValue: form.setValue, patchValues: form.patchValues,
+            }) : section.content}
+        </div>
+    );
+
+    return (
+        <div className={className ? `form-wizard ${className}` : 'form-wizard'} aria-busy={locked || undefined}>
+            {form.formError && <div className="form-alert" role="alert">{form.formError}</div>}
+            {mode === 'tabs' ? (
+                <Tabs
+                    variant={tabVariant}
+                    ariaLabel="Form sections"
+                    activeKey={activeKey}
+                    onActiveKeyChange={go}
+                    items={sections.map((section) => ({
+                        key: section.key,
+                        label: <>{section.label}{section.optional && <span className="form-wizard-optional"> Optional</span>}</>,
+                        disabled: busy || form.uploadPending,
+                        panel: sectionPanel(section),
+                    }))}
+                />
+            ) : (
+                <>
+                    <ol className="form-wizard-progress" aria-label="Form progress">
+                        {sections.map((section, index) => (
+                            <li key={section.key} className={index === activeIndex ? 'is-active' : index < activeIndex ? 'is-complete' : ''} aria-current={index === activeIndex ? 'step' : undefined}>
+                                <span className="form-wizard-step-number">{index + 1}</span>
+                                <span>{section.label}</span>
+                            </li>
+                        ))}
+                    </ol>
+                    {activeSection && sectionPanel(activeSection)}
+                </>
+            )}
+            {!activeSection?.terminal && <div className="modal-actions form-wizard-actions">
+                {onCancel && <button type="button" className="btn" disabled={locked} onClick={onCancel}>{props.cancelText ?? 'Cancel'}</button>}
+                {mode === 'wizard' && activeIndex > 0 && (
+                    <button type="button" className="btn" disabled={locked} onClick={() => go(sections[activeIndex - 1]!.key)}>{props.backText ?? 'Back'}</button>
+                )}
+                {mode === 'wizard' && activeIndex < sections.length - 1 ? (
+                    <button type="button" className="btn btn-primary" disabled={locked} onClick={() => void next()}>{props.nextText ?? 'Next'}</button>
+                ) : (
+                    <button type="button" className="btn btn-primary" disabled={locked} onClick={finish}>
+                        {busy ? props.busyText ?? 'Saving…' : mode === 'tabs' ? props.saveText ?? 'Save' : props.finishText ?? 'Finish'}
+                    </button>
+                )}
+            </div>}
+        </div>
+    );
+}
+
+export type FormWizardModalOptions = Omit<FormWizardProps, 'onCancel'> & { title: string; size?: ModalSize };
+
+export function formWizardModal(options: FormWizardModalOptions): Promise<FormData | null> {
+    let pending = false;
+    let finishing = false;
+    let live = true;
+    return modal.open<FormData>((close) => (
+        <div className="modal-pad">
+            <h2 className="modal-title">{options.title}</h2>
+            <FormWizard
+                {...options}
+                onBusyChange={(busy) => {
+                    pending = busy;
+                    options.onBusyChange?.(busy);
+                }}
+                onCancel={() => {
+                    if (pending) return;
+                    live = false;
+                    close(null as unknown as FormData);
+                }}
+                onFinish={async (data) => {
+                    if (finishing) return;
+                    finishing = true;
+                    pending = true;
+                    try {
+                        const row = await options.onFinish(data);
+                        if (live) {
+                            live = false;
+                            close(data);
+                        }
+                        return row;
+                    } finally {
+                        finishing = false;
+                        pending = false;
+                    }
+                }}
+            />
+        </div>
+    ), { size: options.size, canDismiss: () => !pending }).then((result) => {
+        live = false;
+        return result;
+    });
+}

package/src/ui/GroupSwitcher.tsx

@@ -0,0 +1,202 @@
+// GroupSwitcher — the searchable, hierarchical group selector. Ported from
+// web-mojo GroupSearchView (tree build from flat rows incl. embedded parent
+// objects, name-sorted levels, └/├/│ line segments, kind chips) on
+// SimpleSearchView's mechanics (300ms debounced server-side search).
+// Selection drives the A3 GroupProvider: storage + `?group=` URL param +
+// member fetch all follow from setActiveGroup.
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { useActiveGroup } from '../client/group';
+import type { Group } from '../client/group-context';
+import { useModelList } from '../client/hooks';
+
+interface FlatNode {
+    group: Group;
+    level: number;
+    isLastChild: boolean;
+    /** For each ancestor level: does its vertical line continue past this row? */
+    verticals: boolean[];
+    hasChildren: boolean;
+}
+
+/** GroupSearchView.buildTreeHierarchy + flattenTree + computeVerticalLines. */
+export function buildGroupTree(items: Group[]): FlatNode[] {
+    if (items.length === 0) return [];
+    interface Node { group: Group; children: Node[] }
+    const byId = new Map<number, Node>();
+    // First pass: every row, plus parents embedded on rows (a matched child
+    // whose parent didn't match the search still renders under it).
+    for (const item of items) {
+        if (!byId.has(item.id)) byId.set(item.id, { group: item, children: [] });
+    }
+    for (const item of items) {
+        const parent = item.parent;
+        if (parent && parent.id && !byId.has(parent.id)) {
+            byId.set(parent.id, { group: { kind: 'group', ...parent } as Group, children: [] });
+        }
+    }
+    const roots: Node[] = [];
+    for (const node of byId.values()) {
+        const parentId = node.group.parent?.id;
+        if (parentId != null && byId.has(parentId) && parentId !== node.group.id) {
+            byId.get(parentId)!.children.push(node);
+        } else {
+            roots.push(node);
+        }
+    }
+    const byName = (a: Node, b: Node) => (a.group.name || '').localeCompare(b.group.name || '');
+    roots.sort(byName);
+
+    const flat: FlatNode[] = [];
+    const walk = (nodes: Node[], level: number, ancestorsLast: boolean[]) => {
+        nodes.sort(byName);
+        nodes.forEach((node, i) => {
+            const isLastChild = i === nodes.length - 1;
+            flat.push({ group: node.group, level, isLastChild, verticals: [], hasChildren: node.children.length > 0 });
+            if (node.children.length > 0) walk(node.children, level + 1, [...ancestorsLast, isLastChild]);
+        });
+    };
+    walk(roots, 0, []);
+
+    // Second pass: a vertical line continues at segment s when a later row at
+    // level s+1 appears before the walk returns to level ≤ s.
+    for (let i = 0; i < flat.length; i++) {
+        const node = flat[i]!;
+        for (let s = 0; s < node.level; s++) {
+            let found = false;
+            for (let j = i + 1; j < flat.length; j++) {
+                const later = flat[j]!;
+                if (later.level === s + 1) { found = true; break; }
+                if (later.level <= s) break;
+            }
+            node.verticals[s] = found;
+        }
+    }
+    return flat;
+}
+
+function TreeLines({ node }: { node: FlatNode }) {
+    if (node.level === 0) return null;
+    return (
+        <span className="tree-lines">
+            {Array.from({ length: node.level }, (_, s) => {
+                const last = s === node.level - 1;
+                const cls = last
+                    ? (node.isLastChild ? 'tree-seg tree-seg-last' : 'tree-seg tree-seg-mid')
+                    : (node.verticals[s] ? 'tree-seg tree-seg-vert' : 'tree-seg');
+                return <span key={s} className={cls} />;
+            })}
+        </span>
+    );
+}
+
+export function GroupSwitcher({ onSelected, onCleared }: {
+    /** After a group activates — e.g. navigate into the group menu's home. */
+    onSelected?: (group: Group) => void;
+    /** After the active group clears — e.g. navigate back to the main menu. */
+    onCleared?: () => void;
+} = {}) {
+    const { group, loading, setActiveGroup, clearActiveGroup } = useActiveGroup();
+    const [open, setOpen] = useState(false);
+    const [input, setInput] = useState('');
+    const [term, setTerm] = useState('');
+    const wrapRef = useRef<HTMLDivElement>(null);
+    const searchRef = useRef<HTMLInputElement>(null);
+
+    // SimpleSearchView parity: 300ms debounce into the server-side search.
+    useEffect(() => {
+        const t = setTimeout(() => setTerm(input.trim()), 300);
+        return () => clearTimeout(t);
+    }, [input]);
+
+    useEffect(() => {
+        if (!open) return;
+        searchRef.current?.focus();
+        // 'click', not 'mousedown': a listener attached while the opening
+        // click is still dispatching never sees that same event, so the
+        // opener can't self-close (mousedown-arming raced automation/fast
+        // double-events into instant closes).
+        const onDocClick = (e: MouseEvent) => {
+            if (wrapRef.current && !wrapRef.current.contains(e.target as Node)) setOpen(false);
+        };
+        const onKey = (e: KeyboardEvent) => {
+            if (e.key === 'Escape') setOpen(false);
+        };
+        document.addEventListener('click', onDocClick);
+        document.addEventListener('keydown', onKey);
+        return () => {
+            document.removeEventListener('click', onDocClick);
+            document.removeEventListener('keydown', onKey);
+        };
+    }, [open]);
+
+    const list = useModelList<Group>('/api/group', { search: term || undefined, sort: 'name', size: 50 });
+    const tree = useMemo(() => buildGroupTree(list.data?.rows ?? []), [list.data]);
+
+    const pick = (g: Group) => {
+        setActiveGroup(g);
+        setOpen(false);
+        setInput('');
+        onSelected?.(g);
+    };
+
+    return (
+        <div className="group-switch-wrap" ref={wrapRef}>
+            <button
+                className={`group-btn${group ? ' group-btn-active' : ''}`}
+                onClick={() => setOpen((v) => !v)}
+                aria-haspopup="listbox"
+                aria-expanded={open}
+                title={group ? `Active group: ${group.name}` : 'Select active group'}
+            >
+                <i className={`bi ${group ? 'bi-diagram-3-fill' : 'bi-diagram-3'}`} />
+                <span className="group-btn-label">
+                    {loading ? 'Loading…' : group ? group.name : 'All groups'}
+                </span>
+                {group && <span className="chip chip-primary group-kind">{group.kind}</span>}
+                <i className="bi bi-chevron-expand group-caret" />
+            </button>
+            {open && (
+                <div className="group-menu" role="listbox">
+                    <div className="search-box search-box-fill group-menu-search">
+                        <i className="bi bi-search" />
+                        <input
+                            ref={searchRef}
+                            value={input}
+                            placeholder="Search groups…"
+                            onChange={(e) => setInput(e.target.value)}
+                        />
+                    </div>
+                    <div className="group-menu-list">
+                        {group && (
+                            <button className="group-row group-row-clear" onClick={() => { clearActiveGroup(); setOpen(false); onCleared?.(); }}>
+                                <i className="bi bi-x-circle" /> Clear active group
+                            </button>
+                        )}
+                        {list.isLoading && (
+                            <div className="group-menu-loading">
+                                <span className="skel" /><span className="skel" /><span className="skel" />
+                            </div>
+                        )}
+                        {!list.isLoading && tree.length === 0 && (
+                            <div className="group-menu-empty">No groups match “{term}”</div>
+                        )}
+                        {tree.map((node) => (
+                            <button
+                                key={node.group.id}
+                                className={`group-row${group?.id === node.group.id ? ' group-row-active' : ''}`}
+                                onClick={() => pick(node.group)}
+                                role="option"
+                                aria-selected={group?.id === node.group.id}
+                            >
+                                <TreeLines node={node} />
+                                <span className="group-row-name">{node.group.name}</span>
+                                <span className="group-row-kind">{node.group.kind}</span>
+                                {group?.id === node.group.id && <i className="bi bi-check-lg" />}
+                            </button>
+                        ))}
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+}

package/src/ui/Guarded.tsx

@@ -0,0 +1,16 @@
+// Permission-gated slot. Fail-closed: renders the fallback (default nothing)
+// while `me` loads, while anonymous, and when the check fails. UX gating
+// only — the server stays authoritative on every request it receives.
+import type { ReactNode } from 'react';
+import { useCan } from '../client/me';
+
+export function Guarded({ permission, fallback = null, children }: {
+    /** Permission name(s); an array means ANY-of. `admin` and superuser always pass. */
+    permission: string | string[];
+    /** Rendered when the check fails (default: nothing). */
+    fallback?: ReactNode;
+    children: ReactNode;
+}) {
+    const { can } = useCan(permission);
+    return <>{can ? children : fallback}</>;
+}

package/src/ui/MarkdownView.tsx

@@ -0,0 +1,89 @@
+// MarkdownView — render markdown the platform way: django-mojo's docit
+// renderer does the work, an allowlist sanitizer vets the answer, and a
+// dependency-free client renderer covers everything else.
+//
+// The one sanctioned `dangerouslySetInnerHTML` in portal-mojo lives here, and
+// the ONLY string it can ever receive is the output of `renderMarkdown`, which
+// sanitizes before it resolves (client/markdown-sanitize.ts spells out the
+// trust model). Everything else on screen is React elements.
+//
+// No loading jump, by construction:
+//   1. Already rendered this exact source? The cache answers synchronously and
+//      the server HTML is on the FIRST frame — no request, no transition.
+//   2. Otherwise the client fallback paints immediately (real content at
+//      roughly the right height, marked `aria-busy`), and the server HTML
+//      swaps in underneath the same wrapper when it lands.
+//   3. If the render fails, the fallback simply stays — with one console.warn
+//      saying why. There is no empty state and no spinner at any point.
+import { useEffect, useState } from 'react';
+import { MarkdownFallback, peekMarkdown, renderMarkdown } from '../client/markdown';
+
+export interface MarkdownViewProps {
+    /** The markdown source. */
+    source: string;
+    /**
+     * 'server' (default) asks /api/docit/render and sanitizes the answer;
+     * 'client' never touches the wire — for previews of text being typed, and
+     * for surfaces that must not fan out one request per item.
+     */
+    renderer?: 'server' | 'client';
+    /**
+     * Wait this long after the source stops changing before calling the server.
+     * Leave at 0 for static content; set it for text that grows token by token
+     * (a streaming assistant reply) so one reply is one request, not hundreds.
+     */
+    debounceMs?: number;
+    /** Extra classes on the wrapper; `md` is always present. */
+    className?: string;
+}
+
+export function MarkdownView({ source, renderer = 'server', debounceMs = 0, className }: MarkdownViewProps) {
+    const [served, setServed] = useState<{ source: string; html: string } | null>(null);
+    const [failedFor, setFailedFor] = useState<string | null>(null);
+
+    // Derived, never mirrored into state: a cache hit must win on the first
+    // frame, and it must re-evaluate when `source` changes. In client mode it
+    // is always null — flipping to 'client' must not keep showing server HTML
+    // that a previous 'server' pass had already resolved.
+    const html =
+        renderer === 'server'
+            ? peekMarkdown(source) ?? (served?.source === source ? served.html : null)
+            : null;
+
+    useEffect(() => {
+        if (renderer !== 'server' || !source.trim()) return;
+        if (peekMarkdown(source) !== null) return;
+
+        let cancelled = false;
+        const run = () => {
+            renderMarkdown(source).then(
+                (out) => { if (!cancelled) setServed({ source, html: out }); },
+                (err: unknown) => {
+                    if (cancelled) return;
+                    // The fallback is already on screen — this only records why
+                    // it is what the reader is looking at.
+                    console.warn('[MarkdownView] server render failed, keeping the client fallback:', err);
+                    setFailedFor(source);
+                },
+            );
+        };
+
+        if (debounceMs > 0) {
+            const timer = setTimeout(run, debounceMs);
+            return () => { cancelled = true; clearTimeout(timer); };
+        }
+        run();
+        return () => { cancelled = true; };
+    }, [source, renderer, debounceMs]);
+
+    const pending = renderer === 'server' && !!source.trim() && html === null && failedFor !== source;
+    const cls = ['md', pending ? 'md-pending' : null, className].filter(Boolean).join(' ');
+
+    // Sanitized at its source (renderMarkdown) — see the trust model above.
+    if (html !== null) return <div className={cls} dangerouslySetInnerHTML={{ __html: html }} />;
+    return (
+        <div className={cls} aria-busy={pending || undefined}>
+            <MarkdownFallback source={source} />
+        </div>
+    );
+}