@chatlychat/widget-react 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# @chatlychat/widget-react — changelog
+
+## 0.1.0 — unreleased
+
+- Initial release: `<ChatlyWidget />`, `useChatly()`, `useChatlyEvent()`.
+- React 18 StrictMode safe (one boot, not two), tears the widget down on
+  unmount, and turns an `identity`/`locale` prop change into `identify()` /
+  `setLocale()` rather than a re-init.

package/LICENSE

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

@@ -1,3 +1,203 @@
-# Temporary Holding Version
+# @chatlychat/widget-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Chatly chat widget as a React component.
+
+```bash
+pnpm add @chatlychat/widget-react
+```
+
+```tsx
+import { ChatlyWidget, useChatly } from '@chatlychat/widget-react';
+
+export function App() {
+  return (
+    <>
+      {/* One of these, high in the tree. */}
+      <ChatlyWidget publicId="acme-web" visitor={{ externalId: user.id, email: user.email }} />
+      <Routes />
+    </>
+  );
+}
+
+export function HelpButton() {
+  const chatly = useChatly();
+  return <button onClick={() => chatly.open('help')}>Help</button>;
+}
+```
+
+That is the whole integration. No `<script>` tag, no `window.Chatly`, no
+effect of your own — the component injects the loader, mounts the widget and
+tears it down when it unmounts.
+
+## Why this exists
+
+Without it, the integration is an effect you write by hand:
+
+```tsx
+// Don't. This is the version that was in our own docs, and it has three bugs.
+useEffect(() => {
+  window.Chatly?.init({ publicId });
+  return () => window.Chatly?.destroy();
+}, [publicId]);
+```
+
+1. **It boots twice in StrictMode.** React 18 runs every effect mount →
+   cleanup → mount in development, so that is `init` → `destroy` → `init`:
+   two visitor sessions minted, and a launcher that visibly flickers.
+2. **A `theme` in the deps re-initialises on every render.** `theme={{…}}` is
+   a new object each time, so the widget is destroyed and rebuilt underneath a
+   visitor who was mid-sentence.
+3. **It can never identify anybody.** The only place to put an identity is
+   `init`, which has already run by the time your user signs in.
+
+This component fixes all three, and the mechanism is shared with the custom
+element in [`@chatlychat/widget-element`](../widget-element) so the two cannot
+drift on the part that is hard.
+
+## React is a peer dependency
+
+`react` is in `peerDependencies`, never `dependencies`, and that is a
+deliberate exception to this repo's "no new dependencies" rule.
+
+A real dependency resolves a **second copy of React** in any consumer whose
+version differs by so much as a patch, and two Reacts on one page break hooks
+with `Invalid hook call` — thrown from a component the consumer did not write
+and cannot debug. A peer dependency on the framework the consumer is already
+using adds nothing to their install and cannot duplicate.
+
+The range is `^18.0.0 || ^19.0.0`. The component uses `useRef` and
+`useEffect` and nothing newer, so it works on both.
+
+Everything else here has **one** dependency, `@chatlychat/widget-element`, which
+itself has none.
+
+## `<ChatlyWidget />`
+
+Every [init option](https://chatlychat.com/docs/channel-web) is a prop:
+`publicId` (required), `apiUrl`, `realtimeUrl`, `visitor`, `theme`,
+`behavior`, `quickLinks`, `copy`, `copyByLocale`, `cssOverrides`.
+
+Plus four of its own:
+
+| prop                  | type                                                          |
+| --------------------- | ------------------------------------------------------------- |
+| `loaderUrl`           | Where `loader.js` is served from. **Self-hosting: set this.** |
+| `locale`              | Calls `setLocale()` once the widget is up.                    |
+| `inline`              | Render the chat inside this component's own box.              |
+| `className` / `style` | Applied to the inline container.                              |
+
+And the events, as callbacks: `onReady`, `onOpen`, `onClose`, `onMessage`,
+`onConversation`, `onIdentified`, `onReset`, `onAction`, `onError`. Pass
+inline arrow functions freely — they are read through a ref, so a new one on
+every render costs nothing and the handler that fires is always the latest.
+
+### What a prop change actually does
+
+This is the part worth knowing, because the three outcomes are different:
+
+| changed prop            | what happens                                          |
+| ----------------------- | ----------------------------------------------------- |
+| `visitor`               | `identify()`. Nothing is re-mounted.                  |
+| `visitor` → `undefined` | `reset()` — a sign-out, so the next session is fresh. |
+| `locale`                | `setLocale()`. Nothing is re-mounted.                 |
+| anything else           | `init()` again, which **destroys and re-mounts**.     |
+
+A re-mount loses nothing durable — the conversation lives on the server — but
+it closes an open panel. The widget has no `setTheme`, so there is no honest
+alternative; what this component guarantees is that it only happens when a
+value really changed, not when a parent re-rendered.
+
+`loaderUrl` is the exception: changing it after load warns and does nothing,
+because the bundle is already fetched and pointing the running widget at
+another deployment would need a page reload.
+
+### Inline mounting
+
+```tsx
+<ChatlyWidget publicId="acme-web" inline className="h-[600px] w-full rounded-lg border" />
+```
+
+The chat fills the box instead of floating in the corner — a support page, a
+sidebar, a full-page `/chat` route. In this mode there is no launcher, no
+corner offset, and `close()` warns instead of working (hide or unmount your
+own container instead).
+
+This is the React shape of the widget's `mountTo` option, and it closes
+`mountTo`'s one sharp edge: the container must exist when `init` runs, and a
+selector that matches nothing makes the widget refuse to mount at all. A
+container this component renders itself cannot be missing.
+
+Give it a height. It has a 420px minimum so a container with none is still
+usable.
+
+## `useChatly()`
+
+Returns the widget's post-boot methods: `open`, `close`, `toggle`,
+`identify`, `setUser`, `setCustomAttributes`, `deleteCustomAttribute`,
+`setLabel`, `removeLabel`, `setLocale`, `track`, `registerPushToken`, `reset`.
+
+The object is referentially stable, so it is safe in a dependency array.
+
+`init` and `destroy` are deliberately **not** on it. The component owns the
+lifecycle; calling them behind its back leaves it believing a widget is
+mounted that is not, after which the next unmount does nothing and the next
+mount does nothing.
+
+Every method returns `void`, including `identify`, which the widget's own API
+returns a promise from. Your call may be queued before the bundle has arrived
+and there is nothing to await in that state — use `onIdentified` (or
+`useChatlyEvent('identified', …)`) to learn that it landed, and `onError` to
+learn that it did not.
+
+Calling any of them with no widget mounted warns in the console and does
+nothing. It never throws: a misconfigured chat must not break your click
+handler.
+
+## `useChatlyEvent(event, handler)`
+
+```tsx
+function UnreadBadge() {
+  const [unread, setUnread] = useState(0);
+  useChatlyEvent('message', () => setUnread((n) => n + 1));
+  useChatlyEvent('open', () => setUnread(0));
+  return unread > 0 ? <span className="badge">{unread}</span> : null;
+}
+```
+
+Subscribes for the life of the component. The handler is read through a ref,
+so an inline arrow does not re-subscribe on every render.
+
+`'ready'` fires immediately if the session is already up — the widget replays
+the last one — which is what makes this usable from a component that mounts
+long after the page did.
+
+## One widget per page
+
+`window.Chatly` is a singleton, so there is one widget per page whatever you
+render. Two mounted `<ChatlyWidget />`s with different options is a
+misconfiguration: the **first** one owns the configuration, the second's
+options are ignored (its event handlers still fire), and you get a console
+warning saying so. Render one, high in the tree, and reach for `useChatly()`
+everywhere else.
+
+Two mounted with the _same_ options is harmless and silent — which is what
+makes a `<ChatlyWidget />` inside a layout that remounts on navigation safe.
+
+## Server-side rendering
+
+Safe. The component renders `null` (or an empty `<div>` when `inline`), and
+everything that touches `window` happens in an effect, which never runs on the
+server. There is no `'use client'` needed in Next.js App Router beyond the one
+your own component already has if it uses hooks.
+
+## Self-hosting
+
+Set `loaderUrl` to your deployment's. `GET /v1/channels/:id` returns the right
+value as `embed.loaderUrl` — read it from there rather than typing a host, and
+note that a running widget talks to **three** origins (widget host, API host,
+realtime host); the same endpoint reports all of them as `connectOrigins` for
+your CSP.
+
+## License
+
+MIT — see `LICENSE`.

package/dist/ChatlyWidget.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `<ChatlyWidget />` — the widget as a React component.
+ *
+ * ── What this replaces ──────────────────────────────────────────────────
+ *
+ * Without it, a React app integrates by hand-writing the effect:
+ *
+ *     useEffect(() => {
+ *       window.Chatly?.init({ publicId });
+ *       return () => window.Chatly?.destroy();
+ *     }, [publicId]);
+ *
+ * That snippet has three bugs, and all three were in the version of it we
+ * published in our own docs. In StrictMode it boots twice (two sessions, a
+ * visibly flickering launcher). With a `theme={{…}}` literal in the deps it
+ * re-inits on every parent render, closing the visitor's open panel. And
+ * nothing in it ever calls `identify()`, so a visitor who signs in after load
+ * stays anonymous — because the only place to put an identity was `init`,
+ * which already ran.
+ *
+ * The lifecycle lives in `@chatlychat/widget-element` (refcounting, deferred
+ * teardown, structural prop comparison) so the React and custom-element
+ * wrappers cannot drift on the part that is hard.
+ *
+ * ── React is a peerDependency ───────────────────────────────────────────
+ *
+ * Declared `peerDependencies`, never `dependencies`. A real dependency would
+ * resolve a SECOND copy of React in any consumer whose version differs by so
+ * much as a patch, and two Reacts on one page break hooks with
+ * "Invalid hook call" — from a component the consumer did not write. A peer
+ * dep on the framework the consumer is already using is the one case where
+ * adding to the dependency block is right, and it costs their install nothing.
+ */
+import { type ChatlyEmbedHandlers, type ChatlyEmbedOptions } from '@chatlychat/widget-element';
+import type { CSSProperties, ReactElement } from 'react';
+export interface ChatlyWidgetProps extends ChatlyEmbedOptions, ChatlyEmbedHandlers {
+    /**
+     * Render the chat INSIDE this component's own box instead of floating it in
+     * the page corner.
+     *
+     * This is the React-shaped answer to `mountTo`. The container is a `<div>`
+     * this component renders, so it provably exists when `init` runs — which is
+     * the failure the widget's `mountTo` refusal exists to make loud ("not
+     * mounted — mountTo selector matched nothing"). Give it a height through
+     * `className` or `style`; it has a 420px minimum so a container with none
+     * is still usable.
+     */
+    inline?: boolean;
+    /** Only meaningful with `inline`. */
+    className?: string;
+    /** Only meaningful with `inline`. */
+    style?: CSSProperties;
+}
+export declare function ChatlyWidget(props: ChatlyWidgetProps): ReactElement | null;
+//# sourceMappingURL=ChatlyWidget.d.ts.map

package/dist/ChatlyWidget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatlyWidget.d.ts","sourceRoot":"","sources":["../src/ChatlyWidget.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAEzD,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB,EAAE,mBAAmB;IAChF;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAmDD,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAG,IAAI,CAqF1E"}

package/dist/ChatlyWidget.js

@@ -0,0 +1,159 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * `<ChatlyWidget />` — the widget as a React component.
+ *
+ * ── What this replaces ──────────────────────────────────────────────────
+ *
+ * Without it, a React app integrates by hand-writing the effect:
+ *
+ *     useEffect(() => {
+ *       window.Chatly?.init({ publicId });
+ *       return () => window.Chatly?.destroy();
+ *     }, [publicId]);
+ *
+ * That snippet has three bugs, and all three were in the version of it we
+ * published in our own docs. In StrictMode it boots twice (two sessions, a
+ * visibly flickering launcher). With a `theme={{…}}` literal in the deps it
+ * re-inits on every parent render, closing the visitor's open panel. And
+ * nothing in it ever calls `identify()`, so a visitor who signs in after load
+ * stays anonymous — because the only place to put an identity was `init`,
+ * which already ran.
+ *
+ * The lifecycle lives in `@chatlychat/widget-element` (refcounting, deferred
+ * teardown, structural prop comparison) so the React and custom-element
+ * wrappers cannot drift on the part that is hard.
+ *
+ * ── React is a peerDependency ───────────────────────────────────────────
+ *
+ * Declared `peerDependencies`, never `dependencies`. A real dependency would
+ * resolve a SECOND copy of React in any consumer whose version differs by so
+ * much as a patch, and two Reacts on one page break hooks with
+ * "Invalid hook call" — from a component the consumer did not write. A peer
+ * dep on the framework the consumer is already using is the one case where
+ * adding to the dependency block is right, and it costs their install nothing.
+ */
+import { startWidget, } from '@chatlychat/widget-element';
+import { useEffect, useRef } from 'react';
+/**
+ * Keys that are this component's own, not the widget's.
+ *
+ * Listed so `optionsFrom` can strip them by name. Spreading the rest means a
+ * widget option added later needs no change here — the failure that costs is
+ * the reverse (a prop of ours leaking into `init`), which this prevents.
+ */
+const LOCAL_PROPS = ['inline', 'className', 'style'];
+const HANDLER_PROPS = [
+    'onReady',
+    'onOpen',
+    'onClose',
+    'onMessage',
+    'onConversation',
+    'onIdentified',
+    'onReset',
+    'onAction',
+    'onError',
+];
+function optionsFrom(props, mountTo) {
+    const options = {};
+    const skip = new Set([...LOCAL_PROPS, ...HANDLER_PROPS]);
+    for (const [key, value] of Object.entries(props)) {
+        if (!skip.has(key) && value !== undefined) {
+            options[key] = value;
+        }
+    }
+    if (mountTo !== undefined) {
+        options['mountTo'] = mountTo;
+    }
+    return options;
+}
+function handlersFrom(props) {
+    return {
+        onReady: props.onReady,
+        onOpen: props.onOpen,
+        onClose: props.onClose,
+        onMessage: props.onMessage,
+        onConversation: props.onConversation,
+        onIdentified: props.onIdentified,
+        onReset: props.onReset,
+        onAction: props.onAction,
+        onError: props.onError,
+    };
+}
+export function ChatlyWidget(props) {
+    const container = useRef(null);
+    const handle = useRef(null);
+    /*
+     * The latest callbacks, behind a stable indirection.
+     *
+     * `onMessage={(m) => …}` is a NEW function on every render. Handing it
+     * straight to the lifecycle would either re-register subscribers every
+     * commit or pin the first render's closure forever — the stale-callback bug
+     * that makes a wrapper feel haunted (the handler fires with props from
+     * three navigations ago). One stable object of forwarders that read this ref
+     * is the standard answer and the only one that is correct in both
+     * directions.
+     */
+    const latest = useRef(handlersFrom(props));
+    useEffect(() => {
+        latest.current = handlersFrom(props);
+        // No dependency array: this must run after EVERY commit, because that is
+        // what "latest" means. There is nothing to compare and nothing to skip.
+    });
+    const forwarders = useRef({
+        onReady: (session) => latest.current.onReady?.(session),
+        onOpen: () => latest.current.onOpen?.(),
+        onClose: () => latest.current.onClose?.(),
+        onMessage: (message) => latest.current.onMessage?.(message),
+        onConversation: (detail) => latest.current.onConversation?.(detail),
+        onIdentified: (session) => latest.current.onIdentified?.(session),
+        onReset: (detail) => latest.current.onReset?.(detail),
+        onAction: (detail) => latest.current.onAction?.(detail),
+        onError: (detail) => latest.current.onError?.(detail),
+    });
+    /*
+     * The props of the FIRST render, captured by `useRef`'s initial-value
+     * semantics rather than read from the render scope.
+     *
+     * The mount effect has an empty dependency array — mount and unmount, which
+     * is exactly right — and reading `props` inside it would make
+     * `react-hooks/exhaustive-deps` demand them as dependencies, at which point
+     * the effect re-runs on every render and we are back to re-initialising the
+     * widget for a new object literal. The update effect below is what applies
+     * later props, and it does so through a structural comparison.
+     */
+    const initial = useRef(props);
+    useEffect(() => {
+        if (initial.current.inline === true && container.current === null) {
+            /*
+             * Should be impossible — effects run after the DOM is committed — but if
+             * it ever happens the alternative is mounting a FLOATING widget on a
+             * page built to embed one, which is the exact outcome the widget's own
+             * refusal path exists to prevent. Refuse, and say which component.
+             */
+            console.warn('[Chatly] <ChatlyWidget inline> did not get its container — not mounted');
+            return undefined;
+        }
+        const started = startWidget(
+        // The claim identity. `forwarders` is a per-instance ref object, so two
+        // mounted components are two claims and one of them unmounting does not
+        // take the widget with it.
+        forwarders, optionsFrom(initial.current, container.current ?? undefined), forwarders.current);
+        handle.current = started;
+        return () => {
+            started.stop();
+            handle.current = null;
+        };
+    }, []);
+    useEffect(() => {
+        // Again no dependency array. Every commit re-offers the props; the
+        // lifecycle decides what, if anything, that means — `visitor` becomes an
+        // `identify()`, `locale` a `setLocale()`, and only a material change to
+        // the rest costs a re-init.
+        handle.current?.update(optionsFrom(props, container.current ?? undefined), forwarders.current);
+    });
+    if (props.inline !== true) {
+        return null;
+    }
+    return _jsx("div", { ref: container, className: props.className, style: props.style });
+}
+//# sourceMappingURL=ChatlyWidget.js.map

package/dist/ChatlyWidget.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `@chatlychat/widget-react` — the Chatly widget as a React component.
+ *
+ *     import { ChatlyWidget, useChatly } from '@chatlychat/widget-react';
+ *
+ *     function App() {
+ *       return (
+ *         <>
+ *           <ChatlyWidget publicId="acme-web" visitor={{ externalId: user.id }} />
+ *           <Routes />
+ *         </>
+ *       );
+ *     }
+ *
+ *     function HelpButton() {
+ *       const chatly = useChatly();
+ *       return <button onClick={() => chatly.open('help')}>Help</button>;
+ *     }
+ *
+ * React is a peerDependency — see the note at the top of `ChatlyWidget.tsx`.
+ * The embed lifecycle comes from `@chatlychat/widget-element`, which has no
+ * dependencies of its own and no side effects on import; the custom element it
+ * also ships is NOT registered by anything here.
+ */
+export { ChatlyWidget, type ChatlyWidgetProps } from './ChatlyWidget.js';
+export { useChatly, useChatlyEvent } from './useChatly.js';
+/**
+ * Re-exported so a consumer types their props from one import rather than
+ * reaching into the element package for a theme type.
+ */
+export type { ChatlyBehavior, ChatlyCopy, ChatlyEmbedHandlers, ChatlyEmbedOptions, ChatlyEventName, ChatlyIdentity, ChatlyInitOptions, ChatlyMessageEvent, ChatlyQuickLink, ChatlyQuip, ChatlySession, ChatlyTheme, } from '@chatlychat/widget-element';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE3D;;;GAGG;AACH,YAAY,EACV,cAAc,EACd,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,UAAU,EACV,aAAa,EACb,WAAW,GACZ,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * `@chatlychat/widget-react` — the Chatly widget as a React component.
+ *
+ *     import { ChatlyWidget, useChatly } from '@chatlychat/widget-react';
+ *
+ *     function App() {
+ *       return (
+ *         <>
+ *           <ChatlyWidget publicId="acme-web" visitor={{ externalId: user.id }} />
+ *           <Routes />
+ *         </>
+ *       );
+ *     }
+ *
+ *     function HelpButton() {
+ *       const chatly = useChatly();
+ *       return <button onClick={() => chatly.open('help')}>Help</button>;
+ *     }
+ *
+ * React is a peerDependency — see the note at the top of `ChatlyWidget.tsx`.
+ * The embed lifecycle comes from `@chatlychat/widget-element`, which has no
+ * dependencies of its own and no side effects on import; the custom element it
+ * also ships is NOT registered by anything here.
+ */
+export { ChatlyWidget } from './ChatlyWidget.js';
+export { useChatly, useChatlyEvent } from './useChatly.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,YAAY,EAA0B,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/useChatly.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Hooks for controlling a widget that is already mounted.
+ *
+ * The split matters: `<ChatlyWidget />` OWNS the widget (one per page, high in
+ * the tree), and everything else — a "Chat with us" button in the header, a
+ * badge in the nav, a help link inside a modal — controls it through
+ * `useChatly()`. Rendering a second `<ChatlyWidget />` to get at `open()` is
+ * the mistake this exists to make unnecessary, and the lifecycle warns when
+ * someone makes it anyway.
+ */
+import { controls, type ChatlyEventName } from '@chatlychat/widget-element';
+/**
+ * The widget's post-boot methods.
+ *
+ * A module-level constant, returned as-is: it is referentially stable, so it
+ * is safe in a dependency array and in a `useCallback` closure, and there is
+ * no state for a hook to hold. It is a hook rather than a plain import purely
+ * for discoverability — and because it is where the "mount the widget first"
+ * contract is documented.
+ *
+ * Every method returns `void`, including `identify`, which the widget's own
+ * API returns a promise from. The call may be queued before the bundle has
+ * arrived, and there is nothing to await in that state; `useChatlyEvent`
+ * (or `onIdentified`) is how you learn it landed.
+ *
+ * Calling any of these with no widget mounted warns in the console and does
+ * nothing. It does not throw: a click handler on the host page must not break
+ * because the chat is misconfigured.
+ */
+export declare function useChatly(): typeof controls;
+/**
+ * Subscribe to a widget event for the life of this component.
+ *
+ * The handler is read through a ref, so an inline arrow function does not
+ * re-subscribe on every render — the same reason `<ChatlyWidget />` keeps its
+ * callbacks behind one. Without it, a consumer writing the obvious
+ * `useChatlyEvent('message', (m) => setCount(c => c + 1))` would register and
+ * unregister a subscriber on every commit, and would do so against the
+ * widget's `off`, which can only remove a handler it matches by identity.
+ *
+ * `'ready'` fires immediately if the session is already up: the widget replays
+ * the last one, which is what makes this usable from a component that mounts
+ * long after the page did.
+ */
+export declare function useChatlyEvent(event: ChatlyEventName, handler: (detail: unknown) => void): void;
+//# sourceMappingURL=useChatly.d.ts.map

package/dist/useChatly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChatly.d.ts","sourceRoot":"","sources":["../src/useChatly.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAa,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAGvF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,IAAI,OAAO,QAAQ,CAE3C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAU/F"}

package/dist/useChatly.js

@@ -0,0 +1,58 @@
+/**
+ * Hooks for controlling a widget that is already mounted.
+ *
+ * The split matters: `<ChatlyWidget />` OWNS the widget (one per page, high in
+ * the tree), and everything else — a "Chat with us" button in the header, a
+ * badge in the nav, a help link inside a modal — controls it through
+ * `useChatly()`. Rendering a second `<ChatlyWidget />` to get at `open()` is
+ * the mistake this exists to make unnecessary, and the lifecycle warns when
+ * someone makes it anyway.
+ */
+import { controls, subscribe } from '@chatlychat/widget-element';
+import { useEffect, useRef } from 'react';
+/**
+ * The widget's post-boot methods.
+ *
+ * A module-level constant, returned as-is: it is referentially stable, so it
+ * is safe in a dependency array and in a `useCallback` closure, and there is
+ * no state for a hook to hold. It is a hook rather than a plain import purely
+ * for discoverability — and because it is where the "mount the widget first"
+ * contract is documented.
+ *
+ * Every method returns `void`, including `identify`, which the widget's own
+ * API returns a promise from. The call may be queued before the bundle has
+ * arrived, and there is nothing to await in that state; `useChatlyEvent`
+ * (or `onIdentified`) is how you learn it landed.
+ *
+ * Calling any of these with no widget mounted warns in the console and does
+ * nothing. It does not throw: a click handler on the host page must not break
+ * because the chat is misconfigured.
+ */
+export function useChatly() {
+    return controls;
+}
+/**
+ * Subscribe to a widget event for the life of this component.
+ *
+ * The handler is read through a ref, so an inline arrow function does not
+ * re-subscribe on every render — the same reason `<ChatlyWidget />` keeps its
+ * callbacks behind one. Without it, a consumer writing the obvious
+ * `useChatlyEvent('message', (m) => setCount(c => c + 1))` would register and
+ * unregister a subscriber on every commit, and would do so against the
+ * widget's `off`, which can only remove a handler it matches by identity.
+ *
+ * `'ready'` fires immediately if the session is already up: the widget replays
+ * the last one, which is what makes this usable from a component that mounts
+ * long after the page did.
+ */
+export function useChatlyEvent(event, handler) {
+    const latest = useRef(handler);
+    useEffect(() => {
+        latest.current = handler;
+    });
+    useEffect(() => {
+        return subscribe(event, (detail) => latest.current(detail));
+        // `event` only. The handler is deliberately NOT a dependency — see above.
+    }, [event]);
+}
+//# sourceMappingURL=useChatly.js.map

package/dist/useChatly.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChatly.js","sourceRoot":"","sources":["../src/useChatly.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAwB,MAAM,4BAA4B,CAAC;AACvF,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,KAAsB,EAAE,OAAkC;IACvF,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/B,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,SAAS,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5D,0EAA0E;IAC5E,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@chatlychat/widget-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The Chatly chat widget as a React component — mount, unmount, identity and locale changes handled, StrictMode-safe.",
+  "license": "MIT",
+  "homepage": "https://github.com/livechat/platform/tree/main/packages/widget-react",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/livechat/platform.git",
+    "directory": "packages/widget-react"
+  },
+  "bugs": "https://github.com/livechat/platform/issues",
+  "keywords": [
+    "chatly",
+    "livechat",
+    "chat",
+    "widget",
+    "react",
+    "support"
+  ],
+  "author": "LiveChat Platform Engineering",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.spec.*",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src --max-warnings=0",
+    "test": "vitest run"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@chatlychat/widget-element": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@livechat/config": "workspace:*",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "jsdom": "^30.0.1",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}