Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions doc/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,10 @@ An object is a folder holding **`object.json`** (`$defs/object`):
- **Pine Computer changes an object only in a turn that works on that object.** It plans, draws or rewrites that object itself: never as a side effect of another object changing, and never when it reads one. So a field the person set (`objects_sent_by_draw_request`, `relations`, `variant_of`, the text files) stays as they set it until they, or a turn that works on that object, change it. History keeps both.
- **References that no longer resolve.** A listed object may be deleted later, and a reference may point back at its own object, directly or through others. Both are allowed in the data. A draw sends the shown files of the listed objects that exist, in order, and Pine Computer tells the person each one it could not send (4.4). It refuses nothing. A draw sends files, not a graph, so a cycle sends each file once, as listed.
- **Who creates objects.** Either side may create an object. The client creates one when the person adds it, with `object.json` and the person's `description.md`. drama-cli derives every name a model reads from `name`, never from the id.
- **The person's text.** In an object's folder, `description.md` and `prompt.md`, when present, are the text the person and Pine Computer edit. Whoever writes last wins, and git keeps the earlier text.
- **One editable text per object.** The person and Pine Computer are equal writers of it: whoever writes last wins, and git keeps the earlier text. No side rewrites it as a side effect of drawing.
- A `character`, `scene`, `prop` or `variant` has `description.md`. Its draw composes the prompt from it, so it has no `prompt.md`; the prompt a draw sent is in its receipt (`prompt_sent`, 2.3). A character's outfit and a prop's printed words are part of the description (`Outfit: …`; `It shows the words "…".`). `entry.json` beside it keeps the asset's other story facts, which drama-cli reads and no card edits.
- A `character_face`, `scene_floor_plan` or `scene_view` has neither: it is drawn from its owner's description, and the variant's change for a variant's view.
- A `keyframe`, `storyboard` or `take` has `prompt.md` only as an override, which its draw sends as written. Without one, the draw composes the prompt. Removing it ("Use the automatic prompt") returns to that.
- **Removal.** Removing an object deletes its folder; a variant is a folder below its asset's, so it goes with it.

### 2.3 Receipts
Expand Down Expand Up @@ -113,7 +116,7 @@ Pine Computer keeps its own records of the drama in **`pine-computer-records/`**
- an `object.json` field (`objects_sent_by_draw_request`, `relations`, `variant_of`, `name`);
- adding an object, which writes its folder with `object.json` and `description.md`;
- removing an object, which deletes its folder;
- `description.md` or `prompt.md`;
- `description.md`, or the `prompt.md` of a keyframe, storyboard or take, or its removal (2.2);
- the person's own picture or video, below.
- **Canvas positions** and every other view state are the client's own, per person or per profile, and are never written into the drama.
- **Hand changes** (a folder client): a file changed outside the client is recorded as `client-found-changes-on-disk` at the next opening, before the next turn, or at a running turn's next collection (4.3).
Expand Down Expand Up @@ -188,7 +191,10 @@ A turn ends as Pine reports it ([agent turns](https://console.pinecomputer.io/do
## 5. What the client shows

- **The cards** show what the client holds: each object's `object.json`, its `shown_file` and its receipts. A file's history is every earlier content of it (2.1; in git, `git log` of the path).
- **"Use" on a past result** restores the files that result's change wrote inside the object's own folder, receipts with them, as a `person` change. That is the change's commit in git; for a turn's, the commit of the collection that landed it, which carries the turn's `Pine-Turn-Id`. Files of a variant or any other object folded inside it are not included, since each is an object of its own. Files the same change wrote for other objects stay as they are. The rule is the same whoever made the change: a turn, the person, or `client-found-changes-on-disk`, which may hold the whole project. The restored result's file is the shown one again: `object.json` `shown_file` names it, and a current shown file of another name is deleted with its receipt in the same change, as for the person's own picture (3). Use restores only the files that result's change wrote: a file a later result added beside them, such as a take's last frame, stays.
- **"Use" on a past result** brings the object's own folder back as it was at that result, as a `person` change: the result is the commit that first wrote that shown file (in git; for a turn's, the commit of the collection that landed it, which carries the turn's `Pine-Turn-Id`).
- Every file of the folder then comes back, receipts with them, `description.md` and `entry.json` too, and a file the folder holds now but did not then is deleted.
- `object.json` stays the current one, with that result's `shown_file`. On a keyframe, storyboard or take, that result's `objects_sent_by_draw_request` comes back too, since its `prompt.md` names its images by that list; its `prompt.md` follows the folder, present or absent.
- Files of a variant or any other object folded inside it are not included, since each is an object of its own, and nothing outside the folder changes. The rule is the same whoever made the result: a turn, the person, or `client-found-changes-on-disk`.

## 6. Majors and upgrades

Expand Down
5 changes: 2 additions & 3 deletions doc/quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Your reply is the go: nothing at a stop asks you to approve item by item.

| Stop | You look at | Your choice |
|---|---|---|
| 1 | The planned asset cards, each with its prompt | Add, remove or change an asset, in one sentence |
| 1 | The planned asset cards, each with its description | Add, remove or change an asset, in one sentence |
| 2 | The drawn assets, with what the agent found | The leads' looks |
| 3 | The episode's shot list and its planned cards | Revise it, or go |
| 4 | Storyboards, keyframes, video prompts, and the estimated video cost | Shoot everything, or hold some back |
Expand All @@ -55,7 +55,7 @@ The agent also stops for a red line in the screenplay, and for a screenplay it r
| Place | What's there | What you do |
|---|---|---|
| **Right: Chat** | The agent | Ask, answer, say go, press Stop |
| **Center: canvas** | One canvas for the assets, one per episode | Edit a card's prompt, drop your picture on it, click an old version and press **Use** |
| **Center: canvas** | One canvas for the assets, one per episode | Edit a card's description (an episode card: its prompt), drop your picture on it, click an old version and press **Use** |
| **Center: galleries** | Characters, places, props | **Create New**; click a card to see it on the canvas |
| **Center: seg editor** | An episode's segments and takes | Play takes; **Generate** writes the request into the Chat for you to send |
| **Left: Production** | The project and each object's versions | Look and open only |
Expand Down Expand Up @@ -95,7 +95,6 @@ How and why: [architecture](architecture.md).
| You answer hours after a question | The Computer may have stopped | Send your answer; the agent starts again from your folder |
| The Chat is dead after Stop | Known bug | Run **Developer: Reload Window** |
| A card you made with Create New can't be drawn | Its name has a space, dash or accent (known bug) | Use a name in plain letters a–z, or ask the agent to add it |
| The redraw ignored your new description | A card is drawn from its prompt | Edit the card's prompt, or tell the agent what to change |
| A turn failed | What it made still lands; Pine gives the reason | Ask the agent to go on |

## 6. FAQ
Expand Down
47 changes: 25 additions & 22 deletions extensions/pine-drama/canvas/canvas.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -283,15 +283,14 @@ const notYet = 'Not available yet';

/**
* The composer: one floating dialog under the picked card, the same on both canvases (the person's design). A top row
* (Upload, + Variant, Reference, Style, Full prompt), the references, the text specific to this picture, and a bottom
* bar (model, settings, Generate). An asset's text is its description, its full prompt one click away; an episode
* card's is its prompt, the only text it has; a storyboard has none. The text is for the next draw, so a picture the
* person uploaded keeps it; how the picture on the card was made (its receipt; none for an upload) is behind "How it
* was made". The model and settings are greyed, as the Computer cannot take a choice yet.
* (Upload, + Variant, Reference, Style, Full prompt), the references, an asset's one editable text, its description,
* and a bottom bar (model, settings, Generate). Its full prompt, the one its last draw sent, is read only; a keyframe's,
* a storyboard's or a take's own prompt can only be removed here (doc/protocol.md 2.2). How the picture on the card was
* made (its receipt) is behind "How it was made". The model and settings are greyed, as the Computer cannot take a choice yet.
*/
function Composer({ card, reply, onGo, onClose }: { card: CanvasCard; reply: DetailMessage | undefined; onGo: (stageId: string) => void; onClose: () => void }) {
const record = reply?.record ?? null;
const prompt = reply?.prompt ?? null;
const ownPrompt = reply?.ownPrompt ?? null;
const [draft, setDraft] = useState<{ name: string; text: string } | null>(null);
const [full, setFull] = useState(false);
const [outcome, setOutcome] = useState<{ key: string; busy: boolean; error: string | null; unchanged: string | null } | null>(null);
Expand All @@ -311,16 +310,12 @@ function Composer({ card, reply, onGo, onClose }: { card: CanvasCard; reply: Det
};
const description = useTextEdit(`describe:${card.id}`, record?.description ?? null, busy, act,
text => ({ action: 'describe', object: card.id, description: record?.description ?? '', text }));
const promptEdit = useTextEdit(`prompt:${card.id}`, prompt?.text ?? null, busy, act, text => ({ action: 'prompt', object: prompt?.object ?? card.id, text }));
// The picture shown is the person's own upload: it was made from no prompt.
// An asset's own text is its description, its full prompt behind Full prompt; an episode card's is its prompt, the only
// text it has (the person's decision). One text is edited at a time, so Save and Generate act on the one shown.
const main = record ? (full ? promptEdit : description) : prompt?.text != null ? promptEdit : null;
const fullPrompt = reply?.detail?.prompt ?? 'Composed when drawn';
// What its next draw sends, Image 1..N: the one list the draw builds its request from (objects_sent_by_draw_request).
const references = reply?.nextDraw ?? [];
const generate = () => {
if (!main || main.blank) { return; }
if (main.save()) { generateOnceSaved.set(main.key, card.id); } else { post({ v: CANVAS_PROTOCOL, type: 'generate', stageId: card.id }); }
if (record && description.blank) { return; }
if (record && description.save()) { generateOnceSaved.set(description.key, card.id); } else { post({ v: CANVAS_PROTOCOL, type: 'generate', stageId: card.id }); }
};
const addVariant = () => record && draft && draft.name.trim() && draft.text.trim() && !busy
&& act({ key: `variant:${card.id}`, request: { action: 'add', type: 'variant', from: card.id, name: draft.name.trim(), text: draft.text.trim() } });
Expand All @@ -338,8 +333,8 @@ function Composer({ card, reply, onGo, onClose }: { card: CanvasCard; reply: Det
<button className="chip-button" disabled title={notYet}>Style</button>
<span className="spacer" />
{card.segment && <button className="quiet" onClick={() => post({ v: CANVAS_PROTOCOL, type: 'segEditor', seg: card.segment })} title={`Open ${card.segment} in the seg editor`}>Seg editor ⤢</button>}
{record && prompt?.text != null && <button className="quiet" aria-expanded={full} disabled={main?.changed} onClick={() => setFull(v => !v)}
title={main?.changed ? 'Save or cancel your edit first' : full ? 'Back to its description' : 'The whole prompt its next draw sends'}>{full ? 'Description ⤡' : 'Full prompt ⤢'}</button>}
{record && <button className="quiet" aria-expanded={full} disabled={description.changed} onClick={() => setFull(v => !v)}
title={description.changed ? 'Save or cancel your edit first' : full ? 'Back to its description' : 'The whole prompt its last draw sent, composed from the description'}>{full ? 'Description ⤡' : 'Full prompt ⤢'}</button>}
<button className="icon" onClick={onClose} title="Close (Esc)" aria-label="Close"><span className="codicon codicon-close" /></button>
</div>
{references.length > 0 && (
Expand All @@ -350,13 +345,22 @@ function Composer({ card, reply, onGo, onClose }: { card: CanvasCard; reply: Det
{reply?.picture && <PictureState picture={reply.picture} busy={busy} act={act} />}
{!reply && <div className="detail-note">Reading its record…</div>}
{reply?.error && <div className="detail-note">{reply.error}</div>}
{main && <FlatText key={main.key} edit={main} busy={busy} label={!record ? 'Prompt' : full ? 'Full prompt' : 'Description'} />}
{main?.changed && (
{record && (full ? <textarea className="flat-text" readOnly value={fullPrompt} aria-label="Full prompt" />
: <FlatText key={description.key} edit={description} busy={busy} label="Description" />)}
{ownPrompt && (
<div className="composer-row">
<span className="muted">Its own prompt is used</span>
<span className="spacer" />
<button className="labeled" disabled={busy} onClick={() => act({ key: `automatic:${card.id}`, request: { action: 'automatic', object: card.id } })}
title="Remove its own prompt, so the draw composes it">Use the automatic prompt</button>
</div>
)}
{description.changed && (
<div className="composer-row">
<span className="muted">Unsaved changes · ⌘Enter to save</span>
<span className="spacer" />
<button className="labeled" disabled={busy} onClick={main.cancel} title="Discard your edit (Esc)">Cancel</button>
<button className="labeled" disabled={busy || main.blank} onClick={main.save}>Save</button>
<button className="labeled" disabled={busy} onClick={description.cancel} title="Discard your edit (Esc)">Cancel</button>
<button className="labeled" disabled={busy || description.blank} onClick={description.save}>Save</button>
</div>
)}
{reply?.detail && (
Expand Down Expand Up @@ -388,9 +392,8 @@ function Composer({ card, reply, onGo, onClose }: { card: CanvasCard; reply: Det
<span className="bar-sep" />
<button className="chip-button" disabled title={notYet}>Ratio · Quality · Resolution · Count ▾</button>
<span className="spacer" />
{/* Generate draws from the text shown, so a card with none (a storyboard, a cut) offers none. */}
{main && (
<button className="generate" disabled={busy || main.blank} onClick={generate}
{(record || ownPrompt !== null) && (
<button className="generate" disabled={busy || (record !== null && description.blank)} onClick={generate}
title={`${card.kind === 'take' ? 'Shoot only this segment' : 'Draw only this picture'}: puts a request in the Chat, saving your edit first`}>
<span className="codicon codicon-arrow-up" />Generate
</button>
Expand Down
8 changes: 4 additions & 4 deletions extensions/pine-drama/canvas/seg.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -90,22 +90,22 @@ function Thumb({ poster, icon }: { poster: Poster | null; icon: string }) {
);
}

/** A seg's prompt (section 12c; Pippit's clip view; 760.png). Read-only. */
/** A seg's own prompt (section 12c; Pippit's clip view; 760.png). Read-only here; the canvas edits it. */
function PlannedView({ text }: { text: string }) {
return (
<div className="planned">
<div className="planned-head">Prompt</div>
<div className="planned-head">Your own prompt</div>
<pre className="planned-text">{text}</pre>
</div>
);
}

/** The take's prompt as its next draw sends it (prompt.md), and what the shown take was made with behind its disclosure. */
/** The take's own prompt, which its next shoot sends as written (prompt.md), else none, and what the shown take was made with behind its disclosure. */
function Prompt({ seg }: { seg: Seg }) {
return (
<section className="request">
{seg.prompt !== null ? <PlannedView text={seg.prompt} />
: <p className="muted">No prompt yet: it is written when the take is planned.</p>}
: <p className="muted">The automatic prompt: composed when the take is shot.</p>}
{seg.request && (
<details className="made">
<summary>How it was made</summary>
Expand Down
22 changes: 6 additions & 16 deletions extensions/pine-drama/protocol/v2/major1-to-major2-conversion.json
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@
},
"writes": {
"{owner}/description.md": "the description field's text",
"{owner}/entry.json": "entry.json without entry_json_drop_fields and without the description field (description_field_by_owner_kind); every other field (look, members, establishing, …) stays"
"{owner}/entry.json": "entry.json without entry_json_drop_fields and without the description field (description_field_by_owner_kind); every other field (look, members, establishing, …) stays, until a character's look and a prop's text move into its description.md, after the person's pending text (pending_text): the one-editable-text merge (doc/protocol.md 2.2)"
},
"also_gives": "the fields of {owner}'s object.json (see object_json)",
"entry_json_drop_fields": [
Expand All @@ -49,8 +49,7 @@
"setting",
"inside_of",
"appears_in",
"from",
"text"
"from"
],
"kind_folder_to_type": {
"characters": "character",
Expand Down Expand Up @@ -90,16 +89,6 @@
}
}
},
{
"v1_object_ends_with": "/prompts",
"owner": "the prompts folder's parent ({owner})",
"operation": "extract_json_field_to_markdown",
"reads": "prompt.json",
"field": "text",
"writes": {
"{owner}/prompt.md": "the field's text"
}
},
{
"v1_object_ends_with": "/describe",
"owner": "the describe folder's parent ({owner})",
Expand Down Expand Up @@ -183,14 +172,15 @@
],
"dropped_wherever_they_are": [
"understanding",
"asset-library"
"asset-library",
"prompts"
],
"dropped_wherever_they_are_note": "folders of these names, at any depth (the root, an episode, a variant): drama-cli's own records of major 1, its understand calls and its asset-library uploads; drama-cli of major 2 keeps such records in pine-computer-records/ and reads none of these (kept in the backup)"
"dropped_wherever_they_are_note": "folders of these names, at any depth (the root, an episode, a variant): drama-cli's own records of major 1, its understand calls, its asset-library uploads and its stored prompts, since every prompt is composed when drawn (doc/protocol.md 2.2); drama-cli of major 2 keeps such records in pine-computer-records/ and reads none of these (kept in the backup)"
},
"current": {
"rule": "each kept object's files are the files of its major-1 current version (major 1's 3.2: the chosen version, else the newest not discarded), and every object.json is written (see object_json); earlier versions are kept in the backup only, and the converted folder is recorded as one commit, authored client-found-changes-on-disk",
"removed_objects": "an object choices.json marks removed is deleted, with every variant under it",
"pending_text": "choices.json prompt and description fields become {object}/prompt.md and {object}/description.md"
"pending_text": "choices.json description becomes {object}/description.md; its prompt is dropped (kept in the backup), since every prompt is composed when drawn"
},
"snapshots": {
"read_from": [
Expand Down
Loading
Loading