janux 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janux",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The agent-native UI framework core. One component, two faces: a view for humans, typed MCP tools & resources for AI agents.",
   "repository": {
     "type": "git",

package/src/client/index.ts

@@ -16,3 +16,4 @@ export {
   type WebMCPHandle,
   type WebMCPToolDescriptor,
 } from './webmcp';
+export { collectPageLinks, createNavigateTool, type PageLink } from './navigate-tool';

package/src/client/navigate-tool.test.ts

@@ -0,0 +1,55 @@
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, mock } from 'bun:test';
+import { GLOW_CLASS } from './glow';
+import { collectPageLinks, createNavigateTool } from './navigate-tool';
+
+beforeAll(() => GlobalRegistrator.register({ url: 'https://app.test/docs/guide/components' }));
+afterAll(() => GlobalRegistrator.unregister());
+
+beforeEach(() => {
+  document.body.innerHTML = `
+    <nav>
+      <a href="/docs/guide/components">Components</a>
+      <a href="/docs/guide/cli-and-deployment">CLI and deployment</a>
+      <a href="/docs/guide/cli-and-deployment">CLI (duplicate)</a>
+      <a href="https://github.com/aralroca/Janux">GitHub</a>
+    </nav>`;
+});
+
+describe('collectPageLinks', () => {
+  it('collects same-origin links, deduped, keeping the first label', () => {
+    const links = collectPageLinks();
+
+    expect(links).toEqual([
+      { path: '/docs/guide/components', label: 'Components' },
+      { path: '/docs/guide/cli-and-deployment', label: 'CLI and deployment' },
+    ]);
+  });
+});
+
+describe('createNavigateTool', () => {
+  it('glows the pressed link, then navigates', async () => {
+    const assign = mock((path: string) => path);
+
+    (location as any).assign = assign;
+    const result = createNavigateTool().execute({ path: '/docs/guide/cli-and-deployment' });
+    const anchor = document.querySelector('a[href="/docs/guide/cli-and-deployment"]')!;
+
+    expect(result).toEqual({ navigated: '/docs/guide/cli-and-deployment', label: 'CLI and deployment' });
+    expect(anchor.classList.contains(GLOW_CLASS)).toBe(true);
+    expect(assign).not.toHaveBeenCalled();
+
+    await new Promise((resolve) => setTimeout(resolve, 420));
+    expect(assign).toHaveBeenCalledWith('/docs/guide/cli-and-deployment');
+  });
+
+  it('rejects paths not linked on the page and returns the real links', () => {
+    const assign = mock((path: string) => path);
+
+    (location as any).assign = assign;
+    const result = createNavigateTool().execute({ path: '/docs/made/up' }) as any;
+
+    expect(assign).not.toHaveBeenCalled();
+    expect(result.links.map((link: any) => link.path)).toContain('/docs/guide/components');
+  });
+});

package/src/client/navigate-tool.ts

@@ -0,0 +1,78 @@
+import { glowElement, injectGlowStyles } from './glow';
+import type { WebMCPToolDescriptor } from './webmcp';
+
+export interface PageLink {
+  path: string;
+  label: string;
+}
+
+/** Bounds the tool payload on link-heavy pages. */
+const MAX_LINKS = 100;
+
+function toPageLink(anchor: HTMLAnchorElement): PageLink | undefined {
+  const url = new URL(anchor.getAttribute('href') ?? '', location.href);
+
+  if (url.origin !== location.origin) return undefined;
+
+  return { path: url.pathname + url.search + url.hash, label: anchor.textContent?.trim() ?? '' };
+}
+
+/**
+ * The app's real navigation surface: every same-origin link currently in the
+ * DOM — which is exactly what the JSX projected, SSR'd or client-rendered,
+ * with zero authoring effort.
+ */
+export function collectPageLinks(): PageLink[] {
+  const anchors = [...document.querySelectorAll<HTMLAnchorElement>('a[href]')];
+
+  return anchors
+    .map(toPageLink)
+    .filter((link): link is PageLink => link !== undefined)
+    .filter((link, index, all) => all.findIndex((other) => other.path === link.path) === index)
+    .slice(0, MAX_LINKS);
+}
+
+/** Long enough to see the glow on the link the agent "pressed", short enough to feel instant. */
+const GLOW_BEFORE_NAV_MS = 350;
+
+function anchorFor(path: string): HTMLAnchorElement | undefined {
+  const matches = [...document.querySelectorAll<HTMLAnchorElement>('a[href]')].filter(
+    (anchor) => toPageLink(anchor)?.path === path,
+  );
+
+  // Sidebars often repeat a link in a hidden mobile drawer — glow the visible one.
+  return matches.find((anchor) => anchor.getClientRects().length > 0) ?? matches[0];
+}
+
+function navigateTo(path: string): unknown {
+  const links = collectPageLinks();
+  const resolved = new URL(path, location.href);
+  const wanted = resolved.pathname + resolved.search + resolved.hash;
+  const target = links.find((link) => link.path === wanted);
+  const anchor = target ? anchorFor(target.path) : undefined;
+
+  // Models hallucinate paths; handing back the real links makes the retry self-correcting.
+  if (!target) return { error: `No link to "${path}" on this page. Current links:`, links };
+  if (anchor) {
+    injectGlowStyles();
+    glowElement(anchor);
+    anchor.scrollIntoView({ block: 'nearest' });
+  }
+  setTimeout(() => location.assign(target.path), anchor ? GLOW_BEFORE_NAV_MS : 0);
+
+  return { navigated: target.path, label: target.label };
+}
+
+/** The built-in `navigate` WebMCP tool `installWebMCP` registers on every page. */
+export function createNavigateTool(): WebMCPToolDescriptor {
+  return {
+    name: 'navigate',
+    description: 'Navigate this app to one of the links on the current page, by path.',
+    inputSchema: {
+      type: 'object',
+      properties: { path: { type: 'string', description: 'Target path, e.g. /docs/guide/navigation' } },
+      required: ['path'],
+    },
+    execute: (input) => navigateTo(String((input as { path?: unknown })?.path ?? '')),
+  };
+}

package/src/client/webmcp.test.ts

@@ -115,6 +115,27 @@ describe('WebMCP integration', () => {
     expect(context.listTools().map((tool) => tool.name)).toEqual(['next']);
   });
 
+  it('auto-registers the built-in navigate tool alongside manifest tools', async () => {
+    const client = await serveAndBoot();
+    const handle = installWebMCP(client);
+
+    await handle.sync();
+    expect(polyfillOf().listTools().map((tool) => tool.name)).toContain('navigate');
+  });
+
+  it('an app tool named navigate makes the built-in step aside', async () => {
+    manifestTools = [
+      { name: 'navigate', description: 'App-owned nav', guard: 'auto', input: { type: 'object', properties: { total: { type: 'number' } } } },
+    ];
+    const client = await serveAndBoot();
+    const handle = installWebMCP(client);
+
+    await handle.sync();
+    const navigate = polyfillOf().listTools().find((tool) => tool.name === 'navigate');
+
+    expect(navigate?.description).toContain('App-owned nav');
+  });
+
   it('registers route manifest tools plus live local tools, with sanitized names', async () => {
     const client = await serveAndBoot();
 

package/src/client/webmcp.ts

@@ -1,5 +1,6 @@
 import type { Manifest, ManifestTool } from '../manifest';
 import type { JanuxBridge } from './bridge';
+import { createNavigateTool } from './navigate-tool';
 
 export interface WebMCPToolDescriptor {
   name: string;
@@ -133,12 +134,15 @@ export function installWebMCP(bridge: JanuxBridge): WebMCPHandle {
 
   const run = async (): Promise<void> => {
     const tools = mergedTools(bridge, await routeTools());
+    // An app tool named `navigate` owns the name; the built-in steps aside.
+    const taken = tools.some((tool) => tool.name.replace(/[^\w-]/g, '_') === 'navigate');
+    const descriptors = [...(taken ? [] : [createNavigateTool()]), ...tools.map((tool) => descriptorFor(tool, bridge))];
 
     controller?.abort();
     controller = new AbortController();
-    for (const tool of tools) {
+    for (const descriptor of descriptors) {
       try {
-        await context.registerTool(descriptorFor(tool, bridge), { signal: controller.signal });
+        await context.registerTool(descriptor, { signal: controller.signal });
       } catch {
         // One rejected registration (schema quirks, duplicate names…) must not drop the rest.
       }