@principal-ai/subsystems-react 0.56.0 → 0.56.2

package/src/index.ts

@@ -227,43 +227,6 @@ export type {
   TrailStackView,
 } from './subsystem/trailStack';
 export { buildStepBrief } from './subsystem/trailBrief';
-export {
-  buildStepEmphasisMap,
-  emphasisForTrail,
-  emphasisKey,
-  findStepEmphasis,
-  orphanedEmphasis,
-  stepClaimKey,
-} from './subsystem/stepEmphasis';
-export type {
-  StepEmphasisDocument,
-  StepEmphasisMap,
-  StepEmphasisProvenance,
-  StepEmphasisRecord,
-} from './subsystem/stepEmphasis';
-export {
-  decorationModelIds,
-  decorationTrailId,
-  decorationTrailKey,
-  findDecorationTrail,
-  groupDecorationTrailsByModel,
-} from './subsystem/decoration';
-export type {
-  DecorationBaseTrailRef,
-  DecorationDraft,
-  DecorationDraftComponent,
-  DecorationDraftEdge,
-  DecorationDraftTrailRef,
-  DecorationProvenance,
-  DecorationStepAnchor,
-  DecorationTrailRef,
-  SubsystemDecoration,
-} from './subsystem/decoration';
-export { DecorationPanel } from './subsystem/DecorationPanel';
-export type {
-  DecorationPanelProps,
-  DecorationPanelTrailMeta,
-} from './subsystem/DecorationPanel';
 export { GraphLayoutCover } from './subsystem/GraphLayoutCover';
 export type { GraphLayoutCoverProps } from './subsystem/GraphLayoutCover';
 export {

package/src/pierre/PierreTrailCodeView.tsx

@@ -2,8 +2,8 @@
  * PierreTrailCodeView — multi-file step snippets via `@pierre/diffs` CodeView.
  *
  * Renders one sliced window per trail step in a single virtualized
- * scroll; when `stepIndex` changes, scrolls that step's site line into view
- * and highlights it via CodeView `selectedLines` (same mechanism as
+ * scroll; when `stepIndex` changes, scrolls that step's call into view
+ * and highlights its full range via CodeView `selectedLines` (same mechanism as
  * `PierreSnippetView`).
  */
 
@@ -46,9 +46,9 @@ import { resolveVisibleStepIndex, type VisibleStepRect } from './visibleStep';
 import { fileUnavailableNotice, isFileUnavailableError } from './fileAvailability';
 import {
   remapSnippetLineNumbers,
-  sliceSnippetWindow,
   type SnippetSlice,
 } from './sliceSnippet';
+import { sliceTrailStep, trailCallSelection } from './trailSnippet';
 
 /**
  * A token the user clicked or hovered inside a step's snippet. `stepIndex` is
@@ -88,7 +88,7 @@ export interface PierreTrailCodeViewProps {
   stepIndex: number | null;
   /** Read a step site; `purl` names the seam site's repo for checkout resolution. */
   readFile: (path: string, purl?: string) => Promise<string>;
-  /** Context lines above/below each step site; defaults to 8. */
+  /** Fallback context when a step has no caller construct span; defaults to 8. */
   contextLines?: number;
   /** Override Pierre's container background. */
   background?: string;
@@ -338,20 +338,7 @@ export function PierreTrailCodeView({
         );
       }
       const contents = load.byPath.get(key) ?? '';
-      // A resolved site construct is the frame the reader wants: show its
-      // whole declaration and focus the seam line inside it. Older models
-      // fall back to a context window around the seam.
-      const site = step.site?.span;
-      const start = site?.startLine ?? step.span?.startLine ?? 1;
-      const end = site?.endLine ?? step.span?.endLine ?? start;
-      const focus = step.span?.startLine ?? start;
-      return sliceSnippetWindow(
-        contents,
-        start,
-        end,
-        site ? 0 : contextLines,
-        focus,
-      );
+      return sliceTrailStep(contents, step, contextLines);
     });
   }, [load, trail.steps, contextLines]);
 
@@ -397,13 +384,17 @@ export function PierreTrailCodeView({
     if (stepIndex == null || stepIndex < 0 || stepIndex >= slices.length) {
       return null;
     }
-    const focus = slices[stepIndex]?.focusOffset;
-    if (focus == null) return null;
+    const step = trail.steps[stepIndex];
+    const slice = slices[stepIndex];
+    if (step == null || slice == null || load.status !== 'ready') return null;
+    if (load.unavailable.has(siteKey(step))) return null;
+    const range = trailCallSelection(step, slice);
+    if (range == null) return null;
     return {
       id: stepItemId(trail.id, stepIndex),
-      range: { start: focus, end: focus },
+      range,
     };
-  }, [stepIndex, slices, trail.id]);
+  }, [stepIndex, slices, trail.id, trail.steps, load]);
 
   const sliceStartByItemId = useMemo(() => {
     const map = new Map<string, number>();
@@ -464,7 +455,7 @@ export function PierreTrailCodeView({
           ) : (
             <>
               {step.site?.span
-                ? `L${step.site.span.startLine}-${step.site.span.endLine}`
+                ? `${step.site.symbol} · L${step.site.span.startLine}-${step.site.span.endLine}`
                 : `L${step.span?.startLine ?? '?'}`}
               {onOpenFile && (
                 <OpenFileHeaderButton

package/src/pierre/trailSnippet.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test';
+import type { SubsystemTrailStep } from '../subsystem/model';
+import { sliceTrailStep, trailCallSelection } from './trailSnippet';
+
+const contents = Array.from({ length: 100 }, (_, i) => `line ${i + 1}`).join('\n');
+const step: SubsystemTrailStep = {
+  from: 'caller',
+  to: 'callee',
+  mechanism: 'calls',
+  file: 'src/caller.ts',
+  purl: 'pkg:github/example/repo#src/caller.ts',
+  symbol: 'loadModel',
+  site: {
+    symbol: 'loadModel',
+    span: { startLine: 10, endLine: 70, contentHash: 'caller' },
+  },
+  span: { startLine: 35, endLine: 38, contentHash: 'call' },
+  target: {
+    file: 'src/callee.ts',
+    purl: 'pkg:github/example/repo#src/callee.ts',
+    symbol: 'readFile',
+    span: { startLine: 2, endLine: 8, contentHash: 'callee' },
+  },
+};
+
+describe('trail construct snippets', () => {
+  test('shows the full caller span without extra context, not the callee span', () => {
+    const slice = sliceTrailStep(contents, step, 8);
+    expect(slice.sliceStart).toBe(10);
+    expect(slice.sliceEnd).toBe(70);
+    expect(slice.contents).toBe(contents.split('\n').slice(9, 70).join('\n'));
+    expect(slice.focusOffset).toBe(26);
+  });
+
+  test('highlights every line of a multiline call inside the construct', () => {
+    const slice = sliceTrailStep(contents, step, 8);
+    expect(trailCallSelection(step, slice)).toEqual({ start: 26, end: 29 });
+  });
+
+  test('preserves single-line call highlighting', () => {
+    const single = { ...step, span: { ...step.span!, endLine: 35 } };
+    expect(trailCallSelection(single, sliceTrailStep(contents, single, 8)))
+      .toEqual({ start: 26, end: 26 });
+  });
+
+  test('keeps a context window for older steps without a site construct', () => {
+    const legacy = { ...step, site: undefined };
+    const slice = sliceTrailStep(contents, legacy, 8);
+    expect(slice.sliceStart).toBe(27);
+    expect(slice.sliceEnd).toBe(46);
+    expect(slice.focusOffset).toBe(9);
+    expect(trailCallSelection(legacy, slice)).toEqual({ start: 9, end: 12 });
+  });
+
+  test('does not highlight the declaration as a call when call evidence is missing', () => {
+    const unverified = { ...step, span: undefined };
+    const slice = sliceTrailStep(contents, unverified, 8);
+    expect(slice.sliceStart).toBe(10);
+    expect(slice.sliceEnd).toBe(70);
+    expect(slice.focusOffset).toBe(1);
+    expect(trailCallSelection(unverified, slice)).toBeNull();
+  });
+
+  test('clips stale call ranges to the displayed construct', () => {
+    const stale = { ...step, span: { ...step.span!, startLine: 68, endLine: 75 } };
+    expect(trailCallSelection(stale, sliceTrailStep(contents, stale, 8)))
+      .toEqual({ start: 59, end: 61 });
+  });
+
+  test('does not highlight unrelated lines when the call falls outside the construct', () => {
+    const stale = { ...step, span: { ...step.span!, startLine: 80, endLine: 82 } };
+    expect(trailCallSelection(stale, sliceTrailStep(contents, stale, 8))).toBeNull();
+  });
+});

package/src/pierre/trailSnippet.ts

@@ -0,0 +1,35 @@
+import type { SubsystemTrailStep } from '../subsystem/model';
+import { sliceSnippetWindow, type SnippetSlice } from './sliceSnippet';
+
+/** Show the caller's whole declaration, keeping focus on its call site. */
+export function sliceTrailStep(
+  contents: string,
+  step: SubsystemTrailStep,
+  contextLines: number,
+): SnippetSlice {
+  const site = step.site?.span;
+  const start = site?.startLine ?? step.span?.startLine ?? 1;
+  const end = site?.endLine ?? step.span?.endLine ?? start;
+  return sliceSnippetWindow(
+    contents,
+    start,
+    end,
+    site ? 0 : contextLines,
+    step.span?.startLine ?? start,
+  );
+}
+
+/** Convert the complete call range to snippet-local lines, never inventing evidence. */
+export function trailCallSelection(
+  step: SubsystemTrailStep,
+  slice: SnippetSlice,
+): { start: number; end: number } | null {
+  if (step.span == null) return null;
+  const start = Math.max(step.span.startLine, slice.sliceStart);
+  const end = Math.min(step.span.endLine, slice.sliceEnd);
+  if (start > end) return null;
+  return {
+    start: start - slice.sliceStart + 1,
+    end: end - slice.sliceStart + 1,
+  };
+}

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

@@ -12,8 +12,11 @@ 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 { SubsystemComponentGraph, type TrailViewerContext } from '../../../subsystem/SubsystemComponentGraph';
+import { PierreTrailCodeView } from '../../../pierre/PierreTrailCodeView';
+import { PierreFileView } from '../../../pierre/PierreFileView';
 import type { SubsystemLayoutDirection } from '../../../subsystem/model';
+import type { SubsystemOpenFileOptions } from '../../../subsystem/sourceSpan';
 import { components, graphSpecFromSteps } from './fixtures';
 
 const meta = {
@@ -50,13 +53,57 @@ const layoutSpec = graphSpecFromSteps([
   ['svc', 'event', 'produces', 'src/session/SessionService.ts', 95],
 ]);
 
-function DirectionDemo({ initial }: { initial: SubsystemLayoutDirection }) {
+const codeTrails = layoutSpec.trails.map((trail) => ({
+  ...trail,
+  steps: trail.steps.map((step) => ({
+    ...step,
+    site: {
+      symbol: step.symbol,
+      span: { startLine: 1, endLine: 110, contentHash: 'fixture' },
+    },
+  })),
+}));
+
+const codeSource = Array.from({ length: 110 }, (_, i) => {
+  if (i === 0) return 'export async function handleSession(request: Request) {';
+  if (i === 109) return '}';
+  if ([18, 42, 88, 95].includes(i + 1)) return '  await sessionService.save(request);';
+  return `  // Session processing, line ${i + 1}`;
+}).join('\n');
+const readCodeSource = async () => codeSource;
+
+function renderTrailCode({ trail, stepIndex, onOpenFile, onVisibleStepChange }: TrailViewerContext) {
+  return (
+    <PierreTrailCodeView
+      trail={trail}
+      stepIndex={stepIndex}
+      readFile={readCodeSource}
+      onOpenFile={onOpenFile}
+      onVisibleStepChange={onVisibleStepChange}
+    />
+  );
+}
+
+function renderCodeFile(file: string, opts?: SubsystemOpenFileOptions) {
+  return (
+    <PierreFileView
+      filePath={file}
+      fileName={file.split('/').pop() ?? file}
+      readFile={readCodeSource}
+      focusLine={opts?.startLine}
+    />
+  );
+}
+
+function DirectionDemo({ initial, withCode = false }: { initial: SubsystemLayoutDirection; withCode?: boolean }) {
   return (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={layoutComponents}
-        trails={layoutSpec.trails}
+        trails={withCode ? codeTrails : layoutSpec.trails}
         defaultLayoutDirection={initial}
+        renderTrailViewer={withCode ? renderTrailCode : undefined}
+        renderFileViewer={withCode ? renderCodeFile : undefined}
         showEdgeLabels
       />
     </div>
@@ -73,6 +120,11 @@ export const Vertical: Story = {
   render: () => <DirectionDemo initial="vertical" />,
 };
 
+/** Select a trail step, then flip the layout: code docks left vertically and bottom horizontally. */
+export const WithCodeView: Story = {
+  render: () => <DirectionDemo initial="vertical" withCode />,
+};
+
 /**
  * Host-controlled: the graph renders no built-in toggle; the host owns the
  * value and echoes it back through `onLayoutDirectionChange`.

package/src/subsystem/FileDrawer.test.tsx

@@ -0,0 +1,130 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import type { ComponentProps } from 'react';
+import { Window } from 'happy-dom';
+import { cleanup, fireEvent, render } from '@testing-library/react/pure';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { FileDrawer } from './FileDrawer';
+
+const dom = new Window();
+const globals = globalThis as unknown as Record<string, unknown>;
+globals.window = dom;
+globals.document = dom.document;
+globals.navigator = dom.navigator;
+globals.HTMLElement = dom.HTMLElement;
+globals.Node = dom.Node;
+globals.Element = dom.Element;
+globals.Event = dom.Event;
+globals.MouseEvent = dom.MouseEvent;
+globals.KeyboardEvent = dom.KeyboardEvent;
+globals.localStorage = dom.localStorage;
+globals.sessionStorage = dom.sessionStorage;
+globals.matchMedia = dom.matchMedia.bind(dom);
+globals.requestAnimationFrame = dom.requestAnimationFrame.bind(dom);
+globals.cancelAnimationFrame = dom.cancelAnimationFrame.bind(dom);
+
+afterEach(cleanup);
+
+function drawer(props: Partial<ComponentProps<typeof FileDrawer>> = {}) {
+  return (
+    <ThemeProvider theme={defaultEditorTheme}>
+      <FileDrawer title="Trail code" onClose={() => {}} {...props}>
+        <input aria-label="Code state" defaultValue="selected step" />
+      </FileDrawer>
+    </ThemeProvider>
+  );
+}
+
+function parts(container: HTMLElement) {
+  return {
+    spacer: container.children[0] as HTMLElement,
+    panel: container.children[1] as HTMLElement,
+  };
+}
+
+describe('FileDrawer docking', () => {
+  test('keeps the default bottom drawer and reserves height', () => {
+    const { container } = render(drawer());
+    const { spacer, panel } = parts(container);
+    expect(spacer.style.height).toBe('45%');
+    expect(spacer.style.width).toBe('');
+    expect(panel.style.height).toBe('45%');
+    expect(panel.style.left).toBe('0px');
+    expect(panel.style.right).toBe('0px');
+    expect(panel.style.top).toBe('');
+    expect(panel.style.borderTopStyle).toBe('solid');
+  });
+
+  test('docks on the left and reserves width before the canvas', () => {
+    const { container } = render(drawer({ placement: 'left' }));
+    const { spacer, panel } = parts(container);
+    expect(spacer.style.width).toBe('45%');
+    expect(spacer.style.height).toBe('');
+    expect(spacer.style.order).toBe('-1');
+    expect(panel.style.width).toBe('45%');
+    expect(panel.style.height).toBe('100%');
+    expect(panel.style.left).toBe('0px');
+    expect(panel.style.right).toBe('');
+    expect(panel.style.top).toBe('0px');
+    expect(panel.style.borderRightStyle).toBe('solid');
+    expect(panel.style.borderTopStyle).toBe('none');
+  });
+
+  test('preserves mounted content when switching dock axes', () => {
+    const { container, getByLabelText, rerender } = render(drawer());
+    const input = getByLabelText('Code state') as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'step 3' } });
+    rerender(drawer({ placement: 'left' }));
+    expect(getByLabelText('Code state')).toBe(input);
+    expect(input.value).toBe('step 3');
+    expect(parts(container).spacer.style.height).toBe('');
+    rerender(drawer());
+    expect(getByLabelText('Code state')).toBe(input);
+    expect(parts(container).spacer.style.width).toBe('');
+    expect(parts(container).panel.style.width).toBe('');
+  });
+
+  test('maximizes and restores along the left dock axis', () => {
+    const { container, getByLabelText } = render(drawer({ placement: 'left' }));
+    fireEvent.click(getByLabelText('Maximize code view'));
+    expect(parts(container).panel.style.width).toBe('100%');
+    expect(parts(container).spacer.style.width).toBe('0px');
+    fireEvent.click(getByLabelText('Minimize code view'));
+    expect(parts(container).panel.style.width).toBe('45%');
+    expect(parts(container).spacer.style.width).toBe('45%');
+  });
+
+  test('fills the graph area for full-file reading', () => {
+    const { container } = render(drawer({ placement: 'left', fillHeight: true }));
+    expect(parts(container).panel.style.width).toBe('100%');
+    expect(parts(container).spacer.style.width).toBe('0px');
+  });
+
+  test('closed and hidden left drawers reserve no width', () => {
+    const { container, rerender } = render(drawer({ placement: 'left', title: null }));
+    expect(parts(container).panel.style.width).toBe('0px');
+    expect(parts(container).spacer.style.width).toBe('0px');
+    rerender(drawer({ placement: 'left', hidden: true }));
+    expect(parts(container).panel.style.width).toBe('0px');
+    expect(parts(container).spacer.style.width).toBe('0px');
+  });
+
+  test('closing resets maximize state before reopening', () => {
+    const { container, getByLabelText, rerender } = render(drawer({ placement: 'left' }));
+    fireEvent.click(getByLabelText('Maximize code view'));
+    rerender(drawer({ placement: 'left', title: null }));
+    rerender(drawer({ placement: 'left' }));
+    expect(parts(container).panel.style.width).toBe('45%');
+    expect(getByLabelText('Maximize code view')).not.toBeNull();
+  });
+
+  test('Escape closes a left drawer unless a full-file overlay handles it', () => {
+    let closes = 0;
+    const onClose = () => { closes++; };
+    const { rerender } = render(drawer({ placement: 'left', onClose }));
+    fireEvent.keyDown(window, { key: 'Escape' });
+    expect(closes).toBe(1);
+    rerender(drawer({ placement: 'left', onClose, suppressEscape: true }));
+    fireEvent.keyDown(window, { key: 'Escape' });
+    expect(closes).toBe(1);
+  });
+});

package/src/subsystem/FileDrawer.tsx

@@ -1,6 +1,6 @@
 /**
- * FileDrawer — bottom panel that slides up from the bottom of the graph area
- * to show file / trail code. Opened by sidebar file-tree clicks,
+ * FileDrawer — bottom or left panel in the graph area
+ * showing file / trail code. Opened by sidebar file-tree clicks,
  * declaration links, and trail step focus; content is injected as
  * children by the graph component.
  */
@@ -10,18 +10,15 @@ import type { ReactNode } from "react";
 import { useTheme } from "@principal-ade/industry-theme";
 import { Minimize2, Maximize2, X } from "lucide-react";
 
-/** Matches `transition: height …` below — callers that fitView after open
- *  should wait at least this long so the canvas has its reduced height. */
+/** Matches the drawer's size transition; wait this long before fitting the canvas. */
 export const FILE_DRAWER_HEIGHT_MS = 200;
 
-/** Bottom panel that slides up from the bottom of the graph area.
- *  Bottom-anchored with an animated height; an in-flow spacer reserves its
- *  footprint so the canvas shrinks while open (nothing covered). Stays mounted
- *  so open/close/maximize animate. The header's maximize button (or a
- *  double-click) grows it over the whole graph column for whole-file reading. */
+/** An in-flow spacer reserves the panel's footprint so it never covers the
+ *  canvas. Stays mounted across open/close, maximize, and docking changes. */
 export function FileDrawer({
   title,
   onClose,
+  placement = "bottom",
   fillHeight = false,
   suppressEscape = false,
   hidden = false,
@@ -32,7 +29,9 @@ export function FileDrawer({
   /** Drawer chrome title; `null` closes the drawer. */
   title: string | null;
   onClose: () => void;
-  /** When true and open, fill the graph column instead of ~45% height. */
+  /** Left docking requires a row container; bottom docking requires a column. */
+  placement?: "bottom" | "left";
+  /** When true and open, fill the graph area instead of ~45% of its dock axis. */
   fillHeight?: boolean;
   /** Skip Escape handling (e.g. while a full-file overlay is on top). */
   suppressEscape?: boolean;
@@ -54,18 +53,17 @@ export function FileDrawer({
   const showProgress = progress != null && progress.total > 1;
   const [closeHover, setCloseHover] = useState(false);
   const [maxHover, setMaxHover] = useState(false);
-  // Full-height mode: the maximize button or double-clicking the header.
-  // The panel is always bottom-anchored with an animated height, and a spacer
-  // in normal flow reserves its footprint, so maximizing grows it upward over
-  // the still-mounted graph instead of snapping to full.
+  // Maximize grows over the still-mounted graph along the current dock axis.
   const [maximized, setMaximized] = useState(false);
-  // A closed drawer reopens at the default height, not maximized.
+  // A closed drawer reopens at the default size, not maximized.
   useEffect(() => {
     if (!open) setMaximized(false);
   }, [open]);
-  const fullHeight = open && (maximized || fillHeight);
+  const fullSize = open && (maximized || fillHeight);
+  const sideDocked = placement === "left";
+  const sizeAxis = sideDocked ? "width" : "height";
   // Space the panel takes out of the canvas's flow (0 when it overlays fully).
-  const reservedHeight = fullHeight ? 0 : open ? "45%" : 0;
+  const reservedSize = fullSize ? 0 : open ? "45%" : 0;
 
   useEffect(() => {
     if (!open || suppressEscape) return;
@@ -78,36 +76,37 @@ export function FileDrawer({
 
   return (
     <>
-      {/* Reserves the drawer's footprint in the column so the canvas shrinks
-          while the drawer is open. Animates with the panel, so the boundary
-          between graph and code slides smoothly. */}
+      {/* Reserve the same size along the parent's matching flex axis. */}
       <div
         aria-hidden="true"
         style={{
           flexShrink: 0,
-          height: reservedHeight,
-          transition: `height ${FILE_DRAWER_HEIGHT_MS}ms ease`,
+          order: sideDocked ? -1 : undefined,
+          [sizeAxis]: reservedSize,
+          transition: `${sizeAxis} ${FILE_DRAWER_HEIGHT_MS}ms ease`,
         }}
       />
-      {/* The panel — bottom-anchored and grown via `height`, so maximize/fill
-          reads as dragging up over the diagram. */}
       <div
         style={{
           position: "absolute",
           left: 0,
-          right: 0,
+          top: sideDocked ? 0 : undefined,
+          right: sideDocked ? undefined : 0,
           bottom: 0,
           // Above the edge-label overlay (zIndex 5), React Flow, and overlays
           // (zIndex 6–8); 30 lifts it over the whole graph area when maximized.
           zIndex: maximized ? 30 : 6,
-          height: open ? (fullHeight ? "100%" : "45%") : 0,
+          width: sideDocked ? (open ? (fullSize ? "100%" : "45%") : 0) : undefined,
+          height: sideDocked ? "100%" : open ? (fullSize ? "100%" : "45%") : 0,
+          minWidth: 0,
           minHeight: 0,
           overflow: "hidden",
           display: "flex",
           flexDirection: "column",
           background: theme.colors.background,
-          borderTop: open ? `1px solid ${theme.colors.border}` : "none",
-          transition: `height ${FILE_DRAWER_HEIGHT_MS}ms ease`,
+          borderTop: open && !sideDocked ? `1px solid ${theme.colors.border}` : "none",
+          borderRight: open && sideDocked ? `1px solid ${theme.colors.border}` : "none",
+          transition: `${sizeAxis} ${FILE_DRAWER_HEIGHT_MS}ms ease`,
         }}
       >
         <div

package/src/subsystem/GraphSidebar.test.tsx

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from 'bun:test';
-import { createElement } from 'react';
+import { createElement, useState } from 'react';
 import { Window } from 'happy-dom';
 import { cleanup, fireEvent, render } from '@testing-library/react/pure';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
@@ -125,6 +125,59 @@ describe('GraphSidebar chrome', () => {
     expect(sidebarColumn(container).style.width).toBe('400px');
   });
 
+  test('multiple moves track displacement from drag start without accumulating', () => {
+    const { container, getByLabelText } = renderSidebar({});
+    const handle = getByLabelText('Resize sidebar');
+    fireEvent.mouseDown(handle, { clientX: 100 });
+    fireEvent.mouseMove(document, { clientX: 120 });
+    expect(sidebarColumn(container).style.width).toBe('340px');
+    fireEvent.mouseMove(document, { clientX: 140 });
+    expect(sidebarColumn(container).style.width).toBe('360px');
+    fireEvent.mouseMove(document, { clientX: 110 });
+    expect(sidebarColumn(container).style.width).toBe('330px');
+    fireEvent.mouseUp(document);
+
+    // Each new gesture starts from the width the previous gesture left.
+    fireEvent.mouseDown(handle, { clientX: 110 });
+    fireEvent.mouseMove(document, { clientX: 130 });
+    fireEvent.mouseUp(document);
+    expect(sidebarColumn(container).style.width).toBe('350px');
+  });
+
+  test('clamps at both limits and follows the pointer back from them', () => {
+    const { container, getByLabelText } = renderSidebar({});
+    fireEvent.mouseDown(getByLabelText('Resize sidebar'), { clientX: 100 });
+    fireEvent.mouseMove(document, { clientX: 500 });
+    expect(sidebarColumn(container).style.width).toBe('600px');
+    fireEvent.mouseMove(document, { clientX: 150 });
+    expect(sidebarColumn(container).style.width).toBe('370px');
+    fireEvent.mouseMove(document, { clientX: -100 });
+    expect(sidebarColumn(container).style.width).toBe('240px');
+    fireEvent.mouseMove(document, { clientX: 100 });
+    expect(sidebarColumn(container).style.width).toBe('320px');
+    fireEvent.mouseUp(document);
+  });
+
+  test('controlled host updates do not change the drag baseline', () => {
+    function ControlledSidebar() {
+      const [width, setWidth] = useState(400);
+      return createElement(
+        ThemeProvider,
+        { theme: defaultEditorTheme },
+        createElement(GraphSidebar, { width, onWidthChange: setWidth }),
+      );
+    }
+    const { container, getByLabelText } = render(createElement(ControlledSidebar));
+    fireEvent.mouseDown(getByLabelText('Resize sidebar'), { clientX: 100 });
+    fireEvent.mouseMove(document, { clientX: 140 });
+    expect(sidebarColumn(container).style.width).toBe('440px');
+    fireEvent.mouseMove(document, { clientX: 160 });
+    expect(sidebarColumn(container).style.width).toBe('460px');
+    fireEvent.mouseMove(document, { clientX: 100 });
+    expect(sidebarColumn(container).style.width).toBe('400px');
+    fireEvent.mouseUp(document);
+  });
+
   test('a drag ends by persisting the width under persistKey', () => {
     const { getByLabelText } = renderSidebar({
       persistKey: 'gs-test',
@@ -132,6 +185,8 @@ describe('GraphSidebar chrome', () => {
     });
     const handle = getByLabelText('Resize sidebar');
     fireEvent.mouseDown(handle, { clientX: 100 });
+    fireEvent.mouseMove(document, { clientX: 140 });
+    fireEvent.mouseMove(document, { clientX: 180 });
     fireEvent.mouseMove(document, { clientX: 200 });
     fireEvent.mouseUp(document);
     expect(window.localStorage.getItem('principal.subsystems.sidebarWidth.gs-test')).toBe('420');

package/src/subsystem/GraphSidebar.tsx

@@ -130,6 +130,7 @@ export function GraphSidebar({
   // persisting only then — not on every mousemove.
   const [dragging, setDragging] = useState(false);
   const dragStartX = useRef(0);
+  const dragStartWidth = useRef(0);
   // Mirror of the current width for the mouseup handler (a closure over the
   // drag-start render would persist the stale start width).
   const currentWidthRef = useRef(effectiveWidth);
@@ -139,6 +140,7 @@ export function GraphSidebar({
     (e: ReactMouseEvent) => {
       e.preventDefault();
       dragStartX.current = e.clientX;
+      dragStartWidth.current = effectiveWidth;
       currentWidthRef.current = effectiveWidth;
       setDragging(true);
       onDraggingChange?.(true);
@@ -150,7 +152,7 @@ export function GraphSidebar({
     if (!dragging) return;
     const onMove = (e: MouseEvent) => {
       const next = Math.min(
-        Math.max(currentWidthRef.current + (e.clientX - dragStartX.current), minWidth),
+        Math.max(dragStartWidth.current + (e.clientX - dragStartX.current), minWidth),
         maxWidth,
       );
       if (controlled) {