Migrating To Espalier 5

Espalier 5 removes the compatibility aliases, legacy tokens, and rolling-deploy cleanup that earlier releases kept for older consumers. Each has had a replacement since Espalier 4 or earlier. Make the replacements below in the same change that upgrades the package; nothing forwards the old names.

Espalier 5 also ships esp-video and makes form errors perceivable to assistive technology. Those are additions, but the second changes what a form announces, so the last section lists what to check.

Removed attributes, properties, and methods

Espalier 4	Espalier 5
`<esp-page fixed-menus>` / `page.fixedMenus = true`	`<esp-page header-position="fixed">` / `page.headerPosition = "fixed"`
`menu.collapsed = true` on `esp-menu`	`menu.mode = "drawer"`
`menu.collapsed = false`	`menu.mode = "vertical"` (or the mode the menu had before)
`menu.toggleOpened()`	`menu.toggleDrawer()`
`calculatePhotoLayout(images, width, target, gap, maxHeight, maxPerRow)`	`calculateAlbumLayout(images, { containerWidth, targetRowHeight, gap, maxRowHeight, maxImagesPerRow })`; read `row.items[i].image` and `row.items[i].width` instead of `row.images`. Two results differ: with `maxImagesPerRow`, a final row with fewer images is partial (capped at the tallest earlier row's height instead of stretching to the full width), and a row clamped by `maxRowHeight` still spans the full width with wider cells, so render them with `object-fit: cover`

Removed CSS custom properties

Espalier 4	Espalier 5
`--esp-page-max-width`	`--esp-page-main-max-width`
`--esp-page-preview-min-main-width`	`--esp-page-main-min-width`
`--esp-page-preview-width`	set `--esp-page-preview-min-width` and `--esp-page-preview-max-width` to the same value
`--esp-page-flyout-width`	set `--esp-page-flyout-min-width` and `--esp-page-flyout-max-width` to the same value

Font links

Runtime Google Fonts links created by esp-root and esp-font-picker carry only data-esp-google-font-owner (plus data-esp-family and data-esp-weight). The data-esp-font, data-esp-font-picker, and data-esp-font-picker-root attributes are no longer written, and links that an Espalier 3 or early-4 bundle wrote with only those attributes are no longer cleaned up.

Select runtime font links with link[data-esp-google-font-owner]. The owner key is root:<correlationId>-<slot> for a root and picker:<rootCorrelationId>:<family> for a picker's full font.

CLI

espalier theme-check --expect no longer recognizes fit-table files written by Espalier 4.2.0 or earlier; it reports them as not a fit-table suite. Regenerate them with --update-expect.

Kept on purpose

These look like compatibility paths but are not removed:

Theme decoding and provenance in parseTheme and mergeTheme. They read themes stored before the UTF-8 marker and the explicit-mapping marker existed, which are still in databases and published pages.
esp-page's footer landmark. Footer content that is not itself a landmark (esp-footer, <footer>, or role="contentinfo") is still wrapped in a contentinfo landmark, so any footer content is announced as one.
esp-menu's sliding, which esp-header still drives.

Checklist for Taproot

Each line is a site that the Espalier 5 changes above reach.

ux/client/src/all.ts: replace sideMenu.collapsed = window.innerWidth < 900 with sideMenu.mode = window.innerWidth < 900 ? "drawer" : "vertical".
ux/server/src/routes/authenticated/ui/authenticated-root.vto: the --esp-page-max-width: branch is never taken (nothing sets pageMaxWidth); delete it, or rename the property to --esp-page-main-max-width if it should stay.
ux/client/src/pages/sites/pages/taproot-page-authoring.test.ts: the assertions that --esp-page-preview-width, --esp-page-flyout-width, and --esp-page-preview-min-main-width are empty still pass but no longer test anything; delete them.
Tests that probe font links by the removed attributes would now pass for the wrong reason (they match nothing). Switch them to link[data-esp-google-font-owner]:
- generator/browser-tests/authoring-preview-boundary.spec.ts
- generator/browser-tests/first-paint-font-plan.spec.ts
- ux/client/src/pages/sites/settings/taproot-site-settings-fonts.test.ts

Form behavior to check

Espalier 5 makes form errors reach assistive technology. Nothing to rename, but a consumer should check:

Remove shadow-root workarounds. While an esp-form-item shows an error, the element inside each control that takes focus now has aria-invalid="true", and the error is part of its accessible description after the hint. Code that reached into a control's shadow root to add either should be deleted.
Remove group wrappers. esp-radio-button-group and esp-checkbox-group now take the form item's label as the name of their radiogroup/group. Drop any wrapper role="group" + aria-labelledby added for that.
Decimal fields. Use input-type="number" step="any" for decimal esp-input fields; typing a decimal point now works in every number field.
Errors are announced once through a polite status message ("Label: error"). Re-renders that leave the error unchanged stay quiet.
A choice clears its error. When the visitor changes a radio-button or checkbox group, a checkbox, a switch, or a picker, the form item clears an error from error or errorPool, unless a listener on the control gave the field a new error through error or errorPool while handling that change. If your app re-sends the same server error after the visitor changes the field, it will show again; otherwise it stays cleared until the next submit. Text controls, the date picker, and the slider keep their error until you change it.
Replacing a picker's options is quiet. Setting pickerItems on esp-pick-one or esp-pick-some from code no longer emits esp-value-changed; only the visitor's pick does. Code that relied on that event to learn about its own update should read value after setting pickerItems.
esp-input date and phone values set from code after the visitor typed are now shown, including a value written back from the field's own esp-value-changed.