Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions packages/webui/docs/client/composer.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,18 @@ text preserves the target draft. Synchronous subscribers can edit the committed
later transfer write replacing their changes. Conflicts publish nothing and keep the retained source;
the notice shows a transfer error beside its action so the user can select another destination and retry.

## Workspace folder selection

For a locally launched Windows WebUI with a native directory-picker grant, opening
`选择新项目` offers `选择此电脑上的文件夹` and `添加文件夹`. The add action opens the
native Windows directory chooser; confirming a folder changes the next session's work
directory. Cancelling the system chooser, dismissing the WebUI dialog or failing to
open the chooser does not change the current workspace.

Remote browsers and launches without the local grant use the existing server
directory browser instead. Its paths refer to the machine running WebUI, not
to the browser's device. The native entry also offers this fallback explicitly.

## Where the pieces live

- The surface is `client/features/composer/ui/WebuiComposer.tsx`, with the editor staging, menus,
Expand Down
5 changes: 5 additions & 0 deletions packages/webui/src/client/bindings/browser-capabilities.tsx
Original file line number Diff line number Diff line change
@@ -1,10 +1,15 @@
import { createContext, useContext, type ReactNode } from "react";
import { EMPTY_WEBUI_BROWSER_DOM, type WebuiBrowserDom } from "../platform/browser-dom.js";
import type { NativeWorkspaceDirectoryResult } from "../platform/native-directory-picker.js";
import { createWebuiBrowserStorage, type WebuiBrowserStorage } from "../platform/storage.js";

export interface WebuiBrowserCapabilities {
readonly dom: WebuiBrowserDom;
readonly storage: WebuiBrowserStorage;
readonly nativeDirectoryPicker?: {
readonly available: () => boolean;
readonly choose: (signal: AbortSignal) => Promise<NativeWorkspaceDirectoryResult>;
};
/**
* The runtime's data directory, when the host served the page with one.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,12 @@
// a layer of its own, so the coordinator dismisses it and it keeps no listener.
// The menu's open state stays a prop because the shell owns it.

import { useState } from "react";
import { useEffect, useRef, useState } from "react";

import { WebuiDropdown } from "../../../ui/Dropdown.js";
import { WebuiButton } from "../../../ui/button.js";
import { WebuiDialog } from "../../../ui/dialog.js";
import { useWebuiToastError } from "../../../ui/toast.js";
import { useWebuiBrowserCapabilities } from "../../../bindings/browser-capabilities.js";
import { workspaceProjectName } from "../../../features/workspace/projection/workspace-name.public.js";
import { WebuiWorkspaceDirectoryBrowser } from "../../../features/workspace/ui/WebuiWorkspaceDirectoryBrowser.public.js";
Expand All @@ -44,8 +45,63 @@ export function WebuiComposerProjectRow({
onMenuOpenChange,
onSelectProject,
}: WebuiComposerProjectRowProps) {
const { dom, nativeDirectoryPicker } = useWebuiBrowserCapabilities();
const [browserOpen, setBrowserOpen] = useState(false);
const { dom } = useWebuiBrowserCapabilities();
const [nativeMode, setNativeMode] = useState(false);
const [nativePending, setNativePending] = useState(false);
const [nativeError, setNativeError] = useState("");
useWebuiToastError(nativeError);
const request = useRef<AbortController | null>(null);
const nativeAddButton = useRef<HTMLButtonElement>(null);
useEffect(() => () => {
request.current?.abort();
request.current = null;
}, []);

function closeBrowser() {
request.current?.abort();
request.current = null;
setNativePending(false);
setNativeError("");
setBrowserOpen(false);
}

function showServerBrowser() {
request.current?.abort();
request.current = null;
setNativePending(false);
setNativeError("");
setNativeMode(false);
}

async function addFolder() {
if (!nativeDirectoryPicker || request.current) return;
const current = new AbortController();
request.current = current;
setNativePending(true);
setNativeError("");
try {
const result = await nativeDirectoryPicker.choose(current.signal);
if (request.current !== current) return;
if (result.kind === "selected") {
closeBrowser();
onSelectProject(result.directory);
} else if (result.kind === "unavailable") {
showServerBrowser();
}
} catch (error) {
if (request.current === current) {
setNativeError(error instanceof Error && !(error instanceof TypeError)
? error.message
: "无法打开系统目录选择,请重试或选择服务端目录。");
}
} finally {
if (request.current === current) {
request.current = null;
setNativePending(false);
}
}
}

return (
<div className="webui-workspace-bar" data-webui-workspace-toolbar="true">
Expand Down Expand Up @@ -125,6 +181,7 @@ export function WebuiComposerProjectRow({
className="webui-workspace-option"
onClick={() => {
onMenuOpenChange(false);
setNativeMode(nativeDirectoryPicker?.available() ?? false);
setBrowserOpen(true);
}}
>
Expand All @@ -150,25 +207,41 @@ export function WebuiComposerProjectRow({
<WebuiDialog
id="composer-directory-browser"
open={browserOpen}
title="选择项目目录"
description="选择要用于新会话的工作目录"
title={nativeMode ? "选择新项目" : "选择项目目录"}
description={nativeMode ? "选择此电脑上的文件夹" : "选择运行 WebUI 的主机上用于新会话的工作目录"}
width="standard"
portalTarget={dom.portalTarget()}
onClose={() => setBrowserOpen(false)}
initialFocusRef={nativeMode ? nativeAddButton : undefined}
onClose={closeBrowser}
dismissOnEscape
dismissOnBackdrop
testId="webui-workspace-browser-dialog"
dataAttributes={{ "data-webui-workspace-browser-dialog": "true" }}
bodyClassName="webui-workspace-browser-dialog-body"
>
<WebuiWorkspaceDirectoryBrowser
initialDir={projectDir}
onSelect={(dir) => {
setBrowserOpen(false);
onSelectProject(dir);
}}
onCancel={() => setBrowserOpen(false)}
/>
{nativeMode ? (
<div className="flex flex-col gap-3 p-4" aria-busy={nativePending}>
<div className="flex flex-wrap items-center gap-2">
<WebuiButton ref={nativeAddButton} type="button" variant="primary" loading={nativePending}
loadingLabel="正在等待系统选择窗口…" onClick={() => void addFolder()}>
{nativePending ? "正在等待系统选择窗口…" : "+ 添加文件夹"}
</WebuiButton>
<WebuiButton type="button" variant="plain" disabled={nativePending}
onClick={showServerBrowser}>
浏览服务端目录
</WebuiButton>
</div>
</div>
) : (
<WebuiWorkspaceDirectoryBrowser
initialDir={projectDir}
onSelect={(dir) => {
closeBrowser();
onSelectProject(dir);
}}
onCancel={closeBrowser}
/>
)}
</WebuiDialog>
</div>
</div>
Expand Down
6 changes: 6 additions & 0 deletions packages/webui/src/client/main.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ import { ArchonPage } from "./shell/ArchonPage.js";
import { WebuiErrorBoundary } from "./shell/WebuiErrorBoundary.js";
import { WebuiStartupFallback } from "./shell/StartupFallback.js";
import { WebuiBrowserCapabilitiesProvider } from "./bindings/browser-capabilities.js";
import { canPickNativeWorkspaceDirectory, captureNativeDirectoryLaunchGrant, pickNativeWorkspaceDirectory } from "./platform/native-directory-picker.js";
import { createWebuiBrowserDom } from "./platform/browser-dom.js";
import { MiniAppStandalone } from "./features/miniapp/ui/MiniAppStandalone.public.js";
import { WebuiMiniAppWorkflowsProvider } from "./features/miniapp/bindings/use-miniapp-workflows.js";
Expand Down Expand Up @@ -137,6 +138,7 @@ function installWebuiStallDiagnostics(): void {
}, 1_000);
}

captureNativeDirectoryLaunchGrant();
installWebuiStallDiagnostics();

const rootElement = document.getElementById("webui-root");
Expand Down Expand Up @@ -324,6 +326,10 @@ const root: Root = createRoot(rootElement);
const browserCapabilities = {
dom: createWebuiBrowserDom(globalThis.document, globalThis.window),
storage: createWebuiBrowserStorage(getWebuiBrowserStorage()),
nativeDirectoryPicker: {
available: canPickNativeWorkspaceDirectory,
choose: pickNativeWorkspaceDirectory,
},
// The runtime's data directory is a fact about this host: the composition
// root is the one place that may read the injected config, and the surfaces
// that need it read it from the capabilities.
Expand Down
46 changes: 46 additions & 0 deletions packages/webui/src/client/platform/native-directory-picker.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
// Ephemeral desktop grant: only the local launcher gives it to its auto-opened
// page. Never persist it, expose it in runtime config, or send it cross-origin.
import { readWebuiSessionTransferTarget } from "./session-transfer-target.js";

export type NativeWorkspaceDirectoryResult =
| { readonly kind: "selected"; readonly directory: string }
| { readonly kind: "cancelled" }
| { readonly kind: "unavailable" };
let launch: { readonly origin: string; readonly grant: string } | undefined;

export function captureNativeDirectoryLaunchGrant(): void {
launch = undefined;
const url = new URL(globalThis.location.href);
const fragment = new URLSearchParams(url.hash.slice(1));
const grant = fragment.get("nativeDirectoryGrant");
if (grant === null) return;
fragment.delete("nativeDirectoryGrant");
url.hash = fragment.toString();
// Remove even an invalid grant before any app routing or other interactions.
globalThis.history.replaceState(globalThis.history.state, "", url.href);
if (url.protocol === "http:" && (url.hostname === "127.0.0.1" || url.hostname === "[::1]") &&
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/iu.test(grant)) {
launch = { origin: url.origin, grant };
}
}
export function canPickNativeWorkspaceDirectory(): boolean {
const target = readWebuiSessionTransferTarget();
return Boolean(launch && target?.origin === launch.origin && target.token);
}
export async function pickNativeWorkspaceDirectory(signal: AbortSignal): Promise<NativeWorkspaceDirectoryResult> {
const target = readWebuiSessionTransferTarget();
if (!launch || !target?.token || target.origin !== launch.origin) return { kind: "unavailable" };
const response = await globalThis.fetch(`${launch.origin}/native-directory-picker`, {
method: "POST", credentials: "same-origin", signal,
headers: { "X-Webui-Native-Grant": launch.grant, "X-Webui-Token": target.token },
});
if ([401, 403, 404].includes(response.status)) { launch = undefined; return { kind: "unavailable" }; }
if (!response.ok) throw new Error(response.status === 409 ? "已有系统目录选择窗口,请先完成或取消。" : "系统目录选择失败,请重试或选择服务端目录。");
const result: unknown = await response.json();
if (result && typeof result === "object" && "kind" in result) {
if (result.kind === "cancelled") return { kind: "cancelled" };
if (result.kind === "selected" && "directory" in result && typeof result.directory === "string" && result.directory.length > 0)
return { kind: "selected", directory: result.directory };
}
throw new Error("系统目录选择返回了无效结果。");
}
107 changes: 107 additions & 0 deletions packages/webui/src/server/http/native-directory.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
// Desktop capability supplied only by an interactive local launcher. General
// WebUI credentials alone never authorize opening native desktop UI.
import type { IncomingMessage, ServerResponse } from "node:http";
import { timingSafeEqual } from "node:crypto";
import { credentialPresented, type WebuiCredential } from "../credentials.js";
import { stat } from "node:fs/promises";
import { isAbsolute } from "node:path";
import { rejectHttp } from "./responses.js";

export interface WebuiNativeDirectoryPicker {
readonly grant: string;
/** Abort must close the owned dialog and settle after its process exits. */
choose(signal: AbortSignal): Promise<{ readonly kind: "selected"; readonly directory: string } | { readonly kind: "cancelled" }>;
dispose(): Promise<void>;
}
interface Admission {
readonly host: string;
readonly port?: number;
readonly fullAccess?: boolean;
readonly credential: WebuiCredential;
}
const loopback = (value: string | undefined) => value === "127.0.0.1" || value === "::1" || value === "::ffff:127.0.0.1";
function equalSecret(value: string | string[] | undefined, expected: string): boolean {
if (typeof value !== "string" || !expected) return false;
const a = Buffer.from(value); const b = Buffer.from(expected);
return a.length === b.length && timingSafeEqual(a, b);
}
/** Same absolute/existing-directory semantics as the operation validator,
* but never block the HTTP event loop on a disconnected Windows share. The OS
* stat itself is not cancellable; its late result is ignored after the bound. */
export async function validateNativeDirectory(
directory: string,
timeoutMs = 3_000,
inspect: (path: string) => Promise<{ isDirectory(): boolean }> = stat,
): Promise<boolean> {
if (typeof directory !== "string" || !isAbsolute(directory)) return false;
let timer: ReturnType<typeof setTimeout> | undefined;
try {
return await Promise.race([
Promise.resolve().then(() => inspect(directory)).then(value => value.isDirectory(), () => false),
new Promise<false>(resolve => { timer = setTimeout(() => resolve(false), timeoutMs); }),
]);
} finally { clearTimeout(timer); }
}
export function createNativeDirectoryRoute(picker: WebuiNativeDirectoryPicker, timeoutMs = 120_000) {
let active: { controller: AbortController; settled: Promise<unknown> } | undefined;
let closed = false;
return {
async handle(request: IncomingMessage, response: ServerResponse, context: Admission): Promise<void> {
response.setHeader("Cache-Control", "no-store");
const authority = context.host === "::1" ? `[::1]:${context.port}` : `${context.host}:${context.port}`;
if (closed || context.fullAccess || !loopback(context.host) || !loopback(request.socket.remoteAddress) ||
!context.port || request.headers.host !== authority || request.headers.origin !== `http://${authority}` ||
request.headers["sec-fetch-site"] !== "same-origin" ||
Object.keys(request.headers).some((key) => key === "forwarded" || key.startsWith("x-forwarded-")) ||
!equalSecret(request.headers["x-webui-native-grant"], picker.grant)) {
rejectHttp(response, 403, "Native directory selection unavailable"); return;
}
if (!credentialPresented(context.credential,
typeof request.headers["x-webui-token"] === "string" ? request.headers["x-webui-token"] : undefined,
request.headers.cookie)) {
rejectHttp(response, 401, "Unauthorized"); return;
}
// This command takes no client path, command or options. Empty POST only.
if ((request.headers["content-length"] !== undefined && request.headers["content-length"] !== "0") ||
request.headers["transfer-encoding"] !== undefined) {
rejectHttp(response, 400, "Native directory selection accepts no body"); return;
}
if (active) { rejectHttp(response, 409, "A directory chooser is already open"); return; }
const controller = new AbortController();
const abort = () => { if (!response.writableEnded) controller.abort(); };
request.once("aborted", abort); response.once("close", abort);
const timer = setTimeout(() => controller.abort(), timeoutMs);
// Defer choose so the singleton exists even if a provider throws synchronously.
const settled = Promise.resolve().then(() => picker.choose(controller.signal));
active = { controller, settled };
try {
const result = await settled;
if (response.destroyed) return;
if (controller.signal.aborted || result.kind === "cancelled") {
response.setHeader("Content-Type", "application/json"); response.end(JSON.stringify({ kind: "cancelled" })); return;
}
const valid = await validateNativeDirectory(result.directory);
if (response.destroyed) return;
if (controller.signal.aborted) {
response.setHeader("Content-Type", "application/json"); response.end(JSON.stringify({ kind: "cancelled" })); return;
}
if (!valid) { rejectHttp(response, 422, "The selected directory is no longer available"); return; }
response.setHeader("Content-Type", "application/json");
response.end(JSON.stringify({ kind: "selected", directory: result.directory }));
} catch {
if (!response.destroyed) {
// An abort request is not proof that the native window closed. Only
// the provider's settled cancellation result establishes that.
rejectHttp(response, 503, "Native directory selection failed");
}
} finally {
clearTimeout(timer); request.off("aborted", abort); response.off("close", abort); active = undefined;
}
},
async dispose(): Promise<void> {
closed = true; active?.controller.abort();
await picker.dispose();
await active?.settled.catch(() => undefined);
},
};
}
12 changes: 12 additions & 0 deletions packages/webui/src/server/http/router.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import type { createNativeDirectoryRoute } from "./native-directory.js";
// HTTP router for the loopback service: dispatch one admitted request to the
// session-transfer, workspace-file or static client-asset route. Split from
// `service.ts` with no behaviour change — the admission order, route order,
Expand Down Expand Up @@ -26,6 +27,7 @@ import type { WebuiBrowserExtensionPackage } from "../browser-bridge/extension-p

export interface WebuiHttpRouterContext {
readonly host: string;
readonly nativeDirectoryRoute?: ReturnType<typeof createNativeDirectoryRoute>;
/** The TCP port the kernel allocated, once `start()` has resolved. */
readonly boundTcpPort: () => number | undefined;
/** The configured TCP port, used as the client-asset fallback before bind. */
Expand Down Expand Up @@ -97,6 +99,16 @@ export async function serveHttpRequest(
await serveDesignAsset(request, response, url, context.port);
return;
}
if (url.pathname === "/native-directory-picker") {
if (request.method !== "POST" || url.search || !context.nativeDirectoryRoute) {
rejectHttp(response, 404, "Not Found"); return;
}
await context.nativeDirectoryRoute.handle(request, response, {
host: context.host, port: context.boundTcpPort(), credential: context.credential,
fullAccess: context.fullAccess,
});
return;
}
if (request.method === "GET" && url.pathname === "/session-transfer") {
await handleSessionTransfer(url, response, context.port);
return;
Expand Down
2 changes: 2 additions & 0 deletions packages/webui/src/server/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -130,3 +130,5 @@ export type {
WebuiPermissionDecision,
} from "../shared/contracts/interactions.js";
export type { WebuiModelEntry } from "../shared/contracts/models.js";

export type { WebuiNativeDirectoryPicker } from "./http/native-directory.js";
Loading
Loading