@tai42/studio-sdk 16.0.0 → 17.0.0

package/src/navigation/guarded-navigation.ts

@@ -0,0 +1,147 @@
+/**
+ * Wrap a shell-supplied {@link NavigationContextValue} so every SDK-controlled
+ * transition consults the armed guards before it commits, and — on approval —
+ * advances the committed-entry mirror to the resolved destination. With no guard
+ * armed each call stays synchronous, identical to the raw shell value.
+ */
+import type { RefObject } from 'react';
+
+import { mergeEntryState, reconstructEntryState } from './entry-state';
+import type { NavigationGuardRegistry } from './guard-registry';
+import type { NavigationContextValue } from './types';
+
+/** The last committed history entry the SDK observed: what a canceled back/forward restores to. */
+export interface CommittedEntry {
+  href: string;
+  state: unknown;
+}
+
+type CommittedRef = RefObject<CommittedEntry | null>;
+
+// navigate: forwarded as a REST tuple so the shell's `navigate` is called with
+// exactly the arguments the caller passed — a caller wanting the default history
+// behaviour never turns into one that passed an explicit `undefined` for it.
+function buildNavigate(
+  value: NavigationContextValue,
+  registry: NavigationGuardRegistry,
+  committedRef: CommittedRef,
+): NavigationContextValue['navigate'] {
+  return (...args) => {
+    const [token, search] = args;
+    if (!registry.hasArmedGuards()) {
+      value.navigate(...args);
+      return;
+    }
+    void registry.run().then((allowed) => {
+      if (!allowed) return;
+      value.navigate(...args);
+      // Advance the committed entry to the resolved destination (the router may commit
+      // async, so `window.location` would be stale). Router state is unobservable here.
+      if (committedRef.current !== null) {
+        committedRef.current = { href: value.resolvePath(token, search), state: null };
+      }
+    });
+  };
+}
+
+function buildNavigatePlugin(
+  value: NavigationContextValue,
+  registry: NavigationGuardRegistry,
+  committedRef: CommittedRef,
+): NavigationContextValue['navigatePlugin'] {
+  return (pluginId, pagePath, params, search) => {
+    if (!registry.hasArmedGuards()) {
+      value.navigatePlugin(pluginId, pagePath, params, search);
+      return;
+    }
+    void registry.run().then((allowed) => {
+      if (!allowed) return;
+      value.navigatePlugin(pluginId, pagePath, params, search);
+      if (committedRef.current !== null) {
+        committedRef.current = {
+          href: value.resolvePluginPath(pluginId, pagePath, params, search),
+          state: null,
+        };
+      }
+    });
+  };
+}
+
+// navigatePluginWithOptions: guard-gated exactly like navigatePlugin (a veto never
+// reaches the host member). On approval, refresh the committed entry with the
+// reconstructed state bag so a subsequent vetoed Back restores the slot this
+// navigation just wrote, not null.
+function buildNavigateWithOptions(
+  hostNavigateWithOptions: NonNullable<NavigationContextValue['navigatePluginWithOptions']>,
+  value: NavigationContextValue,
+  registry: NavigationGuardRegistry,
+  committedRef: CommittedRef,
+): NonNullable<NavigationContextValue['navigatePluginWithOptions']> {
+  return (pluginId, pagePath, params, search, options) => {
+    if (!registry.hasArmedGuards()) {
+      hostNavigateWithOptions(pluginId, pagePath, params, search, options);
+      return;
+    }
+    void registry.run().then((allowed) => {
+      if (!allowed) return;
+      hostNavigateWithOptions(pluginId, pagePath, params, search, options);
+      if (committedRef.current !== null) {
+        committedRef.current = {
+          href: value.resolvePluginPath(pluginId, pagePath, params, search),
+          state:
+            options?.state !== undefined ? reconstructEntryState(pluginId, options.state) : null,
+        };
+      }
+    });
+  };
+}
+
+// updatePluginEntryState: guard-FREE — rewriting the current entry's state is not a
+// navigation away. The SDK still wraps it to refresh the committed entry with the
+// merged slot, so a later vetoed Back restores the UPDATED state. URL is unchanged.
+function buildUpdateEntryState(
+  hostUpdateEntryState: NonNullable<NavigationContextValue['updatePluginEntryState']>,
+  committedRef: CommittedRef,
+): NonNullable<NavigationContextValue['updatePluginEntryState']> {
+  return (pluginId, state) => {
+    hostUpdateEntryState(pluginId, state);
+    if (committedRef.current !== null) {
+      committedRef.current = {
+        href: committedRef.current.href,
+        state: mergeEntryState(committedRef.current.state, pluginId, state),
+      };
+    }
+  };
+}
+
+/**
+ * Build the guarded navigation value. The two host-optional members
+ * (`navigatePluginWithOptions`, `updatePluginEntryState`) are wrapped only when the
+ * host provides them; an older host leaves them undefined and the plugin-facing hook
+ * throws loudly.
+ */
+export function buildGuardedNavigation(
+  value: NavigationContextValue,
+  registry: NavigationGuardRegistry,
+  committedRef: CommittedRef,
+): NavigationContextValue {
+  const result: NavigationContextValue = {
+    ...value,
+    navigate: buildNavigate(value, registry, committedRef),
+    navigatePlugin: buildNavigatePlugin(value, registry, committedRef),
+  };
+  const hostNavigateWithOptions = value.navigatePluginWithOptions;
+  if (hostNavigateWithOptions !== undefined) {
+    result.navigatePluginWithOptions = buildNavigateWithOptions(
+      hostNavigateWithOptions,
+      value,
+      registry,
+      committedRef,
+    );
+  }
+  const hostUpdateEntryState = value.updatePluginEntryState;
+  if (hostUpdateEntryState !== undefined) {
+    result.updatePluginEntryState = buildUpdateEntryState(hostUpdateEntryState, committedRef);
+  }
+  return result;
+}

package/src/navigation/index.ts

@@ -1,24 +1,24 @@
+export type { AppLinkProps } from './app-link';
+export { AppLink } from './app-link';
 export {
   NavigationProvider,
-  AppLink,
   useAppNavigate,
-  useResolvePath,
-  usePluginNavigation,
-  usePluginEntryNavigation,
-  useNavigationGuard,
   useNavigationGate,
+  useNavigationGuard,
+  usePluginEntryNavigation,
+  usePluginNavigation,
+  useResolvePath,
 } from './context';
-export type { AppLinkProps } from './context';
-export { useSearchCommit } from './use-search-commit';
-export type { SearchCommitParams } from './use-search-commit';
 export type {
-  RouteToken,
-  RouteSearch,
-  RouteSearchByToken,
-  PageProps,
-  NavigationContextValue,
   NavigateOptions,
+  NavigationContextValue,
+  NavigationGuardHandler,
+  PageProps,
   PluginNavigateOptions,
   PluginSearch,
-  NavigationGuardHandler,
+  RouteSearch,
+  RouteSearchByToken,
+  RouteToken,
 } from './types';
+export type { SearchCommitParams } from './use-search-commit';
+export { useSearchCommit } from './use-search-commit';

package/src/navigation/types.ts

@@ -193,21 +193,18 @@ export interface NavigationContextValue {
   ) => string;
   /**
    * ADDITIVE plugin-page navigation that also carries per-history-entry
-   * {@link PluginNavigateOptions}. OPTIONAL because a Studio host built before this
-   * feature does not provide it; plugins reach it — and require a host that does —
-   * through {@link usePluginEntryNavigation}, which throws loudly on an older host.
+   * {@link PluginNavigateOptions}. OPTIONAL because a host that does not implement it
+   * leaves it undefined; plugins reach it — and require a host that provides it —
+   * through {@link usePluginEntryNavigation}, which throws loudly when it is absent.
    * It behaves exactly like {@link navigatePlugin} for path / params / search, and in
    * addition writes `options.state` onto the DESTINATION entry under the plugin's own
    * namespace slot (see {@link PluginPageProps.entryState}).
    *
-   * NEXT-MAJOR (9.0) CONSOLIDATION NOTE: fold `options` into {@link navigatePlugin}'s
-   * own signature and RETIRE this sibling. It exists as a separate optional member
-   * ONLY to stay additive under the plugin-API equality gate — a new optional member
-   * does not move {@link STUDIO_PLUGIN_API_VERSION}, so every existing plugin keeps
-   * loading. Cutting a MAJOR now purely to rename one method onto another is the
-   * disproportion anti-pattern: a breaking change for a cosmetic merge. The merge
-   * therefore waits for the next major that carries real breaks; until then both
-   * coexist and {@link navigatePlugin} stays byte-for-byte stable.
+   * It is a separate optional member rather than an extra parameter on
+   * {@link navigatePlugin} so it stays additive under the plugin-API equality gate: a
+   * new optional member does not move {@link STUDIO_PLUGIN_API_VERSION}, so every
+   * existing plugin keeps loading and {@link navigatePlugin}'s own signature stays
+   * stable.
    */
   navigatePluginWithOptions?: (
     pluginId: string,

package/src/navigation/use-back-forward-guard.ts

@@ -0,0 +1,90 @@
+/**
+ * The browser back/forward and full-unload arm of the navigation guard. While any
+ * guard is armed it intercepts `popstate` — canceling the move by re-pushing the
+ * committed entry, consulting the guards once, and replaying the move on approval —
+ * and installs a `beforeunload` prompt. It attaches the listeners only while armed,
+ * mirroring the registry's armed state into React.
+ */
+import type { RefObject } from 'react';
+import { useEffect, useState } from 'react';
+
+import type { NavigationGuardRegistry } from './guard-registry';
+import type { CommittedEntry } from './guarded-navigation';
+
+export function useBackForwardGuard(
+  registry: NavigationGuardRegistry,
+  committedRef: RefObject<CommittedEntry | null>,
+): void {
+  // Mirror the registry's armed state into React so the browser listeners attach only
+  // while at least one guard is armed.
+  const [armed, setArmed] = useState(false);
+  useEffect(() => {
+    setArmed(registry.hasArmedGuards());
+    return registry.subscribe(() => {
+      setArmed(registry.hasArmedGuards());
+    });
+  }, [registry]);
+
+  useEffect(() => {
+    if (!armed) return;
+
+    // The protected entry (URL + state); a back/forward landing elsewhere is first
+    // canceled back to here while the guard is consulted.
+    committedRef.current = { href: window.location.href, state: window.history.state };
+    // Set while replaying a guard-approved back/forward, so its `popstate` passes
+    // through instead of being re-intercepted.
+    let bypass = false;
+    // Latched while a decision is pending, so a second Back mid-decision keeps canceling
+    // without starting a concurrent `registry.run()` — one gesture, one dialog.
+    let pending = false;
+    // Restore pushes stacked for the pending decision, so an approved replay unwinds
+    // exactly that far in one `go(-depth)`. Reset per decision.
+    let restores = 0;
+
+    const onPopState = () => {
+      if (bypass) {
+        bypass = false;
+        committedRef.current = { href: window.location.href, state: window.history.state };
+        return;
+      }
+      if (!registry.hasArmedGuards()) {
+        committedRef.current = { href: window.location.href, state: window.history.state };
+        return;
+      }
+      const committed = committedRef.current;
+      if (committed === null) return;
+      // Cancel the browser's move by pushing the committed entry on top of wherever it
+      // landed. popstate exposes no direction/distance and the router owns
+      // `history.state`, so restore can only push, not delete. A vetoed forward thus
+      // strands a stub entry — an accepted limit the next pushState truncates.
+      window.history.pushState(committed.state, '', committed.href);
+      restores += 1;
+      if (pending) return;
+      pending = true;
+      void registry.run().then((allowed) => {
+        pending = false;
+        const depth = restores;
+        restores = 0;
+        if (!allowed) return;
+        bypass = true;
+        window.history.go(-depth);
+      });
+    };
+
+    const onBeforeUnload = (event: BeforeUnloadEvent) => {
+      event.preventDefault();
+      // Browsers below the floor (Chrome 108) gate the prompt on a set `returnValue`,
+      // not `preventDefault` alone; the string is ignored. Typed deprecated, still required.
+      // eslint-disable-next-line @typescript-eslint/no-deprecated -- required beforeunload trigger for the supported browser range.
+      event.returnValue = '';
+    };
+
+    window.addEventListener('popstate', onPopState);
+    window.addEventListener('beforeunload', onBeforeUnload);
+    return () => {
+      committedRef.current = null;
+      window.removeEventListener('popstate', onPopState);
+      window.removeEventListener('beforeunload', onBeforeUnload);
+    };
+  }, [armed, registry, committedRef]);
+}

package/src/navigation/use-search-commit.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, type RefObject } from 'react';
+import { type RefObject, useCallback, useEffect, useRef } from 'react';
 
 import { useAppNavigate } from './context';
 import type { RouteSearch, RouteToken } from './types';

package/src/plugin/host-state.ts

@@ -13,8 +13,8 @@
  */
 import { useSyncExternalStore } from 'react';
 
-import type { PluginContributions } from './types';
 import { getContributions } from './registry';
+import type { PluginContributions } from './types';
 
 /**
  * Identity of a successfully-loaded plugin, for host chrome that must attribute a

package/src/plugin/registry.ts

@@ -24,117 +24,115 @@ const pages: RegisteredPage[] = [];
 const settingsTabs: RegisteredSettingsTab[] = [];
 const navEntries: RegisteredNavEntry[] = [];
 
+/** The contributions one plugin stages before they commit as a batch. */
+interface StagedContributions {
+  readonly pages: RegisteredPage[];
+  readonly toolPanels: Map<string, ToolPanelContribution>;
+  readonly settingsTabs: RegisteredSettingsTab[];
+  readonly tabIds: Set<string>;
+  readonly navEntries: RegisteredNavEntry[];
+}
+
 /**
- * Load one plugin: call its `register` entry with a context bound to `pluginId`,
- * then commit everything it staged into the global registry.
- *
- * Contributions are STAGED into local arrays (identity captured in the closure,
- * never read from ambient state) and only committed after `entry` settles
- * successfully. `entry` is AWAITED before commit, so a synchronous or an `async`
- * entry is fully done first: a post-`await` throw skips the commit (atomicity
- * holds for async too) and a post-`await` registration cannot slip past the batch.
- * The seal is set after `entry` has SETTLED — for a sync entry, after it returns
- * and the `await` continuation runs; for an async entry, after its returned promise
- * resolves. A registration attempted from that point on (a deferred timer, a
- * callback scheduled after settle) throws loudly instead of pushing into an
- * orphaned staged array that never commits. Registrations made during `entry`'s
- * synchronous body — including a microtask it enqueues then, which runs before the
- * `await` continuation — are still captured and committed with the batch. A
- * `register` that throws commits nothing and leaves the registry untouched.
- * Duplicate guards run against BOTH the staged contributions and what is already
- * committed, and fail loudly.
+ * A mutable seal flag passed BY REFERENCE into the staging context, so the seal set
+ * in {@link loadPlugin}'s `finally` is seen by every `register*` method's closure.
  */
-export async function loadPlugin(pluginId: string, entry: PluginEntry): Promise<void> {
-  const stagedPages: RegisteredPage[] = [];
-  const stagedToolPanels = new Map<string, ToolPanelContribution>();
-  const stagedSettingsTabs: RegisteredSettingsTab[] = [];
-  const stagedTabIds = new Set<string>();
-  const stagedNavEntries: RegisteredNavEntry[] = [];
-  let sealed = false;
+interface Seal {
+  closed: boolean;
+}
 
-  const context: PluginContext = {
+function emptyStaged(): StagedContributions {
+  return {
+    pages: [],
+    toolPanels: new Map(),
+    settingsTabs: [],
+    tabIds: new Set(),
+    navEntries: [],
+  };
+}
+
+/**
+ * Build the {@link PluginContext} a plugin's `register` entry contributes through.
+ * Every method stages into `staged` (never ambient state) and refuses once `seal` is
+ * closed — a registration after `entry` settles (a deferred timer, a post-settle
+ * callback) throws loudly rather than pushing into an orphaned array that never
+ * commits. Duplicate guards run against BOTH the staged set and what is already
+ * committed, and fail loudly.
+ */
+function makeStagingContext(
+  pluginId: string,
+  staged: StagedContributions,
+  seal: Seal,
+): PluginContext {
+  const assertOpen = (): void => {
+    if (seal.closed) {
+      throw new Error(
+        'registration is closed: a plugin must register during register(), not after it resolves',
+      );
+    }
+  };
+  return {
     registerPage(contribution: PageContribution): void {
-      if (sealed) {
-        throw new Error(
-          'registration is closed: a plugin must register during register(), not after it resolves',
-        );
-      }
-      const staged = stagedPages.some((p) => p.path === contribution.path);
-      const committed = pages.some((p) => p.pluginId === pluginId && p.path === contribution.path);
-      if (staged || committed) {
+      assertOpen();
+      const duplicate =
+        staged.pages.some((p) => p.path === contribution.path) ||
+        pages.some((p) => p.pluginId === pluginId && p.path === contribution.path);
+      if (duplicate) {
         // A duplicate path within one plugin is an author mistake that would
         // leave one page unreachable — fail loudly, as registerToolPanel does.
         throw new Error(`plugin “${pluginId}” already registered a page at “${contribution.path}”`);
       }
-      stagedPages.push({ ...contribution, pluginId });
+      staged.pages.push({ ...contribution, pluginId });
     },
     registerToolPanel(contribution: ToolPanelContribution): void {
-      if (sealed) {
-        throw new Error(
-          'registration is closed: a plugin must register during register(), not after it resolves',
-        );
-      }
-      if (stagedToolPanels.has(contribution.toolName) || toolPanels.has(contribution.toolName)) {
+      assertOpen();
+      if (staged.toolPanels.has(contribution.toolName) || toolPanels.has(contribution.toolName)) {
         throw new Error(`a tool panel is already registered for ${contribution.toolName}`);
       }
-      stagedToolPanels.set(contribution.toolName, contribution);
+      staged.toolPanels.set(contribution.toolName, contribution);
     },
     registerSettingsTab(contribution: SettingsTabContribution): void {
-      if (sealed) {
-        throw new Error(
-          'registration is closed: a plugin must register during register(), not after it resolves',
-        );
-      }
+      assertOpen();
       const committed = settingsTabs.some(
         (t) => t.pluginId === pluginId && t.id === contribution.id,
       );
-      if (stagedTabIds.has(contribution.id) || committed) {
+      if (staged.tabIds.has(contribution.id) || committed) {
         // A duplicate tab id within one plugin would leave one tab unreachable —
         // fail loudly, mirroring the page-path guard.
         throw new Error(
           `plugin “${pluginId}” already registered a settings tab “${contribution.id}”`,
         );
       }
-      stagedTabIds.add(contribution.id);
-      stagedSettingsTabs.push({ ...contribution, pluginId });
+      staged.tabIds.add(contribution.id);
+      staged.settingsTabs.push({ ...contribution, pluginId });
     },
     registerNavEntry(contribution: NavEntryContribution): void {
-      if (sealed) {
-        throw new Error(
-          'registration is closed: a plugin must register during register(), not after it resolves',
-        );
-      }
-      const staged = stagedNavEntries.some((e) => e.path === contribution.path);
-      const committed = navEntries.some(
-        (e) => e.pluginId === pluginId && e.path === contribution.path,
-      );
-      if (staged || committed) {
+      assertOpen();
+      const duplicate =
+        staged.navEntries.some((e) => e.path === contribution.path) ||
+        navEntries.some((e) => e.pluginId === pluginId && e.path === contribution.path);
+      if (duplicate) {
         // A duplicate nav path within one plugin is an author mistake — two
         // entries pointing at the same page — so fail loudly like the page guard.
         throw new Error(
           `plugin “${pluginId}” already registered a nav entry at “${contribution.path}”`,
         );
       }
-      stagedNavEntries.push({ ...contribution, pluginId });
+      staged.navEntries.push({ ...contribution, pluginId });
     },
   };
+}
 
-  try {
-    await entry(context);
-  } finally {
-    // Whether `entry` resolved or threw, no further registration is valid — seal
-    // so a deferred call fails loudly rather than pushing into an orphaned array.
-    sealed = true;
-  }
-
-  // Every nav entry must link to a page THIS plugin registers — staged in this
-  // call or already committed. A nav entry with no matching page is a guaranteed
-  // dead link (the plugin page surface renders "Page not found"), so reject it
-  // loudly. This throws BEFORE the commit loops, so it propagates out of
-  // `loadPlugin` and NOTHING (pages, panels, tabs, nav) commits — atomicity holds.
-  for (const navEntry of stagedNavEntries) {
+/**
+ * Every nav entry must link to a page THIS plugin registers — staged in this call or
+ * already committed. A nav entry with no matching page is a guaranteed dead link (the
+ * plugin page surface renders "Page not found"), so reject it loudly. Throwing here —
+ * BEFORE any commit — keeps atomicity: nothing (pages, panels, tabs, nav) commits.
+ */
+function assertNavEntriesHavePages(pluginId: string, staged: StagedContributions): void {
+  for (const navEntry of staged.navEntries) {
     const hasPage =
-      stagedPages.some((p) => p.path === navEntry.path) ||
+      staged.pages.some((p) => p.path === navEntry.path) ||
       pages.some((p) => p.pluginId === pluginId && p.path === navEntry.path);
     if (!hasPage) {
       throw new Error(
@@ -142,22 +140,45 @@ export async function loadPlugin(pluginId: string, entry: PluginEntry): Promise<
       );
     }
   }
+}
 
-  // `entry` resolved without throwing: commit the staged contributions as one
-  // batch, so the registry only ever holds a plugin's complete set — never a
-  // partial set left behind by a mid-registration failure.
-  for (const page of stagedPages) {
-    pages.push(page);
-  }
-  for (const [toolName, contribution] of stagedToolPanels) {
-    toolPanels.set(toolName, contribution);
-  }
-  for (const tab of stagedSettingsTabs) {
-    settingsTabs.push(tab);
-  }
-  for (const navEntry of stagedNavEntries) {
-    navEntries.push(navEntry);
+/**
+ * Commit the staged contributions as one batch, so the registry only ever holds a
+ * plugin's complete set — never a partial set left behind by a mid-registration failure.
+ */
+function commitStaged(staged: StagedContributions): void {
+  for (const page of staged.pages) pages.push(page);
+  for (const [toolName, contribution] of staged.toolPanels) toolPanels.set(toolName, contribution);
+  for (const tab of staged.settingsTabs) settingsTabs.push(tab);
+  for (const navEntry of staged.navEntries) navEntries.push(navEntry);
+}
+
+/**
+ * Load one plugin: call its `register` entry with a context bound to `pluginId`,
+ * then commit everything it staged into the global registry.
+ *
+ * `entry` is AWAITED before commit, so a synchronous or an `async` entry is fully
+ * done first: a post-`await` throw skips the commit (atomicity holds for async too)
+ * and a post-`await` registration cannot slip past the batch. The seal is set after
+ * `entry` has SETTLED, so a later registration throws loudly; registrations made
+ * during `entry`'s synchronous body — including a microtask it enqueues then — are
+ * still captured and committed. A `register` that throws commits nothing.
+ */
+export async function loadPlugin(pluginId: string, entry: PluginEntry): Promise<void> {
+  const staged = emptyStaged();
+  const seal: Seal = { closed: false };
+  const context = makeStagingContext(pluginId, staged, seal);
+
+  try {
+    await entry(context);
+  } finally {
+    // Whether `entry` resolved or threw, no further registration is valid — seal
+    // so a deferred call fails loudly rather than pushing into an orphaned array.
+    seal.closed = true;
   }
+
+  assertNavEntriesHavePages(pluginId, staged);
+  commitStaged(staged);
 }
 
 /** The shell reads this after loading every installed plugin bundle. */

package/src/schema-editor/SchemaEditor.tsx

@@ -19,7 +19,7 @@
  * SAFETY: the schema text is operator-authored and every derived value renders as
  * React TEXT (through the DS controls / `JsonTree` / `SchemaForm`), never an HTML sink.
  */
-import { Component, useMemo, useState, type ReactNode } from 'react';
+import { Component, type ReactNode, useMemo, useState } from 'react';
 
 import { Field } from '../components/field';
 import { Textarea } from '../components/inputs';

package/src/schema-editor/index.ts

@@ -3,7 +3,7 @@
  * surface: the `SchemaEditor` component, its change type, and the pure lint helper
  * consumers reuse to pre-check a stored schema.
  */
-export { SchemaEditor } from './SchemaEditor';
-export type { SchemaEditorProps, SchemaEditorChange } from './SchemaEditor';
-export { lintSchemaText } from './lint';
 export type { SchemaLintResult } from './lint';
+export { lintSchemaText } from './lint';
+export type { SchemaEditorChange, SchemaEditorProps } from './SchemaEditor';
+export { SchemaEditor } from './SchemaEditor';