@womp/openai-plugin 0.14.0 → 0.15.1

package/README.md

@@ -58,6 +58,27 @@ sign-in.
 
 ## Contract
 
+### Ownership
+
+The host knows and does; the plugin decides and speaks. Each concern has one owner.
+
+| Concern | Owner |
+|---|---|
+| Who the caller is (`subject`) | host |
+| What is on offer, and each material's finishes, colour rule, prices and print look | host |
+| What a scene measures: size, pieces, colours and their nearest Pantone coated shades, the Areas that print | host |
+| What was finished, in which material and finish (`finishedAs`) | host |
+| Designs, builds, checkouts, payments and orders, and every change to them | host |
+| The print rules: when a design can be finished or ordered (`printability.ts`) | plugin |
+| Everything the model reads: workflow, tool descriptions, results, failures and their fixes | plugin |
+| The tools: names, schemas, and which backend call each makes when | plugin |
+| What the cards show | plugin |
+
+The plugin asks the host for facts, judges them with its rules, and asks the host to act only when they pass. The host
+still guards each action, so it never stores, prices or charges anything invalid, with a short plain error and no
+advice: a guard that fires is a bug. The host words a refusal for the model (`BackendRefusal`) only with a fact the
+plugin cannot know, such as which Areas print.
+
 ### Host → plugin: `WompBackend`
 
 | Method | Does |
@@ -67,12 +88,12 @@ sign-in.
 | `runScript(subject, { designId, code, purpose })` | runs one script on the design; `purpose` becomes the current build's activity, its last screenshot or a fresh render its picture; a failed script returns `ok: false` |
 | `renderScene(subject, { designId, view?, targetId? })` | renders the design; the image also becomes the current build's picture |
 | `getMaterials(subject)` | the materials on offer to the caller, before any design exists: each with its label, whether it prints in one colour (`colorRequired`) and its finishes, the first the default; and the largest size checkout takes |
-| `analyzePrint(subject, { designId, longestSideCm?, parts? })` | the design as its scene is now, analysed as it prints at its own size, or scaled so its longest side is `longestSideCm`, changing nothing, leaving out Areas named `REFERENCE` (bought parts modelled only to show a fit); with `parts` (node ids of Areas that print), only those Areas, at the scale of the whole design: size, whether it fits the largest size, separate pieces, and the price per piece in each material on offer |
-| `finishScene(subject, { designId, title })` | marks the current build done, with this version's title; called only for a design that passed the print checks |
+| `analyzePrint(subject, { designId, longestSideCm?, parts? })` | the design as its scene is now, analysed as it prints at its own size, or scaled so its longest side is `longestSideCm`, changing nothing, leaving out Areas named `REFERENCE` (bought parts modelled only to show a fit); with `parts` (node ids of Areas that print), only those Areas, at the scale of the whole design: size, whether it fits the largest size, separate pieces, the colours on the printed parts' surfaces with the nearest Pantone coated shade of each, the material and finish the last `finishScene` gave all these parts (`finishedAs`, until a script or a new build changes the design), and the price per piece in each material on offer |
+| `finishScene(subject, { designId, title, items })` | marks the current build done, with this version's title, and prints each item `{ parts?, material, finish? }`, the Areas `parts` names or the whole design, in its material and finish: writes that look into the scene, as the web's print view shows it (a preset material's surface, in the parts' colour for a one-colour material; a full-colour material's finish over the parts' own colours), so the build's picture, the live view and every later render show the print, and records it as `analyzePrint`'s `finishedAs`; refuses a printed Area in no item or in two; called only when every item passed the print checks |
 | `liveView?(subject, { designId })` | optional: the caller's design live in 3D on `liveViewOrigin`, with a new key, made each time the design card opens its live view; a design that isn't the caller's is a `BackendRefusal`; undefined when it can't now; without it, or without `liveViewOrigin`, the design card offers no live view |
 | `claimLink?(subject)` | optional: a one-time link to a page that keeps the chat's designs in an account; without it the design card offers no button |
 | `getBuild(subject, { designId, buildId })` | a build's status, activity, title and picture; a build that isn't the caller's reads as empty |
-| `checkoutDesign(subject, { designId, items, longestSideCm?, shipTo? })` | freezes the design as quoted, at its own size or scaled to `longestSideCm`, and without its `REFERENCE` Areas, and returns the quote with one checkout link for all its `items`, each `{ parts?, material, color?, finish?, quantity? }`: the Areas `parts` names, or the whole design, priced on its own; with `shipTo`, also shipping to that address: from a host with `completeCheckout`, the order there as a payment-sheet `session`, else `shipping`, the cheapest shipping as the user's checkout on the web first offers it and the day it arrives; called only when every item passed the print checks |
+| `checkoutDesign(subject, { designId, items, longestSideCm?, shipTo? })` | freezes the design as quoted, at its own size or scaled to `longestSideCm`, and without its `REFERENCE` Areas, and returns the quote with one checkout link for all its `items`, each `{ parts?, quantity? }`: the Areas `parts` names, or the whole design, priced on its own, in the material and finish `finishScene` gave them and in their colours in the scene, each item naming the Areas it prints, also for the whole design, so the quote card lists the printed parts; with `shipTo`, also shipping to that address: from a host with `completeCheckout`, the order there as a payment-sheet `session`, else `shipping`, the cheapest shipping as the user's checkout on the web first offers it and the day it arrives; called only when every item passed the print checks |
 | `checkoutLink?(subject, { url })` | optional: `url`, a checkout link `checkoutDesign` returned, as a one-time link that for a few minutes also signs a signed-out browser in to the caller's account; undefined when it can't now; without it, or then, the quote card's Checkout opens `url` as it is |
 | `completeCheckout?(subject, payment)` | optional: charges a payment made in ChatGPT's payment sheet and places the session's order; without it there is no `complete_checkout`, and a quote to an address carries `shipping` instead of a session |
 | `getOrderStatus(subject, { orderId? })` | the caller's paid orders, newest first, and the one to show, with no name, address, email or money |
@@ -84,7 +105,7 @@ changes an earlier one.
 
 - **Identity.** Every tool acts as `subject`, the signed-in Womp account. Tool arguments and client `_meta` are never read for identity. Without a subject every tool call fails; with `wwwAuthenticate`, the failure carries that challenge in `_meta["mcp/www_authenticate"]`, so ChatGPT offers to link the account.
 - **Brief and review.** `open_scene` requires a brief (a full one for a new design, an edit brief to reopen one) and `finish_scene` the critic's review. Both stay in the chat: the backend never receives them.
-- **Print checks.** `finish_scene` and `checkout_design` take the material, finish, colour and pieces, analyse the design as it is now (`analyzePrint`) and check it (`printability.ts`): the material and finish are on offer, a material that prints in one colour has it as `#rrggbb`, the size fits, and it prints as the pieces given (1 by default). `checkout_design` takes them for each of its items and checks each item on its own: the parts it names, or the whole design. Only a design that passes is finished (`finishScene`), and only when every item passes is it quoted (`checkoutDesign`).
+- **Print checks.** `finish_scene` takes items, each the whole design or some of its parts with a material, finish and pieces; it analyses each item as it is now (`analyzePrint`) and checks it (`printability.ts`): the material and finish are on offer, in a material that prints in one colour the item's parts have one colour and it is a Pantone coated shade, the size fits, and it prints as the pieces given (1 by default); with several items, no item holds parts joined to parts in another, since joined parts print as one piece. Only when every item passes is the design finished (`finishScene`), which shows each part in its print material, so the card is the print. `checkout_design` takes items of parts, pieces and quantity, never a material: it checks each item again in the material and finish `finishScene` gave its parts (`finishedAs`), refuses parts not finished in one, checks that items naming separate parts split no joined parts, and only when every item passes is it quoted (`checkoutDesign`).
 - **Prompts** are five parts, each a template literal in its own tag, after one line on the workflow.
   - `<brief>` (`brief.ts`): what to build: research, size, parts (each hard or soft), proportions, silhouette, the style, the material and the pieces; for a likeness, a character or an object shown only in a photo, a concept image to approve and then a front, side and back turnaround as the reference.
   - `<experience>` (`experience.ts`): the user, the conversation, the card, the product shot, the order of the tools, the print checks as they reach the user.

package/dist/index.d.ts

@@ -62,15 +62,20 @@ interface MinimumOrder {
 }
 /** One material on offer for printing. */
 interface Material {
-    /** The name finish_scene and checkout_design take, such as "resin-clear-tinted". */
+    /** The name finish_scene takes, such as "resin-clear-tinted". */
     material: string;
     /** Such as "Tinted clear". */
     label: string;
-    /** The whole print is one dye colour, which the order names. */
+    /** Its parts print in one dye colour: their colour in the scene. */
     colorRequired: boolean;
     /** The finishes it is made in; the first is the default. */
     finishes: string[];
 }
+/** A material and one of its finishes; `finish` is absent for a material without finishes. */
+interface PrintMaterial {
+    material: string;
+    finish?: string;
+}
 /** One material a design can be printed in, priced per piece. */
 interface PrintOption extends Material {
     /** Per piece, before shipping. */
@@ -86,6 +91,13 @@ interface PrintAnalysis {
     sizeCm: Size;
     /** How many separate pieces it prints as. */
     pieces: number;
+    /** Each colour on the printed parts' surfaces, as #rrggbb, with the nearest Pantone coated shade's. */
+    colors: {
+        hex: string;
+        pantone: string;
+    }[];
+    /** The material and finish the last finishScene gave all these parts, until a script or a new build changes the design; absent otherwise. */
+    finishedAs?: PrintMaterial;
     /** The largest size checkout takes, in cm, in any orientation. */
     maxSizeCm: [number, number, number];
     /** Whether `sizeCm` fits within `maxSizeCm`. */
@@ -115,7 +127,7 @@ interface Checkout {
     designId: string;
     title: string;
     items: {
-        /** The names of the Areas it prints; empty for the whole design. */
+        /** The names of the Areas it prints, REFERENCE Areas left out, also for the whole design. */
         parts: string[];
         /** The item as an order lists it, such as "Tinted clear · #e11d48 · glossy · 4.0 × 3.0 × 1.0 cm". */
         summary: string;
@@ -280,9 +292,17 @@ interface WompBackend {
         longestSideCm?: number;
         parts?: number[];
     }): Promise<PrintAnalysis>;
+    /**
+     * Marks the current build done, with this version's title, and prints each item's parts, the Areas `parts` names or
+     * the whole design, in its material and finish: shows them so in the scene, its picture and live view, and records it
+     * for `analyzePrint` and `checkoutDesign`. A printed Area in no item or in two is refused.
+     */
     finishScene(subject: string, input: {
         designId: string;
         title: string;
+        items: ({
+            parts?: number[];
+        } & PrintMaterial)[];
     }): Promise<void>;
     /**
      * Optional: the design live in 3D with a new key, which the card asks for each time it opens the live view. A design
@@ -300,16 +320,14 @@ interface WompBackend {
     }): Promise<Build>;
     /**
      * Freezes the design as quoted, at `longestSideCm` when given, so its order prints it as it is now: every item in one
-     * checkout, each the Areas its `parts` names or the whole design. With `shipTo`, the quote also prices shipping there:
+     * checkout, each the Areas its `parts` names or the whole design, in the material and finish finishScene gave them and
+     * their colour in the scene. With `shipTo`, the quote also prices shipping there:
      * as a `session` from a host with `completeCheckout`, else as `shipping`.
      */
     checkoutDesign(subject: string, input: {
         designId: string;
         items: {
             parts?: number[];
-            material: string;
-            color?: string;
-            finish?: string;
             quantity?: number;
         }[];
         longestSideCm?: number;