The Liquid Paper interface

The shell is plain HTML, CSS and JavaScript with no build step. The Python API (services/server/api.py) serves the folder as static files, replaces __IMURUN_TOKEN__ in index.html with the per-run bearer token, and sends a strict Content Security Policy:

default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';
img-src 'self' data:; font-src 'self'; connect-src 'self'

Consequences for anyone editing the frontend:

• No CDN, no remote font, no remote image, no inline <script>. Every script is a file loaded with <script src> from index.html.
• Inline style="..." attributes and element.style are allowed ('unsafe-inline' for styles).
• Network calls go only to the same origin (/api/*, /health).
• Sound must be synthesised (WebAudio); there is no media-src.
• Remote images in model output cannot load; the Markdown renderer turns them into link chips.

Related documents in this folder:

Running it#

• Production: python start.py (or python -m services.server) serves the shell with the token injected. The app may also be shown inside a native window (pywebview); the layout needs no browser chrome (see "Native window").
• Design preview without the API: python -m http.server 8731 inside frontend/design-lab, then open http://127.0.0.1:8731/. Without a server the shell shows its honest "server unreachable" states. api.js probes /health and then falls back to http://<host>:8732.

Useful links (query parameters):

Files and responsibilities#

Scripts load in this order (index.html). Order only matters at start-up: after that, modules talk through window.IMURUN at call time.

Every file stays under ~1500 lines; when one grows past that, split it and add a <script src> in index.html after its dependencies.

Stylesheets (index.html order; later wins on equal specificity):

add_models_tab.py is a dead one-off patch script, see the note at the end.

Brand (ImuTechz)#

The brand is the company website's, ported 1:1. The website is a local Next.js project at C:\Users\shubh\Desktop\ImuTechz\WebSite\frontend\ (read-only for this repo: code is ported, assets are copied, nothing is linked). The repository-level brand kit (brand/ at the repo root, see its README) is the brand source for the website and other products too.

Rule: edit the kit, copy to design-lab. frontend/design-lab/aperture.js is brand/vanilla/aperture.js byte for byte: the UI's static root cannot reach brand/, so it serves a copy. After changing the kit file, copy it over and run py -3.15 frontend/design-lab/brand/make_icons.py --check (exit 1 while the two differ); the frontend unit checks fail on drift too. The one file serves both APIs: the kit's (ImuAperture.mount / intro, Node require for scripts/render-svg.js) and the app's (markup, createMark, the live-mark hydrator; IMURUN.aperture is the same object). Colours: --imu-accent / --imu-ink, which styles/tokens.css maps to --logo-accent / --logo-ray on body so the dark themes follow.

Port record#

Live marks in the app: sidebar 26 px, Home 40 px, the start-up card 84 px, the thinking indicator 18 px (the website's loader size), the intro 250 px. BRAND.mark = 'file' in brand.js swaps every mark for <img src="logo.svg">.

Token mapping#

Website -> shell: canvas --color-canvas #f3ede2 -> --bg; --color-surface #faf7f0 -> --surface; surface-2 #ebe4d6 -> --surface-2; surface-3 #e1d9c8 -> --surface-3; line rgba(28,25,20,.10/.22) -> --line / --line-strong; fg #1c1915 -> --text; fg-muted #58524a -> --muted; fg-dim #847c70 -> --muted-soft; accent #d9481e (hi #b93a14, soft rgba(217,72,30,.12)) -> --accent, --accent-hi, --accent-soft, and --logo-accent for the mark; ok #1f8a46 -> --success, --ok-hue; warn #9a6a12 -> --warn-hue; err #b2352a -> --danger; teal #15858d, steel #7e858d -> --teal, --steel, --logo-word-steel; --ink-rgb 28,25,20 kept; radius 14 / 9 / 20 px -> --radius, --radius-sm, --radius-lg; --shadow-card / --shadow-pop -> --shadow-card / --shadow; ease cubic-bezier(.2,.8,.2,1) -> --ease-std; Inter / JetBrains Mono / Fraunces 500 as on the site; eyebrows mono 11 px uppercase .14em; paper grain at 6 %.

Raster icons#

logo.svg is the resting frame, so the raster files never show a moment of the breath. After the website's app/icon.svg changes:

copy WebSite\frontend\app\icon.svg  frontend\design-lab\logo.svg
copy WebSite\frontend\app\icon.svg  frontend\design-lab\brand\icon.svg
py -3.15 frontend\design-lab\brand\make_icons.py

This writes logo.ico (16, 24, 32, 48, 64, 128, 256 px, 32-bit BMP entries, so Win32 LoadImage and System.Drawing load them; PNG entries crashed an icon loader before) and logo-512.png, each size rendered separately by headless Edge (Playwright + Pillow, installed for py -3.15 here). If Mark.jsx changes, port the change into aperture.js; the V8 check below fails until the two agree. Restart the app to see a new taskbar icon.

State model#

All shared state lives in IMURUN.state (core.js):

Engine state shown to the user is derived, never invented (IMURUN.status.engineState): unreachable (no answer), provisioning (runtime !== 'ready'), ready. "No model downloaded" comes from the model catalogue, because some compute paths never report a selected model.

Persistent client-side keys (localStorage, all wrapped in try/catch):

Server-side settings sections: profile, permissions, server, customisation, resources, voice (/api/settings/{section}, cached in localStorage by settings.js), and search (agent-settings.js only; holds API keys, so it is never cached). permissions is loaded by settings.js for the first paint but written through POST /api/permissions (and sendEmail alone through a merge-only PUT); the agent step budget goes through GET/POST /api/agent (stored by the server in section agent).

Per-turn state on the chat.js Turn (not in IMURUN.state): kinds (step -> tool | answer from the step frame), blocks (step -> trace block), activity (activity.js controller), verification, sources, searchResults.

Internal bus events (IMURUN.bus)#

Event flow#

 user presses Enter in the composer
        |
 chat.js submit()
        |   (while typing "/...": slash.js lists skills; Enter/Tab insert "/<id> ")
        |-- "/rename" ............................. app.js handleCommand -> rename dialog
        |-- no session ............................ app.js createSession -> POST /api/sessions
        |-- a reply is running .................... chat.js queue() -> POST /api/prompts (shown as "Queued")
        v
 chat.js send(): append user bubble, new Turn (assistant node exists NOW)
        |
 api.js streamTurn()
   1. new EventSource(/api/events?token=...)       one stream per turn
   2. wait for `open` (max 2.5 s)                  so the first tokens are not lost
   3. POST /api/turns {session_id, text, mode}     -> {turn_id}
        503 -> chat.js provisionAndRetry: no model downloaded -> "No model
               downloaded"; /api/status.selected_model empty -> "Choose a
               model" (inline, Open Models / Try again, no toast); else wait
               for the engine (stack ensure, up to 3 min) and retry once
   4. replay frames buffered before the reply, keeping only turn_id == ours
      (tool.*, agent.*, skill.used must carry exactly our turn_id: manual
      runs publish them with an empty one)
   5. dispatch in arrival order:
        turn.start / step.start / step  -> Turn.onEvent (step.kind -> Turn.kinds;
                                           step.verification/sources kept)
        tool.call / tool.result /
        tool.approval_needed / tool.approved / tool.denied /
        agent.start / agent.end / skill.used
                                        -> Turn.onEvent -> activity.js (rows in
                                           the step's trace block; approval
                                           frames also -> approvals.js)
        research.plan / .search / .fetch / .done
                                        -> Turn.onEvent -> activity.js ->
                                           research.js (block at the top of the
                                           thinking panel; frames without a
                                           turn_id are kept)
        token                           -> Turn.onToken (per step)
        turn.end                        -> Turn.finish(event)   then stream closes
        turn.error                      -> Turn.fail            then stream closes
   6. stream drops mid-turn -> poll GET /api/turns/{id} until not running
        |
 Turn.render() (at most once per animation frame; backs off to ~30/~16 fps
 when a render costs more than 5/12 ms)
   last step text -> markdown.splitReasoning -> thinking panel + answer bubble
     (unless that step's kind is "tool": then it is trace, the bubble is
     cleared and a folded pill unfolds)
   earlier steps -> one trace block per step (Turn.traceBlock), its
     reasoning text first, then its tool rows; "Using `tool` {...}" lines
     are dropped once rows exist
   answer HTML -> patchHtml(): unchanged blocks kept, the growing block
   updated in place (code: only <code> text; tables: only <tbody>), new
   blocks fade in. Never assign innerHTML to a streaming bubble.
   panel open/close/fold -> animateDetails / collapseAway (height animations)
        |
 Turn.finish: final text cleaned (activity.stripNotes drops "[note: unable
 to verify]"-style notes), stats line (engine counters if turn.end carries
 `stats`, otherwise measured in the browser), Copy / Read aloud, then
 activity.finish: sources row, "Used ..." footer with skill chips,
 verification badge next to the stats; announce "Imurun replied"
        |
 bus 'turn.stats' -> panels.js performance drawer and sparkline

 Separately, app.js subscribeEvents(/api/events) receives every frame:
   usage            -> Usage panel
   compaction.*     -> one toast, updated in place (id "compaction")
   model.switch.*   -> models.js toast "model-switch", refresh catalogue
   web_search.*     -> chat.js: "Searching the web…" (dots + query) under the
                       pill, then "Found N sources" (results kept as sources)
   connector        -> connector card + toast
   turn.*           -> session list "replying" chip
   tool.approval_needed -> approvals.js add(): card inline in the live reply
                       when it is on screen, else a kept toast; countdown;
                       tab title "(N) Approval needed"
   tool.approved / tool.denied -> approvals.js: card shows the outcome, leaves
   permissions      -> Settings > Permissions and Tools refresh
   events 'open'    -> approvals.js restore(): GET /api/tools/approvals

 Answering a card: Approve / Approve and remember / Deny (Enter, Esc) ->
 POST /api/tools/approvals/{id} {approved, remember}; the server then
 publishes tool.approved / tool.denied and the waiting turn continues.

 Settings > Tools run form: POST /api/tools/run {name, args}
   200 -> result; 403 {decision: "ask"} -> "Run it once" -> same POST with
   approved: true; 403 {decision: "deny"} -> the reasons.

Stop: the Stop button (or Esc on Chat) calls POST /api/turns/{id}/cancel. If the turn id is not known yet, the cancel is sent as soon as the POST replies. The reply ends when the server sends turn.end with status: "stopped"; if it never does, the UI gives up after 10 s.

Theme system#

A theme is styles/<id>.css that defines, on :root, at least: --bg --surface --surface-2 --text --muted --line --line-strong --accent --accent-text --accent-soft --accent-line --code-bg --success --success-soft --danger --danger-line --danger-text --backdrop --focus-ring --shadow --radius --radius-sm --font --mono, plus optional flourishes (body background, glass on .bubble, .send gradient).

The default theme is imutechz (see "Brand"). Preferences carry a chosen flag set when the user picks a theme or font; without it the pre-2026-11 defaults (liquid-paper, manrope) count as "no choice" and become the current defaults (BUGS-FIXED 66).

theme.js swaps #theme-link by loading the new sheet next to the old one and removing the old one on load (no unstyled flash), sets body[data-theme] and body[data-scheme] (light/dark, from the registry, used for the logo palette and callout colours), and applies preferences:

Persistence: every change is written to localStorage at once and pushed (debounced) to the server customisation section. When the server copy arrives (imurun:settings-hydrated), it is adopted unless the user already changed something on this page, in which case the local copy is pushed.

To add a theme: copy styles/obsidian.css to styles/<id>.css, change the variables, and add {id, label, note, swatch: [bg, surface, accent], dark} to THEMES in theme.js. It appears in the picker and the command palette.

Adding a panel (Settings section or page)#

Settings section:

1. In mockup.js, add a tab button <button class="settings-tab" type="button" data-settings-section="mysection">My section</button> to .settings-subnav, and a panel <section class="settings-section" data-settings-panel="mysection" hidden>...</section> inside .settings-content. app.js wires roles, arrow keys and the crumb.
2. For values stored on the server, give inputs data-setting="mysection.key" and add mysection with defaults to SECTIONS/defaults in settings.js. The server accepts any section name matching ^[a-z0-9][a-z0-9-]{0,63}$.
3. For behaviour, add a module (new file + <script src>), and react to IMURUN.bus.on('settings.section', fn) if it should load lazily.
4. Add a palette entry in actions() in panels.js.

Page: add a nav-item with data-page="x" and a <div class="page-view page-scroll" id="page-x" hidden> in mockup.js; IMURUN.shell.setPage('x') then works, including Alt+number if you extend PAGES in panels.js.

Conventions: render lists with innerHTML and handle clicks with ONE delegated listener on the container, bound once; escape all server text with IMURUN.util.escapeHtml; report failures with IMURUN.toast({tone: 'error', ...}) saying what happened and what to do; never show a number the server did not give without saying it is an estimate.

Accessibility#

• Skip link, landmarks (nav, main, labelled regions), aria-current on the active page and session, Settings as a vertical tablist (arrow keys, Home/End).
• Dialogs (rename, palette, shortcuts, download, guide, drawer) trap focus and return it on close; Esc closes the innermost surface first.
• Sidebar sessions: Enter/Space open, F2 rename, Delete delete, arrows move, Shift+F10 or the Menu key opens the context menu (arrow keys inside).
• The transcript is role="log" with aria-live="off": tokens are not read one by one; completion is announced once through #sr-announcer.
• Toast cards carry their own status/alert role (the container is no longer a second live region). Timers pause on hover and focus.
• Every animation stops under reduced motion (OS or the Customisation toggle); spinners slow down rather than vanish.

Keyboard shortcuts#

Ctrl/Cmd K search, Enter send (queues while a reply runs), Shift Enter new line, Esc stop or close, / focus the message box, Alt N new chat, Ctrl/Cmd B sidebar, Ctrl/Cmd . performance panel, Alt 1-7 pages, ? or Ctrl / the list.

Approval cards: Enter approves when the card has focus (ignored for 0.7 s after it appears), Esc denies the focused card, or the card in the reply on screen when focus is on the page or the composer. That Esc runs in the capture phase, so with a card waiting Esc denies instead of stopping the reply (a second Esc then stops it). In the composer's / list: arrows, Enter/Tab insert, Esc closes.

Native window (pywebview)#

• Title: start.py names the window "IMURUN"; the page title is "IMURUN". The taskbar/window icon is set by the launcher from logo.ico (item 14 in API-REQUESTS.md, done); it now shows the ImuTechz Aperture (resting frame).

• OAuth sign-in: window.open may be blocked in the native window; the Connectors panel then offers "Open sign-in page" / "Copy link" and finishes by polling (API-REQUESTS 31 asks the launcher to open such links in the system browser).

• No history/back-forward use anywhere; navigation is in-app state.

• Works from 720px wide: below 860px the sidebar becomes a drawer (hamburger in the topbar, scrim, focus trap). Window resizes reflow the composer, close menus and drop the drawer when widening.

• window.confirm/window.prompt are used for destructive confirmations and quick inputs; WebView2 shows them natively.

• Links in replies use target="_blank"; whether they open in the system browser depends on the pywebview host configuration.

• WebView2 exposes webkitSpeechRecognition but the service usually refuses; dictation then explains why and disables itself (see VOICE.md).

Verification tooling used#

No Node on the build machine. Checks used during this work (scripts were kept out of the repo):

• Syntax: every *.js parsed with esprima (Python package, ES2017). Code is written to ES2017 (no optional catch binding, no object spread, no ?.). On this machine esprima, playwright and mini-racer are installed for the Python 3.15 interpreter (py -3.15), not in .venv.
• Agentic UI (2026-10-31): headless Edge with the production CSP, every /api/* route mocked in-process and EventSource replaced by a fake the test drives; 49 checks: gallery states, a live turn (tool step preamble cleared, manual-run frame kept out, inline card, toast when Chat is hidden and gone when it is back, countdown, title flag, Enter approves, Esc denies without stopping, delete card has no "remember"), finish (row latency, footer, verified badge, note stripped, title restored, n/a has no badge), 503 -> "Choose a model" without a toast, Permissions (POST, never PUT), Tools 403 ask -> approved re-post, Agent, Search (key never in localStorage), plus light, dark and narrow screenshots under reduced motion. stripNotes / stripCalls / argSummary unit-checked in V8.
• Connectors / MCP / research / brand (2026-11-01): headless Edge, same set-up (production CSP, mocked /api/* including the connector config, test, connect, device and import routes and the MCP routes, fake EventSource, window.open returning null as in the native window); 148 checks (2026-11-02; feedback, Tuning and server voice added; Edge runs with a fake microphone): ImuTechz default theme, canvas colour, the Aperture in the sidebar (6 blades + pupil, live, red 12 o'clock blade; resting frame under reduced motion, breathing otherwise), home lockup, Fraunces loads; the intro measured against Intro.jsx / home.css (curtain intro-up 0.72s at 1.3 s cubic-bezier(0.8, 0, 0.2, 1), mark intro-zoom 1.05s at 0.1 s cubic-bezier(0.22, 1.2, 0.3, 1), ripples 1.1 s at 0.45 / 0.62 s, the edge shadow, cream, 250 px at speed 3, has-intro, Home rise delays, top bar hidden then dropped in, the mark breathing across frames, curtain removed at ~2050 ms (measured 2032), not replayed on in-app navigation, the launch toggle persists; reduced motion: 0.3 s fade, no ripples, removed at ~350 ms, measured 336) with frame screenshots at 120 / 400 / 700 / 1000 / 1300 / 1600 / 1900 ms; the dot field on (light) and off (dark); a press ticks (oscillator count), muted and reduced motion stay silent; search keys PUT under IMURUN_* names and never in localStorage; 8 connector cards with the right status, levels ("reads", "always asks"), tool toggle POST, Test output, client id + secret save (secret cleared from the field and never in localStorage), exact-port note, Gmail import posts only the path, blocked pop-up -> sign-in link -> poll finishes "Connected as", the connector frame updates a card; MCP built-in entry, tools with destructive auto-approve disabled, enable POST keeps ********, mcp.connected / mcp.error frames, form validation and parsed args/env, templates; a live turn driven by engine-shaped research.* frames (lanes wait, a refused source says failed, a page chip fills in, unreported lanes go quiet, verified badge, 3 citation links to numbered chips, the panel survives the fold, citation click highlights the chip without navigating); gallery research states and the Gmail approval card; dark theme blades; no horizontal overflow at 720 px; no CSP violations, no console errors. Screenshots reviewed for light, dark, narrow, intro.
• Connectors to the F1 contract of 2026-11-01 (in the 98, including "Choose file…" through POST /api/system/pick-file and its 501 fallback): built-in / env / user / none credential sources (one Connect, or "Not available yet" + registration_todo and "Use your own app"), credential fields hidden until Advanced is opened, Connect posts {open: true} and shows "Finish signing in in your browser" with no status polling, the connector frame flips the card and a cancelled sign-in gives exactly one notice, token cards (password field, Create a token link + minimum permissions, 401 keeps the field, 200 shows account + permissions and clears it, Forget token -> DELETE), the storage badge, "How it works" renders the doc route's Markdown, the Gmail import result; approvals honour the native rememberable / level; the MCP edit form picks auto-approve from the discovered tools.
• Tuning (in the 127): the history reply carries data-turn-id and three buttons; up posts {turn_id, rating, session_id}, a second click posts clear, the consent notice appears exactly once with the local-only wording, Teach is prefilled with the answer and posts the correction, a tuning.feedback frame syncs the buttons, a finished live reply gets the buttons too; the honest copy; Install posts /api/tuning/setup and tuning.setup frames move the bar; the plan for the target and for an 8B ("refused", reason verbatim); samples and skip reasons; Train now: 409 asks first and only the click resends with confirm: true; tuning.job drives the stepper, progress, loss and "paused", Cancel posts the cancel; Settings post only changed keys plus the write-only token; history with metrics on open; tuning.ready shows the card, never switches by itself, and Use it posts /api/models/select {id}; no overflow at 720 px.
• Aperture vs the website (V8, 21 checks; the three new ones: the served copy is byte-identical to brand/vanilla/aperture.js, the kit file loads with no DOM and exposes the kit API, ImuAperture === IMURUN.aperture): the website's own Mark.jsx math is extracted and run next to aperture.js; the resting frame and law(t) / blade / pupil paths at 400 instants are identical strings; the resting frame equals logo.svg (the website's app/icon.svg) and the repo kit's brand/svg/aperture-small.svg; stroke weights, accent blade, shadow, tiles, mono, centre, live markup; the sound palette and toggle.
• logo.ico loaded through Win32 LoadImage (16, 24, 32, 48, 256 px) and System.Drawing.
• Unit: markdown.js run in V8 (mini-racer) against rendering and splitReasoning cases; 2026-11-01: 24 checks of research.expand (citation groups and ranges), laneOf, phase, mcp.configFrom / parsePairs (ids, stdio/http, redacted env kept, headers, timeout clamp).
• Render: headless Microsoft Edge via Playwright with the production CSP injected, screenshots of the splash, gallery, settings, dark theme, narrow window, palette, stats and shortcuts; and an end-to-end chat against a mocked API whose event stream delivers frames before the POST reply and includes another turn's frames.

Dead file: add_models_tab.py#

A one-off patch script that inserted the Models tab into mockup.js. The tab is already in mockup.js, and the script hardcodes another machine's path (C:\Users\imu\...). On this machine it fails on the path; pointed at the right file it would print "Could not find subnav pattern" and then rewrite mockup.js anyway, reading and writing with the platform default encoding (cp1252 on Windows), which risks corrupting the file's UTF-8 characters. Do not run it. It is kept (not deleted) per the task rules; it is safe to remove.