@rozenite/controls-plugin 2.2.0 → 2.3.0

package/dist/react-native/src/shared/types.d.ts

@@ -0,0 +1,69 @@
+export type ControlsTextItem = {
+    id: string;
+    type: 'text';
+    title: string;
+    value: string;
+    description?: string;
+};
+export type ControlsValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    message: string;
+};
+export type ControlsMutableItemBase<TValue> = {
+    id: string;
+    title: string;
+    value: TValue;
+    description?: string;
+    disabled?: boolean;
+    validate?: (nextValue: TValue) => ControlsValidationResult;
+    onUpdate: (nextValue: TValue) => void | Promise<void>;
+};
+export type ControlsToggleItem = ControlsMutableItemBase<boolean> & {
+    type: 'toggle';
+};
+export type ControlsButtonItem = {
+    id: string;
+    type: 'button';
+    title: string;
+    actionLabel?: string;
+    description?: string;
+    disabled?: boolean;
+    onPress: () => void | Promise<void>;
+};
+export type ControlsSelectOption = {
+    label: string;
+    value: string;
+};
+export type ControlsSelectItem = ControlsMutableItemBase<string> & {
+    type: 'select';
+    options: ControlsSelectOption[];
+};
+export type ControlsInputItem = ControlsMutableItemBase<string> & {
+    type: 'input';
+    placeholder?: string;
+    applyLabel?: string;
+};
+export type ControlsItem = ControlsTextItem | ControlsToggleItem | ControlsButtonItem | ControlsSelectItem | ControlsInputItem;
+export type ControlsSection = {
+    id: string;
+    title: string;
+    description?: string;
+    items: ControlsItem[];
+};
+export type ControlsTextItemSnapshot = Omit<ControlsTextItem, never>;
+export type ControlsToggleItemSnapshot = Omit<ControlsToggleItem, 'validate' | 'onUpdate'>;
+export type ControlsButtonItemSnapshot = Omit<ControlsButtonItem, 'onPress'>;
+export type ControlsSelectItemSnapshot = Omit<ControlsSelectItem, 'validate' | 'onUpdate'>;
+export type ControlsInputItemSnapshot = Omit<ControlsInputItem, 'validate' | 'onUpdate'>;
+export type ControlsItemSnapshot = ControlsTextItemSnapshot | ControlsToggleItemSnapshot | ControlsButtonItemSnapshot | ControlsSelectItemSnapshot | ControlsInputItemSnapshot;
+export type ControlsSectionSnapshot = Omit<ControlsSection, 'items'> & {
+    items: ControlsItemSnapshot[];
+};
+export type RozeniteControlsPluginOptions = {
+    sections: ControlsSection[];
+};
+export type RozeniteControlsPluginOptionsUpdater = (previousOptions: RozeniteControlsPluginOptions) => RozeniteControlsPluginOptions;
+export type RozeniteControlsPluginOptionsInput = RozeniteControlsPluginOptions | RozeniteControlsPluginOptionsUpdater;
+export declare const createSection: <TSection extends ControlsSection>(section: TSection) => TSection;

package/dist/react-native/src/shared/types.js

@@ -0,0 +1 @@
+export const createSection = (section) => section;

package/dist/rozenite.json

@@ -1 +1 @@
-{"name":"@rozenite/controls-plugin","version":"2.2.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":"2.3.0","description":"A Rozenite plugin for exposing app-defined controls directly in React Native DevTools.","panels":[{"name":"Controls","source":"/devtools/panel.html"}],"integrations":["react-native","react-native-web","lynx","lynx-web"]}

package/dist/sdk/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/sdk/sdk.d.ts

@@ -0,0 +1,10 @@
+import { CONTROLS_AGENT_PLUGIN_ID, controlsToolDefinitions } from './src/shared/agent-tools.js';
+export { CONTROLS_AGENT_PLUGIN_ID, controlsToolDefinitions };
+export declare const controlsTools: {
+    readonly listSections: import("@rozenite/agent-shared").AgentToolDescriptor<undefined, import("./src/shared/agent-tools.js").ControlsListSectionsResult>;
+    readonly getItem: import("@rozenite/agent-shared").AgentToolDescriptor<import("./src/shared/agent-tools.js").ControlsSectionItemArgs, import("./src/shared/agent-tools.js").ControlsGetItemResult>;
+    readonly setValue: import("@rozenite/agent-shared").AgentToolDescriptor<import("./src/shared/agent-tools.js").ControlsSetValueArgs, import("./src/shared/agent-tools.js").ControlsSetValueResult>;
+    readonly pressButton: import("@rozenite/agent-shared").AgentToolDescriptor<import("./src/shared/agent-tools.js").ControlsSectionItemArgs, import("./src/shared/agent-tools.js").ControlsPressButtonResult>;
+};
+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/dist/sdk/sdk.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.controlsTools = exports.controlsToolDefinitions = exports.CONTROLS_AGENT_PLUGIN_ID = void 0;
+const agent_shared_1 = require("@rozenite/agent-shared");
+const agent_tools_js_1 = require("./src/shared/agent-tools.js");
+Object.defineProperty(exports, "CONTROLS_AGENT_PLUGIN_ID", { enumerable: true, get: function () { return agent_tools_js_1.CONTROLS_AGENT_PLUGIN_ID; } });
+Object.defineProperty(exports, "controlsToolDefinitions", { enumerable: true, get: function () { return agent_tools_js_1.controlsToolDefinitions; } });
+exports.controlsTools = (0, agent_shared_1.defineAgentToolDescriptors)(agent_tools_js_1.CONTROLS_AGENT_PLUGIN_ID, agent_tools_js_1.controlsToolDefinitions);

package/dist/sdk/src/shared/agent-tools.d.ts

@@ -0,0 +1,48 @@
+import { type AgentToolContract } from '@rozenite/agent-shared';
+import type { ControlsItem, ControlsItemSnapshot } from './types';
+export declare 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 declare const controlsToolDefinitions: {
+    readonly listSections: AgentToolContract<undefined, ControlsListSectionsResult>;
+    readonly getItem: AgentToolContract<ControlsSectionItemArgs, ControlsGetItemResult>;
+    readonly setValue: AgentToolContract<ControlsSetValueArgs, ControlsSetValueResult>;
+    readonly pressButton: AgentToolContract<ControlsSectionItemArgs, ControlsPressButtonResult>;
+};

package/dist/sdk/src/shared/agent-tools.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.controlsToolDefinitions = exports.CONTROLS_AGENT_PLUGIN_ID = void 0;
+const agent_shared_1 = require("@rozenite/agent-shared");
+exports.CONTROLS_AGENT_PLUGIN_ID = '@rozenite/controls-plugin';
+exports.controlsToolDefinitions = {
+    listSections: (0, agent_shared_1.defineAgentToolContract)({
+        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: (0, agent_shared_1.defineAgentToolContract)({
+        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: (0, agent_shared_1.defineAgentToolContract)({
+        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: (0, agent_shared_1.defineAgentToolContract)({
+        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'],
+        },
+    }),
+};

package/dist/sdk/src/shared/messaging.d.ts

@@ -0,0 +1,35 @@
+import type { ControlsSectionSnapshot } from './types';
+export type ControlsSnapshotEvent = {
+    type: 'snapshot';
+    sections: ControlsSectionSnapshot[];
+};
+export type ControlsGetSnapshotEvent = {
+    type: 'get-snapshot';
+};
+export type ControlsUpdateRequestEvent = {
+    type: 'update-request';
+    requestId: string;
+    sectionId: string;
+    itemId: string;
+    value: boolean | string;
+};
+export type ControlsUpdateResultEvent = {
+    type: 'update-result';
+    requestId: string;
+    sectionId: string;
+    itemId: string;
+    status: 'ok' | 'error';
+    message?: string;
+};
+export type ControlsInvokeActionEvent = {
+    type: 'invoke-action';
+    sectionId: string;
+    itemId: string;
+    action: 'press';
+};
+export type ControlsEvent = ControlsSnapshotEvent | ControlsGetSnapshotEvent | ControlsUpdateRequestEvent | ControlsUpdateResultEvent | ControlsInvokeActionEvent;
+export type ControlsEventMap = {
+    [K in ControlsEvent['type']]: Extract<ControlsEvent, {
+        type: K;
+    }>;
+};

package/dist/sdk/src/shared/messaging.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/sdk/src/shared/types.d.ts

@@ -0,0 +1,69 @@
+export type ControlsTextItem = {
+    id: string;
+    type: 'text';
+    title: string;
+    value: string;
+    description?: string;
+};
+export type ControlsValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    message: string;
+};
+export type ControlsMutableItemBase<TValue> = {
+    id: string;
+    title: string;
+    value: TValue;
+    description?: string;
+    disabled?: boolean;
+    validate?: (nextValue: TValue) => ControlsValidationResult;
+    onUpdate: (nextValue: TValue) => void | Promise<void>;
+};
+export type ControlsToggleItem = ControlsMutableItemBase<boolean> & {
+    type: 'toggle';
+};
+export type ControlsButtonItem = {
+    id: string;
+    type: 'button';
+    title: string;
+    actionLabel?: string;
+    description?: string;
+    disabled?: boolean;
+    onPress: () => void | Promise<void>;
+};
+export type ControlsSelectOption = {
+    label: string;
+    value: string;
+};
+export type ControlsSelectItem = ControlsMutableItemBase<string> & {
+    type: 'select';
+    options: ControlsSelectOption[];
+};
+export type ControlsInputItem = ControlsMutableItemBase<string> & {
+    type: 'input';
+    placeholder?: string;
+    applyLabel?: string;
+};
+export type ControlsItem = ControlsTextItem | ControlsToggleItem | ControlsButtonItem | ControlsSelectItem | ControlsInputItem;
+export type ControlsSection = {
+    id: string;
+    title: string;
+    description?: string;
+    items: ControlsItem[];
+};
+export type ControlsTextItemSnapshot = Omit<ControlsTextItem, never>;
+export type ControlsToggleItemSnapshot = Omit<ControlsToggleItem, 'validate' | 'onUpdate'>;
+export type ControlsButtonItemSnapshot = Omit<ControlsButtonItem, 'onPress'>;
+export type ControlsSelectItemSnapshot = Omit<ControlsSelectItem, 'validate' | 'onUpdate'>;
+export type ControlsInputItemSnapshot = Omit<ControlsInputItem, 'validate' | 'onUpdate'>;
+export type ControlsItemSnapshot = ControlsTextItemSnapshot | ControlsToggleItemSnapshot | ControlsButtonItemSnapshot | ControlsSelectItemSnapshot | ControlsInputItemSnapshot;
+export type ControlsSectionSnapshot = Omit<ControlsSection, 'items'> & {
+    items: ControlsItemSnapshot[];
+};
+export type RozeniteControlsPluginOptions = {
+    sections: ControlsSection[];
+};
+export type RozeniteControlsPluginOptionsUpdater = (previousOptions: RozeniteControlsPluginOptions) => RozeniteControlsPluginOptions;
+export type RozeniteControlsPluginOptionsInput = RozeniteControlsPluginOptions | RozeniteControlsPluginOptionsUpdater;
+export declare const createSection: <TSection extends ControlsSection>(section: TSection) => TSection;

package/dist/sdk/src/shared/types.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSection = void 0;
+const createSection = (section) => section;
+exports.createSection = createSection;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rozenite/controls-plugin",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A Rozenite plugin for exposing app-defined controls directly in React Native DevTools.",
   "homepage": "https://github.com/callstackincubator/rozenite#readme",
   "bugs": {
@@ -12,31 +12,30 @@
     "url": "https://github.com/callstackincubator/rozenite.git"
   },
   "type": "module",
-  "main": "./dist/react-native/index.cjs",
-  "module": "./dist/react-native/index.js",
-  "types": "./dist/react-native/index.d.ts",
+  "main": "./dist/react-native/cjs/react-native.js",
+  "module": "./dist/react-native/react-native.js",
+  "types": "./dist/react-native/react-native.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/react-native/index.d.ts",
-      "import": "./dist/react-native/index.js",
-      "require": "./dist/react-native/index.cjs"
+      "types": "./dist/react-native/react-native.d.ts",
+      "import": "./dist/react-native/react-native.js",
+      "require": "./dist/react-native/cjs/react-native.js"
     },
     "./package.json": "./package.json",
     "./sdk": {
       "development": "./sdk.ts",
-      "types": "./dist/sdk/index.d.ts",
-      "import": "./dist/sdk/index.js",
-      "require": "./dist/sdk/index.cjs"
+      "types": "./dist/sdk/sdk.d.ts",
+      "default": "./dist/sdk/sdk.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@rozenite/agent-shared": "2.2.0",
-    "@rozenite/plugin-bridge": "2.2.0",
-    "@rozenite/ui": "2.2.0",
-    "@rozenite/agent-bridge": "2.2.0"
+    "@rozenite/agent-bridge": "2.3.0",
+    "@rozenite/agent-shared": "2.3.0",
+    "@rozenite/plugin-bridge": "2.3.0",
+    "@rozenite/ui": "2.3.0"
   },
   "devDependencies": {
     "@types/react": "~19.2.3",
@@ -47,12 +46,12 @@
     "react-native-web": "^0.21.2",
     "typescript": "~5.9.3",
     "vite": "^7.3.1",
-    "@rozenite/vite-plugin": "2.2.0",
-    "rozenite": "2.2.0"
+    "@rozenite/test-utils": "2.3.0",
+    "@rozenite/vite-plugin": "2.3.0",
+    "rozenite": "2.3.0"
   },
   "peerDependencies": {
-    "react": "*",
-    "react-native": "*"
+    "react": "*"
   },
   "scripts": {
     "build": "rozenite build",

package/react-native.ts

@@ -16,8 +16,15 @@ export {
 
 export let useRozeniteControlsPlugin: typeof import('./src/react-native/useRozeniteControlsPlugin').useRozeniteControlsPlugin;
 
+// Neither Lynx runtime has a `window`, so `typeof window` alone reported
+// every Lynx app as a server and installed the no-op stub below. `lynx` is
+// a free binding in module scope, not a property of `globalThis`. Kept
+// inline rather than imported so this stays a foldable expression and the
+// `require`s below can still be dropped from production bundles.
+declare const lynx: unknown;
+
 const isDev = process.env.NODE_ENV !== 'production';
-const isServer = typeof window === 'undefined';
+const isServer = typeof window === 'undefined' && typeof lynx === 'undefined';
 
 if (isDev && !isServer) {
   useRozeniteControlsPlugin =

package/rozenite.config.ts

@@ -1,4 +1,5 @@
 export default {
+  integrations: ['react-native', 'react-native-web', 'lynx', 'lynx-web'],
   panels: [
     {
       name: 'Controls',

package/src/__tests__/release-bundle.test.ts

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { bundleForRelease, RELEASE_BUNDLE_TIMEOUT } from '@rozenite/test-utils';
+import { describe, expect, it } from 'vitest';
+
+// An app importing this plugin ships its React Native code -- that much is
+// the app's own choice. What must never follow it into the bundle is the
+// panel: the DevTools UI, its React DOM tree and `@rozenite/ui`.
+// See docs/agents/release-bundle-testing.md.
+const packageRoot = path.resolve(fileURLToPath(import.meta.url), '../../..');
+const reactNativeEntry = path.join(packageRoot, 'dist/react-native/cjs/react-native.js');
+
+describe('@rozenite/controls-plugin in a release bundle', () => {
+  it(
+    'ships no panel code when an app imports it',
+    async () => {
+      const result = await bundleForRelease({
+        resolveFrom: packageRoot,
+        files: {
+          'index.js': `require(${JSON.stringify(reactNativeEntry)});\n`,
+        },
+      });
+
+      // Keeps the check below honest: the entry really did get bundled.
+      expect(result.rozeniteModules).toContain(
+        'packages/controls-plugin/dist/react-native/cjs/react-native.js',
+      );
+      expect(result.panelModules).toEqual([]);
+    },
+    RELEASE_BUNDLE_TIMEOUT,
+  );
+});