@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/runtime/source-assets/source-asset-model-hydrator.ts

@@ -0,0 +1,241 @@
+import {
+  createToolcraftDefaultModelFiles,
+  findToolcraftDefaultModelSchemaAsset,
+  isToolcraftDefaultModelPlaceholder,
+  resolveToolcraftDefaultModelControl,
+} from "../model-import/default-model-source-assets";
+import { normalizeToolcraftModelImportLimits } from "../model-import/model-import-limits";
+import {
+  hydrateToolcraftPersistedModels,
+  type ToolcraftModelHydrationController,
+} from "../model-import/model-persistence-hydration";
+import {
+  createToolcraftModelWorkerClient,
+  type ToolcraftModelWorkerClient,
+} from "../model-import/worker/model-import-worker-client";
+import type {
+  ToolcraftCommand,
+  ToolcraftMediaAsset,
+  ToolcraftState,
+} from "../state/types";
+import { snapshotToolcraftSourceAssetControl } from "./source-asset-admission";
+import type { ToolcraftSourceAssetCleanupManager } from "./source-asset-cleanup-manager";
+import {
+  createToolcraftSourceAssetFeedback,
+  getToolcraftSourceAssetFeedback,
+} from "./source-asset-feedback";
+import type { ToolcraftSourceAssetImportRunner } from "./source-asset-import-runner";
+import type {
+  ToolcraftSourceAssetDefaultReplacement,
+  ToolcraftSourceAssetJobManager,
+} from "./source-asset-job-manager";
+import type { ToolcraftSourceAssetOperationStore } from "./source-asset-operation-store";
+import type { ToolcraftBinaryAssetRepository } from "./repository/binary-asset-repository";
+import type { ToolcraftSourceAssetFeedback } from "./source-asset-types";
+
+export type ToolcraftSourceAssetModelHydrator = Readonly<{
+  cancel: () => void;
+  disposeWorker: () => void;
+  hydrateModels: () => Promise<void>;
+  settle: () => Promise<void>;
+}>;
+
+export function createToolcraftSourceAssetModelHydrator({
+  cleanupManager,
+  createModelWorkerClient,
+  dispatch,
+  getState,
+  importRunner,
+  isDefaultReplacementCurrent,
+  jobManager,
+  operationStore,
+  repository,
+}: Readonly<{
+  cleanupManager: ToolcraftSourceAssetCleanupManager;
+  createModelWorkerClient?: () => ToolcraftModelWorkerClient;
+  dispatch: (command: ToolcraftCommand) => void;
+  getState: () => ToolcraftState;
+  importRunner: ToolcraftSourceAssetImportRunner;
+  isDefaultReplacementCurrent: (
+    replacement: ToolcraftSourceAssetDefaultReplacement,
+  ) => boolean;
+  jobManager: ToolcraftSourceAssetJobManager;
+  operationStore: ToolcraftSourceAssetOperationStore;
+  repository: ToolcraftBinaryAssetRepository;
+}>): ToolcraftSourceAssetModelHydrator {
+  let hydration: ToolcraftModelHydrationController | null = null;
+  let hydrationCompletion: Promise<void> | null = null;
+  let hydrationRerunRequested = false;
+  let hydrationWorkerClient: ToolcraftModelWorkerClient | null = null;
+  let workerDisposed = false;
+
+  const markDefaultModelUnavailable = (
+    replacement: ToolcraftSourceAssetDefaultReplacement,
+    feedback: ToolcraftSourceAssetFeedback,
+  ): void => {
+    const placeholder = getState().mediaAssets.find(
+      (asset) => asset.id === replacement.assetId,
+    );
+    if (
+      placeholder?.assetKind !== "model" ||
+      !isDefaultReplacementCurrent(replacement)
+    ) return;
+
+    dispatch({
+      asset: Object.freeze({
+        ...placeholder,
+        lastRepairError: feedback,
+        lifecycle: "unavailable" as const,
+      }),
+      expectedPlaceholderRef: replacement.placeholderRef,
+      type: "media.hydrateDefaultModel",
+    });
+  };
+
+  const hydrateDefaultModel = async (
+    placeholder: Extract<ToolcraftMediaAsset, { assetKind: "model" }>,
+  ): Promise<void> => {
+    if (!placeholder.sourceTarget) {
+      markDefaultModelUnavailable(
+        {
+          assetId: placeholder.id,
+          layerId: placeholder.layerId,
+          placeholderRef: placeholder.sourceBundleRef,
+          sourceTarget: "",
+        },
+        createToolcraftSourceAssetFeedback(
+          "default-model-target-missing",
+          "The default model has no upload target.",
+          "bundle",
+        ),
+      );
+      return;
+    }
+    const replacement: ToolcraftSourceAssetDefaultReplacement = Object.freeze({
+      assetId: placeholder.id,
+      layerId: placeholder.layerId,
+      placeholderRef: placeholder.sourceBundleRef,
+      sourceTarget: placeholder.sourceTarget,
+    });
+
+    try {
+      const schemaAsset = findToolcraftDefaultModelSchemaAsset(
+        getState().schema,
+        placeholder,
+      );
+      if (!schemaAsset) {
+        throw new Error("The default model no longer exists in the app schema.");
+      }
+      const control = resolveToolcraftDefaultModelControl(
+        getState().schema,
+        schemaAsset,
+      );
+      const files = createToolcraftDefaultModelFiles(
+        schemaAsset,
+        normalizeToolcraftModelImportLimits(control.modelLimits),
+      );
+      const controlSnapshot = snapshotToolcraftSourceAssetControl(control);
+      if (!controlSnapshot) {
+        throw new Error("Default model control snapshot is unavailable.");
+      }
+      const admission = jobManager.reserveAdmission(replacement.sourceTarget);
+      const outcome = await jobManager.trackInflight(
+        importRunner.runAdmittedImport(
+          Object.freeze({
+            files,
+            origin: "panel" as const,
+            target: replacement.sourceTarget,
+          }),
+          controlSnapshot,
+          admission,
+          replacement,
+        ),
+      );
+      if (outcome.kind === "rejected") {
+        markDefaultModelUnavailable(replacement, outcome.feedback);
+      }
+    } catch (error) {
+      markDefaultModelUnavailable(
+        replacement,
+        getToolcraftSourceAssetFeedback(error, "default-model-import-failed"),
+      );
+    }
+  };
+
+  const cancelStaleDefaultModelJobs = (): void => {
+    for (const job of jobManager.getActiveJobs()) {
+      if (
+        job.defaultReplacement &&
+        !isDefaultReplacementCurrent(job.defaultReplacement)
+      ) {
+        job.controller.abort();
+        operationStore.setOperation({ phase: "idle", target: job.target });
+      }
+    }
+  };
+
+  const runHydrationRound = async (): Promise<void> => {
+    cancelStaleDefaultModelJobs();
+    const restoringModels = getState().mediaAssets.filter(
+      (asset): asset is Extract<ToolcraftMediaAsset, { assetKind: "model" }> =>
+        asset.assetKind === "model" && asset.lifecycle === "restoring",
+    );
+    const defaultHydrations = restoringModels
+      .filter(isToolcraftDefaultModelPlaceholder)
+      .filter((asset) => !jobManager.hasDefaultReplacement(asset.id))
+      .map((asset) => hydrateDefaultModel(asset));
+
+    const hasPersistedModels = restoringModels.some(
+      (asset) => !isToolcraftDefaultModelPlaceholder(asset),
+    );
+    let persistedHydration: Promise<void> = Promise.resolve();
+    if (hasPersistedModels) {
+      hydrationWorkerClient ??= createModelWorkerClient?.() ??
+        createToolcraftModelWorkerClient();
+      hydration = hydrateToolcraftPersistedModels({
+        dispatch,
+        getState,
+        repository,
+        workerClient: hydrationWorkerClient,
+      });
+      persistedHydration = hydration.promise;
+    }
+    await Promise.all([...defaultHydrations, persistedHydration]);
+  };
+
+  const hydrateModels = (): Promise<void> => {
+    if (jobManager.isDisposed()) return Promise.resolve();
+    cancelStaleDefaultModelJobs();
+    if (hydrationCompletion) {
+      hydrationRerunRequested = true;
+      return hydrationCompletion.then(() => {
+        if (jobManager.isDisposed() || !hydrationRerunRequested) return;
+        hydrationRerunRequested = false;
+        return hydrateModels();
+      });
+    }
+
+    const completion = runHydrationRound().finally(async () => {
+      hydration = null;
+      if (!jobManager.isDisposed()) await cleanupManager.collect();
+      if (hydrationCompletion === completion) hydrationCompletion = null;
+    });
+    hydrationCompletion = completion;
+    return completion;
+  };
+
+  return Object.freeze({
+    cancel: () => hydration?.cancel(),
+    disposeWorker: () => {
+      if (workerDisposed) return;
+      workerDisposed = true;
+      hydrationWorkerClient?.dispose();
+    },
+    hydrateModels,
+    settle: async () => {
+      if (hydrationCompletion) {
+        await Promise.allSettled([hydrationCompletion]);
+      }
+    },
+  });
+}

package/templates/runtime/source-assets/source-asset-operation-store.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createToolcraftSourceAssetOperationStore } from "./source-asset-operation-store";
+
+describe("source asset operation store", () => {
+  it("isolates subscriber failures and continues notifying", () => {
+    const store = createToolcraftSourceAssetOperationStore();
+    const throwingListener = vi.fn(() => {
+      throw new Error("listener failed");
+    });
+    const healthyListener = vi.fn();
+    store.subscribe(throwingListener);
+    store.subscribe(healthyListener);
+
+    expect(() =>
+      store.setOperation({
+        phase: "analyzing",
+        target: "source.files",
+      }),
+    ).not.toThrow();
+
+    expect(throwingListener).toHaveBeenCalledTimes(1);
+    expect(healthyListener).toHaveBeenCalledTimes(1);
+  });
+
+  it("stores presentation feedback beside operation status and clears it explicitly or on a new operation", () => {
+    const store = createToolcraftSourceAssetOperationStore();
+    const feedback = {
+      category: "resource-unavailable" as const,
+      code: "model-presentation-unavailable",
+      message: "The model presentation is unavailable.",
+    };
+    store.setOperation({
+      phase: "analyzing",
+      progress: 0.25,
+      target: "source.model",
+    });
+    store.setPresentationFeedback("source.model", feedback);
+
+    expect(store.getOperation("source.model")).toEqual({
+      phase: "analyzing",
+      presentationFeedback: feedback,
+      progress: 0.25,
+      target: "source.model",
+    });
+    store.clearPresentationFeedback("source.model");
+    expect(store.getOperation("source.model").presentationFeedback).toBeUndefined();
+
+    store.setPresentationFeedback("source.model", feedback);
+    store.setOperation({ phase: "decoding", target: "source.model" });
+    expect(store.getOperation("source.model").presentationFeedback).toBeUndefined();
+  });
+});

package/templates/runtime/source-assets/source-asset-operation-store.ts

@@ -0,0 +1,132 @@
+import type {
+  ToolcraftSourceAssetFeedback,
+  ToolcraftSourceAssetOperation,
+  ToolcraftSourceAssetOperationUpdate,
+} from "./source-asset-types";
+
+export type ToolcraftSourceAssetOperationStore = {
+  clearPresentationFeedback: (target: string) => void;
+  dispose: () => void;
+  getOperation: (target: string) => ToolcraftSourceAssetOperation;
+  setOperation: (operation: ToolcraftSourceAssetOperation) => void;
+  setPresentationFeedback: (
+    target: string,
+    feedback: ToolcraftSourceAssetFeedback,
+  ) => void;
+  subscribe: (listener: () => void) => () => void;
+  updateOperation: (
+    target: string,
+    update: ToolcraftSourceAssetOperationUpdate,
+  ) => void;
+};
+
+function freezeOperation(
+  operation: ToolcraftSourceAssetOperation,
+): ToolcraftSourceAssetOperation {
+  const feedback = operation.feedback
+    ? Object.freeze({ ...operation.feedback })
+    : undefined;
+  const presentationFeedback = operation.presentationFeedback
+    ? Object.freeze({ ...operation.presentationFeedback })
+    : undefined;
+
+  return Object.freeze({
+    ...operation,
+    ...(feedback ? { feedback } : {}),
+    ...(presentationFeedback ? { presentationFeedback } : {}),
+  });
+}
+
+function assertTarget(target: string): void {
+  if (target.length === 0 || target.trim() !== target) {
+    throw new Error("Source asset operation target must be a non-empty trimmed string");
+  }
+}
+
+export function createToolcraftSourceAssetOperationStore(): ToolcraftSourceAssetOperationStore {
+  const listeners = new Set<() => void>();
+  const operations = new Map<string, ToolcraftSourceAssetOperation>();
+  let disposed = false;
+
+  const getOperation = (target: string): ToolcraftSourceAssetOperation => {
+    assertTarget(target);
+    const current = operations.get(target);
+
+    if (current) {
+      return current;
+    }
+
+    const idle = freezeOperation({ phase: "idle", target });
+    operations.set(target, idle);
+    return idle;
+  };
+
+  const setOperation = (operation: ToolcraftSourceAssetOperation): void => {
+    if (disposed) {
+      return;
+    }
+
+    assertTarget(operation.target);
+    if (
+      operation.progress !== undefined &&
+      (!Number.isFinite(operation.progress) ||
+        operation.progress < 0 ||
+        operation.progress > 1)
+    ) {
+      throw new Error("Source asset operation progress must be between 0 and 1");
+    }
+
+    operations.set(operation.target, freezeOperation(operation));
+    for (const listener of [...listeners]) {
+      try {
+        listener();
+      } catch {
+        // One observer cannot interrupt publication to the remaining observers.
+      }
+    }
+  };
+
+  return {
+    clearPresentationFeedback: (target) => {
+      const current = getOperation(target);
+      if (!current.presentationFeedback) return;
+      const { presentationFeedback: _removed, ...operation } = current;
+      setOperation(operation);
+    },
+    dispose: () => {
+      if (disposed) {
+        return;
+      }
+
+      disposed = true;
+      listeners.clear();
+      operations.clear();
+    },
+    getOperation,
+    setOperation,
+    setPresentationFeedback: (target, feedback) => {
+      setOperation({
+        ...getOperation(target),
+        presentationFeedback: feedback,
+        target,
+      });
+    },
+    subscribe: (listener) => {
+      if (disposed) {
+        return () => undefined;
+      }
+
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    updateOperation: (target, update) => {
+      const current = getOperation(target);
+
+      setOperation({
+        ...current,
+        ...update,
+        target,
+      });
+    },
+  };
+}

package/templates/runtime/source-assets/source-asset-prepared-result.ts

@@ -0,0 +1,108 @@
+import type { ToolcraftMediaAssetDraft } from "../state/types";
+import type { ToolcraftBinaryAssetLease } from "./repository/binary-asset-repository";
+import type {
+  ToolcraftPreparedSourceAsset,
+  ToolcraftPreparedSourceAssetRecord,
+  ToolcraftSourceAssetRegistrableHandler,
+} from "./source-asset-types";
+
+type PreparedAsset = ToolcraftPreparedSourceAssetRecord<"file" | "image" | "model">;
+
+export function validateToolcraftSourceAssetPlan(
+  plan: ReturnType<ToolcraftSourceAssetRegistrableHandler["plan"]>,
+): void {
+  if (
+    !Number.isSafeInteger(plan.logicalAssetCount) ||
+    plan.logicalAssetCount <= 0
+  ) {
+    throw new Error("Source asset import plan must contain a positive asset count");
+  }
+  if (plan.target.length === 0 || plan.target.trim() !== plan.target) {
+    throw new Error("Source asset import plan target must be a non-empty trimmed string");
+  }
+  if (
+    plan.sourceTarget !== undefined &&
+    (plan.sourceTarget.length === 0 ||
+      plan.sourceTarget.trim() !== plan.sourceTarget)
+  ) {
+    throw new Error(
+      "Source asset import plan sourceTarget must be a non-empty trimmed string",
+    );
+  }
+}
+
+export function validateToolcraftPreparedSourceAssets(
+  prepared: ToolcraftPreparedSourceAsset<PreparedAsset>,
+  expectedKind: PreparedAsset["assetKind"],
+  expectedAssetCount: number,
+  lease: ToolcraftBinaryAssetLease,
+): void {
+  if (prepared.assets.length !== expectedAssetCount) {
+    throw new Error(
+      `Source asset handler prepared ${prepared.assets.length} assets; expected ${expectedAssetCount}.`,
+    );
+  }
+
+  for (const asset of prepared.assets) {
+    if (asset.assetKind !== expectedKind) {
+      throw new Error(
+        `Source asset handler "${expectedKind}" prepared asset kind "${asset.assetKind}".`,
+      );
+    }
+    if (
+      Object.prototype.hasOwnProperty.call(asset, "id") ||
+      Object.prototype.hasOwnProperty.call(asset, "layerId")
+    ) {
+      throw new Error("Prepared source assets cannot contain final ids");
+    }
+  }
+
+  const declaredRefs = [...new Set(prepared.stagedResourceRefs)].sort();
+  const leasedRefs = [...lease.refs()].sort();
+  if (
+    declaredRefs.length !== prepared.stagedResourceRefs.length ||
+    declaredRefs.length !== leasedRefs.length ||
+    declaredRefs.some((ref, index) => ref !== leasedRefs[index])
+  ) {
+    throw new Error(
+      "Prepared source asset refs must exactly match the repository lease",
+    );
+  }
+}
+
+export function freezeToolcraftPreparedAssetDraft(
+  asset: PreparedAsset,
+  sourceTarget?: string,
+): ToolcraftMediaAssetDraft {
+  const { sourceTarget: _handlerSourceTarget, ...assetWithoutSourceTarget } =
+    asset;
+  const canonicalAsset = {
+    ...assetWithoutSourceTarget,
+    ...(sourceTarget ? { sourceTarget } : {}),
+  } as PreparedAsset;
+
+  if (canonicalAsset.assetKind === "image") {
+    return Object.freeze({
+      ...canonicalAsset,
+      position: Object.freeze({ ...canonicalAsset.position }),
+      ...(canonicalAsset.size
+        ? { size: Object.freeze({ ...canonicalAsset.size }) }
+        : {}),
+      ...(canonicalAsset.transform
+        ? { transform: Object.freeze({ ...canonicalAsset.transform }) }
+        : {}),
+    });
+  }
+  if (canonicalAsset.assetKind === "file") {
+    return Object.freeze({
+      ...canonicalAsset,
+      position: Object.freeze({ ...canonicalAsset.position }),
+    });
+  }
+
+  return Object.freeze({
+    ...canonicalAsset,
+    position: Object.freeze({ ...canonicalAsset.position }),
+    size: Object.freeze({ ...canonicalAsset.size }),
+  });
+}

package/templates/runtime/source-assets/source-asset-presentation-feedback.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "../state/create-template-state";
+import { createMemoryToolcraftBinaryAssetRepository } from "./repository/memory-binary-asset-repository";
+import { createToolcraftSourceAssetCoordinator } from "./source-asset-coordinator";
+
+describe("source asset presentation feedback", () => {
+  it("publishes and clears feedback through the coordinator boundary", async () => {
+    const state = createToolcraftState(defineToolcraft({
+      canvas: { enabled: true },
+      panels: {},
+    }));
+    const coordinator = createToolcraftSourceAssetCoordinator({
+      dispatch: () => undefined,
+      getState: () => state,
+      repository: createMemoryToolcraftBinaryAssetRepository(),
+    });
+    const feedback = {
+      category: "resource-unavailable" as const,
+      code: "model-presentation-unavailable",
+      message: "The model presentation is unavailable.",
+    };
+
+    coordinator.reportPresentationFeedback("source.model", feedback);
+    expect(coordinator.getOperation("source.model").presentationFeedback)
+      .toEqual(feedback);
+    coordinator.clearPresentationFeedback("source.model");
+    expect(coordinator.getOperation("source.model").presentationFeedback)
+      .toBeUndefined();
+
+    await coordinator.dispose();
+  });
+});

package/templates/runtime/source-assets/source-asset-presentation-resources.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createToolcraftSourceAssetPresentationResources } from "./source-asset-presentation-resources";
+
+describe("source asset presentation resources", () => {
+  it("reuses one object URL per active resource and revokes it on release", async () => {
+    const releaseResourceRef = vi.fn();
+    const retainResourceRef = vi.fn(() => releaseResourceRef);
+    const revokeObjectUrl = vi.fn();
+    const resources = createToolcraftSourceAssetPresentationResources({
+      createObjectUrl: vi.fn(() => "blob:media-image-a"),
+      resolveResource: vi.fn(async () => new Uint8Array([1, 2, 3])),
+      retainResourceRef,
+      revokeObjectUrl,
+    });
+
+    const first = await resources.retain("media:image:a", "image/png");
+    const second = await resources.retain("media:image:a", "image/png");
+
+    expect(first.url).toBe(second.url);
+    expect(retainResourceRef).toHaveBeenCalledTimes(1);
+    first.release();
+    expect(revokeObjectUrl).not.toHaveBeenCalled();
+    second.release();
+    expect(revokeObjectUrl).toHaveBeenCalledWith(first.url);
+    expect(releaseResourceRef).toHaveBeenCalledTimes(1);
+  });
+
+  it("releases reachability when resource resolution fails", async () => {
+    const releaseResourceRef = vi.fn();
+    const resources = createToolcraftSourceAssetPresentationResources({
+      createObjectUrl: vi.fn(() => "blob:unused"),
+      resolveResource: vi.fn(async () => null),
+      retainResourceRef: () => releaseResourceRef,
+      revokeObjectUrl: vi.fn(),
+    });
+
+    await expect(
+      resources.retain("media:file:missing", "application/octet-stream"),
+    ).rejects.toThrow(/unavailable/u);
+    expect(releaseResourceRef).toHaveBeenCalledTimes(1);
+  });
+});