@proto-labs-inc/wire 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,6 @@
+# @proto-labs-inc/wire
+
+The typed contract between Proto's Frame and the rig inside a prototype: the
+bridge's message shapes, their guards, and the `prototype.json` schema.
+Prototypes get it through `@proto-labs-inc/rig` or `@proto-labs-inc/rig-vue`;
+import it directly only for its types (`Manifest`, `StateDef`).

package/dist/index.d.ts

@@ -0,0 +1,191 @@
+export declare const PROTOCOL_VERSION = 2;
+export type ResolvedPreviewTheme = "light" | "dark";
+export interface StateDef {
+    id: string;
+    title: string;
+    description?: string;
+    /** optional parent state id, used by the state map's layout/edges */
+    parent?: string;
+    /** variants that make this state a complete reproducible view */
+    variants?: Record<string, string>;
+}
+export interface PrPlanEntryDef {
+    title: string;
+    description?: string;
+    /** implementation pull request, present once this slice has been created */
+    pullRequestUrl?: string;
+    /** source branch in the implementation repository */
+    branchUrl?: string;
+    /** current pull request state, present once the implementation PR exists */
+    status?: "draft" | "in-review" | "merged" | "closed";
+    /** deployed preview for this implementation, when available */
+    previewUrl?: string;
+    /** state that demonstrates this implementation slice */
+    state: string;
+    /** schematic asset, relative to the prototype origin */
+    wireframe: string;
+    /** registered prototype region to focus after selecting this slice */
+    targetId: string;
+}
+export interface PrPlanDef {
+    entries: PrPlanEntryDef[];
+}
+export interface VariantLink {
+    title: string;
+    url: string;
+}
+export interface VariantDef {
+    id: string;
+    title: string;
+    note?: string;
+    /** workspace-relative implementation and style files for targeted edits */
+    sourceFiles?: string[];
+    /** optional static preview asset, relative to the prototype origin */
+    preview?: string;
+    /** canvas color shown around a contained static preview */
+    previewBackground?: string;
+    /** optional per-variant reference (e.g. a Loom or call recording) */
+    reference?: VariantLink;
+}
+export interface ReferenceDef {
+    app: string;
+    url: string;
+    note?: string;
+    /** screenshot path relative to the prototype origin (or absolute URL) */
+    image?: string;
+    /** variant id this reference inspired — linked from that variant's card */
+    variant?: string;
+}
+export interface VariantSetDef {
+    /** component id the variants belong to (matches the rig's registration) */
+    component: string;
+    title?: string;
+    /** temporary lifecycle state while an agent is creating the variant set */
+    status?: "building";
+    variants: VariantDef[];
+    /** variant id the prototype's code defaults to */
+    default: string;
+    /** preview-state id that showcases this variant set (used by previews) */
+    state?: string;
+    /** variant id that is the pre-variant-set original — pinned last, badged ORIGINAL */
+    baseline?: string;
+    /** overview copy shown at the bottom of the variants panel */
+    overview?: {
+        title?: string;
+        description?: string;
+    };
+    references?: ReferenceDef[];
+}
+export interface Manifest {
+    schemaVersion: 2;
+    /** the slug */
+    name: string;
+    port: number;
+    needsServer: boolean;
+    states: StateDef[];
+    variantSets: VariantSetDef[];
+    prPlan?: PrPlanDef;
+}
+export declare const STATE_PARAM = "state";
+export declare const variantParam: (component: string) => string;
+export type FrameToRig = {
+    type: "set-state";
+    id: string;
+} | {
+    type: "set-theme";
+    theme: ResolvedPreviewTheme;
+} | {
+    type: "set-variant";
+    component: string;
+    variant: string;
+} | {
+    type: "focus-target";
+    id: string | null;
+} | {
+    type: "measure-target";
+    id: string;
+} | {
+    type: "set-comment-mode";
+    on: boolean;
+} | {
+    type: "capture-comment";
+    requestId: string;
+} | {
+    type: "set-variant-set-picker";
+    on: boolean;
+} | {
+    type: "set-element-picker";
+    on: boolean;
+};
+export interface CommentAnchor {
+    /** Bounds of the selected component in the prototype viewport. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type RigToFrame = {
+    type: "hello";
+    protocolVersion: number;
+    rigVersion: string;
+    /** manifest.name, so the Frame can sanity-check what it framed */
+    name: string;
+} | {
+    type: "state-changed";
+    /** the prototype's current location.search, the full addressable state */
+    search: string;
+} | {
+    type: "comment-target-picked";
+    /** the clicked [data-proto-id], if the click landed on a marked component */
+    targetId: string | null;
+    /** Used by the Frame to place the composer beside the selection. */
+    anchor: CommentAnchor;
+} | {
+    type: "comment-capture";
+    /** the clicked [data-proto-id], if the click landed on a marked component */
+    targetId: string | null;
+    /** PNG data URL with the highlight composited in; null if capture failed
+        (e.g. modern-screenshot not installed) — the comment still works */
+    image: string | null;
+    /** The requestId of the capture-comment this answers. */
+    requestId: string;
+    /** Used by the Frame to place the composer beside the selection. */
+    anchor: CommentAnchor;
+} | {
+    type: "thumbnail-capture";
+    /** Image data URL of the current viewport, or null when capture failed. */
+    image: string | null;
+    /** The requestId of the capture-thumbnail request this answers. */
+    requestId: string;
+}
+/** the user pressed Escape inside the prototype */
+ | {
+    type: "comment-mode-exited";
+} | {
+    type: "target-focus-dismissed";
+} | {
+    type: "target-measured";
+    targetId: string;
+    /** Null when no matching registered component exists in the current state. */
+    anchor: CommentAnchor | null;
+} | {
+    type: "variant-set-target-picked";
+    targetId: string;
+    /** Used by the Frame to place the variant-set brief beside the selection. */
+    anchor: CommentAnchor;
+} | {
+    type: "variant-set-picker-exited";
+} | {
+    type: "element-target-picked";
+    /** A CSS selector scoped as narrowly as possible to a registered ancestor. */
+    selector: string;
+    tagName: string;
+    /** Short, whitespace-normalized text content to help identify the element. */
+    text: string | null;
+    /** Used by the Frame to place the prompt composer beside the selection. */
+    anchor: CommentAnchor;
+} | {
+    type: "element-picker-exited";
+};
+export declare function isFrameToRig(d: unknown): d is FrameToRig;
+export declare function isRigToFrame(d: unknown): d is RigToFrame;

package/dist/index.js

@@ -0,0 +1,38 @@
+export const PROTOCOL_VERSION = 2;
+// ─── URL param conventions ─────────────────────────────────────────
+export const STATE_PARAM = "state";
+export const variantParam = (component) => `v.${component}`;
+// ─── guards (tolerant: unknown message types are ignored, never errors) ──
+export function isFrameToRig(d) {
+    if (typeof d !== "object" || d === null)
+        return false;
+    const message = d;
+    const t = message.type;
+    return (t === "set-state" ||
+        (t === "set-theme" &&
+            (message.theme === "light" || message.theme === "dark")) ||
+        t === "set-variant" ||
+        t === "focus-target" ||
+        t === "measure-target" ||
+        t === "set-comment-mode" ||
+        t === "capture-comment" ||
+        t === "set-variant-set-picker" ||
+        t === "set-element-picker");
+}
+export function isRigToFrame(d) {
+    if (typeof d !== "object" || d === null)
+        return false;
+    const t = d.type;
+    return (t === "hello" ||
+        t === "state-changed" ||
+        t === "comment-target-picked" ||
+        t === "comment-capture" ||
+        t === "thumbnail-capture" ||
+        t === "comment-mode-exited" ||
+        t === "target-focus-dismissed" ||
+        t === "target-measured" ||
+        t === "variant-set-target-picked" ||
+        t === "variant-set-picker-exited" ||
+        t === "element-target-picked" ||
+        t === "element-picker-exited");
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@proto-labs-inc/wire",
+  "version": "0.1.0",
+  "description": "The typed contract between Proto's Frame and the rig inside a prototype: bridge messages and the prototype.json schema.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proto-labs-inc/proto.git",
+    "directory": "packages/wire"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "typescript": "~6.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}