@we-are-singular/svelte-chop-chop 0.1.0 → 1.0.0

package/README.md

@@ -1,10 +1,10 @@
 # svelte-chop-chop
 
-> Headless-first image cropping and editing SDK for Svelte 5.  
+> Headless-first image cropping and editing SDK for Svelte 5.
 > Zero dependencies beyond Svelte.
 
 [![npm](https://img.shields.io/npm/v/@we-are-singular/svelte-chop-chop)](https://www.npmjs.com/package/@we-are-singular/svelte-chop-chop)
-[![license](https://img.shields.io/github/license/we-are-singular/svelte-chop-chop)](LICENSE)
+[![license](https://img.shields.io/github/license/we-are-singular/svelte-chop-chop?cache=0)](LICENSE)
 
 **[Documentation & Demo →](https://svelte-chop-chop.pages.dev)**
 
@@ -78,18 +78,19 @@ npm install @we-are-singular/svelte-chop-chop
 
 ## Cropper Props
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `src` | `ImageSource` | — | URL, data URL, `File`, `Blob`, or `HTMLImageElement` |
-| `aspectRatio` | `number \| { min?: number; max?: number } \| null` | `null` | Aspect ratio constraint |
-| `sizeConstraints` | `SizeConstraints` | — | Min/max width/height in pixels |
-| `grid` | `"none" \| "rule-of-thirds" \| "grid" \| "golden-ratio"` | `"rule-of-thirds"` | Grid overlay |
-| `transitions` | `boolean` | `true` | CSS transitions |
-| `stencil` | `Component` | `CropStencil` | Custom stencil component |
-| `readOnly` | `boolean` | `false` | Disable interaction |
-| `class` / `style` | `string` | `''` | Root element styling |
-
-**Bindable:** `coordinates` (`CropCoordinates`), `transforms` (`TransformState`)  
+| Prop               | Type                                                     | Default            | Description                                                 |
+| ------------------ | -------------------------------------------------------- | ------------------ | ----------------------------------------------------------- |
+| `src`              | `ImageSource`                                            | —                  | URL, data URL, `File`, `Blob`, or `HTMLImageElement`        |
+| `aspectRatio`      | `number \| { min?: number; max?: number } \| null`       | `null`             | Aspect ratio constraint                                     |
+| `sizeConstraints`  | `SizeConstraints`                                        | —                  | Min/max width/height in pixels                              |
+| `initialCropScale` | `number`                                                 | `1`                | Initial crop as fraction of image (0–1). 0.8 = 80% centered |
+| `grid`             | `"none" \| "rule-of-thirds" \| "grid" \| "golden-ratio"` | `"rule-of-thirds"` | Grid overlay                                                |
+| `transitions`      | `boolean`                                                | `true`             | CSS transitions                                             |
+| `stencil`          | `Component`                                              | `CropStencil`      | Custom stencil component                                    |
+| `readOnly`         | `boolean`                                                | `false`            | Disable interaction                                         |
+| `class` / `style`  | `string`                                                 | `''`               | Root element styling                                        |
+
+**Bindable:** `coordinates` (`CropCoordinates`), `transforms` (`TransformState`)
 **Events:** `onchange`, `onready`, `onerror`
 
 ---
@@ -97,20 +98,20 @@ npm install @we-are-singular/svelte-chop-chop
 ## Headless Usage
 
 ```typescript
-import { createCropper } from '@we-are-singular/svelte-chop-chop/headless';
-import { createImageEditor } from '@we-are-singular/svelte-chop-chop';
+import { createCropper } from "@we-are-singular/svelte-chop-chop/headless";
+import { createImageEditor } from "@we-are-singular/svelte-chop-chop";
 
-// Lightweight cropper
+// Lightweight cropper (export uses full resolution — original image pixels)
 const cropper = createCropper({ aspectRatio: 16 / 9 });
-await cropper.loadImage('/photo.jpg');
-const result = await cropper.export({ format: 'image/webp', quality: 0.9 });
+await cropper.loadImage("/photo.jpg");
+const result = await cropper.export({ format: "image/webp", quality: 0.9 });
 
 // Full editor
 const editor = createImageEditor({ plugins: [pluginFilters()] });
-await editor.loadImage('/photo.jpg');
-editor.applyFilter('clarendon');
+await editor.loadImage("/photo.jpg");
+editor.applyFilter("clarendon");
 editor.rotate(90);
-const result = await editor.export({ format: 'image/webp', quality: 0.9 });
+const result = await editor.export({ format: "image/webp", quality: 0.9 });
 // result.blob, result.dataURL, result.canvas, result.coordinates
 ```
 
@@ -118,34 +119,36 @@ const result = await editor.export({ format: 'image/webp', quality: 0.9 });
 
 ## Plugins
 
-| Import | Description |
-|--------|-------------|
-| `@we-are-singular/svelte-chop-chop/plugins/filters` | 16 Instagram-style color filter presets |
-| `@we-are-singular/svelte-chop-chop/plugins/finetune` | Brightness, contrast, saturation, exposure, etc. |
-| `@we-are-singular/svelte-chop-chop/plugins/frame` | Decorative frame at export (solid, line, hook) |
-| `@we-are-singular/svelte-chop-chop/plugins/watermark` | Text watermark at export |
-| `@we-are-singular/svelte-chop-chop/plugins/resize` | Output width/height controls |
+| Import                                                | Description                                      |
+| ----------------------------------------------------- | ------------------------------------------------ |
+| `@we-are-singular/svelte-chop-chop/plugins/filters`   | 16 Instagram-style color filter presets          |
+| `@we-are-singular/svelte-chop-chop/plugins/finetune`  | Brightness, contrast, saturation, exposure, etc. |
+| `@we-are-singular/svelte-chop-chop/plugins/frame`     | Decorative frame at export (solid, line, hook)   |
+| `@we-are-singular/svelte-chop-chop/plugins/watermark` | Text watermark at export                         |
+| `@we-are-singular/svelte-chop-chop/plugins/resize`    | Output width/height controls                     |
 
 ### Custom Plugin
 
 ```typescript
-import type { ChopPlugin } from '@we-are-singular/svelte-chop-chop';
+import type { ChopPlugin } from "@we-are-singular/svelte-chop-chop";
 
 const myPlugin: ChopPlugin = {
-  name: 'my-plugin',
+  name: "my-plugin",
   setup(ctx) {
     ctx.registerAction({
-      id: 'my-action',
-      label: 'My Action',
-      group: 'tabs',
-      execute: () => ctx.showPanel('my-panel'),
+      id: "my-action",
+      label: "My Action",
+      group: "tabs",
+      execute: () => ctx.showPanel("my-panel"),
     });
 
     ctx.registerPostProcessor(async (drawCtx, canvas) => {
       // draw on canvas at export time
     });
 
-    return () => { /* cleanup */ };
+    return () => {
+      /* cleanup */
+    };
   },
 };
 ```
@@ -161,18 +164,18 @@ import { profilePicture, coverPhoto, productImage } from '@we-are-singular/svelt
 <Cropper src="/photo.jpg" {...profilePicture} />
 ```
 
-| Preset | Aspect | Max Size | Format |
-|--------|--------|----------|--------|
-| `profilePicture` | 1:1 | 512px | JPEG |
-| `coverPhoto` | 16:9 | min 1200px wide | JPEG |
-| `productImage` | 1:1 | — | PNG |
+| Preset           | Aspect | Max Size        | Format |
+| ---------------- | ------ | --------------- | ------ |
+| `profilePicture` | 1:1    | 512px           | JPEG   |
+| `coverPhoto`     | 16:9   | min 1200px wide | JPEG   |
+| `productImage`   | 1:1    | —               | PNG    |
 
 ---
 
 ## Theming
 
 ```css
-@import '@we-are-singular/svelte-chop-chop/themes/default'; /* or dark, minimal */
+@import "@we-are-singular/svelte-chop-chop/themes/default"; /* or dark, minimal */
 ```
 
 Override any CSS custom property:
@@ -191,30 +194,30 @@ Override any CSS custom property:
 
 ## Package Exports
 
-| Path | Description |
-|------|-------------|
-| `@we-are-singular/svelte-chop-chop` | Components, composables, types |
-| `@we-are-singular/svelte-chop-chop/headless` | `createCropper` composable |
-| `@we-are-singular/svelte-chop-chop/plugins` | All plugin factories |
-| `@we-are-singular/svelte-chop-chop/presets` | Preset bundles |
-| `@we-are-singular/svelte-chop-chop/themes/default` | Default CSS theme |
-| `@we-are-singular/svelte-chop-chop/themes/dark` | Dark CSS theme |
-| `@we-are-singular/svelte-chop-chop/themes/minimal` | Minimal CSS theme |
+| Path                                               | Description                    |
+| -------------------------------------------------- | ------------------------------ |
+| `@we-are-singular/svelte-chop-chop`                | Components, composables, types |
+| `@we-are-singular/svelte-chop-chop/headless`       | `createCropper` composable     |
+| `@we-are-singular/svelte-chop-chop/plugins`        | All plugin factories           |
+| `@we-are-singular/svelte-chop-chop/presets`        | Preset bundles                 |
+| `@we-are-singular/svelte-chop-chop/themes/default` | Default CSS theme              |
+| `@we-are-singular/svelte-chop-chop/themes/dark`    | Dark CSS theme                 |
+| `@we-are-singular/svelte-chop-chop/themes/minimal` | Minimal CSS theme              |
 
 ---
 
 ## Keyboard Shortcuts
 
-| Key | Action |
-|-----|--------|
-| `R` / `Shift+R` | Rotate 90° CW / CCW |
-| `H` / `V` | Flip horizontal / vertical |
-| `Ctrl+Z` / `Ctrl+Shift+Z` | Undo / Redo |
-| `+` / `-` | Zoom in / out |
-| `0` | Reset crop to image bounds |
-| `Escape` | Reset all transforms |
-| `Ctrl+F` | Toggle filters panel |
-| Arrow keys | Move crop 1px (10px with Shift) |
+| Key                       | Action                          |
+| ------------------------- | ------------------------------- |
+| `R` / `Shift+R`           | Rotate 90° CW / CCW             |
+| `H` / `V`                 | Flip horizontal / vertical      |
+| `Ctrl+Z` / `Ctrl+Shift+Z` | Undo / Redo                     |
+| `+` / `-`                 | Zoom in / out                   |
+| `0`                       | Reset crop to image bounds      |
+| `Escape`                  | Reset all transforms            |
+| `Ctrl+F`                  | Toggle filters panel            |
+| Arrow keys                | Move crop 1px (10px with Shift) |
 
 ---
 

package/dist/components/CircleStencil.svelte

@@ -3,9 +3,9 @@
   Same contract as CropStencil, but with circular mask.
 -->
 <script lang="ts">
-  import type { HandlePosition, Point, StencilProps } from '../core/types.js';
-  import { createDragHandler } from '../core/interactions.js';
-  import DragHandle from './DragHandle.svelte';
+  import type { HandlePosition, Point, StencilProps } from "../core/types.js";
+  import { createDragHandler } from "../core/interactions.js";
+  import DragHandle from "./DragHandle.svelte";
 
   let {
     rect,
@@ -29,11 +29,13 @@
     onMove: (delta) => onmove(delta),
   });
 
+  const maskId = $state(`chop-circle-mask-${crypto.randomUUID()}`);
+
   // The circle is inscribed in a 1:1 square bounding rect.
   // cx/cy are used for the circle border positioning only.
   const size = $derived(Math.min(rect.width, rect.height));
-  const cx   = $derived(rect.width / 2);
-  const cy   = $derived(rect.height / 2);
+  const cx = $derived(rect.width / 2);
+  const cy = $derived(rect.height / 2);
 </script>
 
 <div
@@ -51,14 +53,9 @@
 >
   <svg class="chop-circle-overlay" aria-hidden="true">
     <defs>
-      <mask id="chop-circle-mask">
+      <mask id={maskId}>
         <rect x="0" y="0" width="100%" height="100%" fill="white" />
-        <circle
-          cx="{cx}"
-          cy="{cy}"
-          r="{size / 2}"
-          fill="black"
-        />
+        <circle {cx} {cy} r={size / 2} fill="black" />
       </mask>
     </defs>
     <rect
@@ -67,7 +64,7 @@
       width="100%"
       height="100%"
       fill="var(--chop-overlay, rgba(0, 0, 0, 0.55))"
-      mask="url(#chop-circle-mask)"
+      mask="url(#{maskId})"
     />
   </svg>
 
@@ -82,10 +79,34 @@
   ></div>
 
   <!-- Handles at the 4 bounding-box corners — correct for a 1:1 square crop with circular mask -->
-  <DragHandle position="nw" {onresize} {onresizestart} {onresizeend} size={16} />
-  <DragHandle position="ne" {onresize} {onresizestart} {onresizeend} size={16} />
-  <DragHandle position="sw" {onresize} {onresizestart} {onresizeend} size={16} />
-  <DragHandle position="se" {onresize} {onresizestart} {onresizeend} size={16} />
+  <DragHandle
+    position="nw"
+    {onresize}
+    {onresizestart}
+    {onresizeend}
+    size={16}
+  />
+  <DragHandle
+    position="ne"
+    {onresize}
+    {onresizestart}
+    {onresizeend}
+    size={16}
+  />
+  <DragHandle
+    position="sw"
+    {onresize}
+    {onresizestart}
+    {onresizeend}
+    size={16}
+  />
+  <DragHandle
+    position="se"
+    {onresize}
+    {onresizestart}
+    {onresizeend}
+    size={16}
+  />
 </div>
 
 <style>

package/dist/components/CircleStencil.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { HandlePosition, Point, StencilProps } from '../core/types.js';
+import type { HandlePosition, Point, StencilProps } from "../core/types.js";
 type $$ComponentProps = StencilProps & {
     onmove: (delta: Point) => void;
     onresize: (handle: HandlePosition, delta: Point) => void;

package/dist/components/CropOverlay.svelte

@@ -4,10 +4,11 @@
   Positioned to cover imageBounds; cutout at rect.
 -->
 <script lang="ts">
-  import type { Rect } from '../core/types.js';
+  import type { Rect } from "../core/types.js";
 
   let { rect, imageBounds }: { rect: Rect; imageBounds: Rect } = $props();
 
+  const maskId = $state(`chop-crop-mask-${crypto.randomUUID()}`);
   const maskX = $derived(rect.x - imageBounds.x);
   const maskY = $derived(rect.y - imageBounds.y);
 </script>
@@ -21,13 +22,13 @@
   style:height="{imageBounds.height}px"
 >
   <defs>
-    <mask id="chop-crop-mask">
+    <mask id={maskId}>
       <rect x="0" y="0" width="100%" height="100%" fill="white" />
       <rect
-        x="{maskX}"
-        y="{maskY}"
-        width="{rect.width}"
-        height="{rect.height}"
+        x={maskX}
+        y={maskY}
+        width={rect.width}
+        height={rect.height}
         fill="black"
       />
     </mask>
@@ -38,7 +39,7 @@
     width="100%"
     height="100%"
     fill="var(--chop-overlay, rgba(0, 0, 0, 0.55))"
-    mask="url(#chop-crop-mask)"
+    mask="url(#{maskId})"
   />
 </svg>
 

package/dist/components/CropOverlay.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { Rect } from '../core/types.js';
+import type { Rect } from "../core/types.js";
 type $$ComponentProps = {
     rect: Rect;
     imageBounds: Rect;

package/dist/components/Cropper.svelte

@@ -23,6 +23,7 @@
     sizeConstraints,
     cropOutsideImage = false,
     initialCrop,
+    initialCropScale = 1,
     grid = "rule-of-thirds",
     gridOnlyActive = true,
     transitions = true,
@@ -48,6 +49,8 @@
     sizeConstraints?: import("../core/types.js").SizeConstraints;
     cropOutsideImage?: boolean;
     initialCrop?: Partial<Rect>;
+    /** Initial crop as fraction of image (0–1). 1 = full image, 0.8 = 80% centered. Default 1. */
+    initialCropScale?: number;
     grid?: import("../core/types.js").GridType;
     gridOnlyActive?: boolean;
     transitions?: boolean;
@@ -90,6 +93,9 @@
     get initialCrop() {
       return initialCrop;
     },
+    get initialCropScale() {
+      return initialCropScale;
+    },
     get grid() {
       return grid;
     },
@@ -99,6 +105,9 @@
     get readOnly() {
       return readOnly;
     },
+    get shape() {
+      return StencilComponent === CircleStencil ? "circle" : "rect";
+    },
   });
 
   /** Only show grid lines while the user is actively interacting (dragging/resizing). */

package/dist/components/Cropper.svelte.d.ts

@@ -7,6 +7,8 @@ type $$ComponentProps = {
     sizeConstraints?: import("../core/types.js").SizeConstraints;
     cropOutsideImage?: boolean;
     initialCrop?: Partial<Rect>;
+    /** Initial crop as fraction of image (0–1). 1 = full image, 0.8 = 80% centered. Default 1. */
+    initialCropScale?: number;
     grid?: import("../core/types.js").GridType;
     gridOnlyActive?: boolean;
     transitions?: boolean;