@ouispec/agent-react 0.1.0

package/dist/entity/AgentEntity.js

@@ -0,0 +1,97 @@
+import React, { useRef, useEffect, useCallback, useState } from 'react';
+import { AgentEntityBase, EntityRegistry, } from '@ouispec/agent-core';
+/**
+ * <AgentEntity> — wrapper component that grants agent capabilities to its children.
+ *
+ * Simplest integration pattern. Wrap any component to make it agent-addressable.
+ *
+ * Example:
+ * ```tsx
+ * <AgentEntity type="Character" id={char.id} displayContext={{ label: char.name }}>
+ *   <CharacterCard character={char} />
+ * </AgentEntity>
+ *
+ * // Or with render prop:
+ * <AgentEntity type="Character" id={char.id} displayContext={{ label: char.name }}>
+ *   {({ isTargeted, execute }) => (
+ *     <div className={isTargeted ? 'highlighted' : ''}>
+ *       <CharacterCard character={char} />
+ *       <button onClick={() => execute('generate-clip', { character: char.id })}>
+ *         Generate
+ *       </button>
+ *     </div>
+ *   )}
+ * </AgentEntity>
+ * ```
+ */
+export function AgentEntity(props) {
+    const { type, id, intents = [], displayContext, capabilities = {}, onTargeted, onReleased, onExecuting, onExecutionComplete, onCommandReceived, onObserve, children, as: Tag = 'div', className, style, } = props;
+    const [, forceUpdate] = useState(0);
+    const rerender = useCallback(() => forceUpdate(n => n + 1), []);
+    const elementRef = useRef(null);
+    const bridgeRef = useRef(null);
+    if (!bridgeRef.current) {
+        bridgeRef.current = new WrapperEntityBridge();
+    }
+    const bridge = bridgeRef.current;
+    bridge._sync(type, id, intents, displayContext, capabilities);
+    bridge._setCallbacks({ onTargeted, onReleased, onExecuting, onExecutionComplete, onCommandReceived, onObserve });
+    bridge._setRerender(rerender);
+    useEffect(() => {
+        bridge.register();
+        return () => bridge.unregister();
+    }, []);
+    useEffect(() => {
+        if (bridge._prevKey !== `${type}::${id}`) {
+            bridge.unregister();
+            bridge._sync(type, id, intents, displayContext, capabilities);
+            bridge.register();
+            bridge._prevKey = `${type}::${id}`;
+        }
+    }, [type, id]);
+    const refCallback = useCallback((el) => {
+        elementRef.current = el;
+        EntityRegistry.instance.updateElement(type, id, el);
+    }, [type, id]);
+    const childContext = {
+        isTargeted: bridge.isTargeted,
+        isExecuting: bridge.isExecuting,
+        currentAction: bridge.currentAction,
+        execute: (intentId, params, options) => bridge.execute(intentId, params, options),
+        emit: (signal, data) => bridge.emit(signal, data),
+    };
+    const content = typeof children === 'function' ? children(childContext) : children;
+    return React.createElement(Tag, { ref: refCallback, className, style, 'data-agent-entity': `${type}::${id}` }, content);
+}
+class WrapperEntityBridge extends AgentEntityBase {
+    _type = '';
+    _id = '';
+    _intents = [];
+    _display = { label: '' };
+    _caps = {};
+    _callbacks = {};
+    _rerender = null;
+    _prevKey = '';
+    get entityType() { return this._type; }
+    get entityId() { return this._id; }
+    get intents() { return this._intents; }
+    get displayContext() { return this._display; }
+    get capabilities() { return this._caps; }
+    _sync(type, id, intents, display, caps) {
+        this._type = type;
+        this._id = id;
+        this._intents = intents;
+        this._display = display;
+        this._caps = caps;
+        this._prevKey = `${type}::${id}`;
+    }
+    _setCallbacks(callbacks) { this._callbacks = callbacks; }
+    _setRerender(fn) { this._rerender = fn; }
+    onTargeted(action) { this._callbacks.onTargeted?.(action); this._rerender?.(); }
+    onReleased() { this._callbacks.onReleased?.(); this._rerender?.(); }
+    onExecuting(intentId, params) { this._callbacks.onExecuting?.(intentId, params); this._rerender?.(); }
+    onExecutionComplete(intentId, result) { this._callbacks.onExecutionComplete?.(intentId, result); this._rerender?.(); }
+    onCommandReceived(command) { return this._callbacks.onCommandReceived?.(command); }
+    onObserve(observation) { this._callbacks.onObserve?.(observation); }
+}
+//# sourceMappingURL=AgentEntity.js.map

package/dist/entity/AgentEntity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentEntity.js","sourceRoot":"","sources":["../../src/entity/AgentEntity.tsx"],"names":[],"mappings":"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"}

package/dist/entity/AgentEntityComponent.d.ts

@@ -0,0 +1,73 @@
+import React from 'react';
+import type { EntityCapabilities, EntityDisplayContext, AgentAction, AgentCommand, AgentCommandResponse, UserObservation, EntityExecuteOptions, Unsubscribe } from '@ouispec/agent-core';
+import type { IntentResult } from '@ouispec/agent-core';
+/**
+ * AgentEntityComponent — class-based React component that extends the core AgentEntityBase.
+ *
+ * This is the primary integration pattern for complex, stateful entity components.
+ * Subclass this and implement the abstract getters for your entity.
+ *
+ * Example:
+ * ```tsx
+ * class CharacterCard extends AgentEntityComponent<{ character: Character }> {
+ *   get entityType() { return 'Character'; }
+ *   get entityId() { return this.props.character.id; }
+ *   get intents() { return ['generate-clip', 'clone-voice']; }
+ *   get displayContext() {
+ *     return { label: this.props.character.name, image: this.props.character.thumbnailUrl };
+ *   }
+ *
+ *   onTargeted(action) {
+ *     this.setState({ highlighted: true });
+ *   }
+ *
+ *   onReleased() {
+ *     this.setState({ highlighted: false });
+ *   }
+ *
+ *   render() {
+ *     return <div ref={this.entityRef}>...</div>;
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class AgentEntityComponent<P = Record<string, never>, S = Record<string, never>> extends React.Component<P, S> {
+    private _entityBridge;
+    private _entityRef;
+    abstract get entityType(): string;
+    abstract get entityId(): string;
+    abstract get intents(): string[];
+    abstract get displayContext(): EntityDisplayContext;
+    get capabilities(): EntityCapabilities;
+    constructor(props: P);
+    /**
+     * Ref to attach to the root DOM element.
+     * The registry uses this for visibility tracking (IntersectionObserver).
+     */
+    get entityRef(): React.RefObject<HTMLElement | null>;
+    get isTargeted(): boolean;
+    get isExecuting(): boolean;
+    /**
+     * Execute an intent through the SDK orchestrator.
+     */
+    execute(intentId: string, params?: Record<string, unknown>, options?: EntityExecuteOptions): Promise<IntentResult>;
+    /**
+     * Emit a signal to the agent (only when capabilities.observe is true).
+     */
+    emit(signal: string, data?: unknown): void;
+    /**
+     * Subscribe to events (only when capabilities.observe is true).
+     */
+    subscribe(event: string, handler: (data: unknown) => void): Unsubscribe;
+    onTargeted?(action: AgentAction): void;
+    onReleased?(): void;
+    onExecuting?(intentId: string, params: Record<string, unknown>): void;
+    onExecutionComplete?(intentId: string, result: IntentResult): void;
+    onCommandReceived?(command: AgentCommand): AgentCommandResponse | Promise<AgentCommandResponse> | void;
+    onObserve?(observation: UserObservation): void;
+    componentDidMount(): void;
+    componentDidUpdate(_prevProps: P): void;
+    componentWillUnmount(): void;
+    private _setupDomObservation;
+}
+//# sourceMappingURL=AgentEntityComponent.d.ts.map

package/dist/entity/AgentEntityComponent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentEntityComponent.d.ts","sourceRoot":"","sources":["../../src/entity/AgentEntityComponent.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAK1B,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,8BAAsB,oBAAoB,CACxC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACzB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CACzB,SAAQ,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7B,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,UAAU,CAAkC;IAEpD,QAAQ,KAAK,UAAU,IAAI,MAAM,CAAC;IAClC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC;IAChC,QAAQ,KAAK,OAAO,IAAI,MAAM,EAAE,CAAC;IACjC,QAAQ,KAAK,cAAc,IAAI,oBAAoB,CAAC;IAEpD,IAAI,YAAY,IAAI,kBAAkB,CAErC;gBAEW,KAAK,EAAE,CAAC;IAKpB;;;OAGG;IACH,IAAI,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAEnD;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;OAEG;IACG,OAAO,CACX,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,YAAY,CAAC;IAIxB;;OAEG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAI1C;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,WAAW;IAKvE,UAAU,CAAC,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IACtC,UAAU,CAAC,IAAI,IAAI;IACnB,WAAW,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IACrE,mBAAmB,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAClE,iBAAiB,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI;IACtG,SAAS,CAAC,CAAC,WAAW,EAAE,eAAe,GAAG,IAAI;IAI9C,iBAAiB,IAAI,IAAI;IAMzB,kBAAkB,CAAC,UAAU,EAAE,CAAC,GAAG,IAAI;IAIvC,oBAAoB,IAAI,IAAI;IAI5B,OAAO,CAAC,oBAAoB;CAM7B"}

package/dist/entity/AgentEntityComponent.js

@@ -0,0 +1,134 @@
+import React from 'react';
+import { AgentEntityBase, EntityRegistry, } from '@ouispec/agent-core';
+/**
+ * AgentEntityComponent — class-based React component that extends the core AgentEntityBase.
+ *
+ * This is the primary integration pattern for complex, stateful entity components.
+ * Subclass this and implement the abstract getters for your entity.
+ *
+ * Example:
+ * ```tsx
+ * class CharacterCard extends AgentEntityComponent<{ character: Character }> {
+ *   get entityType() { return 'Character'; }
+ *   get entityId() { return this.props.character.id; }
+ *   get intents() { return ['generate-clip', 'clone-voice']; }
+ *   get displayContext() {
+ *     return { label: this.props.character.name, image: this.props.character.thumbnailUrl };
+ *   }
+ *
+ *   onTargeted(action) {
+ *     this.setState({ highlighted: true });
+ *   }
+ *
+ *   onReleased() {
+ *     this.setState({ highlighted: false });
+ *   }
+ *
+ *   render() {
+ *     return <div ref={this.entityRef}>...</div>;
+ *   }
+ * }
+ * ```
+ */
+export class AgentEntityComponent extends React.Component {
+    _entityBridge;
+    _entityRef = React.createRef();
+    get capabilities() {
+        return {};
+    }
+    constructor(props) {
+        super(props);
+        this._entityBridge = new EntityBridge(this);
+    }
+    /**
+     * Ref to attach to the root DOM element.
+     * The registry uses this for visibility tracking (IntersectionObserver).
+     */
+    get entityRef() {
+        return this._entityRef;
+    }
+    get isTargeted() {
+        return this._entityBridge.isTargeted;
+    }
+    get isExecuting() {
+        return this._entityBridge.isExecuting;
+    }
+    /**
+     * Execute an intent through the SDK orchestrator.
+     */
+    async execute(intentId, params, options) {
+        return this._entityBridge.execute(intentId, params, options);
+    }
+    /**
+     * Emit a signal to the agent (only when capabilities.observe is true).
+     */
+    emit(signal, data) {
+        this._entityBridge.emit(signal, data);
+    }
+    /**
+     * Subscribe to events (only when capabilities.observe is true).
+     */
+    subscribe(event, handler) {
+        return this._entityBridge.subscribe(event, handler);
+    }
+    // --- React lifecycle ---
+    componentDidMount() {
+        this._entityBridge.syncProperties();
+        this._entityBridge.register();
+        this._setupDomObservation();
+    }
+    componentDidUpdate(_prevProps) {
+        this._entityBridge.syncProperties();
+    }
+    componentWillUnmount() {
+        this._entityBridge.unregister();
+    }
+    _setupDomObservation() {
+        const el = this._entityRef.current;
+        if (el) {
+            EntityRegistry.instance.updateElement(this.entityType, this.entityId, el);
+        }
+    }
+}
+/**
+ * Internal bridge between the React component and AgentEntityBase.
+ * Extends AgentEntityBase and delegates lifecycle hooks to the React component.
+ */
+class EntityBridge extends AgentEntityBase {
+    component;
+    constructor(component) {
+        super();
+        this.component = component;
+    }
+    get entityType() { return this.component.entityType; }
+    get entityId() { return this.component.entityId; }
+    get intents() { return this.component.intents; }
+    get displayContext() { return this.component.displayContext; }
+    get capabilities() { return this.component.capabilities; }
+    syncProperties() {
+        // Properties are read dynamically from the component — no sync needed
+    }
+    onTargeted(action) {
+        this.component.onTargeted?.(action);
+        this.component.forceUpdate();
+    }
+    onReleased() {
+        this.component.onReleased?.();
+        this.component.forceUpdate();
+    }
+    onExecuting(intentId, params) {
+        this.component.onExecuting?.(intentId, params);
+        this.component.forceUpdate();
+    }
+    onExecutionComplete(intentId, result) {
+        this.component.onExecutionComplete?.(intentId, result);
+        this.component.forceUpdate();
+    }
+    onCommandReceived(command) {
+        return this.component.onCommandReceived?.(command);
+    }
+    onObserve(observation) {
+        this.component.onObserve?.(observation);
+    }
+}
+//# sourceMappingURL=AgentEntityComponent.js.map

package/dist/entity/AgentEntityComponent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentEntityComponent.js","sourceRoot":"","sources":["../../src/entity/AgentEntityComponent.tsx"],"names":[],"mappings":"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"}

package/dist/entity/asAgentEntity.d.ts

@@ -0,0 +1,45 @@
+import React from 'react';
+import type { AgentEntityChildContext } from './AgentEntity.js';
+import type { EntityCapabilities, EntityDisplayContext, AgentAction, AgentCommand, AgentCommandResponse, UserObservation } from '@ouispec/agent-core';
+/**
+ * Configuration for the asAgentEntity HOC.
+ */
+export interface AsAgentEntityConfig<P> {
+    entityType: string | ((props: P) => string);
+    entityId: (props: P) => string;
+    intents?: string[] | ((props: P) => string[]);
+    displayContext: (props: P) => EntityDisplayContext;
+    capabilities?: EntityCapabilities;
+    onTargeted?: (props: P, action: AgentAction) => void;
+    onReleased?: (props: P) => void;
+    onCommandReceived?: (props: P, command: AgentCommand) => AgentCommandResponse | Promise<AgentCommandResponse> | void;
+    onObserve?: (props: P, observation: UserObservation) => void;
+}
+/**
+ * Props injected into the wrapped component by asAgentEntity.
+ */
+export interface InjectedAgentEntityProps {
+    agentEntity: AgentEntityChildContext;
+}
+/**
+ * asAgentEntity — Higher-Order Component that wraps an existing component with agent entity capabilities.
+ *
+ * Best for wrapping third-party components or components you can't modify.
+ *
+ * Example:
+ * ```tsx
+ * import { ThirdPartyCard } from 'some-library';
+ *
+ * const AgentThirdPartyCard = asAgentEntity({
+ *   entityType: 'Character',
+ *   entityId: (props) => props.character.id,
+ *   displayContext: (props) => ({ label: props.character.name }),
+ *   intents: ['generate-clip', 'clone-voice'],
+ * })(ThirdPartyCard);
+ *
+ * // Usage:
+ * <AgentThirdPartyCard character={char} />
+ * ```
+ */
+export declare function asAgentEntity<P extends Record<string, unknown>>(config: AsAgentEntityConfig<P>): (WrappedComponent: React.ComponentType<P & Partial<InjectedAgentEntityProps>>) => React.FC<P>;
+//# sourceMappingURL=asAgentEntity.d.ts.map

package/dist/entity/asAgentEntity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asAgentEntity.d.ts","sourceRoot":"","sources":["../../src/entity/asAgentEntity.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,UAAU,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC;IAC5C,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;IAC9C,cAAc,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,oBAAoB,CAAC;IACnD,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;IACrD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAChC,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,KAAK,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAAC;IACrH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,eAAe,KAAK,IAAI,CAAC;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,uBAAuB,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,IAG5B,kBAAkB,KAAK,CAAC,aAAa,CAAC,CAAC,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC,KAC3E,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAkCf"}

package/dist/entity/asAgentEntity.js

@@ -0,0 +1,51 @@
+import React from 'react';
+import { AgentEntity } from './AgentEntity.js';
+/**
+ * asAgentEntity — Higher-Order Component that wraps an existing component with agent entity capabilities.
+ *
+ * Best for wrapping third-party components or components you can't modify.
+ *
+ * Example:
+ * ```tsx
+ * import { ThirdPartyCard } from 'some-library';
+ *
+ * const AgentThirdPartyCard = asAgentEntity({
+ *   entityType: 'Character',
+ *   entityId: (props) => props.character.id,
+ *   displayContext: (props) => ({ label: props.character.name }),
+ *   intents: ['generate-clip', 'clone-voice'],
+ * })(ThirdPartyCard);
+ *
+ * // Usage:
+ * <AgentThirdPartyCard character={char} />
+ * ```
+ */
+export function asAgentEntity(config) {
+    return function wrap(WrappedComponent) {
+        const WithAgentEntity = (props) => {
+            const resolvedType = typeof config.entityType === 'function'
+                ? config.entityType(props)
+                : config.entityType;
+            const resolvedId = config.entityId(props);
+            const resolvedIntents = typeof config.intents === 'function'
+                ? config.intents(props)
+                : (config.intents ?? []);
+            const resolvedDisplay = config.displayContext(props);
+            return React.createElement(AgentEntity, {
+                type: resolvedType,
+                id: resolvedId,
+                intents: resolvedIntents,
+                displayContext: resolvedDisplay,
+                capabilities: config.capabilities,
+                onTargeted: config.onTargeted ? (action) => config.onTargeted(props, action) : undefined,
+                onReleased: config.onReleased ? () => config.onReleased(props) : undefined,
+                onCommandReceived: config.onCommandReceived ? (cmd) => config.onCommandReceived(props, cmd) : undefined,
+                onObserve: config.onObserve ? (obs) => config.onObserve(props, obs) : undefined,
+                children: (context) => React.createElement(WrappedComponent, { ...props, agentEntity: context }),
+            });
+        };
+        WithAgentEntity.displayName = `asAgentEntity(${WrappedComponent.displayName || WrappedComponent.name || 'Component'})`;
+        return WithAgentEntity;
+    };
+}
+//# sourceMappingURL=asAgentEntity.js.map

package/dist/entity/asAgentEntity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asAgentEntity.js","sourceRoot":"","sources":["../../src/entity/asAgentEntity.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAiC/C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAC3B,MAA8B;IAE9B,OAAO,SAAS,IAAI,CAClB,gBAA4E;QAE5E,MAAM,eAAe,GAAgB,CAAC,KAAK,EAAE,EAAE;YAC7C,MAAM,YAAY,GAAG,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU;gBAC1D,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC;gBAC1B,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC;YACtB,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC1C,MAAM,eAAe,GAAG,OAAO,MAAM,CAAC,OAAO,KAAK,UAAU;gBAC1D,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;gBACvB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;YAC3B,MAAM,eAAe,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YAErD,OAAO,KAAK,CAAC,aAAa,CACxB,WAAW,EACX;gBACE,IAAI,EAAE,YAAY;gBAClB,EAAE,EAAE,UAAU;gBACd,OAAO,EAAE,eAAe;gBACxB,cAAc,EAAE,eAAe;gBAC/B,YAAY,EAAE,MAAM,CAAC,YAAY;gBACjC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAmB,EAAE,EAAE,CAAC,MAAM,CAAC,UAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;gBACtG,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,UAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;gBAC3E,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,GAAiB,EAAE,EAAE,CAAC,MAAM,CAAC,iBAAkB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;gBACtH,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAoB,EAAE,EAAE,CAAC,MAAM,CAAC,SAAU,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;gBACjG,QAAQ,EAAE,CAAC,OAAgC,EAAE,EAAE,CAAC,KAAK,CAAC,aAAa,CACjE,gBAAgB,EAChB,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,CACnC;aACF,CACF,CAAC;QACJ,CAAC,CAAC;QAEF,eAAe,CAAC,WAAW,GAAG,iBAAiB,gBAAgB,CAAC,WAAW,IAAI,gBAAgB,CAAC,IAAI,IAAI,WAAW,GAAG,CAAC;QACvH,OAAO,eAAe,CAAC;IACzB,CAAC,CAAC;AACJ,CAAC"}

package/dist/entity/defineAgentEntity.d.ts

@@ -0,0 +1,54 @@
+import React from 'react';
+import type { EntityCapabilities, EntityDisplayContext, AgentAction, AgentCommand, AgentCommandResponse, UserObservation, EntityExecuteOptions, IntentResult } from '@ouispec/agent-core';
+/**
+ * Agent context passed to the render function of a defined entity.
+ */
+export interface AgentEntityRenderContext {
+    ref: React.RefCallback<HTMLElement>;
+    isTargeted: boolean;
+    isExecuting: boolean;
+    currentAction: AgentAction | null;
+    execute: (intentId: string, params?: Record<string, unknown>, options?: EntityExecuteOptions) => Promise<IntentResult>;
+    emit: (signal: string, data?: unknown) => void;
+}
+/**
+ * Configuration for defining an agent entity component.
+ */
+export interface DefineAgentEntityConfig<P> {
+    entityType: string | ((props: P) => string);
+    entityId: (props: P) => string;
+    intents: string[] | ((props: P) => string[]);
+    displayContext: (props: P) => EntityDisplayContext;
+    capabilities?: EntityCapabilities | ((props: P) => EntityCapabilities);
+    onTargeted?: (props: P, action: AgentAction) => void;
+    onReleased?: (props: P) => void;
+    onExecuting?: (props: P, intentId: string, params: Record<string, unknown>) => void;
+    onExecutionComplete?: (props: P, intentId: string, result: IntentResult) => void;
+    onCommandReceived?: (props: P, command: AgentCommand) => AgentCommandResponse | Promise<AgentCommandResponse> | void;
+    onObserve?: (props: P, observation: UserObservation) => void;
+}
+/**
+ * defineAgentEntity — factory function that creates a React component with full
+ * AgentEntity capabilities baked in.
+ *
+ * Example:
+ * ```tsx
+ * const CharacterCard = defineAgentEntity({
+ *   entityType: 'Character',
+ *   entityId: (props) => props.character.id,
+ *   intents: ['generate-clip', 'clone-voice'],
+ *   displayContext: (props) => ({ label: props.character.name, image: props.character.thumbnailUrl }),
+ * }, (props, agent) => {
+ *   return (
+ *     <div ref={agent.ref} className={agent.isTargeted ? 'targeted' : ''}>
+ *       <h3>{props.character.name}</h3>
+ *       <button onClick={() => agent.execute('generate-clip', { character: props.character.id })}>
+ *         Generate Clip
+ *       </button>
+ *     </div>
+ *   );
+ * });
+ * ```
+ */
+export declare function defineAgentEntity<P extends Record<string, unknown>>(config: DefineAgentEntityConfig<P>, render: (props: P, agent: AgentEntityRenderContext) => React.ReactElement | null): React.FC<P>;
+//# sourceMappingURL=defineAgentEntity.d.ts.map

package/dist/entity/defineAgentEntity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineAgentEntity.d.ts","sourceRoot":"","sources":["../../src/entity/defineAgentEntity.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AAKjF,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,YAAY,EACb,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IACpC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACvH,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,UAAU,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC;IAC5C,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IAC/B,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;IAC7C,cAAc,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,oBAAoB,CAAC;IACnD,YAAY,CAAC,EAAE,kBAAkB,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,kBAAkB,CAAC,CAAC;IACvE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;IACrD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAChC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACpF,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IACjF,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,KAAK,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAAC;IACrH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,eAAe,KAAK,IAAI,CAAC;CAC9D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,MAAM,EAAE,uBAAuB,CAAC,CAAC,CAAC,EAClC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,wBAAwB,KAAK,KAAK,CAAC,YAAY,GAAG,IAAI,GAC/E,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAiEb"}

package/dist/entity/defineAgentEntity.js

@@ -0,0 +1,133 @@
+import { useRef, useEffect, useMemo, useCallback, useState } from 'react';
+import { AgentEntityBase, EntityRegistry, } from '@ouispec/agent-core';
+/**
+ * defineAgentEntity — factory function that creates a React component with full
+ * AgentEntity capabilities baked in.
+ *
+ * Example:
+ * ```tsx
+ * const CharacterCard = defineAgentEntity({
+ *   entityType: 'Character',
+ *   entityId: (props) => props.character.id,
+ *   intents: ['generate-clip', 'clone-voice'],
+ *   displayContext: (props) => ({ label: props.character.name, image: props.character.thumbnailUrl }),
+ * }, (props, agent) => {
+ *   return (
+ *     <div ref={agent.ref} className={agent.isTargeted ? 'targeted' : ''}>
+ *       <h3>{props.character.name}</h3>
+ *       <button onClick={() => agent.execute('generate-clip', { character: props.character.id })}>
+ *         Generate Clip
+ *       </button>
+ *     </div>
+ *   );
+ * });
+ * ```
+ */
+export function defineAgentEntity(config, render) {
+    const DefinedEntity = (props) => {
+        const [, forceUpdate] = useState(0);
+        const rerender = useCallback(() => forceUpdate(n => n + 1), []);
+        const resolvedType = typeof config.entityType === 'function' ? config.entityType(props) : config.entityType;
+        const resolvedId = config.entityId(props);
+        const resolvedIntents = typeof config.intents === 'function' ? config.intents(props) : config.intents;
+        const resolvedDisplay = config.displayContext(props);
+        const resolvedCapabilities = typeof config.capabilities === 'function'
+            ? config.capabilities(props)
+            : (config.capabilities ?? {});
+        const bridgeRef = useRef(null);
+        if (!bridgeRef.current) {
+            bridgeRef.current = new FunctionalEntityBridge();
+        }
+        const bridge = bridgeRef.current;
+        bridge._syncProps(resolvedType, resolvedId, resolvedIntents, resolvedDisplay, resolvedCapabilities);
+        bridge._setCallbacks({
+            onTargeted: config.onTargeted ? (action) => config.onTargeted(props, action) : undefined,
+            onReleased: config.onReleased ? () => config.onReleased(props) : undefined,
+            onExecuting: config.onExecuting ? (intentId, params) => config.onExecuting(props, intentId, params) : undefined,
+            onExecutionComplete: config.onExecutionComplete ? (intentId, result) => config.onExecutionComplete(props, intentId, result) : undefined,
+            onCommandReceived: config.onCommandReceived ? (cmd) => config.onCommandReceived(props, cmd) : undefined,
+            onObserve: config.onObserve ? (obs) => config.onObserve(props, obs) : undefined,
+        });
+        bridge._setRerender(rerender);
+        useEffect(() => {
+            bridge.register();
+            return () => bridge.unregister();
+        }, []);
+        useEffect(() => {
+            const prevKey = `${bridge._prevType}::${bridge._prevId}`;
+            const currKey = `${resolvedType}::${resolvedId}`;
+            if (prevKey !== currKey) {
+                bridge.unregister();
+                bridge.register();
+            }
+            bridge._prevType = resolvedType;
+            bridge._prevId = resolvedId;
+        }, [resolvedType, resolvedId]);
+        const refCallback = useCallback((element) => {
+            EntityRegistry.instance.updateElement(resolvedType, resolvedId, element);
+        }, [resolvedType, resolvedId]);
+        const agentContext = useMemo(() => ({
+            ref: refCallback,
+            isTargeted: bridge.isTargeted,
+            isExecuting: bridge.isExecuting,
+            currentAction: bridge.currentAction,
+            execute: (intentId, params, options) => bridge.execute(intentId, params, options),
+            emit: (signal, data) => bridge.emit(signal, data),
+        }), [bridge.isTargeted, bridge.isExecuting, bridge.currentAction, refCallback]);
+        return render(props, agentContext);
+    };
+    DefinedEntity.displayName = `AgentEntity(${typeof config.entityType === 'string' ? config.entityType : 'dynamic'})`;
+    return DefinedEntity;
+}
+class FunctionalEntityBridge extends AgentEntityBase {
+    _type = '';
+    _id = '';
+    _intents = [];
+    _display = { label: '' };
+    _caps = {};
+    _callbacks = {};
+    _rerender = null;
+    _prevType = '';
+    _prevId = '';
+    get entityType() { return this._type; }
+    get entityId() { return this._id; }
+    get intents() { return this._intents; }
+    get displayContext() { return this._display; }
+    get capabilities() { return this._caps; }
+    _syncProps(type, id, intents, display, caps) {
+        this._type = type;
+        this._id = id;
+        this._intents = intents;
+        this._display = display;
+        this._caps = caps;
+    }
+    _setCallbacks(callbacks) {
+        this._callbacks = callbacks;
+    }
+    _setRerender(fn) {
+        this._rerender = fn;
+    }
+    onTargeted(action) {
+        this._callbacks.onTargeted?.(action);
+        this._rerender?.();
+    }
+    onReleased() {
+        this._callbacks.onReleased?.();
+        this._rerender?.();
+    }
+    onExecuting(intentId, params) {
+        this._callbacks.onExecuting?.(intentId, params);
+        this._rerender?.();
+    }
+    onExecutionComplete(intentId, result) {
+        this._callbacks.onExecutionComplete?.(intentId, result);
+        this._rerender?.();
+    }
+    onCommandReceived(command) {
+        return this._callbacks.onCommandReceived?.(command);
+    }
+    onObserve(observation) {
+        this._callbacks.onObserve?.(observation);
+    }
+}
+//# sourceMappingURL=defineAgentEntity.js.map

package/dist/entity/defineAgentEntity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineAgentEntity.js","sourceRoot":"","sources":["../../src/entity/defineAgentEntity.tsx"],"names":[],"mappings":"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"}

package/dist/entity/index.d.ts

@@ -0,0 +1,10 @@
+export { AgentEntityComponent } from './AgentEntityComponent.js';
+export { defineAgentEntity } from './defineAgentEntity.js';
+export { AgentEntity } from './AgentEntity.js';
+export { asAgentEntity } from './asAgentEntity.js';
+export { useViewAnnotation } from './useViewAnnotation.js';
+export type { AgentEntityRenderContext, DefineAgentEntityConfig } from './defineAgentEntity.js';
+export type { AgentEntityProps, AgentEntityChildContext } from './AgentEntity.js';
+export type { AsAgentEntityConfig, InjectedAgentEntityProps } from './asAgentEntity.js';
+export type { UseViewAnnotationOptions, UseViewAnnotationReturn } from './useViewAnnotation.js';
+//# sourceMappingURL=index.d.ts.map