@dialecte/core 0.7.0 → 0.8.1

package/skills/dialecte/references/api.md

@@ -0,0 +1,557 @@
+# @dialecte/core API index
+
+Generated from the source by `dialecte skills generate`: every public method of the project, document, query and transaction, with the first
+paragraph of its JSDoc and its `@intent` tags. It is the same in the repository and in the installed
+package, and `npm run skills:check` keeps it fresh.
+
+Look up your need in the first table (what you are trying to do), then read the method's row. When a
+method looks close to your need, read its JSDoc and its tests before ruling it out, and name what you
+ruled out and why in your hand-over.
+
+## When you need to...
+
+<!-- dialecte-skills:generated intents -->
+
+| When you need to...                                                                                            | Use                                                  |
+| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| accumulate time spent in a hot per-node function                                                               | `doc.query.perf.time`                                |
+| add a child without duplicating it                                                                             | `tx.ensureChild`                                     |
+| add an attachment owned by a document                                                                          | `project.addBlob`                                    |
+| add custom extensions next to a dialecte's base extensions                                                     | `@dialecte/core/helpers.mergeExtensions`             |
+| add error keys usable with invariant and throwDialecteError                                                    | `@dialecte/core.defineErrors`                        |
+| add or update or delete elements and commit them                                                               | `doc.transaction`                                    |
+| announce how many steps a transaction or nested step has                                                       | `tx.progress.plan`                                   |
+| applied or not applied                                                                                         | `@dialecte/core.importOutcomeOf`                     |
+| apply document updates in a custom store                                                                       | `@dialecte/core.applyDocumentUpdates`                |
+| ask a user to confirm an edit                                                                                  | `doc.prepare`                                        |
+| assert a condition and throw a structured error                                                                | `@dialecte/core/utils.invariant`                     |
+| assert exported XML in tests                                                                                   | `@dialecte/core/test.createXmlAssertions`            |
+| assert in a test that a document is structurally valid for its schema                                          | `@dialecte/core/test.createXmlSchemaAssertions`      |
+| assert on store read counts in a test                                                                          | `doc.query.perf.report`                              |
+| assert that XML does not hold an element                                                                       | `@dialecte/core/test.assertUnexpectedElementQueries` |
+| assert that XML holds the elements XPath queries select                                                        | `@dialecte/core/test.assertExpectedElementQueries`   |
+| attach a blob to a record                                                                                      | `project.attachBlob`                                 |
+| attach an extension map to a query or a transaction                                                            | `@dialecte/core.bindExtensions`                      |
+| attach meta to a diagnostic                                                                                    | `@dialecte/core.createDiagnostic`                    |
+| bind a child frame again after its page rejoined the hub                                                       | `@dialecte/core/sqlite.adoptHubPort`                 |
+| build a diagnostic from a dialecte's catalogue                                                                 | `@dialecte/core.createDiagnostic`                    |
+| build a path from the root                                                                                     | `doc.query.findAncestors`                            |
+| build a tree record from a raw or tracked record                                                               | `@dialecte/core/helpers.toTreeRecord`                |
+| build a valid element from its content model                                                                   | `@dialecte/core/utils.requiredChoices`               |
+| build new content in a transaction                                                                             | `tx.addChild`                                        |
+| build the Error throwDialecteError would throw                                                                 | `@dialecte/core.createDialecteError`                 |
+| build typed test records for a dialecte                                                                        | `@dialecte/core/test.createTestRecordFactory`        |
+| call extension functions as methods of an instance                                                             | `@dialecte/core.bindExtensions`                      |
+| canonicalize attribute names before a write                                                                    | `@dialecte/core/helpers.toFullAttributeArray`        |
+| capture a CPU profile of an async operation in DevTools                                                        | `doc.query.perf.profile`                             |
+| cardinality of children                                                                                        | `@dialecte/core/utils.childOccurrences`              |
+| change a document                                                                                              | `doc.transaction`                                    |
+| change attribute values                                                                                        | `tx.update`                                          |
+| check a built document against expected element counts                                                         | `@dialecte/core/helpers.evaluateExpectations`        |
+| check a document exists                                                                                        | `project.getDocument`                                |
+| check a document path is valid and free before registering it                                                  | `@dialecte/core.assertDocumentPlace`                 |
+| check an element's tag with types                                                                              | `@dialecte/core/helpers.isRecordOf`                  |
+| check exported XML against the XSD structure (namespaces, allowed children, known and required attributes)     | `@dialecte/core/test.createXmlSchemaAssertions`      |
+| check fixtures against the schema                                                                              | `@dialecte/core/test.createTestHelpers`              |
+| check that a document imported in another tab can be opened                                                    | `project.getDocumentStatus`                          |
+| check that a string is a tag name of the dialecte                                                              | `@dialecte/core/helpers.isElementOf`                 |
+| check that a string is an attribute of an element                                                              | `@dialecte/core/helpers.isAttributeOf`               |
+| check that an element was removed from an export                                                               | `@dialecte/core/test.assertUnexpectedElementQueries` |
+| check that an export holds an element                                                                          | `@dialecte/core/test.assertExpectedElementQueries`   |
+| check the tag of a record's parent                                                                             | `@dialecte/core/helpers.isParentOf`                  |
+| check whether a child exists                                                                                   | `doc.query.getChild`                                 |
+| check whether a file or folder path is free                                                                    | `@dialecte/core.pathHolderOf`                        |
+| check whether a project exists on SQLite storage without opening it                                            | `@dialecte/core/sqlite.listProjects`                 |
+| check whether a wildcard admits a namespace                                                                    | `@dialecte/core/utils.isNamespaceAllowedByWildcard`  |
+| check whether an attribute is declared for an element                                                          | `@dialecte/core/utils.getAttributeRules`             |
+| choose the store tests run on                                                                                  | `@dialecte/core/test.useTestStorage`                 |
+| clean up leftover imports when a custom store opens                                                            | `@dialecte/core.removeUnfinishedImports`             |
+| clean up the imports a closed tab or a crash left behind                                                       | `@dialecte/core.removeUnfinishedImports`             |
+| close a nested progress plan                                                                                   | `tx.progress.endPlan`                                |
+| close a project                                                                                                | `project.close`                                      |
+| close the project's database connection from a document                                                        | `doc.close`                                          |
+| collect descendants of given tag names under an element                                                        | `doc.query.findDescendants`                          |
+| collect perf from the store engine                                                                             | `doc.query.perf.snapshot`                            |
+| collect results from every document                                                                            | `project.queryAll`                                   |
+| collect timing spans and read a report of them                                                                 | `@dialecte/core.createPerf`                          |
+| combine extension modules into one registry                                                                    | `@dialecte/core/helpers.mergeExtensions`             |
+| combine timings measured in a worker with the page's                                                           | `doc.query.perf.merge`                               |
+| compare attributes ignoring schema defaults                                                                    | `@dialecte/core/utils.isSchemaDefaultValue`          |
+| compare XML holding generated ids                                                                              | `@dialecte/core/test.normalizeUuids`                 |
+| compare xsi:type values written with different prefixes                                                        | `@dialecte/core/utils.canonicalXsiType`              |
+| connect a page to the origin's hub                                                                             | `@dialecte/core/sqlite.connectHub`                   |
+| copy a subtree with fresh ids                                                                                  | `tx.deepClone`                                       |
+| count store reads or cache hits in dev                                                                         | `doc.query.perf.count`                               |
+| count what a transaction will create                                                                           | `@dialecte/core.summarizeOperations`                 |
+| create a new element under a parent                                                                            | `tx.addChild`                                        |
+| create a new empty document                                                                                    | `project.initEmptyDocument`                          |
+| debug what the store holds                                                                                     | `project.getDatabaseInstance`                        |
+| declare a dialecte package                                                                                     | `@dialecte/core.defineDialecte`                      |
+| declare a dialecte's own error catalogue                                                                       | `@dialecte/core.defineErrors`                        |
+| delete a dialecte's project without opening it                                                                 | `@dialecte/core.createProjectFactory`                |
+| delete a document from the project                                                                             | `project.removeDocument`                             |
+| delete a stored file                                                                                           | `project.removeBlob`                                 |
+| delete a subtree                                                                                               | `tx.delete`                                          |
+| delete a whole project                                                                                         | `project.destroy`                                    |
+| delete the whole project database from a document                                                              | `doc.destroy`                                        |
+| destructure several attributes at once                                                                         | `doc.query.getAttributes`                            |
+| detach a blob from a record                                                                                    | `project.detachBlob`                                 |
+| detect which config a file needs                                                                               | `@dialecte/core.inspectXml`                          |
+| download a document                                                                                            | `project.export`                                     |
+| download a stored file                                                                                         | `project.exportBlob`                                 |
+| download an exported document                                                                                  | `@dialecte/core/utils.saveToDisk`                    |
+| drop attributes before cloning a record                                                                        | `@dialecte/core/helpers.stripAttributes`             |
+| dry-run a transaction                                                                                          | `doc.prepare`                                        |
+| duplicate an element under another parent                                                                      | `tx.deepClone`                                       |
+| end a timed section opened with start                                                                          | `doc.query.perf.stop`                                |
+| export a document from a store in batches                                                                      | `@dialecte/core.runExport`                           |
+| export a document to an XML file                                                                               | `project.export`                                     |
+| expose a record factory in a dialecte's test entry                                                             | `@dialecte/core/test.createTestRecordFactory`        |
+| fail with a core or dialecte error key                                                                         | `@dialecte/core.throwDialecteError`                  |
+| fail with a dialecte error key                                                                                 | `@dialecte/core/utils.invariant`                     |
+| fill a dropdown with allowed values                                                                            | `@dialecte/core/utils.enumeratedValues`              |
+| fill an absent attribute with its schema default or fixed value                                                | `@dialecte/core/utils.resolveSchemaAttributeValue`   |
+| filter child refs by tag name                                                                                  | `@dialecte/core/helpers.isChildOf`                   |
+| filter one tag's elements by attribute                                                                         | `doc.query.findByAttributes`                         |
+| find a declared namespace by its prefix                                                                        | `@dialecte/core/utils.resolveNamespaceByPrefix`      |
+| find a namespace by its config key                                                                             | `@dialecte/core/utils.resolveNamespaceByScope`       |
+| find elements by attribute value                                                                               | `doc.query.findByAttributes`                         |
+| find nested elements at any depth below a scope                                                                | `doc.query.findDescendants`                          |
+| find orphan blobs to clean up                                                                                  | `project.getStandaloneBlobs`                         |
+| find outdated or lost projects on SQLite storage                                                               | `@dialecte/core/sqlite.listProjects`                 |
+| find the enclosing element of a tag                                                                            | `doc.query.findAncestors`                            |
+| find the first match across every document                                                                     | `project.queryFirst`                                 |
+| find the prefix to store an attribute under                                                                    | `@dialecte/core/utils.resolvePrefixByNamespaceScope` |
+| find which config a document uses                                                                              | `doc.query.getDocumentInfo`                          |
+| find which document holds a path                                                                               | `@dialecte/core.pathHolderOf`                        |
+| finish reporting progress for a step                                                                           | `tx.progress.endPlan`                                |
+| fix an invariance type error on a record or ref                                                                | `@dialecte/core/helpers.widen`                       |
+| follow transaction progress                                                                                    | `doc.subscribe`                                      |
+| format XML fixtures inside test files                                                                          | `@dialecte/core/utils.formatEmbeddedXml`             |
+| format XML for a snapshot or a fixture                                                                         | `@dialecte/core/utils.formatXml`                     |
+| get a document as a Blob                                                                                       | `project.export`                                     |
+| get a port to hand a child frame of another origin                                                             | `@dialecte/core/sqlite.connectHub`                   |
+| get deterministic uuids in a test                                                                              | `@dialecte/core/test.createMockRandomUUID`           |
+| get document metadata                                                                                          | `doc.query.getDocumentInfo`                          |
+| get documents to test against                                                                                  | `@dialecte/core/test.createTestProject`              |
+| get every test helper of a dialecte                                                                            | `@dialecte/core/test.createTestHelpers`              |
+| get one direct child by tag name                                                                               | `doc.query.getChild`                                 |
+| get one result per file without a throw for a failed file                                                      | `project.import`                                     |
+| get or create a child                                                                                          | `tx.ensureChild`                                     |
+| get the dialecte config of a document                                                                          | `project.getDocumentConfig`                          |
+| get the Document of an id                                                                                      | `project.openDocument`                               |
+| get the DOM of an exported XML file                                                                            | `@dialecte/core.parseXmlDocument`                    |
+| get the factory that creates a dialecte's projects                                                             | `@dialecte/core.createProjectFactory`                |
+| get the local name of a qualified name                                                                         | `@dialecte/core/utils.extractLocalName`              |
+| get the ref of a record or a relationship                                                                      | `@dialecte/core/helpers.toRef`                       |
+| get the regular expressions an attribute value must match                                                      | `@dialecte/core/utils.valuePatterns`                 |
+| get the root element                                                                                           | `doc.query.getRoot`                                  |
+| give a raw record a change status                                                                              | `@dialecte/core/helpers.toTrackedRecord`             |
+| group edits into one undo step                                                                                 | `doc.transaction`                                    |
+| guard against a missing record                                                                                 | `@dialecte/core/utils.invariant`                     |
+| handle a dialecte error in a catch block                                                                       | `@dialecte/core.toDialecteError`                     |
+| how many times a child may appear                                                                              | `@dialecte/core/utils.childOccurrences`              |
+| implement exportFile of a custom store                                                                         | `@dialecte/core.runExport`                           |
+| implement importFile of a custom store                                                                         | `@dialecte/core.runImport`                           |
+| import a file into a store with core's import pipeline                                                         | `@dialecte/core.runImport`                           |
+| import an XML file                                                                                             | `project.importFile`                                 |
+| import several XML files at once                                                                               | `project.import`                                     |
+| indent XML without changing values                                                                             | `@dialecte/core/utils.formatXml`                     |
+| insert a child with attributes                                                                                 | `tx.addChild`                                        |
+| inspect the underlying database                                                                                | `project.getDatabaseInstance`                        |
+| iterate one level below an element                                                                             | `doc.query.getChildren`                              |
+| join the hub from an iframe of another origin                                                                  | `@dialecte/core/sqlite.adoptHubPort`                 |
+| know what an element may hold under its parent                                                                 | `@dialecte/core/utils.resolveDefinition`             |
+| know what an xsi:type lets an element hold                                                                     | `doc.query.getDefinition`                            |
+| know whether an attribute is required                                                                          | `@dialecte/core/utils.getAttributeRules`             |
+| know which schema a document uses                                                                              | `project.getDocumentConfig`                          |
+| know which schema value an absent attribute takes                                                              | `@dialecte/core/utils.resolveSchemaAttributeValue`   |
+| link a stored file to an element                                                                               | `project.attachBlob`                                 |
+| list allowed attributes or enumeration values                                                                  | `doc.query.getDefinition`                            |
+| list direct children of one tag name                                                                           | `doc.query.getChildren`                              |
+| list every element of a tag in the whole document                                                              | `doc.query.getRecordsByTagName`                      |
+| list the allowed values of an attribute                                                                        | `@dialecte/core/utils.enumeratedValues`              |
+| list the ancestors of an element                                                                               | `doc.query.findAncestors`                            |
+| list the documents of a project                                                                                | `project.getDocuments`                               |
+| list the files attached to a document                                                                          | `project.getBlobsByDocument`                         |
+| list the files attached to one element                                                                         | `project.getBlobsByRecord`                           |
+| list the projects stored in the browser on SQLite storage                                                      | `@dialecte/core/sqlite.listProjects`                 |
+| list the xsi:type values an element may take                                                                   | `@dialecte/core/utils.admittedXsiTypes`              |
+| list unattached files                                                                                          | `project.getStandaloneBlobs`                         |
+| listen to project events                                                                                       | `project.createChannel`                              |
+| load a blob by id                                                                                              | `project.getBlob`                                    |
+| load a file into the project                                                                                   | `project.importFile`                                 |
+| load one element by id                                                                                         | `doc.query.getRecord`                                |
+| load several elements by ref at once                                                                           | `doc.query.getRecords`                               |
+| look up an attribute of a held record in a pure function with no query                                         | `@dialecte/core/helpers.readAttribute`               |
+| look up an attribute value on a record you already hold in an import hook                                      | `@dialecte/core/helpers.readAttribute`               |
+| look up an element by an identifying attribute                                                                 | `doc.query.findByAttributes`                         |
+| look up the attribute values of a record you already hold in an import hook                                    | `@dialecte/core/helpers.readAttributes`              |
+| look up the attributes of a held record in a pure function with no query                                       | `@dialecte/core/helpers.readAttributes`              |
+| make generated ids reproducible                                                                                | `@dialecte/core/utils.createSeededRandomUuid`        |
+| make sure a singleton container exists before adding under it                                                  | `tx.ensureChild`                                     |
+| make XPath assertions bound to a dialecte's namespaces                                                         | `@dialecte/core/test.createXmlAssertions`            |
+| map a prefix to its namespace URI                                                                              | `@dialecte/core/utils.resolveNamespaceByPrefix`      |
+| map old ids to new ids                                                                                         | `tx.deepClone`                                       |
+| mark a progress step done                                                                                      | `tx.progress.nextStep`                               |
+| measure how long an operation takes                                                                            | `doc.query.perf.start`                               |
+| measure how long operations take in development                                                                | `@dialecte/core.createPerf`                          |
+| mock crypto.randomUUID                                                                                         | `@dialecte/core/test.createMockRandomUUID`           |
+| name the store table holding a document's blob data                                                            | `@dialecte/core.blobTableName`                       |
+| name the store table holding a document's records                                                              | `@dialecte/core.recordTableName`                     |
+| narrow a child relationship to one tag                                                                         | `@dialecte/core/helpers.isChildOf`                   |
+| narrow a diagnostic to a catalogue's codes                                                                     | `@dialecte/core.isKnownDiagnostic`                   |
+| narrow a parent relationship to one tag                                                                        | `@dialecte/core/helpers.isParentOf`                  |
+| narrow a record to a tree node                                                                                 | `@dialecte/core/helpers.isTreeRecord`                |
+| narrow a record to its raw shape                                                                               | `@dialecte/core/helpers.isRawRecord`                 |
+| narrow a record to its tracked shape                                                                           | `@dialecte/core/helpers.isTrackedRecord`             |
+| narrow a record to one tag name                                                                                | `@dialecte/core/helpers.isRecordOf`                  |
+| narrow an attribute name before a typed read                                                                   | `@dialecte/core/helpers.isAttributeOf`               |
+| narrow an error key for a switch                                                                               | `@dialecte/core.isKnownDialecteError`                |
+| narrow an unknown tag name before a typed query                                                                | `@dialecte/core/helpers.isElementOf`                 |
+| narrow attribute input                                                                                         | `@dialecte/core/helpers.isFullAttributeArray`        |
+| normalize attribute order after a hook                                                                         | `@dialecte/core/utils.orderAttributesBySequence`     |
+| offer a dialecte's engine to the hub (`factory.spawner`)                                                       | `@dialecte/core/sqlite.connectHub`                   |
+| offer type choices for an element                                                                              | `@dialecte/core/utils.admittedXsiTypes`              |
+| one report across realms                                                                                       | `doc.query.perf.merge`                               |
+| open a document to read or write it                                                                            | `project.openDocument`                               |
+| open a project in a test with a fixture imported                                                               | `@dialecte/core/test.createTestProject`              |
+| open a save dialog in the browser                                                                              | `@dialecte/core/utils.saveToDisk`                    |
+| open or create a project database                                                                              | `project.open`                                       |
+| open projects of a dialecte from an app                                                                        | `@dialecte/core.createProjectFactory`                |
+| open projects on SQLite storage in a child frame through its page's engine                                     | `@dialecte/core/sqlite.adoptHubPort`                 |
+| order nodes the way the export writes them                                                                     | `@dialecte/core/utils.orderByConfigSequence`         |
+| parse XML into records                                                                                         | `project.importFile`                                 |
+| pass a per-element record or ref to an API typed with the element union                                        | `@dialecte/core/helpers.widen`                       |
+| pass a raw or tree record where a tracked record is expected                                                   | `@dialecte/core/helpers.toTrackedRecord`             |
+| pass a record where a raw record is expected                                                                   | `@dialecte/core/helpers.toRawRecord`                 |
+| pass a ref to a query                                                                                          | `@dialecte/core/helpers.toRef`                       |
+| paste a tree read with getTree                                                                                 | `tx.deepClone`                                       |
+| peek at an XML file before importing it                                                                        | `@dialecte/core.inspectXml`                          |
+| pretty-print an XML string                                                                                     | `@dialecte/core/utils.formatXml`                     |
+| preview changes before committing                                                                              | `doc.prepare`                                        |
+| preview what a transaction would commit                                                                        | `doc.query.getSnapshot`                              |
+| print perf metrics to the console                                                                              | `doc.query.perf.log`                                 |
+| project a filtered tree with select or omit                                                                    | `doc.query.getTree`                                  |
+| prune a child from its parent                                                                                  | `tx.delete`                                          |
+| put attributes in schema order                                                                                 | `@dialecte/core/utils.orderAttributesBySequence`     |
+| query an export with XPath                                                                                     | `@dialecte/core.parseXmlDocument`                    |
+| raise an error a consumer can read by key                                                                      | `@dialecte/core.throwDialecteError`                  |
+| react to document changes in a UI                                                                              | `doc.subscribe`                                      |
+| read a blob with its file name                                                                                 | `project.exportBlob`                                 |
+| read a document's name or config key by id                                                                     | `project.getDocument`                                |
+| read a document's records from the local database directly                                                     | `@dialecte/core.recordTableName`                     |
+| read a namespaced attribute                                                                                    | `doc.query.getAttribute`                             |
+| read a subtree in document order                                                                               | `doc.query.getTree`                                  |
+| read a subtree to copy it with deepClone                                                                       | `doc.query.getTree`                                  |
+| read all attribute values of an element                                                                        | `doc.query.getAttributes`                            |
+| read an attached file's content                                                                                | `project.getBlob`                                    |
+| read an attribute of an element                                                                                | `doc.query.getAttribute`                             |
+| read an attribute with its schema default                                                                      | `doc.query.getAttribute`                             |
+| read an attribute's default or fixed value                                                                     | `@dialecte/core/utils.getAttributeRules`             |
+| read an export as an XMLDocument in the page                                                                   | `@dialecte/core.parseXmlDocument`                    |
+| read attributes of one namespace                                                                               | `doc.query.getAttributes`                            |
+| read collected perf metrics                                                                                    | `doc.query.perf.report`                              |
+| read one attribute value                                                                                       | `doc.query.getAttribute`                             |
+| read staged changes as XML or as a tree                                                                        | `doc.query.getSnapshot`                              |
+| read the attributes of an element                                                                              | `doc.query.getAttributes`                            |
+| read the definition of a record you hold without a query                                                       | `@dialecte/core/utils.resolveDefinition`             |
+| read the document name or extension                                                                            | `doc.query.getDocumentInfo`                          |
+| read the enumeration of a datatype                                                                             | `@dialecte/core/utils.enumeratedValues`              |
+| read the exported XML as a DOM                                                                                 | `project.export`                                     |
+| read the root element or a version attribute without a full parse                                              | `@dialecte/core.inspectXml`                          |
+| read the schema definition of an element                                                                       | `doc.query.getDefinition`                            |
+| read the structured error from a caught value                                                                  | `@dialecte/core.toDialecteError`                     |
+| read the type an element names with xsi:type                                                                   | `@dialecte/core/utils.resolveXsiType`                |
+| receive commits and imports made in other tabs                                                                 | `project.createChannel`                              |
+| recover after a connection lost during a write                                                                 | `@dialecte/core.writeOutcomeOf`                      |
+| recover after a connection lost during an import                                                               | `@dialecte/core.importOutcomeOf`                     |
+| redo an undone change to a document                                                                            | `project.redo`                                       |
+| refresh a record                                                                                               | `doc.query.getRecord`                                |
+| refresh a view after a commit or an undo                                                                       | `doc.subscribe`                                      |
+| register a dialecte's configs and extensions and hooks once                                                    | `@dialecte/core.defineDialecte`                      |
+| register a dialecte's engine with the hub                                                                      | `@dialecte/core.createProjectFactory`                |
+| register documents in a custom store                                                                           | `@dialecte/core.assertDocumentPlace`                 |
+| register this page's dialecte engines with the hub before any project opens                                    | `@dialecte/core/sqlite.connectHub`                   |
+| reindent xml template literals in source code                                                                  | `@dialecte/core/utils.formatEmbeddedXml`             |
+| release the database connection when leaving a page                                                            | `project.close`                                      |
+| remove a blob for good                                                                                         | `project.removeBlob`                                 |
+| remove an element                                                                                              | `tx.delete`                                          |
+| remove attributes from a record                                                                                | `@dialecte/core/helpers.stripAttributes`             |
+| remove one file and its records                                                                                | `project.removeDocument`                             |
+| rename an element through its name attribute                                                                   | `tx.update`                                          |
+| rename or move a document by its path                                                                          | `@dialecte/core.applyDocumentUpdates`                |
+| reopen a project after close                                                                                   | `project.open`                                       |
+| report a caught error as a dialecte error without throwing                                                     | `@dialecte/core.createDialecteError`                 |
+| report an import or validation problem as a typed diagnostic                                                   | `@dialecte/core.createDiagnostic`                    |
+| report progress of a long operation                                                                            | `tx.progress.plan`                                   |
+| required or optional children of an element                                                                    | `@dialecte/core/utils.childOccurrences`              |
+| reset perf metrics between measured scenarios                                                                  | `doc.query.perf.reset`                               |
+| resolve a list of children or relationships in one batched read                                                | `doc.query.getRecords`                               |
+| resolve a namespace scope to its prefix and URI                                                                | `@dialecte/core/utils.resolveNamespaceByScope`       |
+| resolve a ref or parent/child relationship to its record                                                       | `doc.query.getRecord`                                |
+| resolve an xsi:type prefix to its namespace                                                                    | `@dialecte/core/utils.resolveXsiType`                |
+| roll back a commit                                                                                             | `project.undo`                                       |
+| run node tests on the in-memory store                                                                          | `@dialecte/core/test.useTestStorage`                 |
+| run one query over all documents                                                                               | `project.queryAll`                                   |
+| run table-driven test cases on a dialecte                                                                      | `@dialecte/core/test.createTestRunner`               |
+| run tests on SQLite                                                                                            | `@dialecte/core/test.useTestStorage`                 |
+| save a Blob as a file                                                                                          | `@dialecte/core/utils.saveToDisk`                    |
+| save a blob to disk                                                                                            | `project.exportBlob`                                 |
+| save a document as XML                                                                                         | `project.export`                                     |
+| scan all elements of one type regardless of position                                                           | `doc.query.getRecordsByTagName`                      |
+| search all documents of a project                                                                              | `project.queryFirst`                                 |
+| seed crypto.randomUUID for a script or a test                                                                  | `@dialecte/core/utils.createSeededRandomUuid`        |
+| send a worker's or another realm's timings to the page                                                         | `doc.query.perf.snapshot`                            |
+| serve a dialecte's engine from a worker                                                                        | `@dialecte/core/engine.serveDialecteEngine`          |
+| set an element's text value                                                                                    | `tx.update`                                          |
+| set or clear an attribute                                                                                      | `tx.update`                                          |
+| set up a dialecte package's tests                                                                              | `@dialecte/core/test.createTestHelpers`              |
+| set up a new dialecte                                                                                          | `@dialecte/core.defineDialecte`                      |
+| share one SQLite engine per project between the tabs of an app                                                 | `@dialecte/core.createProjectFactory`                |
+| ship a dialecte's SQLite engine in its package                                                                 | `@dialecte/core/engine.serveDialecteEngine`          |
+| show a confirmation summary before commit                                                                      | `@dialecte/core.summarizeOperations`                 |
+| show a progress bar caption                                                                                    | `tx.progress.plan`                                   |
+| show how much space each project takes                                                                         | `@dialecte/core/sqlite.listProjects`                 |
+| show the files a project holds                                                                                 | `project.getDocuments`                               |
+| show what a prepared transaction would produce                                                                 | `doc.query.getSnapshot`                              |
+| snapshot a document independently of random uuids                                                              | `@dialecte/core/test.normalizeUuids`                 |
+| sort children in schema order                                                                                  | `@dialecte/core/utils.orderByConfigSequence`         |
+| split a document path into folders and file name                                                               | `@dialecte/core.parseDocumentPath`                   |
+| start a document from scratch without a file                                                                   | `project.initEmptyDocument`                          |
+| start a walk from the top of the document                                                                      | `doc.query.getRoot`                                  |
+| start working on a project                                                                                     | `project.open`                                       |
+| store a binary file in the project                                                                             | `project.addBlob`                                    |
+| store blobs in a custom store                                                                                  | `@dialecte/core.blobTableName`                       |
+| strip a record to its stored fields                                                                            | `@dialecte/core/helpers.toRawRecord`                 |
+| strip the prefix from an attribute name                                                                        | `@dialecte/core/utils.extractLocalName`              |
+| summarize a prepared transaction per tag                                                                       | `@dialecte/core.summarizeOperations`                 |
+| tally calls of a hot function cheaply                                                                          | `doc.query.perf.count`                               |
+| tell a stored record from a tracked or tree record                                                             | `@dialecte/core/helpers.isRawRecord`                 |
+| tell a tracked record from a raw or tree record                                                                | `@dialecte/core/helpers.isTrackedRecord`             |
+| tell a tree record from a raw or tracked record                                                                | `@dialecte/core/helpers.isTreeRecord`                |
+| tell an attribute array from an attribute value object                                                         | `@dialecte/core/helpers.isFullAttributeArray`        |
+| tell whether a value equals an attribute's default                                                             | `@dialecte/core/utils.isSchemaDefaultValue`          |
+| tell whether an import is running                                                                              | `@dialecte/core.importOutcomeOf`                     |
+| tell whether an import or a commit was applied                                                                 | `@dialecte/core.writeOutcomeOf`                      |
+| tell whether foreign attributes or elements are allowed                                                        | `@dialecte/core/utils.isNamespaceAllowedByWildcard`  |
+| tell which diagnostic an import reported                                                                       | `@dialecte/core.isKnownDiagnostic`                   |
+| tell which error was thrown                                                                                    | `@dialecte/core.isKnownDialecteError`                |
+| test a transaction against expected XML                                                                        | `@dialecte/core/test.createTestRunner`               |
+| test what a prepared transaction would write                                                                   | `@dialecte/core/helpers.evaluateExpectations`        |
+| the branches of a required choice                                                                              | `@dialecte/core/utils.requiredChoices`               |
+| throw a structured error                                                                                       | `@dialecte/core.throwDialecteError`                  |
+| time a callback without flooding the timeline                                                                  | `doc.query.perf.time`                                |
+| time a code section in dev                                                                                     | `doc.query.perf.start`                               |
+| turn a record into a tree node                                                                                 | `@dialecte/core/helpers.toTreeRecord`                |
+| turn an attribute value object into an attribute array                                                         | `@dialecte/core/helpers.toFullAttributeArray`        |
+| undo the last change to a document                                                                             | `project.undo`                                       |
+| unlink a file from an element                                                                                  | `project.detachBlob`                                 |
+| update and delete                                                                                              | `@dialecte/core.summarizeOperations`                 |
+| update the progress caption                                                                                    | `tx.progress.nextStep`                               |
+| use SQLite storage in an app (import `@dialecte/core/sqlite` once and open with `storage: { type: 'sqlite' }`) | `@dialecte/core.createProjectFactory`                |
+| validate a document path                                                                                       | `@dialecte/core.parseDocumentPath`                   |
+| validate an attribute value against its datatype patterns                                                      | `@dialecte/core/utils.valuePatterns`                 |
+| validate an exported XML file against the schema in a test                                                     | `@dialecte/core/test.createXmlSchemaAssertions`      |
+| verify a script's result before committing                                                                     | `@dialecte/core/helpers.evaluateExpectations`        |
+| wait for a document from another realm                                                                         | `project.getDocumentStatus`                          |
+| walk children recursively                                                                                      | `doc.query.getTree`                                  |
+| walk definitions top-down                                                                                      | `@dialecte/core/utils.resolveDefinition`             |
+| which children an element must hold where its content model offers a choice                                    | `@dialecte/core/utils.requiredChoices`               |
+| wipe every document of the project                                                                             | `doc.destroy`                                        |
+| wipe the project database with every document                                                                  | `project.destroy`                                    |
+| word a diagnostic for a user                                                                                   | `@dialecte/core.isKnownDiagnostic`                   |
+| word an error for a user                                                                                       | `@dialecte/core.isKnownDialecteError`                |
+| write a dialecte package's engine worker file                                                                  | `@dialecte/core/engine.serveDialecteEngine`          |
+| write an attribute in a declared or custom namespace                                                           | `@dialecte/core/utils.resolvePrefixByNamespaceScope` |
+| write an xsi:type value the way core stores it                                                                 | `@dialecte/core/utils.canonicalXsiType`              |
+
+<!-- /dialecte-skills:generated -->
+
+## Methods
+
+<!-- dialecte-skills:generated api -->
+
+| Method                                                                        | What it answers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Reach for it to                                                                                                                                      |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `doc.close`                                                                   | Close the connection to the project's store, shared by every document of the project: after it, no document of this project can read or write. With a built-in store (local, in-memory), opening the project again gives a new store: documents opened before stay closed, open them again from the project. A custom store is reopened in place. To finish with the project, use `project.close`.                                                                                                                                                                                                                                                                                                                                   | close the project's database connection from a document                                                                                              |
+| `doc.destroy`                                                                 | Delete the whole project database and let the connection go: every document of the project, its history and its blobs - not only this document; refused `PROJECT_OPEN_ELSEWHERE`, nothing removed and the connection kept, while another connection has the project open. To delete one document, use `project.removeDocument`.                                                                                                                                                                                                                                                                                                                                                                                                      | delete the whole project database from a document; wipe every document of the project                                                                |
+| `doc.prepare`                                                                 | Build up operations without committing. Returns a PreparedTransaction with staged operations for preview, then call commit() to apply or discard() to throw away.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | preview changes before committing; ask a user to confirm an edit; dry-run a transaction                                                              |
+| `doc.query.findAncestors`                                                     | Walk the parent chain from an element upward, one store read per step; for the parent alone, `getRecord(record.parent)` is enough.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | list the ancestors of an element; find the enclosing element of a tag; build a path from the root                                                    |
+| `doc.query.findByAttributes`                                                  | Find records of one tag matching specific attribute values; it scans every element of that tag in the document.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | find elements by attribute value; look up an element by an identifying attribute; filter one tag's elements by attribute                             |
+| `doc.query.findDescendants`                                                   | Find all descendants of an element, grouped by tag name, in no guaranteed order: walk a `getTree` result for document order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | collect descendants of given tag names under an element; find nested elements at any depth below a scope                                             |
+| `doc.query.getAttribute`                                                      | Read a single attribute value of an element (a ref, a record or a relationship).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | read an attribute of an element; read one attribute value; read a namespaced attribute; read an attribute with its schema default                    |
+| `doc.query.getAttributes`                                                     | Read an element's attributes as a destructurable value object, each under the name it is stored by - what a write takes back. Get a record's attributes for a namespace scope, keyed by **local** name. Get a record's attributes for a custom namespace scope not declared in the config, keyed by local name. Get all attributes of a record as an array of full attribute objects.                                                                                                                                                                                                                                                                                                                                                | read the attributes of an element; read all attribute values of an element; destructure several attributes at once; read attributes of one namespace |
+| `doc.query.getChild`                                                          | Get the first direct child of an element matching a given tag name; it looks one level down only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | get one direct child by tag name; check whether a child exists                                                                                       |
+| `doc.query.getChildren`                                                       | Get all direct children of an element matching a given tag name; it looks one level down only, no recursion.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | list direct children of one tag name; iterate one level below an element                                                                             |
+| `doc.query.getDefinition`                                                     | The definition of an element in its context: the declaration its parent holds when the schema declares the tag several ways, and what the type it names with xsi:type lets it hold.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | read the schema definition of an element; list allowed attributes or enumeration values; know what an xsi:type lets an element hold                  |
+| `doc.query.getDocumentInfo`                                                   | Get the full metadata record of this document.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | read the document name or extension; get document metadata; find which config a document uses                                                        |
+| `doc.query.getRecord`                                                         | Get a single record by ref, record, or relationship, in one store read.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | load one element by id; resolve a ref or parent/child relationship to its record; refresh a record                                                   |
+| `doc.query.getRecords`                                                        | Get multiple records in a single call.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | load several elements by ref at once; resolve a list of children or relationships in one batched read                                                |
+| `doc.query.getRecordsByTagName`                                               | Get all records of a given tag name in the whole document, read from the tag index: the cheapest whole-document scan.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | list every element of a tag in the whole document; scan all elements of one type regardless of position                                              |
+| `doc.query.getRoot`                                                           | Get the root element of the document.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | get the root element; start a walk from the top of the document                                                                                      |
+| `doc.query.getSnapshot`                                                       | Snapshot the (uncommitted) document state as a tree, XML string, or both: a view that includes staged changes. The stored file, to save or download, comes from `project.export`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | preview what a transaction would commit; read staged changes as XML or as a tree; show what a prepared transaction would produce                     |
+| `doc.query.getTree`                                                           | Build a full tree structure from an element down. It loads the whole document unless it is a committed read with an id and a depth.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | read a subtree in document order; walk children recursively; project a filtered tree with select or omit; read a subtree to copy it with deepClone   |
+| `doc.query.perf.count` (also `doc.perf.count`, `project.perf.count`)          | O(1) tally for a hot per-node primitive (e.g. store round-trips, cache hits/misses) — cheaper than a span and safe in a node loop where per-call `start`/`stop` would flood the timeline. Surfaced as `count` in `report()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | count store reads or cache hits in dev; tally calls of a hot function cheaply                                                                        |
+| `doc.query.perf.log` (also `doc.perf.log`, `project.perf.log`)                | Print the perf report as a console table (`console.table(report())`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | print perf metrics to the console                                                                                                                    |
+| `doc.query.perf.merge` (also `doc.perf.merge`, `project.perf.merge`)          | Fold another realm's snapshot in under `<prefix>::<name>`: its spans placed on this realm's timeline (shifted by the difference of the two `timeOrigin`s), its tallies added to this one's.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | combine timings measured in a worker with the page's; one report across realms                                                                       |
+| `doc.query.perf.profile` (also `doc.perf.profile`, `project.perf.profile`)    | Run `fn` inside a DevTools CPU profile (no-op in node/headless).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | capture a CPU profile of an async operation in DevTools                                                                                              |
+| `doc.query.perf.report` (also `doc.perf.report`, `project.perf.report`)       | Aggregate the timeline synchronously on demand — no `PerformanceObserver`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | read collected perf metrics; assert on store read counts in a test                                                                                   |
+| `doc.query.perf.reset` (also `doc.perf.reset`, `project.perf.reset`)          | Clear all marks + measures (bound memory between measured scenarios).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | reset perf metrics between measured scenarios                                                                                                        |
+| `doc.query.perf.snapshot` (also `doc.perf.snapshot`, `project.perf.snapshot`) | This realm's spans (the shared timeline's; this perf's own with `timeline: false`) and this perf's tallies, to hand to another realm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | send a worker's or another realm's timings to the page; collect perf from the store engine                                                           |
+| `doc.query.perf.start` (also `doc.perf.start`, `project.perf.start`)          | Open a span. Name-keyed pair (like `console.time`); name = `layer::op`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | time a code section in dev; measure how long an operation takes                                                                                      |
+| `doc.query.perf.stop` (also `doc.perf.stop`, `project.perf.stop`)             | Close the most recent open span for `name`. Unmatched `stop` is a no-op.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | end a timed section opened with start                                                                                                                |
+| `doc.query.perf.time` (also `doc.perf.time`, `project.perf.time`)             | O(1) wall-time accumulator: runs `fn`, adds its elapsed time to a running total keyed by `name` WITHOUT emitting a timeline measure per call (unlike `start`/`stop`). Surfaced as calls/totalMs/avgMs in `report()`. Use to time a hot per-node primitive (e.g. the SAX handlers) where millions of measures would flood the timeline.                                                                                                                                                                                                                                                                                                                                                                                               | accumulate time spent in a hot per-node function; time a callback without flooding the timeline                                                      |
+| `doc.subscribe`                                                               | Register a callback fired (synchronously, same-realm) whenever this document's shared state changes: progress steps + loading toggles during a transaction, undo/redo, and folded-in cross-realm commits. `terminal` is `true` for the final frame of an operation, letting a consumer flush it without coalescing. Returns an unsubscribe function. Wired from the owning Project's registry.                                                                                                                                                                                                                                                                                                                                       | react to document changes in a UI; refresh a view after a commit or an undo; follow transaction progress                                             |
+| `doc.transaction`                                                             | Run `fn` against a new transaction and commit everything it staged as one undoable step; on a throw nothing is written. A second transaction started on this Document while one runs throws `CONCURRENT_TRANSACTION`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | change a document; add or update or delete elements and commit them; group edits into one undo step                                                  |
+| `project.addBlob`                                                             | Add a blob owned by `documentId`. The binary lives in `blob_{documentId}`. Returns the generated blob id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | store a binary file in the project; add an attachment owned by a document                                                                            |
+| `project.attachBlob`                                                          | Reference an existing blob from an element of a document (optionally from one of its attributes) and tell other tabs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | link a stored file to an element; attach a blob to a record                                                                                          |
+| `project.close`                                                               | Close the store and release resources, once the imports in flight (running and queued), the project's writes running (a Document's transaction or prepared commit included) and the work other realms' messages started have settled. Then the channel and the store are closed, `state.documents` is emptied and the Documents' subscriptions are dropped. From the call on, the project is closed: a new call throws `PROJECT_NOT_OPENED`, a Document opened before answers `STORE_CLOSED` (on a `custom` store opened again it writes but tells nothing: open it again). The stored documents stay. Runs in turn with the Project's other `open`, `close` and `destroy` calls.                                                    | close a project; release the database connection when leaving a page                                                                                 |
+| `project.createChannel`                                                       | Convenience: a fresh BroadcastChannel on this project's channel. The caller owns it — call channel.close() when done listening.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | listen to project events; receive commits and imports made in other tabs                                                                             |
+| `project.destroy`                                                             | Destroy the project - deletes the database entirely, every document with its history and blobs, once the imports in flight have landed; refused `PROJECT_OPEN_ELSEWHERE`, nothing removed, while another connection - a project or store of the name, in this page or another tab - has it open. To delete one document, use `removeDocument`.                                                                                                                                                                                                                                                                                                                                                                                       | delete a whole project; wipe the project database with every document                                                                                |
+| `project.detachBlob`                                                          | Drop the reference from an element of a document to a blob; the blob itself stays stored.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | unlink a file from an element; detach a blob from a record                                                                                           |
+| `project.export`                                                              | Export a document through the store: its file (`Blob`, formatted unless `indent: false`) and filename. On the page, `xmlDocument: true` also answers its DOM (parsed from the compact file: pass `indent: false` to export once) and `download` saves the formatted file (the save dialog is asked first). Two store exports made for one call may see two states of the document if a commit lands between them.                                                                                                                                                                                                                                                                                                                    | export a document to an XML file; get a document as a Blob; download a document; save a document as XML; read the exported XML as a DOM              |
+| `project.exportBlob`                                                          | Export a blob from the store: `{ entry, data, filename }`; `download` also saves it (the save dialog, or a browser download), under its name or the one given.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | download a stored file; save a blob to disk; read a blob with its file name                                                                          |
+| `project.getBlob`                                                             | Read a stored blob: its metadata entry and its binary data, or `undefined` when the id is unknown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | read an attached file's content; load a blob by id                                                                                                   |
+| `project.getBlobsByDocument`                                                  | The blobs referenced from a document (any of their attachments points into it).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | list the files attached to a document                                                                                                                |
+| `project.getBlobsByRecord`                                                    | The blobs referenced from one element of a document.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | list the files attached to one element                                                                                                               |
+| `project.getDatabaseInstance`                                                 | Expose the store's own database object, for debugging: the Dexie instance on `local` (cast it: the type is the store's, `unknown` unless the Project's store type is given), `null` on `sqlite` and `inMemory`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | inspect the underlying database; debug what the store holds                                                                                          |
+| `project.getDocument`                                                         | The metadata record of one document of the project, or `undefined` when it is unknown or still importing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | check a document exists; read a document's name or config key by id                                                                                  |
+| `project.getDocumentConfig`                                                   | Get the dialecte config a document uses, or `undefined` for a document the project does not know.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | get the dialecte config of a document; know which schema a document uses                                                                             |
+| `project.getDocuments`                                                        | The documents of the project; one still importing - here or in another realm - is not among them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | list the documents of a project; show the files a project holds                                                                                      |
+| `project.getDocumentStatus`                                                   | Reconcile this realm's store against persisted state, then report the document's liveness and readiness: - `live` — the document is registered in this realm's registry (so `openDocument` will not throw DOCUMENT_NOT_REGISTERED). - `ready` — the store can serve the document's records (so reads / export will not throw, e.g. a missing per-document table).                                                                                                                                                                                                                                                                                                                                                                    | check that a document imported in another tab can be opened; wait for a document from another realm                                                  |
+| `project.getStandaloneBlobs`                                                  | The blobs of the project that no document references (no attachment).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | list unattached files; find orphan blobs to clean up                                                                                                 |
+| `project.import`                                                              | Import Files into the project: one entry per file, in the order given. The files are imported one after the other - memory is bounded by one file's batches, the registry sees one import - and a file that fails is its own `failed` entry, the next file still attempted: nothing of a failed file lands (but an import whose engine was lost after it landed: see `importFile`). The call itself rejects only for what is about the call: an unknown `configKey`, a project not open, a `path` (`DOCUMENT_PATH_INVALID`: a path names one file, `importFile` takes it).                                                                                                                                                           | import several XML files at once; get one result per file without a throw for a failed file                                                          |
+| `project.importFile`                                                          | Import one File into the project: the store registers, parses and stores it next to the data. The document is in the project state and broadcast once the store answers it `ready`; whatever fails before that, or an abort through `options.signal`, leaves nothing and is thrown (`PARSE_ERROR` for a malformed file, `IMPORT_ABORTED`, `IMPORT_FAILED` wrapping a foreign error). One refusal leaves its document: an import whose engine was lost after it landed is refused `STORE_ENGINE_LOST`, `meta.outcome` `applied`, its document in the state and broadcast. `options.onProgress` is told after each stored batch, never awaited. One file is in flight per project: a call made while another import runs waits for it. | import an XML file; load a file into the project; parse XML into records                                                                             |
+| `project.initEmptyDocument`                                                   | Register a new empty document in the project. Returns the new documentId. Records are added later via import or transactions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | create a new empty document; start a document from scratch without a file                                                                            |
+| `project.open`                                                                | Open a named project: resolve store, open DB connection, hydrate state. Must be called before import/export/openDocument.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | open or create a project database; start working on a project; reopen a project after close                                                          |
+| `project.openDocument`                                                        | Open a file-scoped Document for querying and mutating a specific file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | open a document to read or write it; get the Document of an id                                                                                       |
+| `project.queryAll`                                                            | Run a query function across all documents, collect and flatten results. Iterates documents sequentially; merges all non-empty arrays.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | collect results from every document; run one query over all documents                                                                                |
+| `project.queryFirst`                                                          | Run a query function across all documents, return the first non-undefined result. Iterates documents sequentially; stops at the first match.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | find the first match across every document; search all documents of a project                                                                        |
+| `project.redo`                                                                | Re-apply the last undone transaction of a document and tell other tabs. Does nothing when there is nothing to redo.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | redo an undone change to a document                                                                                                                  |
+| `project.removeBlob`                                                          | Delete a blob and its binary data from the project and tell other tabs. Does nothing when the id is unknown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | delete a stored file; remove a blob for good                                                                                                         |
+| `project.removeDocument`                                                      | Remove one document from the project - its records, history and blobs - and tell other tabs. The other documents stay.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | delete a document from the project; remove one file and its records                                                                                  |
+| `project.undo`                                                                | Revert the last committed transaction of a document and tell other tabs. Does nothing when there is nothing to undo.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | undo the last change to a document; roll back a commit                                                                                               |
+| `tx.addChild`                                                                 | Add a child element to a parent. It always creates one; `ensureChild` reuses an existing child.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | create a new element under a parent; insert a child with attributes; build new content in a transaction                                              |
+| `tx.deepClone`                                                                | Deep-clone a subtree under a new parent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | copy a subtree with fresh ids; duplicate an element under another parent; paste a tree read with getTree; map old ids to new ids                     |
+| `tx.delete`                                                                   | Delete an element and its entire subtree.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | remove an element; delete a subtree; prune a child from its parent                                                                                   |
+| `tx.ensureChild`                                                              | Get an existing child record or create it under the given parent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | get or create a child; make sure a singleton container exists before adding under it; add a child without duplicating it                             |
+| `tx.progress.endPlan`                                                         | Pop the innermost plan. Clears progress only once the stack is empty.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | close a nested progress plan; finish reporting progress for a step                                                                                   |
+| `tx.progress.nextStep`                                                        | Advance the innermost plan by one step (close-previous); optionally recaption.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | mark a progress step done; update the progress caption                                                                                               |
+| `tx.progress.plan`                                                            | Push a plan level (child of the current innermost, or the main if none).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | report progress of a long operation; announce how many steps a transaction or nested step has; show a progress bar caption                           |
+| `tx.update`                                                                   | Update attributes of an existing element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | change attribute values; set or clear an attribute; rename an element through its name attribute; set an element's text value                        |
+
+### `@dialecte/core`
+
+| Function                  | What it answers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Reach for it to                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `applyDocumentUpdates`    | A document with the updates applied, its file name and its path kept one fact: a `path` moves and renames it (its `name` follows the file name, which must end with the document's own `extension`); a `name` on a document with a path rewrites the file name in it, the folders kept; both given must agree; a field given as `undefined` is left as it was, a key beyond `DOCUMENT_UPDATE_FIELDS` ignored. Refused with `DOCUMENT_PATH_INVALID` when the result breaks a rule; the document given is left as it was. Whether the place is free is the store's to check (`assertDocumentPlace`).                            | rename or move a document by its path; apply document updates in a custom store                                                                                                                                                                                                                                                                                        |
+| `assertDocumentPlace`     | Check a document to register against the registered ones: its path valid and ending with its file name (`DOCUMENT_PATH_INVALID`), then its place free (`DOCUMENT_PATH_TAKEN`). A document without a path passes.                                                                                                                                                                                                                                                                                                                                                                                                              | check a document path is valid and free before registering it; register documents in a custom store                                                                                                                                                                                                                                                                    |
+| `bindExtensions`          | The extension map bound to an instance (a Query or a Transaction): same shape, each function called with the instance. Each function in the map gets `instance` prepended as its first argument, so the public API signature has that argument stripped.                                                                                                                                                                                                                                                                                                                                                                      | attach an extension map to a query or a transaction; call extension functions as methods of an instance                                                                                                                                                                                                                                                                |
+| `blobTableName`           | The name of the store table holding the blob data of the document `documentId`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | name the store table holding a document's blob data; store blobs in a custom store                                                                                                                                                                                                                                                                                     |
+| `createDiagnostic`        | Build a diagnostic of a catalogue: `severity`, `source` and the default `message` come from the entry, so a producer only says what the diagnostic is about. The `meta` and `related` given keep their type on the way out, so a dialecte's typed diagnostic (`Diagnostic<'x'> & { meta: {…} }`) is what this returns when it is given that `meta`.                                                                                                                                                                                                                                                                           | report an import or validation problem as a typed diagnostic; build a diagnostic from a dialecte's catalogue; attach meta to a diagnostic                                                                                                                                                                                                                              |
+| `createDialecteError`     | Build the Error `throwDialecteError` throws, without throwing it — for a caller that reports an error it caught instead of raising one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | report a caught error as a dialecte error without throwing; build the Error throwDialecteError would throw                                                                                                                                                                                                                                                             |
+| `createPerf`              | Dev metrics on the platform User Timing API. Disabled builds get `NOOP_PERF`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | measure how long operations take in development; collect timing spans and read a report of them                                                                                                                                                                                                                                                                        |
+| `createProjectFactory`    | The project factory of a dialecte: every config, the default key, the dialecte's extensions merged under the consumer's, and a fresh hooks instance per Project. It carries the declaration, `engineUrl`, the address of the dialecte's engine worker, for the store that spawns it, and `spawner`, the engine as a page registers it with the hub (`connectHub({ spawners })`). `destroyProject({ name })` deletes the dialecte's project of that name on SQLite storage without opening it (an outdated or lost one too).                                                                                                   | open projects of a dialecte from an app; get the factory that creates a dialecte's projects; delete a dialecte's project without opening it; register a dialecte's engine with the hub; use SQLite storage in an app (import `@dialecte/core/sqlite` once and open with `storage: { type: 'sqlite' }`); share one SQLite engine per project between the tabs of an app |
+| `defineDialecte`          | Declare a dialecte once: its identity, its configs, its extensions and how its hooks are made. Core derives the rest: `createProjectFactory`, `createTestRunner`, `createTestProject` and, in a worker, the engine. The declaration is frozen.                                                                                                                                                                                                                                                                                                                                                                                | declare a dialecte package; register a dialecte's configs and extensions and hooks once; set up a new dialecte                                                                                                                                                                                                                                                         |
+| `defineErrors`            | Declare the errors of a dialecte: each entry gets its property name as `key`, so it can be passed wherever a core key is — `throwDialecteError`, `invariant`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | declare a dialecte's own error catalogue; add error keys usable with invariant and throwDialecteError                                                                                                                                                                                                                                                                  |
+| `importOutcomeOf`         | What became of an import, read from the registry: the document its `writeId` is on is `running` while `importing`, `applied` once `ready`; no document carries it after a failure, an abort or a removal - `not-applied`. A store that knows which imports run says so (`isRunning`): a document `importing` whose import does not run is what a failed import left when its removal failed too - `not-applied`, removed when a store of the project next opens.                                                                                                                                                              | tell whether an import is running; applied or not applied; recover after a connection lost during an import                                                                                                                                                                                                                                                            |
+| `inspectXml`              | Inspect an XML string for the first occurrence of each requested element name. Returns a typed report keyed by the requested names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | peek at an XML file before importing it; read the root element or a version attribute without a full parse; detect which config a file needs                                                                                                                                                                                                                           |
+| `isKnownDiagnostic`       | Whether a diagnostic is one the caller knows: an entry of one of the catalogues named, matched on the pair (`source`, `code`) - two dialectes may both have an `unresolved-reference`. Its `code` is then narrowed to those catalogues' codes, so a `switch` on it or a table read with it is checked.                                                                                                                                                                                                                                                                                                                        | tell which diagnostic an import reported; narrow a diagnostic to a catalogue's codes; word a diagnostic for a user                                                                                                                                                                                                                                                     |
+| `isKnownDialecteError`    | Whether a structured error is one the caller knows: a key of the core catalogue, or an entry of one of the catalogues named — same key, same code. Its `key` is then narrowed to those keys, so a `switch` on it or a table read with it is checked again.                                                                                                                                                                                                                                                                                                                                                                    | tell which error was thrown; narrow an error key for a switch; word an error for a user                                                                                                                                                                                                                                                                                |
+| `parseDocumentPath`       | A document's path read apart into its folders and its file name. A path is relative and written one way only: segments joined by `/`, none empty, none `.` or `..`, no backslash, no invisible format, separator or control character, well-formed and in Unicode NFC, each segment at most 255 UTF-8 bytes and the whole at most 1024. Nothing is rewritten: a path breaking a rule is refused with `DOCUMENT_PATH_INVALID`, `detail` naming the rule, `meta.path` the path as given.                                                                                                                                        | validate a document path; split a document path into folders and file name                                                                                                                                                                                                                                                                                             |
+| `parseXmlDocument`        | The DOM of an XML file, in the page (a worker or Node has no `DOMParser`). Parse the compact export (`indent: false`) to get the document the stored records make, with no whitespace-only text node. A file that is not well-formed throws `PARSE_ERROR`, with what the parser said.                                                                                                                                                                                                                                                                                                                                         | get the DOM of an exported XML file; read an export as an XMLDocument in the page; query an export with XPath                                                                                                                                                                                                                                                          |
+| `pathHolderOf`            | The document whose path clashes with `path`, the document `documentId` excepted: one at that very place, or one whose path is a folder of the other's - a file system holds no file and folder of one name. Paths compare exactly; a document without a path holds no place. None when the place is free.                                                                                                                                                                                                                                                                                                                     | find which document holds a path; check whether a file or folder path is free                                                                                                                                                                                                                                                                                          |
+| `recordTableName`         | The name of the store table holding the records of the document `documentId`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | name the store table holding a document's records; read a document's records from the local database directly                                                                                                                                                                                                                                                          |
+| `removeUnfinishedImports` | Remove every document an import left `importing`: an import never outlives the store that ran it, so what a store finds `importing` when it opens is a leftover - a closed tab, a crash. A store shared by several connections names the imports still running (`isRunning`): they are kept. A row is read again before it goes, so an import that ended since the registry was listed stays.                                                                                                                                                                                                                                 | clean up the imports a closed tab or a crash left behind; clean up leftover imports when a custom store opens                                                                                                                                                                                                                                                          |
+| `runExport`               | The export of one document, next to the data - what every store's `exportFile` runs. The records are read parent by parent, `batchSize` children per call in the order they are written (never the whole document in one call), and written as they come; each written batch becomes a part of the answered `Blob`, whose head (declaration and root start tag) is put in front at the end. A write on the document while it is exported restarts it once from the start; a second one fails it with `EXPORT_CONFLICT`. The progress listener and the abort come apart from the export's data, as a worker call carries them. | implement exportFile of a custom store; export a document from a store in batches                                                                                                                                                                                                                                                                                      |
+| `runImport`               | The import of one file, next to the data - what every store's `importFile` runs. It registers the document `importing` under the caller's `writeId`, parses the file with the dialecte's import session and stores it batch by batch, applies the session's writes, marks the document `ready`. A document is whole or absent: whatever fails, or an abort, removes it and is thrown (a foreign error as `IMPORT_FAILED`, its cause kept; diagnostics that are not plain JSON as `STORE_VALUE_NOT_JSON`). The progress listener and the abort come apart from the import's data, as a worker call carries them.               | implement importFile of a custom store; import a file into a store with core's import pipeline                                                                                                                                                                                                                                                                         |
+| `summarizeOperations`     | What staged operations write, counted per record as the commit merges them (a record created then updated is one creation; created then deleted, nothing): totals, and per tag in tag order.                                                                                                                                                                                                                                                                                                                                                                                                                                  | count what a transaction will create; update and delete; summarize a prepared transaction per tag; show a confirmation summary before commit                                                                                                                                                                                                                           |
+| `throwDialecteError`      | Create a structured error and throw it. When `method` is omitted, the caller's name is extracted from the stack trace.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | throw a structured error; fail with a core or dialecte error key; raise an error a consumer can read by key                                                                                                                                                                                                                                                            |
+| `toDialecteError`         | The structured error a caught value carries — thrown by `throwDialecteError` or `invariant` — or nothing when it is any other error or value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | read the structured error from a caught value; handle a dialecte error in a catch block                                                                                                                                                                                                                                                                                |
+| `writeOutcomeOf`          | What became of a write - an import or a commit - read from the registry first, then from the history: `committed` says whether a history entry carries the id (a commit is applied whole or not at all, never running).                                                                                                                                                                                                                                                                                                                                                                                                       | tell whether an import or a commit was applied; recover after a connection lost during a write                                                                                                                                                                                                                                                                         |
+
+### `@dialecte/core/test`
+
+| Function                         | What it answers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Reach for it to                                                                                                                                                                                                                               |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `assertExpectedElementQueries`   | Asserts that each XPath query selects at least one node of the XML text, parsed once for all of them. A failure names the steps that matched, the step that failed, where the last match sits, what the failing step finds there without its predicates, and the XML around it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | assert that XML holds the elements XPath queries select; check that an export holds an element                                                                                                                                                |
+| `assertUnexpectedElementQueries` | Asserts that no XPath query selects a node of the XML text, parsed once for all of them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | assert that XML does not hold an element; check that an element was removed from an export                                                                                                                                                    |
+| `createMockRandomUUID`           | The `crypto.randomUUID` a test case's act runs with: UUID-shaped ids that follow from a seed (0 by default), the same sequence on every run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | get deterministic uuids in a test; mock crypto.randomUUID                                                                                                                                                                                     |
+| `createTestHelpers`              | Every test helper a dialecte needs, derived from its declaration: the runner, the test project, the record factory, the XPath assertions and the schema assertions. A fixture is checked against the schema of the config it is imported under, then by the dialecte's extra checks, before a case or a test project uses it.                                                                                                                                                                                                                                                                                                                                                                                                                             | get every test helper of a dialecte; set up a dialecte package's tests; check fixtures against the schema                                                                                                                                     |
+| `createTestProject`              | Spin up a Project of the declared dialecte - every config, the default key, its extensions and its own hooks instance; core's own test dialecte when none is given - with the source (and optionally the target) imported under the default config. Returns project + pre-opened documents. Opened inside a running test, the project is destroyed when the test ends (after its other `onTestFinished` hooks); opened outside one (`beforeAll`), the caller destroys it. Spin up a Project from a config, extensions and hooks given one by one, with the source (and optionally the target) imported under the key `default`.                                                                                                                           | open a project in a test with a fixture imported; get documents to test against                                                                                                                                                               |
+| `createTestRecordFactory`        | A record factory bound to a dialecte config: given a record (its tag and fields) and a `type`, it builds a raw (default), tracked or tree record of that dialecte, standardized as core stores it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | build typed test records for a dialecte; expose a record factory in a dialecte's test entry                                                                                                                                                   |
+| `createTestRunner`               | The test runner of a declared dialecte: each case runs on a fresh project with every config, the default key, the dialecte's extensions and its own hooks instance, on the store `storage` names (the local one by default). A test runner from a config, extensions and one hooks instance shared by every case.                                                                                                                                                                                                                                                                                                                                                                                                                                         | run table-driven test cases on a dialecte; test a transaction against expected XML                                                                                                                                                            |
+| `createXmlAssertions`            | The query assertions of a dialecte: XPath prefixes are its config's namespace keys, mapped to their URIs once here. Made once per dialecte (e.g. in scl's test entry) and offered beside `createTestProject`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | make XPath assertions bound to a dialecte's namespaces; assert exported XML in tests                                                                                                                                                          |
+| `createXmlSchemaAssertions`      | Structural schema assertions for tests, bound to a dialecte's generated `definition` and declared `namespaces`: `assertValidXml` (and its table form `assertValidXmlTestCases`) fails when an XML text holds an element in the wrong namespace, an element its parent may not hold, an unknown attribute or, with `requireComplete`, a missing required attribute. It is not a full XSD validation: it does not check the order of children, how many times a child occurs (min/max, a missing required child), attribute values (patterns, enumerations, datatypes) nor constraints across elements (unique keys, key references). Made once per dialecte (e.g. in scl's test entry) and offered beside `createTestProject`, like `createXmlAssertions`. | validate an exported XML file against the schema in a test; check exported XML against the XSD structure (namespaces, allowed children, known and required attributes); assert in a test that a document is structurally valid for its schema |
+| `normalizeUuids`                 | Replace every uuid value in a serialized document with a stable, first-appearance token (`uuid-1`, `uuid-2`, …). The same uuid always maps to the same token, so relationships — a `templateUuid` pointing at an element's `uuid`, a reference's target — stay visible, while the result no longer depends on the random uuid VALUES.                                                                                                                                                                                                                                                                                                                                                                                                                     | snapshot a document independently of random uuids; compare XML holding generated ids                                                                                                                                                          |
+| `useTestStorage`                 | The store the test helpers open their projects on when a call names none, for the whole process: the runner (`createTestRunner`), `createTestProject` and `createTestHelpers`. A runner's setup file calls it (`useTestStorage({ type: 'inMemory' })` for a node test project); a test file never does. A call's own `storage` (on the helper or on one call) still wins; `undefined` gives the project's own default back (the local store). In the test helpers `{ type: 'sqlite' }` is the SQLite engine run in the test's own process (its file in memory), in node as in a browser, once the setup file imports `@dialecte/core/sqlite` (as an app opts into SQLite storage).                                                                        | choose the store tests run on; run node tests on the in-memory store; run tests on SQLite                                                                                                                                                     |
+
+### `@dialecte/core/utils`
+
+| Function                        | What it answers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Reach for it to                                                                                                                                              |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `admittedXsiTypes`              | The types the record may name with xsi:type (Clark names): its declared type when named and not abstract, and its variants; where its parent leaves the declaration open, those any declaration of the tag admits. The record's own xsi:type is not read.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | list the xsi:type values an element may take; offer type choices for an element                                                                              |
+| `canonicalXsiType`              | The form core stores an xsi:type value in: the local name for a type in the dialecte's default namespace, the dialecte's prefix and the local name for a type in another namespace it declares. A value whose prefix is bound nowhere, or naming a namespace the dialecte does not declare, is kept as written. The value keeps what XML says it means: only the prefix it is written with changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | write an xsi:type value the way core stores it; compare xsi:type values written with different prefixes                                                      |
+| `childOccurrences`              | How often each child may appear under an element, read from its resolved definition (`resolveDefinition`, or `query.getDefinition`): per child in `children.sequence` order, `{ min, max }` with `max` undefined for unbounded. An absent `minOccurs` is 0 and an absent `maxOccurs` unbounded, as the generator writes them; a sequence adds what its particles allow, a choice keeps the widest of its branches (0 when a branch lacks the child), a group's own occurrences multiply what it holds. A child the content model does not name (no model, or one only a variant holds) is optional and unbounded.                                                                                                                                                                                                                                                                                                                                                     | how many times a child may appear; required or optional children of an element; cardinality of children                                                      |
+| `createSeededRandomUuid`        | A stand-in for `crypto.randomUUID` whose ids follow from a seed: the same seed gives the same sequence, every id in the layout of a version 4 UUID - so a check that reads the layout of an id passes, and two runs of the same script mint the same ids. Not for ids that must be unguessable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | make generated ids reproducible; seed crypto.randomUUID for a script or a test                                                                               |
+| `enumeratedValues`              | The values a datatype enumerates: its own enumeration, else those its union members enumerate - a member restricted by a pattern alone enumerates none. A qualified name's values are written `{uri}local`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | list the allowed values of an attribute; read the enumeration of a datatype; fill a dropdown with allowed values                                             |
+| `extractLocalName`              | Local part of an attribute name — strips a namespace prefix if present (`a:b` → `b`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | strip the prefix from an attribute name; get the local name of a qualified name                                                                              |
+| `formatEmbeddedXml`             | Reformat every XML snippet embedded in a JS/TS source string — a template literal preceded by a `/* xml *\/` marker comment — with `formatXml`, re-indented under the marker's own line with the closing backtick aligned to the statement. Leaves the rest of the source untouched. The reusable core of an `xmlfmt`-style step for test fixtures (see the `dialecte-xmlfmt` bin).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | format XML fixtures inside test files; reindent xml template literals in source code                                                                         |
+| `formatXml`                     | Format an XML string to a canonical, readable shape: one structural tag per line, indented by depth, with pure-text leaves kept inline (`<Name ...>text</Name>`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | pretty-print an XML string; format XML for a snapshot or a fixture; indent XML without changing values                                                       |
+| `getAttributeRules`             | The schema rules of one attribute of an element where it sits: whether the element and the attribute are declared, whether the attribute is required or an identity field, its `fixed` and `default` values and its namespace.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | know whether an attribute is required; read an attribute's default or fixed value; check whether an attribute is declared for an element                     |
+| `invariant`                     | Assert a condition, throwing a structured DialecteError if it fails.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | assert a condition and throw a structured error; guard against a missing record; fail with a dialecte error key                                              |
+| `isNamespaceAllowedByWildcard`  | Whether a wildcard allows a namespace (`''` = none): the namespaces it lists, or every one it does not exclude.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | check whether a wildcard admits a namespace; tell whether foreign attributes or elements are allowed                                                         |
+| `isSchemaDefaultValue`          | Whether a value equals the attribute's schema default for COMPARE: matches the `fixed` value if any, else the `default` (including an empty-string default). Compare sites drop attributes for which this is true so that an authored default-equal value and an absent attribute fold to the same thing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | compare attributes ignoring schema defaults; tell whether a value equals an attribute's default                                                              |
+| `orderAttributesBySequence`     | Put an element's attributes into canonical order: schema-sequence attributes first (in `sequence` order), then everything else sorted deterministically. Never drops attributes — reorders only — so it is safe to re-apply after an `afterStandardizedRecord` hook to normalize whatever the hook added or moved.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | put attributes in schema order; normalize attribute order after a hook                                                                                       |
+| `orderByConfigSequence`         | Order a parent's child nodes by the config-declared child sequence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | sort children in schema order; order nodes the way the export writes them                                                                                    |
+| `requiredChoices`               | The choices an element's content model requires (`resolveDefinition`, or `query.getDefinition`): each one reached through groups that are all required, with how many times it is taken (the groups' own minimum occurrences multiplied) and its branches in order - per branch, how often it holds each child (as `childOccurrences` counts them) and the choices it requires in turn. `childOccurrences` reads a child of a choice of several branches as optional; this is where a valid instance learns it must take one branch. An optional choice, or one inside an optional group, is not listed.                                                                                                                                                                                                                                                                                                                                                              | which children an element must hold where its content model offers a choice; the branches of a required choice; build a valid element from its content model |
+| `resolveDefinition`             | The definition that applies to a record - the one rule every reader of the definition follows. A tag declared one way is its tag level. A tag declared several ways takes the declaration its parent holds in the record's namespace (the only namespace held there, for a record that has none yet); a parent whose wildcard admits it, or no parent, gives the global declaration of that namespace; a parent leaving it to the particle the record matches gives the tag level, the union, lenient where the declarations differ. The parent is read at its tag level unless the caller gives its resolved definition (`parentDefinition`, a top-down walk does). Then the record's `xsi:type`, when its declaration admits the type, gives what the type lets it hold. It takes a record, whose `parent` is always known (`null` for the root); a ref carries no parent, so a caller holding one uses `query.getDefinition(ref)`, which fetches the record first. | read the definition of a record you hold without a query; know what an element may hold under its parent; walk definitions top-down                          |
+| `resolveNamespaceByPrefix`      | Resolve a namespace declared in the config by its prefix (e.g. `ext`, `dev`). Returns `undefined` for an empty prefix or an unknown one — consumers cannot extend `config.namespaces`, so an unknown prefix is a caller error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | find a declared namespace by its prefix; map a prefix to its namespace URI                                                                                   |
+| `resolveNamespaceByScope`       | Resolve a namespace _scope_ string to its full `Namespace`. A scope is normally a `config.namespaces` key (e.g. `ext`, `dev`); as a fallback it is matched against declared prefixes. Returns `undefined` when the scope is neither a known key nor a known prefix — an authoring error, since a registered namespace must be referenced by key (use a full `{ prefix, uri }` object for custom namespaces).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | find a namespace by its config key; resolve a namespace scope to its prefix and URI                                                                          |
+| `resolvePrefixByNamespaceScope` | Resolve the XML prefix to store attributes under for a namespace _scope_. The scope is normally a config namespace **key** (e.g. `ext`, `dev`), which we map to its declared prefix. If the scope is not a declared key it is treated as a raw prefix, so callers can still target custom namespaces the config is unaware of.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | find the prefix to store an attribute under; write an attribute in a declared or custom namespace                                                            |
+| `resolveSchemaAttributeValue`   | The schema value to inject for an **absent** attribute, per the requested view. Derived entirely from `getAttributeRules`, so read, compare, and export share one source of truth. Returns `undefined` when nothing should be injected. A stored value always wins and is handled by the caller before this is consulted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | know which schema value an absent attribute takes; fill an absent attribute with its schema default or fixed value                                           |
+| `resolveXsiType`                | The type a record names with xsi:type, read as core stores it (`storedNamespaceLookup`); `undefined` without xsi:type or when its prefix is bound nowhere.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | read the type an element names with xsi:type; resolve an xsi:type prefix to its namespace                                                                    |
+| `saveToDisk`                    | Save a Blob to disk using the native File System Access API when available (Chrome / Edge) and falling back to a hidden anchor download (Safari / Firefox), also when the dialog is refused because the user's gesture lapsed. The user cancelling the dialog saves nothing; any other failure is thrown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | save a Blob as a file; download an exported document; open a save dialog in the browser                                                                      |
+| `valuePatterns`                 | The patterns of a datatype's own levels, each anchored to the whole value and compiled with the `u` flag the definition writes them for: a value must match every one (one pattern of a level is enough within it).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | validate an attribute value against its datatype patterns; get the regular expressions an attribute value must match                                         |
+
+### `@dialecte/core/helpers`
+
+| Function               | What it answers                                                                                                                                                                                                                                                                                                                                                                                                            | Reach for it to                                                                                                                                       |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `evaluateExpectations` | Check what a document holds against expectations written before the script that builds it, with no DOM: each expectation counts the elements of its tag (with its attribute values, under an element of its `under` scope) through the query, so a prepared transaction's `query` is checked on what `commit()` would write. Every expectation is answered, met or failed with the count found.                            | check a built document against expected element counts; verify a script's result before committing; test what a prepared transaction would write      |
+| `isAttributeOf`        | Type predicate narrowing a string to a valid attribute name for a given record.                                                                                                                                                                                                                                                                                                                                            | check that a string is an attribute of an element; narrow an attribute name before a typed read                                                       |
+| `isChildOf`            | Type predicate narrowing a relationship to a specific tag name.                                                                                                                                                                                                                                                                                                                                                            | filter child refs by tag name; narrow a child relationship to one tag                                                                                 |
+| `isElementOf`          | Type predicate narrowing a string to a valid element tag name for a given config.                                                                                                                                                                                                                                                                                                                                          | check that a string is a tag name of the dialecte; narrow an unknown tag name before a typed query                                                    |
+| `isFullAttributeArray` | Whether attributes come as an array of attribute objects (`FullAttributeObject[]`) rather than a value object.                                                                                                                                                                                                                                                                                                             | tell an attribute array from an attribute value object; narrow attribute input                                                                        |
+| `isParentOf`           | Type predicate narrowing a parent relationship to a specific tag name.                                                                                                                                                                                                                                                                                                                                                     | check the tag of a record's parent; narrow a parent relationship to one tag                                                                           |
+| `isRawRecord`          | Whether a record is a `RawRecord`: the stored shape, without a change status or tree children.                                                                                                                                                                                                                                                                                                                             | tell a stored record from a tracked or tree record; narrow a record to its raw shape                                                                  |
+| `isRecordOf`           | Whether a record is of the tag name given, narrowing its type to that element (raw, tracked or tree record alike).                                                                                                                                                                                                                                                                                                         | narrow a record to one tag name; check an element's tag with types                                                                                    |
+| `isTrackedRecord`      | Whether a record is a `TrackedRecord`: a stored record with its change status, as queries return it.                                                                                                                                                                                                                                                                                                                       | tell a tracked record from a raw or tree record; narrow a record to its tracked shape                                                                 |
+| `isTreeRecord`         | Whether a record is a `TreeRecord`: a node of a tree read, holding its child nodes.                                                                                                                                                                                                                                                                                                                                        | tell a tree record from a raw or tracked record; narrow a record to a tree node                                                                       |
+| `mergeExtensions`      | Merges named extension modules into the flat { query, transaction } registry                                                                                                                                                                                                                                                                                                                                               | combine extension modules into one registry; add custom extensions next to a dialecte's base extensions                                               |
+| `readAttribute`        | Read one attribute of a record you hold, the way `query.getAttribute` reads it - same `namespace` scope, same `defaults` fill, same `''` for an absent attribute - with no query: synchronous, for an import pass or a pure composer. `query.getAttribute` itself delegates to it once it has the record.                                                                                                                  | look up an attribute value on a record you already hold in an import hook; look up an attribute of a held record in a pure function with no query     |
+| `readAttributes`       | Read the attributes of a record you hold, the way `query.getAttributes` reads them - each under the name it is stored by, or keyed by local name in a `namespace` scope, absent schema attributes filled per `defaults` - with no query: synchronous, for an import pass or a pure composer. `query.getAttributes` itself delegates to it once it has the record. Values are plain strings: for typed reads use the query. | look up the attribute values of a record you already hold in an import hook; look up the attributes of a held record in a pure function with no query |
+| `stripAttributes`      | Returns a new record with specified attribute names removed. Pure function — does not mutate the input.                                                                                                                                                                                                                                                                                                                    | remove attributes from a record; drop attributes before cloning a record                                                                              |
+| `toFullAttributeArray` | Converts attributes to FullAttributeObject array format and canonicalizes each attribute name to the two naming rules (see `canonicalizeAttributeName`), so records from import, create, and update share one stored name per attribute.                                                                                                                                                                                   | turn an attribute value object into an attribute array; canonicalize attribute names before a write                                                   |
+| `toRawRecord`          | A new `RawRecord` holding the seven stored fields of a raw, tracked or tree record (`id`, `tagName`, `namespace`, `attributes`, `value`, `parent`, `children`); a change status or tree children are left out. Only the record object is new: `attributes`, `parent` and `children` are the same arrays and objects as the record's, not cloned.                                                                           | strip a record to its stored fields; pass a record where a raw record is expected                                                                     |
+| `toRef`                | Convert a Ref, ParentRelationship, ChildRelationship, or Record to a Ref. ParentsOf/ChildrenOf are subsets of ElementsOf by design, so this is semantically safe.                                                                                                                                                                                                                                                          | get the ref of a record or a relationship; pass a ref to a query                                                                                      |
+| `toTrackedRecord`      | A new `TrackedRecord` of a raw, tracked or tree record: its stored fields (as `toRawRecord` takes them) and a change status - the `status` given, else the record's own, else `'unchanged'`. The field values are shared with the record, not cloned.                                                                                                                                                                      | give a raw record a change status; pass a raw or tree record where a tracked record is expected                                                       |
+| `toTreeRecord`         | A new `TreeRecord` of a raw, tracked or tree record: its stored fields and change status as `toTrackedRecord` gives them, and its child nodes - the `tree` given, else the record's own, else `[]`. The field values and the `tree` array are shared with the record, not cloned.                                                                                                                                          | turn a record into a tree node; build a tree record from a raw or tracked record                                                                      |
+| `widen`                | Widen any per-element dialecte value to its element-union form — the same value, with its element type parameter widened from a specific `GenericElement` to `ElementsOf<GenericConfig>`.                                                                                                                                                                                                                                  | pass a per-element record or ref to an API typed with the element union; fix an invariance type error on a record or ref                              |
+
+### `@dialecte/core/engine`
+
+| Function              | What it answers                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Reach for it to                                                                                                                        |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `serveDialecteEngine` | Serve the dialecte's project engine from this worker, the one call of a dialecte package's engine worker file - today the SQLite engine on the origin's private file system (opfs-sahpool). The realm that spawned it (or the hub, through it) sends control messages - open the project, adopt a client's port, a client gone, close, destroy - handled one at a time and each answered once; every adopted port is served the engine's members. One project per worker. | serve a dialecte's engine from a worker; write a dialecte package's engine worker file; ship a dialecte's SQLite engine in its package |
+
+### `@dialecte/core/sqlite`
+
+| Function       | What it answers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Reach for it to                                                                                                                                                                                                               |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `adoptHubPort` | Join the hub through a port a page made with `createHubPort` (a document that cannot reach the hub's script), and get that document's connection: a client only, whose liveness is that page's. A port nobody answers fails the join `STORE_CONNECTION_FAILED` once the welcome budget has passed. A document that connected already gets its connection - `undefined` when that one found no hub. One the hub dropped with its page (its calls refused `STORE_ENGINE_LOST`, `realm-dropped`) joins again on the new port, on its own: the page makes it one from `onRejoined`, and a join that fails leaves it dropped until the next one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | join the hub from an iframe of another origin; open projects on SQLite storage in a child frame through its page's engine; bind a child frame again after its page rejoined the hub                                           |
+| `connectHub`   | Connect this page to the origin's hub, once, and get its connection (`HubRealm`: `realmId`, `createHubPort` to bind a child frame, `onRejoined`, the moment to bind child frames again after a freeze or a drop): a second call - from this copy of the library or another one of the same protocol - gets the same connection. Answers `undefined` where the browser has no SharedWorker, or the hub never welcomed the page (its script failed to load or was blocked, or it stayed silent): a later call tries again. A hub of another protocol refuses the page: `STORE_PROTOCOL_MISMATCH`; the browser refusing to make the hub's worker (a `DOMException`) is no hub, any other error thrown making it is thrown. The page registers the engines it can start whose worker is of its own origin (each dialecte's `factory.spawner`); a later call adds those it does not run yet - a project opened on `sqlite` adds its own as it opens - and one naming a dialecte the page runs at another version is refused `STORE_HUB_SPAWNERS_FIXED`, the connection kept. A document that joined through `adoptHubPort` hosts no engine: the spawners it names are not registered; neither are those of a page that cannot store (no private file system; two versions of one dialecte refused all the same): its own projects on `sqlite` are refused `STORE_UNAVAILABLE` unless its page bound it, its connection serving to hand ports to its children. An engine's files (the SQLite wasm) are fetched when the page first starts one. | register this page's dialecte engines with the hub before any project opens; connect a page to the origin's hub; offer a dialecte's engine to the hub (`factory.spawner`); get a port to hand a child frame of another origin |
+| `listProjects` | The projects on SQLite storage of this origin - every dialecte's, or `dialecteId`'s - read from the origin's private file system alone (no engine started, no wasm loaded; a project whose engine runs is read too), sorted by dialecte and name: each one's state (`current`, `outdated`, `lost`, `new`, `unknown`), the bytes it takes and when it was last written. Where the browser gives no private file system (Node, a private window) it refuses `STORE_UNAVAILABLE`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | list the projects stored in the browser on SQLite storage; find outdated or lost projects on SQLite storage; show how much space each project takes; check whether a project exists on SQLite storage without opening it      |
+
+<!-- /dialecte-skills:generated -->