# Social Draft Approval Package Pattern

Use this when moving from render planning toward the first user-facing social-media post draft for approval.

## Goal

Produce a complete approval draft before TTS, video rendering, or platform APIs:

```text
VideoCandidate + RenderManifest/Preview
→ SocialMediaDraft
→ SocialMediaDraft review text
→ side-effect-free delivery plan
→ demo CLI output
```

This gives the user a concrete post candidate to approve or revise while still avoiding accidental publishing, external calls, and wasted GPU/TTS work.

## Recommended typed artifacts

1. `SocialMediaDraft`
   - candidate id
   - target platforms: YouTube Shorts, TikTok, Instagram Reels
   - title variants
   - caption
   - hashtags
   - CTA
   - hook
   - planned duration
   - quality/risk summary
   - preview reference, e.g. HTML timeline available or MP4 pending
   - `requires_human_approval=True`
   - `side_effects=()`

2. Social review renderer
   - Telegram-safe text block
   - includes candidate, platforms, hook, titles, caption, hashtags, preview note, quality/risk summary
   - includes approval commands: `Freigabe alle`, platform-specific approvals, `Ablehnen`, `Ändern: <...>`
   - must not imply automatic upload or publishing

3. Draft delivery preparation
   - validates message length and safety language
   - returns typed delivery plan with `requires_human_approval=True` and `side_effects=()`
   - no Telegram API call yet

4. Demo CLI
   - e.g. `python -m autoshorts.cli.demo_social_draft`
   - prints delivery metadata first, then the review text
   - no file writes, platform calls, renderer calls, or credential access

## Sequence before TTS

Do not start with TTS. First get approval on the content package:

```text
ContentBrief
→ ScriptDraft
→ VideoCandidate
→ ShotPlan
→ RenderManifest
→ Preview
→ SocialMediaDraft
→ Review text
→ Approval delivery preview
```

A robust implementation can be split into small TDD slices:

1. `social/draft.py` — `build_social_media_draft(candidate, preview)` and `validate_social_media_draft(draft)`.
2. `social/review.py` — `render_social_media_draft_review(draft)` for Telegram-safe approval text.
3. `social/delivery.py` — `prepare_social_draft_delivery(text, topic="review")` returning a side-effect-free delivery object.
4. `cli/demo_social_draft.py` — local demo command that prints metadata first, then the review text.

Recommended invariant tests for every slice:

- `requires_human_approval is True`
- `side_effects == ()`
- no platform API calls, Telegram calls, renderer calls, file writes, or credential access
- review/delivery text stays under Telegram's 4096-character limit
- review/delivery text does not contain `publish` or `post`
- platform labels are human-readable (`YouTube Shorts`, `TikTok`, `Instagram Reels`) while stored platform ids remain normalized (`youtube`, `tiktok`, `instagram`)
- preview script/reference matches the candidate source brief before building the social draft

Only after the draft is structurally approved should TTS design start:

- voice selection
- final voiceover script
- words-per-second / timing
- caption sync
- audio format
- provider choice
- separate voice approval if needed

## Guardrails

- No credentials in draft output.
- No platform API calls.
- No publish/post semantics except inside explicit approval-command documentation if the codebase already uses that language carefully.
- Preview references are allowed; generated media paths should be placeholders unless a later renderer created real artifacts.
- Keep captions, numbers, labels, arrows, UI text, claims, and platform metadata renderer-owned / system-owned, never baked into generated AI assets.