@joewinke/jatui 0.24.0 → 0.26.0

package/CLAUDE.md

@@ -59,7 +59,7 @@ Then import:
 | `Badge` | Status/label badge | `variant`, `size`, `children` (snippet) |
 | `StatusBadge` | Status indicator with dot | `status: StatusValue`, `label` |
 | `Card` | Content card container | `title`, `children` (snippet) |
-| `Modal` | Dialog overlay. `zIndex` accepts `number` OR any CSS `z-index` string, including `"var(--z-lightbox)"`. | `open` (bindable), `title`, `children` (snippet), `zIndex?: string \| number` |
+| `Modal` | Dialog overlay. `zIndex` accepts `number` OR any CSS `z-index` string, including `"var(--z-lightbox)"`. **Escape is owned by the dialog element itself** (not the window handler) — Modal focuses the dialog on open, so `trapKeys`' stopPropagation would otherwise swallow Esc before the window listener sees it; a Modal opened inside a host Drawer closes before the drawer. The component ships its own open-state `.modal-box` opacity rule, so it renders under DaisyUI 5 with no host global override. | `open` (bindable), `title`, `children` (snippet), `zIndex?: string \| number`, `trapKeys?`, `closeOnEscape?` |
 | `ConfirmModal` | Yes/no confirmation dialog | `open` (bindable), `title`, `message`, `onConfirm`, `onCancel` |
 | `Drawer` | Slide-out side panel | `open` (bindable), `side`, `children` (snippet) |
 | `LoadingSpinner` | Spinner animation | `size`, `color` |
@@ -76,6 +76,14 @@ Then import:
 | `QuotaMeter` | "312 / 500 credits · resets in 4h 10m" bar — warning tint at `warnAt`, error at 100%. Presentational; the host owns the ledger. | `used`, `limit`, `resetsAt?`, `label?`, `unit?`, `warnAt?` (0.8), `size?` |
 | `VariantMatrixPicker` | Category/option chip grid for building a combinatorial variant matrix (harvested from vid-gen's FrameVariantGenerator, presets stripped — caller-supplied `categories`). Each category tab shows a live selection count and an additive/multiplicative badge: multiplicative selections cartesian-multiply the total, additive ones stack flat onto every combination. Live combination count in the footer; algebra exported separately as pure functions (`generateCombinations`, `countCombinations`, `variantCategoryMode`, `findVariantOption`, `generateVariantFilename`). | `categories: VariantCategory[]`, `selected` (bindable `VariantSelection`), `forceMode?`, `showCount?` (true), `countLabel?`, `onChange?`, `class?` |
 
+### Tables (subpath: `jatui/table`)
+
+Requires peer `@tanstack/table-core`. `import { DataTable, flexRender, columnResize } from 'jatui/table'`.
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `DataTable` | TanStack-backed table (generic over the row type): sorting, selection, client pagination, skeleton. Grid-mode hooks per jat `docs/design/datatable-virtualisation-group-rows.md` §3.3: `getRowId` (keys selection/expansion/api by id, renders `data-row-id`); controlled sort — `bind:sorting`, `initialSorting`, `manualSorting` (caller pre-sorts `data`), `onSortingChange(next, {field, shiftKey})`; `rowProps(row, item)` → `{class, attrs, onclick, oncontextmenu, ondragover, ondrop}` (`attrs` for `data-nav-id`, aria); `onRowClick(row, e)` (skips clicks on interactive children); `headerProps(columnId)`; `expandedRow` snippet `(row, {colspan})` — click/Enter toggles unless `isExpanded(row)` makes it controlled; `empty` snippet; `variant` `zebra`/`plain`/`unstyled` + `tableClass`; `bind:api` → `orderedRowIds()`, `scrollToRow(id)`. Sortable headers are keyboard-operable. | `data`, `columns`, `sortable`, `selectable`, `paginated`, `getRowId?`, `sorting?` (bindable), `rowProps?`, `onRowClick?`, `expandedRow?`, `empty?`, `variant?`, `api?` (bindable) |
+
 ### Media
 
 | Component | Purpose | Key Props |
@@ -244,7 +252,7 @@ const callbacks: AnnotationCallbacks = {
 <KeyboardShortcutsOverlay registry={shortcuts} />
 ```
 
-**Sidebar convention: `SIDEBAR_TOGGLE_KEY` = `mod+\`** (Ctrl+\ / ⌘\). Do NOT use Ctrl+B: Chrome reserves it (bookmarks bar). Also avoid Ctrl+T/W/N, which the browser keeps. The overlay owns `?`, so don't register it. Helpers: `formatShortcut(def | "mod+k", platform?)` → `⌘K` / `Ctrl+K`, `isTypingTarget(el)`, `parseShortcutCombo`, `detectShortcutPlatform`.
+**Sidebar convention: `SIDEBAR_TOGGLE_KEY` = `mod+\`** (Ctrl+\ / ⌘\). Do NOT use Ctrl+B: Chrome reserves it (bookmarks bar). Also avoid Ctrl+T/W/N, which the browser keeps. The overlay owns `?` by default, so don't register it — but if a host app already has its own global `?` handler registered first, the overlay respects `event.defaultPrevented` and stays out of the way (one overlay per keypress). Helpers: `formatShortcut(def | "mod+k", platform?)` → `⌘K` / `Ctrl+K`, `isTypingTarget(el)`, `parseShortcutCombo`, `detectShortcutPlatform`.
 
 ### Maps (Google Maps)
 

package/dist/components/KeyboardShortcutsOverlay.svelte

@@ -133,6 +133,11 @@
 	}
 
 	function onKeydown(e: KeyboardEvent) {
+		// Another listener already claimed this keypress (host app's own '?'
+		// handler, an open modal, …) — bail so one keypress can't toggle two
+		// overlays at once. Covers the '?' and Escape branches alike.
+		if (e.defaultPrevented) return;
+
 		if (e.ctrlKey || e.metaKey || e.altKey) return;
 
 		if (e.key === '?') {

package/dist/components/Modal.svelte

@@ -124,6 +124,21 @@
 	}
 
 	function handleKeyDown(event: KeyboardEvent) {
+		// Escape is owned HERE on the dialog element, not by <svelte:window>.
+		// Modal focuses the dialog (tabindex=-1) on open, so in the default state
+		// keydown dispatches from the dialog itself — and the trapKeys
+		// stopPropagation below (which under Svelte 5 delegated events also
+		// blocks every window listener) would swallow Escape before the window
+		// handler could act: Esc did nothing unless focus was in a text field.
+		// Handling it at element level also guarantees a Modal opened inside a
+		// host Drawer closes before the drawer does.
+		if (open && event.key === 'Escape' && closeOnEscape) {
+			event.preventDefault();
+			event.stopPropagation();
+			close();
+			return;
+		}
+
 		// Stop keydown events from bubbling to window while the modal is open.
 		// This prevents page-level keyboard navigation (listNav-style handlers
 		// on window) from reacting to arrow keys, j/k, vim chords, digit counts,
@@ -247,4 +262,21 @@
 		align-items: center;
 		justify-content: center;
 	}
+
+	/*
+	 * DaisyUI 5 puts .modal-box at opacity:0 (layer daisyui.l1.l2.l3) and only
+	 * restores it from `.modal[open] .modal-box { opacity: 1 }` in the outer
+	 * layer — a rule that assumes daisyUI's canonical markup where the box is a
+	 * direct grid child of the dialog. jatui nests the box inside
+	 * .modal-backdrop, and the restore rule loses the cascade: the panel stays
+	 * invisible unless the host adds a global override (the jat IDE had to in
+	 * app.css, jat-vte6e.17). Un-layered author styles beat @layer rules, so
+	 * declaring the open state here makes the component render correctly on
+	 * its own. Entrance motion stays owned by the in:fly transition on the box.
+	 */
+	:global(dialog.modal[open] .modal-box) {
+		opacity: 1;
+		translate: 0;
+		scale: 1;
+	}
 </style>

package/dist/components/session-nav/transcriptModel.d.ts

@@ -34,6 +34,8 @@ export interface TranscriptItem {
     srcLines: number;
     /** id of the signal node that owns this item (assigned after parse) */
     signalId: string | null;
+    /** ISO write time of the first source message (null on line-parsed/live items) */
+    timestamp?: string | null;
 }
 export interface FileTouchedEntry {
     path: string;
@@ -65,11 +67,46 @@ export interface SignalNode {
     /** Net lines changed across all diffs for this block */
     linesAdded: number;
     linesRemoved: number;
+    /**
+     * Original signal JSON payload (full data for rich card rendering). Always
+     * set by the builders below; optional so SignalNodes constructed by hand
+     * (pre-0.25 callers) still type-check.
+     */
+    payload?: Record<string, unknown> | null;
+    /**
+     * True when this node represents the OPEN, in-progress turn — either a
+     * server-marked open block (`WorkBlockClient.open === true`) or the
+     * synthesized live node owning the trailing items past the last block.
+     * SessionNavigator uses this to render a ● live affordance. Optional so
+     * existing SignalNode consumers are unaffected.
+     */
+    isLive?: boolean;
 }
 export interface LinkedSession {
     items: TranscriptItem[];
     signals: SignalNode[];
 }
+/** Tone drives the marker's hue; deliberately NOT a session-state key. */
+export type MarkerTone = 'success' | 'error' | 'warn' | 'neutral' | 'info';
+/** What a card detector declares when its event deserves a rail marker. */
+export interface TimelineMarkerSpec {
+    /** glyph shown on the rail — keep it non-emoji so state glyphs stay distinct */
+    glyph: string;
+    /** short rail label, e.g. "subtask completed" */
+    label: string;
+    /** longer text for the title/tooltip */
+    detail?: string;
+    tone: MarkerTone;
+}
+/** A content event promoted onto the signal timeline, anchored to its row. */
+export interface TimelineMarker extends TimelineMarkerSpec {
+    /** rail id — "mrk-<itemId>" */
+    id: string;
+    /** transcript item this marker anchors to (its `[data-row]`) */
+    itemId: number;
+    /** signal owning that item — clicking a marker inks this signal's ribbon */
+    signalId: string | null;
+}
 export declare function rawTypeToState(raw: string): string;
 /** Build the linked model from rendered transcript lines. */
 export declare function buildLinkedSession(lines: string[]): LinkedSession;
@@ -99,6 +136,14 @@ export interface WorkBlockClient {
     }>;
     linesAdded?: number;
     linesRemoved?: number;
+    /**
+     * True when the server marks this block as the OPEN in-progress turn
+     * (populated by the navigator/sessionWork layer — sibling task jat-difet).
+     * Read defensively: may be undefined on blocks from older payloads. When
+     * true on the last block, that block's node becomes the live node (it
+     * absorbs any trailing items instead of synthesizing a separate one).
+     */
+    open?: boolean;
 }
 export interface WorkTranscriptItemClient {
     id: number;
@@ -107,6 +152,7 @@ export interface WorkTranscriptItemClient {
     detail: string[];
     srcLines: number;
     blockId: string | null;
+    timestamp?: string | null;
 }
 /**
  * Build a LinkedSession from the WorkBlock substrate (B1).

package/dist/components/session-nav/transcriptModel.js

@@ -41,10 +41,36 @@ function parseSignalBody(body) {
     if (!m)
         return null;
     let label = '';
-    const pick = body.match(/"(?:approach|question|reviewFocus|currentStep|summary|reason|taskTitle)"\s*:\s*"([^"]{3,90})/);
-    if (pick)
-        label = pick[1];
-    return { rawType: m[1], label };
+    let payload = null;
+    // Try to extract and parse the JSON payload from the signal call
+    const jsonMatch = body.match(/jat-signal\s+\w+\s+'(\{[\s\S]*?\})'\s*$/) ||
+        body.match(/jat-signal\s+\w+\s+"(\{[\s\S]*?\})"\s*$/) ||
+        body.match(/jat-signal\s+\w+\s+(\{[\s\S]*?\})\s*$/);
+    if (jsonMatch) {
+        try {
+            payload = JSON.parse(jsonMatch[1]);
+        }
+        catch {
+            // ignore parse errors — payload stays null
+        }
+    }
+    if (payload) {
+        // Extract label from full payload
+        const p = payload;
+        const candidate = (Array.isArray(p.summary) ? p.summary[0] : undefined) ??
+            (typeof p.approach === 'string' ? p.approach : undefined) ??
+            (typeof p.taskTitle === 'string' ? p.taskTitle : undefined) ??
+            (typeof p.question === 'string' ? p.question : undefined) ??
+            (typeof p.currentStep === 'string' ? p.currentStep : undefined);
+        if (candidate)
+            label = candidate.slice(0, 90);
+    }
+    else {
+        const pick = body.match(/"(?:approach|question|reviewFocus|currentStep|summary|reason|taskTitle)"\s*:\s*"([^"]{3,90})/);
+        if (pick)
+            label = pick[1];
+    }
+    return { rawType: m[1], label, payload };
 }
 /** Build the linked model from rendered transcript lines. */
 export function buildLinkedSession(lines) {
@@ -64,7 +90,14 @@ export function buildLinkedSession(lines) {
         } // blank ends a block
         if (line.startsWith('› ')) {
             flush();
-            cur = { kind: 'prompt', headline: line.slice(2), detail: [], srcLines: 1 };
+            const headline = line.slice(2);
+            // Claude Code's TUI draws a blank "› " input box while idle between
+            // turns; a capture that lands mid-frame leaks that empty prompt line
+            // into the transcript. Treat it like a blank line (below) rather than
+            // a zero-content prompt item — it never carries real content.
+            if (!headline.trim())
+                continue;
+            cur = { kind: 'prompt', headline, detail: [], srcLines: 1 };
             continue;
         }
         if (line.startsWith('⏺ ')) {
@@ -73,7 +106,7 @@ export function buildLinkedSession(lines) {
             if (sig) {
                 // signal emission = boundary; consume it, don't render as an item
                 flush();
-                emits.push({ afterIdx: items.length - 1, rawType: sig.rawType, label: sig.label });
+                emits.push({ afterIdx: items.length - 1, rawType: sig.rawType, label: sig.label, payload: sig.payload });
                 continue;
             }
             flush();
@@ -113,13 +146,33 @@ export function buildLinkedSession(lines) {
     }
     flush();
     // Build signal nodes from emission boundaries.
+    // Ownership is FORWARD: each signal owns the items that come AFTER it, up to
+    // (but not including) the next signal's emission point. The first signal also
+    // absorbs any preamble items that appear before it.
+    //
+    // Let B[i] = emits[i].afterIdx = last item index before signal[i].
+    //
+    // Partition (non-overlapping):
+    //   sig[0]    → [0 .. B[1]]           preamble + first forward region
+    //   sig[i>0]  → [B[i]+1 .. B[i+1]]   region after sig[i], before sig[i+1]
+    //   sig[last] → [B[last]+1 .. N-1]    region after last signal
+    //
+    // This ensures output printed AFTER a signal emission (e.g. the READY FOR
+    // REVIEW banner after `jat-signal review`) is attributed to that signal, not
+    // the subsequent one.
     const signals = [];
-    let prevBoundary = -1;
+    const N = items.length;
     emits.forEach((e, i) => {
-        const rowStart = Math.max(0, prevBoundary + 1);
-        const rowEnd = Math.max(rowStart, e.afterIdx);
+        // rowStart: first signal starts at 0 (absorbs preamble items before it);
+        // later signals start at the item immediately after this signal's emission.
+        const rowStart = i === 0 ? 0 : e.afterIdx + 1;
+        // naturalEnd: extends to the next signal's pre-boundary, or to the last item.
+        const naturalEnd = i + 1 < emits.length ? emits[i + 1].afterIdx : N - 1;
+        // rowEnd: capped at N-1 (never out of bounds); may be < rowStart when this
+        // signal has no items after it (e.g. last line is the signal itself).
+        const rowEnd = Math.min(naturalEnd, N - 1);
         let lineCount = 0;
-        for (let k = rowStart; k <= rowEnd && k < items.length; k++)
+        for (let k = rowStart; k <= rowEnd && k < N; k++)
             lineCount += items[k].srcLines;
         signals.push({
             id: `sig-${i}`,
@@ -135,9 +188,9 @@ export function buildLinkedSession(lines) {
             filesTouched: [],
             commits: [],
             linesAdded: 0,
-            linesRemoved: 0
+            linesRemoved: 0,
+            payload: e.payload
         });
-        prevBoundary = e.afterIdx;
     });
     for (const sig of signals) {
         for (let k = sig.rowStart; k <= sig.rowEnd && k < items.length; k++) {
@@ -168,9 +221,11 @@ export function buildLinkedSessionFromWork(blocks, items) {
         headline: it.headline,
         detail: it.detail,
         srcLines: it.srcLines,
-        signalId: null // filled in below
+        signalId: null, // filled in below
+        timestamp: it.timestamp ?? null
     }));
-    // Map WorkBlock → SignalNode
+    // Map WorkBlock → SignalNode. `isLive` is seeded from the server's open flag
+    // (read defensively — jat-difet adds it; may be undefined on older payloads).
     const signals = blocks.map((blk) => ({
         id: blk.id,
         state: rawTypeToState(blk.signal.type),
@@ -185,11 +240,80 @@ export function buildLinkedSessionFromWork(blocks, items) {
         filesTouched: blk.filesTouched,
         commits: blk.commits ?? [],
         linesAdded: blk.linesAdded ?? 0,
-        linesRemoved: blk.linesRemoved ?? 0
+        linesRemoved: blk.linesRemoved ?? 0,
+        payload: blk.signal.payload,
+        isLive: blk.open === true
     }));
-    // Assign signalId to transcript items via block ownership
+    const N = transcriptItems.length;
+    // Helper: synthesize the live node owning the open in-progress turn.
+    const makeLiveNode = (start, end, label) => {
+        let lineCount = 0;
+        for (let k = start; k <= end && k < N; k++)
+            lineCount += transcriptItems[k].srcLines;
+        return {
+            id: 'sig-live',
+            state: rawTypeToState('working'),
+            rawType: 'working',
+            label,
+            rowStart: start,
+            rowEnd: end,
+            lineCount: Math.max(1, lineCount),
+            blockId: null,
+            summary: null,
+            filesTouched: [],
+            commits: [],
+            linesAdded: 0,
+            linesRemoved: 0,
+            payload: null,
+            isLive: true
+        };
+    };
+    if (N > 0) {
+        if (signals.length === 0) {
+            // No blocks but live items exist → the whole transcript is the open
+            // turn. Give it a single live node so nothing is left unsignaled.
+            signals.push(makeLiveNode(0, N - 1, 'current'));
+        }
+        else {
+            // (#1 gap-fill) Guarantee a contiguous [0..N-1] partition so EVERY
+            // item ends up owning a signal:
+            //  (a) first signal absorbs any preamble before its range
+            signals[0].rowStart = 0;
+            //  (b) extend each signal's rowEnd to close the gap before the next
+            //      signal's range (no-op when ranges already touch/overlap)
+            for (let i = 0; i < signals.length - 1; i++) {
+                const nextStart = signals[i + 1].rowStart;
+                if (signals[i].rowEnd < nextStart - 1) {
+                    signals[i].rowEnd = nextStart - 1;
+                }
+            }
+            // (#2 live node) Trailing items past the last block's range are the
+            // OPEN in-progress turn — they must NOT be folded into the previous
+            // signal (e.g. a 'review'). Honor a server-marked open block first;
+            // otherwise synthesize a dedicated live node.
+            const lastSig = signals[signals.length - 1];
+            const lastBlockEnd = lastSig.rowEnd;
+            if (lastSig.isLive) {
+                // Server already marked the last block open → IT is the live node;
+                // extend it to absorb any trailing items.
+                lastSig.rowEnd = N - 1;
+            }
+            else if (lastBlockEnd < N - 1) {
+                // Synthesize a live node owning [lastBlockEnd+1 .. N-1]. Label from
+                // the live task title when available, else a neutral 'current'.
+                const p = lastSig.payload;
+                const title = p && typeof p.taskTitle === 'string' ? p.taskTitle.slice(0, 90) : null;
+                signals.push(makeLiveNode(lastBlockEnd + 1, N - 1, title ?? 'current'));
+            }
+            // else: the last block already reaches N-1 — nothing trailing.
+        }
+    }
+    // Assign signalId to transcript items via (gap-filled) ownership ranges.
+    // Clamp to bounds; later signals (incl. the live node) win on any overlap.
     for (const sig of signals) {
-        for (let k = sig.rowStart; k <= sig.rowEnd && k < transcriptItems.length; k++) {
+        const start = Math.max(0, sig.rowStart);
+        const end = Math.min(sig.rowEnd, N - 1);
+        for (let k = start; k <= end; k++) {
             transcriptItems[k].signalId = sig.id;
         }
     }
@@ -202,7 +326,7 @@ export function buildLinkedSessionFromWork(blocks, items) {
  */
 export const SAMPLE_TRANSCRIPT_LINES = [
     '',
-    '› /jat:start GentleCoast jat-7h2k',
+    '› /jat-start GentleCoast jat-7h2k',
     '⏺ Bash(get-current-session-id)',
     '  ⎿ 4f9c1a2e-7b3d-4c8a-9e1f-2a6b8c0d4e5f',
     '⏺ Bash(jat-signal starting \'{"agentName":"GentleCoast","taskTitle":"Add password reset flow"}\')',
@@ -256,7 +380,7 @@ export const SAMPLE_TRANSCRIPT_LINES = [
     '',
     '🔍 READY FOR REVIEW: jat-7h2k — password reset flow implemented, tested, rate-limited.',
     '',
-    '› /jat:complete',
+    '› /jat-complete',
     '⏺ Bash(jat-step committing --task jat-7h2k)',
     '  ⎿ Committed: feat(jat-7h2k): add password reset flow',
     '⏺ Bash(jat-signal complete \'{"taskId":"jat-7h2k","summary":"Shipped password reset flow"}\')',

package/dist/components/table/DataTable.svelte

@@ -1,4 +1,5 @@
-<script lang="ts">
+<script lang="ts" generics="TData">
+	import { tick } from 'svelte';
 	import {
 		createTable,
 		getCoreRowModel,
@@ -9,12 +10,10 @@
 		type RowSelectionState,
 		type PaginationState,
 		type TableOptionsResolved,
+		type Row,
 	} from '@tanstack/table-core';
 	import { flexRender } from './flexRender.js';
-	import type { DataTableProps } from './types.js';
-
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	type AnyData = any;
+	import type { DataTableProps, DataTableRowProps, DataTableSortEvent, GroupedItem } from './types.js';
 
 	let {
 		data,
@@ -27,13 +26,36 @@
 		loadingRows = 5,
 		onSelectionChange,
 		class: className = '',
-	}: DataTableProps = $props();
+		getRowId,
+		sorting = $bindable(),
+		initialSorting,
+		manualSorting = false,
+		onSortingChange,
+		rowProps,
+		onRowClick,
+		headerProps,
+		expandedRow,
+		isExpanded,
+		empty,
+		variant = 'zebra',
+		tableClass = '',
+		api = $bindable(),
+	}: DataTableProps<TData> = $props();
 
 	// ── State ──────────────────────────────────────────────────────────────
-	let sorting = $state<SortingState>([]);
+	// `sorting` is bindable: bound, the caller owns it; unbound, it is local
+	// state seeded from `initialSorting`.
+	// svelte-ignore state_referenced_locally
+	if (sorting === undefined) sorting = initialSorting ?? [];
+	const sortState = $derived<SortingState>(sorting ?? []);
 	let rowSelection = $state<RowSelectionState>({});
 	// svelte-ignore state_referenced_locally
 	let pagination = $state<PaginationState>({ pageIndex: 0, pageSize });
+	/** Internally-owned expansion (only used when `isExpanded` is not supplied). */
+	let expandedIds = $state<Set<string>>(new Set());
+	/** The header click that triggered the sort change currently in flight. */
+	let pendingSortEvent: DataTableSortEvent | null = null;
+	let rootEl: HTMLDivElement | undefined = $state();
 
 	// Reset to the first page whenever the data set changes.
 	//
@@ -50,7 +72,7 @@
 		pagination = { pageIndex: 0, pageSize };
 	});
 
-	const checkboxCol: ColumnDef<AnyData, unknown> = {
+	const checkboxCol: ColumnDef<TData, unknown> = {
 		id: '__select',
 		header: () => null,
 		cell: () => null,
@@ -58,24 +80,26 @@
 		size: 40,
 	};
 
-	const allColumns = $derived<ColumnDef<AnyData, unknown>[]>(
-		selectable ? [checkboxCol, ...(columns as ColumnDef<AnyData, unknown>[])] : (columns as ColumnDef<AnyData, unknown>[])
-	);
+	const allColumns = $derived<ColumnDef<TData, unknown>[]>(selectable ? [checkboxCol, ...columns] : columns);
 
 	// ── Table instance ─────────────────────────────────────────────────────
 	const table = $derived.by(() => {
-		const opts: TableOptionsResolved<AnyData> = {
+		const opts: TableOptionsResolved<TData> = {
 			data,
 			columns: allColumns,
 			state: {
-				sorting,
+				sorting: sortState,
 				rowSelection,
 				...(paginated ? { pagination } : {}),
 			},
+			getRowId: getRowId ? (row: TData) => getRowId(row) : undefined,
 			enableRowSelection: selectable,
 			enableSorting: sortable,
+			manualSorting,
 			onSortingChange: (updater) => {
-				sorting = typeof updater === 'function' ? updater(sorting) : updater;
+				const next = typeof updater === 'function' ? updater(sortState) : updater;
+				sorting = next;
+				onSortingChange?.(next, pendingSortEvent ?? { field: next[0]?.id ?? '', shiftKey: false });
 			},
 			onRowSelectionChange: (updater) => {
 				rowSelection = typeof updater === 'function' ? updater(rowSelection) : updater;
@@ -87,7 +111,7 @@
 				: () => {},
 			onStateChange: () => {},
 			getCoreRowModel: getCoreRowModel(),
-			getSortedRowModel: sortable ? getSortedRowModel() : undefined,
+			getSortedRowModel: sortable && !manualSorting ? getSortedRowModel() : undefined,
 			getPaginationRowModel: paginated ? getPaginationRowModel() : undefined,
 			renderFallbackValue: '',
 		};
@@ -109,30 +133,128 @@
 	const canPrevPage = $derived(table.getCanPreviousPage());
 	const canNextPage = $derived(table.getCanNextPage());
 
+	const tableClasses = $derived(
+		[variant === 'unstyled' ? '' : variant === 'plain' ? 'table' : 'table table-zebra', 'w-full', tableClass]
+			.filter(Boolean)
+			.join(' ')
+	);
+
+	/** The table owns expansion: a row click / Enter / Space toggles the detail row. */
+	const internalExpand = $derived(!!expandedRow && !isExpanded);
+
 	$effect(() => {
 		if (!selectable || !onSelectionChange) return;
-		const selected = table.getSelectedRowModel().rows.map((r: AnyData) => r.original);
+		const selected = table.getSelectedRowModel().rows.map((r) => r.original);
 		onSelectionChange(selected);
 	});
 
+	// ── Imperative api ─────────────────────────────────────────────────────
+	api = {
+		orderedRowIds: () => table.getPrePaginationRowModel().rows.map((r) => r.id),
+		scrollToRow: async (id, align = 'auto') => {
+			if (paginated) {
+				const index = table.getPrePaginationRowModel().rows.findIndex((r) => r.id === id);
+				if (index < 0) return;
+				const pageIndex = Math.floor(index / pagination.pageSize);
+				if (pageIndex !== pagination.pageIndex) {
+					pagination = { ...pagination, pageIndex };
+					await tick();
+				}
+			}
+			const el = rootEl?.querySelector<HTMLElement>(`tr[data-row-id="${CSS.escape(id)}"]`);
+			el?.scrollIntoView({ block: align === 'auto' ? 'nearest' : align });
+		},
+	};
+
 	function sortDir(headerId: string): 'asc' | 'desc' | false {
-		const s = sorting.find((item) => item.id === headerId);
+		const s = sortState.find((item) => item.id === headerId);
 		return s ? (s.desc ? 'desc' : 'asc') : false;
 	}
 
-	function renderHeader(header: ReturnType<typeof table.getHeaderGroups>[0]['headers'][0]) {
+	type AnyHeader = ReturnType<typeof table.getHeaderGroups>[0]['headers'][0];
+
+	function toggleSort(header: AnyHeader, e: MouseEvent | KeyboardEvent) {
+		pendingSortEvent = { field: header.column.id, shiftKey: e.shiftKey };
+		try {
+			header.column.getToggleSortingHandler()?.(e);
+		} finally {
+			pendingSortEvent = null;
+		}
+	}
+
+	function onHeaderKeydown(header: AnyHeader, e: KeyboardEvent) {
+		if (e.key !== 'Enter' && e.key !== ' ') return;
+		e.preventDefault();
+		toggleSort(header, e);
+	}
+
+	function renderHeader(header: AnyHeader) {
 		return flexRender(header.column.columnDef.header, header.getContext());
 	}
 
-	function renderCell(cell: ReturnType<ReturnType<typeof table.getRowModel>['rows'][0]['getVisibleCells']>[0]) {
+	function renderCell(cell: ReturnType<Row<TData>['getVisibleCells']>[0]) {
 		return flexRender(cell.column.columnDef.cell, cell.getContext());
 	}
+
+	// ── Row helpers ────────────────────────────────────────────────────────
+	function rowItem(row: Row<TData>, index: number, count: number): GroupedItem<TData> {
+		const position = count === 1 ? 'only' : index === 0 ? 'first' : index === count - 1 ? 'last' : 'middle';
+		return { kind: 'row', row: row.original, id: row.id, depth: 0, groupPath: [], position };
+	}
+
+	function rowIsExpanded(row: Row<TData>): boolean {
+		if (!expandedRow) return false;
+		return isExpanded ? isExpanded(row.original) : expandedIds.has(row.id);
+	}
+
+	function toggleExpanded(id: string) {
+		const next = new Set(expandedIds);
+		if (next.has(id)) next.delete(id);
+		else next.add(id);
+		expandedIds = next;
+	}
+
+	/** Clicks on these inside a row belong to the control, not to the row. */
+	const INTERACTIVE = 'input, button, a, select, textarea, label, [contenteditable]:not([contenteditable="false"])';
+
+	function isInteractiveTarget(e: Event): boolean {
+		const target = e.target as Element | null;
+		const tr = e.currentTarget as Element;
+		const hit = target?.closest?.(INTERACTIVE);
+		return !!hit && hit !== tr && tr.contains(hit);
+	}
+
+	function onRowClickInternal(row: Row<TData>, rp: DataTableRowProps, e: MouseEvent) {
+		if (isInteractiveTarget(e)) return;
+		rp.onclick?.(e);
+		onRowClick?.(row.original, e);
+		if (internalExpand) toggleExpanded(row.id);
+	}
+
+	function onRowKeydown(row: Row<TData>, e: KeyboardEvent) {
+		if (!internalExpand || e.target !== e.currentTarget) return;
+		if (e.key !== 'Enter' && e.key !== ' ') return;
+		e.preventDefault();
+		toggleExpanded(row.id);
+	}
+
+	/** Normalise `rowProps().attrs`: booleans become `""`/omitted (aria-* stay "true"/"false"). */
+	function rowAttrs(rp: DataTableRowProps): Record<string, string | number | undefined> {
+		const out: Record<string, string | number | undefined> = {};
+		for (const [k, v] of Object.entries(rp.attrs ?? {})) {
+			if (typeof v === 'boolean') out[k] = k.startsWith('aria-') ? String(v) : v ? '' : undefined;
+			else out[k] = v;
+		}
+		return out;
+	}
+
+	const hasRowHandlers = $derived(!!rowProps || !!onRowClick || internalExpand);
 </script>
 
-<div class="datatable-root {className}">
+<div class="datatable-root {className}" bind:this={rootEl}>
 	{#if loading}
 		<div class="overflow-x-auto">
-			<table class="table table-zebra w-full">
+			<table class={tableClasses}>
 				<thead>
 					<tr>
 						{#each allColumns as _}
@@ -155,7 +277,7 @@
 		</div>
 	{:else}
 		<div class="overflow-x-auto">
-			<table class="table table-zebra w-full">
+			<table class={tableClasses}>
 				<thead>
 					{#each headerGroups as headerGroup}
 						<tr>
@@ -175,10 +297,15 @@
 									{@const isSortable = sortable && header.column.getCanSort()}
 									{@const dir = sortDir(header.column.id)}
 									{@const rendered = renderHeader(header)}
+									{@const hp = headerProps?.(header.column.id)}
 									<th
 										style:width={header.getSize() !== 150 ? `${header.getSize()}px` : undefined}
+										class={hp?.class}
 										class:dt-th-sortable={isSortable}
-										onclick={isSortable ? () => header.column.toggleSorting() : undefined}
+										tabindex={isSortable ? 0 : undefined}
+										onclick={isSortable ? (e) => toggleSort(header, e) : undefined}
+										onkeydown={isSortable ? (e) => onHeaderKeydown(header, e) : undefined}
+										oncontextmenu={hp?.oncontextmenu}
 										aria-sort={dir === 'asc' ? 'ascending' : dir === 'desc' ? 'descending' : undefined}
 									>
 										<span class="dt-th-label">
@@ -212,11 +339,33 @@
 				<tbody>
 					{#if rows.length === 0}
 						<tr>
-							<td colspan={allColumns.length} class="dt-empty">No data</td>
+							{#if empty}
+								<td colspan={allColumns.length} class="dt-empty-custom">{@render empty()}</td>
+							{:else}
+								<td colspan={allColumns.length} class="dt-empty">No data</td>
+							{/if}
 						</tr>
 					{:else}
-						{#each rows as row}
-							<tr class:dt-row-selected={row.getIsSelected()}>
+						{#each rows as row, ri (row.id)}
+							{@const rp = rowProps?.(row.original, rowItem(row, ri, rows.length)) ?? {}}
+							{@const attrs = rowAttrs(rp)}
+							{@const expanded = rowIsExpanded(row)}
+							<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+							<tr
+								{...attrs}
+								class={rp.class}
+								class:dt-row-selected={row.getIsSelected()}
+								class:dt-row-clickable={!!rp.onclick || !!onRowClick || internalExpand}
+								class:dt-row-expanded={expanded}
+								data-row-id={getRowId ? row.id : undefined}
+								aria-expanded={expandedRow ? expanded : undefined}
+								tabindex={internalExpand ? (attrs.tabindex ?? 0) : attrs.tabindex}
+								onclick={hasRowHandlers ? (e) => onRowClickInternal(row, rp, e) : undefined}
+								onkeydown={internalExpand ? (e) => onRowKeydown(row, e) : undefined}
+								oncontextmenu={rp.oncontextmenu}
+								ondragover={rp.ondragover}
+								ondrop={rp.ondrop}
+							>
 								{#each row.getVisibleCells() as cell}
 									{#if cell.column.id === '__select'}
 										<td class="dt-select-cell">
@@ -241,12 +390,16 @@
 									{/if}
 								{/each}
 							</tr>
+							{#if expanded && expandedRow}
+								<tr class="dt-expanded-detail" data-detail-for={getRowId ? row.id : undefined}>
+									<td colspan={allColumns.length}>{@render expandedRow(row.original, { colspan: allColumns.length })}</td>
+								</tr>
+							{/if}
 						{/each}
 					{/if}
 				</tbody>
 			</table>
 		</div>
-
 		{#if paginated && pageCount > 1}
 			<div class="dt-pagination">
 				<span class="dt-page-info">
@@ -327,6 +480,14 @@
 		background-color: color-mix(in oklch, var(--color-primary) 6%, transparent) !important;
 	}
 
+	.dt-row-clickable {
+		cursor: pointer;
+	}
+	.dt-row-clickable:focus-visible {
+		outline: 2px solid var(--color-primary);
+		outline-offset: -2px;
+	}
+
 	.dt-select-cell {
 		width: 2.5rem;
 		text-align: center;

package/dist/components/table/DataTable.svelte.d.ts

@@ -1,4 +1,25 @@
 import type { DataTableProps } from './types.js';
-declare const DataTable: import("svelte").Component<DataTableProps<any>, {}, "">;
-type DataTable = ReturnType<typeof DataTable>;
+declare function $$render<TData>(): {
+    props: DataTableProps<TData>;
+    exports: {};
+    bindings: "sorting" | "api";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TData> {
+    props(): ReturnType<typeof $$render<TData>>['props'];
+    events(): ReturnType<typeof $$render<TData>>['events'];
+    slots(): ReturnType<typeof $$render<TData>>['slots'];
+    bindings(): "sorting" | "api";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <TData>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TData>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TData>['props']>, ReturnType<__sveltets_Render<TData>['events']>, ReturnType<__sveltets_Render<TData>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TData>['bindings']>;
+    } & ReturnType<__sveltets_Render<TData>['exports']>;
+    <TData>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const DataTable: $$IsomorphicComponent;
+type DataTable<TData> = InstanceType<typeof DataTable<TData>>;
 export default DataTable;

package/dist/components/table/index.d.ts

@@ -2,4 +2,4 @@ export { default as DataTable } from './DataTable.svelte';
 export { flexRender } from './flexRender';
 export { columnResize } from './columnResize';
 export type { ColumnResizeOptions } from './columnResize';
-export type { DataTableProps, SelectionEvent, ColumnDef, Row } from './types';
+export type { DataTableProps, DataTableApi, DataTableRowProps, DataTableHeaderProps, DataTableSortEvent, DataTableVariant, GroupedItem, SelectionEvent, ColumnDef, Row, SortingState } from './types';

package/dist/components/table/types.d.ts

@@ -1,5 +1,63 @@
-import type { ColumnDef, Row } from '@tanstack/table-core';
-export type { ColumnDef, Row };
+import type { Snippet } from 'svelte';
+import type { ColumnDef, Row, SortingState } from '@tanstack/table-core';
+export type { ColumnDef, Row, SortingState };
+/**
+ * One entry in the table's render list. Today DataTable renders flat rows, so
+ * every item is `kind: 'row'` with `depth: 0`; the `group` variant is the shape
+ * the grouped render list (`groupRows`, design doc
+ * jat/docs/design/datatable-virtualisation-group-rows.md §3.2) will produce, so
+ * `rowProps` callers written now keep working when grouping lands.
+ */
+export type GroupedItem<T = any> = {
+    kind: 'group';
+    key: string;
+    path: string[];
+    depth: number;
+    label: string;
+    rows: T[];
+    count: number;
+    collapsed: boolean;
+} | {
+    kind: 'row';
+    row: T;
+    id: string;
+    depth: number;
+    groupPath: string[];
+    position: 'first' | 'middle' | 'last' | 'only';
+};
+/** What `rowProps` may put on a body `<tr>`. */
+export interface DataTableRowProps {
+    class?: string;
+    /** Extra attributes (`data-*`, `aria-*`, `tabindex`…). `false` omits the attribute. */
+    attrs?: Record<string, string | number | boolean | undefined>;
+    onclick?: (e: MouseEvent) => void;
+    oncontextmenu?: (e: MouseEvent) => void;
+    ondragover?: (e: DragEvent) => void;
+    ondrop?: (e: DragEvent) => void;
+}
+/** What `headerProps` may put on a header `<th>`. */
+export interface DataTableHeaderProps {
+    class?: string;
+    oncontextmenu?: (e: MouseEvent) => void;
+}
+/** Context passed alongside a sorting change: which header, and whether it was a shift-click. */
+export interface DataTableSortEvent {
+    field: string;
+    shiftKey: boolean;
+}
+/** Imperative handle, exposed through `bind:api`. */
+export interface DataTableApi {
+    /** Scroll a row into view (jumping to its page first when paginated). */
+    scrollToRow(id: string, align?: 'auto' | 'start' | 'center'): void;
+    /** Row ids in render order across ALL pages — what keyboard nav should walk. */
+    orderedRowIds(): string[];
+}
+/**
+ * Table skin. `zebra` (default) = DaisyUI `table table-zebra`; `plain` drops the
+ * striping; `unstyled` drops the DaisyUI table classes entirely so the host's
+ * own CSS owns the look.
+ */
+export type DataTableVariant = 'zebra' | 'plain' | 'unstyled';
 export interface DataTableProps<TData = any> {
     /** Row data array */
     data: TData[];
@@ -19,8 +77,53 @@ export interface DataTableProps<TData = any> {
     loadingRows?: number;
     /** Emitted when the selection set changes */
     onSelectionChange?: (rows: TData[]) => void;
-    /** Additional table class */
+    /** Additional class on the root wrapper */
     class?: string;
+    /**
+     * Stable row identity (e.g. a task id). Keys selection, expansion and `api`
+     * by id instead of index, so a poll that reorders `data` keeps state on the
+     * right rows. Also renders `data-row-id` on each body `<tr>`.
+     */
+    getRowId?: (row: TData) => string;
+    /** Controlled sort state — `bind:sorting`. Unbound, the table owns it. */
+    sorting?: SortingState;
+    /** Starting sort state when `sorting` is not supplied (e.g. restored from localStorage). */
+    initialSorting?: SortingState;
+    /**
+     * true = DataTable does not sort; pass `data` already sorted and react to
+     * header clicks through `onSortingChange`. Headers still show the sort state.
+     */
+    manualSorting?: boolean;
+    /** Fires on every header-driven sort change — persist it here. */
+    onSortingChange?: (next: SortingState, ev: DataTableSortEvent) => void;
+    /** Per-row class / attributes / handlers for the body `<tr>`. */
+    rowProps?: (row: TData, item: GroupedItem<TData>) => DataTableRowProps;
+    /**
+     * Shorthand for `rowProps(...).onclick`. Not fired for clicks that land on an
+     * interactive child (input, button, link, select, textarea, label,
+     * contenteditable) — so the select checkbox and inline editors stay inert.
+     */
+    onRowClick?: (row: TData, e: MouseEvent) => void;
+    /** Per-column class / context-menu handler for the header `<th>`. */
+    headerProps?: (columnId: string) => DataTableHeaderProps;
+    /**
+     * Detail row rendered under an expanded row, in one full-width cell.
+     * Without `isExpanded`, the table owns expansion: a row click (or Enter /
+     * Space on the focused row) toggles it.
+     */
+    expandedRow?: Snippet<[TData, {
+        colspan: number;
+    }]>;
+    /** Controlled expansion — when given, the caller owns which rows are open. */
+    isExpanded?: (row: TData) => boolean;
+    /** Replaces the default "No data" cell when `data` is empty. */
+    empty?: Snippet;
+    /** `zebra` (default) | `plain` | `unstyled` — see DataTableVariant. */
+    variant?: DataTableVariant;
+    /** Extra class on the `<table>` element (e.g. `table-sm`). */
+    tableClass?: string;
+    /** Imperative handle — `bind:api`. */
+    api?: DataTableApi;
 }
 export interface SelectionEvent<TData> {
     rows: TData[];

package/dist/index.d.ts

@@ -25,7 +25,7 @@ export { default as Flythrough } from './components/Flythrough.svelte';
 export { default as LessonEmbed } from './components/LessonEmbed.svelte';
 export type { Collection, CollectionCut, CollectionBeat, } from './components/LessonEmbed.svelte';
 export { buildLinkedSession, buildLinkedSessionFromWork, rawTypeToState, sampleLinkedSession, SAMPLE_TRANSCRIPT_LINES, } from './components/session-nav/transcriptModel';
-export type { ItemKind, TranscriptItem, FileTouchedEntry, SignalNode, LinkedSession, WorkBlockClient, WorkTranscriptItemClient, } from './components/session-nav/transcriptModel';
+export type { ItemKind, TranscriptItem, FileTouchedEntry, SignalNode, LinkedSession, WorkBlockClient, WorkTranscriptItemClient, MarkerTone, TimelineMarkerSpec, TimelineMarker, } from './components/session-nav/transcriptModel';
 export { default as UserAvatar } from './components/UserAvatar.svelte';
 export { default as SidebarUserFooter } from './components/SidebarUserFooter.svelte';
 export { default as TaskTypeIcon } from './components/TaskTypeIcon.svelte';

package/dist/index.js

@@ -44,7 +44,8 @@ export { qrMatrix, qrCanvas } from './video/advisors/qr';
 // LessonEmbed renders a demo-assemble collection.json (cut picker + player).
 export { default as Flythrough } from './components/Flythrough.svelte';
 export { default as LessonEmbed } from './components/LessonEmbed.svelte';
-// Data models — Session transcript (from JAT IDE, jat-jj79f.16 G1)
+// Data models — Session transcript (from JAT IDE, jat-jj79f.16 G1; resynced
+// with the IDE's payload/timestamp/live-node/F13-marker model in jatui-ucmkz)
 export { buildLinkedSession, buildLinkedSessionFromWork, rawTypeToState, sampleLinkedSession, SAMPLE_TRANSCRIPT_LINES, } from './components/session-nav/transcriptModel';
 // Components — Universal
 export { default as UserAvatar } from './components/UserAvatar.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",