@rozenite/controls-plugin 2.2.0 → 2.3.0

package/dist/react-native/src/react-native/controlsRegistry.js

@@ -0,0 +1,66 @@
+const EMPTY_OPTIONS = {
+    sections: [],
+};
+const resolveOptionsInput = (previousOptions, input) => {
+    if (typeof input === 'function') {
+        return input(previousOptions);
+    }
+    return {
+        ...previousOptions,
+        ...input,
+        sections: [...previousOptions.sections, ...input.sections],
+    };
+};
+export const createControlsRegistry = () => {
+    const registrations = new Map();
+    const listeners = new Set();
+    let snapshot = 0;
+    const getOwnerId = () => registrations.keys().next().value;
+    const notify = () => {
+        snapshot += 1;
+        listeners.forEach((listener) => listener());
+    };
+    const getRegistrationEntries = (override) => {
+        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]];
+        }
+        return entries.map(([id, input]) => id === override.id ? [id, override.input] : [id, input]);
+    };
+    return {
+        set(id, input) {
+            const previousOwnerId = getOwnerId();
+            registrations.set(id, input);
+            if (previousOwnerId !== getOwnerId()) {
+                notify();
+            }
+        },
+        delete(id) {
+            registrations.delete(id);
+            notify();
+        },
+        getOptions(override) {
+            return getRegistrationEntries(override)
+                .map(([, input]) => input)
+                .reduce(resolveOptionsInput, EMPTY_OPTIONS);
+        },
+        isOwner(id, override) {
+            const ownerEntry = getRegistrationEntries(override)[0];
+            return ownerEntry?.[0] === id;
+        },
+        getSnapshot() {
+            return snapshot;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+};
+export const controlsRegistry = createControlsRegistry();

package/dist/react-native/src/react-native/useControlsAgentTools.d.ts

@@ -0,0 +1,2 @@
+import type { ControlsSection } from '../shared/types';
+export declare const useControlsAgentTools: (getSections: () => ControlsSection[], enabled?: boolean) => void;

package/dist/react-native/src/react-native/useControlsAgentTools.js

@@ -0,0 +1,171 @@
+import { useRozenitePluginAgentTool } from '@rozenite/agent-bridge';
+import { CONTROLS_AGENT_PLUGIN_ID, controlsToolDefinitions } from '../shared/agent-tools';
+const resolveItem = (sections, sectionId, itemId) => {
+    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)'}`);
+    }
+    const item = section.items.find((i) => i.id === itemId);
+    if (!item) {
+        const available = section.items.map((i) => i.id).join(', ');
+        throw new Error(`Item "${itemId}" not found in section "${sectionId}". Available: ${available || '(none)'}`);
+    }
+    return { section, item };
+};
+export const useControlsAgentTools = (getSections, enabled = true) => {
+    useRozenitePluginAgentTool({
+        pluginId: CONTROLS_AGENT_PLUGIN_ID,
+        tool: controlsToolDefinitions.listSections,
+        enabled,
+        handler: () => ({
+            sections: getSections().map((section) => ({
+                id: section.id,
+                title: section.title,
+                description: section.description,
+                items: section.items.map((item) => ({
+                    id: item.id,
+                    type: item.type,
+                    title: item.title,
+                    disabled: 'disabled' in item ? item.disabled : undefined,
+                })),
+            })),
+        }),
+    });
+    useRozenitePluginAgentTool({
+        pluginId: CONTROLS_AGENT_PLUGIN_ID,
+        tool: controlsToolDefinitions.getItem,
+        enabled,
+        handler: ({ sectionId, itemId }) => {
+            const { item } = resolveItem(getSections(), sectionId, itemId);
+            if (item.type === 'text') {
+                return {
+                    sectionId,
+                    item: {
+                        id: item.id,
+                        type: item.type,
+                        title: item.title,
+                        value: item.value,
+                        description: item.description,
+                    },
+                };
+            }
+            if (item.type === 'toggle') {
+                return {
+                    sectionId,
+                    item: {
+                        id: item.id,
+                        type: item.type,
+                        title: item.title,
+                        value: item.value,
+                        description: item.description,
+                        disabled: item.disabled,
+                    },
+                };
+            }
+            if (item.type === 'button') {
+                return {
+                    sectionId,
+                    item: {
+                        id: item.id,
+                        type: item.type,
+                        title: item.title,
+                        actionLabel: item.actionLabel,
+                        description: item.description,
+                        disabled: item.disabled,
+                    },
+                };
+            }
+            if (item.type === 'select') {
+                return {
+                    sectionId,
+                    item: {
+                        id: item.id,
+                        type: item.type,
+                        title: item.title,
+                        value: item.value,
+                        options: item.options,
+                        description: item.description,
+                        disabled: item.disabled,
+                    },
+                };
+            }
+            return {
+                sectionId,
+                item: {
+                    id: item.id,
+                    type: item.type,
+                    title: item.title,
+                    value: item.value,
+                    placeholder: item.placeholder,
+                    applyLabel: item.applyLabel,
+                    description: item.description,
+                    disabled: item.disabled,
+                },
+            };
+        },
+    });
+    useRozenitePluginAgentTool({
+        pluginId: CONTROLS_AGENT_PLUGIN_ID,
+        tool: controlsToolDefinitions.setValue,
+        enabled,
+        handler: async ({ sectionId, itemId, value }) => {
+            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.`);
+            }
+            if (item.type === 'button') {
+                throw new Error(`Item "${itemId}" is a button. Use press-button to trigger its action.`);
+            }
+            if (item.disabled) {
+                throw new Error(`Item "${itemId}" is disabled.`);
+            }
+            if (item.type === 'toggle') {
+                if (typeof value !== 'boolean') {
+                    throw new Error(`Expected boolean value for toggle item "${itemId}".`);
+                }
+                if (item.validate) {
+                    const result = item.validate(value);
+                    if (!result.valid) {
+                        throw new Error(result.message);
+                    }
+                }
+                await item.onUpdate(value);
+                return { applied: true, sectionId, itemId };
+            }
+            if (typeof value !== 'string') {
+                throw new Error(`Expected string value for ${item.type} item "${itemId}".`);
+            }
+            if (item.type === 'select') {
+                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(', ')}`);
+                }
+            }
+            if (item.validate) {
+                const result = item.validate(value);
+                if (!result.valid) {
+                    throw new Error(result.message);
+                }
+            }
+            await item.onUpdate(value);
+            return { applied: true, sectionId, itemId };
+        },
+    });
+    useRozenitePluginAgentTool({
+        pluginId: CONTROLS_AGENT_PLUGIN_ID,
+        tool: controlsToolDefinitions.pressButton,
+        enabled,
+        handler: async ({ 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.`);
+            }
+            if (item.disabled) {
+                throw new Error(`Button "${itemId}" is disabled.`);
+            }
+            await item.onPress();
+            return { pressed: true, sectionId, itemId };
+        },
+    });
+};

package/dist/react-native/src/react-native/useRozeniteControlsPlugin.d.ts

@@ -0,0 +1,3 @@
+import type { ControlsEventMap } from '../shared/messaging';
+import type { RozeniteControlsPluginOptionsInput } from '../shared/types';
+export declare const useRozeniteControlsPlugin: (optionsInput: RozeniteControlsPluginOptionsInput) => import("@rozenite/plugin-bridge").RozeniteDevToolsRequestClient<ControlsEventMap> | null;

package/dist/react-native/src/react-native/useRozeniteControlsPlugin.js

@@ -0,0 +1,173 @@
+import { useRozeniteDevToolsClient } from '@rozenite/plugin-bridge';
+import { useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { buildActionRegistry, getActionRegistryKey, serializeSections, validateValue, } from '../shared/serialization';
+import { useControlsAgentTools } from './useControlsAgentTools';
+import { controlsRegistry } from './controlsRegistry';
+export const useRozeniteControlsPlugin = (optionsInput) => {
+    const client = useRozeniteDevToolsClient({
+        pluginId: '@rozenite/controls-plugin',
+    });
+    const registrationIdRef = useRef(Symbol('rozenite-controls'));
+    const registrationId = registrationIdRef.current;
+    const registrySnapshot = useSyncExternalStore(controlsRegistry.subscribe, controlsRegistry.getSnapshot, controlsRegistry.getSnapshot);
+    useEffect(() => {
+        return () => {
+            controlsRegistry.delete(registrationId);
+        };
+    }, [registrationId]);
+    useEffect(() => {
+        controlsRegistry.set(registrationId, optionsInput);
+    }, [optionsInput, registrationId]);
+    const isRegistryOwner = useMemo(() => controlsRegistry.isOwner(registrationId, {
+        id: registrationId,
+        input: optionsInput,
+    }), [optionsInput, registrySnapshot, registrationId]);
+    useControlsAgentTools(() => controlsRegistry.getOptions().sections, isRegistryOwner);
+    useEffect(() => {
+        if (!client) {
+            return;
+        }
+        client.send('snapshot', {
+            type: 'snapshot',
+            sections: serializeSections(controlsRegistry.getOptions().sections),
+        });
+    }, [client, optionsInput, registrySnapshot]);
+    useEffect(() => {
+        if (!client || !isRegistryOwner) {
+            return;
+        }
+        const handleUpdateRequest = async ({ requestId, sectionId, itemId, value, }) => {
+            const key = getActionRegistryKey(sectionId, itemId);
+            const entry = buildActionRegistry(controlsRegistry.getOptions().sections).get(key);
+            if (!entry || entry.type === 'button') {
+                client.send('update-result', {
+                    type: 'update-result',
+                    requestId,
+                    sectionId,
+                    itemId,
+                    status: 'error',
+                    message: 'Update target not found.',
+                });
+                return;
+            }
+            try {
+                if (entry.type === 'toggle') {
+                    if (typeof value !== 'boolean') {
+                        client.send('update-result', {
+                            type: 'update-result',
+                            requestId,
+                            sectionId,
+                            itemId,
+                            status: 'error',
+                            message: 'Invalid toggle value.',
+                        });
+                        return;
+                    }
+                    const result = validateValue(entry.validate, value);
+                    if (!result.valid) {
+                        client.send('update-result', {
+                            type: 'update-result',
+                            requestId,
+                            sectionId,
+                            itemId,
+                            status: 'error',
+                            message: result.message,
+                        });
+                        return;
+                    }
+                    await entry.onUpdate(value);
+                    client.send('update-result', {
+                        type: 'update-result',
+                        requestId,
+                        sectionId,
+                        itemId,
+                        status: 'ok',
+                    });
+                    return;
+                }
+                if (typeof value !== 'string') {
+                    client.send('update-result', {
+                        type: 'update-result',
+                        requestId,
+                        sectionId,
+                        itemId,
+                        status: 'error',
+                        message: `Invalid ${entry.type} value.`,
+                    });
+                    return;
+                }
+                const result = validateValue(entry.validate, value);
+                if (!result.valid) {
+                    client.send('update-result', {
+                        type: 'update-result',
+                        requestId,
+                        sectionId,
+                        itemId,
+                        status: 'error',
+                        message: result.message,
+                    });
+                    return;
+                }
+                await entry.onUpdate(value);
+                client.send('update-result', {
+                    type: 'update-result',
+                    requestId,
+                    sectionId,
+                    itemId,
+                    status: 'ok',
+                });
+            }
+            catch (error) {
+                console.warn(`[Rozenite] Controls Plugin: Update failed for ${sectionId}/${itemId}.`, error);
+                client.send('update-result', {
+                    type: 'update-result',
+                    requestId,
+                    sectionId,
+                    itemId,
+                    status: 'error',
+                    message: 'Update failed on the device.',
+                });
+            }
+        };
+        const handleInvokeAction = async ({ sectionId, itemId, action }) => {
+            if (action !== 'press') {
+                console.warn(`[Rozenite] Controls Plugin: Unsupported action "${action}" for ${sectionId}/${itemId}.`);
+                return;
+            }
+            const key = getActionRegistryKey(sectionId, itemId);
+            const entry = buildActionRegistry(controlsRegistry.getOptions().sections).get(key);
+            if (!entry) {
+                console.warn(`[Rozenite] Controls Plugin: Action target not found for ${sectionId}/${itemId}.`);
+                return;
+            }
+            try {
+                if (entry.type !== 'button') {
+                    console.warn(`[Rozenite] Controls Plugin: Invalid press action payload for ${sectionId}/${itemId}.`);
+                    return;
+                }
+                await entry.onPress();
+            }
+            catch (error) {
+                console.warn(`[Rozenite] Controls Plugin: Action failed for ${sectionId}/${itemId}.`, error);
+            }
+        };
+        const subscriptions = [
+            client.onMessage('get-snapshot', () => {
+                client.send('snapshot', {
+                    type: 'snapshot',
+                    sections: serializeSections(controlsRegistry.getOptions().sections),
+                });
+            }),
+            client.onMessage('update-request', (event) => {
+                void handleUpdateRequest(event);
+            }),
+            client.onMessage('invoke-action', (event) => {
+                void handleInvokeAction(event);
+            }),
+        ];
+        return () => {
+            subscriptions.forEach((subscription) => subscription.remove());
+        };
+    }, [client, isRegistryOwner]);
+    return client;
+};

package/dist/react-native/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/react-native/src/shared/agent-tools.js

@@ -0,0 +1,48 @@
+import { defineAgentToolContract } from '@rozenite/agent-shared';
+export const CONTROLS_AGENT_PLUGIN_ID = '@rozenite/controls-plugin';
+export const controlsToolDefinitions = {
+    listSections: 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: 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: 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: 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/react-native/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/react-native/src/shared/messaging.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,22 @@
+import type { ControlsButtonItem, ControlsInputItem, ControlsMutableItemBase, ControlsSelectItem, ControlsSection, ControlsSectionSnapshot, ControlsToggleItem, ControlsValidationResult } from './types';
+export type ActionRegistryEntry = {
+    type: 'toggle';
+    validate?: ControlsToggleItem['validate'];
+    onUpdate: ControlsToggleItem['onUpdate'];
+} | {
+    type: 'button';
+    onPress: ControlsButtonItem['onPress'];
+} | {
+    type: 'select';
+    validate?: ControlsSelectItem['validate'];
+    onUpdate: ControlsSelectItem['onUpdate'];
+} | {
+    type: 'input';
+    validate?: ControlsInputItem['validate'];
+    onUpdate: ControlsInputItem['onUpdate'];
+};
+declare const validateValue: <TValue>(validate: ControlsMutableItemBase<TValue>["validate"], value: TValue) => ControlsValidationResult;
+export declare const serializeSections: (sections: ControlsSection[]) => ControlsSectionSnapshot[];
+export declare const buildActionRegistry: (sections: ControlsSection[]) => Map<string, ActionRegistryEntry>;
+export declare const getActionRegistryKey: (sectionId: string, itemId: string) => string;
+export { validateValue };

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

@@ -0,0 +1,96 @@
+const validateValue = (validate, value) => {
+    if (!validate) {
+        return { valid: true };
+    }
+    return validate(value);
+};
+const toSnapshotItem = (item) => {
+    if (item.type === 'text') {
+        return item;
+    }
+    if (item.type === 'toggle') {
+        return {
+            id: item.id,
+            type: item.type,
+            title: item.title,
+            value: item.value,
+            description: item.description,
+            disabled: item.disabled,
+        };
+    }
+    if (item.type === 'button') {
+        return {
+            id: item.id,
+            type: item.type,
+            title: item.title,
+            actionLabel: item.actionLabel,
+            description: item.description,
+            disabled: item.disabled,
+        };
+    }
+    if (item.type === 'select') {
+        return {
+            id: item.id,
+            type: item.type,
+            title: item.title,
+            value: item.value,
+            options: item.options,
+            description: item.description,
+            disabled: item.disabled,
+        };
+    }
+    return {
+        id: item.id,
+        type: item.type,
+        title: item.title,
+        value: item.value,
+        placeholder: item.placeholder,
+        applyLabel: item.applyLabel,
+        description: item.description,
+        disabled: item.disabled,
+    };
+};
+export const serializeSections = (sections) => sections.map((section) => ({
+    id: section.id,
+    title: section.title,
+    description: section.description,
+    items: section.items.map(toSnapshotItem),
+}));
+export const buildActionRegistry = (sections) => {
+    const registry = new Map();
+    sections.forEach((section) => {
+        section.items.forEach((item) => {
+            const key = `${section.id}:${item.id}`;
+            if (item.type === 'toggle') {
+                registry.set(key, {
+                    type: 'toggle',
+                    validate: item.validate,
+                    onUpdate: item.onUpdate,
+                });
+            }
+            if (item.type === 'button') {
+                registry.set(key, {
+                    type: 'button',
+                    onPress: item.onPress,
+                });
+            }
+            if (item.type === 'select') {
+                registry.set(key, {
+                    type: 'select',
+                    validate: item.validate,
+                    onUpdate: item.onUpdate,
+                });
+            }
+            if (item.type === 'input') {
+                registry.set(key, {
+                    type: 'input',
+                    validate: item.validate,
+                    onUpdate: item.onUpdate,
+                });
+            }
+        });
+    });
+    return registry;
+};
+export const getActionRegistryKey = (sectionId, itemId) => `${sectionId}:${itemId}`;
+export { validateValue };