Build Vieunite into your CMS.

# Implement the Vieunite Hosted Picker backend integration

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

## Outcome

Add the smallest production-shaped backend integration that lets an authenticated editor create a Vieunite Picker session, redeem a completed selection through the application backend, and hand the result to the application's existing content or media workflow.

Do not implement or modify frontend UI in this task.

## 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 linked Hosted Picker, authentication, reference lifecycle, asset delivery, error handling, go-live, and official implementation case-study material in full.
6. Keep compact implementation notes rather than copying the documentation into the repository or conversation.

Treat the live documentation and OpenAPI schema as the source of truth. If this prompt conflicts with them, follow the live documentation. Do not invent endpoints, fields, scopes, headers, limits, error codes, or Picker behaviour.

If network access is unavailable, the documentation index is incomplete, or any required page 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 backend framework, architecture, package manager, configuration system, authentication and authorisation model, persistence layer, HTTP client, error format, logging conventions, and test runner. Do not assume a language or framework.
- 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 routes, services, repositories, models, configuration, HTTP clients, error helpers, observability, and tests.
- Do not introduce a parallel architecture, duplicate an existing abstraction, or replace working code merely because another design is preferable.
- Do not perform unrelated refactors, dependency upgrades, repository-wide formatting, schema redesigns, public API breakage, or speculative cleanup.
- Avoid new production dependencies. If the integration genuinely requires one, stop and explain why the existing stack cannot satisfy the requirement.
- Do not modify generated files directly when the repository has a documented source or generator.
- Do not weaken authentication, authorisation, CSRF, origin checks, TLS validation, 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.
- Do not use real tenant credentials in tests or ask the user to paste secrets into source code, chat, logs, fixtures, or commands.

## Read-only discovery

Locate and understand:

- the backend application entrypoint and route registration;
- authenticated editor identity, organisation or tenant ownership, and permission checks;
- CSRF protection and trusted-origin configuration;
- existing server-side secret and environment configuration;
- existing outbound HTTP client, timeout, retry, tracing, and error-mapping patterns;
- current media, asset, content-entry, external-provider, or reference models;
- existing idempotency, job, transaction, and deduplication utilities;
- the nearest analogous integration and its tests;
- repository-supported build, lint, type-check, and 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 change is clear, local, and compatible with this safety contract. Stop for a concise user decision when authentication ownership is ambiguous, a destructive migration would be required, production access would be needed, or more than one materially different persistence model is equally valid.

## Backend scope

Implement only the server-side boundary required by the documented Hosted Picker flow.

### CMS-local bridge

- Add the session-creation and selection-redemption endpoints on the application's own origin, using its existing route naming and response conventions.
- Require the application's normal authenticated editor session and authorisation on both endpoints.
- Apply the application's normal CSRF protection when browser credentials are cookie-based.
- Keep the Vieunite tenant token entirely server-side in the existing secret/configuration system. Never return, serialize, log, or expose it to browser code.
- Use the documented environment base URL and keep Test and Production configuration separate.
- Use the existing outbound HTTP abstraction with explicit connect/read timeouts and normal TLS verification.
- Allowlist and normalise browser-controlled Picker options. Never proxy an arbitrary browser request body to Vieunite.
- Derive the exact `callback_origin` from trusted server configuration, never from untrusted request input.
- Apply the documented immutable host capabilities on the trusted backend.
- Bind each created Picker session to the authenticated editor, organisation or tenant, and relevant content context using the smallest existing persistence or session mechanism.
- Reject redemption unless the same authorised context owns the Picker session.
- Redeem the one-time selection with a stable documented `Idempotency-Key`, preserving the same key across an uncertain retry.
- Preserve Vieunite problem details, HTTP status semantics, and request IDs through the application's established error boundary without leaking secrets or temporary capabilities.

### Existing content or media model

First inspect the application's current model; do not create a new media subsystem.

- If the application already supports external-provider references, persist the documented canonical identity using its existing extension points: provider, resource type, resource ID, and artwork rendition.
- If the application only accepts native media and already has a secure server-side import pipeline, adapt the documented import pattern to that pipeline and retain canonical Vieunite provenance for deduplication and audit.
- Treat rendition or version keys as opaque documented values.
- Do not persist Picker launch capabilities, selection codes, signed delivery URLs, thumbnails, physical asset variants, or metadata snapshots as authoritative source data.
- Resolve current metadata, rights, availability, and the saved rendition at the documented lifecycle points.
- Request signed delivery URLs close to use. If importing an asset, download it only on the backend through the application's constrained asset client, enforce the documented origin, type, redirect, timeout, and size rules, then discard the temporary URL.
- Preserve partial-success semantics when the documented operation is item-based.
- Do not add a database migration if an existing JSON, metadata, provider, integration, or provenance field can represent the contract cleanly.
- If durable ownership cannot be implemented without a schema migration or public contract change, stop after discovery and propose the smallest reversible change. Do not apply it silently.

### Scope discipline

- Do not edit frontend components, styles, routes, browser SDK code, or UI tests.
- Do not build a custom artwork browser when the Hosted Picker satisfies the requirement.
- Do not copy framework-specific examples literally. Translate the documented behaviour into the repository's established patterns.
- Do not make live Vieunite calls unless the repository already has an explicitly authorised integration-test environment and the user has asked for live verification.

## Verification

Add behaviour-level tests using the repository's existing test style and mocked upstream HTTP boundary. Cover at least:

- authorised session creation;
- unauthenticated or unauthorised rejection;
- CSRF rejection where applicable;
- browser options are allowlisted rather than transparently proxied;
- callback origin comes from trusted configuration;
- tenant credentials and temporary capabilities never appear in the public response or logs;
- session ownership is enforced during redemption;
- redemption retries reuse the same idempotency key;
- documented upstream 4xx, 5xx, timeout, malformed response, and request-ID handling;
- the chosen canonical-reference or native-media persistence path;
- partial success and replay behaviour where applicable.

Run the smallest relevant tests first, then the repository's normal lint, type-check, and broader test commands when proportionate. Use only temporary or test databases. Do not alter unrelated tests to hide a failure.

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

## Final response

Report:

1. the backend architecture and existing patterns reused;
2. every file changed;
3. the CMS-local frontend contract: paths, methods, authentication, CSRF requirements, request bodies, responses, and error shape;
4. whether the integration stores canonical references or imports native media, and why that matches the existing application;
5. documentation pages and OpenAPI successfully reviewed;
6. commands run and exact results;
7. any pre-existing failures, unverified assumptions, or work deliberately left out of scope.

Do not claim completion without executable verification evidence.

# 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.