@eintrek/erp-shell 0.1.62 → 0.1.64

package/README.md

@@ -144,6 +144,36 @@ Phase 3a ✅ — Pure / session-only hooks + jwt-utils
 Consumer apps' `@/shared/lib/jwt-utils`, `@/shared/hooks/use-session-refresh`,
 `@/shared/hooks/use-keycloak-roles` shims now re-export from this package.
 
+## Guided tour (ไกด์เริ่มต้น), from 0.1.63
+
+A forced, game-style spotlight tour, written by each app as data and run by
+the shell. Authors' guide: `_claude-work/peoplx-guide/ENGINE-API.md`; the
+progress API: `API.md` next to it.
+
+- `AppLayoutShell guides={{ suite, facts, can, ready }}` mounts `GuideHost`
+  once the URL's organisation is active (never on the not-member refusal).
+  Who sees it (forced / optional / none) comes from platform-api
+  `GET /organizations/:id/guides/me?app=`; any failure shows nothing.
+- Steps advance on outcomes: a route, an anchor appearing or going away, an
+  API answer (the shell's axios reports `erp:api`; an app's own instance calls
+  `reportApiEvent`), an app event (`emitGuideEvent` → `erp:guide:<name>`), a
+  press, a valid value.
+- Anchors: `guideAnchor("peoplx.x.y")` → `data-guide`. The sidebar anchors
+  every row as `nav.<item id>`; the menu button is `shell.menu-toggle`, the
+  "?" button `shell.help`.
+- The "?" button becomes a menu ("ไกด์เริ่มต้น n/N", "ติดต่อทีมช่วยเหลือ")
+  for a user with a tour.
+- The layer is a portal marked `data-erp-guide-layer` with its own
+  stylesheet (`eg-` classes, theme tokens). Radix overlays must ignore it:
+  `@eintrek/erp-theme` ≥ 1.4.21 does; the engine also stops its own presses
+  and focus from reaching an open dialog.
+- New dependency: `@floating-ui/dom` (external in the bundle; Radix already
+  installs it in every app).
+- Code: `src/guide/` — `types.ts` (definitions), `machine.ts` (pure state
+  machine), `patterns.ts`, `progress.ts` / `progress-client.ts` (API),
+  `dom.ts`, `guide-host.tsx`, `guide-ui.tsx`, `guide-styles.ts`. Tests:
+  `src/guide/*.test.ts`.
+
 ## Roadmap
 
 | Phase | Scope                                                                 | Files to move from each app                                      |
@@ -170,6 +200,8 @@ Requires Node 22.13+ and pnpm 11 (same as other ERP packages).
 ```bash
 pnpm install
 pnpm build         # rollup → dist/{index.js,index.esm.js,index.d.ts}
+pnpm test          # node --test (pnpm 11 may refuse to run scripts over
+                   # ignored builds; then: node --test "src/**/*.test.ts")
 pnpm dev           # watch
 pnpm pack          # produce .tgz for local consumer testing
 ```

package/dist/guide/dom.d.ts

@@ -0,0 +1,103 @@
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare function anchorSelector(anchor: string, id?: string): string;
+/**
+ * On screen: connected, with a size, not hidden by style, not inside
+ * aria-hidden or inert (other than the guide's own), not a closed Radix part.
+ *
+ * aria-hidden that Radix put there (data-aria-hidden: everything outside an
+ * open dialog, select or menu is hidden from screen readers) does not count:
+ * a dialog's field is still on screen while its select's list is open.
+ */
+export declare function isPresent(el: Element | null | undefined): el is HTMLElement;
+/** The first matching anchor that is on screen. */
+export declare function findAnchor(anchor: string, id?: string): HTMLElement | null;
+export declare function anchorVisible(anchor: string, id?: string): boolean;
+/** The field to type into: the anchor itself, or the first field inside it. */
+export declare function fieldOf(el: Element | null): HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | HTMLElement | null;
+export declare function fieldValue(el: Element | null): string;
+export declare const FOCUSABLE = "a[href],button:not([disabled]),input:not([disabled]):not([type=hidden]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex='-1']),[contenteditable=''],[contenteditable=true]";
+export declare function focusablesIn(root: Element | null): HTMLElement[];
+export declare function rectOf(el: Element): Rect;
+export declare function padRect(r: Rect, pad: number): Rect;
+export declare function sameRect(a: Rect | null, b: Rect | null): boolean;
+/** Open Radix poppers (a select's list, a menu): usable while a step runs. */
+export declare const POPPER_SELECTOR = "[data-radix-popper-content-wrapper]";
+/** Toasts stay usable above the tour. */
+export declare const TOASTER_SELECTOR = "[data-sonner-toaster]";
+/** Open dialogs (Radix dialog, alert dialog, sheet, popover content). */
+export declare const OPEN_DIALOG_SELECTOR = "[role=\"dialog\"][data-state=\"open\"],[role=\"alertdialog\"][data-state=\"open\"]";
+/**
+ * Whether an open dialog of the app's covers the target: the target is
+ * neither in it nor around it (a confirm opened by the step's own button).
+ * The ring and the hand would be drawn over the dialog, pointing at a button
+ * behind it.
+ */
+export declare function coveredByDialog(el: Element | null): boolean;
+export declare function openPoppers(): HTMLElement[];
+export declare function inGuideLayer(node: EventTarget | null): boolean;
+export declare function prefersReducedMotion(): boolean;
+export declare function isPhoneWidth(): boolean;
+/** The overlap of two rectangles, or null when they do not meet. */
+export declare function intersectRect(a: Rect, b: Rect): Rect | null;
+/** The part of `rect` inside every clip (scroll boxes, the viewport); null when none is. */
+export declare function visibleRect(rect: Rect, clips: Rect[]): Rect | null;
+/**
+ * The ancestors that cut the element off: anything with overflow other than
+ * visible on an axis. The body and the root scroll the page and are covered by
+ * the viewport. Read once per target; their rectangles are read every frame.
+ */
+export declare function clipAncestors(el: Element): Array<{
+    el: Element;
+    x: boolean;
+    y: boolean;
+}>;
+/** An ancestor's clip as a rectangle: unbounded on an axis it does not clip. */
+export declare function clipRectOf(c: {
+    el: Element;
+    x: boolean;
+    y: boolean;
+}): Rect;
+export declare function viewportRect(): Rect;
+/**
+ * The part of the element a person can see: its box cut by every scroll box
+ * around it and by the viewport. The spotlight, its hole, the ring and the
+ * hand use this, so a tab half out of a sideways-scrolling row of tabs is not
+ * spotlit where it cannot be pressed. Null when none of it is on screen.
+ */
+export declare function visibleRectOf(el: Element, ancestors?: {
+    el: Element;
+    x: boolean;
+    y: boolean;
+}[]): Rect | null;
+/** Inside a box that scrolls sideways (with somewhere to scroll) that is itself on screen. */
+export declare function inSidewaysScroller(el: Element): boolean;
+/**
+ * How to bring a target into view, or null when it already is: to the middle
+ * when it is above or below the comfortable band (under the header, at the
+ * bottom edge), the nearest edge when only a side is cut off (a tab out of a
+ * sideways-scrolling row, on a phone).
+ */
+export declare function revealPlan(rect: Rect, visible: Rect | null, viewportHeight: number): {
+    block: "center" | "nearest";
+    inline: "nearest";
+} | null;
+/** Scrolls the target into view (instant under reduced motion). */
+export declare function revealTarget(el: Element): void;
+/**
+ * The scrim's blocking area: the screen (with a 10 px margin) minus the union
+ * of the holes, as rectangles that do not overlap. Cutting each hole out with
+ * an even-odd fill made the place where two holes overlap (a field and the
+ * select list open over it) solid again, and the option there could not be
+ * pressed.
+ *
+ * Every hole edge splits the screen into a grid; a cell is blocked when no
+ * hole covers it. Cells in a row are joined, and identical rows stacked.
+ */
+export declare function blockedRects(holes: Rect[], width: number, height: number): Rect[];
+/** Whether a point is in any of the rectangles (edges excluded). */
+export declare function inRects(rects: Rect[], x: number, y: number): boolean;

package/dist/guide/events.d.ts

@@ -0,0 +1,24 @@
+export declare const GUIDE_ATTRIBUTE = "data-guide";
+export declare const GUIDE_ID_ATTRIBUTE = "data-guide-id";
+export declare const GUIDE_LAYER_ATTRIBUTE = "data-erp-guide-layer";
+export declare const API_EVENT = "erp:api";
+export declare const GUIDE_EVENT_PREFIX = "erp:guide:";
+export interface GuideAnchorProps {
+    "data-guide": string;
+    "data-guide-id"?: string;
+}
+/** Spread onto the element a tour step points at. */
+export declare function guideAnchor(key: string, id?: string | number | null): GuideAnchorProps;
+export interface ApiEventDetail {
+    method: string;
+    path: string;
+    status: number;
+    id?: string;
+    message?: string;
+}
+/** Announces an app event a step can wait for (`advanceOn: { event: name }`). */
+export declare function emitGuideEvent(name: string, detail?: Record<string, string | number>): void;
+/** The bus detail for an axios answer or error; null when it is neither. */
+export declare function apiEventDetail(responseOrError: unknown): ApiEventDetail | null;
+/** Puts an axios answer (or error) on the bus. Safe to call with anything. */
+export declare function reportApiEvent(responseOrError: unknown): void;

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

@@ -0,0 +1,7 @@
+import type { GuideConfig } from "./types";
+export interface GuideHostProps {
+    config: GuideConfig;
+    organizationId: string;
+    code: string;
+}
+export declare function GuideHost(props: GuideHostProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,16 @@
+/**
+ * What the rest of the shell needs to know about the tour, outside the
+ * host's tree: whether this user has one here (the "?" menu's
+ * "ไกด์เริ่มต้น n/N" entry) and a way to open its panel. A tiny external
+ * store, like the help dialog's.
+ */
+export interface GuideEntry {
+    done: number;
+    total: number;
+}
+/** Called by the host: the entry to show (null: none), and how to open the panel. */
+export declare function publishGuideEntry(next: GuideEntry | null, openPanel: (() => void) | null): void;
+/** Opens the tour's quest panel, when this user has a tour here. */
+export declare function openGuidePanel(): void;
+/** The "?" menu's entry, or null when there is no tour for this user. */
+export declare function useGuideEntry(): GuideEntry | null;

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

@@ -0,0 +1,7 @@
+/**
+ * The tour's stylesheet. The shell has no CSS pipeline and the apps only scan
+ * its dist for Tailwind classes, which cannot carry keyframes; so the layer
+ * brings its own sheet, namespaced `eg-`, drawn from the theme's tokens
+ * (--primary carries each app's brand accent; light and dark follow).
+ */
+export declare const GUIDE_CSS = "\n[data-erp-guide-layer]{position:fixed;inset:0;z-index:1000;pointer-events:none;font-family:inherit;color:var(--popover-foreground,#1c2634);\n  --eg-scrim:rgba(12,20,34,.64);--eg-card:var(--popover,#fff);--eg-fg:var(--popover-foreground,#1c2634);\n  --eg-muted:var(--muted-foreground,#6d7886);--eg-soft:var(--muted,#eef3f9);--eg-line:var(--border,#e8ecf1);\n  --eg-primary:var(--primary,#3280dd);--eg-on-primary:var(--primary-foreground,#fff);\n  --eg-tint:color-mix(in oklab,var(--eg-primary) 13%,var(--eg-card));--eg-strong:color-mix(in oklab,var(--eg-primary) 82%,#000);\n  --eg-danger:var(--destructive,#d23b4b);--eg-ok:#1d9a5f;--eg-gold:#e6a417;\n  --eg-shadow:0 18px 50px -12px rgba(16,32,64,.35),0 4px 12px rgba(16,32,64,.08);line-height:1.5;font-size:14px}\n[data-erp-guide-layer] *{box-sizing:border-box}\n[data-erp-guide-layer] button{font:inherit;color:inherit;cursor:pointer}\n.eg-i{pointer-events:auto}\n.eg-sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}\n.eg-scrim-svg{position:fixed;inset:0;width:100%;height:100%;pointer-events:none;overflow:visible}\n.eg-scrim-svg .eg-scrim-fill{fill:var(--eg-scrim);pointer-events:none}\n.eg-scrim-svg .eg-scrim-hit{fill:transparent;pointer-events:all}\n.eg-scrim{position:fixed;inset:0;background:var(--eg-scrim);pointer-events:auto}\n.eg-scrim.eg-light{background:rgba(12,20,34,.45)}\n.eg-scrim.eg-faint{background:rgba(12,20,34,.35)}\n.eg-ring{position:fixed;border-radius:12px;pointer-events:none;box-shadow:0 0 0 3px #fff,0 0 0 6px var(--eg-primary)}\n.eg-ring.eg-move{transition:left .26s ease,top .26s ease,width .26s ease,height .26s ease}\n.eg-ring::after{content:\"\";position:absolute;inset:-6px;border-radius:15px;border:3px solid var(--eg-primary);animation:eg-pulse 1.6s ease-out infinite}\n.eg-ring.eg-flash::after{animation:eg-flash .5s ease 1}\n@keyframes eg-pulse{0%{opacity:.9;transform:scale(1)}100%{opacity:0;transform:scale(1.12)}}\n@keyframes eg-flash{0%,100%{opacity:1;transform:none}50%{opacity:.2}}\n.eg-hand{position:fixed;width:46px;height:46px;pointer-events:none;filter:drop-shadow(0 4px 6px rgba(0,0,0,.35));animation:eg-tap 1.1s ease-in-out infinite}\n.eg-hand svg{width:46px;height:46px;fill:#fff;stroke:#1c2634;stroke-width:1.4;stroke-linejoin:round;stroke-linecap:round}\n.eg-hand.eg-flip svg{transform:scaleY(-1)}\n@keyframes eg-tap{0%,100%{transform:translate(6px,8px)}50%{transform:translate(0,0)}}\n.eg-bubble{position:fixed;left:0;top:0;width:320px;background:var(--eg-card);color:var(--eg-fg);border-radius:14px;box-shadow:var(--eg-shadow);padding:14px 16px 12px;border-top:4px solid var(--eg-primary);outline:none;pointer-events:auto}\n.eg-bubble.eg-err{border-top-color:var(--eg-danger)}\n.eg-bubble.eg-nudge{animation:eg-nudge .38s ease}\n@keyframes eg-nudge{0%,100%{translate:0}20%{translate:-7px}40%{translate:6px}60%{translate:-4px}80%{translate:2px}}\n.eg-b-top{display:flex;justify-content:space-between;align-items:center;gap:8px;font-size:12px;color:var(--eg-muted)}\n.eg-b-top .eg-mis{font-weight:600;color:var(--eg-strong);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}\n.eg-b-top .eg-cnt{white-space:nowrap;font-weight:600}\n.eg-pips{display:flex;gap:4px;margin:8px 0 10px}\n.eg-pips i{flex:1;height:4px;border-radius:2px;background:var(--eg-soft)}\n.eg-pips i.eg-d{background:var(--eg-primary)}\n.eg-pips i.eg-c{background:color-mix(in oklab,var(--eg-primary) 45%,var(--eg-card))}\n.eg-b-t{margin:0;font-size:16px;font-weight:600;line-height:1.45}\n.eg-b-w{margin:2px 0 0;font-size:13.5px;color:var(--eg-muted)}\n.eg-bubble.eg-err .eg-b-t{color:var(--eg-danger)}\n.eg-k{display:inline-block;background:var(--eg-tint);color:var(--eg-strong);border-radius:7px;padding:0 7px;font-weight:600}\n.eg-b-f{display:flex;align-items:center;justify-content:space-between;margin-top:12px;gap:8px}\n.eg-b-f .eg-btn{height:34px;padding:0 14px;font-size:13.5px}\n.eg-exit{border:0;background:none;color:var(--eg-muted);font-size:12.5px;padding:4px 0;text-decoration:underline;text-underline-offset:3px}\n.eg-exit:hover{color:var(--eg-fg)}\n.eg-arrow{position:absolute;width:14px;height:14px;background:var(--eg-card);transform:rotate(45deg);border-radius:2px}\n.eg-arrow.eg-top{background:var(--eg-primary)}\n.eg-bubble.eg-err .eg-arrow.eg-top{background:var(--eg-danger)}\n.eg-btn{display:inline-flex;align-items:center;justify-content:center;gap:8px;height:40px;padding:0 16px;border-radius:10px;border:1px solid transparent;font-size:14px;font-weight:600;white-space:nowrap}\n.eg-btn:focus-visible,.eg-exit:focus-visible,.eg-chip:focus-visible,.eg-x:focus-visible{outline:2px solid var(--eg-primary);outline-offset:2px}\n.eg-primary{background:var(--eg-primary);color:var(--eg-on-primary)!important}\n.eg-primary:hover{background:var(--eg-strong)}\n.eg-primary[disabled]{opacity:.55;cursor:default}\n.eg-ghost{background:var(--eg-card);border-color:var(--eg-line)}\n.eg-ghost:hover{background:var(--eg-soft)}\n.eg-ghost[disabled]{opacity:.55;cursor:default}\n.eg-link{background:none;border:0;color:var(--eg-muted);font-weight:500;padding:0 6px;height:32px}\n.eg-link:hover{color:var(--eg-fg);text-decoration:underline}\n.eg-modal{position:fixed;left:50%;top:50%;transform:translate(-50%,-50%);width:min(440px,calc(100vw - 32px));max-height:calc(100vh - 32px);overflow:auto;background:var(--eg-card);color:var(--eg-fg);border-radius:20px;box-shadow:var(--eg-shadow);padding:28px 28px 22px;text-align:center;outline:none;pointer-events:auto}\n.eg-modal.eg-pop{animation:eg-pop .32s cubic-bezier(.2,.9,.3,1.3)}\n@keyframes eg-pop{from{opacity:0;transform:translate(-50%,-46%) scale(.94)}}\n.eg-modal h2{margin:6px 0 4px;font-size:22px;font-weight:700;letter-spacing:-.2px;line-height:1.3}\n.eg-modal .eg-sub{margin:0;color:var(--eg-muted);font-size:14.5px}\n.eg-eyebrow{margin:0;font-size:12.5px;font-weight:600;letter-spacing:.3px;color:var(--eg-strong)}\n.eg-actions{display:grid;gap:6px;margin-top:20px}\n.eg-actions .eg-btn{height:44px}\n.eg-badge{width:64px;height:64px;border-radius:18px;margin:0 auto 12px;display:grid;place-items:center;background:var(--eg-tint);color:var(--eg-strong)}\n.eg-badge svg.eg-ic{width:30px;height:30px}\n.eg-quests{list-style:none;padding:0;margin:18px 0 0;text-align:left;display:grid;gap:6px}\n.eg-quests li{display:flex;align-items:center;gap:12px;padding:9px 12px;border-radius:11px;background:var(--eg-soft);font-size:14px}\n.eg-quests li .eg-n{width:26px;height:26px;border-radius:50%;background:var(--eg-card);border:1.5px solid var(--eg-line);display:grid;place-items:center;font-size:12px;font-weight:700;color:var(--eg-muted);flex:none}\n.eg-quests li.eg-first{background:var(--eg-tint)}\n.eg-quests li.eg-first .eg-n{border-color:var(--eg-primary);color:var(--eg-strong)}\n.eg-quests li.eg-ok .eg-n{background:var(--eg-ok);border-color:var(--eg-ok);color:#fff}\n.eg-quests li .eg-n svg.eg-ic{width:15px;height:15px;stroke-width:3}\n.eg-quests li .eg-t{flex:1}\n.eg-quests li small{color:var(--eg-muted);font-size:12px;white-space:nowrap}\n.eg-modal.eg-confirm{text-align:left;width:min(380px,calc(100vw - 32px));padding:22px}\n.eg-modal.eg-confirm h2{font-size:18px;margin-top:0}\n.eg-modal.eg-confirm .eg-actions{grid-template-columns:1fr 1fr}\n.eg-medal{width:84px;height:84px;border-radius:50%;margin:4px auto 10px;display:grid;place-items:center;color:#fff;background:radial-gradient(circle at 35% 30%,#ffd666,var(--eg-gold));box-shadow:0 0 0 8px #fff4d6;animation:eg-stamp .5s cubic-bezier(.2,.9,.3,1.4) .1s both}\n.eg-medal svg.eg-ic{width:42px;height:42px;stroke-width:2.6}\n@keyframes eg-stamp{from{transform:scale(.3) rotate(-25deg);opacity:0}}\n.eg-prog{display:flex;align-items:center;gap:10px;margin-top:16px;font-size:13px;color:var(--eg-muted);font-weight:600}\n.eg-prog .eg-bar{flex:1;height:8px;border-radius:4px;background:var(--eg-soft);overflow:hidden}\n.eg-prog .eg-bar i{display:block;height:100%;background:var(--eg-primary);border-radius:4px;transition:width .9s cubic-bezier(.2,.8,.2,1) .35s}\n.eg-burst{position:absolute;left:50%;top:70px;width:0;height:0;pointer-events:none}\n.eg-burst span{position:absolute;width:8px;height:12px;border-radius:2px;opacity:0;animation:eg-conf 1.1s cubic-bezier(.15,.7,.3,1) forwards}\n@keyframes eg-conf{0%{opacity:1;transform:translate(0,0) rotate(0)}100%{opacity:0;transform:translate(var(--x),var(--y)) rotate(var(--r))}}\n.eg-card{position:fixed;left:50%;bottom:28px;transform:translateX(-50%);width:min(360px,calc(100vw - 32px));background:var(--eg-card);color:var(--eg-fg);border-radius:14px;box-shadow:var(--eg-shadow);padding:14px 16px;border-top:4px solid var(--eg-primary);pointer-events:auto;outline:none}\n.eg-card .eg-row{display:flex;align-items:center;justify-content:space-between;gap:10px;margin-top:12px}\n.eg-loading{display:flex;align-items:center;gap:10px;font-weight:600}\n.eg-spin{width:18px;height:18px;border-radius:50%;border:2.5px solid var(--eg-soft);border-top-color:var(--eg-primary);animation:eg-spin .8s linear infinite;flex:none}\n@keyframes eg-spin{to{transform:rotate(360deg)}}\n.eg-chip{position:fixed;right:22px;bottom:22px;display:flex;align-items:center;gap:10px;height:48px;padding:0 18px 0 8px;border-radius:24px;border:1px solid var(--eg-line);background:var(--eg-card);color:var(--eg-fg);box-shadow:0 8px 24px -8px rgba(16,32,64,.3);font-weight:600;font-size:14px;pointer-events:auto}\n.eg-chip svg{width:34px;height:34px}\n.eg-chip.eg-hi{animation:eg-hi 1.2s ease 2}\n@keyframes eg-hi{50%{box-shadow:0 0 0 6px color-mix(in oklab,var(--eg-primary) 35%,transparent),0 8px 24px -8px rgba(16,32,64,.3)}}\n.eg-panel{position:fixed;right:22px;bottom:82px;width:360px;max-height:calc(100vh - 110px);overflow:auto;background:var(--eg-card);color:var(--eg-fg);border:1px solid var(--eg-line);border-radius:16px;box-shadow:var(--eg-shadow);outline:none;pointer-events:auto}\n.eg-panel-bd{display:none}\n.eg-q-h{display:flex;align-items:center;gap:10px;padding:16px 12px 4px 18px}\n.eg-q-h h2{margin:0;font-size:16px;font-weight:700;flex:1}\n.eg-q-h .eg-n{font-size:13px;color:var(--eg-muted);font-weight:600}\n.eg-x{width:34px;height:34px;border-radius:10px;border:0;background:none;display:grid;place-items:center;color:var(--eg-muted)}\n.eg-x:hover{background:var(--eg-soft)}\n.eg-x svg.eg-ic{width:18px;height:18px}\n.eg-panel .eg-prog{margin:6px 18px 8px}\n.eg-q-list{list-style:none;margin:0;padding:4px 10px 6px;display:grid;gap:2px}\n.eg-q-item{display:flex;align-items:center;gap:12px;padding:10px 8px;border-radius:11px}\n.eg-q-item.eg-next{background:var(--eg-tint)}\n.eg-q-item .eg-n{width:30px;height:30px;border-radius:50%;border:1.5px solid var(--eg-line);display:grid;place-items:center;font-size:12.5px;font-weight:700;color:var(--eg-muted);flex:none;background:var(--eg-card)}\n.eg-q-item.eg-next .eg-n{border-color:var(--eg-primary);color:var(--eg-strong)}\n.eg-q-item.eg-done .eg-n{background:var(--eg-ok);border-color:var(--eg-ok);color:#fff}\n.eg-q-item.eg-done .eg-n svg.eg-ic{width:16px;height:16px;stroke-width:3}\n.eg-q-item.eg-dim .eg-n{opacity:.55}\n.eg-q-item.eg-just .eg-n{animation:eg-stamp .55s cubic-bezier(.2,.9,.3,1.4) .2s both}\n.eg-q-item .eg-t{flex:1;min-width:0}\n.eg-q-item .eg-t b{display:block;font-size:14px;font-weight:600}\n.eg-q-item.eg-done .eg-t b{color:var(--eg-muted)}\n.eg-q-item .eg-t small{display:block;font-size:12px;color:var(--eg-muted)}\n.eg-q-item .eg-t small.eg-sk{color:#b06a00}\n.eg-q-item .eg-t small.eg-lock{color:var(--eg-fg);font-weight:500}\n.eg-q-item .eg-btn{height:32px;padding:0 12px;font-size:13px}\n.eg-q-acts{display:flex;flex-direction:column;align-items:flex-end;gap:2px}\n.eg-q-acts .eg-link{height:22px;font-size:12px;padding:0 2px}\n.eg-q-f{border-top:1px solid var(--eg-line);padding:8px 12px;display:flex;justify-content:flex-end}\n.eg-toast{position:fixed;left:50%;bottom:84px;transform:translateX(-50%);background:#1c2634;color:#fff;padding:10px 16px;border-radius:10px;font-size:13.5px;box-shadow:var(--eg-shadow);max-width:calc(100vw - 32px);pointer-events:none}\nsvg.eg-ic{width:18px;height:18px;fill:none;stroke:currentColor;stroke-width:1.8;stroke-linecap:round;stroke-linejoin:round;flex:none}\n@media (max-width:767px){\n  .eg-bubble{width:auto}\n  .eg-arrow{display:none}\n  .eg-modal{top:auto;bottom:12px;transform:translateX(-50%);width:calc(100vw - 24px);padding:24px 20px 18px}\n  .eg-modal.eg-pop{animation:eg-up .3s cubic-bezier(.2,.9,.3,1.1)}\n  .eg-modal .eg-actions .eg-btn{height:46px}\n  .eg-chip{right:16px;bottom:calc(16px + env(safe-area-inset-bottom))}\n  .eg-panel-bd{display:block;position:fixed;inset:0;background:rgba(15,23,42,.38);pointer-events:auto}\n  .eg-panel{left:0;right:0;bottom:0;width:100%;max-height:85vh;border-radius:18px 18px 0 0;padding-bottom:env(safe-area-inset-bottom)}\n  .eg-q-item{padding:12px 8px}\n  .eg-card{bottom:calc(12px + env(safe-area-inset-bottom))}\n  .eg-toast{bottom:calc(76px + env(safe-area-inset-bottom))}\n}\n@keyframes eg-up{from{opacity:0;transform:translate(-50%,30px)}}\n@media (prefers-reduced-motion:reduce){\n  [data-erp-guide-layer] *,[data-erp-guide-layer] *::before,[data-erp-guide-layer] *::after{animation-duration:.001ms!important;animation-iteration-count:1!important;transition-duration:.001ms!important}\n  .eg-ring::after{animation:none!important;opacity:1;transform:none}\n  .eg-ring.eg-flash::after{animation:eg-flash .5s ease 1!important;animation-duration:.5s!important}\n  .eg-hand{animation:none!important;transform:translate(4px,6px)}\n  .eg-burst{display:none}\n  .eg-bubble.eg-nudge{animation:none!important;border-top-color:var(--eg-danger)}\n}\n";

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

@@ -0,0 +1,191 @@
+import { type Placement } from "@floating-ui/dom";
+import { type Rect } from "./dom";
+import type { MissionView, StepError } from "./machine";
+/** "26 ต.ค. 2569 13:04" — day, month, Buddhist year, 24 h. */
+export declare function formatThaiDateTime(iso: string | null | undefined): string;
+/** "กด [บันทึก]": the bracketed word is a chip in the brand colour. */
+export declare function GuideTitle({ text }: {
+    text: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare const IconCheck: () => import("react/jsx-runtime").JSX.Element;
+export declare const IconX: () => import("react/jsx-runtime").JSX.Element;
+export declare const IconFlag: () => import("react/jsx-runtime").JSX.Element;
+export declare const IconTrophy: () => import("react/jsx-runtime").JSX.Element;
+/**
+ * The dim layer that eats every press outside the holes. The holes are a
+ * union: where two overlap (a field and the select list open over it) the
+ * page stays open.
+ *
+ * - The look: one rectangle masked by the rounded holes (a mask adds holes
+ *   up, so an overlap is not filled back in).
+ * - The presses: a transparent path made of the screen minus the holes, as
+ *   rectangles that do not overlap (blockedRects). A press inside a hole
+ *   reaches the page underneath; any other lands on the path (marked
+ *   data-eg-block) and is cancelled.
+ */
+export declare function Scrim({ holes, width, height }: {
+    holes: Rect[];
+    width: number;
+    height: number;
+}): import("react/jsx-runtime").JSX.Element;
+/** The smallest rectangle around all of them. */
+export declare function boundingRect(rs: Rect[]): Rect;
+/** Where the bubble may go, in order of preference. */
+export declare const BUBBLE_PLACEMENTS: Placement[];
+/**
+ * The first placement (in BUBBLE_PLACEMENTS order) whose bubble is on screen,
+ * off the target (with its open list), and off everything to keep clear;
+ * failing that, the first that is only on screen and off the target; -1 when
+ * none is.
+ */
+export declare function pickPlacement(results: Array<{
+    x: number;
+    y: number;
+}>, bw: number, bh: number, anchor: Rect, clear: Rect[], bounds: Rect): number;
+export interface BubbleModel {
+    missionNo: number;
+    missionTitle: string;
+    replay: boolean;
+    index: number;
+    total: number;
+    title: string;
+    why: string;
+    error: StepError | null;
+    showNext: boolean;
+    showEndWithoutSave: boolean;
+}
+export interface StepLayerProps {
+    /** The spotlight (padded target), or null while there is none to show. */
+    spot: Rect | null;
+    /** Other holes: the anchors the step also allows. */
+    holes: Rect[];
+    /**
+     * Open popper lists (a select's options, a menu): holes too. While one is
+     * open the hand is not drawn (the choice is in the list now), and the ring
+     * is not drawn over a list that covers the target.
+     */
+    popovers?: Rect[];
+    /**
+     * An open dialog of the app's covers the target (a confirm its button
+     * opened): no ring, no hand and no hole there; the bubble stays.
+     */
+    covered?: boolean;
+    /** False for a "view" step with nothing to point at: the bubble is centred. */
+    hasTarget: boolean;
+    viewport: {
+        width: number;
+        height: number;
+        offsetTop: number;
+    };
+    phone: boolean;
+    showHand: boolean;
+    bubble: BubbleModel;
+    phase: "waiting" | "ready" | "missing" | "away";
+    confirmExit: boolean;
+    nudge: number;
+    /** Animate the ring to its new place (a new step). */
+    moving: boolean;
+    onExit: () => void;
+    onNext: () => void;
+    onEndWithoutSave: () => void;
+    onRetry: () => void;
+    onGoResume: () => void;
+    onExitConfirm: () => void;
+    onExitCancel: () => void;
+}
+export declare const BUBBLE_TITLE_ID = "eg-bubble-title";
+export declare const BUBBLE_WHY_ID = "eg-bubble-why";
+export declare function StepLayer(p: StepLayerProps): import("react/jsx-runtime").JSX.Element;
+/** The fingertip at ≈62% across and down the target; upside down near the bottom. */
+export declare function handPosition(spot: Rect, viewportHeight: number): {
+    left: number;
+    top: number;
+    flip: boolean;
+};
+export declare function ConfirmModal(p: {
+    title: string;
+    line: string;
+    leaveLabel: string;
+    stayLabel: string;
+    onLeave: () => void;
+    onStay: () => void;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function WelcomeModal(p: {
+    title: string;
+    subtitle: string;
+    missions: Array<{
+        title: string;
+        minutes: number;
+    }>;
+    confirm: boolean;
+    onStart: () => void;
+    onSkip: () => void;
+    onSkipConfirm: () => void;
+    onSkipCancel: () => void;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function GateModal(p: {
+    title: string;
+    subtitle?: string;
+    actionLabel: string;
+    href: string;
+    onLater: () => void;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function CelebrateModal(p: {
+    missionNo: number;
+    title: string;
+    subtitle: string;
+    done: number;
+    total: number;
+    nextTitle: string | null;
+    reduced: boolean;
+    onNext: () => void;
+    onRest: () => void;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function CompleteModal(p: {
+    total: number;
+    title: string;
+    subtitle: string;
+    missions: string[];
+    actionLabel: string;
+    secondary: {
+        label: string;
+        href: string;
+    } | null;
+    reduced: boolean;
+    onFinish: () => void;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function QuestChip({ done, total, pulse, onOpen }: {
+    done: number;
+    total: number;
+    pulse: number;
+    onOpen: () => void;
+}): import("react/jsx-runtime").JSX.Element;
+export interface QuestItem {
+    key: string;
+    title: string;
+    minutes: number;
+    view: MissionView;
+    optional: boolean;
+    completedAt?: string | null;
+    /** For "locked": the missions to do first. */
+    lockedBy?: string;
+}
+export declare function QuestPanel(p: {
+    items: QuestItem[];
+    done: number;
+    total: number;
+    justDone: string | null;
+    gate: {
+        label: string;
+        pending: string;
+        href: string;
+    } | null;
+    canHideChip: boolean;
+    onClose: () => void;
+    onStart: (key: string, replay: boolean) => void;
+    onDismiss: (key: string) => void;
+    onHideChip: () => void;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function GuideToast({ text }: {
+    text: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/guide/machine.d.ts

@@ -0,0 +1,237 @@
+/**
+ * The tour's state machine: pure. `reduceGuide(state, action, suite, env)`
+ * returns the next state and the effects for the host to carry out (save,
+ * announce, toast, navigate). Everything the machine needs to know about the
+ * page comes in through `env`, so the tests drive it with plain objects.
+ *
+ * No React, no DOM: the tests run it in Node (through the test loader).
+ */
+import type { GuideContext, GuideMission, GuideStep, GuideSuite, GuideText, GuideTrigger } from "./types";
+import { type RouteParams } from "./patterns";
+import type { GuideAudience, GuideProgress, MissionEntry } from "./progress";
+export type StepPhase = 
+/** Looking for the target (dim page, "กำลังโหลด…"). */
+"waiting"
+/** Target shown, spotlight on. */
+ | "ready"
+/** Target never came: "ไม่พบส่วนนี้บนหน้า" with ลองอีกครั้ง. */
+ | "missing"
+/** The step happens on another page: the "ทำต่อ" card. */
+ | "away";
+export interface StepError {
+    title: string;
+    detail?: string;
+}
+export type GuideScreen = {
+    name: "idle";
+} | {
+    name: "welcome";
+    confirm: boolean;
+} | {
+    name: "gate";
+} | {
+    name: "step";
+    mission: string;
+    index: number;
+    replay: boolean;
+    /** The phone/closed-sidebar "กดปุ่มเมนู" step before a nav.* target. */
+    bridge: boolean;
+    phase: StepPhase;
+    error: StepError | null;
+    confirmExit: boolean;
+    /** Timeouts so far on this step. */
+    misses: number;
+    /** A `hidden` trigger's anchor has been seen on this step, so its
+     *  going away counts. */
+    armed: boolean;
+} | {
+    name: "celebrate";
+    mission: string;
+} | {
+    name: "complete";
+};
+export interface GuideState {
+    audience: GuideAudience;
+    progress: GuideProgress;
+    screen: GuideScreen;
+    panelOpen: boolean;
+    /** A mission whose tick should pop in the panel. */
+    justDone: string | null;
+    /** Bumped to make the chip pulse twice. */
+    chipPulse: number;
+    /** Bumped to shake the bubble (a press outside the hole). */
+    nudge: number;
+    /** The gate card was put away for this visit ("ไว้ทีหลัง"). */
+    gateDismissed: boolean;
+}
+/** What the machine may ask about the page. */
+export interface GuideEnv {
+    code: string;
+    pathname: string;
+    search: URLSearchParams;
+    facts: Readonly<Record<string, unknown>>;
+    can: (policyKey: string) => boolean;
+    /** An anchor (optionally one row by data-guide-id) is on screen. */
+    isVisible: (anchor: string, id?: string) => boolean;
+    /** The sidebar is open (docked or drawer). */
+    sidebarOpen: boolean;
+    /** The current value of the step target's field. */
+    targetValue: () => string;
+}
+export type GuideSignal = {
+    kind: "api";
+    method: string;
+    path: string;
+    status: number;
+    id?: string;
+    message?: string;
+} | {
+    kind: "event";
+    name: string;
+    detail?: Record<string, string>;
+} | {
+    kind: "activate";
+} | {
+    kind: "value";
+    value: string;
+}
+/** The user typed in the step's field (clears an error). */
+ | {
+    kind: "typing";
+};
+export type GuideAction = {
+    type: "welcome";
+} | {
+    type: "welcomeSkip";
+} | {
+    type: "welcomeSkipCancel";
+} | {
+    type: "welcomeSkipConfirm";
+}
+/** "เริ่มภารกิจแรก" (and "เริ่มเลย" on the skip confirm). */
+ | {
+    type: "welcomeStart";
+} | {
+    type: "gateLater";
+} | {
+    type: "start";
+    mission: string;
+    replay?: boolean;
+} | {
+    type: "resume";
+}
+/** Route, DOM or sidebar changed: re-evaluate the current step. */
+ | {
+    type: "sync";
+} | {
+    type: "signal";
+    signal: GuideSignal;
+}
+/** ถัดไป, or Enter/Tab in an input step. */
+ | {
+    type: "next";
+} | {
+    type: "targetLost";
+} | {
+    type: "timeout";
+} | {
+    type: "retry";
+} | {
+    type: "blocked";
+} | {
+    type: "exit";
+} | {
+    type: "exitCancel";
+} | {
+    type: "exitConfirm";
+} | {
+    type: "endWithoutSave";
+} | {
+    type: "goResume";
+} | {
+    type: "celebrateNext";
+} | {
+    type: "rest";
+} | {
+    type: "finish";
+} | {
+    type: "openPanel";
+} | {
+    type: "closePanel";
+} | {
+    type: "hideChip";
+} | {
+    type: "dismissMission";
+    mission: string;
+} | {
+    type: "serverRow";
+    progress: GuideProgress;
+};
+export type GuideEffect = {
+    type: "save";
+    immediate?: boolean;
+} | {
+    type: "announce";
+    text: string;
+} | {
+    type: "toast";
+    text: string;
+} | {
+    type: "navigate";
+    href: string;
+}
+/** Close the app dialog the replay was in (Escape to Radix). */
+ | {
+    type: "closeAppDialog";
+};
+export interface GuideResult {
+    state: GuideState;
+    effects: GuideEffect[];
+}
+export declare const COPY: {
+    readonly fieldFix: "แก้ในช่องที่ไฮไลต์ แล้วกด ถัดไป";
+    readonly saveFailed: "บันทึกไม่สำเร็จ";
+    readonly blank: "ยังไม่ได้พิมพ์";
+    readonly exitToast: "ออกจากไกด์แล้ว";
+    readonly replayDone: "ทบทวนภารกิจเสร็จแล้ว";
+    readonly replayEnded: "จบการทบทวนแล้ว";
+    readonly hiddenToast: "ซ่อนแล้ว";
+    readonly aborted: "ไกด์ไปต่อไม่ได้ ลองอีกครั้งภายหลัง";
+    readonly bridgeTitle: "กดปุ่มเมนู";
+    readonly bridgeWhy: (app: string) => string;
+};
+export declare const BRIDGE_TARGET = "shell.menu-toggle";
+export declare function initialGuideState(audience: GuideAudience, progress: GuideProgress): GuideState;
+export declare function findMission(suite: GuideSuite, key: string | null | undefined): GuideMission | undefined;
+export declare function guideContext(env: GuideEnv, data: Readonly<Record<string, string>>, params?: RouteParams): GuideContext;
+export declare function resolveText(t: GuideText | undefined, ctx: GuideContext): string;
+export declare function triggersOf(step: GuideStep): GuideTrigger[];
+export declare function stepKind(step: GuideStep): import("./types").GuideStepKind;
+/** The last checkpoint at or before `index` (a mission's first step always is one). */
+export declare function checkpointAtOrBefore(steps: GuideStep[], index: number): number;
+/** Whether the step's target (or the bridge's) is on screen. */
+export declare function stepTargetVisible(step: GuideStep, env: GuideEnv, ctx: GuideContext, bridge: boolean): boolean;
+/** The anchor the spotlight is on for the current step. */
+export declare function spotlightTarget(step: GuideStep, ctx: GuideContext, bridge: boolean): {
+    anchor: string;
+    id?: string;
+} | null;
+/** Status of each mission as the panel shows it. */
+export type MissionView = "todo" | "next" | "active" | "skipped" | "done" | "already" | "locked" | "waiting";
+export declare function missionSettled(m: GuideMission, entry: MissionEntry | undefined, ctx: GuideContext): boolean;
+export declare function settledCount(suite: GuideSuite, progress: GuideProgress, ctx: GuideContext): number;
+export declare function gateState(suite: GuideSuite, ctx: GuideContext): boolean | undefined;
+export declare function missionViews(suite: GuideSuite, progress: GuideProgress, ctx: GuideContext): Array<{
+    mission: GuideMission;
+    view: MissionView;
+    entry?: MissionEntry;
+}>;
+/** The mission the celebration offers next: the first one not settled and not locked. */
+export declare function nextMissionKey(suite: GuideSuite, progress: GuideProgress, ctx: GuideContext): string | null;
+/** Whether the welcome should open by itself. */
+export declare function welcomeDue(state: GuideState, suite: GuideSuite): boolean;
+/** Whether the floating "ภารกิจ n/N" chip shows. */
+export declare function chipVisible(state: GuideState, suite: GuideSuite, ctx: GuideContext): boolean;
+/** "กด [บันทึก]" → "กด บันทึก" (for screen readers). */
+export declare function plainTitle(t: string): string;
+export declare function reduceGuide(state: GuideState, action: GuideAction, suite: GuideSuite, env: GuideEnv): GuideResult;