@peasant-labs/fairtrade 0.0.6 → 0.0.7

package/dist/lib/types/CommitGraph.d.ts

@@ -6,6 +6,7 @@
  * @property {string} message - the commit subject (USER CONTENT — case preserved)
  * @property {string} [branch] - branch name for the chip (USER CONTENT — case preserved)
  * @property {boolean} [session] - a recorded AI session sits behind this commit (-> filled + sparkle)
+ * @property {import('./graph/types.js').TimelineSessionPayload[]} [sessionRefs] - named sessions bound to this commit
  * @property {boolean} [merged] - this commit merged a branch back in (-> merged chip)
  * @property {boolean} [tip] - this commit is a branch tip (-> small tip affordance)
  * @property {string} [time] - relative time label (e.g. "8m ago") — already humanised by the caller
@@ -16,16 +17,20 @@
  * @param {object} props
  * @param {Commit[]} props.commits - the history, newest first; lane 0 is the main line.
  * @param {string} [props.selectedId] - id of the active/selected row (the scarce amber treatment).
- * @param {(commit: Commit) => void} [props.onSelect] - called with the commit when a row is chosen.
+ * @param {(action: import('./graph/timelineNavigation.js').TimelineNavigationAction) => void} [props.onNavigate] - canonical semantic action callback; when present, legacy callbacks do not fire.
+ * @param {(commit: Commit) => void} [props.onSelect] - deprecated legacy row callback; use onNavigate.
+ * @param {(sessionId: string) => void} [props.onOpenSession] - deprecated legacy session callback; use onNavigate.
  * @param {boolean} [props.hasMore=false] - more history exists below the window -> show the "show older" ghost.
- * @param {() => void} [props.onShowOlder] - called when "show older" is pressed.
+ * @param {() => void} [props.onShowOlder] - deprecated legacy pagination callback; use onNavigate.
  * @param {string} [props.label='commit history'] - accessible name for the list (lowercase chrome).
  * @param {string} [props.className] - extra classes appended to the root.
  */
-export default function CommitGraph({ commits, selectedId, onSelect, hasMore, onShowOlder, label, className, ...rest }: {
+export default function CommitGraph({ commits, selectedId, onNavigate, onSelect, onOpenSession, hasMore, onShowOlder, label, className, ...rest }: {
     commits: Commit[];
     selectedId?: string;
+    onNavigate?: (action: import("./graph/timelineNavigation.js").TimelineNavigationAction) => void;
     onSelect?: (commit: Commit) => void;
+    onOpenSession?: (sessionId: string) => void;
     hasMore?: boolean;
     onShowOlder?: () => void;
     label?: string;
@@ -56,6 +61,10 @@ export type Commit = {
      * - a recorded AI session sits behind this commit (-> filled + sparkle)
      */
     session?: boolean;
+    /**
+     * - named sessions bound to this commit
+     */
+    sessionRefs?: import("./graph/types.js").TimelineSessionPayload[];
     /**
      * - this commit merged a branch back in (-> merged chip)
      */

package/dist/lib/types/MapCanvas.d.ts

@@ -23,7 +23,8 @@
  */
 /**
  * MapCanvas — an interactive code-structure map. Pan (drag), zoom (square controls /
- * +/- keys, never wheel), semantic zoom (overview / folders / files) with edge
+ * +/- keys / ctrl-or-cmd+wheel — a plain wheel always just scrolls the page),
+ * semantic zoom (overview / folders / files) with edge
  * ancestor-lifting, a minimap, and a node search combobox. Square metric-encoded
  * nodes (width ∝ LOC, monochrome coverage fill, folder/file icon, amber selection +
  * marker, clay violation badge) and square orthogonal edges (solid structure /
@@ -34,6 +35,8 @@
  * @param {{nodes: MapNode[], edges?: MapEdge[]}} [props.data]   the graph
  * @param {'overview'|'folders'|'files'} [props.grain='folders'] initial semantic zoom
  * @param {Iterable<string>} [props.expandedIds]                 expanded node ids
+ * @param {Iterable<string>} [props.visibleIds]                  canonical derived visible node ids
+ * @param {import('./graph/codeMapState.js').CodeMapHierarchy} [props.hierarchy] canonical validated hierarchy
  * @param {string|null} [props.selectedId]                       selected node id
  * @param {Iterable<string>} [props.highlightedIds]              host hover/relay ids
  * @param {Record<string,'new'|'removed'>} [props.nodeDeltas]    per-node review deltas
@@ -45,14 +48,42 @@
  * @param {number|string} [props.height=520]                     canvas height
  * @param {string} [props.ariaLabel='code map']                  application label
  * @param {string} [props.className]                             extra container class
+ * @param {{scale:number, panX:number, panY:number}|null} [props.viewport] controlled/restorable spatial viewport.
+ *   In `canonicalControlled` mode this is the SOLE source of truth once a
+ *   gesture ends: MapCanvas renders it directly and does not keep its own
+ *   copy. CONTRACT: when a pan/zoom gesture ends, MapCanvas calls
+ *   `onViewportChange`/`onStateAction` with the proposed viewport, and the
+ *   owner is expected to feed that value straight back through this prop
+ *   PROMPTLY (a same-tick/next-render `useState` update, as peasant's real
+ *   integration does, is the reference case — not a debounce, network
+ *   round-trip, or anything else that can take an unbounded amount of time).
+ *   During the gesture itself MapCanvas tracks the pointer locally so the
+ *   drag/zoom stays smooth without waiting on this round-trip; it holds that
+ *   local preview for up to ~500ms after the gesture ends waiting for
+ *   `viewport` to reflect (or nearly reflect — the owner may legitimately
+ *   clamp scale/pan bounds) the proposal, THEN falls back to whatever this
+ *   prop says. An owner that never updates `viewport` in response (rejects
+ *   the change, or simply never wires the callback) will see the gesture
+ *   held for that ~500ms window and then discarded — a visible snap-back to
+ *   the pre-gesture position, not a smooth revert. An owner that reconciles
+ *   slower than ~500ms (e.g. a debounce or a network-backed proposal) will
+ *   see the SAME snap-back-then-jump-to-late-value symptom the pointer-drag
+ *   fix in this file exists to prevent — reconcile synchronously.
+ * @param {(viewport:{scale:number, panX:number, panY:number})=>void} [props.onViewportChange]
+ * @param {(action:import('./graph/codeMapState.js').CodeMapAction)=>void} [props.onStateAction] one semantic canvas gesture
+ * @param {boolean} [props.canonicalControlled=false] canonical values render directly; gestures emit proposals only.
+ *   See the `viewport` prop doc above for the synchronous-reconciliation
+ *   contract this mode requires of its owner.
  */
-export default function MapCanvas({ data, grain: grainProp, expandedIds, selectedId: selectedIdProp, highlightedIds, nodeDeltas, edgeDeltas, onSelect, onGrainChange, onExpandedIdsChange, onExpand, height, ariaLabel, className, }: {
+export default function MapCanvas({ data, grain: grainProp, expandedIds, visibleIds: canonicalVisibleIds, hierarchy: canonicalHierarchy, selectedId: selectedIdProp, highlightedIds, nodeDeltas, edgeDeltas, onSelect, onGrainChange, onExpandedIdsChange, onExpand, height, ariaLabel, className, viewport, onViewportChange, onStateAction, canonicalControlled, }: {
     data?: {
         nodes: MapNode[];
         edges?: MapEdge[];
     };
     grain?: "overview" | "folders" | "files";
     expandedIds?: Iterable<string>;
+    visibleIds?: Iterable<string>;
+    hierarchy?: import("./graph/codeMapState.js").CodeMapHierarchy;
     selectedId?: string | null;
     highlightedIds?: Iterable<string>;
     nodeDeltas?: Record<string, "new" | "removed">;
@@ -64,6 +95,18 @@ export default function MapCanvas({ data, grain: grainProp, expandedIds, selecte
     height?: number | string;
     ariaLabel?: string;
     className?: string;
+    viewport?: {
+        scale: number;
+        panX: number;
+        panY: number;
+    } | null;
+    onViewportChange?: (viewport: {
+        scale: number;
+        panX: number;
+        panY: number;
+    }) => void;
+    onStateAction?: (action: import("./graph/codeMapState.js").CodeMapAction) => void;
+    canonicalControlled?: boolean;
 }): any;
 export type MapNode = {
     /**

package/dist/lib/types/ProviderIcon.d.ts

@@ -7,20 +7,20 @@
  * the surrounding text color — but remember the accent is never the sole signal.
  *
  * @param {object} props
- * @param {'claude-code'|'gemini-cli'|'codex'|'opencode'|'cursor'} props.harness
+ * @param {Harness} props.harness
  * @param {number} [props.size] explicit px; omit to inherit the contextual icon size.
  * @param {boolean} [props.accent] tint with PROVIDER_ACCENT[harness] (default: currentColor).
  * @param {boolean|string} [props.label] true → the provider name as aria-label; a string overrides.
  * @param {string} [props.className] extra classes appended after `pv-icon`.
- * @returns {JSX.Element|null} null when `harness` is unknown.
+ * @returns {JSX.Element}
  */
 export function ProviderIcon({ harness, size, accent, label, className, ...rest }: {
-    harness: "claude-code" | "gemini-cli" | "codex" | "opencode" | "cursor";
+    harness: Harness;
     size?: number;
     accent?: boolean;
     label?: boolean | string;
     className?: string;
-}): JSX.Element | null;
+}): JSX.Element;
 /**
  * ProviderTag — a square hairline chip: the real mark + the lowercase harness slug.
  *
@@ -29,16 +29,16 @@ export function ProviderIcon({ harness, size, accent, label, className, ...rest
  * monochrome it names the provider in words. pass `accent` to tint the mark.
  *
  * @param {object} props
- * @param {'claude-code'|'gemini-cli'|'codex'|'opencode'|'cursor'} props.harness
+ * @param {Harness} props.harness
  * @param {boolean} [props.accent] tint the mark with the provider accent (default: ink).
  * @param {string} [props.className]
- * @returns {JSX.Element|null}
+ * @returns {JSX.Element}
  */
 export function ProviderTag({ harness, accent, className, ...rest }: {
-    harness: "claude-code" | "gemini-cli" | "codex" | "opencode" | "cursor";
+    harness: Harness;
     accent?: boolean;
     className?: string;
-}): JSX.Element | null;
+}): JSX.Element;
 /**
  * ProviderName — mark + the harness slug as a plain inline label (no chip border).
  *
@@ -47,16 +47,16 @@ export function ProviderTag({ harness, accent, className, ...rest }: {
  * non-color cue regardless — it is real text, so it is readable mono-color too).
  *
  * @param {object} props
- * @param {'claude-code'|'gemini-cli'|'codex'|'opencode'|'cursor'} props.harness
+ * @param {Harness} props.harness
  * @param {boolean} [props.accent] tint mark + label with the provider accent.
  * @param {string} [props.className]
- * @returns {JSX.Element|null}
+ * @returns {JSX.Element}
  */
 export function ProviderName({ harness, accent, className, ...rest }: {
-    harness: "claude-code" | "gemini-cli" | "codex" | "opencode" | "cursor";
+    harness: Harness;
     accent?: boolean;
     className?: string;
-}): JSX.Element | null;
+}): JSX.Element;
 /**
  * AccentLegend — the per-provider accent map, documented as a UI.
  *
@@ -73,12 +73,15 @@ export function ProviderName({ harness, accent, className, ...rest }: {
 export function AccentLegend({ className, ...rest }: {
     className?: string;
 }): JSX.Element;
-export const HARNESSES: string[];
-export const PROVIDER_ACCENT: {
-    'claude-code': string;
-    'gemini-cli': string;
-    codex: string;
-    opencode: string;
-    cursor: string;
-};
+/** ProviderIcon — the real brand mark for a harness, single-color via currentColor. */
+/** @typedef {import('@peasant-labs/schema').Harness} Harness */
+/** @type {readonly Harness[]} */
+export const HARNESSES: readonly Harness[];
+/**
+ * @deprecated Use providerAccent(harness), which validates present values at
+ * the canonical schema boundary before returning an accent.
+ * @type {Readonly<Record<Harness, 'amber'|'teal'|'olive'|'mauve'|'clay'>>}
+ */
+export const PROVIDER_ACCENT: Readonly<Record<Harness, "amber" | "teal" | "olive" | "mauve" | "clay">>;
 export default ProviderIcon;
+export type Harness = import("@peasant-labs/schema").Harness;

package/dist/lib/types/commons/providers.d.ts

@@ -1,8 +1,7 @@
-export function formatProvider(provider: any): string;
-export function providerLabel(provider: any): any;
-export const PROVIDER_LABEL: {
-    'claude-code': string;
-    'gemini-cli': string;
-    opencode: string;
-    codex: string;
-};
+/** Format explicitly non-Harness prose. Never use this as a Harness fallback.
+ * @param {unknown} provider
+ */
+export function formatProvider(provider: unknown): string;
+/** @param {import('@peasant-labs/schema').Harness} provider */
+export function providerLabel(provider: import("@peasant-labs/schema").Harness): string;
+export const PROVIDER_LABEL: Readonly<Record<"cursor" | "claude-code" | "gemini-cli" | "codex" | "opencode" | "antigravity", string>>;

package/dist/lib/types/commons/types.d.ts

@@ -129,10 +129,7 @@ export type ExploreTranscriptPayload = {
     id: string;
     title: string | null;
     visibility: TranscriptVisibility;
-    /**
-     * e.g. "claude-code", "opencode"
-     */
-    modelProvider: string;
+    modelProvider: import("@peasant-labs/schema").Harness;
     modelName: string | null;
     harnessVersion: string | null;
     /**
@@ -241,7 +238,7 @@ export type CollectiveTranscriptPayload = {
     id: string;
     title: string | null;
     visibility: TranscriptVisibility;
-    modelProvider: string;
+    modelProvider: import("@peasant-labs/schema").Harness;
     modelName: string | null;
     /**
      * ISO-8601 datetime or null
@@ -268,7 +265,7 @@ export type CollectiveStatsPayload = {
  * Mirrors GroupModelBreakdown from frontend/src/lib/types.ts.
  */
 export type CollectiveModelBreakdownPayload = {
-    modelProvider: string;
+    modelProvider: import("@peasant-labs/schema").Harness;
     transcriptCount: number;
 };
 /**

package/dist/lib/types/graph/Changes.d.ts

@@ -3,19 +3,23 @@
  * @param {import('./types.js').ChangesPayload} props.payload  the cooked changes payload (adapter output)
  * @param {string} [props.projectLabel]  the head label (e.g. "peasant-labs/peasant"); host-supplied (not a payload field)
  * @param {string} [props.selectedId]  id of the active commit/tip row (the scarce amber treatment)
- * @param {(commit: import('./changeGraph.js').CommitGraphRow) => void} [props.onSelectChange]  a row was chosen (open its change detail)
- * @param {() => void} [props.onOpenMap]  the "open the map" affordance was pressed
+ * @param {(action: import('./timelineNavigation.js').TimelineNavigationAction) => void} [props.onNavigate] canonical semantic action callback; when present, legacy callbacks do not fire
+ * @param {(commit: import('./changeGraph.js').CommitGraphRow) => void} [props.onSelectChange]  deprecated legacy row callback; use onNavigate.
+ * @param {() => void} [props.onOpenMap]  deprecated legacy map callback; use onNavigate.
  * @param {boolean} [props.hasMore]  more history exists below the window (→ "show older")
- * @param {() => void} [props.onShowOlder]  "show older" was pressed
+ * @param {() => void} [props.onShowOlder]  deprecated legacy pagination callback; use onNavigate.
+ * @param {(sessionId: string) => void} [props.onOpenSession] deprecated legacy session callback; use onNavigate.
  * @param {number} [props.nowMs]  pins relative-time humanisation (default Date.now()); the harness fixes it for byte-stable captures
  */
-export default function Changes({ payload, projectLabel, selectedId, onSelectChange, onOpenMap, hasMore, onShowOlder, nowMs, }: {
+export default function Changes({ payload, projectLabel, selectedId, onNavigate, onSelectChange, onOpenMap, hasMore, onShowOlder, onOpenSession, nowMs, }: {
     payload: import("./types.js").ChangesPayload;
     projectLabel?: string;
     selectedId?: string;
+    onNavigate?: (action: import("./timelineNavigation.js").TimelineNavigationAction) => void;
     onSelectChange?: (commit: import("./changeGraph.js").CommitGraphRow) => void;
     onOpenMap?: () => void;
     hasMore?: boolean;
     onShowOlder?: () => void;
+    onOpenSession?: (sessionId: string) => void;
     nowMs?: number;
 }): any;

package/dist/lib/types/graph/CodeMap.d.ts

@@ -18,8 +18,12 @@
  * @param {number|string} [props.height]
  * @param {string} [props.ariaLabel]
  * @param {string} [props.className]
+ * @param {{scale:number, panX:number, panY:number}|null} [props.viewport]
+ * @param {(viewport:{scale:number, panX:number, panY:number})=>void} [props.onViewportChange]
+ * @param {import('./codeMapState.js').CodeMapState} [props.state]
+ * @param {(state:import('./codeMapState.js').CodeMapState)=>void} [props.onStateChange]
  */
-export default function CodeMap({ payload, zoom, onZoomChange, selectedId, onSelect, onExpand, highlightedIds, nodeDeltas, structureEdgeDeltas, height, ariaLabel, className, }: {
+export default function CodeMap({ payload, zoom, onZoomChange, selectedId, onSelect, onExpand, highlightedIds, nodeDeltas, structureEdgeDeltas, height, ariaLabel, className, viewport, onViewportChange, state, onStateChange, }: {
     payload: import("./types.js").CodeMapPayload;
     zoom?: {
         level: "project" | "package" | "file";
@@ -38,6 +42,18 @@ export default function CodeMap({ payload, zoom, onZoomChange, selectedId, onSel
     height?: number | string;
     ariaLabel?: string;
     className?: string;
+    viewport?: {
+        scale: number;
+        panX: number;
+        panY: number;
+    } | null;
+    onViewportChange?: (viewport: {
+        scale: number;
+        panX: number;
+        panY: number;
+    }) => void;
+    state?: import("./codeMapState.js").CodeMapState;
+    onStateChange?: (state: import("./codeMapState.js").CodeMapState) => void;
 }): any;
 /**
  * @param {import('./types.js').CodeMapPayload | undefined} payload

package/dist/lib/types/graph/CodeMapComposition.d.ts

@@ -45,8 +45,16 @@
  * @param {React.CSSProperties} [props.canvasWrapperStyle]     inline style on the canvas region wrapper
  *   (e.g. a host's own responsive height clamp)
  * @param {string} [props.className]                           extra class on the root
+ * @param {'canvas'|'navigator'} [props.presentation='canvas'] additive presentation switch; omitted preserves the historical canvas DOM
+ * @param {React.ReactNode} [props.navigatorSlot]              host-controlled navigator content
+ * @param {(presentation:'canvas'|'navigator')=>void} [props.onPresentationChange] when present, renders the canonical browse/map switch
+ * @param {{scale:number, panX:number, panY:number}} [props.viewport]
+ * @param {(viewport:{scale:number, panX:number, panY:number})=>void} [props.onViewportChange]
+ * @param {import('./codeMapState.js').CodeMapState} [props.state] canonical controlled state
+ * @param {Partial<import('./codeMapState.js').CodeMapState>} [props.defaultState] initial canonical uncontrolled state
+ * @param {(state:import('./codeMapState.js').CodeMapState)=>void} [props.onStateChange]
  */
-export default function CodeMapComposition({ payload, zoom, onZoomChange, selectedId, onSelect, onExpand, highlightedIds, nodeDeltas, structureEdgeDeltas, height, ariaLabel, canvasSlot, rail, toolbar, sheetTitle, sheetMeta, railSide, legend, canvasWrapperClassName, canvasWrapperStyle, className, }: {
+export default function CodeMapComposition({ payload, zoom, onZoomChange, selectedId, onSelect, onExpand, highlightedIds, nodeDeltas, structureEdgeDeltas, height, ariaLabel, canvasSlot, rail, toolbar, sheetTitle, sheetMeta, railSide, legend, canvasWrapperClassName, canvasWrapperStyle, className, presentation, navigatorSlot, onPresentationChange, viewport, onViewportChange, state, defaultState, onStateChange, }: {
     payload?: import("./types.js").CodeMapPayload;
     zoom?: {
         level: "project" | "package" | "file";
@@ -74,6 +82,22 @@ export default function CodeMapComposition({ payload, zoom, onZoomChange, select
     canvasWrapperClassName?: string;
     canvasWrapperStyle?: React.CSSProperties;
     className?: string;
+    presentation?: "canvas" | "navigator";
+    navigatorSlot?: React.ReactNode;
+    onPresentationChange?: (presentation: "canvas" | "navigator") => void;
+    viewport?: {
+        scale: number;
+        panX: number;
+        panY: number;
+    };
+    onViewportChange?: (viewport: {
+        scale: number;
+        panX: number;
+        panY: number;
+    }) => void;
+    state?: import("./codeMapState.js").CodeMapState;
+    defaultState?: Partial<import("./codeMapState.js").CodeMapState>;
+    onStateChange?: (state: import("./codeMapState.js").CodeMapState) => void;
 }): any;
 /**
  * The persistent legend explaining the canvas's four orthogonal visual channels

package/dist/lib/types/graph/CodeMapNavigator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CodeMapNavigator presents the code tree as a readable, keyboard-operable
+ * starting point. Hosts keep selection, expansion, focus, and filter state so
+ * a transition to the spatial canvas and back is lossless.
+ *
+ * @param {object} props
+ * @param {import('./types.js').CodeMapPayload} props.payload
+ * @param {'project'|'package'|'file'} [props.grain='package']
+ * @param {Iterable<string>} [props.expandedIds]
+ * @param {(ids:string[])=>void} [props.onExpandedIdsChange]
+ * @param {string|null} [props.selectedId]
+ * @param {(id:string|null, node:import('./types.js').MapNodePayload|null)=>void} [props.onSelect]
+ * @param {string|null} [props.focusedId]
+ * @param {(id:string|null)=>void} [props.onFocusChange]
+ * @param {string} [props.filter='']
+ * @param {(filter:string)=>void} [props.onFilterChange]
+ * @param {(id:string)=>void} [props.onOpenMap]
+ * @param {(action:import('./codeMapState.js').CodeMapAction)=>void} [props.onStateAction]
+ * @param {string} [props.ariaLabel='code map navigator']
+ */
+export default function CodeMapNavigator({ payload, grain, expandedIds, onExpandedIdsChange, selectedId, onSelect, focusedId, onFocusChange, filter, onFilterChange, onOpenMap, onStateAction, ariaLabel, }: {
+    payload: import("./types.js").CodeMapPayload;
+    grain?: "project" | "package" | "file";
+    expandedIds?: Iterable<string>;
+    onExpandedIdsChange?: (ids: string[]) => void;
+    selectedId?: string | null;
+    onSelect?: (id: string | null, node: import("./types.js").MapNodePayload | null) => void;
+    focusedId?: string | null;
+    onFocusChange?: (id: string | null) => void;
+    filter?: string;
+    onFilterChange?: (filter: string) => void;
+    onOpenMap?: (id: string) => void;
+    onStateAction?: (action: import("./codeMapState.js").CodeMapAction) => void;
+    ariaLabel?: string;
+}): any;

package/dist/lib/types/graph/changeGraph.d.ts

@@ -58,6 +58,10 @@ export type CommitGraphRow = {
      * a recorded session sits behind this commit (→ filled dot + sparkle)
      */
     session?: boolean;
+    /**
+     * named sessions bound to this commit
+     */
+    sessionRefs?: import("./types.js").TimelineSessionPayload[];
     /**
      * this commit merged a branch back in (→ merged chip)
      */
@@ -103,4 +107,12 @@ export type ChangesGraph = {
      * number of merged changes
      */
     mergedCount: number;
+    /**
+     * sessions not linked to a commit in this timeline window
+     */
+    unlinkedSessions: import("./types.js").TimelineSessionPayload[];
+    /**
+     * sessions linked to a commit outside the displayed default-branch window
+     */
+    outsideWindowSessions: import("./types.js").TimelineSessionPayload[];
 };

package/dist/lib/types/graph/codeMapState.d.ts

@@ -0,0 +1,136 @@
+/** @param {unknown} value @returns {value is number} */
+export function isCodeMapViewportScale(value: unknown): value is number;
+/**
+ * Creates a canonical, JSON-safe code-map interaction state.
+ * @param {Partial<CodeMapState>|null} [seed]
+ * @returns {CodeMapState}
+ */
+export function createCodeMapState(seed?: Partial<CodeMapState> | null): CodeMapState;
+/** @param {CodeMapState} left @param {CodeMapState} right */
+export function codeMapStatesEqual(left: CodeMapState, right: CodeMapState): boolean;
+/**
+ * Applies one semantic interaction and returns a fresh canonical state.
+ * @param {CodeMapState} state
+ * @param {CodeMapAction} action
+ * @returns {CodeMapState}
+ */
+export function reduceCodeMapState(state: CodeMapState, action: CodeMapAction): CodeMapState;
+/**
+ * Derives the complete navigator and canvas inputs from payload plus canonical state.
+ * Returned nodes are plain public payload data; no private indexes or depths are attached.
+ * @param {import('./types.js').CodeMapPayload|undefined|null} payload
+ * @param {CodeMapState} state
+ * @returns {CodeMapView}
+ */
+export function deriveCodeMapView(payload: import("./types.js").CodeMapPayload | undefined | null, state: CodeMapState): CodeMapView;
+/** @typedef {import('./types.js').MapNodePayload} MapNodePayload */
+/** @typedef {{type:'replace'|'hydrate', state:Partial<CodeMapState>} | {type:'set-presentation', presentation:CodeMapPresentation} | {type:'select'|'toggle-expanded'|'open-in-map', id:string} | {type:'focus', id:string|null} | {type:'clear-selection'} | {type:'set-filter', filter:string} | {type:'set-expanded', ids:Iterable<string>} | {type:'set-grain', grain:CodeMapGrain} | {type:'set-viewport', viewport:CodeMapViewport|null} | {type:'reveal', id:string, grain:CodeMapGrain, expandedIds:Iterable<string>}} CodeMapAction */
+/**
+ * @typedef {object} CodeMapState
+ * @property {1} version
+ * @property {CodeMapPresentation} presentation
+ * @property {string|null} selectedId
+ * @property {CodeMapGrain} grain
+ * @property {string[]} expandedIds
+ * @property {string} navigatorFilter
+ * @property {string|null} navigatorFocusedId
+ * @property {CodeMapViewport|null} viewport
+ */
+/** @typedef {{node:import('./types.js').MapNodePayload, depth:number, parentId:string|null, childIds:string[], hasChildren:boolean, canExpand:boolean, forcedOpen:boolean, expanded:boolean}} CodeMapNavigatorRow */
+/** @typedef {{orderedIds:string[], rootIds:string[], childIdsByParent:Record<string,string[]>, depthById:Record<string,number>}} CodeMapHierarchy */
+/** @typedef {{allNodes:import('./types.js').MapNodePayload[], nodes:import('./types.js').MapNodePayload[], visibleIds:string[], selectedId:string|null, grain:CodeMapGrain, expandedIds:string[], viewport:CodeMapViewport|null, hierarchy:CodeMapHierarchy}} CodeMapCanvasView */
+/** @typedef {{state:CodeMapState, rows:CodeMapNavigatorRow[], focusedId:string|null, selected:import('./types.js').MapNodePayload|null, staleSelectedId:string|null, canvas:CodeMapCanvasView}} CodeMapView */
+export const CODE_MAP_STATE_VERSION: 1;
+export const CODE_MAP_VIEWPORT_SCALE: Readonly<{
+    min: 0.35;
+    max: 2.4;
+}>;
+export const CODE_MAP_GRAIN_DEPTH: Readonly<{
+    project: 0;
+    package: 1;
+    file: 1;
+}>;
+export type CodeMapPresentation = "navigator" | "canvas";
+export type CodeMapGrain = "project" | "package" | "file";
+export type CodeMapViewport = {
+    scale: number;
+    panX: number;
+    panY: number;
+};
+export type MapNodePayload = import("./types.js").MapNodePayload;
+export type CodeMapAction = {
+    type: "replace" | "hydrate";
+    state: Partial<CodeMapState>;
+} | {
+    type: "set-presentation";
+    presentation: CodeMapPresentation;
+} | {
+    type: "select" | "toggle-expanded" | "open-in-map";
+    id: string;
+} | {
+    type: "focus";
+    id: string | null;
+} | {
+    type: "clear-selection";
+} | {
+    type: "set-filter";
+    filter: string;
+} | {
+    type: "set-expanded";
+    ids: Iterable<string>;
+} | {
+    type: "set-grain";
+    grain: CodeMapGrain;
+} | {
+    type: "set-viewport";
+    viewport: CodeMapViewport | null;
+} | {
+    type: "reveal";
+    id: string;
+    grain: CodeMapGrain;
+    expandedIds: Iterable<string>;
+};
+export type CodeMapState = {
+    version: 1;
+    presentation: CodeMapPresentation;
+    selectedId: string | null;
+    grain: CodeMapGrain;
+    expandedIds: string[];
+    navigatorFilter: string;
+    navigatorFocusedId: string | null;
+    viewport: CodeMapViewport | null;
+};
+export type CodeMapNavigatorRow = {
+    node: import("./types.js").MapNodePayload;
+    depth: number;
+    parentId: string | null;
+    childIds: string[];
+    hasChildren: boolean;
+    canExpand: boolean;
+    forcedOpen: boolean;
+    expanded: boolean;
+};
+export type CodeMapHierarchy = {
+    orderedIds: string[];
+    rootIds: string[];
+    childIdsByParent: Record<string, string[]>;
+    depthById: Record<string, number>;
+};
+export type CodeMapCanvasView = {
+    allNodes: import("./types.js").MapNodePayload[];
+    nodes: import("./types.js").MapNodePayload[];
+    visibleIds: string[];
+    selectedId: string | null;
+    grain: CodeMapGrain;
+    expandedIds: string[];
+    viewport: CodeMapViewport | null;
+    hierarchy: CodeMapHierarchy;
+};
+export type CodeMapView = {
+    state: CodeMapState;
+    rows: CodeMapNavigatorRow[];
+    focusedId: string | null;
+    selected: import("./types.js").MapNodePayload | null;
+    staleSelectedId: string | null;
+    canvas: CodeMapCanvasView;
+};

package/dist/lib/types/graph/index.d.ts

@@ -1,11 +1,14 @@
 export { default as Changes } from "./Changes.jsx";
 export { default as ChangeDetail } from "./ChangeDetail.jsx";
+export { default as CodeMapNavigator } from "./CodeMapNavigator.jsx";
+export { assertTimelineNavigationAction } from "./timelineNavigation.js";
 export type MapNodeKind = import("./types.js").MapNodeKind;
 export type ChangeBinding = import("./types.js").ChangeBinding;
 export type EdgeViolationKind = import("./types.js").EdgeViolationKind;
 export type FileChangeStatus = import("./types.js").FileChangeStatus;
 export type DiffLineKind = import("./types.js").DiffLineKind;
 export type CommitRefPayload = import("./types.js").CommitRefPayload;
+export type TimelineSessionPayload = import("./types.js").TimelineSessionPayload;
 export type MapEdgePayload = import("./types.js").MapEdgePayload;
 export type ActivityEdgePayload = import("./types.js").ActivityEdgePayload;
 export type EdgeViolationPayload = import("./types.js").EdgeViolationPayload;
@@ -23,8 +26,19 @@ export type DiffLinePayload = import("./types.js").DiffLinePayload;
 export type DiffHunkPayload = import("./types.js").DiffHunkPayload;
 export type ChangeDiffPayload = import("./types.js").ChangeDiffPayload;
 export type CodeMapPayload = import("./types.js").CodeMapPayload;
+export type CodeMapPresentation = import("./codeMapState.js").CodeMapPresentation;
+export type CodeMapGrain = import("./codeMapState.js").CodeMapGrain;
+export type CodeMapViewport = import("./codeMapState.js").CodeMapViewport;
+export type CodeMapState = import("./codeMapState.js").CodeMapState;
+export type CodeMapAction = import("./codeMapState.js").CodeMapAction;
+export type CodeMapNavigatorRow = import("./codeMapState.js").CodeMapNavigatorRow;
+export type CodeMapCanvasView = import("./codeMapState.js").CodeMapCanvasView;
+export type CodeMapView = import("./codeMapState.js").CodeMapView;
+export type TimelineNavigationAction = import("./timelineNavigation.js").TimelineNavigationAction;
 export { default as CodeMap, codeMapPayloadToMapData } from "./CodeMap.jsx";
 export { default as CodeMapComposition, DefaultMapLegend } from "./CodeMapComposition.jsx";
+export { CODE_MAP_STATE_VERSION, CODE_MAP_VIEWPORT_SCALE, isCodeMapViewportScale, codeMapStatesEqual, createCodeMapState, reduceCodeMapState, deriveCodeMapView } from "./codeMapState.js";
 export { GraphAppShell, GraphSectionNav, GRAPH_APP_SECTIONS } from "../inuse/InUseShell.jsx";
 export { buildChangesGraph, humanizeAge } from "./changeGraph.js";
-export { MAP_NODE_KINDS, CHANGE_BINDINGS, EDGE_VIOLATION_KINDS, FILE_CHANGE_STATUSES, DIFF_LINE_KINDS } from "./types.js";
+export { assertChangeDetailPayloadEnums, assertChangeDiffPayloadEnums, assertCodeMapPayloadEnums, MAP_NODE_KINDS, CHANGE_BINDINGS, EDGE_VIOLATION_KINDS, FILE_CHANGE_STATUSES, DIFF_LINE_KINDS } from "./types.js";
+export { MapNodeKind, AllMapNodeKinds, isMapNodeKind, ChangeBinding, AllChangeBindings, isChangeBinding, EdgeViolationKind, AllEdgeViolationKinds, isEdgeViolationKind, FileChangeStatus, AllFileChangeStatuses, isFileChangeStatus, DiffLineKind, AllDiffLineKinds, isDiffLineKind } from "@peasant-labs/schema";

package/dist/lib/types/graph/timelineNavigation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Fail closed at untyped JavaScript boundaries before a host interprets a timeline gesture.
+ * The accepted object shapes are exact so additions require an explicit contract change.
+ *
+ * @param {unknown} value
+ * @returns {asserts value is TimelineNavigationAction}
+ */
+export function assertTimelineNavigationAction(value: unknown): asserts value is TimelineNavigationAction;
+export type TimelineNavigationAction = {
+    type: "open-change";
+    change: {
+        id: string;
+        branch: string | null;
+    };
+} | {
+    type: "open-session";
+    sessionId: string;
+    source: {
+        kind: "commit";
+        commit: {
+            id: string;
+            branch: string | null;
+        };
+    } | {
+        kind: "unlinked";
+    } | {
+        kind: "outside-window";
+    };
+} | {
+    type: "open-map";
+} | {
+    type: "show-older";
+};