Specify the Settings Support bundle interaction

[frankieramirez]

Question

What prose specification should govern where the Support bundle action lives in Settings and how it communicates disclosure risk, confirmation, generation progress, success, cancellation, and recoverable or terminal failure?

Use Support bundle as the user-facing term and keep the interaction consistent with the authenticated generation and download contract. No prototype is required.

Settled input

Choose the Support bundle generation and download contract fixes a single session-authenticated POST /api/system/support-bundle with no parameters. It returns a fresh in-memory ZIP immediately, never persists an artifact, uses the fixed filename comicarr-support-bundle-v1.zip, and reports complete/partial status in a response header and manifest. The UI needs a credentialed binary-fetch helper with the CSRF header, must handle immediate concurrent 409, retryable 503/generation failures, non-retryable validation failure, and network interruption; there is no job polling, server-side progress, resume, or cleanup flow.

[frankieramirez]

Resolution

Settings gains one deliberately quiet Support bundle interaction whose job is to create informed disclosure, not merely expose a download button.

Placement and hierarchy

Add a new SettingGroup in Settings → About, between What's new and Build / environment.

• Group title: Support bundle
• Group description: Create a diagnostic archive to help troubleshoot Comicarr.
• Do not add a new Settings rail section for one action.
• The action is independent of the Settings save form: it neither saves nor discards draft settings, and the generated bundle reflects active server state rather than unsaved form values.

Inside the group, use one existing card/border surface. Preserve Comicarr's semantic color tokens, typography, radii, and compact Settings density; introduce no new palette, font, hero treatment, promotional illustration, or oversized warning.

The one signature element is a literal three-step disclosure sequence. The numbering carries real order and therefore earns its place:

1. Create — Comicarr builds a fresh archive of allowlisted diagnostic facts.
2. Inspect — Open the ZIP and read README.txt, manifest.json, and diagnostics.json.
3. Share — Attach it publicly only when comfortable; otherwise send it privately to a maintainer.

Use compact monospaced step labels consistent with Comicarr's existing diagnostic/build language. The steps form three columns on wider screens and one ordered vertical stack on small screens, with structural dividers rather than decorative gradients or motion.

Below the sequence, state the exclusion promise plainly:

It does not include your database, settings values, raw log lines, library names, paths, chat content, or other free text.

The group action is an outline button labelled Create support bundle. It remains secondary to the page's global Save action.

Confirmation

Choosing Create support bundle opens the existing focus-managed Base UI dialog.

• Title: Create a support bundle?
• Description: Comicarr will create and download a ZIP of allowlisted diagnostic facts. It does not change your library or settings.
• Disclosure callout: Review the files before attaching the bundle to a public issue. If anything looks sensitive, share it privately with a maintainer instead.
• Secondary action: Cancel
• Primary action: Create and download

This one confirmation is required on every generation. There is no “don't ask again” preference and no checkbox theatre. Initial focus goes to Cancel, not the disclosure action. Escape, backdrop dismissal, the close control, and Cancel all mean the same thing while idle: close the dialog, return focus to Create support bundle, and make no request.

Client interface

Use a dedicated binary-download helper, not the JSON-only apiRequest.

The helper:

• sends a same-origin credentialed POST with X-Requested-With: ComicarrFrontend;
• accepts no caller options or filename;
• parses typed JSON errors through the same safe ApiError rules;
• accepts success only when status is 200, content type is application/zip, contract header is 1, bundle-status header is complete|partial, Content-Disposition matches the fixed contract filename, the body is non-empty, and the Blob does not exceed 512 KiB;
• creates a short-lived object URL, clicks a hidden anchor with comicarr-support-bundle-v1.zip, and revokes the URL after the click has been dispatched;
• never logs or retains Blob bytes.

A protocol mismatch, empty body, oversized body, invalid status header, or object-URL/download-trigger failure is a client-side terminal safety failure; no file is offered.

State machine

The interaction has these explicit states:

Idle

The group button is enabled. A persistent, visually quiet status region beside/below the action is empty but remains mounted for assistive technology.

Confirming

The dialog shows the disclosure copy and actions above. No request exists yet.

Creating

After Create and download:

• issue exactly one request;
• keep the dialog open;
• disable the group trigger and confirm action;
• change the primary label to Creating…;
• show a spinner with no announced decorative label;
• announce Creating support bundle. This may take a moment. through a polite, atomic live region;
• show no percentage, step animation, polling status, upload language, or background-job affordance.

Cancel, Escape, backdrop dismissal, close, navigation, or unmount aborts the browser request and suppresses any later download, toast, or state update. The server may finish its bounded in-memory generation, but no artifact persists. A visible cancellation returns to idle and politely announces Support bundle download canceled. It is not an error toast.

Double-clicks and repeated confirmation are blocked client-side; another tab/process is still handled by the server's typed conflict.

Complete success

After the helper validates the response and dispatches the browser download:

• close the dialog;
• restore focus to Create support bundle;
• set the inline polite status to Support bundle download started. Review it before sharing.;
• show a concise success toast with the same meaning.

Use download started, never downloaded or saved: Comicarr cannot know whether the browser completed the save.

Partial success

A partial header still produces the valid download, then:

• close and restore focus;
• show an info treatment, not success or error;
• announce Support bundle download started with some diagnostics unavailable. Review manifest.json before sharing.;
• keep Create support bundle available for a fresh attempt.

Do not enumerate unavailable sources in the UI; the closed manifest owns that detail.

Canceled or interrupted

If the user cancels before the Blob is dispatched, no file is offered. If the network is interrupted:

• keep/reopen the dialog in a recoverable error state;
• announce The connection was interrupted. No file was downloaded.
• actions: Close and Try again.

Retry always sends a fresh POST; it never resumes a prior response.

Concurrent generation

For support_bundle_in_progress:

• keep the dialog open;
• show Another support bundle is being created. Try again in a moment.;
• respect Retry-After before enabling Try again;
• never poll or retry automatically.

Temporarily unavailable or generation failure

For retryable support_bundle_unavailable or support_bundle_generation_failed:

• show the server's fixed safe sentence;
• offer Close and Try again;
• do not auto-retry.

Disclosure validation failure

For non-retryable support_bundle_validation_failed or a client protocol/Blob validation failure:

• show an assertive inline error: Comicarr stopped the download because the bundle did not pass its safety checks. No file was downloaded.
• offer Close only;
• do not suggest weakening checks, using the legacy CarePackage, or attaching raw diagnostics publicly.

Authentication and CSRF

• 401: Your session has expired. Sign in again before creating a support bundle.
• 403 CSRF: Comicarr blocked the request. Refresh the page before trying again.

Neither retries automatically. The interaction must follow the app's existing authentication transition rather than creating a second login flow.

Accessibility and motion

• Use the existing labelled dialog with focus trap and focus return.
• The persistent inline region is role=status, aria-live=polite, and atomic for creating, canceled, complete, and partial announcements.
• Errors use role=alert; error text is not conveyed by color alone.
• Button text changes carry progress; the spinner is aria-hidden.
• The pending control exposes aria-busy=true.
• Keyboard activation, Escape/cancel semantics, and touch targets match existing Button/Dialog behavior.
• No ornamental animation is added. Existing dialog motion respects the app's reduced-motion treatment; the interaction adds no looping or progress motion beyond the standard spinner.

The current toast implementation announces only errors reliably, so completion and partial status may not depend on a toast. The mounted inline live region is authoritative.

Browser and navigation edge cases

• Navigation or unmount aborts the fetch, revokes any object URL, and suppresses late completion/error UI.
• If object-URL creation or the anchor click throws, revoke any URL, show the terminal safety failure, and do not claim a download started.
• Browsers do not provide a reliable “file saved” signal; no separate “download blocked” state pretends otherwise. The inline result says only that the download was started.
• A user who cannot find the file creates a fresh bundle; the UI does not retain bytes for a second click.

Documentation copy contract

The bug-report template, contributing guide, and security guide must use the same user-facing language:

1. Go to Settings → About → Support bundle.
2. Choose Create support bundle, then Create and download.
3. Open the ZIP and review its three files.
4. Attach it publicly only when comfortable; otherwise share it privately with a maintainer.

They must stop claiming that the archive contains a redacted config, database, environment dump, or logs. They must not use CarePackage as the user-facing name.

Rejected alternatives

• Button with toast only: hides the disclosure contract and fails assistive-technology users because success/info toasts are not reliably announced.
• No confirmation: saves one click on an infrequent action but removes the moment where public-sharing consequences are made explicit.
• Destructive styling: nothing is deleted or changed; red danger treatment would misstate the action.
• A new Support settings section: one action does not justify another navigation destination.
• Progress modal or polling: the endpoint has no job lifecycle or meaningful percentage.
• Retaining the Blob for retry: creates a second in-browser artifact lifetime and stale-snapshot semantics; a fresh bounded request is simpler and safer.
• Prototype: the map explicitly chose a prose specification, and existing Settings primitives cover the interaction without an unresolved visual question.