@flesler/cursor-canvas-web 1.0.1 → 1.1.0

package/src/vendor/canvas-sdk/collapsible-section.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Borderless disclosure row — chevron + structured header (title, optional
+ * leading slot, count, trailing slot) with a body that toggles open. Distilled
+ * from baby-glass `ContextTreeRow`'s lightweight list-row chrome (no card
+ * border, no background fill).
+ *
+ * For a bordered surface that collapses, use `<Card collapsible>` instead.
+ */
+import { type CSSProperties, type JSX, type ReactNode } from "react";
+export type CollapsibleSectionProps = {
+    /** Plain-text title rendered next to the disclosure chevron. */
+    title: string;
+    /**
+     * Optional leading visual (e.g. `<Swatch>`) shown between the chevron and
+     * the title.
+     */
+    leading?: ReactNode;
+    /**
+     * Optional small count rendered after the title (e.g. number of children).
+     */
+    count?: number;
+    /**
+     * Optional trailing node, right-aligned (e.g. token readout, badge, button).
+     * Rendered with `t.text.tertiary` color hint via the wrapper; the slot can
+     * override.
+     */
+    trailing?: ReactNode;
+    /** Body shown when expanded. */
+    children?: ReactNode;
+    /** When true, the section starts expanded (uncontrolled). */
+    defaultOpen?: boolean;
+    style?: CSSProperties;
+};
+/**
+ * Borderless collapsible row with a structured header. Starts closed unless
+ * `defaultOpen` is set.
+ *
+ * Compose with `<Swatch>` in the `leading` slot for a colored category icon,
+ * and put a token readout / pill / button in `trailing`. Body content is
+ * indented under the row so nested `CollapsibleSection`s read as a tree.
+ *
+ * For a bordered, card-shaped collapsible surface, use `<Card collapsible>`
+ * instead — `CollapsibleSection` has no border or background and is meant to
+ * sit in a list of similar rows.
+ *
+ * @example
+ * ```tsx
+ * // Basic
+ * <CollapsibleSection title="Conversation">
+ *   <Text>Messages go here.</Text>
+ * </CollapsibleSection>
+ *
+ * // With a colored category swatch + count + trailing token readout
+ * <CollapsibleSection
+ *   title="Tools"
+ *   count={4}
+ *   leading={<Swatch color="purple" />}
+ *   trailing={<Text size="small" tone="tertiary">12.3k</Text>}
+ * >
+ *   <CollapsibleSection title="Grep">
+ *     <Text>Search results.</Text>
+ *   </CollapsibleSection>
+ * </CollapsibleSection>
+ * ```
+ */
+export declare function CollapsibleSection({ title, leading, count, trailing, children, defaultOpen, style, }: CollapsibleSectionProps): JSX.Element;

package/src/vendor/canvas-sdk/dag-layout.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Pure layout math for directed acyclic graphs. Returns positioned node
+ * coordinates, edge anchor points, rank bounding boxes, and back-edge flags.
+ * Rendering is the caller's responsibility.
+ *
+ * Handles cycles gracefully: back-edges are detected via DFS, excluded from
+ * ranking, and flagged in the output so the caller can render them differently
+ * (e.g. dashed arcs).
+ */
+export type DAGLayoutOptions = {
+    /** Nodes to lay out. Only `id` is required. */
+    nodes: Array<{
+        id: string;
+    }>;
+    /** Directed edges. */
+    edges: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** Flow direction. Default `"vertical"` (top-to-bottom). */
+    direction?: "vertical" | "horizontal";
+    /** Node box width in px. Default 160. */
+    nodeWidth?: number;
+    /** Node box height in px. Default 40. */
+    nodeHeight?: number;
+    /** Gap between ranks (layers) in px. Default 64. */
+    rankGap?: number;
+    /** Gap between sibling nodes in the same rank in px. Default 48. */
+    nodeGap?: number;
+    /** Padding around the bounding box in px. Default 24. */
+    padding?: number;
+};
+export type DAGLayoutNode = {
+    id: string;
+    /** Left edge of the node box. */
+    x: number;
+    /** Top edge of the node box. */
+    y: number;
+    /** Layer index (0 = root). */
+    rank: number;
+    /** Position within the rank (0-indexed). */
+    order: number;
+};
+export type DAGLayoutEdge = {
+    from: string;
+    to: string;
+    /** Suggested source anchor point (center of the outgoing side). */
+    sourceX: number;
+    sourceY: number;
+    /** Suggested target anchor point (center of the incoming side). */
+    targetX: number;
+    targetY: number;
+    /** True when this edge was identified as a back-edge (part of a cycle). */
+    isBackEdge: boolean;
+};
+export type DAGLayoutRank = {
+    /** Rank index (0 = root). */
+    rank: number;
+    /** Left edge of the rank bounding box. */
+    x: number;
+    /** Top edge of the rank bounding box. */
+    y: number;
+    /** Width of the rank bounding box. */
+    width: number;
+    /** Height of the rank bounding box. */
+    height: number;
+    /** Node ids in this rank, in order. */
+    nodeIds: string[];
+};
+export type DAGLayoutResult = {
+    nodes: DAGLayoutNode[];
+    edges: DAGLayoutEdge[];
+    /** Bounding box per rank — useful for drawing layer bands. */
+    ranks: DAGLayoutRank[];
+    /** The direction used for this layout. */
+    direction: "vertical" | "horizontal";
+    /** Total width of the bounding box. */
+    width: number;
+    /** Total height of the bounding box. */
+    height: number;
+};
+/**
+ * Compute a hierarchical layout for a directed graph.
+ *
+ * Returns node positions, edge anchor points, rank bounding boxes, and
+ * back-edge flags. The caller handles all rendering.
+ *
+ * @example
+ * ```ts
+ * const layout = computeDAGLayout({
+ *   nodes: [{ id: "a" }, { id: "b" }, { id: "c" }],
+ *   edges: [{ from: "a", to: "b" }, { from: "b", to: "c" }],
+ * });
+ *
+ * // layout.nodes[i].x / .y → position your own SVG/HTML elements
+ * // layout.edges[i].sourceX/Y, targetX/Y → draw lines between them
+ * // layout.edges[i].isBackEdge → style cycle edges differently
+ * // layout.ranks[i] → draw layer bands behind each rank
+ * ```
+ */
+export declare function computeDAGLayout(options: DAGLayoutOptions): DAGLayoutResult;

package/src/vendor/canvas-sdk/diff-view.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Low-level diff primitives for the canvas SDK.
+ *
+ * The canvas diff surface is intentionally minimal — two components that
+ * compose with the generic `Card` / `CardHeader` / `CardBody` / `Pill` /
+ * `Text` primitives to build any diff layout an agent can imagine:
+ *
+ * - `DiffView` — a monospaced, syntax-highlighted unified diff renderer.
+ *   Drops into any container (a `Card`, a table cell, a bare layout,
+ *   nothing at all). No card chrome, no header, no path display. Pass
+ *   `path` to auto-detect the language for highlighting, or `language`
+ *   to override.
+ *
+ * - `DiffStats` — the canonical `+N` green / `-N` red glyph pair. Use
+ *   it anywhere a small "added/deleted" summary makes sense — in a
+ *   `CardHeader`'s `trailing` slot, next to a filename in a file tree,
+ *   inside a status row, etc.
+ *
+ * For file-level metadata the preferred composition is to use the
+ * generic `Card` family:
+ *
+ * ```tsx
+ * <Card collapsible>
+ *   <CardHeader trailing={<DiffStats additions={5} deletions={2} />}>
+ *     src/utils.ts
+ *   </CardHeader>
+ *   <CardBody style={{ padding: 0 }}>
+ *     <DiffView path="src/utils.ts" lines={lines} />
+ *   </CardBody>
+ * </Card>
+ * ```
+ */
+import type { CSSProperties, JSX } from "react";
+export type DiffStatsProps = {
+    additions?: number;
+    deletions?: number;
+    style?: CSSProperties;
+};
+/**
+ * Inline `+N` / `-N` glyph pair. Green additions, red deletions, with
+ * tabular numerals so columns of stats line up. Renders nothing when
+ * both counts are zero.
+ *
+ * @example
+ * ```tsx
+ * <CardHeader trailing={<DiffStats additions={12} deletions={3} />}>
+ *   src/utils.ts
+ * </CardHeader>
+ *
+ * <Row gap={8}>
+ *   <Text>Refactor pass</Text>
+ *   <DiffStats additions={42} deletions={17} />
+ * </Row>
+ * ```
+ */
+export declare function DiffStats({ additions, deletions, style, }: DiffStatsProps): JSX.Element | null;
+export type DiffLineType = "added" | "removed" | "unchanged";
+export type DiffLineData = {
+    type: DiffLineType;
+    content: string;
+    lineNumber?: number;
+};
+export type DiffViewProps = {
+    lines: DiffLineData[];
+    /**
+     * File path used to infer the syntax-highlighting language from the
+     * extension (e.g. `"src/utils.ts"` → `typescript`). The most ergonomic
+     * way to enable highlighting — pass the same path you show in the
+     * enclosing card header. Unknown extensions silently render as plain
+     * text.
+     *
+     * If both `path` and `language` are provided, `language` wins.
+     */
+    path?: string;
+    /**
+     * Explicit language override for syntax highlighting (e.g.
+     * `"typescript"`, `"python"`, `"tsx"`). Use this when no file path is
+     * available, when the path's extension is misleading, or when the
+     * content is a snippet rather than a real file. Accepts common
+     * aliases (`ts`, `py`, `rs`, `md`, etc.). Unknown languages silently
+     * fall back to plain text.
+     *
+     * Highlighting is applied per line, so multi-line constructs (block
+     * comments, template literals) may not colorize perfectly across line
+     * boundaries. For typical diff-sized inputs this is fine.
+     */
+    language?: string;
+    /** Show line numbers in the gutter. Default `true`. */
+    showLineNumbers?: boolean;
+    /** Color line numbers green/red for added/removed lines. Default `true`. */
+    coloredLineNumbers?: boolean;
+    /** Show a 3px accent strip on the left edge for changed lines. Default `true`. */
+    showAccentStrip?: boolean;
+    style?: CSSProperties;
+};
+/**
+ * Unified diff body renderer with monospaced type, colored line
+ * backgrounds, line-number gutter, accent strip, and optional Shiki
+ * syntax highlighting.
+ *
+ * `DiffView` does not provide any surrounding chrome — place it inside
+ * a `Card` + `CardBody` (with `padding: 0`) when you want the standard
+ * bordered "file diff" look, or drop it anywhere else if you want the
+ * bare renderer.
+ *
+ * Pass `path` to enable syntax highlighting from the file extension.
+ *
+ * @example
+ * ```tsx
+ * <Card>
+ *   <CardHeader trailing={<DiffStats additions={2} deletions={1} />}>
+ *     src/utils.ts
+ *   </CardHeader>
+ *   <CardBody style={{ padding: 0 }}>
+ *     <DiffView
+ *       path="src/utils.ts"
+ *       lines={[
+ *         { type: "unchanged", content: "export function add(a: number, b: number): number {", lineNumber: 1 },
+ *         { type: "removed",   content: "  return a + b;", lineNumber: 2 },
+ *         { type: "added",     content: "  const result = a + b;", lineNumber: 2 },
+ *         { type: "added",     content: "  return result;", lineNumber: 3 },
+ *         { type: "unchanged", content: "}", lineNumber: 4 },
+ *       ]}
+ *     />
+ *   </CardBody>
+ * </Card>
+ * ```
+ */
+export declare function DiffView({ lines, path, language, showLineNumbers, coloredLineNumbers, showAccentStrip, style, }: DiffViewProps): JSX.Element;

package/src/vendor/canvas-sdk/form-primitives.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Form primitives for `cursor/canvas`. Provides themed, controlled form controls
+ * for interactive canvas apps with persistent state. All `onChange` callbacks
+ * receive the **value directly** (not a DOM event), so they pair naturally
+ * with `useCanvasState`:
+ *
+ * ```tsx
+ * const [name, setName] = useCanvasState("name", "");
+ * <TextInput value={name} onChange={setName} placeholder="Enter name…" />
+ * ```
+ */
+import { type CSSProperties, type JSX, type ReactNode } from "react";
+export type TextInputProps = {
+    value?: string;
+    /** Called with the new string value on every keystroke. */
+    onChange?: (value: string) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    type?: "text" | "email" | "password" | "number" | "url" | "search";
+    style?: CSSProperties;
+};
+/**
+ * Single-line text input (28px height). Use for names, titles, search
+ * queries, and short text fields.
+ *
+ * `onChange` receives the **string value**, not a DOM event — this pairs
+ * directly with `useCanvasState` setters.
+ *
+ * @example
+ * ```tsx
+ * const [name, setName] = useCanvasState("name", "");
+ *
+ * <TextInput value={name} onChange={setName} placeholder="Task title…" />
+ * ```
+ */
+export declare function TextInput({ value, onChange, placeholder, disabled, type, style, }: TextInputProps): JSX.Element;
+export type TextAreaProps = {
+    value?: string;
+    /** Called with the new string value on every keystroke. */
+    onChange?: (value: string) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    /** Minimum visible rows. Defaults to 3. */
+    rows?: number;
+    style?: CSSProperties;
+};
+/**
+ * Multi-line text input that auto-resizes to fit its content.
+ * Use for notes, descriptions, comments, and multi-line text fields.
+ *
+ * The textarea grows as the user types. Set `rows` for the minimum visible
+ * height (defaults to 3). Override with `style={{ height: "100px" }}` for a
+ * fixed size.
+ *
+ * @example
+ * ```tsx
+ * const [notes, setNotes] = useCanvasState("notes", "");
+ *
+ * <TextArea value={notes} onChange={setNotes} placeholder="Add notes…" rows={4} />
+ * ```
+ */
+export declare function TextArea({ value, onChange, placeholder, disabled, rows, style, }: TextAreaProps): JSX.Element;
+export type CheckboxProps = {
+    checked?: boolean;
+    /** Called with the new boolean value when toggled. */
+    onChange?: (checked: boolean) => void;
+    disabled?: boolean;
+    /** Optional label rendered beside the checkbox. Clicking the label toggles the checkbox. */
+    label?: ReactNode;
+    style?: CSSProperties;
+};
+/**
+ * Checkbox with optional label (accent blue when checked).
+ *
+ * Pass `label` to render a clickable text label beside the checkbox. Without a
+ * label, provide `title` or wrap in your own `<label>` for accessibility.
+ *
+ * @example
+ * ```tsx
+ * const [agreed, setAgreed] = useCanvasState("agreed", false);
+ *
+ * <Checkbox checked={agreed} onChange={setAgreed} label="I agree to the terms" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Checkbox in a list — no label, parent handles layout
+ * <Checkbox checked={item.done} onChange={(v) => toggleItem(item.id, v)} />
+ * ```
+ */
+export declare function Checkbox({ checked, onChange, disabled, label, style, }: CheckboxProps): JSX.Element;
+export type ToggleProps = {
+    checked?: boolean;
+    /** Called with the new boolean value when toggled. */
+    onChange?: (checked: boolean) => void;
+    disabled?: boolean;
+    /** `sm` = 16px track, `md` = 20px track (default `sm`). */
+    size?: "sm" | "md";
+    style?: CSSProperties;
+};
+/**
+ * Boolean toggle switch. Uses the accent color for the "on" state and a
+ * neutral fill for "off".
+ *
+ * @example
+ * ```tsx
+ * const [enabled, setEnabled] = useCanvasState("enabled", false);
+ *
+ * <Row gap={8} align="center">
+ *   <Text>Notifications</Text>
+ *   <Spacer />
+ *   <Toggle checked={enabled} onChange={setEnabled} />
+ * </Row>
+ * ```
+ */
+export declare function Toggle({ checked, onChange, disabled, size, style, }: ToggleProps): JSX.Element;
+export type SelectOption = {
+    value: string;
+    label: string;
+    disabled?: boolean;
+};
+export type SelectProps = {
+    value?: string;
+    /** Called with the new selected value. */
+    onChange?: (value: string) => void;
+    /** List of options. Each must have a unique `value`. */
+    options: SelectOption[];
+    /** Placeholder shown when no value is selected. */
+    placeholder?: string;
+    disabled?: boolean;
+    style?: CSSProperties;
+};
+/**
+ * Dropdown select (native `<select>` with themed styling).
+ *
+ * Uses a native `<select>` under the hood for reliable keyboard, screen-reader,
+ * and mobile support. The OS-rendered option list is themed for dark mode via
+ * `color-scheme` and per-option colors.
+ *
+ * @example
+ * ```tsx
+ * const [priority, setPriority] = useCanvasState("priority", "medium");
+ *
+ * <Select
+ *   value={priority}
+ *   onChange={setPriority}
+ *   options={[
+ *     { value: "low", label: "Low" },
+ *     { value: "medium", label: "Medium" },
+ *     { value: "high", label: "High" },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function Select({ value, onChange, options, placeholder, disabled, style, }: SelectProps): JSX.Element;
+export type IconButtonProps = {
+    /** Icon content: an SVG element, emoji, or unicode character. */
+    children: ReactNode;
+    onClick?: () => void;
+    disabled?: boolean;
+    /** Tooltip text. Always provide for accessibility since there is no text label. */
+    title?: string;
+    /**
+     * `"default"` is transparent until hovered; `"circle"` has a permanent
+     * background fill.
+     */
+    variant?: "default" | "circle";
+    /** `sm` = 16px, `md` = 20px (default `md`). */
+    size?: "sm" | "md";
+    style?: CSSProperties;
+};
+/**
+ * Compact icon-only button for inline actions on list items (delete, edit,
+ * expand, etc.). Accepts **any** `children` as the icon — use an inline SVG,
+ * an emoji, or a unicode character.
+ *
+ * Always provide `title` for accessibility (screen-reader label + tooltip).
+ *
+ * Canvas has no icon font, so pass icon content directly.
+ *
+ * @example
+ * ```tsx
+ * // Delete button on a card
+ * <IconButton title="Delete" onClick={() => remove(id)}>✕</IconButton>
+ *
+ * // Edit button with an SVG icon
+ * <IconButton title="Edit" variant="circle" size="sm" onClick={edit}>
+ *   <svg width={12} height={12} viewBox="0 0 12 12" fill="none">
+ *     <path d="M8.5 1.5l2 2L4 10H2V8z" stroke="currentColor" strokeWidth={1.2} />
+ *   </svg>
+ * </IconButton>
+ * ```
+ */
+export declare function IconButton({ children, onClick, disabled, title, variant, size, style, }: IconButtonProps): JSX.Element;

package/src/vendor/canvas-sdk/hooks.d.ts

@@ -0,0 +1,173 @@
+import type { CanvasHostThemeBrand, CanvasPalette, CanvasTokens, ChartPalette } from "./canvas-tokens.js";
+import { type CanvasAction } from "./internal/canvas-action-dispatch.js";
+import { type CanvasRadius, type CanvasTypography } from "./theme.js";
+/**
+ * Host theme for the current canvas. Semantic color groups (`text`, `bg`,
+ * `fill`, `stroke`, `accent`, `diff`) live at the top level for ergonomic
+ * inline-style access; `tokens` is also present as a self-reference for
+ * callers that prefer a namespaced form. There is no `colors` bag —
+ * `theme.colors.bg.primary` is not a path.
+ */
+export interface CanvasHostTheme extends CanvasTokens {
+    readonly kind: string;
+    readonly brand: CanvasHostThemeBrand;
+    readonly tokens: CanvasTokens;
+    readonly palette: CanvasPalette;
+    readonly radius: CanvasRadius;
+    readonly typography: CanvasTypography;
+    readonly chart: {
+        readonly palette: ChartPalette;
+        readonly sequence: readonly string[];
+    };
+}
+/**
+ * Raw theme payload read from the host `theme` channel. Every field is typed
+ * `unknown` on purpose: the value crosses an untrusted JSON/SSE boundary
+ * (`window.__cursorCanvas.state`), so it is validated per-field at read time
+ * rather than trusted from the wire. Mirrors `CanvasHostThemeState` from
+ * `@anysphere/constants` (the producer side); kept local so this bundled SDK
+ * stays dependency-free.
+ */
+interface RawHostThemeState {
+    readonly kind?: unknown;
+    readonly brand?: unknown;
+    readonly primary?: unknown;
+    readonly editorBackground?: unknown;
+    readonly editorForeground?: unknown;
+}
+/** Exported for unit tests only; not part of the SDK surface (see index.ts). */
+export declare function resolveTheme(raw: RawHostThemeState | undefined): CanvasHostTheme;
+/**
+ * Returns the current host theme. When no host state is available (first
+ * paint, or a dead state bridge) it falls back to the page's
+ * `prefers-color-scheme` polarity instead of assuming dark.
+ *
+ * Semantic color groups are available directly on the returned object —
+ * `accent`, `text`, `bg`, `fill`, `stroke`, `diff` — as well as `kind`
+ * (`"dark"` | `"light"` | …), `brand` (`"cursor"` | `"grok"`, default
+ * `"cursor"` when the host omits it), and `palette` (the flat color
+ * palette). There is no `theme.colors` group.
+ *
+ * Call `useHostTheme()` inside each component that needs theme access —
+ * the returned object is scoped to that component, not shared across
+ * function boundaries.
+ *
+ * Stable paths for `style={{ ... }}` usage:
+ * - `text.primary / secondary / tertiary / quaternary` — text hierarchy
+ * - `bg.editor / chrome / elevated` — surface backgrounds
+ * - `fill.primary / secondary / tertiary / quaternary` — tinted fills
+ * - `stroke.primary / secondary / tertiary` — borders and dividers
+ * - `accent.primary / control` — accent blue and button background
+ * - `text.link` — link color
+ * - `text.onAccent` — text on accent-colored surfaces
+ *
+ * Prefer built-in components (`Card`, `Button`, `Text`, etc.) over raw
+ * token usage. Reach for tokens only when no component covers the case,
+ * and stick to flat solid colors — no gradients, no box-shadows.
+ *
+ * @example
+ * ```tsx
+ * function Overview() {
+ *   const theme = useHostTheme();
+ *   return (
+ *     <div style={{ background: theme.fill.tertiary, color: theme.text.secondary, padding: 8 }}>
+ *       <span style={{ color: theme.accent.primary }}>Accent text</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useHostTheme(): CanvasHostTheme;
+/**
+ * Setter for `useCanvasState`. Accepts either a new value or an updater
+ * function that receives the previous value.
+ */
+export type SetCanvasState<T> = (action: T | ((prev: T) => T)) => void;
+/**
+ * Persistent state hook for canvas applications. Works like `React.useState`
+ * but the value survives rebuilds, reloads, and IDE restarts — it is stored
+ * in a `.canvas.data.json` sidecar file next to the canvas source.
+ *
+ * Each key is a unique string chosen by the canvas author. Keys are stable
+ * regardless of hook call order or component tree structure.
+ *
+ * @param key - Unique string identifier for this piece of state.
+ * @param defaultValue - Value returned when no persisted value exists for `key`.
+ * @returns A `[value, setValue]` tuple, same shape as `React.useState`.
+ *
+ * @example
+ * ```tsx
+ * function Counter() {
+ *   const [count, setCount] = useCanvasState("count", 0);
+ *   return <Button onClick={() => setCount(c => c + 1)}>{count}</Button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * interface Column { id: string; title: string; cardIds: string[] }
+ * function KanbanBoard() {
+ *   const [columns, setColumns] = useCanvasState<Column[]>("columns", [
+ *     { id: "todo", title: "To Do", cardIds: [] },
+ *     { id: "doing", title: "In Progress", cardIds: [] },
+ *     { id: "done", title: "Done", cardIds: [] },
+ *   ]);
+ *   // ...
+ * }
+ * ```
+ */
+export declare function useCanvasState<T>(key: string, defaultValue: T): [T, SetCanvasState<T>];
+export type { CanvasAction };
+/**
+ * Returns a stable `dispatch` function for triggering IDE actions from
+ * canvas buttons. Actions are fire-and-forget — the canvas does not
+ * receive a response.
+ *
+ * ## Available actions
+ *
+ * **`openAgent`** — Navigate the IDE to an agent conversation.
+ * `agentId` is the conversation UUID (the filename stem from the
+ * `agent-transcripts/` directory). Works for both local and
+ * cloud/background agents in Glass and classic IDE modes.
+ *
+ * **`newComposerChat`** — Open a new local agent chat with the
+ * dispatching canvas file as an @mention. Optional `userPrompt` is
+ * appended after the mention. The canvas file is resolved from the
+ * action route's `canvasId`; do not pass the path from canvas UI.
+ *
+ * **`openFile`** — Open an existing workspace file in the host IDE.
+ * `path` may be workspace-relative or absolute. Optional `selection`
+ * follows VS Code editor line/column fields.
+ *
+ * @example
+ * ```tsx
+ * function AgentLink({ agentId, title }: { agentId: string; title: string }) {
+ *   const dispatch = useCanvasAction();
+ *   return (
+ *     <Button onClick={() => dispatch({ type: "openAgent", agentId })}>
+ *       {title}
+ *     </Button>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function AskAboutCanvas() {
+ *   const dispatch = useCanvasAction();
+ *   return (
+ *     <Button
+ *       onClick={() =>
+ *         dispatch({
+ *           type: "newComposerChat",
+ *           userPrompt: "please explain what is using the most context",
+ *         })
+ *       }
+ *     >
+ *       Ask in chat
+ *     </Button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useCanvasAction(): (action: CanvasAction) => void;