feat(studio): variables inspector panel with live preview values

Author: jrusso1020

packages/sdk/src/index.ts

@@ -27,6 +27,14 @@ export { ORIGIN_APPLY_PATCHES, ORIGIN_LOCAL } from "./types.js";
 export type {
   CompositionVariable,
   CompositionVariableType,
+  CompositionVariableBase,
+  StringVariable,
+  NumberVariable,
+  ColorVariable,
+  BooleanVariable,
+  EnumVariable,
+  FontVariable,
+  ImageVariable,
   VariableValidationIssue,
   VariableUsageScan,
 } from "@hyperframes/core/variables";

packages/studio/src/components/PanelTabButton.tsx

@@ -0,0 +1,31 @@
+import { Tooltip } from "./ui";
+
+/** Tab-bar button for the right inspector panel header. */
+export function PanelTabButton({
+  label,
+  tooltip,
+  active,
+  onClick,
+}: {
+  label: string;
+  tooltip: string;
+  active: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <Tooltip label={tooltip} side="bottom">
+      <button
+        type="button"
+        onClick={onClick}
+        aria-pressed={active}
+        className={`h-8 rounded-xl px-3 text-[11px] font-medium transition-colors active:scale-[0.98] ${
+          active
+            ? "bg-neutral-800 text-white"
+            : "text-neutral-500 hover:bg-neutral-800/70 hover:text-neutral-200"
+        }`}
+      >
+        {label}
+      </button>
+    </Tooltip>
+  );
+}

packages/studio/src/components/StudioRightPanel.tsx

@@ -7,14 +7,15 @@ import {
   type MutableRefObject,
   type PointerEvent as ReactPointerEvent,
 } from "react";
-import { Tooltip } from "./ui";
 import { PropertyPanel } from "./editor/PropertyPanel";
 import { LayersPanel } from "./editor/LayersPanel";
 import { CaptionPropertyPanel } from "../captions/components/CaptionPropertyPanel";
 import { BlockParamsPanel } from "./editor/BlockParamsPanel";
 import { RenderQueue } from "./renders/RenderQueue";
 import { SlideshowPanel } from "./panels/SlideshowPanel";
 import type { SceneInfo } from "./panels/SlideshowPanel";
+import { VariablesPanel } from "./panels/VariablesPanel";
+import { PanelTabButton } from "./PanelTabButton";
 import type { RenderJob } from "./renders/useRenderQueue";
 import type { BlockParam } from "@hyperframes/core/registry";
 import type { IframeWindow } from "../player/lib/playbackTypes";
@@ -461,64 +462,38 @@ export function StudioRightPanel({
             <div className="flex min-w-0 items-center gap-1 overflow-hidden border-b border-neutral-800 px-3 py-2">
               {STUDIO_INSPECTOR_PANELS_ENABLED && (
                 <>
-                  <Tooltip label="Element styles and properties" side="bottom">
-                    <button
-                      type="button"
-                      onClick={() => handleInspectorPaneButtonClick("design")}
-                      aria-pressed={designPaneOpen}
-                      className={`h-8 rounded-xl px-3 text-[11px] font-medium transition-colors active:scale-[0.98] ${
-                        designPaneOpen
-                          ? "bg-neutral-800 text-white"
-                          : "text-neutral-500 hover:bg-neutral-800/70 hover:text-neutral-200"
-                      }`}
-                    >
-                      Design
-                    </button>
-                  </Tooltip>
-                  <Tooltip label="Composition layer stack" side="bottom">
-                    <button
-                      type="button"
-                      onClick={() => handleInspectorPaneButtonClick("layers")}
-                      aria-pressed={layersPaneOpen}
-                      className={`h-8 rounded-xl px-3 text-[11px] font-medium transition-colors active:scale-[0.98] ${
-                        layersPaneOpen
-                          ? "bg-neutral-800 text-white"
-                          : "text-neutral-500 hover:bg-neutral-800/70 hover:text-neutral-200"
-                      }`}
-                    >
-                      Layers
-                    </button>
-                  </Tooltip>
+                  <PanelTabButton
+                    label="Design"
+                    tooltip="Element styles and properties"
+                    active={designPaneOpen}
+                    onClick={() => handleInspectorPaneButtonClick("design")}
+                  />
+                  <PanelTabButton
+                    label="Layers"
+                    tooltip="Composition layer stack"
+                    active={layersPaneOpen}
+                    onClick={() => handleInspectorPaneButtonClick("layers")}
+                  />
                 </>
               )}
-              <Tooltip label="Render queue and exports" side="bottom">
-                <button
-                  type="button"
-                  onClick={() => setRightPanelTab("renders")}
-                  aria-pressed={rightPanelTab === "renders"}
-                  className={`h-8 rounded-xl px-3 text-[11px] font-medium transition-colors active:scale-[0.98] ${
-                    rightPanelTab === "renders"
-                      ? "bg-neutral-800 text-white"
-                      : "text-neutral-500 hover:bg-neutral-800/70 hover:text-neutral-200"
-                  }`}
-                >
-                  {renderJobs.length > 0 ? `Renders (${renderJobs.length})` : "Renders"}
-                </button>
-              </Tooltip>
-              <Tooltip label="Slideshow branching editor" side="bottom">
-                <button
-                  type="button"
-                  onClick={() => setRightPanelTab("slideshow")}
-                  aria-pressed={rightPanelTab === "slideshow"}
-                  className={`h-8 rounded-xl px-3 text-[11px] font-medium transition-colors active:scale-[0.98] ${
-                    rightPanelTab === "slideshow"
-                      ? "bg-neutral-800 text-white"
-                      : "text-neutral-500 hover:bg-neutral-800/70 hover:text-neutral-200"
-                  }`}
-                >
-                  Slideshow
-                </button>
-              </Tooltip>
+              <PanelTabButton
+                label={renderJobs.length > 0 ? `Renders (${renderJobs.length})` : "Renders"}
+                tooltip="Render queue and exports"
+                active={rightPanelTab === "renders"}
+                onClick={() => setRightPanelTab("renders")}
+              />
+              <PanelTabButton
+                label="Slideshow"
+                tooltip="Slideshow branching editor"
+                active={rightPanelTab === "slideshow"}
+                onClick={() => setRightPanelTab("slideshow")}
+              />
+              <PanelTabButton
+                label="Variables"
+                tooltip="Template variables — declare, preview with values"
+                active={rightPanelTab === "variables"}
+                onClick={() => setRightPanelTab("variables")}
+              />
             </div>
             <div className="min-h-0 min-w-0 flex-1 overflow-hidden">
               {rightPanelTab === "block-params" && activeBlockParams ? (
@@ -535,6 +510,13 @@ export function StudioRightPanel({
                   onPersist={onPersistSlideshow}
                   onPersistNotes={onPersistSlideshowNotes}
                 />
+              ) : rightPanelTab === "variables" ? (
+                <VariablesPanel
+                  sdkSession={sdkSession}
+                  reloadPreview={reloadPreview}
+                  domEditSaveTimestampRef={domEditSaveTimestampRef}
+                  recordEdit={recordEdit}
+                />
               ) : layersPaneOpen && designPaneOpen ? (
                 <div ref={splitContainerRef} className="flex h-full min-h-0 min-w-0 flex-col">
                   <div

packages/studio/src/components/panels/VariablesDeclarationForm.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Pure form-logic guards for the Variables declaration form:
+ * mergeDeclarationEdit (unmodeled-key passthrough on same-type edits) and
+ * declarationFromDraft (per-type parsing + validation).
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  mergeDeclarationEdit,
+  declarationFromDraft,
+  draftFromDeclaration,
+  EMPTY_DRAFT,
+} from "./VariablesDeclarationForm.js";
+import type { CompositionVariable } from "@hyperframes/core/variables";
+
+describe("mergeDeclarationEdit", () => {
+  it("preserves unmodeled keys on a same-type edit", () => {
+    // The form owns id/label/type/default/description/min/max/step/options; every
+    // other key (source, brandRole, unit, maxLength, …) must ride through a Save.
+    const original = {
+      id: "brand",
+      type: "font",
+      label: "Brand font",
+      default: "Inter",
+      source: "brand-kit",
+      default_name: "Inter",
+      brandRole: "heading",
+    } as unknown as CompositionVariable;
+    const edited = {
+      id: "brand",
+      type: "font",
+      label: "Brand heading font",
+      default: "Inter",
+    } as CompositionVariable;
+
+    const merged = mergeDeclarationEdit(original, edited) as Record<string, unknown>;
+    expect(merged.label).toBe("Brand heading font");
+    expect(merged.source).toBe("brand-kit");
+    expect(merged.default_name).toBe("Inter");
+    expect(merged.brandRole).toBe("heading");
+  });
+
+  it("drops old type-specific metadata when the type changes", () => {
+    const original = {
+      id: "count",
+      type: "number",
+      label: "Count",
+      default: 3,
+      min: 0,
+      max: 10,
+    } as CompositionVariable;
+    const edited = {
+      id: "count",
+      type: "string",
+      label: "Count",
+      default: "3",
+    } as CompositionVariable;
+
+    const merged = mergeDeclarationEdit(original, edited) as Record<string, unknown>;
+    expect(merged).toEqual(edited);
+    expect(merged.min).toBeUndefined();
+    expect(merged.max).toBeUndefined();
+  });
+});
+
+describe("declarationFromDraft", () => {
+  it("requires a non-empty id", () => {
+    expect(declarationFromDraft({ ...EMPTY_DRAFT, id: "  " })).toBe("Variable id is required.");
+  });
+
+  it("parses a string variable verbatim and defaults label to id", () => {
+    const decl = declarationFromDraft({ ...EMPTY_DRAFT, id: "title", defaultRaw: "Hello" });
+    expect(decl).toEqual({ id: "title", label: "title", type: "string", default: "Hello" });
+  });
+
+  it("rejects a non-numeric number default", () => {
+    expect(
+      declarationFromDraft({ ...EMPTY_DRAFT, id: "n", type: "number", defaultRaw: "abc" }),
+    ).toBe("Default must be a number.");
+  });
+
+  it("parses a number variable with min/max/step and drops blank constraints", () => {
+    const decl = declarationFromDraft({
+      ...EMPTY_DRAFT,
+      id: "n",
+      type: "number",
+      defaultRaw: "5",
+      min: "0",
+      max: "",
+      step: "0.5",
+    });
+    expect(decl).toEqual({ id: "n", label: "n", type: "number", default: 5, min: 0, step: 0.5 });
+  });
+
+  it("rejects an enum with no options and an off-list default", () => {
+    expect(declarationFromDraft({ ...EMPTY_DRAFT, id: "e", type: "enum", optionsRaw: "" })).toBe(
+      "Enum needs at least one option (one per line, value:Label).",
+    );
+    expect(
+      declarationFromDraft({
+        ...EMPTY_DRAFT,
+        id: "e",
+        type: "enum",
+        optionsRaw: "wide:Wide\ntall:Tall",
+        defaultRaw: "square",
+      }),
+    ).toBe("Default must be one of the options.");
+  });
+
+  it("parses a boolean from the 'true' sentinel", () => {
+    expect(
+      declarationFromDraft({ ...EMPTY_DRAFT, id: "b", type: "boolean", defaultRaw: "true" }),
+    ).toMatchObject({
+      type: "boolean",
+      default: true,
+    });
+    expect(
+      declarationFromDraft({ ...EMPTY_DRAFT, id: "b", type: "boolean", defaultRaw: "" }),
+    ).toMatchObject({
+      default: false,
+    });
+  });
+
+  it("round-trips a declaration through draftFromDeclaration → declarationFromDraft", () => {
+    const original: CompositionVariable = {
+      id: "count",
+      type: "number",
+      label: "Count",
+      default: 3,
+      min: 0,
+      max: 10,
+    };
+    expect(declarationFromDraft(draftFromDeclaration(original))).toEqual(original);
+  });
+});