@womp/openai-plugin 0.6.0 → 0.8.0

package/README.md

@@ -25,13 +25,15 @@ src/
   backend.ts       WompBackend: the contract the host implements
   tools/           one file per tool group (scene.ts, commerce.ts); tool.ts: shared helpers
   cards/           one folder per card (design/, quote/, order/); bridge.ts: shared host connection
+  printability.ts  the print checks finish_scene and checkout_design make
   text.ts          what tools and cards say to the model
-  prompts/         the workflow the model follows
+  prompts/         the workflow the model follows: brief.ts, experience.ts, modelling.ts, hardware.ts, printability.ts; index.ts joins them
 ```
 
 ### Dependency rules
 
-- `server` → `tools` → `backend`, `text`, `prompts`, `cards/<card>/data.ts`.
+- `server` → `tools` → `backend`, `printability`, `text`, `prompts`, `cards/<card>/data.ts`.
+- `text` and `printability` → `backend` (types only).
 - `cards/<card>` → its own `data.ts` and `cards/bridge.ts`. A card never imports `tools`, `server` or `backend`.
 - Nothing imports `server` except `index`. Nothing outside this package sees more than the public API.
 
@@ -43,6 +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 |
 
 `subject` is the caller as the host established it. `onError` receives every
 error that is not a `BackendRefusal`. `instructions` is appended to the
@@ -59,15 +62,16 @@ 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 }` |
+| `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 |
 | `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 |
-| `finishScene(subject, { designId, title })` | marks the current build done, with this version's title |
+| `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 })` | the design as its scene is now, analysed as it prints at its own size and changing nothing, leaving out Areas named `REFERENCE` (bought parts modelled only to show a fit): 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 |
 | `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 |
-| `getPrintOptions(subject, { designId, longestSideCm? })` | the design priced per piece in each material on offer, with its print size, its pieces, and checkout's size limit and order minimum |
-| `checkoutDesign(subject, { designId, material, color?, finish?, quantity?, longestSideCm?, shipTo? })` | freezes the design as quoted and returns the quote with its checkout link; with `shipTo`, also the order to that address as a payment-sheet session |
+| `checkoutDesign(subject, { designId, material, color?, finish?, quantity?, shipTo? })` | freezes the design as quoted, at its own size and without its `REFERENCE` Areas, and returns the quote with its checkout link; with `shipTo`, also the order to that address as a payment-sheet session; called only for a design that passed the print checks |
 | `completeCheckout?(subject, payment)` | optional: charges a payment made in ChatGPT's payment sheet and places the session's order; without it `checkout_design` takes no `shipTo` and there is no `complete_checkout` |
 | `getOrderStatus(subject, { orderId? })` | the caller's paid orders, newest first, and the one to show, with no name, address, email or money |
 
@@ -77,11 +81,19 @@ changes an earlier one.
 ### Plugin → model and cards
 
 - **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). Only a design that passes is finished (`finishScene`) or 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.
+  - `<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.
+  - `<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).
 - **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.
-- **Cards** are MCP Apps resources (`text/html;profile=mcp-app`): one self-contained HTML file each, loading nothing from outside, with a `ui://` URI that changes with its content.
+- **Cards** are MCP Apps resources (`text/html;profile=mcp-app`): one self-contained HTML file each, loading no script, style or font from outside, with a `ui://` URI that changes with its content. Only the design card frames a page: the live view, on `liveViewOrigin`.
 
 ### Tools
 
@@ -94,7 +106,6 @@ changes an earlier one.
 | `finish_scene` | model | |
 | `get_scene_progress` | `design` card | |
 | `get_claim_link` | `design` card | |
-| `get_print_options` | model | |
 | `checkout_design` | model | shows `quote` |
 | `complete_checkout` | model and ChatGPT's payment sheet, only with `completeCheckout` | |
 | `get_order_status` | model | shows `order` |
@@ -116,10 +127,16 @@ implementation in the same release.
 ## Development
 
 ```bash
-npm run dev     # card preview at http://127.0.0.1:5188/preview/, live from source
-npm test        # build the cards, run the tests
-npm run check   # format, build, typecheck, tests (CI)
+npm run dev           # card preview at http://127.0.0.1:5188/preview/, live from source
+npm run dev:chatgpt   # this working copy in real ChatGPT on :8787, forwarding the rest to UPSTREAM (default staging)
+npm test              # build the cards, run the tests
+npm run check         # format, build, typecheck, tests (CI)
 ```
 
+`dev:chatgpt` serves the instructions, tools, cards and workflow from `src/` and forwards every other call to a
+deployed swan (`UPSTREAM`, default staging), signed in as you: open `http://localhost:8787/login` once; the sign-in is
+kept in `dev/.token`. Expose it with a tunnel (`cloudflared tunnel --url http://localhost:8787`) and add the https URL
+in ChatGPT with no authentication. New backend methods still need a swan deploy.
+
 Release: bump the version and tag `vX.Y.Z`; CI publishes to npm. Then bump the
 dependency in swan-backend.

package/dist/index.d.ts

@@ -40,19 +40,12 @@ interface Build {
     title?: string;
     picture: Picture | null;
 }
-/**
- * The design live in 3D, for the card to frame: a page on the host's own origin (the
- * `liveViewOrigin` option) and when its key stops working. The URL carries a credential, so it goes to
- * the card alone, never into text the model reads.
- */
+/** The design live in 3D, on `liveViewOrigin`, until `expiresAt`. A credential: for the card alone. */
 interface LiveView {
     url: string;
     expiresAt: string;
 }
-/**
- * A one-time link that opens a page for keeping this chat's designs and orders in a Womp account. Like `LiveView`
- * it is a credential: it goes to the card alone, when the user asks for it, and never into text the model reads.
- */
+/** A one-time link to keep the chat's designs and orders in a Womp account. A credential: for the card alone. */
 interface ClaimLink {
     url: string;
     expiresAt: string;
@@ -62,34 +55,35 @@ interface Size {
     height: number;
     depth: number;
 }
-/** Checkout takes an order whose items cost more than `amount`; below it, it tops the items up to it (`topUp`) or refuses the order. */
+/** Below `amount` in items, checkout tops the order up to it (`topUp`) or refuses it. */
 interface MinimumOrder {
     amount: number;
     topUp: boolean;
 }
-/** One material a design can be printed in, priced per piece. */
-interface PrintOption {
-    /** The name checkout_design takes, such as "resin-clear-tinted". */
+/** One material on offer for printing. */
+interface Material {
+    /** The name finish_scene and checkout_design take, such as "resin-clear-tinted". */
     material: string;
     /** Such as "Tinted clear". */
     label: string;
+    /** The whole print is one dye colour, which the order names. */
+    colorRequired: boolean;
+    /** The finishes it is made in; the first is the default. */
+    finishes: string[];
+}
+/** One material a design can be printed in, priced per piece. */
+interface PrintOption extends Material {
     /** Per piece, before shipping. */
     unitPrice: number;
     /** Business days to make it, once ordered. */
     productionDays: number;
-    /** The material is dyed, so an order names a colour. */
-    colorRequired: boolean;
-    /** The finishes it is made in; the first is the default. */
-    finishes: string[];
 }
-/** A design priced for printing in each material on offer. */
-interface PrintOptions {
+/** A design analysed as it prints, at its own size, and priced in each material on offer. */
+interface PrintAnalysis {
     designId: string;
     title: string;
-    /** The size it prints at, in cm. */
+    /** In cm. */
     sizeCm: Size;
-    /** Scaled to the longest side asked for, rather than at its own size. */
-    resized: boolean;
     /** How many separate pieces it prints as. */
     pieces: number;
     /** The largest size checkout takes, in cm, in any orientation. */
@@ -97,7 +91,6 @@ interface PrintOptions {
     /** Whether `sizeCm` fits within `maxSizeCm`. */
     fits: boolean;
     currency: string;
-    minimumOrder: MinimumOrder;
     options: PrintOption[];
 }
 /** Where an order paid in ChatGPT's payment sheet ships. */
@@ -112,10 +105,7 @@ interface ShipTo {
     country: string;
     phoneNumber?: string;
 }
-/**
- * The user's own checkout on the web, where they enter an address and pay. Like `ClaimLink` it is a credential: it goes
- * to the card alone, never into text the model reads.
- */
+/** The user's own checkout on the web. A credential: for the card alone. */
 interface CheckoutLink {
     url: string;
     expiresAt: string;
@@ -227,10 +217,7 @@ interface OrderSummary {
     id: number;
     statusLabel: string;
 }
-/**
- * An order as the chat may show it. A checkout link can be forwarded and its buyer's order is found too, so it carries
- * no name, address, email or money.
- */
+/** An order as the chat may show it: no name, address, email or money. */
 interface Order extends OrderSummary {
     step: "paid" | "printing" | "shipped" | "delivered" | "canceled";
     /** Only the items made from this user's checkout links. */
@@ -243,7 +230,7 @@ interface Order extends OrderSummary {
         carrier: string;
         trackingNumber: string;
     }[];
-    /** When it leaves the factory and when it arrives, as happened or expected (ISO); null when it won't arrive or can't be dated. */
+    /** When it leaves the factory and arrives (ISO); null when it can't be dated. */
     timeline: {
         factoryShippingStartedAt: string;
         deliveredAt: string;
@@ -273,23 +260,25 @@ interface WompBackend {
         view?: string;
         targetId?: number;
     }): Promise<Image>;
+    /** The materials on offer to this user, and the largest size checkout takes, before any design exists. */
+    getMaterials(subject: string): Promise<{
+        materials: Material[];
+        maxSizeCm: [number, number, number];
+    }>;
+    /** The design as its scene is now, analysed and priced. Changes nothing. */
+    analyzePrint(subject: string, input: {
+        designId: string;
+    }): Promise<PrintAnalysis>;
     finishScene(subject: string, input: {
         designId: string;
         title: string;
     }): Promise<void>;
-    /**
-     * Optional: a host that cannot keep a chat's designs in an account leaves it out, and the card shows no button.
-     * Returns undefined when it has no link to give right now.
-     */
+    /** 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: {
         designId: string;
         buildId: string;
     }): Promise<Build>;
-    getPrintOptions(subject: string, input: {
-        designId: string;
-        longestSideCm?: number;
-    }): Promise<PrintOptions>;
     /** Freezes the design as quoted, so its order prints it as it is now. `shipTo` comes only to a host with `completeCheckout`. */
     checkoutDesign(subject: string, input: {
         designId: string;
@@ -297,14 +286,9 @@ interface WompBackend {
         color?: string;
         finish?: string;
         quantity?: number;
-        longestSideCm?: number;
         shipTo?: ShipTo;
     }): Promise<Checkout>;
-    /**
-     * Optional: paying in ChatGPT's payment sheet. It charges the payment the sheet hands over and places the session's
-     * order; a refused payment returns the session with an error message. A host that leaves it out takes no address in
-     * checkout_design, and checkout is on the web alone.
-     */
+    /** Optional: charges a payment from ChatGPT's payment sheet and places the order; without it, checkout is on the web alone. */
     completeCheckout?(subject: string, payment: CompleteCheckoutArgs): Promise<CheckoutSession>;
     /** The user's paid orders, newest first, and the one to show: `orderId` when it is one of theirs, else the newest. */
     getOrderStatus(subject: string, input: {
@@ -322,23 +306,11 @@ interface ServerOptions {
     subject?: string;
     onError?: (tool: string, error: unknown) => void;
     instructions?: string;
-    /**
-     * The one origin the card may frame for a live view, such as "https://app.womp.com". Without it the
-     * card allows no frames and `live` from the backend is ignored; an `http:` origin, a path or anything
-     * that is not an origin is the same as none.
-     */
+    /** The one https origin the design card may frame for a live view; without it, no live view. */
     liveViewOrigin?: string;
-    /**
-     * The origins of the web pages the cards open — checkout, an order's status, keeping designs in an account — such as
-     * ["https://app.womp.com"]. ChatGPT opens a page on one of them without asking the user first; anything that is not
-     * an https origin is left out.
-     */
+    /** The https origins of the pages the cards open, which ChatGPT then opens without asking. */
     linkOrigins?: string[];
-    /**
-     * The host's OAuth challenge, a `WWW-Authenticate` value, for a request whose sign-in is missing or not valid. With
-     * it and no subject, every tool call fails with the challenge in `_meta["mcp/www_authenticate"]`, which is what
-     * makes ChatGPT offer to link the account.
-     */
+    /** The host's `WWW-Authenticate` challenge for a request without a valid sign-in. */
     wwwAuthenticate?: string;
 }
 declare function createServer({ backend, subject, onError, instructions, liveViewOrigin, linkOrigins, wwwAuthenticate }: ServerOptions): McpServer;