@peasant-labs/fairtrade 0.0.3 → 0.0.5

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

@@ -0,0 +1,356 @@
+/**
+ * Transcript visibility level.
+ * @typedef {'public' | 'private' | 'shared'} TranscriptVisibility
+ */
+/** Canonical TranscriptVisibility values. @type {readonly TranscriptVisibility[]} */
+export const TRANSCRIPT_VISIBILITIES: readonly TranscriptVisibility[];
+/**
+ * Collective acceptance mode: who can join.
+ * Grounded in backend migration 005 — CHECK (acceptance_mode IN
+ * ('open','verified_only','curated')).
+ * @typedef {'open' | 'verified_only' | 'curated'} AcceptanceMode
+ */
+/** Canonical AcceptanceMode values. @type {readonly AcceptanceMode[]} */
+export const ACCEPTANCE_MODES: readonly AcceptanceMode[];
+/**
+ * Collective data access policy: who can read transcripts.
+ * Grounded in backend handler/groups.go canReadData + migration 008
+ * (data_access default 'members_only').
+ * @typedef {'members_only' | 'contributors' | 'public'} DataAccessPolicy
+ */
+/** Canonical DataAccessPolicy values. @type {readonly DataAccessPolicy[]} */
+export const DATA_ACCESS_POLICIES: readonly DataAccessPolicy[];
+/**
+ * Transcript deletion policy for a collective.
+ * Grounded in backend migration 016 — CHECK (transcript_deletion_policy IN
+ * ('user_choice','mandatory')).
+ * @typedef {'user_choice' | 'mandatory'} TranscriptDeletionPolicy
+ */
+/** Canonical TranscriptDeletionPolicy values. @type {readonly TranscriptDeletionPolicy[]} */
+export const TRANSCRIPT_DELETION_POLICIES: readonly TranscriptDeletionPolicy[];
+/**
+ * A member's role within a collective. The `members` list carries
+ * owner/member/contributor; the `pendingMembers` list carries `pending`
+ * (the backend's ListGroupPendingMembers query filters `gm.role = 'pending'`),
+ * so this union — shared by both lists via CollectiveMemberPayload — includes it.
+ * Grounded in backend handler/groups.go (Role: "owner"/"member"/"contributor")
+ * + sqlc ListGroupPendingMembers (WHERE gm.role = 'pending').
+ * @typedef {'owner' | 'member' | 'contributor' | 'pending'} CollectiveRole
+ */
+/** Canonical CollectiveRole values. @type {readonly CollectiveRole[]} */
+export const COLLECTIVE_ROLES: readonly CollectiveRole[];
+/**
+ * Transcript visibility level.
+ */
+export type TranscriptVisibility = "public" | "private" | "shared";
+/**
+ * Collective acceptance mode: who can join.
+ * Grounded in backend migration 005 — CHECK (acceptance_mode IN
+ * ('open','verified_only','curated')).
+ */
+export type AcceptanceMode = "open" | "verified_only" | "curated";
+/**
+ * Collective data access policy: who can read transcripts.
+ * Grounded in backend handler/groups.go canReadData + migration 008
+ * (data_access default 'members_only').
+ */
+export type DataAccessPolicy = "members_only" | "contributors" | "public";
+/**
+ * Transcript deletion policy for a collective.
+ * Grounded in backend migration 016 — CHECK (transcript_deletion_policy IN
+ * ('user_choice','mandatory')).
+ */
+export type TranscriptDeletionPolicy = "user_choice" | "mandatory";
+/**
+ * A member's role within a collective. The `members` list carries
+ * owner/member/contributor; the `pendingMembers` list carries `pending`
+ * (the backend's ListGroupPendingMembers query filters `gm.role = 'pending'`),
+ * so this union — shared by both lists via CollectiveMemberPayload — includes it.
+ * Grounded in backend handler/groups.go (Role: "owner"/"member"/"contributor")
+ * + sqlc ListGroupPendingMembers (WHERE gm.role = 'pending').
+ */
+export type CollectiveRole = "owner" | "member" | "contributor" | "pending";
+/**
+ * Current Explore browse filters mirrored by the host.
+ */
+export type ExploreFilters = {
+    query: string;
+    provider: string;
+    topics: string[];
+    order: string;
+    page: number;
+};
+/**
+ * Surface props for the lifted Explore component.
+ * The component consumes one cooked payload and owns its own browse state; hosts may also supply
+ * navigation slots for transcript/profile/collective exits.
+ */
+export type ExploreSurfaceProps = {
+    data: ExplorePayload;
+    className?: string;
+    onFiltersChange?: (filters: ExploreFilters) => void;
+    onOpenTranscript?: (transcript: ExploreTranscriptPayload) => void;
+    onOpenProfile?: (owner: ExploreOwnerPayload) => void;
+    onOpenCollective?: (collective: CollectiveResultPayload) => void;
+    transcriptHref?: (transcript: ExploreTranscriptPayload) => string;
+    profileHref?: (owner: ExploreOwnerPayload) => string;
+    collectiveHref?: (collective: CollectiveResultPayload) => string;
+};
+/**
+ * The AUTHENTICATED VIEWER's role in a collective — a CollectiveRole, OR the
+ * empty string when the viewer is not a member / anonymous. The backend GetGroup
+ * handler defaults `your_role` to "" for non-members (handler/groups.go:
+ * `yourRole := ""`), so this distinct type is required wherever the viewer's own
+ * role is exposed (your_role + the per-viewer Group.role), as opposed to a
+ * concrete member row's role.
+ */
+export type ViewerRole = CollectiveRole | "";
+/**
+ * One tag attached to a transcript in the Explore list.
+ */
+export type TagPayload = {
+    id: string;
+    name: string;
+};
+/**
+ * The author (owner) of a transcript as shown in the Explore list.
+ */
+export type ExploreOwnerPayload = {
+    githubUsername: string;
+    displayName: string | null;
+    avatarUrl: string | null;
+};
+/**
+ * One transcript row in the Explore browse list.
+ * Cooked from TranscriptListItem (frontend/src/lib/types.ts): snake_case fields
+ * are renamed to camelCase; fields not needed by the Explore surface are omitted.
+ */
+export type ExploreTranscriptPayload = {
+    id: string;
+    title: string | null;
+    visibility: TranscriptVisibility;
+    /**
+     * e.g. "claude-code", "opencode"
+     */
+    modelProvider: string;
+    modelName: string | null;
+    harnessVersion: string | null;
+    /**
+     * ISO-8601 datetime or null
+     */
+    sessionStart: string | null;
+    /**
+     * ISO-8601 datetime or null
+     */
+    sessionEnd: string | null;
+    turnCount: number | null;
+    tokenCount: number | null;
+    toolCallCount: number | null;
+    durationMs: number | null;
+    gitBranch: string | null;
+    projectName: string | null;
+    tags: TagPayload[];
+    owner: ExploreOwnerPayload;
+};
+/**
+ * Paginated list of transcripts for the Explore browse view.
+ * Cooked from TranscriptListResponse.
+ */
+export type ExploreTranscriptListPayload = {
+    transcripts: ExploreTranscriptPayload[];
+    /**
+     * total matching transcripts (for pagination)
+     */
+    total: number;
+    /**
+     * current page (1-based)
+     */
+    page: number;
+    /**
+     * page size
+     */
+    limit: number;
+};
+/**
+ * One collective result from a collective search (useSearchCollectives).
+ * Cooked from CollectiveSearchResult (frontend/src/lib/types.ts).
+ */
+export type CollectiveResultPayload = {
+    id: string;
+    name: string;
+    description: string | null;
+    linkedGithubOrg: string | null;
+    memberCount: number;
+    transcriptCount: number;
+};
+/**
+ * One popular tag with its usage count.
+ * Cooked from TagWithCount (frontend/src/lib/types.ts).
+ */
+export type PopularTagPayload = {
+    id: string;
+    name: string;
+    usageCount: number;
+};
+/**
+ * The Explore surface prop payload. The adapter maps the three hook results
+ * (useTranscripts, useSearchCollectives, usePopularTags) into this single
+ * cooked shape; the lifted <Explore> component never calls hooks directly.
+ *
+ * Query parameters (q, sort, page, provider, tags) are not embedded in the
+ * payload — they live as component-level props that the host passes alongside
+ * the payload (the adapter is called when any of them changes).
+ */
+export type ExplorePayload = {
+    /**
+     * browsing results (page + facet filters applied)
+     */
+    transcripts: ExploreTranscriptListPayload;
+    /**
+     * collective search results (empty when no query)
+     */
+    collectives: CollectiveResultPayload[];
+    /**
+     * top tags for the facet rail (cap set by caller)
+     */
+    popularTags: PopularTagPayload[];
+};
+/**
+ * One member of a collective.
+ * Cooked from GroupMember (frontend/src/lib/types.ts).
+ */
+export type CollectiveMemberPayload = {
+    id: string;
+    githubUsername: string;
+    displayName: string | null;
+    avatarUrl: string | null;
+    /**
+     * owner/member/contributor for the members list; "pending" for the pendingMembers list
+     */
+    role: CollectiveRole;
+    /**
+     * ISO-8601 datetime
+     */
+    joinedAt: string;
+};
+/**
+ * One transcript published to the collective (lightweight row).
+ * Cooked from GroupTranscript (which extends Transcript with owner fields).
+ */
+export type CollectiveTranscriptPayload = {
+    id: string;
+    title: string | null;
+    visibility: TranscriptVisibility;
+    modelProvider: string;
+    modelName: string | null;
+    /**
+     * ISO-8601 datetime or null
+     */
+    sessionStart: string | null;
+    turnCount: number | null;
+    tokenCount: number | null;
+    ownerUsername: string;
+    ownerAvatarUrl: string | null;
+};
+/**
+ * Aggregate statistics for a collective's transcript corpus.
+ * Mirrors GroupTranscriptStats from frontend/src/lib/types.ts.
+ */
+export type CollectiveStatsPayload = {
+    totalTranscripts: number;
+    contributorCount: number;
+    totalTurns: number;
+    totalDurationMs: number;
+    totalTokens: number;
+};
+/**
+ * Model usage breakdown for a collective.
+ * Mirrors GroupModelBreakdown from frontend/src/lib/types.ts.
+ */
+export type CollectiveModelBreakdownPayload = {
+    modelProvider: string;
+    transcriptCount: number;
+};
+/**
+ * One contributor to a collective's transcript corpus.
+ * Mirrors GroupContributor from frontend/src/lib/types.ts.
+ */
+export type CollectiveContributorPayload = {
+    id: string;
+    githubUsername: string;
+    avatarUrl: string | null;
+    transcriptCount: number;
+};
+/**
+ * The collective's own metadata.
+ * Cooked from Group (frontend/src/lib/types.ts): snake_case → camelCase.
+ */
+export type CollectivePayload = {
+    id: string;
+    name: string;
+    description: string | null;
+    linkedGithubOrg: string | null;
+    displayMembers: boolean;
+    transcriptDeletionPolicy: TranscriptDeletionPolicy;
+    /**
+     * user id of the creator
+     */
+    createdBy: string;
+    /**
+     * ISO-8601 datetime
+     */
+    createdAt: string;
+    /**
+     * ISO-8601 datetime
+     */
+    updatedAt: string;
+    acceptanceMode: AcceptanceMode;
+    dataAccess: DataAccessPolicy;
+    /**
+     * the authenticated viewer's role; "" when not a member / anonymous
+     */
+    role: ViewerRole;
+    /**
+     * ISO-8601 datetime when the user joined; null if not a member
+     */
+    memberSince: string | null;
+};
+/**
+ * The Manage surface prop payload. The adapter maps the useGroup hook result
+ * into this single cooked shape; the lifted <Manage> component never calls
+ * hooks directly.
+ *
+ * Mutation callbacks (onCreateGroup, onUpdateGroup, onJoinGroup,
+ * onPromoteMember, onRemoveMember, onAddMember, onDeleteGroup) are
+ * component-level props defined in the surface slice — NOT fields in this
+ * payload. The payload carries only the READ data model.
+ *
+ * FIXTURE GAP: pendingMembers is optional on the wire (`pending_members?`)
+ * and absent from the current mock fixture. The adapter normalizes it to `[]`
+ * when absent; the mock fixture must be filled by the surface slice worker.
+ */
+export type ManagePayload = {
+    collective: CollectivePayload;
+    /**
+     * approved members
+     */
+    members: CollectiveMemberPayload[];
+    /**
+     * pending join requests (may be [] when not yet seeded)
+     */
+    pendingMembers: CollectiveMemberPayload[];
+    /**
+     * published transcripts (paginated externally)
+     */
+    transcripts: CollectiveTranscriptPayload[];
+    stats: CollectiveStatsPayload;
+    /**
+     * usage breakdown by model provider
+     */
+    models: CollectiveModelBreakdownPayload[];
+    contributors: CollectiveContributorPayload[];
+    /**
+     * authenticated viewer's role; "" when not a member / anonymous
+     */
+    yourRole: ViewerRole;
+};

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

@@ -0,0 +1,28 @@
+/**
+ * @param {object} props
+ * @param {import('./types.js').ChangeDetailPayload} props.payload  the cooked change-detail payload
+ * @param {(file: import('./types.js').FileChangePayload) => import('./types.js').ChangeDiffPayload | null | undefined} [props.getDiff]
+ *   resolve the lazy per-file diff (the separate ChangeDiffPayload) for an opened file; return
+ *   null/undefined while loading, or a ChangeDiffPayload whose host-side `error` sentinel is set
+ *   (with empty hunks) when the fetch failed — the surface then renders an error row, not a spinner
+ * @param {string} [props.title]  editorial title; default derived from the branch name
+ * @param {string} [props.annotation]  the saved user label (host-owned)
+ * @param {(value: string) => void} [props.onSaveAnnotation]
+ * @param {() => void} [props.onRemoveAnnotation]
+ * @param {() => void} [props.onOpenMap]    the "see this work on the code map" exit (host owns the route)
+ * @param {() => void} [props.onShare]      the "share … conversations" exit (host owns share UX)
+ * @param {() => void} [props.onCopyRecap]  the "copy recap" exit (host owns the clipboard recap)
+ * @param {Record<string, boolean>} [props.initialOpenFiles]  files open on first render (path → open?)
+ */
+export default function ChangeDetail({ payload, getDiff, title, annotation, onSaveAnnotation, onRemoveAnnotation, onOpenMap, onShare, onCopyRecap, initialOpenFiles, }: {
+    payload: import("./types.js").ChangeDetailPayload;
+    getDiff?: (file: import("./types.js").FileChangePayload) => import("./types.js").ChangeDiffPayload | null | undefined;
+    title?: string;
+    annotation?: string;
+    onSaveAnnotation?: (value: string) => void;
+    onRemoveAnnotation?: () => void;
+    onOpenMap?: () => void;
+    onShare?: () => void;
+    onCopyRecap?: () => void;
+    initialOpenFiles?: Record<string, boolean>;
+}): any;

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

@@ -0,0 +1,21 @@
+/**
+ * @param {object} props
+ * @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 {boolean} [props.hasMore]  more history exists below the window (→ "show older")
+ * @param {() => void} [props.onShowOlder]  "show older" was pressed
+ * @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, }: {
+    payload: import("./types.js").ChangesPayload;
+    projectLabel?: string;
+    selectedId?: string;
+    onSelectChange?: (commit: import("./changeGraph.js").CommitGraphRow) => void;
+    onOpenMap?: () => void;
+    hasMore?: boolean;
+    onShowOlder?: () => void;
+    nowMs?: number;
+}): any;

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

@@ -0,0 +1,49 @@
+/**
+ * CodeMap — the lifted code-topology surface over the shared MapCanvas.
+ *
+ * The payload remains the cooked topology contract from @peasant-labs/fairtrade/graph:
+ * geometry stays derived here, activity edges stay in the host rail, and the host
+ * feeds interaction state through props so demo and app render the same behavior.
+ *
+ * @param {object} props
+ * @param {import('./types.js').CodeMapPayload} props.payload
+ * @param {{level:'project'|'package'|'file', expanded?: Iterable<string>}} [props.zoom]
+ * @param {(zoom:{level:'project'|'package'|'file', expanded:string[]})=>void} [props.onZoomChange]
+ * @param {string|null} [props.selectedId]
+ * @param {(id:string|null, node:import('./types.js').MapNodePayload|null)=>void} [props.onSelect]
+ * @param {(id:string)=>void} [props.onExpand]
+ * @param {Iterable<string>} [props.highlightedIds]
+ * @param {Record<string,'new'|'removed'>} [props.nodeDeltas]
+ * @param {Record<string,'new'|'removed'>} [props.structureEdgeDeltas]
+ * @param {number|string} [props.height]
+ * @param {string} [props.ariaLabel]
+ * @param {string} [props.className]
+ */
+export default function CodeMap({ payload, zoom, onZoomChange, selectedId, onSelect, onExpand, highlightedIds, nodeDeltas, structureEdgeDeltas, height, ariaLabel, className, }: {
+    payload: import("./types.js").CodeMapPayload;
+    zoom?: {
+        level: "project" | "package" | "file";
+        expanded?: Iterable<string>;
+    };
+    onZoomChange?: (zoom: {
+        level: "project" | "package" | "file";
+        expanded: string[];
+    }) => void;
+    selectedId?: string | null;
+    onSelect?: (id: string | null, node: import("./types.js").MapNodePayload | null) => void;
+    onExpand?: (id: string) => void;
+    highlightedIds?: Iterable<string>;
+    nodeDeltas?: Record<string, "new" | "removed">;
+    structureEdgeDeltas?: Record<string, "new" | "removed">;
+    height?: number | string;
+    ariaLabel?: string;
+    className?: string;
+}): any;
+/**
+ * @param {import('./types.js').CodeMapPayload | undefined} payload
+ * @returns {{nodes: Array<object>, edges: Array<object>}}
+ */
+export function codeMapPayloadToMapData(payload: import("./types.js").CodeMapPayload | undefined): {
+    nodes: Array<object>;
+    edges: Array<object>;
+};

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

@@ -0,0 +1,85 @@
+/**
+ * CodeMapComposition — the FULL map surface (full-lift): the
+ * RailShell frame (sticky toolbar + canvas + rail), the persistent visual-
+ * channel legend, and the shared <CodeMap> canvas, composed once here so the
+ * demo GraphMap mockup and every consuming app (peasant, village) render the
+ * SAME toolbar/rail-shell/legend/interaction composition — not just the same
+ * canvas wrapped in each host's own hand-rolled shell.
+ *
+ * Before this component, only the canvas itself (<CodeMap>) was shared; the
+ * surrounding toolbar, rail shell, and legend were reimplemented per host
+ * (review finding: "CodeMap boundary only lifts the canvas wrapper").
+ * Composition-level pieces that are inherently
+ * host-specific — the RAIL's content (real API data vs. demo mock data) and
+ * the canvas region's loading/empty/error states (peasant's WS/REST fetch
+ * lifecycle vs. the demo's static fixture) — stay host-owned via the `rail`
+ * and `canvasSlot` slots below; everything else (frame, legend, interaction
+ * wiring) is now ONE implementation.
+ *
+ * @param {object} props
+ * @param {import('./types.js').CodeMapPayload} [props.payload]              forwarded to <CodeMap> when `canvasSlot` is omitted
+ * @param {{level:'project'|'package'|'file', expanded?: Iterable<string>}} [props.zoom]
+ * @param {(zoom:{level:'project'|'package'|'file', expanded:string[]})=>void} [props.onZoomChange]
+ * @param {string|null} [props.selectedId]
+ * @param {(id:string|null, node:import('./types.js').MapNodePayload|null)=>void} [props.onSelect]
+ * @param {(id:string)=>void} [props.onExpand]
+ * @param {Iterable<string>} [props.highlightedIds]
+ * @param {Record<string,'new'|'removed'>} [props.nodeDeltas]
+ * @param {Record<string,'new'|'removed'>} [props.structureEdgeDeltas]
+ * @param {number|string} [props.height=480]                canvas height, forwarded to <CodeMap>
+ * @param {string} [props.ariaLabel='code map']              forwarded to <CodeMap>
+ * @param {React.ReactNode} [props.canvasSlot]                override the canvas region entirely
+ *   (e.g. a host's loading/disconnected/error states); when omitted, renders
+ *   <CodeMap> from the props above — the demo mockup and any host without
+ *   custom fetch-lifecycle states can rely on the default.
+ * @param {React.ReactNode} props.rail                        the rail's content (host-specific:
+ *   real API data vs. demo mock data) — compose with the kit's <RailSection>.
+ * @param {React.ReactNode} [props.toolbar]                   optional extra sticky toolbar content
+ *   ABOVE the canvas (e.g. a connection indicator) — the canvas's OWN shared
+ *   grain/search toolbar (owned by <CodeMap>/<MapCanvas>) is unaffected either way.
+ * @param {string} [props.sheetTitle='code area']              RailShell's mobile bottom-sheet title
+ * @param {React.ReactNode} [props.sheetMeta]
+ * @param {'left'|'right'} [props.railSide='right']
+ * @param {React.ReactNode|false} [props.legend]               override the default legend; `false` hides it
+ * @param {string} [props.canvasWrapperClassName]              extra class on the canvas region wrapper
+ * @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
+ */
+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, }: {
+    payload?: import("./types.js").CodeMapPayload;
+    zoom?: {
+        level: "project" | "package" | "file";
+        expanded?: Iterable<string>;
+    };
+    onZoomChange?: (zoom: {
+        level: "project" | "package" | "file";
+        expanded: string[];
+    }) => void;
+    selectedId?: string | null;
+    onSelect?: (id: string | null, node: import("./types.js").MapNodePayload | null) => void;
+    onExpand?: (id: string) => void;
+    highlightedIds?: Iterable<string>;
+    nodeDeltas?: Record<string, "new" | "removed">;
+    structureEdgeDeltas?: Record<string, "new" | "removed">;
+    height?: number | string;
+    ariaLabel?: string;
+    canvasSlot?: React.ReactNode;
+    rail: React.ReactNode;
+    toolbar?: React.ReactNode;
+    sheetTitle?: string;
+    sheetMeta?: React.ReactNode;
+    railSide?: "left" | "right";
+    legend?: React.ReactNode | false;
+    canvasWrapperClassName?: string;
+    canvasWrapperStyle?: React.CSSProperties;
+    className?: string;
+}): any;
+/**
+ * The persistent legend explaining the canvas's four orthogonal visual channels
+ * (peasant spec §4/§5: WIDTH ∝ loc, monochrome FILL ∝ coverage, folder/file ICON,
+ * amber SELECTION, clay VIOLATION badge) — so the picture never needs decoding.
+ * Lifted here from the peasant app (was app-only chrome, spec-legend drift risk)
+ * so demo and every consuming app show the SAME legend for the SAME canvas.
+ */
+export function DefaultMapLegend(): any;

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

@@ -0,0 +1,106 @@
+/**
+ * Humanise an absolute epoch-ms time into a short relative label ("5h ago",
+ * "3d ago", "1wk ago"). Pure: depends only on (timeMs, nowMs). Returns '' when
+ * the time is missing so the kit simply omits the label.
+ *
+ * @param {number | null | undefined} timeMs
+ * @param {number} nowMs
+ * @returns {string}
+ */
+export function humanizeAge(timeMs: number | null | undefined, nowMs: number): string;
+/**
+ * Derive the CommitGraph dataset (+ reverted list + counts) from a ChangesPayload.
+ *
+ * Lane assignment is deterministic: open changes sort by tip time (newest first,
+ * branch name as a tiebreak) and take lanes 1..N in that order. Each open change
+ * contributes a tip row inserted just above the first recent commit at/older than
+ * its tip time; its `parents` point at its merge-base (baseHash) when that commit
+ * is in the window. Merged changes flip `merged` on their merge commit and add the
+ * (synthetic) branch tip as a second parent so the kit draws the join elbow.
+ *
+ * @param {ChangesPayload} payload
+ * @param {{ nowMs: number }} opts  `nowMs` pins relative-time humanisation (determinism)
+ * @returns {ChangesGraph}
+ */
+export function buildChangesGraph(payload: ChangesPayload, { nowMs }: {
+    nowMs: number;
+}): ChangesGraph;
+export type ChangesPayload = import("./types.js").ChangesPayload;
+export type ChangeSummaryPayload = import("./types.js").ChangeSummaryPayload;
+export type CommitRefPayload = import("./types.js").CommitRefPayload;
+/**
+ * One row in the kit CommitGraph dataset (mirrors the `Commit` shape documented
+ * on src/ui/CommitGraph.jsx). Time order = array order (newest first); the graph
+ * is implicit in `lane` + `parents`.
+ */
+export type CommitGraphRow = {
+    /**
+     * stable key (commit hash, or `tip:<branch>` for an open tip)
+     */
+    id: string;
+    /**
+     * 0 = the default-branch line; >0 = a branch lane
+     */
+    lane: number;
+    /**
+     * parent row ids (>1 ⇒ a merge)
+     */
+    parents?: string[];
+    /**
+     * the commit subject / branch label (USER CONTENT — case preserved)
+     */
+    message: string;
+    /**
+     * branch name chip (USER CONTENT — case preserved)
+     */
+    branch?: string;
+    /**
+     * a recorded session sits behind this commit (→ filled dot + sparkle)
+     */
+    session?: boolean;
+    /**
+     * this commit merged a branch back in (→ merged chip)
+     */
+    merged?: boolean;
+    /**
+     * this row is an open branch tip (→ tip affordance)
+     */
+    tip?: boolean;
+    /**
+     * humanised relative time (e.g. "5h ago")
+     */
+    time?: string;
+};
+/**
+ * A reverted line of work, surfaced under the graph (the demo's "reverted" chip).
+ */
+export type RevertedChange = {
+    branch: string;
+    mergedAtMs?: number | null;
+    /**
+     * humanised relative time of the merge
+     */
+    when?: string;
+};
+/**
+ * The derived Changes view model: the CommitGraph dataset + the reverted list +
+ * the head counts the surface caption shows.
+ */
+export type ChangesGraph = {
+    /**
+     * newest first; lane 0 is the default branch
+     */
+    commits: CommitGraphRow[];
+    /**
+     * merged-then-reverted changes (listed under the graph)
+     */
+    reverted: RevertedChange[];
+    /**
+     * number of open changes
+     */
+    openCount: number;
+    /**
+     * number of merged changes
+     */
+    mergedCount: number;
+};

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

@@ -0,0 +1,30 @@
+export { default as Changes } from "./Changes.jsx";
+export { default as ChangeDetail } from "./ChangeDetail.jsx";
+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 MapEdgePayload = import("./types.js").MapEdgePayload;
+export type ActivityEdgePayload = import("./types.js").ActivityEdgePayload;
+export type EdgeViolationPayload = import("./types.js").EdgeViolationPayload;
+export type MapNodePayload = import("./types.js").MapNodePayload;
+export type MapSlicePayload = import("./types.js").MapSlicePayload;
+export type ChangeSummaryPayload = import("./types.js").ChangeSummaryPayload;
+export type ChangesPayload = import("./types.js").ChangesPayload;
+export type TaskSummaryPayload = import("./types.js").TaskSummaryPayload;
+export type ChangeSessionPayload = import("./types.js").ChangeSessionPayload;
+export type UnusualSignalPayload = import("./types.js").UnusualSignalPayload;
+export type FrictionClusterPayload = import("./types.js").FrictionClusterPayload;
+export type FileChangePayload = import("./types.js").FileChangePayload;
+export type ChangeDetailPayload = import("./types.js").ChangeDetailPayload;
+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 { default as CodeMap, codeMapPayloadToMapData } from "./CodeMap.jsx";
+export { default as CodeMapComposition, DefaultMapLegend } from "./CodeMapComposition.jsx";
+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";