Widget script tag

The Cortex widget is a single auto-initializing <script> tag. It mounts a floating launcher into a fresh <div> it appends to <body>, with all UI inside an open shadow root so host-page CSS can’t bleed in.

Canonical snippet

<script
  src="https://cdn.cortexlayer.dev/widget.v1.js"
  integrity="sha384-EsA2JT5EXb3PH2k87CX4d7W764dt2ljIUpXKg+37GpWAvY+hR9tFAJnrsTvaKAuh"
  crossorigin="anonymous"
  data-cortex-widget
  data-api-base="https://api.cortexlayer.dev"
  data-agent-id="agt_REPLACE_ME"
  data-session-token="cs_REPLACE_ME"
></script>

integrity is generated at docs build time from the live bundle on the CDN — copy this verbatim into your page.

Required attributes

Attribute	Description
`src`	The CDN URL. Pinned per major version (`widget.v1.js`); we serve it `Cache-Control: immutable` for one year.
`integrity`	The bundle’s `sha384` hash. The browser refuses to execute a non-matching bundle (defense against CDN compromise).
`crossorigin`	Must be `"anonymous"` for `integrity` to take effect.
`data-cortex-widget`	Marker attribute the widget’s auto-init scans for. No value needed.
`data-api-base`	Cortex API origin. `https://api.cortexlayer.dev` in production.
`data-agent-id`	The agent ID returned by `POST /v1/agents`.
`data-session-token`	A short-lived session token from `POST /v1/widget/session`. Mint it server-side and inject into the page.

Optional attributes

Attribute	Default	Description
`data-accent`	brand blue	Any CSS color. Drives the launcher background, send button, and user-bubble accents.
`data-position`	`bottom-right`	One of `bottom-right`, `bottom-left`, `top-right`, `top-left`.
`data-greeting`	”Hi! How can I help today?”	Shown when the panel first opens with an empty conversation.
`data-input-placeholder`	”Ask anything…”	Composer placeholder text.

Examples

Dark accent, bottom-left launcher:

<script
  src="https://cdn.cortexlayer.dev/widget.v1.js"
  integrity="sha384-EsA2JT5EXb3PH2k87CX4d7W764dt2ljIUpXKg+37GpWAvY+hR9tFAJnrsTvaKAuh"
  crossorigin="anonymous"
  data-cortex-widget
  data-api-base="https://api.cortexlayer.dev"
  data-agent-id="agt_REPLACE_ME"
  data-session-token="cs_REPLACE_ME"
  data-accent="#1a1a1a"
  data-position="bottom-left"
></script>

Brand-themed with a custom greeting (escape quotes per HTML rules):

<script
  src="https://cdn.cortexlayer.dev/widget.v1.js"
  integrity="sha384-EsA2JT5EXb3PH2k87CX4d7W764dt2ljIUpXKg+37GpWAvY+hR9tFAJnrsTvaKAuh"
  crossorigin="anonymous"
  data-cortex-widget
  data-api-base="https://api.cortexlayer.dev"
  data-agent-id="agt_REPLACE_ME"
  data-session-token="cs_REPLACE_ME"
  data-accent="#7c3aed"
></script>

CSP requirements

The widget runs under any reasonably strict CSP. Your script-src needs to allow the CDN origin and the bundle’s hash:

script-src 'self' https://cdn.cortexlayer.dev 'sha384-...';
connect-src https://api.cortexlayer.dev;
img-src data: https:;

'sha384-...' is the same hash from the integrity attribute. With 'strict-dynamic' set, the hash alone is enough — https://cdn.cortexlayer.dev becomes optional.

Programmatic init

If auto-init doesn’t fit (SPAs that mount on route change, conditional rendering), import the widget instead:

import { initCortexWidget } from '@cortex/widget';

const handle = initCortexWidget({
  apiBase: 'https://api.cortexlayer.dev',
  agentId: 'agt_abc123...',
  sessionToken: 'cs_...',
  accent: '#7c3aed',
});

// Rotate the session token before it expires — preserves the active
// conversation in memory (App stays mounted, only the auth header swaps).
handle.setSessionToken('cs_newtoken...');

// On logout / route teardown.
handle.destroy();

initCortexWidget returns a MountHandle:

Method	Description
`setSessionToken(token: string)`	Hot-swap the session token used by subsequent `chat()` calls. The App stays mounted, so the open conversation, message history, and conversationId in memory are preserved. Format-validated; an invalid token logs a warning and the previous token stays in effect.
`destroy()`	Tear down: unmounts the Preact tree, removes the floating host from `<body>`. Use on logout or full SPA route changes — calling on token refresh would lose the in-flight conversation.

Calling initCortexWidget again replaces the previous floating mount: the prior host is removed before the new one mounts. For session token rotation (the common case), prefer setSessionToken — it preserves the conversation in memory while swapping auth.