@cleocode/animations 2026.5.105 → 2026.5.107

package/dist/src/index.d.ts

@@ -19,6 +19,7 @@
 export { type AnimateContext, type AnimateContextInput, createAnimateContext, type FlagResolutionLike, SILENT_CONTEXT, } from './animate-context.js';
 export { type BrailleSpinnerName, CANON_TO_GENERIC, type CanonSpinnerName, canonSpinners, default, gridToBraille, makeGrid, resolveSpinner, type Spinner, spinners, } from './braille.js';
 export { type ProgressBarRenderer, type ProgressBarStyle, progressBars, renderProgressBar, } from './progress.js';
+export { type LegendItem, type RenderBadgeOptions, type RenderLegendInput, type RenderSectionInput, type RenderSummaryInput, type RenderTableOptions, type RenderTreeViewOptions, renderBadge, renderLegend, renderSection, renderStatusBadge, renderSummary, renderTable, renderTree, type StatusBadgeName, type SummaryCount, } from './render/index.js';
 export { type Spark, type SparkName, sparkDurationMs, sparks } from './spark.js';
 export { createSpinnerHandle, type SpinnerHandle, type SpinnerHandleOptions, } from './spinner-handle.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,kBAAkB,EACvB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,aAAa,EACb,OAAO,EACP,aAAa,EACb,QAAQ,EACR,cAAc,EACd,KAAK,OAAO,EACZ,QAAQ,GACT,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,YAAY,EACZ,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGjF,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,kBAAkB,EACvB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,aAAa,EACb,OAAO,EACP,aAAa,EACb,QAAQ,EACR,cAAc,EACd,KAAK,OAAO,EACZ,QAAQ,GACT,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,YAAY,EACZ,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,WAAW,EACX,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEjF,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC"}

package/dist/src/index.js

@@ -22,6 +22,8 @@ export { createAnimateContext, SILENT_CONTEXT, } from './animate-context.js';
 export { CANON_TO_GENERIC, canonSpinners, default, gridToBraille, makeGrid, resolveSpinner, spinners, } from './braille.js';
 // === Progress bars ===
 export { progressBars, renderProgressBar, } from './progress.js';
+// === Static UI primitives (T10128 — tree, table, section, badge, legend) ===
+export { renderBadge, renderLegend, renderSection, renderStatusBadge, renderSummary, renderTable, renderTree, } from './render/index.js';
 // === Sparks (one-shot accents) ===
 export { sparkDurationMs, sparks } from './spark.js';
 // === Spinner handle (canonical owner of \r writes) ===

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,kDAAkD;AAClD,OAAO,EAGL,oBAAoB,EAEpB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,mBAAmB;AACnB,OAAO,EAEL,gBAAgB,EAEhB,aAAa,EACb,OAAO,EACP,aAAa,EACb,QAAQ,EACR,cAAc,EAEd,QAAQ,GACT,MAAM,cAAc,CAAC;AAEtB,wBAAwB;AACxB,OAAO,EAGL,YAAY,EACZ,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,oCAAoC;AACpC,OAAO,EAA8B,eAAe,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEjF,wDAAwD;AACxD,OAAO,EACL,mBAAmB,GAGpB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,kDAAkD;AAClD,OAAO,EAGL,oBAAoB,EAEpB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,mBAAmB;AACnB,OAAO,EAEL,gBAAgB,EAEhB,aAAa,EACb,OAAO,EACP,aAAa,EACb,QAAQ,EACR,cAAc,EAEd,QAAQ,GACT,MAAM,cAAc,CAAC;AAEtB,wBAAwB;AACxB,OAAO,EAGL,YAAY,EACZ,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,8EAA8E;AAC9E,OAAO,EAQL,WAAW,EACX,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,UAAU,GAGX,MAAM,mBAAmB,CAAC;AAC3B,oCAAoC;AACpC,OAAO,EAA8B,eAAe,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACjF,wDAAwD;AACxD,OAAO,EACL,mBAAmB,GAGpB,MAAM,qBAAqB,CAAC"}

package/dist/src/render/badge.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Static badge rendering — single-icon glyphs with ASCII fallback.
+ *
+ * @remarks
+ * Part of the Human Render Contract (Epic T10114, ADR-077). Every CLI status,
+ * kind, badge, or relation glyph that surfaces in `--human` mode flows through
+ * one of these two helpers. The {@link AnimateContext} gate guarantees JSON /
+ * quiet / non-TTY / NO_COLOR outputs emit nothing, mirroring the silence
+ * contract enforced by {@link createSpinnerHandle}.
+ *
+ * @epic T10114
+ * @task T10128
+ * @subtask T10145
+ */
+import { type BadgeIcon, type KindIcon, type RelationIcon, StatusIcon } from '@cleocode/contracts/render/icon.js';
+import type { AnimateContext } from '../animate-context.js';
+/**
+ * Common options for badge rendering.
+ *
+ * @remarks
+ * `ascii` is an explicit override. When omitted the helper falls back to
+ * `ctx.inputs.noColor` so callers can simply thread the context through.
+ */
+export interface RenderBadgeOptions {
+    /** Render gate — primitive returns `''` when `enabled === false`. */
+    readonly ctx: AnimateContext;
+    /**
+     * When `true`, force the ASCII fallback regardless of the context's
+     * `noColor` signal. When `false`, force the emoji form. When omitted,
+     * defer to `ctx.inputs.noColor`.
+     */
+    readonly ascii?: boolean;
+}
+/** Lifecycle status names accepted by {@link renderStatusBadge}. */
+export type StatusBadgeName = 'pending' | 'in_progress' | 'done' | 'blocked' | 'cancelled' | 'archived';
+/**
+ * Render a single icon as its emoji form or ASCII fallback.
+ *
+ * @param icon - Any member of {@link StatusIcon}, {@link KindIcon},
+ *   {@link BadgeIcon}, or {@link RelationIcon}.
+ * @param opts - Render gate + optional ASCII override.
+ * @returns The emoji or ASCII glyph. Empty string when `opts.ctx.enabled` is `false`.
+ *
+ * @example
+ * ```ts
+ * renderBadge(StatusIcon.DONE, { ctx: enabledCtx });          // '✅'
+ * renderBadge(StatusIcon.DONE, { ctx: enabledCtx, ascii: true }); // '[x]'
+ * renderBadge(StatusIcon.DONE, { ctx: disabledCtx });          // ''
+ * ```
+ */
+export declare function renderBadge(icon: StatusIcon | KindIcon | BadgeIcon | RelationIcon, opts: RenderBadgeOptions): string;
+/**
+ * Render a lifecycle status string as a badge glyph.
+ *
+ * @param status - Canonical task status name (`'pending'`, `'in_progress'`, …).
+ * @param opts - Render gate + optional ASCII override.
+ * @returns The emoji or ASCII glyph for the status. Empty string when
+ *   `opts.ctx.enabled` is `false`.
+ *
+ * @example
+ * ```ts
+ * renderStatusBadge('done', { ctx });          // '✅'
+ * renderStatusBadge('pending', { ctx: ascii }); // '[ ]'
+ * ```
+ */
+export declare function renderStatusBadge(status: StatusBadgeName, opts: RenderBadgeOptions): string;
+//# sourceMappingURL=badge.d.ts.map

package/dist/src/render/badge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../../src/render/badge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,UAAU,EACX,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,oEAAoE;AACpE,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,aAAa,GACb,MAAM,GACN,SAAS,GACT,WAAW,GACX,UAAU,CAAC;AAEf;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,EACtD,IAAI,EAAE,kBAAkB,GACvB,MAAM,CAIR;AAYD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAE3F"}

package/dist/src/render/badge.js

@@ -0,0 +1,63 @@
+/**
+ * Static badge rendering — single-icon glyphs with ASCII fallback.
+ *
+ * @remarks
+ * Part of the Human Render Contract (Epic T10114, ADR-077). Every CLI status,
+ * kind, badge, or relation glyph that surfaces in `--human` mode flows through
+ * one of these two helpers. The {@link AnimateContext} gate guarantees JSON /
+ * quiet / non-TTY / NO_COLOR outputs emit nothing, mirroring the silence
+ * contract enforced by {@link createSpinnerHandle}.
+ *
+ * @epic T10114
+ * @task T10128
+ * @subtask T10145
+ */
+import { ascii, StatusIcon, } from '@cleocode/contracts/render/icon.js';
+/**
+ * Render a single icon as its emoji form or ASCII fallback.
+ *
+ * @param icon - Any member of {@link StatusIcon}, {@link KindIcon},
+ *   {@link BadgeIcon}, or {@link RelationIcon}.
+ * @param opts - Render gate + optional ASCII override.
+ * @returns The emoji or ASCII glyph. Empty string when `opts.ctx.enabled` is `false`.
+ *
+ * @example
+ * ```ts
+ * renderBadge(StatusIcon.DONE, { ctx: enabledCtx });          // '✅'
+ * renderBadge(StatusIcon.DONE, { ctx: enabledCtx, ascii: true }); // '[x]'
+ * renderBadge(StatusIcon.DONE, { ctx: disabledCtx });          // ''
+ * ```
+ */
+export function renderBadge(icon, opts) {
+    if (!opts.ctx.enabled)
+        return '';
+    const useAscii = opts.ascii ?? opts.ctx.inputs.noColor;
+    return useAscii ? ascii(icon) : icon;
+}
+/** Internal mapping — lifecycle status name → canonical {@link StatusIcon}. */
+const STATUS_NAME_TO_ICON = {
+    pending: StatusIcon.PENDING,
+    in_progress: StatusIcon.ACTIVE,
+    done: StatusIcon.DONE,
+    blocked: StatusIcon.BLOCKED,
+    cancelled: StatusIcon.CANCELLED,
+    archived: StatusIcon.ARCHIVED,
+};
+/**
+ * Render a lifecycle status string as a badge glyph.
+ *
+ * @param status - Canonical task status name (`'pending'`, `'in_progress'`, …).
+ * @param opts - Render gate + optional ASCII override.
+ * @returns The emoji or ASCII glyph for the status. Empty string when
+ *   `opts.ctx.enabled` is `false`.
+ *
+ * @example
+ * ```ts
+ * renderStatusBadge('done', { ctx });          // '✅'
+ * renderStatusBadge('pending', { ctx: ascii }); // '[ ]'
+ * ```
+ */
+export function renderStatusBadge(status, opts) {
+    return renderBadge(STATUS_NAME_TO_ICON[status], opts);
+}
+//# sourceMappingURL=badge.js.map

package/dist/src/render/badge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"badge.js","sourceRoot":"","sources":["../../../src/render/badge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,KAAK,EAIL,UAAU,GACX,MAAM,oCAAoC,CAAC;AA8B5C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,WAAW,CACzB,IAAsD,EACtD,IAAwB;IAExB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC;IACvD,OAAO,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvC,CAAC;AAED,+EAA+E;AAC/E,MAAM,mBAAmB,GAAkD;IACzE,OAAO,EAAE,UAAU,CAAC,OAAO;IAC3B,WAAW,EAAE,UAAU,CAAC,MAAM;IAC9B,IAAI,EAAE,UAAU,CAAC,IAAI;IACrB,OAAO,EAAE,UAAU,CAAC,OAAO;IAC3B,SAAS,EAAE,UAAU,CAAC,SAAS;IAC/B,QAAQ,EAAE,UAAU,CAAC,QAAQ;CAC9B,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAuB,EAAE,IAAwB;IACjF,OAAO,WAAW,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;AACxD,CAAC"}

package/dist/src/render/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Static UI primitives — tree, table, section, badge, legend.
+ *
+ * @remarks
+ * Companion to the spinner / progress / spark animations in this package.
+ * Every primitive is a pure function that returns a string and respects the
+ * {@link AnimateContext} gate — emitting `''` when the context is silent
+ * (JSON, quiet, no-TTY, NO_COLOR).
+ *
+ * Consumes typed contracts from `@cleocode/contracts/render/*` (Epic T10114,
+ * ADR-077) and icon enums from `@cleocode/contracts/render/icon.js`.
+ *
+ * @epic T10114
+ * @task T10128
+ * @packageDocumentation
+ */
+export { type RenderBadgeOptions, renderBadge, renderStatusBadge, type StatusBadgeName, } from './badge.js';
+export { type LegendItem, type RenderLegendInput, type RenderSummaryInput, renderLegend, renderSummary, type SummaryCount, } from './legend.js';
+export { type RenderSectionInput, renderSection, } from './section.js';
+export { type RenderTableOptions, renderTable, } from './table.js';
+export { type RenderTreeViewOptions, renderTree, } from './tree.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/render/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/render/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,WAAW,EACX,iBAAiB,EACjB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,YAAY,EACZ,aAAa,EACb,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,kBAAkB,EACvB,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,kBAAkB,EACvB,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,qBAAqB,EAC1B,UAAU,GACX,MAAM,WAAW,CAAC"}

package/dist/src/render/index.js

@@ -0,0 +1,22 @@
+/**
+ * Static UI primitives — tree, table, section, badge, legend.
+ *
+ * @remarks
+ * Companion to the spinner / progress / spark animations in this package.
+ * Every primitive is a pure function that returns a string and respects the
+ * {@link AnimateContext} gate — emitting `''` when the context is silent
+ * (JSON, quiet, no-TTY, NO_COLOR).
+ *
+ * Consumes typed contracts from `@cleocode/contracts/render/*` (Epic T10114,
+ * ADR-077) and icon enums from `@cleocode/contracts/render/icon.js`.
+ *
+ * @epic T10114
+ * @task T10128
+ * @packageDocumentation
+ */
+export { renderBadge, renderStatusBadge, } from './badge.js';
+export { renderLegend, renderSummary, } from './legend.js';
+export { renderSection, } from './section.js';
+export { renderTable, } from './table.js';
+export { renderTree, } from './tree.js';
+//# sourceMappingURL=index.js.map

package/dist/src/render/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/render/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAEL,WAAW,EACX,iBAAiB,GAElB,MAAM,YAAY,CAAC;AACpB,OAAO,EAIL,YAAY,EACZ,aAAa,GAEd,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,UAAU,GACX,MAAM,WAAW,CAAC"}

package/dist/src/render/legend.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Legend and summary footer rendering.
+ *
+ * @remarks
+ * `renderLegend` produces a compact glossary mapping icons to labels — e.g.
+ * `✅ done  🚧 active  ⏳ pending` — that complements a tree, table, or list.
+ * `renderSummary` produces a one-line aggregate footer such as
+ * `15 Sagas · 89 member Epics · 1 orphan`.
+ *
+ * Both helpers honor the {@link AnimateContext} gate and emit the empty string
+ * when rendering is disabled.
+ *
+ * @epic T10114
+ * @task T10128
+ * @subtask T10146
+ */
+import type { AnimateContext } from '../animate-context.js';
+/** One legend entry — icon glyph + plain-text label. */
+export interface LegendItem {
+    /** Pre-resolved icon glyph (caller is responsible for ASCII selection). */
+    readonly icon: string;
+    /** Plain-text label rendered after the icon. */
+    readonly label: string;
+}
+/** Inputs to {@link renderLegend}. */
+export interface RenderLegendInput {
+    /** Icon → label pairs rendered in order. */
+    readonly items: ReadonlyArray<LegendItem>;
+    /** Render gate — primitive returns `''` when `enabled === false`. */
+    readonly ctx: AnimateContext;
+    /**
+     * When the item count is `<=` this threshold the legend renders as a single
+     * line; above it the legend renders one item per line. Defaults to `8`.
+     */
+    readonly multiLineThreshold?: number;
+}
+/**
+ * Render an icon legend — one-line for small counts, multi-line otherwise.
+ *
+ * @param input - Legend items, render gate, and optional threshold.
+ * @returns The formatted legend string. Empty when `input.ctx.enabled` is `false`
+ *   or `input.items` is empty.
+ *
+ * @example
+ * ```ts
+ * renderLegend({
+ *   ctx,
+ *   items: [
+ *     { icon: '✅', label: 'done' },
+ *     { icon: '🚧', label: 'active' },
+ *     { icon: '⏳', label: 'pending' },
+ *   ],
+ * });
+ * // → '✅ done  🚧 active  ⏳ pending'
+ * ```
+ */
+export declare function renderLegend(input: RenderLegendInput): string;
+/** One aggregate count cell in {@link renderSummary}. */
+export interface SummaryCount {
+    /** Human-readable label (e.g. `'Sagas'`, `'member Epics'`). */
+    readonly label: string;
+    /** Numeric count rendered before the label. */
+    readonly n: number;
+}
+/** Inputs to {@link renderSummary}. */
+export interface RenderSummaryInput {
+    /** Counts rendered left-to-right, separated by middle dots. */
+    readonly counts: ReadonlyArray<SummaryCount>;
+    /** Render gate — primitive returns `''` when `enabled === false`. */
+    readonly ctx: AnimateContext;
+}
+/**
+ * Render a one-line aggregate summary footer.
+ *
+ * @param input - Counts to render and the gate context.
+ * @returns The formatted summary string. Empty when `input.ctx.enabled` is `false`
+ *   or `input.counts` is empty.
+ *
+ * @example
+ * ```ts
+ * renderSummary({
+ *   ctx,
+ *   counts: [
+ *     { label: 'Sagas', n: 15 },
+ *     { label: 'member Epics', n: 89 },
+ *     { label: 'orphan', n: 1 },
+ *   ],
+ * });
+ * // → '15 Sagas · 89 member Epics · 1 orphan'
+ * ```
+ */
+export declare function renderSummary(input: RenderSummaryInput): string;
+//# sourceMappingURL=legend.d.ts.map

package/dist/src/render/legend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legend.d.ts","sourceRoot":"","sources":["../../../src/render/legend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAW5D,wDAAwD;AACxD,MAAM,WAAW,UAAU;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAW7D;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAC7C,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAM/D"}

package/dist/src/render/legend.js

@@ -0,0 +1,83 @@
+/**
+ * Legend and summary footer rendering.
+ *
+ * @remarks
+ * `renderLegend` produces a compact glossary mapping icons to labels — e.g.
+ * `✅ done  🚧 active  ⏳ pending` — that complements a tree, table, or list.
+ * `renderSummary` produces a one-line aggregate footer such as
+ * `15 Sagas · 89 member Epics · 1 orphan`.
+ *
+ * Both helpers honor the {@link AnimateContext} gate and emit the empty string
+ * when rendering is disabled.
+ *
+ * @epic T10114
+ * @task T10128
+ * @subtask T10146
+ */
+/** Default item count above which {@link renderLegend} emits multi-line output. */
+const DEFAULT_MULTILINE_THRESHOLD = 8;
+/** Middle-dot separator used in summaries (U+00B7). */
+const SUMMARY_SEPARATOR = ' · ';
+/** ASCII fallback separator used when the context is in `no-color` mode. */
+const SUMMARY_SEPARATOR_ASCII = ' | ';
+/**
+ * Render an icon legend — one-line for small counts, multi-line otherwise.
+ *
+ * @param input - Legend items, render gate, and optional threshold.
+ * @returns The formatted legend string. Empty when `input.ctx.enabled` is `false`
+ *   or `input.items` is empty.
+ *
+ * @example
+ * ```ts
+ * renderLegend({
+ *   ctx,
+ *   items: [
+ *     { icon: '✅', label: 'done' },
+ *     { icon: '🚧', label: 'active' },
+ *     { icon: '⏳', label: 'pending' },
+ *   ],
+ * });
+ * // → '✅ done  🚧 active  ⏳ pending'
+ * ```
+ */
+export function renderLegend(input) {
+    if (!input.ctx.enabled)
+        return '';
+    if (input.items.length === 0)
+        return '';
+    const threshold = input.multiLineThreshold ?? DEFAULT_MULTILINE_THRESHOLD;
+    const formatted = input.items.map((item) => `${item.icon} ${item.label}`);
+    if (input.items.length <= threshold) {
+        return formatted.join('  ');
+    }
+    return formatted.join('\n');
+}
+/**
+ * Render a one-line aggregate summary footer.
+ *
+ * @param input - Counts to render and the gate context.
+ * @returns The formatted summary string. Empty when `input.ctx.enabled` is `false`
+ *   or `input.counts` is empty.
+ *
+ * @example
+ * ```ts
+ * renderSummary({
+ *   ctx,
+ *   counts: [
+ *     { label: 'Sagas', n: 15 },
+ *     { label: 'member Epics', n: 89 },
+ *     { label: 'orphan', n: 1 },
+ *   ],
+ * });
+ * // → '15 Sagas · 89 member Epics · 1 orphan'
+ * ```
+ */
+export function renderSummary(input) {
+    if (!input.ctx.enabled)
+        return '';
+    if (input.counts.length === 0)
+        return '';
+    const separator = input.ctx.inputs.noColor ? SUMMARY_SEPARATOR_ASCII : SUMMARY_SEPARATOR;
+    return input.counts.map((c) => `${c.n} ${c.label}`).join(separator);
+}
+//# sourceMappingURL=legend.js.map

package/dist/src/render/legend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legend.js","sourceRoot":"","sources":["../../../src/render/legend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,mFAAmF;AACnF,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAEtC,uDAAuD;AACvD,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC,4EAA4E;AAC5E,MAAM,uBAAuB,GAAG,KAAK,CAAC;AAuBtC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAwB;IACnD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAClC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAExC,MAAM,SAAS,GAAG,KAAK,CAAC,kBAAkB,IAAI,2BAA2B,CAAC;IAC1E,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAE1E,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;QACpC,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAkBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAClC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEzC,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,iBAAiB,CAAC;IACzF,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACtE,CAAC"}

package/dist/src/render/section.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Static section rendering — header (optional icon + subtitle) over indented items.
+ *
+ * @remarks
+ * Part of the Human Render Contract (Epic T10114, ADR-077). Sections are the
+ * canonical "labelled block" presenter — used for `cleo saga show` deviation
+ * lists, doctor reports, and similar ad-hoc human output. Items are
+ * pre-formatted; this primitive only owns the header + indentation.
+ *
+ * Section bodies are indented by 2 spaces. An empty `items` array renders only
+ * the header line.
+ *
+ * @epic T10114
+ * @task T10128
+ * @subtask T10144
+ */
+import type { AnimateContext } from '../animate-context.js';
+/** Inputs to {@link renderSection}. */
+export interface RenderSectionInput {
+    /**
+     * Optional leading glyph (emoji or ASCII). Caller picks the right form for
+     * the active terminal — this primitive renders it verbatim.
+     */
+    readonly icon?: string;
+    /** Section heading rendered on the first line. */
+    readonly header: string;
+    /** Optional subtitle appended after the header with an em-dash separator. */
+    readonly subtitle?: string;
+    /** Pre-formatted item strings rendered as an indented block. */
+    readonly items: ReadonlyArray<string>;
+    /** Render gate — primitive returns `''` when `enabled === false`. */
+    readonly ctx: AnimateContext;
+}
+/**
+ * Render a section block — header line plus indented items.
+ *
+ * @param input - Header text, optional icon/subtitle, items, and gate context.
+ * @returns A multi-line string. Empty when `input.ctx.enabled` is `false`.
+ *
+ * @example
+ * ```ts
+ * renderSection({
+ *   ctx,
+ *   icon: '✅',
+ *   header: 'DONE',
+ *   subtitle: '3 epics shipped',
+ *   items: ['T9832 contracts foundation', 'T9836 test helpers', 'T9837 SSoT enforcement'],
+ * });
+ * // ✅ DONE — 3 epics shipped
+ * //   T9832 contracts foundation
+ * //   T9836 test helpers
+ * //   T9837 SSoT enforcement
+ * ```
+ */
+export declare function renderSection(input: RenderSectionInput): string;
+//# sourceMappingURL=section.d.ts.map

package/dist/src/render/section.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../../../src/render/section.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;CAC9B;AAQD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAgB/D"}

package/dist/src/render/section.js

@@ -0,0 +1,56 @@
+/**
+ * Static section rendering — header (optional icon + subtitle) over indented items.
+ *
+ * @remarks
+ * Part of the Human Render Contract (Epic T10114, ADR-077). Sections are the
+ * canonical "labelled block" presenter — used for `cleo saga show` deviation
+ * lists, doctor reports, and similar ad-hoc human output. Items are
+ * pre-formatted; this primitive only owns the header + indentation.
+ *
+ * Section bodies are indented by 2 spaces. An empty `items` array renders only
+ * the header line.
+ *
+ * @epic T10114
+ * @task T10128
+ * @subtask T10144
+ */
+/** Two-space indent applied to every item line. */
+const ITEM_INDENT = '  ';
+/** Em-dash separator between header and subtitle. */
+const SUBTITLE_SEPARATOR = ' — ';
+/**
+ * Render a section block — header line plus indented items.
+ *
+ * @param input - Header text, optional icon/subtitle, items, and gate context.
+ * @returns A multi-line string. Empty when `input.ctx.enabled` is `false`.
+ *
+ * @example
+ * ```ts
+ * renderSection({
+ *   ctx,
+ *   icon: '✅',
+ *   header: 'DONE',
+ *   subtitle: '3 epics shipped',
+ *   items: ['T9832 contracts foundation', 'T9836 test helpers', 'T9837 SSoT enforcement'],
+ * });
+ * // ✅ DONE — 3 epics shipped
+ * //   T9832 contracts foundation
+ * //   T9836 test helpers
+ * //   T9837 SSoT enforcement
+ * ```
+ */
+export function renderSection(input) {
+    if (!input.ctx.enabled)
+        return '';
+    const iconPart = input.icon !== undefined && input.icon.length > 0 ? `${input.icon} ` : '';
+    const subtitlePart = input.subtitle !== undefined && input.subtitle.length > 0
+        ? `${SUBTITLE_SEPARATOR}${input.subtitle}`
+        : '';
+    const headerLine = `${iconPart}${input.header}${subtitlePart}`;
+    if (input.items.length === 0) {
+        return headerLine;
+    }
+    const itemLines = input.items.map((item) => `${ITEM_INDENT}${item}`);
+    return [headerLine, ...itemLines].join('\n');
+}
+//# sourceMappingURL=section.js.map

package/dist/src/render/section.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"section.js","sourceRoot":"","sources":["../../../src/render/section.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAqBH,mDAAmD;AACnD,MAAM,WAAW,GAAG,IAAI,CAAC;AAEzB,qDAAqD;AACrD,MAAM,kBAAkB,GAAG,KAAK,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAElC,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3F,MAAM,YAAY,GAChB,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;QACvD,CAAC,CAAC,GAAG,kBAAkB,GAAG,KAAK,CAAC,QAAQ,EAAE;QAC1C,CAAC,CAAC,EAAE,CAAC;IACT,MAAM,UAAU,GAAG,GAAG,QAAQ,GAAG,KAAK,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;IAE/D,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,WAAW,GAAG,IAAI,EAAE,CAAC,CAAC;IACrE,OAAO,CAAC,UAAU,EAAE,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/C,CAAC"}

package/dist/src/render/table.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Static table rendering — column-aligned rows with terminal-width awareness.
+ *
+ * @remarks
+ * Part of the Human Render Contract (Epic T10114, ADR-077). Consumes a typed
+ * {@link TableResponse} (schema + rows + total) and emits an aligned monospace
+ * table that fits within the active terminal width. Wide string columns shrink
+ * proportionally when the total width exceeds the budget; narrow numeric
+ * columns are preserved.
+ *
+ * @epic T10114
+ * @task T10128
+ * @subtask T10143
+ */
+import type { TableResponse } from '@cleocode/contracts/render/table.js';
+import type { AnimateContext } from '../animate-context.js';
+/** Options to {@link renderTable}. */
+export interface RenderTableOptions {
+    /** Render gate — primitive returns `''` when `enabled === false`. */
+    readonly ctx: AnimateContext;
+    /**
+     * Maximum line width. Defaults to `process.stdout.columns` and falls back to
+     * `80` when the column count is unavailable. The renderer never produces a
+     * row longer than this.
+     */
+    readonly maxWidth?: number;
+    /**
+     * When `true`, force ASCII separator characters. When `false`, force the
+     * Unicode form. When omitted, defer to `ctx.inputs.noColor`.
+     */
+    readonly asciiBoxDrawing?: boolean;
+}
+/**
+ * Render a {@link TableResponse} as an aligned columnar string.
+ *
+ * @param resp - Typed table response (schema + rows + total).
+ * @param opts - Render gate + width / ASCII overrides.
+ * @returns Multi-line aligned table. Empty when `opts.ctx.enabled` is `false`.
+ *
+ * @example
+ * ```ts
+ * renderTable(
+ *   {
+ *     rows: [{ id: 'T1', title: 'Implement', status: 'done' }],
+ *     schema: {
+ *       columns: [
+ *         { key: 'id', header: 'ID' },
+ *         { key: 'title', header: 'Title' },
+ *         { key: 'status', header: 'Status' },
+ *       ],
+ *     },
+ *     total: 1,
+ *   },
+ *   { ctx },
+ * );
+ * ```
+ */
+export declare function renderTable<T>(resp: TableResponse<T>, opts: RenderTableOptions): string;
+//# sourceMappingURL=table.d.ts.map

package/dist/src/render/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../src/render/table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAA4B,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACnG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAmDvF"}