paseo-plugin-genui 0.0.0-stage → 0.1.0

package/shared/logic/references-model.ts

@@ -0,0 +1,201 @@
+// Pure readers behind the reference renderers (references.tsx): Entity,
+// Sources and Hotspots. They turn the loose shapes models write into exactly
+// what the components draw, and report what they cannot read instead of
+// throwing. A list that is still streaming ends in a half-written item; the
+// readers skip that last item quietly rather than flash an error for it.
+import type { Value } from "../core/types";
+import { isNode, isObject, text } from "./values";
+import type { KeyValuePair } from "./content-model";
+
+// ---------------------------------------------------------------------------
+// URLs and images
+
+/** An absolute URL with one of `schemes` (lowercase, without `:`), or null. */
+export function parseUrl(raw: string, schemes: readonly string[]): URL | null {
+  const trimmed = raw.trim();
+  if (trimmed === "") return null;
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  return schemes.includes(url.protocol.slice(0, -1)) && url.hostname !== "" ? url : null;
+}
+
+/** The host a reader recognizes: `www.` dropped, port kept. */
+export function domainOf(url: URL): string {
+  return url.host.replace(/^www\./i, "");
+}
+
+/** The readable part of a URL after its host (`/docs/intro` → `docs/intro`), or null for a bare host. */
+export function pathOf(url: URL): string | null {
+  let path: string;
+  try {
+    path = decodeURIComponent(url.pathname);
+  } catch {
+    path = url.pathname;
+  }
+  path = path.replace(/^\/+|\/+$/g, "");
+  return path === "" ? null : path;
+}
+
+/** What an image `src` names: an https URL or a thread file, both loaded through the runtime; or a refusal. */
+export type ImageRef =
+  | { readonly kind: "none" }
+  | { readonly kind: "load"; readonly src: string }
+  | { readonly kind: "invalid"; readonly error: string };
+
+export function imageRef(src: string): ImageRef {
+  const trimmed = src.trim();
+  if (trimmed === "") return { kind: "none" };
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed)?.[1]?.toLowerCase();
+  // `C:\…` is a Windows path, not a URL scheme.
+  if (scheme === undefined || /^[a-z]:[\\/]/i.test(trimmed)) return { kind: "load", src: trimmed };
+  if (scheme !== "https") {
+    return { kind: "invalid", error: `Images must be https URLs or file paths; ${scheme}: links can't be shown` };
+  }
+  const url = parseUrl(trimmed, ["https"]);
+  return url === null ? { kind: "invalid", error: `Invalid image URL: ${trimmed}` } : { kind: "load", src: url.href };
+}
+
+// ---------------------------------------------------------------------------
+// Entity
+
+export const ENTITY_KINDS = ["product", "place", "person", "org", "link", "other"] as const;
+export type EntityKind = (typeof ENTITY_KINDS)[number];
+
+export function entityKind(value: unknown): EntityKind {
+  return typeof value === "string" && (ENTITY_KINDS as readonly string[]).includes(value)
+    ? (value as EntityKind)
+    : "other";
+}
+
+/** The facts worth showing on the card itself: the first `max` with a plain, non-empty value. */
+export function inlineFacts(
+  pairs: readonly KeyValuePair[],
+  max: number,
+): { readonly label: string; readonly value: string }[] {
+  const out: { label: string; value: string }[] = [];
+  for (const [label, value] of pairs) {
+    if (out.length >= max) break;
+    const shown = typeof value === "string" ? value.trim() : typeof value === "number" || typeof value === "boolean" ? String(value) : "";
+    if (shown !== "") out.push({ label: label.trim(), value: shown });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Sources
+
+export type SourceLink =
+  | {
+      readonly ok: true;
+      /** 1-based position in the list as written, so `[2]` in prose names the second link. */
+      readonly number: number;
+      readonly href: string;
+      /** The given title, else the domain. */
+      readonly title: string;
+      readonly domain: string;
+      /** The path, shown when there is no title to say what the page is. */
+      readonly path: string | null;
+      readonly note: string | null;
+    }
+  | { readonly ok: false; readonly number: number; readonly error: string };
+
+/** `https://…` strings or `{url, title?, note?}` objects; anything else keeps its number and reports why. */
+export function sourceLinks(items: readonly Value[]): SourceLink[] {
+  const out: SourceLink[] = [];
+  items.forEach((item, index) => {
+    const number = index + 1;
+    const last = index === items.length - 1;
+    const fields: Readonly<Record<string, unknown>> | null =
+      typeof item === "string" ? { url: item } : isObject(item) && !isNode(item) ? item : null;
+    if (fields === null) {
+      out.push({ ok: false, number, error: "Each source must be an https URL or {url, title?, note?}" });
+      return;
+    }
+    // A streaming `{title: "…"` has not reached its url yet.
+    if (fields.url === undefined && last) return;
+    const raw = text(fields.url).trim();
+    const url = parseUrl(raw, ["https"]);
+    if (url === null) {
+      out.push({
+        ok: false,
+        number,
+        error: raw === "" ? "This source has no url" : `Not an https link: ${raw}`,
+      });
+      return;
+    }
+    const title = text(fields.title).trim();
+    const note = text(fields.note).trim();
+    out.push({
+      ok: true,
+      number,
+      href: url.href,
+      title: title === "" ? domainOf(url) : title,
+      domain: domainOf(url),
+      path: title === "" ? pathOf(url) : null,
+      note: note === "" ? null : note,
+    });
+  });
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Hotspots
+
+export interface HotspotPoint {
+  /** 1-based, shared by the pin and its row in the list. */
+  readonly number: number;
+  /** Percent across the image, 0–100. */
+  readonly x: number;
+  /** Percent down the image, 0–100. */
+  readonly y: number;
+  readonly title: string;
+  readonly text: string | null;
+}
+
+/** A percentage: a number, or a string such as `"40"` or `"40%"`; clamped to 0–100. */
+export function percent(value: unknown): number | null {
+  const number =
+    typeof value === "number"
+      ? value
+      : typeof value === "string" && /^\s*-?\d+(\.\d+)?\s*%?\s*$/.test(value)
+        ? Number.parseFloat(value)
+        : Number.NaN;
+  return Number.isFinite(number) ? Math.min(100, Math.max(0, number)) : null;
+}
+
+/**
+ * `{x, y, title, text?}` points, numbered in order. A point without a
+ * usable x/y is reported (its number goes to the next good point); the last
+ * point is skipped quietly while it lacks x, y or title, because a
+ * streaming list ends in one that is still being written.
+ */
+export function hotspotPoints(items: readonly Value[]): {
+  readonly points: HotspotPoint[];
+  readonly problems: string[];
+} {
+  const points: HotspotPoint[] = [];
+  const problems: string[] = [];
+  items.forEach((item: unknown, index) => {
+    const last = index === items.length - 1;
+    if (!isObject(item) || isNode(item)) {
+      problems.push(`Point ${index + 1} must be {x, y, title, text?}`);
+      return;
+    }
+    const x = percent(item.x);
+    const y = percent(item.y);
+    const title = text(item.title).trim();
+    if (last && (x === null || y === null || title === "")) return;
+    if (x === null || y === null) {
+      problems.push(`Point ${index + 1}${title === "" ? "" : ` (${title})`} needs x and y in % (0–100)`);
+      return;
+    }
+    const body = text(item.text).trim();
+    const number = points.length + 1;
+    points.push({ number, x, y, title: title === "" ? `Point ${number}` : title, text: body === "" ? null : body });
+  });
+  return { points, problems };
+}

package/shared/logic/sketch.ts

@@ -0,0 +1,165 @@
+// Turns a model's Mermaid source into an Excalidraw-looking diagram: Mermaid's
+// hand-drawn look (rough strokes, hachure fills) in Excalifont, in Excalidraw's
+// palette. Excalidraw's dark theme is its light canvas through
+// `invert(93%) hue-rotate(180deg)`; the dark palette here is that filter
+// worked out per colour, so the SVG is drawn dark natively and BB's zoom view,
+// which copies the SVG elsewhere, shows it right too. Pure: no DOM.
+
+/** The font family the diagram text uses; Excalifont is loaded by sketchFont.ts. */
+export const SKETCH_FONT_FAMILY = "Excalifont, 'Segoe Print', 'Bradley Hand', 'Comic Sans MS', cursive";
+
+/** Excalidraw's stroke and fill colours (its default palette, light theme). */
+const LIGHT = {
+  ink: "#1e1e1e",
+  canvas: "#ffffff",
+  blue: "#a5d8ff",
+  green: "#b2f2bb",
+  yellow: "#ffec99",
+  red: "#ffc9c9",
+  violet: "#d0bfff",
+  gray: "#f1f3f5",
+  /** Clickable nodes (Diagram details): outline, hover hachure, selected hachure. */
+  link: "#1971c2",
+  hover: "#74c0fc",
+  selected: "#ffd43b",
+} as const;
+
+export type SketchPalette = { readonly [K in keyof typeof LIGHT]: string };
+
+const channel = (value: number) => Math.round(Math.min(255, Math.max(0, value)));
+
+/** A colour through Excalidraw's dark-theme filter: invert(93%), then hue-rotate(180deg). */
+export function darkened(hex: string): string {
+  const [r, g, b] = [1, 3, 5].map((at) => 255 * 0.93 + parseInt(hex.slice(at, at + 2), 16) * (1 - 2 * 0.93));
+  // The CSS hue-rotate matrix at 180°.
+  const rotated = [-0.574 * r + 1.43 * g + 0.144 * b, 0.426 * r + 0.43 * g + 0.144 * b, 0.426 * r + 1.43 * g - 0.856 * b];
+  return `#${rotated.map((value) => channel(value).toString(16).padStart(2, "0")).join("")}`;
+}
+
+const DARK = Object.fromEntries(Object.entries(LIGHT).map(([name, hex]) => [name, darkened(hex)])) as SketchPalette;
+
+export function sketchPalette(dark: boolean): SketchPalette {
+  return dark ? DARK : LIGHT;
+}
+
+/** One seed, so every render of the same diagram draws the same wobble. */
+const SEED = 7;
+
+/** `backdrop` is the colour the diagram is drawn on; edge labels are cut out of the lines with it. */
+function frontmatter(colors: SketchPalette, backdrop: string): string {
+  const variables: Record<string, string> = {
+    fontFamily: SKETCH_FONT_FAMILY,
+    fontSize: "17px",
+    background: backdrop,
+    primaryColor: colors.blue,
+    mainBkg: colors.blue,
+    secondaryColor: colors.green,
+    tertiaryColor: colors.yellow,
+    primaryBorderColor: colors.ink,
+    nodeBorder: colors.ink,
+    primaryTextColor: colors.ink,
+    textColor: colors.ink,
+    lineColor: colors.ink,
+    edgeLabelBackground: backdrop,
+    clusterBkg: colors.gray,
+    clusterBorder: colors.ink,
+    titleColor: colors.ink,
+    actorBkg: colors.blue,
+    actorBorder: colors.ink,
+    actorTextColor: colors.ink,
+    actorLineColor: colors.ink,
+    signalColor: colors.ink,
+    signalTextColor: colors.ink,
+    labelBoxBkgColor: colors.yellow,
+    labelBoxBorderColor: colors.ink,
+    labelTextColor: colors.ink,
+    loopTextColor: colors.ink,
+    noteBkgColor: colors.yellow,
+    noteBorderColor: colors.ink,
+    noteTextColor: colors.ink,
+    activationBkgColor: colors.gray,
+    activationBorderColor: colors.ink,
+  };
+  return [
+    "---",
+    "config:",
+    "  look: handDrawn",
+    `  handDrawnSeed: ${SEED}`,
+    "  theme: base",
+    "  darkMode: false",
+    `  fontFamily: "${SKETCH_FONT_FAMILY}"`,
+    "  themeVariables:",
+    ...Object.entries(variables).map(([name, value]) => `    ${name}: "${value}"`),
+    "---",
+  ].join("\n");
+}
+
+/** Flowchart node shapes that get their own colour, as Excalidraw users colour-code. */
+const SHAPE_CLASSES = [
+  // id{text} or id{{text}}: a decision.
+  { name: "sketchDecision", color: "yellow", openers: ["{", "{{"] },
+  // id[(text)]: a data store.
+  { name: "sketchStore", color: "green", openers: ["[("] },
+  // id((text)) or id(((text))): a start or end point.
+  { name: "sketchTerminal", color: "red", openers: ["((", "((("] },
+  // id>text]: a flag, often an input or event.
+  { name: "sketchEvent", color: "violet", openers: [">"] },
+] as const;
+
+/** Lines that define no nodes. */
+const NOT_NODES = /^\s*(%%|subgraph\b|end\b|direction\b|click\b|class\b|classDef\b|style\b|linkStyle\b|flowchart\b|graph\b)/;
+/** Arrows and `&` separate the nodes on a line: -->, ---, -.->, ==>, --o, <-->, ~~~ … */
+const SEPARATORS = /\s*(?:<?(?:-{2,}|-\.+-|={2,}|~{3,})[->ox]?|&)\s*/;
+/** A segment that starts a node: its id and the shape opener after it, if any. */
+const NODE_START = /^([A-Za-z_][\w-]*)\s*(\{\{|\{|\[\(|\(\(\(|\(\(|>)?/;
+
+function isFlowchart(source: string): boolean {
+  return /^\s*(flowchart|graph)\b/.test(source);
+}
+
+/** The model set its own look: front matter or an init directive. */
+function hasOwnStyling(source: string): boolean {
+  return /^\s*---/.test(source) || /%%\{\s*init/.test(source);
+}
+
+function hasOwnClasses(source: string): boolean {
+  return /\bclassDef\b|^\s*style\s|:::/m.test(source);
+}
+
+/** Class lines colouring decisions, data stores, terminals and events in a flowchart. */
+export function shapeClassLines(source: string, colors: SketchPalette = LIGHT): string[] {
+  if (!isFlowchart(source) || hasOwnClasses(source)) return [];
+  const members = new Map<string, Set<string>>(SHAPE_CLASSES.map((shape) => [shape.name, new Set()]));
+  for (const line of source.split("\n")) {
+    if (NOT_NODES.test(line)) continue;
+    // Edge text (|…|) and quoted labels can hold braces that are not shapes.
+    const bare = line.replace(/\|[^|]*\|/g, " ").replace(/"[^"]*"/g, '""');
+    for (const segment of bare.split(SEPARATORS)) {
+      const [, id, opener] = NODE_START.exec(segment.trim()) ?? [];
+      if (id === undefined || opener === undefined) continue;
+      const shape = SHAPE_CLASSES.find((candidate) => (candidate.openers as readonly string[]).includes(opener));
+      if (shape !== undefined) members.get(shape.name)?.add(id);
+    }
+  }
+  const lines: string[] = [];
+  for (const shape of SHAPE_CLASSES) {
+    const ids = [...(members.get(shape.name) ?? [])];
+    if (ids.length === 0) continue;
+    lines.push(`  classDef ${shape.name} fill:${colors[shape.color]}`, `  class ${ids.join(",")} ${shape.name}`);
+  }
+  return lines;
+}
+
+/**
+ * The source BB's Mermaid renderer gets. A diagram that brings its own front
+ * matter or init directive keeps it untouched; one with its own class or style
+ * lines keeps its colours but still gets the hand-drawn look. The diagram has
+ * no canvas of its own: it is drawn on `backdrop`, Excalidraw's canvas colour
+ * if none is given.
+ */
+export function sketchMermaid(source: string, dark = false, backdrop?: string): string {
+  const trimmed = source.trim();
+  if (hasOwnStyling(trimmed)) return trimmed;
+  const colors = sketchPalette(dark);
+  return [frontmatter(colors, backdrop ?? colors.canvas), trimmed, ...shapeClassLines(trimmed, colors)].join("\n");
+}

package/shared/logic/supersession.ts

@@ -0,0 +1,77 @@
+// Pure rules behind useSuperseded: whether a reply has been answered, and
+// which thread changes can change that. No React, no DOM, no SDK.
+
+/** One message of BB's conversation outline (`sdk.threads.conversationOutline`), in thread order. */
+export interface OutlineItem {
+  readonly id: string;
+  readonly role: "assistant" | "user";
+}
+
+/** A user row's event sequence, from its `<thread>:user-seed:<seq>` id; null for any other id. */
+function userSeq(id: string): number | null {
+  const match = /:user-seed:(\d+)$/.exec(id);
+  return match === null ? null : Number(match[1]);
+}
+
+/**
+ * Whether a user message follows the message `anchorId` (the assistant reply
+ * holding a block). Null when the anchor is not in the outline, so the
+ * caller can keep what it knew: a nested agent's message, or a reply the
+ * outline no longer lists.
+ *
+ * A user row whose sequence is below one already seen is out of place, not a
+ * reply: BB's outline can list a rejected steer, sent long before, at its end.
+ */
+export function hasLaterUserMessage(items: readonly OutlineItem[] | null, anchorId: string): boolean | null {
+  if (items === null) return null;
+  const anchor = items.findIndex((item) => item.id === anchorId);
+  if (anchor === -1) return null;
+  let highest = -1;
+  for (const [index, item] of items.entries()) {
+    if (item.role !== "user") continue;
+    const seq = userSeq(item.id);
+    if (seq !== null && seq < highest) continue;
+    if (index > anchor) return true;
+    if (seq !== null) highest = seq;
+  }
+  return false;
+}
+
+/** The part of BB's `thread:changed` realtime event this module reads. */
+export interface ThreadChange {
+  readonly changes: readonly string[];
+  readonly metadata?: { readonly eventTypes?: readonly string[] };
+}
+
+/**
+ * Thread events that add, accept, reject or drop a user message. Every user
+ * message (typed, sent by a plugin or the CLI, dispatched from the queue)
+ * enters as `client/turn/requested`; the rest cover steering, manager
+ * messages and context resets.
+ */
+const CONVERSATION_EVENTS: Readonly<Record<string, true>> = {
+  "client/thread/start": true,
+  "client/turn/requested": true,
+  "client/turn/rejected": true,
+  "client/turn/start": true,
+  "turn/input/accepted": true,
+  "turn/started": true,
+  "system/manager/user_message": true,
+  "thread/context/cleared": true,
+  "thread/compacted": true,
+};
+
+/**
+ * Whether a change can move a user message in or out of the outline, so it
+ * must be read again. Streaming deltas and tool progress never can, which
+ * keeps a running reply from refetching on every token.
+ */
+export function affectsConversation(change: ThreadChange): boolean {
+  return change.changes.some((kind) => {
+    if (kind === "history-rewritten" || kind === "history-compacted") return true;
+    if (kind !== "events-appended") return false;
+    const types = change.metadata?.eventTypes;
+    // An append that doesn't say what it appended may be anything.
+    return types === undefined || types.some((type) => Object.hasOwn(CONVERSATION_EVENTS, type));
+  });
+}

package/shared/logic/values.ts

@@ -0,0 +1,133 @@
+// Defensive readers for evaluated props. The core normalizes params by kind,
+// but plain objects in a spec can mimic node/action shapes, so every reader
+// checks the shape it relies on instead of trusting the declared kind.
+import type { Action, Binding, Scalar, UiNode, Value } from "../core/types";
+
+export type Props = Readonly<Record<string, Value>>;
+
+/** The one object guard of the renderer; callers still check each field. */
+export function isObject(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function asRecord(value: unknown): Readonly<Record<string, Value>> | null {
+  if (!isObject(value)) return null;
+  if ("kind" in value && (value.kind === "node" || value.kind === "action" || value.kind === "binding")) {
+    return null;
+  }
+  return value as Readonly<Record<string, Value>>;
+}
+
+export function isNode(value: unknown): value is UiNode {
+  return (
+    isObject(value) &&
+    value.kind === "node" &&
+    typeof value.type === "string" &&
+    typeof value.key === "string" &&
+    isObject(value.props)
+  );
+}
+
+export function isBinding(value: unknown): value is Binding {
+  return (
+    isObject(value) &&
+    value.kind === "binding" &&
+    typeof value.name === "string" &&
+    "value" in value
+  );
+}
+
+export function isAction(value: unknown): value is Action {
+  if (!isObject(value) || value.kind !== "action") return false;
+  switch (value.type) {
+    case "send":
+    case "copy":
+      return typeof value.text === "string";
+    case "openUrl":
+      return typeof value.url === "string";
+    case "set":
+      return typeof value.name === "string" && "value" in value;
+    default:
+      return false;
+  }
+}
+
+export function isScalar(value: unknown): value is Scalar {
+  return (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  );
+}
+
+/** A `string` param: scalars become strings, anything else is empty. */
+export function text(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return "";
+}
+
+/** An optional `string` param: absent or null stays null. */
+export function optionalText(value: unknown): string | null {
+  return value === undefined || value === null ? null : text(value);
+}
+
+export function finiteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+export function list(value: Value | undefined): readonly Value[] {
+  return Array.isArray(value) ? value : [];
+}
+
+export function nodes(value: Value | undefined): UiNode[] {
+  return list(value).filter(isNode);
+}
+
+export type Tone = "neutral" | "good" | "warn" | "bad" | "info";
+
+/** BB's timeline accent (a muted blue in the stock themes), else the primary ink. */
+export const ACCENT = "var(--color-timeline-accent,var(--primary))";
+
+/** Text color per tone; neutral inherits. */
+export const TONE_TEXT: Record<Tone, string> = {
+  neutral: "",
+  good: "text-success",
+  warn: "text-warning-text",
+  bad: "text-destructive",
+  info: "text-[var(--color-timeline-accent,var(--primary))]",
+};
+
+/** Status-dot fill per tone. */
+export const TONE_DOT: Record<Tone, string> = {
+  neutral: "bg-muted-foreground/45",
+  good: "bg-success",
+  warn: "bg-warning",
+  bad: "bg-destructive",
+  info: "bg-[var(--color-timeline-accent,var(--primary))]",
+};
+
+/** Pill surface per tone: a faint wash of the tone, no border. */
+export const TONE_PILL: Record<Tone, string> = {
+  neutral: "bg-surface-recessed text-muted-foreground",
+  good: "bg-success/12 text-success",
+  warn: "bg-warning/14 text-warning-text",
+  bad: "bg-destructive/10 text-destructive",
+  info: "bg-[color-mix(in_oklch,var(--color-timeline-accent,var(--primary))_12%,transparent)] text-[var(--color-timeline-accent,var(--primary))]",
+};
+
+export function tone(value: Value | undefined): Tone {
+  return typeof value === "string" && Object.hasOwn(TONE_TEXT, value)
+    ? (value as Tone)
+    : "neutral";
+}
+
+const NUMBER_FORMAT = new Intl.NumberFormat("en-US", {
+  maximumFractionDigits: 2,
+});
+
+/** Locale-independent grouping, up to 2 decimals (matches `fmt`). */
+export function formatNumber(value: number): string {
+  return NUMBER_FORMAT.format(value);
+}