@livelayer/react 0.10.7 → 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fusion Studios Code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -48,6 +48,67 @@ That's it. The widget docks bottom-right, the agent can navigate users to other
 
 ---
 
+## Structured data collection (0.12.0)
+
+The agent can run guided, typed Q&A flows backed by LiveKit's [`voice.AgentTask`](https://docs.livekit.io/agents/logic/tasks/) + `beta.workflows.TaskGroup` primitives. **No new components, no special attributes — just write regular HTML forms.** Every `<form>` is auto-discovered.
+
+```tsx
+import { AvatarWidget } from "@livelayer/react";
+
+function App() {
+  return (
+    <>
+      <AvatarWidget
+        agentId="agent_abc"
+        onCollect={(result) => {
+          // result.results keyed by field name — ship to your CRM.
+          fetch("/api/leads", {
+            method: "POST",
+            body: JSON.stringify(result),
+          });
+        }}
+      />
+
+      {/* Plain HTML — the agent finds this. */}
+      <form>
+        <label>Email <input name="email" type="email" required /></label>
+        <label>Company <input name="company" /></label>
+        <button type="submit">Subscribe</button>
+      </form>
+    </>
+  );
+}
+```
+
+The agent infers each field's label from the wrapping `<label>` / `aria-label` / `placeholder`, infers the kind from `type=`, runs a TaskGroup when the visitor wants to fill the form by voice, normalizes each spoken answer per-kind, and paints values into the matching `[name="..."]` inputs live as it records each one. `onCollect` fires once with the typed payload when the run finishes.
+
+**Streaming per-field updates** for a progress UI:
+
+```tsx
+import { useCollect } from "@livelayer/react";
+
+function Progress() {
+  const { fields, isCollecting, lastResult } = useCollect();
+  return Object.entries(fields).map(([name, value]) => (
+    <div key={name}>{name}: {value}</div>
+  ));
+}
+```
+
+**Opt-out** when you don't want a form / input visible to the agent:
+
+```tsx
+<form data-ll-skip>...</form>           // exclude the whole form
+<input data-ll-private />               // exclude one input
+<form data-ll-intent="request a demo">  // disambiguate (still visible)
+```
+
+`type="password"`, `autocomplete="cc-*"`, and `autocomplete="off"` are ALWAYS excluded — you don't have to mark them.
+
+See [docs.livelayer.studio/develop/data-collection](https://docs.livelayer.studio/develop/data-collection) for the full result shape, dashboard-declared field lists, slide-level data collection, capability gating, and webhook delivery.
+
+---
+
 ## Recipes
 
 ### 1. Voice navigation in Next.js / React Router
@@ -167,36 +228,25 @@ The agent emits `{ type: "click", selector: "[data-ll-action='open-pricing-modal
 
 **Page scrolling**: the agent can call `scroll_page` with `direction: "up" | "down" | "top" | "bottom"`. Default behavior scrolls the window by ±1 viewport height. Override with `onScrollPage` for custom scroll containers.
 
-**Forms** — declarative wrappers. Tag the form and the fields the agent is allowed to fill:
+**Forms** — auto-discovered. Just write regular HTML:
 
 ```tsx
-import { LiveLayerForm, LiveLayerField } from "@livelayer/react";
-
-<LiveLayerForm id="contact" intent="contact us — send a message">
-  <LiveLayerField name="name" label="Your name" />
-  <LiveLayerField name="email" label="Email" type="email" />
-  <LiveLayerField name="message" as="textarea" label="Message" />
-  <button type="submit">Send</button>
-</LiveLayerForm>
-```
-
-Or use raw HTML with `data-ll-form` / `data-ll-field`:
-
-```html
-<form data-ll-form="contact" data-ll-intent="contact us">
-  <input data-ll-field="name" name="name" />
-  <input data-ll-field="email" name="email" type="email" />
-  <textarea data-ll-field="message" name="message"></textarea>
+<form onSubmit={handleSubmit}>
+  <label>Name <input name="name" /></label>
+  <label>Email <input name="email" type="email" /></label>
+  <label>Message <textarea name="message" /></label>
   <button type="submit">Send</button>
 </form>
 ```
 
 The agent sees these in `PageContext.forms` and calls:
-- `fill_form` — sets values via the React-controlled-input pattern (your `onChange` listeners fire correctly)
-- `focus_field` — moves focus to a specific field
-- `submit_form` — calls `form.requestSubmit()`. The widget publishes `{ type: "form_submitted", formId }` on success or `{ type: "form_submit_blocked", formId, reason: "validation" }` on HTML5 validation failure
+- `fill_form` — sets values via the canonical native-setter pattern (your `onChange` listeners fire correctly). Use when the agent already has all the answers.
+- `collect_from_page` — runs a guided sub-conversation that asks for each field one at a time, normalizes spoken input per kind (email letter-by-letter, phone digit grouping, etc), and delivers a typed `onCollect` payload. Use when the visitor wants to fill the form by voice. See [Structured data collection](#structured-data-collection-0120) above.
+- `submit_form` — calls `form.requestSubmit()`. Publishes `{ type: "form_submitted", formId }` on success or `{ type: "form_submit_blocked", formId, reason: "validation" }` on HTML5 validation failure.
 
-**Privacy is enforced regardless of tagging**: `type="password"`, `autocomplete="cc-*"`, and `[data-ll-private="true"]` fields are NEVER agent-fillable. Card fields belong in Stripe Elements; we will not be the rail.
+Form IDs are inferred from the form's existing `id` / `name` attribute, falling back to a `data-ll-intent` slug, finally `form_<index>`.
+
+**Opt-out for privacy**: `<form data-ll-skip>...</form>` and `<input data-ll-private />` keep things out of the agent's view. `type="password"`, `autocomplete="cc-*"`, and `autocomplete="off"` are ALWAYS excluded — card fields belong in Stripe Elements; we will not be the rail.
 
 **Routes**: the agent can call `request_routes` to get up to 200 deduped `<a href>` entries from the page (internal flagged separately from external). Useful for "where can I go?" prompts.
 
@@ -281,21 +331,34 @@ All props are optional except `agentId`.
 
 Renders a wrapper element with `data-ll-region` + `data-ll-intent` that the page-context extractor prioritizes.
 
-### `<LiveLayerForm>` + `<LiveLayerField>` (form primitives, 0.4.0)
+### Forms (0.12.0 — no wrappers, just plain HTML)
 
 ```tsx
-<LiveLayerForm id="signup" intent="create account" onSubmit={handleSubmit}>
-  <LiveLayerField name="email" label="Email" type="email" />
-  <LiveLayerField name="bio" as="textarea" label="Bio" />
-  <LiveLayerField name="role" as="select" label="Role">
-    <option value="dev">Developer</option>
-    <option value="pm">PM</option>
-  </LiveLayerField>
+<form onSubmit={handleSubmit}>
+  <label>Email <input name="email" type="email" required /></label>
+  <label>Bio <textarea name="bio" /></label>
+  <label>
+    Role
+    <select name="role">
+      <option value="dev">Developer</option>
+      <option value="pm">PM</option>
+    </select>
+  </label>
   <button type="submit">Sign up</button>
-</LiveLayerForm>
+</form>
 ```
 
-Equivalent to raw HTML with `data-ll-form` + `data-ll-field` attributes. Untagged forms remain invisible to the agent.
+Every `<form>` is auto-discovered. The agent infers labels from the
+wrapping `<label>` / `aria-label` / `placeholder`, infers kinds from
+the input `type=`, and can either fill in one shot (`fill_form`) or
+walk the visitor through it conversationally (`collect_from_page`).
+
+**Opt out** with `data-ll-skip` on a form or `data-ll-private` on an
+input. Browser-native private fields (`type="password"`, `autocomplete="cc-*"`,
+`autocomplete="off"`) are always excluded.
+
+See the *Structured data collection* section above for `onCollect` /
+`useCollect`.
 
 ### Hooks (power users)
 

package/dist/index.d.ts

@@ -1,22 +1,25 @@
 import { AgentConfig } from '@livelayer/sdk';
 import { AgentState } from '@livelayer/sdk';
+import { clearFieldRegistry } from '@livelayer/sdk';
 import { Component } from 'react';
 import { ConnectionState } from '@livelayer/sdk';
 import { CSSProperties } from 'react';
 import { ElementType } from 'react';
 import { ErrorInfo } from 'react';
 import { FC } from 'react';
-import { FormHTMLAttributes } from 'react';
+import { FieldKind } from '@livelayer/sdk';
+import { FieldManifest } from '@livelayer/sdk';
+import { FieldOption } from '@livelayer/sdk';
 import { ForwardRefExoticComponent } from 'react';
-import { InputHTMLAttributes } from 'react';
+import { getRegisteredFields } from '@livelayer/sdk';
 import { JSX } from 'react/jsx-runtime';
 import { LiveKitSession } from '@livelayer/sdk';
 import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
+import { registerFields } from '@livelayer/sdk';
 import { Room } from 'livekit-client';
-import { SelectHTMLAttributes } from 'react';
 import { SessionOptions } from '@livelayer/sdk';
-import { TextareaHTMLAttributes } from 'react';
+import { setFieldValue } from '@livelayer/sdk';
 import { TranscriptEntry } from '@livelayer/sdk';
 
 /**
@@ -33,7 +36,13 @@ import { TranscriptEntry } from '@livelayer/sdk';
  *
  * Default (undefined): everything enabled (matches 0.3.x behavior).
  */
-export declare type AgentCapability = "navigate" | "scroll" | "click" | "fill_forms" | "submit_forms" | "read_page";
+export declare type AgentCapability = "navigate" | "scroll" | "click" | "fill_forms" | "submit_forms" | "read_page"
+/**
+* 0.11.0 — LiveKit Agent Tasks structured collection (page-form,
+* agent-declared field list, slide form). The detailed result types
+* live in `./hooks/useCollect` to keep co-located with the consumer.
+*/
+| "collect_data";
 
 /**
  * Agent commands streamed over the LiveKit data channel. The base package
@@ -326,6 +335,47 @@ export declare interface AvatarWidgetProps {
     onConnectionStateChange?: (state: ConnectionState) => void;
     onAgentEvent?: (e: AgentEventDetail) => void;
     onAgentCommand?: (cmd: AgentCommand) => void;
+    /**
+     * Fires once when the agent finishes a structured collection run.
+     * One callback covers every collection surface:
+     *
+     *   - `source: "page"`  — agent walked the visitor through an
+     *                          on-page <form> (auto-discovered). The
+     *                          values already painted into the matching
+     *                          inputs live as they were recorded.
+     *   - `source: "agent"` — dashboard-declared field list (Behavior →
+     *                          Data collection in the agent editor).
+     *   - `source: "slide"` — slide-level form_fields (slide editor's
+     *                          Data collection toggle).
+     *
+     * Typical use: ship the typed payload to your backend.
+     *
+     *   <AvatarWidget
+     *     agentId="..."
+     *     onCollect={(r) => fetch("/api/leads", { method: "POST",
+     *       body: JSON.stringify(r) })}
+     *   />
+     *
+     * For streaming per-field updates use the `useCollect()` hook
+     * instead. Don't write to `<input value=...>` from inside this
+     * callback — the SDK already auto-painted matching inputs by their
+     * `name` attribute before this fires.
+     */
+    onCollect?: (result: {
+        sessionId: string;
+        startedAt: string;
+        endedAt: string;
+        source: "agent" | "slide" | "page";
+        slideId?: string;
+        formId?: string;
+        results: Record<string, {
+            fieldId: string;
+            fieldName: string;
+            value: string;
+            kind: string;
+        }>;
+        summary?: string;
+    }) => void;
     /**
      * When provided, the widget does not create its own LiveKit session.
      * The consumer owns connection lifecycle. Use for cross-page
@@ -364,17 +414,31 @@ export declare interface CameraStateHandle {
     clearError: () => void;
 }
 
+export { clearFieldRegistry }
+
 export declare function clearPageContextCache(): void;
 
 export declare function clearRoutesCache(): void;
 
-declare interface CommonFieldProps {
-    /** Field identifier. Becomes `data-ll-field` AND the input's `name`. */
-    name: string;
-    /** Visible label. Wrapped in <label>. */
-    label?: ReactNode;
-    /** Optional className for the wrapping <label>. */
-    labelClassName?: string;
+export declare interface CollectedField {
+    fieldId: string;
+    fieldName: string;
+    value: string;
+    kind: string;
+    source: "agent" | "slide" | "page";
+    slideId?: string;
+    formId?: string;
+}
+
+export declare interface CollectedResult {
+    sessionId: string;
+    startedAt: string;
+    endedAt: string;
+    source: "agent" | "slide" | "page";
+    slideId?: string;
+    formId?: string;
+    results: Record<string, CollectedField>;
+    summary?: string;
 }
 
 export { ConnectionState }
@@ -472,12 +536,25 @@ export declare function extractPageContext(extras?: Record<string, unknown>, opt
 
 export declare function extractRoutes(doc?: Document): ExtractedRoute[];
 
-declare type FieldElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+export { FieldKind }
+
+export { FieldManifest }
+
+export { FieldOption }
+
+export declare function FieldProvider({ fields, children }: FieldProviderProps): JSX.Element;
+
+export declare interface FieldProviderProps {
+    fields: FieldManifest[];
+    children: ReactNode;
+}
 
 export declare function getCachedPageContext(extras?: Record<string, unknown>, opts?: ExtractOptions): PageContext;
 
 export declare function getCachedRoutes(): ExtractedRoute[];
 
+export { getRegisteredFields }
+
 export declare interface LegacyAgentEventDetail {
     eventName: string;
     data: Record<string, unknown>;
@@ -500,30 +577,6 @@ export declare interface LiveLayerDebugPanelProps {
     storageKey?: string;
 }
 
-export declare const LiveLayerField: ForwardRefExoticComponent<LiveLayerFieldProps & RefAttributes<FieldElement>>;
-
-export declare type LiveLayerFieldProps = (CommonFieldProps & {
-    as?: "input";
-} & Omit<InputHTMLAttributes<HTMLInputElement>, "name">) | (CommonFieldProps & {
-    as: "textarea";
-} & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "name">) | (CommonFieldProps & {
-    as: "select";
-    children: ReactNode;
-} & Omit<SelectHTMLAttributes<HTMLSelectElement>, "name">);
-
-export declare const LiveLayerForm: ForwardRefExoticComponent<LiveLayerFormProps & RefAttributes<HTMLFormElement>>;
-
-export declare interface LiveLayerFormProps extends FormHTMLAttributes<HTMLFormElement> {
-    /** Stable identifier for the form. Becomes `data-ll-form`. */
-    id: string;
-    /**
-     * One-line description the agent sees. e.g. "create account",
-     * "request a demo". The agent uses this to decide WHEN to fill the
-     * form (matching user intent → form intent).
-     */
-    intent?: string;
-}
-
 export declare const LiveLayerRegion: ForwardRefExoticComponent<LiveLayerRegionProps & RefAttributes<HTMLElement>>;
 
 export declare interface LiveLayerRegionProps {
@@ -669,9 +722,10 @@ export declare interface PageContext {
         type: string;
     }>;
     /**
-     * Author-curated forms via <LiveLayerForm> / data-ll-form. The agent
-     * uses these to call `fill_form` / `submit_form`. Values NEVER included.
-     * (0.4.0)
+     * Every <form> on the page is auto-discovered (0.12.0). The agent
+     * uses these entries to call `fill_form`, `submit_form`, or
+     * `collect_from_page`. Values NEVER included. Forms opted out via
+     * `data-ll-skip` or inside a `data-ll-private` subtree are absent.
      */
     forms: Array<{
         id: string;
@@ -703,6 +757,8 @@ declare interface Props {
     fallback?: ReactNode;
 }
 
+export { registerFields }
+
 /**
  * The shape consumers pass back from the `getRoutes` callback. Matches
  * `ExtractedRoute` but every field except `href` is optional — defaults
@@ -742,6 +798,8 @@ export declare interface ScreenShareStateHandle {
     clearError: () => void;
 }
 
+export { setFieldValue }
+
 /**
  * Pure: should the widget render at this pathname?
  *
@@ -803,6 +861,40 @@ export declare function useAudioLevel(): AudioLevelHandle;
 
 export declare function useCameraState(): CameraStateHandle;
 
+export declare function useCollect(options?: UseCollectOptions): UseCollectHandle;
+
+export declare interface UseCollectHandle {
+    /** Field name → most-recent value. Resets when a new run starts. */
+    fields: Record<string, string>;
+    /** True between the first field update and the completion event. */
+    isCollecting: boolean;
+    /** Most recent completed result; null until at least one run finishes. */
+    lastResult: CollectedResult | null;
+    /** Clear the running snapshot manually (e.g. on slide change). */
+    reset: () => void;
+}
+
+export declare interface UseCollectOptions {
+    /**
+     * Fires for every field as it's recorded. Use for live progress UI.
+     * Omit if you only care about the final payload — that's what
+     * `<AvatarWidget onCollect />` is for.
+     */
+    onFieldUpdate?: (update: CollectedField) => void;
+    /**
+     * Fires once when a collection run finishes. Same payload the
+     * `<AvatarWidget onCollect />` prop receives — they're equivalent.
+     */
+    onComplete?: (result: CollectedResult) => void;
+    /**
+     * Restrict to one source. `"page"` ignores slide / agent flows;
+     * `"slide"` ignores page-form / agent-level flows; `"agent"`
+     * ignores everything except dashboard-declared field lists. Default
+     * `"all"` listens to every source.
+     */
+    source?: "all" | "agent" | "slide" | "page";
+}
+
 export declare function useDisplayMode({ value, defaultValue, onChange, }?: Options): [DisplayMode_2, (next: DisplayMode_2) => void];
 
 export declare function useDisplayModePersistence({ value, defaultValue, onChange, persistKey, disablePersistence, }?: Options_2): [DisplayMode_2, (next: DisplayMode_2) => void];
@@ -852,6 +944,13 @@ export declare function useMicrophoneState(): MicrophoneStateHandle;
  */
 export declare function usePathname(controlledPathname?: string): string;
 
+/**
+ * Register a set of fields with the LiveLayer SDK. Stable across
+ * re-renders by depending on the SERIALIZED field list (so consumers
+ * can inline the array literal without memoizing).
+ */
+export declare function useRegisterFields(fields: FieldManifest[]): void;
+
 export declare function useRouteMatch(pathname: string | undefined, showOn: RoutePattern[] | undefined, hideOn: RoutePattern[] | undefined): boolean;
 
 export declare function useScreenShareState(): ScreenShareStateHandle;