cardano-tessera-respond 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work, excluding
+          those notices that do not pertain to any part of the Derivative
+          Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Matthieu Pizenberg and Tessera contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,456 @@
+# cardano-tessera-respond
+
+The embeddable **`<tessera-respond>`** custom element: drop it into any web page to
+let a user answer a [CIP-179](../../frontend/cip-179.md) survey. Give it a survey
+definition and a responder (a role→credential map) as props; it renders the answering UI,
+validates the answers, timelock-encrypts them for a sealed survey, and emits a
+**ready-to-attach label-17 `Metadatum`** back to you via a `CustomEvent`. You
+attach that payload to a transaction and submit it.
+
+Framework-agnostic (it's a Web Component — use it from React, Vue, Svelte, Solid,
+or plain HTML). **The widget never touches a wallet, a chain, IPFS,
+`localStorage`, or your page's `<html>`.** Connecting a wallet, reading the chain,
+building/signing/submitting the transaction, and network conformance are all
+yours.
+
+## Division of labor
+
+| Concern                                                              | Owner                                             |
+| :------------------------------------------------------------------- | :------------------------------------------------ |
+| Wallet connection (CIP-30/95), signing, submission                   | **Host**                                          |
+| Network conformance (wallet network ↔ target chain)                  | **Host** — the widget never sees a network id     |
+| Fetching / enriching the `SurveyDefinition`                          | **Host**                                          |
+| Supplying the chain tip (`tipEpoch`) and cancellation (`cancelled`)  | **Host** (props, refreshed as it sees fit)        |
+| IPFS pinning for a rationale                                         | **Host** (passes a pre-pinned anchor)             |
+| Rendering the form, validation, sealed encryption, label-17 encoding | **Widget**                                        |
+| Open/closed gating from the tip; quicknet check for a sealed survey  | **Widget** (`surveyStatus` from `cip-179/domain`) |
+
+The widget hands you a validated (and, if sealed, already-encrypted) payload. You
+are responsible only for attaching it at metadata label 17, **proving** each
+declared credential through the carrying transaction (see
+[Proving credentials](#proving-credentials)), signing, and submitting.
+
+## Install
+
+```sh
+npm install cardano-tessera-respond
+```
+
+```ts
+import "cardano-tessera-respond"; // registers <tessera-respond>
+import type { RespondResult } from "cardano-tessera-respond";
+```
+
+The published package is the self-contained built artifact — Solid,
+`respond-core`, and the `cip-179` codec bundled in, with the full TypeScript
+contract rolled up alongside. One side-effect import registers the element;
+there is no peer dependency and no framework requirement (React, Vue, Svelte,
+Solid, or plain HTML all consume the same element). The heavy sealed-encryption
+code splits into lazy chunks fetched only when someone answers a sealed survey.
+
+No build step? Load it from an ES-module CDN (the multi-chunk `dist/` resolves
+fine there):
+
+```html
+<script type="module">
+  import "https://esm.sh/cardano-tessera-respond@0.1";
+</script>
+```
+
+Inside this repository the workspace exposes two more entries: the root export
+resolves to TypeScript **source** (the composable pieces — `RespondRoot`,
+`adoptWidgetStyles`), and `/element` is the registering Solid TSX entry. They
+are workspace-internal: the app consumes the source so `vite-plugin-solid`
+compiles it against a single Solid instance
+(see [Single Solid instance](#single-solid-instance)); npm installers get only
+the artifact. Don't try to import the raw `/element` TSX from a non-Solid
+bundler — without the Solid transform it either fails to build or renders once
+and never reacts.
+
+**Build format is ES only, by design.** `vite build` runs Rollup, which cannot
+code-split UMD/IIFE output — a UMD target would force the lazy tlock/evolution
+chunks to inline and defeat the whole point. Script-tag hosts therefore use
+`<script type="module">`; there is no UMD build.
+
+**SSR hosts (SvelteKit, Next.js, …).** Importing the artifact without a DOM is
+a no-op — module evaluation touches no `window`, and registration is guarded —
+so a plain top-level `import "cardano-tessera-respond"` is safe in
+server-rendered modules; no client-only dynamic import is needed. The server
+serializes `<tessera-respond>` as an unknown (empty) element; it upgrades once
+the bundle runs client-side and renders when your code assigns the required
+props after hydration.
+
+## Quick start (plain HTML, no bundler)
+
+```html
+<script type="module">
+  // Registers <tessera-respond>. Import the package (bundler), a CDN URL,
+  // or a relative path to its dist/ as here.
+  import "./node_modules/cardano-tessera-respond/dist/tessera-respond.es.js";
+
+  const el = document.querySelector("tessera-respond");
+
+  // Object-valued props are set as DOM PROPERTIES, not attributes.
+  el.definition = surveyDefinition; // the SurveyDefinition you fetched
+  el.surveyRef = { txId, index }; // where it lives on-chain
+  // Each role the user can answer as → its credential. Keys are the cip-179
+  // Role numbers: Keyholder 4, Stakeholder 3, DRep 0, SPO 1, CC 2.
+  el.responder = { 4: paymentCred, 3: stakeCred, 0: drepCred };
+  el.tipEpoch = currentEpoch; // from your chain-tip source
+
+  // The widget emits; you attach + sign + submit.
+  el.addEventListener("tessera:response", async (e) => {
+    const { payload, proveCredentials } = e.detail;
+    // 1. attach `payload` at metadata label 17
+    // 2. prove each proveCredentials[i].credential in the tx — via
+    //    required_signers (mechanism A) or a governance vote (mechanism B)
+    // 3. sign with the wallet, submit
+  });
+</script>
+
+<tessera-respond></tessera-respond>
+```
+
+Until every **required** prop (`definition`, `surveyRef`, `responder`,
+`tipEpoch`) is present, the element renders nothing — so writing
+`<tessera-respond>` in static HTML and assigning props later (as above) is the
+intended pattern; it upgrades and connects before your script runs.
+
+For a full **bundler + wallet + real submission** example, see the reference host
+in the app: [`frontend/app/src/ui/screens/DevWidgetHost.tsx`](../../frontend/app/src/ui/screens/DevWidgetHost.tsx).
+It embeds `<tessera-respond>` exactly as a third-party integrator would and closes
+the loop the widget leaves open — proving `proveCredentials` via `required_signers`
+(mechanism A) and signing + submitting through a CIP-30 wallet.
+
+## Props
+
+Object-valued props (everything but `locale`, `layout`, `cancelled`, `tipEpoch`,
+`initialRole`) **must be set as DOM properties** (`el.definition = …`), never as
+HTML attributes. `solid-element` exposes each as a reactive prop with a
+hyphenated attribute alias, so the string/number/boolean ones (`locale`,
+`layout`, `tip-epoch`, `initial-role`, `cancelled`) _may_ also be written as
+plain attributes. `cancelled` also works HTML boolean-attribute style — a bare
+`<tessera-respond cancelled>` means cancelled.
+
+| Prop              | Type                            | Req. | Default            | Notes                                                                                                              |
+| :---------------- | :------------------------------ | :--: | :----------------- | :----------------------------------------------------------------------------------------------------------------- |
+| `definition`      | `SurveyDefinition`              |  ✓   | —                  | On-chain, or host-enriched with off-chain labels. The widget never fetches — you supply the display definition.    |
+| `surveyRef`       | `SurveyRef` (`{ txId, index }`) |  ✓   | —                  | Where the definition lives on-chain. Rides back out on every result and into the built response.                   |
+| `responder`       | `Responder`                     |  ✓   | —                  | Who's answering — see [The responder](#the-responder--eligibility).                                                |
+| `tipEpoch`        | `number`                        |  ✓   | —                  | Current chain-tip epoch. The widget derives open/ended and blocks a closed survey. A snapshot — re-set to refresh. |
+| `cancelled`       | `boolean`                       |      | `false`            | A valid on-chain cancellation exists (you checked); renders the cancelled state, no form.                          |
+| `priorResponses`  | `readonly SurveyResponse[]`     |      | —                  | Prefill for an edit/replace flow — see [Prior responses](#prior-responses-editreplace).                            |
+| `rationaleAnchor` | `ContentAnchor`                 |      | —                  | A host-pre-pinned rationale (CIP-179 key 5). The widget never pins to IPFS.                                        |
+| `locale`          | `string` (BCP-47)               |      | `"en"`             | Drives both strings and number/date formatting — see [Internationalization](#internationalization).                |
+| `messages`        | `DeepPartial<RespondMessages>`  |      | —                  | Deep-merged string overrides, or a whole unshipped language.                                                       |
+| `theme`           | `Record<string, string>`        |      | —                  | Design-token overrides, reflected as `--tessera-<key>` on the host — see [Theming](#theming--fonts).               |
+| `layout`          | `"one-per-screen" \| "list"`    |      | `"one-per-screen"` | Stepper (one question at a time) or all questions at once.                                                         |
+| `initialRole`     | `Role`                          |      | —                  | Initial role when the responder is eligible in several. The user can still switch.                                 |
+
+## Events
+
+All three are dispatched on the element with `bubbles: true, composed: true`, so a
+listener anywhere up the light-DOM tree catches them across the shadow boundary.
+
+| Event              | `detail`               | When                                                                                        |
+| :----------------- | :--------------------- | :------------------------------------------------------------------------------------------ |
+| `tessera:response` | `RespondResult`        | The user finalizes a valid answer set. **The widget does not submit** — you do.             |
+| `tessera:change`   | `RespondChangeDetail`  | Any answer edit — `{ decided, total, valid }`, for a host-driven submit button.             |
+| `tessera:invalid`  | `RespondInvalidDetail` | Validation failed on submit — `{ problems, messages }` (structured codes + localized text). |
+
+### `RespondResult` — the payload to submit
+
+```ts
+interface RespondResult {
+  surveyRef: SurveyRef;
+  role: Role;
+  credential: Credential;
+  payload: Metadatum; // attach at metadata label 17
+  proveCredentials: CredentialProof[]; // prove each in the carrying tx
+  sealed: boolean;
+}
+
+interface CredentialProof {
+  credential: Credential;
+  keyKind: "payment" | "stake" | "drep" | "pool" | "cc"; // which key proves it
+}
+```
+
+`payload` is a generic `Metadatum` tree (**not** CBOR bytes) — hand it to your
+Cardano library's metadatum serializer at label 17. Each `proveCredentials` entry
+names a credential the transaction must **prove** control of, and `keyKind` tells
+you which key does so (e.g. the stake key when answering as Stakeholder).
+
+### Proving credentials
+
+CIP-179 authenticates a response's credential through its carrying transaction by
+**either** of two mechanisms — the widget only _declares_ the credentials; **how**
+you prove them is yours:
+
+- **Mechanism A** — put the credential in the transaction's `required_signers`
+  (or satisfy its native script in the witness set). Works for every role. This is
+  the simple, always-available path, and what the reference host does via
+  `frontend/app/src/wallet/submit.ts` (`buildTx` adds each credential with
+  `tx.addSigner`).
+- **Mechanism B** (governance-linked surveys only) — the **same transaction**
+  casts a qualifying **governance vote** with that very credential on one of the
+  survey's linked actions, the Conway voter tag matching the claimed role (CC,
+  DRep, SPO). No `required_signers` entry is then needed for it — the vote binding
+  is the proof. Only DRep / SPO / CC can bind this way; Stakeholder and Keyholder
+  have no voter tag and must use mechanism A.
+
+So a DRep answering a governance-linked survey in the very transaction that votes
+on its linked action is already proven by that vote (mechanism B); in any other
+case, add the credential to `required_signers` (mechanism A). `keyKind` is the same
+hint either way — it tells you which key signs, whether that signature lands in
+`required_signers` or in the vote's witness.
+
+## TypeScript
+
+Importing anything from the package (even a type) loads global augmentations:
+`HTMLElementTagNameMap` gains `"tessera-respond"`, so
+`document.createElement("tessera-respond")` and tag-name queries return a
+`TesseraRespondElement` — every prop a writable, possibly-`undefined` DOM
+property — and `HTMLElementEventMap` gains the three `tessera:*` events, so
+`addEventListener("tessera:response", (e) => …)` types `e.detail` as
+`RespondResult` on any element (they bubble composed, so ancestors count).
+No hand-rolled element interface or `IntrinsicElements` entry is needed.
+
+The one exception is Solid's JSX: the published types deliberately augment
+nothing framework-specific (a `declare module "solid-js"` block would break
+type-checking for the many hosts that don't have `solid-js` installed). A
+Solid host wanting `<tessera-respond>` in JSX adds the entry itself:
+
+```ts
+declare module "solid-js" {
+  namespace JSX {
+    interface IntrinsicElements {
+      "tessera-respond": JSX.HTMLAttributes<TesseraRespondElement>;
+    }
+  }
+}
+```
+
+(In-workspace, `/element` ships that augmentation from source.)
+
+## The responder & eligibility
+
+`responder` maps each role the user can answer as to the credential that role
+carries — one uniform map (no wallet shape, no provenance flags):
+
+```ts
+type Responder = Partial<Record<Role, Credential>>;
+```
+
+- **Keyholder / Stakeholder / DRep** come from a connected wallet — its
+  payment / stake / DRep credentials. Deriving them is yours; the widget never
+  touches a wallet. The Tessera app does it in
+  [`frontend/app/src/domain/roles.ts`](../../frontend/app/src/domain/roles.ts)
+  (`walletResponder`), which you can copy.
+- **SPO and CC** need cold keys a browser wallet can't hold, so they're never
+  wallet-derivable — add them as extra entries when your host vouches for one. A
+  responder can be entirely host-supplied (an SPO credential and nothing else).
+- The widget takes the map **verbatim** and never validates it — it lists each
+  chosen credential in `proveCredentials` for you to prove through the carrying
+  transaction (see [Proving credentials](#proving-credentials)).
+- **The widget picks the role internally.** A responder eligible in several roles
+  gets a role picker; the emitted `role` + `credential` reflect the one chosen.
+  The role → signing-key mapping is fixed: Keyholder→`payment`,
+  Stakeholder→`stake`, DRep→`drep`, SPO→`pool`, CC→`cc`.
+
+In-workspace, `cardano-tessera-respond-core` exports
+`respondableRolesFor(def, responder)` and `credentialForRole(role, responder)`
+to compute eligibility host-side too (e.g. to decide whether to mount the
+widget at all). That package is not published yet — the planned host toolkit
+(`cardano-tessera-host`) will carry these helpers for npm integrators.
+
+## Prior responses (edit/replace)
+
+For an edit/replace flow, pass the responder's prior responses in
+`priorResponses` — **one per role** they've answered as.
+
+The role is chosen _inside_ the widget, so the host can't know up front which
+prior response applies: pass them all, and the widget selects the one matching the
+current role + credential, re-prefilling as the user switches roles. A responder
+who answered as both DRep and Stakeholder passes both; the array is
+order-independent.
+
+```ts
+// One deduped "mine" set, resolved to a prior response per respondable role.
+el.priorResponses = respondableRolesFor(def, responder).flatMap((r) => {
+  const cred = credentialForRole(r, responder);
+  const prior = cred ? findPriorResponse(mine, surveyRef, r, cred) : undefined;
+  return prior ? [prior] : [];
+});
+```
+
+Pass **sealed** priors too. Their ciphertext can't prefill the form, but the
+widget still marks it as a replacement — on a sealed survey that's the only way
+a responder learns they already answered. The reference host `DevWidgetHost.tsx`
+does exactly this against a survey bundle.
+
+## What the host must do
+
+The widget deliberately leaves these to you:
+
+1. **Attach + submit.** On `tessera:response`, put `payload` at metadata label 17,
+   prove each `proveCredentials[].credential` in the transaction — via
+   `required_signers` or a governance-vote binding (see
+   [Proving credentials](#proving-credentials)) — sign with the indicated key
+   kinds, and submit.
+2. **Network conformance.** The responder carries no network id, so the widget
+   can't tell whether the wallet is on the wrong chain. Check
+   `walletNetworkId === targetNetwork` before you submit.
+3. **Tip freshness.** `tipEpoch` is a snapshot; a survey can close between your
+   last refresh and the user's submit. Re-set the prop to refresh. The chain (and
+   the tally's eligibility rules) is the final arbiter regardless — the emitted
+   payload is still only a payload.
+4. **Only mount for an open survey.** The widget blocks a closed/cancelled survey
+   from its own gate, but you decide whether to show it at all — pass an accurate
+   `tipEpoch` and `cancelled`.
+5. **Enrich the definition.** Any off-chain label enrichment (IPFS presentation
+   docs, etc.) happens upstream; the widget renders the `definition` you give it.
+6. **Pin a rationale** (if used). Pass a pre-pinned `ContentAnchor` in
+   `rationaleAnchor`; the widget attaches it but never pins.
+
+## Sealed surveys
+
+For a survey with `submissionMode.type === "sealed"`, the widget owns encryption
+end-to-end: it timelock-encrypts the answers to the survey's drand round
+(`cip-179/tlock`) before emitting, so the sealed `payload` you receive is already
+the final ciphertext wrapped in the label-17 envelope — you can't get it wrong.
+`sealed: true` on the result marks it.
+
+- The heavy sealing code (tlock + the evolution CBOR codec) is **lazy-loaded** only
+  when a sealed survey is answered. The public path never loads it. In a built
+  bundle these are separate chunks fetched on demand.
+- **Quicknet only.** cip-179 supports only the drand quicknet chain today, and
+  `sealAnswers` encrypts to quicknet unconditionally. A sealed definition pinned to
+  any other drand chain would produce a permanently undecryptable response, so the
+  widget **blocks submission** (rather than mis-encrypting) and shows a notice.
+
+## Internationalization
+
+Hybrid strategy driven by two props:
+
+- **`locale`** (BCP-47, default `"en"`) selects a bundled catalog. **`en` and `fr`
+  ship.** It also drives all number and date formatting via `Intl`, keyed on the
+  locale — including the sealed-reveal date.
+- **`messages`** deep-merges string overrides over the bundled catalog, or supplies
+  an entirely unshipped language.
+
+Numbers always follow `locale`, even when strings fall back to English. If `locale`
+resolves to **no bundled catalog and no `messages`**, the widget emits a one-time
+`console.warn` in dev builds (e.g. _"locale 'de' has no bundled catalog and no
+`messages`; UI text will render in English."_) — the number/date formatting is
+still locale-correct, only the prose falls back.
+
+```ts
+el.locale = "fr"; // bundled
+el.locale = "de";
+el.messages = { respond: { signAndSubmit: "Absenden" } /* … */ }; // supply/override strings
+```
+
+## Theming & fonts
+
+Every color, radius, and font is a `--tessera-*` CSS custom property defined on
+`:host` inside the shadow root (defaults ported from the app's design tokens).
+Custom properties inherit _through_ the shadow boundary, so you override them two
+equivalent ways:
+
+```css
+/* Host CSS — target the element. */
+tessera-respond {
+  --tessera-accent: #6b46ff;
+  --tessera-role-drep: #6b46ff;
+}
+```
+
+```ts
+// The `theme` prop — each entry reflected as `--tessera-<key>` inline on :host.
+el.theme = { accent: "#6b46ff", "role-drep": "#6b46ff" };
+```
+
+Role chips have their own tokens (`--tessera-role-drep`, `--tessera-role-spo`,
+`--tessera-role-cc`, `--tessera-role-stakeholder`, `--tessera-role-keyholder`, each
+with a `-bg` pair). See [`src/theme.css`](./src/theme.css) for the full token list.
+
+- **Dark mode.** You can re-skin every color through the tokens, but native form
+  controls (range track, number spinners) also need `color-scheme: dark`, which a
+  custom property cannot express. Set it in host CSS on the element (or a wrapper):
+  `tessera-respond { color-scheme: dark; }`. The `:host` root is transparent, so it
+  takes your page's background.
+- **Fonts.** The widget **names** fonts via `--tessera-sans` / `--tessera-mono` /
+  `--tessera-serif` but **never loads them** — loading webfonts is the host page's
+  job (a shadow root can't reach your `@font-face` rules for _loading_, only for
+  _using_ already-loaded families). Point these tokens at families your page has
+  loaded, or leave the system-font fallbacks.
+
+## Layout
+
+- **`"one-per-screen"`** (default) — a stepper: one question at a time with
+  prev/next and progress dots.
+- **`"list"`** — every question rendered at once.
+
+Both reuse the same body components, the same `decided()` gating, and the same
+answer collection; layout is pure presentation over shared state.
+
+## Single Solid instance
+
+The widget is built on SolidJS. A bundler host that also uses Solid (or embeds
+another Solid custom element) must ensure a **single** Solid runtime instance —
+two copies break reactivity. Under pnpm this usually happens automatically
+(shared symlink); with a bundler, add `solid-js` and `solid-element` to your
+`resolve.dedupe`. The Tessera app does exactly this in
+[`frontend/app/vite.config.ts`](../../frontend/app/vite.config.ts). A script-tag
+host loading the self-contained artifact has no such concern — Solid is bundled in.
+
+## One copy per page
+
+Load the widget from a **single** source, once. `<tessera-respond>` is a global
+custom-element name, and a second copy of the package landing on the same page
+(the script-tag artifact _plus_ a bundler copy, or two different versions) does
+**not** error: the second registration swaps its component into the class the
+first copy defined, so new connections render the second copy's UI against the
+**first** copy's prop/attribute wiring. A prop that only the newer version
+declares is then silently non-reactive. If you mix consumption styles or
+versions, dedupe them to one before anything registers the element.
+
+## Development
+
+```sh
+pnpm install
+pnpm --filter cardano-tessera-respond dev    # Vite dev harness (dev/index.html)
+pnpm --filter cardano-tessera-respond build   # emits dist/ (bundle + chunks + rolled-up d.ts)
+pnpm --filter cardano-tessera-respond test    # builds, then runs the artifact + token tests
+pnpm --filter cardano-tessera-respond type-check
+```
+
+Two demo/test surfaces cover different failure modes:
+
+| Path                    | What it drives                                                                                                        |
+| :---------------------- | :-------------------------------------------------------------------------------------------------------------------- |
+| `dev/`                  | Vite dev harness — `RespondRoot` in a shadow root, real workspace source, all samples/locales/themes.                 |
+| `demo/index.html`       | Plain-HTML host for the **built** bundle, fully offline. Shows the sealed chunks lazy-loading in the network tab.     |
+| `test/artifact.test.ts` | The automated twin of `demo/` — mounts the built artifact in happy-dom, offline, asserts the whole prop → event loop. |
+| `test/tokens.test.ts`   | Gate: every `--tessera-*` referenced in the CSS is defined in `theme.css`, and vice-versa.                            |
+
+In the workspace the package is consumed straight from `src` (its `exports` map
+points at TypeScript source, like every sibling), so cross-package edits are live
+with no build step.
+
+## Layout
+
+| Path              | Purpose                                                                   |
+| :---------------- | :------------------------------------------------------------------------ |
+| `src/element.tsx` | `customElement("tessera-respond", …)` registration + prop reflection.     |
+| `src/Respond.tsx` | The trimmed answering component (props in → `tessera:*` events out).      |
+| `src/roles.ts`    | Role label/color/keyKind presentation over the injected catalog + tokens. |
+| `src/theme.css`   | The `--tessera-*` design-token defaults on `:host`.                       |
+| `src/styles/`     | Component CSS, shadow-scoped plain CSS delivered via `?inline`.           |
+| `src/types.ts`    | The public prop/event TypeScript contract.                                |
+
+The per-question body components live in
+[`cardano-tessera-respond-ui`](../respond-ui/README.md), shared with the app; see
+[`cardano-tessera-respond-core`](../respond-core/README.md) for the pure logic both
+share.