@tai42/studio-sdk 0.2.0 → 0.4.0

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;
 }
 
 /**
@@ -81,6 +118,16 @@ export interface RegisteredPage extends PageContribution {
   readonly pluginId: string;
 }
 
+/**
+ * The sidebar section a nav entry renders in. A named core section groups the
+ * entry there, after that section's core rows; `'Plugins'`, an absent field, or
+ * any unrecognised value falls to the Plugins section. The shell tolerates an
+ * unknown value at runtime (a bundle newer than this host), so the field is a
+ * placement hint, never a hard contract.
+ */
+export type NavEntrySection =
+  'Capabilities' | 'Integrations' | 'Activity' | 'Administration' | 'Plugins';
+
 export interface NavEntryContribution {
   /**
    * Path of a page THIS plugin registers. The nav entry links to
@@ -89,6 +136,12 @@ export interface NavEntryContribution {
    */
   readonly path: string;
   readonly title: string;
+  /**
+   * Optional target sidebar section (see {@link NavEntrySection}); absent ⇒ the
+   * Plugins section. Additive — an older bundle omits it and stays on the same
+   * plugin API version.
+   */
+  readonly section?: NavEntrySection;
   /**
    * Optional icon rendered before the title. It must be a square inline SVG that
    * fills its box and draws with `currentColor`; the host constrains the slot,

package/src/tool-visibility.ts

@@ -0,0 +1,53 @@
+/**
+ * The tool-visibility tri-state, shared by every surface that must honor it: the
+ * tools screen's list (and its "show hidden" toggle) and every tool picker.
+ *
+ * EFFECTIVE hidden is the overlay's tri-state OVERRIDE of the plugin's own
+ * declaration: an overlay opinion (`true`/`false`) wins, else the plugin
+ * declaration stands. So an overlay `false` UNHIDES a plugin-hidden tool, `true`
+ * force-hides, and `null` (no overlay row is the same) DEFERS to the declaration
+ * (PLAN §Tools-read-surface). The rule lives here ONCE so the list-exclusion and
+ * the picker-exclusion can never drift apart.
+ */
+import type { ToolMetaRecord, ToolTagEntry } from '@tai42/api-client';
+
+/**
+ * Effective hidden after the tri-state override. `overlayHidden` is the overlay's
+ * `hidden` (`true`/`false`), or `null`/`undefined` when the overlay defers or has
+ * no row; `declaredHidden` is the plugin's own `hidden`. Overlay opinion wins;
+ * absence defers to the declaration.
+ */
+export function effectiveHidden(
+  overlayHidden: boolean | null | undefined,
+  declaredHidden: boolean,
+): boolean {
+  return overlayHidden ?? declaredHidden;
+}
+
+/**
+ * The set of tool names whose EFFECTIVE visibility is hidden, from the native
+ * declarations (`listToolTags`) merged with the tool_meta overlay (`listToolMeta`).
+ * A picker excludes exactly these names from its options; the server stays the
+ * authority (a slipped-through name is rejected loudly there), so a name in the set
+ * that is not among a picker's options is simply inert.
+ *
+ * The union of both sources is walked so an overlay row that force-hides a tool
+ * carrying no native tag entry is still caught, and an overlay `false` on a
+ * plugin-hidden tool correctly keeps it OUT of the set (unhidden).
+ */
+export function hiddenToolNames(
+  tagEntries: readonly ToolTagEntry[],
+  overlayRows: readonly ToolMetaRecord[],
+): Set<string> {
+  const declaredByName = new Map(tagEntries.map((entry) => [entry.name, entry.hidden]));
+  const overlayByName = new Map(overlayRows.map((row) => [row.tool_name, row.hidden]));
+  const names = new Set<string>([...declaredByName.keys(), ...overlayByName.keys()]);
+
+  const hidden = new Set<string>();
+  for (const name of names) {
+    if (effectiveHidden(overlayByName.get(name) ?? null, declaredByName.get(name) ?? false)) {
+      hidden.add(name);
+    }
+  }
+  return hidden;
+}