janux 0.1.0 → 0.2.1

package/src/client/webmcp.ts

@@ -0,0 +1,169 @@
+import type { Manifest, ManifestTool } from '../manifest';
+import type { JanuxBridge } from './bridge';
+import { createNavigateTool } from './navigate-tool';
+
+export interface WebMCPToolDescriptor {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+  execute: (input: unknown) => unknown;
+}
+
+export interface ModelContext {
+  registerTool(tool: WebMCPToolDescriptor, options?: { signal?: AbortSignal }): unknown;
+  provideContext?(context: { tools: WebMCPToolDescriptor[] }): unknown;
+}
+
+export interface ModelContextPolyfill extends ModelContext {
+  polyfilled: true;
+  /** Polyfill-only: enumerate registered tools (the real API keeps them internal). */
+  listTools(): WebMCPToolDescriptor[];
+  /** Polyfill-only: invoke a registered tool by name, gui-agent style. */
+  callTool(name: string, input?: unknown): Promise<unknown>;
+}
+
+export interface WebMCPHandle {
+  /** Re-reads the manifest and re-registers every tool. Runs automatically on SPA navigation. */
+  sync(): Promise<void>;
+  dispose(): void;
+}
+
+/**
+ * Spec-shaped stand-in for `document.modelContext` (WebMCP). Lets the same
+ * registration path — and any in-page agent or test — work in browsers that
+ * don't ship the API yet. Registrations honor AbortSignal like the real thing.
+ */
+export function createModelContextPolyfill(): ModelContextPolyfill {
+  const tools = new Map<string, WebMCPToolDescriptor>();
+
+  const registerTool = (tool: WebMCPToolDescriptor, options?: { signal?: AbortSignal }): void => {
+    if (options?.signal?.aborted) return;
+    tools.set(tool.name, tool);
+    options?.signal?.addEventListener('abort', () => {
+      if (tools.get(tool.name) === tool) tools.delete(tool.name);
+    });
+  };
+
+  return {
+    polyfilled: true,
+    registerTool,
+    provideContext({ tools: next }) {
+      tools.clear();
+      next.forEach((tool) => registerTool(tool));
+    },
+    listTools: () => [...tools.values()],
+    async callTool(name, input) {
+      const tool = tools.get(name);
+
+      if (!tool) throw new Error(`WebMCP polyfill: unknown tool "${name}"`);
+
+      return tool.execute(input);
+    },
+  };
+}
+
+/** The native context when the browser has one (Chrome 149+ behind a flag); the polyfill otherwise. */
+function resolveModelContext(): ModelContext {
+  const doc = document as any;
+  const native = doc.modelContext ?? (navigator as any).modelContext;
+
+  if (native) return native;
+
+  return (doc.modelContext = createModelContextPolyfill());
+}
+
+/** The server knows the whole route (lazy islands, api() tools); unreachable → empty, fail-soft. */
+async function routeTools(): Promise<ManifestTool[]> {
+  try {
+    const url = `/_janux/manifest?path=${encodeURIComponent(location.pathname)}`;
+    const response = await fetch(url, { headers: { accept: 'application/json' } });
+
+    if (!response.ok) return [];
+
+    return ((await response.json()) as Manifest).tools ?? [];
+  } catch {
+    return [];
+  }
+}
+
+async function callServerTool(name: string, input: unknown): Promise<unknown> {
+  const response = await fetch(`/_janux/api/${name.slice('api.'.length)}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-janux-origin': 'agent' },
+    body: JSON.stringify(input ?? {}),
+  });
+
+  return response.json();
+}
+
+function descriptorFor(tool: ManifestTool, bridge: JanuxBridge): WebMCPToolDescriptor {
+  const approval = tool.guard === 'confirm' ? ' Returns a proposal a human must approve.' : '';
+
+  return {
+    name: tool.name.replace(/[^\w-]/g, '_'),
+    description: `${tool.description ?? `Janux tool ${tool.name}`}${approval}`,
+    inputSchema: tool.input ?? { type: 'object', properties: {} },
+    async execute(input) {
+      const result = tool.name.startsWith('api.')
+        ? await callServerTool(tool.name, input)
+        : await bridge.call(tool.name, input);
+
+      return { content: [{ type: 'text', text: JSON.stringify(result ?? null) }] };
+    },
+  };
+}
+
+/** Route manifest first, live local manifest on top (its `ready` state is current). */
+function mergedTools(bridge: JanuxBridge, remote: ManifestTool[]): ManifestTool[] {
+  const byName = new Map(remote.map((tool) => [tool.name, tool]));
+
+  bridge.manifest().tools.forEach((tool) => byName.set(tool.name, tool));
+
+  return [...byName.values()];
+}
+
+/**
+ * Zero-config WebMCP: registers every mounted tool with `document.modelContext`
+ * (polyfilled when absent) and keeps the registration in sync across SPA
+ * navigations. Chrome's DevTools WebMCP panel then shows the Janux surface as-is.
+ */
+export function installWebMCP(bridge: JanuxBridge): WebMCPHandle {
+  const context = resolveModelContext();
+  let controller: AbortController | undefined;
+  let chain: Promise<void> = Promise.resolve();
+
+  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 descriptor of descriptors) {
+      try {
+        await context.registerTool(descriptor, { signal: controller.signal });
+      } catch {
+        // One rejected registration (schema quirks, duplicate names…) must not drop the rest.
+      }
+    }
+  };
+
+  // Serialized like navigations: a re-sync never races the previous one's aborts.
+  const sync = (): Promise<void> => (chain = chain.then(run));
+
+  const onNavigate = (event: Event): void => {
+    if ((event as CustomEvent).detail?.phase === 'after') void sync();
+  };
+
+  document.addEventListener('janux:navigate', onNavigate);
+  void sync();
+
+  return {
+    sync,
+    dispose() {
+      document.removeEventListener('janux:navigate', onNavigate);
+      void chain.then(() => controller?.abort());
+    },
+  };
+}

package/src/define/factories.test.tsx

@@ -0,0 +1,25 @@
+/** @jsxImportSource .. */
+import { describe, expect, it } from 'bun:test';
+
+import { component } from './factories';
+import { renderToString } from '../render/server';
+
+const Island = component({
+  name: 'tag-island',
+  view: () => <p>hello</p>,
+});
+
+describe('component() as a JSX tag', () => {
+  it('typechecks as an element and server-renders as an island', async () => {
+    const page = (
+      <main>
+        <Island eager />
+      </main>
+    );
+    const result = await renderToString(page);
+
+    expect(result.html).toContain('data-jx="tag-island#');
+    expect(result.html).toContain('data-jx-eager');
+    expect(result.html).toContain('<p>hello</p>');
+  });
+});

package/src/define/factories.ts

@@ -1,5 +1,6 @@
 import type {
   ComponentDef,
+  ComponentTag,
   EffectDef,
   IntentDef,
   RefreshPolicy,
@@ -16,13 +17,13 @@ function assertName(name: unknown, kind: string): void {
 }
 
 /** Defines a bifacial component: view for humans, resource+tools for agents. */
-export function component(def: ComponentInput): ComponentDef {
+export function component(def: ComponentInput): ComponentTag {
   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 });
+  return Object.freeze({ ...def, kind: 'component' as const }) as ComponentTag;
 }
 
 /** Defines a shared store: a bifacial component without a view. */

package/src/define/types.ts

@@ -1,4 +1,5 @@
 import type { JxType } from '../schema';
+import type { JanuxNode } from '../jsx-runtime';
 
 export type GuardValue = 'auto' | 'confirm' | 'forbidden';
 export type Guard = GuardValue | ((bag: { ctx: Ctx }) => GuardValue);
@@ -81,3 +82,11 @@ export interface ComponentDef {
   scope?: 'app' | 'route';
   persist?: 'local' | 'none';
 }
+
+/**
+ * ComponentDef with a phantom call signature so TSX accepts `<MyIsland />` as
+ * an element. The signature never exists at runtime: `component()` returns a
+ * frozen plain object, and the renderer checks `typeof $t === 'function'`
+ * before `isComponentDef`, so defs always take the island path.
+ */
+export type ComponentTag = ComponentDef & ((props?: Record<string, unknown>) => JanuxNode);

package/src/index.ts

@@ -10,6 +10,7 @@ export {
 } from './define/factories';
 export type {
   ComponentDef,
+  ComponentTag,
   IntentDef,
   EffectDef,
   SourceDef,
@@ -40,5 +41,5 @@ export {
 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 { JanuxIntentError, resolveGuard, type AuditEntry, type Proposal } from './runtime/intents';
 export { Fragment, jsx, jsxs, type JanuxNode } from './jsx-runtime';

package/src/jsx-runtime.ts

@@ -29,6 +29,9 @@ export declare namespace JSX {
   interface IntrinsicElements {
     [element: string]: Record<string, unknown>;
   }
+  interface IntrinsicAttributes {
+    key?: string | number;
+  }
   interface ElementChildrenAttribute {
     children: unknown;
   }

package/src/render/server.test.ts

@@ -75,6 +75,16 @@ describe('renderToString', () => {
     expect(result.html).toBe('<input value="x"/>');
   });
 
+  it('marks persist and eager islands with data attributes (SPA navigation)', async () => {
+    const persisted = await renderToString(jsx(cart as any, { persist: true }));
+    const eager = await renderToString(jsx(cart as any, { eager: true }));
+    const plain = await renderToString(jsx(cart as any, {}));
+
+    expect(persisted.html).toContain('data-jx="cart#default" data-jx-persist>');
+    expect(eager.html).toContain('data-jx="cart#default" data-jx-eager>');
+    expect(plain.html).toContain('data-jx="cart#default">');
+  });
+
   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 }));

package/src/render/server.ts

@@ -69,8 +69,10 @@ async function renderIsland(def: ComponentDef, props: any, scope: RenderScope):
   await loadSources(instance);
   scope.registry.islands.push({ def, key, instance });
   const inner = await renderNode(def.view!(instance.bag), scope);
+  const persist = props.persist ? ' data-jx-persist' : '';
+  const eager = props.eager ? ' data-jx-eager' : '';
 
-  return `<janux-island data-jx="${escapeHtml(`${def.name}#${key}`)}">${inner}</janux-island>`;
+  return `<janux-island data-jx="${escapeHtml(`${def.name}#${key}`)}"${persist}${eager}>${inner}</janux-island>`;
 }
 
 async function renderElement(node: JanuxNode, scope: RenderScope): Promise<string> {

package/src/runtime/effects.ts

@@ -1,5 +1,5 @@
 import { computed, effect as watch, untrack } from '../signals';
-import { allowMutations } from '../state/mutation-gate';
+import { withGate, type MutationGate } from '../state/mutation-gate';
 import { parseDuration } from '../define/factories';
 import type { Cleanup, EffectDef, RunBag } from '../define/types';
 import type { PendingTracker } from './settled';
@@ -8,8 +8,8 @@ interface EffectRuntime {
   dispose: () => void;
 }
 
-function runEffectBody(def: EffectDef, bag: RunBag, tracker: PendingTracker): Cleanup {
-  const result = allowMutations(() => def.run(bag));
+function runEffectBody(def: EffectDef, bag: RunBag, tracker: PendingTracker, gate: MutationGate): Cleanup {
+  const result = withGate(gate, () => def.run(bag));
 
   if (result instanceof Promise) {
     tracker.track(result);
@@ -20,7 +20,7 @@ function runEffectBody(def: EffectDef, bag: RunBag, tracker: PendingTracker): Cl
   return typeof result === 'function' ? result : undefined;
 }
 
-function startOne(def: EffectDef, bag: RunBag, tracker: PendingTracker): EffectRuntime {
+function startOne(def: EffectDef, bag: RunBag, tracker: PendingTracker, gate: MutationGate): EffectRuntime {
   const debounceMs = def.debounce ? parseDuration(def.debounce) : 0;
   let cleanup: Cleanup;
   let timer: ReturnType<typeof setTimeout> | undefined;
@@ -29,7 +29,7 @@ function startOne(def: EffectDef, bag: RunBag, tracker: PendingTracker): EffectR
 
   const runNow = (): void => {
     cleanup?.();
-    cleanup = untrack(() => runEffectBody(def, bag, tracker));
+    cleanup = untrack(() => runEffectBody(def, bag, tracker, gate));
   };
 
   const schedule = (): void => {
@@ -73,8 +73,9 @@ export function startEffects(
   defs: Record<string, EffectDef> | undefined,
   bag: RunBag,
   tracker: PendingTracker,
+  gate: MutationGate,
 ): () => void {
-  const running = Object.values(defs ?? {}).map((def) => startOne(def, bag, tracker));
+  const running = Object.values(defs ?? {}).map((def) => startOne(def, bag, tracker, gate));
 
   return () => running.forEach((runtime) => runtime.dispose());
 }

package/src/runtime/instance.test.ts

@@ -48,6 +48,29 @@ describe('instance: state, derived, intents', () => {
     expect(cart.derived.count).toBe(3);
   });
 
+  it('async intents may mutate state after awaits (regression)', async () => {
+    const def = component({
+      name: 'async-cart',
+      state: schema({ items: list({ id: str(), qty: int() }), coupon: str().nullable() }),
+      intents: {
+        addThenCoupon: intent({
+          run: async ({ state }: any) => {
+            state.items.push({ id: 'a', qty: 1 });
+            await Promise.resolve();
+            state.coupon = 'SAVE10';
+            await new Promise((resolve) => setTimeout(resolve, 5));
+            state.items[0].qty = 2;
+          },
+        }),
+      },
+      view: noopView,
+    });
+    const cart = createInstance(def);
+
+    await cart.intents.addThenCoupon!({});
+    expect(cart.snapshot()).toEqual({ items: [{ id: 'a', qty: 2 }], coupon: 'SAVE10' });
+  });
+
   it('validates intent input against its schema', async () => {
     const cart = createInstance(cartDef());
 

package/src/runtime/instance.ts

@@ -1,7 +1,7 @@
 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 { createGate, withGate } from '../state/mutation-gate';
 import type { ComponentDef, Ctx, Origin, RunBag, StoreHandle } from '../define/types';
 import { createBus, type EventBus } from './bus';
 import { createPendingTracker } from './settled';
@@ -79,7 +79,8 @@ export function createInstance(def: ComponentDef, options: InstanceOptions = {})
   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 gate = createGate();
+  const state = createReactiveState(initial as Record<string, unknown>, gate);
   const sourcesRuntime = createSources(def.sources, ctx, bus, tracker, options.initialSources);
   const { readers: derived, dispose: disposeDerived } = derivedReaders(def, state.proxy);
   const emit = makeEmit(def, bus);
@@ -98,6 +99,7 @@ export function createInstance(def: ComponentDef, options: InstanceOptions = {})
     ctx,
   };
   const hooks = {
+    gate,
     onAudit: options.onAudit,
     onProposal: options.onProposal,
     trackPending: tracker.track,
@@ -113,7 +115,7 @@ export function createInstance(def: ComponentDef, options: InstanceOptions = {})
 
   let stopEffects: (() => void) | undefined;
   const busUnsubs = Object.entries(def.on ?? {}).map(([event, handler]) =>
-    bus.on(event, (payload) => allowMutations(() => handler({ ...bag, event: payload }))),
+    bus.on(event, (payload) => withGate(gate, () => handler({ ...bag, event: payload }))),
   );
 
   return {
@@ -148,15 +150,15 @@ export function createInstance(def: ComponentDef, options: InstanceOptions = {})
     },
     async attach() {
       sourcesRuntime.start();
-      stopEffects = startEffects(def.effects, bag, tracker);
-      await allowMutations(() => def.lifecycle?.attach?.(bag));
+      stopEffects = startEffects(def.effects, bag, tracker, gate);
+      await withGate(gate, () => def.lifecycle?.attach?.(bag));
     },
     async dispose() {
       stopEffects?.();
       sourcesRuntime.dispose();
       disposeDerived();
       busUnsubs.forEach((unsub) => unsub());
-      await allowMutations(() => def.lifecycle?.detach?.(bag));
+      await withGate(gate, () => def.lifecycle?.detach?.(bag));
     },
     handle(): StoreHandle {
       return { state: state.proxy, derived, intents: bindHumanIntents(intents) };

package/src/runtime/intents.ts

@@ -1,5 +1,5 @@
 import { validate } from '../schema';
-import { allowMutations } from '../state/mutation-gate';
+import { withGate, type MutationGate } from '../state/mutation-gate';
 import type { ComponentDef, Ctx, GuardValue, IntentDef, Origin, RunBag } from '../define/types';
 
 export interface AuditEntry {
@@ -10,6 +10,8 @@ export interface AuditEntry {
   ok: boolean;
   error?: string;
   at: number;
+  /** Verified Web Bot Auth key id, when the caller is an authenticated agent. */
+  agent?: string;
 }
 
 export interface Proposal {
@@ -20,6 +22,7 @@ export interface Proposal {
 }
 
 export interface IntentHooks {
+  gate: MutationGate;
   onAudit?: (entry: AuditEntry) => void;
   onProposal?: (proposal: Proposal) => void;
   trackPending: <T>(work: Promise<T>) => Promise<T>;
@@ -71,8 +74,8 @@ function audit(hooks: IntentHooks, entry: Omit<AuditEntry, 'at'>): void {
   hooks.onAudit?.({ ...entry, at: Date.now() });
 }
 
-async function execute(def: IntentDef, bag: RunBag, input: unknown): Promise<unknown> {
-  return allowMutations(() => def.run({ ...bag, input }));
+async function execute(def: IntentDef, bag: RunBag, input: unknown, gate: MutationGate): Promise<unknown> {
+  return withGate(gate, () => def.run({ ...bag, input }));
 }
 
 function propose(tool: string, input: unknown, run: () => Promise<unknown>, hooks: IntentHooks) {
@@ -102,7 +105,7 @@ export async function invokeIntent(
     }
     checkInvocable(tool, def, bag);
     const parsed = parseInput(tool, def, input);
-    const run = () => hooks.trackPending(execute(def, bag, parsed));
+    const run = () => hooks.trackPending(execute(def, bag, parsed, hooks.gate));
 
     if (origin === 'agent' && guard === 'confirm') {
       audit(hooks, { tool, origin, guard, input: parsed, ok: true });

package/src/state/mutation-gate.ts

@@ -1,17 +1,40 @@
-let mutationDepth = 0;
+export interface MutationGate {
+  depth: number;
+}
+
+export function createGate(): MutationGate {
+  return { depth: 0 };
+}
+
+/**
+ * Runs `fn` with mutations enabled on ONE instance's gate. For async bodies
+ * the gate stays open until the promise settles, so `run()` may mutate after
+ * `await`s. Per-instance scoping means an in-flight async intent never opens
+ * the door for other components' state. A development guardrail, not an
+ * isolation boundary.
+ */
+export function withGate<T>(gate: MutationGate, fn: () => T): T {
+  gate.depth += 1;
+  let result: T;
 
-/** Runs `fn` with state mutations enabled (used by intent/effect/event runners). */
-export function allowMutations<T>(fn: () => T): T {
-  mutationDepth += 1;
   try {
-    return fn();
-  } finally {
-    mutationDepth -= 1;
+    result = fn();
+  } catch (error) {
+    gate.depth -= 1;
+    throw error;
+  }
+  if (result instanceof Promise) {
+    return result.finally(() => {
+      gate.depth -= 1;
+    }) as T;
   }
+  gate.depth -= 1;
+
+  return result;
 }
 
-export function assertMutable(path: string): void {
-  if (mutationDepth > 0) return;
+export function assertMutable(gate: MutationGate, path: string): void {
+  if (gate.depth > 0) return;
 
   throw new Error(
     `Janux: illegal mutation of "${path}" outside an intent, effect or event handler. ` +

package/src/state/reactive-state.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, mock } from 'bun:test';
 import { effect } from '../signals';
-import { allowMutations } from './mutation-gate';
+import { createGate, withGate } from './mutation-gate';
 import { createReactiveState } from './reactive-state';
 
 const initial = () => ({
@@ -10,14 +10,16 @@ const initial = () => ({
 
 describe('reactive state', () => {
   it('reads initial data through the proxy', () => {
-    const state = createReactiveState(initial());
+    const gate = createGate();
+    const state = createReactiveState(initial(), gate);
 
     expect(state.proxy.items[0]!.qty).toBe(1);
     expect(state.proxy.coupon).toBe(null);
   });
 
   it('throws on mutation outside a run context', () => {
-    const state = createReactiveState(initial());
+    const gate = createGate();
+    const state = createReactiveState(initial(), gate);
 
     expect(() => {
       state.proxy.coupon = 'SAVE10';
@@ -26,14 +28,15 @@ describe('reactive state', () => {
   });
 
   it('mutates inside allowMutations and notifies path readers', () => {
-    const state = createReactiveState(initial());
+    const gate = createGate();
+    const state = createReactiveState(initial(), gate);
     const runs = mock(() => {});
 
     effect(() => {
       runs();
       state.proxy.items[0]!.qty;
     });
-    allowMutations(() => {
+    withGate(gate, () => {
       state.proxy.items[0]!.qty = 5;
     });
     expect(runs).toHaveBeenCalledTimes(2);
@@ -41,16 +44,17 @@ describe('reactive state', () => {
   });
 
   it('notifies list readers on push and filter-reassign', () => {
-    const state = createReactiveState(initial());
+    const gate = createGate();
+    const state = createReactiveState(initial(), gate);
     const lengths: number[] = [];
 
     effect(() => {
       lengths.push(state.proxy.items.length);
     });
-    allowMutations(() => {
+    withGate(gate, () => {
       state.proxy.items.push({ id: 'b', qty: 2 });
     });
-    allowMutations(() => {
+    withGate(gate, () => {
       state.proxy.items = state.proxy.items.filter((item) => item.id === 'b');
     });
     expect(lengths).toEqual([1, 2, 1]);
@@ -58,21 +62,23 @@ describe('reactive state', () => {
   });
 
   it('does not notify readers of untouched sibling paths', () => {
-    const state = createReactiveState(initial());
+    const gate = createGate();
+    const state = createReactiveState(initial(), gate);
     const runs = mock(() => {});
 
     effect(() => {
       runs();
       state.proxy.coupon;
     });
-    allowMutations(() => {
+    withGate(gate, () => {
       state.proxy.items[0]!.qty = 9;
     });
     expect(runs).toHaveBeenCalledTimes(1);
   });
 
   it('snapshot is plain data detached from the proxy', () => {
-    const state = createReactiveState(initial());
+    const gate = createGate();
+    const state = createReactiveState(initial(), gate);
     const snap = state.snapshot();
 
     snap.items[0]!.qty = 99;

package/src/state/reactive-state.ts

@@ -1,5 +1,5 @@
 import { batch, signal, untrack, type Sig } from '../signals';
-import { assertMutable } from './mutation-gate';
+import { assertMutable, createGate, type MutationGate } from './mutation-gate';
 
 const MUTATING_ARRAY_METHODS = new Set([
   'push',
@@ -34,7 +34,10 @@ function plainObject(value: object): Record<string, unknown> {
   return Object.fromEntries(Object.entries(value).map(([key, v]) => [key, plainify(v)]));
 }
 
-export function createReactiveState<T extends object>(initial: T): ReactiveState<T> {
+export function createReactiveState<T extends object>(
+  initial: T,
+  gate: MutationGate = createGate(),
+): ReactiveState<T> {
   const versions = new Map<string, Sig<number>>();
   let data = structuredClone(initial);
 
@@ -78,7 +81,7 @@ export function createReactiveState<T extends object>(initial: T): ReactiveState
 
   const wrapArrayMethod = (target: unknown[], path: string, method: string) => {
     return (...args: unknown[]) => {
-      assertMutable(path);
+      assertMutable(gate, path);
       const result = (target as any)[method](...args.map(plainify));
 
       touch(path);
@@ -112,7 +115,7 @@ export function createReactiveState<T extends object>(initial: T): ReactiveState
     if (typeof key === 'symbol') return Reflect.set(raw, key, value);
     const target = childPath(path, key);
 
-    assertMutable(target);
+    assertMutable(gate, target);
     Reflect.set(raw, key, plainify(value));
     touch(target);
 
@@ -123,7 +126,7 @@ export function createReactiveState<T extends object>(initial: T): ReactiveState
     if (typeof key === 'symbol') return Reflect.deleteProperty(raw, key);
     const target = childPath(path, key);
 
-    assertMutable(target);
+    assertMutable(gate, target);
     Reflect.deleteProperty(raw, key);
     touch(target);