@mythicalos/ui-core 0.2.1 → 0.3.0

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/stat-tiles.d.ts

@@ -0,0 +1,49 @@
+/** Tile tone. `accent` is the design card's "brag" number (`.tile.save .v`); `warn`/`error` are the
+ *  gauge-band tint. Absent ⇒ a plain tile. */
+export type StatTileTone = "accent" | "warn" | "error";
+export interface StatTile {
+    /** Uppercase micro key, e.g. `tokens in`. */
+    label: string;
+    /** The already-formatted value — use the formatters below, or supply your own string. */
+    value: string;
+    /** Mono sub-caption under the value, e.g. `this session`. */
+    sub?: string;
+    tone?: StatTileTone;
+}
+/** The value shown when a number is absent or not finite. An em dash — NEVER a zero. */
+export declare const STAT_TILE_EMPTY = "\u2014";
+/** Unicode minus (U+2212), not an ASCII hyphen: it matches the digit metrics of the tabular-nums
+ *  mono face the tile value is set in. */
+export declare const STAT_TILE_MINUS = "\u2212";
+/** Every class the row renders, containers and elements — the bindings import these rather than
+ *  spelling the strings themselves, so the two frameworks cannot drift apart on a rename. */
+export declare const STAT_TILE_PARTS: {
+    readonly row: "my-stat-tiles";
+    readonly tile: "my-stat-tile";
+    readonly label: "my-stat-tile__label";
+    readonly value: "my-stat-tile__value";
+    readonly sub: "my-stat-tile__sub";
+};
+/** Row container class. */
+export declare function statTilesClass(): string;
+/** Tile class: base + optional tone modifier. */
+export declare function statTileClass(tone?: StatTileTone): string;
+/** Compact count: `500`, `12.8k`, `230k`, `1.5M`; negatives take the Unicode minus (`−212k`).
+ *  Absent/non-finite ⇒ `STAT_TILE_EMPTY`.
+ *
+ *  The unit is chosen from the ROUNDED value, not the raw one: rounding first and picking the unit
+ *  second would render `999.5` as `1000` and `999_999` as `1000k` — values that are noncanonical
+ *  for the scale and sit right in the middle of a normal token count. Each rung promotes to the
+ *  next when its own rounding carries it to 1000. `M` is the top rung — the design card defines no
+ *  unit above it, so a billion reads `1000M`, not `1B`. */
+export declare function formatStatCompact(n: number | null | undefined): string;
+/** Grouped count: `1,204,551` — the design card's tokens-in/out format. Deliberately NOT
+ *  `toLocaleString()`: the card's grouping is a fixed visual (comma every three digits, mono
+ *  tabular-nums), and a host locale must not silently turn it into `1.204.551`.
+ *  Absent/non-finite ⇒ `STAT_TILE_EMPTY`. */
+export declare function formatStatCount(n: number | null | undefined): string;
+/** USD: `$4.18`, always two decimals. Absent/non-finite ⇒ `STAT_TILE_EMPTY`. */
+export declare function formatStatUsd(n: number | null | undefined): string;
+/** Percent: `71%` by default, `94.5%` at `digits: 1` — the design card shows both forms.
+ *  Absent/non-finite ⇒ `STAT_TILE_EMPTY`. */
+export declare function formatStatPercent(n: number | null | undefined, digits?: number): string;

package/dist/logic/stat-tiles.js

@@ -0,0 +1,102 @@
+// @mythicalos/ui-core — the stat-tile row's tone→class derivation + the value formatters
+// (ds/components-stat-tiles.html: a flex-wrap row of bordered tiles, each an uppercase micro
+// "key", a big mono tabular-nums value, and a mono sub-caption; the "brag" tile paints its value
+// --my-accent-strong).
+//
+// Extracted from the reference implementation in the reference product's session detail pane. That
+// version took the product's `SessionVm` and hard-coded the five session tiles (tokens in/out,
+// prompt cache, cost, spine savings) INSIDE the component. That composition is the product's
+// domain, not the design system's: the atom here takes an already-composed `StatTile[]`, so a
+// consumer's view-model decides which tiles exist and in what order.
+//
+// What DID come along, because it is design and not product:
+//   - the "—" placeholder: an absent value renders the em dash, never a fabricated `0` / `$0.00`
+//     (partial data renders partially — never all-or-nothing),
+//   - the Unicode minus (U+2212, not a hyphen) on negative compact counts — the design card's
+//     spine-savings tile literally reads `−212k`,
+//   - the warn/error tone tint, which the reference drove off the context gauge's own 75/90 bands
+//     (token rule #4) — the thresholds themselves stay with the caller, only the tint is here.
+/** The value shown when a number is absent or not finite. An em dash — NEVER a zero. */
+export const STAT_TILE_EMPTY = "—";
+/** Unicode minus (U+2212), not an ASCII hyphen: it matches the digit metrics of the tabular-nums
+ *  mono face the tile value is set in. */
+export const STAT_TILE_MINUS = "−";
+/** Every class the row renders, containers and elements — the bindings import these rather than
+ *  spelling the strings themselves, so the two frameworks cannot drift apart on a rename. */
+export const STAT_TILE_PARTS = {
+    row: "my-stat-tiles",
+    tile: "my-stat-tile",
+    label: "my-stat-tile__label",
+    value: "my-stat-tile__value",
+    sub: "my-stat-tile__sub",
+};
+/** Row container class. */
+export function statTilesClass() {
+    return STAT_TILE_PARTS.row;
+}
+/** Tile class: base + optional tone modifier. */
+export function statTileClass(tone) {
+    const base = STAT_TILE_PARTS.tile;
+    return tone === undefined ? base : `${base} ${base}--${tone}`;
+}
+/** True only for a real, finite number — `undefined`, `null` and `NaN`/`Infinity` all fall through
+ *  to `STAT_TILE_EMPTY` rather than being coerced. */
+function isNum(n) {
+    return typeof n === "number" && Number.isFinite(n);
+}
+/** Strip a trailing `.0` so `230.0` → `230` while `12.8` stays `12.8`. */
+function stripZero(s) {
+    return s.endsWith(".0") ? s.slice(0, -2) : s;
+}
+/** Sign prefix for an already-rounded magnitude string. A negative input whose ROUNDED magnitude is
+ *  zero gets no sign — `−0` / `−$0.00` would be a lie about the direction of a value that landed on
+ *  zero at display precision. */
+function signed(n, body, zero) {
+    return n < 0 && body !== zero ? STAT_TILE_MINUS + body : body;
+}
+/** Compact count: `500`, `12.8k`, `230k`, `1.5M`; negatives take the Unicode minus (`−212k`).
+ *  Absent/non-finite ⇒ `STAT_TILE_EMPTY`.
+ *
+ *  The unit is chosen from the ROUNDED value, not the raw one: rounding first and picking the unit
+ *  second would render `999.5` as `1000` and `999_999` as `1000k` — values that are noncanonical
+ *  for the scale and sit right in the middle of a normal token count. Each rung promotes to the
+ *  next when its own rounding carries it to 1000. `M` is the top rung — the design card defines no
+ *  unit above it, so a billion reads `1000M`, not `1B`. */
+export function formatStatCompact(n) {
+    if (!isNum(n))
+        return STAT_TILE_EMPTY;
+    const abs = Math.abs(n);
+    let body;
+    if (Math.round(abs) < 1000)
+        body = String(Math.round(abs));
+    else if (Number((abs / 1000).toFixed(1)) < 1000)
+        body = `${stripZero((abs / 1000).toFixed(1))}k`;
+    else
+        body = `${stripZero((abs / 1_000_000).toFixed(1))}M`;
+    return signed(n, body, "0");
+}
+/** Grouped count: `1,204,551` — the design card's tokens-in/out format. Deliberately NOT
+ *  `toLocaleString()`: the card's grouping is a fixed visual (comma every three digits, mono
+ *  tabular-nums), and a host locale must not silently turn it into `1.204.551`.
+ *  Absent/non-finite ⇒ `STAT_TILE_EMPTY`. */
+export function formatStatCount(n) {
+    if (!isNum(n))
+        return STAT_TILE_EMPTY;
+    const grouped = String(Math.round(Math.abs(n))).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    return signed(n, grouped, "0");
+}
+/** USD: `$4.18`, always two decimals. Absent/non-finite ⇒ `STAT_TILE_EMPTY`. */
+export function formatStatUsd(n) {
+    if (!isNum(n))
+        return STAT_TILE_EMPTY;
+    return signed(n, `$${Math.abs(n).toFixed(2)}`, "$0.00");
+}
+/** Percent: `71%` by default, `94.5%` at `digits: 1` — the design card shows both forms.
+ *  Absent/non-finite ⇒ `STAT_TILE_EMPTY`. */
+export function formatStatPercent(n, digits = 0) {
+    if (!isNum(n))
+        return STAT_TILE_EMPTY;
+    const safeDigits = Math.max(0, Math.min(4, Math.trunc(digits)));
+    const body = `${Math.abs(n).toFixed(safeDigits)}%`;
+    return signed(n, body, `${(0).toFixed(safeDigits)}%`);
+}