@tai42/studio-sdk 0.2.0 → 0.3.0

package/src/components/folder-nav.tsx

@@ -0,0 +1,255 @@
+/**
+ * Folder navigation primitives for the tool-organization tree — shared by the tools
+ * screen and PLAN_4's flows page so both explore, breadcrumb, and re-file against
+ * one identical set of controls.
+ *
+ * The tree is passed FLAT (a {@link Folder} list keyed by `id`, each naming its
+ * `parentId`); these helpers derive the current directory, the breadcrumb path, and
+ * the indented picker options from it. Every derivation is cycle-SAFE: a malformed
+ * parent chain (a loop, a dangling parent) is bounded by the folder count rather than
+ * looping forever — bad data degrades to a truncated path, never a hang.
+ *
+ * `FolderPicker` carries inline new-folder creation, so a folder can be created from
+ * BOTH consuming screens through this one component — never a flows-page-only
+ * affordance.
+ */
+import { useState, type ReactNode } from 'react';
+
+import { ChevronRightIcon, FolderIcon } from './icons';
+import { Button } from './primitives';
+import { Select } from './select';
+import { TextInput } from './inputs';
+
+/** A folder in the tree, in the SDK's camelCase UI shape (`parentId`, `null` = root). */
+export interface Folder {
+  readonly id: string;
+  readonly name: string;
+  readonly parentId: string | null;
+}
+
+/** The subfolders directly under `parentId` (`null` = the root directory), name-sorted. */
+export function childFolders(folders: readonly Folder[], parentId: string | null): Folder[] {
+  return folders
+    .filter((folder) => folder.parentId === parentId)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * The ordered ancestor path from the root down to (and including) `folderId`, for a
+ * breadcrumb. `null` is the root (an empty path). The walk is bounded by the folder
+ * count, so a cyclic or dangling chain truncates instead of looping.
+ */
+export function folderPathTo(folders: readonly Folder[], folderId: string | null): Folder[] {
+  if (folderId === null) return [];
+  const byId = new Map(folders.map((folder) => [folder.id, folder]));
+  const path: Folder[] = [];
+  const seen = new Set<string>();
+  let current: string | null = folderId;
+  while (current !== null && !seen.has(current)) {
+    seen.add(current);
+    const folder = byId.get(current);
+    if (folder === undefined) break;
+    path.unshift(folder);
+    current = folder.parentId;
+  }
+  return path;
+}
+
+export interface FolderBreadcrumbProps {
+  readonly folders: readonly Folder[];
+  readonly currentFolderId: string | null;
+  readonly onNavigate: (folderId: string | null) => void;
+  /** The root crumb's label (e.g. "All tools"). */
+  readonly rootLabel: string;
+}
+
+/** The root → … → current path; each crumb navigates to that level. */
+export function FolderBreadcrumb({
+  folders,
+  currentFolderId,
+  onNavigate,
+  rootLabel,
+}: FolderBreadcrumbProps): ReactNode {
+  const path = folderPathTo(folders, currentFolderId);
+  return (
+    <nav className="tai-row" aria-label="Folder path">
+      <Button
+        variant="ghost"
+        onClick={() => {
+          onNavigate(null);
+        }}
+        aria-current={currentFolderId === null ? 'page' : undefined}
+      >
+        {rootLabel}
+      </Button>
+      {path.map((folder) => (
+        <span key={folder.id} className="tai-row">
+          <ChevronRightIcon />
+          <Button
+            variant="ghost"
+            onClick={() => {
+              onNavigate(folder.id);
+            }}
+            aria-current={folder.id === currentFolderId ? 'page' : undefined}
+          >
+            {folder.name}
+          </Button>
+        </span>
+      ))}
+    </nav>
+  );
+}
+
+export interface FolderRowProps {
+  readonly folder: Folder;
+  readonly onOpen: (folderId: string) => void;
+}
+
+/** One subfolder in the current-directory explorer; opening it navigates inward. */
+export function FolderRow({ folder, onOpen }: FolderRowProps): ReactNode {
+  return (
+    <Button
+      variant="ghost"
+      onClick={() => {
+        onOpen(folder.id);
+      }}
+    >
+      <FolderIcon />
+      <span>{folder.name}</span>
+    </Button>
+  );
+}
+
+/** The sentinel option value for "no folder" — folder ids are UUIDs, so it never collides. */
+const UNFILED_VALUE = '__unfiled__';
+
+/** Flatten the tree into indented `Select` options, root first, depth-first. */
+function folderOptions(folders: readonly Folder[]): { value: string; label: string }[] {
+  const options: { value: string; label: string }[] = [];
+  const walk = (parentId: string | null, depth: number): void => {
+    for (const folder of childFolders(folders, parentId)) {
+      options.push({ value: folder.id, label: `${'  '.repeat(depth)}${folder.name}` });
+      walk(folder.id, depth + 1);
+    }
+  };
+  walk(null, 0);
+  return options;
+}
+
+export interface FolderPickerProps {
+  /** The chosen folder id, or `null` for unfiled. */
+  readonly value: string | null;
+  readonly onChange: (folderId: string | null) => void;
+  readonly folders: readonly Folder[];
+  /**
+   * Create a folder under `parentId` (the current selection) and resolve with its
+   * id; the picker selects it. Rejection is the caller's to surface — the picker
+   * leaves the draft in place so the operator can retry.
+   */
+  readonly onCreateFolder: (name: string, parentId: string | null) => Promise<string>;
+  readonly disabled?: boolean;
+  /** The unfiled option's label (e.g. "No folder"). */
+  readonly unfiledLabel: string;
+}
+
+/** A folder chooser with inline new-folder creation, for the edit / move dialogs. */
+export function FolderPicker({
+  value,
+  onChange,
+  folders,
+  onCreateFolder,
+  disabled,
+  unfiledLabel,
+}: FolderPickerProps): ReactNode {
+  const [creating, setCreating] = useState(false);
+  const [draft, setDraft] = useState('');
+  const [busy, setBusy] = useState(false);
+
+  const options = [{ value: UNFILED_VALUE, label: unfiledLabel }, ...folderOptions(folders)];
+
+  const create = async (): Promise<void> => {
+    const name = draft.trim();
+    if (name === '' || busy) return;
+    setBusy(true);
+    try {
+      const id = await onCreateFolder(name, value);
+      onChange(id);
+      setDraft('');
+      setCreating(false);
+    } catch {
+      // The caller owns surfacing the failure (its `onCreateFolder` is the loud
+      // surface); the picker's part is to keep the draft OPEN with its text so the
+      // operator can retry — never to clear it or select nothing.
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <div className="tai-stack tai-stack-2">
+      <Select
+        aria-label="Folder"
+        options={options}
+        value={value ?? UNFILED_VALUE}
+        onValueChange={(next) => {
+          onChange(next === UNFILED_VALUE ? null : next);
+        }}
+        disabled={disabled ?? busy}
+      />
+      {creating ? (
+        <div className="tai-row">
+          <div style={{ flex: 1 }}>
+            <TextInput
+              value={draft}
+              onChange={(event) => {
+                setDraft(event.target.value);
+              }}
+              onKeyDown={(event) => {
+                if (event.key === 'Enter') {
+                  event.preventDefault();
+                  void create();
+                }
+              }}
+              placeholder="New folder name…"
+              aria-label="New folder name"
+              disabled={busy}
+            />
+          </div>
+          <Button
+            type="button"
+            variant="primary"
+            onClick={() => {
+              void create();
+            }}
+            disabled={busy || draft.trim() === ''}
+          >
+            Create
+          </Button>
+          <Button
+            type="button"
+            variant="ghost"
+            onClick={() => {
+              setCreating(false);
+              setDraft('');
+            }}
+            disabled={busy}
+          >
+            Cancel
+          </Button>
+        </div>
+      ) : (
+        <Button
+          type="button"
+          variant="ghost"
+          onClick={() => {
+            setCreating(true);
+          }}
+          disabled={disabled}
+        >
+          <FolderIcon />
+          <span>New folder</span>
+        </Button>
+      )}
+    </div>
+  );
+}

package/src/components/icons.tsx

@@ -477,6 +477,23 @@ export const PendingIcon: IconComponent = (props) => (
   </Icon>
 );
 
+/** Folder: a tabbed folder, for the tool-organization tree and breadcrumbs. */
+export const FolderIcon: IconComponent = (props) => (
+  <Icon {...props}>
+    <path d="M3 6.5a2 2 0 0 1 2-2h4l2 2.5h6a2 2 0 0 1 2 2v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
+  </Icon>
+);
+
+/** Grid: a 2x2 tile array — the card-view half of the list/card toggle. */
+export const GridIcon: IconComponent = (props) => (
+  <Icon {...props}>
+    <rect x="4" y="4" width="7" height="7" rx="1.5" />
+    <rect x="13" y="4" width="7" height="7" rx="1.5" />
+    <rect x="4" y="13" width="7" height="7" rx="1.5" />
+    <rect x="13" y="13" width="7" height="7" rx="1.5" />
+  </Icon>
+);
+
 // -- Route mapping -----------------------------------------------------------
 
 /**

package/src/components/overlay-details-fields.tsx

@@ -0,0 +1,102 @@
+/**
+ * `OverlayDetailsFields` — the display-name + user-tags editor shared by EVERY
+ * tool_meta edit surface (the tools-screen edit dialog, the presets screen, and
+ * PLAN_4's flows page). One canonical control means the merge-patch write semantics
+ * exist exactly once.
+ *
+ * Controlled: the caller owns `value` (prefilled from the tool's overlay row) and
+ * receives every keystroke through `onChange`. This component edits ONLY the two
+ * overlay fields it shows; the write it feeds ({@link overlayDetailsPatch}) sends
+ * ONLY `display_name` and `tags`, so the merge-patch API leaves `folder_id`/`hidden`
+ * untouched — never re-sent from a baseline.
+ *
+ * Display-name mapping is PINNED (the API rejects `""` with a 422): a blank or
+ * whitespace-only input maps to `display_name: null` (clear the override); trimmed
+ * non-empty text is sent as-is. That rule lives in {@link overlayDetailsPatch}, so
+ * every consumer clears identically.
+ *
+ * `nativeTags` (optional) renders the tool's read-only plugin-native tags as
+ * visually DISTINCT chips beside the editable input — the one place native and
+ * overlay tags are shown apart (every other surface merges them).
+ */
+import type { ReactNode } from 'react';
+
+import { Field } from './field';
+import { TextInput } from './inputs';
+import { TagChips, TagsInput } from './tags';
+
+/** The two overlay fields this control edits. */
+export interface OverlayDetails {
+  /** The raw display-name draft (unblank-normalized only at write time). */
+  readonly displayName: string;
+  readonly tags: readonly string[];
+}
+
+export interface OverlayDetailsFieldsProps {
+  readonly value: OverlayDetails;
+  readonly onChange: (next: OverlayDetails) => void;
+  readonly disabled?: boolean;
+  /**
+   * The tool's real name, shown as the display-name input's placeholder so an empty
+   * override reads as "falls back to <name>".
+   */
+  readonly namePlaceholder?: string;
+  /**
+   * Read-only plugin-native tags, rendered as distinct chips. Present only in the
+   * edit surfaces that want native and overlay tags shown apart.
+   */
+  readonly nativeTags?: readonly string[];
+}
+
+/** The merge-patch a display-name + tags write sends: ONLY these two fields. */
+export function overlayDetailsPatch(value: OverlayDetails): {
+  display_name: string | null;
+  tags: string[];
+} {
+  const trimmed = value.displayName.trim();
+  return { display_name: trimmed === '' ? null : trimmed, tags: [...value.tags] };
+}
+
+export function OverlayDetailsFields({
+  value,
+  onChange,
+  disabled,
+  namePlaceholder,
+  nativeTags,
+}: OverlayDetailsFieldsProps): ReactNode {
+  return (
+    <div className="tai-stack tai-stack-3">
+      <Field
+        label="Display name"
+        description="Shown instead of the tool's real name. Leave blank to use the real name."
+      >
+        <TextInput
+          value={value.displayName}
+          onChange={(event) => {
+            onChange({ ...value, displayName: event.target.value });
+          }}
+          placeholder={namePlaceholder}
+          disabled={disabled}
+        />
+      </Field>
+      <Field label="Tags" description="Your own labels for grouping and filtering." group>
+        <div className="tai-stack tai-stack-2">
+          {nativeTags !== undefined && nativeTags.length > 0 ? (
+            <div className="tai-stack tai-stack-2">
+              <span className="tai-muted">Native tags (read-only)</span>
+              <TagChips tags={nativeTags} />
+            </div>
+          ) : null}
+          <TagsInput
+            value={value.tags}
+            onChange={(next) => {
+              onChange({ ...value, tags: next });
+            }}
+            disabled={disabled}
+            aria-label="Tags"
+          />
+        </div>
+      </Field>
+    </div>
+  );
+}

package/src/components/view-toggle.tsx

@@ -0,0 +1,92 @@
+/**
+ * `ViewToggle` + `useViewMode` — the list/card switch every entity screen shares.
+ *
+ * The control is a `RadioGroup variant="segmented"` with ICON-ONLY options: each
+ * option's text label is rendered for assistive tech only (`visuallyHiddenLabel`),
+ * so the segment shows just its glyph while keeping a real accessible name. A single
+ * screen's choice persists across sessions in `localStorage`, keyed per SURFACE —
+ * the tools screen and the flows page each remember their own view — via
+ * {@link useViewMode}. The two live in the SDK so every entity screen (and PLAN_4's
+ * flows page) toggles identically; `EntityCardGrid` renders the card half.
+ */
+import { useCallback, useState, type ReactNode } from 'react';
+
+import { GridIcon, MenuIcon } from './icons';
+import { RadioGroup } from './radio-group';
+
+/** The two entity-screen layouts. */
+export type ViewMode = 'list' | 'cards';
+
+const OPTIONS = [
+  { value: 'list', label: 'List view', icon: <MenuIcon />, visuallyHiddenLabel: true },
+  { value: 'cards', label: 'Card view', icon: <GridIcon />, visuallyHiddenLabel: true },
+] as const;
+
+export interface ViewToggleProps {
+  readonly value: ViewMode;
+  readonly onValueChange: (mode: ViewMode) => void;
+  /** The control's accessible group name (e.g. "Tools view"). */
+  readonly 'aria-label': string;
+  readonly disabled?: boolean;
+}
+
+/** The icon-only segmented switch. Controlled: pair it with {@link useViewMode}. */
+export function ViewToggle({
+  value,
+  onValueChange,
+  'aria-label': ariaLabel,
+  disabled,
+}: ViewToggleProps): ReactNode {
+  return (
+    <RadioGroup
+      variant="segmented"
+      orientation="horizontal"
+      aria-label={ariaLabel}
+      options={OPTIONS}
+      value={value}
+      onValueChange={(next) => {
+        // The option values are a closed pair, so the widening back to `ViewMode`
+        // is exact — a stray value could only come from a mismatched options list.
+        onValueChange(next as ViewMode);
+      }}
+      disabled={disabled}
+    />
+  );
+}
+
+const STORAGE_PREFIX = 'tai-studio.view-mode.';
+
+function readStoredMode(surface: string, fallback: ViewMode): ViewMode {
+  try {
+    const raw = globalThis.localStorage.getItem(STORAGE_PREFIX + surface);
+    if (raw === 'list' || raw === 'cards') return raw;
+  } catch {
+    // No storage (private mode / non-browser) — fall back to the caller's default.
+  }
+  return fallback;
+}
+
+/**
+ * The persisted view mode for one `surface` (a stable key like `'tools'`). Returns
+ * the stored choice or `fallback` when none is set, and a setter that writes through
+ * to `localStorage`. Storage failures degrade to in-memory only — never a thrown
+ * boot, matching the theme preference's defensive reads/writes.
+ */
+export function useViewMode(
+  surface: string,
+  fallback: ViewMode = 'list',
+): readonly [ViewMode, (mode: ViewMode) => void] {
+  const [mode, setModeState] = useState<ViewMode>(() => readStoredMode(surface, fallback));
+  const setMode = useCallback(
+    (next: ViewMode) => {
+      setModeState(next);
+      try {
+        globalThis.localStorage.setItem(STORAGE_PREFIX + surface, next);
+      } catch {
+        // Storage unavailable — the choice still applies for this session.
+      }
+    },
+    [surface],
+  );
+  return [mode, setMode];
+}

package/src/index.ts

@@ -32,6 +32,7 @@ export type {
   PluginEntry,
   ToolPanelProps,
   PluginPageProps,
+  PluginPageParamsSchema,
   SettingsTabProps,
   ToolPanelContribution,
   PageContribution,
@@ -70,7 +71,13 @@ export { useInteractionsStream } from './hooks/useSse';
 export type { InteractionsStreamState, StreamInteraction } from './hooks/useSse';
 
 // -- Navigation (shell ⇄ feature route-token contract) -----------------------
-export { NavigationProvider, AppLink, useAppNavigate, useResolvePath } from './navigation';
+export {
+  NavigationProvider,
+  AppLink,
+  useAppNavigate,
+  useResolvePath,
+  usePluginNavigation,
+} from './navigation';
 export type {
   AppLinkProps,
   RouteToken,
@@ -78,6 +85,7 @@ export type {
   RouteSearchByToken,
   PageProps,
   NavigationContextValue,
+  PluginSearch,
 } from './navigation';
 
 // -- Utilities ---------------------------------------------------------------
@@ -90,6 +98,9 @@ export { toolsListKey, extensionsQueryKey, subMcpKey, tokensPayloadKey } from '.
 // -- Extension-combo editing helpers -----------------------------------------
 export { comboElementNames, extensionElementName } from './extension-combos';
 
+// -- Tool-visibility tri-state -----------------------------------------------
+export { effectiveHidden, hiddenToolNames } from './tool-visibility';
+
 // -- Design system -----------------------------------------------------------
 export { Button, Card, Skeleton, EmptyState, ErrorState, Spinner } from './components/primitives';
 export type {
@@ -154,6 +165,28 @@ export { JsonDiff, diffJson } from './components/json-diff';
 export type { JsonDiffProps, JsonDiffRow } from './components/json-diff';
 export { TagChips, TagsInput } from './components/tags';
 export type { TagChipsProps, TagsInputProps } from './components/tags';
+export { OverlayDetailsFields, overlayDetailsPatch } from './components/overlay-details-fields';
+export type {
+  OverlayDetails,
+  OverlayDetailsFieldsProps,
+} from './components/overlay-details-fields';
+export { ViewToggle, useViewMode } from './components/view-toggle';
+export type { ViewMode, ViewToggleProps } from './components/view-toggle';
+export { EntityCardGrid } from './components/entity-card-grid';
+export type { EntityCardGridProps } from './components/entity-card-grid';
+export {
+  FolderBreadcrumb,
+  FolderRow,
+  FolderPicker,
+  childFolders,
+  folderPathTo,
+} from './components/folder-nav';
+export type {
+  Folder,
+  FolderBreadcrumbProps,
+  FolderRowProps,
+  FolderPickerProps,
+} from './components/folder-nav';
 export { CodeBlock } from './components/code-block';
 export type { CodeBlockProps } from './components/code-block';
 export { FleetReport } from './components/fleet-report';
@@ -212,6 +245,8 @@ export {
   SignOutIcon,
   MenuIcon,
   CloseIcon,
+  FolderIcon,
+  GridIcon,
   FilterIcon,
   ArrowLeftIcon,
   ArrowUpIcon,

package/src/navigation/context.tsx

@@ -48,6 +48,21 @@ export function useResolvePath(): NavigationContextValue['resolvePath'] {
   return useNavigation().resolvePath;
 }
 
+/**
+ * Plugin-page navigation: `navigatePlugin` drives a client-side transition to a
+ * runtime plugin path, `resolvePluginPath` yields its href. These are the ONLY
+ * navigation methods a plugin page uses to reach its own deep-linkable sub-paths —
+ * the token-typed {@link useAppNavigate}/{@link useResolvePath} address the shell's
+ * compile-time routes and know nothing of plugin paths.
+ */
+export function usePluginNavigation(): Pick<
+  NavigationContextValue,
+  'navigatePlugin' | 'resolvePluginPath'
+> {
+  const { navigatePlugin, resolvePluginPath } = useNavigation();
+  return { navigatePlugin, resolvePluginPath };
+}
+
 export interface AppLinkProps<T extends RouteToken> {
   to: T;
   search?: RouteSearch<T>;

package/src/navigation/index.ts

@@ -1,4 +1,10 @@
-export { NavigationProvider, AppLink, useAppNavigate, useResolvePath } from './context';
+export {
+  NavigationProvider,
+  AppLink,
+  useAppNavigate,
+  useResolvePath,
+  usePluginNavigation,
+} from './context';
 export type { AppLinkProps } from './context';
 export type {
   RouteToken,
@@ -6,4 +12,5 @@ export type {
   RouteSearchByToken,
   PageProps,
   NavigationContextValue,
+  PluginSearch,
 } from './types';

package/src/navigation/types.ts

@@ -77,14 +77,39 @@ export interface PageProps<T extends RouteToken> {
   search: RouteSearch<T>;
 }
 
+/**
+ * A plugin page's deep-link search object. Plugin paths are RUNTIME contributions
+ * outside the compile-time {@link RouteToken} map, so their search is an open bag of
+ * serializable values (the page's own {@link PluginPageParamsSchema} validates it);
+ * this is deliberately NOT a `RouteSearch`.
+ */
+export type PluginSearch = Record<string, unknown>;
+
 /**
  * The runtime navigation surface the shell provides through
  * {@link NavigationProvider}. `navigate` performs a client-side transition;
  * `resolvePath` produces the href a link should point at (so an AppLink is a real
  * anchor — middle-click / open-in-new-tab work — while still driving a
  * client-side transition on plain click).
+ *
+ * `navigatePlugin`/`resolvePluginPath` are the plugin-page twins: they target a
+ * runtime plugin path (`/plugins/{pluginId}/{pagePath}` plus an optional validated
+ * sub-path `params` and `search`), NOT a route token — `routes.ts` never learns
+ * plugin paths. Plugins reach these two via the {@link usePluginNavigation} hook.
  */
 export interface NavigationContextValue {
   navigate: <T extends RouteToken>(token: T, search?: RouteSearch<T>) => void;
   resolvePath: <T extends RouteToken>(token: T, search?: RouteSearch<T>) => string;
+  navigatePlugin: (
+    pluginId: string,
+    pagePath: string,
+    params?: string,
+    search?: PluginSearch,
+  ) => void;
+  resolvePluginPath: (
+    pluginId: string,
+    pagePath: string,
+    params?: string,
+    search?: PluginSearch,
+  ) => string;
 }

package/src/plugin/types.ts

@@ -45,9 +45,39 @@ export interface ToolPanelProps {
   readonly run: (args: Record<string, unknown>) => Promise<unknown>;
 }
 
-/** Props a contributed full page receives. Navigation is via shell route tokens. */
+/**
+ * Props a contributed full page receives. A page is deep-linkable: the shell mounts
+ * it at `/plugins/{pluginId}/{path}` and, when the contribution declares a
+ * {@link PluginPageParamsSchema}, forwards the VALIDATED sub-path remainder as
+ * `params` and the VALIDATED search object as `search`. Both are OPTIONAL — a page
+ * that declares no schema receives neither (and accepts no sub-path), so this stays
+ * a non-breaking addition to every existing contribution and the plugin API version
+ * does not move. Navigate between plugin pages with `usePluginNavigation`.
+ */
 export interface PluginPageProps {
   readonly pluginId: string;
+  /** The validated sub-path remainder (present only when the page declared a schema). */
+  readonly params?: Record<string, unknown>;
+  /** The validated search object (present only when the page declared a schema). */
+  readonly search?: Record<string, unknown>;
+}
+
+/**
+ * A page's optional deep-link schema. The shell resolves a URL to a page by
+ * LONGEST registered `path` prefix; the remainder of the URL after the matched
+ * prefix is handed to `parseParams`, and the raw search object to `parseSearch`.
+ * Each parser VALIDATES and shapes its input, RAISING on anything it rejects — the
+ * shell renders that throw as a loud error card, never a blank or partial view. A
+ * contribution that omits the schema entirely accepts no sub-path (the pre-deep-link
+ * behavior, unchanged). Omitting just one parser leaves that half unvalidated:
+ * absent `parseParams` means the page still matches only its exact `path`; absent
+ * `parseSearch` means `search` is not forwarded.
+ */
+export interface PluginPageParamsSchema {
+  /** Validate + shape the sub-path remainder after this page's prefix; throws to reject. */
+  readonly parseParams?: (remainder: string) => Record<string, unknown>;
+  /** Validate + shape the raw search object; throws to reject. */
+  readonly parseSearch?: (raw: Record<string, unknown>) => Record<string, unknown>;
 }
 
 /** Props a contributed settings tab receives. */
@@ -67,6 +97,13 @@ export interface PageContribution {
   readonly component: ComponentType<PluginPageProps>;
   /** Capability gate (see {@link RequiredCapabilities}); absent ⇒ full-only. */
   readonly requiredCapabilities?: RequiredCapabilities;
+  /**
+   * Deep-link schema (see {@link PluginPageParamsSchema}). When present the page is
+   * addressable under its `path` PREFIX, and the shell validates the sub-path
+   * remainder + search before rendering. Absent ⇒ the page matches only its exact
+   * `path` and receives no `params`/`search` (unchanged behavior).
+   */
+  readonly params?: PluginPageParamsSchema;
 }
 
 /**