@eintrek/erp-shell 0.1.66 → 0.1.68

package/dist/guide/core.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@eintrek/erp-shell/guide-core`: the guided-tour engine without the shell.
+ *
+ * For an app that does not use AppLayoutShell (erp-liff): no React Query,
+ * axios, zustand, next-auth, next-themes or sidebar behind it — only React,
+ * react-dom and @floating-ui/dom. The app mounts GuideRuntime with adapters
+ * (routing, isBusy, progress, menu, hidden). Authors:
+ * _claude-work/guides-r2/GUIDE-CORE.md and _claude-work/peoplx-guide/ENGINE-API.md.
+ *
+ * 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, 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 { openGuidePanel, useGuideEntry, type GuideEntry } from "./guide-store";
+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 } from "./progress";
+export { matchApiPath, matchRoute, fillRoute } from "./patterns";

package/dist/guide/dom.d.ts

@@ -38,6 +38,8 @@ export declare const OPEN_DIALOG_SELECTOR = "[role=\"dialog\"][data-state=\"open
  * behind it.
  */
 export declare function coveredByDialog(el: Element | null): boolean;
+/** An app dialog (not the tour's) is open on the page. */
+export declare function appDialogOpen(): boolean;
 export declare function openPoppers(): HTMLElement[];
 export declare function inGuideLayer(node: EventTarget | null): boolean;
 export declare function prefersReducedMotion(): boolean;

package/dist/guide/events.d.ts

@@ -22,3 +22,28 @@ export declare function emitGuideEvent(name: string, detail?: Record<string, str
 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;
+/** One answered request, from a client that is not axios (plain `fetch`). */
+export interface ApiCallReport {
+    /** "POST"; any case. Default "GET". */
+    method?: string;
+    /** The request URL, absolute or relative (any query is dropped). */
+    url: string;
+    /** The base the URL is relative to, if any. */
+    baseURL?: string;
+    /** The HTTP status; 0 for a network failure. */
+    status: number;
+    /**
+     * The parsed response body, if at hand. Only the saved record's id (on a
+     * 2xx: `id` or `data.id`) and the server's message (otherwise) are read
+     * from it; the body itself never goes on the bus.
+     */
+    data?: unknown;
+}
+/** The bus detail for a fetch-style report; null when it has no URL. */
+export declare function apiCallDetail(call: ApiCallReport): ApiEventDetail | null;
+/**
+ * Puts a request answered through plain `fetch` on the bus (`{ api }`
+ * triggers and `completeOn`). Call it once per answer, refusals and network
+ * failures (status 0) included. Safe to call with anything.
+ */
+export declare function reportApiCall(call: ApiCallReport): void;

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

@@ -0,0 +1,83 @@
+/**
+ * GuideRuntime: runs an app's tour against the real page, with everything
+ * app-specific passed in as adapters — routing, "is the page loading",
+ * where progress is kept, the menu, when to stay hidden. It loads progress,
+ * decides who sees what from the answer, runs the state machine (machine.ts)
+ * and draws the layer (guide-ui.tsx) in a portal marked data-erp-guide-layer.
+ *
+ * Two hosts build the adapters: the shell's GuideHost (AppLayoutShell:
+ * Next router, React Query, the sidebar, platform-api through axios) and an
+ * app without the shell, through `@eintrek/erp-shell/guide-core` (erp-liff:
+ * its own fetch client and peoplx-api). No React Query, axios, zustand,
+ * next-auth, next-themes or Next import here.
+ *
+ * Fail open, always: an API error, an odd answer, a predicate or a render
+ * that throws — the tour does not show and the app is untouched.
+ */
+import * as React from "react";
+import type { GuideConfig } from "./types";
+import { type GuideProgressAdapter } from "./progress-sync";
+/** Where the user is, and how the tour sends them somewhere (route triggers, resume, ทำต่อ). */
+export interface GuideRouting {
+    /** The current path, without the query: Next's usePathname(). */
+    pathname: string;
+    /** The current query without "?": useSearchParams().toString(). */
+    search: string;
+    /** Go to an in-app path ("/me/leave"); absolute URLs are opened by the engine itself. */
+    navigate: (href: string) => void;
+}
+/** The app's navigation menu, for the phone's "กดปุ่มเมนู" step before a `nav.*` target. */
+export interface GuideMenu {
+    /** The menu (sidebar or drawer) is open now. */
+    open: boolean;
+}
+export interface GuideRuntimeProps {
+    config: GuideConfig;
+    /** What progress is kept per: the organisation id. A change starts over. */
+    organizationId: string;
+    /**
+     * Fills `[code]` in routes and is the only value `[code]`/`[[code]]` may
+     * match. The org code in the URL; "" where the URL has none (LIFF `/me/…`).
+     */
+    code: string;
+    routing: GuideRouting;
+    /** Where progress is read and saved (progress-sync.ts). */
+    progress: GuideProgressAdapter;
+    /**
+     * Whether the page is still loading data. A step waiting for its target
+     * counts only time when this is false; the welcome and a waiting
+     * celebration open after a moment of it being false. Polled. Default: never.
+     */
+    isBusy?: () => boolean;
+    /** The app's menu; null or omitted: none (no menu step; do not target `nav.*`). */
+    menu?: GuideMenu | null;
+    /** True keeps the tour out of sight (sign-in, a picker, a gate of the app's). */
+    hidden?: boolean;
+    /**
+     * Sets `--erp-guide-bottom-offset` on the layer: how far the chip and the
+     * bottom cards sit from the bottom (above a bottom nav), e.g.
+     * "calc(64px + env(safe-area-inset-bottom))". Default: the CSS variable as
+     * the page sets it, else 16px (22px beside the docked layout on desktop).
+     */
+    bottomOffset?: string;
+}
+/** Hides the tour (and only the tour) after any error under it. */
+export declare class GuideErrorBoundary extends React.Component<{
+    children: React.ReactNode;
+}, {
+    failed: boolean;
+}> {
+    state: {
+        failed: boolean;
+    };
+    static getDerivedStateFromError(): {
+        failed: boolean;
+    };
+    componentDidCatch(error: unknown): void;
+    render(): React.ReactNode;
+}
+/**
+ * Runs a tour with the app's adapters. Mount it once, above the pages (so a
+ * route change does not unmount it), only where the tour may run.
+ */
+export declare function GuideRuntime(props: GuideRuntimeProps): import("react/jsx-runtime").JSX.Element;

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

@@ -3,5 +3,11 @@
  * 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).
+ *
+ * `--erp-guide-bottom-offset` (set by the app on :root/body, or through
+ * GuideRuntime's `bottomOffset`) lifts the chip, the bottom card, the toast
+ * and the desktop panel above a bottom nav. Unset, they sit where they did
+ * before 0.1.68: 16px from the bottom (+ the safe area) on a phone, 22px on
+ * desktop.
  */
-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";
+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:calc(var(--erp-guide-bottom-offset,16px) + 12px);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:var(--erp-guide-bottom-offset,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:calc(var(--erp-guide-bottom-offset,22px) + 60px);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:calc(var(--erp-guide-bottom-offset,22px) + 62px);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:var(--erp-guide-bottom-offset,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(var(--erp-guide-bottom-offset,calc(16px + env(safe-area-inset-bottom))) - 4px)}\n  .eg-toast{bottom:calc(var(--erp-guide-bottom-offset,calc(16px + env(safe-area-inset-bottom))) + 60px)}\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/machine.d.ts

@@ -44,6 +44,9 @@ export type GuideScreen = {
     /** A `hidden` trigger's anchor has been seen on this step, so its
      *  going away counts. */
     armed: boolean;
+    /** A commit step shown in its read form: nothing to save
+     *  (GuideStep.nothingToSave). */
+    nothingToSave: boolean;
 } | {
     name: "celebrate";
     mission: string;
@@ -63,6 +66,23 @@ export interface GuideState {
     nudge: number;
     /** The gate card was put away for this visit ("ไว้ทีหลัง"). */
     gateDismissed: boolean;
+    /**
+     * What the user already had open when the current replay started: those
+     * are theirs, and ending the replay leaves them alone (see pushAbort).
+     */
+    replayPage: ReplayPage | null;
+    /**
+     * Missions done outside the tour (`completeOn`) whose celebration waits for
+     * the next idle moment (never mid-step). Not saved: a reload drops it.
+     */
+    pendingCelebrate: string[];
+}
+export interface ReplayPage {
+    mission: string;
+    /** The mission's abort anchors that were on the page at the start. */
+    anchors: string[];
+    /** An app dialog was open at the start. */
+    dialog: boolean;
 }
 /** What the machine may ask about the page. */
 export interface GuideEnv {
@@ -77,6 +97,8 @@ export interface GuideEnv {
     sidebarOpen: boolean;
     /** The current value of the step target's field. */
     targetValue: () => string;
+    /** An app dialog (not the tour's) is open. */
+    dialogOpen?: () => boolean;
 }
 export type GuideSignal = {
     kind: "api";
@@ -166,6 +188,15 @@ export type GuideAction = {
 } | {
     type: "serverRow";
     progress: GuideProgress;
+}
+/** An API answer or app event, whenever the host is mounted: `completeOn`. */
+ | {
+    type: "passive";
+    signal: GuideSignal;
+}
+/** The host is idle: show a waiting `completeOn` celebration. */
+ | {
+    type: "idleCelebrate";
 };
 export type GuideEffect = {
     type: "save";
@@ -207,12 +238,32 @@ export declare const COPY: {
 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;
+/**
+ * Whether the user has this mission (GuideMission.visible). Without the
+ * predicate, yes; with it, only `true` (undefined — not known yet — and a
+ * throw hide it).
+ */
+export declare function missionShown(m: GuideMission, ctx: GuideContext): boolean;
+/** The missions this user has, in order: what the panel draws and n/N counts. */
+export declare function shownMissions(suite: GuideSuite, ctx: GuideContext): GuideMission[];
+/** The mission's number among the shown ones (1-based); its place in the suite when hidden. */
+export declare function missionNumber(suite: GuideSuite, key: string, ctx: GuideContext): number;
 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;
+/**
+ * A commit step with nothing to save: its button is not on the page, and what
+ * is saved is (GuideStep.nothingToSave).
+ */
+export declare function nothingToSaveHolds(step: GuideStep, env: GuideEnv, ctx: GuideContext): boolean;
+/**
+ * The step as it is shown: a commit step with nothing to save is a read step
+ * on what is saved, with its own title (ถัดไป moves on).
+ */
+export declare function shownStep(step: GuideStep, nothingToSave: boolean): GuideStep;
 /** 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. */
@@ -228,9 +279,18 @@ export declare function spotlightTarget(step: GuideStep, ctx: GuideContext, brid
 export declare function stepHomeRoute(steps: GuideStep[], index: number): string | undefined;
 /** What puts the page back when a replay ends at this step (see GuideStep.abort). */
 export declare function abortActionsFor(mission: GuideMission, index: number): GuideAbortAction[];
+/** Every anchor the mission's abort actions press. */
+export declare function abortAnchorsOf(mission: GuideMission): string[];
+/**
+ * What the replay may do to put the page back: not press what the user had
+ * open before it started, not Escape out of a dialog that was already open,
+ * and no app event while anything of theirs was open.
+ */
+export declare function abortActionsLeft(actions: GuideAbortAction[], before: ReplayPage | null): GuideAbortAction[];
 /** 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;
+/** Settled missions among the shown ones (the n of n/N). */
 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<{
@@ -240,10 +300,16 @@ export declare function missionViews(suite: GuideSuite, progress: GuideProgress,
 }>;
 /** 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 welcome should open by itself (with `ctx`: only when a mission is shown). */
+export declare function welcomeDue(state: GuideState, suite: GuideSuite, ctx?: GuideContext): 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;
+/** A mission's `completeOn` triggers, as a list. */
+export declare function completeTriggersOf(mission: GuideMission): GuideTrigger[];
+/** Every app event name a suite's `completeOn` listens for. */
+export declare function passiveEventNames(suite: GuideSuite): string[];
+/** Missions whose `completeOn` this signal meets ({ api } and { event } only). */
+export declare function passiveMatches(suite: GuideSuite, sig: GuideSignal): GuideMission[];
 export declare function reduceGuide(state: GuideState, action: GuideAction, suite: GuideSuite, env: GuideEnv): GuideResult;

package/dist/guide/patterns.d.ts

@@ -7,10 +7,14 @@ export type RouteParams = Record<string, string>;
 /**
  * Matches a Next-style page pattern ("/[code]/employee/[id]", optionally
  * "?tab=job") against a path and query. `[code]`, when given, must be the
- * organisation code. Returns the params, or null.
+ * organisation code. `[[x]]` is a segment that may be absent. Returns the
+ * params, or null.
  */
 export declare function matchRoute(pattern: string, pathname: string, search?: URLSearchParams | string | null, code?: string): RouteParams | null;
-/** Fills a page pattern's params ("/[code]/x/[id]" → "/O1/x/42"); null if one is missing. */
+/**
+ * Fills a page pattern's params ("/[code]/x/[id]" → "/O1/x/42"); null if one
+ * is missing. A `[[x]]` segment without a value is left out.
+ */
 export declare function fillRoute(pattern: string, params: Readonly<Record<string, string | undefined>>): string | null;
 /**
  * The path of a request, without origin, base URL query or hash:

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

@@ -1,11 +1,12 @@
 import type { GuideSuite } from "./types";
-import { type GuideProgress, type GuidesAnswer } from "./progress";
+import type { GuideProgress, GuidesAnswer } from "./progress";
+import { type GuideProgressAdapter } from "./progress-sync";
+/** platform-api's `…/organizations/:id/guides/me` as a progress adapter. */
+export declare function platformGuideProgress(organizationId: string): GuideProgressAdapter;
 /** GET …/guides/me?app=…; null (show nothing) on any failure or odd answer. */
 export declare function fetchGuides(organizationId: string, suite: GuideSuite, signal?: AbortSignal): Promise<GuidesAnswer | null>;
 /**
- * PUT the whole state. On 409 the server's row comes back: merge (keeping
- * whatever is further along) and try once more with its rev. Returns the
- * stored row, or null when it could not be saved (the tour goes on; the
- * session copy keeps the place).
+ * PUT the whole state; on 409 merge and try once more (progress-sync.ts).
+ * Returns the stored row, or null when it could not be saved.
  */
 export declare function saveGuides(organizationId: string, suite: GuideSuite, progress: GuideProgress): Promise<GuideProgress | null>;

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

@@ -0,0 +1,68 @@
+/**
+ * Loading and saving tour progress through an adapter, so the rules stay in
+ * one place whatever carries the request: platform-api through the shell's
+ * axios (GuideHost), or peoplx-api's `/public/line/me/guides` through LIFF's
+ * fetch client (guide-core). The adapter only moves bytes; parsing, the
+ * fail-open rule and the 409 merge are here.
+ *
+ * No runtime imports beyond sibling pure modules: the tests run it in Node.
+ */
+import type { GuideSuite } from "./types";
+import { type GuideProgress, type GuidesAnswer } from "./progress";
+/** What a progress call is about. */
+export interface GuideProgressRequest {
+    /** The suite's app ("peoplx", "liff"). */
+    app: string;
+    /** The suite's key, the row on the server ("liff.first-run"). */
+    guideKey: string;
+}
+/** An HTTP answer as the adapter got it. */
+export interface GuideProgressResponse {
+    /** The HTTP status. */
+    status: number;
+    /** The parsed JSON body (the API's envelope, or the row itself). */
+    data: unknown;
+}
+/**
+ * How the engine reaches the progress API. Both calls carry the user's
+ * credentials and the organisation, as the app's own client does.
+ *
+ * - `fetchProgress` answers what `GET …/guides/me?app=` answers (API.md §3):
+ *   the envelope `{ data: { app, mode, audience, guides } }` or its `data`.
+ *   Throw, or return anything else, and the tour does not show.
+ * - `saveProgress` sends `body` as the whole row (API.md §4) and returns the
+ *   status and parsed body — a 409 too, with its `current`, so the engine
+ *   merges and retries. A client that throws on non-2xx may instead throw
+ *   `new GuideProgressConflict(current)` (or anything with `status: 409` and
+ *   `current`): it is read as the same 409. Throw anything else (or return
+ *   another status) on any other failure: the tour goes on and the session
+ *   copy keeps the place.
+ */
+export interface GuideProgressAdapter {
+    fetchProgress(req: GuideProgressRequest & {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    saveProgress(req: GuideProgressRequest & {
+        body: Record<string, unknown>;
+    }): Promise<GuideProgressResponse>;
+}
+/**
+ * A 409 from the progress API, for a client that throws on non-2xx: throw
+ * it from `saveProgress` with the answer's `current` (the stored row, or
+ * null) and the engine merges as if `{ status: 409, data: { current } }` had
+ * been returned.
+ */
+export declare class GuideProgressConflict extends Error {
+    readonly current: unknown;
+    readonly code: string;
+    readonly status = 409;
+    constructor(current: unknown, code?: string);
+}
+/** The GET, parsed for this suite; null (show nothing) on any failure or odd answer. */
+export declare function loadGuides(adapter: GuideProgressAdapter, suite: GuideSuite, signal?: AbortSignal): Promise<GuidesAnswer | null>;
+/**
+ * PUT the whole state. On 409 the server's row comes back: merge (keeping
+ * whatever is further along) and try once more with its rev. Returns the
+ * stored row, or null when it could not be saved.
+ */
+export declare function storeGuides(adapter: GuideProgressAdapter, suite: GuideSuite, progress: GuideProgress): Promise<GuideProgress | null>;

package/dist/guide/types.d.ts

@@ -10,7 +10,9 @@
  * The full guide for tour authors is _claude-work/peoplx-guide/ENGINE-API.md.
  */
 /** Which app a tour belongs to (the same ids as the help channel). */
-export type GuideAppId = "platform" | "accounx" | "invenx" | "plannex" | "peoplx" | "sellx" | "carex";
+export type GuideAppId = "platform" | "accounx" | "invenx" | "plannex" | "peoplx" | "sellx" | "carex"
+/** The employee app inside LINE (erp-liff), through `guide-core`. */
+ | "liff";
 /**
  * A `data-guide` key, "<app>.<area>.<element>" — "peoplx.shift.edit".
  * The shell's own: "nav.<menu item id>", "shell.menu-toggle", "shell.help".
@@ -48,7 +50,8 @@ export type GuideText = string | ((ctx: GuideContext) => string);
  */
 export type GuideTrigger = 
 /** The page is this route. Next-style pattern; an optional `?k=v` must be
- *  in the query. `/[code]/setting?tab=department` */
+ *  in the query. `/[code]/setting?tab=department`. `[[x]]` is a segment
+ *  that may be absent: `/me/[[org]]/attendance` (shell ≥ 0.1.68). */
 {
     route: string;
 }
@@ -180,6 +183,17 @@ export interface GuideStep {
      * or Escape to the open dialog. Overrides the mission's `abort`.
      */
     abort?: GuideAbortAction | GuideAbortAction[];
+    /**
+     * "commit" steps whose button only shows after a change (a save bar that
+     * appears once the form is edited). When `target` is not on the page but
+     * `nothingToSave.target` is (what is saved is on screen and nothing is
+     * changed), the step is a read step on that anchor, with ถัดไป, which moves
+     * on as if saved. The moment `target` shows (the user changed something)
+     * it is the commit step again. Name an anchor that only exists when the
+     * saved state is real, so a first run never passes without a save that
+     * was needed (shell ≥ 0.1.67).
+     */
+    nothingToSave?: GuideNothingToSave;
     /**
      * "commit" steps: what a refused save means. Return the key of the step to
      * go back to (a field) and/or the line to show. Default: stay, show the
@@ -190,10 +204,20 @@ export interface GuideStep {
         message?: string;
     } | void;
 }
+/** A commit step's read form when there is nothing to save (GuideStep.nothingToSave). */
+export interface GuideNothingToSave {
+    /** What is saved, on screen (the placed point's card, the saved list). */
+    target: GuideAnchorKey;
+    title: GuideText;
+    why?: GuideText;
+    /** Anchors the user may use meanwhile; a change there brings the save back. */
+    allow?: GuideAnchorKey[];
+}
 /**
  * One thing the engine does to put the page back when a replay ends early.
  * Run in order, after the tour has let go of the page; an anchor that is not
- * on the page is passed over.
+ * on the page is passed over, and so is one that was already on the page
+ * when the replay started (the user's own open form: shell ≥ 0.1.67).
  */
 export type GuideAbortAction = 
 /** Press this anchor (the form's ยกเลิก, a dialog's close). */
@@ -242,6 +266,24 @@ export interface GuideMission {
      * "ดูวิธีทำ" (a replay). undefined = not known yet.
      */
     alreadyDone?: (ctx: GuideContext) => boolean | undefined;
+    /**
+     * Whether this user has the mission at all (a menu the org lacks, a plan
+     * without LINE). A hidden mission is not drawn in the panel or the welcome,
+     * does not count in n/N and is never "next". Without it the mission shows;
+     * with it, only `true` shows it: undefined (not known yet) and a throw hide
+     * it, so a mission the user may not have never flashes in. A hidden
+     * mission named in another's `after` does not lock it (shell ≥ 0.1.68).
+     */
+    visible?: (ctx: GuideContext) => boolean | undefined;
+    /**
+     * Done without the tour: while the engine is mounted (not only inside a
+     * step), this `{ api }` or `{ event }` trigger marks the mission done with
+     * the ordinary save, and its celebration shows at the next idle moment,
+     * never in the middle of a step. Other trigger kinds are ignored here.
+     * E.g. the first real punch: `{ api: { method: "POST", path:
+     * "/public/line/me/attendance/punch" } }` (shell ≥ 0.1.68).
+     */
+    completeOn?: GuideTrigger | GuideTrigger[];
     /** The celebration. Title defaults to "<title>แล้ว". */
     done?: {
         title?: GuideText;
@@ -251,6 +293,9 @@ export interface GuideMission {
      * How to put the page back when a replay of this mission ends without
      * saving (a step's own `abort` wins). Default: Escape, and only from a step
      * that is not a checkpoint (inside the dialog or form the tour opened).
+     * Whatever was already open when the replay started is the user's and is
+     * left alone: an anchor on the page then is never pressed, and no Escape
+     * is sent when an app dialog was open (shell ≥ 0.1.67).
      */
     abort?: GuideAbortAction | GuideAbortAction[];
     steps: GuideStep[];

package/dist/guide-core.cjs

@@ -0,0 +1,29 @@
+'use client';
+'use strict';
+
+var guideRuntime = require('./chunks/guide-runtime-B2RjoQeb.cjs');
+require('react/jsx-runtime');
+require('react');
+require('react-dom');
+require('@floating-ui/dom');
+
+
+
+exports.GUIDE_API_EVENT = guideRuntime.API_EVENT;
+exports.GUIDE_EVENT_PREFIX = guideRuntime.GUIDE_EVENT_PREFIX;
+exports.GUIDE_LAYER_ATTRIBUTE = guideRuntime.GUIDE_LAYER_ATTRIBUTE;
+exports.GuideProgressConflict = guideRuntime.GuideProgressConflict;
+exports.GuideRuntime = guideRuntime.GuideRuntime;
+exports.apiCallDetail = guideRuntime.apiCallDetail;
+exports.emitGuideEvent = guideRuntime.emitGuideEvent;
+exports.fillRoute = guideRuntime.fillRoute;
+exports.guideAnchor = guideRuntime.guideAnchor;
+exports.loadGuides = guideRuntime.loadGuides;
+exports.matchApiPath = guideRuntime.matchApiPath;
+exports.matchRoute = guideRuntime.matchRoute;
+exports.openGuidePanel = guideRuntime.openGuidePanel;
+exports.reportApiCall = guideRuntime.reportApiCall;
+exports.reportApiEvent = guideRuntime.reportApiEvent;
+exports.storeGuides = guideRuntime.storeGuides;
+exports.useGuideEntry = guideRuntime.useGuideEntry;
+//# sourceMappingURL=guide-core.cjs.map

package/dist/guide-core.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide-core.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/guide-core.esm.js

@@ -0,0 +1,7 @@
+'use client';
+export { A as GUIDE_API_EVENT, G as GUIDE_EVENT_PREFIX, a as GUIDE_LAYER_ATTRIBUTE, c as GuideProgressConflict, d as GuideRuntime, e as apiCallDetail, f as emitGuideEvent, g as fillRoute, h as guideAnchor, l as loadGuides, m as matchApiPath, i as matchRoute, o as openGuidePanel, r as reportApiCall, j as reportApiEvent, s as storeGuides, u as useGuideEntry } from './chunks/guide-runtime-BT7rN-5p.esm.js';
+import 'react/jsx-runtime';
+import 'react';
+import 'react-dom';
+import '@floating-ui/dom';
+//# sourceMappingURL=guide-core.esm.js.map

package/dist/guide-core.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide-core.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}