@eintrek/erp-shell 0.1.74 → 0.1.76

package/dist/guide/core.d.ts

@@ -10,9 +10,11 @@
  * The main entry re-exports the same modules, so a tour defined against
  * either entry is the same data, and the bus and the "?" entry are shared.
  */
-export type { GuideAbortAction, GuideAnchorKey, GuideApiFailure, GuideApiMatch, GuideAppId, GuideCaptureEvent, GuideConfig, GuideContext, GuideFacts, GuideGate, GuideMission, GuideNothingToSave, GuideOnMissing, GuidePage, GuideStep, GuideStepKind, GuideSuite, GuideText, GuideTrigger, } from "./types";
+export type { GuideAbortAction, GuideAnchorKey, GuideApiFailure, GuideApiMatch, GuideAppId, GuideCaptureEvent, GuideConfig, GuideContext, GuideFacts, GuideFlow, GuideGate, GuideMission, GuideNothingToSave, GuideOnMissing, GuidePage, GuideSection, GuideStep, GuideStepKind, GuideSuite, GuideText, GuideTrigger, } from "./types";
 export { API_EVENT as GUIDE_API_EVENT, GUIDE_EVENT_PREFIX, GUIDE_LAYER_ATTRIBUTE, apiCallDetail, emitGuideEvent, guideAnchor, reportApiCall, reportApiEvent, type ApiCallReport, type ApiEventDetail, type GuideAnchorProps, } from "./events";
-export { guideMenuItems, guideMenuShown, openGuidePanel, openPageGuide, openPagesPanel, useGuideEntry, usePageGuideEntry, usePageGuides, type GuideEntry, type GuideMenuItem, type PageGuidesEntry, } from "./guide-store";
+export { guideMenuItems, guideMenuShown, openGuidePanel, openPageGuide, openPagesPanel, openSectionGuide, openFlow, openFlowsPanel, setSectionGuideValues, useGuideEntry, usePageGuideEntry, usePageGuides, useSectionGuideValues, type GuideEntry, type GuideMenuItem, type PageGuidesEntry, } from "./guide-store";
+export { SectionGuideButton, type SectionGuideButtonProps } from "./section-button";
+export { THAI_MONTHS_SHORT, formatBaht, thaiMonth, thaiMonthYear } from "./format";
 export { GuideRuntime, type GuideMenu, type GuideRouting, type GuideRuntimeProps, } from "./guide-runtime";
 export { GuideProgressConflict, loadGuides, storeGuides, type GuideProgressAdapter, type GuideProgressRequest, type GuideProgressResponse, } from "./progress-sync";
 export type { GuideAudience, GuideMode, PagesMode } from "./progress";

package/dist/guide/format.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+export declare const THAI_MONTHS_SHORT: readonly ["ม.ค.", "ก.พ.", "มี.ค.", "เม.ย.", "พ.ค.", "มิ.ย.", "ก.ค.", "ส.ค.", "ก.ย.", "ต.ค.", "พ.ย.", "ธ.ค."];
+/**
+ * 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).
+ */
+export declare function formatBaht(n: unknown, opts?: {
+    decimals?: number;
+}): string;
+/** "2026-01" (or a Date, or 1) → "ม.ค."; "" when it is not a month. */
+export declare function thaiMonth(m: unknown): string;
+/**
+ * "2026-01" → "ม.ค. 69" (the Buddhist year's last two digits), or with
+ * `{ year: "full" }` "ม.ค. 2569"; just the month when no year is known.
+ */
+export declare function thaiMonthYear(m: unknown, opts?: {
+    year?: "short" | "full";
+}): string;

package/dist/guide/guide-store.d.ts

@@ -21,11 +21,30 @@ export interface PageGuidesEntry {
     } | null;
     /** Page guides with an `href` this person has (the panel's list). */
     listed: number;
+    /**
+     * Section guides on screen here that this person has ("อธิบายส่วนนี้ ·
+     * <title>"), in the suite's order. Shell ≥ 0.1.75.
+     */
+    sections?: ReadonlyArray<{
+        key: string;
+        title: string;
+    }>;
+    /** Flows that start on this page ("พาทำ · <title>"). Shell ≥ 0.1.76. */
+    flows?: ReadonlyArray<{
+        key: string;
+        title: string;
+    }>;
+    /** Flows this person has (the panel's "พาทำงาน" list). Shell ≥ 0.1.76. */
+    flowsListed?: number;
 }
-/** Called by the host: this page's guide and the listed count, and how to open them. */
-export declare function publishPageGuides(next: PageGuidesEntry | null, openPage: (() => void) | null, openPages: (() => void) | null): void;
-/** The "?" menu's items, in order (pure: the menu and its tests share it). */
-export type GuideMenuItem = "page" | "missions" | "pages" | "help";
+/** Called by the host: this page's guide, the listed count, the sections on screen, and how to open them. */
+export declare function publishPageGuides(next: PageGuidesEntry | null, openPage: (() => void) | null, openPages: (() => void) | null, openSection?: ((key: string) => void) | null, openFlow?: ((key: string) => void) | null, openFlows?: (() => void) | null): void;
+/**
+ * The "?" menu's items, in order (pure: the menu and its tests share it).
+ * "sections": one entry per section guide; "flowsHere": one "พาทำ · <title>"
+ * per flow starting here; "flows": "พาทำงาน" (the panel's flows).
+ */
+export type GuideMenuItem = "page" | "sections" | "flowsHere" | "missions" | "pages" | "flows" | "help";
 export declare function guideMenuItems(e: GuideEntry | null, p?: PageGuidesEntry): GuideMenuItem[];
 /**
  * Whether the "?" press opens a menu rather than the help dialog: a tour
@@ -55,3 +74,32 @@ export declare function usePageGuideEntry(): {
     title: string;
     open: () => void;
 } | null;
+/**
+ * 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`).
+ */
+export declare function openSectionGuide(key: string): void;
+/** Starts a flow that starts on this page ("พาทำ · <title>"). */
+export declare function openFlow(key: string): void;
+/** Opens the panel on the flows alone ("พาทำงาน"). */
+export declare function openFlowsPanel(): void;
+type Values = Readonly<Record<string, unknown>>;
+/**
+ * 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.
+ */
+export declare function setSectionGuideValues(key: string, values: Values | undefined): void;
+/** A section guide's live values now (empty when the app has given none). */
+export declare function getSectionGuideValues(key: string | null | undefined): Values;
+/** Re-renders when any section guide's values change (the engine's own use). */
+export declare function useSectionValuesVersion(): number;
+/**
+ * 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.
+ */
+export declare function useSectionGuideValues(key: string, values: Values | undefined): void;
+export {};

package/dist/guide/guide-ui.d.ts

@@ -191,7 +191,8 @@ export declare function PageOfferCard(p: {
     title: string;
     steps: number;
     onStart: () => void;
-    onLater: () => void;
+    onLater: () => void; /** "คู่มือหน้านี้" by default; a flow's: "พาทำงาน". */
+    eyebrow?: string;
 }): import("react/jsx-runtime").JSX.Element;
 /** One page guide in the panel's "คู่มือแต่ละหน้า" list. */
 export interface PageItem {
@@ -200,6 +201,14 @@ export interface PageItem {
     /** This person has ended this version (ดูแล้ว); otherwise ใหม่. */
     seen: boolean;
 }
+/** One flow in the panel's "พาทำงาน" list. Shell ≥ 0.1.76. */
+export interface FlowItem {
+    key: string;
+    title: string;
+    minutes?: number;
+    /** This person has finished this version (ทำแล้ว). */
+    done: boolean;
+}
 export declare function QuestChip({ done, total, pulse, onOpen }: {
     done: number;
     total: number;
@@ -236,9 +245,14 @@ export declare function QuestPanel(p: {
      * (shell ≥ 0.1.74). Omitted or empty: no section.
      */
     pages?: PageItem[];
-    /** false: the page guides alone (no missions for this person, or "คู่มือทุกหน้า"). */
+    /** false: no missions (none for this person, "คู่มือทุกหน้า" or "พาทำงาน"). */
     showMissions?: boolean;
     onOpenPage?: (key: string) => void;
+    /** The "พาทำงาน" section: the flows this person has (shell ≥ 0.1.76). */
+    flows?: FlowItem[];
+    onOpenFlow?: (key: string) => void;
+    /** Without missions: one list alone ("คู่มือทุกหน้า" → pages, "พาทำงาน" → flows). */
+    only?: "pages" | "flows";
 }): import("react/jsx-runtime").JSX.Element;
 export declare function GuideToast({ text }: {
     text: string;

package/dist/guide/machine.d.ts

@@ -58,11 +58,16 @@ export type GuideScreen = {
     replayNext: boolean;
     /** A page guide's step: the page key (the mission is `page:<key>`). Shell ≥ 0.1.74. */
     page?: string;
+    /** A section guide's step: the section key (the mission is `section:<key>`). Shell ≥ 0.1.75. */
+    section?: string;
+    /** A flow's step: the flow key (the mission is `flow:<key>`). Shell ≥ 0.1.76. */
+    flow?: string;
 }
 /** The first-visit offer of this page's guide: a small card, not modal. */
  | {
     name: "pageOffer";
-    page: string;
+    page: string; /** The offer is a flow's (`page` is the flow key). Shell ≥ 0.1.76. */
+    flow?: boolean;
 } | {
     name: "celebrate";
     mission: string;
@@ -98,24 +103,43 @@ export interface GuideState {
     pagesMode: PagesMode;
     /** Page rows by page key, as the server holds them (or as just written). */
     pages: Record<string, PageRow>;
+    /** Section rows by section key (`<app>.section.<key>`). Shell ≥ 0.1.75. */
+    sections: Record<string, PageRow>;
+    /** Flow rows by flow key (`<app>.flow.<key>`). Shell ≥ 0.1.76. */
+    flows: Record<string, PageRow>;
     /**
-     * The page guide being played: `write` when its row is still to be
-     * written (the offer was taken, or this person has never ended this
-     * version); a replay from "?" of a recorded page writes nothing.
+     * The page or section guide being played: `write` when its row is still
+     * to be written (the offer was taken, or this person has never ended this
+     * version); a replay of a recorded one writes nothing.
      */
     pageRun: {
         key: string;
         write: boolean;
+        kind?: ReadKind;
+        /** A flow's: the tour's captured ids before it started, put back at its end. */
+        context?: Record<string, string>;
+    } | null;
+    /** What the panel shows: everything, the page guides alone ("คู่มือทุกหน้า"), or the flows alone ("พาทำงาน"). */
+    panelSection: "all" | "pages" | "flows";
+    /**
+     * Steps of the mission being played that passed by themselves (a click
+     * whose outcome already held): not counted in "ขั้นที่ x/y". Shell ≥ 0.1.75.
+     */
+    autoPassed: {
+        mission: string;
+        steps: number[];
     } | null;
-    /** What the panel shows: everything, or the page guides alone ("คู่มือทุกหน้า"). */
-    panelSection: "all" | "pages";
 }
 /** The page-guide part of the state, from the progress answer. */
 export interface GuidePagesInit {
     pageAudience: GuideAudience;
     pagesMode: PagesMode;
     pages: Record<string, PageRow>;
+    sections?: Record<string, PageRow>;
+    flows?: Record<string, PageRow>;
 }
+/** A guide with its own row: a page guide, a section guide or a flow. */
+export type ReadKind = "page" | "section" | "flow";
 export interface ReplayPage {
     mission: string;
     /** The mission's abort anchors that were on the page at the start. */
@@ -138,6 +162,8 @@ export interface GuideEnv {
     targetValue: () => string;
     /** An app dialog (not the tour's) is open. */
     dialogOpen?: () => boolean;
+    /** The running (or opening) section guide's live values (GuideContext.values). */
+    values?: Readonly<Record<string, unknown>>;
 }
 export type GuideSignal = {
     kind: "api";
@@ -221,7 +247,7 @@ export type GuideAction = {
     type: "dismissComplete";
 } | {
     type: "openPanel";
-    section?: "all" | "pages";
+    section?: "all" | "pages" | "flows";
 } | {
     type: "closePanel";
 } | {
@@ -242,10 +268,11 @@ export type GuideAction = {
  | {
     type: "idleCelebrate";
 }
-/** The host found this page's guide due (pageOfferDue): show the offer card. */
+/** The host found this page's guide (or, with `flow`, a flow) due: show the offer card. */
  | {
     type: "pageOffer";
     page: string;
+    flow?: boolean;
 }
 /** The offer's [เริ่ม]. */
  | {
@@ -269,6 +296,25 @@ export type GuideAction = {
     type: "pageRow";
     key: string;
     row: PageRow;
+    kind?: ReadKind;
+}
+/** "อธิบายส่วนนี้": a section guide on screen here (its button, or "?"). */
+ | {
+    type: "startSection";
+    section: string;
+}
+/** "พาทำ · <title>", or the panel's "พาทำงาน" (once on its start page). */
+ | {
+    type: "startFlow";
+    flow: string;
+}
+/** After a refresh, in the same session: back into a flow at its checkpoint. */
+ | {
+    type: "resumeFlow";
+    flow: string;
+    step: string;
+    context: Record<string, string>;
+    write: boolean;
 };
 export type GuideEffect = {
     type: "save";
@@ -291,12 +337,13 @@ export type GuideEffect = {
     type: "abort";
     actions: GuideAbortAction[];
 }
-/** Write a page guide's row, once: `<app>.page.<key>`. */
+/** Write a page (or section) guide's row, once: `<app>.page.<key>` / `<app>.section.<key>`. */
  | {
     type: "savePage";
     key: string;
     version: number;
     status: "completed" | "skipped";
+    kind?: ReadKind;
 };
 export interface GuideResult {
     state: GuideState;
@@ -312,6 +359,8 @@ export declare const COPY: {
     readonly hiddenToast: "ซ่อนแล้ว";
     readonly aborted: "ไกด์ไปต่อไม่ได้ ลองอีกครั้งภายหลัง";
     readonly pageDone: "จบคู่มือหน้านี้";
+    readonly sectionDone: "จบคำอธิบายส่วนนี้";
+    readonly flowDone: "พาทำงานเสร็จแล้ว";
     readonly bridgeTitle: "กดปุ่มเมนู";
     readonly bridgeWhy: (app: string) => string;
 };
@@ -389,10 +438,14 @@ export declare function chipVisible(state: GuideState, suite: GuideSuite, ctx: G
  * whose `requires` they lack or whose `skipIf` holds is left out (the step on
  * screen always counts).
  */
-export declare function stepPosition(mission: GuideMission, index: number, env: GuideEnv, context: Readonly<Record<string, string>>): {
+export declare function stepPosition(mission: GuideMission, index: number, env: GuideEnv, context: Readonly<Record<string, string>>, autoPassed?: readonly number[]): {
     no: number;
     total: number;
 };
+/** A step entered now would pass at once: a click or select step whose route or visible outcome holds. */
+export declare function wouldAutoPass(step: GuideStep, env: GuideEnv): boolean;
+/** The steps of this mission that passed by themselves in this run. */
+export declare function autoPassedOf(state: GuideState, mission: string): readonly number[];
 /** "กด [บันทึก]" → "กด บันทึก" (for screen readers). */
 export declare function plainTitle(t: string): string;
 /** The step's status line (GuideStep.status): trimmed text, or null. */
@@ -428,6 +481,29 @@ export declare function firstStepReady(suite: GuideSuite, pageKey: string, env:
  * route, a moment of nothing loading, the primary tab, not hidden.
  */
 export declare function pageOfferDue(state: GuideState, suite: GuideSuite, env: GuideEnv): string | null;
+/** The section guide's row says this person has ended this version of it. */
+export declare function sectionRecorded(state: GuideState, section: {
+    key: string;
+    version: number;
+}): boolean;
+/** The flow's row says this person has ended this version of it. */
+export declare function flowRecorded(state: GuideState, flow: {
+    key: string;
+    version: number;
+}): boolean;
+/** The flows this person has that start on this page ("พาทำ · <title>"). */
+export declare function flowsAvailable(suite: GuideSuite, env: GuideEnv): string[];
+/**
+ * The flow to offer now, or null: only in "offer" mode, only a flow that
+ * says `offer: true`, on its start page, with no row of this version, when
+ * nothing else is up and this page's own guide is not due (it comes first:
+ * no guide here, offer: false, or already recorded), its first step's
+ * target on screen, no app dialog open. The host adds the welcome and the
+ * idle wait, as for the page guide's offer.
+ */
+export declare function flowOfferDue(state: GuideState, suite: GuideSuite, env: GuideEnv): string | null;
+/** The section guides on screen here that this person has (the "?" entries, the buttons). */
+export declare function sectionsAvailable(suite: GuideSuite, env: GuideEnv): string[];
 /** The step before this one that this person sees, or -1. */
 export declare function previousShownIndex(mission: GuideMission, index: number, env: GuideEnv, context: Readonly<Record<string, string>>): number;
 /**

package/dist/guide/pages.d.ts

@@ -6,7 +6,7 @@
  * A page guide runs through the missions' machinery as a synthetic mission
  * `page:<key>` in replay mode, so nothing it does writes tour progress.
  */
-import type { GuideContext, GuideMission, GuidePage, GuideSuite } from "./types";
+import type { GuideContext, GuideFlow, GuideMission, GuidePage, GuideSection, GuideSuite } from "./types";
 /** The synthetic mission key of a page guide: `page:<key>`. */
 export declare const PAGE_PREFIX = "page:";
 export declare function isPageMissionKey(key: string | null | undefined): boolean;
@@ -54,3 +54,54 @@ export declare function pageShown(page: GuidePage, ctx: GuideContext): boolean;
 export declare function currentPage(suite: GuideSuite, where: PageWhere, ctx: GuideContext): GuidePage | null;
 /** The page guides this person has, for the panel's list (those with an `href`). */
 export declare function listedPages(suite: GuideSuite, ctx: GuideContext): GuidePage[];
+/** The synthetic mission key of a section guide: `section:<key>`. */
+export declare const SECTION_PREFIX = "section:";
+export declare function isSectionMissionKey(key: string | null | undefined): boolean;
+export declare function sectionKeyOf(missionKey: string | null | undefined): string | undefined;
+/** Why a section guide cannot run, or null when it can. */
+export declare function sectionProblem(app: string, section: GuideSection): string | null;
+/** The suite's section guides that can run (as validPages: the rest dropped, with a warning in development). */
+export declare function validSections(suite: GuideSuite): GuideSection[];
+export declare function findSection(suite: GuideSuite, key: string | null | undefined): GuideSection | undefined;
+/** A live value is missing: undefined, null, "" or a number that is not finite. */
+export declare function valueMissing(v: unknown): boolean;
+/**
+ * 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.
+ */
+export declare function sectionMission(section: GuideSection): GuideMission;
+/** Whether the section guide applies here: one of its routes matches and its root is on screen. */
+export declare function sectionApplies(section: GuideSection, where: PageWhere): boolean;
+/** Whether this person has the section guide: `visible` (only true) and `requires`. */
+export declare function sectionShown(section: GuideSection, ctx: GuideContext): boolean;
+/** The section guides on screen here that this person has, in the suite's order. */
+export declare function sectionsHere(suite: GuideSuite, where: PageWhere, ctx: GuideContext): GuideSection[];
+/** The synthetic mission key of a flow: `flow:<key>`. */
+export declare const FLOW_PREFIX = "flow:";
+export declare function isFlowMissionKey(key: string | null | undefined): boolean;
+export declare function flowKeyOf(missionKey: string | null | undefined): string | undefined;
+/** Why a flow cannot run, or null when it can. */
+export declare function flowProblem(app: string, flow: GuideFlow): string | null;
+/** The suite's flows that can run (as validPages: the rest dropped, with a warning in development). */
+export declare function validFlows(suite: GuideSuite): GuideFlow[];
+export declare function findFlow(suite: GuideSuite, key: string | null | undefined): GuideFlow | undefined;
+/** The flow as a mission the machine plays (in replay mode): `flow:<key>`, its steps as authored. */
+export declare function flowMission(flow: GuideFlow): GuideMission;
+/**
+ * The flow's chain: its start routes, every step's `route` and route
+ * trigger, and its `transit` routes. Leaving all of them ends the flow.
+ */
+export declare function flowChain(flow: GuideFlow): string[];
+/** Whether the person is on one of the flow's pages. */
+export declare function inFlowChain(flow: GuideFlow, where: Pick<PageWhere, "code" | "pathname">): boolean;
+/** Whether the person is on the flow's start page. */
+export declare function onFlowStart(flow: GuideFlow, where: Pick<PageWhere, "code" | "pathname" | "search">): boolean;
+/** Whether this person has the flow: `visible` (only true) and `requires`. */
+export declare function flowShown(flow: GuideFlow, ctx: GuideContext): boolean;
+/** The flows this person has (the panel's "พาทำงาน" list), in the suite's order. */
+export declare function shownFlows(suite: GuideSuite, ctx: GuideContext): GuideFlow[];
+/** The flows this person has that start on this page ("พาทำ · <title>"). */
+export declare function flowsHere(suite: GuideSuite, where: PageWhere, ctx: GuideContext): GuideFlow[];
+/** Where the panel sends the person to start a flow, or null when it needs an id it does not have. */
+export declare function flowHref(flow: GuideFlow, ctx: GuideContext): string | null;

package/dist/guide/progress-sync.d.ts

@@ -67,10 +67,11 @@ export declare function loadGuides(adapter: GuideProgressAdapter, suite: GuideSu
  */
 export declare function storeGuides(adapter: GuideProgressAdapter, suite: GuideSuite, progress: GuideProgress): Promise<GuideProgress | 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.
  */
-export declare function storePageRow(adapter: GuideProgressAdapter, app: string, key: string, version: number, status: "completed" | "skipped", rev: number): Promise<PageRow | null>;
+export declare function storePageRow(adapter: GuideProgressAdapter, app: string, key: string, version: number, status: "completed" | "skipped", rev: number, kind?: "page" | "section" | "flow"): Promise<PageRow | null>;

package/dist/guide/progress.d.ts

@@ -55,6 +55,10 @@ export interface GuidesAnswer {
     pageAudience: GuideAudience;
     /** Page rows by page key (the part after `<app>.page.`). */
     pages: Record<string, PageRow>;
+    /** Section rows by section key (the part after `<app>.section.`). Shell ≥ 0.1.75. */
+    sections: Record<string, PageRow>;
+    /** Flow rows by flow key (the part after `<app>.flow.`). Shell ≥ 0.1.76. */
+    flows: Record<string, PageRow>;
     /** The suite's row; a fresh one when the user has none or an older version. */
     progress: GuideProgress;
     /** The server holds a newer version than this app's tour: do not run. */
@@ -72,10 +76,10 @@ export declare function parseGuidesAnswer(payload: unknown, suite: {
     version: number;
     app: string;
 }): GuidesAnswer | null;
-/** The row key of a page guide: `<app>.page.<key>`. */
-export declare function pageRowKey(app: string, key: string): string;
-/** Page rows among the list's rows, by page key. Off-shape rows are left out. */
-export declare function parsePageRows(rows: unknown[], app: string): Record<string, PageRow>;
+/** The row key of a page guide `<app>.page.<key>`, a section guide `<app>.section.<key>`, or a flow `<app>.flow.<key>`. */
+export declare function pageRowKey(app: string, key: string, kind?: "page" | "section" | "flow"): string;
+/** Page (or section) rows among the list's rows, by key. Off-shape rows are left out. */
+export declare function parsePageRows(rows: unknown[], app: string, kind?: "page" | "section" | "flow"): Record<string, PageRow>;
 /** One page row (a list entry, a PUT answer, a 409's `current`); null when off-shape. */
 export declare function parsePageRow(raw: unknown): PageRow | null;
 /**

package/dist/guide/section-button.d.ts

@@ -0,0 +1,12 @@
+export interface SectionGuideButtonProps {
+    /** The GuideSection's key. */
+    guideKey: string;
+    /**
+     * The numbers the guide's copy uses (`ctx.values`), from this render.
+     * Optional: the section may call `useSectionGuideValues` itself instead.
+     */
+    values?: Readonly<Record<string, unknown>>;
+    /** Replaces the default look (a 22px round icon button in the text colour). */
+    className?: string;
+}
+export declare function SectionGuideButton({ guideKey, values, className }: SectionGuideButtonProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/guide/types.d.ts

@@ -41,6 +41,12 @@ export interface GuideContext {
     can: (policyKey: string) => boolean;
     /** Whether an anchor is on screen now. */
     visible: (anchor: GuideAnchorKey) => boolean;
+    /**
+     * A section guide's live values, as the app last rendered them
+     * (`useSectionGuideValues` / `SectionGuideButton values`); empty
+     * elsewhere. Shell ≥ 0.1.75.
+     */
+    values?: Readonly<Record<string, unknown>>;
 }
 /** Text that may depend on the context. */
 export type GuideText = string | ((ctx: GuideContext) => string);
@@ -171,6 +177,12 @@ export interface GuideStep {
     status?: (ctx: GuideContext) => string | null | undefined;
     /** Skip the step (silently) when true. Runs every time it is entered. */
     skipIf?: (ctx: GuideContext) => boolean;
+    /**
+     * Section guides: the live values this step's copy uses
+     * (`ctx.values`). The step is skipped while any is missing (undefined,
+     * null, "" or a number that is not finite). Shell ≥ 0.1.75.
+     */
+    needs?: string[];
     /** A policy key the step needs (checked with `guides.can`); skipped when
      *  the user lacks it. */
     requires?: string;
@@ -378,6 +390,90 @@ export interface GuidePage {
      */
     steps: GuideStep[];
 }
+/**
+ * A section guide ("อธิบายส่วนนี้", shell ≥ 0.1.75): explains one section of
+ * a page — a number-heavy card or table — row by row, with the formula and
+ * this record's own numbers. Read-only ("view" steps only; a step may point
+ * at a row or cell inside the section with `targetId`), never offered by
+ * itself: it opens from the section's `SectionGuideButton` or from "?" →
+ * "อธิบายส่วนนี้ · <title>". Same switch and audience as page guides
+ * (`guides.<app>.pages` not off); one row per section guide per person,
+ * `<app>.section.<key>`, written once. Authors:
+ * _claude-work/guides-r4/GUIDE-PAGES.md §10.
+ */
+export interface GuideSection {
+    /** Stable, [a-z0-9-]: the row key is `${suite.app}.section.${key}` (≤ 64 characters). */
+    key: string;
+    version: number;
+    /** The page(s) the section is on, as GuidePage.route. */
+    route: string | string[];
+    /** The section's root: the guide is there only while it is on screen. */
+    anchor: GuideAnchorKey;
+    /** "สรุปกระแสเงินสด": the "?" entry and the bubble's heading. ≤ 40 characters. */
+    title: string;
+    /** Only `true` shows it (as GuideMission.visible). */
+    visible?: (ctx: GuideContext) => boolean | undefined;
+    /** A policy key the section needs (checked with `guides.can`). */
+    requires?: string;
+    /**
+     * "view" steps (the default here), about 12 at most; titles ≤ 40 and whys
+     * ≤ 90 characters (the app's tests check). Copy may be a function of
+     * `ctx.values`; list what it uses in `needs`, and a step whose value is
+     * missing is skipped (so is one whose title comes out empty).
+     */
+    steps: GuideStep[];
+}
+/**
+ * A workflow guide ("พาทำงาน", shell ≥ 0.1.76): walks one job across pages —
+ * "เปิดใบขอซื้อจากบรรทัดงบ" — and stops before anything irreversible. Not a
+ * mission: never in "ไกด์เริ่มต้น n/N" or the welcome. Same switch and
+ * audience as page guides (`guides.<app>.pages` not off; every member,
+ * filtered by `visible` / `requires`). Listed under "?" → "พาทำงาน" and,
+ * on its start page, "พาทำ · <title>". One row per flow per person,
+ * `<app>.flow.<key>`, written once at the end (completed or skipped).
+ * Authors: _claude-work/guides-r4/GUIDE-PAGES.md §11.
+ */
+export interface GuideFlow {
+    /** Stable, [a-z0-9-]: the row key is `${suite.app}.flow.${key}` (≤ 64 characters). */
+    key: string;
+    /** Raise it to offer this flow again (only when `offer: true`). */
+    version: number;
+    /** "เปิดใบขอซื้อจากบรรทัดงบ": the "?" entries, the panel, the bubble. ≤ 30 characters. */
+    title: string;
+    /** Rough minutes, for "ประมาณ n นาที" in the panel. */
+    minutes?: number;
+    /** Only `true` shows it (as GuideMission.visible). */
+    visible?: (ctx: GuideContext) => boolean | undefined;
+    /** A policy key the flow needs (checked with `guides.can`). */
+    requires?: string;
+    /** Where it starts: "พาทำ · <title>" is in "?" there, and the offer (if any) only there. */
+    startRoute: string | string[];
+    /**
+     * Where the panel's "พาทำงาน" list sends the person to start it, when
+     * `startRoute` needs an id (`[code]` is filled in). Default: the first
+     * `startRoute` when it has no other params.
+     */
+    href?: GuideText;
+    /**
+     * Pages the flow may pass through without ending (a redirect, a picker
+     * page), besides `startRoute` and its steps' routes.
+     */
+    transit?: string[];
+    /** true: offered once on its start page in `offer` mode, after the missions and the page guide's offer. Default false. */
+    offer?: boolean;
+    /**
+     * true: the flow may save something harmless and reversible ("commit",
+     * "input" and "select" steps). Every commit step must name its `abort`.
+     * Default false: "view" and "click" steps only.
+     */
+    allowCommit?: boolean;
+    /**
+     * Steps as a mission's: `route`, checkpoints and resume across pages. The
+     * last step on an irreversible button is a "view" step (the app's
+     * deny-list test checks).
+     */
+    steps: GuideStep[];
+}
 /** One app's whole tour: the welcome, the missions, the finish. */
 export interface GuideSuite {
     /** Progress key on the server, "<app>.<name>": "peoplx.first-run". */
@@ -423,6 +519,10 @@ export interface GuideSuite {
     missions: GuideMission[];
     /** Page guides ("คู่มือหน้านี้"), shell ≥ 0.1.74. */
     pages?: GuidePage[];
+    /** Section guides ("อธิบายส่วนนี้"), shell ≥ 0.1.75. */
+    sections?: GuideSection[];
+    /** Workflow guides ("พาทำงาน"), shell ≥ 0.1.76. */
+    flows?: GuideFlow[];
 }
 /** AppLayoutShell's `guides` prop. */
 export interface GuideConfig {