derico.blicca.promoblock 1.0.0a1__tar.gz

derico_blicca_promoblock-1.0.0a1/.copier-answers.yml

@@ -0,0 +1,14 @@
+# Do not edit this file manually.
+# This file is auto-generated by Copier.
+# Changes here will be overwritten when you update the template.
+_src_path: /home/dev/.copier-templates/plone-copier-templates/backend_addon
+author_email: md@derico.de
+author_name: Maik Derstappen
+github_organization: derico-de
+is_headless: false
+package_description: 'Aurora Promo block: an authored promo card with kicker, title,
+    description, image and calls to action'
+package_name: derico.blicca.promoblock
+package_title: Derico Blicca Promoblock
+plone_version: '6.0'
+

derico_blicca_promoblock-1.0.0a1/.editorconfig

@@ -0,0 +1,21 @@
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4
+
+[*.{cfg,ini,toml}]
+indent_size = 4
+
+[*.{xml,zcml,html,pt,zpt}]
+indent_size = 2
+
+[*.{css,js,json}]
+indent_size = 2
+
+[*.{yml,yaml}]
+indent_size = 2

derico_blicca_promoblock-1.0.0a1/.github/workflows/ci.yml

@@ -0,0 +1,120 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      BLICCA_SSH_KEY: ${{ secrets.BLICCA_SSH_KEY }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      # plone.blicca.auroraeditor is PRIVATE and not on PyPI: it is the editor
+      # this block mounts in and the source of the rendering API the package
+      # imports, so without it nothing installs and nothing is tested. A
+      # missing key is a red job on purpose — a green run over a package
+      # that could not be installed says nothing. Use a read-only deploy key
+      # scoped to the host repository, not a personal access token.
+      - name: Require the host checkout key
+        if: env.BLICCA_SSH_KEY == ''
+        run: |
+          echo "::error::BLICCA_SSH_KEY is not set. This package depends on"
+          echo "::error::plone.blicca.auroraeditor, which is private and not"
+          echo "::error::on PyPI, so the tests cannot run."
+          exit 1
+
+      # pyproject resolves the sources below from `../<name>`, so this
+      # repository checks itself out into a subdirectory and its siblings land
+      # beside it, exactly as they sit under the site's `sources/`.
+      - uses: actions/checkout@v5
+        with:
+          path: derico.blicca.promoblock
+
+      - uses: actions/checkout@v5
+        with:
+          repository: derico-de/plone.blicca.auroraeditor
+          ssh-key: ${{ env.BLICCA_SSH_KEY }}
+          persist-credentials: false
+          path: plone.blicca.auroraeditor
+
+      - name: Set up uv and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run tests
+        working-directory: derico.blicca.promoblock
+        run: uv run --frozen --extra test pytest -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Run ruff
+        run: uvx ruff@0.16.6 check .
+
+  bundle:
+    # The editor half is committed build output — there is no Node on the
+    # deploy host (block add-on contract §3.1) — so nothing rebuilds it at
+    # install time and it rots the moment someone edits bundle-src/src/ and
+    # forgets. The `git diff --exit-code` below is what makes committing an
+    # artifact safe rather than merely convenient.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      # pnpm is pinned here rather than by a `packageManager` field in
+      # bundle-src/package.json: pnpm 12 answers that field by writing a
+      # `packageManagerDependencies` block into the lockfile — its own binary
+      # for every platform — and the lockfile is not the place for that.
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 12.3.4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: bundle-src/.nvmrc
+          cache: pnpm
+          cache-dependency-path: bundle-src/pnpm-lock.yaml
+
+      # `working-directory`, not `--dir`: the repository root has no
+      # package.json, and pnpm resolves the workspace from where it stands.
+      - name: Install
+        run: pnpm install --frozen-lockfile
+        working-directory: bundle-src
+
+      - name: Typecheck
+        run: pnpm typecheck
+        working-directory: bundle-src
+
+      - name: Build
+        run: pnpm build
+        working-directory: bundle-src
+
+      # After the build: the harness reads the built artifact.
+      - name: Test
+        run: pnpm test
+        working-directory: bundle-src
+
+      # If this fails, someone edited bundle-src/src/ and did not rebuild.
+      - name: The committed bundle is the one this source builds
+        run: git diff --exit-code -- src/derico/blicca/promoblock/static/

derico_blicca_promoblock-1.0.0a1/.gitignore

@@ -0,0 +1,97 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Type checkers / linters
+.mypy_cache/
+.pyre/
+.pytype/
+.ruff_cache/
+
+# Translations (compiled catalogs are generated; .pot/.po are tracked)
+*.mo
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs / editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Node / frontend tooling (themes, mockup patterns, svelte apps)
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnpm-store/
+.parcel-cache/
+.vite/
+
+# Build outputs from frontend tooling (in addition to top-level dist/)
+src/derico/blicca/promoblock/**/dist/
+src/derico/blicca/promoblock/**/.cache/
+
+# Plone / Zope runtime data
+*.fs
+*.fs.index
+*.fs.lock
+*.fs.tmp
+blobs/
+
+# Project specific
+*.log
+.DS_Store
+Thumbs.db

derico_blicca_promoblock-1.0.0a1/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

derico_blicca_promoblock-1.0.0a1/.scratch/promo-block/issues/01-research-image-widget-in-both-hosts.md

@@ -0,0 +1,181 @@
+# Research: does the host `image` widget behave in both hosts?
+
+Type: research
+Status: resolved
+Blocked by: —
+
+## Question
+
+The map fixes the image field as **named `image`, taking the host's own widget
+through field-id resolution**. That is a deliberate inversion of `derico-hero`'s
+rule and the single largest assumption in the content model. Confirm or break it
+before ticket 03 writes the schema.
+
+Read, don't guess. Sources: `@plone/cmsui/components/Form/Field.tsx` (resolution
+order), `@plone/cmsui/components/ImageWidget/ImageWidget.tsx` (upstream),
+`plone.blicca.auroraeditor/wrapper/src/widgets/ImageWidget.tsx` (the Blicca
+substitute), `@plone/blocks/Image/schema.tsx` (how Aurora's own image block
+declares its field).
+
+- **Resolution.** Confirm `getWidgetByFieldId('image')` really wins over an
+  explicit `widget:` key, and that both hosts register under exactly `image`.
+  If Blicca registers under a different key or category, the whole approach
+  falls over.
+- **Stored shape.** Upstream calls `onValueChange(result['@id'], extras)` — an
+  absolute `@id` string. Blicca writes `../resolveuid/${item.UID}` — a relative
+  path string. Same type, different form. Confirm both, and confirm neither ever
+  writes an array or an object, because the view and the template must accept
+  whatever comes.
+- **`image_scales` / `image_field`.** Upstream passes them as `extras` to
+  `onChange`, but Aurora's `dataAdapter` hook is **vestigial** (zero consumers),
+  so nothing may be catching them. Determine whether either host persists them
+  at all. If neither does, ticket 10's transformer is the only source and that
+  is fine — but it must be known, not assumed.
+- **`widgetOptions.pattern_options`.** Contract §1.5 says `selectableTypes` and
+  `upload` are read. Check whether the *host image widget* honours them, or only
+  `object_browser` does. If it ignores them, we lose "restrict to Image" and
+  need to decide whether that matters.
+- **The fallback.** If any of the above breaks, the alternative is the teaser's
+  idiom — `object_browser`, `mode: 'single'`, `selectableTypes: ['Image']`,
+  `upload: true`, under a field name that is *not* `image`. Say which, and what
+  it costs in native Aurora (where the Blicca upload substitution is absent).
+
+## Answer
+
+**Verdict: the assumption holds. Name the field `image` and it gets the host's
+own image widget in both hosts.** Every sub-question below was read off the
+source, not inferred. Two corrections to the map's reasoning and one new
+cross-host divergence came out of it.
+
+### 1. Resolution — confirmed, but for a different reason than the map assumed
+
+`components/Form/Field.tsx` (`renderFieldWidget`) resolves in this order:
+
+    getWidgetByFieldId(id ?? name)   <-- FIRST, unconditional
+    getWidgetFromTaggedValues(...)
+    getWidgetByName(widget)          <-- an explicit `widget:` key only gets here
+    getWidgetByChoices / ByVocabulary / ByVocabularyFromHint / ByFactory / ByType
+    getWidgetDefault()
+
+So yes — **field-id beats an explicit `widget:` key**, and a field named `image`
+can never have that resolution overridden from the schema.
+
+The key that resolution uses is the **schema property key**.
+`BlockSettingsFormRenderer.tsx` renders each field as
+`<field.Quanta {...schema.properties[key]} name={field.name} ... />` and passes
+no `id`, so `id ?? name` is the property key. Blicca imports that exact
+component (`plone-block-sidebar.tsx:14` imports upstream's `BlockSettingsForm`),
+so **the resolution path is byte-identical in both hosts** — there is no Blicca
+fork to diverge.
+
+**Correction to the map's stated mechanism.** The map says both hosts register
+`image` and implies category matters. It does not: `config.getWidget(key)`
+(`@plone/registry/dist/index.js:397`) **iterates every category and returns the
+first match by key**, so `id`/`widget`/`type`/`vocabulary`/`factory` are
+effectively one flat namespace. Both hosts in fact register `image` under
+category **`widget`**, not `id`:
+
+- upstream `cmsui/config/widgets.ts:41` — `{key:'widget', definition:{image: ImageWidget}}`
+- Blicca `wrapper/src/bootstrap/config.ts:47` — `{key:'widget', definition:{image: BliccaImageWidget}}`
+
+Field-id resolution finds them anyway. The conclusion is unchanged; the reason
+is. **Consequence worth writing into the code comment ticket 03 asks for:** the
+flat namespace is also why the map's `promo_textarea` / `promo_select`
+namespacing is safe *and* why it is necessary — one flat namespace across all
+categories means an unprefixed `textarea` really would collide ecosystem-wide.
+
+**Aurora's own image block does NOT use this idiom.** `blocks/Image/schema.tsx`
+names the field **`url`** with `widget: 'image'`. Both routes work; we are
+choosing the more robust one (field-id cannot be knocked out of first place),
+at the cost of not matching upstream's spelling. Take it deliberately — the map
+already says to comment it.
+
+### 2. Stored shape — always a bare string or `null`. Never an array, never an object.
+
+| host | write path | value written |
+|---|---|---|
+| Blicca | contentbrowser pick | `` `../resolveuid/${item.UID}` `` (relative), or `item['@id']` if no UID |
+| Blicca | clear | `null` |
+| upstream | object-browser pick | `selectedImage['@id']` — **absolute** |
+| upstream | file upload | `result['@id']` from `@createContent` — **absolute** |
+| upstream | **free-text link input** | any trimmed string the author types, or `null` |
+| upstream | clear | `null` |
+
+Neither host ever writes an array or an object. Upstream's `normalizeImageValue`
+does *read* `['@id']` and `[{'@id'}]` shapes tolerantly (legacy Volto defence),
+so tickets 09/10 should **accept** those on read while only ever **writing** a
+string.
+
+### 3. `image_scales` / `image_field` — neither host persists them. Ticket 10 is the only source.
+
+Confirmed on both sides, and the reason is the same on both:
+
+- `Field.tsx` wires `onChange={(value) => { fieldProps.onChange?.(value); onFieldChange(value); }}`
+  — **one argument. The `extras` second argument is dropped on the floor.**
+- Upstream's widget never had them to give: its extras are `{title}` only
+  (`onValueChange(result['@id'], {title})`). It never emits `image_scales` or
+  `image_field` at all.
+- Blicca's widget *does* pass `{title, image_field, image_scales}`, but through
+  that same discarded second argument.
+- Blicca's side-channel `patchSelectedImageBlock` writes them straight onto the
+  node — but `isImagePloneBlock()` gates on `node['@type'] === 'image'`, so for
+  `@type: 'promo'` **it is a no-op**. Good news twice over: nothing corrupts our
+  node, and nothing populates it either.
+
+So ticket 10's transformer pair is not merely "the only source" — it is
+load-bearing, and the block must render correctly from a bare URL string with no
+scales present at all.
+
+### 4. `widgetOptions.pattern_options` — ignored by the image widget in both hosts. No loss.
+
+Contract §1.5 is describing `object_browser`, not the image widget:
+
+- **upstream `ImageWidget`** takes `restrictFileUpload`, `hideLinkPicker`,
+  `hideObjectBrowserPicker`, `objectBrowserPickerType`, `imageSize`,
+  `uploadPath`, `currentPath` as **direct props**, and **hardcodes**
+  `pattern_options: { selectableTypes: ['Image'] }` in its own internal
+  `ObjectBrowserProvider`.
+- **Blicca `BliccaImageWidget`** hardcodes `selectableTypes={['Image']}` and
+  `upload` on its `PatternHost`.
+- `ObjectBrowserWidget` *is* the one that honours
+  `widgetOptions.pattern_options.selectableTypes` (`ObjectBrowserWidget/utils.ts:99-109`).
+
+**We lose nothing**: restrict-to-`Image` is what we wanted and both hosts do it
+unconditionally. We simply cannot *configure* it. Do not declare
+`widgetOptions.pattern_options` on the image field — it would be dead weight
+that reads as if it were doing something.
+
+**A live lever we do get instead:** `BlockSettingsFormRenderer` spreads
+`{...schema.properties[key]}` into the widget, so any key on the schema property
+arrives as a widget prop. Upstream-only props like `imageSize` or
+`hideLinkPicker` can therefore be set from the schema — harmlessly ignored by
+Blicca's widget, which does not read them.
+
+### 5. NEW — a cross-host value-space divergence the map had not anticipated
+
+This did not come from the four bullets but is the biggest thing the reading
+turned up, and it lands on tickets 09, 10 and 15:
+
+1. **Blicca writes relative, upstream writes absolute.** A promo authored in
+   Blicca stores `../resolveuid/<UID>`. Upstream's own preview helper is
+   `getPreviewSrc(url) = url.startsWith('/') ? url + '/@@images/image/<size>' : url`
+   — `../resolveuid/...` does **not** start with `/`, so **native Aurora would
+   render a Blicca-authored promo's image as a raw, broken `src`.** It is only
+   the editing preview, not the published page, but ticket 15 must expect it
+   rather than read it as a build error.
+2. **Upstream offers a free-text URL input; Blicca does not.** In native Aurora
+   an author can type an arbitrary external URL into the image field. So the
+   server renderer's link screening (the `path_of` / non-http item in the map's
+   constraints) is **not confined to the action links — the image field is a
+   second free-text surface**, reachable only from the native host. Ticket 09
+   should screen the image value too, not just the CTA hrefs.
+
+### Fallback — not needed, and it would cost more than it saves
+
+Recorded for completeness since the ticket asked. The `object_browser` /
+`mode:'single'` / `selectableTypes:['Image']` / `upload:true` idiom under a
+non-`image` field name is **worse in native Aurora**: upstream's
+`ObjectBrowserWidget` has **no upload at all** (the `upload` flag is Blicca's
+`PatternHost` extension; nothing upstream reads it). Choosing it would trade a
+working upload in both hosts for a picker that can only select pre-existing
+images in one of them. Stay with the field named `image`.

derico_blicca_promoblock-1.0.0a1/.scratch/promo-block/issues/02-research-exercising-native-aurora.md

@@ -0,0 +1,182 @@
+# Research: how do we exercise the block in native Aurora?
+
+Type: research
+Status: resolved
+Blocked by: —
+
+## Question
+
+Native-Aurora support is a stated must-have, and **there is no Aurora checkout
+in this environment** — only the source-published `@plone/*` packages under
+`plone.blicca.auroraeditor/wrapper/node_modules/`. A must-have we cannot
+exercise is a claim, not a feature. Establish what verification is actually
+available before ticket 08 builds against the assumption.
+
+- **Is there a runnable Aurora?** Determine whether Aurora can be checked out
+  and run against this Plone backend at all (`plone.blicca.auroraeditor`'s ADR
+  0003 describes how the wrapper obtains Aurora's packages; the same route may
+  or may not yield a running app). If it can, that is the verification path and
+  ticket 15 uses it.
+- **If it cannot**, what is the strongest available substitute? Candidates, in
+  descending honesty: mounting our `edit`/`view` components in a vitest/jsdom
+  harness against the **unsubstituted** upstream `@plone/cmsui` widget registry
+  (this catches the whole class of "the widget only exists in Blicca" bugs,
+  which is the actual risk); a Storybook-style render; or nothing but code
+  review.
+- **What exactly differs between the hosts?** Enumerate it, so the substitute
+  test can target it: the widget registry contents, `config.getWidget`
+  resolution, the presence of `BliccaChoicesWidget`, the image widget
+  substitution, and the link-kit replacement. This list is the test plan.
+- **Decide and record the claim we are entitled to make.** If we can only test
+  the registry-level differences, the README says the block *is built against
+  upstream-registered widgets and its own*, not that it *is verified in Aurora*.
+  Overclaiming here is worse than the gap.
+
+## Answer
+
+**Verdict: do not stand up a live Aurora. Verify against the *unsubstituted
+upstream registry* in a vitest/jsdom harness — candidate #2 in this ticket — and
+make the correspondingly narrower claim.** The risk this actually retires is
+"the widget only exists in Blicca", and that risk is fully reachable this way.
+
+### 1. Is there a runnable Aurora? Yes in principle, and it is still the wrong call.
+
+Established, not assumed:
+
+- Aurora is `plone/volto`, branch **`7-plate`**, app **`apps/seven`** (the
+  default branch has no `cmsui`/`blocks`/`layout` — those alphas are published
+  off `7-plate`). Every `@plone/*` package here carries
+  `repository: plone/volto`.
+- **The network is open in this environment** — `npm view @plone/cmsui` and
+  `git ls-remote https://github.com/plone/volto` both succeed. So "we cannot get
+  Aurora" is false and should stop being repeated.
+
+What makes it the wrong call is not availability, it is **three compounding
+environment problems, none of which is a promo-block question**:
+
+1. **Seven assumes domain-root serving.** Blicca's own `ImageWidget` docstring
+   records why: `ImageBlockEdit` flattens URLs against
+   `config.settings.apiPath`, "built for Seven's domain-root serving, which
+   strips the `/<site>` prefix and 404s every scale on a Classic backend
+   without virtual hosting." Running Seven against our Plone at `:8081` means
+   standing up VHM rewriting first.
+2. **Our block has no runtime load path into Seven.** Contract §4 — the import
+   map, the `blockAddons` mount option, the wrapper's import+install
+   sequencing — is *entirely a Blicca `@@aurora-edit` mechanism*. Aurora proper
+   has no runtime add-on loader (§10 lists "Aurora upstream drift —
+   reconciliation if Aurora grows its own runtime add-on story" as still open).
+   Getting the promo into Seven means adding our package to the **monorepo's**
+   deps and registry config and rebuilding the app.
+3. It is a multi-day environment project sitting off this map's critical path,
+   and it would gate tickets 08–15 behind work that teaches us nothing about the
+   promo.
+
+### 2. Correction to the destination's wording: there is no single "same bundle"
+
+Worth fixing now, because it changes what ticket 15 can honestly assert. The two
+hosts consume **two different artifacts built from one source**:
+
+| host | artifact | entry |
+|---|---|---|
+| Blicca | the scope-wrapped Plone static bundle, runtime-imported per contract §4 | `install(config)` via `blockAddons` |
+| Aurora | the **npm package**, a source dependency (`collective.fragmentsblock`'s `bundle-src` exports `./src/index.tsx`) | `install(config)` from Seven's registry config |
+
+The **shared, load-bearing surface is `install(config)` plus the `edit` and
+`view` components** — identical in both. That is precisely what a jsdom harness
+can mount. So the substitute is not a watered-down version of the real test; it
+targets the actual shared seam.
+
+### 3. What exactly differs between the hosts — this is the test plan
+
+Read off `cmsui/config/widgets.ts` (upstream) versus
+`wrapper/src/bootstrap/config.ts` (Blicca, which installs cmsui first and then
+overrides). **Blicca is upstream + these deltas:**
+
+| key (category) | upstream | Blicca | touches the promo? |
+|---|---|---|---|
+| `choices` | **not registered at all** | `BliccaChoicesWidget` | **YES — the one that bites** |
+| `image` (widget) | `cmsui ImageWidget` | `BliccaImageWidget` | **YES** — see ticket 01 |
+| `object_browser` (widget) | React modal, **no upload** | pat-contentbrowser island, upload | no — promo uses free-text links |
+| `boolean` (widget) | Quanta `Checkbox` | `BliccaBooleanWidget` (label adapter) | only if we add a boolean field |
+| `querystring` (widget) | upstream | Blicca | no |
+| `'Relation List'` (factory), `Catalog` (vocabulary) | `ObjectBrowserWidget` | Blicca's | no |
+| `styleFieldDefinition` utility | **`blockWidth` only** (`@plone/blocks/index.ts:147`) | `blockWidth` + **`backgroundColor`** | **YES** |
+| link-kit | cmsui's | `BliccaLinkKit` (Plate plugin) | **no** — promo has no rich text |
+| `BlockSettingsForm` / renderer | upstream | **imports upstream verbatim** (`plone-block-sidebar.tsx:14`) | no difference to test |
+| `align`, `size`, `width`, `date`, `datetime` | upstream | **not overridden** | safe in both |
+
+**The three findings that matter:**
+
+1. **`choices` is Blicca-only.** `getWidgetByChoices` returns
+   `config.widgets?.choices ?? null`; upstream registers nothing, so **any field
+   declared with `choices` silently degrades to a single-line text input in
+   native Aurora.** This vindicates the map's decision to ship `promo_select`
+   under our own namespaced key rather than lean on `choices` — a
+   `widget: 'promo_select'` field resolves through `getWidgetByName` in *both*
+   hosts. Ticket 07 is load-bearing for Aurora support, not a nicety.
+2. **`backgroundColor`'s style definition is Blicca-only**, so the palette field
+   cannot function in native Aurora regardless of how we declare it. This is
+   consistent with the map's "Not yet specified" note and settles it in the same
+   direction: the field is a Blicca-host affordance, and the block must render
+   correctly with no `backgroundColor` at all.
+3. **`textarea` is registered in neither host** — confirming the map. Aurora's
+   own teaser `description` (`widget: 'textarea'`) is *already* degraded to a
+   one-line input upstream. `promo_textarea` is therefore an improvement on
+   upstream behaviour in both hosts, not a workaround for Blicca.
+
+### 4. The harness is idiomatic here, not invented
+
+- `collective.fragmentsblock`'s `bundle-src` — the map's designated copy-me
+  template — **already ships `"test": "vitest run"`**. Ticket 06 inherits the
+  runner for free; no new tooling decision.
+- Upstream `@plone/cmsui` tests itself the same way: `vitest`,
+  `@testing-library/react`, `vitest-axe`, a `vitest.config.ts` and
+  `setupTesting.ts`, with real widget tests (`ImageWidget.test.tsx`). Mounting
+  these source-published packages in jsdom is a **proven** pattern in this exact
+  package set, not a hope.
+- Note the wrapper itself has **no test runner** (`wrapper/package.json` has only
+  `build`/`watch`/`typecheck`), so the harness belongs in our package's
+  `bundle-src`, not in the wrapper.
+
+**Shape of the harness (for ticket 15):** in `bundle-src`, build a config the
+way *Aurora* does — `installTheming`, `installPlate`, `installBlocks`,
+`installLayout`, `installCmsui`, and **stop there, applying none of Blicca's
+overrides** — then call our `install(config)` and render `edit` and `view`.
+Assert: every field in our `blockSchema` resolves to a real widget (nothing
+falls through to the default TextField that should not), `promo_textarea` and
+`promo_select` resolve, the `image` field resolves to cmsui's `ImageWidget`, and
+`view` renders the same anatomy classes as under the Blicca config.
+
+### 5. The claim we are entitled to make — record this verbatim in the README
+
+> The Promo block is built against upstream-registered Aurora widgets and its
+> own namespaced widgets, and its `install`, `edit` and `view` are exercised in
+> a jsdom harness against an **unsubstituted upstream `@plone/*` registry**. It
+> has **not** been run inside a live Aurora (Seven) application.
+
+**Do not** write "verified in Aurora". The residual, honestly-stated gap:
+
+- No live Seven run — so app-level integration (routing, loaders,
+  `config.settings.apiPath` flattening, real upload against `@createContent`)
+  is unexercised.
+- The **npm-package artifact** is not built and consumed by a real Aurora build;
+  only the shared source is exercised.
+- A cross-host value-space divergence found in ticket 01 stands unfixed and
+  unfixable from our side: a promo authored in Blicca stores
+  `../resolveuid/<UID>`, which Seven's `getPreviewSrc` would render as a raw
+  `src` because it does not start with `/`. Editing preview only, not published
+  output — but ticket 15 must expect it rather than read it as a failure.
+
+### 6. Consequences for the map
+
+- **Ticket 15 is re-aimed** from "run it in Aurora" to the harness above; its
+  body has been updated and its `Blocked by` dropped from `02, 08` to `08`
+  (this ticket is now resolved, and nothing about the harness needs a live
+  Aurora).
+- **Standing up a live Seven against this backend is ruled out of scope** for
+  this map — it is an environment project, not a promo-block decision, and the
+  destination asks for the native-Aurora path *exercised*, which the harness
+  does. Recorded in the map's Out of scope.
+- **Ticket 03 gains two hard constraints** rather than open questions: no field
+  may rely on `choices` for its widget, and the block must render correctly with
+  `backgroundColor` absent.