@codecanvas-ide/engine 0.0.0-stage → 0.2.0

package/dist/types/project.d.ts

@@ -0,0 +1,123 @@
+import ts from 'typescript';
+import type { TextEdit } from './edits.js';
+import type { CodeDiagnostic, FileModel, IncomingUsage, Usage } from './types.js';
+import { type ConfigFile, type Workspace } from './workspace.js';
+export type { ConfigFile, Workspace } from './workspace.js';
+export interface ProjectOptions {
+    /**
+     * Standard library declaration files by file name (`lib.es2022.d.ts` → text), including every
+     * file they reference. Without them only syntax errors are reported, since every built-in
+     * (`Math`, `Array`, `console`) would otherwise be a type error.
+     */
+    libFiles?: Record<string, string>;
+    /** Lib entry files to load from `libFiles`. Defaults to ES2022 + DOM. */
+    lib?: string[];
+    compilerOptions?: ts.CompilerOptions;
+}
+export type RenameResult = {
+    ok: true;
+    edits: Record<string, TextEdit[]>;
+} | {
+    ok: false;
+    error: string;
+};
+/** Usage links and errors of one file, found when typing pauses. */
+export interface FileResolution {
+    usages: Usage[];
+    /** Usages in other files that point at blocks in this file. */
+    incoming: IncomingUsage[];
+    diagnostics: CodeDiagnostic[];
+}
+/**
+ * What the canvas needs from a project. `Project` does all of it in place; `RemoteProject` keeps only
+ * the per-keystroke parse and does the rest in a worker, so a pause in a big file can't stall the page.
+ */
+export interface CanvasProject {
+    /** Per-keystroke path: parse this file into blocks, right away. */
+    setFile(path: string, text: string): FileModel;
+    getModel(path: string): FileModel | undefined;
+    getText(path: string): string | undefined;
+    /** Leave out the type errors when the host reports its own (`CodeCanvas.setDiagnostics`). */
+    resolve(path: string, options?: {
+        diagnostics?: boolean;
+    }): Promise<FileResolution>;
+    renameBlock(path: string, blockId: string, newName: string): RenameResult | Promise<RenameResult>;
+}
+/**
+ * Every file of a folder, parsed into blocks, with TypeScript programs for resolving usages, type
+ * errors and renames across files: one per config file (a monorepo has one per package), else one.
+ *
+ * Two speeds: `setFile` is the per-keystroke path (incremental parse of that file only); usages,
+ * diagnostics and renames go through the language service and are meant to run when typing pauses.
+ */
+export declare class Project implements CanvasProject {
+    private projectOptions;
+    private files;
+    private projectVersion;
+    private libFiles;
+    private hasLib;
+    private libOptions;
+    private projectNamesCache;
+    private workspace;
+    private configPrograms;
+    /** Language services by config path, created when a file of that config is first resolved. */
+    private services;
+    /** Shared by the services, so a file several programs include is parsed once. */
+    private documentRegistry;
+    /** Changes when files are added or removed, or the settings change: where imports point may change then. */
+    private fileSetVersion;
+    constructor(files?: Record<string, string>, projectOptions?: ProjectOptions);
+    /** Load the standard library later, e.g. once it has been downloaded. Type errors show from then on. */
+    setLibFiles(libFiles: Record<string, string>): void;
+    /** Use the folder's tsconfig.json (or none, with null). */
+    setConfigFile(config: ConfigFile | null): void;
+    /** Use the folder's config files and workspace packages (or none, with null). */
+    setWorkspace(workspace: Workspace | null): void;
+    private reconfigure;
+    private configure;
+    /** Options for a program: the defaults, then the config's, then `ProjectOptions.compilerOptions`. */
+    private compilerOptions;
+    /** Which config each file uses, and the options of each. Worked out again when files are added or removed. */
+    private programs;
+    private configOf;
+    /** The options a file's imports resolve with: its own config's, whichever program includes it. */
+    private optionsOfFile;
+    private serviceOf;
+    private serviceOfConfig;
+    /** Add or update a file. Parses only this file, incrementally from its previous version. */
+    setFile(path: string, text: string): FileModel;
+    removeFile(path: string): void;
+    hasFile(path: string): boolean;
+    paths(): string[];
+    getModel(path: string): FileModel | undefined;
+    getText(path: string): string | undefined;
+    resolve(path: string, { diagnostics }?: {
+        diagnostics?: boolean;
+    }): Promise<FileResolution>;
+    /** Usage links from this file: within the file, and to blocks in other files (`toPath`). */
+    usages(path: string): Usage[];
+    /** Usages in other files that point at blocks in this file. */
+    usagesInto(path: string): IncomingUsage[];
+    /** Syntax errors, plus type errors when the standard library is loaded and the syntax is valid. */
+    diagnostics(path: string): CodeDiagnostic[];
+    /**
+     * Text edits that rename a block and every usage of it, in every file of the project.
+     * Usages in other files are renamed too, including imports (no `as` aliases are added).
+     */
+    renameBlock(path: string, blockId: string, newName: string): RenameResult;
+    /** The configs of a file and of the files that can use its blocks: its importers, also through re-exports. */
+    private configsUsing;
+    /** Files that import `path`, or import a file that re-exports from it (an `index.ts` of a folder or package). */
+    private importersThroughReExports;
+    private otherFileResolver;
+    private projectNames;
+    /** Files whose imports resolve to `path`. */
+    private importersOf;
+    private importsOf;
+    private moduleResolutionHost;
+    private fileExists;
+    private readFile;
+    private directoryExists;
+    /** The host of one config's program. Its files are those that use the config; their imports come in from the rest. */
+    private createHost;
+}

package/dist/types/projectServer.d.ts

@@ -0,0 +1,20 @@
+import { type ConfigFile, type FileResolution, type RenameResult, type Workspace } from './project.js';
+/** Methods a `RemoteProject` can call. Arguments and results are plain data, so any message channel carries them. */
+declare const SERVER_METHODS: readonly ["setLibFiles", "setConfigFile", "setWorkspace", "setFiles", "setFile", "removeFile", "resolve", "renameBlock"];
+export type ProjectServerMethod = (typeof SERVER_METHODS)[number];
+/** A `Project` behind plain-data methods: the worker side of a `RemoteProject`. */
+export declare class ProjectServer {
+    private project;
+    setLibFiles(libFiles: Record<string, string>): void;
+    setConfigFile(config: ConfigFile | null): void;
+    setWorkspace(workspace: Workspace | null): void;
+    setFiles(files: Record<string, string>): void;
+    setFile(path: string, text: string): void;
+    removeFile(path: string): void;
+    resolve(path: string, options?: {
+        diagnostics?: boolean;
+    }): Promise<FileResolution>;
+    renameBlock(path: string, blockId: string, newName: string): RenameResult;
+}
+export declare function callProjectServer(server: ProjectServer, method: string, args: unknown[]): unknown;
+export {};

package/dist/types/projectWorker.d.ts

@@ -0,0 +1,14 @@
+import { RemoteProject } from './remoteProject.js';
+/** The part of a `Worker`, the worker's `self`, or a `MessagePort` that the project calls use. */
+export interface MessagePortLike {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    /** MessagePorts only deliver messages after `start()`. */
+    start?(): void;
+}
+/** In a worker script: answer the `RemoteProject` on the other side of `port` (usually `self`). */
+export declare function serveProject(port: MessagePortLike): void;
+/** On the main thread: a project whose TypeScript work runs in the worker behind `port`. */
+export declare function connectProjectWorker(port: MessagePortLike): RemoteProject;

package/dist/types/remoteProject.d.ts

@@ -0,0 +1,33 @@
+import type { CanvasProject, ConfigFile, FileResolution, RenameResult, Workspace } from './project.js';
+import type { ProjectServerMethod } from './projectServer.js';
+import type { FileModel } from './types.js';
+/** Sends one call to the `ProjectServer` (in a worker) and resolves with its result. Calls arrive in order. */
+export type ProjectServerCall = (method: ProjectServerMethod, args: unknown[]) => Promise<unknown>;
+/**
+ * The canvas's project when the TypeScript work runs in a worker. The main thread only parses files
+ * into blocks (the per-keystroke path, and lazily for files no canvas shows); usage links, errors and
+ * renames are computed by a `ProjectServer` in the worker.
+ */
+export declare class RemoteProject implements CanvasProject {
+    private callServer;
+    private files;
+    constructor(callServer: ProjectServerCall);
+    /** Load many files at once. They're parsed in the worker; here only when a canvas needs them. */
+    setFiles(files: Record<string, string>): void;
+    setFile(path: string, text: string): FileModel;
+    /** Update a file no canvas shows (e.g. typed in a text editor): no parse on this thread. */
+    setFileText(path: string, text: string): void;
+    removeFile(path: string): void;
+    setLibFiles(libFiles: Record<string, string>): void;
+    /** The folder's tsconfig.json (or none, with null). */
+    setConfigFile(config: ConfigFile | null): void;
+    /** The folder's config files (one per package in a monorepo) and package.json files (or none, with null). */
+    setWorkspace(workspace: Workspace | null): void;
+    getModel(path: string): FileModel | undefined;
+    getText(path: string): string | undefined;
+    paths(): string[];
+    resolve(path: string, options?: {
+        diagnostics?: boolean;
+    }): Promise<FileResolution>;
+    renameBlock(path: string, blockId: string, newName: string): Promise<RenameResult>;
+}

package/dist/types/styles.d.ts

@@ -0,0 +1,3 @@
+/** Canvas styles. Injected once. Hosts can override the CSS variables on `.cc-root`. */
+export declare const CSS = "\n.cc-root {\n  --cc-bg: #15171c;\n  --cc-dot: rgba(255,255,255,.07);\n  --cc-frame-bg: rgba(255,255,255,.025);\n  --cc-frame-border: rgba(255,255,255,.10);\n  --cc-text: #e8eaee;\n  --cc-muted: #9aa1ad;\n  --cc-faint: #c4cad4;\n  --cc-panel: #1f2229;\n  --cc-panel-border: rgba(255,255,255,.12);\n  --cc-accent: #7aa2ff;\n  --cc-danger: #ff6b6b;\n  --cc-shadow: 0 10px 30px rgba(0,0,0,.45);\n\n  --k-import: #6b7280;   --k-import-head: #3b3f46;  --k-import-bg: #25272c;\n  --k-class: #34b27a;    --k-class-head: #1d6b4a;   --k-class-bg: rgba(52,178,122,.08);\n  --k-function: #ec5fa5; --k-function-head: #8f2f62; --k-function-bg: rgba(236,95,165,.09);\n  --k-variable: #4b8ef7; --k-variable-head: #23508f; --k-variable-bg: rgba(75,142,247,.09);\n  --k-type: #d4a92a;     --k-type-head: #6e5714;    --k-type-bg: rgba(212,169,42,.08);\n  --k-namespace: #9b8cf8; --k-namespace-head: #4d4291; --k-namespace-bg: rgba(155,140,248,.08);\n  --k-statement: #7c8799; --k-statement-head: #39414f; --k-statement-bg: rgba(124,135,153,.08);\n\n  position: relative; overflow: hidden; width: 100%; height: 100%;\n  background-color: var(--cc-bg);\n  background-image: radial-gradient(var(--cc-dot) 1.2px, transparent 1.3px);\n  color: var(--cc-text);\n  font: 13px/1.3 ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif;\n  touch-action: none; user-select: none; -webkit-user-select: none; outline: none;\n  -webkit-tap-highlight-color: transparent;\n}\n.cc-root[data-theme=\"light\"] {\n  --cc-bg: #f6f7f9; --cc-dot: rgba(0,0,0,.09);\n  --cc-frame-bg: rgba(255,255,255,.7); --cc-frame-border: rgba(0,0,0,.12);\n  --cc-text: #1d2129; --cc-muted: #5d6573; --cc-faint: #39404c;\n  --cc-panel: #ffffff; --cc-panel-border: rgba(0,0,0,.12); --cc-accent: #3366e6;\n  --cc-shadow: 0 10px 30px rgba(20,30,50,.18);\n  --k-import: #6b7280;   --k-import-head: #4b5058;  --k-import-bg: #eceef1;\n  --k-class: #1f9963;    --k-class-head: #1f9963;   --k-class-bg: rgba(31,153,99,.07);\n  --k-function: #d63e8c; --k-function-head: #d63e8c; --k-function-bg: rgba(214,62,140,.07);\n  --k-variable: #2f6fe0; --k-variable-head: #2f6fe0; --k-variable-bg: rgba(47,111,224,.07);\n  --k-type: #b58a0c;     --k-type-head: #a87f08;    --k-type-bg: rgba(181,138,12,.08);\n  --k-namespace: #6f5ce6; --k-namespace-head: #6f5ce6; --k-namespace-bg: rgba(111,92,230,.07);\n  --k-statement: #64708a; --k-statement-head: #64708a; --k-statement-bg: rgba(100,112,138,.07);\n}\n.cc-world { position: absolute; left: 0; top: 0; transform-origin: 0 0; }\n.cc-root.cc-moving .cc-world { will-change: transform; }\n.cc-frame { position: absolute; border: 1px solid var(--cc-frame-border); background: var(--cc-frame-bg); border-radius: 18px; }\n.cc-frame-title { position: absolute; left: 20px; top: 12px; font: 600 15px/20px var(--cc-font, \"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace); color: var(--cc-muted); white-space: nowrap; }\n.cc-empty { position: absolute; font-size: 15px; color: var(--cc-muted); white-space: nowrap; }\n\n.cc-block {\n  position: absolute; left: 0; top: 0; box-sizing: border-box; border-radius: 10px;\n  border: 1.5px solid var(--k); background: var(--kbg); overflow: hidden; contain: layout style;\n  cursor: default;\n}\n.cc-block.k-import { --k: var(--k-import); --kh: var(--k-import-head); --kbg: var(--k-import-bg); }\n.cc-block.k-class { --k: var(--k-class); --kh: var(--k-class-head); --kbg: var(--k-class-bg); }\n.cc-block.k-function { --k: var(--k-function); --kh: var(--k-function-head); --kbg: var(--k-function-bg); }\n.cc-block.k-variable { --k: var(--k-variable); --kh: var(--k-variable-head); --kbg: var(--k-variable-bg); }\n.cc-block.k-type { --k: var(--k-type); --kh: var(--k-type-head); --kbg: var(--k-type-bg); }\n.cc-block.k-namespace { --k: var(--k-namespace); --kh: var(--k-namespace-head); --kbg: var(--k-namespace-bg); }\n.cc-block.k-statement { --k: var(--k-statement); --kh: var(--k-statement-head); --kbg: var(--k-statement-bg); }\n.cc-block.k-import, .cc-root:not([data-theme=\"light\"]) .cc-block.k-import { border-color: #555a63; }\n\n.cc-head {\n  display: flex; align-items: center; gap: 7px; height: 32px; padding: 0 10px; box-sizing: border-box;\n  background: var(--kh); color: #fff; white-space: nowrap; overflow: hidden;\n  font: 13px/32px var(--cc-font, \"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);\n}\n.cc-kind { font-size: 10px; text-transform: uppercase; letter-spacing: .06em; opacity: .75; flex: none; }\n.cc-name { font-weight: 700; flex: none; max-width: 70%; overflow: hidden; text-overflow: ellipsis; }\n.cc-detail { opacity: .8; overflow: hidden; text-overflow: ellipsis; min-width: 0; flex: 1 1 auto; }\n.cc-tags { font-size: 10px; opacity: .7; flex: none; }\n.cc-exp { width: 6px; height: 6px; border-radius: 50%; background: #fff; opacity: .8; flex: none; }\n.cc-fold {\n  flex: none; margin-left: auto; width: 22px; height: 22px; border: 0; border-radius: 6px; padding: 0;\n  background: rgba(255,255,255,.14); color: #fff; font-size: 12px; line-height: 22px; cursor: pointer;\n}\n.cc-fold:hover { background: rgba(255,255,255,.28); }\n.cc-prev {\n  margin: 0; padding: 5px 12px 0; white-space: pre; overflow: hidden; color: var(--cc-faint); opacity: .5;\n  font: 11px/15px var(--cc-font, \"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);\n}\n.cc-more { opacity: .7; font-style: italic; }\n.cc-mini { position: relative; margin: 6px 12px 0; height: 34px; opacity: .45; }\n.cc-mini > i { position: absolute; border-radius: 2px; border: 1px solid var(--cc-faint); background: rgba(255,255,255,.06); }\n.cc-mini > i.k-class { border-color: var(--k-class); } .cc-mini > i.k-function { border-color: var(--k-function); }\n.cc-mini > i.k-variable { border-color: var(--k-variable); } .cc-mini > i.k-type { border-color: var(--k-type); }\n\n.cc-err {\n  flex: none; min-width: 18px; height: 18px; padding: 0 5px; box-sizing: border-box; border-radius: 9px;\n  background: var(--cc-danger); color: #fff; font: 700 11px/18px ui-sans-serif, system-ui, sans-serif; text-align: center;\n}\n.cc-block.cc-has-error { border-color: var(--cc-danger); }\n.cc-root.lod-2 .cc-err { min-width: 34px; height: 34px; border-radius: 17px; font-size: 22px; line-height: 34px; }\n.cc-rename {\n  font: inherit; font-weight: 700; color: #fff; background: rgba(0,0,0,.35); border: 1px solid var(--cc-accent);\n  border-radius: 4px; padding: 0 4px; height: 22px; outline: none; user-select: text; -webkit-user-select: text; max-width: 100%;\n}\n.cc-rename.invalid { border-color: var(--cc-danger); }\n.cc-name:has(.cc-rename) { max-width: none; overflow: visible; }\n\n/* merge conflicts */\n.cc-block.cc-conflict { border-color: #f0883e; box-shadow: 0 0 0 2px rgba(240, 136, 62, .35); }\n.cc-conflict-chip {\n  flex: none; min-width: 18px; height: 18px; border-radius: 9px; background: #f0883e; color: #1b1300;\n  font: 900 13px/18px ui-sans-serif, system-ui, sans-serif; text-align: center;\n}\n.cc-root.lod-2 .cc-conflict-chip { min-width: 34px; height: 34px; border-radius: 17px; font-size: 24px; line-height: 34px; }\n.cc-block.cc-conflict-incoming {\n  --k: #f0883e; --kh: #8a4a17; --kbg: rgba(240, 136, 62, .08);\n  border-style: dashed; pointer-events: none; opacity: .9;\n}\n.cc-diff-chip.incoming { background: #f0883e; }\n.cc-banner.cc-banner-conflicts { border-color: #f0883e; }\n\n/* changes against a base version (setDiffBase) */\n.cc-block.cc-diff-unchanged { filter: saturate(.3) brightness(.92); }\n.cc-diff-chip {\n  flex: none; min-width: 18px; height: 18px; padding: 0 4px; box-sizing: border-box; border-radius: 5px;\n  font: 800 13px/18px ui-sans-serif, system-ui, sans-serif; text-align: center; color: #fff;\n}\n.cc-diff-chip.added { background: #2ea043; }\n.cc-diff-chip.changed { background: #d29922; }\n.cc-diff-chip.removed { background: var(--cc-danger); }\n.cc-root.lod-2 .cc-diff-chip { min-width: 34px; height: 34px; border-radius: 8px; font-size: 24px; line-height: 34px; }\n.cc-block.cc-diff-removed {\n  --k: var(--cc-danger); --kh: #9c2f2f; --kbg: rgba(255, 107, 107, .10);\n  border-style: dashed; pointer-events: none; opacity: .9;\n}\n.cc-root[data-theme=\"light\"] .cc-block.cc-diff-removed { --kh: #d64545; --kbg: rgba(214, 69, 69, .08); }\n.cc-prev.cc-diff-prev { opacity: .95; }\n.cc-diff-prev > span { display: block; margin: 0 -12px; padding: 0 12px; }\n.cc-diff-prev .cc-line-same { opacity: .5; }\n.cc-diff-prev .cc-line-added { background: rgba(46, 160, 67, .30); }\n.cc-diff-prev .cc-line-removed { background: rgba(248, 81, 73, .26); text-decoration: line-through; text-decoration-color: rgba(248, 81, 73, .7); }\n.cc-diff-summary { padding: 0 8px; font-size: 12px; color: var(--cc-muted); white-space: nowrap; }\n\n.cc-block.cc-sel { box-shadow: 0 0 0 2px var(--cc-bg), 0 0 0 4px var(--k); }\n.cc-block.cc-editing { box-shadow: 0 0 0 2px var(--cc-bg), 0 0 0 4px var(--cc-accent); }\n.cc-block.cc-dragging { box-shadow: var(--cc-shadow); opacity: .92; z-index: 9999 !important; }\n.cc-root.has-hl .cc-block.cc-linked { box-shadow: 0 0 0 2px var(--k); }\n\n.cc-edges { position: absolute; left: 0; top: 0; overflow: visible; pointer-events: none; }\n.cc-edge { fill: none; stroke-width: 1.5; opacity: .22; }\n.cc-edge.u-type { stroke-dasharray: 4 4; }\n.cc-root.has-hl .cc-edge { opacity: .07; }\n.cc-root.has-hl .cc-edge.hl { opacity: .95; stroke-width: 2.5; }\n\n/* level of detail when zoomed out */\n.cc-root.lod-1 .cc-tags { visibility: hidden; }\n.cc-root.lod-2 .cc-prev, .cc-root.lod-2 .cc-detail, .cc-root.lod-2 .cc-mini { visibility: hidden; }\n.cc-root.lod-2 .cc-head { font-size: 26px; }\n.cc-root.lod-2 .cc-kind, .cc-root.lod-2 .cc-fold { display: none; }\n.cc-root.lod-2 .cc-frame-title { font-size: 40px; line-height: 44px; top: -8px; }\n\n/* overlays (screen space) */\n.cc-banner {\n  position: absolute; left: 50%; top: 12px; transform: translateX(-50%); z-index: 20; display: flex; gap: 10px; align-items: center;\n  padding: 8px 12px; border-radius: 10px; background: var(--cc-panel); border: 1px solid var(--cc-danger); box-shadow: var(--cc-shadow);\n  font-size: 13px; max-width: calc(100% - 32px);\n}\n.cc-banner[hidden], .cc-bar[hidden], .cc-refs[hidden] { display: none; }\n.cc-toast {\n  position: absolute; left: 50%; bottom: 76px; transform: translateX(-50%); z-index: 30; padding: 8px 14px; border-radius: 10px;\n  background: var(--cc-panel); border: 1px solid var(--cc-panel-border); box-shadow: var(--cc-shadow); font-size: 13px;\n  transition: opacity .2s; pointer-events: none; max-width: calc(100% - 32px);\n}\n.cc-bar {\n  position: absolute; left: 50%; bottom: 16px; transform: translateX(-50%); z-index: 20; display: flex; align-items: center; gap: 4px;\n  padding: 5px; border-radius: 12px; background: var(--cc-panel); border: 1px solid var(--cc-panel-border); box-shadow: var(--cc-shadow);\n  width: max-content; max-width: calc(100% - 24px); box-sizing: border-box; flex-wrap: wrap; justify-content: center;\n}\n.cc-bar .cc-chip { padding: 0 10px 0 6px; font: 600 12px/30px var(--cc-font, \"JetBrains Mono\", ui-monospace, Menlo, monospace); white-space: nowrap; display: flex; align-items: center; gap: 6px; max-width: 220px; overflow: hidden; text-overflow: ellipsis; }\n.cc-bar .cc-chip i { width: 10px; height: 10px; border-radius: 3px; background: var(--k); flex: none; }\n.cc-btn {\n  border: 0; background: transparent; color: var(--cc-text); font: 500 13px/30px inherit; font-family: inherit; padding: 0 10px; border-radius: 8px;\n  cursor: pointer; white-space: nowrap; min-height: 32px;\n}\n.cc-btn:hover { background: rgba(127,127,127,.16); }\n.cc-btn.danger { color: var(--cc-danger); }\n.cc-btn.primary { background: var(--cc-accent); color: #fff; }\n.cc-sep { width: 1px; height: 20px; background: var(--cc-panel-border); margin: 0 2px; flex: none; }\n.cc-refs {\n  position: absolute; left: 50%; bottom: 64px; transform: translateX(-50%); z-index: 21; width: min(360px, calc(100% - 24px)); max-height: 45%;\n  overflow: auto; border-radius: 12px; background: var(--cc-panel); border: 1px solid var(--cc-panel-border); box-shadow: var(--cc-shadow); padding: 6px;\n}\n.cc-refs h4 { margin: 8px 8px 4px; font-size: 11px; text-transform: uppercase; letter-spacing: .06em; color: var(--cc-muted); }\n.cc-refs button {\n  display: flex; width: 100%; align-items: center; gap: 8px; border: 0; background: transparent; color: var(--cc-text); text-align: left;\n  padding: 6px 8px; border-radius: 8px; cursor: pointer; font: 12px/18px var(--cc-font, \"JetBrains Mono\", ui-monospace, Menlo, monospace);\n}\n.cc-refs button:hover { background: rgba(127,127,127,.16); }\n.cc-refs button i { width: 10px; height: 10px; border-radius: 3px; background: var(--k); flex: none; }\n.cc-refs button span:last-child { margin-left: auto; color: var(--cc-muted); }\n.cc-refs button:disabled { cursor: default; opacity: .7; }\n.cc-refs button:disabled:hover { background: transparent; }\n.cc-refs .cc-file { color: var(--cc-muted); }\n.cc-refs .cc-error-row { --k: var(--cc-danger); align-items: flex-start; }\n.cc-refs .cc-error-row i { border-radius: 50%; margin-top: 4px; }\n.cc-refs .cc-error-row span:nth-child(2) { white-space: pre-wrap; font-family: ui-sans-serif, system-ui, sans-serif; }\n.cc-refs .cc-error-row span:last-child { white-space: nowrap; }\n.cc-refs .none { padding: 4px 8px 8px; color: var(--cc-muted); font-size: 12px; }\n\n.cc-editor {\n  position: absolute; z-index: 25; display: flex; flex-direction: column; border-radius: 12px; overflow: hidden;\n  background: var(--cc-panel); border: 1px solid var(--cc-panel-border); box-shadow: var(--cc-shadow);\n}\n.cc-editor-head { display: flex; align-items: center; gap: 8px; padding: 4px 6px 4px 12px; border-bottom: 1px solid var(--cc-panel-border); }\n.cc-editor-head .cc-chip { flex: 1; min-width: 0; font: 600 12px/30px var(--cc-font, \"JetBrains Mono\", ui-monospace, Menlo, monospace); display: flex; align-items: center; gap: 6px; overflow: hidden; white-space: nowrap; }\n.cc-editor-head .cc-chip i { width: 10px; height: 10px; border-radius: 3px; background: var(--k); flex: none; }\n.cc-editor-body { flex: 1; min-height: 0; overflow: auto; user-select: text; -webkit-user-select: text; touch-action: auto; }\n.cc-editor-hint { font-size: 11px; color: var(--cc-muted); white-space: nowrap; }\n@media (max-width: 640px) { .cc-editor-hint { display: none; } }\n";
+export declare function injectStyles(doc?: Document): void;

package/dist/types/types.d.ts

@@ -0,0 +1,89 @@
+/** What a block represents. Each kind has its own color on the canvas. */
+export type BlockKind = 'import' | 'class' | 'function' | 'variable' | 'type' | 'namespace' | 'statement';
+/** Where new child code goes when a block is used as a container. */
+export type InsertStyle = 'class' | 'body' | null;
+export interface Block {
+    /** Stable id, e.g. `Cart/addItem`. Survives edits, reorders and moves in the text. */
+    id: string;
+    /** Last segment of the id, unique among siblings. */
+    key: string;
+    kind: BlockKind;
+    name: string;
+    /** Parameters and return type, e.g. `(a: number): string`. */
+    detail: string;
+    /** Small labels such as `export`, `async`, `static`. */
+    tags: string[];
+    /** Text range in the file, including attached doc comments. */
+    start: number;
+    end: number;
+    /** Offset of the declared name in the file, or -1. */
+    nameStart: number;
+    /** Faint code preview (own code only, nested blocks removed). */
+    preview: string[];
+    /** Lines left out of the preview. */
+    previewMore: number;
+    children: Block[];
+    parentId: string | null;
+    depth: number;
+    /** How to insert new nested blocks, or null if this block can't hold them. */
+    insert: InsertStyle;
+    /** Offset where new nested code is inserted (before the closing brace). */
+    insertAt: number;
+    /** Indentation of the line the block starts on. */
+    indent: string;
+}
+export type UsageKind = 'call' | 'read' | 'write' | 'type';
+/** A line on the canvas: code in `from` uses the declaration in `to`. */
+export interface Usage {
+    from: string;
+    to: string;
+    kind: UsageKind;
+    count: number;
+    /** Set when `to` is a block in another file (project path). Not drawn as a line on the canvas. */
+    toPath?: string;
+    /** For usages of imported names: the import block they go through. */
+    via?: string;
+}
+/** An error found by the host (e.g. VS Code's Problems), given to `CodeCanvas.setDiagnostics`. */
+export type HostDiagnostic = Omit<CodeDiagnostic, 'blockId'>;
+/** A usage from another file into this one. */
+export interface IncomingUsage extends Usage {
+    fromPath: string;
+}
+export interface CodeDiagnostic {
+    /** Offset in the file. */
+    start: number;
+    length: number;
+    /** 1-based. */
+    line: number;
+    message: string;
+    source: 'syntax' | 'type';
+    severity: 'error' | 'warning';
+    /** Innermost block containing the error, or null when it's outside every block. */
+    blockId: string | null;
+}
+export interface FileModel {
+    path: string;
+    text: string;
+    roots: Block[];
+    blocks: Map<string, Block>;
+    usages: Usage[];
+    /** Number of syntax errors. When > 0 the structure may be unreliable. */
+    syntaxErrors: number;
+    firstErrorLine: number;
+    /** Syntax errors from parsing. Type errors come from the project (`Project.diagnostics`). */
+    diagnostics: CodeDiagnostic[];
+    /** Indentation unit detected in the file. */
+    indentUnit: string;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+/** Saved layout of one file. Stored in the repo under `.codecanvas/`. */
+export interface FileLayout {
+    version: 1;
+    /** Block positions relative to the parent (file or container block). */
+    blocks: Record<string, Point>;
+    collapsed?: string[];
+}

package/dist/types/workspace.d.ts

@@ -0,0 +1,45 @@
+import ts from 'typescript';
+/**
+ * A TypeScript config file of the folder (`tsconfig.json`, `tsconfig.app.json`, `jsconfig.json`).
+ * Path aliases, `baseUrl` and module resolution decide which file an import points at.
+ */
+export interface ConfigFile {
+    /** Project path, e.g. `tsconfig.json` or `packages/web/tsconfig.app.json`. */
+    path: string;
+    text: string;
+    /** Configs it `extends`, by project path. Only relative `extends` are followed. */
+    extendedFiles?: Record<string, string>;
+}
+/**
+ * The folder's TypeScript settings. In a monorepo every package can have its own config: a file
+ * uses the nearest config above it that includes it (`files`, `include`, `exclude`), as in VS Code.
+ */
+export interface Workspace {
+    configFiles: ConfigFile[];
+    /**
+     * `package.json` files by project path. Packages of the workspace import each other by name
+     * (`@acme/utils`); without `node_modules`, the name is resolved to the package's source.
+     */
+    packageFiles?: Record<string, string>;
+}
+/** One config file, read: its options, and which of the project's files it includes. */
+export interface ParsedConfig {
+    path: string;
+    /** Folder of the config, `''` at the root, else ending in `/`. */
+    folder: string;
+    options: ts.CompilerOptions;
+    includes(projectPath: string): boolean;
+}
+/** Read a config file. `projectPaths` are the project's files, for its `include` and `exclude` patterns. */
+export declare function parseConfig(config: ConfigFile, projectPaths: string[]): ParsedConfig | null;
+/**
+ * The config a file uses: the nearest one above it that includes it; failing that, the nearest one
+ * above it (a file left out still gets its package's aliases). Null: no config is above it.
+ */
+export declare function configForFile(projectPath: string, configs: ParsedConfig[]): ParsedConfig | null;
+/**
+ * Path aliases that point each workspace package's name at its source: the file its `package.json`
+ * names (`types`, `exports`, `module`, `main`), its TypeScript source when that is a build output
+ * (`dist/index.js` → `src/index.ts`), or `src/index.ts`.
+ */
+export declare function workspacePackagePaths(packageFiles: Record<string, string>, hasFile: (projectPath: string) => boolean): Record<string, string[]>;

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@codecanvas-ide/engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "The canvas of CodeCanvas: TypeScript and JavaScript files as an editable diagram of blocks, with usage links, references across files, rename, errors, diffs and merge conflicts.",
+  "keywords": [
+    "typescript",
+    "javascript",
+    "code-visualization",
+    "diagram",
+    "canvas",
+    "editor",
+    "ide"
+  ],
+  "license": "MIT",
+  "author": "Daniel Feliz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/d-feliz/codecanvas.git",
+    "directory": "packages/engine"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./dist/codecanvas-engine.js": {
+      "types": "./dist/codecanvas-engine.d.ts",
+      "default": "./dist/codecanvas-engine.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.js.map",
+    "dist/codecanvas-engine.js",
+    "dist/codecanvas-engine.d.ts",
+    "dist/types",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "typescript": "5.9.3"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs"
+  }
+}