janux 0.1.0

package/README.md

@@ -0,0 +1,11 @@
+# janux
+
+Core of **Janux** — the agent-native fullstack UI framework. One component, two faces: a live view for humans, typed MCP tools & resources for AI agents, generated from the same definition.
+
+This package ships the schema types, signals, bifacial component/store runtime (intents, guards, effects, sources, `settled()`), SSR islands, the manifest builder and the client resume runtime + `window.janux` bridge.
+
+```bash
+bunx create-janux my-app
+```
+
+Docs & source: https://github.com/aralroca/Janux · RFC: https://github.com/aralroca/Janux/issues/1

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "janux",
+  "version": "0.1.0",
+  "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",
+    "url": "https://github.com/aralroca/Janux.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Aral Roca Gomez",
+    "email": "contact@aralroca.com"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/schema/index.ts",
+    "./jsx-runtime": "./src/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/jsx-dev-runtime.ts",
+    "./server": "./src/render/server.ts",
+    "./client": "./src/client/index.ts",
+    "./manifest": "./src/manifest/index.ts"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^15.11.0"
+  },
+  "homepage": "https://github.com/aralroca/Janux#readme",
+  "bugs": "https://github.com/aralroca/Janux/issues",
+  "keywords": [
+    "janux",
+    "agentic-ui",
+    "mcp",
+    "webmcp",
+    "ai-agents",
+    "fullstack",
+    "framework",
+    "bun",
+    "vite",
+    "resumability",
+    "copilot"
+  ],
+  "files": [
+    "src"
+  ]
+}

package/src/client/api-stub.ts

@@ -0,0 +1,18 @@
+/**
+ * Client stub for an api() server function (~100 bytes once bundled).
+ * The compiler swaps `*.api.ts` imports for these in client bundles.
+ */
+export function clientApi(name: string): (input?: unknown) => Promise<unknown> {
+  return async (input?: unknown) => {
+    const response = await fetch(`/_janux/api/${name}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(input ?? {}),
+    });
+    const body: any = await response.json();
+
+    if (!body.ok) throw new Error(body.error ?? `api ${name} failed`);
+
+    return body.result;
+  };
+}

package/src/client/boot.test.ts

@@ -0,0 +1,185 @@
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, mock } from 'bun:test';
+import { component, intent, source, store } from '../define/factories';
+import { jsx } from '../jsx-runtime';
+import { int, list, schema, str } from '../schema';
+import { renderToString } from '../render/server';
+import { boot, type JanuxClient } from './boot';
+
+beforeAll(() => GlobalRegistrator.register());
+afterAll(() => GlobalRegistrator.unregister());
+
+const viewRenders = mock(() => {});
+
+const session = store({
+  name: 'session',
+  state: schema({ locale: str().default('en') }),
+  intents: {
+    setLocale: intent({
+      input: schema({ locale: str() }),
+      run: ({ state, input }) => (state.locale = input.locale),
+    }),
+  },
+});
+
+const counter = component({
+  name: 'counter',
+  state: schema({ n: int(), history: list({ v: int() }) }),
+  use: { session },
+  intents: {
+    inc: intent({ run: ({ state }) => (state.n += 1) }),
+    reset: intent({ guard: 'confirm', run: ({ state }) => (state.n = 0) }),
+  },
+  view: ({ state, intents }: any) => {
+    viewRenders();
+
+    return jsx('div', {
+      children: [
+        jsx('output', { children: `n=${state.n}` }),
+        jsx('button', { on: intents.inc, children: '+1' }),
+      ],
+    });
+  },
+});
+
+async function serveAndBoot(): Promise<JanuxClient> {
+  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;
+  viewRenders.mockClear();
+
+  return boot({ defs: [counter, session] });
+}
+
+describe('client boot (resume without hydration)', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('executes zero component code until first interaction', async () => {
+    await serveAndBoot();
+
+    expect(viewRenders).toHaveBeenCalledTimes(0);
+    expect(document.querySelector('output')!.textContent).toBe('n=5');
+  });
+
+  it('resumes on delegated click: mounts from snapshot and runs the intent', async () => {
+    const client = await serveAndBoot();
+
+    document.querySelector('button')!.click();
+    await client.settled();
+    expect(document.querySelector('output')!.textContent).toBe('n=6');
+    expect(viewRenders.mock.calls.length).toBeGreaterThan(0);
+  });
+
+  it('preserves the SSR DOM nodes across resume (morph, not replace)', async () => {
+    const client = await serveAndBoot();
+    const ssrOutput = document.querySelector('output');
+
+    document.querySelector('button')!.click();
+    await client.settled();
+    expect(document.querySelector('output')).toBe(ssrOutput);
+  });
+
+  it('serves agent reads from the live resource', async () => {
+    const client = await serveAndBoot();
+    const resource: any = await client.read('ui://counter');
+
+    expect(resource.state.n).toBe(5);
+    expect(resource.uri).toBe('ui://counter#default');
+  });
+
+  it('routes agent tool calls through guards: auto runs, confirm proposes', async () => {
+    const client = await serveAndBoot();
+    const proposalEvents: any[] = [];
+
+    document.addEventListener('janux:proposal', (event: any) => proposalEvents.push(event.detail));
+    await client.call('counter.inc');
+    await client.settled();
+    expect(document.querySelector('output')!.textContent).toBe('n=6');
+
+    const proposal: any = await client.call('counter.reset');
+
+    expect(proposal.status).toBe('proposal');
+    expect(document.querySelector('output')!.textContent).toBe('n=6');
+    expect(proposalEvents).toHaveLength(1);
+    await client.approve(proposal.id);
+    await client.settled();
+    expect(document.querySelector('output')!.textContent).toBe('n=0');
+  });
+
+  it('exposes store tools and state through the bridge', async () => {
+    const client = await serveAndBoot();
+
+    await client.call('session.setLocale', { locale: 'es' });
+    const resource: any = await client.read('store://session');
+
+    expect(resource.state.locale).toBe('es');
+  });
+
+  it('resumes source values from the snapshot — no double-fetch, ready intents work on first click', async () => {
+    const clientQuery = mock(async () => ['should-not-run']);
+    const shopDef = component({
+      name: 'minishop',
+      state: schema({ picks: int() }),
+      sources: { catalog: source({ query: clientQuery }) },
+      intents: {
+        pick: intent({
+          ready: ({ sources: s }: any) => !s.catalog.pending,
+          run: ({ state }: any) => (state.picks += 1),
+        }),
+      },
+      view: ({ state, intents }: any) =>
+        jsx('div', {
+          children: [
+            jsx('output', { children: String(state.picks) }),
+            jsx('button', { on: intents.pick, children: 'pick' }),
+          ],
+        }),
+    });
+    const { html, snapshots } = await renderToString(jsx(shopDef as any, {}));
+
+    clientQuery.mockClear();
+    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;
+    const client = boot({ defs: [shopDef] });
+
+    document.querySelector('button')!.click();
+    await client.settled();
+    expect(document.querySelector('output')!.textContent).toBe('1');
+    expect(clientQuery).toHaveBeenCalledTimes(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>';
+    const client = boot({ defs: [counter] });
+
+    expect(client.manifest().tools).toEqual([]);
+  });
+
+  it('builds a live manifest from the mounted tree', async () => {
+    const client = await serveAndBoot();
+
+    await client.mount('counter#default');
+    const manifest = client.manifest();
+
+    expect(manifest.tools.map((t) => t.name)).toContain('counter.inc');
+    expect(manifest.resources.map((r) => r.uri)).toContain('ui://counter');
+  });
+});

package/src/client/boot.ts

@@ -0,0 +1,130 @@
+import { createBus } from '../runtime/bus';
+import type { ComponentDef } from '../define/types';
+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';
+
+export interface BootOptions {
+  islands?: Record<string, IslandLoader>;
+  defs?: ComponentDef[];
+  ctx?: Record<string, unknown>;
+}
+
+export interface JanuxClient extends JanuxBridge {
+  mount(id: string): Promise<unknown>;
+  proposals: Map<string, Proposal>;
+}
+
+function readSnapshots(mount: MountContext): void {
+  document.querySelectorAll('script[type="application/janux+state"]').forEach((script) => {
+    const uri = script.getAttribute('data-uri');
+
+    if (!uri) return;
+    try {
+      mount.registry.snapshots.set(uri, JSON.parse(script.textContent ?? '{}'));
+    } catch {
+      reportIntentError(`invalid state snapshot for ${uri}`);
+    }
+  });
+}
+
+function markerTarget(
+  event: Event,
+  attr: string,
+): { marker: string; root: Element; el: Element } | undefined {
+  const el = (event.target as Element | null)?.closest?.(`[${attr}]`);
+  const root = el?.closest('janux-island[data-jx]');
+
+  if (!el || !root) return undefined;
+
+  return { marker: el.getAttribute(attr)!, root, el };
+}
+
+function elementInput(el: Element): unknown {
+  const raw = el.getAttribute('data-input');
+
+  return raw ? JSON.parse(raw) : undefined;
+}
+
+async function invokeMarker(marker: string, root: Element, mount: MountContext, input?: unknown) {
+  const [id = '', intentName = ''] = marker.split(':');
+  const instance = await mountIsland(id, root, mount);
+
+  return instance.intents[intentName]?.(input);
+}
+
+function formInput(form: HTMLFormElement): Record<string, unknown> {
+  return Object.fromEntries(new FormData(form).entries());
+}
+
+function trackInflight(mount: MountContext, work: Promise<unknown>): void {
+  mount.inflight.add(work);
+  work.catch(reportIntentError).finally(() => mount.inflight.delete(work));
+}
+
+function listen(mount: MountContext): void {
+  document.addEventListener('click', (event) => {
+    const found = markerTarget(event, 'data-jxa');
+
+    if (!found) return;
+    event.preventDefault();
+    trackInflight(mount, invokeMarker(found.marker, found.root, mount, elementInput(found.el)));
+  });
+  document.addEventListener('submit', (event) => {
+    const found = markerTarget(event, 'data-jxform');
+
+    if (!found) return;
+    event.preventDefault();
+    const input = formInput(event.target as HTMLFormElement);
+
+    trackInflight(mount, invokeMarker(found.marker, found.root, mount, input));
+  });
+}
+
+function reportIntentError(error: unknown): void {
+  document.dispatchEvent(new CustomEvent('janux:error', { detail: String(error) }));
+}
+
+/**
+ * Resumes a server-rendered page: indexes islands and state snapshots,
+ * installs delegated listeners, and exposes the gui-agent bridge.
+ * No component code executes until first interaction or agent call.
+ */
+export function boot(options: BootOptions = {}): JanuxClient {
+  const registry = createClientRegistry();
+  const proposals = new Map<string, Proposal>();
+  const mount: MountContext = {
+    registry,
+    bus: createBus(),
+    ctx: options.ctx ?? {},
+    inflight: new Set(),
+    onProposal: (proposal) => {
+      proposals.set((proposal as Proposal).id, proposal as Proposal);
+      document.dispatchEvent(new CustomEvent('janux:proposal', { detail: proposal }));
+    },
+  };
+
+  Object.entries(options.islands ?? {}).forEach(([name, loader]) => {
+    registry.loaders.set(name, loader);
+  });
+  (options.defs ?? []).forEach((def) => registerDef(registry, def));
+  readSnapshots(mount);
+  listen(mount);
+  const bridge = createBridge(mount, proposals);
+  const client: JanuxClient = {
+    ...bridge,
+    proposals,
+    mount(id: string) {
+      const root = document.querySelector(`janux-island[data-jx="${id}"]`);
+
+      if (!root) throw new Error(`Janux: island "${id}" not found in the document`);
+
+      return mountIsland(id, root, mount);
+    },
+  };
+
+  if (typeof window !== 'undefined') (window as any).janux = client;
+
+  return client;
+}

package/src/client/bridge.ts

@@ -0,0 +1,106 @@
+import { buildManifest, type Manifest } from '../manifest';
+import type { JanuxInstance } from '../runtime/instance';
+import type { Proposal } from '../runtime/intents';
+import { ensureStore, mountIsland, type MountContext } from './mount';
+import type { ClientRegistry } from './registry';
+
+export interface JanuxBridge {
+  read(uri: string): Promise<Record<string, unknown>>;
+  call(tool: string, input?: unknown): Promise<unknown>;
+  approve(id: string): Promise<unknown>;
+  reject(id: string): boolean;
+  settled(scope?: string): Promise<void>;
+  subscribe(event: string, handler: (payload: unknown) => void): () => void;
+  manifest(): Manifest;
+}
+
+function islandIdFor(component: string): string | undefined {
+  const exact = document.querySelector(`janux-island[data-jx^="${component}#"]`);
+
+  return exact?.getAttribute('data-jx') ?? undefined;
+}
+
+async function instanceFor(component: string, mount: MountContext): Promise<JanuxInstance> {
+  const storeInstance = mount.registry.stores.get(component);
+
+  if (storeInstance) return storeInstance;
+  const registeredDef = mount.registry.defs.get(component);
+
+  if (registeredDef?.kind === 'store') return ensureStore(registeredDef, mount);
+  const id = islandIdFor(component);
+
+  if (!id) throw new Error(`Janux: no mounted surface for "${component}"`);
+  const root = document.querySelector(`janux-island[data-jx="${id}"]`)!;
+
+  return mountIsland(id, root, mount);
+}
+
+function liveInstances(registry: ClientRegistry): JanuxInstance[] {
+  return [...registry.mounted.values(), ...registry.stores.values()];
+}
+
+/** 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;
+
+  return {
+    async read(uri) {
+      const [, name = ''] = /^(?:ui|store):\/\/([^#]+)/.exec(uri) ?? [];
+      const instance = await instanceFor(name, mount);
+
+      return instance.resource();
+    },
+
+    async call(tool, input) {
+      const [component = '', intentName = ''] = tool.split('.');
+      const instance = await instanceFor(component, mount);
+      const invoke = instance.intents[intentName];
+
+      if (!invoke) throw new Error(`Janux: unknown tool "${tool}"`);
+
+      return invoke(input, { origin: 'agent' });
+    },
+
+    async approve(id) {
+      const proposal = proposals.get(id);
+
+      if (!proposal) throw new Error(`Janux: unknown proposal "${id}"`);
+      proposals.delete(id);
+
+      return proposal.execute();
+    },
+
+    reject(id) {
+      return proposals.delete(id);
+    },
+
+    async settled(scope) {
+      do {
+        await Promise.all([...mount.inflight]);
+        const targets = scope
+          ? [await instanceFor(scope.replace(/^(ui|store):\/\//, '').split('#')[0]!, mount)]
+          : liveInstances(registry);
+
+        await Promise.all(targets.map((instance) => instance.settled()));
+      } while (mount.inflight.size > 0);
+    },
+
+    subscribe(event, handler) {
+      return mount.bus.on(event, handler);
+    },
+
+    manifest() {
+      const mountedEntries = [...registry.mounted.values()].map((instance) => ({
+        def: instance.def,
+        key: instance.uri.split('#')[1],
+        instance,
+      }));
+      const storeEntries = [...registry.stores.values()].map((instance) => ({
+        def: instance.def,
+        instance,
+      }));
+
+      return buildManifest([...mountedEntries, ...storeEntries], mount.ctx);
+    },
+  };
+}

package/src/client/dom.ts

@@ -0,0 +1,47 @@
+import { Fragment, type JanuxNode } from '../jsx-runtime';
+import { attrEntries } from '../render/html';
+import type { ComponentDef } from '../define/types';
+
+function isComponentDef(type: unknown): type is ComponentDef {
+  return typeof type === 'object' && type !== null && 'kind' in (type as any);
+}
+
+function setAttr(el: Element, name: string, value: unknown): void {
+  if (value === false || value === null || value === undefined) return;
+
+  el.setAttribute(name, value === true ? '' : String(value));
+}
+
+function appendChildren(el: Element, children: unknown): void {
+  toDomNodes(children).forEach((node) => el.appendChild(node));
+}
+
+function elementFor(node: JanuxNode): Element {
+  const el = document.createElement(node.$t as string);
+
+  attrEntries(node.$p).forEach(([name, value]) => setAttr(el, name, value));
+  if (typeof node.$p.dangerHTML === 'string') el.innerHTML = node.$p.dangerHTML;
+  else appendChildren(el, node.$p.children);
+
+  return el;
+}
+
+/** Expands a client view tree (static fns inline) into real DOM nodes. */
+export function toDomNodes(node: unknown): Node[] {
+  if (node === null || node === undefined || typeof node === 'boolean') return [];
+  if (typeof node === 'string' || typeof node === 'number') {
+    return [document.createTextNode(String(node))];
+  }
+  if (Array.isArray(node)) return node.flatMap(toDomNodes);
+  const jsxNode = node as JanuxNode;
+
+  if (jsxNode.$t === Fragment) return toDomNodes(jsxNode.$p.children);
+  if (typeof jsxNode.$t === 'function') return toDomNodes((jsxNode.$t as any)(jsxNode.$p));
+  if (isComponentDef(jsxNode.$t)) {
+    throw new Error(
+      `Janux: nested island <${jsxNode.$t.name}> inside another island is not supported yet`,
+    );
+  }
+
+  return [elementFor(jsxNode)];
+}

package/src/client/index.ts

@@ -0,0 +1,7 @@
+export { boot, type BootOptions, type JanuxClient } from './boot';
+export { createBridge, type JanuxBridge } from './bridge';
+export { registerDef, createClientRegistry, type ClientRegistry } from './registry';
+export { mountIsland, type MountContext } from './mount';
+export { morph } from './morph';
+export { toDomNodes } from './dom';
+export { clientApi } from './api-stub';

package/src/client/morph.ts

@@ -0,0 +1,65 @@
+function syncAttrs(from: Element, to: Element): void {
+  [...from.getAttributeNames()]
+    .filter((name) => !to.hasAttribute(name))
+    .forEach((name) => from.removeAttribute(name));
+  to.getAttributeNames().forEach((name) => {
+    if (from.getAttribute(name) !== to.getAttribute(name)) {
+      from.setAttribute(name, to.getAttribute(name)!);
+    }
+  });
+}
+
+function syncValue(from: Element, to: Element): void {
+  if (from instanceof HTMLInputElement && to instanceof HTMLInputElement) {
+    if (from.value !== to.value && document.activeElement !== from) from.value = to.value;
+  }
+}
+
+function sameKind(a: Node, b: Node): boolean {
+  if (a.nodeType !== b.nodeType) return false;
+  if (a.nodeType !== Node.ELEMENT_NODE) return true;
+
+  return (a as Element).tagName === (b as Element).tagName;
+}
+
+function morphChildren(from: Element, to: Element): void {
+  const fromKids = [...from.childNodes];
+  const toKids = [...to.childNodes];
+
+  toKids.forEach((toKid, index) => {
+    const fromKid = fromKids[index];
+
+    if (!fromKid) {
+      from.appendChild(toKid);
+
+      return;
+    }
+    if (!sameKind(fromKid, toKid)) {
+      from.replaceChild(toKid, fromKid);
+
+      return;
+    }
+    morphNode(fromKid, toKid);
+  });
+  fromKids.slice(toKids.length).forEach((extra) => from.removeChild(extra));
+}
+
+function morphNode(from: Node, to: Node): void {
+  if (from.nodeType === Node.TEXT_NODE) {
+    if (from.textContent !== to.textContent) from.textContent = to.textContent;
+
+    return;
+  }
+  if (from.nodeType !== Node.ELEMENT_NODE) return;
+  syncAttrs(from as Element, to as Element);
+  syncValue(from as Element, to as Element);
+  morphChildren(from as Element, to as Element);
+}
+
+/** Patches `root`'s children in place to match `nextChildren` (index+tag matching). */
+export function morph(root: Element, nextChildren: Node[]): void {
+  const target = document.createElement(root.tagName);
+
+  nextChildren.forEach((child) => target.appendChild(child));
+  morphChildren(root, target);
+}