Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

24.2 KB
Raw Blame
/**
 * The closed list of style hooks (K-redesign §1.2, Appendices A and B).
 *
 * A hook is a class a component opts into and each theme's CSS gives meaning to. The list is
 * closed so that no theme grows a costume one class at a time: the W0 drafts had eleven hooks, and
 * five of them (a gradient wash, a column grid, a dot matrix, corner ticks, radius that eases on
 * hover, mono button labels) were decoration with no job. `src/hooks.ts` exports the six that
 * remained, the seventh added with the theme identities — `ui-shell`, the app window, the one
 * place a theme may lay a colour field (user decision, 2026-09-19) — the three structure hooks
 * that let the themes differ in organisation rather than in colour alone: `ui-icon-decor` (an icon
 * a theme may recolour or drop), `ui-tree` (rows that nest, which Console joins with connector
 * rules) and `ui-field` (a labelled control row, which Console sets as a table row) — and the
 * eleventh, `ui-activity` (a step of the agent's work: Frost sweeps a highlight across its label,
 * Console renders a transcript; user decision, 2026-09-29), the twelfth and thirteenth,
 * `ui-notice` and `ui-chart` (notices and charts that differ per theme; the same day), the
 * fourteenth, `ui-scrim` (the dimmed backdrop behind a dialog, which Frost blurs; 2026-09-30),
 * and the fifteenth, `ui-stream` (an assistant reply as it arrives: Frost's soft veil, Console's
 * block cursor; the same day). This suite holds the source to it:
 *
 * - no `ui-*` class in markup, and no `.ui-*` selector in a stylesheet, outside the list — in the
 *   package, the web app and the gallery;
 * - each hook applied only inside the components Appendix B names as its hosts: glass only on
 *   transient layers, the eyebrow only as a group label, the display face only on a page title,
 *   the shell only on an app-window frame, the tree only on a nesting list. A host is the nearest
 *   enclosing PascalCase function, so a stand-in in `screens/` or `modules/` carries the name of
 *   the component it imitates. The decorative-icon hook is applied through the icon renderers
 *   (`GlyphIcon`, `Glyph`), which write the class when a call site passes `decor`; the guard
 *   therefore reads `decor` on the call site and holds its enclosing component to the list, so
 *   the renderer being a host loosens nothing;
 * - the markup the recipes select on: `.ui-live` names its signal in `data-live`, `.ui-display`
 *   sits on an h1, `.ui-frame`'s slots are `head`, `body`, `foot` or `pane`, `.ui-shell`'s are
 *   `nav`, `main` or `dock`, `.ui-field`'s are `label`, `control` or `hint`, a tree row's
 *   `data-depth` is a digit 0–8 and its `data-last` is `"true"`, a decorative icon's
 *   `data-role` is one of the four the recipes tint apart, `.ui-activity` names its kind
 *   (`thinking` / `tool`), its state (`running` / `done` / `error`) and its slots (`label`,
 *   `detail`, `progress`), `.ui-notice` its tone (the five) and its slots (`icon`, `title`,
 *   `body`, `actions`), `.ui-stream` its state (`streaming` / `done`) and its one slot
 *   (`caret`), and a chart's parts are the seven the recipes style, wherever a `data-part` is
 *   written.
 */
import { existsSync } from "node:fs";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
import { HOOKS } from "../src/hooks";
import { analyzeFile, matchesPolicyPath, scanSourceRoots, unscannedRoots } from "../src/testing";
import type { ClassToken, FileAnalysis, JsxElementInfo, SourceFile } from "../src/testing";
import { REPO_ROOT, SRC_DIR, WEB_DIR } from "./helpers/paths";

/** Appendix A. Adding a hook is a catalog change: this list, the host table and every theme. */
const APPENDIX_A = [
  "ui-glass",
  "ui-eyebrow",
  "ui-display",
  "ui-live",
  "ui-frame",
  "ui-underline-nav",
  "ui-shell",
  "ui-icon-decor",
  "ui-tree",
  "ui-field",
  "ui-activity",
  "ui-notice",
  "ui-chart",
  "ui-scrim",
  "ui-stream",
];

/**
 * Appendix B: the components that may apply each hook — the web app's own components, which the
 * gallery frames as they are (the package itself renders none). A component is listed only while
 * it exists: the last test below fails on a host no scanned file declares.
 *
 * Glass is for the layers that float over the page (the composer card and its slash list, dialogs,
 * menus, popovers, tooltips, the floating launcher); the eyebrow and display rungs for the
 * sidebar's list label and the page titles; live marks for the spinner, a pulsing state dot, the
 * machines page's working marks and the caret of a reply still streaming in; frames for the
 * transcript's cards, the code block, the page's cards and a table that is its own box; the shell
 * for the app window; a decorative icon for the rows and headers whose label already says what the
 * icon says (a nav row's glyph in the sidebar or a rail, a group header's, a menu row's glyph, a
 * tab, an empty state) — a session row is not a host, its avatar and marks carry information; a
 * tree for a file tree and a work group's steps; a field for a settings row; activity for the
 * transcript's work in progress (the work group's header, a tool call, the thinking row).
 */
const HOSTS: Readonly<Record<string, readonly string[]>> = {
  // The composer's card and the slash list that opens over it (W6) float with the menus.
  "ui-glass": [
    "ComposerCard",
    "SlashMenu",
    "Modal",
    "Dropdown",
    "Select",
    "OptionMenu",
    "InfoPopover",
    "Tooltip",
    "TooltipLayer",
    "TooltipPanel",
    // The floating launcher (W7): its ball and caption, and the fan's entries, float over the
    // conversation with content moving underneath.
    "LauncherBall",
    "LauncherFan",
  ],
  // `Text` carries it for its eyebrow role (W7), the one door a group label takes in new code —
  // the sidebar's list label among them (W7).
  "ui-eyebrow": ["GroupHeader", "PagedDialog", "Text"],
  // The page titles are `PageHeader`'s; the draft view's hero writes its own.
  "ui-display": ["Heading", "PageHeader", "EmptyState", "DraftView"],
  "ui-live": ["Spinner", "Dot", "Stepper", "MachineCard", "ProgressBar", "StreamingCaret"],
  // The transcript's cards (the tool call, the work group, the changes card at a Task's foot) and
  // the code block, and the page-level boxes (W4): the card and a table that is its own box.
  "ui-frame": ["ToolCallCard", "WorkGroup", "ChangesCard", "CodeBlock", "Card", "Table"],
  // The page tab bar, and a dock's tab strip (W7).
  "ui-underline-nav": ["Tabs", "DockTabs"],
  // The app window (W7: the package's shell; the web's layout route renders it).
  "ui-shell": ["AppShell"],
  "ui-icon-decor": [
    "GlyphIcon",
    "NavRow",
    "SettingsDialog",
    "MenuItem",
    "GroupHeader",
    "Tabs",
    "EmptyState",
  ],
  "ui-tree": ["FileTree", "WorkGroup"],
  "ui-field": ["Field", "PrefRow", "SettingRow"],
  "ui-activity": ["WorkGroup", "ToolCallCard", "DisclosureRow"],
  // The Web App's notices (2026-09-29): the toast, and the one shared strip every inline notice
  // renders through. The charts: the plot frame (its children — the trend, requests, token-bar
  // and score charts — carry parts, not the hook), the token donut, the sparkline and the ring.
  "ui-notice": ["Toaster", "NoticeStrip"],
  // The Trace timeline draws its lanes and spans as HTML (`grid` on a lane track, `bar` on a
  // span with a 1-based `data-series`), so the chart recipes carry HTML spellings beside the
  // SVG ones.
  "ui-chart": ["ChartFrame", "TokenDonut", "Sparkline", "Ring", "TimelineChart"],
  // The dimmed backdrop (2026-09-30): a sibling behind a sheet or drawer, or the full-viewport
  // overlay a modal, the command palette, the harness overlay and the lightbox sit in.
  "ui-scrim": ["Modal", "Sheet", "Drawer", "CommandPalette", "HarnessHistoryOverlay", "Lightbox"],
  // An assistant reply as it arrives (2026-09-30): the reply body the transcript renders and the
  // gallery frames on its own.
  "ui-stream": ["AssistantText"],
};

/** CSS keywords that start with `ui-` and are not classes. */
const NOT_HOOKS = new Set(["ui-sans-serif", "ui-serif", "ui-monospace", "ui-rounded"]);

const FRAME_SLOTS = new Set(["head", "body", "foot", "pane"]);
const SHELL_SLOTS = new Set(["nav", "main", "dock"]);
const FIELD_SLOTS = new Set(["label", "control", "hint"]);
const LIVE_SIGNALS = new Set(["dot", "caret", "spinner", "bar"]);
const ICON_ROLES = new Set(["nav", "group", "menu", "empty"]);
const ACTIVITY_KINDS = new Set(["thinking", "tool"]);
const ACTIVITY_STATES = new Set(["running", "done", "error"]);
const ACTIVITY_SLOTS = new Set(["label", "detail", "progress", "mark", "toggle", "toggle-end"]);
const NOTICE_TONES = new Set(["info", "success", "warning", "danger", "neutral"]);
const NOTICE_SLOTS = new Set(["icon", "title", "body", "actions"]);
const STREAM_STATES = new Set(["streaming", "done"]);
const STREAM_SLOTS = new Set(["caret"]);
/** A chart's parts, wherever a chart's children are written (a mark component draws into the frame's svg). */
const CHART_PARTS = new Set(["grid", "axis", "series", "area", "bar", "point", "label"]);
/** The icon renderers: a `decor` prop on one of these is the decorative-icon hook applied. */
const ICON_RENDERERS = new Set(["GlyphIcon"]);
/** A tree row's depth: the eight levels the recipes spell out, and the roots. */
const TREE_DEPTH = /^[0-8]$/;

/** Not UI: the test machinery spells the patterns the checks look for, and hooks.ts is the list. */
const NOT_UI = ["testing/", "hooks.ts"];

const GALLERY_DIR = join(REPO_ROOT, "packages", "ui-gallery", "src");
const ROOTS = {
  ui: SRC_DIR,
  web: join(WEB_DIR, "src"),
  ...(existsSync(GALLERY_DIR) ? { gallery: GALLERY_DIR } : {}),
};
const SCAN = scanSourceRoots(ROOTS, { repoRoot: REPO_ROOT });
const filesOf = (root: string) =>
  SCAN.files.filter((f) => f.root === root && !(root === "ui" && matchesPolicyPath(f.rel, NOT_UI)));

/** Every `ui-*` class token in markup and every `.ui-*` class in a selector, with where it is. */
function hookNames(file: SourceFile): { name: string; line: number }[] {
  const analysis = analyzeFile(file);
  if (analysis.surface === "stylesheet") {
    return analysis.cssRules.flatMap((rule) =>
      [...[...rule.parents, rule.selector].join(" ").matchAll(/\.(ui-[a-z][\w-]*)/g)].map((m) => ({
        name: m[1]!,
        line: rule.line,
      })),
    );
  }
  return analysis.tokens
    .filter((t) => t.utility.startsWith("ui-") && !NOT_HOOKS.has(t.utility))
    .map((t) => ({ name: t.utility, line: t.line }));
}

/** The innermost component a token was written in, or null at module level. */
function componentOf(analysis: FileAnalysis, token: ClassToken): string | null {
  const owners = analysis.components.filter((c) => c.classes.includes(token));
  owners.sort((a, b) => a.classes.length - b.classes.length);
  return owners[0]?.name ?? null;
}

/** The literal `data-slot` values of an element's direct children, with the child. */
function childSlots(element: JsxElementInfo): { slot: string; child: JsxElementInfo }[] {
  return element.children.flatMap((child) => {
    if (child.kind !== "element") return [];
    const slot = child.element.attributes.get("data-slot");
    return typeof slot === "string" ? [{ slot, child: child.element }] : [];
  });
}

describe("style hooks", () => {
  const hooks = new Set<string>(HOOKS);

  it("are the fifteen of Appendix A, each with its hosts", () => {
    expect([...HOOKS].sort()).toEqual([...APPENDIX_A].sort());
    expect(Object.keys(HOSTS).sort()).toEqual([...APPENDIX_A].sort());
  });

  it("scans the package and the web app", () => {
    expect(unscannedRoots(SCAN)).toEqual([]);
  });

  for (const root of Object.keys(ROOTS)) {
    it(`are the only ui-* classes and selectors in ${root}`, () => {
      const strays = filesOf(root).flatMap((file) =>
        hookNames(file)
          .filter((found) => !hooks.has(found.name))
          .map((found) => `${file.id}:${found.line} ${found.name}`),
      );
      expect(
        strays,
        "A ui-* class outside src/hooks.ts is a hook no theme has agreed to — the deleted ones " +
          "(wash, grid, grid-dots, ticks, pill-hover, button) were decoration; use tokens instead.",
      ).toEqual([]);
    });
  }
  if (!existsSync(GALLERY_DIR)) {
    it.skip("in the gallery — PENDING: packages/ui-gallery does not exist on this branch (#764)", () => {});
  }

  // Hooks are applied in markup; a .ts module that names one (a catalog entry) is data, not a host.
  // The web app is where the hosts live now, so its markup is checked alongside the package's.
  const markup = [...filesOf("ui"), ...filesOf("web")].filter((f) => f.name.endsWith(".tsx"));

  it("find markup to check", () => {
    expect(markup.length).toBeGreaterThan(0);
  });

  it("are applied by their hosts only (Appendix B)", () => {
    const misplaced = markup.flatMap((file) => {
      const analysis = analyzeFile(file);
      const byClass = analysis.tokens
        .filter((t) => hooks.has(t.utility))
        .flatMap((t) => {
          const component = componentOf(analysis, t);
          return component !== null && HOSTS[t.utility]!.includes(component)
            ? []
            : [`${file.id}:${t.line} ${t.utility} in ${component ?? "module scope"}`];
        });
      // The icon renderers write `ui-icon-decor` for a call site that passes `decor`, so the
      // call site is where the hook is applied: its enclosing component must be a host.
      const byProp = analysis.elements
        .filter((e) => ICON_RENDERERS.has(e.tag) && e.attributes.has("decor"))
        .flatMap((e) =>
          e.component !== null && HOSTS["ui-icon-decor"]!.includes(e.component)
            ? []
            : [`${file.id}:${e.line} decor on <${e.tag}> in ${e.component ?? "module scope"}`],
        );
      return [...byClass, ...byProp];
    });
    expect(
      misplaced,
      "Each hook belongs to the components K-redesign Appendix B names (see HOSTS). A stand-in " +
        "takes the name of the component it imitates; anything else uses tokens, not the hook.",
    ).toEqual([]);
  });

  it("carry the markup their recipes select on", () => {
    const broken = markup.flatMap((file) =>
      analyzeFile(file).elements.flatMap((element) => {
        const names = new Set(element.classes.map((t) => t.utility));
        const at = `${file.id}:${element.line} <${element.tag}>`;
        const problems: string[] = [];
        const live = element.attributes.get("data-live");
        if (names.has("ui-live") && live !== null && !LIVE_SIGNALS.has(String(live))) {
          problems.push(
            `${at} .ui-live needs data-live="dot|caret|spinner|bar", has ${String(live)}`,
          );
        }
        const level = element.attributes.get("aria-level");
        if (names.has("ui-display") && element.intrinsic && element.tag !== "h1" && level !== "1") {
          problems.push(`${at} .ui-display belongs on an h1`);
        }
        if (names.has("ui-frame")) {
          for (const { slot } of childSlots(element)) {
            if (!FRAME_SLOTS.has(slot)) {
              problems.push(`${at} .ui-frame slot "${slot}" is not head, body, foot or pane`);
            }
          }
        }
        if (names.has("ui-shell")) {
          for (const { slot } of childSlots(element)) {
            if (!SHELL_SLOTS.has(slot)) {
              problems.push(`${at} .ui-shell slot "${slot}" is not nav, main or dock`);
            }
          }
        }
        if (names.has("ui-field")) {
          for (const { slot } of childSlots(element)) {
            if (!FIELD_SLOTS.has(slot)) {
              problems.push(`${at} .ui-field slot "${slot}" is not label, control or hint`);
            }
          }
        }
        const role = element.attributes.get("data-role");
        if (names.has("ui-icon-decor") && typeof role === "string" && !ICON_ROLES.has(role)) {
          problems.push(`${at} .ui-icon-decor data-role="${role}" is not nav|group|menu|empty`);
        }
        // An activity row names its kind and its state as literals the recipes select on; a
        // slot is a literal too, and only the three the recipes style (the slots are found
        // anywhere inside the row, so every literal `data-slot` under it is checked by name).
        if (names.has("ui-activity")) {
          const kind = element.attributes.get("data-kind");
          if (kind !== null && (typeof kind !== "string" || !ACTIVITY_KINDS.has(kind))) {
            problems.push(
              `${at} .ui-activity needs data-kind="thinking|tool", has ${String(kind)}`,
            );
          }
          const state = element.attributes.get("data-state");
          if (state !== null && (typeof state !== "string" || !ACTIVITY_STATES.has(state))) {
            problems.push(
              `${at} .ui-activity needs data-state="running|done|error", has ${String(state)}`,
            );
          }
          for (const { slot } of childSlots(element)) {
            if (!ACTIVITY_SLOTS.has(slot)) {
              problems.push(
                `${at} .ui-activity slot "${slot}" is not label, detail, progress, mark, toggle or toggle-end`,
              );
            }
          }
        }
        // A notice names its tone as a literal the recipes select on, and its slots are the four.
        if (names.has("ui-notice")) {
          const tone = element.attributes.get("data-tone");
          if (tone !== null && (typeof tone !== "string" || !NOTICE_TONES.has(tone))) {
            problems.push(
              `${at} .ui-notice needs data-tone="info|success|warning|danger|neutral", has ${String(tone)}`,
            );
          }
          for (const { slot } of childSlots(element)) {
            if (!NOTICE_SLOTS.has(slot)) {
              problems.push(`${at} .ui-notice slot "${slot}" is not icon, title, body or actions`);
            }
          }
        }
        // A streaming reply names its state, as a literal the recipes select on or an
        // expression; its one direct-child slot is the stream's edge, the caret (Frost's veil
        // stops there, Console's cursor is drawn on it).
        if (names.has("ui-stream")) {
          const state = element.attributes.get("data-state");
          if (state !== null && (typeof state !== "string" || !STREAM_STATES.has(state))) {
            problems.push(
              `${at} .ui-stream needs data-state="streaming|done", has ${String(state)}`,
            );
          }
          for (const { slot } of childSlots(element)) {
            if (!STREAM_SLOTS.has(slot)) {
              problems.push(`${at} .ui-stream slot "${slot}" is not caret`);
            }
          }
        }
        // A chart's parts are written wherever a mark is drawn, inside the frame's svg or by a
        // component that renders into it: every literal `data-part` is one the recipes style.
        const part = element.attributes.get("data-part");
        if (typeof part === "string" && !CHART_PARTS.has(part)) {
          problems.push(`${at} data-part="${part}" is not grid|axis|series|area|bar|point|label`);
        }
        // Tree rows are written by the host, wherever it renders them: every literal depth and
        // last mark in the package must be what the recipes select on.
        const depth = element.attributes.get("data-depth");
        if (typeof depth === "string" && !TREE_DEPTH.test(depth)) {
          problems.push(`${at} data-depth="${depth}" is not a level from 0 to 8`);
        }
        const last = element.attributes.get("data-last");
        if (typeof last === "string" && last !== "true") {
          problems.push(`${at} data-last="${last}" — the last row of a level carries "true"`);
        }
        const branch = element.attributes.get("data-branch");
        if (branch !== undefined && branch !== true && branch !== null && branch !== "true") {
          problems.push(`${at} data-branch="${String(branch)}" — a branch carries the bare flag`);
        }
        if (branch !== undefined && depth === undefined) {
          problems.push(`${at} a branch carries the data-depth of the rows it holds`);
        }
        return problems;
      }),
    );
    expect(broken).toEqual([]);
  });

  it("name only hosts that exist", () => {
    const declared = new Set(
      markup.flatMap((file) => analyzeFile(file).components.map((c) => c.name)),
    );
    const missing = Object.entries(HOSTS).flatMap(([hook, hosts]) =>
      hosts.filter((host) => !declared.has(host)).map((host) => `${hook}: ${host}`),
    );
    expect(missing, "A host no scanned file declares is a stale entry: remove it.").toEqual([]);
  });
});

describe("the hook checks, on known shapes", () => {
  const file = (rel: string, text: string): SourceFile => ({
    root: "ui",
    rel,
    id: `packages/ui/src/${rel}`,
    path: `/virtual/${rel}`,
    name: rel.slice(rel.lastIndexOf("/") + 1),
    text,
  });

  it("find hook classes in markup and selectors, and nothing that only looks like one", () => {
    expect(
      hookNames(
        file(
          "a.tsx",
          [
            'const A = () => <div className="ui-wash flex" />;',
            'const font = "ui-monospace, SFMono-Regular";',
            "// a comment naming ui-ticks is not a class",
          ].join("\n"),
        ),
      ).map((f) => f.name),
    ).toEqual(["ui-wash"]);
    expect(
      hookNames(
        file("t.css", "@layer ui-theme {\n  :root .ui-grid.ui-grid-dots { --ui-canvas: #000; }\n}"),
      ).map((f) => f.name),
    ).toEqual(["ui-grid", "ui-grid-dots"]);
  });

  it("name the innermost component a hook is written in", () => {
    const analysis = analyzeFile(
      file(
        "b.tsx",
        [
          "export function Composer() {",
          '  const Card = () => <div className="ui-glass" />;',
          '  return <span className="ui-live" data-live="caret" />;',
          "}",
          'const LOOSE = "ui-frame";',
        ].join("\n"),
      ),
    );
    const named = (hook: string) =>
      componentOf(
        analysis,
        analysis.tokens.find((t) => t.utility === hook)!,
      );
    expect(named("ui-glass")).toBe("Card");
    expect(named("ui-live")).toBe("Composer");
    expect(named("ui-frame")).toBeNull();
  });

  it("read a tree's rows and a field's slots as the recipes do", () => {
    const analysis = analyzeFile(
      file(
        "c.tsx",
        [
          "export function TreePane() {",
          "  return (",
          '    <ul className="ui-tree">',
          '      <li data-depth="0">root</li>',
          '      <div data-branch data-depth="1">',
          '        <li data-depth="1" data-last="true">leaf</li>',
          "      </div>",
          "    </ul>",
          "  );",
          "}",
          "export function Field() {",
          "  return (",
          '    <div className="ui-field">',
          '      <span data-slot="label">Name</span>',
          '      <div data-slot="control" />',
          "    </div>",
          "  );",
          "}",
        ].join("\n"),
      ),
    );
    const tree = analysis.elements.find((e) => e.classes.some((t) => t.utility === "ui-tree"))!;
    expect(childSlots(tree)).toEqual([]);
    const rows = analysis.elements.filter((e) => e.attributes.has("data-depth"));
    const marks = rows.map((e) => [e.attributes.get("data-depth"), e.attributes.get("data-last")]);
    expect(marks).toEqual([
      ["0", undefined],
      ["1", undefined],
      ["1", "true"],
    ]);
    expect(rows[1]!.attributes.get("data-branch")).toBe(true);
    const field = analysis.elements.find((e) => e.classes.some((t) => t.utility === "ui-field"))!;
    expect(childSlots(field).map((s) => s.slot)).toEqual(["label", "control"]);
  });

  it("read a stream's state and its caret as the recipes do", () => {
    // The state is usually an expression (the check accepts it and judges only a literal); the
    // caret is a direct child even when it is rendered conditionally.
    const analysis = analyzeFile(
      file(
        "d.tsx",
        [
          "export function AssistantText({ revealing }: { revealing: boolean }) {",
          "  return (",
          '    <div className="ui-stream" data-state={revealing ? "streaming" : "done"}>',
          "      <p>text</p>",
          '      {revealing && <span data-slot="caret" aria-hidden />}',
          "    </div>",
          "  );",
          "}",
        ].join("\n"),
      ),
    );
    const host = analysis.elements.find((e) => e.classes.some((t) => t.utility === "ui-stream"))!;
    expect(host.attributes.get("data-state")).toBeNull();
    expect(childSlots(host).map((s) => s.slot)).toEqual(["caret"]);
  });
});