@crowdedkingdoms/crowdyjs 9.0.0 → 10.0.0

package/dist/mod-studio/controller.js

@@ -0,0 +1,915 @@
+import { PlayerCodeBroker, } from '../player-runtime/player-code-broker.js';
+import { parseRustcDiagnostics } from './diagnostics.js';
+import { cloneModStudioProject, modStudioFileKey, normalizeModStudioPath, projectTargets, ModStudioOfflineError, ModStudioRevisionConflictError, } from './models.js';
+import { createModStudioStarterProject, } from './starter-projects.js';
+class OperationCancelledError extends Error {
+}
+/**
+ * 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 class ModStudioController {
+    constructor(options) {
+        this.options = options;
+        this.state = {
+            projects: [],
+            project: null,
+            personalLibraryFiles: [],
+            commonFiles: [],
+            openFiles: [],
+            activeFile: null,
+            saveState: 'SAVED',
+            runtime: { phase: 'IDLE' },
+            buildOutput: '',
+            authoritativeDiagnostics: [],
+            localDiagnostics: [],
+            runs: [],
+            logs: [],
+            usage: null,
+            wallet: null,
+            invokeResult: null,
+        };
+        this.listeners = new Set();
+        this.autosaveTimer = null;
+        this.retryTimer = null;
+        this.savePromise = null;
+        this.editGeneration = 0;
+        this.persistedGeneration = 0;
+        this.conflictRemote = null;
+        this.broker = null;
+        this.operationGeneration = 0;
+        this.visibleSurfaces = new Set();
+        this.surfaceTimers = new Map();
+        this.pageVisible = true;
+        this.destroyed = false;
+        if (options.onStateChange)
+            this.listeners.add(options.onStateChange);
+    }
+    getState() {
+        return this.state;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.state);
+        return () => this.listeners.delete(listener);
+    }
+    canTarget(target, action) {
+        const permission = this.options.targetPermissions?.[target];
+        return permission
+            ? action === 'write'
+                ? permission.canWrite
+                : permission.canRun
+            : true;
+    }
+    async initialize() {
+        this.ensureAlive();
+        const scope = this.scope();
+        let loaded;
+        try {
+            loaded = await Promise.all([
+                this.options.projectProvider.listProjects(scope),
+                this.options.projectProvider.listPersonalLibraryFiles(scope),
+                this.options.projectProvider.listCommonFiles(scope),
+            ]);
+        }
+        catch (error) {
+            if (error instanceof ModStudioOfflineError ||
+                this.options.isOnline?.() === false) {
+                this.update({
+                    saveState: 'OFFLINE',
+                    saveMessage: errorMessage(error),
+                });
+                return;
+            }
+            throw error;
+        }
+        const [projects, personalLibraryFiles, commonFiles] = loaded;
+        this.update({
+            projects,
+            personalLibraryFiles,
+            commonFiles,
+            saveState: 'SAVED',
+            saveMessage: undefined,
+        });
+        const first = projects.find((project) => project.projectId === this.options.initialProjectId) ?? projects[0];
+        if (first)
+            await this.loadProject(first.projectId);
+    }
+    async createProject(options) {
+        this.ensureAlive();
+        if (this.state.project && !(await this.saveNow())) {
+            throw new Error('Resolve or retry the current project save before creating another');
+        }
+        const input = createModStudioStarterProject({
+            ...options,
+            ...this.scope(),
+        });
+        const project = await this.options.projectProvider.createProject(input);
+        this.installProject(project);
+        this.update({
+            projects: upsertSummary(this.state.projects, summaryOf(project)),
+            saveState: 'SAVED',
+            saveMessage: undefined,
+        });
+        return project;
+    }
+    async switchProject(projectId) {
+        if (this.state.project?.projectId === projectId)
+            return;
+        if (this.state.project && !(await this.saveNow())) {
+            throw new Error('Resolve or retry the current project save before switching');
+        }
+        await this.loadProject(projectId);
+    }
+    async loadProject(projectId) {
+        const project = await this.options.projectProvider.getProject({
+            ...this.scope(),
+            projectId,
+        });
+        this.installProject(project);
+    }
+    installProject(project) {
+        ++this.operationGeneration;
+        this.stopSurfacePolling();
+        this.broker?.stop();
+        this.broker = null;
+        this.clearSaveTimers();
+        this.editGeneration = 0;
+        this.persistedGeneration = 0;
+        this.conflictRemote = null;
+        const clone = cloneModStudioProject(project);
+        const preferred = clone.files.find((file) => file.path === 'src/lib.rs') ?? clone.files[0];
+        const activeFile = preferred ? projectFileRef(preferred) : null;
+        this.update({
+            project: clone,
+            openFiles: activeFile ? [activeFile] : [],
+            activeFile,
+            saveState: 'SAVED',
+            saveMessage: undefined,
+            runtime: { phase: 'IDLE' },
+            buildOutput: '',
+            authoritativeDiagnostics: [],
+            localDiagnostics: [],
+            runs: [],
+            logs: [],
+            invokeResult: null,
+        });
+        this.restartVisibleSurfacePolling();
+    }
+    openFile(ref) {
+        this.requireFile(ref);
+        const exists = this.state.openFiles.some((entry) => sameFileRef(entry, ref));
+        this.update({
+            openFiles: exists ? this.state.openFiles : [...this.state.openFiles, ref],
+            activeFile: ref,
+        });
+    }
+    closeFile(ref) {
+        const openFiles = this.state.openFiles.filter((entry) => !sameFileRef(entry, ref));
+        const activeFile = this.state.activeFile && sameFileRef(this.state.activeFile, ref)
+            ? openFiles.at(-1) ?? null
+            : this.state.activeFile;
+        this.update({ openFiles, activeFile });
+    }
+    fileContent(ref) {
+        return this.requireFile(ref).content;
+    }
+    addFile(target, path, content = '') {
+        const project = this.requireProject();
+        this.assertProjectTarget(project, target);
+        const normalized = normalizeModStudioPath(path);
+        if (project.files.some((file) => file.target === target && file.path === normalized)) {
+            throw new Error(`${target}:${normalized} already exists`);
+        }
+        project.files.push({ target, path: normalized, content });
+        project.files.sort(compareProjectFile);
+        const ref = {
+            source: 'PROJECT',
+            target,
+            path: normalized,
+        };
+        this.markEdited();
+        this.openFile(ref);
+    }
+    renameFile(target, path, nextPath) {
+        const project = this.requireProject();
+        const normalized = normalizeModStudioPath(path);
+        const renamed = normalizeModStudioPath(nextPath);
+        const file = project.files.find((entry) => entry.target === target && entry.path === normalized);
+        if (!file)
+            throw new Error(`${target}:${normalized} does not exist`);
+        if (project.files.some((entry) => entry.target === target && entry.path === renamed)) {
+            throw new Error(`${target}:${renamed} already exists`);
+        }
+        file.path = renamed;
+        project.files.sort(compareProjectFile);
+        const replaceRef = (ref) => ref.source === 'PROJECT' &&
+            ref.target === target &&
+            ref.path === normalized
+            ? { ...ref, path: renamed }
+            : ref;
+        this.update({
+            openFiles: this.state.openFiles.map(replaceRef),
+            activeFile: this.state.activeFile
+                ? replaceRef(this.state.activeFile)
+                : null,
+        });
+        this.markEdited();
+    }
+    deleteFile(target, path) {
+        const project = this.requireProject();
+        const normalized = normalizeModStudioPath(path);
+        const index = project.files.findIndex((entry) => entry.target === target && entry.path === normalized);
+        if (index < 0)
+            throw new Error(`${target}:${normalized} does not exist`);
+        project.files.splice(index, 1);
+        this.closeFile({ source: 'PROJECT', target, path: normalized });
+        this.markEdited();
+    }
+    async importReferenceFile(reference, destinationPath = reference.path) {
+        this.requireProject();
+        if (!(await this.saveNow())) {
+            throw new Error('Resolve the current project save before importing a file');
+        }
+        const project = this.requireProject();
+        const saved = await this.options.projectProvider.importReferenceFile({
+            ...this.scope(),
+            projectId: project.projectId,
+            expectedRevisionId: project.revision.id,
+            source: reference.source,
+            referenceId: reference.id,
+            destinationPath,
+        });
+        this.installProject(saved);
+        this.update({
+            projects: upsertSummary(this.state.projects, summaryOf(saved)),
+        });
+        const imported = saved.files.find((file) => file.target === reference.target &&
+            file.path === normalizeModStudioPath(destinationPath));
+        if (imported)
+            this.openFile(projectFileRef(imported));
+    }
+    async saveProjectFileToLibrary(target, path, title) {
+        const file = this.requireProject().files.find((entry) => entry.target === target &&
+            entry.path === normalizeModStudioPath(path));
+        if (!file)
+            throw new Error(`${target}:${path} does not exist`);
+        const saved = await this.options.projectProvider.savePersonalLibraryFile({
+            ...this.scope(),
+            title: title?.trim() || file.path.split('/').at(-1) || file.path,
+            target,
+            path: file.path,
+            content: file.content,
+        });
+        this.update({
+            personalLibraryFiles: upsertReference(this.state.personalLibraryFiles, saved),
+        });
+        return saved;
+    }
+    updateFile(target, path, content) {
+        const project = this.requireProject();
+        const normalized = normalizeModStudioPath(path);
+        const file = project.files.find((entry) => entry.target === target && entry.path === normalized);
+        if (!file)
+            throw new Error(`${target}:${normalized} does not exist`);
+        if (file.content === content)
+            return;
+        file.content = content;
+        this.markEdited();
+    }
+    updateSettings(patch) {
+        const project = this.requireProject();
+        project.metadata = {
+            ...project.metadata,
+            ...patch,
+            pairingPreference: patch.pairingPreference ?? project.metadata.pairingPreference,
+        };
+        this.markEdited();
+    }
+    setPairingPreference(preference) {
+        this.updateSettings({ pairingPreference: preference });
+    }
+    setLocalDiagnostics(diagnostics) {
+        this.update({ localDiagnostics: [...diagnostics] });
+    }
+    /**
+     * 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.
+     */
+    async saveNow() {
+        this.ensureAlive();
+        this.clearTimer('autosave');
+        if (!this.state.project)
+            return true;
+        if (this.savePromise) {
+            await this.savePromise;
+            if (this.persistedGeneration === this.editGeneration)
+                return true;
+        }
+        this.savePromise = this.performSaveLoop();
+        try {
+            return await this.savePromise;
+        }
+        finally {
+            this.savePromise = null;
+        }
+    }
+    async retrySave() {
+        this.clearTimer('retry');
+        if (!this.state.project) {
+            this.update({ saveState: 'SAVING', saveMessage: undefined });
+            await this.initialize();
+            return this.state.saveState !== 'OFFLINE';
+        }
+        if (this.state.saveState === 'CONFLICT')
+            return false;
+        this.update({ saveState: 'SAVING', saveMessage: undefined });
+        return this.saveNow();
+    }
+    async acceptRemoteConflict() {
+        if (this.state.saveState !== 'CONFLICT')
+            return;
+        const remote = this.conflictRemote ??
+            (await this.options.projectProvider.getProject({
+                ...this.scope(),
+                projectId: this.requireProject().projectId,
+            }));
+        this.installProject(remote);
+    }
+    async overwriteConflict() {
+        if (this.state.saveState !== 'CONFLICT')
+            return this.saveNow();
+        const project = this.requireProject();
+        const remote = this.conflictRemote ??
+            (await this.options.projectProvider.getProject({
+                ...this.scope(),
+                projectId: project.projectId,
+            }));
+        project.revision = { ...remote.revision };
+        this.conflictRemote = null;
+        this.update({ saveState: 'SAVING', saveMessage: undefined });
+        return this.saveNow();
+    }
+    async testDraft() {
+        await this.deployProject(true);
+    }
+    async deployLive() {
+        await this.deployProject(false);
+    }
+    async deployProject(draft) {
+        this.requireProject();
+        if (!(await this.saveNow())) {
+            this.setRuntime('ERROR', 'Project must be saved before it can be built');
+            return;
+        }
+        const project = this.requireProject();
+        const operation = ++this.operationGeneration;
+        this.stopSurfacePolling();
+        this.update({
+            runtime: { phase: draft ? 'TESTING_DRAFT' : 'DEPLOYING_LIVE' },
+            buildOutput: '',
+            authoritativeDiagnostics: [],
+        });
+        try {
+            const targets = projectTargets(project.kind);
+            if (targets.length === 1) {
+                const target = targets[0];
+                const compiled = await this.compileTarget(project, target, draft, operation);
+                if (!compiled)
+                    return;
+                if (target === 'SERVER') {
+                    await this.enableServer(compiled.name, operation);
+                }
+                else {
+                    await this.runClient(compiled, operation);
+                }
+            }
+            else {
+                // Compile the client first so a client failure never publishes a new
+                // server version or alters the currently live pairing requirement.
+                const client = await this.compileTarget(project, 'CLIENT', draft, operation);
+                if (!client)
+                    return;
+                const server = await this.compileTarget(project, 'SERVER', draft, operation);
+                if (!server)
+                    return;
+                this.checkOperation(operation);
+                const requiredClientName = project.metadata.pairingPreference === 'REQUIRED'
+                    ? client.name
+                    : null;
+                await this.options.playerCompute.setRequires({
+                    ...this.scope(),
+                    serverName: server.name,
+                    requiredClientName,
+                });
+                this.checkOperation(operation);
+                await this.enableServer(server.name, operation);
+                await this.runClient(client, operation);
+            }
+            this.update({
+                runtime: {
+                    phase: 'RUNNING',
+                    message: draft ? 'Draft test is running' : 'Project is live',
+                },
+            });
+            await this.refreshSurface('usage').catch(() => { });
+        }
+        catch (error) {
+            if (error instanceof OperationCancelledError)
+                return;
+            this.setRuntime('ERROR', errorMessage(error));
+        }
+        finally {
+            if (operation === this.operationGeneration) {
+                this.restartVisibleSurfacePolling();
+            }
+        }
+    }
+    async compileTarget(project, target, draft, operation) {
+        if (!this.canTarget(target, 'write')) {
+            throw new Error(`${target} authoring is unavailable on this grid`);
+        }
+        const name = moduleNameFor(project, target);
+        const files = project.files.filter((file) => file.target === target);
+        if (files.length === 0)
+            throw new Error(`${target} has no project files`);
+        this.update({
+            runtime: {
+                phase: 'COMPILING',
+                target,
+                message: `Submitting ${name}`,
+            },
+        });
+        // This is the sole project→legacy wire conversion. Project state, provider
+        // contracts, editors, and templates all use typed files.
+        const sourceFilesJson = JSON.stringify(Object.fromEntries(files.map((file) => [file.path, file.content])));
+        const deployed = await this.options.playerCompute.deploy({
+            ...this.scope(),
+            name,
+            target: target,
+            sourceFilesJson,
+            sdkVersion: project.sdkVersion,
+            abiVersion: project.abiVersion,
+            tickHz: target === 'SERVER' ? 1 : undefined,
+            draft,
+        });
+        this.checkOperation(operation);
+        const limit = this.options.compilePollLimit ?? 60;
+        const pollMs = this.options.compilePollMs ?? 1500;
+        for (let attempt = 0; attempt < limit; attempt++) {
+            const versions = await this.options.playerCompute.versions({
+                ...this.scope(),
+                name,
+            });
+            this.checkOperation(operation);
+            const version = versions.find((candidate) => candidate.versionId === deployed.versionId);
+            const status = version?.compileStatus.toLowerCase();
+            if (status === 'succeeded' || status === 'success') {
+                this.recordBuild(target, version?.compileLog ?? '');
+                return { target, name, versionId: deployed.versionId };
+            }
+            if (status === 'failed' || status === 'error') {
+                const log = version?.compileLog ?? 'Compilation failed without output';
+                this.recordBuild(target, log);
+                this.update({
+                    runtime: {
+                        phase: 'COMPILE_FAILED',
+                        target,
+                        message: `${name} failed to compile`,
+                    },
+                });
+                return null;
+            }
+            await this.sleep(pollMs);
+            this.checkOperation(operation);
+        }
+        const timeout = `Compilation timed out after ${limit} polls`;
+        this.recordBuild(target, timeout);
+        this.update({
+            runtime: { phase: 'COMPILE_FAILED', target, message: timeout },
+        });
+        return null;
+    }
+    recordBuild(target, log) {
+        const section = `## ${target}\n${log || 'Compiled successfully.'}`;
+        const authoritativeDiagnostics = [
+            ...this.state.authoritativeDiagnostics.filter((diagnostic) => diagnostic.target !== target),
+            ...parseRustcDiagnostics(log, target),
+        ];
+        this.update({
+            buildOutput: [this.state.buildOutput, section].filter(Boolean).join('\n\n'),
+            authoritativeDiagnostics,
+        });
+    }
+    async enableServer(name, operation) {
+        if (!this.canTarget('SERVER', 'run')) {
+            throw new Error(`${name} compiled successfully, but run_server_code is unavailable on this grid`);
+        }
+        this.update({
+            runtime: { phase: 'ENABLING', target: 'SERVER', message: `Enabling ${name}` },
+        });
+        await this.options.playerCompute.setEnabled({
+            ...this.scope(),
+            name,
+            enabled: true,
+        });
+        this.checkOperation(operation);
+    }
+    async runClient(compiled, operation) {
+        if (!this.canTarget('CLIENT', 'run')) {
+            throw new Error(`${compiled.name} compiled successfully, but run_client_code is unavailable on this grid`);
+        }
+        const runtime = this.clientRuntimeOptions();
+        const artifact = await this.options.playerCompute.artifactBytes({
+            ...this.scope(),
+            name: compiled.name,
+            versionId: compiled.versionId,
+        });
+        this.checkOperation(operation);
+        if (artifact.versionId !== compiled.versionId ||
+            !artifact.artifactHash ||
+            artifact.bytes.byteLength === 0) {
+            throw new Error('Client artifact did not match the compiled project version');
+        }
+        const brokerOptions = {
+            ...runtime,
+            artifactHash: artifact.artifactHash,
+            fuelPerDispatch: artifact.fuelPerDispatch,
+            onPresentation: this.options.onPresentation,
+            tickIntervalMs: this.options.clientTickIntervalMs ?? 1000,
+        };
+        const broker = this.options.brokerFactory?.(brokerOptions) ??
+            new PlayerCodeBroker(brokerOptions);
+        await broker.start(artifact.bytes);
+        this.checkOperation(operation);
+        const previous = this.broker;
+        this.broker = broker;
+        previous?.stop();
+    }
+    async stopProject() {
+        const project = this.requireProject();
+        ++this.operationGeneration;
+        this.stopSurfacePolling();
+        this.update({ runtime: { phase: 'STOPPING' } });
+        const failures = [];
+        let serverStopped = null;
+        let clientStopped = null;
+        if (projectTargets(project.kind).includes('CLIENT')) {
+            clientStopped = true;
+            try {
+                this.broker?.stop();
+            }
+            catch (error) {
+                clientStopped = false;
+                failures.push(`Client: ${errorMessage(error)}`);
+            }
+            finally {
+                this.broker = null;
+            }
+        }
+        if (projectTargets(project.kind).includes('SERVER')) {
+            serverStopped = false;
+            try {
+                await this.options.playerCompute.setEnabled({
+                    ...this.scope(),
+                    name: moduleNameFor(project, 'SERVER'),
+                    enabled: false,
+                });
+                serverStopped = true;
+            }
+            catch (error) {
+                failures.push(`Server: ${errorMessage(error)}`);
+            }
+        }
+        const result = { serverStopped, clientStopped, failures };
+        this.update({
+            runtime: failures.length === 0
+                ? { phase: 'STOPPED', message: 'Project stopped' }
+                : {
+                    phase: 'PARTIAL_FAILURE',
+                    message: failures.join(' · '),
+                },
+        });
+        return result;
+    }
+    async invoke(exportName, paramsJson) {
+        const project = this.requireProject();
+        if (!projectTargets(project.kind).includes('SERVER')) {
+            throw new Error('Invoke requires a SERVER target');
+        }
+        const result = await this.options.playerCompute.invoke({
+            ...this.scope(),
+            moduleName: moduleNameFor(project, 'SERVER'),
+            exportName: exportName.trim() || 'invoke',
+            paramsJson: paramsJson?.trim() || null,
+        });
+        this.update({ invokeResult: result });
+        return result;
+    }
+    setSurfaceVisible(surface, visible) {
+        if (visible) {
+            this.visibleSurfaces.add(surface);
+            if (this.pageVisible) {
+                void this.refreshSurface(surface).catch(() => { });
+                this.scheduleSurfacePoll(surface);
+            }
+        }
+        else {
+            this.visibleSurfaces.delete(surface);
+            this.clearSurfaceTimer(surface);
+        }
+    }
+    setPageVisible(visible) {
+        if (this.pageVisible === visible)
+            return;
+        this.pageVisible = visible;
+        if (visible)
+            this.restartVisibleSurfacePolling();
+        else
+            this.stopSurfacePolling();
+    }
+    async refreshSurface(surface) {
+        if (!this.state.project)
+            return;
+        const serverName = this.state.project.metadata.serverModuleName;
+        if (surface === 'runs') {
+            this.update({
+                runs: await this.options.playerCompute.runs({
+                    ...this.scope(),
+                    ...(serverName ? { moduleName: serverName } : {}),
+                    limit: 50,
+                    offset: 0,
+                }),
+            });
+            return;
+        }
+        if (surface === 'logs') {
+            this.update({
+                logs: await this.options.playerCompute.logs({
+                    ...this.scope(),
+                    ...(serverName ? { moduleName: serverName } : {}),
+                    limit: 50,
+                }),
+            });
+            return;
+        }
+        const [usage, wallet] = await Promise.all([
+            this.options.playerCompute.usage({ appId: this.options.appId }),
+            this.options.playerWallet?.balance() ?? Promise.resolve(null),
+        ]);
+        this.update({ usage: normalizeUsage(usage), wallet });
+    }
+    destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        ++this.operationGeneration;
+        this.clearSaveTimers();
+        this.stopSurfacePolling();
+        this.broker?.stop();
+        this.broker = null;
+        this.listeners.clear();
+    }
+    async performSaveLoop() {
+        while (this.persistedGeneration !== this.editGeneration) {
+            const project = this.requireProject();
+            const savingGeneration = this.editGeneration;
+            const snapshot = cloneModStudioProject(project);
+            this.update({ saveState: 'SAVING', saveMessage: undefined });
+            try {
+                const saved = await this.options.projectProvider.saveProject({
+                    ...this.scope(),
+                    projectId: snapshot.projectId,
+                    expectedRevisionId: snapshot.revision.id,
+                    metadata: snapshot.metadata,
+                    files: snapshot.files,
+                });
+                this.persistedGeneration = savingGeneration;
+                if (this.state.project?.projectId !== saved.projectId)
+                    return true;
+                if (this.editGeneration === savingGeneration) {
+                    this.state.project = cloneModStudioProject(saved);
+                }
+                else {
+                    // Preserve newer local edits while advancing the revision precondition.
+                    this.state.project.revision = { ...saved.revision };
+                    this.state.project.updatedAt = saved.updatedAt;
+                }
+                this.update({
+                    projects: upsertSummary(this.state.projects, summaryOf(saved)),
+                    saveState: this.persistedGeneration === this.editGeneration ? 'SAVED' : 'SAVING',
+                    saveMessage: undefined,
+                });
+            }
+            catch (error) {
+                if (error instanceof ModStudioRevisionConflictError) {
+                    this.conflictRemote = error.remoteProject ?? null;
+                    this.update({ saveState: 'CONFLICT', saveMessage: error.message });
+                    return false;
+                }
+                if (error instanceof ModStudioOfflineError ||
+                    this.options.isOnline?.() === false) {
+                    this.update({ saveState: 'OFFLINE', saveMessage: errorMessage(error) });
+                    this.scheduleRetry();
+                    return false;
+                }
+                this.update({ saveState: 'OFFLINE', saveMessage: errorMessage(error) });
+                throw error;
+            }
+        }
+        this.update({ saveState: 'SAVED', saveMessage: undefined });
+        return true;
+    }
+    markEdited() {
+        this.editGeneration++;
+        this.update({ saveState: 'SAVING', saveMessage: undefined });
+        this.clearTimer('autosave');
+        this.autosaveTimer = setTimeout(() => {
+            this.autosaveTimer = null;
+            void this.saveNow().catch(() => { });
+        }, this.options.autosaveMs ?? 700);
+    }
+    scheduleRetry() {
+        this.clearTimer('retry');
+        if (this.destroyed)
+            return;
+        this.retryTimer = setTimeout(() => {
+            this.retryTimer = null;
+            void this.retrySave().catch(() => { });
+        }, this.options.retryMs ?? 3000);
+    }
+    scheduleSurfacePoll(surface) {
+        this.clearSurfaceTimer(surface);
+        if (!this.pageVisible ||
+            !this.visibleSurfaces.has(surface) ||
+            this.destroyed) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            this.surfaceTimers.delete(surface);
+            void this.refreshSurface(surface)
+                .catch(() => { })
+                .finally(() => this.scheduleSurfacePoll(surface));
+        }, this.options.monitorPollMs ?? 5000);
+        this.surfaceTimers.set(surface, timer);
+    }
+    restartVisibleSurfacePolling() {
+        if (!this.pageVisible || this.destroyed)
+            return;
+        for (const surface of this.visibleSurfaces) {
+            void this.refreshSurface(surface).catch(() => { });
+            this.scheduleSurfacePoll(surface);
+        }
+    }
+    stopSurfacePolling() {
+        for (const timer of this.surfaceTimers.values())
+            clearTimeout(timer);
+        this.surfaceTimers.clear();
+    }
+    clearSurfaceTimer(surface) {
+        const timer = this.surfaceTimers.get(surface);
+        if (timer)
+            clearTimeout(timer);
+        this.surfaceTimers.delete(surface);
+    }
+    clearSaveTimers() {
+        this.clearTimer('autosave');
+        this.clearTimer('retry');
+    }
+    clearTimer(kind) {
+        const timer = kind === 'autosave' ? this.autosaveTimer : this.retryTimer;
+        if (timer)
+            clearTimeout(timer);
+        if (kind === 'autosave')
+            this.autosaveTimer = null;
+        else
+            this.retryTimer = null;
+    }
+    clientRuntimeOptions() {
+        if (!this.options.workerUrl || !this.options.grid || !this.options.onHostCall) {
+            throw new Error('CLIENT projects require workerUrl, grid, and an allow-listed onHostCall router');
+        }
+        return {
+            workerUrl: this.options.workerUrl,
+            grid: this.options.grid,
+            onHostCall: this.options.onHostCall,
+        };
+    }
+    checkOperation(generation) {
+        if (generation !== this.operationGeneration || this.destroyed) {
+            throw new OperationCancelledError();
+        }
+    }
+    sleep(ms) {
+        return (this.options.sleep ??
+            ((delay) => new Promise((resolve) => setTimeout(resolve, delay))))(ms);
+    }
+    requireProject() {
+        if (!this.state.project)
+            throw new Error('No Mod Studio project is open');
+        return this.state.project;
+    }
+    requireFile(ref) {
+        if (ref.source === 'PROJECT') {
+            const file = this.requireProject().files.find((entry) => entry.target === ref.target &&
+                entry.path === normalizeModStudioPath(ref.path));
+            if (file)
+                return file;
+        }
+        else {
+            const files = ref.source === 'PERSONAL_LIBRARY'
+                ? this.state.personalLibraryFiles
+                : this.state.commonFiles;
+            const file = files.find((entry) => ref.referenceId
+                ? entry.id === ref.referenceId
+                : entry.path === ref.path && entry.target === ref.target);
+            if (file)
+                return file;
+        }
+        throw new Error(`File is not loaded: ${ref.source}:${ref.path}`);
+    }
+    assertProjectTarget(project, target) {
+        if (!projectTargets(project.kind).includes(target)) {
+            throw new Error(`${project.kind} projects do not have a ${target} target`);
+        }
+    }
+    scope() {
+        return { appId: this.options.appId, gridId: this.options.gridId };
+    }
+    setRuntime(phase, message) {
+        this.update({ runtime: { phase, message } });
+    }
+    update(patch) {
+        this.state = { ...this.state, ...patch };
+        for (const listener of this.listeners)
+            listener(this.state);
+    }
+    ensureAlive() {
+        if (this.destroyed)
+            throw new Error('ModStudioController is destroyed');
+    }
+}
+function projectFileRef(file) {
+    return { source: 'PROJECT', target: file.target, path: file.path };
+}
+function sameFileRef(a, b) {
+    return (a.source === b.source &&
+        a.target === b.target &&
+        a.path === b.path &&
+        a.referenceId === b.referenceId);
+}
+function compareProjectFile(a, b) {
+    return modStudioFileKey(a.target, a.path).localeCompare(modStudioFileKey(b.target, b.path));
+}
+function moduleNameFor(project, target) {
+    const name = target === 'SERVER'
+        ? project.metadata.serverModuleName
+        : project.metadata.clientModuleName;
+    if (!name?.trim()) {
+        throw new Error(`${target} module name is required in Project settings`);
+    }
+    return name.trim();
+}
+function summaryOf(project) {
+    return {
+        projectId: project.projectId,
+        name: project.metadata.name,
+        kind: project.kind,
+        revisionId: project.revision.id,
+        ...(project.metadata.serverModuleName
+            ? { serverModuleName: project.metadata.serverModuleName }
+            : {}),
+        ...(project.metadata.clientModuleName
+            ? { clientModuleName: project.metadata.clientModuleName }
+            : {}),
+        updatedAt: project.updatedAt,
+    };
+}
+function upsertSummary(projects, next) {
+    const result = projects.filter((project) => project.projectId !== next.projectId);
+    result.push(next);
+    return result.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+function upsertReference(files, next) {
+    return [
+        next,
+        ...files.filter((file) => file.source !== next.source || file.id !== next.id),
+    ];
+}
+function normalizeUsage(value) {
+    return {
+        hourUnitsUsed: String(value.hourUnitsUsed),
+        dayUnitsUsed: String(value.dayUnitsUsed),
+        unitsPerHour: value.unitsPerHour == null ? null : String(value.unitsPerHour),
+        unitsPerDay: value.unitsPerDay == null ? null : String(value.unitsPerDay),
+        compilesThisHour: value.compilesThisHour,
+        maxCompilesPerHour: value.maxCompilesPerHour,
+        gateStatus: value.gateStatus,
+        gateReason: value.gateReason ?? null,
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}