@michaelyagi/kiri 0.1.0-alpha.7 → 0.1.0-alpha.9

package/README.md

@@ -9,11 +9,12 @@ A dependency-free TypeScript library for interactive image cropping in the brows
 - **Drag, zoom, rotate, flip** — wheel/trackpad pinch zoom, an optional
   built-in zoom slider (`showZoomer`, placeable on any of the four sides),
   90° rotation, independent horizontal/vertical flip
-- **Rectangle or circle frame** — circle is a real clip on export (transparent
-  corners on PNG/WebP), not just a visual overlay
+- **Rectangle, circle, or rounded-rectangle frame** — circle/rounded-rectangle
+  are real clips on export (transparent corners on PNG/WebP), not just a
+  visual overlay
 - **Zero-CSS sizing** — the stage auto-sizes itself to the frame's dimensions
-- **Filters** — brightness/contrast/saturation/grayscale/sepia, applied
-  identically to the live preview and the export
+- **Filters** — brightness/contrast/saturation/sharpness/grayscale/sepia,
+  applied identically to the live preview and the export
 - **Automatic EXIF orientation correction** on load
 - **Resizable frame**, four independent corner handles, with an optional
   `lockAspectRatio` to keep a fixed ratio while resizing
@@ -78,7 +79,7 @@ an interactive playground, and the full API reference.
 
 ## Status
 
-**`0.1.0-alpha.7`** — see [CHANGELOG.md](./CHANGELOG.md)
+**`0.1.0-alpha.9`** — see [CHANGELOG.md](./CHANGELOG.md)
 for what's in it. Core publishes to npm automatically on version tags via
 GitHub Actions; `kiri-react`/`kiri-vue` aren't published yet. The public API
 is expected to be mostly stable but may still change before a `0.1.0`

package/dist/export.d.ts

@@ -23,5 +23,5 @@ export declare function computeFrameSourceRect(rendered: Size, offset: Offset, f
  * carried through untouched in the result for the caller to apply.
  */
 export declare function computeCropRegion(natural: Size, frame: Size, state: KiriState): CropRegion;
-export declare function renderCropToCanvas(img: HTMLImageElement, state: KiriState, frame: Size, outputWidth: number, outputHeight: number, frameShape: FrameShape): HTMLCanvasElement;
-export declare function exportCrop(img: HTMLImageElement, state: KiriState, frame: Size, frameShape: FrameShape, options: ExportOptions): Promise<ExportResult>;
+export declare function renderCropToCanvas(img: HTMLImageElement, state: KiriState, frame: Size, outputWidth: number, outputHeight: number, frameShape: FrameShape, cornerRadius: number, sharpenFilterId: string): HTMLCanvasElement;
+export declare function exportCrop(img: HTMLImageElement, state: KiriState, frame: Size, frameShape: FrameShape, cornerRadius: number, sharpenFilterId: string, options: ExportOptions): Promise<ExportResult>;

package/dist/filters.d.ts

@@ -2,10 +2,44 @@ import { Filters } from './types';
 export declare const DEFAULT_FILTERS: Filters;
 /** Merges a partial filter update into the current filters, clamping numeric values to >= 0. */
 export declare function mergeFilters(current: Filters, partial: Partial<Filters>): Filters;
+/**
+ * The 3x3 unsharp-mask kernel for `sharpness`, as a `feConvolveMatrix`
+ * `kernelMatrix` attribute value (row-major, space-separated):
+ *
+ * ```
+ *  0  -k   0
+ * -k 1+4k -k
+ *  0  -k   0
+ * ```
+ *
+ * The matrix always sums to `1`, so the convolution needs no separate
+ * `divisor`. `sharpness <= 1` collapses to the identity kernel (center `1`,
+ * neighbors `0`) — no blur/sharpen either way, matching the `1` = unchanged
+ * convention used by the other numeric filters. `4.5` is chosen so a
+ * `sharpness` of `2`–`3` (a reasonable slider range) lands in a visually
+ * subtle-to-strong sharpening range, not an immediately harsh one.
+ */
+export declare function sharpenKernelMatrix(sharpness: number): string;
 /**
  * Builds a CSS `filter` value from the current filter state. Used verbatim as
  * both the live-preview `img.style.filter` and a canvas 2D context's
  * `ctx.filter` before drawing, so preview and export always match exactly —
- * no separately hand-rolled brightness/contrast/saturation pixel math.
+ * no separately hand-rolled brightness/contrast/saturation/sharpness pixel
+ * math. Brightness/contrast/saturation/grayscale/sepia are native CSS filter
+ * functions; CSS has no `sharpen()`, so `sharpness` instead references an
+ * SVG `feConvolveMatrix` filter (by `sharpenFilterId`) that `stage.ts` keeps
+ * in sync with the current `sharpness` value — `ctx.filter` and
+ * `img.style.filter` both support `url(#id)` references to it identically.
+ *
+ * The `url(#id)` reference goes **first**, before the native CSS filter
+ * functions — not last, despite sharpening-as-a-final-step being the more
+ * common photo-editing order. Verified directly in a real browser (Chromium)
+ * that a `url(#id)` SVG filter reference placed *after* one or more native
+ * CSS filter functions in the same chain silently produces a fully blank
+ * (transparent) result, while the identical chain with `url(#id)` first
+ * renders correctly. Sharpening a source that hasn't had brightness/contrast/
+ * saturation applied yet is a legitimate (if less common) ordering rather
+ * than a compromise — but the ordering here is load-bearing either way, not
+ * arbitrary; don't reorder this without re-verifying in a real browser.
  */
-export declare function buildFilterString(filters: Filters): string;
+export declare function buildFilterString(filters: Filters, sharpenFilterId: string): string;

package/dist/kiri.css

@@ -34,6 +34,9 @@
 .kiri-frame--circle {
   border-radius: 50%;
 }
+/* .kiri-frame--rounded-rectangle's border-radius is a per-instance pixel
+   value (frame.cornerRadius), so it's set inline by stage.ts instead of
+   here — this class exists as a CSS hook for consumers, not styling. */
 .kiri-frame-handle {
   position: absolute;
   width: 10px;

package/dist/kiri.d.ts

@@ -69,9 +69,10 @@ export declare class Kiri {
      */
     setFilters(filters: Partial<Filters>): void;
     /**
-     * Renders the current crop. A circle frame is a real clip in the output
-     * (transparent corners on PNG/WebP); a circle exported as JPEG warns and
-     * renders solid black corners instead, since JPEG has no alpha channel.
+     * Renders the current crop. A circle or rounded-rectangle frame is a real
+     * clip in the output (transparent corners on PNG/WebP); either shape
+     * exported as JPEG warns and renders solid black corners instead, since
+     * JPEG has no alpha channel.
      * @returns A data URL string (`type: "base64"`, the default), a `Blob`, or an `HTMLCanvasElement`.
      */
     export(options?: ExportOptions): Promise<ExportResult>;

package/dist/kiri.js

@@ -9,6 +9,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     brightness: 1,
     contrast: 1,
     saturation: 1,
+    sharpness: 1,
     grayscale: false,
     sepia: false
   };
@@ -17,21 +18,52 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       brightness: Math.max(0, partial.brightness ?? current.brightness),
       contrast: Math.max(0, partial.contrast ?? current.contrast),
       saturation: Math.max(0, partial.saturation ?? current.saturation),
+      sharpness: Math.max(0, partial.sharpness ?? current.sharpness),
       grayscale: partial.grayscale ?? current.grayscale,
       sepia: partial.sepia ?? current.sepia
     };
   }
-  function buildFilterString(filters) {
-    const parts = [
+  function sharpenKernelMatrix(sharpness) {
+    const weight = sharpness > 1 ? (sharpness - 1) / 4.5 : 0;
+    const center = 1 + 4 * weight;
+    const neighbor = -weight;
+    return `0 ${neighbor} 0 ${neighbor} ${center} ${neighbor} 0 ${neighbor} 0`;
+  }
+  function buildFilterString(filters, sharpenFilterId) {
+    const parts = [];
+    if (filters.sharpness > 1) parts.push(`url(#${sharpenFilterId})`);
+    parts.push(
       `brightness(${filters.brightness})`,
       `contrast(${filters.contrast})`,
       `saturate(${filters.saturation})`
-    ];
+    );
     if (filters.grayscale) parts.push("grayscale(1)");
     if (filters.sepia) parts.push("sepia(1)");
     return parts.join(" ");
   }
-  function createStage(container, frameShape, frameWidth, frameHeight, zoomer) {
+  const SVG_NS = "http://www.w3.org/2000/svg";
+  let sharpenFilterCounter = 0;
+  function createSharpenFilter() {
+    sharpenFilterCounter += 1;
+    const filterId = `kiri-sharpen-${sharpenFilterCounter}`;
+    const svg = document.createElementNS(SVG_NS, "svg");
+    svg.setAttribute("width", "0");
+    svg.setAttribute("height", "0");
+    svg.style.position = "absolute";
+    const filterEl = document.createElementNS(SVG_NS, "filter");
+    filterEl.setAttribute("id", filterId);
+    filterEl.setAttribute("color-interpolation-filters", "sRGB");
+    const kernelEl = document.createElementNS(SVG_NS, "feConvolveMatrix");
+    kernelEl.setAttribute("order", "3");
+    kernelEl.setAttribute("divisor", "1");
+    kernelEl.setAttribute("edgeMode", "duplicate");
+    kernelEl.setAttribute("preserveAlpha", "true");
+    kernelEl.setAttribute("kernelMatrix", sharpenKernelMatrix(1));
+    filterEl.appendChild(kernelEl);
+    svg.appendChild(filterEl);
+    return { svg, filterId, kernelEl };
+  }
+  function createStage(container, frameShape, frameWidth, frameHeight, cornerRadius, zoomer) {
     container.innerHTML = "";
     const stageEl = document.createElement("div");
     stageEl.className = "kiri-stage";
@@ -47,10 +79,15 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     imgEl.draggable = false;
     imageLayerEl.appendChild(imgEl);
     const frameEl = document.createElement("div");
-    frameEl.className = frameShape === "circle" ? "kiri-frame kiri-frame--circle" : "kiri-frame";
+    frameEl.className = frameShape === "circle" ? "kiri-frame kiri-frame--circle" : frameShape === "rounded-rectangle" ? "kiri-frame kiri-frame--rounded-rectangle" : "kiri-frame";
     setFrameSize(frameEl, frameWidth, frameHeight);
+    if (frameShape === "rounded-rectangle") {
+      frameEl.style.borderRadius = `${cornerRadius}px`;
+    }
+    const { svg: sharpenSvg, filterId: sharpenFilterId, kernelEl: sharpenKernelEl } = createSharpenFilter();
     stageEl.appendChild(imageLayerEl);
     stageEl.appendChild(frameEl);
+    stageEl.appendChild(sharpenSvg);
     let zoomerEl = null;
     if (zoomer.show) {
       const rootEl = document.createElement("div");
@@ -68,7 +105,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     } else {
       container.appendChild(stageEl);
     }
-    return { stageEl, frameEl, imageLayerEl, imgEl, zoomerEl };
+    return { stageEl, frameEl, imageLayerEl, imgEl, zoomerEl, sharpenFilterId, sharpenKernelEl };
   }
   function setFrameSize(frameEl, width, height) {
     frameEl.style.width = `${width}px`;
@@ -84,8 +121,9 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     const scaleY = renderedScale * (state.flip.vertical ? -1 : 1);
     imageLayerEl.style.transform = `translate(-50%, -50%) translate(${state.offset.x}px, ${state.offset.y}px) rotate(${state.rotation}deg) scale(${scaleX}, ${scaleY})`;
   }
-  function applyFilters(imgEl, filters) {
-    imgEl.style.filter = buildFilterString(filters);
+  function applyFilters(imgEl, filters, sharpenKernelEl, sharpenFilterId) {
+    sharpenKernelEl.setAttribute("kernelMatrix", sharpenKernelMatrix(filters.sharpness));
+    imgEl.style.filter = buildFilterString(filters, sharpenFilterId);
   }
   function effectiveNaturalSize(natural, rotationDeg) {
     const swapped = (rotationDeg / 90 % 2 + 2) % 2 === 1;
@@ -368,7 +406,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       flip: { ...state.flip }
     };
   }
-  function renderCropToCanvas(img, state, frame, outputWidth, outputHeight, frameShape) {
+  function renderCropToCanvas(img, state, frame, outputWidth, outputHeight, frameShape, cornerRadius, sharpenFilterId) {
     const natural = { width: img.naturalWidth, height: img.naturalHeight };
     const scale = computeCoverScale(natural, frame, state.rotation) * state.zoom;
     const rendered = effectiveRenderedSize(natural, frame, state.rotation, state.zoom);
@@ -380,7 +418,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     sctx.translate(sourceCanvas.width / 2, sourceCanvas.height / 2);
     sctx.rotate(state.rotation * Math.PI / 180);
     sctx.scale(scale * (state.flip.horizontal ? -1 : 1), scale * (state.flip.vertical ? -1 : 1));
-    sctx.filter = buildFilterString(state.filters);
+    sctx.filter = buildFilterString(state.filters, sharpenFilterId);
     sctx.drawImage(img, -natural.width / 2, -natural.height / 2, natural.width, natural.height);
     const { left: frameLeft, top: frameTop } = computeFrameSourceRect(
       rendered,
@@ -405,6 +443,13 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         Math.PI * 2
       );
       octx.clip();
+    } else if (frameShape === "rounded-rectangle") {
+      const scale2 = outputWidth / frame.width;
+      const radius = clampNum(cornerRadius * scale2, 0, Math.min(outputWidth, outputHeight) / 2);
+      octx.save();
+      octx.beginPath();
+      octx.roundRect(0, 0, outputWidth, outputHeight, radius);
+      octx.clip();
     }
     octx.drawImage(
       sourceCanvas,
@@ -417,21 +462,30 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       outputWidth,
       outputHeight
     );
-    if (frameShape === "circle") octx.restore();
+    if (frameShape === "circle" || frameShape === "rounded-rectangle") octx.restore();
     return outCanvas;
   }
-  async function exportCrop(img, state, frame, frameShape, options) {
+  async function exportCrop(img, state, frame, frameShape, cornerRadius, sharpenFilterId, options) {
     const type = resolveEnumOption(options.type, VALID_EXPORT_TYPES, "base64", "export type");
     const format = resolveEnumOption(options.format, VALID_EXPORT_FORMATS, "image/png", "export format");
     const quality = options.quality;
     const width = options.width ?? frame.width;
     const height = options.height ?? frame.height;
-    if (frameShape === "circle" && format === "image/jpeg") {
+    if ((frameShape === "circle" || frameShape === "rounded-rectangle") && format === "image/jpeg") {
       console.warn(
-        "Kiri: exporting a circle-shaped frame as image/jpeg — JPEG has no alpha channel, so the area outside the circle will render as solid black instead of transparent. Use image/png or image/webp instead."
+        `Kiri: exporting a ${frameShape}-shaped frame as image/jpeg — JPEG has no alpha channel, so the area outside the shape will render as solid black instead of transparent. Use image/png or image/webp instead.`
       );
     }
-    const canvas = renderCropToCanvas(img, state, frame, width, height, frameShape);
+    const canvas = renderCropToCanvas(
+      img,
+      state,
+      frame,
+      width,
+      height,
+      frameShape,
+      cornerRadius,
+      sharpenFilterId
+    );
     if (type === "canvas") return canvas;
     if (type === "base64") return canvas.toDataURL(format, quality);
     return new Promise((resolve, reject) => {
@@ -468,7 +522,8 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   }
   const DEFAULT_FRAME_SIZE = 200;
   const MIN_FRAME_SIZE = 20;
-  const VALID_FRAME_SHAPES = ["rectangle", "circle"];
+  const DEFAULT_CORNER_RADIUS = 20;
+  const VALID_FRAME_SHAPES = ["rectangle", "circle", "rounded-rectangle"];
   const VALID_ZOOMER_POSITIONS = ["top", "bottom", "left", "right"];
   function resolveMouseWheelZoom(value) {
     if (value === void 0) return true;
@@ -502,7 +557,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       /** Snapshot taken right after `load()` resolves, so `reset()` has something to revert to. */
       __publicField(this, "initialState", null);
       __publicField(this, "listeners", { change: [] });
-      var _a, _b, _c;
+      var _a, _b, _c, _d;
       if (!container || typeof container.appendChild !== "function") {
         throw new Error(
           "Kiri: container element is null/undefined or not a DOM element. This usually means the element wasn't in the DOM yet when `new Kiri(...)` ran — e.g. document.getElementById() was called before the element existed. Place the <script> after the element, or construct inside a DOMContentLoaded listener."
@@ -518,7 +573,8 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
             "frame.shape"
           ),
           width: ((_b = options.frame) == null ? void 0 : _b.width) ?? DEFAULT_FRAME_SIZE,
-          height: ((_c = options.frame) == null ? void 0 : _c.height) ?? DEFAULT_FRAME_SIZE
+          height: ((_c = options.frame) == null ? void 0 : _c.height) ?? DEFAULT_FRAME_SIZE,
+          cornerRadius: ((_d = options.frame) == null ? void 0 : _d.cornerRadius) ?? DEFAULT_CORNER_RADIUS
         },
         minZoom: options.minZoom ?? 1,
         maxZoom: options.maxZoom ?? 4,
@@ -544,6 +600,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         this.opts.frame.shape,
         this.opts.frame.width,
         this.opts.frame.height,
+        this.opts.frame.cornerRadius,
         {
           show: this.opts.showZoomer,
           position: this.opts.zoomerPosition,
@@ -553,7 +610,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         }
       );
       if (this.opts.autoSizeStage) this.syncStageSize();
-      applyFilters(this.stage.imgEl, this.state.filters);
+      applyFilters(this.stage.imgEl, this.state.filters, this.stage.sharpenKernelEl, this.stage.sharpenFilterId);
       if (this.stage.zoomerEl) this.enableZoomer(this.stage.zoomerEl);
       this.gestureHandle = attachGestures(
         this.stage.stageEl,
@@ -735,9 +792,10 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this.commitState({ ...this.state, filters: mergeFilters(this.state.filters, filters) });
     }
     /**
-     * Renders the current crop. A circle frame is a real clip in the output
-     * (transparent corners on PNG/WebP); a circle exported as JPEG warns and
-     * renders solid black corners instead, since JPEG has no alpha channel.
+     * Renders the current crop. A circle or rounded-rectangle frame is a real
+     * clip in the output (transparent corners on PNG/WebP); either shape
+     * exported as JPEG warns and renders solid black corners instead, since
+     * JPEG has no alpha channel.
      * @returns A data URL string (`type: "base64"`, the default), a `Blob`, or an `HTMLCanvasElement`.
      */
     async export(options = {}) {
@@ -746,6 +804,8 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         this.state,
         this.getFrameSize(),
         this.opts.frame.shape,
+        this.opts.frame.cornerRadius,
+        this.stage.sharpenFilterId,
         options
       );
     }
@@ -806,7 +866,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this.state = next;
       const scale = computeCoverScale(this.naturalSize, this.getFrameSize(), next.rotation) * next.zoom;
       applyTransform(this.stage.imageLayerEl, next, scale);
-      applyFilters(this.stage.imgEl, next.filters);
+      applyFilters(this.stage.imgEl, next.filters, this.stage.sharpenKernelEl, this.stage.sharpenFilterId);
       if (this.stage.zoomerEl) this.stage.zoomerEl.value = String(next.zoom);
       for (const cb of this.listeners.change) cb(this.getState());
     }