@mythicalos/ui-core 0.2.2 → 0.3.1

package/dist/logic/session-card.js

@@ -0,0 +1,443 @@
+// @mythicalos/ui-core — the pure derivation behind the `session-card` atom (design registry spec
+// v1, `mythical-design/ds/components-session-card.html`). Extracted from the only product that
+// implemented it (the Control Room's rail `SessionCard.tsx` + its `derive.ts`/`sessionsVm.ts`
+// state-dot derivation), with the product's session view-model lifted OUT: every function here
+// takes plain primitives, so a second product can render the same card from a different wire shape.
+//
+// Everything branchy lives here — the Preact and React bindings only render what these functions
+// return, so they cannot drift.
+//
+// THREE HONESTY INVARIANTS ARE LOAD-BEARING (they are design, not product logic):
+//
+//   1. ABSENCE IS NOT ZERO. A session with no context reading belongs to NO band: `ctxBand`
+//      returns `"unknown"`, `ctxFillPct` returns `undefined` (so the binding draws no fill rect at
+//      all — never a 0-width one that reads as "0%"), and `ctxValueText` returns `"—"`, never
+//      `"0%"`. The same rule governs the spine strip: an unreported `distills` yields ZERO nodes
+//      (the strip is omitted), never a fabricated "0 distills"; an unreported `savedTok` renders
+//      `"—"`, never `"0 tok"`. A REPORTED zero is a real reading and renders as zero.
+//
+//   2. UNKNOWN IS NOT IDLE. `idle` is a claim the product's wire has to make. When no activity is
+//      reported, `sessionStatus` falls back to the honest LIFECYCLE label (an active session with
+//      no activity signal reads `"active"`, not `"idle"`); when nothing at all is reported it
+//      returns the distinct `"unknown"` key/tone. `"idle"` is returned ONLY for an explicit
+//      `activity: "idle"`.
+//
+//   3. THE 75/90 THRESHOLDS ARE PRODUCT-TUNABLE (canonical tokens.css rule #4: "thresholds are
+//      product-defined (tweakable)"). They are a defaulted parameter — `CTX_THRESHOLDS_DEFAULT` —
+//      never a constant baked into a render path.
+/** The design card's tick positions: warn at 75%, critical at 90% — overridable per product. */
+export const CTX_THRESHOLDS_DEFAULT = { warn: 75, critical: 90 };
+/** A defensive read for the public entry points below: a parameter default only covers
+ *  `undefined`, and a product's runtime-shaped config can hand us `null` or a non-object. */
+function isObject(v) {
+    return typeof v === "object" && v !== null;
+}
+/**
+ * Normalize a product's threshold pair ONCE, so the band and the bar's ticks can never disagree
+ * about where the thresholds are. Two corrections:
+ *
+ *   · A member that is not a finite number strictly inside the rail (0 < t < 100) is not a usable
+ *     threshold — it marks nothing the meter can draw — so it falls back to the design default
+ *     rather than silently reclassifying every reading. (`{warn: NaN}` must not quietly make every
+ *     session look nominal; `{warn: -5}` must not quietly make every session look hot while
+ *     drawing no tick to explain why.)
+ *   · The pair is ORDERED (`warn` ≤ `critical`). A mis-ordered pair leaves the higher tick
+ *     unreachable — with `{warn: 90, critical: 75}` an 80% reading is already `error` while a
+ *     `warn` tick still sits at 90, so the bar marks a boundary that can never be crossed. Both
+ *     boundaries the product asked for are kept; only which one is named `warn` is corrected.
+ */
+export function normalizeCtxThresholds(thresholds) {
+    // These are PUBLIC entry points a product reaches with runtime-shaped config (a settings blob,
+    // an API response), so a non-object gets the defaults rather than a TypeError mid-render — a
+    // parameter default only covers `undefined`.
+    const t = isObject(thresholds) ? thresholds : CTX_THRESHOLDS_DEFAULT;
+    const usable = (v, fallback) => typeof v === "number" && Number.isFinite(v) && v > 0 && v < CTX_BAR_SPAN ? v : fallback;
+    const warn = usable(t.warn, CTX_THRESHOLDS_DEFAULT.warn);
+    const critical = usable(t.critical, CTX_THRESHOLDS_DEFAULT.critical);
+    return { warn: Math.min(warn, critical), critical: Math.max(warn, critical) };
+}
+/** True only for a usable numeric reading — a garbage reading is not a reading. */
+function isReading(pct) {
+    return typeof pct === "number" && Number.isFinite(pct);
+}
+/**
+ * The ONE number the card works from: the reading clamped to 0–100, at FULL precision, or
+ * `undefined` when there is no reading. The band and the fill are derived from this — the
+ * threshold comparison is against what was actually reported, so an 89.5% session has NOT crossed
+ * a 90% critical line. The LABEL then adapts its precision to this same number (see
+ * `ctxValueText`) so what the card displays can never contradict what it claims.
+ */
+export function ctxReading(pct) {
+    return isReading(pct) ? Math.min(100, Math.max(0, pct)) : undefined;
+}
+/**
+ * Band for a context reading, derived from the reading AS REPORTED — 89.5 has not crossed a 90
+ * critical line and must not be shown as though it had. Absent ⇒ `"unknown"`. The thresholds are
+ * normalized (and ordered) first, so the band and the bar's ticks always agree.
+ */
+export function ctxBand(pct, thresholds) {
+    const v = ctxReading(pct);
+    if (v === undefined)
+        return "unknown";
+    const t = normalizeCtxThresholds(thresholds);
+    if (v >= t.critical)
+        return "error";
+    if (v >= t.warn)
+        return "warn";
+    return "ok";
+}
+/**
+ * The 0–100 fill length, or `undefined` when there is no reading. `undefined` means the binding
+ * draws NO fill at all — the caller must never substitute 0, which would render as a confident
+ * "empty context" (invariant 1).
+ */
+export function ctxFillPct(pct) {
+    return ctxReading(pct);
+}
+/** What an absent reading renders as — never `"0%"`. */
+export const CTX_UNKNOWN_TEXT = "—";
+/** How many decimal places the value may grow to before it is shown verbatim. */
+const CTX_VALUE_PLACES = [0, 1, 2];
+/**
+ * The meter's right-hand value: `"62%"` for a reading, `"—"` for none (invariant 1).
+ *
+ * Whole percents are what the design card shows, but a rounded percent must never contradict the
+ * band the card is enforcing: at the default thresholds, 89.5% is `warn`, so displaying it as
+ * "90%" would put an amber card next to the critical number. The label therefore takes the FIRST
+ * precision whose displayed number lands in the same band as the reading — "89.5%" here, plain
+ * "62%" in the ordinary case — falling back to the reading verbatim, which by definition agrees.
+ */
+export function ctxValueText(pct, thresholds) {
+    const v = ctxReading(pct);
+    if (v === undefined)
+        return CTX_UNKNOWN_TEXT;
+    const band = ctxBand(v, thresholds);
+    for (const places of CTX_VALUE_PLACES) {
+        const shown = Number(v.toFixed(places));
+        if (ctxBand(shown, thresholds) === band)
+            return `${shown}%`;
+    }
+    return `${v}%`;
+}
+/** The meter's left-hand label and the separator the card composes its notes with. */
+export const CTX_LABEL = "context";
+export const SESSION_CARD_SEP = " · ";
+/**
+ * The meter's left-hand note. The design card annotates the band (`context · distill suggested` at
+ * warn, `context · distill now` at error, `context · stale` for a stale reading); the unknown state
+ * says so outright, and says it BEFORE `stale` — "stale" implies a last-known value, so it must
+ * never stand in for "we never measured it".
+ */
+export function ctxNoteText(band, opts) {
+    if (band === "unknown")
+        return `${CTX_LABEL}${SESSION_CARD_SEP}not measured`;
+    if (isObject(opts) && opts.stale === true)
+        return `${CTX_LABEL}${SESSION_CARD_SEP}stale`;
+    if (band === "error")
+        return `${CTX_LABEL}${SESSION_CARD_SEP}distill now`;
+    if (band === "warn")
+        return `${CTX_LABEL}${SESSION_CARD_SEP}distill suggested`;
+    return CTX_LABEL;
+}
+/** Wrapper class for the meter — the band modifier tints the fill AND the value in one place. */
+export function ctxMeterClass(input) {
+    const band = isObject(input) ? input.band : "unknown";
+    const stale = isObject(input) && input.stale === true;
+    return `my-session-card__ctx my-session-card__ctx--${band}${stale ? " is-stale" : ""}`;
+}
+// ── bar geometry (SVG presentation attributes only — CSP forbids the inline `width:62%` the
+//    design prototype used, and product-tunable ticks cannot be expressed as fixed classes) ──
+/** The bar's user-space width: percent IS the x axis, so a reading maps 1:1 onto it. */
+export const CTX_BAR_SPAN = 100;
+/** The bar's user-space height (the design card's 8px rail). */
+export const CTX_BAR_HEIGHT = 8;
+/** `viewBox` for the bar; the binding stretches it to the card width (`preserveAspectRatio="none"`). */
+export const CTX_BAR_VIEWBOX = `0 0 ${CTX_BAR_SPAN} ${CTX_BAR_HEIGHT}`;
+/** Tick width in user space (≈1.5px once the bar is stretched to a ~250px card). */
+export const CTX_BAR_TICK_WIDTH = 0.6;
+/**
+ * Pure bar geometry, from the SAME normalized thresholds `ctxBand` uses — an unusable threshold
+ * falls back to the default in both places, so the ticks always mark the boundaries the band is
+ * actually enforcing. Duplicates collapse, so `{warn: 90, critical: 90}` draws one tick, not two
+ * stacked ones.
+ */
+export function ctxBarGeom(pct, thresholds) {
+    const norm = normalizeCtxThresholds(thresholds);
+    const seen = new Set();
+    const ticks = [];
+    for (const t of [norm.warn, norm.critical]) {
+        if (seen.has(t))
+            continue;
+        seen.add(t);
+        const x = Math.min(CTX_BAR_SPAN - CTX_BAR_TICK_WIDTH, Math.max(0, t - CTX_BAR_TICK_WIDTH / 2));
+        ticks.push({ pct: t, x, width: CTX_BAR_TICK_WIDTH });
+    }
+    ticks.sort((a, b) => a.pct - b.pct);
+    return { span: CTX_BAR_SPAN, height: CTX_BAR_HEIGHT, fill: ctxFillPct(pct), ticks };
+}
+/** The design card's context escalation: at warn/error the status line stops restating the
+ *  lifecycle and names the thing that actually needs acting on. */
+const CONTEXT_ESCALATION = {
+    warn: { key: "context-high", label: "context high", tone: "warn" },
+    error: { key: "context-critical", label: "context critical", tone: "error" },
+};
+/** Statuses the context escalation may speak over: a live session, or one whose lifecycle was
+ *  never reported. A TERMINAL or TRANSIENT lifecycle claim (stopped/failed/spawning/stopping/
+ *  paused) and a DOWN LINK are all more important than a hot context and keep the line. */
+const ESCALATABLE_KEYS = new Set(["working", "idle", "active", "unknown"]);
+const LIFECYCLE_STATUS = {
+    spawning: { label: "spawning…", tone: "info", pulse: true },
+    active: { label: "active", tone: "ok", pulse: false },
+    stopping: { label: "stopping…", tone: "warn", pulse: true },
+    stopped: { label: "stopped", tone: "muted", pulse: false },
+    failed: { label: "failed", tone: "error", pulse: false },
+    paused: { label: "paused", tone: "warn", pulse: false },
+};
+/** The honest "we were told nothing" status — distinct key AND distinct tone from `idle`. */
+export const SESSION_STATUS_UNKNOWN = {
+    key: "unknown",
+    label: "unknown",
+    tone: "unknown",
+    pulse: false,
+};
+/**
+ * Derive the card's status. Precedence, and why:
+ *
+ *  1. A DOWN LINK on a session the product calls `active` — or on one whose lifecycle it does not
+ *     report at all — wins: whatever else was claimed, we are not hearing from it. It does NOT
+ *     override `spawning`/`stopping`/`stopped`/`failed`, whose own lifecycle already explains the
+ *     missing link. The label is `"disconnected"`, not the design prototype's "reconnecting…":
+ *     retry machinery is a product capability this atom cannot verify (a product that really does
+ *     retry can pass its own `statusLabel`).
+ *  2. An ACTIVITY claim, but only for a session that is `active` or has no reported lifecycle —
+ *     a "working" claim about a stopped session is a contradiction, and the lifecycle is the
+ *     stronger truth.
+ *  3. The LIFECYCLE claim. This is where an active-but-no-activity session lands: `"active"`,
+ *     never a fabricated `"idle"` or `"working"` (invariant 2).
+ *  4. Nothing reported at all ⇒ `"unknown"` (invariant 2).
+ */
+export function sessionStatus(input, contextBand) {
+    const base = baseSessionStatus(input);
+    // The design card's warn/error states replace the status line with the context claim ("context
+    // high" / "context critical", in the band's hue). It is a claim about a REAL MEASUREMENT, so it
+    // never fabricates anything — and `unknown` is not a band, so an unmeasured session is never
+    // escalated (invariant 1). The underlying pulse rides along: a working session that goes hot is
+    // still working.
+    if ((contextBand === "warn" || contextBand === "error") && ESCALATABLE_KEYS.has(base.key)) {
+        const esc = CONTEXT_ESCALATION[contextBand];
+        return { key: esc.key, label: esc.label, tone: esc.tone, pulse: base.pulse };
+    }
+    return base;
+}
+function baseSessionStatus(input) {
+    const { lifecycle, activity, connected } = isObject(input) ? input : {};
+    if (connected === false && (lifecycle === "active" || lifecycle === undefined)) {
+        return { key: "disconnected", label: "disconnected", tone: "muted", pulse: true };
+    }
+    if (lifecycle === "active" || lifecycle === undefined) {
+        if (activity === "working")
+            return { key: "working", label: "working", tone: "ok", pulse: true };
+        if (activity === "idle")
+            return { key: "idle", label: "idle", tone: "muted", pulse: false };
+    }
+    if (lifecycle !== undefined) {
+        const base = LIFECYCLE_STATUS[lifecycle];
+        return { key: lifecycle, label: base.label, tone: base.tone, pulse: base.pulse };
+    }
+    return SESSION_STATUS_UNKNOWN;
+}
+/** Status class: tone modifier + the transient-pulse flag. The dot is a child element, so the
+ *  modifier tints the words and the dot together. */
+export function sessionStatusClass(status) {
+    return `my-session-card__status my-session-card__status--${status.tone}${status.pulse ? " is-pulse" : ""}`;
+}
+/**
+ * Whether the card wears the design's STALE treatment (dashed border, muted values) — true exactly
+ * when the link is down. Kept here rather than in the binding so both bindings, and any product
+ * that wants to pre-compute it, agree on one rule.
+ */
+export function sessionCardIsStale(status) {
+    return status.key === "disconnected";
+}
+/**
+ * The card's stale treatment, including a product's own claim. A product may ADD staleness (its
+ * data is old for a reason the card cannot see); it may NOT take away the staleness a down link
+ * implies — `stale={false}` on a disconnected session would paint it as a live, solid-bordered
+ * card, which is exactly the lie this treatment exists to prevent.
+ */
+export function sessionCardStale(status, productClaim) {
+    return sessionCardIsStale(status) || productClaim === true;
+}
+/** Every word the derivation reserves, mapped to the status key that earns it. An override may
+ *  not borrow another key's word — that is how a product would launder a claim it never made. */
+const RESERVED_STATUS_WORDS = new Map([
+    ["working", "working"],
+    ["idle", "idle"],
+    ["active", "active"],
+    ["spawning", "spawning"],
+    ["stopping", "stopping"],
+    ["stopped", "stopped"],
+    ["failed", "failed"],
+    ["paused", "paused"],
+    ["disconnected", "disconnected"],
+    ["unknown", "unknown"],
+    ["context high", "context-high"],
+    ["context critical", "context-critical"],
+]);
+/** Fold a candidate word to the form the reserved map is keyed by (the derived labels carry a
+ *  trailing ellipsis on the transient states). */
+function normalizeStatusWord(word) {
+    return word.trim().toLowerCase().replace(/(…|\.{3})$/, "").trim();
+}
+/**
+ * The ACTIVITY vocabulary invariant 2 is about, guarded more tightly than the rest of the reserved
+ * words: these two are refused ANYWHERE in an override ("currently idle", "working now"), not just
+ * as the whole of it, unless the derivation itself produced that activity. Every other reserved
+ * word is an exact-match refusal — the atom polices the vocabulary the invariant names, and does
+ * not try to police arbitrary prose (a product determined to editorialize can always find other
+ * words; what it cannot do is state the specific claim the wire never made).
+ */
+const ACTIVITY_WORD_PATTERNS = [
+    { key: "idle", re: /\bidle\b/i },
+    { key: "working", re: /\bworking\b/i },
+];
+/**
+ * The words beside the dot. A product may substitute its own honest phrasing for the derived
+ * label — the tone, the pulse and the stale treatment still come from the derivation.
+ *
+ * Three refusals:
+ *   · a BLANK override falls back to the derived label, rather than leaving the status as colour
+ *     alone (token rule #7);
+ *   · the `unknown` status ignores the override entirely. There is no alternative honest wording
+ *     for "the product told us nothing" — nothing was claimed, so there is nothing to reword;
+ *   · an override that states another status's claim is ignored. `statusLabel="idle"` — or
+ *     `"currently idle"` — on a session whose activity was never reported would state a claim no
+ *     wire made; invariant 2 is structural here, not a matter of trusting the caller. The two
+ *     ACTIVITY words are refused anywhere in the override; every other reserved word is refused
+ *     only as the whole of it. Rewording is still free: anything outside that vocabulary
+ *     (`"wake unavailable"`, `"stopped (exit 1)"`, …) passes.
+ *
+ * Documented limit: a status the context escalation has taken over (`context high` /
+ * `context critical`) can no longer use an activity word either, even if the wire did report one —
+ * the rendered status is the context claim, and the product can word it another way.
+ */
+export function sessionStatusText(status, override) {
+    if (status.key === "unknown")
+        return status.label;
+    if (typeof override !== "string" || override.trim().length === 0)
+        return status.label;
+    const reserved = RESERVED_STATUS_WORDS.get(normalizeStatusWord(override));
+    if (reserved !== undefined && reserved !== status.key)
+        return status.label;
+    for (const { key, re } of ACTIVITY_WORD_PATTERNS) {
+        if (status.key !== key && re.test(override))
+            return status.label;
+    }
+    return override;
+}
+// ════════════════════════════════════════════════════════════════════════════════════════
+// card container, identity line, subline
+// ════════════════════════════════════════════════════════════════════════════════════════
+/** Container class — the WHOLE class attribute the card's root carries, including any extra
+ *  classes a product passes, so neither binding composes a class string of its own. `selected` and
+ *  `stale` are INDEPENDENT: a selected session can also be disconnected, so they are two
+ *  modifiers, never one enum. */
+export function sessionCardClass(input) {
+    const i = isObject(input) ? input : {};
+    const extra = typeof i.extra === "string" ? i.extra.trim() : "";
+    return (`my-session-card${i.selected === true ? " is-selected" : ""}${i.stale === true ? " is-stale" : ""}` +
+        (extra.length > 0 ? ` ${extra}` : ""));
+}
+/** What an unnameable session's avatar shows — a question mark, not a fabricated initial. */
+export const SESSION_AVATAR_UNKNOWN = "?";
+/** Avatar initial: the first alphanumeric of the display name, uppercased; `"?"` when there is
+ *  none. (Merges the two divergent copies the product carried — the rail card's "first char,
+ *  em-dash fallback" and derive.ts's "first alphanumeric, ?-fallback" — on the latter, which
+ *  cannot emit punctuation or whitespace as an initial.) */
+export function sessionAvatarInitial(name) {
+    const m = String(name ?? "").match(/[a-z0-9]/i);
+    return m ? m[0].toUpperCase() : SESSION_AVATAR_UNKNOWN;
+}
+/**
+ * The card's meta subline — `role · model · duration` on the design card, but deliberately a free
+ * list: the spec's own states also use it for `role · model · queued: 1 ON-DONE` and
+ * `role · last seen 00:12 ago`. Absent/blank parts COLLAPSE, so there is never a dangling
+ * separator, and an all-absent list yields `""` (the binding then omits the element entirely
+ * rather than rendering an empty row).
+ */
+export function sessionSubline(parts) {
+    return (Array.isArray(parts) ? parts : [])
+        .map((p) => (typeof p === "string" ? p.trim() : ""))
+        .filter((p) => p.length > 0)
+        .join(SESSION_CARD_SEP);
+}
+/**
+ * The most nodes the strip will draw. The strip is a fixed-width row of 13px nodes, so beyond this
+ * they cannot be told apart anyway — and a runaway count from a malformed wire value must not be
+ * able to build an unbounded node list and lock the render. The LABEL beside the strip always
+ * states the TRUE count, so the bound costs no honesty: the strip is a bounded illustration, the
+ * number is the claim.
+ */
+export const SPINE_MAX_NODES = 24;
+/**
+ * Nodes for the strip: one filled node per completed distill, plus the hollow live tip.
+ * An UNREPORTED `distills` yields `[]` — no strip, no fabricated "0 distills" (invariant 1). A
+ * REPORTED 0 is a real reading and yields the tip alone. Non-integer/negative counts are floored,
+ * and the list is capped at `SPINE_MAX_NODES` so a runaway value cannot lock the render (the
+ * strip's label still states the true count).
+ */
+export function sessionSpineNodes(distills) {
+    if (!isReading(distills))
+        return [];
+    const n = Math.min(SPINE_MAX_NODES - 1, Math.max(0, Math.floor(distills)));
+    const nodes = [];
+    for (let i = 0; i < n; i++)
+        nodes.push({ tip: false });
+    nodes.push({ tip: true });
+    return nodes;
+}
+/** Compact token count: `41.2k`, `1.3M`, `412`. */
+function compactTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}k`;
+    return `${Math.round(n)}`;
+}
+/** What an unreported token saving renders as. */
+export const SPINE_SAVED_UNKNOWN = CTX_UNKNOWN_TEXT;
+/**
+ * The strip's right-hand value. Absent ⇒ `"—"` (invariant 1). A saving is a REDUCTION, so it
+ * carries a real minus sign (U+2212); a reported 0 is unsigned; a negative input (context grew)
+ * is stated as growth rather than silently re-signed.
+ */
+export function sessionSpineSavedText(savedTok) {
+    if (!isReading(savedTok))
+        return SPINE_SAVED_UNKNOWN;
+    if (savedTok === 0)
+        return "0 tok";
+    return `${savedTok > 0 ? "−" : "+"}${compactTokens(Math.abs(savedTok))} tok`;
+}
+/** The strip's left-hand label: `spine · 3 distills` (singular at 1). */
+export function sessionSpineLabel(distills) {
+    const n = Math.max(0, Math.floor(distills));
+    return `spine${SESSION_CARD_SEP}${n} ${n === 1 ? "distill" : "distills"}`;
+}
+/**
+ * The whole strip, or `undefined` when the product reported no distill count — the card then
+ * renders no strip at all. `spine.savedTok` is independent: a reported distill count with an
+ * unreported saving still draws the strip, with `"—"` for the value.
+ */
+export function sessionSpineSummary(spine) {
+    if (!spine || !isReading(spine.distills))
+        return undefined;
+    return {
+        nodes: sessionSpineNodes(spine.distills),
+        label: sessionSpineLabel(spine.distills),
+        value: sessionSpineSavedText(spine.savedTok),
+    };
+}
+/** Class for one spine node — filled distill vs. the hollow live tip. */
+export function spineNodeClass(node) {
+    return `my-session-card__spine-node${node.tip ? " my-session-card__spine-node--tip" : ""}`;
+}

package/dist/logic/terminal.d.ts

@@ -0,0 +1,222 @@
+/** The one class that carries the always-heritage-dark surface (token rule 3). */
+export declare const TERM_CLASS = "my-term";
+/**
+ * Every structural class the pane renders. Named here — not typed literally in a binding — so the
+ * Preact and React bindings cannot drift, and so the stylesheet guard can enumerate the real
+ * surface instead of a hand-copied list.
+ */
+export declare const TERM_CLASSES: {
+    readonly pane: "my-term";
+    readonly titlebar: "my-term__titlebar";
+    readonly lights: "my-term__lights";
+    readonly light: "my-term__light";
+    readonly lightRed: "my-term__light my-term__light--r";
+    readonly lightAmber: "my-term__light my-term__light--a";
+    readonly lightGreen: "my-term__light my-term__light--g";
+    readonly noiseToggle: "my-term__noise";
+    readonly staticTitle: "my-term__title";
+    readonly titleRight: "my-term__tb-right";
+    readonly turn: "my-term__turn";
+    readonly turnDot: "my-term__turn-dot";
+    readonly idle: "my-term__idle";
+    readonly stopKey: "my-term__stop-key";
+    readonly body: "my-term__body";
+    readonly banner: "my-term__banner";
+    readonly bannerDot: "my-term__banner-dot";
+    readonly state: "my-term__state";
+    readonly label: "my-term__label";
+    readonly head: "my-term__head";
+    readonly expand: "my-term__expand";
+    readonly detail: "my-term__detail";
+    readonly more: "my-term__more";
+    readonly segment: "my-term__hist";
+    readonly segmentCaption: "my-term__hist-cap";
+    readonly caret: "my-term__caret";
+};
+/**
+ * Transcript row kinds. Generic on purpose — this package knows nothing about any product's
+ * event wire format; a consumer maps its own stream onto these.
+ *  - `boundary` — a wake/session marker; also the segmentation anchor (`currentWakeRows`).
+ *  - `local`    — a CLIENT-SYNTHETIC row (e.g. an interrupt marker). Deliberately its own kind so
+ *                 UI-originated rows can never masquerade as `system` output from the far side.
+ */
+export type TermRowKind = "assistant" | "user" | "tool" | "result" | "system" | "boundary" | "local" | "dim";
+export declare const TERM_ROW_KINDS: readonly TermRowKind[];
+export interface TermRow {
+    kind: TermRowKind;
+    /** The collapsed row's text. */
+    text: string;
+    /** Optional leading label (`assistant`, a tool name, …). */
+    label?: string;
+    /** Optional full body revealed by the row's expand affordance. */
+    detail?: string;
+    /** Stable key for expand state; the row index is used when absent. */
+    id?: string;
+    /** Noise rows are hidden unless noise is shown (see `noiseShow` / `visibleRows`). */
+    noise?: boolean;
+}
+/**
+ * One foreign transcript segment — another session's rows sharing this transcript. Shown ONLY
+ * behind the disclosure, captioned with its own immutable id and visually separated; never blended
+ * into the selected session's log.
+ */
+export interface TranscriptSegment {
+    id: string;
+    /** Overrides the default `session {id}` caption. */
+    caption?: string;
+    rows: readonly TermRow[];
+}
+/** Row class derivation — base + kind modifier. */
+export declare function termRowClass(kind: TermRowKind): string;
+/** A row is expandable exactly when the caller gave it a body to reveal. */
+export declare function isExpandable(row: TermRow): boolean;
+/** Label on a row's expand affordance, per its current state. */
+export declare const ROW_EXPAND_LABEL = "(expand)";
+export declare const ROW_COLLAPSE_LABEL = "(collapse)";
+export declare function expandLabel(expanded: boolean): string;
+/** Stable expand key for a single row — its own id, else its position. */
+export declare function rowKey(row: TermRow, index: number): string;
+/**
+ * Dedupe preferred keys into unique ones, preserving the FIRST occurrence verbatim so a caller's
+ * own id keeps identifying the same thing. Repeats take a `#n` disambiguator; the loop (rather than
+ * a counter) also covers a literal id that collides with a disambiguator already handed out.
+ */
+export declare function uniqueKeys(preferred: readonly string[]): string[];
+/**
+ * Collision-free keys for one list of rows. `id` is honored so expand state survives rows being
+ * prepended, but ids are NOT trusted to be unique: a repeated id would otherwise make two rows
+ * expand together and hand the renderer duplicate sibling keys.
+ */
+export declare function rowKeys(rows: readonly TermRow[]): string[];
+/**
+ * Identity for each foreign segment: its own id where it has one, its position otherwise, deduped.
+ * Using the id (not the position) is what keeps a segment's expand state attached to the segment
+ * when the list is reordered.
+ */
+export declare function segmentKeys(segments: readonly TranscriptSegment[]): string[];
+/** The row scopes a pane renders. Each is a distinct namespace for expand state. */
+export declare const ROW_SCOPE: {
+    readonly transcript: "t";
+    readonly local: "l";
+    readonly history: "h";
+};
+/**
+ * Namespace a list's row keys under a scope so expand state can NEVER leak between the transcript,
+ * the client-synthetic local rows and a history segment.
+ *
+ * A naive `${scope}:${key}` prefix is not enough: a transcript row whose id is literally `local:a`
+ * would then share state with the local row `a`. Every part is escaped before being joined, so the
+ * mapping from (scope parts, row key) to string is injective — two different tuples cannot produce
+ * the same key, whatever ids the caller supplies.
+ */
+export declare function scopedRowKeys(scope: readonly string[], rows: readonly TermRow[]): string[];
+/** Index of the LAST `boundary` row, or -1 when the transcript carries none. */
+export declare function lastBoundaryIndex(rows: readonly TermRow[]): number;
+/**
+ * Only the current wake: from the LAST `boundary` row (that row included, as the "you woke here"
+ * header) onward. With NO boundary the whole transcript IS one wake, so every row is returned —
+ * segmentation never silently blanks a log that simply carries no markers.
+ */
+export declare function currentWakeRows(rows: readonly TermRow[]): readonly TermRow[];
+/**
+ * The renderer option is INVERTED relative to the label: the noise FILTER being enabled means noise
+ * is HIDDEN, and the title line then reads `noise on` (the filter is on).
+ */
+export declare function noiseShow(noiseFilterEnabled: boolean): boolean;
+/** Drop `noise` rows unless noise is being shown. */
+export declare function visibleRows(rows: readonly TermRow[], showNoise: boolean): readonly TermRow[];
+/**
+ * The transcript's input. Six arms, four of which are DISTINCT unavailable states — collapsing any
+ * of them would make the pane claim knowledge it does not have.
+ */
+export type TermSource = {
+    kind: "loading";
+} | {
+    kind: "missing";
+} | {
+    kind: "unaddressable";
+} | {
+    kind: "failed";
+} | {
+    kind: "ready";
+    rows: readonly TermRow[];
+} | {
+    kind: "stale";
+    rows: readonly TermRow[];
+};
+export declare const TERM_LOADING_COPY = "Loading transcript\u2026";
+/** ONE neutral string for "the read succeeded and there is no transcript" — it never speculates
+ *  about lifecycle ("not started yet", "already cleaned up", …). */
+export declare const TERM_MISSING_COPY = "No transcript is available for this session.";
+export declare const TERM_UNADDRESSABLE_COPY = "This transcript can't be attributed to this session.";
+export declare const TERM_FAILED_COPY = "The transcript could not be loaded.";
+/** Stale banner. NO retry/reconnect claim — the design card's "connection lost · retrying (2/5)"
+ *  promises a recovery loop this component does not run. */
+export declare const TERM_STALE_COPY = "Transcript disconnected \u2014 showing the last received log.";
+/** Rendered when a live log has zero rows. Reachable ONLY from `ready`/`stale` (see
+ *  `transcriptView`) — a `loading` pane never renders it. */
+export declare const TERM_NO_EVENTS_COPY = "(no events)";
+/**
+ * HONESTY INVARIANT (binding, do not reword): the wake-unavailable banner says exactly that. Never
+ * "reconnecting", never "retrying (n/m)", never a spinner or countdown implying an automatic
+ * recovery is under way. The component makes no recovery attempt, so it must not look like one.
+ */
+export declare const TERM_WAKE_UNAVAILABLE_COPY = "wake unavailable";
+export type TermView = {
+    kind: "log";
+    stale: boolean;
+} | {
+    kind: "state";
+    copy: string;
+};
+/**
+ * HONESTY INVARIANT (binding): only `ready`/`stale` render a log; `stale` additionally flags the
+ * disconnected banner. `loading` renders the loading copy and NEVER `(no events)` — an unfinished
+ * read is not an empty transcript. `missing` / `unaddressable` / `failed` are three separate
+ * unavailable states with three separate messages.
+ */
+export declare function transcriptView(source: TermSource): TermView;
+/** The source's rows when it carries any (`ready`/`stale`), else `[]`. */
+export declare function sourceRows(source: TermSource): readonly TermRow[];
+/** `{name} · tail · noise {on|off}`; a nameless transcript falls back to `transcript`. */
+export declare function termTitleText(name: string | undefined, noiseFilterEnabled: boolean): string;
+export declare const TURN_IN_FLIGHT_COPY = "turn in flight";
+export declare const TURN_IDLE_COPY = "idle \u00B7 no turn in flight";
+/**
+ * HONESTY INVARIANT: the turn caption rides supplied truth only. `undefined` (the caller does not
+ * know) renders NOTHING — the pane never guesses a turn state, and in particular never shows "idle"
+ * merely because it was told nothing.
+ */
+export declare function turnCaption(turnInFlight: boolean | undefined): string | null;
+/**
+ * NEUTRAL history-toggle copy. Transcript files append generations in FILE order, so a foreign
+ * group can include NEWER sessions when the selected one is an older retained session — "earlier
+ * sessions" would be untruthful. The copy therefore only states that other sessions share this
+ * transcript.
+ */
+export declare function historyToggleLabel(show: boolean, count: number): string;
+/** Caption for one foreign transcript segment (gap: never blended into the selected log). */
+export declare function historySegmentCaption(id: string): string;
+/**
+ * Focused-terminal Ctrl-C → stop-turn. Requires: `c` + ctrl, NOT a key-repeat (holding Ctrl-C must
+ * not fire a burst), NO active text selection (so copy still works), and the pane focused.
+ */
+export declare function shouldStopOnKey(e: {
+    key?: unknown;
+    ctrlKey?: unknown;
+    repeat?: unknown;
+} | null, selectionText: string, paneHasFocus: boolean): boolean;
+/**
+ * DEVIATION FROM THE DESIGN CARD (deliberate, carried over from the shipped implementation this was
+ * extracted from): the card draws a light-surface "Stop turn" button beside the send bar. The
+ * shipped pane instead puts the stop control in the terminal's own title bar, right of the turn
+ * indicator, labelled `◼ stop ^C`. Two reasons it stays that way: the control belongs to the
+ * transcript it interrupts (the send bar can be disabled while a turn is still running), and the
+ * card's own caption already documents the `^C` keybinding, which the label surfaces. The colour
+ * treatment follows token rule 3 — inside the terminal the control wears the --my-term-* palette,
+ * not the app's danger red, which flips with the app theme.
+ */
+export declare const TERM_STOP_LABEL = "\u25FC stop";
+export declare const TERM_STOP_KEY_HINT = "^C";
+/** Stop control class; `is-prominent` is a VISUAL weight only, never a state claim. */
+export declare function stopButtonClass(prominent: boolean): string;