@proto-labs-inc/wire 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const PROTOCOL_VERSION = 2;
+export declare const PROTOCOL_VERSION = 3;
 export type ResolvedPreviewTheme = "light" | "dark";
 export interface StateDef {
     id: string;
@@ -57,18 +57,28 @@ export interface ReferenceDef {
     variant?: string;
 }
 export interface VariantSetDef {
-    /** component id the variants belong to (matches the rig's registration) */
+    /** Stable identity for this creation. Older manifests use component as their identity. */
+    id?: string;
+    /** Unique set address used by the rig, independent of the display title and selected element. */
     component: string;
+    /** This set applies only while this variant in another set is active. */
+    requires?: {
+        component: string;
+        variant: 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 */
+    /** Variant id the prototype's code defaults to; empty for a references-only set. */
     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;
+    /** Marked page regions the set changes, independent of its rig address.
+     *  A decision across the top bar and a notice is one set. */
+    regions?: string[];
     /** overview copy shown at the bottom of the variants panel */
     overview?: {
         title?: string;
@@ -78,6 +88,8 @@ export interface VariantSetDef {
 }
 export interface Manifest {
     schemaVersion: 2;
+    /** Trusted Frame app origin, configured by the workspace owner. */
+    frameOrigin?: string;
     /** the slug */
     name: string;
     port: number;
@@ -85,9 +97,31 @@ export interface Manifest {
     states: StateDef[];
     variantSets: VariantSetDef[];
     prPlan?: PrPlanDef;
+    /** The width (and height) the page was copied at, when the copy only
+     *  lays out right there (a frozen page): the Frame draws it at this
+     *  width and scales it down when the area is narrower. */
+    viewport?: {
+        width: number;
+        height: number;
+        /** the narrowest width it still lays out at without spilling sideways:
+         *  the Frame re-flows it down to here and scales it only below */
+        minWidth?: number;
+    };
 }
 export declare const STATE_PARAM = "state";
 export declare const variantParam: (component: string) => string;
+/** Required ancestors, outermost first. Invalid references and cycles fail closed. */
+export declare function variantSetRequirements(sets: VariantSetDef[], component: string): Array<{
+    component: string;
+    variant: string;
+}> | null;
+export declare function isVariantSetApplicable(sets: VariantSetDef[], component: string, params: URLSearchParams): boolean;
+/** Apply a selection and its ancestors together, preserving dormant child choices. */
+export declare function applyVariantSelection(sets: VariantSetDef[], params: URLSearchParams, component: string, variant: string): boolean;
+/** CSS properties exposed by the annotation inspector. */
+export declare const ELEMENT_STYLE_PROPERTIES: readonly ["color", "background-color", "opacity", "font-family", "font-size", "font-weight", "line-height", "letter-spacing", "padding-top", "padding-right", "padding-bottom", "padding-left", "border-radius", "gap"];
+export type ElementStyleProperty = typeof ELEMENT_STYLE_PROPERTIES[number];
+export type ElementStyles = Partial<Record<ElementStyleProperty, string>>;
 export type FrameToRig = {
     type: "set-state";
     id: string;
@@ -100,10 +134,10 @@ export type FrameToRig = {
     variant: string;
 } | {
     type: "focus-target";
-    id: string | null;
+    selector: string | null;
 } | {
     type: "measure-target";
-    id: string;
+    selector: string;
 } | {
     type: "set-comment-mode";
     on: boolean;
@@ -116,6 +150,13 @@ export type FrameToRig = {
 } | {
     type: "set-element-picker";
     on: boolean;
+} | {
+    type: "preview-element-styles";
+    selectionId: string;
+    styles: ElementStyles;
+} | {
+    type: "release-element";
+    selectionId: string;
 };
 export interface CommentAnchor {
     /** Bounds of the selected component in the prototype viewport. */
@@ -125,6 +166,9 @@ export interface CommentAnchor {
     height: number;
 }
 export type RigToFrame = {
+    type: "frame-tools-status";
+    status: "loading" | "ready" | "unavailable";
+} | {
     type: "hello";
     protocolVersion: number;
     rigVersion: string;
@@ -136,14 +180,14 @@ export type RigToFrame = {
     search: string;
 } | {
     type: "comment-target-picked";
-    /** the clicked [data-proto-id], if the click landed on a marked component */
-    targetId: string | null;
+    /** CSS selector for the exact selected element. */
+    selector: string;
     /** 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;
+    /** CSS selector for the exact selected element. */
+    selector: string;
     /** 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;
@@ -165,18 +209,22 @@ export type RigToFrame = {
     type: "target-focus-dismissed";
 } | {
     type: "target-measured";
-    targetId: string;
-    /** Null when no matching registered component exists in the current state. */
+    selector: string;
+    /** Null when no matching element exists in the current state. */
     anchor: CommentAnchor | null;
 } | {
     type: "variant-set-target-picked";
-    targetId: string;
+    selector: 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";
+    inspection?: {
+        selectionId: string;
+        styles: ElementStyles;
+    };
     /** A CSS selector scoped as narrowly as possible to a registered ancestor. */
     selector: string;
     tagName: string;
@@ -186,6 +234,10 @@ export type RigToFrame = {
     anchor: CommentAnchor;
 } | {
     type: "element-picker-exited";
+} | {
+    type: "element-preview-bounds";
+    selectionId: string;
+    anchor: CommentAnchor | null;
 };
 export declare function isFrameToRig(d: unknown): d is FrameToRig;
 export declare function isRigToFrame(d: unknown): d is RigToFrame;

package/dist/index.js

@@ -1,19 +1,74 @@
-export const PROTOCOL_VERSION = 2;
+export const PROTOCOL_VERSION = 3;
 // ─── URL param conventions ─────────────────────────────────────────
 export const STATE_PARAM = "state";
 export const variantParam = (component) => `v.${component}`;
+/** Required ancestors, outermost first. Invalid references and cycles fail closed. */
+export function variantSetRequirements(sets, component) {
+    const visited = new Set();
+    const requirements = [];
+    let set = sets.find((candidate) => candidate.component === component);
+    if (!set)
+        return null;
+    while (set) {
+        if (visited.has(set.component))
+            return null;
+        visited.add(set.component);
+        const requirement = set.requires;
+        if (!requirement)
+            break;
+        const parent = sets.find((candidate) => candidate.component === requirement.component);
+        if (!parent?.variants.some((variant) => variant.id === requirement.variant))
+            return null;
+        requirements.unshift(requirement);
+        set = parent;
+    }
+    return requirements;
+}
+export function isVariantSetApplicable(sets, component, params) {
+    const requirements = variantSetRequirements(sets, component);
+    return requirements !== null && requirements.every((requirement) => {
+        const parent = sets.find((set) => set.component === requirement.component);
+        return (params.get(variantParam(parent.component)) ?? parent.default) === requirement.variant;
+    });
+}
+/** Apply a selection and its ancestors together, preserving dormant child choices. */
+export function applyVariantSelection(sets, params, component, variant) {
+    const requirements = variantSetRequirements(sets, component);
+    const set = sets.find((candidate) => candidate.component === component);
+    if (!requirements || !set?.variants.some((candidate) => candidate.id === variant))
+        return false;
+    for (const requirement of requirements) {
+        params.set(variantParam(requirement.component), requirement.variant);
+    }
+    params.set(variantParam(component), variant);
+    return true;
+}
+/** CSS properties exposed by the annotation inspector. */
+export const ELEMENT_STYLE_PROPERTIES = [
+    "color", "background-color", "opacity", "font-family", "font-size",
+    "font-weight", "line-height", "letter-spacing",
+    "padding-top", "padding-right", "padding-bottom", "padding-left",
+    "border-radius", "gap",
+];
 // ─── guards (tolerant: unknown message types are ignored, never errors) ──
 export function isFrameToRig(d) {
     if (typeof d !== "object" || d === null)
         return false;
     const message = d;
+    if (message.type === "release-element")
+        return typeof message.selectionId === "string";
+    if (message.type === "preview-element-styles") {
+        return typeof message.selectionId === "string" && typeof message.styles === "object" &&
+            message.styles !== null && !Array.isArray(message.styles) &&
+            Object.entries(message.styles).every(([property, value]) => ELEMENT_STYLE_PROPERTIES.includes(property) && typeof value === "string");
+    }
     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 === "focus-target" && (message.selector === null || typeof message.selector === "string")) ||
+        (t === "measure-target" && typeof message.selector === "string") ||
         t === "set-comment-mode" ||
         t === "capture-comment" ||
         t === "set-variant-set-picker" ||
@@ -22,17 +77,19 @@ export function isFrameToRig(d) {
 export function isRigToFrame(d) {
     if (typeof d !== "object" || d === null)
         return false;
-    const t = d.type;
-    return (t === "hello" ||
+    const message = d;
+    const t = message.type;
+    if (["comment-target-picked", "comment-capture", "variant-set-target-picked", "target-measured"].includes(t)) {
+        return typeof message.selector === "string";
+    }
+    return ((t === "frame-tools-status" && ["loading", "ready", "unavailable"].includes(message.status)) ||
+        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-preview-bounds" ||
         t === "element-target-picked" ||
         t === "element-picker-exited");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proto-labs-inc/wire",
-  "version": "0.1.0",
+  "version": "0.2.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": {