uvd-describe-sdk 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,226 @@
1
+ # Changelog
2
+
3
+ Newest first. A version listed here is a version on `main`, **not** a version on
4
+ npm: publishing is a manual run of `publish.yml` on `main` with that version,
5
+ and never part of the change that bumps the number.
6
+
7
+ ⚠️ Corrected 2026-09-30 (DN-PUB-01). This read *"publishing is a `vX.Y.Z` tag,
8
+ and the tag is pushed by whoever releases"*. That is how 0.1.0, 0.2.0, 0.3.0
9
+ and 0.4.1 went out. Since DN-PUB-01 a tag on a commit that carries this
10
+ `publish.yml` triggers nothing; older revisions of the file keep their old
11
+ triggers and the stored token until the owner completes steps 3 and 4 of its
12
+ header.
13
+
14
+ This file starts at 0.4.0. The versions before it are summarised from their
15
+ commits, so they are shorter than they deserve — `git log` has the measurements.
16
+
17
+ ## Unreleased (DN-PUB-01, no version bump)
18
+
19
+ ### Changed
20
+
21
+ - **Publishing is trusted publishing (OIDC), by hand, from `main`** (DN-PUB-01).
22
+ `publish.yml` runs only on `workflow_dispatch` with a `version` input that must
23
+ equal `package.json`, and no longer on a `v*` tag. It holds no npm token: the
24
+ `publish` job, the only one with `id-token: write`, runs in the `npm`
25
+ environment, with no reviewer. `src/publish-workflow.test.ts` fails if
26
+ a token, a trigger other than the dispatch, the environment or the main-only
27
+ check comes back or goes away. CI on `push` now runs only when a file it reads
28
+ changes.
29
+
30
+ ## 0.5.0 — 2026-09-30 (not published yet)
31
+
32
+ ### Added — `uvd-describe-sdk/widget`
33
+
34
+ One component for "a describe.net score, with its credit", for every surface of
35
+ the stack (WDG-01). Execution Market and MeshRelay showed the credit as a native
36
+ `title=` tooltip; KarmaKadabra had built the one styled card. The subpath takes
37
+ the card from KarmaKadabra, the link rule and the untranslated credit from
38
+ Execution Market, and the custom face from MeshRelay.
39
+
40
+ - **`<describe-score>`**, a custom element with a shadow root, registered only by
41
+ `defineDescribeScore(tagName = 'describe-score')`. It returns `false` and does
42
+ nothing without `customElements` (Node, SSR) or when the tag is taken.
43
+ Importing the subpath registers nothing and touches no `document`.
44
+ - Attributes, each reflected as a property: `score`, `wallet`, `query`,
45
+ `reviews`, `identities`, `chains`, `policy`, `refreshed-at`, `retrieved-at`,
46
+ `lang` (`es` / `en` / `pt`), `theme` (`auto` / `light` / `dark`), `placement`
47
+ (`bottom-start` / `bottom-end`).
48
+ - **`buildDescribeScoreCard(data, lang)`**, the pure model the element paints,
49
+ for tests and for painting the card by hand. Types `DescribeScoreData`,
50
+ `DescribeScoreCard`, `DescribeScoreCardRow`, `DescribeScoreLang`,
51
+ `DescribeScoreElement`, and `DESCRIBE_ATTRIBUTION`.
52
+ - Theme through `--describe-score-*` custom properties, defaulting to
53
+ describe.net's own tokens in both themes; `::part(link)`, `::part(face)`,
54
+ `::part(card)`.
55
+ - `examples/widget.html`, a local demo with no network.
56
+
57
+ ### Rules it keeps
58
+
59
+ - An absent, empty or non-decimal score paints "no data", never `0`
60
+ (`Number('')` is `0`, so the element does not use it).
61
+ - No network: no `fetch`, no remote image or font. It paints only what the host
62
+ holds, which is why it does not contradict describe.net publishing no widget
63
+ (`describenet/badge.py:13-24`).
64
+ - No `innerHTML`: every host string lands through `textContent` or an attribute.
65
+ - Zero runtime dependencies. `widget/index` joins the CI check with the empty
66
+ set.
67
+ - A date is formatted only when it is ISO 8601 with a time; anything else is
68
+ shown raw. `new Date()` alone turns `"Version 2"` into Feb 1, 2001 and a bare
69
+ `2026-09-30` into the previous day west of UTC.
70
+ - A `wallet` or `query` that cannot be URL-encoded (a lone surrogate) gets no
71
+ link. `encodeURIComponent` throws there, and uncaught it left the face empty.
72
+ - `Escape` always closes an open card, and is consumed only when the card is
73
+ open by keyboard focus on its trigger. Opened by hover alone, the key still
74
+ reaches the control that has focus.
75
+
76
+ ### Measured while building it (details in the README)
77
+
78
+ - React 18.3.1 renders `className` on a custom element as a literal `classname`
79
+ attribute. React 19.2.0 translates it. The README's JSX declaration omits
80
+ `className` so the mistake does not compile.
81
+ - A `<slot>` fallback does not render when the only child is whitespace
82
+ (Chromium: one assigned text node, fallback 0 px wide).
83
+ - Python's `http.server` on Windows serves `.mjs` as `text/plain`, and the
84
+ browser refuses the module.
85
+ - The first viewport clamp measured the card during a `transform` transition
86
+ and let it overflow by 7 px from the second opening on; the shift now lives
87
+ in the untransitioned `translate` property.
88
+
89
+ ### Dev only
90
+
91
+ - `happy-dom` (devDependency) for the DOM tests.
92
+ - `package-lock.json` said `0.1.0` in its own `version` field; it now matches.
93
+
94
+ ### Also in this version: FG-DN-03, landed on `main` before this bump
95
+
96
+ Listed here as *Unreleased (FG-DN-03, no version bump)* until 0.5.0; it ships
97
+ in 0.5.0.
98
+
99
+ #### Changed
100
+
101
+ - **`schema/` is describe.net's committed spec, vendored.** `schema/openapi.json`
102
+ and `schema/sdk.overlay.yaml` (Overlay 1.0.0) are byte-for-byte copies from
103
+ describe-net, pinned by sha256 in `schema/SOURCE`. They replace the
104
+ hand-refreshed `schema/openapi.snapshot.json`. `npm run schema:refresh` now
105
+ re-vendors from a describe-net checkout instead of writing the live spec.
106
+ - **`schema/sdk-map.json`**: every operation the overlay does not hide is either
107
+ called by a public `DescribeClient` method (`mapeadas`) or listed in `fuera`
108
+ with its reason. `src/sdk-map.test.ts` runs each method against a recording
109
+ `fetch` and fails on an unclassified operation or a route outside the spec.
110
+ - **`schema:check` watches what the map says.** The schemas it compares are
111
+ derived from the responses of the mapped operations (21, transitively; the
112
+ hand-written list had 8), and the operations the overlay hides (web app,
113
+ `/mcp`, `/a2a`) no longer count.
114
+
115
+ #### Unchanged, on purpose
116
+
117
+ - The client, its types and its parsers. `/names/resolve` and `/names/reverse`
118
+ are in `fuera`, not implemented.
119
+
120
+ ## 0.4.1 — 2026-09-15 (not published yet)
121
+
122
+ ### Added
123
+
124
+ - **`CAVEAT_CODES` gains `thin-chain`** (ten codes, the same set describe.net
125
+ serves). Served since 2026-09-04 on the wallet scope, and evaluated on the free
126
+ route as well: `GET /wallets/{wallet}/chains` evaluates `burn-address` and
127
+ `thin-chain`, and declares the other seven wallet-scope codes in
128
+ `caveatsNotComputed`. `isKnownCaveatCode('thin-chain')` is now `true`. The
129
+ Python twin adds the same literal in its own release.
130
+
131
+ ### Unchanged, on purpose
132
+
133
+ - Types, parsers, the client and `requireFullCaveats()` behave exactly as in
134
+ 0.4.0. A `thin-chain` caveat already arrived whole; this release only makes it
135
+ a known code (autocomplete, `switch`, `isKnownCaveatCode`).
136
+
137
+ ## 0.4.0 — 2026-09-15 (not published yet)
138
+
139
+ Types what describe.net has served since 2026-09-14 (`describe-net` PR #21,
140
+ deployed in `aa1bd75`). Upstream-first: this version exists so that Execution
141
+ Market, KarmaKadabra, MeshRelay and karma-hello adopt the fields through the SDK
142
+ instead of reading them by hand. The Python twin (`uvd-describe-sdk` 0.6.0) ships
143
+ the same contract in its own spelling — same states, same refusals, same class
144
+ name for the error. The one intended difference is the wording of that error's
145
+ `recovery`, which names each language's own API.
146
+
147
+ ### Breaking — only for code that builds these objects by hand
148
+
149
+ - `WalletReputation.caveatsNotComputed` and `Rating.authorClass` are
150
+ **required** properties. An object literal typed as `WalletReputation`,
151
+ `Rating`, or `AgentReputation` (through `ratings`) that compiled against 0.3.0
152
+ no longer compiles against 0.4.0: `TS2741: Property 'caveatsNotComputed' is
153
+ missing` / `Property 'authorClass' is missing` (measured with `tsc --strict`).
154
+ Typically a test fixture or a mock. Fix: add the two fields, or build the
155
+ object from a payload with `parseWalletReputation()` / `parseAgentReputation()`,
156
+ which fill them.
157
+ - If you have nothing to put there, write `null` in both — never `[]`, which
158
+ claims every cut was evaluated, and never `'rater-authored'`, which claims a
159
+ signer the index cannot vouch for.
160
+ - They stay required on purpose, and what the parsers return is unchanged.
161
+ Making them optional would add a fourth state, `undefined`, to every result
162
+ of `wallet()` and `agent()`, next to the three (`[]`, a list, `null`) this
163
+ version exists to keep apart.
164
+ - Code that only reads what the client or the parsers return is not affected.
165
+
166
+ ### Added
167
+
168
+ - **`WalletReputation.caveatsNotComputed: CaveatCode[] | null`** — the caveat
169
+ codes `GET /wallets/{wallet}/chains` did NOT evaluate (seven on 2026-09-15).
170
+ `null` means nothing readable was declared (a server older than 2026-09-14, a
171
+ stored payload, or a value that is not a list of non-empty strings) and is
172
+ deliberately **not** `[]`, which is a declaration.
173
+ - **`requireFullCaveats(rep)`** — returns `rep` only when it declared `[]`;
174
+ throws `CaveatsNotComputedError` for a declared list AND for `null`; throws a
175
+ `TypeError` for anything that is not the `WalletReputation` of `wallet()`
176
+ (a metered result, a `null` response, a raw payload).
177
+ - **`CaveatsNotComputedError`** (`wallet`, `notComputed`, `recovery`). Extends
178
+ `Error`, **not** `DescribeError`: a consumer's fail-open `catch` on
179
+ `DescribeError` must not be able to swallow a refusal as an outage.
180
+ - **`Rating.authorClass: AuthorClass | null`** — `facilitator-authored` or
181
+ `rater-authored`, per row. An unknown class arrives verbatim (never thrown,
182
+ never nulled); `null` means none was served.
183
+ - **`AUTHOR_CLASSES`, `isKnownAuthorClass()`, `AuthorClass`, `KnownAuthorClass`.**
184
+ - **`CAVEAT_CODES` gains `facilitator-authored`** (nine codes).
185
+
186
+ ### Known gap
187
+
188
+ - describe.net serves ten caveat codes; **`thin-chain`** (upstream since
189
+ 2026-09-04, on the free route since 2026-09-05) is still missing here and in
190
+ the Python twin. Left for one follow-up that adds it to both, so the set both
191
+ SDKs publish never differs. `isKnownCaveatCode('thin-chain')` is `false`; the
192
+ caveat itself still arrives whole.
193
+
194
+ ### Changed
195
+
196
+ - `schema/openapi.snapshot.json` refreshed from the live API (2.0.0, 22 paths:
197
+ `GET /categories` and `GET /wallets/{wallet}/exists` are new and not wrapped).
198
+ - `npm run schema:check` now also watches `Rating`, and `types.schema.test.ts`
199
+ covers it. Neither did before, which is how `author_class` becoming a required
200
+ field upstream went unreported by the refresh.
201
+
202
+ ### Unchanged, on purpose
203
+
204
+ - No method changed its return type (the types it returns gained two required
205
+ fields — see *Breaking*), nothing throws where it did not, and
206
+ `DescribeErrorKind` is untouched. The client never calls the gate; `failOpen`
207
+ and `onFailure` behave exactly as in 0.3.0.
208
+
209
+ ## 0.3.0 — 2026-09-10
210
+
211
+ `freshness`: WHEN a subject was last described, with its scope
212
+ (`WalletBreakdown.freshness`, `IndexHealth.freshness`), plus
213
+ `IndexHealth.credibilityM`. (#1, `764cab1`)
214
+
215
+ ## 0.2.0 — 2026-08-31
216
+
217
+ The SDK review round: the `pending` settlement sentinel moved out of `receipt`
218
+ into `settlementPending`, `DescribeHTTPError.serverReason`, and parsers that fail
219
+ loud when fed the wrong route's payload or their own output. (`923a9d6`)
220
+
221
+ ## 0.1.0 — 2026-08-30
222
+
223
+ First version: the free routes with `failOpen`, the metered routes paid through
224
+ `uvd-describe-sdk/x402` (and, the same day, never failing open), the partner rail,
225
+ jitter, `resolveDistinctRaters`, hash-shape validation and `recovery`.
226
+ (`99a87b2` … `8deb0c9`)
package/README.md CHANGED
@@ -17,6 +17,10 @@ subpaths so a free-only consumer installs neither:
17
17
  each request instead and read the metered routes for free
18
18
  (`uvd-describe-sdk/partner`, see [the partner rail](#not-paying-the-partner-rail)).
19
19
 
20
+ And to **draw** a score once you have it, `uvd-describe-sdk/widget` is
21
+ `<describe-score>`: the number, its credit and its card, one component for every
22
+ surface. It makes no network call. See [Widget](#widget-describe-score).
23
+
20
24
  ---
21
25
 
22
26
  ## Sixty seconds
@@ -119,16 +123,65 @@ if (hasCaveat(rep, 'burn-address')) { /* nobody controls this address */ }
119
123
  if (hasCaveat(rep, 'few-raters')) { /* thin evidence */ }
120
124
  ```
121
125
 
122
- The eight codes are exported and typed: `no-score`, `concentration-degraded`,
126
+ The ten codes are exported and typed: `no-score`, `concentration-degraded`,
123
127
  `single-rater`, `few-raters`, `top-client-share`, `campaign-per-rater`,
124
- `self-rated`, `burn-address`. The union stays **open**, so a ninth code the
125
- server adds tomorrow will not be a type error in code you already shipped.
128
+ `self-rated`, `burn-address`, `thin-chain` (since 0.4.1; served since 2026-09-04,
129
+ on the free route too), `facilitator-authored` (since 0.4.0). The union stays
130
+ **open**, so a code the server adds tomorrow will not be a type error in code you
131
+ already shipped: `isKnownCaveatCode()` answers `false` for it, and the caveat
132
+ still arrives whole.
126
133
 
127
134
  ⚠️ On free routes `caveats: []` means *no **public-data** caveat*, not "clean" —
128
135
  the evidence-quality cuts need the grain and ride the metered routes. Check
129
136
  `rep.caveatScope` (`public-data-subset` vs `full`) before calling anything
130
137
  clean.
131
138
 
139
+ **Since 0.4.0 the free route names the cuts it skipped, and there is a gate for
140
+ it.** karma-hello found the trap (2026-08-31): a quality gate on `wallet()`
141
+ passes *every* wallet, because the cuts it checks never ran. describe.net now
142
+ declares them in `caveats_not_computed` (`rep.caveatsNotComputed`), and
143
+ `requireFullCaveats` is the gate that reads the declaration:
144
+
145
+ ```ts
146
+ import { CaveatsNotComputedError, requireFullCaveats } from 'uvd-describe-sdk';
147
+
148
+ const rep = await describe.wallet(w);
149
+ if (rep === null) { /* no answer at all: decide that first */ }
150
+
151
+ try {
152
+ requireFullCaveats(rep);
153
+ } catch (e) {
154
+ if (e instanceof CaveatsNotComputedError) {
155
+ e.notComputed; // ['campaign-per-rater', …] — or null: nothing was declared
156
+ e.recovery; // the route that does evaluate them
157
+ }
158
+ }
159
+ ```
160
+
161
+ | `rep.caveatsNotComputed` | `requireFullCaveats(rep)` |
162
+ |---|---|
163
+ | `[]` | returns `rep` — the only state that passes |
164
+ | `['few-raters', …]` | throws; `notComputed` is the list |
165
+ | `null` — a server before 2026-09-14, a payload stored before then, or a declaration that cannot be read whole | **throws**; `notComputed` is `null` |
166
+
167
+ 🔴 **Today it throws for every free answer** (seven codes declared on
168
+ 2026-09-15). That is the gate working: the evidence-quality cuts are what
169
+ `walletBreakdown()` sells, and a decision that needs them reads that — or the
170
+ partner rail. `null` is not `[]`: an old answer's silence is the old gap, not a
171
+ clean bill (describe.net's position of 2026-08-31 is *"el scope es la señal"*,
172
+ and its own MCP tool keeps the same `None`). Passing means the caveats are
173
+ **complete**, not empty — ask `hasCaveat()` after the gate.
174
+
175
+ Two things it is not, on purpose — and the Python twin (`require_full_caveats`,
176
+ `CaveatsNotComputedError`) makes the same two choices:
177
+
178
+ * **Not a `DescribeError`.** A refusal is a successful read that does not support
179
+ the decision. A `catch` that fails open on `DescribeError` must not be able to
180
+ read it as "describe is down" and wave the subject through.
181
+ * **Not for metered results.** It takes the `WalletReputation` of `wallet()` and
182
+ throws a `TypeError` for anything else: a breakdown evaluates its own scope and
183
+ declares no omissions.
184
+
132
185
  ### 4. One display format, ecosystem-wide
133
186
 
134
187
  **Two decimals, trailing zeros trimmed.** `86.65`, `84.7`, `87` — never `82.0`.
@@ -462,6 +515,228 @@ server already knows which is which. Measured cost of signing everything:
462
515
 
463
516
  ---
464
517
 
518
+ ## Widget: `<describe-score>`
519
+
520
+ One component for "a describe.net score, with its credit", for every surface of
521
+ the stack. Until 0.5.0 three repos drew it three ways: Execution Market and
522
+ MeshRelay put `Powered by describe.net` in a native `title=` (the grey box the
523
+ operating system draws), and KarmaKadabra built a styled card. This is that card,
524
+ with EM's link rule and credit and MeshRelay's custom face, behind its own
525
+ subpath so that importing the root in Node never meets a DOM.
526
+
527
+ ![describe-score in light and dark, with and without a score, cards open](docs/widget/describe-score-demo.png)
528
+
529
+ ```ts
530
+ import { defineDescribeScore } from 'uvd-describe-sdk/widget';
531
+
532
+ defineDescribeScore(); // registers <describe-score>. Importing registers nothing.
533
+ ```
534
+
535
+ ```html
536
+ <describe-score score="83.0" wallet="0x97cd…0996" reviews="123"
537
+ policy="equal-weight-per-chain@2" refreshed-at="2026-09-30T14:15:39Z"
538
+ lang="es"></describe-score>
539
+ ```
540
+
541
+ `defineDescribeScore()` returns `false` and does nothing where there is no
542
+ `customElements` (Node, SSR) or when the tag is already defined, so calling it
543
+ at module scope in a server-rendered app is safe. `defineDescribeScore('my-tag')`
544
+ registers another name.
545
+
546
+ ### It makes no network call, and that is why it can exist
547
+
548
+ describe.net deliberately publishes no widget (`describenet/badge.py:13-24`): only
549
+ an `<img>` + SVG, because a site that embeds a widget which *transmits* data is
550
+ co-responsible for it, and because a `fetch` per pageview would burn a rate limit
551
+ every consumer shares. This component does not contradict that. It fetches
552
+ nothing, loads no image and no font, and paints only what the host already read
553
+ through `DescribeClient`. It draws a number; it does not get one. The only URL in
554
+ it is the link to the public profile, which the reader chooses to follow.
555
+
556
+ ### `null` is never `0`, here either
557
+
558
+ An absent, empty or non-numeric `score` paints **"no data"** (`sin datos`,
559
+ `sem dados`), never `0`. Pass `rep.globalScore` as it comes: React drops the
560
+ attribute for `null` (measured on React 18.3.1 and 19.2.0), and the element
561
+ reads an absent attribute as no data. It does not use `Number(attr)`, because
562
+ `Number('')` is `0`. A real `0` is a score and paints `0`.
563
+
564
+ ### Attributes
565
+
566
+ Every attribute is also a property that reflects it (`el.refreshedAt` ↔
567
+ `refreshed-at`).
568
+
569
+ | Attribute | What it carries | Shown as |
570
+ |---|---|---|
571
+ | `score` | `globalScore` | the face, written by `formatScore` (`83.0` → `83`) |
572
+ | `wallet` | EVM or Solana base58 | link to `describe.net/agent.html?wallet=…` |
573
+ | `query` | fallback lookup | `?q=…` when there is no wallet. With neither — or with a value that cannot be URL-encoded, such as a name cut in half an emoji — **no link** |
574
+ | `reviews` · `identities` · `chains` · `policy` | `totalReviews` · `identityCount` · `chainsWithReputation` · `policyVersion` | a row each, **only if it came** |
575
+ | `refreshed-at` · `retrieved-at` | when describe.net refreshed it · when you read it (ISO 8601 with a time) | a readable date (`Intl`, medium + short). Anything else is shown raw — a bare `2026-09-30` too, which `new Date()` would print as the previous day west of UTC |
576
+ | `lang` | `es` \| `en` \| `pt`, or a full tag (`es-CO`) | default: `<html lang>`, then `en`. Read at render, so a host that switches language at runtime passes it |
577
+ | `theme` | `auto` (default) \| `light` \| `dark` | `auto` follows `prefers-color-scheme` |
578
+ | `placement` | `bottom-start` (default) \| `bottom-end` | the card is kept inside the viewport either way |
579
+
580
+ The credit (`Powered by describe.net`, and `POWERED BY DESCRIBE.NET` on the
581
+ card) is **never translated**. It is exported as `DESCRIBE_ATTRIBUTION` for the
582
+ one visible credit a site carries in its footer.
583
+
584
+ 🔴 **Tailwind `darkMode: 'class'` is invisible to a shadow root.** A media query
585
+ cannot see a `.dark` class on `<html>`, and `:host-context()` is Chromium-only.
586
+ A host that themes by class (Execution Market) passes `theme` itself.
587
+
588
+ ### The face
589
+
590
+ With no children the element paints the formatted score and inherits the font
591
+ and colour of the element, so the host's classes style the number. With
592
+ children, the children are the face (MeshRelay's bar):
593
+
594
+ ```html
595
+ <describe-score score="81.86" wallet="0x…"><span class="bar">…</span></describe-score>
596
+ ```
597
+
598
+ Whitespace does not count as a child. A plain `<slot>` fallback would show
599
+ nothing for `<describe-score score="83">⏎</describe-score>`: measured in
600
+ Chromium, one whitespace text node is assigned to the slot and the fallback
601
+ measures 0 px.
602
+
603
+ ### Styling
604
+
605
+ | Custom property | Default (light / dark), from describe.net's `theme-describeme.css` |
606
+ |---|---|
607
+ | `--describe-score-bg` | `#ffffff` / `#1e1b2d` (`--surface-raised`). Painted with `background`, so a gradient works |
608
+ | `--describe-score-border` | `#e2ded4` / `#2c2840` (`--border-subtle`) |
609
+ | `--describe-score-text` | `#1a1730` / `#f2f0ea` (`--text-primary`) |
610
+ | `--describe-score-text-secondary` | `#4a4668` / `#c3bfd4` (`--text-secondary`) |
611
+ | `--describe-score-accent` | `#332c86` / `#a9a2ff` (`--accent`) |
612
+ | `--describe-score-radius` | `0.375rem` (`--radius-surface`) |
613
+ | `--describe-score-shadow` | `--shadow-overlay` |
614
+ | `--describe-score-font` | the system sans stack. The card never inherits the number's font |
615
+
616
+ The contrast of every default text colour against its background is computed
617
+ in the tests (WCAG AA, both themes). Parts: `::part(link)`, `::part(face)`,
618
+ `::part(card)`.
619
+
620
+ ```css
621
+ /* KarmaKadabra's card, through the properties */
622
+ describe-score {
623
+ --describe-score-bg: linear-gradient(160deg, #4c2f8f 0%, #3b2470 100%);
624
+ --describe-score-border: rgba(201, 162, 255, .34);
625
+ --describe-score-text: #f3efff;
626
+ --describe-score-text-secondary: #d9ccff;
627
+ --describe-score-accent: #c9a2ff;
628
+ }
629
+ /* Mute the NUMBER, not the element: */
630
+ describe-score.empty::part(face) { opacity: .6; }
631
+ ```
632
+
633
+ ⚠️ `opacity`, `filter` and `transform` on the element itself apply to its whole
634
+ box, **card included**. Style the number through `::part(face)`. The card is
635
+ positioned inside the element, so an ancestor with `overflow: hidden` clips it.
636
+ The element puts a `<style>` in its shadow root; a Content-Security-Policy whose
637
+ `style-src` forbids inline styles would block it (none of the three hosts sends
638
+ one as of 2026-09-30).
639
+
640
+ ### Accessibility (WCAG 1.4.13, 2.1.1)
641
+
642
+ - The card opens on **hover and on keyboard focus**. With a link, the link is
643
+ the trigger; without one, the face takes `tabindex="0"`, so the card that
644
+ explains "no data" can still be read without a mouse.
645
+ - The trigger's `aria-describedby` points to the card (`role="tooltip"`).
646
+ - **Hoverable**: a transparent bridge covers the gap between number and card.
647
+ - **Dismissible**: `Escape` closes it without moving focus. When the card is
648
+ open because its trigger has keyboard focus, that `Escape` is consumed, so a
649
+ modal behind it (EM renders scores inside modals) does not close on the same
650
+ keypress. When it is open by hover alone, it closes and the `Escape` still
651
+ reaches the control that has focus (a textarea, a combobox). While no card is
652
+ open nothing listens.
653
+ - `prefers-reduced-motion` removes the transition. The card is clamped to the
654
+ viewport on narrow screens.
655
+
656
+ ### React (Execution Market, MeshRelay)
657
+
658
+ Declare the element once in the host, for example `src/types/describe-score.d.ts`
659
+ (type-checked against `@types/react` 18.3.3 and 19.2.5):
660
+
661
+ ```ts
662
+ import type { HTMLAttributes } from 'react';
663
+
664
+ type DescribeScoreAttributes = Omit<HTMLAttributes<HTMLElement>, 'className'> & {
665
+ /** React 18 writes `className` on a custom element as a literal `classname` attribute. */
666
+ class?: string;
667
+ score?: number | string | null;
668
+ wallet?: string | null;
669
+ query?: string | null;
670
+ reviews?: number | string | null;
671
+ identities?: number | string | null;
672
+ chains?: number | string | null;
673
+ policy?: string | null;
674
+ 'refreshed-at'?: string | null;
675
+ 'retrieved-at'?: string | null;
676
+ theme?: 'auto' | 'light' | 'dark';
677
+ placement?: 'bottom-start' | 'bottom-end';
678
+ };
679
+
680
+ declare module 'react' {
681
+ namespace JSX {
682
+ interface IntrinsicElements {
683
+ 'describe-score': DescribeScoreAttributes;
684
+ }
685
+ }
686
+ }
687
+ ```
688
+
689
+ ```tsx
690
+ import { defineDescribeScore } from 'uvd-describe-sdk/widget';
691
+ defineDescribeScore();
692
+
693
+ <describe-score
694
+ class="text-sm font-semibold"
695
+ score={rep.globalScore}
696
+ wallet={rep.wallet}
697
+ reviews={rep.totalReviews}
698
+ identities={rep.identityCount}
699
+ policy={rep.policyVersion}
700
+ refreshed-at={rep.refreshedAt}
701
+ lang={i18n.language}
702
+ theme={isDark ? 'dark' : 'light'}
703
+ />
704
+ ```
705
+
706
+ 🔴 **On React 18, `className` does not work on a custom element.** Measured with
707
+ React 18.3.1: `<describe-score className="text-sm">` renders the attribute
708
+ `classname="text-sm"`, which no stylesheet matches. React 19 translates it to
709
+ `class`. The declaration above leaves `className` out so the React 18 mistake is
710
+ a compile error; on React 19 (MeshRelay) you may drop the `Omit`.
711
+
712
+ ### HTML without a bundler (KarmaKadabra)
713
+
714
+ `dist/widget/index.mjs` imports nothing (asserted in CI), so it vendors as one file:
715
+
716
+ ```html
717
+ <script type="module">
718
+ import { defineDescribeScore } from '/vendor/uvd-describe-sdk/widget.mjs';
719
+ defineDescribeScore();
720
+ </script>
721
+ ```
722
+
723
+ ⚠️ **The server must send `.mjs` as `text/javascript`.** A module served as
724
+ `text/plain` is refused by the browser and nothing renders. Measured: Python's
725
+ `http.server` on Windows guesses `text/plain` for `.mjs`. Check the
726
+ `Content-Type` your server or bucket gives the file, or vendor it as `.js`.
727
+
728
+ ### Painting it yourself
729
+
730
+ `buildDescribeScoreCard(data, lang)` returns what the card shows (`face`,
731
+ `title`, `seal`, `text`, `rows`, `href`, `hasScore`, `openHint`) with no DOM and
732
+ no network. Use it to test a surface in Node, or to draw the same card where a
733
+ custom element cannot run.
734
+
735
+ Demo, no network: `npm run build`, serve the repo root (`npx serve .`), open
736
+ `/examples/widget.html` (add `?pin` to open every card at once).
737
+
738
+ ---
739
+
465
740
  ## Jitter, on by default
466
741
 
467
742
  Every request waits a random `[0, 400)` ms first. **That is on unless you turn
@@ -548,6 +823,33 @@ and an alarm that screams about good data is worse than no alarm.
548
823
 
549
824
  ---
550
825
 
826
+ ## Who signed a rating: `authorClass`
827
+
828
+ Since describe.net 2026-09-14 every row of `agent().ratings` carries the class of
829
+ whoever **signed** it:
830
+
831
+ ```ts
832
+ const agent = await describe.agent('base', 42);
833
+ const relayed = agent.ratings.filter((r) => r.authorClass === 'facilitator-authored');
834
+ ```
835
+
836
+ * `facilitator-authored` — `client` is a known relayer (today the x402
837
+ facilitator's EVM wallet) writing on behalf of the real rater. `client` is
838
+ **not** the counterparty, and every such row shares it, so any per-rater count
839
+ merges them into one voice. The agent answer then also carries the caveat of
840
+ the same name.
841
+ * `rater-authored` — `client` is not a relayer the index knows about. It does
842
+ **not** prove who signed.
843
+ * `null` — no class was served (an older server, or a stored payload). Unknown,
844
+ and never defaulted to `rater-authored`.
845
+
846
+ The union is **open**: a class the server adds later arrives verbatim — never
847
+ thrown, never nulled — and `isKnownAuthorClass()` tells you whether this SDK has
848
+ heard of it. There is no count or score by author class, upstream or here; what
849
+ to do with the rows you bought is your call.
850
+
851
+ ---
852
+
551
853
  ## Counting distinct raters
552
854
 
553
855
  ```ts
@@ -631,8 +933,10 @@ Never hardcode a threshold. `health()` publishes the live `readingPolicy` and
631
933
 
632
934
  Hand-written, and tied to the schema by two gates rather than by a generator:
633
935
 
634
- - `npm test` — offline, compares the types against a pinned
635
- `schema/openapi.snapshot.json`. Answers *did we drift?*
936
+ - `npm test` — offline, compares the types against `schema/openapi.json`, the
937
+ describe.net spec vendored with its sha256 in `schema/SOURCE`, and checks
938
+ `schema/sdk-map.json`: every public operation is called by a method or listed
939
+ in `fuera` with its reason. Answers *did we drift?*
636
940
  - `npm run schema:check` — re-fetches the live OpenAPI and diffs it. Answers
637
941
  *did they move?*
638
942
 
@@ -650,7 +954,7 @@ cycle.
650
954
 
651
955
  ```bash
652
956
  npm install
653
- npm test # offline. 93 tests, no network
957
+ npm test # offline, no network. 336 tests on 2026-09-30 (227 on 2026-09-15)
654
958
  npm run typecheck
655
959
  npm run lint
656
960
  npm run build