@genesislcap/ai-assistant 15.26.0 → 15.27.0

package/sandbox/README.md

@@ -30,8 +30,8 @@ The panel covers, roughly in the order you'll want them:
 | **Session menu (⋮)** | Whether a persistence provider is configured (the menu is gated on one) and `showSessionMenu`; a button to open the menu |
 | **Context window** | **Jump to state** (the four gate states in one click), the simulated window and fill, `chatConfig.context`, a flow-in-progress toggle, live readouts of the gate / thresholds / compaction plan, and Compact |
 | **Simulated state** | Forces `idle` / busy / cancelling / blocked / compacting / restoring onto the element |
-| **Transcript** | Seeds an empty, short, tool-and-markdown-heavy, 28-turn, ~20k-token, or ~22k-token tool-loop conversation |
-| **Chrome** | Header title, popout mode, suggestions, the tool-call / reasoning / narration toggles, animations |
+| **Transcript** | Seeds an empty, short, tool-and-markdown-heavy, 28-turn, ~20k-token, or ~22k-token tool-loop conversation, and how far back to shift its timestamps |
+| **Chrome** | Header title, popout mode, suggestions, the tool-call / reasoning / narration toggles, the timestamp mode, animations |
 | **Stage** | Frame size (floored at 400px — see below), light/dark, remount, full reset |
 
 Panel state persists in `localStorage`, so a reload picks up where you left off. **Reset sandbox**
@@ -122,6 +122,49 @@ A run worth doing:
 far above `block` on purpose: the reserve exists so an accepted turn can spend it, and a guard at
 the block line would kill every turn that used the headroom it was given.
 
+## Checking message timestamps (GENC-1257)
+
+Each message can show when it was sent, beside the sender name. **Timestamps** in the Chrome
+group and the cog's own picker both drive the same three modes, and whichever you moved last
+wins. Moving any *other* panel control will not disturb a choice made in the cog.
+
+The panel control writes `chatConfig.ui.showTimestamps` **and** the element's
+`timestampDisplay` property. That second write is what makes it work, and is worth knowing
+about before you add a control of your own: `chatConfig.ui` is read only while the store is
+fresh and the user has changed nothing (`applyPreferenceBaseline`), so the moment the cog is
+touched — or a stored preference exists — a config change is correctly ignored. That is right
+for a real host, where a user's choice should outrank a host default, and useless for a
+harness control, which has to win.
+
+Show tool calls / reasoning / narration work the same way, through the same
+`DIRECT_PREFERENCE_WRITERS` table in `sandbox.ts` — add an entry there for any new panel
+control that drives a user preference, or it will quietly stop responding the first time
+anyone opens the cog. **Animations is deliberately not in that table**: it is a feature gate
+rather than a display preference (unsetting it removes the cog control altogether), and it has
+no single element property to mirror onto.
+
+- **On hover** (the default) — hidden until the pointer is over that message row. The space is
+  still reserved, so a reveal never reflows the bubble under the cursor.
+- **Always** — permanently visible.
+- **Off** — not rendered, and therefore absent from the accessibility tree too.
+
+`opacity: 0` hides from paint but not from the accessibility tree, and assistive tech has no
+hover, so in **both** visible modes a screen reader announces a timestamp on every message.
+It hears the absolute date+time, carried in a visually-hidden span with the relative text
+`aria-hidden` — a `<time>` element has no implicit ARIA role, so its `datetime` attribute is
+never announced and cannot serve as the accessible value.
+
+The display has three tiers — "Now" under a minute, "12 minutes ago" under an hour, and a full
+date beyond that. **Age** in the Transcript group is what makes the third reachable: the
+fixtures stamp their turns a minute apart ending "now", so a seeded conversation spans minutes
+and would never cross the hour boundary on its own. Shifting the whole seed back 3 hours or 3
+days is the only way to see the absolute tier without inventing a fixture nobody else needs.
+
+The relative labels are recomputed on a 30s tick rather than at render, because FAST evaluates
+a binding once and an idle conversation never re-renders — without it "2 minutes ago" would
+still read "2 minutes ago" an hour later. The ticker only runs while the element is connected
+and the mode is not `off`.
+
 ## 400px is the narrowest supported width
 
 The stage will not go below it — slider, drag handle and a restored panel state are all clamped —

package/sandbox/sandbox.ts

@@ -3,7 +3,7 @@
  * no backend, so the template, styling and responsive behaviour can be worked on
  * directly. See `sandbox/README.md`.
  */
-import type { ChatConfig } from '@genesislcap/foundation-ai';
+import type { ChatConfig, TimestampDisplay } from '@genesislcap/foundation-ai';
 import { registerAIProviders } from '@genesislcap/foundation-ai';
 import { baseLayerLuminance, registerRapidDesignSystem } from '@genesislcap/rapid-design-system';
 import { DI } from '@genesislcap/web-core';
@@ -135,6 +135,7 @@ interface SandboxState {
   showToolCalls: boolean;
   showThinkingSteps: boolean;
   showNarration: boolean;
+  showTimestamps: TimestampDisplay;
   animations: boolean;
   // Context window (GENC-1567)
   contextPreset: ContextPresetName | typeof CUSTOM_PRESET;
@@ -148,6 +149,7 @@ interface SandboxState {
   // Simulated runtime
   runtime: 'idle' | 'loading' | 'cancelling' | 'blocked' | 'compacting' | 'restoring';
   transcript: TranscriptName;
+  transcriptAge: TranscriptAge;
   // Stage
   width: number;
   height: number;
@@ -176,6 +178,7 @@ const DEFAULT_STATE: SandboxState = {
   showToolCalls: true,
   showThinkingSteps: true,
   showNarration: true,
+  showTimestamps: 'hover',
   animations: true,
   // Chosen so the `huge` (~20k) and `loop` (~22k) seeds actually clear the tail
   // budget these produce (~12.8k) and so have something to compact. Verified, not
@@ -191,6 +194,7 @@ const DEFAULT_STATE: SandboxState = {
   flowInProgress: false,
   runtime: 'idle',
   transcript: 'rich',
+  transcriptAge: 'fresh',
   width: 480,
   height: 760,
   theme: 'dark',
@@ -254,13 +258,41 @@ let assistant!: FoundationAiAssistant;
  */
 let lastSeed = '';
 
+/**
+ * How far back the whole seeded transcript is shifted (GENC-1257).
+ *
+ * The fixtures stamp their turns a minute apart ending "now", which exercises the
+ * "Now" and "N minutes ago" tiers but can never reach the absolute one — an hour of
+ * transcript would take sixty turns. Shifting the entire seed backwards is the only
+ * way to see the third tier without inventing a fixture nobody else needs.
+ */
+type TranscriptAge = 'fresh' | 'hours' | 'days';
+
+const MS_PER_HOUR = 3_600_000;
+const MS_PER_DAY = 86_400_000;
+const AGE_SHIFT_HOURS = 3;
+const AGE_SHIFT_DAYS = 3;
+
+const TRANSCRIPT_AGE_OFFSET_MS: Record<TranscriptAge, number> = {
+  fresh: 0,
+  hours: AGE_SHIFT_HOURS * MS_PER_HOUR,
+  days: AGE_SHIFT_DAYS * MS_PER_DAY,
+};
+
 const seedTranscript = (s: SandboxState): void => {
-  const fingerprint = `${s.transcript}|${s.agentCount}|${s.manualSelection}`;
+  const fingerprint = `${s.transcript}|${s.agentCount}|${s.manualSelection}|${s.transcriptAge}`;
   if (fingerprint === lastSeed) return;
   lastSeed = fingerprint;
   // Deferred so it lands after any driver rebuild the agents change kicked off.
   setTimeout(() => {
-    const seed = TRANSCRIPTS[s.transcript].map((m) => ({ ...m }));
+    const shift = TRANSCRIPT_AGE_OFFSET_MS[s.transcriptAge];
+    const seed = TRANSCRIPTS[s.transcript].map((m) => ({
+      ...m,
+      // Shift rather than restamp, so the fixtures' own relative spacing survives.
+      ...(shift && m.timestamp
+        ? { timestamp: new Date(new Date(m.timestamp).getTime() - shift).toISOString() }
+        : {}),
+    }));
     (assistant as any).driver?.loadHistory?.(seed.map((m) => ({ ...m })));
     assistant.messages = seed;
     // `auto` measures the transcript, which only exists as of this tick — so the
@@ -309,6 +341,7 @@ const buildChatConfig = (s: SandboxState): ChatConfig => ({
     showToolCalls: s.showToolCalls,
     showThinkingSteps: s.showThinkingSteps,
     showNarration: s.showNarration,
+    showTimestamps: s.showTimestamps,
     // `undefined` disables the feature outright (no cog control, nothing enabled);
     // `userConfigurable` turns the defaults on and adds the multiselect to the cog.
     animations: s.animations ? { userConfigurable: true } : undefined,
@@ -473,6 +506,41 @@ const applyStage = (s: SandboxState): void => {
   document.body.dataset.stageTheme = s.theme;
 };
 
+/**
+ * Panel controls that must ALSO be written straight onto the element, keyed by the state
+ * key that drives them.
+ *
+ * `chatConfig.ui` is consulted only while the store is fresh and the user has changed
+ * nothing (`applyPreferenceBaseline`), so the moment the cog is touched — or a stored
+ * preference exists — a config change is correctly ignored. That is right for a real host,
+ * where a user's choice should outrank a host default, and useless for a harness control,
+ * which has to win.
+ *
+ * Applied ONLY for the key that actually moved (see the `renderControls` callback), so an
+ * unrelated panel change cannot silently clobber a choice made in the cog. Whichever of the
+ * two you touched last is what you get.
+ *
+ * `animations` is deliberately absent: it is a feature gate rather than a display
+ * preference (`undefined` disables the feature and removes the cog control altogether), and
+ * it has no single element property to mirror it onto.
+ */
+const DIRECT_PREFERENCE_WRITERS: Partial<
+  Record<keyof SandboxState & string, (s: SandboxState) => void>
+> = {
+  showTimestamps: (s) => {
+    assistant.timestampDisplay = s.showTimestamps;
+  },
+  showToolCalls: (s) => {
+    assistant.showToolCalls = s.showToolCalls;
+  },
+  showThinkingSteps: (s) => {
+    assistant.showThinkingSteps = s.showThinkingSteps;
+  },
+  showNarration: (s) => {
+    assistant.showNarration = s.showNarration;
+  },
+};
+
 function apply(): void {
   assistant.headerTitle = state.headerTitle;
   assistant.placeholder = state.placeholder;
@@ -783,6 +851,17 @@ const GROUPS: ReadonlyArray<ControlGroup<SandboxState>> = [
           { value: 'wall', label: 'Wall (~24k in one indivisible tool result)' },
         ],
       },
+      {
+        kind: 'select',
+        key: 'transcriptAge',
+        label: 'Age',
+        options: [
+          { value: 'fresh', label: 'Just now' },
+          { value: 'hours', label: '3 hours ago' },
+          { value: 'days', label: '3 days ago' },
+        ],
+        hint: 'Shifts the whole seed back. The fixtures span minutes, so this is the only way to reach the absolute date tier.',
+      },
       {
         kind: 'action',
         label: 'Re-seed transcript',
@@ -826,6 +905,17 @@ const GROUPS: ReadonlyArray<ControlGroup<SandboxState>> = [
       { kind: 'toggle', key: 'showToolCalls', label: 'Show tool calls' },
       { kind: 'toggle', key: 'showThinkingSteps', label: 'Show reasoning' },
       { kind: 'toggle', key: 'showNarration', label: 'Show narration' },
+      {
+        kind: 'select',
+        key: 'showTimestamps',
+        label: 'Timestamps',
+        options: [
+          { value: 'off', label: 'Off' },
+          { value: 'hover', label: 'On hover' },
+          { value: 'always', label: 'Always' },
+        ],
+        hint: 'Also settable from the cog. Whichever you moved last wins; moving other panel controls will not disturb a cog choice.',
+      },
       { kind: 'toggle', key: 'animations', label: 'Animations' },
     ],
   },
@@ -890,6 +980,8 @@ const paint = (): void => {
       state.contextPreset = CUSTOM_PRESET;
     }
     apply();
+    // Only for the control that actually moved — see DIRECT_PREFERENCE_WRITERS.
+    if (key) DIRECT_PREFERENCE_WRITERS[key]?.(state);
   });
 };