agentfootprint 2.14.4 → 3.0.0

package/dist/types/core/Agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}

package/dist/types/core/LLMCall.d.ts

@@ -11,7 +11,8 @@
  *            agentfootprint.stream.llm_start / llm_end
  *            agentfootprint.context.injected / slot_composed
  */
-import { type FlowChart, type FlowchartCheckpoint, type RunOptions } from 'footprintjs';
+import { type FlowchartCheckpoint, type RunOptions, type StructureRecorder } from 'footprintjs';
+import type { GroupMetadata, GroupTranslator } from './translator.js';
 import type { RunnerPauseOutcome } from './pause.js';
 import type { LLMProvider, PricingTable } from '../adapters/types.js';
 import { RunnerBase } from './RunnerBase.js';
@@ -40,6 +41,24 @@ export interface LLMCallOptions {
      * — consumers choose whether to abort by listening to the event.
      */
     readonly costBudget?: number;
+    /**
+     * Optional build-time recorders threaded into footprintjs's
+     * `flowChart()` factory. Each recorder observes per-node build
+     * events (`onStageAdded` / `onSubflowMounted` / etc.) for this
+     * LLMCall's internal chart (Seed + slot mounts + CallLLM). When
+     * omitted, no build-time observation is wired up.
+     */
+    readonly structureRecorders?: readonly StructureRecorder[];
+    /**
+     * Optional per-COMPOSITION translator (UI-agnostic). See
+     * `core/translator.ts`. When attached, `runner.getUIGroup()` invokes
+     * it with the LLMCall's `GroupMetadata` (kind `'LLMCall'`, id, name,
+     * empty `members[]`, plus `extra.slots` with the three slot ids —
+     * `system-prompt`, `messages`, `tools` — so Lens can render the slot
+     * cards inside an LLMCall card without inspecting `buildTimeStructure`).
+     * Returns `undefined` when omitted.
+     */
+    readonly groupTranslator?: GroupTranslator;
 }
 export interface LLMCallInput {
     readonly message: string;
@@ -55,10 +74,17 @@ export declare class LLMCall extends RunnerBase<LLMCallInput, LLMCallOutput> {
     private readonly systemPromptValue;
     private readonly pricingTable?;
     private readonly costBudget?;
+    private readonly structureRecorders?;
+    private readonly groupTranslator?;
     private currentRunContext;
     constructor(opts: LLMCallOptions, systemPromptValue: string);
     static create(opts: LLMCallOptions): LLMCallBuilder;
-    toFlowChart(): FlowChart;
+    protected getGroupTranslator(): GroupTranslator | undefined;
+    /** LLMCall has no nested-runner members (slots are subflows of
+     *  the LLMCall's own chart, not Runner instances). The 3 slot ids
+     *  are surfaced via `extra` so Lens can render the slot cards
+     *  inside an LLMCall card without inspecting `buildTimeStructure`. */
+    protected buildUIGroupMetadata(): GroupMetadata;
     run(input: LLMCallInput, options?: RunOptions): Promise<LLMCallOutput | RunnerPauseOutcome>;
     resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<LLMCallOutput | RunnerPauseOutcome>;
     private createExecutor;

package/dist/types/core/LLMCall.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LLMCall.d.ts","sourceRoot":"","sources":["../../../src/core/LLMCall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAWrD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEtE,OAAO,EAAE,UAAU,EAAa,MAAM,iBAAiB,CAAC;AAKxD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAmBnC,qBAAa,OAAQ,SAAQ,UAAU,CAAC,YAAY,EAAE,aAAa,CAAC;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IAGrC,OAAO,CAAC,iBAAiB,CAIvB;gBAEU,IAAI,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM;IAa3D,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc;IAInD,WAAW,IAAI,SAAS;IAIlB,GAAG,CACP,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,aAAa,GAAG,kBAAkB,CAAC;IASxC,MAAM,CACV,UAAU,EAAE,mBAAmB,EAC/B,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,aAAa,GAAG,kBAAkB,CAAC;IAO9C,OAAO,CAAC,cAAc;IA8BtB,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,UAAU;CA+HnB;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,iBAAiB,CAAM;gBAEnB,IAAI,EAAE,cAAc;IAIhC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK5B,KAAK,IAAI,OAAO;CAGjB"}
+{"version":3,"file":"LLMCall.d.ts","sourceRoot":"","sources":["../../../src/core/LLMCall.ts"],"names":[],"mappings":"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"}

package/dist/types/core/RunnerBase.d.ts

@@ -22,13 +22,133 @@ export declare abstract class RunnerBase<TIn = unknown, TOut = unknown> implemen
     protected readonly dispatcher: EventDispatcher;
     protected readonly attachedRecorders: CombinedRecorder[];
     /**
-     * Build the footprintjs FlowChart for this runner. Subclass supplies
-     * its specific structure (slot subflows, callLLM stage, routing, etc.).
+     * The most recently used FlowChartExecutor — set by subclasses in
+     * `run()` so consumers can read the canonical structural snapshot
+     * via `getLastSnapshot()`. Single source of structural truth: this
+     * is footprintjs's snapshot, NOT a domain re-derivation.
      */
-    abstract toFlowChart(): FlowChart;
+    protected lastExecutor: FlowChartExecutor | undefined;
+    /**
+     * Cached footprintjs FlowChart, built ONCE at construction time via
+     * `initChart()`. Subsequent `getSpec()` calls return this same
+     * object — reference-stable across all consumers (Lens spec memos,
+     * footprintjs's OpenAPI/MCP caches, recorder-side correlation).
+     *
+     * Set via `initChart(builder)`, called from the subclass constructor
+     * AFTER all instance fields are populated. Read via `getSpec()`.
+     *
+     * Why eager construction: the `StructureRecorder` contract is
+     * "fires once per node at build time" — lazy construction would
+     * fire each recorder every `getSpec()` / `run()` call (2N invocations
+     * per run instead of N), break reference equality, and trigger
+     * `_mergeStageMap` false-positive collisions on second build.
+     * See `RunnerBase.initChart` for details.
+     *
+     * Visibility note: `private` (not `protected`) so subclasses cannot
+     * bypass the `initChart()` double-init guard by writing the field
+     * directly. All legitimate access goes through `getSpec()` and
+     * `initChart()`.
+     */
+    private chart;
+    /**
+     * Returns the footprintjs snapshot from the most recent run (or
+     * undefined if no run has completed). The snapshot is the CANONICAL
+     * STRUCTURE: nodes, edges, executionTree, runtimeStageId, commitLog.
+     *
+     * Domain consumers (Lens, Trace, dashboards) read this for shape
+     * and join their own per-stage payload by `runtimeStageId`. They
+     * MUST NOT re-derive structure from typed events — that's the
+     * design footprintjs's CLAUDE.md Convention 1 explicitly forbids.
+     *
+     * Returns `undefined` before the first `run()` completes. After,
+     * always returns the snapshot of the most recent run (including
+     * across multi-turn reuse of the same runner instance).
+     */
+    getLastSnapshot(): ReturnType<FlowChartExecutor['getSnapshot']> | undefined;
+    /**
+     * Return the footprintjs FlowChart for this runner — the canonical
+     * design-time blueprint. STABLE REFERENCE across calls (`getSpec()
+     * === getSpec()`). Set once at construction via `initChart()`.
+     *
+     * Pairs with the run-time getters (`getLastSnapshot`,
+     * `getCommitCount`) and matches `ExplainableShell.spec` +
+     * `specToReactFlow(spec, ...)` consumer conventions.
+     *
+     * DO NOT OVERRIDE in subclasses — the reference-identity contract
+     * (Lens / OpenAPI / MCP caches memo on this returning the same
+     * object) depends on the inherited body returning `this.chart`
+     * directly. To customise build behaviour, override `buildChart()`
+     * instead; this getter must remain a thin cache-read.
+     */
+    getSpec(): FlowChart;
+    /**
+     * Cached `getUIGroup()` output. Computed lazily on first read so the
+     * subclass constructor doesn't need to run the translator before all
+     * its members exist (e.g., Parallel builds its branches list mid-
+     * construction). After first invocation, subsequent calls return the
+     * same reference — reference-stable, matches the `getSpec()` contract.
+     *
+     * `null` (not `undefined`) is the explicit "computed; result was
+     * undefined" marker so we can distinguish from "not yet computed."
+     * Consumers see `undefined` when no translator was attached.
+     */
+    private uiGroupCache;
+    /**
+     * Return the consumer-shaped UI group for this composition — produced
+     * by invoking the consumer's `groupTranslator` (if attached) with this
+     * runner's `GroupMetadata`. Returns `undefined` when no translator was
+     * attached.
+     *
+     * STABLE REFERENCE across calls. Computed on first access and cached;
+     * subsequent calls return the same value. Pairs with `getSpec()` —
+     * library shape on one side, consumer-shaped UI on the other.
+     *
+     * Subclasses MUST override `buildUIGroupMetadata()` (the next hook) to
+     * supply the `GroupMetadata` for their composition kind. This method
+     * (the public surface) is `final`-by-convention — do not override.
+     */
+    getUIGroup<T = unknown>(): T | undefined;
+    /**
+     * Subclass hook — returns the consumer's translator if one was
+     * provided at construction time. Default: no translator (returns
+     * undefined). Each composition overrides to surface its own
+     * `opts.groupTranslator`.
+     */
+    protected getGroupTranslator(): import('./translator.js').GroupTranslator | undefined;
+    /**
+     * Translate this runner's group metadata with a CALLER-SUPPLIED
+     * translator that overrides the runner's own default. Used by
+     * parent compositions to apply per-method translator overrides.
+     * See the `Runner.getUIGroupWith` JSDoc for the contract.
+     */
+    getUIGroupWith<T = unknown>(override: import('./translator.js').GroupTranslator): T | undefined;
+    /**
+     * Subclass hook — returns the `GroupMetadata` for this composition.
+     * Default: undefined, meaning "no group translation for this runner
+     * kind." Compositions override to supply their members + kind. Called
+     * AT MOST ONCE per runner (result is cached by `getUIGroup()`).
+     */
+    protected buildUIGroupMetadata(): import('./translator.js').GroupMetadata | undefined;
+    /**
+     * Build + cache the runner's `FlowChart` exactly once. Called by the
+     * subclass constructor AFTER all instance fields are set, so the
+     * builder lambda can close over them safely.
+     *
+     * Throws if called twice on the same instance — the chart is meant
+     * to be immutable post-construction. Each `run()` reuses the same
+     * chart in a fresh `FlowChartExecutor`.
+     *
+     * Implementation invariant (per footprintjs inventor review):
+     * each attached `StructureRecorder` fires exactly N times per
+     * construction (N = node count). Two `getSpec()` calls return the
+     * same `FlowChart` object reference. `_mergeStageMap` collision
+     * guards never see false-positives because each child runner's
+     * stage functions are created once and reused.
+     */
+    protected initChart(builder: () => FlowChart): void;
     /**
      * Execute the runner. Subclass may override for specialized input
-     * mapping, but default invokes toFlowChart() + FlowChartExecutor.
+     * mapping, but default invokes getSpec() + FlowChartExecutor.
      */
     abstract run(input: TIn, options?: RunOptions): Promise<TOut | RunnerPauseOutcome>;
     /**

package/dist/types/core/RunnerBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RunnerBase.d.ts","sourceRoot":"","sources":["../../../src/core/RunnerBase.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RunnerBase.d.ts","sourceRoot":"","sources":["../../../src/core/RunnerBase.ts"],"names":[],"mappings":"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"}

package/dist/types/core/agent/buildAgentChart.d.ts

@@ -37,7 +37,7 @@
  * mounts as a subflow between IterationStart and CallLLM with a
  * TranslateFailFast stage after it. Lands in the next commit.)
  */
-import type { FlowChart } from 'footprintjs';
+import type { FlowChart, StructureRecorder } from 'footprintjs';
 import type { CachePolicy } from '../../cache/types.js';
 import type { MemoryDefinition } from '../../memory/define.types.js';
 /**
@@ -74,6 +74,12 @@ export interface AgentChartDeps {
     readonly cacheDecisionSubflow: FlowChart;
     readonly updateSkillHistoryStage: (scope: never) => void;
     readonly cacheGateDecide: (scope: never) => unknown;
+    /** Structure recorders threaded into both `flowChart()` calls (the
+     *  main chart and the PrepareFinal sub-chart). Each recorder
+     *  observes per-node build events (`onStageAdded` /
+     *  `onSubflowMounted` / etc.) for the Agent's chart. Undefined when
+     *  the consumer didn't attach any. */
+    readonly structureRecorders?: readonly StructureRecorder[];
 }
 /**
  * Build the agent's complete FlowChart from the supplied deps.

package/dist/types/core/agent/buildAgentChart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildAgentChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildAgentChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAQrE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAE/C;uEACmE;IACnE,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC;IAE9C;kDAC8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAG/B,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,YAAY,GAAG,OAAO,CAAC;IAChE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,aAAa,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAGxE,QAAQ,CAAC,sBAAsB,EAAE,SAAS,CAAC;IAC3C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC;IAGrC,QAAQ,CAAC,oBAAoB,EAAE,SAAS,CAAC;IACzC,QAAQ,CAAC,uBAAuB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACzD,QAAQ,CAAC,eAAe,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;CACrD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAuP/D"}
+{"version":3,"file":"buildAgentChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildAgentChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAQrE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAE/C;uEACmE;IACnE,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC;IAE9C;kDAC8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAG/B,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,YAAY,GAAG,OAAO,CAAC;IAChE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,aAAa,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAGxE,QAAQ,CAAC,sBAAsB,EAAE,SAAS,CAAC;IAC3C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC;IAGrC,QAAQ,CAAC,oBAAoB,EAAE,SAAS,CAAC;IACzC,QAAQ,CAAC,uBAAuB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACzD,QAAQ,CAAC,eAAe,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IAGpD;;;;0CAIsC;IACtC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CA0P/D"}

package/dist/types/core/agent/types.d.ts

@@ -7,6 +7,8 @@
  * part of the v2.11.1 decomposition. `core/Agent.ts` re-exports them
  * for back-compat (the 28+ existing import sites continue to work).
  */
+import type { StructureRecorder } from 'footprintjs';
+import type { GroupTranslator } from '../translator.js';
 import type { LLMMessage, LLMProvider, LLMToolSchema, PermissionChecker, PricingTable } from '../../adapters/types.js';
 import type { CacheMarker, CacheStrategy } from '../../cache/types.js';
 import type { ActiveInjection } from '../../lib/injection-engine/types.js';
@@ -64,6 +66,33 @@ export interface AgentOptions {
      * once those land in Phase 7+.
      */
     readonly cacheStrategy?: CacheStrategy;
+    /**
+     * Optional build-time recorders threaded into footprintjs's
+     * `flowChart()` factory. Each recorder fires `onStageAdded` once per
+     * node in the Agent's internal chart (Seed, IterationStart, CallLLM,
+     * Route, tool handler, slot mounts, PrepareFinal, BreakFinal), and
+     * `onSubflowMounted` once per mounted subflow. Recorders own their
+     * own accumulators — agentfootprint just threads them through.
+     *
+     * Cascade: each slot subflow (system-prompt, messages, tools)
+     * was built earlier with its OWN recorders (or none).
+     * footprintjs does NOT propagate StructureRecorders into mounted
+     * subflows — attach the same recorders to every nested composition
+     * for full coverage.
+     *
+     * When omitted, no build-time observation is wired up.
+     */
+    readonly structureRecorders?: readonly StructureRecorder[];
+    /**
+     * Optional per-COMPOSITION translator (UI-agnostic). See
+     * `core/translator.ts`. When attached, `agent.getUIGroup()` invokes
+     * it with the Agent's `GroupMetadata` (kind `'Agent'`, id, name,
+     * empty `members[]`, plus `extra.slots` and `extra.toolNames`).
+     * Tools are not `Runner` instances (they're function executors)
+     * so they're conveyed by name in `extra`, not as group members.
+     * Returns `undefined` when omitted.
+     */
+    readonly groupTranslator?: GroupTranslator;
 }
 export interface AgentInput {
     readonly message: string;

package/dist/types/core/agent/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/types.ts"],"names":[],"mappings":"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"}

package/dist/types/core/runner.d.ts

@@ -1,10 +1,11 @@
 /**
  * Runner — consumer-facing interface for every primitive/composition/pattern.
  *
- * Pattern: Facade (GoF) over ComposableRunner + EventDispatcher.
+ * Pattern: Facade (GoF) over the footprintjs FlowChart + EventDispatcher.
  * Role:    The one object consumers hold. Exposes:
- *            - `.run()` / `.toFlowChart()` (inherited from footprintjs
- *              ComposableRunner — composition + execution)
+ *            - `.run()` (execute)
+ *            - `.getSpec()` (the design-time FlowChart blueprint —
+ *              same value footprintjs's `addSubFlowChart*` accepts)
  *            - `.on() / .off() / .once()` (listener subscription)
  *            - `.attach()` (attach custom CombinedRecorder)
  *            - `.emit()` (consumer-defined custom events on the same
@@ -12,7 +13,7 @@
  * Emits:   N/A — this file defines the INTERFACE. Concrete runners
  *          (LLMCall, Agent, Sequence, etc.) implement it.
  */
-import type { CombinedRecorder, ComposableRunner, FlowchartCheckpoint, RunOptions } from 'footprintjs';
+import type { CombinedRecorder, FlowChart, FlowchartCheckpoint, RunOptions } from 'footprintjs';
 import type { RunnerPauseOutcome } from './pause.js';
 import type { EventListener, ListenOptions, Unsubscribe, WildcardListener, WildcardSubscription } from '../events/dispatcher.js';
 import type { AgentfootprintEvent, AgentfootprintEventType } from '../events/registry.js';
@@ -73,7 +74,52 @@ export interface EnableNamespace {
  * That makes them freely nestable: any runner can be a child of any
  * composition.
  */
-export interface Runner<TIn = unknown, TOut = unknown> extends Omit<ComposableRunner<TIn, TOut>, 'run'> {
+export interface Runner<TIn = unknown, TOut = unknown> {
+    /**
+     * Return the footprintjs FlowChart for this runner — the canonical
+     * design-time blueprint. Stable across calls. Pairs with the run-time
+     * accessors (`getLastSnapshot`, `getCommitCount`) and matches
+     * `ExplainableShell.spec` + `specToReactFlow(spec, ...)` consumer
+     * conventions.
+     *
+     * Subflow mounting (footprintjs `addSubFlowChart*`) accepts the
+     * `FlowChart` value directly:
+     *
+     *   parent.addSubFlowChartNext('sf-agent', child.getSpec(), 'Agent')
+     */
+    getSpec(): FlowChart;
+    /**
+     * Return the consumer-shaped UI group for this runner — produced by
+     * invoking the `groupTranslator` (if one was attached at constructor
+     * time) with this composition's metadata. Returns `undefined` when no
+     * translator was attached.
+     *
+     * Companion of `getSpec()`: `getSpec()` is the canonical (UI-
+     * agnostic) blueprint; `getUIGroup()` is the consumer-shaped view.
+     * Both are stable post-construction.
+     *
+     * See `core/translator.ts` for the `GroupTranslator` /
+     * `GroupMetadata` types.
+     */
+    getUIGroup<T = unknown>(): T | undefined;
+    /**
+     * Translate this runner's group metadata with a CALLER-SUPPLIED
+     * translator that OVERRIDES whatever translator (if any) the runner
+     * was constructed with. Used by parent compositions to apply
+     * per-method translator overrides (e.g.,
+     * `Parallel.create(...).branch('special', runner, { groupTranslator: ... })`
+     * — for the `'special'` branch only, this `override` runs against
+     * `runner`'s own `GroupMetadata` instead of the runner's default
+     * translator).
+     *
+     * NOT cached at the runner level. The caller invokes this exactly
+     * once per build (parent's `buildUIGroupMetadata`) and caches the
+     * resulting `uiGroup` via the parent's `RunnerBase.uiGroupCache`.
+     *
+     * Returns `undefined` when this runner has no group metadata to
+     * translate (i.e., `buildUIGroupMetadata()` returned `undefined`).
+     */
+    getUIGroupWith<T = unknown>(override: import('./translator.js').GroupTranslator): T | undefined;
     /**
      * Execute the runner. On happy-path completion, resolves with `TOut`.
      * If any stage (Agent tool via `pauseHere`, nested runner, or consumer

package/dist/types/core/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/core/runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/core/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+CAA+C,CAAC;AACpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAC;AACtF,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EACjB,MAAM,iDAAiD,CAAC;AACzD,OAAO,KAAK,EACV,0BAA0B,EAC1B,iBAAiB,EACjB,uBAAuB,EACxB,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAAC;IAC7C;;;OAGG;IACH,OAAO,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,WAAW,CAAC;IAC5C;;;;;;;;OAQG;IACH,SAAS,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,eAAe,CAAC;IACpD;;;;;OAKG;IACH,aAAa,CAAC,IAAI,CAAC,EAAE,0BAA0B,GAAG,WAAW,CAAC;IAC9D;;;;OAIG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,WAAW,CAAC;IAC5C;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,uBAAuB,GAAG,WAAW,CAAC;CACxD;AAED;;;;;GAKG;AACH,MAAM,WAAW,MAAM,CAAC,GAAG,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO;IACnD;;;;;;;;;;;OAWG;IACH,OAAO,IAAI,SAAS,CAAC;IAErB;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,SAAS,CAAC;IAEzC;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,OAAO,iBAAiB,EAAE,eAAe,GAAG,CAAC,GAAG,SAAS,CAAC;IAEhG;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,GAAG,kBAAkB,CAAC,CAAC;IAE1E;;;;;OAKG;IACH,MAAM,CACJ,UAAU,EAAE,mBAAmB,EAC/B,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,IAAI,GAAG,kBAAkB,CAAC,CAAC;IAEtC,uDAAuD;IACvD,EAAE,CAAC,CAAC,SAAS,uBAAuB,EAClC,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW,CAAC;IACf,+EAA+E;IAC/E,EAAE,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,WAAW,CAAC;IAEjG,oDAAoD;IACpD,GAAG,CAAC,CAAC,SAAS,uBAAuB,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAClF,GAAG,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAElE,oEAAoE;IACpE,IAAI,CAAC,CAAC,SAAS,uBAAuB,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC;IAC1F,IAAI,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAE1E;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAEhD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAEjC;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC5D;AAED,6EAA6E;AAC7E,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,mBAAmB,CAAC"}

package/dist/types/core/slots/buildMessagesSlot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildMessagesSlot.d.ts","sourceRoot":"","sources":["../../../../src/core/slots/buildMessagesSlot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAEzD,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAMzE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,kBAAuB,GAAG,SAAS,CA8D5E"}
+{"version":3,"file":"buildMessagesSlot.d.ts","sourceRoot":"","sources":["../../../../src/core/slots/buildMessagesSlot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAEzD,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAMzE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,kBAAuB,GAAG,SAAS,CA6D5E"}

package/dist/types/core/slots/buildSystemPromptSlot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildSystemPromptSlot.d.ts","sourceRoot":"","sources":["../../../../src/core/slots/buildSystemPromptSlot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAOzD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC;IACzC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAWD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,sBAAsB,GAAG,SAAS,CAqE/E"}
+{"version":3,"file":"buildSystemPromptSlot.d.ts","sourceRoot":"","sources":["../../../../src/core/slots/buildSystemPromptSlot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAOzD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC;IACzC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAWD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,sBAAsB,GAAG,SAAS,CAoE/E"}

package/dist/types/core/slots/buildThinkingSubflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildThinkingSubflow.d.ts","sourceRoot":"","sources":["../../../../src/core/slots/buildThinkingSubflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAU9E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,CA4ExE"}
+{"version":3,"file":"buildThinkingSubflow.d.ts","sourceRoot":"","sources":["../../../../src/core/slots/buildThinkingSubflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAU9E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,CA2ExE"}

package/dist/types/core/slots/buildToolsSlot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildToolsSlot.d.ts","sourceRoot":"","sources":["../../../../src/core/slots/buildToolsSlot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAM7D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,+BAA+B,CAAC;AAGvF;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAsMjE"}
+{"version":3,"file":"buildToolsSlot.d.ts","sourceRoot":"","sources":["../../../../src/core/slots/buildToolsSlot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAM7D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,+BAA+B,CAAC;AAGvF;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAkMjE"}

package/dist/types/core/translator.d.ts

@@ -0,0 +1,95 @@
+/**
+ * GroupTranslator — UI-agnostic composition-level translator hook.
+ *
+ * Pattern: Visitor (GoF) at the composition boundary. Consumer supplies
+ *          a translator function; each agentfootprint composition
+ *          (Parallel, Sequence, Loop, Conditional, Agent, LLMCall)
+ *          invokes it with composition-level metadata to produce a
+ *          consumer-shaped UI output.
+ * Role:    The per-COMPOSITION hook alongside footprintjs's per-NODE
+ *          `StructureRecorder`. The two are independent — a consumer
+ *          can attach either, both, or neither.
+ *
+ *          - StructureRecorder observes ONE spec node at a time (record).
+ *          - GroupTranslator sees the WHOLE composition (compose).
+ *
+ *          For Lens's compound rendering (Parallel-as-container,
+ *          Agent-as-drillable-card, LLMCall-as-card-with-slots),
+ *          this is the right granularity: the translator knows the
+ *          composition KIND and its full member list at once, so it
+ *          can emit a single group-level shape with children pre-laid.
+ *
+ * Cascade: each composition that runs nested compositions exposes its
+ *          members' OWN translated outputs via `GroupMember.uiGroup`.
+ *          The consumer threads the same translator through every
+ *          composition's construction (or per-method override via
+ *          L1c) to get end-to-end coverage. No automatic propagation
+ *          — propagation requires footprintjs-level changes which
+ *          we're not making for this hook.
+ */
+import type { Runner } from './runner.js';
+/**
+ * The composition KIND a translator sees in `GroupMetadata.kind`.
+ * Closed union — every agentfootprint composition declares exactly
+ * one of these via the literal string baked into its `buildChart()`
+ * description prefix and surfaced here in `GroupMetadata`.
+ */
+export type GroupKind = 'Parallel' | 'Sequence' | 'Loop' | 'Conditional' | 'Agent' | 'LLMCall';
+/**
+ * One member of a composition. Shape is uniform across composition
+ * kinds — Parallel branches, Sequence steps, Loop body, Conditional
+ * branches, Agent tools/slots, LLMCall slots all map to this.
+ *
+ * `memberId` is the stable id the composition assigned (e.g. `legal`
+ * for a Parallel branch, `step-classify` for a Sequence step,
+ * `body` for a Loop). Consumers can correlate this with the
+ * SpecNode's `subflowId` / `id` to drill in.
+ *
+ * `runner` is the underlying `Runner` instance — useful for the
+ * consumer to call `member.runner.getSpec()` for the nested chart or
+ * `member.runner.getUIGroup()` for the nested translation result
+ * (when the same translator was threaded through that runner's
+ * construction).
+ *
+ * `uiGroup` is the member's already-translated output. Populated
+ * when the consumer threaded the same `groupTranslator` reference
+ * into each member's construction; `undefined` otherwise.
+ */
+export interface GroupMember {
+    readonly memberId: string;
+    readonly runner: Runner;
+    readonly uiGroup?: unknown;
+}
+/**
+ * What a composition hands to its `groupTranslator` at build time.
+ * All composition kinds emit the same shape — the `kind` discriminator
+ * + the `extra` bag carry per-composition specifics.
+ */
+export interface GroupMetadata {
+    readonly kind: GroupKind;
+    readonly id: string;
+    readonly name: string;
+    readonly members: ReadonlyArray<GroupMember>;
+    /**
+     * Composition-specific extras. Carried verbatim from the
+     * composition's own state — `Parallel` puts the merge strategy
+     * here, `Loop` puts iteration budgets, `Conditional` puts the
+     * fallback branch id, etc. Closed enough per kind that consumers
+     * can switch on `kind` to read it safely.
+     */
+    readonly extra?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The consumer-supplied translator. Pure function — no async, no
+ * side effects expected. Runs ONCE per composition at the moment
+ * `getUIGroup()` is first called (memoised behaviour is per
+ * composition's discretion).
+ *
+ * Output type `T` is whatever the consumer wants — a React Flow
+ * group node, a Mermaid string, a domain-specific layout object,
+ * anything. agentfootprint stays UI-agnostic.
+ */
+export interface GroupTranslator<T = unknown> {
+    (group: GroupMetadata): T;
+}
+//# sourceMappingURL=translator.d.ts.map

package/dist/types/core/translator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translator.d.ts","sourceRoot":"","sources":["../../../src/core/translator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,CAAC,KAAK,EAAE,aAAa,GAAG,CAAC,CAAC;CAC3B"}