@tai42/studio-sdk 25.0.0 → 26.0.0

package/src/hooks/useCapabilities.ts

@@ -121,7 +121,7 @@ export function useCapabilities(): CapabilityContextValue {
  * seeded editor/viewer carries `["*"]` scopes PLUS a jq fence, so keying on `"*"`
  * scopes would hand every editor/viewer the unfiltered nav and a wall of 403s on
  * the admin routes their fence denies. Keying on `admin` makes editor/viewer
- * SCOPED sessions whose nav is filtered by their jq-exact `routes`, which is
+ * SCOPED sessions whose nav is filtered by their projected `routes`, which is
  * exactly right — and the gate-off synthetic projection (`admin: true`, empty
  * `routes`) still reads as full, so an AC-disabled deployment shows everything.
  */
@@ -143,8 +143,8 @@ function pathUnderPrefix(path: string, prefix: string): boolean {
 /**
  * Whether the projection reaches ANY route under one of `prefixes` — the
  * declarative test behind nav filtering and plugin `requiredCapabilities`. A
- * concrete `routes[].path` covers a prefix when it is that prefix or a
- * segment-nested descendant of it; a dynamic `route_patterns[]` entry covers a
+ * `routes[].path` (a concrete path, or a route template such as `/api/presets/{name}`)
+ * covers a prefix when it is that prefix or a segment-nested descendant of it; a dynamic `route_patterns[]` entry covers a
  * prefix through its served `open_prefix` — the literal the server rules every
  * path starting with is reachable — when it overlaps the prefix at a segment
  * boundary. A `null` open prefix (a pattern whose matched set is not a clean
@@ -167,14 +167,16 @@ export function coversAnyRoute(projection: MeProjection, prefixes: readonly stri
 
 /**
  * Whether the projection reaches a specific WRITE route — an EXACT `path` whose
- * admitted `methods` include `method`. This is the method-aware companion to
+ * admitted `methods` include `method`. A templated route is listed under its template
+ * path (`/api/presets/{name}`) with the methods the caller's grant admits on a
+ * representative instance of it, so a caller names the template on both sides. This is the method-aware companion to
  * {@link coversAnyRoute}: a read/nav surface gates path-only (any method reaching a
  * prefix means the surface is navigable), but an action that issues `method path`
  * must gate on the method too, or a caller whose jq fence admits only GET on `path`
  * would be shown a control that 403s on submit (projection ⊆ gate).
  *
- * Only concrete `routes` are consulted: dynamic `route_patterns` carry no method, so
- * no write capability can be soundly inferred from them, and a synthetic TOTAL
+ * Only `routes` are consulted: dynamic `route_patterns` carry no method, so no write
+ * capability can be soundly inferred from them, and a synthetic TOTAL
  * (admin) projection carries no concrete `routes` at all — callers short-circuit it
  * with {@link isFullProjection} before reaching here. Under-showing is safe (the
  * server stays the authority); over-showing an action the gate denies is the bug.
@@ -191,10 +193,11 @@ export function coversRoute(projection: MeProjection, path: string, method: stri
  * `method path`. While the projection is loading/failed it is `false` — a write control
  * never enables before the gate is known (fail closed; not-ready ⇒ disabled/read-only).
  *
- * Only concrete `routes` carry methods, so a DYNAMIC (templated) write route — one the
- * projection can represent only as a method-less `route_patterns` row — reads `false` for
- * every non-admin caller and degrades that control to read-only. Under-showing is safe
- * (the server stays the authority); over-showing a write the gate denies is the bug.
+ * A templated write route is gated by its template path: the projection lists it with
+ * the methods the caller's grant admits on a representative instance. A credential fenced
+ * per instance is decided at the server, which answers 403 on submit where the fence
+ * denies that instance. Under-showing is safe (the server stays the authority);
+ * over-showing a write the gate denies is the bug.
  */
 export function coversWrite(state: CapabilityState, path: string, method: string): boolean {
   return (
@@ -217,3 +220,49 @@ export function useCanWrite(path: string, method = 'POST'): boolean {
   const { state } = useCapabilities();
   return coversWrite(state, path, method);
 }
+
+/** The session's own identity, as the execution-key pickers offer it. */
+export interface OwnIdentity {
+  readonly userId: string;
+  /** 'account' when the session is a principal itself (no owner claim, a principal row): the bind check refuses
+   * it. 'key' otherwise: an owned api key, or a key with no owner. */
+  readonly kind: 'key' | 'account';
+  readonly admin: boolean;
+}
+
+/** How a form binds the execution key a stored record runs as, read from the session's projection. */
+export type ExecutionKeyBinding =
+  /** The projection is not ready (loading, or failed: the shell shows its own error); the form cannot submit. */
+  | { readonly mode: 'pending' }
+  /** Access control is off: no identity is checked, no key field is shown, a blank key is sent as `fillKey`. */
+  | { readonly mode: 'unchecked'; readonly fillKey: string }
+  /** Access control is on: the key list, plus the session's own identity. */
+  | { readonly mode: 'checked'; readonly own: OwnIdentity };
+
+/** The execution-key binding a capability state implies. */
+export function executionKeyBindingOf(state: CapabilityState): ExecutionKeyBinding {
+  if (state.status !== 'ready') return { mode: 'pending' };
+  const { projection } = state;
+  if (!projection.access_control_enabled) {
+    return { mode: 'unchecked', fillKey: projection.user_id };
+  }
+  return {
+    mode: 'checked',
+    own: {
+      userId: projection.user_id,
+      kind: projection.owner_user_id === null && projection.principal !== null ? 'account' : 'key',
+      admin: projection.admin,
+    },
+  };
+}
+
+/** The execution-key binding of the live session. */
+export function useExecutionKeyBinding(): ExecutionKeyBinding {
+  const { state } = useCapabilities();
+  return useMemo(() => executionKeyBindingOf(state), [state]);
+}
+
+/** The key a write sends: the form's value; with access control off and a blank value, the fill key. */
+export function boundExecutionKey(value: string, binding: ExecutionKeyBinding): string {
+  return binding.mode === 'unchecked' && value.trim() === '' ? binding.fillKey : value;
+}

package/src/index.ts

@@ -42,6 +42,8 @@ import './components/components.css';
 // -- Plugin API --------------------------------------------------------------
 export type {
   ChannelConversationRoute,
+  HolderLinkContribution,
+  HolderLinkTarget,
   NavEntryContribution,
   NavEntrySection,
   PageContribution,
@@ -50,6 +52,7 @@ export type {
   PluginEntry,
   PluginPageParamsSchema,
   PluginPageProps,
+  RegisteredHolderLink,
   RegisteredNavEntry,
   RegisteredPage,
   RegisteredRoutePanel,
@@ -65,7 +68,7 @@ export type {
 export type { VersionGateResult } from './plugin/version';
 export { checkPluginApiVersion, STUDIO_PLUGIN_API_VERSION } from './plugin/version';
 /** What `useApi().runTool` resolves with: the run-tool door's answer, read by its `kind`. */
-export type { RunAnswer } from '@tai42/api-client';
+export type { ReferenceHolder, RunAnswer } from '@tai42/api-client';
 
 // -- Hooks -------------------------------------------------------------------
 export type { ApiClient } from './hooks/useApi';
@@ -74,8 +77,14 @@ export type { AuthState } from './hooks/useAuth';
 export { AuthProvider, useAuth } from './hooks/useAuth';
 export type { Breakpoint, BreakpointState } from './hooks/useBreakpoint';
 export { useBreakpoint } from './hooks/useBreakpoint';
-export type { CapabilityContextValue, CapabilityState } from './hooks/useCapabilities';
+export type {
+  CapabilityContextValue,
+  CapabilityState,
+  ExecutionKeyBinding,
+  OwnIdentity,
+} from './hooks/useCapabilities';
 export {
+  boundExecutionKey,
   CapabilityProvider,
   coversAnyRoute,
   coversRoute,
@@ -83,6 +92,7 @@ export {
   isFullProjection,
   useCanWrite,
   useCapabilities,
+  useExecutionKeyBinding,
 } from './hooks/useCapabilities';
 export type {
   InteractionsStreamOptions,
@@ -118,6 +128,7 @@ export type {
   NavigationContextValue,
   NavigationGuardHandler,
   PageProps,
+  PluginHolderTarget,
   PluginNavigateOptions,
   PluginSearch,
   RouteSearch,
@@ -141,7 +152,7 @@ export {
 export { downloadBlob } from './download';
 export type { EnvRef } from './env-markers';
 export { collectEnvRefs, ENV_MARKER_PREFIX, formatEnvMarker, parseEnvMarker } from './env-markers';
-export { errorMessage } from './errors';
+export { errorMessage, isForbiddenError } from './errors';
 
 // -- Disabled-feature idiom (one helper + component, every consumer) ----------
 export type { FeatureDisabledProps } from './feature-disabled';
@@ -149,8 +160,21 @@ export { FeatureDisabled, featureDisabledMessage, isFeatureDisabled } from './fe
 
 // -- Cross-feature query keys ------------------------------------------------
 export {
+  agentsListKey,
+  channelsListKey,
+  envConfigKey,
   extensionsQueryKey,
+  installedMarketplacePluginsKey,
+  marketplacePluginKey,
+  mcpAdvertisedToolsKey,
+  mcpConfigSchemaKey,
+  mcpEnvRefsKey,
+  mcpExtensionsKey,
+  mcpFailedKey,
+  mcpStatusKey,
+  preservedManifestKey,
   statesListKey,
+  stateTemplateRefereesKey,
   stateTemplatesKey,
   subMcpKey,
   tokensPayloadKey,
@@ -167,6 +191,8 @@ export { effectiveHidden, hiddenToolNames } from './tool-visibility';
 export { mergeToolBadges, toolBadgesByName } from './tool-badges';
 
 // -- Design system -----------------------------------------------------------
+export type { ActionMenuItem, ActionMenuProps } from './components/action-menu';
+export { ActionMenu } from './components/action-menu';
 export type { BadgeProps } from './components/badge';
 export { Badge } from './components/badge';
 export type { CheckboxProps } from './components/checkbox';
@@ -298,10 +324,19 @@ export {
   FolderPicker,
   FolderRow,
 } from './components/folder-nav';
+export type {
+  HolderHref,
+  HolderListProps,
+  HolderPreviewProps,
+  HolderPreviewState,
+} from './components/holder-list';
+export { HolderList, HolderPreview, previewHolders, useHolderHref } from './components/holder-list';
 export type { HeadingLevel, MarkdownBlock, MarkdownProps } from './components/markdown';
 export { Markdown, parseMarkdown } from './components/markdown';
 export type { OpenTargetOptions, OpenTargetProps } from './components/open-target';
 export { openTargetProps } from './components/open-target';
+export type { RecycleRollSectionProps } from './components/recycle-roll';
+export { RecycleRollSection } from './components/recycle-roll';
 export type {
   MediaDocumentProps,
   MediaImageProps,
@@ -316,21 +351,28 @@ export {
   MediaPlayer,
   resolveMediaSrc,
 } from './components/served-media';
+export type { StepperProps, StepperStatus, StepperStep } from './components/stepper';
+export { Stepper } from './components/stepper';
+// The marketplace install UI; its directory index lists the published names.
+export * from './marketplace-install';
 // The URL half of the link-safety pair: `isSafeHttpUrl` answers yes/no, this one
 // hands back the parsed URL, so a caller that needs the URL does not re-parse it.
+export type { AgentListQuery, AgentPickerProps } from './components/agent-picker';
+export { AgentPicker } from './components/agent-picker';
+export type { ChannelListQuery, ChannelPickerProps } from './components/channel-picker';
+export { channelIdentityHint, ChannelPicker } from './components/channel-picker';
 export type { CopyFieldProps } from './components/copy-field';
 export { CopyField } from './components/copy-field';
 export type { ExecutionKeyPickerProps, ExecutionKeyQuery } from './components/execution-key-picker';
-export { ExecutionKeyPicker, isExecutionKeyListEmpty } from './components/execution-key-picker';
+export {
+  canHoldExecutionKey,
+  ExecutionKeyPicker,
+  isExecutionKeyListEmpty,
+} from './components/execution-key-picker';
 export type { ExtensionComboBuilderProps } from './components/extension-combo-builder';
 export { ExtensionComboBuilder } from './components/extension-combo-builder';
-export type { ExtensionFamily, ExtensionKindGroup } from './components/extension-grouping';
-export {
-  baseNameOf,
-  groupByKind,
-  groupIntoFamilies,
-  kindVariant,
-} from './components/extension-grouping';
+export type { ExtensionKindGroup } from './components/extension-grouping';
+export { groupByKind } from './components/extension-grouping';
 export type { ExtensionPickerProps } from './components/extension-picker';
 export { ExtensionPicker } from './components/extension-picker';
 export type { ExternalLinkButtonProps } from './components/external-link';
@@ -347,7 +389,7 @@ export {
 } from './components/subject-section';
 export type { TokenName } from './components/tokens';
 export { TOKEN_NAMES } from './components/tokens';
-export type { ToolPickerProps } from './components/tool-picker';
+export type { ToolListQuery, ToolPickerProps } from './components/tool-picker';
 export { BADGES_NOTE, ToolPicker } from './components/tool-picker';
 export type {
   VersionHistoryEntry,
@@ -374,7 +416,6 @@ export {
   DashboardIcon,
   DatabaseIcon,
   EditIcon,
-  ExtensionsIcon,
   ExternalLinkIcon,
   EyeIcon,
   EyeOffIcon,
@@ -406,7 +447,6 @@ export {
   StorageIcon,
   SunIcon,
   SystemIcon,
-  TemplatesIcon,
   ToolsIcon,
   UnplugIcon,
   XCircleIcon,

package/src/marketplace-install/env-var-fields.tsx

@@ -0,0 +1,59 @@
+import type { ReactNode } from 'react';
+
+import { Checkbox } from '../components/checkbox';
+import { Field } from '../components/field';
+import { TextInput } from '../components/inputs';
+
+/**
+ * One input + secret toggle per required env var, fully controlled. `requiredSecret`
+ * is the server's per-var secret-ness: a `true` var (an OAuth client secret) is
+ * LOCKED on — the server masks it regardless, so an off toggle would lie — while a
+ * `false` var starts off and stays free. `hints` names the item that needs each var.
+ */
+export function EnvVarFields({
+  requiredVars,
+  values,
+  secret,
+  requiredSecret,
+  hints,
+  onChangeValue,
+  onToggleSecret,
+}: {
+  readonly requiredVars: readonly string[];
+  readonly values: Record<string, string>;
+  readonly secret: Record<string, boolean>;
+  readonly requiredSecret?: Record<string, boolean>;
+  readonly hints?: Record<string, string>;
+  readonly onChangeValue: (name: string, value: string) => void;
+  readonly onToggleSecret: (name: string, checked: boolean) => void;
+}): ReactNode {
+  return (
+    <>
+      {requiredVars.map((name) => {
+        const locked = requiredSecret?.[name] === true;
+        const hint = hints?.[name];
+        return (
+          <div key={name} className="tai-stack tai-stack-2">
+            <Field label={name}>
+              <TextInput
+                value={values[name] ?? ''}
+                onChange={(event) => {
+                  onChangeValue(name, event.currentTarget.value);
+                }}
+              />
+            </Field>
+            {hint !== undefined ? <span className="tai-muted">Required by {hint}</span> : null}
+            <Checkbox
+              checked={secret[name] === true}
+              disabled={locked}
+              onCheckedChange={(checked) => {
+                onToggleSecret(name, checked);
+              }}
+              label="Store as secret"
+            />
+          </div>
+        );
+      })}
+    </>
+  );
+}

package/src/marketplace-install/index.ts

@@ -0,0 +1,17 @@
+/**
+ * The marketplace install UI the package publishes: the install and update forms,
+ * the install report, and the helpers a screen composes them with. The Marketplace
+ * detail screen and the Connectors flow render the same forms and the same report.
+ */
+export type { InstallReportProps } from './install-report';
+export { InstallReport } from './install-report';
+export type { MountInstallDialogProps } from './mount-install';
+export { MountInstallDialog, MountInstallForm } from './mount-install';
+export { deliveryOf } from './plugin-detail';
+export type { PluginInstallProps } from './plugin-install';
+export { INSTALL_NO_GRANT, PluginInstallDialog, PluginInstallPanel } from './plugin-install';
+export type { RouteItem } from './route-items';
+export { routeItemsOf } from './route-items';
+export { useDebouncedValue } from './use-debounced-value';
+export type { InstallAction, InstallActionState } from './use-install-action';
+export { useInstallAction } from './use-install-action';

package/src/marketplace-install/install-env.ts

@@ -0,0 +1,39 @@
+/** The secret bands for the install env form: which collected vars are marked
+ * secret, and which are LOCKED secret (the server masks them regardless). */
+
+/** One required-env entry as the install preview reports it. */
+export interface PreviewEnvRequirement {
+  readonly name: string;
+  readonly secret: boolean;
+}
+
+export interface InstallEnvBands {
+  /** Per var, whether its value is treated as a secret (preview, detail, or override). */
+  readonly secretMap: Record<string, boolean>;
+  /** Per var, whether the secret mark is LOCKED on (preview or detail says secret). */
+  readonly lockedSecret: Record<string, boolean>;
+}
+
+/**
+ * Fold the preview's authority, the detail-derived fallback, and the operator's
+ * per-var override into the two bands the env fields render from. A var the preview
+ * or the detail marks secret is LOCKED on (an off toggle would lie, since the server
+ * masks it regardless); the override only turns a free var on.
+ */
+export function installEnvBands(
+  missingVars: readonly string[],
+  previewRequired: readonly PreviewEnvRequirement[],
+  detailSecret: Record<string, boolean>,
+  override: Record<string, boolean>,
+): InstallEnvBands {
+  const previewSecret: Record<string, boolean> = {};
+  for (const req of previewRequired) previewSecret[req.name] = req.secret;
+  const secretMap: Record<string, boolean> = {};
+  const lockedSecret: Record<string, boolean> = {};
+  for (const name of missingVars) {
+    const locked = previewSecret[name] === true || detailSecret[name] === true;
+    lockedSecret[name] = locked;
+    secretMap[name] = locked || override[name] === true;
+  }
+  return { secretMap, lockedSecret };
+}

package/src/marketplace-install/install-mount.ts

@@ -0,0 +1,96 @@
+/**
+ * Pure model for the route-mounting install flow: the env value/secret split, the
+ * per-var secret band derivation, and the install/update body assembly.
+ */
+import type { MarketplaceInstallPreview } from '@tai42/api-client';
+
+/** The install/update body fields the mount form contributes. */
+export interface InstallExtras {
+  route_mounts: Record<string, string>;
+  accept_public_routes: boolean;
+  env?: Record<string, string>;
+  secret_keys?: string[];
+}
+
+/**
+ * The env value + secret-key split from the collected inputs: a blank field is
+ * omitted (the deployment may already provide it); a filled field is marked secret
+ * only when its toggle is ON.
+ *
+ * The toggle state is SEEDED from the server's per-var `required_env[].secret`, so
+ * secret-ness comes from that authority, not a blanket default: a `secret: true`
+ * var (an OAuth client secret) is masked, a `secret: false` var (a client id) is
+ * not unless the operator turns it on. Keying off `=== true` honors an off toggle
+ * and never force-masks — an un-seeded var stays out of the secret band.
+ */
+export function collectEnv(
+  requiredVars: readonly string[],
+  values: Record<string, string>,
+  secret: Record<string, boolean>,
+): { env: Record<string, string>; secretKeys: string[] } {
+  const env: Record<string, string> = {};
+  const secretKeys: string[] = [];
+  for (const name of requiredVars) {
+    const value = values[name] ?? '';
+    if (value === '') continue;
+    env[name] = value;
+    if (secret[name] === true) secretKeys.push(name);
+  }
+  return { env, secretKeys };
+}
+
+/**
+ * The effective per-var secret band for the vars to collect: the SERVER's per-var
+ * `required_env[].secret` from the preview (the authority), OR the caller-supplied
+ * `requiredEnvSecret`, OR an operator override.
+ */
+export function deriveEnvSecretMap(
+  envToCollect: readonly string[],
+  preview: MarketplaceInstallPreview | undefined,
+  requiredEnvSecret: Record<string, boolean> | undefined,
+  envSecretOverride: Record<string, boolean>,
+): Record<string, boolean> {
+  const previewEnvSecret: Record<string, boolean> = {};
+  for (const req of preview?.required_env ?? []) previewEnvSecret[req.name] = req.secret;
+  return Object.fromEntries(
+    envToCollect.map((name) => [
+      name,
+      previewEnvSecret[name] === true ||
+        requiredEnvSecret?.[name] === true ||
+        envSecretOverride[name] === true,
+    ]),
+  );
+}
+
+/**
+ * Assemble the install/update body. INSTALL sends every base (declared default is
+ * correct). UPDATE sends ONLY the items whose base changed from its current stored
+ * base — omitted items are preserved by the server's stored-mount precedence, so a
+ * plugin installed at a non-default base is never reset to default on an edit-free
+ * update. Collected env is attached only when at least one value was filled.
+ */
+export function buildInstallExtras(
+  verb: 'Install' | 'Update',
+  bases: Record<string, string>,
+  seededBases: Record<string, string>,
+  accepted: boolean,
+  envToCollect: readonly string[],
+  envValues: Record<string, string>,
+  envSecretMap: Record<string, boolean>,
+): InstallExtras {
+  const route_mounts =
+    verb === 'Update'
+      ? Object.fromEntries(
+          Object.entries(bases).filter(([name, base]) => base !== seededBases[name]),
+        )
+      : bases;
+  const extras: InstallExtras = { route_mounts, accept_public_routes: accepted };
+  if (envToCollect.length > 0) {
+    const { env, secretKeys } = collectEnv(envToCollect, envValues, envSecretMap);
+    if (Object.keys(env).length > 0) {
+      extras.env = env;
+      extras.secret_keys = secretKeys;
+    }
+  }
+  return extras;
+}

package/src/marketplace-install/install-report.tsx

@@ -0,0 +1,54 @@
+/**
+ * The fleet side of an install, update or uninstall: the reload fan-out report and,
+ * when the reload recycled workers, the roll. The host folds the receipt's
+ * `reload.fanout` / `awaiting_respawn` / `span_release_error` into `summary` with
+ * `summarizeFleetFanout` and passes `reload.recycle` as `recycle`.
+ */
+import type { FleetReportSummary, RecycleRoll } from '@tai42/api-client';
+import { type CSSProperties, type ReactNode, useId } from 'react';
+
+import { FleetReport } from '../components/fleet-report';
+import { RecycleRollSection } from '../components/recycle-roll';
+
+export interface InstallReportProps {
+  readonly summary: FleetReportSummary | null;
+  readonly recycle: RecycleRoll | null;
+}
+
+const sectionTitleStyle: CSSProperties = {
+  margin: '0 0 var(--tai-space-2)',
+  fontSize: 'var(--tai-text-md)',
+  color: 'var(--tai-color-text)',
+};
+
+const sectionIntroStyle: CSSProperties = {
+  margin: '0 0 var(--tai-space-3)',
+  color: 'var(--tai-color-text-muted)',
+  fontSize: 'var(--tai-text-sm)',
+};
+
+export function InstallReport({ summary, recycle }: InstallReportProps): ReactNode {
+  const headingId = useId();
+  return (
+    <div className="tai-stack tai-stack-3">
+      <FleetReport summary={summary} />
+      {recycle !== null ? (
+        <section aria-labelledby={headingId}>
+          <h4 id={headingId} style={sectionTitleStyle}>
+            Worker recycle
+          </h4>
+          <p style={sectionIntroStyle}>
+            Some changed settings take effect only in a fresh worker process, so the fleet recycled
+            its workers one at a time.
+          </p>
+          <RecycleRollSection
+            recycle={recycle.recycle}
+            fresh={recycle.fresh}
+            stopped={recycle.recycle_stopped}
+            writerNote="this worker recycles itself after replying"
+          />
+        </section>
+      ) : null}
+    </div>
+  );
+}

package/src/marketplace-install/install-shell.tsx

@@ -0,0 +1,99 @@
+/**
+ * The two frames an install form renders in: a dialog (the confirm shell) or a panel
+ * in place (its own `<form>` with Cancel and the submit button), so a step can embed
+ * the form without a dialog inside a dialog. The failure of the last call renders
+ * inside the frame and the frame stays open.
+ */
+import type { ReactNode, SyntheticEvent } from 'react';
+
+import { ConfirmDialog } from '../components/confirm-dialog';
+import { Button, ErrorState, Spinner } from '../components/primitives';
+import { errorMessage } from '../errors';
+import { FeatureDisabled, featureDisabledMessage, isFeatureDisabled } from '../feature-disabled';
+
+export type InstallLayout = 'panel' | 'dialog';
+
+/**
+ * The muted note for a store-off refusal (an OFF feature is a state, not an error),
+ * or `undefined` for any other value.
+ */
+export function storeOffNote(error: unknown): ReactNode {
+  if (!isFeatureDisabled(error)) return undefined;
+  return <FeatureDisabled feature="Marketplace installs" message={featureDisabledMessage(error)} />;
+}
+
+/** A failed call's surface: the store-off note, else the server message as an alert. */
+export function InstallFailure({ error }: { readonly error: unknown }): ReactNode {
+  return storeOffNote(error) ?? <ErrorState message={errorMessage(error)} />;
+}
+
+export interface InstallShellProps {
+  readonly layout: InstallLayout;
+  readonly title: string;
+  readonly submitLabel: string;
+  readonly pendingLabel: string;
+  readonly isPending: boolean;
+  /** The loud failure; `null` while there is none. */
+  readonly error: unknown;
+  /** A muted note that takes the failure slot and blocks the submit. */
+  readonly disabledNote?: ReactNode;
+  readonly submitDisabled?: boolean;
+  readonly onSubmit: () => void;
+  readonly onDismiss: () => void;
+  readonly children: ReactNode;
+}
+
+export function InstallShell({
+  layout,
+  title,
+  submitLabel,
+  pendingLabel,
+  isPending,
+  error,
+  disabledNote,
+  submitDisabled = false,
+  onSubmit,
+  onDismiss,
+  children,
+}: InstallShellProps): ReactNode {
+  const errorText = error === null || error === undefined ? null : errorMessage(error);
+  if (layout === 'dialog') {
+    return (
+      <ConfirmDialog
+        title={title}
+        confirmLabel={submitLabel}
+        pendingLabel={pendingLabel}
+        confirmVariant="primary"
+        isPending={isPending}
+        error={errorText}
+        disabledNote={disabledNote}
+        confirmDisabled={submitDisabled}
+        onConfirm={onSubmit}
+        onClose={onDismiss}
+      >
+        {children}
+      </ConfirmDialog>
+    );
+  }
+  const blocked =
+    isPending || submitDisabled || (disabledNote !== undefined && disabledNote !== null);
+  const handleSubmit = (event: SyntheticEvent<HTMLFormElement>): void => {
+    event.preventDefault();
+    if (!blocked) onSubmit();
+  };
+  return (
+    <form aria-label={title} className="tai-stack tai-stack-3" onSubmit={handleSubmit}>
+      {children}
+      {disabledNote ?? (errorText !== null ? <ErrorState message={errorText} /> : null)}
+      <div className="tai-dialog-actions">
+        <Button type="button" onClick={onDismiss}>
+          Cancel
+        </Button>
+        <Button type="submit" variant="primary" disabled={blocked}>
+          {isPending ? <Spinner label={pendingLabel} /> : null}
+          {submitLabel}
+        </Button>
+      </div>
+    </form>
+  );
+}