@immediately-run/grove 0.1.1

package/src/components/DocList.tsx

@@ -0,0 +1,109 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useCallback } from 'react';
+import { Link, useFileMetadata, useMetadataQuery } from '@immediately-run/sdk';
+import { isContentEntry, keyToHref, slugToKey } from '../lib/content';
+import { queryPaths } from '../lib/wiki';
+
+interface Props {
+  shape?: 'feed' | 'grid';
+  title?: string | null;
+  slugs?: string;
+  tag?: string;
+  limit?: string | number;
+  sort?: 'date' | 'title';
+}
+
+function tagsOf(meta: any): string[] {
+  return Array.isArray(meta?.tags) ? meta.tags.filter((t: string) => !t.startsWith('ui/')) : [];
+}
+
+// One entry as a feed row — reads its own frontmatter so the hook count is stable.
+function Row({ path }: { path: string }) {
+  const meta = useFileMetadata(path) as any;
+  if (!meta) return <div className="gdl-row"><div className="sk sk-line" style={{ width: '50%' }} /></div>;
+  return (
+    <Link href={keyToHref(path)} className="gdl-row">
+      <div>
+        <div className="gdl-row__t">{(meta.title || path).replace(/\.$/, '')}</div>
+        {meta.description && <div className="gdl-row__d">{meta.description}</div>}
+        <div className="gdl-row__tags">
+          {tagsOf(meta).slice(0, 3).map((t) => (
+            <span key={t} className="grove-tag">#{t}</span>
+          ))}
+        </div>
+      </div>
+      <div className="gdl-row__meta">{meta.date}</div>
+    </Link>
+  );
+}
+
+// One entry as a grid card — link-graph placeholder pic + a footer of meta.
+function CardTile({ path }: { path: string }) {
+  const meta = useFileMetadata(path) as any;
+  if (!meta) return <div className="gdl-card"><div className="gdl-card__pic" /></div>;
+  return (
+    <Link href={keyToHref(path)} className="gdl-card">
+      <div className="gdl-card__pic" />
+      <div className="gdl-card__foot">
+        <div className="gdl-card__t">{(meta.title || path).replace(/\.$/, '')}</div>
+        {meta.description && <div className="gdl-card__d">{meta.description}</div>}
+        <div className="gdl-card__tags">
+          {tagsOf(meta).slice(0, 3).map((t) => (
+            <span key={t} className="grove-tag">#{t}</span>
+          ))}
+        </div>
+      </div>
+    </Link>
+  );
+}
+
+// Import-free engine component: a frontmatter-driven index of entries, in a feed
+// or grid shape. `slugs` pins an explicit ordered set; otherwise it queries the
+// whole content space (optionally filtered by `tag`), excluding view/index pages.
+export default function DocList({ shape = 'feed', title, slugs, tag, limit, sort = 'date' }: Props) {
+  const queryFn = useCallback(
+    (fm: Record<string, any>) => {
+      const keys = Object.keys(fm).filter((p) => {
+        if (!isContentEntry(p)) return false;
+        const m = fm[p] || {};
+        if (m.view) return false;
+        if (tag && !(Array.isArray(m.tags) && m.tags.includes(tag))) return false;
+        return true;
+      });
+      keys.sort((a, b) => {
+        if (sort === 'title') return (fm[a].title || a) < (fm[b].title || b) ? -1 : 1;
+        return String(fm[b].date || '').localeCompare(String(fm[a].date || ''));
+      });
+      return keys;
+    },
+    [tag, sort]
+  );
+  const queried = useMetadataQuery(queryFn);
+  const loaded = Array.isArray(queried);
+
+  let paths: string[] = slugs
+    ? slugs.split(',').map((s) => slugToKey(s.trim())).filter(Boolean)
+    : queryPaths(queried);
+  const n = limit ? Number(limit) : undefined;
+  if (n && paths.length > n) paths = paths.slice(0, n);
+
+  return (
+    <div className="grove-doclist-wrap">
+      {title ? (
+        <div className="grove-doclist__head">
+          <h2>{title}</h2>
+          <span className="n">{paths.length} {paths.length === 1 ? 'entry' : 'entries'}</span>
+        </div>
+      ) : null}
+      {!slugs && loaded && paths.length === 0 ? (
+        <p className="grove-search__empty">No entries yet.</p>
+      ) : (
+        <div className="grove-doclist" data-shape={shape}>
+          {paths.map((p: string) =>
+            shape === 'grid' ? <CardTile key={p} path={p} /> : <Row key={p} path={p} />
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/DocsByTag.tsx

@@ -0,0 +1,13 @@
+import DocList from './DocList';
+
+// `<DocsByTag tag>` — the body of a tag page: a `#tag` header + the filtered feed.
+export default function DocsByTag({ tag, shape = 'feed' }: { tag: string; shape?: 'feed' | 'grid' }) {
+  return (
+    <div>
+      <div className="grove-doclist__head">
+        <h2><span className="grove-tag" data-active="1">#{tag}</span></h2>
+      </div>
+      <DocList shape={shape} tag={tag} />
+    </div>
+  );
+}

package/src/components/Drawer.tsx

@@ -0,0 +1,45 @@
+import { Link } from '@immediately-run/sdk';
+import Sidebar from './Sidebar';
+import Icon from './Icon';
+
+interface NavItem {
+  href: string;
+  label: string;
+  cur: boolean;
+}
+
+// `.grove-drawer` — the mobile nav drawer: site mark + nav items + the full
+// namespace tree, over a dismiss scrim.
+export default function Drawer({
+  siteTitle,
+  nav,
+  onClose,
+}: {
+  siteTitle: string;
+  nav: NavItem[];
+  onClose: () => void;
+}) {
+  return (
+    <div className="grove-drawer" onClick={onClose}>
+      <div className="grove-drawer__panel" onClick={(e) => e.stopPropagation()}>
+        <div className="grove-drawer__h">
+          <span className="mk" />
+          <span className="t">{siteTitle}</span>
+          <button className="x" aria-label="Close menu" onClick={onClose}>
+            <Icon name="x" />
+          </button>
+        </div>
+        {nav.length ? (
+          <nav className="grove-drawer__nav">
+            {nav.map((n) => (
+              <Link key={n.href} href={n.href} data-cur={n.cur ? '1' : '0'} onClick={onClose}>
+                {n.label}
+              </Link>
+            ))}
+          </nav>
+        ) : null}
+        <Sidebar />
+      </div>
+    </div>
+  );
+}

package/src/components/EntryHeader.tsx

@@ -0,0 +1,51 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useState } from 'react';
+import { requestEdit, useFileMetadata } from '@immediately-run/sdk';
+import { keyToRepoRel } from '../lib/content';
+import { crumb } from '../lib/wiki';
+import Icon from './Icon';
+
+// The entry's header block: breadcrumb, title (optional gradient), meta row
+// (date · reading time · tags) and the unobtrusive edit affordance. Rendered by
+// <PageView> at the top of every entry.
+export default function EntryHeader({
+  entryKey,
+  writable,
+  mins,
+}: {
+  entryKey: string;
+  writable: boolean;
+  mins: number;
+}) {
+  const meta = useFileMetadata(entryKey) as any;
+  const [busy, setBusy] = useState(false);
+  if (!meta) return null;
+  const tags: string[] = Array.isArray(meta.tags) ? meta.tags.filter((t: string) => !t.startsWith('ui/')) : [];
+  const cr = crumb(entryKey);
+  const edit = () => {
+    setBusy(true);
+    requestEdit({ path: keyToRepoRel(entryKey) })
+      .catch(() => undefined)
+      .finally(() => setBusy(false));
+  };
+  return (
+    <header className="grove-entry-header">
+      {cr.includes('/') ? <nav className="crumb">{cr}</nav> : null}
+      <h1 className={meta.grad ? 'grad' : ''}>{meta.title || cr}</h1>
+      <div className="grove-meta">
+        {meta.date && <span>{meta.date}</span>}
+        {mins ? <span>→ {mins} min read</span> : null}
+        {tags.length ? <span className="dot">·</span> : null}
+        {tags.map((t) => (
+          <span key={t} className="grove-tag">#{t}</span>
+        ))}
+        {writable && (
+          <button className="grove-edit-affordance" data-busy={busy ? '1' : '0'} onClick={edit}>
+            <Icon name="pencil" />
+            {busy ? 'Opening editor…' : 'Edit'}
+          </button>
+        )}
+      </div>
+    </header>
+  );
+}

package/src/components/FamilyTree.tsx

@@ -0,0 +1,95 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useContext } from 'react';
+import { useMetadataQuery } from '@immediately-run/sdk';
+import type { Metadata } from '@immediately-run/sdk';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { sandboxPathToKey } from '../lib/content';
+import { familyTreeQuery } from '../lib/queries';
+import type { FamilyNodeRecord } from '../lib/queries';
+
+interface Node {
+  id: string;
+  label: string;
+  group: string;
+  x: number;
+  y: number;
+}
+
+// `<FamilyTree/>` — the relational extension view. Reads each entry's relationship
+// frontmatter (`parent`/`manager`/`team`) and draws the link-graph motif made
+// literal: group hubs joined by hairline edges to their members. Genealogy
+// (`parent`/`house`) and org charts (`team`/`manager`) share the same rendering.
+export default function FamilyTree() {
+  const ctx = useContext(TinkerableContext) as any;
+  const currentKey = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
+
+  // Records, not tab-encoded paths (R3-276a).
+  const q = useMetadataQuery<Metadata, FamilyNodeRecord>(familyTreeQuery);
+  const rows: FamilyNodeRecord[] = Array.isArray(q) ? q : [];
+
+  if (!rows.length) {
+    return <p className="grove-search__empty">No relationships defined.</p>;
+  }
+
+  // Deterministic layout: hubs evenly across the width, members stacked beneath.
+  const groups: Record<string, typeof rows> = {};
+  rows.forEach((r: any) => (groups[r.group] = groups[r.group] || []).push(r));
+  const groupNames = Object.keys(groups).sort();
+  const W = 720;
+  const colW = W / groupNames.length;
+  const hubs: Node[] = [];
+  const members: Node[] = [];
+  const edges: { x1: number; y1: number; x2: number; y2: number; cur: boolean }[] = [];
+  groupNames.forEach((g, gi) => {
+    const cx = colW * gi + colW / 2;
+    const hub: Node = { id: g, label: g, group: g, x: cx, y: 46 };
+    hubs.push(hub);
+    groups[g].forEach((m: any, mi: number) => {
+      const my = 120 + mi * 46;
+      const mn: Node = { id: m.path, label: m.label, group: g, x: cx, y: my };
+      members.push(mn);
+      edges.push({ x1: cx, y1: 56, x2: cx, y2: my, cur: m.path === currentKey });
+    });
+  });
+  const maxRows = Math.max(...groupNames.map((g) => groups[g].length));
+  const H = 120 + maxRows * 46;
+
+  return (
+    <div className="grove-graph">
+      <svg viewBox={`0 0 ${W} ${H}`} width="100%" style={{ maxWidth: W }}>
+        {edges.map((e, i) => (
+          <line
+            key={i}
+            x1={e.x1}
+            y1={e.y1}
+            x2={e.x2}
+            y2={e.y2}
+            stroke={e.cur ? 'var(--accent)' : 'var(--line-2)'}
+            strokeWidth={1}
+          />
+        ))}
+        {hubs.map((h) => (
+          <g key={h.id}>
+            <circle cx={h.x} cy={h.y} r={7} fill="var(--accent-violet)" />
+            <text x={h.x} y={h.y - 14} textAnchor="middle" fill="var(--ink)" fontSize={13} fontFamily="var(--disp)">
+              {h.label}
+            </text>
+          </g>
+        ))}
+        {members.map((m) => (
+          <g key={m.id}>
+            <circle
+              cx={m.x}
+              cy={m.y}
+              r={5}
+              fill={m.id === currentKey ? 'var(--accent)' : 'var(--ink-3)'}
+            />
+            <text x={m.x + 12} y={m.y + 4} fill="var(--ink-2)" fontSize={12} fontFamily="var(--sans)">
+              {m.label}
+            </text>
+          </g>
+        ))}
+      </svg>
+    </div>
+  );
+}

package/src/components/GroveAgent.tsx

@@ -0,0 +1,264 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useEffect, useRef, useState } from 'react';
+import { chat, requestEdit, useChatProvider } from '@immediately-run/sdk';
+import { keyToRepoRel } from '../lib/content';
+import Icon from './Icon';
+
+interface Msg {
+  role: 'user' | 'assistant';
+  text: string;
+}
+
+type Banner = null | 'no-key' | 'forbidden' | 'read-only' | 'error';
+
+const CHIPS = [
+  'Add an entry…',
+  'Fix broken links here',
+  'Summarize this entry',
+  'Reorganize the sidebar',
+  'Add a timeline view',
+];
+
+// `.grove-agent` (brief 06) — Grove's own, always-present, capability-scoped agent.
+// Resting state: the thin "Ask Grove…" input line pinned to the bottom (approach 1,
+// the recommended posture — content stays fully visible until invoked). Expands into
+// a bottom dock (desktop) / sheet (mobile). Rides the host `llm.chat@1` slot via the
+// SDK `chat()` stream; degrades to the SP-7 connect-a-key / forbidden / read-only
+// banners rather than faking a host surface.
+export default function GroveAgent({ writable, entryKey, entryTitle }: { writable: boolean; entryKey: string; entryTitle: string }) {
+  const provider = useChatProvider();
+  const [open, setOpen] = useState(false);
+  const [detent, setDetent] = useState<'half' | 'full'>('half');
+  const [resting, setResting] = useState('');
+  const [draft, setDraft] = useState('');
+  const [msgs, setMsgs] = useState<Msg[]>([]);
+  const [streaming, setStreaming] = useState(false);
+  const [sendBanner, setSendBanner] = useState<Banner>(null);
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const footRef = useRef<HTMLInputElement>(null);
+
+  // Derived banner: read-only (no write grant) / no-key (no provider bound, SP-7)
+  // come straight from props+provider; send-time errors layer on top.
+  const staticBanner: Banner = !writable ? 'read-only' : provider === null ? 'no-key' : null;
+  const banner: Banner = sendBanner || staticBanner;
+
+  useEffect(() => {
+    if (open) requestAnimationFrame(() => footRef.current?.focus());
+  }, [open]);
+  useEffect(() => {
+    bodyRef.current?.scrollTo({ top: bodyRef.current.scrollHeight });
+  }, [msgs, streaming]);
+
+  async function send(text: string) {
+    const q = text.trim();
+    if (!q || streaming) return;
+    setOpen(true);
+    setDraft('');
+    setResting('');
+    const history = [...msgs, { role: 'user' as const, text: q }];
+    setMsgs([...history, { role: 'assistant', text: '' }]);
+    setStreaming(true);
+    setSendBanner(null);
+
+    try {
+      const req = {
+        messages: [
+          {
+            role: 'system' as const,
+            content: [
+              {
+                type: 'text' as const,
+                text: `You are Grove, the embedded agent for this MDX wiki. Entries live as .mdx files under /content and interlink with markdown links and frontmatter tags. The reader is currently on "${entryTitle}". Be concise and wiki-fluent; when you propose changes, describe them plainly. You never see secrets and privileged writes are confirmed by the host.`,
+              },
+            ],
+          },
+          ...history.map((m) => ({
+            role: m.role,
+            content: [{ type: 'text' as const, text: m.text }],
+          })),
+        ],
+        modelHint: 'smart' as const,
+      };
+      let acc = '';
+      for await (const d of chat(req)) {
+        if (d.type === 'text-delta') {
+          acc += d.text;
+          setMsgs((prev) => {
+            const next = prev.slice();
+            next[next.length - 1] = { role: 'assistant', text: acc };
+            return next;
+          });
+        }
+      }
+      if (!acc) throw new Error('empty');
+    } catch (e: any) {
+      const code = e?.code || e?.message;
+      setSendBanner(code === 'auth-required' ? 'no-key' : code === 'forbidden' ? 'forbidden' : 'error');
+      // Drop the empty assistant placeholder.
+      setMsgs((prev) => (prev.length && prev[prev.length - 1].text === '' ? prev.slice(0, -1) : prev));
+    } finally {
+      setStreaming(false);
+    }
+  }
+
+  const restingDisabled = banner === 'read-only';
+
+  return (
+    <div className="grove-agent">
+      {/* Resting: the always-present thin input line (approach 1). */}
+      {!open && (
+        <form
+          className="ga-line"
+          onSubmit={(e) => {
+            e.preventDefault();
+            if (restingDisabled) setOpen(true);
+            else send(resting);
+          }}
+        >
+          <span className="mk" />
+          <input
+            value={resting}
+            placeholder={restingDisabled ? 'Ask Grove about this wiki…' : `Ask Grove to change "${entryTitle}"…`}
+            onChange={(e) => setResting(e.target.value)}
+            onFocus={() => setOpen(true)}
+            aria-label="Ask Grove"
+          />
+          <button className="go" type="submit" aria-label="Ask Grove">
+            <Icon name="send" />
+          </button>
+        </form>
+      )}
+
+      {/* Expanded: dock (desktop) / sheet (mobile). */}
+      {open && (
+        <>
+          <div className="ga-scrim" onClick={() => setOpen(false)} />
+          <div className="ga-panel" data-detent={detent}>
+            <div className="ga-panel-inner">
+              <div className="ga-head">
+                <span className="grip" onClick={() => setDetent((d) => (d === 'half' ? 'full' : 'half'))} />
+                <span className="mk" />
+                <span className="id">Grove</span>
+                <span className="scope">
+                  <Icon name="shield" />
+                  scoped to this wiki
+                </span>
+                <span className="grow">
+                  <button className="ic" aria-label={detent === 'half' ? 'Expand' : 'Collapse'} onClick={() => setDetent((d) => (d === 'half' ? 'full' : 'half'))}>
+                    <Icon name={detent === 'half' ? 'chevron-down' : 'chevron-right'} />
+                  </button>
+                  <button className="ic" aria-label="Close" onClick={() => setOpen(false)}>
+                    <Icon name="x" />
+                  </button>
+                </span>
+              </div>
+
+              {banner && <AgentBanner banner={banner} />}
+
+              <div className="ga-body" ref={bodyRef}>
+                {msgs.length === 0 ? (
+                  <>
+                    <div className="ga-explain">
+                      <b>Grove's agent</b> knows this wiki's entries, tags, and components. Ask it to add or
+                      change content in plain language — it proposes the edit, and the host confirms the write.
+                    </div>
+                    {!restingDisabled && (
+                      <div className="ga-chips">
+                        {CHIPS.map((c) => (
+                          <button key={c} className="ga-chip" onClick={() => send(c)}>
+                            {c}
+                          </button>
+                        ))}
+                      </div>
+                    )}
+                  </>
+                ) : (
+                  msgs.map((m, i) => (
+                    <div key={i} className={`ga-msg ${m.role}`}>
+                      <span className={`ga-msg__av ${m.role === 'assistant' ? 'grove' : 'user'}`}>
+                        {m.role === 'user' ? 'you' : ''}
+                      </span>
+                      <div className="ga-msg__b">
+                        <div className="ga-msg__who">{m.role === 'assistant' ? 'Grove' : 'You'}</div>
+                        <div className="ga-msg__txt">
+                          {m.text}
+                          {streaming && i === msgs.length - 1 && m.role === 'assistant' ? <span className="ga-cursor" /> : null}
+                        </div>
+                      </div>
+                    </div>
+                  ))
+                )}
+              </div>
+
+              <div className="ga-foot">
+                <form
+                  className="ga-foot__row"
+                  onSubmit={(e) => {
+                    e.preventDefault();
+                    send(draft);
+                  }}
+                >
+                  <input
+                    ref={footRef}
+                    value={draft}
+                    placeholder="Ask Grove…"
+                    disabled={streaming || restingDisabled}
+                    onChange={(e) => setDraft(e.target.value)}
+                  />
+                  <button className="go" type="submit" disabled={streaming || restingDisabled || !draft.trim()} aria-label="Send">
+                    <Icon name={streaming ? 'stop' : 'send'} />
+                  </button>
+                </form>
+                <div className="ga-foot__hand">
+                  <span>Grove's own agent · scoped to your grants</span>
+                  <a
+                    onClick={() => requestEdit({ path: keyToRepoRel(entryKey) }).catch(() => undefined)}
+                    role="button"
+                    tabIndex={0}
+                  >
+                    <Icon name="external" />
+                    Open in the workbench
+                  </a>
+                </div>
+              </div>
+            </div>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
+
+// The no-key / forbidden / read-only / error states — calm explanations that hand
+// to the host secret flow rather than faking a key prompt.
+function AgentBanner({ banner }: { banner: Banner }) {
+  const copy: Record<string, { t: string; d: React.ReactNode }> = {
+    'no-key': {
+      t: 'Connect a key to use the agent.',
+      d: 'Grove rides whichever model provider you connect in the host. Add a key to start asking.',
+    },
+    forbidden: {
+      t: 'The agent isn’t available here.',
+      d: "This Grove wasn't granted the chat capability. Reading still works as normal.",
+    },
+    'read-only': {
+      t: 'You’re viewing read-only.',
+      d: 'The agent can explain this wiki, but changes need write access to this space.',
+    },
+    error: {
+      t: 'The agent hit a snag.',
+      d: 'The model or backend errored. Try again in a moment.',
+    },
+  };
+  const c = copy[banner as string];
+  if (!c) return null;
+  return (
+    <div className="ga-banner">
+      <Icon name="alert" />
+      <div>
+        <div className="ga-banner__t">{c.t}</div>
+        <div className="ga-banner__d">{c.d}</div>
+      </div>
+    </div>
+  );
+}

package/src/components/GroveFooter.tsx

@@ -0,0 +1,20 @@
+import { Link } from '@immediately-run/sdk';
+import { useShell } from '../lib/shell';
+
+// `<GroveFooter/>` — the site footer. Import-free in MDX; reads the nav items from
+// the shell context so a layout just places `<GroveFooter/>`.
+export default function GroveFooter() {
+  const { navItems } = useShell();
+  return (
+    <footer className="grove-footer">
+      <div className="grove-footer__links">
+        {navItems.slice(0, 4).map((n) => (
+          <Link key={n.key} href={n.href}>
+            {n.label}
+          </Link>
+        ))}
+      </div>
+      <div className="grove-footer__meta">built with grove</div>
+    </footer>
+  );
+}