janux 0.1.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janux",
-  "version": "0.1.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",
@@ -42,5 +42,8 @@
   ],
   "files": [
     "src"
-  ]
+  ],
+  "dependencies": {
+    "diff-dom-streaming": "^0.6.6"
+  }
 }

package/src/client/boot.test.ts

@@ -165,6 +165,93 @@ describe('client boot (resume without hydration)', () => {
     expect(clientQuery).toHaveBeenCalledTimes(0);
   });
 
+  it('emits janux:tool-call events around bridge calls (agent activity)', async () => {
+    const client = await serveAndBoot();
+    const phases: string[] = [];
+    const onTool = (event: any) => phases.push(`${event.detail.tool}:${event.detail.phase}`);
+
+    document.addEventListener('janux:tool-call', onTool);
+    await client.call('counter.inc');
+    const proposal: any = await client.call('counter.reset');
+
+    expect(phases).toEqual([
+      'counter.inc:start',
+      'counter.inc:ok',
+      'counter.reset:start',
+      'counter.reset:proposal',
+    ]);
+    document.removeEventListener('janux:tool-call', onTool);
+    await client.approve(proposal.id);
+  });
+
+  it('glow targets the element carrying the intent marker, falling back to the island', async () => {
+    const { html, snapshots } = await renderToString(jsx(counter as any, {}), {
+      initialState: { 'ui://counter#default': { n: 5, history: [] } },
+      storeDefs: { session },
+    });
+    const scripts = snapshots
+      .map(
+        (s) =>
+          `<script type="application/janux+state" data-uri="${s.uri}">${JSON.stringify({ state: s.state, sources: s.sources ?? {} })}</script>`,
+      )
+      .join('');
+
+    document.body.innerHTML = html + scripts;
+    document.getElementById('janux-glow-styles')?.remove();
+    const client = boot({ defs: [counter, session], glow: { duration: 10 } });
+    const island = document.querySelector('janux-island')!;
+    const incButton = document.querySelector('[data-jxa="counter#default:inc"]')!;
+
+    // counter.inc has a button in the view → the BUTTON glows, not the island
+    const pending = client.call('counter.inc');
+
+    expect(incButton.classList.contains('janux-agent-glow')).toBe(true);
+    expect(island.classList.contains('janux-agent-glow')).toBe(false);
+    await pending;
+    // the intent mutated state → re-render happened; morph must NOT wipe the class
+    expect(document.querySelector('[data-jxa="counter#default:inc"]')!.classList.contains('janux-agent-glow')).toBe(true);
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    // confirm-guarded intents do NOT glow on call — nothing executed yet
+    const resetPending = client.call('counter.reset');
+
+    expect(island.classList.contains('janux-agent-glow')).toBe(false);
+    const proposal: any = await resetPending;
+
+    expect(document.querySelectorAll('.janux-agent-glow')).toHaveLength(0);
+
+    // the glow happens on APPROVAL, when the action actually runs
+    const approvePending = client.approve(proposal.id);
+
+    expect(island.classList.contains('janux-agent-glow')).toBe(true);
+    await approvePending;
+  });
+
+  it('boot({ glow: true }) injects styles and glows the operated island', async () => {
+    const { html, snapshots } = await renderToString(jsx(counter as any, {}), {
+      initialState: { 'ui://counter#default': { n: 1, history: [] } },
+      storeDefs: { session },
+    });
+    const scripts = snapshots
+      .map(
+        (s) =>
+          `<script type="application/janux+state" data-uri="${s.uri}">${JSON.stringify({ state: s.state, sources: s.sources ?? {} })}</script>`,
+      )
+      .join('');
+
+    document.body.innerHTML = html + scripts;
+    document.getElementById('janux-glow-styles')?.remove();
+    const client = boot({ defs: [counter, session], glow: { duration: 10 } });
+
+    expect(document.getElementById('janux-glow-styles')).not.toBeNull();
+    const pending = client.call('counter.inc');
+
+    expect(document.querySelectorAll('.janux-agent-glow')).toHaveLength(1);
+    await pending;
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(document.querySelectorAll('.janux-agent-glow')).toHaveLength(0);
+  });
+
   it('survives a malformed state snapshot (boot regression)', async () => {
     document.body.innerHTML =
       '<script type="application/janux+state" data-uri="ui://broken">{not json</script>';

package/src/client/boot.ts

@@ -4,15 +4,26 @@ import type { Proposal } from '../runtime/intents';
 import { createBridge, type JanuxBridge } from './bridge';
 import { mountIsland, type MountContext } from './mount';
 import { createClientRegistry, registerDef, type IslandLoader } from './registry';
+import { enableAgentGlow, type GlowOptions } from './glow';
+import { mountEagerIslands, performNavigation } from './navigate';
+import { prefetch } from './prefetch';
+import { installWebMCP } from './webmcp';
 
 export interface BootOptions {
   islands?: Record<string, IslandLoader>;
   defs?: ComponentDef[];
   ctx?: Record<string, unknown>;
+  /** Highlight islands while an agent operates them. `true` or `{ duration }`. */
+  glow?: boolean | GlowOptions;
+  /** SPA navigation via the Navigation API + streamed DOM diff. Default: true. */
+  navigation?: boolean;
+  /** Register mounted tools with `document.modelContext` (WebMCP), polyfilled when absent. Default: true. */
+  webmcp?: boolean;
 }
 
 export interface JanuxClient extends JanuxBridge {
   mount(id: string): Promise<unknown>;
+  navigate(url: string): Promise<void>;
   proposals: Map<string, Proposal>;
 }
 
@@ -59,8 +70,7 @@ function formInput(form: HTMLFormElement): Record<string, unknown> {
 }
 
 function trackInflight(mount: MountContext, work: Promise<unknown>): void {
-  mount.inflight.add(work);
-  work.catch(reportIntentError).finally(() => mount.inflight.delete(work));
+  awaitTracked(mount, work).catch(reportIntentError);
 }
 
 function listen(mount: MountContext): void {
@@ -86,6 +96,59 @@ function reportIntentError(error: unknown): void {
   document.dispatchEvent(new CustomEvent('janux:error', { detail: String(error) }));
 }
 
+/** Tracks navigation work in `inflight` (settled() waits it) while propagating failures. */
+async function awaitTracked(mount: MountContext, work: Promise<unknown>): Promise<void> {
+  mount.inflight.add(work);
+  try {
+    await work;
+  } finally {
+    mount.inflight.delete(work);
+  }
+}
+
+let nativeClickAt = 0;
+
+function shouldIntercept(event: any): boolean {
+  if (!event.canIntercept || event.hashChange || event.downloadRequest || event.formData) return false;
+  if (new URL(event.destination.url).origin !== location.origin) return false;
+  // Prefer the precise source element; fall back to a recent data-native click.
+  if (event.sourceElement) return !event.sourceElement.closest?.('[data-native]');
+  const wasNative = Date.now() - nativeClickAt < 100;
+
+  nativeClickAt = 0;
+
+  return !wasNative;
+}
+
+/**
+ * Navigation API interception (Baseline 2026). Browsers without it keep
+ * native MPA links — which already work — so there is no History fallback.
+ */
+function installNavigation(mount: MountContext): void {
+  const nav = (window as any).navigation;
+
+  document.addEventListener(
+    'click',
+    (event) => {
+      if ((event.target as Element | null)?.closest?.('[data-native]')) nativeClickAt = Date.now();
+    },
+    true,
+  );
+  nav?.addEventListener('navigate', (event: any) => {
+    if (!shouldIntercept(event)) return;
+    event.intercept({
+      scroll: 'after-transition',
+      handler: () =>
+        awaitTracked(mount, performNavigation(event.destination.url, mount, { signal: event.signal })),
+    });
+  });
+  document.addEventListener('mouseover', (event) => {
+    const link = (event.target as Element | null)?.closest?.('a[href^="/"]:not([data-native])');
+
+    if (link) prefetch((link as HTMLAnchorElement).href);
+  });
+}
+
 /**
  * Resumes a server-rendered page: indexes islands and state snapshots,
  * installs delegated listeners, and exposes the gui-agent bridge.
@@ -111,6 +174,8 @@ export function boot(options: BootOptions = {}): JanuxClient {
   (options.defs ?? []).forEach((def) => registerDef(registry, def));
   readSnapshots(mount);
   listen(mount);
+  if (options.glow) enableAgentGlow(options.glow === true ? {} : options.glow);
+  if (options.navigation !== false) installNavigation(mount);
   const bridge = createBridge(mount, proposals);
   const client: JanuxClient = {
     ...bridge,
@@ -122,9 +187,18 @@ export function boot(options: BootOptions = {}): JanuxClient {
 
       return mountIsland(id, root, mount);
     },
+    async navigate(url: string) {
+      const nav = (window as any).navigation;
+
+      // Through the interceptor when the platform has it; direct SPA otherwise.
+      if (nav?.navigate) await nav.navigate(url).finished;
+      else await awaitTracked(mount, performNavigation(new URL(url, location.href).href, mount));
+    },
   };
 
   if (typeof window !== 'undefined') (window as any).janux = client;
+  if (options.webmcp !== false) installWebMCP(bridge);
+  mountEagerIslands(mount).catch(reportIntentError);
 
   return client;
 }

package/src/client/bridge.ts

@@ -1,4 +1,5 @@
 import { buildManifest, type Manifest } from '../manifest';
+import { resolveGuard } from '../runtime/intents';
 import type { JanuxInstance } from '../runtime/instance';
 import type { Proposal } from '../runtime/intents';
 import { ensureStore, mountIsland, type MountContext } from './mount';
@@ -39,6 +40,33 @@ function liveInstances(registry: ClientRegistry): JanuxInstance[] {
   return [...registry.mounted.values(), ...registry.stores.values()];
 }
 
+interface ToolEventExtras {
+  guard?: string;
+  approval?: boolean;
+}
+
+/** Resolves an intent's guard synchronously from the registered defs (no mount needed). */
+function guardOf(mount: MountContext, component: string, intentName: string): string {
+  const def =
+    mount.registry.defs.get(component) ?? mount.registry.stores.get(component)?.def;
+  const intentDef = def?.intents?.[intentName];
+
+  return intentDef ? resolveGuard(intentDef, mount.ctx) : 'auto';
+}
+
+/** Emits `janux:tool-call` DOM events so apps can visualize agent activity (glow, chat lines). */
+function emitToolEvent(
+  tool: string,
+  input: unknown,
+  phase: 'start' | 'ok' | 'proposal' | 'error',
+  extras: ToolEventExtras = {},
+): void {
+  if (typeof document === 'undefined') return;
+  document.dispatchEvent(
+    new CustomEvent('janux:tool-call', { detail: { tool, input, phase, ...extras } }),
+  );
+}
+
 /** The gui-agent bridge: `ui.read / ui.call / ui.settled / ui.subscribe` over the mounted tree. */
 export function createBridge(mount: MountContext, proposals: Map<string, Proposal>): JanuxBridge {
   const { registry } = mount;
@@ -53,12 +81,23 @@ export function createBridge(mount: MountContext, proposals: Map<string, Proposa
 
     async call(tool, input) {
       const [component = '', intentName = ''] = tool.split('.');
-      const instance = await instanceFor(component, mount);
-      const invoke = instance.intents[intentName];
+      const guard = guardOf(mount, component, intentName);
+
+      emitToolEvent(tool, input, 'start', { guard });
+      try {
+        const instance = await instanceFor(component, mount);
+        const invoke = instance.intents[intentName];
 
-      if (!invoke) throw new Error(`Janux: unknown tool "${tool}"`);
+        if (!invoke) throw new Error(`Janux: unknown tool "${tool}"`);
+        const result: any = await invoke(input, { origin: 'agent' });
 
-      return invoke(input, { origin: 'agent' });
+        emitToolEvent(tool, input, result?.status === 'proposal' ? 'proposal' : 'ok', { guard });
+
+        return result;
+      } catch (error) {
+        emitToolEvent(tool, input, 'error', { guard });
+        throw error;
+      }
     },
 
     async approve(id) {
@@ -66,8 +105,18 @@ export function createBridge(mount: MountContext, proposals: Map<string, Proposa
 
       if (!proposal) throw new Error(`Janux: unknown proposal "${id}"`);
       proposals.delete(id);
-
-      return proposal.execute();
+      // The approval IS the execution — this is when activity feedback fires.
+      emitToolEvent(proposal.tool, proposal.input, 'start', { guard: 'confirm', approval: true });
+      try {
+        const result = await proposal.execute();
+
+        emitToolEvent(proposal.tool, proposal.input, 'ok', { guard: 'confirm', approval: true });
+
+        return result;
+      } catch (error) {
+        emitToolEvent(proposal.tool, proposal.input, 'error', { guard: 'confirm', approval: true });
+        throw error;
+      }
     },
 
     reject(id) {

package/src/client/glow.ts

@@ -0,0 +1,74 @@
+export const GLOW_CLASS = 'janux-agent-glow';
+
+export interface GlowOptions {
+  /** ms the glow lingers after the call finishes. Default 700. */
+  duration?: number;
+}
+
+/* !important: the glow is runtime-owned feedback and must win over inline
+   view styles (e.g. a button that sets its own box-shadow). */
+const GLOW_CSS = `
+.${GLOW_CLASS} {
+  box-shadow: 0 0 0 3px var(--janux-glow-ring, rgba(124, 58, 237, 0.55)),
+    0 0 var(--janux-glow-spread, 34px) 4px var(--janux-glow-halo, rgba(34, 211, 238, 0.35)) !important;
+  border-radius: var(--janux-glow-radius, 18px);
+  transition: box-shadow 0.25s;
+}`;
+
+/** Idempotently installs the default glow styles. Override via the --janux-glow-* CSS vars. */
+export function injectGlowStyles(doc: Document = document): void {
+  if (doc.getElementById('janux-glow-styles')) return;
+  const style = doc.createElement('style');
+
+  style.id = 'janux-glow-styles';
+  style.textContent = GLOW_CSS;
+  doc.head.appendChild(style);
+}
+
+/** Glows one element now, fading after `duration` ms. */
+export function glowElement(el: Element, duration = 700): void {
+  el.classList.add(GLOW_CLASS);
+  setTimeout(() => el.classList.remove(GLOW_CLASS), duration);
+}
+
+/**
+ * The element that carries the intent's delegation marker (`on={intents.x}` /
+ * `<form intent>`), so the glow points at the exact control the agent "pressed".
+ * Falls back to the whole island when the intent has no element in the view.
+ */
+export function glowTargetFor(tool: string, scope: ParentNode = document): Element | undefined {
+  const [component = '', intentName = ''] = tool.split('.');
+  const island = scope.querySelector(`janux-island[data-jx^="${component}#"]`);
+
+  if (!island) return undefined;
+  const marker = `${island.getAttribute('data-jx')}:${intentName}`;
+
+  return (
+    island.querySelector(`[data-jxa="${marker}"], [data-jxform="${marker}"]`) ?? island
+  );
+}
+
+/**
+ * Highlights the island an agent is operating (gui-agent style): listens to
+ * `janux:tool-call` bridge events and glows the matching island. Returns a
+ * disposer. `boot({ glow: true })` wires this for you.
+ */
+export function enableAgentGlow(options: GlowOptions = {}): () => void {
+  const duration = options.duration ?? 700;
+  const onToolCall = (event: Event): void => {
+    const { tool, phase, guard, approval } = (event as CustomEvent).detail ?? {};
+    const target = tool ? glowTargetFor(tool) : undefined;
+
+    if (!target) return;
+    // confirm-guarded calls only PROPOSE — nothing executes, nothing glows.
+    // The glow fires on approval, when the action actually runs.
+    if (guard === 'confirm' && !approval) return;
+    if (phase === 'start') target.classList.add(GLOW_CLASS);
+    else setTimeout(() => target.classList.remove(GLOW_CLASS), duration);
+  };
+
+  injectGlowStyles();
+  document.addEventListener('janux:tool-call', onToolCall);
+
+  return () => document.removeEventListener('janux:tool-call', onToolCall);
+}

package/src/client/index.ts

@@ -5,3 +5,15 @@ export { mountIsland, type MountContext } from './mount';
 export { morph } from './morph';
 export { toDomNodes } from './dom';
 export { clientApi } from './api-stub';
+export { enableAgentGlow, injectGlowStyles, glowElement, GLOW_CLASS, type GlowOptions } from './glow';
+export { performNavigation, mountEagerIslands } from './navigate';
+export { prefetch } from './prefetch';
+export {
+  installWebMCP,
+  createModelContextPolyfill,
+  type ModelContext,
+  type ModelContextPolyfill,
+  type WebMCPHandle,
+  type WebMCPToolDescriptor,
+} from './webmcp';
+export { collectPageLinks, createNavigateTool, type PageLink } from './navigate-tool';

package/src/client/morph.ts

@@ -1,4 +1,6 @@
 function syncAttrs(from: Element, to: Element): void {
+  const runtimeClasses = [...from.classList].filter((name) => name.startsWith('janux-'));
+
   [...from.getAttributeNames()]
     .filter((name) => !to.hasAttribute(name))
     .forEach((name) => from.removeAttribute(name));
@@ -7,6 +9,9 @@ function syncAttrs(from: Element, to: Element): void {
       from.setAttribute(name, to.getAttribute(name)!);
     }
   });
+  // `janux-*` classes belong to the runtime (e.g. the agent glow) — views
+  // never render them, so re-renders must not wipe them.
+  runtimeClasses.forEach((name) => from.classList.add(name));
 }
 
 function syncValue(from: Element, to: Element): void {

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 ?? '')),
+  };
+}