Genarrative/packages/image-canvas-core/src/ports.ts

export type ImageCanvasHostKind = 'web' | 'tauri';

export type ImageCanvasHostCapabilities = {
  account: boolean;
  wallet: boolean;
  cloudAssetLibrary: boolean;
  localProject: boolean;
  externalEditorGeneration: boolean;
  advancedBackgroundRemoval: boolean;
};

export type ImageCanvasHostScope = {
  projectId: string;
  draftId: string;
  intent: 'create' | 'refine';
  sourceAssetId: string | null;
};

export type ImageCanvasHostResult<T> =
  | { status: 'ok'; value: T }
  | {
      status: 'unsupported-capability';
      capability: keyof ImageCanvasHostCapabilities;
      message: string;
    }
  | {
      status: 'conflict';
      conflictKind: 'project-identity' | 'host-revision' | 'draft-revision';
      draft: ImageCanvasDraft | null;
      hostRevision: string | null;
    }
  | { status: 'failed'; code: string; message: string };

export type ImageCanvasMediaRef =
  | { kind: 'project-asset'; assetId: string }
  | {
      kind: 'draft-media';
      mediaId: string;
      mediaType: 'image/png' | 'image/jpeg' | 'image/webp';
      sha256: string;
      byteLength: number;
      pixelWidth: number;
      pixelHeight: number;
    }
  | { kind: 'host-resource'; resourceId: string };

export type ImageCanvasDraftLayer = {
  layerId: string;
  resourceId: string;
  title: string;
  mediaRef: ImageCanvasMediaRef;
  x: number;
  y: number;
  width: number;
  height: number;
  originalWidth: number;
  originalHeight: number;
  zIndex: number;
  groupId: string | null;
  hidden: boolean;
  locked: boolean;
  flipX: boolean;
  flipY: boolean;
};

export type ImageCanvasDraftCanvas = {
  viewport: { x: number; y: number; scale: number };
  backgroundColor: string;
  layers: ImageCanvasDraftLayer[];
  selectedLayerIds: string[];
  primarySelectedLayerId: string | null;
};

export type ImageCanvasDraft = {
  schemaVersion: 'game-creator-asset-canvas-draft.v1';
  draftId: string;
  projectId: string;
  intent: 'create' | 'refine';
  sourceAssetId: string | null;
  sourceResourceId: string | null;
  revision: number;
  status:
    | 'editing'
    | 'generating'
    | 'commit-prepared'
    | 'committed'
    | 'cancelled'
    | 'reconciliation-required';
  canvas: ImageCanvasDraftCanvas;
  generations: ImageCanvasGenerationRecord[];
  pendingCommit: {
    commitId: string;
    idempotencyKey?: string;
    requestFingerprint: string;
  } | null;
  lastCommit: {
    commitId: string;
    idempotencyKey?: string;
    assetId: string;
    eventId: string;
    committedProjectRevision: number;
    sourceLayerId: string;
    mediaSha256: string;
  } | null;
  createdAt: number;
  updatedAt: number;
};

export type ImageCanvasGenerationPlaceholder = {
  x: number;
  y: number;
  width: number;
  height: number;
};

export type ImageCanvasGenerationRecord = {
  generationId: string;
  intentId: string;
  phase:
    | 'generation-accepted'
    | 'generation-running'
    | 'remote-completed'
    | 'media-downloaded'
    | 'candidate-ready'
    | 'asset-durable-committed'
    | 'failed'
    | 'reconciliation-required';
  referenceResourceIds: string[];
  outputAssetId: string | null;
  sourceLayerId: string | null;
  placeholder: ImageCanvasGenerationPlaceholder | null;
  errorCode: string | null;
  createdAt: number;
  updatedAt: number;
};

export type ImageCanvasGenerationProgressPhase =
  | 'confirmation-required'
  | ImageCanvasGenerationRecord['phase']
  | 'manifest-projected'
  | 'layout-ready'
  | 'selected';

export type ImageCanvasGenerationProgress = {
  intentId: string;
  generationId: string;
  draftRevision?: number;
  phase: ImageCanvasGenerationProgressPhase;
  progress: number | null;
  errorCode: string | null;
};

export type ImageCanvasGenerationServiceIdentityConfirmation = {
  generationId: string;
  operationId: string | null;
  operationState: string;
  serviceOrigin: string;
  challenge: string;
  expiresAt: number;
};

export type ImageCanvasGenerationFailureDisposition =
  | 'failed'
  | 'reconciliation-required'
  | 'not-started'
  | 'already-terminal';

export type ImageCanvasHostInputImage = {
  name: string;
  mediaType: 'image/png' | 'image/jpeg' | 'image/webp';
  bytes: Uint8Array;
};

export type ImageCanvasHostImage = {
  mediaRef: ImageCanvasMediaRef;
  previewUrl: string;
  resourceId: string | null;
};

export type ImageCanvasLocalImportResult =
  | { status: 'cancelled' }
  | {
      status: 'imported';
      draft: ImageCanvasDraft;
      importedLayerIds: string[];
    };

export interface ImageCanvasProjectPort {
  loadDraft(
    scope: ImageCanvasHostScope,
  ): Promise<ImageCanvasHostResult<ImageCanvasDraft | null>>;
  createDraft(
    scope: ImageCanvasHostScope,
  ): Promise<ImageCanvasHostResult<ImageCanvasDraft>>;
  updateDraft(input: {
    scope: ImageCanvasHostScope;
    expectedDraftRevision: number;
    status: 'editing' | 'generating' | 'cancelled';
    canvas: ImageCanvasDraft['canvas'];
    generations: ImageCanvasGenerationRecord[];
  }): Promise<ImageCanvasHostResult<ImageCanvasDraft>>;
  acknowledgeCandidateLayers(input: {
    scope: ImageCanvasHostScope;
    layerIds: string[];
  }): Promise<ImageCanvasHostResult<ImageCanvasDraft>>;
  discardDraft(input: {
    scope: ImageCanvasHostScope;
    expectedDraftRevision: number;
  }): Promise<ImageCanvasHostResult<ImageCanvasDraft>>;
}

export interface ImageCanvasAssetPort {
  importLocalImages(input: {
    scope: ImageCanvasHostScope;
    expectedDraftRevision: number;
    viewportSize: { width: number; height: number };
  }): Promise<ImageCanvasHostResult<ImageCanvasLocalImportResult>>;
  importImages(input: {
    scope: ImageCanvasHostScope;
    expectedDraftRevision: number;
    images: ImageCanvasHostInputImage[];
  }): Promise<ImageCanvasHostResult<ImageCanvasHostImage[]>>;
  exportImage(input: {
    scope: ImageCanvasHostScope;
    name: string;
    mediaType: 'image/png' | 'image/jpeg' | 'image/webp';
    quality: number | null;
    bytes: Uint8Array;
  }): Promise<
    ImageCanvasHostResult<{
      disposition: 'downloaded' | 'saved';
      byteLength: number;
    }>
  >;
}

export interface ImageCanvasGenerationPort {
  settleGenerationFailure(input: {
    scope: ImageCanvasHostScope;
    expectedDraftRevision: number;
    generationId: string;
    intentId: string;
    errorCode: string;
    reconciliationRequired: boolean;
  }): Promise<
    ImageCanvasHostResult<{
      disposition: ImageCanvasGenerationFailureDisposition;
      draft: ImageCanvasDraft;
    }>
  >;
  archiveFailedGeneration(input: {
    scope: ImageCanvasHostScope;
    expectedDraftRevision: number;
    generationId: string;
  }): Promise<ImageCanvasHostResult<ImageCanvasDraft>>;
  generateImage(input: {
    scope: ImageCanvasHostScope;
    expectedHostRevision: string;
    expectedDraftRevision: number;
    intentId: string;
    generationId: string;
    idempotencyKey: string;
    commitId: string;
    commitIdempotencyKey: string;
    prompt: string;
    aspectRatio: '1:1' | '2:3' | '3:2' | '9:16' | '16:9';
    imageSize: '0.5K' | '1K' | '2K';
    assetKind: string;
    assetName: string;
    referenceResourceIds: string[];
    sourceLayerId: string | null;
    placeholder: ImageCanvasGenerationPlaceholder | null;
    onProgress?: (progress: ImageCanvasGenerationProgress) => void;
  }): Promise<
    ImageCanvasHostResult<{
      generation: ImageCanvasGenerationRecord;
      images: ImageCanvasHostImage[];
      draft: ImageCanvasDraft;
    }>
  >;
  recoverImages(input: {
    scope: ImageCanvasHostScope;
    onProgress?: (progress: ImageCanvasGenerationProgress) => void;
  }): Promise<
    ImageCanvasHostResult<{
      resumedGenerationIds: string[];
      serviceIdentityConfirmations: ImageCanvasGenerationServiceIdentityConfirmation[];
    }>
  >;
  removeBackground(input: {
    scope: ImageCanvasHostScope;
    expectedDraftRevision: number;
    generationId: string;
    idempotencyKey: string;
    sourceLayerId: string;
  }): Promise<
    ImageCanvasHostResult<{
      generation: ImageCanvasGenerationRecord;
      images: ImageCanvasHostImage[];
    }>
  >;
}

export interface ImageCanvasCompletionPort {
  commitSelectedCandidate(input: {
    scope: ImageCanvasHostScope;
    expectedHostRevision: string;
    expectedDraftRevision: number;
    commitId: string;
    idempotencyKey: string;
    sourceLayerId: string;
    name: string;
    assetKind: string;
    referenceResourceIds: string[];
  }): Promise<
    ImageCanvasHostResult<{
      resourceId: string;
      assetId?: string;
      projectId?: string;
      commitId?: string;
      committedProjectRevision?: number;
      draftRevision: number;
      hostRevision: string;
      commitStatus?: 'committed' | 'already-committed';
      manifest?: unknown;
      eventId?: string;
    }>
  >;
  commitImage(input: {
    scope: ImageCanvasHostScope;
    expectedHostRevision: string;
    expectedDraftRevision: number;
    commitId: string;
    idempotencyKey: string;
    name: string;
    assetKind: string;
    referenceResourceIds: string[];
    mediaType: 'image/png' | 'image/jpeg' | 'image/webp';
    bytes: Uint8Array;
  }): Promise<
    ImageCanvasHostResult<{
      resourceId: string;
      assetId?: string;
      projectId?: string;
      commitId?: string;
      committedProjectRevision?: number;
      draftRevision: number;
      hostRevision: string;
      commitStatus?: 'committed' | 'already-committed';
      manifest?: unknown;
      eventId?: string;
    }>
  >;
}

export type ImageCanvasHostPort = {
  readonly kind: ImageCanvasHostKind;
  readonly capabilities: ImageCanvasHostCapabilities;
  project: ImageCanvasProjectPort;
  asset: ImageCanvasAssetPort;
  generation: ImageCanvasGenerationPort;
  completion: ImageCanvasCompletionPort;
};

export function unsupportedImageCanvasCapability(
  capability: keyof ImageCanvasHostCapabilities,
  message: string,
): ImageCanvasHostResult<never> {
  return { status: 'unsupported-capability', capability, message };
}