@eintrek/erp-shell 0.1.74 → 0.1.75

package/dist/chunks/{guide-runtime-Dl8V1iy9.esm.js → format-DCTuLpBU.esm.js}

@@ -1,7 +1,7 @@
 'use client';
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import * as React from 'react';
-import { useSyncExternalStore, useMemo, useRef, useState, useEffect, useLayoutEffect, useCallback } from 'react';
+import { useSyncExternalStore, useMemo, useEffect, useRef, useState, useLayoutEffect, useCallback } from 'react';
 import { createPortal } from 'react-dom';
 import { computePosition, offset, shift, arrow } from '@floating-ui/dom';
 
@@ -337,18 +337,27 @@ function publishGuideEntry(next, openPanel) {
         emit();
     }
 }
-const NO_PAGES = { page: null, listed: 0 };
+const NO_PAGES = { page: null, listed: 0, sections: [] };
 let pages = NO_PAGES;
 let openPageImpl = null;
 let openPagesImpl = null;
-/** Called by the host: this page's guide and the listed count, and how to open them. */
-function publishPageGuides(next, openPage, openPages) {
+let openSectionImpl = null;
+const sectionsKey = (x) => (x ?? []).map(s => `${s.key}\u0000${s.title}`).join("\u0001");
+/** Called by the host: this page's guide, the listed count, the sections on screen, and how to open them. */
+function publishPageGuides(next, openPage, openPages, openSection = null) {
     const n = next ?? NO_PAGES;
     openPageImpl = openPage;
     openPagesImpl = openPages;
-    const same = n.listed === pages.listed && (n.page?.title ?? null) === (pages.page?.title ?? null);
+    openSectionImpl = openSection;
+    const same = n.listed === pages.listed &&
+        (n.page?.title ?? null) === (pages.page?.title ?? null) &&
+        sectionsKey(n.sections) === sectionsKey(pages.sections);
     if (!same) {
-        pages = n.page || n.listed ? { page: n.page ? { title: n.page.title } : null, listed: n.listed } : NO_PAGES;
+        const sections = (n.sections ?? []).map(x => ({ key: x.key, title: x.title }));
+        pages =
+            n.page || n.listed || sections.length
+                ? { page: n.page ? { title: n.page.title } : null, listed: n.listed, sections }
+                : NO_PAGES;
         emit();
     }
 }
@@ -356,6 +365,8 @@ function guideMenuItems(e, p = NO_PAGES) {
     const items = [];
     if (p.page)
         items.push("page");
+    if ((p.sections ?? []).length > 0)
+        items.push("sections");
     if (e && e.total > 0)
         items.push("missions");
     if (p.listed > 0)
@@ -405,6 +416,79 @@ function usePageGuideEntry() {
     const title = p.page?.title ?? null;
     return useMemo(() => (title === null ? null : { title, open: openPageGuide }), [title]);
 }
+/**
+ * Opens a section guide ("อธิบายส่วนนี้"), when it is on screen here for this
+ * person. The values it shows are the ones the app last rendered
+ * (`useSectionGuideValues`).
+ */
+function openSectionGuide(key) {
+    openSectionImpl?.(key);
+}
+const sectionValues = new Map();
+const valueListeners = new Set();
+let valuesVersion = 0;
+function valuesSig(v) {
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(Math.random());
+    }
+}
+/**
+ * Sets (or with undefined, clears) a section guide's live values. The
+ * engine reads the latest whenever it draws a step, so a page that
+ * re-renders mid-guide never leaves an old number on screen.
+ */
+function setSectionGuideValues(key, values) {
+    const prev = sectionValues.get(key);
+    if (values === undefined) {
+        if (!prev)
+            return;
+        sectionValues.delete(key);
+    }
+    else {
+        const sig = valuesSig(values);
+        if (prev && prev.sig === sig)
+            return;
+        sectionValues.set(key, { values, sig });
+    }
+    valuesVersion++;
+    valueListeners.forEach(l => l());
+}
+/** A section guide's live values now (empty when the app has given none). */
+function getSectionGuideValues(key) {
+    return (key && sectionValues.get(key)?.values) || {};
+}
+/** Re-renders when any section guide's values change (the engine's own use). */
+function useSectionValuesVersion() {
+    return useSyncExternalStore(l => {
+        valueListeners.add(l);
+        return () => {
+            valueListeners.delete(l);
+        };
+    }, () => valuesVersion, () => 0);
+}
+/**
+ * Hands a section guide the numbers its copy uses, from the component that
+ * computes them: `useSectionGuideValues("cash-flow", { month: "ม.ค.", cashIn,
+ * … })`. Call it on every render (the latest wins); they go when the
+ * component unmounts. undefined values: nothing.
+ */
+function useSectionGuideValues(key, values) {
+    const sig = values === undefined ? "" : valuesSig(values);
+    useEffect(() => {
+        if (values !== undefined)
+            setSectionGuideValues(key, values);
+        // sig stands for the values.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key, sig]);
+    useEffect(() => {
+        if (values === undefined)
+            return;
+        return () => setSectionGuideValues(key, undefined);
+    }, [key, values === undefined]); // eslint-disable-line react-hooks/exhaustive-deps
+}
 
 /** The synthetic mission key of a page guide: `page:<key>`. */
 const PAGE_PREFIX = "page:";
@@ -583,6 +667,140 @@ function currentPage(suite, where, ctx) {
 function listedPages(suite, ctx) {
     return validPages(suite).filter(p => p.href !== undefined && pageShown(p, ctx));
 }
+/* ------------------------------------------------------------------ */
+/* Section guides ("อธิบายส่วนนี้", shell 0.1.75)                        */
+/* ------------------------------------------------------------------ */
+/** The synthetic mission key of a section guide: `section:<key>`. */
+const SECTION_PREFIX = "section:";
+function isSectionMissionKey(key) {
+    return !!key && key.startsWith(SECTION_PREFIX);
+}
+function sectionKeyOf(missionKey) {
+    return isSectionMissionKey(missionKey) ? missionKey.slice(SECTION_PREFIX.length) : undefined;
+}
+/** Why a section guide cannot run, or null when it can. */
+function sectionProblem(app, section) {
+    if (!section || typeof section.key !== "string" || !PAGE_KEY_RE.test(section.key))
+        return "its key is not [a-z0-9-]";
+    if (`${app}.section.${section.key}`.length > ROW_KEY_MAX)
+        return `its row key is over ${ROW_KEY_MAX} characters`;
+    if (!Number.isInteger(section.version) || section.version < 1)
+        return "its version is not a whole number ≥ 1";
+    const routes = Array.isArray(section.route) ? section.route : [section.route];
+    if (!routes.length || routes.some(r => typeof r !== "string" || !r.startsWith("/")))
+        return "it has no route";
+    if (typeof section.anchor !== "string" || !section.anchor)
+        return "it has no anchor";
+    if (!Array.isArray(section.steps) || section.steps.length === 0)
+        return "it has no steps";
+    for (const st of section.steps) {
+        const kind = st.kind ?? "view";
+        if (kind !== "view")
+            return `step "${st.key}" is a ${kind} step (a section guide only reads)`;
+    }
+    return null;
+}
+const validSectionCache = new WeakMap();
+/** The suite's section guides that can run (as validPages: the rest dropped, with a warning in development). */
+function validSections(suite) {
+    const hit = validSectionCache.get(suite);
+    if (hit)
+        return hit;
+    const out = [];
+    const seen = new Set();
+    for (const section of suite.sections ?? []) {
+        let problem = sectionProblem(suite.app, section);
+        if (!problem && seen.has(section.key))
+            problem = "another section guide has the same key";
+        if (problem) {
+            const id = `${suite.key}:section:${section?.key}:${problem}`;
+            if (!warned.has(id)) {
+                warned.add(id);
+                devWarn(`section guide "${section?.key}" dropped: ${problem}`);
+            }
+            continue;
+        }
+        seen.add(section.key);
+        out.push(section);
+    }
+    validSectionCache.set(suite, out);
+    return out;
+}
+function findSection(suite, key) {
+    return key ? validSections(suite).find(s => s.key === key) : undefined;
+}
+/** A live value is missing: undefined, null, "" or a number that is not finite. */
+function valueMissing(v) {
+    return v === undefined || v === null || v === "" || (typeof v === "number" && !Number.isFinite(v));
+}
+function textOf(t, ctx) {
+    try {
+        return typeof t === "function" ? t(ctx) : t;
+    }
+    catch {
+        return "";
+    }
+}
+const sectionMissionCache = new WeakMap();
+/**
+ * The section guide as a mission the machine plays: `section:<key>`, read
+ * steps only, checkpoints unless they say otherwise. A step is skipped while
+ * a value it `needs` is missing, or when its title comes out empty.
+ */
+function sectionMission(section) {
+    const hit = sectionMissionCache.get(section);
+    if (hit)
+        return hit;
+    const steps = section.steps.map(st => {
+        const { route: _route, resumeUrl: _resume, ...rest } = st;
+        const own = st.skipIf;
+        return {
+            ...rest,
+            kind: "view",
+            checkpoint: st.checkpoint ?? true,
+            skipIf: (ctx) => {
+                const values = ctx.values ?? {};
+                if ((st.needs ?? []).some(k => valueMissing(values[k])))
+                    return true;
+                if (!textOf(st.title, ctx).trim())
+                    return true;
+                return own ? own(ctx) : false;
+            },
+        };
+    });
+    const m = { key: SECTION_PREFIX + section.key, title: section.title, minutes: 1, steps };
+    sectionMissionCache.set(section, m);
+    return m;
+}
+/** Whether the section guide applies here: one of its routes matches and its root is on screen. */
+function sectionApplies(section, where) {
+    const routes = Array.isArray(section.route) ? section.route : [section.route];
+    if (!routes.some(r => !!matchRoute(r, where.pathname, where.search, where.code)))
+        return false;
+    try {
+        return where.isVisible(section.anchor);
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether this person has the section guide: `visible` (only true) and `requires`. */
+function sectionShown(section, ctx) {
+    try {
+        if (section.visible && section.visible(ctx) !== true)
+            return false;
+        if (section.requires && !ctx.can(section.requires))
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The section guides on screen here that this person has, in the suite's order. */
+function sectionsHere(suite, where, ctx) {
+    return validSections(suite).filter(s => sectionApplies(s, where) && sectionShown(s, ctx));
+}
 
 /* ------------------------------------------------------------------ */
 /* Copy                                                                 */
@@ -597,6 +815,7 @@ const COPY = {
     hiddenToast: "ซ่อนแล้ว",
     aborted: "ไกด์ไปต่อไม่ได้ ลองอีกครั้งภายหลัง",
     pageDone: "จบคู่มือหน้านี้",
+    sectionDone: "จบคำอธิบายส่วนนี้",
     bridgeTitle: "กดปุ่มเมนู",
     bridgeWhy: (app) => `เมนูทั้งหมดของ ${app} อยู่ในนี้`,
 };
@@ -609,8 +828,10 @@ function initialGuideState(audience, progress, pages) {
         pageAudience: pages?.pageAudience ?? "none",
         pagesMode: pages?.pagesMode ?? "off",
         pages: pages?.pages ?? {},
+        sections: pages?.sections ?? {},
         pageRun: null,
         panelSection: "all",
+        autoPassed: null,
         audience,
         progress,
         screen: { name: "idle" },
@@ -630,6 +851,10 @@ function findMission(suite, key) {
         const page = findPage(suite, pageKeyOf(key));
         return page ? pageMission(page) : undefined;
     }
+    if (isSectionMissionKey(key)) {
+        const section = findSection(suite, sectionKeyOf(key));
+        return section ? sectionMission(section) : undefined;
+    }
     return suite.missions.find(m => m.key === key);
 }
 /**
@@ -667,6 +892,7 @@ function guideContext(env, data, params = {}) {
         facts: env.facts,
         can: env.can,
         visible: (anchor) => env.isVisible(anchor),
+        values: env.values ?? {},
     };
 }
 function resolveText(t, ctx) {
@@ -980,7 +1206,7 @@ function announceStep(d, suite, env) {
     const ctx = guideContext(env, d.state.progress.context, routeParamsFor(step, env));
     const title = s.bridge ? COPY.bridgeTitle : plainTitle(resolveText(step.title, ctx));
     const why = s.bridge ? COPY.bridgeWhy(suite.appName) : plainTitle(resolveText(step.why, ctx));
-    const pos = stepPosition(mission, s.index, env, d.state.progress.context);
+    const pos = stepPosition(mission, s.index, env, d.state.progress.context, autoPassedOf(d.state, mission.key));
     d.effects.push({
         type: "announce",
         text: `ขั้นที่ ${pos.no} จาก ${pos.total}. ${title}${why ? `. ${why}` : ""}`,
@@ -991,7 +1217,7 @@ function announceStep(d, suite, env) {
  * whose `requires` they lack or whose `skipIf` holds is left out (the step on
  * screen always counts).
  */
-function stepPosition(mission, index, env, context) {
+function stepPosition(mission, index, env, context, autoPassed = []) {
     let no = 0;
     let total = 0;
     mission.steps.forEach((step, i) => {
@@ -1001,6 +1227,12 @@ function stepPosition(mission, index, env, context) {
             const ctx = guideContext(env, context, routeParamsFor(step, env));
             if (step.skipIf && safe(() => step.skipIf(ctx), false))
                 return;
+            // A step that passed by itself (shell ≥ 0.1.75): before this one, as
+            // recorded; after it, one whose outcome already holds now.
+            if (i < index && autoPassed.includes(i))
+                return;
+            if (i > index && wouldAutoPass(step, env))
+                return;
         }
         total++;
         if (i <= index)
@@ -1008,6 +1240,17 @@ function stepPosition(mission, index, env, context) {
     });
     return { no: Math.max(no, 1), total: Math.max(total, 1) };
 }
+/** A step entered now would pass at once: a click or select step whose route or visible outcome holds. */
+function wouldAutoPass(step, env) {
+    const kind = stepKind(step);
+    if (step.autoPass === false || kind === "input" || kind === "view")
+        return false;
+    return safe(() => stateTriggerHolds(step, env) !== null, false);
+}
+/** The steps of this mission that passed by themselves in this run. */
+function autoPassedOf(state, mission) {
+    return state.autoPassed?.mission === mission ? state.autoPassed.steps : [];
+}
 /** "กด [บันทึก]" → "กด บันทึก" (for screen readers). */
 function plainTitle(t) {
     return t.replace(/\[([^\]]+)\]/g, "$1");
@@ -1020,6 +1263,8 @@ function enterStep(d, suite, env, mission, index, opts) {
     const steps = mission.steps;
     let i = Math.max(0, index);
     let firstPass = true;
+    if (d.state.autoPassed?.mission !== mission.key)
+        d.state = { ...d.state, autoPassed: { mission: mission.key, steps: [] } };
     while (i < steps.length) {
         const step = steps[i];
         const params = routeParamsFor(step, env);
@@ -1041,6 +1286,9 @@ function enterStep(d, suite, env, mission, index, opts) {
             const held = stateTriggerHolds(step, env);
             if (held) {
                 captureInto(d, step, held, ctx);
+                const ap = d.state.autoPassed;
+                if (!ap.steps.includes(i))
+                    d.state = { ...d.state, autoPassed: { mission: ap.mission, steps: [...ap.steps, i] } };
                 i++;
                 continue;
             }
@@ -1054,9 +1302,10 @@ function enterStep(d, suite, env, mission, index, opts) {
     const step = steps[i];
     const ctx = guideContext(env, d.state.progress.context, routeParamsFor(step, env));
     const page = pageKeyOf(mission.key);
+    const section = sectionKeyOf(mission.key);
     const where = placeRoute(steps, i);
-    // A page guide is on its page: leaving it ends the guide (never "ทำต่อ").
-    const away = !page && !!where && !matchRoute(where, env.pathname, env.search, env.code);
+    // A page or section guide is on its page: leaving it ends the guide (never "ทำต่อ").
+    const away = !page && !section && !!where && !matchRoute(where, env.pathname, env.search, env.code);
     const bridge = !away && needsBridge(step, env, ctx);
     const nts = !away && !bridge && nothingToSaveHolds(step, env, ctx);
     setScreen(d, {
@@ -1074,6 +1323,7 @@ function enterStep(d, suite, env, mission, index, opts) {
         status: away || bridge ? null : stepStatus(shownStep(step, nts), ctx),
         replayNext: !away && !bridge && opts.replay && replayCanGoOn(mission, i, env, d.state.progress.context, nts),
         ...(page ? { page } : {}),
+        ...(section ? { section } : {}),
     });
     if (!opts.replay) {
         const cp = checkpointAtOrBefore(steps, i);
@@ -1238,9 +1488,9 @@ function advance(d, suite, env, capture) {
     enterStep(d, suite, env, mission, s.index + 1, { replay: s.replay });
 }
 function finishMission(d, suite, env, mission, replay) {
-    if (isPageMissionKey(mission.key)) {
+    if (isPageMissionKey(mission.key) || isSectionMissionKey(mission.key)) {
         endPage(d, suite, "completed");
-        d.effects.push({ type: "toast", text: COPY.pageDone });
+        d.effects.push({ type: "toast", text: isSectionMissionKey(mission.key) ? COPY.sectionDone : COPY.pageDone });
         return;
     }
     if (replay) {
@@ -1344,7 +1594,8 @@ function startMission(d, suite, env, key, replay) {
     // A mission already done is only ever replayed; its done status stays.
     const isReplay = replay || entry?.status === "done";
     const before = d.state.progress;
-    d.state = { ...d.state, panelOpen: false, justDone: null };
+    // A new run: what passed by itself is counted afresh.
+    d.state = { ...d.state, panelOpen: false, justDone: null, autoPassed: null };
     if (d.state.progress.welcome === "not_seen")
         withProgress(d, { welcome: "started" });
     if (!isReplay && d.state.progress.mission_key !== key)
@@ -1503,14 +1754,72 @@ function recordPage(d, suite, key, status) {
     d.state = { ...d.state, pages: { ...d.state.pages, [key]: { version: page.version, status, rev: prev?.rev ?? 0 } } };
     d.effects.push({ type: "savePage", key, version: page.version, status });
 }
-/** The page guide ends: its row written when it is due one; back to idle. */
+/** The section guide's row says this person has ended this version of it. */
+function sectionRecorded(state, section) {
+    const row = state.sections?.[section.key];
+    return !!row && row.version >= section.version;
+}
+/** Write a section guide's row (once per section and version). */
+function recordSection(d, suite, key, status) {
+    const section = findSection(suite, key);
+    if (!section || sectionRecorded(d.state, section))
+        return;
+    const prev = d.state.sections?.[key];
+    d.state = { ...d.state, sections: { ...d.state.sections, [key]: { version: section.version, status, rev: prev?.rev ?? 0 } } };
+    d.effects.push({ type: "savePage", key, version: section.version, status, kind: "section" });
+}
+/** The page or section guide on screen, or null. */
+function readOf(s) {
+    if (s.name !== "step")
+        return null;
+    if (s.page)
+        return { kind: "page", key: s.page };
+    if (s.section)
+        return { kind: "section", key: s.section };
+    return null;
+}
+/** Whether a page or section guide still applies where the person is. */
+function readStillHere(suite, r, env) {
+    if (r.kind === "page")
+        return pageStillHere(suite, r.key, env);
+    const section = findSection(suite, r.key);
+    return !!section && sectionApplies(section, whereOf(env));
+}
+/** The page or section guide ends: its row written when it is due one; back to idle. */
 function endPage(d, suite, how) {
     const run = d.state.pageRun;
-    if (run?.write)
-        recordPage(d, suite, run.key, how);
+    if (run?.write) {
+        if (run.kind === "section")
+            recordSection(d, suite, run.key, how);
+        else
+            recordPage(d, suite, run.key, how);
+    }
     d.state = { ...d.state, pageRun: null, replayPage: null };
     setScreen(d, { name: "idle" });
 }
+/** The section guides on screen here that this person has (the "?" entries, the buttons). */
+function sectionsAvailable(suite, env) {
+    return sectionsHere(suite, whereOf(env), guideContext(env, {})).map(x => x.key);
+}
+function startSection(d, suite, env, key, write) {
+    const section = findSection(suite, key);
+    if (!section)
+        return;
+    const mission = sectionMission(section);
+    d.state = {
+        ...d.state,
+        panelOpen: false,
+        justDone: null,
+        pageRun: { key, write, kind: "section" },
+        autoPassed: null,
+        replayPage: {
+            mission: mission.key,
+            anchors: abortAnchorsOf(mission).filter(a => safe(() => env.isVisible(a), false)),
+            dialog: safe(() => env.dialogOpen?.() === true, false),
+        },
+    };
+    enterStep(d, suite, env, mission, 0, { replay: true });
+}
 function startPage(d, suite, env, key, write) {
     const page = findPage(suite, key);
     if (!page)
@@ -1520,7 +1829,8 @@ function startPage(d, suite, env, key, write) {
         ...d.state,
         panelOpen: false,
         justDone: null,
-        pageRun: { key, write },
+        pageRun: { key, write, kind: "page" },
+        autoPassed: null,
         // What is open now is the person's: ending the guide leaves it alone.
         replayPage: {
             mission: mission.key,
@@ -1620,7 +1930,7 @@ function reduceGuide(state, action, suite, env) {
                 break;
             // A mission always wins over a page guide: a running one ends (its row
             // written if due), an offer goes unrecorded.
-            if (s.name === "step" && s.page)
+            if (readOf(s))
                 endPage(d, suite, "skipped");
             else if (s.name === "pageOffer")
                 setScreen(d, { name: "idle" });
@@ -1641,6 +1951,7 @@ function reduceGuide(state, action, suite, env) {
             const stepAt = mission.steps.findIndex(st => st.key === d.state.progress.step_key);
             const cpAt = mission.steps.findIndex(st => st.key === d.state.progress.checkpoint_key);
             const index = stepAt >= 0 ? checkpointAtOrBefore(mission.steps, stepAt) : Math.max(cpAt, 0);
+            d.state = { ...d.state, autoPassed: null };
             enterStep(d, suite, env, mission, index, { replay: false });
             break;
         }
@@ -1655,8 +1966,9 @@ function reduceGuide(state, action, suite, env) {
             }
             if (s.name !== "step")
                 break;
-            if (s.page && !pageStillHere(suite, s.page, env)) {
-                // Leaving the page ends its guide, silently.
+            const read = readOf(s);
+            if (read && !readStillHere(suite, read, env)) {
+                // Leaving the page (or the section's root going) ends its guide, silently.
                 endPage(d, suite, "skipped");
                 break;
             }
@@ -1689,7 +2001,7 @@ function reduceGuide(state, action, suite, env) {
                     break;
                 }
             }
-            if (!s.bridge && !stepTargetVisible(shownStep(step, s.nothingToSave), env, ctx, false) && offRoute(mission.steps, s.index, env, s.page)) {
+            if (!s.bridge && !stepTargetVisible(shownStep(step, s.nothingToSave), env, ctx, false) && offRoute(mission.steps, s.index, env, s.page ?? s.section)) {
                 // The target is missing because the page is another one.
                 recoverOffRoute(d, suite, env, false);
                 break;
@@ -1805,7 +2117,7 @@ function reduceGuide(state, action, suite, env) {
             const cur = d.state.screen;
             if (stepTargetVisible(shownStep(raw, cur.nothingToSave), env, ctx, cur.bridge))
                 break;
-            if (!cur.bridge && offRoute(mission.steps, cur.index, env, cur.page)) {
+            if (!cur.bridge && offRoute(mission.steps, cur.index, env, cur.page ?? cur.section)) {
                 recoverOffRoute(d, suite, env, false);
                 break;
             }
@@ -1826,7 +2138,7 @@ function reduceGuide(state, action, suite, env) {
             if (!mission)
                 break;
             const step = mission.steps[s.index];
-            if (!s.bridge && offRoute(mission.steps, s.index, env, s.page)) {
+            if (!s.bridge && offRoute(mission.steps, s.index, env, s.page ?? s.section)) {
                 recoverOffRoute(d, suite, env, false);
                 break;
             }
@@ -1843,7 +2155,7 @@ function reduceGuide(state, action, suite, env) {
                 advance(d, suite, env);
             }
             else if (policy === "abort") {
-                if (s.page)
+                if (readOf(s))
                     endPage(d, suite, "skipped");
                 else
                     exitMission(d);
@@ -1869,7 +2181,7 @@ function reduceGuide(state, action, suite, env) {
             if (s.name !== "step" || s.phase !== "missing")
                 break;
             const mission = findMission(suite, s.mission);
-            if (mission && !s.bridge && offRoute(mission.steps, s.index, env, s.page)) {
+            if (mission && !s.bridge && offRoute(mission.steps, s.index, env, s.page ?? s.section)) {
                 // Polling again cannot help on another page: go back to the step's.
                 recoverOffRoute(d, suite, env, true);
                 break;
@@ -1885,7 +2197,7 @@ function reduceGuide(state, action, suite, env) {
         case "exit":
             if (s.name !== "step")
                 break;
-            if (s.page) {
+            if (readOf(s)) {
                 // ✕, Escape or ปิดคู่มือ: ends silently.
                 pushAbort(d, suite, s);
                 endPage(d, suite, "skipped");
@@ -2044,7 +2356,7 @@ function reduceGuide(state, action, suite, env) {
             break;
         }
         case "back": {
-            if (s.name !== "step" || !s.page || s.phase !== "ready" || s.confirmExit)
+            if (s.name !== "step" || !readOf(s) || s.phase !== "ready" || s.confirmExit)
                 break;
             const mission = findMission(suite, s.mission);
             if (!mission)
@@ -2059,12 +2371,32 @@ function reduceGuide(state, action, suite, env) {
             break;
         }
         case "pageRow": {
+            if (action.kind === "section") {
+                const cur = d.state.sections?.[action.key];
+                if (cur && cur.version > action.row.version)
+                    break;
+                d.state = { ...d.state, sections: { ...d.state.sections, [action.key]: action.row } };
+                break;
+            }
             const cur = d.state.pages[action.key];
             if (cur && cur.version > action.row.version)
                 break;
             d.state = { ...d.state, pages: { ...d.state.pages, [action.key]: action.row } };
             break;
         }
+        case "startSection": {
+            // Never offered: only on request. Never over a mission step, a
+            // welcome, a gate or a celebration; only on screen, only theirs.
+            if (state.pageAudience === "none" || state.pagesMode === "off")
+                break;
+            if (s.name !== "idle" && s.name !== "pageOffer")
+                break;
+            if (!sectionsAvailable(suite, env).includes(action.section))
+                break;
+            const section = findSection(suite, action.section);
+            startSection(d, suite, env, section.key, !sectionRecorded(state, section));
+            break;
+        }
         case "idleCelebrate": {
             if (s.name !== "idle" || state.panelOpen)
                 break;
@@ -2193,6 +2525,7 @@ function parseGuidesAnswer(payload, suite) {
         ? data.page_audience
         : "none";
     const pages = parsePageRows(rows, suite.app);
+    const sections = parsePageRows(rows, suite.app, "section");
     let row = null;
     for (const r of rows) {
         if (isRecord(r) && r.guide_key === suite.key) {
@@ -2213,15 +2546,15 @@ function parseGuidesAnswer(payload, suite) {
         progress = row;
         newerOnServer = row.guide_version > suite.version;
     }
-    return { mode, audience: mode === "off" ? "none" : audience, progress, newerOnServer, pagesMode, pageAudience, pages };
+    return { mode, audience: mode === "off" ? "none" : audience, progress, newerOnServer, pagesMode, pageAudience, pages, sections };
 }
-/** The row key of a page guide: `<app>.page.<key>`. */
-function pageRowKey(app, key) {
-    return `${app}.page.${key}`;
+/** The row key of a page guide, `<app>.page.<key>`, or a section guide, `<app>.section.<key>`. */
+function pageRowKey(app, key, kind = "page") {
+    return `${app}.${kind}.${key}`;
 }
-/** Page rows among the list's rows, by page key. Off-shape rows are left out. */
-function parsePageRows(rows, app) {
-    const prefix = pageRowKey(app, "");
+/** Page (or section) rows among the list's rows, by key. Off-shape rows are left out. */
+function parsePageRows(rows, app, kind = "page") {
+    const prefix = pageRowKey(app, "", kind);
     const out = {};
     for (const r of rows) {
         if (!isRecord(r) || typeof r.guide_key !== "string" || !r.guide_key.startsWith(prefix))
@@ -2471,14 +2804,15 @@ async function storeGuides(adapter, suite, progress) {
     return null;
 }
 /**
- * Writes a page guide's row (`<app>.page.<key>`) once: the minimal body,
+ * Writes a page guide's row (`<app>.page.<key>`), or a section guide's
+ * (`<app>.section.<key>`, kind "section"), once: the minimal body,
  * with the same 409 handling as the tour's row. Another tab that already
  * recorded this version wins (its row is returned, nothing is sent again);
  * an older version's row is replaced with its rev; a newer one stops. Returns
  * the stored row, or null when it could not be saved.
  */
-async function storePageRow(adapter, app, key, version, status, rev) {
-    const guideKey = pageRowKey(app, key);
+async function storePageRow(adapter, app, key, version, status, rev, kind = "page") {
+    const guideKey = pageRowKey(app, key, kind);
     let at = rev;
     for (let attempt = 0; attempt < 2; attempt++) {
         let res;
@@ -3567,10 +3901,10 @@ function writeMirror(orgId, suite, p) {
     }
 }
 /** Page rows written in this tab, kept for a remount within the GET's cache time. */
-const pagesMirrorKey = (orgId, suite) => `erp-guide-pages:${orgId}:${suite.app}`;
-function readPagesMirror(orgId, suite) {
+const pagesMirrorKey = (orgId, suite, kind = "page") => `erp-guide-${kind === "section" ? "sections" : "pages"}:${orgId}:${suite.app}`;
+function readPagesMirror(orgId, suite, kind = "page") {
     try {
-        const raw = sessionStorage.getItem(pagesMirrorKey(orgId, suite));
+        const raw = sessionStorage.getItem(pagesMirrorKey(orgId, suite, kind));
         const parsed = raw ? JSON.parse(raw) : {};
         const out = {};
         for (const [k, v] of Object.entries(parsed ?? {})) {
@@ -3583,9 +3917,9 @@ function readPagesMirror(orgId, suite) {
         return {};
     }
 }
-function writePagesMirror(orgId, suite, pages) {
+function writePagesMirror(orgId, suite, pages, kind = "page") {
     try {
-        sessionStorage.setItem(pagesMirrorKey(orgId, suite), JSON.stringify(pages));
+        sessionStorage.setItem(pagesMirrorKey(orgId, suite, kind), JSON.stringify(pages));
     }
     catch {
         /* private mode */
@@ -3713,7 +4047,8 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
     const [answer, setAnswer] = useState(null);
     const missionsReady = config.ready !== false;
     const pagesReady = config.pagesReady ?? missionsReady;
-    const hasPages = useMemo(() => validPages(suite).length > 0, [suite]);
+    const hasPages = useMemo(() => validPages(suite).length > 0 || validSections(suite).length > 0, [suite]);
+    const hasSections = useMemo(() => validSections(suite).length > 0, [suite]);
     const enabled = primary && (missionsReady || (hasPages && pagesReady));
     const loaded = useRef(false);
     useEffect(() => {
@@ -3769,6 +4104,7 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
             pageAudience: pagesOn ? answer.pageAudience : "none",
             pagesMode: answer.pagesMode,
             pages: mergePageRows(answer.pages, readPagesMirror(organizationId, suite)),
+            sections: mergePageRows(answer.sections ?? {}, readPagesMirror(organizationId, suite, "section")),
         });
         stateRef.current = s;
         setState(s);
@@ -3777,8 +4113,12 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
     const pageRef = useRef({ pathname, search, sidebarOpen, facts: config.facts ?? {}, can: config.can });
     pageRef.current = { pathname, search, sidebarOpen, facts: config.facts ?? {}, can: config.can };
     const targetElRef = useRef(null);
+    // The section guide being opened (before its first step is on screen).
+    const openingSection = useRef(null);
     const env = useCallback(() => {
         const pg = pageRef.current;
+        const sc = stateRef.current?.screen;
+        const sectionKey = (sc?.name === "step" ? sc.section : undefined) ?? openingSection.current;
         return {
             code,
             pathname: pg.pathname,
@@ -3796,6 +4136,7 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
             sidebarOpen: pg.sidebarOpen,
             targetValue: () => fieldValue(targetElRef.current),
             dialogOpen: () => appDialogOpen(),
+            values: getSectionGuideValues(sectionKey),
         };
     }, [code]);
     /* ---------------- effects: save, announce, toast, navigate ---------------- */
@@ -3871,13 +4212,15 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
                 }
                 else if (e.type === "savePage") {
                     // Once per page and version; the machine already holds it as written.
-                    if (stateRef.current)
-                        writePagesMirror(organizationId, suite, stateRef.current.pages);
-                    const rev = stateRef.current?.pages[e.key]?.rev ?? 0;
-                    void storePageRow(adapterRef.current, suite.app, e.key, e.version, e.status, rev).then(row => {
+                    const kind = e.kind ?? "page";
+                    const rows = stateRef.current ? (kind === "section" ? stateRef.current.sections : stateRef.current.pages) : undefined;
+                    if (rows)
+                        writePagesMirror(organizationId, suite, rows, kind);
+                    const rev = rows?.[e.key]?.rev ?? 0;
+                    void storePageRow(adapterRef.current, suite.app, e.key, e.version, e.status, rev, kind).then(row => {
                         // eslint-disable-next-line @typescript-eslint/no-use-before-define
                         if (row)
-                            dispatchRef.current({ type: "pageRow", key: e.key, row });
+                            dispatchRef.current({ type: "pageRow", key: e.key, row, kind });
                     });
                 }
             }
@@ -3967,7 +4310,7 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
     /* ---------------- sync on route, sidebar, facts, DOM ---------------- */
     // A page guide's step runs while page guides are live; a mission's while
     // the missions are. The offer card is watched the same way (left: ignored).
-    const inStep = screen.name === "step" && (screen.page ? pagesLive : missionsLive);
+    const inStep = screen.name === "step" && (screen.page || screen.section ? pagesLive : missionsLive);
     const offerUp = pagesLive && screen.name === "pageOffer";
     const watching = inStep || offerUp;
     useEffect(() => {
@@ -4015,6 +4358,7 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
         const step = shownStep(raw, screen.nothingToSave);
         return { mission, step, raw };
     }, [state, screen, suite]);
+    const valuesVersion = useSectionValuesVersion();
     const stepCtx = useMemo(() => {
         if (!state)
             return null;
@@ -4023,7 +4367,7 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
         return guideContext(e, state.progress.context, params);
         // pathname/search/factsKey make it current.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [state, stepInfo, env, code, pathname, search, factsKey]);
+    }, [state, stepInfo, env, code, pathname, search, factsKey, valuesVersion]);
     const target = stepInfo && stepCtx && screen.name === "step"
         ? spotlightTarget(stepInfo.step, stepCtx, screen.bridge)
         : null;
@@ -4531,7 +4875,7 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
     /* ---------------- page guides: this page's, the offer, the list ---------------- */
     // `when` anchors (LIFF's sub-screens) come and go without a route change:
     // look again when the page changes.
-    const hasWhen = useMemo(() => validPages(suite).some(p => !!p.when), [suite]);
+    const hasWhen = useMemo(() => validPages(suite).some(p => !!p.when) || validSections(suite).length > 0, [suite]);
     const [domTick, setDomTick] = useState(0);
     useEffect(() => {
         if (!pagesLive || !hasWhen || typeof MutationObserver === "undefined")
@@ -4565,6 +4909,21 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [pagesLive, hasState, suite, env, pathname, search, factsKey, domTick]);
     const listed = useMemo(() => (pagesLive && ctxIdle ? listedPages(suite, ctxIdle) : []), [pagesLive, suite, ctxIdle]);
+    const sectionsNow = useMemo(() => pagesLive && hasState && hasSections
+        ? sectionsAvailable(suite, env()).map(k => ({ key: k, title: findSection(suite, k)?.title ?? "" }))
+        : [], 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [pagesLive, hasState, hasSections, suite, env, pathname, search, factsKey, domTick]);
+    const sectionsSig = sectionsNow.map(x => x.key).join(",");
+    const openSection = useCallback((key) => {
+        openingSection.current = key;
+        try {
+            dispatchRef.current({ type: "startSection", section: key });
+        }
+        finally {
+            openingSection.current = null;
+        }
+    }, []);
     const openPageHere = useCallback(() => {
         const p = pageHere(suite, env());
         if (p)
@@ -4575,8 +4934,10 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
             publishPageGuides(null, null, null);
             return;
         }
-        publishPageGuides({ page: pageNow ? { title: pageNow.title } : null, listed: listed.length }, openPageHere, () => dispatchRef.current({ type: "openPanel", section: "pages" }));
-    }, [pagesLive, hasState, pageNow, listed.length, openPageHere]);
+        publishPageGuides({ page: pageNow ? { title: pageNow.title } : null, listed: listed.length, sections: sectionsNow }, openPageHere, () => dispatchRef.current({ type: "openPanel", section: "pages" }), openSection);
+        // sectionsSig stands for sectionsNow.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [pagesLive, hasState, pageNow, listed.length, openPageHere, sectionsSig, openSection]);
     useEffect(() => () => publishPageGuides(null, null, null), []);
     // The first-visit offer: in "offer" mode, nothing else up, the welcome
     // not due here, and a moment of nothing loading on this page.
@@ -4693,12 +5054,13 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
         const missionNo = missionNumber(suite, mission.key, ctxIdle);
         const kind = stepKind(step);
         const bridge = screen.bridge;
-        const pos = stepPosition(mission, screen.index, env(), state.progress.context);
+        const pos = stepPosition(mission, screen.index, env(), state.progress.context, autoPassedOf(state, mission.key));
         const page = screen.page ? findPage(suite, screen.page) : undefined;
-        const pageBits = page
+        const section = screen.section ? findSection(suite, screen.section) : undefined;
+        const read = page ? { heading: `คู่มือหน้านี้ · ${page.title}`, exitLabel: "ปิดคู่มือ" } : section ? { heading: `อธิบายส่วนนี้ · ${section.title}`, exitLabel: "ปิดคำอธิบาย" } : null;
+        const pageBits = read
             ? {
-                heading: `คู่มือหน้านี้ · ${page.title}`,
-                exitLabel: "ปิดคู่มือ",
+                ...read,
                 showBack: kind === "view" && !!backTarget(mission, screen.index, env(), state.progress.context),
                 nextLabel: pos.no >= pos.total ? "เสร็จ" : undefined,
             }
@@ -4781,5 +5143,101 @@ function useFactsKey(facts) {
     }, [facts]);
 }
 
-export { API_EVENT as A, GUIDE_EVENT_PREFIX as G, GUIDE_LAYER_ATTRIBUTE as a, GuideErrorBoundary as b, GuideProgressConflict as c, GuideRuntime as d, apiCallDetail as e, emitGuideEvent as f, fillRoute as g, guideAnchor as h, guideMenuItems as i, guideMenuShown as j, matchRoute as k, loadGuides as l, matchApiPath as m, openPageGuide as n, openGuidePanel as o, openPagesPanel as p, reportApiEvent as q, reportApiCall as r, storeGuides as s, usePageGuideEntry as t, useGuideEntry as u, usePageGuides as v };
-//# sourceMappingURL=guide-runtime-Dl8V1iy9.esm.js.map
+const DEFAULT_STYLE = {
+    display: "inline-grid",
+    placeItems: "center",
+    width: 22,
+    height: 22,
+    padding: 0,
+    border: 0,
+    borderRadius: 999,
+    background: "transparent",
+    color: "inherit",
+    opacity: 0.6,
+    cursor: "pointer",
+    flex: "none",
+};
+function SectionGuideButton({ guideKey, values, className }) {
+    useSectionGuideValues(guideKey, values);
+    const { sections } = usePageGuides();
+    const here = (sections ?? []).find(s => s.key === guideKey);
+    if (!here)
+        return null;
+    return (jsx("button", { type: "button", className: className, style: className ? undefined : DEFAULT_STYLE, "aria-label": `อธิบายส่วนนี้ ${here.title}`, title: "\u0E2D\u0E18\u0E34\u0E1A\u0E32\u0E22\u0E2A\u0E48\u0E27\u0E19\u0E19\u0E35\u0E49", "data-guide-section-button": guideKey, onClick: e => {
+            // A header that opens or sorts on press must not hear it.
+            e.stopPropagation();
+            e.preventDefault();
+            openSectionGuide(guideKey);
+        }, children: jsxs("svg", { viewBox: "0 0 24 24", width: "16", height: "16", "aria-hidden": "true", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: [jsx("circle", { cx: "12", cy: "12", r: "10" }), jsx("path", { d: "M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3" }), jsx("path", { d: "M12 17h.01" })] }) }));
+}
+
+/**
+ * Small formatters for section guides' copy (shell 0.1.75): the app passes
+ * its own computed numbers, and the copy says them the way the page does —
+ * "ม.ค. รับ 500,000 − จ่าย 320,000 = คงเหลือ 180,000".
+ *
+ * Pure: the tests run it in Node.
+ */
+const THAI_MONTHS_SHORT = ["ม.ค.", "ก.พ.", "มี.ค.", "เม.ย.", "พ.ค.", "มิ.ย.", "ก.ค.", "ส.ค.", "ก.ย.", "ต.ค.", "พ.ย.", "ธ.ค."];
+const grouped = new Map();
+function nf(decimals) {
+    let f = grouped.get(decimals);
+    if (!f) {
+        f = new Intl.NumberFormat("en-US", { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+        grouped.set(decimals, f);
+    }
+    return f;
+}
+/**
+ * A baht amount with thousands separators, no currency sign: 500000 →
+ * "500,000"; 1234.5 → "1,234.50"; -320000 → "-320,000". Whole amounts
+ * have no decimals unless `decimals` says so; others have two. Not a
+ * finite number → "" (a step whose value is missing is skipped anyway).
+ */
+function formatBaht(n, opts = {}) {
+    const v = typeof n === "string" && n.trim() !== "" ? Number(n) : n;
+    if (typeof v !== "number" || !Number.isFinite(v))
+        return "";
+    const rounded = Math.round(v * 100) / 100;
+    const decimals = opts.decimals ?? (Number.isInteger(rounded) ? 0 : 2);
+    const out = nf(decimals).format(rounded);
+    // No "-0".
+    return out === "-0" || /^-0(\.0+)?$/.test(out) ? out.slice(1) : out;
+}
+/** The month's number 1–12 from "2026-01", "2026-01-15", a Date, or 1–12; null when none. */
+function monthOf(m) {
+    if (m instanceof Date)
+        return Number.isNaN(m.getTime()) ? null : { month: m.getMonth() + 1, year: m.getFullYear() };
+    if (typeof m === "number")
+        return Number.isInteger(m) && m >= 1 && m <= 12 ? { month: m } : null;
+    if (typeof m === "string") {
+        const iso = /^(\d{4})-(\d{1,2})(?:-\d{1,2})?/.exec(m.trim());
+        if (iso) {
+            const month = Number(iso[2]);
+            return month >= 1 && month <= 12 ? { month, year: Number(iso[1]) } : null;
+        }
+    }
+    return null;
+}
+/** "2026-01" (or a Date, or 1) → "ม.ค."; "" when it is not a month. */
+function thaiMonth(m) {
+    const x = monthOf(m);
+    return x ? THAI_MONTHS_SHORT[x.month - 1] : "";
+}
+/**
+ * "2026-01" → "ม.ค. 69" (the Buddhist year's last two digits), or with
+ * `{ year: "full" }` "ม.ค. 2569"; just the month when no year is known.
+ */
+function thaiMonthYear(m, opts = {}) {
+    const x = monthOf(m);
+    if (!x)
+        return "";
+    const name = THAI_MONTHS_SHORT[x.month - 1];
+    if (x.year === undefined)
+        return name;
+    const be = x.year + 543;
+    return `${name} ${opts.year === "full" ? be : String(be).slice(-2)}`;
+}
+
+export { API_EVENT as A, usePageGuides as B, useSectionGuideValues as C, GUIDE_EVENT_PREFIX as G, SectionGuideButton as S, THAI_MONTHS_SHORT as T, GUIDE_LAYER_ATTRIBUTE as a, GuideErrorBoundary as b, GuideProgressConflict as c, GuideRuntime as d, apiCallDetail as e, emitGuideEvent as f, fillRoute as g, formatBaht as h, guideAnchor as i, guideMenuItems as j, guideMenuShown as k, loadGuides as l, matchApiPath as m, matchRoute as n, openGuidePanel as o, openPageGuide as p, openPagesPanel as q, openSectionGuide as r, reportApiCall as s, reportApiEvent as t, setSectionGuideValues as u, storeGuides as v, thaiMonth as w, thaiMonthYear as x, useGuideEntry as y, usePageGuideEntry as z };
+//# sourceMappingURL=format-DCTuLpBU.esm.js.map