@yaklabs-ai/plugin-sdk 0.53.0 → 0.54.0

package/dist/kay-app.d.ts

@@ -1338,6 +1338,21 @@ declare class EncodeBuilder<Type extends TSchema, Encoded extends unknown, Decod
     Encode(callback: TEncodeCallback<Encoded, Decoded>): TCodec<Type, Decoded>;
 }
 
+export declare const EndpointContribution: z.ZodObject<{
+    localId: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    requestSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+    responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<authoringCommonSchemas.JsonValue, unknown, z.core.$ZodTypeInternals<authoringCommonSchemas.JsonValue, unknown>>>>;
+    auth: z.ZodOptional<z.ZodObject<{
+        service: z.ZodString;
+        schemes: z.ZodArray<z.ZodString>;
+        purpose: z.ZodString;
+    }, z.core.$strict>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+
+export declare type EndpointContribution = z.infer<typeof EndpointContribution>;
+
 declare interface EntryBase {
     id: string;
     parentId: string | null;
@@ -2915,11 +2930,45 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.53.0 adds declared working-content layouts, family-root authority, draft projection discovery
  * and session-bound page references. Older customized Whiteboard copies must accept the plugin
  * update before using these interfaces.
+ *
+ * 0.54.0 adds named UI host grants for shared configuration/auth/account reads, retained connection
+ * progress/dismissal and support. Built-in-only page capability scopes are removed; executable
+ * pages declare capabilities on apps[].
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.53.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.54.0";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
+/**
+ * One process the plugin asks the host to run.
+ *
+ * `argvClass` is required and is NOT decoration: it names the class of argument vector this
+ * invocation belongs to, and it must match a class the plugin declared alongside `command` in its
+ * manifest. Declaring a command alone would authorize `git log` and `git push --force` identically;
+ * the class is what a user can be shown and asked to consent to. The host judges the real `args`
+ * against the named class and refuses with `argv-outside-class` when they do not belong to it.
+ */
+declare interface KayAgentProcessRunRequest {
+    readonly command: string;
+    readonly argvClass: string;
+    readonly args: readonly string[];
+    /** Abort the run; the host kills the DIRECT child and rejects - a forked descendant may outlive it (#6153). */
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * A finished run. `stdout`/`stderr` are decoded text, and the host CAPS them - a truncation flag is
+ * set rather than the output silently ending, so a plugin parsing the stream can tell "the command
+ * printed this" apart from "the command printed more than we kept".
+ */
+declare interface KayAgentProcessRunResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly stdoutTruncated?: boolean;
+    readonly stderrTruncated?: boolean;
+}
+
 declare interface KayAgentWhiteboardCreateInput {
     readonly name: string;
     readonly title: string;
@@ -3479,6 +3528,16 @@ export declare type KayAppArtifactOutputFile = {
 };
 
 export declare interface KayAppArtifactOutputs extends Omit<KayAppKnowledgeSource, "watchRoots"> {
+    /**
+     * One page of canonical output URIs across every chat or, with `sessionId`,
+     * only that chat's outputs. A cursor continues the enumeration it came from.
+     */
+    enumerate(options: {
+        readonly cursor?: JsonValue;
+        readonly limit: number;
+        readonly signal: AbortSignal;
+        readonly sessionId?: string;
+    }): ReturnType<KayAppKnowledgeSource["enumerate"]>;
     subscribe(listener: (change: ArtifactOutputChange) => void): () => void;
     /**
      * The exact bytes of one canonical `output://<session>/<name>` file, at most `maxBytes`
@@ -3494,6 +3553,13 @@ export declare interface KayAppArtifactOutputs extends Omit<KayAppKnowledgeSourc
 export declare interface KayAppArtifacts {
     /** Activation-only request for the public artifacts.read {kind: output} capability. */
     outputs(): KayAppArtifactOutputs;
+    /**
+     * Private API: only plugins Bonsai ships; refused for any other. The absolute path of the file
+     * an address names as `sessionId`'s agent would see it (`output://`, `file://` and the other
+     * file-backed schemes), or `undefined` when it names no readable file. Checked against
+     * `artifacts.resolve-file`; a refused call rejects.
+     */
+    resolveFile?(sessionId: string, uri: string): Promise<string | undefined>;
 }
 
 /** A persisted assistant message, published without waiting for its subscribers. */
@@ -5198,6 +5264,13 @@ export declare interface KayAppPaths {
      * empty directory rather than an error.
      */
     readonly sessionsRoot?: string;
+    /**
+     * Absolute path to the folder holding the scratch working folders of chats started without a
+     * folder of their own (`<chatsRoot>/<id>`). Files written there belong to that one chat. Ask for
+     * this rather than deriving it: Desktop keeps it under the app's user-data root, not beside
+     * {@link sessionsRoot}. Absent when the host composed none.
+     */
+    readonly chatsRoot?: string;
     /**
      * Absolute path to Bonsai's local telemetry directory. The live telemetry lane itself is a
      * Postgres table (`telemetry.usage_events`), not anything under this path; it is never a
@@ -5337,6 +5410,11 @@ export declare interface KayAppPluginApi {
      * which blocks the daemon; see {@link KayAppRepos}.
      */
     readonly repos: KayAppRepos;
+    /**
+     * Private API: only plugins Bonsai ships; refused for any other. Runs a program the host bound
+     * for this plugin; see {@link KayAppProcess}. Absent when the host composed no program bindings.
+     */
+    readonly process?: KayAppProcess;
     /**
      * File I/O in user folders (stat, read, list, walk, realpath, write, mkdir, rename), run by the
      * host on its own worker threads under a deadline and answered as a typed result. Always present
@@ -5601,8 +5679,25 @@ export declare interface KayAppPollResult<Cursor extends JsonValue> {
     readonly summary?: string;
 }
 
+/**
+ * Private API: only plugins Bonsai ships; refused for any other. Run a program the host bound
+ * for this plugin, the way {@link import("../kay-agent/index.ts").KayAgentProcess} does for an
+ * agent tool: the plugin names a command and an argument class, the host owns the executable,
+ * which arguments belong to the class, the time limit, the output cap, the working directory and
+ * the environment. Each run is checked against `process.run` and then the exact
+ * `process.spawn {command, argvClass}` claim; a refusal rejects with `KayAgentCapabilityError`,
+ * a timeout resolves with exit code 124.
+ */
+export declare interface KayAppProcess {
+    run(request: KayAppProcessRunRequest): Promise<KayAppProcessRunResult>;
+}
+
 export declare type KayAppProcessingSpeed = "standard" | "fast";
 
+export declare type KayAppProcessRunRequest = KayAgentProcessRunRequest;
+
+export declare type KayAppProcessRunResult = KayAgentProcessRunResult;
+
 /**
  * A gap reason on the run-detail wire: something about the run's work the
  * daemon could not establish from its session transcripts. The vocabulary is
@@ -6265,6 +6360,18 @@ export declare type KayAppSessionPageItem = (Omit<Extract<TranscriptPageItem, {
     readonly unreadable: unknown;
 }>;
 
+/** One write for {@link KayAppSessions.assignProject}. */
+export declare interface KayAppSessionProjectAssignment {
+    readonly sessionId: string;
+    /**
+     * The project the session must still hold for the write to land: a project id, `null` for "no
+     * project" chosen on purpose, or absent for a session whose project was never decided.
+     */
+    readonly expectedProjectId?: string | null;
+    /** The project to set; `null` sets "no project". */
+    readonly projectId: string | null;
+}
+
 export declare type KayAppSessionProvenanceRecord = SessionProvenanceRecord;
 
 export declare type KayAppSessionRelationship = SessionRelationship;
@@ -6605,6 +6712,15 @@ export declare interface KayAppSessions {
     } | {
         readonly kind: "unavailable";
     }>;
+    /**
+     * Private API: only plugins Bonsai ships; refused for any other. Set the project of any stored
+     * sessions, each only while it still holds the project the caller last saw (a compare-and-set,
+     * so a person's own choice made meanwhile always wins). Answers one boolean per assignment, in
+     * order: `false` when the session is gone or its project changed. A written session's project
+     * folder and prompt block are refreshed. Checked against `sessions.assign-project`; a refused
+     * call rejects.
+     */
+    assignProject?(assignments: readonly KayAppSessionProjectAssignment[]): Promise<readonly boolean[]>;
     /**
      * Run one hidden headless system session through Bonsai's harness and resolve
      * with its final output - the sole sanctioned way for a `kay.app` plugin to
@@ -7692,6 +7808,12 @@ export declare interface KayAppSystemPromptFragment {
      * KayAppSystemPromptRegistration.refresh}.
      */
     readonly maxAgeMs?: number;
+    /**
+     * For text about the chat's project. A forked chat starts with its parent's texts unchanged, so
+     * the model's prompt cache still matches; when set, a fork whose project is then chosen drops the
+     * parent's copy of this text and renders its own. Absent: a fork keeps the parent's text.
+     */
+    readonly forksFollowProject?: boolean;
     /** The text, or `undefined` for none. A rejection leaves the text out and is logged. */
     render(request: KayAppSystemPromptRenderRequest): Promise<string | undefined>;
 }
@@ -9012,6 +9134,90 @@ declare type MatchTrueLike = (inferred: TProperties) => unknown;
 /** The most labels a recorded choice question may offer, and so the most one filter names. */
 export declare const MAX_CHOICE_LABELS = 64;
 
+/** The connection state published for one configured MCP server. */
+export declare type McpServerConnectionState = "disconnected" | "connecting" | "connected" | "needs-auth" | "failed";
+
+/** A server mark already resolved into a data URI by its publisher. */
+export declare interface McpServerIcon {
+    /** A `data:` URI. Consumers may render it directly in an `<img src>`. */
+    readonly src: string;
+    /**
+     * Where the mark came from, because the two are not equally trustworthy.
+     *
+     * `declared` is the server's own `serverInfo.icons` (MCP spec 2025-11-25, SEP-973): evidence.
+     * `favicon` is derived from an HTTP server's origin: still evidence, one step removed.
+     * A name match against Bonsai's brand table is neither, and deliberately does not appear here -
+     * that guess lives in the renderer's existing `BrandIcon` fallback, below both of these.
+     */
+    readonly source: "declared" | "favicon";
+    /** The theme the server nominated this variant for, when it declared more than one. */
+    readonly theme?: "light" | "dark";
+}
+
+/** One keyed change to the MCP inventory. */
+export declare type McpServerInventoryChange = {
+    readonly kind: "upsert";
+    readonly server: McpServerRecord;
+} | {
+    readonly kind: "remove";
+    readonly name: string;
+};
+
+/** One configured MCP server in the app-facing inventory. */
+export declare interface McpServerRecord {
+    /** The config key, and the id the `mcp.<name>` auth service keys on. */
+    readonly name: string;
+    /**
+     * The auth service that connects this server, when it has one: `mcp.<name>` for a plugins.mcp
+     * server, the shipping plugin's own service for a vendored one. The Plugins page joins a
+     * connection row to its server on THIS id - never by deriving a name from the service id,
+     * which only ever fit the user-config namespace and left every vendored server toolless.
+     */
+    readonly authServiceId?: string;
+    /** The server's own `serverInfo.title`, when it sent one. Display prefers it over `name`. */
+    readonly title?: string;
+    readonly transport: "stdio" | "http";
+    /** What the server launches or connects to: joined command for stdio, url for http. */
+    readonly target: string;
+    /** The config-level switch (`enabled: false` in `plugins.mcp`), not the connection. */
+    readonly enabled: boolean;
+    readonly state: McpServerConnectionState;
+    /** Live when connected, else from the persisted metadata cache. Zero is ordinary. */
+    readonly toolCount: number;
+    /**
+     * What this server offers, for a surface that lists it. Live when connected, else from the
+     * persisted metadata cache, so a server names its tools before it has connected this session
+     * and after a restart.
+     *
+     * NAMES AND DESCRIPTIONS ONLY. The JSON-Schema input declarations stay out: they are by far the
+     * biggest part of a tool list, nothing on this surface renders them, and this snapshot is
+     * re-encoded whenever any server changes state. A surface that genuinely needs a schema is
+     * asking a different question and should ask the agent bridge, which owns tool detail.
+     *
+     * Bounded by the publisher's tool-list limit - {@link toolCount} remains the true count, so a
+     * server past the bound still reports honestly even though the list is clipped.
+     */
+    readonly tools?: readonly McpServerToolSummary[];
+    readonly icon?: McpServerIcon;
+    /**
+     * Why a `failed` server failed, in one human-legible line, when the host knows. A broken row can
+     * then say what went wrong instead of only offering Retry.
+     */
+    readonly failure?: string;
+}
+
+/** A complete MCP inventory snapshot. */
+export declare interface McpServersSnapshot {
+    readonly servers: readonly McpServerRecord[];
+}
+
+/** A tool name and optional description for inventory presentation. */
+export declare interface McpServerToolSummary {
+    readonly name: string;
+    /** The server's own one-line description, trimmed to the publisher's summary limit. */
+    readonly description?: string;
+}
+
 export declare namespace Memory {
     export {
         Assign,
@@ -10256,6 +10462,33 @@ export declare interface PreparedAccessApproval {
     readonly binding?: unknown;
 }
 
+export declare const ProjectDirectory: z.ZodObject<{
+    id: z.ZodString;
+    path: z.ZodString;
+    defaultCwd: z.ZodString;
+    ancestorIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+
+export declare type ProjectDirectory = z.infer<typeof ProjectDirectory>;
+
+export declare const ProjectDirectoryRequest: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strict>;
+
+export declare type ProjectDirectoryRequest = z.infer<typeof ProjectDirectoryRequest>;
+
+/** `project` is null when no project has the requested id. */
+export declare const ProjectDirectoryResponse: z.ZodObject<{
+    project: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        defaultCwd: z.ZodString;
+        ancestorIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+export declare type ProjectDirectoryResponse = z.infer<typeof ProjectDirectoryResponse>;
+
 declare const Properties: (input: string) => [unknown, string] | [];
 
 declare function PropertiesMapping(input: [unknown, unknown, unknown]): unknown;

package/dist/kay-app.js

@@ -308,6 +308,31 @@ function createUnavailableUriCaller(message) {
   };
 }
 
+// packages/plugin-protocol/dist/project-directories.js
+import { z as z5 } from "zod";
+var PluginProjectDirectories = z5.strictObject({
+  /** An endpoint this plugin's app target declares; called with a {@link ProjectDirectoryRequest}. */
+  endpoint: z5.string().min(1),
+  /** A scheme this plugin's URI modules serve; a project is addressed as `<scheme>://<id>`. */
+  scheme: z5.string().min(1)
+});
+var ProjectDirectoryRequest = z5.strictObject({
+  /** The project's stable id. */
+  id: z5.string().min(1)
+});
+var ProjectDirectory = z5.strictObject({
+  id: z5.string().min(1),
+  /** Absolute path of the project's folder. */
+  path: z5.string().min(1),
+  /** Absolute path a new session in this project starts in. */
+  defaultCwd: z5.string().min(1),
+  /** Ancestor project ids, root first. */
+  ancestorIds: z5.array(z5.string().min(1))
+});
+var ProjectDirectoryResponse = z5.strictObject({
+  project: ProjectDirectory.nullable()
+});
+
 // packages/plugin-sdk/dist/endpoints.js
 function createUnavailablePluginEndpointCaller(message) {
   return {
@@ -374,41 +399,48 @@ function isCredentialShapedText(value) {
   return CREDENTIAL_VALUE_PATTERNS.some((pattern) => pattern.test(value));
 }
 
+// packages/plugin-protocol/dist/resource-invocation-cursor.js
+import { z as z6 } from "zod";
+var CorpusResourceInvocationCursor = z6.strictObject({
+  at: z6.iso.datetime({ offset: true }),
+  eventId: z6.string().min(1)
+});
+
 // packages/plugin-protocol/dist/json.js
-import { z as z5 } from "zod";
-var JsonValue = z5.lazy(() => z5.union([
-  z5.string(),
-  z5.number(),
-  z5.boolean(),
-  z5.null(),
-  z5.array(JsonValue),
-  z5.record(z5.string(), JsonValue)
+import { z as z7 } from "zod";
+var JsonValue = z7.lazy(() => z7.union([
+  z7.string(),
+  z7.number(),
+  z7.boolean(),
+  z7.null(),
+  z7.array(JsonValue),
+  z7.record(z7.string(), JsonValue)
 ]));
-var JsonObject = z5.record(z5.string(), JsonValue);
-var JsonSchema = z5.record(z5.string(), JsonValue);
+var JsonObject = z7.record(z7.string(), JsonValue);
+var JsonSchema = z7.record(z7.string(), JsonValue);
 
 // packages/plugin-protocol/dist/shell-commands.js
-import { z as z6 } from "zod";
-var PluginShellCommand = z6.strictObject({
-  name: z6.string().regex(/^[a-z][a-z0-9-]*$/),
-  aliases: z6.array(z6.string().regex(/^[a-z][a-z0-9-]*$/)).optional(),
-  endpoint: z6.string().min(1),
-  usage: z6.string().min(1)
+import { z as z8 } from "zod";
+var PluginShellCommand = z8.strictObject({
+  name: z8.string().regex(/^[a-z][a-z0-9-]*$/),
+  aliases: z8.array(z8.string().regex(/^[a-z][a-z0-9-]*$/)).optional(),
+  endpoint: z8.string().min(1),
+  usage: z8.string().min(1)
 });
-var ShellCommandOutcome = z6.strictObject({
-  exitCode: z6.number().int(),
+var ShellCommandOutcome = z8.strictObject({
+  exitCode: z8.number().int(),
   envelope: JsonValue,
   result: JsonValue.optional()
 });
-var ShellCommandRequest = z6.strictObject({
-  argv: z6.array(z6.string()),
-  cwd: z6.string(),
-  outcomes: z6.array(ShellCommandOutcome).max(3)
+var ShellCommandRequest = z8.strictObject({
+  argv: z8.array(z8.string()),
+  cwd: z8.string(),
+  outcomes: z8.array(ShellCommandOutcome).max(3)
 });
-var ShellCommandStep = z6.discriminatedUnion("kind", [
-  z6.strictObject({
-    kind: z6.literal("invoke"),
-    toolName: z6.enum([
+var ShellCommandStep = z8.discriminatedUnion("kind", [
+  z8.strictObject({
+    kind: z8.literal("invoke"),
+    toolName: z8.enum([
       "read",
       "list",
       "search",
@@ -417,13 +449,13 @@ var ShellCommandStep = z6.discriminatedUnion("kind", [
       "delete",
       "help"
     ]),
-    input: z6.record(z6.string(), JsonValue),
-    flags: z6.record(z6.string(), z6.string())
+    input: z8.record(z8.string(), JsonValue),
+    flags: z8.record(z8.string(), z8.string())
   }),
-  z6.strictObject({
-    kind: z6.literal("finish"),
-    exitCode: z6.number().int(),
-    stdout: z6.string()
+  z8.strictObject({
+    kind: z8.literal("finish"),
+    exitCode: z8.number().int(),
+    stdout: z8.string()
   })
 ]);
 
@@ -487,7 +519,7 @@ function submit(label) {
 }
 
 // packages/plugin-sdk/dist/signals.js
-import { z as z7 } from "zod";
+import { z as z9 } from "zod";
 function createFallbackOnlySignals() {
   const noStore = { status: "unavailable", reason: "no-store" };
   return {
@@ -517,23 +549,23 @@ var POINTER = /^[^\s\p{C}/?#]+$/u;
 var LABEL = /^[^\s,@\p{C}]+(?: [^\s,@\p{C}]+)*$/u;
 var RUN_ID = /^\P{Cc}+$/u;
 var POINTER_RULE = `1 to ${MAX_POINTER} characters with no whitespace, \`/\`, \`?\`, \`#\`, or control or invisible character`;
-var ObserveShape = z7.looseObject({
-  detector: z7.looseObject({ id: z7.string(), version: z7.string() }),
-  subject: z7.looseObject({ kind: z7.string(), key: z7.string().optional() }).optional(),
-  after: z7.looseObject({ observationId: z7.unknown() }).optional(),
-  reuse: z7.looseObject({ maxAgeMs: z7.unknown() }).optional(),
-  source: z7.looseObject({
-    sessionId: z7.string(),
-    entryId: z7.string(),
-    openerEntryId: z7.string().optional(),
-    runId: z7.string().optional(),
-    occurredAtMs: z7.unknown().optional()
+var ObserveShape = z9.looseObject({
+  detector: z9.looseObject({ id: z9.string(), version: z9.string() }),
+  subject: z9.looseObject({ kind: z9.string(), key: z9.string().optional() }).optional(),
+  after: z9.looseObject({ observationId: z9.unknown() }).optional(),
+  reuse: z9.looseObject({ maxAgeMs: z9.unknown() }).optional(),
+  source: z9.looseObject({
+    sessionId: z9.string(),
+    entryId: z9.string(),
+    openerEntryId: z9.string().optional(),
+    runId: z9.string().optional(),
+    occurredAtMs: z9.unknown().optional()
   }),
-  questions: z7.record(z7.string(), z7.unknown())
+  questions: z9.record(z9.string(), z9.unknown())
 });
-var ChoiceQuestion = z7.looseObject({
-  type: z7.literal("choice"),
-  criteria: z7.record(z7.string(), z7.unknown())
+var ChoiceQuestion = z9.looseObject({
+  type: z9.literal("choice"),
+  criteria: z9.record(z9.string(), z9.unknown())
 });
 var fits = (value, grammar) => value.length <= MAX_NAME && grammar.test(value);
 var isWhole = (value, min) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= SIGNAL_TIME_MAX_MS;
@@ -613,10 +645,10 @@ function grammarProblem(input) {
   }
   return void 0;
 }
-var EchoText = z7.string().catch("");
-var Echo = z7.object({
-  detector: z7.object({ id: EchoText, version: EchoText }).catch({ id: "", version: "" }),
-  source: z7.object({ sessionId: EchoText, entryId: EchoText }).catch({ sessionId: "", entryId: "" })
+var EchoText = z9.string().catch("");
+var Echo = z9.object({
+  detector: z9.object({ id: EchoText, version: EchoText }).catch({ id: "", version: "" }),
+  source: z9.object({ sessionId: EchoText, entryId: EchoText }).catch({ sessionId: "", entryId: "" })
 }).catch({
   detector: { id: "", version: "" },
   source: { sessionId: "", entryId: "" }
@@ -1121,6 +1153,7 @@ var KAY_APP_DATA_CHANGE_MAX_BYTES = 256 * 1024;
 var KAY_APP_DATA_READ_REQUEST_MAX_BYTES = 64 * 1024;
 var KAY_APP_DATA_READ_RESULT_MAX_BYTES = 16 * 1024 * 1024;
 export {
+  CorpusResourceInvocationCursor,
   JsonSchema,
   JsonValue,
   KAY_APP_AUTOMATION_CONDITION_KINDS,
@@ -1140,6 +1173,9 @@ export {
   PLUGIN_SIGNAL_RELATED_KEYS,
   PLUGIN_SIGNAL_SNIPPET_MAX,
   PLUGIN_SIGNAL_TITLE_MAX,
+  ProjectDirectory,
+  ProjectDirectoryRequest,
+  ProjectDirectoryResponse,
   SIGNAL_TIME_MAX_MS,
   STORED_TRANSCRIPT_MESSAGE_FILTER,
   STORED_TRANSCRIPT_MESSAGE_KINDS,

package/dist/text-diff.d.ts

@@ -0,0 +1,106 @@
+/** What changed between the texts the card showed and the texts the person sent. */
+export declare function diffDraft(before: DraftTexts, after: DraftTexts): DraftChange;
+
+declare interface DiffSegment {
+    readonly kind: DiffSegmentKind;
+    readonly text: string;
+}
+
+declare type DiffSegmentKind = "same" | "removed" | "added";
+
+/** Compare two texts word by word. Callers normalize first; this compares what it is given. */
+export declare function diffWords(before: string, after: string): WordDiff;
+
+export declare interface DraftChange {
+    /** The normalized subject or body differ. A change in whitespace alone counts. */
+    readonly edited: boolean;
+    readonly subjectChanged: boolean;
+    readonly bodyChanged: boolean;
+    /** Words across subject and body; zero for an edit that only moved whitespace. */
+    readonly wordsAdded: number;
+    readonly wordsRemoved: number;
+    /**
+     * Words across subject and body of the draft as proposed and of the message as sent, counted the
+     * way `wordsRemoved` and `wordsAdded` are. `(beforeWords - wordsRemoved) / beforeWords` is the
+     * share of the proposed draft that was kept.
+     */
+    readonly beforeWords: number;
+    readonly afterWords: number;
+    readonly beforeChars: number;
+    readonly afterChars: number;
+    /**
+     * Either part's changed span was too long to align, so it counts as one removed block and one
+     * added block: `wordsRemoved` is then an upper bound and the share kept a lower bound.
+     */
+    readonly coarse: boolean;
+    readonly subjectDiff: WordDiff | undefined;
+    readonly bodyDiff: WordDiff | undefined;
+}
+
+export declare interface DraftTexts {
+    readonly subject: string | undefined;
+    readonly body: string;
+}
+
+/** Both ends of a text too long to show whole, and how much lay between them. */
+export declare interface HeadAndTail {
+    readonly head: string;
+    readonly tail: string;
+    /** UTF-16 units left out between `head` and `tail`; `0` when the text fit and `head` is all of it. */
+    readonly omitted: number;
+}
+
+/**
+ * The first `headMax` and the last `tailMax` UTF-16 units of `text`, each cut on a character
+ * boundary. Text that fits in `headMax + tailMax` comes back whole as `head`, with nothing omitted.
+ *
+ * For text whose ASK sits at the end (a reply that closes on a question) as well as its framing at
+ * the start: a head-only cut keeps the framing and loses the ask.
+ */
+export declare function headAndTailChars(text: string, headMax: number, tailMax: number): HeadAndTail;
+
+/** At most `max` UTF-16 units from the start of `text`, never ending inside a surrogate pair. */
+export declare function headChars(text: string, max: number): string;
+
+/** The most cells the alignment table may hold (about 2,000 tokens a side, 16 MB of Uint32). */
+export declare const MAX_LCS_CELLS = 4000000;
+
+/**
+ * Line endings, trailing whitespace on each line and trailing blank lines are not edits: a text
+ * area and a saved file disagree on them without the person touching a word.
+ */
+export declare function normalizeDraftBody(text: string): string;
+
+/** A subject is one line: any whitespace run is one space and the ends are trimmed. */
+export declare function normalizeDraftSubject(subject: string | undefined): string | undefined;
+
+/**
+ * The diff as one marked text: `[-removed-]` and `{+added+}` inside the unchanged words around
+ * them, with a long unchanged stretch collapsed to its edges and an ellipsis. The unmarked parts
+ * are the original wording, so the result reads as the final text with the edits shown.
+ */
+export declare function renderWordDiff(diff: WordDiff, options?: {
+    readonly contextWords?: number;
+    readonly maxChars?: number;
+}): {
+    readonly text: string;
+    readonly truncated: boolean;
+};
+
+/** The end index of a head that does not end inside a surrogate pair. */
+export declare function safeHeadEnd(text: string, end: number): number;
+
+/** The start index of a tail that does not begin inside a surrogate pair. */
+export declare function safeTailStart(text: string, start: number): number;
+
+export declare interface WordDiff {
+    /** Non-whitespace words present before and gone after. */
+    readonly wordsRemoved: number;
+    /** Non-whitespace words present after and not before. */
+    readonly wordsAdded: number;
+    readonly segments: readonly DiffSegment[];
+    /** The middle was too large to align, so it is one removed block and one added block. */
+    readonly coarse: boolean;
+}
+
+export { }