create-opentray 0.24.0 → 0.26.0

package/dist/index.d.mts

@@ -1,6 +1,5 @@
-import { WizardCliOptions, main, parseWizardCli } from "./bin.mjs";
+import { A as resolveFaviconUrl, B as LaunchVector, C as UiLocale, D as extractTitle, E as extractFaviconCandidates, F as parseNetstatPorts, H as resolveLaunchVector, I as parsePowerShellPorts, L as serviceUrl, M as DiscoveredService, N as createPortDiscovery, O as faviconCandidateSize, P as parseLsofPorts, R as verifyHttpService, S as writeScaffold, T as ScrapeResult, U as resolveOnPath, V as parseShebangInterpreter, _ as isDirectoryOccupied, a as parseWizardCli, b as ScaffoldOptions, c as WizardSession, d as MaterializeContext, f as MaterializeInput, g as expectedDarwinBundlePath, h as detectPackageManager, j as scrapeService, k as rankFaviconCandidates, l as WizardState, m as MaterializeResult, n as main, o as WizardEvent, p as MaterializeLogEvent, s as WizardFormValues, t as WizardCliOptions, u as createWizardSession, v as materialize, w as FaviconCandidate, x as ScaffoldResult, y as ScaffoldAppConfig, z as waitForTcpPort } from "./bin-CrMTyTux.mjs";
 import { IncomingMessage } from "node:http";
-import { AppIcon } from "@opentray/spec";
 
 //#region packages/core/src/app-id.d.ts
 /**
@@ -17,59 +16,6 @@ declare const toProjectDirectoryName: (appId: string) => string;
 /** True when the appId has the shape consumers expect for stable identity. */
 declare const isValidAppId: (appId: string) => boolean;
 //#endregion
-//#region packages/core/src/command-family.d.ts
-type Family = "npm" | "go" | "rust" | "python" | "dotnet" | "custom";
-interface FamilyFormState {
-  readonly family: Family;
-  /** npm/python 系列的 runner（如 `npx`、`yarn dlx`、`uvx`、`pipx run`）。 */
-  readonly runner: string;
-  /** runner 与包名之间的选项 token（如 `deno run -A` 的 `-A`）。 */
-  readonly runnerFlags: string;
-  /** 包名 / module 路径 / crate / 工具 ID（保持用户输入原样）。 */
-  readonly pkg: string;
-  /** 空串 = latest/省略。 */
-  readonly version: string;
-  /** 包名之后的参数（原样字符串）。 */
-  readonly args: string;
-  /** 仅 Rust：运行二进制名；空串 = 与 crate 同名。 */
-  readonly binary: string;
-  /** 仅自定义：完整自由命令。 */
-  readonly raw: string;
-}
-//#endregion
-//#region packages/core/src/launch-vector.d.ts
-interface LaunchVector {
-  readonly command: string;
-  readonly args: readonly string[];
-  readonly cwd: string;
-  /** Optional explicit env overlay merged over the runtime environment. */
-  readonly env?: Readonly<Record<string, string>>;
-}
-interface ResolveLaunchVectorOptions {
-  readonly tokens: readonly string[];
-  readonly cwd: string;
-  readonly platform?: NodeJS.Platform;
-  readonly pathEnv?: string;
-  readonly accessFile?: (path: string) => Promise<void>;
-  readonly firstLine?: (path: string) => Promise<string | undefined>;
-}
-/** Resolve a bare command name against PATH; returns undefined when absent. */
-declare const resolveOnPath: (command: string, options: Pick<ResolveLaunchVectorOptions, "platform" | "pathEnv" | "accessFile">) => Promise<string | undefined>;
-/** Read a `#!/usr/bin/env <interpreter>` shebang; undefined for other files. */
-declare const parseShebangInterpreter: (firstLine: string | undefined) => {
-  interpreter: string;
-  args: readonly string[];
-} | undefined;
-/**
- * Resolve the user's command tokens to a PATH-independent vector:
- * - absolute-ize bare executables through PATH lookup;
- * - resolve relative script paths against cwd;
- * - when the executable is an `env <interpreter>` shebang script, run the
- *   interpreter directly with the script as its first argument.
- * The persisted descriptor never includes an environment map.
- */
-declare const resolveLaunchVector: (options: ResolveLaunchVectorOptions) => Promise<LaunchVector>;
-//#endregion
 //#region packages/core/src/tokenize.d.ts
 interface TokenizeResult {
   readonly ok: boolean;
@@ -84,273 +30,6 @@ interface TokenizeResult {
  */
 declare const tokenizeCommandLine: (input: string) => TokenizeResult;
 //#endregion
-//#region packages/core/src/port-scan.d.ts
-interface DiscoveredService {
-  readonly port: number;
-  readonly url: string;
-  readonly firstSeenAt: number;
-  title?: string;
-}
-type ListenersRunner = (platform: NodeJS.Platform) => Promise<ReadonlySet<number>>;
-/** Listener snapshot with process ownership: port -> owning PIDs. */
-type ListenerOwners = ReadonlyMap<number, ReadonlySet<number>>;
-/** Loopback service URL for a discovered port. */
-declare const serviceUrl: (port: number) => string;
-declare const parseLsofPorts: (stdout: string) => ReadonlySet<number>;
-/** Parses `netstat -ano -p tcp` output; keeps LISTENING rows. */
-declare const parseNetstatPorts: (stdout: string) => ReadonlySet<number>;
-declare const parsePowerShellPorts: (stdout: string) => ReadonlySet<number>;
-/** TCP-connect probe used by the generated app and discovery verification. */
-declare const waitForTcpPort: (port: number, timeoutMs: number, intervalMs?: number, host?: string) => Promise<boolean>;
-/** Verify a port answers with an HTTP response (any status counts). */
-declare const verifyHttpService: (port: number, timeoutMs?: number) => Promise<boolean>;
-interface PortDiscoveryOptions {
-  readonly platform?: NodeJS.Platform;
-  readonly baseline: ReadonlySet<number>;
-  readonly listListeners?: ListenersRunner;
-  readonly verifyHttp?: (port: number) => Promise<boolean>;
-  /** Resolves the PIDs whose listeners count as services (preview process tree). */
-  readonly resolveOwnerPids?: () => Promise<ReadonlySet<number>>;
-  readonly listOwners?: () => Promise<ListenerOwners>;
-  readonly intervalMs?: number;
-}
-interface PortDiscoverySession {
-  /** Known new services, first-seen order. */
-  services(): readonly DiscoveredService[];
-  /** One polling pass; resolves to services discovered during this pass. */
-  poll(): Promise<readonly DiscoveredService[]>;
-  stop(): void;
-}
-/**
- * Diff-based port discovery. Each poll re-enumerates listeners, keeps ports
- * absent from the baseline, and adds HTTP-verified ones in first-seen order.
- */
-declare const createPortDiscovery: (options: PortDiscoveryOptions) => PortDiscoverySession;
-//#endregion
-//#region packages/core/src/scrape.d.ts
-/** Variant tag: the original art, a solid-color silhouette derived from it,
- * or an AI subject-extraction derived by the wizard's browser client. */
-type IconVariant = "original" | "solid-black" | "solid-white" | "subject";
-/** One scraped icon candidate, ranked and deduplicated. */
-interface ScrapedIcon {
-  /** Index within the candidate list (stable for /api/icon-data/:port/:index). */
-  readonly index: number;
-  /** Absolute URL the bytes came from (variants inherit their source URL). */
-  readonly url: string;
-  /** Absolute temp file holding the icon bytes. */
-  readonly path: string;
-  /** True pixel clarity (largest dimension; SVG uses intrinsic or 512). */
-  readonly width: number;
-  readonly height: number;
-  /** png | svg | jpeg | webp | gif | ico (ico payloads are extracted to png). */
-  readonly format: string;
-  /** Which art this entry carries (originals feed the app-icon picker; the
-   *  advanced tray picker also shows solid variants). */
-  readonly variant: IconVariant;
-  /** Index of the original candidate a variant was derived from. */
-  readonly variantOf?: number;
-}
-interface ScrapeResult {
-  readonly ok: boolean;
-  readonly title: string | undefined;
-  /** Absolute temp file holding the chosen (clearest) favicon bytes, when found. */
-  readonly iconPath: string | undefined;
-  readonly iconUrl?: string;
-  /** All viable candidates ranked by clarity, near-duplicates removed. */
-  readonly icons: readonly ScrapedIcon[];
-  /**
-   * Whether the page's response policy allows third-party iframe embedding
-   * (toolbar mode feasibility); undefined when the page could not be fetched.
-   */
-  readonly frameEmbeddable?: boolean;
-}
-interface FaviconCandidate {
-  readonly href: string;
-  readonly rel: string;
-  readonly sizes?: string;
-}
-/** Extract `<title>` text from HTML. */
-declare const extractTitle: (html: string) => string | undefined;
-/** Extract `<link rel=... href=...>` favicon candidates from HTML head. */
-declare const extractFaviconCandidates: (html: string) => readonly FaviconCandidate[];
-/** Largest dimension of a `sizes` attribute value such as `32x32` or `any`. */
-declare const faviconCandidateSize: (candidate: FaviconCandidate) => number;
-/** Resolve a favicon href against the service origin. */
-declare const resolveFaviconUrl: (href: string, origin: string) => string | undefined;
-/** Order candidates: declared-size icons descending, then apple-touch-icon, then others. */
-declare const rankFaviconCandidates: (candidates: readonly FaviconCandidate[]) => readonly FaviconCandidate[];
-interface ScrapePage {
-  readonly ok: boolean;
-  readonly status: number;
-  readonly body: string;
-  readonly headers: Record<string, string>;
-}
-interface ScrapeBytes {
-  readonly ok: boolean;
-  readonly status: number;
-  readonly bytes: Buffer;
-  readonly contentType: string;
-}
-interface ScrapeFetch {
-  page(url: string, timeoutMs?: number): Promise<ScrapePage>;
-  bytes(url: string, timeoutMs?: number): Promise<ScrapeBytes>;
-}
-/**
- * Scrape title and ALL icon candidates from an arbitrary http(s) URL.
- * Never throws: failures return `ok: false` with whatever partial identity
- * was found. (`scrapeService` is the loopback-port wrapper over this.)
- */
-declare const scrapeUrl: (url: string, options?: {
-  fetch?: ScrapeFetch;
-  tempDir?: string;
-}) => Promise<ScrapeResult>;
-/**
- * Scrape title and ALL icon candidates from a service port. Never throws:
- * failures return `ok: false` with whatever partial identity was found.
- */
-declare const scrapeService: (port: number, options?: {
-  fetch?: ScrapeFetch;
-  tempDir?: string;
-}) => Promise<ScrapeResult>;
-//#endregion
-//#region ../icon/src/generate.d.ts
-interface OpenTrayAppIconOptions {
-  readonly sourcePath: string;
-  readonly outputPath?: string;
-  readonly icnsOutputPath?: string;
-  readonly icoOutputPath?: string;
-  readonly linuxOutputDirectory?: string;
-  readonly manifestOutputPath?: string;
-  readonly cachePath?: string;
-  /** Advanced: override the module whose bytes identify the generator implementation. */
-  readonly implementationPath?: string;
-  /** Advanced: override the source file whose bytes identify the generator implementation. */
-  readonly implementationSourcePath?: string;
-  /**
-   * Pre-composed source: skip glyph re-tiling; pass pixels through verbatim.
-   */
-  readonly composed?: boolean;
-  /**
-   * Separate macOS content source; ICNS encodes from this while ICO/Linux
-   * use sourcePath.
-   */
-  readonly macosSourcePath?: string;
-}
-interface OpenTrayAppIconCacheMetadata {
-  readonly schemaVersion: number;
-  readonly sourceSha256: string;
-  readonly macosSourceSha256?: string;
-  readonly composed?: boolean;
-  readonly sourceImplementationSha256: string | null;
-  readonly implementationSha256: string;
-  readonly recipeVersion: string;
-  readonly jsquashPngVersion: string;
-  readonly jsquashResizeVersion: string;
-  readonly resvgVersion: string;
-  readonly iconEncoderVersion: string;
-  readonly figmaSquircleVersion: string;
-  readonly exifrVersion: string;
-  readonly outputPath: string;
-  readonly icnsOutputPath: string;
-  readonly icoOutputPath: string;
-  readonly linuxPngOutputPaths: readonly {
-    readonly size: number;
-    readonly path: string;
-  }[];
-  readonly manifestOutputPath: string;
-  /** Absolute file sources ready to pass to OpenTray at runtime. */
-  readonly appIcon: AppIcon;
-}
-/** Generate one strict cross-platform AppIcon asset set. */
-declare function generateOpenTrayAppIcon(options: OpenTrayAppIconOptions): Promise<OpenTrayAppIconCacheMetadata>;
-//#endregion
-//#region ../icon/src/default-icon.d.ts
-interface DefaultAppIconOptions {
-  readonly appName: string;
-  readonly accent?: string;
-  readonly outputDir: string;
-  /**
-   * Output file stem. The runtime uses the default (`default-app-icon`); the
-   * create pipeline passes `app-icon` so the glyph fallback lands in the
-   * scaffold's standard catalog layout — one generator, one visual standard.
-   */
-  readonly fileStem?: string;
-  /** Cache metadata path; defaults to `<outputDir>/../.cache/default-app-icon.json`. */
-  readonly cachePath?: string;
-}
-interface DefaultAppIconResult {
-  readonly fullPngPath: string;
-  readonly macOSPngPath: string;
-  readonly icnsPath: string;
-  readonly icoPath: string;
-  readonly linuxPngPaths: readonly {
-    size: number;
-    path: string;
-  }[];
-  readonly manifestPath: string;
-  /** Absolute file sources ready to pass to the runtime as `appIcon`. */
-  readonly appIcon: AppIcon;
-  readonly cacheIdentity: string;
-  /**
-   * True when the name's own first glyph could not be covered by the font
-   * ladder on this host and the neutral terminal mark was used instead
-   * (e.g. CJK names on CJK-less CI runners and containers).
-   */
-  readonly degraded: boolean;
-}
-/** Generate (or reuse, by full identity) the default glyph App icon catalog. */
-declare function generateDefaultAppIcon(options: DefaultAppIconOptions): Promise<DefaultAppIconResult>;
-//#endregion
-//#region ../icon/src/compose.d.ts
-type IconBackground = "black" | "white" | "transparent";
-//#endregion
-//#region packages/core/src/command-run.d.ts
-interface CommandRunEvent {
-  readonly type: "stdout" | "stderr" | "exit" | "spawn-error" | "pty-ready" | "pty-unavailable";
-  /** The PTY binding's output chunk, verbatim; rendering is the frontend's job. */
-  readonly chunk?: string;
-  readonly code?: number | null;
-  readonly message?: string;
-  /**
-   * Stable machine code for pty-unavailable events so consumers can localize
-   * (and detect) the reason without parsing the human-readable message.
-   */
-  readonly reason?: "pty_bun_terminal_missing" | "pty_node_pty_missing";
-}
-interface CommandRunTerminalSize {
-  readonly cols: number;
-  readonly rows: number;
-}
-interface CommandRunOptions {
-  readonly tokens: readonly string[];
-  readonly cwd?: string;
-  readonly env?: NodeJS.ProcessEnv;
-  readonly ringLimit?: number;
-  /** Attach through a PTY when available; defaults to true. */
-  readonly pty?: boolean;
-  readonly terminalSize?: CommandRunTerminalSize;
-  readonly onEvent: (event: CommandRunEvent) => void;
-}
-interface CommandRun {
-  readonly pid: number | undefined;
-  readonly pty: boolean;
-  readonly exited: Promise<{
-    code: number | null;
-    spawnError?: string;
-  }>;
-  readonly output: readonly string[];
-  /** Write terminal input bytes to the command's stdin (PTY mode only). */
-  write(data: string): void;
-  /** Resize the pseudo-terminal (PTY mode only). */
-  resize(size: CommandRunTerminalSize): void;
-  kill(): Promise<void>;
-}
-declare const startCommandRun: (options: CommandRunOptions) => Promise<CommandRun>;
-//#endregion
-//#region packages/core/src/user-messages.d.ts
-declare const UI_LOCALES: readonly ["zh-CN", "ja", "ko", "en", "ar", "fr", "es", "de", "ru"];
-type UiLocale = (typeof UI_LOCALES)[number];
-//#endregion
 //#region packages/core/src/open-app.d.ts
 interface OpenAppInput {
   readonly projectDir: string;
@@ -369,408 +48,6 @@ declare const openMaterializedApp: (input: OpenAppInput) => Promise<OpenAppResul
  */
 declare const pinningHint: (platform?: NodeJS.Platform, locale?: UiLocale) => string;
 //#endregion
-//#region packages/core/src/scaffold.d.ts
-interface ScaffoldAppConfig {
-  readonly schemaVersion: 1;
-  readonly appId: string;
-  readonly appName: string;
-  /** Command source; exactly one of command/url is present (v1 XOR). */
-  readonly command?: LaunchVector;
-  /** URL source: the address the generated window opens directly. */
-  readonly url?: string;
-  readonly service: {
-    readonly port: number;
-  };
-  readonly window: {
-    readonly width: number;
-    readonly height: number; /** URL applications: host the address-bar wrapper (D12). */
-    readonly toolbar?: boolean;
-    readonly titleFollowsDocument: boolean;
-    readonly iconFollowsDocument: boolean;
-  };
-  /** Tray icon asset (written by materialize); omitted → text-only tray. */
-  readonly trayIcon?: {
-    readonly path: string;
-    readonly template: boolean;
-  };
-  /** Generated-app shell (startup terminal / address-bar tabs). */
-  readonly shell?: {
-    readonly showTerminal: boolean;
-    readonly showAddressBar: boolean;
-  };
-  /** v1 developerMode: only WebView DevTools admission; default false. */
-  readonly developerMode?: boolean;
-}
-interface ScaffoldOptions {
-  readonly config: ScaffoldAppConfig;
-  readonly targetDir: string;
-  /** opentray/@opentray/ext-webview version range written into package.json. */
-  readonly dependencyRange: string;
-  /** Whether install will be skipped; only affects README guidance text. */
-  readonly skipInstall?: boolean;
-  /** Directory holding the prebuilt shell UI (copied to app-shell/).
-   * Defaults to the adapter-staged assets resolved from the running package
-   * layout (published create-opentray/dist/shell, or the workspace build). */
-  readonly shellAssetsDir?: string;
-}
-interface ScaffoldResult {
-  readonly projectDir: string;
-  readonly entryPath: string;
-  readonly configPath: string;
-  readonly appIconDir: string;
-  readonly writtenFiles: readonly string[];
-}
-declare const writeScaffold: (options: ScaffoldOptions) => Promise<ScaffoldResult>;
-//#endregion
-//#region packages/core/src/materialize.d.ts
-type MaterializeLogEvent = {
-  readonly type: "step";
-  readonly step: string;
-  readonly message: string;
-} | {
-  readonly type: "log";
-  readonly message: string;
-};
-interface MaterializeInput {
-  readonly config: ScaffoldAppConfig;
-  readonly targetDir: string;
-  readonly dependencyRange: string;
-  readonly iconSourcePath: string | undefined;
-  /** True when the tray source is a solid silhouette (darwin template). */
-  readonly trayIconIsSolid?: boolean;
-  /** Icon composition (owner round-12): background + foreground scale. */
-  readonly iconBackground?: IconBackground;
-  readonly iconScale?: number;
-  /** Nearest-neighbor sampling for pixel-art sources (v1 imageSmoothingEnabled). */
-  readonly imageSmoothingEnabled?: boolean;
-  /** Tray icon source; defaults to the app icon source when omitted. */
-  readonly trayIconSourcePath?: string;
-  /** Generated-app shell options (startup terminal / address bar). */
-  readonly shell?: {
-    showTerminal: boolean;
-    showAddressBar: boolean;
-  };
-  /** Adapter-owned prebuilt shell UI directory (copied to app-shell/). */
-  readonly shellAssetsDir?: string;
-  readonly packageManager: "npm" | "pnpm" | "bun";
-  readonly skipInstall: boolean;
-  readonly force: boolean;
-}
-interface MaterializeResult {
-  readonly scaffold: ScaffoldResult;
-  readonly projectDir: string;
-}
-interface MaterializeContext {
-  readonly log: (event: MaterializeLogEvent) => void;
-  readonly generateIcon?: typeof generateOpenTrayAppIcon;
-  /** Same seam for the glyph default catalog (wizard tests stub both). */
-  readonly generateDefaultIcon?: typeof generateDefaultAppIcon;
-  readonly runInstall?: (options: RunInstallOptions) => Promise<void>;
-}
-interface RunInstallOptions {
-  readonly projectDir: string;
-  readonly packageManager: "npm" | "pnpm" | "bun";
-  readonly log: (message: string) => void;
-}
-/** True when the directory exists and contains anything beyond ignorable files. */
-declare const isDirectoryOccupied: (dir: string) => Promise<boolean>;
-/** Detect package manager from lockfiles then npm_config_user_agent. */
-declare const detectPackageManager: (files: readonly string[], userAgent: string | undefined) => "npm" | "pnpm" | "bun";
-/** Expected stable Darwin bundle path for the generated project's identity. */
-declare const expectedDarwinBundlePath: (config: {
-  appName: string;
-  appId: string;
-}) => string;
-/**
- * Backward-compatible composition used by the wizard adapter: generation is
- * the payload phase. There is no first-launch validation — the wizard panel's
- * command preview is the validator (decision D1).
- */
-declare const materialize: (input: MaterializeInput, context: MaterializeContext) => Promise<MaterializeResult>;
-//#endregion
-//#region src/wizard.d.ts
-interface WizardEnvEntry {
-  readonly key: string;
-  readonly value: string;
-}
-/** App-icon composition (owner round-12): foreground over black/white/
- *  transparent background; the wizard derives the auto suggestion. */
-type WizardIconBackground = "black" | "white" | "transparent";
-interface WizardIconComposition {
-  readonly key: string;
-  readonly compositePath: string;
-  readonly macOSPath: string;
-  readonly background: WizardIconBackground;
-}
-interface WizardIconAnalysis {
-  readonly luminance: number | undefined;
-  readonly coverage: number;
-  readonly suggested: WizardIconBackground;
-}
-/** Command execution options (advanced): working directory, custom env, and
- *  the input mode — array mode takes argv elements verbatim (no string
- *  splitting), string mode tokenizes one command line. */
-interface WizardCommandOptions {
-  /** Empty = the wizard's working directory. */
-  readonly cwd: string;
-  readonly env: readonly WizardEnvEntry[];
-  readonly argsMode: "string" | "array";
-  /**
-   * 系列作者状态（plan.md D11 / Codex B1）：显式投影是系列/appId 推导的
-   * 服务端权威（Rust 的 crate/binary 无法从命令串恢复）；null = 按命令串派生。
-   * 命令串始终是执行/持久化向量。env 预设（npm_config_yes 等）不再有隐形
-   * 注入开关——env 行是唯一可信源（R10 用户拍板）。
-   */
-  readonly family: FamilyFormState | null;
-}
-type WizardState = "idle" | "running" | "discovered" | "failed" | "frozen" | "materializing" | "success";
-interface WizardFormValues {
-  readonly appId: string;
-  readonly appName: string;
-  readonly iconPath: string;
-  /** Icon composition (owner round-12). */
-  readonly iconBackground: WizardIconBackground;
-  readonly iconScale: number;
-  /** Empty = follow the app icon choice (default). */
-  readonly trayIconPath: string;
-  readonly pm: "npm" | "pnpm" | "bun";
-  /** Wipe an existing non-empty target directory before materializing. */
-  readonly force: boolean;
-  /** Advanced: render the command PTY in the generated app (default false). */
-  readonly showStartupTerminal: boolean;
-  /** Advanced: address-bar service tabs in the generated app (default false). */
-  readonly showAddressBar: boolean;
-  /** Advanced v1 sampling intent: false keeps pixel-art edges (default true). */
-  readonly imageSmoothingEnabled: boolean;
-  /** Advanced v1 developer mode: only WebView DevTools admission (default false). */
-  readonly developerMode: boolean;
-}
-/** Placeholder suggestions shown in the form; empty fields resolve to these. */
-interface WizardFormDefaults {
-  readonly appId: string;
-  readonly appName: string;
-  /** Resolved project directory the app will be generated into. */
-  readonly targetDir: string;
-  /**
-   * Effective default icon source (the clearest scraped candidate). The form
-   * value stays empty until the user picks/upload; composition must follow
-   * this default too, or the preview would never appear without a click.
-   */
-  readonly iconPath: string;
-}
-type WizardEvent = {
-  readonly type: "state";
-  readonly state: WizardState;
-  readonly reason?: string;
-} | {
-  readonly type: "log";
-  readonly stream: "stdout" | "stderr";
-  readonly chunk: string;
-} | {
-  readonly type: "term-mode";
-  readonly interactive: boolean;
-  readonly message?: string;
-} | {
-  readonly type: "run-status";
-  readonly running: boolean;
-  readonly code?: number | null;
-} | {
-  readonly type: "command-display";
-  readonly command: string;
-} | {
-  readonly type: "command-options";
-  readonly options: WizardCommandOptions;
-  readonly defaultCwd: string;
-} | {
-  readonly type: "services";
-  readonly services: readonly DiscoveredService[];
-  readonly selectedPort: number | undefined;
-} | {
-  readonly type: "scrape";
-  readonly port: number;
-  readonly title?: string;
-  readonly hasIcon: boolean;
-} | {
-  readonly type: "icons";
-  readonly port: number;
-  readonly icons: readonly ScrapedIcon[];
-  /** Bumps on every scrape-side REPLACEMENT of the list (not appends):
-   * indexes restart from zero per scrape, so clients keying per-candidate
-   * work (e.g. subject extraction) need this to tell generations apart. */
-  readonly generation: number;
-} | {
-  readonly type: "form";
-  readonly values: WizardFormValues;
-  readonly defaults: WizardFormDefaults;
-  readonly targetDirExists: boolean;
-} | {
-  readonly type: "materialize-log";
-  readonly message: string;
-} | {
-  readonly type: "materialize-step";
-  readonly step: string;
-  readonly message: string;
-} | {
-  readonly type: "success";
-  readonly projectDir: string;
-  readonly bundlePath?: string;
-  readonly pinHint: string;
-} /** Authoritative whole-session state; sent to every NEW SSE client first. */ | {
-  readonly type: "snapshot";
-  readonly state: WizardState;
-  readonly runAlive: boolean;
-  readonly command: string; /** URL 模式激活时的源地址（命令模式为 undefined）。 */
-  readonly urlSource?: string;
-  readonly commandOptions: WizardCommandOptions;
-  readonly form: WizardFormValues;
-  readonly defaults: WizardFormDefaults;
-  readonly targetDirExists: boolean;
-  readonly services: readonly DiscoveredService[];
-  readonly selectedPort?: number | undefined;
-  readonly iconCandidates: readonly ScrapedIcon[];
-  readonly iconsPort?: number | undefined; /** Scrape-generation counter carried by icons events and snapshots. */
-  readonly iconsGeneration: number;
-  readonly interactive: boolean;
-};
-interface WizardOptions {
-  readonly cwd: string;
-  /**
-   * USER_HOME anchor: the command-execution default cwd AND the root of the
-   * default generated-project location (~/.opentray/create/<name>).
-   */
-  readonly homeDir?: string;
-  /** Explicit project directory (CLI positional); default: the create root. */
-  readonly targetDir?: string | undefined;
-  readonly skipInstall: boolean;
-  /** Seed the 强制覆盖 toggle (CLI --force); the form owns the live value. */
-  readonly force?: boolean | undefined;
-  readonly packageManager?: "npm" | "pnpm" | "bun";
-  readonly dependencyRange: string;
-  readonly emit: (event: WizardEvent) => void;
-  readonly spawnRun?: typeof startCommandRun;
-  readonly listListeners?: () => Promise<ReadonlySet<number>>;
-  readonly verifyHttp?: (port: number) => Promise<boolean>;
-  /** Test/embedding seam for listener ownership. */
-  readonly listPortOwners?: () => Promise<ListenerOwners>;
-  readonly scrape?: typeof scrapeService;
-  /** Test seam for the URL-mode preset scrape. */
-  readonly scrapeUrl?: typeof scrapeUrl;
-  readonly resolveVector?: typeof resolveLaunchVector;
-  /** Test/embedding seam for PATH resolution of the cargo-install guard. */
-  readonly resolveOnPath?: typeof resolveOnPath;
-  /** Test/embedding seam for the materialize pipeline. */
-  readonly materializeContext?: Partial<MaterializeContext>;
-  readonly platform?: NodeJS.Platform;
-  readonly pollIntervalMs?: number;
-  readonly scrapeIntervalMs?: number;
-}
-interface WizardSession {
-  readonly state: WizardState;
-  readonly services: readonly DiscoveredService[];
-  readonly selectedPort: number | undefined;
-  /** True while the preview process is alive (Run button shows Interrupt). */
-  readonly runAlive: boolean;
-  /** Latest scraped icon candidates for the selected service, ranked by clarity. */
-  readonly iconCandidates: readonly ScrapedIcon[];
-  /** Persist an uploaded image into the session temp dir; returns its path. */
-  saveIconUpload(bytes: Buffer): Promise<string>;
-  /** Candidate lookup scoped to the port it was scraped from. */
-  iconCandidate(port: number, index: number): ScrapedIcon | undefined;
-  /** Select a scraped candidate as the icon source (marks the field touched). */
-  selectIconCandidate(port: number, index: number): boolean;
-  /** Select a candidate (original or solid variant) as the TRAY icon. */
-  selectTrayIconCandidate(port: number, index: number): boolean;
-  /** Test/extension seam: replace the scraped candidate set for a port. */
-  replaceIconCandidates(port: number, icons: readonly ScrapedIcon[]): void;
-  /** Append a wizard-derived candidate (e.g. browser-side subject extraction)
-   * for the port the current candidates belong to; bytes land in the
-   * session-owned temp dir so icon routes keep serving them. Returns the
-   * appended candidate, or undefined when the port/state rejects it. */
-  addIconCandidate(port: number, candidate: {
-    readonly bytes: Buffer;
-    readonly variantOf: number;
-    readonly width: number;
-    readonly height: number;
-    readonly format: string;
-  }): Promise<ScrapedIcon | undefined>;
-  /** Compose the app icon preview/asset for the current foreground. */
-  composeIcon(options: {
-    foregroundPath: string;
-    background?: WizardIconBackground;
-    scale?: number;
-  }): Promise<WizardIconComposition>;
-  /** Register a composition for token-scoped byte serving (server seam). */
-  trackIconComposition(composition: WizardIconComposition): void;
-  /** Look up a registered composition by cache key. */
-  iconComposition(key: string): WizardIconComposition | undefined;
-  /** Wizard-owned icon source roots (containment for icon routes). */
-  iconSourceRoots(): readonly string[];
-  /** Auto-suggestion for the foreground (background + reason). */
-  analyzeIconForeground(foregroundPath: string): Promise<WizardIconAnalysis>;
-  readonly form: WizardFormValues;
-  readonly result: MaterializeResult | undefined;
-  /** Adopt the webui's locale for every user-facing string this session emits. */
-  setLocale(locale: UiLocale): void;
-  /** Whole-session state for reconnecting clients (page refresh recovery). */
-  snapshot(): WizardEvent;
-  /** String form is tokenized; array form is taken as argv verbatim (array
-   *  input mode — no string splitting is ever applied to it). */
-  submitCommand(command: string | readonly string[]): Promise<void>;
-  /** URL 模式入口：地址即源（一次抓取预设，进入 discovered 可确认态）；
-   * 空 url 退出 URL 模式回到 idle。 */
-  submitUrl(url: string): Promise<void>;
-  /** Active URL-mode source address; undefined in command mode. */
-  readonly urlSource: string | undefined;
-  /** Derive placeholder defaults from command text without spawning anything. */
-  prime(command: string | readonly string[]): void;
-  readonly commandOptions: WizardCommandOptions;
-  updateCommandOptions(patch: Partial<WizardCommandOptions>): void;
-  selectService(port: number): void;
-  updateForm(patch: Partial<WizardFormValues>): void;
-  terminalInput(data: string): void;
-  terminalResize(size: {
-    cols: number;
-    rows: number;
-  }): void;
-  confirm(): void;
-  /** Abort a frozen confirmation and return to the editable pre-freeze state. */
-  cancel(): void;
-  /**
-   * Share the FROZEN parameters (wizard-share-and-list-scan D3): build an
-   * export artifact from the confirmation state WITHOUT running the command
-   * or materializing anything. Works pre-create. Scraped web icons keep
-   * their http source URL plus the icon-generation flags by default;
-   * `inlineIcon` opts into embedding the bytes instead.
-   */
-  exportFrozen(options: {
-    readonly format: "command" | "sh" | "ps1";
-    readonly acknowledgeEnv?: boolean;
-    readonly forceCopy?: boolean; /** true=内嵌字节；false=按引用分享（URL/本地路径）；缺省=按来源默认。 */
-    readonly inlineIcon?: boolean;
-  }): Promise<WizardExportResult>;
-  create(): Promise<void>;
-  stop(): Promise<void>;
-}
-type WizardExportResult = {
-  readonly ok: true;
-  readonly kind: "command";
-  readonly command: string;
-} | {
-  readonly ok: true;
-  readonly kind: "script";
-  readonly filename: string;
-  readonly content: string; /** 核心调用行（不含注释/脚手架），复制命令用。 */
-  readonly commandLine: string;
-  readonly requiresEnvAcknowledgement: boolean; /** How the app icon actually traveled in this artifact. */
-  readonly iconSharedAs: "url" | "embedded" | "local" | "none"; /** What the icon source CAN be shared as: url / local path / none. */
-  readonly iconReference: "url" | "local" | "none";
-} | {
-  readonly ok: false;
-  readonly code: "state_error" | "resolve_failed" | "env_ack_required" | "export_unsafe";
-  readonly message: string;
-};
-declare const createWizardSession: (options: WizardOptions) => WizardSession;
-//#endregion
 //#region src/server.d.ts
 interface WizardServerHandle {
   readonly url: string;