@unisim/sdk 0.167.0 → 0.169.0

package/README.md

@@ -332,6 +332,13 @@ reports the app as in use (guests included) and the menu reads the figure.
   for it to launch is a good deal more deliberate than arriving at a URL. For a
   surface that is watched rather than touched — a wall display, a kiosk — pass
   `presence: { requireInteraction: false }`.
+  ⚠️ **Our own traffic sends no beat at all** (since 0.168.0,
+  `isOwnTraffic()`): a browser under automation (`navigator.webdriver`, set by
+  Playwright, Puppeteer and Selenium, on any host, the live site included), or a
+  web page served from localhost, a loopback or private IP, or a `.local` name.
+  Two days of Playwright runs had made 96 of Jukebox's 104 "users". An installed
+  app is never judged by its host (Capacitor on Android is `https://localhost`).
+  A spec that has to see beats sets `window.__UNISIM_COUNT_OWN_TRAFFIC__ = true`.
   ⚠️ **PostgREST resolves an RPC by its argument NAMES**, so sending
   `p_platform` to a database without migration 0187 is "function not found",
   not an ignored argument. A beat refused for that reason retries without it and
@@ -620,7 +627,16 @@ invisible, keeps a private session, and nothing reports a problem. **Its
 apps** — the Java side keeps no second copy, it filters what the package manager
 admits to by the `.unisimsuiteauth` suffix. Adding an app to the suite means
 adding one line there. (The `<package>` list below it is a different list for a
-different job — see the switcher section.)
+different job — see the switcher section. ⚠️ But a `<package>` entry makes the
+WHOLE package visible, providers included, so an app on that list is reachable
+for session sharing whether or not it is on the provider list — which is how
+Ergo Assess's native app was reached before it was named there.)
+
+**Ergo Assess is the one non-Capacitor member** (2026-09-29). Its Compose app
+hosts a Kotlin port of `SuiteAuthProvider`/`SuiteAuthStore` under the same
+permission and contract (`Ergo_Assess` `android/…/web/SuiteAuthStore.kt`) and
+carries its own copy of the provider list in its manifest — so a new suite app
+goes into both.
 
 ⚠️ **Same key, in practice, means the same BUILD TYPE.** Debug builds are signed
 with `~/.android/debug.keystore` and release builds with the upload key. Install

package/android/src/main/AndroidManifest.xml

@@ -29,11 +29,16 @@
        Two Capacitor apps are deliberately absent, and neither is an oversight:
        Universal AI and Universal Family both run their own Supabase client on
        their own storage key by an explicit decision recorded in their source,
-       so they have no shared session to take part in. Ergo Assess is absent for
-       a different reason again: it is a native Compose app that ships no
-       SuiteAuthProvider at all, so there is no authority to name. It carries
-       the session in its own Keychain/KeyStore instead, which is why it appears
-       in 2b below and not here.
+       so they have no shared session to take part in.
+
+       Ergo Assess IS here (2026-09-29), though it is not Capacitor: its native
+       Compose app hosts a Kotlin port of SuiteAuthProvider under the same
+       permission and contract (Ergo_Assess android/…/web/SuiteAuthStore.kt),
+       keeping the com.universalsimulation. prefix of its Gradle module. Before
+       this line it was already reachable by accident — its <package> entry in
+       2b makes the whole package, providers included, visible — but sharing a
+       session must not hang on the switcher's list. Ergo's own manifest keeps
+       a copy of this list; add a new app there too.
 
        2b. The PACKAGE list: who the suite switcher can OPEN, via
        UnisimSuiteAuthPlugin.installedApps/openApp. Deliberately a separate
@@ -73,14 +78,14 @@
 
     <queries>
         <provider
-            android:authorities="uk.co.unisim.coshhassess.unisimsuiteauth;uk.co.unisim.cyberassess.unisimsuiteauth;uk.co.unisim.fireassess.unisimsuiteauth;uk.co.unisim.riskassess.unisimsuiteauth;uk.co.unisim.wfhassess.unisimsuiteauth;uk.co.unisim.blackbook.unisimsuiteauth;uk.co.unisim.compress.unisimsuiteauth;uk.co.unisim.converter.unisimsuiteauth;uk.co.unisim.images.unisimsuiteauth;uk.co.unisim.jukebox.unisimsuiteauth;uk.co.unisim.pdf.unisimsuiteauth;uk.co.unisim.polling.unisimsuiteauth;uk.co.unisim.qr.unisimsuiteauth" />
+            android:authorities="uk.co.unisim.coshhassess.unisimsuiteauth;uk.co.unisim.cyberassess.unisimsuiteauth;uk.co.unisim.fireassess.unisimsuiteauth;uk.co.unisim.riskassess.unisimsuiteauth;uk.co.unisim.wfhassess.unisimsuiteauth;uk.co.unisim.blackbook.unisimsuiteauth;uk.co.unisim.compress.unisimsuiteauth;uk.co.unisim.converter.unisimsuiteauth;uk.co.unisim.images.unisimsuiteauth;uk.co.unisim.jukebox.unisimsuiteauth;uk.co.unisim.pdf.unisimsuiteauth;uk.co.unisim.polling.unisimsuiteauth;uk.co.unisim.qr.unisimsuiteauth;com.universalsimulation.ergoassesscapture.unisimsuiteauth" />
 
         <!-- Ergo Assess is the one non-Capacitor app here: a Compose app whose
              MainActivity already carries MAIN/LAUNCHER, which is all
              getLaunchIntentForPackage needs. It keeps the
-             com.universalsimulation. prefix from its own Gradle module and is
-             absent from the provider list above on purpose — it has no
-             SuiteAuthProvider, so it shares no session. -->
+             com.universalsimulation. prefix from its own Gradle module. Since
+             2026-09-29 it is in the provider list above as well: it hosts a
+             port of SuiteAuthProvider and shares the session. -->
         <package android:name="com.universalsimulation.ergoassesscapture" />
         <package android:name="uk.co.unisim.cyberassess" />
         <package android:name="uk.co.unisim.wfhassess" />

package/dist/KnowledgeBaseDialog.d.ts

@@ -1,15 +1,37 @@
 import { type Language } from './i18n.js';
 import { type MenuTheme } from './menuTheme.js';
+/** Where the suite's knowledge-base PDFs are served from. See note 4. */
+export declare const KB_LIBRARY_URL = "https://opensource.unisim.co.uk/kb";
+export type KnowledgeSourceKind = 'paper' | 'standard' | 'report' | 'guidance' | 'law';
+/** A paper, standard or report an article draws on. */
+export interface KnowledgeSource {
+    kind: KnowledgeSourceKind;
+    /** In the original language; titles of papers are not translated. */
+    title: string;
+    authors?: string;
+    /** Journal, conference or issuing body — "ACM CCS 2019", "NIST". */
+    publisher?: string;
+    year?: number;
+    /** The canonical free link: a DOI, the publisher's page or their own PDF. */
+    href: string;
+    /**
+     * Our hosted copy, relative to the library (`papers/fips-197-aes.pdf`) or
+     * absolute. Only when the licence permits redistribution (note 5).
+     */
+    pdf?: string;
+    /** The licence the hosted copy is shared under. Shown beside it. */
+    licence?: string;
+}
 export interface KnowledgeArticle {
-    /** Stable slug. Also what `initialArticle` matches. */
+    /** Stable slug. Also what `initialArticle` matches, and the guide PDF's name. */
     id: string;
     title: string;
-    /** One line under the title in the list. */
+    /** One line under the title on its card. */
     summary?: string;
     /**
-     * A heading the list groups articles under — "The basics", "Privacy and
+     * A heading the cards are grouped under — "The basics", "Privacy and
      * security". Articles keep their order; a group starts where its label
-     * first appears. Leave unset on every article for a plain list.
+     * first appears. Leave unset on every article for one ungrouped grid.
      */
     group?: string;
     /**
@@ -17,22 +39,41 @@ export interface KnowledgeArticle {
      * `1. ` numbered steps and `**bold**`. Nothing else is interpreted.
      */
     body: string;
+    /** The research behind the article, shown beside it. Not translated. */
+    sources?: KnowledgeSource[];
 }
 export type KnowledgeArticles = KnowledgeArticle[] | ((language: Language) => KnowledgeArticle[] | Promise<KnowledgeArticle[]>);
 /** What an app hands the navbar (`knowledgeBase`) or <AdvancedMenu>. */
 export interface KnowledgeBaseConfig {
     articles: KnowledgeArticles;
+    /**
+     * The app's guide PDFs have been generated and published (see
+     * `scripts/kb-pdfs.mjs` in universal-platform). Turns on the "Download
+     * guide" buttons, which link to
+     * `<library>/<product>/<language>/<article id>.pdf`. Leave unset until
+     * they exist.
+     */
+    guides?: boolean;
+    /** Override the library's address. Tests and self-hosters only. */
+    library?: string;
 }
 export interface KnowledgeBaseDialogProps extends KnowledgeBaseConfig {
     open: boolean;
     onClose: () => void;
-    /** Open straight onto this article rather than the list. */
+    /** Open straight onto this article rather than the cards. */
     initialArticle?: string;
     /** Heading beside the mark. Defaults to the product's name from the SDK. */
     name?: string;
     theme?: MenuTheme;
 }
-export declare function KnowledgeBaseDialog({ open, onClose, articles, initialArticle, name, theme, }: KnowledgeBaseDialogProps): import("react").ReactPortal | null;
+/**
+ * The folder a language's guides are filed under. The generator writes one
+ * folder per translation the app has; both Englishes share `en`.
+ */
+export declare function guideLanguage(language: string): string;
+/** Resolve a source's `pdf` (library-relative or absolute) to a URL. */
+export declare function libraryUrl(path: string, library?: string): string;
+export declare function KnowledgeBaseDialog({ open, onClose, articles, guides, library, initialArticle, name, theme, }: KnowledgeBaseDialogProps): import("react").ReactPortal | null;
 type Block = {
     kind: 'h';
     text: string;
@@ -46,7 +87,7 @@ type Block = {
     kind: 'ol';
     items: string[];
 };
-/** Exported for the tests — splits an article body into blocks. */
+/** Exported for the tests and the PDF generator — splits a body into blocks. */
 export declare function parseArticleBody(body: string): Block[];
 /** The book glyph for the menu row. Exported so <AdvancedMenu> can use it. */
 export declare function IconBook(): import("react/jsx-runtime").JSX.Element;

package/dist/KnowledgeBaseDialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KnowledgeBaseDialog.d.ts","sourceRoot":"","sources":["../src/KnowledgeBaseDialog.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAK,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAqCrD,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,EAAE,GAClB,CAAC,CAAC,QAAQ,EAAE,QAAQ,KAAK,gBAAgB,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAA;AAE9E,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,iBAAiB,CAAA;CAC5B;AAED,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAED,wBAAgB,mBAAmB,CAAC,EAClC,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,cAAc,EACd,IAAI,EACJ,KAAe,GAChB,EAAE,wBAAwB,sCAkH1B;AAqDD,KAAK,KAAK,GACN;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEnC,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,EAAE,CAkCtD;AAwDD,8EAA8E;AAC9E,wBAAgB,QAAQ,4CAQvB"}
+{"version":3,"file":"KnowledgeBaseDialog.d.ts","sourceRoot":"","sources":["../src/KnowledgeBaseDialog.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAK,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAgErD,yEAAyE;AACzE,eAAO,MAAM,cAAc,uCAAuC,CAAA;AAElE,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAA;AAEtF,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAA;IACzB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,OAAO,CAAC,EAAE,eAAe,EAAE,CAAA;CAC5B;AAED,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,EAAE,GAClB,CAAC,CAAC,QAAQ,EAAE,QAAQ,KAAK,gBAAgB,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAA;AAE9E,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,iBAAiB,CAAA;IAC3B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAiB,GAAG,MAAM,CAEzE;AAED,wBAAgB,mBAAmB,CAAC,EAClC,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,MAAc,EACd,OAAwB,EACxB,cAAc,EACd,IAAI,EACJ,KAAe,GAChB,EAAE,wBAAwB,sCAkJ1B;AAgND,KAAK,KAAK,GACN;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEnC,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,EAAE,CAkCtD;AAqED,8EAA8E;AAC9E,wBAAgB,QAAQ,4CAQvB"}

package/dist/KnowledgeBaseDialog.js

@@ -7,17 +7,91 @@ import { t } from './i18n.js';
 import { MENU } from './menuTheme.js';
 import { useLanguage, useUniversal } from './provider.js';
 import { lookupProduct } from './AboutAppDialog.js';
-export function KnowledgeBaseDialog({ open, onClose, articles, initialArticle, name, theme = 'light', }) {
+// ──────────────────────────────────────────────────────────────────────────────
+// <KnowledgeBaseDialog /> — an app's own knowledge base, read in the app.
+//
+// Owner ask, 2026-09-27: "introduce the knowledge base as per Ergo Assess but
+// in the universal apps it should be more discreet e.g. in advanced in the
+// actions pill" — explainers like "What actually is a PDF?" beside how the app
+// itself works ("level of encryption for send and sign").
+//
+// Owner ask, 2026-09-29: "it should be more like the knowledge base on Ergo
+// Assess with a knowledge base page, cards to click through and downloads
+// available in PDFs. Research papers are the best if we can find." So the
+// entry stays discreet (Advanced ▸ Knowledge base) but what opens is a page:
+// a card grid, and an article view with its guide PDF and its research
+// beside it — Ergo's /knowledge-base and /[method] in one dialog. Ergo-style
+// whole-guide and download-library banners were built and taken out the same
+// day at the owner's ask ("remove the download whole knowledge base and
+// download library buttons"): each download lives on the article it belongs to.
+//
+// Five decisions worth keeping:
+//
+// 1. **A dialog, not a route.** Ergo's knowledge base is a set of Next.js
+//    pages. The Universal Apps are single-page Vite apps that also ship as
+//    Capacitor and Electron builds with no server behind them, so a route
+//    would mean nineteen routers and a knowledge base that 404s offline. The
+//    articles are bundled into the app and read here, which works in Airplane
+//    mode and needs nothing from the host but the words.
+//
+// 2. **The body is a tiny, closed markdown — never HTML.** Blank-line
+//    paragraphs, `## ` subheadings, `- ` bullets, `1. ` steps, `**bold**`.
+//    That is enough for an explainer, easy for a translator to keep intact,
+//    and rendered as React elements, so nothing an article says can inject
+//    markup. Anything else in the text is shown literally.
+//
+// 3. **Articles are per language and may load lazily.** `articles` can be a
+//    function of the language returning a promise, so an app keeps seven
+//    translations out of its first paint and imports only the one it needs.
+//    A language the app has not translated falls back to English (the
+//    function decides; the dialog just shows what it is given).
+//
+// 4. **The PDFs live on the web, not in the app.** Guides and hosted papers
+//    are served from one library, `opensource.unisim.co.uk/kb/`, never from
+//    the app's own bundle. A relative link to a bundled PDF inside a Capacitor
+//    webview NAVIGATES the webview to the PDF, with no back button out; an
+//    https link with target=_blank goes to the system browser on iOS, Android
+//    and Electron alike. It also keeps ~10 MB of papers out of every app
+//    bundle, and lets two apps that cite FIPS 197 share one copy. The cost is
+//    that downloads need a connection; the articles themselves never do.
+//
+// 5. **A hosted copy only when its licence allows it.** `source.pdf` is set
+//    only for public-domain (US Government), Open Government Licence, CC BY,
+//    EUR-Lex and IETF documents; everything else — ACM, IEEE, ISO, Adobe —
+//    is a link to the publisher's own free copy. `licence` says which, and
+//    the dialog shows it beside the download. Same rule as Ergo's
+//    `research-papers.ts`.
+//
+// ⚠️ Inline styles, like every SDK dialog — this ships inside node_modules,
+// where the apps' Tailwind builds do not scan. Layout switches on the card's
+// measured width (ResizeObserver), since inline styles have no media queries.
+// ──────────────────────────────────────────────────────────────────────────────
+/** Where the suite's knowledge-base PDFs are served from. See note 4. */
+export const KB_LIBRARY_URL = 'https://opensource.unisim.co.uk/kb';
+/**
+ * The folder a language's guides are filed under. The generator writes one
+ * folder per translation the app has; both Englishes share `en`.
+ */
+export function guideLanguage(language) {
+    return language === 'en-gb' || language === 'en' ? 'en' : language;
+}
+/** Resolve a source's `pdf` (library-relative or absolute) to a URL. */
+export function libraryUrl(path, library = KB_LIBRARY_URL) {
+    return /^https?:\/\//.test(path) ? path : `${library.replace(/\/$/, '')}/${path.replace(/^\//, '')}`;
+}
+export function KnowledgeBaseDialog({ open, onClose, articles, guides = false, library = KB_LIBRARY_URL, initialArticle, name, theme = 'light', }) {
     const { language } = useLanguage();
     const { config } = useUniversal();
     const p = MENU[theme];
     const [list, setList] = useState(Array.isArray(articles) ? articles : null);
     const [failed, setFailed] = useState(false);
-    const [current, setCurrent] = useState(initialArticle ?? null);
+    const [view, setView] = useState(initialArticle ? { kind: 'article', id: initialArticle } : { kind: 'index' });
+    const [width, setWidth] = useState(0);
     const cardRef = useRef(null);
     // The card scrolls, and a long article leaves it scrolled: moving between
-    // the list and an article starts at the top, as turning a page would.
-    useEffect(() => { cardRef.current?.scrollTo?.({ top: 0 }); }, [current]);
+    // views starts at the top, as turning a page would.
+    const viewKey = view.kind === 'article' ? view.id : '';
+    useEffect(() => { cardRef.current?.scrollTo?.({ top: 0 }); }, [viewKey]);
     // Resolve the articles for the reader's language each time the dialog opens
     // (or the language changes under it). A plain array needs no work.
     useEffect(() => {
@@ -37,10 +111,10 @@ export function KnowledgeBaseDialog({ open, onClose, articles, initialArticle, n
             setFailed(true); });
         return () => { live = false; };
     }, [open, language, articles]);
-    // Every open starts where the caller asked — the list, unless told otherwise.
+    // Every open starts where the caller asked — the cards, unless told otherwise.
     useEffect(() => {
         if (open)
-            setCurrent(initialArticle ?? null);
+            setView(initialArticle ? { kind: 'article', id: initialArticle } : { kind: 'index' });
     }, [open, initialArticle]);
     useEffect(() => {
         if (!open)
@@ -48,25 +122,82 @@ export function KnowledgeBaseDialog({ open, onClose, articles, initialArticle, n
         function onKey(e) {
             if (e.key !== 'Escape')
                 return;
-            // Escape steps back out of an article before it closes the dialog, the
-            // same as the back arrow — reading three articles should not need the
-            // mouse between each.
-            if (current)
-                setCurrent(null);
+            // Escape steps back out of an article before it closes
+            // the dialog, the same as the back arrow — reading three articles should
+            // not need the mouse between each.
+            if (view.kind !== 'index')
+                setView({ kind: 'index' });
             else
                 onClose();
         }
         document.addEventListener('keydown', onKey);
         return () => document.removeEventListener('keydown', onKey);
-    }, [open, onClose, current]);
-    const article = useMemo(() => (current && list ? list.find((a) => a.id === current) ?? null : null), [current, list]);
+    }, [open, onClose, view.kind]);
+    // Measure the card so the grid and the sidebar can reflow (see the ⚠️ above).
+    useEffect(() => {
+        const el = cardRef.current;
+        if (!open || !el)
+            return;
+        setWidth(el.clientWidth);
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        const ro = new ResizeObserver(() => setWidth(el.clientWidth));
+        ro.observe(el);
+        return () => ro.disconnect();
+    }, [open]);
+    const index = view.kind === 'article' && list ? list.findIndex((a) => a.id === view.id) : -1;
+    const article = index >= 0 && list ? list[index] ?? null : null;
     if (!open || typeof document === 'undefined')
         return null;
     const entry = lookupProduct(config.product);
     const title = name ?? entry?.name ?? t(language, 'menu.knowledge_base');
-    return createPortal(_jsx("div", { style: overlayStyle, onClick: onClose, role: "presentation", children: _jsxs("div", { role: "dialog", "aria-modal": "true", "aria-label": `${t(language, 'menu.knowledge_base')} — ${title}`, ref: cardRef, style: cardStyle(p), onClick: (e) => e.stopPropagation(), children: [_jsx("button", { type: "button", onClick: onClose, "aria-label": t(language, 'nav.menu_close'), style: closeButtonStyle(p), onMouseEnter: (e) => { e.currentTarget.style.color = p.text; }, onMouseLeave: (e) => { e.currentTarget.style.color = p.muted; }, children: _jsx(IconClose, {}) }), article ? (_jsxs(_Fragment, { children: [_jsxs("button", { type: "button", onClick: () => setCurrent(null), style: backButtonStyle(p), children: [_jsx("span", { "aria-hidden": true, style: { display: 'inline-flex' }, children: _jsx(IconBack, {}) }), t(language, 'kb.all_articles')] }), _jsx("h2", { style: { ...titleStyle(p), margin: '10px 34px 12px 0' }, children: article.title }), _jsx(ArticleBody, { body: article.body, palette: p })] })) : (_jsxs(_Fragment, { children: [_jsxs("div", { style: identityRowStyle, children: [entry?.glyph && _jsx("span", { style: markTileStyle(p), "aria-hidden": true, children: entry.glyph }), _jsxs("div", { style: { minWidth: 0 }, children: [_jsx("h2", { style: titleStyle(p), children: t(language, 'menu.knowledge_base') }), _jsx("p", { style: subtitleStyle(p), children: title })] })] }), failed ? (_jsx("p", { style: bodyStyle(p), children: t(language, 'kb.load_failed') })) : !list ? (_jsx("p", { style: { ...bodyStyle(p), color: p.faint }, children: t(language, 'kb.loading') })) : list.length === 0 ? (_jsx("p", { style: { ...bodyStyle(p), color: p.faint }, children: t(language, 'kb.no_articles') })) : (_jsx(ArticleList, { articles: list, onOpen: setCurrent, palette: p }))] }))] }) }), document.body);
+    const guideBase = guides && config.product
+        ? `${library.replace(/\/$/, '')}/${config.product}/${guideLanguage(language)}`
+        : null;
+    const wide = width >= 720;
+    let content;
+    if (failed)
+        content = _jsx("p", { style: bodyStyle(p), children: t(language, 'kb.load_failed') });
+    else if (!list)
+        content = _jsx("p", { style: { ...bodyStyle(p), color: p.faint }, children: t(language, 'kb.loading') });
+    else if (article) {
+        content = (_jsx(ArticleView, { article: article, prev: list[index - 1], next: list[index + 1], colour: groupColour(list, article, theme), guideHref: guideBase ? `${guideBase}/${article.id}.pdf` : null, library: library, wide: wide, language: language, palette: p, onOpen: (id) => setView({ kind: 'article', id }), onBack: () => setView({ kind: 'index' }) }));
+    }
+    else {
+        content = (_jsxs(_Fragment, { children: [_jsxs("div", { style: identityRowStyle, children: [entry?.glyph && _jsx("span", { style: markTileStyle(p), "aria-hidden": true, children: entry.glyph }), _jsxs("div", { style: { minWidth: 0 }, children: [_jsx("h2", { style: titleStyle(p), children: t(language, 'menu.knowledge_base') }), _jsx("p", { style: subtitleStyle(p), children: title })] })] }), list.length === 0 ? (_jsx("p", { style: { ...bodyStyle(p), color: p.faint }, children: t(language, 'kb.no_articles') })) : (_jsxs(_Fragment, { children: [_jsx("p", { style: { ...bodyStyle(p), margin: '0 0 16px', color: p.muted }, children: t(language, 'kb.intro').replace('{app}', title) }), _jsx(CardGrid, { articles: list, columns: width >= 760 ? 3 : width >= 480 ? 2 : 1, theme: theme, language: language, palette: p, onOpen: (id) => setView({ kind: 'article', id }) })] }))] }));
+    }
+    return createPortal(_jsx("div", { style: overlayStyle, onClick: onClose, role: "presentation", children: _jsxs("div", { role: "dialog", "aria-modal": "true", "aria-label": `${t(language, 'menu.knowledge_base')} — ${title}`, ref: cardRef, style: cardStyle(p), onClick: (e) => e.stopPropagation(), children: [_jsx("button", { type: "button", onClick: onClose, "aria-label": t(language, 'nav.menu_close'), style: closeButtonStyle(p), onMouseEnter: (e) => { e.currentTarget.style.color = p.text; }, onMouseLeave: (e) => { e.currentTarget.style.color = p.muted; }, children: _jsx(IconClose, {}) }), content] }) }), document.body);
+}
+const HUES = {
+    light: [
+        { fg: '#1d4ed8', bg: '#eff6ff', bar: '#3b82f6' },
+        { fg: '#6d28d9', bg: '#f5f3ff', bar: '#8b5cf6' },
+        { fg: '#047857', bg: '#ecfdf5', bar: '#10b981' },
+        { fg: '#b45309', bg: '#fffbeb', bar: '#f59e0b' },
+        { fg: '#be123c', bg: '#fff1f2', bar: '#f43f5e' },
+    ],
+    dark: [
+        { fg: '#93c5fd', bg: 'rgba(59,130,246,0.16)', bar: '#3b82f6' },
+        { fg: '#c4b5fd', bg: 'rgba(139,92,246,0.16)', bar: '#8b5cf6' },
+        { fg: '#6ee7b7', bg: 'rgba(16,185,129,0.16)', bar: '#10b981' },
+        { fg: '#fcd34d', bg: 'rgba(245,158,11,0.16)', bar: '#f59e0b' },
+        { fg: '#fda4af', bg: 'rgba(244,63,94,0.16)', bar: '#f43f5e' },
+    ],
+};
+function groupOrder(articles) {
+    const seen = [];
+    for (const a of articles)
+        if (!seen.includes(a.group ?? ''))
+            seen.push(a.group ?? '');
+    return seen;
 }
-function ArticleList({ articles, onOpen, palette: p }) {
+function groupColour(articles, a, theme) {
+    const hues = HUES[theme];
+    const i = Math.max(0, groupOrder(articles).indexOf(a.group ?? ''));
+    return hues[i % hues.length];
+}
+// ── The index: the card grid ────────────────────────────────────────────────
+function CardGrid({ articles, columns, theme, language, palette: p, onOpen }) {
     // Consecutive runs of the same group, in the order the app gave them.
     const runs = [];
     for (const a of articles) {
@@ -76,9 +207,25 @@ function ArticleList({ articles, onOpen, palette: p }) {
         else
             runs.push({ group: a.group, items: [a] });
     }
-    return (_jsx("div", { style: { display: 'grid', gap: 14 }, children: runs.map((run, i) => (_jsxs("div", { children: [run.group && _jsx("p", { style: groupLabelStyle(p), children: run.group }), _jsx("div", { style: { display: 'grid', gap: 2, margin: '0 -10px' }, children: run.items.map((a) => (_jsxs("button", { type: "button", onClick: () => onOpen(a.id), style: rowStyle, onMouseEnter: (e) => { e.currentTarget.style.background = p.rowHover; }, onMouseLeave: (e) => { e.currentTarget.style.background = 'transparent'; }, children: [_jsxs("span", { style: { minWidth: 0, flex: 1 }, children: [_jsx("span", { style: { display: 'block', fontSize: 13, fontWeight: 600, color: p.text }, children: a.title }), a.summary && (_jsx("span", { style: { display: 'block', marginTop: 2, fontSize: 11.5, lineHeight: 1.4, color: p.muted }, children: a.summary }))] }), _jsx("span", { "aria-hidden": true, style: { display: 'inline-flex', color: p.faint, flexShrink: 0 }, children: _jsx(IconChevron, {}) })] }, a.id))) })] }, `${run.group ?? ''}-${i}`))) }));
+    return (_jsx("div", { style: { display: 'grid', gap: 20 }, children: runs.map((run, i) => {
+            const hue = groupColour(articles, run.items[0], theme);
+            return (_jsxs("section", { children: [run.group && _jsx("p", { style: groupLabelStyle(p), children: run.group }), _jsx("div", { style: { display: 'grid', gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`, gap: 10 }, children: run.items.map((a) => (_jsxs("button", { type: "button", onClick: () => onOpen(a.id), style: cardButtonStyle(p, hue), onMouseEnter: (e) => { e.currentTarget.style.borderColor = hue.bar; e.currentTarget.style.transform = 'translateY(-1px)'; }, onMouseLeave: (e) => { e.currentTarget.style.borderColor = p.divider; e.currentTarget.style.transform = 'none'; }, children: [_jsx("span", { style: { display: 'block', fontSize: 14, fontWeight: 700, lineHeight: 1.35, color: p.text }, children: a.title }), a.summary && (_jsx("span", { style: { display: 'block', marginTop: 6, fontSize: 12.5, lineHeight: 1.45, color: p.muted }, children: a.summary })), _jsxs("span", { style: cardFooterStyle(p), children: [_jsx("span", { children: a.sources?.length ? count(language, 'kb.sources_count', a.sources.length) : '' }), _jsxs("span", { style: { color: hue.fg, fontWeight: 650 }, children: [t(language, 'kb.read'), " \u2192"] })] })] }, a.id))) })] }, `${run.group ?? ''}-${i}`));
+        }) }));
+}
+// ── An article ──────────────────────────────────────────────────────────────
+function ArticleView({ article, prev, next, colour, guideHref, library, wide, language, palette: p, onOpen, onBack }) {
+    const sources = article.sources ?? [];
+    const aside = (guideHref || sources.length > 0) && (_jsxs("aside", { style: { display: 'grid', gap: 14, alignContent: 'start' }, children: [guideHref && (_jsxs("a", { href: guideHref, target: "_blank", rel: "noopener noreferrer", style: guideButtonStyle(colour), children: [_jsx(IconDownload, {}), _jsx("span", { children: t(language, 'kb.download_guide') })] })), sources.length > 0 && (_jsxs("div", { style: asideBoxStyle(p), children: [_jsx("p", { style: { ...groupLabelStyle(p), margin: '0 0 10px' }, children: t(language, 'kb.sources') }), _jsx("div", { style: { display: 'grid', gap: 12 }, children: sources.map((s) => _jsx(SourceItem, { source: s, library: library, language: language, palette: p }, s.href)) })] }))] }));
+    return (_jsxs(_Fragment, { children: [_jsxs("button", { type: "button", onClick: onBack, style: backButtonStyle(p), children: [_jsx("span", { "aria-hidden": true, style: { display: 'inline-flex' }, children: _jsx(IconBack, {}) }), t(language, 'kb.all_articles')] }), _jsxs("div", { style: { ...heroStyle, background: colour.bg, borderColor: colour.bar }, children: [article.group && _jsx("p", { style: { ...groupLabelStyle(p), color: colour.fg, margin: '0 0 6px' }, children: article.group }), _jsx("h2", { style: { ...titleStyle(p), fontSize: 20, margin: '0 34px 0 0' }, children: article.title }), article.summary && _jsx("p", { style: { ...bodyStyle(p), margin: '6px 0 0', color: p.muted }, children: article.summary })] }), _jsxs("div", { style: { display: 'grid', gridTemplateColumns: wide && aside ? 'minmax(0, 1fr) 260px' : 'minmax(0, 1fr)', gap: 24 }, children: [_jsx("div", { style: { minWidth: 0, maxWidth: 640 }, children: _jsx(ArticleBody, { body: article.body, palette: p }) }), aside] }), (prev || next) && (_jsxs("nav", { style: { display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 10, marginTop: 26, paddingTop: 16, borderTop: `1px solid ${p.divider}` }, children: [prev ? _jsx(PageLink, { label: t(language, 'kb.previous'), title: prev.title, onClick: () => onOpen(prev.id), palette: p }) : _jsx("span", {}), next ? _jsx(PageLink, { label: t(language, 'kb.next'), title: next.title, onClick: () => onOpen(next.id), palette: p, align: "right" }) : _jsx("span", {})] }))] }));
 }
-/** Exported for the tests — splits an article body into blocks. */
+function PageLink({ label, title, onClick, palette: p, align = 'left' }) {
+    return (_jsxs("button", { type: "button", onClick: onClick, style: { ...rowStyle, display: 'block', textAlign: align, border: `1px solid ${p.divider}`, padding: '10px 12px' }, onMouseEnter: (e) => { e.currentTarget.style.background = p.rowHover; }, onMouseLeave: (e) => { e.currentTarget.style.background = 'transparent'; }, children: [_jsx("span", { style: { display: 'block', fontSize: 11, color: p.faint }, children: align === 'left' ? `← ${label}` : `${label} →` }), _jsx("span", { style: { display: 'block', marginTop: 2, fontSize: 13, fontWeight: 600, color: p.text }, children: title })] }));
+}
+function SourceItem({ source: s, library, language, palette: p }) {
+    const byline = [s.authors, s.publisher, s.year].filter(Boolean).join(' · ');
+    return (_jsxs("div", { children: [_jsx("span", { style: kindChipStyle(p), children: t(language, `kb.kind.${s.kind}`) }), _jsx("a", { href: s.href, target: "_blank", rel: "noopener noreferrer", style: sourceTitleStyle(p), children: s.title }), byline && _jsx("span", { style: { display: 'block', marginTop: 2, fontSize: 11.5, lineHeight: 1.4, color: p.muted }, children: byline }), _jsxs("span", { style: { display: 'flex', flexWrap: 'wrap', gap: 6, marginTop: 6 }, children: [s.pdf && (_jsxs("a", { href: libraryUrl(s.pdf, library), target: "_blank", rel: "noopener noreferrer", style: pillLinkStyle(p, true), title: s.licence, children: [_jsx(IconDownload, { size: 11 }), " PDF"] })), _jsxs("a", { href: s.href, target: "_blank", rel: "noopener noreferrer", style: pillLinkStyle(p, false), children: [t(language, s.pdf ? 'kb.publisher' : 'kb.read_source'), " \u2197"] })] }), s.pdf && s.licence && (_jsx("span", { style: { display: 'block', marginTop: 4, fontSize: 10.5, lineHeight: 1.35, color: p.faint }, children: s.licence }))] }));
+}
+/** Exported for the tests and the PDF generator — splits a body into blocks. */
 export function parseArticleBody(body) {
     const blocks = [];
     const lines = body.replace(/\r\n?/g, '\n').split('\n');
@@ -142,6 +289,10 @@ function ArticleBody({ body, palette: p }) {
             return (_jsx(List, { style: listStyle(p), children: b.items.map((item, j) => _jsx("li", { style: { marginTop: j ? 4 : 0 }, children: inline(item) }, j)) }, i));
         }) }));
 }
+/** `{n}` into the singular or plural key (`<key>_one` / `<key>`). */
+function count(language, key, n) {
+    return t(language, n === 1 ? `${key}_one` : key).replace('{n}', String(n));
+}
 // ── Icons ───────────────────────────────────────────────────────────────────
 function IconClose() {
     return (_jsx("svg", { viewBox: "0 0 24 24", width: "16", height: "16", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", "aria-hidden": "true", children: _jsx("path", { d: "M6 6l12 12M18 6L6 18" }) }));
@@ -152,6 +303,9 @@ function IconBack() {
 function IconChevron() {
     return (_jsx("svg", { viewBox: "0 0 12 12", width: "11", height: "11", "aria-hidden": "true", children: _jsx("path", { d: "M4 2 L8 6 L4 10", fill: "none", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round" }) }));
 }
+function IconDownload({ size = 16 }) {
+    return (_jsx("svg", { viewBox: "0 0 24 24", width: size, height: size, fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("path", { d: "M12 3v12M7 10l5 5 5-5M5 21h14" }) }));
+}
 /** The book glyph for the menu row. Exported so <AdvancedMenu> can use it. */
 export function IconBook() {
     return (_jsxs("svg", { viewBox: "0 0 24 24", width: "15", height: "15", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [_jsx("path", { d: "M4 5.5A2.5 2.5 0 0 1 6.5 3H20v15H6.5A2.5 2.5 0 0 0 4 20.5z" }), _jsx("path", { d: "M4 20.5A2.5 2.5 0 0 0 6.5 23H20v-5" }), _jsx("path", { d: "M8 7h8M8 11h6" })] }));
@@ -168,20 +322,22 @@ const overlayStyle = {
     zIndex: NAV_OVERLAY_Z_INDEX + 100,
     fontFamily: "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif",
 };
-// Wider than About (460): this is for reading, and 60-odd characters a line
-// is where prose stops being tiring.
+// A page, not a panel: wide enough for three columns of cards, or an article
+// beside its sources. The body column itself stops at 640px, since 60-odd
+// characters a line is where prose stops being tiring.
 const cardStyle = (p) => ({
     position: 'relative',
     width: '100%',
-    maxWidth: 560,
-    maxHeight: 'calc(100vh - 32px)',
+    maxWidth: 980,
+    height: 'calc(100vh - 32px)',
+    maxHeight: 900,
     overflowY: 'auto',
     background: p.surface,
     color: p.text,
     borderRadius: 16,
     border: `1px solid ${p.border}`,
     boxShadow: p.shadow,
-    padding: '22px 24px 24px',
+    padding: '22px 24px 28px',
     boxSizing: 'border-box',
 });
 const closeButtonStyle = (p) => ({
@@ -198,13 +354,14 @@ const closeButtonStyle = (p) => ({
     background: 'transparent',
     color: p.muted,
     cursor: 'pointer',
+    zIndex: 1,
 });
 const backButtonStyle = (p) => ({
     display: 'inline-flex',
     alignItems: 'center',
     gap: 4,
     padding: '4px 6px 4px 2px',
-    margin: '-4px 0 0 -2px',
+    margin: '-4px 0 10px -2px',
     border: 0,
     borderRadius: 6,
     background: 'transparent',
@@ -218,7 +375,7 @@ const identityRowStyle = {
     display: 'flex',
     alignItems: 'center',
     gap: 12,
-    margin: '0 34px 18px 0',
+    margin: '0 34px 14px 0',
 };
 const markTileStyle = (p) => ({
     display: 'inline-flex',
@@ -232,7 +389,7 @@ const markTileStyle = (p) => ({
 });
 const titleStyle = (p) => ({
     margin: 0,
-    fontSize: 17,
+    fontSize: 18,
     fontWeight: 700,
     letterSpacing: '-0.01em',
     lineHeight: 1.3,
@@ -244,13 +401,95 @@ const subtitleStyle = (p) => ({
     color: p.muted,
 });
 const groupLabelStyle = (p) => ({
-    margin: '0 0 4px',
+    margin: '0 0 8px',
     fontSize: 10.5,
     fontWeight: 700,
     letterSpacing: '0.07em',
     textTransform: 'uppercase',
     color: p.faint,
 });
+const cardButtonStyle = (p, hue) => ({
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'stretch',
+    minHeight: 132,
+    padding: '14px 14px 12px 16px',
+    borderRadius: 12,
+    border: `1px solid ${p.divider}`,
+    borderLeft: `4px solid ${hue.bar}`,
+    background: 'transparent',
+    textAlign: 'left',
+    fontFamily: 'inherit',
+    cursor: 'pointer',
+    transition: 'border-color 120ms, transform 120ms',
+});
+const cardFooterStyle = (p) => ({
+    display: 'flex',
+    justifyContent: 'space-between',
+    gap: 8,
+    marginTop: 'auto',
+    paddingTop: 12,
+    fontSize: 11.5,
+    color: p.faint,
+});
+const heroStyle = {
+    padding: '16px 18px',
+    margin: '0 0 20px',
+    borderRadius: 12,
+    borderLeft: '4px solid',
+};
+const guideButtonStyle = (hue) => ({
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 8,
+    padding: '10px 12px',
+    borderRadius: 10,
+    background: hue.bar,
+    color: '#ffffff',
+    fontSize: 13,
+    fontWeight: 650,
+    textDecoration: 'none',
+});
+const asideBoxStyle = (p) => ({
+    padding: '14px 14px 16px',
+    borderRadius: 12,
+    border: `1px solid ${p.divider}`,
+});
+const kindChipStyle = (p) => ({
+    display: 'inline-block',
+    marginBottom: 4,
+    padding: '1px 7px',
+    borderRadius: 999,
+    background: p.chipBg,
+    color: p.chipText,
+    fontSize: 10,
+    fontWeight: 650,
+    letterSpacing: '0.02em',
+});
+const sourceTitleStyle = (p) => ({
+    display: 'block',
+    fontSize: 12.5,
+    fontWeight: 650,
+    lineHeight: 1.4,
+    color: p.text,
+    textDecoration: 'none',
+});
+const pillLinkStyle = (p, primary) => ({
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: 4,
+    flexShrink: 0,
+    padding: '3px 9px',
+    borderRadius: 999,
+    border: `1px solid ${primary ? p.accentBorder : p.divider}`,
+    background: primary ? p.accentBg : 'transparent',
+    color: primary ? p.accentText : p.muted,
+    fontSize: 11,
+    fontWeight: 650,
+    textDecoration: 'none',
+    whiteSpace: 'nowrap',
+});
 const rowStyle = {
     display: 'flex',
     alignItems: 'center',
@@ -266,22 +505,22 @@ const rowStyle = {
     transition: 'background 120ms',
 };
 const subheadingStyle = (p) => ({
-    margin: '6px 0 0',
-    fontSize: 13.5,
+    margin: '8px 0 0',
+    fontSize: 14.5,
     fontWeight: 700,
     color: p.text,
 });
 const bodyStyle = (p) => ({
     margin: 0,
-    fontSize: 13.5,
-    lineHeight: 1.6,
+    fontSize: 14,
+    lineHeight: 1.65,
     color: p.body,
 });
 const listStyle = (p) => ({
     margin: 0,
     paddingLeft: 20,
-    fontSize: 13.5,
-    lineHeight: 1.55,
+    fontSize: 14,
+    lineHeight: 1.6,
     color: p.body,
 });
 //# sourceMappingURL=KnowledgeBaseDialog.js.map