@eintrek/erp-shell 0.1.74 → 0.1.75

package/dist/chunks/{guide-runtime-YS2nUhwS.cjs → format-CVazK0hP.cjs}

@@ -357,18 +357,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();
     }
 }
@@ -376,6 +385,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)
@@ -425,6 +436,79 @@ function usePageGuideEntry() {
     const title = p.page?.title ?? null;
     return React.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 React.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);
+    React.useEffect(() => {
+        if (values !== undefined)
+            setSectionGuideValues(key, values);
+        // sig stands for the values.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key, sig]);
+    React.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:";
@@ -603,6 +687,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                                                                 */
@@ -617,6 +835,7 @@ const COPY = {
     hiddenToast: "ซ่อนแล้ว",
     aborted: "ไกด์ไปต่อไม่ได้ ลองอีกครั้งภายหลัง",
     pageDone: "จบคู่มือหน้านี้",
+    sectionDone: "จบคำอธิบายส่วนนี้",
     bridgeTitle: "กดปุ่มเมนู",
     bridgeWhy: (app) => `เมนูทั้งหมดของ ${app} อยู่ในนี้`,
 };
@@ -629,8 +848,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" },
@@ -650,6 +871,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);
 }
 /**
@@ -687,6 +912,7 @@ function guideContext(env, data, params = {}) {
         facts: env.facts,
         can: env.can,
         visible: (anchor) => env.isVisible(anchor),
+        values: env.values ?? {},
     };
 }
 function resolveText(t, ctx) {
@@ -1000,7 +1226,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}` : ""}`,
@@ -1011,7 +1237,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) => {
@@ -1021,6 +1247,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)
@@ -1028,6 +1260,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");
@@ -1040,6 +1283,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);
@@ -1061,6 +1306,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;
             }
@@ -1074,9 +1322,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, {
@@ -1094,6 +1343,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);
@@ -1258,9 +1508,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) {
@@ -1364,7 +1614,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)
@@ -1523,14 +1774,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)
@@ -1540,7 +1849,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,
@@ -1640,7 +1950,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" });
@@ -1661,6 +1971,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;
         }
@@ -1675,8 +1986,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;
             }
@@ -1709,7 +2021,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;
@@ -1825,7 +2137,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;
             }
@@ -1846,7 +2158,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;
             }
@@ -1863,7 +2175,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);
@@ -1889,7 +2201,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;
@@ -1905,7 +2217,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");
@@ -2064,7 +2376,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)
@@ -2079,12 +2391,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;
@@ -2213,6 +2545,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) {
@@ -2233,15 +2566,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))
@@ -2491,14 +2824,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;
@@ -3587,10 +3921,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 ?? {})) {
@@ -3603,9 +3937,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 */
@@ -3733,7 +4067,8 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
     const [answer, setAnswer] = React.useState(null);
     const missionsReady = config.ready !== false;
     const pagesReady = config.pagesReady ?? missionsReady;
-    const hasPages = React.useMemo(() => validPages(suite).length > 0, [suite]);
+    const hasPages = React.useMemo(() => validPages(suite).length > 0 || validSections(suite).length > 0, [suite]);
+    const hasSections = React.useMemo(() => validSections(suite).length > 0, [suite]);
     const enabled = primary && (missionsReady || (hasPages && pagesReady));
     const loaded = React.useRef(false);
     React.useEffect(() => {
@@ -3789,6 +4124,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);
@@ -3797,8 +4133,12 @@ function GuideRuntimeInner({ config, organizationId, code, routing, progress: pr
     const pageRef = React.useRef({ pathname, search, sidebarOpen, facts: config.facts ?? {}, can: config.can });
     pageRef.current = { pathname, search, sidebarOpen, facts: config.facts ?? {}, can: config.can };
     const targetElRef = React.useRef(null);
+    // The section guide being opened (before its first step is on screen).
+    const openingSection = React.useRef(null);
     const env = React.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,
@@ -3816,6 +4156,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 ---------------- */
@@ -3891,13 +4232,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 });
                     });
                 }
             }
@@ -3987,7 +4330,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;
     React.useEffect(() => {
@@ -4035,6 +4378,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 = React.useMemo(() => {
         if (!state)
             return null;
@@ -4043,7 +4387,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;
@@ -4551,7 +4895,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 = React.useMemo(() => validPages(suite).some(p => !!p.when), [suite]);
+    const hasWhen = React.useMemo(() => validPages(suite).some(p => !!p.when) || validSections(suite).length > 0, [suite]);
     const [domTick, setDomTick] = React.useState(0);
     React.useEffect(() => {
         if (!pagesLive || !hasWhen || typeof MutationObserver === "undefined")
@@ -4585,6 +4929,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 = React.useMemo(() => (pagesLive && ctxIdle ? listedPages(suite, ctxIdle) : []), [pagesLive, suite, ctxIdle]);
+    const sectionsNow = React.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 = React.useCallback((key) => {
+        openingSection.current = key;
+        try {
+            dispatchRef.current({ type: "startSection", section: key });
+        }
+        finally {
+            openingSection.current = null;
+        }
+    }, []);
     const openPageHere = React.useCallback(() => {
         const p = pageHere(suite, env());
         if (p)
@@ -4595,8 +4954,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]);
     React.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.
@@ -4713,12 +5074,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,
             }
@@ -4801,15 +5163,114 @@ function useFactsKey(facts) {
     }, [facts]);
 }
 
+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 (jsxRuntime.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: jsxRuntime.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: [jsxRuntime.jsx("circle", { cx: "12", cy: "12", r: "10" }), jsxRuntime.jsx("path", { d: "M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3" }), jsxRuntime.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)}`;
+}
+
 exports.API_EVENT = API_EVENT;
 exports.GUIDE_EVENT_PREFIX = GUIDE_EVENT_PREFIX;
 exports.GUIDE_LAYER_ATTRIBUTE = GUIDE_LAYER_ATTRIBUTE;
 exports.GuideErrorBoundary = GuideErrorBoundary;
 exports.GuideProgressConflict = GuideProgressConflict;
 exports.GuideRuntime = GuideRuntime;
+exports.SectionGuideButton = SectionGuideButton;
+exports.THAI_MONTHS_SHORT = THAI_MONTHS_SHORT;
 exports.apiCallDetail = apiCallDetail;
 exports.emitGuideEvent = emitGuideEvent;
 exports.fillRoute = fillRoute;
+exports.formatBaht = formatBaht;
 exports.guideAnchor = guideAnchor;
 exports.guideMenuItems = guideMenuItems;
 exports.guideMenuShown = guideMenuShown;
@@ -4819,10 +5280,15 @@ exports.matchRoute = matchRoute;
 exports.openGuidePanel = openGuidePanel;
 exports.openPageGuide = openPageGuide;
 exports.openPagesPanel = openPagesPanel;
+exports.openSectionGuide = openSectionGuide;
 exports.reportApiCall = reportApiCall;
 exports.reportApiEvent = reportApiEvent;
+exports.setSectionGuideValues = setSectionGuideValues;
 exports.storeGuides = storeGuides;
+exports.thaiMonth = thaiMonth;
+exports.thaiMonthYear = thaiMonthYear;
 exports.useGuideEntry = useGuideEntry;
 exports.usePageGuideEntry = usePageGuideEntry;
 exports.usePageGuides = usePageGuides;
-//# sourceMappingURL=guide-runtime-YS2nUhwS.cjs.map
+exports.useSectionGuideValues = useSectionGuideValues;
+//# sourceMappingURL=format-CVazK0hP.cjs.map