@genesislcap/ai-assistant 15.26.0 → 15.27.0-agent-log-submit.3

package/dist/esm/main/main.styles.js

@@ -354,11 +354,86 @@ const baseStyles = css `
   }
 
   .sender {
+    /* Flex so the timestamp sits on the sender's baseline with a real gap, rather than
+       butting against the name or needing a margin that a missing timestamp would leave
+       behind. Wraps, so a narrow bubble drops the timestamp to its own line instead of
+       stretching the bubble to fit both. */
+    display: flex;
+    align-items: baseline;
+    flex-wrap: wrap;
+    gap: 2px 8px;
     font-weight: bold;
     font-size: 0.9em;
     margin-bottom: 4px;
   }
 
+  /* Recessive against the name it sits beside: lighter, smaller and dimmed. Deliberately
+     not a colour of its own — it inherits the bubble's foreground, so it stays legible on
+     the accent-filled user bubble and the neutral assistant one without a token per
+     variant. */
+  .message-timestamp {
+    font-weight: normal;
+    font-size: 0.85em;
+    opacity: 60%;
+    white-space: nowrap;
+
+    /* Chrome, not message content. Without this, opacity 0 still leaves the text
+       selectable, so dragging across the transcript and copying picks up a timestamp on
+       every message — including the ones the reader never hovered and never saw. */
+    user-select: none;
+  }
+
+  /* Removed from paint and from flow, but kept in the accessibility tree — the standard
+     clip-rect idiom rather than display:none or visibility:hidden, both of which would
+     take it out of the tree and defeat the point. Carries the absolute time behind the
+     relative text; see messageTimestampTemplate. */
+  .visually-hidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  /* 'hover' — the default. Space is RESERVED at all times (opacity, not display) so
+     revealing the timestamp cannot reflow the bubble under the pointer; only the paint
+     changes. The sender line is rarely the widest line in a bubble, so this costs no
+     width except on very short messages. */
+  .messages-content.timestamps-hover .message-timestamp {
+    opacity: 0%;
+    transition: opacity 0.12s ease-out;
+  }
+
+  .messages-content.timestamps-hover .message-row:hover .message-timestamp {
+    opacity: 60%;
+  }
+
+  /* Keyboard and touch reach the same reveal: neither produces a hover. The
+     focus-within rule costs nothing today (message rows are not focusable) and starts
+     working the moment anything inside one is. */
+  .messages-content.timestamps-hover .message-row:focus-within .message-timestamp {
+    opacity: 60%;
+  }
+
+  /* A pointer that cannot hover (touch) would otherwise never see a timestamp, and
+     hover on touch is sticky and unpredictable where it fires at all. Show them. */
+  @media (hover: none) {
+    .messages-content.timestamps-hover .message-timestamp {
+      opacity: 60%;
+    }
+  }
+
+  /* Respect a reduced-motion preference: the fade is decorative, the reveal is not. */
+  @media (prefers-reduced-motion: reduce) {
+    .messages-content.timestamps-hover .message-timestamp {
+      transition: none;
+    }
+  }
+
   .payload {
     font-family: monospace;
     white-space: pre-wrap;

package/dist/esm/main/main.template.js

@@ -17,6 +17,7 @@
 import { isChatToolCallUnknown } from '@genesislcap/foundation-ai';
 import { classNames, html, ref, repeat, when } from '@genesislcap/web-core';
 import { SettingsModalTemplate } from '../components/settings-modal';
+import { formatAbsoluteTimestamp, formatMessageTimestamp, messageTimestampDateTime, } from '../utils/format-message-timestamp';
 import { compactionDividerLabel } from '../utils/history-transform';
 import { LOADING_STYLE_ANIMATIONS } from './main.types';
 function unknownToolPayload(tc) {
@@ -126,6 +127,35 @@ const messageParts = (m) => {
         ? `message message-interaction message-interaction-${interactionPresentation(m)}`
         : `message message-${type}`;
 };
+/**
+ * The timestamp shown beside the sender name (GENC-1257).
+ *
+ * Two strings, not one. A screen reader announces a `<time>` element's TEXT — it has no
+ * implicit ARIA role, and the `datetime` attribute is never surfaced to the user — so the
+ * relative text is hidden from assistive tech and paired with a visually-hidden absolute
+ * string. Otherwise AT would hear "5 minutes ago" with nothing to anchor it, and in
+ * `'hover'` mode would hear it for a timestamp sighted users never asked to see.
+ * `datetime` stays because it is correct HTML and useful to tooling, not for a11y.
+ *
+ * Only the VISUAL reveal is hover-gated, in CSS — see `.message-timestamp`. `opacity: 0`
+ * leaves the element in the accessibility tree, so AT gets a time in both visible modes;
+ * `'off'` is the only mode that removes it.
+ *
+ * Reads `timestampClock` rather than `Date.now()` so every row shares one invalidatable
+ * clock and a tick re-evaluates them all; see `FoundationAiAssistant.timestampClock`.
+ */
+export const messageTimestampTemplate = html `
+  <time
+    class="message-timestamp"
+    part="message-timestamp"
+    datetime="${(m) => messageTimestampDateTime(m.timestamp)}"
+  >
+    <span aria-hidden="true">
+      ${(m, c) => formatMessageTimestamp(m.timestamp, c.parent.timestampClock)}
+    </span>
+    <span class="visually-hidden">${(m) => formatAbsoluteTimestamp(m.timestamp)}</span>
+  </time>
+`;
 // ─── Sub-agent trace fragments ────────────────────────────────────────────────
 const subAgentAssistantTemplate = html `
   <div class="sub-agent-message sub-agent-assistant">${(m) => m.content}</div>
@@ -499,7 +529,8 @@ ${(tc) => { var _a; return (((_a = tc.foldPath) === null || _a === void 0 ? void
     // host sender label. Every other message keeps it.
     (m) => !(m.interaction && interactionPresentation(m) === 'bare'), html `
                 <div class="sender">
-                  ${(m, c) => {
+                  <span class="sender-label">
+                    ${(m, c) => {
         var _a;
         return messageType(m) === 'ai-function' &&
             m.agentName &&
@@ -507,6 +538,13 @@ ${(tc) => { var _a; return (((_a = tc.foldPath) === null || _a === void 0 ? void
             ? `Tool Call · ${(_a = m.agentLabel) !== null && _a !== void 0 ? _a : m.agentName}`
             : senderLabelFor(m);
     }}
+                  </span>
+                  ${when(
+    // Guarded on the stamp too: a session persisted before timestamp
+    // support restores without one, and an empty <time> would still
+    // draw the gap the flex row reserves for it.
+    (m, c) => !!m.timestamp &&
+        c.parent.timestampDisplay !== 'off', messageTimestampTemplate)}
                 </div>
               `)}
             <div class="content">
@@ -826,7 +864,10 @@ ${(tc) => { var _a; return (((_a = tc.foldPath) === null || _a === void 0 ? void
       </div>
 
       <div class="messages" part="messages" ${ref('messagesEl')}>
-        <div class="messages-content" part="messages-content">
+        <div
+          class="messages-content ${(x) => `timestamps-${x.timestampDisplay}`}"
+          part="messages-content"
+        >
           ${when((x) => x.compacting, compactingTemplate)}
           ${when((x) => x.restoring, restoringTemplate)}
           ${repeat((x) => (x.compacting || x.restoring ? [] : x.visibleMessages), messageRowTemplate)}

package/dist/esm/state/ai-assistant-slice.js

@@ -13,6 +13,7 @@ export function createDefaultSessionState() {
         showThinkingSteps: false,
         showNarration: false,
         showAgentSwitchIndicator: false,
+        timestampDisplay: 'hover',
         enabledAnimations: [],
         suggestionsState: { status: 'idle' },
         contextTokens: undefined,
@@ -64,6 +65,9 @@ export const aiAssistantSlice = createSlice({
         setShowAgentSwitchIndicator(state, action) {
             state.showAgentSwitchIndicator = action.payload;
         },
+        setTimestampDisplay(state, action) {
+            state.timestampDisplay = action.payload;
+        },
         setEnabledAnimations(state, action) {
             state.enabledAnimations = action.payload;
         },
@@ -322,6 +326,7 @@ export const aiAssistantSlice = createSlice({
                 showThinkingSteps: state.showThinkingSteps,
                 showNarration: state.showNarration,
                 showAgentSwitchIndicator: state.showAgentSwitchIndicator,
+                timestampDisplay: state.timestampDisplay,
                 enabledAnimations: state.enabledAnimations,
                 providerStatuses: state.providerStatuses,
                 blocked: state.blocked,

package/dist/esm/utils/format-message-timestamp.js

@@ -0,0 +1,126 @@
+/**
+ * The ONE place this package turns a message's `timestamp` into display text
+ * (GENC-1257).
+ *
+ * Three tiers, deliberately coarse — the transcript shows this beside the sender
+ * name, where a long string competes with the name itself:
+ *
+ * | Age            | Reads                                                               |
+ * | -------------- | ------------------------------------------------------------------- |
+ * | under a minute | `Now`                                                                 |
+ * | under an hour  | `12 minutes ago`                                                      |
+ * | anything older | an absolute date+time in the user's locale, e.g. `Sep 10, 2026, 14:18` |
+ *
+ * The absolute tier is deliberately locale-driven, so its exact rendering is the
+ * runtime's to choose — `en-US` gives `Sep 10, 2026, 14:18` and `en-GB` gives
+ * `10 Sept 2026, 14:18`. Only the FIELDS are ours; see {@link ABSOLUTE_FORMAT_OPTIONS}.
+ *
+ * Split out as a pure function (as `format-usd.ts` was) so the tier boundaries are
+ * testable without a clock, an element or a render: every entry point takes `now`
+ * rather than reading `Date.now()` itself.
+ *
+ * @internal
+ */
+/** Milliseconds in a minute. */
+const MS_PER_MINUTE = 60000;
+/** Minutes in an hour. Named for the lint rule that forbids a bare literal in an expression. */
+const MINUTES_PER_HOUR = 60;
+/** Milliseconds in an hour — the boundary between the relative and absolute tiers. */
+const MS_PER_HOUR = MINUTES_PER_HOUR * MS_PER_MINUTE;
+/**
+ * Field selection for the absolute tier.
+ *
+ * Exported so tests can build their expectation from the same options rather than from a
+ * literal: every field below renders differently per locale and time zone, so asserting
+ * `"Sep"` or `"10"` only asserts the machine the test happened to run on.
+ *
+ * Locale is left undefined so it follows the user's, and `hourCycle: 'h23'` pins the clock
+ * to 24-hour regardless — a locale-chosen 12-hour clock would add "am"/"pm" and widen the
+ * string next to the sender name.
+ */
+export const ABSOLUTE_FORMAT_OPTIONS = {
+    day: 'numeric',
+    month: 'short',
+    year: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+    hourCycle: 'h23',
+};
+/**
+ * Built once at module load rather than per message: a transcript re-renders on every
+ * store change, and `Intl.DateTimeFormat` construction is the expensive half of the API
+ * (formatting against an existing instance is cheap).
+ */
+const absoluteFormatter = new Intl.DateTimeFormat(undefined, ABSOLUTE_FORMAT_OPTIONS);
+/**
+ * Display text for a message timestamp, per the tiers above.
+ *
+ * A timestamp slightly in the future (clock skew between a server-stamped message and the
+ * browser) reads `Now` rather than a negative count — "-3 minutes ago" looks broken and
+ * tells the user nothing. That indulgence is bounded at an hour: beyond it the stamp is
+ * not skew but bad data (a machine with a badly wrong clock, a hand-edited session), and
+ * showing `Now` forever on every message would hide that. Past the bound it falls through
+ * to the absolute tier, which shows the user what the data actually says.
+ *
+ * @param iso - ISO-8601 timestamp, as stamped by the driver on append.
+ * @param now - Current epoch ms. Passed in rather than read, so tests pin the clock.
+ * @returns Display text, or `''` when there is nothing sensible to show.
+ */
+export function formatMessageTimestamp(iso, now) {
+    const ms = toEpochMs(iso);
+    if (ms === undefined)
+        return '';
+    const age = now - ms;
+    if (age < MS_PER_MINUTE && age > -MS_PER_HOUR)
+        return 'Now';
+    if (age >= MS_PER_MINUTE && age < MS_PER_HOUR) {
+        const minutes = Math.floor(age / MS_PER_MINUTE);
+        return `${minutes} ${minutes === 1 ? 'minute' : 'minutes'} ago`;
+    }
+    return absoluteFormatter.format(ms);
+}
+/**
+ * The absolute rendering of a stamp, whatever its age — the accessible text behind a
+ * message timestamp.
+ *
+ * Exists because the visible text is relative and a screen reader announces the element's
+ * TEXT, not its `datetime` attribute: `<time>` carries no implicit ARIA role, so the
+ * machine-readable value reaches tooling and nobody else. The template pairs this with
+ * `aria-hidden` on the relative string so assistive tech hears one unambiguous time
+ * instead of "5 minutes ago" with no anchor.
+ *
+ * @param iso - ISO-8601 timestamp, as stamped by the driver on append.
+ * @returns The absolute string, or `''` when there is nothing sensible to show.
+ */
+export function formatAbsoluteTimestamp(iso) {
+    const ms = toEpochMs(iso);
+    return ms === undefined ? '' : absoluteFormatter.format(ms);
+}
+/**
+ * The `datetime` attribute value for the rendered `<time>` element — the raw ISO string,
+ * which is what the HTML spec wants and what date-aware tooling reads. It is NOT an
+ * accessibility affordance: screen readers announce the element's text content instead.
+ *
+ * Returns `null`, not `''`, for a missing or unparseable stamp: FAST removes an attribute
+ * only for `null`/`undefined` (see `DOM.setAttribute`), so an empty string would emit
+ * `datetime=""`, which is invalid per spec and flagged by HTML validators.
+ *
+ * @param iso - ISO-8601 timestamp, as stamped by the driver on append.
+ */
+export function messageTimestampDateTime(iso) {
+    return toEpochMs(iso) === undefined ? null : iso;
+}
+/**
+ * Parse a stamp to epoch ms, rejecting both absence and garbage.
+ *
+ * `timestamp` is optional on {@link ChatMessage} for one real reason — sessions persisted
+ * before timestamp support restore without it — and a persisted blob is host-supplied data
+ * that can also be malformed. `new Date(junk).getTime()` is `NaN`, which would otherwise
+ * flow into the arithmetic and render "NaN minutes ago".
+ */
+function toEpochMs(iso) {
+    if (!iso)
+        return undefined;
+    const ms = new Date(iso).getTime();
+    return Number.isNaN(ms) ? undefined : ms;
+}

package/dist/esm/utils/resolve-debug-log-note.js

@@ -0,0 +1,37 @@
+/** Default cap on the user's note. Short by design — it is a caption for the log, not a report. */
+export const DEBUG_LOG_NOTE_DEFAULT_MAX_LENGTH = 500;
+/** Default prompt in the empty note. */
+export const DEBUG_LOG_NOTE_DEFAULT_PLACEHOLDER = 'What were you doing, or what went wrong? (optional)';
+/** The same prompt for a `required` note — "(optional)" would contradict the disabled Send. */
+export const DEBUG_LOG_NOTE_REQUIRED_PLACEHOLDER = 'What were you doing, or what went wrong?';
+/**
+ * Resolve `debugLogSubmit.note` — `undefined`/`true` mean "compose box with defaults",
+ * `false` means "no compose box, send on first click" (→ `null`), and an object customises
+ * the box. Keeps the template free of the boolean-or-object dance.
+ */
+export function resolveDebugLogNoteConfig(config) {
+    var _a;
+    if (!config || config.note === false)
+        return null;
+    // `typeof null === 'object'`: a host building its config dynamically can hand us `null`
+    // even though the type forbids it, and that must read as "defaults", not crash.
+    const note = typeof config.note === 'object' && config.note !== null ? config.note : {};
+    // `>= 1`, not `> 0`: a fractional cap under 1 would floor to 0 and lock the textarea.
+    const maxLength = typeof note.maxLength === 'number' && note.maxLength >= 1
+        ? Math.floor(note.maxLength)
+        : DEBUG_LOG_NOTE_DEFAULT_MAX_LENGTH;
+    const required = note.required === true;
+    return {
+        placeholder: (_a = note.placeholder) !== null && _a !== void 0 ? _a : (required ? DEBUG_LOG_NOTE_REQUIRED_PLACEHOLDER : DEBUG_LOG_NOTE_DEFAULT_PLACEHOLDER),
+        required,
+        maxLength,
+    };
+}
+/**
+ * Normalise the typed note for the submission: trimmed, and `undefined` when empty so a
+ * host can `message ?? fallback` without checking for whitespace.
+ */
+export function normalizeDebugLogNote(note) {
+    const trimmed = note.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}

package/dist/esm/utils/resolve-preference-baseline.js

@@ -1,5 +1,48 @@
 import { DEFAULT_ANIMATIONS } from '../main/main.types';
 import { resolveExclusiveLoadingStyle } from './animation-exclusivity';
+/**
+ * Whether a preference write is a no-op, so a setter can bail before touching the store.
+ *
+ * Load-bearing rather than an optimisation. The design-system `switch` fires `@change` when its
+ * `:checked` binding is applied on render, not only on user interaction — so an unguarded setter
+ * marks preferences "user-changed" on every render and saves config defaults, which freezes the
+ * reconciler so real stored prefs never apply on reload (GENC-1351 #1).
+ *
+ * List preferences compare order-insensitively: the per-animation switches fire the same spurious
+ * render-time `@change`, and `enabledAnimations` is a set rather than a sequence.
+ *
+ * @internal
+ */
+export function preferenceUnchanged(current, value) {
+    if (Array.isArray(current) && Array.isArray(value)) {
+        return current.length === value.length && current.every((item) => value.includes(item));
+    }
+    return current === value;
+}
+/** The mode used when neither the host config nor stored prefs name a valid one. */
+export const DEFAULT_TIMESTAMP_DISPLAY = 'hover';
+/**
+ * Every valid {@link TimestampDisplay}, for narrowing untrusted input.
+ *
+ * Keyed by the union rather than typed `readonly string[]`, so adding a mode is a compile
+ * error here. A plain string array severs the link: the new mode would type-check
+ * everywhere, then be rejected at runtime as junk and silently fall back to `'hover'` —
+ * surfacing as "my new mode doesn't stick" rather than as a type error.
+ */
+const TIMESTAMP_DISPLAY_MODES = {
+    off: true,
+    hover: true,
+    always: true,
+};
+/**
+ * Narrow an untrusted value to a {@link TimestampDisplay}, or `undefined` if it is not one.
+ *
+ * Both inputs need this: the config field is typed but comes from plain JS hosts, and the
+ * stored field is a bare `string` read back out of a persistence blob.
+ */
+const asTimestampDisplay = (value) => typeof value === 'string' && value in TIMESTAMP_DISPLAY_MODES
+    ? value
+    : undefined;
 /**
  * Resolve the effective preference baseline for a fresh store, applying the
  * precedence (lowest → highest):
@@ -20,7 +63,7 @@ import { resolveExclusiveLoadingStyle } from './animation-exclusivity';
  * @internal
  */
 export function resolvePreferenceBaseline(ui, stored) {
-    var _a, _b;
+    var _a, _b, _c;
     const u = ui !== null && ui !== void 0 ? ui : {};
     // Layer 1 — chatConfig.ui defaults.
     const baseline = {
@@ -28,7 +71,10 @@ export function resolvePreferenceBaseline(ui, stored) {
         showThinkingSteps: u.showThinkingSteps === true,
         showNarration: u.showNarration === true,
         showAgentSwitchIndicator: u.showAgentSwitchIndicator === true,
-        enabledAnimations: resolveExclusiveLoadingStyle((_b = (_a = u.animations) === null || _a === void 0 ? void 0 : _a.enabled) !== null && _b !== void 0 ? _b : (u.animations ? [...DEFAULT_ANIMATIONS] : [])),
+        // Defaults ON, unlike the booleans above — so this reads the config value when it is
+        // a valid mode and falls back to `'hover'`, rather than testing `=== true`.
+        timestampDisplay: (_a = asTimestampDisplay(u.showTimestamps)) !== null && _a !== void 0 ? _a : DEFAULT_TIMESTAMP_DISPLAY,
+        enabledAnimations: resolveExclusiveLoadingStyle((_c = (_b = u.animations) === null || _b === void 0 ? void 0 : _b.enabled) !== null && _c !== void 0 ? _c : (u.animations ? [...DEFAULT_ANIMATIONS] : [])),
     };
     // Layer 2 — stored user preferences override the fields they carry.
     if (stored) {
@@ -43,6 +89,12 @@ export function resolvePreferenceBaseline(ui, stored) {
         if (stored.showAgentSwitchIndicator !== undefined) {
             baseline.showAgentSwitchIndicator = stored.showAgentSwitchIndicator;
         }
+        // Validated, not just presence-checked: `SessionPreferences.timestampDisplay` is a
+        // plain `string` off a host-supplied blob, so a stale or hand-edited value must fall
+        // through to the config layer instead of poking a junk mode into the store.
+        const storedMode = asTimestampDisplay(stored.timestampDisplay);
+        if (storedMode)
+            baseline.timestampDisplay = storedMode;
         if (Array.isArray(stored.animations)) {
             // De-dupe defensively — historical blobs may hold duplicates from the old
             // settings-modal append bug (now fixed at the `setEnabledAnimations` source).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "15.26.0",
+  "version": "15.27.0-agent-log-submit.3",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -74,26 +74,26 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.26.0",
-    "@genesislcap/genx": "15.26.0",
-    "@genesislcap/rollup-builder": "15.26.0",
-    "@genesislcap/ts-builder": "15.26.0",
-    "@genesislcap/uvu-playwright-builder": "15.26.0",
-    "@genesislcap/vite-builder": "15.26.0",
-    "@genesislcap/webpack-builder": "15.26.0",
+    "@genesislcap/foundation-testing": "15.27.0-agent-log-submit.3",
+    "@genesislcap/genx": "15.27.0-agent-log-submit.3",
+    "@genesislcap/rollup-builder": "15.27.0-agent-log-submit.3",
+    "@genesislcap/ts-builder": "15.27.0-agent-log-submit.3",
+    "@genesislcap/uvu-playwright-builder": "15.27.0-agent-log-submit.3",
+    "@genesislcap/vite-builder": "15.27.0-agent-log-submit.3",
+    "@genesislcap/webpack-builder": "15.27.0-agent-log-submit.3",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2",
     "esbuild": "0.25.12"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "15.26.0",
-    "@genesislcap/foundation-logger": "15.26.0",
-    "@genesislcap/foundation-notifications": "15.26.0",
-    "@genesislcap/foundation-redux": "15.26.0",
-    "@genesislcap/foundation-ui": "15.26.0",
-    "@genesislcap/foundation-utils": "15.26.0",
-    "@genesislcap/rapid-design-system": "15.26.0",
-    "@genesislcap/web-core": "15.26.0",
+    "@genesislcap/foundation-ai": "15.27.0-agent-log-submit.3",
+    "@genesislcap/foundation-logger": "15.27.0-agent-log-submit.3",
+    "@genesislcap/foundation-notifications": "15.27.0-agent-log-submit.3",
+    "@genesislcap/foundation-redux": "15.27.0-agent-log-submit.3",
+    "@genesislcap/foundation-ui": "15.27.0-agent-log-submit.3",
+    "@genesislcap/foundation-utils": "15.27.0-agent-log-submit.3",
+    "@genesislcap/rapid-design-system": "15.27.0-agent-log-submit.3",
+    "@genesislcap/web-core": "15.27.0-agent-log-submit.3",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },

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 —