cedar-embeddable-editor 1.5.2 → 2.0.1

package/README.md

@@ -1,12 +1,47 @@
-# Cedar Embeddable Editor (CEE)
+# CEDAR Embeddable Editor (CEE)
 
-The CEDAR Embeddable Editor is as a web component that implements the functionality of the CEDAR Metadata Editor.
+The CEDAR Embeddable Editor (CEE) is a reusable Web Component for adding
+structured, standards-based metadata authoring to web applications.
 
-It takes CEDAR JSON Schema templates as input, and produces CEDAR JSON-LD metadata.
+CEE dynamically renders data-entry forms from machine-actionable CEDAR
+templates and produces semantically rich metadata as JSON-LD. Templates define
+the fields, constraints, controlled vocabularies, and repeatable structures in a
+form, allowing the metadata-authoring experience to evolve independently of the
+application that embeds it. CEE also supports ontology-backed value selection
+and persistent identifiers from external authorities such as ORCID and ROR.
+
+For the design rationale, architecture, and deployments in research platforms,
+see [*Author Once, Publish Everywhere: Portable Metadata Authoring with the CEDAR
+Embeddable Editor*](https://doi.org/10.5334/dsj-2026-002), published in the
+*Data Science Journal* (2026).
+
+This README covers building, testing and releasing the component. For embedding
+it in an application, the CEDAR documentation site carries a fuller guide:
+[CEDAR Embeddable Editor](https://metadatacenter.readthedocs.io/en/latest/cedar-embeddable-editor/intro/).
+
+## Browser support
+
+CEE supports the browser targets of the Angular version each release is built
+with. It requires native Custom Elements v1 and native Shadow DOM.
+
+Automated compatibility tests run against current desktop Chromium, Firefox and
+WebKit engines. Firefox ESR and the configured Edge, Safari and iOS versions are
+compilation targets, but are not all exercised as separate browser products.
+
+Internet Explorer, legacy EdgeHTML, and browsers or embedded web views without
+native `window.customElements` and Shadow DOM support are not supported. CEE
+does not polyfill its host page. Consumers choosing to support browsers outside
+this contract must load and maintain their own Web Components polyfills before
+loading CEE.
 
 ## Running as a standalone application
 
-You can run CEE as a standalone application. This is helpful for developers to see changes to the code reflected immediately in the application. To run CEE in the standalone mode (NOT as a Webcomponent), you will need the editor itself and the sample templates that the editor uses. These are stored in a [separate repo](https://github.com/metadatacenter/cedar-component-distribution).
+You can run CEE as a standalone application. This is helpful for developers to
+see changes to the code reflected immediately in the application. The standalone
+app fetches a small template and instance from `src/assets/cee-demo` and assigns
+them to `templateAndInstanceObject`, the same way any host supplies an artifact,
+so it needs no separate template server and no `cedar-component-distribution`
+checkout.
 
 Proceed with the following steps:
 
@@ -16,12 +51,11 @@ Clone this repository onto a local directory of your choice:
 
 ```shell
 git clone https://github.com/metadatacenter/cedar-embeddable-editor.git
-git clone https://github.com/metadatacenter/cedar-component-distribution.git
 ```
 
 ### Edit configuration
 
-1. Open the file ```app/app.component.dev.ts``` in your favorite editor.
+1. Open the file ```cedar-embeddable-editor/src/app/app.component.dev.ts``` in your favorite editor.
 2. Edit configuration parameters based on your local environment (see section [Configuration](https://github.com/metadatacenter/cedar-embeddable-editor/tree/develop#configuration) for details).
 
 ### Build the project and start the server
@@ -36,37 +70,187 @@ cedar-embeddable-editor$ npm install
 cedar-embeddable-editor$ ng serve
 ```
 
-1. In a different shell navigate to the component distribution directory:
+1. In your browser, navigate to `http://localhost:4400/`. The app will automatically reload if you change any of the source files.
+
+## Building the Web Component
+
+CEE is shipped as one JavaScript file that can be embedded in an application or
+HTML page. Do not concatenate named Angular output files manually: their names,
+locations, and module structure change when Angular changes builders.
+
+Build the production application, then run the browser suite against the
+single-file bundle it produced:
+
 ```shell
-$ cd <...>/<clone directory>/cedar-component-distribution/
+nvm use
+npm run build:production
+npm run test:visual:prebuilt
 ```
 
-1. Run these commands:
+One Node version throughout — 24.19.0, which `.nvmrc` names. The build and the
+tests used to run on different ones, because Angular 14's toolchain and the
+Playwright the suite needs did not accept the same version; from Angular 15 they
+do, so the dist that ships is produced on the same Node that exercised it.
+
+Once that exact bundle is green, stage the publishable npm directory from it:
+
 ```shell
-cedar-embeddable-editor$ npm install
-cedar-embeddable-editor$ ng serve
+npm run package:npm:prebuilt
 ```
 
-1. In your browser, navigate to `http://localhost:4400/`. The app will automatically reload if you change any of the source files.
+This copies the tested bytes to
+`dist-npm/cedar-embeddable-editor/cedar-embeddable-editor.js`, refreshes its
+version, README, changelog, and package lock, and records the bundle manifest.
+The command fails if the browser bundle is stale or does not match its SHA-256
+digest. `npm run check:npm-package` can repeat the byte-for-byte verification
+before `npm pack` or `npm publish`.
+
+## Running as an `npm` package
+
+Releases are published to npmjs.org as
+[`cedar-embeddable-editor`](https://www.npmjs.com/package/cedar-embeddable-editor)
+under the `latest` tag, so an embedder installs the current one by name:
+
+```shell
+npm install cedar-embeddable-editor
+```
 
-## Building the Webcomponent
+`1.6.0` is current on npmjs.org.
 
-This method creates a single Javascript (JS) file that encapsulates all the functionality of CEE. The JS file can be embedded in any application or HTML page. To build a CEE Webcomponent, proceed with these steps:
+Dev snapshots go somewhere else: the BMIR Nexus, as the scoped
+`@org.metadatacenter/cedar-embeddable-editor` under a `dev` tag. `scripts/npm-package.mjs`
+derives which from the version — a `-dev.` in it selects the scoped name and the Nexus
+registry, and anything else the unscoped name and the default one — so the two channels
+cannot be confused by a flag someone forgets to pass. npm routes by scope rather than by
+package name, which is what lets one package come from Nexus while everything else resolves
+from npmjs.org.
 
-### Build and copy the Webcomponent JS file
+A CEDAR frontend names a snapshot through an npm alias:
+
+```json
+"cedar-embeddable-editor": "npm:@org.metadatacenter/cedar-embeddable-editor@2.0.0-dev.20260816.5e7dca6"
+```
+
+Cutting one is in
+[CEE-RUNBOOK.md](https://github.com/metadatacenter/cedar-development/blob/develop/ops/CEE-RUNBOOK.md),
+including the version convention and which host needs what afterwards. Publishing needs the
+Nexus credential; reads are anonymous.
+
+## Testing
+
+The complete test gate is available from the repository root:
 
-1. Run the build command:
 ```shell
-cedar-embeddable-editor$ ng build --configuration=production
+npm run test:ci
 ```
-1. Combine the generated files into a single file and copy the final JS to the sample application:
+
+It runs, in order:
+
+1. `ng lint` over the sources and the ESLint configuration.
+2. A type check of the application and the domain harness, with `strict` on
+   throughout.
+3. The unit tests, in Node under Vitest.
+4. The headless domain harness with V8 coverage, and its per-directory coverage
+   floors.
+5. A production build, then the Playwright suite against that bundle, in a
+   container: the full Chromium baseline at desktop and narrow viewport sizes,
+   plus focused Chromium, Firefox and WebKit compatibility checks. The container
+   is what makes a screenshot baseline mean the same thing on a laptop and on CI,
+   so the pixel budget is zero — see `visual/run-in-container.sh`.
+6. Staging the npm package from the bundle the suite just exercised, which
+   checks the raw and gzip size budgets and verifies every staged byte against
+   its source.
+
+The domain corpora are checked into `harness/fixtures/`; running the tests does
+not require `cedar-artifact-library` or `cedar-test-artifacts` checkouts.
+
+`.github/workflows/test.yml` runs the same gate on every pull request and on
+pushes to `main`, `develop` and the `cee-angular-**` branches. Nothing is
+published from CI: releasing is a separate, manual procedure.
+
+### Auditing what ships
+
 ```shell
-cedar-embeddable-editor$ cat dist/cedar-embeddable-editor/{runtime,polyfills,main}.js > cedar-embeddable-editor.js
+npm run audit:prod
 ```
 
-## Running as an `npm` package
+Only runtime dependencies reach the file an embedder downloads, so this audit is
+the one that describes the shipped artifact, and it is deliberately not part of
+`test:ci` — it can fail on a disclosure rather than on a commit, which would
+break an unrelated pull request its author cannot fix.
+
+A root `npm audit` reports advisories against `@angular/cli` and the packages
+reached through it. **Never run `npm audit fix --force` here.** npm's idea of
+fixing that tree is to walk the toolchain years backwards, undoing the Angular
+march to silence warnings about build tooling an embedder never downloads.
+
+### First-time setup
+
+CEE resolves the model library from `@org.metadatacenter/cedar-model-typescript-library`,
+published to the BMIR Nexus, so no sibling checkout is needed:
+
+```shell
+npm ci
+npm --prefix harness ci
+```
+
+The visual suite installs nothing here. It runs inside Playwright's own container,
+which carries the browsers it drives, and installs its dependencies there against a
+named volume — so it needs Docker running and no `playwright install` of its own.
+
+### Node versions during the Angular migration
+
+The root `.nvmrc` pins the Node version used to update, lint and compile the
+current Angular version. Move that pin with each completed framework hop.
+
+CEE is on **Angular 22.1** and **Node 24.19.0**, named in `.nvmrc`, declared in
+`engines`, and pinned by CI. Angular 22 accepts `^22.22.3 || ^24.15.0 || >=26`; 24
+is the active LTS where 22 is in maintenance, so that is the one CEE uses.
+
+Build and test share it. Through Angular 14 they could not: no Node version
+satisfied both that toolchain and the test tools, so CI built on one and switched
+the runner to another without replacing `dist`. `npm run test:ci:prebuilt` is what
+remains of that arrangement — it tests an already-built artifact and deliberately
+does not invoke `ng build`, which is still what CI wants, because it means the
+bytes tested are the bytes that ship.
+
+Only that one package comes from Nexus; everything else resolves from npmjs.org.
+An `.npmrc` alongside each of the three `package.json` files maps the
+`@org.metadatacenter` scope to Nexus, and reads need no credentials.
+
+Each manifest depends on it under an alias:
+
+```json
+"cedar-model-typescript-library": "npm:@org.metadatacenter/cedar-model-typescript-library@<version>"
+```
+
+The alias keeps the local import name, so source files import
+`cedar-model-typescript-library` regardless of the published name. To move to a
+newer build, publish it to Nexus and bump the version in the root and `visual/`
+manifests together. The harness declares no separate copy; it resolves the root
+installation.
+
+### Focused test commands
+
+Use these when working on one layer:
+
+```shell
+npm run test:unit:ci          # Vitest unit tests, one run
+npm run test:unit:coverage    # unit tests with coverage report
+npm run test:domain           # Vitest domain harness
+npm run test:domain:coverage  # domain harness with coverage report
+npm run test:bundle-size      # exact raw and gzip budgets for the shipped bundle
+npm run test:visual           # production build, fixture preparation, Playwright
+```
+
+`npm test` runs the unit tests once, and `npm run test:watch` keeps them running
+for interactive development. Use `npm run test:ci` for a complete verification.
 
-Please import the latest version of the editor into your project from: [https://www.npmjs.com/package/cedar-embeddable-editor](https://www.npmjs.com/package/cedar-embeddable-editor)
+The unit tests run in Node rather than a browser. None of them uses `TestBed`, so
+none needs Angular's JIT compiler to build a component, and dropping the browser
+took the suite from a Chrome launch to about a second. Anything that does need a
+real browser belongs in the Playwright suite under `visual/`, which tests the
+shipped bundle rather than the sources.
 
 ## Configuration
 
@@ -75,11 +259,11 @@ Please import the latest version of the editor into your project from: [https://
 The CEE configuration file format and storage location depends on the application and the mode in which CEE is being used.
 
 * When running CEE in the standalone mode (developer mode), the configuration parameters are stored in and read from the file: `src/app/app.component.dev.ts`.
-* When running CEE as a generic Webcomponent, the configuration parameters can be stored in any `.json` file that is visible to the application that embeds CEE Webcomponent. CEE Webcomponent API provides a method for loading the configuration file from its path at runtime. For example:
+* When running CEE as a generic Webcomponent, the configuration parameters can be stored in any `.json` file that is visible to the application that embeds CEE Webcomponent. Fetch it and assign the result:
 ```javascript
-document.addEventListener('WebComponentsReady', function () {
+customElements.whenDefined('cedar-embeddable-editor').then(async () => {
   const cee = document.querySelector('cedar-embeddable-editor');
-  cee.loadConfigFromURL('assets/data/cee-config.json');
+  cee.config = await (await fetch('assets/data/cee-config.json')).json();
 });
 ```
 * The configuration can also be passed into the editor as a json map. In Angular this looks as follows:
@@ -94,63 +278,224 @@ document.addEventListener('WebComponentsReady', function () {
 
 ### Required configuration parameters
 
-* **showSampleTemplateLinks:** Wether the sample links are shown or not.
-  * For production this should be false, the template should be injected into the component by the embedding application
-* **terminologyIntegratedSearchUrl:** The URL of the CEDAR integrated search endpoint that communicates with BioPortal.
-  * The value `https://terminology.metadatacenter.org/bioportal/integrated-search` should work for the majority of applications.
+Two keys name the CEDAR services CEE calls, and neither has a default. CEE cannot
+know which deployment it is embedded in, and a default would name one — so a key
+left unset turns its lookups off and CEE reports which key is missing, rather than
+sending a host's users' keystrokes to somebody else's server.
+
+Both are bases and both must end in a slash. Every path below them is CEE's own.
+
+* **terminologyBaseUrl:** the CEDAR terminology server, which searches BioPortal.
+  Unset, controlled fields offer no terms.
+* **bridgeBaseUrl:** the CEDAR bridge server, which reaches the external
+  authorities. Unset, the seven authority fields offer no terms and resolve no
+  identifiers.
 
 ```json
 {
-  "showSampleTemplateLinks": false,
-  "terminologyIntegratedSearchUrl": 'https://terminology.metadatacenter.org/bioportal/integrated-search',
+  "terminologyBaseUrl": "https://terminology.metadatacenter.org/",
+  "bridgeBaseUrl": "https://bridge.metadatacenter.org/"
 }
 ```
 
 ### Optional configuration parameters
 
-There are other optional configuration parameters available for controlling various aspects of the CEE user interface. Most of these are self-explanatory. The example below includes the default values in cases, where the parameter isn't explicitly declared.
+Every other key is optional. The defaults below are the component's own, read
+from `CedarEmbeddableMetadataEditorComponent` and its wrapper, not from the
+standalone developer app in `src/app/app.component.dev.ts`, whose values differ.
+
+What the user sees:
+
+| Key | Default |
+|---|---|
+| `showTemplateDescription` | `false` |
+
+CEE draws no page chrome of its own. It used to render a header carrying the CEDAR
+logo and title, and a footer carrying the Stanford Division of Computational
+Medicine mark and a contact link, behind `showHeader` and `showFooter`. Every string
+and destination was hardcoded, so an embedder took CEDAR's branding or nothing.
+A host renders its own header and footer around the element; the standalone app in
+`src/app/app.component.dev.html` is a worked example.
+
+What CEE keeps is the CEDAR mark and the version stamp inside the form's own title
+block, which is a component naming itself rather than dressing someone else's page.
+
+Editing behaviour and serialization:
+
+| Key | Default |
+|---|---|
+| `readOnlyMode` | `false` |
+| `trustTemplateRichText` | `false` |
+
+`showDownloadMenu` offers a menu that saves CEE's views of the artifact as files.
+It defaults to `false`, and nothing is rendered under the form either way:
+
+| Menu entry | Saves | As |
+|---|---|---|
+| JSON-LD - Instance | The instance as a CEDAR document | `<name>-instance.json` |
+| YAML - Instance | The same instance, as CEDAR YAML | `<name>-instance.yaml` |
+| Compact YAML - Instance | The same instance without root identity and provenance metadata | `<name>-instance-compact.yaml` |
+| JSON Schema - Template | The template as the host supplied it | `<name>-template.json` |
+| YAML - Template | The same template, as CEDAR YAML | `<name>-template.yaml` |
+| Compact YAML - Template | Its compact authoring form, without repository-managed metadata | `<name>-template-compact.yaml` |
+| Data Quality Report | Required-field tally and constraint violations | `<name>-data-quality.json` |
+
+`<name>` is the template's own `schema:name`, reduced to file-name-safe
+characters, so a developer with several forms open can tell the files apart.
+
+These were eight panels once, each printing a dump under the form, and each
+costing two keys — one to show it and one to expand it. Two of the sixteen were
+on by default, so an embedder who configured nothing got a JSON Schema dump and
+a JSON-LD dump beneath every form.
+
+A download is started by the page, which a host running under a restrictive
+sandbox can refuse, with no event to observe when it does. CEE traces each
+attempt through the event handler, so a developer seeing the trace and no file
+knows to look at their own sandbox.
+
+Language:
+
+| Key | Default |
+|---|---|
+| `defaultLanguage` | `en` |
+| `fallbackLanguage` | `en` |
+| `languageMapPathPrefix` | none |
+
+`trustTemplateRichText` decides whether a template author's rich text renders verbatim
+or is sanitized first. It defaults to `false` and should stay there unless your
+application controls which templates load — see [Embedding security](#embedding-security).
+
+`bridgeBaseUrl` is the whole of the external-authority surface, covering the
+seven authorities: ORCID, ROR, PFAS, PubMed, RRID, NIH Grant and DOI. CEE appends
+the bridge server's `ext-auth/` resource, then the path for the authority a field
+is bound to — a search path for a name typed into it, and a details path for an
+identifier pasted into it. All of that is the bridge server's own route shape, so
+none of it is configurable: a deployment moves all fourteen endpoints by moving
+the base, or none of them.
+
+| Authority | Search path | Details path |
+|---|---|---|
+| ORCID | `orcid/search-by-name` | `orcid` |
+| ROR | `ror/search-by-name` | `ror` |
+| PFAS | `comp-tox/search-by-name` | `comp-tox` |
+| PubMed | `pmid/search-by-name` | `pmid` |
+| RRID | `rrid/search-by-name` | `rrid` |
+| NIH Grant | `nih-grant/search-by-name` | `nih-grant` |
+| DOI | `doi/search-by-name` | `doi` |
+
+### TypeScript types
+
+The package ships declarations. A host importing them gets a checked configuration
+object and a typed element:
+
+```ts
+import type { CeeConfig, CedarEmbeddableEditorElement } from 'cedar-embeddable-editor';
+
+const config: CeeConfig = { readOnlyMode: true, showDownloadMenu: true };
+
+// Typed by the package, with no cast: it declares the tag in HTMLElementTagNameMap.
+const cee = document.querySelector('cedar-embeddable-editor');
+cee!.config = config;
+const report = cee!.dataQualityReport;   // CeeDataQualityReport
+```
 
-```json
-{
-  "sampleTemplateLocationPrefix": "http://localhost:4240/cedar-embeddable-editor-sample-templates/",
-  "loadSampleTemplateName": "01",
-  "expandedSampleTemplateLinks": true,
-  "showTemplateDescription": false,
+The declarations are **types only**. The bundle is a script that registers a custom
+element and exports no values, so there is nothing to import at runtime — use
+`import type`, and let the interface rather than a constant catch a mistyped key.
+
+If you are not using TypeScript, or your configuration comes from a JSON file no
+compiler has seen, CEE checks it at runtime instead and reports what it cannot use.
+An unknown key is named, with the nearest real key suggested; a value of the wrong
+kind says what was expected; and settings that conflict are called out. The messages
+go to the console and to any `eventHandler` you registered:
+
+```
+CEE ERROR: Unknown configuration key "readOnlyMod". It has no effect. Did you mean "readOnlyMode"?
+```
+
+A key CEE cannot use is reported *and* refused: it reads as unset, so the setting
+keeps the default it documents. One bad key costs only that key — every other key in
+the same configuration applies. CEE does not repair a value either, so a base URL
+missing its trailing slash is dropped rather than completed, since appending CEE's
+own path to it would name an endpoint nobody chose.
+
+An assignment that is not an object at all configures nothing and does not spend the
+one assignment there is, so your next attempt is still your first.
+
+Configuration and the artifact inputs take one assignment each and keep it. Assign
+`config` a second time, or an artifact input a second time, and CEE reports it and
+ignores it: the first value stands. Build the configuration you want, assign it once,
+and create a new element if it has to change. `eventHandler` is the exception and may
+be replaced, with the last handler assigned receiving — register it before the
+configuration and the artifact if you want the diagnostics from those, since a
+handler hears only what follows it.
+
+The same handler provides the lifecycle signal a host can use instead of polling
+the DOM. `ready` is called once after the element's first successful form render;
+it is not called for a rejected artifact and is not replayed to a handler attached
+after rendering:
+
+```javascript
+cee.eventHandler = {
+  error: (message) => console.error(message),
+  ready: () => startAutosave(),
+};
+```
 
-  "showTemplateRenderingRepresentation": true,
-  "expandedTemplateRenderingRepresentation": false,
+`readOnlyMode` is the only way in or out of read-only mode. CEE used to offer the
+user a switch of its own, in a preferences menu, which wrote to the same state the
+widgets read — so a form you embedded as a viewer could be made editable from inside
+it. Both are gone, along with the `showPreferencesMenu` key that governed the menu.
 
-  "showInstanceDataCore": true,
-  "expandedInstanceDataCore": false,
+## Embedding security
 
-  "showMultiInstanceInfo": true,
-  "expandedMultiInstanceInfo": false,
+CEE renders inside your page, in your origin. It is a custom element using Shadow
+DOM, and **Shadow DOM is not a security boundary**: it scopes styles and markup, not
+privileges. Anything CEE executes runs with the same access to cookies, storage and
+network as the rest of your application.
 
-  "showInstanceDataFull": false,
-  "expandedInstanceDataFull": false,
+That matters for one input in particular.
 
-  "showTemplateSourceData": true,
-  "expandedTemplateSourceData": false,
+### Templates are trusted input
 
-  "showDataQualityReport": false,
-  "expandedDataQualityReport": false,
+A template can carry a **static rich-text field**, whose body is HTML composed by the
+template's author and rendered as HTML by CEE. Instance data is different and is
+always sanitized — a value a form's user typed can never introduce markup that runs.
+The question is only what a *template author* may do.
 
-  "showHeader": true,
-  "showFooter": true,
+CEE sanitizes template rich text by default. Script elements, event-handler
+attributes such as `onerror`, `javascript:` URLs, `iframe`, `form` controls and
+AngularJS directive attributes such as `ng-click` are removed. Formatting is
+preserved: inline styles, tables, lists, headings, links, and inline `data:` images
+in the raster formats all render as the author composed them.
 
-  "languageMapPathPrefix": null,
-  "defaultLanguage": "en",
-  "fallbackLanguage": "en",
+If your application decides which templates load — they ship with the application, or
+come from a source you control — you may prefer the author's markup to render exactly
+as written:
 
-  "collapseStaticComponents": false,
-  "showStaticText": true,
-  
-  "readOnlyMode": false,
-  "hideEmptyFields": false,
-  "showPreferencesMenu": true
+```json
+{
+  "trustTemplateRichText": true
 }
 ```
-Enabling of hiding empty fields is only possible in read-only mode.
+
+**Only set this if template authors are as trusted as your own application code.**
+With it on, a template author can run JavaScript in your origin. "Allowed to define a
+form" and "allowed to run code in this page" are very different permissions, and this
+key is where you say they are the same for your deployment.
+
+In particular, **do not set it if your users choose their own templates** — from
+CEDAR's public library, or from anywhere your users can write to. Leave it off and
+CEE will render the formatting without the risk.
+
+### What is sanitized where
+
+| Content | Origin | Treatment |
+|---|---|---|
+| Static rich-text field body | Template author | Sanitized, unless `trustTemplateRichText` is on |
+| Static section break, image, YouTube | Template author | Not rendered as HTML; content is used as text or a URL |
+| Field values, in the form and in read-only view | Instance data | Always sanitized. Not configurable |
+
 ## Metadata API
 
 CEE Webcomponent includes APIs for exporting metadata externally and importing metadata into CEE.
@@ -163,12 +508,28 @@ The metadata currently being edited inside CEE can be exported at anytime by mak
 const meta = cee.currentMetadata;
 ```
 
+`currentMetadata` always returns a CEDAR JSON object. For YAML, read the
+companion accessor instead:
+
+```javascript
+const yaml = cee.currentMetadataYaml;   // always a YAML string
+```
+
+Either accessor works whatever form the template arrived in. A template written
+as CEDAR YAML is assigned to `templateObject` like any other, as the parsed YAML
+object rather than the YAML source string, and CEE picks the reader from the
+template's own shape:
+
+```javascript
+cee.templateObject = parsedTemplateYaml;
+```
+
 In the example below, the metadata is sent to an external endpoint every 15 seconds:
 
 ```javascript
-document.addEventListener('WebComponentsReady', function () {
+customElements.whenDefined('cedar-embeddable-editor').then(async () => {
   const cee = document.querySelector('cedar-embeddable-editor');
-  cee.loadConfigFromURL('assets/data/cee-config.json');
+  cee.config = await (await fetch('assets/data/cee-config.json')).json();
   const saveTime = 15000; // 15 seconds
 
   setInterval(() => {
@@ -200,38 +561,32 @@ You can inject your metadata into CEE, provided it matches the template currentl
 cee.instanceObject = yourCustomMetadataJson
 ```
 
-In the example below, the metadata is fetched from a remote URL and injected into CEE:
+`templateObject` and `instanceObject` are independent, and either may be assigned
+first: CEE does not build the form until a template is present, so an instance
+supplied ahead of one waits rather than loading against nothing.
 
-```javascript
-function restoreMetadataFromURL(metaUrl, cee, successHandler = null, errorHandler = null) {
-  const xhr = new XMLHttpRequest();
-  xhr.onreadystatechange = () => {
-    if (xhr.readyState === XMLHttpRequest.DONE) {
-      if (xhr.status === 200) {
-        const jsonMeta = JSON.parse(xhr.responseText);
-        cee.instanceObject = jsonMeta;
-
-        if (successHandler) {
-          successHandler(jsonMeta);
-        }
-      } else {
-        if (errorHandler) {
-          errorHandler(xhr);
-        }
-      }
-    }
-  };
-  xhr.open('GET', metaUrl, true);
-  xhr.send();
-}
+Each takes one assignment. Fetch the metadata before you assign it, rather than
+assigning a placeholder and correcting it once the fetch lands:
 
-document.addEventListener('WebComponentsReady', function () {
+```javascript
+customElements.whenDefined('cedar-embeddable-editor').then(async () => {
   const cee = document.querySelector('cedar-embeddable-editor');
-  cee.loadConfigFromURL('assets/data/cee-config.json');
-  restoreMetadataFromURL('uploads/metadata-for-restore.json', cee);
+  cee.config = await (await fetch('assets/data/cee-config.json')).json();
+  cee.instanceObject = await (await fetch('uploads/metadata-for-restore.json')).json();
+  cee.templateObject = yourCustomTemplateJson;
 });
 ```
 
+An instance counts only after CEE can read it. If deserialization fails, CEE
+reports the rejection to the console and to `eventHandler`, does not render a
+replacement empty form, and leaves the instance assignment available for a
+corrected value. The same rule applies to the instance inside
+`templateAndInstanceObject`; a rejected combined value spends neither artifact
+assignment.
+
+To load a different instance, create a new element. Reassigning `instanceObject`
+reports an error and leaves the first instance in place.
+
 To reiterate, the metadata being injected **MUST** match the template currently being edited and open in your browser window.
 
 ### Injecting Template And Metadata Together
@@ -246,6 +601,36 @@ cee.templateAndInstanceObject = templateAndInstance;
 Injecting template and metadata together brings performance benefits as well as allows configuring hiding empty fields.
 Object being injected must strictly have two objects one named 'templateObject' and the other 'instanceObject'.
 
+### Temporal Values
+
+CEE treats a temporal field's declared `temporalType`, `temporalGranularity`
+and `timezoneEnabled` settings as its storage contract. The editor shows only
+the parts named by that contract and emits a complete lexical `xsd:date`,
+`xsd:time` or `xsd:dateTime` value:
+
+| Declared precision | Canonical stored example |
+| --- | --- |
+| date, year | `2026-01-01` |
+| date, month | `2026-08-01` |
+| date, day | `2026-08-09` |
+| time, hour | `21:00:00` |
+| time, minute | `21:45:00` |
+| time, second | `21:45:32` |
+| time, decimal second | `21:45:32.001` |
+| date-time, day | `2026-08-09T00:00:00` |
+| date-time, minute | `2026-08-09T21:45:00` |
+
+The same padding rule applies to the other date-time granularities. If time
+zones are enabled, CEE appends the selected fixed offset (`Z` or `+/-HH:mm`);
+if they are disabled, any offset is removed.
+
+Granularity is authoritative when an existing instance is loaded. Information
+finer than the declared granularity is intentionally discarded and the
+canonical value is written back. For example,
+`2026-08-09T21:45:32.125-07:00` in a day-granularity date-time field becomes
+`2026-08-09T00:00:00-07:00`. Embedders should account for that normalization
+when comparing a saved instance with its original input.
+
 ### Data Quality Report
 
 The dataQualityReport summarizes basic metrics on the instance data.
@@ -254,14 +639,49 @@ The dataQualityReport summarizes basic metrics on the instance data.
 const report = cee.dataQualityReport;
 ```
 
-At the moment these three fields are available, with more to come:
+The report answers two questions: is anything required missing, and is anything
+present invalid.
 
 ```
 requiredFieldValueCount: int
 nonNullRequiredFieldValueCount: int
+problems: ValidationProblem[]
 isValid: boolean
 ```
 
+`isValid` is true when nothing required is missing **and** `problems` is empty.
+
+Each problem names the field and what is wrong with it:
+
+```javascript
+{
+  path: ['_author', '_email'],   // component path from the template root
+  field: '_email',
+  inputType: 'email',
+  code: 'email',                 // stable, matchable without parsing the message
+  message: 'Not a valid email address.',
+  value: 'not-an-email'
+}
+```
+
+Constraints checked: `requiredValue`; `minLength`, `maxLength` and `regex`;
+email, link, phone and external-authority IRI format; numeric type — including
+`xsd:decimal`, `xsd:byte` and `xsd:short` — with the type's own range,
+`minValue`, `maxValue` and `decimalPlace`; temporal shape against
+`temporalType`, `granularity` and `timezoneEnabled`, plus calendar validity;
+membership of a value in its declared choice literals; `minItems` and
+`maxItems`; and the structure of a controlled-term value.
+
+Controlled-term **membership** — whether a term belongs to the declared
+ontologies, value sets, classes or branches — is not checked. It requires the
+terminology server, and a local synchronous report should not depend on the
+network. Structural checks on controlled values (`@id` and `rdfs:label` present
+as a pair, `@id` well-formed) are performed.
+
+An absent value produces no constraint problems; that is the required check's
+business, so an empty form reports what is missing rather than also reporting
+every blank as malformed.
+
 ### Language Maps / Translations
 
 The application currently has two built-in language maps: `en` and `hu`. If you do not specify any language-related config option, the default `English` map will be used.
@@ -301,27 +721,43 @@ Information about the loading process is logged onto the console with the `CEE T
 
 ### Listening for changes
 
-If you need to listen to data changes inside the embeddable editor, you can use the existing `change` DOM events. We added custom events in case of a multi-instance add, copy and delete operations, so you can listen to all the events on the instance.
+CEE emits one composed, bubbling `change` event after an operation actually changes
+the serialized instance. It does not forward incidental DOM control traffic: focus,
+blur, paging, read-only controls, and a write that leaves `currentMetadata` unchanged
+produce no event. Field edits, clears, controlled-term selections, and multi-instance
+add, copy, and delete operations do.
 
-An example in Angular is:
+The event is a `CustomEvent<CeeChangeDetail>`. Its detail carries the operation,
+template path, supplied value, current validity and full data-quality report, plus
+the current title and description. Multi-instance details also retain their former
+`message` name for compatibility.
 
-- `component.html`:
-```html
-<cedar-embeddable-editor
-  [config]="conf"
-  [templateObject]="template"
-  [instanceObject]="instance"
-  (change)="logChange($event)"
-></cedar-embeddable-editor>
-```
+The package's custom-element declaration types the listener and its detail without
+a cast:
 
-- `component.ts`:
 ```typescript
-  logChange(event) {
-    console.log('CHANGE', event);
-  }
+import type { CeeChangeDetail } from 'cedar-embeddable-editor';
+
+const cee = document.querySelector('cedar-embeddable-editor');
+if (!cee) throw new Error('CEE element is missing');
+
+cee.addEventListener('change', (event) => {
+  const detail: CeeChangeDetail = event.detail;
+  console.log(detail.operation, detail.path);
+  console.log('valid:', detail.validity);
+});
 ```
 
+Framework event bindings receive the same custom event. For example, Angular can
+bind `(change)="logChange($event)"` on the element and type the handler parameter as
+`CustomEvent<CeeChangeDetail>`.
+
+The optional `eventHandler.valueChanged(path, value)` callback receives the same
+field mutations. It is not a dirty flag: only the host knows which serialization
+was last loaded or saved. Keep that baseline in the host and compare
+`cee.currentMetadata` after each `change`; doing so also clears dirty state when an
+edit is undone.
+
 ### Viewer Mode
 
 CEE can be used as a viewer to display metadata instances. This can be achieved by the following configuration setting:
@@ -332,11 +768,17 @@ CEE can be used as a viewer to display metadata instances. This can be achieved
 When used in this mode, users won't be able to manipulate the metadata instance but can only read it.
 ## Example Applications
 
-There is a sample applications you can use to demonstrate how to embed and use CEE.
-Follow the links below to the demo application of your choice. The documentation for each demo application can be found in the README file of the corresponding application.
+[`cedar-component-demo`](https://github.com/metadatacenter/cedar-component-demo)
+holds small runnable applications that embed CEE, each with its own README:
 
-### CEE Demo Angular
+| Application | Framework |
+|---|---|
+| `cedar-cee-demo-angular-src` | Angular |
+| `cedar-cee-demo-react` | React |
+| `cedar-cee-demo-ember-src` | Ember |
 
-This demo is written in Angular 2 and requires that framework to run properly.
+Each edits the same template, `eDNA ECT Demonstration`, kept as a file inside the
+application rather than fetched from a server.
 
-https://github.com/metadatacenter/cedar-cee-demo/tree/main/cedar-cee-demo-angular-src
+`cedar-cee-demo-angular-src` needs `npm install --legacy-peer-deps`; the others
+do not.