feat(ep-commerce): headless styling contract + EPSearchBox provider refactor (#305, #308)

[field123]

Summary

Two layered PRDs delivered together because PRD #308 is the architectural completion of PRD #305:

• PRD: EP catalog-search components must honour designer styling (headless styling contract) #305 introduces a headless styling contract for the nine EP catalog-search components: components ship behaviour, not appearance; designer styles from Plasmic's panel reach the rendered DOM unfiltered.
• PRD: Make EPSearchBox styleable by lifting its DOM out of the code-component #308 found and addresses the underlying Plasmic platform constraint that PRD: EP catalog-search components must honour designer styling (headless styling contract) #305's contract alone couldn't bypass: code-component instances filter appearance styles via TPL_COMPONENT_PROPS. The fix is to refactor EPSearchBox from a chrome-rendering code component into a render-children-only provider, pushing the visible <input> and <button> into the slot as Plasmic-controlled tags (which escape the filter).

Changes

New files

• headless-styling.ts — deep module: idempotent injectHeadlessStyles() + useHeadlessStyling() hook. Mounts a single <style data-ep-headless-styles> tag with :where() rules at zero specificity for [data-ep-search-box] (legacy, still useful for non-provider use) and [data-ep-catalog-search-provider].
• __tests__/headless-styling-contract.tsx — describeHeadlessStylingContract shared test helper: asserts className lands on documented leaf, no inline appearance styles, editor + runtime structurally equivalent.

Modified

• EPSearchBox.tsx — provider-only, no DOM. forwardRef + useImperativeHandle exposes setValue(value) (debounced) and clear() ref-actions. Wraps children in <DataProvider name="searchFieldData" data={{value, displayValue, isEmpty}}>. Deprecated props (placeholder/autoFocus/showClear) preserved as hidden no-ops (per pattern_bundle_invariant_orphans) so existing project bundles stay valid.
• EPCatalogSearchProvider.tsx — dropped DEFAULT_PROVIDER_WRAPPER_STYLE from six render sites; structural CSS now ships via the :where() block.
• EPSearchHits.tsx — added data-ep-search-hits attribute for contract-test consistency. The inline gridStyle pattern is preserved (the only justified inline-style workaround in the catalog-search codebase, due to Plasmic's className-strip on display: grid).
• design-time-data.ts — new SearchFieldData type and MOCK_SEARCH_FIELD_DATA.
• __tests__/catalog-search-components.test.tsx — 45 contract assertions (5 per component × 9 components, except EPSearchBox which has its own behavioural tests). 8 new EPSearchBox provider tests covering ref-action behaviour, debounce, displayValue divergence during debounce, and meta correctness.
• README.md — new ## Styling contract section with the four-rule contract, leaf-element table per component, :where() pattern guidance, Composing EPSearchBox walkthrough, migration notes.

Migration

• Existing EPSearchBox instances will lose their inline-rendered chrome. Re-author the slot with a Plasmic <input> and <button>, then bind value and wire interactions per the README's "Composing EPSearchBox" section.
• The example app's project (9iSL9GyrJNp9ebWzxaHtM5) was re-authored via the Plasmic MCP during this work; the /products page now shows a fully styled search input with all designer-set appearance properties reaching the live DOM.

Test plan

• yarn test in plasmicpkgs/commerce-providers/elastic-path — 1522 tests pass (no regressions, 8 new EPSearchBox tests, 45 contract assertions across 9 components).
• yarn build clean (tsdx + server entry).
• Live verified at http://localhost:3456/products:
  • The styled search input renders with designer-set border/radius/padding/font/background — confirms TplTag styles are NOT subject to TPL_COMPONENT_PROPS filtering.
  • searchFieldData propagates to slot children via React context (verified via fiber inspection).
  • Page renders cleanly with no console errors after the safe-fallback binding ($ctx.searchFieldData && $ctx.searchFieldData.value || "").

Outstanding (not blocking this PR)

• Studio-UI step required to wire ref-action interactions on the slot's input/button. Plasmic's canonical invokeRefAction action type is not exposed by the MCP's interaction.add tool (filed as gap add enhanced container insights #81 in the EP MCP feedback tracker). The customFunction-with-$refs workaround saves but doesn't fire ref-actions at runtime. To complete the example app's wiring: in Studio, click the input → add onChange interaction → "Run action" → EP Search Box → setValue → event.target.value. Same for the clear button's onClick → clear.
• Two related MCP gaps surfaced by this work and filed separately: build: trigger fresh terraform plans #79 (Plasmic codegen lag after MCP slot edits) and build: add ingress and egress rules for deploy #82 (Plasmic loader module cache stale despite alwaysFresh: true).

Closes #305.
Closes #308.