Components

Web Components with shadow DOM, for plain HTML or any framework.

Registering the elements

In plain HTML, load the auto entry from a CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/@neocortex-link/web@0.2/dist/ui/auto.js"></script>

defineNeocortexElements() is idempotent and a no-op outside the browser, so it is SSR-safe.

Elements

voice is on when present and off when absent or set to "false". history and mic are on unless set to "false". The other boolean attributes (push-to-talk, no-header, disabled, active) are on whenever present, whatever their value.

neocortex-chat

<neocortex-chat endpoint="/api/neocortex" character-id="your-character-id" voice></neocortex-chat>

Properties and methods

• agent is the SmartAgent behind the element. Register actions or listen to its events on it.
• client gets or sets the NeocortexClient the element uses. Setting it overrides endpoint and starts a new agent.
• reset() stops the current reply, forgets the conversation and clears the panel. The header's reset button does the same.

const chat = document.querySelector("neocortex-chat");
chat.agent.registerAction("OPEN_DOOR", (action) => door.open(action.targetId));

Changing character-id, endpoint or client creates a new agent; register handlers again. The conversation persists in localStorage.

neocortex-group-chat

<neocortex-group-chat endpoint="/api/neocortex" character-ids="aria,bram" voice></neocortex-group-chat>

Takes the same attributes as <neocortex-chat>, with these instead of character-id:

Each character's name and bubble accent get their own colour. The header has a Let them talk button that lets the characters carry on without the player. agent is a GroupDirector. See Group Chat for a walkthrough.

neocortex-quiz

<neocortex-quiz endpoint="/api/neocortex" character-id="host-id" question-set-id="set-id" voice></neocortex-quiz>

The player answers by clicking an option, typing or speaking, and can ask for a hint or pass. The element reflects its phase in a state attribute: idle, playing or finished. agent is a QuizAgent.

See Quiz for a walkthrough.

neocortex-chat-panel

A scrolling message list with a thinking indicator at the end. Use it to build your own chat layout.

neocortex-message

One bubble. Text is always set as text, never parsed as HTML.

neocortex-text-input

Fires nx-send with { text } when the player submits. Call preventDefault() on it to keep the text in the box. It also has a value property and a focus() method.

neocortex-mic-button

Click to listen, and recording stops after a pause. With push-to-talk, hold it with the pointer, Space or Enter.

The element reflects its state in a state attribute: idle, listening or recording. It has a receiver property (the AudioReceiver behind it) and toggle() and stop() methods. The button is disabled in browsers that cannot record audio.

neocortex-mic-select

Lists microphones and switches the one a mic button records from. Device names appear once microphone permission has been granted, and the choice is remembered for the next visit.

<neocortex-mic-button id="mic"></neocortex-mic-button>
<neocortex-mic-select for="mic"></neocortex-mic-select>

Point it at a mic button with for="<id>", or set its receiver property to an AudioReceiver. refresh() re-reads the device list.

neocortex-thinking

Three bouncing dots, hidden unless active is set.

neocortex-usage-badge

A status pill that shows whether characters are available, running low, or resting because credits or a per-player or per-character cap ran out.

The element reflects the result in a status attribute: ok, low, empty, or unknown when the check failed. See UsageGate to gate your own UI.

Events

Events are CustomEvents that bubble out of shadow DOM, so you can listen on the element or any ancestor. The payload is in event.detail.

Emotions are camelCase, for example happy or curious. By default nx-action fires as soon as the reply arrives, before it is played. Change that with the agent's actionTrigger.

The chat and quiz elements show a short notice in the conversation when something goes wrong. Call preventDefault() on nx-error to show your own instead. This covers microphone errors too.

chat.addEventListener("nx-error", (event) => {
  event.preventDefault();
  toast(event.detail.error.message);
});

The built-in text input and mic button sit inside the chat and quiz elements, so their nx-send, nx-recorded and nx-error events bubble out of those elements too.

Theming

Every colour is a CSS custom property. Set them on the element or any ancestor:

neocortex-chat {
  --nx-accent: #7c3aed;
  --nx-character-bubble: #1e1b4b;
  --nx-radius: 20px;
  --nx-font: "Inter", sans-serif;
  height: 600px;
}

<neocortex-chat> is 32rem tall and <neocortex-quiz> is 36rem by default. Set height on the element to change it.

Light, dark and right-to-left

Elements follow the visitor's prefers-color-scheme. Set theme="light" or theme="dark" on an element to choose one; the chat, group chat, quiz and panel elements pass it on to everything inside them. To set exact colours, use the --nx-* tokens, which also reach every nested element.

The layout uses logical CSS properties, so the elements respect dir="rtl" on the element or the page. They also honour prefers-reduced-motion.

Parts

Internals are exposed with ::part():

neocortex-chat::part(header) { display: none; }
neocortex-chat::part(footer) { padding: 1rem; }
neocortex-chat::part(bubble) { font-size: 1.05rem; }
neocortex-chat::part(player) { --nx-player-bubble: #2563eb; }

The chat, group chat and quiz elements forward the parts of the elements inside them, so you can style those from the page too:

Auth headers

Requests carry your site's cookies by default (same origin only). If your proxy expects a token instead, give every element one client that sends it. It applies to every element without an endpoint attribute, including ones already on the page:

import { NeocortexClient, setDefaultClient } from "@neocortex-link/web/ui";

setDefaultClient(
  new NeocortexClient({
    baseUrl: "/api/neocortex",
    headers: () => ({ authorization: `Bearer ${getToken()}` }),
  }),
);

headers can be an object or a function that is called for every request. To give a single element its own client, set its client property instead.

Actions

document.querySelector("neocortex-chat").agent.registerAction("OPEN_DOOR", (action) => doors.get(action.targetId)?.open());

See Interactables.