dsh-workflow-map 0.0.0-stage → 0.3.2

package/src/client/ProgressUnder.js

@@ -0,0 +1,216 @@
+/**
+ * ProgressUnder.js — the rail that hangs UNDER a step card's frame.
+ *
+ * Contract :
+ * - exactly WF_STEP_GAP (8 px) of air between the card's bottom border and the
+ * rail: the rail belongs to the card but must not be glued to its frame;
+ * - a WF_STEP_RAIL (6 px) track whose fill is coloured by state — running
+ * flows, done is solid, failed is red, not started leaves the track empty;
+ * - the number on the right says WHICH KIND of number it is:
+ * "~62% estimated" a time-baseline extrapolation (percentSource "baseline", and its cold-start
+ * sub-variant "baseline:steps", which keeps the same visible flavour)
+ * "62% self-reported" the model's own report (percentSource "model")
+ * "62% measured" the todo table's measured completion ratio (percentSource "todos")
+ * "100%" a closed step's pinned value
+ * - a step that has NOT started never shows a percentage, even when the wire
+ * payload carries a stale one. No number is better than a fake number.
+ *
+ * adds a SECOND line under the rail — one secondary fact about the
+ * number, never about the work:
+ * - `ago`: how long ago that number was estimated (`view.asOf − step.lastEstimateAt`).
+ * Data freshness: a 40-minute-old estimate on a still-running step is not a
+ * lie, but the user deserves to know it is stale. `lastEstimateAt` is 0 when
+ * no estimate ever arrived, and then the segment is NOT rendered at all —
+ * "0 seconds ago" would be a fabricated number, which is exactly what this plugin
+ * refuses to print.
+ *
+ * (2026-10-26) · the projected REMAINING half is GONE by user request. It used to be shipped
+ * by the host as a derived millisecond field (median of the finished steps, hard-bounded) and
+ * rendered as "remaining ~N minutes"; the host no longer computes it and this rail no longer renders it.
+ * One line, one fact, no consumer-less field — and a payload that still carries that field (an
+ * older host) is simply not read.
+ *
+ * Layout : two right-aligned lines. Line 1 = track + percent (unchanged).
+ * Line 2 = ago, one font step and one colour step down, so it reads as
+ * secondary. With no age to show the whole line is omitted — never a placeholder.
+ * In the narrow container (`data-detail='title'`) only line 1 exists — the host
+ * hides line 2 with CSS, and the compact renderer never emits it.
+ *
+ * Pure: no React import, no DOM, no storage — the same functions run in Node for
+ * tools/selftest-panel.mjs and in the browser. `h` (React.createElement) and
+ * `say` are injected, so this chunk can be asserted without React.
+ *
+ * Inlined into client.js by tools/build-client.mjs (single-file browser half).
+ */
+
+/** The rail's three label flavours, as opposed to "no label at all". */
+function wfProgressLabel(percent, source, status, say) {
+  var value = wfFinite(percent);
+  if (value === null) return null;
+ // A step that has not started has no progress to report. Showing a number here
+ // would be the exact lie the acceptance criterion forbids.
+  if (status === "pending" || status === "skipped") return null;
+  var rounded = Math.round(wfClamp(value, 0, 100));
+  // the cold-start sub-variant of the baseline keeps the SAME visible flavour (~N% estimated):
+ // the sub-division is machine-readable (`baseline:steps`), and falling through to the closed
+ // flavour would print it as a pinned 100 %-style number, which it is not.
+  if (source === "baseline" || source === "baseline:steps") {
+    return { kind: "estimate", percent: rounded, text: say("panel.percent.estimate", { percent: rounded }) };
+  }
+  if (source === "model") {
+    return { kind: "self", percent: rounded, text: say("panel.percent.self", { percent: rounded }) };
+  }
+ // a MEASURED number (the todo table's own completion ratio). It must read differently
+ // from both "self-reported" and "estimated", or the user cannot tell a fact from a guess.
+  if (source === "todos") {
+    return { kind: "real", percent: rounded, text: say("panel.percent.real", { percent: rounded }) };
+  }
+  return { kind: "closed", percent: rounded, text: rounded + "%" };
+}
+
+/**
+ * Fill width in percent of the track. A running step with no number yet gets a
+ * narrow indeterminate segment (animated, no digits) instead of a fake value.
+ */
+function wfProgressFillWidth(row) {
+  var status = row && typeof row.status === "string" ? row.status : "pending";
+  if (status === "pending" || status === "skipped") return 0;
+  var value = wfFinite(row.percent);
+  if (value === null) return status === "running" ? 30 : 0;
+  return Math.round(wfClamp(value, 0, 100));
+}
+
+function wfProgressIndeterminate(row) {
+  var status = row && typeof row.status === "string" ? row.status : "pending";
+  return status === "running" && wfFinite(row.percent) === null;
+}
+
+/**
+ * 180_000 -> "3 minutes", 5_400 -> "54 seconds", 3_720_000 -> "62 minutes".
+ * One decimal below ten seconds, integers above — a clock's precision, not a
+ * stopwatch's. 0 or less returns "" (never "0 seconds": see the caller).
+ */
+function wfProgressDurationText(ms) {
+  var value = wfFinite(ms);
+  if (value === null || value <= 0) return "";
+  if (value < 10000) {
+    var seconds = Math.round(value / 100) / 10;
+    return (seconds % 1 === 0 ? String(Math.round(seconds)) : seconds.toFixed(1)) + " 秒";
+  }
+  if (value < 60000) return Math.round(value / 1000) + " 秒";
+  if (value < 3600000) {
+    var minutes = Math.floor(value / 60000);
+    return minutes + " 分钟";
+  }
+  return Math.floor(value / 3600000) + " 小时";
+}
+
+/**
+ * the ONE secondary fact left — how stale the number being quoted is — or null. Pure
+ * arithmetic on the row the host already shipped; no clock is read here (the caller passes `asOf`).
+ *
+ * `ago` needs a real `lastEstimateAt` AND an `asOf` after it: a step that has never carried a
+ * number gets no segment, and a future stamp (a re-ordered event log) is clamped to nothing
+ * rather than shown as a negative duration. A missing field produces NO segment — never a
+ * fabricated 0 or "—" (the ETA half went with the host's derived field).
+ */
+function wfProgressTiming(row, asOf) {
+  var status = row && typeof row.status === "string" ? row.status : "pending";
+  var now = wfFinite(asOf);
+  var estimateAt = wfFinite(row ? row.lastEstimateAt : null);
+ // The gate mirrors the percent label's: only a step that HAS a live progress number can read
+ // "estimated N minutes ago", because the sentence is about that number. A pending row with a leftover stamp
+ // (a re-plan that reset a step, say) would otherwise advertise an estimate it never made — the
+ // same "no number beats a fake number" rule the percent label already follows. `ago` is a fact
+ // about the PAST, so it only needs a number to have existed at all: percent > 0.
+  var livePercent = wfFinite(row ? row.percent : null);
+  var hasAnyNumber = livePercent !== null && livePercent > 0 && status !== "pending";
+  var ago = null;
+  if (hasAnyNumber && now !== null && estimateAt !== null && estimateAt > 0 && now > estimateAt) {
+    ago = wfProgressDurationText(now - estimateAt);
+    if (ago === "") ago = null;
+  }
+  return { ago: ago };
+}
+
+/** One rail: track + fill + the right-hand number (omitted when there is none). */
+function wfRenderProgressDock(h, row, say, asOf) {
+  var status = row && typeof row.status === "string" ? row.status : "pending";
+  var label = wfProgressLabel(row ? row.percent : null, row ? row.percentSource : "none", status, say);
+  var width = wfProgressFillWidth(row);
+  var indeterminate = wfProgressIndeterminate(row);
+  var compact = !!(row && row.compact === true);
+  var ago = compact ? null : wfProgressTiming(row, asOf).ago;
+
+  var trackProps = {
+    className: "wf-prog-track",
+    key: "track",
+    role: "progressbar",
+    "aria-label": say("panel.step.progress", { title: row && row.title ? row.title : "" }),
+    "aria-valuemin": 0,
+    "aria-valuemax": 100,
+  };
+  if (label !== null) {
+    trackProps["aria-valuenow"] = label.percent;
+    trackProps["aria-valuetext"] = label.text;
+  }
+
+ // the second line — ONE fact (the age of the number), so there is no bits array and
+ // no separator any more. the projected remainder is gone, so `data-timing` converged to
+ // none|one; nothing at all renders when there is no age (never a placeholder).
+  var subline = ago === null
+    ? null
+    : h(
+        "div",
+        { className: "wf-prog-sub", key: "sub" },
+        h(
+          "span",
+          {
+            className: "wf-prog-ago",
+            key: "ago",
+            title: say("panel.percent.ago", { duration: ago }),
+          },
+          say("panel.percent.ago", { duration: ago })
+        )
+      );
+
+  return h(
+    "div",
+    {
+      className: "wf-prog-dock",
+      key: "dock",
+      "data-dsh-workflow-map": "progress",
+      "data-step-index": row ? row.index : undefined,
+      "data-status": status,
+      "data-indeterminate": indeterminate ? "true" : "false",
+      "data-timing": ago === null ? "none" : "one",
+    },
+    h(
+      "div",
+      { className: "wf-prog-row", key: "row" },
+      h("div", trackProps, h("div", {
+        className: "wf-prog-fill",
+        key: "fill",
+        "data-indeterminate": indeterminate ? "true" : "false",
+  // Exactly one step's rail carries the flowing gradient: decided by the caller's row.live (the host marks only
+  // the single running row), not "everything running animates". Without that field it falls back to the old behaviour.
+        "data-live": (row && row.live === true) || (row && row.live === undefined && status === "running") ? "true" : "false",
+        style: { width: width + "%" },
+      })),
+      label === null
+        ? null
+        : h(
+            "span",
+            {
+              className: "wf-prog-label",
+              key: "label",
+              "data-kind": label.kind,
+              "data-percent": label.percent,
+              title: label.text,
+            },
+            label.text
+          )
+    ),
+    subline
+  );
+}

package/src/client/RightPage.js

@@ -0,0 +1,285 @@
+/**
+ * RightPage.js — the RIGHT-HAND page, opened by a click on the main flow or on a circle.
+ *
+ * One page, three kinds of content, decided by the click that opened it:
+ *
+ * kind "step" → that step's full record. The report / artifacts / statistics block is the
+ * EXISTING renderer (wfRenderStepDetail); what this file adds is the
+ * per-type list above it — "this step touched .md ×3, pwsh ×2 …" — each row a
+ * button that switches the page to that type. That is how a main-flow click can
+ * walk into a type without going back to the circle.
+ * kind "type" → every call of ONE file type (a step's circle, or the whole session when the
+ * click came from the header's type strip). Each call expands IN PLACE into
+ * 's node detail, so the page never grows a second detail vocabulary.
+ * kind "inject"→ the hot-inject composer (HotInject.js), mounted here instead of a third column.
+ *
+ * Nothing is invented: a type that no call supports renders the empty hint, and a step whose
+ * nodes the host never sent says so (the count comes from the host, the list from the wire).
+ *
+ * Pure: `h` and `say` are injected; no React import, no DOM.
+ *
+ * Inlined into client.js by tools/build-client.mjs (single-file browser half).
+ */
+
+/** The title line: step N · title / .md · 3 calls / hot injection. */
+function wfPageTitle(kind, say, ctx) {
+  var context = ctx || {};
+  if (kind === "inject") return say("panel.page.inject");
+  if (kind === "type") {
+    return say(context.scopeStep === null ? "panel.page.typeSession" : "panel.page.typeStep", {
+      label: context.label || "—",
+      n: wfFinite(context.scopeStep) === null ? "" : context.scopeStep + 1,
+    });
+  }
+  return say("panel.page.step", { n: (wfFinite(context.stepIndex) === null ? 0 : context.stepIndex) + 1 });
+}
+
+/** The close button. One per page; Escape does the same thing (wfBindEscape → onEscapeDetail). */
+function wfPageClose(h, say, actions) {
+  var fire = actions || {};
+  return h(
+    "button",
+    {
+      type: "button",
+      className: "wf-page-close",
+      key: "close",
+      "data-dsh-workflow-map": "page-close",
+      title: say("panel.page.close"),
+      "aria-label": say("panel.page.close"),
+      onClick: function () {
+        if (typeof fire.onClosePage === "function") fire.onClosePage();
+      },
+    },
+    "×"
+  );
+}
+
+/**
+ * A call row of the type page. It is a <button> that opens 's node detail under itself —
+ * the SAME wfRenderNodeDetail the flow column uses, fed the SAME node, so the privacy rule and the
+ * 200-character caps are whatever already guarantees.
+ */
+function wfRenderCallRow(h, node, say, actions, ctx) {
+  var context = ctx || {};
+  var fire = actions || {};
+  var item = node && typeof node === "object" ? node : {};
+  var id = typeof item.id === "string" ? item.id : "";
+  var open = context.openCall === id && id !== "";
+  var status = wfNodeStatus(item, context.activeNodeId);
+  var parts = wfNodeTitleParts(item, wfNodeCategory(item), say);
+
+  var label = [];
+  if (parts.verb !== "") label.push(parts.verb, " · ");
+  label.push(parts.target);
+
+  return h(
+    "li",
+    { className: "wf-call", key: "call-" + id, "data-status": status, "data-node-id": id },
+    h(
+      "button",
+      {
+        type: "button",
+        className: "wf-call-head",
+        key: "head",
+        "data-dsh-workflow-map": "call",
+        "data-node-id": id,
+        "data-open": open ? "true" : "false",
+        "aria-expanded": open ? "true" : "false",
+        title: parts.verb !== "" ? parts.verb + " · " + parts.target : parts.target,
+        onClick: function () {
+          if (typeof fire.onSelectCall === "function") fire.onSelectCall(id);
+        },
+      },
+      h("span", { className: "wf-call-main", key: "main" }, label),
+      h(
+        "span",
+        { className: "wf-call-meta", key: "meta" },
+        wfFormatClock(item.at) === "" ? "" : wfFormatClock(item.at),
+        wfFormatDuration(item.durationMs) === "" ? "" : " · " + wfFormatDuration(item.durationMs)
+      ),
+      h("span", {
+        className: "wf-flow-status",
+        key: "status",
+        "data-status": status,
+        "aria-hidden": "true",
+      })
+    ),
+    open ? wfRenderNodeDetail(h, item, say, fire, { detail: "summary" }) : null
+  );
+}
+
+/**
+ * The type page's body: the calls of one bucket, in wire order, plus the honest note when the
+ * host never sent some of them (the bucket carries the host's count, the list only what arrived).
+ */
+function wfRenderTypeBody(h, bucket, nodes, say, actions, ctx) {
+  var context = ctx || {};
+  var list = Array.isArray(nodes) ? nodes : [];
+  var total = wfFinite(bucket && bucket.count) === null ? list.length : Math.max(0, Math.round(bucket.count));
+
+  if (list.length === 0) {
+    return h("div", { className: "wf-empty", key: "empty" }, say("panel.page.typeEmpty"));
+  }
+
+  var more = total > list.length ? say("panel.page.truncated", { count: total - list.length }) : "";
+
+  return h(
+    "div",
+    { className: "wf-calls", key: "calls", "data-dsh-workflow-map": "calls", "data-count": list.length },
+    h(
+      "ul",
+      { className: "wf-call-list", key: "list", role: "list" },
+      list.map(function (node) {
+        return wfRenderCallRow(h, node, say, actions, context);
+      })
+    ),
+    more === "" ? null : h("div", { className: "wf-detail-note", key: "more" }, more)
+  );
+}
+
+/**
+ * The step page's body: the type summary, then 's own detail block.
+ *
+ * The type summary is the ONLY new thing, and it exists because the page is reached by clicking a
+ * unit, not a circle: without it the circles would be the only way into a type. Each row is a
+ * button with the same `onOpenType(stepIndex, key)` action the circles fire.
+ */
+function wfRenderStepTypeSummary(h, unit, say, actions, ctx) {
+  var context = ctx || {};
+  var fire = actions || {};
+  var types = unit && Array.isArray(unit.types) ? unit.types : [];
+  if (types.length === 0) {
+    return h("div", { className: "wf-detail-empty", key: "empty" }, say("panel.page.noTypes"));
+  }
+
+  return h(
+    "div",
+    { className: "wf-type-list", key: "types", "data-dsh-workflow-map": "type-list", "data-count": types.length },
+    h("div", { className: "wf-detail-label", key: "label" }, say("panel.page.types")),
+    h(
+      "div",
+      { className: "wf-type-rows", key: "rows" },
+      types.map(function (type) {
+        var open = context.openType === type.key && context.openStep === unit.index;
+        return h(
+          "button",
+          {
+            type: "button",
+            className: "wf-type-row",
+            key: "type-" + type.key,
+            "data-dsh-workflow-map": "type-row",
+            "data-type": type.key,
+            "data-side": type.side,
+            "data-live": type.running === true ? "true" : "false",
+            "data-open": open ? "true" : "false",
+            "aria-pressed": open ? "true" : "false",
+            onClick: function () {
+              if (typeof fire.onOpenType === "function") fire.onOpenType(unit.index, type.key);
+            },
+          },
+          h("span", { className: "wf-type-dot", key: "dot", "data-tone": type.tone, "aria-hidden": "true" }),
+          h("span", { className: "wf-type-label", key: "label" }, type.label),
+          h("span", { className: "wf-type-kind", key: "kind" }, say(type.kind === "tool" ? "panel.page.kind.tool" : "panel.page.kind.file")),
+          h("span", { className: "wf-type-count", key: "count" }, say("panel.page.count", { count: type.count }))
+        );
+      })
+    )
+  );
+}
+
+/**
+ * The whole right page. `extras` carries the decided content:
+ * {kind, stepIndex, unit, detail, typeKey, bucket, nodes, stepDetail, openType, openCall,
+ * activeNodeId, inject:{...}}
+ *
+ * `detail` is the record built by store.js for the SELECTED step; a page about another
+ * step falls back to the unit's own numbers and says the report is not loaded, rather than
+ * showing the selected step's report under a different step's title.
+ */
+function wfRenderRightPage(h, model, say, actions, extras) {
+  var fire = actions || {};
+  var ui = extras || {};
+  var kind = ui.kind === "type" || ui.kind === "inject" ? ui.kind : "step";
+  var context = {
+    stepIndex: wfFinite(ui.stepIndex) === null ? null : Math.round(ui.stepIndex),
+    scopeStep: wfFinite(ui.scopeStep) === null ? null : Math.round(ui.scopeStep),
+    openType: typeof ui.openType === "string" && ui.openType !== "" ? ui.openType : null,
+    openCall: typeof ui.openCall === "string" && ui.openCall !== "" ? ui.openCall : null,
+    openStep: wfFinite(ui.stepIndex) === null ? null : Math.round(ui.stepIndex),
+    label: typeof ui.label === "string" ? ui.label : "",
+    activeNodeId: typeof ui.activeNodeId === "string" && ui.activeNodeId !== "" ? ui.activeNodeId : null,
+  };
+
+  var title = wfPageTitle(kind, say, {
+    label: context.label,
+    scopeStep: context.scopeStep,
+    stepIndex: context.stepIndex,
+  });
+
+  var body;
+  if (kind === "inject") {
+    body = wfRenderHotInject(h, say, fire, {
+      sessionId: ui.sessionId,
+      state: ui.injectState,
+      text: ui.injectText,
+      reason: ui.injectReason,
+      history: ui.injectHistory,
+ // the one row being revoked (if any) plus the host's reason when it said no.
+      revokeId: ui.injectRevokeId,
+      revokeState: ui.injectRevokeState,
+      revokeReason: ui.injectRevokeReason,
+    });
+  } else if (kind === "type") {
+    body = [
+      h(
+        "div",
+        { className: "wf-page-sub", key: "sub" },
+        say("panel.page.typeSub", {
+          step: context.scopeStep === null ? say("panel.page.wholeSession") : "第 " + (context.scopeStep + 1) + " 步",
+          count: wfFinite(ui.bucket && ui.bucket.count) === null ? 0 : Math.max(0, Math.round(ui.bucket.count)),
+        })
+      ),
+      wfRenderTypeBody(h, ui.bucket, ui.nodes, say, actions, context),
+    ];
+  } else {
+    var unit = ui.unit && typeof ui.unit === "object" ? ui.unit : null;
+    var stepDetail = ui.stepDetail && typeof ui.stepDetail === "object" ? ui.stepDetail : null;
+    body = [
+      unit ? wfRenderStepTypeSummary(h, unit, say, actions, context) : null,
+      stepDetail
+        ? wfRenderStepDetail(h, stepDetail, say, fire, context)
+        : h("div", { className: "wf-detail-empty", key: "noload" }, say("panel.page.noReport")),
+    ];
+  }
+
+  return h(
+    "aside",
+    {
+      className: "wf-right",
+      key: "right",
+      "data-dsh-workflow-map": "right",
+      "data-kind": kind,
+      role: "region",
+      "aria-label": title,
+    },
+    h(
+      "div",
+      { className: "wf-right-head", key: "head", "data-dsh-workflow-map": "right-head" },
+      h("span", { className: "wf-right-title", key: "title", title: title }, title),
+      wfPageClose(h, say, actions)
+    ),
+    h("div", { className: "wf-right-scroll", key: "scroll", "data-dsh-workflow-map": "right-scroll" }, body),
+ // the persistent dock. Every page kind that is NOT the composer
+ // gets it at the foot, so a prompt can be typed WITHOUT opening the composer first; the
+ // composer itself does not repeat it. It reads the SAME inject state the composer reads.
+    kind === "inject"
+      ? null
+      : wfRenderInjectDock(h, say, fire, {
+          sessionId: ui.sessionId,
+          state: ui.injectState,
+          text: ui.injectText,
+          reason: ui.injectReason,
+          history: ui.injectHistory,
+        })
+  );
+}