Script revisions

Grace tracks script revisions properly - not as "upload a new file, lose history" but as a versioned change with diff review, fork-or-keep artifact versions, and the standard industry color cycle. This page is the detailed reference for how revisions work.

The state machine

A script revision carries:

  • isCurrent - exactly one current script per production at a time.
  • Parent script - soft link to the previous version.
  • Analysis status - pending (queued) / processing (parsing) / pending_review (diff staged and waiting for review) / complete (committed into the breakdown). A discarded draft is deleted outright, so there is no separate discarded status.
  • Diff payload - transient staging of the AI's diff vs the parent script. Held only while status is pending_review, cleared on commit and deleted with the draft on discard.
  • Revision color - one of the 11 industry colors.
  • Revision label - auto-generated from the revision number: "First Draft" for v1, "Blue revision" for v2, then "Double blue," "Triple blue" and so on after the color cycle rolls over. No date is baked into the label.

When you upload a new script:

  1. Parse - status flips to processing. The worker streams via the AI; the TopBar pill shows live progress.
  2. Diff stage - once parsed, status flips to pending_review. The diff is staged. You review it on the breakdown review page.
  3. Commit - accept/reject per scene, optionally keep the prior artifact versions, click COMMIT. Status becomes complete, the new revision becomes current, and the parent stops being current.
  4. Discard - alternatively, abandon the draft. Grace deletes the draft row entirely and nothing changes in the breakdown.

Industry revision colors

The standard production-stationery color cycle, in order:

white -> blue -> pink -> yellow -> green -> goldenrod -> buff -> salmon -> cherry -> tan -> ivory

After ivory, the prefix becomes "Double":

Double white -> Double blue -> Double pink -> ... -> Double ivory -> Triple white -> ...

White is index 0 (the original shooting script); blue is the first revision; and so on.

Each revision's color surfaces in:

  • The script header on the breakdown review page.
  • The version dropdown in the breakdown.
  • The ArtifactVersionBar on the schedule, budget, and shot-list pages, so you always know which revision a given artifact version is bound to.

Scene matching

Grace runs a scene-by-scene diff between parent and child scripts using a three-pass heuristic:

  1. Exact match by scene number. Both scripts have a "5A" -> it's the same scene.
  2. Heading similarity - catches renames like "INT. KITCHEN - DAY" -> "INT. ALANA'S KITCHEN - DAY" where the description didn't change much.
  3. Content fingerprint - catches content-only changes where the header didn't move.

Results bucket into:

  • Unchanged - same scene, same content.
  • Modified - same scene number, different content. Shown for accept/reject.
  • Added - new scene number in child, no parent match.
  • Removed - parent scene number missing from child.
  • Possible - heading similarity match but not exact. Manual review.

Merge-by-name on commit

When you commit a modified scene, Grace merges elements by name (matched case-insensitively within a category) instead of wipe-and-replace. For each existing element on the parent scene:

  • If a matching element exists in the child -> UPDATE (preserving cast linkage, verification status, descriptions).
  • If no match -> DELETE (soft-delete; soft-deleted elements stay in audit but are excluded from views).
  • Any new element from the child -> INSERT.

This is critical because the AI parse doesn't see user-edited fields. If you (a producer) marked a stunt element as verified, then re-uploaded the script, a wipe-and-replace would lose the verification. Merge-by-name preserves it.

Artifact versioning

The schedule, budget, and shot list are version-controlled per (production, script). Exactly one version per artifact is active at any time. Activating a new version atomically deactivates the previous one.

On revision commit, the UI offers fork toggles per artifact:

  • Fork schedule - snapshot the active schedule into a new version bound to the new script. Edits to the new version don't affect the old one.
  • Fork budget - same idea.
  • Fork shot list - same.

By default all three toggles are on, so Grace forks the schedule, budget, and shot list into fresh versions bound to the revision and keeps the prior ones as pinned snapshots you can switch back to. Uncheck a toggle to keep that artifact's current version carrying forward unchanged. A single optional fork-name field labels all three forks at once (for example, "v2 Blue baseline").

Call sheets pin their version

Call sheets bind to the schedule version that was active at approve time. You literally cannot delete a schedule version that has approved call sheets pointing at it. This is the archival invariant - the call sheet you sent on Day 1 references exactly the schedule that was current.

Scene snapshots

Each commit freezes a snapshot of every scene tied to that revision. So when you pull up "Day 1's call sheet referenced these scenes from the blue revision" you see exactly the scene data that existed at that revision - not whatever the scene looks like today.

The dot system on revisions

When a revision is committed, accepted MODIFIED scenes have their elements re-stamped through merge-by-name, so human work carries over:

  • Verified elements stay green. If you confirmed a stunt or cast element on the parent scene, its green (verified) dot is preserved.
  • Manual overrides stay gold. A value you typed in by hand keeps its gold dot; Grace does not overwrite it.
  • New elements from the AI parse get blue dots (Grace suggested, still unverified).
  • Removed elements are soft-deleted - omitted scenes stay visible with strike-through, and their takes, strips, and notes are preserved.

A producer reviewing a revision sees at a glance which elements are fresh AI guesses (blue) versus values they already verified (green) or set by hand (gold).

The revision page UI

The breakdown review page opens with a summary header directly under the title (for example, "REVIEW v2 BLUE"). The summary reads "N unchanged, N modified, N added, N removed," followed by the revision label. Below it:

  • Unchanged scenes are auto-accepted and listed for reference.
  • Modified scenes are split across three tabs - HEADER, CONTENT, and BOTH - each showing the count of scenes changed that way, with per-scene Accept/Reject.
  • Added scenes get Accept/Reject. Grace warns when a new scene looks like a modification of one you are also removing, so you don't create a duplicate.
  • Removed scenes get Omit / Keep live.
  • An Artifact Forks bar with the three fork toggles (all on by default), one shared optional fork-name field, and the COMMIT and DISCARD buttons.