@principal-ai/subsystems-react 0.55.0 → 0.55.2

package/src/index.ts

@@ -74,6 +74,7 @@ export {
   extractNamedTypes,
   extractGraphifySignature,
   compareSignatures,
+  toSymbolFocusedView,
 } from './graphify';
 export type {
   ComponentAnchorInput,
@@ -83,6 +84,9 @@ export type {
   GraphifyInferredSignature,
   ClaimedSignature,
   SignatureCompareResult,
+  SymbolFocusedViewInput,
+  SymbolFocusedViewOptions,
+  SymbolFocusedViewGraph,
 } from './graphify';
 
 // ELK layout utilities
@@ -101,6 +105,8 @@ export type { UseElkLayoutOptions, UseElkLayoutResult } from './hooks/useElkLayo
 // Subsystem component graph
 export { SubsystemComponentGraph } from './subsystem/SubsystemComponentGraph';
 export type { SubsystemComponentGraphProps, TrailViewerContext } from './subsystem/SubsystemComponentGraph';
+export { SymbolFocusedView } from './subsystem/SymbolFocusedView';
+export type { SymbolFocusedViewProps } from './subsystem/SymbolFocusedView';
 export { SubsystemModelTransition } from './subsystem/SubsystemModelTransition';
 export type {
   SubsystemModelTransitionProps,
@@ -235,6 +241,7 @@ export type {
   SubsystemEdgeMechanism,
   SubsystemEdgeView,
   SubsystemEdgeProvenance,
+  SubsystemLayoutDirection,
   SubsystemGraphifyRelation,
   SubsystemConstructDeclaration,
   SubsystemDeclarationProvenance,
@@ -314,13 +321,13 @@ export type {
   SubsystemSourceSpan,
   SubsystemOpenFileOptions,
   SpanFreshness,
-} from './subsystem/declarationRef';
+} from './subsystem/sourceSpan';
 export {
   parseSourceLocation,
   normalizeDeclarationLine,
   extractDeclarationLine,
   DECLARATION_HASH_ALGO,
-} from './subsystem/declarationRef';
+} from './subsystem/sourceSpan';
 export {
   setPrettierProvider,
   getPrettierProvider,

package/src/pierre/PierreTrailCodeView.tsx

@@ -38,7 +38,7 @@ import type {
   SubsystemTrail,
   SubsystemTrailStep,
 } from '../subsystem/model';
-import type { SubsystemOpenFileOptions } from '../subsystem/declarationRef';
+import type { SubsystemOpenFileOptions } from '../subsystem/sourceSpan';
 import { buildPierreOptions, PIERRE_FILE_STYLE } from './pierreBackground';
 import { pierreLangForPath } from './pierreFileLang';
 import { resolvePierreSyntaxThemeName } from './pierreSyntaxTheme';

package/src/stories/{Subsystem/AggregateGraph → Canvases/Aggregate}/AggregateFrameGraph.stories.tsx

@@ -10,7 +10,7 @@ import {
 } from './aggregateViewFixture';
 
 const meta = {
-  title: 'Subsystem/AggregateGraph/AggregateFrameGraph',
+  title: 'Canvases/Aggregate/AggregateFrameGraph',
   component: SubsystemAggregateGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{Subsystem/C4Graph → Canvases/C4}/C4CardGrow.stories.tsx

@@ -5,7 +5,7 @@ import { C4NodeCard, NODE_W, NODE_H } from '../../../subsystem/C4NodeCard';
 import type { C4Container, C4Component } from '../../../subsystem/c4';
 
 const meta = {
-  title: 'Subsystem/C4Graph/C4CardGrow',
+  title: 'Canvases/C4/C4CardGrow',
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],
   decorators: [

package/src/stories/{Subsystem/C4Graph → Canvases/C4}/C4Component.stories.tsx

@@ -6,7 +6,7 @@ import { C4Graph } from '../../../subsystem/C4Graph';
 import type { C4Edge, C4Model, C4Element, C4Component, C4Container } from '../../../subsystem/c4';
 
 const meta = {
-  title: 'Subsystem/C4Graph/C4Component',
+  title: 'Canvases/C4/C4Component',
   component: C4Graph,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/C4Graph → Canvases/C4}/C4Container.stories.tsx

@@ -6,7 +6,7 @@ import { C4Graph } from '../../../subsystem/C4Graph';
 import type { C4Edge, C4Model, C4Element, C4Container } from '../../../subsystem/c4';
 
 const meta = {
-  title: 'Subsystem/C4Graph/C4Container',
+  title: 'Canvases/C4/C4Container',
   component: C4Graph,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/C4Graph → Canvases/C4}/C4NodeGallery.stories.tsx

@@ -31,7 +31,7 @@ import type { C4Element } from '../../../subsystem/c4';
 // ---------------------------------------------------------------------------
 
 const meta = {
-  title: 'Subsystem/C4Graph/C4NodeGallery',
+  title: 'Canvases/C4/C4NodeGallery',
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],
   decorators: [

package/src/stories/{Subsystem/C4Graph → Canvases/C4}/C4ToComponentDrill.stories.tsx

@@ -68,7 +68,7 @@ const MODEL_DESCRIPTION =
  */
 
 const meta = {
-  title: 'Subsystem/C4Graph/C4ToComponentDrill',
+  title: 'Canvases/C4/C4ToComponentDrill',
   component: C4Graph,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/C4Graph → Canvases/C4}/C4Transition.stories.tsx

@@ -6,7 +6,7 @@ import { C4Graph } from '../../../subsystem/C4Graph';
 import type { C4Edge, C4Model, C4Element, C4Component, C4Container } from '../../../subsystem/c4';
 
 const meta = {
-  title: 'Subsystem/C4Graph/C4Transition',
+  title: 'Canvases/C4/C4Transition',
   component: C4Graph,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/AnimatedProgression.stories.tsx

@@ -14,7 +14,7 @@ import type { SubsystemComponent, SubsystemTrail } from '../../../subsystem/mode
  */
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Animated progression',
+  title: 'Canvases/Subsystem/Animated progression',
   component: SubsystemComponentGraph,
   parameters: { layout: 'fullscreen' },
 } satisfies Meta<typeof SubsystemComponentGraph>;

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Appearance.stories.tsx

@@ -8,7 +8,7 @@ import type { GraphifyComponentDetail } from '../../../graphify';
 import { investigateOnlyComponents, investigateOnlyTrails } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Appearance',
+  title: 'Canvases/Subsystem/Appearance',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Basics.stories.tsx

@@ -7,7 +7,7 @@ import type { SubsystemComponent, SubsystemComponentEdge } from '../../../subsys
 import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Basics',
+  title: 'Canvases/Subsystem/Basics',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Captures.stories.tsx

@@ -8,7 +8,7 @@ import type { GraphifyComponentDetail } from '../../../graphify';
 import { components, graphSpecFromSteps, readerDetail, investigateOnlyComponents, investigateOnlyTrails } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Captures',
+  title: 'Canvases/Subsystem/Captures',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Constructs.stories.tsx

@@ -5,11 +5,11 @@ import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import { PierreFileView, PierreSnippetView } from '../../../pierre';
 import type { SubsystemComponent } from '../../../subsystem/model';
-import type { SubsystemOpenFileOptions } from '../../../subsystem/declarationRef';
+import type { SubsystemOpenFileOptions } from '../../../subsystem/sourceSpan';
 import type { GraphifyComponentDetail } from '../../../graphify';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Constructs',
+  title: 'Canvases/Subsystem/Constructs',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/CustomEntities.stories.tsx

@@ -155,7 +155,7 @@ const entityGraph = graphSpecFromSteps([
 ]);
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/CustomEntities',
+  title: 'Canvases/Subsystem/CustomEntities',
   component: SubsystemComponentGraph,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Deprecated.stories.tsx

@@ -17,7 +17,7 @@ import { trailFromSteps } from './fixtures';
  * as siblings — proposed = not built yet, deprecated = built once, removed since.
  */
 const meta = {
-  title: 'Subsystem/ComponentGraph/Deprecated',
+  title: 'Canvases/Subsystem/Deprecated',
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],
   decorators: [

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/DetailPanel.stories.tsx

@@ -5,14 +5,14 @@ import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import { PierreFileView, PierreSnippetView } from '../../../pierre';
 import type { SubsystemComponent, SubsystemComponentEdge } from '../../../subsystem/model';
-import type { SubsystemOpenFileOptions } from '../../../subsystem/declarationRef';
+import type { SubsystemOpenFileOptions } from '../../../subsystem/sourceSpan';
 import type { GraphifyComponentDetail } from '../../../graphify';
 import componentDeclarationSource from '../../../subsystem/ComponentDeclaration.tsx?raw';
 import resolveSource from '../../../graphify/resolve.ts?raw';
 import { readerDetail } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/DetailPanel',
+  title: 'Canvases/Subsystem/DetailPanel',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Diagnostics.stories.tsx

@@ -10,7 +10,7 @@ import {
 import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Diagnostics',
+  title: 'Canvases/Subsystem/Diagnostics',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/EdgeViews.stories.tsx

@@ -7,7 +7,7 @@ import type { SubsystemEdgeView, SubsystemGraphifyRelation } from '../../../subs
 import { components, trailFromSteps } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/EdgeViews',
+  title: 'Canvases/Subsystem/EdgeViews',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/FrameworkStereotype.stories.tsx

@@ -6,7 +6,7 @@ import type { SubsystemComponent } from '../../../subsystem/model';
 import { trailFromSteps } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/FrameworkStereotype',
+  title: 'Canvases/Subsystem/FrameworkStereotype',
   component: SubsystemComponentGraph,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/GraphTitle.stories.tsx

@@ -6,7 +6,7 @@ import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGr
 import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/GraphTitle',
+  title: 'Canvases/Subsystem/GraphTitle',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Issues.stories.tsx

@@ -10,7 +10,7 @@ import type { C4Container } from '../../../subsystem/c4';
 import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Issues',
+  title: 'Canvases/Subsystem/Issues',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/Canvases/Subsystem/LayoutDirection.stories.tsx

@@ -0,0 +1,122 @@
+/**
+ * Layout direction — the canvas toggle flips the layered layout between
+ * left-to-right and top-to-bottom.
+ *
+ * The flip is sequenced: edges fade out, ELK re-lays out while the nodes slide
+ * to their new slots, then the edges fade back in. Old routes never cut across
+ * the new layout mid-flight. The camera refits when the new layout lands
+ * (`refocusOnLayoutFlip`, on by default) — a vertical graph grows
+ * downward and would otherwise leave most of itself off-screen.
+ */
+import React, { useState } 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 { SubsystemLayoutDirection } from '../../../subsystem/model';
+import { components, graphSpecFromSteps } from './fixtures';
+
+const meta = {
+  title: 'Canvases/Subsystem/LayoutDirection',
+  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>;
+
+// A graph with enough layers to make the axis obvious: two producers fan into
+// a service, which writes to a store and produces an event.
+const layoutComponents = components([
+  ['api', 'ApiHandler', 'function', 'src/api/handler.ts', 'pkg:github/principal-ai/agent-monitoring', 'HTTP entry point', 'handleRequest'],
+  ['cli', 'CliHandler', 'function', 'src/cli/handler.ts', 'pkg:github/principal-ai/agent-monitoring', 'command entry point', 'handleCommand'],
+  ['svc', 'SessionService', 'class', 'src/session/SessionService.ts', 'pkg:github/principal-ai/agent-monitoring', 'owns session persistence', 'SessionService'],
+  ['store', 'SessionStore', 'class', 'src/session/SessionStore.ts', 'pkg:github/principal-ai/agent-monitoring', 'retained session state', 'SessionStore'],
+  ['event', 'SessionEvent', 'interface', 'src/types/SessionEvent.ts', 'pkg:github/principal-ai/agent-monitoring', 'output event shape', 'SessionEvent'],
+]);
+
+const layoutSpec = graphSpecFromSteps([
+  ['api', 'svc', 'calls', 'src/api/handler.ts', 42],
+  ['cli', 'svc', 'calls', 'src/cli/handler.ts', 18],
+  ['svc', 'store', 'writes', 'src/session/SessionService.ts', 88],
+  ['svc', 'event', 'produces', 'src/session/SessionService.ts', 95],
+]);
+
+function DirectionDemo({ initial }: { initial: SubsystemLayoutDirection }) {
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <SubsystemComponentGraph
+        components={layoutComponents}
+        trails={layoutSpec.trails}
+        defaultLayoutDirection={initial}
+        showEdgeLabels
+      />
+    </div>
+  );
+}
+
+/** Left-to-right (the default). Click the corner toggle to watch the flip. */
+export const Horizontal: Story = {
+  render: () => <DirectionDemo initial="horizontal" />,
+};
+
+/** Seeded top-to-bottom. The toggle restores the remembered choice per `persistKey`. */
+export const Vertical: Story = {
+  render: () => <DirectionDemo initial="vertical" />,
+};
+
+/**
+ * Host-controlled: the graph renders no built-in toggle; the host owns the
+ * value and echoes it back through `onLayoutDirectionChange`.
+ */
+function ControlledDemo() {
+  const [direction, setDirection] = useState<SubsystemLayoutDirection>('horizontal');
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <div style={{ display: 'flex', gap: 8, padding: 8, background: defaultEditorTheme.colors.background }}>
+        {(['horizontal', 'vertical'] as const).map((d) => (
+          <button
+            key={d}
+            type="button"
+            onClick={() => setDirection(d)}
+            aria-pressed={direction === d}
+            style={{
+              padding: '4px 10px',
+              borderRadius: 6,
+              border: `1px solid ${defaultEditorTheme.colors.border}`,
+              background: direction === d ? defaultEditorTheme.colors.border : 'transparent',
+              color: defaultEditorTheme.colors.text,
+              fontFamily: defaultEditorTheme.fonts.monospace,
+              fontSize: 12,
+              cursor: 'pointer',
+            }}
+          >
+            {d}
+          </button>
+        ))}
+      </div>
+      <div style={{ flex: 1, minHeight: 0 }}>
+        <SubsystemComponentGraph
+          components={layoutComponents}
+          trails={layoutSpec.trails}
+          layoutDirection={direction}
+          onLayoutDirectionChange={setDirection}
+          hideLayoutToggle
+          showEdgeLabels
+        />
+      </div>
+    </div>
+  );
+}
+
+export const ControlledByHost: Story = {
+  render: () => <ControlledDemo />,
+};

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/ModuleBadges.stories.tsx

@@ -12,7 +12,7 @@ import type {
 import { graphSpecFromSteps } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/ModuleBadges',
+  title: 'Canvases/Subsystem/ModuleBadges',
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],
   decorators: [

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/ModulePathNesting.stories.tsx

@@ -15,7 +15,7 @@ import type { SubsystemComponent } from '../../../subsystem/model';
  */
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Module path nesting',
+  title: 'Canvases/Subsystem/Module path nesting',
   component: SubsystemComponentGraph,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Modules.stories.tsx

@@ -6,7 +6,7 @@ import type { SubsystemComponent } from '../../../subsystem/model';
 import { graphSpecFromSteps } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Modules',
+  title: 'Canvases/Subsystem/Modules',
   component: SubsystemComponentGraph,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/NodeAnatomy.stories.tsx

@@ -24,7 +24,7 @@ import type {
  * still proposals.
  */
 const meta = {
-  title: 'Subsystem/ComponentGraph/NodeAnatomy',
+  title: 'Canvases/Subsystem/NodeAnatomy',
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],
   decorators: [

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Packages.stories.tsx

@@ -6,7 +6,7 @@ import type { SubsystemComponent } from '../../../subsystem/model';
 import { graphSpecFromSteps } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Packages',
+  title: 'Canvases/Subsystem/Packages',
   component: SubsystemComponentGraph,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Processes.stories.tsx

@@ -5,7 +5,7 @@ import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGr
 import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Processes',
+  title: 'Canvases/Subsystem/Processes',
   component: SubsystemComponentGraph,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Proposed.stories.tsx

@@ -12,7 +12,7 @@ import type {
 import { trailFromSteps } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Proposed',
+  title: 'Canvases/Subsystem/Proposed',
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],
   decorators: [

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/ProposedTrails.stories.tsx

@@ -6,7 +6,7 @@ import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGr
 import type { SubsystemComponent, SubsystemTrail } from '../../../subsystem/model';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/ProposedTrails',
+  title: 'Canvases/Subsystem/ProposedTrails',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Reorder.stories.tsx

@@ -7,7 +7,7 @@ import { TrailsPanel } from '../../../subsystem/TrailsPanel';
 import type { SubsystemComponent, SubsystemTrail } from '../../../subsystem/model';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Reorder',
+  title: 'Canvases/Subsystem/Reorder',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Scenarios.stories.tsx

@@ -12,7 +12,7 @@ import type { GraphifyComponentDetail } from '../../../graphify';
 import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Scenarios',
+  title: 'Canvases/Subsystem/Scenarios',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Spotlights.stories.tsx

@@ -17,7 +17,7 @@ import { resolvePierreSyntaxThemeName } from '../../../pierre/pierreSyntaxTheme'
 import { useTheme } from '@principal-ade/industry-theme';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Spotlights',
+  title: 'Canvases/Subsystem/Spotlights',
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],
   decorators: [

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/StoreValueType.stories.tsx

@@ -23,7 +23,7 @@ import type { SubsystemComponent, SubsystemGraphNode } from '../../../subsystem/
  * accessor shows the accessor's name instead of the state's.
  */
 const meta = {
-  title: 'Subsystem/ComponentGraph/StoreValueType',
+  title: 'Canvases/Subsystem/StoreValueType',
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],
   decorators: [

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/TrailAutoplay.stories.tsx

@@ -16,7 +16,7 @@ import type { SubsystemComponent, SubsystemTrail } from '../../../subsystem/mode
  * camera today. This story exists to expose that gap and iterate on it.
  */
 const meta = {
-  title: 'Subsystem/ComponentGraph/TrailAutoplay',
+  title: 'Canvases/Subsystem/TrailAutoplay',
   component: SubsystemComponentGraph,
   parameters: { layout: 'fullscreen' },
   tags: ['autodocs'],

package/src/stories/{Subsystem/ComponentGraph → Canvases/Subsystem}/Trails.stories.tsx

@@ -8,7 +8,7 @@ import { PierreTrailCodeView } from '../../../pierre';
 import type { TrailViewerContext } from '../../../subsystem/SubsystemComponentGraph';
 
 const meta = {
-  title: 'Subsystem/ComponentGraph/Trails',
+  title: 'Canvases/Subsystem/Trails',
   component: SubsystemComponentGraph,
   parameters: {
     layout: 'fullscreen',
@@ -272,6 +272,82 @@ const proposedTrails: SubsystemTrail[] = [
       },
     ],
   },
+  // Neighbours for the wrapped title above: a couple of one-line titles and
+  // one that wraps to two, so the header's padding reads against the rows on
+  // either side of it rather than in isolation.
+  {
+    id: 'tl-open-drawing',
+    title: 'Open drawing',
+    steps: [
+      {
+        from: 'panel',
+        to: 'host',
+        mechanism: 'produces',
+        file: 'src/panels/DrawingsLeftPanel.tsx',
+        span: { startLine: 85, endLine: 85, contentHash: 'fixture' },
+        purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'),
+        symbol: 'DrawingsLeftPanel.openDrawing',
+        annotation: 'Emits the open intent up to the host.',
+      },
+      {
+        from: 'host',
+        to: 'storage',
+        mechanism: 'calls',
+        file: 'src/hooks/useDrawingsHost.ts',
+        span: { startLine: 45, endLine: 45, contentHash: 'fixture' },
+        purl: stepPurl('src/hooks/useDrawingsHost.ts'),
+        symbol: 'useDrawingsHost.openDrawing',
+      },
+    ],
+  },
+  {
+    id: 'tl-save-drawing',
+    title: 'Save the drawing and refresh the list',
+    steps: [
+      {
+        from: 'tab',
+        to: 'fs',
+        mechanism: 'calls',
+        file: 'src/components/DrawingTabContent.tsx',
+        span: { startLine: 112, endLine: 112, contentHash: 'fixture' },
+        purl: stepPurl('src/components/DrawingTabContent.tsx'),
+        symbol: 'DrawingTabContent.save',
+      },
+      {
+        from: 'host',
+        to: 'panel',
+        mechanism: 'produces',
+        file: 'src/hooks/useDrawingsHost.ts',
+        span: { startLine: 64, endLine: 64, contentHash: 'fixture' },
+        purl: stepPurl('src/hooks/useDrawingsHost.ts'),
+        symbol: 'useDrawingsHost.onSaved',
+      },
+    ],
+  },
+  {
+    id: 'tl-delete-drawing',
+    title: 'Delete drawing',
+    steps: [
+      {
+        from: 'host',
+        to: 'fs',
+        mechanism: 'calls',
+        file: 'src/hooks/useDrawingsHost.ts',
+        span: { startLine: 66, endLine: 66, contentHash: 'fixture' },
+        purl: stepPurl('src/hooks/useDrawingsHost.ts'),
+        symbol: 'useDrawingsHost.deleteDrawing',
+      },
+      {
+        from: 'panel',
+        to: 'storage',
+        mechanism: 'calls',
+        file: 'src/panels/DrawingsLeftPanel.tsx',
+        span: { startLine: 56, endLine: 56, contentHash: 'fixture' },
+        purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'),
+        symbol: 'DrawingsLeftPanel.scan',
+      },
+    ],
+  },
 ];
 
 function ProposedMissingStepDemo() {
@@ -306,7 +382,7 @@ function ProposedMissingStepDemo() {
         components={proposedComponents}
         trails={proposedTrails}
         title="proposed seam with a missing file"
-        description="Expand **Associate a finished run with its model** and click either step. The proposed step has no file in the checkout, so its snippet shows an inline *Proposed — … isn't in the local checkout yet.* placeholder instead of failing the whole flow."
+        description="The **Trails** panel lists four flows so the long, wrapped title (*Associate a finished run with its model (proposed)*) reads against its neighbours — two one-line titles and one (*Save the drawing and refresh the list*) that also wraps. Expand **Associate a finished run with its model** and click either step: the proposed step has no file in the checkout, so its snippet shows an inline *Proposed — … isn't in the local checkout yet.* placeholder instead of failing the whole flow."
         renderTrailViewer={renderTrailViewer}
         renderFileViewer={(file) => (
           <div