customware-support-widget

name	customware-support-widget
description	Use this skill when adding, placing, configuring, or fixing the Customware support chat widget in the Customware React Router client-only SPA template. It covers root.tsx/root document script loading, route/layout placement, required org/project ids, bubble versus full mode, optional metadata and style options, page-operation support, and constraints for MITB-style code generation.

Customware Support Widget

Use this skill when the Customware React Router client-only SPA template needs a Customware support chat entry point.

The widget is a third-party browser custom element. In this template, load the widget script in root.tsx or the equivalent React Router root file/component where the HTML document structure is defined, and render <customware-chat> only in the route or layout where support should appear. The widget owns its Shadow DOM UI, chat runtime, service calls, tool badges, speech input, and page-operation behavior.

For all React code examples, script loading patterns, JSX typing, bubble/full mode examples, metadata, and style options, read references/component-usage.md.

What It Offers

• A support chat UI as <customware-chat>.
• chat-bubble mode for a floating launcher/dialog.
• full mode for a sidebar, rail, drawer, or split-pane chat region.
• Optional visitor metadata through the meta DOM property.
• Optional sizing/customization through styleOptions or style-options.
• Tool-backed support behavior: read domain/context, list tasks, create tasks, and operate the visible page.
• Page operation for user requests like filling forms, selecting options, clicking buttons, replacing values, or submitting visible UI.

When To Use

• Add support chat to the Customware React Router client-only SPA template.
• Place a floating support launcher in an app shell.
• Place support chat as a full embedded panel in a layout region.
• Allow the support agent to help with visible app UI, such as filling a form on behalf of the user.
• Update an existing support widget placement or styling.

For the exact React implementation patterns, use references/component-usage.md.

When Not To Use

• Do not use this skill for server-side rendering work. The target template is client-only React Router SPA mode.
• Do not use this skill to build a custom chat UI.
• Do not use this skill to iframe the widget.
• Do not use this skill to call support chat endpoints directly.
• Do not use this skill for non-template React apps or non-React apps unless explicitly asked.
• Do not use this skill if orgId or projectId cannot be determined. Fail the task with a clear reason that the required Customware org/project id is missing.

Non-Negotiables

• Always render the real custom element: <customware-chat>.
• Always pass both org-id and project-id.
• If either id is unavailable, fail the task with a clear missing-id reason instead of rendering placeholders or asking follow-up questions.
• Load https://app.customware.ai/support-widget/customware-chat.js once from root.tsx or the template's equivalent React Router root document shell unless an existing app-level loader already does this.
• Do not pass task ids, domain ids, user ids, API tokens, session tokens, auth cookies, or secrets into the component.
• Use meta only for optional visitor identity: email and/or name.
• Use wrapper CSS, styleOptions, or style-options for sizing. Do not use the native DOM style property as widget configuration.
• Tool calls are compact status badges, not buttons.
• Page operation is handled inside the widget. Do not add custom click/fill/page-control handlers around it.
• Do not hardcode page-operation prompts or values into the host app. The user must type the request into the widget.

Implementation Workflow

1. Read references/component-usage.md.
2. Confirm the React app has orgId and projectId.
3. Choose the mode:
   • chat-bubble for a floating support launcher/dialog.
   • full for an embedded rail, drawer, split pane, or fixed chat region.
4. Add the script tag in root.tsx or the React Router root file/component that defines the HTML document <head>, unless it already exists.
5. Add JSX custom element typings in a .d.ts file when the template does not already know <customware-chat>.
6. Render <customware-chat> with org-id and project-id in the specific route or layout that needs support.
7. Set optional meta and styleOptions through a typed React ref when needed.
8. For full mode, ensure the wrapper/component has a concrete height and internal scrolling belongs to the widget.
9. For bubble mode, ensure the wrapper is not clipped and has an appropriate z-index.
10. Validate the resulting React code syntactically and with npm run check when available.

Use references/component-usage.md for complete code examples for each mode.

MITB Agent Constraints

• Do not assume access to Playwright, screenshots, browser DevTools, or visual testing.
• Do not claim that the widget was visually tested.
• Do not write user-facing status reports inside the generated app.
• Validate by code inspection, TypeScript/compile checks, and ensuring the generated React Router/Vite code follows the examples in references/component-usage.md.
• If runtime ids are unavailable during generation, fail the task with a clear missing-id reason. If ids are expected to load asynchronously at runtime, gate the component behind orgId && projectId so it never renders with placeholders.

Do Not Do

• Do not create an iframe integration.
• Do not rebuild or restyle the widget internals in React.
• Do not reach into Shadow DOM or depend on internal class names.
• Do not expose tool calls as clickable UI controls.
• Do not call the support chat API or page-operation API directly from the host app.
• Do not add fallback embed modes.
• Do not store secrets, access tokens, private payloads, or auth/session data in widget attributes.
• Do not pass arbitrary user/profile objects into meta; pass only optional email and name.
• Do not set a fixed height only on an imagined internal message list. Size the whole full-mode host region.
• Do not place bubble mode inside clipped or transformed containers unless that behavior is intentional.