# The browser runtime (kywi-js)

URL: https://kywi-docs-production.up.railway.app/integrating/the-browser-runtime-kywi-js
Type: docPage

The browser runtime boots itself from `/kywi.js`, reads its context from `kywi:*` meta tags, and enhances nav, forms and feeds even with personalization off.

`@kywi-software/js` is a self-booting bundle, not a library you initialise. Loading it publishes `window.Kywi` and runs `Kywi.boot()` — on `DOMContentLoaded`, or straight away if the document is already parsed. Booting twice is a no-op, so injecting the script more than once is harmless.

## What boot turns on

Four things, none of which depend on personalization being configured: the layout module system, the form hooks, nav-menu enhancement — hover intent, Escape and arrow keys, flipping a submenu away from the viewport edge — and the A/B experiment beacons that confirm exposure of the server-rendered variant and forward conversion signals. It also fills in `getEntity`, `getFeed` and `renderFeed` for reading content from the page. Nav renders and works fully without any of this; the bundle is polish on top of markup that already functions.

window.Kywi: { version: string context: KywiContext preInit(fn: (kywi) => void): void // queued, or run now if already booted UI.extend(definition): KywiModuleDefinition DisplayObject.Form.extend(methods): void getEntity(type: string), getFeed(type: string), renderFeed(options) setSelfId(...), clearSelfId() boot(): void }

`preInit` is the hook to register a custom module or a form method before boot runs; registering after boot still works, because a late callback is invoked immediately rather than dropped. `setSelfId` is on the global so a site's own "what brings you here?" control can record an answer without the built-in widget — it reloads the page afterwards, because the arm a visitor was not served is not in the DOM to swap to.

## Context comes from meta tags

There is no configuration call. The runtime reads its context out of the document once, at boot — and the tags split cleanly by who renders them. The four below are the host app's to write; core renders none of them, and every default in the runtime is what a page that emits none gets.

<meta name="kywi:site-id" content="default"> <meta name="kywi:base-path" content="/"> <meta name="kywi:theme-path" content="/themes/deep-field"> <meta name="kywi:csrf-token" content="…">

Core renders a second set on every public page, and these you never write yourself: `kywi:visitor-id` is stamped on every render, and `kywi:audience-id` follows when personalization resolved one. `kywi:experiment-id` and `kywi:variant-id` exist on the same component but nothing on core's shipped render path fills them — the one call site passes only an audience id and a visitor id — so `bootExperiments`' exposure beacon, which is gated on reading `kywi:experiment-id` back out of the document, never fires from that tag today. `bootExperiments` does take its visitor id from `kywi:visitor-id`, and the client data layer reads all four the same way, so a host that renders its own `kywi:visitor-id` tag would only be racing core's.

The site id also falls back to `data-kywi-site` on the `<html>` element, the locale comes from `html[lang]`, and edit mode is detected from the `kywi-edit-mode` class on `<body>`. Every tag is optional and every default is benign: `base-path` defaults to `/`, which makes the API base `/api/v1`, so a same-origin site gets working nav enhancement with no tags at all. The runtime attaches the csrf token to every `getEntity` and `getFeed` call it makes, reads included — but the server only checks it on the two visitor-facing write routes, `/kywi/audience` and `/kywi/self-id`, and only on a site that issues a `kywi_csrf` cookie.

## Where the file comes from

Core injects `<script src="/kywi.js" async>` exactly once, whenever the site has a nav — and it is *your* job to put the built bundle at `public/kywi.js`. This is the one asset the scaffold does not keep in sync: `public/kywi-admin.css` is copied on every `dev` and `build`, and `kywi.js` is not. The path is hard-coded, so the file is served from your own origin, not a CDN.

## A missing kywi.js fails quietly

The script tag is injected whether or not the file exists, and nothing in the app reports the 404 — the browser console is the only signal. Nav menus keep working, so the symptom is subtle: no hover intent, no keyboard handling, no experiment exposure beacons, and personalization stuck on whatever the server rendered. Check for the file before debugging the behaviour.

## The audience engine is a separate opt-in

`bootAudienceEngine` is an export, not part of `boot()`. Turning it on is `personalization: { clientRuntime: true }` on the theme, which is what makes core load it; it brings the self-ID widget, the transparency panel and the client signal adapters. Without it the server-rendered variant is what every visitor sees, which is a perfectly good place for a site to stay. What the panel means for visitors is [The transparency panel and audience switcher](/targeting/the-transparency-panel-and-audience-switcher/).

## Consent, mirrored

The runtime carries its own copy of core's cookie-to-category map — the two packages do not depend on each other, so the copy is what lets a decision made in the browser revoke the cookies it denies without a round trip, and a parity test fails if the two ever drift. Three cookies are `essential` — `kywi_consent`, `kywi_optout`, `kywi_preview_init` — and the seven that carry visitor state, including `kywi_visitor`, `kywi_audience` and `kywi_selfid`, are `personalization`. If you run your own consent banner, record the decision through the exported `setConsent` rather than writing the cookie yourself: the read path normalises what it finds and treats anything it does not recognise as a refusal.
