@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/runtime/state/types.ts

@@ -1,8 +1,9 @@
 import type {
   ToolcraftCanvasSize,
-  ToolcraftFileDropAssetKind,
   ResolvedToolcraftAppSchema,
 } from "../schema/types";
+import type { ToolcraftModelAssetRecord } from "../model-import/model-import-types";
+import type { ToolcraftPanelSnapEdge } from "../contracts/types";
 
 export type ToolcraftCommand =
   | {
@@ -27,6 +28,15 @@ export type ToolcraftCommand =
   | { delta: ToolcraftPoint; type: "canvas.panBy" }
   | { offset: ToolcraftPoint; type: "canvas.setOffset" }
   | { size: ToolcraftCanvasSize; type: "canvas.setSize" }
+  | {
+      aspectRatio?: unknown;
+      history?: ToolcraftHistoryMode;
+      historyGroup?: string;
+      label?: string;
+      mode: ToolcraftCanvasState["mode"];
+      size: ToolcraftCanvasSize;
+      type: "canvas.applySettings";
+    }
   | { type: "canvas.center" }
   | { type: "canvas.zoomIn" }
   | { type: "canvas.zoomOut" }
@@ -42,16 +52,64 @@ export type ToolcraftCommand =
       panelId: ToolcraftPanelId;
       type: "panels.setHidden";
     }
+  | {
+      panelId: ToolcraftPanelId;
+      patch: ToolcraftPanelPatch;
+      type: "panels.update";
+    }
+  | {
+      collapsed: boolean;
+      sectionId: string;
+      type: "panels.setSectionCollapsed";
+    }
   | { panelId: ToolcraftPanelId; type: "panels.resetOffset" }
   | {
-      asset: Omit<ToolcraftMediaAsset, "id" | "layerId"> & {
-        id?: string;
-        layerId?: string;
-        layerName?: string;
-      };
+      asset: ToolcraftMediaImportAsset;
       replaceExisting?: boolean;
       type: "media.import";
     }
+  | {
+      assets: readonly ToolcraftMediaAssetDraft[];
+      replaceExisting?: boolean;
+      type: "media.importBatch";
+    }
+  | {
+      activeDocumentRef: string;
+      analysis: ToolcraftModelAsset["analysis"];
+      appliedRepairRecipeId: string;
+      assetId: string;
+      expectedActiveDocumentRef: string;
+      expectedRepairPlanRef: string;
+      expectedSourceBundleDigest: string;
+      expectedTopologyProfile: ToolcraftModelAsset["topologyProfile"];
+      repairedDocumentRef: string;
+      type: "media.commitModelRepair";
+    }
+  | {
+      asset: ToolcraftModelAsset;
+      expectedSourceBundleDigest: string;
+      expectedTopologyProfile: ToolcraftModelAsset["topologyProfile"];
+      type: "media.hydrateModel";
+    }
+  | {
+      asset: ToolcraftModelAsset;
+      expectedPlaceholderRef: string;
+      type: "media.hydrateDefaultModel";
+    }
+  | {
+      assetId: string;
+      error?: ToolcraftMediaResourceError;
+      expectedResourceRef: string;
+      lifecycle: "ready" | "unavailable";
+      type: "media.setBinaryResourceState";
+    }
+  | {
+      assetId: string;
+      expectedActiveDocumentRef: string;
+      expectedSourceBundleDigest: string;
+      feedback: ToolcraftModelAsset["lastRepairError"] | null;
+      type: "media.setModelRepairError";
+    }
   | { mediaId: string; type: "media.delete" }
   | { mediaIds: string[]; type: "media.reorder" }
   | {
@@ -110,6 +168,7 @@ export const toolcraftRuntimeCommandTypes = [
   "canvas.panBy",
   "canvas.setOffset",
   "canvas.setSize",
+  "canvas.applySettings",
   "canvas.center",
   "canvas.zoomIn",
   "canvas.zoomOut",
@@ -117,8 +176,16 @@ export const toolcraftRuntimeCommandTypes = [
   "canvas.setViewport",
   "panels.setOffset",
   "panels.setHidden",
+  "panels.update",
+  "panels.setSectionCollapsed",
   "panels.resetOffset",
   "media.import",
+  "media.importBatch",
+  "media.commitModelRepair",
+  "media.hydrateDefaultModel",
+  "media.hydrateModel",
+  "media.setBinaryResourceState",
+  "media.setModelRepairError",
   "media.delete",
   "media.reorder",
   "media.transform",
@@ -145,7 +212,13 @@ export type ToolcraftPoint = {
   y: number;
 };
 
+export type ToolcraftSceneElementFrame = {
+  position: ToolcraftPoint;
+  size: ToolcraftCanvasSize;
+};
+
 export type ToolcraftCanvasState = {
+  mode: "finite" | "infinite";
   offset: ToolcraftPoint;
   size: ToolcraftCanvasSize;
   zoom: number;
@@ -173,19 +246,124 @@ export type ToolcraftLayerDraft = {
   visible?: boolean;
 };
 
-export type ToolcraftMediaAsset = {
-  assetKind?: ToolcraftFileDropAssetKind;
-  dataUrl: string;
+export type ToolcraftMediaAssetBase<AssetKind extends "file" | "image" | "model"> = {
+  assetKind: AssetKind;
   fileName: string;
   id: string;
   layerId: string;
   mimeType: string;
+  sourceTarget?: string;
+};
+
+export type ToolcraftMediaResourceError = {
+  code: string;
+  message: string;
+};
+
+export type ToolcraftMediaResourceState =
+  | { lifecycle: "ready" | "restoring"; resourceRef: string }
+  | {
+      error: ToolcraftMediaResourceError;
+      lifecycle: "unavailable";
+      resourceRef: string;
+    };
+
+type ToolcraftBinaryMediaAssetBase<AssetKind extends "file" | "image"> =
+  ToolcraftMediaAssetBase<AssetKind> & ToolcraftMediaResourceState;
+
+export type ToolcraftImageAsset = ToolcraftBinaryMediaAssetBase<"image"> & {
   position: ToolcraftPoint;
   size?: ToolcraftCanvasSize;
-  sourceTarget?: string;
   transform?: ToolcraftMediaTransform;
 };
 
+export type ToolcraftFileAsset = ToolcraftBinaryMediaAssetBase<"file"> & {
+  position: ToolcraftPoint;
+};
+
+export type ToolcraftModelAsset = ToolcraftMediaAssetBase<"model"> &
+  ToolcraftSceneElementFrame &
+  ToolcraftModelAssetRecord;
+
+export type ToolcraftLegacyModelAsset = ToolcraftMediaAssetBase<"model"> &
+  Partial<ToolcraftSceneElementFrame> &
+  ToolcraftModelAssetRecord;
+
+export type ToolcraftMediaAsset =
+  | ToolcraftFileAsset
+  | ToolcraftImageAsset
+  | ToolcraftModelAsset;
+
+type ToolcraftMediaAssetDraftFor<Asset extends ToolcraftMediaAsset> =
+  Asset extends ToolcraftMediaAsset
+    ? Omit<Asset, "id" | "layerId"> & {
+        id?: string;
+        layerId?: string;
+        layerName?: string;
+      }
+    : never;
+
+export type ToolcraftFileAssetDraft =
+  ToolcraftMediaAssetDraftFor<ToolcraftFileAsset>;
+
+export type ToolcraftImageAssetDraft =
+  ToolcraftMediaAssetDraftFor<ToolcraftImageAsset>;
+
+export type ToolcraftModelAssetDraft =
+  ToolcraftMediaAssetDraftFor<ToolcraftModelAsset>;
+
+export type ToolcraftMediaAssetDraft =
+  | ToolcraftFileAssetDraft
+  | ToolcraftImageAssetDraft
+  | ToolcraftModelAssetDraft;
+
+export type ToolcraftLegacyImageAsset = Omit<
+  ToolcraftMediaAssetBase<"image">,
+  "assetKind"
+> & {
+  assetKind?: "image";
+  dataUrl: string;
+  position: ToolcraftPoint;
+  size?: ToolcraftCanvasSize;
+  transform?: ToolcraftMediaTransform;
+};
+
+export type ToolcraftLegacyFileAsset = ToolcraftMediaAssetBase<"file"> & {
+  assetKind: "file";
+  dataUrl: string;
+  position: ToolcraftPoint;
+};
+
+export type ToolcraftLegacyImageAssetDraft = Omit<
+  ToolcraftLegacyImageAsset,
+  "assetKind" | "id" | "layerId"
+> & {
+  assetKind?: "image";
+  id?: string;
+  layerId?: string;
+  layerName?: string;
+};
+
+export type ToolcraftLegacyFileAssetDraft = Omit<
+  ToolcraftLegacyFileAsset,
+  "id" | "layerId"
+> & {
+  id?: string;
+  layerId?: string;
+  layerName?: string;
+};
+
+export type ToolcraftMediaImportAsset =
+  | ToolcraftLegacyFileAssetDraft
+  | ToolcraftLegacyImageAssetDraft
+  | ToolcraftMediaAssetDraft;
+
+export type ToolcraftInitialMediaAsset =
+  | ToolcraftLegacyFileAsset
+  | ToolcraftLegacyImageAsset
+  | ToolcraftLegacyModelAsset
+  | ToolcraftMediaAsset;
+
 export type ToolcraftMediaTransform = {
   flipHorizontal?: boolean;
   flipVertical?: boolean;
@@ -251,6 +429,25 @@ export type ToolcraftPanelState = {
   extended?: boolean;
   hidden?: boolean;
   offset: { x: number; y: number };
+  snapEdge?: ToolcraftPanelSnapEdge;
+};
+
+export type ToolcraftPanelPatch = Partial<
+  Pick<
+    ToolcraftPanelState,
+    "collapsed" | "extended" | "hidden" | "offset" | "snapEdge"
+  >
+>;
+
+export type ToolcraftControlsPanelState = ToolcraftPanelState & {
+  collapsedSections: Record<string, boolean>;
+};
+
+export type ToolcraftPanelsState = {
+  controls: ToolcraftControlsPanelState;
+  layers: ToolcraftPanelState;
+  timeline: ToolcraftPanelState;
+  toolbar: ToolcraftPanelState;
 };
 
 export type ToolcraftState = {
@@ -262,7 +459,7 @@ export type ToolcraftState = {
   };
   layers: ToolcraftLayer[];
   mediaAssets: ToolcraftMediaAsset[];
-  panels: Record<ToolcraftPanelId, ToolcraftPanelState>;
+  panels: ToolcraftPanelsState;
   schema: ResolvedToolcraftAppSchema;
   selectedLayerId: string | null;
   timeline: ToolcraftTimelineState;
@@ -272,8 +469,13 @@ export type ToolcraftState = {
 export type ToolcraftInitialState = {
   canvas?: Partial<ToolcraftCanvasState>;
   layers?: ToolcraftLayer[];
-  mediaAssets?: ToolcraftMediaAsset[];
-  panels?: Partial<Record<ToolcraftPanelId, Partial<ToolcraftPanelState>>>;
+  mediaAssets?: ToolcraftInitialMediaAsset[];
+  panels?: {
+    controls?: Partial<ToolcraftControlsPanelState>;
+    layers?: Partial<ToolcraftPanelState>;
+    timeline?: Partial<ToolcraftPanelState>;
+    toolbar?: Partial<ToolcraftPanelState>;
+  };
   selectedLayerId?: string | null;
   timeline?: Partial<ToolcraftTimelineState>;
   values?: Record<string, unknown>;

package/templates/runtime/testing/model-import-performance-workload.test.ts

@@ -0,0 +1,265 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import type { ToolcraftAppSchema } from "../schema/types";
+import {
+  TOOLCRAFT_MODEL_PERFORMANCE_DEVELOPMENT_PRESSURE,
+  deriveToolcraftModelPerformancePaths,
+} from "./model-import-performance-workload";
+
+function schemaWithControls(
+  controls: ToolcraftAppSchema["panels"]["controls"] extends infer T
+    ? T extends { sections: readonly (infer Section)[] }
+      ? Section extends { controls: infer Controls }
+        ? Controls
+        : never
+      : never
+    : never,
+) {
+  return defineToolcraft({
+    canvas: { enabled: true, sizing: { mode: "editable-output" } },
+    panels: {
+      controls: {
+        sections: [{ controls, title: "Source" }],
+        title: "Controls",
+      },
+    },
+  });
+}
+
+describe("Toolcraft model performance workload", () => {
+  it("derives import, analysis/repair, and orbit paths from normalized model limits", () => {
+    const schema = schemaWithControls({
+      orientation: {
+        defaultValue: { position: [0, 0, 5], up: [0, 1, 0] },
+        keyframeable: false,
+        label: false,
+        target: "view.orientation",
+        type: "orientationGizmo",
+      },
+      source: {
+        assetKind: "model",
+        modelFormats: ["glb", "ply"],
+        modelLimits: {
+          maxBundleFiles: 5,
+          maxDecodedBytes: 1_000_000,
+          maxEstimatedWorkerBytes: 16_000_000,
+          maxNodes: 10,
+          maxPrimitives: 20,
+          maxSourceBytes: 50_000,
+          maxTriangles: 1_000,
+          maxVertices: 2_000,
+        },
+        target: "source.model",
+        topologyProfile: "solid-mesh",
+        type: "fileDrop",
+      },
+    });
+
+    const paths = deriveToolcraftModelPerformancePaths(schema);
+
+    expect(paths.map((path) => [path.kind, path.profile])).toEqual([
+      ["import", "batch-responsive"],
+      ["analysis-repair", "batch-responsive"],
+      ["orbit", "interactive-continuous"],
+    ]);
+    expect(paths[0]).toMatchObject({
+      formats: ["glb", "ply"],
+      id: "runtime-model:source.model:import",
+      target: "source.model",
+      topologyProfile: "solid-mesh",
+    });
+    expect(paths[0]?.dimensions).toEqual([
+      expect.objectContaining({
+        configuredMaximumValue: 5,
+        developmentValue: 4,
+        effectiveMaximumValue: 5,
+        id: "model-bundle-files",
+        limit: "maxBundleFiles",
+        maximumValue: 5,
+        targetPressure: TOOLCRAFT_MODEL_PERFORMANCE_DEVELOPMENT_PRESSURE,
+        unit: "files",
+      }),
+      expect.objectContaining({
+        developmentValue: 40_000,
+        id: "model-source-bytes",
+        limit: "maxSourceBytes",
+        maximumValue: 50_000,
+        targetPressure: TOOLCRAFT_MODEL_PERFORMANCE_DEVELOPMENT_PRESSURE,
+        unit: "bytes",
+      }),
+      expect.objectContaining({
+        developmentValue: 38_410,
+        effectiveMaximumValue: 48_012,
+        id: "model-decoded-bytes",
+      }),
+      expect.objectContaining({
+        developmentValue: 12_800_000,
+        id: "model-worker-bytes",
+      }),
+      expect.objectContaining({ developmentValue: 8, id: "model-nodes" }),
+      expect.objectContaining({ developmentValue: 16, id: "model-primitives" }),
+      expect.objectContaining({ developmentValue: 800, id: "model-triangles" }),
+      expect.objectContaining({ developmentValue: 1_600, id: "model-vertices" }),
+    ]);
+    expect(paths[2]?.dimensions.map((dimension) => dimension.id)).toEqual([
+      "model-nodes",
+      "model-primitives",
+      "model-triangles",
+      "model-vertices",
+    ]);
+    expect(paths[0]?.development).toMatchObject({
+      combinedPressureRatio: TOOLCRAFT_MODEL_PERFORMANCE_DEVELOPMENT_PRESSURE,
+      kind: "development",
+      values: {
+        "model-source-bytes": 40_000,
+        "model-triangles": 800,
+        "model-vertices": 1_600,
+      },
+    });
+    expect(paths[0]?.maximum.combinedPressureRatio).toBe(1);
+    expect(paths[0]?.appearance.configured).toEqual({
+      textureBytes: 33_554_432,
+      textureCount: 256,
+      textureDimension: 8_192,
+      texturePixels: 33_554_432,
+    });
+    expect(paths[0]?.appearance.effectiveMaximum.combinedWorkerBytes)
+      .toBeLessThanOrEqual(16_000_000);
+    expect(paths[0]?.appearance.fitsWorkerLimit).toBe(true);
+    expect(paths[0]?.appearance.development.combinedWorkerBytes)
+      .toBeLessThan(paths[0]!.appearance.effectiveMaximum.combinedWorkerBytes);
+    expect(Object.isFrozen(paths)).toBe(true);
+    expect(Object.isFrozen(paths[0]?.dimensions)).toBe(true);
+  });
+
+  it("treats folders and ZIP packages as multi-file workloads for every format", () => {
+    const singleFileSchema = schemaWithControls({
+      source: {
+        assetKind: "model",
+        modelFormats: ["glb", "obj"],
+        target: "source.model",
+        type: "fileDrop",
+      },
+    });
+    const bundledSchema = schemaWithControls({
+      source: {
+        assetKind: "model",
+        modelFormats: ["gltf"],
+        target: "source.model",
+        type: "fileDrop",
+      },
+    });
+    const bundleDimension = (schema: ReturnType<typeof schemaWithControls>) =>
+      deriveToolcraftModelPerformancePaths(schema)[0]?.dimensions.find(
+        (dimension) => dimension.id === "model-bundle-files",
+      );
+
+    expect(bundleDimension(singleFileSchema)?.effectiveMaximumValue).toBe(32);
+    expect(bundleDimension(bundledSchema)?.effectiveMaximumValue).toBe(32);
+  });
+
+  it("projects raw topology ceilings onto the worker-memory envelope before applying 80% pressure", () => {
+    const schema = schemaWithControls({
+      source: {
+        assetKind: "model",
+        target: "source.model",
+        type: "fileDrop",
+      },
+    });
+
+    const analysisPath = deriveToolcraftModelPerformancePaths(schema).find(
+      (path) => path.kind === "analysis-repair",
+    );
+    const triangles = analysisPath?.dimensions.find(
+      (dimension) => dimension.id === "model-triangles",
+    );
+
+    expect(triangles?.configuredMaximumValue).toBe(1_000_000);
+    expect(triangles?.effectiveMaximumValue).toBeLessThan(1_000_000);
+    expect(triangles?.developmentValue).toBeLessThanOrEqual(
+      triangles?.effectiveMaximumValue ?? 0,
+    );
+    expect(
+      (triangles?.developmentValue ?? 0) /
+        (triangles?.effectiveMaximumValue ?? 1),
+    ).toBeGreaterThanOrEqual(TOOLCRAFT_MODEL_PERFORMANCE_DEVELOPMENT_PRESSURE);
+  });
+
+  it("projects node pressure through the canonical encode memory envelope", () => {
+    const schema = schemaWithControls({
+      source: {
+        assetKind: "model",
+        target: "source.model",
+        type: "fileDrop",
+      },
+    });
+
+    const nodeDimension = deriveToolcraftModelPerformancePaths(schema)[0]
+      ?.dimensions.find((dimension) => dimension.id === "model-nodes");
+
+    expect(nodeDimension?.configuredMaximumValue).toBe(10_000);
+    expect(nodeDimension?.effectiveMaximumValue).toBeLessThan(8_000);
+    expect(nodeDimension?.developmentValue).toBeLessThanOrEqual(
+      nodeDimension?.effectiveMaximumValue ?? 0,
+    );
+  });
+
+  it("uses the nearest admissible integer without dropping below the 80% target", () => {
+    const schema = schemaWithControls({
+      source: {
+        assetKind: "model",
+        modelLimits: {
+          maxBundleFiles: 1,
+          maxDecodedBytes: 3,
+          maxEstimatedWorkerBytes: 3,
+          maxNodes: 3,
+          maxPrimitives: 3,
+          maxSourceBytes: 3,
+          maxTriangles: 3,
+          maxVertices: 3,
+        },
+        target: "source.model",
+        type: "fileDrop",
+      },
+    });
+
+    for (const path of deriveToolcraftModelPerformancePaths(schema)) {
+      expect(path.appearance.fitsWorkerLimit).toBe(false);
+      for (const dimension of path.dimensions) {
+        expect(dimension.developmentValue).toBeLessThanOrEqual(
+          dimension.maximumValue,
+        );
+        expect(dimension.developmentValue / dimension.maximumValue).toBeGreaterThanOrEqual(
+          TOOLCRAFT_MODEL_PERFORMANCE_DEVELOPMENT_PRESSURE,
+        );
+      }
+    }
+  });
+
+  it("does not invent model workloads for non-model uploaders", () => {
+    const schema = schemaWithControls({
+      source: {
+        assetKind: "image",
+        target: "source.image",
+        type: "fileDrop",
+      },
+    });
+
+    expect(deriveToolcraftModelPerformancePaths(schema)).toEqual([]);
+  });
+
+  it("only derives orbit pressure when the built-in orientation control exists", () => {
+    const schema = schemaWithControls({
+      source: {
+        assetKind: "model",
+        target: "source.model",
+        type: "fileDrop",
+      },
+    });
+
+    expect(
+      deriveToolcraftModelPerformancePaths(schema).map((path) => path.kind),
+    ).toEqual(["import", "analysis-repair"]);
+  });
+});