@pixelvault-dev/paste 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PixelVault
+
+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,48 @@
+# @pixelvault-dev/paste
+
+Paste-and-host for any textarea. Paste, drop, or select an image and get a
+hosted CDN URL inserted at the caret — like GitHub's markdown editor, backed by
+[PixelVault](https://pixelvault.dev) publishable keys.
+
+Framework-agnostic core. No dependencies.
+
+## Usage
+
+```ts
+import { attachPaste } from "@pixelvault-dev/paste";
+
+const detach = attachPaste(document.querySelector("textarea"), {
+  publishableKey: "pv_pub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+});
+
+// later, to remove the listeners:
+detach();
+```
+
+Pasting or dropping an image inserts an `![Uploading…]()` placeholder, uploads
+the file, then replaces the placeholder with `![name](https://img.pixelvault.dev/…)`.
+
+### Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `publishableKey` | `string` | **Required.** A `pv_pub_` key. Create one in the PixelVault dashboard with an origin allowlist. |
+| `endpoint` | `string` | Upload endpoint. Defaults to `https://api.pixelvault.dev/v1/images`. |
+| `folder` | `string` | Optional folder to store uploads under. |
+| `render` | `(result, file) => string` | Text inserted on success. Default: a markdown image tag. Override for HTML, BBCode, a bare URL, etc. |
+| `onUploadStart` | `(file) => void` | Called when an upload begins. |
+| `onUploadComplete` | `(result, file) => void` | Called on success. |
+| `onError` | `(error, file) => string \| void` | Called on failure. Return a string to replace the placeholder with it; return nothing to remove the placeholder. |
+
+### Get a publishable key
+
+Publishable keys are safe to ship in browser code: they are **upload-only** and
+restricted to the request `Origin`s you allowlist. Create one in the dashboard
+under your project's "Publishable keys" section.
+
+## Lower-level API
+
+`uploadImage(file, options)` uploads a single `File` and resolves with
+`{ id, url, mimeType, size }` (throws `PixelVaultPasteError` on failure). The
+event helpers (`imageFilesFromClipboard`, `imageFilesFromDrop`) and text helpers
+(`buildImageMarkdown`, `insertText`) are exported for building custom flows.

package/dist/attach.d.ts

@@ -0,0 +1,34 @@
+import { type UploadResult } from "./upload.js";
+/** A text field paste-and-host can attach to. */
+export type PasteTarget = HTMLTextAreaElement | HTMLInputElement;
+export interface PasteOptions {
+    /** Publishable key (pv_pub_…). Required. */
+    publishableKey: string;
+    /** Upload endpoint. Defaults to the PixelVault production endpoint. */
+    endpoint?: string;
+    /** Optional folder to store uploads under. */
+    folder?: string;
+    /**
+     * Produce the text inserted on success. Defaults to a markdown image tag.
+     * Override to insert HTML, BBCode, a bare URL, etc.
+     */
+    render?: (result: UploadResult, file: File) => string;
+    /** Called when an upload starts. */
+    onUploadStart?: (file: File) => void;
+    /** Called when an upload completes successfully. */
+    onUploadComplete?: (result: UploadResult, file: File) => void;
+    /**
+     * Called on upload failure. Return a string to replace the placeholder with
+     * that text; return nothing to remove the placeholder. If omitted, the
+     * placeholder is removed and the error is logged to the console.
+     */
+    onError?: (error: Error, file: File) => string | void;
+}
+/**
+ * Attach paste-and-host behavior to a textarea or text input: pasting or
+ * dropping an image uploads it to PixelVault and inserts a markdown link at the
+ * caret (with an "Uploading…" placeholder in between).
+ *
+ * Returns a detach function that removes the listeners.
+ */
+export declare function attachPaste(target: PasteTarget, options: PasteOptions): () => void;

package/dist/attach.js

@@ -0,0 +1,99 @@
+import { uploadImage } from "./upload.js";
+import { imageFilesFromClipboard, imageFilesFromDrop } from "./events.js";
+import { buildImageMarkdown, buildPlaceholder, insertText, replaceFirst, } from "./text.js";
+/** A unique token per in-flight upload so concurrent placeholders don't collide. */
+function makeToken() {
+    const c = globalThis.crypto;
+    if (c && typeof c.randomUUID === "function")
+        return c.randomUUID();
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+/** Apply a pure text edit to the element and notify listeners (input event). */
+function applyEdit(field, value, caret) {
+    field.value = value;
+    try {
+        field.selectionStart = caret;
+        field.selectionEnd = caret;
+    }
+    catch {
+        // Some input types don't support selection — safe to ignore.
+    }
+    field.dispatchEvent(new Event("input", { bubbles: true }));
+}
+async function handleFile(target, file, options) {
+    const token = makeToken();
+    const placeholder = buildPlaceholder(file.name, token);
+    const inserted = insertText(target, placeholder);
+    applyEdit(target, inserted.value, inserted.caret);
+    options.onUploadStart?.(file);
+    try {
+        const result = await uploadImage(file, {
+            publishableKey: options.publishableKey,
+            endpoint: options.endpoint,
+            folder: options.folder,
+        });
+        const finalText = options.render
+            ? options.render(result, file)
+            : buildImageMarkdown(result.url, file.name);
+        applyEdit(target, replaceFirst(target.value, placeholder, finalText), target.value.length);
+        options.onUploadComplete?.(result, file);
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        let replacement = "";
+        if (options.onError) {
+            const r = options.onError(error, file);
+            if (typeof r === "string")
+                replacement = r;
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.error("[pixelvault-paste] upload failed:", error);
+        }
+        applyEdit(target, replaceFirst(target.value, placeholder, replacement), target.value.length);
+    }
+}
+function handleFiles(target, files, options) {
+    for (const file of files)
+        void handleFile(target, file, options);
+}
+/**
+ * Attach paste-and-host behavior to a textarea or text input: pasting or
+ * dropping an image uploads it to PixelVault and inserts a markdown link at the
+ * caret (with an "Uploading…" placeholder in between).
+ *
+ * Returns a detach function that removes the listeners.
+ */
+export function attachPaste(target, options) {
+    if (!options.publishableKey) {
+        throw new Error("attachPaste: options.publishableKey is required.");
+    }
+    const onPaste = (e) => {
+        const files = imageFilesFromClipboard(e);
+        if (files.length) {
+            e.preventDefault();
+            handleFiles(target, files, options);
+        }
+    };
+    const onDrop = (e) => {
+        const files = imageFilesFromDrop(e);
+        if (files.length) {
+            e.preventDefault();
+            handleFiles(target, files, options);
+        }
+    };
+    const onDragOver = (e) => {
+        // Only claim the drop when files are being dragged, so text drags still work.
+        const types = e.dataTransfer?.types;
+        if (types && Array.from(types).includes("Files"))
+            e.preventDefault();
+    };
+    target.addEventListener("paste", onPaste);
+    target.addEventListener("drop", onDrop);
+    target.addEventListener("dragover", onDragOver);
+    return () => {
+        target.removeEventListener("paste", onPaste);
+        target.removeEventListener("drop", onDrop);
+        target.removeEventListener("dragover", onDragOver);
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Error thrown when an upload fails. Carries the API error code and HTTP status
+ * when the failure came from the server (vs. a network/other error).
+ */
+export declare class PixelVaultPasteError extends Error {
+    /** Machine-readable code from the API (e.g. "origin_not_allowed"), if any. */
+    readonly code: string | undefined;
+    /** HTTP status of the failed response, if the failure was an HTTP error. */
+    readonly status: number | undefined;
+    constructor(message: string, code?: string, status?: number);
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+/**
+ * Error thrown when an upload fails. Carries the API error code and HTTP status
+ * when the failure came from the server (vs. a network/other error).
+ */
+export class PixelVaultPasteError extends Error {
+    /** Machine-readable code from the API (e.g. "origin_not_allowed"), if any. */
+    code;
+    /** HTTP status of the failed response, if the failure was an HTTP error. */
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.name = "PixelVaultPasteError";
+        this.code = code;
+        this.status = status;
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,6 @@
+/** Extract image `File`s from a DataTransfer (clipboard paste or drag-drop). */
+export declare function imageFilesFromDataTransfer(dt: DataTransfer | null | undefined): File[];
+/** Image files from a paste event (empty if none). */
+export declare function imageFilesFromClipboard(event: ClipboardEvent): File[];
+/** Image files from a drop event (empty if none). */
+export declare function imageFilesFromDrop(event: DragEvent): File[];

package/dist/events.js

@@ -0,0 +1,37 @@
+/** Extract image `File`s from a DataTransfer (clipboard paste or drag-drop). */
+export function imageFilesFromDataTransfer(dt) {
+    if (!dt)
+        return [];
+    const out = [];
+    const seen = new Set();
+    const push = (f) => {
+        if (!f || !f.type.startsWith("image/"))
+            return;
+        const key = `${f.name}:${f.size}:${f.lastModified}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push(f);
+    };
+    // Prefer items — a pasted screenshot shows up here (and sometimes not in
+    // .files on older browsers).
+    if (dt.items) {
+        for (const item of Array.from(dt.items)) {
+            if (item.kind === "file")
+                push(item.getAsFile());
+        }
+    }
+    if (dt.files) {
+        for (const f of Array.from(dt.files))
+            push(f);
+    }
+    return out;
+}
+/** Image files from a paste event (empty if none). */
+export function imageFilesFromClipboard(event) {
+    return imageFilesFromDataTransfer(event.clipboardData);
+}
+/** Image files from a drop event (empty if none). */
+export function imageFilesFromDrop(event) {
+    return imageFilesFromDataTransfer(event.dataTransfer);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { attachPaste } from "./attach.js";
+export type { PasteOptions, PasteTarget } from "./attach.js";
+export { uploadImage, DEFAULT_ENDPOINT } from "./upload.js";
+export type { UploadResult, UploadOptions } from "./upload.js";
+export { PixelVaultPasteError } from "./errors.js";
+export { buildImageMarkdown, buildPlaceholder, insertText, replaceFirst, } from "./text.js";
+export type { TextFieldLike } from "./text.js";
+export { imageFilesFromDataTransfer, imageFilesFromClipboard, imageFilesFromDrop, } from "./events.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { attachPaste } from "./attach.js";
+export { uploadImage, DEFAULT_ENDPOINT } from "./upload.js";
+export { PixelVaultPasteError } from "./errors.js";
+export { buildImageMarkdown, buildPlaceholder, insertText, replaceFirst, } from "./text.js";
+export { imageFilesFromDataTransfer, imageFilesFromClipboard, imageFilesFromDrop, } from "./events.js";

package/dist/text.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Minimal shape of a text field we insert into. Both HTMLTextAreaElement and
+ * HTMLInputElement satisfy it, and tests can pass a plain object.
+ */
+export interface TextFieldLike {
+    value: string;
+    selectionStart: number | null;
+    selectionEnd: number | null;
+}
+/** Build the markdown image tag inserted on successful upload. */
+export declare function buildImageMarkdown(url: string, alt: string): string;
+/**
+ * Build the placeholder inserted while an upload is in flight. The token makes
+ * each placeholder unique so concurrent uploads replace the right one.
+ */
+export declare function buildPlaceholder(fileName: string, token: string): string;
+/** Replace the first occurrence of `needle` in `haystack`. Returns the
+ *  original string unchanged if `needle` isn't present. */
+export declare function replaceFirst(haystack: string, needle: string, replacement: string): string;
+/**
+ * Compute the field value + caret after inserting `text` at the current caret,
+ * replacing any current selection. Pure — the caller applies the result to the
+ * real element. Falls back to appending when the selection is unknown.
+ */
+export declare function insertText(field: TextFieldLike, text: string): {
+    value: string;
+    caret: number;
+};

package/dist/text.js

@@ -0,0 +1,38 @@
+/** Escape the parts of a filename that would break markdown alt text / links. */
+function sanitizeAlt(name) {
+    // Drop the extension for a cleaner alt, and neutralize brackets/newlines.
+    const base = name.replace(/\.[^.]+$/, "") || name;
+    return base.replace(/[\r\n]+/g, " ").replace(/[[\]]/g, "").trim() || "image";
+}
+/** Build the markdown image tag inserted on successful upload. */
+export function buildImageMarkdown(url, alt) {
+    return `![${sanitizeAlt(alt)}](${url})`;
+}
+/**
+ * Build the placeholder inserted while an upload is in flight. The token makes
+ * each placeholder unique so concurrent uploads replace the right one.
+ */
+export function buildPlaceholder(fileName, token) {
+    return `![Uploading ${sanitizeAlt(fileName)}…](uploading#${token})`;
+}
+/** Replace the first occurrence of `needle` in `haystack`. Returns the
+ *  original string unchanged if `needle` isn't present. */
+export function replaceFirst(haystack, needle, replacement) {
+    const i = haystack.indexOf(needle);
+    if (i === -1)
+        return haystack;
+    return haystack.slice(0, i) + replacement + haystack.slice(i + needle.length);
+}
+/**
+ * Compute the field value + caret after inserting `text` at the current caret,
+ * replacing any current selection. Pure — the caller applies the result to the
+ * real element. Falls back to appending when the selection is unknown.
+ */
+export function insertText(field, text) {
+    const value = field.value;
+    const hasSelection = field.selectionStart !== null && field.selectionEnd !== null;
+    const start = hasSelection ? field.selectionStart : value.length;
+    const end = hasSelection ? field.selectionEnd : value.length;
+    const nextValue = value.slice(0, start) + text + value.slice(end);
+    return { value: nextValue, caret: start + text.length };
+}

package/dist/upload.d.ts

@@ -0,0 +1,28 @@
+/** The default PixelVault upload endpoint. */
+export declare const DEFAULT_ENDPOINT = "https://api.pixelvault.dev/v1/images";
+/** A successfully uploaded image. */
+export interface UploadResult {
+    /** Image id (e.g. "img_a1b2c3d4e5f6"). */
+    id: string;
+    /** Public CDN URL. */
+    url: string;
+    /** Detected MIME type. */
+    mimeType: string;
+    /** Size in bytes. */
+    size: number;
+}
+export interface UploadOptions {
+    /** Publishable key (pv_pub_…). Required. */
+    publishableKey: string;
+    /** Upload endpoint. Defaults to {@link DEFAULT_ENDPOINT}. */
+    endpoint?: string;
+    /** Optional folder to store the image under. */
+    folder?: string;
+    /** Abort signal to cancel the request. */
+    signal?: AbortSignal;
+}
+/**
+ * Upload a single image file to PixelVault and resolve with its CDN URL.
+ * Throws {@link PixelVaultPasteError} on any HTTP or network failure.
+ */
+export declare function uploadImage(file: File, options: UploadOptions): Promise<UploadResult>;

package/dist/upload.js

@@ -0,0 +1,49 @@
+import { PixelVaultPasteError } from "./errors.js";
+/** The default PixelVault upload endpoint. */
+export const DEFAULT_ENDPOINT = "https://api.pixelvault.dev/v1/images";
+/**
+ * Upload a single image file to PixelVault and resolve with its CDN URL.
+ * Throws {@link PixelVaultPasteError} on any HTTP or network failure.
+ */
+export async function uploadImage(file, options) {
+    const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+    const form = new FormData();
+    form.append("file", file);
+    if (options.folder)
+        form.append("folder", options.folder);
+    let res;
+    try {
+        res = await fetch(endpoint, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${options.publishableKey}` },
+            body: form,
+            signal: options.signal,
+        });
+    }
+    catch (err) {
+        // Network error, abort, CORS rejection, etc.
+        const message = err instanceof Error ? err.message : "Upload request failed.";
+        throw new PixelVaultPasteError(message);
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        body = undefined;
+    }
+    if (!res.ok) {
+        const apiErr = body;
+        throw new PixelVaultPasteError(apiErr?.error?.message ?? `Upload failed with status ${res.status}.`, apiErr?.error?.code, res.status);
+    }
+    const data = body?.data;
+    if (!data || typeof data.url !== "string") {
+        throw new PixelVaultPasteError("Upload succeeded but the response was malformed.");
+    }
+    return {
+        id: data.id,
+        url: data.url,
+        mimeType: data.mime_type,
+        size: data.size,
+    };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@pixelvault-dev/paste",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Paste-and-host: drop, paste, or select an image in any textarea and get a hosted CDN URL back. Backed by PixelVault publishable keys.",
+  "keywords": [
+    "image",
+    "upload",
+    "paste",
+    "clipboard",
+    "drag-and-drop",
+    "cdn",
+    "textarea",
+    "pixelvault"
+  ],
+  "homepage": "https://pixelvault.dev/docs#paste",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pixelvault-dev/pixelvault.git",
+    "directory": "packages/paste"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.4"
+  }
+}