@stigmer/react 3.3.0 → 3.4.1

package/src/test/__tests__/samples.test.ts

@@ -1,7 +1,9 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
 import { ExecutionPhase, MessageType, ToolCallStatus, ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
-import { samples } from "../samples";
+import { formatDuration } from "../../execution/ToolCallDetail";
+import { samples, SAMPLE_INSTANT, sampleInstant, sampleDate } from "../samples";
 
 describe("samples", () => {
   describe("session", () => {
@@ -169,3 +171,158 @@ describe("samples", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Determinism — the reason these factories exist. A `samples.*` value is
+// rendered into Scenar tours that replay in the browser and export to video
+// frame by frame, so any live-clock read paints a pixel that changes between
+// runs (scenar-cloud DD-006). These tests are the regression lock: each one
+// FAILS if a factory is reverted to reading the clock.
+// ---------------------------------------------------------------------------
+
+describe("samples determinism", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  // A zero-arg call for every factory, with representative arguments. The
+  // completeness test below asserts this map covers `samples` exactly, so a
+  // newly-added factory that reads the clock cannot slip past the stability
+  // sweep unnoticed.
+  const invoke: Record<keyof typeof samples, () => unknown> = {
+    session: () => samples.session(),
+    agent: () => samples.agent(),
+    agentExecution: () => samples.agentExecution(),
+    skill: () => samples.skill(),
+    mcpServer: () => samples.mcpServer(),
+    environment: () => samples.environment(),
+    agentInstance: () => samples.agentInstance(),
+    apiKey: () => samples.apiKey(),
+    humanMessage: () => samples.humanMessage("hello"),
+    aiMessage: () => samples.aiMessage("hi"),
+    toolCall: () => samples.toolCall("lookup_order", '{"orderId":"123"}'),
+    artifact: () => samples.artifact("report.md"),
+    sessionList: () => samples.sessionList(),
+    agentExecutionList: () => samples.agentExecutionList(),
+    searchResponse: () => samples.searchResponse(),
+    apiKeyList: () => samples.apiKeyList(),
+    searchResult: () => samples.searchResult(),
+  };
+
+  it("the stability sweep covers every factory", () => {
+    expect(Object.keys(invoke).sort()).toEqual(Object.keys(samples).sort());
+  });
+
+  // Two calls under system clocks a full calendar day apart must produce
+  // identical objects. The day boundary is deliberate: it is what reproduces
+  // the `apiKey` bug (a `createdAt` date that changed daily) and the message
+  // and tool-call timestamp drift, none of which a same-millisecond back-to-
+  // back call would expose.
+  it.each(Object.keys(invoke) as (keyof typeof samples)[])(
+    "%s is identical across a day boundary",
+    (name) => {
+      vi.useFakeTimers();
+
+      vi.setSystemTime(new Date("2026-03-01T08:15:00Z"));
+      const first = invoke[name]();
+
+      vi.setSystemTime(new Date("2026-03-02T21:45:30Z"));
+      const second = invoke[name]();
+
+      expect(second).toEqual(first);
+    },
+  );
+
+  it("stamps the frozen instant on every timestamped primitive", () => {
+    expect(samples.humanMessage("x").timestamp).toBe(SAMPLE_INSTANT);
+    expect(samples.aiMessage("x").timestamp).toBe(SAMPLE_INSTANT);
+    expect(samples.artifact("x").createdAt).toBe(SAMPLE_INSTANT);
+    expect(samples.toolCall("x", "y").startedAt).toBe(SAMPLE_INSTANT);
+
+    const createdAt = samples.apiKey().status?.audit?.specAudit?.createdAt;
+    expect(createdAt).toBeDefined();
+    expect(timestampDate(createdAt!).toISOString()).toBe(SAMPLE_INSTANT);
+  });
+
+  it("renders a stable duration chip rather than the old 0ms flake", () => {
+    const tc = samples.toolCall("lookup_order", "{}");
+    expect(formatDuration(tc.startedAt, tc.completedAt)).toBe("1.2s");
+  });
+
+  it("derives a clock-free tool-call id from the name", () => {
+    expect(samples.toolCall("process_return", "{}").id).toBe("tc-process_return");
+  });
+
+  it("honors an ApiKeyOverrides.createdAt override", () => {
+    const frozen = "2026-01-02T03:04:05.000Z";
+    const key = samples.apiKey({ createdAt: frozen });
+    const createdAt = key.status?.audit?.specAudit?.createdAt;
+    expect(timestampDate(createdAt!).toISOString()).toBe(frozen);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The reader offset window — why SAMPLE_INSTANT is 11:00 UTC. Components
+// format dates in the reader's local time, and real UTC offsets span −11:00
+// to +14:00 (25 hours against a 24-hour day), so no instant renders one
+// calendar date everywhere. The supported window is UTC−11:00 (Midway)
+// through UTC+12:45 (Chatham, southern winter): every inhabited zone except
+// Tongatapu (+13) and Kiritimati (+14). Local date is monotonic in offset,
+// so agreement at the two boundaries proves agreement throughout.
+//
+// `scripts/verify-scenar-tours.mjs` exports the same boundaries as
+// READER_OFFSET_WINDOW (its own test locks those values); this suite locks
+// the anchor's side of the contract.
+// ---------------------------------------------------------------------------
+
+describe("SAMPLE_INSTANT reader offset window", () => {
+  const WEST_OFFSET_MINUTES = -11 * 60; // UTC−11:00, Midway
+  const EAST_OFFSET_MINUTES = 12 * 60 + 45; // UTC+12:45, Chatham (Jul)
+
+  /** Calendar date (YYYY-MM-DD) the instant renders at a fixed UTC offset. */
+  const localDateAtOffset = (iso: string, offsetMinutes: number): string =>
+    new Date(Date.parse(iso) + offsetMinutes * 60_000).toISOString().slice(0, 10);
+
+  it("renders one calendar date at both window boundaries", () => {
+    const west = localDateAtOffset(SAMPLE_INSTANT, WEST_OFFSET_MINUTES);
+    const east = localDateAtOffset(SAMPLE_INSTANT, EAST_OFFSET_MINUTES);
+    expect(west).toBe("2026-07-20");
+    expect(east).toBe("2026-07-20");
+  });
+
+  // The two anchors this one replaced, kept as negative cases so nobody
+  // "corrects" the constant back: 09:30Z was the original tour-world instant
+  // (read Jul 19 in Honolulu); noon was SAMPLE_INSTANT's first value and the
+  // once-planned fix (read Jul 21 in Auckland, Fiji, and Chatham).
+  it.each([
+    ["2026-07-20T09:30:00.000Z", "drifts at the west boundary"],
+    ["2026-07-20T12:00:00.000Z", "drifts at the east boundary"],
+  ])("rejected anchor %s %s", (iso) => {
+    expect(localDateAtOffset(iso, WEST_OFFSET_MINUTES)).not.toBe(
+      localDateAtOffset(iso, EAST_OFFSET_MINUTES),
+    );
+  });
+});
+
+describe("sampleInstant / sampleDate derivation", () => {
+  it("sampleInstant with no delta is the anchor itself", () => {
+    expect(sampleInstant()).toBe(SAMPLE_INSTANT);
+  });
+
+  it("applies positive and negative deltas exactly", () => {
+    expect(sampleInstant(2_400)).toBe("2026-07-20T11:00:02.400Z");
+    expect(sampleInstant(-86_400_000)).toBe("2026-07-19T11:00:00.000Z");
+  });
+
+  it("sampleDate agrees with sampleInstant at every delta", () => {
+    for (const deltaMs of [0, 1_200, 2_400, -3_600_000, 86_400_000]) {
+      expect(sampleDate(deltaMs).toISOString()).toBe(sampleInstant(deltaMs));
+    }
+  });
+
+  it("the default toolCall span derives from the anchor", () => {
+    const tc = samples.toolCall("lookup_order", "{}");
+    expect(tc.startedAt).toBe(sampleInstant());
+    expect(tc.completedAt).toBe(sampleInstant(1_200));
+  });
+});

package/src/test/index.ts

@@ -3,4 +3,4 @@
 // Provides domain-specific data builders for unit tests, Storybook,
 // Playwright, and Scenar preview scenarios.
 
-export { samples } from "./samples.js";
+export { samples, SAMPLE_INSTANT, sampleInstant, sampleDate } from "./samples.js";

package/src/test/samples.ts

@@ -1,4 +1,5 @@
 import { create } from "@bufbuild/protobuf";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
 import { AgentSchema, type Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import { AgentSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import {
@@ -75,6 +76,77 @@ import {
   type SearchResult,
 } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
 
+// ---------------------------------------------------------------------------
+// The frozen instant
+// ---------------------------------------------------------------------------
+
+/**
+ * The frozen instant every timestamped `samples.*` factory defaults to — the
+ * tour world's single clock. Anything in a demo that needs an instant derives
+ * from this one via {@link sampleInstant} / {@link sampleDate}; nothing
+ * authors a second instant of its own (`scripts/verify-scenar-tours.mjs`
+ * enforces that under `demos/tours/`).
+ *
+ * These factories must never read the live clock. A `samples.*` value is
+ * rendered into Scenar tours that replay in the browser and export to video
+ * frame by frame; a clock read paints a pixel that changes between runs, which
+ * breaks the "same source, same result" guarantee (scenar-cloud DD-006).
+ *
+ * The date is `2026-07-20`, the tour world's demo day. The time is 11:00 UTC,
+ * chosen by the *reader offset window*: components format dates in the
+ * reader's local time (e.g. `ApiKeyListPanel` via `toLocaleDateString`), and
+ * real UTC offsets span −11:00 (Midway) to +14:00 (Kiritimati) — a 25-hour
+ * range against a 24-hour day, so **no instant renders one calendar date
+ * everywhere**. The supported window is UTC−11:00 through UTC+12:45 — every
+ * inhabited zone except Tongatapu (+13, ~100k) and Kiritimati (+14, ~6k).
+ * 11:00Z holds `Jul 20` across that whole window; the previous noon anchor
+ * flipped to `Jul 21` at UTC+12:45 and beyond (Auckland, Fiji, Chatham).
+ * Instants whose calendar *date* is rendered must stay inside the window's
+ * stable band, 11:00:00Z–11:14:59Z — the anchor sits at its start so all
+ * derivation headroom points forward. Duration deltas (end minus start) are
+ * zone-invariant and may leave the band freely.
+ *
+ * The window stabilises the rendered *date*, not the rendered *string*:
+ * locale-unpinned formatters still vary the format per reader ("Jul 20, 2026"
+ * vs "20 Jul 2026"), and a component that renders a *time of day* is
+ * zone-dependent no matter which instant is chosen. The property test in
+ * `__tests__/samples.test.ts` locks the date-stability claim at both window
+ * boundaries.
+ */
+export const SAMPLE_INSTANT = "2026-07-20T11:00:00.000Z";
+
+/** {@link SAMPLE_INSTANT} in epoch milliseconds, the base all derivation uses. */
+const SAMPLE_INSTANT_MS = Date.parse(SAMPLE_INSTANT);
+
+/**
+ * An ISO-8601 instant `deltaMs` after {@link SAMPLE_INSTANT} — the way a
+ * fixture expresses "2.4 seconds later" or "a day earlier" without authoring
+ * a second instant. `sampleInstant()` with no argument is the anchor itself.
+ *
+ * Prefer this over a hand-written literal even for values that never render:
+ * derivation keeps the whole fixture world moving together if the demo day is
+ * ever refreshed, and the tour gate rejects authored instant literals anyway.
+ */
+export function sampleInstant(deltaMs = 0): string {
+  return new Date(SAMPLE_INSTANT_MS + deltaMs).toISOString();
+}
+
+/**
+ * {@link sampleInstant} as a `Date`, for APIs that take one (e.g. protobuf's
+ * `timestampFromDate`). Same instant, same derivation rule.
+ */
+export function sampleDate(deltaMs = 0): Date {
+  return new Date(SAMPLE_INSTANT_MS + deltaMs);
+}
+
+/**
+ * When a default {@link samples.toolCall} completes: {@link SAMPLE_INSTANT}
+ * plus 1.2s, so the rendered duration chip reads a stable "1.2s" — long
+ * enough to never collapse to the "0ms" that two adjacent live clock reads
+ * used to produce.
+ */
+const SAMPLE_TOOL_CALL_COMPLETED_AT = sampleInstant(1_200);
+
 // ---------------------------------------------------------------------------
 // Override interfaces — flat projections of commonly-customized fields
 // ---------------------------------------------------------------------------
@@ -145,6 +217,8 @@ export interface ApiKeyOverrides {
   readonly fingerprint?: string;
   readonly neverExpires?: boolean;
   readonly keyHash?: string;
+  /** Frozen ISO-8601 instant for the key's `createdAt`. Defaults to {@link SAMPLE_INSTANT}. */
+  readonly createdAt?: string;
 }
 
 export interface SearchResultOverrides {
@@ -166,17 +240,30 @@ export interface SearchResultOverrides {
  *
  * Each factory returns a realistic protobuf object with sensible defaults.
  * Pass an overrides object to customize the most commonly-needed fields.
- * For deeper customization, modify the returned object directly — protobuf
- * messages from `create()` are mutable plain objects.
+ *
+ * Every timestamp is frozen at {@link SAMPLE_INSTANT} — these factories never
+ * read the live clock, so a fixture renders identical pixels on every browser
+ * replay and every video-export frame (scenar-cloud DD-006). Do not
+ * reintroduce `Date.now()` or `new Date()` here.
+ *
+ * For a value the overrides do not cover — a different timestamp, a distinct
+ * tool-call id — modify the returned object directly rather than growing the
+ * override surface: protobuf messages from `create()` are mutable plain
+ * objects. Timestamps derive from the anchor via {@link sampleInstant} rather
+ * than a hand-written literal, so the fixture world keeps a single clock.
  *
  * @example
  * ```ts
- * import { samples } from "@stigmer/react/test";
+ * import { samples, sampleInstant } from "@stigmer/react/test";
  *
  * const scenario = buildScenario(
  *   fixtures.session.get(() => samples.session({ subject: "My topic" })),
  *   fixtures.agent.getByReference(() => samples.agent({ name: "My Agent" })),
  * );
+ *
+ * // Deeper customization — derive "5 seconds later" from the anchor:
+ * const later = samples.humanMessage("later");
+ * later.timestamp = sampleInstant(5_000);
  * ```
  */
 export const samples = {
@@ -363,7 +450,7 @@ export const samples = {
       status: create(ApiKeyStatusSchema, {
         audit: create(ApiResourceAuditSchema, {
           specAudit: create(ApiResourceAuditInfoSchema, {
-            createdAt: { seconds: BigInt(Math.floor(Date.now() / 1000)), nanos: 0 },
+            createdAt: timestampFromDate(new Date(o?.createdAt ?? SAMPLE_INSTANT)),
           }),
         }),
       }),
@@ -372,44 +459,52 @@ export const samples = {
 
   // ---- Message & artifact primitives ----
 
-  /** A human (user) message. */
+  /** A human (user) message, stamped at {@link SAMPLE_INSTANT}. */
   humanMessage(content: string): AgentMessage {
     return create(AgentMessageSchema, {
       type: MessageType.MESSAGE_HUMAN,
       content,
-      timestamp: new Date().toISOString(),
+      timestamp: SAMPLE_INSTANT,
     });
   },
 
-  /** An AI (assistant) message, optionally with tool calls. */
+  /** An AI (assistant) message, optionally with tool calls, stamped at {@link SAMPLE_INSTANT}. */
   aiMessage(content: string, toolCalls?: ToolCall[]): AgentMessage {
     return create(AgentMessageSchema, {
       type: MessageType.MESSAGE_AI,
       content,
-      timestamp: new Date().toISOString(),
+      timestamp: SAMPLE_INSTANT,
       toolCalls: toolCalls ?? [],
     });
   },
 
-  /** A completed tool call with a result. */
+  /**
+   * A completed tool call with a result, spanning {@link SAMPLE_INSTANT} to 1.2s
+   * later so its duration chip reads a stable "1.2s".
+   *
+   * The `id` is `tc-${name}`, derived from the name so it is stable across
+   * runs. Two tool calls sharing a name therefore share an id — if a single
+   * demo renders both and one drives an approval (`useApproval(toolCall.id)`),
+   * build the second by hand with a distinct id via `create(ToolCallSchema)`.
+   */
   toolCall(name: string, result: string): ToolCall {
     return create(ToolCallSchema, {
-      id: `tc-${name}-${Date.now()}`,
+      id: `tc-${name}`,
       name,
       result,
       status: ToolCallStatus.TOOL_CALL_COMPLETED,
-      startedAt: new Date().toISOString(),
-      completedAt: new Date().toISOString(),
+      startedAt: SAMPLE_INSTANT,
+      completedAt: SAMPLE_TOOL_CALL_COMPLETED_AT,
     });
   },
 
-  /** A file artifact produced by an execution. */
+  /** A file artifact produced by an execution, stamped at {@link SAMPLE_INSTANT}. */
   artifact(name: string, kind?: ExecutionArtifactKind): ExecutionArtifact {
     return create(ExecutionArtifactSchema, {
       name,
       kind: kind ?? ExecutionArtifactKind.FILE,
       storageKey: `demo-artifact-${name}`,
-      createdAt: new Date().toISOString(),
+      createdAt: SAMPLE_INSTANT,
     });
   },
 

package/src/workflow/useWorkflowCount.ts

@@ -17,6 +17,8 @@ export interface UseWorkflowCountOptions {
    * @default "org"
    */
   readonly scope?: ResourceListScope;
+  /** Opaque token that forces a recount when its value changes. */
+  readonly refetchToken?: unknown;
 }
 
 /** Return value of {@link useWorkflowCount}. */