Sir Chats-A-Lot (SCAL)

Open-source React widget for an on-site web agent: chat plus dynamic surfaces (forms, quick actions, confirmations, composed multi-block layouts) driven by your server's JSON responses.

Your traffic never touches our servers: browser → your server route → your LLM key. SCAL ships the widget, the request/response contract, and server helpers — you own the route, the provider, and the data.

Docs, live playground, and roadmap: sir-chats-a-lot.com

This package is MIT, free forever, and fully functional on its own: widget, all surfaces and blocks, conditional reveal, custom registries, hybrid flow guardrails, modes, theming, memory controls, transcripts, and the scal init CLI. A commercial Pro tier for enterprise setups is available at sir-chats-a-lot.com/pro.

Features

• React components: SirChatsALotProvider, SirChatsALotWidget, SirChatsALotLauncher
• Typed browser/server contract: AgentRequest / AgentResponse
• Built-in surfaces: form, quickActions, confirm, and composed with an 11-block vocabulary (text, divider, image, field, button, slider, single-select, multi-select, rating, date-range, image-hotspot)
• showIf conditional reveal on every block
• Custom surface and block registries — render your own React components for any surface.type or block kind
• Hybrid flow guardrails — declare a FlowSpec of must-collect fields; server helpers (enforceFlow, mergeFlowAction, composeSystemPrompt from sir-chats-a-lot/server) re-prompt the LLM when it tries to finish early
• Modes registry — open a specific flow from anywhere with dispatchOpenScalWidget({ intent })
• Optional file attachments — send visitor-selected files to your own route on the current message turn
• Automatic theming from your site's CSS variables, with a manual theme override
• Conversation memory and privacy controls: persist (none / session / local), clearOnClose, idleTimeoutMs
• Transcript export helpers and a mock API (createMockSirChatsALotApi) for UI work without keys

The package does not ship production API routes. You own API keys, rate limits, and provider choice on the server.

Quick start

npm install sir-chats-a-lot

"use client";

import {
  SirChatsALotProvider,
  SirChatsALotWidget,
  SirChatsALotLauncher,
} from "sir-chats-a-lot";
import type { AgentRequest, SirChatsALotApi } from "sir-chats-a-lot";
import "sir-chats-a-lot/styles";

const api: SirChatsALotApi = async (request: AgentRequest) => {
  const res = await fetch("/api/scal", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(request),
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
};

export function AppScal() {
  return (
    <SirChatsALotProvider productName="My SaaS" api={api}>
      <SirChatsALotLauncher />
      <SirChatsALotWidget />
    </SirChatsALotProvider>
  );
}

Scaffolded setup (scal init)

For Next.js App Router projects, one command scaffolds the route handler, mount component, modes registry, system prompt, and env template:

npx sir-chats-a-lot init

Interactive prompts cover LLM provider (Anthropic / OpenAI), modes (faq / contact / feedback), and knowledge source. Non-interactive:

npx sir-chats-a-lot init --yes --provider anthropic --modes faq,contact --no-gnosys

Then add ANTHROPIC_API_KEY (or OPENAI_API_KEY) to .env.local, mount <ScalMount /> in your root layout, and npm run dev.

Surface Spec CLI

scal surface-spec imports supported Cursor canvas flow dialects into canonical .spec.json files and generates starter SCAL modes/skills from those specs. See docs/SURFACES-CLI.md.

Manual setup

Three pieces beyond mounting the component:

1. A server route that accepts the AgentRequest, calls your LLM with a JSON-only system prompt, and returns an AgentResponse. Import flow helpers from sir-chats-a-lot/server so no React client code is bundled server-side.
2. A knowledge layer so answers are grounded in your content — the default pattern is Gnosys gnosys/web (a zero-dep static index), but any RAG works.
3. An LLM API key as a server env var.

Full guides — surfaces, flows, theming, memory, knowledge wiring, security, and the system prompt template — live at sir-chats-a-lot.com.

License

MIT — see LICENSE.

Disclaimer

You are responsible for your API keys, data handling, abuse prevention, and compliance.