@cyann/dash-lab 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,138 @@
+# Engineering Charter — AGENTS.md
+
+## Mission
+
+Build software that is **correct, simple, elegant, and easy for a human to take over**.
+Optimize for human comprehension and long-term ownership, not for the amount of code generated or the speed of the first implementation.
+
+**Decision rule:** every new line, abstraction, dependency, layer, and document must earn its place.
+
+## 1. Autonomy and approval
+
+Work independently on routine implementation, local refactoring, documentation, and safe build/test/lint commands within the project workspace. Do not interrupt for ordinary choices that respect this charter.
+
+**Ask the project owner before:**
+- Adding any external dependency, including development or test dependencies.
+- Introducing a framework or changing the project's technology stack. Do not select a new framework by default.
+- Making a breaking change to a public API, a core contract, or a significant architectural decision.
+- Performing destructive operations, publishing or deploying, accessing secrets, or sending project data to an external service.
+
+For decisions requiring approval, explain the need, realistic alternatives, trade-offs, and your recommendation. Never interpret silence as approval. This file does not override the execution environment's permission and security controls.
+
+## 2. Prefer less code
+
+- First understand the existing code and reuse what already solves the problem.
+- Do not implement speculative features, generic infrastructure, or abstractions for hypothetical future requirements (**YAGNI**).
+- Prefer the simplest solution that preserves correctness and foreseeable evolution; avoid cleverness and boilerplate.
+- Remove unnecessary complexity when it is safely in scope, but avoid unrelated refactoring.
+- A small, explicit implementation often beats an elaborate architecture.
+
+## 3. Write code humans can read
+
+- **Keep code visually airy**, Spacing out code blocks vertically (separating variable declarations, processing, and return statements with blank lines) would make it even easier for humans to review the code.
+- Avoid excessive line wrapping. Keep method signatures, expressions, and short statements on a single line whenever reasonably readable, as the output will be viewed on a wide screen.
+- Give classes, functions, parameters, and variables **precise, intention-revealing names**.
+- Prefer short, cohesive functions and classes with one clear reason to change; do not impose arbitrary line limits.
+- Separate meaningful logical steps, loops, and conditionals with blank lines. Keep code visually airy and consistently formatted.
+- Prefer expressive code over comments. Comments should be rare, concise, **in English**, and explain *why* a non-obvious constraint exists—not narrate *what* the code does.
+- Put substantial explanations in Markdown documentation, not large in-code comment blocks.
+- Favor well-defined object-oriented abstractions when appropriate to the domain, without wrapping trivial behavior in needless classes.
+- Follow the repository's established naming and formatting conventions unless explicitly asked to change them.
+- Add line space between logic blocks of codes, separate blocks as **variable declarations**, different **logic parts of code** and **results** with line space.
+- Limite usage of comments as minimum
+- Write the comments in English
+- Follow the naming conventions defined in the `convention/` directory whenever they apply to the language or framework used in the project.
+
+## 4. Compose components; keep architecture light
+
+- Organize packages/modules around **cohesive capabilities or components** with clear responsibilities and minimal public surfaces.
+- Use a small number of meaningful architectural layers when the application needs them (for example, domain, data/model, and presentation).
+- Keep dependencies directional and acyclic: higher-level consumers may use lower-level services; lower-level components must not know their concrete higher-level consumers.
+- Communicate upward through returned values, events, callbacks, or contracts defined at the appropriate boundary—not hidden reverse dependencies.
+- Keep the domain engine independent of UI and infrastructure details; replacing the UI must not require rewriting the engine.
+- Apply **SOLID**, composition, substitutable contracts, and design patterns (Composite, Strategy, Interpreter, Template Method, etc.) **when they genuinely improve clarity or extension**.
+- Do not introduce interfaces, factories, adapters, or extra layers solely to satisfy a pattern. A package need not be a separately deployable module.
+- MVC and similar UI patterns are tools for separating responsibilities, not mandatory templates for every feature.
+
+## 5. Own external dependencies
+
+**Default: use the language/platform and existing project libraries.** Keep the dependency graph small. Prefer focused, lightweight libraries to broad frameworks; do not add a new framework without explicit approval.
+
+Before *proposing* a new library, provide a concise assessment of:
+1. What problem it solves and why existing/native code is insufficient.
+2. Alternatives and architectural impact, including transitive dependencies.
+3. Maintenance status, version stability, known security issues, and resource cost where relevant.
+4. **Licensing:** inspect the authoritative license text and relevant transitive licenses; identify attribution, source-disclosure, redistribution, SaaS/network-use, and commercial/on-premise implications as applicable. Flag uncertainty rather than asserting legal certainty.
+
+**Do not install or add the dependency until the owner approves it.**
+
+Updates of **existing** dependencies are encouraged when justified. Preserve reproducible versions/lockfiles, review release notes and breaking changes, run relevant unit **and integration** tests, and add regression tests where needed. Never assume mocked tests prove real-library compatibility. Escalate changes that break public contracts or require major redesign.
+
+## 6. Test behavior and invariants
+
+- Prefer a TDD-style loop where practical: define expected behavior, implement, then refactor.
+- For a bug, first add a failing regression test that reproduces it whenever feasible.
+- Test public contracts, invariants, boundary values, error paths, equivalence cases, and important component interactions.
+- Include integration tests at boundaries with real libraries or services when mocks would conceal compatibility failures.
+- Keep tests deterministic, readable, independent, and proportionate to risk. Do not write tests only to inflate coverage numbers.
+- Run the relevant tests after each meaningful change; run a wider suite for dependency updates, migrations, and structural refactors.
+- Never weaken assertions, delete meaningful tests, or conceal failures simply to make a suite pass.
+
+## 7. Document for human handover
+
+Maintain just enough **Markdown** documentation that a new developer can locate the main components, understand their interactions, and safely make a change.
+
+- Keep a short README with setup, build/test commands, and pointers to architecture documentation.
+- Describe major components, dependency direction, key workflows, public contracts, invariants, and known constraints.
+- Record consequential architectural decisions as brief **ADRs**: context, options, chosen approach, and *why*.
+- Use **Mermaid diagrams** when a diagram explains structure or flow better than prose.
+- Update affected documentation alongside code. Avoid redundant or automatically generated essays that become stale.
+
+## 8. UI/UX for web applications
+
+When building an interface, treat usability as a first-class acceptance criterion:
+
+- Make domain concepts easy to discover, understand, and manipulate; do not leak internal engine complexity into the UI.
+- Maintain consistent visual hierarchy, spacing, navigation, terminology, and interaction patterns.
+- Provide clear feedback and deliberate empty, loading, success, and error states.
+- Support keyboard use, semantic HTML, accessible labels, sensible contrast.
+- Keep interactions responsive; measure before adding rendering complexity or optimizations.
+- Respect the existing design language and component conventions; do not introduce a UI framework or component library without approval.
+- For web projects, assess whether responsive design is appropriate for the intended use case. Do not assume it is required by default. If unclear, ask for confirmation before implementing it.
+
+## 9. Finish with a self-review and concise handover
+
+Before marking work complete, check:
+
+- **Necessity:** could any code, dependency, abstraction, or layer be removed?
+- **Clarity:** can another developer understand names, control flow, and component boundaries?
+- **Architecture:** are responsibilities cohesive, dependencies directional, and contracts preserved?
+- **Safety:** are licenses/approvals respected and errors handled rather than hidden?
+- **Evidence:** are appropriate tests passing and architecture docs current?
+
+End with a short report: **what changed; noteworthy decisions; tests run and results; documentation updated; remaining risks or approvals needed.** State clearly what was *not* verified. Do not claim tests or checks were run if they were not.
+
+## 10. Commit your modifications
+
+When developpment is finished, commit it in the local repository.
+
+- DO NOT push it automatically to the repository. A human check is necessary and a manual intervension is needed.
+- Create one commit per feature. Prompt will enumerate each features.S
+- Commit with idiomatic and concise message
+- Every commit must be atomic and must be able to compile and perform tests without any error
+
+## 11. Project handover map
+
+Public library exports live in `src/index.ts`; implementation is organized by capability under `src/`. The consuming application is under `demo/src/`, with plugins discovered only from its local `plugins/*/index.ts` entry points. Keep plugin activation synchronous, registrations transactional, and mounted panel identities stable. Read `docs/api.md` and `docs/architecture.md` before changing public contracts.
+
+Use Node.js 24 LTS. Run the relevant strict type, Vitest, lint/format, build, browser, and packed-consumer checks described in `CONTRIBUTING.md`. Update public JSDoc, English/French labels, affected Markdown, Storybook examples, and `CHANGELOG.md` with each feature. Generated `dist/`, demo builds, profiles, and test artifacts are ignored and must not be edited as sources.
+
+## 12. Maintain release notes automatically
+
+For every implemented feature, fix, public-contract change, or release, update `release-node.md` as part of the same work and commit. Do this without waiting for a separate documentation request. Record concrete resulting behavior, compatibility implications, verification, and remaining limits; keep the shorter `CHANGELOG.md` consistent. Move entries to an actual version/date only when a release is made. Never claim a package was published, deployed, or remotely verified without evidence.
+
+For application/plugin work, read `docs/application-guide.md` and `docs/api.md` first. Keep the README's ten-minute tutorial executable, including its file paths, discovery pattern, commands, and examples.
+
+---
+
+**North star:** an agent's best contribution is not code that merely works today, but a system its human owner can confidently understand, maintain, and evolve tomorrow.

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## Unreleased
+
+The package currently declares version `0.1.0`. No publication or release tag is created by the implementation workflow.
+
+### Added
+
+- Notification popups slide/fade out on dismissal, expiry, history removal, disabling popups or stack replacement, with immediate logical updates and reduced-motion support.
+
+- Automatic custom-layout checkpoints and immediate header/footer persistence, with a Custom layout preset replacing the toolbar save/restore/reset buttons. Built-in presets preserve the custom arrangement; existing commands and storage keys remain compatible.
+
+- Azure, High Contrast, Emerald and Umber themes, each in light/dark, selected in the hamburger menu and automatically persisted with preferences.
+
+- Validated npm publication script with simulation, account verification for `cyann`, public scoped publication, and prerelease tags.
+- Optional `PluginAPI.registerState` callbacks for centralized JSON export/import and layout checkpoints, including plugin rollback, legacy-file compatibility, and a stateful Hello World demo.
+- Reusable React/TypeScript library and a separate Vite Hello World demo, with watch and one-shot startup commands.
+- Dockview panels, chrome slots, Focus mode, and a combined View control.
+- Light/dark CSS tokens, Ant Design integration, reduced-motion support, and blue/gray themes.
+- Versioned explicit layout saves, restore/reset, and application/columns/rows presets.
+- Bounded notification history, unread state, configurable popups, and larger readable controls.
+- Command registry, scoped keyboard shortcuts, and a searchable command palette with recent selections.
+- File menu, Settings, Preferences, and validated JSON configuration import/export.
+- Modal entrance/backdrop animations, backdrop dismissal, and independent panel scrolling.
+- Local-directory plugin SDK covering panels, commands, menus, status, and monitoring; the demo uses Vite discovery.
+- English/French interfaces, language persistence, extensible catalogs, and translated command search.
+- Vitest service/store/provider contracts, real-browser interactions, Storybook, and a packed-consumer compatibility check.
+- API, architecture, contribution, dependency/license, and validation documentation under MIT.
+- GitHub Actions quality/browser workflows, Husky, staged lint/format checks, Conventional Commits, and issue/PR templates.
+- Ten-minute plugin tutorial, complete application/plugin guide, detailed [release notes](release-node.md), and agent instructions to maintain release records with future work.
+- Demo panel counts derived from discovered plugin contributions, with application chrome and plugin status following the selected language.
+
+### Fixed
+
+- Firefox notification dialogs now animate before native closure, with the same fallback shared by Settings and Commands. Reopening cancels pending closure, Escape follows the animated path, and reduced motion stays immediate.
+
+### Changed
+
+- Modal dialogs and backdrops animate on closure as well as opening, preserving native focus handoff, rapid reopening, Preferences content, and reduced-motion choices.
+- Successful npm publication creates an annotated local `version-<version>` Git tag on the validated release commit. Simulation and failed publication create no tag; conflicting tags block publication and existing tags on the same commit are retained.
+- Package name and consumer imports now use `@cyann/dash-lab`, following the existing `@cyann/js-parsec` and `@cyann/js-commons` convention. JSON configuration identifiers and browser-storage keys remain compatible.
+- Airier vertical spacing across library, demo, tests, Storybook examples, and scripts, separating declarations, processing steps, and results.
+
+### Compatibility
+
+- Version-1 configuration files without a language continue to import as English.
+- Plugins are synchronous trusted startup code bundled with the consuming application; membership changes require a remount/rebuild.
+- Desktop workstations are the supported interface target. Cross-browser coverage and tooling audit limits are recorded in [validation](docs/validation.md) and [dependencies](docs/dependencies.md).

package/CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing
+
+Use Node.js 24 LTS, Git, and npm. Read [AGENTS.md](AGENTS.md) before changing the project; it defines dependency approval, architecture, validation, and local-commit rules.
+
+```sh
+npm ci
+npm run dev
+```
+
+The demo opens at http://127.0.0.1:5173. `dev` watches the library, declarations, and application. `npm run start` builds once and previews at http://127.0.0.1:4173. Use `npm.cmd` if PowerShell blocks `npm.ps1`.
+
+## Scope and structure
+
+- `src/`: reusable library, public exports in `src/index.ts`.
+- `demo/src/`: consuming application, including local plugins discovered by Vite.
+- `src/**/*.test.*`: Vitest contracts, stores, and provider tests.
+- `src/**/*.stories.tsx`: interactive component examples.
+- `scripts/`: startup, browser interactions, and packed-consumer verification.
+- `docs/`: architecture, decisions, API reference, dependencies, and validation evidence.
+
+Keep library dependencies directed toward services and contracts. Application-specific code belongs in the demo or another consumer. Public APIs need English JSDoc, examples, and backward compatibility. New runtime-visible labels need English and French support; application/plugin catalogs remain application-owned.
+
+## Before committing
+
+```sh
+npm run check
+npm run lint
+npm run format:check
+npm test
+npm run build
+npm run test:package
+npm run build:storybook
+```
+
+`test:package` uses the npm cache populated by installation to install the produced tarball offline into a fresh consumer. Keep `test-results/` for diagnostics; do not commit generated builds, caches, or screenshots.
+
+For an interface or effect-lifecycle change, start the demo and run `npm run test:browser` in another terminal. It uses an installed Chromium browser, with Microsoft Edge as the Windows default. Set `BROWSER_PATH` for another executable. To test development directly, use `npm run test:browser -- http://127.0.0.1:5173`. Screenshots and isolated profiles stay in `test-results/`. Tests must preserve actual panel instances, focus behavior, and meaningful assertions.
+
+For modal changes, also run `npm run test:firefox` after a build and `npm run test:firefox -- --dev`. This targeted WebDriver BiDi regression starts/closes its own server and an isolated headless Firefox profile. Windows defaults to `C:/Program Files/Mozilla Firefox/firefox.exe`; set `FIREFOX_PATH` for another installation. It checks notification exit on button/Escape/backdrop dismissal, focus restoration, rapid reopening, command handoff, and reduced motion without adding a browser automation dependency.
+
+Use focused commits such as `feat(plugin): add an application contribution`, `fix(layout): preserve a saved checkpoint`, or `docs: clarify plugin startup`. Make one coherent feature or fix per commit. Do not publish or push automatically. Update the affected documentation and [CHANGELOG.md](CHANGELOG.md), including verification and any remaining limits.
+
+## Git hooks and CI
+
+Development installation runs `prepare` to install Husky for this repository. Pre-commit runs lint-staged (ESLint/Prettier on staged code; Prettier on staged documents), and commit-msg checks Conventional Commits with a 100-character header limit. CI and production installs skip hook installation. Consumers installing the published-format tarball do not need Husky.
+
+GitHub Actions defines Linux/Windows Node 24 checks and a Linux Node 22.13 compatibility job, plus Windows Edge interactions against compiled and development servers. Pull-request commits are checked over the base/head range. The workflows have read-only repository permissions and do not publish packages or deploy.
+
+For the same browser orchestration locally, run `npm run build`, then `npm run test:browser:ci` and `npm run test:browser:ci -- --dev`. These commands own and close their temporary servers on ports 4383 and 5383. The full script still accepts `BROWSER_PATH` when Edge is unavailable.
+
+## Publish to npm
+
+The npm package name is `@cyann/dash-lab`, matching `@cyann/js-parsec` and `@cyann/js-commons`. The repository and product remain named `dash-lab`. Use `@cyann/dash-lab` in imports and `@cyann/dash-lab/style.css` for styles.
+
+First simulate publication; no npm login is required for this mode:
+
+```sh
+npm run publish:npm -- --dry-run
+```
+
+The script runs strict TypeScript, lint, formatting, Vitest, publication-script tests, and the packed-consumer check (which builds the library). It packs the resulting library into an ignored `test-results/npm-publish/` directory, then invokes [`npm publish --dry-run`](https://docs.npmjs.com/cli/v11/commands/npm-publish/). The current version stays unchanged, no Git tag is created, and uncommitted work is allowed for simulation.
+
+For a real publication, commit the prepared release notes/version and sign in as `cyann`:
+
+```sh
+npm login --registry=https://registry.npmjs.org/
+npm run publish:npm
+```
+
+Real publication requires a clean Git checkout and verifies the logged-in account using [`npm whoami`](https://docs.npmjs.com/cli/v11/commands/npm-whoami/). It records the release commit, runs the same checks, and verifies that Git stays clean and HEAD unchanged before packing. It publishes the exact packed tarball publicly to `https://registry.npmjs.org/`, then creates an annotated local Git tag `version-<version>` on the recorded commit only after npm succeeds. npm handles any required interactive two-factor authentication. Credentials stay in npm's normal authentication setup; the script does not embed tokens or log in on your behalf.
+
+An existing tag on the release commit is reused unchanged. A tag pointing to another commit blocks publication before contacting npm; it is never overwritten. Git committer identity is checked before publishing. If npm succeeds but Git tagging fails (for example, signing fails), the command reports partial success and exits with an error: repair the local tag on the reported commit manually, without republishing that npm version. Tags and commits are never pushed automatically.
+
+The script publishes the version already declared in `package.json`. For subsequent releases, update `CHANGELOG.md` and `release-node.md`, then explicitly select a new version, for example:
+
+```sh
+npm version patch --no-git-tag-version
+git add package.json package-lock.json CHANGELOG.md release-node.md
+git commit -m "chore(release): prepare next version"
+npm run publish:npm -- --dry-run
+npm run publish:npm
+```
+
+`npm version --no-git-tag-version` updates the manifest/lockfile without creating a premature release tag. Commit those files with the release notes before publishing; the publication script creates the tag after success. It never changes versions or creates commits. Stable versions use the `latest` npm distribution tag; prerelease versions default to `next` and cannot target `latest`. Override with `npm run publish:npm -- --tag next`. This npm tag is separate from the Git version tag, such as `version-0.2.0-rc.1`. npm rejects an already published name/version; choose a new version rather than overwriting it.
+
+The script does not run browser or Storybook builds; run the existing browser/Storybook checks separately for interface changes. Use `npm.cmd` in these examples if PowerShell blocks `npm.ps1`.
+
+## Dependencies and reports
+
+Use the current stack and platform APIs first. Obtain approval before adding a dependency not explicitly requested by the owner. Record versions, authoritative license texts, transitive implications, Node requirements, and relevant security findings in [dependency notes](docs/dependencies.md). Do not apply forced audit downgrades or hide failures.
+
+Bug reports should contain Node/browser versions, steps, expected and actual behavior, and a minimal reproduction. Remove private data from logs and configuration files before sharing them. Contributions are provided under the project's [MIT license](LICENSE).
+
+Keep [release-node.md](release-node.md) current in the same commit as each feature or fix, including verified outcomes and limits. Use the [application/plugin guide](docs/application-guide.md) for complete setup recipes. Tutorial code is part of the handover contract and should compile against the public package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dash-lab contributors
+
+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,155 @@
-# Temporary Holding Version
+# dash-lab
 
-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.
+npm package name: `@cyann/dash-lab`.
+
+Build once. Create many.
+
+A reusable React workbench for desktop applications: dockable panels, light/dark themes, saved layouts, commands and shortcuts, notifications, settings, local plugins, and English/French interfaces. The Hello World demo consumes the same public API as an application.
+
+## Run the demo
+
+Use Node.js 24 LTS, or Node.js 22.13+ in the 22.x series. From this repository directory:
+
+```sh
+npm install
+npm run dev
+```
+
+Open http://127.0.0.1:5173. Development runs the library build with `--watch`, watches TypeScript declarations, and serves the demo with hot reload. Ctrl+C closes the watchers and server.
+
+```sh
+npm run start
+```
+
+This checks types, builds the library and demo once, and previews at http://127.0.0.1:4173. It does not watch files or require a prior build. On Windows, use `npm.cmd` if PowerShell blocks `npm.ps1`.
+
+## Ten-minute tutorial: your first plugin
+
+### 1. Start the workspace — two minutes
+
+Run the commands above. Try dragging a tab, switching themes, and opening Commands with Ctrl/⌘+Shift+P. View hides the header and footer together; Focus hides all chrome and Escape restores it.
+
+### 2. Add a component — three minutes
+
+Create `demo/src/plugins/counter/Counter.tsx`:
+
+```tsx
+import { useState } from 'react';
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return (
+    <section style={{ padding: 24 }}>
+      <h1>Counter</h1>
+      <p>
+        Value: <output aria-label="Counter value">{count}</output>
+      </p>
+      <button type="button" onClick={() => setCount((value) => value + 1)}>
+        Increment
+      </button>
+    </section>
+  );
+}
+```
+
+### 3. Register the plugin — two minutes
+
+Create `demo/src/plugins/counter/index.ts`:
+
+```ts
+import type { WorkbenchPlugin } from '@cyann/dash-lab';
+import { Counter } from './Counter';
+
+const plugin: WorkbenchPlugin = {
+  id: 'counter',
+  activate(api) {
+    api.registerPanel({ id: 'counter.panel', title: 'Counter', component: Counter });
+    api.registerCommand({
+      id: 'counter.notify',
+      title: 'Counter: send a notification',
+      execute: ({ notify }) => {
+        notify({ title: 'The counter plugin is ready.', level: 'success' });
+      },
+    });
+    api.registerMenu({ id: 'counter.menu', title: 'Counter notification', commandId: 'counter.notify' });
+  },
+};
+
+export default plugin;
+```
+
+The demo already discovers `src/plugins/*/index.ts` with Vite. Its plugin boundary reloads when membership changes. If the old saved layout has a different panel set, it is rejected and the default layout stays usable; a new custom checkpoint is saved automatically after arranging your panels.
+
+### 4. Use it — two minutes
+
+Select Counter, click Increment, and switch tabs or enter/leave Focus. The counter value remains. Open Plugins → Counter notification, or search `counter.notify` in Commands, to run the registered action. No additional entry in the demo component is required.
+
+Activation is synchronous. IDs must be unique; `workbench.*` command IDs are reserved. Plugin panels are registered before application panels, and references must point to earlier panels. A panel without a position uses Dockview's default placement. Plugins are trusted application code bundled with the app; production membership changes require a rebuild.
+
+### 5. Verify and continue — one minute
+
+```sh
+npm run check
+npm test
+npm run build
+```
+
+Save a layout, change Preferences → Language, and try JSON export/import from File. Plugins can opt in with `api.registerState({ exportState, importState })`; the Hello World demo saves its name and greeting with the layout and configuration. For a fresh consuming application, all six plugin contributions, state handlers, language catalogs, and troubleshooting, follow the [application and plugin guide](docs/application-guide.md). The [API reference](docs/api.md) covers individual contracts.
+
+## Use the library
+
+```sh
+npm install @cyann/dash-lab
+```
+
+Maintainers can prepare publication with `npm run publish:npm -- --dry-run`, then publish a committed release with `npm run publish:npm`. See [the publication guide](CONTRIBUTING.md#publish-to-npm) for account setup, versioning, and prerelease tags.
+
+Build a local tarball with `npm pack` and install it in a consuming application. No npm publication is assumed. React and React DOM are peers; import the stylesheet explicitly and give the workbench a parent with a height:
+
+```tsx
+import { Workbench } from '@cyann/dash-lab';
+import '@cyann/dash-lab/style.css';
+
+export function App() {
+  return (
+    <div style={{ height: '100vh' }}>
+      <Workbench title="My Lab">Ready</Workbench>
+    </div>
+  );
+}
+```
+
+Use an optional surrounding router for application routes. Workbench supplies isolated theme, notification, command, and language providers, or reuses explicit ancestors. Its stable panels retain React state and scroll independently.
+
+## Development and checks
+
+```sh
+npm run check
+npm run lint
+npm run format:check
+npm test
+npm run build
+npm run test:package
+npm run build:storybook
+npm run test:browser:ci
+npm run test:browser:ci -- --dev
+```
+
+Browser checks use installed Microsoft Edge on Windows. Set `BROWSER_PATH` for another Chromium executable. `npm run test:browser -- http://127.0.0.1:5173` tests an already running demo. The CI runner owns its temporary server. Screenshots, profiles, and packed consumers stay in ignored `test-results/`.
+
+`npm run storybook` opens the interactive examples. Husky installs local hooks during development installation: staged ESLint/Prettier checks and Conventional Commits. CI/production installs skip hook setup. GitHub Actions includes Windows/Linux checks and does not publish or deploy.
+
+## Documentation
+
+- [Application and plugin guide](docs/application-guide.md): complete setup and contribution recipes for humans and agents.
+- [Public API](docs/api.md): props, providers, hooks, services, and persisted-format contracts.
+- [Architecture and decisions](docs/architecture.md): ownership and dependency direction.
+- [Contributing](CONTRIBUTING.md) and [agent instructions](AGENTS.md): implementation and validation rules.
+- [Release notes](release-node.md) and [changelog](CHANGELOG.md): completed features and release status.
+- [Validation](docs/validation.md) and [dependencies/licenses](docs/dependencies.md): evidence and known limits.
+
+Desktop workstations are the supported target. Browser verification currently covers Chromium/Edge; Firefox and Safari are not verified. Runtime audit and remaining tooling/bundle warnings are documented in the dependency notes.
+
+## License
+
+[MIT](LICENSE), with retained [third-party notices](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,31 @@
+# Third-party notices
+
+dash-lab is licensed under MIT. Dependencies retain their own licenses and copyright notices.
+
+The ESM library leaves React, React DOM, Ant Design, Dockview React, and Zustand external. npm installs those packages separately with their published notices. Development tools are not shipped in the library package. See `docs/dependencies.md` in the source repository for the inventory and audit limitations.
+
+## Dockview stylesheet
+
+The distributed stylesheet includes Dockview CSS from dockview-react 8.8.3. The following notice is reproduced from the installed package's LICENCE.md. Source: https://github.com/dockview/dockview.
+
+MIT License
+
+Copyright (c) 2021 mathuo
+
+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/dist/commands/CommandContext.d.ts

@@ -0,0 +1,19 @@
+import type { CommandDefinition, CommandRegistry } from './CommandRegistry.js';
+export declare const CommandContext: import("react").Context<{
+    registry: CommandRegistry;
+    execute: (id: string) => Promise<boolean>;
+} | null>;
+/** Commands and operations supplied by the nearest CommandProvider. */
+export interface CommandControls {
+    /** Registered actions in registration order. */
+    commands: readonly CommandDefinition[];
+    /** Register an action and receive its cleanup function. */
+    register: CommandRegistry['register'];
+    /** Execute an action, reporting failures to the nearest notification center when one is present. */
+    execute: (id: string) => Promise<boolean>;
+    /** Check current availability. */
+    canExecute: CommandRegistry['canExecute'];
+}
+/** Access the nearest registry through React; requires CommandProvider or a Workbench ancestor. */
+export declare function useCommands(): CommandControls;
+//# sourceMappingURL=CommandContext.d.ts.map

package/dist/commands/CommandContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandContext.d.ts","sourceRoot":"","sources":["../../src/commands/CommandContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE/E,eAAO,MAAM,cAAc;cAA6B,eAAe;aAAW,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC;SAAgB,CAAC;AAEnI,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,2DAA2D;IAC3D,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;IACtC,oGAAoG;IACpG,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C,kCAAkC;IAClC,UAAU,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;CAC3C;AAED,mGAAmG;AACnG,wBAAgB,WAAW,IAAI,eAAe,CAW7C"}

package/dist/commands/CommandPalette.d.ts

@@ -0,0 +1,10 @@
+/** Options for the controlled command palette. */
+export interface CommandPaletteProps {
+    /** Whether the palette should be open. */
+    open: boolean;
+    /** Requests closure after dismissal or selection. */
+    onClose: () => void;
+}
+/** Searches and executes the nearest registry's commands; requires command and notification providers. */
+export declare function CommandPalette({ open, onClose }: CommandPaletteProps): import("react").JSX.Element;
+//# sourceMappingURL=CommandPalette.d.ts.map

package/dist/commands/CommandPalette.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandPalette.d.ts","sourceRoot":"","sources":["../../src/commands/CommandPalette.tsx"],"names":[],"mappings":"AAQA,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,IAAI,EAAE,OAAO,CAAC;IACd,qDAAqD;IACrD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AACD,0GAA0G;AAC1G,wBAAgB,cAAc,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,mBAAmB,+BA0JpE"}

package/dist/commands/CommandProvider.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+import { CommandRegistry } from './CommandRegistry.js';
+/** Options for an application command registry. */
+export interface CommandProviderProps {
+    /** Components that register or execute actions. */
+    children: ReactNode;
+    /** Optional existing registry. Keep stable while mounted. */
+    registry?: CommandRegistry;
+}
+/** Provides a registry and routes execution failures into the nearest notification center. */
+export declare function CommandProvider({ children, registry: supplied }: CommandProviderProps): import("react").JSX.Element;
+//# sourceMappingURL=CommandProvider.d.ts.map

package/dist/commands/CommandProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandProvider.d.ts","sourceRoot":"","sources":["../../src/commands/CommandProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAIvD,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,EAAE,SAAS,CAAC;IACpB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,oBAAoB,+BAgCrF"}

package/dist/commands/CommandRegistry.d.ts

@@ -0,0 +1,40 @@
+import type { ShortcutEvent, ShortcutPlatform } from './shortcuts.js';
+/** An application action, callable by ID and optionally by keyboard. */
+export interface CommandDefinition {
+    /** Unique identifier within this registry. Workbench reserves the workbench.* namespace. */
+    readonly id: string;
+    /** Human-readable action name. */
+    readonly title: string;
+    /** Key combination, for example Mod+Alt+S or Mod+Enter. Mod means Command on macOS and Control elsewhere. */
+    readonly shortcut?: string;
+    /** Handler; asynchronous commands remain unavailable until this promise settles. */
+    readonly execute: () => void | Promise<void>;
+    /** Optional predicate evaluated at execution time. */
+    readonly isEnabled?: () => boolean;
+    /** Permit the shortcut inside text inputs and contenteditable regions. Defaults to false. */
+    readonly allowInEditable?: boolean;
+}
+/** A framework-independent command registry with conflict detection and disposable registrations. */
+export declare class CommandRegistry {
+    private readonly platform;
+    private readonly entries;
+    private readonly running;
+    private readonly listeners;
+    private snapshot;
+    /** Selects how Mod is resolved. Defaults to Control; the React provider detects the browser platform. */
+    constructor(platform?: ShortcutPlatform);
+    private publish;
+    /** Register an action. Duplicate IDs and equivalent shortcuts throw before changing the registry. Returns an idempotent unregister function. */
+    readonly register: (command: CommandDefinition) => (() => void);
+    /** Return a stable snapshot suitable for external-store subscriptions. */
+    readonly getCommands: () => readonly CommandDefinition[];
+    /** Subscribe to registration and execution-state changes; returns an unsubscribe function. */
+    readonly subscribe: (listener: () => void) => (() => void);
+    /** Whether the command exists, is enabled, and is not already running. Predicate errors propagate. */
+    readonly canExecute: (id: string) => boolean;
+    /** Execute by ID. Resolves false for unknown, disabled, or running actions; handler and predicate errors reject. */
+    readonly execute: (id: string) => Promise<boolean>;
+    /** Find an enabled keyboard action, respecting composition, repeats, prior handlers, AltGraph, and text-entry policy. */
+    readonly matchShortcut: (event: ShortcutEvent, inEditable?: boolean) => CommandDefinition | undefined;
+}
+//# sourceMappingURL=CommandRegistry.d.ts.map

package/dist/commands/CommandRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandRegistry.d.ts","sourceRoot":"","sources":["../../src/commands/CommandRegistry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEtE,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6GAA6G;IAC7G,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,sDAAsD;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IACnC,6FAA6F;IAC7F,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAOD,qGAAqG;AACrG,qBAAa,eAAe;IAOd,OAAO,CAAC,QAAQ,CAAC,QAAQ;IANrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAoC;IAEpD,yGAAyG;gBAC5E,QAAQ,GAAE,gBAA0B;IAEjE,OAAO,CAAC,OAAO;IAMf,gJAAgJ;IAChJ,QAAQ,CAAC,QAAQ,GAAI,SAAS,iBAAiB,KAAG,CAAC,MAAM,IAAI,CAAC,CAsB5D;IAEF,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,QAAO,SAAS,iBAAiB,EAAE,CAAkB;IAEzE,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAMvD;IAEF,sGAAsG;IACtG,QAAQ,CAAC,UAAU,GAAI,IAAI,MAAM,KAAG,OAAO,CAIzC;IAEF,oHAAoH;IACpH,QAAQ,CAAC,OAAO,GAAU,IAAI,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC,CAgBrD;IAEF,yHAAyH;IACzH,QAAQ,CAAC,aAAa,GAAI,OAAO,aAAa,EAAE,oBAAkB,KAAG,iBAAiB,GAAG,SAAS,CAQhG;CACH"}

package/dist/commands/searchCommands.d.ts

@@ -0,0 +1,3 @@
+import type { CommandDefinition } from './CommandRegistry.js';
+export declare function searchCommands(commands: readonly CommandDefinition[], query: string, recent: readonly string[]): CommandDefinition[];
+//# sourceMappingURL=searchCommands.d.ts.map

package/dist/commands/searchCommands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchCommands.d.ts","sourceRoot":"","sources":["../../src/commands/searchCommands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AA6B9D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,uBAa9G"}

package/dist/commands/shortcuts.d.ts

@@ -0,0 +1,7 @@
+/** Platform used to resolve the portable Mod modifier. */
+export type ShortcutPlatform = 'mac' | 'other';
+/** Native keyboard properties required by the framework-independent matcher. */
+export type ShortcutEvent = Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'metaKey' | 'altKey' | 'shiftKey' | 'repeat' | 'isComposing' | 'defaultPrevented' | 'getModifierState'>;
+export declare function eventSignature(event: Pick<ShortcutEvent, 'key' | 'ctrlKey' | 'metaKey' | 'altKey' | 'shiftKey'>): string;
+export declare function parseShortcut(shortcut: string, platform: ShortcutPlatform): string;
+//# sourceMappingURL=shortcuts.d.ts.map

package/dist/commands/shortcuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcuts.d.ts","sourceRoot":"","sources":["../../src/commands/shortcuts.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,OAAO,CAAC;AAC/C,gFAAgF;AAChF,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,aAAa,EACb,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,aAAa,GAAG,kBAAkB,GAAG,kBAAkB,CAC3H,CAAC;AAqBF,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC,UAE/G;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,UAkCzE"}