/** * Canvas app self-description: the CANVAS-APP-MANIFEST comment convention and * the response-contract grammar, in one module because they are one grammar — * a manifest's embedded contract passes through the SAME normalizer the * draw_canvas tool argument does, so no app can smuggle a shape the browser * would not enforce. * * A canvas app is a normal single-file HTML document whose first HTML comment * (within the first 4 KB, by convention immediately after ) is: * * * * Everything except responseContract is documentation for the loading LLM; * only the contract is enforced (browser-side, default-closed, unchanged). */ export declare function normalizeCanvasResponseContract(raw: unknown): { contract?: Record; error?: string; }; export interface CanvasAppManifest { manifestVersion?: number; name?: string; version?: string; description?: string; data?: string; notes?: string; responseContract?: Record; /** * The app's half of the KV write switch (interactive-canvas-apps Part D.3): * `write: "viewers"` lets the canvas policy admit collaborators; the * default `"owner"` keeps writes to the owner and the agent whatever the * policy says. `shared` lists key globs (`app/task/*`) any admitted * writer may overwrite; everything else is author-bound. */ kv?: { write?: "owner" | "viewers"; shared?: string[]; }; /** * The app's INTERFACE — what an agent needs to drive this app without * reading its HTML. This is the catalog card's payload (Part F): the KV * keys the page reads and writes, the requests it queues for the agent, * and the notes it expects back. Prose fields are clipped; the whole * block is capped at CANVAS_INTERFACE_MAX_BYTES. */ interface?: CanvasAppInterface; /** Catalog tags, e.g. ["review", "release", "collaborative"]. */ tags?: string[]; } export interface CanvasAppInterface { /** KV keys the app uses, one entry per prefix or exact key. */ keys?: Array<{ /** e.g. "app/item/", "app/vote/", "cfg/deadline" */ key: string; /** Who writes it: "page" (viewers), "agent", or "both". */ writer?: "page" | "agent" | "both"; /** The value's shape, as an example object or a one-line description. */ shape?: unknown; note?: string; }>; /** Requests the page queues under req/ for the agent to drain. */ requests?: Array<{ /** The `op` field of the req/* row, e.g. "expand", "store", "summarize". */ op: string; /** The `args` shape, as an example or a one-line description. */ args?: unknown; /** What the agent writes back into `result` when it lands the row. */ result?: unknown; note?: string; }>; /** Notes the agent may write under evt/ that the page renders. */ events?: Array<{ key: string; shape?: unknown; note?: string; }>; /** Anything else an agent must know to operate the app (one paragraph). */ notes?: string; } /** Cap on the serialized `interface` block — it rides every catalog card. */ export declare const CANVAS_INTERFACE_MAX_BYTES: number; /** * Normalize a manifest's `interface` block: unknown fields dropped, lists * capped, prose clipped. Returns null when nothing usable is declared, and * `{ error }` when the block is present but over the size cap. */ export declare function normalizeCanvasAppInterface(raw: unknown): { interface: CanvasAppInterface | null; error?: string; }; /** Normalize a manifest's `kv` block: unknown fields dropped, bad shapes ignored. */ export declare function normalizeCanvasKvManifest(raw: unknown): { write: "owner" | "viewers"; shared: string[]; } | null; /** * Extract the embedded CANVAS-APP-MANIFEST from an HTML document. * * Distinguishes three outcomes on purpose: * { manifest } — present and parseable * { manifest: null } — no manifest (an ordinary canvas document) * { manifest: null, error } — a manifest was ATTEMPTED and is broken; the * draw path treats this as fail-closed when no * explicit contract argument saves the draw. */ export declare function extractCanvasAppManifest(html: string): { manifest: CanvasAppManifest | null; error?: string; }; /** * The compact "app card" fields returned to the drawing agent — never the * html. Carries the INTERFACE (keys, requests, events) and the kv switch, so * an agent that did not write the app can still drive it from this card. */ export declare function canvasAppCard(manifest: CanvasAppManifest | null): Record | undefined; /** Catalog app names: a DNS-label-ish slug, so keys and filenames stay clean. */ export declare const CANVAS_APP_NAME_RE: RegExp; /** * The catalog record for a published app (interactive-canvas-apps Part F.2): * the shared fact `apps/`. Derived from the DOCUMENT's manifest, never * from a model's memory of it; the description is the text search ranks on. */ export declare function buildCanvasAppCatalogRecord(input: { name: string; description: string; manifest: CanvasAppManifest | null; responseContract?: Record | null; source: { sessionId: string; filename: string; sha256: string; }; publishedBy: string | null; publishedAt: string; tags?: string[]; }): Record; //# sourceMappingURL=canvas-app-manifest.d.ts.map