@brightspot/ui 1.11.0 → 3.0.1-cms-ui-migration.0

package/dist/util/upload.js

@@ -0,0 +1,113 @@
+import { l10n } from './i18n.js';
+/**
+ * Validate a File against an `accept` attribute string, matching the HTML
+ * `<input accept>` attribute format. Client-side filter only — server-side
+ * validation is still required.
+ *
+ * Supported forms (comma-separated, any combination):
+ * - `image/*` — MIME wildcard (any image)
+ * - `application/pdf` — exact MIME type
+ * - `.pdf`, `.docx` — file extension (case-insensitive)
+ *
+ * Examples:
+ * - `matchesAccept(file, "image/*")` — any image
+ * - `matchesAccept(file, "image/*,application/pdf")` — images and PDFs
+ * - `matchesAccept(file, ".jpg,.jpeg,.png,.heic")` — specific extensions
+ * - `matchesAccept(file, "")` — allow all (returns true)
+ *
+ * Note: users can bypass the file picker's filter (most browsers offer an
+ * "All Files" option), so this function is a UX filter, not a security
+ * boundary.
+ */
+export function matchesAccept(file, accept) {
+    if (!accept || !accept.trim())
+        return true;
+    const types = accept
+        .split(',')
+        .map(t => t.trim().toLowerCase())
+        .filter(Boolean);
+    const fileMime = file.type.toLowerCase();
+    const fileName = file.name.toLowerCase();
+    return types.some(type => {
+        if (type.startsWith('.')) {
+            return fileName.endsWith(type);
+        }
+        if (type.endsWith('/*')) {
+            const category = type.slice(0, type.indexOf('/'));
+            return fileMime.startsWith(category + '/');
+        }
+        return fileMime === type;
+    });
+}
+/**
+ * Validate a File's size against a maximum byte limit.
+ * Returns false if file exceeds `maxSize` bytes.
+ * Returns true if `maxSize` is 0 (unlimited).
+ */
+export function validateFileSize(file, maxSize) {
+    if (maxSize <= 0)
+        return true;
+    return file.size <= maxSize;
+}
+/**
+ * Resolve a MIME type to a Lucide icon symbol name.
+ *
+ * Mappings:
+ * - `image/*` → `'image'`
+ * - `video/*` → `'film'`
+ * - `audio/*` → `'music'`
+ * - document types → `'file'`
+ * - everything else → `'upload-cloud'`
+ */
+export function resolveFileSymbol(mimeType) {
+    if (!mimeType)
+        return 'upload-cloud';
+    const mime = mimeType.toLowerCase();
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('video/'))
+        return 'film';
+    if (mime.startsWith('audio/'))
+        return 'music';
+    if (mime.startsWith('text/') ||
+        mime === 'application/pdf' ||
+        mime === 'application/msword' ||
+        mime.startsWith('application/vnd.openxmlformats')) {
+        return 'file';
+    }
+    return 'upload-cloud';
+}
+/**
+ * Format a byte count to a human-readable file size string.
+ *
+ * Output format: `"200 KB"`, `"4.2 MB"`, `"16 MB"`, `"1.3 GB"`
+ * Uses `l10n()` for unit labels.
+ *
+ * Thresholds:
+ * - 0 bytes → `"< 1 KB"`
+ * - < 1 KB → `"< 1 KB"` (sub-KB files render the same)
+ * - < 1 MB → whole number KB
+ * - < 1 GB → one decimal MB
+ * - >= 1 GB → one decimal GB
+ */
+export function formatFileSize(bytes) {
+    const KB = 1024;
+    const MB = KB * 1024;
+    const GB = MB * 1024;
+    if (bytes < KB) {
+        return l10n('upload', 'sizeSubKB', '< 1 KB');
+    }
+    if (bytes < MB) {
+        const kb = Math.round(bytes / KB);
+        return `${kb} ${l10n('upload', 'unitKB', 'KB')}`;
+    }
+    if (bytes < GB) {
+        const mb = bytes / MB;
+        const formatted = mb >= 10 ? Math.round(mb).toString() : mb.toFixed(1);
+        return `${formatted} ${l10n('upload', 'unitMB', 'MB')}`;
+    }
+    const gb = bytes / GB;
+    const formatted = gb >= 10 ? Math.round(gb).toString() : gb.toFixed(1);
+    return `${formatted} ${l10n('upload', 'unitGB', 'GB')}`;
+}
+//# sourceMappingURL=upload.js.map

package/dist/util/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../src/util/upload.ts"],"names":[],"mappings":"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"}

package/docs/adr/0001-retire-cms-ui-package-fold-under-src-legacy.md

@@ -0,0 +1,78 @@
+# 1. Retire `@brightspot/cms-ui`; fold cms-ui under `@brightspot/ui` `src/legacy/tool-ui/`
+
+Date: 2026-05-18
+Status: Accepted
+
+## Context
+
+The earlier migration plan (Phases 0–2, committed on branch `feat/cms-ui-migration`)
+extracted brightspot's `cms/tool-ui/` frontend into a new npm sub-package
+`@brightspot/cms-ui` at `cms/`, registered with release-please as a separate
+track, with brightspot's gradle wrapper consuming it via `yarn link`. Phase 4
+(Vite swap) was attempted then reverted on 2026-05-13. `@brightspot/cms-ui@0.1.0`
+was scaffolded in-repo but was **never published to npm**.
+
+Maintaining two npm packages for two related code surfaces has cost: separate
+release-please track, separate `cms-ui/v*` tag stream, separate CI publish
+flow, separate `package.json` to maintain, separate `yarn link` target for the
+brightspot consumer. The cms-ui surface is also slated for retirement
+short-term (cms-ui's v4 entry is on a removal path; v5 will eventually follow
+or be rewritten in the modern stack).
+
+## Decision
+
+- Retire the `@brightspot/cms-ui` npm package name. Drop its release-please
+  track. Never publish it.
+- Move the cms-ui source tree to `src/legacy/tool-ui/` inside the
+  `@brightspot/ui` repo.
+- `@brightspot/ui` becomes the single published npm package for both the
+  modern design-system surface (`dist/`) and the legacy cms-ui webpack output
+  (`src/legacy/tool-ui/src/main/webapp/dist/`).
+- The directory marker `legacy` is load-bearing — tooling carve-outs (tsc,
+  storybook, conventions, prettier, root eslint) scope around `src/legacy/**`.
+
+## Consequences
+
+### Positive
+
+- One published artifact. Consumers pull one tarball. The brightspot consumer's
+  `yarn link` target changes from `@brightspot/cms-ui` to `@brightspot/ui`,
+  but the file paths it reads stay structurally similar.
+- One release-please track. No more `cms-ui/v*` tag stream, no separate
+  publish step.
+- `@brightspot/cms-ui` was never on npm, so retirement is free —
+  no deprecation, no migration period.
+- `cms-ui/` retirement when v4 (and eventually v5) leaves becomes a directory
+  delete, not a package deprecation.
+
+### Negative
+
+- `@brightspot/ui` 3.x consumers who never touch cms-ui still pull a tarball
+  with the legacy webpack output. Bloat is temporary — disappears as v4/v5
+  retire.
+- Any commit touching `src/legacy/tool-ui/` drives `@brightspot/ui` version
+  bumps. CHANGELOG includes cms-ui entries during the retirement window.
+  Acceptable given the limited duration.
+- Forced dep convergence at install time for some packages
+  (TypeScript, prettier, tailwindcss, Lit) — addressed by ADR-0002 via yarn
+  workspaces.
+
+### Cross-repo follow-on
+
+- `brightspot/cms/tool-ui/build-css.mjs` updates its file-read path from
+  `node_modules/@brightspot/cms-ui/legacy/tool-ui/src/main/webapp/dist/`
+  to `node_modules/@brightspot/ui/src/legacy/tool-ui/src/main/webapp/dist/`.
+- `brightspot/cms/tool-ui/package.json` declares `@brightspot/ui` as the
+  consumer dep (yarn-linked during HITL, registry dep at publish time).
+
+## Alternatives considered
+
+1. **Keep two packages, source under one repo.** Source moves but release-please
+   still cuts both. Rejected — preserves two release streams and two CHANGELOGs
+   for code on a retirement path; the cost we want to remove stays.
+2. **Subpath export (`@brightspot/ui/cms`).** Rejected — the brightspot
+   consumer reads files via filesystem in `build-css.mjs`, not via ESM imports.
+   `exports` subpaths don't add value for this consumption pattern.
+3. **Leave cms-ui at `cms/` as today.** Rejected — the user wants the source
+   under `src/` for navigability and as a step toward eventual integration with
+   the modern surface.

package/docs/adr/0002-yarn-workspaces-preserve-cms-ui-deps.md

@@ -0,0 +1,130 @@
+# 2. Use a postinstall hook (not yarn workspaces, not dep convergence) to preserve cms-ui's pin set
+
+Date: 2026-05-18
+Status: Accepted
+
+> **Revision note (2026-05-18, mid-fold)**: Originally accepted as
+> "use yarn workspaces." Reversed during commit #3 implementation after
+> discovering yarn 1's workspaces require `"private": true` on the host
+> project, which would block `npm publish` on `@brightspot/ui` without
+> a publish-pipeline overhaul (clean-publish swap or
+> prepack/postpack lifecycle gymnastics). The independent-install
+> approach below achieves the same goal (preserve cms-ui's pin set with
+> zero cross-contamination) without touching the publish pipeline.
+
+## Context
+
+ADR-0001 folds cms-ui under `@brightspot/ui`'s `src/legacy/tool-ui/`. The two
+codebases have meaningfully different dep stacks:
+
+| Dep | `@brightspot/ui` root | cms-ui (today's `cms/`) |
+|---|---|---|
+| TypeScript | 5.9.3 | ^4.7.3 |
+| Lit | ^3.3.0 | ^2.2.6 |
+| Prettier | ^3.2.5 (8.x in practice) | 3.2.5 (pinned via `resolutions`) |
+| Tailwindcss | peer ^3.4.x (19.x in practice) | 3.4.13 (pinned via `resolutions`) |
+| `@brightspot/ui` | n/a (self) | 1.2.0 (legacy tailwind preset source) |
+| Module type | `"type": "module"` (ESM) | unset (commonjs default) |
+
+These cannot share a single hoisted `node_modules` without breaking either the
+modern surface (downgrading Lit/TS) or bundle equivalence with brightspot's
+production tool-ui build (the acceptance criterion in ADR-0003 requires
+byte-identical webpack inputs).
+
+## Decision
+
+- `src/legacy/tool-ui/` is a **standalone yarn-1 subproject** with its own
+  `package.json` (`"private": true`), `yarn.lock`, and `node_modules` tree.
+- The workspace `package.json` mirrors today's `cms/package.json` (same deps,
+  same `resolutions`, no `"type"` field so it defaults to commonjs).
+- Root `package.json` has a `postinstall` script that runs
+  `cd src/legacy/tool-ui && yarn install`, so a single root `yarn install`
+  produces both installs in sequence.
+- The published `@brightspot/ui` tarball includes the workspace's webpack
+  output via the root `files` field; the workspace `package.json` itself
+  is not in the tarball.
+- Build orchestration: root `yarn build` stays modern-only (preserves design-
+  system iteration speed). `prepack` extends to also invoke
+  `cd src/legacy/tool-ui && yarn build`, so any `npm pack` / publish always
+  contains both surfaces.
+- Local cms-ui dev story is preserved: `cd src/legacy/tool-ui && yarn build`
+  works identically to today's `cd cms/legacy/tool-ui && yarn build`, minus
+  the `cd` shim Phase 1 had to add.
+
+## Consequences
+
+### Positive
+
+- Bundle equivalence is achievable (see ADR-0003) because cms-ui's exact
+  toolchain (TS 4.7, Lit 2.2.6, babel, webpack 5, loaders) is preserved at
+  install time. Module resolution from `src/legacy/tool-ui/` walks the local
+  `node_modules` first and finds the pinned versions.
+- ESM/commonjs isolation comes for free: each project has its own
+  `package.json` and `node_modules`.
+- No publish-pipeline changes needed. `@brightspot/ui` stays unprivate; CI's
+  bare `npm publish` continues to work.
+- `@brightspot/ui@1.2.0` (the legacy tailwind preset source) installs cleanly
+  into the workspace's `node_modules/@brightspot/ui/` from the npm registry —
+  no self-reference conflict with the host project, since yarn workspace
+  semantics aren't engaged.
+- cms-ui's local-dev workflow is unchanged (slightly cleaner — drops the
+  Phase 1 `cd legacy/tool-ui &&` script prefix once commit #4 lands).
+- Future retirement is a directory delete + remove the postinstall hook,
+  not a complex unwind.
+
+### Negative
+
+- Two `package.json` files in the repo (root + workspace). Slight cognitive
+  overhead vs a single converged manifest. Mitigation: workspace `package.json`
+  is structurally a near-copy of today's `cms/package.json`, so it's not new
+  surface.
+- Two `yarn.lock` files (root + workspace). Same arrangement as Phase 1 had
+  pre-fold; no new burden.
+- Two `node_modules` trees. The ~12 deps that genuinely overlap between root
+  and workspace (loglevel, tabbable, broadcast-channel, uuid, webpack,
+  ts-node, css-loader, mini-css-extract-plugin, postcss-import, postcss-loader,
+  style-loader, webpack-cli, webpack-merge) install in both. Disk overhead
+  ~100MB, dwarfed by cms-ui's own heavy deps.
+- Root `yarn install` becomes slower (cms-ui's heavy install runs too).
+  Mitigation: matches Phase 1's pre-fold total cost; design-system contributors
+  who never edit cms-ui still incur it. Acceptable for the retirement window.
+- Workspace deps aren't visible to `yarn workspace <name> <cmd>` ergonomics
+  (those commands need yarn workspaces). Mitigation: `cd src/legacy/tool-ui &&
+  yarn <cmd>` works fine — matches Phase 1.
+- The webpack `nodeModulesPath` in `src/legacy/tool-ui/webpack.common.ts` —
+  used to resolve vendored static assets like `lucide-static` and
+  `iframe-resizer` — must point at `src/legacy/tool-ui/node_modules`.
+  Verified empirically in commit #4.
+
+## Alternatives considered
+
+1. **Yarn 1 workspaces (originally accepted, then reversed).**
+   Hits the `"private": true` constraint on the host project. Would require:
+   - Adding `"private": true` to `@brightspot/ui`'s root, AND
+   - Reworking CI's `npm publish` step (clean-publish, prepack swap, or
+     two-file `package.json` / `package.publish.json` pattern).
+
+   Yarn 1 workspaces' main benefit — hoisting deps shared by root and
+   workspace — would save ~100MB of disk for ~12 deps. The cost of the
+   publish-pipeline rework outweighs that gain for retirement-pending code.
+   Rejected.
+
+2. **Yarn 4 / Yarn Berry / pnpm workspaces.**
+   Yarn 4 doesn't require host-project `"private": true` for workspaces.
+   Migrating the repo away from yarn 1 is a worthwhile initiative but
+   explicitly out of scope for this fold. Tracked separately if cms-ui
+   retirement timeline extends.
+
+3. **Converge to brightspot-ui's modern pins; fix what breaks.**
+   Rejected. Lit 2 → Lit 3 emit-byte differences would cascade through
+   every v5 module. Bundle equivalence becomes unachievable; confidence
+   relies on functional/Playwright testing only.
+
+4. **Aliased dual install (`lit` + `lit-2`).**
+   Rejected. Requires rewriting hundreds of `import … from 'lit'` statements
+   in cms-ui source to `'lit-2'`. Bytes diverge anyway because import
+   specifiers differ. Cost without the benefit.
+
+5. **cms-ui's pins win at root (no subproject).**
+   Rejected. Downgrades `@brightspot/ui`'s modern stack (Storybook 10,
+   vitest 4, Lit 3 features in use today) — regression on the stable surface.

package/docs/adr/0003-bundle-equivalence-as-fold-acceptance-criterion.md

@@ -0,0 +1,286 @@
+# 3. Bundle equivalence as the fold's acceptance criterion
+
+Date: 2026-05-18
+Status: Accepted (with near-equivalence revision)
+
+> **Revision note (2026-05-18, end of fold):** Strict 100% bundle
+> equivalence is **not achievable** without reverting Phase 1's
+> package.json deviations (which would re-break the workspace as a
+> standalone subproject). Final state after commit #6's verify run
+> shows targeted, harmless divergences:
+>
+> - `core-js`: workspace 3.49.0 vs golden 3.36.0 (workspace's fresh
+>   `yarn install` resolved this transitive differently from brightspot's
+>   lockfile). Causes ~150 extra/missing core-js polyfill modules in the
+>   stats diff and downstream license-sidecar content drift on `v4.js`
+>   and `v5.js`. Polyfill semantics are identical for the
+>   browsers cms-ui targets; the diff is purely byte-level.
+> - `iframeResizer.contentWindow.min.js`: byte diff between the two
+>   `iframe-resizer@4.3.8` installations. Same functional content.
+> - `v5.css`: ~5 KB diff (~0.1%) downstream of the core-js shift through
+>   babel polyfill inclusion. The brightspot Java content extraction
+>   (commit #5) closed the original 153 `\!frame` selectors gap that was
+>   the headline Phase 1 divergence.
+>
+> The verify script (commit #6) ships as a one-shot diagnostic, not a
+> CI gate. Future cms-ui changes will drift further; bundle equivalence
+> stops being a useful signal once intentional changes accumulate. The
+> brightspot consumer's correctness depends on the same v3-era babel +
+> webpack toolchain and the same runtime semantics, both preserved.
+
+## Context
+
+The fold (ADR-0001) relocates cms-ui from `cms/legacy/tool-ui/` to
+`src/legacy/tool-ui/` and replaces the separate `@brightspot/cms-ui` npm
+package with a yarn-workspace surface inside `@brightspot/ui` (ADR-0002).
+
+The cms-ui webpack output is consumed downstream by brightspot's gradle
+wrapper (`brightspot/cms/tool-ui/build-css.mjs`), which reads JS bundles
+off disk, passes them through to the running CMS, and regenerates CSS
+locally with brightspot's Java content paths visible (Phase 2 commit
+`afa31ba572a`). The browser runs whatever webpack emitted.
+
+The user's stated top concern for the fold is confidence that the post-fold
+build is **backward-compatible with brightspot's currently-running production
+tool-ui build**. The most trustworthy signal for that, available without
+standing up a Playwright matrix, is byte-equivalence of the emitted webpack
+bundles.
+
+Phase 1's `verify-bundle-equivalence.mjs` measured cms-ui (built from `cms/`)
+against brightspot's pre-migration tool-ui at SHA `28876f4e9f6` and reported
+99.96% module-source match: **2450/2451 module sources byte-identical,
+1/4 CSS chunks byte-identical**. Both divergences (1 module + 3 CSS chunks)
+trace to the same cause: tailwind's `content:` paths in
+`tailwind.config.ts` point at 16 brightspot Java sources via `../../cms/db/.../CmsTool.java`-
+style relative paths. From brightspot's own `cms/tool-ui/` those files resolve;
+from cms-ui's location in brightspot-ui they don't, so tailwind silently
+skips them, fewer utilities are generated, and the entry module that
+imports the resulting CSS chunk diverges.
+
+## Stale-dist self-perpetuation (2026-05-18 finding)
+
+During initial golden generation we discovered that cms-ui's webpack build
+emits **different `v5.css` bytes depending on prior `dist/` state**, even with
+identical source, lockfile, and node_modules.
+
+Root cause: `clean-webpack-plugin` v4 runs its `cleanOnceBeforeBuildPatterns`
+in webpack's `emit` hook — **after** tailwind's PostCSS pass has already
+scanned content. Tailwind's `content:` glob `./src/**/*.css` matches
+`src/main/webapp/dist/*.css`, so the *previous* build's emitted CSS gets
+re-scanned, and class candidates inside it (orphan selectors like
+`.btu-button-current` that no source file references anymore) get re-emitted
+into the new build. The cycle is self-perpetuating: once a class enters
+`v5.css`, it stays.
+
+Two stable build modes result:
+
+| Mode | Hash at SHA `28876f4e9f6` | What it represents |
+|---|---|---|
+| **Cold** | `v5.8acae93faec68b445941.css` | Fresh build with empty `dist/`. What clean CI runs produce. |
+| **Warm** | `v5.b665f7f237580883575e.css` | Build with prior `dist/` present. What ran locally during ongoing development. Includes ~12+ orphan rules (~5KB). |
+
+Both are deterministic given their starting state. JS bundles (`v4.js`, `v5.js`,
+`preview.js`) and `v4.css` are byte-identical across modes — only `v5.css`
+differs. Orphans don't affect rendering (no DOM uses them) but they
+materially affect bundle-equivalence comparisons.
+
+This is **a latent bug in cms-ui's webpack pipeline**, independent of the
+fold. A clean fix (e.g., switching CleanWebpackPlugin to run in `beforeRun`,
+or excluding `dist/` from tailwind's content glob) is tracked as a follow-on
+to the fold itself.
+
+For the fold we **capture both goldens** and defer the cold-vs-warm
+selection to comparison time, once we have evidence on what brightspot's
+production CI actually emits.
+
+## Decision
+
+The fold is "done" when **the post-fold build matches the chosen golden
+(cold or warm — see "Stale-dist self-perpetuation" above) at 100%** across
+the script's gated buckets:
+
+| Bucket | Target |
+|---|---|
+| Module source bodies | 100% (after path normalization) |
+| Static-copy assets | 100% byte (`lucide.woff2`, `iframeResizer.contentWindow.min.js`, `iframeResizer.contentWindow.map`) |
+| License sidecars — named-entry | 100% content (v4/v5/preview) |
+| License sidecars — chunk-numbered | content set equal (renumbering tolerated) |
+| CSS chunks | 100% byte (after hash strip) |
+
+The script's overall pass criterion is **all of the above with zero
+mismatches** — the same `ok = …` predicate Phase 1's script already
+enforces. We are no longer accepting Phase 1's "1 module + 3 CSS chunks"
+as documented exceptions; we resolve them.
+
+### Resolving the Java content visibility
+
+Both Phase 1 divergences resolve when tailwind sees the 16 Java content
+paths. The fold uses **pre-extraction into the existing
+`src/legacy/tool-ui/src/additional-tailwind-classes.txt`** (currently 62
+lines, listing utilities tailwind's content scanner can't otherwise detect).
+
+Process during the fold:
+
+1. From brightspot at SHA `28876f4e9f6`, run tailwind against the 16 Java
+   files in isolation and capture the set of utilities generated.
+   Equivalent procedure: scan the 16 Java files with the same regex tailwind
+   uses for content extraction and capture the candidate class strings.
+2. Append the resulting class list to
+   `src/legacy/tool-ui/src/additional-tailwind-classes.txt`, deduplicated.
+3. Delete the 16 Java content paths from
+   `src/legacy/tool-ui/tailwind.config.ts` (they don't resolve from the new
+   location anyway). The text file is now the single source of truth.
+4. Re-run the fold's webpack build. Diff against the brightspot golden via
+   `verify-bundle-equivalence.mjs`. Expect 100%.
+
+Drift management: if the brightspot platform team adds a new tailwind
+utility in those Java files, the cms-ui side must regenerate. A
+regeneration script (one of the fold's deliverables) supports this.
+
+### Golden workflow — dual capture
+
+Both goldens are captured during fold validation. The cold-vs-warm
+selection happens at comparison time, informed by what brightspot's CI
+actually emits.
+
+```bash
+# 1. Cold golden — fresh worktree, no prior dist
+cd ~/work/brightspot
+git worktree add .worktrees/cms-ui-golden 28876f4e9f6
+cd .worktrees/cms-ui-golden/cms/tool-ui && yarn install
+npx webpack --config webpack.build.ts --json > /tmp/build-stats-source-cold.json
+cp -R src/main/webapp/dist /tmp/cms-ui-golden-cold
+
+# 2. Warm golden — same worktree, the cold dist now seeds tailwind's
+# scan for the next build
+npx webpack --config webpack.build.ts --json > /tmp/build-stats-source-warm.json
+cp -R src/main/webapp/dist /tmp/cms-ui-golden-warm
+
+# 3. Build the fold candidate
+cd ~/work/brightspot-ui
+git checkout <fold-branch>
+yarn install
+yarn workspace <legacy-workspace-name> build --json > /tmp/build-stats-target.json
+
+# 4. Compare against COLD first
+node scripts/verify-bundle-equivalence.mjs \
+  /tmp/build-stats-source-cold.json \
+  /tmp/build-stats-target.json \
+  /tmp/cms-ui-golden-cold \
+  src/legacy/tool-ui/src/main/webapp/dist
+
+# 5. If cold passes: done. If cold fails and brightspot CI builds warm,
+# rerun against warm:
+node scripts/verify-bundle-equivalence.mjs \
+  /tmp/build-stats-source-warm.json \
+  /tmp/build-stats-target.json \
+  /tmp/cms-ui-golden-warm \
+  src/legacy/tool-ui/src/main/webapp/dist
+```
+
+Acceptance: script exits 0 against the **chosen golden** (cold or warm).
+Any non-zero exit is investigated and root-caused before merge.
+
+### CI build state — investigated 2026-05-18
+
+**Brightspot CI builds COLD.** The cold golden is production-faithful.
+
+Evidence from brightspot's `.github/workflows/ci.yml`:
+
+- `actions/checkout@v4` with `fetch-depth: 0` (line 28–30): every CI run
+  starts from a fresh git working tree. No persistence of `cms/tool-ui/src/main/webapp/dist/`
+  between runs.
+- `gradle/actions/setup-gradle@v4` with `cache-read-only` flag (line 38–41):
+  caches `~/.gradle/caches`, not the project working tree. Read-write on
+  `release/*`, read-only on PRs.
+- `./gradlew build` (line 49): drives `:cms-tool-ui:yarnBuild`.
+
+`cms/tool-ui/build.gradle` at SHA `28876f4e9f6`:
+
+```
+task yarnBuild(type: YarnTask) {
+    outputs.dir 'src/main/webapp/dist'
+    outputs.cacheIf { true }
+    args = ['build']
+}
+```
+
+Behavior:
+
+- **Cache hit** — gradle restores `src/main/webapp/dist/` from the gradle
+  build cache and **skips** the yarn build entirely. Webpack does not run.
+  The restored bytes are whatever the most recent cache-pushing run emitted.
+- **Cache miss** — gradle invokes the task. `yarn build` runs against a
+  fresh checkout's empty `src/main/webapp/dist/`. **Cold build.**
+
+The cache is populated by builds on `release/*` branches (the only ones with
+write access). The first build at any given input-hash set is a cache miss
+on a fresh checkout — therefore cold. Subsequent cache hits restore that
+cold output. Cold propagates; warm cannot enter the cache without manual
+intervention (which would require pre-existing `dist/` in a fresh checkout,
+impossible by construction).
+
+**Implication for the fold:** the cold golden (`v5.8acae93faec68b445941.css`)
+is the production-faithful baseline. The warm golden's orphan classes are a
+local-dev quirk and do not reach production. We retain the warm capture for
+diagnostic purposes only.
+
+**Stale-dist follow-on:** the underlying tailwind/clean-webpack-plugin
+ordering bug should be fixed independently of the fold, so future cms-ui
+builds become deterministic regardless of prior `dist/` state.
+
+### Ongoing CI gate
+
+**Bundle equivalence is a one-time fold validation, not an ongoing CI
+gate.** Once the fold lands, intentional cms-ui changes will drift from
+brightspot's pinned SHA, and the comparison becomes stale. Future
+correctness depends on workspace-local Playwright tests and brightspot
+consumer smoke.
+
+### Adjacent acceptance criteria (non-bundle)
+
+1. **Modern surface integrity** — root `yarn build`, `yarn check:conventions`,
+   `yarn build-storybook`, `yarn test:storybook` all pass; `npm pack --dry-run`
+   from root contains both `dist/**` and `src/legacy/tool-ui/src/main/webapp/dist/**`.
+2. **Consumer end-to-end** — `yarn link @brightspot/ui` from brightspot's
+   `cms/tool-ui/` succeeds; `./gradlew :cms-tool-ui:yarnBuild` runs cleanly;
+   docker at `https://localhost:8080/cms/` serves v4 + v5 with zero console
+   errors; ProseMirror RTE loads; manual smoke (login → dashboard → create
+   content) passes.
+3. **Workspace-local dev** — `cd src/legacy/tool-ui && yarn build|server:local|test|lint:*`
+   all succeed.
+
+## Consequences
+
+### Positive
+
+- Production-faithful confidence: the fold output matches what brightspot
+  ships today, byte for byte across all gated buckets.
+- Single source of truth for tailwind-classes-not-in-source moves to the
+  text file; eliminates dead-weight Java content paths in `tailwind.config.ts`.
+- Phase 1's verify machinery is reusable — restored from history, pointed at
+  the brightspot-built golden.
+
+### Negative
+
+- Drift maintenance: if brightspot's Java files gain new tailwind utilities,
+  someone has to regenerate the text file. Mitigation: a regeneration script
+  ships with the fold; platform-team awareness needed for new utility usage.
+- Heavier golden generation: requires a brightspot checkout and build, not
+  just an in-repo build. One-time per validator.
+
+## Alternatives considered
+
+1. **Build golden in brightspot-ui (Option Y).** Both pre-fold and post-fold
+   built in brightspot-ui's repo, where Java paths don't resolve. 100%
+   achievable trivially, but the bar is "match the package we're retiring"
+   rather than "match brightspot's actual production output." Rejected on
+   production-fidelity grounds.
+2. **Accept Phase 1's 99.96% as the bar.** Rejected — the user explicitly
+   asked for 100%. Resolvable via the Java-extraction step at one-time cost.
+3. **Build-time extraction via `BRIGHTSPOT_REPO_PATH` env var.** Higher
+   fidelity (always in sync with brightspot's current Java) but adds a
+   build-step dependency. Rejected for fold-time simplicity in favor of
+   pre-extraction; can revisit if drift becomes painful.
+4. **Build cms-ui from inside brightspot (invert Phase 2).** Most faithful
+   but heavy coupling. Rejected.

package/docs/components/ActionBar.md

@@ -27,6 +27,12 @@
 | `label`     |         | `string`    | `''`        | Accessible label for the toolbar region.                                                                                                                                                                        |                |
 | `compact`   |         | `boolean`   | `false`     | Enables progressive label compacting. When space shrinks, items marked
\`compactable\` (with icons) have their labels hidden one-by-one
from least to most important before items overflow into "More". |                |
 
+### Methods
+
+| Name   | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
+| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
+| `emit` |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |
+
 ### Events
 
 | Name                    | Type                           | Description                                                         | Inherited From |