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

package/lib/types/index.d.ts

@@ -326,17 +326,42 @@ export interface PersistenceOptions {
      */
     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;
     /**

package/package.json

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