@demlik/tea 0.6.0 → 0.8.0

package/dist/chart/inspect/index.d.ts

@@ -0,0 +1,85 @@
+import { C as Cmd, S as Sub, M as Machine } from '../../core-Bjc0bS8j.js';
+export { A as AnyCell, a as AnyGuard, C as ChartDescription, b as ChartEdge, c as ChartEventInfo, d as ChartRefusal, e as ChartStateInfo, E as EdgeCore, f as EdgeKind, g as EventPreview, G as GuardPreview, h as GuardUnknown, I as InspectOptions, i as InspectParts, R as ReducerChartDescription, j as ReducerEdge, k as ReducerEventInfo, l as ReducerEventPreview, m as RefusalReason, n as ResolvedBy, U as Unanswerable, o as describeChart, p as describeReducerChart, q as edgeAt, r as explainRefusal, s as inspectReducerState, t as inspectState, u as inspectStateSummary, v as previewEvent, w as previewReducerEvent, x as reducerEdgeAt, y as refusalAtState, z as stateInfo } from '../../reducer-BqyoVyBG.js';
+export { R as RtSamples, S as SamplePayload, a as Samples, s as sampleMsg } from '../../samples-DCt6nF8H.js';
+import '../../graph-CcjWZVrd.js';
+
+/**
+ * The cmds ONE step emitted, tagged with the msg that caused them.
+ *
+ * `step` is `0` for `init` and `n` for the nth recorded msg, which is the same
+ * index the scrubber's cursor uses — so a UI showing step `n` asks for
+ * `capture.steps[n]` and gets the effects of the transition it is displaying.
+ */
+interface CapturedStep<M extends {
+    type: string;
+}, K extends Cmd> {
+    /** `0` = `init`; `1..n` = the nth recorded msg. */
+    readonly step: number;
+    /**
+     * The msg that caused these cmds. `null` at step `0` — `init` has no cause,
+     * and pinning its cmds on the first msg would be a lie about who fired them.
+     */
+    readonly by: M | null;
+    /** What ACTUALLY fired, in emission order. Cell-built cmds included. */
+    readonly cmds: readonly K[];
+}
+/**
+ * Every step of a recorded run, with the cmds each one actually emitted.
+ *
+ * `stoppedAt` is the honest degradation: a fold that throws (a chart compiled
+ * against parts that are not there, a cell that blew up on a state the current
+ * code no longer produces) truncates the capture at that step and says so,
+ * rather than reporting a short list as if it were complete.
+ */
+interface CmdCapture<M extends {
+    type: string;
+}, K extends Cmd> {
+    readonly steps: readonly CapturedStep<M, K>[];
+    /** Every captured cmd, flattened in fire order. */
+    readonly cmds: readonly K[];
+    /** Present iff the fold threw before the trace ran out. */
+    readonly stoppedAt?: {
+        readonly step: number;
+        readonly error: string;
+    };
+}
+/** The recorded input a capture folds — `Trace`'s two input halves. */
+interface CaptureInput<S, M extends {
+    type: string;
+}, Ctx> {
+    readonly msgs: readonly M[];
+    readonly ctx: Ctx;
+    /** The rehydrated state the run booted from, when it booted from one. */
+    readonly loaded?: S | null;
+}
+/**
+ * Fold `input` through `machine` and report the cmds EVERY step emitted.
+ *
+ * This is the after-the-fact counterpart to the declarative preview: where
+ * `EventPreview.cmds` says *what would fire if this event were dispatched now*,
+ * this says *what did fire, in order, and which msg caused it*. Both are useful
+ * and they are not the same question — a cell edge declares no cmds and emits
+ * plenty, and a guarded edge declares two arms and takes one.
+ */
+declare function captureCmds<S, M extends {
+    type: string;
+}, K extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, K, U, Ctx>, input: CaptureInput<S, M, Ctx>): CmdCapture<M, K>;
+/**
+ * The step at cursor `n`, or `undefined` when the capture does not reach it
+ * (an out-of-range cursor, or a fold that stopped early).
+ */
+declare function firedAt<M extends {
+    type: string;
+}, K extends Cmd>(capture: CmdCapture<M, K>, step: number): CapturedStep<M, K> | undefined;
+/**
+ * The captured cmds grouped by cmd NAME, in first-fire order — the roll-up a
+ * "which effects did this run actually perform" panel wants.
+ */
+declare function firedCounts<M extends {
+    type: string;
+}, K extends Cmd>(capture: CmdCapture<M, K>): readonly {
+    readonly type: string;
+    readonly count: number;
+}[];
+
+export { type CaptureInput, type CapturedStep, type CmdCapture, captureCmds, firedAt, firedCounts };

package/dist/chart/inspect/index.js

@@ -0,0 +1,5 @@
+export { captureCmds, describeChart, describeReducerChart, edgeAt, explainRefusal, firedAt, firedCounts, inspectReducerState, inspectState, inspectStateSummary, previewEvent, previewReducerEvent, reducerEdgeAt, refusalAtState, sampleMsg, stateInfo } from '../../chunk-ZD6PNZBK.js';
+import '../../chunk-5EHLEUTL.js';
+import '../../chunk-B5VXOFMZ.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/chart/inspect/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/chart/inspect/react.d.ts

@@ -0,0 +1,112 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { R as Runtime } from '../../runtime-types-Bxc637bp.js';
+import { C as Cmd, M as Machine, S as Sub } from '../../core-Bjc0bS8j.js';
+import { Recorder } from '../../recorder/index.js';
+import { Parts, RParts } from '../index.js';
+import { C as Chart, S as StateOf, M as MsgOf, a as CmdOf, I as InitialData, R as ReducerChart, b as RStateOf } from '../../graph-CcjWZVrd.js';
+import { a as Samples } from '../../samples-DCt6nF8H.js';
+import 'better-result';
+
+/**
+ * Everything `<ChartInspector>` needs. Four fields, and every one of them is a
+ * fact the chart genuinely does not carry — see the module doc. Anything the
+ * chart DOES carry (events, states, phases, guards, cmds, refusals) has no prop
+ * here by design: a prop that restated one would be the fact said twice.
+ */
+interface ChartInspectorProps<C, S extends {
+    type: string;
+}, M extends {
+    type: string;
+}, Ctx> {
+    /** The chart. Everything the UI draws is read off this value. */
+    readonly chart: C;
+    /** The parts bag `compile` demands — assign, plus guards/cmds/cells if used. */
+    readonly parts: Parts<C, S, M>;
+    /** The entry state's data. The chart names the state; you supply its ctx. */
+    readonly boot: () => InitialData<C, S>;
+    /** One payload per event that declares one. Typed by the chart. */
+    readonly samples?: Samples<C>;
+    /** The runtime ctx. Omit for a machine that reads nothing from one. */
+    readonly ctx?: Ctx;
+    /** Diagram title. Cosmetic — defaults to no title. */
+    readonly title?: string;
+    /** Diagram direction. Default `"TB"`. */
+    readonly direction?: "TB" | "LR";
+    /** Appended to the container's class list. */
+    readonly className?: string;
+}
+/**
+ * Everything `<ReducerChartInspector>` needs — the same four undecidable facts,
+ * over the form that has no phase dimension.
+ *
+ * There is no `direction` prop, and its absence is the honest kind: the reducer
+ * drawing has one `any` node with every edge leaving it (that is what having no
+ * phase dimension MEANS), so a layout knob would be a knob over nothing.
+ */
+interface ReducerChartInspectorProps<C, S extends {
+    type: string;
+}, M extends {
+    type: string;
+}, Ctx> {
+    /** The reducer chart. Everything the UI draws is read off this value. */
+    readonly chart: C;
+    /** The parts bag `compileReducer` demands. */
+    readonly parts: RParts<C, S, M>;
+    /** The entry state's data — for this form, the whole state minus its tag. */
+    readonly boot: () => Omit<RStateOf<C>, "type">;
+    /** One payload per event that declares one. Typed by the chart. */
+    readonly samples?: Samples<C>;
+    /** The runtime ctx. Omit for a machine that reads nothing from one. */
+    readonly ctx?: Ctx;
+    /** Panel title. Cosmetic — defaults to no title. */
+    readonly title?: string;
+    /** Appended to the container's class list. */
+    readonly className?: string;
+}
+/**
+ * Own a runtime for the component's lifetime (built with `run`, stopped on
+ * unmount or reset) so the recorder has something to attach to — `useMachine`
+ * hides the runtime, and the recorder needs it. The booted `Runtime` is
+ * consumed with `useRuntime`'s contract: the component that owns the lifecycle
+ * stops it.
+ *
+ * Shared by both chart forms because none of it is form-specific: a compiled
+ * `Transitions` and a compiled `Reducer` are both just a `Machine["update"]`.
+ *
+ * EXPORTED for the one other component with the same lifecycle to own:
+ * `@demlik/tea/chart/lane/react`'s live lane, whose `update` is `runLane`'s.
+ * A lane is not a chart form, but "own a runtime for the component's lifetime,
+ * record it, and stop it on unmount" is not a fact about charts either — and a
+ * second copy of it is a second place for the recorder's stop to be forgotten.
+ */
+declare function useInspectorRuntime<S, M extends {
+    type: string;
+}, K extends Cmd, Ctx>(machine: Machine<S, M, K, Sub<never>, Ctx>, ctx: Ctx, epoch: number): {
+    readonly rt: Runtime<S, M> | null;
+    readonly rec: Recorder<S, M>;
+};
+/**
+ * The self-building debugger for any GRID-form chart.
+ */
+declare function ChartInspector<const C extends Chart<C>, S extends {
+    type: string;
+} = StateOf<C>, M extends {
+    type: string;
+} = MsgOf<C>, K extends Cmd = CmdOf<C>, Ctx = Record<never, never>>(props: ChartInspectorProps<C, S, M, Ctx>): react_jsx_runtime.JSX.Element;
+/**
+ * The same debugger for a REDUCER-form chart — the panels that apply, and the
+ * ones that do not left out with the reason on screen.
+ *
+ * What is missing here is missing because the form does not have it: no phase
+ * on the header, no refusal on any control (this form cannot refuse an event),
+ * and no highlighted node in the drawing (every edge leaves the one `any`
+ * node). The "not available in this form" panel names each one, so the
+ * omission reads as a property of the chart rather than a hole in the tool.
+ */
+declare function ReducerChartInspector<const C extends ReducerChart<C>, S extends {
+    type: string;
+} = RStateOf<C>, M extends {
+    type: string;
+} = MsgOf<C>, K extends Cmd = CmdOf<C>, Ctx = Record<never, never>>(props: ReducerChartInspectorProps<C, S, M, Ctx>): react_jsx_runtime.JSX.Element;
+
+export { ChartInspector, type ChartInspectorProps, ReducerChartInspector, type ReducerChartInspectorProps, useInspectorRuntime };

package/dist/chart/inspect/react.js

@@ -0,0 +1,11 @@
+export { ChartInspector, ReducerChartInspector, useInspectorRuntime } from '../../chunk-JER5O7PQ.js';
+import '../../chunk-ZD6PNZBK.js';
+import '../../chunk-E6GEDSF4.js';
+import '../../chunk-UOC2PL46.js';
+import '../../chunk-MUUROGIH.js';
+import '../../chunk-WRAA7GVZ.js';
+import '../../chunk-EWJP3YYP.js';
+import '../../chunk-5EHLEUTL.js';
+import '../../chunk-B5VXOFMZ.js';
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map

package/dist/chart/inspect/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"react.js"}

package/dist/chart/inspect/styles.css

@@ -0,0 +1,286 @@
+/*
+ * @demlik/tea/chart/inspect — visual defaults for <ChartInspector>.
+ *
+ * Same strategy as `@demlik/tea/devtools/styles.css`, deliberately: every class
+ * is prefixed (here `.tea-ci-*`) so it cannot collide with host styles, and
+ * every colour is a consumer design token (shadcn slots + Radix accents) so the
+ * inspector inherits whatever theme is active. Override by re-declaring the
+ * --tea-ci-* vars on .tea-ci, or pass your own `className`.
+ *
+ * The state / log / diff panels are devtools components, so this sheet is a
+ * COMPANION to devtools' — import both.
+ *
+ * Refusal palette — the one thing this sheet says that devtools' does not.
+ * A refused event is drawn, not hidden, and WHY it is refused is a colour:
+ *   end          → --crimson-11  (this state is over)
+ *   out-of-scope → --muted-foreground (not addressed here — the quietest)
+ *   ignored      → --amber-11    (addressed here, and deliberately dropped)
+ *   undeclared   → --crimson-11  (the totality bypass; should never appear)
+ */
+
+.tea-ci {
+  --tea-ci-fg: var(--foreground);
+  --tea-ci-muted: var(--muted-foreground);
+  --tea-ci-border: var(--border);
+  --tea-ci-accent: var(--teal-11);
+  --tea-ci-warn: var(--amber-11);
+  --tea-ci-bad: var(--crimson-11);
+
+  font-family: var(
+    --font-mono,
+    "JetBrains Mono",
+    ui-monospace,
+    "SF Mono",
+    Menlo,
+    Consolas,
+    monospace
+  );
+  font-size: 12px;
+  color: var(--tea-ci-fg);
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.tea-ci-boot {
+  color: var(--tea-ci-muted);
+  font-style: italic;
+  padding: 16px;
+}
+
+.tea-ci-head {
+  display: flex;
+  align-items: baseline;
+  gap: 12px;
+  flex-wrap: wrap;
+  border-bottom: 1px solid var(--tea-ci-border);
+  padding-bottom: 8px;
+}
+.tea-ci-title {
+  font-weight: 600;
+}
+.tea-ci-now {
+  display: inline-flex;
+  gap: 6px;
+  align-items: baseline;
+}
+.tea-ci-phase {
+  color: var(--tea-ci-muted);
+}
+.tea-ci-phase::after {
+  content: " /";
+}
+.tea-ci-state {
+  color: var(--tea-ci-accent);
+  font-weight: 600;
+}
+.tea-ci-tag {
+  border: 1px solid var(--tea-ci-border);
+  border-radius: var(--radius, 0.25rem);
+  padding: 0 4px;
+  color: var(--tea-ci-muted);
+  font-size: 10.5px;
+}
+.tea-ci-warn {
+  color: var(--tea-ci-warn);
+}
+
+.tea-ci-panel {
+  border: 1px solid var(--tea-ci-border);
+  border-radius: var(--radius, 0.25rem);
+  padding: 12px 14px;
+  background: transparent;
+  min-width: 0;
+}
+.tea-ci-h {
+  margin: 0 0 6px;
+  font-size: 10.5px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--tea-ci-muted);
+}
+
+.tea-ci-cols {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 12px;
+}
+
+/* ── the button row ─────────────────────────────────────────────────────── */
+.tea-ci-events {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+  gap: 8px;
+}
+.tea-ci-ev {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  min-width: 0;
+}
+/* THE THING YOU CAN CLICK LOOKS LIKE THE THING YOU CAN CLICK.
+ *
+ * This read backwards: a pressable event was plain text on a transparent
+ * ground while every REFUSED one wore a dashed or dotted box, so on a state
+ * accepting two of six events the only two you could click were the only two
+ * that looked like labels. The chrome belongs to the affordance — a button
+ * raised while it can be pressed, and flat when it cannot. The refusal keeps
+ * its colour and its reason, which is what says WHY; it just stops being the
+ * loudest thing in the row. */
+.tea-ci-btn {
+  font: inherit;
+  text-align: left;
+  padding: 4px 8px;
+  border: 1px solid var(--tea-ci-border);
+  border-radius: var(--radius, 0.25rem);
+  background: var(--tea-ci-raised, rgba(127, 127, 127, 0.14));
+  color: var(--tea-ci-fg);
+  cursor: pointer;
+}
+.tea-ci-btn:hover:not(:disabled) {
+  border-color: var(--tea-ci-accent);
+  color: var(--tea-ci-accent);
+}
+.tea-ci-btn:disabled {
+  cursor: not-allowed;
+  border-color: transparent;
+  background: transparent;
+  padding-left: 0;
+}
+.tea-ci-to {
+  color: var(--tea-ci-muted);
+}
+.tea-ci-why {
+  color: var(--tea-ci-muted);
+  font-style: italic;
+}
+/* The sample is a PAYLOAD and payloads wrap. On one line with no wrap and no
+ * scroll cue, `{"at":3,"reason":"review` was the whole of what a reader could
+ * see of it — the rest was not hidden, it was invisible. */
+.tea-ci-sample {
+  font: inherit;
+  resize: vertical;
+  border: 1px dashed var(--tea-ci-border);
+  border-radius: var(--radius, 0.25rem);
+  background: transparent;
+  color: var(--tea-ci-fg);
+  padding: 2px 6px;
+  min-width: 0;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  overflow-x: auto;
+  max-height: 8lh;
+}
+
+/* A refused control keeps its NAME and loses its chrome — the reason beneath it
+ * is the content, the colour is only the cue. */
+.tea-ci-ev-end .tea-ci-btn,
+.tea-ci-ev-undeclared .tea-ci-btn,
+.tea-ci-ev-no-edge .tea-ci-btn {
+  color: var(--tea-ci-bad);
+  text-decoration: line-through;
+}
+.tea-ci-ev-ignored .tea-ci-btn {
+  color: var(--tea-ci-warn);
+  text-decoration: line-through;
+}
+.tea-ci-ev-out-of-scope .tea-ci-btn {
+  color: var(--tea-ci-muted);
+}
+.tea-ci-ev-end .tea-ci-why,
+.tea-ci-ev-undeclared .tea-ci-why,
+.tea-ci-ev-no-edge .tea-ci-why {
+  color: var(--tea-ci-bad);
+}
+.tea-ci-ev-ignored .tea-ci-why {
+  color: var(--tea-ci-warn);
+}
+
+/* ── the diagram ────────────────────────────────────────────────────────── */
+.tea-ci-mermaid {
+  margin: 0;
+  overflow-x: auto;
+  white-space: pre;
+  color: var(--tea-ci-muted);
+  line-height: 1.5;
+}
+
+/* ── cmds fired ─────────────────────────────────────────────────────────────
+ * The AFTER panel. The button row above says what an edge DECLARES it would
+ * fire; this says what the run did fire, so a step that emitted nothing reads
+ * as a dash rather than as a missing row. The step on the scrubber is the one
+ * highlighted, because the two are indexed by the same cursor. */
+.tea-ci-firelog {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  max-height: 220px;
+  overflow-y: auto;
+}
+.tea-ci-fire {
+  display: flex;
+  gap: 10px;
+  align-items: baseline;
+  padding: 1px 4px;
+  border-left: 2px solid transparent;
+}
+.tea-ci-fire-now {
+  border-left-color: var(--tea-ci-accent);
+}
+.tea-ci-fire-by {
+  color: var(--tea-ci-muted);
+  min-width: 9em;
+}
+.tea-ci-fire[data-fired="0"] .tea-ci-fire-cmds {
+  color: var(--tea-ci-muted);
+}
+.tea-ci-fire-cmds {
+  color: var(--tea-ci-accent);
+}
+
+/* ── what this chart form cannot answer ─────────────────────────────────────
+ * Named, never silently absent: an empty refusal list would read as "nothing is
+ * refused", which is the one wrong answer worth going out of the way to avoid. */
+.tea-ci-omits ul {
+  margin: 0;
+  padding-left: 1.1em;
+  color: var(--tea-ci-muted);
+}
+.tea-ci-omits b {
+  color: var(--tea-ci-fg);
+}
+
+/* ── time travel ────────────────────────────────────────────────────────── */
+.tea-ci-scrub {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-bottom: 10px;
+  flex-wrap: wrap;
+}
+.tea-ci-scrub input[type="range"] {
+  flex: 1 1 160px;
+  min-width: 120px;
+  accent-color: var(--tea-ci-accent);
+}
+.tea-ci-step {
+  color: var(--tea-ci-muted);
+  white-space: nowrap;
+}
+.tea-ci-scrub button {
+  font: inherit;
+  padding: 2px 10px;
+  border: 1px solid var(--tea-ci-border);
+  border-radius: var(--radius, 0.25rem);
+  background: transparent;
+  color: var(--tea-ci-fg);
+  cursor: pointer;
+}
+.tea-ci-scrub button:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}