@proto-labs-inc/rig-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Proto Labs Inc.
+
+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,7 @@
+# @proto-labs-inc/rig-core
+
+The rig, framework-free: URL-state sync, the postMessage bridge to Proto's
+Frame, and comment mode. Prototypes use it through an adapter,
+`@proto-labs-inc/rig` for React or `@proto-labs-inc/rig-vue` for Vue.
+Comment capture lazy-imports `modern-screenshot` from the prototype's own
+dependencies; without it a comment still works, with no picture.

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The rig's framework-free core: URL-state sync, the bridge, and comment
+ * mode. Everything here is plain DOM + history + postMessage — no framework.
+ * Framework adapters (@proto-labs-inc/rig for React, @proto-labs-inc/rig-vue for Vue) wrap
+ * this with their own idioms and nothing else.
+ */
+import { type Manifest, type ResolvedPreviewTheme, type RigToFrame } from "@proto-labs-inc/wire";
+export { STATE_PARAM, variantParam } from "@proto-labs-inc/wire";
+export declare const INTERNAL_PREVIEW_THEME_PARAM = "__protoTheme";
+export declare function applyPreviewTheme(theme: ResolvedPreviewTheme): void;
+/** All addressable state, mirrored to the URL. Keys: "state" | "v.<component>". */
+export declare class RigStore {
+    private values;
+    private listeners;
+    constructor(manifest: Manifest);
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    setMany(entries: Array<[string, string]>): void;
+    setState(id: string, variants: Record<string, string>): void;
+    subscribe: (l: () => void) => () => void;
+    private syncUrl;
+}
+export declare function postToFrame(msg: RigToFrame): void;
+/**
+ * Wire a store to the bridge: listen for Frame messages, announce the rig,
+ * and report the boot-time state (the deep-link fix). Returns a disposer.
+ * Call client-side only.
+ */
+export declare function wireRig(store: RigStore, manifest: Manifest): () => void;

package/dist/index.js

@@ -0,0 +1,569 @@
+/**
+ * The rig's framework-free core: URL-state sync, the bridge, and comment
+ * mode. Everything here is plain DOM + history + postMessage — no framework.
+ * Framework adapters (@proto-labs-inc/rig for React, @proto-labs-inc/rig-vue for Vue) wrap
+ * this with their own idioms and nothing else.
+ */
+import { PROTOCOL_VERSION, STATE_PARAM, variantParam, isFrameToRig, } from "@proto-labs-inc/wire";
+export { STATE_PARAM, variantParam } from "@proto-labs-inc/wire";
+const RIG_VERSION = "0.1.0";
+export const INTERNAL_PREVIEW_THEME_PARAM = "__protoTheme";
+export function applyPreviewTheme(theme) {
+    if (typeof document === "undefined")
+        return;
+    const root = document.documentElement;
+    root.dataset.protoTheme = theme;
+    root.classList.toggle("dark", theme === "dark");
+    root.style.colorScheme = theme;
+}
+function resolvedSystemTheme() {
+    return window.matchMedia("(prefers-color-scheme: dark)").matches
+        ? "dark"
+        : "light";
+}
+function searchForFrame() {
+    const params = new URLSearchParams(window.location.search);
+    params.delete(INTERNAL_PREVIEW_THEME_PARAM);
+    const search = params.toString();
+    return search ? `?${search}` : "";
+}
+/** All addressable state, mirrored to the URL. Keys: "state" | "v.<component>". */
+export class RigStore {
+    values = new Map();
+    listeners = new Set();
+    constructor(manifest) {
+        if (typeof window === "undefined")
+            return;
+        const params = new URLSearchParams(window.location.search);
+        const bootTheme = params.get(INTERNAL_PREVIEW_THEME_PARAM);
+        applyPreviewTheme(bootTheme === "light" || bootTheme === "dark"
+            ? bootTheme
+            : resolvedSystemTheme());
+        for (const [k, v] of params) {
+            if (k === STATE_PARAM || k.startsWith("v."))
+                this.values.set(k, v);
+        }
+        const state = manifest.states.find((s) => s.id === this.values.get(STATE_PARAM));
+        let hydrated = false;
+        for (const [component, variant] of Object.entries(state?.variants ?? {})) {
+            const key = variantParam(component);
+            if (this.values.has(key))
+                continue;
+            this.values.set(key, variant);
+            params.set(key, variant);
+            hydrated = true;
+        }
+        if (hydrated) {
+            window.history.replaceState(null, "", `?${params.toString()}`);
+        }
+    }
+    get(key) {
+        return this.values.get(key);
+    }
+    set(key, value) {
+        this.setMany([[key, value]]);
+    }
+    setMany(entries) {
+        let changed = false;
+        for (const [key, value] of entries) {
+            if (this.values.get(key) === value)
+                continue;
+            this.values.set(key, value);
+            changed = true;
+        }
+        if (!changed)
+            return;
+        this.syncUrl();
+        this.listeners.forEach((l) => l());
+    }
+    setState(id, variants) {
+        const next = new Map([[STATE_PARAM, id]]);
+        for (const [component, variant] of Object.entries(variants)) {
+            next.set(variantParam(component), variant);
+        }
+        let changed = this.values.size !== next.size;
+        if (!changed) {
+            for (const [key, value] of next) {
+                if (this.values.get(key) !== value) {
+                    changed = true;
+                    break;
+                }
+            }
+        }
+        if (!changed)
+            return;
+        this.values = next;
+        this.syncUrl();
+        this.listeners.forEach((l) => l());
+    }
+    subscribe = (l) => {
+        this.listeners.add(l);
+        return () => {
+            this.listeners.delete(l);
+        };
+    };
+    syncUrl() {
+        const params = new URLSearchParams(window.location.search);
+        for (const key of [...params.keys()]) {
+            if (key === STATE_PARAM || key.startsWith("v."))
+                params.delete(key);
+        }
+        for (const [k, v] of this.values)
+            params.set(k, v);
+        const search = `?${params.toString()}`;
+        window.history.replaceState(null, "", search);
+        postToFrame({ type: "state-changed", search: searchForFrame() });
+    }
+}
+export function postToFrame(msg) {
+    // P0: the Frame's origin isn't known to the prototype; "*" is acceptable
+    // because nothing sensitive crosses the bridge. Revisit with link protection.
+    if (typeof window !== "undefined" && window.parent !== window)
+        window.parent.postMessage(msg, "*");
+}
+// ─── comment mode ──────────────────────────────────────────────────
+// The Frame can't touch this document (cross-origin iframe), so the blue
+// selector runs here: hit-test [data-proto-id] under the cursor, draw the
+// highlight, and on click capture the view with the highlight baked in.
+// The highlight is Proto blue (#0088FF): 2px solid at 55%, a 6% fill,
+// radius 4px, 0.12s ease-out entry; the picker layer sits at z-index 99997.
+const COMMENT_BLUE = "#0088FF";
+const TARGET_ATTR = "data-proto-id";
+function selectorFor(element) {
+    if (element === document.documentElement)
+        return "html";
+    if (element === document.body)
+        return "body";
+    const protoId = element.getAttribute(TARGET_ATTR);
+    if (protoId)
+        return `[${TARGET_ATTR}="${CSS.escape(protoId)}"]`;
+    if (element.id) {
+        const idSelector = `#${CSS.escape(element.id)}`;
+        if (document.querySelectorAll(idSelector).length === 1)
+            return idSelector;
+    }
+    const owner = element.closest(`[${TARGET_ATTR}]`);
+    const boundary = owner ?? document.body;
+    const segments = [];
+    let current = element;
+    while (current && current !== boundary) {
+        const tag = current.tagName.toLowerCase();
+        const currentTagName = current.tagName;
+        const siblings = current.parentElement
+            ? [...current.parentElement.children].filter((sibling) => sibling.tagName === currentTagName)
+            : [];
+        const index = siblings.indexOf(current);
+        segments.unshift(siblings.length > 1 && index >= 0 ? `${tag}:nth-of-type(${index + 1})` : tag);
+        current = current.parentElement;
+    }
+    const base = owner
+        ? `[${TARGET_ATTR}="${CSS.escape(owner.getAttribute(TARGET_ATTR) ?? "")}"]`
+        : boundary === element
+            ? element.tagName.toLowerCase()
+            : "body";
+    return segments.length > 0 ? `${base} > ${segments.join(" > ")}` : base;
+}
+async function waitForCaptureReady() {
+    const pendingImages = [...document.images]
+        .filter((image) => !image.complete)
+        .map((image) => new Promise((resolve) => {
+        image.addEventListener("load", () => resolve(), { once: true });
+        image.addEventListener("error", () => resolve(), { once: true });
+    }));
+    const assetsReady = Promise.all([document.fonts.ready, ...pendingImages]);
+    await Promise.race([
+        assetsReady,
+        new Promise((resolve) => window.setTimeout(resolve, 3000)),
+    ]);
+    // requestAnimationFrame may be suspended for an invisible iframe. The timer
+    // also lets entrance transitions and canvas-backed backgrounds reach their
+    // resting state before the gallery captures them.
+    await new Promise((resolve) => window.setTimeout(resolve, 1500));
+}
+async function captureViewport(scale = Math.min(window.devicePixelRatio || 1, 2)) {
+    try {
+        // Optional peer provided by the prototype, not the rig.
+        const mod = (await import("modern-screenshot"));
+        const root = document.body;
+        const viewportWidth = document.documentElement.clientWidth;
+        const viewportHeight = document.documentElement.clientHeight;
+        const scrollX = window.scrollX || document.documentElement.scrollLeft;
+        const scrollY = window.scrollY || document.documentElement.scrollTop;
+        const contentWidth = Math.max(viewportWidth, document.documentElement.scrollWidth, root.scrollWidth);
+        const contentHeight = Math.max(viewportHeight, document.documentElement.scrollHeight, root.scrollHeight);
+        return await mod.domToDataUrl(root, {
+            scale,
+            width: viewportWidth,
+            height: viewportHeight,
+            features: { restoreScrollPosition: true },
+            style: {
+                margin: "0",
+                width: `${contentWidth}px`,
+                height: `${contentHeight}px`,
+                transform: `translate(${-scrollX}px, ${-scrollY}px)`,
+                transformOrigin: "top left",
+                overflow: "visible",
+            },
+            onCloneNode: (cloned) => {
+                if (!(cloned instanceof HTMLElement) || (!scrollX && !scrollY))
+                    return;
+                const fixed = [cloned, ...cloned.querySelectorAll("*")].filter((element) => element.style.position === "fixed");
+                for (const element of fixed) {
+                    const existing = element.style.transform;
+                    element.style.transform =
+                        `translate(${scrollX}px, ${scrollY}px)` +
+                            (existing && existing !== "none" ? ` ${existing}` : "");
+                }
+            },
+        });
+    }
+    catch {
+        return null;
+    }
+}
+async function captureThumbnail() {
+    const restingState = document.createElement("style");
+    restingState.textContent = `
+    *, *::before, *::after {
+      animation-delay: 0s !important;
+      animation-duration: 0s !important;
+      transition-delay: 0s !important;
+      transition-duration: 0s !important;
+    }
+    .opacity-0,
+    [style*="opacity: 0"] {
+      opacity: 1 !important;
+      transform: none !important;
+    }
+  `;
+    document.head.append(restingState);
+    try {
+        for (const animation of document.getAnimations()) {
+            try {
+                animation.finish();
+            }
+            catch {
+                animation.cancel();
+            }
+        }
+        await waitForCaptureReady();
+        // Optional peer provided by the prototype, not the rig.
+        const mod = (await import("modern-screenshot"));
+        const bodyBackground = window.getComputedStyle(document.body).backgroundColor;
+        const htmlBackground = window.getComputedStyle(document.documentElement).backgroundColor;
+        const backgroundColor = bodyBackground !== "rgba(0, 0, 0, 0)" ? bodyBackground : htmlBackground;
+        return await mod.domToDataUrl(document.documentElement, {
+            backgroundColor,
+            timeout: 5000,
+            width: window.innerWidth,
+            height: window.innerHeight,
+            scale: 1,
+        });
+    }
+    catch {
+        return null;
+    }
+    finally {
+        restingState.remove();
+    }
+}
+class ElementPicker {
+    overlay = null;
+    highlight = null;
+    cursorStyle = null;
+    target = null;
+    active = false;
+    mode = null;
+    enable(mode) {
+        if (typeof document === "undefined")
+            return;
+        if (this.active || this.overlay)
+            this.disable();
+        this.active = true;
+        this.mode = mode;
+        this.cursorStyle = document.createElement("style");
+        this.cursorStyle.setAttribute("data-proto-picker-cursor", "");
+        this.cursorStyle.textContent =
+            "html, body, body * { cursor: crosshair !important; }";
+        document.head.appendChild(this.cursorStyle);
+        const blue = COMMENT_BLUE;
+        this.overlay = document.createElement("div");
+        this.overlay.setAttribute("data-proto-rig-overlay", "");
+        Object.assign(this.overlay.style, {
+            position: "fixed",
+            inset: "0",
+            zIndex: "99997",
+            pointerEvents: "none",
+        });
+        this.highlight = document.createElement("div");
+        Object.assign(this.highlight.style, {
+            position: "absolute",
+            border: `2px solid color-mix(in srgb, ${blue} 55%, transparent)`,
+            borderRadius: "4px",
+            backgroundColor: `color-mix(in srgb, ${blue} 6%, transparent)`,
+            pointerEvents: "none",
+            boxSizing: "border-box",
+            opacity: "0",
+            transition: "opacity 0.12s ease-out",
+            willChange: "opacity",
+        });
+        this.overlay.appendChild(this.highlight);
+        document.body.appendChild(this.overlay);
+        document.addEventListener("pointermove", this.onMove, true);
+        document.addEventListener("click", this.onClick, true);
+        document.addEventListener("keydown", this.onKey, true);
+    }
+    disable() {
+        if (!this.active && !this.overlay && !this.cursorStyle)
+            return;
+        this.active = false;
+        document.removeEventListener("pointermove", this.onMove, true);
+        document.removeEventListener("click", this.onClick, true);
+        document.removeEventListener("keydown", this.onKey, true);
+        this.overlay?.remove();
+        this.cursorStyle?.remove();
+        this.overlay = null;
+        this.highlight = null;
+        this.cursorStyle = null;
+        this.target = null;
+        this.mode = null;
+    }
+    freezeSelection() {
+        this.active = false;
+        document.removeEventListener("pointermove", this.onMove, true);
+        document.removeEventListener("click", this.onClick, true);
+        document.removeEventListener("keydown", this.onKey, true);
+        this.cursorStyle?.remove();
+        this.cursorStyle = null;
+    }
+    onMove = (e) => {
+        const hit = this.targetAt(e.clientX, e.clientY);
+        if (hit === this.target)
+            return;
+        this.target = hit;
+        if (!this.highlight)
+            return;
+        const rect = this.rectFor(hit);
+        Object.assign(this.highlight.style, {
+            left: `${rect.left}px`,
+            top: `${rect.top}px`,
+            width: `${rect.width}px`,
+            height: `${rect.height}px`,
+            opacity: "1",
+        });
+    };
+    onClick = (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        const clickedTarget = this.targetAt(e.clientX, e.clientY);
+        this.target = clickedTarget;
+        const targetId = clickedTarget?.getAttribute(TARGET_ATTR) ?? null;
+        if (this.mode === "element") {
+            const rect = this.rectFor(clickedTarget);
+            const text = clickedTarget.textContent?.replace(/\s+/g, " ").trim() || null;
+            this.disable();
+            postToFrame({
+                type: "element-target-picked",
+                selector: selectorFor(clickedTarget),
+                tagName: clickedTarget.tagName.toLowerCase(),
+                text: text?.slice(0, 160) ?? null,
+                anchor: {
+                    x: rect.left,
+                    y: rect.top,
+                    width: rect.width,
+                    height: rect.height,
+                },
+            });
+            return;
+        }
+        if (this.mode === "variantSet") {
+            if (!targetId)
+                return;
+            const rect = this.rectFor(clickedTarget);
+            this.disable();
+            postToFrame({
+                type: "variant-set-target-picked",
+                targetId,
+                anchor: {
+                    x: rect.left,
+                    y: rect.top,
+                    width: rect.width,
+                    height: rect.height,
+                },
+            });
+            return;
+        }
+        const rect = this.rectFor(clickedTarget);
+        if (this.highlight) {
+            Object.assign(this.highlight.style, {
+                left: `${rect.left}px`,
+                top: `${rect.top}px`,
+                width: `${rect.width}px`,
+                height: `${rect.height}px`,
+                opacity: "1",
+            });
+        }
+        this.freezeSelection();
+        postToFrame({
+            type: "comment-target-picked",
+            targetId,
+            anchor: {
+                x: rect.left,
+                y: rect.top,
+                width: rect.width,
+                height: rect.height,
+            },
+        });
+    };
+    targetAt(x, y) {
+        const hit = document.elementFromPoint(x, y);
+        if (this.mode === "element")
+            return hit ?? document.body;
+        return hit?.closest(`[${TARGET_ATTR}]`) ?? document.body;
+    }
+    rectFor(target) {
+        if (target === document.body || target === document.documentElement) {
+            return {
+                left: 0,
+                top: 0,
+                width: document.documentElement.clientWidth,
+                height: document.documentElement.clientHeight,
+            };
+        }
+        return target.getBoundingClientRect();
+    }
+    onKey = (e) => {
+        if (e.key !== "Escape")
+            return;
+        e.preventDefault();
+        const mode = this.mode;
+        this.disable();
+        postToFrame({
+            type: mode === "variantSet"
+                ? "variant-set-picker-exited"
+                : mode === "element"
+                    ? "element-picker-exited"
+                    : "comment-mode-exited",
+        });
+    };
+    async captureSelection(requestId) {
+        if (!this.target)
+            return;
+        const targetId = this.target.getAttribute(TARGET_ATTR);
+        const rect = this.rectFor(this.target);
+        const anchor = {
+            x: rect.left,
+            y: rect.top,
+            width: rect.width,
+            height: rect.height,
+        };
+        if (this.highlight) {
+            Object.assign(this.highlight.style, {
+                left: `${rect.left}px`,
+                top: `${rect.top}px`,
+                width: `${rect.width}px`,
+                height: `${rect.height}px`,
+            });
+        }
+        // The page is already interactive when the user picks a comment target.
+        // Capture immediately: thumbnail readiness delays can consume the Frame's
+        // request timeout on image-heavy prototypes.
+        const image = await captureViewport();
+        this.disable();
+        postToFrame({
+            type: "comment-capture",
+            targetId,
+            image,
+            requestId,
+            anchor,
+        });
+    }
+}
+const elementPicker = typeof window === "undefined" ? null : new ElementPicker();
+/**
+ * Wire a store to the bridge: listen for Frame messages, announce the rig,
+ * and report the boot-time state (the deep-link fix). Returns a disposer.
+ * Call client-side only.
+ */
+export function wireRig(store, manifest) {
+    let controlledTheme = false;
+    const media = window.matchMedia("(prefers-color-scheme: dark)");
+    const onSystemTheme = () => {
+        if (!controlledTheme)
+            applyPreviewTheme(resolvedSystemTheme());
+    };
+    media.addEventListener("change", onSystemTheme);
+    const onMessage = (e) => {
+        if (!isFrameToRig(e.data))
+            return; // tolerate unknown messages silently
+        if (e.data.type === "set-state") {
+            const state = manifest.states.find((s) => s.id === e.data.id);
+            store.setState(e.data.id, state?.variants ?? {});
+        }
+        else if (e.data.type === "set-theme") {
+            controlledTheme = true;
+            applyPreviewTheme(e.data.theme);
+        }
+        else if (e.data.type === "set-variant")
+            store.set(variantParam(e.data.component), e.data.variant);
+        else if (e.data.type === "measure-target") {
+            const target = Array.from(document.querySelectorAll(`[${TARGET_ATTR}]`)).find((candidate) => candidate.getAttribute(TARGET_ATTR) === e.data.id);
+            const rect = target?.getBoundingClientRect();
+            postToFrame({
+                type: "target-measured",
+                targetId: e.data.id,
+                anchor: rect
+                    ? {
+                        x: rect.left,
+                        y: rect.top,
+                        width: rect.width,
+                        height: rect.height,
+                    }
+                    : null,
+            });
+        }
+        else if (e.data.type === "set-comment-mode") {
+            if (e.data.on)
+                elementPicker?.enable("comment");
+            else
+                elementPicker?.disable();
+        }
+        else if (e.data.type === "capture-comment")
+            void elementPicker?.captureSelection(e.data.requestId);
+        else if (e.data.type === "set-variant-set-picker") {
+            if (e.data.on)
+                elementPicker?.enable("variantSet");
+            else
+                elementPicker?.disable();
+        }
+        else if (e.data.type === "set-element-picker") {
+            if (e.data.on)
+                elementPicker?.enable("element");
+            else
+                elementPicker?.disable();
+        }
+    };
+    window.addEventListener("message", onMessage);
+    postToFrame({
+        type: "hello",
+        protocolVersion: PROTOCOL_VERSION,
+        rigVersion: RIG_VERSION,
+        name: manifest.name,
+    });
+    postToFrame({ type: "state-changed", search: searchForFrame() });
+    const thumbnailRequestId = new URLSearchParams(window.location.search).get("_protoThumbnail");
+    if (thumbnailRequestId) {
+        void captureThumbnail().then((image) => {
+            postToFrame({
+                type: "thumbnail-capture",
+                image,
+                requestId: thumbnailRequestId,
+            });
+        });
+    }
+    return () => {
+        media.removeEventListener("change", onSystemTheme);
+        window.removeEventListener("message", onMessage);
+        elementPicker?.disable();
+    };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@proto-labs-inc/rig-core",
+  "version": "0.1.0",
+  "description": "Proto's rig, framework-free: URL-state sync, the postMessage bridge to the Frame, and comment mode.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proto-labs-inc/proto.git",
+    "directory": "packages/rig-core"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "modern-screenshot": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "modern-screenshot": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@proto-labs-inc/wire": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.2",
+    "modern-screenshot": "^4.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}