@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 03:37 UTC

main
ts 1,450 lines 51.2 KB
Raw
1 import * as Schema from "effect/Schema";
2 import type { PreviewCaptureFailureEncoded } from "./previewCapture.ts";
3
4 import { SnapShotSource } from "./chatAttachment.ts";
5 import { EnvironmentId, PortSchema, TrimmedNonEmptyString } from "./baseSchemas.ts";
6 import { BrowserProfileId } from "./browserProfile.ts";
7 import type {
8 BrowserImportResult,
9 BrowserImportSource,
10 BrowserImportSourceId,
11 } from "./browserImport.ts";
12 import { AuthAccessTokenResult, AuthSessionState } from "./auth.ts";
13 import { AdvertisedEndpoint } from "./remoteAccess.ts";
14 import { ExecutionEnvironmentDescriptor } from "./environment.ts";
15 import { type ClientSettings, type QuitConfirmationMode, SnapShotShortcut } from "./settings.ts";
16 import type { EditorId } from "./editor.ts";
17 import { KeybindingShortcut, type PreviewForwardedShortcut } from "./keybindings.ts";
18
19 import type {
20 DesktopAppActivationRequest,
21 DesktopAppActivationResponse,
22 } from "./desktopAppActivation.ts";
23
24 export interface ContextMenuItem<T extends string = string> {
25 id: T;
26 label: string;
27 detail?: string;
28 destructive?: boolean;
29 disabled?: boolean;
30 header?: boolean;
31 icon?: string;
32 separatorBefore?: boolean;
33 checked?: boolean;
34 children?: readonly ContextMenuItem<T>[];
35 }
36
37 export type QuitShortcutHintEvent =
38 | { readonly state: "down"; readonly mode: Exclude<QuitConfirmationMode, "direct"> }
39 | { readonly state: "up" };
40
41 export interface ContextMenuItemSchemaType {
42 readonly id: string;
43 readonly label: string;
44 readonly detail?: string;
45 readonly destructive?: boolean;
46 readonly disabled?: boolean;
47 readonly header?: boolean;
48 readonly icon?: string;
49 readonly separatorBefore?: boolean;
50 readonly checked?: boolean;
51 readonly children?: readonly ContextMenuItemSchemaType[];
52 }
53
54 export const ContextMenuItemSchema: Schema.Codec<ContextMenuItemSchemaType> = Schema.Struct({
55 id: Schema.String,
56 label: Schema.String,
57 detail: Schema.optionalKey(Schema.String),
58 destructive: Schema.optionalKey(Schema.Boolean),
59 disabled: Schema.optionalKey(Schema.Boolean),
60 header: Schema.optionalKey(Schema.Boolean),
61 icon: Schema.optionalKey(Schema.String),
62 separatorBefore: Schema.optionalKey(Schema.Boolean),
63 checked: Schema.optionalKey(Schema.Boolean),
64 children: Schema.optionalKey(
65 Schema.Array(
66 Schema.suspend((): Schema.Codec<ContextMenuItemSchemaType> => ContextMenuItemSchema),
67 ),
68 ),
69 });
70
71 // Native menus opened from the keyboard select their first item, which is what
72 // moves a screen reader into the menu. Electron assumes a mouse unless told.
73 export const ContextMenuSource = Schema.Literals(["mouse", "keyboard"]);
74 export type ContextMenuSource = typeof ContextMenuSource.Type;
75
76 export type DesktopUpdateStatus =
77 | "disabled"
78 | "idle"
79 | "checking"
80 | "up-to-date"
81 | "available"
82 | "downloading"
83 | "downloaded"
84 | "error";
85
86 export type DesktopRuntimeArch = "arm64" | "x64" | "other";
87 export type DesktopTheme = "light" | "dark" | "system";
88 export type DesktopUpdateChannel = "latest" | "nightly";
89 export type DesktopAppStageLabel = "Alpha" | "Beta" | "Dev" | "Nightly";
90
91 export const DesktopUpdateStatusSchema = Schema.Literals([
92 "disabled",
93 "idle",
94 "checking",
95 "up-to-date",
96 "available",
97 "downloading",
98 "downloaded",
99 "error",
100 ]);
101 export const DesktopRuntimeArchSchema = Schema.Literals(["arm64", "x64", "other"]);
102 export const DesktopThemeSchema = Schema.Literals(["light", "dark", "system"]);
103 export const DesktopUpdateChannelSchema = Schema.Literals(["latest", "nightly"]);
104 export const DesktopAppStageLabelSchema = Schema.Literals(["Alpha", "Beta", "Dev", "Nightly"]);
105
106 export interface DesktopAppBranding {
107 baseName: string;
108 stageLabel: DesktopAppStageLabel;
109 displayName: string;
110 }
111
112 export const DesktopAppBrandingSchema = Schema.Struct({
113 baseName: Schema.String,
114 stageLabel: DesktopAppStageLabelSchema,
115 displayName: Schema.String,
116 });
117
118 export const DesktopSnapShotMode = Schema.Literals(["direct", "portal", "unavailable"]);
119 export type DesktopSnapShotMode = typeof DesktopSnapShotMode.Type;
120
121 export const DesktopCaptureExtensionState = Schema.Struct({
122 status: Schema.Literals([
123 "not-installed",
124 "disabled",
125 "enabled",
126 "restart-required",
127 "update-required",
128 "extensions-disabled",
129 "unsupported",
130 "error",
131 ]),
132 message: Schema.String,
133 });
134 export type DesktopCaptureExtensionState = typeof DesktopCaptureExtensionState.Type;
135
136 export const DesktopCaptureHelperState = Schema.Struct({
137 status: Schema.Literals(["not-installed", "update-required", "ready", "error"]),
138 message: Schema.String,
139 feedbackAvailable: Schema.optional(Schema.Boolean),
140 });
141 export type DesktopCaptureHelperState = typeof DesktopCaptureHelperState.Type;
142
143 export const DesktopSnapShotSetupAction = Schema.Literals([
144 "install-extension",
145 "enable-extension",
146 "disable-extension",
147 "install-kde-helper",
148 "remove-kde-helper",
149 "install-hyprland-helper",
150 "remove-hyprland-helper",
151 "test-mac-capture",
152 "allow-screen-recording",
153 "allow-accessibility",
154 "retry-shortcut",
155 ]);
156 export type DesktopSnapShotSetupAction = typeof DesktopSnapShotSetupAction.Type;
157
158 export const DesktopCaptureConfigRequest = Schema.Struct({
159 operation: Schema.Literals(["install", "remove"]),
160 chooseFile: Schema.Boolean,
161 shortcut: Schema.optional(Schema.String.check(Schema.isMaxLength(80))),
162 });
163 export type DesktopCaptureConfigRequest = typeof DesktopCaptureConfigRequest.Type;
164
165 export const DesktopCaptureConfigPreview = Schema.Struct({
166 id: Schema.String,
167 path: Schema.String,
168 resolvedPath: Schema.String,
169 before: Schema.String,
170 after: Schema.String,
171 shortcut: Schema.String,
172 operation: Schema.Literals(["install", "remove"]),
173 });
174 export type DesktopCaptureConfigPreview = typeof DesktopCaptureConfigPreview.Type;
175
176 export const DesktopCaptureConfigApplied = Schema.Struct({
177 backupPath: Schema.NullOr(Schema.String),
178 warning: Schema.NullOr(Schema.String),
179 });
180 export type DesktopCaptureConfigApplied = typeof DesktopCaptureConfigApplied.Type;
181
182 export const DesktopSnapShotState = Schema.Struct({
183 mode: DesktopSnapShotMode,
184 windows: Schema.optional(Schema.Boolean),
185 linuxDesktop: Schema.optional(Schema.Literals(["gnome", "kde", "niri", "hyprland"])),
186 linuxBackend: Schema.optional(
187 Schema.Literals(["screenshot-portal", "gnome-extension", "niri", "kde", "hyprland", "picker"]),
188 ),
189 linuxFeedbackAvailable: Schema.optional(Schema.Boolean),
190 shortcut: SnapShotShortcut,
191 shortcutRegistered: Schema.Boolean,
192 shortcutPending: Schema.optional(Schema.Boolean),
193 shortcutCanRetry: Schema.optional(Schema.Boolean),
194 shortcutLabel: Schema.optional(Schema.String),
195 shortcutMessage: Schema.NullOr(Schema.String),
196 shortcutBinding: Schema.optional(Schema.String),
197 shortcutConfigPath: Schema.optional(Schema.String),
198 shortcutActionRegistered: Schema.optional(Schema.Boolean),
199 gnomeExtension: Schema.optional(DesktopCaptureExtensionState),
200 kdeHelper: Schema.optional(DesktopCaptureHelperState),
201 hyprlandHelper: Schema.optional(DesktopCaptureHelperState),
202 macPermissions: Schema.optional(
203 Schema.Struct({ screenRecording: Schema.Boolean, accessibility: Schema.Boolean }),
204 ),
205 shortcutVerified: Schema.optional(Schema.Boolean),
206 message: Schema.NullOr(Schema.String),
207 });
208 export type DesktopSnapShotState = typeof DesktopSnapShotState.Type;
209
210 export const DesktopSnapShotShortcutAvailability = Schema.Struct({
211 available: Schema.Boolean,
212 message: Schema.NullOr(Schema.String),
213 });
214 export type DesktopSnapShotShortcutAvailability = typeof DesktopSnapShotShortcutAvailability.Type;
215
216 export const DesktopSnapShotId = TrimmedNonEmptyString.check(
217 Schema.isMaxLength(64),
218 Schema.isPattern(/^[a-f0-9-]+$/i),
219 );
220 export type DesktopSnapShotId = typeof DesktopSnapShotId.Type;
221
222 /** `id` is absent for failures before a capture exists. */
223 export const DesktopSnapShotEvent = Schema.Union([
224 Schema.Struct({ type: Schema.Literal("requested"), id: DesktopSnapShotId }),
225 Schema.Struct({ type: Schema.Literal("started"), id: DesktopSnapShotId }),
226 Schema.Struct({ type: Schema.Literal("ready"), id: DesktopSnapShotId }),
227 Schema.Struct({ type: Schema.Literal("failed"), id: Schema.optional(DesktopSnapShotId) }),
228 Schema.Struct({ type: Schema.Literal("shortcut-changed") }),
229 ]);
230 export type DesktopSnapShotEvent = typeof DesktopSnapShotEvent.Type;
231
232 export const DesktopPendingSnapShot = Schema.Struct({
233 id: DesktopSnapShotId,
234 name: Schema.String,
235 mimeType: Schema.Literal("image/png"),
236 sizeBytes: Schema.Int,
237 source: SnapShotSource,
238 });
239 export type DesktopPendingSnapShot = typeof DesktopPendingSnapShot.Type;
240
241 export const DesktopSnapShot = Schema.Struct({
242 ...DesktopPendingSnapShot.fields,
243 dataUrl: Schema.String,
244 });
245 export type DesktopSnapShot = typeof DesktopSnapShot.Type;
246
247 export const DesktopSnapShotAnimationDestination = Schema.Struct({
248 id: DesktopSnapShotId,
249 viewportFrame: Schema.Struct({
250 x: Schema.Number,
251 y: Schema.Number,
252 width: Schema.Number,
253 height: Schema.Number,
254 }),
255 backgroundColor: Schema.String,
256 borderColor: Schema.String,
257 borderWidth: Schema.Number,
258 cornerRadius: Schema.Number,
259 details: Schema.optional(
260 Schema.Struct({
261 appName: SnapShotSource.fields.appName,
262 windowTitle: SnapShotSource.fields.windowTitle,
263 appIconDataUrl: SnapShotSource.fields.appIconDataUrl,
264 }),
265 ),
266 });
267 export type DesktopSnapShotAnimationDestination = typeof DesktopSnapShotAnimationDestination.Type;
268
269 export interface DesktopRuntimeInfo {
270 hostArch: DesktopRuntimeArch;
271 appArch: DesktopRuntimeArch;
272 runningUnderArm64Translation: boolean;
273 }
274
275 export interface DesktopUpdateState {
276 enabled: boolean;
277 status: DesktopUpdateStatus;
278 channel: DesktopUpdateChannel;
279 currentVersion: string;
280 hostArch: DesktopRuntimeArch;
281 appArch: DesktopRuntimeArch;
282 runningUnderArm64Translation: boolean;
283 availableVersion: string | null;
284 downloadedVersion: string | null;
285 releaseNotes: ReadonlyArray<DesktopUpdateReleaseNote>;
286 omittedReleaseCount: number;
287 downloadPercent: number | null;
288 checkedAt: string | null;
289 message: string | null;
290 errorContext: "check" | "download" | "install" | null;
291 canRetry: boolean;
292 notAppliedVersion?: string;
293 /** Off only because a managed policy rules out this channel; switching channels turns it on. */
294 channelBlockedByPolicy?: true;
295 /** The check failed only because this build's track differs from the saved `channel`. */
296 trackMismatch?: { readonly buildChannel: DesktopUpdateChannel };
297 }
298
299 export interface DesktopUpdateReleaseNote {
300 version: string;
301 items: ReadonlyArray<string>;
302 totalItems: number;
303 /** ISO time from the update feed for the offered version, else `YYYY-MM-DD` from a prerelease version. */
304 releasedAt?: string;
305 /** Paragraph-style summaries from older releases keep their fixes in `items`. */
306 intro?: string;
307 /** Generated summaries only, for example "275 changes from 22 contributors". */
308 stats?: string;
309 footer?: string;
310 }
311
312 export const DesktopUpdateReleaseNoteSchema = Schema.Struct({
313 version: Schema.String,
314 items: Schema.Array(Schema.String),
315 totalItems: Schema.Number,
316 releasedAt: Schema.optionalKey(Schema.String),
317 intro: Schema.optionalKey(Schema.String),
318 stats: Schema.optionalKey(Schema.String),
319 footer: Schema.optionalKey(Schema.String),
320 });
321
322 export const DesktopUpdateStateSchema = Schema.Struct({
323 enabled: Schema.Boolean,
324 status: DesktopUpdateStatusSchema,
325 channel: DesktopUpdateChannelSchema,
326 currentVersion: Schema.String,
327 hostArch: DesktopRuntimeArchSchema,
328 appArch: DesktopRuntimeArchSchema,
329 runningUnderArm64Translation: Schema.Boolean,
330 availableVersion: Schema.NullOr(Schema.String),
331 downloadedVersion: Schema.NullOr(Schema.String),
332 releaseNotes: Schema.Array(DesktopUpdateReleaseNoteSchema),
333 omittedReleaseCount: Schema.Number,
334 downloadPercent: Schema.NullOr(Schema.Number),
335 checkedAt: Schema.NullOr(Schema.String),
336 message: Schema.NullOr(Schema.String),
337 errorContext: Schema.NullOr(Schema.Literals(["check", "download", "install"])),
338 canRetry: Schema.Boolean,
339 notAppliedVersion: Schema.optionalKey(Schema.String),
340 channelBlockedByPolicy: Schema.optionalKey(Schema.Literal(true)),
341 trackMismatch: Schema.optionalKey(Schema.Struct({ buildChannel: DesktopUpdateChannelSchema })),
342 });
343
344 export const DesktopCliCommandStateSchema = Schema.Struct({
345 supported: Schema.Boolean,
346 installedPath: Schema.NullOr(Schema.String),
347 onPath: Schema.Boolean,
348 shadowedBy: Schema.optionalKey(Schema.String),
349 /** For an installed `t3` that is off PATH: the shell startup file that adds it, and whether it has. */
350 pathSetup: Schema.optionalKey(Schema.Struct({ file: Schema.String, added: Schema.Boolean })),
351 /** The app's bundled `t3` launcher, which runs without Node or a PATH entry. */
352 launcherPath: Schema.NullOr(Schema.String),
353 });
354 export type DesktopCliCommandState = typeof DesktopCliCommandStateSchema.Type;
355
356 export interface DesktopUpdateActionResult {
357 accepted: boolean;
358 completed: boolean;
359 state: DesktopUpdateState;
360 }
361
362 export const DesktopUpdateActionResultSchema = Schema.Struct({
363 accepted: Schema.Boolean,
364 completed: Schema.Boolean,
365 state: DesktopUpdateStateSchema,
366 });
367
368 export interface DesktopUpdateCheckResult {
369 checked: boolean;
370 state: DesktopUpdateState;
371 }
372
373 export const DesktopUpdateCheckResultSchema = Schema.Struct({
374 checked: Schema.Boolean,
375 state: DesktopUpdateStateSchema,
376 });
377
378 export const PRIMARY_LOCAL_ENVIRONMENT_ID = "primary";
379
380 export interface DesktopEnvironmentBootstrap {
381 // Stable backend identity used to reopen routed projects.
382 id: string;
383 label: string;
384 // Actual distro for this run; id stays wsl:default when tracking the default.
385 runningDistro?: string | null;
386 httpBaseUrl: string | null;
387 wsBaseUrl: string | null;
388 bootstrapToken?: string;
389 }
390
391 export const DesktopEnvironmentBootstrapSchema = Schema.Struct({
392 id: Schema.String,
393 label: Schema.String,
394 runningDistro: Schema.optionalKey(Schema.NullOr(Schema.String)),
395 httpBaseUrl: Schema.NullOr(Schema.String),
396 wsBaseUrl: Schema.NullOr(Schema.String),
397 bootstrapToken: Schema.optionalKey(Schema.String),
398 });
399
400 export const DesktopSshEnvironmentTargetSchema = Schema.Struct({
401 alias: Schema.String,
402 hostname: Schema.String,
403 username: Schema.NullOr(Schema.String),
404 port: Schema.NullOr(Schema.Number),
405 });
406 export type DesktopSshEnvironmentTarget = typeof DesktopSshEnvironmentTargetSchema.Type;
407
408 export type DesktopSshHostSource = "ssh-config" | "known-hosts";
409 export const DesktopSshHostSourceSchema = Schema.Literals(["ssh-config", "known-hosts"]);
410
411 export interface DesktopDiscoveredSshHost extends DesktopSshEnvironmentTarget {
412 source: DesktopSshHostSource;
413 }
414
415 export const DesktopDiscoveredSshHostSchema = Schema.Struct({
416 alias: Schema.String,
417 hostname: Schema.String,
418 username: Schema.NullOr(Schema.String),
419 port: Schema.NullOr(Schema.Number),
420 source: DesktopSshHostSourceSchema,
421 });
422
423 export interface DesktopSshEnvironmentBootstrap {
424 target: DesktopSshEnvironmentTarget;
425 httpBaseUrl: string;
426 wsBaseUrl: string;
427 pairingToken: string | null;
428 remotePort?: number;
429 remoteServerKind?: "external" | "managed";
430 }
431
432 export const DesktopSshEnvironmentBootstrapSchema = Schema.Struct({
433 target: DesktopSshEnvironmentTargetSchema,
434 httpBaseUrl: Schema.String,
435 wsBaseUrl: Schema.String,
436 pairingToken: Schema.NullOr(Schema.String),
437 remotePort: Schema.optionalKey(Schema.Number),
438 remoteServerKind: Schema.optionalKey(Schema.Literals(["external", "managed"])),
439 });
440
441 export interface DesktopSshPasswordPromptRequest {
442 requestId: string;
443 destination: string;
444 username: string | null;
445 prompt: string;
446 expiresAt: string;
447 }
448
449 export const DesktopSshPasswordPromptCancelledType = "ssh-password-prompt-cancelled" as const;
450
451 export const DesktopSshPasswordPromptCancelledResultSchema = Schema.Struct({
452 type: Schema.Literal(DesktopSshPasswordPromptCancelledType),
453 message: Schema.String,
454 });
455
456 export const DesktopSshEnvironmentEnsureOptionsSchema = Schema.Struct({
457 issuePairingToken: Schema.optionalKey(Schema.Boolean),
458 });
459
460 export const DesktopSshEnvironmentEnsureInputSchema = Schema.Struct({
461 target: DesktopSshEnvironmentTargetSchema,
462 options: Schema.optionalKey(DesktopSshEnvironmentEnsureOptionsSchema),
463 });
464
465 export const DesktopSshEnvironmentEnsureResultSchema = Schema.Union([
466 DesktopSshEnvironmentBootstrapSchema,
467 DesktopSshPasswordPromptCancelledResultSchema,
468 ]);
469
470 export const DesktopSshHttpBaseUrlInputSchema = Schema.Struct({
471 httpBaseUrl: Schema.String,
472 });
473
474 export const DesktopSshBearerRequestInputSchema = Schema.Struct({
475 httpBaseUrl: Schema.String,
476 bearerToken: Schema.String,
477 });
478
479 export const DesktopSshBearerBootstrapInputSchema = Schema.Struct({
480 httpBaseUrl: Schema.String,
481 credential: Schema.String,
482 });
483
484 export const DesktopSshPasswordPromptResolutionInputSchema = Schema.Struct({
485 requestId: Schema.String,
486 password: Schema.NullOr(Schema.String),
487 });
488
489 export const PersistedSavedEnvironmentRecordSchema = Schema.Struct({
490 environmentId: EnvironmentId,
491 label: Schema.String,
492 wsBaseUrl: Schema.String,
493 httpBaseUrl: Schema.String,
494 createdAt: Schema.String,
495 lastConnectedAt: Schema.NullOr(Schema.String),
496 desktopSsh: Schema.optionalKey(DesktopSshEnvironmentTargetSchema),
497 relayManaged: Schema.optionalKey(
498 Schema.Struct({
499 relayUrl: Schema.String,
500 }),
501 ),
502 });
503 export type PersistedSavedEnvironmentRecord = typeof PersistedSavedEnvironmentRecordSchema.Type;
504
505 export type DesktopServerExposureMode = "local-only" | "network-accessible";
506
507 export const DesktopServerExposureModeSchema = Schema.Literals([
508 "local-only",
509 "network-accessible",
510 ]);
511
512 export interface DesktopServerExposureState {
513 mode: DesktopServerExposureMode;
514 endpointUrl: string | null;
515 advertisedHost: string | null;
516 tailscaleServeEnabled: boolean;
517 tailscaleServePort: number;
518 }
519
520 export const DesktopServerExposureStateSchema = Schema.Struct({
521 mode: DesktopServerExposureModeSchema,
522 endpointUrl: Schema.NullOr(Schema.String),
523 advertisedHost: Schema.NullOr(Schema.String),
524 tailscaleServeEnabled: Schema.Boolean,
525 tailscaleServePort: Schema.Number,
526 });
527
528 export interface PickFolderOptions {
529 initialPath?: string | null;
530 targetEnvironmentId?: string;
531 }
532
533 export const PickFolderOptionsSchema = Schema.Struct({
534 initialPath: Schema.optionalKey(Schema.NullOr(Schema.String)),
535 targetEnvironmentId: Schema.optionalKey(Schema.String),
536 });
537
538 /** Oversized files have empty text so the main process never loads their contents. */
539 export interface PickedThemeFile {
540 name: string;
541 size: number;
542 text: string;
543 }
544
545 export const PickedThemeFileSchema = Schema.Struct({
546 name: Schema.String,
547 size: Schema.Number,
548 text: Schema.String,
549 });
550
551 export interface DesktopWslDistro {
552 name: string;
553 isDefault: boolean;
554 version: 1 | 2;
555 }
556
557 export const DesktopWslDistroSchema = Schema.Struct({
558 name: Schema.String,
559 isDefault: Schema.Boolean,
560 version: Schema.Literals([1, 2]),
561 });
562
563 export interface DesktopWslState {
564 enabled: boolean;
565 // null means "track the current WSL default distro".
566 distro: string | null;
567 available: boolean;
568 wslOnly: boolean;
569 distros: readonly DesktopWslDistro[];
570 // Always null in wsl-only mode, which falls back to Windows with a dialog.
571 preflightError: string | null;
572 }
573
574 export const DesktopWslStateSchema = Schema.Struct({
575 enabled: Schema.Boolean,
576 distro: Schema.NullOr(Schema.String),
577 available: Schema.Boolean,
578 wslOnly: Schema.Boolean,
579 distros: Schema.Array(DesktopWslDistroSchema),
580 preflightError: Schema.NullOr(Schema.String),
581 });
582
583 export type DesktopPreviewNavStatus =
584 | { kind: "Idle" }
585 | { kind: "Loading"; url: string; title: string }
586 | { kind: "Success"; url: string; title: string }
587 | {
588 kind: "LoadFailed";
589 url: string;
590 title: string;
591 code: number;
592 description: string;
593 };
594
595 export type DesktopPreviewColorScheme = "system" | "light" | "dark";
596
597 export const DesktopPreviewColorSchemeSchema: Schema.Codec<DesktopPreviewColorScheme> =
598 Schema.Literals(["system", "light", "dark"]);
599
600 export const FAVICON_DATA_URL_MAX_LENGTH = 8192;
601 export const FAVICON_CAPTURED_AT_MAX = 8_640_000_000_000_000;
602
603 export interface DesktopPreviewFavicon {
604 dataUrl: string;
605 pageUrl: string;
606 capturedAt: number;
607 }
608
609 export interface DesktopPreviewTabState {
610 tabId: string;
611 webContentsId: number | null;
612 navStatus: DesktopPreviewNavStatus;
613 canGoBack: boolean;
614 canGoForward: boolean;
615 zoomFactor: number;
616 pictureInPicture: boolean;
617 colorScheme: DesktopPreviewColorScheme;
618 audioMuted: boolean;
619 /** Chromium reports playback even when audioMuted is true. */
620 audible: boolean;
621 controller: "human" | "agent" | "none";
622 /** A screenshot or stream of the guest is pending, so the client keeps it painting while hidden. */
623 capturing: boolean;
624 favicon?: DesktopPreviewFavicon;
625 updatedAt: string;
626 }
627
628 export const DesktopPreviewTabIdSchema = Schema.String.check(Schema.isTrimmed()).check(
629 Schema.isNonEmpty(),
630 );
631
632 export interface DesktopPreviewPointerEvent {
633 tabId: string;
634 phase: "move" | "click";
635 x: number;
636 y: number;
637 sequence: number;
638 createdAt: string;
639 }
640
641 export interface DesktopPreviewOpenLinkEvent {
642 tabId: string;
643 url: string;
644 background: boolean;
645 }
646
647 export interface DesktopPreviewFindResultEvent {
648 tabId: string;
649 activeMatchOrdinal: number;
650 matches: number;
651 }
652
653 export const DesktopPreviewRecordingInputSchema = Schema.Union([
654 Schema.Struct({
655 type: Schema.Literal("pointer"),
656 phase: Schema.Literals(["move", "down", "up", "click"]),
657 x: Schema.Finite,
658 y: Schema.Finite,
659 width: Schema.Finite.check(Schema.isGreaterThan(0)),
660 height: Schema.Finite.check(Schema.isGreaterThan(0)),
661 }),
662 Schema.Struct({
663 type: Schema.Literal("key"),
664 label: Schema.NullOr(Schema.String.check(Schema.isMaxLength(100))),
665 held: Schema.Boolean,
666 width: Schema.Finite.check(Schema.isGreaterThan(0)),
667 }),
668 Schema.Struct({ type: Schema.Literal("clear") }),
669 ]);
670 export type DesktopPreviewRecordingInput = typeof DesktopPreviewRecordingInputSchema.Type;
671 export interface DesktopPreviewRecordingInputEvent {
672 readonly tabId: string;
673 readonly input: DesktopPreviewRecordingInput;
674 }
675
676 export interface DesktopPreviewWebviewConfig {
677 partition: string;
678 /** Sandboxed with contextIsolation off so the picker preload can read the React DevTools hook. */
679 webPreferences: string;
680 /** Absolute file:// preload URL; null requires disabling element picking. */
681 preloadUrl: string | null;
682 }
683
684 export const DesktopPreviewWebviewConfigSchema: Schema.Codec<DesktopPreviewWebviewConfig> =
685 Schema.Struct({
686 partition: Schema.String,
687 webPreferences: Schema.String,
688 preloadUrl: Schema.NullOr(Schema.String),
689 });
690
691 export interface DesktopPreviewAnnotationTheme {
692 colorScheme: "light" | "dark";
693 radius: string;
694 background: string;
695 foreground: string;
696 popover: string;
697 popoverForeground: string;
698 primary: string;
699 primaryForeground: string;
700 muted: string;
701 mutedForeground: string;
702 accent: string;
703 accentForeground: string;
704 border: string;
705 input: string;
706 ring: string;
707 fontSans: string;
708 fontMono: string;
709 }
710
711 export const DesktopPreviewAnnotationThemeSchema: Schema.Codec<DesktopPreviewAnnotationTheme> =
712 Schema.Struct({
713 colorScheme: Schema.Literals(["light", "dark"]),
714 radius: Schema.String,
715 background: Schema.String,
716 foreground: Schema.String,
717 popover: Schema.String,
718 popoverForeground: Schema.String,
719 primary: Schema.String,
720 primaryForeground: Schema.String,
721 muted: Schema.String,
722 mutedForeground: Schema.String,
723 accent: Schema.String,
724 accentForeground: Schema.String,
725 border: Schema.String,
726 input: Schema.String,
727 ring: Schema.String,
728 fontSans: Schema.String,
729 fontMono: Schema.String,
730 });
731
732 export interface DesktopPreviewRecordingFrame {
733 tabId: string;
734 data: string;
735 width: number;
736 height: number;
737 receivedAt: string;
738 }
739
740 export interface DesktopPreviewRecordingArtifact {
741 id: string;
742 tabId: string;
743 path: string;
744 mimeType: string;
745 sizeBytes: number;
746 createdAt: string;
747 }
748
749 export const DesktopPreviewRecordingArtifactSchema: Schema.Codec<DesktopPreviewRecordingArtifact> =
750 Schema.Struct({
751 id: Schema.String,
752 tabId: DesktopPreviewTabIdSchema,
753 path: Schema.String,
754 mimeType: Schema.String,
755 sizeBytes: Schema.Int,
756 createdAt: Schema.String,
757 });
758
759 export interface DesktopPreviewScreenshotArtifact {
760 id: string;
761 tabId: string;
762 path: string;
763 mimeType: "image/png";
764 sizeBytes: number;
765 createdAt: string;
766 }
767
768 export const DesktopPreviewScreenshotArtifactSchema: Schema.Codec<DesktopPreviewScreenshotArtifact> =
769 Schema.Struct({
770 id: Schema.String,
771 tabId: DesktopPreviewTabIdSchema,
772 path: Schema.String,
773 mimeType: Schema.Literal("image/png"),
774 sizeBytes: Schema.Int,
775 createdAt: Schema.String,
776 });
777
778 export interface PickedElementStackFrame {
779 functionName: string | null;
780 fileName: string | null;
781 lineNumber: number | null;
782 columnNumber: number | null;
783 }
784
785 export const PickedElementStackFrameSchema: Schema.Codec<PickedElementStackFrame> = Schema.Struct({
786 functionName: Schema.NullOr(Schema.String),
787 fileName: Schema.NullOr(Schema.String),
788 lineNumber: Schema.NullOr(Schema.Number),
789 columnNumber: Schema.NullOr(Schema.Number),
790 });
791
792 export interface PickedElementPayload {
793 pageUrl: string;
794 pageTitle: string | null;
795 tagName: string;
796 selector: string | null;
797 htmlPreview: string;
798 componentName: string | null;
799 source: PickedElementStackFrame | null;
800 stack: ReadonlyArray<PickedElementStackFrame>;
801 styles: string;
802 pickedAt: string;
803 }
804
805 export const PickedElementPayloadSchema: Schema.Codec<PickedElementPayload> = Schema.Struct({
806 pageUrl: Schema.String,
807 pageTitle: Schema.NullOr(Schema.String),
808 tagName: Schema.String,
809 selector: Schema.NullOr(Schema.String),
810 htmlPreview: Schema.String,
811 componentName: Schema.NullOr(Schema.String),
812 source: Schema.NullOr(PickedElementStackFrameSchema),
813 stack: Schema.Array(PickedElementStackFrameSchema),
814 styles: Schema.String,
815 pickedAt: Schema.String,
816 });
817
818 export interface PreviewAnnotationRect {
819 x: number;
820 y: number;
821 width: number;
822 height: number;
823 }
824
825 export const PreviewAnnotationRectSchema: Schema.Codec<PreviewAnnotationRect> = Schema.Struct({
826 x: Schema.Number,
827 y: Schema.Number,
828 width: Schema.Number,
829 height: Schema.Number,
830 });
831
832 export interface PreviewAnnotationPoint {
833 x: number;
834 y: number;
835 }
836
837 export const PreviewAnnotationPointSchema: Schema.Codec<PreviewAnnotationPoint> = Schema.Struct({
838 x: Schema.Number,
839 y: Schema.Number,
840 });
841
842 export interface PreviewAnnotationElementTarget {
843 id: string;
844 element: PickedElementPayload;
845 rect: PreviewAnnotationRect;
846 }
847
848 export const PreviewAnnotationElementTargetSchema: Schema.Codec<PreviewAnnotationElementTarget> =
849 Schema.Struct({
850 id: Schema.String,
851 element: PickedElementPayloadSchema,
852 rect: PreviewAnnotationRectSchema,
853 });
854
855 export interface PreviewAnnotationRegionTarget {
856 id: string;
857 rect: PreviewAnnotationRect;
858 }
859
860 export const PreviewAnnotationRegionTargetSchema: Schema.Codec<PreviewAnnotationRegionTarget> =
861 Schema.Struct({
862 id: Schema.String,
863 rect: PreviewAnnotationRectSchema,
864 });
865
866 export interface PreviewAnnotationStrokeTarget {
867 id: string;
868 color: string;
869 width: number;
870 points: ReadonlyArray<PreviewAnnotationPoint>;
871 bounds: PreviewAnnotationRect;
872 }
873
874 export const PreviewAnnotationStrokeTargetSchema: Schema.Codec<PreviewAnnotationStrokeTarget> =
875 Schema.Struct({
876 id: Schema.String,
877 color: Schema.String,
878 width: Schema.Number,
879 points: Schema.Array(PreviewAnnotationPointSchema),
880 bounds: PreviewAnnotationRectSchema,
881 });
882
883 export interface PreviewAnnotationStyleChange {
884 targetId: string;
885 selector: string | null;
886 property: string;
887 previousValue: string;
888 value: string;
889 }
890
891 export const PreviewAnnotationStyleChangeSchema: Schema.Codec<PreviewAnnotationStyleChange> =
892 Schema.Struct({
893 targetId: Schema.String,
894 selector: Schema.NullOr(Schema.String),
895 property: Schema.String,
896 previousValue: Schema.String,
897 value: Schema.String,
898 });
899
900 export interface PreviewAnnotationScreenshot {
901 dataUrl: string;
902 width: number;
903 height: number;
904 cropRect: PreviewAnnotationRect;
905 }
906
907 export const PreviewAnnotationScreenshotSchema: Schema.Codec<PreviewAnnotationScreenshot> =
908 Schema.Struct({
909 dataUrl: Schema.String,
910 width: Schema.Number,
911 height: Schema.Number,
912 cropRect: PreviewAnnotationRectSchema,
913 });
914
915 export interface PreviewAnnotationPayload {
916 id: string;
917 pageUrl: string;
918 pageTitle: string | null;
919 comment: string;
920 elements: ReadonlyArray<PreviewAnnotationElementTarget>;
921 regions: ReadonlyArray<PreviewAnnotationRegionTarget>;
922 strokes: ReadonlyArray<PreviewAnnotationStrokeTarget>;
923 styleChanges: ReadonlyArray<PreviewAnnotationStyleChange>;
924 screenshot: PreviewAnnotationScreenshot | null;
925 createdAt: string;
926 }
927
928 export const PreviewAnnotationPayloadSchema: Schema.Codec<PreviewAnnotationPayload> = Schema.Struct(
929 {
930 id: Schema.String,
931 pageUrl: Schema.String,
932 pageTitle: Schema.NullOr(Schema.String),
933 comment: Schema.String,
934 elements: Schema.Array(PreviewAnnotationElementTargetSchema),
935 regions: Schema.Array(PreviewAnnotationRegionTargetSchema),
936 strokes: Schema.Array(PreviewAnnotationStrokeTargetSchema),
937 styleChanges: Schema.Array(PreviewAnnotationStyleChangeSchema),
938 screenshot: Schema.NullOr(PreviewAnnotationScreenshotSchema),
939 createdAt: Schema.String,
940 },
941 );
942
943 export type PreviewAnnotationSubmission = "attach" | "send";
944 export const PreviewAnnotationSubmissionSchema: Schema.Codec<PreviewAnnotationSubmission> =
945 Schema.Literals(["attach", "send"]);
946
947 export interface PreviewAnnotationSubmissionResult {
948 annotation: PreviewAnnotationPayload;
949 submission: PreviewAnnotationSubmission;
950 screenshotFailed?: boolean;
951 }
952 export const PreviewAnnotationSubmissionResultSchema: Schema.Codec<PreviewAnnotationSubmissionResult> =
953 Schema.Struct({
954 annotation: PreviewAnnotationPayloadSchema,
955 submission: PreviewAnnotationSubmissionSchema,
956 screenshotFailed: Schema.optionalKey(Schema.Boolean),
957 });
958
959 export const DesktopPreviewTabInputSchema = Schema.Struct({
960 tabId: DesktopPreviewTabIdSchema,
961 });
962
963 /** Apply zoom and color scheme at creation to avoid flashing browser defaults. */
964 export const DesktopPreviewCreateTabInputSchema = Schema.Struct({
965 tabId: DesktopPreviewTabIdSchema,
966 zoomFactor: Schema.optional(Schema.Number.check(Schema.isGreaterThan(0))),
967 colorScheme: Schema.optional(DesktopPreviewColorSchemeSchema),
968 serverTab: Schema.optional(
969 Schema.Struct({ threadId: TrimmedNonEmptyString, tabId: TrimmedNonEmptyString }),
970 ),
971 });
972
973 export interface DesktopPreviewTabDefaults {
974 readonly zoomFactor?: number | undefined;
975 readonly colorScheme?: DesktopPreviewColorScheme | undefined;
976 readonly serverTab?: { readonly threadId: string; readonly tabId: string } | undefined;
977 }
978
979 export const DesktopPreviewRegisterWebviewInputSchema = Schema.Struct({
980 tabId: DesktopPreviewTabIdSchema,
981 webContentsId: Schema.Int.check(Schema.isGreaterThan(0)),
982 });
983
984 export const DesktopPreviewNavigateInputSchema = Schema.Struct({
985 tabId: DesktopPreviewTabIdSchema,
986 url: Schema.String,
987 });
988
989 export const DesktopPreviewConfigInputSchema = Schema.Struct({
990 environmentId: EnvironmentId,
991 /** Main must derive the partition to ensure its session has UA rewrites and permission handlers. */
992 profileId: Schema.optional(BrowserProfileId),
993 /** Carry the partition's loopback traffic to the environment instead of this machine. */
994 tunnelLoopback: Schema.optional(Schema.Boolean),
995 });
996
997 export interface DesktopPreviewTunnelAccessRequest {
998 readonly requestId: string;
999 readonly environmentId: EnvironmentId;
1000 }
1001
1002 export const DesktopPreviewTunnelAccessResolutionInputSchema = Schema.Struct({
1003 requestId: Schema.String,
1004 /** The environment's tunnel WebSocket URL with its ticket, or null when it cannot be reached. */
1005 url: Schema.NullOr(Schema.String),
1006 });
1007
1008 /** A loopback port of another environment, reachable on this machine's 127.0.0.1. */
1009 export const DesktopPortForwardSchema = Schema.Struct({
1010 environmentId: EnvironmentId,
1011 remotePort: PortSchema,
1012 /** The same as `remotePort` unless that port was taken here. */
1013 localPort: PortSchema,
1014 });
1015 export type DesktopPortForward = typeof DesktopPortForwardSchema.Type;
1016
1017 export const DesktopSharesLoopbackInputSchema = Schema.Struct({ environmentId: EnvironmentId });
1018
1019 export const DesktopPortForwardInputSchema = Schema.Struct({
1020 environmentId: EnvironmentId,
1021 remotePort: PortSchema,
1022 });
1023
1024 export const DesktopPreviewClearDataInputSchema = Schema.Struct({
1025 environmentId: EnvironmentId,
1026 /** Omit to clear every profile; otherwise only this profile's partition. */
1027 profileId: Schema.optional(BrowserProfileId),
1028 });
1029
1030 export const DesktopPreviewSetColorSchemeInputSchema = Schema.Struct({
1031 tabId: DesktopPreviewTabIdSchema,
1032 colorScheme: DesktopPreviewColorSchemeSchema,
1033 });
1034
1035 export const DesktopPreviewSetZoomFactorInputSchema = Schema.Struct({
1036 tabId: DesktopPreviewTabIdSchema,
1037 zoomFactor: Schema.Number.check(Schema.isGreaterThan(0)),
1038 });
1039
1040 export const DesktopPreviewFindInPageInputSchema = Schema.Struct({
1041 tabId: DesktopPreviewTabIdSchema,
1042 text: Schema.NonEmptyString.check(Schema.isMaxLength(1000)),
1043 forward: Schema.Boolean,
1044 newSession: Schema.Boolean,
1045 });
1046
1047 export const DesktopPreviewSetAudioMutedInputSchema = Schema.Struct({
1048 tabId: DesktopPreviewTabIdSchema,
1049 audioMuted: Schema.Boolean,
1050 });
1051
1052 export const DesktopPreviewSetShownInputSchema = Schema.Struct({
1053 tabId: DesktopPreviewTabIdSchema,
1054 shown: Schema.Boolean,
1055 });
1056
1057 export const DesktopPreviewSetCaptureDrawnInputSchema = Schema.Struct({
1058 tabId: DesktopPreviewTabIdSchema,
1059 drawn: Schema.Boolean,
1060 });
1061
1062 export const DesktopPreviewAnnotationThemeInputSchema = Schema.Struct({
1063 theme: DesktopPreviewAnnotationThemeSchema,
1064 });
1065
1066 export const DesktopPreviewAnnotationSendEnabledInputSchema = Schema.Struct({
1067 tabId: DesktopPreviewTabIdSchema,
1068 enabled: Schema.Boolean,
1069 });
1070
1071 export const DesktopPreviewArtifactInputSchema = Schema.Struct({
1072 path: Schema.String.check(Schema.isTrimmed()).check(Schema.isNonEmpty()),
1073 });
1074
1075 export const DesktopPreviewRecordingSaveInputSchema = Schema.Struct({
1076 tabId: DesktopPreviewTabIdSchema,
1077 mimeType: Schema.String.check(Schema.isTrimmed()).check(Schema.isNonEmpty()),
1078 data: Schema.Uint8Array,
1079 });
1080
1081 export const DesktopMediaReadSchema = Schema.Struct({
1082 status: Schema.Number,
1083 mimeType: Schema.String,
1084 data: Schema.Uint8Array,
1085 });
1086 export type DesktopMediaRead = typeof DesktopMediaReadSchema.Type;
1087
1088 /** `value` is the resolved locale from `prepare` and the transcript from `transcribe`. */
1089 export const DesktopAppleSpeechResultSchema = Schema.Union([
1090 Schema.Struct({ ok: Schema.Literal(true), value: Schema.String }),
1091 Schema.Struct({
1092 ok: Schema.Literal(false),
1093 code: Schema.Literals(["unavailable", "unsupported-locale", "failed"]),
1094 }),
1095 ]);
1096 export type DesktopAppleSpeechResult = typeof DesktopAppleSpeechResultSchema.Type;
1097
1098 export const DesktopAppleSpeechTranscribeInputSchema = Schema.Struct({
1099 locale: Schema.String.check(Schema.isMaxLength(64)),
1100 // 16 kHz mono Float32 PCM, at most five minutes.
1101 pcm: Schema.Uint8Array,
1102 });
1103
1104 export const SystemSettingsPaneSchema = Schema.Literals(["full-disk-access"]);
1105 export type SystemSettingsPane = typeof SystemSettingsPaneSchema.Type;
1106
1107 export interface DesktopBridge {
1108 getAppBranding: () => DesktopAppBranding | null;
1109 /** `null` until the desktop host has read the login shell's environment; ask again later. */
1110 getRelayTelemetryEnabled: () => boolean | null;
1111 getPathForFile: (file: File) => string;
1112 getClientPlatform: () => string;
1113 restartAudioService?: () => Promise<boolean>;
1114 setNotificationBadge: (badge: { count: number; image: string | null }) => Promise<void>;
1115 onNotificationBadgeClear: (listener: () => void) => () => void;
1116 onTrackpadScrollBegin: (listener: () => void) => () => void;
1117 onTrackpadScrollEnd: (listener: () => void) => () => void;
1118 /**
1119 * Renderer `window.focus()` cannot raise an Electron window, and on Wayland
1120 * only the main process can spend a notification click's activation token.
1121 */
1122 revealWindow: () => Promise<void>;
1123 /**
1124 * The OS locale as a BCP-47 tag, which the renderer cannot read for itself:
1125 * the packaged app ships only the `en-US` Chromium locale pak, so
1126 * `navigator.language` and the default `Intl` locale are pinned to `en-US`
1127 * regardless of OS settings.
1128 */
1129 getSystemLocale: () => string | null;
1130 /** The OS's preferred languages, most preferred first; `navigator.languages` is pinned like the locale. */
1131 getPreferredSystemLanguages: () => readonly string[];
1132 /** False when the OS turned off middle-click PRIMARY paste (`gtk-enable-primary-paste`). */
1133 getPrimaryPasteEnabled?: () => boolean;
1134 getLocalEnvironmentBootstraps: () => readonly DesktopEnvironmentBootstrap[];
1135 getLocalEnvironmentEnabled: () => boolean;
1136 setLocalEnvironmentEnabled: (enabled: boolean) => Promise<void>;
1137 /** The environment ID recorded in this app's T3 home, such as its own machine's background service. */
1138 getHostEnvironmentId?: () => Promise<string | null>;
1139 getLocalEnvironmentBearerToken: () => Promise<string>;
1140 getClientSettings: () => Promise<ClientSettings | null>;
1141 setClientSettings: (settings: ClientSettings) => Promise<void>;
1142 getConnectionCatalog: () => Promise<string | null>;
1143 setConnectionCatalog: (catalog: string) => Promise<boolean>;
1144 discoverSshHosts: () => Promise<readonly DesktopDiscoveredSshHost[]>;
1145 resolveSshHost: (alias: string) => Promise<DesktopSshEnvironmentTarget>;
1146 requestSnapShotPermissions: (includeAccessibility: boolean) => Promise<void>;
1147 getSnapShotState: () => Promise<DesktopSnapShotState>;
1148 setupSnapShot: (action: DesktopSnapShotSetupAction) => Promise<void>;
1149 previewSnapShotConfig: (
1150 request: DesktopCaptureConfigRequest,
1151 ) => Promise<DesktopCaptureConfigPreview | null>;
1152 applySnapShotConfig: (previewId: string) => Promise<DesktopCaptureConfigApplied>;
1153 checkSnapShotShortcut: (
1154 shortcut: SnapShotShortcut,
1155 ) => Promise<DesktopSnapShotShortcutAvailability>;
1156 setSnapShotShortcutSuppressed: (suppressed: boolean) => Promise<void>;
1157 listPendingSnapShots: () => Promise<readonly DesktopPendingSnapShot[]>;
1158 readSnapShot: (id: string) => Promise<DesktopSnapShot>;
1159 setSnapShotAnimationDestination: (
1160 destination: DesktopSnapShotAnimationDestination,
1161 ) => Promise<void>;
1162 dismissSnapShotAnimation: (id: DesktopSnapShotId) => Promise<void>;
1163 acknowledgeSnapShot: (id: string) => Promise<void>;
1164 ensureSshEnvironment: (
1165 target: DesktopSshEnvironmentTarget,
1166 options?: { issuePairingToken?: boolean },
1167 ) => Promise<DesktopSshEnvironmentBootstrap>;
1168 disconnectSshEnvironment: (target: DesktopSshEnvironmentTarget) => Promise<void>;
1169 fetchSshEnvironmentDescriptor: (httpBaseUrl: string) => Promise<ExecutionEnvironmentDescriptor>;
1170 bootstrapSshBearerSession: (
1171 httpBaseUrl: string,
1172 credential: string,
1173 ) => Promise<AuthAccessTokenResult>;
1174 fetchSshSessionState: (httpBaseUrl: string, bearerToken: string) => Promise<AuthSessionState>;
1175 onSshPasswordPrompt: (listener: (request: DesktopSshPasswordPromptRequest) => void) => () => void;
1176 /** Fires with a prompt's request id once it is answered, cancelled, expired or abandoned. */
1177 onSshPasswordPromptSettled: (listener: (requestId: string) => void) => () => void;
1178 resolveSshPasswordPrompt: (requestId: string, password: string | null) => Promise<void>;
1179 getServerExposureState: () => Promise<DesktopServerExposureState>;
1180 setServerExposureMode: (mode: DesktopServerExposureMode) => Promise<DesktopServerExposureState>;
1181 setTailscaleServeEnabled: (input: {
1182 readonly enabled: boolean;
1183 readonly port?: number;
1184 }) => Promise<DesktopServerExposureState>;
1185 getAdvertisedEndpoints: () => Promise<readonly AdvertisedEndpoint[]>;
1186 getWslState: () => Promise<DesktopWslState>;
1187 setWslBackendEnabled: (enabled: boolean) => Promise<DesktopWslState>;
1188 setWslDistro: (distro: string | null) => Promise<DesktopWslState>;
1189 setWslOnly: (enabled: boolean) => Promise<DesktopWslState>;
1190 pickFolder: (options?: PickFolderOptions) => Promise<string | null>;
1191 /** Maps a Windows path to the one a local backend (`primary` or `wsl:…`) sees; null when it cannot. */
1192 toLocalBackendPath: (backendId: string, windowsPath: string) => Promise<string | null>;
1193 pickProjectFavicon: (initialPath?: string) => Promise<string | null>;
1194 pickThemeFiles: () => Promise<readonly PickedThemeFile[] | null>;
1195 setTheme: (theme: DesktopTheme) => Promise<void>;
1196 showContextMenu: <T extends string>(
1197 items: readonly ContextMenuItem<T>[],
1198 position?: { x: number; y: number },
1199 source?: ContextMenuSource,
1200 ) => Promise<T | null>;
1201 receiveProviderAuthCallback: (authorizationUrl: string) => Promise<string>;
1202 cancelProviderAuthCallback: (authorizationUrl: string) => Promise<void>;
1203 startFileDrag: (input: { environmentId: EnvironmentId; path: string }) => Promise<boolean>;
1204 openExternal: (url: string) => Promise<boolean>;
1205 /** Reads http(s) media in the main process, outside renderer CORS and CSP; null on network failure. */
1206 readMedia: (url: string) => Promise<DesktopMediaRead | null>;
1207 openSystemSettings: (pane: SystemSettingsPane) => Promise<boolean>;
1208 checkSystemPermission: (pane: SystemSettingsPane) => Promise<boolean>;
1209 probeRemoteEditors: () => Promise<readonly EditorId[]>;
1210 pasteAsText: () => Promise<void>;
1211 onMenuAction: (listener: (action: string) => void) => () => void;
1212 onSnapShotEvent: (listener: (event: DesktopSnapShotEvent) => void) => () => void;
1213 onQuitShortcut: (listener: (event: QuitShortcutHintEvent) => void) => () => void;
1214 getWindowFullscreenState: () => boolean;
1215 onWindowFullscreenStateChange: (listener: (fullscreen: boolean) => void) => () => void;
1216 getWindowZoomFactor: () => number;
1217 getUpdateState: () => Promise<DesktopUpdateState>;
1218 /** `minimumVersion` is a track switch's checked release; nothing older is offered after. */
1219 setUpdateChannel: (
1220 channel: DesktopUpdateChannel,
1221 minimumVersion?: string,
1222 ) => Promise<DesktopUpdateState>;
1223 checkForUpdate: () => Promise<DesktopUpdateCheckResult>;
1224 downloadUpdate: () => Promise<DesktopUpdateActionResult>;
1225 /** With a version, installs only that downloaded build. */
1226 installUpdate: (expectedVersion?: string) => Promise<DesktopUpdateActionResult>;
1227 onUpdateState: (listener: (state: DesktopUpdateState) => void) => () => void;
1228 cliCommand: {
1229 getState: () => Promise<DesktopCliCommandState>;
1230 install: () => Promise<DesktopCliCommandState>;
1231 uninstall: () => Promise<DesktopCliCommandState>;
1232 addToPath: () => Promise<DesktopCliCommandState>;
1233 };
1234 webLinks: {
1235 setReady: (ready: boolean) => Promise<void>;
1236 onOpen: (listener: (url: string) => void) => () => void;
1237 };
1238 appActivation: {
1239 setReady: (ready: boolean) => Promise<void>;
1240 complete: (response: DesktopAppActivationResponse) => Promise<void>;
1241 onRequest: (listener: (request: DesktopAppActivationRequest) => void) => () => void;
1242 };
1243 preview: DesktopPreviewBridge;
1244 /** On-device dictation through macOS 26 SpeechAnalyzer; absent in older desktop builds. */
1245 appleSpeech?: {
1246 supportedLocales: () => Promise<readonly string[]>;
1247 prepare: (locale: string) => Promise<DesktopAppleSpeechResult>;
1248 transcribe: (input: { locale: string; pcm: Uint8Array }) => Promise<DesktopAppleSpeechResult>;
1249 };
1250 }
1251
1252 /** Renderer callback invoked by Electron with a fresh user gesture before display-media capture. */
1253 export const DESKTOP_PREVIEW_RECORDING_CAPTURE_TRIGGER = "__t3DesktopPreviewRecordingCapture";
1254
1255 /**
1256 * Dictation for the annotation editor drawn inside a preview guest. The guest only shows
1257 * controls and forwards trusted user gestures; the renderer records, with its consent
1258 * checks, and publishes state back. `shortcuts` are the dictation chords in effect.
1259 */
1260 export const DesktopPreviewAnnotationVoiceConfigSchema = Schema.Struct({
1261 sessionId: Schema.String.check(Schema.isMaxLength(64)),
1262 shortcuts: Schema.Array(KeybindingShortcut).check(Schema.isMaxLength(16)),
1263 });
1264 export type DesktopPreviewAnnotationVoiceConfig =
1265 typeof DesktopPreviewAnnotationVoiceConfigSchema.Type;
1266
1267 export const DesktopPreviewAnnotationVoiceEventSchema = Schema.Struct({
1268 sessionId: Schema.String.check(Schema.isMaxLength(64)),
1269 text: Schema.String.check(Schema.isMaxLength(100_000)),
1270 cursor: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
1271 selectionEnd: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
1272 action: Schema.Literals([
1273 "sync",
1274 "start",
1275 "stop",
1276 "cancel",
1277 "skip",
1278 "settings",
1279 "key",
1280 "focus",
1281 "blur",
1282 ]),
1283 keyboard: Schema.optional(
1284 Schema.Struct({
1285 type: Schema.Literals(["keydown", "keyup"]),
1286 key: Schema.String.check(Schema.isMaxLength(32)),
1287 code: Schema.String.check(Schema.isMaxLength(64)),
1288 metaKey: Schema.Boolean,
1289 ctrlKey: Schema.Boolean,
1290 shiftKey: Schema.Boolean,
1291 altKey: Schema.Boolean,
1292 repeat: Schema.Boolean,
1293 }),
1294 ),
1295 });
1296 export type DesktopPreviewAnnotationVoiceEvent =
1297 typeof DesktopPreviewAnnotationVoiceEventSchema.Type;
1298
1299 export const DesktopPreviewAnnotationVoiceStateSchema = Schema.Struct({
1300 tabId: DesktopPreviewTabIdSchema,
1301 sessionId: Schema.String.check(Schema.isMaxLength(64)),
1302 available: Schema.Boolean,
1303 phase: Schema.Literals([
1304 "idle",
1305 "preparing",
1306 "recording",
1307 "transcribing",
1308 "post-processing",
1309 "error",
1310 ]),
1311 status: Schema.NullOr(Schema.String),
1312 errorAction: Schema.NullOr(Schema.Literals(["retry", "settings"])),
1313 preview: Schema.NullOr(Schema.String),
1314 level: Schema.Number,
1315 shortcutLabel: Schema.NullOr(Schema.String),
1316 freezesEditor: Schema.Boolean,
1317 blocksSubmission: Schema.Boolean,
1318 draft: Schema.NullOr(Schema.Struct({ text: Schema.String, cursor: Schema.Int })),
1319 });
1320 export type DesktopPreviewAnnotationVoiceState =
1321 typeof DesktopPreviewAnnotationVoiceStateSchema.Type;
1322
1323 export const DesktopPreviewPickElementInputSchema = Schema.Struct({
1324 tabId: DesktopPreviewTabIdSchema,
1325 voice: Schema.optional(DesktopPreviewAnnotationVoiceConfigSchema),
1326 });
1327
1328 export interface DesktopPreviewBridge {
1329 setForwardedShortcuts: (shortcuts: ReadonlyArray<PreviewForwardedShortcut>) => Promise<void>;
1330 createTab: (tabId: string, defaults?: DesktopPreviewTabDefaults) => Promise<void>;
1331 closeTab: (tabId: string) => Promise<void>;
1332 registerWebview: (tabId: string, webContentsId: number) => Promise<void>;
1333 navigate: (tabId: string, url: string) => Promise<void>;
1334 goBack: (tabId: string) => Promise<void>;
1335 goForward: (tabId: string) => Promise<void>;
1336 refresh: (tabId: string) => Promise<void>;
1337 stopLoading: (tabId: string) => Promise<void>;
1338 zoomIn: (tabId: string) => Promise<void>;
1339 zoomOut: (tabId: string) => Promise<void>;
1340 resetZoom: (tabId: string) => Promise<void>;
1341 setZoomFactor: (tabId: string, zoomFactor: number) => Promise<void>;
1342 hardReload: (tabId: string) => Promise<void>;
1343 setColorScheme: (tabId: string, colorScheme: DesktopPreviewColorScheme) => Promise<void>;
1344 setAudioMuted: (tabId: string, audioMuted: boolean) => Promise<void>;
1345 findInPage: (
1346 tabId: string,
1347 text: string,
1348 options: { forward: boolean; newSession: boolean },
1349 ) => Promise<void>;
1350 stopFindInPage: (tabId: string) => Promise<void>;
1351 /** Tells the tab's server whether its webview is on screen. */
1352 setShown: (tabId: string, shown: boolean) => Promise<void>;
1353 /** Tells the tab's server whether its webview is drawn at full detail for a capture. */
1354 setCaptureDrawn: (tabId: string, drawn: boolean) => Promise<void>;
1355 openDevTools: (tabId: string) => Promise<void>;
1356 clearCookies: (environmentId: EnvironmentId, profileId?: string) => Promise<void>;
1357 clearCache: (environmentId: EnvironmentId, profileId?: string) => Promise<void>;
1358 getPreviewConfig: (
1359 environmentId: EnvironmentId,
1360 profileId?: string,
1361 tunnelLoopback?: boolean,
1362 ) => Promise<DesktopPreviewWebviewConfig>;
1363 /** Main asks for an environment's tunnel URL once per connection a tunnelled page opens. */
1364 onTunnelAccessRequest: (
1365 listener: (request: DesktopPreviewTunnelAccessRequest) => void,
1366 ) => () => void;
1367 resolveTunnelAccess: (requestId: string, url: string | null) => Promise<void>;
1368 /** Forwards an environment's loopback port to this machine until stopped or the app quits. */
1369 forwardPort: (environmentId: EnvironmentId, remotePort: number) => Promise<DesktopPortForward>;
1370 stopPortForward: (environmentId: EnvironmentId, remotePort: number) => Promise<void>;
1371 listPortForwards: () => Promise<ReadonlyArray<DesktopPortForward>>;
1372 /** Whether the environment runs on this machine, where its ports need no forward. */
1373 sharesLoopback: (environmentId: EnvironmentId) => Promise<boolean>;
1374 onPortForwards: (listener: (forwards: ReadonlyArray<DesktopPortForward>) => void) => () => void;
1375 listBrowserImportSources: () => Promise<ReadonlyArray<BrowserImportSource>>;
1376 importBrowserCookies: (input: {
1377 readonly environmentId: EnvironmentId;
1378 readonly sourceId: BrowserImportSourceId;
1379 readonly sourceProfileDirectory: string;
1380 readonly targetProfileId: string;
1381 }) => Promise<BrowserImportResult>;
1382 setAnnotationTheme: (theme: DesktopPreviewAnnotationTheme) => Promise<void>;
1383 setAnnotationSendEnabled: (tabId: string, enabled: boolean) => Promise<void>;
1384 annotationVoice: {
1385 onEvent: (
1386 listener: (tabId: string, event: DesktopPreviewAnnotationVoiceEvent) => void,
1387 ) => () => void;
1388 update: (state: DesktopPreviewAnnotationVoiceState) => Promise<void>;
1389 };
1390 /** Resolves with the annotation and attach/send intent, or null on cancellation. Rejects if activation fails. */
1391 pickElement: (
1392 tabId: string,
1393 voice?: DesktopPreviewAnnotationVoiceConfig,
1394 ) => Promise<PreviewAnnotationSubmissionResult | null>;
1395 cancelPickElement: (tabId: string) => Promise<void>;
1396 captureScreenshot: (
1397 tabId: string,
1398 ) => Promise<DesktopPreviewScreenshotArtifact | PreviewCaptureFailureEncoded>;
1399 revealArtifact: (path: string) => Promise<void>;
1400 copyArtifactToClipboard: (path: string) => Promise<void>;
1401 pictureInPicture: {
1402 open: (tabId: string) => Promise<void>;
1403 close: (tabId: string) => Promise<void>;
1404 };
1405 recording: {
1406 onInput: (listener: (event: DesktopPreviewRecordingInputEvent) => void) => () => void;
1407 startScreencast: (tabId: string) => Promise<void | PreviewCaptureFailureEncoded>;
1408 stopScreencast: (tabId: string) => Promise<void>;
1409 save: (
1410 tabId: string,
1411 mimeType: string,
1412 data: Uint8Array,
1413 ) => Promise<DesktopPreviewRecordingArtifact>;
1414 };
1415 onStateChange: (listener: (tabId: string, state: DesktopPreviewTabState) => void) => () => void;
1416 onPointerEvent: (listener: (event: DesktopPreviewPointerEvent) => void) => () => void;
1417 onOpenLink: (listener: (event: DesktopPreviewOpenLinkEvent) => void) => () => void;
1418 onFindResult: (listener: (event: DesktopPreviewFindResultEvent) => void) => () => void;
1419 }
1420
1421 export type ConfirmDialogVariant = "default" | "destructive";
1422
1423 export interface ConfirmDialogOptions {
1424 readonly variant?: ConfirmDialogVariant;
1425 /** Which button takes focus on open. Defaults to Cancel; destructive confirms always keep Cancel. */
1426 readonly initialFocus?: "confirm" | "cancel";
1427 }
1428
1429 export interface LocalApi {
1430 dialogs: {
1431 pickFolder: (options?: PickFolderOptions) => Promise<string | null>;
1432 confirm: (message: string, options?: ConfirmDialogOptions) => Promise<boolean>;
1433 };
1434 shell: {
1435 openExternal: (url: string) => Promise<void>;
1436 openSystemSettings: (pane: SystemSettingsPane) => Promise<void>;
1437 };
1438 contextMenu: {
1439 show: <T extends string>(
1440 items: readonly ContextMenuItem<T>[],
1441 position?: { x: number; y: number },
1442 source?: ContextMenuSource,
1443 ) => Promise<T | null>;
1444 close: () => Promise<void>;
1445 };
1446 persistence: {
1447 getClientSettings: () => Promise<ClientSettings | null>;
1448 setClientSettings: (settings: ClientSettings) => Promise<void>;
1449 };
1450 }