@immediately-run/grove 0.1.5 → 0.1.8

package/src/hooks/useHeadingFragmentUrl.ts

@@ -0,0 +1,98 @@
+import { useCallback, useEffect } from 'react';
+import { useContext } from 'react';
+import { navigate } from '@immediately-run/sdk';
+import { TinkerableContext } from '@immediately-run/sdk/TinkerableContext';
+import { constructOuterUrl } from '@immediately-run/sdk/urlUtils';
+import { fragmentOf } from '../lib/fragment';
+
+/**
+ * Reflect same-page heading navigation in the ADDRESS BAR.
+ *
+ * The deep-linking pair has exactly one half so far: the host forwards the outer URL's
+ * `#fragment` in (R3-249, Capability C §13.5) and `<ScrollToFragment>` lands it — but
+ * nothing ever WRITES a fragment, so a reader who follows the contents rail, clicks a
+ * heading permalink or lands on a section has a URL bar that still names no section.
+ * Copying the address gives someone else the top of the page.
+ *
+ * This hook is the outgoing half. A delegated `click` listener on the document covers
+ * every way a heading is reached without each surface wiring its own handler:
+ *
+ *  - the contents rail's `<a href="#id">` (grove's `<TableOfContents>` smooth-scrolls
+ *    itself; the URL simply never heard about it);
+ *  - the SDK's `<HeadingAnchor>` permalinks — absolute host URLs whose own pathname
+ *    (a `/files/…` subpath) must NOT be navigated to, so only the FRAGMENT is taken and
+ *    the target is rebuilt on the reader's current path;
+ *  - a click on a heading element with an id (any depth).
+ *
+ * `navigate()` is the sanctioned app→host URL channel: an in-prefix `urlchange` whose
+ * target carries a hash is pushed onto the browser's address bar without a reload, and
+ * the echoed navigation sets `navigationState.hash`, which is what `<ScrollToFragment>`
+ * re-runs on — the platform's own loop completes the landing. Modifier clicks are the
+ * browser's (open-in-new-tab and copy-link are what the permalink's absolute href is
+ * FOR); a fragment naming nothing on the page is ignored rather than pushed; and a
+ * fragment equal to the one already in the URL does not stack another history entry.
+ *
+ * Off-host (`vite dev`, an empty `outerHref`) there is no host to tell, so the fragment
+ * is written to the frame's own URL with `history.replaceState` — a reload then lands
+ * where the reader was, and no history is spent.
+ */
+export function useHeadingFragmentUrl(): void {
+  // Deep import per <ScrollToFragment>'s precedent: the context is not on the SDK's
+  // index surface, and this app reads it for `outerHref`/`navigationState` only.
+  const ctx = useContext(TinkerableContext) as {
+    outerHref?: string;
+    navigationState?: { hash?: string };
+  };
+
+  const sync = useCallback(
+    (fragment: string) => {
+      const navigationState = ctx?.navigationState;
+      if (!ctx?.outerHref || !navigationState) {
+        try {
+          history.replaceState(null, '', `#${fragment}`);
+        } catch {
+          // a history the browser refuses is dev noise, not an error
+        }
+        return;
+      }
+      navigate(constructOuterUrl(ctx.outerHref, `#${fragment}`, navigationState as never));
+    },
+    [ctx],
+  );
+
+  useEffect(() => {
+    const onClick = (event: MouseEvent) => {
+      if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+      const fragment = clickedFragment(event.target as HTMLElement | null, ctx?.outerHref ?? '');
+      if (!fragment) return;
+      // Already shown (locator-glued dev hashes included — `fragmentOf` takes the
+      // leading component): a second push would only stack a history entry.
+      if (fragmentOf(ctx?.navigationState?.hash) === fragment) return;
+      if (!document.getElementById(fragment) && !document.querySelector(`[data-slug="${fragment}"]`)) return;
+      sync(fragment);
+    };
+    document.addEventListener('click', onClick);
+    return () => document.removeEventListener('click', onClick);
+  }, [sync, ctx]);
+}
+
+/** The fragment this click addresses, or null when it is not heading navigation. */
+function clickedFragment(element: HTMLElement | null, outerHref: string): string | null {
+  const anchor = element?.closest('a');
+  if (anchor) {
+    const href = anchor.getAttribute('href') ?? '';
+    if (href.startsWith('#')) return fragmentOf(href);
+    try {
+      const url = new URL(href, window.location.href);
+      // Absolute hrefs: only the app's OWN permalink URLs count. Their origin is the
+      // outer origin — the sandbox frame's `location.origin` is different, so compare
+      // against the outer href, never against the frame.
+      const ownOrigin = outerHref ? new URL(outerHref).origin : window.location.origin;
+      if (!url.hash || url.origin !== ownOrigin) return null;
+      return fragmentOf(url.hash);
+    } catch {
+      return null;
+    }
+  }
+  return element?.closest('h1[id], h2[id], h3[id], h4[id]')?.id ?? null;
+}

package/src/lib/content.test.ts

@@ -147,7 +147,7 @@ describe('linkKind — which hrefs may become a navigating <a>', () => {
 // dispatch declares CORPUS-relative (the host joins its chroot prefix — the corpus's
 // repo-side location is host knowledge this app cannot see).
 import { viewedDocumentForTarget } from './content';
-import { setContentRoot, resetContentRoot } from './contentRoot';
+import { setContentRoot, resetContentRoot, isDispatched } from './contentRoot';
 import { afterEach } from 'vitest';
 
 describe('viewedDocumentForTarget — the R3-268 declaration path space', () => {
@@ -195,6 +195,25 @@ describe('viewedDocumentForTarget — the R3-268 declaration path space', () =>
 // answer "which PATH?" as well as "which entry?" — `[the handbook](handbook)` names
 // something real and must not render as a broken link.
 describe('hrefTargetKey — resolution without the entry-file requirement', () => {
+  afterEach(resetContentRoot);
+  it('R3-184 S2 — the $fs: clamp, ON THE RENDER PATH (the join: isDispatched → resolveLinkTarget)', () => {
+    // The clamp that is in force lives in hrefTargetKey's linkSpaceOpts: the
+    // decision (isDispatched) and the emission (resolveLinkTarget) join in ONE
+    // call, and THIS is the join — ways_of_working §4's rule that a decision and
+    // an emitter can both be tested while the line joining them is not.
+    // Fork (own repo): $fs: stays mount-absolute, as shipped (R3-273).
+    expect(hrefTargetKey('$fs:/mnt/aaa/x.mdx', HOME)).toBe('/mnt/aaa/x.mdx');
+    // Dispatched (a corpus mount): the shared resolver clamps $fs: onto the
+    // bundle root (R3-319's bundleChrooted), so the app-level mount point is
+    // not nameable — the resolved target is a CORPUS path, and only a real
+    // corpus entry there resolves downstream.
+    setContentRoot('/mnt/chroot1');
+    expect(hrefTargetKey('$fs:/mnt/aaa/x.mdx', '/mnt/chroot1/h.mdx')).toBe('/mnt/chroot1/mnt/aaa/x.mdx');
+    // And the same corpus path by its ordinary spelling resolves identically —
+    // the clamp makes $fs:/p and /p the same address, which is the invariant.
+    expect(hrefTargetKey('/mnt/aaa/x.mdx', '/mnt/chroot1/h.mdx')).toBe('/mnt/chroot1/mnt/aaa/x.mdx');
+  });
+
   it('resolves a folder href the entry-candidate list rejects', () => {
     expect(hrefKeyCandidates('handbook', HOME)).toEqual([]);
     expect(hrefTargetKey('handbook', HOME)).toBe('/app/content/handbook');
@@ -275,3 +294,30 @@ describe('link-space parity (LINK_SPACE_FIXTURE, R3-277b)', () => {
     );
   });
 });
+
+describe('isDispatched — the R3-184 S2 `$fs:` clamp discriminator', () => {
+  afterEach(resetContentRoot);
+  // The clamp caller (GroveWiki's LinkSpaceContext) keys the SDK's
+  // `bundleChrooted` flag on this: a DISPATCHED corpus renders inside a
+  // host-minted chroot, so `$fs:` resolves within the corpus and a federated
+  // mount materialised beside it is not nameable from a corpus document; the
+  // fork's `$fs:` stays mount-absolute, as shipped. The flag derivation is
+  // one line over THIS module's state. The JOIN — this decision reaching the
+  // shared resolver on the render path — is pinned by the `$fs:` clamp case in
+  // the hrefTargetKey describe above (the two tests are the pair: the decision
+  // here, the emission there, and the wire between them asserted once).
+  it('fork (own repo): false — the corpus is the engine repo, not a chroot', () => {
+    expect(isDispatched()).toBe(false);
+  });
+
+  it('dispatch (a corpus mount): true', () => {
+    setContentRoot('/mnt/0a1b2c3d');
+    expect(isDispatched()).toBe(true);
+  });
+
+  it('the afterEach resets the root — a later reader sees the fork state', () => {
+    // The reset itself is the convention's job (afterEach, above); asserting it
+    // keeps the leak-visible property testable rather than assumed.
+    expect(isDispatched()).toBe(false);
+  });
+});

package/src/lib/content.ts

@@ -186,6 +186,25 @@ export function hrefKeyCandidates(href: string, fromKey: string): string[] {
  * The two callers ask different questions of the same resolution — "which entry?" and
  * "which path?" — so the resolution lives here once.
  */
+// R3-184 S2 (PERSISTENCE_SPEC §8.3) — the `$fs:` clamp ON the render path, the one
+// the spec's dated note names as the missing piece. This file's hrefTargetKey is
+// where a corpus document's link targets actually resolve (grove's own WikiLink
+// override routes here), so the clamp lives HERE: `bundleChrooted: isDispatched()`
+// makes the shared resolver treat `$fs:/p` exactly like `/p` under the bundle root
+// (R3-319), so a dispatched corpus document's `$fs:/mnt/{hash}/…` cannot name a
+// federated mount materialised beside it — the app-level mount point is not a
+// corpus path. The fork (own repo, not a corpus mount) keeps `$fs:`
+// mount-absolute, as shipped. The LinkSpaceContext field in GroveWiki carries the
+// same flag for the SDK's generic component consumers, the day a release that
+// forwards it is pinned.
+const linkSpaceOpts = (fromKey: string) => ({
+  currentFile: fromKey,
+  // The canonical spelling (mdx-plugins reads bundleRoot-else-corpusRoot; the
+  // deprecated corpusRoot opts field stays for older consumers, not for new code).
+  bundleRoot: getContentRoot(),
+  bundleChrooted: isDispatched(),
+});
+
 export function hrefTargetKey(href: string, fromKey: string): string | null {
   if (!href) return null;
   if (/^(https?:|mailto:|tel:|#)/i.test(href)) return null;
@@ -198,7 +217,7 @@ export function hrefTargetKey(href: string, fromKey: string): string | null {
   // targets resolve against the authoring file; `$fs:` targets resolve
   // mount-absolute (addressing, never reach — R3-273).
   if (!path.startsWith('/')) {
-    const rel = resolveLinkTarget(path, { currentFile: fromKey, corpusRoot: getContentRoot() });
+    const rel = resolveLinkTarget(path, linkSpaceOpts(fromKey));
     if (rel.state !== 'resolved') return null;
     // Confinement, not tidiness: an href in foreign content is untrusted, and the
     // result flows into `fs` reads. In the default space anything that lands outside
@@ -221,7 +240,7 @@ export function hrefTargetKey(href: string, fromKey: string): string | null {
     const legacy = normalizeAbsolute(legacyAnchor + path);
     if (legacy.startsWith(contentDir())) return legacy;
   }
-  const corpusAnchored = resolveLinkTarget(path, { currentFile: fromKey, corpusRoot: getContentRoot() });
+  const corpusAnchored = resolveLinkTarget(path, linkSpaceOpts(fromKey));
   if (corpusAnchored.state === 'resolved' && corpusAnchored.path.startsWith(contentDir())) {
     return corpusAnchored.path;
   }