@kizenapps/engine 1.7.4-2fa1b01 → 1.8.0-acda2a8

package/README.md

@@ -201,3 +201,77 @@ Some worker calls are coordinated using `@tanstack/react-query`. If your consume
 ### Script Return Values
 
 Scripts can return values from the worker thread. Awaiting the execute function returned from a plugin runner script will yield the value that the worker thread returned.
+
+### Navigation Context
+
+A script can hand a JSON payload to the page it navigates to — for example, to open a custom object page with an unsaved filter already applied. The engine stores the payload in `sessionStorage`, appends a `session_data_key` query param to the target URL, and lets the destination page read it back.
+
+Context only applies to **in-app** (same-origin, relative) navigations. Both targets are supported:
+
+- **`'_self'`** navigates the current tab via the host router.
+- **`'_blank'`** opens a new tab. The browser copies the current tab's `sessionStorage` into the new one at open time, so the payload rides along. (This is why the engine opens context-carrying `_blank` tabs without `noopener`/`noreferrer` — that copy only happens while the opener relationship is intact. It is restricted to same-origin URLs so `window.opener` is never exposed cross-origin.)
+
+**External / cross-origin** navigations ignore context entirely and keep the secure `noopener noreferrer` defaults. The reader helpers are **main-thread only** — workers cannot read this state.
+
+#### Passing context from a script
+
+Pass the payload as the third argument to `openWindow`. It is serialized with `JSON.stringify`: circular references and `BigInt` values throw synchronously, while functions, `undefined`, and symbols are silently dropped (standard `JSON.stringify` behavior).
+
+```js
+// Same tab:
+this.openWindow('/custom-objects/leads/records', '_self', {
+  unsavedFilter: {
+    /* ...payload */
+  },
+});
+
+// New tab — same payload, copied into the new tab's sessionStorage:
+this.openWindow('/custom-objects/leads/records', '_blank', {
+  unsavedFilter: {
+    /* ...payload */
+  },
+});
+```
+
+#### Reading context in React
+
+`useAppNavigationContext` takes the current URL (feed it from your router) and returns the payload plus a `clear` callback. Clear it once applied so a back-nav or refresh doesn't reapply stale context.
+
+```tsx
+import { useEffect } from 'react';
+import { useLocation } from 'react-router-dom';
+import { useAppNavigationContext } from '@kizenapps/engine/react';
+
+const RecordsPage = () => {
+  const { pathname, search } = useLocation();
+  const [navContext, clearNavContext] = useAppNavigationContext(`${pathname}${search}`);
+
+  useEffect(() => {
+    if (!navContext) return;
+
+    applyUnsavedFilter(navContext.unsavedFilter);
+
+    clearNavContext();
+  }, [navContext, clearNavContext]);
+
+  return null;
+};
+```
+
+#### Reading context outside React
+
+The package root exports plain helpers that all take an explicit URL. `consumeNavigationContext` reads and clears in one call:
+
+```ts
+import {
+  consumeNavigationContext, // read + clear (default choice)
+  readNavigationContext, // read only
+  clearNavigationContext, // clear only
+} from '@kizenapps/engine';
+
+const context = consumeNavigationContext(window.location.href);
+
+if (context?.unsavedFilter) {
+  applyUnsavedFilter(context.unsavedFilter);
+}
+```

package/dist/{automation-Bpg6VoKc.d.ts → automation-Dr26TnMo.d.ts}

@@ -117,6 +117,7 @@ interface OpenWindowEvent extends BaseEvent {
     url: string;
     target: string;
     features: string;
+    context?: Record<string, unknown>;
 }
 interface RecipientConfig {
     frame?: string;
@@ -363,4 +364,4 @@ interface AutomationStepConfig<T = unknown> {
     plugin_api_name?: string;
 }
 
-export type { SchemaValidation as $, AutomationStepConfig as A, BaseEvent as B, CalendarSourceConfig as C, DataAdornmentConfig as D, ErrorEvent as E, FloatingFrameConfig as F, GetPendingCacheCountFn as G, HideEvent as H, IframeOutputEvent as I, OnShowToastFn as J, KizenFile as K, OpenCreateRecordModalRequestEvent as L, MessageEventData as M, OpenCreateRelatedRecordModalRequestEvent as N, OnClearToastsFn as O, OpenWindowEvent as P, PerformKizenFileUploadFn as Q, RoutablePageConfig as R, PostFormDataRequestEvent as S, ToolbarItemConfig as T, PromptRequestEvent as U, QueryRequestEvent as V, RecipientConfig as W, RefreshEntityEvent as X, RefreshTimelineEvent as Y, RequestableQueryMethods as Z, RunEventScriptEvent as _, RouteScriptConfig as a, SetStateEvent as a0, ShowEvent as a1, ShowToastEvent as a2, ShowViewInModalRequestEvent as a3, TerminatorContent as a4, Terminators as a5, UIOutputEvent as a6, UpdateSessionDataEvent as a7, UploadFilePayload as a8, UploadFileRequestEvent as a9, WindowPosition as aa, RunScriptOptions as b, AuthorizeEvent as c, CalendarDefinition as d, CalendarScriptReturnData as e, CalendarSourceMap as f, CalendarSources as g, CloseModalRequestEvent as h, CommonExecutionPlugin as i, CommonPluginDefinition as j, CommunicateEvent as k, ConsoleLogEvent as l, CopyToClipboardEvent as m, CreateFileIdFn as n, DoneEvent as o, DynamicPromptRequestEvent as p, ExecuteCalendarSourceScript as q, ExecuteFloatingFrameScript as r, FloatingFrameEmployeeConfig as s, FrameQuadrant as t, InstallThirdPartyScriptRequestEvent as u, InvalidateCacheFn as v, MinimizedConfig as w, OnConsoleLogFn as x, OnNetworkRequestFn as y, OnRunEventScriptFn as z };
+export type { SchemaValidation as $, AutomationStepConfig as A, BaseEvent as B, CalendarSourceConfig as C, DataAdornmentConfig as D, ErrorEvent as E, FloatingFrameConfig as F, GetPendingCacheCountFn as G, HideEvent as H, IframeOutputEvent as I, OnShowToastFn as J, KizenFile as K, OpenCreateRecordModalRequestEvent as L, MessageEventData as M, OpenCreateRelatedRecordModalRequestEvent as N, OnClearToastsFn as O, OpenWindowEvent as P, PerformKizenFileUploadFn as Q, RoutablePageConfig as R, PostFormDataRequestEvent as S, ToolbarItemConfig as T, PromptRequestEvent as U, QueryRequestEvent as V, RecipientConfig as W, RefreshEntityEvent as X, RefreshTimelineEvent as Y, RequestableQueryMethods as Z, RunEventScriptEvent as _, RouteScriptConfig as a, SetStateEvent as a0, ShowEvent as a1, ShowToastEvent as a2, ShowViewInModalRequestEvent as a3, TerminatorContent as a4, Terminators as a5, UIOutputEvent as a6, UpdateSessionDataEvent as a7, UploadFilePayload as a8, UploadFileRequestEvent as a9, WindowPosition as aa, CommonExecutionPlugin as b, CommonPluginDefinition as c, RunScriptOptions as d, AuthorizeEvent as e, CalendarDefinition as f, CalendarScriptReturnData as g, CalendarSourceMap as h, CalendarSources as i, CloseModalRequestEvent as j, CommunicateEvent as k, ConsoleLogEvent as l, CopyToClipboardEvent as m, CreateFileIdFn as n, DoneEvent as o, DynamicPromptRequestEvent as p, ExecuteCalendarSourceScript as q, ExecuteFloatingFrameScript as r, FloatingFrameEmployeeConfig as s, FrameQuadrant as t, InstallThirdPartyScriptRequestEvent as u, InvalidateCacheFn as v, MinimizedConfig as w, OnConsoleLogFn as x, OnNetworkRequestFn as y, OnRunEventScriptFn as z };

package/dist/{blocks-DuJJdwgj.d.ts → blocks-C0e9BCrR.d.ts}

@@ -1,4 +1,4 @@
-import { i as CommonExecutionPlugin, j as CommonPluginDefinition } from './automation-Bpg6VoKc.js';
+import { b as CommonExecutionPlugin, c as CommonPluginDefinition } from './automation-Dr26TnMo.js';
 import { U as UnknownJSON } from './ThirdPartyScript-DauYx3B5.js';
 
 interface GenericPluginConfig extends CommonPluginDefinition {

package/dist/{chunk-UQBW6I5K.js → chunk-2F7MTOPU.js}

@@ -1,6 +1,6 @@
-import { getPartialLocation, generateUUIDV4 } from './chunk-UUITD2B5.js';
-import { getAllNestedInputsFromConfig, buildIframeURLWithProxy, getParentFrameAllowParam, deserializeConsoleArg, KizenRequestError, filterSandboxList, filterAllowList } from './chunk-MRHISAX3.js';
-import { IFRAME_PREFIX, ACTIONS, RESPONSES, COMMUNICATIONS, thirdPartyGlobalNames, getScriptIntegrationType, thirdPartySetupScripts, thirdPartyReadyPredicates } from './chunk-W37TFKDD.js';
+import { getPartialLocation, generateUUIDV4 } from './chunk-R347VQ7Y.js';
+import { getAllNestedInputsFromConfig, buildIframeURLWithProxy, getParentFrameAllowParam, deserializeConsoleArg, KizenRequestError, filterSandboxList, filterAllowList } from './chunk-T24XZSEF.js';
+import { IFRAME_PREFIX, ACTIONS, RESPONSES, COMMUNICATIONS, thirdPartyGlobalNames, getScriptIntegrationType, thirdPartySetupScripts, thirdPartyReadyPredicates } from './chunk-5AVQAIL3.js';
 import { __commonJS, __toESM } from './chunk-5WRI5ZAA.js';
 import DOMPurify from 'dompurify';
 
@@ -1796,10 +1796,66 @@ var getPluginSafeHTML = (html, pluginApiName, options) => {
   }
 };
 
+// src/communication/storage.ts
+var STORAGE_KEY_PREFIX = "kizen-app-context";
+var SESSION_DATA_PARAM = "session_data_key";
+var getStorageKey = () => `${STORAGE_KEY_PREFIX}-${generateUUIDV4()}`;
+var getStorageKeyFromUrl = (url) => {
+  try {
+    const key = new URL(url, window.location.origin).searchParams.get(SESSION_DATA_PARAM);
+    return key?.startsWith(`${STORAGE_KEY_PREFIX}-`) ? key : null;
+  } catch {
+    return null;
+  }
+};
+var storeNavigationContext = (context) => {
+  const storageKey = getStorageKey();
+  sessionStorage.setItem(storageKey, JSON.stringify(context));
+  return storageKey;
+};
+var transformNavigationUrl = (url, key) => {
+  const urlObj = new URL(url, window.location.origin);
+  urlObj.searchParams.set(SESSION_DATA_PARAM, key);
+  return `${urlObj.pathname}${urlObj.search}${urlObj.hash}`;
+};
+var readNavigationContext = (url) => {
+  const storageKey = getStorageKeyFromUrl(url);
+  if (!storageKey) {
+    return void 0;
+  }
+  try {
+    const contextString = sessionStorage.getItem(storageKey);
+    if (!contextString) {
+      return void 0;
+    }
+    return JSON.parse(contextString);
+  } catch {
+    return void 0;
+  }
+};
+var clearNavigationContext = (url) => {
+  const storageKey = getStorageKeyFromUrl(url);
+  if (storageKey) {
+    sessionStorage.removeItem(storageKey);
+  }
+};
+var consumeNavigationContext = (url) => {
+  const context = readNavigationContext(url);
+  clearNavigationContext(url);
+  return context;
+};
+
 // src/WorkerManager.ts
 var isRelative = (url) => {
   return url.startsWith("/");
 };
+var isSameOrigin = (url) => {
+  try {
+    return new URL(url, window.location.origin).origin === window.location.origin;
+  } catch {
+    return false;
+  }
+};
 var refreshTimeout = 3e4;
 var refreshInterval = 100;
 var WorkerManager = class {
@@ -1948,7 +2004,8 @@ var WorkerManager = class {
         this.handleOpenWindow(
           consideredEvent.url,
           consideredEvent.target,
-          consideredEvent.features
+          consideredEvent.features,
+          consideredEvent.context
         );
         return;
       }
@@ -2460,12 +2517,56 @@ var WorkerManager = class {
       });
     }
   };
-  handleOpenWindow = (url, target, features) => {
-    if (!isRelative(url) || target === "_blank" || !this.pushHistory) {
-      window.open(url, target, features);
-    } else {
-      this.pushHistory(url);
+  applyNavigationContext = (url, context) => {
+    let storageKey;
+    try {
+      storageKey = storeNavigationContext(context);
+    } catch {
+      this.onError?.({
+        message: "Failed to store context in sessionStorage."
+      });
+      return url;
+    }
+    try {
+      return transformNavigationUrl(url, storageKey);
+    } catch {
+      try {
+        sessionStorage.removeItem(storageKey);
+      } catch {
+      }
+      this.onError?.({
+        message: "Failed to append the context key to the navigation URL."
+      });
+      return url;
+    }
+  };
+  handleOpenWindow = (url, target, features, context) => {
+    const { pushHistory } = this;
+    if (isRelative(url) && target !== "_blank") {
+      const finalUrl = context ? this.applyNavigationContext(url, context) : url;
+      if (pushHistory) {
+        pushHistory(finalUrl);
+      } else {
+        window.open(finalUrl, target, features);
+      }
+      return;
+    }
+    if (isRelative(url) && target === "_blank" && context && isSameOrigin(url)) {
+      let storageKey;
+      try {
+        storageKey = storeNavigationContext(context);
+      } catch {
+        this.onError?.({
+          message: "Failed to store context in sessionStorage."
+        });
+        window.open(url, target, features);
+        return;
+      }
+      window.open(transformNavigationUrl(url, storageKey), "_blank");
+      sessionStorage.removeItem(storageKey);
+      return;
     }
+    window.open(url, target, features);
   };
   handleAuthorize = (serviceName, config = {}) => {
     const params = new URLSearchParams();
@@ -2682,8 +2783,8 @@ var modalSize = {
 };
 
 // src/index.ts
-var version = "1.7.4-2fa1b01";
+var version = "1.8.0-acda2a8";
 
-export { forceQualifiedUrl, getDisabledValue, getEnabledState, getHash, getLinkValue, getPluginSafeHTML, getQrCodeValue, getStableHash, isFlagEnabled, mergeConfig, modalSize, pluginMapper, reduceEnabledResults, replaceConfigValues, runExpression, runObjectExpression, runOptionExpression, runScript, runStringExpression, version };
-//# sourceMappingURL=chunk-UQBW6I5K.js.map
-//# sourceMappingURL=chunk-UQBW6I5K.js.map
+export { clearNavigationContext, consumeNavigationContext, forceQualifiedUrl, getDisabledValue, getEnabledState, getHash, getLinkValue, getPluginSafeHTML, getQrCodeValue, getStableHash, isFlagEnabled, mergeConfig, modalSize, pluginMapper, readNavigationContext, reduceEnabledResults, replaceConfigValues, runExpression, runObjectExpression, runOptionExpression, runScript, runStringExpression, version };
+//# sourceMappingURL=chunk-2F7MTOPU.js.map
+//# sourceMappingURL=chunk-2F7MTOPU.js.map