@rozenite/controls-plugin 1.11.0 → 1.12.0

package/dist/react-native/index.d.ts

@@ -127,8 +127,12 @@ export declare type RozeniteControlsPluginOptions = {
     sections: ControlsSection[];
 };
 
+export declare type RozeniteControlsPluginOptionsInput = RozeniteControlsPluginOptions | RozeniteControlsPluginOptionsUpdater;
+
+export declare type RozeniteControlsPluginOptionsUpdater = (previousOptions: RozeniteControlsPluginOptions) => RozeniteControlsPluginOptions;
+
 export declare let useRozeniteControlsPlugin: typeof useRozeniteControlsPlugin_2;
 
-declare const useRozeniteControlsPlugin_2: ({ sections, }: RozeniteControlsPluginOptions) => RozeniteDevToolsClient<ControlsEventMap> | null;
+declare const useRozeniteControlsPlugin_2: (optionsInput: RozeniteControlsPluginOptionsInput) => RozeniteDevToolsClient<ControlsEventMap> | null;
 
 export { }

package/dist/rozenite.json

@@ -1 +1 @@
-{"name":"@rozenite/controls-plugin","version":"1.11.0","description":"A Rozenite plugin for exposing app-defined controls directly in React Native DevTools.","panels":[{"name":"Controls","source":"/devtools/panel.html"}]}
+{"name":"@rozenite/controls-plugin","version":"1.12.0","description":"A Rozenite plugin for exposing app-defined controls directly in React Native DevTools.","panels":[{"name":"Controls","source":"/devtools/panel.html"}]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rozenite/controls-plugin",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "A Rozenite plugin for exposing app-defined controls directly in React Native DevTools.",
   "type": "module",
   "main": "./dist/react-native/index.cjs",
@@ -15,9 +15,9 @@
     "url": "https://github.com/callstackincubator/rozenite.git"
   },
   "dependencies": {
-    "@rozenite/agent-shared": "1.11.0",
-    "@rozenite/agent-bridge": "1.11.0",
-    "@rozenite/plugin-bridge": "1.11.0"
+    "@rozenite/agent-shared": "1.12.0",
+    "@rozenite/agent-bridge": "1.12.0",
+    "@rozenite/plugin-bridge": "1.12.0"
   },
   "devDependencies": {
     "@types/react": "~19.2.2",
@@ -32,8 +32,8 @@
     "tailwindcss-animate": "^1.0.7",
     "typescript": "~5.9.3",
     "vite": "^7.3.1",
-    "@rozenite/vite-plugin": "1.11.0",
-    "rozenite": "1.11.0"
+    "@rozenite/vite-plugin": "1.12.0",
+    "rozenite": "1.12.0"
   },
   "peerDependencies": {
     "react": "*",
@@ -61,6 +61,7 @@
     "build": "rozenite build",
     "dev": "rozenite dev",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "test": "vitest --run --passWithNoTests"
   }
 }

package/react-native.d.ts

@@ -8,12 +8,16 @@ export {
   type ControlsSection,
   type ControlsTextItem,
   type ControlsToggleItem,
+  type RozeniteControlsPluginOptionsInput,
   type ControlsValidationResult,
   type RozeniteControlsPluginOptions,
+  type RozeniteControlsPluginOptionsUpdater,
 } from './src/shared/types';
 
 export declare const useRozeniteControlsPlugin: (
-  options: import('./src/shared/types').RozeniteControlsPluginOptions
-) => import('@rozenite/plugin-bridge').RozeniteDevToolsClient<
-  import('./src/shared/messaging').ControlsEventMap
-> | null;
+  options: import('./src/shared/types').RozeniteControlsPluginOptionsInput,
+) =>
+  | import('@rozenite/plugin-bridge').RozeniteDevToolsClient<
+      import('./src/shared/messaging').ControlsEventMap
+    >
+  | null;

package/react-native.ts

@@ -8,8 +8,10 @@ export {
   type ControlsSection,
   type ControlsTextItem,
   type ControlsToggleItem,
+  type RozeniteControlsPluginOptionsInput,
   type ControlsValidationResult,
   type RozeniteControlsPluginOptions,
+  type RozeniteControlsPluginOptionsUpdater,
 } from './src/shared/types';
 
 export let useRozeniteControlsPlugin: typeof import('./src/react-native/useRozeniteControlsPlugin').useRozeniteControlsPlugin;

package/src/react-native/__tests__/controlsRegistry.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createControlsRegistry } from '../controlsRegistry';
+import type { ControlsSection } from '../../shared/types';
+
+const section = (id: string): ControlsSection => ({
+  id,
+  title: id,
+  items: [],
+});
+
+describe('controlsRegistry', () => {
+  it('combines section registrations in registration order', () => {
+    const registry = createControlsRegistry();
+    const first = Symbol('first');
+    const second = Symbol('second');
+
+    registry.set(first, { sections: [section('app')] });
+    registry.set(second, { sections: [section('locale')] });
+
+    expect(registry.getOptions().sections.map(({ id }) => id)).toEqual([
+      'app',
+      'locale',
+    ]);
+  });
+
+  it('lets updater registrations derive from previous options', () => {
+    const registry = createControlsRegistry();
+    const first = Symbol('first');
+    const second = Symbol('second');
+
+    registry.set(first, { sections: [section('app')] });
+    registry.set(second, (previousOptions) => ({
+      sections: [...previousOptions.sections, section('locale')],
+    }));
+
+    expect(registry.getOptions().sections.map(({ id }) => id)).toEqual([
+      'app',
+      'locale',
+    ]);
+  });
+
+  it('lets updater registrations replace previous options when needed', () => {
+    const registry = createControlsRegistry();
+    const first = Symbol('first');
+    const second = Symbol('second');
+
+    registry.set(first, { sections: [section('app')] });
+    registry.set(second, () => ({
+      sections: [section('replacement')],
+    }));
+
+    expect(registry.getOptions().sections.map(({ id }) => id)).toEqual([
+      'replacement',
+    ]);
+  });
+
+  it('can include the current render input before the effect registers it', () => {
+    const registry = createControlsRegistry();
+    const id = Symbol('pending');
+
+    expect(
+      registry
+        .getOptions({ id, input: { sections: [section('pending')] } })
+        .sections.map((registeredSection) => registeredSection.id),
+    ).toEqual(['pending']);
+    expect(registry.isOwner(id, { id, input: { sections: [] } })).toBe(true);
+  });
+
+  it('notifies subscribers when ownership changes or registrations are removed', () => {
+    const registry = createControlsRegistry();
+    const listener = vi.fn();
+    const first = Symbol('first');
+    const second = Symbol('second');
+
+    registry.subscribe(listener);
+    expect(registry.getSnapshot()).toBe(0);
+
+    registry.set(first, { sections: [section('app')] });
+    expect(registry.getSnapshot()).toBe(1);
+
+    registry.set(second, { sections: [section('locale')] });
+    expect(registry.getSnapshot()).toBe(1);
+
+    registry.delete(second);
+    expect(registry.getSnapshot()).toBe(2);
+
+    registry.delete(first);
+    expect(registry.getSnapshot()).toBe(3);
+
+    expect(listener).toHaveBeenCalledTimes(3);
+  });
+});

package/src/react-native/__tests__/useRozeniteControlsPlugin.test.tsx

@@ -0,0 +1,211 @@
+// @vitest-environment jsdom
+
+import { act, type ReactNode } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createSection } from '../../shared/types';
+import type { ControlsEventMap } from '../../shared/messaging';
+
+declare global {
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
+}
+
+type Listener = (payload: unknown) => void;
+
+const mocks = vi.hoisted(() => {
+  const listeners = new Map<string, Set<Listener>>();
+  const send = vi.fn();
+  const onMessage = vi.fn((type: string, listener: Listener) => {
+    const typeListeners = listeners.get(type) ?? new Set<Listener>();
+    typeListeners.add(listener);
+    listeners.set(type, typeListeners);
+
+    return {
+      remove: () => {
+        typeListeners.delete(listener);
+      },
+    };
+  });
+
+  return {
+    client: {
+      send,
+      onMessage,
+    },
+    emit: (type: keyof ControlsEventMap, payload: unknown) => {
+      listeners.get(type)?.forEach((listener) => {
+        listener(payload);
+      });
+    },
+    reset: () => {
+      listeners.clear();
+      send.mockReset();
+      onMessage.mockClear();
+    },
+  };
+});
+
+vi.mock('@rozenite/plugin-bridge', () => ({
+  useRozeniteDevToolsClient: () => mocks.client,
+}));
+
+vi.mock('../useControlsAgentTools', () => ({
+  useControlsAgentTools: vi.fn(),
+}));
+
+import { useRozeniteControlsPlugin } from '../useRozeniteControlsPlugin';
+
+const appSection = createSection({
+  id: 'app',
+  title: 'App',
+  items: [],
+});
+
+const localeSection = (onUpdate: (value: string) => void = vi.fn()) =>
+  createSection({
+    id: 'locale',
+    title: 'Locale',
+    items: [
+      {
+        id: 'language',
+        type: 'select',
+        title: 'Language',
+        value: 'en',
+        options: [
+          { label: 'English', value: 'en' },
+          { label: 'Polish', value: 'pl' },
+        ],
+        onUpdate,
+      },
+    ],
+  });
+
+function AppControls() {
+  useRozeniteControlsPlugin({
+    sections: [appSection],
+  });
+
+  return null;
+}
+
+function LocaleControls({
+  onUpdate = vi.fn(),
+}: {
+  onUpdate?: (value: string) => void;
+}) {
+  useRozeniteControlsPlugin((previousOptions) => ({
+    sections: [...previousOptions.sections, localeSection(onUpdate)],
+  }));
+
+  return null;
+}
+
+function TestApp({
+  showLocale = true,
+  onUpdate,
+}: {
+  showLocale?: boolean;
+  onUpdate?: (value: string) => void;
+}) {
+  return (
+    <>
+      <AppControls />
+      {showLocale ? <LocaleControls onUpdate={onUpdate} /> : null}
+    </>
+  );
+}
+
+const renderControls = async (
+  element: ReactNode,
+): Promise<{
+  root: Root;
+  container: HTMLDivElement;
+}> => {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+
+  await act(async () => {
+    root.render(element);
+  });
+
+  return { root, container };
+};
+
+const unmountControls = async (root: Root, container: HTMLDivElement) => {
+  await act(async () => {
+    root.unmount();
+  });
+  container.remove();
+};
+
+const getLastSnapshotSectionIds = () => {
+  const snapshots = mocks.client.send.mock.calls.filter(
+    ([type]) => type === 'snapshot',
+  );
+  const lastSnapshot = snapshots.at(-1)?.[1] as
+    | ControlsEventMap['snapshot']
+    | undefined;
+
+  return lastSnapshot?.sections.map((section) => section.id);
+};
+
+describe('useRozeniteControlsPlugin', () => {
+  beforeEach(() => {
+    mocks.reset();
+    globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = '';
+    delete globalThis.IS_REACT_ACT_ENVIRONMENT;
+  });
+
+  it('publishes a combined snapshot from multiple hook instances', async () => {
+    const { root, container } = await renderControls(<TestApp />);
+
+    expect(getLastSnapshotSectionIds()).toEqual(['app', 'locale']);
+
+    await unmountControls(root, container);
+  });
+
+  it('removes sections when their hook instance unmounts', async () => {
+    const { root, container } = await renderControls(<TestApp />);
+
+    await act(async () => {
+      root.render(<TestApp showLocale={false} />);
+    });
+
+    expect(getLastSnapshotSectionIds()).toEqual(['app']);
+
+    await unmountControls(root, container);
+  });
+
+  it('routes updates to sections registered by another hook instance', async () => {
+    const onUpdate = vi.fn();
+    const { root, container } = await renderControls(
+      <TestApp onUpdate={onUpdate} />,
+    );
+
+    await act(async () => {
+      mocks.emit('update-request', {
+        type: 'update-request',
+        requestId: 'request-1',
+        sectionId: 'locale',
+        itemId: 'language',
+        value: 'pl',
+      });
+    });
+
+    expect(onUpdate).toHaveBeenCalledWith('pl');
+    expect(mocks.client.send).toHaveBeenCalledWith('update-result', {
+      type: 'update-result',
+      requestId: 'request-1',
+      sectionId: 'locale',
+      itemId: 'language',
+      status: 'ok',
+    });
+
+    await unmountControls(root, container);
+  });
+});

package/src/react-native/controlsRegistry.ts

@@ -0,0 +1,101 @@
+import type {
+  RozeniteControlsPluginOptions,
+  RozeniteControlsPluginOptionsInput,
+} from '../shared/types';
+
+type ControlsRegistryListener = () => void;
+type ControlsRegistryOverride = {
+  id: symbol;
+  input: RozeniteControlsPluginOptionsInput;
+};
+
+const EMPTY_OPTIONS: RozeniteControlsPluginOptions = {
+  sections: [],
+};
+
+const resolveOptionsInput = (
+  previousOptions: RozeniteControlsPluginOptions,
+  input: RozeniteControlsPluginOptionsInput,
+): RozeniteControlsPluginOptions => {
+  if (typeof input === 'function') {
+    return input(previousOptions);
+  }
+
+  return {
+    ...previousOptions,
+    ...input,
+    sections: [...previousOptions.sections, ...input.sections],
+  };
+};
+
+export const createControlsRegistry = () => {
+  const registrations = new Map<symbol, RozeniteControlsPluginOptionsInput>();
+  const listeners = new Set<ControlsRegistryListener>();
+  let snapshot = 0;
+
+  const getOwnerId = () => registrations.keys().next().value;
+
+  const notify = () => {
+    snapshot += 1;
+    listeners.forEach((listener) => listener());
+  };
+
+  const getRegistrationEntries = (override?: ControlsRegistryOverride) => {
+    const entries = Array.from(registrations.entries());
+
+    if (!override) {
+      return entries;
+    }
+
+    const overrideIndex = entries.findIndex(([id]) => id === override.id);
+
+    if (overrideIndex === -1) {
+      return [...entries, [override.id, override.input] as const];
+    }
+
+    return entries.map(([id, input]) =>
+      id === override.id
+        ? ([id, override.input] as const)
+        : ([id, input] as const),
+    );
+  };
+
+  return {
+    set(id: symbol, input: RozeniteControlsPluginOptionsInput) {
+      const previousOwnerId = getOwnerId();
+      registrations.set(id, input);
+
+      if (previousOwnerId !== getOwnerId()) {
+        notify();
+      }
+    },
+    delete(id: symbol) {
+      registrations.delete(id);
+      notify();
+    },
+    getOptions(
+      override?: ControlsRegistryOverride,
+    ): RozeniteControlsPluginOptions {
+      return getRegistrationEntries(override)
+        .map(([, input]) => input)
+        .reduce(resolveOptionsInput, EMPTY_OPTIONS);
+    },
+    isOwner(id: symbol, override?: ControlsRegistryOverride) {
+      const ownerEntry = getRegistrationEntries(override)[0];
+
+      return ownerEntry?.[0] === id;
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    subscribe(listener: ControlsRegistryListener) {
+      listeners.add(listener);
+
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+};
+
+export const controlsRegistry = createControlsRegistry();

package/src/react-native/useControlsAgentTools.ts

@@ -8,14 +8,14 @@ import type { ControlsSection } from '../shared/types';
 const resolveItem = (
   sections: ControlsSection[],
   sectionId: string,
-  itemId: string
+  itemId: string,
 ) => {
   const section = sections.find((s) => s.id === sectionId);
 
   if (!section) {
     const available = sections.map((s) => s.id).join(', ');
     throw new Error(
-      `Section "${sectionId}" not found. Available: ${available || '(none)'}`
+      `Section "${sectionId}" not found. Available: ${available || '(none)'}`,
     );
   }
 
@@ -24,19 +24,23 @@ const resolveItem = (
   if (!item) {
     const available = section.items.map((i) => i.id).join(', ');
     throw new Error(
-      `Item "${itemId}" not found in section "${sectionId}". Available: ${available || '(none)'}`
+      `Item "${itemId}" not found in section "${sectionId}". Available: ${available || '(none)'}`,
     );
   }
 
   return { section, item };
 };
 
-export const useControlsAgentTools = (sections: ControlsSection[]) => {
+export const useControlsAgentTools = (
+  getSections: () => ControlsSection[],
+  enabled = true,
+) => {
   useRozenitePluginAgentTool({
     pluginId: CONTROLS_AGENT_PLUGIN_ID,
     tool: controlsToolDefinitions.listSections,
+    enabled,
     handler: () => ({
-      sections: sections.map((section) => ({
+      sections: getSections().map((section) => ({
         id: section.id,
         title: section.title,
         description: section.description,
@@ -53,8 +57,9 @@ export const useControlsAgentTools = (sections: ControlsSection[]) => {
   useRozenitePluginAgentTool({
     pluginId: CONTROLS_AGENT_PLUGIN_ID,
     tool: controlsToolDefinitions.getItem,
+    enabled,
     handler: ({ sectionId, itemId }) => {
-      const { item } = resolveItem(sections, sectionId, itemId);
+      const { item } = resolveItem(getSections(), sectionId, itemId);
 
       if (item.type === 'text') {
         return {
@@ -131,18 +136,19 @@ export const useControlsAgentTools = (sections: ControlsSection[]) => {
   useRozenitePluginAgentTool({
     pluginId: CONTROLS_AGENT_PLUGIN_ID,
     tool: controlsToolDefinitions.setValue,
+    enabled,
     handler: async ({ sectionId, itemId, value }) => {
-      const { item } = resolveItem(sections, sectionId, itemId);
+      const { item } = resolveItem(getSections(), sectionId, itemId);
 
       if (item.type === 'text') {
         throw new Error(
-          `Item "${itemId}" is a read-only text item and cannot be updated.`
+          `Item "${itemId}" is a read-only text item and cannot be updated.`,
         );
       }
 
       if (item.type === 'button') {
         throw new Error(
-          `Item "${itemId}" is a button. Use press-button to trigger its action.`
+          `Item "${itemId}" is a button. Use press-button to trigger its action.`,
         );
       }
 
@@ -153,7 +159,7 @@ export const useControlsAgentTools = (sections: ControlsSection[]) => {
       if (item.type === 'toggle') {
         if (typeof value !== 'boolean') {
           throw new Error(
-            `Expected boolean value for toggle item "${itemId}".`
+            `Expected boolean value for toggle item "${itemId}".`,
           );
         }
 
@@ -170,7 +176,7 @@ export const useControlsAgentTools = (sections: ControlsSection[]) => {
 
       if (typeof value !== 'string') {
         throw new Error(
-          `Expected string value for ${item.type} item "${itemId}".`
+          `Expected string value for ${item.type} item "${itemId}".`,
         );
       }
 
@@ -178,7 +184,7 @@ export const useControlsAgentTools = (sections: ControlsSection[]) => {
         const validOptions = item.options.map((o) => o.value);
         if (!validOptions.includes(value)) {
           throw new Error(
-            `Invalid option "${value}" for item "${itemId}". Valid options: ${validOptions.join(', ')}`
+            `Invalid option "${value}" for item "${itemId}". Valid options: ${validOptions.join(', ')}`,
           );
         }
       }
@@ -198,12 +204,13 @@ export const useControlsAgentTools = (sections: ControlsSection[]) => {
   useRozenitePluginAgentTool({
     pluginId: CONTROLS_AGENT_PLUGIN_ID,
     tool: controlsToolDefinitions.pressButton,
+    enabled,
     handler: async ({ sectionId, itemId }) => {
-      const { item } = resolveItem(sections, sectionId, itemId);
+      const { item } = resolveItem(getSections(), sectionId, itemId);
 
       if (item.type !== 'button') {
         throw new Error(
-          `Item "${itemId}" is not a button (type: ${item.type}). Use set-value to update its value.`
+          `Item "${itemId}" is not a button (type: ${item.type}). Use set-value to update its value.`,
         );
       }