conductor/SLICE2a.md

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

• Make template-capable request fields aware of compatible component and declared-variable references.

• Offer suggestions when a user begins entering a template, including after typing {{, without requiring exact template syntax from memory.

• Apply suggestions to endpoint URLs, header values, query-parameter values, and request body templates where the existing runtime supports references.

• Insert the canonical executed forms {{components.<componentName>.value}} and {{variables.<variableName>}}.

• Filter suggestions to references supported by the selected field and current project configuration.

• Preserve free-form template editing and the existing Request value reference controls.

Header Name Suggestions

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

Source and Destination Alignment

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

Acceptance Criteria

• Typing {{ in a supported request field offers compatible component and declared-variable suggestions.
• Choosing a suggestion inserts valid canonical template syntax without preventing subsequent free-form editing.
• Unsupported or ambiguous references are not offered.
• Header-name authoring suggests common HTTP headers while still accepting arbitrary custom names.
• A destination such as Query: environment is vertically aligned with the environment request key below it.
• A source such as Component: environment is vertically aligned with the resulting {{components.environment.value}} request value below it.
• 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.