# Slice 2a: Request Reference Usability

## Status

Complete - automated validation, proportional manual acceptance, and explicit final sign-off passed

## Objective

Make REST request-template authoring easier to discover and visually map while
preserving the existing canonical template format and guided insertion workflow.

## Compatible Reference Suggestions

- [x] Make template-capable request fields aware of compatible component and
  declared-variable references.
- [x] Offer suggestions when a user begins entering a template, including after
  typing `{{`, without requiring exact template syntax from memory.
- [x] Apply suggestions to endpoint URLs, header values, query-parameter values,
  and request body templates where the existing runtime supports references.
- [x] Insert the canonical executed forms
  `{{components.<componentName>.value}}` and `{{variables.<variableName>}}`.

- [x] Filter suggestions to references supported by the selected field and
  current project configuration.
- [x] Preserve free-form template editing and the existing **Request value
  reference** controls.

## Header Name Suggestions

- [x] Offer a pulldown of common HTTP header names, including **Accept** and
  **Content-Type**, when authoring REST Action headers.
- [x] Keep free-form custom header-name entry available for backend-agnostic,
  vendor-specific, and less common headers.
- [x] Preserve the existing canonical header object and runtime behavior.

## Source and Destination Alignment

- [x] Reorder the **Request value reference** controls so request destinations
  align vertically with request keys and value sources align vertically with
  request values.
- [x] Present the controls in this order: request destination, component or
  variable source, then **Insert reference**.
- [x] Preserve the source and destination terminology and existing insertion
  behavior.
- [x] Manually verify the alignment remains clear for URL, header, query, and body
  destinations at supported viewport widths.

## Acceptance Criteria

- [x] Typing `{{` in a supported request field offers compatible component and
  declared-variable suggestions.
- [x] Choosing a suggestion inserts valid canonical template syntax without
  preventing subsequent free-form editing.
- [x] Unsupported or ambiguous references are not offered.
- [x] Header-name authoring suggests common HTTP headers while still accepting
  arbitrary custom names.
- [x] A destination such as `Query: environment` is vertically aligned with the
  `environment` request key below it.
- [x] A source such as `Component: environment` is vertically aligned with the
  resulting `{{components.environment.value}}` request value below it.
- [x] Existing request-template execution and canonical/runtime-state separation
  continue to pass automated and manual regression checks.

## Boundaries

- This work improves authoring only; it does not add new runtime template
  destinations, expression syntax, transforms, or orchestration.
- Path-parameter reference insertion remains excluded until its runtime contract
  is deliberately unified.
- Authentication and secret references remain owned by Slice 3.

## Automated Validation

- Focused request-authoring coverage: 4 suites / 23 tests passed.
- Complete frontend coverage: 21 suites / 507 tests passed, 0 snapshots.
- Frontend production build passed under the documented Node 20/npm 10 toolchain.
- Backend and schema validation were not rerun because Slice 2a changes only frontend authoring behavior and preserves the canonical document shape.

## Manual Acceptance

Proportional manual acceptance passed on 2026-08-01 in an isolated Chromium browser against project `Slice 2 Final` (`#12`) at `http://localhost:3000/`. The normal viewport was 1440 x 1100 and the responsive viewport was 700 x 1000. The saved project was not updated.

- Contextual component and variable suggestions passed across URL, header-value, query-value, and body-template fields.
- Duplicate `hostname` component names were withheld from contextual and guided suggestions while `Variable: statusText` remained available; `hostname` and `hostnameSecondary` became eligible after uniqueness was restored.
- Common header suggestions included `Accept` and `Content-Type`; `X-Custom-Vendor-Header` was preserved exactly with value `test` in the canonical `headers` object.
- Guided controls appeared as **Request destination**, **Value source**, and **Insert reference**, aligned semantically at 1440 x 1100 and stacked clearly without overlap at 700 x 1000.
- Header/query insertion replaced existing values, URL/body insertion appended, path parameters remained excluded, free-form editing remained available, and canonical JSON remained free of mapping and runtime state.

This evidence is manual acceptance, separate from the automated validation above. The user granted explicit final Slice 2a sign-off on 2026-08-01.