The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import { Schema } from "effect"; |
| 2 | import { NonNegativeInt, PositiveInt, ThreadId, TrimmedNonEmptyString } from "./baseSchemas.ts"; |
| 3 | import { BROWSER_PROFILE_MAX_COUNT, BrowserProfile, BrowserProfileId } from "./browserProfile.ts"; |
| 4 | |
| 5 | export const PREVIEW_URL_MAX_LENGTH = 2_048; |
| 6 | export const CONFIGURED_LOCAL_SERVER_URLS_MAX_ITEMS = 32; |
| 7 | |
| 8 | const Url = TrimmedNonEmptyString.check(Schema.isMaxLength(PREVIEW_URL_MAX_LENGTH)); |
| 9 | |
| 10 | export const ConfiguredLocalServerUrls = Schema.Array(Url).check( |
| 11 | Schema.isMaxLength(CONFIGURED_LOCAL_SERVER_URLS_MAX_ITEMS), |
| 12 | ); |
| 13 | const Title = Schema.String.check(Schema.isMaxLength(512)); |
| 14 | |
| 15 | export const PreviewTabId = TrimmedNonEmptyString.check(Schema.isMaxLength(128)); |
| 16 | export type PreviewTabId = typeof PreviewTabId.Type; |
| 17 | |
| 18 | export const PREVIEW_VIEWPORT_MIN_DIMENSION = 240; |
| 19 | export const PREVIEW_VIEWPORT_MAX_DIMENSION = 3840; |
| 20 | export const PREVIEW_VIEWPORT_MAX_AREA = 3840 * 2160; |
| 21 | |
| 22 | const PreviewViewportDimension = Schema.Int.check( |
| 23 | Schema.isBetween({ |
| 24 | minimum: PREVIEW_VIEWPORT_MIN_DIMENSION, |
| 25 | maximum: PREVIEW_VIEWPORT_MAX_DIMENSION, |
| 26 | }), |
| 27 | ); |
| 28 | |
| 29 | const viewportAreaFilter = Schema.makeFilter( |
| 30 | ({ width, height }: { readonly width: number; readonly height: number }) => |
| 31 | width * height <= PREVIEW_VIEWPORT_MAX_AREA || |
| 32 | `Viewport area must not exceed ${PREVIEW_VIEWPORT_MAX_AREA} pixels.`, |
| 33 | ); |
| 34 | |
| 35 | export const PreviewViewportSize = Schema.Struct({ |
| 36 | width: PreviewViewportDimension, |
| 37 | height: PreviewViewportDimension, |
| 38 | }).check(viewportAreaFilter); |
| 39 | export type PreviewViewportSize = typeof PreviewViewportSize.Type; |
| 40 | |
| 41 | /** Fill mode can measure below selectable minimum sizes; validate measurements separately. */ |
| 42 | export const PreviewRenderedViewportSize = Schema.Struct({ |
| 43 | width: Schema.Int.check(Schema.isGreaterThan(0)), |
| 44 | height: Schema.Int.check(Schema.isGreaterThan(0)), |
| 45 | }); |
| 46 | export type PreviewRenderedViewportSize = typeof PreviewRenderedViewportSize.Type; |
| 47 | |
| 48 | export const PREVIEW_VIEWPORT_PRESET_IDS = [ |
| 49 | "iphone-se", |
| 50 | "iphone-xr", |
| 51 | "iphone-12-pro", |
| 52 | "iphone-14-pro-max", |
| 53 | "pixel-7", |
| 54 | "samsung-galaxy-s8-plus", |
| 55 | "samsung-galaxy-s20-ultra", |
| 56 | "ipad-mini", |
| 57 | "ipad-air", |
| 58 | "ipad-pro", |
| 59 | "surface-pro-7", |
| 60 | "surface-duo", |
| 61 | "galaxy-z-fold-5", |
| 62 | "asus-zenbook-fold", |
| 63 | "samsung-galaxy-a51-71", |
| 64 | "nest-hub", |
| 65 | "nest-hub-max", |
| 66 | ] as const; |
| 67 | |
| 68 | export const PreviewViewportPresetId = Schema.Literals(PREVIEW_VIEWPORT_PRESET_IDS); |
| 69 | export type PreviewViewportPresetId = typeof PreviewViewportPresetId.Type; |
| 70 | |
| 71 | const LEGACY_PREVIEW_VIEWPORT_PRESET_IDS = [ |
| 72 | "desktop-1920x1080", |
| 73 | "desktop-1440x900", |
| 74 | "laptop-1366x768", |
| 75 | "laptop-1280x800", |
| 76 | "ipad-pro-11", |
| 77 | "iphone-15-pro", |
| 78 | "pixel-8", |
| 79 | "galaxy-s24", |
| 80 | ] as const; |
| 81 | |
| 82 | const StoredPreviewViewportPresetId = Schema.Literals([ |
| 83 | ...PREVIEW_VIEWPORT_PRESET_IDS, |
| 84 | ...LEGACY_PREVIEW_VIEWPORT_PRESET_IDS, |
| 85 | ]); |
| 86 | |
| 87 | export const PreviewViewportSetting = Schema.Union([ |
| 88 | Schema.TaggedStruct("fill", {}), |
| 89 | Schema.TaggedStruct("freeform", { |
| 90 | ...PreviewViewportSize.fields, |
| 91 | }).check(viewportAreaFilter), |
| 92 | Schema.TaggedStruct("preset", { |
| 93 | ...PreviewViewportSize.fields, |
| 94 | presetId: StoredPreviewViewportPresetId, |
| 95 | }).check(viewportAreaFilter), |
| 96 | ]); |
| 97 | export type PreviewViewportSetting = typeof PreviewViewportSetting.Type; |
| 98 | |
| 99 | export const FILL_PREVIEW_VIEWPORT = { |
| 100 | _tag: "fill", |
| 101 | } as const satisfies PreviewViewportSetting; |
| 102 | |
| 103 | /** Shared steps keep settings aligned with desktop Chromium zoom controls. */ |
| 104 | export const PREVIEW_ZOOM_LEVELS = [ |
| 105 | 0.25, 0.33, 0.5, 0.67, 0.75, 0.8, 0.9, 1.0, 1.1, 1.25, 1.5, 1.75, 2.0, 2.5, 3.0, 4.0, 5.0, |
| 106 | ] as const; |
| 107 | |
| 108 | export const PreviewZoomFactor = Schema.Literals(PREVIEW_ZOOM_LEVELS); |
| 109 | export type PreviewZoomFactor = typeof PreviewZoomFactor.Type; |
| 110 | |
| 111 | export const DEFAULT_PREVIEW_ZOOM_FACTOR: PreviewZoomFactor = 1.0; |
| 112 | |
| 113 | export const PreviewAppearancePreference = Schema.Literals(["system", "light", "dark"]); |
| 114 | export type PreviewAppearancePreference = typeof PreviewAppearancePreference.Type; |
| 115 | |
| 116 | export const DEFAULT_PREVIEW_APPEARANCE: PreviewAppearancePreference = "system"; |
| 117 | |
| 118 | const PreviewFileDownload = Schema.Struct({ id: Schema.String, fileName: Schema.String }); |
| 119 | |
| 120 | export const PreviewNavStatus = Schema.Union([ |
| 121 | Schema.TaggedStruct("Idle", {}), |
| 122 | Schema.TaggedStruct("Loading", { |
| 123 | url: Url, |
| 124 | title: Title, |
| 125 | }), |
| 126 | Schema.TaggedStruct("Success", { |
| 127 | url: Url, |
| 128 | title: Title, |
| 129 | }), |
| 130 | Schema.TaggedStruct("LoadFailed", { |
| 131 | url: Url, |
| 132 | title: Title, |
| 133 | code: Schema.Int, |
| 134 | description: Schema.String, |
| 135 | download: Schema.optional(PreviewFileDownload), |
| 136 | }), |
| 137 | ]); |
| 138 | export type PreviewNavStatus = typeof PreviewNavStatus.Type; |
| 139 | |
| 140 | export const PreviewRuntime = Schema.Literals(["desktop", "server"]); |
| 141 | export type PreviewRuntime = typeof PreviewRuntime.Type; |
| 142 | |
| 143 | /** JSON reason for preview stream close code 4503; must fit the 123-byte close-reason limit. */ |
| 144 | export const PreviewStreamHostSetup = Schema.Struct({ |
| 145 | need: Schema.Literals(["sandbox", "libraries"]), |
| 146 | command: Schema.String, |
| 147 | }); |
| 148 | export type PreviewStreamHostSetup = typeof PreviewStreamHostSetup.Type; |
| 149 | export const PREVIEW_STREAM_HOST_SETUP_CLOSE_CODE = 4503; |
| 150 | |
| 151 | export const PreviewSessionSnapshot = Schema.Struct({ |
| 152 | threadId: TrimmedNonEmptyString, |
| 153 | tabId: PreviewTabId, |
| 154 | navStatus: PreviewNavStatus, |
| 155 | canGoBack: Schema.Boolean, |
| 156 | canGoForward: Schema.Boolean, |
| 157 | viewport: Schema.optional(PreviewViewportSetting), |
| 158 | colorScheme: Schema.optional(PreviewAppearancePreference), |
| 159 | zoomFactor: Schema.optional(PreviewZoomFactor), |
| 160 | /** Fixed at open; Electron cannot change a webview partition after attach without losing page state. */ |
| 161 | profileId: Schema.optional(BrowserProfileId), |
| 162 | runtime: Schema.optional(PreviewRuntime), |
| 163 | /** The server runs this tab in headless Chromium, so the desktop streams it like other clients. */ |
| 164 | headless: Schema.optional(Schema.Boolean), |
| 165 | automationOwner: Schema.optional(Schema.String), |
| 166 | reveal: Schema.optional(Schema.Boolean), |
| 167 | revealRequest: Schema.optional(Schema.Struct({ id: Schema.String, force: Schema.Boolean })), |
| 168 | updatedAt: Schema.String, |
| 169 | }); |
| 170 | export type PreviewSessionSnapshot = typeof PreviewSessionSnapshot.Type; |
| 171 | |
| 172 | export const PreviewOpenInput = Schema.Struct({ |
| 173 | threadId: ThreadId, |
| 174 | url: Schema.optional(Url), |
| 175 | viewport: Schema.optional(PreviewViewportSetting), |
| 176 | profileId: Schema.optional(BrowserProfileId), |
| 177 | runtime: Schema.optional(PreviewRuntime), |
| 178 | colorScheme: Schema.optional(PreviewAppearancePreference), |
| 179 | zoomFactor: Schema.optional(PreviewZoomFactor), |
| 180 | reveal: Schema.optional(Schema.Boolean), |
| 181 | }); |
| 182 | export type PreviewOpenInput = typeof PreviewOpenInput.Type; |
| 183 | |
| 184 | export const PreviewReportStatusInput = Schema.Struct({ |
| 185 | threadId: ThreadId, |
| 186 | tabId: PreviewTabId, |
| 187 | navStatus: PreviewNavStatus, |
| 188 | canGoBack: Schema.Boolean, |
| 189 | canGoForward: Schema.Boolean, |
| 190 | }); |
| 191 | export type PreviewReportStatusInput = typeof PreviewReportStatusInput.Type; |
| 192 | |
| 193 | export const PreviewResizeInput = Schema.Struct({ |
| 194 | threadId: ThreadId, |
| 195 | tabId: PreviewTabId, |
| 196 | viewport: PreviewViewportSetting, |
| 197 | }); |
| 198 | export type PreviewResizeInput = typeof PreviewResizeInput.Type; |
| 199 | |
| 200 | /** Requires no tab control, unlike page input. */ |
| 201 | export const PreviewAdjustInput = Schema.Struct({ |
| 202 | threadId: ThreadId, |
| 203 | tabId: PreviewTabId, |
| 204 | colorScheme: Schema.optional(PreviewAppearancePreference), |
| 205 | zoomFactor: Schema.optional(PreviewZoomFactor), |
| 206 | hardReload: Schema.optional(Schema.Boolean), |
| 207 | clear: Schema.optional(Schema.Literals(["cookies", "cache"])), |
| 208 | }); |
| 209 | export type PreviewAdjustInput = typeof PreviewAdjustInput.Type; |
| 210 | |
| 211 | export const PreviewCloseInput = Schema.Struct({ |
| 212 | threadId: ThreadId, |
| 213 | tabId: Schema.optional(PreviewTabId), |
| 214 | }); |
| 215 | export type PreviewCloseInput = typeof PreviewCloseInput.Type; |
| 216 | |
| 217 | export const BROWSER_RECORDING_FRAME_RATES = [30, 60] as const; |
| 218 | export const BrowserRecordingFrameRate = Schema.Literals(BROWSER_RECORDING_FRAME_RATES); |
| 219 | export type BrowserRecordingFrameRate = typeof BrowserRecordingFrameRate.Type; |
| 220 | export const DEFAULT_BROWSER_RECORDING_FRAME_RATE: BrowserRecordingFrameRate = 30; |
| 221 | |
| 222 | export const PreviewReportProfilesInput = Schema.Struct({ |
| 223 | profiles: Schema.Array(BrowserProfile).check(Schema.isMaxLength(BROWSER_PROFILE_MAX_COUNT)), |
| 224 | defaultProfileId: BrowserProfileId, |
| 225 | /** Optional so older clients keep reporting; omitting it keeps the last reported rate. */ |
| 226 | recordingFrameRate: Schema.optional(BrowserRecordingFrameRate), |
| 227 | }); |
| 228 | export type PreviewReportProfilesInput = typeof PreviewReportProfilesInput.Type; |
| 229 | |
| 230 | export const PreviewClearProfileInput = Schema.Struct({ |
| 231 | profileId: BrowserProfileId, |
| 232 | }); |
| 233 | export type PreviewClearProfileInput = typeof PreviewClearProfileInput.Type; |
| 234 | |
| 235 | export const PreviewListInput = Schema.Struct({ |
| 236 | threadId: ThreadId, |
| 237 | }); |
| 238 | export type PreviewListInput = typeof PreviewListInput.Type; |
| 239 | |
| 240 | export const PreviewListResult = Schema.Struct({ |
| 241 | sessions: Schema.Array(PreviewSessionSnapshot), |
| 242 | /** Identifies the current server process so revision resets are safe. */ |
| 243 | serverEpoch: TrimmedNonEmptyString, |
| 244 | revision: NonNegativeInt, |
| 245 | }); |
| 246 | export type PreviewListResult = typeof PreviewListResult.Type; |
| 247 | |
| 248 | const PreviewEventBaseSchema = Schema.Struct({ |
| 249 | threadId: TrimmedNonEmptyString, |
| 250 | tabId: PreviewTabId, |
| 251 | createdAt: Schema.String, |
| 252 | serverEpoch: TrimmedNonEmptyString, |
| 253 | /** Monotonic server state revision shared with PreviewListResult. */ |
| 254 | revision: PositiveInt, |
| 255 | }); |
| 256 | |
| 257 | const PreviewOpenedEvent = Schema.Struct({ |
| 258 | ...PreviewEventBaseSchema.fields, |
| 259 | type: Schema.Literal("opened"), |
| 260 | snapshot: PreviewSessionSnapshot, |
| 261 | }); |
| 262 | |
| 263 | const PreviewNavigatedEvent = Schema.Struct({ |
| 264 | ...PreviewEventBaseSchema.fields, |
| 265 | type: Schema.Literal("navigated"), |
| 266 | snapshot: PreviewSessionSnapshot, |
| 267 | }); |
| 268 | |
| 269 | const PreviewResizedEvent = Schema.Struct({ |
| 270 | ...PreviewEventBaseSchema.fields, |
| 271 | type: Schema.Literal("resized"), |
| 272 | snapshot: PreviewSessionSnapshot, |
| 273 | request: Schema.optional( |
| 274 | Schema.Struct({ |
| 275 | hardReload: Schema.optional(Schema.Boolean), |
| 276 | clear: Schema.optional(Schema.Literals(["cookies", "cache"])), |
| 277 | }), |
| 278 | ), |
| 279 | }); |
| 280 | |
| 281 | const PreviewFailedEvent = Schema.Struct({ |
| 282 | ...PreviewEventBaseSchema.fields, |
| 283 | type: Schema.Literal("failed"), |
| 284 | url: Url, |
| 285 | title: Title, |
| 286 | code: Schema.Int, |
| 287 | description: Schema.String, |
| 288 | download: Schema.optional(PreviewFileDownload), |
| 289 | }); |
| 290 | |
| 291 | const PreviewClosedEvent = Schema.Struct({ |
| 292 | ...PreviewEventBaseSchema.fields, |
| 293 | type: Schema.Literal("closed"), |
| 294 | }); |
| 295 | |
| 296 | export const PreviewEvent = Schema.Union([ |
| 297 | PreviewOpenedEvent, |
| 298 | PreviewNavigatedEvent, |
| 299 | PreviewResizedEvent, |
| 300 | PreviewFailedEvent, |
| 301 | PreviewClosedEvent, |
| 302 | ]); |
| 303 | export type PreviewEvent = typeof PreviewEvent.Type; |
| 304 | |
| 305 | const LocalServerPort = Schema.Int.check(Schema.isGreaterThan(0)).check(Schema.isLessThan(65536)); |
| 306 | |
| 307 | export const DiscoveredLocalServer = Schema.Struct({ |
| 308 | host: TrimmedNonEmptyString, |
| 309 | port: LocalServerPort, |
| 310 | url: Url, |
| 311 | processName: Schema.NullOr(TrimmedNonEmptyString), |
| 312 | pid: Schema.NullOr(Schema.Int.check(Schema.isGreaterThan(0))), |
| 313 | terminal: Schema.NullOr( |
| 314 | Schema.Struct({ |
| 315 | threadId: ThreadId, |
| 316 | terminalId: TrimmedNonEmptyString, |
| 317 | }), |
| 318 | ), |
| 319 | /** Started by the thread's agent. Older servers omit it. */ |
| 320 | agent: Schema.optionalKey(Schema.NullOr(Schema.Struct({ threadId: ThreadId }))), |
| 321 | }); |
| 322 | export type DiscoveredLocalServer = typeof DiscoveredLocalServer.Type; |
| 323 | |
| 324 | export const PreviewStopLocalServerInput = Schema.Struct({ |
| 325 | pid: PositiveInt, |
| 326 | port: LocalServerPort, |
| 327 | }); |
| 328 | export type PreviewStopLocalServerInput = typeof PreviewStopLocalServerInput.Type; |
| 329 | |
| 330 | export class PreviewStopLocalServerError extends Schema.TaggedError<PreviewStopLocalServerError>()( |
| 331 | "PreviewStopLocalServerError", |
| 332 | { |
| 333 | reason: Schema.Literals(["not-found", "shared-group", "unsupported", "signal-failed"]), |
| 334 | cause: Schema.optional(Schema.Defect()), |
| 335 | }, |
| 336 | ) { |
| 337 | override get message() { |
| 338 | switch (this.reason) { |
| 339 | case "not-found": |
| 340 | return "This server is no longer running."; |
| 341 | case "shared-group": |
| 342 | return "This server shares a process group with T3 Code, an agent, or a terminal shell, so it can't be stopped on its own."; |
| 343 | case "unsupported": |
| 344 | return "Stopping servers is not supported on this environment's platform."; |
| 345 | case "signal-failed": |
| 346 | return "The server's processes could not be signaled."; |
| 347 | } |
| 348 | } |
| 349 | } |
| 350 | |
| 351 | export const DiscoveredLocalServerList = Schema.Struct({ |
| 352 | servers: Schema.Array(DiscoveredLocalServer), |
| 353 | scannedAt: Schema.String, |
| 354 | configuredUrlProbing: Schema.optional(Schema.Literal(true)), |
| 355 | }); |
| 356 | export type DiscoveredLocalServerList = typeof DiscoveredLocalServerList.Type; |
| 357 | |
| 358 | export class PreviewSessionLookupError extends Schema.TaggedError<PreviewSessionLookupError>()( |
| 359 | "PreviewSessionLookupError", |
| 360 | { |
| 361 | threadId: Schema.String, |
| 362 | tabId: Schema.String, |
| 363 | }, |
| 364 | ) { |
| 365 | override get message() { |
| 366 | return `Unknown preview session: thread=${this.threadId}, tab=${this.tabId}`; |
| 367 | } |
| 368 | } |
| 369 | |
| 370 | export class PreviewInvalidUrlError extends Schema.TaggedError<PreviewInvalidUrlError>()( |
| 371 | "PreviewInvalidUrlError", |
| 372 | { |
| 373 | inputLength: Schema.Number, |
| 374 | reason: Schema.Literals(["empty", "parse", "unsupported-protocol", "unexpected"]), |
| 375 | protocol: Schema.optional(Schema.String), |
| 376 | cause: Schema.Defect(), |
| 377 | }, |
| 378 | ) { |
| 379 | override get message() { |
| 380 | const protocol = this.protocol === undefined ? "" : `: ${this.protocol}`; |
| 381 | return `Invalid preview URL (${this.reason}${protocol}; input length ${this.inputLength}). Use an http(s) URL or a schemeless host such as localhost:5173. With preview_open, omit url when creating a new tab to open a blank tab.`; |
| 382 | } |
| 383 | } |
| 384 | |
| 385 | export class PreviewControlRequiredError extends Schema.TaggedError<PreviewControlRequiredError>()( |
| 386 | "PreviewControlRequiredError", |
| 387 | { tabId: Schema.String }, |
| 388 | ) { |
| 389 | override get message() { |
| 390 | return "Take control of the server browser and use its viewer controls."; |
| 391 | } |
| 392 | } |
| 393 | |
| 394 | export class PreviewClearProfileError extends Schema.TaggedError<PreviewClearProfileError>()( |
| 395 | "PreviewClearProfileError", |
| 396 | { profileId: Schema.String, cause: Schema.Defect() }, |
| 397 | ) { |
| 398 | override get message() { |
| 399 | return "The environment could not delete this browser profile's data."; |
| 400 | } |
| 401 | } |
| 402 | |
| 403 | export const PreviewError = Schema.Union([ |
| 404 | PreviewSessionLookupError, |
| 405 | PreviewInvalidUrlError, |
| 406 | PreviewControlRequiredError, |
| 407 | ]); |
| 408 | export type PreviewError = typeof PreviewError.Type; |