@rozenite/controls-plugin 1.7.0-rc.2 → 1.8.0

package/dist/sdk/index.d.ts

@@ -0,0 +1,150 @@
+import { AgentToolContract } from '@rozenite/agent-shared';
+import { AgentToolDescriptor } from '@rozenite/agent-shared';
+
+export declare const CONTROLS_AGENT_PLUGIN_ID = "@rozenite/controls-plugin";
+
+declare type ControlsButtonItem = {
+    id: string;
+    type: 'button';
+    title: string;
+    actionLabel?: string;
+    description?: string;
+    disabled?: boolean;
+    onPress: () => void | Promise<void>;
+};
+
+export declare type ControlsButtonItemSnapshot = Omit<ControlsButtonItem, 'onPress'>;
+
+export declare type ControlsGetItemArgs = ControlsSectionItemArgs;
+
+export declare type ControlsGetItemResult = {
+    sectionId: string;
+    item: ControlsItemSnapshot;
+};
+
+declare type ControlsInputItem = ControlsMutableItemBase<string> & {
+    type: 'input';
+    placeholder?: string;
+    applyLabel?: string;
+};
+
+export declare type ControlsInputItemSnapshot = Omit<ControlsInputItem, 'validate' | 'onUpdate'>;
+
+declare type ControlsItem = ControlsTextItem | ControlsToggleItem | ControlsButtonItem | ControlsSelectItem | ControlsInputItem;
+
+export declare type ControlsItemSnapshot = ControlsTextItemSnapshot | ControlsToggleItemSnapshot | ControlsButtonItemSnapshot | ControlsSelectItemSnapshot | ControlsInputItemSnapshot;
+
+export declare type ControlsListSectionItemSummary = {
+    id: string;
+    type: ControlsItem['type'];
+    title: string;
+    disabled?: boolean;
+};
+
+export declare type ControlsListSectionsArgs = undefined;
+
+export declare type ControlsListSectionsResult = {
+    sections: ControlsListSectionSummary[];
+};
+
+export declare type ControlsListSectionSummary = {
+    id: string;
+    title: string;
+    description?: string;
+    items: ControlsListSectionItemSummary[];
+};
+
+declare type ControlsMutableItemBase<TValue> = {
+    id: string;
+    title: string;
+    value: TValue;
+    description?: string;
+    disabled?: boolean;
+    validate?: (nextValue: TValue) => ControlsValidationResult;
+    onUpdate: (nextValue: TValue) => void | Promise<void>;
+};
+
+export declare type ControlsPressButtonArgs = ControlsSectionItemArgs;
+
+export declare type ControlsPressButtonResult = {
+    pressed: true;
+    sectionId: string;
+    itemId: string;
+};
+
+declare type ControlsSection = {
+    id: string;
+    title: string;
+    description?: string;
+    items: ControlsItem[];
+};
+
+export declare type ControlsSectionItemArgs = {
+    sectionId: string;
+    itemId: string;
+};
+
+export declare type ControlsSectionSnapshot = Omit<ControlsSection, 'items'> & {
+    items: ControlsItemSnapshot[];
+};
+
+declare type ControlsSelectItem = ControlsMutableItemBase<string> & {
+    type: 'select';
+    options: ControlsSelectOption[];
+};
+
+export declare type ControlsSelectItemSnapshot = Omit<ControlsSelectItem, 'validate' | 'onUpdate'>;
+
+export declare type ControlsSelectOption = {
+    label: string;
+    value: string;
+};
+
+export declare type ControlsSetValueArgs = ControlsSectionItemArgs & {
+    value: boolean | string;
+};
+
+export declare type ControlsSetValueResult = {
+    applied: true;
+    sectionId: string;
+    itemId: string;
+};
+
+declare type ControlsTextItem = {
+    id: string;
+    type: 'text';
+    title: string;
+    value: string;
+    description?: string;
+};
+
+export declare type ControlsTextItemSnapshot = Omit<ControlsTextItem, never>;
+
+declare type ControlsToggleItem = ControlsMutableItemBase<boolean> & {
+    type: 'toggle';
+};
+
+export declare type ControlsToggleItemSnapshot = Omit<ControlsToggleItem, 'validate' | 'onUpdate'>;
+
+export declare const controlsToolDefinitions: {
+    readonly listSections: AgentToolContract<undefined, ControlsListSectionsResult>;
+    readonly getItem: AgentToolContract<ControlsSectionItemArgs, ControlsGetItemResult>;
+    readonly setValue: AgentToolContract<ControlsSetValueArgs, ControlsSetValueResult>;
+    readonly pressButton: AgentToolContract<ControlsSectionItemArgs, ControlsPressButtonResult>;
+};
+
+export declare const controlsTools: {
+    readonly listSections: AgentToolDescriptor<undefined, ControlsListSectionsResult>;
+    readonly getItem: AgentToolDescriptor<ControlsSectionItemArgs, ControlsGetItemResult>;
+    readonly setValue: AgentToolDescriptor<ControlsSetValueArgs, ControlsSetValueResult>;
+    readonly pressButton: AgentToolDescriptor<ControlsSectionItemArgs, ControlsPressButtonResult>;
+};
+
+declare type ControlsValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    message: string;
+};
+
+export { }

package/dist/sdk/index.js

@@ -0,0 +1,55 @@
+import { defineAgentToolContract as e, defineAgentToolDescriptors as t } from "@rozenite/agent-shared";
+const i = "@rozenite/controls-plugin", o = {
+  listSections: e({
+    name: "list-sections",
+    description: "List all controls sections with their item IDs, types, and titles. Does not include values — call get-item for that.",
+    inputSchema: { type: "object", properties: {} }
+  }),
+  getItem: e({
+    name: "get-item",
+    description: "Get full details of a single controls item including its current value. For select items this includes available options.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sectionId: { type: "string", description: "Section ID." },
+        itemId: { type: "string", description: "Item ID." }
+      },
+      required: ["sectionId", "itemId"]
+    }
+  }),
+  setValue: e({
+    name: "set-value",
+    description: "Update the value of a toggle, select, or input item. Runs the validate callback when present. Fails for text (read-only) and button items.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sectionId: { type: "string", description: "Section ID." },
+        itemId: { type: "string", description: "Item ID." },
+        value: {
+          description: "New value. Boolean for toggle items, string for select/input items."
+        }
+      },
+      required: ["sectionId", "itemId", "value"]
+    }
+  }),
+  pressButton: e({
+    name: "press-button",
+    description: "Trigger a button item's action. Fails if the item is not a button or is disabled.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sectionId: { type: "string", description: "Section ID." },
+        itemId: { type: "string", description: "Item ID." }
+      },
+      required: ["sectionId", "itemId"]
+    }
+  })
+}, n = t(
+  i,
+  o
+);
+export {
+  i as CONTROLS_AGENT_PLUGIN_ID,
+  o as controlsToolDefinitions,
+  n as controlsTools
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rozenite/controls-plugin",
-  "version": "1.7.0-rc.2",
+  "version": "1.8.0",
   "description": "A Rozenite plugin for exposing app-defined controls directly in React Native DevTools.",
   "type": "module",
   "main": "./dist/react-native/index.cjs",
@@ -15,8 +15,9 @@
     "url": "https://github.com/callstackincubator/rozenite.git"
   },
   "dependencies": {
-    "@rozenite/agent-bridge": "1.7.0-rc.2",
-    "@rozenite/plugin-bridge": "1.7.0-rc.2"
+    "@rozenite/agent-shared": "1.8.0",
+    "@rozenite/agent-bridge": "1.8.0",
+    "@rozenite/plugin-bridge": "1.8.0"
   },
   "devDependencies": {
     "@types/react": "~19.2.2",
@@ -31,8 +32,8 @@
     "tailwindcss-animate": "^1.0.7",
     "typescript": "~5.9.3",
     "vite": "^7.3.1",
-    "@rozenite/vite-plugin": "1.7.0-rc.2",
-    "rozenite": "1.7.0-rc.2"
+    "@rozenite/vite-plugin": "1.8.0",
+    "rozenite": "1.8.0"
   },
   "peerDependencies": {
     "react": "*",
@@ -45,7 +46,13 @@
       "import": "./dist/react-native/index.js",
       "require": "./dist/react-native/index.cjs"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./sdk": {
+      "development": "./sdk.ts",
+      "types": "./dist/sdk/index.d.ts",
+      "import": "./dist/sdk/index.js",
+      "require": "./dist/sdk/index.cjs"
+    }
   },
   "publishConfig": {
     "access": "public"

package/sdk.ts

@@ -0,0 +1,40 @@
+import { defineAgentToolDescriptors } from '@rozenite/agent-shared';
+import {
+  CONTROLS_AGENT_PLUGIN_ID,
+  controlsToolDefinitions,
+} from './src/shared/agent-tools.js';
+
+export {
+  CONTROLS_AGENT_PLUGIN_ID,
+  controlsToolDefinitions,
+};
+
+export const controlsTools = defineAgentToolDescriptors(
+  CONTROLS_AGENT_PLUGIN_ID,
+  controlsToolDefinitions,
+);
+
+export type {
+  ControlsGetItemArgs,
+  ControlsGetItemResult,
+  ControlsListSectionItemSummary,
+  ControlsListSectionSummary,
+  ControlsListSectionsArgs,
+  ControlsListSectionsResult,
+  ControlsPressButtonArgs,
+  ControlsPressButtonResult,
+  ControlsSectionItemArgs,
+  ControlsSetValueArgs,
+  ControlsSetValueResult,
+} from './src/shared/agent-tools.js';
+
+export type {
+  ControlsButtonItemSnapshot,
+  ControlsInputItemSnapshot,
+  ControlsItemSnapshot,
+  ControlsSectionSnapshot,
+  ControlsSelectItemSnapshot,
+  ControlsSelectOption,
+  ControlsTextItemSnapshot,
+  ControlsToggleItemSnapshot,
+} from './src/shared/types.js';

package/src/react-native/useControlsAgentTools.ts

@@ -1,69 +1,10 @@
-import { useRozenitePluginAgentTool, type AgentTool } from '@rozenite/agent-bridge';
+import { useRozenitePluginAgentTool } from '@rozenite/agent-bridge';
+import {
+  CONTROLS_AGENT_PLUGIN_ID,
+  controlsToolDefinitions,
+} from '../shared/agent-tools';
 import type { ControlsSection } from '../shared/types';
 
-type SectionItemInput = {
-  sectionId: string;
-  itemId: string;
-};
-
-type SetValueInput = SectionItemInput & {
-  value: boolean | string;
-};
-
-const pluginId = '@rozenite/controls-plugin';
-
-const listSectionsTool: AgentTool = {
-  name: 'list-sections',
-  description:
-    'List all controls sections with their item IDs, types, and titles. Does not include values — call get-item for that.',
-  inputSchema: { type: 'object', properties: {} },
-};
-
-const getItemTool: AgentTool = {
-  name: 'get-item',
-  description:
-    'Get full details of a single controls item including its current value. For select items this includes available options.',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      sectionId: { type: 'string', description: 'Section ID.' },
-      itemId: { type: 'string', description: 'Item ID.' },
-    },
-    required: ['sectionId', 'itemId'],
-  },
-};
-
-const setValueTool: AgentTool = {
-  name: 'set-value',
-  description:
-    'Update the value of a toggle, select, or input item. Runs the validate callback when present. Fails for text (read-only) and button items.',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      sectionId: { type: 'string', description: 'Section ID.' },
-      itemId: { type: 'string', description: 'Item ID.' },
-      value: {
-        description:
-          'New value. Boolean for toggle items, string for select/input items.',
-      },
-    },
-    required: ['sectionId', 'itemId', 'value'],
-  },
-};
-
-const pressButtonTool: AgentTool = {
-  name: 'press-button',
-  description: "Trigger a button item's action. Fails if the item is not a button or is disabled.",
-  inputSchema: {
-    type: 'object',
-    properties: {
-      sectionId: { type: 'string', description: 'Section ID.' },
-      itemId: { type: 'string', description: 'Item ID.' },
-    },
-    required: ['sectionId', 'itemId'],
-  },
-};
-
 const resolveItem = (
   sections: ControlsSection[],
   sectionId: string,
@@ -92,8 +33,8 @@ const resolveItem = (
 
 export const useControlsAgentTools = (sections: ControlsSection[]) => {
   useRozenitePluginAgentTool({
-    pluginId,
-    tool: listSectionsTool,
+    pluginId: CONTROLS_AGENT_PLUGIN_ID,
+    tool: controlsToolDefinitions.listSections,
     handler: () => ({
       sections: sections.map((section) => ({
         id: section.id,
@@ -109,9 +50,9 @@ export const useControlsAgentTools = (sections: ControlsSection[]) => {
     }),
   });
 
-  useRozenitePluginAgentTool<SectionItemInput>({
-    pluginId,
-    tool: getItemTool,
+  useRozenitePluginAgentTool({
+    pluginId: CONTROLS_AGENT_PLUGIN_ID,
+    tool: controlsToolDefinitions.getItem,
     handler: ({ sectionId, itemId }) => {
       const { item } = resolveItem(sections, sectionId, itemId);
 
@@ -187,9 +128,9 @@ export const useControlsAgentTools = (sections: ControlsSection[]) => {
     },
   });
 
-  useRozenitePluginAgentTool<SetValueInput>({
-    pluginId,
-    tool: setValueTool,
+  useRozenitePluginAgentTool({
+    pluginId: CONTROLS_AGENT_PLUGIN_ID,
+    tool: controlsToolDefinitions.setValue,
     handler: async ({ sectionId, itemId, value }) => {
       const { item } = resolveItem(sections, sectionId, itemId);
 
@@ -224,7 +165,7 @@ export const useControlsAgentTools = (sections: ControlsSection[]) => {
         }
 
         await item.onUpdate(value);
-        return { applied: true, sectionId, itemId };
+        return { applied: true as const, sectionId, itemId };
       }
 
       if (typeof value !== 'string') {
@@ -250,13 +191,13 @@ export const useControlsAgentTools = (sections: ControlsSection[]) => {
       }
 
       await item.onUpdate(value);
-      return { applied: true, sectionId, itemId };
+      return { applied: true as const, sectionId, itemId };
     },
   });
 
-  useRozenitePluginAgentTool<SectionItemInput>({
-    pluginId,
-    tool: pressButtonTool,
+  useRozenitePluginAgentTool({
+    pluginId: CONTROLS_AGENT_PLUGIN_ID,
+    tool: controlsToolDefinitions.pressButton,
     handler: async ({ sectionId, itemId }) => {
       const { item } = resolveItem(sections, sectionId, itemId);
 
@@ -271,7 +212,7 @@ export const useControlsAgentTools = (sections: ControlsSection[]) => {
       }
 
       await item.onPress();
-      return { pressed: true, sectionId, itemId };
+      return { pressed: true as const, sectionId, itemId };
     },
   });
 };

package/src/shared/agent-tools.ts

@@ -0,0 +1,121 @@
+import {
+  defineAgentToolContract,
+  type AgentToolContract,
+} from '@rozenite/agent-shared';
+import type {
+  ControlsItem,
+  ControlsItemSnapshot,
+} from './types';
+
+export const CONTROLS_AGENT_PLUGIN_ID = '@rozenite/controls-plugin';
+
+export type ControlsSectionItemArgs = {
+  sectionId: string;
+  itemId: string;
+};
+
+export type ControlsListSectionsArgs = undefined;
+
+export type ControlsListSectionItemSummary = {
+  id: string;
+  type: ControlsItem['type'];
+  title: string;
+  disabled?: boolean;
+};
+
+export type ControlsListSectionSummary = {
+  id: string;
+  title: string;
+  description?: string;
+  items: ControlsListSectionItemSummary[];
+};
+
+export type ControlsListSectionsResult = {
+  sections: ControlsListSectionSummary[];
+};
+
+export type ControlsGetItemArgs = ControlsSectionItemArgs;
+
+export type ControlsGetItemResult = {
+  sectionId: string;
+  item: ControlsItemSnapshot;
+};
+
+export type ControlsSetValueArgs = ControlsSectionItemArgs & {
+  value: boolean | string;
+};
+
+export type ControlsSetValueResult = {
+  applied: true;
+  sectionId: string;
+  itemId: string;
+};
+
+export type ControlsPressButtonArgs = ControlsSectionItemArgs;
+
+export type ControlsPressButtonResult = {
+  pressed: true;
+  sectionId: string;
+  itemId: string;
+};
+
+export const controlsToolDefinitions = {
+  listSections: defineAgentToolContract<
+    ControlsListSectionsArgs,
+    ControlsListSectionsResult
+  >({
+    name: 'list-sections',
+    description:
+      'List all controls sections with their item IDs, types, and titles. Does not include values — call get-item for that.',
+    inputSchema: { type: 'object', properties: {} },
+  }),
+  getItem: defineAgentToolContract<ControlsGetItemArgs, ControlsGetItemResult>({
+    name: 'get-item',
+    description:
+      'Get full details of a single controls item including its current value. For select items this includes available options.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sectionId: { type: 'string', description: 'Section ID.' },
+        itemId: { type: 'string', description: 'Item ID.' },
+      },
+      required: ['sectionId', 'itemId'],
+    },
+  }),
+  setValue: defineAgentToolContract<
+    ControlsSetValueArgs,
+    ControlsSetValueResult
+  >({
+    name: 'set-value',
+    description:
+      'Update the value of a toggle, select, or input item. Runs the validate callback when present. Fails for text (read-only) and button items.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sectionId: { type: 'string', description: 'Section ID.' },
+        itemId: { type: 'string', description: 'Item ID.' },
+        value: {
+          description:
+            'New value. Boolean for toggle items, string for select/input items.',
+        },
+      },
+      required: ['sectionId', 'itemId', 'value'],
+    },
+  }),
+  pressButton: defineAgentToolContract<
+    ControlsPressButtonArgs,
+    ControlsPressButtonResult
+  >({
+    name: 'press-button',
+    description:
+      "Trigger a button item's action. Fails if the item is not a button or is disabled.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sectionId: { type: 'string', description: 'Section ID.' },
+        itemId: { type: 'string', description: 'Item ID.' },
+      },
+      required: ['sectionId', 'itemId'],
+    },
+  }),
+} as const satisfies Record<string, AgentToolContract<unknown, unknown>>;

package/tsconfig.json

@@ -13,6 +13,7 @@
     "moduleResolution": "bundler",
     "baseUrl": ".",
     "paths": {
+      "@rozenite/agent-shared": ["../agent-shared/src/index.ts"],
       "@rozenite/plugin-bridge": ["../plugin-bridge/src/index.ts"]
     },
     "resolveJsonModule": true,
@@ -20,7 +21,7 @@
     "noEmit": true,
     "jsx": "react-jsx"
   },
-  "include": ["src/**/*", "react-native.ts", "rozenite.config.ts"],
+  "include": ["src/**/*", "react-native.ts", "sdk.ts", "rozenite.config.ts"],
   "exclude": ["node_modules", "dist", "build"],
   "references": [
     {

package/vite.config.ts

@@ -18,6 +18,7 @@ export default defineConfig({
     open: true,
   },
   test: {
+    passWithNoTests: true,
     environment: 'node',
   },
 });