@dotdirfm/ui 0.1.1

package/dist/lib/features/bridge/index.d.ts

@@ -0,0 +1,209 @@
+export type EntryKind = "file" | "directory" | "symlink" | "block_device" | "char_device" | "named_pipe" | "socket" | "whiteout" | "door" | "event_port" | "unknown";
+export interface FsRawEntry {
+    name: string;
+    kind: EntryKind;
+    size: number;
+    mtimeMs: number;
+    mode: number;
+    nlink: number;
+    hidden: boolean;
+    /** Populated only when kind === 'symlink'. Omitted when not a symlink. */
+    linkTarget?: string;
+}
+export type FsChangeType = "appeared" | "disappeared" | "modified" | "errored" | "unknown";
+export interface FsChangeEvent {
+    watchId: string;
+    type: FsChangeType;
+    name: string | null;
+}
+export type ConflictPolicy = "ask" | "overwrite" | "skip" | "rename" | "append" | "onlyNewer";
+export type SymlinkMode = "smart" | "alwaysLink" | "alwaysTarget";
+export interface CopyOptions {
+    conflictPolicy: ConflictPolicy;
+    copyPermissions: boolean;
+    copyXattrs: boolean;
+    sparseFiles: boolean;
+    useCow: boolean;
+    symlinkMode: SymlinkMode;
+    disableWriteCache: boolean;
+}
+export type ConflictResolution = {
+    type: "overwrite";
+} | {
+    type: "skip";
+} | {
+    type: "rename";
+    newName: string;
+} | {
+    type: "overwriteAll";
+} | {
+    type: "skipAll";
+} | {
+    type: "cancel";
+};
+export interface CopyProgress {
+    bytesCopied: number;
+    bytesTotal: number;
+    filesDone: number;
+    filesTotal: number;
+    currentFile: string;
+}
+export type CopyProgressEvent = {
+    copyId: number;
+    event: {
+        kind: "progress";
+        bytesCopied: number;
+        bytesTotal: number;
+        filesDone: number;
+        filesTotal: number;
+        currentFile: string;
+    } | {
+        kind: "conflict";
+        src: string;
+        dest: string;
+        srcSize: number;
+        srcMtimeMs: number;
+        destSize: number;
+        destMtimeMs: number;
+    } | {
+        kind: "done";
+        filesDone: number;
+        bytesCopied: number;
+    } | {
+        kind: "error";
+        message: string;
+    };
+};
+export interface MoveOptions {
+    conflictPolicy: ConflictPolicy;
+}
+export type MoveProgressEvent = {
+    moveId: number;
+    event: {
+        kind: "progress";
+        bytesCopied: number;
+        bytesTotal: number;
+        filesDone: number;
+        filesTotal: number;
+        currentFile: string;
+    } | {
+        kind: "conflict";
+        src: string;
+        dest: string;
+        srcSize: number;
+        srcMtimeMs: number;
+        destSize: number;
+        destMtimeMs: number;
+    } | {
+        kind: "done";
+        filesDone: number;
+        bytesCopied: number;
+    } | {
+        kind: "error";
+        message: string;
+    };
+};
+export type DeleteProgressEvent = {
+    deleteId: number;
+    event: {
+        kind: "progress";
+        filesDone: number;
+        currentFile: string;
+    } | {
+        kind: "done";
+        filesDone: number;
+    } | {
+        kind: "error";
+        message: string;
+    };
+};
+export interface PtyLaunchInfo {
+    ptyId: number;
+    cwd: string;
+    shell: string;
+}
+export type CwdEscapeMode = "posix" | "powershell" | "cmd";
+export interface TerminalProfile {
+    id: string;
+    label: string;
+    shell: string;
+    hiddenCdTemplate: string;
+    cwdEscape: CwdEscapeMode;
+    lineEnding: "\n" | "\r\n";
+    spawnArgs: string[];
+}
+export interface FspEntry {
+    name: string;
+    kind: "file" | "directory";
+    size?: number;
+    mtimeMs?: number;
+}
+export interface Bridge {
+    fs: {
+        entries(dirPath: string): Promise<FsRawEntry[]>;
+        stat(filePath: string): Promise<{
+            size: number;
+            mtimeMs: number;
+        }>;
+        exists(filePath: string): Promise<boolean>;
+        readFile(filePath: string): Promise<ArrayBuffer>;
+        open(filePath: string): Promise<number>;
+        read(fd: number, offset: number, length: number): Promise<ArrayBuffer>;
+        close(fd: number): Promise<void>;
+        watch(watchId: string, dirPath: string): Promise<boolean>;
+        unwatch(watchId: string): Promise<void>;
+        onFsChange(callback: (event: FsChangeEvent) => void): () => void;
+        writeFile(filePath: string, data: string): Promise<void>;
+        writeBinaryFile(filePath: string, data: Uint8Array): Promise<void>;
+        createDir?(dirPath: string): Promise<void>;
+        moveToTrash(paths: string[]): Promise<void>;
+        copy: {
+            start(sources: string[], destDir: string, options: CopyOptions): Promise<number>;
+            cancel(copyId: number): Promise<void>;
+            resolveConflict(copyId: number, resolution: ConflictResolution): Promise<void>;
+            onProgress(callback: (event: CopyProgressEvent) => void): () => void;
+        };
+        move: {
+            start(sources: string[], destDir: string, options: MoveOptions): Promise<number>;
+            cancel(moveId: number): Promise<void>;
+            resolveConflict(moveId: number, resolution: ConflictResolution): Promise<void>;
+            onProgress(callback: (event: MoveProgressEvent) => void): () => void;
+        };
+        delete: {
+            start(paths: string[]): Promise<number>;
+            cancel(deleteId: number): Promise<void>;
+            onProgress(callback: (event: DeleteProgressEvent) => void): () => void;
+        };
+        rename: {
+            rename(source: string, newName: string): Promise<void>;
+        };
+    };
+    pty: {
+        spawn(cwd: string, shellPath: string, options?: {
+            spawnArgs?: string[];
+        }): Promise<PtyLaunchInfo>;
+        write(ptyId: number, data: string): Promise<void>;
+        resize(ptyId: number, cols: number, rows: number): Promise<void>;
+        close(ptyId: number): Promise<void>;
+        onData(callback: (ptyId: number, data: string | Uint8Array) => void): () => void;
+        onExit(callback: (ptyId: number) => void): () => void;
+        setShellIntegrations?(integrations: Record<string, {
+            script: string;
+            scriptArg: boolean;
+        }>): Promise<void>;
+    };
+    utils: {
+        getHomePath(): Promise<string>;
+        getEnv(): Promise<Record<string, string>>;
+    };
+    theme: {
+        get(): Promise<string>;
+        onChange(callback: (theme: string) => void): () => void;
+    };
+    onReconnect?(callback: () => void): () => void;
+    fsProvider?: {
+        load(wasmPath: string): Promise<void>;
+        listEntries(wasmPath: string, containerPath: string, innerPath: string): Promise<FspEntry[]>;
+        readFileRange(wasmPath: string, containerPath: string, innerPath: string, offset: number, length: number): Promise<ArrayBuffer>;
+    };
+}

package/dist/lib/features/bridge/useBridge.d.ts

@@ -0,0 +1,9 @@
+import { Bridge } from '.';
+export declare const bridgeAtom: import('jotai').PrimitiveAtom<Bridge | null> & {
+    init: Bridge | null;
+};
+export declare function useBridge(): Bridge;
+export declare function BridgeProvider({ bridge, children }: {
+    bridge: Bridge;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/lib/features/commands/builtInCommandContributions.d.ts

@@ -0,0 +1,2 @@
+import { CommandContribution } from './commands';
+export declare const builtInCommandContributions: CommandContribution[];

package/dist/lib/features/commands/commands.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Command System
+ *
+ * VS Code compatible command registry with support for:
+ * - Command registration and execution
+ * - Keyboard shortcuts (keybindings) with layered override system
+ * - Extension-contributed commands
+ * - Command palette integration
+ *
+ * Keybinding layers (later layers override earlier ones):
+ * 1. Default (.dir built-in)
+ * 2. Extensions
+ * 3. User (from ~/.dotdir/keybindings.json)
+ */
+export interface Command {
+    id: string;
+    title: string;
+    shortTitle?: string;
+    category?: string;
+    icon?: string;
+}
+export interface Keybinding {
+    command: string;
+    key: string;
+    mac?: string;
+    when?: string;
+}
+export interface CommandContribution {
+    command: string;
+    title: string;
+    shortTitle?: string;
+    category?: string;
+    icon?: string;
+}
+export interface KeybindingContribution {
+    command: string;
+    key: string;
+    mac?: string;
+    when?: string;
+}
+export type KeybindingLayer = "default" | "extension" | "user";
+type CommandHandler = (...args: unknown[]) => void | Promise<void>;
+type ContextGetter = () => Record<string, unknown>;
+declare class CommandRegistry {
+    private contributions;
+    private handlers;
+    private keybindingLayers;
+    private contextGetter;
+    private contextValues;
+    private listeners;
+    private batchDepth;
+    private batchDirty;
+    beginBatch(): void;
+    endBatch(): void;
+    setContext(key: string, value: unknown): void;
+    getContext(key: string): unknown;
+    registerContributions(contributions: CommandContribution[]): () => void;
+    registerCommand(id: string, handler: CommandHandler): () => void;
+    registerKeybinding(binding: Keybinding, layer?: KeybindingLayer): () => void;
+    setLayerKeybindings(layer: KeybindingLayer, bindings: Keybinding[]): void;
+    clearLayerKeybindings(layer: KeybindingLayer): void;
+    setContextGetter(getter: ContextGetter): void;
+    executeCommand(id: string, ...args: unknown[]): Promise<void>;
+    getCommand(id: string): Command | undefined;
+    getAllCommands(): Command[];
+    getKeybindings(): Keybinding[];
+    getKeybindingsForLayer(layer: KeybindingLayer): Keybinding[];
+    getKeybindingForCommand(commandId: string): Keybinding | undefined;
+    evaluateWhen(when: string | undefined): boolean;
+    /** Evaluate a `when` expression. Supports `&&` and `||`, and `!` negation. */
+    private static evalWhen;
+    handleKeyboardEvent(e: KeyboardEvent): boolean;
+    private isMac;
+    /**
+     * Map physical key position (`KeyboardEvent.code`) to our normalized key id.
+     * Layout-independent so shortcuts work with non-Latin / non-QWERTY layouts.
+     */
+    private physicalCodeToKeyPart;
+    /**
+     * Fallback when `code` is missing (e.g. synthetic events) or unmapped: use `key` (layout-dependent).
+     */
+    private keyStringToKeyPart;
+    private eventToKeyCombo;
+    private normalizeKey;
+    onChange(callback: () => void): () => void;
+    private notifyListeners;
+}
+export declare const commandRegistry: CommandRegistry;
+export declare function formatKeybinding(binding: Keybinding): string;
+export {};

package/dist/lib/features/extensions/browserExtensionHost.d.ts

@@ -0,0 +1,36 @@
+import { LoadedExtension } from '../../../features/extensions/extensions';
+export type BrowserDisposable = {
+    dispose: () => void;
+};
+export interface BrowserExtensionKeybinding {
+    command: string;
+    key: string;
+    mac?: string;
+    when?: string;
+}
+export interface BrowserExtensionContributions {
+    keybindings?: BrowserExtensionKeybinding[];
+}
+export interface BrowserExtensionContext {
+    subscriptions: BrowserDisposable[];
+    dotdir: {
+        commands: {
+            registerCommand: (commandId: string, handler: (...args: unknown[]) => void | Promise<void>, options?: {
+                title?: string;
+                category?: string;
+                icon?: string;
+                when?: string;
+            }) => BrowserDisposable;
+            registerKeybinding: (binding: BrowserExtensionKeybinding) => BrowserDisposable;
+        };
+    };
+}
+export declare class BrowserExtensionHost {
+    private active;
+    private queue;
+    private dotdir;
+    reconcile(extensions: LoadedExtension[]): Promise<void>;
+    private activateOne;
+    private deactivateOne;
+    dispose(): Promise<void>;
+}

package/dist/lib/features/extensions/browserFsProvider.d.ts

@@ -0,0 +1,5 @@
+import { Bridge } from '../../../features/bridge';
+import { FsProviderExtensionApi } from '../../../features/extensions/extensionApi';
+export declare function loadFsProvider(bridge: Bridge, extensionDirPath: string, entry: string): Promise<FsProviderExtensionApi>;
+/** Evict all cached providers (e.g. when extensions reload). */
+export declare function clearFsProviderCache(): void;

package/dist/lib/features/extensions/extensionApi.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Shared types for the host ↔ extension iframe communication (postMessage RPC).
+ *
+ * Host exposes HostApi to the iframe.
+ * Viewer extensions expose ViewerExtensionApi; editor extensions expose EditorExtensionApi.
+ */
+export interface ViewerProps {
+    filePath: string;
+    fileName: string;
+    fileSize: number;
+    inline?: boolean;
+    /** When set (e.g. Web VFS), extension can load scripts/workers from this base URL. */
+    extensionScriptBaseUrl?: string;
+}
+/** Grammar contribution + loaded content (from host, for custom syntax highlighting). */
+export interface EditorGrammarPayload {
+    contribution: {
+        language: string;
+        scopeName: string;
+        path: string;
+        embeddedLanguages?: Record<string, string>;
+    };
+    /** Absolute path to grammar JSON file (used for lazy loading). */
+    path?: string;
+    /** Parsed TextMate grammar JSON (optional; host may lazy-load and fill it). */
+    content?: object;
+}
+export interface EditorLanguagePayload {
+    id: string;
+    aliases?: string[];
+    extensions?: string[];
+    filenames?: string[];
+}
+export interface EditorProps {
+    filePath: string;
+    fileName: string;
+    langId: string;
+    /** Extension root path (for reading package.json / grammars). */
+    extensionDirPath?: string;
+    /** All languages from loaded extensions (for Monaco registration). */
+    languages?: EditorLanguagePayload[];
+    /** All grammars with content from loaded extensions (for TextMate tokenization). */
+    grammars?: EditorGrammarPayload[];
+    /** True when shown inline (e.g. preview tab). Extensions should not steal focus when inline. */
+    inline?: boolean;
+    /** When set (e.g. Web VFS), extension can load scripts/workers from this base URL for lazy loading. */
+    extensionScriptBaseUrl?: string;
+}
+export interface ColorThemeData {
+    /** Theme kind: 'dark' or 'light'. */
+    kind: "dark" | "light";
+    /** VS Code color theme colors (e.g. 'editor.background' → '#1e1e2e'). Undefined when no VS Code theme active. */
+    colors?: Record<string, string>;
+    /** VS Code tokenColors for syntax highlighting. Undefined when no VS Code theme active. */
+    tokenColors?: unknown[];
+}
+export interface HostApi {
+    readFile(path: string): Promise<ArrayBuffer>;
+    readFileText(path: string): Promise<string>;
+    /** Read a byte range (for chunked viewing). */
+    readFileRange?(path: string, offset: number, length: number): Promise<ArrayBuffer>;
+    /** Lightweight stat for the currently viewed file. */
+    statFile?(path: string): Promise<{
+        size: number;
+        mtimeMs: number;
+    }>;
+    /** Subscribe to external changes of the currently viewed file. */
+    onFileChange?(callback: () => void): () => void;
+    writeFile(path: string, content: string): Promise<void>;
+    getTheme(): Promise<string>;
+    /** Get the active color theme data (colors + tokenColors). Returns null if no VS Code theme is active. */
+    getColorTheme?(): ColorThemeData | null;
+    /** Subscribe to theme changes. Callback fires when the color theme changes. Returns unsubscribe function. */
+    onThemeChange?(callback: (theme: ColorThemeData) => void): () => void;
+    onClose(): void;
+    /** Execute a host command (e.g. navigatePrev, navigateNext, getFileIndex). */
+    executeCommand?<T = unknown>(command: string, args?: unknown): Promise<T>;
+    /**
+     * Commands API exposed to extensions running inside the iframe.
+     * Implemented to mimic VS Code: `registerCommand(id, callback) -> Disposable`.
+     */
+    registerCommand?(commandId: string, handler: (...args: unknown[]) => void | Promise<void>): () => void;
+    /** Contribute a keybinding (extension layer). */
+    registerKeybinding?(binding: {
+        command: string;
+        key: string;
+        mac?: string;
+        when?: string;
+    }): () => void;
+    /** Oniguruma WASM binary for TextMate grammars (optional). */
+    getOnigurumaWasm?(): Promise<ArrayBuffer>;
+    /** URL to a file inside the extension dir (for lazy-loading workers). Returns blob URL. */
+    getExtensionResourceUrl?(relativePath: string): Promise<string>;
+}
+export interface ViewerExtensionApi {
+    /** Render viewer UI into the provided root. */
+    mount(root: HTMLElement, props: ViewerProps): Promise<void>;
+    unmount(): Promise<void>;
+}
+export interface EditorExtensionApi {
+    /** Render editor UI into the provided root. */
+    mount(root: HTMLElement, props: EditorProps): Promise<void>;
+    unmount(): Promise<void>;
+    setDirty?(dirty: boolean): void;
+    /** Change the editor language (e.g. for syntax highlighting). */
+    setLanguage?(langId: string): void | Promise<void>;
+}
+/** A single entry returned by an fsProvider. */
+export interface FsProviderEntry {
+    name: string;
+    type: "file" | "directory";
+    size?: number;
+    mtimeMs?: number;
+}
+/**
+ * Host API available to fsProvider extensions (injected as `window.__dotdirProviderHostApi`
+ * before the provider bundle is evaluated).
+ */
+export interface FsProviderHostApi {
+    /** Read the entire container file from the real filesystem. */
+    readFile(realPath: string): Promise<ArrayBuffer>;
+    /** Read a byte range from the real filesystem. */
+    readFileRange(realPath: string, offset: number, length: number): Promise<ArrayBuffer>;
+}
+/**
+ * API that an fsProvider extension bundle must expose.
+ *
+ * Protocol: the bundle assigns a factory to `window.__dotdirProviderReady`.
+ * The host evaluates the bundle, then calls `window.__dotdirProviderReady(hostApi)`
+ * and stores the returned object.
+ *
+ * Example bundle (CommonJS):
+ * ```js
+ * window.__dotdirProviderReady = function(hostApi) {
+ *   return {
+ *     async listEntries(containerPath, innerPath) {
+ *       const bytes = await hostApi.readFile(containerPath);
+ *       // ... parse format, return entries
+ *       return [{ name: 'README.md', type: 'file', size: 1234 }];
+ *     }
+ *   };
+ * };
+ * ```
+ */
+export interface FsProviderExtensionApi {
+    /**
+     * List the entries at `innerPath` inside the container at `containerPath`.
+     * `containerPath` is always a real filesystem path.
+     * `innerPath` is always absolute, e.g. '/' for the root.
+     */
+    listEntries(containerPath: string, innerPath: string): Promise<FsProviderEntry[]>;
+    /**
+     * Read a byte range of a file inside the container.
+     * Optional — only needed if the host should be able to open files inside containers.
+     */
+    readFileRange?(containerPath: string, innerPath: string, offset: number, length: number): Promise<ArrayBuffer>;
+}
+/** Extension calls this when loaded; host sets it before injecting the script. */
+export type DotDirHostReadyCallback = (api: ViewerExtensionApi | EditorExtensionApi) => void;
+/** Factory signature for fsProvider bundles. */
+export type FsProviderFactory = (hostApi: FsProviderHostApi) => FsProviderExtensionApi;
+declare global {
+    interface Window {
+        __dotdirHostReady?: DotDirHostReadyCallback;
+        /**
+         * Set by the fsProvider bundle. The host calls it after the bundle loads,
+         * passing the HostApi, and stores the returned FsProviderExtensionApi.
+         */
+        __dotdirProviderReady?: FsProviderFactory;
+        /**
+         * Host API exposed to isolated extensions (iframe) as a global.
+         * Extensions can call `window.dotdir.readFile(...)`, etc.
+         *
+         * We'll later publish these typings via an npm package (`dotdir`).
+         */
+        dotdir?: HostApi & {
+            commands?: {
+                registerCommand: (commandId: string, handler: (...args: unknown[]) => void | Promise<void>, options?: {
+                    title?: string;
+                    category?: string;
+                    icon?: string;
+                }) => {
+                    dispose: () => void;
+                };
+                registerKeybinding: (binding: {
+                    command: string;
+                    key: string;
+                    mac?: string;
+                    when?: string;
+                }) => {
+                    dispose: () => void;
+                };
+            };
+        };
+    }
+}