temporalio
diff --git a/‎.stylelintrc‎
Lines changed: 1 addition & 0 deletions b/‎.stylelintrc‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/timeline-architecture.md‎
Lines changed: 218 additions & 0 deletions b/‎docs/timeline-architecture.md‎
Lines changed: 218 additions & 0 deletions
diff --git a/‎package.json‎
Lines changed: 5 additions & 0 deletions b/‎package.json‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎scripts/perf-events.ts‎
Lines changed: 113 additions & 0 deletions b/‎scripts/perf-events.ts‎
Lines changed: 113 additions & 0 deletions
@@ -37,6 +37,7 @@
       }
     ],
     "custom-property-pattern": null,
+    "custom-property-empty-line-before": null,
     "declaration-block-no-redundant-longhand-properties": [
       true,
       {
 
@@ -0,0 +1,218 @@
+# Timeline & Event History Architecture
+
+## Core Principle: One Copy, One Truth
+
+All event data lives in a **single module-level singleton** (`grouped-event-buffer.ts`).
+Consumers read it via `getEventArray()` / `getGroupArray()`. A thin `bufferVersion`
+signal and `fullEventHistory` store expose it to Svelte, but they carry references
+to the same objects — never copies.
+
+```mermaid
+flowchart LR
+    API["API / live stream"] -->|processEvent| BUF
+
+    subgraph BUF["grouped-event-buffer.ts (singleton)"]
+        direction TB
+        EV["events[]<br/>one array, no copies"]
+        GR["groups[]<br/>metadata only — stores IDs + refs"]
+        SO["soloEvents[]<br/>WorkflowExecutionStarted etc."]
+        ID["liveSeenIds Set<br/>dedup guard"]
+    end
+
+    BUF -->|getEventArray| TL["Timeline layout"]
+    BUF -->|getGroupArray| HL["History layout"]
+    BUF -->|getEventArray| WD["Workflow Details"]
+
+    BUF -->|bufferVersion signal| TL
+    BUF -->|onLatestGroup callback| HL
+```
+
+### Key tenets
+
+| Tenet                        | How                                                                                                                                                     |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **No second data structure** | `EventGroup` is a metadata envelope — it stores event IDs and a reference to the head event; it does not copy field values                              |
+| **No duplicate objects**     | `liveSeenIds` rejects any event ID seen before; `appendLiveEvent` and `processEvent` both gate on this set                                              |
+| **Lazy detail rendering**    | Raw event payload is read from the existing array entry only when a detail panel opens — not on every group build                                       |
+| **Solo events included**     | `WorkflowExecutionStarted` events that don't belong to a group live in `soloEvents[]` and are merged into `getEventArray()` at read time                |
+| **Reactive signal is cheap** | `bufferVersion` is a plain Svelte `writable(0)` incremented on each buffer flush; consumers `$derived` off it to re-read without diffing the full array |
+
+---
+
+## Group Assembly: Park-and-Flush Pattern
+
+Temporal events arrive out of order. A group (Activity, Timer, Child Workflow, …) is made up of 2–5 events where only the **head event** (e.g. `ActivityTaskScheduled`) carries the group identity. Followers (Started, Completed) reference the head by ID.
+
+Two separate sources can deliver events concurrently:
+
+- **Bidirectional fetch** — ascending cursor from event 1, descending cursor from the last event, racing toward the middle.
+- **Live poll** — long-poll at the frontier while a workflow is running.
+
+Both use the same core pattern: **park followers invisibly until the head arrives, then flush them into the group in one shot.**
+
+```mermaid
+flowchart TD
+    subgraph SOURCES["Event sources"]
+        ASC["Ascending cursor\n(processEvent)"]
+        DESC["Descending cursor\n(processEvent)"]
+        LIVE["Live poll\n(appendLiveEvent)"]
+    end
+
+    ASC & DESC --> PE["processEvent(event)"]
+    LIVE --> ALE["appendLiveEvent(event)"]
+
+    PE -->|isHead = true| POOL["groupPool slot\neventToGroup[slot] = poolIdx+1"]
+    PE -->|isHead = false| ATF["attachFollower(headSlotIdx, followerSlotIdx)"]
+
+    ATF -->|head already in pool| ATFP["attachFollowerToPool\n→ insertEventById into group\n→ eventSlots[slot] = null"]
+    ATF -->|head not yet in pool| PF["pendingFollowers.set(headSlot, followerSlots[])"]
+
+    POOL -->|flush| PF_FLUSH["flush pendingFollowers\n→ attachFollowerToPool × N"]
+    POOL -->|flush| LPF_FLUSH["flush livePendingFollowers\n→ insertEventById × N\n→ eventToGroup[slot] = poolIdx+1"]
+
+    ALE -->|isHead = true| LG["liveGroups entry\n+ flush livePendingFollowers"]
+    ALE -->|head in liveGroups| LG_EXT["extend live group directly"]
+    ALE -->|head in groupPool| POOL_EXT["extend pool group directly\n(Option B)"]
+    ALE -->|head unknown| LPF["livePendingFollowers.set(headId, events[])"]
+```
+
+### Four resolution paths for a follower event
+
+| Source                   | Head already where? | Action                                                                                  |
+| ------------------------ | ------------------- | --------------------------------------------------------------------------------------- |
+| `processEvent` (bidir)   | groupPool           | `attachFollowerToPool` — inserts immediately, nulls raw slot                            |
+| `processEvent` (bidir)   | Nowhere yet         | `pendingFollowers` map — parks slot index; flushed when head arrives                    |
+| `appendLiveEvent` (live) | liveGroups          | Extends live group's `eventList` in place                                               |
+| `appendLiveEvent` (live) | groupPool           | Extends pool group's `eventList` directly; marks `eventToGroup[followerSlot]`           |
+| `appendLiveEvent` (live) | Nowhere yet         | `livePendingFollowers` map — parks converted `WorkflowEvent`; flushed when head arrives |
+
+**A group only becomes visible in `getGroupArray()` once its head has been processed.** No partial or stub groups are rendered.
+
+### What each map stores
+
+```
+pendingFollowers:    Map<headSlotIdx: number, followerSlotIdx[]: number[]>
+                     ↑ slot indices only — raw HistoryEvent stays in eventSlots[]
+
+livePendingFollowers: Map<headEventId: string, WorkflowEvent[]>
+                      ↑ already-converted events — appendLiveEvent never writes to eventSlots
+```
+
+One copy of each event exists at any time — either waiting in a park map, or committed inside `group.eventList`.
+
+### Dedup when both sources deliver the same event
+
+`attachFollowerToPool` guards with:
+
+```
+if (eventToGroup[followerSlotIdx] !== 0) { null the slot; return; }
+```
+
+If `livePendingFollowers` already claimed a slot (by writing `eventToGroup[followerSlotIdx]` during flush), the bidirectional cursor's delivery of the same event is silently discarded.
+
+### Live groups in `getGroupArray()`
+
+Complete live groups (head delivered by live poll) are included alongside pool groups. Once `processEvent` claims the head (`eventToGroup[headSlot] !== 0`) the live group is excluded — the pool group takes over with an identical or superset `eventList`.
+
+---
+
+## Reactivity: Events and Callbacks, Not Svelte Primitives
+
+The buffer is **plain TypeScript** — no `$state`, no `$derived`, no stores inside the module.
+Svelte's reactive graph is only entered at the outermost boundary, via two narrow escape hatches.
+
+```mermaid
+flowchart TD
+    subgraph NEW["✅ New approach (buffer + narrow signals)"]
+        direction LR
+        N1["Plain TS array mutated<br/>in-place — no reactive cost"] -->|batch complete| N2["bufferVersion.set(v+1)<br/>one integer write"]
+        N2 -->|$derived reads version| N3["Consumer calls getEventArray()<br/>reads already-built array — O(1)"]
+        N1 -->|group head appended| N4["onLatestGroup() fires<br/>registered callback"]
+        N4 --> N5["Layout calls getGroupArray()<br/>reads cached sorted slice — O(1)"]
+    end
+```
+
+```mermaid
+flowchart TD
+    subgraph OLD["❌ Old approach (stores)"]
+        direction LR
+        O1["Svelte writable store<br/>holds full WorkflowEvent[]"] -->|every push triggers| O2["$derived chains re-run<br/>across all subscribers"]
+        O2 --> O3["Full array diff + re-render<br/>at 50k events = jank"]
+    end
+```
+
+### Why this matters at scale
+
+|                  | Svelte store approach                           | Buffer + signal approach                                                  |
+| ---------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
+| 10 k event push  | Re-runs every `$derived` chain for each push    | Mutates array silently; one `bufferVersion` tick at end                   |
+| Subscriber count | Every component watching the store re-evaluates | Only components that read `bufferVersion` or register via `onLatestGroup` |
+| Memory per event | Two copies — one in store, one in group         | One copy in `events[]`; group holds a reference to the same object        |
+| Render trigger   | Svelte decides (potentially every frame)        | Explicit: either a version bump or a callback — nothing else              |
+
+### The two signal types
+
+**`bufferVersion`** — a plain `writable(0)`. Consumers write:
+
+```svelte
+let rows = $derived.by(() => {
+  $bufferVersion;           // subscribe to the tick
+  return getEventArray();   // read the already-built array
+});
+```
+
+No array is passed through the signal. The signal carries only the intent to re-read.
+
+**`onLatestGroup(cb)`** — a callback registration (pub/sub, not Svelte reactive). Layouts register on mount and receive a teardown function. The buffer calls every registered callback synchronously after appending a new group head. No Svelte primitive involved — the callback fires imperative code that then reassigns a `$state` variable once, queueing exactly one Svelte flush.
+
+---
+
+## Virtualization: Scroll-Driven Window + Row Pool
+
+The timeline can have tens of thousands of rows; only a small pooled window is
+ever in the DOM. Rows are plain absolutely-positioned **HTML** divs (not SVG).
+
+```mermaid
+flowchart TD
+    A["scroll / wheel / touchmove"] --> B["pokeSampler: (re)start the rAF loop"]
+    B --> C["rAF: read container offset via getBoundingClientRect\n→ visible pixel band"]
+    C --> D{band changed?}
+    D -- no, N frames --> E["idle out (loop stops)"]
+    D -- yes --> F["getWindowBounds(band) → [start, end) row indices"]
+    F --> G["pool re-points its slots to those groups\n(no create/destroy — props update in place)"]
+    G --> C
+```
+
+- **The container is the full drawn height** (`svgHeight`) and scrolls with the
+  page inside its overflow ancestor (found via `findScrollParent`, in practice
+  `#content-wrapper`). There is no `translateY`, no sentinel, and no spacer div —
+  the page scrolls the tall container directly.
+- **Band measurement is scroll-driven, per frame.** A self-driven `requestAnimationFrame`
+  loop reads the container's offset within its scroll parent each frame and idles
+  out after a few still frames. It's kept alive by `scroll` **and** `wheel` /
+  `touchmove`, because a wheel/trackpad fling fires `wheel` but coalesces `scroll`
+  — an event-only measure goes stale mid-fling and rows blank out. (This replaced
+  an earlier IntersectionObserver approach, which the browser throttles during
+  fast scroll.)
+- **`getWindowBounds`** is the closed-form inverse of `getRowY` — it maps the
+  visible band to a `[start, end)` row-index range (ascending/descending/pending-gap
+  aware), plus `OVERSCAN` rows on each side.
+- **Row pool.** Instead of a keyed `{#each}` that creates/destroys rows as the
+  window slides, a fixed-size set of slots (keyed by slot **index**) is reused. As
+  you scroll, each slot re-points to a new group — the `<li>` and its component
+  instance stay mounted and only props update. This removed the `cloneNode` /
+  insert / effect-teardown churn that was tripping frequent major-GC pauses.
+
+### Positioning math (`timeline-graph/timeline-positioning.ts`)
+
+- `getRowY(i, …)` — y (px) for the group at index `i`; descending-cursor rows
+  shift down by `pendingGroupCount` to open the loading gap.
+- `getPendingBlockY(…)` — top of the skeleton gap rectangle.
+- `getDescStart` / `getTotalForY` — locate the cursor split and the descending-sort
+  denominator.
+- Row height and dot radius come from `timeline-graph/constants.ts`
+  (`ROW_HEIGHT`, `RADIUS`, `GUTTER`); the color helpers live in `lines-and-dots/colors.ts`.
+
+> Point-in-time change summaries (regressions fixed, tests added, test-workflow
+> setup) intentionally live in the PR description and git history, not here, so
+> this document can stay a description of the _current_ architecture.
@@ -38,6 +38,8 @@
     "serve:playwright:e2e": "vite build && vite preview --mode test.e2e",
     "serve:playwright:integration": "vite build && vite preview --mode test.integration --port 3333",
     "test": "TZ=UTC vitest",
+    "perf:signals": "esno scripts/perf-signals.ts",
+    "perf:events": "esno scripts/perf-events.ts",
     "test:ui": "TZ=UTC vitest --ui",
     "test:coverage": "TZ=UTC vitest run --coverage",
     "test:e2e": "PW_MODE=e2e playwright test tests/e2e",
@@ -53,6 +55,8 @@
     "prettier:fix": "prettier --write --plugin prettier-plugin-svelte --plugin prettier-plugin-tailwindcss .",
     "preview:local": "VITE_TEMPORAL_UI_BUILD_TARGET=local vite preview",
     "preview:docker": "VITE_API=http://localhost:8080 VITE_TEMPORAL_UI_BUILD_TARGET=local vite preview",
+    "preview:local-temporal": "VITE_API=http://localhost:8081 vite build --sourcemap && VITE_TEMPORAL_UI_BUILD_TARGET=local vite preview --port 3001",
+    "preview:local-temporal:full": "trap 'kill 0' EXIT INT TERM; pnpm temporal-server & pnpm dev:local-temporal & pnpm preview:local-temporal",
     "package": "svelte-package",
     "package:patch": "pnpm version patch && svelte-package",
     "package:minor": "pnpm version minor && svelte-package",
@@ -65,6 +69,7 @@
     "stylelint:fix": "stylelint --fix \"src/**/*.{css,postcss,svelte}\"",
     "generate:locales": "esno scripts/generate-locales.ts",
     "run-workflows": "esno scripts/run-workflows.ts",
+    "run-workflows:long-running": "esno scripts/start-long-running.ts",
     "audit:tailwind": "esno scripts/audit-tailwind-colors",
     "validate:versions": "./scripts/validate-versions.sh",
     "knip": "knip",
 
@@ -0,0 +1,113 @@
+/**
+ * Performance test: run HighVolumeEventWorkflow which generates a mixed
+ * history of activities, timers, child workflows, and signals.
+ *
+ * Usage:
+ *   pnpm perf:events                    # 40 000 target events
+ *   pnpm perf:events --target 10000     # custom target
+ *   pnpm perf:events --no-worker        # use already-running worker
+ */
+
+import yargs from 'yargs/yargs';
+
+import { connect } from '../temporal/client';
+import { runWorker, stopWorker } from '../temporal/worker';
+import { HighVolumeEventWorkflow } from '../temporal/workflows';
+
+const argv = await yargs(process.argv.slice(2))
+  .option('target', {
+    type: 'number',
+    default: 40_000,
+    describe: 'Target history event count',
+  })
+  .option('worker', {
+    type: 'boolean',
+    default: true,
+    describe: 'Start embedded Temporal worker',
+  })
+  .parse();
+
+const TARGET: number = argv.target;
+const WORKFLOW_ID = `perf-events-${Date.now()}`;
+
+async function main() {
+  console.log('\n🚀 Temporal mixed-event perf test');
+  console.log(`   Target events : ${TARGET.toLocaleString()}`);
+  console.log(
+    '   Mix           : activities · timers · child workflows · signals',
+  );
+  console.log(`   Workflow      : ${WORKFLOW_ID}\n`);
+
+  if (argv.worker) {
+    console.log('⏳ Starting embedded worker...');
+    await runWorker();
+  }
+
+  const client = await connect();
+
+  console.log('⏳ Starting HighVolumeEventWorkflow...');
+  const handle = await client.workflow.start(HighVolumeEventWorkflow, {
+    taskQueue: 'e2e-1',
+    workflowId: WORKFLOW_ID,
+    args: [TARGET],
+  });
+
+  console.log(`✅ Workflow started: ${handle.workflowId}`);
+  console.log(
+    `\n⚙️  Generating ${TARGET.toLocaleString()} history events...\n`,
+  );
+
+  const startMs = performance.now();
+  let lastLogMs = startMs;
+  let lastCount = 0;
+
+  const poller = setInterval(async () => {
+    try {
+      const desc = await client.workflow.describe(WORKFLOW_ID);
+      const count = desc.historyLength ?? 0;
+      const now = performance.now();
+      const elapsed = ((now - startMs) / 1000).toFixed(1);
+      const rate = Math.round((count - lastCount) / ((now - lastLogMs) / 1000));
+      const pct = Math.min(100, Math.round((count / TARGET) * 100));
+      console.log(
+        `  [${elapsed}s] ${count.toLocaleString()} / ${TARGET.toLocaleString()} events (${pct}%) · ${rate.toLocaleString()} ev/s`,
+      );
+      lastLogMs = now;
+      lastCount = count;
+    } catch {
+      // workflow may not be describable yet
+    }
+  }, 3000);
+
+  const result = await handle.result();
+  clearInterval(poller);
+
+  const totalMs = performance.now() - startMs;
+
+  console.log(`\n✅ Done in ${(totalMs / 1000).toFixed(1)}s`);
+  console.log('\n📊 Workflow result:');
+  console.log(`   History events : ${result.historyLength.toLocaleString()}`);
+  console.log(`   Activities     : ${result.activities.toLocaleString()}`);
+  console.log(`   Timers         : ${result.timers.toLocaleString()}`);
+  console.log(`   Child workflows: ${result.children.toLocaleString()}`);
+  console.log(`   Signals recv'd : ${result.signals.toLocaleString()}`);
+  if (result.durationMs) {
+    console.log(
+      `   Workflow span  : ${(result.durationMs / 1000).toFixed(1)}s`,
+    );
+    console.log(
+      `   Event rate     : ${Math.round(result.historyLength / (result.durationMs / 1000)).toLocaleString()} ev/s`,
+    );
+  }
+  console.log(`\n   Workflow ID: ${WORKFLOW_ID}`);
+  console.log('   → Load in UI to test fast-history performance\n');
+
+  if (argv.worker) {
+    await stopWorker();
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
Original file line number	Diff line number	Diff line change
`@@ -37,6 +37,7 @@`
`37`	`37`	`}`
`38`	`38`	`],`
`39`	`39`	`"custom-property-pattern": null,`
	`40`	`+ "custom-property-empty-line-before": null,`
`40`	`41`	`"declaration-block-no-redundant-longhand-properties": [`
`41`	`42`	`true,`
`42`	`43`	`{`