@womp/openai-plugin 0.12.0 → 0.14.0

package/README.md

@@ -45,7 +45,7 @@ src/
 | `WompBackend` | the contract the host implements |
 | `BackendRefusal` | an error whose message reaches the model as worded |
 | `CheckoutSession`, `CompleteCheckoutArgs` | ChatGPT's payment sheet: the session it takes, and what it hands `complete_checkout` |
-| `LiveView`, `ClaimLink` | what `openScene` and `claimLink` return for the design card's live view and account link |
+| `LiveView`, `ClaimLink` | what `liveView` and `claimLink` return for the design card's live view and account link |
 
 `subject` is the caller as the host established it. `onError` receives every
 error that is not a `BackendRefusal`. `instructions` is appended to the
@@ -62,13 +62,14 @@ sign-in.
 
 | Method | Does |
 |---|---|
-| `openScene(subject, { designId?, title? })` | finds the caller's design, or makes one, and opens a **build** of it; returns `{ designId, buildId, title, live? }`, `live` only from a host that can show the design live |
+| `openScene(subject, { designId?, title? })` | finds the caller's design, or makes one, and opens a **build** of it; returns `{ designId, buildId, title }` |
 | `getSceneApi()` | the scene skill, script limits, view names, and `notes` about these designs |
 | `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 |
+| `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 |
@@ -85,15 +86,16 @@ changes an earlier one.
 - **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`).
 - **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, proportions, silhouette, the material and the pieces.
+  - `<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.
-  - `<modelling>` (`modelling.ts`): building, inspecting and reviewing the scene, the Womp way and the critic pass.
+  - `<modelling>` (`modelling.ts`): building, inspecting and reviewing the scene: how Womp builds (distance fields, CSG, goop as a blend set by eye, Areas, colour across a goop join, resolution, Curves), the Womp way, detail in four layers, Womp craft recipes and the critic pass.
   - `<hardware>` (`hardware.ts`): cases for real devices: the fit model in `REFERENCE` Areas, the case around it, the build guide and the Womp price.
-  - `<printability>` (`printability.ts`): the physical object: one material, real colours, the review before finishing, how each material prints, what finish_scene and checkout_design check, and a guide to minimums while building (walls by size, protrusions and loops, details, moving and separate parts).
+  - `<printability>` (`printability.ts`): the physical object: one material, real colours, the review before finishing, how each material prints, what finish_scene and checkout_design check, a guide to minimums while building (walls by size, protrusions and loops, details, moving and separate parts), the 2 mm detail floor for small prints, and pointers to Womp's docs and published design rules.
 - **Errors.** A `BackendRefusal` message reaches the model as is. Any other error is one generic failure, reported to `onError`.
 - **Tool metadata states facts.** Descriptions, input schemas and server instructions say what a tool does, never how the model should behave. Behaviour lives in `prompts/` and reaches the model in `load_scene_skill`'s result.
 - **Every tool** declares `ui.visibility`, explicit annotation hints, and `securitySchemes: oauth2` with the `mcp:generate` scope. Tools only a card calls are `ui.visibility: ["app"]`.
 - **Card data** is the tool result's `structuredContent`, typed by the card's `data.ts`. Tools map backend types to it; a card never receives backend types. What only the card may see is in the result's `_meta`, typed by the same `data.ts`: a link that is a credential, and a quote or an order, which the model would otherwise draw as a card of its own.
+- **Live view.** `open_scene` sets `_meta.live` when the host has `liveView` and `liveViewOrigin`. The design card then offers the live view for as long as it is shown, and asks `get_live_view` for a new key each time it opens it. A result from before 0.13.0 carries a live view with its own key in `_meta.live`; the card reads it as the same offer, whether or not that key has expired.
 - **Cards** are MCP Apps resources (`text/html;profile=mcp-app`): one self-contained HTML file each, loading no script, style or font from outside, at a fixed URI, `ui://womp/<card>.html`. A ChatGPT app added while card URIs were content hashes keeps the URI of its time, `ui://womp/<card>-<hash>.html`; every such URI reads as the current card. Only the design card frames a page: the live view, on `liveViewOrigin`.
 
 ### Tools
@@ -106,6 +108,7 @@ changes an earlier one.
 | `render_scene` | model | |
 | `finish_scene` | model | |
 | `get_scene_progress` | `design` card | |
+| `get_live_view` | `design` card | |
 | `get_claim_link` | `design` card | |
 | `checkout_design` | model | shows `quote` |
 | `get_checkout_link` | `quote` card, only with `checkoutLink` | |

package/dist/index.d.ts

@@ -250,7 +250,6 @@ interface Order extends OrderSummary {
     statusUrl: string | null;
 }
 interface WompBackend {
-    /** `live` is optional: a host that cannot offer a live view leaves it out and the card shows its picture. */
     openScene(subject: string, input: {
         designId?: string;
         title?: string;
@@ -258,7 +257,6 @@ interface WompBackend {
         designId: string;
         buildId: string;
         title: string;
-        live?: LiveView;
     }>;
     getSceneApi(): Promise<SceneApi>;
     runScript(subject: string, input: {
@@ -286,6 +284,14 @@ interface WompBackend {
         designId: string;
         title: string;
     }): 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
+     * that isn't this user's is a `BackendRefusal`; undefined when there is no live view now. Without it the card offers
+     * no live view.
+     */
+    liveView?(subject: string, input: {
+        designId: string;
+    }): Promise<LiveView | undefined>;
     /** Optional: without it the card offers no account button. Undefined when no link is available now. */
     claimLink?(subject: string): Promise<ClaimLink | undefined>;
     getBuild(subject: string, input: {