@12ui/design 0.2.9 → 0.2.11

package/skills/design-branch/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: design-branch
+description: "Expand one approved design into a coherent multi-screen site or app, generate every planned screen in dependency order, and download the ordered pages. Use after a design is chosen to produce its remaining routes, viewports, and app states."
+---
+
+# Design Branch
+
+Branch one approved design into the rest of the product. The server plans the
+screens and their dependencies; dispatch each screen only when the plan allows
+it, and keep every paid screen addressable.
+
+## Start the run
+
+A branch run is a create run with `"source": "build"`. It starts from exactly one
+of an earlier create candidate or an uploaded image — sending both, or neither,
+is `400 invalid_request`.
+
+```bash
+curl -sS -X POST "$ORIGIN/api/v1/create" \
+  -H "Authorization: Bearer $TWELVE_UI_API_KEY" \
+  -H 'content-type: application/json' \
+  -H "Idempotency-Key: <stable-run-key>" \
+  -d '{
+    "source": "build",
+    "concept": "<product, audience, and what the rest of the surface must cover>",
+    "winner": { "createRunId": "crt-<run>", "slot": "a" }
+  }' | tee <run-dir>/branch.json
+```
+
+Start from an image instead of a winner with
+`"referenceImage": {"data": "<base64>", "mediaType": "image/png", "sha256": "<hex>"}`,
+at most 6 MB decoded and matching its magic bytes.
+
+`concept` is required and capped at 600 characters. `aspect` is optional and
+inherits the winner's run; set `landscape`, `portrait`, or `square` only to
+override it. There is no screen count, seed, or candidates field: the server
+plans 2-8 screens into slots `a`-`h` and trims a longer plan to that cap.
+
+Work under the system temporary directory, set `ORIGIN` to `TWELVE_UI_ORIGIN`
+or `https://12ui.com`, and authenticate as for any create run —
+`Authorization: Bearer <key>` scoped to `design.corpus.retrieve`, or a browser
+`x-session-token`. `Idempotency-Key` is
+required and derives the run ID; the same key with the same body replays `200`,
+and with a changed body answers `409 idempotency_conflict`.
+
+The claim runs the planner inline and takes roughly ten to twenty seconds before
+answering, and buys no image. `502 build_plan_failed` means planning failed
+before any image spend: retry the same request with the same key.
+
+## Read the plan
+
+`plan.pages[]` gives each page's `index`, `kind` (`source` or `additional`),
+`title`, `pageType`, `surfaceType`, `purpose`, and its ordered `slots`. Page 0 is
+the approved design's own page and is absent when that screen already ends the
+page. `plan.statusUpdate` is written to be shown verbatim.
+
+Each `candidates[]` entry adds `pageIndex`, `viewportOrdinal` (continuations of
+the approved screen start at 2), `header`, `footer`, `pageEndsHere`,
+`dependsOnSlot`, and `content`. Preserve that grouping and order; it is the site
+structure, not a ranking to redo.
+
+## Dispatch in plan order
+
+Dispatch every screen whose dependencies are already settled, concurrently. Each
+request blocks until that screen settles.
+
+```bash
+curl -sS -X POST "$ORIGIN/api/v1/create/<run-id>/candidates/b" \
+  -H "Authorization: Bearer $TWELVE_UI_API_KEY" \
+  -H 'content-length: 0'
+```
+
+Two gates hold a screen back, and both answer `409` with a nested error object
+carrying `code` and `dependsOn`:
+
+- `dependency_pending`: the screen continues `dependsOn`; generate that slot
+  first.
+- `footer_reference_pending`: the screen closes a page and waits for the first
+  footer-bearing screen in plan order to draw the site footer. Once that seed has
+  failed, later footer screens proceed without it.
+
+Send no `Idempotency-Key` on dispatch: an unkeyed repeat replays the settled
+screen for free. A new key on a settled slot buys one more image for that screen
+and leaves its siblings untouched, so reserve it for an explicit redraw request.
+`409 candidate_in_flight` means another caller holds the slot — wait a few
+seconds and read the run.
+
+## Poll and download
+
+```bash
+curl -sS "$ORIGIN/api/v1/create/<run-id>" \
+  -H "Authorization: Bearer $TWELVE_UI_API_KEY" | tee <run-dir>/status.json
+```
+
+There is no run-level progress: count candidate `status` values, which are
+`pending`, `dispatched`, `succeeded`, and `failed`. A `failed` screen is a
+settled, paid outcome, not a transient error. Download each succeeded screen
+with the same headers:
+
+```bash
+curl -sS "$ORIGIN/api/v1/create/<run-id>/candidates/b/image" \
+  -H "Authorization: Bearer $TWELVE_UI_API_KEY" \
+  -o <run-dir>/screens/b.png
+```
+
+Runs expire seven days after the claim and then answer `410 expired`.
+
+## Quota
+
+A branch run is charged per dispatched screen rather than at the claim: one
+image against the daily allowance — 20 per UTC day for an account, 12 for an
+anonymous caller — then the prepaid wallet for the overflow. An exhausted
+allowance without a funded wallet is `429 quota_exhausted` with `retry-after`; a
+funded account that cannot cover a screen is `402 insufficient_funds`, and that
+screen is not persisted. Decide which screens the task needs before dispatching.
+
+## Hand off
+
+Keep the plan's grouping: `plan.pages[].slots` is the order viewports stack down
+one page, and page order is site order with the approved design first.
+
+- Ordered viewports of one continuous page: submit them as one conversion
+  package (`POST /api/v1/convert/package`, read back with
+  `GET /api/v1/convert/package/<package-id>`) so page order and stitching are
+  preserved. Every viewport of a page must share one width.
+- One independent route, app state, or mobile screen: `design-convert` on that
+  PNG.
+
+Report the run ID, planned pages and slots, each screen's slot, status, and
+hash, any regeneration, and the conversion package or conversion IDs.

package/skills/design-branch/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Design Branch"
+  short_description: "Expand one approved design into a whole site using 12ui design branch"
+  icon_small: "./assets/small-400px.png"
+  icon_large: "./assets/large-logo.svg"
+  default_prompt: "Use $design-branch to expand this homepage into a site."
+policy:
+  allow_implicit_invocation: true

package/skills/design-branch/assets/large-logo.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024" version="1.1" role="img" aria-label="design-branch logo">
+	<path d="M 366.13 592.44 L 716.78 247.44 L 657.87 187.56 L 307.22 532.56 Z" stroke="none" fill="#000"/>
+	<path d="M 307.22 491.44 L 657.87 836.44 L 716.78 776.56 L 366.13 431.56 Z" stroke="none" fill="#000"/>
+	<path d="M 96 366 L 388 366 L 388 658 L 96 658 Z" stroke="none" fill="#000"/>
+	<path d="M 636 122 L 928 122 L 928 414 L 636 414 Z" stroke="none" fill="#000"/>
+	<path d="M 636 610 L 928 610 L 928 902 L 636 902 Z" stroke="none" fill="#000"/>
+</svg>

package/skills/design-draft/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: design-draft
+description: "Draft candidate interface designs from a written brief, optionally conditioned on reference images, then poll the run and download the winning image. Use to explore several distinctive directions for a new UI, web, or mobile screen before branching or converting one."
+---
+
+# Design Draft
+
+Buy one small set of candidate designs, keep the run addressable, and hand the
+chosen candidate to branching or conversion. Every candidate is paid work: the
+run is identified by its idempotency key, so a retry replays evidence instead of
+generating again.
+
+## Prepare
+
+Work under the system temporary directory. Set `ORIGIN` to `TWELVE_UI_ORIGIN`
+or `https://12ui.com`, and send a personal key in `Authorization: Bearer <key>`
+taken from `TWELVE_UI_API_KEY` or `~/.config/12ui/credentials.json` and scoped
+to `design.corpus.retrieve`. A browser session may present `x-session-token`
+instead.
+
+Write one `concept`: product, audience, surface, primary goal, and personality
+in at most 600 characters. Describe the design problem, not every section,
+control, or exact string.
+
+Default to four candidates in slots `a`-`d`; a run accepts 1-96 across slots
+`a`-`cr`. Pick one `aspect` for the whole run — `landscape` (1536x1024),
+`portrait` (1024x1536), or `square` (1024x1024).
+
+Give every candidate its own short `direction` (at most 120 characters), such as
+airy editorial, tactile retail, or cinematic, and make the directions
+meaningfully different. Leaving any direction blank spends one extra metered
+text call to derive them all.
+
+## Claim the run
+
+`Idempotency-Key` is required and derives the run ID, so the same key always
+resolves the same run, quota allocation, and stored images.
+
+```bash
+curl -sS -X POST "$ORIGIN/api/v1/create" \
+  -H "Authorization: Bearer $TWELVE_UI_API_KEY" \
+  -H 'content-type: application/json' \
+  -H "Idempotency-Key: <stable-run-key>" \
+  -d '{
+    "concept": "<concise interface concept>",
+    "aspect": "landscape",
+    "mode": "inspiration",
+    "candidates": [
+      { "slot": "a", "direction": "<short direction>", "referenceId": "gen-<corpus-id>" },
+      { "slot": "b", "direction": "<short direction>", "referenceId": "gen-<corpus-id>" }
+    ]
+  }' | tee <run-dir>/run.json
+```
+
+Give a candidate at most one reference and never both kinds: `referenceId` is a
+`design-search` corpus ID, `"useReferenceImage": true` conditions on the one
+run-level image sent as base64 with its media type and SHA-256. Omitting both
+generates from the concept and direction alone.
+
+```json
+"referenceImage": { "data": "<base64>", "mediaType": "image/png", "sha256": "<hex>" }
+```
+
+The decoded image must be at most 6 MB, its media type must match its magic
+bytes, and the whole body must stay under 8 MB. `mode` defaults to
+`inspiration`; use `preserve-structure` only with a `referenceImage` that every
+candidate uses.
+
+The reply is the run envelope: `id`, `aspect`, `mode`, `source`, `expiresAt`
+seven days out, and one `pending` entry per slot. Replaying the same key with the
+same body answers `200` with that envelope. The same key with a changed body is
+`409 idempotency_conflict`, or `503 service_unavailable` when the candidate
+count changed too; either way keep the original request rather than editing a
+claim. Mint a new key only when the reply says to start a new run, which a
+poisoned claim such as `502 create_directions_failed` or
+`409 run_setup_incomplete` does say.
+
+## Dispatch the candidates
+
+Each slot is one provider call and one paid image. Dispatch all slots
+concurrently; every request blocks until its own image settles.
+
+```bash
+curl -sS -X POST "$ORIGIN/api/v1/create/<run-id>/candidates/a" \
+  -H "Authorization: Bearer $TWELVE_UI_API_KEY" \
+  -H 'content-length: 0'
+```
+
+Send no `Idempotency-Key` on dispatch: an unkeyed repeat replays the durable
+result for free. A new key on a settled slot buys another image for that slot,
+so use it only when the user asks for a fresh attempt. `409 candidate_in_flight`
+means another caller already holds the slot — wait a few seconds and read the
+run instead of dispatching again.
+
+## Poll and download
+
+```bash
+curl -sS "$ORIGIN/api/v1/create/<run-id>" \
+  -H "Authorization: Bearer $TWELVE_UI_API_KEY" | tee <run-dir>/status.json
+```
+
+There is no run-level status or percentage: count candidate `status` values,
+which are `pending`, `dispatched`, `succeeded`, and `failed`. A `failed`
+candidate is a settled, paid outcome — `content_policy`, `provider_timeout`,
+`provider_error`, or `reference_unavailable` — not a transient error to retry.
+
+A succeeded candidate carries a relative `image` path. It is owner
+authenticated rather than signed, so download it with the same headers:
+
+```bash
+curl -sS "$ORIGIN/api/v1/create/<run-id>/candidates/a/image" \
+  -H "Authorization: Bearer $TWELVE_UI_API_KEY" \
+  -o <run-dir>/candidates/a.png
+```
+
+Runs expire seven days after the claim; `410 expired` is terminal.
+
+## Quota
+
+An account generates 20 images per UTC day and an anonymous caller 12. Overflow
+spills to the prepaid wallet as one billable image per slot. An exhausted
+allowance without a funded wallet is `429 quota_exhausted` with `retry-after`; a
+funded account that cannot cover the overflow is `402 insufficient_funds` with
+`required_micros` and `available_micros`, and no candidate is persisted. Neither
+answer becomes success by resending.
+
+## Select and hand off
+
+Inspect every downloaded candidate at original detail and choose the best
+direction for the brief, hierarchy, usability, personality, accessibility, and
+ability to extend into later screens. Treat common model palettes as neutral,
+and prefer a repeatable visual system over an impressive one-off hero. Record
+the run ID, slots, directions, references, image hashes, and rejection reasons.
+
+- Expand the winner into a multi-screen site or app with `design-branch`, which
+  starts from `{ "createRunId": "<run-id>", "slot": "<slot>" }` and never needs
+  the bytes.
+- Turn one screen into code or another format with `design-convert` on the
+  downloaded PNG.

package/skills/design-draft/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Design Draft"
+  short_description: "Draft candidate design directions from a brief with 12ui design draft"
+  icon_small: "./assets/small-400px.png"
+  icon_large: "./assets/large-logo.svg"
+  default_prompt: "Use $design-draft to draft four homepage directions."
+policy:
+  allow_implicit_invocation: true

package/skills/design-draft/assets/large-logo.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024" version="1.1" role="img" aria-label="design-create logo">
+	<path d="M 600 110 C 600 335.72, 716.28 452, 942 452 C 716.28 452, 600 568.28, 600 794 C 600 568.28, 483.72 452, 258 452 C 483.72 452, 600 335.72, 600 110 Z M 232 628 C 232 745.48, 292.52 806, 410 806 C 292.52 806, 232 866.52, 232 984 C 232 866.52, 171.48 806, 54 806 C 171.48 806, 232 745.48, 232 628 Z" stroke="none" fill="#000"/>
+</svg>