@zaip-ai/cli 5.0.0 → 5.1.0

package/templates/.agents/dashboard/apps/frontend/src/use-app-trace-documents.navigation.test.tsx

@@ -0,0 +1,125 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const browserRequire = createRequire(
+  fileURLToPath(new URL("../../../tests/e2e/package.json", import.meta.url)),
+);
+const { chromium, expect: browserExpect } = browserRequire("@playwright/test");
+
+describe("macro trace navigation from a compact overview", () => {
+  it("hydrates exact macro details, keeps linked rows, and ignores stale macro and Task requests", async () => {
+    const esbuild = browserRequire("esbuild");
+    const harness = await esbuild.build({
+      bundle: true,
+      format: "iife",
+      logLevel: "silent",
+      platform: "browser",
+      write: false,
+      stdin: {
+        contents: `
+          import React, { useState } from "react";
+          import { createRoot } from "react-dom/client";
+          import { useAppTraceDocuments } from "./use-app-trace-documents.js";
+
+          const pending = [];
+          window.__macroTraceProbe = { pending };
+          const api = {
+            operations: (_period, _scope, signal) => new Promise((resolve) => {
+              pending.push({ resolve, signal });
+            }),
+            taskTrace: async (id) => ({ task_id: id, task_title: id }),
+            prd: async (id) => ({ id, title: id, body: "Full document", artifact_path: "prds/one.md" }),
+          };
+          function Harness() {
+            const [error, setError] = useState(null);
+            const [, setFailedArea] = useState(null);
+            const [, setLoadingArea] = useState(null);
+            const state = useAppTraceDocuments({
+              api,
+              operations: { prds: [], specs: [], tasks: [], runs: [], changes: [] },
+              isOperationsDetailLoaded: () => false,
+              setError,
+              setFailedArea,
+              setLoadingArea,
+            });
+            return <>
+              <button onClick={() => void state.openTraceMacro("SPEC", "SPEC-TARGET")}>Open SPEC</button>
+              <button onClick={() => void state.openTraceMacro("PRD", "PRD-TARGET")}>Open PRD</button>
+              <button onClick={() => void state.openTrace("TASK-TARGET")}>Open Task</button>
+              <button onClick={() => void state.openDocument("prd", "PRD-TARGET")}>Read PRD</button>
+              <output id="state">{JSON.stringify({
+                macro: state.traceLink?.kind === "macro" ? state.traceLink.row.id : null,
+                kind: state.traceLink?.kind === "macro" ? state.traceLink.row.kind : null,
+                linkedTaskIds: state.traceLink?.kind === "macro"
+                  ? state.traceLink.projection.tasks.map((row) => row.id) : [],
+                loading: state.traceMacroLoading?.id ?? null,
+                task: state.trace?.task_id ?? null,
+                document: state.documentDetail?.preview.id ?? null,
+                error,
+              })}</output>
+            </>;
+          }
+          createRoot(document.getElementById("root")).render(<Harness />);
+        `,
+        loader: "tsx",
+        resolveDir: fileURLToPath(new URL(".", import.meta.url)),
+        sourcefile: "macro-trace-navigation-harness.tsx",
+      },
+    });
+    const browser = await chromium.launch({ headless: true });
+    try {
+      const page = await browser.newPage();
+      const pageErrors: string[] = [];
+      page.on("pageerror", (error: Error) => pageErrors.push(error.message));
+      await page.setContent('<div id="root"></div>');
+      await page.addScriptTag({ content: harness.outputFiles[0].text });
+      const state = () => page.locator("#state");
+      const resolve = (index: number, prds: unknown[], specs: unknown[]) =>
+        page.evaluate(
+          ({ index, prds, specs }: { index: number; prds: unknown[]; specs: unknown[] }) => {
+            const request = (
+              window as typeof window & {
+                __macroTraceProbe: { pending: Array<{ resolve: (value: unknown) => void }> };
+              }
+            ).__macroTraceProbe.pending[index];
+            if (!request) throw new Error(`Missing pending macro request ${index}`);
+            request.resolve({
+              prds,
+              specs,
+              tasks: [{ id: "TASK-LINKED" }],
+              runs: [],
+            });
+          },
+          { index, prds, specs },
+        );
+
+      await page.getByRole("button", { name: "Open SPEC" }).click();
+      await browserExpect(state()).toContainText('"loading":"SPEC-TARGET"');
+      await page.getByRole("button", { name: "Open PRD" }).click();
+      await browserExpect(state()).toContainText('"loading":"PRD-TARGET"');
+      await resolve(0, [], [{ id: "SPEC-TARGET", kind: "spec" }]);
+      await browserExpect(state()).toContainText('"macro":null');
+      await resolve(1, [{ id: "PRD-TARGET", kind: "prd" }], []);
+      await browserExpect(state()).toContainText('"macro":"PRD-TARGET"');
+      await browserExpect(state()).toContainText('"linkedTaskIds":["TASK-LINKED"]');
+      await page.getByRole("button", { name: "Read PRD" }).click();
+      await browserExpect(state()).toContainText('"document":"PRD-TARGET"');
+
+      await page.getByRole("button", { name: "Open SPEC" }).click();
+      await page.getByRole("button", { name: "Open Task" }).click();
+      await browserExpect(state()).toContainText('"task":"TASK-TARGET"');
+      await resolve(2, [], [{ id: "SPEC-TARGET", kind: "spec" }]);
+      await browserExpect(state()).toContainText('"macro":null');
+
+      await page.getByRole("button", { name: "Open PRD" }).click();
+      await resolve(3, [{ id: "PRD-OTHER", kind: "prd" }], []);
+      await browserExpect(state()).toContainText('"error":"PRD PRD-TARGET not found"');
+      await browserExpect(state()).toContainText('"loading":null');
+      expect(pageErrors).toEqual([]);
+      await page.close();
+    } finally {
+      await browser.close();
+    }
+  }, 60_000);
+});

package/templates/.agents/dashboard/apps/frontend/src/use-app-trace-documents.ts

@@ -13,12 +13,14 @@ import type { DashboardApiClient } from "./dashboard-api.js";
 export function useAppTraceDocuments({
   api,
   operations,
+  isOperationsDetailLoaded,
   setError,
   setFailedArea,
   setLoadingArea,
 }: {
   api: DashboardApiClient;
   operations: OperationsProjection | null;
+  isOperationsDetailLoaded: () => boolean;
   setError: Dispatch<SetStateAction<string | null>>;
   setFailedArea: Dispatch<SetStateAction<LoadingArea | null>>;
   setLoadingArea: Dispatch<SetStateAction<LoadingArea | null>>;
@@ -34,16 +36,31 @@ export function useAppTraceDocuments({
   } | null>(null);
   const [traceLink, setTraceLink] = useState<
     | { kind: "change"; row: ChangeProjection }
-    | { kind: "macro"; label: "PRD" | "SPEC"; row: MacroProjection }
+    | {
+        kind: "macro";
+        label: "PRD" | "SPEC";
+        row: MacroProjection;
+        projection: OperationsProjection;
+      }
     | null
   >(null);
   const documentRequestId = useRef(0);
   const traceRequestId = useRef(0);
+  const macroRequestId = useRef(0);
+  const macroAbortController = useRef<AbortController | null>(null);
+  const [traceMacroLoading, setTraceMacroLoading] = useState<{
+    label: "PRD" | "SPEC";
+    id: string;
+  } | null>(null);
   const traceAbortController = useRef<AbortController | null>(null);
   const [traceLoadingTaskId, setTraceLoadingTaskId] = useState<string | null>(null);
   const [selectedTraceTaskId, setSelectedTraceTaskId] = useState("");
 
   async function openTrace(taskId: string) {
+    macroRequestId.current += 1;
+    macroAbortController.current?.abort();
+    setTraceMacroLoading(null);
+    setTraceLink(null);
     const requestId = ++traceRequestId.current;
     traceAbortController.current?.abort();
     const controller = new AbortController();
@@ -92,18 +109,58 @@ export function useAppTraceDocuments({
     setTraceLink({ kind: "change", row });
   }
 
-  function openTraceMacro(label: "PRD" | "SPEC", id: string) {
-    const rows = label === "PRD" ? operations?.prds : operations?.specs;
-    const row = rows?.find((macro) => macro.id === id);
-    if (row === undefined) return;
+  async function openTraceMacro(label: "PRD" | "SPEC", id: string) {
+    const requestId = ++macroRequestId.current;
+    macroAbortController.current?.abort();
+    macroAbortController.current = null;
+    traceRequestId.current += 1;
+    traceAbortController.current?.abort();
+    traceAbortController.current = null;
+    setTraceLoadingTaskId(null);
+    setLoadingArea((current) => (current === "traceability" ? null : current));
+    setError(null);
+    setFailedArea(null);
     setTrace(null);
-    setTraceLink({ kind: "macro", label, row });
+    setTraceLink(null);
+    const rows = label === "PRD" ? operations?.prds : operations?.specs;
+    const existing = rows?.find((macro) => macro.id === id && macro.kind === label.toLowerCase());
+    if (existing && operations && isOperationsDetailLoaded()) {
+      setTraceMacroLoading(null);
+      setTraceLink({ kind: "macro", label, row: existing, projection: operations });
+      return;
+    }
+    const controller = new AbortController();
+    macroAbortController.current = controller;
+    setTraceMacroLoading({ label, id });
+    try {
+      // The compact first fold has ranking IDs but omits macro and linked Task rows.
+      // Hydrate only after the user requests this traceability dialog.
+      const projection = await api.operations(undefined, "detail", controller.signal);
+      if (requestId !== macroRequestId.current || controller.signal.aborted) return;
+      const row = (label === "PRD" ? projection.prds : projection.specs).find(
+        (macro) => macro.id === id && macro.kind === label.toLowerCase(),
+      );
+      if (!row) throw new Error(`${label} ${id} not found`);
+      setTraceLink({ kind: "macro", label, row, projection });
+    } catch (cause) {
+      if (requestId !== macroRequestId.current || controller.signal.aborted) return;
+      setError(cause instanceof Error ? cause.message : String(cause));
+    } finally {
+      if (requestId === macroRequestId.current) {
+        if (macroAbortController.current === controller) macroAbortController.current = null;
+        setTraceMacroLoading(null);
+      }
+    }
   }
 
   async function openDocument(kind: "prd" | "spec", id: string) {
-    const preview = (kind === "prd" ? operations?.prds : operations?.specs)?.find(
-      (macro) => macro.id === id,
-    );
+    const preview =
+      (kind === "prd" ? operations?.prds : operations?.specs)?.find((macro) => macro.id === id) ??
+      (traceLink?.kind === "macro"
+        ? (kind === "prd" ? traceLink.projection.prds : traceLink.projection.specs).find(
+            (macro) => macro.id === id,
+          )
+        : undefined);
     if (!preview) return;
     const requestId = ++documentRequestId.current;
     const label = kind === "prd" ? "PRD" : "SPEC";
@@ -143,6 +200,7 @@ export function useAppTraceDocuments({
     setTraceTasks,
     trace,
     traceLink,
+    traceMacroLoading,
     traceLoadingTaskId,
     traceTasks,
   };

package/templates/.agents/dashboard/apps/frontend/src/use-dashboard-app-model.tsx

@@ -62,6 +62,7 @@ import { useAppTraceDocuments } from "./use-app-trace-documents.js";
 import { useAppTraceTaskPagination } from "./use-app-trace-task-pagination.js";
 import { useAppWorkBoard } from "./use-app-work-board.js";
 import { useAppWorkListPage } from "./use-app-work-list-page.js";
+import { useDashboardLocale } from "./use-dashboard-locale.js";
 import { useOperationsDetailExport } from "./use-operations-detail-export.js";
 import { useSnapshotNotice } from "./use-snapshot-notice.js";
 import "./loading-feedback.css";
@@ -103,18 +104,8 @@ export function useDashboardAppModel() {
     useState<OverviewClassificationPages>({});
   const [costs, setCosts] = useState<CostMonitorProjection | null>(null);
   const [displayedCosts, setDisplayedCosts] = useState<CostMonitorProjection | null>(null);
-  const [costLocale, setCostLocale] = useState<CostLocale>(savedLocale);
-  const [currency, setCurrency] = useState<CostCurrency>(() =>
-    window.localStorage.getItem(currencyKey) === "USD" ? "USD" : "BRL",
-  );
-  const currencyRef = useRef(currency);
-  currencyRef.current = currency;
-  // Language is the global selector's source of truth for the paired display
-  // currency, so Operations and Cost Monitor cannot diverge.
-  const changeDashboardLocale = useCallback((next: CostLocale) => {
-    setCostLocale(next);
-    setCurrency(next === "en-US" ? "USD" : "BRL");
-  }, []);
+  const { costLocale, currency, setCurrency, currencyRef, changeDashboardLocale } =
+    useDashboardLocale();
   const [operationsPeriod, setOperationsPeriod] = useState(() => defaultOperationsPeriod);
   // All Time may update its displayed factual range without changing the
   // unbounded request identity. Keep the refresh callback stable for that
@@ -174,6 +165,7 @@ export function useDashboardAppModel() {
       cancelled = true;
     };
   }, [api, applyDashboardIdentity]);
+  const operationsDetailLoadedRef = useRef(false);
   const {
     closeDocument,
     documentDetail,
@@ -181,6 +173,7 @@ export function useDashboardAppModel() {
     openTrace,
     openTraceChange,
     openTraceMacro,
+    traceMacroLoading,
     selectedTraceTaskId,
     setSelectedTraceTaskId,
     setTrace,
@@ -191,7 +184,14 @@ export function useDashboardAppModel() {
     traceLink,
     traceLoadingTaskId,
     traceTasks,
-  } = useAppTraceDocuments({ api, operations, setError, setFailedArea, setLoadingArea });
+  } = useAppTraceDocuments({
+    api,
+    operations,
+    isOperationsDetailLoaded: () => operationsDetailLoadedRef.current,
+    setError,
+    setFailedArea,
+    setLoadingArea,
+  });
   const { loadMoreTraceTasks, traceTasksHasMore, traceTasksLoading } = useAppTraceTaskPagination(
     api,
     traceTasks,
@@ -205,7 +205,6 @@ export function useDashboardAppModel() {
   const costSummaryRequestVersion = useRef(0);
   const costSummaryAbortRef = useRef<AbortController | null>(null);
   const costsLoadedRef = useRef(false);
-  const operationsDetailLoadedRef = useRef(false);
   const operationsDetailCancelRef = useRef<(() => void) | null>(null);
   const operationsDetailAbortRef = useRef<AbortController | null>(null);
   const operationsPageAbortRef = useRef<AbortController | null>(null);
@@ -571,7 +570,7 @@ export function useDashboardAppModel() {
         setLoadingArea((current) => (current === "costs" ? null : current));
       if (costSummaryAbortRef.current === controller) costSummaryAbortRef.current = null;
     }
-  }, [api, currency, operationsPeriod]);
+  }, [api, currency, operationsPeriod, currencyRef]);
 
   // The global language selector can request USD while Operations is active.
   // Acquire its coherent Cost Monitor snapshot here instead of requiring a
@@ -695,6 +694,7 @@ export function useDashboardAppModel() {
     openTraceChange,
     openTraceMacro,
     selectedTraceTaskId,
+    traceMacroLoading,
     trace,
     traceLoadingTaskId,
     traceTasksHasMore,

package/templates/.agents/dashboard/apps/frontend/src/use-dashboard-locale.ts

@@ -0,0 +1,18 @@
+import type { CostCurrency, CostLocale } from "@zaip-ai/dashboard-cost-monitor/react";
+import { useCallback, useRef, useState } from "react";
+import { currencyKey, savedLocale } from "./app-preferences.js";
+export function useDashboardLocale() {
+  const [costLocale, setCostLocale] = useState<CostLocale>(savedLocale);
+  const [currency, setCurrency] = useState<CostCurrency>(() =>
+    window.localStorage.getItem(currencyKey) === "USD" ? "USD" : "BRL",
+  );
+  const currencyRef = useRef(currency);
+  currencyRef.current = currency;
+  // Language is the global selector's source of truth for the paired display
+  // currency, so Operations and Cost Monitor cannot diverge.
+  const changeDashboardLocale = useCallback((next: CostLocale) => {
+    setCostLocale(next);
+    setCurrency(next === "en-US" ? "USD" : "BRL");
+  }, []);
+  return { costLocale, currency, setCurrency, currencyRef, changeDashboardLocale };
+}

package/templates/.agents/dashboard/modules/cost-monitor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaip-ai/dashboard-cost-monitor",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "private": true,
   "type": "module",
   "exports": {

package/templates/.agents/dashboard/modules/operations/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaip-ai/dashboard-operations",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "private": true,
   "type": "module",
   "exports": {

package/templates/.agents/dashboard/modules/operations/src/react/OperationsOverview.tsx

@@ -1,3 +1,4 @@
+import type { OperationsOverviewProps } from "./operations-overview-contract.js";
 import { formatSummaryMetricValue, unmeasuredZeroDescription } from "./overview-metric-format.js";
 import { overviewMetricStats } from "./overview-metric-stats.js";
 
@@ -94,6 +95,7 @@ export function OperationsOverview({
   onDatePresetChange,
   onOpenTask,
   onOpenDocument,
+  onOpenMacro,
   onLoadStatus,
   statusPage,
   onLoadStatusPage,
@@ -109,45 +111,7 @@ export function OperationsOverview({
   costLoading = false,
   resolveRunCost,
   includeLegacyEffort: _includeLegacyEffort = false,
-}: {
-  currency: "BRL" | "USD";
-  data: OperationsProjection;
-  /** App-controlled range paired with datePreset; retained by Page while loading. */
-  dateRange?: OperationDateRange;
-  datePreset: OperationDatePreset;
-  locale: OperationsLocale;
-  onDatePresetChange: (preset: OperationDatePreset) => void;
-  onOpenTask: (taskId: string) => Promise<boolean>;
-  onOpenDocument: (kind: "prd" | "spec", id: string) => void;
-  onLoadStatus?: ((stage: WorkStage, kind: OverviewStatusKind, offset: number) => void) | undefined;
-  statusPage?:
-    | ((stage: WorkStage, kind: OverviewStatusKind) => OverviewStatusPage | undefined)
-    | undefined;
-  onLoadStatusPage?:
-    | ((stage: WorkStage, kind: OverviewStatusKind, offset: number) => void)
-    | undefined;
-  classificationPage?:
-    | ((
-        kind: OverviewStatusKind,
-        classification: OverviewClassification,
-      ) => OverviewClassificationPage | undefined)
-    | undefined;
-  onLoadClassificationPage?:
-    | ((kind: OverviewStatusKind, classification: OverviewClassification, offset: number) => void)
-    | undefined;
-  onLoadMacroMetrics?: (() => void) | undefined;
-  prds?: OperationsProjection["prds"];
-  runs?: OperationsProjection["runs"];
-  specs?: OperationsProjection["specs"];
-  tasks?: OperationsProjection["tasks"];
-  /** Factual Cost Monitor snapshot total for the selected locale/currency. */
-  factualCostTotal?: number | null | undefined;
-  /** Measurement completeness for the matching Cost Monitor snapshot. */
-  factualCostFact?: FactualCostFact | undefined;
-  costLoading?: boolean | undefined;
-  resolveRunCost?: ((runId: string) => number | null) | undefined;
-  includeLegacyEffort?: boolean;
-}) {
+}: OperationsOverviewProps) {
   const [overviewView, setOverviewView] = useState<OverviewView>("tasks");
   const [selectedStatus, setSelectedStatus] = useState<WorkStage | null>(null);
   const [selectedClassification, setSelectedClassification] =
@@ -687,6 +651,7 @@ export function OperationsOverview({
           currency={currency}
           locale={locale}
           maxDuration={maxDuration}
+          onOpenMacro={onOpenMacro}
           onOpenTask={onOpenTask}
           summary={topEntitiesSummary}
           text={text}

package/templates/.agents/dashboard/modules/operations/src/react/OperationsOverviewTopPanel.navigation.test.tsx

@@ -0,0 +1,150 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import type { Browser } from "@playwright/test";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+declare global {
+  interface Window {
+    __topFiveNavigationProbe: {
+      tasks: string[];
+      documents: { kind: "prd" | "spec"; id: string }[];
+    };
+  }
+}
+
+const browserRequire = createRequire(
+  fileURLToPath(new URL("../../../../tests/e2e/package.json", import.meta.url)),
+);
+const { chromium, expect: expectPlaywright } = browserRequire("@playwright/test");
+
+describe("Operations Top 5 navigation", () => {
+  let browser: Browser;
+  let bundle: string;
+
+  beforeAll(async () => {
+    const esbuild = browserRequire("esbuild");
+    const harness = await esbuild.build({
+      bundle: true,
+      define: { "import.meta.url": '"http://localhost/"' },
+      format: "iife",
+      loader: { ".css": "text" },
+      logLevel: "silent",
+      platform: "browser",
+      alias: {
+        "@zaip-ai/dashboard-ui": fileURLToPath(
+          new URL("../../../../packages/ui/src/index.ts", import.meta.url),
+        ),
+        react: fileURLToPath(
+          new URL(
+            "../../../../../../node_modules/.pnpm/react@19.2.7/node_modules/react",
+            import.meta.url,
+          ),
+        ),
+        "react-dom": fileURLToPath(
+          new URL(
+            "../../../../../../node_modules/.pnpm/react-dom@19.2.7_react@19.2.7/node_modules/react-dom",
+            import.meta.url,
+          ),
+        ),
+      },
+      stdin: {
+        contents: `
+          import React, { useState } from "react";
+          import { createRoot } from "react-dom/client";
+          import { OperationsOverviewTopPanel } from "./OperationsOverviewTopPanel.js";
+
+          const entities = {
+            tasks: [
+              { id: "TASK-TRACE-FIRST", title: "First task", durationMs: 120000, tokens: 1, costBrl: 1, runCount: 1 },
+              { id: "TASK-TRACE-SECOND", title: "Second task", durationMs: 60000, tokens: 1, costBrl: 1, runCount: 1 },
+            ],
+            specs: [
+              { id: "SPEC-TRACE-FIRST", title: "First spec", durationMs: 120000, tokens: 1, costBrl: 1, runCount: 1 },
+              { id: "SPEC-TRACE-SECOND", title: "Second spec", durationMs: 60000, tokens: 1, costBrl: 1, runCount: 1 },
+            ],
+            prds: [
+              { id: "PRD-TRACE-FIRST", title: "First prd", durationMs: 120000, tokens: 1, costBrl: 1, runCount: 1 },
+              { id: "PRD-TRACE-SECOND", title: "Second prd", durationMs: 60000, tokens: 1, costBrl: 1, runCount: 1 },
+            ],
+          };
+          const probe = { tasks: [], documents: [] };
+          window.__topFiveNavigationProbe = probe;
+
+          function Harness() {
+            const [view, setView] = useState("tasks");
+            return <>
+              <nav aria-label="Overview mode">
+                {Object.keys(entities).map((mode) => <button key={mode} type="button" onClick={() => setView(mode)}>{mode}</button>)}
+              </nav>
+              <OperationsOverviewTopPanel
+                copy={{ empty: "Empty", hint: "Duration", title: "Top 5" }}
+                currency="BRL" locale="en-US" maxDuration={120000}
+                onOpenTask={async (id) => { probe.tasks.push(id); return true; }}
+                onOpenMacro={(kind, id) => probe.documents.push({ kind, id })}
+                summary={{ durationMs: 180000, durationShare: 1, runCount: 2, tokens: 2 }}
+                text={{ accumulatedTime: "Time", associatedRuns: "runs", concentration: "Concentration", totalMeasuredTime: "Total", topFiveCost: "Cost", tokensUnavailable: "Unavailable" }}
+                topCost={2} topEntities={entities[view]} view={view}
+              />
+            </>;
+          }
+          createRoot(document.getElementById("root")).render(<Harness />);
+        `,
+        loader: "tsx",
+        resolveDir: fileURLToPath(new URL(".", import.meta.url)),
+        sourcefile: "OperationsOverviewTopPanel.navigation-harness.tsx",
+      },
+      write: false,
+    });
+    bundle = harness.outputFiles[0].text;
+    browser = await chromium.launch({ headless: true });
+  }, 60_000);
+
+  afterAll(async () => {
+    await browser?.close();
+  }, 60_000);
+
+  it("opens the selected Task, SPEC, and PRD after switching modes by mouse and keyboard", async () => {
+    const page = await browser.newPage();
+    const pageErrors: string[] = [];
+    page.on("pageerror", (error) => pageErrors.push(error.message));
+    try {
+      await page.setContent('<div id="root"></div>');
+      await page.addScriptTag({ content: bundle });
+      await expectPlaywright(page.locator(".operations-run-bar")).toHaveCount(2);
+
+      await page.getByRole("button", { name: /Open task details for Second task/ }).click();
+      await page
+        .getByRole("navigation", { name: "Overview mode" })
+        .getByRole("button", { name: "specs" })
+        .click();
+      const spec = page.getByRole("button", { name: /Open details for SPEC First spec/ });
+      await expectPlaywright(spec).toBeEnabled();
+      await spec.focus();
+      await page.keyboard.press("Enter");
+      await page
+        .getByRole("navigation", { name: "Overview mode" })
+        .getByRole("button", { name: "prds" })
+        .click();
+      const prd = page.getByRole("button", { name: /Open details for PRD Second prd/ });
+      await expectPlaywright(prd).toBeEnabled();
+      await prd.focus();
+      await page.keyboard.press("Space");
+      await page
+        .getByRole("navigation", { name: "Overview mode" })
+        .getByRole("button", { name: "tasks" })
+        .click();
+      await page.getByRole("button", { name: /Open task details for First task/ }).click();
+
+      expect(await page.evaluate(() => window.__topFiveNavigationProbe)).toEqual({
+        tasks: ["TASK-TRACE-SECOND", "TASK-TRACE-FIRST"],
+        documents: [
+          { kind: "spec", id: "SPEC-TRACE-FIRST" },
+          { kind: "prd", id: "PRD-TRACE-SECOND" },
+        ],
+      });
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await page.close();
+    }
+  }, 60_000);
+});

package/templates/.agents/dashboard/modules/operations/src/react/OperationsOverviewTopPanel.tsx

@@ -18,6 +18,7 @@ export function OperationsOverviewTopPanel({
   currency,
   locale,
   maxDuration,
+  onOpenMacro,
   onOpenTask,
   summary,
   text,
@@ -30,6 +31,7 @@ export function OperationsOverviewTopPanel({
   currency: "BRL" | "USD";
   locale: OperationsLocale;
   maxDuration: number;
+  onOpenMacro: (kind: "prd" | "spec", id: string) => void;
   onOpenTask: (taskId: string) => Promise<boolean>;
   summary: {
     durationMs: number | null;
@@ -68,14 +70,16 @@ export function OperationsOverviewTopPanel({
               const label =
                 view === "tasks"
                   ? `${locale === "pt-BR" ? "Abrir detalhes da tarefa" : "Open task details for"} ${entity.title}: ${measuredDuration}`
-                  : `${entityKind} ${entity.title}: ${measuredDuration}`;
+                  : `${locale === "pt-BR" ? "Abrir detalhes da" : "Open details for"} ${entityKind} ${entity.title}: ${measuredDuration}`;
               return (
                 <button
                   aria-label={label}
                   className={`operations-run-bar${entity.durationMs === null ? " is-duration-unavailable" : ""}`}
-                  disabled={view !== "tasks"}
                   key={entity.id}
-                  onClick={() => void onOpenTask(entity.id)}
+                  onClick={() => {
+                    if (view === "tasks") void onOpenTask(entity.id);
+                    else onOpenMacro(view === "specs" ? "spec" : "prd", entity.id);
+                  }}
                   title={`${entity.title}: ${measuredDuration}`}
                   type="button"
                 >

package/templates/.agents/dashboard/modules/operations/src/react/OperationsPage.tsx

@@ -20,6 +20,7 @@ import {
   workListTypeOnViewChange,
 } from "./operations-page-contract.js";
 import { useOperationFilterFeedback } from "./use-operation-filter-feedback.js";
+import { useOperationsDefaultRange } from "./use-operations-default-range.js";
 import { useOperationsFilterSync } from "./use-operations-filter-sync.js";
 
 export {
@@ -86,6 +87,7 @@ export function OperationsPage({
   locale,
   onLocaleChange,
   onOpenDocument,
+  onOpenMacro,
   onOpenTask,
   onPriorityChange,
   onLoadMacroMetrics,
@@ -125,13 +127,7 @@ export function OperationsPage({
   const [originFilter, setOriginFilter] = useState<TaskOrigin | "">("");
   const { filterLoading, showFilterLoading } = useOperationFilterFeedback();
   const searchInputRef = useRef<HTMLInputElement>(null);
-  const defaultDateRange = useMemo(() => {
-    const operationsRange = initialOperationsDateRange(
-      data.tasks,
-      Object.keys(data.summary.periods?.daily ?? {}),
-    );
-    return factualCostDateRange(factualCostPeriods?.day, operationsRange);
-  }, [data.summary.periods, data.tasks, factualCostPeriods?.day]);
+  const defaultDateRange = useOperationsDefaultRange(data, factualCostPeriods);
   const initialDateRange = useMemo(() => dateRangeForPreset("this-month"), []);
   const [localDateRange, setLocalDateRange] = useState(() => initialDateRange);
   const [localDatePreset, setLocalDatePreset] = useState<OperationDatePreset>("all");
@@ -633,6 +629,7 @@ export function OperationsPage({
               locale={locale}
               onOpenTask={onOpenTask}
               onOpenDocument={onOpenDocument}
+              onOpenMacro={onOpenMacro}
               onLoadStatus={onLoadStatusPage}
               prds={prds}
               query={query}