janux 0.1.0

package/src/render/server.ts

@@ -0,0 +1,139 @@
+import { Fragment, type JanuxNode } from '../jsx-runtime';
+import { createInstance, type JanuxInstance } from '../runtime/instance';
+import type { EventBus } from '../runtime/bus';
+import type { ComponentDef, Ctx } from '../define/types';
+import { escapeHtml, renderAttrs, VOID_ELEMENTS } from './html';
+
+export interface IslandRecord {
+  def: ComponentDef;
+  key: string;
+  instance: JanuxInstance;
+}
+
+export interface RenderRegistry {
+  islands: IslandRecord[];
+  stores: Map<string, JanuxInstance>;
+}
+
+export interface RenderOptions {
+  ctx?: Ctx;
+  bus?: EventBus;
+  storeDefs?: Record<string, ComponentDef>;
+  initialState?: Record<string, Record<string, unknown>>;
+}
+
+interface RenderScope extends RenderOptions {
+  registry: RenderRegistry;
+  keySeq: Map<string, number>;
+}
+
+function isComponentDef(type: unknown): type is ComponentDef {
+  return typeof type === 'object' && type !== null && 'kind' in (type as any);
+}
+
+function nextKey(scope: RenderScope, def: ComponentDef, explicit?: string): string {
+  if (explicit) return explicit;
+  const seq = (scope.keySeq.get(def.name) ?? 0) + 1;
+
+  scope.keySeq.set(def.name, seq);
+
+  return seq === 1 ? 'default' : `n${seq}`;
+}
+
+async function loadSources(instance: JanuxInstance): Promise<void> {
+  const readers = Object.values(instance.sources) as { refresh: () => Promise<void> }[];
+
+  await Promise.all(readers.map((reader) => reader.refresh()));
+}
+
+function storeInstances(scope: RenderScope): Record<string, JanuxInstance> {
+  Object.entries(scope.storeDefs ?? {}).forEach(([alias, def]) => {
+    if (scope.registry.stores.has(alias)) return;
+    const initial = scope.initialState?.[`store://${def.name}`];
+
+    scope.registry.stores.set(alias, createInstance(def, { bus: scope.bus, ctx: scope.ctx, initial }));
+  });
+
+  return Object.fromEntries(scope.registry.stores);
+}
+
+async function renderIsland(def: ComponentDef, props: any, scope: RenderScope): Promise<string> {
+  const key = nextKey(scope, def, props.key ?? props.id);
+  const stores = storeInstances(scope);
+  const useStores = Object.fromEntries(
+    Object.keys(def.use ?? {}).map((alias) => [alias, stores[alias]!]),
+  );
+  const initial = scope.initialState?.[`ui://${def.name}#${key}`] ?? props.initial;
+  const instance = createInstance(def, { key, ctx: scope.ctx, bus: scope.bus, initial, stores: useStores });
+
+  await loadSources(instance);
+  scope.registry.islands.push({ def, key, instance });
+  const inner = await renderNode(def.view!(instance.bag), scope);
+
+  return `<janux-island data-jx="${escapeHtml(`${def.name}#${key}`)}">${inner}</janux-island>`;
+}
+
+async function renderElement(node: JanuxNode, scope: RenderScope): Promise<string> {
+  const tag = node.$t as string;
+  const attrs = renderAttrs(node.$p);
+
+  if (VOID_ELEMENTS.has(tag)) return `<${tag}${attrs}/>`;
+  const children =
+    typeof node.$p.dangerHTML === 'string'
+      ? node.$p.dangerHTML
+      : await renderNode(node.$p.children, scope);
+
+  return `<${tag}${attrs}>${children}</${tag}>`;
+}
+
+export async function renderNode(node: unknown, scope: RenderScope): Promise<string> {
+  if (node === null || node === undefined || typeof node === 'boolean') return '';
+  if (typeof node === 'string' || typeof node === 'number') return escapeHtml(node);
+  if (Array.isArray(node)) {
+    const parts = await Promise.all(node.map((child) => renderNode(child, scope)));
+
+    return parts.join('');
+  }
+  const jsxNode = node as JanuxNode;
+
+  if (jsxNode.$t === Fragment) return renderNode(jsxNode.$p.children, scope);
+  if (typeof jsxNode.$t === 'function') {
+    return renderNode((jsxNode.$t as any)(jsxNode.$p), scope);
+  }
+  if (isComponentDef(jsxNode.$t)) return renderIsland(jsxNode.$t, jsxNode.$p, scope);
+
+  return renderElement(jsxNode, scope);
+}
+
+export interface Snapshot {
+  uri: string;
+  state: Record<string, unknown>;
+  sources?: Record<string, { value: unknown }>;
+}
+
+export interface RenderResult {
+  html: string;
+  registry: RenderRegistry;
+  snapshots: Snapshot[];
+}
+
+/** Server-renders a page tree: static components inline, bifacial components as islands. */
+export async function renderToString(node: unknown, options: RenderOptions = {}): Promise<RenderResult> {
+  const registry: RenderRegistry = { islands: [], stores: new Map() };
+  const scope: RenderScope = { ...options, registry, keySeq: new Map() };
+  const html = await renderNode(node, scope);
+  const islandSnapshots = registry.islands
+    .filter(({ def }) => def.state || def.sources)
+    .map(({ instance }) => ({
+      uri: instance.uri,
+      state: instance.snapshot(),
+      sources: instance.sourcesSnapshot(),
+    }));
+  const storeSnapshots = [...registry.stores.values()].map((instance) => ({
+    uri: instance.uri,
+    state: instance.snapshot(),
+    sources: instance.sourcesSnapshot(),
+  }));
+
+  return { html, registry, snapshots: [...islandSnapshots, ...storeSnapshots] };
+}

package/src/runtime/bus.ts

@@ -0,0 +1,25 @@
+export type BusHandler = (payload: unknown) => void;
+
+export interface EventBus {
+  emit(event: string, payload: unknown): void;
+  on(event: string, handler: BusHandler): () => void;
+}
+
+/** Typed event bus: local component events, store events and server events share it. */
+export function createBus(): EventBus {
+  const handlers = new Map<string, Set<BusHandler>>();
+
+  return {
+    emit(event, payload) {
+      handlers.get(event)?.forEach((handler) => handler(payload));
+    },
+    on(event, handler) {
+      const set = handlers.get(event) ?? new Set();
+
+      handlers.set(event, set);
+      set.add(handler);
+
+      return () => set.delete(handler);
+    },
+  };
+}

package/src/runtime/effects.ts

@@ -0,0 +1,80 @@
+import { computed, effect as watch, untrack } from '../signals';
+import { allowMutations } from '../state/mutation-gate';
+import { parseDuration } from '../define/factories';
+import type { Cleanup, EffectDef, RunBag } from '../define/types';
+import type { PendingTracker } from './settled';
+
+interface EffectRuntime {
+  dispose: () => void;
+}
+
+function runEffectBody(def: EffectDef, bag: RunBag, tracker: PendingTracker): Cleanup {
+  const result = allowMutations(() => def.run(bag));
+
+  if (result instanceof Promise) {
+    tracker.track(result);
+
+    return undefined;
+  }
+
+  return typeof result === 'function' ? result : undefined;
+}
+
+function startOne(def: EffectDef, bag: RunBag, tracker: PendingTracker): EffectRuntime {
+  const debounceMs = def.debounce ? parseDuration(def.debounce) : 0;
+  let cleanup: Cleanup;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let releaseTimer: (() => void) | undefined;
+  let disposers: (() => void)[] = [];
+
+  const runNow = (): void => {
+    cleanup?.();
+    cleanup = untrack(() => runEffectBody(def, bag, tracker));
+  };
+
+  const schedule = (): void => {
+    if (debounceMs === 0) return runNow();
+    clearTimeout(timer);
+    releaseTimer?.();
+    releaseTimer = tracker.add();
+    timer = setTimeout(() => {
+      releaseTimer?.();
+      releaseTimer = undefined;
+      runNow();
+    }, debounceMs);
+  };
+
+  if (def.when) {
+    const watched = computed(() => def.when!(bag.state));
+    let first = true;
+    const stop = watch(() => {
+      watched.value;
+      untrack(() => (first ? runNow() : schedule()));
+      first = false;
+    });
+
+    disposers = [stop, watched.dispose];
+  } else {
+    runNow();
+  }
+
+  return {
+    dispose() {
+      clearTimeout(timer);
+      releaseTimer?.();
+      disposers.forEach((dispose) => dispose());
+      cleanup?.();
+    },
+  };
+}
+
+/** Starts all declared effects; each runs on attach and on `when` changes (debounced). */
+export function startEffects(
+  defs: Record<string, EffectDef> | undefined,
+  bag: RunBag,
+  tracker: PendingTracker,
+): () => void {
+  const running = Object.values(defs ?? {}).map((def) => startOne(def, bag, tracker));
+
+  return () => running.forEach((runtime) => runtime.dispose());
+}

package/src/runtime/instance.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, it, mock } from 'bun:test';
+import { component, intent, effect, source, store, onEvent } from '../define/factories';
+import { int, list, schema, str } from '../schema';
+import { createBus } from './bus';
+import { createInstance } from './instance';
+import type { Proposal } from './intents';
+
+const noopView = () => null;
+
+const cartDef = () =>
+  component({
+    name: 'cart',
+    state: schema({ items: list({ id: str(), qty: int().min(1) }), coupon: str().nullable() }),
+    derived: { count: (s: any) => s.items.reduce((acc: number, i: any) => acc + i.qty, 0) },
+    emits: { 'cart.cleared': schema({}) },
+    intents: {
+      addItem: intent({
+        input: schema({ id: str(), qty: int().min(1).default(1) }),
+        run: ({ state, input }) => state.items.push(input),
+      }),
+      clear: intent({
+        guard: 'confirm',
+        run: ({ state, emit }) => {
+          state.items = [];
+          emit('cart.cleared', {});
+        },
+      }),
+      hidden: intent({ guard: 'forbidden', run: () => 'secret' }),
+    },
+    view: noopView,
+  });
+
+describe('instance: state, derived, intents', () => {
+  it('initializes from schema defaults and exposes uri', () => {
+    const cart = createInstance(cartDef());
+
+    expect(cart.uri).toBe('ui://cart');
+    expect(cart.snapshot()).toEqual({ items: [], coupon: null });
+  });
+
+  it('runs intents, mutates state and updates derived', async () => {
+    const cart = createInstance(cartDef(), { key: 'main' });
+
+    await cart.intents.addItem!({ id: 'a', qty: 2 });
+    await cart.intents.addItem!({ id: 'b' });
+    expect(cart.uri).toBe('ui://cart#main');
+    expect(cart.snapshot().items).toHaveLength(2);
+    expect(cart.derived.count).toBe(3);
+  });
+
+  it('validates intent input against its schema', async () => {
+    const cart = createInstance(cartDef());
+
+    expect(cart.intents.addItem!({ id: 'a', qty: 0 })).rejects.toThrow(/below min 1/);
+  });
+
+  it('records audit entries for every invocation', async () => {
+    const entries: any[] = [];
+    const cart = createInstance(cartDef(), { onAudit: (entry) => entries.push(entry) });
+
+    await cart.intents.addItem!({ id: 'a' });
+    expect(entries).toEqual([
+      expect.objectContaining({ tool: 'cart.addItem', origin: 'human', guard: 'auto', ok: true }),
+    ]);
+  });
+});
+
+describe('instance: guards', () => {
+  it('agent + confirm returns a proposal; executing it applies the change', async () => {
+    let proposal: Proposal | undefined;
+    const cart = createInstance(cartDef(), { onProposal: (p) => (proposal = p) });
+
+    const result: any = await cart.intents.clear!({}, { origin: 'agent' });
+
+    expect(result.status).toBe('proposal');
+    expect(cart.snapshot().items).toEqual([]);
+    await proposal!.execute();
+    expect(cart.snapshot().items).toEqual([]);
+  });
+
+  it('human origin runs confirm intents directly', async () => {
+    const cart = createInstance(cartDef());
+
+    await cart.intents.addItem!({ id: 'a' });
+    await cart.intents.clear!({});
+    expect(cart.snapshot().items).toEqual([]);
+  });
+
+  it('agent cannot invoke forbidden intents', () => {
+    const cart = createInstance(cartDef());
+
+    expect(cart.intents.hidden!({}, { origin: 'agent' })).rejects.toThrow(/not available/);
+  });
+});
+
+describe('instance: sources, effects, settled', () => {
+  const catalogDef = (query: () => unknown) =>
+    component({
+      name: 'shop',
+      state: schema({ picks: int() }),
+      sources: { catalog: source({ query, refresh: onEvent('inventory.changed') }) },
+      intents: {
+        pick: intent({
+          ready: ({ sources }) => !sources.catalog!.pending,
+          run: ({ state }) => (state.picks += 1),
+        }),
+      },
+      view: noopView,
+    });
+
+  it('loads sources async, gates ready intents, resolves settled()', async () => {
+    const shop = createInstance(catalogDef(async () => ['p1']));
+
+    await shop.attach();
+    expect(shop.intents.pick!({})).rejects.toThrow(/not ready/);
+    await shop.settled();
+    expect(shop.sources.catalog.value).toEqual(['p1']);
+    await shop.intents.pick!({});
+    expect(shop.snapshot().picks).toBe(1);
+    await shop.dispose();
+  });
+
+  it('re-queries sources when a refresh event fires', async () => {
+    const bus = createBus();
+    const query = mock(async () => 'data');
+    const shop = createInstance(catalogDef(query), { bus });
+
+    await shop.attach();
+    await shop.settled();
+    bus.emit('inventory.changed', {});
+    await shop.settled();
+    expect(query).toHaveBeenCalledTimes(2);
+    await shop.dispose();
+  });
+
+  it('runs effects on attach, on change (debounced) and cleans up', async () => {
+    const runs = mock(() => {});
+    const cleanups = mock(() => {});
+    const def = component({
+      name: 'fx',
+      state: schema({ n: int() }),
+      effects: {
+        track: effect({
+          when: (s: any) => s.n,
+          debounce: '10ms',
+          run: () => {
+            runs();
+
+            return cleanups;
+          },
+        }),
+      },
+      intents: { bump: intent({ run: ({ state }) => (state.n += 1) }) },
+      view: noopView,
+    });
+    const fx = createInstance(def);
+
+    await fx.attach();
+    expect(runs).toHaveBeenCalledTimes(1);
+    await fx.intents.bump!({});
+    await fx.settled();
+    expect(runs).toHaveBeenCalledTimes(2);
+    expect(cleanups).toHaveBeenCalledTimes(1);
+    await fx.dispose();
+    expect(cleanups).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('instance: events and stores', () => {
+  it('emits validated events across instances on a shared bus', async () => {
+    const bus = createBus();
+    const cart = createInstance(cartDef(), { bus });
+    const listener = store({
+      name: 'analytics',
+      state: schema({ clears: int() }),
+      on: { 'cart.cleared': ({ state }) => (state.clears += 1) },
+    });
+    const analytics = createInstance(listener, { bus });
+
+    await cart.intents.clear!({});
+    expect(analytics.snapshot().clears).toBe(1);
+    expect(analytics.uri).toBe('store://analytics');
+  });
+
+  it('consumer intents reach store intents through use', async () => {
+    const session = createInstance(
+      store({
+        name: 'session',
+        state: schema({ locale: str().default('en') }),
+        intents: {
+          setLocale: intent({
+            input: schema({ locale: str() }),
+            run: ({ state, input }) => (state.locale = input.locale),
+          }),
+        },
+      }),
+    );
+    const header = createInstance(
+      component({
+        name: 'header',
+        intents: {
+          toSpanish: intent({ run: ({ use }) => use.session!.intents.setLocale!({ locale: 'es' }) }),
+        },
+        view: noopView,
+      }),
+      { stores: { session } },
+    );
+
+    await header.intents.toSpanish!({});
+    expect(session.snapshot().locale).toBe('es');
+  });
+
+  it('exposes an agent resource projection', async () => {
+    const cart = createInstance(cartDef());
+
+    await cart.intents.addItem!({ id: 'a', qty: 2 });
+    const resource: any = cart.resource();
+
+    expect(resource.uri).toBe('ui://cart');
+    expect(resource.state.items).toEqual([{ id: 'a', qty: 2 }]);
+    expect(resource.derived.count).toBe(2);
+    expect(resource.sync).toBe('idle');
+  });
+});

package/src/runtime/instance.ts

@@ -0,0 +1,171 @@
+import { buildDefault, toJsonSchema, validate } from '../schema';
+import { computed, untrack, type ReadonlySig } from '../signals';
+import { createReactiveState } from '../state/reactive-state';
+import { allowMutations } from '../state/mutation-gate';
+import type { ComponentDef, Ctx, Origin, RunBag, StoreHandle } from '../define/types';
+import { createBus, type EventBus } from './bus';
+import { createPendingTracker } from './settled';
+import { createSources } from './sources';
+import { startEffects } from './effects';
+import { invokeIntent, type AuditEntry, type Proposal } from './intents';
+
+export interface InstanceOptions {
+  key?: string;
+  initial?: Record<string, unknown>;
+  initialSources?: Record<string, { value: unknown }>;
+  ctx?: Ctx;
+  bus?: EventBus;
+  stores?: Record<string, JanuxInstance>;
+  onAudit?: (entry: AuditEntry) => void;
+  onProposal?: (proposal: Proposal) => void;
+}
+
+export interface JanuxInstance {
+  def: ComponentDef;
+  uri: string;
+  state: any;
+  derived: Record<string, unknown>;
+  sources: Record<string, any>;
+  intents: Record<string, (input?: unknown, opts?: { origin?: Origin }) => Promise<unknown>>;
+  emit: (event: string, payload: unknown) => void;
+  bag: RunBag;
+  snapshot(): Record<string, unknown>;
+  sourcesSnapshot(): Record<string, { value: unknown }>;
+  resource(): Record<string, unknown>;
+  settled(): Promise<void>;
+  attach(): Promise<void>;
+  dispose(): Promise<void>;
+  handle(): StoreHandle;
+}
+
+function derivedReaders(def: ComponentDef, proxy: any) {
+  const computeds = new Map<string, ReadonlySig<unknown>>(
+    Object.entries(def.derived ?? {}).map(([name, fn]) => [name, computed(() => fn(proxy))]),
+  );
+  const readers: Record<string, unknown> = {};
+
+  computeds.forEach((sig, name) => {
+    Object.defineProperty(readers, name, { get: () => sig.value, enumerable: true });
+  });
+
+  return { readers, dispose: () => computeds.forEach((sig) => sig.dispose()) };
+}
+
+function storeHandles(stores: Record<string, JanuxInstance>): Record<string, StoreHandle> {
+  return Object.fromEntries(
+    Object.entries(stores).map(([alias, instance]) => [alias, instance.handle()]),
+  );
+}
+
+function makeEmit(def: ComponentDef, bus: EventBus) {
+  return (event: string, payload: unknown): void => {
+    const schema = def.emits?.[event];
+
+    if (!schema) throw new Error(`Janux: "${def.name}" does not declare event "${event}"`);
+    const result = validate(schema, payload ?? {});
+
+    if (!result.ok) throw new Error(`Janux: invalid payload for "${event}"`);
+    bus.emit(event, result.value);
+  };
+}
+
+function evaluateDerived(readers: Record<string, unknown>): Record<string, unknown> {
+  return untrack(() => JSON.parse(JSON.stringify({ ...readers })));
+}
+
+/** Creates a live component/store instance. Call `attach()` to start sources, effects and lifecycle. */
+export function createInstance(def: ComponentDef, options: InstanceOptions = {}): JanuxInstance {
+  const ctx = options.ctx ?? {};
+  const bus = options.bus ?? createBus();
+  const tracker = createPendingTracker();
+  const initial = options.initial ?? (def.state ? (buildDefault(def.state) as any) : {});
+  const state = createReactiveState(initial as Record<string, unknown>);
+  const sourcesRuntime = createSources(def.sources, ctx, bus, tracker, options.initialSources);
+  const { readers: derived, dispose: disposeDerived } = derivedReaders(def, state.proxy);
+  const emit = makeEmit(def, bus);
+  const use = storeHandles(options.stores ?? {});
+  const scheme = def.kind === 'store' ? 'store' : 'ui';
+  const uri = `${scheme}://${def.name}${options.key ? `#${options.key}` : ''}`;
+
+  const intents: JanuxInstance['intents'] = {};
+  const bag: RunBag = {
+    state: state.proxy,
+    derived,
+    sources: sourcesRuntime.readers,
+    intents,
+    use,
+    emit,
+    ctx,
+  };
+  const hooks = {
+    onAudit: options.onAudit,
+    onProposal: options.onProposal,
+    trackPending: tracker.track,
+  };
+
+  Object.entries(def.intents ?? {}).forEach(([name, intentDef]) => {
+    const invoke = (input?: unknown, opts?: { origin?: Origin }) =>
+      invokeIntent(def.name, name, intentDef, bag, input, opts?.origin ?? 'human', hooks);
+
+    (invoke as any).$intent = { component: def.name, key: options.key, name };
+    intents[name] = invoke;
+  });
+
+  let stopEffects: (() => void) | undefined;
+  const busUnsubs = Object.entries(def.on ?? {}).map(([event, handler]) =>
+    bus.on(event, (payload) => allowMutations(() => handler({ ...bag, event: payload }))),
+  );
+
+  return {
+    def,
+    uri,
+    state: state.proxy,
+    derived,
+    sources: sourcesRuntime.readers,
+    intents,
+    emit,
+    bag,
+    snapshot: () => state.snapshot(),
+    sourcesSnapshot() {
+      return untrack(() =>
+        Object.fromEntries(
+          Object.entries(sourcesRuntime.readers)
+            .filter(([, reader]) => !reader.pending && reader.error === null)
+            .map(([name, reader]) => [name, { value: reader.value }]),
+        ),
+      );
+    },
+    settled: () => tracker.settled(),
+    resource() {
+      return {
+        uri,
+        description: def.description,
+        schema: def.state ? toJsonSchema(def.state) : undefined,
+        state: state.snapshot(),
+        derived: evaluateDerived(derived),
+        sync: tracker.count > 0 ? 'pending' : 'idle',
+      };
+    },
+    async attach() {
+      sourcesRuntime.start();
+      stopEffects = startEffects(def.effects, bag, tracker);
+      await allowMutations(() => def.lifecycle?.attach?.(bag));
+    },
+    async dispose() {
+      stopEffects?.();
+      sourcesRuntime.dispose();
+      disposeDerived();
+      busUnsubs.forEach((unsub) => unsub());
+      await allowMutations(() => def.lifecycle?.detach?.(bag));
+    },
+    handle(): StoreHandle {
+      return { state: state.proxy, derived, intents: bindHumanIntents(intents) };
+    },
+  };
+}
+
+function bindHumanIntents(intents: JanuxInstance['intents']) {
+  return Object.fromEntries(
+    Object.entries(intents).map(([name, invoke]) => [name, (input?: unknown) => invoke(input)]),
+  );
+}