From 7a7ef23ca711a6adc29e7079360c41b10c07e7dd Mon Sep 17 00:00:00 2001
From: Zeeshan Tariq <zeeshan.ghazi@yahoo.com>
Date: Wed, 22 Apr 2026 15:49:28 +0500
Subject: [PATCH] adds pearls a receipt recording app

---
 package.json                                  |   1 +
 src/alex_frontend/core/config/apps.ts         |   4 +-
 .../features/pearl/components/FieldError.tsx  |  19 +
 .../pearl/components/HeaderFields.tsx         | 129 ++++++
 .../features/pearl/components/LineItemRow.tsx | 193 +++++++++
 .../pearl/components/LineItemsEditor.tsx      |  69 ++++
 .../features/pearl/components/NotesField.tsx  |  31 ++
 .../pearl/components/PaymentSection.tsx       |  59 +++
 .../features/pearl/components/PearlForm.tsx   |  88 ++++
 .../features/pearl/components/TagsInput.tsx   |  82 ++++
 .../features/pearl/components/TapePreview.tsx | 138 +++++++
 .../pearl/components/TaxLinesEditor.tsx       |  95 +++++
 .../core/features/pearl/components/Totals.tsx |  59 +++
 .../core/features/pearl/constants.ts          |  65 +++
 .../features/pearl/hooks/useComputedTotals.ts |  46 +++
 .../features/pearl/hooks/useMintReceipt.ts    |  74 ++++
 src/alex_frontend/core/features/pearl/plan.md |   7 +
 .../core/features/pearl/schema.ts             |  58 +++
 .../features/pearl/utils/buildArweaveTags.ts  |  84 ++++
 .../features/pearl/utils/renderTapeImage.ts   |  57 +++
 .../features/perpetua/actions/AddItem.tsx     |  47 ++-
 .../perpetua/components/ShelfDetail.tsx       |  57 ++-
 src/alex_frontend/lbry/public/logos/Pearl.svg |  33 ++
 src/alex_frontend/lbry/routeTree.gen.ts       |  23 ++
 .../lbry/src/components/Tabs/AppsTab.tsx      |   2 +-
 .../lbry/src/pages/pearl/PearlPage.tsx        | 382 ++++++++++++++++++
 .../lbry/src/routes/_auth/app/pearl.lazy.tsx  |   6 +
 27 files changed, 1900 insertions(+), 8 deletions(-)
 create mode 100644 src/alex_frontend/core/features/pearl/components/FieldError.tsx
 create mode 100644 src/alex_frontend/core/features/pearl/components/HeaderFields.tsx
 create mode 100644 src/alex_frontend/core/features/pearl/components/LineItemRow.tsx
 create mode 100644 src/alex_frontend/core/features/pearl/components/LineItemsEditor.tsx
 create mode 100644 src/alex_frontend/core/features/pearl/components/NotesField.tsx
 create mode 100644 src/alex_frontend/core/features/pearl/components/PaymentSection.tsx
 create mode 100644 src/alex_frontend/core/features/pearl/components/PearlForm.tsx
 create mode 100644 src/alex_frontend/core/features/pearl/components/TagsInput.tsx
 create mode 100644 src/alex_frontend/core/features/pearl/components/TapePreview.tsx
 create mode 100644 src/alex_frontend/core/features/pearl/components/TaxLinesEditor.tsx
 create mode 100644 src/alex_frontend/core/features/pearl/components/Totals.tsx
 create mode 100644 src/alex_frontend/core/features/pearl/constants.ts
 create mode 100644 src/alex_frontend/core/features/pearl/hooks/useComputedTotals.ts
 create mode 100644 src/alex_frontend/core/features/pearl/hooks/useMintReceipt.ts
 create mode 100644 src/alex_frontend/core/features/pearl/plan.md
 create mode 100644 src/alex_frontend/core/features/pearl/schema.ts
 create mode 100644 src/alex_frontend/core/features/pearl/utils/buildArweaveTags.ts
 create mode 100644 src/alex_frontend/core/features/pearl/utils/renderTapeImage.ts
 create mode 100644 src/alex_frontend/lbry/public/logos/Pearl.svg
 create mode 100644 src/alex_frontend/lbry/src/pages/pearl/PearlPage.tsx
 create mode 100644 src/alex_frontend/lbry/src/routes/_auth/app/pearl.lazy.tsx

diff --git a/package.json b/package.json
index 047b13852..ab2e67d96 100644
--- a/package.json
+++ b/package.json
@@ -94,6 +94,7 @@
 		"flatted": "^3.3.1",
 		"formik": "^2.4.6",
 		"graphql": "^16.11.0",
+		"html-to-image": "^1.11.13",
 		"html-to-text": "^9.0.5",
 		"human-crypto-keys": "^0.1.4",
 		"ic-mops": "^1.0.1",
diff --git a/src/alex_frontend/core/config/apps.ts b/src/alex_frontend/core/config/apps.ts
index 003625415..ebd685ba2 100644
--- a/src/alex_frontend/core/config/apps.ts
+++ b/src/alex_frontend/core/config/apps.ts
@@ -5,6 +5,7 @@ export interface App {
 	path: string;
 	logo?: string;
 	comingSoon?: boolean;
+	hideFromHeader?: boolean;
 }
 
 export const appsData: App[] = [
@@ -12,8 +13,9 @@ export const appsData: App[] = [
 	{ name: 'Alexandrian', description: 'Library', path: '/app/alexandrian', logo: '/logos/Alexandrian.svg' },
 	{ name: 'Permasearch', description: 'Explore', path: '/app/permasearch', logo: '/logos/Permasearch.svg' },
 	{ name: 'Emporium', description: 'Trade', path: '/app/emporium', logo: '/logos/Emporium.svg' },
-	{ name: 'Pinax', description: 'Upload', path: '/app/pinax', logo: '/logos/Pinax.svg', comingSoon: false },
 	{ name: 'Sonora', description: 'Audio', path: '/app/sonora', logo: '/logos/Sonora.svg' },
+	{ name: 'Pinax', description: 'Upload', path: '/app/pinax', logo: '/logos/Pinax.svg', comingSoon: false, hideFromHeader: true },
+	{ name: 'Pearl', description: 'Receipt', path: '/app/pearl', logo: '/logos/Pearl.svg', comingSoon: false, hideFromHeader: true },
 	{ name: 'Syllogos', description: 'Aggregate', path: '/app/syllogos', logo: '/logos/Syllogos.svg', comingSoon: true },
 	{ name: 'Bibliotheca', description: 'Library', path: '/app/bibliotheca', comingSoon: true },
 	{ name: 'Dialectica', description: 'Debate', path: '/app/dialectica', comingSoon: true },
diff --git a/src/alex_frontend/core/features/pearl/components/FieldError.tsx b/src/alex_frontend/core/features/pearl/components/FieldError.tsx
new file mode 100644
index 000000000..241e15537
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/components/FieldError.tsx
@@ -0,0 +1,19 @@
+import React from "react";
+import { useFormikContext, getIn } from "formik";
+
+/**
+ * Renders a Yup/Formik error for a (possibly nested) field path, gated on the
+ * field being touched. Safe for paths like `items[0].description` or
+ * `taxLines[2].ratePercent` via Formik's `getIn`.
+ */
+export function FieldError({ name }: { name: string }) {
+  const { errors, touched } = useFormikContext<unknown>();
+  const error = getIn(errors, name);
+  const isTouched = getIn(touched, name);
+  if (!isTouched || !error) return null;
+  return (
+    <p className="text-xs text-red-500 dark:text-red-400 mt-1">
+      {String(error)}
+    </p>
+  );
+}
diff --git a/src/alex_frontend/core/features/pearl/components/HeaderFields.tsx b/src/alex_frontend/core/features/pearl/components/HeaderFields.tsx
new file mode 100644
index 000000000..92f63e5c2
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/components/HeaderFields.tsx
@@ -0,0 +1,129 @@
+import React, { useState } from "react";
+import { useFormikContext } from "formik";
+import { ChevronDown, Check } from "lucide-react";
+import { Input } from "@/lib/components/input";
+import { Button } from "@/lib/components/button";
+import { Label } from "@/lib/components/label";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/lib/components/popover";
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@/lib/components/command";
+import type { Receipt } from "../schema";
+import { CURRENCIES } from "../constants";
+import { FieldError } from "./FieldError";
+
+const labelClass =
+  "text-xs font-medium text-gray-700 dark:text-gray-300 font-roboto-condensed";
+
+export function HeaderFields() {
+  const { values, handleChange, setFieldValue } = useFormikContext<Receipt>();
+
+  return (
+    <div className="grid grid-cols-1 sm:grid-cols-4 gap-4">
+      <div className="sm:col-span-2 space-y-1.5">
+        <Label htmlFor="merchant" className={labelClass}>
+          Merchant
+        </Label>
+        <Input
+          id="merchant"
+          name="merchant"
+          value={values.merchant}
+          onChange={handleChange}
+          placeholder="e.g. Tartine Bakery"
+          autoComplete="off"
+          scale="sm"
+          rounded="md"
+          className="h-8"
+        />
+        <FieldError name="merchant" />
+      </div>
+
+      <div className="sm:col-span-1 space-y-1.5">
+        <Label htmlFor="date" className={labelClass}>
+          Date
+        </Label>
+        <Input
+          id="date"
+          name="date"
+          type="date"
+          value={values.date}
+          onChange={handleChange}
+          scale="sm"
+          rounded="md"
+          className="h-8"
+        />
+        <FieldError name="date" />
+      </div>
+
+      <div className="sm:col-span-1 space-y-1.5">
+        <Label className={labelClass}>Currency</Label>
+        <CurrencyPicker
+          value={values.currency}
+          onChange={code => setFieldValue("currency", code)}
+        />
+      </div>
+    </div>
+  );
+}
+
+/** Currency combobox, styled to match the surrounding inputs (rounded-md,
+ *  same border + fill) so it reads as part of the header row. */
+function CurrencyPicker({
+  value,
+  onChange,
+}: {
+  value: string;
+  onChange: (code: string) => void;
+}) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          type="button"
+          variant="outline"
+          scale="sm"
+          rounded="md"
+          className="h-8 w-full justify-between font-mono font-semibold border-gray-400 bg-white dark:bg-gray-800"
+        >
+          <span>{value}</span>
+          <ChevronDown size={14} className="opacity-60" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="p-0 w-64" align="end">
+        <Command>
+          <CommandInput placeholder="Search currency..." />
+          <CommandList>
+            <CommandEmpty>No currency found.</CommandEmpty>
+            <CommandGroup>
+              {CURRENCIES.map(c => (
+                <CommandItem
+                  key={c.code}
+                  value={`${c.code} ${c.name}`}
+                  onSelect={() => {
+                    onChange(c.code);
+                    setOpen(false);
+                  }}
+                >
+                  <span className="font-mono font-semibold w-12">{c.code}</span>
+                  <span className="flex-1 text-xs text-gray-500">{c.name}</span>
+                  {c.code === value && <Check size={14} className="ml-2" />}
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  );
+}
diff --git a/src/alex_frontend/core/features/pearl/components/LineItemRow.tsx b/src/alex_frontend/core/features/pearl/components/LineItemRow.tsx
new file mode 100644
index 000000000..c63a8aec7
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/components/LineItemRow.tsx
@@ -0,0 +1,193 @@
+import React from "react";
+import { FieldArray, useFormikContext } from "formik";
+import { nanoid } from "nanoid";
+import { Plus, X } from "lucide-react";
+import { Input } from "@/lib/components/input";
+import { Button } from "@/lib/components/button";
+import type { Receipt, LineItem, LineItemChild } from "../schema";
+import { useComputedTotals } from "../hooks/useComputedTotals";
+import { FieldError } from "./FieldError";
+
+interface LineItemRowProps {
+  item: LineItem;
+  index: number;
+  onRemove: () => void;
+}
+
+const numericInputClass = "font-mono tabular-nums text-right";
+
+export function LineItemRow({ item, index, onRemove }: LineItemRowProps) {
+  const { handleChange, setFieldValue } = useFormikContext<Receipt>();
+  const totals = useComputedTotals();
+  const hasChildren = item.children.length > 0;
+  const namePrefix = `items[${index}]`;
+
+  return (
+    <div className="space-y-1.5 pt-2 first:pt-0">
+      <div className="grid grid-cols-12 gap-2 items-center">
+        <div className="col-span-5">
+          <Input
+            name={`${namePrefix}.description`}
+            value={item.description}
+            onChange={handleChange}
+            placeholder="Item description"
+            scale="sm"
+            rounded="md"
+          />
+          <FieldError name={`${namePrefix}.description`} />
+        </div>
+        <div className="col-span-2">
+          <Input
+            name={`${namePrefix}.quantity`}
+            type="number"
+            min={0}
+            step="any"
+            value={item.quantity}
+            onChange={handleChange}
+            placeholder="Qty"
+            scale="sm"
+            rounded="md"
+            className={numericInputClass}
+          />
+          <FieldError name={`${namePrefix}.quantity`} />
+        </div>
+        <div className="col-span-2">
+          <Input
+            name={`${namePrefix}.unitPrice`}
+            type="number"
+            min={0}
+            step="any"
+            value={item.unitPrice ?? ""}
+            onChange={handleChange}
+            disabled={hasChildren}
+            placeholder={hasChildren ? "bundle" : "0.00"}
+            scale="sm"
+            rounded="md"
+            className={numericInputClass}
+          />
+          {!hasChildren && <FieldError name={`${namePrefix}.unitPrice`} />}
+        </div>
+        <div className="col-span-2 flex items-center justify-end pr-1 text-sm font-mono tabular-nums text-gray-900 dark:text-gray-100">
+          {totals.itemTotal(item).toFixed(2)}
+        </div>
+        <div className="col-span-1 flex items-center justify-end">
+          <Button type="button" variant="ghost" scale="icon" onClick={onRemove} aria-label="Remove item">
+            <X size={14} />
+          </Button>
+        </div>
+      </div>
+
+      <FieldArray name={`${namePrefix}.children`}>
+        {({ push, remove }) => {
+          if (item.children.length === 0) {
+            return (
+              <Button
+                type="button"
+                variant="muted"
+                scale="sm"
+                onClick={() => {
+                  setFieldValue(`${namePrefix}.unitPrice`, null);
+                  push({ id: nanoid(), description: "", quantity: 1, unitPrice: 0 });
+                }}
+              >
+                <Plus size={12} /> add sub-item
+              </Button>
+            );
+          }
+          return (
+            <div className="relative">
+              {/* Left rule spans the whole sub-items block; only the
+                  description column is visually indented. Qty / Unit / Total /
+                  actions stay in the same x-position as the parent row. */}
+              <div
+                aria-hidden
+                className="absolute left-2 top-0 bottom-7 border-l-2 border-gray-200 dark:border-gray-800"
+              />
+              <div className="space-y-1.5">
+              {item.children.map((child: LineItemChild, ci: number) => {
+                const cPrefix = `${namePrefix}.children[${ci}]`;
+                return (
+                  <div key={child.id} className="grid grid-cols-12 gap-2 items-center">
+                    <div className="col-span-5 pl-6">
+                      <Input
+                        name={`${cPrefix}.description`}
+                        value={child.description}
+                        onChange={handleChange}
+                        placeholder="Sub-item"
+                        scale="sm"
+                        rounded="md"
+                      />
+                      <FieldError name={`${cPrefix}.description`} />
+                    </div>
+                    <div className="col-span-2">
+                      <Input
+                        name={`${cPrefix}.quantity`}
+                        type="number"
+                        min={0}
+                        step="any"
+                        value={child.quantity}
+                        onChange={handleChange}
+                        placeholder="Qty"
+                        scale="sm"
+                        rounded="md"
+                        className={numericInputClass}
+                      />
+                      <FieldError name={`${cPrefix}.quantity`} />
+                    </div>
+                    <div className="col-span-2">
+                      <Input
+                        name={`${cPrefix}.unitPrice`}
+                        type="number"
+                        min={0}
+                        step="any"
+                        value={child.unitPrice}
+                        onChange={handleChange}
+                        placeholder="0.00"
+                        scale="sm"
+                        rounded="md"
+                        className={numericInputClass}
+                      />
+                      <FieldError name={`${cPrefix}.unitPrice`} />
+                    </div>
+                    <div className="col-span-2 flex items-center justify-end pr-1 text-sm font-mono tabular-nums text-gray-700 dark:text-gray-300">
+                      {(child.quantity * child.unitPrice).toFixed(2)}
+                    </div>
+                    <div className="col-span-1 flex items-center justify-end">
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        scale="icon"
+                        onClick={() => {
+                          remove(ci);
+                          if (item.children.length === 1) {
+                            setFieldValue(`${namePrefix}.unitPrice`, 0);
+                          }
+                        }}
+                        aria-label="Remove sub-item"
+                      >
+                        <X size={12} />
+                      </Button>
+                    </div>
+                  </div>
+                );
+              })}
+              </div>
+              <div className="pl-6">
+                <Button
+                  type="button"
+                  variant="muted"
+                  scale="sm"
+                  onClick={() =>
+                    push({ id: nanoid(), description: "", quantity: 1, unitPrice: 0 })
+                  }
+                >
+                  <Plus size={12} /> add sub-item
+                </Button>
+              </div>
+            </div>
+          );
+        }}
+      </FieldArray>
+    </div>
+  );
+}
diff --git a/src/alex_frontend/core/features/pearl/components/LineItemsEditor.tsx b/src/alex_frontend/core/features/pearl/components/LineItemsEditor.tsx
new file mode 100644
index 000000000..aa7d0b77f
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/components/LineItemsEditor.tsx
@@ -0,0 +1,69 @@
+import React from "react";
+import { FieldArray, useFormikContext } from "formik";
+import { nanoid } from "nanoid";
+import { Plus } from "lucide-react";
+import { Button } from "@/lib/components/button";
+import type { Receipt } from "../schema";
+import { CURRENCIES } from "../constants";
+import { LineItemRow } from "./LineItemRow";
+
+export function LineItemsEditor() {
+  // Use submitCount (not touched.items): Formik's touch-all on failed submit
+  // walks `values` and can't mark leaves of an empty array, so touched.items
+  // stays undefined even after a submit attempt on an empty list.
+  const { values, errors, submitCount } = useFormikContext<Receipt>();
+  const symbol =
+    CURRENCIES.find(c => c.code === values.currency)?.symbol ?? values.currency;
+
+  return (
+    <FieldArray name="items">
+      {({ push, remove }) => (
+        <div className="space-y-2">
+          {values.items.length > 0 && (
+            <>
+              <div className="hidden sm:grid grid-cols-12 gap-2 text-[10px] font-semibold uppercase tracking-[0.12em] text-gray-500 dark:text-gray-400">
+                <div className="col-span-5">Description</div>
+                <div className="col-span-2 text-right">Qty</div>
+                <div className="col-span-2 text-right">Unit ({symbol})</div>
+                <div className="col-span-2 text-right">Total</div>
+                <div className="col-span-1" />
+              </div>
+
+              <div className="divide-y-2 divide-dotted divide-gray-300 dark:divide-gray-700 space-y-2">
+                {values.items.map((item, i) => (
+                  <LineItemRow
+                    key={item.id}
+                    item={item}
+                    index={i}
+                    onRemove={() => remove(i)}
+                  />
+                ))}
+              </div>
+            </>
+          )}
+
+          <Button
+            type="button"
+            variant="muted"
+            scale="sm"
+            onClick={() =>
+              push({
+                id: nanoid(),
+                description: "",
+                quantity: 1,
+                unitPrice: 0,
+                children: [],
+              })
+            }
+          >
+            <Plus size={13} /> Add item
+          </Button>
+
+          {typeof errors.items === "string" && submitCount > 0 && (
+            <p className="text-xs text-red-500 dark:text-red-400">{errors.items}</p>
+          )}
+        </div>
+      )}
+    </FieldArray>
+  );
+}
diff --git a/src/alex_frontend/core/features/pearl/components/NotesField.tsx b/src/alex_frontend/core/features/pearl/components/NotesField.tsx
new file mode 100644
index 000000000..7329e35ab
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/components/NotesField.tsx
@@ -0,0 +1,31 @@
+import React from "react";
+import { useFormikContext } from "formik";
+import { Label } from "@/lib/components/label";
+import { Textarea } from "@/lib/components/textarea";
+import type { Receipt } from "../schema";
+
+export function NotesField() {
+  const { values, handleChange } = useFormikContext<Receipt>();
+  const count = values.notes.length;
+  return (
+    <div className="space-y-1.5">
+      <div className="flex items-baseline justify-between">
+        <Label htmlFor="notes" className="text-xs font-medium text-gray-700 dark:text-gray-300 font-roboto-condensed">
+          Notes
+        </Label>
+        <span className="text-[11px] text-gray-600 dark:text-gray-400 tabular-nums">
+          {count}/2000
+        </span>
+      </div>
+      <Textarea
+        id="notes"
+        name="notes"
+        value={values.notes}
+        onChange={handleChange}
+        placeholder="Optional — why you bought this, who reimbursed, etc."
+        rows={3}
+        className="font-roboto-condensed text-sm border-gray-400 rounded-md bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100 placeholder:text-gray-400 dark:placeholder:text-gray-500 focus-visible:ring-0 focus-visible:ring-offset-0 focus-visible:border-gray-900 dark:focus-visible:border-gray-200 resize-none"
+      />
+    </div>
+  );
+}
diff --git a/src/alex_frontend/core/features/pearl/components/PaymentSection.tsx b/src/alex_frontend/core/features/pearl/components/PaymentSection.tsx
new file mode 100644
index 000000000..e4edbc181
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/components/PaymentSection.tsx
@@ -0,0 +1,59 @@
+import React from "react";
+import { useFormikContext } from "formik";
+import { Input } from "@/lib/components/input";
+import { Button } from "@/lib/components/button";
+import { Label } from "@/lib/components/label";
+import type { Receipt } from "../schema";
+import {
+  PAYMENT_METHODS,
+  PAYMENT_METHOD_LABELS,
+  type PaymentMethod,
+} from "../constants";
+import { FieldError } from "./FieldError";
+
+export function PaymentSection() {
+  const { values, handleChange, setFieldValue } = useFormikContext<Receipt>();
+
+  return (
+    <div className="space-y-3">
+      <div className="flex flex-wrap items-center gap-1.5">
+        {PAYMENT_METHODS.map(m => {
+          const active = values.paymentMethod === m;
+          return (
+            <Button
+              key={m}
+              type="button"
+              variant="outline"
+              scale="sm"
+              rounded="full"
+              onClick={() => setFieldValue("paymentMethod", m as PaymentMethod)}
+              className={`h-6 text-xs ${active ? "bg-gray-900 text-white border-gray-900 hover:bg-gray-800 hover:text-white dark:bg-gray-100 dark:text-gray-900 dark:border-gray-100 dark:hover:bg-gray-200" : ""}`}
+            >
+              {PAYMENT_METHOD_LABELS[m]}
+            </Button>
+          );
+        })}
+      </div>
+      <FieldError name="paymentMethod" />
+
+      <div className="space-y-1.5">
+        <Label
+          htmlFor="paymentNote"
+          className="text-xs font-medium text-gray-700 dark:text-gray-300 font-roboto-condensed"
+        >
+          Note
+        </Label>
+        <Input
+          id="paymentNote"
+          name="paymentNote"
+          value={values.paymentNote}
+          onChange={handleChange}
+          placeholder="e.g. Visa ending 4242 (optional)"
+          scale="sm"
+          rounded="md"
+        />
+        <FieldError name="paymentNote" />
+      </div>
+    </div>
+  );
+}
diff --git a/src/alex_frontend/core/features/pearl/components/PearlForm.tsx b/src/alex_frontend/core/features/pearl/components/PearlForm.tsx
new file mode 100644
index 000000000..79520ba30
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/components/PearlForm.tsx
@@ -0,0 +1,88 @@
+import React from "react";
+import { Form } from "formik";
+import { Send } from "lucide-react";
+import { Button } from "@/lib/components/button";
+import { Card, CardContent } from "@/lib/components/card";
+import { HeaderFields } from "./HeaderFields";
+import { LineItemsEditor } from "./LineItemsEditor";
+import { TaxLinesEditor } from "./TaxLinesEditor";
+import { Totals } from "./Totals";
+import { PaymentSection } from "./PaymentSection";
+import { TagsInput } from "./TagsInput";
+import { NotesField } from "./NotesField";
+
+interface PearlFormProps {
+  /** Disables the submit button while a mint is in flight. */
+  isSubmitting?: boolean;
+}
+
+export function PearlForm({ isSubmitting }: PearlFormProps) {
+  return (
+    <Form className="space-y-5 font-roboto-condensed">
+      <Section>
+        <HeaderFields />
+      </Section>
+
+      <Section title="Line items">
+        <LineItemsEditor />
+      </Section>
+
+      <Section title="Taxes">
+        <TaxLinesEditor />
+      </Section>
+
+      <Section title="Summary">
+        <Totals />
+      </Section>
+
+      <Section title="Payment">
+        <PaymentSection />
+      </Section>
+
+      <Section title="Extras">
+        <div className="space-y-5">
+          <TagsInput />
+          <NotesField />
+        </div>
+      </Section>
+
+      <div className="flex items-center justify-between gap-4 pt-1">
+        <p className="text-xs text-gray-600 dark:text-gray-400">
+          Minting is permanent — this cannot be undone.
+        </p>
+        <Button
+          type="submit"
+          variant="info"
+          scale="sm"
+          rounded="md"
+          disabled={isSubmitting}
+        >
+          <Send size={13} className="mr-1.5" />
+          Save &amp; Mint
+        </Button>
+      </div>
+    </Form>
+  );
+}
+
+/** Section = small uppercase title *above* a shadcn Card. */
+function Section({
+  title,
+  children,
+}: {
+  title?: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="space-y-1">
+      {title && (
+        <h2 className="text-base font-semibold uppercase tracking-wider text-gray-800 dark:text-gray-100 px-1">
+          {title}
+        </h2>
+      )}
+      <Card className="dark:bg-gray-900 dark:border-gray-800">
+        <CardContent className="p-4">{children}</CardContent>
+      </Card>
+    </div>
+  );
+}
diff --git a/src/alex_frontend/core/features/pearl/components/TagsInput.tsx b/src/alex_frontend/core/features/pearl/components/TagsInput.tsx
new file mode 100644
index 000000000..8f80316d0
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/components/TagsInput.tsx
@@ -0,0 +1,82 @@
+import React, { useState, KeyboardEvent } from "react";
+import { useFormikContext } from "formik";
+import { X } from "lucide-react";
+import { Input } from "@/lib/components/input";
+import { Button } from "@/lib/components/button";
+import { Label } from "@/lib/components/label";
+import type { Receipt } from "../schema";
+
+const MAX_TAGS = 20;
+const MAX_TAG_LEN = 40;
+
+export function TagsInput() {
+  const { values, setFieldValue } = useFormikContext<Receipt>();
+  const [draft, setDraft] = useState("");
+
+  const addTag = (raw: string) => {
+    const v = raw.trim().toLowerCase();
+    if (!v) return;
+    if (values.tags.includes(v)) return;
+    if (values.tags.length >= MAX_TAGS) return;
+    if (v.length > MAX_TAG_LEN) return;
+    setFieldValue("tags", [...values.tags, v]);
+    setDraft("");
+  };
+
+  const removeTag = (t: string) => {
+    setFieldValue("tags", values.tags.filter(x => x !== t));
+  };
+
+  const onKey = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === "Enter" || e.key === ",") {
+      e.preventDefault();
+      addTag(draft);
+    } else if (e.key === "Backspace" && !draft && values.tags.length > 0) {
+      removeTag(values.tags[values.tags.length - 1]);
+    }
+  };
+
+  return (
+    <div className="space-y-1.5">
+      <div className="flex items-baseline justify-between">
+        <Label className="text-xs font-medium text-gray-700 dark:text-gray-300 font-roboto-condensed">
+          Tags
+        </Label>
+        <span className="text-[11px] text-gray-600 dark:text-gray-400 tabular-nums">
+          {values.tags.length}/{MAX_TAGS}
+        </span>
+      </div>
+      <div className="flex flex-wrap gap-1.5 items-center px-2 py-1.5 rounded-md border border-gray-400 bg-white dark:bg-gray-800 min-h-[36px] focus-within:border-gray-900 dark:focus-within:border-gray-200 transition-colors">
+        {values.tags.map(t => (
+          <span
+            key={t}
+            className="inline-flex items-center gap-1 h-6 pl-2.5 pr-1 rounded-full text-[11px] font-medium border bg-gray-100 border-gray-300 text-gray-800 dark:bg-gray-700 dark:border-gray-600 dark:text-gray-100"
+          >
+            {t}
+            <Button
+              type="button"
+              variant="ghost"
+              scale="icon"
+              rounded="full"
+              onClick={() => removeTag(t)}
+              aria-label={`Remove tag ${t}`}
+              className="h-4 w-4"
+            >
+              <X size={10} />
+            </Button>
+          </span>
+        ))}
+        <Input
+          value={draft}
+          onChange={e => setDraft(e.target.value)}
+          onKeyDown={onKey}
+          onBlur={() => addTag(draft)}
+          placeholder={values.tags.length === 0 ? "Type a tag, press Enter or comma" : ""}
+          scale="sm"
+          rounded="md"
+          className="flex-1 min-w-[120px] border-0 shadow-none focus-visible:ring-0 px-1 h-6 bg-transparent"
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/src/alex_frontend/core/features/pearl/components/TapePreview.tsx b/src/alex_frontend/core/features/pearl/components/TapePreview.tsx
new file mode 100644
index 000000000..1fe9c4433
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/components/TapePreview.tsx
@@ -0,0 +1,138 @@
+import React, { forwardRef } from "react";
+import { useFormikContext } from "formik";
+import type { Receipt } from "../schema";
+import { useComputedTotals } from "../hooks/useComputedTotals";
+import { CURRENCIES } from "../constants";
+
+interface TapePreviewProps {
+  /** Enlarged version shown in the confirm modal. */
+  size?: "sidebar" | "large";
+}
+
+/**
+ * Thermal tape render. Always cream-paper in both light and dark modes.
+ * Reads form state via Formik context so it re-renders live.
+ * Exposes a ref so html2canvas can capture the node on save.
+ */
+export const TapePreview = forwardRef<HTMLDivElement, TapePreviewProps>(
+  function TapePreview({ size = "sidebar" }, ref) {
+    const { values } = useFormikContext<Receipt>();
+    const totals = useComputedTotals();
+
+    const currency = CURRENCIES.find(c => c.code === values.currency);
+    const symbol = currency?.symbol ?? values.currency;
+
+    const fmt = (n: number) => n.toFixed(2);
+
+    const widthPx = size === "large" ? 320 : 240;
+    const fontPx = size === "large" ? 13 : 11;
+
+    return (
+      <div
+        ref={ref}
+        className="pearl-tape"
+        style={{
+          background: "#fdfbf5",
+          color: "#2a2620",
+          padding: "14px 16px 22px 16px",
+          fontFamily: "'Courier New', ui-monospace, monospace",
+          fontSize: `${fontPx}px`,
+          lineHeight: 1.55,
+          width: widthPx,
+          boxShadow: "0 2px 6px rgba(0,0,0,0.10)",
+          clipPath:
+            "polygon(0 0, 100% 0, 100% calc(100% - 8px), 95% 100%, 90% calc(100% - 6px), 85% 100%, 80% calc(100% - 8px), 75% 100%, 70% calc(100% - 6px), 65% 100%, 60% calc(100% - 8px), 55% 100%, 50% calc(100% - 6px), 45% 100%, 40% calc(100% - 8px), 35% 100%, 30% calc(100% - 6px), 25% 100%, 20% calc(100% - 8px), 15% 100%, 10% calc(100% - 6px), 5% 100%, 0 calc(100% - 8px))",
+        }}
+      >
+        <div style={{ textAlign: "center" }}>
+          <b>{values.merchant || "—"}</b>
+        </div>
+        <div style={{ textAlign: "center" }}>{values.date}</div>
+
+        <Divider />
+
+        {values.items.length === 0 && (
+          <div style={{ textAlign: "center", opacity: 0.5 }}>no items</div>
+        )}
+
+        {values.items.map(item => (
+          <div key={item.id}>
+            <Row
+              left={
+                item.children.length > 0 && item.quantity > 1
+                  ? `${item.description || "—"} (×${item.quantity})`
+                  : item.description || "—"
+              }
+              right={fmt(totals.itemTotal(item))}
+            />
+            {item.children.map(c => (
+              <div key={c.id} style={{ paddingLeft: 10, color: "#6b6558", fontSize: fontPx - 1 }}>
+                {c.description || "—"}{" "}
+                <span style={{ float: "right" }}>
+                  {fmt(c.quantity * c.unitPrice)}
+                </span>
+              </div>
+            ))}
+          </div>
+        ))}
+
+        <Divider />
+
+        <Row left="Subtotal" right={`${symbol}${fmt(totals.subtotal)}`} />
+        {totals.taxes.map((t, i) => (
+          <Row
+            key={i}
+            left={`${t.name} (${t.ratePercent}%)`}
+            right={fmt(t.amount)}
+          />
+        ))}
+        <Row left="TOTAL" right={`${symbol}${fmt(totals.grandTotal)}`} bold />
+
+        <Divider />
+
+        <div style={{ textAlign: "center", textTransform: "uppercase" }}>
+          {values.paymentMethod}
+          {values.paymentNote ? ` · ${values.paymentNote}` : ""}
+        </div>
+        <div style={{ textAlign: "center", marginTop: 4, opacity: 0.7 }}>
+          -- THANK YOU --
+        </div>
+      </div>
+    );
+  }
+);
+
+function Divider() {
+  return (
+    <hr
+      style={{
+        border: "none",
+        borderTop: "1px dashed #999",
+        margin: "6px 0",
+      }}
+    />
+  );
+}
+
+function Row({
+  left,
+  right,
+  bold,
+}: {
+  left: string;
+  right: string;
+  bold?: boolean;
+}) {
+  return (
+    <div
+      style={{
+        display: "flex",
+        justifyContent: "space-between",
+        fontWeight: bold ? 700 : 400,
+      }}
+    >
+      <span>{left}</span>
+      <span>{right}</span>
+    </div>
+  );
+}
diff --git a/src/alex_frontend/core/features/pearl/components/TaxLinesEditor.tsx b/src/alex_frontend/core/features/pearl/components/TaxLinesEditor.tsx
new file mode 100644
index 000000000..a8113ee9a
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/components/TaxLinesEditor.tsx
@@ -0,0 +1,95 @@
+import React from "react";
+import { FieldArray, useFormikContext } from "formik";
+import { nanoid } from "nanoid";
+import { Plus, X } from "lucide-react";
+import { Input } from "@/lib/components/input";
+import { Button } from "@/lib/components/button";
+import type { Receipt } from "../schema";
+import { useComputedTotals } from "../hooks/useComputedTotals";
+import { FieldError } from "./FieldError";
+
+const numericInputClass = "font-mono tabular-nums text-right";
+
+export function TaxLinesEditor() {
+  const { values, handleChange } = useFormikContext<Receipt>();
+  const totals = useComputedTotals();
+
+  return (
+    <FieldArray name="taxLines">
+      {({ push, remove }) => (
+        <div className="space-y-2">
+          {values.taxLines.length > 0 && (
+            <>
+              <div className="hidden sm:grid grid-cols-12 gap-2 text-[10px] font-semibold uppercase tracking-[0.12em] text-gray-500 dark:text-gray-400">
+                <div className="col-span-5">Label</div>
+                <div className="col-span-3 text-right">Rate %</div>
+                <div className="col-span-3 text-right">Amount</div>
+                <div className="col-span-1" />
+              </div>
+
+              <div className="divide-y-2 divide-dotted divide-gray-300 dark:divide-gray-700 space-y-2">
+                {values.taxLines.map((line, i) => (
+                  <div
+                    key={line.id}
+                    className="grid grid-cols-12 gap-2 items-center pt-2 first:pt-0"
+                  >
+                    <div className="col-span-5">
+                      <Input
+                        name={`taxLines[${i}].name`}
+                        value={line.name}
+                        onChange={handleChange}
+                        placeholder="e.g. GST"
+                        scale="sm"
+                        rounded="md"
+                      />
+                      <FieldError name={`taxLines[${i}].name`} />
+                    </div>
+                    <div className="col-span-3">
+                      <Input
+                        name={`taxLines[${i}].ratePercent`}
+                        type="number"
+                        min={0}
+                        max={100}
+                        step="any"
+                        value={line.ratePercent}
+                        onChange={handleChange}
+                        placeholder="0.0"
+                        scale="sm"
+                        rounded="md"
+                        className={numericInputClass}
+                      />
+                      <FieldError name={`taxLines[${i}].ratePercent`} />
+                    </div>
+                    <div className="col-span-3 flex items-center justify-end pr-1 text-sm font-mono tabular-nums text-gray-700 dark:text-gray-300">
+                      {(totals.taxes[i]?.amount ?? 0).toFixed(2)}
+                    </div>
+                    <div className="col-span-1 flex items-center justify-end">
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        scale="icon"
+                        onClick={() => remove(i)}
+                        aria-label="Remove tax line"
+                      >
+                        <X size={14} />
+                      </Button>
+                    </div>
+                  </div>
+                ))}
+              </div>
+            </>
+          )}
+
+          <Button
+            type="button"
+            variant="muted"
+            scale="sm"
+            onClick={() => push({ id: nanoid(), name: "", ratePercent: 0 })}
+          >
+            <Plus size={13} /> Add tax line
+          </Button>
+        </div>
+      )}
+    </FieldArray>
+  );
+}
diff --git a/src/alex_frontend/core/features/pearl/components/Totals.tsx b/src/alex_frontend/core/features/pearl/components/Totals.tsx
new file mode 100644
index 000000000..d7f24f317
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/components/Totals.tsx
@@ -0,0 +1,59 @@
+import React from "react";
+import { useFormikContext } from "formik";
+import type { Receipt } from "../schema";
+import { useComputedTotals } from "../hooks/useComputedTotals";
+import { CURRENCIES } from "../constants";
+
+export function Totals() {
+  const { values } = useFormikContext<Receipt>();
+  const totals = useComputedTotals();
+  const symbol = CURRENCIES.find(c => c.code === values.currency)?.symbol ?? "";
+
+  return (
+    <div className="space-y-1.5">
+      <Row label="Subtotal" value={`${symbol}${totals.subtotal.toFixed(2)}`} />
+      {totals.taxes.map((t, i) => (
+        <Row
+          key={i}
+          label={`${t.name || "Tax"} (${t.ratePercent}%)`}
+          value={`${symbol}${t.amount.toFixed(2)}`}
+          muted
+        />
+      ))}
+      <div className="pt-2 mt-2 border-t border-gray-200 dark:border-gray-800">
+        <Row
+          label="Total"
+          value={`${symbol}${totals.grandTotal.toFixed(2)}`}
+          bold
+        />
+      </div>
+    </div>
+  );
+}
+
+function Row({
+  label,
+  value,
+  bold,
+  muted,
+}: {
+  label: string;
+  value: string;
+  bold?: boolean;
+  muted?: boolean;
+}) {
+  return (
+    <div
+      className={`flex justify-between text-sm ${
+        bold
+          ? "font-semibold text-base text-gray-900 dark:text-gray-100"
+          : muted
+          ? "text-gray-600 dark:text-gray-400"
+          : "text-gray-800 dark:text-gray-200"
+      }`}
+    >
+      <span>{label}</span>
+      <span className="font-mono tabular-nums">{value}</span>
+    </div>
+  );
+}
diff --git a/src/alex_frontend/core/features/pearl/constants.ts b/src/alex_frontend/core/features/pearl/constants.ts
new file mode 100644
index 000000000..1e2552752
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/constants.ts
@@ -0,0 +1,65 @@
+
+/** Payment method enum — matches the chip selector UI and the `Pearl-Payment-Method` Arweave tag. */
+export const PAYMENT_METHODS = ["cash", "card", "bank", "crypto", "other"] as const;
+export type PaymentMethod = typeof PAYMENT_METHODS[number];
+
+/** Display labels for payment chips. */
+export const PAYMENT_METHOD_LABELS: Record<PaymentMethod, string> = {
+  cash: "Cash",
+  card: "Card",
+  bank: "Bank",
+  crypto: "Crypto",
+  other: "Other",
+};
+
+/** Common ISO 4217 currency codes with symbol + name. Extend as needed. */
+export const CURRENCIES = [
+  { code: "USD", symbol: "$",  name: "US Dollar" },
+  { code: "EUR", symbol: "€",  name: "Euro" },
+  { code: "GBP", symbol: "£",  name: "British Pound" },
+  { code: "JPY", symbol: "¥",  name: "Japanese Yen" },
+  { code: "CAD", symbol: "CA$", name: "Canadian Dollar" },
+  { code: "AUD", symbol: "A$", name: "Australian Dollar" },
+  { code: "INR", symbol: "₹",  name: "Indian Rupee" },
+  { code: "CHF", symbol: "Fr", name: "Swiss Franc" },
+  { code: "CNY", symbol: "¥",  name: "Chinese Yuan" },
+  { code: "BRL", symbol: "R$", name: "Brazilian Real" },
+  { code: "MXN", symbol: "Mex$", name: "Mexican Peso" },
+  { code: "SGD", symbol: "S$", name: "Singapore Dollar" },
+  { code: "HKD", symbol: "HK$", name: "Hong Kong Dollar" },
+  { code: "NZD", symbol: "NZ$", name: "New Zealand Dollar" },
+  { code: "SEK", symbol: "kr", name: "Swedish Krona" },
+  { code: "NOK", symbol: "kr", name: "Norwegian Krone" },
+  { code: "DKK", symbol: "kr", name: "Danish Krone" },
+  { code: "PLN", symbol: "zł", name: "Polish Zloty" },
+  { code: "ZAR", symbol: "R",  name: "South African Rand" },
+  { code: "AED", symbol: "د.إ", name: "UAE Dirham" },
+  { code: "TRY", symbol: "₺",  name: "Turkish Lira" },
+  { code: "KRW", symbol: "₩",  name: "South Korean Won" },
+] as const;
+
+export type CurrencyCode = typeof CURRENCIES[number]["code"];
+
+export const DEFAULT_CURRENCY: CurrencyCode = "USD";
+
+/** Arweave tag name constants used by buildArweaveTags — keep in one place for consistency. */
+export const PEARL_TAG = {
+  AppName: "App-Name",
+  AppVersion: "App-Version",
+  Schema: "Pearl-Schema",
+  ReceiptId: "Pearl-Receipt-Id",
+  Merchant: "Pearl-Merchant",
+  Date: "Pearl-Date",
+  Currency: "Pearl-Currency",
+  PaymentMethod: "Pearl-Payment-Method",
+  Subtotal: "Pearl-Subtotal",
+  TaxTotal: "Pearl-Tax-Total",
+  GrandTotal: "Pearl-Grand-Total",
+  ItemCount: "Pearl-Item-Count",
+  Tag: "Pearl-Tag",
+  Data: "Pearl-Data",
+} as const;
+
+export const PEARL_APP_NAME = "Pearl";
+export const PEARL_APP_VERSION = "1.0.0";
+export const PEARL_SCHEMA_ID = "receipt-v1";
diff --git a/src/alex_frontend/core/features/pearl/hooks/useComputedTotals.ts b/src/alex_frontend/core/features/pearl/hooks/useComputedTotals.ts
new file mode 100644
index 000000000..a7456bf28
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/hooks/useComputedTotals.ts
@@ -0,0 +1,46 @@
+import { useMemo } from "react";
+import { useFormikContext } from "formik";
+import type { Receipt, LineItem } from "../schema";
+
+export interface ComputedTotals {
+  /** Sum of all line-item totals (pre-tax). */
+  subtotal: number;
+  /** Resolved tax rows with computed amounts. */
+  taxes: Array<{ name: string; ratePercent: number; amount: number }>;
+  /** Sum of all tax amounts. */
+  taxTotal: number;
+  /** subtotal + taxTotal. */
+  grandTotal: number;
+  /** Helper: total for a single line item (sum of children if present, else qty*unit). */
+  itemTotal: (item: LineItem) => number;
+}
+
+/** Pure computation — used by the Totals UI, the TapePreview, and buildArweaveTags. */
+export function computeTotals(receipt: Receipt): ComputedTotals {
+  // With children, the item is a bundle: total = parentQty × sum(children).
+  // Without children, it's a simple line: total = qty × unitPrice.
+  const itemTotal = (i: LineItem): number => {
+    if (i.children.length > 0) {
+      const bundle = i.children.reduce((s, c) => s + c.quantity * c.unitPrice, 0);
+      return i.quantity * bundle;
+    }
+    return (i.unitPrice ?? 0) * i.quantity;
+  };
+
+  const subtotal = receipt.items.reduce((s, i) => s + itemTotal(i), 0);
+  const taxes = receipt.taxLines.map(t => ({
+    name: t.name,
+    ratePercent: t.ratePercent,
+    amount: subtotal * t.ratePercent / 100,
+  }));
+  const taxTotal = taxes.reduce((s, t) => s + t.amount, 0);
+  const grandTotal = subtotal + taxTotal;
+
+  return { subtotal, taxes, taxTotal, grandTotal, itemTotal };
+}
+
+/** React hook wrapper — subscribes to Formik state and recomputes on change. */
+export function useComputedTotals(): ComputedTotals {
+  const { values } = useFormikContext<Receipt>();
+  return useMemo(() => computeTotals(values), [values]);
+}
diff --git a/src/alex_frontend/core/features/pearl/hooks/useMintReceipt.ts b/src/alex_frontend/core/features/pearl/hooks/useMintReceipt.ts
new file mode 100644
index 000000000..8d26fd01f
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/hooks/useMintReceipt.ts
@@ -0,0 +1,74 @@
+import { useState } from "react";
+import { useUploadAndMint } from "@/features/pinax/hooks/useUploadAndMint";
+import { renderTapeImage } from "../utils/renderTapeImage";
+import { buildArweaveTags } from "../utils/buildArweaveTags";
+import type { Receipt } from "../schema";
+import type { ComputedTotals } from "./useComputedTotals";
+
+/**
+ * Orchestrates the pearl-specific mint pipeline on top of pinax's useUploadAndMint:
+ *   1. Render the tape DOM node to a PNG Blob on a framed background
+ *   2. Build structured ArweaveTag[] from the receipt + totals
+ *   3. Hand off to pinax (which handles estimate → pay → upload → mint)
+ */
+export function useMintReceipt() {
+  const pinax = useUploadAndMint();
+  const [renderError, setRenderError] = useState<string | null>(null);
+
+  const mint = async (
+    tapeEl: HTMLElement | null,
+    receipt: Receipt,
+    totals: ComputedTotals,
+    /** If provided, this file is minted as-is and we skip rendering the tape. */
+    uploadedFile?: File | null,
+  ) => {
+    setRenderError(null);
+
+    let file: File;
+    if (uploadedFile) {
+      // User-supplied receipt — mint the file as-is; metadata tags still come
+      // from the form values below.
+      file = uploadedFile;
+    } else {
+      if (!tapeEl) {
+        const msg = "Receipt preview is not ready";
+        setRenderError(msg);
+        throw new Error(msg);
+      }
+      let blob: Blob;
+      try {
+        blob = await renderTapeImage(tapeEl);
+      } catch (e: any) {
+        const msg = e?.message ?? "Failed to render receipt image";
+        setRenderError(msg);
+        throw new Error(msg);
+      }
+      file = new File([blob], "pearl-receipt.png", { type: "image/png" });
+    }
+
+    const tags = buildArweaveTags(receipt, totals);
+
+    return pinax.uploadAndMint(file, tags);
+  };
+
+  const reset = () => {
+    setRenderError(null);
+    pinax.resetUpload();
+  };
+
+  return {
+    mint,
+    reset,
+    renderError,
+    // Re-export pinax state so the modal can show progress / errors
+    uploading: pinax.uploading,
+    minting: pinax.minting,
+    estimating: pinax.estimating,
+    progress: pinax.progress,
+    cost: pinax.cost,
+    lbryFee: pinax.lbryFee,
+    error: pinax.error,
+    success: pinax.success,
+    isProcessing: pinax.isProcessing,
+  };
+}
diff --git a/src/alex_frontend/core/features/pearl/plan.md b/src/alex_frontend/core/features/pearl/plan.md
new file mode 100644
index 000000000..9acadfc85
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/plan.md
@@ -0,0 +1,7 @@
+# Pearl — Deferred Follow-ups
+
+1. **Canister `Pearl(String)` variant.** Add to `ItemContent` (`src/perpetua/src/storage/shelf_storage.rs`), regenerate `.did` + `declarations/`, replace the `AddItem.tsx:82` Nft workaround, add `PearlItemCard` branch in `ItemCard.tsx`, extend `ContentType` in perpetua `types.ts`/`utils.ts`, surface in the content-type filter.
+
+2. **LBRY cost card on PearlPage.** `useMintReceipt` already exposes `cost` / `lbryFee` / `estimating`; wire them into `PearlPage.tsx` (was reverted — revisit after flow stabilizes).
+
+3. **Real-time cost estimation.** Debounce form changes → render tape via `html-to-image` → call `pinax.estimate()` to show live cost as the user types (currently estimation only fires inside `uploadAndMint` at submit time).
diff --git a/src/alex_frontend/core/features/pearl/schema.ts b/src/alex_frontend/core/features/pearl/schema.ts
new file mode 100644
index 000000000..46a8727b6
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/schema.ts
@@ -0,0 +1,58 @@
+import * as Yup from "yup";
+import { PAYMENT_METHODS, DEFAULT_CURRENCY } from "./constants";
+
+export const LineItemChildSchema = Yup.object({
+  id: Yup.string().required(),
+  description: Yup.string().trim().required("Required").max(200),
+  quantity: Yup.number().typeError("Number").min(0).required().default(1),
+  unitPrice: Yup.number().typeError("Number").min(0).required().default(0),
+});
+
+export const LineItemSchema = Yup.object({
+  id: Yup.string().required(),
+  description: Yup.string().trim().required("Required").max(200),
+  quantity: Yup.number().typeError("Number").min(0).required().default(1),
+  unitPrice: Yup.number().typeError("Number").min(0).nullable().default(null),
+  children: Yup.array().of(LineItemChildSchema).default([]),
+});
+
+export const TaxLineSchema = Yup.object({
+  id: Yup.string().required(),
+  name: Yup.string().trim().required("Required").max(40),
+  ratePercent: Yup.number().typeError("Number").min(0).max(100).required(),
+});
+
+export const ReceiptSchema = Yup.object({
+  merchant: Yup.string().trim().required("Merchant is required").max(120),
+  date: Yup.string()
+    .required("Date is required")
+    .matches(/^\d{4}-\d{2}-\d{2}$/, "Invalid date"),
+  currency: Yup.string().required().default(DEFAULT_CURRENCY),
+  items: Yup.array().of(LineItemSchema).min(1, "At least one item").default([]),
+  taxLines: Yup.array().of(TaxLineSchema).default([]),
+  paymentMethod: Yup.string().oneOf(PAYMENT_METHODS).required("Payment method is required"),
+  paymentNote: Yup.string().max(120).default(""),
+  tags: Yup.array().of(Yup.string().max(40).required()).max(20).default([]),
+  notes: Yup.string().max(2000).default(""),
+});
+
+export type Receipt = Yup.InferType<typeof ReceiptSchema>;
+export type LineItem = Yup.InferType<typeof LineItemSchema>;
+export type LineItemChild = Yup.InferType<typeof LineItemChildSchema>;
+export type TaxLine = Yup.InferType<typeof TaxLineSchema>;
+
+/** Produce a blank Receipt suitable for Formik's initialValues. */
+export function buildEmptyReceipt(): Receipt {
+  const today = new Date().toISOString().slice(0, 10); // yyyy-mm-dd
+  return {
+    merchant: "",
+    date: today,
+    currency: DEFAULT_CURRENCY,
+    items: [],
+    taxLines: [],
+    paymentMethod: "card",
+    paymentNote: "",
+    tags: [],
+    notes: "",
+  };
+}
diff --git a/src/alex_frontend/core/features/pearl/utils/buildArweaveTags.ts b/src/alex_frontend/core/features/pearl/utils/buildArweaveTags.ts
new file mode 100644
index 000000000..2a5b6b408
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/utils/buildArweaveTags.ts
@@ -0,0 +1,84 @@
+import { nanoid } from "nanoid";
+import type { ArweaveTag } from "@/features/pinax/thunks/uploadFile";
+import type { Receipt, LineItem, LineItemChild } from "../schema";
+import type { ComputedTotals } from "../hooks/useComputedTotals";
+import {
+  PEARL_TAG,
+  PEARL_APP_NAME,
+  PEARL_APP_VERSION,
+  PEARL_SCHEMA_ID,
+} from "../constants";
+
+/** Shape of the JSON blob written to the `Pearl-Data` tag. IDs are stripped. */
+interface PearlDataBlob {
+  schema: typeof PEARL_SCHEMA_ID;
+  merchant: string;
+  date: string;
+  currency: string;
+  items: Array<{
+    description: string;
+    quantity: number;
+    unitPrice: number | null;
+    children: Array<{ description: string; quantity: number; unitPrice: number }>;
+  }>;
+  taxLines: Array<{ name: string; ratePercent: number }>;
+  paymentMethod: string;
+  paymentNote: string;
+  tags: string[];
+  notes: string;
+}
+
+function stripItemIds(item: LineItem) {
+  return {
+    description: item.description,
+    quantity: item.quantity,
+    unitPrice: item.unitPrice ?? null,
+    children: item.children.map((c: LineItemChild) => ({
+      description: c.description,
+      quantity: c.quantity,
+      unitPrice: c.unitPrice,
+    })),
+  };
+}
+
+export function buildArweaveTags(receipt: Receipt, totals: ComputedTotals): ArweaveTag[] {
+  const blob: PearlDataBlob = {
+    schema: PEARL_SCHEMA_ID,
+    merchant: receipt.merchant,
+    date: receipt.date,
+    currency: receipt.currency,
+    items: receipt.items.map(stripItemIds),
+    taxLines: receipt.taxLines.map(t => ({ name: t.name, ratePercent: t.ratePercent })),
+    paymentMethod: receipt.paymentMethod,
+    paymentNote: receipt.paymentNote,
+    tags: receipt.tags,
+    notes: receipt.notes,
+  };
+
+  const flat: ArweaveTag[] = [
+    { name: PEARL_TAG.AppName,        value: PEARL_APP_NAME },
+    { name: PEARL_TAG.AppVersion,     value: PEARL_APP_VERSION },
+    { name: PEARL_TAG.Schema,         value: PEARL_SCHEMA_ID },
+    { name: PEARL_TAG.ReceiptId,      value: nanoid() },
+    { name: PEARL_TAG.Merchant,       value: receipt.merchant },
+    { name: PEARL_TAG.Date,           value: receipt.date },
+    { name: PEARL_TAG.Currency,       value: receipt.currency },
+    { name: PEARL_TAG.PaymentMethod,  value: receipt.paymentMethod },
+    { name: PEARL_TAG.Subtotal,       value: totals.subtotal.toFixed(2) },
+    { name: PEARL_TAG.TaxTotal,       value: totals.taxTotal.toFixed(2) },
+    { name: PEARL_TAG.GrandTotal,     value: totals.grandTotal.toFixed(2) },
+    { name: PEARL_TAG.ItemCount,      value: String(receipt.items.length) },
+  ];
+
+  const tagRepeats: ArweaveTag[] = receipt.tags.map(t => ({
+    name: PEARL_TAG.Tag,
+    value: t,
+  }));
+
+  const blobTag: ArweaveTag = {
+    name: PEARL_TAG.Data,
+    value: JSON.stringify(blob),
+  };
+
+  return [...flat, ...tagRepeats, blobTag];
+}
diff --git a/src/alex_frontend/core/features/pearl/utils/renderTapeImage.ts b/src/alex_frontend/core/features/pearl/utils/renderTapeImage.ts
new file mode 100644
index 000000000..80d19e15a
--- /dev/null
+++ b/src/alex_frontend/core/features/pearl/utils/renderTapeImage.ts
@@ -0,0 +1,57 @@
+import { toCanvas } from "html-to-image";
+
+/**
+ * Render the tape DOM node to a PNG Blob placed on a dark framed background (Option I2).
+ *
+ * - Captures the tape element at 2× pixel density for retina-quality output.
+ * - Draws the result centered on a padded, subtly-gradiented dark canvas.
+ * - Returns a PNG Blob.
+ */
+export async function renderTapeImage(tapeEl: HTMLElement): Promise<Blob> {
+  // Step 1 — capture the tape node via html-to-image (faster + smaller than
+  // html2canvas on small DOMs; same retina behavior via pixelRatio).
+  const tapeCanvas = await toCanvas(tapeEl, {
+    backgroundColor: undefined, // transparent — the composite supplies the bg
+    pixelRatio: 2,              // retina
+    cacheBust: true,            // avoid cached-image CORS surprises
+  });
+
+  // Step 2 — build composite canvas with padding around the tape
+  const PAD_X = 120; // in output pixels (before scale-down at display)
+  const PAD_Y = 140;
+  const outW = tapeCanvas.width + PAD_X * 2;
+  const outH = tapeCanvas.height + PAD_Y * 2;
+
+  const out = document.createElement("canvas");
+  out.width = outW;
+  out.height = outH;
+  const ctx = out.getContext("2d");
+  if (!ctx) throw new Error("Failed to create canvas 2D context for image composition");
+
+  // Step 3 — paint dark textured background (radial gradient top-left like the mockup)
+  ctx.fillStyle = "#1a1614";
+  ctx.fillRect(0, 0, outW, outH);
+
+  const radial = ctx.createRadialGradient(outW * 0.3, outH * 0.2, 10, outW * 0.3, outH * 0.2, outW * 0.8);
+  radial.addColorStop(0, "rgba(255, 240, 210, 0.06)");
+  radial.addColorStop(1, "rgba(255, 240, 210, 0)");
+  ctx.fillStyle = radial;
+  ctx.fillRect(0, 0, outW, outH);
+
+  // Step 4 — soft shadow beneath the tape for depth
+  // (drawImage emits a shadow from the source canvas's opaque pixels)
+  ctx.save();
+  ctx.shadowColor = "rgba(0, 0, 0, 0.55)";
+  ctx.shadowBlur = 40;
+  ctx.shadowOffsetY = 10;
+  ctx.drawImage(tapeCanvas, PAD_X, PAD_Y);
+  ctx.restore();
+
+  // Step 5 — export to PNG Blob
+  return new Promise<Blob>((resolve, reject) => {
+    out.toBlob(
+      (blob) => (blob ? resolve(blob) : reject(new Error("Failed to export tape PNG"))),
+      "image/png",
+    );
+  });
+}
diff --git a/src/alex_frontend/core/features/perpetua/actions/AddItem.tsx b/src/alex_frontend/core/features/perpetua/actions/AddItem.tsx
index ae08ef2ce..1750ffff9 100644
--- a/src/alex_frontend/core/features/perpetua/actions/AddItem.tsx
+++ b/src/alex_frontend/core/features/perpetua/actions/AddItem.tsx
@@ -1,5 +1,6 @@
 import React, { useState, useMemo } from "react";
 import { Plus, Loader2, AlertCircle, Search } from "lucide-react";
+import { useNavigate } from "@tanstack/react-router";
 import { Button } from "@/lib/components/button";
 import { Input } from "@/lib/components/input";
 import { Textarea } from "@/lib/components/textarea";
@@ -30,10 +31,12 @@ export default function AddItem({ shelfId, existingShelfIds }: AddItemProps) {
 	const [tab, setTab] = useState("markdown");
 	const [markdown, setMarkdown] = useState("");
 	const [nftTokenId, setNftTokenId] = useState("");
+	const [pearlTokenId, setPearlTokenId] = useState("");
 	const [selectedShelfId, setSelectedShelfId] = useState("");
 	const [error, setError] = useState<string | null>(null);
 	const addItem = useAddItem();
 	const { data: myShelves } = useMyShelves();
+	const navigate = useNavigate();
 
 	// Shelf sub-mode state
 	const [shelfMode, setShelfMode] = useState<ShelfMode>("mine");
@@ -63,6 +66,7 @@ export default function AddItem({ shelfId, existingShelfIds }: AddItemProps) {
 	const canSubmit = !addItem.isPending && (
 		(tab === "markdown" && markdown.trim().length > 0) ||
 		(tab === "nft" && nftTokenId.trim().length > 0) ||
+		(tab === "pearl" && pearlTokenId.trim().length > 0) ||
 		(tab === "shelf" && selectedShelfId.length > 0)
 	);
 
@@ -70,15 +74,19 @@ export default function AddItem({ shelfId, existingShelfIds }: AddItemProps) {
 		if (!canSubmit) return;
 		setError(null);
 
+		// Pearl receipts are NFTs minted through the same pipeline, so they
+		// share the `Nft` content variant on the canister side.
 		let content;
 		if (tab === "markdown") content = { Markdown: markdown.trim() };
 		else if (tab === "nft") content = { Nft: nftTokenId.trim() };
+		else if (tab === "pearl") content = { Nft: pearlTokenId.trim() };
 		else content = { Shelf: selectedShelfId };
 
 		try {
 			await addItem.mutateAsync({ shelfId, content });
 			setMarkdown("");
 			setNftTokenId("");
+			setPearlTokenId("");
 			setSelectedShelfId("");
 			setOpen(false);
 		} catch (err: any) {
@@ -91,6 +99,7 @@ export default function AddItem({ shelfId, existingShelfIds }: AddItemProps) {
 			setError(null);
 			setMarkdown("");
 			setNftTokenId("");
+			setPearlTokenId("");
 			setSelectedShelfId("");
 			setTab("markdown");
 			setShelfMode("mine");
@@ -108,6 +117,11 @@ export default function AddItem({ shelfId, existingShelfIds }: AddItemProps) {
 		}
 	};
 
+	const goTo = (path: "/app/pinax" | "/app/pearl") => {
+		handleOpenChange(false);
+		navigate({ to: path });
+	};
+
 	const handleShelfModeChange = (mode: ShelfMode) => {
 		setShelfMode(mode);
 		setSelectedShelfId("");
@@ -145,6 +159,7 @@ export default function AddItem({ shelfId, existingShelfIds }: AddItemProps) {
 							<TabsTrigger value="markdown" className="flex-1 dark:data-[state=active]:bg-gray-900 dark:data-[state=active]:text-gray-100 dark:text-gray-400">Markdown</TabsTrigger>
 							<TabsTrigger value="nft" className="flex-1 dark:data-[state=active]:bg-gray-900 dark:data-[state=active]:text-gray-100 dark:text-gray-400">NFT</TabsTrigger>
 							<TabsTrigger value="shelf" className="flex-1 dark:data-[state=active]:bg-gray-900 dark:data-[state=active]:text-gray-100 dark:text-gray-400">Shelf</TabsTrigger>
+							<TabsTrigger value="pearl" className="flex-1 dark:data-[state=active]:bg-gray-900 dark:data-[state=active]:text-gray-100 dark:text-gray-400">Pearl</TabsTrigger>
 						</TabsList>
 
 						<TabsContent value="markdown" className="mt-3 space-y-1">
@@ -168,7 +183,15 @@ export default function AddItem({ shelfId, existingShelfIds }: AddItemProps) {
 								rounded="md"
 							/>
 							<p className="text-sm text-muted-foreground dark:text-gray-400">
-								Find NFTs in Alexandrian, Permasearch, or Emporium.
+								Find NFTs in Alexandrian, Permasearch, or Emporium, or{" "}
+								<button
+									type="button"
+									onClick={() => goTo("/app/pinax")}
+									className="text-muted-foreground/80 hover:text-foreground underline underline-offset-2"
+								>
+									upload media
+								</button>
+								.
 							</p>
 						</TabsContent>
 
@@ -304,6 +327,28 @@ export default function AddItem({ shelfId, existingShelfIds }: AddItemProps) {
 								</div>
 							)}
 						</TabsContent>
+
+						<TabsContent value="pearl" className="mt-3 space-y-2">
+							<Input
+								type="text"
+								value={pearlTokenId}
+								onChange={(e) => setPearlTokenId(e.target.value)}
+								placeholder="Enter Pearl receipt token ID"
+								scale="sm"
+								rounded="md"
+							/>
+							<p className="text-sm text-muted-foreground dark:text-gray-400">
+								Paste the token ID of an already-minted Pearl receipt, or{" "}
+								<button
+									type="button"
+									onClick={() => goTo("/app/pearl")}
+									className="text-muted-foreground/80 hover:text-foreground underline underline-offset-2"
+								>
+									create a new one
+								</button>
+								.
+							</p>
+						</TabsContent>
 					</Tabs>
 				</div>
 
diff --git a/src/alex_frontend/core/features/perpetua/components/ShelfDetail.tsx b/src/alex_frontend/core/features/perpetua/components/ShelfDetail.tsx
index 02e2bfe40..5594e3899 100644
--- a/src/alex_frontend/core/features/perpetua/components/ShelfDetail.tsx
+++ b/src/alex_frontend/core/features/perpetua/components/ShelfDetail.tsx
@@ -37,6 +37,7 @@ import RemoveItem from "../actions/RemoveItem";
 import EditShelfMeta from "../actions/EditShelfMeta";
 import TogglePublicAccess from "../actions/TogglePublicAccess";
 import ManageTags from "../actions/ManageTags";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/lib/components/select";
 
 type ViewMode = "grid" | "list" | "blog";
 
@@ -46,6 +47,32 @@ const viewModes: { mode: ViewMode; icon: typeof LayoutGrid }[] = [
 	{ mode: "blog", icon: BookOpen },
 ];
 
+type ContentFilter = "all" | "Markdown" | "Nft" | "Shelf";
+
+const contentFilters: { key: ContentFilter; label: string }[] = [
+	{ key: "all", label: "All" },
+	{ key: "Markdown", label: "Markdown" },
+	{ key: "Nft", label: "NFT" },
+	{ key: "Shelf", label: "Shelf" },
+];
+
+function ContentTypeFilter({ value, onChange }: { value: ContentFilter; onChange: (f: ContentFilter) => void }) {
+	return (
+		<Select value={value} onValueChange={(v) => onChange(v as ContentFilter)}>
+			<SelectTrigger className="h-[22px] w-auto rounded-full border-gray-300 dark:border-gray-600 bg-gray-50 dark:bg-gray-800 px-2.5 py-0 gap-1 text-xs text-muted-foreground dark:text-gray-400 [&>svg]:h-3 [&>svg]:w-3">
+				<SelectValue />
+			</SelectTrigger>
+			<SelectContent>
+				{contentFilters.map(({ key, label }) => (
+					<SelectItem key={key} value={key} className="text-xs">
+						{label}
+					</SelectItem>
+				))}
+			</SelectContent>
+		</Select>
+	);
+}
+
 function ViewSwitch({ viewMode, onChange }: { viewMode: ViewMode; onChange: (mode: ViewMode) => void }) {
 	return (
 		<div className="inline-flex items-center h-[22px] rounded-full border border-gray-300 dark:border-gray-600 bg-gray-50 dark:bg-gray-800 px-1 py-0.5 gap-0.5">
@@ -127,6 +154,7 @@ export default function ShelfDetail({ shelfId, userId }: ShelfDetailProps) {
 	const setItemOrder = useSetItemOrder();
 	const [nftModal, setNftModal] = useState<Modal | null>(null);
 	const [viewMode, setViewMode] = useState<ViewMode>("grid");
+	const [contentFilter, setContentFilter] = useState<ContentFilter>("all");
 	const { username: ownerName } = useUsername(shelf?.owner);
 
 	const handleSaveOrder = useCallback(async (reordered: [number, Item][]) => {
@@ -154,6 +182,13 @@ export default function ShelfDetail({ shelfId, userId }: ShelfDetailProps) {
 		[reorder.displayItems],
 	);
 
+	// Client-side filter by content-variant. NFTs and Pearls are both stored
+	// as `{ Nft: tokenId }` today, so selecting "NFT" shows both.
+	const filteredItems = useMemo(() => {
+		if (contentFilter === "all") return reorder.displayItems;
+		return reorder.displayItems.filter(([, item]) => contentFilter in item.content);
+	}, [reorder.displayItems, contentFilter]);
+
 	if (isLoading) return <ShelfDetailSkeleton />;
 
 	if (error || !shelf) {
@@ -280,10 +315,13 @@ export default function ShelfDetail({ shelfId, userId }: ShelfDetailProps) {
 				</div>
 			</div>
 
-			{/* Row 2: View switch + Tags */}
+			{/* Row 2: Content filter + View switch + Tags */}
 			<div className="flex gap-2 flex-wrap items-center">
 				{!reorder.isEditMode && reorder.displayItems.length > 0 && (
-					<ViewSwitch viewMode={viewMode} onChange={setViewMode} />
+					<>
+						<ContentTypeFilter value={contentFilter} onChange={setContentFilter} />
+						<ViewSwitch viewMode={viewMode} onChange={setViewMode} />
+					</>
 				)}
 
 				{isOwner ? (
@@ -308,6 +346,15 @@ export default function ShelfDetail({ shelfId, userId }: ShelfDetailProps) {
 						</div>
 						<p className="text-base">This shelf is empty. Add some items to get started!</p>
 					</div>
+				) : !reorder.isEditMode && filteredItems.length === 0 ? (
+					<div className="flex flex-col items-center gap-4 py-24 text-muted-foreground dark:text-gray-400 animate-fade">
+						<div className="h-12 w-12 rounded-full bg-muted dark:bg-gray-800 flex items-center justify-center">
+							<Package className="h-6 w-6" />
+						</div>
+						<p className="text-base">
+							No {contentFilters.find((f) => f.key === contentFilter)?.label} items in this shelf.
+						</p>
+					</div>
 				) : reorder.isEditMode ? (
 					<DndContext
 						sensors={sensors}
@@ -328,10 +375,10 @@ export default function ShelfDetail({ shelfId, userId }: ShelfDetailProps) {
 						</SortableContext>
 					</DndContext>
 				) : isBlogView ? (
-					<BlogView items={reorder.displayItems} canEdit={canEdit} shelfId={shelfId} />
+					<BlogView items={filteredItems} canEdit={canEdit} shelfId={shelfId} />
 				) : viewMode === "list" ? (
 					<div className="flex flex-col gap-4 max-w-3xl">
-						{reorder.displayItems.map(([itemKey, item], index) => (
+						{filteredItems.map(([itemKey, item], index) => (
 							<div
 								key={itemKey}
 								className="relative group animate-fade"
@@ -348,7 +395,7 @@ export default function ShelfDetail({ shelfId, userId }: ShelfDetailProps) {
 					</div>
 				) : (
 					<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-5 items-center">
-						{reorder.displayItems.map(([itemKey, item], index) => (
+						{filteredItems.map(([itemKey, item], index) => (
 							<div
 								key={itemKey}
 								className="relative group animate-fade"
diff --git a/src/alex_frontend/lbry/public/logos/Pearl.svg b/src/alex_frontend/lbry/public/logos/Pearl.svg
new file mode 100644
index 000000000..4ab09f5f8
--- /dev/null
+++ b/src/alex_frontend/lbry/public/logos/Pearl.svg
@@ -0,0 +1,33 @@
+<svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M0 40C0 17.9086 17.9086 0 40 0H472C494.091 0 512 17.9086 512 40V472C512 494.091 494.091 512 472 512H40C17.9086 512 0 494.091 0 472V40Z" fill="url(#pearl_bg)" fill-opacity="0.35"/>
+<g filter="url(#pearl_shadow)">
+<path d="M76 176 L108 144 L140 176 L172 144 L204 176 L236 144 L268 176 L300 144 L332 176 L364 144 L396 176 L428 144 L436 176 L436 336 L428 368 L396 336 L364 368 L332 336 L300 368 L268 336 L236 368 L204 336 L172 368 L140 336 L108 368 L76 336 Z" stroke="url(#pearl_stroke)" stroke-width="8" stroke-linejoin="round" fill="none"/>
+<circle cx="256" cy="256" r="62" stroke="url(#pearl_stroke)" stroke-width="8" fill="none"/>
+<path d="M224 232 A 40 40 0 0 1 250 216" stroke="url(#pearl_stroke)" stroke-width="10" stroke-linecap="round" fill="none" stroke-opacity="0.8"/>
+<line x1="110" y1="220" x2="176" y2="220" stroke="url(#pearl_stroke)" stroke-width="6" stroke-linecap="round" stroke-opacity="0.55"/>
+<line x1="336" y1="220" x2="402" y2="220" stroke="url(#pearl_stroke)" stroke-width="6" stroke-linecap="round" stroke-opacity="0.55"/>
+<line x1="110" y1="292" x2="176" y2="292" stroke="url(#pearl_stroke)" stroke-width="6" stroke-linecap="round" stroke-opacity="0.55"/>
+<line x1="336" y1="292" x2="402" y2="292" stroke="url(#pearl_stroke)" stroke-width="6" stroke-linecap="round" stroke-opacity="0.55"/>
+</g>
+<defs>
+<filter id="pearl_shadow" x="60" y="128" width="392" height="256" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+<feOffset dx="4" dy="4"/>
+<feGaussianBlur stdDeviation="7"/>
+<feComposite in2="hardAlpha" operator="out"/>
+<feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.25 0"/>
+<feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow"/>
+<feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow" result="shape"/>
+</filter>
+<linearGradient id="pearl_bg" x1="494.5" y1="0" x2="0" y2="512" gradientUnits="userSpaceOnUse">
+<stop stop-color="#FDE4D3"/>
+<stop offset="1" stop-color="#7B3A5F"/>
+</linearGradient>
+<linearGradient id="pearl_stroke" x1="256" y1="144" x2="256" y2="368" gradientUnits="userSpaceOnUse">
+<stop stop-color="#F2B8A6"/>
+<stop offset="0.5" stop-color="#C0708A"/>
+<stop offset="1" stop-color="#4A1E3E"/>
+</linearGradient>
+</defs>
+</svg>
diff --git a/src/alex_frontend/lbry/routeTree.gen.ts b/src/alex_frontend/lbry/routeTree.gen.ts
index 489519024..c7bd226cd 100644
--- a/src/alex_frontend/lbry/routeTree.gen.ts
+++ b/src/alex_frontend/lbry/routeTree.gen.ts
@@ -59,6 +59,7 @@ const AuthDashboardAnalyticsLazyRouteImport = createFileRoute(
   '/_auth/dashboard/analytics',
 )()
 const AuthAppPinaxLazyRouteImport = createFileRoute('/_auth/app/pinax')()
+const AuthAppPearlLazyRouteImport = createFileRoute('/_auth/app/pearl')()
 const AuthDashboardLibrarianRouteLazyRouteImport = createFileRoute(
   '/_auth/dashboard/_librarian',
 )()
@@ -281,6 +282,13 @@ const AuthAppPinaxLazyRoute = AuthAppPinaxLazyRouteImport.update({
 } as any).lazy(() =>
   import('./src/routes/_auth/app/pinax.lazy').then((d) => d.Route),
 )
+const AuthAppPearlLazyRoute = AuthAppPearlLazyRouteImport.update({
+  id: '/app/pearl',
+  path: '/app/pearl',
+  getParentRoute: () => AuthRouteLazyRoute,
+} as any).lazy(() =>
+  import('./src/routes/_auth/app/pearl.lazy').then((d) => d.Route),
+)
 const AuthDashboardLibrarianRouteLazyRoute =
   AuthDashboardLibrarianRouteLazyRouteImport.update({
     id: '/_librarian',
@@ -482,6 +490,7 @@ export interface FileRoutesByFullPath {
   '/info/': typeof InfoIndexLazyRoute
   '/app/emporium': typeof AuthAppEmporiumRouteLazyRouteWithChildren
   '/app/sonora': typeof AuthAppSonoraRouteLazyRouteWithChildren
+  '/app/pearl': typeof AuthAppPearlLazyRoute
   '/app/pinax': typeof AuthAppPinaxLazyRoute
   '/dashboard/analytics': typeof AuthDashboardAnalyticsLazyRoute
   '/dashboard/arweave-assets': typeof AuthDashboardArweaveAssetsLazyRoute
@@ -527,6 +536,7 @@ export interface FileRoutesByTo {
   '/swap/redeem': typeof SwapRedeemLazyRoute
   '/swap/stake': typeof SwapStakeLazyRoute
   '/info': typeof InfoIndexLazyRoute
+  '/app/pearl': typeof AuthAppPearlLazyRoute
   '/app/pinax': typeof AuthAppPinaxLazyRoute
   '/dashboard/analytics': typeof AuthDashboardAnalyticsLazyRoute
   '/dashboard/arweave-assets': typeof AuthDashboardArweaveAssetsLazyRoute
@@ -577,6 +587,7 @@ export interface FileRoutesById {
   '/_auth/app/emporium': typeof AuthAppEmporiumRouteLazyRouteWithChildren
   '/_auth/app/sonora': typeof AuthAppSonoraRouteLazyRouteWithChildren
   '/_auth/dashboard/_librarian': typeof AuthDashboardLibrarianRouteLazyRouteWithChildren
+  '/_auth/app/pearl': typeof AuthAppPearlLazyRoute
   '/_auth/app/pinax': typeof AuthAppPinaxLazyRoute
   '/_auth/dashboard/analytics': typeof AuthDashboardAnalyticsLazyRoute
   '/_auth/dashboard/arweave-assets': typeof AuthDashboardArweaveAssetsLazyRoute
@@ -627,6 +638,7 @@ export interface FileRouteTypes {
     | '/info/'
     | '/app/emporium'
     | '/app/sonora'
+    | '/app/pearl'
     | '/app/pinax'
     | '/dashboard/analytics'
     | '/dashboard/arweave-assets'
@@ -672,6 +684,7 @@ export interface FileRouteTypes {
     | '/swap/redeem'
     | '/swap/stake'
     | '/info'
+    | '/app/pearl'
     | '/app/pinax'
     | '/dashboard/analytics'
     | '/dashboard/arweave-assets'
@@ -721,6 +734,7 @@ export interface FileRouteTypes {
     | '/_auth/app/emporium'
     | '/_auth/app/sonora'
     | '/_auth/dashboard/_librarian'
+    | '/_auth/app/pearl'
     | '/_auth/app/pinax'
     | '/_auth/dashboard/analytics'
     | '/_auth/dashboard/arweave-assets'
@@ -960,6 +974,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AuthAppPinaxLazyRouteImport
       parentRoute: typeof AuthRouteLazyRoute
     }
+    '/_auth/app/pearl': {
+      id: '/_auth/app/pearl'
+      path: '/app/pearl'
+      fullPath: '/app/pearl'
+      preLoaderRoute: typeof AuthAppPearlLazyRouteImport
+      parentRoute: typeof AuthRouteLazyRoute
+    }
     '/_auth/dashboard/_librarian': {
       id: '/_auth/dashboard/_librarian'
       path: ''
@@ -1246,6 +1267,7 @@ interface AuthRouteLazyRouteChildren {
   AuthSwapRouteLazyRoute: typeof AuthSwapRouteLazyRouteWithChildren
   AuthAppEmporiumRouteLazyRoute: typeof AuthAppEmporiumRouteLazyRouteWithChildren
   AuthAppSonoraRouteLazyRoute: typeof AuthAppSonoraRouteLazyRouteWithChildren
+  AuthAppPearlLazyRoute: typeof AuthAppPearlLazyRoute
   AuthAppPinaxLazyRoute: typeof AuthAppPinaxLazyRoute
   AuthAppPerpetuaIndexLazyRoute: typeof AuthAppPerpetuaIndexLazyRoute
   AuthAppPerpetuaShelfShelfIdLazyRoute: typeof AuthAppPerpetuaShelfShelfIdLazyRoute
@@ -1258,6 +1280,7 @@ const AuthRouteLazyRouteChildren: AuthRouteLazyRouteChildren = {
   AuthSwapRouteLazyRoute: AuthSwapRouteLazyRouteWithChildren,
   AuthAppEmporiumRouteLazyRoute: AuthAppEmporiumRouteLazyRouteWithChildren,
   AuthAppSonoraRouteLazyRoute: AuthAppSonoraRouteLazyRouteWithChildren,
+  AuthAppPearlLazyRoute: AuthAppPearlLazyRoute,
   AuthAppPinaxLazyRoute: AuthAppPinaxLazyRoute,
   AuthAppPerpetuaIndexLazyRoute: AuthAppPerpetuaIndexLazyRoute,
   AuthAppPerpetuaShelfShelfIdLazyRoute: AuthAppPerpetuaShelfShelfIdLazyRoute,
diff --git a/src/alex_frontend/lbry/src/components/Tabs/AppsTab.tsx b/src/alex_frontend/lbry/src/components/Tabs/AppsTab.tsx
index a6987f3d3..e474b620c 100644
--- a/src/alex_frontend/lbry/src/components/Tabs/AppsTab.tsx
+++ b/src/alex_frontend/lbry/src/components/Tabs/AppsTab.tsx
@@ -8,7 +8,7 @@ export const AppsTab: React.FC = () => {
 	const navigate = useNavigate();
 	const [isHovered, setIsHovered] = useState(false);
 
-	const activeApps = appsData.filter((app: App) => !app.comingSoon);
+	const activeApps = appsData.filter((app: App) => !app.comingSoon && !app.hideFromHeader);
 
 	return (
 		<div
diff --git a/src/alex_frontend/lbry/src/pages/pearl/PearlPage.tsx b/src/alex_frontend/lbry/src/pages/pearl/PearlPage.tsx
new file mode 100644
index 000000000..1d2811a67
--- /dev/null
+++ b/src/alex_frontend/lbry/src/pages/pearl/PearlPage.tsx
@@ -0,0 +1,382 @@
+import React, { useEffect, useRef, useState } from "react";
+import { Helmet } from "react-helmet-async";
+import { Formik } from "formik";
+import { Link } from "@tanstack/react-router";
+import {
+  CheckCircle2,
+  ExternalLink,
+  FileText,
+  LoaderCircle,
+  Upload,
+  X,
+} from "lucide-react";
+import { useAppSelector } from "@/store/hooks/useAppSelector";
+import useNavigationGuard from "@/features/pinax/hooks/useNavigationGuard";
+import { formatFileSize } from "@/features/pinax/utils";
+import { arweaveIdToNat } from "@/utils/id_convert";
+import { Button } from "@/lib/components/button";
+import { Alert } from "@/components/Alert";
+import Copy from "@/components/Copy";
+import { ReceiptSchema, buildEmptyReceipt } from "@/features/pearl/schema";
+import { computeTotals } from "@/features/pearl/hooks/useComputedTotals";
+import { useMintReceipt } from "@/features/pearl/hooks/useMintReceipt";
+import { PearlForm } from "@/features/pearl/components/PearlForm";
+import { TapePreview } from "@/features/pearl/components/TapePreview";
+
+type MintedIds = { tokenId: string; arweaveId: string };
+
+function PearlPage() {
+  const [mintedIds, setMintedIds] = useState<MintedIds | null>(null);
+  const [uploadedFile, setUploadedFile] = useState<File | null>(null);
+  const tapeRef = useRef<HTMLDivElement>(null);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  // Object URL for image previews — revoked on change / unmount to avoid leaks.
+  const [previewUrl, setPreviewUrl] = useState<string | null>(null);
+  useEffect(() => {
+    if (!uploadedFile || !uploadedFile.type.startsWith("image/")) {
+      setPreviewUrl(null);
+      return;
+    }
+    const url = URL.createObjectURL(uploadedFile);
+    setPreviewUrl(url);
+    return () => URL.revokeObjectURL(url);
+  }, [uploadedFile]);
+
+  const handleFilePicked: React.ChangeEventHandler<HTMLInputElement> = (e) => {
+    const file = e.target.files?.[0] ?? null;
+    setUploadedFile(file);
+    // Reset so choosing the same file again still triggers onChange.
+    e.target.value = "";
+  };
+
+  const clearUploadedFile = () => setUploadedFile(null);
+  const openFilePicker = () => fileInputRef.current?.click();
+
+  const { uploading, minting, transaction, minted } = useAppSelector(
+    (s) => s.pinax,
+  );
+  useNavigationGuard({ uploading, minting, transaction, minted });
+
+  const { mint, reset, renderError, error, isProcessing } = useMintReceipt();
+
+  // Local flag so the overlay + disabled state engage the instant the user
+  // clicks "Save & Mint", before html2canvas (which can take ~1s) finishes
+  // and pinax's own loading flag flips.
+  const [submitting, setSubmitting] = useState(false);
+  const busy = isProcessing || submitting;
+
+  const stageLabel = uploading
+    ? "Uploading to Arweave..."
+    : minting
+    ? "Minting NFT..."
+    : "Preparing...";
+
+  return (
+    <div className="flex-grow">
+      <Helmet>
+        <title>Pearl | Alexandria</title>
+        <meta
+          name="description"
+          content="Mint permanent receipts of your purchases on Alexandria."
+        />
+      </Helmet>
+
+      <div className="mx-auto max-w-6xl px-4 sm:px-6 lg:px-8 py-10 font-roboto-condensed">
+        <Formik
+          initialValues={buildEmptyReceipt()}
+          validationSchema={ReceiptSchema}
+          onSubmit={async (values) => {
+            if (!uploadedFile && !tapeRef.current) return;
+            setSubmitting(true);
+            try {
+              const totals = computeTotals(values);
+              const arweaveId = await mint(
+                tapeRef.current,
+                values,
+                totals,
+                uploadedFile,
+              );
+              setMintedIds({
+                tokenId: arweaveIdToNat(arweaveId).toString(),
+                arweaveId,
+              });
+            } catch {
+              // Error surfaced via renderError / error state in the form alert.
+            } finally {
+              setSubmitting(false);
+            }
+          }}
+        >
+          {({ resetForm }) => (
+            mintedIds ? (
+              <SuccessView
+                ids={mintedIds}
+                uploadedFile={uploadedFile}
+                previewUrl={previewUrl}
+                onStartOver={() => {
+                  resetForm();
+                  reset();
+                  setMintedIds(null);
+                  setUploadedFile(null);
+                }}
+              />
+            ) : (
+              <div className="relative p-4 sm:p-6">
+                <div className="grid grid-cols-1 lg:grid-cols-[minmax(0,1fr)_340px] gap-10">
+                  <section>
+                    <div className="flex flex-col justify-center items-center mb-6">
+                      <h2 className="text-2xl font-bold">Pearl</h2>
+                      <p>Mint a permanent, on-chain receipt of a purchase.</p>
+                    </div>
+                    <PearlForm isSubmitting={busy} />
+                  </section>
+
+                  <aside>
+                    {/* Spacer matching the form-column header so the tape
+                        aligns with the first form card on desktop. */}
+                    <div
+                      aria-hidden
+                      className="hidden lg:flex flex-col items-center mb-6 invisible"
+                    >
+                      <h2 className="text-2xl font-bold">Pearl</h2>
+                      <p>Mint a permanent, on-chain receipt of a purchase.</p>
+                    </div>
+                    <div className="lg:sticky lg:top-24 space-y-3">
+                      {uploadedFile ? (
+                        <UploadedPreview
+                          file={uploadedFile}
+                          previewUrl={previewUrl}
+                          onClear={clearUploadedFile}
+                        />
+                      ) : (
+                        <button
+                          type="button"
+                          onClick={openFilePicker}
+                          aria-label="Upload a receipt image or PDF instead"
+                          className="group relative block cursor-pointer rounded-xl transition-all hover:ring-2 hover:ring-amber-400/40 dark:hover:ring-amber-500/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-amber-400/60"
+                        >
+                          <TapeStage>
+                            <TapePreview ref={tapeRef} size="sidebar" />
+                          </TapeStage>
+
+                          <div className="absolute inset-0 flex items-center justify-center rounded-xl bg-black/55 opacity-0 group-hover:opacity-100 transition-opacity">
+                            <div className="flex flex-col items-center gap-1 text-white">
+                              <Upload size={20} />
+                              <span className="text-xs font-medium">
+                                Click to upload instead
+                              </span>
+                            </div>
+                          </div>
+                        </button>
+                      )}
+
+                      <input
+                        ref={fileInputRef}
+                        type="file"
+                        accept="image/*,application/pdf"
+                        className="hidden"
+                        onChange={handleFilePicked}
+                      />
+
+                      {(renderError || error) && (
+                        <Alert variant="danger" title="Mint failed">
+                          {renderError ?? error}
+                        </Alert>
+                      )}
+                    </div>
+                  </aside>
+                </div>
+
+                {busy && (
+                  <div className="absolute inset-0 z-10 flex items-center justify-center rounded-xl bg-white/70 dark:bg-gray-950/70 backdrop-blur-sm">
+                    <div className="flex flex-col items-center gap-3">
+                      <LoaderCircle className="h-8 w-8 animate-spin text-gray-800 dark:text-gray-200" />
+                      <div className="text-sm font-medium text-gray-800 dark:text-gray-200">
+                        {stageLabel}
+                      </div>
+                    </div>
+                  </div>
+                )}
+              </div>
+            )
+          )}
+        </Formik>
+      </div>
+    </div>
+  );
+}
+
+/** Dark framed stage the tape sits on. Mirrors the minted image's background. */
+function TapeStage({ children }: { children: React.ReactNode }) {
+  return (
+    <div
+      className="rounded-xl p-4 w-fit mx-auto"
+      style={{
+        background:
+          "radial-gradient(120% 80% at 30% 20%, rgba(255,240,210,0.08), transparent 60%), #1a1614",
+        boxShadow:
+          "inset 0 0 0 1px rgba(255,255,255,0.04), 0 10px 30px -10px rgba(0,0,0,0.35)",
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Post-mint view: centered preview of the minted artifact (uploaded file
+ *  if the user provided one, otherwise the generated tape) + success message
+ *  + structured IDs the user can copy to paste into a shelf. */
+function SuccessView({
+  ids,
+  uploadedFile,
+  previewUrl,
+  onStartOver,
+}: {
+  ids: MintedIds;
+  uploadedFile: File | null;
+  previewUrl: string | null;
+  onStartOver: () => void;
+}) {
+  return (
+    <div className="flex flex-col items-center text-center space-y-6 py-6 font-roboto-condensed">
+      {uploadedFile ? (
+        <UploadedPreview file={uploadedFile} previewUrl={previewUrl} />
+      ) : (
+        <TapeStage>
+          <TapePreview size="large" />
+        </TapeStage>
+      )}
+
+      <div className="space-y-2 max-w-md">
+        <div className="inline-flex items-center gap-2 text-base font-semibold text-gray-900 dark:text-gray-100">
+          <CheckCircle2
+            size={18}
+            className="text-green-600 dark:text-green-400"
+          />
+          Receipt minted
+        </div>
+        <p className="text-sm text-gray-600 dark:text-gray-400">
+          Your receipt has been sent to the chain. On-chain confirmation can
+          take a few minutes. Copy the token ID to add this receipt to a
+          shelf.
+        </p>
+      </div>
+
+      {/* Structured IDs — mirrors pinax's PostUploadPreview layout so it's
+          familiar, and every value has a Copy button. */}
+      <div className="w-full max-w-md text-left space-y-2">
+        <IdRow label="Token ID" value={ids.tokenId} />
+        <IdRow label="Arweave ID" value={ids.arweaveId} />
+        <IdRow
+          label="File URL"
+          value={`https://arweave.net/${ids.arweaveId}`}
+          href={`https://arweave.net/${ids.arweaveId}`}
+        />
+      </div>
+
+      <div className="flex items-center gap-2">
+        <Button variant="outline" scale="sm" onClick={onStartOver}>
+          Cancel
+        </Button>
+        <Button asChild variant="info" scale="sm">
+          <Link to="/nft/$tokenId" params={{ tokenId: ids.tokenId }}>
+            View receipt <ExternalLink size={13} className="ml-1" />
+          </Link>
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+/** A label + monospace value + Copy button row — matches pinax's
+ *  TransactionHash / FileUrl pattern for consistency across the app. */
+function IdRow({
+  label,
+  value,
+  href,
+}: {
+  label: string;
+  value: string;
+  href?: string;
+}) {
+  return (
+    <div className="flex items-center justify-between gap-3">
+      <span className="text-sm font-semibold text-gray-700 dark:text-gray-300 flex-shrink-0">
+        {label}
+      </span>
+      <div className="flex items-center gap-2 min-w-0">
+        {href ? (
+          <a
+            href={href}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="px-2 py-1 border rounded text-xs font-mono bg-white dark:bg-transparent truncate max-w-[240px] text-primary/80 hover:text-primary"
+            title={value}
+          >
+            {value}
+          </a>
+        ) : (
+          <code
+            className="px-2 py-1 border rounded text-xs font-mono bg-white dark:bg-transparent truncate max-w-[240px]"
+            title={value}
+          >
+            {value}
+          </code>
+        )}
+        <Copy text={value} size="sm" />
+      </div>
+    </div>
+  );
+}
+
+/** Renders the user-selected receipt file inside the same dark stage as the
+ *  tape — actual image preview for images, a filename chip for PDFs/others. */
+function UploadedPreview({
+  file,
+  previewUrl,
+  onClear,
+}: {
+  file: File;
+  previewUrl: string | null;
+  /** If omitted, the remove ("×") button is not shown — used in the success view. */
+  onClear?: () => void;
+}) {
+  const isImage = file.type.startsWith("image/");
+  return (
+    <div className="relative">
+      <TapeStage>
+        {isImage && previewUrl ? (
+          <img
+            src={previewUrl}
+            alt={file.name}
+            className="block max-w-[240px] max-h-[400px] object-contain rounded-sm"
+          />
+        ) : (
+          <div className="w-[240px] py-10 px-4 text-center text-[#fdfbf5]">
+            <FileText size={40} className="mx-auto mb-2 opacity-80" />
+            <div className="text-sm font-medium truncate" title={file.name}>
+              {file.name}
+            </div>
+            <div className="text-xs opacity-60 mt-1">
+              {formatFileSize(file.size)}
+            </div>
+          </div>
+        )}
+      </TapeStage>
+
+      {onClear && (
+        <button
+          type="button"
+          onClick={onClear}
+          aria-label="Remove uploaded file"
+          className="absolute -top-2 -right-2 h-7 w-7 inline-flex items-center justify-center rounded-full bg-gray-900 text-white hover:bg-gray-800 shadow-md"
+        >
+          <X size={14} />
+        </button>
+      )}
+    </div>
+  );
+}
+
+export default PearlPage;
diff --git a/src/alex_frontend/lbry/src/routes/_auth/app/pearl.lazy.tsx b/src/alex_frontend/lbry/src/routes/_auth/app/pearl.lazy.tsx
new file mode 100644
index 000000000..1a182c46b
--- /dev/null
+++ b/src/alex_frontend/lbry/src/routes/_auth/app/pearl.lazy.tsx
@@ -0,0 +1,6 @@
+import { createLazyFileRoute } from '@tanstack/react-router'
+import PearlPage from './../../../pages/pearl/PearlPage'
+
+export const Route = createLazyFileRoute('/_auth/app/pearl')({
+  component: PearlPage,
+})