@touchcastllc/napster-companion-api-dev 1.0.0-alpha.86 → 1.5.0-alpha.1

package/lib/persistence/index.d.ts

@@ -22,6 +22,17 @@ export declare const PERSIST_NAVIGATE_EVENT = "napster:persist:navigate";
  * off it, so the marker is defined in exactly one place.
  */
 export declare const SITE_FRAME_CLASS = "np_site-frame";
+/**
+ * Browsing-context name of the site frame. Form submissions are routed into the frame by
+ * pointing `form.target` here, letting the BROWSER perform the submit (works for POST,
+ * which no URL-based re-navigation could replay).
+ */
+export declare const SITE_FRAME_NAME = "np_site_frame";
+/**
+ * Class of the navigation progress bar shown while a wrapped page loads. Styled in
+ * `Persistence.css`; exists because browser chrome ignores an in-iframe navigation.
+ */
+export declare const SITE_PROGRESS_CLASS = "np_site-progress";
 /**
  * True when the current window is running INSIDE our own persistence site frame (the
  * `.np_site-frame` iframe) rather than the top document or a third-party embed. Both entry

package/lib/types/index.d.ts

@@ -292,6 +292,18 @@ export interface avatarStyleConfig {
  * Allows both string and number values for CSS properties.
  */
 export type StyleObject = Partial<CSSStyleDeclaration>;
+/**
+ * Styling for the navigation progress bar — see
+ * {@link PersistenceOptions.navigationProgress}. Both map onto CSS custom properties,
+ * so a stylesheet can override them instead
+ * (`--np-persist-progress-color` / `--np-persist-progress-height`).
+ */
+export interface NavigationProgressOptions {
+    /** Any CSS colour. Default: `"#be369d"`. */
+    color?: string;
+    /** Any CSS length. Default: `"3px"`. */
+    height?: string;
+}
 /**
  * Cross-page persistence options. Works with BOTH entry points — `init` and
  * `initWithButton` share the same persistence engine.
@@ -302,30 +314,93 @@ export interface PersistenceOptions {
     /**
      * Defer the iframe wrap until the user first navigates. The landing page stays
      * fully native — no iframe — and the wrap happens on the first allowed link click.
-     * Default: `false` (eager wrap on connect). Off by default because on-navigate only
-     * catches anchor clicks: a programmatic redirect on the landing page would fall
-     * through and end the session.
+     * **Default: `false`** (eager wrap on connect).
+     *
+     * Eager costs one reload of the current page up front, but is unconditional: once
+     * wrapped, EVERY navigation happens inside the frame. Deferring avoids that reload for
+     * the many sessions that never leave the landing page, but it has to intercept the
+     * navigation to work, and interception can be defeated — by a programmatic redirect
+     * (`location.href = …`), or by a site handler calling `stopPropagation()` on the click.
+     * Either one ends the session. Sites that navigate from JS should dispatch
+     * {@link PERSIST_NAVIGATE_EVENT}, which the engine routes through the wrap.
      */
     iframeOnNavigate?: boolean;
     /**
-     * URLs/domains excluded from persistence: instead of loading inside the iframe they
-     * open as a normal top-level navigation (which ends the session). Use for pages that
-     * can't be framed (auth / SSO) or shouldn't be (checkout, signout). Cross-origin
-     * links always open top-level by default, so this only matters for same-origin.
+     * Pages of YOUR OWN site that must not be framed: they open as a normal top-level
+     * navigation, which ends the session. Use for anything that breaks inside an iframe
+     * or shouldn't be wrapped — auth / SSO, checkout, sign-out.
+     *
+     * Same-origin only, and that is not a limitation: anything cross-origin already opens
+     * top-level unless you list it under {@link include}.
      */
     exclude?: {
-        /** Hostnames to exclude (exact host or a parent domain, e.g. `"napster.com"`). */
-        domains?: string[];
-        /** URLs to exclude: an absolute `"https://…"` (exact/prefix) or a same-origin path prefix. */
+        /** An absolute `"https://…"` (exact or prefix) or a same-origin path prefix (`"/checkout"`). */
         urls?: string[];
     };
+    /**
+     * Other people's domains that ARE allowed to load inside the site frame, so following
+     * a link to them keeps the session alive instead of ending it. Everything cross-origin
+     * breaks out by default; this is the exception list.
+     *
+     * ```ts
+     * include: { domains: ["docs.example.com", "partner.io"] }
+     * ```
+     *
+     * Matches the exact host or any subdomain of it. Only add a domain you control or have
+     * agreed with, and know what you give up — inside a cross-origin page the engine can
+     * see nothing:
+     *
+     * - the site must permit framing at all; one that sends `X-Frame-Options: DENY` or a
+     *   restrictive `frame-ancestors` shows a blank frame, and that cannot be detected;
+     * - links clicked in there are not intercepted, so the user can wander anywhere and
+     *   nothing brings them back;
+     * - the address bar stops following the frame, and back/forward stop syncing with it;
+     * - ending the session there cannot reload the page the user is on, so it unwraps to
+     *   the last page of your own site instead.
+     */
+    include?: {
+        /** Hostnames allowed inside the frame (exact host or a parent domain, e.g. `"example.com"`). */
+        domains?: string[];
+    };
     /** Value for the site iframe's `allow` attribute (Permissions Policy). Default: `"autoplay; clipboard-write"`. */
     iframeAllowAttribute?: string;
+    /**
+     * Show a thin progress bar at the top of the page while a page loads into the site
+     * frame. **Off by default** — opt in with `true`, or with an object to restyle it.
+     *
+     * Worth turning on because a navigation inside the iframe drives no browser chrome:
+     * no tab spinner, no reload-turns-into-stop. Without some indicator, a click the
+     * engine took over looks dead for the whole load. Covers navigation both before the
+     * wrap and inside the frame afterwards. Leave it off if the site already shows its
+     * own navigation indicator.
+     *
+     * ```ts
+     * navigationProgress: true                          // default styling
+     * navigationProgress: { color: "#00b3ff" }          // brand colour
+     * navigationProgress: { color: "#fff", height: "2px" }
+     * ```
+     */
+    navigationProgress?: boolean | NavigationProgressOptions;
     /**
      * While a persisted session is active, mirror the iframe's path into the address bar
      * and follow parent back/forward into the iframe. Same-origin only. Default: `true`.
      */
     syncHistory?: boolean;
+    /**
+     * Keep Back from leaving the persisted site while a session is live. Default: `true`.
+     * Requires {@link syncHistory} (the engine keys off the history entries it owns).
+     *
+     * Back/forward BETWEEN pages of the session keep working normally. Only the step that
+     * would leave the site is refused — that step unloads the top document, and with it
+     * the live session, mid-conversation. At that boundary Back does nothing.
+     *
+     * Note this is a back-button trap, and users do notice: repeated presses that appear
+     * stuck read as the site holding them hostage. Set to `false` to let Back leave (the
+     * session ends and the page unwraps normally), and prefer that on sites where exiting
+     * quickly matters more than keeping the session alive. It cannot trap everything
+     * either — a long-press on Back jumps several entries at once and leaves regardless.
+     */
+    trapBackNavigation?: boolean;
 }
 /**
  * Main configuration object passed to `init(token, config)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@touchcastllc/napster-companion-api-dev",
-  "version": "1.0.0-alpha.86",
+  "version": "1.5.0-alpha.1",
   "keywords": [
     "napster",
     "companion-api",