@calliopelabs/ui 0.6.1 → 0.11.0

package/dist/workflow/problems.js

@@ -0,0 +1,409 @@
+/**
+ * What is wrong with a workflow definition, at three levels, and whether this
+ * destination can run each node. `blocking` problems stop a publish,
+ * `warning`s do not, and `not-run` marks a node this destination does not run
+ * (yet): its module, a capability or its kind is missing here. Problems carry
+ * a code and values, never English; the editor's copy names them. Pure.
+ */
+import { downstream, edgeId, exitLabel, exitsOf, findFact, findGateKind, findPreset, inputsOf, operatorsFor, outputsOf, portOf, startOf, typeAccepts, upstream, } from "./definition.js";
+export const WORKFLOW_PROBLEM_CODES = [
+    // the definition
+    "no-main",
+    "flow-empty",
+    // nodes and edges
+    "duplicate-id",
+    "unreachable",
+    "dangling-edge",
+    "missing-exit",
+    "cycle",
+    "loop-no-until",
+    "loop-no-max",
+    "loop-not-back",
+    "exit-unwired",
+    // data
+    "input-unbound",
+    "data-port-missing",
+    "data-type",
+    "data-order",
+    // steps
+    "unknown-preset",
+    "unknown-model",
+    "unknown-harness",
+    "unknown-effort",
+    // sub-flows
+    "subflow-none",
+    "subflow-missing",
+    "subflow-recursive",
+    // gates
+    "unknown-gate-kind",
+    "gate-no-approver",
+    "gate-quorum",
+    "gate-no-threshold",
+    "gate-no-rule",
+    "gate-no-timeout-action",
+    // conditions
+    "no-cases",
+    "unknown-fact",
+    "unknown-operator",
+    "operator-mismatch",
+    "value-missing",
+    "value-type",
+    "fact-node-missing",
+    // logic
+    "goto-no-target",
+    "goto-missing-target",
+    "goto-no-max",
+    "fanout-few",
+    "join-few",
+    "join-no-n",
+    "variants-few",
+    "variants-no-select",
+    "variants-no-evaluator",
+    // judges
+    "rubric-short",
+    "no-threshold",
+    "no-question",
+    "options-few",
+    "option-duplicate",
+    // executability
+    "not-runnable",
+];
+const AVAILABLE = { status: "available" };
+function merge(parts) {
+    const unsupported = parts.find((p) => p.status === "unsupported");
+    if (unsupported)
+        return unsupported;
+    const missing = parts.filter((p) => p.status === "missing-capabilities");
+    if (!missing.length)
+        return AVAILABLE;
+    const names = [...new Set(missing.flatMap((p) => p.missing ?? []))];
+    const reason = missing.length === 1 ? missing[0]?.reason : undefined;
+    return { status: "missing-capabilities", missing: names, ...(reason ? { reason } : {}) };
+}
+function capabilities(registry, needs) {
+    if (!registry.capabilities || !needs?.length)
+        return AVAILABLE;
+    const missing = needs.filter((c) => !registry.capabilities?.includes(c));
+    return missing.length ? { status: "missing-capabilities", missing } : AVAILABLE;
+}
+/**
+ * Whether this destination can run a node, reusing the gallery's
+ * availability: `unsupported` when its kind, module, preset or gate kind is
+ * not here, `missing-capabilities` with the names when the module is but a
+ * capability it needs is not.
+ */
+export function nodeAvailability(node, registry) {
+    const parts = [registry.nodeKinds?.[node.kind] ?? AVAILABLE];
+    if ((node.kind === "step" || node.kind === "variants") && node.preset) {
+        const module = registry.modules.find((m) => m.id === node.preset?.module);
+        const found = findPreset(registry, node.preset);
+        if (!module || !found)
+            parts.push({ status: "unsupported" });
+        else {
+            parts.push(module.availability ?? AVAILABLE);
+            parts.push(capabilities(registry, found.preset.capabilities));
+        }
+    }
+    if (node.kind === "gate") {
+        const kind = findGateKind(registry, node.gate);
+        if (!kind)
+            parts.push({ status: "unsupported" });
+        else
+            parts.push(kind.availability ?? AVAILABLE, capabilities(registry, kind.capabilities));
+    }
+    return merge(parts);
+}
+/** Whether this destination can run the whole definition: every node of every flow. */
+export function definitionAvailability(definition, registry) {
+    return merge(Object.values(definition.flows).flatMap((f) => f.nodes.map((n) => nodeAvailability(n, registry))));
+}
+function checkCondition(flow, c, registry, push) {
+    const fact = findFact(registry, c.fact);
+    if (!fact)
+        return push("unknown-fact", { fact: c.fact });
+    const op = registry.operators.find((o) => o.id === c.op);
+    if (!op)
+        return push("unknown-operator", { fact: fact.label, op: c.op });
+    if (!operatorsFor(registry, fact).includes(op))
+        push("operator-mismatch", { fact: fact.label, op: op.label });
+    if (fact.node) {
+        const n = flow.nodes.find((x) => x.id === c.node);
+        if (!n || (fact.node !== true && !fact.node.includes(n.kind)))
+            push("fact-node-missing", { fact: fact.label });
+    }
+    if (op.unary)
+        return;
+    if (c.value === undefined || c.value === "")
+        return push("value-missing", { fact: fact.label });
+    const ok = fact.type === "number"
+        ? typeof c.value === "number"
+        : fact.type === "boolean"
+            ? typeof c.value === "boolean"
+            : fact.type === "enum"
+                ? !fact.values || fact.values.some((v) => v.id === c.value)
+                : typeof c.value === "string";
+    if (!ok)
+        push("value-type", { fact: fact.label });
+}
+function checkFlow(name, flow, definition, registry, push) {
+    const ids = new Set();
+    const label = (id) => flow.nodes.find((n) => n.id === id)?.label ?? id;
+    for (const n of flow.nodes) {
+        if (ids.has(n.id))
+            push("blocking", "duplicate-id", { node: n.id }, { id: n.id });
+        ids.add(n.id);
+    }
+    if (!flow.nodes.length)
+        push("warning", "flow-empty", {}, { flow: flow.label ?? name });
+    for (const e of flow.edges) {
+        const at = { edge: edgeId(e) };
+        const a = flow.nodes.find((n) => n.id === e.from);
+        const b = flow.nodes.find((n) => n.id === e.to);
+        if (!a || !b) {
+            push("blocking", "dangling-edge", at, { from: label(e.from), to: label(e.to) });
+            continue;
+        }
+        const names = { from: a.label, to: b.label };
+        if (e.kind === "next" && !exitsOf(a).includes(portOf(e)))
+            push("blocking", "missing-exit", at, { ...names, exit: portOf(e) });
+        if (e.kind === "loop") {
+            if (!e.until)
+                push("blocking", "loop-no-until", at, names);
+            else
+                checkCondition(flow, e.until, registry, (code, v) => push("blocking", code, at, { ...names, ...v }));
+            if (!e.max)
+                push("blocking", "loop-no-max", at, names);
+            if (!downstream(flow, b.id).has(a.id))
+                push("blocking", "loop-not-back", at, names);
+        }
+        if (e.kind === "data") {
+            const out = outputsOf(a, registry, definition).find((p) => p.id === e.port);
+            const input = inputsOf(b, registry, definition).find((p) => p.id === e.input);
+            if (!out || !input)
+                push("blocking", "data-port-missing", at, {
+                    ...names,
+                    output: e.port ?? "",
+                    input: e.input ?? "",
+                });
+            else {
+                const v = {
+                    ...names,
+                    output: out.label,
+                    input: input.label,
+                    given: out.type,
+                    wanted: input.type,
+                };
+                if (!typeAccepts(registry, out.type, input.type))
+                    push("blocking", "data-type", at, v);
+                if (!downstream(flow, a.id).has(b.id))
+                    push("blocking", "data-order", at, v);
+            }
+        }
+    }
+    // Next edges never cycle: going back is a loop edge, with a count and an exit.
+    const colour = new Map();
+    const visit = (id) => {
+        if (colour.get(id) === 2)
+            return false;
+        if (colour.get(id) === 1)
+            return true;
+        colour.set(id, 1);
+        const cyc = flow.edges.some((e) => e.kind === "next" && e.from === id && visit(e.to));
+        colour.set(id, 2);
+        return cyc;
+    };
+    if (flow.nodes.some((n) => visit(n.id)))
+        push("blocking", "cycle", {}, { flow: flow.label ?? name });
+    const start = startOf(flow);
+    if (start) {
+        const seen = new Set([start]);
+        const stack = [start];
+        while (stack.length) {
+            const id = stack.pop();
+            const n = flow.nodes.find((x) => x.id === id);
+            const nexts = flow.edges.filter((e) => e.kind === "next" && e.from === id).map((e) => e.to);
+            if (n?.kind === "goto" && n.target)
+                nexts.push(n.target);
+            for (const t of nexts)
+                if (!seen.has(t)) {
+                    seen.add(t);
+                    stack.push(t);
+                }
+        }
+        for (const n of flow.nodes)
+            if (!seen.has(n.id))
+                push("warning", "unreachable", { node: n.id }, { node: n.label });
+    }
+    const nextOut = (id) => flow.edges.filter((e) => e.kind === "next" && e.from === id);
+    const nextIn = (id) => flow.edges.filter((e) => e.kind === "next" && e.to === id);
+    const picks = (list, value) => !list || !value || list.some((o) => o.id === value);
+    for (const n of flow.nodes) {
+        const at = { node: n.id };
+        const v = { node: n.label };
+        const block = (code, more = {}) => push("blocking", code, at, { ...v, ...more });
+        const warn = (code, more = {}) => push("warning", code, at, { ...v, ...more });
+        // Inputs a node needs: bound by a data edge, or by type to something before it.
+        const required = inputsOf(n, registry, definition).filter((p) => !p.optional);
+        if (required.length) {
+            const before = upstream(flow, n.id);
+            const available = [
+                ...(flow.inputs ?? []),
+                ...flow.nodes
+                    .filter((x) => before.has(x.id))
+                    .flatMap((x) => outputsOf(x, registry, definition)),
+            ];
+            for (const p of required) {
+                const bound = flow.edges.some((e) => e.kind === "data" && e.to === n.id && e.input === p.id);
+                if (!bound && !available.some((o) => typeAccepts(registry, o.type, p.type)))
+                    block("input-unbound", { input: p.label, type: p.type });
+            }
+        }
+        switch (n.kind) {
+            case "step":
+            case "variants": {
+                if (n.preset && !findPreset(registry, n.preset))
+                    warn("unknown-preset", { module: n.preset.module, preset: n.preset.id });
+                const runs = n.kind === "step" ? [n] : n.variants;
+                for (const r of runs) {
+                    if (!picks(registry.models, r.model))
+                        warn("unknown-model", { value: r.model ?? "" });
+                    if (!picks(registry.harnesses, r.harness))
+                        warn("unknown-harness", { value: r.harness ?? "" });
+                    if (!picks(registry.efforts, r.effort))
+                        warn("unknown-effort", { value: r.effort ?? "" });
+                }
+                if (n.kind === "variants") {
+                    if (n.variants.length < 2)
+                        block("variants-few");
+                    if (!n.select)
+                        block("variants-no-select");
+                    if (n.select === "evaluator" &&
+                        flow.nodes.find((x) => x.id === n.evaluator)?.kind !== "evaluator")
+                        block("variants-no-evaluator");
+                }
+                break;
+            }
+            case "subflow":
+                if (!n.flow)
+                    block("subflow-none");
+                else if (!definition.flows[n.flow])
+                    block("subflow-missing", { flow: n.flow });
+                else if (n.flow === name || callsFlow(definition, n.flow, name))
+                    block("subflow-recursive", { flow: n.flow });
+                break;
+            case "gate": {
+                const kind = findGateKind(registry, n.gate);
+                if (!kind) {
+                    block("unknown-gate-kind", { gate: n.gate });
+                    break;
+                }
+                const p = n.policy ?? {};
+                if (kind.fields.includes("approvers")) {
+                    const people = (p.roles?.length ?? 0) + (p.members?.length ?? 0);
+                    if (!people)
+                        block("gate-no-approver");
+                    else if (!p.roles?.length && (p.quorum ?? 1) > (p.members?.length ?? 0))
+                        block("gate-quorum", { quorum: p.quorum ?? 1, members: p.members?.length ?? 0 });
+                }
+                if (kind.fields.includes("threshold") && n.threshold === undefined)
+                    block("gate-no-threshold");
+                if (kind.fields.includes("rule") && !n.rule?.trim())
+                    block("gate-no-rule");
+                if (p.timeoutHours && !p.onTimeout)
+                    warn("gate-no-timeout-action");
+                break;
+            }
+            case "condition":
+                if (!n.cases.length)
+                    block("no-cases");
+                for (const c of n.cases)
+                    checkCondition(flow, c.when, registry, (code, more) => block(code, { case: c.label, ...more }));
+                break;
+            case "goto":
+                if (!n.target)
+                    block("goto-no-target");
+                else if (!ids.has(n.target) || n.target === n.id)
+                    block("goto-missing-target", { target: n.target });
+                if (!n.max)
+                    block("goto-no-max");
+                break;
+            case "fanout":
+                if (nextOut(n.id).length < 2)
+                    warn("fanout-few");
+                break;
+            case "join":
+                if (nextIn(n.id).length < 2)
+                    warn("join-few");
+                if (n.wait === "n" && !n.n)
+                    block("join-no-n");
+                break;
+            case "evaluator":
+                if (n.levels.length < 2)
+                    block("rubric-short");
+                if (n.routes && n.threshold === undefined)
+                    block("no-threshold");
+                if (!n.question?.trim())
+                    warn("no-question");
+                break;
+            case "classifier": {
+                if (n.options.length < 2)
+                    block("options-few");
+                const labels = n.options.map((o) => o.label);
+                const twice = labels.find((l, i) => labels.indexOf(l) !== i);
+                if (twice !== undefined)
+                    block("option-duplicate", { option: twice });
+                if (!n.question?.trim())
+                    warn("no-question");
+                break;
+            }
+            case "check":
+                if (!n.question.trim())
+                    block("no-question");
+                break;
+        }
+        // A routing node whose exit goes nowhere stops the run there.
+        if (exitsOf(n).length > 1)
+            for (const exit of exitsOf(n))
+                if (!nextOut(n.id).some((e) => portOf(e) === exit))
+                    warn("exit-unwired", { exit: exitLabel(n, exit) });
+        const availability = nodeAvailability(n, registry);
+        if (availability.status !== "available")
+            push("not-run", "not-runnable", at, v, availability);
+    }
+}
+/** Whether flow `from` calls flow `target`, directly or through other sub-flows. */
+function callsFlow(definition, from, target) {
+    const seen = new Set();
+    const stack = [from];
+    while (stack.length) {
+        const name = stack.pop();
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        for (const n of definition.flows[name]?.nodes ?? [])
+            if (n.kind === "subflow" && n.flow) {
+                if (n.flow === target)
+                    return true;
+                stack.push(n.flow);
+            }
+    }
+    return false;
+}
+/** Every problem in a definition, against what this destination's registry says. */
+export function checkDefinition(definition, registry) {
+    const out = [];
+    if (!definition.flows[definition.main])
+        out.push({ level: "blocking", code: "no-main", values: { flow: definition.main } });
+    for (const [name, flow] of Object.entries(definition.flows))
+        checkFlow(name, flow, definition, registry, (level, code, at = {}, values = {}, availability) => out.push({
+            level,
+            code,
+            flow: name,
+            ...at,
+            values,
+            ...(availability ? { availability } : {}),
+        }));
+    return out;
+}
+/** The problems that stop a publish. */
+export const blockingProblems = (problems) => problems.filter((p) => p.level === "blocking");

package/dist/workflow/run.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The run and review model the workflow run components read: stages,
+ * artifacts, gates, comments and decisions. Module-neutral: a stage is any
+ * unit of work, an artifact any typed output (a video, a contract, a filled
+ * form, a report), a gate any point where people or checks must say go.
+ * Times and sizes arrive formatted by the host, in its locale. Pure.
+ */
+import type { StatusTone } from "../status/tones.js";
+export type RunStageStatus = "pending" | "running" | "waiting" | "blocked" | "passed" | "failed" | "skipped" | "cancelled";
+/** Each stage status's tone; `running` also pulses. */
+export declare const RUN_STAGE_TONE: Record<RunStageStatus, StatusTone>;
+/** One named value a stage took in or gave out, summarized for display. */
+export interface RunValue {
+    label: string;
+    value: string;
+}
+/** One unit of work in a run. */
+export interface RunStage {
+    id: string;
+    label: string;
+    status: RunStageStatus;
+    /** When it started, formatted by the host ("14:02", "Nov 14, 14:02"). */
+    startedAt?: string;
+    /** How long it took or has taken, formatted by the host ("2m 14s"). */
+    duration?: string;
+    /** Which attempt this is, from 1. Shown when above 1 or when `maxAttempts` is set. */
+    attempt?: number;
+    maxAttempts?: number;
+    inputs?: readonly RunValue[];
+    outputs?: readonly RunValue[];
+    /** One line: why it failed, what it waits for. */
+    detail?: string;
+    /** Set when the stage is a gate. */
+    gate?: Gate;
+}
+export type GateStatus = "waiting" | "approved" | "rejected" | "expired" | "skipped";
+export declare const GATE_TONE: Record<GateStatus, StatusTone>;
+/** A point where people or checks must say go. */
+export interface Gate {
+    id: string;
+    /** What it asks, in the host's words ("Counsel sign-off", "Two approvers"). */
+    label: string;
+    status: GateStatus;
+    /** Approvals so far and needed, for a quorum. */
+    approvals?: number;
+    required?: number;
+    /** The decision that closed it. */
+    decision?: ReviewDecision;
+}
+/** A gate's or a review's closing decision. */
+export interface ReviewDecision {
+    verdict: "approved" | "rejected";
+    /** Why, as the person wrote it. Required for a rejection. */
+    reason?: string;
+    by?: string;
+    /** Formatted by the host. */
+    at?: string;
+}
+/** Where a review stands. */
+export type ReviewVerdict = "pending" | "approved" | "changes-requested" | "rejected";
+export declare const VERDICT_TONE: Record<ReviewVerdict, StatusTone>;
+export interface ReviewComment {
+    id: string;
+    author: string;
+    body: string;
+    /** Formatted by the host. */
+    at?: string;
+    /**
+     * Where in the artifact it points, as a module viewer labels it: a timecode
+     * ("00:01:12"), a region, a page and clause ("p. 3, 4.2"), a field.
+     */
+    anchor?: string;
+    resolved?: boolean;
+}
+export type ArtifactStatus = "draft" | "in-review" | "approved" | "rejected" | "superseded";
+export declare const ARTIFACT_TONE: Record<ArtifactStatus, StatusTone>;
+/** A typed output of a run. */
+export interface Artifact {
+    id: string;
+    name: string;
+    /** The host's type key ("video", "contract", "form", "report"); viewers switch on it. */
+    kind: string;
+    /** The type's display name ("Video", "Contract"). */
+    kindLabel: string;
+    /** The MIME type, when there is one. */
+    mediaType?: string;
+    /** Formatted by the host ("4.2 MB", "12 pages", "0:30"). */
+    size?: string;
+    version?: string;
+    status?: ArtifactStatus;
+    /** The stage that produced it, by label. */
+    producedBy?: string;
+    summary?: string;
+}

package/dist/workflow/run.js

@@ -0,0 +1,31 @@
+/** Each stage status's tone; `running` also pulses. */
+export const RUN_STAGE_TONE = {
+    pending: "muted",
+    running: "info",
+    waiting: "warn",
+    blocked: "warn",
+    passed: "ok",
+    failed: "error",
+    skipped: "muted",
+    cancelled: "muted",
+};
+export const GATE_TONE = {
+    waiting: "warn",
+    approved: "ok",
+    rejected: "error",
+    expired: "muted",
+    skipped: "muted",
+};
+export const VERDICT_TONE = {
+    pending: "muted",
+    approved: "ok",
+    "changes-requested": "warn",
+    rejected: "error",
+};
+export const ARTIFACT_TONE = {
+    draft: "muted",
+    "in-review": "warn",
+    approved: "ok",
+    rejected: "error",
+    superseded: "muted",
+};

package/dist/workflow/workspace.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Where a workflow document stands against the host's revisions: unsaved
+ * edits, a draft that differs from what runs, and a conflict when the saved
+ * revision moved under unsaved edits. Persistence and authority stay with the
+ * host; this only compares. Pure.
+ */
+import type { WorkflowDefinition } from "./definition.js";
+/** A revision as the host's authority holds it. */
+export interface WorkflowRevision {
+    /** Changes whenever the stored definition changes. */
+    id: string;
+    /** As the host labels it ("12", "2026-11-14.3"). */
+    label?: string;
+    /** Formatted by the host. */
+    at?: string;
+    by?: string;
+    definition: WorkflowDefinition;
+}
+export interface WorkflowDocumentStatus {
+    /** The working copy differs from the revision it started from (positions count). */
+    dirty: boolean;
+    /** What would run differs from what runs today (positions do not count). */
+    unpublished: boolean;
+    /** The saved revision moved to one this working copy did not start from, while it had edits. */
+    conflict: boolean;
+    /** Nothing has been saved or published yet. */
+    fresh: boolean;
+}
+/**
+ * Compares the working copy with the revision it started from (`base`), the
+ * host's latest saved revision, and the published one.
+ */
+export declare function documentStatus(draft: WorkflowDefinition, base: WorkflowRevision | null | undefined, saved: WorkflowRevision | null | undefined, published: WorkflowRevision | null | undefined): WorkflowDocumentStatus;

package/dist/workflow/workspace.js

@@ -0,0 +1,17 @@
+import { sameDefinition } from "./portable.js";
+/**
+ * Compares the working copy with the revision it started from (`base`), the
+ * host's latest saved revision, and the published one.
+ */
+export function documentStatus(draft, base, saved, published) {
+    const start = base ?? saved ?? published;
+    const dirty = start ? !sameDefinition(draft, start.definition) : true;
+    return {
+        dirty,
+        unpublished: published
+            ? !sameDefinition(draft, published.definition, { positions: false })
+            : true,
+        conflict: !!(dirty && base && saved && saved.id !== base.id),
+        fresh: !saved && !published,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calliopelabs/ui",
-  "version": "0.6.1",
+  "version": "0.11.0",
   "description": "Calliope AI shared operator UI: app shell, navigation, page frame, data table and list patterns, status colours, design tokens and appearance for Astrolift AI and Zentinelle AI.",
   "keywords": [
     "calliope-ai",
@@ -32,6 +32,10 @@
     },
     "./theme.css": "./dist/styles/theme.css",
     "./preset.css": "./dist/styles/preset.css",
+    "./css/tokens.css": "./dist/css/tokens.css",
+    "./css/appearance.js": "./dist/css/appearance.js",
+    "./css/components.css": "./dist/css/components.css",
+    "./css/calliope.css": "./dist/css/calliope.css",
     "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
@@ -55,6 +59,7 @@
     "build-storybook": "storybook build --quiet"
   },
   "dependencies": {
+    "@xyflow/react": "^12.12.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.58.0",