@hibira-io/chat-ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hibira
+
+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/PROTOCOL.md

@@ -0,0 +1,71 @@
+# Chat protocol v1
+
+How the `@hibira-io/chat-ui` components talk to your backend and to a
+[Hibira](https://hibira.io) channel. Any backend can implement it; the
+`server` helpers do the channel side for Node.
+
+## Principles
+
+- **Your backend stores messages.** Pages read them over HTTPS from your
+  routes (the `load` and `send` functions you pass to `createConversation`).
+- **The channel carries hints only**: small events that say "something
+  changed". A page that misses one catches up on its next poll, so a lost
+  event never loses a message, and message text never crosses the socket.
+- One channel per conversation. Use a private channel (for example
+  `private-chat.{conversationId}`) and authorize only the people in it.
+
+## Message
+
+```json
+{
+  "id": "msg_01",
+  "seq": 7,
+  "sender": "agent",
+  "name": "Support",
+  "text": "Markdown text",
+  "created_at": "2026-10-31T12:00:00Z",
+  "metadata": { "assistant": true, "suggestions": ["Is there a free plan?"] }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `seq` | Position in the conversation, increasing by one. Pages ask for messages after the last `seq` they have. |
+| `sender` | `customer` for the person using the chat (the page's `me`), anything else for your side (`agent`, `operator`, ...). |
+| `text` | Markdown. Pages render it without HTML (see the README). |
+| `metadata.assistant` | `true` on a reply your agent wrote: shown as an automatic reply. |
+| `metadata.handoff` | `true` when the agent passed the conversation to a person. |
+| `metadata.suggestions` | Up to 3 follow-up questions; the customer sends one with a tap. Clean them with `cleanSuggestions()`. |
+
+## Routes (yours)
+
+- `load(after)`: return `{ messages: Message[] }` with the messages whose
+  `seq > after`, oldest first. Anything else you return (status, read
+  marks) shows up as `state.extra`.
+- `send(text)`: store the customer's message and return it (or
+  `{ message }`). Then send the `message` hint.
+
+## Events on the conversation's channel
+
+| Event | Data | Sent when |
+| --- | --- | --- |
+| `message` | `{ "seq": 7, "from": "agent" }` | A message was stored. Pages read what they have not seen. |
+| `typing` | `{ "from": "agent", "step": "writing" }` | Someone is writing. Repeat every ~4 s while it lasts; pages hide it after 8 s without one, or when that side's message arrives. |
+| anything else | your data | Passed to `onEvent` (status changes, read marks, ...). |
+
+### Agent steps
+
+While your agent writes a reply, send `typing` with a `step` each time it
+moves on. Pages show the steps so far with a check and the current one with
+a spinner. Send only steps your agent really takes:
+
+| Step | Shown as (en) |
+| --- | --- |
+| `reading` | Reading your question |
+| `account` | Looking at your account |
+| `searching` | Searching our docs |
+| `writing` | Writing a reply |
+| `checking` | Checking the reply |
+
+Other step names show as plain typing unless you add labels for them
+(`labels.steps`).

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
+# chat-ui
 
-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.
+A small, open-source chat interface for support conversations where an AI agent answers first and a person steps in when needed. It shows what the agent is doing while it writes, renders safe Markdown, offers follow-up questions, and marks when a conversation is handed to your team.
+
+![A support conversation with an automatic reply, a code block and suggested follow-up questions](art/thread-en-desktop-light.png)
+
+| Agent steps (zh-TW, mobile) | Handed to a person (ja, dark) |
+| --- | --- |
+| ![Agent steps while a reply is written](art/steps-zh-TW-mobile-light.png) | ![A reply marked as passed to the team](art/handoff-ja-mobile-dark.png) |
+
+- **Agent steps**: "Reading your question", "Looking at your account", "Writing a reply"… shown live, from hints your backend sends.
+- **Safe Markdown**: parsed into elements, never HTML. Only http(s), mailto and same-site links; images show inline only from origins you allow.
+- **Follow-up suggestions**: up to three short questions the customer can send with one tap.
+- **Handoff**: a reply can say it was passed to a person, and the badge shows it.
+- **Typewriter reveal**, copy buttons on replies and code blocks, a "Seen" marker.
+- **Seven languages** built in: en, zh-TW, zh-CN, ja, ko, th, vi.
+- **Small**: about 9 KB of JavaScript and 2 KB of CSS gzipped, no runtime dependencies. React is an optional peer.
+
+It works with any backend. Messages live in your database and are read over HTTPS; a realtime channel on [Hibira](https://hibira.io) (or any Pusher-compatible service) only carries hints, so a missed event costs a poll, never a message. See [PROTOCOL.md](PROTOCOL.md).
+
+## Install
+
+```sh
+npm install @hibira-io/chat-ui pusher-js
+```
+
+## React
+
+```jsx
+import { useEffect } from 'react';
+import Pusher from 'pusher-js';
+import { Chat, createConversation } from '@hibira-io/chat-ui/react';
+import '@hibira-io/chat-ui/styles.css';
+
+const pusher = new Pusher('YOUR_APP_KEY', { wsHost: 'ws.hibira.io', forceTLS: true, cluster: '' });
+
+const conversation = createConversation({
+  pusher,
+  channel: `private-conversation-${conversationId}`,
+  load: (after, signal) => fetch(`/api/conversations/${conversationId}/messages?after=${after}`, { signal }).then((r) => r.json()),
+  send: (text) =>
+    fetch(`/api/conversations/${conversationId}/messages`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text }),
+    }).then((r) => r.json()),
+});
+
+export function SupportChat() {
+  useEffect(() => conversation.start(), []);
+  return <Chat conversation={conversation} locale="ja" />;
+}
+```
+
+`load(after)` returns `{ messages: [...] }` with every message whose `seq` is greater than `after`. A message looks like:
+
+```js
+{
+  seq: 12,
+  sender: 'agent',            // or 'customer'; `me` (default "customer") is the person on this page
+  text: 'Here is how to **rotate** a key…',
+  created_at: '2026-10-31T09:00:00Z',
+  metadata: { assistant: true, suggestions: ['How do I revoke the old key?'] },
+}
+```
+
+The pieces are exported on their own too: `ChatThread` (controlled: pass `messages`, `typing`, `step`, `onSend`), `Markdown`, `AgentSteps`, `Suggestions`, `CopyButton` and `useReveal`.
+
+## Without a framework
+
+```js
+import { createConversation, parseMarkdown } from '@hibira-io/chat-ui';
+
+const conversation = createConversation({ pusher, channel, load, send });
+conversation.subscribe((state) => render(state)); // { messages, loading, error, typing, step }
+conversation.start();
+```
+
+`parseMarkdown(text, { origin, imageOrigins })` returns a plain block tree you can render with anything.
+
+## Server (Node)
+
+```js
+import Pusher from 'pusher';
+import { createChatServer, agentMetadata } from '@hibira-io/chat-ui/server';
+
+const pusher = new Pusher({ appId, key, secret, host: 'api.hibira.io', useTLS: true });
+const chat = createChatServer({ pusher });
+
+const typing = chat.agentTyping(channel);       // "Reading your question", repeated every 4 s
+typing.step('account');                         // "Looking at your account"
+const answer = await yourAgent(question);
+typing.step('writing');
+typing.step('checking');
+const msg = await db.saveMessage({
+  sender: 'agent',
+  text: answer.text,
+  metadata: agentMetadata({ handoff: answer.handoff, suggestions: answer.suggestions }),
+});
+typing.stop();
+await chat.message(channel, { seq: msg.seq, from: 'agent' });
+```
+
+`agentMetadata` keeps at most three short suggestions and drops any with links, line breaks or markup, since the customer sends them as their own words. Only send the steps your agent really goes through.
+
+## Styling
+
+Every color is a CSS variable on `.hb-chat`:
+
+```css
+.hb-chat {
+  --hb-chat-accent: #3e63dd;
+  --hb-chat-radius: 10px;
+  --hb-chat-max-height: 480px;
+}
+```
+
+Dark mode follows `prefers-color-scheme`, or set `data-theme="dark"` / `"light"` on any ancestor. Labels can be overridden one by one with `labels={{ handoff: 'With our support team' }}`.
+
+## Safety
+
+- Message text is never inserted as HTML.
+- Links open only for `http:`, `https:`, `mailto:` and same-site paths, with `rel="noopener noreferrer"`.
+- Images render inline only from `origin` and `imageOrigins`; any other image becomes a plain link, so a message cannot make the page load third-party content.
+- Treat replies from your agent as untrusted text, like any customer message.
+
+## License
+
+MIT © Hibira

package/conversation.js

@@ -0,0 +1,188 @@
+// A conversation kept up to date in the browser, without a UI framework.
+//
+// Messages are read from your backend (`load`), never from the socket:
+// events on the conversation's channel are hints (PROTOCOL.md). A `message`
+// hint makes it read what it has not seen; a `typing` hint shows that the
+// other side (a person or your agent) is writing, with the agent's `step`.
+// A missed event costs a poll, never a message: it polls slowly while the
+// socket is up and every few seconds without one.
+
+/** What an agent can be doing while it writes a reply, in order (PROTOCOL.md). */
+export const STEPS = Object.freeze(['reading', 'account', 'searching', 'writing', 'checking']);
+
+/** Polling intervals, with the socket connected (a safety net) and without. */
+export const POLL_LIVE_MS = 60_000;
+export const POLL_MS = 10_000;
+/** How long a typing hint shows without another one. */
+export const TYPING_SHOW_MS = 8_000;
+
+/** Merges a page of messages into a list ordered by seq, without repeats. */
+export function mergeMessages(list, page) {
+  if (!page?.length) return list;
+  const bySeq = new Map(list.map((m) => [m.seq, m]));
+  for (const m of page) bySeq.set(m.seq, m);
+  return [...bySeq.values()].sort((a, b) => a.seq - b.seq);
+}
+
+export const lastSeq = (list) => (list.length ? list[list.length - 1].seq : 0);
+
+/** An automatic reply (your agent marks it in metadata). */
+export const isAutomatic = (m) => !!m?.metadata?.assistant;
+
+/**
+ * @param {{
+ *   load: (after: number, signal: AbortSignal) => Promise<{ messages: any[] } & Record<string, any>>,
+ *   send?: (text: string) => Promise<any>,
+ *   pusher?: any,
+ *   channel?: string,
+ *   me?: string,
+ *   pollMs?: number,
+ *   livePollMs?: number,
+ *   onEvent?: (event: string, data: any) => void,
+ * }} options
+ */
+export function createConversation(options) {
+  if (typeof options?.load !== 'function') throw new TypeError('createConversation() needs a load(after, signal) function.');
+  const me = options.me ?? 'customer';
+  const pollMs = options.pollMs ?? POLL_MS;
+  const livePollMs = options.livePollMs ?? POLL_LIVE_MS;
+  let state = { messages: [], loading: true, error: null, typing: false, step: undefined, extra: {} };
+  const listeners = new Set();
+  let timer = null;
+  let typingTimer = null;
+  let abort = null;
+  let inflight = null;
+  let again = false;
+  let stopped = true;
+  let unbind = [];
+
+  const set = (patch) => {
+    state = { ...state, ...patch };
+    listeners.forEach((fn) => fn(state));
+  };
+
+  const connected = () => options.pusher?.connection?.state === 'connected';
+
+  function schedule() {
+    if (stopped) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => void refresh(), connected() ? livePollMs : pollMs);
+  }
+
+  function setTyping(on, step) {
+    clearTimeout(typingTimer);
+    typingTimer = on ? setTimeout(() => setTyping(false), TYPING_SHOW_MS) : null;
+    const next = on ? step : undefined;
+    if (state.typing !== on || state.step !== next) set({ typing: on, step: next });
+  }
+
+  function onHint(event, data) {
+    const d = data && typeof data === 'object' ? data : {};
+    if (event === 'typing') {
+      if (d.from !== me) setTyping(true, typeof d.step === 'string' ? d.step : undefined);
+      return;
+    }
+    if (event === 'message') {
+      if (d.from !== me) setTyping(false);
+      if (typeof d.seq === 'number' && d.seq <= lastSeq(state.messages)) return;
+      void refresh();
+      return;
+    }
+    options.onEvent?.(event, d);
+  }
+
+  /** Reads what is new; calls made while one runs fold into one more. */
+  function refresh() {
+    if (stopped) return Promise.resolve();
+    if (inflight) {
+      again = true;
+      return inflight;
+    }
+    const run = async () => {
+      do {
+        again = false;
+        abort = new AbortController();
+        try {
+          const { messages = [], ...extra } = await options.load(lastSeq(state.messages), abort.signal);
+          if (stopped) return;
+          set({ messages: mergeMessages(state.messages, messages), extra: { ...state.extra, ...extra }, error: null, loading: false });
+        } catch (err) {
+          if (stopped || err?.name === 'AbortError') return;
+          set({ error: err, loading: false });
+        }
+      } while (again && !stopped);
+    };
+    inflight = run().finally(() => {
+      inflight = null;
+      schedule();
+    });
+    return inflight;
+  }
+
+  function start() {
+    if (!stopped) return stop;
+    stopped = false;
+    const { pusher, channel } = options;
+    if (pusher && channel) {
+      const ch = pusher.subscribe(channel);
+      const global = (event, data) => {
+        if (event.startsWith('pusher:') || event.startsWith('pusher_internal:')) return;
+        onHint(event, data);
+      };
+      const subscribed = () => void refresh();
+      ch.bind_global(global);
+      ch.bind('pusher:subscription_succeeded', subscribed);
+      const state = () => schedule();
+      pusher.connection?.bind?.('state_change', state);
+      unbind.push(() => {
+        ch.unbind_global(global);
+        ch.unbind('pusher:subscription_succeeded', subscribed);
+        pusher.connection?.unbind?.('state_change', state);
+      });
+    }
+    if (typeof document !== 'undefined') {
+      const vis = () => document.visibilityState === 'visible' && void refresh();
+      document.addEventListener('visibilitychange', vis);
+      unbind.push(() => document.removeEventListener('visibilitychange', vis));
+    }
+    void refresh();
+    return stop;
+  }
+
+  function stop() {
+    stopped = true;
+    clearTimeout(timer);
+    clearTimeout(typingTimer);
+    abort?.abort();
+    unbind.forEach((fn) => fn());
+    unbind = [];
+  }
+
+  /** Adds a message the page just sent (the server's copy). */
+  function added(message) {
+    if (message && typeof message.seq === 'number') set({ messages: mergeMessages(state.messages, [message]) });
+  }
+
+  /** Sends through options.send and adds the message it returns. */
+  async function send(text) {
+    if (!options.send) throw new Error('createConversation() has no send(text) function.');
+    const out = await options.send(text);
+    added(out?.message ?? out);
+    return out;
+  }
+
+  return {
+    get: () => state,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start,
+    stop,
+    refresh,
+    added,
+    send,
+    /** For tests and custom transports: deliver a hint as if from the channel. */
+    hint: onHint,
+  };
+}

package/index.d.ts

@@ -0,0 +1,22 @@
+import type { Block, ChatLabels, ChatMessage, Conversation, ConversationOptions, InlineNode, LabelOverrides, MarkdownOptions } from './types.js';
+
+export type * from './types.js';
+
+export function parseMarkdown(text: string, options?: MarkdownOptions): Block[];
+export function parseInline(text: string, options?: MarkdownOptions): InlineNode[];
+export function plainText(text: string): string;
+export function safeHref(url: string): string | null;
+export function imageSrc(url: string, options?: MarkdownOptions): string | null;
+
+export function createConversation(options: ConversationOptions): Conversation;
+export function mergeMessages(list: ChatMessage[], page: ChatMessage[]): ChatMessage[];
+export function lastSeq(list: ChatMessage[]): number;
+export function isAutomatic(message: ChatMessage | undefined | null): boolean;
+export const STEPS: readonly string[];
+export const POLL_MS: number;
+export const POLL_LIVE_MS: number;
+export const TYPING_SHOW_MS: number;
+
+export const LOCALES: Record<'en' | 'zh-TW' | 'zh-CN' | 'ja' | 'ko' | 'th' | 'vi', ChatLabels>;
+export function labelsFor(locale?: string, overrides?: LabelOverrides): ChatLabels;
+export function format(text: string, vars?: Record<string, string | number>): string;

package/index.js

@@ -0,0 +1,7 @@
+// Framework-free core: Markdown as data, the conversation store, labels.
+// React components: '@hibira-io/chat-ui/react'. Server helpers:
+// '@hibira-io/chat-ui/server'.
+
+export { parseMarkdown, parseInline, plainText, safeHref, imageSrc } from './markdown.js';
+export { createConversation, mergeMessages, lastSeq, isAutomatic, STEPS, POLL_MS, POLL_LIVE_MS, TYPING_SHOW_MS } from './conversation.js';
+export { labelsFor, LOCALES, format } from './locales.js';

package/locales.js

@@ -0,0 +1,173 @@
+// Labels for the bundled components. Pass `locale` to pick one, or `labels`
+// to override single strings.
+
+const en = {
+  placeholder: 'Write a message…',
+  send: 'Send',
+  typing: 'Typing…',
+  automatic: 'Automatic reply',
+  handoff: 'Passed to our team',
+  suggestions: 'You might also ask',
+  copy: 'Copy',
+  copied: 'Copied',
+  copyCode: 'Copy code',
+  seen: 'Seen',
+  empty: 'Ask us anything.',
+  tooLong: 'Keep a message under {n} characters.',
+  steps: {
+    reading: 'Reading your question',
+    account: 'Looking at your account',
+    searching: 'Searching our docs',
+    writing: 'Writing a reply',
+    checking: 'Checking the reply',
+  },
+};
+
+const zhTW = {
+  placeholder: '輸入訊息…',
+  send: '送出',
+  typing: '正在輸入…',
+  automatic: '自動回覆',
+  handoff: '已轉交團隊',
+  suggestions: '你可能還想問',
+  copy: '複製',
+  copied: '已複製',
+  copyCode: '複製程式碼',
+  seen: '已讀',
+  empty: '有任何問題都可以問我們。',
+  tooLong: '每則訊息請少於 {n} 個字元。',
+  steps: {
+    reading: '正在閱讀你的問題',
+    account: '正在查看你的帳戶',
+    searching: '正在搜尋文件',
+    writing: '正在撰寫回覆',
+    checking: '正在檢查回覆',
+  },
+};
+
+const zhCN = {
+  placeholder: '输入消息…',
+  send: '发送',
+  typing: '正在输入…',
+  automatic: '自动回复',
+  handoff: '已转交团队',
+  suggestions: '你可能还想问',
+  copy: '复制',
+  copied: '已复制',
+  copyCode: '复制代码',
+  seen: '已读',
+  empty: '有任何问题都可以问我们。',
+  tooLong: '每条消息请少于 {n} 个字符。',
+  steps: {
+    reading: '正在阅读你的问题',
+    account: '正在查看你的账户',
+    searching: '正在搜索文档',
+    writing: '正在撰写回复',
+    checking: '正在检查回复',
+  },
+};
+
+const ja = {
+  placeholder: 'メッセージを入力…',
+  send: '送信',
+  typing: '入力中…',
+  automatic: '自動応答',
+  handoff: '担当チームに引き継ぎ済み',
+  suggestions: 'こちらもよく聞かれます',
+  copy: 'コピー',
+  copied: 'コピーしました',
+  copyCode: 'コードをコピー',
+  seen: '既読',
+  empty: 'お気軽にご質問ください。',
+  tooLong: 'メッセージは {n} 文字未満にしてください。',
+  steps: {
+    reading: 'ご質問を確認しています',
+    account: 'アカウントを確認しています',
+    searching: 'ドキュメントを検索しています',
+    writing: '回答を作成しています',
+    checking: '回答をチェックしています',
+  },
+};
+
+const ko = {
+  placeholder: '메시지를 입력하세요…',
+  send: '보내기',
+  typing: '입력 중…',
+  automatic: '자동 답변',
+  handoff: '담당 팀에 전달됨',
+  suggestions: '이런 질문도 있어요',
+  copy: '복사',
+  copied: '복사됨',
+  copyCode: '코드 복사',
+  seen: '읽음',
+  empty: '무엇이든 물어보세요.',
+  tooLong: '메시지는 {n}자 미만으로 써 주세요.',
+  steps: {
+    reading: '질문을 읽고 있어요',
+    account: '계정을 확인하고 있어요',
+    searching: '문서를 찾고 있어요',
+    writing: '답변을 작성하고 있어요',
+    checking: '답변을 확인하고 있어요',
+  },
+};
+
+const th = {
+  placeholder: 'พิมพ์ข้อความ…',
+  send: 'ส่ง',
+  typing: 'กำลังพิมพ์…',
+  automatic: 'ตอบกลับอัตโนมัติ',
+  handoff: 'ส่งต่อให้ทีมงานแล้ว',
+  suggestions: 'คุณอาจอยากถามต่อ',
+  copy: 'คัดลอก',
+  copied: 'คัดลอกแล้ว',
+  copyCode: 'คัดลอกโค้ด',
+  seen: 'อ่านแล้ว',
+  empty: 'ถามเราได้ทุกเรื่อง',
+  tooLong: 'โปรดเขียนข้อความไม่เกิน {n} ตัวอักษร',
+  steps: {
+    reading: 'กำลังอ่านคำถามของคุณ',
+    account: 'กำลังดูบัญชีของคุณ',
+    searching: 'กำลังค้นหาในเอกสาร',
+    writing: 'กำลังเขียนคำตอบ',
+    checking: 'กำลังตรวจสอบคำตอบ',
+  },
+};
+
+const vi = {
+  placeholder: 'Nhập tin nhắn…',
+  send: 'Gửi',
+  typing: 'Đang nhập…',
+  automatic: 'Trả lời tự động',
+  handoff: 'Đã chuyển cho đội ngũ',
+  suggestions: 'Bạn cũng có thể hỏi',
+  copy: 'Sao chép',
+  copied: 'Đã sao chép',
+  copyCode: 'Sao chép mã',
+  seen: 'Đã xem',
+  empty: 'Hãy hỏi chúng tôi bất cứ điều gì.',
+  tooLong: 'Tin nhắn cần ít hơn {n} ký tự.',
+  steps: {
+    reading: 'Đang đọc câu hỏi của bạn',
+    account: 'Đang xem tài khoản của bạn',
+    searching: 'Đang tìm trong tài liệu',
+    writing: 'Đang viết câu trả lời',
+    checking: 'Đang kiểm tra câu trả lời',
+  },
+};
+
+export const LOCALES = { en, 'zh-TW': zhTW, 'zh-CN': zhCN, ja, ko, th, vi };
+
+/** The labels for a locale ("ja", "zh-Hant-TW", "pt" falls back to English), with overrides. */
+export function labelsFor(locale, overrides) {
+  const tag = String(locale ?? 'en');
+  let base = LOCALES[tag];
+  if (!base) {
+    const lower = tag.toLowerCase();
+    if (lower.startsWith('zh')) base = /hant|tw|hk|mo/.test(lower) ? zhTW : zhCN;
+    else base = LOCALES[lower.split('-')[0]] ?? en;
+  }
+  return { ...base, ...overrides, steps: { ...base.steps, ...overrides?.steps } };
+}
+
+/** Fills {name} placeholders. */
+export const format = (s, vars = {}) => String(s).replace(/\{(\w+)\}/g, (m, k) => (k in vars ? String(vars[k]) : m));