Skip to content

Inside the panel ​

The chat the user sees is not a Delphi control drawing bubbles: it is one HTML page inside an embedded browser - WebView2 (TEdgeBrowser) in the VCL, TWebBrowser in FireMonkey. This page explains how that page is made, how it talks to the engine with htmx and a little JavaScript, how its buttons reach the events of your Delphi component (and how the component reaches the page), how it is light or dark, and how to change its look with CSS of your own without rebuilding anything.

You do not need any of this to use the component. You need it when you want the chat to look like your application, or when you want to know why it behaves as it does.

The three parts of the panel: header, conversation, footer

The page has three parts, and the rest of this page refers to them:

  1. The header (.hc-chat-header): the name and icon of the assistant, and the buttons that act on the whole conversation - copy, PDF, clear, language, model.
  2. The conversation (#hc-body): the bubbles, rendered by the engine and put in place by htmx. The documentation view (#hc-doc) takes its place when the user opens a page of the manual.
  3. The footer (.hc-chat-footer): the attached files, the clip, the microphone, the question box and the send button.

One page, nothing to deploy ​

The page is four files of the repository, compiled into the library as resources:

FileWhat it is
resources/panel.htmlThe skeleton: header, conversation, documentation view, footer
resources/panel.cssEvery rule of the page, written only in terms of --hc-* variables
resources/panel.jsWhat htmx does not do: polling, commands, menus, clipboard, attachments
resources/htmx.min.jshtmx 2, about 50 KB

Tools\BuildResources.cmd compiles them into source/HelpChatAI.Panel.res, which is linked into your executable. When the panel is opened, the server builds the page by filling the placeholders of panel.html (THelpChatPanel.RenderPage): the language and the labels, the name and the icon of the assistant, the address of the API, a window.HC object with the configuration and the token, the CSS, the theme and the scripts - all inline. There is no external file, no CDN, no font to download: the page works on a machine with no Internet access, and there is nothing to copy next to your executable except WebView2Loader.dll.

The Content Security Policy ​

The page carries a strict policy of its own:

text
default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline';
connect-src 'self' <api> <ui>; img-src 'self' data:; form-action 'self' <api>; base-uri 'none';

It is what makes the panel safe to fill with text a model wrote, and it has consequences you meet as soon as you customize it: the page can only talk to its own server, an image must be a data: URI, and a stylesheet cannot load anything from outside - no @import of a URL, no web font from Google Fonts. A call to an address the policy does not name is dropped by the browser before it reaches the network, without an error.

Where the page comes from ​

With a local engine (the normal case) the component starts a small HTTP server inside your process (Indy), bound to 127.0.0.1 on a random port, and the browser navigates to http://127.0.0.1:<port>/?t=<token>. The token is a secret generated at every start: every request of the page carries it in the X-HelpChat-Token header, so another program on the same machine cannot read the conversation even if it finds the port.

With a remote engine the page is served by that server instead, and the requests meant for the application (close the window, start the microphone) go to a second, loopback channel that the component opens on the client (HC.uiBase). The page does not know the difference: it calls the addresses window.HC gives it.

htmx: the server renders, the page swaps ​

The page has almost no rendering code, because the server sends HTML, not data. Every bubble is produced in Delphi (HelpChatAI.Html): the answer of the model goes through the safe Markdown converter (GFM, raw HTML stripped, URLs checked), the text of the user is escaped, and what reaches the page is a finished fragment:

html
<div class="hc-chat-msg hc-chat-assistant" data-msgid="m12" data-pending="1">
  <div class="hc-chat-bubble"><p>The <strong>Leads</strong> board shows...</p></div>
</div>

That is the whole answer once it is complete: paragraphs, bold, the table the model wrote in Markdown - GFM, because a model answers with tables all the time and CommonMark would print one as a line full of pipes.

An answer of the assistant about the Leads screen: paragraphs, bold and a table

htmx puts those fragments in place, declared by attributes in panel.html. Only three elements are htmx's - the ones whose answer is a piece of conversation; every other button of the panel is wired by panel.js (see every button, and who answers it):

Elementhtmx attributesWhat happens
#hc-body (the conversation)hx-get="/api/history" hx-trigger="load" hx-swap="innerHTML"When the page loads, the whole conversation is asked for and replaces the body - so a reload (a VCL style change recreates the window) always shows what the engine has
#hc-form (the question box)hx-post="/api/send" hx-target="#hc-body" hx-swap="beforeend"Enter posts the question; the server answers with two bubbles - the question and an empty, pending answer - appended at the end
the ↺ buttonhx-post="/api/clear" hx-target="#hc-body" hx-swap="innerHTML"The conversation is cleared and the body replaced by the greeting

panel.js hooks four htmx events, and that is where the behaviour you notice lives:

  • htmx:configRequest adds the token to every request, and intercepts a line that starts with /: a slash command never reaches the model, so the request is cancelled and the command runs instead - a /word that is no command is said to be unknown and stays in its box. A question typed while a file is still going up waits there too, and leaves when the upload is over;
  • htmx:beforeRequest empties the box as soon as the question has been taken (and stops the microphone, if it was listening);
  • htmx:afterSwap scrolls to the end, starts watching any pending answer, adds the copy and PDF buttons beside each answer, and gives the caret back to the box;
  • htmx:responseError / htmx:sendError show the "could not send" notice; a 403 also posts the UI command reload, once (see from the page to Delphi).

What only the page knows - the question being written, the open documentation page and the way back from it, the timing of the last answer - is kept in localStorage under hc-state, tied to the token of the session: a reload (a change of language, a VCL style change) loses nothing, and another run of the application finds nothing.

Streaming without a stream ​

A model answers in seconds, token after token. The engine never waits for it (a worker fills the pending message), and the page follows the answer by polling: while a message carries data-pending, panel.js asks GET /api/poll/<id> every HC.pollMs milliseconds and replaces the bubble with the fragment it gets back - the same message, a little longer each time. When the fragment comes back without data-pending, the answer is complete and the polling stops. The ■ button posts /api/cancel/<id>. A poll the server refuses turns the pending bubble into an error bubble (data-error, .hc-chat-msg-error) instead of leaving the dots there for ever - only a network error is tried again - and after HC.maxPolls polls (900 by default) the page cancels the reply and marks it failed. Polling is plain HTTP, so it works through the same server, the same token and the same policy as everything else, local or remote.

What JavaScript does ​

panel.js (one file, no framework, no build step) handles what is not "send something, swap the answer":

  • the header: the flag of the language and the model in use, with their menus (GET /api/languages, GET /api/assistants, and the two select posts - the paths say "assistant", which is what a model was called before 1.7);
  • the slash commands answered in the page (/use, /lang, /retry, /stats...) and the system bubbles of every command, with the × that removes them;
  • the documentation view: a link to a page of the manual opens inside the panel (GET /api/doc?page=), with its own back button; no link ever navigates the page itself;
  • the clipboard: copying an answer, the conversation or a documentation page puts both HTML and plain text on it, without involving Delphi at all;
  • attachments: the clip, drag and drop anywhere on the panel, the bar of attached files;
  • the question box: it grows with the text, Up/Down browse the previous questions, and every click on a button leaves the caret in the box.

Every button, and who answers it ​

What each button does, when the page shows it, and where the click ends up: in the page alone, in the engine, or in your application.

Header

The five buttons of the header, numbered as in the table

#ButtonShownHandled byWhat happens
1⧉ Copy conversation (#hc-copy)alwayspanel.jsThe conversation goes to the clipboard as HTML and as text; nothing leaves the page
2PDF of the conversation (#hc-pdf)when a PDF can be written (HC.pdf, a listening host)panel.js → POST /api/pdf (kind=conversation)The engine builds the document, the component asks where to save it (OnPdfInfo) and prints it; a remote engine answers 501 and the page says so
3↺ Clearalwayshtmx → POST /api/clearThe engine drops the conversation and its attachments; the body is replaced by the greeting
4The flag (#hc-lang)with two or more Settings.Languagespanel.js → GET /api/languages, POST /api/language/selectThe engine switches language and the page reloads in it; the component rewrites its own captions. A remote engine answers 403
5The model in use (#hc-agent)when it has an icon or Settings.Models lists more than onepanel.js → GET /api/assistants, POST /api/assistant/selectWith more than one, the tooltip adds "Change model", the click opens the list and the choice switches provider and model - for every panel on the same engine. A remote engine answers 403

Beside each answer (.hc-chat-mbtn, added by panel.js once the answer is complete; visible while the pointer or the keyboard focus is on that answer, always on a touch screen)

Copy and PDF beside a complete answer

ButtonShownHandled byWhat happens
⧉ Copy answeron hover or focuspanel.jsThat answer to the clipboard, HTML and text
PDF of the answeron hover or focus, when a PDF can be writtenpanel.js → POST /api/pdf (kind=answer)As for the conversation, one answer only

In the conversation

The answer of a command: a system bubble, with its own colour and its heading

The answer of a command and every notice of the page are system bubbles, with their own colours (--hc-system-bg, --hc-system-text) and, for a command, the heading of what they answer. They are created by panel.js, never stored, and carry a × of their own (1):

ButtonShownHandled byWhat happens
× on a system bubble (.hc-chat-dismiss)on the answer of a command and on every noticepanel.jsThe bubble is removed from the page; it was never stored

Documentation view (#hc-doc, opened by a link to a page of the manual)

A page of the manual inside the panel: back, copy, PDF

#ButtonShownHandled byWhat happens
1← Back (#hc-doc-back)alwayspanel.jsThe previous page of the manual, or back to the conversation
2⧉ Copy page (#hc-doc-copy)alwayspanel.jsThe page to the clipboard, HTML and text
3PDF of the page (#hc-doc-pdf)when a PDF can be writtenpanel.js → POST /api/pdf (kind=page)As for the conversation, the page of the manual

Footer

The footer: a file in the bar, the clip, the microphone, the question box, send

#ButtonShownHandled byWhat happens
1× of an attached file (.hc-chat-attachments)when files are attachedpanel.js → POST /api/attach/removeThe file leaves the conversation: it is not sent with the next questions
2📎 Attach (#hc-clip)when Settings.Attachments.Enabled and the provider reads documentspanel.js → POST /api/attachThe file dialog of the browser (or a file dropped anywhere on the panel); the engine keeps the file with the conversation and sends it with every question
3🎤 Microphone (#hc-mic)only when the host can listen (window.hcVoiceEnable)panel.js → POST /api/ui/mic-start / mic-stopThe component starts the dictation and pushes the text back with window.hcVoiceText
4The question box (#hc-input)alwayspanel.jsIt grows with the text; Enter sends, Shift+Enter starts a new line, Up/Down browse the previous questions
5➤ Send (#hc-send, or Enter)while nothing is being writtenhtmx → POST /api/sendThe question goes to the engine - unless it starts with /: then it is a command, run by the page or by POST /api/command
5■ Stop (#hc-stop), in place of Sendwhile an answer is being writtenpanel.js → POST /api/cancel/{id}The worker stops the request to the model; what was written so far stays

From the page to Delphi ​

The page has no message bridge to its host - FireMonkey's TWebBrowser offers none, and a remote page has no native side at all. What the page asks of the application is an HTTP call:

text
POST /api/ui/<command>      X-HelpChat-Token: ...

The server hands the command to the component with TThread.Queue, so it is executed on the main thread, where your event handlers expect to be.

In the pageRequestIn the component
EscapePOST /api/ui/closeClose: OnBeforeHideHelp, the window hides, OnAfterHideHelp
🎤POST /api/ui/mic-start / mic-stopThe dictation starts or stops; OnVoiceConsentNeeded the first time, OnVoiceText with what it hears
a language chosenPOST /api/language/select (the server then raises the UI command language by itself)The engine switches language; the component rewrites the captions it owns (window, bubble hint); the page reloads
a model chosenPOST /api/assistant/select (the server raises model)OnModelChanged
the server answers 403 (a remote session expired)POST /api/ui/reloadThe component asks its transport for the URL of the panel again and loads the page on the new session
PDF button, /pdfPOST /api/pdfThe engine builds the document, the component asks where to save it (OnPdfInfo fills the bands) and prints it
a link outside the panel(a navigation)The browser control cancels whatever leaves the exact origin of the panel and calls OnOpenLink; unhandled, it opens in the system browser
a request for an action(the model, not the page)OnActionConfirm before it runs, OnActionExecuted after

Two more events are not commands of the page but moments of its life: when the page has loaded (the control's OnPageReady) the component pushes the current theme and the state of the microphone, and gives it the focus if the panel is visible; when the VCL style changes (CM_STYLECHANGED) it pushes the new theme.

From Delphi to the page ​

The other way round, the component runs a line of script in the browser (ExecuteScript of TEdgeBrowser in the VCL, EvaluateJavaScript of TWebBrowser in FireMonkey): the page exposes a handful of window.hc* functions for that, and each method of the component that changes what the user sees goes through one of them.

ComponentIn the page
OpenWithQuestion(question, send), F1 with a questionwindow.hcAsk(text, send)
ExecuteCommand(cmd, args)window.hcCommand(line, true)
OpenDocPage(page)window.hcOpenDoc(page)
ClearConversationwindow.hcRefresh()
SelectModel(name)window.hcRefreshAssistants()
AttachFile(file)window.hcRefreshAttachments()
EnabledCommands := ...window.hcRefreshCommands()
AssistantName, the iconwindow.hcSetAssistant(name, icon)
the theme (style change, OnGetTheme)window.hcApplyTheme({...})
SelectLanguage(language)window.location.reload(): the labels are written into the page when it is rendered
the microphone (VCL only)window.hcVoiceEnable, hcVoiceState, hcVoiceText
a notice, which is a voice error (VCL only)window.hcSystem(text)
focuswindow.hcFocus()

Whatever the user can do in the panel, code can do on the component: that is the rule these functions exist for.

Light and dark ​

Colours are the one thing the page never hard-codes: panel.css uses only --hc-* variables, and three layers decide their values, each overriding the previous one.

  1. The defaults of the page. panel.css defines a light set in :root and a dark set inside @media (prefers-color-scheme: dark), and <meta name="color-scheme" content="light dark"> tells the browser that both are supported (scroll bars, form controls). With no theme from the application, the chat follows the light/dark setting of Windows.
  2. The theme of the application, at load. The component builds a THelpChatTheme - in the VCL from the active VCL style (FollowVclStyle), in FMX from ThemeMode - lets you adjust it in OnGetTheme, and the server writes it into the page as a :root{ --hc-bg: ...; color-scheme: dark; } rule in <style id="hc-theme">, after panel.css. The page is born with the right colours: no flash of white before a dark theme.
  3. The theme at runtime. When the style changes while the chat is open, the component calls window.hcApplyTheme({...}), which sets the variables on the root element - no reload.

The same panel, light and dark - every colour comes from the --hc-* variables, nothing else changes:

The panel with a light themeThe panel with a dark theme

In the VCL the chat (2) takes its colours from the VCL style of the application (1), and follows it when the style changes while the chat is open:

The VCL demo: the chat follows the VCL style of the application

In FireMonkey there is no style to follow, so the application chooses: the FMX demo offers ThemeMode in a combo box (1), and the chat (2) is light, dark or as Windows says:

The FMX demo: the theme of the chat chosen with ThemeMode

The details of how a VCL style becomes seven base colours, and how the rest is derived, are in Colours and theming.

Customizing the look with CSS ​

Colours belong to the theme. Everything else a stylesheet can say - a radius, a spacing, the width of a bubble, a button you do not want - goes in a stylesheet of your application, added to the page after its own:

pascal
HelpChat.PanelStyleSheet := 'helpchat.css';   // next to the executable

PanelStyleSheet is a property of both components, next to PdfStyleSheet. A relative path resolves against the executable; the file is read once, when the component activates, and a named file that is not there stops the activation with EHelpChatConfigError - an application that asked for a look and would run with another is shipped wrong.

The same CSS reaches OnGetTheme as ATheme.StyleSheet, which is also where code writes CSS of its own - built at run time, taken from a resource, or chosen by the user:

pascal
procedure TMainForm.HelpChatGetTheme(Sender: TObject; var ATheme: THelpChatTheme);
begin
  // what the file said, plus a rule decided here
  ATheme.StyleSheet := ATheme.StyleSheet +
    '.hc-chat-bubble { max-width: 95%; }';
end;

It travels with the theme, so it reaches the page at load and at every theme change, and it works with a remote engine too: the client posts it with the colours.

What goes where ​

  • Colours: in the theme. The stylesheet is written before the :root rule of the colours, so a --hc-bg set in it is overridden as soon as the theme sets one. Use OnGetTheme (ATheme.Accent := '#c8102e') for colours: it also derives the matching ones.
  • --hc-radius is yours. The corner radius of the bubbles is a variable the theme never sets: :root { --hc-radius: 4px; } in your stylesheet changes every bubble at once.
  • Everything else: rules on the classes of the page. They are listed below and they are the contract: a class may gain rules from a release to the next, but it is not renamed silently.
  • The policy still applies: no @import url(...), no web fonts from a URL, images only as data: URIs. A font installed on the machine is fine (ATheme.FontFamily, or font-family in a rule).

Examples ​

css
/* Square bubbles, without the hairline */
:root { --hc-radius: 4px; }
.hc-chat-bubble { border-color: transparent; }

/* Use the whole width of a narrow docked panel */
.hc-chat-bubble { max-width: 96%; }
.hc-chat-body { padding: 8px; gap: 6px; }

/* A smaller text, for a dense application */
.hc-chat-app { font-size: 13px; }

/* No copy button in the header: our users must not take the text away */
#hc-copy { display: none; }

/* The answer of a command in italics */
.hc-chat-system .hc-chat-bubble { font-style: italic; }

The classes of the page ​

SelectorWhat it is
.hc-chat-appThe whole panel
.hc-chat-header, .hc-chat-brand, .hc-chat-title, .hc-chat-iconThe header, the name and icon of the assistant
.hc-chat-hbtnEvery button of the header (#hc-copy, #hc-pdf, #hc-lang, #hc-agent, ↺)
.hc-chat-agentsThe drop-down lists of models (#hc-agents) and languages (#hc-langs)
.hc-chat-body (#hc-body)The conversation
.hc-chat-msgOne message (row); with .hc-chat-user, .hc-chat-assistant, .hc-chat-system, .hc-chat-greeting, .hc-chat-msg-error
.hc-chat-bubbleThe bubble inside a message
.hc-chat-mbtnThe copy and PDF buttons under an answer
[data-pending]A message still being written
.hc-chat-dismissThe × of a system bubble
.hc-chat-cmd-titleThe heading of the answer of a command
.hc-chat-promptThe system prompt shown by /prompt
.hc-chat-doc, .hc-chat-doc-bar, .hc-chat-doc-bodyThe documentation view
.hc-chat-footer, #hc-formThe footer and the question form
.hc-chat-input (#hc-input)The question box
.hc-chat-send (#hc-send, #hc-stop)Send and stop
.hc-chat-mic (#hc-mic, #hc-clip)Microphone and attachments
.hc-chat-attachmentsThe bar of attached files

The variables, all set by the theme except --hc-radius: --hc-bg, --hc-surface, --hc-text, --hc-muted, --hc-border, --hc-accent, --hc-accent-text, --hc-user-bg, --hc-user-text, --hc-assistant-bg, --hc-assistant-text, --hc-system-bg, --hc-system-text, --hc-error-bg, --hc-error-text, --hc-code-bg, --hc-link (links and focus rings), --hc-shadow, --hc-font, --hc-radius.

Changing the page itself ​

When a stylesheet is not enough - a different layout of the header, a new element - the page can be changed at the source: edit resources/panel.html, panel.css or panel.js, run Tools\BuildResources.cmd and rebuild. You then own a fork of the page, to merge at every release. Two rules keep it working: never write a colour outside the --hc-* definitions, and name every new outbound address in the Content Security Policy.

Released under the Apache License 2.0