reviewflow 3.26.0 → 3.28.0

package/dist/dashboard/modules/setupWizardAvatar.js

@@ -0,0 +1,217 @@
+/**
+ * Dashboard module — Setup Wizard wireframe avatar (SPEC-188, Phase 1).
+ * Humble object: pure functions, no global state, no direct DOM access.
+ * Holds ALL the avatar logic: maps the SPEC-183/187 wizard stream into one of
+ * six avatar states, decides whether the avatar or the 2D fallback applies, and
+ * projects the procedural wireframe geometry. The requestAnimationFrame canvas
+ * loop lives in setupWizardAvatarRenderer.js and delegates every decision here.
+ *
+ * Visual DNA: "Agentic OS" — see project_agentic_os_design_dna.md.
+ */
+
+/**
+ * @typedef {'idle' | 'working' | 'success' | 'error' | 'listening' | 'celebrating'} AvatarState
+ */
+
+/**
+ * The six avatar states a wireframe core can be in, in narrative order.
+ * @type {AvatarState[]}
+ */
+export const AVATAR_STATES = ['idle', 'working', 'success', 'error', 'listening', 'celebrating'];
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function statusOf(value) {
+  return value && typeof value === 'object' && typeof (/** @type {Record<string, unknown>} */ (value).status) === 'string'
+    ? /** @type {string} */ (/** @type {Record<string, unknown>} */ (value).status)
+    : '';
+}
+
+/**
+ * Maps a single event status to the avatar state it drives. Returns null for a
+ * status the avatar does not react to (so the fold can keep the previous state).
+ *
+ * @param {string} status
+ * @returns {AvatarState | null}
+ */
+function avatarStateForStatus(status) {
+  if (status === 'in_progress' || status === 'warning') {
+    return 'working';
+  }
+  if (status === 'succeeded' || status === 'skipped') {
+    return 'success';
+  }
+  if (status === 'blocked') {
+    return 'error';
+  }
+  if (status === 'awaiting_input') {
+    return 'listening';
+  }
+  if (status === 'completed') {
+    return 'celebrating';
+  }
+  return null;
+}
+
+/**
+ * Folds the ordered event list to the avatar state of the latest relevant event.
+ * Nothing relevant yet → idle.
+ *
+ * @param {Array<Record<string, unknown>>} events
+ * @returns {AvatarState}
+ */
+export function avatarStateFromEvents(events) {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const state = avatarStateForStatus(statusOf(events[index]));
+    if (state !== null) {
+      return state;
+    }
+  }
+  return 'idle';
+}
+
+/**
+ * Decides whether the animated wireframe avatar applies. Phase 1 renders on a
+ * plain 2D canvas (no WebGL), so the capability gate is "can we get a 2D
+ * context"; reduced motion always routes to the static 2D fallback.
+ *
+ * @param {{ canvasSupported: boolean; reducedMotion: boolean }} capabilities
+ * @returns {boolean}
+ */
+export function shouldUseAvatar(capabilities) {
+  return capabilities.canvasSupported === true && capabilities.reducedMotion === false;
+}
+
+/**
+ * @typedef {Object} AvatarVisual
+ * @property {string} color CSS custom-property name driving the stroke colour.
+ * @property {number} lineWidth Stroke width in device pixels.
+ * @property {number} rotationSpeed Radians per second of the Y rotation.
+ * @property {number} pulse Amplitude of the radius/opacity breathing envelope.
+ */
+
+/** @type {Record<AvatarState, AvatarVisual>} */
+const AVATAR_VISUALS = {
+  idle: { color: '--accent', lineWidth: 1, rotationSpeed: 0.3, pulse: 0.15 },
+  working: { color: '--accent', lineWidth: 1.5, rotationSpeed: 1.2, pulse: 0.25 },
+  success: { color: '--success', lineWidth: 1.5, rotationSpeed: 0.6, pulse: 0.4 },
+  error: { color: '--danger', lineWidth: 2, rotationSpeed: 0.2, pulse: 0.5 },
+  listening: { color: '--accent', lineWidth: 1.5, rotationSpeed: 0.45, pulse: 0.3 },
+  celebrating: { color: '--success', lineWidth: 2, rotationSpeed: 1.6, pulse: 0.6 },
+};
+
+/**
+ * Maps an avatar state to its stroke/animation parameters. Keeps the renderer
+ * humble: every per-state visual decision lives here, not in the canvas loop.
+ *
+ * @param {AvatarState} state
+ * @returns {AvatarVisual}
+ */
+export function avatarStateToVisual(state) {
+  return AVATAR_VISUALS[state];
+}
+
+const GOLDEN_RATIO = (1 + Math.sqrt(5)) / 2;
+
+/**
+ * @typedef {[number, number, number]} Vertex
+ */
+
+/**
+ * The 12 vertices of a unit icosahedron (golden-ratio rectangles). A fixed,
+ * abstract wireframe core — the six avatar states reuse this same geometry and
+ * differ only by colour/line-width/rotation-speed/pulse.
+ * @type {Vertex[]}
+ */
+export const WIREFRAME_VERTICES = [
+  [-1, GOLDEN_RATIO, 0],
+  [1, GOLDEN_RATIO, 0],
+  [-1, -GOLDEN_RATIO, 0],
+  [1, -GOLDEN_RATIO, 0],
+  [0, -1, GOLDEN_RATIO],
+  [0, 1, GOLDEN_RATIO],
+  [0, -1, -GOLDEN_RATIO],
+  [0, 1, -GOLDEN_RATIO],
+  [GOLDEN_RATIO, 0, -1],
+  [GOLDEN_RATIO, 0, 1],
+  [-GOLDEN_RATIO, 0, -1],
+  [-GOLDEN_RATIO, 0, 1],
+];
+
+/**
+ * The 30 edges of the icosahedron, as index pairs into WIREFRAME_VERTICES.
+ * @type {Array<[number, number]>}
+ */
+export const WIREFRAME_EDGES = [
+  [0, 11],
+  [0, 5],
+  [0, 1],
+  [0, 7],
+  [0, 10],
+  [1, 5],
+  [5, 11],
+  [11, 10],
+  [10, 7],
+  [7, 1],
+  [3, 9],
+  [3, 4],
+  [3, 2],
+  [3, 6],
+  [3, 8],
+  [4, 9],
+  [9, 8],
+  [8, 6],
+  [6, 2],
+  [2, 4],
+  [5, 9],
+  [11, 4],
+  [10, 2],
+  [7, 6],
+  [1, 8],
+  [4, 5],
+  [9, 1],
+  [8, 7],
+  [6, 10],
+  [2, 11],
+];
+
+/**
+ * @typedef {Object} Projection
+ * @property {number} tilt Fixed X-axis tilt in radians.
+ * @property {number} distance Camera distance for the perspective divide.
+ * @property {number} scale Pixels per unit at the projection plane.
+ * @property {number} centerX Canvas-space x offset.
+ * @property {number} centerY Canvas-space y offset.
+ */
+
+/**
+ * Projects a 3D vertex to a 2D canvas point: rotates around Y by
+ * `rotationRadians`, applies the fixed X tilt, then a trivial perspective
+ * divide and scale. Pure and deterministic.
+ *
+ * @param {Vertex} vertex
+ * @param {number} rotationRadians
+ * @param {Projection} projection
+ * @returns {{ x: number; y: number }}
+ */
+export function projectVertex(vertex, rotationRadians, projection) {
+  const [x, y, z] = vertex;
+
+  const cosY = Math.cos(rotationRadians);
+  const sinY = Math.sin(rotationRadians);
+  const rotatedX = x * cosY + z * sinY;
+  const rotatedZ = -x * sinY + z * cosY;
+
+  const cosTilt = Math.cos(projection.tilt);
+  const sinTilt = Math.sin(projection.tilt);
+  const tiltedY = y * cosTilt - rotatedZ * sinTilt;
+  const tiltedZ = y * sinTilt + rotatedZ * cosTilt;
+
+  const perspective = projection.scale / (tiltedZ + projection.distance);
+  return {
+    x: projection.centerX + rotatedX * perspective,
+    y: projection.centerY + tiltedY * perspective,
+  };
+}

package/dist/dashboard/modules/setupWizardAvatar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupWizardAvatar.js","sourceRoot":"","sources":["../../../src/dashboard/modules/setupWizardAvatar.js"],"names":[],"mappings":"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"}

package/dist/dashboard/modules/setupWizardAvatarRenderer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The structural slice of a canvas the renderer actually depends on. A real
+ * HTMLCanvasElement satisfies it; tests can pass a lightweight fake without casts.
+ *
+ * @typedef {Object} AvatarCanvas
+ * @property {number} width
+ * @property {number} height
+ * @property {(contextId: '2d') => CanvasRenderingContext2D | null} getContext
+ */
+/**
+ * Mounts the animated wireframe avatar on a 2D canvas and returns its controls.
+ * The page calls setState() on each stream event and destroy() before any
+ * redirect or fallback switch so the rAF loop never leaks.
+ *
+ * @param {Object} options
+ * @param {AvatarCanvas} options.canvas
+ * @param {import('./setupWizardAvatar.js').AvatarState} [options.initialState]
+ * @param {(callback: FrameRequestCallback) => number} [options.requestFrame]
+ * @param {(handle: number) => void} [options.cancelFrame]
+ * @param {() => number} [options.now]
+ * @returns {{ setState: (state: import('./setupWizardAvatar.js').AvatarState) => void; destroy: () => void }}
+ */
+export function mountSetupWizardAvatar(options: {
+    canvas: AvatarCanvas;
+    initialState?: import("./setupWizardAvatar.js").AvatarState | undefined;
+    requestFrame?: ((callback: FrameRequestCallback) => number) | undefined;
+    cancelFrame?: ((handle: number) => void) | undefined;
+    now?: (() => number) | undefined;
+}): {
+    setState: (state: import("./setupWizardAvatar.js").AvatarState) => void;
+    destroy: () => void;
+};
+/**
+ * The structural slice of a canvas the renderer actually depends on. A real
+ * HTMLCanvasElement satisfies it; tests can pass a lightweight fake without casts.
+ */
+export type AvatarCanvas = {
+    width: number;
+    height: number;
+    getContext: (contextId: "2d") => CanvasRenderingContext2D | null;
+};
+//# sourceMappingURL=setupWizardAvatarRenderer.d.ts.map

package/dist/dashboard/modules/setupWizardAvatarRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupWizardAvatarRenderer.d.ts","sourceRoot":"","sources":["../../../src/dashboard/modules/setupWizardAvatarRenderer.js"],"names":[],"mappings":"AA6BA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;GAYG;AACH,gDAPG;IAA8B,MAAM,EAA5B,YAAY;IAC2C,YAAY;IACd,YAAY,eAAtD,oBAAoB,KAAK,MAAM;IACP,WAAW,aAArC,MAAM,KAAK,IAAI;IACD,GAAG,UAApB,MAAM;CACpB,GAAU;IAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,wBAAwB,EAAE,WAAW,KAAK,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAkE5G;;;;;;WAlFa,MAAM;YACN,MAAM;gBACN,CAAC,SAAS,EAAE,IAAI,KAAK,wBAAwB,GAAG,IAAI"}

package/dist/dashboard/modules/setupWizardAvatarRenderer.js

@@ -0,0 +1,117 @@
+/**
+ * Dashboard module — Setup Wizard wireframe avatar renderer (SPEC-188, Phase 1).
+ * Humble glue: a thin requestAnimationFrame loop that strokes the procedural
+ * wireframe core on a 2D canvas. It owns the rAF handle and its teardown, and
+ * delegates EVERY decision (state, colour, line width, rotation speed, pulse,
+ * geometry, projection) to the pure setupWizardAvatar.js module — so it carries
+ * no branching logic of its own. Not unit-tested (browser-only), mirroring the
+ * connectSetupWizardStream precedent.
+ *
+ * Visual DNA: "Agentic OS" — see project_agentic_os_design_dna.md.
+ */
+
+import {
+  avatarStateToVisual,
+  projectVertex,
+  WIREFRAME_VERTICES,
+  WIREFRAME_EDGES,
+} from './setupWizardAvatar.js';
+
+/**
+ * @param {CanvasRenderingContext2D} context
+ * @param {string} colorToken
+ * @returns {string}
+ */
+function resolveColor(context, colorToken) {
+  const value = getComputedStyle(context.canvas).getPropertyValue(colorToken).trim();
+  return value === '' ? '#F4A93D' : value;
+}
+
+/**
+ * The structural slice of a canvas the renderer actually depends on. A real
+ * HTMLCanvasElement satisfies it; tests can pass a lightweight fake without casts.
+ *
+ * @typedef {Object} AvatarCanvas
+ * @property {number} width
+ * @property {number} height
+ * @property {(contextId: '2d') => CanvasRenderingContext2D | null} getContext
+ */
+
+/**
+ * Mounts the animated wireframe avatar on a 2D canvas and returns its controls.
+ * The page calls setState() on each stream event and destroy() before any
+ * redirect or fallback switch so the rAF loop never leaks.
+ *
+ * @param {Object} options
+ * @param {AvatarCanvas} options.canvas
+ * @param {import('./setupWizardAvatar.js').AvatarState} [options.initialState]
+ * @param {(callback: FrameRequestCallback) => number} [options.requestFrame]
+ * @param {(handle: number) => void} [options.cancelFrame]
+ * @param {() => number} [options.now]
+ * @returns {{ setState: (state: import('./setupWizardAvatar.js').AvatarState) => void; destroy: () => void }}
+ */
+export function mountSetupWizardAvatar(options) {
+  const requestFrame = options.requestFrame ?? globalThis.requestAnimationFrame.bind(globalThis);
+  const cancelFrame = options.cancelFrame ?? globalThis.cancelAnimationFrame.bind(globalThis);
+  const now = options.now ?? (() => performance.now());
+  const context = options.canvas.getContext('2d');
+
+  let currentState = options.initialState ?? 'idle';
+  let rotation = 0;
+  let lastTime = now();
+  /** @type {number | null} */
+  let frameHandle = null;
+
+  const projection = {
+    tilt: 0.5,
+    distance: 4,
+    scale: Math.min(options.canvas.width, options.canvas.height) * 0.28,
+    centerX: options.canvas.width / 2,
+    centerY: options.canvas.height / 2,
+  };
+
+  /**
+   * @param {number} time
+   */
+  function draw(time) {
+    if (context === null) {
+      return;
+    }
+    const elapsedSeconds = Math.max(0, (time - lastTime) / 1000);
+    lastTime = time;
+
+    const visual = avatarStateToVisual(currentState);
+    rotation += visual.rotationSpeed * elapsedSeconds;
+
+    const breathe = 1 + visual.pulse * Math.sin(time / 600);
+    const framedProjection = { ...projection, scale: projection.scale * breathe };
+
+    context.clearRect(0, 0, options.canvas.width, options.canvas.height);
+    context.lineWidth = visual.lineWidth;
+    context.strokeStyle = resolveColor(context, visual.color);
+    context.beginPath();
+    for (const [from, to] of WIREFRAME_EDGES) {
+      const start = projectVertex(WIREFRAME_VERTICES[from], rotation, framedProjection);
+      const end = projectVertex(WIREFRAME_VERTICES[to], rotation, framedProjection);
+      context.moveTo(start.x, start.y);
+      context.lineTo(end.x, end.y);
+    }
+    context.stroke();
+
+    frameHandle = requestFrame(draw);
+  }
+
+  frameHandle = requestFrame(draw);
+
+  return {
+    setState: (state) => {
+      currentState = state;
+    },
+    destroy: () => {
+      if (frameHandle !== null) {
+        cancelFrame(frameHandle);
+        frameHandle = null;
+      }
+    },
+  };
+}

package/dist/dashboard/modules/setupWizardAvatarRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupWizardAvatarRenderer.js","sourceRoot":"","sources":["../../../src/dashboard/modules/setupWizardAvatarRenderer.js"],"names":[],"mappings":"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"}

package/dist/dashboard/modules/setupWizardForms.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Maps an awaiting_input event into the form view model, or null when the event
+ * is absent or not an awaiting_input event.
+ *
+ * @param {Record<string, unknown> | null} event
+ * @returns {FormModel | null}
+ */
+export function buildFormModel(event: Record<string, unknown> | null): FormModel | null;
+/**
+ * Renders the form markup for the active awaiting_input step. The DOM wiring
+ * binds submit/click handlers afterwards; the markup here is keyboard-reachable
+ * through native inputs and buttons in DOM order.
+ *
+ * @param {FormModel | null} model
+ * @returns {string}
+ */
+export function renderForm(model: FormModel | null): string;
+/**
+ * Builds the exact `{ runId, kind, value }` body the SPEC-187 endpoint accepts,
+ * coercing the raw form value to the type the kind requires and rejecting any
+ * choice/multiSelect value that was not offered (so junk is never posted).
+ *
+ * @param {FormKind} kind
+ * @param {string} runId
+ * @param {unknown} rawValue
+ * @param {FormOption[]} options
+ * @returns {PayloadResult}
+ */
+export function buildInputPayload(kind: FormKind, runId: string, rawValue: unknown, options: FormOption[]): PayloadResult;
+export type FormKind = "text" | "confirm" | "choice" | "multiSelect";
+export type FormOption = {
+    label: string;
+    value: string;
+};
+export type FormModel = {
+    stepId: string;
+    kind: FormKind;
+    prompt: string;
+    options: FormOption[];
+    defaultValue: string | null;
+};
+export type TextPayload = {
+    runId: string;
+    kind: "text";
+    value: string;
+};
+export type ConfirmPayload = {
+    runId: string;
+    kind: "confirm";
+    value: boolean;
+};
+export type ChoicePayload = {
+    runId: string;
+    kind: "choice";
+    value: string;
+};
+export type MultiSelectPayload = {
+    runId: string;
+    kind: "multiSelect";
+    value: string[];
+};
+export type InputPayload = TextPayload | ConfirmPayload | ChoicePayload | MultiSelectPayload;
+export type PayloadResult = {
+    ok: true;
+    body: InputPayload;
+} | {
+    ok: false;
+    error: string;
+};
+//# sourceMappingURL=setupWizardForms.d.ts.map

package/dist/dashboard/modules/setupWizardForms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupWizardForms.d.ts","sourceRoot":"","sources":["../../../src/dashboard/modules/setupWizardForms.js"],"names":[],"mappings":"AA8FA;;;;;;GAMG;AACH,sCAHW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAC5B,SAAS,GAAG,IAAI,CAoB5B;AAgFD;;;;;;;GAOG;AACH,kCAHW,SAAS,GAAG,IAAI,GACd,MAAM,CAelB;AAWD;;;;;;;;;;GAUG;AACH,wCANW,QAAQ,SACR,MAAM,YACN,OAAO,WACP,UAAU,EAAE,GACV,aAAa,CAgCzB;uBAlQY,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,aAAa;;WAK5C,MAAM;WACN,MAAM;;;YAKN,MAAM;UACN,QAAQ;YACR,MAAM;aACN,UAAU,EAAE;kBACZ,MAAM,GAAG,IAAI;;;WAKb,MAAM;UACN,MAAM;WACN,MAAM;;;WAKN,MAAM;UACN,SAAS;WACT,OAAO;;;WAKP,MAAM;UACN,QAAQ;WACR,MAAM;;;WAKN,MAAM;UACN,aAAa;WACb,MAAM,EAAE;;2BAIT,WAAW,GAAG,cAAc,GAAG,aAAa,GAAG,kBAAkB;4BAIjE;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE"}