@pooder/kit 6.3.0 → 6.3.1

package/src/extensions/image/ImageTool.ts

@@ -44,6 +44,7 @@ import {
   resolveImageOperationArea,
   type ImageOperation,
 } from "./imageOperations";
+import { validateImagePlacement } from "./imagePlacement";
 import { buildImageSessionOverlaySpecs } from "./sessionOverlay";
 
 export interface ImageItem {
@@ -75,6 +76,18 @@ export interface ImageViewState {
   isImageSelectionActive: boolean;
   hasWorkingChanges: boolean;
   source: "working" | "committed";
+  placementPolicy: ImageSessionPlacementPolicy;
+  sessionNotice: ImageSessionNotice | null;
+}
+
+export type ImageSessionPlacementPolicy = "free" | "warn" | "strict";
+
+export interface ImageSessionNotice {
+  code: "image-outside-frame";
+  level: "warning" | "error";
+  message: string;
+  imageIds: string[];
+  policy: ImageSessionPlacementPolicy;
 }
 
 interface RenderImageState {
@@ -238,6 +251,7 @@ export class ImageTool implements Extension {
   private activeSnapX: SnapMatch | null = null;
   private activeSnapY: SnapMatch | null = null;
   private movingImageId: string | null = null;
+  private sessionNotice: ImageSessionNotice | null = null;
   private hasRenderedSnapGuides = false;
   private canvasObjectMovingHandler?: (e: any) => void;
   private canvasMouseUpHandler?: (e: any) => void;
@@ -349,8 +363,12 @@ export class ImageTool implements Extension {
           if (
             e.key.startsWith("size.") ||
             e.key.startsWith("image.frame.") ||
+            e.key.startsWith("image.session.") ||
             e.key.startsWith("image.control.")
           ) {
+            if (e.key === "image.session.placementPolicy") {
+              this.clearSessionNotice();
+            }
             if (e.key.startsWith("image.control.")) {
               this.imageControlsByCapabilityKey.clear();
             }
@@ -951,6 +969,7 @@ export class ImageTool implements Extension {
           interaction: "session",
           commands: {
             begin: "imageSessionReset",
+            validate: "validateImageSession",
             commit: "completeImages",
             rollback: "imageSessionReset",
           },
@@ -1001,6 +1020,47 @@ export class ImageTool implements Extension {
     return this.isToolActive ? this.workingItems : this.items;
   }
 
+  private getPlacementPolicy(): ImageSessionPlacementPolicy {
+    const policy = this.getConfig<ImageSessionPlacementPolicy>(
+      "image.session.placementPolicy",
+      "free",
+    );
+    return policy === "warn" || policy === "strict" ? policy : "free";
+  }
+
+  private areSessionNoticesEqual(
+    a: ImageSessionNotice | null,
+    b: ImageSessionNotice | null,
+  ): boolean {
+    if (!a && !b) return true;
+    if (!a || !b) return false;
+    return (
+      a.code === b.code &&
+      a.level === b.level &&
+      a.message === b.message &&
+      a.policy === b.policy &&
+      JSON.stringify(a.imageIds) === JSON.stringify(b.imageIds)
+    );
+  }
+
+  private setSessionNotice(
+    notice: ImageSessionNotice | null,
+    options: { emit?: boolean } = {},
+  ) {
+    if (this.areSessionNoticesEqual(this.sessionNotice, notice)) {
+      return;
+    }
+    this.sessionNotice = notice;
+    if (options.emit !== false) {
+      this.context?.eventBus.emit("image:session:notice", this.sessionNotice);
+      this.emitImageStateChange();
+    }
+  }
+
+  private clearSessionNotice(options: { emit?: boolean } = {}) {
+    this.setSessionNotice(null, options);
+  }
+
   private getImageViewState(): ImageViewState {
     this.syncToolActiveFromWorkbench();
     const items = this.cloneItems(this.getViewItems());
@@ -1018,6 +1078,8 @@ export class ImageTool implements Extension {
       isImageSelectionActive: this.isImageSelectionActive,
       hasWorkingChanges: this.hasWorkingChanges,
       source: this.isToolActive ? "working" : "committed",
+      placementPolicy: this.getPlacementPolicy(),
+      sessionNotice: this.sessionNotice,
     };
   }
 
@@ -1085,6 +1147,7 @@ export class ImageTool implements Extension {
     operation?: ImageOperation,
   ): Promise<string> {
     this.syncToolActiveFromWorkbench();
+    this.clearSessionNotice({ emit: false });
     const id = this.generateId();
     const newItem = this.normalizeItem({
       id,
@@ -1153,7 +1216,11 @@ export class ImageTool implements Extension {
       return { id: targetId, mode: "replace" };
     }
 
-    const id = await this.addImageEntry(url, options.addOptions, options.operation);
+    const id = await this.addImageEntry(
+      url,
+      options.addOptions,
+      options.operation,
+    );
     return { id, mode: "add" };
   }
 
@@ -1200,6 +1267,7 @@ export class ImageTool implements Extension {
 
   private updateConfig(newItems: ImageItem[], skipCanvasUpdate = false) {
     if (!this.context) return;
+    this.clearSessionNotice({ emit: false });
     this.applyCommittedItems(newItems);
     runDeferredConfigUpdate(
       this,
@@ -1313,6 +1381,82 @@ export class ImageTool implements Extension {
     return getCoverScaleFromRect(frame, size);
   }
 
+  private resolvePlacementState(item: ImageItem) {
+    return {
+      left: Number.isFinite(item.left as any) ? (item.left as number) : 0.5,
+      top: Number.isFinite(item.top as any) ? (item.top as number) : 0.5,
+      scale: Math.max(0.05, item.scale ?? 1),
+      angle: Number.isFinite(item.angle as any) ? (item.angle as number) : 0,
+    };
+  }
+
+  private async validatePlacementForItem(item: ImageItem): Promise<boolean> {
+    const frame = this.getFrameRect();
+    if (!frame.width || !frame.height) {
+      return true;
+    }
+
+    const src = item.sourceUrl || item.url;
+    if (!src) {
+      return true;
+    }
+
+    const source = await this.resolveImageSourceSize(item.id, src);
+    if (!source) {
+      return true;
+    }
+
+    return validateImagePlacement({
+      frame,
+      source,
+      placement: this.resolvePlacementState(item),
+    }).ok;
+  }
+
+  private async validateImageSession() {
+    const policy = this.getPlacementPolicy();
+    if (policy === "free") {
+      this.clearSessionNotice();
+      return { ok: true, policy };
+    }
+
+    const invalidImageIds: string[] = [];
+    for (const item of this.workingItems) {
+      const valid = await this.validatePlacementForItem(item);
+      if (!valid) {
+        invalidImageIds.push(item.id);
+      }
+    }
+
+    if (!invalidImageIds.length) {
+      this.clearSessionNotice();
+      return { ok: true, policy };
+    }
+
+    const notice: ImageSessionNotice = {
+      code: "image-outside-frame",
+      level: policy === "strict" ? "error" : "warning",
+      message:
+        policy === "strict"
+          ? "图片位置不能超出 frame，请调整后再提交。"
+          : "图片位置已超出 frame，建议调整后再提交。",
+      imageIds: invalidImageIds,
+      policy,
+    };
+    this.setSessionNotice(notice);
+    this.setImageFocus(invalidImageIds[0], {
+      syncCanvasSelection: true,
+      skipRender: true,
+    });
+    return {
+      ok: policy !== "strict",
+      reason: notice.code,
+      message: notice.message,
+      imageIds: notice.imageIds,
+      policy: notice.policy,
+    };
+  }
+
   private getFrameVisualConfig(): FrameVisualConfig {
     const strokeStyleRaw = (this.getConfig<string>(
       "image.frame.strokeStyle",
@@ -1657,6 +1801,7 @@ export class ImageTool implements Extension {
   }
 
   private resetImageSession() {
+    this.clearSessionNotice({ emit: false });
     this.workingItems = this.cloneItems(this.items);
     this.hasWorkingChanges = false;
     this.updateImages();
@@ -1706,6 +1851,7 @@ export class ImageTool implements Extension {
     const index = this.workingItems.findIndex((item) => item.id === id);
     if (index < 0) return;
 
+    this.clearSessionNotice({ emit: false });
     const next = [...this.workingItems];
     next[index] = this.normalizeItem({ ...next[index], ...updates });
     this.workingItems = next;
@@ -1724,6 +1870,7 @@ export class ImageTool implements Extension {
     const index = this.items.findIndex((item) => item.id === id);
     if (index < 0) return;
 
+    this.clearSessionNotice({ emit: false });
     const replacingSource =
       typeof updates.url === "string" && updates.url.length > 0;
     const next = [...this.items];
@@ -1868,12 +2015,44 @@ export class ImageTool implements Extension {
     }
 
     this.hasWorkingChanges = false;
+    this.clearSessionNotice({ emit: false });
     this.workingItems = this.cloneItems(next);
     this.updateConfig(next);
     this.emitWorkingChange(this.focusedImageId);
     return { ok: true };
   }
 
+  private async completeImageSession() {
+    const sessionState =
+      this.context?.services.get<ToolSessionService>("ToolSessionService");
+    const workbench = this.context?.services.get<any>("WorkbenchService");
+    console.info("[ImageTool] completeImageSession:start", {
+      activeToolId: workbench?.activeToolId ?? null,
+      isToolActive: this.isToolActive,
+      dirtyBeforeComplete: this.hasWorkingChanges,
+      workingCount: this.workingItems.length,
+      committedCount: this.items.length,
+      sessionDirty: sessionState?.isDirty(this.id),
+    });
+    const validation = await this.validateImageSession();
+    if (!validation.ok) {
+      console.warn("[ImageTool] completeImageSession:validation-failed", {
+        validation,
+        dirtyAfterValidation: this.hasWorkingChanges,
+      });
+      return validation;
+    }
+    const result = await this.commitWorkingImagesAsCropped();
+    console.info("[ImageTool] completeImageSession:done", {
+      result,
+      dirtyAfterComplete: this.hasWorkingChanges,
+      workingCount: this.workingItems.length,
+      committedCount: this.items.length,
+      sessionDirty: sessionState?.isDirty(this.id),
+    });
+    return result;
+  }
+
   private async exportCroppedImageByIds(
     imageIds: string[],
     options: ExportCroppedImageOptions,

package/src/extensions/image/commands.ts

@@ -63,12 +63,20 @@ export function createImageCommands(tool: any): CommandContribution[] {
         tool.resetImageSession();
       },
     },
+    {
+      command: "validateImageSession",
+      id: "validateImageSession",
+      title: "Validate Image Session",
+      handler: async () => {
+        return await tool.validateImageSession();
+      },
+    },
     {
       command: "completeImages",
       id: "completeImages",
       title: "Complete Images",
       handler: async () => {
-        return await tool.commitWorkingImagesAsCropped();
+        return await tool.completeImageSession();
       },
     },
     {

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/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/tests/run.ts

@@ -33,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(
@@ -76,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})`,
@@ -97,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, {
@@ -111,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}`);
@@ -290,7 +314,10 @@ function testVisibilityDsl() {
 }
 
 function testImageViewStateHelper() {
-  assert(hasAnyImageInViewState(null) === false, "null image state should be empty");
+  assert(
+    hasAnyImageInViewState(null) === false,
+    "null image state should be empty",
+  );
   assert(
     hasAnyImageInViewState({
       items: [],
@@ -301,6 +328,8 @@ function testImageViewStateHelper() {
       isImageSelectionActive: false,
       hasWorkingChanges: false,
       source: "committed",
+      placementPolicy: "free",
+      sessionNotice: null,
     }) === false,
     "empty image state should report false",
   );
@@ -324,6 +353,8 @@ function testImageViewStateHelper() {
       isImageSelectionActive: true,
       hasWorkingChanges: true,
       source: "working",
+      placementPolicy: "free",
+      sessionNotice: null,
     }) === true,
     "non-empty image state should report true",
   );
@@ -348,6 +379,7 @@ function testContributionCompatibility() {
     "getImageViewState",
     "setImageTransform",
     "imageSessionReset",
+    "validateImageSession",
     "completeImages",
     "exportUserCroppedImage",
     "focusImage",
@@ -427,6 +459,7 @@ function testContributionCompatibility() {
     "image.frame.dashLength",
     "image.frame.innerBackground",
     "image.frame.outerBackground",
+    "image.session.placementPolicy",
   ];
   const expectedWhiteInkConfigKeys = [
     "whiteInk.items",
@@ -472,10 +505,10 @@ function main() {
   testBridgeSelection();
   testMaskOps();
   testEdgeScale();
-testFeaturePlacementProjection();
-testVisibilityDsl();
-testImageViewStateHelper();
-testContributionCompatibility();
+  testFeaturePlacementProjection();
+  testVisibilityDsl();
+  testImageViewStateHelper();
+  testContributionCompatibility();
   console.log("ok");
 }