@immediately-run/grove 0.1.1

package/src/GroveWiki.tsx

@@ -0,0 +1,386 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useCallback, useContext, useEffect, useState } from 'react';
+import type { ReactNode } from 'react';
+import fs from 'fs';
+import type { Metadata } from '@immediately-run/sdk';
+import {
+  Include,
+  useAllMetadata,
+  useFileMetadata,
+  useMetadataQuery,
+  useMounts,
+} from '@immediately-run/sdk';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { LinkSpaceContext } from '@immediately-run/sdk/linkSpace';
+import { CorpusContext, toCorpusPath, fromCorpusPath } from '@immediately-run/sdk/corpus';
+import {
+  contentDir,
+  homeKey,
+  isContentEntry,
+  keyToFsPath,
+  keyToHref,
+  keyToInclude,
+  sandboxPathToKey,
+} from './lib/content';
+import { queryPaths, queryRecords, readingTime, stripFrontmatter } from './lib/wiki';
+import { navQuery } from './lib/queries';
+import type { NavRecord } from './lib/queries';
+import { layoutChainForKey } from './lib/layout';
+import { folderIndexKey } from './lib/directory';
+import { useDirectoryListing } from './hooks/useDirectoryListing';
+import { getContentRoot, isDispatched } from './lib/contentRoot';
+import type { RejectedComponent } from './lib/corpusComponents';
+import { GroveShellContext, OutletContext } from './lib/shell';
+import type { GroveShell, NavItem } from './lib/shell';
+import PageView from './components/PageView';
+import SafeLayout from './components/SafeLayout';
+import DefaultLayout from './components/DefaultLayout';
+import Search from './components/Search';
+import Drawer from './components/Drawer';
+import GroveAgent from './components/GroveAgent';
+
+declare const module: any;
+
+function readPref(k: string): string | null {
+  try {
+    return localStorage.getItem(k);
+  } catch {
+    return null;
+  }
+}
+function writePref(k: string, v: string): void {
+  try {
+    localStorage.setItem(k, v);
+  } catch {
+    /* ignore */
+  }
+}
+
+// Corpus-absolute path → the href that navigates to it, for CONTENT (R3-174).
+//
+// Module scope, and that is load-bearing rather than tidiness: this function is handed to
+// content through `CorpusContext`, and the SDK's `useCorpusEntries` memoizes on its
+// identity. A closure rebuilt each render would make that memo never hold, so the hook the
+// SDK documents as "safe in a dependency array" would quietly stop being one — from the
+// PROVIDER's side, where nobody using it would think to look. Nothing here is reactive:
+// `contentDir()` is boot-settled module state and `keyToHref` is a pure function of it.
+function corpusHref(corpusPath: string): string {
+  const absolute = fromCorpusPath(corpusPath, contentDir().replace(/\/+$/, ''));
+  return absolute === null ? corpusPath : keyToHref(absolute);
+}
+
+// Build the nested render for a layout chain (outermost first). Each layer wraps
+// its `_layout.mdx` (or the built-in <DefaultLayout/>) in an OutletContext whose
+// value is the node one level inward — so `<Outlet/>` inside a layer renders the
+// next layer, and the innermost <Outlet/> renders the page (<PageView/>).
+//
+// `safe` picks the RENDERER for each layer, exactly as it does for entry bodies in
+// <PageView/> (R3-263). Before this, every layer went through <Include> whatever the wiki
+// declared — so an interpreter-mode wiki still EXECUTED author JavaScript out of its
+// `_layout.mdx`, and the non-executable guarantee had a hole in the shell rather than in
+// the entries. It is also what makes the chain work at all under dispatch: <Include>
+// evaluates an app-source module, which a layout resident in a content mount is not.
+function renderLayers(chain: string[], useDefault: boolean, safe: boolean): ReactNode {
+  let node: ReactNode = <PageView />;
+  if (useDefault) {
+    return <OutletContext.Provider value={node}><DefaultLayout /></OutletContext.Provider>;
+  }
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const inner = node;
+    node = (
+      <OutletContext.Provider value={inner} key={chain[i]}>
+        {safe ? <SafeLayout layoutKey={chain[i]} /> : <Include filename={chain[i]} baseModule={module} />}
+      </OutletContext.Provider>
+    );
+  }
+  return node;
+}
+
+/**
+ * The wiki itself: routing, chrome, and the entry render. Everything here reads the
+ * content root, so it may only mount once that root is settled — which is why the
+ * default export of `App.tsx` is a gate in front of it rather than this component
+ * (R3-169: under dispatch the root is a runtime value, not `/app/content/`).
+ */
+export default function GroveWiki({
+  readOnly = false,
+  rejectedComponents = [],
+}: {
+  readOnly?: boolean;
+  /** Corpus component declarations that could not be loaded (R3-174). Shown, not
+   *  swallowed: a `<RoadmapBoard/>` that silently never appears is indistinguishable from
+   *  one nobody wrote, and the author has no other channel to learn which it was. */
+  rejectedComponents?: RejectedComponent[];
+}) {
+  const ctx = useContext(TinkerableContext) as any;
+  const sandboxPath: string = ctx?.navigationState?.sandboxPath || '/';
+  const mounts = useMounts() as any[];
+
+  const [theme, setTheme] = useState(() => readPref('grove:theme') || 'default');
+  const [light, setLight] = useState(() => readPref('grove:appearance') === 'light');
+  const [menuOpen, setMenuOpen] = useState(false);
+  const [searchOpen, setSearchOpen] = useState(false);
+  const [drawerOpen, setDrawerOpen] = useState(false);
+  const [mins, setMins] = useState(0);
+  const [vw, setVw] = useState<'mobile' | 'desktop'>(() =>
+    typeof window !== 'undefined' && window.matchMedia('(max-width: 720px)').matches ? 'mobile' : 'desktop'
+  );
+
+  useEffect(() => {
+    const mq = window.matchMedia('(max-width: 720px)');
+    const on = () => setVw(mq.matches ? 'mobile' : 'desktop');
+    mq.addEventListener('change', on);
+    return () => mq.removeEventListener('change', on);
+  }, []);
+  useEffect(() => writePref('grove:theme', theme), [theme]);
+  useEffect(() => writePref('grove:appearance', light ? 'light' : 'dark'), [light]);
+
+  // ⌘K / Ctrl-K opens search.
+  useEffect(() => {
+    const on = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
+        e.preventDefault();
+        setSearchOpen((o) => !o);
+      }
+    };
+    window.addEventListener('keydown', on);
+    return () => window.removeEventListener('keydown', on);
+  }, []);
+
+  // ⚠ TEMPORARY, and not a design: dispatched content IS writable — R3-266.
+  //
+  // The affordance below calls `requestEdit`, which is **self-scoped by contract** ("v1
+  // supports only a repo-relative path in the CURRENT repo … editing a file in one of your
+  // mounts is the `edit-file` task, not this"). Under dispatch the corpus is a mount, so
+  // that call would edit GROVE rather than the corpus on screen. Offering it would be
+  // wrong; withholding it *as a design* is also wrong, and this comment exists so the next
+  // reader does not conclude the second from the first.
+  //
+  // The fix is a verb swap, not a withheld capability: delegate the entry to
+  // `invokeTask('edit-file', { file: capFile({ mountId, relPath }, { mode: 'rw' }) })`,
+  // declare `invokes: edit-file`, and gate on the CORPUS MOUNT's mode rather than on the
+  // packaging. A task callee already holds the minted delegated grant, so nothing new has
+  // to be minted. Tracked in R3-266; `docs/specs/REPO_CONTENT_DISPATCH_SPEC.mdx` §5.
+  const writable =
+    !isDispatched() && !readOnly && (mounts?.some((m) => m.type === 'worktree' && m.mode !== 'ro') ?? false);
+
+  const routeKey = sandboxPathToKey(sandboxPath) || homeKey();
+  // The site brand is a wiki-wide constant, so read it from the home entry's
+  // `site` frontmatter — not the current entry's (which only home would carry),
+  // else the brand flips to the 'Grove' fallback on every sub-page.
+  const homeMeta = useFileMetadata(homeKey()) as any;
+  // Existence / 404: the whole index tells us if a followed link is dead. Layout
+  // files are structure, not entries, so they're excluded here (and everywhere).
+  const allKeysQuery = useCallback((fm: Record<string, any>) => Object.keys(fm).filter(isContentEntry), []);
+  const idx = useMetadataQuery(allKeysQuery);
+  const keys: string[] = queryPaths(idx);
+  const indexLoaded = keys.length > 0;
+
+  // A URL that names a FOLDER is a legitimate address, and there are two right answers
+  // to it — in this order:
+  //
+  //   1. the folder's own `index.mdx`, if the author wrote one. Curation beats
+  //      generation, and it is how a corpus overrides the listing per folder without
+  //      touching the engine;
+  //   2. otherwise the generated <DirectoryView> — the entries and assets that are
+  //      actually there.
+  //
+  // Both used to be "No entry at …", which is the one answer that is false.
+  const folderIndex = indexLoaded && !keys.includes(routeKey) ? folderIndexKey(routeKey, keys) : null;
+  const entryKey = folderIndex ?? routeKey;
+  const includePath = keyToInclude(entryKey);
+  const meta = useFileMetadata(entryKey) as any;
+
+  const layout: string = meta?.layout || 'doc';
+  const navMode: 'top' | 'side' = 'side';
+  const siteTitle: string = meta?.site || homeMeta?.site || 'Grove';
+  // Interpreter mode (TRUST_MODES §5 / R3-213): render this entry's body through the
+  // non-executable safe renderer instead of the compiled `<Include>` path.
+  //
+  // Read from the HOME entry (wiki-wide) OR this entry (per-entry), because the two
+  // answer different questions. Wiki-wide is the interpreter declaration — a Grove
+  // rendering foreign content sets it there. Per-entry exists because this corpus has
+  // one document, the non-executable proof page, whose whole point is planted code that
+  // must NOT execute: on the compiled path that page doesn't just look wrong, it runs
+  // (R3-252). A document that is only correct as data says so itself.
+  const safe: boolean = homeMeta?.render === 'safe' || meta?.render === 'safe';
+  const showRails = layout === 'doc' && !meta?.view;
+
+
+  // Ask the filesystem only about a key the ENTRY index already missed: an ordinary page
+  // render performs no extra I/O, and this readdir replaces a 404 that was about to
+  // render anyway. The index cannot answer it — it holds `.md`/`.mdx` only, so a folder
+  // of assets is invisible to it.
+  const unresolved = indexLoaded && !keys.includes(entryKey);
+  const directory = useDirectoryListing(unresolved ? entryKey : null);
+  const missing = unresolved && directory.status === 'none';
+
+  // The layout chain wrapping this entry (outermost first). Needs the full
+  // frontmatter map (folder convention + `frame` override), so it reads the whole
+  // metadata store and re-derives when the content set or the entry changes.
+  const allMeta = useAllMetadata() as Record<string, Record<string, unknown>>;
+  const chain: string[] = layoutChainForKey(entryKey, allMeta);
+  const frameNone = meta?.frame === 'none' || meta?.frame === false;
+  const useDefault = chain.length === 0 && !frameNone;
+
+  // Reading time: read the entry body once per entry.
+  useEffect(() => {
+    let active = true;
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setMins(0);
+    fs.promises
+      .readFile(keyToFsPath(entryKey), 'utf8')
+      .then((b: unknown) => {
+        if (active) setMins(readingTime(stripFrontmatter(String(b))));
+      })
+      .catch(() => undefined);
+    return () => {
+      active = false;
+    };
+  }, [entryKey]);
+
+  // Records, not tab-encoded paths (R3-276a): the query selects `{ path, label }`
+  // and the hook returns them as-is — no fake-path encoding round-trip.
+  const navResult = useMetadataQuery<Metadata, NavRecord>(navQuery);
+  const navItems: NavItem[] = queryRecords<NavRecord>(navResult).map(({ path, label }) => ({
+    key: path,
+    href: keyToHref(path),
+    label,
+  }));
+
+  // Closest-match suggestion for a 404 (shared namespace or name overlap).
+  const suggestion = missing
+    ? keys
+        .map((k) => ({ k, score: overlap(k, entryKey) }))
+        .sort((a, b) => b.score - a.score)[0]?.k
+    : undefined;
+
+  const shell: GroveShell = {
+    theme,
+    setTheme,
+    light,
+    setLight,
+    menuOpen,
+    setMenuOpen,
+    searchOpen,
+    setSearchOpen,
+    drawerOpen,
+    setDrawerOpen,
+    vw,
+    navMode,
+    writable,
+    siteTitle,
+    safe,
+    navItems,
+    entryKey,
+    includePath,
+    layout,
+    showRails,
+    mins,
+    missing,
+    suggestion,
+    directory,
+  };
+
+  // The corpus scope handed to CONTENT (R3-174; MDX_FROM_MOUNT_SPEC §2, §7 1a).
+  //
+  // A component the corpus ships cannot import this engine — it would resolve a second
+  // copy from the registry, with its own `contentRoot` module state, and answer about the
+  // wrong corpus — so everything it needs about the corpus arrives through the SDK, which
+  // both sides genuinely share (one `/node_modules` per frame). Three facts, and each is
+  // one a content component cannot derive for itself:
+  //
+  //  • `root` — so metadata keys can be rebased off the mount prefix. Content must never
+  //    see `/mnt/<hash>/…`: it is host knowledge the viewer reads THROUGH but does not
+  //    publish (the property `DirectoryList.test.tsx` pins), and it is not stable across
+  //    loads, so anything content stored or linked with it would rot.
+  //  • `entry` — the entry being READ, not the file the component sits in. A component in
+  //    a `_layout.mdx` wraps the entry, so `<Include>`'s own module identity would name
+  //    the layout; furniture in the layout chain (a status line, a dependency rail) needs
+  //    the page it is describing.
+  //  • `toHref` — because corpus-path→URL is this VIEWER's policy and the two packagings
+  //    genuinely disagree (`urlAnchor`). Content that computed its own hrefs would be
+  //    correct in exactly one packaging, which is the mode-invariance rule
+  //    (PLATFORM_LAYERING §1.1) broken in the least visible possible way.
+  // `contentRoot` is module state settled at boot, so it is read here — into a local the
+  // memo can list as a dependency — rather than inside the factory. Calling it inside
+  // would close over a value the dependency list does not name, which the React Compiler
+  // correctly refuses to preserve memoization across.
+  // Built fresh each render, like everything else in this component — no hand-memoization
+  // (the rest of the file has none either; `react-hooks/preserve-manual-memoization`
+  // rejects one here because `entryKey` derives from the metadata query's array).
+  //
+  // That is safe because the EXPENSIVE half does not key on this object's identity: the
+  // SDK's `useCorpusEntries` destructures `{root, toHref}` and memoizes on those, and both
+  // are stable — `root` is a string compared by value, `toHref` is the module-scope
+  // `corpusHref` above. A new wrapper re-renders consumers (cheap); it does not re-derive
+  // 800-odd entries. Making `toHref` a closure would silently undo that, which is the
+  // whole reason it is not one.
+  const corpusRoot = contentDir().replace(/\/+$/, '');
+  const corpusEntry = toCorpusPath(entryKey, corpusRoot);
+  const corpusScope = { root: corpusRoot, entry: corpusEntry, toHref: corpusHref };
+
+  return (
+    // R3-277b: declare the enclosing corpus for the platform's link-space consumers
+    // (the shared resolver's corpus-anchored absolute + `$fs:` handling read this).
+    <LinkSpaceContext.Provider value={{ corpusRoot: getContentRoot() }}>
+    {/* R3-174: the corpus scope CONTENT reads — sibling to the link space, not a
+        replacement for it. The two answer different questions: `LinkSpaceContext` tells
+        the platform's link resolver where absolute hrefs are anchored; `CorpusContext`
+        tells a component the corpus ships which entries exist, which one is being read,
+        and how to turn a corpus path into a URL. */}
+    <CorpusContext value={corpusScope}>
+    <GroveShellContext.Provider value={shell}>
+      <div
+        className="grove-root"
+        data-vw={vw}
+        data-nav={navMode}
+        data-grove-theme={theme === 'default' ? undefined : theme}
+        data-theme={theme === 'default' && light ? 'light' : undefined}
+      >
+        <div className="device__scroll">
+          {rejectedComponents.length > 0 ? (
+            <div className="grove-decl-error" role="status">
+              <strong>This corpus declares components that could not be loaded.</strong>
+              <ul>
+                {rejectedComponents.map((r) => (
+                  <li key={r.name}>
+                    <code>{r.name}</code> — {r.reason}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ) : null}
+          <div className="grove-shell" data-nav={frameNone ? undefined : navMode}>
+            {renderLayers(chain, useDefault, safe)}
+          </div>
+        </div>
+
+        {searchOpen ? <Search onClose={() => setSearchOpen(false)} /> : null}
+        {drawerOpen ? (
+          <Drawer
+            siteTitle={siteTitle}
+            nav={navItems.map((n) => ({ href: n.href, label: n.label, cur: n.key === entryKey }))}
+            onClose={() => setDrawerOpen(false)}
+          />
+        ) : null}
+        <GroveAgent writable={writable} entryKey={entryKey} entryTitle={(meta?.title || 'this entry').replace(/\.$/, '')} />
+      </div>
+    </GroveShellContext.Provider>
+    </CorpusContext>
+    </LinkSpaceContext.Provider>
+  );
+}
+
+// Crude closest-match score for the 404 suggestion: shared namespace + name chars.
+function overlap(a: string, b: string): number {
+  const an = a.replace(contentDir(), '').replace(/\.mdx?$/, '');
+  const bn = b.replace(contentDir(), '').replace(/\.mdx?$/, '');
+  const aNs = an.split('/').slice(0, -1).join('/');
+  const bNs = bn.split('/').slice(0, -1).join('/');
+  let score = aNs && aNs === bNs ? 5 : 0;
+  const aName = an.split('/').pop() || '';
+  const bName = bn.split('/').pop() || '';
+  for (const ch of new Set(aName)) if (bName.includes(ch)) score++;
+  return score;
+}

package/src/components/AssetImage.tsx

@@ -0,0 +1,58 @@
+import { useContext, useMemo } from 'react';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { MountImage } from '@immediately-run/sdk';
+import type { SandboxMount } from '@immediately-run/sdk';
+import { toFsPath } from '../lib/content';
+
+// MDX `img` override: display a mount-relative image by reading its bytes off the
+// sandbox fs (the opaque-origin iframe can't fetch a relative path). Resolves the
+// src relative to the entry currently being rendered (navigationState.sandboxPath),
+// then hands the file to the SDK's `MountImage`, which owns the read → object URL →
+// revoke lifecycle we used to hand-roll here.
+
+function resolvePath(basePath: string, relativePath: string): string {
+  if (relativePath.startsWith('/')) return relativePath;
+  const parts = basePath.split('/');
+  parts.pop();
+  for (const part of relativePath.split('/')) {
+    if (part === '.' || part === '') continue;
+    if (part === '..') parts.pop();
+    else parts.push(part);
+  }
+  return parts.join('/');
+}
+
+// The whole sandbox fs, `/`-rooted. The resolved asset path is already absolute
+// (`/app/content/…`), so anchor at root and pass it as the mount-relative path
+// (leading slash stripped) — preserving the exact paths the old `fs.readFile` read.
+const ROOT_MOUNT: SandboxMount = { path: '/', type: 'repo' };
+
+interface Props {
+  src?: string;
+  alt?: string;
+  className?: string;
+}
+
+export default function AssetImage({ src = '', alt = '', className }: Props) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const { navigationState } = useContext(TinkerableContext) as any;
+
+  const relPath = useMemo(() => {
+    // The entry's absolute fs path (/app/content/...) is the base for relative assets.
+    const base = toFsPath(navigationState?.sandboxPath || '/');
+    return resolvePath(base, src).replace(/^\/+/, '');
+  }, [navigationState?.sandboxPath, src]);
+
+  return (
+    <MountImage
+      mount={ROOT_MOUNT}
+      relPath={relPath}
+      alt={alt}
+      className={className || 'grove-img__el'}
+      placeholder={
+        <span className="grove-img__box" style={{ display: 'block', minHeight: 80 }} />
+      }
+      fallback={<span className="grove-img__cap">missing asset: {src}</span>}
+    />
+  );
+}

package/src/components/Backlinks.tsx

@@ -0,0 +1,104 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useCallback, useContext, useEffect, useState } from 'react';
+import fs from 'fs';
+import { Link, useFileMetadata, useMetadataQuery } from '@immediately-run/sdk';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { isContentEntry, keyToFsPath, keyToHref, sandboxPathToKey } from '../lib/content';
+import { backlinkSnippet, bodyLinksTo, crumb, queryPaths } from '../lib/wiki';
+
+interface Hit {
+  key: string;
+  snippet: string;
+}
+
+// One linking entry: title + namespace crumb + the snippet around the link.
+function Row({ hit }: { hit: Hit }) {
+  const meta = useFileMetadata(hit.key) as any;
+  const title = (meta?.title || crumb(hit.key)).replace(/\.$/, '');
+  return (
+    <Link href={keyToHref(hit.key)} className="grove-bl">
+      <div className="grove-bl__t">
+        {title}
+        <span className="crumb">/{crumb(hit.key)}</span>
+      </div>
+      <div className="grove-bl__snip" dangerouslySetInnerHTML={{ __html: hit.snippet }} />
+    </Link>
+  );
+}
+
+// `<Backlinks/>` — the signature wiki affordance: who links here. Reads sibling
+// entry bodies off the fs and scans for a link to the current entry.
+export default function Backlinks() {
+  const ctx = useContext(TinkerableContext) as any;
+  const currentKey = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
+
+  const allKeys = useCallback(
+    (fm: Record<string, any>) => Object.keys(fm).filter(isContentEntry),
+    []
+  );
+  const q = useMetadataQuery(allKeys);
+  const keys: string[] = queryPaths(q);
+  const keysKey = keys.join('|');
+
+  const [hits, setHits] = useState<Hit[] | null>(null);
+
+  useEffect(() => {
+    let active = true;
+    if (!keys.length) return; // index not loaded yet → keep the skeleton
+    const others = keys.filter((k) => k !== currentKey);
+    Promise.all(
+      others.map((k) =>
+        fs.promises
+          .readFile(keyToFsPath(k), 'utf8')
+          .then((body: unknown) => ({ key: k, body: String(body) }))
+          .catch(() => null)
+      )
+    ).then((rows) => {
+      if (!active) return;
+      const found: Hit[] = [];
+      for (const r of rows) {
+        // R3-283: the linking entry's own key is part of the question — corpus links
+        // are RELATIVE to the file they are written in, so `r.key` is what resolves them.
+        if (r && bodyLinksTo(r.body, currentKey, r.key)) {
+          found.push({ key: r.key, snippet: backlinkSnippet(r.body, currentKey, r.key) });
+        }
+      }
+      setHits(found.sort((a, b) => (a.key < b.key ? -1 : 1)));
+    });
+    return () => {
+      active = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentKey, keysKey]);
+
+  // Skeleton while the bodies resolve.
+  if (hits === null) {
+    return (
+      <section className="grove-backlinks">
+        <div className="grove-backlinks__h">Backlinks</div>
+        <div className="grove-backlinks__list">
+          <div className="sk sk-line" style={{ width: '60%' }} />
+          <div className="sk sk-line" style={{ width: '40%' }} />
+        </div>
+      </section>
+    );
+  }
+
+  return (
+    <section className="grove-backlinks">
+      <h2 className="grove-backlinks__h">
+        Linked from
+        <span className="n">{hits.length} {hits.length === 1 ? 'entry' : 'entries'}</span>
+      </h2>
+      {hits.length ? (
+        <div className="grove-backlinks__list">
+          {hits.map((h) => (
+            <Row key={h.key} hit={h} />
+          ))}
+        </div>
+      ) : (
+        <p className="grove-bl__snip">Nothing links here yet.</p>
+      )}
+    </section>
+  );
+}

package/src/components/Callout.tsx

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react';
+import Icon from './Icon';
+
+interface Props {
+  variant?: 'tip' | 'note' | 'warning';
+  type?: 'tip' | 'note' | 'warning';
+  title?: string;
+  children?: ReactNode;
+}
+
+const ICON: Record<string, string> = { tip: 'sparkles', note: 'message', warning: 'alert' };
+
+// Import-free engine component: an Obsidian-style callout panel with an accent
+// spine + a Lucide cue (tip / note / warning).
+export default function Callout({ variant, type, title, children }: Props) {
+  const v = variant || type || 'note';
+  return (
+    <div className="grove-callout" data-v={v}>
+      <Icon name={ICON[v] || 'message'} />
+      <div>
+        {title ? <div className="grove-callout__t">{title}</div> : null}
+        <div className="grove-callout__b">{children}</div>
+      </div>
+    </div>
+  );
+}

package/src/components/ChildPages.tsx

@@ -0,0 +1,40 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useCallback, useContext } from 'react';
+import { Link, useMetadataQuery } from '@immediately-run/sdk';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { contentDir, isContentEntry, keyToHref, sandboxPathToKey } from '../lib/content';
+import { namespaceOf, queryPaths } from '../lib/wiki';
+
+// `<ChildPages/>` — the entries that live under the current entry's namespace, as
+// a compact nested list (e.g. everything in `handbook/` from the handbook index).
+export default function ChildPages() {
+  const ctx = useContext(TinkerableContext) as any;
+  const currentKey = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
+  const rel = currentKey.replace(contentDir(), '').replace(/\.mdx?$/, '');
+  // The folder this entry indexes: its own slug if it's a section index, else its namespace.
+  const scope = rel.replace(/\/?(index|home)$/, '');
+
+  const queryFn = useCallback(
+    (fm: Record<string, any>) =>
+      Object.keys(fm)
+        .filter((p) => {
+          if (!isContentEntry(p) || p === currentKey) return false;
+          return namespaceOf(p) === scope;
+        })
+        .sort(),
+    [currentKey, scope]
+  );
+  const q = useMetadataQuery(queryFn);
+  const paths: string[] = queryPaths(q);
+
+  if (!paths.length) return null;
+  return (
+    <div className="grove-doclist" data-shape="feed">
+      {paths.map((p) => (
+        <Link key={p} href={keyToHref(p)} className="gdl-row">
+          <div className="gdl-row__t">{p.replace(contentDir(), '').replace(/\.mdx?$/, '').split('/').pop()}</div>
+        </Link>
+      ))}
+    </div>
+  );
+}

package/src/components/DefaultLayout.tsx

@@ -0,0 +1,27 @@
+import { useShell } from '../lib/shell';
+import GroveNav from './GroveNav';
+import Sidebar from './Sidebar';
+import GroveFooter from './GroveFooter';
+import Outlet from './Outlet';
+
+// The built-in root layout: the standard Grove shell, used when a repo ships no
+// `content/_layout.mdx` of its own — so even a bare folder of `.mdx` files gets
+// full chrome (product value 3, "a bare folder is a usable site"). A repo makes
+// the shell its own by dropping in `content/_layout.mdx`, which overrides this.
+//
+// This is intentionally the SAME arrangement a content `_layout.mdx` would write
+// by hand (`<GroveNav/> <GroveSidebar/> <main><Outlet/></main> <GroveFooter/>`),
+// so the default and a custom shell are structurally identical.
+export default function DefaultLayout() {
+  const { navMode } = useShell();
+  return (
+    <>
+      <GroveNav />
+      {navMode === 'side' ? <Sidebar /> : null}
+      <main className="grove-content">
+        <Outlet />
+      </main>
+      <GroveFooter />
+    </>
+  );
+}