@mantaq/viz 0.0.0 → 0.2.0

package/dist/standalone.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/standalone.mjs

@@ -0,0 +1,6 @@
+import { mountEmbedded } from "./page.mjs";
+// src/viewer/standalone.ts
+/** Entry of the self-contained HTML page `mantaq-inspect` writes. */
+const root = document.querySelector("#app");
+if (root) mountEmbedded(root);
+export {};

package/dist/style.css

@@ -0,0 +1,404 @@
+.viz {
+  --fuzz: #138a4a;
+  --bg: #fbfbfa;
+  --fg: #1d1d1f;
+  --muted: #6b6b70;
+  --line: #4a4a52;
+  --state-bg: #fff;
+  --state-border: #3b3b44;
+  --region-bg: #f1f1ef;
+  --accent: #2463eb;
+  --unknown: #a35c00;
+  --banner-bg: #fff6e0;
+  --banner-fg: #5a3e00;
+  color-scheme: light;
+  background: var(--bg);
+  color: var(--fg);
+}
+
+@media (prefers-color-scheme: dark) {
+  .viz {
+    --bg: #141416;
+    --fg: #ececf0;
+    --muted: #9a9aa3;
+    --line: #b4b4bf;
+    --state-bg: #1f1f23;
+    --state-border: #c9c9d2;
+    --region-bg: #1a1a1e;
+    --accent: #7aa7ff;
+    --unknown: #f0a742;
+    --fuzz: #4cc98a;
+    --banner-bg: #2e2510;
+    --banner-fg: #f3d58c;
+    color-scheme: dark;
+  }
+}
+
+.viz .viz-header {
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 16px;
+  display: flex;
+}
+
+.viz .viz-header :is(h1, h2, h3) {
+  margin: 0;
+  font-size: 18px;
+}
+
+.viz .banner {
+  background: var(--banner-bg);
+  color: var(--banner-fg);
+  border-radius: 6px;
+  padding: 8px 12px;
+}
+
+.viz .legend {
+  color: var(--muted);
+  flex-wrap: wrap;
+  gap: 4px 18px;
+  padding: 0;
+  font-size: 12px;
+  list-style: none;
+  display: flex;
+}
+
+.viz .viz-main {
+  grid-template-columns: minmax(0, 1fr) 320px;
+  gap: 16px;
+  display: grid;
+}
+
+@media (width <= 760px) {
+  .viz .viz-main {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+
+.viz .canvas {
+  overflow: auto;
+}
+
+.viz .panel {
+  border-left: 1px solid var(--region-bg);
+  padding-left: 16px;
+}
+
+.viz .panel dl {
+  grid-template-columns: auto 1fr;
+  gap: 4px 12px;
+  display: grid;
+}
+
+.viz .panel dt {
+  color: var(--muted);
+}
+
+.viz .panel dd {
+  margin: 0;
+}
+
+.viz .panel ul {
+  margin: 0;
+  padding-left: 16px;
+}
+
+.viz .link {
+  color: var(--accent);
+  cursor: pointer;
+}
+
+.viz .graph {
+  width: 100%;
+  height: auto;
+}
+
+.viz .graph text {
+  fill: var(--fg);
+  paint-order: stroke;
+  stroke: var(--bg);
+  stroke-width: 4px;
+  stroke-linejoin: round;
+  font-size: 12px;
+}
+
+.viz .graph .arrow-head {
+  fill: var(--line);
+}
+
+.viz .region rect {
+  fill: var(--region-bg);
+  stroke: var(--muted);
+  stroke-dasharray: 2 3;
+}
+
+.viz .region text {
+  fill: var(--muted);
+}
+
+.viz .state .frame {
+  fill: var(--state-bg);
+  stroke: var(--state-border);
+  stroke-width: 1.5px;
+}
+
+.viz .state.final .inner {
+  fill: none;
+}
+
+.viz .state, .viz .edge {
+  cursor: pointer;
+  outline: none;
+}
+
+.viz .edge path {
+  fill: none;
+  stroke: var(--line);
+  stroke-width: 1.5px;
+}
+
+.viz .edge.internal path {
+  stroke-dasharray: 1 3;
+  stroke-linecap: round;
+}
+
+.viz .edge.internal text {
+  font-style: italic;
+}
+
+.viz .edge.effect {
+  opacity: .45;
+}
+
+.viz .edge.undetermined path {
+  stroke: var(--unknown);
+  stroke-dasharray: 6 4;
+}
+
+.viz .edge.fuzz path {
+  stroke: var(--fuzz);
+}
+
+.viz .edge.fuzz text {
+  fill: var(--fuzz);
+}
+
+.viz .edge.stay path {
+  stroke-dasharray: 1 3;
+  stroke-linecap: round;
+}
+
+.viz .steps {
+  margin: 0;
+  padding-left: 20px;
+  font-family: ui-monospace, monospace;
+  font-size: 12px;
+}
+
+.viz .unknown-node circle {
+  fill: var(--state-bg);
+  stroke: var(--unknown);
+  stroke-dasharray: 4 3;
+}
+
+.viz .unknown-node text {
+  fill: var(--unknown);
+  font-weight: 700;
+}
+
+.viz .any-node rect {
+  fill: none;
+  stroke: var(--state-border);
+  stroke-width: 1.5px;
+  stroke-dasharray: 2 3;
+}
+
+.viz .any-node text {
+  fill: var(--muted);
+  font-style: italic;
+}
+
+.viz .entry circle {
+  fill: var(--line);
+}
+
+.viz .entry path {
+  stroke: var(--line);
+  stroke-width: 1.5px;
+}
+
+.viz.coverage-on .unreached {
+  opacity: .35;
+}
+
+.viz.coverage-on .state.unreached .frame, .viz.coverage-on .edge.unreached path {
+  stroke-dasharray: 3 3;
+}
+
+.viz .highlight path, .viz .highlight .frame, .viz .highlight circle, .viz .selected path, .viz .selected .frame {
+  stroke: var(--accent);
+  stroke-width: 2.5px;
+}
+
+.viz .state:focus-visible .frame, .viz .edge:focus-visible path {
+  stroke: var(--accent);
+  stroke-width: 3px;
+}
+
+.viz .load-error {
+  color: var(--unknown);
+}
+
+.viz .muted {
+  color: var(--muted);
+}
+
+.viz .explanation p {
+  margin: 2px 0;
+}
+
+.viz .explanation pre {
+  background: var(--region-bg);
+  border-radius: 4px;
+  padding: 6px;
+  font-size: 12px;
+  overflow-x: auto;
+}
+
+.viz .branches {
+  padding-left: 16px;
+}
+
+.viz .branch[data-branch-status="not in graph"] .branch-status {
+  color: var(--unknown);
+  font-weight: 600;
+}
+
+.viz .branch[data-branch-status="this edge"] .branch-status {
+  color: var(--accent);
+}
+
+.viz .prediction-note, .viz .routing-note {
+  background: var(--banner-bg);
+  color: var(--banner-fg);
+  border-radius: 4px;
+  padding: 6px 8px;
+}
+
+.viz .taken path, .viz .current .frame {
+  stroke: var(--accent);
+  stroke-width: 2.5px;
+}
+
+.viz .current .frame {
+  stroke-width: 3.5px;
+}
+
+.viz .next path {
+  stroke: var(--accent);
+  stroke-width: 3px;
+  stroke-dasharray: 8 5;
+  animation: .8s linear infinite viz-march;
+}
+
+.viz .next text {
+  fill: var(--accent);
+  font-weight: 700;
+}
+
+.viz .edge.effect.running {
+  opacity: 1;
+}
+
+.viz .running path {
+  stroke: var(--accent);
+  stroke-width: 2.5px;
+}
+
+.viz .running text {
+  fill: var(--accent);
+  font-weight: 700;
+}
+
+@keyframes viz-march {
+  to {
+    stroke-dashoffset: -13px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .viz .next path {
+    animation: none;
+  }
+}
+
+.viz .explore {
+  background: var(--region-bg);
+  border-radius: 6px;
+  margin-bottom: 12px;
+  padding: 6px 10px;
+}
+
+.viz .explore h3 {
+  color: var(--muted);
+  margin: 10px 0 4px;
+  font-size: 13px;
+}
+
+.viz .explore ul, .viz .explore ol {
+  margin: 0;
+  padding-left: 18px;
+}
+
+.viz .explore li {
+  margin: 3px 0;
+}
+
+.viz .explore li > button + button {
+  margin-left: 6px;
+}
+
+.viz .explore button {
+  cursor: pointer;
+}
+
+.viz .explore-path li[aria-current="step"] button {
+  font-weight: 700;
+}
+
+.viz .explore-controls {
+  gap: 6px;
+  margin: 8px 0;
+  display: flex;
+}
+
+.viz .explore .unhandled code {
+  color: var(--unknown);
+  text-decoration: line-through;
+}
+
+.viz .explore-done {
+  border-left: 3px solid var(--accent);
+  padding: 4px 8px;
+}
+
+.viz .explore-warning {
+  background: var(--banner-bg);
+  color: var(--banner-fg);
+  border-radius: 4px;
+  padding: 4px 8px;
+}
+
+.viz .reachable .frame {
+  stroke: var(--accent);
+  stroke-dasharray: 4 3;
+}
+body {
+  margin: 0;
+  padding: 16px;
+  font: 14px / 1.4 system-ui, sans-serif;
+}
+
+.toolbar {
+  margin-bottom: 12px;
+}

package/dist/validate-C_EXBtem.d.mts

@@ -0,0 +1,230 @@
+import { Either } from "@mantaq/utils";
+/**
+ * Viz document schema. Bump `VIZ_SCHEMA_VERSION` on any breaking change.
+ * Everything not observable at runtime is `null`, never guessed.
+ */
+declare const VIZ_SCHEMA_VERSION = 8;
+/**
+ * Edge source of an `onAny` registration: any non-final state of the machine,
+ * or `region.*` inside a region. Never listed in `states`.
+ */
+declare const ANY_STATE = "*";
+/** Region prefix of a state id (`""` at the root). */
+declare function scopeOf(id: string): string;
+declare function isAnyState(id: string): boolean;
+/** True when `stateId` is one of the states an `anyId` source stands for. */
+declare function coveredByAny(anyId: string, stateId: string): boolean;
+interface VizCoverage {
+  hits: number;
+}
+/** An effect a state runs on entry. Effects never transition; the events they send do. */
+interface VizEffect {
+  name: string;
+  /** Event ids from the effect's `sends` declaration. null = not declared. */
+  sends: string[] | null;
+}
+interface VizState {
+  /** Path-prefixed id, e.g. `payment` or `region1.childA`. */
+  id: string;
+  label: string;
+  /** Region path this state belongs to, or null for the root machine. */
+  region: string | null;
+  initial: boolean;
+  final: boolean;
+  /** Effects this state runs on entry, in registration order. */
+  effects: VizEffect[];
+  /** Visits in the supplied run (history or fuzz corpus replay). null = no run. */
+  coverage: VizCoverage | null;
+  /** Visits by the supplied test sequences. null = no tests supplied. */
+  tested: VizCoverage | null;
+  /** Leading JSDoc of the `state(...)` declaration. null = undocumented or AST not run. */
+  doc: string | null;
+}
+interface VizEvent {
+  id: string;
+  internal: boolean;
+  /** Leading JSDoc of the `event(...)` declaration. null = undocumented or AST not run. */
+  doc: string | null;
+  /** Payload types are erased at runtime; always null. */
+  payloadType: null;
+}
+/**
+ * `stay`: the event was handled but the state did not change. Declared by a
+ * registration without `to`, or observed while fuzzing.
+ */
+type VizEdgeKind = "initial" | "transition" | "effect" | "stay";
+/**
+ * `declared`: from the builder's `to` list, so the type checker vouches for it.
+ * `probe`: an actor without declarations, found by synthetic traversal.
+ * `fuzz`: observed only while fuzzing.
+ */
+type VizEdgeOrigin = "declared" | "probe" | "fuzz";
+interface VizLocation {
+  /** POSIX path relative to the analysis root. */
+  file: string;
+  /** 1-based. */
+  line: number;
+  /** 1-based. */
+  column: number;
+}
+/** Where a handler return path goes. `stay` = no `state` in the result. */
+type VizBranchTarget = {
+  kind: "state";
+  state: string;
+} | {
+  kind: "stay";
+} | {
+  kind: "unresolved";
+  text: string;
+};
+interface VizBranch {
+  /** Source text of each condition on the path, outermost first; `!(...)` = else side. */
+  conditions: string[];
+  target: VizBranchTarget;
+}
+/** `payload.amount > 50000` style comparison against a literal, for search guidance. */
+interface VizComparison {
+  source: "payload" | "context";
+  /** Dotted path below payload / context, e.g. `result.reservationId`. */
+  path: string;
+  operator: "<" | "<=" | ">" | ">=" | "===" | "!==" | "==" | "!=";
+  literal: number | string | boolean;
+}
+/**
+ * Static reading of the handler behind an edge (TypeScript compiler API).
+ * Annotates runtime edges; never creates them.
+ */
+type VizExplanation = {
+  status: "analyzed";
+  location: VizLocation;
+  registration: "on" | "onAny";
+  branches: VizBranch[];
+  payloadReads: string[];
+  contextReads: string[];
+  contextWrites: string[];
+  /** Reads `<actor>.state`: target depends on live state, which probing cannot see. */
+  readsActorState: boolean;
+  comparisons: VizComparison[];
+  literals: Array<number | string>;
+} | {
+  status: "not_analyzed";
+  location: VizLocation | null;
+  reason: string;
+  /** First lines of the source, when there is any. */
+  snippet: string | null;
+};
+interface VizEdge {
+  id: string;
+  from: string;
+  /** Event id; empty string for the initial edge. */
+  event: string;
+  /** null = handler target depends on payload or context (undetermined). */
+  to: string | null;
+  kind: VizEdgeKind;
+  origin: VizEdgeOrigin;
+  emits: string[];
+  /** Sample-context names under which this edge was observed. */
+  contexts: string[];
+  /** null = no handler behind this edge (initial, effect) or analysis not run. */
+  explanation: VizExplanation | null;
+  /** Leading JSDoc of the `m.on` / `m.onAny` call. null = undocumented, no handler, or AST not run. */
+  doc: string | null;
+  /** Times taken in the supplied run (history or fuzz corpus replay). null = no run. */
+  coverage: VizCoverage | null;
+  /** Times taken by the supplied test sequences. null = no tests supplied. */
+  tested: VizCoverage | null;
+}
+interface VizMachine {
+  id: string;
+  initial: string | null;
+  /** Region paths, sorted. Empty for flat machines. */
+  regions: string[];
+  states: VizState[];
+  events: VizEvent[];
+  edges: VizEdge[];
+  /** null = not fuzzed. */
+  fuzz: VizFuzz | null;
+}
+type VizJson = null | boolean | number | string | VizJson[] | {
+  [key: string]: VizJson;
+};
+/** One input to a machine: an event (`send` for inputs, `inject` for internal) or a clock advance. */
+type VizStep = {
+  kind: "event";
+  event: string;
+  payload: VizJson;
+} | {
+  kind: "advance";
+  ms: number;
+};
+/** What one step did: the actor moved, handled it without moving, or had no handler. */
+type VizLiveOutcome = "transition" | "stay" | "ignored";
+interface VizLiveStep {
+  from: string;
+  event: string;
+  to: string;
+  outcome: VizLiveOutcome;
+  /** Names of the effects the step ran. */
+  effects: string[];
+  context: VizJson;
+  /** Message of a handler that threw; null when none did. */
+  error: string | null;
+}
+interface VizLiveTimer {
+  id: string;
+  ms: number;
+  deadline: number;
+  eventName: string | null;
+}
+/** Where a running actor is, after the steps in `steps`. */
+interface VizLiveState {
+  state: string;
+  steps: VizStep[];
+  last: VizLiveStep | null;
+  timers: VizLiveTimer[];
+  context: VizJson;
+}
+/**
+ * A running actor behind the viewer. JSON in, JSON out, so viz needs no core:
+ * `@mantaq/inspect` implements it on the step function the fuzzer uses.
+ */
+interface VizDriver {
+  reset(): VizLiveState;
+  step(step: VizStep): VizLiveState;
+}
+interface VizFuzzSequence {
+  /** Shrunk replayable sequence, starting from a fresh actor. */
+  steps: VizStep[];
+  /** Coverage features this sequence was kept for, e.g. `edge:a>go>b`. */
+  discovered: string[];
+}
+/** A handler that threw: the actor entered its error state. */
+interface VizFuzzError {
+  from: string;
+  event: string;
+  message: string;
+  steps: VizStep[];
+}
+interface VizFuzz {
+  seed: number;
+  iterations: number;
+  corpus: VizFuzzSequence[];
+  errors: VizFuzzError[];
+}
+interface VizDocument {
+  schemaVersion: typeof VIZ_SCHEMA_VERSION;
+  machines: VizMachine[];
+}
+/** One problem found while reading a document, with a JSON-path-like location. */
+interface VizIssue {
+  path: string;
+  message: string;
+}
+/**
+ * Read an untrusted value (parsed JSON) as an viz document. Returns every
+ * issue found, not just the first, so a broken file can be fixed in one pass.
+ */
+declare function validateViz(value: unknown): Either<VizIssue[], VizDocument>;
+/** Parse JSON text and validate it. JSON syntax errors become an issue at `$`. */
+declare function parseViz(text: string): Either<VizIssue[], VizDocument>;
+export { coveredByAny as A, VizLiveState as C, VizMachine as D, VizLocation as E, scopeOf as M, VizState as O, VizLiveOutcome as S, VizLiveTimer as T, VizExplanation as _, VIZ_SCHEMA_VERSION as a, VizFuzzSequence as b, VizComparison as c, VizDriver as d, VizEdge as f, VizEvent as g, VizEffect as h, ANY_STATE as i, isAnyState as j, VizStep as k, VizCoverage as l, VizEdgeOrigin as m, validateViz as n, VizBranch as o, VizEdgeKind as p, VizIssue as r, VizBranchTarget as s, parseViz as t, VizDocument as u, VizFuzz as v, VizLiveStep as w, VizJson as x, VizFuzzError as y };

package/dist/viewer.d.mts

@@ -0,0 +1,2 @@
+import { a as ViewerOptions, i as STRUCTURE_BANNER, n as showIssues, o as mountViewer, r as FUZZ_NOTE, t as mountVizText } from "./embed-CISoaFIK.mjs";
+export { FUZZ_NOTE, STRUCTURE_BANNER, type ViewerOptions, mountViewer, mountVizText, showIssues };

package/dist/viewer.mjs

@@ -0,0 +1 @@
+export { r as FUZZ_NOTE, i as STRUCTURE_BANNER, a as mountViewer, t as mountVizText, n as showIssues } from "./embed-QX7vRXoL.mjs";

package/package.json

@@ -1,7 +1,46 @@
 {
   "name": "@mantaq/viz",
-  "version": "0.0.0",
-  "description": "Placeholder to enable npm trusted publishing.",
-  "repository": { "type": "git", "url": "git+https://github.com/AndersCan/mantaq.git" },
-  "license": "MIT"
-}
+  "version": "0.2.0",
+  "description": "Draw and walk a Mantaq machine in the browser, from a versioned, deterministic JSON document.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AndersCan/mantaq",
+    "directory": "packages/viz"
+  },
+  "files": [
+    "dist",
+    "src/viewer/viewer.css",
+    "src/viewer/page.css"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./viewer": "./dist/viewer.mjs",
+    "./viewer.css": "./src/viewer/viewer.css",
+    "./page.css": "./src/viewer/page.css",
+    "./page": "./dist/page.mjs",
+    "./standalone": "./dist/standalone.mjs",
+    "./live": "./dist/live.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dagrejs/dagre": "^3.1.2",
+    "@mantaq/utils": "0.0.4"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "happy-dom": "^21.0.4",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0",
+    "vite-plus": "1.4.0"
+  },
+  "scripts": {
+    "dev": "vp dev",
+    "build": "vp pack",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}

package/src/viewer/page.css

@@ -0,0 +1,12 @@
+/* Standalone viewer page chrome (index.html). Embeds bring their own. */
+body {
+  margin: 0;
+  padding: 16px;
+  font:
+    14px/1.4 system-ui,
+    sans-serif;
+}
+
+.toolbar {
+  margin-bottom: 12px;
+}