2a. What the PWA is

At its core, the PWA is a SvelteKit web app served over HTTPS with a service worker that pre-caches the catalog + app shell for offline use. Once you've logged in once, the next time you open the app on a plane or in a basement with no signal, the entire catalog + your personal notes are still navigable.

It runs on phone, tablet, and desktop browsers. On Chrome Android you can install it to the home screen and it behaves like a native app (no URL bar, no back button — the in-app nav replaces them). On desktop it's a tab.

The data layer is split in two:

• Catalog data (parameters, faults, features, drives, switches, safety sections, 77:S rules) — these are vendored as a static catalog.json shipped with the bundle, cache-firsted by the service worker. Every account on the same install sees the same data.
• Personal data (field notes, shared guidance, favorites, theme, account settings) — these live server-side in Postgres and sync to the device's IndexedDB. Edits made offline queue in an outbox and flush the next time you're online.

2b. The catalog

The catalog is the bread and butter of the app. There are six sub-surfaces, each tuned to a different kind of lookup:

/parameters — the standard parameter table

~425 KONE LCE UI parameters, filterable by menu (EU / NA / NC standards), section, and free-text. Each row opens a detail page showing the parameter's function, default values per region, the min/max range, the format string, and the source code identifier. The detail page is the canonical "what does parameter 1-5 do?" answer.

/parameters/faults — the fault code browser

Seven fault catalogs: LCE, KCE, KDM, KDL, KDH, KDD, KDHN. The master-detail split-view lets you pick a catalog on the left and scan codes on the right. Each code has a code, name, priority, description, "possible reason", detection, operation, recovery, and testing — the same nine columns the source workbook ships.

/parameters/features — the KONE feature catalogue

~537 KONE features (control modes, alarms, drive options) with descriptions, UI settings, and cabling notes. Cross-referenced from parameter prose — if a parameter mentions ABE in its values field, the token becomes a clickable chip that opens the ABE feature preview.

/drives — drive families (KDD, KDL, KDM, ...)

Each drive family has its own parameter list (e.g. KDD-6-1's speed-regulator bandwidth). The drive index is the "what's particular to this drive?" surface — useful when a controller shipped in a job is a KDM and the standard LCE parameters don't fully cover it.

/parameters/safety — Safety Information Forms (SIF) reference

Curated safety procedures grouped by section. Each section is a self-contained procedure with a checklist, hazard callouts, and the associated parameters (cross-linked via chips).

2c. Tools: calculators, converters, switches

The Tools surface bundles the field-calculators, unit converters, and the switches pictorial.

/tools/calculators — 18 field calculators

Buffer stroke, canting, door timing, fault lookup, feet-inch- fraction, jump, ohms law, param lookup, reduced stroke, resistor decode, series-parallel, sheave speed, transformer helper, trip time, velocity, voltage drop, motor FLA, kVA/kW conversion, and the combined ampacity/voltage-drop calculator. Each is a single-purpose form with units you can flip (EU / NA / NC) and a result that explains itself.

/tools/converters — unit converters

Feet-inch-fraction, kVA ↔ kW, °C ↔ °F, and other common conversions. Useful when a controller label is in millimeters but the manual is in inches.

/tools/switches — NTS / ETS / ETSL switch charts

Four KONE switch-chart sets, each with a per-speed table of NTS distance, ETS stages (1–4), and the minimum terminal travel. Click a chart set to see the per-rated-speed rows. This is the table you reach for when adjusting the slowdown distances on a KDM at 200 fpm.

2d. Crosslinks (chips)

Any prose field on a parameter, fault, or feature detail page is scanned for valid references and the references become clickable chips. Three shapes are recognized:

• Parameter — a hyphen-separated id like 1-5 or 7-43. Sub-fields use three parts (1-5-1) and click through to the parent 1-5.
• Fault — a space-separated 2+2 digit code like 00 06 or 21 00. On drive catalogs the sub-code + data1 fields are also recognized, so a KDM row reading 130 5000 54 is three chips deep.
• Feature — a 2–4 character code like ABE, OSS, ACL B. So if a parameter's values field says "see ABE on the alarm-bell page", the ABE token is a chip that opens the ABE feature preview.

Clicking a chip opens a preview modal with the target's function / description / first three lines of the body. The preview is dismissable with Esc, the close button, or a backdrop click. Use the "open full page" link in the preview header to navigate to the canonical detail page.

Self-references are filtered out — a token like 1-5-1 appearing on the 1-5 parameter detail page is treated as a sub-field of the current page, not a cross-link. The filter is per-page.

2e. Notes & shared guidance

Two related surfaces for capturing knowledge on top of the catalog. They are operator-protected (see AGENTS.md "Operator directives" — field notes + shared guidance are core features and are not removed without explicit per-turn consent).

/notes — your personal field notes

The parameters list page and the faults list page each have an "Add note" affordance on every row. A note is anchored to that specific id (the parameter id, e.g. 1-5; or the fault code, e.g. 00 06) and shows up on your personal notes list and in the dashboard's "Recent activity" panel. Notes support Markdown (bold, italic, code, lists, links). Edits made offline queue in the sync outbox and flush when you're back on Wi-Fi. A note can be soft- or hard-deleted by its author; moderation is available out-of-band for cross-account cleanup.

Shared guidance — operator-published broadcasts

Where field notes are private to their author, shared guidance is published out-of-band and visible to every signed-in user. Same anchor system as field notes — only parameter ids and fault codes are supported today. The body is Markdown. Shared guidance is immutable from a regular user's perspective — you see it, you can react to it, but you can't edit it.

Comments — short messages between operators

A lightweight messaging surface for asking a question about a specific catalog entry. Not anchored to a long-form note; use notes for knowledge capture, use comments for back-and- forth.

/favorites — starred catalog entries

A star button on every detail page adds that anchor to your favorites list. The favorites page is one tap from the top nav.

Markdown formatting (field notes + shared guidance + comments)

Every note / shared-guidance / comment body is rendered through the PWA's safe markdown renderer at apps/web/src/lib/markdown.ts. It's hand-rolled (no marked or markdown-it dependency); every user byte is HTML-escaped BEFORE any markdown pattern is matched, so a body like <script>alert(1)</script> renders as visible text, never as executable HTML.

Supported syntax (matches the renderer's regex set):

• Bold — **bold** → <strong> (added v0.9.86; pre-v0.9.86 was identical)
• Italic — *italic* → <em> (asterisk-only; underscore-italic is NOT supported)
• inline code — `code` → <code> (backticks; no language hint on inline code)
• Strikethrough — ~~struck~~ → <del> (added v0.9.86)
• Inline link — [text](url) → <a> (added v0.9.86; URL must be on the allowlist — see below)
• Autolink — <https://example.com> or <mailto:a@b.com> → <a> (added v0.9.86)
• Headings — # H1 / ## H2 / ### H3 → <h1> … <h3> (only 1-3; H4-H6 not recognized — the source regex is ^(#{1,3})\s+)
• Unordered list — - item or * item → <ul><li> (+ nested up to 2 levels via 2+ space indent)
• Ordered list — 1. item → <ol><li> (nested ordered lists are NOT supported)
• Task list — - [ ] todo / - [x] done → read-only <input type="checkbox" disabled> (added v0.9.86; the checkbox is always disabled — this is a display affordance, not an interactive toggle)

• Blockquote

  — > quoted text → <blockquote> (added v0.9.86; nested blockquotes via > > are NOT supported)
• GFM table — | h1 | h2 | + divider | --- | --- | + data rows → <table> (added v0.9.86; alignment colons like | :--- | are accepted but the columns are always left-aligned)
• Fenced code block — ```lang + body + ``` → <pre><code class="language-lang"> (added v0.9.86; the language identifier is HTML-escaped, so a malicious ```<script> just renders as visible text)
• Horizontal rule — --- on its own line → <hr> (added v0.9.44; must be on a line by itself — inline --- in a paragraph is rendered as literal text)
• Paragraph break — a blank line between blocks separates paragraphs; a single newline within a paragraph renders as <br>

URL allowlist (inline links + autolinks):

• https://… — external HTTPS link (rendered with target="_blank" rel="noopener noreferrer")
• http://… — external HTTP link (same target/rel)
• mailto:… — email link
• /path — in-app absolute path (the leading / is required; relative paths like foo/bar are rejected)

Anything off the allowlist — javascript:, data:, file:, // (protocol-relative), or vbscript: — is rejected at render time. The link's text stays as visible content but the <a> wrapper is dropped (no clickable target, no XSS).

NOT supported (the renderer leaves these as escaped text):

• Raw HTML — <div>, <script>, <style> etc. are HTML-escaped and shown as visible text. There is no raw HTML pass-through mode. This is the primary XSS-defence property of the renderer.
• Images — ![alt](url) is NOT recognized (the ! prefix is not in the link regex); the source renders as literal text. Images are out of scope — field notes are plain text by design.
• Underscore-emphasis — _italic_ does NOT render as italic. The italic regex requires asterisks.
• Footnotes — [^1] references are not resolved; the syntax renders as literal text.
• Definition lists — term\n: definition is not recognized.
• Tables of contents, anchor links, code highlighting, line numbers — none of the CommonMark extensions beyond the v0.9.86 GFM set are implemented.

2f. Search, offline, settings

Search palette (Cmd / Ctrl-K)

The keyboard shortcut opens a top-down palette that searches parameters, fault codes, features, and drives in one box. Results are scored by the same ranker the dashboard's "search the catalog" panel uses; arrow keys + Enter pick a result. The palette is on every page — including this one.

Offline mode

After your first signed-in session, the service worker pre-caches the app shell (every static route) and the entire catalog. The "Offline" badge in the header confirms your state; if you've lost signal, the catalog + the app shell still work, and your edits queue in the sync outbox. The dashboard has a "Ready to use offline" verdict (allReady) that turns green once both the data and the shell are fully cached.

/settings — your account + the app

Theme picker (six themes: light, dark, industrial, warm, teal, nordic), region (EU / NA / NC), jurisdiction (for calculators), and a "save for offline use?" toggle that encrypts your profile in IndexedDB so you can sign in with a PIN instead of typing your password the next time. There's also a "Forget this device" entry to wipe the encrypted profile on a shared laptop.

The dashboard

/dashboard is the post-login home. It shows your last ten field notes + shared guidance updates merged by time, four calculator shortcuts, six catalog jump-to tiles (parameters, faults, features, switches, safety, 77:S), the catalog search palette, and the offline / service-worker update status panels.