ZZD public AI gateway · zzd_public_ai_gateway_v3
Resource: 04 · Show and Piece contract / 字段
Canonical map: https://zzd.show/docs/ai/map.json
Full handbook: https://zzd.show/llms-full.txt
REST capabilities: https://zzd.show/api/v1/capabilities/

# Public Show contract

Treat the fields below as the author-facing contract. The signed-in
editor and scoped REST v1 expose different safe subsets.

## Show fields an AI may prepare

- `title` — required; at most 50 characters.
- `desc` — concise public description; at most 255 characters.
- `prompt` — a procedural brief for a future AI editing this Show.
  Describe composition, editable content/media roles, motion and
  state behavior, responsive constraints, and acceptance checks.
  Do not put provenance, source URLs, worker notes, audit evidence,
  secrets, or private reasoning here.
- `context` — short application context; at most 255 characters.
- `category` — bounded lowercase platform slug when using REST v1.
- `tags` — accurate discovery labels; never keyword spam.
- `cdns` — pinned shared browser-library dependencies.
- `esm` — explicit ES module/import configuration when needed.
- `pieces[]` — the live editable source.
- `thumbnail` — a fresh image of the final usable state.
- `favicon` — optional supported image/icon file.
- `private` — access control. `true` means only authorized users can
  access it.
- `hidden` — discovery control. `true` excludes it from ordinary
  listings even if access is public.
- `is_component` — only when the Show is intentionally reusable as
  a component.

REST v1 metadata create/PATCH currently accepts only `title`,
`desc`, `prompt`, `context`, `category`, `tags`, `cdns`, and `esm`.
Pieces use the dedicated whole-tree PUT. Assets and bounded BaaS use
their own routes. A verified thumbnail uses the dedicated multipart
POST and owner-scoped content GET. Favicon editing and component
controls remain signed-in UI actions. REST clients cannot write
`private` or `hidden` directly: draft-producing mutations force both
true and the confirmed publication route changes both together.

`private` and `hidden` are independent:

- private + hidden: normal draft;
- public + hidden: accessible by link but not normally discoverable;
- public + visible: published and discoverable;
- private + visible is not a valid way to grant public access.

Author, ownership, IDs, timestamps, counters, buyers, audit status,
compiled output, backend binding internals, and generated URLs are
platform-managed/read-only unless a specific capability says
otherwise.

## Piece fields

Each Piece has:

- `name` — meaningful, unique within the Show; at most 30 characters;
- language/type — HTML, CSS, or JavaScript;
- `raw` — formatted, readable, authoritative live source;
- module/import-map settings only when the runtime needs them.

The platform may derive or cache compiled output. Never make compiled
output the only source. After changing raw source, ensure the editor
intentionally rebuilds or clears stale compiled output and reopen all
preview environments.

There is no mandatory one-file-per-concept schema. Split by real
responsibility when useful: semantic structure, design tokens/styles,
content/data, media roles, state/routes, motion/timelines, and safety
adapters. The readable Piece that claims to own a behavior must
causally control the rendered behavior.

Suggested metadata example:

```json
{
  "title": "城市回声",
  "desc": "一个可交互的声音与地图叙事体验",
  "prompt": "保持三段叙事顺序；地点卡片可编辑；滚轮推进时间线；移动端改为纵向滚动；验证静音与无定位权限状态。",
  "context": "面向移动端与桌面的互动故事",
  "tags": ["互动叙事", "地图", "音频"],
  "private": true,
  "hidden": true
}
```

Do not paste this example blindly. Use the user's actual product,
language, accessibility needs, and distribution intent.