@steppy/player 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,45 @@
+/**
+ * Keeps the spotlight on the target and the bubble next to it while a step is
+ * shown. Geometry is written through CSSOM custom properties only (no
+ * ``style=`` attributes, which a strict CSP blocks).
+ *
+ * Driven by capture-phase scroll (which catches scrolling ancestors), resize,
+ * the visual viewport, ResizeObserver and a slow poll; ``notify`` coalesces
+ * them into one placement per frame. A target that got detached or hidden is
+ * re-found by id first; only when that fails is the step reported lost.
+ *
+ * Invariant: the bubble never covers the spotlight when a side has room for
+ * it; otherwise it becomes a sheet at the top or bottom of the viewport, away
+ * from the target's centre (where a click lands). A step with nothing to point
+ * at is centred, unless that would cover an open app dialog: such a step is
+ * usually about the dialog (a confirmation), so it becomes a sheet instead.
+ */
+import { type Rect, type TooltipSide } from '../ui/placement.js';
+import type { DomAdapter } from './dom.js';
+export declare const SPOT_PAD = 6;
+export declare const GAP = 10;
+export declare const MARGIN = 8;
+export declare const SHEET_BELOW = 640;
+export interface TrackerOptions {
+    dom: DomAdapter;
+    layer: () => HTMLElement | null;
+    bubble: () => HTMLElement | null;
+    /** The current target, or null for a centred (targetless) step. */
+    target: () => Element | null;
+    /** Re-find the target by id after it was detached or hidden. */
+    refind: () => Element | null;
+    preferred: () => TooltipSide | 'auto';
+    /** A rect the bubble should not cover when it has a choice (the next step's target). */
+    avoid: () => Rect | null;
+    /** The app's open dialogs, which a centred bubble moves off. */
+    dialogs?: () => Rect[];
+    onLost: () => void;
+    /** The bubble was placed (it is visible from now on, so it can take focus). */
+    onPlaced?: () => void;
+}
+export interface Tracker {
+    start(): void;
+    stop(): void;
+    notify(): void;
+}
+export declare function createTracker(o: TrackerOptions): Tracker;

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

@@ -0,0 +1,52 @@
+/**
+ * Turns what the user does *in the app* into engine events: document-level
+ * capture listeners that never stop or alter the app's own events.
+ *
+ * - A click whose path holds the current step's test-id advances a ``click``
+ *   step; a click on a *later* step's target jumps there (performed when that
+ *   step is itself a click step). The resume record is written synchronously,
+ *   before any navigation the click may cause; the engine is told on the next
+ *   task so the app's handlers run first.
+ * - ``input`` / ``change`` on an ``input`` step's target enable Next / commit.
+ * - Any interaction outside the overlay arms a ``change`` step's watcher.
+ * - Escape dismisses the tour unless the app is using it (a dialog, an open
+ *   popup, ``preventDefault``, an IME composition).
+ *
+ * Events whose path goes through the overlay are its own UI and are ignored.
+ * Untrusted (scripted) events count like trusted ones: the CI replay clicks
+ * with synthetic events.
+ */
+import type { EngineEvent, EngineState } from './engine.js';
+export interface TriggerContext {
+    host: HTMLElement;
+    attr: string;
+    state(): EngineState;
+    dispatch(e: EngineEvent): void;
+    /** The current step's resolved target. */
+    target(): Element | null;
+    /** Called synchronously when a click advances or jumps: persist the next step. */
+    persistAhead(fromIndex: number): void;
+    /** Any interaction outside the overlay (arms ``change`` watchers). */
+    interacted(): void;
+    /** A ``change`` event or a document click: re-check a ``change`` step. */
+    tick(): void;
+    defer(cb: () => void): void;
+}
+/** An app dialog: Escape inside one is the app's, and a centred bubble moves off an open one. */
+export declare const APP_DIALOG = "dialog,[role=dialog],[role=alertdialog],[aria-modal=\"true\"]";
+export declare function attachTriggers(ctx: TriggerContext): () => void;
+/**
+ * Watches a ``change`` step: the value signature is sampled until the user
+ * first interacts (so a label the app fills in asynchronously is not taken
+ * for a change), then any difference — ignored while a popup is open, since
+ * the signature of an open dropdown is not a choice — advances the step.
+ */
+export declare function watchChange(target: Element, signature: (el: Element) => string, onChange: () => void, schedule: {
+    raf(cb: () => void): number;
+    setInterval(cb: () => void, ms: number): number;
+    clearInterval(id: number): void;
+}): {
+    arm(): void;
+    tick(): void;
+    stop(): void;
+};

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

@@ -0,0 +1,82 @@
+/**
+ * The overlay's security boundary: every manifest and tour file is validated
+ * here before anything renders, and a file that breaks any rule is rejected
+ * whole (spec 7.1). Hand-written rather than zod so the tour bundle stays small.
+ *
+ * Only known keys are copied into fresh objects — unknown keys are ignored, so
+ * a newer producer's extra field never breaks an older overlay — but unknown
+ * enum values and an unknown schema major are rejected: a tour file is data,
+ * never code. The rules mirror ``src/steppy/contracts/tours.py`` (the
+ * producer's self-check); ``contracts/fixtures/tours/cases.json`` runs both
+ * sides over the same cases.
+ */
+import { type AdvanceKind, type Placement } from './contract.js';
+export interface TourEntry {
+    readonly route: string;
+}
+export interface ManifestTour {
+    readonly id: string;
+    readonly role: string;
+    readonly title: Readonly<Record<string, string>>;
+    readonly entry: TourEntry | null;
+    readonly steps: number;
+    readonly files: Readonly<Record<string, string>>;
+    readonly integrity: Readonly<Record<string, string>>;
+}
+export interface TourManifest {
+    readonly buildId: string;
+    readonly defaultLocale: string;
+    readonly locales: readonly string[];
+    readonly testIdAttribute: string;
+    readonly guideOrigin: string | null;
+    readonly layouts: Readonly<Record<string, string>> | null;
+    readonly tours: readonly ManifestTour[];
+}
+export interface TourStep {
+    readonly id: string;
+    readonly target: string | null;
+    readonly advance: AdvanceKind;
+    readonly waitFor: string | null;
+    readonly title: string | null;
+    readonly text: string | null;
+    readonly placement: Placement | null;
+    readonly layouts: readonly string[] | null;
+}
+export interface TourFile {
+    readonly id: string;
+    readonly buildId: string;
+    readonly locale: string;
+    readonly title: string;
+    readonly guideUrl: string | null;
+    readonly entry: TourEntry | null;
+    readonly steps: readonly TourStep[];
+}
+export interface Issue {
+    path: string;
+    message: string;
+}
+export type FailReason = 'invalid-data' | 'schema-unsupported' | 'load-failed';
+export type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: FailReason;
+    issues: Issue[];
+};
+/** A same-origin, base-relative route pattern (``/invoices/:invoiceId``). */
+export declare function isRoutePattern(value: unknown): value is string;
+export declare function isBuildId(value: unknown): value is string;
+/** ``scheme://host[:port]`` of an absolute http(s) URL without credentials, else null. */
+export declare function httpOrigin(value: string): string | null;
+/** Parse JSON text; an HTML body (an SPA fallback page) is a load failure, not bad data. */
+export declare function parseJson(text: string): Result<unknown>;
+export declare function validateManifest(raw: unknown): Result<TourManifest>;
+export interface TourContext {
+    manifest: TourManifest;
+    entry: ManifestTour;
+    locale: string;
+    /** The guide origin this overlay trusts for ``guideUrl`` (null: none). */
+    guideOrigin: string | null;
+}
+export declare function validateTour(raw: unknown, ctx: TourContext): Result<TourFile>;

package/dist/types/ui/markdown.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Inline-markdown renderer shared by the guide player and the in-app tour
+ * overlay.
+ *
+ * Mirrors the inline subset of the server-side ``markdown-it`` ``renderInline``
+ * filter (``src/steppy/guide.py``, configured ``{html:false, breaks:true,
+ * linkify:true}``) used by the step-by-step guide, so the interactive player
+ * renders the same content the static guide does:
+ *
+ *   - **bold** / __bold__ , *italic* / _italic_ (recursive — emphasis nests)
+ *   - `inline code`
+ *   - [label](url) links — label is parsed recursively
+ *   - autolinked bare URLs (``https://…`` / ``www.…``) and emails (linkify)
+ *   - hard line breaks: every ``\n`` becomes ``<br>`` (``breaks:true``)
+ *
+ * The manifest carries raw text (it is reused for ``alt``/``aria-label``
+ * attributes, where HTML must not appear), so emphasis is rendered here, on the
+ * client, only at the visible display sites.
+ *
+ * Returns an array of literal-string + Lit ``TemplateResult`` parts, meant to be
+ * interpolated into an existing parent element (``${renderInlineMarkdown(text)}``,
+ * the same shape as ``${items.map(...)}``). Literal text and ``href`` values stay
+ * auto-escaped by Lit, and which link URLs become links is decided by a
+ * ``LinkPolicy`` — so it is XSS-safe by construction, with no ``unsafeHTML``.
+ *
+ * Link policies: the guide keeps its historical set (http/https/mailto, a
+ * site-relative path, an anchor) minus protocol-relative ``//host`` and
+ * ``/\host``, which browsers resolve to another origin. The tour overlay passes
+ * a stricter policy of its own (same-origin routes and the guide origin only,
+ * no autolinks). A URL the policy refuses leaves the whole ``[label](url)``
+ * literal, exactly as an unmatched link always rendered.
+ *
+ * Scope is intentionally inline-only (no block constructs — ``renderInline`` does
+ * not render lists/headings/blockquotes either, so there is no parity gap). The
+ * regex emphasis rule is not markdown-it's full delimiter-run algorithm, so a few
+ * pathological mixed-nesting cases (e.g. *italic wrapping **bold***) are not
+ * matched; the common cases — bold-containing-italic, adjacent emphasis, links
+ * with emphasised labels — all work.
+ */
+import { type TemplateResult } from 'lit';
+export type MarkdownNode = TemplateResult | string;
+/** What a ``[label](url)`` becomes: a new-tab link, or a same-tab one the host routes. */
+export type LinkTarget = {
+    kind: 'external';
+    href: string;
+} | {
+    kind: 'internal';
+    href: string;
+    onActivate: (event: MouseEvent) => void;
+};
+export interface LinkPolicy {
+    /** The link for ``url``, or ``null`` to leave the markdown literal. */
+    link(url: string): LinkTarget | null;
+    /** Whether bare URLs and e-mail addresses are turned into links (linkify). */
+    autolink: boolean;
+}
+export declare const GUIDE_LINK_POLICY: LinkPolicy;
+export declare function renderInlineMarkdown(src: string, policy?: LinkPolicy): MarkdownNode[];

package/dist/types/ui/names.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Product-derived names, the TypeScript twin of ``src/steppy/naming.py``.
+ *
+ * One literal per line on purpose: ``tests/test_tour_contract_sync.py`` reads
+ * this file with regular expressions and fails when a value drifts from the
+ * Python side. A future rename edits both files.
+ */
+export declare const PRODUCT = "steppy";
+export declare const TOUR_HOST_TAG = "steppy-tour-host";
+export declare const TOURS_MANIFEST_KIND = "steppy-tours-manifest";
+export declare const TOUR_FILE_KIND = "steppy-tour";
+export declare const TOURS_MANIFEST_FILENAME = "tours.manifest.json";
+export declare const TOURS_KILL_SWITCH_GLOBAL = "__STEPPY_TOURS_DISABLED__";
+export declare const TOUR_RESUME_STORAGE_KEY = "steppy:tour";
+/** ``globalThis[Symbol.for(...)]`` marks the host instance that owns the running tour. */
+export declare const TOUR_ACTIVE_SYMBOL_KEY = "steppy.tour.active";
+/** Prefix of every public CSS custom property (``--steppy-accent`` ...). */
+export declare const CSS_TOKEN_PREFIX = "--steppy-";

package/dist/types/ui/placement.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Bubble placement next to a highlighted rect, shared by the guide player's
+ * tooltip and the in-app tour popover. Pure math, no DOM.
+ *
+ * Called without options, ``placeTooltip`` is the guide's historical rule,
+ * byte for byte (guard: ``test/ui/placement.test.ts`` against a frozen copy).
+ * With options it honours a preferred side, keeps a margin from the stage
+ * edges, steers clear of rects to ``avoid`` and reports whether the bubble
+ * could not avoid covering the hotspot.
+ *
+ * ``Rect`` is declared here rather than imported from ``cursor/`` so the tour's
+ * type declarations do not pull the cursor animator in.
+ */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type TooltipSide = 'top' | 'bottom' | 'left' | 'right';
+export interface TooltipPlacement {
+    side: TooltipSide;
+    /** Top-left offset, in display space, of the tooltip's bounding box. */
+    x: number;
+    y: number;
+    /** Only with options: true when no side fits and the bubble covers the hotspot. */
+    overlaps?: boolean;
+}
+export interface PlaceOptions {
+    /** Side to try first; ``auto`` (the default) uses the historical bias. */
+    preferred?: TooltipSide | 'auto';
+    /** Distance kept from every stage edge (default 0). */
+    margin?: number;
+    /** Rects a fitting side should not cover (e.g. the next step's target). */
+    avoid?: readonly Rect[];
+}
+type Size = {
+    width: number;
+    height: number;
+};
+/**
+ * Decide which side of the hotspot the tooltip should sit on. Picks the side
+ * with the most room, then biases toward ``bottom`` for ties (matches
+ * Guideflow's default).
+ *
+ * All inputs and outputs are in display space (the same coordinate frame as
+ * the hotspot rect).
+ */
+export declare function placeTooltip(hotspot: Rect, tooltip: Size, stage: Size, gap?: number, opts?: PlaceOptions): TooltipPlacement;
+/** True when ``a`` and ``b`` share a positive area. */
+export declare function intersects(a: Rect, b: Rect): boolean;
+/** The overlap of ``a`` and ``b``, or ``null`` when they share no area. */
+export declare function intersect(a: Rect, b: Rect): Rect | null;
+/** The smallest rect containing both. */
+export declare function union(a: Rect, b: Rect): Rect;
+/** ``r`` grown by ``pad`` on every side. */
+export declare function inflate(r: Rect, pad: number): Rect;
+export declare function containsPoint(r: Rect, x: number, y: number): boolean;
+export {};

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

@@ -0,0 +1,31 @@
+/**
+ * The string mechanism both players share: placeholder formatting, locale
+ * lookup with a base-language rung, and the chrome vocabulary they have in
+ * common (so "Next" reads the same in the guide and in the tour).
+ */
+/** Replace ``{name}`` placeholders; unknown names stay as written. */
+export declare function format(template: string, vars: Record<string, string | number>): string;
+/**
+ * Bare language subtag, lowercased (``fr-BE`` -> ``fr``). Mirrors Python's
+ * ``steppy.locales.base_language``: lenient, never validates.
+ */
+export declare function baseLanguage(tag: string): string;
+/**
+ * The key of ``keys`` to use for ``requested``: an exact match (case- and
+ * ``_``/``-``-insensitive) first, then the requested tag's base language. The
+ * query is only ever truncated, never widened — ``fr`` does not match ``fr-BE``.
+ */
+export declare function lookupLocale(keys: Iterable<string>, requested: string | null | undefined): string | null;
+/**
+ * Bundled ``defaults`` for ``locale`` (else ``fallback``), with the host's
+ * sparse per-locale ``overrides`` merged on top. Without an override the
+ * bundled object itself is returned.
+ */
+export declare function resolveStrings<T extends object>(defaults: Record<string, T>, locale: string, overrides?: Partial<Record<string, Partial<T>>>, fallback?: string): T;
+export interface ChromeStrings {
+    next: string;
+    /** Placeholders: ``{current}`` and ``{total}``. */
+    progress: string;
+}
+/** Chrome words the guide and the tour share, per bundled locale. */
+export declare const CHROME_STRINGS: Record<'en' | 'fr' | 'nl' | 'de', ChromeStrings>;

package/dist/types/ui/tokens.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Default look values shared by the guide player and the in-app tour overlay.
+ *
+ * Constants only, never data: they are interpolated into the ``css`` tagged
+ * templates with ``cssValue`` (Lit's ``unsafeCSS``), which concatenates the
+ * value verbatim — ``baseStyles.cssText`` is byte-identical to the literal
+ * stylesheet it replaced (guard: ``test/ui/guide-styles-stable.test.ts``).
+ */
+import { type CSSResult } from 'lit';
+/** The guide's palette (``--steppy-*`` defaults in ``templates/base-styles.ts``). */
+export declare const PALETTE: {
+    readonly bg: "#f4f1ea";
+    readonly surface: "#fbf9f4";
+    readonly chromeBg: "#efece3";
+    readonly fg: "#1f1d1a";
+    readonly muted: "#8a857c";
+    readonly border: "#e1ddd1";
+    readonly accent: "#d24f2c";
+    readonly accentWeak: "rgba(210, 79, 44, 0.35)";
+    readonly success: "#3a7d44";
+};
+/** System font stacks only: offline, no CDN. */
+export declare const FONTS: {
+    readonly serif: "ui-serif, Georgia, 'Times New Roman', serif";
+    readonly sans: "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif";
+    readonly mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
+};
+/** The dark bubble both players draw next to a target (guide tooltip, tour popover). */
+export declare const BUBBLE_LOOK: {
+    readonly padding: "8px 12px";
+    readonly radius: "6px";
+    readonly maxWidth: "280px";
+    readonly fontSize: "14px";
+    readonly lineHeight: "1.4";
+    readonly shadow: "0 4px 12px rgba(0, 0, 0, 0.2)";
+};
+export declare const BUTTON_LOOK: {
+    readonly radius: "4px";
+    readonly padding: "4px 10px";
+};
+/**
+ * Tour overlay defaults. The accent differs from the guide's on purpose:
+ * ``#d24f2c`` measures 4.29:1 against white text, below WCAG AA for the
+ * overlay's buttons; ``#a8410e`` measures 6.13:1 (guard: ``test/tour/small-modules.test.ts``).
+ */
+export declare const TOUR_DEFAULTS: {
+    readonly bubbleBg: "#1f1d1a";
+    readonly bubbleFg: "#fbf9f4";
+    readonly muted: "#c9c5bd";
+    readonly accent: "#a8410e";
+    readonly accentFg: "#ffffff";
+    readonly focus: "#f09a6a";
+    readonly scrim: "rgba(31, 29, 26, 0.45)";
+    readonly radius: "6px";
+};
+/** A token value inside a ``css`` template (inserted verbatim, never data). */
+export declare const cssValue: (value: string | number) => CSSResult;

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@steppy/player",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Steppy players — the interactive guide (Lit web component + manifest validator) and the in-app tour overlay",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Steppy-dev/steppy.git",
+    "directory": "packages/player"
+  },
+  "type": "module",
+  "main": "./dist/steppy-player.js",
+  "module": "./dist/steppy-player.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/steppy-player.js"
+    },
+    "./schema.json": "./schema/guide.schema.json",
+    "./tour": {
+      "types": "./dist/types/tour/index.d.ts",
+      "default": "./dist/steppy-tour.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "tour": [
+        "./dist/types/tour/index.d.ts"
+      ]
+    }
+  },
+  "sideEffects": true,
+  "files": [
+    "dist",
+    "schema",
+    "LICENSE",
+    "NOTICE",
+    "THIRD_PARTY_LICENSES.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && vite build -c vite.iife.config.ts && vite build -c vite.video.config.ts && npm run build:tour && npm run build:schema",
+    "build:esm": "vite build",
+    "build:iife": "vite build -c vite.iife.config.ts",
+    "build:video": "vite build -c vite.video.config.ts",
+    "build:tour": "vite build -c vite.tour.config.ts && npm run build:types",
+    "build:schema": "tsx scripts/emit-json-schema.ts",
+    "size:tour": "tsx scripts/check-tour-size.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "build:types": "tsc -p tsconfig.types.json",
+    "check:pack": "tsx scripts/check-pack.ts",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "lit": "^3.2.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "happy-dom": "^15.7.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vite": "^5.4.0",
+    "vitest": "^2.1.0",
+    "zod-to-json-schema": "^3.23.0"
+  }
+}

package/schema/README.md

@@ -0,0 +1,19 @@
+# Generated JSON Schema
+
+`guide.schema.json` here is generated from the Zod schema at
+[../src/manifest/schema.ts](../src/manifest/schema.ts).
+
+Regenerate with:
+
+```
+npm run build:schema
+```
+
+The Zod schema is the source of truth. The JSON Schema is shipped for external
+tooling (IDE completion, validation in downstream projects, docs). The runtime
+validator in `parseManifest()` uses the Zod schema directly.
+
+Cross-field rules (e.g. `defaultLocale` must appear in `locales`) live in a
+`superRefine` block on the Zod schema and are **not** emitted into the JSON
+Schema — JSON Schema lacks the expressiveness for them. Treat JSON Schema as
+structural validation; `parseManifest()` is the authority.