@calliopelabs/ui 0.7.0 → 0.12.0

package/dist/workflow/GateBadge.d.ts

@@ -0,0 +1,11 @@
+import { type Gate } from "./run.js";
+export interface GateBadgeProps {
+    gate: Pick<Gate, "label" | "status" | "approvals" | "required">;
+    className?: string;
+}
+/**
+ * A gate in one pill: what it asks, where it stands, and the quorum so far.
+ * The tone is the gate's status: waiting is a warning, approved ok, rejected
+ * an error, expired and skipped muted.
+ */
+export declare function GateBadge({ gate, className }: GateBadgeProps): import("react").JSX.Element;

package/dist/workflow/GateBadge.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useUI } from "../provider/UIProvider.js";
+import { StatusBadge } from "../status/StatusBadge.js";
+import { GATE_TONE } from "./run.js";
+/**
+ * A gate in one pill: what it asks, where it stands, and the quorum so far.
+ * The tone is the gate's status: waiting is a warning, approved ok, rejected
+ * an error, expired and skipped muted.
+ */
+export function GateBadge({ gate, className }) {
+    const { messages } = useUI();
+    return (_jsx(StatusBadge, { tone: GATE_TONE[gate.status], "data-slot": "gate-badge", className: className, children: messages.run.gate(gate.label, gate.status, gate.approvals, gate.required) }));
+}

package/dist/workflow/MediaReview.d.ts

@@ -0,0 +1,63 @@
+import * as React from "react";
+/** A rectangle on an image or a frame, as fractions of its width and height (0 to 1). */
+export interface MediaRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Where a media comment points: a moment, a region, or both (a region of a frame). */
+export interface MediaAnchor {
+    /** Seconds from the start. */
+    time?: number;
+    region?: MediaRegion;
+}
+/** A comment pinned to the media. */
+export interface MediaComment extends MediaAnchor {
+    id: string;
+    author: string;
+    body: string;
+    resolved?: boolean;
+}
+export interface MediaCaptionTrack {
+    src: string;
+    srcLang: string;
+    label: string;
+}
+export interface MediaReviewProps {
+    kind: "video" | "audio" | "image";
+    src: string;
+    /** Names the media: an image's alternative text, a player's label. */
+    title: string;
+    /** A video's still before it plays. */
+    poster?: string;
+    captions?: readonly MediaCaptionTrack[];
+    /** Seconds, for placing markers before the media's metadata loads. */
+    duration?: number;
+    comments: readonly MediaComment[];
+    activeCommentId?: string;
+    /** A marker was chosen: the viewer seeks to it; the host shows the comment. */
+    onCommentSelect?: (comment: MediaComment) => void;
+    /**
+     * The person picked where their next comment points: the current time of a
+     * player, or a region drawn on an image. The host labels it (see
+     * `formatTimecode`) and hands it to ReviewPanel as `commentAnchor`.
+     */
+    onAnchor?: (anchor: MediaAnchor) => void;
+    className?: string;
+}
+/** Seconds as a timecode: "00:01:12". */
+export declare function formatTimecode(seconds: number): string;
+/**
+ * Media review for the media module: a video, audio or image with comments
+ * pinned to timecodes (markers on a rail under the player) or to regions
+ * (boxes over the image). Choosing a marker seeks the player and tells the
+ * host; "comment here" hands the host the current time, and on an image
+ * drawing a box hands it the region. "Mark a region" is the keyboard path on
+ * an image or a video frame: it drops a box that the arrow keys move and
+ * Shift with the arrows size, Enter hands the host the region (with the
+ * current time on a video) and Escape cancels. Plugs into ArtifactCard's
+ * preview and feeds ReviewPanel's anchors. The host supplies the media URL; the viewer
+ * fetches nothing itself beyond what the browser's media element does.
+ */
+export declare function MediaReview({ kind, src, title, poster, captions, duration: durationProp, comments, activeCommentId, onCommentSelect, onAnchor, className, }: MediaReviewProps): React.JSX.Element;

package/dist/workflow/MediaReview.js

@@ -0,0 +1,166 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CrosshairIcon, MessageSquarePlusIcon, SquareDashedIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { Button } from "../primitives/Button.js";
+import { useUI } from "../provider/UIProvider.js";
+/** Seconds as a timecode: "00:01:12". */
+export function formatTimecode(seconds) {
+    const s = Math.max(0, Math.floor(seconds));
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${pad(Math.floor(s / 3600))}:${pad(Math.floor((s % 3600) / 60))}:${pad(s % 60)}`;
+}
+const percent = (fraction) => `${Math.min(100, Math.max(0, fraction * 100))}%`;
+/** Where the keyboard box starts, and how far one arrow press moves or sizes it. */
+const START = { x: 0.35, y: 0.35, width: 0.3, height: 0.3 };
+const STEP = 0.05;
+/**
+ * One arrow press on the keyboard box: move it, or with Shift size it, never
+ * past the picture's edges or smaller than one step.
+ */
+function nudge(region, key, resize) {
+    const dx = key === "ArrowRight" ? STEP : key === "ArrowLeft" ? -STEP : 0;
+    const dy = key === "ArrowDown" ? STEP : key === "ArrowUp" ? -STEP : 0;
+    if (!dx && !dy)
+        return null;
+    const clamp = (n, low, high) => Math.round(Math.min(high, Math.max(low, n)) * 100) / 100;
+    const { x, y, width, height } = region;
+    return resize
+        ? { x, y, width: clamp(width + dx, STEP, 1 - x), height: clamp(height + dy, STEP, 1 - y) }
+        : { x: clamp(x + dx, 0, 1 - width), y: clamp(y + dy, 0, 1 - height), width, height };
+}
+/**
+ * Media review for the media module: a video, audio or image with comments
+ * pinned to timecodes (markers on a rail under the player) or to regions
+ * (boxes over the image). Choosing a marker seeks the player and tells the
+ * host; "comment here" hands the host the current time, and on an image
+ * drawing a box hands it the region. "Mark a region" is the keyboard path on
+ * an image or a video frame: it drops a box that the arrow keys move and
+ * Shift with the arrows size, Enter hands the host the region (with the
+ * current time on a video) and Escape cancels. Plugs into ArtifactCard's
+ * preview and feeds ReviewPanel's anchors. The host supplies the media URL; the viewer
+ * fetches nothing itself beyond what the browser's media element does.
+ */
+export function MediaReview({ kind, src, title, poster, captions = [], duration: durationProp, comments, activeCommentId, onCommentSelect, onAnchor, className, }) {
+    const { messages } = useUI();
+    const t = messages.media;
+    const player = React.useRef(null);
+    const [loaded, setLoaded] = React.useState(null);
+    const duration = loaded ?? durationProp ?? 0;
+    const timed = comments.filter((c) => c.time != null);
+    const regions = comments.filter((c) => c.region);
+    const id = React.useId();
+    const [mark, setMark] = React.useState(null);
+    const canMark = Boolean(onAnchor) && kind !== "audio";
+    // The host took commenting away: the open box goes, and does not come back with it.
+    if (mark && !canMark)
+        setMark(null);
+    const marking = canMark ? mark : null;
+    const box = React.useRef(null);
+    const markButton = React.useRef(null);
+    const wasMarking = React.useRef(false);
+    const isMarking = marking != null;
+    // Focus follows the box: onto it when it appears, back to "Mark a region" when it goes.
+    React.useEffect(() => {
+        if (isMarking)
+            box.current?.focus();
+        else if (wasMarking.current)
+            markButton.current?.focus();
+        wasMarking.current = isMarking;
+    }, [isMarking]);
+    function endMark(region) {
+        setMark(null);
+        if (region) {
+            onAnchor?.(kind === "video" ? { time: player.current?.currentTime ?? 0, region } : { region });
+        }
+    }
+    function select(comment) {
+        if (comment.time != null && player.current) {
+            try {
+                player.current.currentTime = comment.time;
+            }
+            catch {
+                // A media element without metadata refuses a seek; the host still shows the comment.
+            }
+        }
+        onCommentSelect?.(comment);
+    }
+    const regionButtons = regions.map((c) => (_jsx("button", { type: "button", onClick: () => select(c), "aria-label": t.regionComment(c.author, c.time != null ? formatTimecode(c.time) : undefined), "aria-current": c.id === activeCommentId || undefined, style: {
+            left: percent(c.region.x),
+            top: percent(c.region.y),
+            width: percent(c.region.width),
+            height: percent(c.region.height),
+        }, className: cn("absolute rounded-sm border-2 border-warning outline-none focus-visible:ring-2 focus-visible:ring-ring", c.id === activeCommentId && "border-primary bg-primary/10", c.resolved && "border-dashed opacity-60") }, c.id)));
+    const whole = (fraction) => Math.round(fraction * 100);
+    /*
+     * The box is an application: a two-dimensional move and resize has no
+     * widget role, and the role puts a screen reader in focus mode so the
+     * arrow keys reach the box. jsx-a11y counts the role as non-interactive.
+     */
+    /* eslint-disable jsx-a11y/no-noninteractive-element-interactions, jsx-a11y/no-noninteractive-tabindex */
+    const regionMarker = marking && (_jsx("div", { ref: box, role: "application", tabIndex: 0, "aria-label": t.regionBox, "aria-describedby": `${id}-help ${id}-bounds`, onKeyDown: (event) => {
+            if (event.key === "Enter") {
+                event.preventDefault();
+                endMark(marking);
+            }
+            else if (event.key === "Escape") {
+                // Cancels the box, not a dialog the review sits in.
+                event.preventDefault();
+                event.stopPropagation();
+                endMark();
+            }
+            else {
+                const next = nudge(marking, event.key, event.shiftKey);
+                if (next) {
+                    event.preventDefault();
+                    setMark(next);
+                }
+            }
+        }, style: {
+            left: percent(marking.x),
+            top: percent(marking.y),
+            width: percent(marking.width),
+            height: percent(marking.height),
+        }, className: "pointer-events-auto absolute rounded-sm border-2 border-dashed border-primary bg-primary/10 outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:ring-offset-background" }));
+    /* eslint-enable jsx-a11y/no-noninteractive-element-interactions, jsx-a11y/no-noninteractive-tabindex */
+    return (_jsxs("figure", { "data-slot": "media-review", "data-kind": kind, className: cn("flex min-w-0 flex-col gap-2", className), children: [_jsx("div", { className: "relative min-w-0 overflow-hidden rounded-lg border bg-muted/40", children: kind === "image" ? (_jsxs(RegionDrawer, { enabled: Boolean(onAnchor) && !marking, onRegion: (region) => onAnchor?.({ region }), children: [_jsx("img", { src: src, alt: title, className: "block h-auto w-full" }), regionButtons, regionMarker] })) : kind === "video" ? (_jsxs("div", { className: "relative", children: [_jsx("video", { ref: player, src: src, poster: poster, controls: true, preload: "metadata", "aria-label": title, onLoadedMetadata: (event) => setLoaded(event.currentTarget.duration || null), className: "block h-auto w-full", children: captions.map((track) => (_jsx("track", { kind: "captions", ...track }, track.src))) }), _jsxs("div", { className: "pointer-events-none absolute inset-0 [&>button]:pointer-events-auto", children: [regionButtons, regionMarker] })] })) : (_jsx("audio", { ref: player, src: src, controls: true, preload: "metadata", "aria-label": title, onLoadedMetadata: (event) => setLoaded(event.currentTarget.duration || null), className: "block w-full p-2", children: captions.map((track) => (_jsx("track", { kind: "captions", ...track }, track.src))) })) }), kind !== "image" && (_jsxs("div", { className: "flex min-w-0 items-center gap-3", children: [_jsx("ol", { "aria-label": t.markers, className: "relative h-6 min-w-0 flex-1 rounded-full bg-muted", children: timed.map((c) => (_jsx("li", { className: "absolute top-1/2 -translate-x-1/2 -translate-y-1/2", style: { left: duration ? percent(c.time / duration) : "0%" }, children: _jsx("button", { type: "button", onClick: () => select(c), "aria-label": t.timeComment(formatTimecode(c.time), c.author), "aria-current": c.id === activeCommentId || undefined, className: cn("block size-3 rounded-full border-2 border-background bg-warning outline-none focus-visible:ring-2 focus-visible:ring-ring", c.id === activeCommentId && "size-4 bg-primary", c.resolved && "bg-muted-foreground") }) }, c.id))) }), onAnchor && (_jsxs(Button, { size: "sm", variant: "outline", onClick: () => onAnchor({ time: player.current?.currentTime ?? 0 }), children: [_jsx(MessageSquarePlusIcon, { "aria-hidden": true }), t.commentHere] }))] })), canMark &&
+                (marking ? (_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-x-3 gap-y-2", children: [_jsx("p", { id: `${id}-help`, className: "min-w-0 basis-full text-xs text-muted-foreground", children: t.regionHelp }), _jsx("span", { id: `${id}-bounds`, "aria-live": "polite", className: "min-w-0 flex-1 basis-56 font-mono text-xs tabular-nums", children: t.regionBounds(whole(marking.x), whole(marking.y), whole(marking.width), whole(marking.height)) }), _jsxs("div", { className: "ml-auto flex items-center gap-2", children: [_jsx(Button, { size: "sm", variant: "ghost", onClick: () => endMark(), children: t.cancel }), _jsxs(Button, { size: "sm", onClick: () => endMark(marking), children: [_jsx(MessageSquarePlusIcon, { "aria-hidden": true }), t.confirmRegion] })] })] })) : (_jsx("div", { className: "flex min-w-0", children: _jsxs(Button, { ref: markButton, size: "sm", variant: "outline", onClick: () => setMark(START), children: [_jsx(SquareDashedIcon, { "aria-hidden": true }), t.markRegion] }) }))), _jsxs("figcaption", { className: "flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1 text-xs text-muted-foreground", children: [_jsx("span", { className: "min-w-0 [overflow-wrap:anywhere]", children: title }), _jsx("span", { children: t.count(comments.length) }), kind === "image" && onAnchor && (_jsxs("span", { className: "inline-flex items-center gap-1", children: [_jsx(CrosshairIcon, { "aria-hidden": true, className: "size-3.5" }), t.drawHint] }))] })] }));
+}
+/** Drag on the image to draw a region: the pointer path ("Mark a region" is the keyboard one). */
+function RegionDrawer({ enabled, onRegion, children, }) {
+    const [start, setStart] = React.useState(null);
+    const [box, setBox] = React.useState(null);
+    const at = (event) => {
+        const rect = event.currentTarget.getBoundingClientRect();
+        return {
+            x: rect.width ? (event.clientX - rect.left) / rect.width : 0,
+            y: rect.height ? (event.clientY - rect.top) / rect.height : 0,
+        };
+    };
+    const span = (a, b) => ({
+        x: Math.min(a.x, b.x),
+        y: Math.min(a.y, b.y),
+        width: Math.abs(a.x - b.x),
+        height: Math.abs(a.y - b.y),
+    });
+    return (_jsxs("div", { className: cn("relative", enabled && "cursor-crosshair"), onPointerDown: (event) => {
+            if (!enabled || event.target !== event.currentTarget.querySelector("img"))
+                return;
+            event.currentTarget.setPointerCapture(event.pointerId);
+            setStart(at(event));
+        }, onPointerMove: (event) => start && setBox(span(start, at(event))), onPointerUp: (event) => {
+            if (!start)
+                return;
+            const region = span(start, at(event));
+            setStart(null);
+            setBox(null);
+            if (region.width > 0.01 && region.height > 0.01)
+                onRegion(region);
+        }, children: [children, box && (_jsx("span", { "aria-hidden": true, style: {
+                    left: percent(box.x),
+                    top: percent(box.y),
+                    width: percent(box.width),
+                    height: percent(box.height),
+                }, className: "pointer-events-none absolute rounded-sm border-2 border-dashed border-primary bg-primary/10" }))] }));
+}

package/dist/workflow/ReviewPanel.d.ts

@@ -0,0 +1,41 @@
+import * as React from "react";
+import { type Gate, type ReviewComment, type ReviewDecision, type ReviewVerdict } from "./run.js";
+export interface ReviewPanelProps {
+    /** What is under review, for the heading ("Review: Promo cut v3"). */
+    subject?: string;
+    verdict: ReviewVerdict;
+    /** The gate this review decides, when it decides one. */
+    gate?: Gate;
+    /** The decision that closed the review, when it is closed. */
+    decision?: ReviewDecision;
+    comments: readonly ReviewComment[];
+    /** Posts a comment. The composer shows only with it. A rejection keeps the draft and shows the error. */
+    onComment?: (body: string, anchor?: string) => Promise<unknown> | unknown;
+    /**
+     * Where the next comment points, picked in a module viewer (a timecode, a
+     * region, a clause, a field). Shown on the composer, cleared with `onClearAnchor`.
+     */
+    commentAnchor?: string;
+    onClearAnchor?: () => void;
+    /** Makes each comment's anchor a button, so the viewer can go to it. */
+    onCommentSelect?: (comment: ReviewComment) => void;
+    activeCommentId?: string;
+    /** Approves, after the confirm step. Awaited; see ConfirmDialog. */
+    onApprove?: (reason: string) => Promise<unknown> | unknown;
+    /** Rejects, after the confirm step, with a required reason. */
+    onReject?: (reason: string) => Promise<unknown> | unknown;
+    /** Ask for a reason on approval too. */
+    approveReasonRequired?: boolean;
+    /** Why the person may not decide: the decision buttons show disabled with it. */
+    decisionDenied?: string;
+    headingLevel?: "h2" | "h3";
+    className?: string;
+}
+/**
+ * The review of one artifact or stage: its verdict and gate, the comments
+ * (each with its anchor in the artifact), a composer, and approve and reject
+ * through the confirm flow, a rejection always with a reason. Module viewers
+ * sit beside it and feed it anchors; it never decides anything itself, the
+ * host's callbacks do.
+ */
+export declare function ReviewPanel({ subject, verdict, gate, decision, comments, onComment, commentAnchor, onClearAnchor, onCommentSelect, activeCommentId, onApprove, onReject, approveReasonRequired, decisionDenied, headingLevel, className, }: ReviewPanelProps): React.JSX.Element;

package/dist/workflow/ReviewPanel.js

@@ -0,0 +1,59 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { CheckIcon, XIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { ConfirmDialog } from "../overlays/ConfirmDialog.js";
+import { Button } from "../primitives/Button.js";
+import { Textarea } from "../primitives/Textarea.js";
+import { useUI } from "../provider/UIProvider.js";
+import { StatusBadge } from "../status/StatusBadge.js";
+import { GateBadge } from "./GateBadge.js";
+import { VERDICT_TONE, } from "./run.js";
+/**
+ * The review of one artifact or stage: its verdict and gate, the comments
+ * (each with its anchor in the artifact), a composer, and approve and reject
+ * through the confirm flow, a rejection always with a reason. Module viewers
+ * sit beside it and feed it anchors; it never decides anything itself, the
+ * host's callbacks do.
+ */
+export function ReviewPanel({ subject, verdict, gate, decision, comments, onComment, commentAnchor, onClearAnchor, onCommentSelect, activeCommentId, onApprove, onReject, approveReasonRequired = false, decisionDenied, headingLevel = "h2", className, }) {
+    const { messages } = useUI();
+    const t = messages.review;
+    const Heading = headingLevel;
+    const SubHeading = headingLevel === "h2" ? "h3" : "h4";
+    const id = React.useId();
+    const [confirming, setConfirming] = React.useState(null);
+    const open = !decision && (!gate || gate.status === "waiting");
+    const canDecide = open && Boolean(onApprove || onReject);
+    return (_jsxs("section", { "aria-labelledby": `${id}-title`, "data-slot": "review-panel", className: cn("flex min-w-0 flex-col gap-4 rounded-lg border bg-card p-(--panel-pad) text-card-foreground", className), children: [_jsxs("header", { className: "flex min-w-0 flex-col gap-2", children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-2", children: [_jsx(Heading, { id: `${id}-title`, className: "text-sm font-medium [overflow-wrap:anywhere]", children: subject ? t.titleFor(subject) : t.title }), _jsx(StatusBadge, { tone: VERDICT_TONE[verdict], children: t.verdict(verdict) }), gate && _jsx(GateBadge, { gate: gate })] }), decision && (_jsxs("p", { className: "text-sm [overflow-wrap:anywhere] text-muted-foreground", children: [t.decided(decision.verdict, decision.by, decision.at), decision.reason && (_jsxs(_Fragment, { children: [" ", _jsx("span", { className: "text-foreground", children: decision.reason })] }))] })), canDecide && (_jsxs("div", { className: "flex min-w-0 flex-col gap-1.5", children: [_jsxs("div", { className: "flex flex-wrap gap-2", children: [onApprove && (_jsxs(Button, { size: "sm", disabled: decisionDenied != null, "aria-describedby": decisionDenied != null ? `${id}-denied` : undefined, onClick: () => setConfirming("approve"), children: [_jsx(CheckIcon, { "aria-hidden": true }), t.approve] })), onReject && (_jsxs(Button, { size: "sm", variant: "destructive", disabled: decisionDenied != null, "aria-describedby": decisionDenied != null ? `${id}-denied` : undefined, onClick: () => setConfirming("reject"), children: [_jsx(XIcon, { "aria-hidden": true }), t.reject] }))] }), decisionDenied != null && (_jsx("p", { id: `${id}-denied`, className: "text-xs text-muted-foreground", children: decisionDenied }))] }))] }), _jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [_jsx(SubHeading, { className: "font-mono text-2xs font-medium tracking-wider text-muted-foreground uppercase", children: t.comments(comments.length) }), comments.length === 0 ? (_jsx("p", { className: "text-sm text-muted-foreground", children: t.noComments })) : (_jsx("ol", { className: "flex min-w-0 flex-col gap-2", children: comments.map((comment) => (_jsxs("li", { "aria-current": comment.id === activeCommentId || undefined, className: cn("flex min-w-0 flex-col gap-1 rounded-lg border p-2.5", comment.id === activeCommentId && "border-primary", comment.resolved && "opacity-70"), children: [_jsxs("p", { className: "flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 text-xs", children: [_jsx("span", { className: "font-medium", children: comment.author }), comment.at && _jsx("span", { className: "text-muted-foreground", children: comment.at }), comment.anchor &&
+                                            (onCommentSelect ? (_jsx("button", { type: "button", onClick: () => onCommentSelect(comment), "aria-label": t.goToAnchor(comment.anchor), className: "rounded-sm font-mono text-primary underline-offset-2 outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring", children: comment.anchor })) : (_jsx("span", { className: "font-mono text-muted-foreground", children: comment.anchor }))), comment.resolved && (_jsx(StatusBadge, { tone: "muted", className: "ml-auto", children: t.resolved }))] }), _jsx("p", { className: "text-sm [overflow-wrap:anywhere] whitespace-pre-wrap", children: comment.body })] }, comment.id))) })), onComment && (_jsx(Composer, { onComment: onComment, anchor: commentAnchor, onClearAnchor: onClearAnchor }))] }), _jsx(ConfirmDialog, { open: confirming === "approve", onOpenChange: (next) => !next && setConfirming(null), title: t.approveTitle, description: t.approveDescription, confirmLabel: t.approve, reason: approveReasonRequired ? { label: t.reasonLabel } : undefined, onConfirm: (reason) => onApprove?.(reason) }), _jsx(ConfirmDialog, { open: confirming === "reject", onOpenChange: (next) => !next && setConfirming(null), title: t.rejectTitle, description: t.rejectDescription, confirmLabel: t.reject, destructive: true, reason: { label: t.reasonLabel }, onConfirm: (reason) => onReject?.(reason) })] }));
+}
+function Composer({ onComment, anchor, onClearAnchor, }) {
+    const { messages } = useUI();
+    const t = messages.review;
+    const id = React.useId();
+    const [draft, setDraft] = React.useState("");
+    const [pending, setPending] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    async function submit(event) {
+        event.preventDefault();
+        const body = draft.trim();
+        if (!body || pending)
+            return;
+        setPending(true);
+        setError(null);
+        try {
+            const result = await onComment(body, anchor);
+            if (result !== false)
+                setDraft("");
+        }
+        catch (err) {
+            setError(err instanceof Error && err.message ? err.message : messages.confirm.failed);
+        }
+        finally {
+            setPending(false);
+        }
+    }
+    return (_jsxs("form", { onSubmit: submit, className: "flex min-w-0 flex-col gap-2", children: [_jsx("label", { htmlFor: id, className: "sr-only", children: t.addComment }), anchor && (_jsxs("p", { className: "flex min-w-0 items-center gap-2 text-xs text-muted-foreground", children: [_jsx("span", { className: "[overflow-wrap:anywhere]", children: t.commentOn(anchor) }), onClearAnchor && (_jsx(Button, { type: "button", size: "xs", variant: "ghost", onClick: onClearAnchor, children: t.clearAnchor }))] })), _jsx(Textarea, { id: id, value: draft, rows: 2, disabled: pending, placeholder: t.addComment, "aria-invalid": error != null || undefined, "aria-describedby": error ? `${id}-error` : undefined, onChange: (event) => setDraft(event.target.value) }), error && (_jsx("p", { id: `${id}-error`, role: "alert", className: "text-xs text-danger-fg", children: error })), _jsx(Button, { type: "submit", size: "sm", variant: "outline", disabled: pending || !draft.trim(), className: "self-end", children: pending ? messages.confirm.working : t.post })] }));
+}

package/dist/workflow/RunTimeline.d.ts

@@ -0,0 +1,25 @@
+import * as React from "react";
+import { type RunStage } from "./run.js";
+export interface RunTimelineProps {
+    stages: readonly RunStage[];
+    /** Names the timeline. Defaults to "Run stages". */
+    label?: string;
+    loading?: boolean;
+    error?: {
+        message: string;
+    } | null;
+    onRetry?: () => void;
+    /** Makes each stage's name a button, for a host that shows the stage beside the timeline. */
+    onStageSelect?: (stage: RunStage) => void;
+    selectedStageId?: string;
+    /** Stages whose inputs and outputs start open. */
+    defaultExpanded?: readonly string[];
+    className?: string;
+}
+/**
+ * A run's stages in order, for any module: each with its status, timing,
+ * attempt and retries, a one-line detail, its gate when it is one, and its
+ * inputs and outputs summarized behind a disclosure. Process and automation
+ * runs read here as they are; other modules put their review surfaces beside it.
+ */
+export declare function RunTimeline({ stages, label, loading, error, onRetry, onStageSelect, selectedStageId, defaultExpanded, className, }: RunTimelineProps): React.JSX.Element;

package/dist/workflow/RunTimeline.js

@@ -0,0 +1,56 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronRightIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { Skeleton } from "../primitives/Skeleton.js";
+import { useUI } from "../provider/UIProvider.js";
+import { EmptyState } from "../states/EmptyState.js";
+import { ErrorState } from "../states/ErrorState.js";
+import { StatusDot } from "../status/StatusDot.js";
+import { GateBadge } from "./GateBadge.js";
+import { RUN_STAGE_TONE } from "./run.js";
+/**
+ * A run's stages in order, for any module: each with its status, timing,
+ * attempt and retries, a one-line detail, its gate when it is one, and its
+ * inputs and outputs summarized behind a disclosure. Process and automation
+ * runs read here as they are; other modules put their review surfaces beside it.
+ */
+export function RunTimeline({ stages, label, loading = false, error, onRetry, onStageSelect, selectedStageId, defaultExpanded = [], className, }) {
+    const { messages } = useUI();
+    const t = messages.run;
+    const name = label ?? t.timeline;
+    const id = React.useId();
+    const [expanded, setExpanded] = React.useState(() => new Set(defaultExpanded));
+    if (error) {
+        return (_jsx(ErrorState, { title: t.loadFailed(name), error: error, onRetry: onRetry, className: className }));
+    }
+    if (loading) {
+        return (_jsxs("div", { "aria-busy": true, className: cn("flex flex-col gap-4", className), children: [_jsx("p", { role: "status", className: "sr-only", children: messages.states.loading }), Array.from({ length: 4 }, (_, i) => (_jsxs("div", { className: "flex items-center gap-3", children: [_jsx(Skeleton, { className: "size-3 rounded-full" }), _jsx(Skeleton, { className: "h-4 flex-1" }), _jsx(Skeleton, { className: "h-4 w-16" })] }, i)))] }));
+    }
+    if (stages.length === 0) {
+        return (_jsx(EmptyState, { title: t.noStages, description: t.noStagesDescription, className: className }));
+    }
+    return (_jsx("ol", { "aria-label": name, "data-slot": "run-timeline", className: cn("flex min-w-0 flex-col", className), children: stages.map((stage, index) => {
+            const open = expanded.has(stage.id);
+            const hasValues = Boolean(stage.inputs?.length || stage.outputs?.length);
+            const valuesId = `${id}-${index}-values`;
+            const last = index === stages.length - 1;
+            const selected = stage.id === selectedStageId;
+            const attempt = stage.attempt && (stage.attempt > 1 || stage.maxAttempts)
+                ? t.attempt(stage.attempt, stage.maxAttempts)
+                : null;
+            return (_jsxs("li", { "data-status": stage.status, "aria-current": selected ? "step" : undefined, className: "relative flex min-w-0 gap-3 pb-4 last:pb-0", children: [!last && (_jsx("span", { "aria-hidden": true, className: "absolute top-4 bottom-0 left-1 w-px -translate-x-1/2 bg-border" })), _jsx(StatusDot, { tone: RUN_STAGE_TONE[stage.status], pulse: stage.status === "running", className: "mt-1.5 self-start" }), _jsxs("div", { className: cn("-my-1 flex min-w-0 flex-1 flex-col gap-1 rounded-lg px-2 py-1", selected && "bg-muted"), children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-baseline gap-x-3 gap-y-1", children: [_jsx("span", { className: "min-w-0 text-sm font-medium [overflow-wrap:anywhere]", children: onStageSelect ? (_jsx("button", { type: "button", onClick: () => onStageSelect(stage), className: "rounded-sm text-left outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring", children: stage.label })) : (stage.label) }), _jsx("span", { className: "font-mono text-xs text-muted-foreground", children: t.stageStatus(stage.status) }), stage.gate && _jsx(GateBadge, { gate: stage.gate }), _jsxs("span", { className: "ml-auto flex flex-wrap gap-x-3 font-mono text-xs text-muted-foreground tabular-nums", children: [attempt && _jsx("span", { children: attempt }), stage.startedAt && _jsx("span", { children: t.startedAt(stage.startedAt) }), stage.duration && _jsx("span", { children: t.duration(stage.duration) })] })] }), stage.detail && (_jsx("p", { className: "text-sm [overflow-wrap:anywhere] text-muted-foreground", children: stage.detail })), hasValues && (_jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [_jsxs("button", { type: "button", "aria-expanded": open, "aria-controls": valuesId, onClick: () => setExpanded((current) => {
+                                            const next = new Set(current);
+                                            if (open)
+                                                next.delete(stage.id);
+                                            else
+                                                next.add(stage.id);
+                                            return next;
+                                        }), className: "inline-flex w-fit items-center gap-1 rounded-sm text-xs text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring", children: [_jsx(ChevronRightIcon, { "aria-hidden": true, className: cn("size-3.5 transition-transform", open && "rotate-90") }), t.inputsOutputs(stage.inputs?.length ?? 0, stage.outputs?.length ?? 0)] }), open && (_jsxs("div", { id: valuesId, className: "grid min-w-0 gap-3 sm:grid-cols-2", children: [_jsx(Values, { title: t.inputs, values: stage.inputs }), _jsx(Values, { title: t.outputs, values: stage.outputs })] }))] }))] })] }, stage.id));
+        }) }));
+}
+function Values({ title, values }) {
+    const { messages } = useUI();
+    return (_jsxs("div", { className: "flex min-w-0 flex-col gap-1 rounded-lg border bg-card p-2", children: [_jsx("p", { className: "font-mono text-2xs font-medium tracking-wider text-muted-foreground uppercase", children: title }), values?.length ? (_jsx("dl", { className: "grid min-w-0 grid-cols-[auto_minmax(0,1fr)] gap-x-3 gap-y-1 text-xs", children: values.map((v, i) => (_jsxs(React.Fragment, { children: [_jsx("dt", { className: "text-muted-foreground", children: v.label }), _jsx("dd", { className: "font-mono [overflow-wrap:anywhere]", children: v.value })] }, i))) })) : (_jsx("p", { className: "text-xs text-muted-foreground", children: messages.run.none }))] }));
+}

package/dist/workflow/WorkflowCard.d.ts

@@ -0,0 +1,39 @@
+import * as React from "react";
+import type { WorkflowPermissions, WorkflowSummary } from "./model.js";
+/** What a card can do, as the host permits it. An action renders only when its handler is given. */
+export interface WorkflowCardActions {
+    /** Opens the workflow: the title becomes a link through the app's link component. */
+    href?: string;
+    /** Opens the workflow without a route: the title becomes a button. Ignored with `href`. */
+    onOpen?: () => void;
+    onEdit?: () => void;
+    /** Enabled only when the workflow is available here and `permissions.start` is not false. */
+    onStart?: () => void;
+    onExport?: () => void;
+    /** An action set to false is shown disabled, with the reason. */
+    permissions?: WorkflowPermissions;
+}
+export interface WorkflowCardProps extends WorkflowCardActions {
+    workflow: WorkflowSummary;
+    /** The host's picture of the workflow (a flow diagram, a thumbnail). Decorative unless it names itself. */
+    preview?: React.ReactNode;
+    /** A card in a grid, or a row in a list. */
+    layout?: "card" | "row";
+    /** For the document outline. Defaults to h3, under a page's h1 and a section's h2. */
+    headingLevel?: "h2" | "h3" | "h4";
+    className?: string;
+}
+/**
+ * One saved workflow definition, as a gallery shows it: module and version,
+ * name and description, scope, revision and draft or published state, an
+ * optional host preview, and the actions the host permits. A workflow this
+ * factory cannot run, or that the person may not start, never shows an
+ * enabled start: the card says why instead. The card only reports intent;
+ * the host keeps authorization and execution.
+ */
+export declare function WorkflowCard({ workflow, preview, layout, headingLevel, href, onOpen, onEdit, onStart, onExport, permissions, className, }: WorkflowCardProps): React.JSX.Element;
+/** A card's placeholder while the gallery loads, with the card's geometry. */
+export declare function WorkflowCardSkeleton({ layout, className, }: {
+    layout?: "card" | "row";
+    className?: string;
+}): React.JSX.Element;

package/dist/workflow/WorkflowCard.js

@@ -0,0 +1,56 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { Button } from "../primitives/Button.js";
+import { Skeleton } from "../primitives/Skeleton.js";
+import { useUI } from "../provider/UIProvider.js";
+import { StatusBadge } from "../status/StatusBadge.js";
+const STATUS_TONE = { draft: "info", published: "ok" };
+const AVAILABILITY_TONE = { unsupported: "muted", "missing-capabilities": "warn" };
+/**
+ * One saved workflow definition, as a gallery shows it: module and version,
+ * name and description, scope, revision and draft or published state, an
+ * optional host preview, and the actions the host permits. A workflow this
+ * factory cannot run, or that the person may not start, never shows an
+ * enabled start: the card says why instead. The card only reports intent;
+ * the host keeps authorization and execution.
+ */
+export function WorkflowCard({ workflow, preview, layout = "card", headingLevel = "h3", href, onOpen, onEdit, onStart, onExport, permissions = {}, className, }) {
+    const { Link, messages } = useUI();
+    const t = messages.workflow;
+    const id = React.useId();
+    const titleId = `${id}-title`;
+    const noteId = `${id}-note`;
+    const Heading = headingLevel;
+    const { availability } = workflow;
+    const row = layout === "row";
+    const handlers = [
+        ["edit", onEdit],
+        ["start", onStart],
+        ["export", onExport],
+    ];
+    const offered = handlers.filter(([, handler]) => handler);
+    const denied = offered.filter(([action]) => permissions[action] === false).map(([a]) => a);
+    const startBlocked = Boolean(onStart) && availability.status !== "available";
+    const notes = [];
+    if (startBlocked) {
+        notes.push(availability.reason ??
+            (availability.status === "unsupported"
+                ? t.unsupported
+                : t.missingCapabilities(availability.missing ?? [])));
+    }
+    if (denied.length)
+        notes.push(t.denied(denied.map((a) => t.action(a))));
+    const titleClass = "outline-none after:absolute after:inset-0 after:rounded-lg hover:underline focus-visible:after:ring-2 focus-visible:after:ring-ring focus-visible:after:ring-inset";
+    const title = href ? (_jsx(Link, { href: href, className: titleClass, children: workflow.name })) : onOpen ? (_jsx("button", { type: "button", onClick: onOpen, className: cn(titleClass, "text-left"), children: workflow.name })) : (workflow.name);
+    return (_jsxs("article", { "data-slot": "workflow-card", "data-layout": layout, "data-status": workflow.status, "data-availability": availability.status, "aria-labelledby": titleId, className: cn("relative flex min-w-0 overflow-hidden rounded-lg border bg-card text-card-foreground", row ? "flex-col sm:flex-row sm:items-stretch" : "flex-col", className), children: [preview != null && (_jsx("div", { role: "img", "aria-label": t.preview(workflow.name), className: cn("flex shrink-0 items-center justify-center overflow-hidden bg-muted/40 text-muted-foreground", row ? "border-b sm:w-48 sm:border-r sm:border-b-0" : "h-28 border-b"), children: preview })), _jsxs("div", { className: cn("flex min-w-0 flex-1 gap-3 p-(--panel-pad)", row ? "flex-col md:flex-row md:items-start" : "flex-col"), children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-1.5", children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1", children: [_jsx("span", { className: "min-w-0 truncate font-mono text-xs text-muted-foreground", children: t.module(workflow.module.label, workflow.module.version) }), _jsx(StatusBadge, { tone: STATUS_TONE[workflow.status], children: t.status(workflow.status) }), availability.status !== "available" && (_jsx(StatusBadge, { tone: AVAILABILITY_TONE[availability.status], children: t.availability(availability.status) }))] }), _jsx(Heading, { id: titleId, className: "line-clamp-2 text-sm font-medium [overflow-wrap:anywhere]", children: title }), workflow.description && (_jsx("p", { className: "line-clamp-3 text-sm [overflow-wrap:anywhere] text-muted-foreground", children: workflow.description })), _jsxs("p", { className: "flex min-w-0 flex-wrap gap-x-3 font-mono text-xs text-muted-foreground", children: [_jsx("span", { children: t.scope(workflow.scope) }), workflow.revision && (_jsx("span", { className: "min-w-0 truncate", children: t.revision(workflow.revision) }))] }), notes.length > 0 && (_jsx("p", { id: noteId, className: "text-xs [overflow-wrap:anywhere] text-muted-foreground", children: notes.join(" ") }))] }), offered.length > 0 && (_jsx("div", { className: cn("relative z-10 flex shrink-0 flex-wrap items-center gap-1.5", !row && "mt-auto border-t pt-3"), children: offered.map(([action, handler]) => {
+                            const label = t.action(action);
+                            const disabled = permissions[action] === false || (action === "start" && startBlocked);
+                            return (_jsx(Button, { size: "sm", variant: action === "start" ? "default" : "outline", disabled: disabled, "aria-label": t.actionName(label, workflow.name), "aria-describedby": disabled && notes.length ? noteId : undefined, onClick: handler, children: label }, action));
+                        }) }))] })] }));
+}
+/** A card's placeholder while the gallery loads, with the card's geometry. */
+export function WorkflowCardSkeleton({ layout = "card", className, }) {
+    return (_jsxs("div", { "data-slot": "workflow-card-skeleton", "aria-hidden": true, className: cn("flex min-w-0 gap-3 overflow-hidden rounded-lg border bg-card p-(--panel-pad)", layout === "row" ? "flex-row items-center" : "flex-col", className), children: [layout === "card" && _jsx(Skeleton, { className: "h-20 w-full" }), _jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx(Skeleton, { className: "h-3 w-24" }), _jsx(Skeleton, { className: "h-4 w-2/3" }), _jsx(Skeleton, { className: "h-3 w-full" })] }), _jsx(Skeleton, { className: "h-7 w-20" })] }));
+}

package/dist/workflow/WorkflowGallery.d.ts

@@ -0,0 +1,43 @@
+import * as React from "react";
+import { type WorkflowGalleryFilters } from "./gallery.js";
+import type { WorkflowModule, WorkflowSummary } from "./model.js";
+import { type WorkflowCardActions } from "./WorkflowCard.js";
+export type WorkflowGalleryView = "grid" | "list";
+export interface WorkflowGalleryProps {
+    /** The page title. Defaults to "Workflows". */
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    /** The workflows to show, already filtered by the host (see `filterWorkflows`). */
+    workflows: readonly WorkflowSummary[];
+    /** The modules the module filter offers. Leave empty to hide that filter. */
+    modules: readonly WorkflowModule[];
+    filters: WorkflowGalleryFilters;
+    onFiltersChange: (filters: WorkflowGalleryFilters) => void;
+    /** Grid of cards or list of rows. Uncontrolled without it. */
+    view?: WorkflowGalleryView;
+    defaultView?: WorkflowGalleryView;
+    onViewChange?: (view: WorkflowGalleryView) => void;
+    loading?: boolean;
+    error?: {
+        message: string;
+    } | null;
+    onRetry?: () => void;
+    /** Shown only when the person may create. */
+    onCreate?: () => void;
+    /** Shown only when the person may import. */
+    onImport?: () => void;
+    /** The actions the host permits on each workflow. */
+    actionsFor?: (workflow: WorkflowSummary) => WorkflowCardActions;
+    /** The host's preview of each workflow. */
+    renderPreview?: (workflow: WorkflowSummary) => React.ReactNode;
+    className?: string;
+}
+/**
+ * The workflow gallery: a full page of saved definitions over WorkflowCard,
+ * with search, a module filter, scope and status filters, grid and list
+ * views, and create and import when the host permits them. Host-driven: the
+ * filters are controlled and the host returns the matching workflows (a host
+ * holding the whole set uses `filterWorkflows`). Empty and no-matches are
+ * different states.
+ */
+export declare function WorkflowGallery({ title, description, workflows, modules, filters, onFiltersChange, view: viewProp, defaultView, onViewChange, loading, error, onRetry, onCreate, onImport, actionsFor, renderPreview, className, }: WorkflowGalleryProps): React.JSX.Element;