@mythicalos/ui-core 0.2.2 → 0.3.1

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;