dsh-webui-studio 0.1.0 → 0.2.0

package/docs/harmony-api-requirements.md

@@ -1,24 +1,28 @@
 # Harmony API requirements
 
-WebUI Studio is a Harmony extension. It imports no Harmony source files and
-communicates with Harmony through the `harmony` Cordis service exposed by the
-public `dsh-harmony` package.
+WebUI Studio is an ordinary DSH plugin loaded after Harmony. It imports no
+Harmony source files and communicates with Harmony through the public
+`dsh-harmony` package.
 
 The Studio production path requires Harmony to provide:
 
-- extension discovery for profile dependencies declaring
-  `dsh.harmony.extension`;
-- `HarmonyService.binEntry` and `HarmonyService.profileDir`;
-- `HarmonyService.inspect()` and `inspectDependencies()`;
-- `HarmonyService.prepareDraft()` with staged, active, preview-pending, and
-  closed Draft transitions;
+- `HarmonyService.profile()` and transactional `updateProfile()` for the stable
+  Host's plugin order and provider enablement;
+- `HarmonyService.inspect()` for Patch state, targets, match counts, and errors;
+- the public `dsh-harmony/bin` export and `harmony reload` command for
+  transactionally reloading a built Draft and its Patch declarations; Studio
+  owns the Preview lifecycle transitions;
 - source Patch declaration metadata and optional render trace metadata used by
   Preview inspection.
 
-These APIs are public in `dsh-harmony@0.1.3`, which is the minimum compatible
-registry release for Studio Host integration.
+Profile paths come from `HarmonyService.profile().dir`. Studio resolves the CLI
+entry through the package export rather than through the Cordis service.
+Studio and Harmony releases must keep this public contract aligned.
 
-`dsh-harmony-react@0.1.0` exposes the generic `./studio` React element and
+`dsh-harmony-react@0.3.0` exposes the generic `./studio` React element and
 variable registration API used by the browser and Preview bridge. Studio uses
 the package published on the npm registry and resolves it exclusively through
-the `dsh-harmony-react/studio` package export.
+the `dsh-harmony-react/studio` package export. Source persistence additionally
+requires the `StudioVariableDefinition.defaultSource` anchors introduced by the
+corresponding React package release; bindings without those anchors remain
+Preview-only.

package/docs/remote-development.md

@@ -0,0 +1,80 @@
+# Remote Docker development
+
+Remote development runs one complete Studio Host per Agent on a Docker machine,
+while the browser and source checkout remain local. Each Compose project owns
+its own `DSH_HOME`, npm cache, pnpm store, Studio port, and fixed Preview port
+range. SSH forwards only those loopback ports, so Studio and Draft Preview Hosts
+remain unavailable directly from the LAN.
+
+## Remote prerequisite
+
+The remote host must provide a running Docker Engine and a `docker` CLI that is
+available to non-interactive SSH sessions. Node.js and DSH are installed in the
+image and are not required on the remote macOS host.
+
+Installing Docker Desktop, OrbStack, or another system runtime changes the
+remote machine and is intentionally outside this repository's setup script.
+After installation, verify the daemon from the local machine:
+
+```sh
+npm run remote -- check
+```
+
+The default SSH host is `macmini`. Override it with
+`DSH_STUDIO_REMOTE=user@host` when needed.
+
+## Start isolated Agents
+
+Choose a unique Studio port and non-overlapping Preview range for each Agent:
+
+```sh
+npm run remote -- up agent-a 13081 13100-13115
+npm run remote -- up agent-b 14081 14100-14115
+```
+
+`up` sends the current checkout as the Docker build context, starts the remote
+Compose project, and opens an SSH control connection that forwards the Studio
+and Preview ports. Open the URL printed by the command. Re-run `up` after source
+changes to rebuild the image.
+
+Other lifecycle commands are:
+
+```sh
+npm run remote -- logs agent-a
+npm run remote -- status agent-a
+npm run remote -- tunnel agent-a 13081 13100-13115
+npm run remote -- down agent-a
+```
+
+`down` removes the Agent's container but preserves its named volumes and Draft
+state. Remove those volumes explicitly only when their data is no longer needed.
+
+Docker Desktop must support host networking because DSH intentionally listens
+on `127.0.0.1`. The fixed Preview range is enabled only in the container through
+`DSH_STUDIO_PREVIEW_PORT_RANGE`; ordinary local Studio runs continue to pass
+`--port 0` and use an operating-system-assigned port.
+
+## 中文说明
+
+远程开发模式会在 Docker 主机上为每个 Agent 运行一套完整 Studio Host，本机只保留
+源码工作区、浏览器和 SSH 隧道。每个 Compose project 都有独立的 `DSH_HOME`、npm
+缓存、pnpm store、Studio 端口和 Preview 端口段。DSH 仍只监听回环地址，局域网不能
+直接访问这些服务。
+
+远端只需安装并启动 Docker Engine，Node.js 和 DSH 均由镜像提供。仓库脚本不会安装
+Docker Desktop、OrbStack 等系统软件。安装 Docker 后，可先运行：
+
+```sh
+npm run remote -- check
+```
+
+随后为每个 Agent 分配互不重叠的端口并启动：
+
+```sh
+npm run remote -- up agent-a 13081 13100-13115
+npm run remote -- up agent-b 14081 14100-14115
+```
+
+源码改变后重新执行 `up` 即可在远端重建。`down` 只移除容器，保留该 Agent 的命名
+卷和 Draft 数据。远端 Docker Desktop 需要支持 host networking，因为 DSH 会继续
+绑定 `127.0.0.1`。

package/lib/bridge/element-style-selector.d.ts

@@ -0,0 +1 @@
+export declare function compileElementStyleSelector(selector: string, scope: string): string;

package/lib/bridge/element-style-selector.js

@@ -0,0 +1,53 @@
+function escapesRoot(selector) {
+    const suffix = selector.slice(1);
+    let bracketDepth = 0;
+    let parenthesisDepth = 0;
+    let quote = '';
+    for (let index = 0; index < suffix.length; index += 1) {
+        const character = suffix[index];
+        if (quote !== '') {
+            if (character === quote && suffix[index - 1] !== '\\')
+                quote = '';
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            continue;
+        }
+        if (character === '[') {
+            bracketDepth += 1;
+            continue;
+        }
+        if (character === ']') {
+            bracketDepth -= 1;
+            continue;
+        }
+        if (character === '(') {
+            parenthesisDepth += 1;
+            continue;
+        }
+        if (character === ')') {
+            parenthesisDepth -= 1;
+            continue;
+        }
+        if (bracketDepth !== 0 || parenthesisDepth !== 0)
+            continue;
+        if (character === '+' || character === '~')
+            return true;
+        if (character === '>')
+            return false;
+        if (/\s/.test(character)) {
+            while (/\s/.test(suffix[index + 1] ?? ''))
+                index += 1;
+            return suffix[index + 1] === '+' || suffix[index + 1] === '~';
+        }
+    }
+    return false;
+}
+export function compileElementStyleSelector(selector, scope) {
+    if (!selector.startsWith('&') || selector.indexOf('&', 1) !== -1 || /[{},;]/.test(selector)
+        || escapesRoot(selector)) {
+        throw new Error('Element CSS selectors must contain one leading & and stay within its subtree');
+    }
+    return selector.replace('&', scope);
+}

package/lib/contracts.d.ts

@@ -1,37 +1,22 @@
+import type { HarmonyInspection, HarmonyProfileView, HarmonyRuntimeProfileUpdateResult, HarmonyService } from 'dsh-harmony';
+import type { StudioElementDefinition, StudioVariableNode, StudioVariableValue } from 'dsh-harmony-react/studio';
 export declare const STUDIO_PATH = "/studio";
-export declare const STUDIO_API_PATH = "/studio/api";
 export declare const STUDIO_PREVIEW_FRAGMENT = "dsh-studio-preview";
-export declare const STUDIO_PREVIEW_API_PATH = "/dsh-harmony/studio-preview/api";
-export interface StudioClientRequest {
-    type: 'client-request';
-    rpcId: string;
-    method: string;
-    payload: unknown;
-}
-export interface StudioServerResponse<T = unknown> {
-    type: 'server-response';
-    rpcId: string;
-    result: {
-        ok: true;
-        value: T;
-    } | {
-        ok: false;
-        error: {
-            code: string;
-            message: string;
-            details?: unknown;
-        };
-    };
-}
 export interface StudioServerRequest<T = unknown> {
     type: 'server-request';
     rpcId: string;
     method: 'events.mux' | 'events.host';
     payload: T;
 }
-export interface StudioCreateAgentResult {
+export interface StudioAgentBinding {
     sessionId: string;
     agentPreset?: string;
+    source: 'created' | 'existing';
+}
+export interface StudioCurrentInstanceView {
+    previewUrl: string;
+    bridgeCapability: string;
+    agent?: StudioAgentBinding;
 }
 export interface StudioReactSnapshot {
     component?: string;
@@ -45,7 +30,7 @@ export interface StudioReactSnapshot {
 export interface StudioPatchTrace {
     key: string;
     owner: string;
-    effect: 'replace-element' | 'wrap-element' | 'insert-before' | 'insert-after' | 'transform-props';
+    effect: 'replace-element' | 'wrap-element' | 'insert-before' | 'insert-after' | 'transform-props' | 'decorate-component' | 'replace-component';
     declaration: string;
     target: {
         package: string;
@@ -86,6 +71,45 @@ export interface StudioSurfaceBoundary {
     surfaceId: string;
     path: string[];
 }
+export interface StudioElementStyleTarget {
+    owner: string;
+    elementId: string;
+    boundary: StudioSurfaceBoundary;
+    selector: string;
+    property: string;
+    value?: string;
+}
+export interface StudioElementStyleDeclaration {
+    property: string;
+    value: string;
+}
+export interface StudioElementStyleRule {
+    selector: string;
+    declarations: StudioElementStyleDeclaration[];
+}
+export interface StudioElementStyleSource {
+    elementId: string;
+    rules: StudioElementStyleRule[];
+}
+export interface StudioElementSelectorTarget {
+    owner: string;
+    elementId: string;
+    boundary: StudioSurfaceBoundary;
+}
+export interface StudioElementSnapshot {
+    owner: string;
+    element: StudioElementDefinition;
+    values: Readonly<Record<string, StudioVariableValue>>;
+}
+export interface StudioVariablesSnapshot {
+    owner: string;
+    variables: readonly StudioVariableNode[];
+    values: Readonly<Record<string, StudioVariableValue>>;
+}
+export interface StudioRegistrySnapshot {
+    elements: readonly StudioElementSnapshot[];
+    variables: readonly StudioVariablesSnapshot[];
+}
 export interface StudioPreviewStatus {
     connected: boolean;
     graphRev?: string;
@@ -93,6 +117,24 @@ export interface StudioPreviewStatus {
     selection?: StudioDomSelection;
     registry?: StudioRegistrySnapshot;
 }
+export interface StudioAgentContext {
+    target: 'draft' | 'current-instance';
+    readOnly: boolean;
+    selection: StudioDomSelection | null;
+    project: StudioProjectState;
+    preview: StudioPreviewStatus;
+    projectFiles: StudioProjectFile[];
+    profile: HarmonyProfileView;
+    harmony: StudioHarmonyInspection | null;
+    targetRefs: Array<{
+        package: string;
+        file: string;
+    }>;
+    targetRefsTruncated: boolean;
+    readiness: {
+        findings: StudioReadinessFinding[];
+    };
+}
 export interface StudioPreviewUpdate {
     connected: boolean;
     graphRev?: string;
@@ -100,40 +142,22 @@ export interface StudioPreviewUpdate {
     selection?: StudioDomSelection | null;
     registry?: StudioRegistrySnapshot | null;
 }
-export type { StudioRegistrySnapshot };
 export interface StudioProjectFile {
     path: string;
     size: number;
 }
-export interface StudioHarmonyInspection {
-    patches: Array<{
-        key: string;
-        owner: string;
-        target: {
-            package: string;
-            files: string[];
-            version?: string;
-        };
-        kind: 'source' | 'semantic';
-        state: 'pending' | 'bound' | 'disabled' | 'failed';
-        loaded: boolean;
-        declaration: string;
-        file?: string;
-        error?: string;
-    }>;
-    targets: Array<{
-        package: string;
-        file: string;
-        original: string;
-        final: string;
-        steps: Array<{
-            key: string;
-            owner: string;
-            matches: number;
-            source: string;
-        }>;
-    }>;
+export type StudioHarmonyInspection = HarmonyInspection;
+export interface StudioRuntimePluginEntry {
+    entryId: string;
+    moduleName: string;
+    enabled: boolean;
 }
+export type StudioHarmonyProfile = HarmonyProfileView & {
+    runtimePlugins: StudioRuntimePluginEntry[];
+};
+export type StudioHarmonyProfileUpdateResult = Omit<HarmonyRuntimeProfileUpdateResult, 'profile'> & {
+    profile: StudioHarmonyProfile;
+};
 export type StudioReadinessLevel = 'error' | 'warning' | 'info';
 export interface StudioReadinessFinding {
     level: StudioReadinessLevel;
@@ -157,7 +181,7 @@ export interface StudioReadinessReport {
 export interface StudioProjectState {
     name: string;
     root: string;
-    state: 'staged' | 'active' | 'preview-pending' | 'closed';
+    state: 'active' | 'preview-pending' | 'closed';
     graphRev: string;
 }
 export type StudioDraftProfileMode = 'main-home' | 'custom';
@@ -180,6 +204,7 @@ export interface StudioDraftRecord {
     root: string;
     runtimeHome: string;
     profileMode: StudioDraftProfileMode;
+    profileDirectory?: string;
     createdAt: string;
 }
 export interface StudioDraftView extends StudioDraftRecord {
@@ -191,11 +216,12 @@ export interface StudioDraftView extends StudioDraftRecord {
         log: string;
     };
     project?: StudioProjectState;
-    agent?: StudioCreateAgentResult;
+    agent?: StudioAgentBinding;
 }
 export interface StudioCreateDraftInput {
     source: StudioDraftSource;
     profileMode: StudioDraftProfileMode;
+    profileDirectory?: string;
     destinationDirectory?: string;
 }
 export interface StudioWorkspaceState {
@@ -212,35 +238,78 @@ export interface StudioBuildResult {
     project: StudioProjectState;
     build: StudioBuildOutput;
 }
-export interface StudioHarmonyService {
-    readonly binEntry: string;
-    readonly profileDir: string;
-    inspect(input?: {
-        package?: string;
-        file?: string;
-    }): StudioHarmonyInspection;
-    inspectDependencies(owner: string): StudioPatchDependency[];
-    prepareDraft(input: {
-        root: string;
-    }): Promise<StudioPreviewDraftHandle>;
-}
-export interface StudioPreviewDraftHandle {
-    snapshot(): StudioProjectState;
-    activateAfterPreviewReady(graphRev: string): Promise<StudioProjectState>;
-    applyBuild(): Promise<StudioProjectState>;
-    deactivate(): Promise<void>;
+export interface StudioAutomaticPatchTarget {
+    package: string;
+    file: string;
 }
-export interface StudioPreviewInspection {
-    harmony: StudioHarmonyInspection;
-    dependencies: StudioPatchDependency[];
+export interface StudioAutomaticCssVariable {
+    id: string;
+    label: string;
+    property: string;
+    control: 'color' | 'length' | 'number' | 'enum' | 'string';
+    value: string | number;
+    options?: string[];
+    constraints?: {
+        min?: number;
+        max?: number;
+        step?: number;
+    };
 }
-export interface StudioPatchDependency {
-    patch: string;
-    target: {
-        package: string;
+export type StudioAutomaticPatchRequest = {
+    kind: 'replace-string';
+    targets: StudioAutomaticPatchTarget[];
+    text: string;
+    replacement: string;
+    clientFile: string;
+    boundary: StudioSurfaceBoundary;
+    targetSelector?: string;
+    selector: string;
+    elementId: string;
+    elementLabel: string;
+    elementSourceFile?: string;
+} | {
+    kind: 'css-style';
+    targets: StudioAutomaticPatchTarget[];
+    component: string;
+    clientFile: string;
+    boundary: StudioSurfaceBoundary;
+    targetSelector?: string;
+    selector: string;
+    elementId: string;
+    elementLabel: string;
+    variables: StudioAutomaticCssVariable[];
+};
+export interface StudioAutomaticPatchMatch {
+    line: number;
+    column: number;
+    excerpt: string;
+    applicable: boolean;
+    reason?: string;
+}
+export interface StudioAutomaticPatchTargetAnalysis extends StudioAutomaticPatchTarget {
+    version: string;
+    matches: StudioAutomaticPatchMatch[];
+}
+export interface StudioAutomaticPatchPlan {
+    request: StudioAutomaticPatchRequest;
+    targets: StudioAutomaticPatchTargetAnalysis[];
+    canApply: boolean;
+    provider: {
+        file: string;
+        source: string;
+        patchIds: string[];
+    };
+    client?: {
         file: string;
+        source: string;
+        export: string;
+        entryFile: string;
     };
-    providerCandidates: string[];
-    reason: string;
 }
-import type { StudioRegistrySnapshot } from 'dsh-harmony-react/studio';
+export interface StudioAutomaticPatchWriteResult extends StudioAutomaticPatchPlan {
+    files: string[];
+}
+export type StudioHarmonyService = HarmonyService;
+export interface StudioPreviewInspection {
+    harmony: StudioHarmonyInspection;
+}

package/lib/contracts.js

@@ -1,4 +1,2 @@
 export const STUDIO_PATH = '/studio';
-export const STUDIO_API_PATH = `${STUDIO_PATH}/api`;
 export const STUDIO_PREVIEW_FRAGMENT = 'dsh-studio-preview';
-export const STUDIO_PREVIEW_API_PATH = '/dsh-harmony/studio-preview/api';

package/lib/host/agent.d.ts

@@ -1,31 +1,33 @@
 import type { AgentRegistry } from '@deepseek-ai/dsh-agent';
-import type { StudioBuildResult, StudioDomSelection, StudioHarmonyInspection, StudioPreviewStatus, StudioProjectState } from '../contracts.js';
+import type { HarmonyProfileView } from 'dsh-harmony';
+import type { StudioAgentBinding, StudioAgentContext, StudioBuildResult, StudioDomSelection, StudioHarmonyInspection, StudioPreviewStatus, StudioProjectState } from '../contracts.js';
 export interface StudioAgentWorkspace {
+    readonly kind: 'draft' | 'current-instance';
     project(): StudioProjectState;
     selection(): StudioDomSelection | undefined;
+    context(): Promise<StudioAgentContext>;
     previewStatus(): StudioPreviewStatus;
+    harmonyProfile(): Promise<HarmonyProfileView>;
     inspectHarmony(input: {
         package?: string;
         file?: string;
     }): Promise<StudioHarmonyInspection>;
     readDependencySource(packageName: string, file: string): Promise<string>;
-    readFile(path: string): Promise<string>;
-    applyPatch(path: string, before: string, after: string): Promise<'created' | 'updated'>;
-    build(signal: AbortSignal): Promise<StudioBuildResult>;
+    readFile?(path: string): Promise<string>;
+    applyPatch?(path: string, before: string, after: string): Promise<'created' | 'updated'>;
+    build?(signal: AbortSignal): Promise<StudioBuildResult>;
 }
 export declare class StudioAgentController {
     private readonly agents;
     private readonly workspace;
     private handle?;
+    private removeStudioMode?;
     private active?;
+    private activating;
     constructor(agents: AgentRegistry, workspace: StudioAgentWorkspace);
-    snapshot(): {
-        sessionId: string;
-        agentPreset?: string;
-    } | undefined;
-    create(agentPreset?: string): Promise<{
-        sessionId: string;
-        agentPreset?: string;
-    }>;
-    dispose(): Promise<void>;
+    snapshot(): StudioAgentBinding | undefined;
+    create(agentPreset?: string): Promise<StudioAgentBinding>;
+    attach(sessionId: string): Promise<StudioAgentBinding>;
+    leave(): Promise<void>;
+    private beginActivation;
 }