Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,11 @@
# secrets, API keys or tokens in this file. PokeGuru needs no API keys.

# Canonical public origin, with no trailing slash, e.g. https://pokeguru.example.com
# Used for canonical links, Open Graph URLs, robots.txt and sitemap.xml.
# Leave empty to derive URLs from the address the app is served from.
# Used for canonical links, Open Graph URLs, robots.txt, sitemap.xml AND the QR
# code on the printable 5 x 7 in flyer.
# Leave empty to derive URLs from the address the app is served from; the flyer
# then refuses to generate a QR code unless that address is a real production
# origin (never localhost, preview or sandbox hosts).
VITE_PUBLIC_SITE_URL=

# "Buy Me a Pack" support destination (a real, verified payment/support page).
Expand Down
55 changes: 52 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,13 @@ and keeps a private collection vault in the browser.
or estimated, shows the modelled tier odds with sources, and keeps simulated
pulls in their own store (`pokeguru_pack_sim_v1`) so they can never leak into
your real collection or its valuation.
- **Offline-tolerant PWA** — app shell cached, clearly labelled cached data, and
a safe update prompt that never traps you on an old version.
- **Printable 5 × 7 in flyer** — one-click, vector, print-ready PDF
(`PokeGuru-5x7-QR-Flyer.pdf`) with a QR code that always points at the live
production site, plus a Print option that opens your print dialogue. Linked
from the footer, the homepage “Share PokeGuru” panel and the About page.
- **Offline-tolerant PWA** — app shell cached, clearly labelled cached data, a
safe update prompt that never traps you on an old version, and an optional
install invitation (“Take PokeGuru with you!”).

---

Expand Down Expand Up @@ -111,7 +116,7 @@ so never put secrets in them.

| Variable | Required | Purpose |
| --- | --- | --- |
| `VITE_PUBLIC_SITE_URL` | no | Canonical origin used for canonical/OG tags, `sitemap.xml` and absolute `robots.txt` entries, e.g. `https://pokeguru.example.com` (no trailing slash). Empty = derive from the browser and skip the sitemap. When set, the build asks TCGdex for the live set list so every `/set/:id` page is listed (static routes only if the API is unreachable). |
| `VITE_PUBLIC_SITE_URL` | **yes for the flyer** | Canonical origin used for canonical/OG tags, `sitemap.xml`, absolute `robots.txt` entries **and the QR code on the printable flyer**, e.g. `https://pokeguru.example.com` (no trailing slash). Empty = derive from the browser and skip the sitemap; for the flyer the served origin is used only when it looks like a real production address (see below). When set, the build asks TCGdex for the live set list so every `/set/:id` page is listed (static routes only if the API is unreachable). |
| `VITE_BUY_ME_A_PACK_URL` | no | A real support/payment page for “Buy Me a Pack”. When empty the call-to-action renders in a clearly labelled *not configured* state — no fabricated link is ever shown. |
| `DEPLOY_TARGET` | no | `github-pages` builds with the `/PokeGuru/` base path. Leave unset for Vercel and other root-hosted deployments. |

Expand All @@ -120,6 +125,42 @@ so never put secrets in them.

---

## 🎴 Printable flyer

Every page footer, the homepage “Share PokeGuru” panel and the About page offer
**🎴 Download PokeGuru Flyer** (and **Print flyer**).

- **File:** `PokeGuru-5x7-QR-Flyer.pdf` — exactly one page, exactly **5 × 7 in
portrait (127 × 177.8 mm = 360 × 504 pt)**. The PDF is generated in the browser
on demand, so it is never a stale checked-in binary: one current design, one
download, no server work.
- **Everything is vector** — text uses the standard Helvetica faces, the artwork
is native PDF paths and the QR code is one rectangle per module, so it stays
sharp at any print resolution.
- **The QR code is verified.** `tests/flyer.test.ts` decodes the generated
matrix with the independent `jsqr` decoder and asserts the payload is the
production URL, and also re-opens the produced PDF to assert the page count
and page box.
- **The production address is enforced.** `src/services/flyer/qr.ts` accepts
`VITE_PUBLIC_SITE_URL` (or, if unset, the origin the app is served from) only
when it is `https`, has no path/query/hash, and is not `localhost`, `127.x`,
`*.local`, a sandbox preview (`*.e2b.app`) or a Vercel preview/branch
deployment. If nothing passes, the buttons show a **configuration warning**
instead of generating a QR code that would not work once printed — no dummy
URLs, ever.
- **Printing:** choose 100% / “Actual size” (never “Fit to page”). The design is
full-bleed dark, so a slightly heavier paper stock keeps it crisp.
- **Wording:** the flyer advertises only shipped features (search, set archive,
collection, real market prices, free virtual packs) and carries an unofficial
fan-project disclaimer. No official artwork, logos, character images or
partnership claims are used.

To point the flyer at your own domain, set `VITE_PUBLIC_SITE_URL` (for example
in the Vercel project’s environment variables) and redeploy; Google Fonts, the
sitemap, canonical tags and the printed QR code all follow that one value.

---

## 🎁 Pack Opening Simulator

| Piece | Where |
Expand Down Expand Up @@ -215,6 +256,14 @@ card.
- Cached/offline data is labelled in the UI.
- Updates are non-blocking: a prompt appears, and `SKIP_WAITING` swaps versions
on your next action instead of pinning an old build.
- **Install invitation** (`src/components/UI/InstallPrompt.tsx`): a branded
“Take PokeGuru with you!” card appears ~7 s after load, only when the browser
can actually install the app (`beforeinstallprompt` has fired) or on iOS,
where it explains the Safari “Add to Home Screen” route instead of pretending
a one-tap prompt exists. The browser’s own install dialogue is opened **only**
after the visitor chooses *Install PokeGuru*; *Maybe later* or a dismissal is
remembered in `localStorage` for 60 days, and the card never appears when the
app is already installed (standalone display mode).

---

Expand Down
62 changes: 60 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@
"@fontsource-variable/space-grotesk": "^5.3.0",
"clsx": "2.1.1",
"lucide-react": "^1.18.0",
"pdf-lib": "^1.17.1",
"qrcode-generator": "^2.0.4",
"react": "19.2.6",
"react-dom": "19.2.6",
"react-router-dom": "^7.17.0",
Expand All @@ -49,6 +51,7 @@
"gh-pages": "^6.3.0",
"globals": "^17.14.0",
"jsdom": "^31.0.1",
"jsqr": "^1.4.0",
"sharp": "^0.35.5",
"tailwindcss": "4.1.17",
"typescript": "5.9.3",
Expand Down
154 changes: 154 additions & 0 deletions src/components/Flyer/FlyerActions.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
import { useMemo, useState } from "react";
import { AlertTriangle, Check, Download, Loader2, Printer } from "lucide-react";
import { cn } from "../../utils/cn";
import { FlyerConfigurationError, downloadFlyer, printFlyer, resolveFlyerOrigin } from "../../services/flyer";

type Status = { tone: "ok" | "warn" | "error"; text: string } | null;

interface FlyerActionsProps {
variant?: "full" | "compact";
className?: string;
/** Show the printer button (kept on for every surface by default). */
showPrint?: boolean;
}

/**
* Download / print controls for the 5 × 7 in promotional flyer.
*
* The PDF is generated in the browser on demand, so the button always hands
* out the current design with a QR code for the live production address — there
* is no stale static file to forget about, and no server work.
*/
export default function FlyerActions({ variant = "full", className, showPrint = true }: FlyerActionsProps) {
const [busy, setBusy] = useState<"download" | "print" | null>(null);
const [status, setStatus] = useState<Status>(null);

const origin = useMemo(() => resolveFlyerOrigin(), []);
const compact = variant === "compact";

const handleDownload = async () => {
if (busy) return;
setBusy("download");
setStatus(null);
try {
const file = await downloadFlyer();
setStatus({
tone: "ok",
text: `Saved ${file.fileName} — ${file.millimetres.width} × ${file.millimetres.height} mm, print at 100%.`,
});
} catch (error) {
setStatus({
tone: error instanceof FlyerConfigurationError ? "warn" : "error",
text:
error instanceof FlyerConfigurationError
? error.message
: "The flyer could not be generated in this browser. Please try again.",
});
} finally {
setBusy(null);
}
};

const handlePrint = async () => {
if (busy) return;
setBusy("print");
setStatus(null);
try {
const { printed } = await printFlyer();
setStatus({
tone: "ok",
text: printed
? "Opened the PDF in a new tab — in the print dialogue choose 100% / Actual size."
: "Your browser blocked the new tab, so the flyer was downloaded instead. Print it at 100%.",
});
} catch (error) {
setStatus({
tone: error instanceof FlyerConfigurationError ? "warn" : "error",
text:
error instanceof FlyerConfigurationError
? error.message
: "The flyer could not be generated in this browser. Please try again.",
});
} finally {
setBusy(null);
}
};

return (
<div className={cn("flex flex-col gap-2", className)}>
<div className="flex flex-wrap items-center gap-2">
<button
type="button"
onClick={handleDownload}
disabled={busy !== null}
className={cn("btn btn-primary no-underline", compact ? "text-xs" : "")}
aria-describedby="flyer-note"
>
{busy === "download" ? (
<Loader2 size={15} className="animate-spin" aria-hidden="true" />
) : (
<Download size={15} aria-hidden="true" />
)}
<span aria-hidden="true">🎴</span> {busy === "download" ? "Generating…" : "Download PokeGuru Flyer"}
</button>

{showPrint && (
<button type="button" onClick={handlePrint} disabled={busy !== null} className={cn("btn btn-secondary", compact ? "text-xs" : "")}>
{busy === "print" ? <Loader2 size={14} className="animate-spin" aria-hidden="true" /> : <Printer size={14} aria-hidden="true" />}
Print flyer
</button>
)}
</div>

{compact ? (
<p id="flyer-note" className="text-[11px] text-[var(--muted)]">
5 × 7 in print-ready PDF · QR links to{" "}
<strong className="text-[var(--text-soft)]">{origin.origin ? origin.host : "the live site once configured"}</strong>
</p>
) : (
<p id="flyer-note" className="text-xs leading-relaxed text-[var(--muted)]">
One-page, print-ready PDF · exactly 5 × 7 in (127 × 177.8 mm) · the QR code links to{" "}
<strong className="text-[var(--text-soft)]">{origin.origin ? origin.host : "the live site once configured"}</strong>. Free to
download, print and share — no account needed.
</p>
)}

<div aria-live="polite" className="empty:hidden">
{status && (
<p
className={cn(
"flex items-start gap-1.5 rounded-lg border px-2.5 py-1.5 text-[11px] leading-relaxed",
status.tone === "ok" && "border-[var(--success)]/35 bg-[var(--success-soft)] text-[var(--success)]",
status.tone === "warn" && "border-[var(--accent-2)]/40 bg-[var(--warning-soft)] text-[var(--accent-2)]",
status.tone === "error" && "border-[var(--accent)]/40 bg-[var(--bg-elevated)] text-[var(--accent-text)]"
)}
>
{status.tone === "ok" ? (
<Check size={12} className="mt-0.5 shrink-0" aria-hidden="true" />
) : (
<AlertTriangle size={12} className="mt-0.5 shrink-0" aria-hidden="true" />
)}
<span>{status.text}</span>
</p>
)}
</div>

{!origin.origin && (
<p className="flex items-start gap-1.5 rounded-lg border border-[var(--accent-2)]/40 bg-[var(--warning-soft)] px-2.5 py-2 text-[11px] leading-relaxed text-[var(--accent-2)]">
<AlertTriangle size={12} className="mt-0.5 shrink-0" aria-hidden="true" />
<span>
<strong>Flyer not configured:</strong> set <code className="font-mono">VITE_PUBLIC_SITE_URL</code> to the live site address and
rebuild, so the printed QR code can never point at a preview deployment.
</span>
</p>
)}

{!compact && (
<p className="text-[10px] leading-relaxed text-[var(--muted-dim)]">
Wrapper artwork and logo are original PokeGuru designs. Promotional flyer for an unofficial fan-made companion — no physical
cards are supplied and there is no affiliation with The Pokémon Company.
</p>
)}
</div>
);
}
Loading
Loading