@dimina-kit/devtools 0.3.2-dev.20260525152421 → 0.3.2-dev.20260601115343

package/dist/shared/ipc-channels.d.ts

@@ -96,6 +96,20 @@ export declare const ProjectChannel: {
     readonly CaptureThumbnail: "project:captureThumbnail";
     readonly GetThumbnail: "project:getThumbnail";
 };
+export declare const ProjectFsChannel: {
+    readonly GetRoot: "project:fs:getRoot";
+    readonly ReadFile: "project:fs:readFile";
+    readonly WriteFile: "project:fs:writeFile";
+    /**
+     * Synchronous (blocking) write, used ONLY by the editor's `beforeunload`
+     * flush: a hard window/app close tears the renderer down before an async
+     * `WriteFile` IPC can round-trip, so the last in-debounce-window edit would
+     * be lost. `sendSync` blocks page teardown until the bytes hit disk. Runs the
+     * SAME sandbox as `WriteFile` (see project-fs `writeFileSync`).
+     */
+    readonly WriteFileSync: "project:fs:writeFileSync";
+    readonly ListFiles: "project:fs:listFiles";
+};
 export declare const ProjectsChannel: {
     readonly List: "projects:list";
     readonly Add: "projects:add";
@@ -123,6 +137,16 @@ export declare const PanelChannel: {
     readonly Select: "panel:select";
     readonly SelectSimulator: "panel:selectSimulator";
 };
+export declare const ViewChannel: {
+    /** Update the simulator DevTools view's bounds (or hide if w/h = 0). */
+    readonly SimulatorDevtoolsBounds: "view:simulator:devtools-bounds";
+};
+export interface ViewBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 export declare const PopoverChannel: {
     readonly Show: "popover:show";
     readonly Hide: "popover:hide";

package/dist/shared/ipc-channels.js

@@ -74,6 +74,27 @@ export const ProjectChannel = {
     CaptureThumbnail: 'project:captureThumbnail',
     GetThumbnail: 'project:getThumbnail',
 };
+// ── Project file system (sandboxed to active project root) ────────────────
+//
+// Read/write access to the active project's files, used by the in-renderer
+// Monaco editor. Every path is verified against the active project root in
+// the main process (see `services/project-fs`). Replaces the OpenSumi
+// editor's `editor:fs:*` bridge — same sandbox, callable from the main
+// renderer instead of a separate WebContentsView.
+export const ProjectFsChannel = {
+    GetRoot: 'project:fs:getRoot',
+    ReadFile: 'project:fs:readFile',
+    WriteFile: 'project:fs:writeFile',
+    /**
+     * Synchronous (blocking) write, used ONLY by the editor's `beforeunload`
+     * flush: a hard window/app close tears the renderer down before an async
+     * `WriteFile` IPC can round-trip, so the last in-debounce-window edit would
+     * be lost. `sendSync` blocks page teardown until the bytes hit disk. Runs the
+     * SAME sandbox as `WriteFile` (see project-fs `writeFileSync`).
+     */
+    WriteFileSync: 'project:fs:writeFileSync',
+    ListFiles: 'project:fs:listFiles',
+};
 // ── Project list / workspace ─────────────────────────────────────────────
 export const ProjectsChannel = {
     List: 'projects:list',
@@ -99,6 +120,22 @@ export const PanelChannel = {
     Select: 'panel:select',
     SelectSimulator: 'panel:selectSimulator',
 };
+// ── Embedded views (renderer → main) ─────────────────────────────────────
+//
+// The main window's React layout owns the *positions* of the editor +
+// simulator-DevTools WebContentsView overlays — each visible placeholder
+// `<div>` measures its client rect via ResizeObserver and pushes the
+// rectangle to the main process. The view manager caches the latest
+// payload per kind and applies it to the overlay; no payload means the
+// overlay is hidden.
+//
+// Payload (after schema validation): `{ x, y, width, height }` in CSS
+// pixels relative to the window's content area (origin = top-left,
+// not including the OS chrome).
+export const ViewChannel = {
+    /** Update the simulator DevTools view's bounds (or hide if w/h = 0). */
+    SimulatorDevtoolsBounds: 'view:simulator:devtools-bounds',
+};
 // ── Popover ──────────────────────────────────────────────────────────────
 export const PopoverChannel = {
     Show: 'popover:show',

package/dist/shared/ipc-schemas.d.ts

@@ -29,6 +29,12 @@ export declare const PopoverShowSchema: z.ZodTuple<[z.ZodObject<{}, z.core.$loos
 export declare const SimulatorAttachSchema: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
 /** simulator:resize — simulator width. */
 export declare const SimulatorResizeSchema: z.ZodTuple<[z.ZodNumber], null>;
+export declare const ViewBoundsSchema: z.ZodTuple<[z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>], null>;
 /** simulator:setVisible — visible flag + simulator width. */
 export declare const SimulatorSetVisibleSchema: z.ZodTuple<[z.ZodBoolean, z.ZodNumber], null>;
 /**

package/dist/shared/ipc-schemas.js

@@ -57,6 +57,21 @@ export const SimulatorAttachSchema = z.tuple([
 ]);
 /** simulator:resize — simulator width. */
 export const SimulatorResizeSchema = z.tuple([SimWidth]);
+/**
+ * view:*:bounds — renderer-measured CSS pixel rectangle in window content
+ * coordinates. Width/height = 0 is the canonical "overlay hidden" signal.
+ * No upper bound is enforced (window can be very large); we only refuse
+ * negative/NaN values that would break setBounds.
+ */
+const NonNegInt = z.number().int().min(0).max(100_000);
+export const ViewBoundsSchema = z.tuple([
+    z.object({
+        x: NonNegInt,
+        y: NonNegInt,
+        width: NonNegInt,
+        height: NonNegInt,
+    }),
+]);
 /** simulator:setVisible — visible flag + simulator width. */
 export const SimulatorSetVisibleSchema = z.tuple([z.boolean(), SimWidth]);
 /**

package/dist/shared/types.d.ts

@@ -27,9 +27,33 @@ export type BuiltinModuleId = 'projects' | 'session' | 'simulator' | 'popover' |
  * Cross-IPC / renderer shape of a toolbar action. Carries no `handler` — the
  * handler is non-serialisable and never crosses the IPC boundary.
  */
+export type ToolbarActionPlacement = 'leading' | 'primary' | 'trailing';
+export type ToolbarActionKind = 'button' | 'avatar';
+export type BeforeOpenProjectResult = {
+    allow: true;
+    statusMessage?: string;
+} | {
+    allow: false;
+    reason: string;
+    userMessage?: string;
+};
 export interface ToolbarAction {
     id: string;
     label: string;
+    /** Visual treatment. `avatar` keeps an account entry circular even without an image URL. */
+    kind?: ToolbarActionKind;
+    /**
+     * Optional visual placement in the project-window header.
+     * Omitted actions default to `primary` so existing hosts remain visible
+     * near the compile controls.
+     */
+    placement?: ToolbarActionPlacement;
+    /** Short text glyph rendered before the label for compact host actions. */
+    icon?: string;
+    /** Explicit fallback text for avatar actions when no image URL is available. */
+    displayInitial?: string;
+    /** Avatar image URL for account-style actions. Falls back to label initials. */
+    avatarUrl?: string;
 }
 /**
  * Host-facing toolbar action passed to `instance.toolbar.set()`. Includes the
@@ -39,6 +63,11 @@ export interface ToolbarAction {
 export interface ToolbarActionInput {
     id: string;
     label: string;
+    kind?: ToolbarActionKind;
+    placement?: ToolbarActionPlacement;
+    icon?: string;
+    displayInitial?: string;
+    avatarUrl?: string;
     handler: () => void | Promise<void>;
 }
 export interface WorkbenchConfig {
@@ -132,6 +161,10 @@ export interface WorkbenchHostInstance {
         set(actions: ToolbarActionInput[]): void;
     };
 }
+export type BeforeOpenProjectHook = (ctx: {
+    projectPath: string;
+    instance: WorkbenchHostInstance;
+}) => BeforeOpenProjectResult | Promise<BeforeOpenProjectResult>;
 /**
  * Pluggable backend for the project-list panel. Hosts may supply this to
  * take over project storage from the default `<userData>/dimina-projects.json`.
@@ -149,6 +182,8 @@ export interface ProjectsProvider {
     updateLastOpened?(dirPath: string): void | Promise<void>;
     getCompileConfig?(dirPath: string): unknown;
     saveCompileConfig?(dirPath: string, cfg: unknown): void | Promise<void>;
+    saveThumbnail?(dirPath: string, imageDataUrl: string): void | Promise<void>;
+    getThumbnail?(dirPath: string): string | null | Promise<string | null>;
 }
 export interface ProjectTemplate {
     id: string;
@@ -182,6 +217,8 @@ export interface WorkbenchAppConfig extends WorkbenchConfig {
     menuBuilder?: (mainWindow: import('electron').BrowserWindow, menuContext: MenuContext) => void;
     /** Called after window and context are created but before start() resolves. Use to register custom IPC handlers. */
     onSetup?: (instance: WorkbenchHostInstance) => void | Promise<void>;
+    /** Called after project-directory validation but before an active session is closed and a new project compile starts. */
+    onBeforeOpenProject?: BeforeOpenProjectHook;
     /** Called before window close when a session is active. Session disposal happens automatically after this hook. */
     onBeforeClose?: (instance: WorkbenchHostInstance) => void | Promise<void>;
     /** Custom update checker. If provided, enables the check-for-updates feature. */

package/dist/shared/vpath.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Phase 0 vpath resolver.
+ *
+ * Spec: `docs/file-system.md` §3.3 — single resolver shared by every FSM
+ * entry, the renderer-side temp store, and (Phase 1) the main-process
+ * protocol.handle / disk reader.
+ *
+ *   resolveVPath(url): { kind, writable, realPath? } | null
+ *
+ *   - `difile://_tmp/<id>`   → kind=tmp,   writable=false, no realPath
+ *   - `difile://_store/<id>` → kind=store, writable=false, realPath in base
+ *   - `difile://<rel>`       → kind=usr,   writable=true,  realPath in base
+ *
+ * Security invariants (the resolver returns `null` instead of throwing):
+ *   - any non-`difile://` scheme is rejected outright;
+ *   - any `..` segment (raw or URL-encoded) is rejected before canonicalize;
+ *   - after `path.normalize` the resulting `realPath` MUST stay inside the
+ *     sandbox base; otherwise `null`;
+ *   - reserved prefixes `_tmp/` and `_store/` are case-sensitive — `_TMP/`,
+ *     `_Tmp/`, etc. fall through to the user-data namespace.
+ */
+export type VPathKind = 'tmp' | 'store' | 'usr';
+export interface ResolvedVPath {
+    kind: VPathKind;
+    /** `tmp` and `store` are runtime-owned and read-only; `usr` is writable. */
+    writable: boolean;
+    /**
+     * Canonical local path on disk for `store` / `usr` kinds (always within the
+     * USER_DATA_PATH base directory after canonicalize). `tmp` kind has no
+     * realPath — the bytes live in the renderer-side Blob Map.
+     */
+    realPath?: string;
+}
+/**
+ * USER_DATA_PATH sandbox base. Looked up dynamically on every call so test
+ * doubles (e.g. monkey-patching `os.homedir`) and the `DIMINA_HOME` env
+ * override apply per invocation. The env override exists for headless test
+ * affordance and to keep the renderer/main store sharing one base.
+ */
+export declare function sandboxBase(): string;
+export declare function resolveVPath(url: unknown): ResolvedVPath | null;
+//# sourceMappingURL=vpath.d.ts.map

package/dist/shared/vpath.js

@@ -0,0 +1,105 @@
+/**
+ * Phase 0 vpath resolver.
+ *
+ * Spec: `docs/file-system.md` §3.3 — single resolver shared by every FSM
+ * entry, the renderer-side temp store, and (Phase 1) the main-process
+ * protocol.handle / disk reader.
+ *
+ *   resolveVPath(url): { kind, writable, realPath? } | null
+ *
+ *   - `difile://_tmp/<id>`   → kind=tmp,   writable=false, no realPath
+ *   - `difile://_store/<id>` → kind=store, writable=false, realPath in base
+ *   - `difile://<rel>`       → kind=usr,   writable=true,  realPath in base
+ *
+ * Security invariants (the resolver returns `null` instead of throwing):
+ *   - any non-`difile://` scheme is rejected outright;
+ *   - any `..` segment (raw or URL-encoded) is rejected before canonicalize;
+ *   - after `path.normalize` the resulting `realPath` MUST stay inside the
+ *     sandbox base; otherwise `null`;
+ *   - reserved prefixes `_tmp/` and `_store/` are case-sensitive — `_TMP/`,
+ *     `_Tmp/`, etc. fall through to the user-data namespace.
+ */
+// Main-process (Node ESM) resolves these natively. Simulator (vite browser
+// bundle) externalizes node builtins as no-op stubs — that's safe here only
+// because the simulator never enters the `store`/`usr` branches below
+// (renderer-side FSM forwards disk-backed reads/writes to main via IPC).
+import os from 'node:os';
+import path from 'node:path';
+const DIFILE_PREFIX = 'difile://';
+/**
+ * USER_DATA_PATH sandbox base. Looked up dynamically on every call so test
+ * doubles (e.g. monkey-patching `os.homedir`) and the `DIMINA_HOME` env
+ * override apply per invocation. The env override exists for headless test
+ * affordance and to keep the renderer/main store sharing one base.
+ */
+export function sandboxBase() {
+    const env = (typeof process !== 'undefined' && process.env && process.env.DIMINA_HOME) || '';
+    if (env) {
+        return path.join(env, 'files');
+    }
+    return path.join(os.homedir(), '.dimina', 'files');
+}
+export function resolveVPath(url) {
+    if (typeof url !== 'string')
+        return null;
+    if (!url.startsWith(DIFILE_PREFIX))
+        return null;
+    const raw = url.slice(DIFILE_PREFIX.length);
+    if (raw.length === 0)
+        return null;
+    // Decode URL-encoded sequences first so `%2e%2e` style escapes are caught
+    // by the segment check below.
+    let decoded;
+    try {
+        decoded = decodeURIComponent(raw);
+    }
+    catch {
+        return null;
+    }
+    // Reject NUL bytes (raw or %00) — Node `fs.*` throws TypeError on a NUL
+    // in the path, bypassing the API's `fail` callback and crashing the
+    // renderer. Pull the rejection up to the validator.
+    if (decoded.includes('\0'))
+        return null;
+    // Developer convention: `wx.env.USER_DATA_PATH = 'difile://'` so a write
+    // like `${USER_DATA_PATH}/foo.txt` produces `difile:///foo.txt`. Strip
+    // leading slashes so that path-joins cleanly under the sandbox base.
+    decoded = decoded.replace(/^[/\\]+/, '');
+    if (decoded.length === 0)
+        return null;
+    // Reject any '..' or '.' segment after decoding. We split on both '/' and
+    // '\\' so Windows-style separators cannot smuggle a traversal segment past
+    // the validator on POSIX hosts.
+    const segments = decoded.split(/[/\\]+/);
+    if (segments.some(s => s === '..' || s === '.'))
+        return null;
+    // Classify by reserved prefix (case-sensitive — `_TMP/` is a user file).
+    let kind;
+    let writable;
+    if (decoded.startsWith('_tmp/')) {
+        kind = 'tmp';
+        writable = false;
+    }
+    else if (decoded.startsWith('_store/')) {
+        kind = 'store';
+        writable = false;
+    }
+    else {
+        kind = 'usr';
+        writable = true;
+    }
+    // `tmp` lives in the renderer Blob Map — no realPath.
+    if (kind === 'tmp') {
+        return { kind, writable };
+    }
+    // `store` / `usr`: anchor under the sandbox base and assert containment
+    // after normalization. Defense in depth against any traversal that the
+    // segment check above missed (e.g. backslash trickery on POSIX).
+    const base = sandboxBase();
+    const joined = path.join(base, decoded);
+    const normalized = path.normalize(joined);
+    if (normalized !== base && !normalized.startsWith(base + path.sep))
+        return null;
+    return { kind, writable, realPath: normalized };
+}
+//# sourceMappingURL=vpath.js.map