@asterism-app/sdk 0.0.0-stage → 1.0.0

package/src/provider-usage.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { uiTextSchema } from "./i18n.ts";
+
+/** Usage implementations have global catalog identities, independent of configured model connections. */
+export const providerUsageIdSchema = z.string().trim().min(1).max(160).regex(/^\S+$/u);
+
+const identity = {
+  id: z.string().trim().min(1), label: uiTextSchema,
+  scope: z.enum(["account", "plan", "key", "connection"]),
+};
+export const quotaValueSchema = z.discriminatedUnion("type", [
+  z.strictObject({ type: z.literal("ratio"), remaining: z.number().min(0).max(1) }),
+  z.strictObject({ type: z.literal("quantity"), remaining: z.number().nonnegative(), limit: z.number().positive(), unit: uiTextSchema })
+    .refine(value => value.remaining <= value.limit, "Remaining quota cannot exceed its limit."),
+]);
+export const usageItemSchema = z.discriminatedUnion("type", [
+  z.strictObject({ ...identity, type: z.literal("balance"), remaining: z.number(), currency: z.string().regex(/^[A-Z]{3}$/u) }),
+  z.strictObject({ ...identity, type: z.literal("quota"), value: quotaValueSchema,
+    category: z.enum(["allowance", "rate_limit"]).optional(),
+    window: z.strictObject({
+      mode: z.enum(["rolling", "fixed", "unknown"]),
+      /** Supply an actual fixed duration only when known; unknown periods must not be fabricated as weeks or months. */
+      durationMs: z.number().positive().nullable(),
+      resetAt: z.number().nonnegative().nullable(),
+    }),
+  }),
+]);
+export const usageItemsSchema = z.array(usageItemSchema).refine(items => new Set(items.map(item => item.id)).size === items.length,
+  "Usage item IDs must be unique.");
+export type UsageItem = z.infer<typeof usageItemSchema>;
+export type QuotaItem = Extract<UsageItem, { type: "quota" }>;
+export const providerUsageErrorSchema = z.enum(["unavailable", "credential", "authentication", "unsupported", "rate_limit", "network", "timeout", "protocol", "server"]);
+export type ProviderUsageError = z.infer<typeof providerUsageErrorSchema>;
+export const usageProviderInfoSchema = z.strictObject({ id: providerUsageIdSchema, label: uiTextSchema, owner: z.string(),
+  source: z.enum(["query", "headers"]).default("query") });
+export type UsageProviderInfo = z.infer<typeof usageProviderInfoSchema>;
+
+export function quotaRemaining(item: QuotaItem): number {
+  return item.value.type === "ratio" ? item.value.remaining : item.value.remaining / item.value.limit;
+}
+/** Select the window with the shortest period, independently of the reset countdown; unknown periods follow known ones, and equal lengths retain source order. */
+export function primaryQuota(items: readonly UsageItem[]): QuotaItem | null {
+  let selected: QuotaItem | null = null;
+  for (const item of items) if (item.type === "quota" && (!selected ||
+    (item.window.durationMs ?? Infinity) < (selected.window.durationMs ?? Infinity))) selected = item;
+  return selected;
+}

package/src/records.ts

@@ -0,0 +1,60 @@
+import type { z } from "zod";
+import type { Json } from "./json.ts";
+import type { Source } from "./workspace.ts";
+
+/** Public envelope for session records: the host maps its storage format to this envelope, and plugins decode by contract without depending on internal node structure. */
+export interface RecordRef { readonly id: string }
+export interface SessionRecord {
+  readonly id: string;
+  readonly sessionId: string;
+  readonly parentId: string | null;
+  /** Append order within the session, starting at 1. */
+  readonly sequence: number;
+  readonly createdAt: string;
+  readonly contract: RecordRef;
+  /** Writer; stamped by the host according to the write channel, while the associated object belongs in data. */
+  readonly source: Source;
+  /** Model-visible text written by the platform, consumed when executors project context; recipient being null means all executors. */
+  readonly context: { readonly text: string; readonly recipient: string | null } | null;
+  readonly data: Json;
+}
+export type Decoded<D> =
+  | { readonly status: "known"; readonly record: SessionRecord; readonly data: D }
+  | { readonly status: "unknown"; readonly record: SessionRecord; readonly reason: "invalid_data" };
+export interface RecordContract<D extends Json = Json> extends RecordRef {
+  /** Decodes persisted JSON into D; record writers encode D through the same schema. */
+  readonly schema: z.ZodType<D>;
+  /** Return null when the record does not belong to this contract; compatibility and transformations are determined by the schema, and failure preserves the raw record. */
+  decode(record: SessionRecord): Decoded<D> | null;
+}
+export function defineRecord<D extends Json>(id: string, definition: {
+  schema: z.ZodType<D>;
+}): RecordContract<D> {
+  const { schema } = definition;
+  return {
+    id, schema,
+    decode(record) {
+      if (record.contract.id !== id) return null;
+      const data = structuredClone(record.data);
+      try {
+        const parsed = schema.safeParse(data);
+        return parsed.success ? { status: "known", record, data: parsed.data } : { status: "unknown", record, reason: "invalid_data" };
+      } catch { return { status: "unknown", record, reason: "invalid_data" }; }
+    },
+  };
+}
+/** timeline reads the complete ancestor path to the snapshot tip; session reads all session records within the snapshot's upper bound in save order. */
+export interface RecordQuery { readonly scope: "timeline" | "session" }
+/** An observation handle fixed at one read position; reads records on demand and does not switch to the latest state after await. */
+export interface SessionView {
+  readonly id: string;
+  readonly title: string;
+  readonly records: {
+    all(query: RecordQuery): readonly SessionRecord[];
+    /** The earliest matching record; returns unknown if it cannot be decoded, without skipping it. */
+    first<D extends Json>(contract: RecordContract<D>, query: RecordQuery): Decoded<D> | null;
+    /** The latest matching record, located by scope and contract; decodes only that record and returns unknown if undecodable, without falling back. */
+    last<D extends Json>(contract: RecordContract<D>, query: RecordQuery): Decoded<D> | null;
+    query<D extends Json>(contract: RecordContract<D>, query: RecordQuery): Decoded<D>[];
+  };
+}

package/src/renderer-calls.ts

@@ -0,0 +1,15 @@
+import { createContext, useContext } from "react";
+import type { CallContract, PluginCalls } from "./calls.ts";
+import type { RendererContentInput } from "./renderer-content.ts";
+
+export interface RendererCalls extends PluginCalls<RendererContentInput> {
+  input(contract: CallContract): RendererContentInput;
+}
+const Calls = createContext<RendererCalls | null>(null);
+export const RendererCallsProvider = Calls.Provider;
+/** Invoke a registered backend contract; associating an object does not change resource ownership. */
+export function useRendererCalls(): RendererCalls {
+  const calls = useContext(Calls);
+  if (!calls) throw new Error("Renderer calls must be provided by the host.");
+  return calls;
+}

package/src/renderer-card.ts

@@ -0,0 +1,29 @@
+import { createContext, useContext, type ComponentType, type ReactNode } from "react";
+import type { UiText } from "./i18n.ts";
+
+/** Auxiliary panel identities are unique within a single card renderer; content receives the same validated projection as the body. */
+export interface CardPanelDefinition<T> {
+  id: string;
+  label: UiText;
+  icon: ReactNode;
+  Body: ComponentType<{ data: T }>;
+}
+export interface CardPanelView {
+  id: string;
+  label: UiText;
+  icon: ReactNode;
+  body: ReactNode;
+}
+/** Local card view operations; do not submit resource commands or write task history. */
+export interface RendererCard {
+  readonly activePanel: string | null;
+  openPanel(id: string): void;
+  closePanel(): void;
+}
+const CardContext = createContext<RendererCard | null>(null);
+export const RendererCardProvider = CardContext.Provider;
+export function useRendererCard(): RendererCard {
+  const card = useContext(CardContext);
+  if (!card) throw new Error("The renderer must be bound to a card.");
+  return card;
+}

package/src/renderer-content.ts

@@ -0,0 +1,9 @@
+import type { ContentRef } from "./content.ts";
+import type { ContentReader } from "./content-runtime.ts";
+
+/** The host binds input drafts to contracts; business input carries only ContentRef. The host closes drafts after command success and preserves them for retry after failure. */
+export interface RendererContentInput extends ContentReader {
+  stage(source: Blob | Uint8Array, options?: { signal?: AbortSignal; progress?(bytes: number, total: number): void }): Promise<ContentRef>;
+  close(): Promise<void>;
+}
+export interface RendererInputOptions { content?: RendererContentInput }

package/src/renderer-creation.ts

@@ -0,0 +1,83 @@
+import { createContext, useContext, type ComponentType, type ReactNode } from "react";
+import type { z } from "zod";
+import type { CreationContract } from "./commands.ts";
+import type { Json } from "./json.ts";
+import type { RendererContentInput } from "./renderer-content.ts";
+
+/**
+ * Host snapshot of dropped content: the host reads it from DataTransfer at drop time, and it remains valid after the event ends.
+ * The host resolves file paths through the desktop bridge; plugins cannot forge them.
+ */
+export type DropItem =
+  /** Local drops carry a host-resolved path; sources without paths, such as clipboard images, contain only file bytes. */
+  | { readonly kind: "file"; readonly file: File; readonly name: string; readonly mime: string; readonly directory: boolean; readonly path?: string }
+  | { readonly kind: "url"; readonly url: string }
+  | { readonly kind: "text"; readonly text: string };
+
+/**
+ * Declarative acceptance conditions: the host matches them synchronously during drag hover without calling plugin functions.
+ * Extensions include a leading dot and use lowercase; MIME supports wildcards such as `image/*`.
+ */
+export interface DropAccepts {
+  /** requiresPath accepts only items with a local path; directories implicitly requires a path. */
+  readonly files?: { readonly requiresPath?: boolean; readonly directories?: boolean; readonly extensions?: readonly string[]; readonly mime?: readonly string[] };
+  readonly urls?: { readonly schemes?: readonly string[] };
+  readonly text?: boolean;
+}
+
+/** The source that triggered the entry point; menus have no payload. */
+export type CreationSource = { readonly kind: "menu" } | { readonly kind: "drop"; readonly item: DropItem };
+
+/** Plugin-owned preferences: the host isolates them by plugin and persists them in UI state; reads validate using the caller's schema. */
+export interface RendererPreferences {
+  get<T extends Json>(key: string, schema: z.ZodType<T>): T | null;
+  set(key: string, value: Json | null): void;
+}
+
+/**
+ * Input phase component: can render any UI, such as forms or previews, and can only return input or cancel.
+ * resolve returns whether host creation succeeded; on failure the component stays open and the host shell displays the error.
+ */
+export interface CreationInputProps<I = Json> {
+  readonly source: CreationSource;
+  readonly initialInput?: I;
+  readonly busy: boolean;
+  readonly content: RendererContentInput;
+  resolve(input: I): Promise<boolean>;
+  cancel(): void;
+}
+
+export interface CreationEntry<I = Json> {
+  /** Globally stable identity using the declaring plugin's namespace; routing memory stores this as its value. */
+  readonly id: string;
+  readonly contract: CreationContract<I, Json, Json>;
+  readonly label: UiText;
+  readonly description?: UiText;
+  readonly icon?: ReactNode;
+  /** Menu group; defaults to resources when omitted. */
+  readonly group?: "agents" | "resources";
+  readonly triggers: {
+    readonly menu?: { readonly initialInput?: I };
+    readonly drop?: { readonly accepts: DropAccepts; toInput(item: DropItem, content: RendererContentInput): I | null | Promise<I | null> };
+  };
+  /** When omitted, input is produced directly from the trigger source; menu sources must then provide initialInput. */
+  readonly InputView?: ComponentType<CreationInputProps<I>>;
+}
+
+/** Type erasure occurs only at the registration boundary; call and component input types are inferred from the creation contract. */
+export function creationEntry<I, O extends Json>(contract: CreationContract<I, Json, O>,
+  definition: Omit<CreationEntry<NoInfer<I> & Json>, "contract">): CreationEntry {
+  if (!definition.triggers.menu && !definition.triggers.drop) throw new Error(`Creation entry ${definition.id} declares no trigger.`);
+  if (definition.triggers.menu && !definition.InputView && definition.triggers.menu.initialInput === undefined)
+    throw new Error(`Creation entry ${definition.id} needs an InputView or a menu initialInput.`);
+  return { ...definition, contract } as unknown as CreationEntry;
+}
+
+const Preferences = createContext<RendererPreferences | null>(null);
+export const RendererPreferencesProvider = Preferences.Provider;
+export function useRendererPreferences(): RendererPreferences {
+  const value = useContext(Preferences);
+  if (!value) throw new Error("Renderer preferences must be provided by the host.");
+  return value;
+}
+import type { UiText } from "./i18n.ts";

package/src/renderer-i18n.ts

@@ -0,0 +1,49 @@
+import { createContext, createElement, useContext, type ReactNode } from "react";
+import { createIntl, createIntlCache, RawIntlProvider, FormattedMessage } from "react-intl";
+
+import type { UiText, UiMessage, MessageValues } from "./i18n.ts";
+
+export interface I18n {
+  readonly locale: string;
+  readonly interfaceLocale: string;
+  readonly revision: number;
+  text(value: UiText): string;
+  formatMessage(message: UiMessage, values?: MessageValues): string;
+  formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+  formatDate(value: number, options?: Intl.DateTimeFormatOptions): string;
+  resolve(message: UiMessage): { locale: string; message: string; revision: string };
+}
+
+const I18nContext = createContext<I18n | null>(null);
+
+export function I18nProvider({ value, children }: { value: I18n; children: ReactNode }) {
+  return createElement(I18nContext.Provider, { value }, children);
+}
+
+export function useI18n(): I18n {
+  const value = useContext(I18nContext);
+  if (!value) throw new Error("The renderer requires the host I18nProvider.");
+  return value;
+}
+
+const cache = createIntlCache();
+
+/** Rich-text mappings remain in React; default copy is still declared and extracted through standard defineMessages. */
+export function UiFormattedMessage({ message, values }: {
+  message: UiMessage;
+  values?: Record<string, string | number | boolean | ((chunks: ReactNode[]) => ReactNode)>;
+}) {
+  const i18n = useI18n();
+  const selected = i18n.resolve(message);
+  const intl = createIntl({
+    locale: selected.locale,
+    defaultLocale: message.sourceLocale,
+    messages: { [message.id]: selected.message },
+    onError: error => console.warn("Rich text message formatting failed.", error),
+  }, cache);
+  return createElement(RawIntlProvider, { value: intl }, createElement(FormattedMessage, {
+    id: message.id,
+    defaultMessage: message.defaultMessage,
+    values: { ...message.values, ...values },
+  }));
+}

package/src/renderer-island.ts

@@ -0,0 +1,66 @@
+import { createContext, createElement, useContext, useEffect, useRef, type ComponentType, type ReactNode } from "react";
+import type { UiText } from "./i18n.ts";
+
+/**
+ * Island: an independent surface column within the host screen; opening one places it to the right of the current island and replaces existing deeper islands.
+ * The host uniformly manages width, position, motion, and focus; plugins provide only identity, an accessible name, and content.
+ */
+export interface RendererIslandSpec {
+  /** Island identity unique within the plugin; the host isolates it by plugin identity. Opening the same identity again replaces its content. */
+  key: string;
+  /** The island's accessible name and overflow navigation hint. */
+  label: UiText;
+  /** The element that opened it: used for the expansion animation and receives focus again after closing. */
+  origin?: HTMLElement | null;
+  render: () => ReactNode;
+}
+/** Close guard: returning false (or resolving to false) aborts closing; may asynchronously wait for user confirmation. */
+export type RendererCloseGuard = () => boolean | Promise<boolean>;
+export interface RendererIsland {
+  /** Identities of deeper islands opened by this plugin to the right of this island. */
+  readonly child: string | undefined;
+  /** Open a deeper island to the right of this one; replaced islands may refuse through guards. Resolves to whether it opened. */
+  open(spec: RendererIslandSpec): Promise<boolean>;
+  /** Close this island and deeper islands; has no effect on the host-managed island containing the plugin settings page. force skips guards. */
+  close(options?: { force?: boolean }): Promise<boolean>;
+  /** Close deeper islands to the right of this one. */
+  closeChild(options?: { force?: boolean }): Promise<boolean>;
+  /** Register a close guard for this island and return an unregister function. Normally used through useRendererCloseGuard. */
+  guard(guard: RendererCloseGuard): () => void;
+}
+/**
+ * Panel island frame: the title bar stays fixed and the content scrolls independently; the primary action and close control sit on the right of the title bar.
+ * When dirty is true, the host asks for confirmation to discard changes before closing this island, including through ancestor closure or replacement.
+ */
+export interface RendererIslandPanelProps {
+  title: string;
+  description?: string;
+  /** Primary title bar action, such as save. */
+  action?: ReactNode;
+  /** Fixed toolbar below the title bar, such as search. */
+  toolbar?: ReactNode;
+  dirty?: boolean;
+  children: ReactNode;
+}
+
+const Island = createContext<RendererIsland | null>(null);
+const Panel = createContext<ComponentType<RendererIslandPanelProps> | null>(null);
+export const RendererIslandProvider = Island.Provider;
+export const RendererIslandPanelProvider = Panel.Provider;
+function required<T>(value: T | null, name: string): T {
+  if (value === null) throw new Error(`Renderer ${name} must be provided by the host.`);
+  return value;
+}
+/** The containing island; available within plugin settings pages and islands they open. */
+export function useRendererIsland(): RendererIsland { return required(useContext(Island), "island"); }
+/** Register a close guard for the containing island; null guard permits closing, and the guard always uses the latest callback. */
+export function useRendererCloseGuard(guard: RendererCloseGuard | null) {
+  const island = useRendererIsland();
+  const latest = useRef(guard);
+  latest.current = guard;
+  useEffect(() => island.guard(() => latest.current ? latest.current() : true), [island]);
+}
+/** Host-rendered panel frame for use within islands opened by plugins. */
+export function IslandPanel(props: RendererIslandPanelProps) {
+  return createElement(required(useContext(Panel), "island panel"), props);
+}

package/src/renderer-records.ts

@@ -0,0 +1,49 @@
+import { createElement, type ComponentType, type ReactNode } from "react";
+import type { UiText } from "./i18n.ts";
+import type { Json } from "./json.ts";
+import { reference, type ContractReference } from "./presentation.ts";
+import type { RecordContract, SessionRecord } from "./records.ts";
+
+/** Host-provided queries: records carry only identities, while the host resolves titles and type names using the full history. */
+export interface RecordRenderContext {
+  /** An object's title across the entire history; objects that were removed or belong to other branches can still be resolved. */
+  resourceTitle(id: string): string;
+  resourceLabel(kind: string): UiText;
+  /** Format copy as plain text in the current UI language for composing summaries. */
+  text(value: UiText): string;
+  /** Contracts wrapping other records borrow the wrapped record's view; return null when unregistered or undecodable. */
+  describe(record: SessionRecord): RecordView | null;
+}
+export interface RecordRowProps<D> { data: D; record: SessionRecord; label: string }
+export interface RecordRendererDefinition<D> {
+  /** Required plain-text summary for search, tooltips, and accessible names. */
+  label(data: D, context: RecordRenderContext, record: SessionRecord): UiText;
+  icon?: ReactNode | ((data: D, record: SessionRecord) => ReactNode);
+  /** Optional summary row content; the host owns the row shell, including selection, position marker, source, and menu. */
+  Row?: ComponentType<RecordRowProps<D>>;
+}
+export interface RecordView {
+  label: UiText;
+  icon?: ReactNode;
+  /** Generate row content from the host-formatted summary; the host displays the summary text when omitted. */
+  row?(label: string): ReactNode;
+}
+export interface RecordRenderer {
+  contract: ContractReference;
+  resolve(record: SessionRecord, context: RecordRenderContext): RecordView | null;
+}
+
+/** Declare history presentation by record contract; data enters the view only after contract decoding, otherwise the host displays an unknown record. */
+export function recordRenderer<D extends Json>(contract: RecordContract<D>, definition: RecordRendererDefinition<D>): RecordRenderer {
+  return { contract: reference(contract), resolve(record, context) {
+    const decoded = contract.decode(record);
+    if (decoded?.status !== "known") return null;
+    const { data } = decoded;
+    const { Row, icon } = definition;
+    return {
+      label: definition.label(data, context, record),
+      icon: typeof icon === "function" ? icon(data, record) : icon,
+      row: Row ? label => createElement(Row, { data, record, label }) : undefined,
+    };
+  } };
+}

package/src/renderer-services.ts

@@ -0,0 +1,89 @@
+import { createContext, useContext } from "react";
+import type { Json } from "./json.ts";
+import type { DataContract } from "./presentation.ts";
+import type { ConfigContract } from "./config.ts";
+import type { ModelLiveBlock } from "./models.ts";
+import type { ToolRenderProps, ToolView } from "./renderer-tools.ts";
+import type { EventSubscriber } from "./events.ts";
+import type { ResourceDescription } from "./renderer.ts";
+import type { UiText } from "./i18n.ts";
+
+/** Static resource type presentation catalog; querying descriptions grants no access to resource instances. */
+export interface RendererResources {
+  list(): readonly ResourceDescription[];
+  get(kind: string): ResourceDescription;
+}
+export interface RendererCatalogs { get<T extends Json>(contract: DataContract<T>): T | null; error: UiText | null }
+export interface RendererTools {
+  resolve(props: ToolRenderProps): ToolView & { props: ToolRenderProps };
+  preparation(name: string): string;
+}
+export interface RendererModels { readonly blocks: readonly ModelLiveBlock[] }
+export interface RendererNavigation { home(): void }
+const Resources = createContext<RendererResources | null>(null);
+const Catalogs = createContext<RendererCatalogs | null>(null);
+const Tools = createContext<RendererTools | null>(null);
+const Models = createContext<RendererModels | null>(null);
+const Navigation = createContext<RendererNavigation | null>(null);
+const Events = createContext<EventSubscriber | null>(null);
+export const RendererEventsProvider = Events.Provider;
+/** Global typed subscriptions; components should close subscriptions they establish during effect cleanup. */
+export function useRendererEvents(): EventSubscriber { return required(useContext(Events), "events"); }
+export const RendererResourcesProvider = Resources.Provider;
+export const RendererCatalogsProvider = Catalogs.Provider;
+export const RendererToolsProvider = Tools.Provider;
+export const RendererModelsProvider = Models.Provider;
+export const RendererNavigationProvider = Navigation.Provider;
+function required<T>(value: T | null, name: string): T {
+  if (value === null) throw new Error(`Renderer ${name} must be provided by the host.`);
+  return value;
+}
+export function useRendererResources(): RendererResources { return required(useContext(Resources), "resources"); }
+export function useRendererCatalogs(): RendererCatalogs { return required(useContext(Catalogs), "catalogs"); }
+export function useRendererTools(): RendererTools { return required(useContext(Tools), "tools"); }
+export function useRendererModels(): RendererModels { return required(useContext(Models), "models"); }
+export function useRendererNavigation(): RendererNavigation { return required(useContext(Navigation), "navigation"); }
+
+/** Renderer access to plugin configuration: the host decodes by contract and updates on change notifications after settings are saved; can read only this plugin's configuration. */
+export interface RendererConfiguration<T extends Json> {
+  value: T;
+  status: "saved" | "defaults" | "invalid";
+  ready: boolean;
+  error: UiText | null;
+}
+export interface RendererConfigs {
+  get<T extends Json>(contract: ConfigContract<T>): RendererConfiguration<T>;
+  save<T extends Json>(contract: ConfigContract<T>, value: NoInfer<T>): Promise<void>;
+  reset(contract: ConfigContract): Promise<void>;
+  refresh(): Promise<void>;
+}
+const Configs = createContext<RendererConfigs | null>(null);
+export const RendererConfigsProvider = Configs.Provider;
+export function useRendererConfig<T extends Json>(contract: ConfigContract<T>): T {
+  return required(useContext(Configs), "configs").get(contract).value;
+}
+/** Custom settings pages use managed configuration; writes are validated in the backend, and successful writes synchronously publish a new snapshot. */
+export function useRendererConfiguration<T extends Json>(contract: ConfigContract<T>) {
+  const configs = required(useContext(Configs), "configs");
+  return { ...configs.get(contract), save: (value: T) => configs.save(contract, value), reset: () => configs.reset(contract), refresh: configs.refresh };
+}
+
+export interface RendererSettingsNavigation {
+  open(pluginId: string, pageId: string, location?: string): void;
+  openHost(pageId: string): void;
+}
+const SettingsNavigation = createContext<RendererSettingsNavigation | null>(null);
+export const RendererSettingsNavigationProvider = SettingsNavigation.Provider;
+/** Open plugin settings without binding the current resource or session. */
+export function useRendererSettings(): RendererSettingsNavigation { return required(useContext(SettingsNavigation), "settings navigation"); }
+
+/** Application-wide frontend capabilities shared by plugin interfaces. */
+export interface RendererApplicationServices {
+  readonly platform: "darwin" | "win32" | "linux";
+  preferences(pluginId: string): import("./renderer-creation.ts").RendererPreferences;
+  pickDirectory(initialPath?: string): Promise<string | null>;
+  openLocalFile(path: string): Promise<void>;
+}
+const Application = createContext<RendererApplicationServices | null>(null);
+export const RendererApplicationProvider = Application.Provider;
+export function useRendererApplication(): RendererApplicationServices { return required(useContext(Application), "application"); }

package/src/renderer-tools.ts

@@ -0,0 +1,103 @@
+import { createElement, type ComponentType, type ReactNode } from "react";
+import type { z } from "zod";
+import type { UiText } from "./i18n.ts";
+import type { Json } from "./json.ts";
+import { reference, type ContractReference, type DataContract } from "./presentation.ts";
+import type { ToolCompletion, ToolInvocationInfo, ToolResult } from "./tool-result.ts";
+
+interface ToolCallProps<T, A> {
+  name: string;
+  target: T;
+  args: A;
+  invocation: ToolInvocationInfo;
+}
+/** Partial JSON has not passed the argument contract; fields may be missing, incomplete, or of the wrong type. */
+export interface ToolInputRenderProps extends ToolCallProps<Json, Json> {
+  phase: "input";
+  result: null;
+}
+/** Waiting for scheduling and execution share a view; complete arguments have passed contract validation. */
+export interface ToolExecutionRenderProps<D = Json, T = Json, A = Json> extends ToolCallProps<T, A> {
+  phase: "ready" | "executing";
+  result: Extract<ToolResult<D>, { kind: "running" }> | null;
+}
+export interface ToolResultRenderProps<D = Json, T = Json, A = Json> extends ToolCallProps<T, A> {
+  phase: "settled";
+  result: ToolCompletion<D>;
+}
+export type ToolRenderProps<D = Json, T = Json, A = Json> =
+  | ToolInputRenderProps | ToolExecutionRenderProps<D, T, A> | ToolResultRenderProps<D, T, A>;
+
+/** All three states use the same two independently optional entry points; the same declaration can be reused across phases. */
+export interface ToolPhaseView<P> {
+  headerRenderer?: ComponentType<P>;
+  bodyRenderer?: ComponentType<P>;
+}
+/** Input and execution views declare previewable content; bodyRenderer still owns the body layout. */
+export interface ToolStreamingPhaseView<P> extends ToolPhaseView<P> {
+  /** Pure function: returns true when a body suitable for streaming preview exists; after the first match within a phase, the shell manages expansion and collapse according to user preferences. */
+  streaming?: (props: P) => boolean;
+}
+/** Execution views may additionally declare bodies that require user attention. */
+export interface ToolExecutionPhaseView<P> extends ToolStreamingPhaseView<P> {
+  /** Pure function: returns true when the body requires user attention; the shell immediately expands once on the first match during execution, independently of streaming preferences, and users can still collapse it. */
+  attention?: (props: P) => boolean;
+}
+export interface ToolRendererDefinition<D = Json, T = Json, A = Json> {
+  label?: UiText;
+  icon?: ReactNode;
+  input?: ToolStreamingPhaseView<ToolInputRenderProps>;
+  execution?: ToolExecutionPhaseView<ToolExecutionRenderProps<D, T, A>>;
+  result?: ToolPhaseView<ToolResultRenderProps<D, T, A>>;
+}
+export interface ToolView {
+  label?: UiText;
+  icon?: ReactNode;
+  header?: ReactNode;
+  body?: ReactNode;
+  /** Bodies in input or execution phases may participate in streaming preview expansion and collapse; false means no match this time, and phase completion is determined by the call lifecycle. */
+  streaming?: boolean;
+  /** The executing body requires user attention; the shell expands once when this first becomes true within the phase. */
+  attention?: boolean;
+}
+export interface ToolRenderer {
+  contract: ContractReference;
+  resolve(props: ToolRenderProps): ToolView | null;
+}
+
+function render<P extends { phase: ToolRenderProps["phase"] }>(
+  definition: Pick<ToolView, "label" | "icon">, view: ToolExecutionPhaseView<P> | undefined, props: P,
+): ToolView {
+  return {
+    label: definition.label, icon: definition.icon,
+    header: view?.headerRenderer ? createElement(view.headerRenderer, props) : undefined,
+    body: view?.bodyRenderer ? createElement(view.bodyRenderer, props) : undefined,
+    streaming: (props.phase === "input" || props.phase === "executing")
+      && !!view?.bodyRenderer && (view.streaming?.(props) ?? false),
+    attention: props.phase === "executing" && !!view?.bodyRenderer && (view.attention?.(props) ?? false),
+  };
+}
+
+/** Dispatch by phase; streaming input is not treated as valid arguments, while execution and results share complete argument and output validation. */
+export function toolRenderer<D extends Json, T extends Json = Json, A extends Json = Json>(
+  contract: DataContract<D> & { targetSchema?: z.ZodType<T>; tool?: { argsSchema: z.ZodType<A> } },
+  definition: ToolRendererDefinition<D, T, A>,
+): ToolRenderer {
+  return { contract: reference(contract), resolve(props) {
+    if (props.phase === "input") return definition.input ? render(definition, definition.input, props) : null;
+    const data = props.result?.data;
+    const parsed = data === null || data === undefined ? null : contract.schema.safeParse(data);
+    if (parsed && !parsed.success) return null;
+    const target = contract.targetSchema?.safeParse(props.target);
+    const args = contract.tool?.argsSchema.safeParse(props.args);
+    if (target && !target.success || args && !args.success) return null;
+    // Pure data contracts without an argument schema preserve raw JSON; type erasure occurs only at the registration boundary.
+    const input = { target: (target ? target.data : props.target) as T, args: (args ? args.data : props.args) as A };
+    if (props.phase === "settled") return render(definition, definition.result, {
+      ...props, ...input, result: { ...props.result, data: parsed?.data ?? null },
+    });
+    return render(definition, definition.execution, {
+      ...props, ...input, result: props.result ? { ...props.result, data: parsed?.data ?? null } : null,
+    });
+  } };
+}

package/src/renderer-view-state.ts

@@ -0,0 +1,33 @@
+import { createContext, createElement, useContext, useState, type ReactNode } from "react";
+
+/**
+ * List item view state: items in virtualized lists unmount and remount as they scroll; user-modified expansion, tabs, and other
+ * state are stored per item in storage supplied by the list owner and restored on remount. Outside an item scope, this behaves like component state.
+ */
+export type RendererViewStateEntry = Map<string, unknown>;
+const Entry = createContext<RendererViewStateEntry | null>(null);
+
+/** The list owner provides stable storage for each item; the same instance must be passed when that item remounts. */
+export function RendererViewStateProvider({ value, children }: { value: RendererViewStateEntry; children?: ReactNode }) {
+  return createElement(Entry.Provider, { value }, children);
+}
+
+/**
+ * Read and write one view state value within the current item. key is unique within the item and prefixed with the plugin ID to avoid conflicts with other contributors;
+ * when key is null, this is only component state and does not survive remounts. initial is used only when the item has no such value yet.
+ */
+export function useRendererViewState<T>(key: string | null, initial: T | (() => T)): [T, (value: T) => void] {
+  const entry = useContext(Entry);
+  const stored = key !== null && entry !== null;
+  const [value, setLocal] = useState<T>(() => {
+    if (stored && entry.has(key)) return entry.get(key) as T;
+    const created = typeof initial === "function" ? (initial as () => T)() : initial;
+    if (stored) entry.set(key, created);
+    return created;
+  });
+  const set = (next: T) => {
+    if (stored) entry.set(key, next);
+    setLocal(next);
+  };
+  return [value, set];
+}