@mutka-explorer/module 1.0.0-rc.2

package/README.md

@@ -0,0 +1,72 @@
+# @mutka-explorer/module
+
+TypeScript types for authoring [Mutka](https://github.com/ilianAZZ/mutka) modules.
+
+A Mutka module is a single self-contained ESM file that
+`export default`s a module definition. It **imports nothing at runtime** — it
+reaches the system only through the `host` object passed to `setup(host)`, and
+every `host.*` call is checked against the permissions it declares.
+
+This package ships **only type definitions** (`.d.ts`, zero runtime code). You
+`import type` from it, TypeScript erases the import at compile time, and your
+built `index.js` stays self-contained — exactly what Mutka loads.
+
+## Install
+
+```bash
+npm i -D @mutka-explorer/module
+```
+
+## Usage
+
+```ts
+import type { SandboxModuleDef } from "@mutka-explorer/module";
+
+const mod: SandboxModuleDef = {
+  id: "you.hello",
+  name: "Hello",
+  version: "1.0.0",
+  permissions: ["fs:read"],
+  commands: [
+    { id: "you.hello.count", label: "Count items", contextMenu: true, when: { selection: "any" } },
+  ],
+  setup(host) {
+    host.onCommand("you.hello.count", async (snap) => {
+      const items = await host.fs.readDir(snap.currentDirectory);
+      host.log(`${items.length} items`);
+    });
+  },
+};
+
+export default mod;
+```
+
+`host` is fully typed (`host.fs`, `host.ui`, `host.net`, `host.dialog`, …), as
+are permissions, `when` clauses, the declarative `UINode` tree, and `FormSchema`.
+
+### Build to a single file
+
+Mutka loads one ESM file with the default export intact. Bundle your TypeScript
+(and any pure-JS dependencies) down to one `index.js`, e.g. with
+[tsup](https://tsup.egoist.dev/):
+
+```bash
+tsup src/index.ts --format esm --bundle
+```
+
+> The module runs in a Web Worker with **no DOM and no native network**
+> (`fetch`/`XMLHttpRequest`/`WebSocket` are blocked). Use `host.net` for HTTP.
+> Pure-logic libraries bundle fine; DOM- or network-dependent ones do not.
+
+## What's exported
+
+Types only: `SandboxModuleDef`, `SandboxHostApi` (the `host`), `ModulePermission`,
+`SandboxCommand`, `SandboxOpenHandler`, `WhenClause`, `UINode`, `FormSchema`,
+`FileItem`, `HostSnapshot`, the contribution shapes (panels, columns, status-bar,
+file icons, discovery sources), and their supporting types.
+
+## Versioning
+
+The package version tracks the Mutka app release it was generated from, so the
+types always match a shipped host API. See the app's `docs/` for the full module
+architecture.

package/index.d.ts

@@ -0,0 +1,737 @@
+// Type definitions for @mutka-explorer/module v1.0.0-rc.2
+// Mutka module SDK — author-facing types only (no runtime code).
+// Generated from the Mutka app source; do not edit by hand.
+
+/**
+ * Permissions a module may request. A module must declare every capability it
+ * uses; the gateway (core/sandbox/gateway.ts) denies any capability whose
+ * permission is absent from the module's manifest.
+ */
+export type ModulePermission = "fs:read" | "fs:write" | "fs:temp" | "clipboard:read" | "clipboard:write" | "navigation" | "view" | "dialog" | "network:public" | "network:local" | "storage" | "secrets" | "ui" | "discovery" | "shell";
+/**
+ * A declarative entry a module contributes to the left "Places" sidebar.
+ * Serializable — crosses the worker boundary. Clicking navigates to `path`
+ * or runs `command` (provide one).
+ */
+export interface SidebarItem {
+	id: string;
+	label: string;
+	/** Icon registry key (e.g. "cloud", "folder") or an emoji. */
+	icon?: string;
+	/** Group header. Use SidebarCategories or any custom string. */
+	category?: string;
+	/** Navigate here when clicked. */
+	path?: string;
+	/** Or run this command id when clicked. */
+	command?: string;
+	/**
+	 * Show a remove (✕) affordance. Clicking it emits "sidebar:item-remove" with
+	 * this item's id — the owning module listens and updates its dynamic items.
+	 */
+	removable?: boolean;
+}
+/** A single entry returned by the Rust `read_dir` command. */
+export interface FileItem {
+	/** Filename without path, e.g. "document.pdf" */
+	name: string;
+	/** Absolute POSIX path, e.g. "/Users/ilian/Documents/document.pdf" */
+	path: string;
+	/** True if this entry is a directory */
+	isDir: boolean;
+	/** File size in bytes. 0 for directories. */
+	size: number;
+	/** Last-modified timestamp in UNIX seconds */
+	modified: number;
+	/** Lowercase extension without dot, e.g. "pdf". Undefined for dirs or extensionless files. */
+	extension?: string;
+	/** True for dotfiles (name starts with "."). The UI dims these like Finder. */
+	isHidden: boolean;
+	/**
+	 * True if this entry is a symbolic link. `isDir`/`size`/`modified` reflect the
+	 * link's TARGET (Rust follows it), so a link to a folder navigates in-app.
+	 */
+	isSymlink: boolean;
+	/**
+	 * True if this directory is a macOS package/bundle (.app, .bundle, …). Though
+	 * `isDir` is true, the UI launches it like a file and shows its real icon
+	 * instead of navigating into it.
+	 */
+	isPackage: boolean;
+	/**
+	 * True if this folder carries a custom Finder icon (an "Icon\r" file). Still
+	 * navigable, but the UI shows its real icon instead of the generic folder one.
+	 */
+	hasCustomIcon: boolean;
+}
+export interface ClipboardState {
+	/** Items currently held in the clipboard */
+	items: FileItem[];
+	/** Whether items were copied or cut. Null when clipboard is empty. */
+	operation: "copy" | "cut" | null;
+}
+/** An application able to open a file — returned by the `sys.appsForFile` capability. */
+export interface AppInfo {
+	/** Display name, e.g. "Visual Studio Code". */
+	name: string;
+	/** Absolute bundle path, e.g. "/Applications/Visual Studio Code.app". */
+	path: string;
+	/** The app's icon as a base64 PNG data-URI (empty if unavailable). */
+	icon: string;
+	/** True for the app macOS would use by default for this file. */
+	isDefault: boolean;
+}
+declare const MENU_ZONES: readonly [
+	"file",
+	"background",
+	"breadcrumb",
+	"sidebar"
+];
+export type MenuZone = (typeof MENU_ZONES)[number];
+export type WhenSelection = "any" | "none" | "some" | "single" | "multiple" | "singleDir" | "singleFile" | "files" | "dirs";
+export interface WhenClause {
+	selection?: WhenSelection;
+	/** Gate on clipboard contents (for a Paste command). */
+	clipboard?: "hasItems";
+	/** Only when EVERY selected item's file name is one of these (e.g. ["index.js"]
+	 *  to show an action only on module files). Case-sensitive. */
+	fileNames?: string[];
+	/** Only when EVERY selected item's extension is one of these (lowercased, no dot,
+	 *  e.g. ["js"]). */
+	extensions?: string[];
+}
+export interface SandboxCommand {
+	id: string;
+	label: string;
+	icon?: string;
+	shortcut?: string;
+	contextMenu?: boolean;
+	contextMenuCategory?: string;
+	/**
+	 * Which UI regions this command appears in when right-clicked. Omit to use the
+	 * default (file rows + empty file-list background). Use e.g. ["breadcrumb"] to
+	 * target the path bar, or ["sidebar"] for a panel. See core/menu/menuZone.ts.
+	 */
+	contextMenuZones?: MenuZone[];
+	when?: WhenClause;
+}
+export interface SandboxOpenMatch {
+	isDir?: boolean;
+	extensions?: string[];
+	/** Match macOS packages/bundles (.app, …). Use `false` to exclude them. */
+	isPackage?: boolean;
+}
+export interface SandboxOpenHandler {
+	id: string;
+	priority?: number;
+	match: SandboxOpenMatch;
+	handler: string;
+}
+/** Gate a column on the current directory. Omit a field to not constrain it. */
+export interface ColumnDirMatch {
+	/** Show only under these path prefixes (a leading "~" is expanded host-side). */
+	pathPrefixes?: string[];
+	/** …or when the directory path contains one of these substrings. */
+	pathContains?: string[];
+}
+/** What a single cell renders — plain data, shown via text / <img src> only. */
+export interface ColumnCell {
+	/** Primary text of the cell. */
+	text?: string;
+	/** A data:image/...;base64 icon (injection-safe, rendered via <img src>). */
+	icon?: string;
+	/** Text colour — MUST be a `var(--...)` token; anything else is dropped. */
+	tint?: string;
+	/** A short pill (e.g. "⤓", "3"). */
+	badge?: string;
+}
+export interface ColumnContribution {
+	/** Unique column id, e.g. "com.exif.dimensions". */
+	id: string;
+	/** Header label. */
+	label: string;
+	/** Default width in px (defaults to 100). */
+	width?: number;
+	/** Cell alignment. */
+	align?: "start" | "end";
+	/** Directory-level gate. Omit to show in every directory. */
+	dirMatch?: ColumnDirMatch;
+	/** Item-level gate. Omit to compute a value for every item. */
+	cellMatch?: SandboxOpenMatch;
+}
+export interface FileIconContribution {
+	/** Extensions (without dot, case-insensitive) this icon applies to, e.g. ["pdf"]. */
+	extensions: string[];
+	/** The icon image as a data:image/...;base64,... URI. */
+	image: string;
+}
+/** Text emphasis for a `text` node. */
+export type UITextWeight = "normal" | "medium" | "bold";
+/** Relative text size for a `text` node. */
+export type UITextSize = "sm" | "md" | "lg";
+/** Visual intent for a `button` node. */
+export type UIButtonVariant = "default" | "primary" | "danger";
+/** One row in a `list` node — clicking it fires `action` with `value` (or `id`). */
+export interface UIListItem {
+	id: string;
+	label: string;
+	detail?: string;
+	/** Icon registry key or emoji. */
+	icon?: string;
+	/** Text colour — MUST be a `var(--…)` token; anything else is dropped. */
+	tint?: string;
+	/** UI-event handler id fired on click (registered via host.onUIEvent). */
+	action?: string;
+	/** Payload passed to the handler; defaults to the item's `id`. */
+	value?: unknown;
+}
+/** A single declarative UI node. Rendered host-side, never as innerHTML. */
+export type UINode = {
+	type: "vstack";
+	gap?: number;
+	children: UINode[];
+} | {
+	type: "hstack";
+	gap?: number;
+	align?: "start" | "center" | "end";
+	children: UINode[];
+} | {
+	type: "text";
+	text: string;
+	tint?: string;
+	weight?: UITextWeight;
+	size?: UITextSize;
+	muted?: boolean;
+} | {
+	type: "row";
+	label: string;
+	value?: string;
+	icon?: string;
+} | {
+	type: "button";
+	label: string;
+	action: string;
+	icon?: string;
+	variant?: UIButtonVariant;
+	value?: unknown;
+} | {
+	type: "list";
+	items: UIListItem[];
+} | {
+	type: "badge";
+	text: string;
+	tint?: string;
+} | {
+	type: "icon";
+	name: string;
+} | {
+	type: "divider";
+} | {
+	type: "spacer";
+	size?: number;
+}
+/** An image — `src` MUST be a data:image/… URI (rendered via <img src> only). */
+ | {
+	type: "image";
+	src: string;
+	alt?: string;
+}
+/** A form built from a JSON-Schema subset; submitting fires `action` with the values object. */
+ | {
+	type: "form";
+	schema: FormSchema;
+	action: string;
+	submitLabel?: string;
+};
+/** Renders as: text input, number input, checkbox, or (with `enum`) a select. */
+export interface FormProperty {
+	type: "string" | "number" | "integer" | "boolean";
+	title?: string;
+	description?: string;
+	default?: string | number | boolean;
+	/** Allowed values → rendered as a select. */
+	enum?: string[];
+	/** Optional labels parallel to `enum` (falls back to the value). */
+	enumLabels?: string[];
+	/** String rendering hint. `textarea` → multiline, `password` → masked. */
+	format?: "password" | "textarea" | "email" | "path";
+	minimum?: number;
+	maximum?: number;
+	minLength?: number;
+	maxLength?: number;
+}
+export interface FormSchema {
+	type: "object";
+	properties: Record<string, FormProperty>;
+	/** Keys that must be non-empty before the form can submit. */
+	required?: string[];
+}
+export interface PanelContribution {
+	/** Surface id — render into it via host.ui.render(id, node). */
+	id: string;
+	/** Tab tooltip / accessible label. */
+	title: string;
+	/** Icon registry key or emoji shown in the sidebar tab strip. */
+	icon: string;
+	/** Preferred edge. Defaults to "right". */
+	side?: "left" | "right";
+	/** Default panel width in px (clamped 180–480). */
+	defaultWidth?: number;
+}
+export interface SettingsSectionContribution {
+	/** Surface id — render into it via host.ui.render(id, node). */
+	id: string;
+	/** Section header shown in the Settings panel. */
+	title: string;
+}
+/** What happens when a status-bar item is clicked. */
+export type StatusBarAction = {
+	command: string;
+} | {
+	popover: string;
+};
+export interface StatusBarItem {
+	/** Unique within the owning module. */
+	id: string;
+	text?: string;
+	/** Icon registry key or emoji. */
+	icon?: string;
+	/** Text/icon colour — MUST be a `var(--…)` token; anything else is dropped. */
+	tint?: string;
+	/** A short pill (e.g. "↑2", "3"). */
+	badge?: string;
+	tooltip?: string;
+	/** Which end of the bar. Defaults to "right". */
+	side?: "left" | "right";
+	onClick?: StatusBarAction;
+}
+/** Who made a module, for display in the Modules UI. All fields optional. */
+export interface ModuleAuthor {
+	/** Display name shown on the card. */
+	name?: string;
+	/** GitHub login (user or org). Drives the avatar + profile link. When the
+	 *  module is installed from a GitHub repo and this is omitted, the catalog
+	 *  defaults it to the repo owner. */
+	github?: string;
+}
+interface SandboxManifest {
+	id: string;
+	name: string;
+	version: string;
+	description?: string;
+	/** Display image: a `data:image/...` URI or an `https://` URL. Rendered via
+	 *  <img src> only, so it is injection-safe. */
+	icon?: string;
+	/** Author shown in the Modules UI (avatar + profile link). */
+	author?: ModuleAuthor;
+	/** Free-form tags for discovery filtering (e.g. ["files", "git"]). */
+	tags?: string[];
+	permissions: ModulePermission[];
+	commands: SandboxCommand[];
+	openHandlers: SandboxOpenHandler[];
+	/** Declarative left-sidebar entries. */
+	sidebarItems: SidebarItem[];
+	/** URI schemes this module provides a virtual file system for. */
+	fileSystemProviders: string[];
+	/** File-type icon overrides (by extension) this module contributes. */
+	fileIcons: FileIconContribution[];
+	/** Custom list-view columns this module contributes. */
+	columns: ColumnContribution[];
+	/** Declarative side-pane panels this module contributes. */
+	panels: PanelContribution[];
+	/** Declarative settings sections this module contributes. */
+	settingsSections: SettingsSectionContribution[];
+	/** Module-discovery sources this module contributes (served over host RPC). */
+	discoverySources: DiscoverySourceDecl[];
+	/** Buttons this module adds to the Modules overlay (Browse tab). */
+	moduleManagerButtons: ModuleManagerButton[];
+}
+/** A button a module contributes to the Modules overlay. Clicking it runs the
+ *  module's host.onUIEvent(id, …) handler (no payload). */
+export interface ModuleManagerButton {
+	id: string;
+	label: string;
+	/** Optional icon key from the icon registry (unknown keys render as nothing). */
+	icon?: string;
+}
+/** A discovery source a module declares (and serves via host.onDiscover/onFetchSource). */
+export interface DiscoverySourceDecl {
+	id: string;
+	label: string;
+}
+/** Serializable snapshot of app state handed to a command when it runs. */
+export interface HostSnapshot {
+	selectedItems: FileItem[];
+	/** The current directory's visible items, in display order (sorted/filtered). */
+	orderedItems: FileItem[];
+	currentDirectory: string;
+	clipboard: ClipboardState;
+}
+/** The file-system provider operations a module may implement (mirrors hostProxy). */
+export type ProviderMethod = "list" | "openFile" | "createFolder" | "createFile" | "deleteItem" | "renameItem" | "copyFiles" | "moveFiles";
+/** The discovery operations a module may implement (mirrors hostProxy). */
+export type DiscoveryMethod = "discover" | "fetchSource";
+/** Author display info, resolved to concrete avatar/profile URLs by a source. */
+export interface CatalogAuthor {
+	name?: string;
+	/** GitHub login (user or org). */
+	github?: string;
+	avatarUrl?: string;
+	profileUrl?: string;
+}
+/**
+ * A module surfaced by a discovery source — metadata only, no code yet. The core
+ * fetches the source (via the source's `fetchSource(ref)`) and probes it at
+ * install. `permissions` are advisory (filtering/preview); the authoritative set
+ * comes from probing the fetched source.
+ */
+export interface ModuleListing {
+	/** Discovery source that surfaced this (its declared `id`). */
+	sourceId: string;
+	/** Opaque, source-encoded locator passed back to `fetchSource`. */
+	ref: string;
+	id: string;
+	name: string;
+	version: string;
+	description?: string;
+	/** Display image (data: URI or https URL). */
+	icon?: string;
+	author?: CatalogAuthor | null;
+	permissions: ModulePermission[];
+	tags?: string[];
+	/** External page for the module (repo URL, etc.). */
+	homepageUrl?: string;
+}
+/** Filters + pagination passed to a discovery source. */
+export interface DiscoveryQuery {
+	text?: string;
+	permissions?: ModulePermission[];
+	tags?: string[];
+	extension?: string;
+	/** 1-based page number. */
+	page?: number;
+	perPage?: number;
+}
+/** A page of discovery results. */
+export interface DiscoveryResult {
+	listings: ModuleListing[];
+	/** Next page number, or undefined when there are no more results. */
+	nextPage?: number;
+}
+export type CommandHandler = (snapshot: HostSnapshot) => void | Promise<void>;
+export type OpenHandler = (item: FileItem) => void | Promise<void>;
+export type ColumnProvider = (item: FileItem) => ColumnCell | null | Promise<ColumnCell | null>;
+export type EventHandler = (payload: unknown) => void;
+export type ListHandler = (path: string) => FileItem[] | Promise<FileItem[]>;
+export type OpenFileHandler = (path: string) => void | Promise<void>;
+export type WriteHandler = (path: string) => void | Promise<void>;
+export type RenameProviderHandler = (from: string, to: string) => void | Promise<void>;
+export type TransferHandler = (paths: string[], dest: string) => void | Promise<void>;
+export type ProviderHandler = ListHandler | OpenFileHandler | WriteHandler | RenameProviderHandler | TransferHandler;
+/** A UI-event handler (button/list/form interaction) registered via host.onUIEvent. */
+export type UIEventHandler = (value: unknown) => void | Promise<void>;
+/** A discovery source's two handlers, registered via host.onDiscover / onFetchSource. */
+export type DiscoverHandler = (query: DiscoveryQuery) => Promise<DiscoveryResult>;
+export type FetchSourceHandler = (ref: string) => Promise<string>;
+/** Options for host.net.request — a host-proxied HTTP call (bypasses CORS). */
+export interface NetRequestOptions {
+	url: string;
+	method?: string;
+	headers?: Record<string, string>;
+	/** Text (UTF-8) or raw bytes (e.g. from host.fs.readBytes for an upload). */
+	body?: string | Uint8Array;
+}
+/** What host.net.request resolves to. */
+export interface NetResponse {
+	status: number;
+	headers: Record<string, string>;
+	/** Body decoded as UTF-8 text (JSON/XML/text APIs). */
+	body: string;
+	/** Body as raw bytes (binary downloads). */
+	bytes: Uint8Array;
+}
+/** What host.board.readFiles resolves to — the pasteboard's pending file list. */
+export interface ClipboardFiles {
+	paths: string[];
+	operation: "copy" | "cut";
+}
+/** Whether a file's data is materialized locally or still cloud-only. */
+export type CloudStatus = "downloaded" | "cloud";
+export interface SandboxHostApi {
+	fs: {
+		/** List a directory's entries (works for local paths and provider schemes). */
+		readDir(path: string): Promise<FileItem[]>;
+		/** Open an item with the system default handler. */
+		openItem(path: string): Promise<void>;
+		/** Read a file's raw bytes. */
+		readBytes(path: string): Promise<Uint8Array>;
+		/** Whether a file is materialized locally or cloud-only. */
+		cloudStatus(path: string): Promise<CloudStatus>;
+		copyFiles(paths: string[], dest: string): Promise<void>;
+		moveFiles(paths: string[], dest: string): Promise<void>;
+		deleteItem(path: string): Promise<void>;
+		renameItem(from: string, to: string): Promise<void>;
+		createFile(path: string): Promise<void>;
+		createFolder(path: string): Promise<void>;
+	};
+	board: {
+		/** Read the pasteboard's pending file list, or null if it holds no files. */
+		readFiles(): Promise<ClipboardFiles | null>;
+		writeFiles(paths: string[], operation: "copy" | "cut"): Promise<void>;
+	};
+	nav: {
+		navigate(path: string): Promise<void>;
+		goBack(): Promise<void>;
+		goForward(): Promise<void>;
+		goUp(): Promise<void>;
+	};
+	tabs: {
+		openTab(path: string): Promise<void>;
+		openTabInBackground(path: string): Promise<void>;
+		/** Whether this module's runtime is bound to the active tab. */
+		isActive(): Promise<boolean>;
+	};
+	/** Drive view state: the current selection and the active sort. */
+	selection: {
+		set(items: FileItem[]): Promise<void>;
+	};
+	view: {
+		setSort(sort: {
+			key: string;
+			dir: "asc" | "desc";
+		}): Promise<void>;
+		toggleSort(key: string): Promise<void>;
+		/** Toggle whether hidden/system files (dotfiles) are shown. */
+		toggleHidden(): Promise<void>;
+		/** Explicitly set whether hidden/system files are shown. */
+		setShowHidden(value: boolean): Promise<void>;
+	};
+	dialog: {
+		/** Text-input dialog. Resolves with the entered string, or null if cancelled. */
+		prompt(options: {
+			message: string;
+			placeholder?: string;
+			defaultValue?: string;
+		}): Promise<string | null>;
+		/** Yes/no dialog. Resolves true (confirm) or false (cancel). */
+		confirm(options: {
+			message: string;
+			detail?: string;
+			destructive?: boolean;
+		}): Promise<boolean>;
+		/** Show a single-choice list. Resolves with the chosen option's value, or null. */
+		choose(options: {
+			message: string;
+			options: {
+				label: string;
+				value: string;
+				detail?: string;
+				icon?: string;
+			}[];
+		}): Promise<string | null>;
+		/** Open a Mutka file browser to pick one file. Resolves with its path, or null. */
+		pickFile(options?: {
+			title?: string;
+			initialDir?: string;
+			fileNames?: string[];
+		}): Promise<string | null>;
+	};
+	/** The app's home directory store (distinct from the OS home, sys.homeDir). */
+	home: {
+		/** Read the current app home directory. */
+		get(): Promise<string>;
+		/** Set the app home directory (any module may override it). */
+		set(path: string): Promise<void>;
+	};
+	/** Toggle the settings overlay open/closed. */
+	settings: {
+		toggle(): Promise<void>;
+	};
+	/** Render declarative UI (a serializable UINode tree). Gated by `ui`. */
+	ui: {
+		/** Render/replace the UINode shown in a named surface (panel/settings/popover). */
+		render(surfaceId: string, node: UINode): Promise<void>;
+		/** Clear a surface so it renders empty. */
+		clear(surfaceId: string): Promise<void>;
+		/** Open a modal with `node`, or pass null to close the current one. */
+		modal(node: UINode | null): Promise<void>;
+	};
+	/** Bottom status-bar items (e.g. a git widget). Gated by `ui`. */
+	statusbar: {
+		/** Add or replace one status-bar item (keyed by its id). */
+		set(item: StatusBarItem): Promise<void>;
+		/** Remove a status-bar item by id. */
+		remove(itemId: string): Promise<void>;
+	};
+	sys: {
+		/** The OS home directory. */
+		homeDir(): Promise<string>;
+		/** The last visited local directory, or null on first run. */
+		lastDir(): Promise<string | null>;
+		/** Write bytes to a temp file and return its path (Uint8Array, or a base64
+		 * string for a Finder-dropped file). Gated by `fs:temp`. */
+		writeTempFile(filename: string, data: string | Uint8Array): Promise<string>;
+		quickLook(path: string): Promise<void>;
+		/** Refresh an already-open Quick Look panel to preview `path` (else no-op). */
+		previewUpdate(path: string): Promise<void>;
+		/** Apps that can open a file (Launch Services), default flagged + first. */
+		appsForFile(path: string): Promise<AppInfo[]>;
+		/** Open a file with a specific application bundle path. */
+		openWith(path: string, appPath: string): Promise<void>;
+		/** Start a native OS file drag of `paths`, previewed by `icon` (data-URI/path). */
+		startDrag(paths: string[], icon?: string): Promise<void>;
+	};
+	/**
+	 * 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.
+	 */
+	net: {
+		request(options: NetRequestOptions): Promise<NetResponse>;
+	};
+	/** Module tooling (gated by the `discovery` permission). */
+	modules: {
+		/** Validate an ESM source in a throwaway worker and return its manifest. */
+		probe(source: string): Promise<SandboxManifest>;
+		/** Propose a module source for install — opens the permission-review dialog so
+		 *  the user approves before anything is written. */
+		install(source: string): Promise<void>;
+	};
+	/** Per-module persisted config (gated by the `storage` permission). */
+	config: {
+		/** Read a stored value, or null if the key was never set. */
+		get(key: string): Promise<string | null>;
+		set(key: string, value: string): Promise<void>;
+	};
+	/** Per-module credentials in the macOS Keychain (gated by `secrets`). */
+	secrets: {
+		/** Read a stored credential, or null if absent. */
+		get(key: string): Promise<string | null>;
+		set(key: string, value: string): Promise<void>;
+		delete(key: string): Promise<void>;
+	};
+	/** Re-read the current directory after a mutation. */
+	refresh(): Promise<void>;
+	/** Run an item through the open-resolution pipeline (keyboard double-click). */
+	activate(item: FileItem): Promise<void>;
+	/** Register the function that runs when one of this module's commands fires. */
+	onCommand(commandId: string, handler: CommandHandler): void;
+	/** Register the function that runs when an item matches one of this module's open handlers. */
+	onOpen(handlerId: string, handler: OpenHandler): void;
+	/** Register the value provider for one of this module's custom columns. */
+	onColumn(columnId: string, provider: ColumnProvider): void;
+	/** Register a handler fired when a button/list/form in this module's UI is used. */
+	onUIEvent(handlerId: string, handler: UIEventHandler): void;
+	/** Register the directory-listing handler for a file system provider scheme. */
+	onList(scheme: string, handler: ListHandler): void;
+	/** Register the file-open handler for a file system provider scheme. */
+	onOpenFile(scheme: string, handler: OpenFileHandler): void;
+	/** Register the create-folder handler for a file system provider scheme. */
+	onCreateFolder(scheme: string, handler: WriteHandler): void;
+	/** Register the create-file handler for a file system provider scheme. */
+	onCreateFile(scheme: string, handler: WriteHandler): void;
+	/** Register the delete handler for a file system provider scheme. */
+	onDeleteItem(scheme: string, handler: WriteHandler): void;
+	/** Register the rename/move handler for a file system provider scheme. */
+	onRenameItem(scheme: string, handler: RenameProviderHandler): void;
+	/** Register the copy handler (sources may be local → upload, or same-scheme). */
+	onCopyFiles(scheme: string, handler: TransferHandler): void;
+	/** Register the move handler (same-scheme sources). */
+	onMoveFiles(scheme: string, handler: TransferHandler): void;
+	/** Register the discover handler for a declared discovery source. */
+	onDiscover(sourceId: string, handler: DiscoverHandler): void;
+	/** Register the fetch-source handler for a declared discovery source. */
+	onFetchSource(sourceId: string, handler: FetchSourceHandler): void;
+	/** Replace this module's dynamic left-sidebar items (e.g. a bookmarks list). */
+	sidebar: {
+		set(items: SidebarItem[]): void;
+	};
+	/** Subscribe to a whitelisted app event. */
+	events: {
+		on(event: string, handler: EventHandler): void;
+	};
+	/** Forwarded to the host console, prefixed with the module id. */
+	log(...args: unknown[]): void;
+}
+export interface SandboxModuleDef {
+	/** Unique module id, "author.name" convention. */
+	id: string;
+	name?: string;
+	version?: string;
+	description?: string;
+	/**
+	 * Display image for the Modules UI: a `data:image/...` URI (self-contained) or
+	 * an `https://` URL. Rendered via <img src> only, so it is injection-safe.
+	 */
+	icon?: string;
+	/**
+	 * Who made this module — shown in the Modules UI as an avatar + profile link.
+	 * `author.github` (a user or org login) drives the avatar; when omitted and the
+	 * module is installed from a GitHub repo, it defaults to the repo owner.
+	 */
+	author?: ModuleAuthor;
+	/** Free-form tags for discovery filtering, e.g. ["files", "git", "viewer"]. */
+	tags?: string[];
+	/** Every privileged capability this module uses MUST be listed here. */
+	permissions?: ModulePermission[];
+	/** Commands surfaced into the app's menus / toolbar. */
+	commands?: SandboxCommand[];
+	/** Open handlers (double-click behavior) by item type. */
+	openHandlers?: SandboxOpenHandler[];
+	/** Declarative entries in the left "Places" sidebar, grouped by category. */
+	sidebarItems?: SidebarItem[];
+	/**
+	 * File-type icon overrides: ship your own logo (a base64 data:image/... URI)
+	 * for a set of extensions, replacing the native macOS icon. Rendered via
+	 * <img src> only, so it's injection-safe.
+	 */
+	fileIcons?: FileIconContribution[];
+	/**
+	 * Custom list-view columns. Each column declares declarative applicability
+	 * (which directories it shows in, which items get a value) and its value is
+	 * produced by a provider registered in setup via host.onColumn(id, handler).
+	 */
+	columns?: ColumnContribution[];
+	/**
+	 * Declarative side-pane panels. Each declares a tab (id/title/icon/side); fill
+	 * it from setup with host.ui.render(id, node) — a serializable UINode tree the
+	 * host renders natively. Buttons/lists/forms in the tree fire UI-event handlers
+	 * registered via host.onUIEvent(id, handler). Requires the `ui` permission.
+	 */
+	panels?: PanelContribution[];
+	/**
+	 * Declarative settings sections shown inside the app's Settings panel. Same
+	 * model as `panels`: declare {id, title}, fill via host.ui.render(id, node).
+	 * Requires the `ui` permission.
+	 */
+	settingsSections?: SettingsSectionContribution[];
+	/**
+	 * URI schemes this module provides a virtual file system for (e.g. "nextcloud").
+	 * Register the handlers in setup with host.onList(scheme, …) / host.onOpenFile(…).
+	 * Works in BOTH runtimes: built-ins call providers in-process; community modules
+	 * serve each op over a worker round-trip. Note the worker realm has no DOM APIs
+	 * (DOMParser, etc.), so providers needing those should ship as built-ins.
+	 */
+	fileSystemProviders?: string[];
+	/**
+	 * Module-discovery sources this module provides (e.g. a GitLab or local-folder
+	 * source). Declare `{ id, label }` here, then in setup serve them with
+	 * host.onDiscover(id, …) and host.onFetchSource(id, …). The id appears in the
+	 * Modules "Browse" tab; results are validated + installed by the core. Gated by
+	 * the `discovery` permission (plus whatever the fetch needs, e.g. `network:public`).
+	 */
+	discoverySources?: DiscoverySourceDecl[];
+	/**
+	 * Buttons to add to the Modules overlay (Browse tab). Declare `{ id, label, icon? }`
+	 * and register the click handler with `host.onUIEvent(id, …)`. Lets a module
+	 * surface an action there (e.g. an "Import local file" installer button).
+	 */
+	moduleManagerButtons?: ModuleManagerButton[];
+	/**
+	 * Runs once after load. Register command/open handlers and event subscriptions
+	 * here. Reaches the system only through `host.*` (each gated by permissions).
+	 */
+	setup?: (host: SandboxHostApi) => void | Promise<void>;
+}
+
+export {};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mutka-explorer/module",
+  "version": "1.0.0-rc.2",
+  "description": "TypeScript types for authoring Mutka modules — the SandboxModuleDef shape plus the full host API. Types only, no runtime code.",
+  "license": "MIT",
+  "author": "Mutka contributors",
+  "homepage": "https://github.com/ilianAZZ/mutka",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ilianAZZ/mutka.git",
+    "directory": "packages/module-sdk"
+  },
+  "keywords": [
+    "mutka",
+    "module",
+    "types",
+    "sdk",
+    "file-explorer"
+  ],
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts"
+    }
+  },
+  "files": [
+    "index.d.ts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepublishOnly": "node build.mjs"
+  },
+  "devDependencies": {
+    "dts-bundle-generator": "^9.5.1",
+    "typescript": "^5.5.3"
+  }
+}