@elabs-ai/components-editor 4.0.0

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@elabs-ai/components-editor",
+  "version": "4.0.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mreimitz/elabs-components.git",
+    "directory": "packages/editor"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": [
+    "./src/lib/monaco-environment.ts",
+    "./dist/lib/monaco-environment.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./markdown": {
+      "types": "./dist/markdown/index.d.ts",
+      "default": "./dist/markdown/index.js"
+    },
+    "./markdown/frontmatter": {
+      "types": "./dist/markdown/frontmatter.d.ts",
+      "default": "./dist/markdown/frontmatter.js"
+    },
+    "./markdown/parse": {
+      "types": "./dist/markdown/parse.d.ts",
+      "default": "./dist/markdown/parse.js"
+    },
+    "./monaco-environment": {
+      "types": "./dist/lib/monaco-environment.d.ts",
+      "default": "./dist/lib/monaco-environment.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@milkdown/kit": "^7.21.2",
+    "@prosemirror-adapter/react": "^0.5.0",
+    "@streamdown/code": "^1.1.0",
+    "class-variance-authority": "^0.7.1",
+    "js-yaml": "^4.1.0",
+    "katex": "^0.16.11",
+    "lucide-react": "^0.577.0",
+    "mermaid": "^11.15.0",
+    "remark-directive": "^4.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "shiki": "^3.22.0",
+    "streamdown": "^2.4.0",
+    "unified": "^11.0.0",
+    "unist-util-visit": "^5.0.0"
+  },
+  "peerDependencies": {
+    "monaco-editor": "^0.55.1",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0",
+    "@elabs-ai/components-tokens": "4.0.0",
+    "@elabs-ai/components-ui": "4.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/js-yaml": "^4.0.9",
+    "@types/mdast": "^4.0.4",
+    "@types/react": "^19.0.2",
+    "@types/react-dom": "^19.0.2",
+    "@vitejs/plugin-react": "^4.3.4",
+    "eslint": "^9.17.0",
+    "jsdom": "^25.0.1",
+    "monaco-editor": "^0.55.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.2",
+    "@elabs-ai/components-typescript-config": "0.1.0",
+    "@elabs-ai/components-tokens": "4.0.0",
+    "@elabs-ai/components-ui": "4.0.0",
+    "@elabs-ai/components-eslint-config": "0.1.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsup && node ../../scripts/link-dist-css.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist .turbo coverage"
+  }
+}

package/src/ai-objects/ai-objects-integration.test.tsx

@@ -0,0 +1,128 @@
+/**
+ * Integration tests: ai-object directives wired into MarkdownPreview via
+ * `extensions.directives`. Verifies the full parse → render pipeline for all
+ * three directive types without forking the engine.
+ */
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { MarkdownPreview } from "../markdown-preview/markdown-preview";
+import { aiObjectDirectives } from "./directives";
+import type { KnowledgeSourceResolver } from "./knowledge-card";
+
+afterEach(cleanup);
+
+const resolve: KnowledgeSourceResolver = (path) => {
+  if (path === "notes/a.md") return { href: "/notes/a", title: "Note A" };
+  return null;
+};
+
+const extensions = { directives: aiObjectDirectives({ resolveKnowledge: resolve }) };
+
+describe("MarkdownPreview + aiObjectDirectives — :::decision", () => {
+  it("renders the status badge and rationale body", async () => {
+    render(
+      <MarkdownPreview extensions={extensions}>
+        {`:::decision{status=accepted date=2026-06-15}\nWe chose PostgreSQL.\n:::`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() => expect(screen.getByText("Accepted")).toBeInTheDocument());
+    expect(screen.getByText("We chose PostgreSQL.")).toBeInTheDocument();
+    expect(screen.getByText("2026-06-15")).toBeInTheDocument();
+  });
+
+  it("renders alternatives from the attribute", async () => {
+    render(
+      <MarkdownPreview extensions={extensions}>
+        {`:::decision{status=accepted alternatives="Redis, SQLite"}\nBody.\n:::`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() => expect(screen.getByText("Accepted")).toBeInTheDocument());
+    expect(screen.getByText("Redis")).toBeInTheDocument();
+    expect(screen.getByText("SQLite")).toBeInTheDocument();
+  });
+
+  it("degrades an unknown status to 'proposed' without errors", async () => {
+    render(
+      <MarkdownPreview extensions={extensions}>
+        {`:::decision{status=unknown}\nBody.\n:::`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() => expect(screen.getByText("Proposed")).toBeInTheDocument());
+    expect(screen.queryByText(/Unknown block/)).toBeNull();
+  });
+});
+
+describe("MarkdownPreview + aiObjectDirectives — :::entity (block)", () => {
+  it("renders the entity name and kind label", async () => {
+    render(
+      <MarkdownPreview extensions={extensions}>
+        {`:::entity{kind=org name="Acme Corp"}\nPrimary vendor.\n:::`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() => expect(screen.getByText("Acme Corp")).toBeInTheDocument());
+    expect(screen.getByText("Organisation")).toBeInTheDocument();
+    expect(screen.getByText("Primary vendor.")).toBeInTheDocument();
+  });
+});
+
+describe("MarkdownPreview + aiObjectDirectives — :entity[…] (inline chip)", () => {
+  it("renders the chip inside the paragraph text flow", async () => {
+    render(
+      <MarkdownPreview extensions={extensions}>
+        {`Owner :entity[Acme]{kind=org} ships it.`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() => expect(screen.getByText("Acme")).toBeInTheDocument());
+    // The chip must live inside a <p> — no block wrapper around it.
+    const chip = screen.getByRole("mark", { name: /Acme \(Organisation\)/i });
+    expect(chip).toBeInTheDocument();
+    expect(chip.closest("p")).not.toBeNull();
+  });
+
+  it("renders an inline chip for an unknown kind without errors", async () => {
+    render(
+      <MarkdownPreview extensions={extensions}>
+        {`See :entity[Widget]{kind=thing} for details.`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() => expect(screen.getByText("Widget")).toBeInTheDocument());
+    expect(screen.queryByText(/Unknown block/)).toBeNull();
+  });
+});
+
+describe("MarkdownPreview + aiObjectDirectives — :::knowledge", () => {
+  it("renders the fact body and a resolved source link", async () => {
+    render(
+      <MarkdownPreview extensions={extensions}>
+        {`:::knowledge{sources="notes/a.md"}\nPostgreSQL reduced latency by 38%.\n:::`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() =>
+      expect(screen.getByText("PostgreSQL reduced latency by 38%.")).toBeInTheDocument(),
+    );
+    expect(screen.getByRole("link", { name: /Source: Note A/i })).toBeInTheDocument();
+  });
+
+  it("degrades an unresolved source to a plain label (no broken link)", async () => {
+    render(
+      <MarkdownPreview extensions={extensions}>
+        {`:::knowledge{sources="notes/missing.md"}\nfact\n:::`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() => expect(screen.getByText("fact")).toBeInTheDocument());
+    expect(screen.queryByRole("link")).toBeNull();
+    expect(screen.getByText("notes/missing.md")).toBeInTheDocument();
+  });
+
+  it("renders mixed resolved/unresolved sources without errors", async () => {
+    render(
+      <MarkdownPreview extensions={extensions}>
+        {`:::knowledge{sources="notes/a.md, notes/missing.md"}\nfact\n:::`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() => expect(screen.getByText("fact")).toBeInTheDocument());
+    expect(screen.getByRole("link", { name: /Note A/i })).toBeInTheDocument();
+    expect(screen.getByText("notes/missing.md")).toBeInTheDocument();
+  });
+});

package/src/ai-objects/ai-objects.stories.tsx

@@ -0,0 +1,233 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { DecisionCard } from "./decision-card";
+import { EntityCard, EntityChip } from "./entity";
+import { KnowledgeCard, type KnowledgeSourceResolver } from "./knowledge-card";
+
+/* ------------------------------------------------------------------ */
+/* DecisionCard                                                         */
+/* ------------------------------------------------------------------ */
+
+const decisionMeta = {
+  title: "Editor/AiObjects/DecisionCard",
+  component: DecisionCard,
+  tags: ["autodocs"],
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof DecisionCard>;
+
+export default decisionMeta;
+type DecisionStory = StoryObj<typeof decisionMeta>;
+
+export const Accepted: DecisionStory = {
+  args: {
+    status: "accepted",
+    date: "2026-06-15",
+    alternatives: "Redis cache, in-memory map, SQLite",
+    children: (
+      <p>
+        PostgreSQL was chosen because it already runs in production, supports JSONB for flexible
+        schemas, and the team has operational expertise with it. Introducing a second data store for
+        caching would add operational burden that outweighs the latency gain at current scale.
+      </p>
+    ),
+  },
+};
+
+export const Proposed: DecisionStory = {
+  args: {
+    status: "proposed",
+    date: "2026-07-01",
+    children: <p>Migrate the report pipeline to streaming to reduce time-to-first-byte by ~40%.</p>,
+  },
+};
+
+export const Rejected: DecisionStory = {
+  args: {
+    status: "rejected",
+    date: "2026-05-10",
+    alternatives: "Micro-frontend shell, Module federation",
+    children: <p>Full micro-frontend split was rejected due to excessive coordination overhead.</p>,
+  },
+};
+
+export const Superseded: DecisionStory = {
+  args: {
+    status: "superseded",
+    date: "2025-11-01",
+    children: (
+      <p>
+        Original caching strategy (Redis) was superseded by the PostgreSQL materialized-view
+        approach in ADR-0014.
+      </p>
+    ),
+  },
+};
+
+/** No rationale body — header-only layout. */
+export const NoBody: DecisionStory = {
+  args: {
+    status: "accepted",
+    date: "2026-06-01",
+  },
+};
+
+/** Unrecognised status degrades to "proposed". */
+export const UnknownStatus: DecisionStory = {
+  args: {
+    status: "in-review",
+    date: "2026-06-15",
+    children: <p>Unknown status values fall back to the "proposed" state.</p>,
+  },
+};
+
+/** Long alternatives list — chips wrap. */
+export const ManyAlternatives: DecisionStory = {
+  args: {
+    status: "accepted",
+    date: "2026-06-15",
+    alternatives: "Option A, Option B, Option C, Option D, Option E, Option F, Option G, Option H",
+    children: <p>Chose the simplest path that could possibly work.</p>,
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* EntityChip (inline)                                                  */
+/* ------------------------------------------------------------------ */
+
+export const EntityChipDefault: StoryObj = {
+  name: "EntityChip / Default",
+  render: () => (
+    <p className="max-w-prose text-body text-foreground">
+      The contract was signed between <EntityChip kind="org">Acme Corp</EntityChip> and{" "}
+      <EntityChip kind="person">Jane Smith</EntityChip> at the{" "}
+      <EntityChip kind="place">London office</EntityChip>. The{" "}
+      <EntityChip kind="product">DataBridge SDK</EntityChip> was the primary deliverable, and the{" "}
+      <EntityChip kind="concept">data sovereignty</EntityChip> requirement shaped every clause.
+    </p>
+  ),
+  parameters: { layout: "padded" },
+};
+
+export const EntityChipKinds: StoryObj = {
+  name: "EntityChip / All kinds",
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      <EntityChip kind="org">Acme Corp</EntityChip>
+      <EntityChip kind="person">Jane Smith</EntityChip>
+      <EntityChip kind="place">London</EntityChip>
+      <EntityChip kind="product">DataBridge</EntityChip>
+      <EntityChip kind="concept">Data Sovereignty</EntityChip>
+      <EntityChip>Unknown kind</EntityChip>
+    </div>
+  ),
+  parameters: { layout: "padded" },
+};
+
+/* ------------------------------------------------------------------ */
+/* EntityCard (block)                                                   */
+/* ------------------------------------------------------------------ */
+
+export const EntityCardOrg: StoryObj = {
+  name: "EntityCard / Organisation",
+  render: () => (
+    <EntityCard kind="org" name="Acme Corp">
+      <p>
+        Acme Corp is the primary vendor for the data integration layer. Founded 2014, HQ Berlin.
+      </p>
+    </EntityCard>
+  ),
+  parameters: { layout: "padded" },
+};
+
+export const EntityCardPerson: StoryObj = {
+  name: "EntityCard / Person",
+  render: () => (
+    <EntityCard kind="person" name="Jane Smith">
+      <p>Jane Smith is the lead architect on the platform migration project.</p>
+    </EntityCard>
+  ),
+  parameters: { layout: "padded" },
+};
+
+export const EntityCardNoBody: StoryObj = {
+  name: "EntityCard / No body",
+  render: () => <EntityCard kind="product" name="DataBridge SDK" />,
+  parameters: { layout: "padded" },
+};
+
+/* ------------------------------------------------------------------ */
+/* KnowledgeCard                                                        */
+/* ------------------------------------------------------------------ */
+
+const resolve: KnowledgeSourceResolver = (path) => {
+  const map: Record<string, { href: string; title: string }> = {
+    "notes/adr-0012.md": { href: "#adr-0012", title: "ADR-0012: Caching strategy" },
+    "notes/perf-report.md": { href: "#perf-report", title: "Q1 Performance Report" },
+  };
+  return map[path] ?? null;
+};
+
+export const KnowledgeCardResolved: StoryObj = {
+  name: "KnowledgeCard / Resolved sources",
+  render: () => (
+    <KnowledgeCard sources="notes/adr-0012.md, notes/perf-report.md" resolve={resolve}>
+      <p>
+        The PostgreSQL materialized-view approach reduces p95 query latency by 38% compared to the
+        Redis cache measured in Q1 2026.
+      </p>
+    </KnowledgeCard>
+  ),
+  parameters: { layout: "padded" },
+};
+
+export const KnowledgeCardPartialResolve: StoryObj = {
+  name: "KnowledgeCard / Partial resolve (one stale link)",
+  render: () => (
+    <KnowledgeCard
+      sources="notes/adr-0012.md, notes/deleted-note.md, notes/perf-report.md"
+      resolve={resolve}
+    >
+      <p>
+        Stale links degrade to plain labels — the card never shows a broken anchor or throws an
+        error.
+      </p>
+    </KnowledgeCard>
+  ),
+  parameters: { layout: "padded" },
+};
+
+export const KnowledgeCardNoResolve: StoryObj = {
+  name: "KnowledgeCard / No resolver (all labels)",
+  render: () => (
+    <KnowledgeCard sources="notes/a.md, notes/b.md">
+      <p>Without a resolver every source path renders as a plain label.</p>
+    </KnowledgeCard>
+  ),
+  parameters: { layout: "padded" },
+};
+
+export const KnowledgeCardNoSources: StoryObj = {
+  name: "KnowledgeCard / No sources",
+  render: () => (
+    <KnowledgeCard>
+      <p>A knowledge card with no sources attribute — the footer is omitted entirely.</p>
+    </KnowledgeCard>
+  ),
+  parameters: { layout: "padded" },
+};
+
+export const KnowledgeCardLongFact: StoryObj = {
+  name: "KnowledgeCard / Long fact body",
+  render: () => (
+    <KnowledgeCard sources="notes/adr-0012.md" resolve={resolve}>
+      <p>
+        The decision to adopt PostgreSQL materialized views was driven by three factors: the
+        operational simplicity of a single data store, the 38% latency reduction observed in Q1
+        benchmarks, and the team&rsquo;s existing expertise with PostgreSQL query planning. The
+        Redis alternative was estimated to add 1.5 FTE of operational overhead annually, which the
+        engineering leadership deemed unacceptable given current headcount constraints.
+      </p>
+    </KnowledgeCard>
+  ),
+  parameters: { layout: "padded" },
+};

package/src/ai-objects/ai-objects.test.tsx

@@ -0,0 +1,205 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { DecisionCard } from "./decision-card";
+import { EntityCard, EntityChip } from "./entity";
+import { KnowledgeCard, type KnowledgeSourceResolver } from "./knowledge-card";
+
+/* ------------------------------------------------------------------ */
+/* DecisionCard                                                         */
+/* ------------------------------------------------------------------ */
+
+describe("DecisionCard", () => {
+  it("renders the status badge and date", () => {
+    render(
+      <DecisionCard status="accepted" date="2026-06-15">
+        <p>We chose PostgreSQL.</p>
+      </DecisionCard>,
+    );
+    expect(screen.getByText("Accepted")).toBeInTheDocument();
+    expect(screen.getByText("2026-06-15")).toBeInTheDocument();
+  });
+
+  it("renders the rationale body (children)", () => {
+    render(
+      <DecisionCard status="accepted">
+        <p>We chose PostgreSQL.</p>
+      </DecisionCard>,
+    );
+    expect(screen.getByText("We chose PostgreSQL.")).toBeInTheDocument();
+  });
+
+  it("renders the alternatives section from the comma-separated attribute", () => {
+    render(
+      <DecisionCard status="accepted" alternatives="Redis, SQLite, DynamoDB">
+        <p>body</p>
+      </DecisionCard>,
+    );
+    expect(screen.getByText("Redis")).toBeInTheDocument();
+    expect(screen.getByText("SQLite")).toBeInTheDocument();
+    expect(screen.getByText("DynamoDB")).toBeInTheDocument();
+  });
+
+  it("omits the alternatives section when not provided", () => {
+    render(<DecisionCard status="accepted">body</DecisionCard>);
+    expect(screen.queryByText("Alternatives considered")).toBeNull();
+  });
+
+  it("degrades an unrecognised status to 'proposed'", () => {
+    render(<DecisionCard status="in-review">body</DecisionCard>);
+    expect(screen.getByText("Proposed")).toBeInTheDocument();
+  });
+
+  it("has an accessible section label derived from the status", () => {
+    render(<DecisionCard status="rejected">body</DecisionCard>);
+    expect(screen.getByRole("region", { name: /Decision: Rejected/i })).toBeInTheDocument();
+  });
+
+  it("renders without children (header-only layout)", () => {
+    render(<DecisionCard status="accepted" date="2026-06-01" />);
+    expect(screen.getByText("Accepted")).toBeInTheDocument();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* EntityChip                                                           */
+/* ------------------------------------------------------------------ */
+
+describe("EntityChip", () => {
+  it("renders the label text", () => {
+    render(<EntityChip kind="org">Acme Corp</EntityChip>);
+    expect(screen.getByText("Acme Corp")).toBeInTheDocument();
+  });
+
+  it("carries an aria-label that names the entity and its kind", () => {
+    render(<EntityChip kind="org">Acme Corp</EntityChip>);
+    expect(screen.getByRole("mark", { name: /Acme Corp \(Organisation\)/i })).toBeInTheDocument();
+  });
+
+  it("is a <span> (inline element — valid inside <p>)", () => {
+    const { container } = render(
+      <p>
+        Text <EntityChip kind="person">Jane</EntityChip> here
+      </p>,
+    );
+    const chip = container.querySelector("span[role='mark']");
+    expect(chip).not.toBeNull();
+    expect(chip?.closest("p")).not.toBeNull();
+  });
+
+  it("renders all five known kinds without errors", () => {
+    const kinds = ["org", "person", "place", "product", "concept"] as const;
+    for (const kind of kinds) {
+      render(<EntityChip kind={kind}>{kind}</EntityChip>);
+      expect(screen.getAllByText(kind).length).toBeGreaterThan(0);
+    }
+  });
+
+  it("gracefully renders an unknown kind without throwing", () => {
+    render(<EntityChip kind="unknown-kind">X</EntityChip>);
+    expect(screen.getByText("X")).toBeInTheDocument();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* EntityCard                                                           */
+/* ------------------------------------------------------------------ */
+
+describe("EntityCard", () => {
+  it("renders the entity name and kind label", () => {
+    render(<EntityCard kind="org" name="Acme Corp" />);
+    expect(screen.getByText("Acme Corp")).toBeInTheDocument();
+    expect(screen.getByText("Organisation")).toBeInTheDocument();
+  });
+
+  it("renders the description body", () => {
+    render(
+      <EntityCard kind="person" name="Jane">
+        <p>Lead architect.</p>
+      </EntityCard>,
+    );
+    expect(screen.getByText("Lead architect.")).toBeInTheDocument();
+  });
+
+  it("has an accessible section label naming kind and entity", () => {
+    render(<EntityCard kind="org" name="Acme Corp" />);
+    expect(screen.getByRole("region", { name: /Organisation: Acme Corp/i })).toBeInTheDocument();
+  });
+
+  it("renders without a name (kind-only card)", () => {
+    render(<EntityCard kind="concept" />);
+    expect(screen.getByText("Concept")).toBeInTheDocument();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* KnowledgeCard                                                        */
+/* ------------------------------------------------------------------ */
+
+describe("KnowledgeCard", () => {
+  const resolve: KnowledgeSourceResolver = (path) => {
+    if (path === "notes/a.md") return { href: "/notes/a", title: "Note A" };
+    return null;
+  };
+
+  it("renders the fact body", () => {
+    render(
+      <KnowledgeCard>
+        <p>PostgreSQL reduced p95 latency by 38%.</p>
+      </KnowledgeCard>,
+    );
+    expect(screen.getByText("PostgreSQL reduced p95 latency by 38%.")).toBeInTheDocument();
+  });
+
+  it("renders a resolved source as a link with its title", () => {
+    render(
+      <KnowledgeCard sources="notes/a.md" resolve={resolve}>
+        <p>fact</p>
+      </KnowledgeCard>,
+    );
+    const link = screen.getByRole("link", { name: /Source: Note A/i });
+    expect(link).toBeInTheDocument();
+    expect(link).toHaveAttribute("href", "/notes/a");
+  });
+
+  it("renders an unresolved source as a plain label (no link)", () => {
+    render(
+      <KnowledgeCard sources="notes/missing.md" resolve={resolve}>
+        <p>fact</p>
+      </KnowledgeCard>,
+    );
+    expect(screen.queryByRole("link")).toBeNull();
+    expect(screen.getByText("notes/missing.md")).toBeInTheDocument();
+  });
+
+  it("renders mixed resolved/unresolved sources without errors", () => {
+    render(
+      <KnowledgeCard sources="notes/a.md, notes/missing.md" resolve={resolve}>
+        <p>fact</p>
+      </KnowledgeCard>,
+    );
+    expect(screen.getByRole("link", { name: /Note A/i })).toBeInTheDocument();
+    expect(screen.getByText("notes/missing.md")).toBeInTheDocument();
+  });
+
+  it("omits the sources section when no sources attribute is provided", () => {
+    render(<KnowledgeCard>fact</KnowledgeCard>);
+    expect(screen.queryByText("Sources")).toBeNull();
+  });
+
+  it("works without a resolver (all sources as plain labels)", () => {
+    render(
+      <KnowledgeCard sources="notes/a.md, notes/b.md">
+        <p>fact</p>
+      </KnowledgeCard>,
+    );
+    expect(screen.queryByRole("link")).toBeNull();
+    expect(screen.getByText("notes/a.md")).toBeInTheDocument();
+    expect(screen.getByText("notes/b.md")).toBeInTheDocument();
+  });
+
+  it("has an accessible section label", () => {
+    render(<KnowledgeCard>fact</KnowledgeCard>);
+    expect(screen.getByRole("region", { name: /Knowledge fact/i })).toBeInTheDocument();
+  });
+});