scriptflow/docs/plans/2026-03-11-audience-word-range.md

Audience And Word Range Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add shared audience and word-range controls to both modes, persist them locally, and include them in every script generation request.

Architecture: Extend src/App.tsx with two new shared state values and reusable option lists, render matching controls in both parameter areas, and thread the new values through the existing AI request payloads. Update src/services/ai.ts to accept the expanded settings object and append the new fields to prompts.

Tech Stack: React 19, TypeScript, Vite

---

Task 1: Add shared state and persistence

Files:

• Modify: src/App.tsx

Step 1: Add the failing test surrogate

There is no existing automated test harness in this repo, so use TypeScript as the first guard by introducing the new state and payload types in a way that will initially break downstream call sites until they are wired through.

Step 2: Verify the break

Run: npm run lint Expected: FAIL until all new settings usages are connected.

Step 3: Write minimal implementation

• Add AudiencePreference and WordRange union types.
• Add shared option arrays.
• Add useState hooks with Chinese defaults.
• Persist them with localStorage.

Step 4: Verify

Run: npm run lint Expected: still failing until AI payload changes are completed.

Task 2: Render controls in both modes

Files:

• Modify: src/App.tsx

Step 1: Add UI in conversion mode

• Insert 受众倾向 and 字数范围 rows into the expanded conversion settings panel.

Step 2: Add UI in creation mode

• Insert the same two rows into the creation top filter area.

Step 3: Keep styling consistent

• Reuse the existing pill-button class patterns.
• Ensure the labels remain Chinese-only.

Task 3: Thread settings into AI generation

Files:

• Modify: src/App.tsx
• Modify: src/services/ai.ts

Step 1: Expand payload shape

• Add audiencePreference and wordRange to the existing global settings object passed into generation functions.

Step 2: Update all call sites

• convertTextToScript
• generatePageScript
• generateAllScripts

Step 3: Update prompts

• Mention audience preference and target word range in each generated prompt alongside worldview, outline, and characters.

Task 4: Verify

Files:

• Modify: src/App.tsx
• Modify: src/services/ai.ts

Step 1: Run type check

Run: npm run lint Expected: PASS

Step 2: Run production build

Run: npm run build Expected: PASS

Step 3: Review

• Confirm both modes show the two controls.
• Confirm defaults are 男频 and 不限.
• Confirm no English values were introduced.