From f1539195a2a9df2f988ec920bef2ec4d2b2bb95a Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Mon, 16 Nov 2026 10:09:39 +0100 Subject: [PATCH] Move icon words API docs to own file Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WzxdWYNS1qAMRdgAtbr5Rq --- DOCS-icon-words.md | 14 ++++++++++++++ DOCS-web-control-api.md | 11 +---------- 2 files changed, 15 insertions(+), 10 deletions(-) create mode 100644 DOCS-icon-words.md diff --git a/DOCS-icon-words.md b/DOCS-icon-words.md new file mode 100644 index 0000000..4b04445 --- /dev/null +++ b/DOCS-icon-words.md @@ -0,0 +1,14 @@ +# Icon words API + +Part of the web control API ([DOCS-web-control-api.md](DOCS-web-control-api.md)). + +## `/api/icon-words` + +`GET /api/icon-words` → `IconLedger`; `POST` or `PUT /api/icon-words/{icon_id}` with `{word?, glyph?}` → `IconLedger` (200). Writes need Host, Origin and `X-SBE-Token` like every non-GET. TS mirror: `web/src/api/iconWordsContract.ts`. + +- **Ledger** `web/src/ui/icon_words.json` (a repo file the user commits; `SBE_ICON_WORDS` overrides the path): `{"version":1,"icons":{"":{"word":""|null,"glyph":""|null}}}`. Absent id = unanswered; no `word` key = only a glyph chosen; `word: null` = skipped (no label); `glyph: null` = default. The server reads it per request and never builds from it (`_web_build` ignores it); writes go to a sibling temp file, then rename. +- **Registry** `web/src/icons/registry.json`: id → default glyph, spoken name, description, 3 suggested words, 3 alternative glyphs (`registry.ts` types it). +- **`word`**: any text; casing kept, whitespace runs collapsed; 1–40 characters, no control characters, else `invalid_params`. `null` skips. **`glyph`**: the default or one of the icon's 3 alternatives (the default is stored as `null`), else `invalid_params`. Unknown id → `not_found`; empty body or unknown key → `invalid_params`. +- Every served `.html` page carries the ledger as `