@principal-ai/subsystems-react 0.52.0 → 0.53.1

package/src/subsystem/model.ts

@@ -8,8 +8,9 @@
  * subgraphs, only cross-package edges leave the box, and shared seams
  * (registries/barrels/facades) are edge targets, never member nodes.
  *
- * Self-contained in this package (not yet promoted to `@principal-ai/core`), so
- * we can iterate on the UI + story without publishing a dependency.
+ * Document types come from `@principal-ai/subsystems-core` (the portable
+ * standard's home); react layers display concerns (edges, regions, layout)
+ * on top.
  */
 
 import {
@@ -22,9 +23,7 @@ import { EDGE_LABEL_SIDE_PADDING, EDGE_ARROW_INSET } from '../utils/edgeLabel';
 import type { GraphifyComponentDetail } from '../graphify';
 import type {
   SubsystemConstructDeclaration,
-  SubsystemComponentRemoval,
 } from '@principal-ai/subsystems-core';
-import type { SubsystemDeclarationRef } from './declarationRef';
 import { purlOwnerName, purlRepoKey } from './paths';
 
 /**
@@ -55,7 +54,6 @@ export type { SubsystemConstructDeclaration } from '@principal-ai/subsystems-cor
 export type AnyComponentDetail =
   | SubsystemConstructDeclaration
   | GraphifyComponentDetail;
-export type SubsystemDeclarationProvenance = 'verified' | 'authored';
 
 /** One declared parameter in an agent-extracted (augmented) signature. */
 export interface SubsystemSignatureParameter {
@@ -78,84 +76,60 @@ export interface SubsystemSignatureClaim {
   returnType?: string;
 }
 
-export type SubsystemComponentConstruct =
-  | 'class'
-  | 'function'
-  | 'method'
-  | 'interface'
-  | 'type_alias'
-  | 'enum'
-  | 'store'
-  | 'external'
-  | 'custom_entity';
-
-/**
- * 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';
-
 /**
- * Framework that owns a stereotype vocabulary (open string).
- * Examples: `react`, `vue`, `nestjs`, `django`, `spring`.
- * Empty when the node is language-only / framework-agnostic.
+ * Document vocabulary — imported from `@principal-ai/subsystems-core`, the
+ * portable standard's home. This package used to define a parallel copy
+ * ("self-contained until promoted"); core owns the types now, so react
+ * re-exports them by construction instead of hand-mirroring.
  */
-export type SubsystemFramework = string;
+import type {
+  SubsystemModelDocument,
+  SubsystemTrail,
+  SubsystemTrailStep,
+  SubsystemComponentRole,
+  SubsystemTrailMechanism,
+  SubsystemEdgeMechanism,
+  SubsystemConstruct as SubsystemComponentConstruct,
+  SubsystemComponent as CoreSubsystemComponent,
+} from '@principal-ai/subsystems-core';
+import {
+  getSubsystemProcessRegions as coreGetSubsystemProcessRegions,
+  getSubsystemModuleRegions as coreGetSubsystemModuleRegions,
+} from '@principal-ai/subsystems-core';
 
+export type {
+  SubsystemModelDocument,
+  SubsystemTrail,
+  SubsystemTrailStep,
+  SubsystemComponentRole,
+  SubsystemFramework,
+  SubsystemStereotype,
+  SubsystemEntityKind,
+  SubsystemTrailMechanism,
+  SubsystemEdgeMechanism,
+  SubsystemDeclToken,
+  SubsystemDeclTokenKind,
+  SubsystemDeclarationProvenance,
+} from '@principal-ai/subsystems-core';
+export type { SubsystemComponentConstruct };
 /**
- * Framework-level pattern stamped on a language construct (open string).
- * Examples: `component`, `hook`, `middleware`, `controller`, `guard`.
- * Empty when no framework pattern applies. Pair with `framework` when set —
- * a React component stays `construct: 'function'` with
- * `framework: 'react'` + `stereotype: 'component'`.
+ * A component node — the named unit, construct-tagged; `file` is its location.
+ * Core's portable shape plus the one field a model document never carries:
+ * `signatureAugmentation` is host-enrichment (populated when serving an
+ * enriched graph), never persisted.
  */
-export type SubsystemStereotype = string;
-
-// ---------------------------------------------------------------------------
-// Declaration tokens — structured source representation
-// ---------------------------------------------------------------------------
-
-export type SubsystemDeclTokenKind =
-  | 'keyword'
-  | 'name'
-  | 'member'
-  | 'type'
-  | 'punctuation'
-  | 'string'
-  | 'newline';
-
-export interface SubsystemDeclToken {
-  text: string;
-  kind: SubsystemDeclTokenKind;
-  /** Shiki/Pierre foreground when tokenized client-side; omitted on legacy wire tokens. */
-  color?: string;
+export interface SubsystemComponent extends CoreSubsystemComponent {
+  /**
+   * Accepted agent-extracted signature (from the graphify augmentation store)
+   * confirming this function/method when Graphify has no usable signature
+   * edges. Populated by the host when serving an enriched graph — never
+   * persisted in the model document. Rendered as the declaration when the
+   * component has no own `declaration`; no marker distinguishes the source.
+   */
+  signatureAugmentation?: SubsystemSignatureClaim;
 }
 
-/**
- * Trail step mechanism — runtime seams with a `file:line` site.
- */
-export type SubsystemTrailMechanism =
-  | 'calls'
-  | 'uses'
-  | 'feeds'
-  | 'produces'
-  | 'writes'
-  | 'reads'
-  | 'watches'
-  | 'registers-into';
-
-/** Union for derived graph-edge styling — the trail step mechanism. */
-export type SubsystemEdgeMechanism = SubsystemTrailMechanism;
-
-/**
- * Which edge source the canvas draws. The two sources are disjoint; a view
+/** Which edge source the canvas draws. The two sources are disjoint; a view
  * shows only edges (and their labels) from the selected source.
  * - `graphify`: only graphify-native static edges (`imports`, `contains`, …)
  * - `trails`: only trail step edges (`calls`, `feeds`, …)
@@ -203,155 +177,10 @@ export interface SubsystemGraphifyRelation {
   context?: string;
 }
 
-/** A component node — the named unit, construct-tagged; `file` is its location. */
-export interface SubsystemComponent {
-  /**
-   * Model-local stable alias, unique per model. Referenced by trail
-   * `from` / `to`; edges point at the alias, not the location.
-   * Code identity (for composed multi-model views) lives on
-   * `purl` + `file` + `symbol`, not here.
-   */
-  alias: string;
-  name: string;
-  /**
-   * 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, framework + stereotype = which framework pattern
-   * it plays, role = where it sits, process = where it runs. Prefer
-   * `framework` + `stereotype` over inventing framework-specific constructs
-   * (a React component is still `construct: 'function'`).
-   */
-  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;
-  /**
-   * App/repo logo shown on the declaration card in place of the GitHub owner
-   * avatar (any image URL or data URI). Optional; typically one image stamped
-   * across the components of a repo.
-   */
-  logo?: string;
-  /** One-line purpose shown on the node. */
-  purpose?: string;
-  /**
-   * Design / migration placeholder — participates in edges and flows but is
-   * not a live source declaration yet. Verification skips source checks until
-   * promoted (`proposed` cleared, `file` + `symbol` filled). Orthogonal to
-   * `construct` (intended shape) and `role` (topology).
-   */
-  proposed?: boolean;
-  /**
-   * The claim was real but its source is gone upstream — deleted or renamed.
-   * The inverse of `proposed`; verification skips source checks the same way.
-   * Renders with a slate border and a `deprecated` badge that opens the removal
-   * provenance. Transitional — a cleanup pass removes the node.
-   */
-  deprecated?: boolean;
-  /** Which commit removed this claim's source, and why. Present when deprecated. */
-  removedIn?: SubsystemComponentRemoval;
-  /**
-   * 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;
-  /**
-   * Framework that owns the stereotype vocabulary (e.g. `react`, `nestjs`).
-   * Orthogonal to `construct` — leave empty for language-only units.
-   */
-  framework?: SubsystemFramework;
-  /**
-   * Framework pattern this declaration plays (e.g. `component`, `hook`).
-   * When set, the node badge prefers this label over the construct name so
-   * 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
-   * sharing a `process` are drawn inside one boundary region; nodes without
-   * one sit outside every process boundary (external actors, services,
-   * libraries). Orthogonal to `module` (source-file frame).
-   */
-  process?: string;
-  /**
-   * Source-module membership — which file/module this export belongs to
-   * (e.g. `src/session/transcript.ts`). Nodes sharing a `module` are drawn
-   * inside one boundary frame. Prefer this over inventing a module construct:
-   * each export keeps its real construct (`function` / `class` / …) and the
-   * file reads as a frame. Orthogonal to `process` (runtime deployment).
-   * When both are set, the module frame is the component's parent (finer
-   * grain); process framing still groups siblings that share a process.
-   */
-  module?: string;
-  /** A symbol this component exposes / is (the node's identity). */
-  symbol?: string;
-  /**
-   * Semantic layer/phase for the layout (e.g. `1` = input, `2` = processing,
-   * `3` = output). When set, ELK places the component in this layer so the
-   * graph reads as a left-to-right pipeline and *conveys the idea* rather than
-   * letting ELK guess the order.
-   */
-  layer?: number;
-  /**
-   * Structured declaration shape of the construct (params, members, type
-   * buckets, …). Single source of truth for the click panel — authored by
-   * agents/CLI or filled by verified graphify capture. Discriminated by kind.
-   */
-  declaration?: SubsystemConstructDeclaration;
-  /**
-   * @deprecated No longer used — verification now tracks at the model level
-   * via `verifiedAtCommits`. Keeping the field temporarily for migration.
-   */
-  declarationProvenance?: SubsystemDeclarationProvenance;
-  /**
-   * Pre-tokenized declaration for the detail panel. When present, the
-   * renderer skips client-side tokenization. Tokens are language-agnostic;
-   * a different language just needs a different tokenizer and text joiner.
-   */
-  tokens?: SubsystemDeclToken[];
-  /**
-   * Accepted agent-extracted signature (from the graphify augmentation store)
-   * confirming this function/method when Graphify has no usable signature
-   * edges. Populated by the host when serving an enriched graph — never
-   * persisted in the model document. Rendered as the declaration when the
-   * component has no own `declaration`; no marker distinguishes the source.
-   */
-  signatureAugmentation?: SubsystemSignatureClaim;
-  /**
-   * Anchored declaration location: graphify start line + hash of that line's
-   * content at capture time. Populated by verify when an exact anchor resolves.
-   */
-  declarationRef?: SubsystemDeclarationRef;
-}
-
 /**
  * Derived / display graph edge used by renderers. Built from trail steps
  * (and graphify-native relations) — not authored as its own document field.
+ * Richer than core's minimal edge: this is the canvas's drawing shape.
  */
 export interface SubsystemComponentEdge {
   id: string;
@@ -359,7 +188,7 @@ export interface SubsystemComponentEdge {
   to: string; // component alias or external target label
   /**
    * The edge verb. For `provenance: 'subsystem'` (the default) this is a
-   * `SubsystemEdgeMechanism`; for `provenance: 'graphify'` it is the raw
+   * `SubsystemTrailMechanism`; for `provenance: 'graphify'` it is the raw
    * graphify relation. Typed as `string` because the display edge is a derived
    * structure and graphify's verb set is open — the trail vocabulary
    * (`SubsystemTrailMechanism`) stays closed.
@@ -381,60 +210,6 @@ export interface SubsystemComponentEdge {
   context?: string;
 }
 
-/**
- * A single runtime step — `from`/`to`/`mechanism` plus the exact `file:line`
- * where that seam fires for a trail.
- */
-export interface SubsystemTrailStep {
-  from: string;
-  to: string;
-  mechanism: SubsystemTrailMechanism;
-  /** Repo-root-relative path of the file where the seam fires. */
-  file: string;
-  /** 1-based line of the site within `file`. */
-  line: number;
-  /**
-   * File-anchored purl of the seam site (e.g.
-   * `pkg:github/owner/name#path/to/file.ts`), mirroring component `purl`.
-   * Required: readers resolve the checkout from this instead of guessing
-   * the repo from the step's endpoint components.
-   */
-  purl: string;
-  /**
-   * Frame name for this step — the function/method on the stack at the site.
-   * Required; the Trails list shows this instead of a bare
-   * 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
-   * surfaces it in the annotation column next to the highlighted line.
-   */
-  annotation?: string;
-}
-
-/** An ordered runtime trail — one named behavior story. */
-export interface SubsystemTrail {
-  id: string;
-  title: string;
-  steps: SubsystemTrailStep[];
-}
-
-export interface SubsystemModelDocument {
-  components: SubsystemComponent[];
-  /** Ordered runtime trails (one per named behavior). */
-  trails?: SubsystemTrail[];
-}
-
 /** Stable id for a derived graph edge from a trail step. */
 export function derivedGraphEdgeId(
   from: string,
@@ -819,47 +594,29 @@ function packageRegionLabel(packageKey: string): string {
 
 /**
  * Derive process boundary regions — one per distinct non-empty `process`
- * value, in first-appearance order.
+ * value, in first-appearance order. Wraps core's rollup, adding the frame
+ * `kind` the canvas reads.
  */
 export function getSubsystemRegions(
   doc: Pick<SubsystemModelDocument, 'components'>,
 ): SubsystemProcessRegion[] {
-  const byProcess = new Map<string, string[]>();
-  for (const c of doc.components) {
-    const p = c.process?.trim();
-    if (!p) continue;
-    const list = byProcess.get(p) ?? [];
-    list.push(c.alias);
-    byProcess.set(p, list);
-  }
-  return [...byProcess.entries()].map(([key, memberAliases]) => ({
+  return coreGetSubsystemProcessRegions(doc).map((r) => ({
+    ...r,
     kind: 'process' as const,
-    key,
-    label: key,
-    memberAliases,
   }));
 }
 
 /**
  * Derive module boundary regions — one per distinct non-empty `module`
  * value, in first-appearance order. Label is the module path (file).
+ * Wraps core's rollup, adding the frame `kind` the canvas reads.
  */
 export function getSubsystemModuleRegions(
   doc: Pick<SubsystemModelDocument, 'components'>,
 ): SubsystemProcessRegion[] {
-  const byModule = new Map<string, string[]>();
-  for (const c of doc.components) {
-    const m = c.module?.trim();
-    if (!m) continue;
-    const list = byModule.get(m) ?? [];
-    list.push(c.alias);
-    byModule.set(m, list);
-  }
-  return [...byModule.entries()].map(([key, memberAliases]) => ({
+  return coreGetSubsystemModuleRegions(doc).map((r) => ({
+    ...r,
     kind: 'module' as const,
-    key,
-    label: key,
-    memberAliases,
   }));
 }
 
@@ -1933,7 +1690,7 @@ export function nodeMinWidthForBadges(component: {
  * then refines with compound layout.
  */
 export function convertSubsystemToNodes(
-  doc: SubsystemModelDocument,
+  doc: Pick<SubsystemModelDocument, 'components' | 'trails'>,
   opts: { maxNodeWidth?: number } = {},
 ): SubsystemGraphNode[] {
   const { maxNodeWidth } = opts;
@@ -2024,7 +1781,7 @@ export function convertSubsystemToGroups(
  * relationship is visible without a member node.
  */
 export function convertSubsystemToEdges(
-  doc: SubsystemModelDocument,
+  doc: Pick<SubsystemModelDocument, 'components' | 'trails'>,
   graphifyRelations: readonly SubsystemGraphifyRelation[] = [],
 ): SubsystemGraphEdge[] {
   const compAliases = new Set(doc.components.map((c) => c.alias));
@@ -2086,7 +1843,7 @@ export function subsystemGraphLayoutKey(
  * layered with minimized crossings.
  */
 export async function buildSubsystemGraph(
-  doc: SubsystemModelDocument,
+  doc: Pick<SubsystemModelDocument, 'components' | 'trails'>,
   opts: {
     maxNodeWidth?: number;
     showEdgeLabels?: boolean;

package/src/utils/elkLayout.ts

@@ -150,9 +150,16 @@ export interface ElkLayoutOptions {
    * decoration drawn around wherever the members landed.
    *
    * Only for groups whose members need no parent-relative positioning (C4's
-   * system frame). @default false
+   * system frame).
+   *
+   * A set names specific groups to flatten, leaving the rest as real ELK
+   * parents — the drill-down needs this, because the opened container must be
+   * *sized by ELK to fit its nested components* while the system frame around
+   * it stays decorative. Descendants of a flattened group are flattened too.
+   *
+   * @default false
    */
-  flatGroups?: boolean;
+  flatGroups?: boolean | ReadonlySet<string>;
 
   /**
    * ELK partition per node id. Nodes are banded by `partition` — ELK places all
@@ -520,6 +527,21 @@ export interface CompoundGroupDef {
   id: string;
   memberIds: string[];
   minWidth?: number;
+  /**
+   * ELK partition for this group. Partitioning is activated on the root and
+   * inherited, so a compound parent must be told its band explicitly —
+   * otherwise it falls to partition 0 and lays out away from the siblings it is
+   * supposed to sit among (which, for a flat frame around those siblings, drags
+   * the frame across an unrelated band).
+   */
+  partition?: number;
+  /**
+   * Space reserved above the first child, in px. Set it when the parent draws
+   * its own chrome at the top (C4's grown container draws a label slot and a
+   * technology row) so ELK still owns the fit — it pads the parent by this and
+   * the children land below the chrome rather than under it.
+   */
+  padTop?: number;
 }
 
 /** Which groups ELK builds, and which it drops. */
@@ -528,7 +550,7 @@ export interface CompoundGroupPlan {
    * Built groups in build order — a group's children always appear before it,
    * so callers can map ids to shells in one forward pass.
    */
-  built: Array<{ id: string; childIds: string[]; minWidth?: number }>;
+  built: Array<{ id: string; childIds: string[]; minWidth?: number; padTop?: number; partition?: number }>;
   /**
    * Dropped groups. Their members are promoted into the nearest built
    * ancestor, so callers must clear those members' `parentId`.
@@ -864,11 +886,27 @@ export async function computeElkLayout(
   // and the frame is synthesized from the members' bounds after layout. This
   // keeps every edge on one spacing instead of inheriting a nested frame's.
   const flatGroupIds = new Set<string>();
-  if (flatGroups) {
+  if (flatGroups === true) {
     for (const g of plan.built) flatGroupIds.add(g.id);
+  } else if (flatGroups) {
+    for (const g of plan.built) if (flatGroups.has(g.id)) flatGroupIds.add(g.id);
+    // A group inside a flat frame can't be an ELK parent either — its members
+    // lay out at the root alongside the frame's other members.
+    let grew = true;
+    while (grew) {
+      grew = false;
+      for (const g of plan.built) {
+        if (flatGroupIds.has(g.id)) continue;
+        const parentId = groupById.get(g.id)?.parentId;
+        if (parentId && flatGroupIds.has(parentId)) {
+          flatGroupIds.add(g.id);
+          grew = true;
+        }
+      }
+    }
   }
   for (const g of plan.built) {
-    if (flatGroups) break;
+    if (flatGroupIds.has(g.id)) continue;
     const children: ElkNode[] = [];
     for (const cid of g.childIds) {
       const leaf = elkById.get(cid);
@@ -878,14 +916,26 @@ export async function computeElkLayout(
         if (nested) children.push(nested);
       }
     }
+    const sizeOptions: Record<string, string> = {};
+    if (g.minWidth != null) {
+      // MINIMUM_SIZE, not a forced size: ELK grows the parent past it when the
+      // children need more, but never shrinks it below it.
+      sizeOptions['elk.nodeSize.constraints'] = 'MINIMUM_SIZE';
+      sizeOptions['elk.nodeSize.minimum'] = `(${g.minWidth},0)`;
+    }
+    if (g.padTop != null) {
+      // Reserving the parent's own chrome. Children then start below it, and
+      // the parent's height still comes from ELK's fit.
+      sizeOptions['elk.padding'] = `[top=${g.padTop},left=12,bottom=12,right=12]`;
+    }
+    if (g.partition != null) sizeOptions['partition'] = String(g.partition);
     builtGroups.set(g.id, {
       id: g.id,
       children,
-      layoutOptions: g.minWidth == null ? compoundLayoutOptions : {
-        ...compoundLayoutOptions,
-        'elk.nodeSize.constraints': 'MINIMUM_SIZE',
-        'elk.nodeSize.minimum': `(${g.minWidth},0)`,
-      },
+      layoutOptions:
+        Object.keys(sizeOptions).length > 0
+          ? { ...compoundLayoutOptions, ...sizeOptions }
+          : compoundLayoutOptions,
     });
   }