@principal-ai/principal-view-react 0.16.55 → 0.16.57

package/src/subsystem/model.ts

@@ -2,7 +2,7 @@
  * Subsystem component-graph data model + converters.
  *
  * A subsystem snapshot (see the "Subsystem artifact: facets" topic) is captured
- * as component nodes (kind-tagged source units), file refs, integration edges,
+ * as component nodes (construct-tagged source units), file refs, integration edges,
  * and entry points. This module defines the minimal document shape for the
  * *graph* facet and converts it to React Flow nodes/edges — packages render as
  * subgraphs, only cross-package edges leave the box, and shared seams
@@ -21,14 +21,30 @@ import { computeElkLayout } from '../utils/elkLayout';
 import type { GraphifyComponentDetail } from '../graphify';
 import type { SubsystemDeclarationRef } from './declarationRef';
 
-export type SubsystemComponentKind =
+export type SubsystemComponentConstruct =
   | 'class'
   | 'function'
   | 'method'
-  | 'type'
+  | 'interface'
+  | 'type_alias'
+  | 'enum'
   | 'module'
+  | 'store'
   | 'external';
 
+/**
+ * Semantic role — where the node sits in the topology, orthogonal to
+ * `construct` (what it is). Roles have *inherited* anatomy: an entry renders
+ * as its real code shape (function dispatcher, type contract); a service has
+ * no source at all (`construct: 'external'` + purl identity). Contrast with
+ * `construct: 'store'`, which introduces its own anatomy (the state block) —
+ * that is why store is a construct and not a role. Role nodes must stay anchored to real code: an
+ * `entry` is a boundary element (route dispatcher, message contract) carrying
+ * the wire address as identity; a `service` is an external system the process
+ * calls out to (identity via purl, no `process` — it belongs to no region).
+ */
+export type SubsystemComponentRole = 'entry' | 'service';
+
 // ---------------------------------------------------------------------------
 // Declaration tokens — structured source representation
 // ---------------------------------------------------------------------------
@@ -45,6 +61,8 @@ export type SubsystemDeclTokenKind =
 export interface SubsystemDeclToken {
   text: string;
   kind: SubsystemDeclTokenKind;
+  /** Shiki/Pierre foreground when tokenized client-side; omitted on legacy wire tokens. */
+  color?: string;
 }
 
 export type SubsystemEdgeMechanism =
@@ -63,19 +81,48 @@ export type SubsystemEdgeMechanism =
   | 'contains'
   | 'feeds'
   | 'produces'
+  | 'writes'
+  | 'reads'
+  | 'watches'
   | 'registers-into';
 
-/** A component node — the named unit, kind-tagged; `file` is its location. */
+/** A component node — the named unit, construct-tagged; `file` is its location. */
 export interface SubsystemComponent {
   id: string;
   name: string;
-  kind: SubsystemComponentKind;
+  /**
+   * The node's construct — what it IS as a declaration (class, function,
+   * method, interface, type alias, enum, store, external), driving node
+   * anatomy, color, badge, and the verification strategy. Every construct
+   * anchors to a definition; runtime occurrences (variables, activations,
+   * instances) are NOT constructs — they belong to a future execution-mode
+   * graph whose occurrence nodes reference these definitions. Ontology:
+   * construct = what it is, role = where it sits, process = where it runs.
+   */
+  construct: SubsystemComponentConstruct;
   /** Source location the component lives in (repo-root-relative path). */
   file: string;
   /** PURL identifying the repo or package this component lives in (for subgraph grouping). */
   purl: string;
   /** One-line purpose shown on the node. */
   purpose?: string;
+  /**
+   * Semantic role — where the node sits in the topology (boundary element,
+   * external system), orthogonal to `construct` (what it is). Drives the
+   * glyph and the edge-pairing rules: boundary-crossing edges must terminate
+   * at an entry or a service. Retained state is NOT a role — it is
+   * `construct: 'store'` (state-block anatomy, `writes`/`reads`/`watches`
+   * inbound, `produces` outbound).
+   */
+  role?: SubsystemComponentRole;
+  /**
+   * Runtime process membership — which deployment unit this node is a
+   * member of (e.g. `trail-viewer/host`, `trail-viewer/renderer`). Nodes
+   * sharing a `process` are drawn inside one boundary region (grouping is
+   * `process ?? purl`); nodes without one sit outside every boundary
+   * (external actors, services, libraries).
+   */
+  process?: string;
   /** A symbol this component exposes / is (the node's identity). */
   symbol?: string;
   /**
@@ -94,7 +141,7 @@ export interface SubsystemComponent {
   capture?: 'edited' | 'analyzed' | 'referenced';
   /**
    * Graphify drill-down detail for this component, when the facet is anchored
-   * to a graphify node. Discriminated by kind (class/function/type/module/
+   * to a graphify node. Discriminated by kind (class/function/type/module/store/
    * external); rendered in the detail panel on click.
    */
   detail?: GraphifyComponentDetail;
@@ -131,10 +178,10 @@ export interface SubsystemComponentEdge {
 }
 
 /**
- * Derive a consistent display `name` from a code `symbol` + kind.
+ * Derive a consistent display `name` from a code `symbol` + construct.
  *
- * `symbol` is the source of truth (fully-qualified code identity). For most
- * kinds the name is the symbol itself or its last dotted segment:
+ * `symbol` is the source of truth (fully-qualified code identity). The name
+ * is the symbol itself:
  *  - class/type/module/function/script/...  symbol → symbol (e.g. `SessionReader`)
  *  - method                               `Owner.method` → last segment (e.g. `SessionReader.normalize` → `normalize`)
  *  - module, no symbol → basename of `file` (e.g. `transcript.ts` → `transcript`) —
@@ -143,20 +190,37 @@ export interface SubsystemComponentEdge {
  */
 export function deriveNameFromSymbol(
   symbol: string | undefined,
-  kind: SubsystemComponentKind,
+  construct: SubsystemComponentConstruct,
   existingName?: string,
   file?: string,
 ): string {
+  let name: string | undefined;
   if (symbol && symbol.trim()) {
-    return symbol;
-  }
-  // Module nodes without a symbol are whole files → use the file basename.
-  if (kind === 'module' && file) {
+    name = symbol;
+  } else if (construct === 'module' && file) {
     const base = file.split('/').pop() ?? '';
     const clean = base.replace(/\.[^.]+$/, ''); // strip extension
-    if (clean) return clean;
+    if (clean) name = clean;
+  }
+  if (!name) name = existingName ?? 'untitled';
+
+  // Decoration = what the drill-down shows. Executable constructs wear `()`
+  // (a signature you can call); brace-bodied constructs wear ` {}` (a member
+  // body — fields for types/interfaces/enums, fields+methods for classes).
+  // Everything else (store, variable, module, external) renders bare.
+  if ((construct === 'function' || construct === 'method') && !name.endsWith('()')) {
+    name = `${name}()`;
   }
-  return existingName ?? 'untitled';
+  if (
+    (construct === 'class' ||
+      construct === 'interface' ||
+      construct === 'type_alias' ||
+      construct === 'enum') &&
+    !name.endsWith('{}')
+  ) {
+    name = `${name} {}`;
+  }
+  return name;
 }
 
 /**
@@ -235,6 +299,9 @@ export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
   contains: '#6c5ce7', // indigo
   feeds: '#22c55e', // green — data-flow into a processor
   produces: '#e07a5f', // terracotta — emits an output type
+  writes: '#2f9e44', // deep green — mutates retained state
+  reads: '#0ea5e9', // sky — pulls from retained state
+  watches: '#9ca3af', // gray — observes, owns nothing
   'registers-into': '#ff6b35', // orange
 };
 
@@ -254,6 +321,9 @@ export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed'
   contains: 'solid',
   feeds: 'solid',
   produces: 'solid',
+  writes: 'solid',
+  reads: 'solid',
+  watches: 'dashed',
   'registers-into': 'dashed',
 };
 
@@ -272,14 +342,19 @@ export function packageColor(name: string): string {
   return palette[h % palette.length];
 }
 
-/** Color per component kind — the informative signal (rather than package). */
-export const KIND_COLOR: Record<SubsystemComponentKind, string> = {
-  class: '#0893d2', // blue
-  function: '#6c5ce7', // indigo
-  method: '#d4a03c', // gold
-  type: '#e07a5f', // terracotta
-  module: '#4ec9b0', // teal
-  external: '#b48ead', // purple
+/** Color per semantic role — applied ONLY to the role badge (top-right tab on
+ *  nodes that carry a role). The node border stays construct-colored. Note:
+ *  `service` currently equals the old class hex; harmless while role badges
+ *  are the only surface using it, but pick a distinct value if roles ever
+ *  take over node borders. */
+export const ROLE_COLOR: Record<SubsystemComponentRole, string> = {
+  entry: '#ff6b35', // orange — boundary element
+  service: '#0893d2', // blue — external system
+};
+
+export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
+  entry: 'entry',
+  service: 'service',
 };
 
 /**
@@ -295,12 +370,16 @@ export function convertSubsystemToNodes(
   opts: { maxNodeWidth?: number } = {},
 ): SubsystemGraphNode[] {
   const { maxNodeWidth } = opts;
-  // Group components by package.
+  // Group components into boundary regions by process when authored, else by
+  // package. Process is runtime membership (drawn as one boundary region);
+  // purl is code identity — nodes without a process (external actors,
+  // services, libraries) fall back to purl and sit outside every boundary.
   const byPkg = new Map<string, SubsystemComponent[]>();
   for (const c of doc.components) {
-    const list = byPkg.get(c.purl) ?? [];
+    const regionKey = c.process ?? c.purl;
+    const list = byPkg.get(regionKey) ?? [];
     list.push(c);
-    byPkg.set(c.purl, list);
+    byPkg.set(regionKey, list);
   }
 
   const nodes: SubsystemGraphNode[] = [];
@@ -320,7 +399,7 @@ export function convertSubsystemToNodes(
       const row = Math.floor(i / COLS);
       // Estimate rendered node width from the longest text line so ELK reserves
       // the right space (names can wrap, so we cap at the configurable max).
-      const text = [c.symbol, c.name, c.file.split('/').pop() ?? '']
+      const text = [c.symbol, c.name, c.file?.split('/').pop() ?? '']
         .filter((t): t is string => !!t)
         .sort((a, b) => b.length - a.length)[0];
       const cap = maxNodeWidth ?? 300;
@@ -385,8 +464,8 @@ export function subsystemGraphLayoutKey(
   doc: Pick<SubsystemGraphDocument, 'components' | 'edges'>,
 ): string {
   const components = doc.components
-    .map(({ id, purl, name, symbol, kind, file, purpose }) =>
-      [id, purl, name, symbol ?? '', kind, file, purpose ?? ''].join('\0'))
+    .map(({ id, purl, name, symbol, construct, file, purpose, process }) =>
+      [id, purl, name, symbol ?? '', construct, file, purpose ?? '', process ?? ''].join('\0'))
     .sort()
     .join('\n');
   const edgeKey = doc.edges
@@ -435,7 +514,7 @@ export async function buildSubsystemGraph(
         component: {
           id: extId,
           name: label,
-          kind: 'external',
+          construct: 'external',
           purl: 'external',
           file: '',
           purpose: 'cross-package integration target (not a member node)',

package/src/subsystem/nodes.tsx

@@ -16,18 +16,26 @@ import {
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
 import {
-  KIND_COLOR,
   MECHANISM_COLOR,
+  MECHANISM_STYLE,
+  ROLE_COLOR,
+  ROLE_LABEL,
   deriveNameFromSymbol,
   type SubsystemGraphNode,
   type SubsystemGraphEdge,
 } from './model';
+import { constructColorsFromPierreTheme } from '../pierre/constructColors';
+import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
 
-export const KIND_LABEL: Record<string, string> = {
+export const CONSTRUCT_LABEL: Record<string, string> = {
   class: 'class',
   function: 'function',
-  type: 'type',
+  method: 'method',
+  interface: 'interface',
+  type_alias: 'type alias',
+  enum: 'enum',
   module: 'module',
+  store: 'store',
   external: 'external',
 };
 
@@ -48,6 +56,9 @@ function breakWords(s: string): string {
 export interface SubsystemGraphCallbacks {
   /** Click a component — open its file/entry point. */
   onSelect?: (componentId: string) => void;
+  /** Click the filename badge — open that component's file in the drawer
+   *  (same path as clicking the file link in the declaration panel). */
+  onOpenFile?: (componentId: string) => void;
   /** Click an edge (or its label) — select the relationship. */
   onEdgeSelect?: (edgeId: string) => void;
   /** Hover a component (null on leave) — associates it with the file tree. */
@@ -60,15 +71,19 @@ export interface SubsystemGraphCallbacks {
 export const SUBSYSTEM_CALLBACKS: SubsystemGraphCallbacks = {};
 
 export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
-  const { theme } = useTheme();
+  const { theme, mode } = useTheme();
   const { data, selected, width: nodeWidth, height: nodeHeight } = props;
   const c = data.component;
-  const color = KIND_COLOR[c.kind] ?? '#888';
+  // Construct owns node color, derived from the active Pierre syntax theme —
+  // the same palette the declaration panel and file drawer render with. Role
+  // shows as the hover badge, not as color — for now; a role glyph/accent may
+  // come later.
+  const color = constructColorsFromPierreTheme(resolvePierreSyntaxThemeName(mode))[c.construct];
   const [hover, setHover] = useState(false);
   const configuredMax = SUBSYSTEM_CALLBACKS.maxNodeWidth;
   const maxWidth = configuredMax ?? 300;
   // `symbol` is the source of truth; `name` is derived from it consistently.
-  const displayName = deriveNameFromSymbol(c.symbol, c.kind, c.name, c.file);
+  const displayName = deriveNameFromSymbol(c.symbol, c.construct, c.name, c.file);
   // Set while a file is open in the drawer: true → spotlight, false → dim,
   // absent (no file open) → neutral.
   const fileMatch = data.fileMatch as boolean | undefined;
@@ -117,36 +132,91 @@ export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
         fontFamily: theme.fonts.body,
       }}
     >
-      {/* Kind + package tooltip, shown at the top on hover */}
-      {hover && (
+      {/* Construct badge — a small tab riding the top-right border, in the
+          construct color. Persistent (no hover needed); pointer-events none so
+          clicks pass through to the node. */}
+      <div
+        style={{
+          position: 'absolute',
+          top: -9,
+          left: 10,
+          zIndex: 1,
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[0] * 1.1,
+          letterSpacing: 0.5,
+          textTransform: 'uppercase',
+          lineHeight: '17px',
+          color,
+          background: theme.colors.backgroundSecondary ?? theme.colors.background,
+          border: `1px solid ${color}`,
+          borderRadius: 4,
+          padding: '0 5px',
+        }}
+      >
+        {CONSTRUCT_LABEL[c.construct] ?? c.construct}
+      </div>
+
+      {/* Role badge — top-right, only when the node carries a topology role.
+          Role color (entry orange / service blue) on the badge; the node
+          border stays construct-colored. */}
+      {c.role != null && (
         <div
           style={{
             position: 'absolute',
-            top: -26,
-            left: 0,
-            zIndex: 1000,
-            display: 'flex',
-            alignItems: 'center',
-            gap: 6,
-            whiteSpace: 'nowrap',
-            fontSize: theme.fontSizes[0] * 0.8,
+            top: -9,
+            right: 10,
+            zIndex: 1,
             fontFamily: theme.fonts.monospace,
+            fontSize: theme.fontSizes[0] * 1.1,
             letterSpacing: 0.5,
-            color,
-            background: theme.colors.background,
-            border: `1px solid ${theme.colors.border}`,
+            textTransform: 'uppercase',
+            lineHeight: '17px',
+            color: ROLE_COLOR[c.role],
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            border: `1px solid ${ROLE_COLOR[c.role]}`,
             borderRadius: 4,
-            padding: '1px 6px',
+            padding: '0 5px',
           }}
         >
-          <span style={{ textTransform: 'uppercase' }}>
-            {KIND_LABEL[c.kind] ?? c.kind}
-          </span>
-          {c.file ? ` · ${c.file.split('/').pop()}` : ''}
-          {c.capture && c.capture !== 'edited' ? ` · ${c.capture}` : ''}
+          {ROLE_LABEL[c.role]}
         </div>
       )}
 
+      {/* Filename badge — a strip across the bottom border, shown on hover
+          and pinned while this node's file is open in the drawer (fileMatch).
+          Mirrors the construct/role tab badges; hidden for fileless nodes. */}
+      {(hover || fileMatch === true) && c.file ? (
+        <div
+          style={{
+            position: 'absolute',
+            bottom: -13,
+            left: '50%',
+            transform: 'translateX(-50%)',
+            zIndex: 1,
+            fontFamily: theme.fonts.monospace,
+            fontSize: theme.fontSizes[0] * 1.1,
+            letterSpacing: 0.5,
+            lineHeight: '17px',
+            whiteSpace: 'nowrap',
+            // filename stays neutral — the construct color belongs to the
+            // borders and badges, not the file name
+            color: theme.colors.text ?? theme.colors.textSecondary,
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            border: `1px solid ${color}`,
+            borderRadius: 4,
+            padding: '0 5px',
+            cursor: 'pointer',
+          }}
+          onClick={(e) => {
+            // Open the file directly; don't also toggle node selection.
+            e.stopPropagation();
+            SUBSYSTEM_CALLBACKS.onOpenFile?.(c.id);
+          }}
+        >
+          {c.file.split('/').pop()}
+        </div>
+      ) : null}
+
       {/* Purpose is no longer shown as a hover tooltip below the node — it
           lives in the declaration panel and the graphify detail payload. */}
 
@@ -168,7 +238,11 @@ export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
         {breakWords(displayName)}
       </div>
 
-      {c.symbol && c.symbol !== displayName && (
+      {/* Hide the identity line when the symbol is just the title without its
+          decoration (`()` or ` {}`) — only show it when it adds information
+          (e.g. the dotted host on methods, or a different code identity). */}
+      {c.symbol &&
+        c.symbol !== displayName.replace(/ ?\{\}$/, '').replace(/\(\)$/, '') && (
         <div
           style={{
             fontSize: theme.fontSizes[0] * 0.82,
@@ -204,7 +278,9 @@ export function SubsystemEdge({
   const path = data?.elkPath ?? '';
   const mechanism = data?.mechanism ?? 'imports';
   const color = MECHANISM_COLOR[mechanism] ?? '#888';
-  const isDashed = mechanism === 'registers-into';
+  // Dash style comes from the mechanism table (dashed = inverted-control or
+  // observational relationships: hierarchy, registration, watches).
+  const isDashed = MECHANISM_STYLE[mechanism] === 'dashed';
   const dimmed = data?.dimmed === true;
   const opacity = dimmed ? 0.15 : 1;
 

package/src/subsystem/tokenizeComponent.ts

@@ -2,12 +2,13 @@
  * Tokenize a SubsystemComponent into a flat token stream for the detail panel.
  *
  * Pipeline: generate declaration string → format with Prettier → tokenize
- * with highlight.js. The `component.tokens` field, when present, overrides
- * the entire pipeline (for pre-tokenized data from graphify).
+ * with Shiki + Pierre themes. The `component.tokens` field, when present,
+ * overrides the entire pipeline (for pre-tokenized data from graphify).
  *
  * This function is async because Prettier's format() is async.
  */
 
+import type { PierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
 import type { SubsystemComponent, SubsystemDeclToken } from './model';
 import { generateDeclarationString } from './formatDeclaration';
 import { tokenizeFormatted } from './tokenizeFormatted';
@@ -40,21 +41,20 @@ async function getPrettier() {
  * it's returned as-is. Otherwise the pipeline generates a TypeScript
  * declaration string, formats it with Prettier, and tokenizes the output.
  */
-export async function tokenizeComponent(component: SubsystemComponent, printWidth = 80): Promise<SubsystemDeclToken[]> {
+export async function tokenizeComponent(
+  component: SubsystemComponent,
+  printWidth = 80,
+  themeName: PierreSyntaxThemeName = 'pierre-dark',
+): Promise<SubsystemDeclToken[]> {
   // Pre-tokenized tokens from the wire take precedence.
   if (component.tokens) return component.tokens;
 
   // External kind — not valid TypeScript, bypass Prettier.
-  const kind = component.detail?.kind ?? component.kind;
+  const kind = component.detail?.kind ?? component.construct;
   if (kind === 'external') {
     const label = component.detail?.kind === 'external' ? component.detail.label : component.name;
-    return [
-      { text: 'external', kind: 'keyword' },
-      { text: ' ', kind: 'punctuation' },
-      { text: "'", kind: 'punctuation' },
-      { text: label, kind: 'string' },
-      { text: "'", kind: 'punctuation' },
-    ];
+    const escaped = label.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    return tokenizeFormatted(`external '${escaped}'`, themeName);
   }
 
   // Generate → format → tokenize
@@ -66,5 +66,5 @@ export async function tokenizeComponent(component: SubsystemComponent, printWidt
     printWidth,
   });
 
-  return tokenizeFormatted(formatted);
+  return tokenizeFormatted(formatted, themeName);
 }

package/src/subsystem/tokenizeFormatted.ts

@@ -1,92 +1,19 @@
 /**
  * Tokenize a formatted TypeScript declaration string into SubsystemDeclToken[]
- * using highlight.js.
- *
- * highlight.js produces HTML with `<span class="hljs-...">` wrappers. This
- * module parses that output into our token format so the renderer stays
- * language-agnostic.
+ * using Shiki + Pierre themes (same highlighter stack as @pierre/diffs).
  */
 
-import hljs from 'highlight.js/lib/core';
-import typescript from 'highlight.js/lib/languages/typescript';
-import type { SubsystemDeclToken, SubsystemDeclTokenKind } from './model';
-
-// Register once — safe to call multiple times.
-try {
-  hljs.registerLanguage('typescript', typescript);
-} catch {
-  // Already registered.
-}
-
-// hljs class → our token kind
-const CLASS_MAP: Record<string, SubsystemDeclTokenKind> = {
-  'hljs-keyword': 'keyword',
-  'hljs-title': 'name',
-  'hljs-title.function_': 'name',
-  'hljs-params': 'member',
-  'hljs-type': 'type',
-  'hljs-built_in': 'type',
-  'hljs-string': 'string',
-  'hljs-number': 'string',
-  'hljs-comment': 'punctuation',
-};
+import { tokenizeWithPierreSyntax } from '../pierre/syntaxTokens';
+import type { PierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
+import type { SubsystemDeclToken } from './model';
 
 /**
  * Tokenize a formatted TypeScript string into SubsystemDeclToken[].
  * The input should already be formatted by Prettier (or be valid TS).
  */
-export function tokenizeFormatted(code: string): SubsystemDeclToken[] {
-  const result = hljs.highlight(code, { language: 'typescript' });
-  return parseHighlightedHtml(result.value);
-}
-
-// ---------------------------------------------------------------------------
-// HTML parser — walks the hljs output and extracts tokens
-// ---------------------------------------------------------------------------
-
-function unescapeHtml(text: string): string {
-  return text
-    .replace(/&quot;/g, '"')
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&amp;/g, '&')
-    .replace(/&#39;/g, "'");
-}
-
-function parseHighlightedHtml(html: string): SubsystemDeclToken[] {
-  const tokens: SubsystemDeclToken[] = [];
-  // Regex matches either `<span class="hljs-...">`, `</span>`, or text content.
-  const re = /<span class="([^"]+)">|<\/span>|[^<]+/g;
-  const classStack: string[] = [];
-  let match: RegExpExecArray | null;
-
-  while ((match = re.exec(html)) !== null) {
-    const chunk = match[0];
-
-    if (chunk.startsWith('<span')) {
-      // Opening tag — push class onto stack.
-      classStack.push(match[1]);
-    } else if (chunk === '</span>') {
-      // Closing tag — pop class.
-      classStack.pop();
-    } else {
-      // Text content — emit tokens for each line segment.
-      const currentClass = classStack[classStack.length - 1] ?? '';
-      const kind = CLASS_MAP[currentClass] ?? 'punctuation';
-      const text = chunk;
-
-      // Split on newlines so each line becomes its own token set.
-      const lines = text.split('\n');
-      for (let i = 0; i < lines.length; i++) {
-        if (i > 0) {
-          tokens.push({ text: '', kind: 'newline' });
-        }
-        if (lines[i]) {
-          tokens.push({ text: unescapeHtml(lines[i]), kind });
-        }
-      }
-    }
-  }
-
-  return tokens;
+export function tokenizeFormatted(
+  code: string,
+  themeName: PierreSyntaxThemeName = 'pierre-dark',
+): Promise<SubsystemDeclToken[]> {
+  return tokenizeWithPierreSyntax(code, themeName);
 }