@crowdedkingdoms/crowdyjs 9.0.0 → 10.0.0

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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"}