taet-ui 0.0.0-stage → 0.6.0-rc.4

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Tæt UI changes
+
+## 0.6.0-rc.4 - release candidate, 2026-11-03
+
+- Clean current branding, remove the private historical CI link and update local benchmark/demo identifiers.
+- Export taet-ui-theme v1 files as .taet-theme.json; keep importing the previous v1 format and bare definitions.
+- Prefer taet-ui.theme-editor.v1 storage, fall back to the previous key and write only the current key; opening an editor does not migrate or erase stored data.
+- Expose taetUiDocs and taetThemeEditor while retaining existing host aliases; preserve CSS selectors, CSS imports and cross-version drag MIME contracts.
+- Rename the row-drag plain-text label to Tæt UI rows without changing reorder behavior.
+- Add the real light/dark Atelier desktop showcase, a reproducible host example and documented consumer-trial limitations.
+- Published rc.3 packages, release assets and source history remain unchanged. Publication outcomes are recorded in the matching GitHub prerelease notes.
+
+## 0.6.0-rc.3 — local migration, 2026-11-03
+
+- Rename display branding to Tæt UI, package/imports/assets to taet-ui.
+- Preserve the released rc.2 framework scope and zero runtime dependencies.
+- Integrate the accepted PropertyGrid gutter-border and selection-marker CSS patch.
+- Retain legacy CSS selectors, tokens, drag/theme formats and the dense.css alias.
+- Start new history, preserving the original project folders/tags and provenance.
+- Use owned Node HTTP fixtures for browser gates; retain all assertions.
+- Add classic TaetUI IIFE delivery alongside ESM, with minified variants and portable ZIP examples/checksums.
+- Prepare public npm metadata and the next preview channel; publication outcomes are verified separately. See docs/TAET_MIGRATION.md.
+
+The following pre-rename changelog is historical and keeps exact released versions.
+
+# Changelog
+
+## 0.6.0-rc.2 - preview (2026-11-02)
+
+- TreeGrid compares pairs of valid Date values by timestamp. Equal timestamps remain stable within siblings; null placement, locale, and the legacy invalid/mixed-value fallback are unchanged. See `docs/GRID_TYPES.md`.
+- Grid and TreeGrid settings buttons use a deterministic decorative SVG in the existing 10px service gutter. Row markers, drag gestures, menu scope, and keyboard focus remain unchanged.
+- Added checked integration recipes for DTO dialog results, guarded asynchronous work and retry, master/detail context, ownership, application UI snapshots, and resize persistence. No new public runtime API or default policy is introduced.
+- Fixed Switch cell-editor activation on WebKit so the native label default cannot override deliberate application focus. One toggle and callback-safe teardown are preserved. Forwarded private DOM clicks are synthetic (`isTrusted: false`); the original visual-label event is prevented. See `docs/GRID_EDITOR_MATRIX.md`.
+- Browser fixtures await actual Date DOM paint, Mapper port geometry and editor focus before assertions or keyboard injection. Strict behavior assertions and global timeouts are unchanged.
+- Windows CI uses two workers after a recorded `ERR_NO_BUFFER_SPACE` module-load failure. This is a conservative mitigation, not a proven explanation of the historical retained-renderer failure.
+- The feedback base passed full Windows/Linux Node22/24 CI, three-engine compatibility and bundle gates. Its Windows Tauri/WebView2 stand passed 46/46 programmatic checks in each of two launches; the maintainer subsequently reported the manual interactive check passed. Exact inputs and limits are in `docs/VERIFICATION.md` and `docs/NATIVE_ACCEPTANCE.md`. The rc.1 tag and historical failed runs remain unchanged.
+
+## 0.6.0-rc.1 - preview
+
+### Working checkpoint - 2026-11-01
+
+User hands-on acceptance confirmed Grid editing/editor fonts, the 10px gutter
+and per-selected-row markers, multi-select, pinning/column reorder, cross-Grid
+move/copy and local TreeGrid node-with-subtree moves. This local checkpoint
+preserves the tested desktop baseline, not a publication or universal readiness
+claim. Tree copy/cross-tree/remote/custom providers remain outside this scope;
+a separate Windows Tauri/WebView2 stand later passed bounded programmatic checks
+and user-observed row/subtree moves. Full physical input/IME and remote CI remain
+unverified. Exact scope: docs/VERIFICATION.md and docs/NATIVE_ACCEPTANCE.md.
+
+
+Grid column QA: measured multi-pin header/editor geometry, live backward-move
+focus, stale/reentrant drag protection and delta Tree expanded-state restore.
+The optional workbench column mode and editor matrix demonstrate row multi-select
+with per-row markers; Check/Radio now have passive read visuals.
+
+Managed overlays now use the common bundled-font tokens. The editor matrix shows
+Switch state using the existing static indicator and explicit transactional edit
+activation, with passive read visuals and no per-row Controls.
+
+Grid editor matrix: nine existing factories on Grid/TreeGrid, typed nullable
+Select values, common closed-Select/popup keyboard policy, compact Select/Radio
+geometry, popup resize/focus and callback-safe teardown; live recipe11/example.
+Disabling a table now silently cancels its draft and releases the owned popup.
+
+Grid/TreeGrid indicator gutter now defaults to 10px instead of 20px; explicit
+CSS widths and gutter/menu opt-outs remain supported.
+
+- Foundation/components/advanced aliases over existing constructors; maturity unchanged.
+- Specialized raster/Painter/StockChart/FlatFile/Spectrum/Pivot delivery deferred.
+  Reader must retain its complete pinned 0.5 bundle.
+- Form removes logical slots/values/subscriptions; composition owns children before mount.
+- Stop late callback phases after teardown; ignore focus events during destruction.
+- Reject terminal admission, duplicate/prototype keys and ownership cycles atomically.
+- ShortcutManager respects defaultPrevented/IME, explicit editor opt-in, semantic keys
+  and exact Meta priority over portable Ctrl/Cmd fallback.
+- Grid/TreeGrid share silent selection invalidation, safe selection reentry, keyboard
+  editing, beforeEditStart/commit metadata and schema reconciliation. Legacy APIs remain.
+- Read-only tables no longer import the built-in editor catalog just to check a factory.
+- Desktop tree/table/property workbench demonstrates shared data and edit context.
+- Imported source hashes remain immutable; approved table changes have a separate candidate manifest.
+- Runnable mutation example, exact docs routes, coherent assets and honest provenance.
+
+Compatibility: duplicate pending Form slots now fail early; shortcuts in text
+editors require opt-in. Specialized exports are intentionally absent, not emulated.
+
+Table compatibility: legacy getSortState return types and Tree string/function
+filters remain. getSortModel returns Rule[] on both. clearAllFilters({search})
+explicitly chooses scope; omission retains each legacy default. Tab/Shift+Tab
+now exit at editable boundaries rather than wrapping; invalid drafts retain focus.
+
+- Shared presentation gutter (now 10px by default) carries the selected-row accent and table menu.
+  Columns/Best fit all/global clears moved out of local column menus; reset is
+  explicitly column layout only. Shared indicatorGutter/gridMenu constructor
+  opt-outs preserve compact embedded layouts; data/ARIA/range/export indices stay.
+- At a document edge with no external tabbable, Tab commits and releases table
+  focus to the document body consistently in Chromium/Firefox/WebKit.

package/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+Start with README, AGENTS.md, docs/AI_CONTEXT.md and the relevant docs/AI_MAP.md row.
+Read exact declarations and a checked recipe before changing a public contract.
+Runtime stays dependency-free. Preserve ownership/lifecycle, tier and maturity rules.
+
+Table changes require explicit approval and review before regenerating the separate
+candidate hashes. The immutable imported snapshot must retain its original bytes.
+Run shared/table regressions when changing shared mechanics.
+
+Use npm ci and npm test; then test:all, relevant compatibility/bundle gates and pack
+inspection. Browser binaries are separate development prerequisites. Regenerate
+API inventories after export changes. Keep exact results/limits in docs/VERIFICATION.md.
+Do not commit generated dist/node_modules/reports/caches, binaries or private data.
+Publication is a separate maintainer action. See docs/VERSIONING.md and SECURITY.md.

package/LICENSE

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

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# Tæt UI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Compact desktop UI controls for embedded WebViews. Build screens with live
+JavaScript objects, explicit ownership, events, commands and data models.
+No JSX, virtual DOM, runtime npm dependencies or CDN.
+
+**0.6.0-rc.4 is a pre-1.0 release candidate; published rc.3 artifacts remain unchanged.** Grid/TreeGrid and Advanced remain experimental.
+Source packages and standalone WebView ZIPs are separate delivery choices.
+The npm preview channel uses `next`: `npm install taet-ui@next`; publication
+status is recorded in the matching GitHub prerelease notes.
+
+Display name: **Tæt UI**. Package and technical names: **taet-ui**.
+Repository: [edward-ap/taet-ui](https://github.com/edward-ap/taet-ui).
+See the [migration inventory](docs/TAET_MIGRATION.md) and [verification](docs/VERIFICATION.md).
+
+## Standalone WebView distribution
+
+`npm run distribution` builds/minifies the library and produces versioned ZIPs in
+ignored `distribution/`. Release builds use `npm run distribution -- --release`
+from a clean commit. GitHub prerelease assets include one ZIP for each profile:
+full, components and foundation. Each contains matching CSS/fonts/licenses,
+readable/minified ESM and classic IIFE JavaScript, examples, provenance and SHA-256.
+Use one profile and one JS format in each document. Classic scripts expose `TaetUI`;
+ESM files export named bindings. Both target ES2022 without API polyfills.
+
+Each ZIP has a working `index.html` (classic IIFE) and `example-esm.html`. Serve
+through a WebView origin or HTTP; local-file access depends on host policy.
+Node/Python/npm are build/preview tools, not packaged-application dependencies.
+Generated ZIPs and `dist/` stay out of Git. The npm package delivers typed ESM
+source and CSS/font assets for resolver/bundler consumers.
+
+```js
+// Browser application with a resolver/bundler and its CSS loader:
+import {Panel, Form, TextInput, Button} from 'taet-ui';
+import 'taet-ui/taet-ui.css';
+```
+
+
+## Try it
+
+Build prerequisites: Node 22+, npm and Python 3.10+ on PATH. They are development
+tools; a packaged application does not need a Node/Python server. Your host
+must provide a compatible system WebView runtime.
+
+```sh
+npm ci
+npm run build
+npm run dev
+```
+
+Open http://127.0.0.1:5173/examples/basic-form/index.html.
+With that server running, also open the [workbench](http://127.0.0.1:5173/examples/grid-workbench/),
+[editor matrix](http://127.0.0.1:5173/examples/grid-editors/), [Grid transfer](http://127.0.0.1:5173/examples/grid-transfer/)
+and [tree movement](http://127.0.0.1:5173/examples/tree-move/).
+
+Documentation: http://127.0.0.1:5173/docs/index.html, or run `npm run docs`
+for http://127.0.0.1:5174/docs/index.html.
+If a port is occupied, use `npm run dev -- --port 5641` and the corresponding URL.
+In Windows PowerShell, use `npm.cmd run dev -- --port 5641` if the npm.ps1 shim
+consumes forwarded options. Check `node --version`, `npm --version` and
+`python --version` before starting.
+
+## Desktop showcase
+
+[Atelier](https://github.com/edward-ap/taet-ui/tree/main/examples/desktop-showcase) is a runnable dummy IDE made from
+TreeList, DockLayout/DockPanel, MdiWorkspace, PropertyGrid, TabBar, Menu, Toolbar,
+Form and Dialog. Project data and build/run actions are synthetic. These are real
+controls in the same live application, captured in the built-in light/dark themes
+from the rc.4 candidate.
+
+![Light theme: project tree, overlapping MDI documents with Code and Design tabs, live form preview, property inspector and build output](https://raw.githubusercontent.com/edward-ap/taet-ui/main/.github/screenshots/desktop-ide-light.png)
+
+*Light theme — the project tree selects the object inspected beside the MDI workspace.*
+
+![Dark theme of the same application with the same selected object, documents, properties and build output](https://raw.githubusercontent.com/edward-ap/taet-ui/main/.github/screenshots/desktop-ide-dark.png)
+
+*Dark theme — switched on the same instance without losing edits or window state.*
+
+<img src="https://raw.githubusercontent.com/edward-ap/taet-ui/main/.github/screenshots/desktop-ide-dialog.png" width="320" alt="Actual modal Run configuration dialog with program arguments, Cancel and Run preview actions">
+
+*The run configuration uses a real modal Dialog and Form; fixed side placement is host CSS.*
+
+UI composition uses live objects and explicit ownership. For example, the workspace
+frame is ordinary JavaScript; the complete [example](https://github.com/edward-ap/taet-ui/tree/main/examples/desktop-showcase)
+also wires selection, descriptor setters, commands, tabs and cleanup:
+
+```js
+import {DataStore} from 'taet-ui';
+import {TreeList} from 'taet-ui/components';
+import {DockLayout, DockPanel, MdiWorkspace} from 'taet-ui/advanced';
+
+const records = new DataStore();
+records.parse([{id: 'project', parentId: null, text: 'Demo project'}]);
+const dock = new DockLayout('#desktop', {leftSize: 216, rightSize: 268});
+const explorer = dock.addPanel(new DockPanel({id: 'explorer', title: 'Project', area: 'left'}));
+explorer.add(new TreeList({data: records, textField: 'text'}));
+const center = dock.addPanel(new DockPanel({id: 'editor', title: 'Workspace', area: 'center'}));
+center.add(new MdiWorkspace({width: '100%', height: '100%'}));
+const destroy = () => { dock.destroy(); records.destroy(); };
+```
+
+The host supplies data, actions and layout CSS. A WebView can serve the full ESM
+profile with matching local CSS/fonts through its own origin; Node/npm are build
+tools. The example explains the import map and teardown. Desktop APIs retain their
+[experimental maturity](docs/STABLE_API.md); the consumer trial and its API friction
+are described in the [example notes](https://github.com/edward-ap/taet-ui/tree/main/examples/desktop-showcase).
+
+## Use it in a WebView
+
+Copy one built profile's JS, matching CSS, `fonts/`, `LICENSE` and
+`THIRD_PARTY_NOTICES.md` into your app. Full is `dist/`; subsets are
+`dist/components/` and `dist/foundation/`. Use one library instance per document.
+Serve modules from a WebView origin/custom protocol or HTTP. Do not assume that
+opening ES modules directly through `file://` works in every host.
+
+```html
+<link rel="stylesheet" href="./taet-ui.min.css">
+<body class="dui-page dui-theme-light-blue">
+  <main id="app"></main>
+  <script type="module" src="./app.js"></script>
+</body>
+```
+
+```js
+import {Panel, Form, TextInput, Button} from './taet-ui.min.js';
+const name = new TextInput({name: 'name', label: 'Customer', value: 'Ada'});
+const form = new Form().row(name);
+form.row(new Button({text: 'Save', onClick() { console.log(form.value.get()); }}));
+const screen = new Panel('#app').add(form);
+export function destroy() { screen.destroy(); } // Host calls this when closing.
+```
+
+A source-only [minimal Tauri host](examples/tauri-minimal/README.md) demonstrates
+a compact Form and bounded Rust echo. Its historical pre-rename Windows smoke passed
+7/7 programmatic checks. A renamed Tæt UI native rebuild, physical input and other OSes remain unverified.
+
+For TypeScript or resolver-based apps, `npm pack --pack-destination ..` creates
+the local `taet-ui-0.6.0-rc.4.tgz`. Install that file in your app with
+`npm install ../taet-ui-0.6.0-rc.4.tgz`. Bare package names need a resolver or
+browser import map; installing a tarball does not create native browser URLs.
+
+| Import | Scope |
+| --- | --- |
+| `taet-ui/foundation` | Lifecycle, events, commands, models, validators, icons and themes |
+| `taet-ui/components` | Layouts, forms, inputs, lists, tables, properties and indicators |
+| `taet-ui/advanced` | MDI, docking, generic charts, mapping and theme editor |
+| `taet-ui` | Stable root; legacy subpaths remain for retained APIs |
+| `taet-ui/taet-ui.css` | Styles and local font |
+
+[Architecture tiers](docs/TIERS.md) and [API maturity](docs/STABLE_API.md) are
+separate. A tier name does not promote an experimental API. For changing a live
+screen, read [mutation/ownership examples](docs/MUTATIONS.md).
+
+## Preview limits
+
+Current migration checks are recorded in [verification](docs/VERIFICATION.md).
+Earlier pre-rename results identify their original inputs and are historical evidence.
+
+Recorded checks include Windows browser automation and a separate Windows
+Tauri/WebView2 acceptance stand. Programmatic/synthetic input is distinguished
+from physical input in [verification](docs/VERIFICATION.md).
+macOS and Linux native hosts are **not verified**. macOS will be checked in a new
+consumer project after GitHub publication; it is not a blocker for this preview.
+Real IME, screen-reader, native file-dialog and mixed-DPI acceptance remain unverified.
+
+Grid row transfer is local and opt-in. Tree subtree movement is inside one local
+tree; cross-tree copy/move and remote/custom providers are outside that contract.
+Raster/Painter/StockChart/FlatFile/Spectrum/Pivot are [deferred extensions](docs/EXTENSIONS.md).
+
+For contributors: [setup/checks](CONTRIBUTING.md), [AI entry point](docs/AI_CONTEXT.md),
+[preview version recommendations](docs/VERSIONING.md), [changelog](CHANGELOG.md), [security](SECURITY.md).
+Browser tests additionally require matching Playwright binaries; `npm ci` alone
+does not install them. After npm ci, use `npx playwright install chromium firefox webkit`.
+For selective Windows project flags, use the direct-node commands in
+[release checks](docs/RELEASE.md). Exact remote CI and publication outcomes are
+linked from the matching GitHub prerelease notes.
+
+Tæt UI is [MIT](LICENSE). Local Noto Sans is OFL; retain its license and
+[third-party notices](THIRD_PARTY_NOTICES.md) when distributing assets.

package/SECURITY.md

@@ -0,0 +1,37 @@
+# Security
+
+This pre-1.0 project does not currently offer a supported-version security policy. The development HTTP server is for trusted local development, not production hosting.
+
+After GitHub publication, use the repository's private vulnerability reporting channel when enabled. Do not post credentials, personal data or exploit details in public issues. The publication checklist requires enabling that channel before advertising it as available.
+
+Reports should identify the affected revision, component, reproducible trigger and impact. Use synthetic or anonymized datasets.
+
+## Data and application-code boundaries
+
+Built-in TextLayout, CodeBlock, list captions and default Grid cells display text
+as text, not HTML. Imported JSON definitions are data; field identifiers including
+`__proto__` remain own data properties. Regression cases cover these boundaries.
+Custom renderers returning DOM Nodes, factories, validators, icon registrations
+and service callbacks are trusted application code: Tæt UI does not sandbox them.
+Do not construct such callbacks from imported strings or untrusted code.
+
+Select/TreeGrid image URLs are assigned to image elements. They can cause network
+requests; applications must decide which origins and image sources are acceptable.
+Text escaping does not provide network isolation. Deploy an appropriate host origin,
+navigation and content policy; the local development server is not that policy.
+
+## Files and exported data
+
+Specialized file parsers and preview pipelines are deferred extensions and are not included in this candidate.
+
+CSV/TSV exporters preserve raw values by default. For spreadsheet-oriented output,
+use `gridExporters.csv({ escapeFormulas: true })` (also available for TSV and the
+generic delimited exporter). It prefixes formula-like string values and headers
+with an apostrophe, including leading whitespace/control-character cases, while
+preserving numeric values. This changes exported text and is deliberately opt-in.
+It is not a guarantee for every spreadsheet application or subsequent re-export;
+review the receiving application's import policy. Workbook descriptors retain raw
+values and require the downstream writer to choose cell types safely.
+
+The current hardening review is a scoped internal audit, not a security certification
+or an exhaustive review of every renderer, host integration and input format.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,45 @@
+# Third-party notices
+
+Tæt UI source is licensed under [MIT](LICENSE). Core has no npm runtime dependencies. No external icon font or icon package is bundled; icons are implemented in the source registry.
+
+Development tests use [Playwright](https://github.com/microsoft/playwright), licensed under Apache-2.0. Installed packages and downloaded browser distributions retain their own notices and are not included in the Tæt UI package.
+
+Declaration and package-consumer tests use [TypeScript](https://github.com/microsoft/TypeScript), licensed under Apache-2.0. It is a development dependency and is not shipped in the Tæt UI package or required at runtime.
+
+New third-party source, artwork or fonts must include attribution and license. This inventory describes the checked-in tree and manifests, not undisclosed historical provenance.
+
+## Default UI font
+
+`src/ui/fonts/NotoSans-variable.woff2` is a container-only conversion of the Google
+Fonts Noto Sans upright variable font, bundled locally under SIL OFL 1.1. All
+glyphs, metrics, hinting and variation tables are preserved; no subsetting is used.
+Copyright and full license: `src/ui/fonts/NotoSans-OFL.txt` in source/package
+delivery, or `fonts/NotoSans-OFL.txt` beside a portable bundle.
+Source/conversion provenance is in the repository file `src/ui/fonts/README.md`.
+Runtime WOFF2 SHA-256: `7ed77c38412a34312e975abcd5eb2b2848a596f1921393f925a53a27938eb116`.
+The font license is separate from Tæt UI's MIT license.
+
+## Optional font comparison Lab
+
+`examples/labs/fonts/NotoSans-variable.ttf` and `Roboto-variable.ttf` are original
+Google Fonts distributions under SIL OFL 1.1. Their respective copyright and license
+files are `NotoSans-OFL.txt` and `Roboto-OFL.txt` in the same directory; exact sources
+and file hashes are recorded in `sources.json`. The Lab copies are not packaged; the Noto Sans runtime copy is described above.
+Roboto is only used in the comparison. Segoe UI is accessed
+from the host OS only and is not redistributed.
+
+## Theme Designer color math
+
+The Theme Designer OKLab conversion uses the public-domain matrix implementation
+by Björn Ottosson (2021 revision), with local JavaScript sRGB transfer functions
+and chroma gamut search. Source and permission: https://bottosson.github.io/posts/oklab/ .
+No color library or new runtime dependency is included.
+
+## Build tool
+
+Portable bundles use esbuild (MIT) as a development/build dependency. Its code is
+not a required runtime library in the Tæt UI delivery. Source: https://github.com/evanw/esbuild .
+
+An optional Tauri source example has separate Rust host dependencies. Those are
+not Tæt UI JavaScript runtime dependencies; source users retain their upstream
+licenses. A distributed native binary needs its own resolved dependency notice review.

package/docs/AI_CONTEXT.md

@@ -0,0 +1,23 @@
+# Tæt UI: start here
+
+0.6.0-rc.4 is a dependency-free desktop/WebView preview.
+
+1. Read [LLM_GUIDE](LLM_GUIDE.md), then one [AI_MAP](AI_MAP.md) row.
+2. Read its exact public .d.ts and one recipe before guessing a method.
+3. [TIERS](TIERS.md) is architecture; [STABLE_API](STABLE_API.md) is maturity.
+4. To change existing UI read [MUTATIONS](MUTATIONS.md).
+
+Use live controls. Form owns composed rows/columns before mount; general Panel
+must be mounted before add/attach. One child has one owner. Form.remove and owned
+child.destroy forget fields/values/slots. Duplicate keys fail before ownership/mount.
+Fields use .value; collections mutate through DataStore. Silent still synchronizes
+UI/models without semantic events. Options are not reactive property assignments.
+Destroy the owner; release borrowed application services separately. Register
+external cleanup as () => service.destroy(), not the Control object itself.
+
+Portable apps use one JS profile with matching CSS/fonts/licenses. Never mix
+source, bundles or separately built profiles in one document. Grid changes require explicit approval and candidate hash updates;
+run regressions after table/shared changes. [Common table contract](GRID_COMMON_CONTRACT.md). Specialized extensions are absent:
+[EXTENSIONS](EXTENSIONS.md). HostBridge/general JSON engine are not supplied.
+Concrete existing JSON factories remain with components. Reports/proposals are not
+shipped implementations. Current work: [ROADMAP](../ROADMAP.md), [checks](VERIFICATION.md).

package/docs/AI_MAP.md

@@ -0,0 +1,19 @@
+# Task, contract and source map
+
+Read one row, exact types and one recipe before changing behavior.
+
+| Task | Contract / types | Source / regression |
+| --- | --- | --- |
+| Lifecycle / focus | [control contract](CONTROL_TYPES.md), [BaseControl](../src/core/BaseControl.d.ts) | [BaseControl source](../src/core/BaseControl.js), [regressions](../test/foundation-regressions.test.js) |
+| Form / ownership / live edits | [containers](../src/ui/container-contracts.d.ts), [mutations](MUTATIONS.md) | [Panel](../src/ui/Panel.js), [Form](../src/ui/Form.js), [browser](../browser-tests/foundation-regressions.spec.js), [recipe](../examples/ai-recipes/01-basic-form.js) |
+| Events / values / validation | [inputs](INPUT_TYPES.md), [EditorControl types](../src/ui/EditorControl.d.ts) | [EventBus](../src/core/EventBus.js), [EditorControl](../src/ui/EditorControl.js), [recipe](../examples/ai-recipes/02-validation-form.js) |
+| Data / projections / selection | [model contracts](DATA_MODEL_TYPES.md), [core types](../src/core/index.d.ts) | [DataStore](../src/core/DataStore.js), [DataView](../src/core/DataView.js), [TreeDataView](../src/core/TreeDataView.js) |
+| Commands / shortcuts | [command types](../src/core/CommandRegistry.d.ts), [keyboard](../spec/15-shortcut-manager.md) | [ShortcutManager](../src/core/ShortcutManager.js), [recipe](../examples/ai-recipes/04-toolbar-commands.js) |
+| Theme service / editor | [applicator](../src/ui/ThemeApplicator.d.ts), [designer](../src/ui/ThemeDesigner.d.ts) | [applicator source](../src/ui/ThemeApplicator.js), [browser](../browser-tests/theme-applicator.spec.js) |
+| Existing JSON factories | [Form](FORM_JSON.md), [Grid](GRID_JSON.md), [collections](COLLECTION_JSON.md) | FormDefinition/GridDefinition/TreeDefinition and their existing regressions |
+| Grid / TreeGrid | [guide](GRID_TYPES.md), [menu/gutter](GRID_MENUS.md), [layout/selection](GRID_COLUMN_LAYOUT.md), [row transfer](GRID_TRANSFER.md), [subtree move](TREE_GRID_MOVE.md), [editors](GRID_EDITOR_MATRIX.md), [exact entry](../src/ui/grid-api.d.ts) | [Grid](../src/ui/Grid.js), [TreeGrid](../src/ui/TreeGrid.js), [candidate-hash guard](../scripts/check-package-boundaries.js), [recipe](../examples/ai-recipes/05-grid-readonly.js) |
+| Lists / properties / inputs | [collections](../src/ui/collection-contracts.d.ts), [inputs](../src/ui/inputs.d.ts) | [PropertyGrid](../src/ui/PropertyGrid.js), [List](../src/ui/List.js), [recipe](../examples/ai-recipes/06-property-grid.js) |
+| Existing Advanced | [entry](../src/advanced/index.d.ts), [Chart](CHARTS.md) | MDI/docking/mapping, Chart/Gauge, ThemeDesigner; no new advanced features here |
+
+Current [tiers](TIERS.md), [maturity](STABLE_API.md), [build](BUILD.md),
+[release gates](RELEASE.md), [verification](VERIFICATION.md), [extensions](EXTENSIONS.md).

package/docs/AI_REFERENCE.md

@@ -0,0 +1,7 @@
+# Focused lookup
+
+Use [AI_MAP](AI_MAP.md) for exact declarations, not duplicated signatures.
+[Mutations](MUTATIONS.md), [inputs](INPUT_TYPES.md), [models](DATA_MODEL_TYPES.md),
+[Grid](GRID_TYPES.md), [editors](GRID_EDITOR_TYPES.md), [tiers](TIERS.md),
+[maturity](STABLE_API.md), [delivery](BUILD.md), [native limits](NATIVE_ACCEPTANCE.md)
+and [extensions](EXTENSIONS.md) are current. History is retained in the archive.

package/docs/BUILD.md

@@ -0,0 +1,42 @@
+# Portable delivery
+
+From a source checkout run npm ci and npm run build. Exact-pinned esbuild is
+build-only. Runtime does not require Node/Python or a server.
+
+Dist contains readable/minified ESM/CSS/maps, fonts/NotoSans-variable.woff2 + OFL,
+LICENSE/notices/README, size-report and full/components/foundation metafiles.
+The full profile is dist/; alternatives are dist/components/ and dist/foundation/.
+Full contains retained stable/experimental APIs plus Advanced. Components contains
+foundation+ordinary controls; Foundation has no component constructors.
+
+Use one profile per document with matching CSS/fonts/notices. Profiles are separate
+library instances. Complete shared CSS/fonts are retained deliberately; no unsafe
+style purging. Specialized workers/reader profile are not shipped.
+
+ES2022 is a syntax target, not API polyfills. Use HTTP/WebView origin, not file://
+as a portability assumption. Maps embed sources and can be omitted from production.
+Bundles do not flatten declarations; typed users use package entries.
+
+size-report includes hashes, compression estimates, modules and source provenance.
+Git state may be not-versioned/uncommitted/dirty/clean; no clean commit is invented.
+Content SHA-256, immutable imported snapshot hash and approved Grid candidate
+manifest hash identify pre-commit builds.
+Run check-bundle.js and test:bundle. Native limits: [NATIVE_ACCEPTANCE](NATIVE_ACCEPTANCE.md).
+
+## Standalone release archives
+
+Each profile now has readable/minified ESM (`taet-ui[.min].js`) and classic IIFE
+(`taet-ui.global[.min].js`, global `TaetUI`) plus matching CSS and source maps.
+These are alternative instances: use one profile/format in a document.
+`npm run distribution` builds and packages full/components/foundation ZIPs in
+ignored distribution/. `npm run distribution -- --release` requires a clean
+commit and matching current build provenance. Archives include a working classic
+and ESM example, fonts/OFL, MIT/notices, PROVENANCE.json and SHA256SUMS.txt.
+Source maps embed public framework code. Keep them for debugging or omit them
+from a deployed host; JS/CSS/fonts/licenses must remain together.
+
+The automated browser harness uses scripts/test-server.js (Node built-in HTTP).
+It serves exact Buffer bytes/Content-Length and only binds loopback. The runner
+checks its own child PID in readiness responses and reports fixture stderr.
+The existing Python dev/docs server remains available. No app runtime server is
+required by either portable format. Source npm exports remain typed ESM.

package/docs/CHARTS.md

@@ -0,0 +1,129 @@
+# Charts (experimental)
+
+`Chart` and `Gauge` are exported by `taet-ui/experimental`, `taet-ui/all` and the
+full portable bundle. They are original Tæt UI implementations, with no runtime
+dependencies. DHTMLX's locally supplied public declarations were inspected for
+feature vocabulary; no proprietary renderer or source was incorporated.
+
+```js
+import { Chart, Gauge } from './taet-ui.min.js';
+const chart = new Chart('#plot', {
+  label: 'Monthly orders', type: 'spline', markers: true, height: 320,
+  categoryField: 'month',
+  series: [{ id: 'orders', valueField: 'count', label: 'Orders' }]
+});
+chart.data.parse([{ id: 1, month: 'January', count: 42 },
+                 { id: 2, month: 'February', count: 58 }]);
+chart.events.on('itemClick', ({ item, seriesId, value }) => {
+  // Host-owned action, e.g. navigate to the selected month.
+});
+const gauge = new Gauge('#capacity', { label: 'Capacity', min: 0, max: 200,
+  value: 136, textMode: 'value', width: 280 });
+gauge.value.set(150);
+// On teardown: chart.destroy(); gauge.destroy();
+```
+
+Link the matching bundle CSS once. The docs workbench itself uses source modules.
+
+## Models and presentation
+
+| Requested presentation | API |
+| --- | --- |
+| Basic / BasicMarkers | `type: 'line'`, `markers: false / true` |
+| Spline / SplineMarkers | `type: 'spline'`, `markers: false / true` |
+| Column | `type: 'column'` (grouped vertical columns) |
+| StackedColumn | `type: 'stackedColumn'` |
+| StackedColumn 100% | `type: 'stackedColumn100'` |
+| Bar | `type: 'bar'` (grouped horizontal bars) |
+| Gauge | Separate `Gauge`, sharing ProgressBar's value/range contract |
+
+Each record is a category, in store order; series read numeric fields from it.
+Only finite **numbers** are measurements: missing/non-numeric values create gaps,
+not zeros. Spline uses monotone cubic Hermite interpolation and splits at gaps.
+An isolated point needs markers to be visible without hover/focus. The X axis is
+categorical even when its label looks like a timestamp; intervals are equally spaced.
+
+Columns and bars always include zero; Line/Spline/Area can use `includeZero:false`.
+Positive/negative stack accumulators are separate.
+100% stacks normalize positive and negative totals independently to +100/-100;
+zero totals stay zero. Hidden series do not contribute. Tooltips/events retain
+raw values. If a raw stack sum overflows the finite numeric range, the chart
+shows an error message instead of emitting invalid SVG geometry.
+
+`data` is an owned DataStore unless a store is supplied. Normal parse/update/clear/
+batch operations invalidate the display, including `silent` writes. A borrowed
+store survives chart destruction. `getSeries()` returns detached descriptors;
+use `setSeries`, `setType`, `setMarkers` and `setSeriesVisible` to change configuration.
+IDs and valueField strings are required for each series; IDs must be unique.
+
+`seriesVisibilityChange` reports `seriesId`, `visible`, `origin`, `userAction`;
+`silent` suppresses this event but still repaints. `itemClick` reports `item`, typed
+`id`, `seriesId`, raw `value` and `category`, with user mutation metadata.
+
+## Rendering, theme and interaction
+
+- SVG paths, bars and markers; native SVG title tooltips. Labels are plain text.
+- Automatic container resize handling. Default height is 320px; minimum plotted
+  viewBox is 240x140. Very small containers scale that viewBox down.
+- One pending animation-frame callback coalesces invalidations. No idle frame loop,
+  animation, polling, document-level pointer handler or network request.
+- SVG is O(records × visible series); this is not a virtualized or decimated renderer.
+  V1 targets small/medium datasets. Thousands of SVG points require host measurement.
+- Theme tokens control background, text, gridlines and the first accent series.
+  Series 2–6 have distinct fallback colors; override `--dui-chart-series-1` … `-6`
+  on the chart or use a series `color`. Colors repeat after six series. No claim of
+  automatic palette contrast or colorblind-safe differentiation.
+- Legend entries are keyboard buttons. One Tab stop enters plotted values; arrows
+  and Home/End navigate, Enter/Space activates. Each point has an accessible label.
+  Disabled charts ignore point activation and disable the legend.
+- Gauge is a read-only meter (not progress completion and not CircularSlider).
+  Range clamping, clean/reset, silent updates and formatting follow ProgressBar.
+  Theme controls its track/needle/arc; `--dui-gauge-color` overrides the arc.
+
+## Deliberate v1 limits and verification entry points
+
+No mixed-type charts, pie/radar, numeric/time X scales, fixed axis bounds,
+zoom/pan, decimation, remote paging, HTML formatter injection or image export.
+Native tooltip timing and real screen-reader speech are not browser-test guarantees.
+
+See `test/chart.test.js` (math/model), `browser-tests/charts.spec.js` (rendering,
+interaction/lifetime), `test/types/chart-consumer.ts` (installed declarations),
+`npm run test:charts` (Chromium/Firefox/WebKit). Live examples: Components → Charts
+and `/examples/labs/charts.html`. Public declarations: Chart.d.ts and Gauge.d.ts.
+
+## Financial and area charts
+
+`type:'candlestick'` draws Japanese candles, including doji (open equals close).
+`wickCaps:true` adds horizontal caps at high/low; `setWickCaps` toggles them.
+`type:'ohlc'` draws the low/high stem, open tick left and close tick right.
+
+```js
+const prices = new Chart('#prices', {
+  type: 'candlestick', wickCaps: true,
+  series: [{ id: 'price', label: 'Price',
+    ohlc: { open: 'o', high: 'h', low: 'l', close: 'c' } }]
+});
+prices.data.parse([{ id: 1, label: 'Monday', o: 102, h: 108, l: 100, c: 106 }]);
+```
+
+`series.ohlc` maps all four fields, and supplies its close field as valueField
+when omitted. Without an explicit OHLC mapping, financial types use standard
+`open/high/low` fields and the series valueField as close. All four must be finite
+numbers, with low <= open/close <= high. Invalid records are skipped in place;
+no silent correction or filling. Event `value` is close; `itemClick.ohlc` supplies
+all four numeric values. Tooltip/accessibility text also contains all four.
+
+Financial axes default to low/high extents plus 5% padding, not zero; use
+`includeZero:true` to include zero explicitly. Flat ranges receive a nonzero span.
+Direction is close versus open: rising/falling/doji. CSS tokens `--dui-chart-up`,
+`--dui-chart-down`, `--dui-chart-neutral` customize those colors independently of
+series colors. Negative prices are supported.
+
+`type:'area'` fills each contiguous line segment separately. Default baseline is
+zero; with `includeZero:false` it is the closest plotted bound to zero. This is
+a truncated price axis, not a claim that the shaded area represents total value.
+Missing values leave unfilled gaps. Series overlap translucently rather than stack.
+`markers:true` also works for Area. No animation, calendars, automatic time sorting,
+market aggregation or indicators are introduced. See Components → Charts → Financial Charts.
+
+For interactive time-based price/volume charts, use separate StockChart (deferred extension; see [extension boundaries](EXTENSIONS.md)). Categorical Chart retains its existing contract.