@playcraft/cli 0.1.54 → 0.1.55-beta

package/templates/preview-runtime/v1/types/adapters.d.ts

@@ -0,0 +1,26 @@
+import type { FieldCapability, RawDocuments } from './protocol.js';
+export interface ApplyContext<C> {
+    beforeConfig: C;
+    config: C;
+    draftRevision: number;
+    fields: FieldCapability[];
+    signal: AbortSignal;
+    assertCurrent(): void;
+}
+/** All callbacks must check cancellation before late asynchronous side effects. */
+export interface GameAdapter<C> {
+    apply(context: ApplyContext<C>): void | Promise<void>;
+    restartScene(context: ApplyContext<C>): void | Promise<void>;
+    afterRender(context: ApplyContext<C>): Promise<void>;
+    dispose(): void | Promise<void>;
+}
+export interface RuntimeOptions<C> {
+    binding: import('./protocol.js').SessionBinding;
+    fields: FieldCapability[];
+    resolve(documents: RawDocuments): C;
+    source: {
+        get(): C;
+        install(config: C): unknown;
+    };
+    createGame(context: ApplyContext<C>): Promise<GameAdapter<C>>;
+}

package/templates/preview-runtime/v1/types/preview.d.ts

@@ -0,0 +1,23 @@
+import type { RuntimeOptions } from './adapters.js';
+import type { SessionBinding } from './protocol.js';
+/** Reads only the platform's explicit context; a game receives no platform credentials. */
+export declare function readWorkspacePreviewContext(expectedContractVersion: string): {
+    binding: SessionBinding;
+    parentOrigin: string;
+};
+export declare function connectPreviewRuntime<C>(options: RuntimeOptions<C> & {
+    parentOrigin: string;
+}): {
+    runtime: {
+        hello(value: unknown): import("./protocol.js").Capabilities;
+        snapshot(value: unknown): import("./protocol.js").Receipt;
+        patch(value: unknown): import("./protocol.js").Receipt;
+        restart(value: unknown): import("./protocol.js").Receipt;
+        status(value: unknown): import("./protocol.js").ApplicationResult;
+        subscribe(fn: (result: import("./protocol.js").ApplicationResult) => void): () => boolean;
+        onCapabilities(fn: (value: import("./protocol.js").Capabilities) => void): () => boolean;
+        settled(): Promise<void>;
+        dispose(): Promise<void>;
+    };
+    dispose(): Promise<void>;
+};

package/templates/preview-runtime/v1/types/protocol.d.ts

@@ -0,0 +1,94 @@
+/** Independent editor-preview protocol. Production games must not import this module. */
+export declare const PROTOCOL_VERSION: 1;
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export type RawDocuments = Record<string, JsonObject>;
+export interface SessionBinding {
+    scope: {
+        projectId: string;
+        branchName: string;
+        themeId: string;
+    };
+    schemaVersion: string;
+    configContractVersion: string;
+    locale: string;
+}
+export interface Hello extends SessionBinding {
+    protocolVersion: 1;
+    sessionId: string;
+    frameEpoch: number;
+}
+export interface Identity extends Hello {
+    runtimeInstanceId: string;
+}
+export type ApplyMode = 'live' | 'restart-scene' | 'reload';
+export interface FieldCapability {
+    documentId: string;
+    path: string[];
+    effectivePath: string[];
+    groupId: string;
+    mode: ApplyMode;
+}
+export interface Capabilities extends Identity {
+    stage: 'bootstrap-ready' | 'game-ready';
+    canAcceptSnapshot: boolean;
+    fields: FieldCapability[];
+}
+export type Operation = {
+    op: 'set';
+    documentId: string;
+    path: string[];
+    value: JsonValue;
+} | {
+    op: 'remove';
+    documentId: string;
+    path: string[];
+};
+export interface SnapshotRequest extends Identity {
+    draftRevision: number;
+    documents: RawDocuments;
+}
+export interface PatchRequest extends Identity {
+    baseDraftRevision: number;
+    draftRevision: number;
+    phase: 'preview' | 'commit';
+    operations: Operation[];
+}
+export interface Receipt {
+    accepted: true;
+    receivedRevision: number;
+}
+export interface GroupResult {
+    groupId: string;
+    appliedRevision: number;
+    status: 'applied' | 'pending-commit' | 'requires-reload' | 'unknown';
+}
+export interface ApplicationResult extends Identity {
+    resultSequence: number;
+    receivedRevision: number;
+    installedRevision: number;
+    appliedRevision: number;
+    status: 'idle' | 'applying' | 'applied' | 'pending-commit' | 'requires-reload' | 'error';
+    groups: GroupResult[];
+    error?: string;
+}
+export declare class ProtocolError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare const revision: (v: unknown) => v is number;
+export declare function assertJson(value: unknown, depth?: number): asserts value is JsonValue;
+export declare function clone<T>(value: T): T;
+export declare function freeze<T>(value: T): T;
+export declare function fingerprint(value: unknown): string;
+export declare function assertHello(value: unknown): asserts value is Hello;
+export declare function assertIdentity(value: unknown): asserts value is Identity;
+export declare function sameIdentity(a: Identity, b: unknown): b is Identity;
+export declare function assertBinding(expected: SessionBinding, actual: Hello): void;
+export declare function assertDocuments(value: unknown): asserts value is RawDocuments;
+export declare function assertSnapshot(value: unknown): asserts value is SnapshotRequest;
+export declare function assertPatch(value: unknown): asserts value is PatchRequest;
+export declare function applyOperations(documents: RawDocuments, operations: Operation[]): RawDocuments;
+export declare function readPath(value: unknown, path: string[]): unknown;

package/templates/preview-runtime/v1/types/runtime.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimeOptions } from './adapters.js';
+import type { ApplicationResult, Capabilities, Receipt } from './protocol.js';
+export declare function createParameterRuntime<C>(options: RuntimeOptions<C>): {
+    hello(value: unknown): Capabilities;
+    snapshot(value: unknown): Receipt;
+    patch(value: unknown): Receipt;
+    restart(value: unknown): Receipt;
+    status(value: unknown): ApplicationResult;
+    subscribe(fn: (result: ApplicationResult) => void): () => boolean;
+    onCapabilities(fn: (value: Capabilities) => void): () => boolean;
+    settled(): Promise<void>;
+    dispose(): Promise<void>;
+};
+export type ParameterRuntime<C> = ReturnType<typeof createParameterRuntime<C>>;