@michaelyagi/kiri 0.1.0-alpha.10

package/README.md

@@ -0,0 +1,100 @@
+> **AI-authored.** 100% of the code was written by Claude (Anthropic); I shaped the architecture, scope, and every decision, and did all the testing.
+
+# Kiri
+
+A dependency-free TypeScript library for interactive image cropping in the browser.
+
+## Features
+
+- **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, 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/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
+- **`movableFrame`** — invert the interaction model: freeze the image and
+  drag/resize the frame over it instead of panning/zooming the image
+- **`setOffset()`/`reset()`** for programmatic panning and reverting to the
+  post-`load()` state
+- **`getCropRegion()`** — the crop mapped back to the original image's own
+  pixel coordinates, for server-side cropping of the full-resolution source
+- **Keyboard-accessible** — the stage is focusable; arrow keys pan, `+`/`-`
+  zoom, `0` resets
+- **Export** to base64, Blob, or Canvas — JPEG/PNG/WebP, custom output size
+- **Upload** — a built-in FormData/fetch helper, or plug in your own
+- **Batch cropping** — a documented recipe for stepping one shared cropper
+  through a queue of images, no separate class needed
+- **React and Vue wrappers** (`kiri-react`, `kiri-vue`) — thin components, no
+  duplicated logic, reactive to prop changes after mount
+- Runtime-validated options (a typo'd setting warns and falls back rather
+  than silently misbehaving), a clear error if the container element is
+  missing, and a real, CSP-safe stylesheet instead of injected styles
+- Ships as ESM for bundlers and UMD/CJS for a plain `<script>` tag —
+  minified and unminified builds of both
+
+## Install
+
+```bash
+npm install @michaelyagi/kiri
+```
+
+[npmjs.com/package/@michaelyagi/kiri](https://www.npmjs.com/package/@michaelyagi/kiri)
+
+## Zero-config quickstart
+
+```html
+<link rel="stylesheet" href="node_modules/@michaelyagi/kiri/dist/kiri.min.css" />
+<script src="node_modules/@michaelyagi/kiri/dist/kiri.min.js"></script>
+<div id="cropper"></div>
+<script>
+  const cropper = new Kiri(document.getElementById("cropper"), {
+    frame: { shape: "circle", width: 200, height: 200 },
+  });
+  await cropper.load("photo.jpg");
+  const blob = await cropper.export({ type: "blob" });
+</script>
+```
+
+No CSS sizing needed on the container — the stage auto-sizes itself to the
+frame's dimensions. See [Getting started](https://michaelyagi.github.io/kiri/guides/getting-started.html)
+for npm/ESM installation too.
+
+## Documentation
+
+**[michaelyagi.github.io/kiri](https://michaelyagi.github.io/kiri)** —
+getting started, every method/event/setting, guides, real runnable examples,
+an interactive playground, and the full API reference.
+
+## Packages
+
+| Package | Path | What it is |
+|---|---|---|
+| `@michaelyagi/kiri` | `packages/core` | The library itself — framework-agnostic |
+| `kiri-react` | `packages/react` | `<KiriCropper>` React component (unpublished) |
+| `kiri-vue` | `packages/vue` | `<KiriCropper>` Vue component (unpublished) |
+
+## Status
+
+**`0.1.0-alpha.10`** — 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`
+(non-alpha) release.
+
+## Development
+
+```bash
+npm install                # installs all workspace packages
+npm run dev                 # core demo at http://localhost:5173
+npm run build                # builds all three packages
+npm test                      # runs all three packages' test suites
+npm run docs:build             # rebuilds the docs/ site (library + API reference + asset sync)
+```
+
+See [design.md](./design.md) for the full design document.

package/dist/exif.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Reads the EXIF orientation tag (1-8) from a JPEG ArrayBuffer, defaulting to 1
+ * (no adjustment) for images with no EXIF data or non-JPEG input.
+ */
+export declare function readExifOrientation(buffer: ArrayBuffer): number;
+export interface OrientationTransform {
+    rotation: number;
+    flipHorizontal: boolean;
+}
+/**
+ * Maps an EXIF orientation value to the rotation + horizontal-flip pair that
+ * normalizes it. A vertical flip is never needed on its own: orientation 4
+ * (mirror vertical) is expressed as rotate(180) + flip horizontal, which is
+ * mathematically equivalent.
+ *
+ * Rotation and flip don't commute, so which rotation value is paired with
+ * `flipHorizontal: true` depends on Kiri's actual render order: rotation is
+ * applied first, then flip mirrors the already-rotated result (see
+ * stage.ts's `applyTransform()`). That's why orientations 5 and 7 use `270`/
+ * `90` here rather than the more "obvious" `90`/`270` — reflections invert
+ * the effective rotation direction (`flip · rotate(θ) = rotate(-θ) · flip`),
+ * so producing the correct final image under this render order needs the
+ * negated angle. Orientations 2/3/4/6/8 are unaffected: 2 and 4 have no
+ * rotation-order ambiguity (0° and 180° are their own negation mod 360), and
+ * 3/6/8 have no flip at all. Verified directly (not just by this algebra) —
+ * confirmed in a real browser that `rotate(270) + flipHorizontal` under the
+ * current render order reproduces the exact same pixels as
+ * `rotate(90) + flipHorizontal` did under the old (flip-before-rotate) order,
+ * and vice versa.
+ */
+export declare function orientationToTransform(orientation: number): OrientationTransform;

package/dist/export.d.ts

@@ -0,0 +1,27 @@
+import { CropRegion, ExportOptions, ExportResult, FrameShape, KiriState, Offset } from './types';
+import { Size } from './gestures';
+/**
+ * Top-left corner of the frame, in the local pixel space of the rendered
+ * (rotated + scaled) image. Pure so the crop-region math is testable without
+ * a real canvas: the frame is centered on the stage, the image's own center
+ * sits at `offset` from that same point, so the frame's top-left in the
+ * rendered image's local space is the rendered center, shifted back by the
+ * offset.
+ */
+export declare function computeFrameSourceRect(rendered: Size, offset: Offset, frame: Size): {
+    left: number;
+    top: number;
+};
+/**
+ * Maps the current crop selection back into the *original, unrotated,
+ * unflipped* source image's own pixel coordinates. Corner-based: takes the
+ * frame rect's four corners in rendered (rotated + scaled) space, undoes the
+ * scale, then inverse-rotates each corner (rotation is always a multiple of
+ * 90°, so this stays an axis-aligned rectangle — no interpolation needed)
+ * back into the natural image's coordinate space, then takes the bounding
+ * box. Flip doesn't move the rectangle (mirroring is content-only), so it's
+ * 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, 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

@@ -0,0 +1,45 @@
+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/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, sharpenFilterId: string): string;

package/dist/gestures.d.ts

@@ -0,0 +1,56 @@
+import { KiriState, Offset } from './types';
+export interface Size {
+    width: number;
+    height: number;
+}
+/** Rotation-aware natural size: 90/270 degrees swap width and height. */
+export declare function effectiveNaturalSize(natural: Size, rotationDeg: number): Size;
+/** The smallest scale at which the (rotation-adjusted) image still fully covers the frame. */
+export declare function computeCoverScale(natural: Size, frame: Size, rotationDeg: number): number;
+/** Rendered size of the image layer given a user zoom multiplier (relative to cover scale). */
+export declare function effectiveRenderedSize(natural: Size, frame: Size, rotationDeg: number, zoom: number): Size;
+export declare function clampZoom(zoom: number, minZoom: number, maxZoom: number): number;
+/**
+ * Clamp the image-center offset (from stage/frame center) so the frame stays
+ * fully covered by the rendered image on every axis.
+ */
+export declare function clampOffset(offset: Offset, rendered: Size, frame: Size): Offset;
+export declare function normalizeRotation(deg: number): number;
+interface GestureCallbacks {
+    getNaturalSize: () => Size;
+    getFrameSize: () => Size;
+    getState: () => KiriState;
+    getMinMaxZoom: () => {
+        min: number;
+        max: number;
+    };
+    setState: (next: KiriState) => void;
+    /** Called on the "0" key — reverts to the post-`load()` state. */
+    reset: () => void;
+    /**
+     * `movableFrame` mode only: the image's fixed on-screen size — frozen at
+     * `load()` time (and recomputed on `rotate()`, since rotation swaps which
+     * natural dimension maps to width/height), *not* derived from the current
+     * `getFrameSize()`. Deliberately not just
+     * `effectiveRenderedSize(natural, getFrameSize(), rotation, 1)` computed
+     * on demand — the frame can be resized after load in this mode, and the
+     * image must stay the same size regardless, not jump every time the frame
+     * does.
+     */
+    getFixedImageSize: () => Size;
+}
+export interface GestureOptions {
+    mouseWheelZoom?: boolean | "ctrl";
+    /**
+     * When true, drag/wheel/pinch/arrow-keys move and (with `resizableFrame`)
+     * resize the *frame* instead of panning/zooming the image — see
+     * `KiriOptions.movableFrame`. The image is fixed at `zoom: 1`,
+     * `offset: { x: 0, y: 0 }` in this mode, so none of the zoom/offset
+     * gesture logic below runs at all.
+     */
+    movableFrame?: boolean;
+}
+export declare function attachGestures(stageEl: HTMLElement, callbacks: GestureCallbacks, options: GestureOptions): {
+    destroy: () => void;
+};
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Kiri } from './kiri';
+export type { CropRegion, ExportFormat, ExportOptions, ExportResult, ExportType, Filters, Flip, FrameShape, FrameSize, KiriEventCallback, KiriEventName, KiriOptions, KiriState, LoadOptions, Offset, UploadOptions, Uploader, ZoomerPosition, } from './types';

package/dist/kiri.css

@@ -0,0 +1,82 @@
+.kiri-stage {
+  position: relative;
+  overflow: hidden;
+  width: 100%;
+  height: 100%;
+  min-height: 200px;
+  background: #333;
+  touch-action: none;
+  cursor: grab;
+  user-select: none;
+}
+.kiri-stage.kiri-dragging {
+  cursor: grabbing;
+}
+.kiri-image-layer {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  pointer-events: none;
+}
+.kiri-image-layer img {
+  display: block;
+  max-width: none;
+}
+.kiri-frame {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  border: 1px solid rgba(255, 255, 255, 0.85);
+  box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.5);
+  pointer-events: none;
+}
+.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;
+  height: 10px;
+  background: #fff;
+  border: 1px solid #333;
+  border-radius: 50%;
+  pointer-events: auto;
+}
+.kiri-frame-handle--top-left,
+.kiri-frame-handle--bottom-right {
+  cursor: nwse-resize;
+}
+.kiri-frame-handle--top-right,
+.kiri-frame-handle--bottom-left {
+  cursor: nesw-resize;
+}
+.kiri-root {
+  display: inline-flex;
+  gap: 10px;
+  align-items: stretch;
+}
+.kiri-root--bottom,
+.kiri-root--top {
+  flex-direction: column;
+}
+.kiri-root--left,
+.kiri-root--right {
+  flex-direction: row;
+}
+.kiri-root--top .kiri-zoomer,
+.kiri-root--left .kiri-zoomer {
+  order: -1;
+}
+.kiri-zoomer {
+  cursor: pointer;
+}
+.kiri-root--left .kiri-zoomer,
+.kiri-root--right .kiri-zoomer {
+  writing-mode: vertical-lr;
+  direction: rtl;
+  width: 24px;
+}

package/dist/kiri.d.ts

@@ -0,0 +1,173 @@
+import { CropRegion, ExportOptions, ExportResult, Filters, KiriEventCallback, KiriEventName, KiriOptions, KiriState, LoadOptions, Offset, UploadOptions } from './types';
+/**
+ * An interactive image cropper attached to a plain DOM element. Drag to pan,
+ * zoom via wheel/pinch/an optional built-in slider, rotate in 90° steps,
+ * flip, apply filters, then export or upload the crop. With
+ * `movableFrame: true`, this inverts: the image is fixed and the frame
+ * itself is what you drag/resize instead — see `KiriOptions.movableFrame`.
+ */
+export declare class Kiri {
+    private readonly container;
+    private readonly opts;
+    private readonly stage;
+    private readonly gestureHandle;
+    private resizeHandle;
+    private zoomerHandle;
+    private naturalSize;
+    private state;
+    /**
+     * `movableFrame` mode only: the image's fixed on-screen size, frozen at
+     * `load()` time and recomputed on `rotate()` — see `getFixedImageSize()`.
+     */
+    private fixedImageSize;
+    /** Snapshot taken right after `load()` resolves, so `reset()` has something to revert to. */
+    private initialState;
+    private listeners;
+    /**
+     * @param container An element already present in the DOM. Passing
+     * `null`/`undefined`, or an element that isn't in the DOM yet, throws.
+     * @param options See the {@link KiriOptions} fields for defaults.
+     */
+    constructor(container: HTMLElement, options?: KiriOptions);
+    /**
+     * Loads an image, replacing whatever was loaded before. EXIF orientation
+     * (rotation + horizontal flip) is corrected automatically unless
+     * `useExifOrientation: false` was passed to the constructor — only for
+     * `File`/`Blob` sources, since a plain URL string can't be read for EXIF
+     * data without an extra fetch.
+     * @param source A `File` (e.g. from a file input), a `Blob`, or a URL string.
+     * @param loadOptions Initial `zoom`/`offset`/`rotation`/`flip`.
+     */
+    load(source: File | Blob | string, loadOptions?: LoadOptions): Promise<void>;
+    /** A snapshot of the current state — mutating the returned object has no effect. */
+    getState(): KiriState;
+    /**
+     * Sets the zoom to an absolute value, clamped to `[minZoom, maxZoom]`.
+     * No-op if `movableFrame: true` — the image never zooms in that mode.
+     */
+    setZoom(zoom: number): void;
+    /**
+     * Sets the pan offset to an absolute value (image-center offset from the
+     * frame center, in stage pixels), clamped so the frame stays fully covered
+     * by the rendered image. No-op if `movableFrame: true` — the image never
+     * pans in that mode; see `setFramePosition()` instead.
+     */
+    setOffset(offset: Offset): void;
+    /**
+     * Sets the frame's position to an absolute value (offset from stage
+     * center, in stage pixels), clamped so the frame stays fully within the
+     * image's fixed bounds. Only meaningful — and only takes effect — when
+     * `movableFrame: true`; a no-op otherwise, since the frame always stays
+     * centered in the default mode.
+     */
+    setFramePosition(position: Offset): void;
+    /**
+     * Reverts zoom/offset/rotation/flip/filters/framePosition to what they
+     * were right after `load()` resolved (including any `loadOptions` passed
+     * to it). No-op if nothing has been loaded yet.
+     */
+    reset(): void;
+    /**
+     * Rotates relative to the current rotation, snapped to the nearest 90°.
+     * No-op if `rotatable: false` was passed to the constructor.
+     */
+    rotate(deltaDeg: number): void;
+    /**
+     * Toggles horizontal flip. Always mirrors left-right as currently
+     * displayed on screen, regardless of the current `rotation` — not the
+     * image's own pre-rotation axes, so the visible effect stays "horizontal"
+     * no matter how the image is rotated. No-op if `flippable: false`.
+     */
+    flipHorizontal(): void;
+    /**
+     * Toggles vertical flip. Always mirrors top-to-bottom as currently
+     * displayed on screen, regardless of the current `rotation`. No-op if
+     * `flippable: false`.
+     */
+    flipVertical(): void;
+    /**
+     * Resizes the frame. Also resizes the stage to match, if
+     * `autoSizeStage: true` (the default) — except in `movableFrame` mode,
+     * where the stage stays pinned to the fixed image's own size (see
+     * `fixedImageSize`'s doc comment) instead of following the frame; letting
+     * the stage shrink along with the frame there would clip the (unchanged,
+     * still full-size) image down to whatever's left, visually reading as the
+     * picture itself shrinking even though its actual rendered size never
+     * changes. Each axis is clamped to a 20px minimum.
+     */
+    setFrameSize(width: number, height: number): void;
+    /**
+     * Merges a partial update into the current filters (omitted fields are
+     * left as they are). Numeric values are clamped to `>= 0`.
+     */
+    setFilters(filters: Partial<Filters>): void;
+    /**
+     * 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>;
+    /**
+     * The current crop selection as a rectangle in the original, unrotated,
+     * unflipped source image's own pixel coordinates — for sending to a server
+     * that will crop the full-resolution original itself instead of uploading
+     * a client-re-encoded image. See {@link CropRegion}.
+     */
+    getCropRegion(): CropRegion;
+    /**
+     * Exports the current crop as a blob, then uploads it — a default
+     * FormData/`fetch` POST, or a custom `uploader` (per-call `options.uploader`
+     * wins over the constructor's, which wins over the built-in default).
+     */
+    upload(url: string, options?: UploadOptions): Promise<unknown>;
+    /** Subscribes to `"change"` — fires on every state update (drag/zoom/rotate/flip/filters), and once after `load()` resolves. */
+    on(event: KiriEventName, callback: KiriEventCallback): void;
+    /** Unsubscribes a callback previously passed to {@link on}. */
+    off(event: KiriEventName, callback: KiriEventCallback): void;
+    /**
+     * Tears the instance down: removes all pointer/wheel event listeners
+     * (drag/zoom gestures), the resize-handle listener (if `resizableFrame`),
+     * and the zoom-slider listener (if `showZoomer`); clears the container's
+     * `innerHTML`, leaving an empty container element; and clears all
+     * `"change"` listeners. Call this when you're done with an instance (e.g.
+     * unmounting) to avoid leaking listeners.
+     */
+    destroy(): void;
+    private getFrameSize;
+    /**
+     * `computeCropRegion()`/`renderCropToCanvas()` only know one model: an
+     * image shifted by `offset` under a frame fixed at center, scaled by
+     * `computeCoverScale(natural, frame, rotation) * zoom` — where `frame` is
+     * whatever's passed in, i.e. the *current* frame size. In `movableFrame`
+     * mode neither of those assumptions holds as-is: it's the frame that
+     * shifts (by `framePosition`, image fixed at center), and the image's
+     * scale must stay pinned to `fixedImageSize` regardless of how the frame
+     * has since been resized — not recomputed from the current frame size,
+     * which is exactly what those functions would otherwise do internally.
+     *
+     * Both are fixed by substituting two `state` fields before calling them,
+     * rather than changing either function:
+     * - `offset = -framePosition` — "frame moved right by d" and "image moved
+     *   left by d" describe the identical relative geometry, so this alone
+     *   carries the frame's position into the existing math unmodified.
+     *   (`state.offset` is always `{0,0}` in this mode already, since
+     *   `setOffset()`/gesture panning are no-ops here — this substitution is
+     *   what actually does the work, not a redundant no-op.)
+     * - `zoom` = a value chosen so that
+     *   `computeCoverScale(natural, currentFrame, rotation) * zoom` evaluates
+     *   to exactly `fixedImageSize`'s own scale, whatever the current frame
+     *   size is — i.e. `zoom = frozenScale / computeCoverScale(natural,
+     *   currentFrame, rotation)`, which cancels the current-frame-size term
+     *   out algebraically. Caught by an actual pixel test (a moved+resized
+     *   frame exported as fully transparent) before trusting the offset
+     *   substitution was sufficient on its own — it wasn't.
+     */
+    private getEffectiveStateForCrop;
+    private syncStageSize;
+    private syncStageSizeToFixedImage;
+    private commitState;
+    private enableZoomer;
+    private enableFrameResize;
+}