Add temporal lifecycle page and lifecycle APIs

Introduce a Temporal Lifecycle feature and integrate annotation lifecycle primitives across docs and code. Adds docs/content: new TemporalLifecyclePage, nav entry, route, and expanded CLAUDE.md notes (including the "semantic" anchor and lifecycle helpers). Replace page-local freshness logic in blog and ConversationArc demos with exported helpers (applyAnnotationLifecycle, annotationFreshnessFor) and wire the demo UIs to the shared behavior. Code changes: add realtime lifecycleBands implementation and tests, expose lifecycle-related types/APIs (semiotic-ai / semiotic-realtime), and extend Annotation props to accept opacity and strokeDasharray so lifecycle visual treatments cascade. The changes unify banded freshness classification (bandFromAge) and provide a default visual treatment for aging/stale/expired annotations.

Author: emeeks

CLAUDE.md

@@ -239,7 +239,7 @@ All HOCs accept `annotations` (array). Coordinates use data field names.
 **Ordinal**: `category-highlight`
 **Enclosures**: `enclose`, `rect-enclose`, `highlight`
 **Statistical**: `trend`, `envelope`, `anomaly-band`, `forecast`
-**Streaming anchors**: `"fixed"` | `"latest"` | `"sticky"`
+**Streaming anchors**: `"fixed"` | `"latest"` | `"sticky"` | `"semantic"` — also exposed as `lifecycle.anchor` on the `semiotic/ai` annotation lifecycle. Same `AnnotationAnchor` type either way; `"semantic"` re-resolves via `provenance.stableId` (runtime support landing incrementally).
 
 ## Theming
 
@@ -342,25 +342,63 @@ store.record({ type: "suggestion-shown", components: ["LineChart"], intent: "tre
 ```
 
 ### Annotation provenance + lifecycle (`semiotic/ai`, types also re-exported from `semiotic`)
-Type surface for "where did this annotation come from?" and "is it stale?" Optional blocks attached to any annotation — existing arrays keep working unchanged.
+Tracks "where did this annotation come from?" and "is it stale?" Two optional blocks attach to any annotation — existing arrays keep working unchanged.
 - **`provenance`**: `{ author?, source?, confidence?, createdAt?, stableId? }`. `source` is an open string union (`"user" | "ai" | "agent" | "import" | "computed" | "system" | (string & {})`).
 - **`lifecycle`**: `{ freshness?, ttlHint?, anchor? }`. `freshness` is `"fresh" | "aging" | "stale" | "expired"`. `anchor` is `"fixed" | "latest" | "sticky" | "semantic"`. `ttlHint` accepts an ISO 8601 duration string (`"P30D"`) or milliseconds.
 - **`withProvenance(annotation, { provenance?, lifecycle? })`** → returns a new annotation with the blocks attached. Pure, SSR-safe.
 - **`Annotated<T>`** type alias: `T & { provenance?, lifecycle? }`. Use for explicit typing.
-- Type surface only at this stage. Freshness computation, default visual treatment, and stable-id anchor resolution land later.
+- **`computeAnnotationFreshness(annotations, { now?, dataExtent?, thresholds? })`** → returns annotations with `lifecycle.freshness` populated based on `createdAt` + `ttlHint`. `now` defaults to `dataExtent`'s max, then `Date.now()`. Custom thresholds override the default 1× / 1.5× / 3× TTL breakpoints.
+- **`annotationFreshnessFor(annotation, nowMs, thresholds?)`** → classifies a single annotation. Honors any pre-existing `lifecycle.freshness` (explicit assignment wins).
+- **`applyAnnotationLifecycle(annotations, { now?, dataExtent?, opacity?, strokeDasharray?, labelSuffix?, showExpiredAnnotations?, thresholds? })`** → composes the freshness pass with a default visual treatment: aging dims (opacity 0.55), stale dims more + dashes (strokeDasharray `"4 4"`), expired is filtered out (set `showExpiredAnnotations: true` to keep). Per-band overrides via the options; pass `null` for a band to disable that default. Annotation `opacity` / `strokeDasharray` set explicitly on the annotation win over the treatment. Annotation renderer cascades both as SVG presentation attributes to every stroked / filled child.
+- Still owed (M3): stable-id anchor resolution after data refresh.
 
 ```ts
-import { withProvenance } from "semiotic/ai"
+import { withProvenance, applyAnnotationLifecycle } from "semiotic/ai"
 
 const ann = withProvenance(
-  { type: "y-threshold", value: 100, label: "SLA breach" },
+  { type: "y-threshold", value: 100, label: "SLA breach", color: "#3a8eff" },
   {
     provenance: { author: "alice", source: "user", createdAt: "2026-05-20T14:00:00Z" },
     lifecycle: { ttlHint: "P30D", anchor: "semantic" },
   },
 )
+
+// Pass through the lifecycle treatment before handing to a chart.
+<LineChart annotations={applyAnnotationLifecycle([ann], { dataExtent: [t0, tNow] })} />
 ```
 
+### Temporal lifecycle (shared between `semiotic/realtime` + `semiotic/ai`)
+Three Semiotic systems answer "how does this thing look as it ages?" with three different policies on three different time axes. They are *not* interchangeable — pick the one that matches the question.
+
+| Policy | Lives in | Time axis | Output | Scope |
+|---|---|---|---|---|
+| `DecayConfig` | `semiotic/realtime` | buffer position | continuous opacity ramp | per-datum |
+| `StalenessConfig` | `semiotic/realtime` | wall-clock idle | binary live/stale (+ optional badge) | chart-wide |
+| Annotation freshness | `semiotic/ai` | `createdAt` + `ttlHint` | 4 named bands (opacity + dashing + expired filter) | per-annotation |
+
+Shared primitive that bridges them: **`bandFromAge(ageMs, ttlMs, thresholds?)`** → `"fresh" | "aging" | "stale" | "expired"`. Pure function exported from both `semiotic/realtime` and `semiotic/ai`. `DEFAULT_LIFECYCLE_THRESHOLDS = { fresh: 1.0, aging: 1.5, stale: 3.0 }` (multipliers of TTL). Annotation freshness uses this primitive today; future banded-decay or banded-staleness opt-ins can plug into the same classifier.
+
+**Anchor mode** (`"fixed" | "latest" | "sticky" | "semantic"`) is also shared — `AnnotationAnchor` from `semiotic/realtime` is the canonical type, re-exported from `semiotic/ai` as `lifecycle.anchor`. `"semantic"` re-resolves via `provenance.stableId` (runtime support landing incrementally).
+
+**Streaming chart-time aging**: pass the chart's `dataExtent` to `applyAnnotationLifecycle` and the latest data point becomes the "now" reference. Annotations age against chart-time, not wall-clock — useful when streams pause or run slow. Pair with `withCurrentProvenance(annotation, { author?, source? })` or `currentTimestamp()` to auto-stamp `createdAt` at the moment of creation.
+
+```ts
+import { bandFromAge, withCurrentProvenance, applyAnnotationLifecycle } from "semiotic/ai"
+
+bandFromAge(20_000, 8000) // "stale" — age is 2.5× TTL
+
+const ann = withCurrentProvenance(
+  { type: "callout", t: latest.t, value: latest.value, label: "Spike" },
+  { author: "alice", source: "user" },
+)
+
+<LineChart
+  annotations={applyAnnotationLifecycle([ann], { dataExtent: [data[0].t, data.at(-1).t] })}
+/>
+```
+
+Full survey at `/intelligence/temporal-lifecycle`.
+
 ### Variant discovery (`semiotic/ai`)
 Interface for proposing and scoring chart variants beyond the hand-curated `capability.variants`. Heuristic and model-based proposers plug in through `registerVariantDiscovery`. M1 ships the type surface + stub implementations; behavior arrives in subsequent milestones.
 - **`VariantProposal`**: `{ id, baseComponent, intentDeltas?, rubricDeltas?, buildProps?, rationale?, source: "manual" | "heuristic" | "model", variantKey?, tags? }`.

docs/src/App.js

@@ -97,6 +97,7 @@ import CapabilitiesPage from "./pages/features/CapabilitiesPage"
 import InterrogationPage from "./pages/features/InterrogationPage"
 import SuggestionsPage from "./pages/features/SuggestionsPage"
 import ConversationArcPage from "./pages/features/ConversationArcPage"
+import TemporalLifecyclePage from "./pages/features/TemporalLifecyclePage"
 
 // New cookbook pages
 import HomerunMapPage from "./pages/cookbook/HomerunMapPage"
@@ -401,6 +402,7 @@ export default function DocsApp() {
               <Route path="suggestions" element={<SuggestionsPage />} />
               <Route path="interrogation" element={<InterrogationPage />} />
               <Route path="conversation-arc" element={<ConversationArcPage />} />
+              <Route path="temporal-lifecycle" element={<TemporalLifecyclePage />} />
               <Route path="serialization" element={<SerializationPage />} />
               <Route path="vega-lite" element={<VegaLiteTranslatorPage />} />
             </Route>

docs/src/blog/entries/talk-track-intelligence.js

@@ -3,6 +3,8 @@ import React, { useEffect, useMemo, useRef, useState } from "react"
 import { Link } from "react-router-dom"
 import { CategoryColorProvider, DotPlot, LineChart } from "semiotic"
 import {
+  annotationFreshnessFor,
+  applyAnnotationLifecycle,
   disableConversationArc,
   enableConversationArc,
   getConversationArcStore,
@@ -267,59 +269,32 @@ const RAW_ANNOTATIONS = [
 ]
 
 const FRESHNESS_BASE_COLOR = { user: "#3a8eff", ai: "#d49a00" }
-const FRESHNESS_COLOR = {
-  fresh: (base) => base,
-  aging: () => "#8a96a3",
-  stale: () => "#b0b0b0",
-}
-const FRESHNESS_SUFFIX = { fresh: "", aging: " · aging", stale: " · stale" }
 const FRESHNESS_BADGE = {
   fresh: "#2d8a4a",
   aging: "#d49a00",
   stale: "#a0a0a0",
   expired: "#c43d3d",
 }
 
-function parseIsoDuration(s) {
-  const m = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?)?$/.exec(s)
-  if (!m) return 0
-  return (parseInt(m[1] || "0", 10) * 24 + parseInt(m[2] || "0", 10)) * 60 * 60 * 1000
-}
-
-function previewFreshness(ann, nowMs) {
-  const created = ann?.provenance?.createdAt ? Date.parse(ann.provenance.createdAt) : null
-  const ttl = ann?.lifecycle?.ttlHint
-  if (created == null || ttl == null) return "fresh"
-  const ms = typeof ttl === "number" ? ttl : parseIsoDuration(ttl)
-  const age = nowMs - created
-  if (age < ms) return "fresh"
-  if (age < ms * 1.5) return "aging"
-  if (age < ms * 3) return "stale"
-  return "expired"
-}
-
 function FreshnessLiveDemo() {
   const [nowIso, setNowIso] = useState("2026-03-10T00:00:00Z")
   const nowMs = Date.parse(nowIso)
 
-  const states = RAW_ANNOTATIONS.map((a) => ({
-    raw: a,
-    freshness: previewFreshness(a, nowMs),
+  // Each annotation keeps its author's brand color via `color`. The
+  // shipped applyAnnotationLifecycle treatment fills in opacity +
+  // strokeDasharray per band and drops expired ones.
+  const annotationsWithColor = RAW_ANNOTATIONS.map((a) => ({
+    ...a,
+    color: FRESHNESS_BASE_COLOR[a.provenance.source] ?? "#5a5a5a",
+  }))
+  const visible = applyAnnotationLifecycle(annotationsWithColor, {
+    now: nowMs,
+    labelSuffix: { aging: " · aging", stale: " · stale" },
+  })
+  const states = RAW_ANNOTATIONS.map((raw) => ({
+    raw,
+    freshness: annotationFreshnessFor(raw, nowMs),
   }))
-
-  // Expired annotations drop out of the array — mirrors M2's default
-  // of hiding them unless `showExpiredAnnotations` is on.
-  const visible = states
-    .filter((s) => s.freshness !== "expired")
-    .map(({ raw, freshness }) => {
-      const base = FRESHNESS_BASE_COLOR[raw.provenance.source] ?? "#5a5a5a"
-      return {
-        ...raw,
-        label: raw.label + FRESHNESS_SUFFIX[freshness],
-        color: FRESHNESS_COLOR[freshness](base),
-        lifecycle: { ...raw.lifecycle, freshness },
-      }
-    })
 
   return (
     <div style={card}>
@@ -493,9 +468,12 @@ function Body() {
       <FreshnessLiveDemo />
 
       <p>
-        The styling above is page-local — the M1 surface is type-only,
-        and the shipping <code style={inlineCode}>computeAnnotationFreshness</code>{" "}
-        helper plus the default visual treatment land next.
+        The styling above is the shipped default: a single call to{" "}
+        <code style={inlineCode}>applyAnnotationLifecycle(annotations, {"{ now }"})</code>{" "}
+        classifies each annotation, dims aging, dashes stale, and drops
+        expired from the array. The author's brand color survives the
+        treatment — provenance stays visible while age signals layer on
+        top.
       </p>
 
       <h2>Variants the library didn't think of</h2>

docs/src/components/navData.js

@@ -130,6 +130,7 @@ const navData = [
       { title: "Chart Suggestions", path: "/intelligence/suggestions" },
       { title: "Interrogation", path: "/intelligence/interrogation" },
       { title: "Conversation Arc", path: "/intelligence/conversation-arc" },
+      { title: "Temporal Lifecycle", path: "/intelligence/temporal-lifecycle" },
       { title: "Serialization", path: "/intelligence/serialization" },
       { title: "Vega-Lite Translator", path: "/intelligence/vega-lite" }
     ]