@tai42/studio-sdk 16.0.0 → 16.0.1

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 { useEffect, useState } from 'react';
+import type { RefObject } 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/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-form/SecretRefField.tsx

@@ -1,11 +1,8 @@
 /**
  * `SecretRefField` — a data-agnostic masked editor for ONE secret value that is
  * EITHER a reference to an existing env key OR a freshly pasted secret. It knows
- * nothing about the `!ENV ${KEY}` marker syntax or any wire format: it emits a
- * discriminated {@link SecretRef} and the host maps that to whatever it stores
- * (the consumer that mounts this — the connectors page's McpServersSection —
- * writes an `!ENV ${KEY}` marker for a `key` ref and runs the combined
- * store-then-mark op for a `paste`).
+ * nothing about any wire format: it emits a discriminated {@link SecretRef} and
+ * the host maps that to whatever it stores.
  *
  * WRITE-ONLY for a pasted secret: the plaintext lives only in local editor state
  * until the user commits it, at which point it leaves the DOM entirely (held only
@@ -29,10 +26,9 @@ import { Select } from '../components/select';
 /**
  * The value {@link SecretRefField} emits and reads back. The `source` discriminant
  * is what the host branches on:
- *  - `key`   — reference an existing env key; the host writes `!ENV ${key}`.
+ *  - `key`   — reference an existing env key; the host resolves the reference.
  *  - `paste` — a new plaintext secret; the host stores it under a generated key
- *              (combined op) and writes the resulting marker. `secret` is
- *              write-only and is never rendered.
+ *              and records the reference. `secret` is write-only and never rendered.
  */
 export type SecretRef =
   | { readonly source: 'key'; readonly key: string }
@@ -141,71 +137,125 @@ export function SecretRefField({
   return (
     <div data-testid={idPrefix}>
       {canPick ? (
-        <div className="tai-row" role="group" aria-label={`${label} source`}>
-          <Button
-            type="button"
-            variant={effectiveMode === 'key' ? 'primary' : 'secondary'}
-            aria-pressed={effectiveMode === 'key'}
-            onClick={() => {
-              setMode('key');
-            }}
-          >
-            Reference existing key
-          </Button>
-          <Button
-            type="button"
-            variant={effectiveMode === 'paste' ? 'primary' : 'secondary'}
-            aria-pressed={effectiveMode === 'paste'}
-            onClick={() => {
-              setMode('paste');
-            }}
-          >
-            Paste new secret
-          </Button>
-        </div>
+        <SecretSourceToggle label={label} effectiveMode={effectiveMode} onMode={setMode} />
       ) : null}
+      <SecretEditorBody
+        label={label}
+        effectiveMode={effectiveMode}
+        availableKeys={availableKeys}
+        pickedKey={pickedKey}
+        onPickKey={commitKey}
+        draftSecret={draftSecret}
+        onDraftChange={setDraftSecret}
+        onCommitPaste={commitPaste}
+        pasteDisabledReason={pasteDisabledReason}
+        pasteBlocked={pasteBlocked}
+      />
+    </div>
+  );
+}
 
-      {effectiveMode === 'key' ? (
-        availableKeys.length === 0 ? (
-          <span className="tai-field-hint">No keys available</span>
-        ) : (
-          <Field label={label}>
-            <Select
-              value={pickedKey === '' ? undefined : pickedKey}
-              onValueChange={commitKey}
-              placeholder="Select a key"
-              options={availableKeys.map((key) => ({ value: key, label: key }))}
-            />
-          </Field>
-        )
-      ) : (
-        <div className="tai-row">
-          <div style={{ flex: 1 }}>
-            <Field label={label} error={pasteDisabledReason}>
-              {/* type=password: the plaintext is masked and offers no reveal —
-                  it is write-only. */}
-              <TextInput
-                type="password"
-                value={draftSecret}
-                onChange={(event) => {
-                  setDraftSecret(event.target.value);
-                }}
-                autoComplete="off"
-                spellCheck={false}
-                placeholder="Paste a secret value"
-              />
-            </Field>
-          </div>
-          <Button
-            type="button"
-            variant="primary"
-            disabled={draftSecret === '' || pasteBlocked}
-            onClick={commitPaste}
-          >
-            Use secret
-          </Button>
-        </div>
-      )}
+/** The key/paste source switch, shown only when key picking is available. */
+function SecretSourceToggle({
+  label,
+  effectiveMode,
+  onMode,
+}: {
+  label: string;
+  effectiveMode: 'key' | 'paste';
+  onMode: (mode: 'key' | 'paste') => void;
+}): ReactNode {
+  return (
+    <div className="tai-row" role="group" aria-label={`${label} source`}>
+      <Button
+        type="button"
+        variant={effectiveMode === 'key' ? 'primary' : 'secondary'}
+        aria-pressed={effectiveMode === 'key'}
+        onClick={() => {
+          onMode('key');
+        }}
+      >
+        Reference existing key
+      </Button>
+      <Button
+        type="button"
+        variant={effectiveMode === 'paste' ? 'primary' : 'secondary'}
+        aria-pressed={effectiveMode === 'paste'}
+        onClick={() => {
+          onMode('paste');
+        }}
+      >
+        Paste new secret
+      </Button>
+    </div>
+  );
+}
+
+/** The active editor: a key Select (or an empty-keys hint) or the write-only paste input. */
+function SecretEditorBody({
+  label,
+  effectiveMode,
+  availableKeys,
+  pickedKey,
+  onPickKey,
+  draftSecret,
+  onDraftChange,
+  onCommitPaste,
+  pasteDisabledReason,
+  pasteBlocked,
+}: {
+  label: string;
+  effectiveMode: 'key' | 'paste';
+  availableKeys: readonly string[];
+  pickedKey: string;
+  onPickKey: (key: string) => void;
+  draftSecret: string;
+  onDraftChange: (secret: string) => void;
+  onCommitPaste: () => void;
+  pasteDisabledReason: string | undefined;
+  pasteBlocked: boolean;
+}): ReactNode {
+  if (effectiveMode === 'key') {
+    if (availableKeys.length === 0) {
+      return <span className="tai-field-hint">No keys available</span>;
+    }
+    return (
+      <Field label={label}>
+        <Select
+          value={pickedKey === '' ? undefined : pickedKey}
+          onValueChange={onPickKey}
+          placeholder="Select a key"
+          options={availableKeys.map((key) => ({ value: key, label: key }))}
+        />
+      </Field>
+    );
+  }
+  return (
+    <div className="tai-row">
+      <div style={{ flex: 1 }}>
+        <Field label={label} error={pasteDisabledReason}>
+          {/* type=password: the plaintext is masked and offers no reveal —
+              it is write-only. */}
+          <TextInput
+            type="password"
+            value={draftSecret}
+            onChange={(event) => {
+              onDraftChange(event.target.value);
+            }}
+            autoComplete="off"
+            spellCheck={false}
+            placeholder="Paste a secret value"
+          />
+        </Field>
+      </div>
+      <Button
+        type="button"
+        variant="primary"
+        disabled={draftSecret === '' || pasteBlocked}
+        onClick={onCommitPaste}
+      >
+        Use secret
+      </Button>
     </div>
   );
 }