@pixelvibing/cli 0.34.0 → 0.36.0

package/dist/pixel-vibing-cli.js

@@ -610,6 +610,8 @@ function createWebApi(fetcher = (input, init2) => fetch(input, init2), base = AP
     /** Start a generation for a project, answering its job's id, or `TooFewCredits` (R3.2, R3.4). */
     generate: (kind, body) => paying2(async () => (await json2(`/generations/${id(kind)}`, { method: "POST", body })).id),
     job: (jobId) => json2(`/jobs/${id(jobId)}`),
+    /** Ask a job again with its own input, answering the new job's id, or `TooFewCredits` (specs/generation-jobs/ R6). */
+    redo: (jobId) => paying2(async () => (await json2(`/jobs/${id(jobId)}/redo`, { method: "POST" })).id),
     /** Cancel a job no worker has taken, answering it and the credits that came back; 409 once one has (specs/generation-jobs/ R5). */
     cancelJob: (jobId) => json2(`/jobs/${id(jobId)}/cancel`, { method: "POST" }),
     jobs: (projectId, before = null, kinds = null) => json2(
@@ -1041,7 +1043,6 @@ function nameProblem(name) {
   }
   return null;
 }
-const HUD_PIECE_NAMES = ["health-bar", "mana-bar", "button", "inventory-slot", "panel-frame", "minimap-frame"];
 const ICON_SIZES = [16, 32, 64];
 const DEFAULT_ICON_SIZE = 32;
 const MAX_ICONS = 16;
@@ -3923,27 +3924,16 @@ const GENERATED = {
   object: { references: 8, words: "an object" },
   creature: { references: 3, words: "a creature" },
   "level-design": { references: 3, words: "a level design" },
-  hud: { references: 0, words: "a HUD set" },
   icons: { references: 0, words: "an icon set" },
-  "hud-mockup": { references: 3, words: "a HUD mockup" },
-  "ui-sketch": { references: 3, words: "a UI sketch" }
+  "ui-sketch": { references: 3, words: "a UI" }
 };
+const KIND_NAMES = { ui: "ui-sketch" };
 function listOf(given, what) {
   const items = given.split(",").map((item) => item.trim());
   if (items.some((item) => item === "")) throw new CliError(`${what} is a comma-separated list with no empty entry`);
   return items;
 }
-function interfaceFields(kind, args) {
-  if (kind === "hud") {
-    if (stringOf(args, "names") !== void 0 || stringOf(args, "purpose") !== void 0) throw new CliError("--names and --purpose are an icon set's");
-    if (stringOf(args, "size") !== void 0) throw new CliError("--size is an object's or an icon set's");
-    const pieces = listOf(stringOf(args, "pieces") ?? HUD_PIECE_NAMES.join(","), "--pieces");
-    const unknown = pieces.find((piece) => !HUD_PIECE_NAMES.includes(piece));
-    if (unknown !== void 0) throw new CliError(`${unknown} is not a HUD piece: ${HUD_PIECE_NAMES.join(", ")}`);
-    if (new Set(pieces).size !== pieces.length) throw new CliError("--pieces names a piece twice");
-    return { fields: { pieces }, words: `a HUD set of ${pieces.join(", ")}` };
-  }
-  if (stringOf(args, "pieces") !== void 0) throw new CliError("--pieces is a HUD set's");
+function iconFields(args) {
   const given = stringOf(args, "names");
   if (given === void 0) throw new CliError('name the icons with --names, such as --names "red potion,key,coin"');
   const names = listOf(given, "--names");
@@ -3961,7 +3951,7 @@ function interfaceFields(kind, args) {
 }
 const MAX_SKETCH_BYTES = 256 * 1024;
 async function sketchOf(context, path, instruction) {
-  if (path === void 0) throw new CliError("lay the sketch out in a JSON file and name it with --sketch, such as --sketch hud.json");
+  if (path === void 0) throw new CliError("lay the UI out in a JSON file and name it with --sketch, such as --sketch ui.json");
   const file = resolve(context.io.cwd, path);
   let text2;
   try {
@@ -3998,7 +3988,7 @@ async function sketchOf(context, path, instruction) {
   const labels = sketch.shapes.map((shape) => shape.label.trim());
   return {
     sketch,
-    words: `a UI sketch of ${labels.length} shape${labels.length === 1 ? "" : "s"} (${labels.join(", ")}) on ${canvas.width} × ${canvas.height}`
+    words: `a UI of ${labels.length} shape${labels.length === 1 ? "" : "s"} (${labels.join(", ")}) on ${canvas.width} × ${canvas.height}`
   };
 }
 const MAX_DESIGN_TILES = 64;
@@ -4021,11 +4011,12 @@ async function referenceOf(context, path) {
   if (!isPng(bytes)) throw new CliError(`the reference ${path} is not a PNG`);
   return bytes;
 }
-async function requestOf(context, kind, args) {
+async function requestOf(context, asked, args) {
+  const kind = KIND_NAMES[asked] ?? asked;
   const known = GENERATED[kind];
-  if (known === void 0) throw new CliError(`generate makes ${Object.keys(GENERATED).join(", ")}, not ${kind}`);
+  if (known === void 0) throw new CliError(`generate makes ${Object.keys(GENERATED).join(", ")} (or ui), not ${asked}`);
   const instruction = stringOf(args, "instruction")?.trim() ?? "";
-  const set = kind === "hud" || kind === "icons";
+  const set = kind === "icons";
   if (instruction === "" && !set) throw new CliError("say what to make with --instruction");
   if (stringOf(args, "quality") !== void 0)
     context.io.warn("--quality is the platform's to choose now: it draws each asset at the quality it needs, and nothing was sent for it.\n");
@@ -4033,8 +4024,8 @@ async function requestOf(context, kind, args) {
   if (paths.length > known.references)
     throw new CliError(known.references === 0 ? `${known.words} takes no reference` : `${known.words} takes at most ${known.references} references`);
   if (kind === "ui-sketch") {
-    for (const flag of ["pieces", "names", "purpose", "size", "tiles"])
-      if (stringOf(args, flag) !== void 0) throw new CliError(`--${flag} is not a UI sketch's: its shapes are in the --sketch file`);
+    for (const flag of ["names", "purpose", "size", "tiles"])
+      if (stringOf(args, flag) !== void 0) throw new CliError(`--${flag} is not a UI's: its shapes are in the --sketch file`);
     const { sketch, words: words2 } = await sketchOf(context, stringOf(args, "sketch"), instruction);
     const styles = [];
     for (const path of paths) styles.push(await referenceOf(context, path));
@@ -4045,15 +4036,14 @@ async function requestOf(context, kind, args) {
       words: `${words2}${styles.length > 0 ? `, in the style of ${styles.length} reference${styles.length === 1 ? "" : "s"}` : ""}: ${instruction}`
     };
   }
-  if (stringOf(args, "sketch") !== void 0) throw new CliError("--sketch is a UI sketch's");
+  if (stringOf(args, "sketch") !== void 0) throw new CliError("--sketch is a UI's");
   if (set) {
-    const { fields, words: words2 } = interfaceFields(kind, args);
+    const { fields, words: words2 } = iconFields(args);
     if (stringOf(args, "tiles") !== void 0) throw new CliError("--tiles is a level design's");
     const body2 = { ...fields, ...instruction === "" ? {} : { instruction } };
     return { kind, body: body2, words: instruction === "" ? words2 : `${words2}; ${instruction}` };
   }
-  for (const flag of ["pieces", "names", "purpose"])
-    if (stringOf(args, flag) !== void 0) throw new CliError(`--${flag} is ${flag === "pieces" ? "a HUD set's" : "an icon set's"}`);
+  for (const flag of ["names", "purpose"]) if (stringOf(args, flag) !== void 0) throw new CliError(`--${flag} is an icon set's`);
   const references = [];
   for (const path of paths) references.push(await referenceOf(context, path));
   const body = { instruction };
@@ -4100,27 +4090,26 @@ async function followed(context, platform, jobId) {
 }
 const generate = {
   name: "generate",
-  summary: "Generate an object, a creature, a level design, a HUD set, icons, a HUD mockup or a UI sketch on the platform, then pull it",
-  usage: "<object|creature|level-design|hud|icons|hud-mockup|ui-sketch> [--instruction <text>] [--size <c>x<r>|<px>] [--tiles <c>x<r>] [--pieces <list>] [--names <list>] [--purpose skill|item] [--sketch <json>] [--reference <png>]… [--yes]",
+  summary: "Generate an object, a creature, a level design, icons or a UI on the platform, then pull it",
+  usage: "<object|creature|level-design|icons|ui> [--instruction <text>] [--size <c>x<r>|<px>] [--tiles <c>x<r>] [--names <list>] [--purpose skill|item] [--sketch <json>] [--reference <png>]… [--yes]",
   options: {
     instruction: {
       type: "string",
       value: "<text>",
-      description: "what to make, in your own words; a HUD set's or icon set's theme; a UI sketch's set, in a line"
+      description: "what to make, in your own words; an icon set's theme; a UI's set, in a line"
     },
     size: {
       type: "string",
       value: "<cols>x<rows>|<px>",
       description: "an object's footprint in tiles, 1x1 unless given; an icon's size, 16, 32 or 64 px, 32 unless given"
     },
-    pieces: { type: "string", value: "<list>", description: `a HUD set's pieces, comma-separated: ${HUD_PIECE_NAMES.join(", ")}; all unless given` },
     names: { type: "string", value: "<list>", description: `an icon set's icons, comma-separated, at most ${MAX_ICONS}` },
     purpose: { type: "string", value: "skill|item", description: "whether an icon set is skills on badges or items alone; item unless given" },
     tiles: { type: "string", value: "<cols>x<rows>", description: "how many tiles a level design is across, 6x4 unless given" },
     sketch: {
       type: "string",
       value: "<json>",
-      description: "a UI sketch's file: { canvas: { width, height }, shapes: [{ label, kind, x, y, width, height, radius?, sides?, caption?, note?, border?, hollow? }] }"
+      description: "a UI's layout file, as the Skill's references/ui.schema.json says: { canvas: { width, height }, shapes: [{ label, kind, x, y, width, height, radius?, sides?, caption?, note?, border?, hollow? }] }"
     },
     reference: { type: "string", multiple: true, value: "<png>", description: "an image to draw from" },
     quality: { type: "string", value: "<quality>", description: "the platform's to choose now; ignored, and said so" },
@@ -4601,7 +4590,7 @@ const move = {
     );
   }
 };
-const version = "0.34.0";
+const version = "0.36.0";
 const manifest = {
   version
 };
@@ -4681,13 +4670,31 @@ const HARNESS_FILES = { claude: ".mcp.json", codex: ".codex/config.toml" };
 const HARNESSES = { claude: ".claude", codex: ".codex" };
 const SKILLS_MANIFEST = "pixelvibing-skills.json";
 const sha256 = (text2) => createHash("sha256").update(text2).digest("hex");
+function skillHash(text2, files = []) {
+  if (files.length === 0) return sha256(text2);
+  const hash = createHash("sha256").update(text2);
+  for (const file of files) hash.update(`\0${file.path}\0`).update(file.text);
+  return hash.digest("hex");
+}
+async function referencesOf(directory) {
+  let names;
+  try {
+    names = (await readdir(join(directory, "references"), { withFileTypes: true })).filter((entry) => entry.isFile()).map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const name of names.sort()) files.push({ path: `references/${name}`, text: await readFile(join(directory, "references", name), "utf8") });
+  return files;
+}
 const SHIPPED_DIRECTORY = fileURLToPath(new URL("../skills/", import.meta.url));
 async function shippedSkills(directory = SHIPPED_DIRECTORY) {
   const names = (await readdir(directory, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
   const skills = [];
   for (const name of names.sort()) {
     const text2 = await readFile(join(directory, name, "SKILL.md"), "utf8");
-    skills.push({ name, text: text2, sha256: sha256(text2) });
+    const files = await referencesOf(join(directory, name));
+    skills.push({ name, text: text2, ...files.length > 0 ? { files } : {}, sha256: skillHash(text2, files) });
   }
   return skills;
 }
@@ -4731,6 +4738,11 @@ async function writeSkill(root, harness, skill) {
   const path = skillPath(root, harness, skill.name);
   await mkdir(join(path, ".."), { recursive: true });
   await writeFile(path, skill.text);
+  for (const file of skill.files ?? []) {
+    const at = join(path, "..", file.path);
+    await mkdir(join(at, ".."), { recursive: true });
+    await writeFile(at, file.text);
+  }
 }
 async function textAt(path) {
   try {
@@ -4739,17 +4751,25 @@ async function textAt(path) {
     return null;
   }
 }
+async function hashThere(root, harness, skill) {
+  const path = skillPath(root, harness, skill.name);
+  const text2 = await textAt(path);
+  if (text2 === null) return null;
+  const files = [];
+  for (const file of skill.files ?? []) files.push({ path: file.path, text: await textAt(join(path, "..", file.path)) ?? "" });
+  return skillHash(text2, files);
+}
 async function installMissing(root, harness, skills) {
   const manifest2 = await readManifest(root, harness) ?? {};
   const installed = [];
   const left = [];
   for (const skill of skills) {
-    const there = await textAt(skillPath(root, harness, skill.name));
+    const there = await hashThere(root, harness, skill);
     if (there === null) {
       await writeSkill(root, harness, skill);
       manifest2[skill.name] = skill.sha256;
       installed.push(skill.name);
-    } else if (sha256(there) === skill.sha256) manifest2[skill.name] = skill.sha256;
+    } else if (there === skill.sha256) manifest2[skill.name] = skill.sha256;
     else if (manifest2[skill.name] === void 0) left.push(skill.name);
   }
   await writeManifest(root, harness, manifest2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelvibing/cli",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "PixelVibing: pixel art game assets from the command line, and the Skills that teach coding assistants to make them.",
   "license": "MIT",
   "homepage": "https://pixelvibing.com",

package/skills/pixelvibing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixelvibing
-description: Make pixel art for this game with pixel-vibing-cli — objects, creatures, level designs and interface art (a HUD, skill and item icons, pieces laid out in a sketch) generated on the PixelVibing platform, listed, pulled into the project's art and its folder, and exported or sealed for the game. Use when the game needs a sprite, a prop, a creature, a level's art, its HUD or its icons, or art already made for it.
+description: Make pixel art for this game with pixel-vibing-cli — objects, creatures, level designs and interface art (a UI laid out as JSON, skill and item icons) generated on the PixelVibing platform, listed, pulled into the project's art and its folder, and exported or sealed for the game. Use when the game needs a sprite, a prop, a creature, a level's art, its HUD or its icons, or art already made for it.
 ---
 
 # PixelVibing art for this game
@@ -32,10 +32,8 @@ Progress and errors go to standard error, and a failure exits 1.
 pixel-vibing-cli generate object --instruction "<what>" --size <cols>x<rows> --yes --json
 pixel-vibing-cli generate creature --instruction "<what>" [--reference <png>]... --yes --json
 pixel-vibing-cli generate level-design --instruction "<what>" --tiles <cols>x<rows> --yes --json
-pixel-vibing-cli generate hud [--pieces <list>] [--instruction "<theme>"] --yes --json
 pixel-vibing-cli generate icons --names "<name>,<name>,..." --purpose <skill|item> [--size <16|32|64>] --yes --json
-pixel-vibing-cli generate hud-mockup --instruction "<the HUD>" --yes --json
-pixel-vibing-cli generate ui-sketch --sketch <file.json> --instruction "<the set, in a line>" --yes --json
+pixel-vibing-cli generate ui --sketch <file.json> --instruction "<the set, in a line>" --yes --json
 ```
 
 Each generation spends the account's credits.
@@ -50,30 +48,23 @@ Each generation spends the account's credits.
   - No quality is given: the platform draws each asset at the quality it needs. The cost
     printed is the most it may take, and what it does not use is given back.
   - `--reference` is a PNG to draw from, repeated for several: at most 8 for an object,
-    3 for a creature, a level design, a HUD mockup or a UI sketch, none for a HUD set or icons. A UI
-    sketch's references are a style to follow (frames, materials, a way of drawing), never what to draw.
+    3 for a creature, a level design or a UI, none for icons. A UI's references are a style
+    to follow (frames, materials, a way of drawing), never what to draw.
 - **Interface art.** When the game shows the player something over the world, make it here
   rather than drawing it in code:
-  - `hud` makes a matching set in one generation: `health-bar`, `mana-bar`, `button`,
-    `inventory-slot`, `panel-frame` and `minimap-frame`, all unless `--pieces` names some.
-    Frames, buttons, slots and the minimap frame come with nine-slice insets, so stretch
-    them with the engine's nine-slice sprite rather than scaling them.
   - `icons` makes up to 16 icons that match, from `--names`: `--purpose skill` for a
     hotbar or a skill tree (each on a square badge), `--purpose item` for an inventory,
     potions or loot (each alone). `--size` is 16, 32 (the default) or 64 px.
-  - `hud-mockup` draws one screen with its whole HUD, to agree on the look first; take
-    its pieces out in the desktop editor.
-  - `ui-sketch` draws pieces where a sketch lays them out, when the game needs pieces the
-    HUD set does not have, or at sizes and places of its own. Write the sketch as JSON:
-    `{ "canvas": { "width": 256, "height": 256 }, "shapes": [...] }`, the canvas 128 × 128,
-    256 × 256, 256 × 128 or 128 × 256, and up to 16 shapes that do not overlap, each
-    `{ "label", "kind": "rect" | "ellipse" | "polygon", "x", "y", "width", "height" }` in
-    the canvas's pixels, with `radius` for a rounded rectangle and `sides` (3 to 8) for a
-    polygon. A shape may say more: `note` (what the piece is, such as "a full red health
-    bar"), `caption` (text drawn on it, such as "Quit"), `border` (its frame's width in
-    pixels, which gives the piece nine-slice insets) and `hollow: true` (only the border
-    drawn, its inside transparent). Leave a few pixels between shapes.
-  - The art never carries text or numbers, but a UI sketch's captions: draw labels,
+  - `ui` draws a game's interface (a HUD, a menu, an inventory) from a layout in JSON:
+    a canvas and up to 16 components, each with a `label` (its role, never drawn), a
+    `kind` (`rect`, `ellipse` or `polygon`), its position and size (`x`, `y`, `width`,
+    `height` in the canvas's pixels) and, as it needs, `caption` (text drawn on it), `note`
+    (how it looks), `border` (a frame that stretches by nine-slice) and `hollow` (its inside
+    transparent). Read `references/ui.md` before writing one: it gives every field and rule,
+    `references/ui.schema.json` is the JSON Schema the file follows (name it with
+    `"$schema"`), and `references/ui.example.json` is a whole HUD laid out. Each component
+    comes back as its own piece. `ui-sketch` is the same kind by its platform name.
+  - The art never carries text or numbers, but a UI's captions: draw labels,
     counts and values in the game.
 - **Success.** The asset is pulled at once. The answer's `files` are where its pictures
   are, relative to `pixelvibing/`.
@@ -92,9 +83,9 @@ pixel-vibing-cli pull <id|name> [--as <name>] --json
   `creature`, `level-design`, `rotate`, `animate`…
 - **Pulling.** `pull` adds the asset to the project's art on the platform, where the editor
   sees it too, and then writes the folder from the platform. An asset of one picture
-  lands as `<name>`, one of several as `<name>/<n>`; a HUD set's pieces as `ui/hud/<piece>`,
-  an icon set's as `ui/icon/<name>` and a UI sketch's as `ui/sketch/<label>`, each under
-  `pixelvibing/out/`. A level design or a HUD mockup is kept as a reference, under
+  lands as `<name>`, one of several as `<name>/<n>`; an icon set's pieces as `ui/icon/<name>`
+  and a UI's as `ui/sketch/<label>`, each under `pixelvibing/out/`. A level design is kept
+  as a reference, under
   `pixelvibing/ref/`. Pulling again lands nothing while the art still holds it.
 - **Collisions.** `pull` lands nothing under a name the art holds for something else. When
   it refuses, give the asset another name with `--as`. A terrain set is landed from the
@@ -129,7 +120,7 @@ pixel-vibing-cli export <default|pixi|phaser|godot> [--out <dir>] --json
 - **The map.** `map.json` lists each placed sprite, with its frame, its box in world
   pixels, its level and its layer (`ground`, `object` or `foreground`), in draw order.
   Place them in that order.
-- **Interface art that stretches.** A HUD frame's nine-slice insets travel with it:
+- **Interface art that stretches.** A UI frame's nine-slice insets travel with it:
   `nineGrid` on its frame in `sheets.json`, `borders` on its PixiJS frame (a
   `NineSliceSprite` reads them), Phaser's `nine-slices.json` (the widths `nineslice()`
   takes), and a `NinePatchRect` scene under Godot's `nine-patch/`.

package/skills/pixelvibing/references/ui.example.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "./ui.schema.json",
+  "canvas": { "width": 256, "height": 256 },
+  "shapes": [
+    { "label": "Health bar", "kind": "rect", "x": 8, "y": 8, "width": 120, "height": 14, "radius": 2, "border": 2, "note": "a full red health bar" },
+    { "label": "Mana bar", "kind": "rect", "x": 8, "y": 28, "width": 120, "height": 14, "radius": 2, "border": 2, "note": "a full blue mana bar" },
+    { "label": "Minimap frame", "kind": "ellipse", "x": 176, "y": 8, "width": 72, "height": 72, "border": 6, "hollow": true },
+    { "label": "Inventory slot", "kind": "rect", "x": 8, "y": 208, "width": 40, "height": 40, "border": 3, "note": "an empty, recessed slot" },
+    { "label": "Skill badge", "kind": "polygon", "sides": 6, "x": 56, "y": 208, "width": 40, "height": 40, "border": 3 },
+    { "label": "Quit button", "kind": "rect", "x": 160, "y": 216, "width": 88, "height": 28, "radius": 4, "border": 3, "caption": "Quit" }
+  ]
+}

package/skills/pixelvibing/references/ui.md

@@ -0,0 +1,63 @@
+# A UI, laid out as JSON
+
+`pixel-vibing-cli generate ui --sketch <file.json> --instruction "<the set, in a line>"`
+draws a game's interface from a layout: each shape in the file becomes one piece of the
+interface, drawn where it sits, all of them as one matching set in the game's style. The
+file's shape is `ui.schema.json`, beside this page; `ui.example.json` is a whole HUD laid
+out in it. Name the schema in the file (`"$schema": "./ui.schema.json"`) so an editor checks
+it as it is written; the CLI checks it again, with the platform's own rules, before anything
+is sent or paid for.
+
+## The layout
+
+```json
+{
+  "canvas": { "width": 256, "height": 256 },
+  "shapes": [
+    { "label": "Quit button", "kind": "rect", "x": 160, "y": 216, "width": 88, "height": 28, "radius": 4, "border": 3, "caption": "Quit" }
+  ]
+}
+```
+
+- **`canvas`** is 128 × 128, 256 × 256, 256 × 128 or 128 × 256 pixels, the game's own.
+  Pick the one the screen's pieces fit at the size they are used in the game.
+- **`shapes`** holds 1 to 16 components. Every one has:
+
+| Field | Type | What it is |
+|---|---|---|
+| `label` | text, 1–40 | The component's name and role: `Health bar`, `Quit button`, `Inventory slot`. Read to decide what to draw, never drawn. Unique in the file, ignoring case. |
+| `kind` | `rect` · `ellipse` · `polygon` | Its outline. |
+| `x`, `y` | whole pixels | Its top left corner on the canvas. |
+| `width`, `height` | whole pixels, at least 4 | Its size; it stays inside the canvas. |
+
+  And, when the component needs it:
+
+| Field | Type | What it is |
+|---|---|---|
+| `radius` | whole pixels | A `rect`'s rounded corners. |
+| `sides` | 3–8 | A `polygon`'s sides, its first corner at the top. Required for a polygon. |
+| `caption` | text, up to 24 | Text drawn on the piece, exactly: `Quit`, `Inventory`. The only text the art carries. |
+| `note` | text, up to 200 | What it is or how it looks: `a full red health bar`, `an empty recessed slot`. |
+| `border` | whole pixels, 1 or more | Its frame's width. A piece with a border comes with nine-slice insets, so it stretches; twice the border is less than its shorter side. |
+| `hollow` | `true` | Transparency: only the border is drawn and the inside stays fully transparent, as a minimap frame or a window. Needs `border`. |
+
+## Rules the platform holds it to
+
+- Shapes never overlap. Leave 4 or more pixels between them: a piece's outline and
+  ornament reach a little past its shape.
+- A label names one component; two shapes with the same label are refused.
+- Nothing else goes in the file: a field the schema does not name is refused.
+- The set's description (`--instruction`, up to 600 characters) says the theme in a line:
+  `gothic iron with green enamel`. What each piece is goes in its `label` and `note`.
+- `--reference <png>`, up to 3, is a style to follow, never what to draw.
+
+## Laying out a screen
+
+1. List the components the screen needs: bars, buttons, slots, frames, badges.
+2. Give each a role-naming `label`, the outline closest to it, and a `note` when the label
+   alone does not say how it looks.
+3. Give frames, buttons and slots a `border`; give a frame the game shows through `hollow`.
+4. Put a `caption` only on what carries fixed words; counts and values are the game's to draw.
+5. Place them as the screen places them, so the set is drawn at the sizes it is used at.
+
+Each piece is pulled as `ui/sketch/<label>` under `pixelvibing/out/`, its insets with it.

package/skills/pixelvibing/references/ui.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://pixelvibing.com/schemas/ui.schema.json",
+  "title": "PixelVibing UI layout",
+  "description": "The layout `pixel-vibing-cli generate ui --sketch <file>` reads: a canvas and the labelled shapes on it, each drawn as its own piece of the game's interface where it sits. Coordinates are the canvas's pixels from its top left. Shapes never overlap, and labels are unique, ignoring case. The set's description is given apart, with --instruction.",
+  "type": "object",
+  "required": ["canvas", "shapes"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "This schema's path or URL, for an editor; never sent."
+    },
+    "canvas": {
+      "description": "The canvas the UI is drawn on, in the game's pixels.",
+      "oneOf": [
+        { "$ref": "#/$defs/canvas", "properties": { "width": { "const": 128 }, "height": { "const": 128 } } },
+        { "$ref": "#/$defs/canvas", "properties": { "width": { "const": 256 }, "height": { "const": 256 } } },
+        { "$ref": "#/$defs/canvas", "properties": { "width": { "const": 256 }, "height": { "const": 128 } } },
+        { "$ref": "#/$defs/canvas", "properties": { "width": { "const": 128 }, "height": { "const": 256 } } }
+      ]
+    },
+    "shapes": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 16,
+      "items": { "$ref": "#/$defs/shape" }
+    }
+  },
+  "$defs": {
+    "canvas": {
+      "type": "object",
+      "required": ["width", "height"],
+      "additionalProperties": false,
+      "properties": {
+        "width": { "type": "integer" },
+        "height": { "type": "integer" }
+      }
+    },
+    "shape": {
+      "type": "object",
+      "required": ["label", "kind", "x", "y", "width", "height"],
+      "additionalProperties": false,
+      "properties": {
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 40,
+          "description": "The component's name, what it is for: health bar, Quit button, inventory slot. Read to decide what to draw; never drawn."
+        },
+        "kind": {
+          "enum": ["rect", "ellipse", "polygon"],
+          "description": "The component's outline: a rectangle (with `radius` for rounded corners), an ellipse, or a regular polygon of `sides`."
+        },
+        "x": { "type": "integer", "minimum": 0, "description": "Left edge, in canvas pixels." },
+        "y": { "type": "integer", "minimum": 0, "description": "Top edge, in canvas pixels." },
+        "width": { "type": "integer", "minimum": 4, "description": "Width in pixels; x + width is at most the canvas's width." },
+        "height": { "type": "integer", "minimum": 4, "description": "Height in pixels; y + height is at most the canvas's height." },
+        "radius": { "type": "integer", "minimum": 0, "description": "A rect's corner radius, in pixels." },
+        "sides": { "type": "integer", "minimum": 3, "maximum": 8, "description": "A polygon's sides, its first corner at the top. Required for a polygon." },
+        "caption": { "type": "string", "maxLength": 24, "description": "Text drawn on the piece, exactly, such as Quit. The only text the art carries." },
+        "note": { "type": "string", "maxLength": 200, "description": "What the piece is or looks like, such as a full red health bar." },
+        "border": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The frame's width in pixels, which gives the piece nine-slice insets so it stretches; twice it is less than the shorter side."
+        },
+        "hollow": {
+          "type": "boolean",
+          "description": "Transparency: true draws only the border and leaves the inside fully transparent, as a minimap frame or a window. Needs `border`."
+        }
+      },
+      "allOf": [
+        { "if": { "properties": { "kind": { "const": "polygon" } } }, "then": { "required": ["sides"] } },
+        { "if": { "properties": { "hollow": { "const": true } }, "required": ["hollow"] }, "then": { "required": ["border"] } }
+      ]
+    }
+  }
+}