qrdamage/specs/chatgpt_0.1.0.md

QR Code Generator Website Spec v0.1.0

1) Purpose

Provide a tiny, static website that generates a QR code for a URL entirely on the user’s device.

2) Key constraints

• No backend. After the initial page load, the app performs no network communication of any kind.
• Extremely fast to load. Minimal assets, minimal JS, no frameworks.
• Traditional web. Plain HTML + CSS + vanilla JS; no dynamic imports, no runtime downloads.
• Pleasant, subtle UI. Simple, elegant styling using basic CSS and system fonts.

---

3) Functional requirements

3.1 Inputs

• A single text input labelled URL.
• User can paste or type a URL.

3.2 Validation & normalization

• The app should treat the input as a URL string to encode.
• If the user enters a value without a scheme (e.g. example.com), normalize by prefixing https://.
• If the value cannot reasonably be treated as a URL, display a short error message and do not generate a QR code.

3.3 QR generation

• Generate a QR code from the normalized URL locally in the browser.
• Display the QR code preview immediately after valid input is present.
• Update the preview as the input changes (debounced to prevent jank while typing).

3.4 Export

• Provide a single action: Download PNG.
• The downloaded PNG must match the currently displayed QR code.
• Default PNG size: choose one sensible size for v0.1.0 (e.g. 512×512) and keep it fixed for now.

3.5 Reset

• Provide a Clear action that empties the input and removes the QR preview (or replaces it with a placeholder state).

---

4) UX and UI requirements

4.1 Layout

Single page, centered column:

• Title: “QR Code Generator”
• URL input
• Inline validation/error text (only when needed)
• QR preview area (shows placeholder state when empty)
• Actions row: Download PNG, Clear

4.2 Styling

• Use system font stack only.
• Subtle borders, light spacing, modest rounding.
• No heavy animation; at most a very subtle transition on preview update.
• Responsive: usable on mobile and desktop; input and buttons are comfortably tappable.

4.3 Accessibility

• Label associated with input (<label for=...>).
• Keyboard navigation works (Tab order sensible).
• Visible focus styles.
• Error text is readable and associated with the input.

---

5) Performance requirements

5.1 Load performance

• Ship as a static site: either a single index.html with inline CSS/JS or small separate files (style.css, app.js).
• No external resources (no CDNs, no hosted fonts, no analytics scripts).
• Keep total compressed payload small (target: “tiny”; exact budget can be decided later).

5.2 Runtime performance

• Input-to-preview updates should feel instantaneous for normal URLs.
• Use a short debounce (e.g. ~100 ms) on typing updates.

---

6) Privacy & security requirements

6.1 Offline after load

• After initial page load, no fetch, XHR, beacons, websockets, or external resource loads.
• No third-party assets referenced by URL.

6.2 Recommended hardening (static-friendly)

• Include a Content Security Policy (CSP) that blocks external connections and limits resource sources to self.
• Do not persist user input (no localStorage) in v0.1.0.

---

7) Browser support

• Must work on current Chrome, Firefox, Safari, and Edge.
• If any export feature is unsupported in a given browser, present a clear message (though PNG download should be broadly supported).

---

8) Technical approach

8.1 Implementation style

• Vanilla JS and DOM APIs only.
• No framework, no build step required (build step optional only if it materially reduces size).

8.2 QR generation dependency

• Use a small, permissively licensed QR generation library vendored into the repository (bundled or included locally).
• The library must not perform network requests.
• Keep the dependency footprint minimal.

8.3 Rendering

• Render QR to a <canvas> for preview.
• PNG download should be produced from the same canvas.

---

9) Acceptance criteria (testable)

• With devtools Network tab open: after initial load, interacting with the page triggers zero network requests.
• Pasting https://example.com produces a scannable QR code.
• Entering example.com produces a QR code for https://example.com.
• Entering invalid input shows an error and does not generate a QR code.
• “Download PNG” downloads a PNG that scans correctly.
• “Clear” resets the UI to the initial state.

---

10) Deliverables

• Static site files:

  • index.html
  • (optional) style.css, app.js
  • vendored QR library file(s)

• README:

  • how to run locally (open file vs local static server)
  • how to deploy (any static hosting)
  • privacy statement: “runs entirely in your browser; no network after load”

---

Notes for later versions (explicitly out of scope for v0.1.0)

• Customisation options (error correction, sizes, colors, margins)
• Content types beyond URL
• SVG export
• PWA/offline installability
• Persistence of settings/history
• Explicit max data length/QR version targets