zzz - API docs - @fuzdev stack

"/api/account/status" import {ACCOUNT_STATUS_PATH} from '@fuzdev/zzz/session_recheck.js';

The fuz_app account status route — 200 with a live session, 401 without.

Action
#

import {Action} from '@fuzdev/zzz/action.svelte.js';

Represents a single action in the system, tracking its full lifecycle through action events.

The actions log keeps many of these, so an action holds only a bounded copy of its event's data — payloads over ACTION_PAYLOAD_BUDGET become markers (see bound_action_event_data) — and lets go of the event itself once it completes.

inheritance

extends: Cell<typeof ActionJson>

`method`

type ActionMethod

$state.raw

`action_event_data`

The event's data, with payloads over ACTION_PAYLOAD_BUDGET replaced by markers.

type ActionEventData | undefined

$state.raw

`spec`

type ActionSpecUnion

readonly $derived.by

`kind`

type ActionKind

readonly $derived

`has_error`

type boolean

readonly $derived

`pending`

Returns true if the action is still pending (not in a terminal state). An action is complete when it reaches a terminal phase (where next phase is null) AND the step is terminal (handled or failed).

type boolean

readonly $derived.by

`failed`

type boolean

readonly $derived

`success`

Returns true if the action completed successfully. Success means: action is complete (terminal phase + step), step is 'handled', and no error.

type boolean

readonly $derived.by

`constructor`

type new (options: ActionOptions): Action

`options`

type ActionOptions

`unlisten_to_action_event`

type (() => void) | undefined

`action_event`

`listen_to_action_event`

Mirrors action_event's data (bounded, see bound_action_event_data) into action_event_data until the event completes, then stops listening and drops the event, so the full payloads it holds can be collected.

`action_event`

type

ActionEvent<string, "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", "initial" | "parsed" | "handling" | "handled" | "failed">

returns () => void

`dispose`

type (): void

returns void

ACTION_ERROR_MESSAGE_TRUNCATED_KEY
#

"zzz_message_truncated_from" import {ACTION_ERROR_MESSAGE_TRUNCATED_KEY} from '@fuzdev/zzz/action_helpers.js';

Set on an error whose message bound_action_event_data truncated, to the message's original length. JSON-RPC error objects allow extra members, so the bounded error still parses.

action_event_data_has_omitted_payload
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): boolean

import {action_event_data_has_omitted_payload} from '@fuzdev/zzz/action_helpers.js';

Whether bound_action_event_data omitted any of data's payloads or truncated an error message.

`data`

type ActionEventData

returns

boolean

ACTION_PAYLOAD_BUDGET
#

8192 import {ACTION_PAYLOAD_BUDGET} from '@fuzdev/zzz/action_helpers.js';

The most JSON, in characters, the actions log keeps of one payload — an action's input, output, progress, request params, response result, notification params, or error data. A larger payload is replaced by an ActionPayloadOmitted marker, so the log's 512 entries stay small even when calls carry file contents (session_load, diskfile_update) or whole chat histories (completion_create).

action_specs
#

ActionContextmenu.svelte view source

({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; ...

type ActionSpecUnion[]

import {action_specs} from '@fuzdev/zzz/action_collections.js';

ActionContextmenu
#

accepts children

import ActionContextmenu from '@fuzdev/zzz/ActionContextmenu.svelte';

`action`

type Action

`children`

type Snippet<[]>

ActionDetail
#

ActionDetail.svelte view source

import ActionDetail from '@fuzdev/zzz/ActionDetail.svelte';

`action`

type Action

ActionEventDatas
#

ActionEventDatas import type {ActionEventDatas} from '@fuzdev/zzz/action_collections.js';

Action event data types indexed by method name. These represent the full discriminated union of all possible states for each action's event data, properly typed with inputs and outputs.

`heartbeat`

type ActionEventRequestResponseData

`cancel`

type ActionEventRemoteNotificationData

`peer/ping`

type ActionEventRequestResponseData

`ping`

type ActionEventRequestResponseData

`session_load`

type ActionEventRequestResponseData

`filer_change`

type ActionEventRemoteNotificationData

`diskfile_update`

type ActionEventRequestResponseData

`diskfile_create`

type ActionEventRequestResponseData

`diskfile_delete`

type ActionEventRequestResponseData

`directory_create`

type ActionEventRequestResponseData

`media_finalize`

type ActionEventRequestResponseData

`transcription_create`

type ActionEventRequestResponseData

`transcription_progress`

type ActionEventRemoteNotificationData

`job_cancel`

type ActionEventRequestResponseData

`job_changed`

type ActionEventRemoteNotificationData

`completion_create`

type ActionEventRequestResponseData

`completion_progress`

type ActionEventRemoteNotificationData

`toggle_main_menu`

type ActionEventLocalCallData

`provider_load_status`

type ActionEventRequestResponseData

`terminal_create`

type ActionEventRequestResponseData

`terminal_data_send`

type ActionEventRequestResponseData

`terminal_data`

type ActionEventRemoteNotificationData

`terminal_ack`

type ActionEventRequestResponseData

`terminal_resize`

type ActionEventRequestResponseData

`terminal_close`

type ActionEventRequestResponseData

`terminal_exited`

type ActionEventRemoteNotificationData

`workspace_open`

type ActionEventRequestResponseData

`workspace_close`

type ActionEventRequestResponseData

`workspace_list`

type ActionEventRequestResponseData

`workspace_changed`

type ActionEventRemoteNotificationData

ActionInputs
#

value + type

ActionInputs import {ActionInputs} from '@fuzdev/zzz/action_collections.js';

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; method: "heartbeat" | "cancel" | "peer/ping" | ... 26 more ... | "workspace_changed"; action_event_data?: { ...; } | undefined; }

import {ActionJson} from '@fuzdev/zzz/action.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`method`

`action_event_data?`

type { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

ActionJsonInput
#

ActionList.svelte view source

{ method: "heartbeat" | "cancel" | "peer/ping" | "ping" | "session_load" | "filer_change" | "diskfile_update" | "diskfile_create" | "diskfile_delete" | "directory_create" | "media_finalize" | ... 18 more ... | "workspace_changed"; id?: string | undefined; created?: string | undefined; updated?: string | undefined; a...

import type {ActionJsonInput} from '@fuzdev/zzz/action.svelte.js';

`method`

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

`action_event_data?`

ActionList
#

import ActionList from '@fuzdev/zzz/ActionList.svelte';

`limit?`

type number

optional default 20

`selected_action_id?`

type string | null

optional default null

`attrs?`

type HTMLAttributes<HTMLDivElement>

optional

`onselect?`

type (action: Action) => void

optional

snippet parameters

action Action

ActionListitem
#

ActionListitem.svelte view source

import ActionListitem from '@fuzdev/zzz/ActionListitem.svelte';

`action`

type Action

`selected?`

type boolean

optional default false

`onselect?`

type (action: Action) => void

optional

snippet parameters

action Action

ActionMethod
#

value + type

"heartbeat" | "cancel" | "peer/ping" | "ping" | "session_load" | "filer_change" | "diskfile_update" | "diskfile_create" | "diskfile_delete" | "directory_create" | "media_finalize" | ... 18 more ... | "workspace_changed"

import {ActionMethod} from '@fuzdev/zzz/action_metatypes.js';

All action method names. Request/response actions have two types per method.

ActionOptions
#

ActionOptions import type {ActionOptions} from '@fuzdev/zzz/action.svelte.js';

inheritance

extends: CellOptions<typeof ActionJson>

ActionOutputs
#

Stores the action history.

inheritance

extends: Cell<typeof ActionsJson>

`items`

type IndexedCollection<Action>

readonly

`history_limit`

type number

$state.raw

`constructor`

type new (options: ActionsOptions): Actions

`options`

type ActionsOptions

`set_json`

Override to populate the indexed collection after parsing JSON.

type (value?: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; items?: { method: "heartbeat" | "cancel" | "peer/ping" | "ping" | "session_load" | "filer_change" | ... 23 more ... | "workspace_changed"; id?: string | undefined; created?: string | undefined; updated?: string | undefined; action_event_data?: { ...; } | undefined; }[] | undefined; } | undefined): void

`value?`

type ActionsJsonInput

optional

returns void

`add`

type (action: Action): void

`action`

type Action

returns void

`add_from_json`

type (action_json: { method: "heartbeat" | "cancel" | "peer/ping" | "ping" | "session_load" | "filer_change" | "diskfile_update" | "diskfile_create" | "diskfile_delete" | "directory_create" | ... 19 more ... | "workspace_changed"; id?: string | undefined; created?: string | undefined; updated?: string | undefined; action_event_data?: { ...; } | undefined; }): Action

`action_json`

type ActionJsonInput

returns Action

ActionSchema
#

ZodCustom<Action, Action>

type ZodCustom<Action, Action>

import {ActionSchema} from '@fuzdev/zzz/action.svelte.js';

ActionsJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; items: { id: string & $brand<"Uuid">; created: string & $brand<...>; updated: string & $brand<...>; method: "heartbeat" | ... 28 more ... | "workspace_changed"; action_event_data?: { ...; } | undefined; }[]; }

import {ActionsJson} from '@fuzdev/zzz/actions.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`items`

type ActionJson[]

ActionsJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; items?: { method: "heartbeat" | "cancel" | "peer/ping" | "ping" | "session_load" | "filer_change" | ... 23 more ... | "workspace_changed"; id?: string | undefined; created?: string | undefined; updated?: string | undefined; action...

import type {ActionsJsonInput} from '@fuzdev/zzz/actions.svelte.js';

type number

ActionSpecs
#

value + type

ActionSpecs import {ActionSpecs} from '@fuzdev/zzz/action_collections.js';

Action specifications indexed by method name. These represent the complete action spec definitions.

`heartbeat`

`cancel`

type { method: string; kind: "remote_notification"; initiator: "frontend"; auth: null; side_effects: true; input: ZodObject<{ request_id: ZodUnion<readonly [ZodString, ZodNumber]>; }, $strict>; output: ZodVoid; async: true; description: string; }

`peer/ping`

type { method: string; kind: "request_response"; initiator: "both"; auth: { account: "none"; actor: "none"; }; side_effects: false; input: ZodDefault<ZodObject<{ nonce: ZodOptional<ZodNumber>; timeout_ms: ZodOptional<...>; }, $strict>>; output: ZodObject<...>; async: true; rate_limit: "ip"; description: string; }

`ping`

type { method: string; kind: "request_response"; initiator: "both"; auth: { account: "none"; actor: "none"; }; side_effects: false; input: ZodVoid; output: ZodObject<{ ping_id: ZodUnion<readonly [ZodString, ZodNumber]>; }, $strict>; async: true; description: string; }

`session_load`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: false; input: ZodVoid; output: ZodObject<{ data: ZodObject<{ zzz_dir: $ZodBranded<ZodPipe<ZodPipe<...>, $ZodBranded<...>>, "DiskfileDirectoryPath", "out">; ... 7 more ...; server_instance_i...

`filer_change`

type { method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodUnion<readonly [ZodObject<{ change: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; type: ZodEnum<...>; }, $strict>; disknode: ZodObject<...>; }, $strict>, ZodObject<...>]>; output: ZodVoid...

`diskfile_update`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; content: ZodString; }, $strict>; output: ZodNull; async: true; description: string; }

`diskfile_create`

`diskfile_delete`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; }, $strict>; output: ZodNull; async: true; description: string; }

`directory_create`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; }, $strict>; output: ZodNull; async: true; description: string; }

`media_finalize`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; }, $strict>; output: ZodObject<...>; async: true; description: string; }

`transcription_create`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; language: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; description: string; }

`transcription_progress`

type { method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ job_id: $ZodBranded<ZodUUID, "Uuid", "out">; segments: ZodArray<...>; }, $strict>; output: ZodVoid; async: true; description: string; }

`job_cancel`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ job_id: $ZodBranded<ZodUUID, "Uuid", "out">; }, $strict>; output: ZodNull; async: true; description: string; }

`job_changed`

type { method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ job: ZodObject<{ job_id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 10 more ...; stderr: ZodString; }, $strict>; }, $strict>; output: ZodVoid; async: true; description: string; }

`completion_create`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ completion_request: ZodObject<{ created: ZodDefault<$ZodBranded<ZodISODateTime, "Datetime", "out">>; provider_name: ZodEnum<...>; model: ZodString; prompt: ZodStrin...

`completion_progress`

type { method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ chunk: ZodOptional<ZodObject<{ model: ZodOptional<ZodString>; created_at: ZodOptional<...>; done: ZodOptional<...>; message: ZodOptional<...>; }, $loose>>; _meta: ZodOptional<...>; }, $strict>; out...

`toggle_main_menu`

type { method: string; kind: "local_call"; initiator: "frontend"; auth: null; side_effects: true; input: ZodOptional<ZodObject<{ show: ZodOptional<ZodBoolean>; }, $strict>>; output: ZodObject<...>; async: false; description: string; }

`provider_load_status`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: false; input: ZodObject<{ provider_name: ZodEnum<{ claude: "claude"; chatgpt: "chatgpt"; gemini: "gemini"; }>; reload: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; de...

`terminal_create`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ command: ZodString; args: ZodDefault<ZodArray<ZodString>>; cwd: ZodOptional<...>; preset_id: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; des...

`terminal_data_send`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ terminal_id: $ZodBranded<ZodUUID, "Uuid", "out">; data: ZodString; }, $strict>; output: ZodNull; async: true; description: string; }

`terminal_data`

type { method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ terminal_id: $ZodBranded<ZodUUID, "Uuid", "out">; data: ZodString; sent_bytes: ZodNumber; }, $strict>; output: ZodVoid; async: true; description: string; }

`terminal_ack`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ terminal_id: $ZodBranded<ZodUUID, "Uuid", "out">; bytes: ZodNumber; }, $strict>; output: ZodNull; async: true; description: string; }

`terminal_resize`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ terminal_id: $ZodBranded<ZodUUID, "Uuid", "out">; cols: ZodNumber; rows: ZodNumber; }, $strict>; output: ZodNull; async: true; description: string; }

`terminal_close`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ terminal_id: $ZodBranded<ZodUUID, "Uuid", "out">; signal: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; description: string; }

`terminal_exited`

type { method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ terminal_id: $ZodBranded<ZodUUID, "Uuid", "out">; exit_code: ZodNullable<...>; }, $strict>; output: ZodVoid; async: true; description: string; }

`workspace_open`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodPipe<ZodPipe<ZodString, ZodTransform<string, string>>, $ZodBranded<...>>, "DiskfileDirectoryPath", "out">; }, $strict>; output: ZodObject<...>;...

`workspace_close`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodPipe<ZodPipe<ZodString, ZodTransform<string, string>>, $ZodBranded<...>>, "DiskfileDirectoryPath", "out">; }, $strict>; output: ZodNull; async:...

`workspace_list`

type { method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: false; input: ZodVoid; output: ZodObject<{ workspaces: ZodArray<ZodObject<{ path: $ZodBranded<...>; name: ZodString; opened_at: ZodString; }, $strict>>; }, $strict>; async: true; descriptio...

`workspace_changed`

type { method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ type: ZodEnum<{ open: "open"; close: "close"; }>; workspace: ZodObject<{ path: $ZodBranded<ZodPipe<ZodPipe<...>, $ZodBranded<...>>, "DiskfileDirectoryPath", "out">; name: ZodString; opened_at: ZodS...

all_action_specs
#

app.svelte.ts view source

({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; ...

type ActionSpecUnion[]

import {all_action_specs} from '@fuzdev/zzz/action_specs.js';

inheritance

extends: Frontend

`constructor`

type new (options?: AppOptions | undefined): App

`options?`

type AppOptions

optional

app_context
#

{ get: (error_message?: string | undefined) => App; get_maybe: () => App | undefined; set: (value: App) => App; } import {app_context} from '@fuzdev/zzz/app.svelte.js';

This is an example of a user-typed alias of frontend_context. I like this pattern in my apps but there are other patterns too.

append_file_bytes
#

app.svelte.ts view source

(fetch: FileBytesFetch, api_url: string, path: string, offset: number, body: Blob | BufferSource): Promise<FileBytesWriteResult>

import {append_file_bytes} from '@fuzdev/zzz/file_bytes.js';

Appends bytes to a file, only if it is exactly offset bytes long. Otherwise it fails with offset_mismatch and the file's current size, having written nothing.

`fetch`

the fetch to send with

type FileBytesFetch

`api_url`

the API's URL or path, with no trailing slash

type string

`path`

the file's absolute path

type string

`offset`

the size the file must currently have

type number

`body`

the bytes to append

type Blob | BufferSource

returns

Promise<FileBytesWriteResult>

AppOptions
#

AppOptions import type {AppOptions} from '@fuzdev/zzz/app.svelte.js';

inheritance

extends: FrontendOptions

AUDIO_CAPTURE_TICK_INTERVAL
#

100 import {AUDIO_CAPTURE_TICK_INTERVAL} from '@fuzdev/zzz/audio_capture.svelte.js';

How often AudioCapture.duration and AudioCapture.level update while the microphone is open, in milliseconds.

AUDIO_EXTENSIONS
#

ReadonlySet<string>

type ReadonlySet<string>

import {AUDIO_EXTENSIONS} from '@fuzdev/zzz/diskfile_content_kind.js';

Extensions viewed as audio. Each is one the backend serves with a media type (twin of media_content_type in zzz_server's file_bytes.rs), so an <audio> element can play it from the byte route. webm is here because that's what a recording is; a .webm holding video plays as its audio track.

AudioCapture
#

import {AudioCapture} from '@fuzdev/zzz/audio_capture.svelte.js';

Captures the microphone with MediaRecorder, handing each chunk to a sink as it's recorded, with pause and resume, the duration so far, and a level.

Capture starts only in start, and only during a user gesture. active is true the whole time the microphone may be open, for an indicator.

`deps`

type AudioCaptureDeps

`status`

type AudioCaptureStatus

$state.raw

`duration`

How long the current capture is so far, in milliseconds, not counting paused time. Updates every AUDIO_CAPTURE_TICK_INTERVAL while recording, and keeps its last value once the capture ends.

type number

$state.raw

`level`

How loud the microphone is right now, 0 to 1 — for a level meter. Updates every AUDIO_CAPTURE_TICK_INTERVAL while the microphone is open (paused included), and is 0 otherwise or where it can't be measured.

type number

$state.raw

`active`

Whether the microphone may be open: any status but idle.

type boolean

readonly $derived

`constructor`

type new (options?: AudioCaptureOptions): AudioCapture

`options`

type AudioCaptureOptions

default {}

`start`

Opens the microphone and the sink, and starts recording. Must be called from a user gesture (a click handler).

type <TSink extends AudioCaptureSink>(options: AudioCaptureStartOptions<TSink>): Promise<TSink | null>

`options`

type AudioCaptureStartOptions<TSink>

returns Promise<TSink | null>

the opened sink once recording, or null when the capture was stopped or disposed before it got there

throws

Error - when one is already under way (leaving it untouched), or when there's no user gesture, the browser can't record, the microphone can't be opened, or the sink can't be opened — each of those after closing whatever the start opened

`pause`

Pauses a capture: the microphone stays open, nothing is recorded.

type (): void

returns void

`resume`

Resumes a paused capture.

type (): void

returns void

`stop`

Stops the capture: hands the last chunk to the sink, closes the microphone, and closes the sink. A capture still starting is abandoned.

type (): Promise<AudioCaptureStopResult | null>

returns Promise<AudioCaptureStopResult | null>

how closing the sink went, or null when nothing was being recorded, or the capture failed or was disposed while stopping

`dispose`

Ends the capture without closing the sink. The last chunk the browser hands over as it stops is still written to it.

type (): void

returns void

AudioCaptureDeps
#

AudioCaptureDeps import type {AudioCaptureDeps} from '@fuzdev/zzz/audio_capture.svelte.js';

The browser a capture runs in — everything it touches outside itself, so a test can stand in for the microphone and the clock.

`get_user_media`

navigator.mediaDevices.getUserMedia.

type (constraints: MediaStreamConstraints): Promise<MediaStream>

`constraints`

type MediaStreamConstraints

returns Promise<MediaStream>

`create_media_recorder`

new MediaRecorder(stream, options).

type (stream: MediaStream, options: MediaRecorderOptions): MediaRecorder

`stream`

type MediaStream

`options`

type MediaRecorderOptions

returns MediaRecorder

`is_type_supported`

MediaRecorder.isTypeSupported — false where there's no MediaRecorder.

type (mime_type: string): boolean

`mime_type`

type string

returns boolean

`create_level_meter`

A meter on stream (Web Audio), or null where it can't be made.

type (stream: MediaStream): LevelMeter | null

`stream`

type MediaStream

returns LevelMeter | null

`has_user_activation`

Whether a user gesture is in effect (navigator.userActivation.isActive) — true in a browser that can't say.

type (): boolean

returns boolean

`now`

Date.now.

type (): number

returns number

AudioCaptureOptions
#

AudioCaptureOptions import type {AudioCaptureOptions} from '@fuzdev/zzz/audio_capture.svelte.js';

`deps?`

The browser to capture with (default create_audio_capture_deps()).

type AudioCaptureDeps

AudioCaptureSink
#

AudioCaptureSink import type {AudioCaptureSink} from '@fuzdev/zzz/audio_capture.svelte.js';

Where a capture's chunks go — a file on a backend, local storage, anywhere.

`write`

Takes the next chunk, after every chunk written before it.

type (chunk: Blob): void

`chunk`

type Blob

returns void

`close`

Waits for every written chunk to land.

type (): Promise<void>

returns Promise<void>

throws

Error - when they didn't

AudioCaptureStartOptions
#

AudioCaptureStartOptions<TSink> import type {AudioCaptureStartOptions} from '@fuzdev/zzz/audio_capture.svelte.js';

generics

AudioCaptureStartOptions<TSink extends AudioCaptureSink = AudioCaptureSink>

`TSink`

constraint AudioCaptureSink

default AudioCaptureSink

`chunk_duration`

How often the browser hands over a chunk, in milliseconds — the most a sink can lose when the tab crashes.

type number

`open_sink`

Opens the sink for a capture in format, once the microphone is open. fail ends the capture with a reason, for a sink that breaks while chunks are still arriving; it's ignored once the capture has ended.

type (format: RecordingFormat, fail: (message: string) => void): Promise<TSink>

`format`

type RecordingFormat

`fail`

type (message: string) => void

returns Promise<TSink>

throws

Error - when the sink can't be opened, which ends the start

`on_fail`

Called when a capture under way breaks and has ended, with why.

type (message: string): void

`message`

type string

returns void

`on_input_ended`

Called when the microphone's track ends on its own — the device was unplugged, or the browser revoked the permission. Typically stops the capture the way its owner normally does.

type (): void

returns void

AudioCaptureStatus
#

AudioCaptureStatus

type "idle" | "starting" | "recording" | "paused" | "stopping"

import type {AudioCaptureStatus} from '@fuzdev/zzz/audio_capture.svelte.js';

Where a capture is: starting while the microphone opens and the sink opens, stopping while the last chunk is handed over and the sink closes.

AudioCaptureStopResult
#

AudioCaptureStopResult

type ({ ok: true; } & object) | ({ ok: false; } & { message: string; })

import type {AudioCaptureStopResult} from '@fuzdev/zzz/audio_capture.svelte.js';

What a stop got from the sink: ok, or why closing it failed.

AuthGateInput
#

AuthGateState

type "checking" | "daemon_unreachable" | "bootstrap" | "login"

import type {AuthGateState} from '@fuzdev/zzz/auth_gate.js';

What the gate shows in place of the app:

checking — the first session check or the backend probe hasn't settled (or the session just verified and the app is mounting)
daemon_unreachable — no zzz backend answers
bootstrap — no account exists yet
login — the backend is up and there's no session

backend_reachable_context
#

{ get: (error_message?: string | undefined) => () => boolean | null; get_maybe: () => (() => boolean | null) | undefined; set: (value: () => boolean | null) => () => boolean | null; }

import {backend_reachable_context} from '@fuzdev/zzz/auth_gate.js';

Whether a zzz backend answered the root layout's probe — null until the probe settles (and during SSR). Set by the root layout as a getter, so public routes can say why they're missing the app: no daemon, or no login.

BackendActionMethod
#

value + type

"heartbeat" | "cancel" | "peer/ping" | "ping" | "session_load" | "filer_change" | "diskfile_update" | "diskfile_create" | "diskfile_delete" | "directory_create" | "media_finalize" | ... 17 more ... | "workspace_changed"

import {BackendActionMethod} from '@fuzdev/zzz/action_metatypes.js';

Names of all actions the backend may encounter — request_response and remote_notification (local_call is frontend-only).

BackendRequestResponseMethod
#

value + type

"ping" | "session_load" | "diskfile_update" | "diskfile_create" | "diskfile_delete" | "directory_create" | "media_finalize" | "transcription_create" | "job_cancel" | "completion_create" | ... 8 more ... | "workspace_list"

import {BackendRequestResponseMethod} from '@fuzdev/zzz/action_metatypes.js';

Names of request_response actions the backend handles (initiator excludes backend).

BOTS_DEFAULT
#

{ namerbot: string; } import {BOTS_DEFAULT} from '@fuzdev/zzz/config_defaults.js';

bound_action_event_data
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }, budget?: number): { ...; }

import {bound_action_event_data} from '@fuzdev/zzz/action_helpers.js';

Bounds what the actions log keeps of an action event's data: each payload over budget — input, output, progress, the request's params, the response's result (or its error's data), the notification's params, and the error's data — becomes an ActionPayloadOmitted marker, and an error message over budget characters is truncated (see truncate_action_error_message) and flagged with ACTION_ERROR_MESSAGE_TRUNCATED_KEY. The lifecycle fields (kind, phase, step, method, executor), the JSON-RPC envelopes, and the error's code are always kept, so the result still parses as ActionEventData. Returns data itself when nothing is over the budget.

`data`

type ActionEventData

`budget`

type number

default ACTION_PAYLOAD_BUDGET

returns

ActionEventData

BroadcastActionMethod
#

value + type

import {BroadcastActionMethod} from '@fuzdev/zzz/action_metatypes.js';

Names of remote_notification actions exposed by the broadcast API (backend-initiated, excluding request-scoped progress notifications named by another action's streams).

calculate_reorderable_target_index
#

(source_index: number, current_index: number, position: ReorderableValidDropPosition): number import {calculate_reorderable_target_index} from '@fuzdev/zzz/reorderable_helpers.js';

Calculate the target index based on source, current index, and position.

`source_index`

type number

`current_index`

type number

`position`

type ReorderableValidDropPosition

returns

number

Capabilities
#

import {Capabilities} from '@fuzdev/zzz/capabilities.svelte.js';

A class that encapsulates system capabilities detection and management. This is NOT generic or extensible - it contains hardcoded logic for all capabilities the system supports.

inheritance

extends: Cell<typeof CapabilitiesJson>

type new (options: CellOptions<ZodObject<{ id: ZodDefault<$ZodBranded<ZodUUID, "Uuid", "out">>; created: ZodDefault<$ZodBranded<ZodISODateTime, "Datetime", "out">>; updated: ZodDefault<...>; }, $strict>>): Capabilities

`options`

type

CellOptions<ZodObject<{ id: ZodDefault<$ZodBranded<ZodUUID, "Uuid", "out">>; created: ZodDefault<$ZodBranded<ZodISODateTime, "Datetime", "out">>; updated: ZodDefault<$ZodBranded<ZodISODateTime, "Datetime", "out">>; }, $strict>>

`init_backend_check`

Check backend availability only if it hasn't been checked before. (when status is 'initial')

type (): Promise<void>

returns Promise<void>

`check_backend`

Check backend availability with a ping.

type (): Promise<void>

returns Promise<void>

`handle_ping_sent`

type (request_id: string | number): void

`request_id`

type JsonrpcRequestId

returns void

`handle_ping_received`

type (ping_id: string | number): void

`ping_id`

type JsonrpcRequestId

returns void

`handle_ping_error`

type (ping_id: string | number, error_message: string): void

`ping_id`

type JsonrpcRequestId

`error_message`

type string

returns void

`reset_backend`

Reset just the backend capability to uninitialized state.

type (): void

returns void

CapabilitiesJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; } import {CapabilitiesJson} from '@fuzdev/zzz/capabilities.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

CapabilitiesJsonInput
#

CapabilitiesView.svelte view source

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; } import type {CapabilitiesJsonInput} from '@fuzdev/zzz/capabilities.svelte.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

CapabilitiesView
#

import CapabilitiesView from '@fuzdev/zzz/CapabilitiesView.svelte';

Capability
#

CapabilityBackend.svelte view source

Capability<T> import type {Capability} from '@fuzdev/zzz/capabilities.svelte.js';

Generic interface for a capability with standardized status tracking.

generics

Capability<T>

`T`

`name`

The capability name.

type string

`data`

The capability's status: undefined=not initialized, null=checking, otherwise available or not.

type T

`status`

Async status tracking the connection/check state.

type AsyncStatus

`message_id`

Message id of the last request for this capability's info, if any.

type string | number | null

`error_message`

Error message if any.

type string | null

`updated`

Timestamp when the capability was last checked.

type number | null

CapabilityBackend
#

import CapabilityBackend from '@fuzdev/zzz/CapabilityBackend.svelte';

CapabilityFilesystem
#

CapabilityFilesystem.svelte view source

import CapabilityFilesystem from '@fuzdev/zzz/CapabilityFilesystem.svelte';

CapabilityProvider
#

CapabilityProvider.svelte view source

import CapabilityProvider from '@fuzdev/zzz/CapabilityProvider.svelte';

`provider_name`

type ProviderName

CapabilityProviderApi
#

CapabilityProviderApi.svelte view source

import CapabilityProviderApi from '@fuzdev/zzz/CapabilityProviderApi.svelte';

`provider_name`

type "claude" | "chatgpt" | "gemini"

`show_info?`

type boolean

optional default true

CapabilitySystem
#

CapabilitySystem.svelte view source

import CapabilitySystem from '@fuzdev/zzz/CapabilitySystem.svelte';

CapabilityWebsocket
#

CapabilityWebsocket.svelte view source

import CapabilityWebsocket from '@fuzdev/zzz/CapabilityWebsocket.svelte';

`socket?`

type Socket

optional

Cell
#

cell.svelte.ts view source

import {Cell} from '@fuzdev/zzz/cell.svelte.js';

The Cell is the base class for schema-driven data models in Zzz. The goals are still evolving, but a main idea is to have fully reactive state that can be flexibly snapshotted and reinstantiated in a typesafe, extensible system that uses normal Svelte patterns.

The design aims for:

Integration with Svelte's reactivity, encouraging single-depth inheritance with Svelte class patterns for both persistent and ephemeral state
Schema-driven parsing/validation and JSON serialization/deserialization (supporting snapshot and restore/replay patterns) via Zod
Custom property encoding/decoding for complex types, and no boilerplate for schema-inferrable properties
Lifecycle management with generic instantiation/registration and disposal (conceptually a WIP, partially implemented)
Runtime type metadata for reflection

Cells are automatically registered in the global registry by id, making them discoverable and referenceable throughout the system. Each cell has common properties including id and created/updated timestamps.

There are currently a lot of rough edges and missing features! My hope is that this could be generic enough to extract to a library, but it's not there yet. I assume there's a really nice design in this space that takes full advantage of Svelte runes.

Many things will be possible with this pattern, but it's still a work in progress.

generics

Cell<TSchema extends z.ZodType = z.ZodType>

`TSchema`

constraint z.ZodType

default z.ZodType

inheritance

readonly $derived

`updated_formatted_time`

type string

readonly $derived

`constructor`

type new <TSchema extends z.ZodType = ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>(schema: TSchema, options: CellOptions<TSchema>): Cell<TSchema>

`schema`

type TSchema

`options`

type CellOptions<TSchema>

`init`

Initialize the instance with options.json data if provided. Must be called before using the instance - the current pattern is calling it at the end of subclass constructors.

We should investigate deferring to callers so e.g. instantiating from the registry would init automatically, subclasses need no init logic (which can get unwieldy with inheritance), and then callers could always do custom init patterns if they wanted.

Can't be called automatically by the Cell's constructor because the subclass' constructor needs to run first to support field initialization. A design goal behind the Cell is to support normal TS and Svelte patterns with the most power and least intrusion. (there's a balance to find from Zzz's POV)

type (): void

protected

returns void

`dispose`

Clean up resources when this cell is no longer needed.

type (): void

returns void

`[Symbol.dispose]`

This is not supported in Safari, don't rely on this yet. Uncomment temporarily to experiment in dev.

type (): void

returns void

`register`

type (): void

protected

returns void

`unregister`

Unregister this cell from the global cell registry. Called automatically by dispose().

type (): void

protected

returns void

`toJSON`

For Svelte's $snapshot.

type (): output<TSchema>

returns output<TSchema>

`to_json`

Encodes the cell's serializable state as JSON. Use the derived cell.json if you don't need a fresh copy.

type (): output<TSchema>

returns output<TSchema>

`set_json`

Apply JSON data to this instance. Overwrites all properties including 'id'. Special-cases created and updated for synchronization.

type (value: input<TSchema> | undefined): void

`value`

type input<TSchema> | undefined

returns void

`set_json_partial`

Update only the specified properties on this instance. Preserves current values for any properties not included in the input.

type (partial_value: Partial<input<TSchema>>): void

`partial_value`

type Partial<input<TSchema>>

returns void

`encode_property`

Encode a value during serialization. Can be overridden for custom encoding logic. Defaults to Svelte's $state.snapshot, which handles most cases and uses toJSON when available, so overriding to_json is sufficient for most cases before overriding encode_property.

type (value: unknown, _key: string): unknown

`value`

type unknown

`_key`

type string

returns unknown

`decode_property`

Decode a value based on its schema type information. This handles instantiating classes, transforming arrays, and special types.

Complex property types might require custom handling in parser functions rather than using this general decoding mechanism.

type <K extends SchemaKeys<TSchema>>(value: unknown, key: K): any

`value`

type unknown

`key`

type K

returns any

`assign_property`

Process a single schema property during JSON deserialization. This method handles the workflow for mapping schema properties to instance properties.

Flow:

If a decoder exists for this property, try to use it
If decoder returns HANDLED, consider the property fully handled (short circuit)
If decoder returns a value other than HANDLED or undefined, use that value
If decoder returns undefined, fall through to standard decoding
For properties not directly represented in the class instance but defined in the schema, the decoder MUST return HANDLED to indicate proper handling

type (key: SchemaKeys<TSchema>, value: unknown): void

protected

`key`

type SchemaKeys

`value`

type unknown

returns void

`clone`

Generic clone method that works for any subclass.

type (json?: input<TSchema> | undefined, options?: CellOptions<TSchema> | undefined): this

`json?`

type input<TSchema>

optional

`options?`

type CellOptions<TSchema>

optional

returns this

cell_classes
#

{ Parts: typeof Parts; Capabilities: typeof Capabilities; Chat: typeof Chat; Chats: typeof Chats; Diskfile: typeof Diskfile; DiskfileTab: typeof DiskfileTab; DiskfileTabs: typeof DiskfileTabs; ... 28 more ...; Workspaces: typeof Workspaces; }

type CellClasses

import {cell_classes} from '@fuzdev/zzz/cell_classes.js';

The registered cell classes, keyed by the name schemas refer to them by (their cell_class_name meta) — the registry's key, never constructor.name, which a minified build mangles.

CellClasses
#

{ Parts: typeof Parts; Capabilities: typeof Capabilities; Chat: typeof Chat; Chats: typeof Chats; Diskfile: typeof Diskfile; DiskfileTab: typeof DiskfileTab; DiskfileTabs: typeof DiskfileTabs; ... 28 more ...; Workspaces: typeof Workspaces; }

import type {CellClasses} from '@fuzdev/zzz/cell_classes.js';

`Parts`

type typeof Parts

`Capabilities`

type typeof Capabilities

`Chat`

type typeof Chat

`Chats`

type typeof Chats

`Diskfile`

type typeof Diskfile

`DiskfileTab`

type typeof DiskfileTab

`DiskfileTabs`

type typeof DiskfileTabs

`DiskfilePart`

type typeof DiskfilePart

`DiskfileHistory`

type typeof DiskfileHistory

`Diskfiles`

type typeof Diskfiles

`DiskfilesEditor`

type typeof DiskfilesEditor

`Job`

type typeof Job

`Jobs`

type typeof Jobs

`Model`

type typeof Model

`Models`

type typeof Models

`Action`

type typeof Action

`Actions`

type typeof Actions

`Prompt`

type typeof Prompt

`Prompts`

type typeof Prompts

`Provider`

type typeof Provider

`Providers`

type typeof Providers

`Recorder`

type typeof Recorder

`Space`

type typeof Space

`Spaces`

type typeof Spaces

`Terminal`

type typeof Terminal

`TerminalPreset`

type typeof TerminalPreset

`TerminalPresets`

type typeof TerminalPresets

`Terminals`

type typeof Terminals

`Turn`

type typeof Turn

`Thread`

type typeof Thread

`Threads`

type typeof Threads

`Time`

type typeof Time

`TextPart`

type typeof TextPart

`Ui`

type typeof Ui

`Workspace`

type typeof Workspace

`Workspaces`

type typeof Workspaces

CellClassNames
#

cell_types.ts view source

"Action" | "Actions" | "Capabilities" | "Parts" | "Chat" | "Chats" | "Diskfile" | "DiskfileTab" | "DiskfileTabs" | "DiskfilePart" | "DiskfileHistory" | "Diskfiles" | "DiskfilesEditor" | ... 22 more ... | "Workspaces"

import type {CellClassNames} from '@fuzdev/zzz/cell_classes.js';

CellJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; } import {CellJson} from '@fuzdev/zzz/cell_types.js';

Base schema that defines common properties for all cells.

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

CellJsonInput
#

cell_types.ts view source

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; } import type {CellJsonInput} from '@fuzdev/zzz/cell_types.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

CellOptions
#

cell.svelte.ts view source

CellOptions<TSchema> import type {CellOptions} from '@fuzdev/zzz/cell.svelte.js';

Any options besides these declared ones are ignored, so they're safe to forward when subclassing without needing to extract the rest options.

generics

CellOptions<TSchema extends z.ZodType>

`TSchema`

constraint z.ZodType

`app`

type Frontend

`json?`

type input<TSchema>

CellRegistry
#

cell_registry.svelte.ts view source

import {CellRegistry} from '@fuzdev/zzz/cell_registry.svelte.js';

Registry for managing cell classes and their instances. The goal is to allow dynamic instantiation of all cells from serializable JSON. CellRegistry does not currently justify its weight/complexity and may be removed in the future, but I want to continue exploring the ideas behind it until we get fully snapshottable UI.

`app`

type Frontend

readonly

`class_names`

type string[]

readonly $derived

`all`

type Map<Uuid, Cell<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>

readonly

`constructor`

type new (app: Frontend): CellRegistry

`app`

type Frontend

`register`

Register a cell class with the registry under class_name — the name schemas refer to it by (their cell_class_name meta). It's explicit, not constructor.name, which a minified build mangles.

type (class_name: string, constructor: ClassConstructor<Cell<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>): void

`class_name`

type string

`constructor`

type ClassConstructor<Cell<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>

returns void

`unregister`

Unregister a cell class from the registry.

type (class_name: string): boolean

`class_name`

type string

returns boolean

`maybe_instantiate`

Attempt to instantiate a class, returning null if not found. Logs an error in development if the class isn't registered.

type <K extends keyof CellRegistryMap>(class_name: K, json?: (CellRegistryMap[K] extends Cell<infer TSchema extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>> ? input<...> : never) | undefined, options?: object | undefined): CellRegistryMap[K] | null

`class_name`

type K

`json?`

type

CellRegistryMap[K] extends Cell<infer TSchema extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>> ? input<TSchema> : never

optional

`options?`

type object

optional

returns CellRegistryMap[K] | null

`instantiate`

Create an instance of a registered cell class by name. Throws if the class isn't found.

Type is automatically inferred from class name literals.

`class_name`

type K

`json?`

type

CellRegistryMap[K] extends Cell<infer TSchema extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>> ? input<TSchema> : never

optional

`options?`

type object

optional

returns CellRegistryMap[K]

`add_cell`

type (cell: Cell<any>): void

`cell`

type Cell<any>

returns void

`remove_cell`

type (id: string & $brand<"Uuid">): void

`id`

type Uuid

returns void

CellRegistryMap
#

CellRegistryMap import type {CellRegistryMap} from '@fuzdev/zzz/cell_classes.js';

`Action`

type Action

`Actions`

type Actions

`Capabilities`

type Capabilities

`Parts`

type Parts

`Chat`

type Chat

`Chats`

type Chats

`Diskfile`

type Diskfile

`DiskfileTab`

type DiskfileTab

`DiskfileTabs`

type DiskfileTabs

`DiskfilePart`

type DiskfilePart

`DiskfileHistory`

type DiskfileHistory

`Diskfiles`

type Diskfiles

`DiskfilesEditor`

type DiskfilesEditor

`Job`

type Job

`Jobs`

type Jobs

`Model`

type Model

`Models`

type Models

`Prompt`

type Prompt

`Prompts`

type Prompts

`Provider`

type Provider

`Providers`

type Providers

`Recorder`

type Recorder

`Space`

type Space

`Spaces`

type Spaces

`Terminal`

type Terminal

`TerminalPreset`

type TerminalPreset

`TerminalPresets`

type TerminalPresets

`Terminals`

type Terminals

`Turn`

type Turn

`Thread`

type Thread

`Threads`

type Threads

`Time`

type Time

`TextPart`

type TextPart

`Ui`

type Ui

`Workspace`

type Workspace

`Workspaces`

type Workspaces

CellValueDecoder
#

CellValueDecoder<TSchema, TKey> import type {CellValueDecoder} from '@fuzdev/zzz/cell_helpers.js';

Type helper for decoders that includes base schema properties. Use this instead of ValueParser when creating decoders for cells to properly type the base properties.

generics

CellValueDecoder<TSchema extends z.ZodType, TKey extends keyof z.infer<TSchema> = keyof z.infer<TSchema>>

`TSchema`

constraint z.ZodType

`TKey`

constraint keyof z.infer<TSchema>

default keyof z.infer<TSchema>

Chat
#

import {Chat} from '@fuzdev/zzz/chat.svelte.js';

type Thread | undefined

returns void

`add_threads_by_model_tag`

the number of threads a message was sent to

`send_to_thread`

Sends content to one thread, and auto-names the chat from the first successful exchange.

type (thread_id: string & $brand<"Uuid">, content: string): Promise<Turn | null>

`thread_id`

type Uuid

`content`

type string

returns Promise<Turn | null>

the assistant turn, or null if the send was skipped

`rename`

Renames the chat as the user, which stops auto-naming from replacing the name. A no-op when name is unchanged.

type (name: string): void

`name`

type string

returns void

`init_name_from_turns`

Uses an LLM to name the chat based on the user input and AI response. Only runs while autoname is set, so it never replaces a name the user chose. A failure is retried on a later send, up to CHAT_AUTONAME_ATTEMPTS_MAX attempts, except one that can't change on retry (e.g. an unknown model or an auth error), which ends it at once; the last failure is kept in init_name_error.

type (user_content: string, assistant_content: string): Promise<void>

`user_content`

type string

`assistant_content`

type string

returns Promise<void>

`select_thread`

type (thread_id: (string & $brand<"Uuid">) | null): void

`thread_id`

type Uuid | null

returns void

`reorder_threads`

Reorder threads by moving from one index to another.

type (from_index: number, to_index: number): void

`from_index`

type number

`to_index`

type number

returns void

CHAT_AUTONAME_ATTEMPTS_MAX
#

3 import {CHAT_AUTONAME_ATTEMPTS_MAX} from '@fuzdev/zzz/chat.svelte.js';

How many failed auto-naming attempts a chat makes before giving up.

chat_template_defaults
#

ChatContextmenu.svelte view source

ChatTemplate[]

type ChatTemplate[]

import {chat_template_defaults} from '@fuzdev/zzz/config_defaults.js';

Default chat templates available in the application

ChatContextmenu
#

accepts children

import ChatContextmenu from '@fuzdev/zzz/ChatContextmenu.svelte';

`chat`

type Chat

`children`

type Snippet<[]>

ChatInitializer
#

ChatInitializer.svelte view source

import ChatInitializer from '@fuzdev/zzz/ChatInitializer.svelte';

`chat?`

type Chat

optional

`oninit?`

type (chat_id: string & $brand<"Uuid">) => void

optional

snippet parameters

chat_id Uuid

`heading?`

type string

optional default 'create new chat'

`items?`

type Model[]

optional

ChatJson
#

ChatList.svelte view source

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; name: string; autoname: boolean; thread_ids: (string & $brand<...>)[]; main_input: string; view_mode: "simple" | "multi"; selected_thread_id: (string & $brand<...>) | null; }

import {ChatJson} from '@fuzdev/zzz/chat.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`name`

type string

`autoname`

type string

`view_mode?`

type "simple" | "multi"

`selected_thread_id?`

type string | null

ChatList
#

import ChatList from '@fuzdev/zzz/ChatList.svelte';

ChatListitem
#

ChatListitem.svelte view source

import ChatListitem from '@fuzdev/zzz/ChatListitem.svelte';

`chat`

type Chat

`selected?`

type boolean

optional

ChatOptions
#

ChatOptions import type {ChatOptions} from '@fuzdev/zzz/chat.svelte.js';

inheritance

extends: CellOptions<typeof ChatJson>

Chats
#

import {Chats} from '@fuzdev/zzz/chats.svelte.js';

inheritance

extends: Cell<typeof ChatsJson>

`items`

type IndexedCollection<Chat>

readonly

`selected_id_last_non_null`

type Uuid | null

$state.raw

`selected`

type Chat | undefined

readonly $derived

`selected_id_error`

type boolean

readonly $derived

`show_sort_controls`

Controls visibility of sort controls in the chats list.

type boolean

$state.raw

`ordered_items`

Ordered array of chats derived from the manual_order index.

type Chat[]

readonly $derived

`items_by_name`

type ReadonlyMap<any, Chat>

readonly $derived

`constructor`

type new (options: ChatsOptions): Chats

`options`

type ChatsOptions

`add`

Adds a chat. Without a name it gets a unique default one that auto-naming may replace; a given name is kept unless json.autoname says otherwise.

type (json?: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; autoname?: boolean | undefined; thread_ids?: string[] | undefined; main_input?: string | undefined; view_mode?: "simple" | ... 1 more ... | undefined; selected_thread_id?: string | ... 1 more ... | undefined; } | undefined, select?: boolean | undefined): Chat

`json?`

type ChatJsonInput

optional

`select?`

type boolean

optional

returns Chat

`generate_unique_name`

type (base_name?: string): string

`base_name`

type string

default 'new chat'

returns string

`add_chat`

type (chat: Chat, select?: boolean | undefined): Chat

`chat`

type Chat

`select?`

type boolean

optional

returns Chat

`duplicate`

Duplicates chat with a unique name and fresh, empty threads for the same models — no threads or turns are shared with the original. The duplicate's selected thread mirrors the original's by position, and it inherits autoname, so auto-naming leaves its name alone unless the original's was still a default one. Threads whose model can't be found are skipped.

type (chat: Chat): Chat

`chat`

the chat to duplicate

type Chat

returns Chat

the new chat, unselected

`add_many`

type (chats_json: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; autoname?: boolean | undefined; thread_ids?: string[] | undefined; main_input?: string | undefined; view_mode?: "simple" | ... 1 more ... | undefined; selected_thread_id?: string | ... 1 more ... | undefined; }[], select?: number | ... 1 more ... | undefined): Chat[]

`chats_json`

type ChatJsonInput[]

`select?`

type boolean | number

optional

returns Chat[]

`remove`

Removes a chat, along with its threads unless another chat still has them — which cancels their in-flight completions and removes their turns' parts.

type (id: string & $brand<"Uuid">): void

`id`

type Uuid

returns void

`remove_many`

Removes chats — see remove.

type (ids: (string & $brand<"Uuid">)[]): number

`ids`

type Uuid[]

returns number

the number of chats removed

`select`

type (chat_id: (string & $brand<"Uuid">) | null): Promise<void>

`chat_id`

type Uuid | null

returns Promise<void>

`select_next`

type (): Promise<void>

returns Promise<void>

`navigate_to`

type (chat_id: (string & $brand<"Uuid">) | null, force?: boolean): Promise<void>

`chat_id`

type Uuid | null

`force`

type boolean

default false

returns Promise<void>

`reorder_chats`

type (from_index: number, to_index: number): void

`from_index`

type number

`to_index`

type number

returns void

`toggle_sort_controls`

Toggles the visibility of sort controls in the chats list.

type (value?: boolean): void

`value`

type boolean

default !this.show_sort_controls

returns void

`chat_templates`

type ChatTemplate[]

$state.raw

`get_template_by_id`

type (id: string): ChatTemplate | undefined

`id`

type string

returns ChatTemplate | undefined

`get_default_template`

type (): ChatTemplate

returns ChatTemplate

`selected_id`

type Uuid | null

gettersetter

ChatSchema
#

ChatsContextmenu.svelte view source

ZodCustom<Chat, Chat>

type ZodCustom<Chat, Chat>

import {ChatSchema} from '@fuzdev/zzz/chat.svelte.js';

ChatsContextmenu
#

accepts children

import ChatsContextmenu from '@fuzdev/zzz/ChatsContextmenu.svelte';

`children`

type Snippet<[]>

ChatsJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; items: { id: string & $brand<"Uuid">; ... 7 more ...; selected_thread_id: (string & $brand<...>) | null; }[]; selected_id: string | null; selected_id_last_non_null: string | null; show_sort_controls: boolean; }

import {ChatsJson} from '@fuzdev/zzz/chats.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`items`

type ChatJson[]

`selected_id`

type string | null

`selected_id_last_non_null`

type string | null

`show_sort_controls`

type boolean

ChatsJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; items?: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; ... 4 more ...; selected_thread_id?: string | ... 1 more ... | undefined; }[] | undefined; selected_id?: str...

import type {ChatsJsonInput} from '@fuzdev/zzz/chats.svelte.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

`items?`

type ChatJsonInput[]

`selected_id?`

type string | null

`selected_id_last_non_null?`

type string | null

`show_sort_controls?`

type boolean

ChatsOptions
#

ChatsOptions import type {ChatsOptions} from '@fuzdev/zzz/chats.svelte.js';

inheritance

extends: CellOptions<typeof ChatsJson>

ChatsSchema
#

chat_template.ts view source

ZodCustom<Chats, Chats>

type ZodCustom<Chats, Chats>

import {ChatsSchema} from '@fuzdev/zzz/chats.svelte.js';

ChatTemplate
#

ChatTemplate import type {ChatTemplate} from '@fuzdev/zzz/chat_template.js';

Represents a template for creating a new chat with specific model configurations

`id`

type Uuid

`name`

Human-readable name of the template.

type string

`model_names`

List of model names to include in chats created from this template.

type string[]

ChatThread
#

ChatThread.svelte view source

import ChatThread from '@fuzdev/zzz/ChatThread.svelte';

`thread`

type Thread

`onsend`

type (input: string) => Promise<unknown>

snippet parameters

input string

`focus_key?`

type string | number | null

optional

`pending_element_to_focus_key?`

type Chat

ChatView
#

ChatView.svelte view source

import ChatView from '@fuzdev/zzz/ChatView.svelte';

`chat`

type Chat

ChatViewMode
#

ChatViewMulti.svelte view source

"simple" | "multi"

type "simple" | "multi"

import type {ChatViewMode} from '@fuzdev/zzz/chat.svelte.js';

ChatViewMulti
#

import ChatViewMulti from '@fuzdev/zzz/ChatViewMulti.svelte';

`chat`

type Chat

ChatViewSimple
#

ChatViewSimple.svelte view source

import ChatViewSimple from '@fuzdev/zzz/ChatViewSimple.svelte';

`chat`

type Chat

`thread`

type Thread | undefined

check_dev_server_port
#

dev_server_port.ts view source

(options: DevServerPortOptions): string | null import {check_dev_server_port} from '@fuzdev/zzz/dev_server_port.js';

Checks that the dev UI calls the dev server that serves it.

The UI sends its HTTP RPC calls and file bytes to http://localhost:<PUBLIC_ZZZ_SERVER_PORT> when the variable is set, so a value naming another port sends them to whatever process listens there. Login and the WebSocket don't use the variable and keep working, which makes the misroute easy to miss — so the dev server refuses to start. Unset or blank is fine: the UI then calls the page's own origin.

vite.config.ts runs this when the dev server starts.

`options`

type DevServerPortOptions

returns

string | null

the error to fail the dev server with, or null when the value is consistent

CHUNK_UPLOAD_RETRY_DELAYS
#

chunk_upload.ts view source

readonly number[] import {CHUNK_UPLOAD_RETRY_DELAYS} from '@fuzdev/zzz/chunk_upload.js';

Waits between attempts of one chunk; a chunk fails once these run out.

ChunkUpload
#

chunk_upload.ts view source

import {ChunkUpload} from '@fuzdev/zzz/chunk_upload.js';

One file's upload. create makes the file, enqueue appends each chunk after the ones before it, and flush waits for everything queued.

Each chunk is appended at the offset the upload expects, so one can never land twice or out of order. A request that gets no answer or a server error is retried; when the retry finds the file already grew by exactly this chunk, the earlier attempt landed and the chunk is done. Any other refusal — the file changed underneath, the session ended — fails the upload.

`path`

type string

readonly

`uploaded_bytes`

The file's size as the backend last confirmed it.

type number

`error`

Why the upload failed, once it has.

type string | null

`constructor`

type new (options: ChunkUploadOptions): ChunkUpload

`options`

type ChunkUploadOptions

`create`

Creates the file, empty. Call it once, before any enqueue.

type (): Promise<void>

returns Promise<void>

throws

Error - when the file can't be created — `already exists` for a taken path

`enqueue`

Queues a chunk to append after every chunk queued before it. Chunks queued after the upload failed are dropped.

type (chunk: Blob): void

`chunk`

type Blob

returns void

`flush`

Waits for every queued chunk.

type (): Promise<void>

returns Promise<void>

throws

Error - with the failure when the upload failed

ChunkUploadOptions
#

chunk_upload.ts view source

ChunkUploadOptions import type {ChunkUploadOptions} from '@fuzdev/zzz/chunk_upload.js';

`fetch`

type (input: string, init?: RequestInit | undefined): Promise<Response>

`input`

type string

`init?`

`ms`

type number

returns Promise<unknown>

ClassNotRegisteredError
#

cell_registry.svelte.ts view source

import {ClassNotRegisteredError} from '@fuzdev/zzz/cell_registry.svelte.js';

Error thrown when attempting to instantiate an unregistered class.

inheritance

extends: Error

`class_name`

type string

readonly

`available_classes`

type string[]

readonly

`constructor`

type new (class_name: string, available_classes: string[], options?: ErrorOptions | undefined): ClassNotRegisteredError

`class_name`

type string

`available_classes`

type string[]

`options?`

type ErrorOptions

optional

ClearRestoreButton
#

ClearRestoreButton.svelte view source

accepts children

import ClearRestoreButton from '@fuzdev/zzz/ClearRestoreButton.svelte';

`value`

type string | (string[] & string)

bindable

`restore_icon?`

type Snippet<[]> | string | SvgData

optional default icon_restore

`clear_icon?`

type Snippet<[]> | string | SvgData

optional default icon_clear

`onchange?`

type (FormEventHandler<HTMLButtonElement>) | null

optional

external types

SvelteHTMLElements['button']

click_outside
#

click_outside.svelte.ts view source

(cb: () => void): Attachment<HTMLElement> import {click_outside} from '@fuzdev/zzz/click_outside.svelte.js';

Creates an attachment that calls cb when a mousedown occurs outside the element.

`cb`

type () => void

returns

Attachment<HTMLElement>

completion_create_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ completion_request: ZodObject<{ created: ZodDefault<$ZodBranded<ZodISODateTime, "Datetime", "out">>; provider_name: ZodEnum<...>; model: ZodString; prompt: ZodStrin...

import {completion_create_action_spec} from '@fuzdev/zzz/action_specs.js';

completion_progress_action_spec
#

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ chunk: ZodOptional<ZodObject<{ model: ZodOptional<ZodString>; created_at: ZodOptional<...>; done: ZodOptional<...>; message: ZodOptional<...>; }, $loose>>; _meta: ZodOptional<...>; }, $strict>; out...

import {completion_progress_action_spec} from '@fuzdev/zzz/action_specs.js';

CompletionCreateInput
#

value + type

{ completion_request: { created: string & $brand<"Datetime">; provider_name: "claude" | "chatgpt" | "gemini"; model: string; prompt: string; completion_messages?: { [x: string]: unknown; role: string; content: string; }[] | undefined; }; _meta?: { ...; } | undefined; }

import {CompletionCreateInput} from '@fuzdev/zzz/action_specs.js';

Input for completion_create.

`completion_request`

type CompletionRequest

`_meta?`

type ProgressMeta

CompletionCreateOutput
#

value + type

{ completion_response: { created: string & $brand<"Datetime">; provider_name: "claude" | "chatgpt" | "gemini"; model: string; data: { type: "claude"; value: any; } | { type: "chatgpt"; value: any; } | { ...; }; }; _meta?: { ...; } | undefined; }

import {CompletionCreateOutput} from '@fuzdev/zzz/action_specs.js';

Output for completion_create.

`completion_response`

type CompletionResponse

`_meta?`

type ProgressMeta

CompletionMessage
#

value + type

{ [x: string]: unknown; role: string; content: string; } import {CompletionMessage} from '@fuzdev/zzz/completion_types.js';

`role`

type string

`content`

type string

`[key: string]`

type unknown

CompletionProgressInput
#

value + type

{ chunk?: { [x: string]: unknown; model?: string | undefined; created_at?: string | undefined; done?: boolean | undefined; message?: { [x: string]: unknown; role: string; content: string; } | undefined; } | undefined; _meta?: { ...; } | undefined; }

import {CompletionProgressInput} from '@fuzdev/zzz/action_specs.js';

Input for completion_progress.

TODO improve chunk schema. Today it carries a loose provider-shaped payload (model, created_at, done, message); add done_reason, timing fields (total_duration, load_duration, prompt_eval_*, eval_*), thinking, images, tool_calls as more provider streams land.

`chunk?`

type { [x: string]: unknown; model?: string | undefined; created_at?: string | undefined; done?: boolean | undefined; message?: { [x: string]: unknown; role: string; content: string; } | undefined; }

`_meta?`

type ProgressMeta

CompletionRequest
#

value + type

{ created: string & $brand<"Datetime">; provider_name: "claude" | "chatgpt" | "gemini"; model: string; prompt: string; completion_messages?: { [x: string]: unknown; role: string; content: string; }[] | undefined; }

import {CompletionRequest} from '@fuzdev/zzz/completion_types.js';

`created`

type string & $brand<"Datetime">

`provider_name`

type "claude" | "chatgpt" | "gemini"

`model`

type string

`prompt`

type string

`completion_messages?`

type CompletionMessage[]

CompletionResponse
#

value + type

{ created: string & $brand<"Datetime">; provider_name: "claude" | "chatgpt" | "gemini"; model: string; data: { type: "claude"; value: any; } | { type: "chatgpt"; value: any; } | { ...; }; }

import {CompletionResponse} from '@fuzdev/zzz/completion_types.js';

`created`

type string & $brand<"Datetime">

`provider_name`

type "claude" | "chatgpt" | "gemini"

`model`

type string

`data`

type ProviderData

CompletionRole
#

value + type

string import {CompletionRole} from '@fuzdev/zzz/completion_types.js';

CompletionTruncation
#

CompletionTruncation

type "max_tokens" | "context_window"

import type {CompletionTruncation} from '@fuzdev/zzz/response_helpers.js';

Why a reply was cut off: the output token limit, or (Claude only) the context window.

compute_list_window
#

(options: ListWindowOptions): ListWindow import {compute_list_window} from '@fuzdev/zzz/list_helpers.js';

Computes which rows of a fixed-row-height list to render: those overlapping the visible area plus overscan rows on each side, clamped to the list. A list entirely outside the visible area yields at most the overscan rows at its nearest edge. Without a usable row_height or visible area (say, before the first measurement) it yields the first overscan rows.

`options`

type ListWindowOptions

returns

ListWindow

confirm_unload_while_recording
#

(event: BeforeUnloadEvent, recorder: { readonly active: boolean; } | undefined): void import {confirm_unload_while_recording} from '@fuzdev/zzz/recording_helpers.js';

Handles beforeunload: while the microphone is live, asks the browser to confirm leaving the page, since that ends the recording.

`event`

the beforeunload event

type BeforeUnloadEvent

`recorder`

the app's recorder, if there's an app

type { readonly active: boolean; } | undefined

returns

void

mutates

event — cancels it (`preventDefault` plus the legacy `returnValue`) to ask for confirmation

confirm_unload_with_unsaved_changes
#

(event: BeforeUnloadEvent, diskfiles: Diskfiles | undefined): void import {confirm_unload_with_unsaved_changes} from '@fuzdev/zzz/diskfile_helpers.js';

Handles beforeunload: while any file has unsaved changes (Diskfiles.has_unsaved_changes), asks the browser to confirm leaving the page, since drafts live only in memory.

`event`

the beforeunload event

type BeforeUnloadEvent

`diskfiles`

the app's diskfiles, if there's an app

type Diskfiles | undefined

returns

void

mutates

event — cancels it (`preventDefault` plus the legacy `returnValue`) to ask for confirmation

CONTENT_PREVIEW_LENGTH
#

ContentEditor.svelte view source

100 import {CONTENT_PREVIEW_LENGTH} from '@fuzdev/zzz/constants.js';

ContentEditor
#

accepts children

import ContentEditor from '@fuzdev/zzz/ContentEditor.svelte';

`content`

type string

bindable

`token_count?`

Estimated if not provided and show_stats is true.

snippet parameters

value string

`save_shortcut?`

Where Ctrl+S / Cmd+S triggers onsave — see SaveShortcutScope.

type SaveShortcutScope

optional default 'focused'

ContentPreview
#

ContentPreview.svelte view source

import ContentPreview from '@fuzdev/zzz/ContentPreview.svelte';

type number

ContextmenuEntryCopyToClipboard
#

ContextmenuEntryCopyToClipboard.svelte view source

accepts children

import ContextmenuEntryCopyToClipboard from '@fuzdev/zzz/ContextmenuEntryCopyToClipboard.svelte';

OmitStrict<ComponentProps<typeof ContextmenuEntry>, 'run' | 'children'>

ContextmenuEntryToggle
#

ContextmenuEntryToggle.svelte view source

accepts children

import ContextmenuEntryToggle from '@fuzdev/zzz/ContextmenuEntryToggle.svelte';

`enabled`

type boolean

bindable

`label?`

type string

optional

`children?`

type Snippet<[enabled: boolean]>

optional

snippet parameters

enabled boolean

`icon?`

type SvgData | string | Snippet<[]>

optional default icon_default

`run?`

type ContextmenuRun

optional default

() => {
			enabled = !enabled;
		}

external types

OmitStrict<Partial<ComponentProps<typeof ContextmenuEntry>>, 'children'>

create_action_payload_omitted
#

(budget: number): ActionPayloadOmitted import {create_action_payload_omitted} from '@fuzdev/zzz/action_helpers.js';

(clear: () => void, add: (json: any) => unknown): (value: unknown) => typeof HANDLED import {create_collection_decoder} from '@fuzdev/zzz/cell_helpers.js';

Creates the decoder for a property that holds a collection of cells. An array value replaces the collection's contents — clear, then add for each element — and any other value leaves the collection unchanged. It always returns HANDLED, so the property is never assigned the raw JSON.

`clear`

empties the collection, disposing the items it owns

type () => void

`add`

creates and adds the item for one element's JSON

type (json: any) => unknown

returns

(value: unknown) => unique symbol

a decoder for Cell.decoders

create_derived_index
#

reactive_helpers.svelte.ts view source

<T extends IndexedItem, TResult extends Array<T> = T[]>(options: DerivedIndexOptions<T, TResult>): IndexDefinition<T, TResult>

import {create_derived_index} from '@fuzdev/zzz/indexed_collection_helpers.svelte.js';

Creates an incremental derived collection index.

`options`

type DerivedIndexOptions<T, TResult>

returns

IndexDefinition<T, TResult>

generics

create_derived_index<T extends IndexedItem, TResult extends Array<T> = Array<T>>

`T`

constraint IndexedItem

`TResult`

constraint Array<T>

default Array<T>

create_detached
#

<T>(create: () => T): T import {create_detached} from '@fuzdev/zzz/reactive_helpers.svelte.js';

Runs create outside the current component or effect, so app-level state it constructs (Cells, or any class with $derived fields) outlives it.

Svelte owns a $derived by the effect that was running when it was created, and once that effect is destroyed the derived can stop recomputing — reads return its last cached value. A Cell constructed during component init does exactly that when the component unmounts, while the app keeps using it. Code in onMount or an $effect body runs inside an effect too, so state created there that outlives it goes through here as well, rather than relying on how Svelte treats those effects' deriveds today. Event handlers and async continuations run with no effect and are safe.

create runs untracked in a fresh effect root that is never destroyed (a root survives its parent's teardown), so the deriveds it creates stay live for as long as their state is referenced.

`create`

constructs the state; runs synchronously, untracked

type () => T

returns

T

what create returned

generics

create_detached<T>

`T`

create_file_bytes
#

(fetch: FileBytesFetch, api_url: string, path: string, body?: Blob | BufferSource | null): Promise<FileBytesWriteResult> import {create_file_bytes} from '@fuzdev/zzz/file_bytes.js';

Creates a file from bytes, never replacing one: a taken path fails with already_exists.

`fetch`

the fetch to send with

type FileBytesFetch

`api_url`

the API's URL or path, with no trailing slash

type string

`path`

the new file's absolute path

type string

`body`

the file's first bytes, or null to create it empty

type Blob | BufferSource | null

default null

returns

Promise<FileBytesWriteResult>

Map<T[K], T>

generics

create_map_by_property<T, K extends keyof T>

`T`

`K`

constraint keyof T

create_multi_index
#

<T extends IndexedItem, K>(options: MultiIndexOptions<T, K>): IndexDefinition<T, Map<K, T[]>> import {create_multi_index} from '@fuzdev/zzz/indexed_collection_helpers.svelte.js';

Create a multi-value index (one key maps to many items).

`options`

type MultiIndexOptions<T, K>

returns

IndexDefinition<T, Map<K, T[]>>

generics

create_multi_index<T extends IndexedItem, K>

`T`

constraint IndexedItem

`K`

create_quiet_action_log
#

(log?: ActionLog): ActionLog import {create_quiet_action_log} from '@fuzdev/zzz/action_helpers.js';

Wraps a dispatch log so a failed request of a quiet method (QUIET_ACTION_METHODS) isn't reported; everything else passes through.

`log`

where the rest goes, by default the console

type ActionLog

default console_action_log

returns

ActionLog

create_recorder_deps
#

(): RecorderDeps import {create_recorder_deps} from '@fuzdev/zzz/recorder.svelte.js';

RecorderDeps over the real browser, each global read when it's called.

returns

RecorderDeps

create_session_recheck
#

Dashboard.svelte view source

(options: SessionRecheckOptions): () => Promise<void> import {create_session_recheck} from '@fuzdev/zzz/session_recheck.js';

Create a coalescing session recheck. Calls made while a recheck is in flight share it, so a burst of unauthenticated errors costs one probe.

`options`

type SessionRecheckOptions

returns

() => Promise<void>

a function that rechecks the session and resolves when done (never rejects)

Turn

Dashboard
#

accepts children

import Dashboard from '@fuzdev/zzz/Dashboard.svelte';

`children`

type Snippet<[]>

DashboardActions
#

DashboardActions.svelte view source

import DashboardActions from '@fuzdev/zzz/DashboardActions.svelte';

DashboardCapabilities
#

DashboardCapabilities.svelte view source

import DashboardCapabilities from '@fuzdev/zzz/DashboardCapabilities.svelte';

DashboardChats
#

DashboardChats.svelte view source

import DashboardChats from '@fuzdev/zzz/DashboardChats.svelte';

DashboardDiskfiles
#

DashboardDiskfiles.svelte view source

import DashboardDiskfiles from '@fuzdev/zzz/DashboardDiskfiles.svelte';

DashboardHeader
#

DashboardHeader.svelte view source

accepts children

import DashboardHeader from '@fuzdev/zzz/DashboardHeader.svelte';

`header`

type Snippet<[]>

`children`

type Snippet<[]>

DashboardHome
#

DashboardHome.svelte view source

import DashboardHome from '@fuzdev/zzz/DashboardHome.svelte';

DashboardModels
#

DashboardModels.svelte view source

import DashboardModels from '@fuzdev/zzz/DashboardModels.svelte';

DashboardPrompts
#

DashboardPrompts.svelte view source

import DashboardPrompts from '@fuzdev/zzz/DashboardPrompts.svelte';

DashboardProviders
#

DashboardProviders.svelte view source

import DashboardProviders from '@fuzdev/zzz/DashboardProviders.svelte';

DashboardSettings
#

DashboardSettings.svelte view source

import DashboardSettings from '@fuzdev/zzz/DashboardSettings.svelte';

DEFAULT_AUTO_RECONNECT
#

true import {DEFAULT_AUTO_RECONNECT} from '@fuzdev/zzz/socket_helpers.js';

defined
#

<T>(value: T | undefined): T import {defined} from '@fuzdev/zzz/helpers.js';

`value`

type T | undefined

returns

T

generics

defined<T>

`T`

delete_diskfile
#

(diskfiles: Diskfiles, diskfile: Diskfile): Promise<boolean> import {delete_diskfile} from '@fuzdev/zzz/diskfile_helpers.js';

Deletes diskfile on disk (see Diskfiles.delete), alerting on failure with its path first (couldn't delete a.txt: <backend message>), like prompt_create_diskfile. The failure is already logged by the action handler.

`diskfiles`

the diskfiles to delete from

type Diskfiles

`diskfile`

the file to delete

type Diskfile

returns

Promise<boolean>

whether the file was deleted

DerivedIndexOptions
#

DerivedIndexOptions<T, TResult> import type {DerivedIndexOptions} from '@fuzdev/zzz/indexed_collection_helpers.svelte.js';

Options for derived indexes.

generics

DerivedIndexOptions<T extends IndexedItem, TResult extends Array<T> = Array<T>>

`T`

constraint IndexedItem

`TResult`

constraint Array<T>

default Array<T>

inheritance

extends: IndexOptions<T>

`compute`

Function that computes the derived collection from the full collection.

type (collection: IndexedCollection<T>): TResult

`collection`

type IndexedCollection<T>

returns TResult

`sort?`

Optional sort function for the derived array. compute's result is copied before sorting, so compute can return an array it doesn't own (like collection.values).

type (a: T, b: T): number

`a`

type T

`b`

type T

returns number

`onadd?`

Optional custom add handler.

type (items: TResult, item: T, collection: IndexedCollection<T>): TResult

`items`

type TResult

`item`

type T

`collection`

import DeskMenu from '@fuzdev/zzz/DeskMenu.svelte';

detect_reorderable_direction
#

dev_server_port.ts view source

(element: HTMLElement): ReorderableDirection import {detect_reorderable_direction} from '@fuzdev/zzz/reorderable_helpers.js';

Detect layout direction from an element - supports flex and grid.

`element`

type HTMLElement

returns

ReorderableDirection

DEV_SERVER_PORT_VAR
#

"PUBLIC_ZZZ_SERVER_PORT" import {DEV_SERVER_PORT_VAR} from '@fuzdev/zzz/dev_server_port.js';

The env var the dev UI builds its absolute server URL from (SERVER_URL in constants.ts).

DevServerPortOptions
#

dev_server_port.ts view source

DevServerPortOptions import type {DevServerPortOptions} from '@fuzdev/zzz/dev_server_port.js';

`loaded`

The value of DEV_SERVER_PORT_VAR as Vite loaded it, undefined when unset.

type string | undefined

`port`

The port the dev server is about to serve on.

type number

`from_process_env`

Whether the loaded value came from the process environment rather than an env file.

type boolean

`mode`

The Vite mode, which names the env file (.env.<mode>).

type string

directory_create_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; }, $strict>; output: ZodNull; async: true; description: string; }

import {directory_create_action_spec} from '@fuzdev/zzz/action_specs.js';

DirectoryCreateInput
#

diskfile.svelte.ts view source

value + type

{ path: string & $brand<"DiskfilePath">; } import {DirectoryCreateInput} from '@fuzdev/zzz/action_specs.js';

Input for directory_create.

`path`

type string & $brand<"DiskfilePath">

Diskfile
#

import {Diskfile} from '@fuzdev/zzz/diskfile.svelte.js';

inheritance

extends: Cell<typeof DiskfileJson>

`path`

type DiskfilePath

$state.raw

`source_dir`

$state.raw

`content`

type string | null

$state.raw

`mtime`

type number | null

$state.raw

`deleted_on_disk`

The file is gone from disk, but this diskfile is kept because a tab holds unsaved edits for it. Transient client state, not serialized — cleared when the path reappears on disk. Set it through Diskfiles.set_deleted_on_disk, which keeps the index's directories in step.

type number

readonly $derived

`content_preview`

type string

readonly $derived

`constructor`

type new (options: DiskfileOptions): Diskfile

`options`

type DiskfileOptions

DISKFILE_CONTENT_NOT_LOADED_MESSAGE
#

"content not loaded — the file is over 4 MiB, not UTF-8 text, or unreadable" import {DISKFILE_CONTENT_NOT_LOADED_MESSAGE} from '@fuzdev/zzz/diskfile_helpers.js';

Why a diskfile's content can be missing: the backend indexes a file's content only when it's a UTF-8 text file of at most 4 MiB that it could read, and sends contents: null otherwise.

DISKFILE_CONTENT_NOT_LOADED_PLACEHOLDER
#

"[content not loaded — the file is over 4 MiB, not UTF-8 text, or unreadable]" import {DISKFILE_CONTENT_NOT_LOADED_PLACEHOLDER} from '@fuzdev/zzz/diskfile_helpers.js';

Stands in for a file part's content in a formatted prompt when the file's content wasn't loaded, so the omission is visible — to the user in the preview and copied text, and to a model — instead of the file silently dropping out.

diskfile_create_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; content: ZodString; }, $strict>; output: ZodNull; async: true; description: string; }

import {diskfile_create_action_spec} from '@fuzdev/zzz/action_specs.js';

diskfile_delete_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; }, $strict>; output: ZodNull; async: true; description: string; }

import {diskfile_delete_action_spec} from '@fuzdev/zzz/action_specs.js';

DISKFILE_HISTORY_MAX_CONTENT_LENGTH
#

number import {DISKFILE_HISTORY_MAX_CONTENT_LENGTH} from '@fuzdev/zzz/diskfile_history.svelte.js';

Default cap on the total content length (UTF-16 code units) a DiskfileHistory keeps — about four versions of a file at the 4 MiB index cap.

DISKFILE_HISTORY_MAX_ENTRIES
#

prompt_helpers.ts view source

100 import {DISKFILE_HISTORY_MAX_ENTRIES} from '@fuzdev/zzz/diskfile_history.svelte.js';

Default cap on the number of entries a DiskfileHistory keeps.

DISKFILE_PART_STATUS_ATTRIBUTES
#

ReadonlySet<string>

type ReadonlySet<string>

import {DISKFILE_PART_STATUS_ATTRIBUTES} from '@fuzdev/zzz/prompt_helpers.js';

The XML attributes format_prompt_content sets on a file part's tag to say it sends an unsaved draft. While it does, a user attribute with one of these keys is left out, so the tag never says both; a file part sending the disk content keeps the user's.

DISKFILE_TABS_CLOSED_MAX
#

50 import {DISKFILE_TABS_CLOSED_MAX} from '@fuzdev/zzz/diskfile_tabs.svelte.js';

How many closed tabs DiskfileTabs remembers, both for reopening (recently_closed_tabs) and for back/forward navigation to them (closed_tab_diskfiles) — the oldest are forgotten first.

diskfile_update_action_spec
#

DiskfileActions.svelte view source

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; content: ZodString; }, $strict>; output: ZodNull; async: true; description: string; }

import {diskfile_update_action_spec} from '@fuzdev/zzz/action_specs.js';

DiskfileActions
#

import DiskfileActions from '@fuzdev/zzz/DiskfileActions.svelte';

`diskfile`

type Diskfile

`editor_state`

type DiskfileEditorState

`readonly?`

type boolean

optional default false

`auto_save?`

type boolean

optional default false

DiskfileAudioView
#

DiskfileAudioView.svelte view source

import DiskfileAudioView from '@fuzdev/zzz/DiskfileAudioView.svelte';

`diskfile`

type Diskfile

DiskfileChange
#

value + type

{ type: "add" | "change" | "touch" | "delete"; path: string & $brand<"DiskfilePath">; } import {DiskfileChange} from '@fuzdev/zzz/diskfile_types.js';

`type`

type "add" | "change" | "touch" | "delete"

`path`

type string & $brand<"DiskfilePath">

DiskfileChangeTracker
#

DiskfileChangeTracker import type {DiskfileChangeTracker} from '@fuzdev/zzz/diskfiles.svelte.js';

Records what filer_change reports while a file-tree snapshot is in flight.

inheritance

extends: DiskfileSnapshotChanges

`stop`

Stops recording.

type (): void

returns void

DiskfileChangeType
#

DiskfileCloseDialog.svelte view source

value + type

"add" | "change" | "touch" | "delete"

type "add" | "change" | "touch" | "delete"

import {DiskfileChangeType} from '@fuzdev/zzz/diskfile_types.js';

What happened to a file the backend indexes:

add — it's newly indexed
change — its contents differ
touch — its metadata changed and the contents the backend holds for it didn't (a touch, a rewrite of the same bytes), so they aren't sent again. The backend holds no contents for a file it didn't load (contents: null), so every change to such a file is a touch
delete — it's gone

DiskfileCloseDialog
#

import DiskfileCloseDialog from '@fuzdev/zzz/DiskfileCloseDialog.svelte';

DiskfileConflictNotice
#

DiskfileConflictNotice.svelte view source

import DiskfileConflictNotice from '@fuzdev/zzz/DiskfileConflictNotice.svelte';

`editor_state`

type DiskfileEditorState

`onresolve?`

Called after the user overwrites or reloads, e.g. to refocus the editor.

type () => void

optional

`attrs?`

type HTMLAttributes<HTMLDivElement>

optional

DiskfileContentKind
#

DiskfileEditorNav.svelte view source

DiskfileContentKind

type "audio" | "transcript" | "markdown" | "other"

import type {DiskfileContentKind} from '@fuzdev/zzz/diskfile_content_kind.js';

audio gets the player, transcript (a transcription's sidecar) the segment view, markdown the source beside its preview, and other the text editor.

DiskfileContextmenu
#

type string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">

import {DiskfileDirectoryPath} from '@fuzdev/zzz/diskfile_types.js';

These always have a trailing slash.

external types

z.infer<typeof DiskfileDirectoryPath>

DiskfileEditorNav
#

import DiskfileEditorNav from '@fuzdev/zzz/DiskfileEditorNav.svelte';

`editor_state`

type DiskfileEditorState

DiskfileEditorState
#

DiskfileEditorView.svelte view source

import {DiskfileEditorState} from '@fuzdev/zzz/diskfile_editor_state.svelte.js';

The editing state of one file, shared by every view of it — the /files editor, file-part editors, tabs — and kept while none is mounted, like a VS Code text model. Get it with Diskfiles.get_editor_state, which creates it on first use and keeps it until the diskfile is removed; views never own it.

It holds the file's DiskfileHistory, and records every change of the file's content on disk into it (Diskfiles.upsert calls check_disk_changes), whether or not an editor shows it:

The editor shows the selected history entry (current_content), or the disk content when none is selected. A clean editor follows the disk.
Editing keeps the file's one draft: a single unsaved-edit entry, updated in place and re-dated on each edit. Editing from another entry (an older state picked from the history) starts a new draft and sets the old one aside as a discarded-edit entry, so its text stays restorable.
When the disk changes under a draft, or under a picked entry, the edit is kept and has_conflict is set: saving stops until the user chooses to overwrite (save_changes({overwrite: true})) or reload from disk (discard_draft). Our own save's broadcast never counts — the disk then holds the edit, which settles it. The check is frontend-only: an external write landing after the backend received our save but before its broadcast reached us isn't seen as a conflict.

`app`

type Frontend

readonly

type string | null

readonly $derived.by

`path`

type DiskfilePath

readonly $derived.by

`content_loaded`

Whether the file's content was loaded (see Diskfile.content_loaded). When it wasn't, the editor is read-only: edits are ignored and nothing can be saved, since a save would overwrite a file nobody has seen.

type boolean

readonly $derived

`markdown_view_mode`

The mode the markdown view shows this file in: the user's choice, else split, or preview while the content isn't loaded (read-only).

type MarkdownViewMode

readonly $derived

`has_changes`

type boolean

readonly $derived.by

`can_save`

Whether saving would write anything. Always true for a file deleted on disk — saving recreates it even when the content matches its last state. Never true when the content wasn't loaded.

type boolean

readonly $derived.by

`has_conflict`

Whether the editor shows the user's content over a disk change it predates (see disk_conflict). While true, save_changes refuses unless asked to overwrite.

`has_history`

type boolean

readonly $derived

`has_unsaved_edits`

type boolean

readonly $derived.by

`dirty`

Whether the file is marked modified (the tab's and explorer's ●): it has a draft, or the editor shows something other than the disk content.

Percent change in length from the original. Growth from an empty original reads as 100% (no change reads as 0%).

type number

readonly $derived

`original_token_count`

type number

readonly $derived.by

`current_token_count`

type number

readonly $derived

`token_diff`

type number

readonly $derived

`token_diff_percent`

Percent change in token count from the original — see length_diff_percent.

type number

readonly $derived

`constructor`

type new (options: { app: Frontend; diskfile: Diskfile; }): DiskfileEditorState

`options`

type { app: Frontend; diskfile: Diskfile; }

`dispose`

Disposes the history. Called by Diskfiles when the diskfile goes away.

type (): void

returns void

`check_disk_changes`

Records the diskfile's content in the history if it changed on disk since last seen. Diskfiles.upsert calls it for every content change, so the history tracks the disk whether or not an editor shows the file; calling it again is a no-op.

A clean editor moves to the new disk content. An editor showing the user's content keeps it, and the change becomes a disk_conflict — unless it's that very content (e.g. our own save's broadcast, landing after an external edit's), which settles the editor, or the content of the save in flight (our own write, with typing continuing past it).

type (): void

returns void

`save_changes`

Save changes to the diskfile. History, selection, and the modified flag change only once the write succeeds; a failure leaves the edit unsaved and sets save_error — including a write that throws, so this never rejects. One save runs at a time: saving while a write is in flight queues a single follow-up save (repeat calls share it) that writes whatever the editor holds once the first settles — skipped if that write failed. If the editor or the disk moves on while the write is in flight — more typing, another history entry picked, an external edit landing after the save's own — the saved content is recorded in history without taking over the editor.

Refuses, writing nothing, while has_conflict — unless overwrite — so a change made on disk under the edit is never overwritten silently. A file whose content wasn't loaded is never saved: this sets save_error.

type (options?: DiskfileSaveOptions | undefined): Promise<boolean>

`options?`

type DiskfileSaveOptions

optional

returns Promise<boolean>

whether the content was written — for a queued follow-up with nothing left to write, whether the in-flight save succeeded

`save_draft`

Saves the draft — "save" when closing a tab, "overwrite with your draft" on a conflict — whatever history entry the editor shows: it shows the draft first, then saves as save_changes does. Without a draft, saves what the editor shows.

type (options?: DiskfileSaveOptions | undefined): Promise<boolean>

`options?`

type DiskfileSaveOptions

optional

returns Promise<boolean>

see save_changes

`discard_draft`

Drops the edit in favor of the disk — "reload from disk" on a conflict, "don't save" on closing a tab: shows the disk content, setting the draft aside as a discarded-edit entry so its text stays in the history (until the history caps or a clear drop it). A file deleted on disk that was kept only for the draft is then forgotten (Diskfiles.release_if_unneeded), disposing this state.

type (): void

returns void

`reset_view`

Resets what the editor shows when the file's last tab closes, so reopening it shows the draft if there is one, else the disk content.

type (): void

returns void

`set_content_from_history`

Shows history entry id in the editor. Picking an entry changes nothing else — editing it is what starts a draft.

type (id: string & $brand<"Uuid">): void

`id`

type Uuid

returns void

`clear_history`

Clears the history down to the unsaved edits and the entry for the disk content — the newest saved entry holding it, else a new one, never an older state that would show as a change to save — which becomes the original state. A selection it removes moves to that entry. For a file whose content wasn't loaded, the newest saved entry is kept instead.

type (): void

returns void

`clear_unsaved_edits`

Deletes the unsaved edits from the history. If the editor showed one, it moves to the disk content.

type (): void

returns void

`current_content`

The editor's text: the selected history entry's, else the disk content. Always '' when the content isn't loaded — earlier text in history (from before the file grew past the index cap, say) isn't what's on disk, so the read-only editor never shows or copies it.

type string

gettersetter

DiskfileEditorView
#

import DiskfileEditorView from '@fuzdev/zzz/DiskfileEditorView.svelte';

`diskfile`

type Diskfile

`onmodified?`

type (diskfile_id: string & $brand<"Uuid">) => void

optional

snippet parameters

diskfile_id Uuid

DiskfileExplorer
#

DiskfileExplorer.svelte view source

import DiskfileExplorer from '@fuzdev/zzz/DiskfileExplorer.svelte';

`empty?`

type Snippet<[]>

optional

DiskfileHistory
#

import {DiskfileHistory} from '@fuzdev/zzz/diskfile_history.svelte.js';

Stores edit history for a single diskfile, newest first. Owned by the file's app-level DiskfileEditorState, which keeps at most one unsaved edit in it.

Capped by max_entries and max_content_length: adding or growing an entry drops the oldest entries past either cap (discarded edits included), but never an unsaved edit, the newest saved state, or the caller's keep_id — so the caps can be exceeded only by those.

inheritance

extends: Cell<typeof DiskfileHistoryJson>

`path`

type DiskfilePath

$state.raw

`entries`

type HistoryEntry[]

$state

`max_entries`

type number

$state.raw

`max_content_length`

type number

$state.raw

`current_entry`

The most recent history entry (by creation timestamp) Since entries are always kept sorted by creation time (newest first), the most recent is always the first element.

type HistoryEntry | null

readonly $derived

`draft_entry`

The newest entry holding unsaved user edits — the file's draft.

type HistoryEntry | null

readonly $derived

`has_unsaved_edits`

Whether any entry holds unsaved user edits.

type boolean

readonly $derived

`constructor`

type new (options: DiskfileHistoryOptions): DiskfileHistory

`options`

type DiskfileHistoryOptions

`add_entry`

Add a new history entry — or return the current one when it's a duplicate: the same content, the same kind (an unsaved edit, a discarded edit, or a saved state — each defaulting to a saved state when not given), and the same is_disk_change / is_original_state / label wherever options sets them. So adding a saved state never returns a draft or a discarded edit that happens to hold its content.

type (content: string, options?: DiskfileHistoryAddEntryOptions): { id: string & $brand<"Uuid">; created: number; content: string; label: string; is_disk_change: boolean; is_unsaved_edit: boolean; is_original_state: boolean; is_discarded_edit: boolean; }

`content`

type string

`options`

type DiskfileHistoryAddEntryOptions

default EMPTY_OBJECT

returns HistoryEntry

`update_entry_content`

Replaces the content of entry id and dates it now, moving it to the front — how a draft tracks the latest edit.

type (id: string & $brand<"Uuid">, content: string): { id: string & $brand<"Uuid">; created: number; content: string; label: string; is_disk_change: boolean; is_unsaved_edit: boolean; is_original_state: boolean; is_discarded_edit: boolean; } | undefined

`id`

type Uuid

`content`

type string

returns HistoryEntry | undefined

the entry, or undefined if it's gone

`remove_entry`

Removes entry id.

type (id: string & $brand<"Uuid">): boolean

`id`

type Uuid

returns boolean

whether it existed

`find_entry_by_id`

Find a history entry by id.

type (id: string & $brand<"Uuid">): { id: string & $brand<"Uuid">; created: number; content: string; label: string; is_disk_change: boolean; is_unsaved_edit: boolean; is_original_state: boolean; is_discarded_edit: boolean; } | undefined

`id`

type Uuid

returns HistoryEntry | undefined

`get_content`

Get the content of a specific history entry.

type (id: string & $brand<"Uuid">): string | null

`id`

type Uuid

returns string | null

`clear_except_current`

Clear all history entries except the most recent one by creation time and any entries that match the optional keep predicate.

type (keep?: ((entry: { id: string & $brand<"Uuid">; created: number; content: string; label: string; is_disk_change: boolean; is_unsaved_edit: boolean; is_original_state: boolean; is_discarded_edit: boolean; }) => boolean) | undefined): void

`keep?`

type

(entry: { id: string & $brand<"Uuid">; created: number; content: string; label: string; is_disk_change: boolean; is_unsaved_edit: boolean; is_original_state: boolean; is_discarded_edit: boolean; }) => boolean

optional

returns void

DiskfileHistoryAddEntryOptions
#

DiskfileHistoryAddEntryOptions import type {DiskfileHistoryAddEntryOptions} from '@fuzdev/zzz/diskfile_history.svelte.js';

DiskfileHistoryJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; path: string & $brand<"DiskfilePath">; entries: { ...; }[]; max_entries: number; max_content_length: number; }

import {DiskfileHistoryJson} from '@fuzdev/zzz/diskfile_history.svelte.js';

Schema for the DiskfileHistory cell.

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`path`

type string & $brand<"DiskfilePath">

`entries`

type HistoryEntry[]

`max_entries`

type number

`max_content_length`

type number

DiskfileHistoryJsonInput
#

DiskfileInfo.svelte view source

{ path: string; id?: string | undefined; created?: string | undefined; updated?: string | undefined; entries?: { created: number; content: string; label: string; id?: string | undefined; is_disk_change?: boolean | undefined; is_unsaved_edit?: boolean | undefined; is_original_state?: boolean | undefined; is_discarded...

optional

DiskfileInfo
#

import DiskfileInfo from '@fuzdev/zzz/DiskfileInfo.svelte';

`diskfile`

type Diskfile

`editor_state`

type DiskfileEditorState

DiskfileJson
#

DiskfileListitem.svelte view source

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; path: string & $brand<"DiskfilePath">; ... 4 more ...; dependencies: [...][]; }

import {DiskfileJson} from '@fuzdev/zzz/diskfile_types.js';

A file on disk. path and source_dir are required — a diskfile is always for one file. content is null when it wasn't loaded (see Diskfile.content_loaded).

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`path`

type string & $brand<"DiskfilePath">

`source_dir`

type string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">

`content`

type string | null

`mtime`

When the file was last modified on disk, in milliseconds since the epoch — null when the backend couldn't say. It moves whenever the file's bytes do, including for a file whose content isn't loaded.

`content?`

type string | null

`mtime?`

type number | null

`dependents?`

type [string, any][]

`dependencies?`

type [string, any][]

DiskfileListitem
#

import DiskfileListitem from '@fuzdev/zzz/DiskfileListitem.svelte';

`diskfile`

type Diskfile

`selected?`

type boolean

optional default false

`attrs?`

type Record<string, unknown>

optional

`onselect?`

open_not_preview indicates a "open_not_preview select" like a doubleclick or enter keypress.

type (diskfile: Diskfile, open_not_preview: boolean) => void

optional

snippet parameters

diskfile Diskfile

open_not_preview boolean

DiskfileMarkdownView
#

DiskfileMarkdownView.svelte view source

import DiskfileMarkdownView from '@fuzdev/zzz/DiskfileMarkdownView.svelte';

`diskfile`

type Diskfile

`onmodified?`

type (diskfile_id: string & $brand<"Uuid">) => void

optional

snippet parameters

diskfile_id Uuid

DiskfileMetrics
#

DiskfileMetrics.svelte view source

import DiskfileMetrics from '@fuzdev/zzz/DiskfileMetrics.svelte';

`editor_state`

type DiskfileEditorState

DiskfileOptions
#

diskfile.svelte.ts view source

DiskfileOptions import type {DiskfileOptions} from '@fuzdev/zzz/diskfile.svelte.js';

inheritance

extends: CellOptions<typeof DiskfileJson>

DiskfilePart
#

DiskfilePartDraftLabel.svelte view source

import {DiskfilePart} from '@fuzdev/zzz/part.svelte.js';

Diskfile part - references content from a Diskfile.

inheritance

extends: Part<typeof DiskfilePartJson>

`type`

type "diskfile"

readonly

`diskfile`

The diskfile at path. One deleted on disk counts as missing unless it has a draft — then it's kept for the draft (see Diskfiles.remove_by_path), which the part shows and sends.

type Diskfile | null | undefined

readonly $derived.by

`draft_status`

How content relates to the disk: 'unsaved' when it's the file's draft, 'conflict' when that draft predates a change on disk, 'deleted' when the file is gone from disk and only the draft remains, else null (the disk content).

type "unsaved" | "conflict" | "deleted" | null

readonly $derived.by

`relative_path`

type string | null | undefined

readonly $derived

`constructor`

type new (options: DiskfilePartOptions): DiskfilePart

`options`

type DiskfilePartOptions

`path`

Writable value that determines this.diskfile. Also includes special diskfile part logic for attributes.

type DiskfilePath | null

gettersetter

`content`

The file's draft if it has one (draft_status says so), else its disk content — never merely an older history entry an editor is viewing. Read-only: the part never writes to disk. Edits go through the file's DiskfileEditorState, whose save_changes reports failures.

undefined when there's no file at path, null when the file's content wasn't loaded (Diskfile.content_loaded) — never an editor's empty text, so an unloaded file can't pass for an empty one.

type string | null | undefined

getter

DiskfilePartDraftLabel
#

import DiskfilePartDraftLabel from '@fuzdev/zzz/DiskfilePartDraftLabel.svelte';

`part`

type DiskfilePart

DiskfilePartJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; name: string; start: number | null; end: number | null; ... 7 more ...; has_xml_tag: boolean; }

import {DiskfilePartJson} from '@fuzdev/zzz/part.svelte.js';

Diskfile part schema - references a diskfile.

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string

`updated?`

DiskfilePartOptions
#

DiskfilePartOptions

type PartOptions<ZodObject<{ id: ZodDefault<$ZodBranded<ZodUUID, "Uuid", "out">>; created: ZodDefault<$ZodBranded<ZodISODateTime, "Datetime", "out">>; updated: ZodDefault<$ZodBranded<ZodISODateTime, "Datetime", "out">>; name: ZodDefault<ZodString>; start: ZodDefault<ZodNullable<ZodNumber>>; end: ZodDefault<ZodNullable<ZodNumber>>; xml_tag_name: ZodDefault<ZodString>; attributes: ZodDefault<ZodArray<ZodObject<{ id: ZodDefault<$ZodBranded<ZodUUID, "Uuid", "out">>; key: ZodDefault<ZodString>; value: ZodDefault<ZodString>; }, $strict>>>; enabled: ZodDefault<ZodBoolean>; title: ZodDefault<ZodNullable<ZodString>>; summary: ZodDefault<ZodNullable<ZodString>>; type: ZodDefault<ZodLiteral<"diskfile">>; path: ZodDefault<ZodNullable<$ZodBranded<ZodString, "DiskfilePath", "out">>>; has_xml_tag: ZodDefault<ZodDefault<ZodBoolean>>; }, $strict>>

import type {DiskfilePartOptions} from '@fuzdev/zzz/part.svelte.js';

`json?`

type DiskfilePartJsonInput

`app`

type Frontend

DiskfilePartSchema
#

DiskfilePartView.svelte view source

ZodCustom<DiskfilePart, DiskfilePart>

type ZodCustom<DiskfilePart, DiskfilePart>

import {DiskfilePartSchema} from '@fuzdev/zzz/part.svelte.js';

DiskfilePartView
#

import DiskfilePartView from '@fuzdev/zzz/DiskfilePartView.svelte';

`diskfile`

type Diskfile

DiskfilePath
#

DiskfilePickerDialog.svelte view source

value + type

string & $brand<"DiskfilePath">

type string & $brand<"DiskfilePath">

import {DiskfilePath} from '@fuzdev/zzz/diskfile_types.js';

An absolute Unix-style file path.

external types

z.infer<typeof DiskfilePath>

DiskfilePickerDialog
#

import DiskfilePickerDialog from '@fuzdev/zzz/DiskfilePickerDialog.svelte';

`onpick`

type (diskfile: Diskfile | undefined) => boolean | void

snippet parameters

diskfile Diskfile | undefined

`show?`

type boolean

optional bindable default false

`filter?`

type (diskfile: Diskfile) => boolean

optional

snippet parameters

diskfile Diskfile

`exclude_ids?`

type Uuid[]

optional

`selected_ids?`

type Uuid[]

optional

`dialog_props?`

type

OmitStrict<Omit<HTMLDialogAttributes, "children" | "onclose"> & { show?: boolean | undefined; align?: DialogAlign | undefined; dismissable?: boolean | undefined; content_selector?: string | undefined; onbeforeclose?: (() => boolean | void) | undefined; onclose?: (() => void) | undefined; children: Snippet<[dialog: DialogContext]>; }, "children">

optional

Diskfiles
#

import {Diskfiles} from '@fuzdev/zzz/diskfiles.svelte.js';

inheritance

extends: Cell<typeof DiskfilesJson>

`items`

type IndexedCollection<Diskfile>

readonly

`selected_file_id`

type Uuid | null

$state.raw

`selected_file`

A path an add, change, or delete reported keeps what the notification left: the snapshot's entry for it is skipped, and it isn't pruned. So a file deleted meanwhile isn't resurrected and newer content isn't reverted.
A touch never makes the snapshot yield, because it carries no contents: a client that missed a change while disconnected holds old text, and only the snapshot can replace it. The snapshot's entry is applied (or the file pruned, if the snapshot lacks it), and then the path's latest touch is applied again — unless an add, change, or delete was also reported for the path, whose result already stands.

The touch's metadata wins over the snapshot's whichever mtime is higher. The two can't be ordered from here — a notification that arrives during the request may have been sent before or after the backend read its index for the snapshot, and a file's mtime can move backwards — but the backend queues a notification for every change to its index, so its notifications converge on the index: if the snapshot was the newer of the two, whatever moved the file past the touch has its own notification still to come, and that one settles it. Preferring the snapshot would have no such correction when the touch was the newer.

type (): DiskfileChangeTracker

returns DiskfileChangeTracker

`handle_change`

Applies a filer_change notification. add and change both upsert by path — the backend's add/change split is advisory, and a re-seed or a missed delete must never leave two diskfiles for one path. A touch carries no contents (see touch).

type (params: { change: { path: string & $brand<"DiskfilePath">; type: "add" | "change" | "delete"; }; disknode: { id: string & $brand<"DiskfilePath">; source_dir: string & $brand<...> & $brand<...>; ... 4 more ...; dependencies: [...][]; }; } | { ...; }): void

`params`

type FilerChangeInput

returns void

`touch`

Applies a touch: the file's metadata changed on disk and the contents the backend holds for it did not, so the diskfile keeps the content it has — loaded or not — and takes the new mtime. For a file whose content isn't loaded the backend holds none, so every change to it arrives this way. Nothing else changes: no editor state is notified, since there's no new content to weigh against a draft.

A path this client doesn't hold is left alone (there are no contents to add it with — the next snapshot brings it), as is a diskfile kept after its file was deleted, whose content is no longer the file's.

type (metadata: { id: string & $brand<"DiskfilePath">; source_dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; ctime: number | null; mtime: number | null; dependents: [...][]; dependencies: [...][]; }): boolean

`metadata`

type DisknodeMetadata

returns boolean

whether a diskfile was updated

`add`

Adds a diskfile. It isn't selected: a file appearing on disk — seeded by a snapshot, or created by another tool — never moves the selection or opens a tab. Only create_file selects the file it creates.

type (json: { path: string; source_dir: string; id?: string | undefined; created?: string | undefined; updated?: string | undefined; content?: string | null | undefined; mtime?: number | null | undefined; dependents?: [...][] | undefined; dependencies?: [...][] | undefined; }): Diskfile

`json`

type DiskfileJsonInput

returns Diskfile

`get_editor_state`

The app-level editing state of diskfile (its draft, history, and save state), created on first use and kept until the diskfile is removed — views read it, they don't own it. Safe to call from component init or a $derived: it's created detached from the calling effect, and reading it doesn't track the lookup. A diskfile no longer in the collection gets a throwaway state.

type (diskfile: Diskfile): DiskfileEditorState

`diskfile`

type Diskfile

returns DiskfileEditorState

`find_editor_state`

The editing state of diskfile id if one was created — see get_editor_state.

type (id: string & $brand<"Uuid">): DiskfileEditorState | undefined

`id`

type Uuid

returns DiskfileEditorState | undefined

`upsert`

Adds a diskfile for disknode, or updates the existing one at the same path in place — keeping its id, so tabs, selection, and parts stay attached. A diskfile kept after a delete (see remove_by_path) is reattached this way when its path reappears on disk. An existing diskfile whose content and dependency data already match is left untouched but for its mtime, so a resync that re-sends every file doesn't churn the unchanged ones. A content change is recorded in the file's editing state, if it has one (DiskfileEditorState.check_disk_changes).

type (disknode: { id: string & $brand<"DiskfilePath">; source_dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; contents: string | null; ctime: number | null; mtime: number | null; dependents: [...][]; dependencies: [...][]; }): Diskfile

`disknode`

type SerializableDisknode

returns Diskfile

`add_initial`

Seed diskfiles from an initial file tree (e.g. session load or workspace open). Upserts by path, so overlapping seeds don't duplicate.

type (files: { id: string & $brand<"DiskfilePath">; source_dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; contents: string | null; ctime: number | null; mtime: number | null; dependents: [...][]; dependencies: [...][]; }[], changes?: DiskfileSnapshotChanges | undefined): void

`files`

the snapshot's file tree

type SerializableDisknode[]

`changes?`

what filer_change reported while the snapshot was in flight (see track_changes)

type DiskfileSnapshotChanges

optional

returns void

`reconcile`

Replaces the file tree under roots with a session snapshot's: upserts every snapshot file (like add_initial), and removes each known file under a root that the snapshot lacks, via remove_by_path — so a file open with unsaved edits is kept, flagged deleted_on_disk. Files outside every root are left alone, since the snapshot says nothing about them.

type (files: { id: string & $brand<"DiskfilePath">; source_dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; contents: string | null; ctime: number | null; mtime: number | null; dependents: [...][]; dependencies: [...][]; }[], roots: readonly string[], options?: { ...; } | undefined): void

`files`

the snapshot's file tree

type SerializableDisknode[]

`roots`

the directories (trailing /) whose complete trees files holds

type readonly string[]

`options?`

type { changes?: DiskfileSnapshotChanges | undefined; skip_dirs?: readonly string[] | undefined; }

optional

returns void

`remove_by_path`

Handles the diskfile at path being gone from disk.

Writes content to the file at path. The local Diskfile changes only when the resulting filer_change broadcast arrives, not from the response.

Refuses, without sending, to write over a known file whose content wasn't loaded (Diskfile.content_loaded — over 4 MiB, not UTF-8 text, or unreadable): nobody has seen what it would overwrite. Fails with conflict (data.reason content_not_loaded).

type (path: string & $brand<"DiskfilePath">, content: string): Promise<Result<{ value: null; }, { error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }; }>>

`path`

type DiskfilePath

`content`

type string

returns Promise<Result>

the RPC result — on failure, callers surface error themselves

`delete`

Deletes the file at path on disk. The file leaves the index when its filer_change arrives.

type (path: string & $brand<"DiskfilePath">): Promise<void>

`path`

type DiskfilePath

returns Promise<void>

throws

Error - with the backend's message when the delete fails

`new_files_dir`

The directory new files and folders are created in: the active workspace's, null when no workspace is open.

type DiskfileDirectoryPath | null

readonly $derived

`indexed_roots`

The directories the file index covers, each with a trailing /: the app directory, the scoped dirs, and the open workspaces.

type readonly DiskfileDirectoryPath[]

readonly $derived.by

`directory_paths`

The directories holding a file on disk, each with a trailing / — changing only as a directory gains its first file or loses its last.

type ReadonlySet<string>

readonly

`set_deleted_on_disk`

Marks diskfile gone from disk, or back — the one writer of Diskfile.deleted_on_disk besides upsert, so directory_paths stays in step.

type (diskfile: Diskfile, deleted_on_disk: boolean): void

`diskfile`

type Diskfile

`deleted_on_disk`

type boolean

returns void

`link_index`

The file index as markdown links see it, for telling a link's target exists — reactive, so a check in a $derived follows the index.

type MarkdownLinkIndex

readonly

`open_path`

Opens the file at path in a tab, as a preview unless open_not_preview (see select) — only a file on disk in the index. A markdown file's markdown view then reveals the heading fragment names (see DiskfileEditorState.markdown_pending_fragment).

type (path: string, options?: { fragment?: string | null | undefined; open_not_preview?: boolean | undefined; } | undefined): boolean

`path`

type string

`options?`

type { fragment?: string | null | undefined; open_not_preview?: boolean | undefined; }

optional

returns boolean

whether a file was opened

`create_file`

Creates a new file in new_files_dir — never overwriting one: the backend's diskfile_create creates the final name exclusively, so an existing file (indexed or not) is left untouched. The new file is selected and opened in a permanent tab, like VS Code's new file — now if its filer_change already arrived, else when it does.

type (filename: string, content?: string): Promise<void>

`filename`

the file's path relative to new_files_dir, parsed by parse_new_diskfile_name: trimmed, with leading slashes dropped; refused when blank, naming the directory itself, with a whitespace-only segment, climbing out with .., or ending in an empty, ., or .. segment

type string

`content`

the new file's content

type string

default ''

returns Promise<void>

throws

Error - when no workspace is open, the name is refused, the file already exists, or the write fails

`create_file_at`

Creates a new file at an absolute path — never overwriting one, like create_file — and selects it, opened in a permanent tab, now or when its filer_change arrives.

type (path: string & $brand<"DiskfilePath">, content?: string): Promise<void>

`path`

the new file's absolute path

type DiskfilePath

`content`

the new file's content

type string

default ''

returns Promise<void>

throws

Error - when the file already exists or the write fails

`follow_selected_tab`

Makes the selected file the editor's selected tab's (or none) after a user-driven tab change — selecting, opening, closing the selected tab, reopening, or navigating back/forward (the DiskfilesEditor methods) — and drops a pending create_file selection, since the user has moved on.

type (): void

returns void

`handle_workspace_removed`

Called when the workspace at path is removed: a file created there that hasn't arrived won't be selected if it arrives later.

type (path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">): void

`path`

returns void

`create_directory`

Creates a new directory in new_files_dir.

type (dirname: string): Promise<void>

`dirname`

the directory's path relative to new_files_dir, parsed by parse_new_diskfile_name as for create_file, except that its last segment may be empty, ., or .. (src/, a/b/..)

type string

returns Promise<void>

throws

Error - when no workspace is open, the name is refused or already taken, or the backend refuses

`get_by_path`

type (path: string & $brand<"DiskfilePath">): Diskfile | undefined

`path`

type DiskfilePath

returns Diskfile | undefined

`to_relative_path`

The value undefined means uninitialized, null means loading, '' means none.

type (path: string): string | null | undefined

`path`

type string

returns string | null | undefined

`select`

Select a diskfile by id and also update the editor tabs. Default to the first file if id is undefined. If id is null, it selects no file. If open_not_preview is true, opens as a permanent tab, otherwise previews.

type (id: (string & $brand<"Uuid">) | null | undefined, open_not_preview?: boolean): void

`id`

type Uuid | null | undefined

`open_not_preview`

type boolean

default false

returns void

`select_next`

type (): void

returns void

DiskfileSaveOptions
#

diskfile.svelte.ts view source

DiskfileSaveOptions import type {DiskfileSaveOptions} from '@fuzdev/zzz/diskfile_editor_state.svelte.js';

Options for DiskfileEditorState.save_changes.

`overwrite?`

Save even though the file changed on disk under the edit (has_conflict) — the user chose to overwrite that change.

type boolean

DiskfileSchema
#

ZodCustom<Diskfile, Diskfile>

type ZodCustom<Diskfile, Diskfile>

import {DiskfileSchema} from '@fuzdev/zzz/diskfile.svelte.js';

DiskfilesEditor
#

import {DiskfilesEditor} from '@fuzdev/zzz/diskfiles_editor.svelte.js';

Editor state management for diskfiles.

inheritance

extends: Cell<typeof DiskfilesEditorJson>

`show_sort_controls`

Controls visibility of sort controls in the file explorer.

type boolean

$state.raw

`tabs`

Tabs for managing the open diskfiles.

type DiskfileTabs

readonly

`pending_close_request`

A tab close waiting on the user's choice — save, don't save, or cancel — because it's the last tab of a file with a draft (see request_close_tab). Lapses on its own once that tab closes or that draft is gone (saved, discarded, …), so a later draft never revives it; a lapsed request is dropped by the next close or request.

type DiskfileTabCloseRequest | null

readonly $derived.by

`pending_close_tab`

The tab pending_close_request asks about.

type DiskfileTab | undefined

readonly $derived

`pending_close_tab_id`

The id of pending_close_tab.

type Uuid | null

readonly $derived

`constructor`

type new (options: DiskfilesEditorOptions): DiskfilesEditor

`options`

type DiskfilesEditorOptions

`preview_diskfile`

Opens a diskfile in preview mode.

type (diskfile_id: string & $brand<"Uuid">): void

`diskfile_id`

type Uuid

returns void

`open_diskfile`

Opens a diskfile in permanent mode.

type (diskfile_id: string & $brand<"Uuid">): void

`diskfile_id`

type Uuid

returns void

`reorder_tabs`

Reorders tabs.

type (from_index: number, to_index: number): void

`from_index`

type number

`to_index`

type number

returns void

`navigate_to_tab`

Navigates back or forward to a tab (see DiskfileTabs.navigate_to_tab), and selects its file.

type (tab_id: string & $brand<"Uuid">): (string & $brand<"Uuid">) | null

`tab_id`

type Uuid

returns Uuid | null

the id of the tab navigated to, null if there's none

`close_tab`

Closes a tab by id, now — see request_close_tab for the user-facing close. If its file was the selected one, selection follows the newly selected tab. A draft isn't lost either way: it's app-level, and the file reopens on it.

type (tab_id: string & $brand<"Uuid">): void

`tab_id`

type Uuid

returns void

`request_close_tab`

Closes a tab as the user asked, like VS Code: the tab of a file with a draft isn't closed yet — it becomes pending_close_tab_id, for the user to save, not save (DiskfileEditorState.discard_draft), or cancel. (A file has at most one tab — see DiskfileTabs.)

type (tab_id: string & $brand<"Uuid">): boolean

`tab_id`

type Uuid

returns boolean

whether the tab closed now

`cancel_close_tab`

Cancels a pending tab close, marking its request cancelled — see request_close_tab.

type (): void

returns void

`reopen_last_closed_tab`

Reopens the last closed tab whose file isn't open (see DiskfileTabs.reopen_last_closed_tab), and selects its file.

type boolean

default !this.show_sort_controls

returns void

DiskfilesEditorJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; show_sort_controls: boolean; }

import {DiskfilesEditorJson} from '@fuzdev/zzz/diskfiles_editor.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`show_sort_controls`

type boolean

DiskfilesEditorJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; show_sort_controls?: boolean | undefined; }

import type {DiskfilesEditorJsonInput} from '@fuzdev/zzz/diskfiles_editor.svelte.js';

`id?`

`json?`

type DiskfilesEditorJsonInput

DiskfilesEditorSchema
#

ZodCustom<DiskfilesEditor, DiskfilesEditor>

type ZodCustom<DiskfilesEditor, DiskfilesEditor>

import {DiskfilesEditorSchema} from '@fuzdev/zzz/diskfiles_editor.svelte.js';

DiskfilesJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; diskfiles: { id: string & $brand<"Uuid">; ... 7 more ...; dependencies: [...][]; }[]; selected_file_id: (string & $brand<...>) | null; }

import {DiskfilesJson} from '@fuzdev/zzz/diskfiles.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`diskfiles`

type DiskfileJson[]

`selected_file_id`

type (string & $brand<"Uuid">) | null

DiskfilesJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; diskfiles?: { path: string; source_dir: string; id?: string | undefined; created?: string | undefined; ... 4 more ...; dependencies?: [...][] | undefined; }[] | undefined; selected_file_id?: string | ... 1 more ... | undefined; }

import type {DiskfilesJsonInput} from '@fuzdev/zzz/diskfiles.svelte.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

`diskfiles?`

type DiskfileJsonInput[]

`selected_file_id?`

type string | null

DiskfileSnapshotChanges
#

DiskfileSnapshotChanges import type {DiskfileSnapshotChanges} from '@fuzdev/zzz/diskfiles.svelte.js';

What filer_change reported while a file-tree snapshot was in flight — see Diskfiles.track_changes for how a snapshot is applied around it.

`paths`

Paths an add, change, or delete reported. The snapshot's entries for them are skipped.

type ReadonlySet<string>

readonly

`touches`

The latest touch reported per path. A touch never makes the snapshot yield; its metadata is applied again after the snapshot.

type ReadonlyMap<string, DisknodeMetadata>

readonly

DiskfilesOptions
#

DiskfilesOptions import type {DiskfilesOptions} from '@fuzdev/zzz/diskfiles.svelte.js';

inheritance

extends: CellOptions<typeof DiskfilesJson>

DiskfileTab
#

import {DiskfileTab} from '@fuzdev/zzz/diskfile_tab.svelte.js';

inheritance

extends: Cell<typeof DiskfileTabJson>

`diskfile_id`

type Uuid

$state.raw

`tabs`

Reference to the parent tabs collection, allowing us to have collection-derived data, at the cost of requiring exactly 1 parent.

This pattern is somewhat experimental - the idea is it's more declarative to have things like the "preview" or "selected" tabs be state on the collection, so it doesn't need to be separately managed as state on each tab.

type DiskfileTabs

readonly

`is_preview`

Derived from parent collection's state.

type boolean

readonly $derived.by

`is_selected`

Derived from parent collection's state.

type boolean

readonly $derived.by

`diskfile`

type Diskfile | undefined

readonly $derived

`constructor`

type new (options: DiskfileTabOptions): DiskfileTab

`options`

type DiskfileTabOptions

DiskfileTabCloseRequest
#

DiskfileTabCloseRequest import type {DiskfileTabCloseRequest} from '@fuzdev/zzz/diskfiles_editor.svelte.js';

A tab close waiting on the user — see DiskfilesEditor.request_close_tab. Whoever acts on it (e.g. saving first) holds the request and checks cancelled before closing, since saving the draft lapses the request.

`tab_id`

type Uuid

readonly

`draft_id`

type Uuid

readonly

`cancelled`

Set by cancel_close_tab — the user chose to keep the tab.

type boolean

DiskfileTabJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; diskfile_id: string & $brand<"Uuid">; }

import {DiskfileTabJson} from '@fuzdev/zzz/diskfile_tab.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`diskfile_id`

type string & $brand<"Uuid">

DiskfileTabJsonInput
#

{ diskfile_id: string; id?: string | undefined; created?: string | undefined; updated?: string | undefined; } import type {DiskfileTabJsonInput} from '@fuzdev/zzz/diskfile_tab.svelte.js';

`diskfile_id`

type string

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

DiskfileTabListitem
#

DiskfileTabOptions import type {DiskfileTabOptions} from '@fuzdev/zzz/diskfile_tab.svelte.js';

inheritance

extends: CellOptions<typeof DiskfileTabJson>

`tabs`

type DiskfileTabs

DiskfileTabs
#

import {DiskfileTabs} from '@fuzdev/zzz/diskfile_tabs.svelte.js';

Manages tabs for diskfiles in the editor with preview behavior. A diskfile has at most one tab (by_diskfile_id): opening, previewing, reopening, and navigating back to a file that's open select its tab.

`recently_closed_tabs`

Recently closed tabs for potential reopening, oldest first, at most DISKFILE_TABS_CLOSED_MAX.

type DiskfileTab[]

$state

`closed_tab_diskfiles`

Map of closed tab ids to their diskfile ids - used for browser navigation. Holds the DISKFILE_TABS_CLOSED_MAX most recently closed.

type SvelteMap<Uuid, Uuid>

readonly

`constructor`

type new (options: DiskfileTabsOptions): DiskfileTabs

Promotes the current preview tab to a permanent tab.

type (): boolean

returns boolean

true if a tab was promoted, false otherwise

`close_tab`

Closes a tab by id.

type (tab_id: string & $brand<"Uuid">): void

`tab_id`

type Uuid

returns void

`navigate_to_tab`

Navigates to a tab by id. If the tab doesn't exist but was previously closed, selects its diskfile's tab if the file is open again, else previews the diskfile.

type (tab_id: string & $brand<"Uuid">): (string & $brand<"Uuid">) | null

`tab_id`

the tab id to navigate to

type Uuid

returns Uuid | null

the id of the resulting tab, null for an unknown tab

`open_tab`

`close_all_tabs`

Closes all tabs. Like VS Code's "close all editors", they join the reopen stack on top of the earlier closed tabs — pushed last-to-first, so reopening them one by one restores their order.

type (): void

returns void

DiskfileTabSchema
#

ZodCustom<DiskfileTab, DiskfileTab>

type ZodCustom<DiskfileTab, DiskfileTab>

import {DiskfileTabSchema} from '@fuzdev/zzz/diskfile_tab.svelte.js';

DiskfileTabsJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; selected_tab_id: (string & $brand<"Uuid">) | null; preview_tab_id: (string & $brand<...>) | null; tab_order: (string & $brand<...>)[]; recent_tab_ids: (string & $brand<...>)[]; max_tab_history: number; }

import {DiskfileTabsJson} from '@fuzdev/zzz/diskfile_tabs.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`selected_tab_id`

type (string & $brand<"Uuid">) | null

`preview_tab_id`

type (string & $brand<"Uuid">) | null

`tab_order`

type (string & $brand<"Uuid">)[]

`recent_tab_ids`

Tracks recently accessed tabs for better tab selection when closing tabs.

type (string & $brand<"Uuid">)[]

`max_tab_history`

Maximum number of tabs to track in access history.

type number

DiskfileTabsJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; selected_tab_id?: string | null | undefined; preview_tab_id?: string | null | undefined; tab_order?: string[] | undefined; recent_tab_ids?: string[] | undefined; max_tab_history?: number | undefined; }

import type {DiskfileTabsJsonInput} from '@fuzdev/zzz/diskfile_tabs.svelte.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

`selected_tab_id?`

type string | null

`preview_tab_id?`

type string | null

`tab_order?`

type string[]

`recent_tab_ids?`

Tracks recently accessed tabs for better tab selection when closing tabs.

type string[]

`max_tab_history?`

Maximum number of tabs to track in access history.

type number

DiskfileTabsOptions
#

DiskfileTabsOptions

type CellOptions<ZodObject<{ id: ZodDefault<$ZodBranded<ZodUUID, "Uuid", "out">>; created: ZodDefault<$ZodBranded<ZodISODateTime, "Datetime", "out">>; updated: ZodDefault<$ZodBranded<ZodISODateTime, "Datetime", "out">>; selected_tab_id: ZodDefault<ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>>; preview_tab_id: ZodDefault<ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>>; tab_order: ZodDefault<ZodArray<$ZodBranded<ZodUUID, "Uuid", "out">>>; recent_tab_ids: ZodDefault<ZodArray<$ZodBranded<ZodUUID, "Uuid", "out">>>; max_tab_history: ZodDefault<ZodNumber>; }, $strict>>

import type {DiskfileTabsOptions} from '@fuzdev/zzz/diskfile_tabs.svelte.js';

`app`

type Frontend

`json?`

type DiskfileTabsJsonInput

DiskfileTabsSchema
#

DiskfileTranscriptView.svelte view source

ZodCustom<DiskfileTabs, DiskfileTabs>

type ZodCustom<DiskfileTabs, DiskfileTabs>

import {DiskfileTabsSchema} from '@fuzdev/zzz/diskfile_tabs.svelte.js';

DiskfileTranscriptView
#

import DiskfileTranscriptView from '@fuzdev/zzz/DiskfileTranscriptView.svelte';

`diskfile`

type Diskfile

`onmodified?`

type (diskfile_id: string & $brand<"Uuid">) => void

optional

snippet parameters

diskfile_id Uuid

DiskfileUpdateInput
#

DiskfileView.svelte view source

value + type

{ path: string & $brand<"DiskfilePath">; content: string; } import {DiskfileUpdateInput} from '@fuzdev/zzz/action_specs.js';

Input for diskfile_update.

`path`

type string & $brand<"DiskfilePath">

`content`

type string

DiskfileView
#

import DiskfileView from '@fuzdev/zzz/DiskfileView.svelte';

`diskfile`

type Diskfile

`onmodified?`

type (diskfile_id: string & $brand<"Uuid">) => void

optional

snippet parameters

diskfile_id Uuid

disknode_to_diskfile_json
#

(disknode: { id: string & $brand<"DiskfilePath">; source_dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; contents: string | null; ctime: number | null; mtime: number | null; dependents: [...][]; dependencies: [...][]; }, existing_id?: string & $brand<...>): { ...; }

import {disknode_to_diskfile_json} from '@fuzdev/zzz/diskfile_helpers.js';

Converts a SerializableDisknode to the DiskfileJson format.

`disknode`

the source file to convert

type SerializableDisknode

`existing_id`

optional existing Uuid to preserve id stability across updates

type Uuid

default create_uuid()

returns

DiskfileJson

DisknodeMetadata
#

value + type

{ id: string & $brand<"DiskfilePath">; source_dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; ctime: number | null; mtime: number | null; dependents: [...][]; dependencies: [...][]; }

import {DisknodeMetadata} from '@fuzdev/zzz/diskfile_types.js';

A disknode without its contents — what a touch change carries. It has no contents key, which is not contents: null: null says the file's contents aren't loaded, and this says nothing about them — whoever holds the file keeps the contents it has.

`id`

type string & $brand<"DiskfilePath">

`source_dir`

type string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">

`ctime`

type number | null

`mtime`

type number | null

`dependents`

type [string & $brand<"DiskfilePath">, any][]

`dependencies`

type [string & $brand<"DiskfilePath">, any][]

DRAG_OVER_BOTTOM_CLASS_DEFAULT
#

"drag-over-bottom" import {DRAG_OVER_BOTTOM_CLASS_DEFAULT} from '@fuzdev/zzz/reorderable.svelte.js';

DRAG_OVER_CLASS_DEFAULT
#

"drag-over" import {DRAG_OVER_CLASS_DEFAULT} from '@fuzdev/zzz/reorderable.svelte.js';

DRAG_OVER_LEFT_CLASS_DEFAULT
#

"drag-over-left" import {DRAG_OVER_LEFT_CLASS_DEFAULT} from '@fuzdev/zzz/reorderable.svelte.js';

DRAG_OVER_RIGHT_CLASS_DEFAULT
#

"drag-over-right" import {DRAG_OVER_RIGHT_CLASS_DEFAULT} from '@fuzdev/zzz/reorderable.svelte.js';

DRAG_OVER_TOP_CLASS_DEFAULT
#

"drag-over-top" import {DRAG_OVER_TOP_CLASS_DEFAULT} from '@fuzdev/zzz/reorderable.svelte.js';

DRAGGING_CLASS_DEFAULT
#

"dragging" import {DRAGGING_CLASS_DEFAULT} from '@fuzdev/zzz/reorderable.svelte.js';

DURATION_LG
#

1000 import {DURATION_LG} from '@fuzdev/zzz/helpers.js';

DURATION_SM
#

EditableText.svelte view source

180 import {DURATION_SM} from '@fuzdev/zzz/helpers.js';

EditableText
#

import EditableText from '@fuzdev/zzz/EditableText.svelte';

`value`

type string

bindable

`attrs?`

type HTMLAttributes<HTMLSpanElement>

optional

`span_attrs?`

type HTMLAttributes<HTMLSpanElement>

optional

`input_attrs?`

type HTMLInputAttributes

optional

ERROR_CONTENT_NOT_LOADED
#

workspace_helpers.ts view source

"content_not_loaded" import {ERROR_CONTENT_NOT_LOADED} from '@fuzdev/zzz/diskfile_helpers.js';

data.reason of the error refusing to write over a file whose content wasn't loaded.

ERROR_WORKSPACE_NOT_OPEN
#

"workspace_not_open" import {ERROR_WORKSPACE_NOT_OPEN} from '@fuzdev/zzz/workspace_helpers.js';

data.reason of the invalid_params error workspace_close returns for a path that isn't an open workspace — e.g. one a daemon restart forgot.

ErrorMessage
#

ErrorMessage.svelte view source

accepts children

import ErrorMessage from '@fuzdev/zzz/ErrorMessage.svelte';

external types

ComponentProps<typeof Alert>

ErrorMessageInline
#

ErrorMessageInline.svelte view source

accepts children

import ErrorMessageInline from '@fuzdev/zzz/ErrorMessageInline.svelte';

`icon?`

type SvgData | null

optional default icon_error

`children`

type Snippet<[]>

estimate_json_length
#

(value: unknown, limit: number): number import {estimate_json_length} from '@fuzdev/zzz/action_helpers.js';

Estimates the length of value serialized as JSON, stopping as soon as it passes limit — so the cost is bounded by limit, not by the value's size. The estimate ignores string escaping, so it can undercount strings full of characters JSON escapes.

`value`

the value to measure

type unknown

`limit`

the length to stop measuring at

type number

returns

number

the estimated length, or a number over limit once it's passed

estimate_token_count
#

(text: string): number import {estimate_token_count} from '@fuzdev/zzz/helpers.js';

Quick and dirty token count estimate using ESTIMATED_CHARS_PER_TOKEN. Real tokenizers are heavy and of little benefit for our cases right now, especially because each LLM may tokenize differently.

`text`

type string

returns

number

estimate_token_count_from_length
#

(length: number): number import {estimate_token_count_from_length} from '@fuzdev/zzz/helpers.js';

estimate_token_count for a text of length characters, for callers that know the length without building the text.

`length`

type number

returns

number

ESTIMATED_CHARS_PER_TOKEN
#

ExternalLink.svelte view source

3 import {ESTIMATED_CHARS_PER_TOKEN} from '@fuzdev/zzz/helpers.js';

ExternalLink
#

accepts children

import ExternalLink from '@fuzdev/zzz/ExternalLink.svelte';

`href`

type string

`new_tab?`

Set to false to open in the same tab.

type boolean

optional default true

`icon?`

type Snippet<[known_logo: SvgData | null]>

optional

snippet parameters

known_logo SvgData | null

`children?`

type Snippet<[]>

optional

external types

SvelteHTMLElements['a']

ExternalLinkIcon
#

ExternalLinkIcon.svelte view source

accepts children

import ExternalLinkIcon from '@fuzdev/zzz/ExternalLinkIcon.svelte';

`children?`

type Snippet<[icon: SvgData]>

optional

snippet parameters

icon SvgData

FailedMessage
#

FailedMessage import type {FailedMessage} from '@fuzdev/zzz/socket.svelte.js';

Failed message that exceeded retry count.

inheritance

extends: QueuedMessage

`failed`

type number

`reason`

type string

FILE_BYTES_MAX_BODY_BYTES
#

number import {FILE_BYTES_MAX_BODY_BYTES} from '@fuzdev/zzz/file_bytes.js';

Largest body one create or append accepts, in bytes — twin of the backend's FILE_BYTES_MAX_BODY_BYTES. A larger file is written as several appends.

FILE_BYTES_SUBPATH
#

"/files/bytes" import {FILE_BYTES_SUBPATH} from '@fuzdev/zzz/file_bytes.js';

The byte routes' path below the API path — twin of the backend's FILE_BYTES_PATH, which the cross-backend byte-route suite pins it to.

FILE_DATETIME_FORMAT
#

"MMM d, yyyy h:mm:ss a" import {FILE_DATETIME_FORMAT} from '@fuzdev/zzz/cell_helpers.js';

FILE_INDEX_IGNORED_DIR_NAMES
#

ReadonlySet<string>

type ReadonlySet<string>

import {FILE_INDEX_IGNORED_DIR_NAMES} from '@fuzdev/zzz/markdown_links.js';

Directory names the file index never enters, wherever they appear under a root — the backend filer's default ignores (DEFAULT_IGNORED_DIRS in crates/zzz_server/src/filer.rs, which a test holds this to). A link into one is skipped, not broken.

FILE_INDEX_TEMP_FILE_PREFIX
#

".zzz-tmp-" import {FILE_INDEX_TEMP_FILE_PREFIX} from '@fuzdev/zzz/markdown_links.js';

The prefix of the backend's staging files, which the index never lists (TEMP_FILE_PREFIX in crates/zzz_server/src/scoped_fs.rs, which a test holds this to).

FILE_SHORT_DATE_FORMAT
#

"MMM d, p" import {FILE_SHORT_DATE_FORMAT} from '@fuzdev/zzz/cell_helpers.js';

FILE_TIME_FORMAT
#

"HH:mm:ss" import {FILE_TIME_FORMAT} from '@fuzdev/zzz/cell_helpers.js';

FileBytesError
#

FileBytesError import type {FileBytesError} from '@fuzdev/zzz/file_bytes.js';

Body of a refused request. error is a reason like already_exists, offset_mismatch, path_not_allowed, or authentication_required.

`error`

type string

`size?`

The file's current size, sent with offset_mismatch.

type number

FileBytesFetch
#

FileBytesFetch import type {FileBytesFetch} from '@fuzdev/zzz/file_bytes.js';

The fetch the byte-route calls go through.

`(call)`

type (input: string, init?: RequestInit | undefined): Promise<Response>

`input`

type string

`init?`

type RequestInit

optional

returns Promise<Response>

FileBytesWriteResult
#

FileBytesWriteResult

type { ok: true; size: number; } | { ok: false; status: number; reason: string; size?: number | undefined; }

import type {FileBytesWriteResult} from '@fuzdev/zzz/file_bytes.js';

Outcome of a create or an append. On failure status is the HTTP status (0 when the request never got an answer) and reason the backend's error (network_error or invalid_response when there was none).

FileBytesWritten
#

FileBytesWritten import type {FileBytesWritten} from '@fuzdev/zzz/file_bytes.js';

Body of a successful create (201) or append (200): the file's size after it.

`size`

type number

filer_change_action_spec
#

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodUnion<readonly [ZodObject<{ change: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; type: ZodEnum<...>; }, $strict>; disknode: ZodObject<...>; }, $strict>, ZodObject<...>]>; output: ZodVoid...

import {filer_change_action_spec} from '@fuzdev/zzz/action_specs.js';

FilerChangeInput
#

value + type

{ change: { path: string & $brand<"DiskfilePath">; type: "add" | "change" | "delete"; }; disknode: { id: string & $brand<"DiskfilePath">; source_dir: string & $brand<...> & $brand<...>; ... 4 more ...; dependencies: [...][]; }; } | { ...; }

type { change: { path: string & $brand<"DiskfilePath">; type: "add" | "change" | "delete"; }; disknode: { id: string & $brand<"DiskfilePath">; source_dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; contents: string | null; ctime: number | null; mtime: number | null; dependents: [string & $brand<"DiskfilePath">, any][]; dependencies: [string & $brand<"DiskfilePath">, any][]; }; } | { change: { path: string & $brand<"DiskfilePath">; type: "touch"; }; disknode: { id: string & $brand<"DiskfilePath">; source_dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; ctime: number | null; mtime: number | null; dependents: [string & $brand<"DiskfilePath">, any][]; dependencies: [string & $brand<"DiskfilePath">, any][]; }; }

import {FilerChangeInput} from '@fuzdev/zzz/action_specs.js';

Input for filer_change: the file's whole disknode — or, for a touch, its metadata without the contents (DisknodeMetadata).

FilesystemCapabilityData
#

FilesystemCapabilityData import type {FilesystemCapabilityData} from '@fuzdev/zzz/capabilities.svelte.js';

`zzz_dir`

type DiskfileDirectoryPath | null | undefined

`scoped_dirs`

type readonly DiskfileDirectoryPath[]

find_scroll_container
#

(el: Element): HTMLElement | null import {find_scroll_container} from '@fuzdev/zzz/list_helpers.js';

Finds the nearest ancestor of el whose computed overflow-y is auto, scroll, or overlay, or null when there's none (the document scrolls).

Computed style can't tell a vertical scroller apart from an ancestor with only overflow-x: auto (its overflow-y: visible computes to auto) or an overflow: auto box whose height grows with its content, and those are returned too. Callers that window a list by this ancestor's visible area need the real scroller to be the nearest one, with a constrained height.

`el`

type Element

returns

HTMLElement | null

find_transcripts
#

Footer.svelte view source

<T extends TranscriptCandidate>(files: Iterable<T>, source_path: string): FoundTranscript<T>[] import {find_transcripts} from '@fuzdev/zzz/transcript_helpers.js';

Finds the transcript sidecars of the audio file at source_path among files: the files beside it named <source name>.<model>.transcript.json whose content says they were made from it. Sorted by model name.

`files`

the files to look through

type Iterable<T, any, any>

`source_path`

the audio file's absolute path

type string

returns

FoundTranscript<T>[]

generics

find_transcripts<T extends TranscriptCandidate>

`T`

constraint TranscriptCandidate

Footer
#

import Footer from '@fuzdev/zzz/Footer.svelte';

format_datetime
#

format_helpers.ts view source

(value: TimeValue | null | undefined, fallback?: string): string import {format_datetime} from '@fuzdev/zzz/time_helpers.js';

`value`

type TimeValue | null | undefined

`fallback`

type string

default ''

returns

string

format_gigabytes
#

(gb: number): string import {format_gigabytes} from '@fuzdev/zzz/format_helpers.js';

`gb`

type number

returns

string

format_ms_to_readable
#

(ms: number): string import {format_ms_to_readable} from '@fuzdev/zzz/time_helpers.js';

Formats a duration for display: milliseconds under a second, else seconds to at most one decimal place with no trailing zero, like 1 second or 1.5 seconds.

`ms`

type number

returns

string

format_placeholder
#

prompt_helpers.ts view source

(text?: string | null | undefined): string import {format_placeholder} from '@fuzdev/zzz/helpers.js';

Formats input placeholder text, prefixed with a ↳ arrow. The arrow is a text glyph rather than an icon_* SVG because the placeholder attribute can't host markup.

`text?`

type string | null

optional

returns

string

format_prompt_content
#

(parts: PartUnion[]): string import {format_prompt_content} from '@fuzdev/zzz/prompt_helpers.js';

Formats a collection of parts into a prompt string, applying XML tags and attributes where specified.

A file part whose file content wasn't loaded (over 4 MiB, not UTF-8 text, or unreadable) contributes DISKFILE_CONTENT_NOT_LOADED_PLACEHOLDER in its place, so the prompt shows the file is missing rather than dropping it.

A file part sends the file's unsaved draft when it has one (DiskfilePart.draft_status); its XML tag then says so with unsaved="true", plus changed_on_disk="true" when the draft predates a change on disk or deleted_on_disk="true" when the file is gone — so the model isn't told an unsaved buffer is the file on disk. Those keys then replace any user attribute of the same name (DISKFILE_PART_STATUS_ATTRIBUTES).

`parts`

type PartUnion[]

returns

string

format_recording_duration
#

(ms: number): string import {format_recording_duration} from '@fuzdev/zzz/recording_helpers.js';

Formats a duration as m:ss, or h:mm:ss from an hour up.

`ms`

the duration in milliseconds

type number

returns

string

format_short_date
#

(value: TimeValue | null | undefined, fallback?: string): string import {format_short_date} from '@fuzdev/zzz/time_helpers.js';

`value`

type TimeValue | null | undefined

`fallback`

type string

default ''

returns

string

format_terminal_command
#

(command: string, args: readonly string[]): string import {format_terminal_command} from '@fuzdev/zzz/terminal_helpers.js';

Formats a command and its args as the line typed into the terminal's shell. Each arg follows a space, except one that starts with whitespace, which carries its own separator — how parse_terminal_command keeps a typed line verbatim.

`command`

type string

`args`

type readonly string[]

returns

string

format_time
#

(value: TimeValue | null | undefined, fallback?: string): string import {format_time} from '@fuzdev/zzz/time_helpers.js';

`value`

type TimeValue | null | undefined

`fallback`

type string

default ''

returns

string

format_timestamp
#

(value: TimeValue | null | undefined, fallback?: string): string import {format_timestamp} from '@fuzdev/zzz/time_helpers.js';

`value`

type TimeValue | null | undefined

`fallback`

type string

default ''

returns

string

format_transcript_time
#

(ms: number): string import {format_transcript_time} from '@fuzdev/zzz/transcript_helpers.js';

Formats a position in a recording as m:ss, or h:mm:ss from an hour up.

`ms`

the position in milliseconds

type number

returns

string

FoundTranscript
#

FoundTranscript<T> import type {FoundTranscript} from '@fuzdev/zzz/transcript_helpers.js';

A transcript sidecar found for a source.

generics

FoundTranscript<T extends TranscriptCandidate = TranscriptCandidate>

`T`

constraint TranscriptCandidate

default TranscriptCandidate

`file`

type T

`transcript`

type Transcript

Frontend
#

import {Frontend} from '@fuzdev/zzz/frontend.svelte.js';

The base frontend app, typically used by creating your own App extends Frontend. Gettable with frontend_context.get() inside a FrontendRoot.

inheritance

extends: Cell<typeof FrontendJson>

implements: ActionEventEnvironment

The backend API's URL or path, with no trailing slash — null without one.

type string | null

readonly

`bots`

type { namerbot: string; }

readonly

`provider_status`

Tracks which providers are available (configured with API keys).

type ProviderStatus[]

$state

`tags`

type Set<string>

readonly $derived.by

`futuremode`

See into Zzz's future.

type boolean

$state.raw

`session_status`

Status of loading the session snapshot with load_session — 'failure' while waiting to retry.

type AsyncStatus

$state.raw

`session_error`

Why the last session_load failed, cleared when one succeeds.

type string | null

$state.raw

`server_instance_id`

The backend instance the last session snapshot came from — a snapshot with a different one means zzzd restarted. null until one loads.

type Uuid | null

$state.raw

`constructor`

type new (options?: FrontendOptions): Frontend

`options`

type FrontendOptions

default EMPTY_OBJECT

`load_session`

Loads the session snapshot (session_load) and reconciles the app with it (see receive_session), retrying with backoff (SESSION_LOAD_RETRY_DELAY doubling to SESSION_LOAD_RETRY_DELAY_MAX) until one succeeds or the app is disposed. Calling it while a retry waits retries now. Runs at boot and after every reconnect (see handle_socket_connect).

Changes that arrive while the request is in flight win over the snapshot: files a filer_change added, changed, or deleted (a touch only keeps its metadata — see Diskfiles.track_changes) and workspaces opened or closed are left as they are, and only terminals running when the request was sent can be found lost.

A success also re-pings a backend whose last ping failed (see Capabilities.check_backend).

type (): Promise<boolean>

returns Promise<boolean>

whether this attempt succeeded

`boot_session`

Starts the boot-time session load. It waits for the socket to open, so the snapshot comes over the socket that then carries the notifications, with no gap between the two (see handle_socket_connect); if the socket hasn't opened within fallback_delay, it loads over HTTP instead. Loads right away when the socket is already open or there's none configured.

type (fallback_delay?: number): void

`fallback_delay`

ms to wait for the socket before loading over HTTP

type number

default SESSION_BOOT_FALLBACK_DELAY

returns void

`handle_socket_connect`

Handles the socket's last_connect_time changing — call it with each new value (the app root wires this to the socket's reactive state).

Notifications only arrive while the socket is open, so a snapshot loaded before this connect may miss changes: those sent while a previous socket was down (filer_change, workspace_changed, terminal_data, terminal_exited), or, on the first connect, those between an HTTP boot load and the socket opening. So:

with no load yet, this is the boot load (see boot_session)
on the first connect, a load sent while the socket was already open (so over it) needs nothing more
otherwise, an earlier load is followed by a resync — the session snapshot is reloaded (after the in-flight load, if any) to reconcile files, workspaces, and terminals, and on a reconnect running terminals are flagged as possibly missing output

type (connect_time: number | null): boolean

`connect_time`

the socket's last_connect_time, null before it connects

type number | null

returns boolean

whether this connect started a resync

`resync_session`

Reloads the session snapshot to reconcile state no notification carries — after a reconnect, or a workspace opened elsewhere (see Workspaces.receive_remote_open). With a load in flight, which may predate the change, another follows it.

type (): void

returns void

`receive_session`

Reconciles the app with a session snapshot — replacing, not just adding:

workspaces: adds the listed ones and removes the rest (Workspaces.reconcile) — except after a zzzd restart (a new server_instance_id), when the ones it lost are reopened instead (Workspaces.open), keeping their files and tabs; a reopen refused because the directory is gone or forbidden drops the workspace and its files, while any other failure keeps it for the next snapshot to retry
files: upserts the snapshot's, and removes known files it lacks under file_roots or a removed workspace, keeping ones with unsaved edits (Diskfiles.reconcile) — files elsewhere are left alone
terminals: running ones the backend no longer has become lost (Terminals.reconcile)

type (data: { zzz_dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; scoped_dirs: readonly (string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">)[]; ... 6 more ...; server_instance_id: string & $brand<...>; }, changes?: SessionSnapshotChanges | undefined): void

`data`

the session_load output's snapshot

type SessionLoadData

`changes?`

what changed while the snapshot was in flight, which the snapshot doesn't override (see load_session); without it nothing is skipped and every running terminal is judged

type SessionSnapshotChanges

optional

returns void

`close_workspace`

Closes the workspace at path (workspace_close) and removes it here. A reply that it isn't open (ERROR_WORKSPACE_NOT_OPEN — e.g. a restart forgot it and its reopen hasn't succeeded) removes it here too, and the close always cancels a pending reopen — one in flight closes the workspace again once it lands — so a closed workspace stays closed.

type (path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">): Promise<Result<{ value: null; }, { error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; }>>

`path`

returns Promise<Result>

the RPC result — any failure but "not open" is for the caller to surface

`add_providers`

type (providers_json: { name: "claude" | "chatgpt" | "gemini"; title: string; url: string; homepage: string; company: string; api_key_url: string | null; id?: string | undefined; created?: string | undefined; updated?: string | undefined; }[]): void

`providers_json`

type ProviderJsonInput[]

returns void

`add_provider`

type (provider_json: { name: "claude" | "chatgpt" | "gemini"; title: string; url: string; homepage: string; company: string; api_key_url: string | null; id?: string | undefined; created?: string | undefined; updated?: string | undefined; }): void

`provider_json`

type ProviderJsonInput

returns void

`lookup_provider_status`

type (provider_name: string): { name: string; available: true; checked_at: number; } | { name: string; available: false; error: string; checked_at: number; } | null

`provider_name`

type string

returns

{ name: string; available: true; checked_at: number; } | { name: string; available: false; error: string; checked_at: number; } | null

`update_provider_status`

type (status: { name: string; available: true; checked_at: number; } | { name: string; available: false; error: string; checked_at: number; }): void

`status`

type ProviderStatus

returns void

`dispose`

Tear the app down: closes the socket (no reconnect loop is left behind), ends a recording, stops session_load retries and the cells that own timers, then unregisters.

type (): void

returns void

`lookup_action_handler`

`method`

type string

`phase`

type ActionEventPhase

returns ((event: any) => any) | undefined

`lookup_action_spec`

type (method: string): { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; } | undefined

`method`

type string

returns

{ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; description: string; kind: "request_response"; auth: { account: "optional" | "none" | "required"; actor: "optional" | "none" | "required"; roles?: readonly string[] | undefined; credential_types?: readonly string[] | undefined; required_scope?: string | undefined; }; async: true; streams?: string | undefined; error_reasons?: readonly string[] | undefined; rate_limit?: "both" | "account" | "ip" | undefined; } | { method: string; initiator: "frontend" | "backend" | "both"; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; description: string; kind: "remote_notification"; auth: null; side_effects: true; output: ZodVoid; async: true; streams?: string | undefined; error_reasons?: readonly string[] | undefined; rate_limit?: "both" | "account" | "ip" | undefined; } | { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; async: boolean; description: string; kind: "local_call"; auth: null; streams?: string | undefined; error_reasons?: readonly string[] | undefined; rate_limit?: "both" | "account" | "ip" | undefined; } | undefined

`zzz_dir`

The zzz_dir is the path to Zzz's primary directory on the server's filesystem. The server's ScopedFs instance restricts operations to this directory. The value is undefined when uninitialized, null when loading, and '' when disabled or no server.

type DiskfileDirectoryPath | null | undefined

gettersetter

`scoped_dirs`

Additional filesystem paths the server can access for user files.

type readonly DiskfileDirectoryPath[]

gettersetter

frontend_context
#

frontend_action_types.ts view source

{ get: (error_message?: string | undefined) => Frontend; get_maybe: () => Frontend | undefined; set: (value: Frontend) => Frontend; }

import {frontend_context} from '@fuzdev/zzz/frontend.svelte.js';

FrontendActionHandlers
#

FrontendActionHandlers import type {FrontendActionHandlers} from '@fuzdev/zzz/frontend_action_types.js';

Frontend action handlers organized by method and phase. Generated using spec.initiator to determine valid phases:

initiator: 'frontend' → send/execute phases
initiator: 'backend' → receive phases
initiator: 'both' → all valid phases

`heartbeat?`

type { send_request?: ((action_event: TypedActionEvent<"heartbeat", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; rec...

`cancel?`

type { send?: ((action_event: TypedActionEvent<"cancel", "send", "handling">) => void | Promise<void>) | undefined; }

`peer/ping?`

type { send_request?: ((action_event: TypedActionEvent<"peer/ping", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; rec...

`ping?`

type { send_request?: ((action_event: TypedActionEvent<"ping", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; receive_...

`session_load?`

type { send_request?: ((action_event: TypedActionEvent<"session_load", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; ...

`filer_change?`

type { receive?: ((action_event: TypedActionEvent<"filer_change", "receive", "handling">) => void | Promise<void>) | undefined; }

`diskfile_update?`

type { send_request?: ((action_event: TypedActionEvent<"diskfile_update", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefine...

`diskfile_create?`

type { send_request?: ((action_event: TypedActionEvent<"diskfile_create", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefine...

`diskfile_delete?`

type { send_request?: ((action_event: TypedActionEvent<"diskfile_delete", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefine...

`directory_create?`

type { send_request?: ((action_event: TypedActionEvent<"directory_create", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefin...

`media_finalize?`

type { send_request?: ((action_event: TypedActionEvent<"media_finalize", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined...

`transcription_create?`

type { send_request?: ((action_event: TypedActionEvent<"transcription_create", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | und...

`transcription_progress?`

type { receive?: ((action_event: TypedActionEvent<"transcription_progress", "receive", "handling">) => void | Promise<void>) | undefined; }

`job_cancel?`

type { send_request?: ((action_event: TypedActionEvent<"job_cancel", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; re...

`job_changed?`

type { receive?: ((action_event: TypedActionEvent<"job_changed", "receive", "handling">) => void | Promise<void>) | undefined; }

`completion_create?`

type { send_request?: ((action_event: TypedActionEvent<"completion_create", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefi...

`completion_progress?`

type { receive?: ((action_event: TypedActionEvent<"completion_progress", "receive", "handling">) => void | Promise<void>) | undefined; }

`toggle_main_menu?`

type { execute?: ((action_event: TypedActionEvent<"toggle_main_menu", "execute", "handling">) => { show: boolean; }) | undefined; }

`provider_load_status?`

type { send_request?: ((action_event: TypedActionEvent<"provider_load_status", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | und...

`terminal_create?`

type { send_request?: ((action_event: TypedActionEvent<"terminal_create", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefine...

`terminal_data_send?`

type { send_request?: ((action_event: TypedActionEvent<"terminal_data_send", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undef...

`terminal_data?`

type { receive?: ((action_event: TypedActionEvent<"terminal_data", "receive", "handling">) => void | Promise<void>) | undefined; }

`terminal_ack?`

type { send_request?: ((action_event: TypedActionEvent<"terminal_ack", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; ...

`terminal_resize?`

type { send_request?: ((action_event: TypedActionEvent<"terminal_resize", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefine...

`terminal_close?`

type { send_request?: ((action_event: TypedActionEvent<"terminal_close", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined...

`terminal_exited?`

type { receive?: ((action_event: TypedActionEvent<"terminal_exited", "receive", "handling">) => void | Promise<void>) | undefined; }

`workspace_open?`

type { send_request?: ((action_event: TypedActionEvent<"workspace_open", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined...

`workspace_close?`

type { send_request?: ((action_event: TypedActionEvent<"workspace_close", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefine...

`workspace_list?`

type { send_request?: ((action_event: TypedActionEvent<"workspace_list", "send_request", "handling">) => void | Promise<void>) | undefined; receive_response?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined; send_error?: ((action_event: TypedActionEvent<...>) => void | Promise<...>) | undefined...

`workspace_changed?`

type { receive?: ((action_event: TypedActionEvent<"workspace_changed", "receive", "handling">) => void | Promise<void>) | undefined; }

FrontendActionMethod
#

value + type

"heartbeat" | "cancel" | "peer/ping" | "ping" | "session_load" | "filer_change" | "diskfile_update" | "diskfile_create" | "diskfile_delete" | "directory_create" | "media_finalize" | ... 18 more ... | "workspace_changed"

import {FrontendActionMethod} from '@fuzdev/zzz/action_metatypes.js';

Names of all actions in the typed FrontendActionsApi surface — every spec the frontend may encounter (call, receive, or execute locally).

FrontendActionsApi
#

FrontendActionsApi import type {FrontendActionsApi} from '@fuzdev/zzz/action_metatypes.js';

Typed dispatch surface for the frontend's RPC client. Symmetric counterpart of BackendActionsApi. Async methods (request_response, remote_notification, async local_call) return Promise<Result<...>> and accept an optional RpcClientCallOptions second arg that threads signal, transport_name, and queue through to the peer. Sync local_call methods return values directly.

`heartbeat`

type (input?: void | undefined, options?: RpcClientCallOptions | undefined): Promise<Result<{ value: Record<string, never>; }, { error: { [x: string]: unknown; code: -32700 | ... 4 more ... | (number & $brand<...>); message: string; data?: unknown; }; }>>

`input?`

type void

optional

`options?`

type RpcClientCallOptions

optional

returns Promise<Result>

`cancel`

type (input: { request_id: string | number; }, options?: RpcClientCallOptions | undefined): Promise<Result<{ value: void; }, { error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; }>>

type RpcClientCallOptions

optional

returns Promise<Result>

type (input?: { chunk?: { [x: string]: unknown; model?: string | undefined; created_at?: string | undefined; done?: boolean | undefined; message?: { [x: string]: unknown; role: string; content: string; } | undefined; } | undefined; _meta?: { ...; } | undefined; } | undefined, options?: RpcClientCallOptions | undefined): Promise<...>

`input?`

type CompletionProgressInput

optional

`options?`

returns Promise<Result>

`workspace_list`

type (input?: void | undefined, options?: RpcClientCallOptions | undefined): Promise<Result<{ value: { workspaces: { path: string & $brand<"DiskfilePath"> & $brand<...>; name: string; opened_at: string; }[]; }; }, { ...; }>>

`input?`

type void

optional

`options?`

type RpcClientCallOptions

optional

returns Promise<Result>

`workspace_changed`

type (input: { type: "open" | "close"; workspace: { path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; name: string; opened_at: string; }; }, options?: RpcClientCallOptions | undefined): Promise<...>

`input`

type WorkspaceChangedInput

`options?`

type RpcClientCallOptions

optional

returns Promise<Result>

FrontendJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; ui: { id: string & $brand<"Uuid">; ... 9 more ...; desk_pinned: boolean; }; }

import {FrontendJson} from '@fuzdev/zzz/frontend.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`ui`

type UiJson

FrontendJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; ui?: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; show_main_dialog?: boolean | undefined; ... 6 more ...; desk_pinned?: boolean | undefined; } | undefined; }

import type {FrontendJsonInput} from '@fuzdev/zzz/frontend.svelte.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

`ui?`

type UiJsonInput

FrontendOptions
#

FrontendOptions import type {FrontendOptions} from '@fuzdev/zzz/frontend.svelte.js';

inheritance

extends: OmitStrict<CellOptions<typeof FrontendJson>, 'app'>

`app?`

Do not use - optional to avoid circular reference problem.

type undefined

`models?`

type ModelJsonInput[]

`bots?`

type { namerbot: string; }

`providers?`

type ProviderJsonInput[]

`cell_classes?`

Cell classes to register, keyed by their cell_class_name (default cell_classes).

type Record<string, ClassConstructor<Cell<any>>>

`action_specs?`

type ActionSpecUnion[]

`action_handlers?`

type FrontendActionHandlers

`http_rpc_url?`

type string | null

`http_headers?`

type Record<string, string>

`api_url?`

The backend API's URL or path, with no trailing slash — what the byte routes hang off (see file_bytes.ts). Without it nothing can be recorded.

type string | null

`socket_url?`

type string | null

`on_unauthenticated?`

Called when an action fails with unauthenticated — the backend no longer accepts this session (revoked, expired, logged out elsewhere). Typically wired to a session recheck (see create_session_recheck).

type (() => void) | null

FrontendRequestResponseMethod
#

FrontendRoot.svelte view source

value + type

"ping" import {FrontendRequestResponseMethod} from '@fuzdev/zzz/action_metatypes.js';

Names of request_response actions the frontend handles (initiator excludes frontend).

FrontendRoot
#

accepts children

import FrontendRoot from '@fuzdev/zzz/FrontendRoot.svelte';

`app`

type Frontend

`children`

type Snippet<[zzz: Frontend]>

snippet parameters

zzz Frontend

gen
#

action_metatypes.gen.ts view source

import {gen} from '@fuzdev/zzz/action_metatypes.gen.js';

get_cell_class_names
#

part_helpers.ts view source

(): ("Action" | "Actions" | "Capabilities" | "Parts" | "Chat" | "Chats" | "Diskfile" | "DiskfileTab" | "DiskfileTabs" | "DiskfilePart" | "DiskfileHistory" | "Diskfiles" | "DiskfilesEditor" | ... 22 more ... | "Workspaces")[]

import {get_cell_class_names} from '@fuzdev/zzz/cell_classes.js';

`method`

type ActionMethod

returns

SvgData

get_part_type_icon
#

(part: PartUnion): SvgData import {get_part_type_icon} from '@fuzdev/zzz/part_helpers.js';

`part`

type PartUnion

returns

SvgData

get_reorderable_drop_position
#

ReorderableValidDropPosition

(direction: ReorderableDirection, source_index: number, target_index: number): ReorderableValidDropPosition import {get_reorderable_drop_position} from '@fuzdev/zzz/reorderable_helpers.js';

Determine the drop position based on source and target indices and layout direction.

`direction`

type ReorderableDirection

`source_index`

type number

`target_index`

type number

returns

get_schema_class_info
#

(schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> | null | undefined): SchemaClassInfo | null import {get_schema_class_info} from '@fuzdev/zzz/cell_helpers.js';

Get schema class information from a Zod schema. This helps determine how to decode values based on their schema definition.

`schema`

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> | null | undefined

returns

SchemaClassInfo | null

get_unique_name
#

(name: string, existing_names: { has: (name: string) => boolean; }): string import {get_unique_name} from '@fuzdev/zzz/helpers.js';

Returns name, or name suffixed with the lowest number from 2 up that makes it unique among existing_names.

`name`

the preferred name

type string

`existing_names`

the taken names, like a Set or a Map keyed by name

type { has: (name: string) => boolean; }

returns

string

goto_unless_current
#

save_shortcut.ts view source

(path: string | URL, options?: GotoOptions | undefined): Promise<void> import {goto_unless_current} from '@fuzdev/zzz/nav.js';

Navigate to a path only if we're not already on that path. This avoids unnecessary navigation history changes when already at the destination.

`path`

type string | URL

`options?`

type GotoOptions

optional

returns

Promise<void>

handle_save_shortcut_keydown
#

(event: KeyboardEvent, save: (() => void) | null | undefined): void import {handle_save_shortcut_keydown} from '@fuzdev/zzz/save_shortcut.js';

Calls save on Ctrl+S / Cmd+S (case-insensitive, without Alt), swallowing the event so the browser's save dialog never opens and a page-level listener never saves a different editor than the focused one. An event a handler already took (defaultPrevented) is ignored, and a held key saves once per press.

`event`

the keydown event

type KeyboardEvent

`save`

the editor's save, or nullish to let the event through untouched

type (() => void) | null | undefined

returns

void

mutates

event — swallowed (`preventDefault` + `stopImmediatePropagation`) when it's the shortcut

handle_testing_emit_notifications
#

testing_action_specs.ts view source

(input: { count: number; }, ctx: ActionContext): { count: number; } | Promise<{ count: number; }> import {handle_testing_emit_notifications} from '@fuzdev/zzz/testing_action_specs.js';

Handler for _testing_emit_notifications. Emits count notifications via ctx.notify.

`input`

type TestingEmitNotificationsInput

`ctx`

type ActionContext

returns

TestingEmitNotificationsOutput | Promise<TestingEmitNotificationsOutput>

HANDLED
#

unique symbol import {HANDLED} from '@fuzdev/zzz/cell_helpers.js';

Sentinel value to indicate a parser has completely handled a property.

has_dependencies
#

(diskfile: Diskfile): boolean import {has_dependencies} from '@fuzdev/zzz/diskfile_helpers.js';

`diskfile`

type Diskfile

returns

boolean

HEALTH_PATH
#

"/health" import {HEALTH_PATH} from '@fuzdev/zzz/auth_gate.js';

The zzz backend's liveness route.

HEARTBEAT_INTERVAL_BOUNDS
#

MsSettingBounds import {HEARTBEAT_INTERVAL_BOUNDS} from '@fuzdev/zzz/socket_helpers.js';

Allowed heartbeat idle intervals — fuz_app's client scales the receive timeout with it (resolve_heartbeat_receive_timeout in @fuzdev/fuz_app/actions/socket.svelte.ts).

HISTORY_LABEL_DISCARDED_EDIT
#

"Discarded edit" import {HISTORY_LABEL_DISCARDED_EDIT} from '@fuzdev/zzz/diskfile_editor_state.svelte.js';

Label of a draft set aside unsaved (see DiskfileEditorState).

HISTORY_LABEL_DISK_CHANGE
#

"Disk change" import {HISTORY_LABEL_DISK_CHANGE} from '@fuzdev/zzz/diskfile_editor_state.svelte.js';

Label of a history entry recording a disk state.

HISTORY_LABEL_UNSAVED_EDIT
#

"Unsaved edit" import {HISTORY_LABEL_UNSAVED_EDIT} from '@fuzdev/zzz/diskfile_editor_state.svelte.js';

Label of the history entry holding a file's draft.

HISTORY_LIMIT_DEFAULT
#

512 import {HISTORY_LIMIT_DEFAULT} from '@fuzdev/zzz/actions.svelte.js';

HistoryEntry
#

media_icons.ts view source

value + type

{ id: string & $brand<"Uuid">; created: number; content: string; label: string; is_disk_change: boolean; is_unsaved_edit: boolean; is_original_state: boolean; is_discarded_edit: boolean; }

type boolean

Icon
#

Icon.svelte view source

accepts children

import Icon from '@fuzdev/zzz/Icon.svelte';

`size?`

Sets both the width and height of the svg. Overridden by the width and height props.

type string

optional default '1em'

`inline?`

Renders the SVG as an inline block with spacing appropriate for text. Defaults to false.

type boolean

optional default true

`shrink?`

type boolean

optional default false

`style?`

type string | null

optional

external types

ComponentProps<typeof Svg>

icon_microphone
#

{ label: string; paths: { d: string; }[]; } import {icon_microphone} from '@fuzdev/zzz/media_icons.js';

icon_record
#

media_icons.ts view source

{ label: string; paths: { d: string; }[]; } import {icon_record} from '@fuzdev/zzz/media_icons.js';

IndexDefinition
#

IndexDefinition<T, TResult> import type {IndexDefinition} from '@fuzdev/zzz/indexed_collection.svelte.js';

An index definition. The create_*_index helpers build these; a custom definition without a type is read through indexes.

generics

IndexDefinition<T extends IndexedItem, TResult = any>

`T`

constraint IndexedItem

`TResult`

default any

`key`

Unique identifier for this index.

type string

`type?`

The category the typed accessors check before reading the index.

type IndexType

`compute`

Function to compute the index value from scratch.

type (collection: IndexedCollection<T>): TResult

`collection`

type IndexedCollection<T>

returns TResult

`matches?`

Optional predicate to determine if an item is relevant to this index.

type (item: T): boolean

`item`

type T

returns boolean

`reactive?`

When true, the index is a $derived of compute — recomputed on the next read after the collection changes or any reactive state compute read changes, so it follows items whose indexed fields change after they're added. onadd and onremove are unused.

When false or omitted, onadd and onremove maintain the index incrementally, which is only correct when the indexed values of an item never change while it's in the collection.

type boolean

`onadd?`

Optional function to update the index when an item is added.

type (result: TResult, item: T, collection: IndexedCollection<T>): TResult

`result`

type TResult

`item`

type T

`collection`

type IndexedCollection<T>

returns TResult

`onremove?`

Optional function to update the index when an item is removed. Runs after the item (and every other item removed in the same call) has left by_id.

type (result: TResult, item: T, collection: IndexedCollection<T>): TResult

`result`

type TResult

`item`

type T

`collection`

type IndexedCollection<T>

returns TResult

IndexedCollection
#

import {IndexedCollection} from '@fuzdev/zzz/indexed_collection.svelte.js';

A reactive collection of items keyed by id, with indexes kept current as items are added and removed (see IndexDefinition for how each index is maintained).

generics

IndexedCollection<T extends IndexedItem>

`T`

constraint IndexedItem

`by_id`

The main source of truth, the full collection keyed by Uuid.

type SvelteMap<Uuid, T>

readonly

`values`

type T[]

readonly $derived

`keys`

type Uuid[]

readonly $derived

`size`

Get the current count of items.

type number

readonly $derived

`indexes`

All index values by key. Each property is an accessor over a reactive holder: incremental indexes are deeply reactive $state (so arrays can be mutated in place, and replaced by assignment), while reactive indexes are read-only $derived values.

type Record<string, any>

readonly

`constructor`

type new <T extends IndexedItem>(options?: IndexedCollectionOptions<T> | undefined): IndexedCollection<T>

`options?`

type IndexedCollectionOptions<T>

optional

`toJSON`

type (): readonly any[]

returns readonly any[]

`single_index`

Get a single-value index.

type (key: string): ReadonlyMap<any, T>

`key`

type string

returns ReadonlyMap<any, T>

throws

Error - if `key` isn't a `single` index

`derived_index`

Get a derived index.

type (key: string): T[]

`key`

type string

returns T[]

throws

Error - if `key` isn't a `derived` index

`clear`

Clear all items and reset indexes. Disposes the items when the collection has dispose_item.

type (): void

returns void

`where`

Get the items a multi index holds for value. The result is read-only: it's the index's own bucket, or a shared empty array when there's none, so copy it before changing it.

type <V = any>(index_key: string, value: V): readonly T[]

`index_key`

type string

`value`

type V

returns readonly T[]

throws

Error - if `index_key` isn't a `multi` index

`by_optional`

Get the item a single index holds for value, or undefined.

type <V = any>(index_key: string, value: V): T | undefined

`index_key`

type string

`value`

type V

returns T | undefined

throws

Error - if `index_key` isn't a `single` index

IndexedCollectionOptions
#

IndexedCollectionOptions<T> import type {IndexedCollectionOptions} from '@fuzdev/zzz/indexed_collection.svelte.js';

generics

IndexedCollectionOptions<T extends IndexedItem>

`T`

constraint IndexedItem

`indexes?`

type IndexDefinition<T, any>[]

`initial_items?`

type T[]

`dispose_item?`

Disposes an item after it leaves the collection through remove, remove_many, or clear. Pass it when the collection owns its items, so removed ones release their resources (for cells, their cell_registry entry).

type (item: T): void

`item`

type T

returns void

IndexedItem
#

value + type

{ id: string & $brand<"Uuid">; } import {IndexedItem} from '@fuzdev/zzz/indexed_collection_helpers.svelte.js';

Interface for objects that can be stored in an IndexedCollection.

`id`

type string & $brand<"Uuid">

IndexOptions
#

IndexOptions<T> import type {IndexOptions} from '@fuzdev/zzz/indexed_collection_helpers.svelte.js';

Common options interface for all index types.

generics

IndexOptions<T extends IndexedItem>

`T`

constraint IndexedItem

`key`

Unique key for this index.

type string

`matches?`

Optional predicate to determine if an item is relevant to this index.

type (item: T): boolean

`item`

type T

returns boolean

IndexType
#

IndexType

type "single" | "multi" | "derived"

import type {IndexType} from '@fuzdev/zzz/indexed_collection.svelte.js';

The index categories the typed accessors check: single_index and by_optional read a single index, where a multi one, and derived_index a derived one.

INVALID_DROP_CLASS_DEFAULT
#

`budget`

type number

default ACTION_PAYLOAD_BUDGET

returns

boolean

is_cell_type
#

<K extends CellClassNames>(cell: Cell<any> | null | undefined, class_name: K): cell is CellRegistryMap[K] import {is_cell_type} from '@fuzdev/zzz/cell_classes.js';

Type guard to check if a cell is an instance of a specific cell class.

`cell`

type Cell<any> | null | undefined

`class_name`

type K

returns

boolean

generics

is_cell_type<K extends CellClassNames>

`K`

constraint CellClassNames

is_completion_truncated
#

(completion_response: { created: string & $brand<"Datetime">; provider_name: "claude" | "chatgpt" | "gemini"; model: string; data: { type: "claude"; value: any; } | { type: "chatgpt"; value: any; } | { ...; }; } | null | undefined): boolean

import {is_completion_truncated} from '@fuzdev/zzz/response_helpers.js';

Whether a completion response was cut off by the output token limit or the context window rather than finished.

`completion_response`

type CompletionResponse | null | undefined

returns

boolean

is_job_finished
#

(status: "failed" | "queued" | "running" | "succeeded" | "cancelled"): boolean import {is_job_finished} from '@fuzdev/zzz/job_types.js';

Whether a job in status is over.

`status`

type JobStatus

returns

boolean

is_path_absolute
#

(path: string): boolean import {is_path_absolute} from '@fuzdev/zzz/diskfile_helpers.js';

`path`

type string

returns

boolean

is_plain_file_name
#

(name: string): boolean import {is_plain_file_name} from '@fuzdev/zzz/transcript_types.js';

Whether name is one path component: not empty, not . or .., and with no separator in it.

`name`

type string

returns

boolean

is_public_route
#

(pathname: string, public_paths?: readonly string[]): boolean import {is_public_route} from '@fuzdev/zzz/auth_gate.js';

Whether pathname is a public route or below one. A .html suffix is ignored: a static server without clean URLs serves the prerendered about.html at /about.html, and SvelteKit hydrates it as /about.

`pathname`

the URL pathname, e.g. page.url.pathname

type string

`public_paths`

the public route paths (resolved against the base path)

type readonly string[]

default PUBLIC_ROUTE_PATHS

returns

boolean

is_reorder_allowed
#

(can_reorder: ((from_index: number, to_index: number) => boolean) | undefined, source_index: number, target_index: number): boolean

import {is_reorder_allowed} from '@fuzdev/zzz/reorderable_helpers.js';

Check if reordering is allowed between two indices.

`can_reorder`

type ((from_index: number, to_index: number) => boolean) | undefined

`source_index`

type number

`target_index`

type number

returns

boolean

is_transcript_path
#

(path: string): boolean import {is_transcript_path} from '@fuzdev/zzz/transcript_helpers.js';

Whether path is named like a transcript sidecar.

`path`

type string

returns

boolean

ITEM_CLASS_DEFAULT
#

job.svelte.ts view source

"reorderable-item" import {ITEM_CLASS_DEFAULT} from '@fuzdev/zzz/reorderable.svelte.js';

Job
#

import {Job} from '@fuzdev/zzz/job.svelte.js';

A job on the backend: long-running work on a file — a transcription — that outlives the request that started it. Mirrors the backend's state: every job_changed notification replaces these fields (Jobs.receive_changed).

type string

$state.raw

`live_segments`

The segments a running transcription has decoded so far — a preview, in the order they arrived. Not part of the job's state on the backend: a reload starts it empty, and the transcript file is the result.

type TranscriptSegment[]

$state.raw

type new (options: JobOptions): Job

`options`

type JobOptions

job_cancel_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ job_id: $ZodBranded<ZodUUID, "Uuid", "out">; }, $strict>; output: ZodNull; async: true; description: string; }

import {job_cancel_action_spec} from '@fuzdev/zzz/action_specs.js';

job_changed_action_spec
#

job.svelte.ts view source

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ job: ZodObject<{ job_id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 10 more ...; stderr: ZodString; }, $strict>; }, $strict>; output: ZodVoid; async: true; description: string; }

import {job_changed_action_spec} from '@fuzdev/zzz/action_specs.js';

JobCancelInput
#

`updated`

`stderr`

type string

JobJsonInput
#

{ job_id: string; kind: "transcription"; input_path: string; queued_at: number; id?: string | undefined; created?: string | undefined; updated?: string | undefined; status?: "failed" | "queued" | "running" | "succeeded" | "cancelled" | undefined; ... 6 more ...; stderr?: string | undefined; }

import type {JobJsonInput} from '@fuzdev/zzz/job.svelte.js';

`job_id`

type string

`kind`

type "transcription"

`input_path`

type string

`queued_at`

type number

`id?`

type string

`created?`

type string

`updated?`

JobKind
#

job.svelte.ts view source

value + type

"transcription" import {JobKind} from '@fuzdev/zzz/job_types.js';

What a job does.

JobOptions
#

JobOptions import type {JobOptions} from '@fuzdev/zzz/job.svelte.js';

inheritance

extends: CellOptions<typeof JobJson>

Jobs
#

import {Jobs} from '@fuzdev/zzz/jobs.svelte.js';

App-level collection of the account's jobs, mirroring the backend's: jobs live in the daemon's memory, so this holds nothing of its own. job_changed notifications keep it current (receive_changed), and each session snapshot replaces it (reconcile) — after a daemon restart that's empty.

inheritance

extends: Cell<typeof JobsJson>

`items`

type IndexedCollection<Job>

readonly

`newest_first`

Jobs newest first, by when they were queued.

type Job[]

readonly $derived

`unfinished`

Jobs that are queued or running.

type Job[]

readonly $derived

`constructor`

type new (options: JobsOptions): Jobs

`options`

type JobsOptions

`get_by_job_id`

type (job_id: string & $brand<"Uuid">): Job | undefined

`job_id`

type Uuid

returns Job | undefined

`latest_for_input`

The newest job working on the file at path, if any — the one whose state a view of that file shows.

type (path: string & $brand<"DiskfilePath">): Job | undefined

`path`

type DiskfilePath

returns Job | undefined

`receive_changed`

Applies a job_changed notification: adds the job, or updates it in place.

type (snapshot: { job_id: string & $brand<"Uuid">; kind: "transcription"; status: "failed" | "queued" | "running" | "succeeded" | "cancelled"; progress: number | null; input_path: string & $brand<...>; ... 6 more ...; stderr: string; }): Job

`snapshot`

type JobSnapshot

returns Job

`receive_transcription_progress`

Applies a transcription_progress notification: appends the segments to the job's preview. Segments for a job this app hasn't heard of are dropped — its job_changed always comes first.

type (job_id: string & $brand<"Uuid">, segments: readonly { start_ms: number | null; end_ms: number | null; text: string; words?: { start_ms: number; end_ms: number; text: string; p: number; }[] | undefined; }[]): void

`job_id`

type Uuid

`segments`

type readonly TranscriptSegment[]

returns void

`reconcile`

Replaces the collection with a session snapshot's jobs: listed jobs are added or updated, and ones the backend no longer has — it restarted, or dropped them from its history — are removed.

type (snapshots: readonly { job_id: string & $brand<"Uuid">; kind: "transcription"; status: "failed" | "queued" | "running" | "succeeded" | "cancelled"; progress: number | null; input_path: string & $brand<...>; ... 6 more ...; stderr: string; }[]): void

`snapshots`

type readonly JobSnapshot[]

returns void

`transcribe`

Queues a transcription of the audio file at path (transcription_create). The job arrives through job_changed.

type (path: string & $brand<"DiskfilePath">, language?: string | undefined): Promise<Result<{ value: { job_id: string & $brand<"Uuid">; }; }, { error: { [x: string]: unknown; code: -32700 | ... 4 more ... | (number & $brand<...>); message: string; data?: unknown; }; }>>

`path`

the audio file

type DiskfilePath

`language?`

a language code, or omitted to detect it

type string

optional

returns Promise<Result>

the job's id, or the RPC error

`cancel`

Cancels a job (job_cancel). Its job_changed carries the outcome.

type (job: Job): Promise<Result<{ value: null; }, { error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }; }>>

`job`

type Job

returns Promise<Result>

the RPC result — not_found when the backend no longer has it

JobsJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; } import {JobsJson} from '@fuzdev/zzz/jobs.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

JobsJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; } import type {JobsJsonInput} from '@fuzdev/zzz/jobs.svelte.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

JobSnapshot
#

value + type

{ job_id: string & $brand<"Uuid">; kind: "transcription"; status: "failed" | "queued" | "running" | "succeeded" | "cancelled"; progress: number | null; input_path: string & $brand<...>; ... 6 more ...; stderr: string; }

import {JobSnapshot} from '@fuzdev/zzz/job_types.js';

A job as the backend reports it: long-running work on a file that outlives the request that started it. Twin of the backend's JobSnapshot.

`job_id`

type string & $brand<"Uuid">

`kind`

type "transcription"

`status`

type "failed" | "queued" | "running" | "succeeded" | "cancelled"

`progress`

How far along a running job is, 0 to 1 — null when unknown.

type number | null

`input_path`

The file the job works on.

type string & $brand<"DiskfilePath">

`output_path`

The file the job wrote, once it succeeded.

type (string & $brand<"DiskfilePath">) | null

`commands`

The command lines run so far, in order, for display.

type string[]

`queued_at`

Milliseconds since the epoch.

type number

`started_at`

type number | null

`ended_at`

type number | null

`error`

Why a failed job failed.

type string | null

`stderr`

The tail of the failing tool's stderr — derived from the input file, so render it as text.

type string

JobsOptions
#

JobsOptions import type {JobsOptions} from '@fuzdev/zzz/jobs.svelte.js';

inheritance

extends: CellOptions<typeof JobsJson>

JobStatus
#

JobStatusView.svelte view source

value + type

"failed" | "queued" | "running" | "succeeded" | "cancelled"

type "failed" | "queued" | "running" | "succeeded" | "cancelled"

import {JobStatus} from '@fuzdev/zzz/job_types.js';

Where a job is in its life. The last three are final.

JobStatusView
#

import JobStatusView from '@fuzdev/zzz/JobStatusView.svelte';

`job`

type Job

`show_input?`

Show the file the job works on — for a list of jobs across files.

type boolean

optional default false

joined_content_length
#

(content_lengths: Iterable<number | null | undefined>): number import {joined_content_length} from '@fuzdev/zzz/thread_helpers.js';

The length of contents joined with '\n\n', skipping null ones, as a turn joins its parts' content — from the contents' lengths, without building the string.

`content_lengths`

type Iterable<number | null | undefined, any, any>

returns

number

JSONRPC_ERROR_CODES
#

{ readonly ai_provider_error: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); readonly parse_error: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); ... 13 more ...; readonly request_cancelled: -32700 | ... 4 more ... | (number & $brand<...>); }

import {JSONRPC_ERROR_CODES} from '@fuzdev/zzz/zzz_jsonrpc_errors.js';

Extended error codes with zzz-specific AI provider error.

jsonrpc_error_messages
#

{ readonly ai_provider_error: (provider?: string | undefined, message?: string | undefined, data?: unknown) => { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }; ... 14 more ...; readonly request_cancelled: (...a...

import {jsonrpc_error_messages} from '@fuzdev/zzz/zzz_jsonrpc_errors.js';

Extended error message constructors.

jsonrpc_errors
#

{ readonly ai_provider_error: (provider?: string | undefined, message?: string | undefined, data?: unknown) => ThrownJsonrpcError; readonly parse_error: (...args: any[]) => ThrownJsonrpcError; ... 13 more ...; readonly request_cancelled: (...args: any[]) => ThrownJsonrpcError; }

import {jsonrpc_errors} from '@fuzdev/zzz/zzz_jsonrpc_errors.js';

Extended error throwers.

JsonrpcErrorName
#

JsonrpcErrorName

type JsonrpcErrorName | "ai_provider_error"

import type {JsonrpcErrorName} from '@fuzdev/zzz/zzz_jsonrpc_errors.js';

zzz error names — extends fuz_app's base set with AI provider errors.

KeyedIndexOptions
#

KeyedIndexOptions<T> import type {KeyedIndexOptions} from '@fuzdev/zzz/indexed_collection_helpers.svelte.js';

Options shared by the key-extracting single-value and multi-value indexes.

generics

KeyedIndexOptions<T extends IndexedItem>

`T`

constraint IndexedItem

inheritance

extends: IndexOptions<T>

`immutable_key?`

Declares that the extracted key(s) of an item never change while it's in the collection, so the index is maintained incrementally on add and remove (O(1) per change, reactive per key through a SvelteMap). If a key does change, lookups go stale — only use it for identity-like fields (like a diskfile's path).

By default the index is reactive: a $derived rebuilt in O(n) on the next read after the collection or any reactive field the extractor (or matches) reads changes, so it stays correct when a field like name is edited. The costs:

every rebuild makes a new map, so everything reading the index re-runs on any change to the collection or an indexed field, not just the keys it read
reads outside a reactive context (event handlers, plain functions) can't rely on change notifications, so each one checks all O(n) dependencies — fine for occasional lookups, but code that adds an item and then reads the index in a loop is O(n²)

Opt into immutable_key for large or busy collections when the key allows it.

type boolean

LANG_BY_EXTENSION
#

path_lang.ts view source

ReadonlyMap<string, string>

type ReadonlyMap<string, string>

import {LANG_BY_EXTENSION} from '@fuzdev/zzz/path_lang.js';

File extensions (lowercase, without the dot) and the fuz_code language each is highlighted as — a primary id registered on fuz_code's syntax_styler_global. JavaScript is highlighted by the TypeScript lexer (it registers js as an alias); JSX and TSX are left out, since that lexer doesn't read their markup.

lang_for_path
#

path_lang.ts view source

(path: string): string | null import {lang_for_path} from '@fuzdev/zzz/path_lang.js';

The fuz_code language to highlight the file at path as, by its extension (case-insensitive), or null when there's none — which disables highlighting.

`path`

the file's path or name

type string

returns

string | null

LevelMeter
#

LevelMeter import type {LevelMeter} from '@fuzdev/zzz/audio_capture.svelte.js';

Reads how loud a live stream is right now.

`read`

The current peak level, 0 (silence) to 1 (full scale).

type (): number

returns number

`close`

Releases what the meter holds.

type (): void

returns void

library_context
#

library.ts view source

{ get: (error_message?: string | undefined) => Library; get_maybe: () => Library | undefined; set: (value: Library) => Library; }

import {library_context} from '@fuzdev/zzz/library.js';

LIST_CLASS_DEFAULT
#

"reorderable-list" import {LIST_CLASS_DEFAULT} from '@fuzdev/zzz/reorderable.svelte.js';

ListWindow
#

ListWindow import type {ListWindow} from '@fuzdev/zzz/list_helpers.js';

A half-open [start, end) range of list indexes.

`start`

type number

Extra rows rendered on each side of the visible ones.

type number

LocalCallActionMethod
#

value + type

"toggle_main_menu" import {LocalCallActionMethod} from '@fuzdev/zzz/action_metatypes.js';

Names of all local_call actions.

logo_chatgpt
#

{ label: string; paths: { d: string; }[]; } import {logo_chatgpt} from '@fuzdev/zzz/logos.js';

logo_claude
#

{ label: string; fill: string; paths: { d: string; }[]; } import {logo_claude} from '@fuzdev/zzz/logos.js';

logo_gemini
#

{ label: string; fill: string; gradients: { type: "radial"; id: string; attrs: { cx: string; cy: string; r: string; gradientUnits: string; gradientTransform: string; }; stops: { offset: string; color: string; }[]; }[]; paths: { ...; }[]; }

import {logo_gemini} from '@fuzdev/zzz/logos.js';

logo_zzz
#

{ label: string; fill: string; paths: { d: string; }[]; } import {logo_zzz} from '@fuzdev/zzz/logos.js';

main_nav_items_default
#

MainDialog.svelte view source

NavItem[]

type NavItem[]

import {main_nav_items_default} from '@fuzdev/zzz/nav.js';

MainDialog
#

import MainDialog from '@fuzdev/zzz/MainDialog.svelte';

`disabled?`

type boolean

optional

MARKDOWN_DIRECTORY_INDEX_NAMES
#

readonly string[] import {MARKDOWN_DIRECTORY_INDEX_NAMES} from '@fuzdev/zzz/markdown_links.js';

The names a folder link opens, first found wins — a repository host shows the README.

MARKDOWN_EXTENSIONS
#

ReadonlySet<string>

type ReadonlySet<string>

import {MARKDOWN_EXTENSIONS} from '@fuzdev/zzz/diskfile_content_kind.js';

Extensions viewed as markdown.

MARKDOWN_VIEW_MODE_LABELS
#

Readonly<Record<MarkdownViewMode, string>>

type Readonly<Record<MarkdownViewMode, string>>

import {MARKDOWN_VIEW_MODE_LABELS} from '@fuzdev/zzz/markdown_view_mode.js';

What each mode is called in the UI.

MARKDOWN_VIEW_MODE_SHORTCUTS
#

Readonly<Record<MarkdownViewMode, string>>

type Readonly<Record<MarkdownViewMode, string>>

import {MARKDOWN_VIEW_MODE_SHORTCUTS} from '@fuzdev/zzz/markdown_view_mode.js';

Each mode's keyboard shortcut, Ctrl+Shift with its position in MARKDOWN_VIEW_MODES — as shown in the UI.

MARKDOWN_VIEW_MODES
#

MarkdownBrokenLinks.svelte view source

readonly MarkdownViewMode[]

type readonly MarkdownViewMode[]

import {MARKDOWN_VIEW_MODES} from '@fuzdev/zzz/markdown_view_mode.js';

The markdown view's modes, in the order the UI offers them.

MarkdownBrokenLinks
#

import MarkdownBrokenLinks from '@fuzdev/zzz/MarkdownBrokenLinks.svelte';

`links`

The document's links, from to_markdown_links; only the broken ones are listed.

type readonly MarkdownLink[]

`onselect`

Called with the link's position in links when it's clicked.

type (index: number, link: MarkdownLink) => void

snippet parameters

index number

link MarkdownLink

`attrs?`

type HTMLAttributes<HTMLElement>

optional

MarkdownHeading
#

MarkdownHeading import type {MarkdownHeading} from '@fuzdev/zzz/markdown_links.js';

A heading in a markdown document, for an outline.

`level`

type 6 | 2 | 1 | 4 | 3 | 5

`id`

The slug a #fragment names it by — '' when its text has none.

type string

`text`

type string

`start`

Where its source starts, a UTF-16 offset into the document.

type number

MarkdownLink
#

MarkdownLink import type {MarkdownLink} from '@fuzdev/zzz/markdown_links.js';

A link in a markdown document, resolved.

`reference`

The reference as written — the rendered <a>'s href, except where mdz collapses a leading slash run (see query_markdown_link_anchors).

type string

`text`

type string

`start`

Where its source starts, a UTF-16 offset into the document.

type number

`target`

type MarkdownLinkTarget

`status`

For a path link checked against an index, how it stands; else null.

type MarkdownLinkStatus | null

MarkdownLinkIndex
#

MarkdownLinkIndex import type {MarkdownLinkIndex} from '@fuzdev/zzz/markdown_links.js';

What the file index knows — the files and folders under its roots — for telling a link's target exists, is missing, or is out of sight.

`has_file`

Whether a file is indexed at path.

type (path: string): boolean

`path`

type string

returns boolean

`has_directory`

Whether an indexed file sits somewhere under path, a directory with a trailing /.

type (path: string): boolean

`path`

type string

returns boolean

`roots`

The directories the index covers, each with a trailing /.

type readonly string[]

readonly

MarkdownLinkMark
#

MarkdownLinkMark

type "broken" | "unknown"

import type {MarkdownLinkMark} from '@fuzdev/zzz/markdown_links.js';

How the preview marks a link: broken when the index says its target is missing, unknown when the index can't see where it points.

MarkdownLinkStatus
#

MarkdownLinkStatus

import type {MarkdownLinkStatus} from '@fuzdev/zzz/markdown_links.js';

How a path link stands against the file index:

file / directory — it names an indexed file, or a folder holding one
broken — it's inside a root the index covers, where the index would list it, yet nothing is there
the index can't say (see MarkdownLinkMark's unknown):
- outside — outside every root the index covers
- skipped — inside a folder the index never enters (FILE_INDEX_IGNORED_DIR_NAMES)
- root_relative — written /… and not found from the workspace's root, which may not be the repository's

MarkdownLinkTarget
#

MarkdownOutline.svelte view source

MarkdownLinkTarget

type { kind: "external"; href: string; } | { kind: "fragment"; fragment: string; } | { kind: "path"; path: string; directory: boolean; fragment: string | null; root_relative: boolean; } | { kind: "inert"; }

import type {MarkdownLinkTarget} from '@fuzdev/zzz/markdown_links.js';

Where a link in a markdown file leads:

external — an http: or https: URL, left to the browser
fragment — a heading in the same document (#id, decoded)
path — an absolute path on disk, with directory when the link names a folder (a trailing /, or a last segment of . or ..), its decoded #fragment if any, and root_relative when it was written /…
inert — nothing to follow: empty, query-only, another scheme, protocol-relative, malformed, climbing past its root, or relative with no file to resolve against

MarkdownOutline
#

import MarkdownOutline from '@fuzdev/zzz/MarkdownOutline.svelte';

`headings`

The document's headings, from to_markdown_headings.

type readonly MarkdownHeading[]

`onselect`

Called with the heading's position in headings when it's clicked.

type (index: number, heading: MarkdownHeading) => void

snippet parameters

index number

heading MarkdownHeading

MarkdownPreview
#

MarkdownPreview.svelte view source

import MarkdownPreview from '@fuzdev/zzz/MarkdownPreview.svelte';

`path?`

The absolute path of the file rendered — without it, relative links are inert.

type string | null

optional

`focus_key?`

MarkdownViewMode

type "split" | "preview" | "source"

import type {MarkdownViewMode} from '@fuzdev/zzz/markdown_view_mode.js';

split shows the source beside its preview, preview the rendered markdown alone, and source the source alone.

media_finalize_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; }, $strict>; output: ZodObject<...>; async: true; description: string; }

import {media_finalize_action_spec} from '@fuzdev/zzz/action_specs.js';

MediaFinalizeInput
#

value + type

{ path: string & $brand<"DiskfilePath">; } import {MediaFinalizeInput} from '@fuzdev/zzz/action_specs.js';

Input for media_finalize.

`path`

type string & $brand<"DiskfilePath">

MediaFinalizeOutput
#

value + type

{ size: number; } import {MediaFinalizeOutput} from '@fuzdev/zzz/action_specs.js';

Output for media_finalize: the rewritten file's size in bytes.

`size`

type number

Model
#

ModelContextmenu.svelte view source

import {Model} from '@fuzdev/zzz/model.svelte.js';

type number | undefined

$state.raw

`filesize`

Size in gigabytes.

type number | undefined

$state.raw

`cost_input`

type number | undefined

$state.raw

`cost_output`

type number | undefined

$state.raw

`training_cutoff`

type string | undefined

$state.raw

`provider`

Lookup the provider for this model.

type Provider | undefined

readonly $derived

`context_window_formatted`

type string | null

readonly $derived

`constructor`

type new (options: ModelOptions): Model

`options`

type ModelOptions

ModelContextmenu
#

accepts children

import ModelContextmenu from '@fuzdev/zzz/ModelContextmenu.svelte';

`model`

type Model | undefined

`children`

type Snippet<[]>

ModelDetail
#

ModelDetail.svelte view source

import ModelDetail from '@fuzdev/zzz/ModelDetail.svelte';

`model`

type Model

`attrs?`

type HTMLAttributes<HTMLDivElement>

optional

ModelJson
#

ModelLink.svelte view source

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; name: string; provider_name: "claude" | "chatgpt" | "gemini"; ... 9 more ...; training_cutoff?: string | undefined; }

import {ModelJson} from '@fuzdev/zzz/model.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

`updated?`

Required and initially equal to created.

`cost_input?`

type number

`cost_output?`

type number

`training_cutoff?`

type string

ModelLink
#

accepts children

import ModelLink from '@fuzdev/zzz/ModelLink.svelte';

`model`

type Model

`icon?`

Icon rendered before the model name. SvgData renders via Svg; 'logo' renders the provider's brand logo.

type SvgData | "logo"

value + type

string import {ModelName} from '@fuzdev/zzz/model.svelte.js';

ModelOptions
#

ModelPicker.svelte view source

ModelOptions import type {ModelOptions} from '@fuzdev/zzz/model.svelte.js';

inheritance

extends: CellOptions<typeof ModelJson>

ModelPicker
#

import ModelPicker from '@fuzdev/zzz/ModelPicker.svelte';

`onpick`

type (model: Model | undefined) => boolean | void

snippet parameters

model Model | undefined

`items?`

type Model[]

optional default models.ordered_by_name

`filter?`

type (model: Model) => boolean

model Model

`dialog_props?`

type

OmitStrict<Omit<HTMLDialogAttributes, "children" | "onclose"> & { show?: boolean | undefined; align?: DialogAlign | undefined; dismissable?: boolean | undefined; content_selector?: string | undefined; onbeforeclose?: (() => boolean | void) | undefined; onclose?: (() => void) | undefined; children: Snippet<[dialog: DialogContext]>; }, "children">

optional

`children?`

type Snippet<[]>

optional

Models
#

import {Models} from '@fuzdev/zzz/models.svelte.js';

inheritance

extends: Cell<typeof ModelsJson>

`items`

type IndexedCollection<Model>

readonly

`ordered_by_name`

Get all models ordered alphabetically by name.

type Model[]

readonly $derived

`constructor`

type new (options: ModelsOptions): Models

`options`

type ModelsOptions

`add`

type (model_json: { name: string; provider_name: "claude" | "chatgpt" | "gemini"; id?: string | undefined; created?: string | undefined; updated?: string | undefined; tags?: string[] | undefined; architecture?: string | undefined; ... 7 more ...; training_cutoff?: string | undefined; }): void

`model_json`

type ModelJsonInput

returns void

`add_many`

type (models_json: { name: string; provider_name: "claude" | "chatgpt" | "gemini"; id?: string | undefined; created?: string | undefined; updated?: string | undefined; tags?: string[] | undefined; architecture?: string | undefined; ... 7 more ...; training_cutoff?: string | undefined; }[]): void

`models_json`

type ModelJsonInput[]

returns void

`find_by_name`

type (name: string): Model | undefined

`name`

type string

returns Model | undefined

`filter_by_names`

type (names: string[]): Model[] | undefined

`names`

type string[]

returns Model[] | undefined

`filter_by_tag`

type (tag: string): readonly Model[]

`tag`

type string

returns readonly Model[]

models_default
#

{ name: string; provider_name: "claude" | "chatgpt" | "gemini"; id?: string | undefined; created?: string | undefined; updated?: string | undefined; tags?: string[] | undefined; architecture?: string | undefined; ... 7 more ...; training_cutoff?: string | undefined; }[]

type ModelJsonInput[]

import {models_default} from '@fuzdev/zzz/config_defaults.js';

ModelSchema
#

ZodCustom<Model, Model>

type ZodCustom<Model, Model>

import {ModelSchema} from '@fuzdev/zzz/model.svelte.js';

ModelsJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; items: { id: string & $brand<"Uuid">; ... 13 more ...; training_cutoff?: string | undefined; }[]; }

import {ModelsJson} from '@fuzdev/zzz/models.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`items`

type ModelJson[]

ModelsJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; items?: { name: string; provider_name: "claude" | "chatgpt" | "gemini"; id?: string | undefined; ... 11 more ...; training_cutoff?: string | undefined; }[] | undefined; }

import type {ModelsJsonInput} from '@fuzdev/zzz/models.svelte.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

`items?`

type ModelJsonInput[]

ModelsOptions
#

ModelSummary.svelte view source

ModelsOptions import type {ModelsOptions} from '@fuzdev/zzz/models.svelte.js';

inheritance

extends: CellOptions<typeof ModelsJson>

ModelSummary
#

import ModelSummary from '@fuzdev/zzz/ModelSummary.svelte';

`model`

type Model

`omit_provider?`

type boolean

optional

`attrs?`

type HTMLAttributes<HTMLDivElement>

optional

MsSettingBounds
#

MsSettingInput.svelte view source

MsSettingBounds import type {MsSettingBounds} from '@fuzdev/zzz/socket_helpers.js';

Inclusive range of a millisecond socket setting.

`min`

type number

`max`

type number

MsSettingInput
#

import MsSettingInput from '@fuzdev/zzz/MsSettingInput.svelte';

A millisecond setting as a range slider plus a number field. Both are one-way: the slider commits as it moves (its values are always in range), the number field commits on change (blur or Enter) so the setter's coercion and clamping don't fight each keystroke. After a commit the field shows the value the setter kept.

`id?`

The number field's id, for an external <label for>.

type string

optional

`label`

Accessible name for the slider, which has no <label> of its own.

type string

`value`

The current setting.

snippet parameters

value number

MultiIndexOptions
#

MultiIndexOptions<T, K> import type {MultiIndexOptions} from '@fuzdev/zzz/indexed_collection_helpers.svelte.js';

Options for multi-value indexes.

generics

MultiIndexOptions<T extends IndexedItem, K>

`T`

constraint IndexedItem

`K`

inheritance

extends: KeyedIndexOptions<T>

`extractor`

Function that extracts the key(s) from an item.

type (item: T): K | K[] | undefined

`item`

type T

returns K | K[] | undefined

`sort?`

Optional sort function for items in each bucket.

type (a: T, b: T): number

`a`

type T

`b`

type T

returns number

NavItem
#

NavLink.svelte view source

NavItem import type {NavItem} from '@fuzdev/zzz/nav.js';

`group`

type string

`items`

type NavLinkItem[]

NavLink
#

accepts children

import NavLink from '@fuzdev/zzz/NavLink.svelte';

`href`

type string

`selected?`

type boolean

optional

`show_selected_descendent?`

type boolean

optional default true

`children`

type Snippet<[selected: boolean, selected_descendent: boolean]>

snippet parameters

selected boolean

selected_descendent boolean

external types

OmitStrict<SvelteHTMLElements['a'], 'children'>

NavLinkItem
#

NavLinkItem import type {NavLinkItem} from '@fuzdev/zzz/nav.js';

`label`

type string

`href`

type string

`icon`

type SvgData

normalize_path
#

(path: string): string import {normalize_path} from '@fuzdev/zzz/diskfile_helpers.js';

Normalizes an absolute path the way the backend's ScopedFs does before touching the filesystem, without filesystem access: drops empty and . segments and any trailing /, and resolves .. against the preceding segment (never above /). The filer reports paths in this form.

`path`

an absolute path

type string

returns

string

the normalized path, / for the root

parse_new_diskfile_name
#

(name: string, kind: "file" | "folder"): Result<{ value: string; }, { message: string; }> import {parse_new_diskfile_name} from '@fuzdev/zzz/diskfile_helpers.js';

Parses a name entered for a new file or folder, a path relative to Diskfiles.new_files_dir (sub/name.ts creates any missing folders). Leading whitespace and slashes are dropped, as is trailing whitespace — like a pasted name's stray space or newline, they're almost never meant. Whitespace inside the name is kept, including around an inner /. Empty, ., and .. segments are left for the backend to normalize (sub/../a.txt creates a.txt). Refused: a blank or whitespace-only name; one that normalizes to the directory itself (sub/..); a whitespace-only segment (it would create a folder named by whitespace); a .. that climbs out of the directory; and for a file, a last segment that's empty, ., or .. (x/, x/., x/y/..), which names a folder, not a file.

`name`

the entered name

type string

`kind`

whether the name is for a file or a folder

type "file" | "folder"

returns

Result

the name to create, or a message saying why it's refused

parse_terminal_command
#

(text: string): { command: string; args: string[]; } | null import {parse_terminal_command} from '@fuzdev/zzz/terminal_helpers.js';

Splits a typed command line, trimmed, into its first whitespace-delimited word — the command, used for display and a preset's default name — and the rest of the line verbatim, whitespace separator included, as the one arg. The terminal types the line into sh (see format_terminal_command), so nothing is parsed here: quotes, comments, and unterminated lines are the shell's to interpret, and the line it gets is exactly the trimmed line that was typed.

`text`

type string

returns

{ command: string; args: string[]; } | null

the command and args, or null for a blank line

parse_transcript
#

(content: string | null): { [x: string]: unknown; version: number; source: { [x: string]: unknown; name: string; blake3: string; size: number; duration_ms: number; }; tool: { [x: string]: unknown; backend: string; version: string | null; model: string; model_blake3: string; params: { ...; }; }; language: string | null; segments: { ...; }[]; } | null

import {parse_transcript} from '@fuzdev/zzz/transcript_helpers.js';

Parses a transcript sidecar's content.

`content`

the file's text, or null when it isn't loaded

type string | null

returns

Transcript | null

the transcript, or null when the content isn't one

parse_url_param_uuid
#

workspace_helpers.ts view source

(value: unknown): (string & $brand<"Uuid">) | null import {parse_url_param_uuid} from '@fuzdev/zzz/nav.js';

Parse and validate a UUID parameter value from the URL.

`value`

type unknown

returns

Uuid | null

parse_workspace_path
#

(raw: string): Result<{ path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; }, { message: string; }>

import {parse_workspace_path} from '@fuzdev/zzz/workspace_helpers.js';

Parse user input (the open-workspace form or the ?workspace= URL param) into a workspace directory path, without throwing.

The input is trimmed and must be absolute. A leading ~ is rejected rather than expanded — the frontend can't know the daemon's home directory. The result is not canonical (/a/./b/ and symlinked paths pass through as given); the daemon canonicalizes on workspace_open, so callers should activate by the path in its output, not by this one.

`raw`

the path as typed or passed in the URL

type string

returns

Result

the path with a trailing slash, or a user-facing error message

Part
#

part_helpers.ts view source

import {Part} from '@fuzdev/zzz/part.svelte.js';

Abstract base class for all part types.

generics

Part<T extends z.ZodType = typeof PartJsonBase>

`T`

constraint z.ZodType

default typeof PartJsonBase

inheritance

extends: Cell<T>

`type`

type string

abstractreadonly

`start`

type number | null

$state.raw

`end`

type number | null

$state.raw

`length`

type number | null | undefined

readonly $derived.by

`token_count`

type number | null | undefined

readonly $derived.by

`content_preview`

content with a max length.

type string

readonly $derived.by

`add_attribute`

type (partial?: { id?: string | undefined; key?: string | undefined; value?: string | undefined; }): void

`partial`

type { id?: string | undefined; key?: string | undefined; value?: string | undefined; }

default EMPTY_OBJECT

returns void

`update_attribute`

type (id: string & $brand<"Uuid">, updates: Partial<OmitStrict<{ id: string & $brand<"Uuid">; key: string; value: string; }, "id">>): boolean

`id`

type Uuid

`updates`

type Partial<OmitStrict<XmlAttributeWithDefaults, "id">>

returns boolean

true if the attribute was updated, false if the attribute was not found

`remove_attribute`

type (id: string & $brand<"Uuid">): void

`id`

type Uuid

returns void

`create`

type (app: Frontend, json: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; start?: number | null | undefined; end?: number | ... 1 more ... | undefined; ... 7 more ...; content?: string | undefined; }, options?: TextPartOptions | undefined): TextPart

static

`app`

type Frontend

`json`

type TextPartJsonInput

`options?`

type TextPartOptions

optional

returns TextPart

`content`

type string | null | undefined

getterabstract

PART_ICONS
#

{ text: { label: string; paths: { d: string; }[]; }; diskfile: { label: string; paths: { d: string; }[]; }; } import {PART_ICONS} from '@fuzdev/zzz/part_helpers.js';

PartContextmenu
#

PartContextmenu.svelte view source

accepts children

import PartContextmenu from '@fuzdev/zzz/PartContextmenu.svelte';

`part`

type PartUnion

`owner?`

What the part belongs to — without one, there's no delete entry.

type PartOwner

optional

`children`

type Snippet<[]>

PartEditorForDiskfile
#

PartEditorForDiskfile.svelte view source

import PartEditorForDiskfile from '@fuzdev/zzz/PartEditorForDiskfile.svelte';

`diskfile_part`

type DiskfilePart

`show_actions?`

type boolean

optional default true

PartEditorForText
#

PartEditorForText.svelte view source

accepts children

import PartEditorForText from '@fuzdev/zzz/PartEditorForText.svelte';

`token_count?`

Estimated if not provided and show_stats is true.

snippet parameters

value string

`save_shortcut?`

Where Ctrl+S / Cmd+S triggers onsave — see SaveShortcutScope.

type SaveShortcutScope

optional

`text_part`

type TextPart

PartJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; name: string; start: number | null; end: number | null; ... 7 more ...; content: string; } | { ...; }

type TextPartJson | DiskfilePartJson

import {PartJson} from '@fuzdev/zzz/part.svelte.js';

Union of all part types for deserialization.

PartJsonBase
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; type: string; name: string; start: number | null; ... 6 more ...; summary: string | null; }

import {PartJsonBase} from '@fuzdev/zzz/part.svelte.js';

Common properties for all part types.

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; start?: number | null | undefined; end?: number | null | undefined; ... 7 more ...; content?: string | undefined; } | { ...; }

type TextPartJsonInput | DiskfilePartJsonInput

import type {PartJsonInput} from '@fuzdev/zzz/part.svelte.js';

PartJsonType
#

PartList.svelte view source

PartJsonType

type TextPartJson | DiskfilePartJson

import type {PartJsonType} from '@fuzdev/zzz/part.svelte.js';

PartList
#

import PartList from '@fuzdev/zzz/PartList.svelte';

PartOptions<T> import type {PartOptions} from '@fuzdev/zzz/part.svelte.js';

generics

PartOptions<T extends z.ZodType = typeof PartJsonBase>

`T`

constraint z.ZodType

default typeof PartJsonBase

inheritance

extends: CellOptions<T>

`json?`

type input<T>

PartOptionsUnion
#

part_helpers.ts view source

PartOptionsUnion

type TextPartOptions | DiskfilePartOptions

import type {PartOptionsUnion} from '@fuzdev/zzz/part.svelte.js';

PartOwner
#

PartOwner

type Prompt | Turn

import type {PartOwner} from '@fuzdev/zzz/part_helpers.js';

What a part belongs to. A Prompt owns its part instances; a Turn references parts in app.parts. Both remove through remove_part, which disposes the part once nothing owns it.

PartRemoveButton
#

PartRemoveButton.svelte view source

accepts children

import PartRemoveButton from '@fuzdev/zzz/PartRemoveButton.svelte';

`part`

type PartUnion

`owner`

type PartOwner

external types

OmitStrict<SvelteHTMLElements['button'], 'part'>

Parts
#

import {Parts} from '@fuzdev/zzz/parts.svelte.js';

inheritance

extends: Cell<typeof PartsJson>

`items`

type IndexedCollection<PartUnion>

readonly

`constructor`

type new (options: PartsOptions): Parts

`options`

type PartsOptions

`add`

Add a part to the collection.

type (json: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; start?: number | null | undefined; end?: number | null | undefined; ... 7 more ...; content?: string | undefined; } | { ...; }): PartUnion

`json`

type PartJsonInput

returns PartUnion

`generate_unique_name`

Generate a unique name for a part.

type (base_name?: string): string

`base_name`

type string

default 'new part'

returns string

`remove`

Remove a part by id.

type (id: string & $brand<"Uuid">): boolean

`id`

type Uuid

returns boolean

`remove_unreferenced`

Removes the parts in ids that no turn references anymore. Turns are the only owners of the parts in this collection — a prompt's parts are its own instances, and Diskfile.part is a lookup, not a reference.

type (ids: Iterable<string & $brand<"Uuid">>): number

`ids`

type Iterable<Uuid, any, any>

returns number

the number of parts removed

`find_part_by_diskfile_path`

Find a part that references a specific file path.

type (path: string): PartUnion | undefined

`path`

type string

returns PartUnion | undefined

PartSchema
#

ZodCustom<Part<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>, Part<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>

type ZodCustom<Part<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>, Part<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>

import {PartSchema} from '@fuzdev/zzz/part.svelte.js';

PartsJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; items: ({ id: string & $brand<"Uuid">; ... 12 more ...; content: string; } | { ...; })[]; }

import {PartsJson} from '@fuzdev/zzz/parts.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`items`

type PartJson[]

PartsJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; items?: ({ id?: string | undefined; created?: string | undefined; updated?: string | undefined; ... 10 more ...; content?: string | undefined; } | { ...; })[] | undefined; }

import type {PartsJsonInput} from '@fuzdev/zzz/parts.svelte.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

`items?`

type PartJsonInput[]

PartsOptions
#

PartStats.svelte view source

PartsOptions import type {PartsOptions} from '@fuzdev/zzz/parts.svelte.js';

inheritance

extends: CellOptions<typeof PartsJson>

PartStats
#

import PartStats from '@fuzdev/zzz/PartStats.svelte';

`part`

type PartUnion

PartSummary
#

PartSummary.svelte view source

import PartSummary from '@fuzdev/zzz/PartSummary.svelte';

`part`

type PartUnion

`owner?`

What the part belongs to — without one, the part can't be removed from here.

type PartOwner

optional

PartToggleButton
#

PartToggleButton.svelte view source

import PartToggleButton from '@fuzdev/zzz/PartToggleButton.svelte';

`part`

type PartUnion

`attrs?`

type HTMLInputAttributes

optional

PartUnion
#

PartView.svelte view source

PartUnion

type TextPart | DiskfilePart

import type {PartUnion} from '@fuzdev/zzz/part.svelte.js';

PartView
#

import PartView from '@fuzdev/zzz/PartView.svelte';

`part`

type PartUnion

`owner?`

What the part belongs to — without one, the part can't be removed from here.

type PartOwner

optional

`show_actions?`

type boolean

optional default true

PathWithLeadingSlash
#

zod_helpers.ts view source

value + type

string import {PathWithLeadingSlash} from '@fuzdev/zzz/zod_helpers.js';

PathWithoutTrailingSlash
#

zod_helpers.ts view source

value + type

string import {PathWithoutTrailingSlash} from '@fuzdev/zzz/zod_helpers.js';

PathWithTrailingSlash
#

zod_helpers.ts view source

value + type

string import {PathWithTrailingSlash} from '@fuzdev/zzz/zod_helpers.js';

pick_recording_format
#

Picker.svelte view source

(is_type_supported: (mime_type: string) => boolean): RecordingFormat | null import {pick_recording_format} from '@fuzdev/zzz/recording_helpers.js';

Picks the first of RECORDING_FORMATS the browser can record.

`is_type_supported`

MediaRecorder.isTypeSupported

type (mime_type: string) => boolean

returns

RecordingFormat | null

the format, or null when the browser records none of them

Picker
#

accepts children

import Picker from '@fuzdev/zzz/Picker.svelte';

`items`

The collection of items - required

type T[]

`onpick`

Handle both picking an item or no item. Return false to prevent closing.

type (item: T | undefined) => boolean | void

snippet parameters

item T | undefined

`filter?`

type (item: T) => boolean

optional

type string | null

optional default null

`search_text?`

The text an item is searched by. When given, the picker shows a filter input that keeps the items whose text contains the query, ignoring case.

type (item: T) => string

optional

snippet parameters

item T

`search_placeholder?`

type string

optional default 'filter'

`windowed?`

Render only the rows near the viewport of the picker's own scrolling list — for pickers over thousands of items. Every row must have the same height. See SortableList.

type boolean

optional default false

`children`

Called once per rendered item

type Snippet<[item: T, pick: (item: T) => void]>

snippet parameters

item T

pick (item: T) => void

generics

Picker<T extends {id: Uuid}>

`T`

constraint {id: Uuid}

PickerDialog
#

PickerDialog.svelte view source

accepts children

import PickerDialog from '@fuzdev/zzz/PickerDialog.svelte';

`items`

The collection of items - required

type T[]

`onpick`

Handle both picking an item or no item. Return false to prevent closing.

type (item: T | undefined) => boolean | void

snippet parameters

item T | undefined

`filter?`

type (item: T) => boolean

optional

type string | null

optional

`search_text?`

The text an item is searched by. When given, the picker shows a filter input that keeps the items whose text contains the query, ignoring case.

type (item: T) => string

optional

snippet parameters

item T

`search_placeholder?`

type string

optional

`windowed?`

Render only the rows near the viewport of the picker's own scrolling list — for pickers over thousands of items. Every row must have the same height. See SortableList.

type boolean

optional

`children`

Called once per rendered item

type Snippet<[item: T, pick: (item: T) => void]>

snippet parameters

item T

pick (item: T) => void

`show?`

type boolean

optional bindable default false

`dialog_props?`

type

OmitStrict<Omit<HTMLDialogAttributes, "children" | "onclose"> & { show?: boolean | undefined; align?: DialogAlign | undefined; dismissable?: boolean | undefined; content_selector?: string | undefined; onbeforeclose?: (() => boolean | void) | undefined; onclose?: (() => void) | undefined; children: Snippet<[dialog: DialogContext]>; }, "children">

optional

generics

PickerDialog<T extends {id: Uuid}>

`T`

constraint {id: Uuid}

ping_action_spec
#

{ method: string; kind: "request_response"; initiator: "both"; auth: { account: "none"; actor: "none"; }; side_effects: false; input: ZodVoid; output: ZodObject<{ ping_id: ZodUnion<readonly [ZodString, ZodNumber]>; }, $strict>; async: true; description: string; }

import {ping_action_spec} from '@fuzdev/zzz/action_specs.js';

PING_HISTORY_MAX
#

6 import {PING_HISTORY_MAX} from '@fuzdev/zzz/capabilities.svelte.js';

Maximum number of ping records to keep.

PingData
#

PingForm.svelte view source

PingData import type {PingData} from '@fuzdev/zzz/capabilities.svelte.js';

`ping_id`

type JsonrpcRequestId

`completed`

type boolean

`sent_time`

type number

`received_time`

type number | null

`round_trip_time`

type number | null

PingForm
#

accepts children

import PingForm from '@fuzdev/zzz/PingForm.svelte';

`children?`

type Snippet<[]>

optional

PingOutput
#

value + type

{ ping_id: string | number; } import {PingOutput} from '@fuzdev/zzz/action_specs.js';

Output for ping. Echoes the JSON-RPC request id back as ping_id.

`ping_id`

type string | number

PONG_DISPLAY_LIMIT
#

6 import {PONG_DISPLAY_LIMIT} from '@fuzdev/zzz/actions.svelte.js';

probe_backend
#

(fetch_health?: () => Promise<Response>): Promise<boolean> import {probe_backend} from '@fuzdev/zzz/auth_gate.js';

Probe whether a zzz backend is serving. Only its health reply counts — a static server (or an SPA fallback answering every path with HTML) is not a backend, and neither is a network error.

`fetch_health`

fetches the health route (injectable for tests)

type () => Promise<Response>

default () => fetch(HEALTH_PATH)

returns

Promise<boolean>

whether the zzz backend answered

probe_session
#

ProgressBar.svelte view source

(fetch_status?: () => Promise<Response>): Promise<SessionProbe> import {probe_session} from '@fuzdev/zzz/session_recheck.js';

Probe the account status endpoint.

`fetch_status`

fetches the status route (injectable for tests)

type () => Promise<Response>

default () => ui_fetch(ACCOUNT_STATUS_PATH)

returns

Promise<SessionProbe>

what the probe learned about the session

ProgressBar
#

import ProgressBar from '@fuzdev/zzz/ProgressBar.svelte';

`value`

The percentage value of the progress bar, 0-100.

type number

`text?`

type Snippet<[]>

optional

ProgressMeta
#

value + type

{ [x: string]: unknown; progressToken?: (string & $brand<"Uuid">) | undefined; } import {ProgressMeta} from '@fuzdev/zzz/action_specs.js';

Progress-token envelope shared by streaming actions. Carries the caller's progressToken so streamed *_progress notifications can be correlated with the originating request. looseObject lets transports tack on additional MCP-style metadata without a schema bump.

`progressToken?`

type string & $brand<"Uuid">

`[key: string]`

type unknown

Prompt
#

import {Prompt} from '@fuzdev/zzz/prompt.svelte.js';

type string

readonly $derived

`constructor`

type new (options: PromptOptions): Prompt

`options`

type PromptOptions

`add_part`

Add a part to this prompt.

type (part: PartUnion): PartUnion

`part`

type PartUnion

returns PartUnion

`remove_part`

Remove and dispose a part — a prompt's parts are its own, not shared.

type (id: string & $brand<"Uuid">): boolean

`id`

type Uuid

returns boolean

`remove_all_parts`

Remove and dispose all parts.

type (): void

returns void

`dispose`

Disposes the prompt's parts along with it.

type (): void

returns void

`reorder_parts`

type (from_index: number, to_index: number): void

`from_index`

type number

`to_index`

type number

returns void

prompt_create_diskfile
#

(diskfiles: Diskfiles, kind: "file" | "folder"): Promise<void> import {prompt_create_diskfile} from '@fuzdev/zzz/diskfile_helpers.js';

Asks for a name and creates a file or folder of that name in Diskfiles.new_files_dir (see Diskfiles.create_file and Diskfiles.create_directory), alerting on failure — including a name parse_new_diskfile_name refuses, such as a whitespace-only one — with the name first (couldn't create file a.txt: <reason>). A backend failure is already logged by its action handler. Cancelling or entering an empty name does nothing.

`diskfiles`

the diskfiles to create in

type Diskfiles

`kind`

whether to create a file or a folder

type "file" | "folder"

returns

Promise<void>

PromptActionContent
#

PromptContextmenu.svelte view source

string import type {PromptActionContent} from '@fuzdev/zzz/prompt.svelte.js';

PromptContextmenu
#

accepts children

import PromptContextmenu from '@fuzdev/zzz/PromptContextmenu.svelte';

`prompt`

type Prompt

`children`

type Snippet<[]>

PromptJson
#

PromptList.svelte view source

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; name: string; parts: ({ id: string & $brand<"Uuid">; ... 12 more ...; content: string; } | { ...; })[]; }

import {PromptJson} from '@fuzdev/zzz/prompt.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

`name?`

type string

`parts?`

type PartJsonInput[]

PromptList
#

import PromptList from '@fuzdev/zzz/PromptList.svelte';

PromptListitem
#

PromptListitem.svelte view source

import PromptListitem from '@fuzdev/zzz/PromptListitem.svelte';

`prompt`

type Prompt

`selected?`

type boolean

optional

PromptMessage
#

PromptMessage import type {PromptMessage} from '@fuzdev/zzz/prompt.svelte.js';

`role`

type "user" | "system"

`content`

type string[]

PromptOptions
#

PromptOptions import type {PromptOptions} from '@fuzdev/zzz/prompt.svelte.js';

inheritance

extends: CellOptions<typeof PromptJson>

`name?`

type string

Prompts
#

import {Prompts} from '@fuzdev/zzz/prompts.svelte.js';

inheritance

extends: Cell<typeof PromptsJson>

`items`

type IndexedCollection<Prompt>

readonly

`selected_id_last_non_null`

type Uuid | null

$state.raw

`selected`

type Prompt | undefined

readonly $derived

`show_sort_controls`

Controls visibility of sort controls in the prompts list.

type boolean

$state.raw

`ordered_items`

Ordered array of prompts derived from the manual_order index.

type Prompt[]

readonly $derived

`constructor`

type new (options: PromptsOptions): Prompts

`options`

type PromptsOptions

`filter_by_diskfile_path`

The prompts with a diskfile part for path. A prompt owns its part instances, so a file is matched by path, not by part identity.

type (path: string & $brand<"DiskfilePath">): Prompt[]

`path`

type DiskfilePath

returns Prompt[]

`add`

type (json?: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; parts?: ({ id?: string | undefined; created?: string | undefined; ... 11 more ...; content?: string | undefined; } | { ...; })[] | undefined; } | undefined): Prompt

`json?`

type PromptJsonInput

optional

returns Prompt

`generate_unique_name`

type (base_name?: string): string

`base_name`

type string

default 'new prompt'

returns string

`add_many`

type (prompts_json: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; parts?: ({ id?: string | undefined; created?: string | undefined; ... 11 more ...; content?: string | undefined; } | { ...; })[] | undefined; }[]): Prompt[]

`prompts_json`

type PromptJsonInput[]

returns Prompt[]

`remove`

Removes a prompt, disposing it with its parts — see remove_many.

type (prompt: Prompt): void

`prompt`

type Prompt

returns void

`remove_many`

Removes prompts, selecting another if the selected one went, and forgetting the last selected one if it went.

type (prompt_ids: (string & $brand<"Uuid">)[]): number

`prompt_ids`

type Uuid[]

returns number

the number of prompts removed

`select`

type (prompt_id: (string & $brand<"Uuid">) | null): Promise<void>

`prompt_id`

type Uuid | null

returns Promise<void>

`select_next`

type (): Promise<void>

returns Promise<void>

`navigate_to`

type (prompt_id: (string & $brand<"Uuid">) | null, force?: boolean): Promise<void>

`prompt_id`

type Uuid | null

`force`

type boolean

default false

returns Promise<void>

`reorder_prompts`

type (from_index: number, to_index: number): void

`from_index`

type number

`to_index`

type number

returns void

`toggle_sort_controls`

Toggles the visibility of sort controls in the prompts list.

type (value?: boolean): void

`value`

type boolean

default !this.show_sort_controls

returns void

`selected_id`

type Uuid | null

gettersetter

PromptSchema
#

ZodCustom<Prompt, Prompt>

type ZodCustom<Prompt, Prompt>

import {PromptSchema} from '@fuzdev/zzz/prompt.svelte.js';

PromptsJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; items: { id: string & $brand<"Uuid">; created: string & $brand<...>; updated: string & $brand<...>; name: string; parts: ({ ...; } | { ...; })[]; }[]; selected_id: string | null; show_sort_controls: boolean; }

import {PromptsJson} from '@fuzdev/zzz/prompts.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

`items?`

type PromptJsonInput[]

`selected_id?`

type string | null

`show_sort_controls?`

type boolean

PromptsOptions
#

PromptsOptions import type {PromptsOptions} from '@fuzdev/zzz/prompts.svelte.js';

inheritance

extends: CellOptions<typeof PromptsJson>

PromptsSchema
#

PromptStats.svelte view source

ZodCustom<Prompts, Prompts>

type ZodCustom<Prompts, Prompts>

import {PromptsSchema} from '@fuzdev/zzz/prompts.svelte.js';

PromptStats
#

import PromptStats from '@fuzdev/zzz/PromptStats.svelte';

`prompt`

type Prompt

Provider
#

provider.svelte.ts view source

import {Provider} from '@fuzdev/zzz/provider.svelte.js';

type new (options: ProviderOptions): Provider

`options`

type ProviderOptions

PROVIDER_ERROR_NEEDS_API_KEY
#

"needs API key" import {PROVIDER_ERROR_NEEDS_API_KEY} from '@fuzdev/zzz/provider_types.js';

PROVIDER_ERROR_REASON_HTTP
#

"provider_http_error" import {PROVIDER_ERROR_REASON_HTTP} from '@fuzdev/zzz/provider_types.js';

data.reason on a completion error caused by a non-2xx response from the provider's API — data.status carries the upstream HTTP status.

provider_load_status_action_spec
#

provider_capability.svelte.ts view source

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: false; input: ZodObject<{ provider_name: ZodEnum<{ claude: "claude"; chatgpt: "chatgpt"; gemini: "gemini"; }>; reload: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; de...

import {provider_load_status_action_spec} from '@fuzdev/zzz/action_specs.js';

ProviderCapability
#

import {ProviderCapability} from '@fuzdev/zzz/provider_capability.svelte.js';

Per-provider availability capability, derived from the backend's provider_status. Plain reactive class — not a Cell: it has no persisted state, everything is $derived from app.lookup_provider_status(name). One instance per ProviderName lives in Capabilities.providers, collapsing what were three hand-rolled claude/chatgpt/gemini $derived blocks plus their init_*_check/check_* pairs into a single keyed shape.

inheritance

implements: Capability<null | undefined>

`app`

type Frontend

readonly

`name`

type ProviderName

readonly

`message_id`

type string | number | null

readonly

`status`

type AsyncStatus

readonly $derived

`data`

null available, undefined unknown — matches the Capability data contract.

type null | undefined

readonly $derived

`error_message`

type string | null

readonly $derived

`updated`

type number | null

readonly $derived

`constructor`

type new (options: ProviderCapabilityOptions): ProviderCapability

`options`

type ProviderCapabilityOptions

`init_check`

Check availability only if it hasn't been checked before (when status is 'initial').

type (): Promise<void>

returns Promise<void>

`check`

Check availability by loading provider status from the backend.

type (): Promise<void>

returns Promise<void>

ProviderCapabilityOptions
#

provider_capability.svelte.ts view source

ProviderCapabilityOptions import type {ProviderCapabilityOptions} from '@fuzdev/zzz/provider_capability.svelte.js';

`app`

type Frontend

`name`

type ProviderName

ProviderData
#

{ type: "claude"; value: any; } | { type: "chatgpt"; value: any; } | { type: "gemini"; value: { text: string; candidates?: any[] | null | undefined; function_calls?: any[] | null | undefined; prompt_feedback?: any; usage_metadata?: any; }; }

type ProviderDataClaude | ProviderDataChatgpt | ProviderDataGemini

import type {ProviderData} from '@fuzdev/zzz/provider_types.js';

ProviderDataChatgpt
#

value + type

{ type: "chatgpt"; value: any; } import {ProviderDataChatgpt} from '@fuzdev/zzz/provider_types.js';

`type`

type "chatgpt"

`value`

type any

ProviderDataClaude
#

value + type

{ type: "claude"; value: any; } import {ProviderDataClaude} from '@fuzdev/zzz/provider_types.js';

`type`

type "claude"

`value`

type any

ProviderDataGemini
#

value + type

{ type: "gemini"; value: { text: string; candidates?: any[] | null | undefined; function_calls?: any[] | null | undefined; prompt_feedback?: any; usage_metadata?: any; }; }

import {ProviderDataGemini} from '@fuzdev/zzz/provider_types.js';

`type`

type "gemini"

`value`

type { text: string; candidates?: any[] | null | undefined; function_calls?: any[] | null | undefined; prompt_feedback?: any; usage_metadata?: any; }

ProviderDataSchema
#

ProviderDetail.svelte view source

ZodDiscriminatedUnion<[ZodObject<{ type: ZodLiteral<"claude">; value: ZodDefault<ZodOptional<ZodAny>>; }, $strict>, ZodObject<{ type: ZodLiteral<...>; value: ZodDefault<...>; }, $strict>, ZodObject<...>], "type">

type ZodDiscriminatedUnion<[ZodObject<{ type: ZodLiteral<"claude">; value: ZodDefault<ZodOptional<ZodAny>>; }, $strict>, ZodObject<{ type: ZodLiteral<"chatgpt">; value: ZodDefault<ZodOptional<ZodAny>>; }, $strict>, ZodObject<{ type: ZodLiteral<"gemini">; value: ZodObject<{ text: ZodString; candidates: ZodOptional<ZodNullable<ZodArray<ZodAny>>>; function_calls: ZodOptional<ZodNullable<ZodArray<ZodAny>>>; prompt_feedback: ZodOptional<ZodNullable<ZodAny>>; usage_metadata: ZodOptional<ZodNullable<ZodAny>>; }, $strict>; }, $strict>], "type">

import {ProviderDataSchema} from '@fuzdev/zzz/provider_types.js';

ProviderDetail
#

import ProviderDetail from '@fuzdev/zzz/ProviderDetail.svelte';

`provider`

type Provider

`attrs?`

type HTMLAttributes<HTMLDivElement>

optional

ProviderJson
#

provider.svelte.ts view source

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; name: "claude" | "chatgpt" | "gemini"; title: string; url: string; homepage: string; company: string; api_key_url: string | null; }

import {ProviderJson} from '@fuzdev/zzz/provider.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

ProviderLink
#

ProviderLink.svelte view source

accepts children

import ProviderLink from '@fuzdev/zzz/ProviderLink.svelte';

`provider`

type Provider | null | undefined

`icon?`

Icon rendered before the label. SvgData renders via Svg; 'logo' renders the provider's brand logo.

type SvgData | "logo"

optional

`icon_props?`

Props forwarded to the rendered icon, ProviderLogo or Svg.

type Record<string, any>

optional

`label?`

Which provider field labels the link. Defaults to 'title'.

type "title" | "name"

optional default 'title'

`fallback?`

type Snippet<[]>

optional

`children?`

type Snippet<[]>

optional

external types

SvelteHTMLElements['a']

ProviderLoadStatusInput
#

value + type

{ provider_name: "claude" | "chatgpt" | "gemini"; reload?: boolean | undefined; } import {ProviderLoadStatusInput} from '@fuzdev/zzz/action_specs.js';

Input for provider_load_status.

`provider_name`

type "claude" | "chatgpt" | "gemini"

`reload?`

type boolean

ProviderLoadStatusOutput
#

ProviderLogo.svelte view source

value + type

{ status: { name: string; available: true; checked_at: number; } | { name: string; available: false; error: string; checked_at: number; }; }

import {ProviderLoadStatusOutput} from '@fuzdev/zzz/action_specs.js';

Output for provider_load_status.

`status`

type ProviderStatus

ProviderLogo
#

accepts children

import ProviderLogo from '@fuzdev/zzz/ProviderLogo.svelte';

`name`

type ProviderName

`fill?`

type string | null

optional default 'var(--text_color)'

`size?`

type string

optional default 'var(--font_size, var(--font_size_xl))'

`inline?`

type boolean

optional default true

external types

OmitStrict<ComponentProps<typeof Svg>, 'data'>

ProviderName
#

provider.svelte.ts view source

value + type

"claude" | "chatgpt" | "gemini"

type "claude" | "chatgpt" | "gemini"

import {ProviderName} from '@fuzdev/zzz/provider_types.js';

See app.providers.names for the available names at runtime.

ProviderOptions
#

ProviderOptions import type {ProviderOptions} from '@fuzdev/zzz/provider.svelte.js';

inheritance

extends: CellOptions<typeof ProviderJson>

Providers
#

providers.svelte.ts view source

import {Providers} from '@fuzdev/zzz/providers.svelte.js';

inheritance

extends: Cell<typeof ProvidersJson>

`items`

type Provider[]

$state

`names`

type readonly ProviderName[]

readonly $derived

`constructor`

type new (options: ProvidersOptions): Providers

`options`

type ProvidersOptions

`add`

type (provider: Provider): void

`provider`

type Provider

returns void

`find_by_name`

type (name: string): Provider | undefined

`name`

type string

returns Provider | undefined

providers_default
#

providers.svelte.ts view source

{ name: "claude" | "chatgpt" | "gemini"; title: string; url: string; homepage: string; company: string; api_key_url: string | null; id?: string | undefined; created?: string | undefined; updated?: string | undefined; }[]

type ProviderJsonInput[]

import {providers_default} from '@fuzdev/zzz/config_defaults.js';

ProvidersJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; items: { id: string & $brand<"Uuid">; ... 7 more ...; api_key_url: string | null; }[]; }

import {ProvidersJson} from '@fuzdev/zzz/providers.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`items`

type ProviderJson[]

ProvidersJsonInput
#

providers.svelte.ts view source

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; items?: { name: "claude" | "chatgpt" | "gemini"; title: string; url: string; homepage: string; company: string; api_key_url: string | null; id?: string | undefined; created?: string | undefined; updated?: string | undefined; }[] |...

import type {ProvidersJsonInput} from '@fuzdev/zzz/providers.svelte.js';

ProviderSummary.svelte view source

value + type

{ name: string; available: true; checked_at: number; } | { name: string; available: false; error: string; checked_at: number; }

type { name: string; available: true; checked_at: number; } | { name: string; available: false; error: string; checked_at: number; }

import {ProviderStatus} from '@fuzdev/zzz/provider_types.js';

ProviderSummary
#

import ProviderSummary from '@fuzdev/zzz/ProviderSummary.svelte';

`provider`

type Provider

`attrs?`

type HTMLAttributes<HTMLDivElement>

optional

PUBLIC_ROUTE_PATHS
#

readonly ["/about", "/docs"] import {PUBLIC_ROUTE_PATHS} from '@fuzdev/zzz/auth_gate.js';

Routes that render without a session or a backend.

query_markdown_link_anchors
#

(container: ParentNode, links: readonly MarkdownLink[]): HTMLAnchorElement[] | null import {query_markdown_link_anchors} from '@fuzdev/zzz/markdown_links.js';

The rendered <a> of each of links inside container, matched by document order — the ith anchor with an href is the ith link — or null when the counts disagree, so no link is paired with another's anchor. Order, not href, because the href isn't always the reference: mdz renders a root-relative one through SvelteKit's resolve, collapsing its leading run of / and \ to one / (//a/b.md renders /a/b.md), so an anchor that reads as a path can stand for a reference this module reads as protocol-relative or backslashed, and inert. Assumes mdz renders every anchor in container, which holds while no mdz context injects components that render their own.

`container`

the element mdz rendered the document into

type ParentNode

`links`

the document's links, from to_markdown_links

type readonly MarkdownLink[]

returns

HTMLAnchorElement[] | null

QueuedMessage
#

QueuedMessage import type {QueuedMessage} from '@fuzdev/zzz/socket.svelte.js';

Queued message that couldn't be sent immediately.

`id`

type Uuid

`data`

type any

`created`

type number

QUIET_ACTION_METHODS
#

ReadonlySet<string>

type ReadonlySet<string>

import {QUIET_ACTION_METHODS} from '@fuzdev/zzz/action_helpers.js';

Methods the app calls as flow control rather than on anyone's behalf, many times a second: terminal_ack under a flood of terminal output. Their calls are kept out of the actions log, whose bounded history they would turn over in seconds, and a failed send isn't reported by the dispatcher's log (create_quiet_action_log) — the caller handles its own failures, some of which are expected (an ack racing its terminal's close).

RECONNECT_DELAY_BOUNDS
#

MsSettingBounds import {RECONNECT_DELAY_BOUNDS} from '@fuzdev/zzz/socket_helpers.js';

Allowed reconnect delays, for both the base delay and the backoff cap — the floor keeps a bad value from spinning a reconnect loop.

Recorder
#

import {Recorder} from '@fuzdev/zzz/recorder.svelte.js';

Records the microphone to a file on disk, uploading it as it's recorded.

App-level, so a recording carries on across route changes. capture owns the microphone; this owns where the chunks go and what happens after. The file is created under its final name and grows as chunks arrive (ChunkUpload over the backend's byte routes), so a crashed tab loses at most the last chunk; stopping uploads the rest and finalizes the file (media_finalize) so it has a duration and seeks, then — with transcribe_on_stop — queues its transcription.

Capture starts only in start, and only during a user gesture — nothing the backend sends can open the microphone. active is true the whole time it may be open and until the recording is saved, for the indicator every page shows.

inheritance

extends: Cell<typeof RecorderJson>

`chunk_duration`

type number

$state.raw

`transcribe_on_stop`

type boolean

$state.raw

Whether the microphone may be open or the recording is still being saved.

type boolean

readonly $derived

`constructor`

type new (options: RecorderOptions): Recorder

`options`

type RecorderOptions

`start`

Starts recording to a new file in dir, named for the current local time. Must be called from a user gesture (a click handler).

type (dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">): Promise<void>

`dir`

the directory to create the recording in

returns Promise<void>

throws

Error - when one is already under way (leaving it and `error` untouched), or when there's no backend to record to, no user gesture, the browser can't record, the microphone can't be opened, or the file can't be created — each of those also left in `error`

`pause`

Pauses a recording: the microphone stays open, nothing is recorded.

type (): void

returns void

`resume`

Resumes a paused recording.

type (): void

returns void

`stop`

Stops the recording: closes the microphone, uploads what's left, and finalizes the file. A failure to upload or finalize is left in error — the file is still there, as far as it got.

type (): Promise<(string & $brand<"DiskfilePath">) | null>

returns Promise<DiskfilePath | null>

the recording's path, or null when nothing was being recorded or the upload failed

`dispose`

Ends the recording without finalizing — the session is gone. Chunks the uploader already holds, and the last one the browser hands over as it stops, are still sent.

type (): void

returns void

`duration`

How long the current recording is so far — see AudioCapture.duration.

type number

getter

`level`

How loud the microphone is right now — see AudioCapture.level.

type number

getter

`deps`

type RecorderDeps

gettersetter

RecorderDeps
#

RecorderIndicator.svelte view source

RecorderDeps import type {RecorderDeps} from '@fuzdev/zzz/recorder.svelte.js';

The browser the recorder runs in — the microphone, and fetch for the upload — so a test can stand in for both.

inheritance

extends: AudioCaptureDeps

`fetch`

type (input: string, init?: RequestInit | undefined): Promise<Response>

`input`

type string

`init?`

type RequestInit

optional

returns Promise<Response>

RecorderIndicator
#

import RecorderIndicator from '@fuzdev/zzz/RecorderIndicator.svelte';

`recorder`

type Recorder

RecorderJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; chunk_duration: number; transcribe_on_stop: boolean; }

import {RecorderJson} from '@fuzdev/zzz/recorder.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`chunk_duration`

How often the browser hands over a chunk to upload, in milliseconds — the most audio a crashed tab can lose.

type number

`transcribe_on_stop`

Whether a recording is transcribed, by the local model, once it's saved.

type boolean

RecorderJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; chunk_duration?: number | undefined; transcribe_on_stop?: boolean | undefined; }

import type {RecorderJsonInput} from '@fuzdev/zzz/recorder.svelte.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

`chunk_duration?`

How often the browser hands over a chunk to upload, in milliseconds — the most audio a crashed tab can lose.

type number

`transcribe_on_stop?`

Whether a recording is transcribed, by the local model, once it's saved.

type boolean

RecorderOptions
#

RecorderOptions import type {RecorderOptions} from '@fuzdev/zzz/recorder.svelte.js';

inheritance

extends: CellOptions<typeof RecorderJson>

`deps?`

The browser to record with (default create_recorder_deps()).

type RecorderDeps

RECORDING_FORMATS
#

readonly RecordingFormat[]

type readonly RecordingFormat[]

import {RECORDING_FORMATS} from '@fuzdev/zzz/recording_helpers.js';

The formats a recording is made in, most preferred first: Opus in WebM, Opus in Ogg, then whatever the browser puts in MP4.

RecordingFormat
#

RecordingFormat import type {RecordingFormat} from '@fuzdev/zzz/recording_helpers.js';

A container and codec the browser can record, and the extension its files get.

`mime_type`

The MediaRecorder MIME type.

type string

`extension`

The file extension, without the dot — one the backend can finalize and serve.

type string

RECORDINGS_DIRNAME
#

"recordings" import {RECORDINGS_DIRNAME} from '@fuzdev/zzz/recording_helpers.js';

The directory under the app directory that the recordings page records to.

RemoteNotificationActionMethod
#

value + type

"cancel" | "filer_change" | "transcription_progress" | "job_changed" | "completion_progress" | "terminal_data" | "terminal_exited" | "workspace_changed"

import {RemoteNotificationActionMethod} from '@fuzdev/zzz/action_metatypes.js';

Names of all remote_notification actions.

render_completion_messages
#

(turns: Iterable<Pick<Turn, "content" | "role" | "enabled" | "error_message">>, completion_messages?: { [x: string]: unknown; role: string; content: string; }[]): { ...; }[]

import {render_completion_messages} from '@fuzdev/zzz/thread_helpers.js';

Creates a thread history array for model consumption from a collection of turns.

Every turn contributes its current content, so edits to a completed assistant turn are what later requests see. Skips disabled turns, errored turns (their partial content isn't a valid reply), and turns with empty or whitespace-only content (e.g. a completion cancelled before the first token), because providers like Anthropic reject empty messages. Cancelled turns with partial content are kept. Assistant turns before the first user turn are dropped (e.g. when the first user turn is disabled or removed), since Anthropic and Gemini require the conversation to open with a user message; system turns are kept wherever they are.

`turns`

the thread's turns in order

type Iterable<Pick<Turn, "enabled" | "role" | "content" | "error_message">, any, any>

`completion_messages`

array to append to

type CompletionMessage[]

default []

returns

CompletionMessage[]

completion_messages with the rendered turns appended

mutates

completion_messages — appends one message per included turn

render_message_with_role
#

(role: string, content: string, tag?: string): string import {render_message_with_role} from '@fuzdev/zzz/thread_helpers.js';

Renders a single message with an XML tag that includes the role attribute.

`role`

type string

`content`

type string

`tag`

type string

default 'message'

returns

string

render_message_with_role_length
#

(role: string, content_length: number, tag?: string): number import {render_message_with_role_length} from '@fuzdev/zzz/thread_helpers.js';

The length of render_message_with_role(role, content, tag) for a content of content_length characters, without building the string.

`role`

type string

`content_length`

type number

`tag`

type string

default 'message'

returns

number

render_messages_length
#

(turns: Iterable<{ role: string; length: number; enabled?: boolean | undefined; }>, tag?: string): number import {render_messages_length} from '@fuzdev/zzz/thread_helpers.js';

The length of render_messages_to_string(turns, tag), from each turn's content length rather than its content — so a streaming reply updates the total without re-concatenating the whole thread.

`turns`

type Iterable<{ role: string; length: number; enabled?: boolean | undefined; }, any, any>

`tag`

type string

default 'message'

returns

number

render_messages_to_string
#

(turns: Iterable<{ role: string; content: string; enabled?: boolean | undefined; }>, tag?: string): string import {render_messages_to_string} from '@fuzdev/zzz/thread_helpers.js';

`turns`

type Iterable<{ role: string; content: string; enabled?: boolean | undefined; }, any, any>

`tag`

type string

default 'message'

returns

string

reorder_list
#

(items: any[], from_index: number, to_index: number): void import {reorder_list} from '@fuzdev/zzz/list_helpers.js';

Reorders an array, mutating it by moving an item from one index to another.

`items`

type any[]

`from_index`

type number

`to_index`

type number

returns

void

Reorderable
#

import {Reorderable} from '@fuzdev/zzz/reorderable.svelte.js';

inheritance

implements: ReorderableStyleOptions

`initialized`

type boolean

`source_index`

type number

`source_item_id`

type ReorderableItemId | null

`active_indicator_item_id`

type ReorderableItemId | null

`current_indicator`

type ReorderableDropPosition

type string | null

readonly

`list_node`

type HTMLElement | null

`list_params`

type ReorderableListParams | null

`indices`

type Map<ReorderableItemId, number>

readonly

`elements`

type Map<ReorderableItemId, HTMLElement>

readonly

`pending_items`

type { id: ReorderableItemId; index: number; element: HTMLElement; }[]

`constructor`

type new (options?: ReorderableOptions): Reorderable

`options`

type ReorderableOptions

default EMPTY_OBJECT

`init`

Made public for testing purposes.

type (): void

returns void

`clear_indicators`

type (): void

returns void

`update_indicator`

type (item_id: ReorderableItemId, new_indicator: ReorderableDropPosition, is_valid?: boolean): void

`item_id`

type ReorderableItemId

`new_indicator`

type ReorderableDropPosition

`is_valid`

type boolean

default true

returns void

`list`

type (params: ReorderableListParams) => Attachment<HTMLElement>

`item`

type (params: ReorderableItemParams) => Attachment<HTMLElement>

ReorderableDirection
#

ReorderableDirection

type "horizontal" | "vertical"

import type {ReorderableDirection} from '@fuzdev/zzz/reorderable.svelte.js';

ReorderableDropPosition
#

ReorderableDropPosition

type "none" | "top" | "bottom" | "left" | "right"

import type {ReorderableDropPosition} from '@fuzdev/zzz/reorderable.svelte.js';

ReorderableId
#

ReorderableId

type string & Flavor<"ReorderableId">

import type {ReorderableId} from '@fuzdev/zzz/reorderable.svelte.js';

external types

Flavored<string, 'ReorderableId'>

ReorderableItemId
#

ReorderableItemId

type string & Flavor<"ReorderableItemId">

import type {ReorderableItemId} from '@fuzdev/zzz/reorderable.svelte.js';

external types

Flavored<string, 'ReorderableItemId'>

ReorderableItemParams
#

ReorderableItemParams import type {ReorderableItemParams} from '@fuzdev/zzz/reorderable.svelte.js';

Parameters for item attachment.

`index`

type number

ReorderableListParams
#

ReorderableOptions import type {ReorderableOptions} from '@fuzdev/zzz/reorderable.svelte.js';

Additional configuration options for Reorderable.

`direction?`

Forces a specific direction for the reorderable list. Defaults to auto-detection, 'vertical' as the fallback.

type "top" | "bottom" | "left" | "right"

import type {ReorderableValidDropPosition} from '@fuzdev/zzz/reorderable.svelte.js';

RequestResponseActionMethod
#

value + type

"heartbeat" | "peer/ping" | "ping" | "session_load" | "diskfile_update" | "diskfile_create" | "diskfile_delete" | "directory_create" | "media_finalize" | "transcription_create" | ... 10 more ... | "workspace_list"

import {RequestResponseActionMethod} from '@fuzdev/zzz/action_metatypes.js';

Names of all request_response actions.

resolve_markdown_link
#

(href: string, options?: ResolveMarkdownLinkOptions): MarkdownLinkTarget import {resolve_markdown_link} from '@fuzdev/zzz/markdown_links.js';

Resolves href, a link's reference in a markdown file, to where it leads (see MarkdownLinkTarget). A path link drops its ?query, keeps its #fragment, has each segment percent-decoded, and is normalized: . and empty segments vanish and .. climbs, but never above / — or above root_dir for a root-relative link — which makes it inert. An escape that decodes to / or a NUL is inert too, since it would change the path's shape.

`href`

the link's reference as written (an <a>'s href attribute)

type string

`options`

the file the link is in, and the root a root-relative link resolves against

type ResolveMarkdownLinkOptions

default {}

returns

MarkdownLinkTarget

ResolveMarkdownLinkOptions
#

rpc_message_limit.ts view source

ResolveMarkdownLinkOptions import type {ResolveMarkdownLinkOptions} from '@fuzdev/zzz/markdown_links.js';

`file_path?`

The absolute path of the file the link is in — without it, every path link is inert.

type string | null

`root_dir?`

The directory (with a trailing /) a root-relative link resolves against — see to_root_dir. Without it, root-relative links are inert.

type string | null

RPC_MESSAGE_MAX_BYTES
#

number import {RPC_MESSAGE_MAX_BYTES} from '@fuzdev/zzz/rpc_message_limit.js';

Largest JSON-RPC message the backend accepts, in bytes of its UTF-8 JSON encoding — the /api/rpc request-body cap and the /api/ws message cap (16 MiB on both). Twin of the backend's RPC_MESSAGE_MAX_BYTES in zzz_server; the cross-backend filesystem suite pins the two together. The frontend's FrontendWebsocketTransport takes it as max_message_bytes, so an oversized message is refused before it's sent rather than closing the socket.

SaveShortcutScope
#

save_shortcut.ts view source

SaveShortcutScope

type "focused" | "page"

import type {SaveShortcutScope} from '@fuzdev/zzz/save_shortcut.js';

type new (params?: ScrollableParameters | undefined): Scrollable

`params?`

type ScrollableParameters

optional

`container`

Attachment for the scrollable container - detects scrolling and updates state.

type Attachment<Element>

`target`

Attachment for the element that should receive the scrolled class. Since attachments run in effects, the class updates will be reactive automatically.

type Attachment<Element>

ScrollableParameters
#

scrollable.svelte.ts view source

ScrollableParameters import type {ScrollableParameters} from '@fuzdev/zzz/scrollable.svelte.js';

`target_class?`

CSS class to apply to the target element when scrolled. Defaults to 'scrolled'.

type string

`threshold?`

Threshold in pixels before considering the element scrolled. Defaults to 0.

type number

SerializableDisknode
#

value + type

{ id: string & $brand<"DiskfilePath">; source_dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; contents: string | null; ctime: number | null; mtime: number | null; dependents: [...][]; dependencies: [...][]; }

import {SerializableDisknode} from '@fuzdev/zzz/diskfile_types.js';

`id`

type string & $brand<"DiskfilePath">

`source_dir`

type string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">

`contents`

type string | null

`ctime`

type number | null

`mtime`

type number | null

`dependents`

type [string & $brand<"DiskfilePath">, any][]

`dependencies`

type [string & $brand<"DiskfilePath">, any][]

SERVER_HOST
#

string import {SERVER_HOST} from '@fuzdev/zzz/constants.js';

SERVER_PROTOCOL
#

string import {SERVER_PROTOCOL} from '@fuzdev/zzz/constants.js';

SERVER_URL
#

string import {SERVER_URL} from '@fuzdev/zzz/constants.js';

The server the UI talks to: PUBLIC_ZZZ_SERVER_* when PUBLIC_ZZZ_SERVER_PORT is set (dev: the Vite server, which proxies /api), else the page's origin (the UI served by zzzd). Empty during SSR/prerender when unset, making the API URLs root-relative there.

ServerCapabilityData
#

ServerCapabilityData import type {ServerCapabilityData} from '@fuzdev/zzz/capabilities.svelte.js';

`round_trip_time`

type number

SESSION_BOOT_FALLBACK_DELAY
#

2000 import {SESSION_BOOT_FALLBACK_DELAY} from '@fuzdev/zzz/frontend.svelte.js';

How long Frontend.boot_session waits for the socket to open before loading the session over HTTP instead.

session_load_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: false; input: ZodVoid; output: ZodObject<{ data: ZodObject<{ zzz_dir: $ZodBranded<ZodPipe<ZodPipe<...>, $ZodBranded<...>>, "DiskfileDirectoryPath", "out">; ... 7 more ...; server_instance_i...

import {session_load_action_spec} from '@fuzdev/zzz/action_specs.js';

SESSION_LOAD_RETRY_DELAY
#

1000 import {SESSION_LOAD_RETRY_DELAY} from '@fuzdev/zzz/frontend.svelte.js';

Delay before the first session_load retry, doubling per failure.

SESSION_LOAD_RETRY_DELAY_MAX
#

30000 import {SESSION_LOAD_RETRY_DELAY_MAX} from '@fuzdev/zzz/frontend.svelte.js';

Cap on the session_load retry delay.

SessionLoadData
#

value + type

{ zzz_dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; scoped_dirs: readonly (string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">)[]; ... 6 more ...; server_instance_id: string & $brand<...>; }

import {SessionLoadData} from '@fuzdev/zzz/action_specs.js';

Inner payload of session_load. The fields here are the actual session snapshot — files and the roots they cover, scoped dirs, provider status, workspaces, the caller's terminals, and the server instance. The frontend loads it at boot and again after every reconnect, reconciling its state to it (see Frontend.load_session).

TODO extract to diskfile_types.ts (or a session-specific module) once the Rust backend grows its own typed session response and we can move this schema to the shared boundary.

`zzz_dir`

type string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">

`scoped_dirs`

type readonly (string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">)[]

`files`

type SerializableDisknode[]

`file_roots`

The directories whose complete file trees files holds (the backend's watched roots) — a known file under one of them that's missing from files is gone from disk.

type (string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">)[]

`provider_status`

type ProviderStatus[]

`workspaces`

type WorkspaceInfoJson[]

`terminal_ids`

Backend ids of the caller's live terminals.

type (string & $brand<"Uuid">)[]

`jobs`

The caller's jobs, oldest first — running, queued, and recent finished ones.

type JobSnapshot[]

`server_instance_id`

Minted each time the backend starts — a different id than the last snapshot's means it restarted, losing its terminals and runtime workspaces.

type string & $brand<"Uuid">

SessionLoadOutput
#

value + type

{ data: { zzz_dir: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; scoped_dirs: readonly (string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">)[]; ... 6 more ...; server_instance_id: string & $brand<...>; }; }

import {SessionLoadOutput} from '@fuzdev/zzz/action_specs.js';

Output for session_load. The data wrapper is historical; the Rust backend serializes this exact shape (SessionLoadResult in crates/zzz_server), so flattening it is a coordinated wire change on both sides.

`data`

type SessionLoadData

SessionProbe
#

SessionProbe

type "valid" | "invalid" | "unknown"

import type {SessionProbe} from '@fuzdev/zzz/session_recheck.js';

What the status probe learned: valid (200), invalid (401), or unknown (network failure or any other status — the session may well be fine).

SessionRecheckOptions
#

SessionRecheckOptions import type {SessionRecheckOptions} from '@fuzdev/zzz/session_recheck.js';

`probe?`

Probes the session. Defaults to probe_session.

type (): Promise<SessionProbe>

returns Promise<SessionProbe>

`on_invalid`

Called once the probe finds the session invalid — typically AuthState.check_session.

type (): void | Promise<void>

returns void | Promise<void>

`on_valid?`

Called once the probe finds the session still valid — e.g. to reconnect a socket the server closed as revoked (see Socket.reconnect_revoked).

type (): void | Promise<void>

returns void | Promise<void>

SessionSnapshotChanges
#

SessionSnapshotChanges import type {SessionSnapshotChanges} from '@fuzdev/zzz/frontend.svelte.js';

What changed while a session snapshot was in flight — see Frontend.receive_session.

`file_changes`

What filer_change reported (Diskfiles.track_changes).

type DiskfileSnapshotChanges

`workspace_paths`

Workspace paths opened or closed (Workspaces.track_changes).

type ReadonlySet<string>

`running_terminal_ids`

Backend ids of the terminals running when the snapshot was requested.

type ReadonlySet<Uuid>

set_reorderable_drag_data_transfer
#

Settings.svelte view source

(dataTransfer: DataTransfer, item_id: ReorderableItemId): void import {set_reorderable_drag_data_transfer} from '@fuzdev/zzz/reorderable_helpers.js';

Set up drag data transfer with consistent properties and formats This centralizes the dataTransfer setup logic used in multiple places.

`dataTransfer`

type DataTransfer

`item_id`

type ReorderableItemId

returns

void

Settings
#

import Settings from '@fuzdev/zzz/Settings.svelte';

SingleIndexOptions
#

SingleIndexOptions<T, K> import type {SingleIndexOptions} from '@fuzdev/zzz/indexed_collection_helpers.svelte.js';

Options for single-value indexes.

generics

SingleIndexOptions<T extends IndexedItem, K>

`T`

constraint IndexedItem

`K`

inheritance

extends: KeyedIndexOptions<T>

`extractor`

Function that extracts the key from an item.

type (item: T): K

`item`

type T

returns K

Socket
#

SocketMessageQueue.svelte view source

import {Socket} from '@fuzdev/zzz/socket.svelte.js';

Wraps FrontendWebsocketClient with zzz-specific concerns: a retryable fire-and-forget send queue (distinct from fuz_app's request-level durable queue), URL input tracking, and a mapping from fuz_app's SocketStatus onto zzz's AsyncStatus. Plain reactive class — not a Cell. Implements WebsocketRpcConnection so it can back FrontendWebsocketTransport; the request method is a one-line delegate to the underlying FrontendWebsocketClient, keeping the pending-request map in one canonical place.

fuz_app's FrontendWebsocketClient owns the activity-aware heartbeat, sending the shared heartbeat_action at heartbeat_interval idle, with a receive timeout it scales to the interval (resolve_heartbeat_receive_timeout). Assigning heartbeat_interval pushes the new policy into the live client immediately (the timer is restarted in place when connected).

Reconnect settings (reconnect_delay, reconnect_delay_max, auto_reconnect) propagate to the underlying client on assignment via apply_reconnect_policy() — in-flight waits are monotonically shortened (never extended).

The millisecond settings coerce and clamp on assignment (HEARTBEAT_INTERVAL_BOUNDS, RECONNECT_DELAY_BOUNDS) since form inputs can hand over strings or empty values; a non-numeric write is ignored.

inheritance

implements: WebsocketRpcConnection

`app`

type Frontend

readonly

`url_input`

type string

$state.raw

`message_queue`

type QueuedMessage[]

$state

type boolean

readonly $derived

`revoked`

Whether the server closed the socket with WS_CLOSE_SESSION_REVOKED — terminal for this client. Usually the session is gone, but not always (see reconnect_revoked).

type boolean

readonly $derived

`superseded`

Whether the server closed the socket with WS_CLOSE_CONNECTION_LIMIT, to admit a newer connection on the account. Closed until the next connect() (disconnect() drops the client and the flag with it); anything that reconnects on initial must check this first — status reads initial here, and reconnecting unasked would close a newer socket in turn.

`constructor`

type new (options: SocketOptions): Socket

`options`

type SocketOptions

`connect`

type (url?: string | null): void

`url`

type string | null

default null

returns void

`disconnect`

type (): void

returns void

`reconnect_revoked`

Reconnect after the server closed the socket as revoked — a revoked client never reconnects on its own, so this replaces it with a fresh one. Call only once a session recheck finds the session still valid: some revocations close every socket of the account while ending only another session (another tab's logout, an API-token revoke-all).

type (): boolean

returns boolean

whether a reconnect started (false unless revoked)

`request`

Delegate to the underlying FrontendWebsocketClient.request — keeps the pending-request map, durable queue, and AbortSignal cancel in one canonical place. Rejects when there is no client (call connect() first).

type (method: string, params?: unknown, options?: { signal?: AbortSignal | undefined; queue?: boolean | undefined; id?: string | number | undefined; } | undefined): Promise<unknown>

`method`

type string

`params?`

type unknown

optional

`options?`

type { signal?: AbortSignal | undefined; queue?: boolean | undefined; id?: string | number | undefined; }

optional

returns Promise<unknown>

`send`

Fire-and-forget send, queued for retry when it can't go out now. With auto_reconnect on, queueing connects an idle socket (status initial) — except a superseded one.

type (data: object): boolean

`data`

type object

returns boolean

`update_url`

type (url: string): void

`url`

type string

returns void

`retry_queued_messages`

type (handler: SocketErrorHandler): () => void

`handler`

type SocketErrorHandler

returns () => void

`heartbeat_interval`

Heartbeat idle interval in ms, clamped to HEARTBEAT_INTERVAL_BOUNDS. Writing pushes the new policy into the underlying client immediately — when connected, the live timer is restarted in place; when disconnected, the policy is stashed for the next connect().

type number

gettersetter

`reconnect_delay`

Reconnect policy fields. Assignments push into the underlying client via apply_reconnect_policy() so in-flight waits honor the new policy (monotonically shortened, never extended).

type number

gettersetter

`reconnect_delay_max`

type number

gettersetter

`auto_reconnect`

type boolean

gettersetter

SocketMessageQueue
#

import SocketMessageQueue from '@fuzdev/zzz/SocketMessageQueue.svelte';

`socket`

type Socket

`type`

type "queued" | "failed"

SocketOptions
#

SocketOptions import type {SocketOptions} from '@fuzdev/zzz/socket.svelte.js';

`app`

type Frontend

sort_by_numeric
#

<T extends Cell<any>>(key: string, label: string, field: keyof T, direction?: "asc" | "desc"): Sorter<T> import {sort_by_numeric} from '@fuzdev/zzz/sortable.svelte.js';

Creates a numeric sorter with optional direction. Falls back to cell's cid for equal values.

`key`

type string

`label`

type string

`field`

type keyof T

`direction`

type "asc" | "desc"

default 'asc'

returns

Sorter<T>

generics

sort_by_numeric<T extends Cell<any>>

`T`

constraint Cell<any>

sort_by_text
#

<T extends Cell<any>>(key: string, label: string, field: keyof T, direction?: "asc" | "desc"): Sorter<T> import {sort_by_text} from '@fuzdev/zzz/sortable.svelte.js';

Creates a text sorter with optional direction. Falls back to cell's cid for equal values.

`key`

type string

`label`

type string

`field`

type keyof T

`direction`

type "asc" | "desc"

default 'asc'

returns

Sorter<T>

generics

sort_by_text<T extends Cell<any>>

`T`

constraint Cell<any>

sort_with_hint
#

<T>(items: readonly T[], compare: (a: T, b: T) => number, hint: readonly T[] | null | undefined): T[] import {sort_with_hint} from '@fuzdev/zzz/sortable.svelte.js';

Sorts a copy of items, starting from the order of hint — typically the previous sorted result. The items still present keep their hinted order and new ones are appended, so after a small change the input is nearly sorted, which the engine's sort (TimSort in V8) handles in close to linear time instead of a full n log n re-sort. With a comparator that orders every pair (the cell sorters break ties by cid) the result doesn't depend on hint, only the cost does: a stale or unrelated hint just sorts slower.

`items`

the items to sort, left unmodified

type readonly T[]

`compare`

the sort comparator

type (a: T, b: T) => number

`hint`

an earlier ordering of (some of) the items, or null for none

type readonly T[] | null | undefined

returns

T[]

a new sorted array

generics

sort_with_hint<T>

`T`

Sortable
#

SortableList.svelte view source

import {Sortable} from '@fuzdev/zzz/sortable.svelte.js';

Manages which of a reactive set of sorters is active. Sorting itself is the consumer's (see SortableList and sort_with_hint).

generics

Sortable<T>

`T`

`sorters`

type Sorter<T>[]

readonly $derived.by

`default_key`

type string | undefined

readonly $derived.by

`active_key`

Current active sort key.

type string

$state.raw

`active_sorter`

The currently active sorter.

type Sorter<T> | undefined

readonly $derived

`active_sort_fn`

The sort function from the active sorter.

type ((a: T, b: T) => number) | undefined

readonly $derived

`constructor`

Creates a new Sortable instance with reactive sources.

type new <T>(sorters_getter: Thunk<Sorter<T>[]>, key_getter_default?: Thunk<string | undefined> | undefined): Sortable<T>

`sorters_getter`

function that returns the current sorters

type Thunk<Sorter<T>[]>

`key_getter_default?`

optional function that returns the current default sort key

type Thunk<string | undefined>

optional

`update_active_key`

Updates the active key based on sorters and default key. Called on initialization only — nothing re-runs it when the sorters or the default key change, so call it again after they do.

type (): void

returns void

SortableList
#

accepts children

import SortableList from '@fuzdev/zzz/SortableList.svelte';

`items`

type T[]

`filter?`

type (item: T) => boolean

optional

snippet parameters

item T

`exclude_ids?`

type Uuid[]

optional

`sorters?`

type Sorter<T>[]

optional default EMPTY_ARRAY

`sort_key_default?`

type string

optional

`show_sort_controls?`

type boolean

optional default false

`no_items?`

type Snippet<[]> | string

optional default '[no items available]'

`windowed?`

Render only the rows in or near the visible part of the nearest scrolling ancestor (or the page), with padding standing in for the rest, so a list of thousands stays cheap. Every row must have the same height, which is measured from the rendered rows. Rows scrolled out of range unmount, taking their DOM state (like focus) with them.

The nearest ancestor whose computed overflow-y is auto or scroll (see find_scroll_container) must be the one that scrolls the list, with a constrained height — or have none, so the page scrolls it. An ancestor that only scrolls horizontally, or grows to fit the list, is still picked; the visible area is clipped to the window, so such a list renders the rows on screen, not all of them, but can over-render and waste work.

type boolean

optional default false

`overscan?`

Extra rows rendered above and below the visible ones when windowed.

type number

optional default 10

`list_attrs?`

type HTMLAttributes<HTMLUListElement>

optional

`item_attrs?`

type HTMLLiAttributes

optional

`label_attrs?`

type HTMLLabelAttributes

optional

`children`

Called once per rendered item.

type Snippet<[item: T]>

snippet parameters

item T

generics

SortableList<T extends {id: Uuid}>

`T`

constraint {id: Uuid}

Sorter
#

SourceEditor.svelte view source

Sorter<T> import type {Sorter} from '@fuzdev/zzz/sortable.svelte.js';

generics

Sorter<T>

`T`

`key`

type string

`label`

type string

`fn`

type (a: T, b: T): number

`a`

type T

`b`

type T

returns number

SourceEditor
#

import SourceEditor from '@fuzdev/zzz/SourceEditor.svelte';

`value`

The source text.

type string

bindable

`lang?`

The fuz_code language to highlight as — a language registered on syntax_styler_global, like lang_for_path returns; null disables highlighting.

type string | null

optional default null

`readonly?`

type boolean

optional default false

`placeholder?`

type string | null

optional

`focus_key?`

Focuses the textarea when pending_element_to_focus_key equals it, then clears that.

type string | number | null

optional

`pending_element_to_focus_key?`

type string | number | null

optional bindable

`onsave?`

Called with the value on Ctrl+S / Cmd+S — see save_shortcut.

type (value: string) => void

optional

snippet parameters

value string

`save_shortcut?`

Where Ctrl+S / Cmd+S triggers onsave — see SaveShortcutScope.

type SaveShortcutScope

optional default 'focused'

`attrs?`

Attributes for the <textarea>.

type HTMLTextareaAttributes

optional

`wrapper_attrs?`

Attributes for CodeTextarea's wrapper <div>, the box the textarea fills.

type HTMLAttributes<HTMLDivElement>

optional

Space
#

space.svelte.ts view source

import {Space} from '@fuzdev/zzz/space.svelte.js';

inheritance

extends: Cell<typeof SpaceJson>

`name`

type string

$state.raw

`directory_paths`

type DiskfileDirectoryPath[]

$state

`directory_count`

type number

readonly $derived

`active_directory_paths`

Directory paths filtered to only include those backed by an open workspace. Stale entries (from closed workspaces) are excluded.

type DiskfileDirectoryPath[]

readonly $derived

`constructor`

type new (options: SpaceOptions): Space

`options`

type SpaceOptions

`add_directory`

type (path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">): void

`path`

returns void

`remove_directory`

type (path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">): void

`path`

space.svelte.ts view source

returns void

SpaceJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; name: string; directory_paths: (string & $brand<"DiskfilePath"> & $brand<...>)[]; }

import {SpaceJson} from '@fuzdev/zzz/space.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

`name?`

type string

`directory_paths?`

type string[]

SpaceOptions
#

space.svelte.ts view source

SpaceOptions import type {SpaceOptions} from '@fuzdev/zzz/space.svelte.js';

inheritance

extends: CellOptions<typeof SpaceJson>

Spaces
#

spaces.svelte.ts view source

import {Spaces} from '@fuzdev/zzz/spaces.svelte.js';

inheritance

extends: Cell<typeof SpacesJson>

`items`

type IndexedCollection<Space>

readonly

`active_id`

type Uuid | null

$state.raw

`active`

type Space | undefined

readonly $derived

`scratchpad_id`

type Uuid | null

$state.raw

`scratchpad`

The default space, identified by id so renaming it doesn't change which space it is.

type Space | undefined

readonly $derived

`constructor`

type new (options: SpacesOptions): Spaces

`options`

type SpacesOptions

`set_json`

Applies value, then ensures the scratchpad — including on construction, so replacing the spaces can never leave none.

type (value?: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; items?: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; directory_paths?: string[] | undefined; }[] | undefined; active_id?: string | ... 1 more ... | undefined; scratchpad_id?: string | ... 1 more ... | undefined; } | undefined): void

`value?`

type SpacesJsonInput

optional

returns void

`ensure_scratchpad`

Returns the scratchpad, adopting a space named SCRATCHPAD_NAME (e.g. from JSON without a scratchpad_id) or creating and activating one if needed.

type (): Space

returns Space

`add`

type (json?: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; directory_paths?: string[] | undefined; } | undefined): Space

`json?`

type SpaceJsonInput

optional

returns Space

`generate_unique_name`

type (base_name?: string): string

`base_name`

type string

default 'new space'

returns string

`remove`

Removes and disposes a space. The scratchpad can't be removed.

type (id: string & $brand<"Uuid">): void

`id`

type Uuid

returns void

`activate`

type (id: string & $brand<"Uuid">): void

`id`

type Uuid

returns void

SpacesJson
#

spaces.svelte.ts view source

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; items: { id: string & $brand<"Uuid">; created: string & $brand<...>; updated: string & $brand<...>; name: string; directory_paths: (string & ... 1 more ... & $brand<...>)[]; }[]; active_id: (string & $brand<......

import {SpacesJson} from '@fuzdev/zzz/spaces.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

`items?`

type SpaceJsonInput[]

`active_id?`

type string | null

`scratchpad_id?`

type string | null

SpacesOptions
#

spaces.svelte.ts view source

SpacesOptions import type {SpacesOptions} from '@fuzdev/zzz/spaces.svelte.js';

inheritance

extends: CellOptions<typeof SpacesJson>

SUPPORTED_CODE_FILETYPE_MATCHER
#

terminal.svelte.ts view source

RegExp import {SUPPORTED_CODE_FILETYPE_MATCHER} from '@fuzdev/zzz/diskfile_helpers.js';

Terminal
#

import {Terminal} from '@fuzdev/zzz/terminal.svelte.js';

A PTY terminal run: the command it runs, its backend process status, a bounded output buffer that outlives any mounted view, and ordered input.

Output is acked to the backend (terminal_ack) as it's consumed, which is what paces a process that prints faster than this client takes it: with views attached, once every view has consumed a chunk; with none, as soon as it's buffered (the buffer drops its oldest output, so it never backs up).

Input goes through a per-terminal queue with at most one terminal_data_send in flight — the backend dispatches one socket's requests concurrently, so independent sends could reorder keystrokes. Data queued while a send is in flight is coalesced into the next send. Resizes coalesce to the latest size.

type string

readonly $derived

`running`

type boolean

readonly $derived

`output`

Output kept for replay into views mounted after it arrived.

type TerminalOutputBuffer

readonly

`constructor`

type new (options: TerminalOptions): Terminal

`options`

type TerminalOptions

`attach_output`

Forwards new output to listener until detached, and returns the output buffered so far for the caller to replay first. Replay is left to the caller so it can tell replayed output from live output — a replay can contain terminal queries (cursor position, device attributes) that xterm would answer again, and those answers must not reach the process.

type (listener: TerminalOutputListener): TerminalOutputAttachment

`listener`

type TerminalOutputListener

returns TerminalOutputAttachment

`receive_output`

Buffers output from the backend and forwards it to attached views.

type (data: string, sent_bytes: number): void

`data`

the output

type string

`sent_bytes`

the chunk's terminal_data sent_bytes, acked once the output is consumed

type number

returns void

`start`

Marks the process started as the backend PTY terminal_id, flushing any input or resize queued while starting.

type (terminal_id: string & $brand<"Uuid">, exited?: { exit_code: number | null; } | null): void

`terminal_id`

the backend PTY's id

type Uuid

`exited`

an exit that arrived before the terminal_create reply — recorded instead of starting, discarding the queued input

type { exit_code: number | null; } | null

why, shown as the terminal's error_message

type string

returns void

`mark_output_gap`

Flags possibly missing output after a reconnect (see output_gap). Ignored unless running.

type (): void

returns void

`reset`

Resets to starting for a fresh spawn — clears the backend id, exit state, errors, queued I/O, and buffered output.

type (): void

returns void

`send_input`

Queues data as input, sent in order with at most one terminal_data_send in flight. Input queued while starting is sent once the process starts.

On queue_overflow (the child isn't reading its input) the data is retried with backoff — the backend enqueued none of it, so a resend can't duplicate — and the error is surfaced until a send succeeds. On not_found the backend no longer has the process, so the terminal is marked lost. Any other failure is surfaced without a retry, because the data may have been delivered.

type (data: string): void

`data`

type string

returns void

`resize`

Requests a PTY resize, coalesced to the latest size while one is in flight. On not_found the terminal is marked lost, like send_input.

type (cols: number, rows: number): void

`cols`

type number

`rows`

type number

returns void

`close`

Closes the running process with terminal_close. The backend broadcasts no terminal_exited for a closed terminal, so the response settles the status — unless a natural exit was recorded first. A not_found means the process is already gone (it just ended, or zzzd restarted), which is what closing wanted, so it closes with an unknown exit code and no error.

type (): Promise<void>

returns Promise<void>

`dispose`

type (): void

returns void

terminal_ack_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ terminal_id: $ZodBranded<ZodUUID, "Uuid", "out">; bytes: ZodNumber; }, $strict>; output: ZodNull; async: true; description: string; }

import {terminal_ack_action_spec} from '@fuzdev/zzz/action_specs.js';

TERMINAL_ACK_DELAY
#

100 import {TERMINAL_ACK_DELAY} from '@fuzdev/zzz/terminal_helpers.js';

How long (ms) consumed output under the threshold waits to be acked.

TERMINAL_ACK_RETRY_DELAY
#

1000 import {TERMINAL_ACK_RETRY_DELAY} from '@fuzdev/zzz/terminal_helpers.js';

How long (ms) before a failed ack is sent again.

TERMINAL_ACK_THRESHOLD_BYTES
#

number import {TERMINAL_ACK_THRESHOLD_BYTES} from '@fuzdev/zzz/terminal_helpers.js';

Consumed output a terminal acks at once rather than after TERMINAL_ACK_DELAY — see TerminalOutputAcker.

It must not exceed the backend's low-water mark (256 KiB, the unacked output at or under which a paused terminal reads again). While the backend holds a terminal paused, more than that mark is unacked; so a client that has consumed everything it was sent has at least this much waiting, and acks at once instead of leaving the process blocked for the delay. The cross-backend terminal suite pins the relation against the backend.

terminal_close_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ terminal_id: $ZodBranded<ZodUUID, "Uuid", "out">; signal: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; description: string; }

import {terminal_close_action_spec} from '@fuzdev/zzz/action_specs.js';

terminal_create_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ command: ZodString; args: ZodDefault<ZodArray<ZodString>>; cwd: ZodOptional<...>; preset_id: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; des...

import {terminal_create_action_spec} from '@fuzdev/zzz/action_specs.js';

terminal_data_action_spec
#

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ terminal_id: $ZodBranded<ZodUUID, "Uuid", "out">; data: ZodString; sent_bytes: ZodNumber; }, $strict>; output: ZodVoid; async: true; description: string; }

import {terminal_data_action_spec} from '@fuzdev/zzz/action_specs.js';

terminal_data_send_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ terminal_id: $ZodBranded<ZodUUID, "Uuid", "out">; data: ZodString; }, $strict>; output: ZodNull; async: true; description: string; }

import {terminal_data_send_action_spec} from '@fuzdev/zzz/action_specs.js';

terminal_exited_action_spec
#

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ terminal_id: $ZodBranded<ZodUUID, "Uuid", "out">; exit_code: ZodNullable<...>; }, $strict>; output: ZodVoid; async: true; description: string; }

import {terminal_exited_action_spec} from '@fuzdev/zzz/action_specs.js';

TERMINAL_INPUT_PENDING_MAX_LENGTH
#

number import {TERMINAL_INPUT_PENDING_MAX_LENGTH} from '@fuzdev/zzz/terminal_helpers.js';

Max characters of input queued per terminal while a send is in flight or waiting to retry. Input past this is refused and surfaced, not queued.

TERMINAL_LOST_TO_RESTART_MESSAGE
#

"lost: zzzd restarted, ending this terminal" import {TERMINAL_LOST_TO_RESTART_MESSAGE} from '@fuzdev/zzz/terminal_helpers.js';

Why a terminal is lost when a session snapshot from a restarted backend lacks it.

TERMINAL_LOST_WHILE_DISCONNECTED_MESSAGE
#

"lost: the terminal ended while the connection was down" import {TERMINAL_LOST_WHILE_DISCONNECTED_MESSAGE} from '@fuzdev/zzz/terminal_helpers.js';

Why a terminal is lost when a session snapshot from the same backend lacks it — it exited, or was closed from another tab, while the connection was down.

TERMINAL_NOT_FOUND_MESSAGE
#

"lost: the backend no longer has this terminal — zzzd may have restarted" import {TERMINAL_NOT_FOUND_MESSAGE} from '@fuzdev/zzz/terminal_helpers.js';

Why a terminal is lost when the backend answers not_found for it.

TERMINAL_OUTPUT_MAX_LENGTH
#

1000000 import {TERMINAL_OUTPUT_MAX_LENGTH} from '@fuzdev/zzz/terminal_helpers.js';

Max characters of output kept per terminal for replay into a (re)mounted view. Counted in UTF-16 code units — about 1-2 MB of memory. The oldest output is dropped first.

TERMINAL_PRESETS_DEFAULT
#

readonly { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; command?: string | undefined; args?: string[] | undefined; cwd?: string | undefined; }[]

type readonly TerminalPresetJsonInput[]

import {TERMINAL_PRESETS_DEFAULT} from '@fuzdev/zzz/terminal_presets.svelte.js';

The presets a TerminalPresets starts with when constructed without items.

terminal_resize_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ terminal_id: $ZodBranded<ZodUUID, "Uuid", "out">; cols: ZodNumber; rows: ZodNumber; }, $strict>; output: ZodNull; async: true; description: string; }

import {terminal_resize_action_spec} from '@fuzdev/zzz/action_specs.js';

TerminalAckInput
#

value + type

{ terminal_id: string & $brand<"Uuid">; bytes: number; } import {TerminalAckInput} from '@fuzdev/zzz/action_specs.js';

Input for terminal_ack.

`terminal_id`

type string & $brand<"Uuid">

`bytes`

The sent_bytes of the last terminal_data the client finished with. Cumulative: the backend keeps the highest it has seen from a connection.

type number

TerminalAckOutcome
#

TerminalAckOutcome

type "ok" | "retry" | "stop"

import type {TerminalAckOutcome} from '@fuzdev/zzz/terminal_helpers.js';

How a terminal_ack ended: ok, retry (it failed and is worth sending again), or stop (the backend no longer has the terminal).

TerminalCloseInput
#

value + type

{ terminal_id: string & $brand<"Uuid">; signal?: "SIGTERM" | "SIGKILL" | undefined; } import {TerminalCloseInput} from '@fuzdev/zzz/action_specs.js';

Input for terminal_close.

`terminal_id`

type string & $brand<"Uuid">

`signal?`

type "SIGTERM" | "SIGKILL"

TerminalCloseOutput
#

value + type

{ exit_code: number | null; } import {TerminalCloseOutput} from '@fuzdev/zzz/action_specs.js';

Output for terminal_close.

`exit_code`

type number | null

TerminalCloseSignal
#

TerminalCommandInput.svelte view source

value + type

"SIGTERM" | "SIGKILL"

type "SIGTERM" | "SIGKILL"

import {TerminalCloseSignal} from '@fuzdev/zzz/action_specs.js';

A signal terminal_close can send.

TerminalCommandInput
#

import TerminalCommandInput from '@fuzdev/zzz/TerminalCommandInput.svelte';

`onsend`

type (command_text: string) => void

snippet parameters

command_text string

TerminalContextmenu
#

TerminalContextmenu.svelte view source

accepts children

import TerminalContextmenu from '@fuzdev/zzz/TerminalContextmenu.svelte';

`get_terminal_text`

type (Thunk<string>) | null

`display_command`

type string

`children`

type Snippet<[]>

TerminalCreateInput
#

value + type

{ command: string; args: string[]; cwd?: string | undefined; preset_id?: (string & $brand<"Uuid">) | undefined; } import {TerminalCreateInput} from '@fuzdev/zzz/action_specs.js';

Input for terminal_create.

`command`

type string

`args`

type string[]

`cwd?`

The working directory — absolute, never resolved against the daemon's own.

type string

`preset_id?`

type string & $brand<"Uuid">

TerminalCreateOutput
#

value + type

{ terminal_id: string & $brand<"Uuid">; } import {TerminalCreateOutput} from '@fuzdev/zzz/action_specs.js';

Output for terminal_create.

`terminal_id`

type string & $brand<"Uuid">

TerminalDataInput
#

value + type

{ terminal_id: string & $brand<"Uuid">; data: string; sent_bytes: number; } import {TerminalDataInput} from '@fuzdev/zzz/action_specs.js';

Input for terminal_data (backend → frontend stdout/stderr stream).

`terminal_id`

type string & $brand<"Uuid">

`data`

type string

`sent_bytes`

Bytes of output (data as UTF-8) the terminal has sent in total, this chunk included — the backend's count, echoed back by terminal_ack.

type number

TerminalDataSendInput
#

value + type

{ terminal_id: string & $brand<"Uuid">; data: string; } import {TerminalDataSendInput} from '@fuzdev/zzz/action_specs.js';

Input for terminal_data_send.

`terminal_id`

type string & $brand<"Uuid">

`data`

type string

TerminalDimension
#

value + type

number import {TerminalDimension} from '@fuzdev/zzz/action_specs.js';

A terminal dimension (cols / rows) — the u16 range of a PTY winsize, minus zero.

TerminalExitedInput
#

terminal.svelte.ts view source

value + type

{ terminal_id: string & $brand<"Uuid">; exit_code: number | null; } import {TerminalExitedInput} from '@fuzdev/zzz/action_specs.js';

Input for terminal_exited.

`terminal_id`

type string & $brand<"Uuid">

`exit_code`

type number | null

TerminalJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; name: string; command: string; args: string[]; terminal_id: (string & $brand<...>) | null; ... 4 more ...; cwd?: string | undefined; }

import {TerminalJson} from '@fuzdev/zzz/terminal.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`name`

type string

`command`

type string

`args`

type string[]

`terminal_id`

The backend PTY's id — changes on restart, null until terminal_create resolves.

type (string & $brand<"Uuid">) | null

`status`

`exit_code`

type number | null

`error_message`

The last failure to spawn, close, or send to the terminal.

`name?`

type string

`command?`

type string

`args?`

type string[]

`cwd?`

type string

`terminal_id?`

The backend PTY's id — changes on restart, null until terminal_create resolves.

import {TerminalOutputAcker} from '@fuzdev/zzz/terminal_helpers.js';

Batches one terminal's output acks. The backend stops reading a terminal whose output runs too far ahead of what this client has acked, so acks must keep up with consumption without doubling the message rate.

Counts are the backend's: each terminal_data carries sent_bytes, the terminal's running output total, and an ack echoes the sent_bytes of the last chunk consumed. Acks are cumulative, so a lost one is covered by the next.

An ack is sent at once when threshold_bytes of consumed output are waiting, and after delay when fewer are — so the last of a burst is always acked. At most one ack is in flight: output consumed meanwhile waits for it to return and is then acked by the same rule, so under a flood acks go out per threshold_bytes consumed, not per round trip (each ack is a request the backend runs in a transaction).

Acks can't stall a terminal the backend has paused, as long as threshold_bytes is at most the backend's low-water mark (see TERMINAL_ACK_THRESHOLD_BYTES): once everything sent is consumed, at least the threshold is waiting, and the ack goes out at once or as soon as the one in flight returns. delay bounds every other case. Not reactive.

`constructor`

type new (options: TerminalOutputAckerOptions): TerminalOutputAcker

`options`

type TerminalOutputAckerOptions

`consumed`

Records that output through sent_bytes has been consumed. Counts only move forward — a lower value is ignored.

type (sent_bytes: number): void

`sent_bytes`

type number

returns void

`flush`

Acks what's been consumed now, unless an ack is in flight (what it leaves is acked when it returns) or nothing is waiting.

type (): void

returns void

`stop`

Stops acking for good — pending and later output is never acked.

type (): void

returns void

`acked`

The highest sent_bytes an ack has succeeded for.

type number

getter

TerminalOutputAckerOptions
#

TerminalOutputAckerOptions import type {TerminalOutputAckerOptions} from '@fuzdev/zzz/terminal_helpers.js';

`send`

Sends a terminal_ack for output consumed through bytes. Must not throw.

type (bytes: number): Promise<TerminalAckOutcome>

`bytes`

type number

Output buffered before attaching, to replay before any streamed output.

type string

`truncated`

Whether older output was dropped from buffered to stay under the cap.

type boolean

`detach`

type (): void

returns void

TerminalOutputBuffer
#

terminal_preset.svelte.ts view source

import {TerminalOutputBuffer} from '@fuzdev/zzz/terminal_helpers.js';

Bounded buffer of terminal output chunks — keeps about the most recent max_length characters, dropping the oldest first. Not reactive.

Trimming cuts after a newline where the oldest chunk has one past the trim point, and otherwise drops that whole chunk, so a replay starts at a line or chunk boundary rather than at an arbitrary character. Backend chunk boundaries are arbitrary too, so a replay can still start inside an escape sequence — xterm's parser starts in its ground state and prints the tail of the sequence as text.

`max_length`

type number

readonly

`constructor`

type new (max_length?: number): TerminalOutputBuffer

`max_length`

type number

default TERMINAL_OUTPUT_MAX_LENGTH

`push`

Appends data, then drops the oldest output past max_length.

type (data: string): void

`data`

type string

returns void

`mark_dropped`

Records that output was dropped before reaching this buffer, e.g. from a buffer whose content was handed over.

type (): void

returns void

`clear`

returns void

TerminalPreset
#

import {TerminalPreset} from '@fuzdev/zzz/terminal_preset.svelte.js';

inheritance

extends: Cell<typeof TerminalPresetJson>

`name`

type string

$state.raw

`command`

type string

$state.raw

`args`

type string[]

$state.raw

`cwd`

type string | undefined

$state.raw

`constructor`

type new (options: TerminalPresetOptions): TerminalPreset

`options`

type TerminalPresetOptions

TerminalPresetBar
#

TerminalPresetBar.svelte view source

import TerminalPresetBar from '@fuzdev/zzz/TerminalPresetBar.svelte';

`presets`

type readonly TerminalPreset[]

`onrun`

type (preset: TerminalPreset) => void

snippet parameters

preset TerminalPreset

`oncreate?`

type (name: string, command: string, args: string[]) => void

optional

snippet parameters

name string

command string

args string[]

`ondelete?`

type (preset: TerminalPreset) => void

optional

snippet parameters

preset TerminalPreset

TerminalPresetJson
#

terminal_preset.svelte.ts view source

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; name: string; command: string; args: string[]; cwd?: string | undefined; }

import {TerminalPresetJson} from '@fuzdev/zzz/terminal_preset.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

`name?`

type string

`command?`

type string

`args?`

type string[]

`cwd?`

type string

TerminalPresetOptions
#

terminal_preset.svelte.ts view source

TerminalPresetOptions import type {TerminalPresetOptions} from '@fuzdev/zzz/terminal_preset.svelte.js';

inheritance

extends: CellOptions<typeof TerminalPresetJson>

TerminalPresets
#

import {TerminalPresets} from '@fuzdev/zzz/terminal_presets.svelte.js';

App-level collection of saved terminal commands. Seeded once with TERMINAL_PRESETS_DEFAULT unless constructed with items.

TODO persist user-created presets — they last only as long as the page

inheritance

extends: Cell<typeof TerminalPresetsJson>

`items`

type IndexedCollection<TerminalPreset>

readonly

`constructor`

type new (options: TerminalPresetsOptions): TerminalPresets

`options`

type TerminalPresetsOptions

`add`

type (json?: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; command?: string | undefined; args?: string[] | undefined; cwd?: string | undefined; } | undefined): TerminalPreset

`json?`

type TerminalPresetJsonInput

optional

returns TerminalPreset

`remove`

Removes and disposes a preset.

type (id: string & $brand<"Uuid">): boolean

`id`

type Uuid

returns boolean

whether the preset was found

`clear`

Removes and disposes every preset.

type (): void

returns void

`dispose`

type (): void

returns void

TerminalPresetsJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; items: { id: string & $brand<"Uuid">; ... 5 more ...; cwd?: string | undefined; }[]; }

import {TerminalPresetsJson} from '@fuzdev/zzz/terminal_presets.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`items`

type TerminalPresetJson[]

TerminalPresetsJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; items?: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; command?: string | undefined; args?: string[] | undefined; cwd?: string | undefined; }[] | undefined; }

import type {TerminalPresetsJsonInput} from '@fuzdev/zzz/terminal_presets.svelte.js';

TerminalRunItem.svelte view source

value + type

{ terminal_id: string & $brand<"Uuid">; cols: number; rows: number; } import {TerminalResizeInput} from '@fuzdev/zzz/action_specs.js';

Input for terminal_resize.

`terminal_id`

type string & $brand<"Uuid">

`cols`

type number

`rows`

type number

TerminalRunItem
#

import TerminalRunItem from '@fuzdev/zzz/TerminalRunItem.svelte';

`terminal`

type Terminal

`onrestart?`

type () => void

optional

`onremove?`

type () => void

optional

TerminalRunner
#

TerminalRunner.svelte view source

import TerminalRunner from '@fuzdev/zzz/TerminalRunner.svelte';

Terminals
#

terminals.svelte.ts view source

import {Terminals} from '@fuzdev/zzz/terminals.svelte.js';

App-level collection of terminal runs — outlives the views that render them, so navigating away and back reattaches to live terminals and their output.

Every terminal spawns a shell (sh) and types its command line into it, so the session stays alive for follow-up input.

After a reconnect, reconcile marks the terminals the backend no longer has as lost (from the session_load snapshot's terminal_ids).

TODO the list is in-memory, so a page reload loses it while the backend PTYs keep running — session_load lists their ids, but reattaching would also need their commands and output.

inheritance

extends: Cell<typeof TerminalsJson>

`items`

type IndexedCollection<Terminal>

readonly

`constructor`

type new (options: TerminalsOptions): Terminals

`options`

type TerminalsOptions

`get_by_terminal_id`

Looks up a terminal by its backend terminal_id.

type (terminal_id: string & $brand<"Uuid">): Terminal | undefined

`terminal_id`

type Uuid

returns Terminal | undefined

`add`

Adds a terminal cell without spawning a process. See create to spawn one.

`json?`

type TerminalJsonInput

optional

returns Terminal

`create`

Adds a terminal and spawns its process. A spawn failure is recorded on the terminal (status: 'failed' + error_message), so this doesn't reject.

type (json: Pick<{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; command?: string | undefined; args?: string[] | undefined; cwd?: string | undefined; ... 4 more ...; preset_id?: string | ... 1 more ... | undefined; }, "name" | ... 3 more ... | "preset_id">): Promise<...>

`json`

type Pick<TerminalJsonInput, "name" | "command" | "args" | "cwd" | "preset_id">

returns Promise<Terminal>

`restart`

Closes the terminal's process if it's running, then spawns a fresh one with a new terminal_id and cleared output. Does nothing if the close fails — the error is on the terminal — to avoid orphaning a live process.

type (terminal: Terminal): Promise<void>

`terminal`

type Terminal

returns Promise<void>

`remove`

Closes the terminal's process if it's running, then removes and disposes the terminal. Keeps it if the close fails, so the process stays reachable. A terminal removed while starting has its process closed once spawned.

type (terminal: Terminal): Promise<void>

`terminal`

type Terminal

returns Promise<void>

`clear`

Removes and disposes every terminal without closing their processes.

type (): void

returns void

`receive_output`

Routes a terminal_data notification to its terminal, buffering it whether or not a view is mounted.

type (terminal_id: string & $brand<"Uuid">, data: string, sent_bytes: number): void

`terminal_id`

type Uuid

`data`

type string

`sent_bytes`

type number

returns void

`receive_exited`

Routes a terminal_exited notification to its terminal, recording the exit whether or not a view is mounted.

type (terminal_id: string & $brand<"Uuid">, exit_code: number | null): void

`terminal_id`

type Uuid

`exit_code`

type number | null

returns void

`running_terminal_ids`

The backend ids of the running terminals.

type (): Set<string & $brand<"Uuid">>

returns Set<Uuid>

`mark_output_gap`

Marks every running terminal as possibly missing output (see Terminal.output_gap) — called when the socket reconnects.

type (): void

returns void

`reconcile`

Reconciles with the backend's live terminals from a session snapshot: a running terminal it doesn't list is marked lost, since its terminal_exited (if any) was missed.

type (live_terminal_ids: ReadonlySet<string & $brand<"Uuid">>, known_terminal_ids: ReadonlySet<string & $brand<"Uuid">>, reason: string): void

`live_terminal_ids`

the snapshot's terminal_ids

type ReadonlySet<Uuid>

`known_terminal_ids`

the ids running when the snapshot was requested; only these are judged, since a terminal started after the request may postdate the snapshot

type ReadonlySet<Uuid>

`reason`

the lost terminals' error_message

type string

returns void

`dispose`

type (): void

returns void

TerminalsJson
#

terminals.svelte.ts view source

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; items: { id: string & $brand<"Uuid">; ... 10 more ...; cwd?: string | undefined; }[]; }

import {TerminalsJson} from '@fuzdev/zzz/terminals.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`items`

type TerminalJson[]

TerminalsJsonInput
#

terminals.svelte.ts view source

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; items?: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; ... 7 more ...; preset_id?: string | ... 1 more ... | undefined; }[] | undefined; }

import type {TerminalsJsonInput} from '@fuzdev/zzz/terminals.svelte.js';

terminal.svelte.ts view source

value + type

import {TerminalStatus} from '@fuzdev/zzz/terminal.svelte.js';

Lifecycle of a terminal's backend process:

starting — terminal_create is in flight
running — the PTY process is live
exited — the process exited on its own (terminal_exited), exit_code is its real code
closed — the user closed it (terminal_close), exit_code is the code the close observed, or null if the process outlived the close grace (the backend reaps it and broadcasts no terminal_exited)
failed — terminal_create failed, see error_message
lost — the backend no longer has the process: zzzd restarted, or it ended or was closed elsewhere while this client wasn't listening; see error_message

TerminalView
#

TerminalView.svelte view source

import TerminalView from '@fuzdev/zzz/TerminalView.svelte';

`terminal`

type Terminal

`get_text?`

type (fn: () => string) => void

optional

snippet parameters

fn () => string

testing_action_specs
#

testing_action_specs.ts view source

({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; ...

type ActionSpecUnion[]

import {testing_action_specs} from '@fuzdev/zzz/testing_action_specs.js';

type number

TextPart
#

import {TextPart} from '@fuzdev/zzz/part.svelte.js';

Text part - stores content directly.

inheritance

extends: Part<typeof TextPartJson>

`type`

type "text"

readonly

`content`

type string

$state.raw

`constructor`

type new (options: TextPartOptions): TextPart

`options`

type TextPartOptions

TextPartJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; name: string; start: number | null; end: number | null; ... 7 more ...; content: string; }

import {TextPartJson} from '@fuzdev/zzz/part.svelte.js';

Text part schema - direct content storage.

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

TextPartJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; start?: number | null | undefined; end?: number | null | undefined; has_xml_tag?: boolean | undefined; ... 6 more ...; content?: string | undefined; }

import type {TextPartJsonInput} from '@fuzdev/zzz/part.svelte.js';

`id?`

type string

`created?`

type string

`updated?`

TextPartOptions
#

TextPartOptions

type PartOptions<ZodObject<{ id: ZodDefault<$ZodBranded<ZodUUID, "Uuid", "out">>; created: ZodDefault<$ZodBranded<ZodISODateTime, "Datetime", "out">>; updated: ZodDefault<$ZodBranded<ZodISODateTime, "Datetime", "out">>; name: ZodDefault<ZodString>; start: ZodDefault<ZodNullable<ZodNumber>>; end: ZodDefault<ZodNullable<ZodNumber>>; has_xml_tag: ZodDefault<ZodBoolean>; xml_tag_name: ZodDefault<ZodString>; attributes: ZodDefault<ZodArray<ZodObject<{ id: ZodDefault<$ZodBranded<ZodUUID, "Uuid", "out">>; key: ZodDefault<ZodString>; value: ZodDefault<ZodString>; }, $strict>>>; enabled: ZodDefault<ZodBoolean>; title: ZodDefault<ZodNullable<ZodString>>; summary: ZodDefault<ZodNullable<ZodString>>; type: ZodDefault<ZodLiteral<"text">>; content: ZodDefault<ZodString>; }, $strict>>

import type {TextPartOptions} from '@fuzdev/zzz/part.svelte.js';

`json?`

type TextPartJsonInput

`app`

type Frontend

TextPartSchema
#

thread.svelte.ts view source

ZodCustom<TextPart, TextPart>

type ZodCustom<TextPart, TextPart>

import {TextPartSchema} from '@fuzdev/zzz/part.svelte.js';

Thread
#

import {Thread} from '@fuzdev/zzz/thread.svelte.js';

A thread is a linear sequence of turns that maintains a chronological record of interactions between the user and the AI.

inheritance

extends: Cell<typeof ThreadJson>

`model_name`

type string

$state.raw

`model`

type Model | undefined

readonly $derived.by

`turns`

type IndexedCollection<Turn>

readonly

`enabled`

type boolean

$state.raw

`main_input`

type string

$state.raw

`main_input_length`

type number

readonly $derived

type number

readonly $derived

`content_preview`

type string

readonly $derived

`pending`

Reactive flag: true while send_message has an in-flight completion_create. Owned by the thread so multiple views of the same thread stay in sync. Callers that bypass send_message and call app.api.completion_create directly will not update this flag.

type boolean

$state.raw

`can_send`

Whether send_message would send now: no send in flight, the model is known, and its provider isn't reported unavailable (an unchecked provider counts as available, as in send_message).

type boolean

readonly $derived.by

`constructor`

type new (options: ThreadOptions): Thread

`options`

type ThreadOptions

`add_turn`

Add a turn to this thread.

type (turn: Turn): void

`turn`

type Turn

returns void

`add_user_turn`

Create and add a user turn with the given content.

type (content: string, request?: { created: string & $brand<"Datetime">; provider_name: "claude" | "chatgpt" | "gemini"; model: string; prompt: string; completion_messages?: { [x: string]: unknown; role: string; content: string; }[] | undefined; } | undefined): Turn

`content`

type string

`request?`

type CompletionRequest

optional

returns Turn

`add_assistant_turn`

Create and add an assistant turn with the given content.

type (content: string, json?: Partial<{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; part_ids: (string & $brand<...>)[]; ... 5 more ...; error_message?: string | undefined; }> | undefined): Turn

`content`

type string

`json?`

type Partial<TurnJson>

optional

returns Turn

`remove_all_turns`

Remove and dispose all turns from this thread, cancelling any in-flight completion first since its turn is going away, and remove the turns' parts from app.parts unless another turn references them.

type (): void

returns void

`dispose`

Cancels any in-flight completion and disposes the thread's turns. Their parts are left to whoever removes the thread (see Threads.remove), since disposal also happens when a decoder replaces the collection.

type (): void

returns void

`send_message`

Send a message to the AI and create corresponding turns. Returns null if a send is already in flight, or if the model or provider is unavailable (defensive checks - UI should prevent these).

type (content: string): Promise<Turn | null>

`content`

type string

returns Promise<Turn | null>

`cancel_pending`

Abort the in-flight completion_create call (if any). Safe to call when nothing is pending — no-op. The frontend WS client rejects the pending promise with request_cancelled and fires a cancel notification so the server can stop its provider stream.

The in-flight assistant turn is marked cancelled (unless it already settled) so it stops showing as pending even if no content streamed in, and any late streaming chunks are ignored.

type (): void

returns void

`cancel_pending_turn`

Cancels the in-flight completion if it's the one streaming into turn (see cancel_pending).

type (turn: Turn): boolean

`turn`

type Turn

returns boolean

whether turn was the pending turn

`switch_model`

type (model_id: string & $brand<"Uuid">): void

`model_id`

type Uuid

returns void

`part_ids`

The ids of the parts of every turn.

type Uuid[]

getter

ThreadContextmenu
#

ThreadContextmenu.svelte view source

accepts children

import ThreadContextmenu from '@fuzdev/zzz/ThreadContextmenu.svelte';

`thread`

type Thread

`children`

type Snippet<[]>

ThreadJson
#

thread_types.ts view source

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; model_name: string; turns: { id: string & $brand<"Uuid">; ... 8 more ...; error_message?: string | undefined; }[]; enabled: boolean; main_input: string; }

import {ThreadJson} from '@fuzdev/zzz/thread_types.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`model_name`

type string

`turns`

type TurnJson[]

`enabled`

type boolean

`main_input`

The unsent draft for this thread's input, preserved across chat and thread switches.

type string

ThreadJsonInput
#

thread_types.ts view source

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; model_name?: string | undefined; turns?: { role: string; id?: string | undefined; created?: string | undefined; ... 6 more ...; cancelled?: boolean | undefined; }[] | undefined; enabled?: boolean | undefined; main_input?: string |...

import type {ThreadJsonInput} from '@fuzdev/zzz/thread_types.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

`model_name?`

type string

`turns?`

type TurnJsonInput[]

`enabled?`

type boolean

`main_input?`

The unsent draft for this thread's input, preserved across chat and thread switches.

type string

ThreadList
#

ThreadList.svelte view source

import ThreadList from '@fuzdev/zzz/ThreadList.svelte';

`chat?`

type Chat

optional default frontend_context.get().chats.selected

ThreadListitem
#

ThreadListitem.svelte view source

import ThreadListitem from '@fuzdev/zzz/ThreadListitem.svelte';

`thread`

type Thread

`chat`

type Chat

ThreadOptions
#

thread.svelte.ts view source

ThreadOptions import type {ThreadOptions} from '@fuzdev/zzz/thread.svelte.js';

inheritance

extends: CellOptions<typeof ThreadJson>

Threads
#

import {Threads} from '@fuzdev/zzz/threads.svelte.js';

inheritance

extends: Cell<typeof ThreadsJson>

`items`

type IndexedCollection<Thread>

readonly

`constructor`

type new (options: ThreadsOptions): Threads

`options`

type ThreadsOptions

`add_thread`

type (thread: Thread): Thread

`thread`

type Thread

returns Thread

`remove`

Removes a thread — from every chat that has it, and its turns' parts unless another turn references them. Disposing the thread cancels its in-flight completion.

type (id: string & $brand<"Uuid">): void

`id`

type Uuid

returns void

`remove_many`

Removes threads — see remove.

type (ids: (string & $brand<"Uuid">)[]): number

`ids`

type Uuid[]

returns number

the number of threads removed

`remove_unreferenced`

Removes the threads in ids that no chat has anymore.

type (ids: Iterable<string & $brand<"Uuid">>): number

`ids`

type Iterable<Uuid, any, any>

returns number

the number of threads removed

ThreadsJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; items: { id: string & $brand<"Uuid">; ... 5 more ...; main_input: string; }[]; }

import {ThreadsJson} from '@fuzdev/zzz/threads.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`items`

type ThreadJson[]

ThreadsJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; items?: { id?: string | undefined; created?: string | undefined; updated?: string | undefined; model_name?: string | undefined; turns?: { ...; }[] | undefined; enabled?: boolean | undefined; main_input?: string | undefined; }[] | ...

import type {ThreadsJsonInput} from '@fuzdev/zzz/threads.svelte.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

`items?`

type ThreadJsonInput[]

ThreadsOptions
#

ThreadToggleButton.svelte view source

ThreadsOptions import type {ThreadsOptions} from '@fuzdev/zzz/threads.svelte.js';

inheritance

extends: CellOptions<typeof ThreadsJson>

ThreadToggleButton
#

import ThreadToggleButton from '@fuzdev/zzz/ThreadToggleButton.svelte';

`thread`

type Thread

`attrs?`

type HTMLInputAttributes

optional

Time
#

import {Time} from '@fuzdev/zzz/time.svelte.js';

Reactive time management class that provides time-related utilities. Has a configurable update interval that defaults to a full minute to minimize wasteful reactivity, so it's suitable for any cases that need at best 1-minute precision, unless reconfigured.

inheritance

extends: Cell<typeof TimeJson>

`DEFAULT_INTERVAL`

Default update interval in milliseconds (1 minute). The idea is to minimize reactivity and CPU usage for a common use case.

type number

static

`now`

Current time that updates on the configured interval. This is reactive and can be used in derived computations.

Whether the interval timer is currently running.

type boolean

$state.raw

`constructor`

type new (options: TimeOptions): Time

`options`

type TimeOptions

`start`

Starts the interval timer if it's not already running. Ticks land on local wall-clock multiples of interval — the top of each minute by default, the top of each local hour for an hour interval (even in a half-hour timezone) — so a displayed h:mm changes when the clock does instead of up to a full interval late. The UTC offset is read at each tick, so a DST change realigns the next one. An interval that doesn't divide a day evenly has no natural boundary: it still ticks every interval, at an arbitrary phase.

type (): boolean

returns boolean

`stop`

Stops the interval timer if it's running.

type (): boolean

returns boolean

`restart`

Restarts the interval timer, optionally with a new interval.

type (interval?: number | undefined): void

`interval?`

type number

optional

returns void

throws

Error - when `interval` isn't a positive number of milliseconds up to `TIME_INTERVAL_MAX`

`update_now`

Updates the now to the current time immediately.

type (value?: number): void

`value`

type number

default Date.now()

returns void

`dispose`

Override Cell.dispose to stop the interval timer before unregistering.

type (): void

returns void

`interval`

The interval in milliseconds between time updates. Change it with restart.

type number

getter

TIME_INTERVAL_MAX
#

2147483647 import {TIME_INTERVAL_MAX} from '@fuzdev/zzz/time.svelte.js';

The longest Time interval, in milliseconds (about 24.8 days): the largest delay setTimeout takes — a longer one overflows and fires at once.

TimeJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; } import {TimeJson} from '@fuzdev/zzz/time.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

TimeJsonInput
#

{ id?: string | undefined; created?: string | undefined; updated?: string | undefined; } import type {TimeJsonInput} from '@fuzdev/zzz/time.svelte.js';

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

TimeOptions
#

TimeOptions import type {TimeOptions} from '@fuzdev/zzz/time.svelte.js';

Options for configuring a Time instance.

inheritance

extends: CellOptions<typeof TimeJson>

`interval?`

Interval in milliseconds for updating now — positive, at most TIME_INTERVAL_MAX. Ticks land on local wall-clock multiples of it (see Time.start).

type number

default 60_000 (1 minute)

`autostart?`

Whether to automatically start the timer on initialization.

type boolean

default true in browser, false otherwise

TimeValue
#

TimeWidget.svelte view source

TimeValue

type string | number | Date

import type {TimeValue} from '@fuzdev/zzz/time_helpers.js';

TimeWidget
#

import TimeWidget from '@fuzdev/zzz/TimeWidget.svelte';

`value`

type Date

to_auth_gate_state
#

(input: AuthGateInput): AuthGateState import {to_auth_gate_state} from '@fuzdev/zzz/auth_gate.js';

Derive the gate's state. Only the *first* session check shows checking: a login or bootstrap in flight keeps its form mounted, so a failure leaves the fields as typed.

`input`

type AuthGateInput

returns

AuthGateState

to_auth_redirect
#

(url: Pick<URL, "search" | "pathname" | "hash">, root?: string): string import {to_auth_redirect} from '@fuzdev/zzz/auth_gate.js';

Where a login or bootstrap returns to: the page the gate replaced, with its query and hash, so a deep link survives logging in. A path starting // or /\ would read as protocol-relative — another origin — so it returns to the root instead.

`url`

the current page URL

type Pick<URL, "pathname" | "search" | "hash">

`root`

where an unsafe path falls back to (the resolved /)

type string

default '/'

returns

string

to_bounded_ms
#

(value: unknown, bounds: MsSettingBounds): number | null import {to_bounded_ms} from '@fuzdev/zzz/socket_helpers.js';

Coerce a user-entered millisecond setting — inputs can hand over strings, null, or NaN — into a whole number within bounds.

`value`

the raw value

type unknown

`bounds`

the allowed range

type MsSettingBounds

returns

number | null

the clamped value, or null when value isn't a finite number (the caller keeps the current one)

to_chats_url
#

(chat_id: (string & $brand<"Uuid">) | null): string import {to_chats_url} from '@fuzdev/zzz/nav.js';

`chat_id`

type Uuid | null

returns

string

to_completion_response_text
#

(completion_response: { created: string & $brand<"Datetime">; provider_name: "claude" | "chatgpt" | "gemini"; model: string; data: { type: "claude"; value: any; } | { type: "chatgpt"; value: any; } | { ...; }; } | null | undefined): string | null

import {to_completion_response_text} from '@fuzdev/zzz/response_helpers.js';

Extracts the text content from a completion response. For Claude, joins every text content block, skipping thinking blocks.

`completion_response`

type CompletionResponse | null | undefined

returns

string | null

to_completion_stop_reason
#

(completion_response: { created: string & $brand<"Datetime">; provider_name: "claude" | "chatgpt" | "gemini"; model: string; data: { type: "claude"; value: any; } | { type: "chatgpt"; value: any; } | { ...; }; } | null | undefined): string | null

import {to_completion_stop_reason} from '@fuzdev/zzz/response_helpers.js';

Reads the provider's own stop/finish reason from a completion response — Claude's stop_reason, ChatGPT's finish_reason, Gemini's finishReason.

`completion_response`

type CompletionResponse | null | undefined

returns

string | null

the reason, or null when the response carries none

to_completion_truncation
#

(completion_response: { created: string & $brand<"Datetime">; provider_name: "claude" | "chatgpt" | "gemini"; model: string; data: { type: "claude"; value: any; } | { type: "chatgpt"; value: any; } | { ...; }; } | null | undefined): CompletionTruncation | null

import {to_completion_truncation} from '@fuzdev/zzz/response_helpers.js';

Why a completion response was cut off rather than finished. The backend fails a cut-off reply with no text, so a truncated response always has some.

`completion_response`

type CompletionResponse | null | undefined

returns

CompletionTruncation | null

the limit that cut the reply off, or null when it finished

to_default_markdown_view_mode
#

(content_loaded: boolean): MarkdownViewMode import {to_default_markdown_view_mode} from '@fuzdev/zzz/markdown_view_mode.js';

The mode a file opens in until one is chosen: preview where its content is read-only (not loaded), else split.

`content_loaded`

whether the file's content was loaded, so it can be edited

type boolean

returns

MarkdownViewMode

to_directory_readme_path
#

(dir_path: string, index: MarkdownLinkIndex): string | null import {to_directory_readme_path} from '@fuzdev/zzz/markdown_links.js';

The README a link to the folder at dir_path opens, or null when the index has none there (see MARKDOWN_DIRECTORY_INDEX_NAMES).

`dir_path`

the folder, with a trailing /

type string

`index`

what the file index knows

type MarkdownLinkIndex

returns

string | null

to_diskfile_content_kind
#

(path: string): DiskfileContentKind import {to_diskfile_content_kind} from '@fuzdev/zzz/diskfile_content_kind.js';

The content kind of the file at path, by its extension (case-insensitive).

`path`

the file's path or name

type string

returns

DiskfileContentKind

to_duplicate_base_name
#

(name: string, existing_names: { has: (name: string) => boolean; }): string import {to_duplicate_base_name} from '@fuzdev/zzz/chats.svelte.js';

Gets the base name to number a duplicate from, so duplicating my chat 2 yields my chat 3 rather than my chat 2 2. The numeric suffix is only stripped when the base name is itself an existing chat, so names that merely end in a number (like gpt 4) are kept whole.

`name`

the name of the chat being duplicated

type string

`existing_names`

the names of existing chats

type { has: (name: string) => boolean; }

returns

string

the base name for get_unique_name

to_file_bytes_append_url
#

(api_url: string, path: string, offset: number): string import {to_file_bytes_append_url} from '@fuzdev/zzz/file_bytes.js';

Builds the URL to PATCH to append to a file. The append lands only if the file is exactly offset bytes long.

(target: { kind: "path"; path: string; directory: boolean; fragment: string | null; root_relative: boolean; }, index: MarkdownLinkIndex): MarkdownLinkStatus

import {to_markdown_link_status} from '@fuzdev/zzz/markdown_links.js';

Checks a path link's target against the file index (see MarkdownLinkStatus). A folder holding no indexed file — say an empty one — reads as missing, since the index lists only files.

`target`

a resolved path link

type { kind: "path"; path: string; directory: boolean; fragment: string | null; root_relative: boolean; }

MarkdownViewMode | null

to_mdz_plain_text
#

(nodes: readonly MdzNode[]): string import {to_mdz_plain_text} from '@fuzdev/zzz/markdown_links.js';

The plain text of nodes, formatting dropped.

`nodes`

type readonly MdzNode[]

returns

string

to_microphone_error_message
#

(error: unknown): string import {to_microphone_error_message} from '@fuzdev/zzz/recording_helpers.js';

Says why the microphone couldn't be opened, from the error getUserMedia rejected with.

`error`

the rejection

type unknown

returns

string

to_nav_link_href
#

(app: Frontend, label: string, href: string): string import {to_nav_link_href} from '@fuzdev/zzz/nav.js';

`app`

type Frontend

`label`

type string

`href`

type string

returns

string

to_path_extension
#

path_lang.ts view source

(path: string): string | null import {to_path_extension} from '@fuzdev/zzz/path_lang.js';

The extension of the file at path, lowercased and without the dot: the text after the last . of its last segment, null when that segment has no .. A dotfile's name is its extension (.bashrc → bashrc), and a trailing dot gives ''.

`path`

the file's path or name

type string

returns

string | null

to_prepended_list
#

<T>(items: T[], item: T, max: number): T[] import {to_prepended_list} from '@fuzdev/zzz/list_helpers.js';

Creates a new array with item first, followed by items, keeping at most max — the oldest (last) entries fall off. For bounded most-recent-first stacks, like back/forward navigation.

`items`

type T[]

`item`

type T

`max`

type number

returns

T[]

generics

to_prepended_list<T>

`T`

to_preview
#

(content: string | null | undefined, max_length?: number): string import {to_preview} from '@fuzdev/zzz/helpers.js';

`content`

type string | null | undefined

`max_length`

type number

default CONTENT_PREVIEW_LENGTH

returns

string

to_prompts_url
#

(prompt_id: (string & $brand<"Uuid">) | null): string import {to_prompts_url} from '@fuzdev/zzz/nav.js';

`prompt_id`

type Uuid | null

returns

string

to_provider_http_status
#

(data: unknown): number | null import {to_provider_http_status} from '@fuzdev/zzz/provider_types.js';

Reads the upstream HTTP status from a completion error's data.

`data`

the JSON-RPC error's data

type unknown

returns

number | null

the provider API's HTTP status, or null when the error wasn't a non-2xx response

to_recording_name
#

(date: Date): string import {to_recording_name} from '@fuzdev/zzz/recording_helpers.js';

Names a recording by when it started, in local time: 2026-01-31_09-05-07. Sorts by time and has no character a filesystem or a shell minds.

`date`

when the recording started

type Date

returns

string

to_recordings_dir
#

(zzz_dir: string): string import {to_recordings_dir} from '@fuzdev/zzz/recording_helpers.js';

The directory the recordings page records to: recordings/ in the app directory. It needs no open workspace, and keeps voice notes out of whatever repository a workspace is.

`zzz_dir`

the app directory, with its trailing slash

type string

returns

string

to_relative_path
#

(path: string, parent: string): string import {to_relative_path} from '@fuzdev/zzz/diskfile_helpers.js';

Formats path for display relative to the directory parent: the part after parent when path is inside it, else path unchanged, so a path outside parent stays absolute rather than losing its leading /.

`path`

the absolute path to format

type string

`parent`

the directory to show path relative to, with or without a trailing /

type string

returns

string

path relative to parent if it's inside it, else path

to_reordered_list
#

<T>(items: T[], from_index: number, to_index: number): T[] import {to_reordered_list} from '@fuzdev/zzz/list_helpers.js';

Creates a new reordered array without modifying the original.

`items`

type T[]

`from_index`

type number

`to_index`

type number

returns

T[]

generics

to_reordered_list<T>

`T`

to_root_dir
#

(path: string, roots: readonly string[]): string | null import {to_root_dir} from '@fuzdev/zzz/markdown_links.js';

The innermost of roots (directories with a trailing /) holding path, or null when none does — the directory a root-relative link in the file at path resolves against.

`path`

an absolute path

type string

`roots`

the open directories, each with a trailing /

type readonly string[]

returns

string | null

to_transcript_copy_path
#

(source_path: string, is_taken: (path: string) => boolean): string import {to_transcript_copy_path} from '@fuzdev/zzz/transcript_helpers.js';

The path an editable copy of a sidecar's text is created at: the source's path plus .md, or .2.md, .3.md, … when that's taken.

`source_path`

the audio file's absolute path

type string

`is_taken`

whether a path is already a file

type (path: string) => boolean

returns

string

to_transcript_source_path
#

(sidecar_path: string, transcript: { [x: string]: unknown; version: number; source: { [x: string]: unknown; name: string; blake3: string; size: number; duration_ms: number; }; tool: { [x: string]: unknown; backend: string; version: string | null; model: string; model_blake3: string; params: { ...; }; }; language: string | null; segments: { ...; }[]; }): string

import {to_transcript_source_path} from '@fuzdev/zzz/transcript_helpers.js';

The path of the audio a sidecar was made from: the file its source.name names, beside it. The sidecar's own name can't say — a model's name has dots in it too. source.name is always a single path component (the Transcript schema refuses anything else), so this never leaves the sidecar's directory.

`sidecar_path`

the sidecar's absolute path

type string

`transcript`

the sidecar, parsed

type Transcript

returns

string

toggle_main_menu_action_spec
#

ToggleButton.svelte view source

{ method: string; kind: "local_call"; initiator: "frontend"; auth: null; side_effects: true; input: ZodOptional<ZodObject<{ show: ZodOptional<ZodBoolean>; }, $strict>>; output: ZodObject<...>; async: false; description: string; }

import {toggle_main_menu_action_spec} from '@fuzdev/zzz/action_specs.js';

ToggleButton
#

accepts children

import ToggleButton from '@fuzdev/zzz/ToggleButton.svelte';

`active`

Current state of the toggle

type boolean

bindable

`active_content`

Content to display when toggle is active

type Snippet<[]> | string

`inactive_content`

Content to display when toggle is inactive

type Snippet<[]> | string

external types

SvelteHTMLElements['button']

ToggleMainMenuInput
#

value + type

{ show?: boolean | undefined; } | undefined

type { show?: boolean | undefined; } | undefined

import {ToggleMainMenuInput} from '@fuzdev/zzz/action_specs.js';

Input for toggle_main_menu. Optional — omit to toggle, pass {show} to set explicitly.

ToggleMainMenuOutput
#

value + type

{ show: boolean; } import {ToggleMainMenuOutput} from '@fuzdev/zzz/action_specs.js';

Output for toggle_main_menu.

`show`

type boolean

ToMarkdownLinksOptions
#

ToMarkdownLinksOptions import type {ToMarkdownLinksOptions} from '@fuzdev/zzz/markdown_links.js';

`file_path?`

The absolute path of the document's file — without it, path links are inert.

type string | null

`index?`

What the file index knows; without it, nothing gets a status.

type MarkdownLinkIndex | null

Transcript
#

value + type

{ [x: string]: unknown; version: number; source: { [x: string]: unknown; name: string; blake3: string; size: number; duration_ms: number; }; tool: { [x: string]: unknown; backend: string; version: string | null; model: string; model_blake3: string; params: { ...; }; }; language: string | null; segments: { ...; }[]; }

import {Transcript} from '@fuzdev/zzz/transcript_types.js';

A transcript sidecar: the file a transcription writes beside its source, <source name>.<model>.transcript.json. It records what it was made from and what made it. Twin of the backend's Transcript.

Loose, because it's a file on disk: one written by a newer zzz may carry fields this one doesn't know.

`version`

type number

`source`

type { [x: string]: unknown; name: string; blake3: string; size: number; duration_ms: number; }

`tool`

type { [x: string]: unknown; backend: string; version: string | null; model: string; model_blake3: string; params: { [x: string]: unknown; language: string; }; }

`language`

type string | null

`segments`

type TranscriptSegment[]

`[key: string]`

type unknown

TRANSCRIPT_PARAGRAPH_PAUSE_MS
#

2000 import {TRANSCRIPT_PARAGRAPH_PAUSE_MS} from '@fuzdev/zzz/transcript_helpers.js';

A silence at least this long starts a new paragraph in transcript_to_text.

TRANSCRIPT_SIDECAR_SUFFIX
#

".transcript.json" import {TRANSCRIPT_SIDECAR_SUFFIX} from '@fuzdev/zzz/transcript_types.js';

What every transcript sidecar's name ends with.

transcript_to_paragraphs
#

(segments: readonly { start_ms: number | null; end_ms: number | null; text: string; words?: { start_ms: number; end_ms: number; text: string; p: number; }[] | undefined; }[], pause_ms?: number): string[]

import {transcript_to_paragraphs} from '@fuzdev/zzz/transcript_helpers.js';

Joins a transcript's segments into paragraphs of plain text, starting a new one at each pause of pause_ms or more. Untimed segments never break.

`segments`

the transcript's segments, in order

type readonly TranscriptSegment[]

`pause_ms`

the shortest silence that starts a new paragraph

type number

default TRANSCRIPT_PARAGRAPH_PAUSE_MS

returns

string[]

transcript_to_text
#

(transcript: { [x: string]: unknown; version: number; source: { [x: string]: unknown; name: string; blake3: string; size: number; duration_ms: number; }; tool: { [x: string]: unknown; backend: string; version: string | null; model: string; model_blake3: string; params: { ...; }; }; language: string | null; segments: { ...; }[]; }): string

import {transcript_to_text} from '@fuzdev/zzz/transcript_helpers.js';

Makes the text of an editable copy of a transcript: a link to the audio beside it, then the speech as paragraphs split at pauses. The transcript itself is tool output and is never edited — this is what gets edited.

`transcript`

the transcript to copy

type Transcript

returns

string

TranscriptCandidate
#

TranscriptCandidate import type {TranscriptCandidate} from '@fuzdev/zzz/transcript_helpers.js';

A file that might be a transcript sidecar: its path and loaded text.

`path`

type string

readonly

`content`

type string | null

readonly

transcription_create_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodString, "DiskfilePath", "out">; language: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; description: string; }

import {transcription_create_action_spec} from '@fuzdev/zzz/action_specs.js';

transcription_progress_action_spec
#

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ job_id: $ZodBranded<ZodUUID, "Uuid", "out">; segments: ZodArray<...>; }, $strict>; output: ZodVoid; async: true; description: string; }

import {transcription_progress_action_spec} from '@fuzdev/zzz/action_specs.js';

TranscriptionCreateInput
#

value + type

{ path: string & $brand<"DiskfilePath">; language?: string | undefined; } import {TranscriptionCreateInput} from '@fuzdev/zzz/action_specs.js';

Input for transcription_create.

`path`

type string & $brand<"DiskfilePath">

`language?`

A language code like en, or auto (the default) to detect it.

type string

TranscriptionCreateOutput
#

value + type

{ job_id: string & $brand<"Uuid">; } import {TranscriptionCreateOutput} from '@fuzdev/zzz/action_specs.js';

Output for transcription_create: the job that will do it.

`job_id`

type string & $brand<"Uuid">

TranscriptionProgressInput
#

value + type

{ job_id: string & $brand<"Uuid">; segments: { start_ms: number | null; end_ms: number | null; text: string; words?: { start_ms: number; end_ms: number; text: string; p: number; }[] | undefined; }[]; }

import {TranscriptionProgressInput} from '@fuzdev/zzz/action_specs.js';

Input for the transcription_progress notification.

`job_id`

type string & $brand<"Uuid">

`segments`

The segments decoded since the last notification.

type TranscriptSegment[]

TranscriptSegment
#

TranscriptSegments.svelte view source

value + type

{ start_ms: number | null; end_ms: number | null; text: string; words?: { start_ms: number; end_ms: number; text: string; p: number; }[] | undefined; }

import {TranscriptSegment} from '@fuzdev/zzz/transcript_types.js';

A stretch of speech. The times are null from a recognizer that doesn't time its text — then the segment can't be sought to.

`start_ms`

type number | null

`end_ms`

type number | null

`text`

type string

`words?`

type TranscriptWord[]

TranscriptSegments
#

import TranscriptSegments from '@fuzdev/zzz/TranscriptSegments.svelte';

`segments`

type readonly TranscriptSegment[]

`onseek?`

Called with a segment's start, in milliseconds, when it's clicked.

type (ms: number) => void

optional

snippet parameters

ms number

`current_ms?`

The playback position, to mark the segment being spoken.

type number | null

optional default null

TranscriptWord
#

TurnContextmenu.svelte view source

value + type

type PartUnion[]

readonly $derived

`completion_part`

The part completion output is written to — the first TextPart of an assistant turn. null for other roles and for turns without a text part, so completion output never writes through a DiskfilePart to disk.

type TextPart | null

readonly $derived.by

`length`

content.length, summed from the parts' lengths rather than by joining their content.

type number

readonly $derived

`token_count`

type number

readonly $derived

`raw_content`

type string | null | undefined

readonly $derived

`is_content_loaded`

type boolean

readonly $derived

type boolean

readonly $derived

`pending`

type boolean

readonly $derived

`constructor`

type new (options: TurnOptions): Turn

`options`

type TurnOptions

`append_completion_text`

Appends streamed completion text to completion_part.

type (text: string): boolean

`text`

the chunk to append

type string

returns boolean

false if the turn has no completion_part, leaving it unchanged

`set_completion_text`

Replaces the text of completion_part with a final completion response.

type (text: string): boolean

`text`

the full response text

type string

returns boolean

false if the turn has no completion_part, leaving it unchanged

`remove_part`

Removes a part from this turn, and from app.parts unless another turn still references it. Removing the completion_part while its thread's in-flight completion streams into this turn cancels that completion first — its output has nowhere to go. An idle turn is left as is.

type (part_id: string & $brand<"Uuid">): boolean

`part_id`

type Uuid

returns boolean

whether the turn had the part

`cancel_completion`

Cancels the completion streaming into this turn — through its thread when it's the thread's pending turn, so the request is aborted too — settling the turn so late chunks are ignored.

type (): void

returns void

`enabled`

type boolean

gettersetter

`content`

type string

getter

TurnContextmenu
#

accepts children

import TurnContextmenu from '@fuzdev/zzz/TurnContextmenu.svelte';

`turn`

type Turn

`children`

type Snippet<[]>

TurnJson
#

turn_types.ts view source

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; part_ids: (string & $brand<"Uuid">)[]; ... 5 more ...; error_message?: string | undefined; }

import {TurnJson} from '@fuzdev/zzz/turn_types.js';

Turn is a conversation turn (like A2A Message) that references one or more parts (content entities). Turns contextualize reusable content within conversations, providing role, metadata, and ordering.

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`part_ids`

type (string & $brand<"Uuid">)[]

`role`

type string

`cancelled`

Set when the user stops a completion before it finished. The turn keeps any partial content that streamed in, and stops showing as pending.

type boolean

`thread_id?`

type (string & $brand<"Uuid">) | null

`request?`

type CompletionRequest

`response?`

type CompletionResponse

`error_message?`

Set when a completion fails. The turn keeps any content that streamed in before the failure; errored turns are excluded from later completion history.

type string

TurnJsonInput
#

turn_types.ts view source

{ role: string; id?: string | undefined; created?: string | undefined; updated?: string | undefined; part_ids?: string[] | undefined; thread_id?: string | null | undefined; request?: { provider_name: "claude" | ... 1 more ... | "gemini"; model: string; prompt: string; created?: string | undefined; completion_message...

import type {TurnJsonInput} from '@fuzdev/zzz/turn_types.js';

`role`

type string

`id?`

type string

`created?`

type string

`updated?`

Required and initially equal to created.

type string

`part_ids?`

type string[]

`thread_id?`

type string | null

`request?`

type { provider_name: "claude" | "chatgpt" | "gemini"; model: string; prompt: string; created?: string | undefined; completion_messages?: { [x: string]: unknown; role: string; content: string; }[] | undefined; }

`response?`

type { provider_name: "claude" | "chatgpt" | "gemini"; model: string; data: { type: "claude"; value?: any; } | { type: "chatgpt"; value?: any; } | { type: "gemini"; value: { text: string; candidates?: any[] | null | undefined; function_calls?: any[] | ... 1 more ... | undefined; prompt_feedback?: any; usage_metadata?: an...

`error_message?`

Set when a completion fails. The turn keeps any content that streamed in before the failure; errored turns are excluded from later completion history.

type string

`cancelled?`

Set when the user stops a completion before it finished. The turn keeps any partial content that streamed in, and stops showing as pending.

type boolean

TurnList
#

TurnList.svelte view source

import TurnList from '@fuzdev/zzz/TurnList.svelte';

`thread`

type Thread

`attrs?`

type HTMLAttributes<HTMLDivElement>

optional

TurnListitem
#

TurnListitem.svelte view source

import TurnListitem from '@fuzdev/zzz/TurnListitem.svelte';

`turn`

type Turn

TurnOptions
#

turn.svelte.ts view source

TurnOptions import type {TurnOptions} from '@fuzdev/zzz/turn.svelte.js';

inheritance

extends: CellOptions<typeof TurnJson>

TurnSchema
#

turn_types.ts view source

ZodCustom<Cell<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>, Cell<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>

type ZodCustom<Cell<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>, Cell<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>

import {TurnSchema} from '@fuzdev/zzz/turn_types.js';

TurnView
#

TurnView.svelte view source

import TurnView from '@fuzdev/zzz/TurnView.svelte';

`turn`

type Turn

`show_actions?`

type boolean

optional default true

TutorialForChats
#

TutorialForChats.svelte view source

import TutorialForChats from '@fuzdev/zzz/TutorialForChats.svelte';

TutorialForDatabase
#

TutorialForDatabase.svelte view source

import TutorialForDatabase from '@fuzdev/zzz/TutorialForDatabase.svelte';

TutorialForDiskfiles
#

TutorialForDiskfiles.svelte view source

import TutorialForDiskfiles from '@fuzdev/zzz/TutorialForDiskfiles.svelte';

TutorialForPrompts
#

TutorialForPrompts.svelte view source

import TutorialForPrompts from '@fuzdev/zzz/TutorialForPrompts.svelte';

Ui
#

ui.svelte.ts view source

import {Ui} from '@fuzdev/zzz/ui.svelte.js';

type boolean

$state.raw

`pending_element_to_focus_key`

Consumed by components like ContentEditor for focusing elements.

type string | number | null

$state.raw

`constructor`

type new (options: UiOptions): Ui

`options`

type UiOptions

`toggle_main_menu`

Toggle the main menu visibility.

type (value?: boolean): boolean

`value`

type boolean

default !this.show_main_dialog

returns boolean

`toggle_sidebar`

Toggle the sidebar visibility.

type (value?: boolean): boolean

`value`

type boolean

default !this.show_sidebar

returns boolean

`toggle_desk_menu`

Toggle the desk menu visibility.

type (value?: boolean): boolean

`value`

type boolean

default !this.show_desk_menu

returns boolean

`toggle_desk_pinned`

Toggle the desk menu pinned state.

type (value?: boolean): boolean

`value`

type boolean

default !this.desk_pinned

returns boolean

UiJson
#

ui.svelte.ts view source

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; show_main_dialog: boolean; show_sidebar: boolean; ... 5 more ...; desk_pinned: boolean; }

import {UiJson} from '@fuzdev/zzz/ui.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

UiOptions
#

ui.svelte.ts view source

UiOptions import type {UiOptions} from '@fuzdev/zzz/ui.svelte.js';

inheritance

extends: CellOptions<typeof UiJson>

validate_reorderable_target_index
#

(target_index: number, max_index: number): number import {validate_reorderable_target_index} from '@fuzdev/zzz/reorderable_helpers.js';

Validate and adjust a target index to ensure it's within bounds

`target_index`

type number

`max_index`

type number

returns

number

ValueParser
#

ValueParser<TSchema, TKey> import type {ValueParser} from '@fuzdev/zzz/cell_helpers.js';

generics

ValueParser<TSchema extends z.ZodType, TKey extends keyof z.infer<TSchema> = keyof z.infer<TSchema>>

`TSchema`

constraint z.ZodType

`TKey`

constraint keyof z.infer<TSchema>

default keyof z.infer<TSchema>

WEBSOCKET_PATH
#

string | undefined

type string | undefined

import {WEBSOCKET_PATH} from '@fuzdev/zzz/constants.js';

WEBSOCKET_URL
#

string import {WEBSOCKET_URL} from '@fuzdev/zzz/constants.js';

PUBLIC_ZZZ_WEBSOCKET_URL when set (dev: zzzd directly), else API_PATH + '/ws' on the page's origin (the Vite dev proxy carries WebSockets too). Empty during SSR/prerender when unset.

WEBSOCKET_URL_OBJECT
#

URL | null

type URL | null

import {WEBSOCKET_URL_OBJECT} from '@fuzdev/zzz/constants.js';

WebsocketCapabilityData
#

Workspace
#

import {Workspace} from '@fuzdev/zzz/workspace.svelte.js';

A workspace represents an open directory that zzz is watching and serving.

Workspaces are the primary unit of file access — each workspace registers its directory with ScopedFs and starts a Filer for file watching.

inheritance

extends: Cell<typeof WorkspaceJson>

`path`

$state.raw

`name`

type string

$state.raw

`opened_at`

type Datetime

$state.raw

`watch_status`

Whether the daemon watches every directory of this workspace, as of the last workspace_open — degraded means some are only rescanned periodically. Transient client state, not serialized.

type WorkspaceWatchStatus

$state.raw

`constructor`

type new (options: WorkspaceOptions): Workspace

`options`

type WorkspaceOptions

workspace_changed_action_spec
#

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ type: ZodEnum<{ open: "open"; close: "close"; }>; workspace: ZodObject<{ path: $ZodBranded<ZodPipe<ZodPipe<...>, $ZodBranded<...>>, "DiskfileDirectoryPath", "out">; name: ZodString; opened_at: ZodS...

import {workspace_changed_action_spec} from '@fuzdev/zzz/action_specs.js';

workspace_close_action_spec
#

workspace_helpers.ts view source

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodPipe<ZodPipe<ZodString, ZodTransform<string, string>>, $ZodBranded<...>>, "DiskfileDirectoryPath", "out">; }, $strict>; output: ZodNull; async:...

import {workspace_close_action_spec} from '@fuzdev/zzz/action_specs.js';

WORKSPACE_DEGRADED_NOTICE
#

"Not every directory has a file watch (likely the system's watch limit) — changes in some show up after a few seconds."

import {WORKSPACE_DEGRADED_NOTICE} from '@fuzdev/zzz/workspace_helpers.js';

What to tell the user about a workspace whose watch_status is degraded: some of its directories have no file watch, so the daemon rescans them every few seconds instead.

workspace_list_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: false; input: ZodVoid; output: ZodObject<{ workspaces: ZodArray<ZodObject<{ path: $ZodBranded<...>; name: ZodString; opened_at: ZodString; }, $strict>>; }, $strict>; async: true; descriptio...

import {workspace_list_action_spec} from '@fuzdev/zzz/action_specs.js';

workspace_open_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { account: "required"; actor: "none"; }; side_effects: true; input: ZodObject<{ path: $ZodBranded<ZodPipe<ZodPipe<ZodString, ZodTransform<string, string>>, $ZodBranded<...>>, "DiskfileDirectoryPath", "out">; }, $strict>; output: ZodObject<...>;...

import {workspace_open_action_spec} from '@fuzdev/zzz/action_specs.js';

WorkspaceChangedInput
#

value + type

{ type: "open" | "close"; workspace: { path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; name: string; opened_at: string; }; }

import {WorkspaceChangedInput} from '@fuzdev/zzz/action_specs.js';

Input for workspace_changed.

`type`

type "open" | "close"

`workspace`

type WorkspaceInfoJson

WorkspaceChangeTracker
#

WorkspaceChangeTracker import type {WorkspaceChangeTracker} from '@fuzdev/zzz/workspaces.svelte.js';

Records the workspace paths added or removed while a session snapshot is in flight.

`paths`

Paths add or remove touched since tracking started.

type ReadonlySet<string>

readonly

`stop`

Stops recording.

type (): void

returns void

WorkspaceCloseInput
#

value + type

{ path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; } import {WorkspaceCloseInput} from '@fuzdev/zzz/action_specs.js';

Input for workspace_close.

`path`

type string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">

WorkspaceInfoJson
#

value + type

{ path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; name: string; opened_at: string; } import {WorkspaceInfoJson} from '@fuzdev/zzz/workspace.svelte.js';

The wire format for workspace info shared between frontend and backend. Used in action spec inputs/outputs and for JSON persistence.

`path`

Absolute directory path for this workspace.

type string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">

`name`

Display name, auto-derived from directory basename.

type string

`opened_at`

ISO timestamp of when this workspace was opened.

type string

WorkspaceJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; path: string & $brand<"DiskfilePath"> & $brand<...>; name: string; opened_at: string; }

import {WorkspaceJson} from '@fuzdev/zzz/workspace.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

`name?`

type string

`opened_at?`

type string

WorkspaceListOutput
#

value + type

{ workspaces: { path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; name: string; opened_at: string; }[]; }

import {WorkspaceListOutput} from '@fuzdev/zzz/action_specs.js';

Output for workspace_list.

`workspaces`

type WorkspaceInfoJson[]

WorkspaceOpenInput
#

value + type

{ path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; } import {WorkspaceOpenInput} from '@fuzdev/zzz/action_specs.js';

Input for workspace_open.

`path`

type string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">

WorkspaceOpenOutput
#

value + type

{ workspace: { path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; name: string; opened_at: string; }; files: { id: string & $brand<"DiskfilePath">; ... 5 more ...; dependencies: [...][]; }[]; watch_status: "full" | "degraded"; }

import {WorkspaceOpenOutput} from '@fuzdev/zzz/action_specs.js';

Output for workspace_open.

`workspace`

type WorkspaceInfoJson

`files`

type SerializableDisknode[]

`watch_status`

type "full" | "degraded"

WorkspaceOptions
#

WorkspaceOptions import type {WorkspaceOptions} from '@fuzdev/zzz/workspace.svelte.js';

inheritance

extends: CellOptions<typeof WorkspaceJson>

Workspaces
#

import {Workspaces} from '@fuzdev/zzz/workspaces.svelte.js';

Collection of open workspaces.

Manages the set of directories the daemon is watching and serving. Each workspace has a unique path used as the index key.

inheritance

extends: Cell<typeof WorkspacesJson>

`items`

type IndexedCollection<Workspace>

readonly

`active_id`

type Uuid | null

$state.raw

`active`

type Workspace | undefined

readonly $derived

`constructor`

type new (options: WorkspacesOptions): Workspaces

`options`

type WorkspacesOptions

`track_changes`

Starts recording the workspace paths add and remove touch. Start it before requesting a session snapshot and pass its paths to reconcile, so the snapshot doesn't undo an open or close that happened while the request was in flight.

type (): WorkspaceChangeTracker

returns WorkspaceChangeTracker

`add`

Add a workspace. If a workspace with the same path already exists, returns it.

type (json: { path: string; id?: string | undefined; created?: string | undefined; updated?: string | undefined; name?: string | undefined; opened_at?: string | undefined; }, options?: { activate?: boolean | undefined; } | undefined): Workspace

`json`

type WorkspaceJsonInput

`options?`

type { activate?: boolean | undefined; }

optional

returns Workspace

`receive_remote_open`

Handles a workspace_changed open — broadcast for every open, this client's own included. A workspace this client doesn't know was opened elsewhere (another tab, zzz <dir>): it's added without being activated, and since the notification carries none of its files (the daemon's initial scan broadcasts nothing), the session is resynced to fetch them (Frontend.resync_session). While this client's own open is in flight the notification may be its own, landing before the reply that carries the files, so the resync waits for the opens to settle and is skipped when one of them turns out to be that workspace.

type (json: { path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; name: string; opened_at: string; }): void

`json`

type WorkspaceInfoJson

returns void

`open`

Opens the workspace at path on the backend (workspace_open), then adds it with its file tree, applied around what filer_change reported while the request was in flight (see Diskfiles.track_changes).

type (path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">, options?: { reconcile_files?: boolean | undefined; } | undefined): Promise<Result<{ value: Workspace; }, { ...; }>>

`path`

the directory to open; the daemon canonicalizes it, so the returned workspace's path may differ

`options?`

type { reconcile_files?: boolean | undefined; }

optional

returns Promise<Result>

the opened workspace, or the RPC error

`remove`

type (id: string & $brand<"Uuid">): void

`id`

type Uuid

returns void

`reconcile`

Reconciles the open workspaces with a session snapshot's: adds the ones it lists, and removes the ones it doesn't — the backend closed them — unless keep_unlisted (after a restart the caller reopens them instead).

type (workspaces: readonly { path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">; name: string; opened_at: string; }[], options?: { skip_paths?: ReadonlySet<string> | undefined; keep_unlisted?: boolean | undefined; } | undefined): (string & ... 1 more ... & $brand<...>)[]

`workspaces`

the snapshot's workspaces

type readonly WorkspaceInfoJson[]

`options?`

type { skip_paths?: ReadonlySet<string> | undefined; keep_unlisted?: boolean | undefined; }

optional

returns DiskfileDirectoryPath[]

the paths of the open workspaces the snapshot doesn't list (outside skip_paths) — removed unless keep_unlisted

`get_by_path`

type (path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">): Workspace | undefined

`path`

returns Workspace | undefined

`remove_by_path`

Remove the workspace at path, if one exists. No-op when absent.

type (path: string & $brand<"DiskfilePath"> & $brand<"DiskfileDirectoryPath">): void

`path`

returns void

`activate`

type (id: string & $brand<"Uuid">): void

`id`

type Uuid

returns void

WorkspacesJson
#

value + type

{ id: string & $brand<"Uuid">; created: string & $brand<"Datetime">; updated: string & $brand<"Datetime">; items: { id: string & $brand<"Uuid">; ... 4 more ...; opened_at: string; }[]; active_id: (string & $brand<...>) | null; }

import {WorkspacesJson} from '@fuzdev/zzz/workspaces.svelte.js';

`id`

type string & $brand<"Uuid">

`created`

type string & $brand<"Datetime">

`updated`

Required and initially equal to created.

type string & $brand<"Datetime">

`items`

type WorkspaceJson[]

`active_id`

type (string & $brand<"Uuid">) | null

WorkspacesJsonInput
#