@dimina-kit/devtools 0.3.1 → 0.3.2-dev.20260522085907

package/dist/shared/simulator-route.js

@@ -0,0 +1,169 @@
+/**
+ * Single source of truth for the simulator URL format.
+ *
+ * Upstream dimina (didi/dimina, since commit 68310fe) encodes the page route
+ * as query params: `?appId={id}&entry={spec}&page={spec}` where each spec is
+ * `pagePath?key=val&…`. HashRouter.syncStack rewrites the URL after every
+ * navigation; before mount, parent code consumes whatever URL it received.
+ *
+ * Every URL-building or URL-parsing site in devtools should go through this
+ * module — if upstream changes the contract again it's a single-file diff.
+ */
+const ROUTE_KEYS = ['appId', 'entry', 'page'];
+// ── Low-level encode / decode ────────────────────────────────────────────────
+/**
+ * Encode a search-param value but leave `/` and `,` un-escaped for
+ * readability. Upstream `HashRouter._encodeSearchValue` only spares `/`;
+ * we also spare `,` so CSV-style extras (e.g. `apiNamespaces=qd,mt`) stay
+ * legible in the URL. Both characters are safe in a query string.
+ */
+export function encodeRouteValue(value) {
+    return encodeURIComponent(value).replace(/%2F/g, '/').replace(/%2C/g, ',');
+}
+/** Encode `{ pagePath, query }` as `pagePath?k1=v1&k2=v2` (no trailing `?` when empty). */
+export function encodePageSpec(spec) {
+    const keys = Object.keys(spec.query);
+    if (keys.length === 0)
+        return spec.pagePath;
+    const qs = keys
+        .map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(spec.query[k] ?? '')}`)
+        .join('&');
+    return `${spec.pagePath}?${qs}`;
+}
+/** Decode `pagePath?k=v` into `{ pagePath, query }`. Tolerates missing query. */
+export function decodePageSpec(value) {
+    const qIdx = value.indexOf('?');
+    if (qIdx < 0)
+        return { pagePath: value, query: {} };
+    const pagePath = value.slice(0, qIdx);
+    const query = {};
+    for (const pair of value.slice(qIdx + 1).split('&')) {
+        if (!pair)
+            continue;
+        const eqIdx = pair.indexOf('=');
+        const k = eqIdx >= 0 ? pair.slice(0, eqIdx) : pair;
+        const v = eqIdx >= 0 ? pair.slice(eqIdx + 1) : '';
+        if (k)
+            query[decodeURIComponent(k)] = decodeURIComponent(v);
+    }
+    return { pagePath, query };
+}
+// ── Build ────────────────────────────────────────────────────────────────────
+/**
+ * Build the search-params string (without a leading `?`) for a route where
+ * `entry === current`. `extras` is appended verbatim (e.g. `apiNamespaces`).
+ */
+export function buildRouteSearch(appId, page, extras = {}) {
+    const spec = encodePageSpec(page);
+    const params = [
+        `appId=${encodeRouteValue(appId)}`,
+        `entry=${encodeRouteValue(spec)}`,
+        `page=${encodeRouteValue(spec)}`,
+    ];
+    for (const [k, v] of Object.entries(extras)) {
+        if (ROUTE_KEYS.includes(k))
+            continue;
+        params.push(`${encodeURIComponent(k)}=${encodeRouteValue(v)}`);
+    }
+    return params.join('&');
+}
+/**
+ * Build a full simulator URL. The default `host`/`pathname` match what the
+ * devkit dev server serves; both are overridable for tests.
+ */
+export function buildSimulatorUrlFromSpec(opts) {
+    const host = opts.host ?? 'localhost';
+    const pathname = opts.pathname ?? '/simulator.html';
+    const search = buildRouteSearch(opts.appId, opts.page, opts.extras ?? {});
+    return `http://${host}:${opts.port}${pathname}?${search}`;
+}
+/**
+ * Renderer-facing convenience: build a simulator URL from devtools'
+ * `CompileConfig` shape (startPage / scene / queryParams).
+ */
+export function buildSimulatorUrl(appId, compileConfig, port, apiNamespaces) {
+    const pagePath = compileConfig.startPage || 'pages/index/index';
+    const query = {};
+    for (const p of compileConfig.queryParams ?? []) {
+        if (p.key)
+            query[p.key] = p.value;
+    }
+    query.scene = String(compileConfig.scene ?? 1001);
+    const extras = {};
+    if (apiNamespaces?.length)
+        extras.apiNamespaces = apiNamespaces.join(',');
+    return buildSimulatorUrlFromSpec({
+        appId,
+        page: { pagePath, query },
+        port,
+        extras,
+    });
+}
+// ── Parse ────────────────────────────────────────────────────────────────────
+/**
+ * Parse `location.search` (the query route `?appId=&entry=&page=`) into a
+ * `SimulatorRoute`. Returns `null` when no recognisable route is present.
+ */
+export function parseLocationRoute(search) {
+    const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
+    const appId = params.get('appId');
+    const entryRaw = params.get('entry');
+    if (!appId || !entryRaw)
+        return null;
+    const entry = decodePageSpec(entryRaw);
+    const pageRaw = params.get('page');
+    const current = pageRaw && pageRaw !== entryRaw ? decodePageSpec(pageRaw) : entry;
+    return { appId, entry, current };
+}
+/** Parse a full URL string into a `SimulatorRoute`, or `null`. */
+export function parseRoute(url) {
+    if (!url)
+        return null;
+    try {
+        const u = new URL(url);
+        return parseLocationRoute(u.search);
+    }
+    catch {
+        return null;
+    }
+}
+// ── Convenience helpers ──────────────────────────────────────────────────────
+/** Return the current page path (no query) from a URL, or `''` if unparseable. */
+export function getCurrentPagePath(url) {
+    const route = parseRoute(url);
+    return route?.current.pagePath ?? '';
+}
+/**
+ * Rewrite the URL so `entry === current`. Used before a hot-reload so the
+ * container boots at just the top page — avoids merged-bundle requests for a
+ * multi-page stack that the incremental compiler never emits.
+ */
+export function collapseRouteToTopPage(url) {
+    if (!url)
+        return url;
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return url;
+    }
+    const route = parseLocationRoute(u.search);
+    if (!route)
+        return url;
+    if (route.entry.pagePath === route.current.pagePath
+        && encodePageSpec(route.entry) === encodePageSpec(route.current)) {
+        return url;
+    }
+    // Preserve non-route extras (apiNamespaces etc.) from the query portion;
+    // a non-route fragment in `u.hash`, if any, is carried through verbatim.
+    const searchParams = new URLSearchParams(u.search.startsWith('?') ? u.search.slice(1) : u.search);
+    const extras = {};
+    for (const [k, v] of searchParams) {
+        if (!ROUTE_KEYS.includes(k))
+            extras[k] = v;
+    }
+    const search = buildRouteSearch(route.appId, route.current, extras);
+    return `${u.origin}${u.pathname}?${search}${u.hash}`;
+}
+//# sourceMappingURL=simulator-route.js.map

package/dist/shared/types.d.ts

@@ -1,3 +1,4 @@
+import type { OpenProjectOptions } from '@dimina-kit/devkit';
 export interface AppInfo {
     appName?: string;
     [key: string]: unknown;
@@ -8,14 +9,7 @@ export interface ProjectSession {
     appInfo: AppInfo | unknown;
 }
 export interface CompilationAdapter {
-    openProject(opts: {
-        projectPath: string;
-        port?: number;
-        sourcemap?: boolean;
-        simulatorDir?: string;
-        onRebuild?: () => void;
-        onBuildError?: (err: unknown) => void;
-    }): Promise<ProjectSession>;
+    openProject(opts: Omit<OpenProjectOptions, 'containerDir' | 'outputDir'>): Promise<ProjectSession>;
 }
 export type BuiltinPanelId = 'wxml' | 'console' | 'appdata' | 'storage';
 export type BuiltinModuleId = 'projects' | 'session' | 'simulator' | 'popover' | 'settings';
@@ -86,6 +80,43 @@ export interface WorkbenchHostInstance {
     mainWindow: import('electron').BrowserWindow;
     context: import('../main/services/workbench-context.js').WorkbenchContext;
 }
+/**
+ * Pluggable backend for the project-list panel. Hosts may supply this to
+ * take over project storage from the default `<userData>/dimina-projects.json`.
+ *
+ * Detailed contract lives in
+ * `@dimina-kit/devtools/projects-provider` (the runtime exports it).
+ * Repeated here as a structural type so `WorkbenchAppConfig` can reference
+ * it without a circular import from the main-process tree.
+ */
+export interface ProjectsProvider {
+    listProjects(): unknown[] | Promise<unknown[]>;
+    validateProjectDir?(dirPath: string): string | null;
+    addProject(dirPath: string): unknown;
+    removeProject(dirPath: string): void | Promise<void>;
+    updateLastOpened?(dirPath: string): void | Promise<void>;
+    getCompileConfig?(dirPath: string): unknown;
+    saveCompileConfig?(dirPath: string, cfg: unknown): void | Promise<void>;
+}
+export interface ProjectTemplate {
+    id: string;
+    name: string;
+    description?: string;
+    icon?: string;
+    source?: {
+        type: 'directory';
+        path: string;
+    };
+    generate?: (target: string, opts: {
+        name: string;
+    }) => Promise<void>;
+}
+export interface CreateProjectInput {
+    name: string;
+    path: string;
+    templateId?: string;
+    extra?: Record<string, unknown>;
+}
 export interface WorkbenchAppConfig extends WorkbenchConfig {
     /** Absolute path to the renderer dist directory. Defaults to dimina-devtools' built-in renderer. */
     rendererDir?: string;
@@ -112,5 +143,48 @@ export interface WorkbenchAppConfig extends WorkbenchConfig {
         /** Override the version string passed to the checker. Default: app.getVersion() */
         getCurrentVersion?: () => string;
     };
+    /** Override the default `<userData>/dimina-projects.json` backend. */
+    projectsProvider?: ProjectsProvider;
+    /** Templates injected at the head of the list; same-id overrides a built-in. */
+    projectTemplates?: ProjectTemplate[];
+    /** Built-in policy: 'all' (default), 'none', or an allowlist of ids. */
+    builtinTemplates?: 'all' | 'none' | string[];
+    /**
+     * Host-supplied "新建项目" dialog. When provided, the renderer routes the
+     * "+" card click through IPC into this main-process hook instead of
+     * showing the built-in dialog. Receives the parent window for native
+     * dialog parenting and the merged + sanitized template list (no
+     * `generate` functions cross the IPC boundary).
+     *
+     * Return either:
+     *  - `null` — user cancelled.
+     *  - a `CreateProjectInput` — devtools runs its built-in scaffold
+     *    (copy template → write project.config.json → provider.addProject)
+     *    on the host's behalf.
+     *  - `{ ready: Project }` — the host has ALREADY created the project
+     *    (typically via its own backend). devtools skips the scaffold and
+     *    just refreshes the list. Use this when materialization is remote
+     *    or already done.
+     */
+    customCreateProjectDialog?: (ctx: {
+        parentWindow: import('electron').BrowserWindow;
+        templates: ProjectTemplate[];
+    }) => Promise<CustomCreateProjectDialogResult>;
 }
+/**
+ * Discriminated return of `customCreateProjectDialog`. `null` = cancelled.
+ * `{ ready }` = host created the project itself; devtools just refreshes.
+ * Otherwise treated as `CreateProjectInput` and devtools materializes the
+ * template locally.
+ *
+ * The `ready.Project` shape is the structural minimum devtools needs to
+ * render the card (mirrors `Project` in `./projects-provider`).
+ */
+export type CustomCreateProjectDialogResult = null | {
+    ready: {
+        name: string;
+        path: string;
+        lastOpened?: string | null;
+    };
+} | CreateProjectInput;
 //# sourceMappingURL=types.d.ts.map