@aquera/mcp-ui-render 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aquera Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# @aquera/mcp-ui-render
+
+Framework-agnostic **Lit 3** web components that render a `bootstrap` tenant-configuration
+descriptor (see `kb/specs/SPEC-mcp-ui-render.md` and the descriptor contract) using **Nile**.
+Renders identically in Angular (`CUSTOM_ELEMENTS_SCHEMA`), React, or a plain HTML page: no
+framework runtime dependency, no per-connector hand-built form.
+
+- **Pure renderer.** No network I/O, holds no secrets. It renders, validates, and emits
+  intent (`aq-mcp-change` / `aq-mcp-submit` / `aq-mcp-action`); the host executes tools.
+- **Nile is a peer dependency.** The host provides and registers `@aquera/nile-elements`.
+- **Published to public npm** as `@aquera/mcp-ui-render`, MIT-licensed, alongside the other
+  `@aquera` packages. Development happened against the private Verdaccio registry; the public
+  line starts at `0.0.1` (D-6b's promotion step — see `RELEASE-NOTES.md`).
+
+## Install
+
+```bash
+npm install @aquera/mcp-ui-render
+```
+
+Requires the host to also install and register Nile:
+
+```bash
+npm install @aquera/nile-elements @aquera/nile @aquera/nile-glyph
+```
+
+## Quick start
+
+```html
+<script type="module">
+  import '@aquera/nile-elements'; // host registers Nile once
+  import '@aquera/mcp-ui-render/styles.css'; // required — the elements render into light DOM (see USAGE.md)
+  import '@aquera/mcp-ui-render';
+  const el = document.querySelector('aq-mcp-config');
+  el.descriptor = await callBootstrapTool(); // the bootstrap tool result
+  el.values = currentValues;
+  el.addEventListener('aq-mcp-submit', (e) => host.save(e.detail));
+  el.addEventListener('aq-mcp-action', (e) => host.callTool(e.detail.tool, e.detail.args));
+</script>
+<aq-mcp-config></aq-mcp-config>
+```
+
+See [`USAGE.md`](./USAGE.md) for the Angular / React / plain-HTML integration guides and the
+full event contract, [`CONFIGURATION.md`](./CONFIGURATION.md) for every property, method, event,
+and extensibility hook on `<aq-mcp-config>` / `<aq-mcp-section>` / `<aq-mcp-field>`, and
+[`TEST-PLAN.md`](./TEST-PLAN.md) for how the descriptor contract's §15 conformance checklist maps
+to test coverage.
+
+Or open [`REFERENCE.html`](./REFERENCE.html) directly in a browser — a single self-contained page
+covering all of the above (getting started, the descriptor contract, every built-in control,
+validation/dependency/secret rules, the four customization levers, the full API surface, and
+worked examples pulled from real descriptors) in one place, with no build step.
+
+## Rendering a single `ui-component`, without a descriptor
+
+Sometimes a host just wants one control's output (e.g. a `test-connection-report` result)
+dropped into some div, not the whole `bootstrap` form. Two ways, no full descriptor/section
+required:
+
+**`<aq-mcp-field>` on its own** (recommended): it's an independent custom element, not tied to
+`<aq-mcp-config>`. It only ever needs a minimal `field` object plus a `value`:
+
+```html
+<aq-mcp-field></aq-mcp-field>
+<script type="module">
+  import '@aquera/mcp-ui-render';
+  const el = document.querySelector('aq-mcp-field');
+  el.field = { attribute: 'connectionTest', datatype: 'none', 'ui-component': 'test-connection-report' };
+  el.value = theReportJson; // whatever value shape that ui-component expects
+</script>
+```
+
+This still renders `<aq-mcp-field>`'s own two-column row (a label column + the control), so it
+reads as a form-field row rather than a bare block; override `.aq-mcp-field` in
+`mcp-ui-render.css` if that layout isn't wanted. See `apps/mcp-render-demo`'s "Standalone
+`<aq-mcp-field>`" section for a working example.
+
+**Bypass the element entirely** with the registry, for the truly bare markup with no wrapper:
+
+```ts
+import { resolveControl } from '@aquera/mcp-ui-render';
+import { render } from 'lit';
+
+const renderer = resolveControl('test-connection-report');
+render(renderer({ field: theField, value: theReportJson, error: null, onInput: () => {} }), document.querySelector('#myDiv'));
+```
+
+This needs the host to import Lit's own `render()`, so it fits better when the host is already
+Lit-based; `<aq-mcp-field>` is the simpler choice for any other framework or plain HTML.
+
+## What it does
+
+- **Renders a `bootstrap` descriptor**: ordered sections of ordered fields, two-column layout,
+  with no per-connector code (`<aq-mcp-config>` → `<aq-mcp-section>` → `<aq-mcp-field>`).
+- **Eleven default controls**, each a Nile element (`properties-table` is the one exception — a
+  plain semantic `<table>`, since Nile has no read-only data-table primitive this use case
+  needs): `input`, `textarea`, `password`, `select` (+ multi-select for `array`), `radio`,
+  `checkbox`, `button`, `file`, `test-connection-report`, `properties-table`, and
+  `permissions-report`. An **extensible component registry**
+  (`registerControl`) lets a host add or override a `ui-component` without touching the engine;
+  an unknown `ui-component` always falls back to the field's datatype default (never dropped).
+  `select`/`radio` `options` accept a plain primitive (`value === display text`) or
+  `{ value, label }` (`0.5.0`) when the submitted code and its human-readable name differ.
+- **Validation engine.** Compiles each field's `validation` regexes (whole-value, AND-combined),
+  applies `isRequired`/`min`/`max`, and pushes the result into the Nile control's own
+  `error`/`errorMessage` props; a non-compiling regex logs and never blocks the user. A `file`
+  field's `accept`/`maxSizeKB` checks run the same way — **client-side only, advisory**: this is
+  a pure renderer with no network I/O, so a connector must still enforce file type/size
+  server-side; the UI check is a fast first pass, not the real gate.
+- **Secrets & hidden fields.** Hidden fields render nothing but round-trip unchanged on submit;
+  `secret`/`password` fields are masked and never prefilled; `writeOnce` fields render as
+  "Replace" and omit from submit unless the user actually enters a new value
+  (`WRITE_ONCE_UNCHANGED` sentinel).
+- **Accessible labels.** `input`/`textarea`/`password`/`select` (`0.4.1`) and `radio` (`0.5.0`)
+  are given a real, natively associated accessible name — the visible label lives in
+  `<aq-mcp-field>`'s own left column, but each control also gets it via Nile's own `label`
+  property, with Nile's internal label visually hidden so nothing shows twice. **Known gap:** `checkbox`
+  (`nile-slide-toggle`) has no equivalent wiring in Nile itself — its internal checkbox
+  isn't `for`/`aria-labelledby`-associated with its `label` at all; not fixable from this
+  library's side.
+- **Submit / save-target resolution.** Collects values keyed by `attribute` for the fields that
+  applied, resolves each section's save target (its own `submitTool` vs the platform default),
+  and emits the payload; it never calls the tool itself.
+- **Dynamic `select`/`radio` options** (`0.5.0`, §9.6). A field with `tool` set and no options
+  yet emits `aq-mcp-options-request` once it's applicable — the host calls the tool and feeds
+  the result back via `dynamicOptions`, still without this library ever touching the network
+  itself (D-4). Pending-a-fetch and a genuine "no options, no way to get any" defect render
+  the same (disabled) but only the latter logs the §15 warning.
+- **`properties-table` — a read-only Property/Value summary** (`0.5.0`, `datatype: "none"`,
+  never validated/submitted, same contract as `test-connection-report`). For surfacing a
+  handful of attributes' current values — typically read-only/hidden tenant attributes that
+  matter to see but shouldn't be directly editable fields — without duplicating them as
+  disabled form controls. Rows (`PropertiesTableRow[]`) come from either `field.rows` (static,
+  declared in the descriptor — the connector already knows the data) or `values[attribute]`
+  (dynamic, host-computed at render time — wins if both are present, same priority
+  `dynamicOptions` has over `options` for `select`/`radio`). The control formats
+  booleans/arrays/plain objects (JSON-stringified)/`null` and truncates long values and
+  property names (full text still in each cell's `title`).
+- **Compound field dependency** (`0.5.0`, §12). `Field.dependsOn?: { attribute: string; value:
+  string | string[] }[]` — alongside the existing single-attribute
+  `dependencyAttribute`/`dependencyValue` — for a field relevant when EITHER of two different
+  attributes hits a value (e.g. an FTP-server picker relevant under a direct-connection mode OR
+  under an SFTP storage mode, two unrelated fields). Every condition is OR'd together; `[]` or
+  omitted behaves as no dependency at all, same as before this addition.
+- **Collapsible field help** (`0.5.0`). `field.help` over 100 characters renders truncated with
+  a "View more"/"View less" toggle instead of always showing in full — purely a
+  `<aq-mcp-field>` presentation detail, no model change.
+- **`Field.actions` — a multi-action toolbar** (`0.5.0`, §5). `properties-table` uses this to
+  render its own card header — title/subtitle from `field.label`/`field.help`, plus a
+  right-aligned toolbar of independently-wired buttons (an `icon`-bearing entry renders
+  icon-only via `nile-icon-button`; without `icon`, a labeled `nile-button`) — matching the live
+  reference's "Generated Configuration" card (a download button + "Edit Configuration"). Each
+  entry has its own `tool`/`args`/`confirm`; `aq-mcp-action`'s detail includes which `action`
+  fired. `properties-table` is consequently a full-width control (spans the whole field row)
+  rather than the usual two-column label/control split — its label still always renders, now in
+  its own header instead of `<aq-mcp-field>`'s left column. This icon-vs-label rendering is the
+  DEFAULT only — a host wanting different toolbar UI overrides `properties-table` entirely via
+  `registerControl` (below), the same escape hatch every other built-in control already has.
+- **`permissions-report` — a scope/permission GRANT table** (`0.5.0`, `datatype: "none"`, never
+  validated/submitted). Distinct from `test-connection-report` (that one models PASS/FAIL
+  endpoint probes): this renders a validation banner (success/error from `report.valid`) plus a
+  "Validation Report" — a running "N Granted" count (always derived from the current `grants`
+  array, never a separately-suppliable number) and an All/Success filter, then a Resource
+  Type/Permission Type/Access table — matching the live reference's own "Credentials" tab Test
+  Connection result exactly. The filter is pure CSS (native radio inputs + a general-sibling
+  rule), no Lit reactive state.
+- **Per-section footer customization** (`registerSectionFooter`): a host can replace a
+  section's default "Save `<label>`" button with custom markup, keyed by `section.key`. Absent
+  a registration, the library's default footer renders unchanged.
+- **Host-driven validation & footer control.** `AqMcpConfig.validateAll()` lets a host bypass
+  per-section footers entirely and validate the whole form itself, still getting the library's
+  real inline field errors; `showSectionFooters`/`showFooter` hide every footer (default or
+  custom) at once. Every edit is also live-validated as it happens, not just on submit.
+- **Configurable section layout.** `sectionsLayout: 'stacked' | 'tabs' | 'accordion'` (default
+  `'stacked'`) switches between one-card-per-section, a Nile nav-tab arrangement (`tabsPlacement`
+  for horizontal/vertical, `tabsShowErrorIndicator` for a per-tab error dot), and a single-open
+  `nile-accordion` stack whose cards tint their edge when a section still has a required field
+  empty, so a collapsed section says it needs attention (`accordionOpenSection`,
+  `accordionShowFooters`, `accordionColumns` for one- or two-column fields). Validation and submit behave identically in every layout. See [`CONFIGURATION.md`](./CONFIGURATION.md).
+- **Extensibility by construction.** Unknown datatype is treated as `string` (+ warn if
+  required); unknown section/field keys are preserved on round-trip; a descriptor `version` MAJOR
+  ahead of what the library understands renders best-effort plus a notice, switching on MAJOR only.
+
+## Public API (`index.ts`)
+
+| Export | What |
+|---|---|
+| `AqMcpConfig`, `AqMcpSection`, `AqMcpField` | the custom element classes (`aq-mcp-config`, `aq-mcp-section`, `aq-mcp-field`) |
+| `Descriptor`, `Section`, `Field`, `FieldAction`, `Values`, `Datatype`, `AuthType` | descriptor type model |
+| `registerControl` / `resolveControl` / `ControlContext` / `ControlRenderer` | the `ui-component` registry |
+| `registerSectionFooter` / `resolveSectionFooter` / `SectionFooterContext` / `SectionFooterRenderer` | the per-section footer registry |
+| `validateField` | the validation engine, standalone |
+| `collectSubmit`, `sectionHasEditableFields`, `WRITE_ONCE_UNCHANGED`, `SubmitPayload` | submit assembly + save-target resolution |
+| `fieldApplies`, `seedDefaults`, `asArray` | dependency/default-seeding helpers |
+| `sectionStatus`, `SectionStatus`, `isEmpty` | section-completeness engine behind the accordion's attention state, standalone |
+
+## Status
+
+Current version in this repo: **`0.0.1`** — the **first public npm release** (`npm view
+@aquera/mcp-ui-render`). It is the same code as the internal `0.6.0` Verdaccio build, renumbered
+for a registry that has never held this package; `RELEASE-NOTES.md` is the published record and
+`CHANGELOG.md` is the pre-npm history. A `^0.6.0` range will not resolve on npm — pin `0.0.1`.
+
+The feature history below is written against the Verdaccio version numbers it happened under, and
+is kept because it explains *why* each behaviour is the way it is. `0.6.0` adds the `sectionsLayout: 'accordion'` layout — a single-open stack of `nile-accordion`
+cards with a label-above-control body in one or two columns (`accordionColumns`) and each field's
+`help` as hint text beneath it, where a card whose section still has a required field empty tints
+its edge so it is findable while collapsed. `0.5.5` gave `datatype: "object"` a real editable
+control:
+`input`/`textarea` previously rendered an object value as the literal text `"[object Object]"`;
+both now pretty-print it as editable JSON and parse typed text back into a real object, keeping
+the raw text as an interim value (never throwing, never corrupting the display) while the JSON is
+mid-typing and not yet valid. `object`'s default `ui-component` also changed from `input` to
+`textarea`. See `CHANGELOG.md` for the full writeup. See
+[`CHANGELOG.md`](./CHANGELOG.md) for the full version history and
+[`CONFIGURATION.md`](./CONFIGURATION.md) for the full property/method/event reference.
+
+Built and tested (all of it, via `nx test mcp-ui-render` / `nx test-browser mcp-ui-render`):
+descriptor rendering, the control registry, validation, secrets/submit behaviour, the §15
+conformance suite, per-section footer customization, host-driven validation (`validateAll()`,
+`showSectionFooters`) and live on-change validation (`0.3.0`), the `sectionsLayout: 'tabs'`
+layout (`0.4.0`), the `sectionsLayout: 'accordion'` layout and its `sectionStatus` engine
+(`0.6.0`), and every `0.5.0` feature listed above — including two display fixes: a
+`test-connection-report`/`permissions-report` field with no value yet now renders nothing at all
+(not even its own label, previously left dangling next to blank space), and a `file` field's
+upload hint is derived from its own `accept`/`maxSizeKB` instead of always showing
+`nile-file-upload`'s hardcoded image-upload default. Every feature past `0.2.0` is filed as a
+DRAFT amendment (A through J) in `kb/specs/SPEC-mcp-ui-render.md`, pending Hanu/Ahi ratification
+— already built and shipped, per this spec's own established pattern of documenting after build.
+
+The MCP-App (`ext-apps`) delivery mode **is built**, in the `mcp-gateway` app, not a separate
+`mcp-engine` repo: `servers/mcp-gateway-service/apps/mcp-gateway/src/mcp-apps/ui/src/mcp-ui-render-app.js`
+(a vanilla-JS single-file entry using `@modelcontextprotocol/ext-apps`'s core `App` class) plus
+server-side `bootstrap`/`credential_test`/`saveConnectorConfig` tool stubs. Not yet done: adding
+`bootstrap` to the per-appType S3 tool allowlist for any real tenant, and end-to-end verification
+against a real MCP client. See "MCP delivery" in `kb/specs/SPEC-mcp-ui-render.md` and the
+2026-08-01 entry in `kb/QA-QUEUE.md` for the full detail.

package/RELEASE-NOTES.md

@@ -0,0 +1,77 @@
+# Release notes — `@aquera/mcp-ui-render`
+
+Public releases on **npm** (`https://registry.npmjs.org/`). One entry per published version,
+newest first.
+
+**On the numbering.** This package was developed against the private Verdaccio registry and
+reached `0.5.4` there. `0.0.1` is the **first public npm release** and deliberately restarts the
+series: npm has never held this package, so the public line begins at the beginning rather than
+inheriting a private history no npm consumer can see. The Verdaccio-era detail is preserved in
+`CHANGELOG.md` and is not replayed here — this file describes what a consumer *gets*, not how it
+was built.
+
+**If you were installing from Verdaccio:** `0.0.1` is not a downgrade. It is the same code as the
+internal `0.6.0` line, republished. A dependency range like `^0.6.0` will **not** resolve against
+npm — pin `0.0.1` (or `^0.0.1`) when you switch your registry over.
+
+---
+
+## [0.0.1] — first public release
+
+First publication of the framework-agnostic renderer to public npm. Same code as the internal
+`0.6.0` build; no functional change was made for the move.
+
+### What the package is
+
+**Lit 3 custom elements that render a `bootstrap` tenant-configuration descriptor** — ordered
+sections of ordered fields — with no per-connector code. The element tree is
+`<aq-mcp-config>` → `<aq-mcp-section>` → `<aq-mcp-field>`, and it renders identically in Angular
+(with `CUSTOM_ELEMENTS_SCHEMA`), React, or a plain HTML page.
+
+It is a **pure renderer**: no network I/O, and it holds no secrets. It renders, validates, and
+emits intent (`aq-mcp-change`, `aq-mcp-submit`, `aq-mcp-action`); the host executes the tools.
+
+### What is in this release
+
+- **Three section layouts** — `stacked` (a card per section), `tabs`, and `accordion` (a
+  single-open stack whose collapsed cards still report what is inside them and how much is left
+  to fill in).
+- **Eleven controls**, each a Nile element: `input`, `textarea`, `password`, `select` (with
+  multi-select for `array`), `radio`, `checkbox`, `button`, `file`, `test-connection-report`,
+  `properties-table`, and `permissions-report`. `properties-table` is the one deliberate
+  exception — a plain semantic `<table>`, because Nile has no read-only data-table primitive that
+  fits this use.
+- **An extensible control registry** (`registerControl`) so a host can add or override a
+  `ui-component` without touching the engine. An unknown `ui-component` falls back to the field's
+  datatype default and is never dropped.
+- **A validation engine** — per-field regexes (whole-value, AND-combined) plus
+  `isRequired`/`min`/`max`, pushed into the Nile control's own `error`/`errorMessage`. A regex
+  that does not compile is logged and never blocks the user.
+- **Secrets and hidden fields handled deliberately** — hidden fields render nothing but
+  round-trip unchanged; `secret`/`password` fields are masked and never prefilled; `writeOnce`
+  fields render as "Replace" and are omitted from submit unless the user actually enters a new
+  value.
+- **Accessible names** wired natively for `input`, `textarea`, `password`, `select` and `radio`.
+- **Typed ESM with per-element entry points** for tree-shaking, `.d.ts` types, and a stylesheet
+  exported as `@aquera/mcp-ui-render/styles.css`.
+
+### Known gaps, carried forward rather than quietly dropped
+
+- **`checkbox` has no programmatic label association.** `nile-slide-toggle`'s internal checkbox is
+  not `for`/`aria-labelledby`-associated with its label in Nile itself. It is not fixable from
+  this library, and it is a real accessibility gap for screen-reader users on checkbox fields.
+- **File `accept`/`maxSizeKB` checks are advisory only.** This is a pure renderer with no network
+  I/O, so a connector **must** still enforce file type and size server-side. The client-side check
+  is a fast first pass, not the gate.
+
+### Requirements
+
+Nile is a **peer dependency** — the host installs and registers it:
+`@aquera/nile >= 1.2.0`, `@aquera/nile-elements >= 1.9.0`, `@aquera/nile-glyph >= 1.0.0`.
+`lit ^3.2.0` is a direct dependency.
+
+### Licensing
+
+Published under **MIT**, matching the other `@aquera` packages on npm. The package previously
+declared `UNLICENSED`, which was correct while it was private and wrong for a public release;
+the `LICENSE` file ships inside the tarball.

package/TEST-PLAN.md

@@ -0,0 +1,72 @@
+# TEST-PLAN — @aquera/mcp-ui-render
+
+Two runnable layers:
+
+- **Engine (pure logic)** — `nx test mcp-ui-render` (jest, node env).
+  Specs: `test/unit/apps/mcp-ui-render/engine.spec.ts` (validate/values/submit),
+  `test/unit/apps/mcp-ui-render/registry.spec.ts` (control + section-footer registries).
+- **Element / rendering (browser)** — `nx test-browser mcp-ui-render`
+  (`@web/test-runner` + Chromium, real Nile registered).
+  Split by concern under `apps/mcp-ui-render/test/` (each file self-contained; shared
+  mount/assert helpers in `test/support/browser-helpers.js`, which is not itself a test
+  file):
+  - `conformance.browser.js` — hidden/secret fields (§7), dependency reveal (§12), a standing
+    regression test for a dependent field's `defaultValue` being seeded when it becomes newly
+    applicable mid-session (not just at initial descriptor load, §12), unknown-`ui-component`
+    fallback (§9.1), MAJOR-version negotiation (§9.5), section DOM ordering.
+  - `controls.browser.js` — control→Nile mapping (§5), the two-column layout, `select`
+    without `options` (§15), every built-in control end to end (`textarea`, `select`
+    single/multi, `checkbox`, live number validation, `file` incl. the mount-noop guard),
+    `datatype: "object"`'s JSON display/parse in `input`/`textarea` (pretty-printed display,
+    valid-JSON commits a real object, invalid/incomplete JSON kept as an interim raw string
+    without throwing or corrupting the display, defaults to `textarea` not `input`),
+    and `test-connection-report`.
+  - `layout.browser.js` — `sectionsLayout: 'tabs'` (0.4.0): tab-per-section, hidden-only
+    sections excluded from nav, `compact` styling, the error-dot's touched-vs-untouched
+    timing, `tabsShowErrorIndicator` opt-out, vertical-placement attributes.
+  - `write-once-regression.browser.js` — `writeOnce`/password masking (§7) and the
+    standing regression test for the 0.3.1 write-once password bug.
+  - `submit.browser.js` — `button` + `confirm` → `aq-mcp-action` (§5), `aq-mcp-submit`
+    payload (§13/§14), `validateAll()`, `showSectionFooters`/`showFooter`, a
+    `registerSectionFooter` override (0.3.0).
+
+## Conformance checklist (contract §15) → coverage
+
+| # | §15 item | Layer | Status |
+|---|---|---|---|
+| 1 | Every field carries `attribute`/`datatype`/`ui-component` | descriptor authoring (server) | n/a to renderer |
+| 2 | Unknown `ui-component` → datatype default; field never dropped (§9.1) | element | ✅ browser |
+| 3 | Exactly one auth section `authType`; no auth-type chooser | authoring | n/a (renderer adds no chooser) |
+| 4 | Every auth field is one the shape needs | authoring | n/a |
+| 5 | No field ships a secret value; use `valueFrom: secretRef` | authoring + defensive | ✅ browser (hidden secret not rendered; password never prefilled) |
+| 6 | Section whose every field is `hidden` renders nothing (§7/§12) | element | ✅ browser (hidden field not rendered) |
+| 7 | `none` submits nothing; `writeOnce` never in a read | engine + element | ✅ engine (submit) + ✅ browser (writeOnce Replace, not prefilled) |
+| 8 | Every `button`/`submitTool` names a same-server tool | authoring | n/a (renderer emits the name via `aq-mcp-action`) |
+| 9 | Section with no `submitTool` saved by the platform (§13) | engine + element | ✅ engine + ✅ browser (submit target null) |
+| 10 | Every `select` has `options` | element + warn | ✅ browser (empty→disabled + `console.warn`) |
+| 11 | Every `attribute` under `authorization.*` / `tenantAttributes.*` | authoring | n/a |
+| 12 | `validation` compiles; no pseudo-rules; range via min/max | engine | ✅ engine (§8 per-datatype, bad-regex graceful) |
+| 13 | Every field with `validation` also has `validationmessage` | authoring | n/a (renderer falls back to "Invalid value.") |
+
+Additional renderer behaviour covered:
+- **engine** — dependency apply + default seeding (§12, incl. dependency-not-yet-met and array `dependencyValue`), the compound `dependsOn` OR-across-attributes dependency (§9.7: any entry matching is enough, combines with `dependencyAttribute` via OR not AND, an empty `dependsOn: []` is a no-op), unknown-datatype→string+warn (§9.2), number coercion + prefix preservation on submit (§14), file/multi-file validation (`accept`/`maxSizeKB`/`minItems`/`maxItems`), object `requiredKeys`, boundary cases for `isEmpty` (whitespace, boolean `undefined` vs explicit `false`), the `WRITE_ONCE_UNCHANGED` sentinel short-circuiting `validateField` before any datatype check runs — both for `file` (where it would otherwise crash reading `.name` off the sentinel string) and `string` (where it previously "passed" only by accident), `validateFile`'s `instanceof File` guard failing safe (not crashing) for ANY other non-`File` value a `file`-datatype field might hold, `sectionHasEditableFields`, and the `registerControl`/`registerSectionFooter`/`defaultControlFor` extensibility registries (`registry.spec.ts`).
+- **browser** — every built-in control end to end with real Nile elements and real DOM events (`input`, `textarea`, `password`, `select` single/multi, `radio` incl. the §15 no-options-disabled case, `select`/`radio` `{value,label}` options (code emitted, label displayed), `checkbox`, `file` incl. the mount-noop guard, `test-connection-report` incl. the collapsible-mitigation and hard-error paths, `permissions-report` (null-renders-nothing, banner variant follows `valid`, the granted count derived from `grants` not host-supplied, badge variant follows `access`, and the All/Success filter's structural contract — two radios sharing one native group, `data-access` attributes on every row — since the harness never loads `mcp-ui-render.css` so the actual CSS-driven hide/show isn't assertable here), `properties-table` incl. empty/null, boolean/array/em-dash value formatting, plain-object values JSON-stringified (not `[object Object]`), long-value AND long-property-name truncation with the full text in `title`, static `field.rows` with no host-supplied value at all, `values[attribute]` taking priority over `field.rows` when both are present, the card header/title always rendering even with no rows, the `FULL_WIDTH_CONTROLS` layout — no standalone `.aq-mcp-field__label` column, one full-width control column instead — and `field.actions` (an icon-bearing entry renders icon-only via `nile-icon-button`, else a labeled `nile-button`; clicking one emits `aq-mcp-action` with that specific action's own `tool`/`args`, distinct from a sibling action; an action's own `confirm` opens the shared confirm dialog before emitting), dynamic `select`/`radio` options via `dynamicOptions` + `aq-mcp-options-request` (§9.6: request fires once per applicable tool-backed field, respects `dependencyAttribute`, never double-fires, `dynamicOptions` takes priority over static `options`, pending vs. §15-defect warning distinction), control→Nile mapping (§5), dependency reveal (§12), collapsible "View more"/"View less" help text (short help unaffected, long help toggles between truncated and full), `writeOnce` Replace → input (§7), a standing **regression test for the 0.3.1 write-once password bug** (keystroke-by-keystroke typing into a blank field never reverts to masked/Replace), `button` + `confirm` → `nile-dialog` → `aq-mcp-action` (§5), `aq-mcp-submit` payload (§13/§14), MAJOR-ahead version banner (§9.5), two-column layout, section DOM order following `order` (not descriptor array order), the `sectionsLayout: 'tabs'` feature (tab-per-section, hidden-only sections excluded from nav, `compact` styling, the error-indicator dot's touched-vs-untouched timing, `tabsShowErrorIndicator` opt-out, vertical-placement attributes), `validateAll()`, `showSectionFooters`/`showFooter`, and a `registerSectionFooter` override.
+
+## Running
+```
+nx test mcp-ui-render          # engine (jest, node)          — 67 assertions
+nx test-browser mcp-ui-render  # rendering (wtr + Chromium)   — 66 assertions, 6 files
+```
+`test-browser` requires Playwright's Chromium: `npx playwright install chromium` once.
+
+## Known external gap (not a bug in this library)
+
+`@aquera/nile-elements@1.9.9` registers `nile-file-upload`/`nile-file-preview` inside
+its full bundle but does not export either as an individual subpath (unlike every other
+element it ships — see its `package.json` `exports` map). A host that imports Nile
+selectively (subpath imports, to avoid pulling in the WYSIWYG editor's CommonJS
+dependency) must import the full `@aquera/nile-elements` bundle instead to get the
+`file` control working, or ask the Nile team to add the missing subpath exports. The
+browser test suite works around this with a pair of logic-free stub custom elements
+(registered in `test/support/browser-helpers.js`) purely so it can test **this
+library's** `file`-control wiring in isolation from that packaging gap.

package/USAGE.md

@@ -0,0 +1,100 @@
+# Using @aquera/mcp-ui-render
+
+The library ships standard custom elements, so every host uses the same tags. The host
+provides the descriptor + current values, registers Nile, and handles the emitted intents.
+
+## Events
+
+| Event | Detail | When |
+|---|---|---|
+| `aq-mcp-change` | `{ attribute, value, values }` | any field edit |
+| `aq-mcp-submit` | `{ sectionKey, submitTool, values }` | per-section Save (validated); `submitTool` is the connector tool or `null` for the platform default (§13) |
+| `aq-mcp-action` | `{ tool, args, confirm, field }` | a `button` (after `confirm`, if any) |
+| `aq-mcp-options-request` | `{ attribute, tool, args }` | a `select`/`radio` field with `tool` set has no options yet and currently applies (§9.6) — at most once per `attribute` |
+
+The library performs no network I/O and holds no secrets; the host executes the tools
+(`aq-mcp-submit` → the platform update or the section's `submitTool`; `aq-mcp-action` → the
+button's `tool`; `aq-mcp-options-request` → the field's `tool`, feeding the result back via
+`dynamicOptions`), enforcing the same-server rule.
+
+## Styling & light DOM
+
+`<aq-mcp-config>`, `<aq-mcp-section>`, and `<aq-mcp-field>` all render into **light DOM**
+(`createRenderRoot()` returns `this` — no shadow root), deliberately: it lets Nile's CSS
+custom-property tokens (`--ng-*`/`--nile-*`) and this package's own stylesheet cascade in from
+the host's page the same way any other content does, with no per-shadow-root style injection.
+
+The trade-off is **zero style encapsulation** — the host's global CSS can affect `.aq-mcp-*`
+classes, and vice versa — and it means the host **must** import the stylesheet globally once:
+
+```ts
+import '@aquera/mcp-ui-render/styles.css';
+```
+
+Without this import the elements still render structurally (every field, control, and section
+appears) but with **no styling at all** — no card borders, no two-column layout, no error
+colors — and **no console error or warning** to point at why. If a new integration looks
+completely unstyled, check for this import first.
+
+## Plain HTML
+
+```html
+<script type="module">
+  import '@aquera/nile-elements'; // host registers Nile
+  import '@aquera/mcp-ui-render/styles.css'; // required — see "Styling & light DOM" above
+  import '@aquera/mcp-ui-render';
+  const el = document.querySelector('aq-mcp-config');
+  el.descriptor = await callBootstrapTool();   // the bootstrap tool result
+  el.values = currentValues;
+  el.addEventListener('aq-mcp-submit', (e) => host.save(e.detail));
+  el.addEventListener('aq-mcp-action', (e) => host.callTool(e.detail.tool, e.detail.args));
+</script>
+<aq-mcp-config></aq-mcp-config>
+```
+
+## Angular
+
+```ts
+// Standalone component (or NgModule) that renders the custom element:
+@Component({
+  selector: 'app-connector-config',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA], // required for aq-mcp-* / nile-* tags
+  template: `<aq-mcp-config [descriptor]="descriptor" [values]="values"
+    (aq-mcp-submit)="onSubmit($event)" (aq-mcp-action)="onAction($event)"></aq-mcp-config>`,
+})
+export class ConnectorConfigComponent {}
+```
+`import '@aquera/mcp-ui-render'` **and** `import '@aquera/mcp-ui-render/styles.css'` once at
+bootstrap (alongside `@aquera/nile-elements`) — see "Styling & light DOM" above.
+
+## React
+
+```tsx
+import '@aquera/nile-elements';
+import '@aquera/mcp-ui-render/styles.css'; // required — see "Styling & light DOM" above
+import '@aquera/mcp-ui-render';
+
+function ConnectorConfig({ descriptor, values, onSubmit }) {
+  const ref = useRef<HTMLElement>(null);
+  useEffect(() => {
+    const el = ref.current!;
+    (el as any).descriptor = descriptor;
+    (el as any).values = values;
+    const submit = (e: any) => onSubmit(e.detail);
+    el.addEventListener('aq-mcp-submit', submit);
+    return () => el.removeEventListener('aq-mcp-submit', submit);
+  }, [descriptor, values, onSubmit]);
+  return <aq-mcp-config ref={ref} />;
+}
+```
+
+## MCP-App (ext-apps) delivery mode
+
+For MCP clients, a thin single-file entry (built with `vite-plugin-singlefile`, Nile inlined)
+imports the same Lit engine and bridges it to the MCP-Apps host: `ontoolresult` →
+`descriptor`/`values`; `aq-mcp-submit`/`aq-mcp-action` → `callServerTool`. This entry is **built**,
+at `servers/mcp-gateway-service/apps/mcp-gateway/src/mcp-apps/ui/src/mcp-ui-render-app.js` (a
+vanilla-JS entry using `@modelcontextprotocol/ext-apps`'s core `App` class — no React), not in a
+separate `mcp-engine` repo (see SPEC-mcp-ui-render §"MCP delivery" and the 2026-08-01 entry in
+`kb/QA-QUEUE.md`).

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@aquera/mcp-ui-render",
+  "version": "0.0.1",
+  "description": "Framework-agnostic Lit 3 web components that render a Keycloak/MCP bootstrap tenant-configuration descriptor using Nile. Decoupled from any framework — renders in Angular, React, or plain HTML.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./elements/*": {
+      "types": "./src/elements/*.d.ts",
+      "import": "./src/elements/*.js"
+    },
+    "./styles.css": "./src/mcp-ui-render.css"
+  },
+  "sideEffects": [
+    "**/controls.js",
+    "**/elements/*.js",
+    "**/index.js"
+  ],
+  "dependencies": {
+    "lit": "^3.2.0"
+  },
+  "peerDependencies": {
+    "@aquera/nile": ">=1.2.0",
+    "@aquera/nile-elements": ">=1.9.0",
+    "@aquera/nile-glyph": ">=1.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "bootstrap",
+    "descriptor",
+    "lit",
+    "web-components",
+    "nile",
+    "aquera"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@bitbucket.org/aquerateam/agentic-access-platform.git",
+    "directory": "servers/mcp-gateway-service/apps/mcp-ui-render"
+  }
+}

package/src/controls.d.ts

@@ -0,0 +1 @@
+export {};