API ReferenceSandboxAuthoringsandbox/authoring/hostProxyInterfaces

SandboxHostApi

Reference — SandboxHostApi in the Mutka module API.

Interface: SandboxHostApi<TCommandId>

Defined in: sandbox/authoring/hostProxy.ts:43

Type Parameters

Type Parameter	Default type
`TCommandId` extends `string`	`string`

Properties

board

board: {
  readFiles: Promise<ClipboardFiles | null>;
  writeFiles: Promise<void>;
};

Defined in: sandbox/authoring/hostProxy.ts:63

readFiles()

readFiles(): Promise<ClipboardFiles | null>;

Read the pasteboard's pending file list, or null if it holds no files.

Returns

Promise<ClipboardFiles | null>

writeFiles()

writeFiles(paths, operation): Promise<void>;

Parameters

Parameter	Type
`paths`	`string`[]
`operation`	`"copy"` \| `"cut"`

Returns

Promise<void>

config

config: {
  get: Promise<string | null>;
  set: Promise<void>;
};

Defined in: sandbox/authoring/hostProxy.ts:167

Per-module persisted config (gated by the storage permission).

get()

get(key): Promise<string | null>;

Read a stored value, or null if the key was never set.

Parameters

Parameter	Type
`key`	`string`

Returns

Promise<string | null>

set()

set(key, value): Promise<void>;

Parameters

Parameter	Type
`key`	`string`
`value`	`string`

Returns

Promise<void>

dialog

dialog: {
  choose: Promise<string | null>;
  confirm: Promise<boolean>;
  pickFile: Promise<string | null>;
  prompt: Promise<string | null>;
};

Defined in: sandbox/authoring/hostProxy.ts:92

choose()

choose(options): Promise<string | null>;

Show a single-choice list. Resolves with the chosen option's value, or null.

Parameters

Parameter	Type
`options`	{ `message`: `string`; `options`: { `detail?`: `string`; `icon?`: `string`; `label`: `string`; `value`: `string`; }[]; }
`options.message`	`string`
`options.options`	{ `detail?`: `string`; `icon?`: `string`; `label`: `string`; `value`: `string`; }[]

Returns

Promise<string | null>

confirm()

confirm(options): Promise<boolean>;

Yes/no dialog. Resolves true (confirm) or false (cancel).

Parameters

Parameter	Type
`options`	{ `destructive?`: `boolean`; `detail?`: `string`; `message`: `string`; }
`options.destructive?`	`boolean`
`options.detail?`	`string`
`options.message`	`string`

Returns

Promise<boolean>

pickFile()

pickFile(options?): Promise<string | null>;

Open a Mutka file browser to pick one file. Resolves with its path, or null.

Parameters

Parameter	Type
`options?`	{ `fileNames?`: `string`[]; `initialDir?`: `string`; `title?`: `string`; }
`options.fileNames?`	`string`[]
`options.initialDir?`	`string`
`options.title?`	`string`

Returns

Promise<string | null>

prompt()

prompt(options): Promise<string | null>;

Text-input dialog. Resolves with the entered string, or null if cancelled.

Parameters

Parameter	Type
`options`	{ `defaultValue?`: `string`; `message`: `string`; `placeholder?`: `string`; }
`options.defaultValue?`	`string`
`options.message`	`string`
`options.placeholder?`	`string`

Returns

Promise<string | null>

events

events: {
  on: void;
};

Defined in: sandbox/authoring/hostProxy.ts:216

Subscribe to a whitelisted app event.

on()

on(event, handler): void;

Parameters

Parameter	Type
`event`	`string`
`handler`	`EventHandler`

Returns

void

fs

fs: {
  cloudStatus: Promise<CloudStatus>;
  copyFiles: Promise<void>;
  createFile: Promise<void>;
  createFolder: Promise<void>;
  deleteItem: Promise<void>;
  moveFiles: Promise<void>;
  openItem: Promise<void>;
  readBytes: Promise<Uint8Array<ArrayBufferLike>>;
  readDir: Promise<FileItem[]>;
  renameItem: Promise<void>;
  trashItem: Promise<void>;
};

Defined in: sandbox/authoring/hostProxy.ts:44

cloudStatus()

cloudStatus(path): Promise<CloudStatus>;

Whether a file is materialized locally or cloud-only.

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<CloudStatus>

copyFiles()

copyFiles(paths, dest): Promise<void>;

Parameters

Parameter	Type
`paths`	`string`[]
`dest`	`string`

Returns

Promise<void>

createFile()

createFile(path): Promise<void>;

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

createFolder()

createFolder(path): Promise<void>;

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

deleteItem()

deleteItem(path): Promise<void>;

Permanently delete an item (unrecoverable). Use trashItem unless the user asked to erase.

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

moveFiles()

moveFiles(paths, dest): Promise<void>;

Parameters

Parameter	Type
`paths`	`string`[]
`dest`	`string`

Returns

Promise<void>

openItem()

openItem(path): Promise<void>;

Open an item with the system default handler.

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

readBytes()

readBytes(path): Promise<Uint8Array<ArrayBufferLike>>;

Read a file's raw bytes.

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<Uint8Array<ArrayBufferLike>>

readDir()

readDir(path): Promise<FileItem[]>;

List a directory's entries (works for local paths and provider schemes).

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<FileItem[]>

renameItem()

renameItem(from, to): Promise<void>;

Parameters

Parameter	Type
`from`	`string`
`to`	`string`

Returns

Promise<void>

trashItem()

trashItem(path): Promise<void>;

Move an item to the OS Trash (recoverable). Prefer this over deleteItem.

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

home

home: {
  get: Promise<string>;
  set: Promise<void>;
};

Defined in: sandbox/authoring/hostProxy.ts:103

The app's home directory store (distinct from the OS home, sys.homeDir).

get()

get(): Promise<string>;

Read the current app home directory.

Returns

Promise<string>

set()

set(path): Promise<void>;

Set the app home directory (any module may override it).

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

modules

modules: {
  install: Promise<void>;
  probe: Promise<SandboxManifest>;
};

Defined in: sandbox/authoring/hostProxy.ts:159

Module tooling (gated by the discovery permission).

install()

install(source): Promise<void>;

Propose a module source for install - opens the permission-review dialog so the user approves before anything is written.

Parameters

Parameter	Type
`source`	`string`

Returns

Promise<void>

probe()

probe(source): Promise<SandboxManifest>;

Validate an ESM source in a throwaway worker and return its manifest.

Parameters

Parameter	Type
`source`	`string`

Returns

Promise<SandboxManifest>

nav

nav: {
  goBack: Promise<void>;
  goForward: Promise<void>;
  goUp: Promise<void>;
  navigate: Promise<void>;
};

Defined in: sandbox/authoring/hostProxy.ts:68

goBack()

goBack(): Promise<void>;

Returns

Promise<void>

goForward()

goForward(): Promise<void>;

Returns

Promise<void>

goUp()

goUp(): Promise<void>;

Returns

Promise<void>

navigate()

navigate(path): Promise<void>;

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

net

net: {
  request: Promise<NetResponse>;
};

Defined in: sandbox/authoring/hostProxy.ts:155

Host-proxied HTTP (avoids CORS, gated by network:public / network:local). One role: it sends a request and returns the response - it never touches the filesystem. To upload, read bytes via fs.readBytes (fs:read) and pass them as body; to save a response, write bytes via fs.* / sys.writeTempFile.

request()

request(options): Promise<NetResponse>;

Parameters

Parameter	Type
`options`	`NetRequestOptions`

Returns

Promise<NetResponse>

secrets

secrets: {
  delete: Promise<void>;
  get: Promise<string | null>;
  set: Promise<void>;
};

Defined in: sandbox/authoring/hostProxy.ts:173

Per-module credentials in the macOS Keychain (gated by secrets).

delete()

delete(key): Promise<void>;

Parameters

Parameter	Type
`key`	`string`

Returns

Promise<void>

get()

get(key): Promise<string | null>;

Read a stored credential, or null if absent.

Parameters

Parameter	Type
`key`	`string`

Returns

Promise<string | null>

set()

set(key, value): Promise<void>;

Parameters

Parameter	Type
`key`	`string`
`value`	`string`

Returns

Promise<void>

selection

selection: {
  set: Promise<void>;
};

Defined in: sandbox/authoring/hostProxy.ts:81

Drive view state: the current selection and the active sort.

set()

set(items): Promise<void>;

Parameters

Parameter	Type
`items`	`FileItem`[]

Returns

Promise<void>

settings

settings: {
  toggle: Promise<void>;
};

Defined in: sandbox/authoring/hostProxy.ts:110

Toggle the settings overlay open/closed.

toggle()

toggle(): Promise<void>;

Returns

Promise<void>

sidebar: {
  set: void;
};

Defined in: sandbox/authoring/hostProxy.ts:214

Replace this module's dynamic left-sidebar items (e.g. a bookmarks list).

set()

set(items): void;

Parameters

Parameter	Type
`items`	`SidebarItem`[]

Returns

void

statusbar

statusbar: {
  remove: Promise<void>;
  set: Promise<void>;
};

Defined in: sandbox/authoring/hostProxy.ts:123

Bottom status-bar items (e.g. a git widget). Gated by ui.

remove()

remove(itemId): Promise<void>;

Remove a status-bar item by id.

Parameters

Parameter	Type
`itemId`	`string`

Returns

Promise<void>

set()

set(item): Promise<void>;

Add or replace one status-bar item (keyed by its id).

Parameters

Parameter	Type
`item`	`StatusBarItem`

Returns

Promise<void>

sys

sys: {
  appsForFile: Promise<AppInfo[]>;
  appVersion: Promise<string>;
  homeDir: Promise<string>;
  lastDir: Promise<string | null>;
  openWith: Promise<void>;
  previewUpdate: Promise<void>;
  quickLook: Promise<void>;
  startDrag: Promise<void>;
  writeTempFile: Promise<string>;
};

Defined in: sandbox/authoring/hostProxy.ts:129

appsForFile()

appsForFile(path): Promise<AppInfo[]>;

Apps that can open a file (Launch Services), default flagged + first.

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<AppInfo[]>

appVersion()

appVersion(): Promise<string>;

The app's own version string (e.g. "1.0.0"). Gated by storage.

Returns

Promise<string>

homeDir()

homeDir(): Promise<string>;

The OS home directory.

Returns

Promise<string>

lastDir()

lastDir(): Promise<string | null>;

The last visited local directory, or null on first run.

Returns

Promise<string | null>

openWith()

openWith(path, appPath): Promise<void>;

Open a file with a specific application bundle path.

Parameters

Parameter	Type
`path`	`string`
`appPath`	`string`

Returns

Promise<void>

previewUpdate()

previewUpdate(path): Promise<void>;

Refresh an already-open Quick Look panel to preview path (else no-op).

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

quickLook()

quickLook(path): Promise<void>;

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

startDrag()

startDrag(paths, icon?): Promise<void>;

Start a native OS file drag of paths, previewed by icon (data-URI/path).

Parameters

Parameter	Type
`paths`	`string`[]
`icon?`	`string`

Returns

Promise<void>

writeTempFile()

writeTempFile(filename, data): Promise<string>;

Write bytes to a temp file and return its path (Uint8Array, or a base64 string for a Finder-dropped file). Gated by fs:temp.

Parameters

Parameter	Type
`filename`	`string`
`data`	`string` \| `Uint8Array`<`ArrayBufferLike`>

Returns

Promise<string>

tabs

tabs: {
  isActive: Promise<boolean>;
  openTab: Promise<void>;
  openTabInBackground: Promise<void>;
};

Defined in: sandbox/authoring/hostProxy.ts:74

isActive()

isActive(): Promise<boolean>;

Whether this module's runtime is bound to the active tab.

Returns

Promise<boolean>

openTab()

openTab(path): Promise<void>;

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

openTabInBackground()

openTabInBackground(path): Promise<void>;

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

ui

ui: {
  clear: Promise<void>;
  modal: Promise<void>;
  render: Promise<void>;
};

Defined in: sandbox/authoring/hostProxy.ts:114

Render declarative UI (a serializable UINode tree). Gated by ui.

clear()

clear(surfaceId): Promise<void>;

Clear a surface so it renders empty.

Parameters

Parameter	Type
`surfaceId`	`string`

Returns

Promise<void>

modal(node): Promise<void>;

Open a modal with node, or pass null to close the current one.

Parameters

Parameter	Type
`node`	`UINode` \| `null`

Returns

Promise<void>

render()

render(surfaceId, node): Promise<void>;

Render/replace the UINode shown in a named surface (panel/settings/popover).

Parameters

Parameter	Type
`surfaceId`	`string`
`node`	`UINode`

Returns

Promise<void>

view

view: {
  setShowHidden: Promise<void>;
  setSort: Promise<void>;
  toggleHidden: Promise<void>;
  toggleSort: Promise<void>;
};

Defined in: sandbox/authoring/hostProxy.ts:84

setShowHidden()

setShowHidden(value): Promise<void>;

Explicitly set whether hidden/system files are shown.

Parameters

Parameter	Type
`value`	`boolean`

Returns

Promise<void>

setSort()

setSort(sort): Promise<void>;

Parameters

Parameter	Type
`sort`	`SortState`

Returns

Promise<void>

toggleHidden()

toggleHidden(): Promise<void>;

Toggle whether hidden/system files (dotfiles) are shown.

Returns

Promise<void>

toggleSort()

toggleSort(key): Promise<void>;

Parameters

Parameter	Type
`key`	`SortKey`

Returns

Promise<void>

Methods

activate()

activate(item): Promise<void>;

Defined in: sandbox/authoring/hostProxy.ts:182

Run an item through the open-resolution pipeline (keyboard double-click).

Parameters

Parameter	Type
`item`	`FileItem`

Returns

Promise<void>

log()

log(...args): void;

Defined in: sandbox/authoring/hostProxy.ts:218

Forwarded to the host console, prefixed with the module id.

Parameters

Parameter	Type
...`args`	`unknown`[]

Returns

void

onColumn()

onColumn(columnId, provider): void;

Defined in: sandbox/authoring/hostProxy.ts:190

Register the value provider for one of this module's custom columns.

Parameters

Parameter	Type
`columnId`	`string`
`provider`	`ColumnProvider`

Returns

void

onCommand()

onCommand(commandId, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:186

Register the function that runs when one of this module's commands fires. When you use defineModule, commandId is constrained to the ids you declared in commands[], so a typo or stale id is a compile error.

Parameters

Parameter	Type
`commandId`	`TCommandId`
`handler`	`CommandHandler`

Returns

void

onCopyFiles()

onCopyFiles(scheme, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:206

Register the copy handler (sources may be local → upload, or same-scheme).

Parameters

Parameter	Type
`scheme`	`string`
`handler`	`TransferHandler`

Returns

void

onCreateFile()

onCreateFile(scheme, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:200

Register the create-file handler for a file system provider scheme.

Parameters

Parameter	Type
`scheme`	`string`
`handler`	`WriteHandler`

Returns

void

onCreateFolder()

onCreateFolder(scheme, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:198

Register the create-folder handler for a file system provider scheme.

Parameters

Parameter	Type
`scheme`	`string`
`handler`	`WriteHandler`

Returns

void

onDeleteItem()

onDeleteItem(scheme, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:202

Register the delete handler for a file system provider scheme.

Parameters

Parameter	Type
`scheme`	`string`
`handler`	`WriteHandler`

Returns

void

onDiscover()

onDiscover(sourceId, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:210

Register the discover handler for a declared discovery source.

Parameters

Parameter	Type
`sourceId`	`string`
`handler`	`DiscoverHandler`

Returns

void

onFetchSource()

onFetchSource(sourceId, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:212

Register the fetch-source handler for a declared discovery source.

Parameters

Parameter	Type
`sourceId`	`string`
`handler`	`FetchSourceHandler`

Returns

void

onList()

onList(scheme, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:194

Register the directory-listing handler for a file system provider scheme.

Parameters

Parameter	Type
`scheme`	`string`
`handler`	`ListHandler`

Returns

void

onMoveFiles()

onMoveFiles(scheme, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:208

Register the move handler (same-scheme sources).

Parameters

Parameter	Type
`scheme`	`string`
`handler`	`TransferHandler`

Returns

void

onOpen()

onOpen(handlerId, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:188

Register the function that runs when an item matches one of this module's open handlers.

Parameters

Parameter	Type
`handlerId`	`string`
`handler`	`OpenHandler`

Returns

void

onOpenFile()

onOpenFile(scheme, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:196

Register the file-open handler for a file system provider scheme.

Parameters

Parameter	Type
`scheme`	`string`
`handler`	`OpenFileHandler`

Returns

void

onRenameItem()

onRenameItem(scheme, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:204

Register the rename/move handler for a file system provider scheme.

Parameters

Parameter	Type
`scheme`	`string`
`handler`	`RenameProviderHandler`

Returns

void

onUIEvent()

onUIEvent(handlerId, handler): void;

Defined in: sandbox/authoring/hostProxy.ts:192

Register a handler fired when a button/list/form in this module's UI is used.

Parameters

Parameter	Type
`handlerId`	`string`
`handler`	`UIEventHandler`

Returns

void

refresh()

refresh(): Promise<void>;

Defined in: sandbox/authoring/hostProxy.ts:180

Re-read the current directory after a mutation.

Returns

Promise<void>

NetResponse

Reference — NetResponse in the Mutka module API.

CloudStatus

Reference — CloudStatus in the Mutka module API.

On this page

Interface: SandboxHostApi<TCommandId>Type Parameters Properties board readFiles()Returns writeFiles()Parameters Returns config get()Parameters Returns set()Parameters Returns dialog choose()Parameters Returns confirm()Parameters Returns pickFile()Parameters Returns prompt()Parameters Returns events on()Parameters Returns fs cloudStatus()Parameters Returns copyFiles()Parameters Returns createFile()Parameters Returns createFolder()Parameters Returns deleteItem()Parameters Returns moveFiles()Parameters Returns openItem()Parameters Returns readBytes()Parameters Returns readDir()Parameters Returns renameItem()Parameters Returns trashItem()Parameters Returns home get()Returns set()Parameters Returns modules install()Parameters Returns probe()Parameters Returns nav goBack()Returns goForward()Returns goUp()Returns navigate()Parameters Returns net request()Parameters Returns secrets delete()Parameters Returns get()Parameters Returns set()Parameters Returns selection set()Parameters Returns settings toggle()Returns sidebar set()Parameters Returns statusbar remove()Parameters Returns set()Parameters Returns sys appsForFile()Parameters Returns appVersion()Returns homeDir()Returns lastDir()Returns openWith()Parameters Returns previewUpdate()Parameters Returns quickLook()Parameters Returns startDrag()Parameters Returns writeTempFile()Parameters Returns tabs isActive()Returns openTab()Parameters Returns openTabInBackground()Parameters Returns ui clear()Parameters Returns modal()Parameters Returns render()Parameters Returns view setShowHidden()Parameters Returns setSort()Parameters Returns toggleHidden()Returns toggleSort()Parameters Returns Methods activate()Parameters Returns log()Parameters Returns onColumn()Parameters Returns onCommand()Parameters Returns onCopyFiles()Parameters Returns onCreateFile()Parameters Returns onCreateFolder()Parameters Returns onDeleteItem()Parameters Returns onDiscover()Parameters Returns onFetchSource()Parameters Returns onList()Parameters Returns onMoveFiles()Parameters Returns onOpen()Parameters Returns onOpenFile()Parameters Returns onRenameItem()Parameters Returns onUIEvent()Parameters Returns refresh()Returns