Durar · دُرَر

Arabic words, like pearls. An immersive, single-screen 3D space for discovering beautiful Arabic vocabulary. Word cards drift like pearls in deep water. You swipe through them, or search for one and watch it rise out of the depths.

Status: Phase 0.4 — Sharing. Reports: 0.1, 0.2, 0.3, 0.4. Setup: accounts, daily email, domain day.

Quick start

npm install
npm run dev            # http://localhost:5173
npm run build          # type-check, bundle, prerender /word/<slug> pages → dist/
npm run preview        # serve dist/ at http://localhost:4173 (clean URLs like production)
npm run validate:data  # schema check for words.json, topics.json and illustrations.json
npm run test:e2e       # Playwright (builds are served via `npm run preview`)
npm run test:db        # database tests (RLS, subscriptions); needs DATABASE_URL (PostgreSQL)
npm run test:unit      # schedule, email rendering, server handlers (handlers need DATABASE_URL)
npm run cards          # render card images into .cards/ for a look (CI uploads the real ones)
npm run illustrations  # restyle illustrations into .illustrations/ (needs Wikimedia; CI uploads them)
npm run email:render   # write today's emails to dist-email/ for a look
npm run check:functions  # compile api/ like Vercel and load it in plain Node

Accounts need a Supabase project (see docs/ACCOUNTS-SETUP.md). Copy .env.example to .env.local and fill in the values. Without them the site runs exactly as before, just without sign-in. To try accounts with no backend at all, run VITE_BACKEND=mock npm run dev: a browser-only demo that needs no email.

If Playwright can't download browsers in your environment, point it at an existing Chromium: PW_CHROMIUM_PATH=/path/to/chrome npm run test:e2e.

How to use it

Action	Mouse / trackpad	Touch	Keyboard
I know this (card sinks into the deep)	drag right · two-finger swipe right	swipe right	→
Still learning (card drifts aside, comes back soon)	drag left · two-finger swipe left	swipe left	←
Search	click the search box	tap it	/
Bring a background pearl forward	click it	tap it	—
Save to My Pearls	the pearl on the card's corner	tap it	S
Share	the share icon beside it: WhatsApp, Copy link, Download image	tap it: your phone's share sheet, with the image	Tab to it, Enter

A Text-only view toggle (bottom-left) switches to a calm HTML version with the same data and controls. It's also what you see automatically if WebGL isn't available.

Architecture

src/
  data/words.json        curated word set (140 words) — the single source of truth
  lib/words.ts           data access + search (diacritic/hamza-insensitive Arabic, translit, English)
  lib/router.ts          “/” and “/word/<slug>” routing; URL + <title> follow the focused card
  lib/cardTexture.ts     canvas renderer for card text (browser-shaped RTL Arabic)
  lib/fonts.ts           self-hosted webfonts, explicitly loaded before canvas drawing
  state/store.ts         Zustand store: rotation queue, swipes, search surfacing
  scene/                 react-three-fiber scene (lazy-loaded chunk)
    Experience.tsx       <Canvas> + scene graph
    PearlCard.tsx        one card: choreography (focus, sink, drift, rise) via critically-damped springs
    cardMaterial.ts      card shader: nacre body, iridescent rim, caustics, mip-bias depth-of-field, water fog
    Backdrop/GodRays/Particles/Bubbles
    useSwipeInput.ts     one gesture model for mouse, touch, trackpad and arrow keys
  ui/                    2D chrome: search, swipe controls, live regions, text-only view,
                         sign-in dialog, account menu, save control
  account/               accounts: Supabase client (lazy chunk), browser-only mock, store
                         (optimistic saves, pending save across sign-in), friendly errors
  pages/                 /library (My Pearls), /privacy and /credits, light CSS-only pages
  share/                 sharing (lazy chunk): share text + links, the 9:16 story image, share sheet
shared/                  code used by both site and server (Pearl of the Day schedule, flags,
                         image URLs, licences and credit lines)
api/                     Vercel functions: subscribe, confirm, unsubscribe, cron/daily
server/                  their logic: handlers, SQL-function store, email templates, SES adapter
scripts/cards.mjs        card images (social previews + email): CI renders and uploads them to img.durar.space
scripts/illustrations.mjs  illustrations: CI restyles public-domain plates and uploads them to img.durar.space
supabase/migrations/     versioned SQL: saved_pearls, subscribers, daily_sends, RLS, functions
supabase/setup/          one-off owner SQL (pg_cron schedule for the daily email)
scripts/prerender.mjs    post-build: static HTML + OG/Twitter/JSON-LD for every word; noindex /library
tests/                   Playwright e2e (desktop, mobile touch, no-WebGL, accounts, axe a11y)
tests/db/                node:test Row Level Security suite against real PostgreSQL

Design decisions:

This is the beginning of the README. Read the rest at the original. Read the full README ↗