# Implement the Vieunite Hosted Picker frontend integration

You are working inside an existing application repository. Implement the frontend half of a Vieunite Hosted Picker integration while preserving the application's current architecture, user experience, conventions, and user-owned work.

The secure CMS-local backend bridge should be implemented and documented first. Do not implement or modify backend behaviour in this task.

## Outcome

Add the smallest native-feeling editor entry point that opens the documented Vieunite Hosted Picker through the application's existing same-origin backend bridge, handles selection and cancellation correctly, and feeds the result into the application's existing content or media workflow.

## Authoritative documentation gate

Before editing any file, read the complete current Vieunite developer documentation. Do not rely only on this prompt, previous knowledge, or isolated code examples.

1. Open `https://collection.vieunite.com/docs`.
2. Fetch `https://collection.vieunite.com/docs/search-index.json`.
3. From `data[].href`, remove URL fragments, deduplicate the page paths, resolve them against `https://collection.vieunite.com`, and read every unique documentation page returned by the index. Follow same-origin redirects.
4. Read `https://collection.vieunite.com/docs/openapi.json` as the exact tenant API contract.
5. Read the linked Hosted Picker SDK and TypeScript types, authentication boundary, result model, reference lifecycle, error handling, go-live, demos, and official implementation case study in full.
6. Keep compact implementation notes rather than copying the documentation into the repository or conversation.

Treat the live documentation, SDK contract, and OpenAPI schema as the source of truth. If this prompt conflicts with them, follow the live documentation. Do not invent endpoints, fields, events, options, errors, or Picker behaviour.

If network access is unavailable, the documentation index is incomplete, or any required page, SDK contract, or schema cannot be read, stop before editing and report exactly what could not be accessed. Ask the user for an accessible documentation snapshot instead of guessing.

## Repository safety contract

- Begin with read-only inspection.
- Read every applicable repository instruction file, including `AGENTS.md`, `CLAUDE.md`, `README`, contribution guidance, and directory-scoped instructions, before editing.
- Detect the actual frontend framework, language, package manager, routing, state management, API client, authentication model, component system, styling conventions, accessibility patterns, and test runner. Do not assume a technology stack.
- If the repository uses Git, inspect its status first. Treat all existing modified, staged, and untracked files as user-owned.
- Never reset, clean, stash, revert, checkout over, delete, overwrite, or reformat user-owned work.
- If a required edit overlaps an existing uncommitted change and cannot be preserved with confidence, stop and report the exact file and conflict.
- Make the smallest compatible change. Reuse existing components, design tokens, routes, API clients, state/query utilities, error surfaces, analytics, and tests.
- Do not introduce a parallel design system, duplicate an existing abstraction, or replace working code merely because another design is preferable.
- Do not perform unrelated refactors, dependency upgrades, repository-wide formatting, route redesigns, public API breakage, or speculative cleanup.
- Avoid new production dependencies. Use the documented browser SDK and existing application primitives. If another dependency is genuinely required, stop and explain why.
- Do not modify generated files directly when the repository has a documented source or generator.
- Do not weaken authentication, CSRF, Content Security Policy, origin validation, accessibility, tests, type checks, lint rules, or error handling to make the change pass.
- Keep the coding agent's normal approval, permission, and sandbox controls enabled. Do not bypass them or widen filesystem or network access to finish the task.
- Do not commit, push, open a pull request, deploy, change cloud resources, access production data, or perform any external write unless the user explicitly requests it.
- Never place or request tenant credentials in browser code, HTML, local storage, URLs, logs, fixtures, screenshots, or commands.

## Read-only discovery

Locate and understand:

- the editor, media library, asset chooser, content form, or layout surface where users already select media;
- the nearest analogous provider, upload, embed, or external-media action;
- routing, modal or popup, focus-management, notification, and error patterns;
- the existing API client, authentication and CSRF mechanism;
- the CMS-local Vieunite session and redemption endpoint contract produced by the backend task;
- the existing content/reference or native-media result model;
- query invalidation, cache refresh, selection state, form state, and persistence flow;
- current loading, disabled, cancellation, retry, responsive, and accessibility conventions;
- repository-supported build, lint, type-check, unit, component, and browser test commands.

After discovery, write a brief implementation plan naming the minimal files and existing patterns you will reuse. Continue without waiting only when the backend bridge contract exists, the UI insertion point is clear, and the change remains within this safety contract.

If the secure same-origin backend bridge is missing or its request/response contract cannot be determined from the repository, stop without creating mock endpoints or editing backend files. Report the exact frontend contract needed from the backend task.

## Frontend scope

Implement only the browser and editor experience required by the documented Hosted Picker flow.

### Native editor entry point

- Place one clearly labelled Vieunite action where editors already choose or add media. Do not build a separate media library, new navigation hierarchy, or custom artwork browser.
- Reuse the application's existing button, menu, modal, icon, spacing, responsive, loading, error, and permission patterns.
- Preserve existing media sources and editor workflows.
- Show the action only where the current user is already allowed to add or select content, using the application's existing permission source.

### SDK integration

- Load the documented major-version Picker SDK from the documented origin using the repository's existing external-script pattern.
- Load it once, reuse one client when appropriate, handle concurrent clicks safely, and clean up listeners or in-flight work according to the documented SDK lifecycle.
- Use only the application's existing same-origin session and redemption bridge endpoints. Browser code must never call authenticated Vieunite tenant APIs directly.
- Configure the exact documented trusted Picker origin and the backend-provided bridge contract. Do not accept an origin or endpoint from untrusted runtime messages or URL parameters.
- Pass only documented, product-approved selection options. Treat initial filters as UX defaults, not authorisation.
- Preserve the SDK's documented source-window, origin, protocol, active-session, capability, and cancellation behaviour rather than recreating its message protocol.
- Do not read, expose, persist, or log the tenant token, Picker launch capability, selection code, signed asset URLs, or other temporary credentials.

### Result handling

- Treat user cancellation as a normal result, not an application error.
- Prevent duplicate opens and duplicate result application while a selection is in progress.
- For a selected result, use the existing backend contract and current application workflow rather than inventing a second persistence path.
- If the backend returns canonical references, retain provider, resource type, resource ID, and artwork rendition exactly as documented and connect them to the existing form or content state.
- If the backend imports selections into native media, consume only its sanitized local-media result, refresh the existing media query or store, and select the returned native item through the normal workflow.
- Treat rendition and version keys as opaque. Do not derive crop, ratio, physical asset variant, or permanent URL semantics in the browser.
- Preserve per-item success and failure when multiple selection is supported.
- Surface documented recoverable errors through the application's existing notification pattern, with a retry that does not create duplicate sessions or apply a result twice.
- Never display raw secrets, capabilities, upstream response bodies, or sensitive diagnostics to the editor.

### Accessibility and behaviour

- Preserve focus when opening and closing the Picker and return focus to the initiating control.
- Provide an accessible name, keyboard operation, visible focus, disabled/loading state, and non-colour error communication.
- Keep the existing editor responsive at its supported breakpoints.
- Respect reduced-motion preferences and existing motion conventions.
- Avoid changing unrelated layout, typography, colours, global CSS, or component APIs.

### Scope discipline

- Do not edit backend routes, services, models, migrations, secrets, server configuration, or backend tests.
- Do not copy framework-specific examples literally. Translate documented behaviour into the repository's established frontend patterns.
- Do not bypass a missing backend with a browser-held tenant token, direct tenant API request, insecure proxy, hardcoded response, or permanent mock.
- Do not self-host or rewrite the SDK unless the live documentation and existing repository architecture explicitly require it.
- If Content Security Policy or deployment configuration outside frontend ownership must change, report the exact required origin and directive without editing the other layer.

## Verification

Add tests using the repository's existing test style. Cover at least:

- the Vieunite action appears in the intended existing editor surface and respects current permissions;
- the SDK is loaded once and configured with the documented exact origin and same-origin bridge paths;
- tenant credentials and temporary capabilities are absent from browser code, rendered HTML, storage, URLs, logs, and test fixtures;
- loading state prevents duplicate opens;
- selected canonical-reference or native-media results enter the existing workflow exactly once;
- cancellation is quiet and restores the previous UI state;
- recoverable bridge or SDK failures use the existing error surface and can retry safely;
- multiple-selection partial results are preserved when enabled;
- keyboard focus, accessible naming, and responsive behaviour remain correct.

Run the smallest relevant tests first, followed by the repository's normal lint, type-check, build, and broader tests when proportionate. If browser tooling exists, exercise the real editor flow locally and verify open, select, cancel, error, retry, and focus restoration. Do not make live tenant calls unless explicitly authorised.

Inspect the final diff and repository status. Confirm that only intended frontend and test files changed, no secret was introduced, and existing user-owned files remain untouched.

## Final response

Report:

1. the existing editor surface and frontend patterns reused;
2. every file changed;
3. the CMS-local backend contract consumed;
4. how SDK loading, selected results, cancellation, errors, accessibility, and duplicate prevention work;
5. documentation pages, SDK contract, and OpenAPI successfully reviewed;
6. commands run and exact results, including browser evidence when available;
7. any pre-existing failures, missing backend requirement, unverified assumption, or work deliberately left out of scope.

Do not claim completion without executable verification evidence.