@driggsby/sdk 0.2.2 → 0.2.4

package/dist/driggsby-sdk.js

@@ -11,6 +11,10 @@ function isAllowedHostOrigin(origin, allowLocalHostOrigins) {
   if (EXACT_ALLOWED_HOST_ORIGINS.has(origin)) return true;
   return allowLocalHostOrigins && LOCAL_HOST_ORIGIN_PATTERN.test(origin);
 }
+var APP_ROUTE_PATTERN = /^#[A-Za-z0-9/\-._]{1,256}$/;
+function sanitizeAppRoute(value) {
+  return typeof value === "string" && APP_ROUTE_PATTERN.test(value) ? value : "";
+}
 function parseProtocolMessage(data) {
   if (typeof data !== "object" || data === null) return null;
   const record = data;
@@ -27,15 +31,17 @@ function parseProtocolMessage(data) {
     type,
     id: typeof record.id === "string" ? record.id : null,
     result: record.result,
-    errorMessage
+    errorMessage,
+    route: sanitizeAppRoute(record.route)
   };
 }
 var SdkCore = class {
   // Wired by the page entry: remove the standalone note, log tool errors,
-  // reload on a new deployed version.
+  // reload on a new deployed version, restore the host-remembered route.
   onHostReady = null;
   onToolError = null;
   onNewVersion = null;
+  onRestoreRoute = null;
   post;
   allowLocalHostOrigins;
   hostOrigin = null;
@@ -73,7 +79,7 @@ var SdkCore = class {
     const message = parseProtocolMessage(data);
     if (message === null) return;
     if (message.type === "hello") {
-      this.handleHello(origin);
+      this.handleHello(origin, message.route);
       return;
     }
     if (this.hostOrigin === null || origin !== this.hostOrigin) return;
@@ -85,13 +91,27 @@ var SdkCore = class {
       this.onNewVersion?.();
     }
   }
-  handleHello(origin) {
+  handleHello(origin, route) {
     if (this.hostOrigin !== null) return;
     if (!isAllowedHostOrigin(origin, this.allowLocalHostOrigins)) return;
     this.hostOrigin = origin;
     this.onHostReady?.();
+    if (route !== "") this.onRestoreRoute?.(route);
     this.requestAllWatches();
   }
+  // The app moved to a new in-page location; tell the pinned host so it
+  // can mirror the fragment into its own page URL. Anything unmirrorable —
+  // an empty hash (the app is back at its no-hash location) or a hash
+  // outside the strict shape (a query-bearing route, say) — is reported
+  // as the bare-"#" cleared sentinel: the host must forget rather than
+  // keep claiming a location the app already left, or a refresh or
+  // redeploy reload would yank the user to a stale page. Before the
+  // handshake there is nobody to tell.
+  reportRoute(hash) {
+    if (this.hostOrigin === null) return;
+    const route = sanitizeAppRoute(hash) || "#";
+    this.post({ protocol: PROTOCOL, type: "route", hash: route }, this.hostOrigin);
+  }
   handleResult(message) {
     const entry = message.id === null ? void 0 : this.watches.get(message.id);
     if (entry === void 0) return;
@@ -150,13 +170,23 @@ var core = new SdkCore((message, targetOrigin) => {
   // exactly the Driggsby console origin.
   allowLocalHostOrigins: isLocalAppHostname(window.location.hostname)
 });
-core.onHostReady = removeStandaloneNote;
 core.onNewVersion = () => {
   window.location.reload();
 };
 core.onToolError = (tool, message) => {
   console.error(`Driggsby: the ${tool} call didn't work \u2014 ${message}`);
 };
+core.onHostReady = () => {
+  removeStandaloneNote();
+  if (window.location.hash !== "") core.reportRoute(window.location.hash);
+};
+core.onRestoreRoute = (route) => {
+  if (window.location.hash === route) return;
+  window.location.replace((window.location.href.split("#")[0] ?? "") + route);
+};
+window.addEventListener("hashchange", () => {
+  core.reportRoute(window.location.hash);
+});
 window.addEventListener("message", (event) => {
   core.handleMessage(event.origin, event.source === window.parent, event.data);
 });

package/dist/sdk-core.d.ts

@@ -4,10 +4,12 @@ export declare function isLocalAppHostname(hostname: string): boolean;
 export declare function isAllowedHostOrigin(origin: string, allowLocalHostOrigins: boolean): boolean;
 export type WatchCallback = (result: unknown) => void;
 export type PostFunction = (message: Record<string, unknown>, targetOrigin: string) => void;
+export declare function sanitizeAppRoute(value: unknown): string;
 export declare class SdkCore {
     onHostReady: (() => void) | null;
     onToolError: ((tool: string, message: string) => void) | null;
     onNewVersion: (() => void) | null;
+    onRestoreRoute: ((route: string) => void) | null;
     private readonly post;
     private readonly allowLocalHostOrigins;
     private hostOrigin;
@@ -20,6 +22,7 @@ export declare class SdkCore {
     watch(tool: string, params: Record<string, unknown> | null | undefined, callback: WatchCallback): () => void;
     handleMessage(origin: string, fromParent: boolean, data: unknown): void;
     private handleHello;
+    reportRoute(hash: string): void;
     private handleResult;
     private requestAllWatches;
     private requestWatch;

package/dist/sdk-core.js

@@ -38,6 +38,15 @@ export function isAllowedHostOrigin(origin, allowLocalHostOrigins) {
         return true;
     return allowLocalHostOrigins && LOCAL_HOST_ORIGIN_PATTERN.test(origin);
 }
+// The app's in-page location, as a URL fragment. The host mirrors it into
+// its own page URL (so refresh and shared links restore it) and hands it
+// back in the hello after a reload. The shape is deliberately narrow — a
+// short, boring hash — and must stay identical to the host's sanitizer;
+// anything else normalizes to ''.
+const APP_ROUTE_PATTERN = /^#[A-Za-z0-9/\-._]{1,256}$/;
+export function sanitizeAppRoute(value) {
+    return typeof value === "string" && APP_ROUTE_PATTERN.test(value) ? value : "";
+}
 // Untrusted wire data -> a normalized message, or null when it is not ours.
 function parseProtocolMessage(data) {
     if (typeof data !== "object" || data === null)
@@ -59,14 +68,16 @@ function parseProtocolMessage(data) {
         id: typeof record.id === "string" ? record.id : null,
         result: record.result,
         errorMessage,
+        route: sanitizeAppRoute(record.route),
     };
 }
 export class SdkCore {
     // Wired by the page entry: remove the standalone note, log tool errors,
-    // reload on a new deployed version.
+    // reload on a new deployed version, restore the host-remembered route.
     onHostReady = null;
     onToolError = null;
     onNewVersion = null;
+    onRestoreRoute = null;
     post;
     allowLocalHostOrigins;
     hostOrigin = null;
@@ -112,7 +123,7 @@ export class SdkCore {
         if (message === null)
             return;
         if (message.type === "hello") {
-            this.handleHello(origin);
+            this.handleHello(origin, message.route);
             return;
         }
         // Everything after the handshake must come from the pinned host origin.
@@ -128,15 +139,34 @@ export class SdkCore {
             this.onNewVersion?.();
         }
     }
-    handleHello(origin) {
+    handleHello(origin, route) {
         if (this.hostOrigin !== null)
             return; // pinned; later hellos are ignored
         if (!isAllowedHostOrigin(origin, this.allowLocalHostOrigins))
             return;
         this.hostOrigin = origin;
         this.onHostReady?.();
+        // Restore before the watches fire so the app renders the remembered
+        // page (the host page's fragment, or the pre-redeploy location) with
+        // its first data, not after it.
+        if (route !== "")
+            this.onRestoreRoute?.(route);
         this.requestAllWatches();
     }
+    // The app moved to a new in-page location; tell the pinned host so it
+    // can mirror the fragment into its own page URL. Anything unmirrorable —
+    // an empty hash (the app is back at its no-hash location) or a hash
+    // outside the strict shape (a query-bearing route, say) — is reported
+    // as the bare-"#" cleared sentinel: the host must forget rather than
+    // keep claiming a location the app already left, or a refresh or
+    // redeploy reload would yank the user to a stale page. Before the
+    // handshake there is nobody to tell.
+    reportRoute(hash) {
+        if (this.hostOrigin === null)
+            return;
+        const route = sanitizeAppRoute(hash) || "#";
+        this.post({ protocol: PROTOCOL, type: "route", hash: route }, this.hostOrigin);
+    }
     handleResult(message) {
         const entry = message.id === null ? undefined : this.watches.get(message.id);
         if (entry === undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driggsby/sdk",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "The browser SDK for Driggsby apps: live financial data through driggsby.watch().",
   "license": "Apache-2.0",
   "repository": {