@immediately-run/grove 0.1.1

package/src/components/GroveNav.tsx

@@ -0,0 +1,102 @@
+import { Link, requestEdit } from '@immediately-run/sdk';
+import { useShell } from '../lib/shell';
+import { THEMES } from '../data/themes';
+import Icon from './Icon';
+
+// `<GroveNav/>` — the top navigation bar. Import-free in MDX, so a layout places
+// it with `<GroveNav/>`. Its interactive state (drawer / search / theme menu)
+// lives in the shell context; this component only arranges and drives it.
+export default function GroveNav() {
+  const {
+    siteTitle,
+    navItems,
+    entryKey,
+    writable,
+    theme,
+    setTheme,
+    light,
+    setLight,
+    menuOpen,
+    setMenuOpen,
+    setSearchOpen,
+    setDrawerOpen,
+  } = useShell();
+
+  const askGrove = () => {
+    const el = (document.querySelector('.ga-foot input') || document.querySelector('.ga-line input')) as HTMLElement | null;
+    el?.focus();
+  };
+  const newEntry = () => requestEdit({ path: 'content/untitled.mdx' }).catch(() => undefined);
+
+  return (
+    <nav className="grove-nav">
+      <button className="grove-hamburger icbtn" aria-label="Menu" onClick={() => setDrawerOpen(true)}>
+        <Icon name="list" />
+      </button>
+      <Link href="/" className="grove-brand">
+        <span className="tile" style={{ background: 'var(--grad)' }} />
+        {siteTitle}
+      </Link>
+      <div className="grove-nav__links">
+        {navItems.map((n) => (
+          <Link key={n.key} href={n.href} data-cur={n.key === entryKey ? '1' : '0'}>
+            {n.label}
+          </Link>
+        ))}
+      </div>
+      <div className="grove-nav__cluster">
+        <button className="icbtn" aria-label="Search" onClick={() => setSearchOpen(true)}>
+          <Icon name="search" />
+        </button>
+        {writable && (
+          <button className="icbtn" aria-label="New entry" onClick={newEntry}>
+            <Icon name="plus" />
+          </button>
+        )}
+        <button className="icbtn" aria-label="Ask Grove" onClick={askGrove}>
+          <Icon name="message" />
+        </button>
+        <div className="grove-nav__more">
+          <button className="icbtn" title="Theme" aria-expanded={menuOpen} onClick={() => setMenuOpen((o) => !o)}>
+            ☀
+          </button>
+          {menuOpen ? (
+            <>
+              <div className="gtm__scrim" onClick={() => setMenuOpen(false)} />
+              <div className="grove-theme-menu" role="menu">
+                <div className="gtm__h">Theme</div>
+                <div className="gtm__list">
+                  {THEMES.map((t) => (
+                    <button
+                      key={t.id}
+                      className="gtm__row"
+                      data-cur={theme === t.id ? '1' : '0'}
+                      onClick={() => setTheme(t.id)}
+                    >
+                      <span className="gtm__sw" style={{ background: t.swatch }} />
+                      <span className="gtm__name">{t.label}</span>
+                      {theme === t.id ? <span className="gtm__ck"><Icon name="check" /></span> : null}
+                    </button>
+                  ))}
+                </div>
+                {theme === 'default' ? (
+                  <div className="gtm__appearance">
+                    <div className="gtm__sub">Appearance</div>
+                    <div className="gtm__seg">
+                      <button data-on={!light ? '1' : '0'} onClick={() => setLight(false)}>
+                        <Icon name="moon" /> Dark
+                      </button>
+                      <button data-on={light ? '1' : '0'} onClick={() => setLight(true)}>
+                        <Icon name="sun" /> Light
+                      </button>
+                    </div>
+                  </div>
+                ) : null}
+              </div>
+            </>
+          ) : null}
+        </div>
+      </div>
+    </nav>
+  );
+}

package/src/components/Icon.tsx

@@ -0,0 +1,56 @@
+import type { SVGProps } from 'react';
+
+// The Lucide micro-set Grove needs, inlined as path data so the app carries no
+// icon dependency and every glyph inherits `currentColor` + the CSS-sized box
+// (HANDOFF constraint 4: Lucide, ~1.75 stroke, no emoji). One default-exported
+// component keyed by `name` keeps the Fast-Refresh "one component per file" rule.
+const PATHS: Record<string, string> = {
+  search: 'M21 21l-4.34-4.34M17 11a6 6 0 11-12 0 6 6 0 0112 0z',
+  plus: 'M5 12h14M12 5v14',
+  pencil: 'M21.17 6.83l-3-3L4 18l-1 4 4-1zM14.5 6.5l3 3',
+  send: 'M12 19V5M5 12l7-7 7 7',
+  x: 'M18 6L6 18M6 6l12 12',
+  'chevron-right': 'M9 6l6 6-6 6',
+  'chevron-down': 'M6 9l6 6 6-6',
+  unlink:
+    'M16.5 9.4l2.1-2.1a3 3 0 000-4.2l-.7-.7a3 3 0 00-4.2 0L11.6 4.5M7.5 14.6l-2.1 2.1a3 3 0 000 4.2l.7.7a3 3 0 004.2 0l1.9-1.9M8 12l8 0',
+  alert: 'M10.3 3.8L1.8 18a2 2 0 001.7 3h17a2 2 0 001.7-3L14.7 3.8a2 2 0 00-3.4 0zM12 9v4M12 17h.01',
+  sparkles:
+    'M12 3l1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10l5.1-1.9zM19 3v4M21 5h-4M5 17v2M6 18H4',
+  folder: 'M3 7a2 2 0 012-2h4l2 2h8a2 2 0 012 2v8a2 2 0 01-2 2H5a2 2 0 01-2-2z',
+  file: 'M14 3H7a2 2 0 00-2 2v14a2 2 0 002 2h10a2 2 0 002-2V8zM14 3v5h5M9 13h6M9 17h6',
+  'file-plus': 'M14 3H7a2 2 0 00-2 2v14a2 2 0 002 2h10a2 2 0 002-2V8zM14 3v5h5M12 12v6M9 15h6',
+  check: 'M20 6L9 17l-5-5',
+  undo: 'M3 7v6h6M3 13a9 9 0 109-9 9 9 0 00-7.5 4',
+  external: 'M15 3h6v6M10 14L21 3M19 13v6a2 2 0 01-2 2H5a2 2 0 01-2-2V7a2 2 0 012-2h6',
+  sun: 'M12 17a5 5 0 100-10 5 5 0 000 10zM12 1v2M12 21v2M4.2 4.2l1.4 1.4M18.4 18.4l1.4 1.4M1 12h2M21 12h2M4.2 19.8l1.4-1.4M18.4 5.6l1.4-1.4',
+  moon: 'M21 12.8A9 9 0 1111.2 3a7 7 0 009.8 9.8z',
+  message: 'M21 11.5a8.5 8.5 0 01-12.3 7.6L3 21l1.9-5.7A8.5 8.5 0 1121 11.5z',
+  shield: 'M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z',
+  list: 'M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01',
+  stop: 'M6 6h12v12H6z',
+};
+
+interface IconProps extends SVGProps<SVGSVGElement> {
+  name: keyof typeof PATHS | string;
+}
+
+export default function Icon({ name, ...rest }: IconProps) {
+  const d = PATHS[name] || '';
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.75}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      {...rest}
+    >
+      {d.split('M').filter(Boolean).map((seg, i) => (
+        <path key={i} d={'M' + seg} />
+      ))}
+    </svg>
+  );
+}

package/src/components/Infobox.tsx

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+
+interface Props {
+  title?: string;
+  cover?: boolean;
+  children?: ReactNode;
+}
+
+// Import-free engine component: a sidebar fact panel. Authors put a markdown
+// list of `- Key: value` lines inside; it renders as the panel body.
+export default function Infobox({ title, cover, children }: Props) {
+  return (
+    <aside className="grove-infobox">
+      {title ? <div className="grove-infobox__h">{title}</div> : null}
+      {cover ? <div className="grove-infobox__cover" /> : null}
+      <div className="grove-infobox__body">{children}</div>
+    </aside>
+  );
+}

package/src/components/Kbd.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+
+interface Props {
+  children?: ReactNode;
+}
+
+// Import-free engine component: a keyboard key cap, e.g. <Kbd>⌘K</Kbd>.
+export default function Kbd({ children }: Props) {
+  return <kbd className="grove-kbd">{children}</kbd>;
+}

package/src/components/KeyValue.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+
+interface Pair {
+  /** Label — rendered in Space Mono, uppercased. */
+  label: string;
+  /** Value — a plain string or arbitrary ReactNode (links, code, etc.). */
+  value: ReactNode;
+}
+
+interface Props {
+  /** Label/value pairs, rendered top-to-bottom as <dt>/<dd> rows. */
+  pairs: Pair[];
+}
+
+// Import-free engine component: a compact definition list of label/value pairs
+// (contact details, metadata, quick facts). `label` is set in Space Mono and
+// uppercased; `value` may be a string or any ReactNode, so links and inline
+// code compose naturally. Rendered as a <dl> of <dt>/<dd> pairs with hairline
+// row separators and a panel background, using the same design tokens as the
+// rest of the component vocabulary.
+export default function KeyValue({ pairs }: Props) {
+  return (
+    <dl className="grove-keyvalue">
+      {pairs.map((p, i) => (
+        <div className="grove-keyvalue__row" key={i}>
+          <dt className="grove-keyvalue__label">{p.label}</dt>
+          <dd className="grove-keyvalue__value">{p.value}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}

package/src/components/Lede.tsx

@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react';
+
+// Import-free engine component: the oversized opening paragraph of an entry.
+export default function Lede({ children }: { children?: ReactNode }) {
+  return <p className="grove-lede">{children}</p>;
+}

package/src/components/More.tsx

@@ -0,0 +1,10 @@
+// Import-free engine component: marks the excerpt cutoff in an entry body.
+export default function More() {
+  return (
+    <div className="grove-more" aria-hidden="true">
+      <span>●</span>
+      <span>●</span>
+      <span>●</span>
+    </div>
+  );
+}

package/src/components/Outlet.tsx

@@ -0,0 +1,11 @@
+import { useContext } from 'react';
+import { OutletContext } from '../lib/shell';
+
+// `<Outlet/>` — the injection point inside a layout (`_layout.mdx`). It renders
+// whatever the engine placed one level inward: the next nested layout, or — at
+// the bottom of the chain — the page itself. Import-free in MDX (registered in
+// GROVE_MDX), so a layout author just writes `<Outlet/>` where the page goes.
+// The React Router analogue, adapted to Grove's content-is-chrome model.
+export default function Outlet() {
+  return <>{useContext(OutletContext)}</>;
+}

package/src/components/PageMeta.tsx

@@ -0,0 +1,24 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useContext } from 'react';
+import { useFileMetadata } from '@immediately-run/sdk';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { sandboxPathToKey } from '../lib/content';
+
+// `<PageMeta/>` — the current entry's date + tags as a styled strip, for authors
+// who want the meta inside the body (the entry header already renders one).
+export default function PageMeta() {
+  const ctx = useContext(TinkerableContext) as any;
+  const key = sandboxPathToKey(ctx?.navigationState?.sandboxPath || '/');
+  const meta = useFileMetadata(key) as any;
+  if (!meta) return null;
+  const tags: string[] = Array.isArray(meta.tags) ? meta.tags.filter((t: string) => !t.startsWith('ui/')) : [];
+  return (
+    <div className="grove-meta">
+      {meta.date && <span>{meta.date}</span>}
+      {tags.length ? <span className="dot">·</span> : null}
+      {tags.map((t) => (
+        <span key={t} className="grove-tag">#{t}</span>
+      ))}
+    </div>
+  );
+}

package/src/components/PageView.tsx

@@ -0,0 +1,98 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Include, Link } from '@immediately-run/sdk';
+import { useShell } from '../lib/shell';
+import { keyToHref, keyToRepoRel } from '../lib/content';
+import { crumb } from '../lib/wiki';
+import { requestEdit } from '@immediately-run/sdk';
+import DirectoryView from './DirectoryView';
+import EntryHeader from './EntryHeader';
+import SafeEntryBody from './SafeEntryBody';
+import ScrollToFragment from './ScrollToFragment';
+import Toc from './Toc';
+import Backlinks from './Backlinks';
+import Icon from './Icon';
+
+declare const module: any;
+
+// `<PageView/>` — the reading view for the current entry: the 404/missing state,
+// or the entry header + prose body (+ ToC / backlinks rails). This is what the
+// INNERMOST `<Outlet/>` renders at the bottom of the layout chain. It carries no
+// site chrome (nav / sidebar / footer) — that's the layout's job — so the page
+// stays free of shell concerns.
+export default function PageView() {
+  const { entryKey, includePath, layout, showRails, mins, missing, suggestion, writable, vw, safe, directory } = useShell();
+
+  // A folder URL. `checking` renders nothing rather than the 404: the readdir that
+  // decides between them is one RPC away, and a 404 that appears and then turns into a
+  // listing reads as a broken link that healed itself.
+  if (directory.status === 'checking') return <div className="grove-state" data-state="checking" />;
+  if (directory.status === 'ready') return <DirectoryView />;
+
+  if (missing) {
+    return (
+      <div className="grove-state">
+        <div className="grove-state__art" />
+        <h2>No entry at <code>{keyToRepoRel(entryKey).replace(/^content/, '')}</code>.</h2>
+        <p>
+          That link points to an entry that doesn’t exist yet.
+          {suggestion ? <> Did you mean <Link className="grove-wikilink" data-state="ok" href={keyToHref(suggestion)}>{crumb(suggestion)}</Link>?</> : null}
+        </p>
+        <div className="grove-state__actions">
+          <Link className="btn-ghost" href="/"><Icon name="chevron-right" /> Back to home</Link>
+          {writable ? <button className="btn-primary" onClick={() => requestEdit({ path: keyToRepoRel(entryKey) }).catch(() => undefined)}><Icon name="file-plus" /> Create it</button> : null}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <article className="grove-page" data-layout={layout}>
+      <div className="gp-main">
+        <EntryHeader entryKey={entryKey} writable={writable} mins={mins} />
+        {showRails && vw === 'mobile' ? (
+          <details className="grove-toc__disclosure">
+            <summary>On this page</summary>
+            <Toc entryKey={entryKey} />
+          </details>
+        ) : null}
+        <div className="grove-prose">
+          {/* Interpreter mode (R3-213) renders the raw entry as data — no author JS runs;
+              executable mode compiles + runs the MDX via <Include>. Both are supported,
+              and since R3-252 the choice is per-entry as well as wiki-wide.
+
+              The compiled branch mounts <ScrollToFragment> too — deep-link landing is not
+              a safe-path feature — but deliberately carries NO `data-entry` marker, and
+              both halves of that are load-bearing (R3-252).
+
+              `key={entryKey}` forces an unmount across a client-side navigation. Without
+              it React reuses this subtree and keeps the PREVIOUS document mounted while
+              the new one compiles, so `#sec-4` resolves against the wrong entry — every
+              entry here numbers its sections from 1, so that lookup always succeeds and
+              always lands wrong. Measured on the host: a citation to core_concepts §4
+              ("4 — Principal") scrolled to a different document's "4. The provider-facing
+              contract" (R3-249's hazard, reintroduced).
+
+              No marker, because `<Include>` owns an internal <Suspense> and this wrapper
+              is OUTSIDE it — so a marker here would appear the instant we navigate, while
+              the body is still compiling, and claim a commit that has not happened. That
+              is worse than no signal: `data-entry` means "this subtree holds entry X's
+              committed body" everywhere else (`SafeEntryBody` puts it inside the suspended
+              subtree, so it is true there), and the on-host harness waits on it. Keying
+              already removes the hazard the marker defended against — the outgoing
+              document is gone from the DOM, not lingering — so `resolveFragmentTarget`'s
+              documented document-wide fallback for the compiled path is safe here. */}
+          {safe ? (
+            <SafeEntryBody entryKey={entryKey} />
+          ) : (
+            <div className="grove-entry-body" key={entryKey}>
+              <Include filename={includePath} baseModule={module} />
+              <ScrollToFragment entryKey={entryKey} />
+            </div>
+          )}
+        </div>
+        {showRails ? <Backlinks /> : null}
+      </div>
+      {showRails && vw === 'desktop' ? <Toc entryKey={entryKey} /> : null}
+    </article>
+  );
+}

package/src/components/Quote.tsx

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react';
+import WikiLink from './WikiLink';
+
+interface Props {
+  /** Attribution — a person, role, or document. Rendered in mono as "— cite". */
+  cite?: string;
+  /** Wiki path of the entry the quote is drawn from, e.g.
+   *  "content/handbook/onboarding.mdx". When set, a "Source →" link is shown. */
+  source?: string;
+  children?: ReactNode;
+}
+
+// Import-free engine component: a pull-quote with a gradient accent spine and a
+// large gradient opening quote mark. `cite` is the attribution (Space Mono);
+// `source`, when given, links to the entry the quote came from — its
+// resolved / broken / self state is decided by the shared <WikiLink> resolver, so
+// a moved or missing target reads as broken rather than a dead link (no
+// hand-rolled href logic here, just the wiki path → in-app href normalization).
+export default function Quote({ cite, source, children }: Props) {
+  const href = source ? (source.startsWith('/') ? source : `/${source}`) : null;
+  return (
+    <figure className="grove-quote">
+      <blockquote className="grove-quote__body">{children}</blockquote>
+      {(cite || href) && (
+        <figcaption className="grove-quote__cap">
+          {cite ? <span className="grove-quote__cite">{cite}</span> : null}
+          {href ? (
+            <WikiLink href={href} className="grove-quote__src">
+              Source →
+            </WikiLink>
+          ) : null}
+        </figcaption>
+      )}
+    </figure>
+  );
+}

package/src/components/RecentlyUpdated.tsx

@@ -0,0 +1,6 @@
+import DocList from './DocList';
+
+// `<RecentlyUpdated limit>` — a compact, date-sorted feed of the latest entries.
+export default function RecentlyUpdated({ limit = 6, title }: { limit?: string | number; title?: string }) {
+  return <DocList shape="feed" sort="date" limit={limit} title={title ?? 'Recently updated'} />;
+}

package/src/components/SafeEntryBody.tsx

@@ -0,0 +1,72 @@
+import { Suspense, use } from 'react';
+import {
+  SafeContent,
+  RenderExportedComponentContext,
+  useFileMetadata,
+} from '@immediately-run/sdk';
+import { SAFE_MDX } from '../mdxComponents';
+import { safeSources } from '../lib/safeSources';
+import ScrollToFragment from './ScrollToFragment';
+
+// The NON-EXECUTABLE (interpreter) body renderer — TRUST_MODES §5.1 / R3-213. It reads
+// the entry's RAW `.mdx` and renders it through the SDK safe renderer (parseSafeMdast +
+// renderMdast): **no author JavaScript executes** — a stray `{fetch(...)}` in any entry
+// is inert literal text. This is the alternative to `<Include>` (the executable/executor
+// path, where compiled MDX runs) that `PageView` uses when the wiki is NOT in interpreter
+// mode. The engine keeps BOTH; the wiki declares which via the home entry's `render:` flag,
+// so a trusted first-party grove deployment can still use standard, executable MDX.
+//
+// Uniformity (R3-213): the component map is `SAFE_MDX` — the SDK's DEFAULT_MDX_COMPONENTS
+// (the platform Admonition / WikiLink / HeadingAnchor, carrying the R3-212 deep-link
+// resolver) merged UNDER the Grove vocabulary, the SAME merge `boot()` does for the compiled
+// path — so the admonitions / wiki-links / `sec-…` heading ids the shared remark plugins emit
+// render identically in both standards. Since R3-263 that map lives in `mdxComponents.ts` and
+// is shared with `SafeLayout`, so the body and the shell around it cannot resolve differently.
+// We publish `RenderExportedComponentContext` with this entry's path so the WikiLink resolver
+// learns the current file and a relative `[[target]]` (and its `#sec-…` fragment) resolves
+// exactly as it does under `<Include>`.
+
+/** Strip a leading YAML frontmatter block (and an optional BOM) so only the body reaches
+ *  the safe renderer. */
+function stripFrontmatter(src: string): string {
+  return src.replace(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/, "");
+}
+
+function SafeBody({ entryKey }: { entryKey: string }) {
+  const raw = use(safeSources.read(entryKey));
+  // Consume the entry's metadata so this re-renders if frontmatter changes (parity with
+  // the compiled path's reactivity); the body itself is the stripped source.
+  useFileMetadata(entryKey);
+  const body = stripFrontmatter(raw);
+  return (
+    <RenderExportedComponentContext
+      value={{ evaluationContext: { evaluation: { module: { filepath: entryKey } } } } as never}
+    >
+      {/* `data-entry` marks WHICH entry these bytes are, and it is rendered INSIDE the
+          suspended subtree — so it flips only when the new body actually commits, never
+          while the previous entry is still on screen. `<ScrollToFragment>` waits for it
+          before scrolling. Without that signal a deep-link scrolls the OUTGOING document:
+          every spec has `sec-1 … sec-N`, so the id the incoming page wants is already in
+          the DOM, and a scroll fired at navigation time lands on the wrong page's section
+          and is then thrown away by the re-render (R3-249). */}
+      <div className="grove-entry-body" data-entry={entryKey}>
+        <SafeContent source={body} components={SAFE_MDX as never} fallback={<div className="grove-prose__loading" />} />
+        {/* Deep-link landing lives INSIDE the committed body, not outside watching for it.
+            Mounted anywhere above this boundary it is unmounted by the very transition it
+            is waiting on — measured on the real host: it polled 159 times and was torn
+            down at the exact moment the new body arrived. Here it mounts *because* the
+            content did, so there is nothing to wait for. */}
+        <ScrollToFragment entryKey={entryKey} />
+      </div>
+    </RenderExportedComponentContext>
+  );
+}
+
+/** Interpreter-mode entry body: the raw `.mdx` rendered as data (no author JS runs). */
+export default function SafeEntryBody({ entryKey }: { entryKey: string }) {
+  return (
+    <Suspense fallback={<div className="grove-prose__loading" />}>
+      <SafeBody entryKey={entryKey} />
+    </Suspense>
+  );
+}

package/src/components/SafeLayout.tsx

@@ -0,0 +1,35 @@
+import { Include } from '@immediately-run/sdk';
+import { SAFE_MDX } from '../mdxComponents';
+
+// A `_layout.mdx` rendered NON-EXECUTABLY — now a thin call to the PLATFORM's interpreter
+// include rather than Grove's own reader. (R3-263: (a) built it here, (b) moved it into the
+// SDK, this switch consumes it.)
+//
+// WHY THE LAYOUT NEEDS THIS AT ALL. `renderLayers` used to send every layer through
+// `<Include>` — the compiled path — *regardless* of `render: safe`. So an interpreter-mode
+// wiki still EXECUTED author JavaScript out of one content file, and the non-executable
+// guarantee had a hole in the shell rather than in the entries. It was also inoperable under
+// dispatch: the compiled path evaluates an app-source module, which a mount-resident layout
+// is not.
+//
+// WHY IT IS NOW THE SDK'S JOB. The same capability is what whiteboard object bodies and the
+// `AGENT_AUTHORING §10` MDX-from-mount gate need — a gate `TRUST_MODES §5.1` says MUST
+// terminate in the safe renderer and never in compiled MDX. Keeping a second implementation
+// here would let the platform path and the path Grove actually exercises drift apart; and
+// because the SDK's own render-level coverage is bounded by its CJS test runner, this wiki
+// exercising the real thing is what keeps the platform path honest.
+//
+// WHAT GROVE STILL OWNS: the component map. `<Include mode="interpreted">` resolves components
+// from `useMDXComponents` — the map `boot({ mdxComponents })` established — which for this app
+// is `SAFE_MDX` (`mdxComponents.ts`): the SDK defaults under the Grove vocabulary, plus the
+// sanitizing structural tags (`lib/safeIntrinsics.tsx`). That is app policy and stays here.
+//
+// THE AUTHORING CONSTRAINTS ARE UNCHANGED and documented in `docs/ENGINE_BOUNDARY.md §6`:
+// literal attributes only; an unregistered tag collapses to a Fragment that keeps its
+// children; an `import` renders as visible prose rather than resolving; and a block tag must
+// open on its own line or micromark consumes it as an HTML block.
+
+/** Interpreter-mode layout layer: the raw `_layout.mdx` rendered as data (no author JS runs). */
+export default function SafeLayout({ layoutKey }: { layoutKey: string }) {
+  return <Include filename={layoutKey} mode="interpreted" components={SAFE_MDX as never} />;
+}

package/src/components/ScrollToFragment.tsx

@@ -0,0 +1,63 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useContext, useEffect } from 'react';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { fragmentOf, resolveFragmentTarget } from '../lib/fragment';
+
+/**
+ * Land a deep-link on its section.
+ *
+ * **Mounted inside the entry body it belongs to** (`SafeEntryBody`), which is the whole
+ * trick. The obvious placement — up in `PageView`, watching for the new content to arrive —
+ * does not work: the component is unmounted by the very transition it is waiting on.
+ * Measured on the real host, it polled 159 times and was torn down at the exact moment the
+ * new body committed, so it never saw the thing it existed to see. Rendered *within* the
+ * body, it mounts because the content did; the first attempt succeeds and there is nothing
+ * to wait for.
+ *
+ * The target is still resolved against `data-entry` rather than looked up blindly, because
+ * the outgoing document lingers briefly during a navigation and every document in this
+ * corpus numbers its sections from 1 — `#sec-4` exists in almost all of them, so an
+ * unscoped lookup can land on the page you just left (R3-249).
+ *
+ * Requires a host that forwards the fragment (`site-main` #272). Before that fix
+ * `navigationState.hash` was always empty inside the sandbox, and no app could do this at
+ * all. The SDK's own `<ScrollAfterNavigation>` is not used: it scrolls on its first hit and
+ * returns, and with repeated section ids that first hit is the outgoing document's.
+ */
+export default function ScrollToFragment({ entryKey }: { entryKey: string }) {
+  const ctx = useContext(TinkerableContext) as any;
+  const hash = ctx?.navigationState?.hash ?? '';
+  const frag = fragmentOf(hash);
+
+  useEffect(() => {
+    if (!frag || typeof document === 'undefined') return;
+    let done = false;
+
+    const attempt = () => {
+      if (done) return true;
+      const el = resolveFragmentTarget(document, entryKey, frag);
+      if (!el) return false;
+      el.scrollIntoView();
+      done = true;
+      return true;
+    };
+
+    // The first attempt succeeds on the safe path — that effect runs after the body has
+    // committed. On the COMPILED path it cannot: `<Include>` owns an internal Suspense, so
+    // this mounts while the entry is still being compiled in-browser, and the retry is the
+    // whole mechanism rather than a fallback.
+    //
+    // The window is sized from measurement, not taste (R3-252). Time from mount to a
+    // rendered body on the real host: ~2.6s for a 3K entry, ~12s for 37K, ~24s for the
+    // 282K `UI_AS_APPS_SPEC`. The old 5s bound was tuned for the safe renderer (~2–10s)
+    // and silently expired mid-compile on any large spec — the citation landed on the
+    // page and never reached the section. 30s clears the largest entry with margin;
+    // polling is 200ms, it stops on the first success, and it cannot outlive the entry.
+    if (attempt()) return;
+    const timer = setInterval(() => { if (attempt()) clearInterval(timer); }, 200);
+    const stop = setTimeout(() => clearInterval(timer), 30_000);
+    return () => { clearInterval(timer); clearTimeout(stop); };
+  }, [entryKey, frag]);
+
+  return null;
+}