truecanvas 0.1.0

package/dist/core/index.d.ts

@@ -0,0 +1,820 @@
+import MagicString from 'magic-string';
+
+type PropValue = {
+    kind: "string";
+    value: string;
+} | {
+    kind: "number";
+    value: number;
+} | {
+    kind: "boolean";
+    value: boolean;
+} | {
+    kind: "array";
+    value: (string | number | boolean)[];
+} | {
+    kind: "expression";
+    code: string;
+};
+type NodeKind = "component" | "element" | "text" | "expression" | "fragment";
+interface AttrRange {
+    name: string;
+    start: number;
+    end: number;
+    /**
+     * For `className={cn("a b", className)}` (cn, clsx, cx, twMerge, classNames):
+     * the range of the string literal, so class edits replace it and keep the merge.
+     */
+    literal?: {
+        start: number;
+        end: number;
+    };
+}
+interface CanvasNode {
+    id: string;
+    kind: NodeKind;
+    /** Tag or component name; for text the trimmed text, for expressions the code. */
+    name: string;
+    props: Record<string, PropValue>;
+    /** Spread attributes like {...rest}. When present, some props are not statically known. */
+    spreads: number;
+    children: CanvasNode[];
+    text?: string;
+    start: number;
+    end: number;
+    line: number;
+    col: number;
+    /** Index path from the canvas root: [frameIndex, childIndex, ...]. */
+    path: number[];
+    attrs: AttrRange[];
+    nameEnd: number;
+    openEnd: number;
+    selfClosing: boolean;
+    closeStart: number;
+}
+interface CanvasFrame extends CanvasNode {
+    frameName: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number | null;
+    theme: "light" | "dark" | null;
+    device: string | null;
+    /** linked frame: the App Router page it shows (project-relative). Its layers are that page's JSX. */
+    page: string | null;
+    /** exploration copied from this page file ("Apply to page" writes it back) */
+    from: string | null;
+    /** main component frame: "components/button.tsx#Button". Its layers are that component's JSX. */
+    component: string | null;
+    /** set on linked frames once resolved */
+    link: FrameLink | null;
+}
+interface FrameLink {
+    /** "page": a linked App Router page; "component": a main component */
+    kind?: "page" | "component";
+    page: string;
+    /** URL path of the page, e.g. "/" */
+    route: string;
+    /** page and layout files whose JSX appears as layers */
+    files: string[];
+    /** false when the page has data or logic: shown as is, edit a copy instead */
+    editable: boolean;
+    reason?: string;
+}
+interface ImportInfo {
+    source: string;
+    typeOnly: boolean;
+    names: string[];
+    defaultName: string | null;
+    start: number;
+    end: number;
+    /** End of the last named specifier, for appending `, Name`. */
+    lastSpecifierEnd: number | null;
+}
+interface CanvasDoc {
+    name: string;
+    file: string;
+    frames: CanvasFrame[];
+    imports: ImportInfo[];
+    canvasNode: CanvasNode | null;
+    /** End of the "use client" directive prologue; imports must go after it. */
+    prologueEnd: number;
+    /** Top-level names declared in the canvas file itself. */
+    declared: string[];
+    error?: string;
+}
+interface PropSpec {
+    name: string;
+    type: "string" | "number" | "boolean" | "enum" | "node" | "function" | "color" | "colors" | "other";
+    options?: string[];
+    /** shown under "Advanced" in the inspector */
+    advanced?: boolean;
+    /** numeric range, from docs like "(0 to 1)" */
+    min?: number;
+    max?: number;
+    optional: boolean;
+    default?: string | number | boolean | (string | number | boolean)[];
+    description?: string;
+    typeText: string;
+}
+interface Preset {
+    name: string;
+    props: Record<string, string | number | boolean | (string | number | boolean)[]>;
+}
+interface ComponentSpec {
+    name: string;
+    /** project-relative file, or the package name for library components */
+    file: string;
+    /** set for components from npm packages: the import specifier */
+    library?: string;
+    presets?: Preset[];
+    description?: string;
+    props: PropSpec[];
+    acceptsClassName: boolean;
+    acceptsChildren: boolean;
+}
+
+declare function parseCanvas(name: string, file: string, source: string): CanvasDoc;
+/** Every node in the doc, depth-first, including frames. */
+declare function allNodes(doc: CanvasDoc): Generator<{
+    node: CanvasNode;
+    parent: CanvasNode | null;
+    frame: CanvasFrame;
+}>;
+declare function findNode(doc: CanvasDoc, id: string): {
+    node: CanvasNode;
+    parent: CanvasNode | null;
+    frame: CanvasFrame;
+} | null;
+declare function findFrame(doc: CanvasDoc, ref: string): CanvasFrame | null;
+
+type Literal = string | number | boolean | null | (string | number | boolean)[];
+declare class EditError extends Error {
+}
+/** Formats a literal as a JSX attribute: `name="v"`, `name={1}`, `name`. */
+declare function attrCode(name: string, value: Literal): string;
+/** Formats text as a JSX child; falls back to a string expression when it needs escaping. */
+declare function textCode(text: string): string;
+/**
+ * One editing session over a canvas source. Each method describes a change
+ * against the *original* positions; `result()` gives the new source.
+ */
+declare class CanvasEditor {
+    readonly source: string;
+    readonly doc: CanvasDoc;
+    readonly s: MagicString;
+    /** Path of the node that should be selected after the edit (best effort, before formatting). */
+    selectPaths: number[][];
+    private usedFrameNames;
+    private placed;
+    constructor(source: string, doc: CanvasDoc);
+    node(id: string): {
+        node: CanvasNode;
+        parent: CanvasNode | null;
+        frame: CanvasFrame;
+    };
+    frame(ref: string): CanvasFrame;
+    /** A frame id/name or a node id: whatever an agent passes as "parent". */
+    container(ref: string): CanvasNode;
+    setProp(node: CanvasNode, name: string, value: Literal | undefined, opts?: {
+        raw?: string;
+    }): void;
+    setText(node: CanvasNode, text: string): void;
+    private unitCache;
+    /** The file's indent unit: tabs, or the smallest non-zero space indent. */
+    private unit;
+    lineIndent(pos: number): string;
+    /** Where a node's real content starts/ends (JSX text includes surrounding whitespace). */
+    contentStart(n: CanvasNode): number;
+    contentEnd(n: CanvasNode): number;
+    childIndent(parent: CanvasNode): string;
+    /** Re-indents lines 2..n of a snippet so it sits at `indent`. */
+    shift(code: string, indent: string): string;
+    private openToClose;
+    private insertAt;
+    insertChild(parent: CanvasNode, index: number | undefined, jsx: string): void;
+    /** Removes a node together with its line when it sits alone on it. */
+    remove(node: CanvasNode): void;
+    duplicate(node: CanvasNode): void;
+    move(node: CanvasNode, target: CanvasNode, index: number | undefined): void;
+    wrap(nodes: CanvasNode[], open: string, close: string): void;
+    /** Like wrap, but keeps content that sits on one line on one line: `<p><X>Hi</X></p>`. */
+    wrapInline(nodes: CanvasNode[], open: string, close: string): void;
+    /** Replaces a wrapper element with its children (re-indented to its place). */
+    unwrap(node: CanvasNode): void;
+    replace(node: CanvasNode, jsx: string): void;
+    private added;
+    ensureImport(name: string, from: string): void;
+    /** Adds a whole import statement unless every name it binds is already imported. */
+    addImportStatement(statement: string): void;
+    private importsPrepended;
+    /** First imports of a file: in order, with a blank line before the code. */
+    private prependImport;
+    insertFrame(code: string): void;
+    result(): string;
+}
+
+/**
+ * Stamps every JSX element in a canvas file with `data-tc="line:col"` so the
+ * in-frame runtime can map rendered DOM back to the exact JSX in the source.
+ * Inserted on the same line, so stack traces and line numbers stay intact.
+ * App files (pages, layouts) pass their project-relative path: their ids are
+ * `file#line:col`, so they never collide with the canvas file's own ids.
+ */
+declare function injectIds(source: string, file?: string): string;
+
+interface DarkMode {
+    /** "class": toggles a class on <html>. "attribute": sets an attribute on <html>. */
+    strategy: "class" | "attribute";
+    /** Class name (class strategy) or attribute value (attribute strategy). */
+    value: string;
+    /** Attribute name for the attribute strategy, e.g. "data-theme". */
+    attribute?: string;
+    /** Value written for light mode with the attribute strategy. */
+    lightValue?: string;
+}
+interface TruecanvasConfig {
+    root: string;
+    /** Where your Next.js dev server runs. */
+    appUrl: string;
+    /** Port of the Truecanvas editor + MCP server. */
+    port: number;
+    /** Folder holding *.canvas.tsx files. */
+    canvasDir: string;
+    /** Next.js app directory ("app" or "src/app"). */
+    appDir: string;
+    /** Globs of component files shown in the Components panel. */
+    components: string[];
+    darkMode: DarkMode;
+    /** npm packages whose components appear in the Components panel (auto-detects known ones). */
+    libraries: string[];
+    /** Editor used for "Open in editor" (code, zed, cursor, webstorm…). Defaults to auto-detect. */
+    editor?: string;
+}
+declare function loadConfig(root: string, overrides?: Partial<TruecanvasConfig>): TruecanvasConfig;
+
+/**
+ * Reads component prop types with the TypeScript checker. The program is
+ * created on demand and dropped right after, so only the small JSON result
+ * stays in memory; it is rebuilt when component files change.
+ */
+declare class Catalog {
+    private root;
+    private globs;
+    private libraries;
+    private cache;
+    private loading;
+    private generation;
+    constructor(root: string, globs: string[], libraries?: string[]);
+    invalidate(): void;
+    /** Cached components; call load() first. */
+    list(): ComponentSpec[];
+    get(name: string): ComponentSpec | undefined;
+    /**
+     * Analyzes components in a short-lived worker thread: the TypeScript program
+     * is large, and a worker gives all of that memory back when it exits.
+     */
+    load(): Promise<ComponentSpec[]>;
+}
+
+interface CommentAuthor {
+    name: string;
+    kind: "user" | "agent";
+}
+interface CommentMessage {
+    id: string;
+    author: CommentAuthor;
+    text: string;
+    at: number;
+}
+interface CommentThread {
+    id: string;
+    /** frame name + position in frame coordinates */
+    frame: string;
+    x: number;
+    y: number;
+    /** the layer under the pin when it was placed (tree path + name), best effort */
+    node: {
+        path: string;
+        name: string;
+    } | null;
+    resolved: boolean;
+    resolvedBy?: CommentAuthor;
+    messages: CommentMessage[];
+    createdAt: number;
+}
+/**
+ * Comments live next to the canvas in `<page>.comments.json`, so they are
+ * versioned, reviewed and merged with git like the design itself.
+ */
+declare class Comments {
+    private config;
+    constructor(config: TruecanvasConfig);
+    file(canvas: string): string;
+    list(canvas: string): CommentThread[];
+    private save;
+    private update;
+    add(canvas: string, input: {
+        frame: string;
+        x: number;
+        y: number;
+        node?: CommentThread["node"];
+        text: string;
+        author: CommentAuthor;
+    }): CommentThread;
+    reply(canvas: string, id: string, text: string, author: CommentAuthor): CommentThread;
+    resolve(canvas: string, id: string, resolved: boolean, author: CommentAuthor): CommentThread;
+    remove(canvas: string, id: string): void;
+    /** Frames keep their comments when renamed. */
+    renameFrame(canvas: string, from: string, to: string): void;
+    renameCanvas(from: string, to: string): void;
+}
+
+interface GitFile {
+    path: string;
+    status: "modified" | "added" | "deleted" | "renamed" | "untracked";
+    staged: boolean;
+}
+interface GitStatus {
+    repo: boolean;
+    root: string | null;
+    branch: string | null;
+    /** no commits yet */
+    unborn: boolean;
+    upstream: string | null;
+    ahead: number;
+    behind: number;
+    files: GitFile[];
+    user: string | null;
+    /** main/master: the branch pull requests go into */
+    defaultBranch: string | null;
+    /** remote "origin" URL, if any */
+    remote: string | null;
+}
+interface PullRequest {
+    number: number;
+    url: string;
+    title: string;
+    state: "OPEN" | "CLOSED" | "MERGED";
+    draft: boolean;
+    review: "APPROVED" | "CHANGES_REQUESTED" | "REVIEW_REQUIRED" | null;
+    checks: {
+        passed: number;
+        failed: number;
+        pending: number;
+    };
+}
+interface GitCommit {
+    hash: string;
+    short: string;
+    subject: string;
+    author: string;
+    at: number;
+}
+/** Thin wrapper over the git CLI for the editor's Git panel. */
+declare class Git {
+    private cwd;
+    constructor(cwd: string);
+    status(): Promise<GitStatus>;
+    /** The branch PRs target: origin's HEAD, else a local main/master. */
+    defaultBranch(): Promise<string | null>;
+    /** When the last commit was made (ms), or 0 with no commits. */
+    lastCommitAt(): Promise<number>;
+    /** When a commit was made (ms). */
+    commitAt(ref: string): Promise<number>;
+    /** Commit where this branch left `base`. */
+    mergeBase(base: string): Promise<string | null>;
+    /** Files changed between a commit and HEAD, from the project root. */
+    changedSince(ref: string): Promise<string[]>;
+    /** Unified diff of these files against HEAD, including new files. */
+    diff(files: string[]): Promise<string>;
+    /**
+     * Adds files to a side branch without touching the working tree or index
+     * (used for PR screenshots), and pushes it. Returns the branch tip.
+     */
+    commitToSideBranch(branch: string, files: {
+        path: string;
+        data: Buffer;
+    }[], message: string): Promise<void>;
+    /** owner/name of the GitHub repo, if origin is on GitHub and gh is set up. */
+    githubRepo(): Promise<string | null>;
+    /** The open (or latest) pull request of the current branch. */
+    pullRequest(): Promise<PullRequest | null>;
+    createPullRequest(opts: {
+        title: string;
+        body: string;
+        base: string;
+        draft?: boolean;
+    }): Promise<string>;
+    /** Creates a GitHub repo for this project and pushes it (gh repo create). */
+    publish(name: string, isPrivate: boolean): Promise<string>;
+    /** git reports paths from the repo root; we show them from the project root. */
+    private rel;
+    branches(): Promise<{
+        current: string | null;
+        local: string[];
+        remote: string[];
+    }>;
+    /** Commits that touched these paths (newest first). */
+    log(paths: string[], limit?: number): Promise<GitCommit[]>;
+    /** A file's content at a ref, or null if it doesn't exist there. */
+    show(ref: string, file: string): Promise<string | null>;
+    commit(message: string, files: string[]): Promise<string>;
+    push(): Promise<void>;
+    pull(): Promise<void>;
+    fetch(): Promise<void>;
+    switch(branch: string, create?: boolean): Promise<void>;
+}
+
+type Actor = {
+    kind: "user";
+} | {
+    kind: "agent";
+    name: string;
+} | {
+    kind: "file";
+};
+type Command = {
+    op: "set_props";
+    canvas: string;
+    id: string;
+    props: Record<string, Literal>;
+} | {
+    op: "set_text";
+    canvas: string;
+    id: string;
+    text: string;
+} | {
+    op: "set_class";
+    canvas: string;
+    id: string;
+    className: string;
+} | {
+    op: "insert_jsx";
+    canvas: string;
+    parent: string;
+    index?: number;
+    jsx: string;
+} | {
+    op: "insert_component";
+    canvas: string;
+    parent: string;
+    index?: number;
+    component: string;
+    props?: Record<string, Literal>;
+    text?: string;
+} | {
+    op: "replace";
+    canvas: string;
+    id: string;
+    jsx: string;
+} | {
+    op: "duplicate";
+    canvas: string;
+    ids: string[];
+} | {
+    op: "delete";
+    canvas: string;
+    ids: string[];
+} | {
+    op: "move";
+    canvas: string;
+    id: string;
+    parent: string;
+    index?: number;
+} | {
+    op: "reorder";
+    canvas: string;
+    id: string;
+    delta: number;
+} | {
+    op: "wrap";
+    canvas: string;
+    ids: string[];
+    className?: string;
+} | {
+    op: "create_frame";
+    canvas: string;
+    name?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number | null;
+    theme?: "light" | "dark" | null;
+    device?: string | null;
+    jsx?: string;
+} | {
+    op: "update_frame";
+    canvas: string;
+    frame: string;
+    name?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number | null;
+    theme?: "light" | "dark" | null;
+    device?: string | null;
+} | {
+    op: "add_background";
+    canvas: string;
+    parent: string;
+    component: string;
+    preset?: string;
+} | {
+    op: "apply_preset";
+    canvas: string;
+    id: string;
+    preset: string;
+} | {
+    op: "import_route";
+    canvas: string;
+    route: string;
+    name?: string;
+    width?: number;
+    x?: number;
+    y?: number;
+    copy?: boolean;
+} | {
+    op: "explore_copy";
+    canvas: string;
+    frame: string;
+    name?: string;
+} | {
+    op: "apply_to_page";
+    canvas: string;
+    frame: string;
+} | {
+    op: "add_animation";
+    canvas: string;
+    id: string;
+    kind: "reveal" | "text";
+    effect?: string;
+    delay?: number;
+    duration?: number;
+    stagger?: number;
+    once?: boolean;
+} | {
+    op: "remove_animation";
+    canvas: string;
+    id: string;
+    kind: "reveal" | "text";
+} | {
+    op: "create_component";
+    canvas: string;
+    name: string;
+    from?: string;
+    parent?: string;
+    index?: number;
+} | {
+    op: "add_component_frame";
+    canvas: string;
+    component: string;
+    x?: number;
+    y?: number;
+    width?: number;
+} | {
+    op: "create_variants";
+    canvas: string;
+    component: string;
+    prop: string;
+    props?: Record<string, Literal>;
+    x?: number;
+    y?: number;
+};
+interface HistoryEntry {
+    id: number;
+    canvas: string;
+    label: string;
+    actor: Actor;
+    at: number;
+    before: string;
+    after: string;
+    ids: string[];
+    /** project-relative file this entry edited, when it isn't the canvas (a linked page or layout) */
+    file?: string;
+    /** frames the change touched (for "what changed" in the Git panel) */
+    frames?: string[];
+}
+type WorkspaceEvent = {
+    type: "doc";
+    canvas: string;
+    doc: CanvasDoc;
+} | {
+    type: "canvases";
+    canvases: string[];
+} | {
+    type: "catalog";
+} | {
+    type: "change";
+    entry: PublicEntry;
+    ids: string[];
+} | {
+    type: "history";
+    canvas: string;
+    undo: number;
+    redo: number;
+} | {
+    type: "focus";
+    canvas: string;
+    ids: string[];
+    actor: string;
+} | {
+    type: "agents";
+    agents: AgentInfo[];
+} | {
+    type: "presence";
+    presence: Presence;
+} | {
+    type: "canvas-renamed";
+    from: string;
+    to: string;
+} | {
+    type: "comments";
+    canvas: string;
+} | {
+    type: "motion";
+    canvas: string;
+    frame: string;
+    action: "play" | "replay" | "stop";
+} | {
+    type: "git";
+};
+/** What an agent is doing right now, for live cursors in the editor. */
+interface Presence {
+    session: string;
+    name: string;
+    canvas: string;
+    action: "reading" | "editing" | "looking";
+    label: string;
+    /** node or frame ids the agent is on */
+    ids: string[];
+    /** frame name when the target is a whole frame */
+    frame: string | null;
+    at: number;
+}
+type PublicEntry = Omit<HistoryEntry, "before" | "after">;
+interface AgentInfo {
+    session: string;
+    name: string;
+    since: number;
+    lastSeen: number;
+}
+declare class Workspace {
+    readonly config: TruecanvasConfig;
+    readonly catalog: Catalog;
+    private sources;
+    private undoStacks;
+    private redoStacks;
+    readonly feed: HistoryEntry[];
+    private seq;
+    private queue;
+    private listeners;
+    selection: {
+        canvas: string | null;
+        ids: string[];
+    };
+    agents: Map<string, AgentInfo>;
+    readonly comments: Comments;
+    readonly git: Git;
+    constructor(config: TruecanvasConfig);
+    on(fn: (e: WorkspaceEvent) => void): () => boolean;
+    emit(e: WorkspaceEvent): void;
+    canvases(): string[];
+    file(canvas: string): string;
+    relFile(canvas: string): string;
+    read(canvas: string): string;
+    doc(canvas: string): CanvasDoc;
+    /** A canvas doc with linked frames resolved to their page's layers. */
+    docFrom(canvas: string, source: string): CanvasDoc;
+    /** Where a node's code lives: the canvas, or a linked page/layout file. */
+    nodeSource(canvas: string, id: string): {
+        node: CanvasNode;
+        rel: string;
+        abs: string;
+        source: string;
+    } | null;
+    /** Page and layout files shown by linked frames, across all canvases (the Git panel counts them as design files). */
+    linkedFiles(): string[];
+    /**
+     * Files that belong with design commits besides the canvas folder: linked
+     * pages and layouts, and the motion components animations import.
+     */
+    designFiles(): string[];
+    /** Canvases with a linked frame showing this page or layout file. */
+    private canvasesLinking;
+    /** Called by the app-dir watcher: a page or layout changed (in a code editor, or by git). */
+    linkedFileChanged(rel: string): void;
+    createCanvas(name: string, actor: Actor, content?: string): string;
+    userAuthor(): Promise<CommentAuthor>;
+    commentsChanged(canvas: string): void;
+    /** Pages panel: each canvas with its frame count. */
+    canvasInfos(): {
+        name: string;
+        frames: number;
+    }[];
+    private uniqueCanvasName;
+    private canvasesChanged;
+    renameCanvas(from: string, to: string): string;
+    duplicateCanvas(name: string): string;
+    /** Deleted pages are kept in memory for this session so they can be restored. */
+    private trash;
+    deleteCanvas(name: string): void;
+    restoreCanvas(name: string): string;
+    /** Called by the file watcher. Edits made in a code editor become undoable history too. */
+    externalChange(fileName: string): void;
+    run(cmd: Command, actor: Actor): Promise<{
+        doc: CanvasDoc;
+        ids: string[];
+        label: string;
+    }>;
+    private exec;
+    /**
+     * Linked frames: a frame passed as a parent means the page's root element,
+     * and view-only pages refuse edits on their layers.
+     */
+    private routeLinked;
+    /** The page/layout file the command's layers live in, or null for the canvas. */
+    private targetOf;
+    private apply;
+    private autoImport;
+    private motion;
+    /** work resolved (async) in exec before the synchronous apply */
+    private pending;
+    private cleanCache;
+    isPrettierClean(source: string, file: string): Promise<boolean>;
+    /** Pretty-prints an agent's JSX snippet so it lands in the file readable. */
+    formatSnippet(jsx: string): Promise<string>;
+    private prettier;
+    format(source: string, file: string): Promise<string>;
+    private record;
+    /** Changes still in effect (not undone) on a canvas since a time, oldest first. */
+    changesSince(canvas: string, since: number): PublicEntry[];
+    historyState(canvas: string): {
+        undo: number;
+        redo: number;
+    };
+    private emitHistory;
+    undo(canvas: string, actor: Actor): Promise<{
+        doc: CanvasDoc;
+        label: string;
+    }>;
+    redo(canvas: string, actor: Actor): Promise<{
+        doc: CanvasDoc;
+        label: string;
+    }>;
+    private step;
+    publicFeed(): PublicEntry[];
+    touchAgent(session: string, name: string): void;
+    /** Agents that went quiet for 15 minutes are shown as disconnected. */
+    pruneAgents(maxIdle?: number): void;
+    dropAgent(session: string): void;
+    ensureRoute(): boolean;
+    /** First canvas of a project: its homepage as a linked frame when there is one, else the placeholder. */
+    private homeCanvas;
+    findFrameOf(canvas: string, ref: string): CanvasFrame;
+}
+declare function componentJsx(spec: ComponentSpec, props?: Record<string, Literal>, text?: string): string;
+
+/** Compact, token-cheap tree an agent can read: one line per node, ids in brackets. */
+declare function outlineDoc(doc: CanvasDoc, opts?: {
+    frame?: string;
+    depth?: number;
+}): string;
+declare function describeComponent(c: ComponentSpec, verbose?: boolean): string;
+
+/**
+ * Reads Tailwind v4 `@theme` blocks so agents use the project's real tokens
+ * (bg-surface, text-text-muted…) instead of guessing class names.
+ */
+declare function readDesignTokens(root: string): string;
+
+interface Device {
+    id: string;
+    name: string;
+    kind: "phone" | "tablet" | "desktop";
+    width: number;
+    height: number;
+    /** device pixel ratio */
+    dpr: number;
+    /** status bar height (phones/tablets) */
+    statusBar: number;
+    /** home indicator area at the bottom */
+    homeIndicator: number;
+    /** screen corner radius */
+    radius: number;
+    /** dynamic island / notch */
+    island?: boolean;
+}
+declare const DEVICES: Device[];
+declare function findDevice(id: string | null | undefined): Device | undefined;
+
+/**
+ * Writes an older version of a canvas next to the generated route so Next can
+ * render it like any canvas ("__compare__<name>"). Relative imports are
+ * rewritten for the new location; alias imports (@/…) work unchanged.
+ */
+declare function writeCompare(config: TruecanvasConfig, canvas: string, source: string, files?: Record<string, string>, as?: string): string;
+/** Per frame: same, changed, added (only now) or removed (only before). */
+declare function frameChanges(before: string, after: string): Record<string, "changed" | "added" | "removed" | "same">;
+
+export { type Actor, type AttrRange, type CanvasDoc, CanvasEditor, type CanvasFrame, type CanvasNode, Catalog, type Command, Comments, type ComponentSpec, DEVICES, type DarkMode, type Device, EditError, type FrameLink, Git, type HistoryEntry, type ImportInfo, type NodeKind, type Preset, type PropSpec, type PropValue, type TruecanvasConfig, Workspace, type WorkspaceEvent, allNodes, attrCode, componentJsx, describeComponent, findDevice, findFrame, findNode, frameChanges, injectIds, loadConfig, outlineDoc, parseCanvas, readDesignTokens, textCode, writeCompare };