astro-hotspot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Hell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# astro-hotspot
+
+Astro's built-in image cropping picks from a fixed nine-anchor enum (`"center"`, `"top"`, `"right top"`, `"attention"`, …). For any image where the subject sits between those anchors — a face slightly off to one side, a product in the lower third — there's no way to say "crop around this exact point" when you resize.
+
+`astro-hotspot` adds a `hotspot` prop — same idea as CSS `object-position` / `background-position`, but applied to the underlying crop — on `<Image>`, `<Picture>`, and `getImage()`. The framing holds at every requested aspect ratio.
+
+## Install
+
+```sh
+pnpm add astro-hotspot
+```
+
+```js
+// astro.config.js
+import { defineConfig } from "astro/config";
+import hotspot from "astro-hotspot";
+
+export default defineConfig({
+  integrations: [hotspot()],
+});
+```
+
+## Use
+
+```astro
+<Image src={hero} alt="…" width={1200} height={1600} hotspot="70% 34%" />
+<Image src={hero} alt="…" width={1200} height={1600} hotspot={{ x: 0.7, y: 0.34 }} />
+```
+
+Two equivalent forms — percent string or `{x, y}` in `[0, 1]`. Values outside the range are clamped (`"-10% 50%"` snaps to the left edge).
+
+## When you don't need it
+
+If your subject is roughly centered, Sharp's built-in `position="attention"` (entropy-based auto-focus) gets it right most of the time and ships with Astro already. Reach for `astro-hotspot` when auto-focus misframes a particular image and you want explicit control.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import type { AstroIntegration } from "astro";
+import type { Hotspot } from "./types.js";
+export type { Hotspot, HotspotCoord } from "./types.js";
+/**
+ * Registers the hotspot image service. Adds a `hotspot` prop to
+ * `<Image>`, `<Picture>`, and `getImage()` that takes `{x, y}` or
+ * `"<n>% <n>%"` coordinates and crops around that point.
+ *
+ * @example
+ * ```js
+ * // astro.config.js
+ * import hotspot from "astro-hotspot";
+ * export default defineConfig({ integrations: [hotspot()] });
+ * ```
+ *
+ * @example
+ * ```astro
+ * <Image src={hero} alt="…" width={1200} height={1600} hotspot="70% 34%" />
+ * <Image src={hero} alt="…" width={1200} height={1600} hotspot={{ x: 0.7, y: 0.34 }} />
+ * ```
+ */
+declare const hotspot: () => AstroIntegration;
+export default hotspot;
+/**
+ * Surface `hotspot` as a known prop on `<Image>`, `<Picture>`, and
+ * `getImage()`. Without this, the service still works but call sites
+ * lose autocomplete + type-checking for the prop.
+ */
+declare global {
+    namespace Astro {
+        interface CustomImageProps {
+            hotspot?: Hotspot;
+        }
+    }
+}

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * Registers the hotspot image service. Adds a `hotspot` prop to
+ * `<Image>`, `<Picture>`, and `getImage()` that takes `{x, y}` or
+ * `"<n>% <n>%"` coordinates and crops around that point.
+ *
+ * @example
+ * ```js
+ * // astro.config.js
+ * import hotspot from "astro-hotspot";
+ * export default defineConfig({ integrations: [hotspot()] });
+ * ```
+ *
+ * @example
+ * ```astro
+ * <Image src={hero} alt="…" width={1200} height={1600} hotspot="70% 34%" />
+ * <Image src={hero} alt="…" width={1200} height={1600} hotspot={{ x: 0.7, y: 0.34 }} />
+ * ```
+ */
+const hotspot = () => ({
+    name: "astro-hotspot",
+    hooks: {
+        "astro:config:setup": ({ updateConfig }) => {
+            updateConfig({
+                image: {
+                    service: { entrypoint: "astro-hotspot/service" },
+                },
+            });
+        },
+    },
+});
+export default hotspot;

package/dist/service.d.ts

@@ -0,0 +1,11 @@
+import type { LocalImageService } from "astro";
+import type { HotspotCoord } from "./types.js";
+export type { Hotspot, HotspotCoord } from "./types.js";
+export declare const parseHotspot: (value: unknown) => HotspotCoord | undefined;
+/**
+ * LocalImageService that wraps the default Sharp service and adds
+ * hotspot cropping when a transform has `hotspot: {x, y}` or
+ * `hotspot: "<n>% <n>%"`. All other transforms pass through unchanged.
+ */
+declare const hotspotImageService: LocalImageService;
+export default hotspotImageService;

package/dist/service.js

@@ -0,0 +1,109 @@
+import baseSharpService from "astro/assets/services/sharp";
+const clamp01 = (n) => Math.max(0, Math.min(1, n));
+export const parseHotspot = (value) => {
+    if (value == null)
+        return undefined;
+    if (typeof value === "object" && "x" in value && "y" in value) {
+        const { x, y } = value;
+        if (typeof x === "number" &&
+            typeof y === "number" &&
+            isFinite(x) &&
+            isFinite(y)) {
+            return { x: clamp01(x), y: clamp01(y) };
+        }
+    }
+    if (typeof value === "string") {
+        const m = value.match(/^\s*(-?[\d.]+)%\s+(-?[\d.]+)%\s*$/);
+        if (m) {
+            return {
+                x: clamp01(parseFloat(m[1]) / 100),
+                y: clamp01(parseFloat(m[2]) / 100),
+            };
+        }
+    }
+    return undefined;
+};
+const getURL = (options, imageConfig) => {
+    const url = baseSharpService.getURL(options, imageConfig);
+    const hotspot = parseHotspot(options.hotspot);
+    if (!hotspot || typeof url !== "string")
+        return url;
+    const sep = url.includes("?") ? "&" : "?";
+    return `${url}${sep}hotspot=${hotspot.x},${hotspot.y}`;
+};
+const parseURL = (url, imageConfig) => {
+    const transform = baseSharpService.parseURL(url, imageConfig);
+    if (!transform || transform instanceof Promise)
+        return transform;
+    const raw = url.searchParams.get("hotspot");
+    if (raw) {
+        const [x, y] = raw.split(",").map(parseFloat);
+        if (isFinite(x) && isFinite(y)) {
+            transform.hotspot = { x, y };
+        }
+    }
+    return transform;
+};
+const transform = async (inputBuffer, transformOptions, config) => {
+    const hotspot = parseHotspot(transformOptions.hotspot);
+    if (!hotspot || !transformOptions.width || !transformOptions.height) {
+        return baseSharpService.transform(inputBuffer, transformOptions, config);
+    }
+    const { default: sharp } = await import("sharp");
+    const img = sharp(inputBuffer, { failOnError: false, pages: -1 }).rotate();
+    const meta = await img.metadata();
+    const srcW = meta.width;
+    const srcH = meta.height;
+    if (!srcW || !srcH) {
+        return baseSharpService.transform(inputBuffer, transformOptions, config);
+    }
+    const targetW = Math.round(Number(transformOptions.width));
+    const targetH = Math.round(Number(transformOptions.height));
+    const targetAR = targetW / targetH;
+    const srcAR = srcW / srcH;
+    // Largest rect of the target AR that fits in the source.
+    let cropW;
+    let cropH;
+    if (srcAR > targetAR) {
+        cropH = srcH;
+        cropW = Math.round(srcH * targetAR);
+    }
+    else {
+        cropW = srcW;
+        cropH = Math.round(srcW / targetAR);
+    }
+    // Center the rect on the hotspot, then clamp inside the source.
+    let left = Math.round(hotspot.x * srcW - cropW / 2);
+    let top = Math.round(hotspot.y * srcH - cropH / 2);
+    left = Math.max(0, Math.min(left, srcW - cropW));
+    top = Math.max(0, Math.min(top, srcH - cropH));
+    const cropped = await img
+        .extract({ left, top, width: cropW, height: cropH })
+        .toBuffer();
+    // Cropped buffer is already at target AR — delegate the final resize
+    // + format encode to the base service so we don't reimplement it.
+    return baseSharpService.transform(cropped, transformOptions, config);
+};
+/**
+ * LocalImageService that wraps the default Sharp service and adds
+ * hotspot cropping when a transform has `hotspot: {x, y}` or
+ * `hotspot: "<n>% <n>%"`. All other transforms pass through unchanged.
+ */
+const hotspotImageService = {
+    ...baseSharpService,
+    propertiesToHash: [
+        "src",
+        "width",
+        "height",
+        "format",
+        "quality",
+        "fit",
+        "position",
+        "background",
+        "hotspot",
+    ],
+    getURL,
+    parseURL,
+    transform,
+};
+export default hotspotImageService;

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Hotspot coordinates within the source image, normalized to [0, 1].
+ * `{x: 0, y: 0}` is top-left; `{x: 1, y: 1}` is bottom-right.
+ */
+export type HotspotCoord = {
+    x: number;
+    y: number;
+};
+/**
+ * Anything the hotspot image service accepts as `hotspot`.
+ *
+ * Both forms route through the service's extract+resize path. Sharp's
+ * built-in anchor strings (`"center"`, `"top"`, `"attention"`, …) are
+ * not part of this type — pass those via Astro's regular `position`
+ * prop instead; the hotspot service doesn't intercept them.
+ *
+ * Values outside `[0, 1]` are clamped (negatives snap to `0`, `> 1`
+ * snaps to `1`).
+ */
+export type Hotspot = HotspotCoord | `${number}% ${number}%`;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "astro-hotspot",
+  "version": "0.1.0",
+  "description": "Astro image service: hotspot cropping (x/y or '70% 34%') via Sharp's extract+resize",
+  "type": "module",
+  "license": "MIT",
+  "author": "David Hell <dev@davidhell.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/whytspace/astro-hotspot.git"
+  },
+  "homepage": "https://github.com/whytspace/astro-hotspot#readme",
+  "bugs": {
+    "url": "https://github.com/whytspace/astro-hotspot/issues"
+  },
+  "keywords": [
+    "astro-integration",
+    "astro-component",
+    "astro",
+    "image",
+    "sharp",
+    "hotspot",
+    "focal-point",
+    "art-direction"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./service": {
+      "types": "./dist/service.d.ts",
+      "import": "./dist/service.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "astro": ">=5.0.0 <7.0.0",
+    "sharp": ">=0.33.0 <0.36.0"
+  },
+  "devDependencies": {
+    "astro": "6.3.7",
+    "prettier": "3.8.3",
+    "sharp": "0.34.5",
+    "typescript": "6.0.3",
+    "vitest": "4.1.7"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "format": "prettier --write ."
+  }
+}