@mythicalos/ui-core 0.2.2 → 0.3.1

package/dist/logic/terminal.js

@@ -0,0 +1,264 @@
+// @mythicalos/ui-core — the terminal half of the terminal set (ds/components-terminal, spec v2):
+// the transcript row model, source→view resolution, segmentation, and every user-visible string.
+// Pure — no framework, no DOM.
+//
+// TOKEN RULE 3 (ds/tokens): "Terminal surfaces always use the --my-term-* set, regardless of app
+// theme." The terminal is heritage-dark in BOTH themes. That is enforced in styles.css by the
+// `.my-term` block, which re-points the theme-flipping locals onto the fixed --my-term-* palette
+// for the whole subtree — `TERM_CLASS` is the single class that carries it, so a binding cannot
+// render a terminal that follows the app theme. The send bar and the queue rows are app chrome and
+// DO follow the theme (matching the design card, where both are drawn on the light surface).
+/** The one class that carries the always-heritage-dark surface (token rule 3). */
+export 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 const TERM_CLASSES = {
+    pane: TERM_CLASS,
+    titlebar: "my-term__titlebar",
+    lights: "my-term__lights",
+    light: "my-term__light",
+    lightRed: "my-term__light my-term__light--r",
+    lightAmber: "my-term__light my-term__light--a",
+    lightGreen: "my-term__light my-term__light--g",
+    noiseToggle: "my-term__noise",
+    staticTitle: "my-term__title",
+    titleRight: "my-term__tb-right",
+    turn: "my-term__turn",
+    turnDot: "my-term__turn-dot",
+    idle: "my-term__idle",
+    stopKey: "my-term__stop-key",
+    body: "my-term__body",
+    banner: "my-term__banner",
+    bannerDot: "my-term__banner-dot",
+    state: "my-term__state",
+    label: "my-term__label",
+    head: "my-term__head",
+    expand: "my-term__expand",
+    detail: "my-term__detail",
+    more: "my-term__more",
+    segment: "my-term__hist",
+    segmentCaption: "my-term__hist-cap",
+    caret: "my-term__caret",
+};
+export const TERM_ROW_KINDS = [
+    "assistant",
+    "user",
+    "tool",
+    "result",
+    "system",
+    "boundary",
+    "local",
+    "dim",
+];
+/** Row class derivation — base + kind modifier. */
+export function termRowClass(kind) {
+    return `my-term__row my-term__row--${kind}`;
+}
+/** A row is expandable exactly when the caller gave it a body to reveal. */
+export function isExpandable(row) {
+    return typeof row.detail === "string" && row.detail.length > 0;
+}
+/** Label on a row's expand affordance, per its current state. */
+export const ROW_EXPAND_LABEL = "(expand)";
+export const ROW_COLLAPSE_LABEL = "(collapse)";
+export function expandLabel(expanded) {
+    return expanded ? ROW_COLLAPSE_LABEL : ROW_EXPAND_LABEL;
+}
+/** Stable expand key for a single row — its own id, else its position. */
+export function rowKey(row, index) {
+    return row.id ?? String(index);
+}
+/**
+ * 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 function uniqueKeys(preferred) {
+    const arr = Array.isArray(preferred) ? preferred : [];
+    const used = new Set();
+    return arr.map((base) => {
+        let key = base;
+        for (let n = 1; used.has(key); n++)
+            key = `${base}#${n}`;
+        used.add(key);
+        return key;
+    });
+}
+/**
+ * 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 function rowKeys(rows) {
+    const arr = Array.isArray(rows) ? rows : [];
+    return uniqueKeys(arr.map((row, index) => rowKey(row, index)));
+}
+/**
+ * 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 function segmentKeys(segments) {
+    const arr = Array.isArray(segments) ? segments : [];
+    return uniqueKeys(arr.map((seg, index) => (seg?.id ? seg.id : String(index))));
+}
+/** The row scopes a pane renders. Each is a distinct namespace for expand state. */
+export const ROW_SCOPE = {
+    transcript: "t",
+    local: "l",
+    history: "h",
+};
+/** `%` and `|` are the escape and the delimiter, so both must be escaped inside a part. */
+function escapePart(part) {
+    return part.replace(/%/g, "%25").replace(/\|/g, "%7C");
+}
+/**
+ * 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 function scopedRowKeys(scope, rows) {
+    const prefix = scope.map(escapePart).join("|");
+    return rowKeys(rows).map((key) => `${prefix}|${escapePart(key)}`);
+}
+// ── segmentation ──
+/** Index of the LAST `boundary` row, or -1 when the transcript carries none. */
+export function lastBoundaryIndex(rows) {
+    const arr = Array.isArray(rows) ? rows : [];
+    let idx = -1;
+    for (let i = 0; i < arr.length; i++) {
+        if (arr[i]?.kind === "boundary")
+            idx = i;
+    }
+    return idx;
+}
+/**
+ * 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 function currentWakeRows(rows) {
+    const arr = Array.isArray(rows) ? rows : [];
+    const idx = lastBoundaryIndex(arr);
+    return idx >= 0 ? arr.slice(idx) : arr;
+}
+/**
+ * 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 function noiseShow(noiseFilterEnabled) {
+    return !noiseFilterEnabled;
+}
+/** Drop `noise` rows unless noise is being shown. */
+export function visibleRows(rows, showNoise) {
+    const arr = Array.isArray(rows) ? rows : [];
+    return showNoise ? arr : arr.filter((r) => !r?.noise);
+}
+export const TERM_LOADING_COPY = "Loading transcript…";
+/** ONE neutral string for "the read succeeded and there is no transcript" — it never speculates
+ *  about lifecycle ("not started yet", "already cleaned up", …). */
+export const TERM_MISSING_COPY = "No transcript is available for this session.";
+export const TERM_UNADDRESSABLE_COPY = "This transcript can't be attributed to this session.";
+export 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 const TERM_STALE_COPY = "Transcript disconnected — 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 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 const TERM_WAKE_UNAVAILABLE_COPY = "wake unavailable";
+/**
+ * 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 function transcriptView(source) {
+    switch (source.kind) {
+        case "ready":
+            return { kind: "log", stale: false };
+        case "stale":
+            return { kind: "log", stale: true };
+        case "loading":
+            return { kind: "state", copy: TERM_LOADING_COPY };
+        case "missing":
+            return { kind: "state", copy: TERM_MISSING_COPY };
+        case "unaddressable":
+            return { kind: "state", copy: TERM_UNADDRESSABLE_COPY };
+        case "failed":
+            return { kind: "state", copy: TERM_FAILED_COPY };
+    }
+}
+/** The source's rows when it carries any (`ready`/`stale`), else `[]`. */
+export function sourceRows(source) {
+    return source.kind === "ready" || source.kind === "stale" ? source.rows : [];
+}
+// ── title bar ──
+/** `{name} · tail · noise {on|off}`; a nameless transcript falls back to `transcript`. */
+export function termTitleText(name, noiseFilterEnabled) {
+    const trimmed = name?.trim();
+    return `${trimmed ? trimmed : "transcript"} · tail · noise ${noiseFilterEnabled ? "on" : "off"}`;
+}
+export const TURN_IN_FLIGHT_COPY = "turn in flight";
+export const TURN_IDLE_COPY = "idle · 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 function turnCaption(turnInFlight) {
+    if (turnInFlight === true)
+        return TURN_IN_FLIGHT_COPY;
+    if (turnInFlight === false)
+        return TURN_IDLE_COPY;
+    return 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 function historyToggleLabel(show, count) {
+    return show ? "↓ hide other sessions" : `↑ show other sessions in this transcript (${count})`;
+}
+/** Caption for one foreign transcript segment (gap: never blended into the selected log). */
+export function historySegmentCaption(id) {
+    return `session ${id ? id : "—"}`;
+}
+// ── keyboard ──
+/**
+ * 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 function shouldStopOnKey(e, selectionText, paneHasFocus) {
+    return !!e && e.key === "c" && e.ctrlKey === true && e.repeat !== true && selectionText.length === 0 && paneHasFocus;
+}
+/**
+ * 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 const TERM_STOP_LABEL = "◼ stop";
+export const TERM_STOP_KEY_HINT = "^C";
+/** Stop control class; `is-prominent` is a VISUAL weight only, never a state claim. */
+export function stopButtonClass(prominent) {
+    return prominent ? "my-term__stop is-prominent" : "my-term__stop";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mythicalos/ui-core",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "mythicalOS framework-agnostic UI core — the pure logic (class derivation, poll scheduling, dialog/toast/gauge helpers), the token-driven component stylesheet, and the <mythical-select> form-associated web component. Zero framework runtime; the Preact and React bindings derive identical output from this package. Apache-2.0.",
   "type": "module",
   "license": "Apache-2.0",

package/src/select/mythical-select.js

@@ -225,8 +225,9 @@ button:focus-visible{outline:2px solid var(--my-accent,#0F6B66);outline-offset:2
 .car{flex:none;color:var(--my-muted,#5A5F6A);transition:transform var(--my-t-fast,120ms ease)}
 :host([data-open]) .car{transform:rotate(180deg)}
 /* Pinned to BOTH edges with border-box sizing: under the old
-   `min-width:100%` + content-box, the 6px padding and 1px border were added
-   OUTSIDE the 100%, so the popup rendered 14px wider than its own control. */
+   min-width:100% + content-box, the 6px padding and 1px border were added
+   OUTSIDE the 100%, so the popup rendered 14px wider than its own control.
+   (No backticks in this comment — the whole sheet is a JS template literal.) */
 #pop{position:absolute;top:calc(100% + 6px);left:0;right:0;z-index:30;width:100%;
   box-sizing:border-box;max-height:280px;
   overflow:auto;overscroll-behavior:contain;padding:6px;background:var(--my-surface,#fff);