@touchcastllc/napster-companion-api-dev 1.0.0-alpha.85 → 1.5.0-alpha.0

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,9 +314,15 @@ 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;
     /**
@@ -321,11 +339,43 @@ export interface PersistenceOptions {
     };
     /** 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.85",
+  "version": "1.5.0-alpha.0",
   "keywords": [
     "napster",
     "companion-api",