@peasant-labs/fairtrade 0.0.5 → 0.0.7

package/dist/lib/types/transcript/TranscriptViewer.d.ts

@@ -1,6 +1,6 @@
 /**
  * @param {TranscriptViewerProps} props
  */
-export default function TranscriptViewer({ viewModel, capabilities, callbacks, theme: themeProp, onThemeChange, graphSlot, activeTab: activeTabProp, onTabChange, viewMode: viewModeProp, onViewModeChange, leftRailOpen: leftRailOpenProp, onLeftRailOpenChange, rightRailOpen: rightRailOpenProp, onRightRailOpenChange, openTools: openToolsProp, onOpenToolsChange, activeTurn: activeTurnProp, onActiveTurnChange, search: searchProp, onSearchChange, filters: filtersProp, onFiltersChange, savedLabels: savedLabelsProp, onSavedLabelsChange, shareOpen: shareOpenProp, onShareOpenChange, moreOpen: moreOpenProp, onMoreOpenChange, }: TranscriptViewerProps): any;
+export default function TranscriptViewer({ viewModel, capabilities, callbacks, theme: themeProp, onThemeChange, graphSlot, activeTab: activeTabProp, onTabChange, viewMode: viewModeProp, onViewModeChange, leftRailOpen: leftRailOpenProp, onLeftRailOpenChange, rightRailOpen: rightRailOpenProp, onRightRailOpenChange, openTools: openToolsProp, onOpenToolsChange, initialPosition: initialPositionProp, activeTurn: activeTurnProp, onActiveTurnChange, search: searchProp, onSearchChange, filters: filtersProp, onFiltersChange, savedLabels: savedLabelsProp, onSavedLabelsChange, shareOpen: shareOpenProp, onShareOpenChange, moreOpen: moreOpenProp, onMoreOpenChange, breadcrumb, LinkComponent, renderTurnPanel, renderTurnActions, anchorHref, headerActions, streamPrelude, }: TranscriptViewerProps): any;
 export type TranscriptViewerProps = import("./state-capabilities.js").TranscriptViewerProps;
 export type TranscriptFilters = import("./state-capabilities.js").TranscriptFilters;

package/dist/lib/types/transcript/TurnCard.d.ts

@@ -8,11 +8,12 @@
  * @param {boolean} [props.copied]
  * @param {(turnIndex: number, el: HTMLElement | null) => void} [props.registerRef]
  * @param {(turnIndex: number) => void} [props.onLabel]   omit to hide the "label" affordance
+ * @param {(turn: object) => unknown} [props.renderActions]  host-owned per-turn actions; replaces the built-in label button (hosts with their own label models render their own popover)
  * @param {{ outcome: string, flag?: string }} [props.savedLabel]
  * @param {boolean} [props.compact]
  * @param {boolean} [props.expandAll]
  */
-export default function TurnCard({ turn, active, openTools, toggleTool, onCopyAnchor, copied, registerRef, onLabel, savedLabel, compact, expandAll, }: {
+export default function TurnCard({ turn, active, openTools, toggleTool, onCopyAnchor, copied, registerRef, onLabel, renderActions, savedLabel, compact, expandAll, }: {
     turn?: TurnVM;
     active?: boolean;
     openTools?: Record<string, boolean>;
@@ -21,6 +22,7 @@ export default function TurnCard({ turn, active, openTools, toggleTool, onCopyAn
     copied?: boolean;
     registerRef?: (turnIndex: number, el: HTMLElement | null) => void;
     onLabel?: (turnIndex: number) => void;
+    renderActions?: (turn: object) => unknown;
     savedLabel?: {
         outcome: string;
         flag?: string;

package/dist/lib/types/transcript/adapter.d.ts

@@ -21,9 +21,9 @@ export function diffLines(oldText: string, newText: string): DiffLineVM[];
 /**
  * Project the canonical wire payload (folded turns) into the cooked
  * `TranscriptViewModel` every dumb transcript component renders. The SOLE
- * wire-parse + git-drift normalisation site.
+ * wire-parse + legacy-git normalisation site.
  *
- * @param {TranscriptWireInput} payload          canonical wire; tolerates both git shapes
+ * @param {TranscriptWireInput} payload          canonical wire plus legacy git compatibility
  * @param {AnnotationSummary[]} [annotations]     separately-fetched entry annotations
  * @param {TranscriptAnalyticsVM} [analytics]     precomputed analytics; else derived on demand
  * @returns {TranscriptViewModel}
@@ -34,6 +34,9 @@ export type SessionDetailPayload = import("./wire-types.js").SessionDetailPayloa
 export type TurnDetail = import("./wire-types.js").TurnDetail;
 export type ToolCallDetail = import("./wire-types.js").ToolCallDetail;
 export type AnnotationSummary = import("./wire-types.js").AnnotationSummary;
+export type CommitInfo = import("./wire-types.js").CommitInfo;
+export type LegacyCommit = import("./wire-types.js").LegacyCommit;
+export type LegacyGitContext = import("./wire-types.js").LegacyGitContext;
 export type TranscriptViewModel = import("./view-model.js").TranscriptViewModel;
 export type TranscriptAnalyticsVM = import("./view-model.js").TranscriptAnalyticsVM;
 export type SessionVM = import("./view-model.js").SessionVM;
@@ -50,41 +53,3 @@ export type AnnotationVM = import("./view-model.js").AnnotationVM;
 export type HighlightVM = import("./view-model.js").HighlightVM;
 export type FilterIndexVM = import("./view-model.js").FilterIndexVM;
 export type PhaseVM = import("./view-model.js").PhaseVM;
-export type WireGitLike = {
-    branch?: string | null;
-    remote?: string | null;
-    /**
-     * TS-drift author (transcript.ts)
-     */
-    user?: string;
-    commits?: unknown[];
-};
-export type WireCommitLike = {
-    hash?: string;
-    message?: string;
-    /**
-     * Go shape (metadata.go)
-     */
-    authorName?: string;
-    /**
-     * Go shape, Unix millis
-     */
-    commitTime?: number;
-    /**
-     * TS-drift shape (transcript.ts)
-     */
-    timestamp?: string;
-    /**
-     * TS-drift per-commit churn
-     */
-    filesChanged?: number;
-    /**
-     * TS-drift per-commit churn
-     */
-    insertions?: number;
-    /**
-     * TS-drift per-commit churn
-     */
-    deletions?: number;
-    session?: boolean;
-};

package/dist/lib/types/transcript/graph/GraphLegend.d.ts

@@ -10,7 +10,7 @@ export function GraphLegend({ items, className }: GraphLegendProps): JSX.Element
  * @property {'user' | 'assistant' | 'subagent' | 'tool' | 'error' | (string & {})} kind
  *   the node kind this swatch stands for; selects the accent
  * @property {string} label                    the lowercase word shown beside the swatch
- * @property {string} [provider]               harness key → assistant swatch accent
+ * @property {import('@peasant-labs/schema').Harness} [provider] canonical harness → assistant swatch accent
  */
 /**
  * @typedef {object} GraphLegendProps
@@ -36,9 +36,9 @@ export type GraphLegendItem = {
      */
     label: string;
     /**
-     * harness key → assistant swatch accent
+     * canonical harness → assistant swatch accent
      */
-    provider?: string;
+    provider?: import("@peasant-labs/schema").Harness;
 };
 export type GraphLegendProps = {
     /**

package/dist/lib/types/transcript/graph/GraphTurnNode.d.ts

@@ -66,9 +66,9 @@ export type GraphTurnNodeProps = {
      */
     isSelected?: boolean;
     /**
-     * harness key (e.g. "claude-code") → assistant accent
+     * canonical harness → assistant accent
      */
-    provider?: string;
+    provider?: import("@peasant-labs/schema").Harness;
     /**
      * extra classes appended after the base
      */

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

@@ -14,6 +14,7 @@ export { default as TranscriptViewSwitch } from "./ViewSwitch.jsx";
 export { default as TranscriptScrubber } from "./Scrubber.jsx";
 export { default as TranscriptScorecard } from "./Scorecard.jsx";
 export { default as TranscriptLabelPopover } from "./LabelPopover.jsx";
+export { default as useTranscriptInitialPosition } from "./useTranscriptInitialPosition.jsx";
 export type TaskGroup = import("./analytics.js").TaskGroup;
 export type WaterfallSegment = import("./analytics.js").WaterfallSegment;
 export type TranscriptAnnotation = import("./analytics.js").TranscriptAnnotation;
@@ -31,11 +32,12 @@ export type TurnDetail = import("./wire-types.js").TurnDetail;
 export type ChildSessionRef = import("./wire-types.js").ChildSessionRef;
 export type SessionScorecard = import("./wire-types.js").SessionScorecard;
 export type CommitInfo = import("./wire-types.js").CommitInfo;
-export type GitContext = import("./wire-types.js").GitContext;
 export type AnnotationSummary = import("./wire-types.js").AnnotationSummary;
 export type SessionDetailPayload = import("./wire-types.js").SessionDetailPayload;
 export type TranscriptWireInput = import("./wire-types.js").TranscriptWireInput;
 export type TranscriptViewerProps = import("./state-capabilities.js").TranscriptViewerProps;
+export type TranscriptInitialPosition = import("./state-capabilities.js").TranscriptInitialPosition;
+export type BreadcrumbItem = import("./state-capabilities.js").BreadcrumbItem;
 export type ViewerCapabilities = import("./state-capabilities.js").ViewerCapabilities;
 export type ViewerCallbacks = import("./state-capabilities.js").ViewerCallbacks;
 export type GraphSlotContext = import("./state-capabilities.js").GraphSlotContext;
@@ -67,3 +69,4 @@ export { ROLES, ENTRY_TYPES, TOOL_CALL_KINDS, STOP_REASONS, SESSION_OUTCOMES, HA
 export { adaptTranscript, prefilterTurns, diffLines } from "./adapter.js";
 export { computeTasks, computeTurnLabels, buildTaskWaterfall, annotateTranscript, computePersonalMedians, detectPhases, assessScorecard, computeAnalytics, computeTaskGroups, phaseLabel } from "./analytics.js";
 export { default as TranscriptDiffEntryCard, DiffHunks as TranscriptDiffHunks } from "./DiffEntryCard.jsx";
+export { advanceTranscriptInitialPositionConsumption, normalizeTranscriptInitialPosition, resolveTranscriptInitialPosition, shouldApplyTranscriptInitialPosition, transcriptInitialPositionReadiness, transcriptInitialPositionToken } from "./initial-position.js";

package/dist/lib/types/transcript/initial-position.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Fail-closed normalization for the public one-time positioning contract.
+ * Only exact own-key shapes are accepted.
+ *
+ * @param {unknown} value
+ * @returns {TranscriptInitialPosition | null}
+ */
+export function normalizeTranscriptInitialPosition(value: unknown): TranscriptInitialPosition | null;
+/**
+ * Pure precedence transition used by the React hook. Keeping this outside the
+ * hook makes explicit/fallback/legacy ownership executable without copying the
+ * controller into consumer tests.
+ *
+ * @param {{
+ *   initialPosition: unknown,
+ *   fallbackInitialPosition: unknown,
+ *   legacyInitialPosition: unknown,
+ *   explicitUsed: boolean,
+ *   fallbackUsed: boolean,
+ * }} input
+ * @returns {{explicitUsed: boolean, fallbackUsed: boolean, position: TranscriptInitialPosition | null}}
+ */
+export function resolveTranscriptInitialPosition(input: {
+    initialPosition: unknown;
+    fallbackInitialPosition: unknown;
+    legacyInitialPosition: unknown;
+    explicitUsed: boolean;
+    fallbackUsed: boolean;
+}): {
+    explicitUsed: boolean;
+    fallbackUsed: boolean;
+    position: TranscriptInitialPosition | null;
+};
+/**
+ * Pure authoritative/readiness decision shared by both transcript viewers.
+ * Side effects remain in each renderer, but only this function decides when a
+ * request is pending, terminally absent, or ready to apply.
+ *
+ * @param {TranscriptInitialPosition} position
+ * @param {{
+ *   authoritativeTurnIndices: readonly number[],
+ *   renderedTurnIndices: readonly number[],
+ *   viewReady: boolean,
+ *   scrollerReady: boolean,
+ *   targetReady: boolean,
+ * }} state
+ * @returns {TranscriptInitialPositionResult}
+ */
+export function transcriptInitialPositionReadiness(position: TranscriptInitialPosition, state: {
+    authoritativeTurnIndices: readonly number[];
+    renderedTurnIndices: readonly number[];
+    viewReady: boolean;
+    scrollerReady: boolean;
+    targetReady: boolean;
+}): TranscriptInitialPositionResult;
+/**
+ * @param {string | undefined} sessionId
+ * @param {TranscriptInitialPosition | null} position
+ * @returns {string | null}
+ */
+export function transcriptInitialPositionToken(sessionId: string | undefined, position: TranscriptInitialPosition | null): string | null;
+/**
+ * @param {unknown} result
+ * @returns {asserts result is TranscriptInitialPositionResult}
+ */
+export function assertTranscriptInitialPositionResult(result: unknown): asserts result is TranscriptInitialPositionResult;
+/**
+ * @param {string | null} consumedToken
+ * @param {string | null} nextToken
+ */
+export function shouldApplyTranscriptInitialPosition(consumedToken: string | null, nextToken: string | null): boolean;
+/**
+ * @param {string | null} consumedToken
+ * @param {string | null} nextToken
+ * @param {TranscriptInitialPositionResult} result
+ * @returns {string | null}
+ */
+export function advanceTranscriptInitialPositionConsumption(consumedToken: string | null, nextToken: string | null, result: TranscriptInitialPositionResult): string | null;
+export type TranscriptInitialPosition = import("./state-capabilities.js").TranscriptInitialPosition;
+export type TranscriptInitialPositionResult = "pending" | "applied" | "discarded";

package/dist/lib/types/transcript/state-capabilities.d.ts

@@ -91,13 +91,26 @@ export type ViewerCallbacks = {
 /**
  * What the `graphSlot` render-prop receives. The composite owns NO graph engine
  * (no `@xyflow` dependency); in `viewMode: 'graph'` it hands the consumer this
- * cooked context and renders whatever the consumer returns (TB plugs its
+ * cooked context and renders whatever the consumer returns (transcript-browser plugs its
  */
 export type GraphSlotContext = {
     viewModel: import("./view-model.js").TranscriptViewModel;
     activeTurn: number;
     onSelectTurn: (turnIndex: number) => void;
 };
+/**
+ * A one-time position applied when a transcript target is first presented.
+ * This is deliberately separate from `activeTurn`, which represents ongoing
+ * selection while the user reads or navigates the transcript.
+ */
+export type TranscriptInitialPosition = {
+    kind: "top";
+    requestKey?: string;
+} | {
+    kind: "turn";
+    turnIndex: number;
+    requestKey?: string;
+};
 /**
  * Every TranscriptViewer prop. `viewModel` + `capabilities` are the only required
  * props; everything else is optional with a sane internal default, so
@@ -137,6 +150,10 @@ export type TranscriptViewerProps = {
      */
     openTools?: Record<string, boolean>;
     onOpenToolsChange?: (openTools: Record<string, boolean>) => void;
+    /**
+     * one-time position; null clears, and session/target/requestKey changes rearm
+     */
+    initialPosition?: TranscriptInitialPosition | null;
     activeTurn?: number;
     onActiveTurnChange?: (turnIndex: number) => void;
     search?: string;
@@ -158,4 +175,39 @@ export type TranscriptViewerProps = {
      */
     moreOpen?: boolean;
     onMoreOpenChange?: (open: boolean) => void;
+    /**
+     * host-routable trail; omit for the demo's static crumb
+     */
+    breadcrumb?: BreadcrumbItem[];
+    /**
+     * router link for crumb items (e.g. next/link); defaults to 'a'
+     */
+    LinkComponent?: any;
+    /**
+     * host per-turn extension rendered under each turn card
+     */
+    renderTurnPanel?: (turn: import("./view-model.js").TurnVM) => unknown;
+    /**
+     * host-owned per-turn actions; replaces the built-in label affordance (hosts with typed label models keep their own popovers)
+     */
+    renderTurnActions?: (turn: import("./view-model.js").TurnVM) => unknown;
+    /**
+     * host permalink for a turn's copy-anchor action; a root-relative return is absolutized against the page origin. Omitted, the demo copies its bare '#turn-N' placeholder
+     */
+    anchorHref?: (turnIndex: number) => string;
+    /**
+     * host session-level actions rendered at the head of the hero action row (attest etc.); the composite's own actions stay the shared tail
+     */
+    headerActions?: unknown;
+    /**
+     * host controls or context rendered at the start of the list-mode transcript scroller; omitted in graph mode
+     */
+    streamPrelude?: unknown;
+};
+/**
+ * One breadcrumb segment. The last item renders as the current page (no link).
+ */
+export type BreadcrumbItem = {
+    label: string;
+    href?: string;
 };

package/dist/lib/types/transcript/useTranscriptInitialPosition.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Canonical layout consumer for transcript initial positions. It owns the
+ * legacy mount snapshot, explicit-contract latch, null reset, token, consumed
+ * state, StrictMode replay guard, readiness retries, and terminal consumption.
+ *
+ * @param {{
+ *   sessionId?: string,
+ *   initialPosition?: import('./state-capabilities.js').TranscriptInitialPosition | null,
+ *   fallbackInitialPosition?: import('./state-capabilities.js').TranscriptInitialPosition | null,
+ *   legacyInitialPosition?: import('./state-capabilities.js').TranscriptInitialPosition | null,
+ *   readiness: readonly unknown[],
+ *   apply: (position: import('./state-capabilities.js').TranscriptInitialPosition) => 'pending' | 'applied' | 'discarded',
+ * }} options
+ * @returns {{position: import('./state-capabilities.js').TranscriptInitialPosition | null, token: string | null}}
+ */
+export default function useTranscriptInitialPosition(options: {
+    sessionId?: string;
+    initialPosition?: import("./state-capabilities.js").TranscriptInitialPosition | null;
+    fallbackInitialPosition?: import("./state-capabilities.js").TranscriptInitialPosition | null;
+    legacyInitialPosition?: import("./state-capabilities.js").TranscriptInitialPosition | null;
+    readiness: readonly unknown[];
+    apply: (position: import("./state-capabilities.js").TranscriptInitialPosition) => "pending" | "applied" | "discarded";
+}): {
+    position: import("./state-capabilities.js").TranscriptInitialPosition | null;
+    token: string | null;
+};

package/dist/lib/types/transcript/view-model.d.ts

@@ -1,15 +1,15 @@
 /**
  * Cooked git chrome for the session header. Produced by the adapter from
- * whichever wire shape is present — flat `gitBranch`/`gitRemote` OR nested
+ * whichever wire shape is present — canonical flat git fields OR retired nested
  * `gitContext` (see TranscriptWireInput in wire-types.js). Absent on the model
  * ⇒ the git chips are omitted entirely (clean degrade). Every field is optional
- * because the real Go wire carries only branch + remote today; the rest arrive
- * only via metadata.json fixtures.
+ * because the canonical session-detail wire carries only branch + remote today;
+ * the rest arrive only via legacy inputs and fixtures.
  *
  * @typedef {object} SessionGitVM
  * @property {string} [branch]
  * @property {string} [remote]
- * @property {string} [author]              cooked from the drifted gitContext.user (TS shape); absent on the Go-flat wire (render-when-present)
+ * @property {string} [author]              cooked from legacy gitContext.user; absent on the canonical flat wire
  * @property {CommitVM[]} [commits]
  * @property {number} [filesChanged]
  * @property {number} [insertions]
@@ -18,10 +18,10 @@
 /**
  * A cooked commit for the git chrome / commit chips. Mirrors CommitInfo
  * (wire-types.js) with display-ready fields. The churn (`adds`/`dels`/`files`)
- * and `turn` anchor are render-when-present: the canonical Go CommitInfo carries
+ * and `turn` anchor are render-when-present: canonical CommitInfo carries
  * no churn and commits are not on the session_detail payload (the deferred
- * backend follow-up), so these light up from fixtures / the drifted TS shape now
- * and from the wire when that follow-up lands.
+ * backend follow-up), so these light up from fixtures / the retired nested shape now
+ * and from the canonical wire when that follow-up lands.
  *
  * @typedef {object} CommitVM
  * @property {string} hash
@@ -70,17 +70,17 @@
 export const TOOL_GROUPS: readonly ToolGroup[];
 /**
  * Cooked git chrome for the session header. Produced by the adapter from
- * whichever wire shape is present — flat `gitBranch`/`gitRemote` OR nested
+ * whichever wire shape is present — canonical flat git fields OR retired nested
  * `gitContext` (see TranscriptWireInput in wire-types.js). Absent on the model
  * ⇒ the git chips are omitted entirely (clean degrade). Every field is optional
- * because the real Go wire carries only branch + remote today; the rest arrive
- * only via metadata.json fixtures.
+ * because the canonical session-detail wire carries only branch + remote today;
+ * the rest arrive only via legacy inputs and fixtures.
  */
 export type SessionGitVM = {
     branch?: string;
     remote?: string;
     /**
-     * cooked from the drifted gitContext.user (TS shape); absent on the Go-flat wire (render-when-present)
+     * cooked from legacy gitContext.user; absent on the canonical flat wire
      */
     author?: string;
     commits?: CommitVM[];
@@ -91,10 +91,10 @@ export type SessionGitVM = {
 /**
  * A cooked commit for the git chrome / commit chips. Mirrors CommitInfo
  * (wire-types.js) with display-ready fields. The churn (`adds`/`dels`/`files`)
- * and `turn` anchor are render-when-present: the canonical Go CommitInfo carries
+ * and `turn` anchor are render-when-present: canonical CommitInfo carries
  * no churn and commits are not on the session_detail payload (the deferred
- * backend follow-up), so these light up from fixtures / the drifted TS shape now
- * and from the wire when that follow-up lands.
+ * backend follow-up), so these light up from fixtures / the retired nested shape now
+ * and from the canonical wire when that follow-up lands.
  */
 export type CommitVM = {
     hash: string;
@@ -268,9 +268,9 @@ export type TurnVM = {
      */
     depth: number;
     /**
-     * provider/role accent token name (decoration)
+     * canonical provider identity for a top-level assistant turn
      */
-    accent?: string;
+    provider?: import("@peasant-labs/schema").Harness;
     /**
      * subagent name when depth > 0
      */