@pooder/kit 6.2.2 → 6.3.1

package/src/extensions/image/commands.ts

@@ -1,4 +1,5 @@
 import type { CommandContribution } from "@pooder/core";
+import type { ImageOperation } from "./imageOperations";
 
 export function createImageCommands(tool: any): CommandContribution[] {
   return [
@@ -23,30 +24,51 @@ export function createImageCommands(tool: any): CommandContribution[] {
       },
     },
     {
-      command: "getWorkingImages",
-      id: "getWorkingImages",
-      title: "Get Working Images",
+      command: "applyImageOperation",
+      id: "applyImageOperation",
+      title: "Apply Image Operation",
+      handler: async (
+        id: string,
+        operation: ImageOperation,
+        options: Record<string, any> = {},
+      ) => {
+        await tool.applyImageOperation(id, operation, options);
+      },
+    },
+    {
+      command: "getImageViewState",
+      id: "getImageViewState",
+      title: "Get Image View State",
       handler: () => {
-        return tool.cloneItems(tool.workingItems);
+        return tool.getImageViewState();
       },
     },
     {
-      command: "setWorkingImage",
-      id: "setWorkingImage",
-      title: "Set Working Image",
-      handler: (id: string, updates: Record<string, any>) => {
-        tool.updateImageInWorking(id, updates);
+      command: "setImageTransform",
+      id: "setImageTransform",
+      title: "Set Image Transform",
+      handler: async (
+        id: string,
+        updates: Record<string, any>,
+        options: Record<string, any> = {},
+      ) => {
+        await tool.setImageTransform(id, updates, options);
       },
     },
     {
-      command: "resetWorkingImages",
-      id: "resetWorkingImages",
-      title: "Reset Working Images",
+      command: "imageSessionReset",
+      id: "imageSessionReset",
+      title: "Reset Image Session",
       handler: () => {
-        tool.workingItems = tool.cloneItems(tool.items);
-        tool.hasWorkingChanges = false;
-        tool.updateImages();
-        tool.emitWorkingChange();
+        tool.resetImageSession();
+      },
+    },
+    {
+      command: "validateImageSession",
+      id: "validateImageSession",
+      title: "Validate Image Session",
+      handler: async () => {
+        return await tool.validateImageSession();
       },
     },
     {
@@ -54,7 +76,7 @@ export function createImageCommands(tool: any): CommandContribution[] {
       id: "completeImages",
       title: "Complete Images",
       handler: async () => {
-        return await tool.commitWorkingImagesAsCropped();
+        return await tool.completeImageSession();
       },
     },
     {
@@ -65,30 +87,6 @@ export function createImageCommands(tool: any): CommandContribution[] {
         return await tool.exportUserCroppedImage(options);
       },
     },
-    {
-      command: "fitImageToArea",
-      id: "fitImageToArea",
-      title: "Fit Image to Area",
-      handler: async (
-        id: string,
-        area: {
-          width: number;
-          height: number;
-          left?: number;
-          top?: number;
-        },
-      ) => {
-        await tool.fitImageToArea(id, area);
-      },
-    },
-    {
-      command: "fitImageToDefaultArea",
-      id: "fitImageToDefaultArea",
-      title: "Fit Image to Default Area",
-      handler: async (id: string) => {
-        await tool.fitImageToDefaultArea(id);
-      },
-    },
     {
       command: "focusImage",
       id: "focusImage",
@@ -105,9 +103,10 @@ export function createImageCommands(tool: any): CommandContribution[] {
       id: "removeImage",
       title: "Remove Image",
       handler: (id: string) => {
-        const removed = tool.items.find((item: any) => item.id === id);
-        const next = tool.items.filter((item: any) => item.id !== id);
-        if (next.length !== tool.items.length) {
+        const sourceItems = tool.isToolActive ? tool.workingItems : tool.items;
+        const removed = sourceItems.find((item: any) => item.id === id);
+        const next = sourceItems.filter((item: any) => item.id !== id);
+        if (next.length !== sourceItems.length) {
           tool.purgeSourceSizeCacheForItem(removed);
           if (tool.focusedImageId === id) {
             tool.setImageFocus(null, {
@@ -115,6 +114,13 @@ export function createImageCommands(tool: any): CommandContribution[] {
               skipRender: true,
             });
           }
+          if (tool.isToolActive) {
+            tool.workingItems = tool.cloneItems(next);
+            tool.hasWorkingChanges = true;
+            tool.updateImages();
+            tool.emitWorkingChange(id);
+            return;
+          }
           tool.updateConfig(next);
         }
       },
@@ -141,6 +147,13 @@ export function createImageCommands(tool: any): CommandContribution[] {
           syncCanvasSelection: true,
           skipRender: true,
         });
+        if (tool.isToolActive) {
+          tool.workingItems = [];
+          tool.hasWorkingChanges = true;
+          tool.updateImages();
+          tool.emitWorkingChange();
+          return;
+        }
         tool.updateConfig([]);
       },
     },
@@ -149,11 +162,19 @@ export function createImageCommands(tool: any): CommandContribution[] {
       id: "bringToFront",
       title: "Bring Image to Front",
       handler: (id: string) => {
-        const index = tool.items.findIndex((item: any) => item.id === id);
-        if (index !== -1 && index < tool.items.length - 1) {
-          const next = [...tool.items];
+        const sourceItems = tool.isToolActive ? tool.workingItems : tool.items;
+        const index = sourceItems.findIndex((item: any) => item.id === id);
+        if (index !== -1 && index < sourceItems.length - 1) {
+          const next = [...sourceItems];
           const [item] = next.splice(index, 1);
           next.push(item);
+          if (tool.isToolActive) {
+            tool.workingItems = tool.cloneItems(next);
+            tool.hasWorkingChanges = true;
+            tool.updateImages();
+            tool.emitWorkingChange(id);
+            return;
+          }
           tool.updateConfig(next);
         }
       },
@@ -163,11 +184,19 @@ export function createImageCommands(tool: any): CommandContribution[] {
       id: "sendToBack",
       title: "Send Image to Back",
       handler: (id: string) => {
-        const index = tool.items.findIndex((item: any) => item.id === id);
+        const sourceItems = tool.isToolActive ? tool.workingItems : tool.items;
+        const index = sourceItems.findIndex((item: any) => item.id === id);
         if (index > 0) {
-          const next = [...tool.items];
+          const next = [...sourceItems];
           const [item] = next.splice(index, 1);
           next.unshift(item);
+          if (tool.isToolActive) {
+            tool.workingItems = tool.cloneItems(next);
+            tool.hasWorkingChanges = true;
+            tool.updateImages();
+            tool.emitWorkingChange(id);
+            return;
+          }
           tool.updateConfig(next);
         }
       },

package/src/extensions/image/config.ts

@@ -124,5 +124,12 @@ export function createImageConfigurations(): ConfigurationContribution[] {
       label: "Image Frame Outer Background",
       default: "#f5f5f5",
     },
+    {
+      id: "image.session.placementPolicy",
+      type: "select",
+      label: "Image Session Placement Policy",
+      options: ["free", "warn", "strict"],
+      default: "free",
+    },
   ];
 }

package/src/extensions/image/imageOperations.ts

@@ -0,0 +1,135 @@
+import type { FrameRect } from "../../shared/scene/frame";
+import {
+  getCoverScale as getCoverScaleFromRect,
+  type SourceSize,
+} from "../../shared/imaging/sourceSizeCache";
+
+export interface ImageOperationArea {
+  width: number;
+  height: number;
+  centerX: number;
+  centerY: number;
+}
+
+export interface ImageOperationViewport {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export type ImageOperationAreaSpec =
+  | { type: "frame" }
+  | { type: "viewport" }
+  | ({
+      type: "custom";
+    } & ImageOperationArea);
+
+export type ImageOperation =
+  | { type: "cover"; area?: ImageOperationAreaSpec }
+  | { type: "contain"; area?: ImageOperationAreaSpec }
+  | { type: "maximizeWidth"; area?: ImageOperationAreaSpec }
+  | { type: "maximizeHeight"; area?: ImageOperationAreaSpec }
+  | { type: "center"; area?: ImageOperationAreaSpec }
+  | { type: "resetTransform" };
+
+export interface ComputeImageOperationArgs {
+  frame: FrameRect;
+  source: SourceSize;
+  operation: ImageOperation;
+  area: ImageOperationArea;
+}
+
+function clampNormalizedAnchor(value: number): number {
+  return Math.max(-1, Math.min(2, value));
+}
+
+function toNormalizedAnchor(center: number, start: number, size: number): number {
+  return clampNormalizedAnchor((center - start) / Math.max(1, size));
+}
+
+function resolveAbsoluteScale(
+  operation: ImageOperation,
+  area: ImageOperationArea,
+  source: SourceSize,
+): number | null {
+  const widthScale = Math.max(1, area.width) / Math.max(1, source.width);
+  const heightScale = Math.max(1, area.height) / Math.max(1, source.height);
+
+  switch (operation.type) {
+    case "cover":
+      return Math.max(widthScale, heightScale);
+    case "contain":
+      return Math.min(widthScale, heightScale);
+    case "maximizeWidth":
+      return widthScale;
+    case "maximizeHeight":
+      return heightScale;
+    default:
+      return null;
+  }
+}
+
+export function resolveImageOperationArea(args: {
+  frame: FrameRect;
+  viewport: ImageOperationViewport;
+  area?: ImageOperationAreaSpec;
+}): ImageOperationArea {
+  const spec = args.area || { type: "frame" };
+
+  if (spec.type === "custom") {
+    return {
+      width: Math.max(1, spec.width),
+      height: Math.max(1, spec.height),
+      centerX: spec.centerX,
+      centerY: spec.centerY,
+    };
+  }
+
+  if (spec.type === "viewport") {
+    return {
+      width: Math.max(1, args.viewport.width),
+      height: Math.max(1, args.viewport.height),
+      centerX: args.viewport.left + args.viewport.width / 2,
+      centerY: args.viewport.top + args.viewport.height / 2,
+    };
+  }
+
+  return {
+    width: Math.max(1, args.frame.width),
+    height: Math.max(1, args.frame.height),
+    centerX: args.frame.left + args.frame.width / 2,
+    centerY: args.frame.top + args.frame.height / 2,
+  };
+}
+
+export function computeImageOperationUpdates(
+  args: ComputeImageOperationArgs,
+): { scale?: number; left?: number; top?: number; angle?: number } {
+  const { frame, source, operation, area } = args;
+
+  if (operation.type === "resetTransform") {
+    return {
+      scale: 1,
+      left: 0.5,
+      top: 0.5,
+      angle: 0,
+    };
+  }
+
+  const left = toNormalizedAnchor(area.centerX, frame.left, frame.width);
+  const top = toNormalizedAnchor(area.centerY, frame.top, frame.height);
+
+  if (operation.type === "center") {
+    return { left, top };
+  }
+
+  const absoluteScale = resolveAbsoluteScale(operation, area, source);
+  const coverScale = getCoverScaleFromRect(frame, source);
+
+  return {
+    scale: Math.max(0.05, (absoluteScale || coverScale) / coverScale),
+    left,
+    top,
+  };
+}

package/src/extensions/image/imagePlacement.ts

@@ -0,0 +1,78 @@
+import type { FrameRect } from "../../shared/scene/frame";
+import {
+  getCoverScale as getCoverScaleFromRect,
+  type SourceSize,
+} from "../../shared/imaging/sourceSizeCache";
+
+export interface ImagePlacementState {
+  left: number;
+  top: number;
+  scale: number;
+  angle: number;
+}
+
+export interface ImagePlacementValidationArgs {
+  frame: FrameRect;
+  source: SourceSize;
+  placement: ImagePlacementState;
+}
+
+export interface ImagePlacementValidationResult {
+  ok: boolean;
+}
+
+function toRadians(angle: number): number {
+  return (angle * Math.PI) / 180;
+}
+
+export function validateImagePlacement(
+  args: ImagePlacementValidationArgs,
+): ImagePlacementValidationResult {
+  const { frame, source, placement } = args;
+  if (
+    frame.width <= 0 ||
+    frame.height <= 0 ||
+    source.width <= 0 ||
+    source.height <= 0
+  ) {
+    return { ok: true };
+  }
+
+  const coverScale = getCoverScaleFromRect(frame, source);
+  const imageWidth =
+    source.width * coverScale * Math.max(0.05, Number(placement.scale || 1));
+  const imageHeight =
+    source.height * coverScale * Math.max(0.05, Number(placement.scale || 1));
+
+  if (imageWidth <= 0 || imageHeight <= 0) {
+    return { ok: true };
+  }
+
+  const centerX = frame.left + placement.left * frame.width;
+  const centerY = frame.top + placement.top * frame.height;
+  const halfWidth = imageWidth / 2;
+  const halfHeight = imageHeight / 2;
+  const radians = toRadians(placement.angle || 0);
+  const cos = Math.cos(radians);
+  const sin = Math.sin(radians);
+
+  const frameCorners = [
+    { x: frame.left, y: frame.top },
+    { x: frame.left + frame.width, y: frame.top },
+    { x: frame.left + frame.width, y: frame.top + frame.height },
+    { x: frame.left, y: frame.top + frame.height },
+  ];
+
+  const coversFrame = frameCorners.every((corner) => {
+    const dx = corner.x - centerX;
+    const dy = corner.y - centerY;
+    const localX = dx * cos + dy * sin;
+    const localY = -dx * sin + dy * cos;
+    return (
+      Math.abs(localX) <= halfWidth + 1e-6 &&
+      Math.abs(localY) <= halfHeight + 1e-6
+    );
+  });
+
+  return { ok: coversFrame };
+}

package/src/extensions/image/index.ts

@@ -1,5 +1,6 @@
 export * from "./ImageTool";
 export * from "./commands";
 export * from "./config";
+export * from "./imageOperations";
 export * from "./model";
 export * from "./renderer";

package/src/extensions/image/model.ts

@@ -1 +1,13 @@
-export type { ImageItem } from "./ImageTool";
+export type {
+  ImageItem,
+  ImageTransformUpdates,
+  ImageViewState,
+} from "./ImageTool";
+
+import type { ImageViewState } from "./ImageTool";
+
+export function hasAnyImageInViewState(
+  state: ImageViewState | null | undefined,
+): boolean {
+  return Boolean(state?.hasAnyImage);
+}

package/tests/run.ts

@@ -25,6 +25,7 @@ import {
   normalizePointInGeometry,
   resolveFeaturePosition,
 } from "../src/extensions/featureCoordinates";
+import { hasAnyImageInViewState } from "../src/extensions/image/model";
 
 function assert(condition: unknown, message: string) {
   if (!condition) throw new Error(message);
@@ -32,7 +33,10 @@ function assert(condition: unknown, message: string) {
 
 function testWrappedOffsets() {
   assert(wrappedDistance(100, 10, 30) === 20, "distance 10->30 should be 20");
-  assert(wrappedDistance(100, 90, 10) === 20, "distance 90->10 should wrap to 20");
+  assert(
+    wrappedDistance(100, 90, 10) === 20,
+    "distance 90->10 should wrap to 20",
+  );
 
   const a = sampleWrappedOffsets(100, 10, 30, 5);
   assert(
@@ -75,9 +79,18 @@ function testMaskOps() {
 
   const r = findMinimalConnectRadius(mask, width, height, 20);
   const closed = circularMorphology(mask, width, height, r, "closing");
-  assert(isMaskConnected8(closed, width, height), `closed mask should be connected (r=${r})`);
+  assert(
+    isMaskConnected8(closed, width, height),
+    `closed mask should be connected (r=${r})`,
+  );
   if (r > 0) {
-    const closedPrev = circularMorphology(mask, width, height, r - 1, "closing");
+    const closedPrev = circularMorphology(
+      mask,
+      width,
+      height,
+      r - 1,
+      "closing",
+    );
     assert(
       !isMaskConnected8(closedPrev, width, height),
       `r should be minimal (r=${r})`,
@@ -96,10 +109,12 @@ function testMaskOps() {
 
   const imgW = 2;
   const imgH = 1;
-  const rgba = new Uint8ClampedArray([
-    255, 255, 255, 255, 10, 10, 10, 254,
-  ]);
-  const imageData = { width: imgW, height: imgH, data: rgba } as unknown as ImageData;
+  const rgba = new Uint8ClampedArray([255, 255, 255, 255, 10, 10, 10, 254]);
+  const imageData = {
+    width: imgW,
+    height: imgH,
+    data: rgba,
+  } as unknown as ImageData;
   const paddedWidth = imgW + 4;
   const paddedHeight = imgH + 4;
   const created = createMask(imageData, {
@@ -110,15 +125,25 @@ function testMaskOps() {
     maskMode: "auto",
     alphaOpaqueCutoff: 250,
   });
-  assert(created[2 * paddedWidth + 2] === 0, "white pixel should be background");
-  assert(created[2 * paddedWidth + 3] === 1, "non-white pixel should be foreground");
+  assert(
+    created[2 * paddedWidth + 2] === 0,
+    "white pixel should be background",
+  );
+  assert(
+    created[2 * paddedWidth + 3] === 1,
+    "non-white pixel should be foreground",
+  );
 }
 
 function testEdgeScale() {
   const currentMax = 100;
   const baseBounds = { width: 50, height: 20 };
   const expandedBounds = { width: 70, height: 40 };
-  const { width, height, scale } = computeDetectEdgeSize(currentMax, baseBounds, expandedBounds);
+  const { width, height, scale } = computeDetectEdgeSize(
+    currentMax,
+    baseBounds,
+    expandedBounds,
+  );
   assert(scale === 2, `expected scale 2, got ${scale}`);
   assert(width === 140, `expected width 140, got ${width}`);
   assert(height === 80, `expected height 80, got ${height}`);
@@ -288,6 +313,53 @@ function testVisibilityDsl() {
   );
 }
 
+function testImageViewStateHelper() {
+  assert(
+    hasAnyImageInViewState(null) === false,
+    "null image state should be empty",
+  );
+  assert(
+    hasAnyImageInViewState({
+      items: [],
+      hasAnyImage: false,
+      focusedId: null,
+      focusedItem: null,
+      isToolActive: false,
+      isImageSelectionActive: false,
+      hasWorkingChanges: false,
+      source: "committed",
+      placementPolicy: "free",
+      sessionNotice: null,
+    }) === false,
+    "empty image state should report false",
+  );
+  assert(
+    hasAnyImageInViewState({
+      items: [
+        {
+          id: "img-1",
+          url: "blob:test",
+          opacity: 1,
+        },
+      ],
+      hasAnyImage: true,
+      focusedId: "img-1",
+      focusedItem: {
+        id: "img-1",
+        url: "blob:test",
+        opacity: 1,
+      },
+      isToolActive: true,
+      isImageSelectionActive: true,
+      hasWorkingChanges: true,
+      source: "working",
+      placementPolicy: "free",
+      sessionNotice: null,
+    }) === true,
+    "non-empty image state should report true",
+  );
+}
+
 function testContributionCompatibility() {
   const imageCommandNames = createImageCommands({} as any).map(
     (entry) => entry.command,
@@ -303,13 +375,13 @@ function testContributionCompatibility() {
   const expectedImageCommands = [
     "addImage",
     "upsertImage",
-    "getWorkingImages",
-    "setWorkingImage",
-    "resetWorkingImages",
+    "applyImageOperation",
+    "getImageViewState",
+    "setImageTransform",
+    "imageSessionReset",
+    "validateImageSession",
     "completeImages",
     "exportUserCroppedImage",
-    "fitImageToArea",
-    "fitImageToDefaultArea",
     "focusImage",
     "removeImage",
     "updateImage",
@@ -387,6 +459,7 @@ function testContributionCompatibility() {
     "image.frame.dashLength",
     "image.frame.innerBackground",
     "image.frame.outerBackground",
+    "image.session.placementPolicy",
   ];
   const expectedWhiteInkConfigKeys = [
     "whiteInk.items",
@@ -434,6 +507,7 @@ function main() {
   testEdgeScale();
   testFeaturePlacementProjection();
   testVisibilityDsl();
+  testImageViewStateHelper();
   testContributionCompatibility();
   console.log("ok");
 }