@principal-ai/subsystems-react 0.19.2 → 0.20.0

package/dist/subsystem/tokenizeComponent.js

@@ -43,6 +43,10 @@ export async function tokenizeComponent(component, printWidth = 80, themeName =
         const escaped = label.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
         return tokenizeFormatted(`external '${escaped}'`, themeName);
     }
+    // Custom entity — an actor (Person/agent/queue), not code; bypass Prettier.
+    if (kind === 'custom_entity') {
+        return tokenizeFormatted(generateDeclarationString(component), themeName);
+    }
     // Generate → format → tokenize
     const raw = generateDeclarationString(component);
     const { prettier, plugins } = await getPrettier();

package/dist/subsystem/tokenizeComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"tokenizeComponent.js","sourceRoot":"","sources":["../../src/subsystem/tokenizeComponent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,8CAA8C;AAC9C,IAAI,eAAe,GAAyD,IAAI,CAAC;AACjF,IAAI,sBAAsB,GAGd,IAAI,CAAC;AAEjB,KAAK,UAAU,WAAW;IACxB,IAAI,CAAC,eAAe,EAAE;QACpB,eAAe,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;KACjD;IACD,IAAI,CAAC,sBAAsB,EAAE;QAC3B,sBAAsB,GAAG,OAAO,CAAC,GAAG,CAAC;YACnC,MAAM,CAAC,6BAA6B,CAAC;YACrC,MAAM,CAAC,yBAAyB,CAAC;SAClC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;KAC7D;IACD,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC,CAAC;IACzF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAA6B,EAC7B,UAAU,GAAG,EAAE,EACf,YAAmC,aAAa;IAEhD,sDAAsD;IACtD,IAAI,SAAS,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC,MAAM,CAAC;IAE9C,yDAAyD;IACzD,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,IAAI,SAAS,CAAC,SAAS,CAAC;IAC3D,IAAI,IAAI,KAAK,UAAU,EAAE;QACvB,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC;QAC9F,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAClE,OAAO,iBAAiB,CAAC,aAAa,OAAO,GAAG,EAAE,SAAS,CAAC,CAAC;KAC9D;IAED,+BAA+B;IAC/B,MAAM,GAAG,GAAG,yBAAyB,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IAClD,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE;QAC3C,MAAM,EAAE,YAAY;QACpB,OAAO,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC;QAC7C,UAAU;KACX,CAAC,CAAC;IAEH,OAAO,iBAAiB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AACjD,CAAC"}
+{"version":3,"file":"tokenizeComponent.js","sourceRoot":"","sources":["../../src/subsystem/tokenizeComponent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,8CAA8C;AAC9C,IAAI,eAAe,GAAyD,IAAI,CAAC;AACjF,IAAI,sBAAsB,GAGd,IAAI,CAAC;AAEjB,KAAK,UAAU,WAAW;IACxB,IAAI,CAAC,eAAe,EAAE;QACpB,eAAe,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;KACjD;IACD,IAAI,CAAC,sBAAsB,EAAE;QAC3B,sBAAsB,GAAG,OAAO,CAAC,GAAG,CAAC;YACnC,MAAM,CAAC,6BAA6B,CAAC;YACrC,MAAM,CAAC,yBAAyB,CAAC;SAClC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;KAC7D;IACD,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC,CAAC;IACzF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAA6B,EAC7B,UAAU,GAAG,EAAE,EACf,YAAmC,aAAa;IAEhD,sDAAsD;IACtD,IAAI,SAAS,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC,MAAM,CAAC;IAE9C,yDAAyD;IACzD,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,IAAI,SAAS,CAAC,SAAS,CAAC;IAC3D,IAAI,IAAI,KAAK,UAAU,EAAE;QACvB,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC;QAC9F,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAClE,OAAO,iBAAiB,CAAC,aAAa,OAAO,GAAG,EAAE,SAAS,CAAC,CAAC;KAC9D;IAED,4EAA4E;IAC5E,IAAI,IAAI,KAAK,eAAe,EAAE;QAC5B,OAAO,iBAAiB,CAAC,yBAAyB,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC;KAC3E;IAED,+BAA+B;IAC/B,MAAM,GAAG,GAAG,yBAAyB,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IAClD,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE;QAC3C,MAAM,EAAE,YAAY;QACpB,OAAO,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC;QAC7C,UAAU;KACX,CAAC,CAAC;IAEH,OAAO,iBAAiB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AACjD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-react",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "React UI for Subsystem Models — graph, Pierre code views, and session-event feeds",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -45,7 +45,7 @@
     "@pierre/diffs": "1.3.6",
     "@principal-ade/industry-theme": "0.1.7",
     "@principal-ai/agent-monitoring": "^0.3.38",
-    "@principal-ai/subsystems-core": "0.30.0",
+    "@principal-ai/subsystems-core": "0.31.0",
     "@storybook/addon-docs": "10.1.2",
     "@storybook/addon-links": "10.1.2",
     "@storybook/addon-onboarding": "10.1.2",

package/src/graphify/consolidated.ts

@@ -190,6 +190,23 @@ export interface GraphifyExternalDetail {
   label: string;
 }
 
+/** A single authored attribute on a custom entity — free-form key/value. */
+export interface GraphifyCustomEntityAttribute {
+  key: string;
+  value: string;
+}
+
+/**
+ * A custom-entity (actor — Person/agent/queue) declaration. Authored, never
+ * extracted: there is no graphify node for a Person. `attributes` are
+ * free-form key/value pairs surfaced in the declaration panel; the base
+ * component fields carry the node identity (`entityKind`, `color`, `purpose`).
+ */
+export interface GraphifyCustomEntityDetail {
+  kind: 'custom_entity';
+  attributes: GraphifyCustomEntityAttribute[];
+}
+
 /**
  * A retained-state node (`kind: 'store'`): state and its contract, no
  * behavior. `kind` is the node's verifiable anchor — a store anchors to a
@@ -232,6 +249,7 @@ export type GraphifyComponentDetail =
   | GraphifyTypeDetail
   | GraphifyModuleDetail
   | GraphifyExternalDetail
+  | GraphifyCustomEntityDetail
   | GraphifyStoreDetail;
 
 /** A raw graphify edge backing a facet claim (verification + provenance). */

package/src/graphify/index.ts

@@ -31,6 +31,8 @@ export type {
   GraphifyTypeDetail,
   GraphifyModuleDetail,
   GraphifyExternalDetail,
+  GraphifyCustomEntityDetail,
+  GraphifyCustomEntityAttribute,
   GraphifyStoreDetail,
   GraphifyComponentDetail,
   GraphifyEdgeRef,

package/src/index.ts

@@ -43,6 +43,8 @@ export type {
   GraphifyTypeDetail,
   GraphifyModuleDetail,
   GraphifyExternalDetail,
+  GraphifyCustomEntityDetail,
+  GraphifyCustomEntityAttribute,
   GraphifyComponentDetail,
   GraphifyEdgeRef,
 } from './graphify';
@@ -92,7 +94,7 @@ export type {
 } from './subsystem/ComponentDeclaration';
 export { ComponentDeclaration } from './subsystem/ComponentDeclaration';
 export { MECHANISM_COLOR, MECHANISM_STYLE } from './subsystem/model';
-export { CONSTRUCT_COLOR, constructColorsFromPierreTheme } from './pierre/constructColors';
+export { CONSTRUCT_COLOR, componentColor, constructColorsFromPierreTheme } from './pierre/constructColors';
 export {
   purlRepoKey,
   purlOwnerName,

package/src/pierre/constructColors.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, test } from 'bun:test';
-import { CONSTRUCT_COLOR, constructColorsFromPierreTheme } from './constructColors';
+import {
+  CONSTRUCT_COLOR,
+  componentColor,
+  constructColorsFromPierreTheme,
+} from './constructColors';
 import type { SubsystemComponentConstruct } from '../subsystem/model';
 
 const CONSTRUCTS: SubsystemComponentConstruct[] = [
@@ -12,6 +16,7 @@ const CONSTRUCTS: SubsystemComponentConstruct[] = [
   'module',
   'store',
   'external',
+  'custom_entity',
 ];
 
 const HEX = /^#[0-9a-f]{6}$/;
@@ -26,7 +31,7 @@ describe('constructColorsFromPierreTheme', () => {
     }
   });
 
-  test('all seven constructs are distinguishable within a theme', () => {
+  test('all ten constructs are distinguishable within a theme', () => {
     for (const themeName of ['pierre-dark', 'pierre-light'] as const) {
       const colors = constructColorsFromPierreTheme(themeName);
       const values = CONSTRUCTS.map((c) => colors[c]);
@@ -49,4 +54,29 @@ describe('constructColorsFromPierreTheme', () => {
   test('the static dark instantiation matches the derived table', () => {
     expect(CONSTRUCT_COLOR).toEqual(constructColorsFromPierreTheme('pierre-dark'));
   });
+
+  test('componentColor inherits the construct color when no override', () => {
+    expect(componentColor({ construct: 'class' }, 'pierre-dark')).toBe(
+      constructColorsFromPierreTheme('pierre-dark').class,
+    );
+    expect(componentColor({ construct: 'custom_entity' }, 'pierre-light')).toBe(
+      constructColorsFromPierreTheme('pierre-light').custom_entity,
+    );
+  });
+
+  test('componentColor prefers an authored color override', () => {
+    expect(
+      componentColor(
+        { construct: 'custom_entity', color: '#ff00aa' },
+        'pierre-dark',
+      ),
+    ).toBe('#ff00aa');
+    // same override in both themes — the explicit color wins outright
+    expect(
+      componentColor(
+        { construct: 'custom_entity', color: '#ff00aa' },
+        'pierre-light',
+      ),
+    ).toBe('#ff00aa');
+  });
 });

package/src/pierre/constructColors.ts

@@ -19,6 +19,20 @@ import type { PierreSyntaxThemeName } from './pierreSyntaxTheme';
 import pierreDark from '@pierre/theme/pierre-dark';
 import pierreLight from '@pierre/theme/pierre-light';
 
+/**
+ * Resolve a component's accent color: an authored `color` override wins;
+ * otherwise the construct color derived from the active Pierre syntax theme.
+ * Single source of truth so the node border/badges and the declaration panel
+ * agree on what a custom entity (or any component) renders as.
+ */
+export function componentColor(
+  component: { color?: string; construct: SubsystemComponentConstruct },
+  themeName: PierreSyntaxThemeName,
+): string {
+  if (component.color) return component.color;
+  return constructColorsFromPierreTheme(themeName)[component.construct];
+}
+
 interface PierreThemeInput {
   type: 'dark' | 'light';
   colors: Record<string, string>;
@@ -93,6 +107,10 @@ export function constructColorsFromPierreTheme(
     module: towardBackground(moduleColor, 0.18),
     store: pick('variable.other.constant'),
     external: pick('comment'),
+    // custom entities are actors, not code — the heading/emphasis coral reads
+    // as a highlight against the code-construct hues. Distinct from entry role
+    // orange (#ff6b35) which stays a badge, not a border.
+    custom_entity: pick('markup.heading'),
   };
 }
 

package/src/stories/Subsystem/ComponentGraph/CustomEntities.stories.tsx

@@ -0,0 +1,184 @@
+import React from 'react';
+import '@xyflow/react/dist/style.css';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
+import type { SubsystemComponent, SubsystemComponentEdge } from '../../../subsystem/model';
+import type { GraphifyCustomEntityDetail } from '../../../graphify';
+
+/** Authored attributes surfaced in the declaration panel. */
+function entityDetail(attributes: Array<[string, string]>): GraphifyCustomEntityDetail {
+  return {
+    kind: 'custom_entity',
+    attributes: attributes.map(([key, value]) => ({ key, value })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Custom-entity prototype — the NovaTech work-request chain as it would read
+// once the `custom_entity` construct ships. Persons, an agent, and a queue are
+// authored as `construct: 'custom_entity'` with an open-string `entityKind`
+// (Person / agent / queue); every entity still groups by `process` and flows
+// through the same edge vocabulary as code nodes.
+// ---------------------------------------------------------------------------
+
+const components: SubsystemComponent[] = [
+  {
+    id: 'wr',
+    name: 'WorkRequester',
+    construct: 'custom_entity',
+    entityKind: 'Person',
+    file: '',
+    purl: 'external',
+    purpose: 'submits a facilities work request',
+    role: 'entry',
+    detail: entityDetail([
+      ['vertical', 'buildings'],
+      ['escalationPath', 'FacilitiesTechnician → ShiftSupervisor'],
+    ]),
+  },
+  {
+    id: 'tech',
+    name: 'FacilitiesTechnician',
+    construct: 'custom_entity',
+    entityKind: 'Person',
+    file: '',
+    purl: 'pkg:github/novatech/facilities-ops',
+    purpose: 'performs repairs, resolves L1 requests',
+    process: 'novatech/core-ops',
+    layer: 1,
+    detail: entityDetail([
+      ['level', 'L1'],
+      ['projects', 'HVAC, plumbing'],
+    ]),
+  },
+  {
+    id: 'sup',
+    name: 'ShiftSupervisor',
+    construct: 'custom_entity',
+    entityKind: 'Person',
+    file: '',
+    purl: 'pkg:github/novatech/facilities-ops',
+    purpose: 'assigns technicians, approves out-of-scope work',
+    process: 'novatech/core-ops',
+    layer: 2,
+    detail: entityDetail([
+      ['level', 'L2'],
+      ['approvalLimit', '$500'],
+    ]),
+  },
+  {
+    id: 'mgr',
+    name: 'CampusOpsManager',
+    construct: 'custom_entity',
+    entityKind: 'Person',
+    file: '',
+    purl: 'pkg:github/novatech/facilities-ops',
+    purpose: 'owns the queue, escalates campus-wide issues',
+    process: 'novatech/core-ops',
+    layer: 3,
+    detail: entityDetail([
+      ['level', 'L3'],
+      ['approvalLimit', '$5,000'],
+    ]),
+  },
+  {
+    id: 'vp',
+    name: 'VPOperations',
+    construct: 'custom_entity',
+    entityKind: 'Person',
+    file: '',
+    purl: 'pkg:github/novatech/facilities-ops',
+    purpose: 'funds large projects, signs off L4 requests',
+    process: 'novatech/core-ops',
+    layer: 4,
+    detail: entityDetail([
+      ['level', 'L4'],
+      ['approvalLimit', 'unlimited'],
+    ]),
+  },
+  {
+    id: 'agent',
+    name: 'OpsInsightAgent',
+    construct: 'custom_entity',
+    entityKind: 'agent',
+    color: '#9d6afb',
+    file: '',
+    purl: 'pkg:github/novatech/facilities-ops',
+    purpose: 'proposes nudges from open-request patterns; never owns the queue',
+    process: 'novatech/core-ops',
+    layer: 2,
+    detail: entityDetail([
+      ['slack', 'novatech/facilities-ops'],
+      ['permission', 'propose-only'],
+    ]),
+  },
+  {
+    id: 'queue',
+    name: 'NudgeQueue',
+    construct: 'custom_entity',
+    entityKind: 'queue',
+    color: '#b48ead',
+    file: '',
+    purl: 'pkg:github/novatech/facilities-ops',
+    purpose: 'holds proposed nudges until a supervisor confirms them',
+    process: 'novatech/core-ops',
+    layer: 3,
+    detail: entityDetail([
+      ['durable', 'postgres + outbox'],
+      ['owner', 'CampusOpsManager'],
+    ]),
+  },
+  {
+    id: 'store',
+    name: 'WorkRequestStore',
+    construct: 'store',
+    file: 'src/ops/workRequests.ts',
+    purl: 'pkg:github/novatech/facilities-ops',
+    purpose: 'retained work-request state — submissions, assignments, approvals',
+    symbol: 'workRequests',
+    process: 'novatech/core-ops',
+    layer: 1,
+  },
+];
+
+const edges: SubsystemComponentEdge[] = [
+  ['wr', 'store', 'feeds'],
+  ['store', 'tech', 'feeds'],
+  ['tech', 'sup', 'watches'],
+  ['sup', 'queue', 'watches'],
+  ['agent', 'store', 'reads'],
+  ['agent', 'queue', 'feeds'],
+  ['queue', 'mgr', 'feeds'],
+  ['mgr', 'vp', 'watches'],
+].map(([from, to, mechanism], i) => ({ id: `e${i}`, from, to, mechanism }));
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/CustomEntities',
+  component: SubsystemComponentGraph,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof SubsystemComponentGraph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const NovaTechWorkRequests: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        title="Custom entities — NovaTech work-request chain"
+        description="Persons, an agent, and a queue as `custom_entity` nodes (badge = entityKind). Actors keep the themed coral; the agent and queue wear authored `color` overrides. Click a node for its declaration — `entity 'Name' — kind` plus authored `attributes` (key: value)."
+        components={components}
+        edges={edges}
+      />
+    </div>
+  ),
+};

package/src/subsystem/ComponentDeclaration.tsx

@@ -18,7 +18,7 @@ import {
 import type { SubsystemOpenFileOptions } from './declarationRef';
 import { parseSourceLocation } from './declarationRef';
 import { tokenizeComponent } from './tokenizeComponent';
-import { constructColorsFromPierreTheme } from '../pierre/constructColors';
+import { componentColor } from '../pierre/constructColors';
 
 /** Live / result state for the declaration-panel Verify control. */
 export type ComponentVerificationPhase =
@@ -263,7 +263,7 @@ export function ComponentDeclaration({
   const [showFile, setShowFile] = useState(false);
   const [showPurpose, setShowPurpose] = useState(false);
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
-  const color = constructColorsFromPierreTheme(pierreSyntaxTheme)[component.construct];
+  const color = componentColor(component, pierreSyntaxTheme);
   const okColor = '#3d9a5f';
   const warnColor = theme.colors.textSecondary;
 

package/src/subsystem/formatDeclaration.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from 'bun:test';
+import { generateDeclarationString } from './formatDeclaration';
+import type { SubsystemComponent } from './model';
+
+describe('generateDeclarationString — custom_entity', () => {
+  test('renders entity identity + entityKind, no attributes when none authored', () => {
+    const component: SubsystemComponent = {
+      id: 'ct',
+      name: 'FacilitiesTechnician',
+      construct: 'custom_entity',
+      entityKind: 'Person',
+      file: '',
+      purl: 'pkg:github/novatech/facilities-ops',
+    };
+    expect(generateDeclarationString(component)).toBe(
+      "entity 'FacilitiesTechnician' — Person",
+    );
+  });
+
+  test('renders authored attributes as indented key: value lines', () => {
+    const component: SubsystemComponent = {
+      id: 'ct',
+      name: 'OpsInsightAgent',
+      construct: 'custom_entity',
+      entityKind: 'agent',
+      file: '',
+      purl: 'pkg:github/novatech/facilities-ops',
+      detail: {
+        kind: 'custom_entity',
+        attributes: [
+          { key: 'slack', value: 'novatech/facilities-ops' },
+          { key: 'permission', value: 'propose-only' },
+        ],
+      },
+    };
+    expect(generateDeclarationString(component)).toBe(
+      "entity 'OpsInsightAgent' — agent\n  slack: novatech/facilities-ops\n  permission: propose-only",
+    );
+  });
+});

package/src/subsystem/formatDeclaration.ts

@@ -45,6 +45,19 @@ export function generateDeclarationString(component: SubsystemComponent): string
     case 'external':
       // Not valid TypeScript — caller should handle formatting.
       return `external '${detail?.kind === 'external' ? detail.label : name}'`;
+    case 'custom_entity':
+      // An actor, not code — no declaration to generate. Renders as a
+      // non-TypeScript block: `entity 'Name' — kind` followed by the authored
+      // attributes (key: value) indented beneath. Not valid TS — callers
+      // bypass Prettier.
+    {
+      const kindLabel = component.entityKind ? ` — ${component.entityKind}` : '';
+      const attrs = detail?.kind === 'custom_entity' ? detail.attributes : [];
+      const attrLines = attrs.map((a) => `  ${a.key}: ${a.value}`).join('\n');
+      return attrLines
+        ? `entity '${name}'${kindLabel}\n${attrLines}`
+        : `entity '${name}'${kindLabel}`;
+    }
     default:
       return `${construct} ${name}`;
   }

package/src/subsystem/model.test.ts

@@ -93,6 +93,8 @@ describe('subsystem graph model', () => {
     // falls back to existing name when no symbol (class stays bare).
     expect(deriveNameFromSymbol(undefined, 'class', 'SessionReader')).toBe('SessionReader');
     expect(deriveNameFromSymbol('', 'external', 'principal-studio-host')).toBe('principal-studio-host');
+    // custom entities render bare — no decoration, name is the identity
+    expect(deriveNameFromSymbol(undefined, 'custom_entity', 'FacilitiesTechnician')).toBe('FacilitiesTechnician');
   });
 
   test('executable constructs wear () on the node', () => {
@@ -127,6 +129,13 @@ describe('subsystem graph model', () => {
     expect(constructBadgeLabel({ construct: 'function', stereotype: 'hook' })).toBe('hook');
     expect(constructBadgeLabel({ construct: 'function' })).toBe('function');
     expect(constructBadgeLabel({ construct: 'type_alias' })).toBe('type alias');
+    // custom entities wear their entityKind as the badge
+    expect(
+      constructBadgeLabel({ construct: 'custom_entity', entityKind: 'Person' }),
+    ).toBe('Person');
+    expect(
+      constructBadgeLabel({ construct: 'custom_entity' }),
+    ).toBe('custom_entity');
   });
 
   test('nodeMinWidthForBadges widens for long construct badges and role pairs', () => {

package/src/subsystem/model.ts

@@ -30,7 +30,8 @@ export type SubsystemComponentConstruct =
   | 'enum'
   | 'module'
   | 'store'
-  | 'external';
+  | 'external'
+  | 'custom_entity';
 
 /**
  * Semantic role — where the node sits in the topology, orthogonal to
@@ -145,6 +146,22 @@ export interface SubsystemComponent {
    * a React UI unit reads as "component" rather than "function".
    */
   stereotype?: SubsystemStereotype;
+  /**
+   * Open-string entity kind for `construct: 'custom_entity'` nodes — what the
+   * actor/entity is (e.g. `Person`, `agent`, `queue`). Not code; there is no
+   * graphify anchor. Contrast with `construct` (what the declaration is) and
+   * `role` (where it sits topologically). Empty/unset for code constructs.
+   */
+  entityKind?: string;
+  /**
+   * Authored color override for the node border + badges, when the themed
+   * construct color isn't wanted. Primarily for `construct: 'custom_entity'`
+   * (an author picks a fitting hue for a Person/agent/queue) — but usable on
+   * any construct. Any `#rrggbb` string; when set it wins over the
+   * construct-derived color, mirrors in the declaration panel. Leave unset to
+   * inherit the Pierre construct palette.
+   */
+  color?: string;
   /**
    * Runtime process membership — which deployment unit this node is a
    * member of (e.g. `principal-studio/host`, `principal-studio/renderer`). Nodes
@@ -512,13 +529,18 @@ export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
  * Primary badge text for a node: prefer framework stereotype over the
  * language construct so a React UI unit reads as "component" / "hook"
  * rather than "function". When both framework and stereotype are set,
- * show `framework · stereotype` (e.g. `react · component`).
+ * show `framework · stereotype` (e.g. `react · component`). A custom
+ * entity wears its `entityKind` (Person/agent/queue) as the badge.
  */
 export function constructBadgeLabel(component: {
   construct: SubsystemComponentConstruct;
   framework?: string;
   stereotype?: string;
+  entityKind?: string;
 }): string {
+  if (component.construct === 'custom_entity' && component.entityKind) {
+    return component.entityKind;
+  }
   const constructLabel =
     component.construct === 'type_alias' ? 'type alias' : component.construct;
   if (component.stereotype && component.framework) {
@@ -554,6 +576,7 @@ export function nodeMinWidthForBadges(component: {
   framework?: string;
   stereotype?: string;
   role?: SubsystemComponentRole;
+  entityKind?: string;
 }): number {
   const left = estimateBadgeLabelWidth(constructBadgeLabel(component));
   if (component.role == null) {

package/src/subsystem/nodes.tsx

@@ -30,7 +30,7 @@ import {
   type SubsystemGroupNodeData,
   type SubsystemGraphEdge,
 } from './model';
-import { constructColorsFromPierreTheme } from '../pierre/constructColors';
+import { componentColor } from '../pierre/constructColors';
 import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
 
 export const CONSTRUCT_LABEL: Record<string, string> = {
@@ -43,6 +43,7 @@ export const CONSTRUCT_LABEL: Record<string, string> = {
   module: 'module',
   store: 'store',
   external: 'external',
+  custom_entity: 'entity',
 };
 
 /** Insert zero-width spaces at identifier word boundaries so long names wrap
@@ -83,8 +84,8 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   // 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];
+  // come later. A component-authored `color` override wins over the construct.
+  const color = componentColor(c, resolvePierreSyntaxThemeName(mode));
   const [hover, setHover] = useState(false);
   const configuredMax = SUBSYSTEM_CALLBACKS.maxNodeWidth;
   const maxWidth = configuredMax ?? 300;

package/src/subsystem/tokenizeComponent.ts

@@ -57,6 +57,11 @@ export async function tokenizeComponent(
     return tokenizeFormatted(`external '${escaped}'`, themeName);
   }
 
+  // Custom entity — an actor (Person/agent/queue), not code; bypass Prettier.
+  if (kind === 'custom_entity') {
+    return tokenizeFormatted(generateDeclarationString(component), themeName);
+  }
+
   // Generate → format → tokenize
   const raw = generateDeclarationString(component);
   const { prettier, plugins } = await getPrettier();