@immediately-run/grove 0.1.5 → 0.1.7

package/src/hooks/useCatalogAnswered.test.tsx

@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+// `useCatalogAnswered` — rendered in a real React tree, driven through the SDK's REAL
+// catalog push channel against an emitting stub transport. The whole point of the hook is
+// a timing property of that channel, so a mock of either would assert nothing.
+//
+// The property under test: the push channel has no value-equality check, so a host answer
+// of `[]` — identical to the initial value — still notifies. That second notification is
+// the signal. A test that only pushed a NON-empty catalog would pass against a naive
+// `catalog.length > 0` implementation and prove nothing, which is why the empty-answer
+// case is the one that carries this file.
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+
+type Handler = (msg: Record<string, unknown>) => void;
+const handlers = new Set<Handler>();
+const emit = (msg: Record<string, unknown>): void => {
+  for (const h of handlers) h(msg);
+};
+
+// Installed BEFORE the SDK is imported: the channel resolves its transport lazily, and
+// the hook module subscribes at import time.
+(globalThis as { __immediatelyRun__?: unknown }).__immediatelyRun__ = {
+  transport: {
+    sendMessage: vi.fn(),
+    protocolRequest: vi.fn(async () => ({})),
+    onMessage: (handler: Handler) => {
+      handlers.add(handler);
+      return { dispose: () => handlers.delete(handler) };
+    },
+  },
+};
+
+let useCatalogAnswered: typeof import('./useCatalogAnswered').useCatalogAnswered;
+let getCatalog: typeof import('@immediately-run/sdk').getCatalog;
+
+beforeAll(async () => {
+  ({ useCatalogAnswered } = await import('./useCatalogAnswered'));
+  ({ getCatalog } = await import('@immediately-run/sdk'));
+});
+
+/** Render a probe recording the hook's value on every render. */
+const renderProbe = async () => {
+  const seen: boolean[] = [];
+  const Probe = () => {
+    seen.push(useCatalogAnswered());
+    return null;
+  };
+  const root = createRoot(document.createElement('div'));
+  await act(async () => {
+    root.render(<Probe />);
+  });
+  return { seen, unmount: () => act(async () => root.unmount()) };
+};
+
+describe('useCatalogAnswered', () => {
+  it('is false before the host answers — the subscribe-time call is not an answer', async () => {
+    // `onCatalogChange` invokes its listener once, SYNCHRONOUSLY, with the current value
+    // when you subscribe. If that counted, the flag would be true from module load and
+    // the reach card would read an unanswered catalog as "not granted" — the exact defect
+    // this hook exists to prevent.
+    getCatalog(); // start the channel the way the app does
+    const { seen, unmount } = await renderProbe();
+    expect(seen[seen.length - 1]).toBe(false);
+    await unmount();
+  });
+
+  it('an EMPTY catalog answer flips it, and RE-RENDERS — an empty answer is still an answer', async () => {
+    const { seen, unmount } = await renderProbe();
+    expect(seen[seen.length - 1]).toBe(false);
+    const before = seen.length;
+
+    await act(async () => {
+      emit({ type: 'api-catalog', methods: [] });
+    });
+
+    // Both halves matter: a hook that returned the flag without subscribing would show
+    // the right value only on the NEXT unrelated render.
+    expect(seen.length).toBeGreaterThan(before);
+    expect(seen[seen.length - 1]).toBe(true);
+    await unmount();
+  });
+
+  it('stays true for a probe mounted after the answer', async () => {
+    const { seen, unmount } = await renderProbe();
+    expect(seen[seen.length - 1]).toBe(true);
+    await unmount();
+  });
+});

package/src/hooks/useCatalogAnswered.ts

@@ -0,0 +1,73 @@
+import { useSyncExternalStore } from 'react';
+import { onCatalogChange } from '@immediately-run/sdk';
+
+// Has the host actually ANSWERED the grant-filtered method catalog?
+//
+// `useCatalog()` starts `[]` and an empty catalog is a legitimate answer (a frame granted
+// nothing), so the value alone cannot distinguish "granted nothing" from "has not replied
+// yet". The reach card needs that distinction: `!chatGranted` is true in both cases, and
+// reading it as "not granted" before the host has spoken claims a consent state about a
+// frame that may well hold the grant (grove#75 round 1).
+//
+// It is derivable here with no SDK change, because the push channel has **no
+// value-equality check**: every host push notifies subscribers, including one whose value
+// equals the initial `[]`. So a notification after the subscribe means the host replied.
+//
+// THE SUBSCRIBE-TIME CALL. `onCatalogChange` invokes the listener once, SYNCHRONOUSLY,
+// with the current value before returning. That call is the subscribe, not an answer — but
+// it is not worthless either, and an earlier version of this file threw it away with a
+// blanket reset. A NON-EMPTY catalog at subscribe can only have come from the host, so it
+// is proof the answer already landed. Reading it that way is what makes this correct when
+// the module is evaluated LATE: grove is also published as a pinned library
+// (`src/lib.ts`), so "imported before any render" is an assumption about one embedding,
+// not a guarantee (grove#75 round 3).
+//
+// RESIDUALS, stated rather than implied:
+//  - a host that answers `[]` BEFORE this module is evaluated is indistinguishable from
+//    one that has not answered, and leaves the flag false for the realm's life. The Q&A
+//    row then stays neutral rather than naming a cause — the same honest "we have not been
+//    told" that the provider channel's `unknown` already renders, but it will not
+//    self-correct, because the host does not push again;
+//  - a host that never answers at all leaves it false forever, for the same reason;
+//  - importing this module is what STARTS the catalog channel and sends
+//    `REQUEST_API_CATALOG`. That used to be the first `useCatalog()` render. The channel
+//    starts at most once and the poll is idempotent, but the timing moved.
+let answered = false;
+let subscribing = true;
+const waiters = new Set<() => void>();
+
+onCatalogChange((catalog) => {
+  if (subscribing) {
+    // Synchronous, at subscribe: the current value, not an answer — except that a
+    // non-empty catalog could only have come from the host.
+    answered = catalog.length > 0;
+    return;
+  }
+  if (answered) return;
+  answered = true;
+  for (const w of waiters) w();
+});
+subscribing = false;
+
+const subscribe = (onStoreChange: () => void): (() => void) => {
+  waiters.add(onStoreChange);
+  return () => {
+    waiters.delete(onStoreChange);
+  };
+};
+const getSnapshot = (): boolean => answered;
+
+/**
+ * Whether the host has answered the method catalog. Re-renders when it flips.
+ *
+ * `useSyncExternalStore` rather than `useState` + `useEffect`, deliberately: the flag is
+ * read during render and written outside React, and a passive effect leaves a window
+ * between the two. An answer landing in that window used to be lost — the effect saw the
+ * flag already set, returned early without registering a waiter, and the component
+ * rendered a stale `false` with nothing left to wake it (grove#75 round 3, reproduced).
+ * `useSyncExternalStore` re-reads the snapshot after subscribing and re-renders if it
+ * moved, which is exactly that hole.
+ */
+export function useCatalogAnswered(): boolean {
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

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;
   }