@hyperframes/studio 0.7.46 → 0.7.48

package/src/components/StudioRightPanel.tsx

@@ -7,7 +7,6 @@ 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";
@@ -15,6 +14,9 @@ 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 { usePreviewVariablesStore } from "../hooks/previewVariablesStore";
 import type { RenderJob } from "./renders/useRenderQueue";
 import type { BlockParam } from "@hyperframes/core/registry";
 import type { IframeWindow } from "../player/lib/playbackTypes";
@@ -22,6 +24,7 @@ import { STUDIO_INSPECTOR_PANELS_ENABLED } from "./editor/manualEditingAvailabil
 import type { Composition } from "@hyperframes/sdk";
 import type { EditHistoryKind } from "../utils/editHistory";
 import { useSlideshowPersist } from "../hooks/useSlideshowPersist";
+import { DesignPanelPromoteProvider } from "./DesignPanelPromoteProvider";
 
 import { useStudioPlaybackContext, useStudioShellContext } from "../contexts/StudioContext";
 import { usePanelLayoutContext } from "../contexts/PanelLayoutContext";
@@ -340,63 +343,74 @@ export function StudioRightPanel({
   );
 
   const propertyPanel = (
-    <PropertyPanel
+    <DesignPanelPromoteProvider
+      selection={domEditGroupSelections.length > 1 ? null : domEditSelection}
       projectId={projectId}
-      projectDir={projectDir}
-      assets={assets}
-      element={domEditGroupSelections.length > 1 ? null : domEditSelection}
-      multiSelectCount={domEditGroupSelections.length}
-      copiedAgentPrompt={copiedAgentPrompt}
-      onClearSelection={clearDomSelection}
-      onToggleElementHidden={onToggleElementHidden}
-      onUngroup={handleUngroupSelection}
-      onSetStyle={handleDomStyleCommit}
-      onSetAttribute={handleDomAttributeCommit}
-      onSetAttributeLive={handleDomAttributeLiveCommit}
-      onApplyColorGradingScope={handleApplyColorGradingScope}
-      onSetHtmlAttribute={handleDomHtmlAttributeCommit}
-      onRemoveBackground={handleRemoveBackground}
-      onSetManualOffset={handleDomPathOffsetCommit}
-      onSetManualSize={handleDomBoxSizeCommit}
-      onSetManualRotation={handleDomRotationCommit}
-      onSetText={handleDomTextCommit}
-      onSetTextFieldStyle={handleDomTextFieldStyleCommit}
-      onAddTextField={handleDomAddTextField}
-      onRemoveTextField={handleDomRemoveTextField}
-      onAskAgent={handleAskAgent}
-      onImportAssets={handleImportFiles}
-      fontAssets={fontAssets}
-      onImportFonts={handleImportFonts}
-      previewIframeRef={previewIframeRef}
-      gsapAnimations={selectedGsapAnimations}
-      gsapMultipleTimelines={gsapMultipleTimelines}
-      gsapUnsupportedTimelinePattern={gsapUnsupportedTimelinePattern}
-      onUpdateGsapProperty={handleGsapUpdateProperty}
-      onUpdateGsapMeta={handleGsapUpdateMeta}
-      onDeleteGsapAnimation={handleGsapDeleteAnimation}
-      onAddGsapProperty={handleGsapAddProperty}
-      onRemoveGsapProperty={handleGsapRemoveProperty}
-      onUpdateGsapFromProperty={handleGsapUpdateFromProperty}
-      onAddGsapFromProperty={handleGsapAddFromProperty}
-      onRemoveGsapFromProperty={handleGsapRemoveFromProperty}
-      onAddGsapAnimation={handleGsapAddAnimation}
-      onCommitAnimatedProperty={commitAnimatedProperty}
-      onCommitAnimatedProperties={commitAnimatedProperties}
-      onAddKeyframe={handleGsapAddKeyframe}
-      onRemoveKeyframe={handleGsapRemoveKeyframe}
-      onConvertToKeyframes={(animId, duration) =>
-        handleGsapConvertToKeyframes(animId, undefined, duration)
-      }
-      onSeekToTime={(t) => usePlayerStore.getState().requestSeek(t)}
-      onSetArcPath={handleSetArcPath}
-      onUpdateArcSegment={handleUpdateArcSegment}
-      onUnroll={handleUnroll}
-      onUpdateKeyframeEase={handleUpdateKeyframeEase}
-      onSetAllKeyframeEases={handleSetAllKeyframeEases}
-      recordingState={recordingState}
-      recordingDuration={recordingDuration}
-      onToggleRecording={onToggleRecording}
-    />
+      activeCompPath={activeCompPath}
+      readProjectFile={readProjectFile}
+      writeProjectFile={writeProjectFile}
+      recordEdit={recordEdit}
+      reloadPreview={reloadPreview}
+      domEditSaveTimestampRef={domEditSaveTimestampRef}
+    >
+      <PropertyPanel
+        projectId={projectId}
+        projectDir={projectDir}
+        assets={assets}
+        element={domEditGroupSelections.length > 1 ? null : domEditSelection}
+        multiSelectCount={domEditGroupSelections.length}
+        copiedAgentPrompt={copiedAgentPrompt}
+        onClearSelection={clearDomSelection}
+        onToggleElementHidden={onToggleElementHidden}
+        onUngroup={handleUngroupSelection}
+        onSetStyle={handleDomStyleCommit}
+        onSetAttribute={handleDomAttributeCommit}
+        onSetAttributeLive={handleDomAttributeLiveCommit}
+        onApplyColorGradingScope={handleApplyColorGradingScope}
+        onSetHtmlAttribute={handleDomHtmlAttributeCommit}
+        onRemoveBackground={handleRemoveBackground}
+        onSetManualOffset={handleDomPathOffsetCommit}
+        onSetManualSize={handleDomBoxSizeCommit}
+        onSetManualRotation={handleDomRotationCommit}
+        onSetText={handleDomTextCommit}
+        onSetTextFieldStyle={handleDomTextFieldStyleCommit}
+        onAddTextField={handleDomAddTextField}
+        onRemoveTextField={handleDomRemoveTextField}
+        onAskAgent={handleAskAgent}
+        onImportAssets={handleImportFiles}
+        fontAssets={fontAssets}
+        onImportFonts={handleImportFonts}
+        previewIframeRef={previewIframeRef}
+        gsapAnimations={selectedGsapAnimations}
+        gsapMultipleTimelines={gsapMultipleTimelines}
+        gsapUnsupportedTimelinePattern={gsapUnsupportedTimelinePattern}
+        onUpdateGsapProperty={handleGsapUpdateProperty}
+        onUpdateGsapMeta={handleGsapUpdateMeta}
+        onDeleteGsapAnimation={handleGsapDeleteAnimation}
+        onAddGsapProperty={handleGsapAddProperty}
+        onRemoveGsapProperty={handleGsapRemoveProperty}
+        onUpdateGsapFromProperty={handleGsapUpdateFromProperty}
+        onAddGsapFromProperty={handleGsapAddFromProperty}
+        onRemoveGsapFromProperty={handleGsapRemoveFromProperty}
+        onAddGsapAnimation={handleGsapAddAnimation}
+        onCommitAnimatedProperty={commitAnimatedProperty}
+        onCommitAnimatedProperties={commitAnimatedProperties}
+        onAddKeyframe={handleGsapAddKeyframe}
+        onRemoveKeyframe={handleGsapRemoveKeyframe}
+        onConvertToKeyframes={(animId, duration) =>
+          handleGsapConvertToKeyframes(animId, undefined, duration)
+        }
+        onSeekToTime={(t) => usePlayerStore.getState().requestSeek(t)}
+        onSetArcPath={handleSetArcPath}
+        onUpdateArcSegment={handleUpdateArcSegment}
+        onUnroll={handleUnroll}
+        onUpdateKeyframeEase={handleUpdateKeyframeEase}
+        onSetAllKeyframeEases={handleSetAllKeyframeEases}
+        recordingState={recordingState}
+        recordingDuration={recordingDuration}
+        onToggleRecording={onToggleRecording}
+      />
+    </DesignPanelPromoteProvider>
   );
 
   const renderQueuePanel = (
@@ -420,6 +434,9 @@ export function StudioRightPanel({
           format,
           resolution,
           composition,
+          // Render what the user is previewing: active variable overrides
+          // from the Variables panel ride along (undefined = defaults).
+          variables: usePreviewVariablesStore.getState().values ?? undefined,
         });
       }}
       compositionDimensions={compositionDimensions}
@@ -461,64 +478,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 +526,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

package/src/components/editor/LayersPanel.tsx

@@ -14,6 +14,7 @@ import {
 } from "../../utils/studioHelpers";
 import { Layers } from "../../icons/SystemIcons";
 import { useLayerDrag, isLayerDraggable, type LayerReorderEvent } from "./useLayerDrag";
+import { computeReorderZValues, getElementZIndex } from "../../player/lib/layerOrdering";
 
 const TAG_ICONS: Record<string, string> = {
   video: "Vi",
@@ -228,9 +229,7 @@ export const LayersPanel = memo(function LayersPanel() {
       reordered.splice(toIndex, 0, moved);
 
       const existingValues = siblingLayers.map((l) => getElementZIndex(l.element));
-      const sorted = [...existingValues].sort((a, b) => b - a);
-      const hasDupes = sorted.some((v, i) => i > 0 && v === sorted[i - 1]);
-      const zValues = hasDupes ? reordered.map((_, i) => reordered.length - i) : sorted;
+      const zValues = computeReorderZValues(existingValues, fromIndex, toIndex);
 
       const entries = reordered.map((layer, i) => ({
         element: layer.element,
@@ -388,25 +387,6 @@ export const LayersPanel = memo(function LayersPanel() {
 
 // ── Pure helpers ──────────────────────────────────────────────────────
 
-// fallow-ignore-next-line complexity
-function getElementZIndex(element: HTMLElement): number {
-  try {
-    const inline = element.style?.zIndex;
-    if (inline && inline !== "auto") {
-      const parsed = parseInt(inline, 10);
-      if (Number.isFinite(parsed)) return parsed;
-    }
-    const win = element.ownerDocument?.defaultView;
-    if (!win) return 0;
-    const value = win.getComputedStyle(element).zIndex;
-    if (value === "auto" || value === "") return 0;
-    const parsed = parseInt(value, 10);
-    return Number.isFinite(parsed) ? parsed : 0;
-  } catch {
-    return 0;
-  }
-}
-
 // fallow-ignore-next-line complexity
 export function sortLayersByZIndex(layers: DomEditLayerItem[]): DomEditLayerItem[] {
   if (layers.length <= 1) return layers;

package/src/components/editor/PromotableControl.tsx

@@ -0,0 +1,105 @@
+/**
+ * Wraps a Design-panel property control with the promote-to-variable gesture.
+ * When a control can be promoted it shows a visible "◇ var" button; clicking it
+ * declares a variable (default = current value, so the render is unchanged) and
+ * binds this property to it. Once bound, the button is replaced by a "◆ {id}"
+ * chip and edits route to the variable's default (edit-in-place). Controls that
+ * aren't eligible (or render outside a promote context, or are disabled by the
+ * caller) pass through untouched. Uses a render-prop so each control keeps its
+ * own value/onCommit shape.
+ */
+
+import { useEffect } from "react";
+import {
+  useVariablePromoteChannel,
+  type PromoteChannel,
+} from "../../contexts/VariablePromoteContext";
+
+interface RenderArgs {
+  /** When bound, the variable's default to display; otherwise undefined. */
+  value?: string;
+  /** When bound, routes commits to the variable default; otherwise undefined. */
+  onCommit?: (value: string) => void;
+  bound: boolean;
+}
+
+export function PromotableControl({
+  channel,
+  enabled = true,
+  children,
+}: {
+  channel: PromoteChannel;
+  /**
+   * Caller-side gate. Text-section controls only promote when the edited field
+   * is the selected element's OWN text (source "self"); binding a child/text-
+   * node field would target a different element than the control edits.
+   */
+  enabled?: boolean;
+  children: (args: RenderArgs) => React.ReactNode;
+}) {
+  const promote = useVariablePromoteChannel(channel);
+
+  // A binding attribute (`data-var-*` / `var(--id)`) pointing at a declaration
+  // that no longer exists renders as a plain unbound control — a silent
+  // fallback that leaves a dev wondering why "their binding isn't showing".
+  // Surface it in the console so the dangling reference is discoverable.
+  const danglingId =
+    enabled && promote && promote.boundId != null && promote.declaration == null
+      ? promote.boundId
+      : null;
+  useEffect(() => {
+    if (danglingId != null) {
+      console.warn(
+        `[hyperframes] Control is bound to variable "${danglingId}", but no such declaration exists. The element still carries the binding on disk — re-declare the variable or unbind the element.`,
+      );
+    }
+  }, [danglingId]);
+
+  if (!promote || !enabled) return <>{children({ bound: false })}</>;
+
+  // A binding whose declaration was removed elsewhere is dangling: don't show
+  // it as an editable bound control (setDefault would silently no-op) — let it
+  // fall back to a plain, re-promotable control.
+  const bound = promote.boundId != null && promote.declaration != null;
+  const canPromote = promote.action != null && !bound;
+  const defaultValue = promote.declaration?.default;
+
+  const rendered = children(
+    bound
+      ? {
+          // Only string defaults render inline; a FontValue/ImageValue object
+          // falls back to the element's real value instead of "[object Object]".
+          value: typeof defaultValue === "string" ? defaultValue : undefined,
+          onCommit: promote.setDefault,
+          bound: true,
+        }
+      : { bound: false },
+  );
+
+  return (
+    <div className={`relative ${bound ? "rounded-lg ring-1 ring-studio-accent/40" : ""}`}>
+      {rendered}
+      {bound && (
+        <span
+          className="pointer-events-none absolute right-1.5 top-0 z-10 inline-flex max-w-[60%] items-center gap-1 truncate rounded bg-studio-accent/20 px-1 py-px font-mono text-[8px] font-medium text-studio-accent"
+          title={`Bound to variable "${promote.boundId}"`}
+        >
+          ◆ {promote.boundId}
+        </span>
+      )}
+      {canPromote && (
+        <button
+          type="button"
+          title="Make this a variable"
+          onClick={(e) => {
+            e.stopPropagation();
+            promote.promote();
+          }}
+          className="absolute right-1.5 top-0 z-10 inline-flex items-center gap-1 rounded bg-neutral-800/80 px-1 py-px font-mono text-[8px] font-medium text-neutral-400 opacity-70 transition-colors hover:bg-studio-accent/20 hover:text-studio-accent hover:opacity-100"
+        >
+          ◇ var
+        </button>
+      )}
+    </div>
+  );
+}

package/src/components/editor/propertyPanelSections.tsx

@@ -6,6 +6,7 @@ import { FIELD, LABEL, normalizeTextMetricValue, RESPONSIVE_GRID } from "./prope
 import { MetricField, Section, SelectField } from "./propertyPanelPrimitives";
 import { ColorField } from "./propertyPanelColor";
 import { FontFamilyField } from "./propertyPanelFont";
+import { PromotableControl } from "./PromotableControl";
 
 /* ------------------------------------------------------------------ */
 /*  Text helpers (used only by text section components)                */
@@ -280,20 +281,31 @@ function TextFieldEditor({
           </button>
         )}
       </div>
-      <TextAreaField
-        key={field.key}
-        label="Content"
-        value={field.value}
-        disabled={false}
-        autoFocus={showRemove}
-        onCommit={(next) => onSetText(next, field.key)}
-      />
-      <ColorField
-        label="Text color"
-        value={getTextFieldColor(field, styles)}
-        disabled={false}
-        onCommit={(next) => onSetTextFieldStyle(field.key, "color", next)}
-      />
+      <PromotableControl channel={{ kind: "text" }} enabled={field.source === "self"}>
+        {({ value, onCommit }) => (
+          <TextAreaField
+            key={field.key}
+            label="Content"
+            value={value ?? field.value}
+            disabled={false}
+            autoFocus={showRemove}
+            onCommit={onCommit ?? ((next) => onSetText(next, field.key))}
+          />
+        )}
+      </PromotableControl>
+      <PromotableControl
+        channel={{ kind: "style", prop: "color" }}
+        enabled={field.source === "self"}
+      >
+        {({ value, onCommit }) => (
+          <ColorField
+            label="Text color"
+            value={value ?? getTextFieldColor(field, styles)}
+            disabled={false}
+            onCommit={onCommit ?? ((next) => onSetTextFieldStyle(field.key, "color", next))}
+          />
+        )}
+      </PromotableControl>
       <div className={RESPONSIVE_GRID}>
         <MetricField
           label="Size"
@@ -309,13 +321,22 @@ function TextFieldEditor({
           onCommit={(next) => onSetTextFieldStyle(field.key, "font-weight", next)}
         />
       </div>
-      <FontFamilyField
-        value={field.computedStyles["font-family"] || styles["font-family"] || "inherit"}
-        disabled={false}
-        importedFonts={fontAssets}
-        onImportFonts={onImportFonts}
-        onCommit={(next) => onSetTextFieldStyle(field.key, "font-family", next)}
-      />
+      <PromotableControl
+        channel={{ kind: "style", prop: "font-family" }}
+        enabled={field.source === "self"}
+      >
+        {({ value, onCommit }) => (
+          <FontFamilyField
+            value={
+              value ?? (field.computedStyles["font-family"] || styles["font-family"] || "inherit")
+            }
+            disabled={false}
+            importedFonts={fontAssets}
+            onImportFonts={onImportFonts}
+            onCommit={onCommit ?? ((next) => onSetTextFieldStyle(field.key, "font-family", next))}
+          />
+        )}
+      </PromotableControl>
       <AdvancedTextControls
         field={field}
         inheritedStyles={styles}