@steppy/player 0.0.0-stage → 0.4.0

package/dist/types/tour/engine.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The tour state machine, as a pure reducer: ``reduce(state, event)`` returns
+ * the next state and the effects the host must carry out (load, navigate, wait
+ * for an element, emit an event, persist the resume record, ...). No DOM, no
+ * timers — every transition is a unit test.
+ *
+ * Async results come back as events carrying the ``token`` they were started
+ * under; ``token`` changes whenever a step or phase change invalidates pending
+ * work, so a late answer from an abandoned wait is dropped instead of moving
+ * the tour.
+ *
+ * Phases: ``idle`` → ``loading`` → (``entering``) → ``resolving`` →
+ * ``showing``; a target that does not appear in time puts the step in
+ * ``fallback`` (the "can't find this element" popover, with Skip / End); a
+ * target that disappears while shown goes ``lost``, then ``paused`` (the pill)
+ * when it stays away.
+ */
+import type { TourErrorReason } from './contract.js';
+import type { Issue, TourFile } from './validate.js';
+export type Phase = 'idle' | 'loading' | 'entering' | 'resolving' | 'showing' | 'lost' | 'fallback' | 'paused';
+export type StepReason = 'start' | 'advance' | 'jump' | 'skip' | 'resume' | 'recovered';
+export type DismissVia = 'close' | 'escape' | 'end' | 'api' | 'replaced' | 'disabled';
+export type TourSourceKind = 'bundled' | 'remote' | 'custom';
+export type TriggerKind = 'click' | 'input-commit' | 'change' | 'visible';
+export type WaitMode = 'resolve' | 'fallback' | 'lost' | 'paused' | 'visible';
+export interface Loaded {
+    tour: TourFile;
+    source: TourSourceKind;
+    /** Per step: does it apply to the current layout (``tours.layouts``)? */
+    applicable: readonly boolean[];
+    start: number;
+    resumed: boolean;
+    /** The entry route must be navigated to before the first step. */
+    navigate: boolean;
+}
+export interface TourErrorDetail {
+    reason: TourErrorReason;
+    fatal: boolean;
+    message: string;
+    tourId?: string;
+    buildId?: string;
+    locale?: string;
+    stepId?: string;
+    index?: number;
+    testId?: string;
+    kind?: 'target' | 'waitFor';
+    missing?: string[];
+    issues?: Issue[];
+}
+export interface EngineState {
+    readonly phase: Phase;
+    readonly token: number;
+    readonly loaded: Loaded | null;
+    readonly index: number;
+    /** The ``tour-step`` reason to report when the pending step shows. */
+    readonly reason: StepReason;
+    readonly fieldNonEmpty: boolean;
+}
+export type EngineEvent = {
+    type: 'REQUEST';
+} | {
+    type: 'LOADED';
+    loaded: Loaded;
+} | {
+    type: 'LOAD_FAILED';
+    error: TourErrorDetail;
+} | {
+    type: 'ENTER_DONE';
+    token: number;
+} | {
+    type: 'ENTER_FAILED';
+    token: number;
+    message: string;
+} | {
+    type: 'RESOLVED';
+    token: number;
+    fieldNonEmpty?: boolean;
+} | {
+    type: 'RESOLVE_TIMEOUT';
+    token: number;
+    testId: string | null;
+    kind: 'target' | 'waitFor';
+} | {
+    type: 'TRIGGER';
+    token: number;
+    kind: TriggerKind;
+} | {
+    type: 'NEXT';
+    token?: number;
+} | {
+    type: 'SKIP';
+    token: number;
+} | {
+    type: 'FIELD';
+    token: number;
+    nonEmpty: boolean;
+} | {
+    type: 'JUMP';
+    token: number;
+    to: number;
+    performed: boolean;
+} | {
+    type: 'TARGET_LOST';
+    token: number;
+} | {
+    type: 'TARGET_BACK';
+    token: number;
+} | {
+    type: 'LOST_TIMEOUT';
+    token: number;
+} | {
+    type: 'RESUME';
+    token: number;
+} | {
+    type: 'DISMISS';
+    via: DismissVia;
+    reason?: string;
+} | {
+    type: 'LOCALE';
+    tour: TourFile;
+};
+export type Effect = {
+    type: 'load';
+} | {
+    type: 'emit';
+    name: 'tour-start' | 'tour-step' | 'tour-complete' | 'tour-dismiss' | 'tour-offpath' | 'tour-error';
+    detail: object;
+} | {
+    type: 'persist';
+    index: number;
+} | {
+    type: 'clearPersist';
+} | {
+    type: 'navigate';
+    token: number;
+} | {
+    type: 'wait';
+    mode: WaitMode;
+    index: number;
+    token: number;
+} | {
+    type: 'focus';
+} | {
+    type: 'teardown';
+};
+export interface Transition {
+    state: EngineState;
+    effects: Effect[];
+}
+export declare function initialState(): EngineState;
+export declare const isActive: (s: EngineState) => boolean;
+/** Position among applicable steps (0-based) and their count — what progress shows. */
+export declare function position(s: EngineState, index?: number): {
+    index: number;
+    total: number;
+};
+export declare function reduce(s: EngineState, e: EngineEvent): Transition;

package/dist/types/tour/events.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The six DOM events the overlay dispatches on its host element — bubbling
+ * and composed, JSON-only details. Colon-free names on purpose: Angular
+ * templates read ``(a:b)`` as a global event target.
+ */
+import type { AdvanceKind } from './contract.js';
+import type { DismissVia, StepReason, TourErrorDetail, TourSourceKind } from './engine.js';
+export interface TourEventMeta {
+    tourId: string;
+    buildId: string;
+    locale: string;
+}
+export interface TourStepPosition extends TourEventMeta {
+    stepId: string;
+    /** 0-based, counting only the steps that apply to the current layout. */
+    index: number;
+    total: number;
+}
+export interface TourEventDetailMap {
+    'tour-start': TourEventMeta & {
+        total: number;
+        source: TourSourceKind;
+        resumed: boolean;
+        entryNavigated: boolean;
+    };
+    'tour-step': TourStepPosition & {
+        advance: AdvanceKind;
+        reason: StepReason;
+    };
+    'tour-complete': TourEventMeta & {
+        total: number;
+    };
+    'tour-dismiss': TourStepPosition & {
+        via: DismissVia;
+        reason?: string;
+    };
+    'tour-offpath': TourStepPosition & {
+        reason: 'target-lost';
+    };
+    'tour-error': TourErrorDetail;
+}
+export declare function emitTourEvent<K extends keyof TourEventDetailMap>(host: EventTarget, name: K, detail: TourEventDetailMap[K]): void;

package/dist/types/tour/host.d.ts

@@ -0,0 +1,153 @@
+/**
+ * ``<steppy-tour-host>`` — mount it once in the app shell and call
+ * ``start(tourId)``. The element interprets the engine's effects (``engine.ts``)
+ * and owns the browser-facing pieces: loader, resolver, tracker, triggers,
+ * focus, the live region and the resume record. It renders nothing while no
+ * tour runs.
+ *
+ * Two switches keep it out of the way: the global
+ * ``__STEPPY_TOURS_DISABLED__`` (set by generated E2E tests so an app that
+ * auto-starts a tour cannot cover what a test clicks; read at call time) and
+ * the ``disabled`` property. Either makes ``start()`` a no-op.
+ */
+import { LitElement, nothing, type PropertyValues } from 'lit';
+import type { TourHostApi, TourNavigate, TourPosition, TourStartOptions } from './api.js';
+import { type DomAdapter } from './dom.js';
+import { type TourEventDetailMap } from './events.js';
+import { type TourSource } from './loader.js';
+import { type TourStringOverrides } from './strings.js';
+export interface SteppyTourHost {
+    addEventListener<K extends keyof TourEventDetailMap>(type: K, listener: (this: SteppyTourHost, ev: CustomEvent<TourEventDetailMap[K]>) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+}
+export declare class SteppyTourHost extends LitElement implements TourHostApi {
+    static styles: import("lit").CSSResult;
+    static properties: {
+        manifest: {
+            type: StringConstructor;
+        };
+        fallbackManifest: {
+            type: StringConstructor;
+            attribute: string;
+        };
+        buildId: {
+            type: StringConstructor;
+            attribute: string;
+        };
+        locale: {
+            type: StringConstructor;
+        };
+        guideOrigin: {
+            type: StringConstructor;
+            attribute: string;
+        };
+        baseZIndex: {
+            type: NumberConstructor;
+            attribute: string;
+        };
+        targetTimeout: {
+            type: NumberConstructor;
+            attribute: string;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        source: {
+            attribute: boolean;
+        };
+        navigate: {
+            attribute: boolean;
+        };
+        strings: {
+            attribute: boolean;
+        };
+    };
+    /** Test seam: geometry and timing. */
+    static dom: DomAdapter;
+    manifest: string;
+    fallbackManifest: string;
+    buildId: string;
+    locale: string;
+    guideOrigin: string;
+    baseZIndex: number;
+    targetTimeout: number;
+    disabled: boolean;
+    source: TourSource | null;
+    navigate: TourNavigate | null;
+    strings: TourStringOverrides | undefined;
+    private _s;
+    private _queue;
+    private _dispatching;
+    private _run;
+    private _cache;
+    private _resolver;
+    private _cancelWait;
+    private _target;
+    private _tracker;
+    private _detach;
+    private _change;
+    private _shownKey;
+    private _shownAt;
+    private _pressToken;
+    private _focusPending;
+    private _appFocus;
+    private _swapSeq;
+    /** While a tour runs: an app that switches language through ``<html lang>`` alone. */
+    private _lang;
+    private _policy;
+    private _handlers;
+    private get _dom();
+    get isActive(): boolean;
+    get current(): TourPosition | null;
+    start(tourId: string, options?: TourStartOptions): Promise<boolean>;
+    stop(reason?: string): void;
+    next(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    protected updated(changed: PropertyValues<this>): void;
+    protected firstUpdated(): void;
+    protected render(): import("lit-html").TemplateResult | typeof nothing;
+    private _start;
+    private _fail;
+    private _tryResume;
+    private _manifestKey;
+    /** The host's ``locale``, else the page's ``<html lang>``. */
+    private _preferredLocale;
+    private _cfg;
+    /** Reload the running tour in the preferred locale; the last request wins. */
+    private _swapLocale;
+    private _dispatch;
+    private _effect;
+    private _persist;
+    private _enter;
+    private _timeout;
+    private _wait;
+    private _layer;
+    private _bubble;
+    private _afterRender;
+    /** Manual and fallback steps take focus — once placed: a hidden bubble cannot be focused. */
+    private _applyPendingFocus;
+    private _onStepShown;
+    private _announce;
+    private _makeTracker;
+    private _preferredSide;
+    private _nextTargetRect;
+    /** The app's open dialogs (the overlay's own bubble is in the shadow root, so never one of them). */
+    private _openDialogs;
+    private _ensureTriggers;
+    private _onFocusIn;
+    /** Our buttons: a click counts only if it was pressed on this step (or, by keyboard, after a short grace). */
+    private _guarded;
+    private _deepActive;
+    private _teardown;
+    private _link;
+}
+/** Register ``<steppy-tour-host>`` once; a second call (or a second copy of the bundle) is a no-op. */
+export declare function defineTourHost(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'steppy-tour-host': SteppyTourHost;
+    }
+}

package/dist/types/tour/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ``@steppy/player/tour`` — the in-app tour overlay.
+ *
+ * Importing this module registers ``<steppy-tour-host>`` (once, even if two
+ * copies of the bundle load). It touches ``HTMLElement`` at load, so a
+ * server-rendered app imports it in the browser only.
+ */
+export { SteppyTourHost, defineTourHost } from './host.js';
+export type { TourHostApi, TourNavigate, TourNavigateContext, TourPosition, TourSource, TourStartOptions, TourStringOverrides } from './api.js';
+export type { TourEventDetailMap, TourEventMeta, TourStepPosition } from './events.js';
+export type { DismissVia, StepReason, TourErrorDetail, TourSourceKind } from './engine.js';
+export { ADVANCE_KINDS, PLACEMENTS, TOUR_ERROR_REASONS, TOUR_EVENTS, TOUR_PARTS, TOUR_SCHEMA_VERSION, type AdvanceKind, type Placement, type TourErrorReason, type TourEventName, type TourPart, } from './contract.js';
+export { TOUR_HOST_TAG, TOURS_KILL_SWITCH_GLOBAL } from '../ui/names.js';
+export { DEFAULT_TOUR_STRINGS, type TourStrings } from './strings.js';
+export { validateManifest, validateTour, type TourFile, type TourManifest, type TourStep } from './validate.js';

package/dist/types/tour/layer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Stacking. Where the popover API exists the layer is a ``popover="manual"``
+ * element in the browser's top layer — above any z-index the app uses — and
+ * every step re-raises it (hide, then show) so it stays above an app dialog
+ * opened after it. Elsewhere the layer falls back to ``z-index: var(--_pw-z)``.
+ *
+ * Known limit: a native ``<dialog>`` opened with ``showModal()`` makes
+ * everything outside it inert, the layer included; re-raising does not lift
+ * that. Steps advanced by the app's own events still work, the overlay's
+ * buttons do not until the dialog closes.
+ */
+import type { DomAdapter } from './dom.js';
+export declare function isLayerOpen(el: HTMLElement): boolean;
+export declare function showLayer(el: HTMLElement, dom: DomAdapter): void;
+/** Move the layer to the top of the top layer, keeping the app's focus where it was. */
+export declare function raiseLayer(el: HTMLElement, dom: DomAdapter): void;

package/dist/types/tour/loader.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Loads a tour: the manifest(s), then the tour file for the best locale.
+ *
+ * Two manifests can be configured. ``fallbackManifest`` is the copy bundled
+ * with the app (same origin only). ``manifest`` may point at a remote guide
+ * site and may contain ``{buildId}``, filled with the app's build id — the
+ * host's ``buildId`` property, else the bundled manifest's — so remote mode
+ * only ever fetches the tours of the app's own build. The remote copy is
+ * tried first and the bundled copy is the fallback; a remote failure is only
+ * logged.
+ *
+ * Cross-origin requests send no credentials, refuse redirects, and pass the
+ * bundled manifest's SRI hash when both copies are the same build, so a
+ * tampered remote file is rejected by the browser. Every body is read with a
+ * byte cap and an HTML sniff (an SPA answering a missing JSON file with its
+ * index page is a load failure, not bad data). Nothing a cross-origin
+ * manifest says widens what the bundled one allows: when the bundled manifest
+ * is for the same build, any other manifest (remote, or a same-origin proxy)
+ * only locates files — the tour, the locale and the SRI hash all come from the
+ * bundle, so a tour, locale or case variant the bundle does not pin is never
+ * fetched from it.
+ */
+import type { TourSourceKind } from './engine.js';
+import { type FailReason, type Issue, type Result, type TourFile, type TourManifest } from './validate.js';
+export type TourSource = (tourId: string, locale: string, ctx: {
+    buildId: string;
+    manifestUrl: string;
+}) => Promise<string | Response | object> | string | Response | object;
+export interface LoaderConfig {
+    manifest: string;
+    fallbackManifest: string;
+    buildId: string;
+    /** The locale asked for (host ``locale``, else the page's ``lang``). */
+    locale: string;
+    /** The host's ``guide-origin``: the only origin trusted without a manifest's say-so. */
+    guideOrigin: string;
+    source?: TourSource | null;
+    fetch?: typeof fetch;
+    origin?: string;
+    baseURI?: string;
+    timeoutMs?: number;
+    /** Manifests per resolved URL, kept by the host for the page's lifetime. */
+    cache?: Map<string, Promise<ManifestLoad>>;
+}
+export interface LoadOk {
+    ok: true;
+    manifest: TourManifest;
+    manifestUrl: string;
+    tour: TourFile;
+    locale: string;
+    source: TourSourceKind;
+    testIdAttribute: string;
+    guideOrigin: string | null;
+}
+export interface LoadErr {
+    ok: false;
+    reason: FailReason;
+    message: string;
+    issues?: Issue[];
+}
+export type ManifestLoad = (Result<TourManifest> & {
+    url: string;
+}) | (LoadErr & {
+    url: string;
+});
+/** Exact tag, then its base language, then the manifest's default, then the first file. */
+export declare function pickLocale(available: readonly string[], requested: string, fallback: string): string;
+/** The body as text, refusing more than ``cap`` bytes and invalid UTF-8. */
+export declare function readCapped(res: Response, cap: number): Promise<string>;
+export declare function loadTour(cfg: LoaderConfig, tourId: string): Promise<LoadOk | LoadErr>;

package/dist/types/tour/resolver.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Test-id resolution: ``[data-testid="<id>"]`` (the manifest's attribute)
+ * against the document — light DOM only — skipping the overlay itself, first
+ * *visible* match wins.
+ *
+ * Waiting is event-driven and only runs while the tour needs an element: a
+ * document MutationObserver (filtered to attributes that can change
+ * visibility, coalesced to one check per frame) plus a slow poll for changes
+ * no mutation reports (a stylesheet swap, a CSS transition finishing). Time
+ * spent in a background tab does not count against the deadline.
+ */
+import type { DomAdapter } from './dom.js';
+export interface WaitRequest {
+    ids: readonly string[];
+    /** Milliseconds to wait, or null for no deadline. */
+    timeoutMs: number | null;
+    onFound(found: Map<string, Element>): void;
+    /** Called with the first id still missing. */
+    onTimeout(missing: string): void;
+}
+export interface Resolver {
+    find(id: string): Element | null;
+    /** Start waiting; returns the cancel function. */
+    wait(req: WaitRequest): () => void;
+}
+export declare function createResolver(opts: {
+    attr: string;
+    host: Element;
+    dom: DomAdapter;
+}): Resolver;

package/dist/types/tour/routes.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Entry routes: match the current location against a tour's ``entry.route``
+ * (``/invoices/:invoiceId``), fill its parameters, and translate between app
+ * paths (relative to ``<base href>``) and document paths.
+ *
+ * The compiler strips the app's full URL (path included), so routes are
+ * base-relative; an app served under ``/app/`` has documents at
+ * ``/app/invoices`` for the route ``/invoices``. Both forms of the current
+ * path are tried, so an app without a base element works either way.
+ */
+export type RouteParams = Record<string, string>;
+/** Parameters of ``path`` under ``pattern``, or null when it does not match. */
+export declare function matchRoute(pattern: string, path: string): RouteParams | null;
+/** The route's names, in order (``/a/:x/b/:y`` -> ``['x', 'y']``). */
+export declare function routeParams(pattern: string): string[];
+/** ``pattern`` with its parameters filled (URI-encoded), or the names missing a value. */
+export declare function buildRoute(pattern: string, params: Record<string, unknown>): {
+    path: string;
+} | {
+    missing: string[];
+};
+/** The document's base path (``/`` or ``/app/``); ``/`` when the base is cross-origin. */
+export declare function basePath(baseURI: string, origin: string): string;
+/** ``/app/invoices`` under base ``/app/`` -> ``/invoices``; paths outside the base are unchanged. */
+export declare function toAppPath(documentPath: string, base: string): string;
+/** ``/invoices`` under base ``/app/`` -> ``/app/invoices``. */
+export declare function toDocumentPath(appPath: string, base: string): string;
+/**
+ * A link target the tour may follow in the same tab: a site-relative path —
+ * not protocol-relative (``//host``, ``/\host``), no backslash, whitespace or
+ * control characters.
+ */
+export declare function isSafeRelativeUrl(url: string): boolean;
+/**
+ * The same-tab href for a link in step text, or null. The URL is normalised
+ * first and the *result* checked: dot segments (``/.//host``, ``/a/..//host``,
+ * ``/%2e%2e//host``) collapse into a protocol-relative ``//host``, which the raw
+ * string never looked like.
+ */
+export declare function linkHref(url: string, base: string, origin: string): string | null;

package/dist/types/tour/signature.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Readers for the ``input`` and ``change`` advance kinds.
+ *
+ * ``valueSignature`` summarises everything a "pick a value" widget can change:
+ * native controls inside the target, ARIA state, and the visible label. A
+ * component library that sets a value programmatically fires no ``change``
+ * event (PrimeNG's select does exactly that), so the overlay compares
+ * signatures instead of listening for the event.
+ */
+export declare function valueSignature(target: Element): string;
+/** True while the target, or anything in it, reports an open popup (a dropdown in use). */
+export declare function isExpanded(target: Element): boolean;
+/** The value an ``input`` step watches: the target's own, else its first field. */
+export declare function readFieldValue(target: Element): string;
+/** A select-like widget, whose popup the bubble should leave room for (placed on top). */
+export declare function isComboboxLike(target: Element): boolean;

package/dist/types/tour/storage.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The resume record: which step of which tour is running, kept in
+ * ``sessionStorage`` so a full page load (a classic form post, a link the app
+ * does not route) picks the tour up where it was. Per tab by design.
+ *
+ * Every access is wrapped: storage throws in private modes and sandboxed
+ * frames, and a tour must keep working without it.
+ */
+export declare const RESUME_TTL_MS: number;
+export interface ResumeRecord {
+    v: 1;
+    tourId: string;
+    stepId: string;
+    locale: string;
+    params: Record<string, string>;
+    buildId: string;
+    /** The manifest URL(s) the record was made with; another host config ignores it. */
+    manifestKey: string;
+    savedAt: number;
+}
+export declare function writeResume(record: ResumeRecord): void;
+export declare function clearResume(): void;
+/**
+ * The stored record when it is well formed, fresh and made for ``manifestKey``.
+ * A malformed or expired record is removed; one made by another host
+ * configuration is left for that host.
+ */
+export declare function readResume(manifestKey: string, now: number): ResumeRecord | null;

package/dist/types/tour/strings.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The overlay's chrome strings. They resolve against the *loaded tour file's*
+ * locale, never the page's, so the buttons and the step text are always in
+ * one language. ``next`` and ``progress`` are the guide player's words
+ * (``ui/strings.ts``); a host overrides any key per locale with ``strings``.
+ *
+ * The ``instruction*`` keys are the generic hint a step shows when its
+ * scenario authored no text for that locale (the compiler warns about each).
+ */
+import type { AdvanceKind } from './contract.js';
+export interface TourStrings {
+    next: string;
+    /** Placeholders: ``{current}`` and ``{total}``. */
+    progress: string;
+    /** The primary button on the last step. */
+    done: string;
+    close: string;
+    skipStep: string;
+    endTour: string;
+    resume: string;
+    paused: string;
+    dialogLabel: string;
+    openGuide: string;
+    notFoundTitle: string;
+    notFoundBody: string;
+    instructionClick: string;
+    instructionInput: string;
+    instructionChange: string;
+    instructionVisible: string;
+    instructionManual: string;
+}
+export type TourStringOverrides = Partial<Record<string, Partial<TourStrings>>>;
+export declare const DEFAULT_TOUR_STRINGS: Record<string, TourStrings>;
+export declare function resolveTourStrings(contentLocale: string, overrides?: TourStringOverrides): TourStrings;
+/**
+ * Writing direction of a locale tag: a script subtag decides (``az-Arab``,
+ * ``sd-Deva``), else the language. Set on the overlay with ``lang``, so a tour
+ * shown in another language than the page is read and laid out as its own.
+ */
+export declare function textDir(tag: string): 'rtl' | 'ltr';
+/** The generic hint for a step without authored text. */
+export declare function instructionFor(kind: AdvanceKind, strings: TourStrings): string;

package/dist/types/tour/styles.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Overlay styles. Theming goes through public ``--steppy-*`` custom
+ * properties, read into private ``--_pw-*`` ones on ``:host`` and never
+ * declared themselves — so a page sets them on ``:root`` or on the element.
+ * Geometry comes from properties the tracker writes through CSSOM.
+ *
+ * Defaults meet WCAG AA (guard: ``test/tour/small-modules.test.ts``). The bubble
+ * inherits the app's font unless ``--steppy-font-family`` is set. The
+ * bubble's inner layout uses logical properties, so it mirrors under the
+ * layer's ``dir`` (an Arabic or Hebrew tour); its placement around the target
+ * stays physical.
+ */
+export declare const tourStyles: import("lit").CSSResult;

package/dist/types/tour/templates.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The overlay's DOM. Data is only ever bound as text or attribute values
+ * (never ``style=``, never HTML), and the UI never carries the app's test-id
+ * attribute, so app locators cannot match it.
+ *
+ * DOM contract (the CI replay and the docs rely on it): the bubble is
+ * ``section[part~="bubble"][role="dialog"]`` with ``data-tour-id``,
+ * ``data-step-id``, ``data-state`` (``shown`` | ``fallback``) and
+ * ``data-advance``; Next is ``part="button next primary"`` on input and manual
+ * steps and ``"button next secondary"`` on change steps, absent on click and
+ * visible steps; the fallback has ``skip`` and ``end``; the pill holds
+ * ``resume`` and ``close``.
+ */
+import { type TemplateResult } from 'lit';
+import { type LinkPolicy } from '../ui/markdown.js';
+import type { TourStrings } from './strings.js';
+import type { TourStep } from './validate.js';
+export interface ViewModel {
+    mode: 'bubble' | 'pill' | 'none';
+    /** The tour file's language and direction, set on the layer (the page's may differ). */
+    lang: string;
+    dir: 'ltr' | 'rtl';
+    tourId: string;
+    step: TourStep;
+    state: 'shown' | 'fallback';
+    /** Spotlight drawn (an anchored step that is showing). */
+    anchored: boolean;
+    position: {
+        index: number;
+        total: number;
+    };
+    last: boolean;
+    nextEnabled: boolean;
+    guideUrl: string | null;
+    strings: TourStrings;
+    policy: LinkPolicy;
+    popover: boolean;
+}
+export interface Handlers {
+    press(e: Event): void;
+    next(e: MouseEvent): void;
+    skip(e: MouseEvent): void;
+    end(e: MouseEvent): void;
+    close(e: MouseEvent): void;
+    resume(e: MouseEvent): void;
+}
+export declare function renderLayer(v: ViewModel, h: Handlers): TemplateResult;