@asterism-app/sdk 0.0.0-stage → 0.47.0

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,75 @@
+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, location?: 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"); }

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];
+}

package/src/renderer.ts

@@ -0,0 +1,158 @@
+/** SDK renderer entry point: cards, tool views, and frontend capabilities bound to objects; React is shared by the host. */
+import { createContext, createElement, useContext, type ComponentType, type ReactNode } from "react";
+import type { UiText } from "./i18n.ts";
+import type { CardAppearance } from "./card.ts";
+export type { CardAppearance } from "./card.ts";
+export * from "./renderer-i18n.ts";
+import type { ActionContract, CreationContract } from "./commands.ts";
+import type { Json } from "./json.ts";
+import { reference, type ContractReference, type DataContract } from "./presentation.ts";
+import type { ResourceRef, SessionSnapshot } from "./workspace.ts";
+export * from "./renderer-services.ts";
+export * from "./renderer-calls.ts";
+export * from "./renderer-creation.ts";
+export * from "./renderer-tools.ts";
+export * from "./renderer-records.ts";
+export * from "./renderer-card.ts";
+export * from "./renderer-island.ts";
+export * from "./renderer-view-state.ts";
+import type { CardPanelDefinition, CardPanelView } from "./renderer-card.ts";
+import type { RecordRenderer } from "./renderer-records.ts";
+export type * from "./renderer-content.ts";
+import type { RendererContentInput, RendererInputOptions } from "./renderer-content.ts";
+import type { ContentReader } from "./content-runtime.ts";
+export type { ContentReader } from "./content-runtime.ts";
+import type { CreationEntry } from "./renderer-creation.ts";
+import type { ToolRenderer } from "./renderer-tools.ts";
+import type { EventSubscriber } from "./events.ts";
+import type { PluginCalls } from "./calls.ts";
+import type { ChannelContract, ChannelEnd, ChannelValue } from "./channels.ts";
+
+/** The frontend end of a channel: messages are delivered in order and buffered until a listener registers; closed resolves when either end terminates. */
+export interface RendererChannel<Up extends ChannelValue = ChannelValue, Down extends ChannelValue = ChannelValue> {
+  send(data: Up): void;
+  onMessage(listener: (data: Down) => void): () => void;
+  close(): void;
+  readonly closed: Promise<ChannelEnd>;
+}
+
+export type RendererReceipt = { ok: true } | { ok: false; error: { code: string; message: string; display?: UiText } };
+/**
+ * Frontend state retained per object, such as input drafts: survives card remounts, switches between focus containers, and session view disposal;
+ * release is called when the object leaves the current session projection through removal or a cursor jump, or is explicitly discarded; state is not restored after application restart.
+ */
+export interface RendererRetained {
+  /** Obtain the value for key, creating it with create on first access; the same object and key return the same instance. Prefix key with the plugin ID to avoid conflicts with other contributors. */
+  get<T>(key: string, create: () => T, release?: (value: T) => void | Promise<void>): T;
+  /** End retention immediately and call release; no effect if absent. */
+  discard(key: string): void;
+}
+/** Frontend capabilities bound to a card object; the host handles subscriptions, command gating, and current-view consistency. */
+export interface RendererObjectContext {
+  readonly ref: ResourceRef;
+  readonly content: ContentReader;
+  input<I, O extends Json>(contract: ActionContract<I, O> | CreationContract<I, Json, O>): RendererContentInput;
+  readonly view: {
+    /** The current object view is operable; ordinary background refreshes and local commits on other objects do not change this value. */
+    ready: boolean;
+    /** View read error; object action and creation failures are returned through their respective call receipts. */
+    error: UiText | null; missing: boolean;
+  };
+  readonly session: {
+    snapshot(): SessionSnapshot | null;
+    subscribe(listener: () => void): () => void;
+    create<I, O extends Json>(contract: CreationContract<I, Json, O>, input: NoInfer<I> & Json, position: { x: number; y: number }, options?: RendererInputOptions): Promise<RendererReceipt>;
+    refresh(): Promise<void>;
+  };
+  invoke<I, O extends Json>(contract: ActionContract<I, O>, input: NoInfer<I> & Json, options?: RendererInputOptions): Promise<RendererReceipt>;
+  /** Open a duplex channel for this object; the host validates that it is on the current path and routes to its owning plugin. Ends when the object leaves the current set or the connection disconnects. */
+  openChannel<Up extends ChannelValue, Down extends ChannelValue>(contract: ChannelContract<Up, Down>): RendererChannel<Up, Down>;
+  /** Object-level retained state with a lifecycle managed uniformly by the host. */
+  readonly retained: RendererRetained;
+}
+const ObjectContext = createContext<RendererObjectContext | null>(null);
+export function useRendererObject(): RendererObjectContext {
+  const object = useContext(ObjectContext);
+  if (!object) throw new Error("The renderer must be bound to an object.");
+  return object;
+}
+
+/** Static identification information at the type level; does not parse card data or create body components. */
+export interface ResourceDescription {
+  kind: string;
+  label: UiText;
+  icon: ReactNode;
+  /** Default card dimensions available before creation, sharing a declaration with the card renderer. */
+  card?: CardAppearance;
+  /** This resource can be the endpoint of a directed link, matching backend links.receive. */
+  receivesLinks?: boolean;
+}
+export interface CardView extends CardAppearance {
+  body: ReactNode;
+  actions?: ReactNode;
+  panels?: readonly CardPanelView[];
+}
+export interface CardRenderer {
+  contract: ContractReference;
+  resolve(data: Json, context?: RendererObjectContext): CardView | null;
+}
+export interface RendererModule {
+  resources: ResourceDescription[];
+  cards: CardRenderer[];
+  tools: ToolRenderer[];
+  /** History record views: declare summaries, icons, and optional row content by record contract. */
+  records?: RecordRenderer[];
+  /** Creation entry points: the host arbitrates menus and drag-and-drop uniformly, with all paths ultimately using the bound creation contract. */
+  creations?: CreationEntry[];
+  /** Startup preparation: the host invokes modules in parallel before the first screen, and modules initialize their own internal resources; timeouts or failures are logged without blocking startup. */
+  prepare?(context: RendererPrepareContext): Promise<void>;
+}
+export interface PluginSettingsPage {
+  /** A directly addressable location within a page; an empty location means the root page. */
+  locations?: readonly string[];
+  Body: ComponentType<{ location?: string }>;
+}
+/** Frontend plugins own settings pages and shared service lifecycles; feature views are composed from modules. */
+export interface RendererPlugin {
+  modules?: readonly RendererModule[];
+  settings?: PluginSettingsPage;
+  prepare?(context: RendererPrepareContext): Promise<void>;
+  closing?(): void | Promise<void>;
+}
+export function defineRendererPlugin(plugin: RendererPlugin): RendererPlugin { return plugin; }
+export interface RendererPrepareContext {
+  /** Typed calls for frontend module-level services; cancellation propagates with the preparation scope. */
+  readonly calls: PluginCalls;
+  /** Global subscriptions bound to the module lifecycle, cleaned up on failure, timeout, or application shutdown. */
+  readonly events: EventSubscriber;
+  /** Triggered when the host stops waiting due to timeout or shutdown; the module should stop promptly. */
+  readonly signal: AbortSignal;
+}
+
+/** Type erasure occurs only at the registration boundary; components receive data that has passed contract validation. */
+export function cardRenderer<T extends Json>(
+  contract: DataContract<T>,
+  definition: CardAppearance & {
+    Body: ComponentType<{ data: T }>;
+    Actions?: ComponentType<{ data: T }>;
+    panels?: readonly CardPanelDefinition<T>[];
+  },
+): CardRenderer {
+  const { Body, Actions, panels, ...appearance } = definition;
+  const ids = new Set<string>();
+  for (const panel of panels ?? []) {
+    if (!panel.id.trim() || panel.id !== panel.id.trim()) throw new Error("Card panel IDs must be non-empty and trimmed.");
+    if (ids.has(panel.id)) throw new Error(`Duplicate card panel ID: ${panel.id}`);
+    ids.add(panel.id);
+  }
+  return { contract: reference(contract), resolve(raw, context) {
+    const parsed = contract.schema.safeParse(raw);
+    if (!parsed.success) return null;
+    const bind = (node: ReactNode) => context ? createElement(ObjectContext.Provider, { value: context }, node) : node;
+    return { ...appearance, body: bind(createElement(Body, { data: parsed.data })),
+      actions: Actions ? bind(createElement(Actions, { data: parsed.data })) : undefined,
+      panels: panels?.map(({ Body: PanelBody, ...panel }) => ({
+        ...panel, body: bind(createElement(PanelBody, { data: parsed.data })),
+      })) };
+  } };
+}

package/src/runtime-calls.ts

@@ -0,0 +1,20 @@
+import type { CallContract, CallScope } from "./calls.ts";
+import type { z } from "zod";
+import type { Json } from "./json.ts";
+import type { ObjectReader } from "./objects.ts";
+import type { Source } from "./workspace.ts";
+
+export type CallContext<S extends CallScope = CallScope> = {
+  /** The host binds the source for backend plugin calls; null for desktop user calls. */
+  readonly source: Source;
+  readonly signal: AbortSignal;
+} & (S extends "object" ? { readonly object: ObjectReader } : { readonly object?: never });
+export interface CallContribution {
+  readonly contract: CallContract;
+  execute(input: Json, context: CallContext): Promise<Json>;
+}
+/** Implementations receive parsed input and return JSON accepted by the output schema before caller-side decoding. */
+export function implementCall<Input extends z.ZodType<Json>, Output extends z.ZodType<Json>, S extends CallScope>(contract: CallContract<Input, Output, S>,
+  execute: (input: NoInfer<z.output<Input>>, context: CallContext<NoInfer<S>>) => Promise<NoInfer<z.input<Output>> & Json>): CallContribution {
+  return { contract, execute: (input, context) => execute(input as z.output<Input>, context as CallContext<S>) };
+}