@stcn52/pro 0.0.0-stage → 0.2.0

package/CONVENTIONS.md

@@ -0,0 +1,152 @@
+# Component authoring conventions
+
+`@stcn52/pro` is a component library, not a demo. Everything in it must be
+reasonable to ship to a host application that knows nothing about PingCode Ship,
+the demo store or the demo's routes. This file is the definition of done for a
+component; `pnpm verify` is the machine check behind it.
+
+## What the library is
+
+A 1:1 restoration of the PingCode **Ship** workbench, published as tokens, CSS
+layers and React components. Styling is **plain CSS classes driven by design
+tokens** — no CSS-in-JS, no per-component stylesheet files, no inline geometry.
+
+```
+src/styles/tokens.css    raw scale + purpose-named semantic tokens (light/dark)
+src/styles/base.css      reset, type scale, utilities
+src/styles/primitives.css  controls, overlays, table, navigation, states, charts
+src/styles/ship.css      the Ship surface: rail, headers, toolbar, detail sheet,
+                         list workbench, wizard, detail blocks
+src/components/*.tsx     primitives (one file per component family)
+src/components/table/    a family that outgrew one file: the DataTable parts,
+                         re-exported unchanged by src/components/Table.tsx
+src/ship/*.tsx           product chrome and the extracted composites
+src/index.ts             the only barrel: every public name is re-exported here
+```
+
+## Rules
+
+1. **Tokens only.** Colours, spacing, radii, type and durations come from
+   `tokens.css`. A new literal needs a reason in a comment next to it.
+2. **Purpose-named colour.** `--surface-*`, `--fg-*`, `--border-*`, `--accent`,
+   `--status-*`. The raw `--gray-*` scale exists only underneath them.
+3. **One stylesheet per layer.** A new component adds its rules to the layer it
+   belongs to, in the same order as the barrel, not to a new file. Element
+   resets are written with `:where()` so they carry zero specificity.
+4. **Class naming is `pro-<block>__<element>--<modifier>`.** A class that
+   describes a _layout slot_ (`pro-row`, `pro-num`, `pro-detail__tools`) may be
+   used by a host; anything else is internal and a host should get a component
+   instead. Never add an `app-*` class: that prefix belongs to host applications.
+5. **No host knowledge.** The library must not contain a route string
+   (`/ship/...`, `/pjm/...`), a store, a `localStorage` key, a demo id or a demo
+   name. Data arrives as props; navigation arrives as callbacks.
+6. **Controlled by default where it matters.** Anything with a selection takes
+   `value` + `onChange`; use `useControllableState` so a component also works
+   uncontrolled (`defaultValue`, `defaultOpen`, `defaultExpanded`).
+7. **Refs are forwarded** on every form control (focus management is the host's
+   job, and `⌘K`-style shortcuts depend on it).
+8. **The five states are structural.** Anything that shows data accepts
+   `status="loading" | "error" | "ready"` plus `emptyState` / `errorState`, so no
+   screen can ship with only the populated case.
+9. **Keyboard first.** One focus ring (`:focus-visible` in `base.css`), `Esc`
+   closes every floating layer, arrows move through lists, `Enter`/`Space`
+   activate, focus returns to the element that opened a layer, and dialogs trap
+   `Tab` inside themselves.
+10. **Accessibility is not optional.** Every control has a label; an icon-only
+    button takes `label` (becomes `aria-label` + `title`); decorative icons are
+    `aria-hidden`; live regions exist before content arrives; motion is disabled
+    under `prefers-reduced-motion`.
+11. **Export discipline.** Named exports only, no default exports, types exported
+    next to the component, and every public name re-exported from
+    `src/index.ts`. Adding an export means updating the README table and
+    `docs/components.md` in the same change.
+12. **Every exported component has a test** under `src/__tests__/<Name>.test.tsx`
+    covering, at minimum: it renders; a controlled prop is honoured; the keyboard
+    path works; and `Esc`/focus behaviour where the component has a floating
+    layer.
+13. **Semantic versioning.** A user-visible change adds a CHANGELOG entry under
+    `## [Unreleased]`; breaking a prop, a default or an exported name is a major
+    bump and needs a migration note.
+
+## Documentation
+
+`docs/api.md` and `docs/tokens.md` are **generated** from `src/` — run `pnpm gen:docs`
+after touching a component, a prop or a token. `pnpm verify` regenerates them and
+fails on any difference, so the committed reference cannot drift from the code.
+
+The prose is hand-written and checked the other way round: every runtime export
+must be named in `README.md`, and every component in `docs/components.md`. Adding
+an export means adding it to both.
+
+## Focus
+
+`base.css` draws the focus ring for everything inside `.pro-root` /
+`.pro-portal` with `.pro-root :focus-visible` (**0,2,0**). A component that paints
+its own focus indicator — the open cell editors, whose accent hairline _is_ the
+field — has to out-specify that rule: name the component, not the bare input
+(`.pro-cell-editor :focus-visible`, not `.pro-quick-text__input { outline: none }`,
+which is only 0,1,0 and loses). Two rings around one field is the symptom.
+
+## Grid cells
+
+`.pro-table th, .pro-table td { text-align: left; … }` is one class **plus an
+element**, so a bare `.pro-table__pick { text-align: center }` loses to it. A rule
+that aligns or states a table cell has to name the element too
+(`.pro-table td.pro-table__pick`). The same applies to the pick cell's two states:
+the checkbox is taken out of the flow and centred, so the invisible one cannot
+push the row number off the axis the header's select-all sits on.
+
+## Stories
+
+Every exported component gets a story, next to its source
+(`src/components/Button.stories.tsx`), under a `Components/<Group>/<Name>` or
+`Ship/<Group>/<Name>` title. A story set is expected to show the states a host
+will actually meet — the five list states, controlled and uncontrolled, the
+keyboard path, an open floating layer — not just the happy one. `pnpm verify`
+fails when an export has no story (`scripts/check-story-coverage.mjs`), and both
+ESLint and Prettier cover the story files.
+
+## Frozen columns
+
+A pinned cell has to be opaque, or the columns sliding under it show through — but
+it must never look like a column of its own. The **row** carries the state
+background (`tr:hover`, `tr.is-selected`, `tr.is-cursor`, a host's own class) and
+`td.is-fixed` takes `background: inherit`. A pinned cell that paints a colour of
+its own is one row-state away from outlining itself.
+
+## Splitting a component family
+
+One file per family is the default, and most families stay one file. When one
+grows past what a reader can hold — `DataTable` reached 912 lines — it becomes a
+directory (`src/components/table/`) of modules cut by **what changes together**:
+the public contract (`types`), the arithmetic (`geometry`), the keyboard
+(`keyboard`), the grouping (`grouping`), and one module per thing the component
+renders (`DataTable`, `TableHead`, `TableRow`, `SkeletonRows`, `BulkBar`,
+`ColumnMenu`, `CellCommands`).
+
+Two rules keep that readable and keep the tooling honest:
+
+- **The public path stays where it was.** `src/components/Table.tsx` remains the
+  barrel (`export * from './table/types'` and `'./table/DataTable'`), so no host
+  and no story has to learn a new import. `src/index.ts` is unchanged.
+- **The props type stays next to the component.** `scripts/gen-docs.mjs` resolves
+  `DataTableProps` **in the same file** as `DataTable`, so moving the type to a
+  separate module would silently empty the generated props table — which is also
+  why `scripts/public-surface.mjs` follows `export * from` rather than only
+  reading declarations: without that, every name behind a barrel would drop out
+  of `docs/api.md` and out of the test/story coverage checks.
+
+## Working on it
+
+```bash
+pnpm typecheck   # tsc --noEmit
+pnpm lint        # eslint
+pnpm test        # vitest run
+pnpm build       # tsup (ESM + CJS + d.ts) then scripts/build-styles.mjs
+pnpm verify      # everything above, plus publint/attw and a pack smoke test
+```
+
+`pnpm verify` is the gate: a change is done when it passes, and the docs and
+CHANGELOG are updated in the same change.
+
+React ref access and state-in-effect checks are errors. `pnpm verify` permits zero lint warnings; fix the cause rather than disabling a rule. Stable controlled setters publish committed props before descendant layout effects.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Klun
+
+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,227 @@
-# Temporary Holding Version
+# @stcn52/pro
 
-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.
+A 1:1 restoration of the PingCode **Ship** workbench as a publishable React
+component library: design tokens, primitives and the Ship product chrome, with
+light and dark themes.
+
+```
+src/styles/tokens.css   raw PingCode scale + purpose-named semantic tokens
+src/styles/base.css     reset, type scale, utilities
+src/components/*        primitives (button, input, table, tree, overlay, charts…)
+src/ship/*              product chrome (rail, headers, toolbar, entity views)
+src/icons/icons.ts      146 glyphs taken verbatim from PingCode's icon sprite
+```
+
+## Install and use
+
+```bash
+pnpm add @stcn52/pro react react-dom
+```
+
+```tsx
+import { AppRail, ListToolbar, DataTable, StatusTag } from '@stcn52/pro';
+import '@stcn52/pro/styles.css'; // or '@stcn52/pro/tokens.css' for tokens only
+
+export function Screen() {
+  return (
+    <div className="pro-root">
+      <StatusTag status="Pending" />
+    </div>
+  );
+}
+```
+
+Every component is a named export from the package root. The stylesheet is a
+single file; the token layer is also published separately so a host application
+can adopt the scale without the component styles.
+
+### Consuming a local checkout
+
+A host next to this repository depends on it with pnpm's `link:` protocol, so
+imports resolve through the package's `exports` map into `dist/`:
+
+```json
+{ "dependencies": { "@stcn52/pro": "link:../klun-pro" } }
+```
+
+`file:` also works, but pnpm snapshots the directory at install time: a later
+`pnpm build` here would not reach the host until it installs again, and the host
+would quietly run a stale library. `link:` keeps the package live, and the host
+still consumes the built artefact rather than the source.
+
+## Storybook
+
+Every component has a story, and the story is where to look first when a prop's
+behaviour is not obvious from its name:
+
+```bash
+pnpm storybook          # http://localhost:6006
+pnpm build:storybook    # static site in dist-storybook/
+```
+
+The preview loads the same stylesheet the package publishes
+(`src/styles/index.css`), renders each story inside `.pro-root` — where the
+library's element resets live — and puts a light/dark switch in the toolbar that
+sets `data-theme` on the frame. The docs addon reads the exported props types
+with `react-docgen-typescript`, so an args table is generated from the same
+declarations `docs/api.md` is generated from.
+
+`scripts/check-story-coverage.mjs` runs inside `pnpm verify`: every runtime
+export has to be named by a `*.stories.tsx`, with a budget that only goes down.
+
+## Theming
+
+Theme is selected with `data-theme` on any ancestor — usually `<html>`:
+
+```html
+<html data-theme="light">
+  <!-- or "dark" -->
+  <html data-theme="auto">
+    <!-- follows prefers-color-scheme -->
+  </html>
+</html>
+```
+
+Components never branch on colour scheme; they only read CSS variables.
+
+## What is in the box
+
+| Group           | Exports                                                                                                                                                                                                                                                                                  |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Foundations     | `cx`, `formatNumber`, `formatCount`, `formatDay`, `formatListTime`, `formatDateTime`, `formatCompact`, `pluralize`, `statusColor`, `avatarColor`, `initials`, `useControllableState`                                                                                                     |
+| Icons           | `Icon`, `ICONS`, `IconName`                                                                                                                                                                                                                                                              |
+| Actions         | `Button`, `SplitButton`, `ActionButton`                                                                                                                                                                                                                                                  |
+| Forms           | `Input`, `Textarea`, `SearchInput`, `Field`, `Checkbox`, `Switch`, `Select`, `MultiSelect`                                                                                                                                                                                               |
+| Overlays        | `Popover`, `Menu`, `Tooltip`, `Dialog`, `ContextMenu` / `ContextMenuList` / `useContextMenu`, `useToast` / `ToastProvider`, `usePopoverClose`, `useAnchorRef`                                                                                                                            |
+| Data            | `DataTable` (`Column`, `SortState`), `Pagination`, `Tag` / `StatusTag` / `LevelTag` / `CountTag`, `Avatar` / `AvatarStack` / `AvatarPlaceholder` / `IconAvatar`, `Progress`, `Metric`, `BarChart`, `Donut`, `Sparkline`, `ScatterPlot`, `Crumbs`, `KeyValue`, `Card`                     |
+| Navigation      | `Nav`, `Tree` / `TreeGroup`, `Sidebar` / `SidebarCollapseProvider` / `useSidebarCollapsed`, `Segment`, `Chip`, `Divider`                                                                                                                                                                 |
+| States          | `Empty`, `Spin`, `Result`, `EmptyState`, `ErrorState`, `EmptyArt`, `Skeleton`, `TableSkeleton`, `LoadingBlock`, `InlineSpinner`, `Banner`                                                                                                                                                |
+| Ship chrome     | `AppRail`, `AppHeader`, `ProductHeader`, `HeaderActions`, `BrandMark`, `ListHeader`, `ListToolbar`, `FilterPanel`, `FilterChip`, `BoardView`, `RoadmapView`, `DocSplit`, `TitleCell`, `TypeBadge`, `ProductCell`, `StarButton`, `QuickStart`, `TableBanner`, `SelectionBar`, `VoteCount` |
+| Entity surfaces | `DetailSheet`, `DetailBlock`, `DetailTool`, `DetailSection`, `DetailField`, `Feed`, `FeedFilter`, `CommentComposer`, `EditableText`                                                                                                                                                      |
+| Inline editors  | `PeoplePicker` (`PeoplePickerTab`), `QuickSelect`, `QuickText`, `useSelectAnchor`, `useListCursor`                                                                                                                                                                                       |
+| Assistant       | `AiPanel`, `PingMark`                                                                                                                                                                                                                                                                    |
+| Shell surfaces  | `AccountMenu`, `ShortcutsDialog`, `QuickStartDialog`                                                                                                                                                                                                                                     |
+| Canonical data  | `DEFAULT_SHARING` (`ReportSharing`), `defaultCanvasWidgets` / `isCanvasWidgetSpan`, `componentLine` / `primaryComponents`, `quarterWeekendDays`, `cursorAfter` / `matchesQuery`, `downloadAttachment` / `exportRowsToCsv`                                                                |
+| Composites      | `ListWorkbench`, `EntityPicker`, `EntityDialog`, `ProjectWizard`, `CommentThread`, `AttachmentUpload`, `LinkPicker`, `FilePreview`, `TransitionsTimeline`, `ShareDialog`, `ReportCanvas`, `RoadmapEditor`, `RichTextToolbar`                                                             |     |
+
+## Design rules the code follows
+
+- **Tokens over literals.** Colours, spacing, radii and type come from
+  `tokens.css`; a new literal needs a reason. Element resets are written with
+  `:where()` so they carry zero specificity and never beat a component class.
+- **Purpose-named colour.** `--surface-*`, `--fg-*`, `--border-*`, `--accent`,
+  `--status-*` — the raw `--gray-*` scale exists only underneath them.
+- **The five states are real.** `DataTable` takes `status="loading" | "error" |
+"ready"` plus `emptyState` / `errorState` nodes, so no list can ship with only
+  the populated case.
+- **Keyboard first.** One focus ring style, `Esc` closes every floating layer,
+  `Dialog` traps Tab inside the sheet, `Tree` and the rail expose
+  `aria-current`, table headers expose `aria-sort`, and a live region announces
+  row counts.
+- **Motion is small and optional.** 120–180 ms transitions, all of them
+  disabled under `prefers-reduced-motion`.
+
+## Build
+
+```bash
+pnpm install
+pnpm build        # tsup (ESM + CJS + .d.ts) then scripts/build-styles.mjs
+pnpm typecheck
+pnpm gen:icons <path-to-icons-common-full.json>   # regenerates src/icons/icons.ts
+```
+
+`pnpm build` writes `dist/index.{js,cjs,d.ts}`, `dist/styles.css` and
+`dist/tokens.css`.
+
+## Fidelity
+
+`docs/measurements.md` records where every measurement came from (live DOM
+probes, pixel sampling, and PingCode's own stylesheets) and lists the known
+gaps — the most important being that four Ship tabs were captured while their
+grid was still a loading skeleton, so their column sets come from the DOM rather
+than from pixels, and that no dark-theme screenshot of the running product was
+obtainable, so dark mode is built from PingCode's own `:root[theme=dark]`
+token block.
+
+## Additional common components
+
+`Radio` / `RadioGroup`, `Tabs`, `Collapse`, `Badge`, `Slider`, `Steps`, `Alert`, `CheckboxGroup`, `PasswordInput`, `Rate`, `Cascader`, `Transfer`, `DatePicker`, and `DateRangePicker` complement the Ship primitives.
+Their option-based APIs and behaviour are informed by [Ant Design](https://github.com/ant-design/ant-design), implemented with native controls and the existing tokens; no antd runtime dependency is required.
+Tree/DirectoryTree include cached directory ranges, RTL navigation, leaf icons and
+source-aligned drop geometry; see the onDrop position migration in `docs/components.md`.
+
+Cascader supports multiple parent/leaf paths, intermediate selection, field mapping,
+lazy children with retry and controlled opening/search.
+
+Selection components support controlled and uncontrolled state. Transfer also supports
+independent controlled checks, directional moves, per-side paging and custom lists. See Storybook and `docs/components.md`.
+
+Releases and deployments use the platform workflow (build → approval → publish →
+deploy). See [RELEASING.md](./RELEASING.md); local release commands validate only.
+
+`Tree` now supports controlled expansion/selection/checking, lazy loading,
+search highlighting, drag-and-drop and fixed-height virtual scrolling.
+`DirectoryTree` adds file-browser Ctrl/Meta/Shift selection and click/double-click expansion.
+
+### Global configuration and forms
+
+`ConfigProvider` supplies nested `locale` (`en-US` / `zh-CN`), `direction` and
+`disabled` defaults. Explicit control props win. `useProConfig` and
+`useComponentDisabled` expose these defaults to host controls.
+
+`Form`, `FormItem`, `FormList`, `useForm`, `useFormInstance` and `useWatch` provide
+nested field state, dynamic arrays, validation, resets and async submission.
+`Form.Item`, `Form.List` and the compound hooks are also available. Full Ant
+Design API compatibility is not implemented. See [component reference](docs/components.md).
+
+Select and MultiSelect support grouped options, labeled values, clearing, custom rendering,
+controlled popups, async states, custom/remote search and opt-in virtual scrolling.
+MultiSelect also supports tags, token separators, and selection limits; see
+[component contracts](docs/components.md#select--multiselect).
+
+全库完善的待办、优先级和验收标准见[AntD 对照计划](docs/antd-alignment-plan.md)。
+
+Common input additions: `InputNumber` (number/null), `AutoComplete` (editable suggestions),
+`TreeSelect` (hierarchical single/multiple/check selection) and `TimePicker` (local ISO clock).
+They integrate with Form and ConfigProvider; see the component guide for native API differences.
+
+General display entries: `Breadcrumb`, responsive `Descriptions`, formatted `Statistic`,
+and `Typography` with Text/Title/Paragraph/Link, copying, editing and CSS ellipsis.
+
+General layout entries: `Layout` (Header/Content/Footer/Sider), `Row`/`Col` (24-column
+responsive grid), `Grid.useBreakpoint`, `Flex`, `Space`/Compact and `Splitter`/Panel.
+
+`Dropdown` combines a native Button trigger with `Menu`; `Popconfirm` adds controlled opening,
+async confirmation, cancellation and retry feedback using the existing Popover.
+
+`Drawer` shares Dialog's modal stack, focus restoration and body scroll lock, with four physical
+edge placements, bounded width/height and independent keyboard/mask/close-button controls.
+
+`Image` renders actual image bytes with native refs, fallback/loading content and controlled
+Dialog previews; `Image.PreviewGroup` navigates an explicit `items` list.
+
+`Upload` keeps real File objects, supports manual/preflight uploads and explicit XHR `action`
+or cancellable `customRequest`, controlled lists, accept/count limits and drag/drop.
+
+`App` hosts separate message and notification stacks. Use `App.useApp()` for the nearest context;
+exported `message`/`notification` use the last registered App and restore the prior host on unmount.
+
+Standalone Calendar and Timeline provide event calendars and chronological lists without Ship data dependencies.
+
+List (with ListItem and ListItemMeta), Listy and Masonry provide paginated lists, grouped fixed-height virtual lists, and measured responsive masonry layouts.
+
+Affix, Anchor, FloatButton (with FloatButtonGroup) and BackTop support scroll navigation and floating actions.
+
+Mentions provides native textarea suggestions; ColorPicker provides validated solid/gradient color editing, formats, alpha and presets.
+
+Carousel, Tour, QRCode, Watermark and BorderBeam add media navigation, guided steps, real QR encoding, repeated marks and perimeter decoration.
+
+DataTable supports hierarchical rows, grouped headers, multi-column sorting, radio selection and fixed-height virtual windows; see the component guide for summary scope and full-render fallbacks.
+
+DatePicker supports ISO periods, local datetime confirmation, multiple dates, lazy presets and strict display formats; DateRangePicker shares date/time constraints and atomic tuple presets.
+
+ConfigProvider supports nested `locale`, `direction`, `disabled`, `theme` and Klun CSS `tokens`; portalled overlays retain this configuration. See [configuration behavior](docs/components.md).
+
+Avatar supports numeric sizes, square shapes and measured text scaling; AvatarStack names hidden members in its overflow marker. See [component contracts](docs/components.md).
+
+Card exposes `Card.Grid` / `Card.Meta` (also `CardGrid` / `CardMeta`) for responsive content composition.

package/RELEASING.md

@@ -0,0 +1,51 @@
+# Releasing
+
+All releases and deployments must run through the Klun platform workflow:
+**build → approval → publish → deploy**. Local commands are for validation and
+artifact inspection. Never replace the workflow with `kc deploy`, a direct local
+npm publish, or manual cluster changes. If a workflow fails, fix it and rerun it.
+
+## Prepare the change
+
+1. Commit the code, tests, generated docs and release notes.
+2. Choose a version: patch for compatible fixes, minor for additive components or
+   props, major for breaking API changes. While 0.x, a breaking minor still needs
+   an explicit migration note.
+3. Update `package.json` and move the applicable `CHANGELOG.md` entries from
+   `Unreleased` into `## [x.y.z] — YYYY-MM-DD`.
+4. Run `pnpm verify` and `pnpm build:storybook` locally. For an already dated
+   version, `pnpm release x.y.z --dry-run` performs local validation only. It does
+   not commit, tag, publish, deploy, or call the platform.
+
+## Platform workflow
+
+Configure the workflow on the platform for this repository and environment.
+The repository does not contain an environment-specific platform workflow ID or
+registry credentials; those must come from the platform configuration.
+
+| Stage    | Required behavior                                                                                                                                                                                                                                   |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Build    | Check out the selected commit on a connected build runner. Install with `pnpm install --frozen-lockfile`, then run `pnpm verify` and `pnpm build:storybook`. Store the npm tarball, Storybook bundle and check results as run artifacts.            |
+| Approval | Review the exact commit, version, release notes, validation results and artifact before allowing publication.                                                                                                                                       |
+| Publish  | Publish the approved artifact to the registry configured on the platform, using platform-managed credentials. Record its version, checksum and source commit; create the release tag through this workflow.                                         |
+| Deploy   | Deploy the approved Storybook artifact or consuming application through the workflow when there is a deployment target. An npm package has no cluster deployment of its own; record that stage as not applicable when only the package is released. |
+
+Runner selection is declared through the platform's build-runner node and its
+connections. Approval must precede publication and deployment. Retrying uses the
+same reviewed commit; a different commit requires a new reviewed run.
+
+## Local safeguards
+
+`pnpm release` rejects invocations without `--dry-run`. The script only validates;
+it contains no commit, tag or publication path. `pnpm pack` is safe for inspecting
+a local artifact. `prepublishOnly` runs `pnpm verify` as an additional package
+check; it cannot authenticate platform approval, so approval enforcement belongs
+to the platform and its registry credentials.
+
+## Recovery
+
+Repair failed workflow steps and rerun the workflow. Roll back a deployed site or
+consumer by selecting its prior approved artifact in the platform workflow. Do
+not overwrite an existing npm version; publish a new corrected version through
+a new approved run. Keep the run ID, approval, logs and artifact checksums with
+the release record.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# Third-party notices
+
+@rc-component/qrcode 2.0.0 is bundled for SVG/canvas QR encoding.
+
+The MIT License (MIT)
+Copyright (c) 2015-present Alipay.com, https://www.alipay.com/
+
+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.
+
+The bundled QR Code generator also carries Copyright (c) Project Nayuki (MIT License).
+The MIT permission and disclaimer above apply to that code.
+
+## @babel/runtime helpers
+
+MIT License
+
+Copyright (c) 2014-present Sebastian McKenzie and other 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.