@narumitw/pi-image-drop 0.18.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+
+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,149 @@
+# 🖼️ pi-image-drop — Browser Image Staging for Pi
+
+[![npm](https://img.shields.io/npm/v/@narumitw/pi-image-drop)](https://www.npmjs.com/package/@narumitw/pi-image-drop) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+`@narumitw/pi-image-drop` adds one `/image-drop` command to the latest [Pi Coding Agent](https://pi.dev). It serves a private loopback page where you can paste, drop, choose, preview, reorder, retry, and remove local images. The ordered batch is attached to your next non-empty interactive Pi message.
+
+The page never contains a prompt or Attach button: Pi remains the only place where messages are written and sent.
+
+## Install
+
+```bash
+pi install npm:@narumitw/pi-image-drop
+```
+
+Try the working tree without installing:
+
+```bash
+pi -e ./extensions/pi-image-drop
+# or
+just try image-drop
+```
+
+This package targets the latest Pi release and uses its `agent_settled` lifecycle event. Older Pi releases are not supported.
+
+## Workflow
+
+1. Run `/image-drop` in an interactive Pi session.
+2. Pi prints and displays a clickable one-time `http://127.0.0.1:<port>/...` link. The extension does **not** open a browser.
+3. Open the link. Paste images anywhere, drop files, or select **Choose images**.
+4. Review previews and processing details. Drag to reorder, use the keyboard-accessible arrow buttons, retry failures, delete individual items, or use confirmed **Clear all**.
+5. Write and submit a non-empty message in Pi. The ready images are appended after any attachments already on that message, in browser order.
+
+The `🖼️` widget above Pi's editor reports ready, uploading, error, and queued counts. Uploading or failed items block the whole batch and preserve the Pi editor text. Image-only messages are not supported.
+
+Each `/image-drop` invocation rotates the unused one-time link. A browser refresh keeps the current in-memory batch. Opening the authenticated page in another tab gives the new tab the editing lease and makes the old tab stale.
+
+## Supported images
+
+| Input | Provider-ready output |
+| --- | --- |
+| PNG | PNG |
+| JPEG | JPEG |
+| WebP | WebP |
+| GIF, including animation | GIF |
+| BMP | PNG |
+| TIFF | PNG |
+| HEIC/HEIF | PNG |
+| AVIF | PNG |
+
+Detection uses file signatures, not filenames or browser MIME types. SVG, HTML, remote URLs, unknown formats, corrupt files, and images over the configured pixel limit are rejected.
+
+The processor applies orientation and removes EXIF (including GPS), XMP, IPTC, comments, and other sensitive metadata. It retains an ICC color profile and animated GIF timing where the output format supports them. With Pi's `images.autoResize` enabled (the default), output is reduced to fit Pi's 2,000-pixel and approximately 4.5 MiB Base64 inline limits. With it disabled, output that exceeds either limit fails visibly instead of being resized.
+
+## Configuration
+
+Image Drop has one optional **global-only** JSON file:
+
+```text
+${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-image-drop.json
+```
+
+Example:
+
+```json
+{
+  "maxImages": 8,
+  "maxImageBytes": 10485760,
+  "maxBatchBytes": 41943040,
+  "maxImagePixels": 50000000
+}
+```
+
+| Setting | Safe default | Hard ceiling |
+| --- | ---: | ---: |
+| `maxImages` | 8 | 32 |
+| `maxImageBytes` | 10 MiB | 50 MiB |
+| `maxBatchBytes` | 40 MiB | 200 MiB |
+| `maxImagePixels` | 50 megapixels | 100 megapixels |
+
+Values are positive integer counts/bytes/pixels. `maxImageBytes` cannot exceed `maxBatchBytes`. Unknown fields, malformed JSON, invalid values, symlinks, or values above a hard ceiling cause the **whole file** to be ignored with one warning and safe defaults to be used. Values above a safe default but within a hard ceiling produce a memory/provider-limit warning.
+
+At upload and submission time, the extension also re-reads Pi's documented global and trusted-project `images.autoResize` and `images.blockImages` settings. `blockImages: true` or a text-only current model blocks processing/submission without discarding the draft.
+
+## Security and privacy
+
+- The HTTP listener binds only to a random `127.0.0.1` port.
+- A rotating bootstrap token is exchanged once for an HttpOnly, `SameSite=Strict` session cookie, then removed from the URL.
+- Exact Host, mutation Origin, session-cookie, and active-client checks are enforced. No permissive CORS headers are sent.
+- Pages use a restrictive Content Security Policy plus no-store, no-referrer, MIME-sniffing, and frame-denial headers.
+- Raw request bodies, decoded pixels, source bytes, previews, and provider-ready bytes are bounded and stay in the Pi process memory. The extension creates no image cache or temporary image files.
+- Bytes are released after Pi records the matching user message, after Delete/Clear all, and on reload, session replacement/fork, or shutdown. Once Pi records a message, normal Pi/provider retention rules apply.
+
+A loopback page is local to your operating-system network namespace. Do not expose the port to a LAN or public interface.
+
+## Platforms, browsers, and remote environments
+
+The supported local targets are current macOS, Windows, desktop Linux, and WSL with current stable Chrome, Edge, Firefox, or Safari where those browsers are available. Native `sharp` packages are installed for the current platform; HEVC-backed HEIC and BMP use bounded portable decoders because the patent-safe prebuilt `sharp`/libvips bundle omits them.
+
+WSL normally forwards loopback to Windows automatically; always use the printed `127.0.0.1` URL rather than changing it to `localhost`. For SSH, a container, or a devcontainer, forward the exact printed port and preserve the Host value. If Pi prints port `45678`, for example:
+
+```bash
+ssh -L 45678:127.0.0.1:45678 user@remote-host
+```
+
+Then open the unchanged `http://127.0.0.1:45678/...` link locally. Image Drop does not provide a cloud relay or remote upload endpoint.
+
+## Limitations
+
+- Only `/image-drop` is registered; there is no `/image-drop clear` command.
+- A non-empty interactive Pi message is required. RPC, extension-generated, slash-command, and image-only inputs do not consume the batch.
+- All items must be ready. One uploading or failed item blocks submission until it is retried or deleted.
+- Provider aggregate request limits vary. Raising the defaults to the hard ceilings does not guarantee that a provider accepts the final multi-image request.
+- Batches are intentionally not persisted or shown as recent history.
+
+## Package layout
+
+```text
+src/image-drop.ts       Pi extension entrypoint
+src/runtime.ts          Pi lifecycle and message orchestration
+src/batch.ts            in-memory batch state machine
+src/images.ts           bounded image processing
+src/server.ts           authenticated loopback HTTP/SSE server
+src/settings.ts         extension settings
+src/pi-settings.ts      effective Pi image settings adapter
+src/web/                framework-free browser page
+```
+
+## Development
+
+From the repository root:
+
+```bash
+npm --workspace @narumitw/pi-image-drop run check
+npm test
+just try image-drop
+just pack image-drop
+```
+
+The dry-run package must contain the manifest, license, README, TypeScript sources, and static web assets, but no tests, fixtures, image bytes, or `node_modules`.
+
+## Publishing
+
+The first publication is intentionally a maintainer action:
+
+```bash
+npm publish --workspace @narumitw/pi-image-drop --access public
+```
+
+`just npm-public` only changes visibility after a scoped package already exists. Do not publish from an implementation or verification run.

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@narumitw/pi-image-drop",
+	"version": "0.18.0",
+	"description": "Pi extension for staging browser images and attaching them to the next message.",
+	"type": "module",
+	"license": "MIT",
+	"private": false,
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"images",
+		"attachments",
+		"browser"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/image-drop.ts"
+		]
+	},
+	"scripts": {
+		"check": "biome check . && npm run typecheck",
+		"format": "biome check --write .",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"bmp-js": "^0.1.0",
+		"heic-decode": "^2.1.0",
+		"sharp": "^0.35.3"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.3",
+		"@earendil-works/pi-ai": "0.80.3",
+		"@earendil-works/pi-coding-agent": "0.80.3",
+		"typescript": "6.0.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/narumiruna/pi-extensions",
+		"directory": "extensions/pi-image-drop"
+	}
+}

package/src/batch.ts

@@ -0,0 +1,418 @@
+import { createHash } from "node:crypto";
+import type { ImageContent } from "@earendil-works/pi-ai";
+import type { ImageDropSettings } from "./settings.js";
+
+export type ItemStatus = "uploading" | "processing" | "ready" | "error";
+export type BatchPhase = "empty" | "editing" | "ready" | "blocked" | "reserved" | "closed";
+
+export interface ItemReservation {
+	id: string;
+	name: string;
+	size: number;
+}
+
+export interface ProcessedImage {
+	bytes: Buffer;
+	mimeType: string;
+	width: number;
+	height: number;
+	originalWidth: number;
+	originalHeight: number;
+	sourceFormat: string;
+	outputFormat: string;
+	resized: boolean;
+	hash: string;
+	notes: string[];
+}
+
+interface BatchItem extends ItemReservation {
+	status: ItemStatus;
+	source?: Buffer;
+	processed?: ProcessedImage;
+	processedAutoResize?: boolean;
+	error?: string;
+}
+
+export interface PublicBatchItem extends ItemReservation {
+	status: ItemStatus;
+	error?: string;
+	mimeType?: string;
+	width?: number;
+	height?: number;
+	originalWidth?: number;
+	originalHeight?: number;
+	sourceFormat?: string;
+	outputFormat?: string;
+	resized?: boolean;
+	notes: string[];
+}
+
+export interface PublicBatchState {
+	revision: number;
+	phase: BatchPhase;
+	items: PublicBatchItem[];
+	totalSourceBytes: number;
+}
+
+export interface MessageReservation {
+	id: string;
+	text: string;
+	streamingBehavior?: "steer" | "followUp";
+	images: ImageContent[];
+	digest: string;
+	preflightStarted: boolean;
+}
+
+export type CompleteResult = { kind: "ready" } | { kind: "duplicate"; existingId: string };
+
+export class BatchError extends Error {
+	constructor(
+		message: string,
+		readonly code: "closed" | "frozen" | "stale" | "limit" | "invalid" | "not-found" | "not-ready",
+	) {
+		super(message);
+	}
+}
+
+export class BatchStore {
+	private items: BatchItem[] = [];
+	private revision = 0;
+	private reservation?: MessageReservation;
+	private closed = false;
+
+	constructor(private readonly settings: ImageDropSettings) {}
+
+	publicState(): PublicBatchState {
+		return {
+			revision: this.revision,
+			phase: this.phase(),
+			items: this.items.map((item) => ({
+				id: item.id,
+				name: item.name,
+				size: item.size,
+				status: item.status,
+				error: item.error,
+				mimeType: item.processed?.mimeType,
+				width: item.processed?.width,
+				height: item.processed?.height,
+				originalWidth: item.processed?.originalWidth,
+				originalHeight: item.processed?.originalHeight,
+				sourceFormat: item.processed?.sourceFormat,
+				outputFormat: item.processed?.outputFormat,
+				resized: item.processed?.resized,
+				notes: [...(item.processed?.notes ?? [])],
+			})),
+			totalSourceBytes: this.items.reduce((sum, item) => sum + item.size, 0),
+		};
+	}
+
+	reserveItems(inputs: readonly ItemReservation[], expectedRevision = this.revision): number {
+		this.assertMutable(expectedRevision);
+		if (inputs.length === 0) throw new BatchError("No images supplied", "invalid");
+		const ids = new Set(this.items.map((item) => item.id));
+		let addedBytes = 0;
+		for (const input of inputs) {
+			if (!isSafeIdentifier(input.id) || ids.has(input.id)) {
+				throw new BatchError("Image id is invalid or duplicated", "invalid");
+			}
+			if (!input.name || input.name.length > 255 || hasControlCharacter(input.name)) {
+				throw new BatchError("Image name is invalid", "invalid");
+			}
+			if (!Number.isSafeInteger(input.size) || input.size <= 0) {
+				throw new BatchError("Image size is invalid", "invalid");
+			}
+			if (input.size > this.settings.maxImageBytes) {
+				throw new BatchError("Image exceeds the per-image limit", "limit");
+			}
+			ids.add(input.id);
+			addedBytes += input.size;
+		}
+		if (this.items.length + inputs.length > this.settings.maxImages) {
+			throw new BatchError("Batch exceeds the image-count limit", "limit");
+		}
+		const currentBytes = this.items.reduce((sum, item) => sum + item.size, 0);
+		if (currentBytes + addedBytes > this.settings.maxBatchBytes) {
+			throw new BatchError("Batch exceeds the byte limit", "limit");
+		}
+		this.items.push(...inputs.map((input) => ({ ...input, status: "uploading" as const })));
+		return this.bump();
+	}
+
+	startProcessing(id: string, source: Buffer): number {
+		this.assertOpen();
+		if (this.reservation) throw new BatchError("Batch is frozen", "frozen");
+		const item = this.item(id);
+		if (source.byteLength !== item.size) {
+			throw new BatchError("Uploaded size does not match the reservation", "invalid");
+		}
+		item.source = Buffer.from(source);
+		item.processed = undefined;
+		item.processedAutoResize = undefined;
+		item.error = undefined;
+		item.status = "processing";
+		return this.bump();
+	}
+
+	complete(id: string, processed: ProcessedImage, autoResize?: boolean): CompleteResult {
+		this.assertOpen();
+		if (this.reservation) throw new BatchError("Batch is frozen", "frozen");
+		const item = this.item(id);
+		if (item.status !== "processing") throw new BatchError("Image is not processing", "invalid");
+		const itemIndex = this.items.indexOf(item);
+		const duplicates = this.items
+			.map((candidate, index) => ({ candidate, index }))
+			.filter(
+				({ candidate }) => candidate.id !== id && candidate.processed?.hash === processed.hash,
+			);
+		const earlier = duplicates.find(({ index }) => index < itemIndex);
+		if (earlier) {
+			this.items = this.items.filter((candidate) => candidate.id !== id);
+			this.bump();
+			return { kind: "duplicate", existingId: earlier.candidate.id };
+		}
+		item.processed = cloneProcessed(processed);
+		item.processedAutoResize = autoResize;
+		item.status = "ready";
+		item.error = undefined;
+		if (duplicates.length > 0) {
+			const laterIds = new Set(duplicates.map(({ candidate }) => candidate.id));
+			this.items = this.items.filter((candidate) => !laterIds.has(candidate.id));
+			this.bump();
+			return { kind: "duplicate", existingId: item.id };
+		}
+		this.bump();
+		return { kind: "ready" };
+	}
+
+	fail(id: string, error: string): number {
+		this.assertOpen();
+		if (this.reservation) throw new BatchError("Batch is frozen", "frozen");
+		const item = this.item(id);
+		item.status = "error";
+		item.error = sanitizeError(error);
+		item.processed = undefined;
+		item.processedAutoResize = undefined;
+		return this.bump();
+	}
+
+	failUpload(id: string, error: string): number {
+		this.assertOpen();
+		if (this.reservation) throw new BatchError("Batch is frozen", "frozen");
+		const item = this.item(id);
+		if (item.status !== "uploading") {
+			throw new BatchError("Upload is no longer pending", "invalid");
+		}
+		item.status = "error";
+		item.error = sanitizeError(error);
+		return this.bump();
+	}
+
+	beginAutoResizeReprocessing(autoResize: boolean): Array<{ id: string; source: Buffer }> {
+		this.assertOpen();
+		if (this.reservation) throw new BatchError("Batch is frozen", "frozen");
+		if (this.items.some((item) => item.status !== "ready")) {
+			throw new BatchError("Every image must be ready before reprocessing", "not-ready");
+		}
+		const candidates = this.items.filter(
+			(item) => item.processedAutoResize !== undefined && item.processedAutoResize !== autoResize,
+		);
+		if (candidates.length === 0) return [];
+		const jobs = candidates.map((item) => {
+			if (!item.source) throw new BatchError("Image source bytes are unavailable", "not-ready");
+			return { id: item.id, source: Buffer.from(item.source) };
+		});
+		for (const item of candidates) {
+			item.status = "processing";
+			item.processed = undefined;
+			item.processedAutoResize = undefined;
+			item.error = undefined;
+		}
+		this.bump();
+		return jobs;
+	}
+
+	retrySource(id: string): Buffer {
+		this.assertOpen();
+		if (this.reservation) throw new BatchError("Batch is frozen", "frozen");
+		const item = this.item(id);
+		if (item.status !== "error" || !item.source) {
+			throw new BatchError("Image cannot be retried without uploaded source bytes", "not-ready");
+		}
+		item.status = "processing";
+		item.error = undefined;
+		item.processedAutoResize = undefined;
+		this.bump();
+		return Buffer.from(item.source);
+	}
+
+	delete(id: string, expectedRevision = this.revision): number {
+		this.assertMutable(expectedRevision);
+		const before = this.items.length;
+		this.items = this.items.filter((item) => item.id !== id);
+		if (this.items.length === before) throw new BatchError("Image not found", "not-found");
+		return this.bump();
+	}
+
+	reorder(ids: readonly string[], expectedRevision = this.revision): number {
+		this.assertMutable(expectedRevision);
+		if (
+			ids.length !== this.items.length ||
+			new Set(ids).size !== ids.length ||
+			ids.some((id) => !this.items.some((item) => item.id === id))
+		) {
+			throw new BatchError("Order must contain every image exactly once", "invalid");
+		}
+		const byId = new Map(this.items.map((item) => [item.id, item]));
+		this.items = ids.map((id) => byId.get(id) as BatchItem);
+		return this.bump();
+	}
+
+	clear(expectedRevision = this.revision): number {
+		this.assertMutable(expectedRevision);
+		this.items = [];
+		return this.bump();
+	}
+
+	reserveMessage(text: string, streamingBehavior?: "steer" | "followUp"): MessageReservation {
+		this.assertOpen();
+		if (this.reservation) throw new BatchError("Batch is already frozen", "frozen");
+		if (!text.trim()) throw new BatchError("Message text is required", "invalid");
+		if (this.items.length === 0 || this.items.some((item) => item.status !== "ready")) {
+			throw new BatchError("Every image must be ready", "not-ready");
+		}
+		const images = this.items.map((item) => ({
+			type: "image" as const,
+			data: item.processed?.bytes.toString("base64") ?? "",
+			mimeType: item.processed?.mimeType ?? "",
+		}));
+		const reservation: MessageReservation = {
+			id: cryptoId(this.revision, images),
+			text,
+			streamingBehavior,
+			images,
+			digest: digestImages(images),
+			preflightStarted: false,
+		};
+		this.reservation = reservation;
+		this.bump();
+		return cloneReservation(reservation);
+	}
+
+	markPreflightStarted(): void {
+		if (this.reservation) this.reservation.preflightStarted = true;
+	}
+
+	currentReservation(): MessageReservation | undefined {
+		return this.reservation ? cloneReservation(this.reservation) : undefined;
+	}
+
+	preview(id: string): { bytes: Buffer; mimeType: string } {
+		this.assertOpen();
+		const processed = this.item(id).processed;
+		if (!processed) throw new BatchError("Image preview is not ready", "not-ready");
+		return { bytes: Buffer.from(processed.bytes), mimeType: processed.mimeType };
+	}
+
+	commitReservation(digest: string): boolean {
+		if (!this.reservation || this.reservation.digest !== digest) return false;
+		this.reservation = undefined;
+		this.items = [];
+		this.bump();
+		return true;
+	}
+
+	restoreReservation(): MessageReservation | undefined {
+		if (!this.reservation) return undefined;
+		const restored = cloneReservation(this.reservation);
+		this.reservation = undefined;
+		this.bump();
+		return restored;
+	}
+
+	close(): void {
+		if (this.closed) return;
+		this.closed = true;
+		this.reservation = undefined;
+		this.items = [];
+		this.bump();
+	}
+
+	private phase(): BatchPhase {
+		if (this.closed) return "closed";
+		if (this.reservation) return "reserved";
+		if (this.items.length === 0) return "empty";
+		if (this.items.some((item) => item.status === "error")) return "blocked";
+		if (this.items.every((item) => item.status === "ready")) return "ready";
+		return "editing";
+	}
+
+	private assertOpen(): void {
+		if (this.closed) throw new BatchError("Batch is closed", "closed");
+	}
+
+	private assertMutable(expectedRevision: number): void {
+		this.assertOpen();
+		if (this.reservation) throw new BatchError("Batch is frozen", "frozen");
+		if (expectedRevision !== this.revision)
+			throw new BatchError("Batch revision is stale", "stale");
+	}
+
+	private item(id: string): BatchItem {
+		const item = this.items.find((candidate) => candidate.id === id);
+		if (!item) throw new BatchError("Image not found", "not-found");
+		return item;
+	}
+
+	private bump(): number {
+		this.revision += 1;
+		return this.revision;
+	}
+}
+
+export function digestImages(images: readonly ImageContent[]): string {
+	const hash = createHash("sha256");
+	for (const image of images) {
+		hash.update(image.mimeType);
+		hash.update("\0");
+		hash.update(image.data);
+		hash.update("\0");
+	}
+	return hash.digest("hex");
+}
+
+function cloneProcessed(processed: ProcessedImage): ProcessedImage {
+	return { ...processed, bytes: Buffer.from(processed.bytes), notes: [...processed.notes] };
+}
+
+function cloneReservation(reservation: MessageReservation): MessageReservation {
+	return { ...reservation, images: reservation.images.map((image) => ({ ...image })) };
+}
+
+function sanitizeError(error: string): string {
+	const normalized = [...error]
+		.map((character) => (isControlCharacter(character) ? " " : character))
+		.join("")
+		.replace(/\s+/g, " ")
+		.trim();
+	return normalized.slice(0, 500) || "Image processing failed";
+}
+
+function hasControlCharacter(value: string): boolean {
+	return [...value].some(isControlCharacter);
+}
+
+function isControlCharacter(character: string): boolean {
+	const code = character.charCodeAt(0);
+	return code <= 31 || code === 127;
+}
+
+function isSafeIdentifier(id: string): boolean {
+	return /^[A-Za-z0-9_-]{1,80}$/.test(id);
+}
+
+function cryptoId(revision: number, images: readonly ImageContent[]): string {
+	return createHash("sha256")
+		.update(`${revision}\0${Date.now()}\0${digestImages(images)}`)
+		.digest("hex")
+		.slice(0, 24);
+}

package/src/image-drop.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ImageDropRuntime } from "./runtime.js";
+
+export default function imageDrop(pi: ExtensionAPI) {
+	const runtime = new ImageDropRuntime(pi);
+	runtime.register();
+}
+
+export { ImageDropRuntime } from "./runtime.js";