@markbrutx/promptbook-viewer 0.1.0

package/src/web/components/Addons.tsx

@@ -0,0 +1,109 @@
+import { kvLabel } from "../format.js";
+import type { LintResponse, Trace, When } from "../types.js";
+
+interface AddonsProps {
+  trace: Trace;
+  lint: LintResponse | null;
+}
+
+function whenLabel(when: When): string {
+  return Object.keys(when).length === 0 ? "always" : kvLabel(when);
+}
+
+/** Lint findings panel: severity-tagged messages with the fragment/rule origin. */
+function LintPanel({ lint }: { lint: LintResponse | null }) {
+  if (lint === null) {
+    return <p className="muted">—</p>;
+  }
+  if (lint.findings.length === 0) {
+    return <p className="muted">No findings ({lint.tokens} tokens).</p>;
+  }
+  return (
+    <ul className="findings">
+      {lint.findings.map((finding, index) => (
+        <li key={`${finding.ruleId}:${index}`} className={`finding ${finding.severity}`}>
+          <span className="finding-sev">{finding.severity}</span>
+          <span className="finding-rule">{finding.ruleId}</span>
+          <span>{finding.message}</span>
+          {finding.fragmentId ? <code className="finding-frag">{finding.fragmentId}</code> : null}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/** Explain trace panel: which rules fired and why, plus the net effects. */
+function ExplainPanel({ trace }: { trace: Trace }) {
+  return (
+    <div className="explain">
+      <h4>Rules</h4>
+      <ul className="rules">
+        {trace.rules.map((rule) => (
+          <li key={rule.index} className={rule.fired ? "fired" : "skipped"}>
+            <span className="rule-mark">{rule.fired ? "✓" : "·"}</span>
+            <span className="rule-action">{rule.action}</span>
+            <span className="muted">when {whenLabel(rule.when)}</span>
+            {rule.effect ? <div className="rule-effect">{rule.effect}</div> : null}
+            {rule.reason ? <div className="rule-reason">{rule.reason}</div> : null}
+          </li>
+        ))}
+        {trace.rules.length === 0 ? <li className="muted">No rules.</li> : null}
+      </ul>
+
+      <h4>Final order</h4>
+      <p className="order">{trace.finalOrder.join(" → ") || "(empty)"}</p>
+
+      {trace.replaced.length > 0 ? (
+        <p>
+          <strong>replaced:</strong> {trace.replaced.map((r) => `${r.from}→${r.to}`).join(", ")}
+        </p>
+      ) : null}
+      {trace.added.length > 0 ? (
+        <p>
+          <strong>added:</strong> {trace.added.map((a) => a.id).join(", ")}
+        </p>
+      ) : null}
+      {trace.forbidden.length > 0 ? (
+        <p>
+          <strong>forbidden:</strong> {trace.forbidden.map((f) => f.id).join(", ")}
+        </p>
+      ) : null}
+
+      {trace.unmatchedAxes.length > 0 ? (
+        <p className="warn">
+          <strong>unmatched axes:</strong>{" "}
+          {trace.unmatchedAxes.map((axis) => `${axis.key}=${axis.value}`).join(", ")}
+        </p>
+      ) : null}
+      {trace.warnings.length > 0 ? (
+        <ul className="warnings">
+          {trace.warnings.map((warning) => (
+            <li key={warning} className="warn">
+              {warning}
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </div>
+  );
+}
+
+/** Right-hand Addons rail: tokens, lint, and the explain trace. */
+export function Addons({ trace, lint }: AddonsProps) {
+  return (
+    <aside className="addons">
+      <section>
+        <h3>Tokens</h3>
+        <p className="tokens">{lint ? `~${lint.tokens}` : "—"}</p>
+      </section>
+      <section>
+        <h3>Lint</h3>
+        <LintPanel lint={lint} />
+      </section>
+      <section>
+        <h3>Explain</h3>
+        <ExplainPanel trace={trace} />
+      </section>
+    </aside>
+  );
+}

package/src/web/components/Canvas.tsx

@@ -0,0 +1,180 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { type AnchorSpec, markAnchors } from "../annotations.js";
+import { fragmentAccent, fragmentColor } from "../colors.js";
+import type { Annotation, Segment } from "../types.js";
+
+interface CanvasProps {
+  title: string;
+  subtitle?: string;
+  segments: Segment[];
+  tokens?: number;
+  /** Open annotations for this variant, highlighted inside their fragment. */
+  annotations: Annotation[];
+  /** Persist a new annotation for the selected fragment text. */
+  onAnnotate: (fragmentId: string, anchorText: string, comment: string) => Promise<void>;
+}
+
+/** A pending selection awaiting a comment, anchored near the selected text. */
+interface Draft {
+  fragmentId: string;
+  anchorText: string;
+  top: number;
+  left: number;
+}
+
+/** Read the current text selection, if it lands inside a segment's body. */
+function selectionDraft(): Draft | null {
+  const selection = window.getSelection();
+  if (selection === null || selection.isCollapsed) {
+    return null;
+  }
+  const anchorText = selection.toString().trim();
+  if (anchorText === "") {
+    return null;
+  }
+  const node = selection.anchorNode;
+  const element = node instanceof Element ? node : (node?.parentElement ?? null);
+  const host = element?.closest<HTMLElement>("[data-fragment-id]") ?? null;
+  const fragmentId = host?.dataset.fragmentId;
+  if (fragmentId === undefined) {
+    return null;
+  }
+  const rect = selection.getRangeAt(0).getBoundingClientRect();
+  return { fragmentId, anchorText, top: rect.bottom, left: rect.left };
+}
+
+/**
+ * The assembled prompt, each segment tinted by its source fragment. The
+ * segments concatenate (with blank lines between them) into the exact resolved
+ * text, so what is shown here is byte-for-byte the prompt the model would see.
+ * Selecting text opens a comment popover; existing annotations are highlighted.
+ */
+export function Canvas({ title, subtitle, segments, tokens, annotations, onAnnotate }: CanvasProps) {
+  const ids = [...new Set(segments.map((s) => s.fragmentId))];
+  const [draft, setDraft] = useState<Draft | null>(null);
+  const [comment, setComment] = useState("");
+  const [saving, setSaving] = useState(false);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  // A document-level listener keeps interaction handlers off the static prompt
+  // markup (and selections outside a segment are simply ignored).
+  useEffect(() => {
+    const onMouseUp = (): void => {
+      const next = selectionDraft();
+      if (next !== null) {
+        setDraft(next);
+        setComment("");
+      }
+    };
+    document.addEventListener("mouseup", onMouseUp);
+    return () => document.removeEventListener("mouseup", onMouseUp);
+  }, []);
+
+  useEffect(() => {
+    if (draft !== null) {
+      textareaRef.current?.focus();
+    }
+  }, [draft]);
+
+  // Group anchors by fragment once per annotations change, so each segment does
+  // a map lookup instead of scanning the whole list on every render.
+  const anchorsByFragment = useMemo(() => {
+    const byFragment = new Map<string, AnchorSpec[]>();
+    for (const a of annotations) {
+      const list = byFragment.get(a.anchor.fragmentId) ?? [];
+      list.push({ id: a.id, anchorText: a.anchor.anchorText });
+      byFragment.set(a.anchor.fragmentId, list);
+    }
+    return byFragment;
+  }, [annotations]);
+
+  const submit = async (): Promise<void> => {
+    if (draft === null || comment.trim() === "") {
+      return;
+    }
+    setSaving(true);
+    try {
+      await onAnnotate(draft.fragmentId, draft.anchorText, comment.trim());
+      setDraft(null);
+      setComment("");
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <main className="canvas">
+      <header className="canvas-head">
+        <div>
+          <h1 className="canvas-title">{title}</h1>
+          {subtitle ? <p className="muted">{subtitle}</p> : null}
+        </div>
+        {tokens !== undefined ? <span className="badge">~{tokens} tokens</span> : null}
+      </header>
+
+      {ids.length > 0 ? (
+        <ul className="legend">
+          {ids.map((id) => (
+            <li key={id}>
+              <span className="swatch" style={{ background: fragmentAccent(id) }} />
+              {id}
+            </li>
+          ))}
+        </ul>
+      ) : null}
+
+      <div className="prompt">
+        {segments.length === 0 ? (
+          <p className="muted">No fragments rendered for this context.</p>
+        ) : (
+          segments.map((segment) => (
+            <pre
+              key={segment.fragmentId}
+              className="segment"
+              data-fragment-id={segment.fragmentId}
+              style={{
+                background: fragmentColor(segment.fragmentId),
+                borderColor: fragmentAccent(segment.fragmentId),
+              }}
+              title={segment.fragmentId}
+            >
+              <span className="segment-tag">{segment.fragmentId}</span>
+              {annotations.length === 0
+                ? segment.text
+                : markAnchors(segment.text, anchorsByFragment.get(segment.fragmentId) ?? []).map(
+                    (run, index) =>
+                      run.annotationId !== undefined ? (
+                        <mark key={index} className="annot-mark">
+                          {run.text}
+                        </mark>
+                      ) : (
+                        <span key={index}>{run.text}</span>
+                      ),
+                  )}
+            </pre>
+          ))
+        )}
+      </div>
+
+      {draft !== null ? (
+        <div className="annot-popover" style={{ top: draft.top, left: draft.left }}>
+          <p className="annot-quote">“{draft.anchorText}”</p>
+          <textarea
+            ref={textareaRef}
+            value={comment}
+            placeholder="Comment for the agent…"
+            onChange={(event) => setComment(event.target.value)}
+          />
+          <div className="annot-actions">
+            <button type="button" className="link" onClick={() => setDraft(null)}>
+              Cancel
+            </button>
+            <button type="button" disabled={saving || comment.trim() === ""} onClick={() => void submit()}>
+              Save
+            </button>
+          </div>
+        </div>
+      ) : null}
+    </main>
+  );
+}

package/src/web/components/CodePromptView.tsx

@@ -0,0 +1,87 @@
+import { useState } from "react";
+import { kvLabel } from "../format.js";
+import type { CodePromptSummary } from "../types.js";
+import { Diff } from "./Diff.js";
+
+interface CodePromptViewProps {
+  codePrompt: CodePromptSummary;
+  /** The sample label currently shown. */
+  sample: string;
+  onSelectSample: (label: string) => void;
+}
+
+/**
+ * A code-prompt node: a builder-backed prompt the core never executes. The
+ * canvas shows a captured snapshot of its output (no fragment breakdown, since
+ * the builder is opaque) with a "code" badge, lets you switch samples, and
+ * diffs two snapshots. Honest about being computed, not declarative.
+ */
+export function CodePromptView({ codePrompt, sample, onSelectSample }: CodePromptViewProps) {
+  const [compare, setCompare] = useState("");
+  const samples = codePrompt.samples;
+  const current = samples.find((s) => s.label === sample) ?? samples[0];
+  const other = samples.find((s) => s.label === compare);
+
+  return (
+    <main className="canvas">
+      <header className="canvas-head">
+        <div>
+          <h1 className="canvas-title">
+            {codePrompt.name} <span className="badge badge-code">code</span>
+          </h1>
+          {codePrompt.description ? <p className="muted">{codePrompt.description}</p> : null}
+        </div>
+      </header>
+
+      {samples.length === 0 || current === undefined ? (
+        <p className="muted">No samples captured for this code-prompt.</p>
+      ) : (
+        <>
+          <div className="code-tabs">
+            {samples.map((s) => (
+              <button
+                key={s.label}
+                type="button"
+                className={`code-tab${s.label === current.label ? " active" : ""}`}
+                onClick={() => onSelectSample(s.label)}
+              >
+                {s.label}
+              </button>
+            ))}
+          </div>
+
+          <div className="prompt">
+            <pre className="segment code-sample">
+              <span className="segment-tag">
+                code{current.context ? ` · ${kvLabel(current.context)}` : ""}
+              </span>
+              {current.output}
+            </pre>
+          </div>
+
+          <section className="code-diff">
+            <h3>Diff</h3>
+            <select value={compare} onChange={(event) => setCompare(event.target.value)}>
+              <option value="">Compare with…</option>
+              {samples
+                .filter((s) => s.label !== current.label)
+                .map((s) => (
+                  <option key={s.label} value={s.label}>
+                    {s.label}
+                  </option>
+                ))}
+            </select>
+            {other !== undefined ? (
+              <Diff
+                leftLabel={other.label}
+                rightLabel={current.label}
+                leftText={other.output}
+                rightText={current.output}
+              />
+            ) : null}
+          </section>
+        </>
+      )}
+    </main>
+  );
+}

package/src/web/components/Controls.tsx

@@ -0,0 +1,71 @@
+import { useState } from "react";
+import type { Context, ContextValue } from "../types.js";
+
+interface ControlsProps {
+  /** Keys worth offering: the union of rule `when` keys and current context. */
+  keys: string[];
+  context: Context;
+  onChange: (context: Context) => void;
+}
+
+const NUMERIC = /^-?\d+(?:\.\d+)?$/;
+
+/** Coerce a raw input string like the CLI's `--ctx`: bool, number, else string. */
+function coerce(raw: string): ContextValue {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (NUMERIC.test(raw)) return Number(raw);
+  return raw;
+}
+
+/**
+ * Context pickers = Storybook Controls. Editing a field re-resolves the variant
+ * live. Keys come from the composition's `when` conditions plus whatever the
+ * selected variant set; an extra row adds ad-hoc keys.
+ */
+export function Controls({ keys, context, onChange }: ControlsProps) {
+  const [newKey, setNewKey] = useState("");
+
+  const setValue = (key: string, raw: string): void => {
+    const next: Context = { ...context };
+    if (raw === "") {
+      delete next[key];
+    } else {
+      next[key] = coerce(raw);
+    }
+    onChange(next);
+  };
+
+  const offered = [...new Set([...keys, ...Object.keys(context)])].sort();
+
+  return (
+    <div className="controls">
+      {offered.length === 0 ? <p className="muted">No context axes.</p> : null}
+      {offered.map((key) => (
+        <label key={key} className="control-row">
+          <span className="control-key">{key}</span>
+          <input
+            value={context[key] === undefined ? "" : String(context[key])}
+            placeholder="(unset)"
+            onChange={(event) => setValue(key, event.target.value)}
+          />
+        </label>
+      ))}
+
+      <form
+        className="control-add"
+        onSubmit={(event) => {
+          event.preventDefault();
+          const key = newKey.trim();
+          if (key !== "") {
+            onChange({ ...context, [key]: "" });
+            setNewKey("");
+          }
+        }}
+      >
+        <input value={newKey} placeholder="add axis…" onChange={(event) => setNewKey(event.target.value)} />
+        <button type="submit">+</button>
+      </form>
+    </div>
+  );
+}

package/src/web/components/Diff.tsx

@@ -0,0 +1,30 @@
+import { diffLines } from "../diff.js";
+
+interface DiffProps {
+  leftLabel: string;
+  rightLabel: string;
+  leftText: string;
+  rightText: string;
+}
+
+const MARK: Record<string, string> = { equal: " ", add: "+", remove: "-" };
+
+/** Line diff of two variants of the same composition. */
+export function Diff({ leftLabel, rightLabel, leftText, rightText }: DiffProps) {
+  const rows = diffLines(leftText, rightText);
+  return (
+    <div className="diff">
+      <p className="muted">
+        − {leftLabel} &nbsp; + {rightLabel}
+      </p>
+      <pre className="diff-body">
+        {rows.map((row, index) => (
+          <div key={`${index}:${row.text}`} className={`diff-row ${row.type}`}>
+            <span className="diff-mark">{MARK[row.type]}</span>
+            {row.text}
+          </div>
+        ))}
+      </pre>
+    </div>
+  );
+}

package/src/web/components/FragmentView.tsx

@@ -0,0 +1,54 @@
+import { fragmentAccent } from "../colors.js";
+import type { FragmentSummary, UsedInResponse } from "../types.js";
+
+interface FragmentViewProps {
+  fragment: FragmentSummary;
+  usedIn: UsedInResponse | null;
+  onSelectVariant: (composition: string) => void;
+}
+
+/** Inspect a fragment: its body, metadata, and where it is used (the graph). */
+export function FragmentView({ fragment, usedIn, onSelectVariant }: FragmentViewProps) {
+  return (
+    <main className="canvas">
+      <header className="canvas-head">
+        <div>
+          <h1 className="canvas-title">
+            <span className="swatch" style={{ background: fragmentAccent(fragment.id) }} />
+            {fragment.id}
+          </h1>
+          <p className="muted">
+            {fragment.kind ?? "—"}
+            {fragment.tags.length > 0 ? ` · ${fragment.tags.join(", ")}` : ""} · {fragment.sourceFile}
+          </p>
+        </div>
+      </header>
+
+      <pre className="segment" style={{ background: "#f6f8fa" }}>
+        {fragment.body}
+      </pre>
+
+      <section className="used-in">
+        <h3>Used in</h3>
+        {usedIn === null || usedIn.references.length === 0 ? (
+          <p className="muted">Not referenced by any composition.</p>
+        ) : (
+          <ul className="used-list">
+            {usedIn.references.map((ref, index) => (
+              <li key={`${ref.composition}:${ref.role}:${index}`}>
+                <button type="button" className="link" onClick={() => onSelectVariant(ref.composition)}>
+                  {ref.composition}
+                </button>
+                <span className="muted">
+                  {" "}
+                  {ref.role}
+                  {ref.ruleIndex !== undefined ? ` (rule #${ref.ruleIndex})` : ""}
+                </span>
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+    </main>
+  );
+}