dsh-webui-studio 0.1.0 → 0.2.0

package/lib/host/preview-draft.js

@@ -0,0 +1,162 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { createRequire, findPackageJSON } from 'node:module';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { studioCommands } from './drafts.js';
+const CLIENT_ENTRY_TIMEOUT_MS = 10_000;
+const HARMONY_BIN_ENTRY = fileURLToPath(import.meta.resolve('dsh-harmony/bin'));
+function packageNameOf(specifier) {
+    const clean = specifier.replace(/\?dsh-harmony=\d+$/, '');
+    if (clean.startsWith('.') || clean.startsWith('/') || clean.startsWith('file:') || clean.includes(':'))
+        return undefined;
+    return clean.startsWith('@') ? clean.split('/').slice(0, 2).join('/') : clean.split('/')[0];
+}
+function resolveDraft(profileDir, inputRoot) {
+    if (!isAbsolute(inputRoot))
+        throw new Error('harmony-studio: Draft root must be an absolute path');
+    const root = realpathSync(inputRoot);
+    const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    if (typeof manifest.name !== 'string' || manifest.name.length === 0) {
+        throw new Error('harmony-studio: Draft package name must be a non-empty string');
+    }
+    if (manifest.dsh?.client?.platform !== 'web') {
+        throw new Error(`harmony-studio: Draft ${JSON.stringify(manifest.name)} must declare dsh.client.platform as "web"`);
+    }
+    const profileManifest = join(profileDir, 'package.json');
+    const profile = JSON.parse(readFileSync(profileManifest, 'utf8'));
+    if (!(manifest.name in (profile.dependencies ?? {}))) {
+        throw new Error(`harmony-studio: Draft ${JSON.stringify(manifest.name)} is not a dependency of the Preview profile`);
+    }
+    const installedManifest = findPackageJSON(manifest.name, pathToFileURL(profileManifest));
+    if (installedManifest === undefined || realpathSync(dirname(installedManifest)) !== root) {
+        throw new Error(`harmony-studio: Draft ${JSON.stringify(manifest.name)} is not linked to the selected root`);
+    }
+    try {
+        createRequire(profileManifest).resolve(`${manifest.name}/client`);
+    }
+    catch {
+        throw new Error(`harmony-studio: Draft ${JSON.stringify(manifest.name)} must export "./client"`);
+    }
+    return { name: manifest.name, root };
+}
+export class StudioPreviewDraft {
+    ctx;
+    harmony;
+    commands;
+    name;
+    root;
+    entryId;
+    createdEntry = false;
+    project;
+    constructor(ctx, harmony, root, commands = studioCommands) {
+        this.ctx = ctx;
+        this.harmony = harmony;
+        this.commands = commands;
+        const draft = resolveDraft(harmony.profile().dir, root);
+        this.name = draft.name;
+        this.root = draft.root;
+    }
+    async open() {
+        const entries = [...this.ctx.loader.entries()].filter(entry => packageNameOf(entry.options.name) === this.name);
+        if (entries.length > 1)
+            throw new Error(`harmony-studio: Draft ${JSON.stringify(this.name)} has multiple Loader entries`);
+        try {
+            if (entries.length === 1) {
+                this.entryId = entries[0].id;
+            }
+            else {
+                this.entryId = await this.ctx.loader.create({ name: this.name });
+                this.createdEntry = true;
+            }
+            await this.waitForClientEntry();
+            await this.reload();
+            const graph = this.ctx.clientModules.graph();
+            if (!graph.entries.some(entry => entry.id === this.name)) {
+                throw new Error(`harmony-studio: Draft ${JSON.stringify(this.name)} left the client graph while loading its Patches`);
+            }
+            this.project = { name: this.name, root: this.root, state: 'preview-pending', graphRev: graph.rev };
+            return this;
+        }
+        catch (error) {
+            if (!this.createdEntry || this.entryId === undefined)
+                throw error;
+            const cleanupErrors = [];
+            try {
+                await this.ctx.loader.remove(this.entryId);
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+            try {
+                await this.reload();
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+            if (cleanupErrors.length > 0) {
+                throw new AggregateError([error, ...cleanupErrors], 'harmony-studio: failed to clean up Draft after Preview startup failed');
+            }
+            throw error;
+        }
+    }
+    snapshot() {
+        if (this.project === undefined)
+            throw new Error('harmony-studio: Draft Preview is still preparing');
+        return { ...this.project };
+    }
+    runtimePlugins() {
+        return [...this.ctx.loader.entries()]
+            .filter(entry => !entry.options.group)
+            .map(entry => ({ entryId: entry.id, moduleName: entry.options.name, enabled: !entry.disabled }));
+    }
+    activate(graphRev) {
+        if (this.project?.state !== 'preview-pending')
+            throw new Error('harmony-studio: Draft is not waiting for Preview confirmation');
+        const graph = this.ctx.clientModules.graph();
+        if (graph.rev !== graphRev || !graph.entries.some(entry => entry.id === this.name)) {
+            throw new Error('harmony-studio: Preview did not confirm the current Draft client graph');
+        }
+        this.project = { ...this.project, state: 'active', graphRev };
+        return this.snapshot();
+    }
+    async applyBuild() {
+        if (this.project?.state !== 'active')
+            throw new Error('harmony-studio: Draft is not active');
+        const graph = this.ctx.clientModules.graph();
+        if (!graph.entries.some(entry => entry.id === this.name)) {
+            throw new Error(`harmony-studio: Draft ${JSON.stringify(this.name)} left the client graph while applying its build`);
+        }
+        this.project = { ...this.project, state: 'preview-pending', graphRev: graph.rev };
+        return this.snapshot();
+    }
+    async close() {
+        if (this.project?.state === 'closed')
+            return;
+        if (this.createdEntry && this.entryId !== undefined) {
+            await this.ctx.loader.remove(this.entryId);
+            await this.reload();
+        }
+        this.project = { name: this.name, root: this.root, state: 'closed', graphRev: this.project?.graphRev ?? '' };
+    }
+    async waitForClientEntry() {
+        const modules = this.ctx.clientModules;
+        if (modules.graph().entries.some(entry => entry.id === this.name))
+            return;
+        await new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                stop();
+                reject(new Error(`harmony-studio: Draft ${JSON.stringify(this.name)} did not enter the client graph`));
+            }, CLIENT_ENTRY_TIMEOUT_MS);
+            const stop = modules.onGraphChanged(() => {
+                if (!modules.graph().entries.some(entry => entry.id === this.name))
+                    return;
+                clearTimeout(timeout);
+                stop();
+                resolve();
+            });
+        });
+    }
+    reload() {
+        return this.commands.run(process.execPath, [HARMONY_BIN_ENTRY, 'harmony', 'reload', this.name]);
+    }
+}

package/lib/host/preview-port.d.ts

@@ -0,0 +1,8 @@
+export declare class StudioPreviewPortPool {
+    private readonly ports?;
+    private readonly claimed;
+    constructor(range?: string);
+    claim(): number | undefined;
+    release(port: number | undefined): void;
+}
+export declare const studioPreviewPortPool: StudioPreviewPortPool;

package/lib/host/preview-port.js

@@ -0,0 +1,32 @@
+const PORT_RANGE = /^(\d+)-(\d+)$/;
+export class StudioPreviewPortPool {
+    ports;
+    claimed = new Set();
+    constructor(range) {
+        if (range === undefined || range === '')
+            return;
+        const match = PORT_RANGE.exec(range);
+        if (match === null)
+            throw new Error('DSH_STUDIO_PREVIEW_PORT_RANGE must use start-end syntax');
+        const start = Number(match[1]);
+        const end = Number(match[2]);
+        if (start < 1 || end > 65_535 || start > end) {
+            throw new Error('DSH_STUDIO_PREVIEW_PORT_RANGE must contain an ascending TCP port range');
+        }
+        this.ports = Array.from({ length: end - start + 1 }, (_, index) => start + index);
+    }
+    claim() {
+        if (this.ports === undefined)
+            return undefined;
+        const port = this.ports.find(candidate => !this.claimed.has(candidate));
+        if (port === undefined)
+            throw new Error('No free Studio Preview port remains in DSH_STUDIO_PREVIEW_PORT_RANGE');
+        this.claimed.add(port);
+        return port;
+    }
+    release(port) {
+        if (port !== undefined)
+            this.claimed.delete(port);
+    }
+}
+export const studioPreviewPortPool = new StudioPreviewPortPool(process.env.DSH_STUDIO_PREVIEW_PORT_RANGE);

package/lib/host/preview-worker.d.ts

@@ -1,11 +1,74 @@
 import type { Context } from '@deepseek-ai/cordis';
-import { type StudioHarmonyService } from '../contracts.js';
+import { TypertRemoteService, type InvocationDescriptor, type RemoteResult, type TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol';
+import { type StudioHarmonyProfile, type StudioHarmonyProfileUpdateResult, type StudioHarmonyService, type StudioPreviewInspection, type StudioProjectState, type StudioSourceCandidate, type StudioSourceLocation } from '../contracts.js';
 interface PreviewWorkerOptions {
     root: string;
-    controlToken: string;
+    packageDirs: string[];
     parentOrigin: string;
     bridgeCapability: string;
     bridge: Buffer;
 }
+export interface StudioPreviewHealth {
+    ready: boolean;
+    error?: string;
+}
+export interface StudioPreviewWorkerRemote {
+    health(signal?: AbortSignal): Promise<RemoteResult<StudioPreviewHealth>>;
+    state(signal?: AbortSignal): Promise<RemoteResult<StudioProjectState>>;
+    activate(graphRev: string, signal?: AbortSignal): Promise<RemoteResult<StudioProjectState>>;
+    applyBuild(operationId: string, signal?: AbortSignal): Promise<RemoteResult<StudioProjectState>>;
+    inspect(input: {
+        package?: string;
+        file?: string;
+    }, signal?: AbortSignal): Promise<RemoteResult<StudioPreviewInspection>>;
+    profile(signal?: AbortSignal): Promise<RemoteResult<StudioHarmonyProfile>>;
+    updateProfile(input: {
+        operationId: string;
+        order?: string[];
+        patchOrder?: string[];
+        disabled?: string[];
+    }, signal?: AbortSignal): Promise<RemoteResult<StudioHarmonyProfileUpdateResult>>;
+    resolveSource(source: StudioSourceLocation, signal?: AbortSignal): Promise<RemoteResult<StudioSourceCandidate>>;
+    readSource(packageName: string, file: string, signal?: AbortSignal): Promise<RemoteResult<string>>;
+    readPatchTarget(packageName: string, file: string, signal?: AbortSignal): Promise<RemoteResult<{
+        package: string;
+        file: string;
+        version: string;
+        source: string;
+    }>>;
+}
+export declare const STUDIO_PREVIEW_INVOCATIONS: readonly InvocationDescriptor[];
+export declare const STUDIO_PREVIEW_REMOTE: TypertRemoteContribution;
+export declare class StudioPreviewWorkerService extends TypertRemoteService {
+    private readonly harmony;
+    private readiness;
+    private readonly ready;
+    private readonly sources;
+    constructor(ctx: Context, harmony: StudioHarmonyService, options: Pick<PreviewWorkerOptions, 'root' | 'packageDirs'>);
+    health(signal: AbortSignal): Promise<StudioPreviewHealth>;
+    state(signal: AbortSignal): Promise<StudioProjectState>;
+    activate(graphRev: string, signal: AbortSignal): Promise<StudioProjectState>;
+    applyBuild(operationId: string, signal: AbortSignal): Promise<StudioProjectState>;
+    inspect(input: {
+        package?: string;
+        file?: string;
+    }, signal: AbortSignal): Promise<StudioPreviewInspection>;
+    profile(signal: AbortSignal): Promise<StudioHarmonyProfile>;
+    updateProfile(input: {
+        operationId: string;
+        order?: string[];
+        patchOrder?: string[];
+        disabled?: string[];
+    }, signal: AbortSignal): Promise<StudioHarmonyProfileUpdateResult>;
+    resolveSource(source: StudioSourceLocation, signal: AbortSignal): Promise<StudioSourceCandidate>;
+    readSource(packageName: string, file: string, signal: AbortSignal): Promise<string>;
+    readPatchTarget(packageName: string, file: string, signal: AbortSignal): Promise<{
+        package: string;
+        file: string;
+        version: string;
+        source: string;
+    }>;
+    close(): Promise<void>;
+}
 export declare function applyPreviewWorker(ctx: Context, harmony: StudioHarmonyService, options: PreviewWorkerOptions): void;
 export {};

package/lib/host/preview-worker.js

@@ -1,5 +1,194 @@
-import { STUDIO_PATH, STUDIO_PREVIEW_API_PATH, } from '../contracts.js';
+import { TypertRemoteService, } from '@deepseek-ai/dsh-typert-protocol';
+import { z } from 'zod';
+import { STUDIO_PATH, } from '../contracts.js';
+import { StudioPreviewDraft } from './preview-draft.js';
 import { StudioSourceResolver } from './source-resolution.js';
+const projectStateSchema = z.object({
+    name: z.string(),
+    root: z.string(),
+    state: z.enum(['active', 'preview-pending', 'closed']),
+    graphRev: z.string(),
+});
+const sourceLocationSchema = z.object({
+    file: z.string().min(1),
+    line: z.number().int().min(1).optional(),
+    column: z.number().int().min(1).optional(),
+});
+const sourceCandidateSchema = sourceLocationSchema.extend({
+    package: z.string().optional(),
+    kind: z.enum(['draft', 'dependency', 'generated', 'unknown']),
+    confidence: z.enum(['exact', 'candidate']),
+});
+const stringListSchema = z.array(z.string().min(1));
+const profileUpdateSchema = z.object({
+    operationId: z.string().min(1),
+    order: stringListSchema.optional(),
+    patchOrder: stringListSchema.optional(),
+    disabled: stringListSchema.optional(),
+});
+const inspectInputSchema = z.object({ package: z.string().optional(), file: z.string().optional() });
+const healthSchema = z.object({ ready: z.boolean(), error: z.string().optional() });
+const previewInspectionSchema = z.object({ harmony: z.unknown() });
+const patchTargetSchema = z.object({
+    package: z.string(),
+    file: z.string(),
+    version: z.string(),
+    source: z.string(),
+});
+function jsonTransport(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+const profileUpdateOperations = new Map();
+const applyBuildOperations = new Map();
+const PROFILE_UPDATE_OPERATION_LIMIT = 32;
+function codec(typeSymbol, schema) {
+    return { mode: 'strict', typeSymbol, schema };
+}
+function parameter(name, schema) {
+    return { name, wire: name, source: 'json', codec: codec(`dsh-webui-studio#${name}`, schema) };
+}
+function invocation(method, parameters, result) {
+    return {
+        id: `dsh-webui-studio#studioPreviewWorker/${method}`,
+        service: 'studioPreviewWorker',
+        namespace: 'studioPreviewWorker',
+        method,
+        invocation: { kind: 'direct' },
+        parameters,
+        cancellation: { parameter: 'signal' },
+        result: codec(`dsh-webui-studio#studioPreviewWorker/${method}:result`, result),
+    };
+}
+export const STUDIO_PREVIEW_INVOCATIONS = [
+    invocation('health', [], healthSchema),
+    invocation('state', [], projectStateSchema),
+    invocation('activate', [parameter('graphRev', z.string().min(1))], projectStateSchema),
+    invocation('applyBuild', [parameter('operationId', z.string().min(1))], projectStateSchema),
+    invocation('inspect', [parameter('input', inspectInputSchema)], previewInspectionSchema),
+    invocation('profile', [], z.unknown()),
+    invocation('updateProfile', [parameter('input', profileUpdateSchema)], z.unknown()),
+    invocation('resolveSource', [parameter('source', sourceLocationSchema)], sourceCandidateSchema),
+    invocation('readSource', [parameter('packageName', z.string().min(1)), parameter('file', z.string().min(1))], z.string()),
+    invocation('readPatchTarget', [parameter('packageName', z.string().min(1)), parameter('file', z.string().min(1))], patchTargetSchema),
+];
+export const STUDIO_PREVIEW_REMOTE = {
+    package: 'dsh-webui-studio/preview-worker',
+    descriptors: STUDIO_PREVIEW_INVOCATIONS,
+};
+const STUDIO_PREVIEW_LOCAL = {
+    package: 'dsh-webui-studio/preview-worker',
+    face: 'host',
+    schemas: [],
+    model: { services: [], events: [], objects: [] },
+    invocations: STUDIO_PREVIEW_INVOCATIONS,
+};
+export class StudioPreviewWorkerService extends TypertRemoteService {
+    harmony;
+    readiness = { state: 'starting' };
+    ready;
+    sources;
+    constructor(ctx, harmony, options) {
+        super(ctx, 'studioPreviewWorker');
+        this.harmony = harmony;
+        this.ready = Promise.resolve().then(() => new StudioPreviewDraft(ctx, harmony, options.root).open());
+        void this.ready.then(() => { this.readiness = { state: 'ready' }; }, error => { this.readiness = { state: 'failed', error }; });
+        this.sources = new StudioSourceResolver(options.root, harmony.profile().dir, options.packageDirs);
+    }
+    async health(signal) {
+        signal.throwIfAborted();
+        if (this.readiness.state === 'starting')
+            return { ready: false };
+        if (this.readiness.state === 'failed') {
+            return {
+                ready: false,
+                error: this.readiness.error instanceof Error
+                    ? this.readiness.error.message
+                    : String(this.readiness.error),
+            };
+        }
+        return { ready: true };
+    }
+    async state(signal) {
+        signal.throwIfAborted();
+        return (await this.ready).snapshot();
+    }
+    async activate(graphRev, signal) {
+        signal.throwIfAborted();
+        return (await this.ready).activate(graphRev);
+    }
+    async applyBuild(operationId, signal) {
+        signal.throwIfAborted();
+        const existing = applyBuildOperations.get(operationId);
+        if (existing !== undefined)
+            return existing;
+        const result = this.ready.then(opened => opened.applyBuild()).then(jsonTransport);
+        applyBuildOperations.set(operationId, result);
+        while (applyBuildOperations.size > PROFILE_UPDATE_OPERATION_LIMIT) {
+            const oldest = applyBuildOperations.keys().next().value;
+            if (oldest === undefined)
+                break;
+            applyBuildOperations.delete(oldest);
+        }
+        return result;
+    }
+    async inspect(input, signal) {
+        signal.throwIfAborted();
+        await this.ready;
+        return jsonTransport({
+            harmony: this.harmony.inspect(input),
+        });
+    }
+    async profile(signal) {
+        signal.throwIfAborted();
+        const opened = await this.ready;
+        return jsonTransport({ ...this.harmony.profile(), runtimePlugins: opened.runtimePlugins() });
+    }
+    async updateProfile(input, signal) {
+        signal.throwIfAborted();
+        await this.ready;
+        const { operationId, ...update } = input;
+        const serialized = JSON.stringify(update);
+        const existing = profileUpdateOperations.get(operationId);
+        if (existing !== undefined) {
+            if (existing.input !== serialized)
+                throw new Error('Profile update operation input changed');
+            return existing.result;
+        }
+        const result = this.harmony.updateProfile(update).then(async (result) => {
+            const opened = await this.ready;
+            return jsonTransport({
+                ...result,
+                profile: { ...result.profile, runtimePlugins: opened.runtimePlugins() },
+            });
+        });
+        profileUpdateOperations.set(operationId, { input: serialized, result });
+        while (profileUpdateOperations.size > PROFILE_UPDATE_OPERATION_LIMIT) {
+            const oldest = profileUpdateOperations.keys().next().value;
+            if (oldest === undefined)
+                break;
+            profileUpdateOperations.delete(oldest);
+        }
+        return result;
+    }
+    async resolveSource(source, signal) {
+        signal.throwIfAborted();
+        await this.ready;
+        return jsonTransport(await this.sources.resolve(source));
+    }
+    async readSource(packageName, file, signal) {
+        signal.throwIfAborted();
+        await this.ready;
+        return this.sources.readDependency(packageName, file);
+    }
+    async readPatchTarget(packageName, file, signal) {
+        signal.throwIfAborted();
+        await this.ready;
+        return jsonTransport(await this.sources.readDependencyTarget(packageName, file));
+    }
+    async close() {
+        await this.ready.then(opened => opened.close(), () => undefined);
+    }
+}
 function loopback(request) {
     const address = request.socket.remoteAddress;
     return address === '::1' || address === '127.0.0.1' || address?.startsWith('::ffff:127.') === true;
@@ -8,80 +197,10 @@ function json(response, status, body) {
     response.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
     response.end(JSON.stringify(body));
 }
-async function readJson(request) {
-    const chunks = [];
-    for await (const chunk of request)
-        chunks.push(Buffer.from(chunk));
-    if (Buffer.concat(chunks).byteLength > 1024 * 1024)
-        throw new Error('request body is too large');
-    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
-}
 export function applyPreviewWorker(ctx, harmony, options) {
     ctx.effect(() => {
-        let handle;
-        const ready = harmony.prepareDraft({ root: options.root }).then(value => { handle = value; return value; });
-        const sources = new StudioSourceResolver(options.root, harmony.profileDir);
-        const worker = {
-            kind: 'prefix',
-            path: STUDIO_PREVIEW_API_PATH,
-            async handler(request, response) {
-                if (!loopback(request) || request.headers.authorization !== `Bearer ${options.controlToken}`) {
-                    return json(response, 403, { ok: false, error: 'invalid Preview worker capability' });
-                }
-                if (request.method !== 'POST')
-                    return json(response, 405, { ok: false, error: 'method not allowed' });
-                try {
-                    const payload = await readJson(request);
-                    const method = new URL(request.url ?? '/', 'http://localhost').pathname.slice(`${STUDIO_PREVIEW_API_PATH}/`.length);
-                    if (method === 'health')
-                        return json(response, 200, { ok: true, value: { ready: true } });
-                    const draft = await ready;
-                    if (method === 'state')
-                        return json(response, 200, { ok: true, value: { project: draft.snapshot() } });
-                    if (method === 'activate') {
-                        if (typeof payload.graphRev !== 'string')
-                            throw new Error('graphRev is required');
-                        return json(response, 200, { ok: true, value: { project: await draft.activateAfterPreviewReady(payload.graphRev) } });
-                    }
-                    if (method === 'apply-build') {
-                        return json(response, 200, { ok: true, value: { project: await draft.applyBuild() } });
-                    }
-                    if (method === 'inspect') {
-                        const packageName = typeof payload.package === 'string' ? payload.package : undefined;
-                        const file = typeof payload.file === 'string' ? payload.file : undefined;
-                        return json(response, 200, {
-                            ok: true,
-                            value: {
-                                harmony: harmony.inspect({ ...(packageName === undefined ? {} : { package: packageName }), ...(file === undefined ? {} : { file }) }),
-                                dependencies: harmony.inspectDependencies(draft.snapshot().name),
-                            },
-                        });
-                    }
-                    if (method === 'resolve-source') {
-                        const source = payload.source;
-                        if (typeof source?.file !== 'string' || source.file === ''
-                            || (source.line !== undefined && (!Number.isInteger(source.line) || source.line < 1))
-                            || (source.column !== undefined && (!Number.isInteger(source.column) || source.column < 1))) {
-                            throw new Error('source location is invalid');
-                        }
-                        return json(response, 200, { ok: true, value: await sources.resolve(source) });
-                    }
-                    if (method === 'read-source') {
-                        if (typeof payload.package !== 'string' || typeof payload.file !== 'string') {
-                            throw new Error('dependency package and file are required');
-                        }
-                        return json(response, 200, {
-                            ok: true,
-                            value: await sources.readDependency(payload.package, payload.file),
-                        });
-                    }
-                    return json(response, 404, { ok: false, error: `unknown Preview worker method ${method}` });
-                }
-                catch (error) {
-                    return json(response, 400, { ok: false, error: error instanceof Error ? error.message : String(error) });
-                }
-            },
-        };
+        const worker = new StudioPreviewWorkerService(ctx, harmony, options);
+        const disposeContribution = ctx.typert.register(STUDIO_PREVIEW_LOCAL);
         const bridge = {
             kind: 'exact',
             path: `${STUDIO_PATH}/bridge.js`,
@@ -92,7 +211,15 @@ export function applyPreviewWorker(ctx, harmony, options) {
                 response.end(request.method === 'HEAD' ? undefined : options.bridge);
             },
         };
-        const dispose = [ctx.webServer.register(worker), ctx.webServer.register(bridge), ctx.webServer.tapIndex(html => {
+        const removedApi = {
+            kind: 'prefix',
+            path: '/dsh-harmony/studio-preview/api',
+            handler(_request, response) {
+                response.writeHead(404);
+                response.end('not found');
+            },
+        };
+        const dispose = [ctx.webServer.register(bridge), ctx.webServer.register(removedApi), ctx.webServer.tapIndex(html => {
                 const config = `<script>window.__DSH_STUDIO_PREVIEW__=${JSON.stringify({
                     parentOrigin: options.parentOrigin,
                     capability: options.bridgeCapability,
@@ -103,8 +230,8 @@ export function applyPreviewWorker(ctx, harmony, options) {
         return async () => {
             for (const stop of dispose.reverse())
                 stop();
-            await ready.catch(() => undefined);
-            await handle?.deactivate();
+            await disposeContribution();
+            await worker.close();
         };
     }, 'harmony-studio: Preview worker');
 }

package/lib/host/preview.d.ts

@@ -1,5 +1,6 @@
-import type { StudioDraftRecord, StudioPreviewInspection, StudioProjectState, StudioSourceCandidate, StudioSourceLocation } from '../contracts.js';
+import type { StudioDraftRecord, StudioHarmonyProfile, StudioHarmonyProfileUpdateResult, StudioPreviewInspection, StudioProjectState, StudioSourceCandidate, StudioSourceLocation } from '../contracts.js';
 import type { StudioCommandRunner } from './drafts.js';
+import { type StudioPreviewPortPool } from './preview-port.js';
 export interface StudioPreviewRuntime {
     state: 'stopped' | 'starting' | 'running' | 'failed';
     previewUrl?: string;
@@ -7,6 +8,7 @@ export interface StudioPreviewRuntime {
     error?: string;
     log: string;
 }
+export declare function dshPackageModules(harmonyBinEntry: string): string;
 export declare class StudioPreviewSupervisor {
     readonly draft: StudioDraftRecord;
     private readonly mainProfileDir;
@@ -14,17 +16,20 @@ export declare class StudioPreviewSupervisor {
     private readonly commands;
     private readonly harmonyBinEntry;
     private readonly stopTimeoutMs;
+    private readonly portPool;
     private child?;
-    private controlToken?;
+    private peerClient?;
     private runtime;
     private startAbort?;
     private startPromise?;
-    constructor(draft: StudioDraftRecord, mainProfileDir: string, parentOrigin: string, commands: StudioCommandRunner, harmonyBinEntry: string, stopTimeoutMs?: number);
+    private previewPort?;
+    constructor(draft: StudioDraftRecord, mainProfileDir: string, parentOrigin: string, commands: StudioCommandRunner, harmonyBinEntry: string, stopTimeoutMs?: number, portPool?: StudioPreviewPortPool);
     snapshot(): StudioPreviewRuntime;
     start(): Promise<StudioPreviewRuntime>;
     private startRuntime;
     stop(): Promise<StudioPreviewRuntime>;
     private terminateChild;
+    private releasePreviewPort;
     state(): Promise<StudioProjectState>;
     activate(graphRev: string): Promise<StudioProjectState>;
     applyBuild(): Promise<StudioProjectState>;
@@ -32,11 +37,27 @@ export declare class StudioPreviewSupervisor {
         package?: string;
         file?: string;
     }): Promise<StudioPreviewInspection>;
+    profile(): Promise<StudioHarmonyProfile>;
+    updateProfile(input: {
+        order?: string[];
+        patchOrder?: string[];
+        disabled?: string[];
+    }): Promise<StudioHarmonyProfileUpdateResult>;
     resolveSource(source: StudioSourceLocation): Promise<StudioSourceCandidate>;
     readDependencySource(packageName: string, file: string): Promise<string>;
+    readPatchTarget(packageName: string, file: string): Promise<{
+        package: string;
+        file: string;
+        version: string;
+        source: string;
+    }>;
     dispose(): Promise<void>;
-    private waitUntilRunning;
+    private waitForPreviewUrl;
     private waitForWorker;
-    private worker;
+    private remote;
+    private invoke;
+    private closePeer;
+    private isGenerationLoss;
+    private reconnectPeer;
     private delay;
 }