@crowdedkingdoms/crowdyjs 8.22.0 → 10.0.0

package/dist/live-coding/vfs.js

@@ -0,0 +1,174 @@
+export const DEFAULT_VFS_LIMITS = {
+    maxFiles: 32,
+    maxFileBytes: 256 * 1024,
+    maxWorkspaceBytes: 1024 * 1024,
+};
+export class VfsLimitError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = 'VFS_LIMIT';
+        this.name = 'VfsLimitError';
+    }
+}
+export class VirtualFileSystem {
+    constructor(workspaceUri = 'file:///player-mod', limits = {}) {
+        this.files = new Map();
+        this.encoder = new TextEncoder();
+        this.totalBytes = 0;
+        this.workspaceUri = workspaceUri.replace(/\/+$/, '');
+        const root = new URL(this.workspaceUri);
+        if (root.protocol !== 'file:' ||
+            root.search ||
+            root.hash ||
+            !root.pathname.startsWith('/') ||
+            root.pathname === '/') {
+            throw new Error('workspaceUri must be a non-root file URI');
+        }
+        this.limits = { ...DEFAULT_VFS_LIMITS, ...limits };
+        this.assertLimits();
+    }
+    get size() {
+        return this.files.size;
+    }
+    get bytes() {
+        return this.totalBytes;
+    }
+    open(item) {
+        const path = this.pathForUri(item.uri);
+        const previous = this.files.get(item.uri);
+        if (!previous && this.files.size >= this.limits.maxFiles) {
+            throw new VfsLimitError(`Workspace file limit is ${this.limits.maxFiles}`);
+        }
+        if (previous && item.version <= previous.version) {
+            return previous;
+        }
+        const next = this.makeDocument(item, path);
+        this.ensureFits(next.bytes, previous?.bytes ?? 0);
+        if (previous)
+            this.totalBytes -= previous.bytes;
+        this.files.set(item.uri, next);
+        this.totalBytes += next.bytes;
+        return next;
+    }
+    change(uri, version, changes) {
+        const previous = this.require(uri);
+        if (version <= previous.version) {
+            return { applied: false, document: previous };
+        }
+        let text = previous.text;
+        for (const change of changes) {
+            if (!change.range) {
+                text = change.text;
+                continue;
+            }
+            const start = offsetAt(text, change.range.start);
+            const end = offsetAt(text, change.range.end);
+            if (end < start)
+                throw new Error('Invalid content change range');
+            text = text.slice(0, start) + change.text + text.slice(end);
+        }
+        const next = this.makeDocument({
+            uri,
+            version,
+            languageId: previous.languageId,
+            text,
+        }, previous.path);
+        this.ensureFits(next.bytes, previous.bytes);
+        this.files.set(uri, next);
+        this.totalBytes += next.bytes - previous.bytes;
+        return { applied: true, document: next };
+    }
+    close(uri) {
+        const previous = this.files.get(uri);
+        if (!previous)
+            return false;
+        this.files.delete(uri);
+        this.totalBytes -= previous.bytes;
+        return true;
+    }
+    get(uri) {
+        return this.files.get(uri);
+    }
+    require(uri) {
+        const document = this.files.get(uri);
+        if (!document)
+            throw new Error(`Document is not open: ${uri}`);
+        return document;
+    }
+    documents() {
+        return [...this.files.values()];
+    }
+    clear() {
+        this.files.clear();
+        this.totalBytes = 0;
+    }
+    pathForUri(uri) {
+        let parsed;
+        try {
+            parsed = new URL(uri);
+        }
+        catch {
+            throw new Error(`Invalid document URI: ${uri}`);
+        }
+        if (parsed.protocol !== 'file:' ||
+            parsed.search ||
+            parsed.hash ||
+            !uri.startsWith(`${this.workspaceUri}/`)) {
+            throw new Error(`Document is outside ${this.workspaceUri}`);
+        }
+        const relative = decodeURIComponent(parsed.pathname.slice(new URL(this.workspaceUri).pathname.length + 1));
+        if (relative.length === 0 ||
+            relative.startsWith('/') ||
+            relative.split('/').some((part) => part === '' || part === '..' || part === '.')) {
+            throw new Error(`Unsafe document path: ${relative}`);
+        }
+        return relative;
+    }
+    makeDocument(item, path) {
+        if (!Number.isSafeInteger(item.version) || item.version < 0) {
+            throw new Error('Document version must be a non-negative safe integer');
+        }
+        const bytes = this.encoder.encode(item.text).byteLength;
+        if (bytes > this.limits.maxFileBytes) {
+            throw new VfsLimitError(`${path} is ${bytes} bytes; file limit is ${this.limits.maxFileBytes}`);
+        }
+        return Object.freeze({ ...item, path, bytes });
+    }
+    ensureFits(nextBytes, replacedBytes) {
+        const total = this.totalBytes - replacedBytes + nextBytes;
+        if (total > this.limits.maxWorkspaceBytes) {
+            throw new VfsLimitError(`Workspace is ${total} bytes; limit is ${this.limits.maxWorkspaceBytes}`);
+        }
+    }
+    assertLimits() {
+        for (const [name, value] of Object.entries(this.limits)) {
+            if (!Number.isSafeInteger(value) || value <= 0) {
+                throw new Error(`${name} must be a positive safe integer`);
+            }
+        }
+        if (this.limits.maxFileBytes > this.limits.maxWorkspaceBytes) {
+            throw new Error('maxFileBytes cannot exceed maxWorkspaceBytes');
+        }
+    }
+}
+export function offsetAt(text, position) {
+    if (!Number.isSafeInteger(position.line) ||
+        !Number.isSafeInteger(position.character) ||
+        position.line < 0 ||
+        position.character < 0) {
+        throw new Error('Invalid document position');
+    }
+    let offset = 0;
+    for (let line = 0; line < position.line; line++) {
+        const newline = text.indexOf('\n', offset);
+        if (newline < 0)
+            throw new Error('Document position is outside the text');
+        offset = newline + 1;
+    }
+    const newline = text.indexOf('\n', offset);
+    const lineEnd = newline < 0 ? text.length : newline;
+    const target = offset + position.character;
+    if (target > lineEnd)
+        throw new Error('Document position is outside the text');
+    return target;
+}

package/dist/live-coding/worker-transport.d.ts

@@ -0,0 +1,63 @@
+import { AbstractMessageReader, AbstractMessageWriter, type DataCallback, type Disposable, type Message } from 'vscode-jsonrpc';
+import { type JsonRpcMessage } from './lsp-protocol.js';
+export type { Disposable };
+export interface LanguageWorkerLike {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message' | 'error' | 'messageerror', listener: EventListener): void;
+    removeEventListener(type: 'message' | 'error' | 'messageerror', listener: EventListener): void;
+    terminate(): void;
+}
+/** Standard vscode-jsonrpc MessageReader over structured-clone worker messages. */
+export declare class WorkerMessageReader extends AbstractMessageReader {
+    private readonly worker;
+    private callback;
+    private listening;
+    constructor(worker: LanguageWorkerLike);
+    listen(callback: DataCallback): Disposable;
+    dispose(): void;
+    private readonly onMessage;
+    private readonly onMessageError;
+    private readonly onWorkerError;
+}
+/** Standard vscode-jsonrpc MessageWriter over structured-clone worker messages. */
+export declare class WorkerMessageWriter extends AbstractMessageWriter {
+    private readonly worker;
+    private disposed;
+    private errorCount;
+    constructor(worker: LanguageWorkerLike);
+    write(message: Message): Promise<void>;
+    end(): void;
+    dispose(): void;
+}
+export interface WorkerLanguageClientOptions {
+    requestTimeoutMs?: number;
+}
+/**
+ * LSP 3.17 JSON-RPC client over a real vscode-jsonrpc MessageConnection.
+ * Monaco providers adapt editor calls to this connection; transport framing,
+ * request ids, cancellation, errors, and notifications are standard JSON-RPC.
+ */
+export declare class WorkerLanguageClient {
+    private readonly worker;
+    private readonly options;
+    private readonly reader;
+    private readonly writer;
+    private readonly connection;
+    private readonly transportErrorHandlers;
+    private readonly persistentErrorHandlers;
+    private readonly readerErrorDisposable;
+    private disposed;
+    private terminateTimer;
+    constructor(worker: LanguageWorkerLike, options?: WorkerLanguageClientOptions);
+    initialize(params: unknown): Promise<unknown>;
+    request(method: string, params?: unknown): Promise<unknown>;
+    notify(method: string, params?: unknown): Promise<void>;
+    onNotification(method: string, callback: (params: unknown) => void): Disposable;
+    /** Observe worker/transport failures for editor fallback and telemetry. */
+    onError(callback: (error: Error) => void): Disposable;
+    shutdown(): void;
+    dispose(): void;
+}
+export declare function createDefaultRustLanguageWorker(): Worker;
+export declare function isWorkerLspMessage(value: unknown): value is JsonRpcMessage;
+//# sourceMappingURL=worker-transport.d.ts.map

package/dist/live-coding/worker-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-transport.d.ts","sourceRoot":"","sources":["../../src/live-coding/worker-transport.ts"],"names":[],"mappings":"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"}

package/dist/live-coding/worker-transport.js

@@ -0,0 +1,217 @@
+import { AbstractMessageReader, AbstractMessageWriter, CancellationTokenSource, } from 'vscode-jsonrpc';
+import { ExitNotification, InitializeRequest, InitializedNotification, ShutdownRequest, createProtocolConnection, } from 'vscode-languageserver-protocol';
+import { decodeJsonRpcMessage, } from './lsp-protocol.js';
+/** Standard vscode-jsonrpc MessageReader over structured-clone worker messages. */
+export class WorkerMessageReader extends AbstractMessageReader {
+    constructor(worker) {
+        super();
+        this.worker = worker;
+        this.callback = null;
+        this.listening = false;
+        this.onMessage = (event) => {
+            const decoded = decodeJsonRpcMessage(event.data);
+            if (!decoded.ok) {
+                this.fireError(new Error(decoded.message));
+                return;
+            }
+            this.callback?.(decoded.message);
+        };
+        this.onMessageError = () => {
+            this.fireError(new Error('Language worker sent an unreadable message'));
+        };
+        this.onWorkerError = (event) => {
+            const message = 'message' in event && typeof event.message === 'string'
+                ? event.message
+                : 'Language worker failed';
+            this.fireError(new Error(message));
+        };
+    }
+    listen(callback) {
+        if (this.listening)
+            throw new Error('WorkerMessageReader is already listening');
+        this.listening = true;
+        this.callback = callback;
+        this.worker.addEventListener('message', this.onMessage);
+        this.worker.addEventListener('messageerror', this.onMessageError);
+        this.worker.addEventListener('error', this.onWorkerError);
+        return { dispose: () => this.dispose() };
+    }
+    dispose() {
+        if (this.listening) {
+            this.worker.removeEventListener('message', this.onMessage);
+            this.worker.removeEventListener('messageerror', this.onMessageError);
+            this.worker.removeEventListener('error', this.onWorkerError);
+        }
+        this.listening = false;
+        this.callback = null;
+        super.dispose();
+    }
+}
+/** Standard vscode-jsonrpc MessageWriter over structured-clone worker messages. */
+export class WorkerMessageWriter extends AbstractMessageWriter {
+    constructor(worker) {
+        super();
+        this.worker = worker;
+        this.disposed = false;
+        this.errorCount = 0;
+    }
+    write(message) {
+        if (this.disposed)
+            return Promise.reject(new Error('Worker writer is disposed'));
+        try {
+            this.worker.postMessage(message);
+            return Promise.resolve();
+        }
+        catch (error) {
+            this.errorCount++;
+            this.fireError(error, message, this.errorCount);
+            return Promise.reject(error);
+        }
+    }
+    end() {
+        this.dispose();
+    }
+    dispose() {
+        this.disposed = true;
+        super.dispose();
+    }
+}
+/**
+ * LSP 3.17 JSON-RPC client over a real vscode-jsonrpc MessageConnection.
+ * Monaco providers adapt editor calls to this connection; transport framing,
+ * request ids, cancellation, errors, and notifications are standard JSON-RPC.
+ */
+export class WorkerLanguageClient {
+    constructor(worker, options = {}) {
+        this.worker = worker;
+        this.options = options;
+        this.transportErrorHandlers = new Set();
+        this.persistentErrorHandlers = new Set();
+        this.disposed = false;
+        this.terminateTimer = null;
+        this.reader = new WorkerMessageReader(worker);
+        this.writer = new WorkerMessageWriter(worker);
+        this.readerErrorDisposable = this.reader.onError((error) => {
+            for (const handler of this.transportErrorHandlers)
+                handler(error);
+            for (const handler of this.persistentErrorHandlers)
+                handler(error);
+        });
+        this.connection = createProtocolConnection(this.reader, this.writer);
+        this.connection.listen();
+    }
+    async initialize(params) {
+        const result = await this.request(InitializeRequest.type.method, params);
+        await this.notify(InitializedNotification.type.method, {});
+        return result;
+    }
+    request(method, params) {
+        if (this.disposed)
+            return Promise.reject(new Error('Language client is disposed'));
+        const cancellation = new CancellationTokenSource();
+        const timeoutMs = this.options.requestTimeoutMs ?? 3000;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const onTransportError = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                cancellation.cancel();
+                cancellation.dispose();
+                this.transportErrorHandlers.delete(onTransportError);
+                reject(error);
+            };
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                cancellation.cancel();
+                cancellation.dispose();
+                this.transportErrorHandlers.delete(onTransportError);
+                reject(new Error(`Language request timed out: ${method}`));
+            }, timeoutMs);
+            this.transportErrorHandlers.add(onTransportError);
+            const request = params === undefined
+                ? this.connection.sendRequest(method, cancellation.token)
+                : this.connection.sendRequest(method, params, cancellation.token);
+            void request
+                .then((value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                cancellation.dispose();
+                this.transportErrorHandlers.delete(onTransportError);
+                resolve(value);
+            }, (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                cancellation.dispose();
+                this.transportErrorHandlers.delete(onTransportError);
+                reject(error instanceof Error
+                    ? error
+                    : new Error('Language request failed'));
+            });
+        });
+    }
+    notify(method, params) {
+        if (this.disposed)
+            return Promise.reject(new Error('Language client is disposed'));
+        return this.connection.sendNotification(method, params);
+    }
+    onNotification(method, callback) {
+        return this.connection.onNotification(method, callback);
+    }
+    /** Observe worker/transport failures for editor fallback and telemetry. */
+    onError(callback) {
+        if (this.disposed)
+            return { dispose() { } };
+        this.persistentErrorHandlers.add(callback);
+        return {
+            dispose: () => this.persistentErrorHandlers.delete(callback),
+        };
+    }
+    shutdown() {
+        if (this.disposed || this.terminateTimer)
+            return;
+        const finish = () => {
+            if (this.disposed)
+                return;
+            void this.connection
+                .sendNotification(ExitNotification.type.method)
+                .catch(() => { })
+                .finally(() => this.dispose());
+        };
+        void this.request(ShutdownRequest.type.method)
+            .catch(() => { })
+            .finally(finish);
+        this.terminateTimer = setTimeout(finish, this.options.requestTimeoutMs ?? 3000);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.terminateTimer)
+            clearTimeout(this.terminateTimer);
+        this.terminateTimer = null;
+        this.transportErrorHandlers.clear();
+        this.persistentErrorHandlers.clear();
+        this.readerErrorDisposable.dispose();
+        this.connection.dispose();
+        this.reader.dispose();
+        this.writer.dispose();
+        this.worker.terminate();
+    }
+}
+export function createDefaultRustLanguageWorker() {
+    return new Worker(new URL('./rust-lsp.worker.js', import.meta.url), {
+        type: 'module',
+        name: 'crowdy-rust-lsp',
+    });
+}
+export function isWorkerLspMessage(value) {
+    return decodeJsonRpcMessage(value).ok;
+}

package/dist/mod-studio/controller.d.ts

@@ -0,0 +1,188 @@
+import { type PlayerCodeBrokerOptions, type PlayerCodeGridBounds } from '../player-runtime/player-code-broker.js';
+import type { PlayerComputeAPI } from '../domains/playerCompute.js';
+import type { PlayerWalletAPI } from '../domains/playerWallet.js';
+import { type ModStudioDiagnostic } from './diagnostics.js';
+import { type ModStudioFileRef, type ModStudioPairingPreference, type ModStudioProject, type ModStudioProjectMetadata, type ModStudioProjectProvider, type ModStudioProjectSummary, type ModStudioReferenceFile, type ModStudioSaveState, type ModStudioTarget } from './models.js';
+import { type ModStudioNewProjectOptions } from './starter-projects.js';
+export type ModStudioPhase = 'IDLE' | 'TESTING_DRAFT' | 'DEPLOYING_LIVE' | 'COMPILING' | 'ENABLING' | 'RUNNING' | 'COMPILE_FAILED' | 'STOPPING' | 'STOPPED' | 'PARTIAL_FAILURE' | 'ERROR';
+export type ModStudioPolledSurface = 'runs' | 'logs' | 'usage';
+export interface ModStudioRuntimeStatus {
+    phase: ModStudioPhase;
+    target?: ModStudioTarget;
+    message?: string;
+}
+export interface ModStudioUsageSnapshot {
+    hourUnitsUsed: string;
+    dayUnitsUsed: string;
+    unitsPerHour: string | null;
+    unitsPerDay: string | null;
+    compilesThisHour: number;
+    maxCompilesPerHour: number;
+    gateStatus: string;
+    gateReason: string | null;
+}
+export interface ModStudioWalletSnapshot {
+    balanceCents: string;
+    currency: string;
+}
+export interface ModStudioRun {
+    runId: string;
+    moduleName: string;
+    triggerSource: string;
+    startedAt: string;
+    durationUs: number;
+    fuelUsed: string;
+    success: boolean;
+    errorMessage?: string | null;
+}
+export interface ModStudioInvokeResult {
+    resultBase64?: string | null;
+    resultJson?: string | null;
+    fuelUsed?: string;
+    durationUs?: number;
+}
+export interface ModStudioState {
+    projects: readonly ModStudioProjectSummary[];
+    project: ModStudioProject | null;
+    personalLibraryFiles: readonly ModStudioReferenceFile[];
+    commonFiles: readonly ModStudioReferenceFile[];
+    openFiles: readonly ModStudioFileRef[];
+    activeFile: ModStudioFileRef | null;
+    saveState: ModStudioSaveState;
+    saveMessage?: string;
+    runtime: ModStudioRuntimeStatus;
+    buildOutput: string;
+    authoritativeDiagnostics: readonly ModStudioDiagnostic[];
+    localDiagnostics: readonly ModStudioDiagnostic[];
+    runs: readonly ModStudioRun[];
+    logs: readonly ModStudioRun[];
+    usage: ModStudioUsageSnapshot | null;
+    wallet: ModStudioWalletSnapshot | null;
+    invokeResult: ModStudioInvokeResult | null;
+}
+export type ModStudioPlayerCompute = Pick<PlayerComputeAPI, 'deploy' | 'versions' | 'setEnabled' | 'setRequires' | 'artifactBytes' | 'usage' | 'runs' | 'logs' | 'invoke'>;
+export type ModStudioPlayerWallet = Pick<PlayerWalletAPI, 'balance'>;
+export interface ModStudioBroker {
+    start(bytes: ArrayBuffer): Promise<void>;
+    stop(): void;
+}
+export interface ModStudioControllerOptions {
+    projectProvider: ModStudioProjectProvider;
+    playerCompute: ModStudioPlayerCompute;
+    playerWallet?: ModStudioPlayerWallet;
+    appId: string;
+    gridId: string;
+    initialProjectId?: string;
+    /** Required only when a project has a CLIENT target. */
+    grid?: PlayerCodeGridBounds;
+    /** Platform-owned glue worker; required only for CLIENT execution. */
+    workerUrl?: string | URL;
+    /** Page-side allow-listed host-call router; required only for CLIENT execution. */
+    onHostCall?: PlayerCodeBrokerOptions['onHostCall'];
+    onPresentation?: PlayerCodeBrokerOptions['onPresentation'];
+    /** Host-visible effective permissions; server authorization remains final. */
+    targetPermissions?: Partial<Record<ModStudioTarget, {
+        canWrite: boolean;
+        canRun: boolean;
+    }>>;
+    clientTickIntervalMs?: number;
+    autosaveMs?: number;
+    retryMs?: number;
+    compilePollMs?: number;
+    compilePollLimit?: number;
+    monitorPollMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    brokerFactory?: (options: PlayerCodeBrokerOptions) => ModStudioBroker;
+    isOnline?: () => boolean;
+    onStateChange?: (state: ModStudioState) => void;
+}
+export interface ModStudioStopResult {
+    serverStopped: boolean | null;
+    clientStopped: boolean | null;
+    failures: string[];
+}
+/**
+ * Headless project-first Mod Studio driver. It owns optimistic project saves,
+ * file CRUD, deployment ordering, runtime polling, and client hot swaps; the
+ * DOM mount is only a view over this state.
+ */
+export declare class ModStudioController {
+    private readonly options;
+    private state;
+    private readonly listeners;
+    private autosaveTimer;
+    private retryTimer;
+    private savePromise;
+    private editGeneration;
+    private persistedGeneration;
+    private conflictRemote;
+    private broker;
+    private operationGeneration;
+    private readonly visibleSurfaces;
+    private readonly surfaceTimers;
+    private pageVisible;
+    private destroyed;
+    constructor(options: ModStudioControllerOptions);
+    getState(): ModStudioState;
+    subscribe(listener: (state: ModStudioState) => void): () => void;
+    canTarget(target: ModStudioTarget, action: 'write' | 'run'): boolean;
+    initialize(): Promise<void>;
+    createProject(options: Omit<ModStudioNewProjectOptions, 'appId' | 'gridId'>): Promise<ModStudioProject>;
+    switchProject(projectId: string): Promise<void>;
+    private loadProject;
+    private installProject;
+    openFile(ref: ModStudioFileRef): void;
+    closeFile(ref: ModStudioFileRef): void;
+    fileContent(ref: ModStudioFileRef): string;
+    addFile(target: ModStudioTarget, path: string, content?: string): void;
+    renameFile(target: ModStudioTarget, path: string, nextPath: string): void;
+    deleteFile(target: ModStudioTarget, path: string): void;
+    importReferenceFile(reference: ModStudioReferenceFile, destinationPath?: string): Promise<void>;
+    saveProjectFileToLibrary(target: ModStudioTarget, path: string, title?: string): Promise<ModStudioReferenceFile>;
+    updateFile(target: ModStudioTarget, path: string, content: string): void;
+    updateSettings(patch: Partial<Pick<ModStudioProjectMetadata, 'name' | 'description' | 'serverModuleName' | 'clientModuleName' | 'pairingPreference'>>): void;
+    setPairingPreference(preference: ModStudioPairingPreference): void;
+    setLocalDiagnostics(diagnostics: readonly ModStudioDiagnostic[]): void;
+    /**
+     * Flush all edits in one optimistic-concurrency save. If edits arrive while
+     * the request is in flight, a second atomic save follows with the new
+     * revision instead of overwriting local content with the earlier response.
+     */
+    saveNow(): Promise<boolean>;
+    retrySave(): Promise<boolean>;
+    acceptRemoteConflict(): Promise<void>;
+    overwriteConflict(): Promise<boolean>;
+    testDraft(): Promise<void>;
+    deployLive(): Promise<void>;
+    private deployProject;
+    private compileTarget;
+    private recordBuild;
+    private enableServer;
+    private runClient;
+    stopProject(): Promise<ModStudioStopResult>;
+    invoke(exportName: string, paramsJson?: string): Promise<ModStudioInvokeResult>;
+    setSurfaceVisible(surface: ModStudioPolledSurface, visible: boolean): void;
+    setPageVisible(visible: boolean): void;
+    refreshSurface(surface: ModStudioPolledSurface): Promise<void>;
+    destroy(): void;
+    private performSaveLoop;
+    private markEdited;
+    private scheduleRetry;
+    private scheduleSurfacePoll;
+    private restartVisibleSurfacePolling;
+    private stopSurfacePolling;
+    private clearSurfaceTimer;
+    private clearSaveTimers;
+    private clearTimer;
+    private clientRuntimeOptions;
+    private checkOperation;
+    private sleep;
+    private requireProject;
+    private requireFile;
+    private assertProjectTarget;
+    private scope;
+    private setRuntime;
+    private update;
+    private ensureAlive;
+}
+//# sourceMappingURL=controller.d.ts.map

package/dist/mod-studio/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/mod-studio/controller.ts"],"names":[],"mappings":"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"}