From 4e62adaa0ed6c57b9c6ea38c2df029e4eb41a20c Mon Sep 17 00:00:00 2001
From: jcode runner <runner@jcode.local>
Date: Fri, 31 Jul 2026 22:59:42 +0000
Subject: [PATCH] [jcode] Add H3 camera movement preset chips

---
 README.md                                     |  31 ++++
 .../client/src/features/Composer.test.tsx     | 100 +++++++++++-
 packages/client/src/features/Composer.tsx     | 152 +++++++++++++++---
 packages/client/src/styles.css                |  31 ++++
 .../server/src/__tests__/services.test.ts     |  68 ++++++++
 packages/server/src/__tests__/util.test.ts    |   6 +
 .../server/src/services/generationService.ts  |  35 +++-
 packages/server/src/util.ts                   |   3 +
 .../src/__tests__/cameraPresets.test.ts       | 117 ++++++++++++++
 packages/shared/src/__tests__/schemas.test.ts |  13 ++
 packages/shared/src/cameraPresets.ts          | 141 ++++++++++++++++
 packages/shared/src/index.ts                  |   1 +
 packages/shared/src/schemas.ts                |   8 +
 13 files changed, 682 insertions(+), 24 deletions(-)
 create mode 100644 packages/shared/src/__tests__/cameraPresets.test.ts
 create mode 100644 packages/shared/src/cameraPresets.ts

diff --git a/README.md b/README.md
index 7c224f5..da84632 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,10 @@ configured.
 
 - **Versioned prompt library** — immutable versions, restore-as-new-head,
   duplicate, archive (never delete), full-text + tag/status filters.
+- **H3 camera-motion chips** — one-click camera cues (Pan left/right, Push in,
+  Pull out, Tracking shot, Static shot) insert at the prompt cursor in the
+  generation composer, preserving surrounding text; the cue-augmented prompt is
+  still validated through the H3 policy before submission.
 - **Pure template engine** — `{{variable}}` parsing/rendering with name
   validation (letters, numbers, `_`, `.`, `-`), duplicate normalization, and
   rejection of blank/unresolved variables.
@@ -117,6 +121,33 @@ curl -X PUT localhost:3001/api/debug/mock -H 'Content-Type: application/json' \
 
 ---
 
+## Camera-movement preset chips (composer)
+
+MiniMax's H3 guide recommends camera-motion cues (pan, push/pull, tracking,
+static). The generation composer offers them as keyboard-reachable chips so you
+don't have to remember or retype the phrasing:
+
+- Open a prompt version → **Generate from head** to reach the composer.
+- The **Prompt** card lists the chips: **Pan left, Pan right, Push in, Pull out,
+  Tracking shot, Static shot**. Each is a real button (`Tab` to reach, `Enter`/
+  `Space` to activate) with a visible focus ring and a tooltip describing the
+  motion.
+- Activating a chip inserts its token at the current cursor (or replaces the
+  current selection) without disturbing the surrounding text; before you place
+  the cursor it appends at the end. You can then edit the prompt freely.
+- While the prompt is untouched it mirrors the rendered template (filling a
+  variable live-updates it). The first chip insert or manual edit freezes it as
+  the source of truth; **Reset to rendered** re-syncs it from the variables.
+- The exact text shown is what is generated, sent as a `prompt` override and
+  still validated through the existing H3 request policy (the 7000-character
+  limit, duration, ratio, and media rules) before submission.
+
+The preset labels and inserted tokens live in one pure, tested module
+(`packages/shared/src/cameraPresets.ts`) so they are not duplicated across the
+UI.
+
+---
+
 ## Using the real MiniMax H3 API
 
 Real mode is selected by configuration and **fails visibly** when the key is
diff --git a/packages/client/src/features/Composer.test.tsx b/packages/client/src/features/Composer.test.tsx
index 1e1bb6a..10d455b 100644
--- a/packages/client/src/features/Composer.test.tsx
+++ b/packages/client/src/features/Composer.test.tsx
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi, beforeEach } from 'vitest';
-import { render, screen, waitFor } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { NavProvider } from '../nav.js';
 import { Composer } from './Composer.js';
@@ -128,3 +128,101 @@ describe('Composer', () => {
     );
   });
 });
+
+describe('Composer camera-movement preset chips', () => {
+  it('renders the six presets as keyboard-reachable buttons with names', async () => {
+    renderComposer();
+    await waitFor(() => expect(screen.getByLabelText('subject')).toBeInTheDocument());
+
+    const group = screen.getByRole('group', { name: /camera movement presets/i });
+    const chips = within(group).getAllByRole('button');
+    expect(chips).toHaveLength(6);
+    // Each chip is a real <button> (keyboard reachable) with a meaningful name.
+    expect(chips.map((c) => c.textContent)).toEqual([
+      'Pan left',
+      'Pan right',
+      'Push in',
+      'Pull out',
+      'Tracking shot',
+      'Static shot',
+    ]);
+    for (const chip of chips) {
+      expect(chip.tagName).toBe('BUTTON');
+      expect(chip).toHaveAttribute('type', 'button');
+    }
+  });
+
+  it('appends a camera cue at the end when the cursor has not been placed', async () => {
+    const user = userEvent.setup();
+    renderComposer();
+    await user.type(await screen.findByLabelText('subject'), 'a car');
+    await user.click(screen.getByRole('button', { name: 'Pan left' }));
+
+    const prompt = screen.getByLabelText('Rendered prompt') as HTMLTextAreaElement;
+    expect(prompt.value).toBe('A film of a car pan left');
+  });
+
+  it('inserts a camera cue at the cursor in the middle of the prompt', async () => {
+    renderComposer();
+    await userEvent.type(await screen.findByLabelText('subject'), 'a car');
+
+    const prompt = screen.getByLabelText('Rendered prompt') as HTMLTextAreaElement;
+    prompt.focus();
+    prompt.setSelectionRange(6, 6); // caret after "A film"
+    fireEvent.click(screen.getByRole('button', { name: 'Tracking shot' }));
+
+    expect(prompt.value).toBe('A film tracking shot of a car');
+  });
+
+  it('replaces the current selection with the camera cue', async () => {
+    renderComposer();
+    await userEvent.type(await screen.findByLabelText('subject'), 'a car');
+
+    const prompt = screen.getByLabelText('Rendered prompt') as HTMLTextAreaElement;
+    prompt.focus();
+    prompt.setSelectionRange(0, 6); // select "A film"
+    fireEvent.click(screen.getByRole('button', { name: 'Static shot' }));
+
+    expect(prompt.value).toBe('static shot of a car');
+  });
+
+  it('preserves surrounding text across multiple consecutive cues', async () => {
+    renderComposer();
+    await userEvent.type(await screen.findByLabelText('subject'), 'a car');
+
+    const prompt = screen.getByLabelText('Rendered prompt') as HTMLTextAreaElement;
+    prompt.focus();
+    prompt.setSelectionRange(6, 6); // after "A film"
+    fireEvent.click(screen.getByRole('button', { name: 'Pan left' }));
+    // After an insert the caret sits right after the inserted token, so a second
+    // cue is added directly after it without clobbering the rest of the prompt.
+    fireEvent.click(screen.getByRole('button', { name: 'Push in' }));
+
+    expect(prompt.value).toBe('A film pan left push in of a car');
+  });
+
+  it('sends the cue-augmented prompt as the generated prompt', async () => {
+    const user = userEvent.setup();
+    createGeneration.mockResolvedValue({ job: { id: 'job-1' }, reused: false });
+    renderComposer();
+    await user.type(await screen.findByLabelText('subject'), 'a car');
+    await user.click(screen.getByRole('button', { name: 'Push in' }));
+    await user.click(screen.getByRole('button', { name: /Generate video/i }));
+
+    await waitFor(() => expect(createGeneration).toHaveBeenCalledTimes(1));
+    const payload = createGeneration.mock.calls[0]![0] as { prompt: string };
+    expect(payload.prompt).toBe('A film of a car push in');
+  });
+
+  it('reset restores the freshly rendered prompt', async () => {
+    renderComposer();
+    await userEvent.type(await screen.findByLabelText('subject'), 'a car');
+
+    fireEvent.click(screen.getByRole('button', { name: 'Pan left' }));
+    const prompt = screen.getByLabelText('Rendered prompt') as HTMLTextAreaElement;
+    expect(prompt.value).toBe('A film of a car pan left');
+
+    fireEvent.click(screen.getByRole('button', { name: /reset to rendered/i }));
+    expect(prompt.value).toBe('A film of a car');
+  });
+});
diff --git a/packages/client/src/features/Composer.tsx b/packages/client/src/features/Composer.tsx
index 7cf4040..de8fce2 100644
--- a/packages/client/src/features/Composer.tsx
+++ b/packages/client/src/features/Composer.tsx
@@ -1,8 +1,15 @@
 /** Generation composer: render variables, pick H3 parameters, and submit a
- * protected generation request. Launched from a prompt version. */
+ * protected generation request. Launched from a prompt version.
+ *
+ * The composer also offers H3 camera-movement preset chips (see
+ * `@h3/shared` `cameraPresets`). Activating a chip inserts the preset's token at
+ * the current prompt cursor without disturbing the surrounding text. The edited
+ * prompt is sent as a rendered-prompt override so it is still validated through
+ * the existing H3 request policy (character limit etc.) before submission. */
 
-import { useEffect, useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import {
+  CAMERA_PRESETS,
   findMissingVariables,
   H3_ADAPTIVE_RATIO,
   H3_CONCRETE_RATIOS,
@@ -10,9 +17,11 @@ import {
   H3_MIN_DURATION_SECONDS,
   H3_RATIOS,
   H3_RESOLUTION,
+  insertTokenAtSelection,
   mediaMode,
   renderTemplate,
   UnresolvedVariableError,
+  type CameraPreset,
   type ProviderName,
 } from '@h3/shared';
 import type { CreateGenerationRequest } from '@h3/shared';
@@ -39,6 +48,19 @@ export function Composer({
   const [variables, setVariables] = useState<string[]>([]);
   const [values, setValues] = useState<Record<string, string>>({});
 
+  // Editable rendered prompt. While the user has not touched it, it mirrors the
+  // rendered template (so filling a variable live-updates it). Once a camera cue
+  // is inserted or the text is hand-edited, it is frozen as the source of truth
+  // so surrounding edits and inserted tokens are preserved.
+  const [promptOverride, setPromptOverride] = useState('');
+  const [promptTouched, setPromptTouched] = useState(false);
+  const promptRef = useRef<HTMLTextAreaElement | null>(null);
+  // True once the user has focused/placed the cursor in the prompt; before that,
+  // a chip appends at the end rather than at an uninitialized (0) cursor.
+  const promptInteractedRef = useRef(false);
+  // Restored to the DOM after a chip insert so the caret lands after the token.
+  const pendingSelectionRef = useRef<{ start: number; end: number } | null>(null);
+
   const [duration, setDuration] = useState(6);
   const [aspectRatio, setAspectRatio] = useState<string>(H3_CONCRETE_RATIOS[0]);
   const [firstFrame, setFirstFrame] = useState('');
@@ -87,16 +109,38 @@ export function Composer({
     [content, values],
   );
 
-  const preview = useMemo(() => {
+  // Rendered template (variables substituted). Shown editable in the UI and sent
+  // as the prompt override. Separated from `missing` so a render error (e.g. an
+  // unresolved variable) does not also disable other derived state.
+  const rendered = useMemo<{ text: string | null; error: string | null }>(() => {
     try {
-      return renderTemplate(content, values);
+      return { text: renderTemplate(content, values), error: null };
     } catch (e) {
-      return e instanceof UnresolvedVariableError
-        ? `Missing variable: ${e.variable}`
-        : 'Preview unavailable.';
+      const msg =
+        e instanceof UnresolvedVariableError
+          ? `Missing variable: ${e.variable}`
+          : 'Preview unavailable.';
+      return { text: null, error: msg };
     }
   }, [content, values]);
 
+  // The prompt the user actually sees and submits. Untouched → live render;
+  // touched → the frozen, possibly cue-augmented override.
+  const effectivePrompt = promptTouched ? promptOverride : (rendered.text ?? '');
+
+  // Restore the caret to the end of an inserted token once the new value is in
+  // the DOM. Only acts immediately after a chip insert (pendingSelection set).
+  useEffect(() => {
+    const el = promptRef.current;
+    const sel = pendingSelectionRef.current;
+    if (el && sel) {
+      el.selectionStart = sel.start;
+      el.selectionEnd = sel.end;
+      pendingSelectionRef.current = null;
+      el.focus();
+    }
+  }, [effectivePrompt]);
+
   // Conditional H3 ratio behavior, exposed honestly in the UI:
   //  - text-to-video requires a concrete ratio;
   //  - first/last-frame mode is adaptive;
@@ -121,6 +165,26 @@ export function Composer({
 
   const canSubmit = missing.length === 0 && !submitting;
 
+  function insertCameraPreset(preset: CameraPreset) {
+    const el = promptRef.current;
+    const text = effectivePrompt;
+    // Before the user has placed the cursor, append at the end (intuitive
+    // default) instead of an uninitialized 0 cursor.
+    const fallback = text.length;
+    const start = el && promptInteractedRef.current ? el.selectionStart : fallback;
+    const end = el && promptInteractedRef.current ? el.selectionEnd : fallback;
+    const result = insertTokenAtSelection(text, start, end, preset.token);
+    pendingSelectionRef.current = { start: result.selectionStart, end: result.selectionEnd };
+    setPromptOverride(result.text);
+    setPromptTouched(true);
+  }
+
+  function resetPrompt() {
+    setPromptTouched(false);
+    setPromptOverride('');
+    promptInteractedRef.current = false;
+  }
+
   async function submit() {
     if (!canSubmit) return;
     setSubmitting(true);
@@ -128,6 +192,9 @@ export function Composer({
     const body: CreateGenerationRequest = {
       promptVersionId: versionId,
       values,
+      // The rendered prompt (with any inserted camera cues) is the exact text
+      // generated. The server still enforces the H3 character limit on it.
+      prompt: effectivePrompt,
       durationSeconds: duration,
       aspectRatio: effectiveRatio as CreateGenerationRequest['aspectRatio'],
       resolution: H3_RESOLUTION,
@@ -220,20 +287,65 @@ export function Composer({
           </div>
 
           <div className="card">
-            <div className="section-title">Rendered prompt</div>
-            <pre
-              className="mono"
-              style={{
-                whiteSpace: 'pre-wrap',
-                margin: 0,
-                background: 'var(--bg-elev)',
-                padding: 12,
-                borderRadius: 8,
-                border: '1px solid var(--border)',
-              }}
+            <div className="row between">
+              <div className="section-title" style={{ margin: 0 }}>
+                Prompt
+              </div>
+              {promptTouched ? (
+                <button
+                  type="button"
+                  className="btn ghost sm"
+                  onClick={resetPrompt}
+                  title="Replace the prompt with the freshly rendered template"
+                >
+                  Reset to rendered
+                </button>
+              ) : null}
+            </div>
+
+            <div
+              className="chips"
+              role="group"
+              aria-label="Camera movement presets"
             >
-              {preview}
-            </pre>
+              {CAMERA_PRESETS.map((preset) => (
+                <button
+                  key={preset.id}
+                  type="button"
+                  className="chip"
+                  onClick={() => insertCameraPreset(preset)}
+                  title={preset.description}
+                >
+                  {preset.label}
+                </button>
+              ))}
+            </div>
+
+            <Field
+              label="Rendered prompt"
+              htmlFor="c-prompt"
+              hint="Camera cues insert at the cursor. This exact text is generated and still validated before submission."
+            >
+              <textarea
+                id="c-prompt"
+                ref={promptRef}
+                value={effectivePrompt}
+                placeholder="Fill in the variables to render the prompt…"
+                onChange={(e) => {
+                  setPromptOverride(e.target.value);
+                  setPromptTouched(true);
+                  promptInteractedRef.current = true;
+                }}
+                onFocus={() => {
+                  promptInteractedRef.current = true;
+                }}
+                onSelect={() => {
+                  promptInteractedRef.current = true;
+                }}
+                style={{ minHeight: 150 }}
+              />
+            </Field>
+            {rendered.error ? <ErrorBanner message={rendered.error} /> : null}
           </div>
         </div>
 
diff --git a/packages/client/src/styles.css b/packages/client/src/styles.css
index 38bca37..57edb63 100644
--- a/packages/client/src/styles.css
+++ b/packages/client/src/styles.css
@@ -275,6 +275,37 @@ button {
   font-size: 12px;
 }
 
+/* Camera-movement preset chips (insert a cue into the prompt at the cursor) */
+.chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin: 10px 0 14px;
+}
+.chip {
+  appearance: none;
+  cursor: pointer;
+  font: inherit;
+  font-size: 13px;
+  color: var(--text);
+  background: var(--bg-elev-2);
+  border: 1px solid var(--border-strong);
+  border-radius: 999px;
+  padding: 5px 13px;
+  transition: filter 0.15s ease, border-color 0.15s ease, background 0.15s ease;
+}
+.chip:hover {
+  filter: brightness(1.12);
+  border-color: var(--accent);
+}
+.chip:active {
+  transform: translateY(1px);
+}
+.chip:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
 /* Badges */
 .badge {
   font-size: 11px;
diff --git a/packages/server/src/__tests__/services.test.ts b/packages/server/src/__tests__/services.test.ts
index 6ccbd57..86c7c62 100644
--- a/packages/server/src/__tests__/services.test.ts
+++ b/packages/server/src/__tests__/services.test.ts
@@ -273,6 +273,74 @@ describe('GenerationService idempotency', () => {
   });
 });
 
+describe('GenerationService prompt override (camera cues)', () => {
+  it('uses the supplied prompt verbatim instead of rendering the version', async () => {
+    const detail = createPromptWithContent('render {{subject}}');
+    const result = await generationService.create({
+      promptVersionId: detail.versions[0]!.id,
+      values: { subject: 'cat' },
+      prompt: 'a cat, tracking shot',
+      durationSeconds: 5,
+      aspectRatio: '16:9',
+      resolution: '2K',
+    });
+    expect(result.job.renderedPrompt).toBe('a cat, tracking shot');
+  });
+
+  it('still enforces the H3 char limit on the supplied prompt before submission', async () => {
+    const detail = createPromptWithContent('render {{subject}}');
+    await expect(
+      generationService.create({
+        promptVersionId: detail.versions[0]!.id,
+        values: {},
+        prompt: 'x'.repeat(7001),
+        durationSeconds: 5,
+        aspectRatio: '16:9',
+        resolution: '2K',
+      }),
+    ).rejects.toMatchObject({ code: ErrorCode.VALIDATION_ERROR, status: 400 });
+    // No job row created (enforced before persistence).
+    expect(jobs.list({ limit: 100 })).toHaveLength(0);
+  });
+
+  it('treats a blank prompt override as absent and renders from the version', async () => {
+    const detail = createPromptWithContent('render {{subject}}');
+    const result = await generationService.create({
+      promptVersionId: detail.versions[0]!.id,
+      values: { subject: 'cat' },
+      prompt: '   ',
+      durationSeconds: 5,
+      aspectRatio: '16:9',
+      resolution: '2K',
+    });
+    expect(result.job.renderedPrompt).toBe('render cat');
+  });
+
+  it('distinguishes jobs by the supplied prompt text for idempotency', async () => {
+    const detail = createPromptWithContent('render {{subject}}');
+    const base = {
+      promptVersionId: detail.versions[0]!.id,
+      values: { subject: 'cat' },
+      durationSeconds: 5,
+      aspectRatio: '16:9' as const,
+      resolution: '2K' as const,
+      idempotencyKey: 'k-prompt',
+    };
+    const first = await generationService.create({ ...base, prompt: 'pan left' });
+    expect(first.job.renderedPrompt).toBe('pan left');
+
+    // Same key, different prompt text -> conflict (not reuse).
+    await expect(
+      generationService.create({ ...base, prompt: 'push in' }),
+    ).rejects.toMatchObject({ code: ErrorCode.IDEMPOTENCY_CONFLICT });
+
+    // Same key, same prompt text -> reuse.
+    const reused = await generationService.create({ ...base, prompt: 'pan left' });
+    expect(reused.reused).toBe(true);
+    expect(reused.job.id).toBe(first.job.id);
+  });
+});
+
 describe('JobPoller lifecycle', () => {
   it('advances a queued job to succeeded across ticks', async () => {
     const detail = createPromptWithContent('render {{subject}}');
diff --git a/packages/server/src/__tests__/util.test.ts b/packages/server/src/__tests__/util.test.ts
index 5dc378a..771394b 100644
--- a/packages/server/src/__tests__/util.test.ts
+++ b/packages/server/src/__tests__/util.test.ts
@@ -40,6 +40,12 @@ describe('computePayloadHash determinism (locale-independent code-unit ordering)
       computePayloadHash({ ...base, values: { a: '2' } }),
     );
   });
+
+  it('produces different hashes for different prompt overrides', () => {
+    expect(
+      computePayloadHash({ ...base, values: { a: '1' }, prompt: 'pan left' }),
+    ).not.toBe(computePayloadHash({ ...base, values: { a: '1' }, prompt: 'push in' }));
+  });
 });
 
 describe('compareCodeUnits / sortRecord', () => {
diff --git a/packages/server/src/services/generationService.ts b/packages/server/src/services/generationService.ts
index f7d0d2a..03d00cf 100644
--- a/packages/server/src/services/generationService.ts
+++ b/packages/server/src/services/generationService.ts
@@ -47,11 +47,15 @@ export class GenerationService {
       );
     }
 
-    const renderedPrompt = this.renderOrFail(version.content, request.values);
+    const renderedPrompt = this.resolveRenderedPrompt(
+      version.content,
+      request.values,
+      request.prompt,
+    );
 
     // Official H3 contract: the text item is capped at 7000 chars. Enforce on
-    // the rendered prompt (after substitution), server-side, BEFORE any job is
-    // created or the provider is called.
+    // the rendered prompt (after substitution or the supplied override), server-
+    // side, BEFORE any job is created or the provider is called.
     if (renderedPrompt.length > H3_MAX_PROMPT_CHARS) {
       throw new ApiError(
         ErrorCode.VALIDATION_ERROR,
@@ -69,6 +73,7 @@ export class GenerationService {
     const payloadHash = computePayloadHash({
       promptVersionId: request.promptVersionId,
       values: request.values,
+      prompt: request.prompt,
       durationSeconds: request.durationSeconds,
       aspectRatio: request.aspectRatio,
       resolution: request.resolution,
@@ -97,6 +102,7 @@ export class GenerationService {
     const now = nowIso();
     const parameters = {
       values: request.values,
+      prompt: request.prompt ?? null,
       durationSeconds: request.durationSeconds,
       aspectRatio: request.aspectRatio,
       resolution: request.resolution,
@@ -253,6 +259,7 @@ export class GenerationService {
   ): CreateGenerationRequest {
     const p = original.parameters as {
       values?: Record<string, string>;
+      prompt?: string | null;
       durationSeconds?: number;
       aspectRatio?: string;
       resolution?: string;
@@ -276,6 +283,9 @@ export class GenerationService {
       referenceAudioUrl: p.referenceAudioUrl ?? undefined,
       idempotencyKey,
     };
+    if (p.prompt && p.prompt.length > 0) {
+      request.prompt = p.prompt;
+    }
     if (p.mockScenario) {
       request.mockScenario = p.mockScenario;
     }
@@ -314,6 +324,25 @@ export class GenerationService {
     }
   }
 
+  /**
+   * Determine the final prompt text item. A non-blank client-supplied `prompt`
+   * override (e.g. the rendered prompt with inserted camera-motion cues) is used
+   * verbatim; otherwise the immutable version is rendered with `values`. Either
+   * way the result is subject to the H3 rendered-character limit by the caller.
+   * The route layer trims the override via the schema; the `.trim()` guard here
+   * also protects direct/retry callers that may supply a whitespace-only value.
+   */
+  private resolveRenderedPrompt(
+    content: string,
+    values: Record<string, string>,
+    promptOverride: string | undefined,
+  ): string {
+    if (promptOverride !== undefined && promptOverride.trim().length > 0) {
+      return promptOverride;
+    }
+    return this.renderOrFail(content, values);
+  }
+
   /**
    * Translate a submission error into a single, consistent error vocabulary: a
    * `ProviderErrorCategory` value (stored on `generation_jobs.error_code`). A
diff --git a/packages/server/src/util.ts b/packages/server/src/util.ts
index 991ad11..5dcf4ab 100644
--- a/packages/server/src/util.ts
+++ b/packages/server/src/util.ts
@@ -22,6 +22,8 @@ export function newId(): string {
 export function computePayloadHash(input: {
   promptVersionId: string;
   values: Record<string, string>;
+  /** Rendered-prompt override (e.g. with inserted camera cues). */
+  prompt?: string;
   durationSeconds: number;
   aspectRatio: string;
   resolution: string;
@@ -36,6 +38,7 @@ export function computePayloadHash(input: {
     durationSeconds: input.durationSeconds,
     aspectRatio: input.aspectRatio,
     resolution: input.resolution,
+    prompt: input.prompt ?? '',
     values: sortRecord(input.values),
     urls: sortRecord({
       firstFrameUrl: input.firstFrameUrl ?? '',
diff --git a/packages/shared/src/__tests__/cameraPresets.test.ts b/packages/shared/src/__tests__/cameraPresets.test.ts
new file mode 100644
index 0000000..c86f4d9
--- /dev/null
+++ b/packages/shared/src/__tests__/cameraPresets.test.ts
@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CAMERA_PRESETS,
+  findCameraPreset,
+  insertTokenAtSelection,
+} from '../cameraPresets.js';
+
+describe('CAMERA_PRESETS', () => {
+  it('exposes the minimum required H3 camera-motion cues', () => {
+    const labels = CAMERA_PRESETS.map((p) => p.label);
+    expect(labels).toEqual([
+      'Pan left',
+      'Pan right',
+      'Push in',
+      'Pull out',
+      'Tracking shot',
+      'Static shot',
+    ]);
+  });
+
+  it('every preset has a stable id, a non-empty token, and a description', () => {
+    for (const preset of CAMERA_PRESETS) {
+      expect(preset.id.length).toBeGreaterThan(0);
+      expect(preset.token.trim().length).toBeGreaterThan(0);
+      expect(preset.description.trim().length).toBeGreaterThan(0);
+    }
+  });
+
+  it('ids are unique (safe React keys / test selectors)', () => {
+    const ids = CAMERA_PRESETS.map((p) => p.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('findCameraPreset resolves by id and returns undefined for unknown ids', () => {
+    expect(findCameraPreset('pan-left')?.label).toBe('Pan left');
+    expect(findCameraPreset('nope')).toBeUndefined();
+  });
+});
+
+describe('insertTokenAtSelection', () => {
+  it('inserts at the start, adding a trailing space so the rest reads naturally', () => {
+    const result = insertTokenAtSelection('hello world', 0, 0, 'pan left');
+    expect(result.text).toBe('pan left hello world');
+    // Caret lands right after the inserted token word.
+    expect(result.selectionStart).toBe('pan left'.length);
+    expect(result.selectionEnd).toBe('pan left'.length);
+  });
+
+  it('inserts in the middle at the cursor without duplicating spacing', () => {
+    // Cursor sits on the existing space between the two words.
+    const result = insertTokenAtSelection('hello world', 5, 5, 'pan left');
+    expect(result.text).toBe('hello pan left world');
+    expect(result.selectionStart).toBe('hello pan left'.length);
+    expect(result.selectionEnd).toBe('hello pan left'.length);
+  });
+
+  it('inserts in the middle between non-space characters with spacing on both sides', () => {
+    // Cursor between "ab" and "cd" with no surrounding whitespace.
+    const result = insertTokenAtSelection('abcd', 2, 2, 'pan left');
+    expect(result.text).toBe('ab pan left cd');
+    expect(result.selectionStart).toBe('ab pan left'.length);
+  });
+
+  it('appends at the end with a leading space', () => {
+    const result = insertTokenAtSelection('hello world', 11, 11, 'pan left');
+    expect(result.text).toBe('hello world pan left');
+    expect(result.selectionStart).toBe('hello world pan left'.length);
+    expect(result.selectionEnd).toBe('hello world pan left'.length);
+  });
+
+  it('replaces the current selection with the token', () => {
+    // "hello" (0..5) is selected and replaced.
+    const result = insertTokenAtSelection('hello world', 0, 5, 'static shot');
+    expect(result.text).toBe('static shot world');
+    expect(result.selectionStart).toBe('static shot'.length);
+    expect(result.selectionEnd).toBe('static shot'.length);
+  });
+
+  it('does not add a leading space when replacing a selection at the start', () => {
+    const result = insertTokenAtSelection('hello world', 0, 5, 'tracking shot');
+    expect(result.text).toBe('tracking shot world');
+    expect(result.text.at(0)).not.toBe(' ');
+  });
+
+  it('does not double up whitespace adjacent to existing whitespace', () => {
+    // Leading space already present before the cursor.
+    const result = insertTokenAtSelection('hello ', 6, 6, 'push in');
+    expect(result.text).toBe('hello push in');
+  });
+
+  it('handles an empty prompt by becoming just the token', () => {
+    const result = insertTokenAtSelection('', 0, 0, 'pan left');
+    expect(result.text).toBe('pan left');
+    expect(result.selectionStart).toBe('pan left'.length);
+  });
+
+  it('clamps out-of-range selection indices into the text bounds', () => {
+    const tooFar = insertTokenAtSelection('hi', 999, 999, 'pan left');
+    expect(tooFar.text).toBe('hi pan left');
+  });
+
+  it('treats a non-finite cursor (uninitialized) as the end of the text', () => {
+    const result = insertTokenAtSelection('hi', Number.NaN, Number.NaN, 'pan left');
+    expect(result.text).toBe('hi pan left');
+  });
+
+  it('normalizes a reversed selection (start > end) like a forward selection', () => {
+    const result = insertTokenAtSelection('hello world', 5, 0, 'static shot');
+    expect(result.text).toBe('static shot world');
+  });
+
+  it('is pure: the inputs are not mutated', () => {
+    const original = 'hello world';
+    insertTokenAtSelection(original, 5, 5, 'pan left');
+    expect(original).toBe('hello world');
+  });
+});
diff --git a/packages/shared/src/__tests__/schemas.test.ts b/packages/shared/src/__tests__/schemas.test.ts
index 3fc9b73..0ee0571 100644
--- a/packages/shared/src/__tests__/schemas.test.ts
+++ b/packages/shared/src/__tests__/schemas.test.ts
@@ -89,6 +89,19 @@ describe('createGenerationSchema validation', () => {
   it('requires a prompt version id', () => {
     expect(() => createGenerationSchema.parse({ ...base, promptVersionId: '' })).toThrow();
   });
+
+  it('accepts an optional rendered-prompt override and caps it at the H3 limit', () => {
+    expect(() =>
+      createGenerationSchema.parse({ ...base, prompt: 'a car, pan left' }),
+    ).not.toThrow();
+    const at = createGenerationSchema.parse({ ...base, prompt: 'x'.repeat(7000) });
+    expect(at.prompt).toHaveLength(7000);
+    expect(() =>
+      createGenerationSchema.parse({ ...base, prompt: 'x'.repeat(7001) }),
+    ).toThrow();
+    // Blank trims to empty (treated as "no override" by the service).
+    expect(createGenerationSchema.parse({ ...base, prompt: '   ' }).prompt).toBe('');
+  });
 });
 
 describe('createGenerationSchema cross-field + ratio rules (negative)', () => {
diff --git a/packages/shared/src/cameraPresets.ts b/packages/shared/src/cameraPresets.ts
new file mode 100644
index 0000000..e986429
--- /dev/null
+++ b/packages/shared/src/cameraPresets.ts
@@ -0,0 +1,141 @@
+/**
+ * Camera-movement preset chips — a small, pure, dependency-free module.
+ *
+ * MiniMax's official H3 guide recommends camera-motion cues (pan, push/pull,
+ * tracking, static, …). Rather than ask creators to remember or retype the
+ * supported phrasing, the generation composer offers one-click "chips" that
+ * insert a preset token at the current prompt cursor.
+ *
+ * The data (labels + inserted tokens) and the insertion logic live here so they
+ * are testable in isolation and are not duplicated across UI surfaces. The
+ * inserted token is ordinary prompt text; once inserted it is validated through
+ * the same H3 request policy (character limit etc.) as any other prompt.
+ *
+ * Source: MiniMax platform guides
+ * `guides/video-generation` (camera-motion cues for model `MiniMax-H3`).
+ */
+
+/** A single camera-movement preset surfaced as a chip in the composer. */
+export interface CameraPreset {
+  /** Stable id for React keys / test selectors. */
+  id: string;
+  /** Human-readable chip label; doubles as the accessible name. */
+  label: string;
+  /** Exact text inserted into the prompt at the cursor. */
+  token: string;
+  /** Short description of the motion, used for tooltips/aria descriptions. */
+  description: string;
+}
+
+/**
+ * The minimum set of H3 camera-motion presets. Order is the chip order shown in
+ * the UI. Keep this in one place so labels and tokens stay in sync and testable.
+ */
+export const CAMERA_PRESETS: readonly CameraPreset[] = [
+  {
+    id: 'pan-left',
+    label: 'Pan left',
+    token: 'pan left',
+    description: 'Camera pans horizontally to the left.',
+  },
+  {
+    id: 'pan-right',
+    label: 'Pan right',
+    token: 'pan right',
+    description: 'Camera pans horizontally to the right.',
+  },
+  {
+    id: 'push-in',
+    label: 'Push in',
+    token: 'push in',
+    description: 'Camera moves forward, toward the subject.',
+  },
+  {
+    id: 'pull-out',
+    label: 'Pull out',
+    token: 'pull out',
+    description: 'Camera moves backward, away from the subject.',
+  },
+  {
+    id: 'tracking-shot',
+    label: 'Tracking shot',
+    token: 'tracking shot',
+    description: 'Camera follows the moving subject.',
+  },
+  {
+    id: 'static-shot',
+    label: 'Static shot',
+    token: 'static shot',
+    description: 'Fixed, unmoving camera.',
+  },
+];
+
+/** Look up a preset by id (returns undefined when absent). */
+export function findCameraPreset(id: string): CameraPreset | undefined {
+  return CAMERA_PRESETS.find((preset) => preset.id === id);
+}
+
+/** Result of inserting a token into a text field. */
+export interface TokenInsertResult {
+  /** The new full text after insertion. */
+  text: string;
+  /** Carear position after the inserted token (collapsed selection). */
+  selectionStart: number;
+  selectionEnd: number;
+}
+
+function clampIndex(value: number, max: number): number {
+  if (!Number.isFinite(value)) return max;
+  const truncated = Math.trunc(value);
+  if (truncated < 0) return 0;
+  if (truncated > max) return max;
+  return truncated;
+}
+
+/**
+ * Insert `token` into `text` at the current selection, replacing any selected
+ * range. A single space is added before and/or after the token only when the
+ * neighbouring text does not already provide separation, so surrounding text is
+ * preserved and the result reads naturally.
+ *
+ * The returned selection is collapsed to the end of the inserted token, matching
+ * typical "insert" behavior in a text field.
+ *
+ * Selection indices outside `[0, text.length]` are clamped, and a non-finite
+ * index (e.g. an uninitialized cursor) is treated as the end of the text.
+ */
+export function insertTokenAtSelection(
+  text: string,
+  selectionStart: number,
+  selectionEnd: number,
+  token: string,
+): TokenInsertResult {
+  const max = text.length;
+  const rawStart = clampIndex(selectionStart, max);
+  const rawEnd = clampIndex(selectionEnd, max);
+  const start = Math.min(rawStart, rawEnd);
+  const end = Math.max(rawStart, rawEnd);
+
+  const before = text.slice(0, start);
+  const after = text.slice(end);
+
+  const needsLeadingSpace = before.length > 0 && !/\s$/.test(before);
+  const needsTrailingSpace = after.length > 0 && !/^\s/.test(after);
+
+  const inserted =
+    (needsLeadingSpace ? ' ' : '') +
+    token +
+    (needsTrailingSpace ? ' ' : '');
+
+  const nextText = before + inserted + after;
+  // Caret lands immediately after the inserted token (excluding any trailing
+  // separator space) so it is clear where the insertion ended and a following
+  // chip/keystroke continues naturally.
+  const caret = before.length + (needsLeadingSpace ? 1 : 0) + token.length;
+
+  return {
+    text: nextText,
+    selectionStart: caret,
+    selectionEnd: caret,
+  };
+}
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index bdc69a4..0d7d36a 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -1,5 +1,6 @@
 export * from './template.js';
 export * from './h3-policy.js';
+export * from './cameraPresets.js';
 export * from './errors.js';
 export * from './types.js';
 export * from './schemas.js';
diff --git a/packages/shared/src/schemas.ts b/packages/shared/src/schemas.ts
index 572064b..b70719f 100644
--- a/packages/shared/src/schemas.ts
+++ b/packages/shared/src/schemas.ts
@@ -77,6 +77,14 @@ export const createGenerationSchema = z
   .object({
     promptVersionId: idSchema,
     values: z.record(z.string(), z.string()).default({}),
+    /**
+     * Optional fully-rendered prompt override. When a non-empty string is
+     * supplied (e.g. by the composer after inserting camera-motion cues), the
+     * server uses it verbatim as the prompt text item instead of rendering the
+     * immutable prompt version with `values`. It is still subject to the H3
+     * rendered-character limit. Omit/leave blank to render from the version.
+     */
+    prompt: z.string().trim().max(H3_MAX_PROMPT_CHARS).optional(),
     durationSeconds: z
       .number()
       .int()