backpack-viewer 0.6.0 → 0.7.1

package/dist/extensions/manifest.js

@@ -0,0 +1,116 @@
+import { VIEWER_API_VERSION } from "./types.js";
+export class ManifestError extends Error {
+    constructor(extensionPath, problem) {
+        super(`Invalid manifest at ${extensionPath}: ${problem}`);
+        this.name = "ManifestError";
+    }
+}
+/**
+ * Validate a parsed manifest object. Throws ManifestError on invalid input.
+ * Returns the typed manifest. Stricter than tsc since the file comes from
+ * disk; we want clear errors at load time, not silent misbehavior later.
+ */
+export function validateManifest(raw, extensionPath) {
+    if (!raw || typeof raw !== "object") {
+        throw new ManifestError(extensionPath, "must be a JSON object");
+    }
+    const obj = raw;
+    function requireString(field) {
+        const v = obj[field];
+        if (typeof v !== "string" || !v) {
+            throw new ManifestError(extensionPath, `field "${field}" must be a non-empty string`);
+        }
+        return v;
+    }
+    const name = requireString("name");
+    const version = requireString("version");
+    const viewerApi = requireString("viewerApi");
+    const entry = requireString("entry");
+    if (viewerApi !== VIEWER_API_VERSION) {
+        throw new ManifestError(extensionPath, `viewerApi "${viewerApi}" is not supported (this viewer supports "${VIEWER_API_VERSION}")`);
+    }
+    if (!/^[a-z0-9][a-z0-9-_]*$/.test(name)) {
+        throw new ManifestError(extensionPath, `name "${name}" must be lowercase with hyphens/underscores only — used as a URL path segment and a directory name`);
+    }
+    // Optional fields
+    const displayName = typeof obj.displayName === "string" ? obj.displayName : undefined;
+    const description = typeof obj.description === "string" ? obj.description : undefined;
+    const stylesheet = typeof obj.stylesheet === "string" ? obj.stylesheet : undefined;
+    let permissions;
+    if (obj.permissions !== undefined) {
+        if (!obj.permissions || typeof obj.permissions !== "object") {
+            throw new ManifestError(extensionPath, "permissions must be an object");
+        }
+        permissions = validatePermissions(obj.permissions, extensionPath);
+    }
+    return { name, version, viewerApi, displayName, description, entry, stylesheet, permissions };
+}
+function validatePermissions(raw, extensionPath) {
+    const out = {};
+    if (raw.graph !== undefined) {
+        if (!Array.isArray(raw.graph)) {
+            throw new ManifestError(extensionPath, "permissions.graph must be an array");
+        }
+        out.graph = raw.graph.filter((v) => v === "read" || v === "write");
+    }
+    if (raw.viewer !== undefined) {
+        if (!Array.isArray(raw.viewer)) {
+            throw new ManifestError(extensionPath, "permissions.viewer must be an array");
+        }
+        out.viewer = raw.viewer.filter((v) => v === "focus" || v === "pan");
+    }
+    if (raw.settings !== undefined) {
+        out.settings = raw.settings === true;
+    }
+    if (raw.network !== undefined) {
+        if (!Array.isArray(raw.network)) {
+            throw new ManifestError(extensionPath, "permissions.network must be an array");
+        }
+        out.network = raw.network.map((entry, i) => validateNetworkEntry(entry, i, extensionPath));
+    }
+    return out;
+}
+function validateNetworkEntry(raw, index, extensionPath) {
+    if (!raw || typeof raw !== "object") {
+        throw new ManifestError(extensionPath, `permissions.network[${index}] must be an object with { origin, injectHeaders? }`);
+    }
+    const obj = raw;
+    const origin = obj.origin;
+    if (typeof origin !== "string" || !origin) {
+        throw new ManifestError(extensionPath, `permissions.network[${index}].origin must be a non-empty string`);
+    }
+    // Reject obviously bad shapes early
+    let parsed;
+    try {
+        parsed = new URL(origin);
+    }
+    catch {
+        throw new ManifestError(extensionPath, `permissions.network[${index}].origin "${origin}" is not a valid URL`);
+    }
+    if (parsed.pathname !== "/" && parsed.pathname !== "") {
+        throw new ManifestError(extensionPath, `permissions.network[${index}].origin must be a bare origin (no path); got "${origin}"`);
+    }
+    let injectHeaders;
+    if (obj.injectHeaders !== undefined) {
+        if (!obj.injectHeaders || typeof obj.injectHeaders !== "object") {
+            throw new ManifestError(extensionPath, `permissions.network[${index}].injectHeaders must be an object`);
+        }
+        injectHeaders = {};
+        for (const [headerName, value] of Object.entries(obj.injectHeaders)) {
+            if (!value || typeof value !== "object") {
+                throw new ManifestError(extensionPath, `injectHeaders.${headerName} must be an object`);
+            }
+            const v = value;
+            if (typeof v.fromEnv === "string") {
+                injectHeaders[headerName] = { fromEnv: v.fromEnv };
+            }
+            else if (typeof v.literal === "string") {
+                injectHeaders[headerName] = { literal: v.literal };
+            }
+            else {
+                throw new ManifestError(extensionPath, `injectHeaders.${headerName} must have either fromEnv (string) or literal (string)`);
+            }
+        }
+    }
+    return { origin: parsed.origin, injectHeaders };
+}

package/dist/extensions/panel-mount.d.ts

@@ -0,0 +1,26 @@
+import type { MountPanelOptions, MountedPanel } from "./types";
+/**
+ * Panel mount surface — wraps an extension-provided body element with
+ * standard chrome (title, custom buttons, fullscreen toggle, close X)
+ * and makes it draggable + click-to-front + position-persistent.
+ *
+ * Layout policy:
+ *   - Each panel positions itself via inline left/top from JS, so
+ *     drag-to-move is just updating those properties.
+ *   - The user grabs the title bar to move the panel anywhere within
+ *     the canvas container. Bounds-clamped so the title bar stays
+ *     visible.
+ *   - Click anywhere on a panel raises it above all other panels via
+ *     a shared z-index counter. The counter is module-global so
+ *     info-panel and extension panels share the same focus stack.
+ *   - Position + fullscreen state are persisted to localStorage per
+ *     panel key, so dragging + maximize survive page refreshes.
+ *
+ * No region/dock vocabulary, no automatic collision avoidance — if
+ * two panels overlap, the user drags one out of the way. The user is
+ * the layout coordinator.
+ */
+export interface PanelMount {
+    mount(extName: string, body: HTMLElement, opts?: MountPanelOptions): MountedPanel;
+}
+export declare function createPanelMount(parent: HTMLElement): PanelMount;

package/dist/extensions/panel-mount.js

@@ -0,0 +1,377 @@
+import { makeSvgIcon } from "../dom-utils";
+const PANEL_TIER_BASE = 30; // matches --z-panel
+const PANEL_TIER_MAX = 39; // last value before --z-floating (40); reset above this
+const FULLSCREEN_Z = 45; // matches --z-panel-fullscreen — above secondary floating, below floating-primary (search bar)
+const DEFAULT_PANEL_WIDTH = 380;
+const DEFAULT_TOP_OFFSET = 70;
+const DEFAULT_RIGHT_MARGIN = 16;
+const MIN_VISIBLE_AFTER_DRAG = 80;
+const STORAGE_PREFIX = "backpack-viewer:panel:";
+const FULLSCREEN_PARENT_CLASS = "has-fullscreen-panel";
+/**
+ * Module-global click-to-front counter shared by all panels (info-panel
+ * AND extension panels). Click any panel and it bumps it above the
+ * other panels in the panel tier. Reset on page reload.
+ *
+ * If the counter ever exceeds PANEL_TIER_MAX (e.g., the user clicks
+ * many panels back and forth), all panels reset to base+1 and the
+ * counter resumes — this prevents panels from leaking into the
+ * floating tier and overlapping the top bar.
+ */
+let topZ = PANEL_TIER_BASE;
+function bringPanelToFront(panel) {
+    topZ++;
+    if (topZ > PANEL_TIER_MAX) {
+        // Compress: reset every panel in the layer to base+1, then
+        // promote this one. Counter resumes from base+2.
+        document.querySelectorAll(".extension-panel").forEach((p) => {
+            p.style.zIndex = String(PANEL_TIER_BASE + 1);
+        });
+        topZ = PANEL_TIER_BASE + 2;
+    }
+    panel.style.zIndex = String(topZ);
+}
+/**
+ * Ref-count of panels currently in fullscreen mode. The has-fullscreen
+ * class is added to #canvas-container while count > 0 and removed when
+ * it drops to 0. CSS uses the class to hide secondary top-bar controls
+ * (zoom, theme, copy-prompt, sidebar-expand, taskbar slots) so they
+ * don't visually conflict with the fullscreen panel's chrome buttons.
+ */
+let fullscreenCount = 0;
+function notifyFullscreenChange(parent, entering) {
+    // Walk up to #canvas-container — that's where the class lives.
+    // If parent is the canvas container itself, use it directly.
+    const target = parent.id === "canvas-container"
+        ? parent
+        : parent.closest("#canvas-container") ?? parent;
+    if (entering) {
+        fullscreenCount++;
+    }
+    else {
+        fullscreenCount = Math.max(0, fullscreenCount - 1);
+    }
+    target.classList.toggle(FULLSCREEN_PARENT_CLASS, fullscreenCount > 0);
+}
+function loadPersistedState(key) {
+    try {
+        const raw = localStorage.getItem(STORAGE_PREFIX + key);
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object")
+            return parsed;
+    }
+    catch {
+        /* ignore — best effort */
+    }
+    return null;
+}
+function savePersistedState(key, state) {
+    try {
+        localStorage.setItem(STORAGE_PREFIX + key, JSON.stringify(state));
+    }
+    catch {
+        /* ignore — quota exceeded etc */
+    }
+}
+/** Build a fullscreen-toggle SVG icon (4 corner arrows). */
+function makeFullscreenIcon() {
+    return makeSvgIcon({ size: 13, strokeWidth: 1.8, strokeLinecap: "round", strokeLinejoin: "round" }, [
+        { tag: "polyline", attrs: { points: "4 9 4 4 9 4" } },
+        { tag: "polyline", attrs: { points: "20 9 20 4 15 4" } },
+        { tag: "polyline", attrs: { points: "4 15 4 20 9 20" } },
+        { tag: "polyline", attrs: { points: "20 15 20 20 15 20" } },
+    ]);
+}
+/** Build a restore-from-fullscreen SVG icon (4 inward arrows). */
+function makeRestoreIcon() {
+    return makeSvgIcon({ size: 13, strokeWidth: 1.8, strokeLinecap: "round", strokeLinejoin: "round" }, [
+        { tag: "polyline", attrs: { points: "9 4 9 9 4 9" } },
+        { tag: "polyline", attrs: { points: "15 4 15 9 20 9" } },
+        { tag: "polyline", attrs: { points: "9 20 9 15 4 15" } },
+        { tag: "polyline", attrs: { points: "15 20 15 15 20 15" } },
+    ]);
+}
+export function createPanelMount(parent) {
+    const layer = document.createElement("div");
+    layer.className = "extension-panel-layer";
+    parent.appendChild(layer);
+    function defaultPosition() {
+        const parentRect = parent.getBoundingClientRect();
+        const left = Math.max(0, parentRect.width - DEFAULT_PANEL_WIDTH - DEFAULT_RIGHT_MARGIN);
+        return { left, top: DEFAULT_TOP_OFFSET };
+    }
+    function clampPosition(pos, panelRect) {
+        const parentRect = parent.getBoundingClientRect();
+        const minLeft = MIN_VISIBLE_AFTER_DRAG - panelRect.width;
+        const maxLeft = parentRect.width - MIN_VISIBLE_AFTER_DRAG;
+        const minTop = 0;
+        const maxTop = parentRect.height - 40;
+        return {
+            left: Math.max(minLeft, Math.min(maxLeft, pos.left)),
+            top: Math.max(minTop, Math.min(maxTop, pos.top)),
+        };
+    }
+    function mount(extName, body, opts = {}) {
+        const persistKey = opts.persistKey ?? extName;
+        const persisted = loadPersistedState(persistKey);
+        const root = document.createElement("aside");
+        root.className = "extension-panel";
+        root.dataset.panel = persistKey;
+        // --- Header (drag handle + chrome) ---
+        const header = document.createElement("div");
+        header.className = "extension-panel-header";
+        const titleEl = document.createElement("span");
+        titleEl.className = "extension-panel-title";
+        titleEl.textContent = opts.title ?? extName;
+        header.appendChild(titleEl);
+        // Custom header buttons get their own container so setHeaderButtons
+        // can replace its children without disturbing the built-in controls.
+        const customBtnContainer = document.createElement("div");
+        customBtnContainer.className = "extension-panel-custom-btns";
+        header.appendChild(customBtnContainer);
+        function renderCustomButtons(buttons) {
+            customBtnContainer.replaceChildren();
+            for (const spec of buttons) {
+                const btn = document.createElement("button");
+                btn.className = "extension-panel-btn";
+                btn.title = spec.label;
+                btn.setAttribute("aria-label", spec.label);
+                btn.textContent = spec.iconText ?? spec.label;
+                if (spec.disabled)
+                    btn.disabled = true;
+                btn.addEventListener("click", (e) => {
+                    e.stopPropagation();
+                    try {
+                        spec.onClick();
+                    }
+                    catch (err) {
+                        console.error(`[backpack-viewer] panel header button "${spec.label}" threw:`, err);
+                    }
+                });
+                // Buttons live inside the header (which is the drag handle), so
+                // mousedown must not start a drag.
+                btn.addEventListener("mousedown", (e) => e.stopPropagation());
+                customBtnContainer.appendChild(btn);
+            }
+        }
+        renderCustomButtons(opts.headerButtons ?? []);
+        // --- Built-in fullscreen + close buttons ---
+        let fullscreen = false;
+        let fullscreenBtn = null;
+        let fullscreenIconEl = null;
+        if (opts.showFullscreenButton !== false) {
+            fullscreenBtn = document.createElement("button");
+            fullscreenBtn.className = "extension-panel-btn extension-panel-btn-fullscreen";
+            fullscreenBtn.title = "Toggle fullscreen";
+            fullscreenBtn.setAttribute("aria-label", "Toggle fullscreen");
+            fullscreenIconEl = makeFullscreenIcon();
+            fullscreenBtn.appendChild(fullscreenIconEl);
+            fullscreenBtn.addEventListener("click", (e) => {
+                e.stopPropagation();
+                setFullscreen(!fullscreen);
+            });
+            fullscreenBtn.addEventListener("mousedown", (e) => e.stopPropagation());
+            header.appendChild(fullscreenBtn);
+        }
+        let closeBtn = null;
+        if (opts.showCloseButton !== false) {
+            closeBtn = document.createElement("button");
+            closeBtn.className = "extension-panel-btn extension-panel-btn-close";
+            closeBtn.title = "Close panel";
+            closeBtn.setAttribute("aria-label", "Close panel");
+            closeBtn.textContent = "\u00d7";
+            closeBtn.addEventListener("click", (e) => {
+                e.stopPropagation();
+                if (opts.hideOnClose) {
+                    setVisible(false);
+                    // Fire onClose for hideOnClose panels too — owners may want
+                    // to reset state.
+                    try {
+                        opts.onClose?.();
+                    }
+                    catch (err) {
+                        console.error("[backpack-viewer] panel onClose threw:", err);
+                    }
+                }
+                else {
+                    close();
+                }
+            });
+            closeBtn.addEventListener("mousedown", (e) => e.stopPropagation());
+            header.appendChild(closeBtn);
+        }
+        root.appendChild(header);
+        // --- Body ---
+        const bodyWrap = document.createElement("div");
+        bodyWrap.className = "extension-panel-body";
+        bodyWrap.appendChild(body);
+        root.appendChild(bodyWrap);
+        layer.appendChild(root);
+        // --- Initial position ---
+        // Priority: persisted > opts.defaultPosition > computed default
+        const initial = (persisted && persisted.left != null && persisted.top != null)
+            ? { left: persisted.left, top: persisted.top }
+            : (opts.defaultPosition ?? defaultPosition());
+        // Bounds-clamp the restored position in case the viewport shrank
+        // since it was saved (otherwise the panel could end up off-screen
+        // and unrecoverable).
+        const initialRect = { width: DEFAULT_PANEL_WIDTH, height: 200 };
+        const clampedInitial = clampPosition(initial, initialRect);
+        root.style.left = clampedInitial.left + "px";
+        root.style.top = clampedInitial.top + "px";
+        bringPanelToFront(root);
+        // --- Drag handling ---
+        let dragStartX = 0;
+        let dragStartY = 0;
+        let panelStartLeft = 0;
+        let panelStartTop = 0;
+        let dragging = false;
+        function onMouseMove(e) {
+            if (!dragging)
+                return;
+            const dx = e.clientX - dragStartX;
+            const dy = e.clientY - dragStartY;
+            const next = clampPosition({ left: panelStartLeft + dx, top: panelStartTop + dy }, root.getBoundingClientRect());
+            root.style.left = next.left + "px";
+            root.style.top = next.top + "px";
+        }
+        function onMouseUp() {
+            if (!dragging)
+                return;
+            dragging = false;
+            document.removeEventListener("mousemove", onMouseMove);
+            document.removeEventListener("mouseup", onMouseUp);
+            // Persist the new position
+            const rect = root.getBoundingClientRect();
+            const parentRect = parent.getBoundingClientRect();
+            savePersistedState(persistKey, {
+                ...loadPersistedState(persistKey),
+                left: rect.left - parentRect.left,
+                top: rect.top - parentRect.top,
+            });
+        }
+        header.addEventListener("mousedown", (e) => {
+            if (fullscreen)
+                return; // can't drag while fullscreen
+            // Buttons inside the header stop propagation already, so we know
+            // this came from the title area or empty space.
+            dragging = true;
+            dragStartX = e.clientX;
+            dragStartY = e.clientY;
+            const rect = root.getBoundingClientRect();
+            const parentRect = parent.getBoundingClientRect();
+            panelStartLeft = rect.left - parentRect.left;
+            panelStartTop = rect.top - parentRect.top;
+            bringPanelToFront(root);
+            document.addEventListener("mousemove", onMouseMove);
+            document.addEventListener("mouseup", onMouseUp);
+            e.preventDefault();
+        });
+        // Click anywhere on the panel raises it.
+        root.addEventListener("mousedown", () => {
+            if (!fullscreen)
+                bringPanelToFront(root);
+        }, { capture: true });
+        // --- Lifecycle ---
+        let closed = false;
+        let visible = true;
+        function close() {
+            if (closed)
+                return;
+            closed = true;
+            document.removeEventListener("mousemove", onMouseMove);
+            document.removeEventListener("mouseup", onMouseUp);
+            // If this panel was in fullscreen, decrement the global counter
+            // so the parent class clears properly.
+            if (fullscreen) {
+                notifyFullscreenChange(parent, false);
+                fullscreen = false;
+            }
+            root.remove();
+            try {
+                opts.onClose?.();
+            }
+            catch (err) {
+                console.error("[backpack-viewer] panel onClose threw:", err);
+            }
+        }
+        function setVisible(value) {
+            if (value === visible)
+                return;
+            visible = value;
+            root.classList.toggle("is-hidden", !visible);
+            if (visible) {
+                bringPanelToFront(root);
+                // If we were fullscreen when hidden, the global counter was
+                // decremented; restore it now that we're visible again.
+                if (fullscreen) {
+                    notifyFullscreenChange(parent, true);
+                }
+            }
+            else if (fullscreen) {
+                // Hidden while fullscreen — decrement the global counter so
+                // other panels and the top bar reappear.
+                notifyFullscreenChange(parent, false);
+            }
+        }
+        function setFullscreen(value) {
+            if (value === fullscreen)
+                return;
+            fullscreen = value;
+            root.classList.toggle("is-fullscreen", fullscreen);
+            // Swap the icon between the fullscreen-out and restore-in glyphs
+            if (fullscreenBtn && fullscreenIconEl) {
+                fullscreenIconEl.remove();
+                fullscreenIconEl = fullscreen ? makeRestoreIcon() : makeFullscreenIcon();
+                fullscreenBtn.appendChild(fullscreenIconEl);
+            }
+            // Bump z-index above secondary floating tier when fullscreen so
+            // the panel covers zoom/theme/copy-prompt; restore to the
+            // panel-tier counter when not. The search bar lives at
+            // --z-floating-primary above this and stays visible.
+            if (fullscreen) {
+                root.style.zIndex = String(FULLSCREEN_Z);
+            }
+            else {
+                bringPanelToFront(root);
+            }
+            // Toggle the parent class so CSS hides secondary controls
+            notifyFullscreenChange(parent, fullscreen);
+            // Persist
+            savePersistedState(persistKey, {
+                ...loadPersistedState(persistKey),
+                fullscreen,
+            });
+            try {
+                opts.onFullscreenChange?.(fullscreen);
+            }
+            catch (err) {
+                console.error("[backpack-viewer] panel onFullscreenChange threw:", err);
+            }
+        }
+        // Restore fullscreen state if persisted
+        if (persisted?.fullscreen) {
+            setFullscreen(true);
+        }
+        function setTitle(t) {
+            titleEl.textContent = t;
+        }
+        function setHeaderButtons(buttons) {
+            renderCustomButtons(buttons);
+        }
+        return {
+            close,
+            setFullscreen,
+            isFullscreen: () => fullscreen,
+            setTitle,
+            setHeaderButtons,
+            setVisible,
+            isVisible: () => visible,
+            bringToFront: () => bringPanelToFront(root),
+            element: body,
+        };
+    }
+    return { mount };
+}

package/dist/extensions/share/backpack-extension.json

@@ -0,0 +1,20 @@
+{
+  "name": "share",
+  "version": "0.1.0",
+  "viewerApi": "1",
+  "displayName": "Share",
+  "description": "Share encrypted backpacks via a link. Recipients decrypt in-browser — the server never sees your data.",
+  "entry": "src/index.js",
+  "stylesheet": "style.css",
+  "permissions": {
+    "graph": ["read"],
+    "viewer": [],
+    "settings": true,
+    "network": [
+      {
+        "origin": "https://app.backpackontology.com",
+        "description": "Share relay for uploading encrypted backpacks"
+      }
+    ]
+  }
+}