@lexingtonthemes/astro-image-inspector 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @lexingtonthemes/astro-image-inspector
+
+Astro Dev Toolbar app that lets you **inspect images on hover** during local development: see actual size, render size, loading mode, and common warnings (upscaled, oversized source, missing dimensions).
+
+Only runs when `astro dev` is running; it does not appear in production builds.
+
+## Install
+
+```bash
+npm install @lexingtonthemes/astro-image-inspector --save-dev
+```
+
+## Setup
+
+In `astro.config.mjs`:
+
+```js
+import { defineConfig } from 'astro/config';
+import imageInspector from '@lexingtonthemes/astro-image-inspector';
+
+export default defineConfig({
+  integrations: [
+    imageInspector(),
+  ],
+});
+```
+
+## Usage
+
+1. Run `astro dev`.
+2. Hover near the bottom of the page to show the Dev Toolbar.
+3. Click the **Image Inspector** icon to turn inspection on.
+4. Hover over any `<img>` on the page to see:
+   - **src** – current image URL
+   - **natural** – intrinsic width×height
+   - **rendered** – displayed width×height
+   - **loading** – `lazy` / `eager` / `auto`
+   - **warnings** – e.g. Upscaled, Possibly oversized source, No width/height
+
+The inspector draws a highlight around the hovered image and shows a small info panel (bottom-left by default).
+
+## Config
+
+| Option            | Default            | Description                                              |
+| ----------------- | ------------------ | -------------------------------------------------------- |
+| `enabled`         | `true`             | Enable the Image Inspector app.                         |
+| `appName`         | `"Image Inspector"`| Label in the dev toolbar.                               |
+| `showWarningsOnly`| `false`            | *(Reserved)* Only show panel when there are warnings.    |
+| `warnOnUpscale`   | `true`             | *(Reserved)* Warn when image is rendered larger than source. |
+| `warnOnOversized` | `true`             | *(Reserved)* Warn when source is much larger than render size. |
+
+Example:
+
+```js
+imageInspector({
+  enabled: true,
+  appName: 'Images',
+}),
+```
+
+## Warnings
+
+- **Upscaled** – Rendered size is larger than the image’s natural size.
+- **Possibly oversized source** – Natural dimensions are more than 2× the rendered size (good candidate for resizing).
+- **No width/height** – Missing `width`/`height` attributes (can affect layout and LCP).
+
+## Publishing (maintainers)
+
+This package is published under the [@lexingtonthemes](https://www.npmjs.com/settings/lexingtonthemes/packages) npm organization.
+
+```bash
+npm run build
+npm publish
+```
+
+Ensure you are logged in (`npm login`) and have access to the `lexingtonthemes` org.
+
+## License
+
+MIT © [Lexington Themes](https://www.npmjs.com/settings/lexingtonthemes/packages)

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { AstroIntegration } from "astro";
+import type { ImageInspectorOptions } from "./types.js";
+export type { ImageInspectorOptions };
+export default function imageInspector(options?: ImageInspectorOptions): AstroIntegration;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,YAAY,EAAE,qBAAqB,EAAE,CAAC;AAEtC,MAAM,CAAC,OAAO,UAAU,cAAc,CACpC,OAAO,GAAE,qBAA0B,GAClC,gBAAgB,CAmBlB"}

package/dist/index.js

@@ -0,0 +1,19 @@
+export default function imageInspector(options = {}) {
+    const enabled = options.enabled ?? true;
+    const appName = options.appName ?? "Image Inspector";
+    return {
+        name: "@lexingtonthemes/astro-image-inspector",
+        hooks: {
+            "astro:config:setup"({ addDevToolbarApp, command }) {
+                if (!enabled || command !== "dev")
+                    return;
+                addDevToolbarApp({
+                    id: "astro-image-inspector",
+                    name: appName,
+                    icon: "image",
+                    entrypoint: new URL("./toolbar-app.js", import.meta.url),
+                });
+            },
+        },
+    };
+}

package/dist/toolbar-app.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("astro").DevToolbarApp;
+export default _default;
+//# sourceMappingURL=toolbar-app.d.ts.map

package/dist/toolbar-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolbar-app.d.ts","sourceRoot":"","sources":["../src/toolbar-app.ts"],"names":[],"mappings":";AAiKA,wBAuBG"}

package/dist/toolbar-app.js

@@ -0,0 +1,157 @@
+import { defineToolbarApp } from "astro/toolbar";
+const OVERLAY_ID = "astro-image-inspector-overlay";
+const PANEL_ID = "astro-image-inspector-panel";
+function getImageInfo(img) {
+    const rect = img.getBoundingClientRect();
+    const nw = img.naturalWidth || 0;
+    const nh = img.naturalHeight || 0;
+    const rw = Math.round(rect.width);
+    const rh = Math.round(rect.height);
+    const warnings = [];
+    if (nw > 0 && nh > 0) {
+        if (rw > nw || rh > nh)
+            warnings.push("Upscaled");
+        if (nw > rw * 2 || nh > rh * 2)
+            warnings.push("Possibly oversized source");
+    }
+    if (!img.hasAttribute("width") && !img.hasAttribute("height")) {
+        warnings.push("No width/height");
+    }
+    return {
+        src: img.currentSrc || img.src || "",
+        naturalWidth: nw,
+        naturalHeight: nh,
+        renderedWidth: rw,
+        renderedHeight: rh,
+        loading: img.loading || "auto",
+        decoding: img.decoding || "auto",
+        warnings,
+    };
+}
+function ensureOverlay() {
+    let el = document.getElementById(OVERLAY_ID);
+    if (!el) {
+        el = document.createElement("div");
+        el.id = OVERLAY_ID;
+        el.style.cssText = `
+      position: fixed;
+      pointer-events: none;
+      border: 2px solid rgba(139, 92, 246, 0.8);
+      box-sizing: border-box;
+      z-index: 2147483646;
+      transition: top 0.05s, left 0.05s, width 0.05s, height 0.05s;
+    `;
+        document.body.appendChild(el);
+    }
+    return el;
+}
+function ensurePanel() {
+    let el = document.getElementById(PANEL_ID);
+    if (!el) {
+        el = document.createElement("div");
+        el.id = PANEL_ID;
+        el.style.cssText = `
+      position: fixed;
+      bottom: 60px;
+      left: 12px;
+      max-width: 360px;
+      padding: 12px;
+      background: rgba(30, 30, 40, 0.97);
+      color: #e2e8f0;
+      font-family: ui-monospace, monospace;
+      font-size: 12px;
+      border-radius: 8px;
+      box-shadow: 0 4px 20px rgba(0,0,0,0.3);
+      z-index: 2147483646;
+      pointer-events: auto;
+      line-height: 1.5;
+    `;
+        document.body.appendChild(el);
+    }
+    return el;
+}
+function hideOverlay() {
+    const el = document.getElementById(OVERLAY_ID);
+    if (el)
+        el.style.display = "none";
+}
+function hidePanel() {
+    const el = document.getElementById(PANEL_ID);
+    if (el)
+        el.style.display = "none";
+}
+function showOverlay(rect) {
+    const el = ensureOverlay();
+    el.style.display = "block";
+    el.style.top = `${rect.top + window.scrollY}px`;
+    el.style.left = `${rect.left + window.scrollX}px`;
+    el.style.width = `${rect.width}px`;
+    el.style.height = `${rect.height}px`;
+    el.style.borderColor = "rgba(139, 92, 246, 0.8)";
+}
+function showPanel(info) {
+    const el = ensurePanel();
+    el.style.display = "block";
+    const srcShort = info.src.length > 50 ? info.src.slice(0, 47) + "…" : info.src;
+    const warnText = info.warnings.length > 0
+        ? `<span style="color: #fbbf24;">${info.warnings.join(", ")}</span>`
+        : "none";
+    el.innerHTML = `
+    <div><strong>src</strong> ${srcShort}</div>
+    <div><strong>natural</strong> ${info.naturalWidth}×${info.naturalHeight}</div>
+    <div><strong>rendered</strong> ${info.renderedWidth}×${info.renderedHeight}</div>
+    <div><strong>loading</strong> ${info.loading}</div>
+    <div><strong>warnings</strong> ${warnText}</div>
+  `;
+}
+function enableInspector(windowContent) {
+    windowContent.textContent = "Hover an image to inspect it.";
+    const onMouseOver = (event) => {
+        const target = event.target;
+        if (!(target instanceof HTMLImageElement)) {
+            hideOverlay();
+            hidePanel();
+            return;
+        }
+        const info = getImageInfo(target);
+        showOverlay(target.getBoundingClientRect());
+        showPanel(info);
+    };
+    const onMouseOut = (event) => {
+        const related = event.relatedTarget;
+        if (related && document.body.contains(related))
+            return;
+        hideOverlay();
+        hidePanel();
+    };
+    document.addEventListener("mouseover", onMouseOver, true);
+    document.addEventListener("mouseout", onMouseOut, true);
+    return () => {
+        document.removeEventListener("mouseover", onMouseOver, true);
+        document.removeEventListener("mouseout", onMouseOut, true);
+        hideOverlay();
+        hidePanel();
+    };
+}
+export default defineToolbarApp({
+    init(canvas, app) {
+        const windowEl = document.createElement("astro-dev-toolbar-window");
+        const content = document.createElement("div");
+        content.style.cssText = "padding: 12px; font-size: 14px;";
+        content.textContent = "Toggle on and hover an image to inspect it.";
+        windowEl.appendChild(content);
+        canvas.appendChild(windowEl);
+        let cleanup = null;
+        app.onToggled(({ state }) => {
+            if (cleanup) {
+                cleanup();
+                cleanup = null;
+            }
+            if (!state) {
+                content.textContent = "Toggle on and hover an image to inspect it.";
+                return;
+            }
+            cleanup = enableInspector(content);
+        });
+    },
+});

package/dist/types.d.ts

@@ -0,0 +1,23 @@
+export interface ImageInspectorOptions {
+    /** Enable the Image Inspector toolbar app. Default: true */
+    enabled?: boolean;
+    /** Label shown in the dev toolbar. Default: "Image Inspector" */
+    appName?: string;
+    /** Only show the panel when there are warnings. Default: false */
+    showWarningsOnly?: boolean;
+    /** Warn when the image is rendered larger than its natural size. Default: true */
+    warnOnUpscale?: boolean;
+    /** Warn when natural size is more than 2x rendered size. Default: true */
+    warnOnOversized?: boolean;
+}
+export interface ImageInfo {
+    src: string;
+    naturalWidth: number;
+    naturalHeight: number;
+    renderedWidth: number;
+    renderedHeight: number;
+    loading: string;
+    decoding: string;
+    warnings: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,0EAA0E;IAC1E,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB"}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@lexingtonthemes/astro-image-inspector",
+  "version": "0.1.0",
+  "description": "Astro Dev Toolbar app to inspect images on hover: actual size, render size, and warnings",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "astro": ">=4.7.0"
+  },
+  "devDependencies": {
+    "astro": "^5.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "dev-toolbar",
+    "images",
+    "inspector",
+    "lexingtonthemes"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lexingtonthemes/astro-image-inspector"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}