@on-dev/dash-chat

Web → native bridge SDK for the Dash Chat WebView host.

Any web page hosted inside the embedding Android app can use this package to drive the same on-device engines the native chat uses, and to navigate the native host via deep links:

• LLM — on-device language model (window.AiEdgeLlm)
• STT — speech-to-text (window.AiEdgeStt)
• TTS — text-to-speech (window.AiEdgeTts)
• Host navigation — deep links into the app's nav graph

In a plain browser the native bridges are absent: the wrappers return null / false and navigation falls back to a handler you provide, so the same page degrades gracefully.

Author

lonycell, 2026

Install

npm install @on-dev/dash-chat

Usage

Detect the host

import { isEmbedded, isLlmReady, isSttAvailable, isTtsReady } from '@on-dev/dash-chat';

if (isEmbedded()) {
  // running inside the app
}

Stream from the on-device LLM

The on-device session is stateful: it retains the system instruction and prior turns. Set the system instruction once at the start of a session with resetConversation (it lands in the model's real system slot, not folded into a user turn, and clears prior history), then send only the new user turn each time. Await the reset before the first streamPrompt so generation never races the rebuild. Note the session is shared with the app's own chat, so a reset also clears that chat.

import { resetConversation, streamPrompt } from '@on-dev/dash-chat';

await resetConversation('당신은 따뜻한 AI 인터뷰어입니다. …'); // once per session

const gen = streamPrompt('안녕하세요', {
  onToken: (t) => append(t),
  onDone: (full) => finish(full),
  onError: (msg) => showError(msg),
});

// `gen` is null when no bridge is present → fall back to your own generator.
if (!gen) runMockReply();
else cancelButton.onclick = () => gen.cancel();

Tool calling (the page provides & runs the tools)

The model can call tools that your page executes. Register the tools (this enables tool support), include toolCatalogPrompt(...) in the system instruction so the model knows they exist, then chat as usual. Register before resetConversation — the native side binds tools at session reset. Requires a host whose model supports function calling; check with isToolCallingSupported().

import {
  registerTools,
  toolCatalogPrompt,
  resetConversation,
  streamPrompt,
  type ToolSpec,
} from '@on-dev/dash-chat';

const tools: ToolSpec[] = [
  {
    name: 'get_weather',
    description: '도시의 현재 날씨를 반환',
    parameters: { city: 'string' },
    handler: async ({ city }) => (await fetch(`/api/weather?city=${city}`)).json(),
  },
];

const unregister = registerTools(tools); // enables tool support + routes calls to handlers

await resetConversation(`당신은 비서입니다.\n${toolCatalogPrompt(tools)}`);

streamPrompt('서울 날씨 알려줘', {
  onToken: (t) => append(t),
  onDone: (full) => finish(full), // the model called get_weather mid-turn, then answered
  onError: (msg) => showError(msg),
});

// unregister(); // when leaving the session

Speech-to-text / text-to-speech

import { startListening, speak } from '@on-dev/dash-chat';

const session = startListening({
  onPartial: (t) => setDraft(t),
  onResult: (t) => send(t),
  onError: (msg) => showError(msg),
});
session?.stop();

speak('읽어드릴게요', { onDone: () => {}, onError: () => {} });

onStart fires when the first audio actually reaches the speaker — after the voice has loaded and the opening phrase has been synthesized — so it is the right moment to show a page as speaking.

The neural voices are hundreds of megabytes of on-device models, and isTtsReady() says only that the host will accept a request. isTtsPreparing() answers the other question: whether the configured voice is still loading, and the next speak will therefore wait for it.

import { isTtsReady, isTtsPreparing, speak } from '@on-dev/dash-chat';

if (!isTtsReady()) return;               // nothing here can speak — hide the control
button.disabled = false;
button.textContent = isTtsPreparing() ? '준비 중…' : '읽어주기';

speak(text, {
  onStart: () => setSpeaking(true),      // sound has begun, not "request sent"
  onDone: () => setSpeaking(false),
  onError: () => setSpeaking(false),
});

isTtsPreparing() is false on a host that predates it and in a plain browser, so a page that checks it keeps its old behaviour rather than showing a preparing state that never clears.

Host navigation (deep links)

The library renders no UI of its own. Wire a fallback handler once at startup so navigation outside the app surfaces however your app prefers (a toast, a banner, or nothing):

import { configureHost, openHome, openChat, openCharacters, openScreen } from '@on-dev/dash-chat';

configureHost({
  onFallback: (_route, hint) => showToast(hint),
  // Optional overrides (defaults shown):
  // scheme: 'kr.co.utopsoft.ai.ondash',
  // routes: { home: 'home', characters: 'characters', chat: 'mainpage' },
});

openHome();              // leaves the site for the app's landing page (home/hub)
openChat();              // deep-links into the app, or fires the fallback in a browser
openCharacters();
openScreen('settings');  // generic: open any named app screen → `…://open/settings`
openScreen('profile');   // host maps the name; unknown screens are a no-op

Chat engine (turn orchestration)

The low-level wrappers above give you one token / one utterance / one spoken sentence. ChatEngine stitches them into a full voice chat turn loop — message state, streamed replies, sentence-by- sentence TTS with barge-in, push-to-talk STT, muting, a per-session system-prompt reset, and a mock fallback when no model is present. It is framework-agnostic (plain state + a subscribe listener), so it drives a React, other-framework, or vanilla UI. The engine renders no UI of its own.

Only one chat may be active at a time (STT/TTS are single physical resources, and the on-device LLM session is shared with the app's own chat). Starting a session on one engine deactivates any other.

import { ChatEngine, type ChatSessionConfig } from '@on-dev/dash-chat';

const engine = new ChatEngine();
const unsubscribe = engine.subscribe((state) => render(state)); // { messages, listening, thinking, speaking, turns, … }

const config: ChatSessionConfig = {
  id: 'topic-1',                                   // change id to start a new session
  systemPrompt: '당신은 따뜻한 AI 인터뷰어입니다. …', // caller builds the persona
  greeting: '안녕하세요, 오늘은 어떤 이야기를 들려주실래요?',
  buildMockReply: (userText, turn) => '…',          // browser fallback text (optional)
  tools: [                                          // page-executed tools the model may call (optional)
    {
      name: 'pause_interview',
      description: '사용자가 쉬고 싶다고 하면 인터뷰를 일시중지',
      parameters: {},
      handler: () => { showPausedOverlay(); return { ok: true }; },
    },
  ],
};
engine.startSession(config);

engine.sendText('안녕하세요');   // or engine.toggleListening() for push-to-talk
// engine.stopSpeaking(); engine.toggleMuted(); engine.speakText('…');
// engine.dispose(); unsubscribe();   // on teardown

React hooks — @on-dev/dash-chat/react

The React adapter wraps the engine as a hook. It lives behind a subpath so the core stays React-free; add react (>=18) as it is an optional peer dependency.

import { useChat, useLlmStatus } from '@on-dev/dash-chat/react';

function Chat({ topic }: { topic: ChatSessionConfig }) {
  const chat = useChat(topic); // (re)starts the session whenever topic.id changes; disposes on unmount
  const { status, embedded } = useLlmStatus(); // drive a "download the AI brain" prompt

  return (
    <>
      {chat.messages.map((m) => <Bubble key={m.id} role={m.role} text={m.text} />)}
      <button onClick={chat.toggleListening}>{chat.listening ? '멈추기' : '말하기'}</button>
    </>
  );
}

The site keeps what's domain-specific — the persona/prompt, the topic model, any auto-advance policy, and the UI — and maps them into a ChatSessionConfig.

When tools are given, the engine handles the whole tool-calling handshake per session: it registers them before the conversation reset (the native side binds tools at reset), appends toolCatalogPrompt(tools) to the system instruction, and unregisters them on takeover/teardown. On hosts without tool support — and in a plain browser — tools are ignored, so keep UI buttons for anything critical and treat voice-triggered tools as an enhancement.

API

| Export | Kind | Notes | | --- | --- | --- | | ChatEngine | class | Framework-agnostic turn orchestrator. startSession(config), sendText, toggleListening, stopSpeaking, toggleMuted, speakText, subscribe, getState, dispose. | | ChatSessionConfig, ChatState, ChatMessage, ChatRole | types | Engine config / state / message shapes. | | drainSentences / sanitizeForSpeech / extractEmojis | fn | Speech text utils (sentence split for incremental TTS, strip symbols, emoji extraction). | | useChat(config) (/react) | hook | Drives one session; (re)starts on config.id change, disposes on unmount. | | useLlmStatus() (/react) | hook | { status, embedded } for a model-download prompt. | | isEmbedded() | fn | True when any native bridge is injected. | | nextRequestId(prefix) | fn | Unique id for routing bridge callbacks. | | isLlmAvailable() / isLlmReady() | fn | LLM bridge presence / readiness. | | resetConversation(systemInstruction) | fn | Rebuild the session with systemInstruction in the model's system slot, clearing history. Resolves Promise<boolean>. | | streamPrompt(prompt, handlers) | fn | Stream a completion; returns LlmGeneration \| null. | | isToolCallingSupported() | fn | True when the host model supports web tool calling. | | registerTools(tools) | fn | Register page-executed tools the model can call; enables tool support. Call before resetConversation. Returns an unregister fn. | | toolCatalogPrompt(tools) | fn | System-prompt fragment advertising the tools to the model. | | isSttAvailable() | fn | Speech recognizer present. | | startListening(handlers) | fn | Start STT; returns SttSession \| null. | | isTtsReady() | fn | The host will accept a speak. | | isTtsPreparing() | fn | Accepted, but the configured voice is still loading — the next speak waits for it. False on older hosts and in a browser. | | speak(text, handlers) | fn | Speak text; returns TtsUtterance \| null. onStart fires at first audio, not at request. | | configureHost(config) | fn | Set scheme / routes / fallback handler. | | openHostRoute(route) / openHome() / openChat() / openCharacters() / openSettings() | fn | Fixed-route deep-link navigation. openHome() leaves the site for the app's landing page. | | openScreen(screen) | fn | Generic navigation: opens a named app screen via …://open/<screen>. New screens need no SDK change; unknown ones are a host no-op. | | isFilesAvailable() | fn | Native page-owned file storage present. Native-only: in a browser every call below resolves empty / null. | | pickFile(domain, scope, accept?, opts?) | fn | Native picker; the host copies the file into data/<domain>/<scope>/ and returns a StoredFile whose url renders directly — no base64. opts takes onProgress and an AbortSignal. | | listFiles(domain, scope) / deleteFile(…, id) / clearFiles(domain, scope) | fn | Read and remove what the page stored. | | cropImage(domain, scope, fileId, rect) | fn | Crop a stored image to a normalized 0..1 rect; the host does the pixel work off the stored original and saves a new file. | | isSaveImageAvailable() / saveImage(name, dataUrl) | fn | Save a picture the page drew (canvas.toDataURL()) to the device gallery — the only call that carries pixels, and the only way a page can hand a file back at all: a WebView has no download manager, so <a download> saves nothing and reports nothing. | | AiEdgeLlmBridge, AiEdgeSttBridge, AiEdgeTtsBridge, AiEdgeFilesBridge, StoredFile, *Handlers, HostConfig, … | types | |

Develop

npm run build      # bundle ESM + CJS + .d.ts into dist/
npm run dev        # rebuild on change
npm run typecheck  # tsc --noEmit