@immediately-run/grove 0.1.1

package/src/components/Search.tsx

@@ -0,0 +1,127 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Link, useMetadataQuery } from '@immediately-run/sdk';
+import type { Metadata } from '@immediately-run/sdk';
+import { keyToHref } from '../lib/content';
+import { crumb } from '../lib/wiki';
+import { searchQuery } from '../lib/queries';
+import type { SearchRecord } from '../lib/queries';
+import Icon from './Icon';
+
+interface Hit {
+  key: string;
+  title: string;
+  ns: string;
+}
+
+// `.grove-search` — the ⌘K command palette: client-side fuzzy filter over the
+// in-memory index, grouped into entries + tags, keyboard-navigable.
+export default function Search({ onClose }: { onClose: () => void }) {
+  const [query, setQuery] = useState('');
+  const [sel, setSel] = useState(0);
+  const boxRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // Records, not tab-encoded paths (R3-276a): `tags` is the array itself, so the
+  // join/split round-trip is gone.
+  const q = useMetadataQuery<Metadata, SearchRecord>(searchQuery);
+  const rows: SearchRecord[] = Array.isArray(q) ? q : [];
+
+  const rowsKey = rows.map((r) => r.path).join('|');
+  const { entries, tags } = useMemo(() => {
+    const es = rows.map(({ path, title, desc, tags: entryTags }) => ({
+      key: path,
+      title: (title || path).replace(/\.$/, ''),
+      desc: desc || '',
+      tags: entryTags.join(','),
+    }));
+    const tagSet = new Set<string>();
+    es.forEach((e) => e.tags.split(',').filter(Boolean).forEach((t) => tagSet.add(t)));
+    return { entries: es, tags: Array.from(tagSet).sort() };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rowsKey]);
+
+  const ql = query.trim().toLowerCase();
+  const matchedEntries: Hit[] = (ql
+    ? entries.filter(
+        (e) => e.title.toLowerCase().includes(ql) || e.desc.toLowerCase().includes(ql) || e.key.toLowerCase().includes(ql)
+      )
+    : entries.slice(0, 6)
+  ).map((e) => ({ key: e.key, title: e.title, ns: crumb(e.key) }));
+  const matchedTags = ql ? tags.filter((t) => t.toLowerCase().includes(ql)) : [];
+  const total = matchedEntries.length + matchedTags.length;
+
+  useEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+
+  const onKey = (e: React.KeyboardEvent) => {
+    if (e.key === 'Escape') return onClose();
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setSel((s) => Math.min(s + 1, Math.max(0, total - 1)));
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setSel((s) => Math.max(0, s - 1));
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      (boxRef.current?.querySelector('.grove-search__row[data-sel="1"]') as HTMLElement | null)?.click();
+    }
+  };
+
+  return (
+    <div className="grove-search" onClick={onClose}>
+      <div className="grove-search__box" ref={boxRef} onClick={(e) => e.stopPropagation()}>
+        <div className="grove-search__in">
+          <Icon name="search" />
+          <input
+            ref={inputRef}
+            value={query}
+            placeholder="Search entries and tags…"
+            onChange={(e) => {
+              setQuery(e.target.value);
+              setSel(0);
+            }}
+            onKeyDown={onKey}
+          />
+          <kbd>esc</kbd>
+        </div>
+        <div className="grove-search__res">
+          {total === 0 ? (
+            <div className="grove-search__empty">
+              No entry matches <code>{query}</code>.
+            </div>
+          ) : (
+            <>
+              {matchedEntries.length ? <div className="grove-search__grp">{ql ? 'Entries' : 'Recent'}</div> : null}
+              {matchedEntries.map((h, i) => (
+                <Link
+                  key={h.key}
+                  href={keyToHref(h.key)}
+                  className="grove-search__row"
+                  data-sel={sel === i ? '1' : '0'}
+                  onClick={onClose}
+                >
+                  <Icon name="file" />
+                  <span className="t">{h.title}</span>
+                  <span className="c">/{h.ns}</span>
+                </Link>
+              ))}
+              {matchedTags.length ? <div className="grove-search__grp">Tags</div> : null}
+              {matchedTags.map((t, i) => (
+                <div
+                  key={t}
+                  className="grove-search__row"
+                  data-sel={sel === matchedEntries.length + i ? '1' : '0'}
+                  onClick={onClose}
+                >
+                  <Icon name="list" />
+                  <span className="t">#{t}</span>
+                </div>
+              ))}
+            </>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/Sidebar.tsx

@@ -0,0 +1,118 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useContext, useMemo, useState } from 'react';
+import { Link, useMetadataQuery } from '@immediately-run/sdk';
+import type { Metadata } from '@immediately-run/sdk';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { contentDir, keyToHref, sandboxPathToKey } from '../lib/content';
+import { sidebarQuery } from '../lib/queries';
+import type { SidebarRecord } from '../lib/queries';
+import Icon from './Icon';
+
+interface TreeNode {
+  name: string;
+  key?: string; // leaf entry key
+  title?: string;
+  children: Record<string, TreeNode>;
+}
+
+function insert(root: TreeNode, key: string, title: string) {
+  const rel = key.replace(contentDir(), '').replace(/\.mdx?$/, '');
+  const parts = rel.split('/');
+  let node = root;
+  parts.forEach((part, i) => {
+    const leaf = i === parts.length - 1;
+    node.children[part] = node.children[part] || { name: part, children: {} };
+    node = node.children[part];
+    if (leaf) {
+      node.key = key;
+      node.title = title;
+    }
+  });
+}
+
+function hasDescendant(node: TreeNode, key: string): boolean {
+  return Object.values(node.children).some((c) => c.key === key || hasDescendant(c, key));
+}
+
+// A folder (has children) or a leaf entry. Folders are collapsible; the branch
+// holding the current entry starts open.
+function Branch({ node, currentKey, depth }: { node: TreeNode; currentKey: string; depth: number }) {
+  const childKeys = Object.keys(node.children).sort();
+  const isFolder = childKeys.length > 0;
+  const containsCurrent = !!currentKey && (node.key === currentKey || hasDescendant(node, currentKey));
+  const [open, setOpen] = useState(depth < 1 || containsCurrent);
+
+  if (!isFolder) {
+    return (
+      <Link href={keyToHref(node.key!)} className="gs-tree__row" data-cur={node.key === currentKey ? '1' : '0'}>
+        <Icon name="file" />
+        {(node.title || node.name).replace(/\.$/, '')}
+      </Link>
+    );
+  }
+
+  return (
+    <div>
+      <div className="gs-tree__row gs-folder" data-open={open ? '1' : '0'} onClick={() => setOpen((o) => !o)}>
+        <Icon name="chevron-down" className="chev" />
+        {node.name}
+        <span className="ct">{childKeys.length}</span>
+      </div>
+      {open ? (
+        <div className="gs-tree__children">
+          {childKeys.map((k) => (
+            <Branch key={k} node={node.children[k]} currentKey={currentKey} depth={depth + 1} />
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+// `.grove-sidebar` — the wiki shell's left rail: a namespace tree + author-defined
+// `ui/sidebar` sections (a header + a link into the tagged entry).
+export default function Sidebar() {
+  const ctx = useContext(TinkerableContext) as any;
+  const currentKey = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
+
+  // Records, not tab-encoded paths (R3-276a).
+  const q = useMetadataQuery<Metadata, SidebarRecord>(sidebarQuery);
+  const rows: SidebarRecord[] = Array.isArray(q) ? q : [];
+
+  const rowsKey = rows.map((r) => r.path).join('|');
+  const { tree, sections } = useMemo(() => {
+    const root: TreeNode = { name: '', children: {} };
+    const secs: { key: string; label: string }[] = [];
+    rows.forEach(({ path, title, tags, nav }) => {
+      insert(root, path, title);
+      if (tags.includes('ui/sidebar')) secs.push({ key: path, label: nav || title || path });
+    });
+    return { tree: root, sections: secs };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rowsKey]);
+
+  const topKeys = Object.keys(tree.children).sort();
+
+  return (
+    <aside className="grove-sidebar">
+      <div className="gs-block">
+        <div className="gs-block__h">Browse</div>
+        <div className="gs-tree">
+          {topKeys.map((k) => (
+            <Branch key={k} node={tree.children[k]} currentKey={currentKey} depth={0} />
+          ))}
+        </div>
+      </div>
+      {sections.map((s) => (
+        <div className="gs-block" key={s.key}>
+          <div className="gs-block__h">{s.label.replace(/\.$/, '')}</div>
+          <div className="gs-section__body">
+            <Link href={keyToHref(s.key)} className="grove-wikilink" data-state="ok">
+              Open
+            </Link>
+          </div>
+        </div>
+      ))}
+    </aside>
+  );
+}

package/src/components/TableOfContents.test.tsx

@@ -0,0 +1,163 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import TableOfContents from './TableOfContents';
+
+// jsdom performs no layout, so every geometry property this component reads is 0. The
+// numbers are planted instead — which is fine, because the arithmetic itself is proven in
+// `lib/tocScroll.test.ts`. What THIS file proves is the wiring: that the component reads
+// the right elements, moves the right one, and declines when it should.
+
+let ioCallback: ((entries: unknown[]) => void) | null = null;
+class FakeIO {
+  constructor(cb: (entries: unknown[]) => void) {
+    ioCallback = cb;
+  }
+  observe() {}
+  disconnect() {
+    ioCallback = null;
+  }
+}
+
+/** Report a heading as the one the reader is currently in. */
+async function spyTo(id: string) {
+  await act(async () => {
+    ioCallback?.([{ isIntersecting: true, target: document.getElementById(id) }]);
+  });
+}
+
+function plantProse(ids: string[]) {
+  const prose = document.createElement('div');
+  prose.className = 'grove-prose';
+  prose.innerHTML = ids.map((id) => `<h2 id="${id}">${id}</h2>`).join('');
+  document.body.appendChild(prose);
+}
+
+/** Give the rendered list a fake layout: 200px tall over 1000px of content, each row
+ *  20px starting at 40px (below the "On this page" header). */
+function layout(nav: HTMLElement, opts: { viewHeight?: number; scrollHeight?: number } = {}) {
+  Object.defineProperty(nav, 'clientHeight', { value: opts.viewHeight ?? 200, configurable: true });
+  Object.defineProperty(nav, 'scrollHeight', { value: opts.scrollHeight ?? 1000, configurable: true });
+  let top = 0;
+  Object.defineProperty(nav, 'scrollTop', {
+    get: () => top,
+    set: (v) => { top = v; },
+    configurable: true,
+  });
+  nav.querySelectorAll('a').forEach((a, i) => {
+    Object.defineProperty(a, 'offsetTop', { value: 40 + i * 20, configurable: true });
+    Object.defineProperty(a, 'offsetHeight', { value: 20, configurable: true });
+  });
+  return nav;
+}
+
+const IDS = Array.from({ length: 40 }, (_, i) => `sec-${i + 1}`);
+
+let scrollTo: ReturnType<typeof vi.fn>;
+let scrollIntoView: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  ioCallback = null;
+  (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver = FakeIO;
+  scrollTo = vi.fn();
+  scrollIntoView = vi.fn();
+  Element.prototype.scrollTo = scrollTo as never;
+  Element.prototype.scrollIntoView = scrollIntoView as never;
+});
+afterEach(() => {
+  document.body.innerHTML = '';
+  vi.restoreAllMocks();
+});
+
+async function mount(): Promise<HTMLElement> {
+  plantProse(IDS);
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  await act(async () => {
+    createRoot(host).render(<TableOfContents entryKey="/app/content/x.mdx" />);
+  });
+  return layout(host.querySelector('nav')!);
+}
+
+describe('<TableOfContents/>', () => {
+  it('lists the rendered entry’s headings', async () => {
+    const nav = await mount();
+    expect(nav.querySelectorAll('a')).toHaveLength(40);
+    expect(nav.querySelector('.grove-toc__h')?.textContent).toBe('On this page');
+  });
+
+  it('scrolls its OWN container when the active entry is below the fold', async () => {
+    const nav = await mount();
+    await spyTo('sec-30'); // offsetTop 620, bottom 640 — far past a 200px view
+    expect(scrollTo).toHaveBeenCalledTimes(1);
+    expect(scrollTo.mock.calls[0][0]).toMatchObject({ top: 640 + 28 - 200 });
+    // …and on the LIST, not on some ancestor. The whole claim is "its own container".
+    expect(scrollTo.mock.instances[0]).toBe(nav);
+  });
+
+  it('never calls scrollIntoView on a list entry — that would scroll the PAGE', async () => {
+    // The trap this component exists to avoid: `scrollIntoView` walks every scrollable
+    // ancestor, so using it here moves the document and the article jumps under the reader.
+    await mount();
+    await spyTo('sec-30');
+    expect(scrollIntoView).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when the active entry is already in view', async () => {
+    await mount();
+    await spyTo('sec-3'); // offsetTop 80 — comfortably inside a 200px view at scrollTop 0
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when the whole list fits', async () => {
+    plantProse(IDS);
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    await act(async () => {
+      createRoot(host).render(<TableOfContents entryKey="/app/content/x.mdx" />);
+    });
+    layout(host.querySelector('nav')!, { viewHeight: 1000, scrollHeight: 1000 });
+    await spyTo('sec-30');
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+
+  it('does not fight a reader who just scrolled the list by hand', async () => {
+    const nav = await mount();
+    await act(async () => {
+      nav.dispatchEvent(new WheelEvent('wheel', { bubbles: true }));
+    });
+    await spyTo('sec-30');
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+
+  it('marks the active entry for styling and for assistive tech', async () => {
+    const nav = await mount();
+    await spyTo('sec-12');
+    const active = nav.querySelector('a[data-cur="1"]');
+    expect(active?.getAttribute('href')).toBe('#sec-12');
+    expect(active?.getAttribute('aria-current')).toBe('location');
+    expect(nav.querySelectorAll('a[data-cur="1"]')).toHaveLength(1);
+  });
+
+  it('renders nothing for an entry with no sub-headings', async () => {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    await act(async () => {
+      createRoot(host).render(<TableOfContents entryKey="/app/content/empty.mdx" />);
+    });
+    expect(host.querySelector('nav')).toBeNull();
+  });
+
+  it('clicking an entry scrolls the DOCUMENT to that heading, and suspends the auto-scroll', async () => {
+    const nav = await mount();
+    const link = nav.querySelector('a[href="#sec-30"]') as HTMLAnchorElement;
+    await act(async () => {
+      link.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
+    });
+    // The heading, not the list entry.
+    expect(scrollIntoView).toHaveBeenCalledTimes(1);
+    await spyTo('sec-30');
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+});

package/src/components/TableOfContents.tsx

@@ -0,0 +1,101 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { useHeadings, useActiveHeading } from '../hooks/useHeadings';
+import { measure, scrollOffsetFor } from '../lib/tocScroll';
+
+interface Props {
+  /** Re-scan when the rendered entry changes. */
+  entryKey?: string;
+  /** Heading above the list; `null`/`""` renders none. */
+  title?: string | null;
+  /** Extra class on the `<nav>` — how `<Toc>` keeps its rail styling. */
+  className?: string;
+}
+
+/** Breathing room kept between the active entry and the edge it is pulled away from. One
+ *  row's worth: an entry flush against the fold reads as "the last one", and the margin is
+ *  what tells the reader the list continues. */
+const EDGE_MARGIN = 28;
+
+/** How long a manual scroll of the list suppresses the automatic one. Without this the
+ *  reader who scrolls the contents to look ahead is yanked back on the next heading the
+ *  DOCUMENT passes — the list fighting the hand that moved it. */
+const MANUAL_SCROLL_GRACE_MS = 2000;
+
+/**
+ * `<TableOfContents/>` — the on-this-page list, which **keeps the current entry in view**.
+ *
+ * A long entry has a long contents list, and a list taller than its rail scrolls. Without
+ * this the reader scrolls into §12 and the contents still shows §1–§9 with nothing
+ * highlighted: the one surface whose whole job is "where am I" stops answering exactly
+ * when the document is long enough to need it.
+ *
+ * Three things it deliberately does NOT do:
+ *
+ * - **It never scrolls the page.** `scrollIntoView()` walks every scrollable ancestor, so
+ *   the obvious implementation moves the document too — the reader passes a heading and
+ *   the article jumps. This assigns `scrollTop` on its OWN container and nothing else can
+ *   move (`lib/tocScroll`).
+ * - **It does not scroll when the entry is already visible.** Otherwise the list twitches
+ *   on every heading the reader passes.
+ * - **It does not fight the reader.** A manual scroll of the list suspends the automatic
+ *   one briefly.
+ */
+export default function TableOfContents({ entryKey, title = 'On this page', className }: Props) {
+  const heads = useHeadings(entryKey);
+  const cur = useActiveHeading(heads);
+  const listRef = useRef<HTMLElement | null>(null);
+  const itemsRef = useRef(new Map<string, HTMLAnchorElement>());
+  const manualUntilRef = useRef(0);
+
+  const noteManualScroll = useCallback(() => {
+    manualUntilRef.current = Date.now() + MANUAL_SCROLL_GRACE_MS;
+  }, []);
+
+  useEffect(() => {
+    const list = listRef.current;
+    const item = cur ? itemsRef.current.get(cur) : undefined;
+    if (!list || !item) return;
+    if (Date.now() < manualUntilRef.current) return;
+    const offset = scrollOffsetFor(...measure(list, item), { margin: EDGE_MARGIN });
+    if (offset === null) return; // already in view — "when necessary"
+    // `scroll()` on the element, never `scrollIntoView()` on the item: only this container
+    // may move. Motion is opt-out — a reader who asked the OS for less of it gets a jump.
+    const reduced = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+    list.scrollTo({ top: offset, behavior: reduced ? 'auto' : 'smooth' });
+  }, [cur]);
+
+  if (!heads.length) return null;
+
+  return (
+    <nav
+      ref={listRef}
+      className={['grove-toc', className].filter(Boolean).join(' ')}
+      aria-label={title || 'On this page'}
+      onWheel={noteManualScroll}
+      onTouchMove={noteManualScroll}
+    >
+      {title ? <div className="grove-toc__h">{title}</div> : null}
+      {heads.map((h) => (
+        <a
+          key={h.id}
+          ref={(el) => {
+            if (el) itemsRef.current.set(h.id, el);
+            else itemsRef.current.delete(h.id);
+          }}
+          href={`#${h.id}`}
+          data-cur={cur === h.id ? '1' : '0'}
+          aria-current={cur === h.id ? 'location' : undefined}
+          className={h.level === 3 ? 'lvl3' : undefined}
+          onClick={(e) => {
+            e.preventDefault();
+            // Clicking IS the reader moving the list, so don't also auto-scroll it.
+            noteManualScroll();
+            document.getElementById(h.id)?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+          }}
+        >
+          {h.text}
+        </a>
+      ))}
+    </nav>
+  );
+}

package/src/components/TagCloud.tsx

@@ -0,0 +1,46 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useCallback } from 'react';
+import { useMetadataQuery } from '@immediately-run/sdk';
+import { contentDir } from '../lib/content';
+import { queryPaths } from '../lib/wiki';
+
+// Import-free engine component: every tag across the site, sized by frequency.
+// Chrome tags (`ui/*`) are excluded — they drive layout, not classification.
+export default function TagCloud() {
+  const queryFn = useCallback((filesMetadata: Record<string, any>) => {
+    const counts: Record<string, number> = {};
+    Object.entries(filesMetadata).forEach(([p, m]) => {
+      if (!p.startsWith(contentDir())) return;
+      if (m && Array.isArray(m.tags)) {
+        m.tags.forEach((t: string) => {
+          if (t.startsWith('ui/')) return;
+          counts[t] = (counts[t] || 0) + 1;
+        });
+      }
+    });
+    // Encode counts into the string[] the query contract returns.
+    return Object.keys(counts)
+      .sort()
+      .map((t) => `${t}:${counts[t]}`);
+  }, []);
+
+  const result = useMetadataQuery(queryFn);
+  const entries: string[] = queryPaths(result);
+
+  return (
+    <div className="grove-tagcloud">
+      {entries.map((e) => {
+        const [tag, count] = e.split(':');
+        return (
+          <span
+            key={tag}
+            className="grove-tag"
+            style={{ fontSize: 11 + Number(count) * 2 + 'px', padding: '4px 12px' }}
+          >
+            #{tag} <span style={{ opacity: 0.5, marginLeft: 4 }}>{count}</span>
+          </span>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/TagList.tsx

@@ -0,0 +1,31 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useCallback } from 'react';
+import { useMetadataQuery } from '@immediately-run/sdk';
+import { contentDir } from '../lib/content';
+import { queryPaths } from '../lib/wiki';
+
+// `<TagList/>` — every content tag, sorted, as plain chips (the "related tags"
+// strip on a tag page). Reserved `ui/*` chrome tags are excluded.
+export default function TagList() {
+  const queryFn = useCallback((fm: Record<string, any>) => {
+    const set = new Set<string>();
+    Object.entries(fm).forEach(([p, m]: [string, any]) => {
+      if (!p.startsWith(contentDir())) return;
+      (Array.isArray(m?.tags) ? m.tags : []).forEach((t: string) => {
+        if (!t.startsWith('ui/')) set.add(t);
+      });
+    });
+    return Array.from(set).sort();
+  }, []);
+  const q = useMetadataQuery(queryFn);
+  const tags: string[] = queryPaths(q);
+
+  if (!tags.length) return null;
+  return (
+    <div className="grove-tagcloud">
+      {tags.map((t) => (
+        <span key={t} className="grove-tag">#{t}</span>
+      ))}
+    </div>
+  );
+}

package/src/components/Timeline.tsx

@@ -0,0 +1,55 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useCallback } from 'react';
+import { Link, useFileMetadata, useMetadataQuery } from '@immediately-run/sdk';
+import { isContentEntry, keyToHref } from '../lib/content';
+import { queryPaths } from '../lib/wiki';
+
+// One dated entry on the axis: mono date · node · card.
+function Row({ path }: { path: string }) {
+  const m = useFileMetadata(path) as any;
+  if (!m) return null;
+  const tags: string[] = Array.isArray(m.tags) ? m.tags.filter((t: string) => !t.startsWith('ui/')) : [];
+  return (
+    <Link href={keyToHref(path)} className="gtl-row">
+      <div className="gtl-date">{m.date}</div>
+      <div className="gtl-node" />
+      <div className="gtl-card">
+        <div className="gtl-title">{(m.title || path).replace(/\.$/, '')}</div>
+        {m.description && <div className="gtl-desc">{m.description}</div>}
+        {tags.length ? (
+          <div className="gtl-tags">
+            {tags.slice(0, 3).map((t) => (
+              <span key={t} className="grove-tag">#{t}</span>
+            ))}
+          </div>
+        ) : null}
+      </div>
+    </Link>
+  );
+}
+
+// `<Timeline/>` — an agent-added view: every entry with a `date`, laid on a time
+// axis newest-first, with a restrained per-row reveal (CSS `gtlin`).
+export default function Timeline() {
+  const queryFn = useCallback(
+    (fm: Record<string, any>) =>
+      Object.keys(fm)
+        .filter((p) => isContentEntry(p) && fm[p]?.date && !fm[p]?.view)
+        .sort((a, b) => String(fm[b].date).localeCompare(String(fm[a].date))),
+    []
+  );
+  const q = useMetadataQuery(queryFn);
+  const loaded = Array.isArray(q);
+  const paths: string[] = queryPaths(q);
+
+  if (loaded && !paths.length) {
+    return <p className="grove-search__empty">No dated entries yet.</p>;
+  }
+  return (
+    <div className="grove-timeline">
+      {paths.map((p) => (
+        <Row key={p} path={p} />
+      ))}
+    </div>
+  );
+}

package/src/components/Toc.tsx

@@ -0,0 +1,14 @@
+import TableOfContents from './TableOfContents';
+
+// `<Toc/>` — the on-this-page rail, and the name every existing layout and entry uses.
+//
+// It is now an alias for `<TableOfContents/>`, which is the same list plus "keep the
+// current entry in view". Kept as its own name rather than rewritten at the call sites
+// because `Toc` is registered content vocabulary: a corpus may already say `<Toc/>`, and
+// the engine's names are an interface (spec_style's §-number rule, applied to components).
+//
+// Deliberately NOT a second implementation. The two used to be one copy of the DOM scan
+// each, which is precisely the drift ENGINE_BOUNDARY §4 was written about.
+export default function Toc({ entryKey }: { entryKey?: string }) {
+  return <TableOfContents entryKey={entryKey} />;
+}