The browser runtime (kywi-js)
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.
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.
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.