@brightspot/ui 3.0.1-cms-ui-migration.3 → 3.0.1-cms-ui-migration.4

package/dist/storybook/assets/if-defined-DaMmbcIU.js

@@ -1 +0,0 @@
-import{E as r}from"./iframe-CQArUhO8.js";const m=o=>o??r;export{m as o};

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

@@ -1,78 +0,0 @@
-# 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

@@ -1,130 +0,0 @@
-# 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

@@ -1,286 +0,0 @@
-# 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.