@principal-ai/subsystems-react 0.51.2 → 0.51.3

package/src/subsystem/c4.ts

@@ -7,9 +7,10 @@
  * reading `process` strings will produce it — `process` answers "where does
  * this run", which is a different question.
  *
- * So the element list is authored. An agent proposes it, a person confirms it,
- * and `buildC4Model` does the only mechanical job left: draw the boxes the
- * author named, and use the trails to draw the lines between them.
+ * So the element list is authored, and so is the `C4Model` projected from it.
+ * There is no builder here: how edges are determined is still open, so a caller
+ * supplies the drawable model directly rather than having trails converted into
+ * lines.
  *
  * ## Why a union and not one type with two axes
  *
@@ -31,7 +32,7 @@
  * [C4 notation]: https://c4model.com/diagrams/notation
  */
 
-import type { SubsystemComponent, SubsystemModelDocument } from './model';
+import type { SubsystemComponent } from './model';
 
 /**
  * Has anyone signed off on this element yet?
@@ -55,12 +56,9 @@ interface C4ElementBase {
    * The component aliases that live directly inside this element.
    *
    * Named explicitly rather than derived from a `process` value, because two
-   * runs of code being one container is a judgement, not a lookup. This is also
-   * the dedup mechanism: two elements that should be one simply end up as one
-   * element holding both member sets.
+   * runs of code being one container is a judgement, not a lookup.
    *
-   * Each alias belongs to exactly one element. A container does *not* repeat
-   * the aliases its components already claim — `buildC4Model` rolls those up.
+   * Each alias belongs to exactly one element.
    */
   members: string[];
   /**
@@ -185,18 +183,29 @@ export interface C4Group {
   memberIds: string[];
 }
 
-/** A line between two elements, rolled up from a trail step. */
+/**
+ * A line between two elements. Authored, like the boxes.
+ *
+ * C4 asks a container-diagram line to say the *technology/protocol* of the
+ * interaction (`protocol`), and the label is that plus the trail verbs where
+ * known. `label` is what the chip shows; `protocol` and `mechanisms` are kept
+ * separate so a caller can render either.
+ */
 export interface C4Edge {
   id: string;
   source: string;
   target: string;
+  /** Text the edge chip shows, e.g. `RPC` or `calls (HTTP)`. */
   label: string;
+  /** The interaction's technology/protocol, e.g. `RPC`, `HTTP`, `stdin`. */
+  protocol?: string;
+  /** Trail verbs that produced this line (`calls`, `writes`, …). */
   mechanisms: string[];
-  /** Trail steps that produced this line. */
+  /** How many underlying steps this line rolled up. */
   count: number;
 }
 
-/** A drawable C4 projection. */
+/** A drawable C4 projection. Authored, not derived. */
 export interface C4Model {
   view: C4View;
   system: { id: string; label: string; repoKey?: string };
@@ -205,355 +214,12 @@ export interface C4Model {
   edges: C4Edge[];
 }
 
-/** Something an author should fix before this set is trusted. */
-export type C4ProblemKind =
-  /** a member is claimed by two elements */
-  | 'conflicting_member'
-  /** a member is not in the supplied document */
-  | 'unknown_member'
-  /** two elements share an id */
-  | 'duplicate_id'
-  /** an element that should have contents has none */
-  | 'empty_element'
-  /** a component names a container that is missing, or is not a container */
-  | 'unknown_container';
-
-export interface C4Problem {
-  kind: C4ProblemKind;
-  message: string;
-  /** Alias for member problems, element id for the rest. */
-  subject: string;
-}
-
-export interface C4BuildResult {
-  model: C4Model;
-  /** Authoring mistakes. An empty array means the set is self-consistent. */
-  problems: C4Problem[];
-  /** Component aliases in the document that no element claims. */
-  unmapped: string[];
-}
-
-export interface C4BuildOptions {
-  /** The elements. The source of truth — nothing is invented. */
-  elements: readonly C4Element[];
-  /** Supply to resolve members and draw lines from trails. */
-  document?: SubsystemModelDocument;
-  view?: C4View;
-  /** Name of the system the elements sit in. */
-  systemLabel?: string;
-  /** Override the repo key (defaults to the first member's purl). */
-  repoKey?: string;
-  /** Model-id attribution per component alias. */
-  modelsByAlias?: Record<string, string[]>;
-}
-
 /**
- * Element kinds drawn inside the system boundary.
- *
- * A C4 container diagram puts external systems *inside* the boundary: they are
- * things this system depends on, drawn as containers we do not own. People go
- * outside it, because a person is never part of any system.
+ * `owner/name` from a purl, trimmed of scheme and fragment. Used to label the
+ * system frame when a repo key is known.
  */
-const IN_BOUNDARY = new Set<C4Element['kind']>(['container', 'external-system']);
-
-/** True when this element kind is drawn inside the system frame. */
-export function isInBoundary(e: C4Element): boolean {
-  return IN_BOUNDARY.has(e.kind);
-}
-
-function purlRepoKey(purl: string | undefined): string | undefined {
-  const p = (purl ?? '').split('#')[0]?.trim();
-  if (!p || p === 'external' || p.startsWith('external:')) return undefined;
-  return p;
-}
-
-/** `owner/name` from a purl, trimmed of scheme and fragment. */
 export function labelFromPurl(purl: string): string {
   const base = purl.replace(/^external:/, '').split('#')[0]?.trim() ?? '';
   const parts = base.split('/').filter(Boolean);
   return parts.slice(-2).join('/') || base || purl;
 }
-
-/**
- * Build the drawable projection from authored elements.
- *
- * A plain join with no architectural judgement:
- *
- *   boxes  ← one per element, named and placed by the author
- *   lines  ← trail steps, with each endpoint mapped to its owning element
- *
- * Trail steps whose endpoints are not claimed by any element are skipped:
- * drawing them would assert a relationship the author did not describe.
- */
-export function buildC4Model(options: C4BuildOptions): C4BuildResult {
-  const view = options.view ?? 'container';
-  const doc = options.document;
-  const problems: C4Problem[] = [];
-
-  const byAlias = new Map(doc?.components.map((c) => [c.alias, c]) ?? []);
-  /**
-   * Alias → owning element, innermost home wins. One owner per alias: this is
-   * what makes `conflicting_member` mean "two boxes disagree" rather than
-   * "a container and its components both mention the same code".
-   */
-  const membersOf = new Map<string, string[]>();
-
-  // --- accept each element once, and resolve membership --------------------
-  const seenIds = new Set<string>();
-  /** alias → element id. One owner per alias; conflicts are reported. */
-  const ownerOf = new Map<string, string>();
-  /** Ids in authored order, duplicates dropped. */
-  const accepted: string[] = [];
-  const elementById = new Map<string, C4Element>();
-
-  for (const e of options.elements) {
-    if (seenIds.has(e.id)) {
-      problems.push({
-        kind: 'duplicate_id',
-        subject: e.id,
-        message: `two elements share the id ${e.id}`,
-      });
-      continue;
-    }
-    seenIds.add(e.id);
-    accepted.push(e.id);
-    elementById.set(e.id, e);
-
-    // A rejected element is not drawn, so its members are inside nothing.
-    // Leaving them claimed would hide them from `unmapped` and quietly hide
-    // the fact that rejecting an element orphans whatever was in it.
-    if (e.state === 'rejected') continue;
-
-    for (const alias of e.members) {
-      if (doc && !byAlias.has(alias)) {
-        problems.push({
-          kind: 'unknown_member',
-          subject: alias,
-          message: `element "${e.id}" claims "${alias}", which is not in the supplied document`,
-        });
-        continue;
-      }
-      const existing = ownerOf.get(alias);
-      if (existing && existing !== e.id) {
-        problems.push({
-          kind: 'conflicting_member',
-          subject: alias,
-          message: `"${alias}" is claimed by both ${existing} and ${e.id}; it is drawn inside ${existing}`,
-        });
-        continue;
-      }
-      ownerOf.set(alias, e.id);
-      const list = membersOf.get(e.id) ?? [];
-      list.push(alias);
-      membersOf.set(e.id, list);
-    }
-  }
-
-  // --- the system boundary -------------------------------------------------
-  const repoKey =
-    options.repoKey ??
-    options.elements
-      .flatMap((e) => e.members)
-      .map((alias) => purlRepoKey(byAlias.get(alias)?.purl))
-      .find(Boolean);
-
-  const systemId = `system:${repoKey ?? 'unspecified'}`;
-  const systemLabel = options.systemLabel ?? (repoKey ? labelFromPurl(repoKey) : 'Software System');
-
-  // --- draw the boxes ------------------------------------------------------
-  const nodes: C4Node[] = [];
-  /**
-   * The aliases an element claimed itself, before any rollup. A component's
-   * own members and its container's own members are disjoint by construction,
-   * which is what lets the two be added together below.
-   */
-  const ownMembers = new Map<string, string[]>();
-  for (const id of accepted) {
-    const e = elementById.get(id)!;
-    if (e.state === 'rejected') continue;
-
-    const own = membersOf.get(id) ?? [];
-
-    // A component's parent is stated, not inferred. Check it resolves: a
-    // dangling parent would silently drop the component out of every frame.
-    let parentId: string | undefined;
-    if (e.kind === 'component') {
-      const parent = elementById.get(e.container);
-      if (!parent || parent.state === 'rejected') {
-        problems.push({
-          kind: 'unknown_container',
-          subject: id,
-          message: `component "${id}" names container "${e.container}", which is not in this set`,
-        });
-      } else if (parent.kind !== 'container') {
-        problems.push({
-          kind: 'unknown_container',
-          subject: id,
-          message: `component "${id}" names container "${e.container}", which is a ${parent.kind}, not a container`,
-        });
-      } else {
-        parentId = parent.id;
-      }
-    } else if (isInBoundary(e)) {
-      parentId = systemId;
-    }
-
-    ownMembers.set(id, own);
-    nodes.push({
-      id: e.id,
-      kind: e.kind,
-      label: e.label,
-      ...(parentId ? { parentId } : {}),
-      technology: 'technology' in e ? e.technology : undefined,
-      description: e.description,
-      state: e.state,
-      ...(e.kind === 'container' ? { containerKind: e.containerKind } : {}),
-      ...(e.derivedFrom && e.derivedFrom.length > 1 ? { derivedFrom: e.derivedFrom } : {}),
-      members: own,
-      constructs: [],
-    });
-  }
-
-  // --- roll components up into their container ------------------------------
-  //
-  // A C4 container diagram draws the container as a whole, so a container
-  // holds everything inside its components. Membership is still authored
-  // exactly once: an alias belongs to one element, so a container must not
-  // repeat what its components already claim — that repetition would read as
-  // a `conflicting_member` and hide the real question, which is how many
-  // components a container has.
-  for (const n of nodes) {
-    if (n.kind !== 'component' || !n.parentId) continue;
-    const list = membersOf.get(n.parentId) ?? [];
-    list.push(...(ownMembers.get(n.id) ?? []));
-    membersOf.set(n.parentId, list);
-  }
-
-  for (const n of nodes) {
-    n.members = membersOf.get(n.id) ?? [];
-    if (n.members.length === 0) {
-      problems.push({
-        kind: 'empty_element',
-        subject: n.id,
-        message: `element "${n.id}" (${n.kind}) claims no members, and nothing is inside it either, so there is nothing to draw`,
-      });
-    }
-    const resolved = n.members.map((m) => byAlias.get(m)).filter((c): c is SubsystemComponent => !!c);
-    const constructs: string[] = [];
-    for (const c of resolved) if (!constructs.includes(c.construct)) constructs.push(c.construct);
-    n.constructs = constructs;
-    if (n.kind === 'component' && resolved[0]) n.component = resolved[0];
-
-    const models = [...new Set(n.members.flatMap((m) => options.modelsByAlias?.[m] ?? []))];
-    if (models.length > 0) n.models = models;
-  }
-
-  // --- compound frames -----------------------------------------------------
-  const groups: C4Group[] = [];
-
-  if (view === 'container') {
-    const containerIds = nodes.filter((n) => n.kind === 'container').map((n) => n.id);
-    if (containerIds.length > 0) {
-      groups.push({ id: systemId, kind: 'system', label: systemLabel, memberIds: containerIds });
-    }
-  } else {
-    const byContainer = new Map<string, string[]>();
-    for (const n of nodes) {
-      if (n.kind !== 'component' || !n.parentId) continue;
-      const list = byContainer.get(n.parentId) ?? [];
-      list.push(n.id);
-      byContainer.set(n.parentId, list);
-    }
-    const framed: string[] = [];
-    for (const [id, memberIds] of byContainer) {
-      const label = nodes.find((n) => n.id === id)?.label ?? id;
-      groups.push({ id, kind: 'container', label, parentId: systemId, memberIds });
-      framed.push(id);
-    }
-    if (framed.length > 0) {
-      groups.push({ id: systemId, kind: 'system', label: systemLabel, memberIds: framed });
-    }
-  }
-
-  // --- lines, from the trails ---------------------------------------------
-  const drawn = new Set(nodes.map((n) => n.id));
-  const edges = new Map<string, C4Edge>();
-  for (const trail of doc?.trails ?? []) {
-    for (const step of trail.steps ?? []) {
-      const source = ownerOf.get(step.from);
-      const target = ownerOf.get(step.to);
-      // An endpoint no element claims has no box, so there is no line to draw.
-      if (!source || !target || source === target) continue;
-      if (!drawn.has(source) || !drawn.has(target)) continue;
-      const key = `${source}\0${target}`;
-      const edge = edges.get(key);
-      if (edge) {
-        edge.count += 1;
-        if (!edge.mechanisms.includes(step.mechanism)) edge.mechanisms.push(step.mechanism);
-      } else {
-        edges.set(key, {
-          id: `flow:${key}`,
-          source,
-          target,
-          label: step.mechanism,
-          mechanisms: [step.mechanism],
-          count: 1,
-        });
-      }
-    }
-  }
-  for (const e of edges.values()) e.label = [...e.mechanisms].sort().join(' + ');
-
-  const unmapped = (doc?.components ?? []).filter((c) => !ownerOf.has(c.alias)).map((c) => c.alias);
-
-  return {
-    model: {
-      view,
-      system: { id: systemId, label: systemLabel, repoKey },
-      nodes,
-      groups,
-      edges: [...edges.values()],
-    },
-    problems,
-    unmapped,
-  };
-}
-
-/**
- * Tally for the confirm UI: how much is proposed vs accepted, and how much is
- * still missing what the C4 notation requires.
- *
- * Counts the authored set, not the projection — a rejected element is still a
- * decision that was made, so it is reported rather than forgotten.
- */
-export function summarizeElements(elements: readonly C4Element[]): {
-  containers: number;
-  components: number;
-  externals: number;
-  people: number;
-  accepted: number;
-  proposed: number;
-  rejected: number;
-  /** Containers missing the technology C4 requires. */
-  missingTechnology: number;
-  /** Elements missing a description. */
-  missingDescription: number;
-  /** Elements whose state is not yet `accepted`. */
-  needsDecision: number;
-} {
-  const live = elements.filter((e) => e.state !== 'rejected');
-  return {
-    containers: live.filter((e) => e.kind === 'container').length,
-    components: live.filter((e) => e.kind === 'component').length,
-    externals: live.filter((e) => e.kind === 'external-system').length,
-    people: live.filter((e) => e.kind === 'person').length,
-    accepted: live.filter((e) => e.state === 'accepted').length,
-    proposed: live.filter((e) => e.state === 'proposed').length,
-    rejected: elements.filter((e) => e.state === 'rejected').length,
-    // `technology` is required by the type on containers and components, so a
-    // missing one can only mean an empty string — still worth reporting.
-    missingTechnology: live.filter((e) => 'technology' in e && !e.technology).length,
-    missingDescription: live.filter((e) => !e.description).length,
-    needsDecision: live.filter((e) => e.state !== 'accepted').length,
-  };
-}

package/src/subsystem/c4Evidence.test.ts

@@ -261,7 +261,7 @@ describe('proposeElements', () => {
   });
 
   test('a key with no framework signal gets an empty technology, not a guess', () => {
-    // `technology` is required by the type, and `summarizeElements` reports the
+    // `technology` is required by the type, and an empty one is reported.
     // gap. Writing "TypeScript" here would be the derivation this module does
     // not do.
     const set = proposeElements({ repoKey: REPO, rollup });

package/src/subsystem/c4Evidence.ts

@@ -288,7 +288,7 @@ export function proposeElements(
       label: key,
       containerKind: suggestContainerKind(members),
       // C4 requires a technology on every container. With no framework signal
-      // the honest value is empty and `summarizeElements` reports the gap —
+      // the honest value is empty and the notation-gap check reports it —
       // inventing "TypeScript" here would be exactly the derivation this
       // module stopped doing.
       technology: frameworks.length > 0 ? frameworks.join(' + ') : '',

package/src/subsystem/model.ts

@@ -406,6 +406,14 @@ export interface SubsystemTrailStep {
    * mechanism + filename fallback.
    */
   symbol: string;
+  /**
+   * Planned seam — the step describes intended behavior through code that is
+   * not written yet. Orthogonal to (and redundant with) the endpoints' own
+   * `proposed` flags: a step is proposed when it says so OR either endpoint
+   * is proposed. Verification skips source checks either way, and viewers
+   * tint it exactly like a proposed node.
+   */
+  proposed?: boolean;
   /**
    * Free-text note anchored to this step's site line. Optional — informative
    * only, never verified against source; the Pierre trail code view

package/src/subsystem/techIcons/bun.ts

@@ -0,0 +1,10 @@
+/**
+ * Bun mark — the official logo, vendored verbatim.
+ *
+ * Source: https://bun.sh/logo.svg.
+ * Bun and the Bun logo are trademarks of Oven. Used here for identification
+ * only, with no endorsement implied.
+ *
+ * Root sized to 100% so the card's wrapper controls the box.
+ */
+export const bunSvg = `<svg id="Bun" xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 80 70"><path id="Shadow" d="M71.09,20.74c-.16-.17-.33-.34-.5-.5s-.33-.34-.5-.5-.33-.34-.5-.5-.33-.34-.5-.5-.33-.34-.5-.5-.33-.34-.5-.5-.33-.34-.5-.5A26.46,26.46,0,0,1,75.5,35.7c0,16.57-16.82,30.05-37.5,30.05-11.58,0-21.94-4.23-28.83-10.86l.5.5.5.5.5.5.5.5.5.5.5.5.5.5C19.55,65.3,30.14,69.75,42,69.75c20.68,0,37.5-13.48,37.5-30C79.5,32.69,76.46,26,71.09,20.74Z"/><g id="Body"><path id="Background" d="M73,35.7c0,15.21-15.67,27.54-35,27.54S3,50.91,3,35.7C3,26.27,9,17.94,18.22,13S33.18,3,38,3s8.94,4.13,19.78,10C67,17.94,73,26.27,73,35.7Z" style="fill:#fbf0df"/><path id="Bottom_Shadow" data-name="Bottom Shadow" d="M73,35.7a21.67,21.67,0,0,0-.8-5.78c-2.73,33.3-43.35,34.9-59.32,24.94A40,40,0,0,0,38,63.24C57.3,63.24,73,50.89,73,35.7Z" style="fill:#f6dece"/><path id="Light_Shine" data-name="Light Shine" d="M24.53,11.17C29,8.49,34.94,3.46,40.78,3.45A9.29,9.29,0,0,0,38,3c-2.42,0-5,1.25-8.25,3.13-1.13.66-2.3,1.39-3.54,2.15-2.33,1.44-5,3.07-8,4.7C8.69,18.13,3,26.62,3,35.7c0,.4,0,.8,0,1.19C9.06,15.48,20.07,13.85,24.53,11.17Z" style="fill:#fffefc"/><path id="Top" d="M35.12,5.53A16.41,16.41,0,0,1,29.49,18c-.28.25-.06.73.3.59,3.37-1.31,7.92-5.23,6-13.14C35.71,5,35.12,5.12,35.12,5.53Zm2.27,0A16.24,16.24,0,0,1,39,19c-.12.35.31.65.55.36C41.74,16.56,43.65,11,37.93,5,37.64,4.74,37.19,5.14,37.39,5.49Zm2.76-.17A16.42,16.42,0,0,1,47,17.12a.33.33,0,0,0,.65.11c.92-3.49.4-9.44-7.17-12.53C40.08,4.54,39.82,5.08,40.15,5.32ZM21.69,15.76a16.94,16.94,0,0,0,10.47-9c.18-.36.75-.22.66.18-1.73,8-7.52,9.67-11.12,9.45C21.32,16.4,21.33,15.87,21.69,15.76Z" style="fill:#ccbea7;fill-rule:evenodd"/><path id="Outline" d="M38,65.75C17.32,65.75.5,52.27.5,35.7c0-10,6.18-19.33,16.53-24.92,3-1.6,5.57-3.21,7.86-4.62,1.26-.78,2.45-1.51,3.6-2.19C32,1.89,35,.5,38,.5s5.62,1.2,8.9,3.14c1,.57,2,1.19,3.07,1.87,2.49,1.54,5.3,3.28,9,5.27C69.32,16.37,75.5,25.69,75.5,35.7,75.5,52.27,58.68,65.75,38,65.75ZM38,3c-2.42,0-5,1.25-8.25,3.13-1.13.66-2.3,1.39-3.54,2.15-2.33,1.44-5,3.07-8,4.7C8.69,18.13,3,26.62,3,35.7,3,50.89,18.7,63.25,38,63.25S73,50.89,73,35.7C73,26.62,67.31,18.13,57.78,13,54,11,51.05,9.12,48.66,7.64c-1.09-.67-2.09-1.29-3-1.84C42.63,4,40.42,3,38,3Z"/></g><g id="Mouth"><g id="Background-2" data-name="Background"><path d="M45.05,43a8.93,8.93,0,0,1-2.92,4.71,6.81,6.81,0,0,1-4,1.88A6.84,6.84,0,0,1,34,47.71,8.93,8.93,0,0,1,31.12,43a.72.72,0,0,1,.8-.81H44.26A.72.72,0,0,1,45.05,43Z" style="fill:#b71422"/></g><g id="Tongue"><path id="Background-3" data-name="Background" d="M34,47.79a6.91,6.91,0,0,0,4.12,1.9,6.91,6.91,0,0,0,4.11-1.9,10.63,10.63,0,0,0,1-1.07,6.83,6.83,0,0,0-4.9-2.31,6.15,6.15,0,0,0-5,2.78C33.56,47.4,33.76,47.6,34,47.79Z" style="fill:#ff6164"/><path id="Outline-2" data-name="Outline" d="M34.16,47a5.36,5.36,0,0,1,4.19-2.08,6,6,0,0,1,4,1.69c.23-.25.45-.51.66-.77a7,7,0,0,0-4.71-1.93,6.36,6.36,0,0,0-4.89,2.36A9.53,9.53,0,0,0,34.16,47Z"/></g><path id="Outline-3" data-name="Outline" d="M38.09,50.19a7.42,7.42,0,0,1-4.45-2,9.52,9.52,0,0,1-3.11-5.05,1.2,1.2,0,0,1,.26-1,1.41,1.41,0,0,1,1.13-.51H44.26a1.44,1.44,0,0,1,1.13.51,1.19,1.19,0,0,1,.25,1h0a9.52,9.52,0,0,1-3.11,5.05A7.42,7.42,0,0,1,38.09,50.19Zm-6.17-7.4c-.16,0-.2.07-.21.09a8.29,8.29,0,0,0,2.73,4.37A6.23,6.23,0,0,0,38.09,49a6.28,6.28,0,0,0,3.65-1.73,8.3,8.3,0,0,0,2.72-4.37.21.21,0,0,0-.2-.09Z"/></g><g id="Face"><ellipse id="Right_Blush" data-name="Right Blush" cx="53.22" cy="40.18" rx="5.85" ry="3.44" style="fill:#febbd0"/><ellipse id="Left_Bluch" data-name="Left Bluch" cx="22.95" cy="40.18" rx="5.85" ry="3.44" style="fill:#febbd0"/><path id="Eyes" d="M25.7,38.8a5.51,5.51,0,1,0-5.5-5.51A5.51,5.51,0,0,0,25.7,38.8Zm24.77,0A5.51,5.51,0,1,0,45,33.29,5.5,5.5,0,0,0,50.47,38.8Z" style="fill-rule:evenodd"/><path id="Iris" d="M24,33.64a2.07,2.07,0,1,0-2.06-2.07A2.07,2.07,0,0,0,24,33.64Zm24.77,0a2.07,2.07,0,1,0-2.06-2.07A2.07,2.07,0,0,0,48.75,33.64Z" style="fill:#fff;fill-rule:evenodd"/></g></svg>`;

package/src/subsystem/techIcons/index.tsx

@@ -0,0 +1,73 @@
+/**
+ * Technology marks — official brand SVGs, vendored one per file, matched
+ * against an element's free-text `technology`.
+ *
+ * The rule is deliberately strict: if we do not hold the official mark for a
+ * technology, the slot stays empty. We do not substitute a generic glyph or a
+ * lookalike — a wrong logo is worse than none. Adding a brand is dropping its
+ * SVG in this folder and adding one row to `TECH_BRANDS`.
+ *
+ * Brand logos remain the property of their owners and are used for
+ * identification only, under each owner's trademark policy.
+ */
+
+import { bunSvg } from './bun';
+import { nodeSvg } from './node';
+import { reactSvg } from './react';
+
+export interface TechBrand {
+  /** Human name, used for the tooltip / accessible label. */
+  name: string;
+  /** Where the mark was vendored from. */
+  source: string;
+  /** The official SVG, with its root sized to 100%. */
+  svg: string;
+  /** Matched against the technology string. First match in `TECH_BRANDS` wins. */
+  match: RegExp;
+}
+
+/**
+ * Order matters: the first brand whose pattern matches is the one drawn, so
+ * put the more specific marks first if two could match the same string.
+ */
+export const TECH_BRANDS: readonly TechBrand[] = [
+  {
+    name: 'React',
+    source: 'https://react.dev',
+    svg: reactSvg,
+    match: /\breact\b/i,
+  },
+  {
+    name: 'Bun',
+    source: 'https://bun.sh/logo.svg',
+    svg: bunSvg,
+    match: /\bbun\b/i,
+  },
+  {
+    name: 'Node.js',
+    source: 'https://nodejs.org/static/logos/nodejsHex.svg',
+    svg: nodeSvg,
+    // Matches "Node" and "Node.js"; "Electrobun" has no word boundary before
+    // "bun" and never reaches here.
+    match: /\bnode(\.js)?\b/i,
+  },
+];
+
+/** The official mark for a technology string, or undefined when we hold none. */
+export function technologyBrand(technology: string | undefined): TechBrand | undefined {
+  if (!technology) return undefined;
+  return TECH_BRANDS.find((brand) => brand.match.test(technology));
+}
+
+/** A brand mark sized to the top row. Full-colour, not tinted by state. */
+export function TechMark({ brand, size = 14 }: { brand: TechBrand; size?: number }) {
+  return (
+    <span
+      title={`${brand.name} — ${brand.source}`}
+      aria-label={brand.name}
+      style={{ display: 'inline-flex', width: size, height: size, flexShrink: 0 }}
+      // The SVG is a static, vendored string — never user input.
+      dangerouslySetInnerHTML={{ __html: brand.svg }}
+    />
+  );
+}

package/src/subsystem/techIcons/node.ts

@@ -0,0 +1,38 @@
+/**
+ * Node.js mark — the official hexagon logo, vendored verbatim.
+ *
+ * Source: https://nodejs.org/static/logos/nodejsHex.svg (via
+ * https://nodejs.org/en/about/branding). Node.js and the Node.js logo are
+ * trademarks of the OpenJS Foundation. Used here for identification only,
+ * subject to https://trademark-policy.openjsf.org/.
+ *
+ * Root sized to 100% so the card's wrapper controls the box.
+ */
+export const nodeSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 44 50">
+  <defs>
+    <clipPath id="hexClip">
+      <path d="M22.8725 0.4166C22.136 0 21.2616 0 20.5253 0.4166L1.1505 11.6694C0.4142 12.0862 0 12.8733 0 13.707V36.2584C0 37.0921 0.4602 37.8791 1.1505 38.296L20.5253 49.5487C21.2616 49.9653 22.136 49.9653 22.8725 49.5487L42.2471 38.296C42.9836 37.8791 43.3976 37.0921 43.3976 36.2584V13.707C43.3976 12.8733 42.9375 12.0862 42.2471 11.6694L22.8725 0.4166Z" />
+    </clipPath>
+    <linearGradient id="main" x1="30.33" y1="8.56" x2="14.9" y2="44.7" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#3F8B3D"/>
+      <stop offset="0.64" stop-color="#3F873F"/>
+      <stop offset="0.93" stop-color="#3DA92E"/>
+      <stop offset="1" stop-color="#3DAE2B"/>
+    </linearGradient>
+    <linearGradient id="r1" x1="18.8" y1="26.8" x2="68" y2="0.4" gradientUnits="userSpaceOnUse">
+      <stop offset="0.14" stop-color="#3F873F"/>
+      <stop offset="0.4" stop-color="#52A044"/>
+      <stop offset="0.71" stop-color="#64B749"/>
+      <stop offset="0.91" stop-color="#6ABF4B"/>
+    </linearGradient>
+    <linearGradient id="r2" x1="0.25" y1="24.5" x2="44" y2="24.5" gradientUnits="userSpaceOnUse">
+      <stop offset="0.09" stop-color="#6ABF4B"/>
+      <stop offset="0.29" stop-color="#64B749"/>
+      <stop offset="0.6" stop-color="#52A044"/>
+      <stop offset="0.86" stop-color="#3F873F"/>
+    </linearGradient>
+  </defs>
+  <path fill="url(#main)" d="M22.8725 0.4166C22.136 0 21.2616 0 20.5253 0.4166L1.1505 11.6694C0.4142 12.0862 0 12.8733 0 13.707V36.2584C0 37.0921 0.4602 37.8791 1.1505 38.296L20.5253 49.5487C21.2616 49.9653 22.136 49.9653 22.8725 49.5487L42.2471 38.296C42.9836 37.8791 43.3976 37.0921 43.3976 36.2584V13.707C43.3976 12.8733 42.9375 12.0862 42.2471 11.6694L22.8725 0.4166Z" />
+  <polygon fill="url(#r1)" clip-path="url(#hexClip)" points="21.698901,-1.046618 43.20532,11.948247 21.698901,51.072715 0.152778,38.055107" />
+  <polygon fill="url(#r2)" clip-path="url(#hexClip)" points="21.698901,-1.046618 0.152778,11.948247 21.698901,51.072715 43.20532,38.055107" />
+</svg>`;

package/src/subsystem/techIcons/react.ts

@@ -0,0 +1,18 @@
+/**
+ * React mark — the official logo, vendored verbatim.
+ *
+ * Source: https://react.dev (the React logo; mirrored at
+ * https://commons.wikimedia.org/wiki/File:React-icon.svg).
+ * React and the React logo are trademarks of Meta Platforms, Inc. Used here
+ * for identification only, with no endorsement implied.
+ *
+ * Root sized to 100% so the card's wrapper controls the box.
+ */
+export const reactSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="-11.5 -10.23174 23 20.46348">
+  <circle cx="0" cy="0" r="2.05" fill="#61dafb"/>
+  <g stroke="#61dafb" stroke-width="1" fill="none">
+    <ellipse rx="11" ry="4.2"/>
+    <ellipse rx="11" ry="4.2" transform="rotate(60)"/>
+    <ellipse rx="11" ry="4.2" transform="rotate(120)"/>
+  </g>
+</svg>`;

package/src/subsystem/techIcons/techIcons.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test';
+import { TECH_BRANDS, technologyBrand } from './index';
+
+describe('technologyBrand', () => {
+  test('matches the brand named in the technology string', () => {
+    expect(technologyBrand('React 19')?.name).toBe('React');
+    expect(technologyBrand('React + ELK')?.name).toBe('React');
+    expect(technologyBrand('Bun + Electrobun host')?.name).toBe('Bun');
+    expect(technologyBrand('Bun fs')?.name).toBe('Bun');
+  });
+
+  test('does not match a brand name inside another word', () => {
+    // "Electrobun" contains "bun" but is not Bun — no word boundary.
+    expect(technologyBrand('Electrobun host')).toBeUndefined();
+  });
+
+  test('returns nothing for technologies we hold no official mark for', () => {
+    for (const tech of ['HTTP', 'REST', 'JSON files under ~/.principal', 'Electrobun host']) {
+      expect(technologyBrand(tech)).toBeUndefined();
+    }
+    expect(technologyBrand('')).toBeUndefined();
+    expect(technologyBrand(undefined)).toBeUndefined();
+  });
+
+  test('matches Node and Node.js', () => {
+    expect(technologyBrand('Node')?.name).toBe('Node.js');
+    expect(technologyBrand('Node.js 20')?.name).toBe('Node.js');
+  });
+
+  test('every vendored brand carries a source and an SVG', () => {
+    for (const brand of TECH_BRANDS) {
+      expect(brand.source).toMatch(/^https?:\/\//);
+      expect(brand.svg.startsWith('<svg')).toBe(true);
+      // Root sized to 100%, so the card wrapper controls the box.
+      expect(brand.svg).toContain('width="100%"');
+      expect(brand.svg).toContain('height="100%"');
+    }
+  });
+});