@typeonce/effect-machine-devtools 0.25.0 → 0.26.0

package/src/internal/browser/chart-renderer.ts

@@ -168,7 +168,7 @@ const stateContent = (layout: LaidOutChartNode, stateStatus: HTMLElement): Docum
     const activities = element("div", "chart-state-section")
     activities.append(element("div", "chart-section-label", "invokes"))
     layout.node.activities.slice(0, maxVisibleActivities).forEach((activity) => {
-      const row = element("div", "chart-activity-row")
+      const row = element("div", `chart-activity-row chart-activity-${activity.kind}`)
       row.append(
         element("span", "chart-activity-kind", activity.kind),
         element("span", "chart-activity-name", activity.label)
@@ -184,10 +184,83 @@ const stateContent = (layout: LaidOutChartNode, stateStatus: HTMLElement): Docum
   return fragment
 }
 
-const pathData = (points: ReadonlyArray<ChartPoint>): string => {
+const pointAlong = (start: ChartPoint, end: ChartPoint, distance: number): ChartPoint => {
+  const length = Math.abs(end.x - start.x) + Math.abs(end.y - start.y)
+  if (length === 0) return start
+  const ratio = distance / length
+  return {
+    x: start.x + (end.x - start.x) * ratio,
+    y: start.y + (end.y - start.y) * ratio
+  }
+}
+
+export const chartEdgePathData = (points: ReadonlyArray<ChartPoint>, radius = 9): string => {
   const first = points[0]
   if (first === undefined) return ""
-  return points.slice(1).reduce((path, point) => `${path} L ${point.x} ${point.y}`, `M ${first.x} ${first.y}`)
+  if (points.length === 1) return `M ${first.x} ${first.y}`
+  let path = `M ${first.x} ${first.y}`
+  for (let index = 1; index < points.length - 1; index++) {
+    const previous = points[index - 1]!
+    const corner = points[index]!
+    const next = points[index + 1]!
+    const incoming = Math.abs(corner.x - previous.x) + Math.abs(corner.y - previous.y)
+    const outgoing = Math.abs(next.x - corner.x) + Math.abs(next.y - corner.y)
+    const cornerRadius = Math.min(radius, incoming / 2, outgoing / 2)
+    const before = pointAlong(corner, previous, cornerRadius)
+    const after = pointAlong(corner, next, cornerRadius)
+    path += ` L ${before.x} ${before.y} Q ${corner.x} ${corner.y} ${after.x} ${after.y}`
+  }
+  const last = points.at(-1)!
+  return `${path} L ${last.x} ${last.y}`
+}
+
+export interface ChartDirectionCue {
+  readonly start: ChartPoint
+  readonly end: ChartPoint
+}
+
+export const chartDirectionCue = (
+  points: ReadonlyArray<ChartPoint>,
+  minimumRouteLength = 280
+): ChartDirectionCue | null => {
+  const segments = points.slice(1).map((end, index) => {
+    const start = points[index]!
+    return {
+      start,
+      end,
+      length: Math.abs(end.x - start.x) + Math.abs(end.y - start.y)
+    }
+  })
+  const total = segments.reduce((sum, segment) => sum + segment.length, 0)
+  if (total < minimumRouteLength) return null
+  let remaining = total * 0.32
+  let selected: { readonly start: ChartPoint; readonly end: ChartPoint; readonly distance: number } | undefined
+  for (const segment of segments) {
+    if (segment.length >= 24 && remaining <= segment.length) {
+      selected = {
+        start: segment.start,
+        end: segment.end,
+        distance: Math.min(segment.length - 12, Math.max(12, remaining))
+      }
+      break
+    }
+    remaining -= segment.length
+  }
+  if (selected === undefined) {
+    const segment = [...segments].sort((left, right) => right.length - left.length)[0]
+    if (segment === undefined || segment.length < 24) return null
+    selected = { start: segment.start, end: segment.end, distance: segment.length / 2 }
+  }
+  const center = pointAlong(selected.start, selected.end, selected.distance)
+  const deltaX = selected.end.x - selected.start.x
+  const deltaY = selected.end.y - selected.start.y
+  const horizontal = Math.abs(deltaX) >= Math.abs(deltaY)
+  const directionX = horizontal ? Math.sign(deltaX) : 0
+  const directionY = horizontal ? 0 : Math.sign(deltaY)
+  return {
+    start: { x: center.x - directionX * 5, y: center.y - directionY * 5 },
+    end: { x: center.x + directionX * 5, y: center.y + directionY * 5 }
+  }
 }
 
 const setStateClass = (
@@ -219,16 +292,29 @@ const render = (
   const definitions = svgElement("defs")
   const marker = svgElement("marker")
   marker.id = "chart-arrow"
-  marker.setAttribute("viewBox", "0 0 10 10")
-  marker.setAttribute("refX", "9")
-  marker.setAttribute("refY", "5")
-  marker.setAttribute("markerWidth", "7")
-  marker.setAttribute("markerHeight", "7")
+  marker.setAttribute("viewBox", "0 0 12 12")
+  marker.setAttribute("refX", "11")
+  marker.setAttribute("refY", "6")
+  marker.setAttribute("markerWidth", "12")
+  marker.setAttribute("markerHeight", "12")
+  marker.setAttribute("markerUnits", "userSpaceOnUse")
   marker.setAttribute("orient", "auto-start-reverse")
   const arrow = svgElement("path")
-  arrow.setAttribute("d", "M 0 0 L 10 5 L 0 10 z")
+  arrow.setAttribute("d", "M 1 1 L 11 6 L 1 11 z")
   marker.append(arrow)
-  definitions.append(marker)
+  const directionMarker = svgElement("marker")
+  directionMarker.id = "chart-direction"
+  directionMarker.setAttribute("viewBox", "0 0 8 8")
+  directionMarker.setAttribute("refX", "7")
+  directionMarker.setAttribute("refY", "4")
+  directionMarker.setAttribute("markerWidth", "8")
+  directionMarker.setAttribute("markerHeight", "8")
+  directionMarker.setAttribute("markerUnits", "userSpaceOnUse")
+  directionMarker.setAttribute("orient", "auto")
+  const directionArrow = svgElement("path")
+  directionArrow.setAttribute("d", "M 1 1 L 7 4 L 1 7 z")
+  directionMarker.append(directionArrow)
+  definitions.append(marker, directionMarker)
   svg.append(definitions)
   const nodesLayer = element("div", "chart-nodes")
   const labelsLayer = element("div", "chart-labels")
@@ -274,6 +360,15 @@ const render = (
     edgeElements.set(id, registered)
   }
 
+  for (const regionLayout of layout.regions) {
+    const region = element("div", "chart-unconnected-region")
+    region.title = "No statically known transition reaches these states. Runtime-resolved targets may still reach them."
+    position(region, regionLayout)
+    const label = element("div", "chart-unconnected-region-label", "No static path from initial")
+    region.append(label)
+    regions.append(region)
+  }
+
   for (const laidOut of layout.nodes) {
     if (laidOut.node.children.length > 0) {
       const region = element("div", `chart-compound chart-compound-${laidOut.node.type}`)
@@ -337,16 +432,32 @@ const render = (
     const group = svgElement(
       "g",
       `chart-edge-group chart-edge-${laidOut.kind}${
-        laidOut.kind === "transition" ? ` chart-transition-${laidOut.edge.kind}` : ""
+        laidOut.kind === "transition"
+          ? ` chart-transition-${laidOut.edge.kind} chart-edge-trigger-${laidOut.edge.trigger.type}${
+            laidOut.edge.activityKind === null ? "" : ` chart-edge-activity-${laidOut.edge.activityKind}`
+          }`
+          : ""
       }`
     )
+    const casing = svgElement("path", "chart-edge-casing")
     const visible = svgElement("path", "chart-edge-line")
-    const route = pathData(laidOut.points)
+    const route = chartEdgePathData(laidOut.points)
+    casing.setAttribute("d", route)
     visible.setAttribute("d", route)
     visible.setAttribute("marker-end", "url(#chart-arrow)")
     const hit = svgElement("path", "chart-edge-hit")
     hit.setAttribute("d", route)
-    group.append(visible, hit)
+    group.append(casing, visible)
+    if (laidOut.kind === "transition") {
+      const cue = chartDirectionCue(laidOut.points)
+      if (cue !== null) {
+        const direction = svgElement("path", "chart-edge-direction")
+        direction.setAttribute("d", `M ${cue.start.x} ${cue.start.y} L ${cue.end.x} ${cue.end.y}`)
+        direction.setAttribute("marker-end", "url(#chart-direction)")
+        group.append(direction)
+      }
+    }
+    group.append(hit)
     svg.append(group)
     if (laidOut.kind === "initial") continue
 
@@ -354,7 +465,9 @@ const render = (
     registerEdgeElement(laidOut.edge.id, group)
     const label = element(
       "button",
-      `chart-edge-label chart-edge-label-${laidOut.edge.trigger.type}`,
+      `chart-edge-label chart-edge-label-${laidOut.edge.trigger.type}${
+        laidOut.edge.activityKind === null ? "" : ` chart-edge-activity-${laidOut.edge.activityKind}`
+      }`,
       laidOut.edge.label
     )
     label.type = "button"

package/src/internal/browser/styles.css

@@ -308,6 +308,31 @@ button {
   cursor: default;
 }
 
+.toolbar-button[aria-pressed="true"] {
+  color: #dce8ff;
+  background: rgb(65 103 165 / 28%);
+}
+
+.analysis-button {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.analysis-button[hidden] {
+  display: none;
+}
+
+.analysis-button-count {
+  min-width: 17px;
+  padding: 2px 5px;
+  border-radius: 8px;
+  color: #9da6b3;
+  background: #20242a;
+  font: 10px/1 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  text-align: center;
+}
+
 .topology-chart {
   display: flex;
   flex: 1;
@@ -411,6 +436,23 @@ button {
   background: rgb(20 24 30 / 74%);
 }
 
+.chart-unconnected-region {
+  position: absolute;
+  border: 1px dashed #353b44;
+  border-radius: 5px;
+  background: rgb(14 16 19 / 58%);
+}
+
+.chart-unconnected-region-label {
+  position: absolute;
+  top: 17px;
+  left: 24px;
+  color: #727984;
+  font: 9px/1 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+}
+
 .chart-state {
   position: absolute;
   display: block;
@@ -558,11 +600,51 @@ button {
 
 .chart-activity-kind {
   min-width: max-content;
-  color: #77a990;
+  color: var(--chart-activity-color, #77a990);
   overflow: visible;
   text-overflow: clip;
 }
 
+.chart-activity-process,
+.chart-edge-activity-process,
+.badge-activity-process {
+  --chart-activity-color: #a98978;
+  --chart-activity-border: #51433c;
+  --chart-activity-background: #191513;
+}
+
+.chart-activity-effect,
+.chart-edge-activity-effect,
+.badge-activity-effect {
+  --chart-activity-color: #7f9f8c;
+  --chart-activity-border: #42564b;
+  --chart-activity-background: #131815;
+}
+
+.chart-activity-timer,
+.chart-edge-activity-timer,
+.badge-activity-timer {
+  --chart-activity-color: #aaa07c;
+  --chart-activity-border: #57503c;
+  --chart-activity-background: #191812;
+}
+
+.chart-activity-stream,
+.chart-edge-activity-stream,
+.badge-activity-stream {
+  --chart-activity-color: #7898a2;
+  --chart-activity-border: #405259;
+  --chart-activity-background: #121719;
+}
+
+.chart-activity-machine,
+.chart-edge-activity-machine,
+.badge-activity-machine {
+  --chart-activity-color: #958aa8;
+  --chart-activity-border: #4d4658;
+  --chart-activity-background: #17151a;
+}
+
 .chart-more {
   min-height: 18px;
   padding-top: 3px;
@@ -591,17 +673,30 @@ button {
   user-select: none;
 }
 
+.chart-edge-casing,
 .chart-edge-line,
+.chart-edge-direction,
 .chart-edge-hit {
   fill: none;
 }
 
-.chart-edge-line {
+.chart-edge-casing {
+  stroke: #0b0c0e;
+  stroke-width: 5.5;
+  vector-effect: non-scaling-stroke;
+}
+
+.chart-edge-line,
+.chart-edge-direction {
   stroke: #626b77;
   stroke-width: 1.4;
   vector-effect: non-scaling-stroke;
 }
 
+.chart-edge-direction {
+  pointer-events: none;
+}
+
 .chart-edge-initial .chart-edge-line {
   stroke: #89929e;
 }
@@ -613,7 +708,8 @@ button {
   pointer-events: stroke;
 }
 
-#chart-arrow path {
+#chart-arrow path,
+#chart-direction path {
   fill: context-stroke;
 }
 
@@ -647,7 +743,8 @@ button {
   color: #d4b4e9;
 }
 
-.chart-edge-group.is-hovered .chart-edge-line {
+.chart-edge-group.is-hovered .chart-edge-line,
+.chart-edge-group.is-hovered .chart-edge-direction {
   stroke: #7c9ed2;
   stroke-width: 1.8;
 }
@@ -661,22 +758,56 @@ button {
   stroke-dasharray: 5 5;
 }
 
-.chart-edge-group.is-incoming .chart-edge-line {
+.chart-edge-group.chart-edge-trigger-always .chart-edge-line,
+.chart-edge-group.chart-edge-trigger-choice .chart-edge-line,
+.chart-edge-group.chart-edge-trigger-done .chart-edge-line,
+.chart-edge-group.chart-edge-trigger-invoke .chart-edge-line {
+  stroke-dasharray: 7 5;
+}
+
+.chart-edge-group.chart-edge-activity-process .chart-edge-line,
+.chart-edge-group.chart-edge-activity-effect .chart-edge-line,
+.chart-edge-group.chart-edge-activity-timer .chart-edge-line,
+.chart-edge-group.chart-edge-activity-stream .chart-edge-line,
+.chart-edge-group.chart-edge-activity-machine .chart-edge-line,
+.chart-edge-group.chart-edge-activity-process .chart-edge-direction,
+.chart-edge-group.chart-edge-activity-effect .chart-edge-direction,
+.chart-edge-group.chart-edge-activity-timer .chart-edge-direction,
+.chart-edge-group.chart-edge-activity-stream .chart-edge-direction,
+.chart-edge-group.chart-edge-activity-machine .chart-edge-direction {
+  stroke: var(--chart-activity-color);
+}
+
+.chart-edge-label.chart-edge-activity-process,
+.chart-edge-label.chart-edge-activity-effect,
+.chart-edge-label.chart-edge-activity-timer,
+.chart-edge-label.chart-edge-activity-stream,
+.chart-edge-label.chart-edge-activity-machine {
+  border-color: var(--chart-activity-border);
+  color: var(--chart-activity-color);
+  background: var(--chart-activity-background);
+}
+
+.chart-edge-group.is-incoming .chart-edge-line,
+.chart-edge-group.is-incoming .chart-edge-direction {
   stroke: #ed6a70;
   stroke-width: 2;
 }
 
-.chart-edge-group.is-outgoing .chart-edge-line {
+.chart-edge-group.is-outgoing .chart-edge-line,
+.chart-edge-group.is-outgoing .chart-edge-direction {
   stroke: #6eb6dc;
   stroke-width: 2;
 }
 
-.chart-edge-group.is-selected .chart-edge-line {
+.chart-edge-group.is-selected .chart-edge-line,
+.chart-edge-group.is-selected .chart-edge-direction {
   stroke: #8ab5ff;
   stroke-width: 2.5;
 }
 
-.chart-edge-group.is-walkthrough-available .chart-edge-line {
+.chart-edge-group.is-walkthrough-available .chart-edge-line,
+.chart-edge-group.is-walkthrough-available .chart-edge-direction {
   stroke: #d5aa57;
   stroke-width: 2;
 }
@@ -827,6 +958,15 @@ button {
   background: rgb(78 181 131 / 14%);
 }
 
+.badge-activity-process,
+.badge-activity-effect,
+.badge-activity-timer,
+.badge-activity-stream,
+.badge-activity-machine {
+  color: var(--chart-activity-color);
+  background: var(--chart-activity-background);
+}
+
 .badge-count {
   color: #858c96;
   background: transparent;
@@ -835,7 +975,7 @@ button {
 .inspector {
   position: absolute;
   z-index: 10;
-  top: 14px;
+  top: 60px;
   right: 14px;
   bottom: 14px;
   width: min(460px, calc(100% - 28px));
@@ -973,6 +1113,13 @@ button {
   border-bottom: 1px solid var(--line);
 }
 
+.analysis-summary {
+  margin: 12px 0 0;
+  color: #7f8690;
+  font-size: 12px;
+  line-height: 1.6;
+}
+
 .state-annotations {
   margin-top: 18px;
 }
@@ -1071,6 +1218,33 @@ button {
   background: var(--surface-raised);
 }
 
+.analysis-card {
+  padding-bottom: 12px;
+}
+
+.analysis-card .state-link {
+  color: #e2e4e7;
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.analysis-message,
+.analysis-qualification {
+  margin: 0;
+  padding: 0 12px;
+  font-size: 11px;
+  line-height: 1.6;
+}
+
+.analysis-message {
+  color: #b9bec6;
+}
+
+.analysis-qualification {
+  margin-top: 5px;
+  color: #747c87;
+}
+
 .card-header {
   display: flex;
   min-height: 42px;
@@ -1546,7 +1720,7 @@ button {
   }
 
   .inspector {
-    top: 8px;
+    top: 54px;
     right: 8px;
     bottom: 8px;
     width: min(440px, calc(100% - 16px));
@@ -1572,6 +1746,10 @@ button {
     padding: 48px 14px 18px;
   }
 
+  .inspector {
+    top: 84px;
+  }
+
   .zoom-controls {
     bottom: 8px;
     left: 8px;

package/src/internal/browser/transition-semantics-example.ts

@@ -33,6 +33,9 @@ class Paused extends Schema.TaggedClass<Paused>("TransitionPaused")("Paused", {
 class Published extends Schema.TaggedClass<Published>("TransitionPublished")("Published", {
   result: Schema.String
 }) {}
+class Disabled extends Schema.TaggedClass<Disabled>("TransitionDisabled")("Disabled", {
+  reason: Schema.String
+}) {}
 
 class Create extends Schema.TaggedClass<Create>("TransitionCreate")("Create", {
   text: Schema.String,
@@ -67,6 +70,9 @@ class BumpWorkspace extends Schema.TaggedClass<BumpWorkspace>("TransitionBumpWor
   "BumpWorkspace",
   {}
 ) {}
+class Archive extends Schema.TaggedClass<Archive>("TransitionArchive")("Archive", {
+  reason: Schema.String
+}) {}
 
 const TransitionStates = Machine.states({
   Workspace: {
@@ -91,6 +97,7 @@ const TransitionStates = Machine.states({
     }
   },
   Paused,
+  Disabled,
   Published: { schema: Published, type: "final", output: Schema.String }
 })
 
@@ -121,7 +128,8 @@ export const transitionSemanticsMachine = Machine.make({
     Refresh,
     Ignore,
     MaybeHandle,
-    BumpWorkspace
+    BumpWorkspace,
+    Archive
   ),
   initial: (to) => to.Paused().resolve(({ target }) => target.decoded(new Paused({ reason: "not started" })))
 }).handle({
@@ -230,6 +238,7 @@ export const transitionSemanticsMachine = Machine.make({
         )
     }
   },
+  Disabled: {},
   Published: {
     output: ({ state }) => state.result
   }

package/src/internal/browser/visualizer-analysis.ts

@@ -0,0 +1,52 @@
+import type { MachineDocument as VisualizationDocument } from "../../MachineDocument.js"
+import { makeChartLayoutPolicy } from "./chart-layout-policy.js"
+import { makeChartModel } from "./chart-model.js"
+
+export interface UnhandledPublicEventWarning {
+  readonly _tag: "UnhandledPublicEvent"
+  readonly event: string
+}
+
+export interface NoStaticPathNote {
+  readonly _tag: "NoStaticPathFromInitial"
+  readonly path: string
+  readonly label: string
+  readonly type: "atomic" | "compound" | "parallel" | "final" | "history" | "choice"
+  readonly descendantCount: number
+}
+
+export interface VisualizerAnalysis {
+  readonly warnings: ReadonlyArray<UnhandledPublicEventWarning>
+  readonly topologyNotes: ReadonlyArray<NoStaticPathNote>
+}
+
+/** Static findings derived without executing machine callbacks. */
+export const analyzeVisualization = (document: VisualizationDocument): VisualizerAnalysis => {
+  const handledEvents = new Set(
+    document.transitions.flatMap((transition): ReadonlyArray<string> =>
+      transition.trigger.type === "event" ? [transition.trigger.event] : []
+    )
+  )
+  const declaredEvents = new Set(document.inputs.events.map(({ event }) => event))
+  const warnings = [...declaredEvents].flatMap((event): ReadonlyArray<UnhandledPublicEventWarning> =>
+    handledEvents.has(event) ? [] : [{ _tag: "UnhandledPublicEvent", event }]
+  )
+
+  const chart = makeChartModel(document)
+  const policy = makeChartLayoutPolicy(chart)
+  const topologyNotes = chart.nodes.flatMap((node): ReadonlyArray<NoStaticPathNote> => {
+    const hasStaticPath = policy.node(node.path).staticPath
+    const parentHasStaticPath = node.parent === null || policy.node(node.parent).staticPath
+    if (hasStaticPath || !parentHasStaticPath) return []
+    const descendantCount = chart.nodes.filter(({ path }) => path.startsWith(`${node.path}.`)).length
+    return [{
+      _tag: "NoStaticPathFromInitial",
+      path: node.path,
+      label: node.label,
+      type: node.type,
+      descendantCount
+    }]
+  })
+
+  return { warnings, topologyNotes }
+}