From 1be35ee625b9a51b35b0f2c2ee59a8eec8c2c13f Mon Sep 17 00:00:00 2001
From: Tarulata Priya <tarulatapriya@gmail.com>
Date: Sun, 18 Oct 2026 22:40:15 +0530
Subject: [PATCH] feat(editor): support text overlays URL query parameter and
 position presets (#1422)

---
 src/components/TextControls.tsx        | 475 +++++++++++++------------
 src/hooks/tests/useVideoEditor.test.ts |  31 ++
 src/hooks/useVideoEditor.ts            |  90 ++++-
 src/lib/editorPersistence.ts           |   2 +-
 4 files changed, 365 insertions(+), 233 deletions(-)

diff --git a/src/components/TextControls.tsx b/src/components/TextControls.tsx
index 48cbef3b6..9a3a96a40 100644
--- a/src/components/TextControls.tsx
+++ b/src/components/TextControls.tsx
@@ -1,223 +1,252 @@
-"use client";
-
-import { EditRecipe, TextOverlay } from "@/lib/types";
-import { createDefaultTextOverlay } from "@/lib/text-overlay";
-import { Trash2, Plus } from "lucide-react";
-import { useMemo } from "react";
-import FontSelector from "./FontSelector";
-import ColorPicker from "./ColorPicker"
-import { useFontManager } from "@/hooks/useFontManager";
-
-interface TextControlsProps {
-  recipe: EditRecipe;
-  onChange: (patch: Partial<EditRecipe>) => void;
-  selectedTextId: string | null;
-  onSelectText: (id: string | null) => void;
-}
-
-/**
- * Controls for managing text overlays on the video.
- * Allows users to add, remove, and select text overlays.
- */
-export default function TextControls({
-  recipe,
-  onChange,
-  selectedTextId,
-  onSelectText,
-}: TextControlsProps) {
-  const { customFonts, addFonts, removeFont, getErrors } = useFontManager();
-
-  /**
-   * Always ensures textOverlays is an array, even if recipe is malformed.
-   */
-  const textOverlays = useMemo(
-    (): TextOverlay[] => {
-      const overlays = recipe?.textOverlays;
-      return Array.isArray(overlays) ? overlays : [];
-    },
-    [recipe?.textOverlays]
-  );
-
-  /**
-   * Adds a new text overlay to the recipe.
-   */
-  const handleAddText = () => {
-    const newOverlay = createDefaultTextOverlay();
-    const updatedOverlays = [...textOverlays, newOverlay];
-    onChange({ textOverlays: updatedOverlays });
-    onSelectText(newOverlay.id);
-  };
-
-  /**
-   * Removes a text overlay from the recipe.
-   */
-  const handleRemoveText = (id: string) => {
-    const updatedOverlays = textOverlays.filter((overlay) => overlay.id !== id);
-    onChange({ textOverlays: updatedOverlays });
-    if (selectedTextId === id) {
-      onSelectText(null);
-    }
-  };
-
-  /**
-   * Updates a text overlay property.
-   */
-  const handleUpdateText = (id: string, updates: Partial<TextOverlay>) => {
-    const updatedOverlays = textOverlays.map((overlay) =>
-      overlay.id === id ? { ...overlay, ...updates } : overlay
-    );
-    onChange({ textOverlays: updatedOverlays });
-  };
-
-  /**
-   * Get the currently selected overlay.
-   */
-  const selectedOverlay = useMemo(
-    (): TextOverlay | undefined =>
-      textOverlays.find((o) => o.id === selectedTextId),
-    [textOverlays, selectedTextId]
-  );
-
-  return (
-    <div className="w-full space-y-3">
-      {/* Add Text Button */}
-      <button
-        type="button"
-        onClick={handleAddText}
-        className="w-full flex items-center justify-center gap-2 px-3 py-2 rounded-lg border border-[var(--border)] bg-[var(--surface)] text-[var(--text)] font-semibold text-sm hover:bg-[var(--border)] transition-colors"
-      >
-        <Plus size={14} />
-        Add Text
-      </button>
-
-      {/* Text Overlay List */}
-      {textOverlays.length > 0 && (
-        <div className="space-y-2 max-h-40 overflow-y-auto">
-          {textOverlays.map((overlay, idx) => (
-            <div
-              key={overlay.id}
-              className={`flex items-center justify-between gap-2 p-2 rounded border transition-colors ${
-                selectedTextId === overlay.id
-                  ? "border-film-500 bg-film-600/10"
-                  : "border-[var(--border)] bg-[var(--surface)] hover:bg-[var(--border)]"
-              }`}
-            >
-              <button
-                type="button"
-                onClick={() => onSelectText(overlay.id)}
-                className="flex-1 text-left text-xs truncate text-[var(--text)] font-medium"
-              >
-                {overlay.text || "(empty)"}
-              </button>
-              <button
-                type="button"
-                onClick={() => handleRemoveText(overlay.id)}
-                className="w-5 h-5 flex items-center justify-center rounded text-red-400 hover:bg-red-500/10 transition-colors"
-                aria-label={`Remove text overlay ${idx + 1}`}
-              >
-                <Trash2 size={13} />
-              </button>
-            </div>
-          ))}
-        </div>
-      )}
-
-      {/* Text Editing Controls */}
-      {selectedOverlay && (
-        <div className="space-y-3 pt-2 border-t border-[var(--border)]">
-          {/* Text Input */}
-          <div>
-            <label htmlFor="text-input" className="text-xs text-[var(--muted)] font-medium mb-1 block">
-              Text
-            </label>
-            <textarea
-              id="text-input"
-              value={selectedOverlay.text}
-              onChange={(e) => handleUpdateText(selectedTextId!, { text: e.target.value })}
-              placeholder="Enter text here"
-              className="w-full px-2 py-1.5 text-xs rounded border border-[var(--border)] bg-[var(--bg)] text-[var(--text)] placeholder-[var(--muted)] focus:outline-none focus:ring-2 focus:ring-film-500 resize-none"
-              rows={2}
-            />
-          </div>
-
-          {/* Font Selector */}
-          <FontSelector
-            selectedFont={selectedOverlay.fontFamily}
-            onSelectFont={(fontName) =>
-              handleUpdateText(selectedTextId!, { fontFamily: fontName })
-            }
-            customFonts={customFonts}
-            onAddFonts={addFonts}
-            onRemoveFont={removeFont}
-            errors={getErrors()}
-          />
-
-          {/* Font Size Slider */}
-          <div>
-            <div className="flex items-center justify-between mb-1">
-              <label htmlFor="font-size-slider" className="text-xs text-[var(--muted)] font-medium">
-                Font Size
-              </label>
-              <span className="text-xs text-[var(--text)] font-semibold">
-                {selectedOverlay.fontSize}px
-              </span>
-            </div>
-            <input
-              id="font-size-slider"
-              type="range"
-              min="12"
-              max="120"
-              step="2"
-              value={selectedOverlay.fontSize}
-              onChange={(e) =>
-                handleUpdateText(selectedTextId!, {
-                  fontSize: Number(e.target.value),
-                })
-              }
-              className="w-full accent-film-600"
-            />
-          </div>
-
-          {/* 🎨 Custom Glassmorphic Color Picker Implementation */}
-          <div>
-            <ColorPicker
-              label="Text Color"
-              value={selectedOverlay.color}
-              onChange={(hex) => handleUpdateText(selectedTextId!, { color: hex })}
-            />
-          </div>
-
-          {/* Font Weight */}
-          <div>
-            <legend className="text-xs text-[var(--muted)] font-medium mb-1 block">
-              Weight
-            </legend>
-            <div className="grid grid-cols-3 gap-1">
-              {(["normal", "bold", "900"] as const).map((weight) => (
-                <button
-                  key={weight}
-                  type="button"
-                  onClick={() =>
-                    handleUpdateText(selectedTextId!, { fontWeight: weight })
-                  }
-                  className={`px-2 py-1.5 text-xs rounded border transition-colors ${
-                    selectedOverlay.fontWeight === weight
-                      ? "border-film-500 bg-film-600/10 text-film-400"
-                      : "border-[var(--border)] bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--border)]"
-                  }`}
-                  style={{
-                    fontWeight: weight === "normal" ? 400 : weight === "bold" ? 700 : 900,
-                  }}
-                >
-                  {weight === "900" ? "Heavy" : weight.charAt(0).toUpperCase() + weight.slice(1)}
-                </button>
-              ))}
-            </div>
-          </div>
-        </div>
-      )}
-    </div>
-  );
-}
-
-// help
\ No newline at end of file
+"use client";
+
+import { EditRecipe, TextOverlay } from "@/lib/types";
+import { createDefaultTextOverlay } from "@/lib/text-overlay";
+import { Trash2, Plus } from "lucide-react";
+import { useMemo } from "react";
+import FontSelector from "./FontSelector";
+import ColorPicker from "./ColorPicker"
+import { useFontManager } from "@/hooks/useFontManager";
+
+interface TextControlsProps {
+  recipe: EditRecipe;
+  onChange: (patch: Partial<EditRecipe>) => void;
+  selectedTextId: string | null;
+  onSelectText: (id: string | null) => void;
+}
+
+/**
+ * Controls for managing text overlays on the video.
+ * Allows users to add, remove, and select text overlays.
+ */
+export default function TextControls({
+  recipe,
+  onChange,
+  selectedTextId,
+  onSelectText,
+}: TextControlsProps) {
+  const { customFonts, addFonts, removeFont, getErrors } = useFontManager();
+
+  /**
+   * Always ensures textOverlays is an array, even if recipe is malformed.
+   */
+  const textOverlays = useMemo(
+    (): TextOverlay[] => {
+      const overlays = recipe?.textOverlays;
+      return Array.isArray(overlays) ? overlays : [];
+    },
+    [recipe?.textOverlays]
+  );
+
+  /**
+   * Adds a new text overlay to the recipe.
+   */
+  const handleAddText = () => {
+    const newOverlay = createDefaultTextOverlay();
+    const updatedOverlays = [...textOverlays, newOverlay];
+    onChange({ textOverlays: updatedOverlays });
+    onSelectText(newOverlay.id);
+  };
+
+  /**
+   * Removes a text overlay from the recipe.
+   */
+  const handleRemoveText = (id: string) => {
+    const updatedOverlays = textOverlays.filter((overlay) => overlay.id !== id);
+    onChange({ textOverlays: updatedOverlays });
+    if (selectedTextId === id) {
+      onSelectText(null);
+    }
+  };
+
+  /**
+   * Updates a text overlay property.
+   */
+  const handleUpdateText = (id: string, updates: Partial<TextOverlay>) => {
+    const updatedOverlays = textOverlays.map((overlay) =>
+      overlay.id === id ? { ...overlay, ...updates } : overlay
+    );
+    onChange({ textOverlays: updatedOverlays });
+  };
+
+  /**
+   * Get the currently selected overlay.
+   */
+  const selectedOverlay = useMemo(
+    (): TextOverlay | undefined =>
+      textOverlays.find((o) => o.id === selectedTextId),
+    [textOverlays, selectedTextId]
+  );
+
+  return (
+    <div className="w-full space-y-3">
+      {/* Add Text Button */}
+      <button
+        type="button"
+        onClick={handleAddText}
+        className="w-full flex items-center justify-center gap-2 px-3 py-2 rounded-lg border border-[var(--border)] bg-[var(--surface)] text-[var(--text)] font-semibold text-sm hover:bg-[var(--border)] transition-colors"
+      >
+        <Plus size={14} />
+        Add Text
+      </button>
+
+      {/* Text Overlay List */}
+      {textOverlays.length > 0 && (
+        <div className="space-y-2 max-h-40 overflow-y-auto">
+          {textOverlays.map((overlay, idx) => (
+            <div
+              key={overlay.id}
+              className={`flex items-center justify-between gap-2 p-2 rounded border transition-colors ${
+                selectedTextId === overlay.id
+                  ? "border-film-500 bg-film-600/10"
+                  : "border-[var(--border)] bg-[var(--surface)] hover:bg-[var(--border)]"
+              }`}
+            >
+              <button
+                type="button"
+                onClick={() => onSelectText(overlay.id)}
+                className="flex-1 text-left text-xs truncate text-[var(--text)] font-medium"
+              >
+                {overlay.text || "(empty)"}
+              </button>
+              <button
+                type="button"
+                onClick={() => handleRemoveText(overlay.id)}
+                className="w-5 h-5 flex items-center justify-center rounded text-red-400 hover:bg-red-500/10 transition-colors"
+                aria-label={`Remove text overlay ${idx + 1}`}
+              >
+                <Trash2 size={13} />
+              </button>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {/* Text Editing Controls */}
+      {selectedOverlay && (
+        <div className="space-y-3 pt-2 border-t border-[var(--border)]">
+          {/* Text Input */}
+          <div>
+            <label htmlFor="text-input" className="text-xs text-[var(--muted)] font-medium mb-1 block">
+              Text
+            </label>
+            <textarea
+              id="text-input"
+              value={selectedOverlay.text}
+              onChange={(e) => handleUpdateText(selectedTextId!, { text: e.target.value })}
+              placeholder="Enter text here"
+              className="w-full px-2 py-1.5 text-xs rounded border border-[var(--border)] bg-[var(--bg)] text-[var(--text)] placeholder-[var(--muted)] focus:outline-none focus:ring-2 focus:ring-film-500 resize-none"
+              rows={2}
+            />
+          </div>
+
+          {/* Font Selector */}
+          <FontSelector
+            selectedFont={selectedOverlay.fontFamily}
+            onSelectFont={(fontName) =>
+              handleUpdateText(selectedTextId!, { fontFamily: fontName })
+            }
+            customFonts={customFonts}
+            onAddFonts={addFonts}
+            onRemoveFont={removeFont}
+            errors={getErrors()}
+          />
+
+          {/* Font Size Slider */}
+          <div>
+            <div className="flex items-center justify-between mb-1">
+              <label htmlFor="font-size-slider" className="text-xs text-[var(--muted)] font-medium">
+                Font Size
+              </label>
+              <span className="text-xs text-[var(--text)] font-semibold">
+                {selectedOverlay.fontSize}px
+              </span>
+            </div>
+            <input
+              id="font-size-slider"
+              type="range"
+              min="12"
+              max="120"
+              step="2"
+              value={selectedOverlay.fontSize}
+              onChange={(e) =>
+                handleUpdateText(selectedTextId!, {
+                  fontSize: Number(e.target.value),
+                })
+              }
+              className="w-full accent-film-600"
+            />
+          </div>
+
+          {/* 🎨 Custom Glassmorphic Color Picker Implementation */}
+          <div>
+            <ColorPicker
+              label="Text Color"
+              value={selectedOverlay.color}
+              onChange={(hex) => handleUpdateText(selectedTextId!, { color: hex })}
+            />
+          </div>
+
+          {/* Font Weight */}
+          <div>
+            <legend className="text-xs text-[var(--muted)] font-medium mb-1 block">
+              Weight
+            </legend>
+            <div className="grid grid-cols-3 gap-1">
+              {(["normal", "bold", "900"] as const).map((weight) => (
+                <button
+                  key={weight}
+                  type="button"
+                  onClick={() =>
+                    handleUpdateText(selectedTextId!, { fontWeight: weight })
+                  }
+                  className={`px-2 py-1.5 text-xs rounded border transition-colors ${
+                    selectedOverlay.fontWeight === weight
+                      ? "border-film-500 bg-film-600/10 text-film-400"
+                      : "border-[var(--border)] bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--border)]"
+                  }`}
+                  style={{
+                    fontWeight: weight === "normal" ? 400 : weight === "bold" ? 700 : 900,
+                  }}
+                >
+                  {weight === "900" ? "Heavy" : weight.charAt(0).toUpperCase() + weight.slice(1)}
+                </button>
+              ))}
+            </div>
+          </div>
+
+          {/* Position Presets */}
+          <div>
+            <span className="text-xs text-[var(--muted)] font-medium mb-1 block">
+              Position Presets
+            </span>
+            <div className="grid grid-cols-3 gap-1">
+              {[
+                { label: "Top Left", x: 10, y: 10 },
+                { label: "Top", x: 50, y: 10 },
+                { label: "Top Right", x: 90, y: 10 },
+                { label: "Left", x: 10, y: 50 },
+                { label: "Center", x: 50, y: 50 },
+                { label: "Right", x: 90, y: 50 },
+                { label: "Bottom Left", x: 10, y: 90 },
+                { label: "Bottom", x: 50, y: 90 },
+                { label: "Bottom Right", x: 90, y: 90 },
+              ].map((pos) => (
+                <button
+                  key={pos.label}
+                  type="button"
+                  onClick={() =>
+                    handleUpdateText(selectedTextId!, { x: pos.x, y: pos.y })
+                  }
+                  className="px-2 py-1 text-[11px] rounded border border-[var(--border)] bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--border)] hover:text-[var(--text)] transition-colors"
+                >
+                  {pos.label}
+                </button>
+              ))}
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/hooks/tests/useVideoEditor.test.ts b/src/hooks/tests/useVideoEditor.test.ts
index a99157ec0..2262d4256 100644
--- a/src/hooks/tests/useVideoEditor.test.ts
+++ b/src/hooks/tests/useVideoEditor.test.ts
@@ -39,6 +39,7 @@ describe("useVideoEditor core controller", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     localStorageMock.clear();
+    window.history.replaceState(null, "", "/");
   });
 
   it("should initialize with the default recipe", () => {
@@ -83,4 +84,34 @@ describe("useVideoEditor core controller", () => {
     });
     expect(result.current.recipe.speed).toBe(DEFAULT_RECIPE.speed);
   });
+
+  it("should parse textOverlays string from query param on initial load", () => {
+    window.history.replaceState(null, "", "/?textOverlays=hello");
+    const { result } = renderHook(() => useVideoEditor());
+    expect(result.current.recipe.textOverlays).toHaveLength(1);
+    expect(result.current.recipe.textOverlays[0]?.text).toBe("hello");
+  });
+
+  it("should parse textOverlays JSON array from query param on initial load", () => {
+    const overlays = [
+      {
+        id: "custom-1",
+        text: "Title overlay",
+        x: 50,
+        y: 20,
+        fontSize: 36,
+        color: "#ffffff",
+        fontWeight: "bold",
+      },
+    ];
+    window.history.replaceState(
+      null,
+      "",
+      `/?textOverlays=${encodeURIComponent(JSON.stringify(overlays))}`
+    );
+    const { result } = renderHook(() => useVideoEditor());
+    expect(result.current.recipe.textOverlays).toHaveLength(1);
+    expect(result.current.recipe.textOverlays[0]?.text).toBe("Title overlay");
+    expect(result.current.recipe.textOverlays[0]?.fontWeight).toBe("bold");
+  });
 });
diff --git a/src/hooks/useVideoEditor.ts b/src/hooks/useVideoEditor.ts
index 2833bd853..a0df2e115 100644
--- a/src/hooks/useVideoEditor.ts
+++ b/src/hooks/useVideoEditor.ts
@@ -10,6 +10,7 @@ import {
   TimelineTrack,
   MultiTrackEditorState,
   isValidRecipe,
+  TextOverlay,
 } from "@/lib/types";
 import { DEFAULT_RECIPE, SPEED_STEPS } from "@/lib/constants";
 import { getPresetById } from "@/lib/presets";
@@ -31,6 +32,7 @@ import {
   migrateRecipe as migratePersistedRecipe,
   persistRecipe,
   persistSoundPreference,
+  sanitizeTextOverlay,
   RECIPE_STORAGE_KEY,
   LEGACY_SETTINGS_KEY,
 } from "@/lib/editorPersistence";
@@ -258,6 +260,22 @@ export function useVideoEditor() {
         return typeof val === "number" && !isNaN(val) && val >= 0 && val <= 2;
       case "saturation":
         return typeof val === "number" && !isNaN(val) && val >= 0 && val <= 3;
+      case "textOverlays":
+        return (
+          Array.isArray(val) &&
+          val.every(
+            (o) =>
+              o &&
+              typeof o === "object" &&
+              typeof o.id === "string" &&
+              typeof o.text === "string" &&
+              typeof o.x === "number" &&
+              typeof o.y === "number" &&
+              typeof o.fontSize === "number" &&
+              typeof o.color === "string" &&
+              ["normal", "bold", "900"].includes(o.fontWeight)
+          )
+        );
       default:
         return true;
     }
@@ -329,7 +347,20 @@ export function useVideoEditor() {
             const defaultType = typeof DEFAULT_RECIPE[key];
             let parsedVal: any;
 
-            if (defaultType === "number") {
+            if (key === "textOverlays") {
+              try {
+                const parsed = JSON.parse(paramVal);
+                if (Array.isArray(parsed)) {
+                  parsedVal = parsed.map(sanitizeTextOverlay);
+                } else if (paramVal.trim()) {
+                  parsedVal = [sanitizeTextOverlay({ text: paramVal })];
+                }
+              } catch {
+                if (paramVal.trim()) {
+                  parsedVal = [sanitizeTextOverlay({ text: paramVal })];
+                }
+              }
+            } else if (defaultType === "number") {
               parsedVal = parseFloat(paramVal);
             } else if (defaultType === "boolean") {
               parsedVal = paramVal === "true";
@@ -350,15 +381,48 @@ export function useVideoEditor() {
           }));
         }
       } else {
-        setRecipe((current) =>
-          loadPersistedRecipe(
-            localStorage,
-            migratePersistedRecipe({
-              ...current,
-              soundOnCompletion: getStoredSoundPreference(localStorage),
-            })
-          )
+        const textOverlaysParam = params.get("textOverlays");
+        let initialRecipe = loadPersistedRecipe(
+          localStorage,
+          migratePersistedRecipe({
+            ...DEFAULT_RECIPE,
+            soundOnCompletion: getStoredSoundPreference(localStorage),
+          })
         );
+
+        if (textOverlaysParam) {
+          try {
+            const parsed = JSON.parse(textOverlaysParam);
+            if (Array.isArray(parsed)) {
+              initialRecipe = {
+                ...initialRecipe,
+                textOverlays: parsed.map(sanitizeTextOverlay),
+              };
+            } else if (typeof textOverlaysParam === "string" && textOverlaysParam.trim()) {
+              initialRecipe = {
+                ...initialRecipe,
+                textOverlays: [
+                  sanitizeTextOverlay({
+                    text: textOverlaysParam,
+                  }),
+                ],
+              };
+            }
+          } catch {
+            if (textOverlaysParam.trim()) {
+              initialRecipe = {
+                ...initialRecipe,
+                textOverlays: [
+                  sanitizeTextOverlay({
+                    text: textOverlaysParam,
+                  }),
+                ],
+              };
+            }
+          }
+        }
+
+        setRecipe(initialRecipe);
       }
     } catch (e) {
       // ignore
@@ -375,6 +439,14 @@ export function useVideoEditor() {
         const currentVal = recipe[key];
         const defaultVal = DEFAULT_RECIPE[key];
 
+        if (key === "textOverlays") {
+          const overlays = Array.isArray(currentVal) ? (currentVal as TextOverlay[]) : [];
+          if (overlays.length > 0) {
+            params.set(key, JSON.stringify(overlays));
+          }
+          return;
+        }
+
         if (currentVal !== defaultVal) {
           params.set(key, currentVal === null ? "null" : String(currentVal));
         }
diff --git a/src/lib/editorPersistence.ts b/src/lib/editorPersistence.ts
index 1abc8ba67..ec43d4d1e 100644
--- a/src/lib/editorPersistence.ts
+++ b/src/lib/editorPersistence.ts
@@ -19,7 +19,7 @@ function clamp(value: number, min: number, max: number): number {
 
 const VALID_FONT_WEIGHTS = ["normal", "bold", "900"];
 
-function sanitizeTextOverlay(overlay: any): TextOverlay {
+export function sanitizeTextOverlay(overlay: any): TextOverlay {
   return {
     id: typeof overlay.id === "string" ? overlay.id : generateTextOverlayId(),
     text: typeof overlay.text === "string" ? overlay.text.slice(0, 500) : "",