create-opentray 0.24.0 → 0.26.0

package/dist/bin-CrMTyTux.d.mts

@@ -0,0 +1,751 @@
+import { AppIcon } from "@opentray/spec";
+
+//#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/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[];
+}
+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;
+}
+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/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;
+    /**
+     * Host the native navigation-toolbar carrier (add-webview-orchestration
+     * D12/D13): one toolbar webview above one content webview per generated
+     * window, for BOTH URL and command applications. This is the one
+     * canonical toolbar field — the legacy shell `showAddressBar` input is
+     * retired (stale frozen occurrences are ignored by loose parsing).
+     */
+    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 options (startup terminal visibility only). */
+  readonly shell?: {
+    readonly showTerminal: 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 visibility only; the
+   *  toolbar is a `window.toolbar` fact, add-webview-orchestration D13). */
+  readonly shell?: {
+    showTerminal: 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;
+  /**
+   * 「导航工具栏」开关 (add-webview-orchestration D15): compose the native
+   * navigation-toolbar carrier over the target/service window — a
+   * desired-state fact compiling into the v1 `window.toolbar` field for BOTH
+   * application flows (default false). Replaces the retired showAddressBar
+   * input (D13); enabling it requires no embedding knowledge.
+   */
+  readonly toolbar: 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/bin.d.ts
+interface WizardCliOptions {
+  readonly open: boolean;
+  readonly port: number | undefined;
+  readonly pm: "npm" | "pnpm" | "bun" | undefined;
+  readonly skipInstall: boolean;
+  readonly force: boolean;
+  readonly targetDir: string | undefined;
+}
+declare const parseWizardCli: (argv: readonly string[]) => WizardCliOptions;
+declare const openBrowser: (url: string) => Promise<void>;
+/** Draft form values carry fields across versions — forward only the
+ *  known-safe, type-checked subset. Retired fields (the legacy
+ *  showAddressBar, replaced by `toolbar` in add-webview-orchestration D13)
+ *  are ignored here: a stale draft never resurrects a removed input.
+ *  Exported for tests alongside parseWizardCli. */
+declare const normalizeDraftForm: (raw: unknown) => Partial<WizardFormValues> | undefined;
+declare const main: (argv: readonly string[]) => Promise<number>;
+//#endregion
+export { resolveFaviconUrl as A, LaunchVector as B, UiLocale as C, extractTitle as D, extractFaviconCandidates as E, parseNetstatPorts as F, resolveLaunchVector as H, parsePowerShellPorts as I, serviceUrl as L, DiscoveredService as M, createPortDiscovery as N, faviconCandidateSize as O, parseLsofPorts as P, verifyHttpService as R, writeScaffold as S, ScrapeResult as T, resolveOnPath as U, parseShebangInterpreter as V, isDirectoryOccupied as _, parseWizardCli as a, ScaffoldOptions as b, WizardSession as c, MaterializeContext as d, MaterializeInput as f, expectedDarwinBundlePath as g, detectPackageManager as h, openBrowser as i, scrapeService as j, rankFaviconCandidates as k, WizardState as l, MaterializeResult as m, main as n, WizardEvent as o, MaterializeLogEvent as p, normalizeDraftForm as r, WizardFormValues as s, WizardCliOptions as t, createWizardSession as u, materialize as v, FaviconCandidate as w, ScaffoldResult as x, ScaffoldAppConfig as y, waitForTcpPort as z };
+//# sourceMappingURL=bin-CrMTyTux.d.mts.map