gesso-vite-plugin 0.6.30 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # gesso-vite-plugin
 
+## 0.8.0
+
+### Patch Changes
+
+- b80e4ab: The dev server's start says how to connect any agent, not only Claude Code: the endpoint, which any MCP client connects to, and the line to add it in Claude Code, Codex and Gemini CLI. `agentName` names the server in those lines, the root folder's name unless given.
+
+## 0.7.0
+
+### Minor Changes
+
+- fe71a86: An application can offer an agent tools of its own, beside its channels' and its screen's: `renderRoot(App).useAgentTools([...])`, and `useAgentTools` on the app builder. A tool is a name, a description, an input schema and a `run` that may answer with text, data and pictures (`agentText`, `agentImages`, `agentError` from `gesso-framework/agent`); its arguments are checked against the schema first. In `gesso-vite-plugin`, `agentInstructions` adds an application's own words to what an agent is told when it connects, and `catalog.exclude` leaves folders of generated code out of the component catalog, so they are not counted as uses.
+
+### Patch Changes
+
+- cedb9ff: A call the dev server's agent bridge sent to a page that then closed or reloaded is answered at once, saying the page closed and to call again, rather than left to time out; a tool that waits on purpose would otherwise have kept the agent waiting for its whole wait.
+- 3910bc9: `gesso({ catalog: { root } })` reads another project's components for the agent endpoint, rather than those of the project Vite serves: for an application that designs one, such as a design editor serving the project it works on from another folder. The dev server watches that folder too, so a component saved in a new file there is in the next answer.
+- 4198183: The component catalog reads a project's components through the tsconfig it was given, not whichever one sits beside them, and keeps working when a tsconfig it had seen is deleted while the dev server runs: TypeScript refusing the update is a fresh checker, and a failed read is a warning and an empty catalog, never an unhandled rejection that ended the server.
+- 0e73baa: The dev server's agent endpoint now offers the project's own components, so an AI agent designing a screen uses what is there instead of drawing it again from boxes. `library_overview` lists every component in one line each, `library_search` finds the ones a few words describe, and `library_get` gives one in full: each input's type, default and meaning, examples, and the files that already use it. They are read from the files the project's tsconfig includes, a component saved in a new file is in the next answer, and they are answered on the dev server, so an agent can read them before a page is open. A library's components join only when named: `gesso({ catalog: { libraries: ['gesso-components'] } })`, and `catalog: false` leaves the tools out.
+
+  `tokens_view` joins the screen tools: the colours, type styles, corner radii, spacing scale and shadows of the theme in force, by name and value, at a control or at the application's outermost content. An agent told the names writes `backgroundColor="surface"` rather than a colour that will not follow the theme into dark mode. `GessoRuntime.themeAt(id)` gives the same theme to anything else that asks.
+
+- 4a13fb4: `ContractReader.readComponents(file)` describes every component a module exports, as the channel reader already describes channels: what each one is for, from its JSDoc, and each input as JSON Schema with its TypeScript type, its description, its `@default`, and whether it is required. A callback, a child and a value only code can make are named for what they are rather than rejected. A type several inputs share, such as `UiLength`, is described once under `$defs`, and an input inherited from a shared props type says which one. Point it at a library's index and it reads the whole library: all 55 of `gesso-components` in under half a second. It is the catalog an AI agent designing with the library reads, so that it reaches for `Badge` instead of drawing one from boxes.
+
+  Every component in `gesso-components` now opens with a one-line JSDoc summary, so hovering one in an editor says what it is. Twelve had their description only in the design note at the top of the file, which attached to whatever was declared under it.
+
+- 4894062: The component catalog can be served from a desktop app's main process. `gesso-vite-plugin/catalog` carries it without Vite: `openCatalog({ root, fs })` reads the project's components with the checker and watches `root` with the `fs` it is given, so a component saved in a new file is in the next answer, and answers null when TypeScript 7 is not installed. `serveDesktopAgent` takes it as `catalog` and offers `library_overview`, `library_search` and `library_get` after the channels and the screen, with the catalog's instructions added to the app's, so an agent designing in a desktop app builds with the project's own components.
+- 9c411b1: An application's agent tool can say it waits on purpose, for a person or for its next task, with `waitsUpToMs`: it is listed under MCP's `_meta` as `gesso/waitsUpToMs` (`WAITS_UP_TO`), and the bridges between the agent and the thread, the dev server's and the render worker's, give a call of it that long, where they gave up on every call after two minutes.
+
 ## 0.6.30
 
 ## 0.6.29

package/dist/catalog-CbeOrdxD.d.ts

@@ -0,0 +1,305 @@
+import * as TsApi from "typescript/unstable/sync";
+//#region src/contracts.d.ts
+/**
+ * Channel contracts, read by the type checker and written back as JSON
+ * Schema.
+ *
+ * A contract module already says everything an agent driving the
+ * application would need to know: the view's keys and their types, each
+ * command's parameters and their types, and, where the author wrote
+ * them, what each one is for. All of it is types and comments, and
+ * both are gone by the time the module runs. This puts them back, as a
+ * `describeChannel(token, schema)` call appended to the module, so the
+ * token carries its own description wherever it is imported.
+ *
+ * The checker rather than the syntax, because a contract names its
+ * types where it likes: `ProductRow` from another file, a status union
+ * behind an alias, a view written as an object literal whose type is
+ * inferred. Only the checker resolves all of those the way the compiler
+ * that checked the application did. TypeScript 7's checker runs in a
+ * separate process behind an API its package calls unstable, so all of
+ * it is in this file, and the rest of the plugin sees one function.
+ *
+ * What the comments carry:
+ *
+ *   - The JSDoc on the exported token is the channel's description, on
+ *     a view key is that key's, and on a command is the command's.
+ *   - `@param name text` describes a parameter.
+ *   - `@destructive`, `@idempotent`, `@confirm` and `@hidden` on a
+ *     command are its annotations; `CommandSchema` says what each means.
+ *   - `@hidden` on a view key keeps that key from an agent; see
+ *     `ChannelSchema.hidden`. On the token, it keeps the whole channel
+ *     from one; see `ChannelSchema.internal`.
+ *
+ * And what it will not describe: a value that is not plain data, which
+ * cannot cross a channel anyway. A function, a `Date`, a `Map`, a class
+ * instance. Each is reported, by its path in the contract, and
+ * described as `{}` so the rest of the schema still stands.
+ */
+/** The parts of `typescript/unstable/sync` this file uses, values included. */
+type TypeScriptApi = typeof TsApi;
+/** A channel's description, in the shape `describeChannel` takes. */
+interface ChannelSchemaOut {
+  description?: string;
+  internal?: true;
+  view: JsonSchema;
+  hidden?: string[];
+  commands: Record<string, CommandSchemaOut>;
+}
+interface CommandSchemaOut {
+  description?: string;
+  parameters: string[];
+  rest?: true;
+  input: JsonSchema;
+  destructive?: true;
+  idempotent?: true;
+  confirm?: true;
+  hidden?: true;
+}
+type JsonSchema = Record<string, unknown>;
+/**
+ * A component's description: what it is for, and what each of its
+ * inputs takes. The catalog an agent designing with the library reads,
+ * so that it uses `Badge` rather than drawing one from boxes.
+ */
+interface ComponentSchemaOut {
+  /** The first paragraph of its JSDoc: what it is, for a list of many. */
+  summary?: string;
+  /** The whole JSDoc, for the one component being used. */
+  description?: string;
+  /**
+   * Its inputs, as an object schema. Each input says its TypeScript
+   * type as `x-gesso-type`, which an agent writing TSX reads more
+   * readily than the schema; an input declared on a shared props type
+   * (`ControlLayoutProps`) says which as `x-gesso-from`; a callback is
+   * `x-gesso-callback` and a child `x-gesso-child`.
+   */
+  inputs: JsonSchema;
+  /** The `@example` blocks, as written. */
+  examples?: string[];
+  /** The `@deprecated` text, or true when it gives none. */
+  deprecated?: string | true;
+}
+/** Every component a module exports, and what could not be described. */
+interface ComponentReading {
+  /** Export name to schema, in declaration order. */
+  readonly components: ReadonlyMap<string, ComponentSchemaOut>;
+  readonly warnings: readonly string[];
+}
+/** Every channel a module exports, and what could not be described. */
+interface ContractReading {
+  /** Export name to schema, in declaration order. */
+  readonly channels: ReadonlyMap<string, ChannelSchemaOut>;
+  /** One sentence per value that could not be described, naming where it is. */
+  readonly warnings: readonly string[];
+}
+/**
+ * A module that describes channels when it is imported, for a bundle
+ * this plugin never sees.
+ *
+ * The plugin describes a contract by appending to it as Vite bundles
+ * it. An Electrobun main process is bundled by Electrobun's own build,
+ * which takes no plugins, so there the description is written ahead of
+ * time instead: `gesso-channels` reads the contracts with the same
+ * checker and writes this module, and the main process imports it once.
+ * A token is imported from its contract, so the schema lands on the
+ * same object the application serves.
+ *
+ * `outFile` and every `file` are absolute POSIX paths.
+ */
+declare function describedModule(contracts: readonly {
+  readonly file: string;
+  readonly channels: ReadonlyMap<string, ChannelSchemaOut>;
+}[], outFile: string): string;
+/**
+ * The checker, held open across reads.
+ *
+ * Spawning it and loading a project costs about a hundred
+ * milliseconds; a question after that costs well under one. So one
+ * reader lives as long as the dev server or the build, is told which
+ * files changed between reads, and is closed at the end, because the
+ * process it holds would otherwise keep the build from exiting.
+ */
+declare class ContractReader {
+  private api;
+  private readonly changed;
+  private readonly created;
+  private readonly deleted;
+  /** Each contract's tsconfig, found once. */
+  private readonly configs;
+  /**
+   * @param fs Callbacks the checker reads through before the disk, for
+   *   a spec that keeps its project in memory.
+   */
+  private readonly ts;
+  private readonly cwd;
+  private readonly fs;
+  constructor(ts: TypeScriptApi, cwd: string, fs?: TsApi.APIOptions['fs']);
+  /**
+   * A file changed on disk since the last read. A new or deleted one is
+   * said so, because a program's list of files only changes for those:
+   * a component in a new file is otherwise not in the catalog.
+   */
+  invalidate(file: string, event?: 'update' | 'create' | 'delete'): void;
+  /**
+   * A snapshot of the projects, with what changed since the last one.
+   *
+   * The checker keeps every project it has opened, and asked to update
+   * one whose tsconfig has since been deleted it refuses the whole
+   * update ("project not found for update"). That was a dev server gone
+   * with it: a project's tsconfig removed while the server ran threw out
+   * of the catalog's read and took the process down. A refused update is
+   * a checker started afresh, which reads the disk as it now is and
+   * opens only what is asked of it again.
+   */
+  private snapshot;
+  /** What changed since the last snapshot, emptied for the next. */
+  private takeChanges;
+  /** Every channel `file` exports, described. */
+  read(file: string): ContractReading;
+  /**
+   * Every component `file` exports, described: a function whose first
+   * parameter is `Inputs<P>`, or a class extending `Component`, whose
+   * inputs are its `InputCell` fields. A library's index re-exports its
+   * components, and reading it reads all of them.
+   */
+  readComponents(file: string, config?: string): ComponentReading;
+  /**
+   * The source files of the project `config` describes, with their
+   * text: what the project itself wrote, so neither its dependencies
+   * nor declaration files. The project's own tsconfig decides what that
+   * is, which is the answer the person already gave their editor.
+   */
+  sources(config: string): {
+    readonly file: string;
+    readonly text: string;
+  }[];
+  /** The inputs a component's type declares, or undefined when it is not a component. */
+  private inputsOf;
+  /** Whether a function returning `type` returns a child: `UiChild`, an element, or a union of them. */
+  private drawable;
+  private extendsComponent;
+  /**
+   * The checker and the module's exports, or why there are none: read
+   * in the project `preferred` names when it includes the file (the
+   * catalog's own tsconfig, which may resolve its imports differently
+   * from any beside it), else the project TypeScript finds for it.
+   */
+  private open;
+  close(): void;
+}
+//#endregion
+//#region src/catalog.d.ts
+/**
+ * The project's components, as tools an AI agent designs with.
+ *
+ * An agent asked for a settings screen will draw one from boxes unless
+ * it knows the project already has a `SettingsRow`, a `Toggle` and a
+ * `PageHeader`, what each takes, and where the others are used. Those
+ * are the project's own: what its designers and its agents made, not a
+ * kit the framework ships. So the catalog is read from the project's
+ * source, by the checker that already describes its channels, and a
+ * library joins it only when the project names one.
+ *
+ * Three tools, from cheap to complete, so an agent reads only what it
+ * needs:
+ *
+ *   library_overview   every component, one line each
+ *   library_search     the ones a few words find
+ *   library_get        one, with every input it takes and where it is used
+ *
+ * They are answered on the dev server rather than in the page, because
+ * the checker runs here and a page need not be open for an agent to
+ * learn what it can build with.
+ */
+/** One component in the catalog. */
+interface CatalogEntry {
+  readonly name: string;
+  /**
+   * Where to import it from: the module's path from the project root
+   * without its extension (`src/ui/Picker`), or the library's name.
+   */
+  readonly from: string;
+  /** The library it came from, when it is not the project's own. */
+  readonly library?: string;
+  readonly schema: ComponentSchemaOut;
+  /** Project files that write it as a tag, from the root, its own file left out. */
+  readonly usedIn: readonly string[];
+}
+interface CatalogLibrary {
+  /** The name it is imported by, such as `gesso-components`. */
+  readonly name: string;
+  /** The module that exports its components: its entry, resolved. */
+  readonly file: string;
+}
+interface ComponentCatalogOptions {
+  /** The tsconfig whose files are the project's source. */
+  readonly tsconfig: string;
+  /**
+   * Libraries whose components join the project's own, resolved when the
+   * catalog is first read. None by default.
+   */
+  readonly libraries?: () => Promise<readonly CatalogLibrary[]>;
+  /**
+   * Folders under the root whose files are not the project's
+   * components nor uses of them, from the root: generated code, say,
+   * which names the same components in another framework.
+   */
+  readonly exclude?: readonly string[];
+}
+/** A tool, in the shape MCP's `tools/list` returns. */
+interface CatalogTool {
+  readonly name: string;
+  readonly title: string;
+  readonly description: string;
+  readonly inputSchema: Record<string, unknown>;
+  readonly annotations: {
+    readonly readOnlyHint: true;
+    readonly openWorldHint: false;
+  };
+}
+/** A tool's answer, in the shape MCP's `tools/call` returns. */
+interface CatalogResult {
+  readonly content: readonly {
+    readonly type: 'text';
+    readonly text: string;
+  }[];
+  readonly structuredContent?: Record<string, unknown>;
+  readonly isError: boolean;
+}
+/** What tells an agent, when it connects, that the catalog is here and to use it. */
+declare const CATALOG_INSTRUCTIONS: string;
+declare const CATALOG_TOOLS: readonly CatalogTool[];
+declare class ComponentCatalog {
+  private cached;
+  private readonly reader;
+  private readonly root;
+  private readonly options;
+  constructor(reader: () => Promise<ContractReader | null>, root: string, options: ComponentCatalogOptions);
+  /**
+   * Something in the project changed. The whole catalog is read again
+   * on the next call: a project's components read in a tenth of a
+   * second, and a save can move a component between files, rename it,
+   * or start using it somewhere else.
+   */
+  invalidate(): void;
+  /**
+   * The components, read once until something changes. A read that
+   * fails (TypeScript refusing a project mid-change) is a warning and an
+   * empty catalog, tried again on the next call, never a rejection left
+   * for nobody to catch, which ends the dev server.
+   */
+  entries(): Promise<readonly CatalogEntry[]>;
+  call(name: string, args?: Readonly<Record<string, unknown>>): Promise<CatalogResult>;
+  private read;
+}
+/**
+ * Whether a module could declare a component, without asking the
+ * checker: it imports from `gesso-framework` and names `Inputs` or
+ * `Component`. Most of a project's files are neither, and each one the
+ * checker is spared is a round trip to its process.
+ */
+declare function mayDeclareComponent(text: string): boolean;
+//#endregion
+export { CatalogResult as a, ComponentCatalogOptions as c, ComponentSchemaOut as d, ContractReader as f, describedModule as h, CatalogLibrary as i, mayDeclareComponent as l, TypeScriptApi as m, CATALOG_TOOLS as n, CatalogTool as o, ContractReading as p, CatalogEntry as r, ComponentCatalog as s, CATALOG_INSTRUCTIONS as t, ComponentReading as u };
+//# sourceMappingURL=catalog-CbeOrdxD.d.ts.map