janux 0.1.0

package/src/client/mount.ts

@@ -0,0 +1,87 @@
+import { effect as watch } from '../signals';
+import { createInstance, type JanuxInstance } from '../runtime/instance';
+import type { ComponentDef } from '../define/types';
+import type { EventBus } from '../runtime/bus';
+import { toDomNodes } from './dom';
+import { morph } from './morph';
+import { resolveDef, type ClientRegistry } from './registry';
+
+export interface MountContext {
+  registry: ClientRegistry;
+  bus: EventBus;
+  ctx: Record<string, unknown>;
+  inflight: Set<Promise<unknown>>;
+  onProposal: (proposal: unknown) => void;
+  onAudit?: (entry: unknown) => void;
+}
+
+async function ensureStores(def: ComponentDef, mount: MountContext): Promise<Record<string, JanuxInstance>> {
+  const entries = await Promise.all(
+    Object.entries(def.use ?? {}).map(async ([alias, storeDef]) => {
+      return [alias, await ensureStore(storeDef, mount)] as const;
+    }),
+  );
+
+  return Object.fromEntries(entries);
+}
+
+export async function ensureStore(storeDef: ComponentDef, mount: MountContext): Promise<JanuxInstance> {
+  const { registry } = mount;
+  const existing = registry.stores.get(storeDef.name);
+
+  if (existing) return existing;
+  const snap = registry.snapshots.get(`store://${storeDef.name}`) as any;
+  const instance = createInstance(storeDef, {
+    bus: mount.bus,
+    ctx: mount.ctx,
+    initial: snap?.state,
+    initialSources: snap?.sources,
+    onProposal: mount.onProposal as any,
+    onAudit: mount.onAudit as any,
+  });
+
+  registry.stores.set(storeDef.name, instance);
+  await instance.attach();
+
+  return instance;
+}
+
+function startRenderLoop(instance: JanuxInstance, root: Element): () => void {
+  return watch(() => {
+    morph(root, toDomNodes(instance.def.view!(instance.bag)));
+  });
+}
+
+/** Resumes one island: instance from its SSR snapshot, reactive render loop, no replay. */
+export async function mountIsland(id: string, root: Element, mount: MountContext): Promise<JanuxInstance> {
+  const { registry } = mount;
+  const mounted = registry.mounted.get(id);
+
+  if (mounted) return mounted;
+  const [name, key = 'default'] = id.split('#');
+  const def = await resolveDef(registry, name!);
+  const snap = (registry.snapshots.get(`ui://${id}`) ?? registry.snapshots.get(`ui://${name}`)) as any;
+  const instance = createInstance(def, {
+    key,
+    bus: mount.bus,
+    ctx: mount.ctx,
+    initial: snap?.state,
+    initialSources: snap?.sources,
+    stores: await ensureStores(def, mount),
+    onProposal: mount.onProposal as any,
+    onAudit: mount.onAudit as any,
+  });
+
+  registry.mounted.set(id, instance);
+  const stopRender = startRenderLoop(instance, root);
+  const dispose = instance.dispose.bind(instance);
+
+  instance.dispose = async () => {
+    stopRender();
+    registry.mounted.delete(id);
+    await dispose();
+  };
+  await instance.attach();
+
+  return instance;
+}

package/src/client/registry.ts

@@ -0,0 +1,42 @@
+import type { ComponentDef } from '../define/types';
+import type { JanuxInstance } from '../runtime/instance';
+
+export type IslandLoader = () => Promise<unknown>;
+
+export interface ClientRegistry {
+  defs: Map<string, ComponentDef>;
+  loaders: Map<string, IslandLoader>;
+  mounted: Map<string, JanuxInstance>;
+  stores: Map<string, JanuxInstance>;
+  snapshots: Map<string, Record<string, unknown>>;
+}
+
+export function createClientRegistry(): ClientRegistry {
+  return {
+    defs: new Map(),
+    loaders: new Map(),
+    mounted: new Map(),
+    stores: new Map(),
+    snapshots: new Map(),
+  };
+}
+
+/** Island/store modules call this on import so boot can resolve defs by name. */
+export function registerDef(registry: ClientRegistry, def: ComponentDef): void {
+  registry.defs.set(def.name, def);
+}
+
+export async function resolveDef(registry: ClientRegistry, name: string): Promise<ComponentDef> {
+  const existing = registry.defs.get(name);
+
+  if (existing) return existing;
+  const loader = registry.loaders.get(name);
+
+  if (!loader) throw new Error(`Janux: unknown island "${name}" (no loader registered)`);
+  await loader();
+  const loaded = registry.defs.get(name);
+
+  if (!loaded) throw new Error(`Janux: island module for "${name}" did not register its def`);
+
+  return loaded;
+}

package/src/define/factories.ts

@@ -0,0 +1,78 @@
+import type {
+  ComponentDef,
+  EffectDef,
+  IntentDef,
+  RefreshPolicy,
+  SourceDef,
+} from './types';
+
+type ComponentInput = Omit<ComponentDef, 'kind'>;
+type StoreInput = Omit<ComponentDef, 'kind' | 'view'>;
+
+function assertName(name: unknown, kind: string): void {
+  if (typeof name === 'string' && /^[a-z][a-z0-9-]*$/.test(name)) return;
+
+  throw new Error(`Janux: ${kind} needs a kebab-case "name", got ${JSON.stringify(name)}`);
+}
+
+/** Defines a bifacial component: view for humans, resource+tools for agents. */
+export function component(def: ComponentInput): ComponentDef {
+  assertName(def.name, 'component()');
+  if (typeof def.view !== 'function') {
+    throw new Error(`Janux: component "${def.name}" requires a view`);
+  }
+
+  return Object.freeze({ ...def, kind: 'component' as const });
+}
+
+/** Defines a shared store: a bifacial component without a view. */
+export function store(def: StoreInput): ComponentDef {
+  assertName(def.name, 'store()');
+
+  return Object.freeze({ ...def, kind: 'store' as const, scope: def.scope ?? 'app' });
+}
+
+export function intent(def: IntentDef): IntentDef {
+  if (typeof def.run !== 'function') throw new Error('Janux: intent() requires run()');
+
+  return def;
+}
+
+export function effect(def: EffectDef): EffectDef {
+  if (typeof def.run !== 'function') throw new Error('Janux: effect() requires run()');
+
+  return def;
+}
+
+export function source(def: SourceDef): SourceDef {
+  if (typeof def.query !== 'function') throw new Error('Janux: source() requires query()');
+
+  return def;
+}
+
+/** Refresh policy builder: `every('5m').orOn('inventory.changed')`. */
+export function every(interval: string): RefreshPolicy & { orOn: (event: string) => RefreshPolicy } {
+  const policy = { everyMs: parseDuration(interval), events: [] as string[] };
+
+  return {
+    ...policy,
+    orOn(event: string) {
+      return { ...policy, events: [...policy.events, event] };
+    },
+  };
+}
+
+/** Event-only refresh policy: `on('inventory.changed')`. */
+export function onEvent(event: string): RefreshPolicy {
+  return { events: [event] };
+}
+
+const DURATION_UNITS: Record<string, number> = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 };
+
+export function parseDuration(input: string): number {
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/.exec(input);
+
+  if (!match) throw new Error(`Janux: invalid duration "${input}" (use e.g. 300ms, 2s, 5m, 1h)`);
+
+  return Number(match[1]) * DURATION_UNITS[match[2]!]!;
+}

package/src/define/types.ts

@@ -0,0 +1,83 @@
+import type { JxType } from '../schema';
+
+export type GuardValue = 'auto' | 'confirm' | 'forbidden';
+export type Guard = GuardValue | ((bag: { ctx: Ctx }) => GuardValue);
+export type Ctx = Record<string, unknown>;
+export type Origin = 'human' | 'agent';
+export type Cleanup = (() => void) | undefined;
+
+export interface RunBag {
+  state: any;
+  derived: Record<string, unknown>;
+  sources: Record<string, SourceReader>;
+  intents: Record<string, (input?: unknown) => Promise<unknown>>;
+  use: Record<string, StoreHandle>;
+  emit: (event: string, payload: unknown) => void;
+  ctx: Ctx;
+  input?: any;
+  event?: any;
+  signal?: AbortSignal;
+}
+
+export interface SourceReader {
+  readonly value: any;
+  readonly pending: boolean;
+  readonly error: unknown;
+}
+
+export interface StoreHandle {
+  state: any;
+  derived: Record<string, unknown>;
+  intents: Record<string, (input?: unknown) => Promise<unknown>>;
+}
+
+export interface IntentDef {
+  description?: string;
+  input?: JxType;
+  guard?: Guard;
+  server?: boolean;
+  prefetch?: 'eager' | 'visible' | 'idle';
+  ready?: (bag: RunBag) => boolean;
+  run: (bag: RunBag) => unknown;
+}
+
+export interface EffectDef {
+  description?: string;
+  when?: (state: any) => unknown;
+  debounce?: string;
+  run: (bag: RunBag) => Cleanup | void | Promise<void>;
+}
+
+export interface RefreshPolicy {
+  everyMs?: number;
+  events: string[];
+}
+
+export interface SourceDef {
+  description?: string;
+  query: (bag: { ctx: Ctx }) => unknown;
+  refresh?: RefreshPolicy;
+}
+
+export interface LifecycleDef {
+  attach?: (bag: RunBag) => void | Promise<void>;
+  detach?: (bag: RunBag) => void | Promise<void>;
+}
+
+export interface ComponentDef {
+  kind: 'component' | 'store';
+  name: string;
+  description?: string;
+  state?: JxType;
+  derived?: Record<string, (state: any) => unknown>;
+  sources?: Record<string, SourceDef>;
+  effects?: Record<string, EffectDef>;
+  intents?: Record<string, IntentDef>;
+  emits?: Record<string, JxType>;
+  on?: Record<string, (bag: RunBag) => void>;
+  lifecycle?: LifecycleDef;
+  use?: Record<string, ComponentDef>;
+  view?: (bag: RunBag) => unknown;
+  scope?: 'app' | 'route';
+  persist?: 'local' | 'none';
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+export {
+  component,
+  store,
+  intent,
+  effect,
+  source,
+  every,
+  onEvent,
+  parseDuration,
+} from './define/factories';
+export type {
+  ComponentDef,
+  IntentDef,
+  EffectDef,
+  SourceDef,
+  Ctx,
+  Guard,
+  GuardValue,
+  Origin,
+  RunBag,
+  StoreHandle,
+} from './define/types';
+export { renderToString, type RenderResult } from './render/server';
+export { buildManifest, type Manifest, type ManifestEntry } from './manifest';
+export {
+  schema,
+  str,
+  int,
+  num,
+  bool,
+  money,
+  enums,
+  list,
+  obj,
+  JxType,
+  validate,
+  buildDefault,
+  toJsonSchema,
+} from './schema';
+export { signal, computed, effect as watch, batch, untrack } from './signals';
+export { createInstance, type JanuxInstance, type InstanceOptions } from './runtime/instance';
+export { createBus, type EventBus } from './runtime/bus';
+export { JanuxIntentError, type AuditEntry, type Proposal } from './runtime/intents';
+export { Fragment, jsx, jsxs, type JanuxNode } from './jsx-runtime';

package/src/jsx-dev-runtime.ts

@@ -0,0 +1 @@
+export { Fragment, jsx, jsxs, jsxDEV, type JanuxNode, type JanuxType } from './jsx-runtime';

package/src/jsx-runtime.ts

@@ -0,0 +1,35 @@
+import type { ComponentDef } from './define/types';
+
+export type JanuxType = string | ((props: any) => unknown) | ComponentDef | symbol;
+
+export interface JanuxNode {
+  $t: JanuxType;
+  $p: Record<string, unknown>;
+  $k?: string | number;
+}
+
+export const Fragment = Symbol.for('janux.fragment');
+
+export function jsx(type: JanuxType, props: Record<string, unknown> | null, key?: string | number): JanuxNode {
+  return { $t: type, $p: props ?? {}, $k: key };
+}
+
+export const jsxs = jsx;
+
+export function jsxDEV(
+  type: JanuxType,
+  props: Record<string, unknown> | null,
+  key?: string | number,
+): JanuxNode {
+  return jsx(type, props, key);
+}
+
+export declare namespace JSX {
+  type Element = JanuxNode;
+  interface IntrinsicElements {
+    [element: string]: Record<string, unknown>;
+  }
+  interface ElementChildrenAttribute {
+    children: unknown;
+  }
+}

package/src/manifest/index.ts

@@ -0,0 +1,107 @@
+import { toJsonSchema } from '../schema';
+import type { ComponentDef, Ctx } from '../define/types';
+import { resolveGuard } from '../runtime/intents';
+import type { JanuxInstance } from '../runtime/instance';
+
+export interface ManifestTool {
+  name: string;
+  description?: string;
+  guard: string;
+  input?: Record<string, unknown>;
+  ready?: boolean;
+  server?: boolean;
+  prefetch?: string;
+}
+
+export interface ManifestResource {
+  uri: string;
+  description?: string;
+  schema?: Record<string, unknown>;
+  readers?: string[];
+  opaque?: boolean;
+}
+
+export interface Manifest {
+  janux: string;
+  resources: ManifestResource[];
+  tools: ManifestTool[];
+  events: string[];
+}
+
+function uriFor(def: ComponentDef, key?: string): string {
+  const scheme = def.kind === 'store' ? 'store' : 'ui';
+
+  return `${scheme}://${def.name}${key && key !== 'default' ? `#${key}` : ''}`;
+}
+
+function toolsFor(def: ComponentDef, ctx: Ctx, instance?: JanuxInstance): ManifestTool[] {
+  return Object.entries(def.intents ?? {})
+    .filter(([, intentDef]) => resolveGuard(intentDef, ctx) !== 'forbidden')
+    .map(([name, intentDef]) => ({
+      name: `${def.name}.${name}`,
+      description: intentDef.description,
+      guard: resolveGuard(intentDef, ctx),
+      input: intentDef.input ? toJsonSchema(intentDef.input) : undefined,
+      ready: instance && intentDef.ready ? safeReady(intentDef, instance) : true,
+      server: intentDef.server || undefined,
+      prefetch: intentDef.prefetch,
+    }));
+}
+
+function safeReady(intentDef: NonNullable<ComponentDef['intents']>[string], instance: JanuxInstance): boolean {
+  try {
+    return intentDef.ready!(instance.bag) === true;
+  } catch {
+    return false;
+  }
+}
+
+function resourceFor(def: ComponentDef, key?: string, readers?: string[]): ManifestResource[] {
+  if (!def.state) return [];
+
+  return [
+    {
+      uri: uriFor(def, key),
+      description: def.description,
+      schema: toJsonSchema(def.state),
+      readers,
+    },
+  ];
+}
+
+export interface ManifestEntry {
+  def: ComponentDef;
+  key?: string;
+  instance?: JanuxInstance;
+}
+
+/**
+ * Builds the agent-facing manifest from mounted components and stores.
+ * The mounted component tree IS the MCP tree (RFC §5.1).
+ */
+export function buildManifest(entries: ManifestEntry[], ctx: Ctx = {}): Manifest {
+  const readersByStore = storeReaders(entries);
+  const resources = entries.flatMap(({ def, key }) =>
+    resourceFor(def, key, def.kind === 'store' ? readersByStore.get(def.name) : undefined),
+  );
+  const tools = entries.flatMap(({ def, instance }) => toolsFor(def, ctx, instance));
+  const events = [...new Set(entries.flatMap(({ def }) => Object.keys(def.emits ?? {})))];
+
+  return { janux: '0.1', resources, tools, events };
+}
+
+function storeReaders(entries: ManifestEntry[]): Map<string, string[]> {
+  const readers = new Map<string, string[]>();
+
+  entries
+    .filter(({ def }) => def.kind === 'component')
+    .forEach(({ def, key }) => {
+      Object.values(def.use ?? {}).forEach((storeDef) => {
+        const list = readers.get(storeDef.name) ?? [];
+
+        readers.set(storeDef.name, [...list, uriFor(def, key)]);
+      });
+    });
+
+  return readers;
+}

package/src/render/html.ts

@@ -0,0 +1,68 @@
+export const VOID_ELEMENTS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'source',
+  'track',
+  'wbr',
+]);
+
+const ESCAPES: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+};
+
+export function escapeHtml(value: unknown): string {
+  return String(value).replace(/[&<>"]/g, (char) => ESCAPES[char]!);
+}
+
+function intentMarker(value: unknown): string | undefined {
+  const meta = (value as any)?.$intent;
+
+  if (!meta) return undefined;
+  const key = meta.key ? `#${meta.key}` : '';
+
+  return `${meta.component}${key}:${meta.name}`;
+}
+
+function attrFor(name: string, value: unknown): string {
+  if (value === false || value === null || value === undefined) return '';
+  if (value === true) return ` ${name}`;
+
+  return ` ${name}="${escapeHtml(value)}"`;
+}
+
+const VALID_ATTR_NAME = /^[a-zA-Z][\w-]*$/;
+
+/** Maps a JSX prop to an HTML attribute pair; `on`/`intent` become data markers for delegation. */
+function propToAttr(name: string, value: unknown): [string, unknown] | undefined {
+  if (name === 'children' || name === 'key' || name === 'dangerHTML') return undefined;
+  if (name === 'on') return ['data-jxa', intentMarker(value)];
+  if (name === 'intent') return ['data-jxform', intentMarker(value)];
+  if (name === 'class' || name === 'className') return ['class', value];
+  if (typeof value === 'function') return undefined;
+  if (!VALID_ATTR_NAME.test(name)) return undefined;
+
+  return [name, value];
+}
+
+export function attrEntries(props: Record<string, unknown>): [string, unknown][] {
+  return Object.entries(props)
+    .map(([name, value]) => propToAttr(name, value))
+    .filter((entry): entry is [string, unknown] => entry !== undefined);
+}
+
+export function renderAttrs(props: Record<string, unknown>): string {
+  return attrEntries(props)
+    .map(([name, value]) => attrFor(name, value))
+    .join('');
+}

package/src/render/server.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'bun:test';
+import { component, intent, source, store } from '../define/factories';
+import { jsx, Fragment } from '../jsx-runtime';
+import { int, list, schema, str } from '../schema';
+import { buildManifest } from '../manifest';
+import { renderToString } from './server';
+
+function PriceTag({ amount }: { amount: number }) {
+  return jsx('span', { class: 'price', children: `${amount}¢` });
+}
+
+const cart = component({
+  name: 'cart',
+  description: 'Shopping cart',
+  state: schema({ items: list({ id: str(), qty: int() }) }),
+  derived: { count: (s: any) => s.items.length },
+  sources: { catalog: source({ query: async () => ['p1', 'p2'] }) },
+  emits: { 'cart.cleared': schema({}) },
+  intents: {
+    addItem: intent({
+      description: 'Add product',
+      input: schema({ id: str() }),
+      run: ({ state, input }) => state.items.push({ id: input.id, qty: 1 }),
+    }),
+    checkout: intent({ guard: 'confirm', run: () => {} }),
+    admin: intent({ guard: 'forbidden', run: () => {} }),
+  },
+  view: ({ state, sources, intents }: any) =>
+    jsx('section', {
+      children: [
+        jsx('p', { children: `${state.items.length} items / ${sources.catalog.value.length} products` }),
+        jsx('button', { on: intents.checkout, children: 'Pay' }),
+      ],
+    }),
+});
+
+describe('renderToString', () => {
+  it('renders static components with zero islands', async () => {
+    const page = jsx('main', { children: jsx(PriceTag as any, { amount: 100 }) });
+    const result = await renderToString(page);
+
+    expect(result.html).toBe('<main><span class="price">100¢</span></main>');
+    expect(result.registry.islands).toHaveLength(0);
+    expect(result.snapshots).toHaveLength(0);
+  });
+
+  it('escapes text and attribute content', async () => {
+    const page = jsx('p', { title: '"><script>', children: '<script>alert(1)</script>' });
+    const result = await renderToString(page);
+
+    expect(result.html).toBe(
+      '<p title="&quot;&gt;&lt;script&gt;">&lt;script&gt;alert(1)&lt;/script&gt;</p>',
+    );
+  });
+
+  it('renders islands with loaded sources, markers and snapshots', async () => {
+    const page = jsx(Fragment, { children: [jsx('h1', { children: 'Shop' }), jsx(cart as any, {})] });
+    const result = await renderToString(page, { initialState: { 'ui://cart#default': { items: [{ id: 'a', qty: 1 }] } } });
+
+    expect(result.html).toContain('<janux-island data-jx="cart#default">');
+    expect(result.html).toContain('1 items / 2 products');
+    expect(result.html).toContain('data-jxa="cart#default:checkout"');
+    expect(result.snapshots).toEqual([
+      {
+        uri: 'ui://cart#default',
+        state: { items: [{ id: 'a', qty: 1 }] },
+        sources: { catalog: { value: ['p1', 'p2'] } },
+      },
+    ]);
+  });
+
+  it('renders void elements self-closed and skips function props', async () => {
+    const result = await renderToString(jsx('input', { value: 'x', onInput: () => {} }));
+
+    expect(result.html).toBe('<input value="x"/>');
+  });
+
+  it('escapes attacker-controlled island keys (XSS regression)', async () => {
+    const evil = 'x"><img src=x onerror=alert(1)>';
+    const result = await renderToString(jsx(cart as any, { key: evil }));
+
+    expect(result.html).not.toContain('"><img');
+    expect(result.html).toContain('data-jx="cart#x&quot;&gt;&lt;img');
+  });
+
+  it('drops invalid attribute names (attribute injection regression)', async () => {
+    const result = await renderToString(jsx('div', { 'onmouseover=alert(1) x': 'y', title: 'ok' }));
+
+    expect(result.html).toBe('<div title="ok"></div>');
+  });
+});
+
+describe('buildManifest', () => {
+  const session = store({
+    name: 'session',
+    state: schema({ locale: str().default('en') }),
+    intents: { setLocale: intent({ input: schema({ locale: str() }), run: () => {} }) },
+  });
+  const header = component({ name: 'header', use: { session }, view: () => null });
+
+  it('projects mounted components as resources, tools and events', () => {
+    const manifest = buildManifest([{ def: cart, key: 'default' }, { def: session }, { def: header }]);
+
+    expect(manifest.resources.map((r) => r.uri)).toEqual(['ui://cart', 'store://session']);
+    expect(manifest.tools.map((t) => `${t.name}:${t.guard}`)).toEqual([
+      'cart.addItem:auto',
+      'cart.checkout:confirm',
+      'session.setLocale:auto',
+    ]);
+    expect(manifest.events).toEqual(['cart.cleared']);
+  });
+
+  it('hides forbidden tools and lists store readers', () => {
+    const manifest = buildManifest([{ def: cart }, { def: session }, { def: header }]);
+    const sessionResource = manifest.resources.find((r) => r.uri === 'store://session');
+
+    expect(manifest.tools.find((t) => t.name === 'cart.admin')).toBeUndefined();
+    expect(sessionResource!.readers).toEqual(['ui://header']);
+  });
+
+  it('serializes tool input schemas as JSON Schema', () => {
+    const manifest = buildManifest([{ def: cart }]);
+    const addItem = manifest.tools.find((t) => t.name === 'cart.addItem')!;
+
+    expect(addItem.input).toEqual({
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+      additionalProperties: false,
+    });
+  });
+});