1326 lines
28 KiB
Markdown
1326 lines
28 KiB
Markdown
# PlotDirector – Microsoft Word Companion Add-in & Manuscript Sync API
|
||
|
||
## Overview
|
||
|
||
The PlotDirector Microsoft Word Companion Add-in is intended to provide a lightweight bridge between an author’s manuscript in Microsoft Word and their planning data in PlotDirector.
|
||
|
||
The goal is not to recreate PlotDirector inside Word. The add-in should remain focused, fast and unobtrusive.
|
||
|
||
The core philosophy is:
|
||
|
||
> **Word is where the author writes.**
|
||
> **PlotDirector is where the author plans, tracks and manages the book.**
|
||
|
||
The add-in exists to reduce friction between those two places.
|
||
|
||
It should help the author:
|
||
|
||
- See the current scene writing brief while drafting.
|
||
- Quickly sync chapters, scenes and word counts.
|
||
- Associate characters, assets and locations with the current scene.
|
||
- Create missing chapters and scenes found in the Word document.
|
||
- Avoid duplicate data entry.
|
||
|
||
It should not become a full scene editor, timeline editor, schedule planner, continuity dashboard or replacement for the main PlotDirector application.
|
||
|
||
---
|
||
|
||
## Primary Goals
|
||
|
||
The Word Companion should provide:
|
||
|
||
1. A side panel inside Microsoft Word.
|
||
2. A way to connect Word to a PlotDirector account, project and book.
|
||
3. Detection of the current chapter and scene from the Word document.
|
||
4. Display of the current scene’s writing brief.
|
||
5. Quick management of scene links:
|
||
- Characters
|
||
- Assets
|
||
- Locations
|
||
6. Sync of chapter and scene structure from Word to PlotDirector.
|
||
7. Sync of actual word counts from Word to PlotDirector.
|
||
8. Safe creation of missing chapters and scenes.
|
||
9. No deletion of PlotDirector planning data from Word.
|
||
10. A simple, fast workflow that does not interrupt writing.
|
||
|
||
---
|
||
|
||
## Non-Goals
|
||
|
||
The first version should not include:
|
||
|
||
- Full scene editing.
|
||
- Timeline editing.
|
||
- Plot line editing.
|
||
- Relationship map editing.
|
||
- Story health analytics.
|
||
- Story warnings dashboard.
|
||
- Writing schedule planner.
|
||
- Revision workflow controls.
|
||
- AI analysis.
|
||
- Automatic entity detection.
|
||
- Automatic continuity warnings.
|
||
- Full manuscript upload for analysis.
|
||
- Deleting chapters or scenes from PlotDirector.
|
||
- Reordering PlotDirector scenes automatically without review.
|
||
- Editing the scene writing brief directly in Word.
|
||
|
||
These may be considered later, but they should not be included in the initial implementation.
|
||
|
||
The add-in should avoid becoming a second version of PlotDirector.
|
||
|
||
---
|
||
|
||
## User Experience
|
||
|
||
### Typical Author Flow
|
||
|
||
1. Author opens their manuscript in Microsoft Word.
|
||
2. Author opens the PlotDirector side panel.
|
||
3. Author signs in or confirms they are already connected.
|
||
4. Author selects:
|
||
- Project
|
||
- Book
|
||
5. Author places the cursor inside a scene.
|
||
6. The side panel identifies the current chapter and scene.
|
||
7. The panel displays:
|
||
- Current chapter
|
||
- Current scene
|
||
- Scene writing brief
|
||
- Scene word count
|
||
- Character checklist
|
||
- Asset checklist
|
||
- Location checklist
|
||
8. Author ticks or unticks relevant characters, assets and locations.
|
||
9. Author clicks **Save Scene Links**.
|
||
10. Author clicks **Sync Current Scene** or **Sync All Chapters & Scenes** when needed.
|
||
|
||
---
|
||
|
||
## Side Panel Layout
|
||
|
||
The add-in should use a Microsoft Word task pane.
|
||
|
||
Suggested layout:
|
||
|
||
```text
|
||
PlotDirector
|
||
|
||
Project:
|
||
The Alpha Flame: Reckoning
|
||
|
||
Book:
|
||
Book 2
|
||
|
||
Current Location
|
||
Chapter 12: The Wall
|
||
Scene 3: Beth searches the drawer
|
||
|
||
[Refresh From Document]
|
||
[Open Scene in PlotDirector]
|
||
|
||
Scene Writing Brief
|
||
------------------------------------------------
|
||
Purpose:
|
||
Beth realises Elen may have been involved.
|
||
|
||
Key Beats:
|
||
- Beth checks the memory tin
|
||
- Finds the missing note
|
||
- Calls Rosie
|
||
- Decides not to wait for Graham
|
||
|
||
Emotional Target:
|
||
Fear becoming resolve
|
||
|
||
Continuity Notes:
|
||
Maggie is still missing.
|
||
Beth does not yet know about Kevin.
|
||
|
||
[Refresh Brief]
|
||
|
||
Scene Links
|
||
------------------------------------------------
|
||
Characters
|
||
[ ] Beth
|
||
[ ] Maggie
|
||
[ ] Rosie
|
||
[ ] Graham
|
||
[ ] Rebecca
|
||
|
||
Assets
|
||
[ ] Memory tin
|
||
[ ] Deposit box key
|
||
[ ] TR6
|
||
|
||
Locations
|
||
[ ] Grace
|
||
[ ] Ashdown House
|
||
[ ] Lickey Hills
|
||
|
||
[Save Scene Links]
|
||
|
||
Sync
|
||
------------------------------------------------
|
||
Current scene word count:
|
||
1,248
|
||
|
||
[Sync Current Scene]
|
||
[Sync All Chapters & Scenes]
|
||
|
||
Last Sync:
|
||
Today 09:42
|
||
```
|
||
|
||
The design should be compact and suitable for a narrow side panel.
|
||
|
||
---
|
||
|
||
## Add-in Responsibilities
|
||
|
||
The Word add-in should be responsible for:
|
||
|
||
- Providing the user interface inside Word.
|
||
- Reading the document structure through Office.js.
|
||
- Identifying the current chapter and scene.
|
||
- Counting words for the current scene or full manuscript.
|
||
- Fetching PlotDirector project/book data through the API.
|
||
- Fetching the current scene writing brief.
|
||
- Fetching character, asset and location lists.
|
||
- Displaying selected scene links.
|
||
- Posting scene link updates.
|
||
- Posting chapter/scene/word count sync data.
|
||
- Showing concise success or error messages.
|
||
|
||
The add-in should remain lightweight.
|
||
|
||
It should not perform heavy processing that risks making Word feel unresponsive.
|
||
|
||
---
|
||
|
||
## PlotDirector Responsibilities
|
||
|
||
PlotDirector should be responsible for:
|
||
|
||
- Authentication and authorisation.
|
||
- Storing project, book, chapter and scene records.
|
||
- Storing actual word counts.
|
||
- Storing scene links.
|
||
- Returning the writing brief for a scene.
|
||
- Creating missing chapters and scenes safely.
|
||
- Matching incoming Word structure to existing PlotDirector records.
|
||
- Validating user access to projects and books.
|
||
- Recording sync history.
|
||
- Protecting planning data from accidental deletion or overwrite.
|
||
|
||
---
|
||
|
||
## Document Structure Assumptions
|
||
|
||
The first version should rely on Word heading styles.
|
||
|
||
Recommended convention:
|
||
|
||
```text
|
||
Heading 1 = Chapter
|
||
Heading 2 = Scene
|
||
```
|
||
|
||
Example:
|
||
|
||
```text
|
||
Chapter 1: Echoes of the Past Heading 1
|
||
Scene 1: The Memory Tin Heading 2
|
||
Scene 2: St Luke’s Heading 2
|
||
|
||
Chapter 2: The Weight of Redemption Heading 1
|
||
Scene 1: Sunday Morning Heading 2
|
||
```
|
||
|
||
This avoids brittle parsing based on plain text patterns.
|
||
|
||
The add-in can later support alternative structures, such as:
|
||
|
||
- Scene separators.
|
||
- Custom markers.
|
||
- Content controls.
|
||
- Imported document mapping rules.
|
||
|
||
However, the first version should keep the rules simple.
|
||
|
||
---
|
||
|
||
## Current Scene Detection
|
||
|
||
When the cursor is inside the document, the add-in should identify the current scene by walking backwards through the document structure until it finds the nearest preceding Heading 2.
|
||
|
||
It should then identify the current chapter by walking backwards until it finds the nearest preceding Heading 1.
|
||
|
||
If no scene heading is found, the add-in should show:
|
||
|
||
```text
|
||
No scene detected.
|
||
|
||
Place the cursor inside a scene or use Heading 2 for scene titles.
|
||
```
|
||
|
||
If no chapter heading is found, the add-in should show:
|
||
|
||
```text
|
||
No chapter detected.
|
||
|
||
Use Heading 1 for chapter titles.
|
||
```
|
||
|
||
---
|
||
|
||
## Word Count Calculation
|
||
|
||
### Current Scene Word Count
|
||
|
||
The add-in should count words between:
|
||
|
||
- The current scene Heading 2.
|
||
- The next Heading 2 or Heading 1.
|
||
- Or the end of the document.
|
||
|
||
This value should be posted to PlotDirector as the scene’s actual word count.
|
||
|
||
### Full Manuscript Sync
|
||
|
||
For a full sync, the add-in should:
|
||
|
||
1. Read all Heading 1 chapters.
|
||
2. Read all Heading 2 scenes under each chapter.
|
||
3. Count words for each scene.
|
||
4. Count words for each chapter.
|
||
5. Send the structure to PlotDirector.
|
||
|
||
---
|
||
|
||
## Sync Behaviour
|
||
|
||
### Safe Sync Rules
|
||
|
||
The sync process should follow these rules:
|
||
|
||
| Word Document State | PlotDirector Action |
|
||
|--------------------|--------------------|
|
||
| Chapter exists in Word and PlotDirector | Update word count / sync metadata |
|
||
| Scene exists in Word and PlotDirector | Update actual word count / sync metadata |
|
||
| Chapter exists in Word but not PlotDirector | Create chapter |
|
||
| Scene exists in Word but not PlotDirector | Create scene |
|
||
| Chapter exists in PlotDirector but not Word | Leave unchanged |
|
||
| Scene exists in PlotDirector but not Word | Leave unchanged |
|
||
| Scene order differs | Do not automatically reorder in MVP |
|
||
| Scene title differs | Match cautiously; do not overwrite without confidence |
|
||
|
||
The add-in must not delete chapters or scenes from PlotDirector.
|
||
|
||
This is important because PlotDirector is the planning source. Chapters and scenes may exist in PlotDirector long before they are written in Word.
|
||
|
||
---
|
||
|
||
## Matching Strategy
|
||
|
||
### MVP Matching
|
||
|
||
The first version can match records by:
|
||
|
||
- Project ID
|
||
- Book ID
|
||
- Chapter title
|
||
- Scene title
|
||
|
||
This is simple and sufficient for early use.
|
||
|
||
However, title-based matching can break if the author renames chapters or scenes.
|
||
|
||
### Future Matching Improvement
|
||
|
||
A later version should introduce stable external sync IDs.
|
||
|
||
Options:
|
||
|
||
1. Store PlotDirector IDs in hidden Word content controls.
|
||
2. Store PlotDirector IDs in custom document properties.
|
||
3. Store a document-level mapping table in the add-in state.
|
||
4. Store sync IDs in hidden metadata associated with chapter/scene headings.
|
||
|
||
Recommended future direction:
|
||
|
||
```text
|
||
Use Word content controls or custom XML metadata to store stable PlotDirector ChapterID and SceneID values.
|
||
```
|
||
|
||
This would allow authors to rename chapters and scenes without breaking sync.
|
||
|
||
---
|
||
|
||
## Scene Writing Brief
|
||
|
||
The add-in should display the current scene writing brief from PlotDirector.
|
||
|
||
The brief should be read-only in the first version.
|
||
|
||
Reason:
|
||
|
||
- PlotDirector remains the planning source.
|
||
- Authors know where to edit planning information.
|
||
- It avoids confusion about whether Word or PlotDirector owns the brief.
|
||
- It keeps the add-in simple.
|
||
|
||
The panel should provide:
|
||
|
||
```text
|
||
[Open Scene in PlotDirector]
|
||
```
|
||
|
||
This allows authors to edit the scene brief in the main application when needed.
|
||
|
||
### Suggested Brief Fields
|
||
|
||
Depending on the existing PlotDirector model, the side panel may display:
|
||
|
||
- Scene purpose
|
||
- Scene summary
|
||
- Writing brief
|
||
- Key beats
|
||
- Emotional target
|
||
- Continuity notes
|
||
- Practical blockers
|
||
- Blocked reason
|
||
|
||
The first implementation should display whatever scene brief field already exists, then expand later if needed.
|
||
|
||
---
|
||
|
||
## Scene Links
|
||
|
||
The add-in should allow quick association of the current scene with:
|
||
|
||
- Characters
|
||
- Assets
|
||
- Locations
|
||
|
||
These should be shown as checklists.
|
||
|
||
### Character Checklist
|
||
|
||
Displays characters from the current project/book.
|
||
|
||
Each character item should show:
|
||
|
||
- Character name
|
||
- Existing checked state for current scene
|
||
|
||
Author actions:
|
||
|
||
- Tick character to add appearance.
|
||
- Untick character to remove appearance.
|
||
- Save changes.
|
||
|
||
### Asset Checklist
|
||
|
||
Displays assets from the current project/book.
|
||
|
||
Each asset item should show:
|
||
|
||
- Asset name
|
||
- Existing checked state for current scene
|
||
|
||
Author actions:
|
||
|
||
- Tick asset to add scene usage.
|
||
- Untick asset to remove scene usage.
|
||
- Save changes.
|
||
|
||
### Location Checklist
|
||
|
||
Displays locations from the current project/book.
|
||
|
||
Each location item should show:
|
||
|
||
- Location name
|
||
- Existing checked state for current scene
|
||
|
||
Author actions:
|
||
|
||
- Tick location to add scene association.
|
||
- Untick location to remove scene association.
|
||
- Save changes.
|
||
|
||
---
|
||
|
||
## Scene Link Detail Level
|
||
|
||
The first version should keep associations simple.
|
||
|
||
For example:
|
||
|
||
```text
|
||
Character appears in scene.
|
||
Asset is used or mentioned in scene.
|
||
Location is associated with scene.
|
||
```
|
||
|
||
Do not require detailed involvement classification in the Word add-in.
|
||
|
||
More detailed classification can remain in PlotDirector.
|
||
|
||
Examples of details that should stay in PlotDirector:
|
||
|
||
- POV character.
|
||
- Present vs mentioned only.
|
||
- Active participant vs background.
|
||
- Asset owner.
|
||
- Asset state.
|
||
- Character location state.
|
||
- Relationship changes.
|
||
|
||
The add-in should provide fast capture, not detailed modelling.
|
||
|
||
---
|
||
|
||
## API Requirements
|
||
|
||
The feature requires a small API surface in PlotDirector.
|
||
|
||
All endpoints must require authentication and must validate project/book access.
|
||
|
||
The exact route names can be adjusted to match PlotDirector conventions.
|
||
|
||
---
|
||
|
||
# API Design
|
||
|
||
## Authentication
|
||
|
||
The add-in should authenticate against PlotDirector.
|
||
|
||
Possible approaches:
|
||
|
||
1. Existing web login session if hosted under the same domain.
|
||
2. OAuth-style flow.
|
||
3. Device code flow.
|
||
4. Personal access token.
|
||
5. Add-in-specific API token.
|
||
|
||
For MVP, if feasible, use the existing PlotDirector authentication mechanism with secure cookies and HTTPS.
|
||
|
||
If cookie authentication is awkward inside the Office task pane, introduce add-in tokens.
|
||
|
||
Recommended long-term approach:
|
||
|
||
```text
|
||
Add-in-specific access tokens scoped to the user and project.
|
||
```
|
||
|
||
Tokens should be revocable from the user’s PlotDirector account page.
|
||
|
||
---
|
||
|
||
## Endpoint: Get User Projects
|
||
|
||
```http
|
||
GET /api/word/projects
|
||
```
|
||
|
||
Returns projects available to the signed-in user.
|
||
|
||
Example response:
|
||
|
||
```json
|
||
{
|
||
"projects": [
|
||
{
|
||
"projectId": 12,
|
||
"title": "The Alpha Flame"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Endpoint: Get Project Books
|
||
|
||
```http
|
||
GET /api/word/projects/{projectId}/books
|
||
```
|
||
|
||
Returns books in the selected project.
|
||
|
||
Example response:
|
||
|
||
```json
|
||
{
|
||
"books": [
|
||
{
|
||
"bookId": 4,
|
||
"title": "The Alpha Flame: Reckoning",
|
||
"sortOrder": 2
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Endpoint: Get Book Structure
|
||
|
||
```http
|
||
GET /api/word/books/{bookId}/structure
|
||
```
|
||
|
||
Returns chapters and scenes for the selected book.
|
||
|
||
Example response:
|
||
|
||
```json
|
||
{
|
||
"bookId": 4,
|
||
"chapters": [
|
||
{
|
||
"chapterId": 101,
|
||
"title": "Chapter 1: Echoes of the Past",
|
||
"sortOrder": 1,
|
||
"scenes": [
|
||
{
|
||
"sceneId": 5001,
|
||
"title": "Scene 1: The Memory Tin",
|
||
"sortOrder": 1,
|
||
"revisionStatus": "Outlined",
|
||
"estimatedWords": 1800,
|
||
"actualWords": 0
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Endpoint: Get Scene Companion Data
|
||
|
||
```http
|
||
GET /api/word/scenes/{sceneId}/companion
|
||
```
|
||
|
||
Returns everything needed to populate the side panel for one scene.
|
||
|
||
Example response:
|
||
|
||
```json
|
||
{
|
||
"sceneId": 5001,
|
||
"chapterId": 101,
|
||
"chapterTitle": "Chapter 1: Echoes of the Past",
|
||
"sceneTitle": "Scene 1: The Memory Tin",
|
||
"actualWords": 1248,
|
||
"estimatedWords": 1800,
|
||
"writingBrief": "Beth searches through the memory tin and realises the poem may contain a clue.",
|
||
"blocked": false,
|
||
"blockedReason": null,
|
||
"characters": [
|
||
{
|
||
"characterId": 22,
|
||
"name": "Beth",
|
||
"linked": true
|
||
},
|
||
{
|
||
"characterId": 23,
|
||
"name": "Maggie",
|
||
"linked": false
|
||
}
|
||
],
|
||
"assets": [
|
||
{
|
||
"assetId": 8,
|
||
"name": "Memory tin",
|
||
"linked": true
|
||
}
|
||
],
|
||
"locations": [
|
||
{
|
||
"locationId": 5,
|
||
"name": "Grace",
|
||
"linked": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Endpoint: Resolve Scene by Titles
|
||
|
||
```http
|
||
POST /api/word/books/{bookId}/resolve-scene
|
||
```
|
||
|
||
Used when the add-in has chapter and scene titles but not a SceneID.
|
||
|
||
Request:
|
||
|
||
```json
|
||
{
|
||
"chapterTitle": "Chapter 1: Echoes of the Past",
|
||
"sceneTitle": "Scene 1: The Memory Tin"
|
||
}
|
||
```
|
||
|
||
Response:
|
||
|
||
```json
|
||
{
|
||
"matched": true,
|
||
"chapterId": 101,
|
||
"sceneId": 5001,
|
||
"matchType": "ExactTitle"
|
||
}
|
||
```
|
||
|
||
If not matched:
|
||
|
||
```json
|
||
{
|
||
"matched": false
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Endpoint: Sync Current Scene
|
||
|
||
```http
|
||
POST /api/word/books/{bookId}/sync-scene
|
||
```
|
||
|
||
Creates or updates one chapter/scene and updates actual word count.
|
||
|
||
Request:
|
||
|
||
```json
|
||
{
|
||
"chapterTitle": "Chapter 1: Echoes of the Past",
|
||
"chapterSortOrder": 1,
|
||
"sceneTitle": "Scene 1: The Memory Tin",
|
||
"sceneSortOrder": 1,
|
||
"actualWords": 1248,
|
||
"documentId": "word-doc-abc123",
|
||
"contentHash": "optional-hash"
|
||
}
|
||
```
|
||
|
||
Response:
|
||
|
||
```json
|
||
{
|
||
"chapterId": 101,
|
||
"sceneId": 5001,
|
||
"chapterCreated": false,
|
||
"sceneCreated": false,
|
||
"actualWordsUpdated": true,
|
||
"message": "Scene synced successfully."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Endpoint: Sync Full Manuscript Structure
|
||
|
||
```http
|
||
POST /api/word/books/{bookId}/sync-manuscript
|
||
```
|
||
|
||
Creates missing chapters/scenes and updates actual word counts.
|
||
|
||
Request:
|
||
|
||
```json
|
||
{
|
||
"documentId": "word-doc-abc123",
|
||
"chapters": [
|
||
{
|
||
"title": "Chapter 1: Echoes of the Past",
|
||
"sortOrder": 1,
|
||
"wordCount": 4260,
|
||
"scenes": [
|
||
{
|
||
"title": "Scene 1: The Memory Tin",
|
||
"sortOrder": 1,
|
||
"wordCount": 1800,
|
||
"contentHash": "optional-hash"
|
||
},
|
||
{
|
||
"title": "Scene 2: St Luke's",
|
||
"sortOrder": 2,
|
||
"wordCount": 2460,
|
||
"contentHash": "optional-hash"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Response:
|
||
|
||
```json
|
||
{
|
||
"chaptersCreated": 1,
|
||
"chaptersUpdated": 4,
|
||
"scenesCreated": 3,
|
||
"scenesUpdated": 18,
|
||
"itemsNotMatched": [],
|
||
"message": "Manuscript sync completed."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Endpoint: Update Scene Links
|
||
|
||
```http
|
||
PUT /api/word/scenes/{sceneId}/links
|
||
```
|
||
|
||
Updates character, asset and location associations for a scene.
|
||
|
||
Request:
|
||
|
||
```json
|
||
{
|
||
"characterIds": [22, 23],
|
||
"assetIds": [8],
|
||
"locationIds": [5]
|
||
}
|
||
```
|
||
|
||
Response:
|
||
|
||
```json
|
||
{
|
||
"sceneId": 5001,
|
||
"charactersUpdated": 2,
|
||
"assetsUpdated": 1,
|
||
"locationsUpdated": 1,
|
||
"message": "Scene links updated."
|
||
}
|
||
```
|
||
|
||
The server should treat this as the selected set from the add-in.
|
||
|
||
If detailed link records exist, the server should preserve fields not controlled by the add-in wherever possible.
|
||
|
||
---
|
||
|
||
## Endpoint: Update Scene Word Count
|
||
|
||
```http
|
||
PATCH /api/word/scenes/{sceneId}/word-count
|
||
```
|
||
|
||
Request:
|
||
|
||
```json
|
||
{
|
||
"actualWords": 1248
|
||
}
|
||
```
|
||
|
||
Response:
|
||
|
||
```json
|
||
{
|
||
"sceneId": 5001,
|
||
"actualWords": 1248,
|
||
"message": "Word count updated."
|
||
}
|
||
```
|
||
|
||
This endpoint may be optional if word count updates are always included in sync calls.
|
||
|
||
---
|
||
|
||
## Data Model Changes
|
||
|
||
The MVP may only require minor database additions.
|
||
|
||
Suggested additions:
|
||
|
||
### Scene Sync Metadata
|
||
|
||
If not already present, add fields to scenes:
|
||
|
||
```text
|
||
ActualWords
|
||
LastSyncedFromWordUtc
|
||
WordDocumentId
|
||
WordContentHash
|
||
```
|
||
|
||
Some of these may already exist in PlotDirector.
|
||
|
||
If so, reuse existing fields.
|
||
|
||
### Add-in Connection / Token Table
|
||
|
||
If API tokens are used:
|
||
|
||
```text
|
||
UserWordAddInTokens
|
||
```
|
||
|
||
Suggested fields:
|
||
|
||
```text
|
||
TokenID
|
||
UserID
|
||
TokenHash
|
||
CreatedUtc
|
||
LastUsedUtc
|
||
RevokedUtc
|
||
DeviceName
|
||
```
|
||
|
||
Do not store raw tokens.
|
||
|
||
### Sync History
|
||
|
||
Optional but useful:
|
||
|
||
```text
|
||
WordSyncHistory
|
||
```
|
||
|
||
Suggested fields:
|
||
|
||
```text
|
||
SyncHistoryID
|
||
UserID
|
||
ProjectID
|
||
BookID
|
||
DocumentID
|
||
SyncType
|
||
StartedUtc
|
||
CompletedUtc
|
||
ChaptersCreated
|
||
ChaptersUpdated
|
||
ScenesCreated
|
||
ScenesUpdated
|
||
WordCountsUpdated
|
||
ErrorMessage
|
||
```
|
||
|
||
This helps with diagnostics.
|
||
|
||
---
|
||
|
||
## Stored Procedures
|
||
|
||
Depending on existing PlotDirector conventions, add or update stored procedures for:
|
||
|
||
- Getting user projects available to the add-in.
|
||
- Getting project books.
|
||
- Getting book structure.
|
||
- Resolving a chapter/scene by title.
|
||
- Creating a missing chapter.
|
||
- Creating a missing scene.
|
||
- Updating scene actual word count.
|
||
- Updating scene sync metadata.
|
||
- Getting scene companion data.
|
||
- Updating scene character links.
|
||
- Updating scene asset links.
|
||
- Updating scene location links.
|
||
- Inserting sync history.
|
||
|
||
All database changes should follow the established migration policy:
|
||
|
||
- Do not modify committed migration scripts.
|
||
- Add new migration scripts.
|
||
- Stored procedure changes should use `ALTER PROCEDURE`.
|
||
- Seed data must be idempotent.
|
||
- New installations run all migrations in order.
|
||
- Existing installations run only new migrations.
|
||
|
||
---
|
||
|
||
## Security Considerations
|
||
|
||
### Authentication
|
||
|
||
All API endpoints must require authentication.
|
||
|
||
The add-in must never expose unrestricted project or book data.
|
||
|
||
### Authorisation
|
||
|
||
Each endpoint must verify:
|
||
|
||
- The authenticated user has access to the project.
|
||
- The selected book belongs to a project the user can access.
|
||
- The requested scene belongs to that book/project.
|
||
- The requested character/asset/location IDs belong to the same project or valid scope.
|
||
|
||
### HTTPS
|
||
|
||
The add-in and API should run over HTTPS.
|
||
|
||
Office add-ins generally require secure origins.
|
||
|
||
### CSRF
|
||
|
||
If cookie authentication is used, CSRF protection must be handled properly.
|
||
|
||
For API token authentication, CSRF risk is reduced, but token storage becomes important.
|
||
|
||
### Token Storage
|
||
|
||
If the add-in uses tokens:
|
||
|
||
- Store tokens securely.
|
||
- Store only token hashes server-side.
|
||
- Allow users to revoke tokens.
|
||
- Scope tokens to the authenticated user.
|
||
- Consider scoping tokens to specific projects later.
|
||
|
||
### Data Protection
|
||
|
||
The add-in should not upload full manuscript text in the MVP.
|
||
|
||
It should upload:
|
||
|
||
- Chapter titles.
|
||
- Scene titles.
|
||
- Word counts.
|
||
- Optional content hashes.
|
||
|
||
This avoids privacy concerns and keeps sync lightweight.
|
||
|
||
---
|
||
|
||
## Performance Considerations
|
||
|
||
The add-in should feel quick.
|
||
|
||
Avoid:
|
||
|
||
- Full manuscript parsing on every cursor move.
|
||
- Heavy document reads during selection change events.
|
||
- Fuzzy matching inside Word.
|
||
- Entity detection inside Word.
|
||
- Large API calls during typing.
|
||
- Blocking modal workflows.
|
||
|
||
Recommended approach:
|
||
|
||
- Use explicit sync buttons.
|
||
- Use debounced current scene detection.
|
||
- Cache project/book lists in the task pane.
|
||
- Cache character/asset/location lists for the selected book/project.
|
||
- Fetch scene companion data only when the current scene changes.
|
||
- Keep Office.js calls small and deliberate.
|
||
- Perform heavier matching and validation server-side.
|
||
|
||
The side panel should behave like a lightweight helper, not a background process constantly inspecting the document.
|
||
|
||
---
|
||
|
||
## Error Handling
|
||
|
||
The add-in should show clear, concise messages.
|
||
|
||
Examples:
|
||
|
||
```text
|
||
Could not detect a scene. Use Heading 2 for scene titles.
|
||
```
|
||
|
||
```text
|
||
You are not connected to PlotDirector.
|
||
```
|
||
|
||
```text
|
||
This book could not be found.
|
||
```
|
||
|
||
```text
|
||
Sync failed. Please try again.
|
||
```
|
||
|
||
```text
|
||
Scene links saved.
|
||
```
|
||
|
||
For detailed errors, use a collapsible diagnostics section or developer log mode.
|
||
|
||
Do not expose raw stack traces to users.
|
||
|
||
---
|
||
|
||
## UX Rules
|
||
|
||
The add-in should follow these rules:
|
||
|
||
1. Do not interrupt the author while typing.
|
||
2. Do not show large modal workflows during writing.
|
||
3. Do not ask users to confirm every minor update.
|
||
4. Do not delete planning data.
|
||
5. Do not silently overwrite scene briefs.
|
||
6. Do not duplicate full PlotDirector pages inside Word.
|
||
7. Keep the panel narrow and readable.
|
||
8. Prefer checklists and single-click actions.
|
||
9. Show a clear last sync time.
|
||
10. Provide links back to PlotDirector for deeper editing.
|
||
|
||
---
|
||
|
||
## Suggested Implementation Phases
|
||
|
||
## Phase W1 – API Foundation
|
||
|
||
Build the PlotDirector API required by the add-in.
|
||
|
||
Deliverables:
|
||
|
||
- Authenticated API area for Word Companion.
|
||
- Get projects endpoint.
|
||
- Get books endpoint.
|
||
- Get book structure endpoint.
|
||
- Resolve scene by title endpoint.
|
||
- Get scene companion data endpoint.
|
||
- Sync current scene endpoint.
|
||
- Sync full manuscript endpoint.
|
||
- Update scene links endpoint.
|
||
- Optional word count endpoint.
|
||
- Database changes for sync metadata if needed.
|
||
- Sync history table if desired.
|
||
|
||
Testing:
|
||
|
||
- Verify unauthorised access is rejected.
|
||
- Verify users cannot access another user’s projects.
|
||
- Verify chapters/scenes are created only when missing.
|
||
- Verify existing PlotDirector-only scenes are not deleted.
|
||
- Verify word counts update correctly.
|
||
- Verify scene links update correctly.
|
||
|
||
---
|
||
|
||
## Phase W2 – Add-in Shell
|
||
|
||
Create the Word add-in project and basic task pane.
|
||
|
||
Deliverables:
|
||
|
||
- Office add-in manifest.
|
||
- Task pane UI shell.
|
||
- PlotDirector connection screen.
|
||
- Project selector.
|
||
- Book selector.
|
||
- Stored selected project/book in add-in state.
|
||
- Basic API connectivity test.
|
||
- Friendly connection status.
|
||
|
||
Testing:
|
||
|
||
- Add-in loads in Word.
|
||
- User can connect to PlotDirector.
|
||
- User can select project and book.
|
||
- API failures are handled cleanly.
|
||
|
||
---
|
||
|
||
## Phase W3 – Document Structure Detection
|
||
|
||
Add Office.js document reading.
|
||
|
||
Deliverables:
|
||
|
||
- Detect Heading 1 chapters.
|
||
- Detect Heading 2 scenes.
|
||
- Detect current chapter/scene from cursor position.
|
||
- Display current chapter and scene in the panel.
|
||
- Calculate current scene word count.
|
||
- Manual refresh button.
|
||
|
||
Testing:
|
||
|
||
- Works with normal chapter/scene headings.
|
||
- Handles cursor outside any scene.
|
||
- Handles missing Heading 1.
|
||
- Handles missing Heading 2.
|
||
- Handles empty scenes.
|
||
- Performs acceptably on long manuscripts.
|
||
|
||
---
|
||
|
||
## Phase W4 – Current Scene Companion Panel
|
||
|
||
Connect detected scene to PlotDirector.
|
||
|
||
Deliverables:
|
||
|
||
- Resolve detected chapter/scene to PlotDirector IDs.
|
||
- Display scene writing brief.
|
||
- Display estimated and actual words.
|
||
- Display blocked status and blocked reason if useful.
|
||
- Provide **Open Scene in PlotDirector** link.
|
||
- Provide **Sync Current Scene** button.
|
||
|
||
Testing:
|
||
|
||
- Existing scenes resolve correctly.
|
||
- Missing scenes can be created through sync.
|
||
- Word count updates correctly.
|
||
- Brief displays read-only.
|
||
- Link opens correct PlotDirector page.
|
||
|
||
---
|
||
|
||
## Phase W5 – Scene Links
|
||
|
||
Add character, asset and location checklists.
|
||
|
||
Deliverables:
|
||
|
||
- Fetch characters for current project/book.
|
||
- Fetch assets for current project/book.
|
||
- Fetch locations for current project/book.
|
||
- Display checked state for current scene.
|
||
- Save selected links back to PlotDirector.
|
||
- Show success/failure message.
|
||
|
||
Testing:
|
||
|
||
- Existing scene links load correctly.
|
||
- Ticking a character creates the appearance/link.
|
||
- Unticking removes the appearance/link.
|
||
- Asset links update correctly.
|
||
- Location links update correctly.
|
||
- Invalid IDs are rejected server-side.
|
||
|
||
---
|
||
|
||
## Phase W6 – Full Manuscript Sync
|
||
|
||
Allow the author to sync the full document structure.
|
||
|
||
Deliverables:
|
||
|
||
- Read all Heading 1 chapters.
|
||
- Read all Heading 2 scenes.
|
||
- Count words.
|
||
- Send full structure to PlotDirector.
|
||
- Create missing chapters.
|
||
- Create missing scenes.
|
||
- Update word counts.
|
||
- Show sync summary.
|
||
|
||
Testing:
|
||
|
||
- Creates missing chapters.
|
||
- Creates missing scenes.
|
||
- Does not delete existing PlotDirector-only scenes.
|
||
- Updates word counts.
|
||
- Handles duplicate heading names gracefully.
|
||
- Handles long manuscripts without freezing Word noticeably.
|
||
|
||
---
|
||
|
||
## Phase W7 – Refinement and Hardening
|
||
|
||
Polish the feature for real usage.
|
||
|
||
Deliverables:
|
||
|
||
- Better loading states.
|
||
- Better error handling.
|
||
- Caching project/book/entity lists.
|
||
- Last sync status.
|
||
- Sync history view in PlotDirector.
|
||
- User-facing documentation.
|
||
- Developer diagnostics mode.
|
||
- Add-in token revocation if tokens are used.
|
||
- Deployment packaging.
|
||
|
||
Testing:
|
||
|
||
- Test against several real manuscripts.
|
||
- Test poor network behaviour.
|
||
- Test expired authentication.
|
||
- Test large book documents.
|
||
- Test duplicate chapter/scene titles.
|
||
- Test renamed scenes.
|
||
- Test copy/pasted chapters.
|
||
|
||
---
|
||
|
||
## Future Enhancements
|
||
|
||
Possible later additions:
|
||
|
||
- Stable hidden chapter/scene IDs inside Word.
|
||
- Optional editing of scene brief from Word.
|
||
- Optional quick notes from Word.
|
||
- Optional manuscript text analysis.
|
||
- Suggested character/asset/location links.
|
||
- Continuity warning suggestions.
|
||
- Writing schedule progress integration.
|
||
- Sync of selected scene only on save.
|
||
- Multi-document book support.
|
||
- Scrivener or Google Docs integration.
|
||
- Add-in marketplace publication.
|
||
|
||
These should not be included until the lightweight companion workflow has proven useful.
|
||
|
||
---
|
||
|
||
## Recommended MVP Scope
|
||
|
||
The recommended MVP is:
|
||
|
||
1. Side panel loads in Word.
|
||
2. User connects to PlotDirector.
|
||
3. User selects project and book.
|
||
4. Add-in detects current chapter and scene using headings.
|
||
5. Add-in displays read-only scene writing brief.
|
||
6. Add-in displays character, asset and location checklists.
|
||
7. User can save scene links.
|
||
8. User can sync current scene word count.
|
||
9. User can sync all chapters/scenes.
|
||
10. PlotDirector creates missing chapters/scenes but deletes nothing.
|
||
|
||
This gives immediate practical value while keeping the feature focused.
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
The Microsoft Word Companion Add-in should make PlotDirector feel closer to the writing process without moving PlotDirector’s planning responsibilities into Word.
|
||
|
||
The add-in should be:
|
||
|
||
- Lightweight.
|
||
- Fast.
|
||
- Focused.
|
||
- Safe.
|
||
- Side-by-side with the manuscript.
|
||
- Useful during drafting.
|
||
|
||
The API should provide a secure and narrow bridge between Word and PlotDirector.
|
||
|
||
The first version should focus on:
|
||
|
||
- Scene brief visibility.
|
||
- Chapter/scene sync.
|
||
- Word count sync.
|
||
- Character/asset/location association.
|
||
|
||
The central rule is:
|
||
|
||
> **The add-in helps the author write. PlotDirector remains the source of planning truth.**
|