@meridial/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meridial
+
+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

@@ -0,0 +1,134 @@
+# `@meridial/react`
+
+React components for embedding the Meridial in-app assistant UI (`Voicebox`) and workflow recorder UI (`Recorder`).
+
+## Exports
+
+- **`Voicebox`**: embedded assistant widget (badge + draggable conversation bar).
+- **`Recorder`**: draggable recorder UI that captures click-steps + microphone narration and stores workflows locally (and can read server workflows when authenticated).
+
+## Installation
+
+```
+npm i @meridial/react
+```
+
+## `Voicebox`
+
+### Props
+
+```ts
+interface VoiceboxProps {
+  firstMessage?: string
+  instructions?: string
+  baseUrl?: string
+  publishableKey?: string
+  identifier?: string | null
+  tools?: VoiceboxTool[]
+  triggerIcon?: React.ReactNode
+  cursor?: React.ReactNode
+  metadata?: Record<string, string>
+  onError?: (error: string) => void
+}
+```
+
+### Minimal example (Next.js / React)
+
+```tsx
+"use client"
+
+import { z } from "zod"
+import { Voicebox, defineTool, type VoiceboxTool } from "@meridial/react"
+
+const tools: VoiceboxTool[] = [
+  defineTool({
+    name: "current_weather",
+    description: "Get the current weather for a given location.",
+    parameters: z.object({
+      location: z.string(),
+    }),
+    execute: async ({ location }) => {
+      // Runs in the browser/client.
+      return { location, weather: "sunny", temperature: "24°C" }
+    },
+  }),
+]
+
+export function VoiceboxWidget({
+  publishableKey,
+  identifier,
+}: {
+  publishableKey: string
+  identifier: string | null
+}) {
+  return (
+    <Voicebox
+      baseUrl="https://app.meridial.dev" 
+      publishableKey={publishableKey}
+      identifier={identifier}
+      firstMessage="Hi, I am a meridial agent. How can I help you today ?"
+      instructions="You are a helpful assistant that can answer questions and help with tasks."
+      tools={tools}
+      metadata={{ orgId: "org_123..." }}
+      onError={(err) => console.error("[Voicebox]", err)}
+    />
+  )
+}
+```
+
+## `Recorder`
+
+### Props
+
+```ts
+interface RecorderProps {
+  baseUrl?: string
+  publishableKey?: string
+  cursor?: React.ReactNode
+  onError?: (error: string) => void
+}
+```
+
+### Minimal example
+
+```tsx
+"use client"
+
+import { Recorder } from "@meridial/react"
+
+export function RecorderWidget({ publishableKey }: { publishableKey?: string }) {
+  return (
+    <Recorder
+      baseUrl=""
+      publishableKey={publishableKey}
+      onError={(err) => console.error("[Recorder]", err)}
+    />
+  )
+}
+```
+
+## Styling / UI
+
+These components use Tailwind CSS classes and are designed to work with your existing Tailwind / shadcn setup.
+
+You can integrate styles in either of these ways:
+
+### Option 1: include `@meridial/react` in your Tailwind sources
+
+If your app compiles Tailwind itself, make sure your global stylesheet scans the React package too.
+
+```css
+@source "../node_modules/@meridial/react/dist/**/*.{js,mjs}";
+```
+
+Adjust the relative path so it is correct from your own global stylesheet location.
+
+### Option 2: import the built CSS directly
+
+If you do not want Tailwind to scan the package, import the package CSS in your global stylesheet instead:
+
+```css
+@import "@meridial/react/dist/styles.css";
+```
+
+Use this approach when you want the package to provide its own prebuilt styles instead of relying on your app's Tailwind build to generate them.