@mythicalos/ui-core 0.2.1 → 0.3.0

package/dist/logic/save-bar.js

@@ -0,0 +1,54 @@
+// @mythicalos/ui-core — the dirty-state save bar's pure text composition + class derivation
+// (ds/layouts-settings.html: the bar pinned to the bottom of the settings screen —
+// `1 unsaved change · Base URL` on the left, Discard + the page's single primary on the right).
+//
+// Extracted from the reference implementation in the reference product's settings/projects pages,
+// which took a `(keyof MythicalConfig)[]` — a product config's key union. That product coupling is
+// lifted out here: the atom takes plain `string[]` field labels and composes the same sentence.
+//
+// The count/plural derivation and the separator live here (not in the bindings) so the Preact and
+// React renders can never drift, and so a consumer can assert the exact visible sentence without a
+// DOM — the same contract `composeToastText` holds for the toast.
+/** The separator between the bold "N unsaved change(s)" count and the changed-field list. */
+export const SAVE_BAR_SEP = " · ";
+/** Design-card copy for the two actions (ds/layouts-settings.html). Both are overridable per
+ *  surface — the reference product's settings page says "Save locally" because its save writes to
+ *  the local container, not the card's "Save & apply". */
+export const SAVE_BAR_DISCARD_LABEL = "Discard";
+export const SAVE_BAR_SAVE_LABEL = "Save & apply";
+/** Compose the save bar's note from the list of changed-field labels. Pluralization is decided
+ *  here, once, for both bindings. Non-string / blank entries are dropped rather than rendered as
+ *  `undefined` in the list — but they are dropped BEFORE the count, so the count always equals the
+ *  number of fields actually named. */
+export function saveBarNote(changed) {
+    const fields = (changed ?? []).filter((f) => typeof f === "string" && f.trim().length > 0);
+    const count = fields.length;
+    const countLabel = `${count} unsaved ${count === 1 ? "change" : "changes"}`;
+    const detail = fields.join(", ");
+    return {
+        count,
+        countLabel,
+        detail,
+        text: detail.length > 0 ? `${countLabel}${SAVE_BAR_SEP}${detail}` : countLabel,
+    };
+}
+/** The card's "the save bar slides up only when dirty" rule, as a predicate. The bindings return
+ *  `null` for a not-dirty bar so no surface can ever render "0 unsaved changes" next to a live
+ *  Save button. */
+export function saveBarDirty(changed) {
+    return saveBarNote(changed).count > 0;
+}
+/** Every class the bar renders, root and elements. The bindings import these rather than spelling
+ *  the strings themselves, so a rename cannot land in one framework and not the other, and the
+ *  stylesheet test can enumerate the parts instead of restating a hand-written list. */
+export const SAVE_BAR_PARTS = {
+    root: "my-savebar",
+    note: "my-savebar__note",
+    count: "my-savebar__count",
+    actions: "my-savebar__actions",
+};
+/** Root class for the bar. No tone axis — the modifier space is reserved for the caller's own
+ *  passthrough class, which the bindings append. */
+export function saveBarClass() {
+    return SAVE_BAR_PARTS.root;
+}

package/dist/logic/sendbar.d.ts

@@ -0,0 +1,105 @@
+/** Delivery class. `asap` takes the first turn gap; `on-done` waits for full idle. */
+export type DeliveryClass = "asap" | "on-done";
+export declare const DELIVERY_CLASSES: readonly DeliveryClass[];
+/** The class a bar starts on when the caller expresses no preference. One definition, so the two
+ *  bindings cannot ship different defaults. */
+export declare const DEFAULT_DELIVERY_CLASS: DeliveryClass;
+/** Verbatim badge/button label for a delivery class. */
+export declare function deliveryClassLabel(cls: DeliveryClass): "ASAP" | "ON-DONE";
+/**
+ * HONESTY INVARIANT (binding, do not reword): delivery ALWAYS waits for a turn boundary. The design
+ * card's older per-class wording — "ASAP interrupts · ON-DONE waits" — is FALSE: nothing about ASAP
+ * interrupts a turn in flight, it merely takes the FIRST gap between turns. This one combined line
+ * replaces both of the card's per-class hints. Never reintroduce "interrupts" here.
+ */
+export declare const DELIVERY_HINT = "ASAP takes the first turn gap \u00B7 ON-DONE waits for full idle.";
+/** Enabled placeholder when the caller supplies no target name. */
+export declare const SEND_PLACEHOLDER = "Message\u2026 (\u23CE send \u00B7 \u21E7\u23CE newline)";
+/** Last-resort disabled placeholder when the caller supplies no reason. Says only that sending is
+ *  unavailable — it never speculates about why. */
+export declare const SEND_DISABLED_FALLBACK = "Sending is unavailable.";
+/**
+ * Placeholder copy. Disabled ⇒ the caller's honest reason (or the neutral fallback); enabled ⇒ the
+ * design's named prompt `Message {name}… (⏎ send · ⇧⏎ newline)` when a target name is supplied,
+ * otherwise the nameless form. A disabled bar NEVER shows the enabled prompt.
+ */
+export declare function sendPlaceholder(disabled: boolean, disabledReason?: string, targetName?: string): string;
+/** Send is possible only with non-blank text, when enabled and not mid-send. */
+export declare function canSend(text: string, disabled: boolean, busy: boolean): boolean;
+/**
+ * The ASAP/ON-DONE semantics line renders ONLY where the delivery controls are actually usable — a
+ * disabled bar surfaces just the truthful reason (through the placeholder), never per-class
+ * semantics for controls the user cannot operate.
+ */
+export declare function showDeliveryHint(disabled: boolean): boolean;
+/**
+ * Single-flight gate for the send action. `canSend`'s `busy` argument covers the case where the
+ * CALLER tracks the in-flight state, but `onSend` may be async and a caller that flips `busy` in a
+ * later tick (or not at all) leaves a window in which two clicks — or a click racing an Enter —
+ * both call `onSend` and deliver the same message twice. The gate closes that window inside the
+ * component: it is synchronous, so the second attempt in the same tick is refused before any state
+ * update can land.
+ *
+ * Lives here rather than in a binding so both bindings get identical semantics, and so the race is
+ * testable without a DOM.
+ */
+export interface SendGate {
+    /** Takes the lock and returns true; returns false when a send is already in flight. */
+    tryAcquire(): boolean;
+    /** Releases the lock. Safe to call when not held. */
+    release(): void;
+    inFlight(): boolean;
+}
+export declare function makeSendGate(): SendGate;
+/**
+ * Resolve one send attempt to a plain success/failure.
+ *
+ * `onSend` is contracted to resolve a boolean, but it is caller code and may REJECT. Letting that
+ * rejection escape an async event handler surfaces it as an unhandled rejection — an application
+ * error, in many apps a full error overlay — for what is really just a send that did not land. So a
+ * rejection is treated as a FAILED send: nothing was delivered, the draft is kept, and the failure
+ * is handed to `onError` so the caller can still see it. It is never swallowed silently AND never
+ * reported as a success: anything other than a resolved `true` is a failure.
+ *
+ * Lives here so both bindings behave identically and so the rejection path is testable without a
+ * DOM.
+ */
+export declare function resolveSend(attempt: () => boolean | Promise<boolean>, onError?: (error: unknown) => void): Promise<boolean>;
+/**
+ * The draft clears ONLY on a delivered/queued success AND only when the field still holds exactly
+ * the submitted body — the field stays editable while the request is in flight, so text typed
+ * meanwhile is a NEWER draft a completing send must not erase. A failed send keeps the text either
+ * way, so the user retries without retyping.
+ */
+export declare function clearDraftOnSend(sent: boolean, submitted: string, current: string): boolean;
+/** Textarea key semantics: Enter=send, Shift/Alt-Enter=newline, IME composition suppressed. */
+export type KeyAction = "send" | "newline" | "none";
+/**
+ * HONESTY INVARIANT: an in-progress IME composition NEVER sends — `isComposing` short-circuits to
+ * `none` so a CJK/dead-key commit press can't fire a delivery the user did not ask for.
+ */
+export declare function keyAction(ev: unknown): KeyAction;
+/** The send button's label. */
+export declare const SEND_BUTTON_LABEL = "Send";
+/**
+ * Every structural class the send bar renders. Named here — not typed literally in a binding — so
+ * the Preact and React bindings cannot drift.
+ *
+ * DEVIATION FROM THE DESIGN CARD (deliberate, carried over from the shipped implementation this was
+ * extracted from): the card draws the delivery class as a `<select>`. The shipped bar uses a
+ * two-button segmented control with `aria-pressed`, because with exactly two mutually exclusive
+ * options both are visible at once — the current class is readable without opening a menu, which is
+ * what a delivery decision needs. Everything else in the bar follows the card.
+ */
+export declare const SENDBAR_CLASSES: {
+    readonly wrap: "my-sendbar-wrap";
+    readonly segment: "my-sendbar__seg";
+    readonly input: "my-sendbar__input";
+    readonly send: "my-sendbar__send";
+    readonly hint: "my-sendbar__hint";
+    readonly notice: "my-sendbar__notice";
+};
+/** The bar wrapper: `my-sendbar`, plus `is-disabled` when the whole bar is unusable. */
+export declare function sendBarClass(disabled: boolean): string;
+/** One delivery-class segment button; `is-on` marks the current selection. */
+export declare function deliveryClassButtonClass(selected: boolean): string;

package/dist/logic/sendbar.js

@@ -0,0 +1,136 @@
+// @mythicalos/ui-core — the send bar half of the terminal set (ds/components-terminal, spec v2):
+// delivery-class selection, draft/keyboard semantics, and the honest per-class hint. Pure — both
+// the Preact and React bindings derive every class string and every user-visible string from here,
+// so the two bindings (and any future one) cannot drift on the copy that carries the honesty.
+export const DELIVERY_CLASSES = ["asap", "on-done"];
+/** The class a bar starts on when the caller expresses no preference. One definition, so the two
+ *  bindings cannot ship different defaults. */
+export const DEFAULT_DELIVERY_CLASS = "asap";
+/** Verbatim badge/button label for a delivery class. */
+export function deliveryClassLabel(cls) {
+    return cls === "asap" ? "ASAP" : "ON-DONE";
+}
+/**
+ * HONESTY INVARIANT (binding, do not reword): delivery ALWAYS waits for a turn boundary. The design
+ * card's older per-class wording — "ASAP interrupts · ON-DONE waits" — is FALSE: nothing about ASAP
+ * interrupts a turn in flight, it merely takes the FIRST gap between turns. This one combined line
+ * replaces both of the card's per-class hints. Never reintroduce "interrupts" here.
+ */
+export const DELIVERY_HINT = "ASAP takes the first turn gap · ON-DONE waits for full idle.";
+/** Enabled placeholder when the caller supplies no target name. */
+export const SEND_PLACEHOLDER = "Message… (⏎ send · ⇧⏎ newline)";
+/** Last-resort disabled placeholder when the caller supplies no reason. Says only that sending is
+ *  unavailable — it never speculates about why. */
+export const SEND_DISABLED_FALLBACK = "Sending is unavailable.";
+/**
+ * Placeholder copy. Disabled ⇒ the caller's honest reason (or the neutral fallback); enabled ⇒ the
+ * design's named prompt `Message {name}… (⏎ send · ⇧⏎ newline)` when a target name is supplied,
+ * otherwise the nameless form. A disabled bar NEVER shows the enabled prompt.
+ */
+export function sendPlaceholder(disabled, disabledReason, targetName) {
+    if (disabled)
+        return disabledReason ?? SEND_DISABLED_FALLBACK;
+    const name = targetName?.trim();
+    return name ? `Message ${name}… (⏎ send · ⇧⏎ newline)` : SEND_PLACEHOLDER;
+}
+/** Send is possible only with non-blank text, when enabled and not mid-send. */
+export function canSend(text, disabled, busy) {
+    return !disabled && !busy && text.trim().length > 0;
+}
+/**
+ * The ASAP/ON-DONE semantics line renders ONLY where the delivery controls are actually usable — a
+ * disabled bar surfaces just the truthful reason (through the placeholder), never per-class
+ * semantics for controls the user cannot operate.
+ */
+export function showDeliveryHint(disabled) {
+    return !disabled;
+}
+export function makeSendGate() {
+    let held = false;
+    return {
+        tryAcquire() {
+            if (held)
+                return false;
+            held = true;
+            return true;
+        },
+        release() {
+            held = false;
+        },
+        inFlight() {
+            return held;
+        },
+    };
+}
+/**
+ * Resolve one send attempt to a plain success/failure.
+ *
+ * `onSend` is contracted to resolve a boolean, but it is caller code and may REJECT. Letting that
+ * rejection escape an async event handler surfaces it as an unhandled rejection — an application
+ * error, in many apps a full error overlay — for what is really just a send that did not land. So a
+ * rejection is treated as a FAILED send: nothing was delivered, the draft is kept, and the failure
+ * is handed to `onError` so the caller can still see it. It is never swallowed silently AND never
+ * reported as a success: anything other than a resolved `true` is a failure.
+ *
+ * Lives here so both bindings behave identically and so the rejection path is testable without a
+ * DOM.
+ */
+export async function resolveSend(attempt, onError) {
+    try {
+        return (await attempt()) === true;
+    }
+    catch (error) {
+        onError?.(error);
+        return false;
+    }
+}
+/**
+ * The draft clears ONLY on a delivered/queued success AND only when the field still holds exactly
+ * the submitted body — the field stays editable while the request is in flight, so text typed
+ * meanwhile is a NEWER draft a completing send must not erase. A failed send keeps the text either
+ * way, so the user retries without retyping.
+ */
+export function clearDraftOnSend(sent, submitted, current) {
+    return sent === true && submitted === current;
+}
+/**
+ * HONESTY INVARIANT: an in-progress IME composition NEVER sends — `isComposing` short-circuits to
+ * `none` so a CJK/dead-key commit press can't fire a delivery the user did not ask for.
+ */
+export function keyAction(ev) {
+    const e = ev;
+    if (!e || e.key !== "Enter" || e.isComposing)
+        return "none";
+    if (e.shiftKey || e.altKey)
+        return "newline";
+    return "send";
+}
+// ── class derivation ──
+/** The send button's label. */
+export const SEND_BUTTON_LABEL = "Send";
+/**
+ * Every structural class the send bar renders. Named here — not typed literally in a binding — so
+ * the Preact and React bindings cannot drift.
+ *
+ * DEVIATION FROM THE DESIGN CARD (deliberate, carried over from the shipped implementation this was
+ * extracted from): the card draws the delivery class as a `<select>`. The shipped bar uses a
+ * two-button segmented control with `aria-pressed`, because with exactly two mutually exclusive
+ * options both are visible at once — the current class is readable without opening a menu, which is
+ * what a delivery decision needs. Everything else in the bar follows the card.
+ */
+export const SENDBAR_CLASSES = {
+    wrap: "my-sendbar-wrap",
+    segment: "my-sendbar__seg",
+    input: "my-sendbar__input",
+    send: "my-sendbar__send",
+    hint: "my-sendbar__hint",
+    notice: "my-sendbar__notice",
+};
+/** The bar wrapper: `my-sendbar`, plus `is-disabled` when the whole bar is unusable. */
+export function sendBarClass(disabled) {
+    return disabled ? "my-sendbar is-disabled" : "my-sendbar";
+}
+/** One delivery-class segment button; `is-on` marks the current selection. */
+export function deliveryClassButtonClass(selected) {
+    return selected ? "my-sendbar__cls is-on" : "my-sendbar__cls";
+}

package/dist/logic/session-card.d.ts

@@ -0,0 +1,263 @@
+/** Product-tunable context thresholds (percent). Defaults per the design card's fixed ticks. */
+export interface CtxThresholds {
+    /** ≥ this reading is `warn`. */
+    warn: number;
+    /** ≥ this reading is `error` ("critical"). */
+    critical: number;
+}
+/** The design card's tick positions: warn at 75%, critical at 90% — overridable per product. */
+export declare const CTX_THRESHOLDS_DEFAULT: CtxThresholds;
+/**
+ * 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 declare function normalizeCtxThresholds(thresholds?: CtxThresholds | null): CtxThresholds;
+/**
+ * The context band. `"unknown"` is a FIRST-CLASS member, not a fallback to `"ok"`: a session with
+ * no reading (undefined/null/NaN/±Infinity) belongs to no health band — it is neither healthy nor
+ * hot (invariant 1).
+ */
+export type CtxBand = "unknown" | "ok" | "warn" | "error";
+/**
+ * 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 declare function ctxReading(pct: number | null | undefined): number | 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 declare function ctxBand(pct: number | null | undefined, thresholds?: CtxThresholds | null): CtxBand;
+/**
+ * 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 declare function ctxFillPct(pct: number | null | undefined): number | undefined;
+/** What an absent reading renders as — never `"0%"`. */
+export declare const CTX_UNKNOWN_TEXT = "\u2014";
+/**
+ * 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 declare function ctxValueText(pct: number | null | undefined, thresholds?: CtxThresholds | null): string;
+/** The meter's left-hand label and the separator the card composes its notes with. */
+export declare const CTX_LABEL = "context";
+export declare const SESSION_CARD_SEP = " \u00B7 ";
+/**
+ * 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 declare function ctxNoteText(band: CtxBand, opts?: {
+    stale?: boolean;
+} | null): string;
+/** Wrapper class for the meter — the band modifier tints the fill AND the value in one place. */
+export declare function ctxMeterClass(input?: {
+    band: CtxBand;
+    stale?: boolean;
+} | null): string;
+/** The bar's user-space width: percent IS the x axis, so a reading maps 1:1 onto it. */
+export declare const CTX_BAR_SPAN = 100;
+/** The bar's user-space height (the design card's 8px rail). */
+export declare const CTX_BAR_HEIGHT = 8;
+/** `viewBox` for the bar; the binding stretches it to the card width (`preserveAspectRatio="none"`). */
+export declare const CTX_BAR_VIEWBOX = "0 0 100 8";
+/** Tick width in user space (≈1.5px once the bar is stretched to a ~250px card). */
+export declare const CTX_BAR_TICK_WIDTH = 0.6;
+export interface CtxBarTick {
+    /** The threshold this tick marks. */
+    pct: number;
+    /** Left edge in user space — centred on `pct`, then kept inside the rail. */
+    x: number;
+    width: number;
+}
+export interface CtxBarGeom {
+    span: number;
+    height: number;
+    /** Fill width in user space. `undefined` ⇒ draw no fill rect at all (invariant 1). */
+    fill: number | undefined;
+    /** In-range, de-duplicated, ascending threshold ticks. */
+    ticks: CtxBarTick[];
+}
+/**
+ * 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 declare function ctxBarGeom(pct: number | null | undefined, thresholds?: CtxThresholds | null): CtxBarGeom;
+/** Lifecycle claims a product can make. Absent ⇒ the product reported no lifecycle. */
+export type SessionLifecycle = "spawning" | "active" | "stopping" | "stopped" | "failed" | "paused";
+/** Activity claims a product can make. Absent ⇒ NOT reported — never collapsed to `idle`. */
+export type SessionActivity = "working" | "idle";
+/** Colour axis. `"unknown"` is its own tone: the card renders a HOLLOW dot for it, so an
+ *  unmeasured session cannot be mistaken for a solid-dot claim of any kind. */
+export type SessionStatusTone = "ok" | "warn" | "error" | "info" | "muted" | "unknown";
+export type SessionStatusKey = "working" | "idle" | "context-high" | "context-critical" | "spawning" | "active" | "stopping" | "stopped" | "failed" | "paused" | "disconnected" | "unknown";
+export interface SessionStatus {
+    /** Machine-readable outcome — what the card decided, independent of wording. */
+    key: SessionStatusKey;
+    /** Default wording; the binding lets a product override it with its own honest phrasing. */
+    label: string;
+    tone: SessionStatusTone;
+    /** ≤1/s dot pulse — transient states only; a steady state never fakes motion. */
+    pulse: boolean;
+}
+/** Everything the card needs to state a session's status. Every field is OPTIONAL, and every
+ *  absent field means "the product did not report this" — never a default claim. */
+export interface SessionStatusInput {
+    lifecycle?: SessionLifecycle;
+    activity?: SessionActivity;
+    /** The session's link/wake readiness. `false` ⇒ down; `undefined` ⇒ not reported. */
+    connected?: boolean;
+}
+/** The honest "we were told nothing" status — distinct key AND distinct tone from `idle`. */
+export declare const SESSION_STATUS_UNKNOWN: SessionStatus;
+/**
+ * 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 declare function sessionStatus(input?: SessionStatusInput | null, contextBand?: CtxBand | null): SessionStatus;
+/** 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 declare function sessionStatusClass(status: SessionStatus): string;
+/**
+ * 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 declare function sessionCardIsStale(status: SessionStatus): boolean;
+/**
+ * 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 declare function sessionCardStale(status: SessionStatus, productClaim?: boolean): boolean;
+/**
+ * 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 declare function sessionStatusText(status: SessionStatus, override?: string | null): string;
+/** 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 declare function sessionCardClass(input?: {
+    selected?: boolean;
+    stale?: boolean;
+    extra?: string | null;
+} | null): string;
+/** What an unnameable session's avatar shows — a question mark, not a fabricated initial. */
+export declare 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 declare function sessionAvatarInitial(name: string | null | undefined): string;
+/**
+ * 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 declare function sessionSubline(parts?: readonly (string | null | undefined)[] | null): string;
+export interface SessionSpine {
+    /** Distills completed. `undefined` ⇒ the product did not report it — the strip is OMITTED. */
+    distills?: number;
+    /** Tokens saved. `undefined` ⇒ not reported — renders `"—"`, never `"0 tok"`. */
+    savedTok?: number;
+}
+/**
+ * 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 declare const SPINE_MAX_NODES = 24;
+export interface SpineNode {
+    /** The live tip (hollow); every other node is a completed distill (filled). */
+    tip: boolean;
+}
+/**
+ * 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 declare function sessionSpineNodes(distills: number | null | undefined): SpineNode[];
+/** What an unreported token saving renders as. */
+export declare const SPINE_SAVED_UNKNOWN = "\u2014";
+/**
+ * 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 declare function sessionSpineSavedText(savedTok: number | null | undefined): string;
+/** The strip's left-hand label: `spine · 3 distills` (singular at 1). */
+export declare function sessionSpineLabel(distills: number): string;
+export interface SpineSummary {
+    nodes: SpineNode[];
+    label: string;
+    value: string;
+}
+/**
+ * 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 declare function sessionSpineSummary(spine: SessionSpine | null | undefined): SpineSummary | undefined;
+/** Class for one spine node — filled distill vs. the hollow live tip. */
+export declare function spineNodeClass(node: SpineNode): string;