SealShare/docs/plans/share-qr-code.md

# Share by QR code and share sheet

## Goal

After an upload, the share created page offers two more ways to hand a share over besides
copying the link: a QR code, in a dialog, that another device scans (and that downloads as a
PNG for chats and mails), and, where the browser has one, the device's native share sheet. Both
carry only the share's link — never a password.

## Context

- Laravel 13.31, Livewire 4.4, Livewire Material 1.0.x, Pest 5 with browser tests, Octane
  (FrankenPHP). Production image `dunglas/frankenphp:php8.5-alpine` with `intl`, `pcntl`, `zip`
  added; it has `xmlwriter` and `iconv`, and neither `gd` nor `imagick`.
- `bacon/bacon-qr-code` v3.1.1 is installed through `laravel/fortify` (`^3.0`), which draws the
  two-factor setup QR with `Writer` + `ImageRenderer` + `SvgImageBackEnd` and strips the XML
  declaration (`TwoFactorAuthenticatable::twoFactorQrCodeSvg()`). SVG needs no image extension;
  a server-side PNG would.
- `app/Livewire/ShareCreated.php` (`#[Layout('layouts.app')]`, `public Share $share`) renders
  `resources/views/livewire/share-created.blade.php`: the link as
  `<x-input :value="route('share.download', $share)" readonly copyable data-test="share-link">`,
  four `<x-stat>`, an info alert for password-protected shares, and "Upload More". The route
  `share/{share:token}/created` sits behind `system.password`, like the upload page.
- The two-factor dialog (`pages/settings/⚡two-factor`) is the in-app pattern: the SVG inline
  on a `bg-white` panel inside `<x-modal fullscreen>`, so it stays scannable in dark mode.
- `<x-modal>` without `wire:model` opens from `open` in the surrounding Alpine scope and gives
  `close()`; `materialToast()` is global; `resources/js/app.js` imports only the package JS.
- Services live in `app/Services` (`ShareService`, `FileEncryptionService`). Share passwords
  are hashed and turned into a key; the plain password is never stored.
- No feature test covers `ShareCreated` yet; `tests/Browser/SealShareTest.php` copies the link
  on that page.

## Decisions

- **Only on the share created page** — that is where a share is handed over; the admin
  dashboard and the download page stay as they are.
- **A "Show QR code" button opens a dialog** — the page stays as calm as now; the dialog is
  `<x-modal fullscreen>` (the whole screen on a phone, to hold up to another camera) with the
  QR on a white panel.
- **Download is a PNG made in the browser** — the dialog's SVG is drawn onto a canvas and saved
  as `share-<token>.png`; no server route and no `gd`/`imagick` in the Docker images.
- **Require `bacon/bacon-qr-code:^3.0` directly** — the version already installed through
  Fortify, declared so SealShare does not depend on Fortify keeping it.
- **Password-protected shares get a note in the dialog** — "Recipients also need the password."
  The QR holds the link only.
- **A "Share…" button opens the native share sheet** — shown only where `navigator.share` exists
  (mostly phones and Safari), sharing `{ title: <site title>, url: <share link> }`.
  Cancelling the sheet (`AbortError`) does nothing; any other failure shows an error snackbar.
- **In 2.0.0, on the `material` branch** — 2.0.0 is not released and the page was just rebuilt
  there; one PR, one changelog entry.
- **Black modules on white, a four-module quiet zone, error correction M** — the most reliable
  to scan from a screen or a print; the site's theme does not tint it.
- **The SVG is drawn at 1024 × 1024** — CSS scales it down in the dialog, and the canvas draws it
  at its own size, so the PNG is sharp in every browser (Safari rasterises an SVG at its
  intrinsic size).
- **Generated server-side with the page, opened client-side** — the SVG is a few kilobytes and
  the dialog needs no round trip; the dialog's `open` is Alpine state, not a Livewire property.
- **`App\Services\QrCodeService::svg(string $contents): string`** — one place that knows Bacon's
  API; `ShareCreated::render()` passes `shareUrl`, `qrCodeSvg` and `siteTitle` to the view (as
  `FileUploader::render()` passes `siteTitle`), so the URL is built once.
- **The share and download behaviour lives in `resources/js/share-created.js`** — an
  `Alpine.data('shareActions', …)` with `canShare`, `share()` and `downloadQrCode()`, imported
  by `app.js`, instead of long inline Alpine in the view.

## Out of scope

- QR codes on the admin dashboard or the download page.
- Sharing the QR image itself through the share sheet (`navigator.share({ files })`).
- An SVG download, a server-rendered PNG, or a print layout.
- A logo in the middle of the QR, or colours from the theme.
- Putting the password (or any secret beyond the link's token) into the QR or the share sheet.

## Implementation steps

1. **Dependency.** `composer require bacon/bacon-qr-code:^3.0` (stays at v3.1.1).
2. **Service.** `php artisan make:class Services/QrCodeService`: `svg(string $contents): string`
   renders with `new Writer(new ImageRenderer(new RendererStyle(1024, 4, null, null,
   Fill::uniformColor(new Rgb(255, 255, 255), new Rgb(0, 0, 0))), new SvgImageBackEnd))`,
   `writeString($contents, Encoder::DEFAULT_BYTE_MODE_ENCODING, ErrorCorrectionLevel::M())`, and
   drops the XML declaration as Fortify does.
3. **Component.** `ShareCreated::render()` builds `$shareUrl = route('share.download',
   $this->share)` and passes `shareUrl`, `qrCodeSvg` (from the service) and `siteTitle`
   (`Setting::get('site_title') ?: config('app.name')`) to the view; the link field uses
   `$shareUrl`.
4. **JavaScript.** `resources/js/share-created.js` registers on `alpine:init`
   `Alpine.data('shareActions', ({ url, title, filename, messages }) => …)`, `messages` holding
   the translated `shareFailed` and `downloadFailed`:
   - `open: false` for the dialog;
   - `canShare`: `typeof navigator.share === 'function'`, read once at init;
   - `share()`: `navigator.share({ title, url })`, ignoring `AbortError`, otherwise
     `materialToast(messages.shareFailed, { type: 'error' })`;
   - `downloadQrCode(svg)`: takes the `<svg>` element (the button passes
     `$el.closest('dialog').querySelector('[data-qr-code] svg')` — the dialog has its own Alpine
     scope, so `$refs` from the outer one would not reach it), serialises it, loads it into an
     `Image` from a Blob URL, draws it on a 1024 × 1024 canvas with a white fill and
     `imageSmoothingEnabled = false`, `toBlob('image/png')`, clicks a temporary `<a download>`
     named `filename`, and revokes both object URLs; a failed load or an empty blob shows
     `materialToast(messages.downloadFailed, { type: 'error' })`.
   `resources/js/app.js` imports it after the package.
5. **View.** In `share-created.blade.php`, wrap the link and actions in
   `<div x-data="shareActions({ url: @js($shareUrl), title: @js($siteTitle), filename: @js('share-'.$share->token.'.png'), messages: @js(['shareFailed' => __('The share sheet could not open.'), 'downloadFailed' => __('The QR code could not be saved.')]) })">`
   (a plain element, so `@js` compiles there):
   - under the link field, a row with `<x-button :label="__('Show QR code')" icon="qr_code_2"
     variant="tonal" x-on:click="open = true" data-test="show-qr-code" />` and, in a
     `<span x-show="canShare" x-cloak>` wrapper, `<x-button :label="__('Share…')" icon="share"
     variant="tonal" x-on:click="share()" data-test="share-sheet" />`;
   - `<x-modal fullscreen :title="__('Scan to open the share')">` holding
     `<div data-qr-code class="mx-auto aspect-square w-full max-w-80 rounded-corner-lg bg-white p-2 [&>svg]:size-full">{!! $qrCodeSvg !!}</div>`
     (the SVG is generated from the app's own URL — no user input), then, for a
     password-protected share, `<x-alert color="info" icon="lock" :title="__('Recipients also need the password.')" />`,
     and actions `<x-button :label="__('Download')" icon="download" x-on:click="downloadQrCode($el.closest('dialog').querySelector('[data-qr-code] svg'))" data-test="download-qr-code" />`
     and `<x-button :label="__('Close')" x-on:click="close()" />`.
   "Upload More" and the stats stay where they are.
6. **Docs.** README: the "Shareable Links" feature line mentions the QR code and share sheet.
   CHANGELOG `2.0.0`: an "Added" section (before "Changed", as Keep a Changelog orders them)
   with an entry for both.

## Testing

- `tests/Unit/QrCodeServiceTest.php` (the service needs no application):
  `svg()` returns markup starting with `<svg`, without an XML declaration, 1024 wide, and the
  same markup for the same contents and different markup for different contents.
- `tests/Feature/ShareCreatedTest.php` (new): the page shows the link, and its HTML contains
  exactly `QrCodeService::svg(route('share.download', $share))` inside the dialog, the
  "Show QR code" and "Share…" buttons, and the download filename `share-<token>.png`; the
  password note appears for a protected share and not for an open one.
- `tests/Browser/SealShareTest.php`:
  - "Show QR code" opens the dialog with the QR on a white panel; Download produces an
    `image/png` blob named `share-<token>.png` (recorded by stubbing
    `HTMLAnchorElement.prototype.click` through `window.eval`), with no JavaScript errors;
  - the Share button is hidden where `navigator.share` is missing, and `share()` passes the
    link to a stubbed `navigator.share`, stays quiet on `AbortError` and shows the error snackbar
    on any other rejection.
- `DesignLanguageTest` keeps passing (`qr_code_2`, `share`, `download` are Material Symbols;
  `bg-white` is a token).
- Narrow runs per step, then the full suite.

## Risks and open questions

- **Scanning reliability** is not proven by the tests (no decoder in the stack): the feature
  test pins the SVG to Bacon's output for the exact URL, and a manual scan with a phone during
  review is the check.
- **The QR is only as right as the link.** Behind a reverse proxy with a wrong `APP_URL` or
  trusted-proxy setting, both point at the wrong host — unchanged from today.
- **Safari and canvas.** Drawing an SVG from a Blob URL onto a canvas works in current
  Chrome, Firefox and Safari without tainting the canvas; the browser test runs in Chromium
  locally and in CI, and the three-engine check is manual.
- **Share sheet on desktop** exists in Safari and Chromium on some platforms and not in
  Firefox; the button's absence there is by design.