Build FalconScan customs document assistant

.dockerignore

@@ -0,0 +1,6 @@
+.git
+.venv
+__pycache__
+.pytest_cache
+*.pyc
+tests

.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.py[cod]
+.DS_Store

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1 FALCONSCAN_OCR_ENABLED=true
+RUN apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 libgomp1 && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+COPY . .
+RUN useradd -m -u 1000 user && chown -R user:user /app
+USER user
+EXPOSE 7860
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,211 @@
+---
+title: FalconScan
+emoji: 🦅
+colorFrom: green
+colorTo: yellow
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+# FalconScan
+
+FalconScan is a bilingual, AI-assisted camera companion for customs documents. It lets a non-specialist point a phone or webcam at a manifest, bill of lading, airway bill, declaration, invoice, packing list, delivery order, or port-clearance form and tap contextual dots for plain-language definitions.
+
+The product is deliberately **glossary-first and CPU-first**. The browser provides continuous camera feedback and detects stable, sharp, well-lit frames. Only a stable frame—or an explicit “Scan now”—is sent to the backend. PaddleOCR handles English and Arabic text; local services then match customs terminology. A VLM is an optional, separately hosted enhancement, never a requirement for the core app.
+
+## 1. Project overview
+
+FalconScan is an end-to-end, camera-based customs terminology assistant for Dubai Customs, freight-forwarding desks, free-zone operators, logistics teams, and trade-compliance staff. Phase 1 delivers the CPU-friendly scanning loop; Phase 2 adds governed knowledge and feedback; Phase 3 defines optional AI/VLM enhancement without making it a core dependency.
+
+## 2. Problem statement
+
+Customs paperwork assumes specialist vocabulary. Staff often lose context by switching to a search tool or relying on an unverified explanation. FalconScan keeps the explanation attached to the physical term in the camera view.
+
+## 3. Functional requirements
+
+Requirements implemented:
+
+- Camera permission, live preview, local motion/blur/lighting signals, stable-frame auto-capture, and manual capture.
+- English and Arabic PaddleOCR with word/line bounding boxes.
+- Exact, case-insensitive, acronym, alias, Arabic, multi-word phrase, and fuzzy OCR matching.
+- Clickable dot overlays, bilingual definition cards, confidence, source labels, related terms, and RTL display.
+- Thumbs-up/down feedback, correction entry, local audit history, pending review, and SME approve/reject UI.
+- Definition priority: SME-approved → pending user correction → verified glossary → optional knowledge/RAG layer → cautious AI fallback. SME approval intentionally overrides pending user text because it is the governed official answer.
+- Optional VLM gate for low confidence, unknown terms, complex layouts, or explicit full-document analysis.
+
+## 4. Non-functional requirements
+
+- **Mobile-first responsive design:** phone portrait is the primary interaction target. Camera controls, scanning status, definition sheets, and feedback use touch-friendly dimensions and safe-area spacing. Tablet and desktop layouts progressively enhance the same interface without removing features.
+- CPU usability, bounded OCR cache, lazy model loading, and graceful operation without VLM.
+- No saved document images by default, clear provenance, and governed corrections.
+- Simple JSON persistence for the MVP and an API shape ready for later database/RAG migration.
+- Accessible semantics, readable contrast, RTL definitions, reduced-motion support, and 320px minimum viewport support.
+
+## 5. Architecture
+
+The phone performs the continuous, latency-sensitive work. The backend only receives a stable or explicitly captured frame, performs cache/OCR/knowledge lookup, and returns terms with coordinates. Feedback feeds a human-governed approval loop. Optional VLM analysis is isolated from the routine path.
+
+```mermaid
+flowchart TD
+    A["Mobile browser camera"] --> B["On-device stability, blur and lighting checks"]
+    B -->|"Stable frame or Scan now"| C["FastAPI image utilities"]
+    C --> D{"Similar frame cached?"}
+    D -->|"Yes"| H["Definition priority layer"]
+    D -->|"No"| E["PaddleOCR English + Arabic"]
+    E --> F["Text and bounding boxes"]
+    F --> G["Exact, alias, phrase and fuzzy matching"]
+    G --> H
+    H --> I["Clickable dots and definition sheet"]
+    I --> J["User feedback and corrections"]
+    J --> K["SME review"]
+    K --> H
+    E -. "Low confidence, unknown term or complex layout" .-> L["Optional external AI or VLM"]
+    L -. "Unverified result with source label" .-> H
+```
+
+The definition layer applies governed precedence: SME-approved definition, pending user correction, verified glossary, future RAG retrieval, then explicitly unverified AI fallback. Full document images are not persisted.
+
+## 6. Folder structure
+
+```text
+Browser camera
+  → local stability / blur / light checks
+  → one JPEG on stable or manual capture
+  → FastAPI → perceptual cache → PaddleOCR (EN + AR)
+  → corrections / SME / glossary / optional RAG / AI priority
+  → bounding boxes + definitions → clickable overlay
+  → feedback audit → SME approval
+  ↘ optional external VLM only when gated
+```
+
+```text
+app.py                       FastAPI routes and orchestration
+backend/ocr_service.py       Lazy bilingual PaddleOCR adapter
+backend/glossary_service.py  Matching and definition priority
+backend/feedback_service.py  Corrections, audit, SME workflow
+backend/ai_definition_service.py  Conservative AI fallback boundary
+backend/vlm_service.py       Phase 3 trigger and endpoint gate
+backend/image_utils.py       Decode, quality, frame fingerprint
+backend/progress_service.py  Persistent project checkpoint
+frontend/                    Camera UI, overlay, feedback, styles
+data/                        Glossary, corrections, approvals, cache
+tests/                       Service and API tests
+```
+
+## 7. Data model
+
+`data/glossary.json` is RAG-ready rather than a flat string map. Each canonical term can have aliases, full form, English and Arabic definitions, category, related terms, document types, and provenance. Twenty seed concepts include B/L, MAWB, HAWB, HS Code, CIF, FOB, COO, TIR, FZE, customs duty, consignee, shipper, manifest, and key trade documents.
+
+Corrections are separated into pending user suggestions and SME-approved definitions. Feedback history is append-only. For a multi-instance production deployment, replace the JSON repositories with SQLite/Postgres or a Hugging Face Dataset while keeping the service interfaces.
+
+## 8. Glossary examples
+
+The seeded bilingual knowledge includes B/L, MAWB, HAWB, HS Code, CIF, FOB, COO, TIR, FZE, Bonded Warehouse, Customs Duty, Consignee, Shipper, Manifest, Declaration Number, Incoterms, Delivery Order, Packing List, and Commercial Invoice. Each record can carry aliases, Arabic equivalents, category, document types, related terms, definition provenance, and confidence.
+
+## 9. APIs
+
+- `POST /analyze-frame` — base64 image, dimensions, language preference; returns detected terms, bounding boxes, OCR confidence, quality, cache state, unknown text, and VLM suggestion.
+- `POST /analyze-document` — analyzes uploaded JPG, PNG, WebP, PDF, or DOCX; renders a private preview and returns positioned terms with definitions.
+- `POST /explain-selection` — turns selected OCR text or a highlighted paragraph into a sourced summary and business meaning.
+- `GET /definition/{term}?language=en` — best governed definition or a labeled verification fallback.
+- `POST /submit-feedback` — records positive feedback or a correction.
+- `GET /admin/corrections` — pending review queue.
+- `POST /admin/review` — approve or reject a suggestion.
+- `POST /analyze-document-vlm` — explicit Phase 3 gate; remains graceful when unconfigured.
+- `GET /health` and `GET /progress` — runtime and project state.
+
+Interactive schemas are available at `/docs`.
+
+## 10. Frontend camera workflow
+
+The camera samples a tiny 96×72 canvas locally. Average pixel change estimates motion, vertical luminance differences provide a cheap focus signal, and brightness detects darkness/glare. Twelve good samples trigger one capture, with an eight-second cooldown. Phone portrait is the baseline UI: the camera comes first, controls are touch-sized, status remains readable over video, and definitions open as bottom sheets. At 900px and above, the scanner and control panel become a two-column desktop workspace.
+
+## 11. Backend OCR workflow
+
+The backend decodes one stable JPEG, computes an image-quality signal and visual fingerprint, then checks the bounded cache. A cache miss invokes lazy English and Arabic PaddleOCR. The backend hashes a 16×16 luminance thumbnail and reuses one of at most 100 cached OCR results for visually similar frames. Original images are not written to disk.
+
+## 12. Matching logic
+
+OCR detections retain source coordinates. The browser maps them through the contained-video scale and offsets. Definitions are selected by canonical/alias normalization, longest phrase containment, then a 0.78 fuzzy threshold. OCR and match confidence are combined and always displayed as a confidence signal—not as legal certainty.
+
+## 13. Feedback correction logic
+
+A thumbs-down correction immediately becomes the preferred pending user explanation. Feedback events remain in the audit history. The header badge shows the actual pending-review count and stays hidden when the count is zero or unavailable.
+
+## 14. SME approval workflow
+
+The SME queue shows current and suggested text, author, timestamp, and actions. Approval copies the definition into the governed store; rejection removes it from the active priority path while preserving the audit record. An approved correction becomes the official answer and overrides pending user text.
+
+## 15. AI fallback logic
+
+Unknown-term AI output is intentionally conservative and labeled `ai_generated_unverified`. Set `FALCONSCAN_AI_ENDPOINT` and `HF_TOKEN` only after implementing the chosen provider adapter. If no endpoint exists, FalconScan says that the term needs customs-expert verification rather than guessing.
+
+## 16. VLM enhancement workflow
+
+`FALCONSCAN_VLM_ENDPOINT` configures the optional Phase 3 boundary. A VLM should run outside the CPU web process and only for an explicit request, low OCR confidence, unknown content, stamps/tables, or complex layout. It must not replace word localization or the governed glossary.
+
+## 17. Run and deploy
+
+Lightweight local UI/API development (no OCR model):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements-lite.txt
+FALCONSCAN_OCR_ENABLED=false uvicorn app:app --reload
+```
+
+Full local OCR:
+
+```bash
+pip install -r requirements.txt
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+Open `http://localhost:7860`. Camera access requires localhost or HTTPS. The first English/Arabic scan downloads PaddleOCR models and therefore has a cold start.
+
+For Hugging Face Spaces:
+
+1. Create a **Docker Space** using a free CPU hardware tier.
+2. Push this repository. The README metadata and Dockerfile expose port 7860.
+3. Allow the initial image build and model download. If build size is tight, preselect only the languages you need or host model files in a Dataset.
+4. Add `HF_TOKEN`, `FALCONSCAN_AI_ENDPOINT`, or `FALCONSCAN_VLM_ENDPOINT` as secrets only if optional remote services are implemented.
+5. Treat local JSON as demo persistence: free Spaces may restart. Use persistent storage, a Dataset, or an external database before operational use.
+6. Test on HTTPS with a real phone and representative, anonymized documents.
+
+## 18. Testing plan
+
+Run `pip install -r requirements-dev.txt && pytest -q`. Automated tests cover health, exact/Arabic/fuzzy definitions, invalid images, VLM-disabled behavior, and SME priority. Manual acceptance cases:
+
+1. B/L on a bill of lading produces a dot and definition.
+2. MAWB on an airway bill is recognized.
+3. `رمز النظام المنسق` can display Arabic or English.
+4. Thumbs down saves a correction; the next lookup uses it.
+5. SME approval overrides pending user text.
+6. Poor capture suggests full-document analysis.
+7. Unknown terms get an explicitly unverified verification message.
+8. Admin can approve/reject with an audit timestamp.
+9. The app stays useful when VLM is disabled.
+10. Images never appear in `data/` after scans.
+
+## 19. Performance, security, and governance
+
+- Never OCR each frame; keep continuous work in the browser and send stable/manual frames only.
+- Resize before upload later if real documents show 1280px is sufficient; current capture preserves camera resolution for OCR quality.
+- Keep OCR lazy, cache by visual fingerprint, cap the cache, and avoid loading a VLM in-process.
+- Do not store full images by default. Persist only terms, definitions, feedback, confidence, status, and timestamps.
+- Put admin routes behind authentication before real deployment. Add rate limits, request-size limits, encryption, retention rules, and named SME identities.
+- Treat all definitions as assistance, not a customs ruling. Only governed SME content should become official knowledge.
+
+## 20. Progress checkpoint
+
+PROGRESS CHECKPOINT:
+- Completed: End-to-end camera UI, stability capture, bilingual OCR adapter, bounding boxes, glossary/fuzzy matching, dot overlays, definitions, feedback, SME workflow, guarded AI/VLM paths, data, tests, and Docker Space configuration.
+- In progress: Real-device and production Space validation.
+- Pending: Install/warm PaddleOCR models; connect optional remote AI/VLM provider; replace demo JSON for durable multi-user storage; add production authentication.
+- Current file being worked on: `README.md` (handoff complete).
+- Next exact step: Deploy to a free CPU Docker Space and test the ten manual scenarios with anonymized English/Arabic documents.
+- Important decisions made: Browser stability creates real-time feel; glossary remains primary; images are never persisted; SME-approved text outranks pending user corrections; VLM runs only behind an explicit external gate.
+- Known issues: Default Space disk is ephemeral; OCR cold start can be slow; PaddleOCR footprint is substantial; AI/VLM provider adapters are intentionally unimplemented until an endpoint contract is selected.

TASK_SHEET.md

@@ -0,0 +1,167 @@
+# FalconScan task sheet
+
+This sheet is the implementation baseline. A requirement is marked complete only when it exists in the code and has a verification path.
+
+| # | Requirement | Implementation | Status | Verification |
+|---:|---|---|---|---|
+| 1 | Browser camera view | Live `getUserMedia` preview | Complete | Start camera on localhost or HTTPS |
+| 2 | Browser-side frame stability | Motion, blur/focus, and lighting checks on a 96×72 canvas | Complete | Observe live status metrics |
+| 3 | Stable/manual frame capture | 12 stable samples or Scan now | Complete | Hold document still or tap button |
+| 4 | English and Arabic OCR | Lazy PaddleOCR service with boxes/confidence | Complete | Install full requirements and scan bilingual samples |
+| 5 | Customs glossary matching | Exact, acronym, alias, phrase, Arabic, and fuzzy matching | Complete | Automated service tests |
+| 6 | Clickable dot overlays | OCR coordinates mapped into contained camera video | Complete | Tap a detected dot |
+| 7 | Bilingual definition sheet | English/Arabic, RTL, source, confidence, related terms | Complete | Switch header language and open a term |
+| 8 | Feedback correction | Thumbs up/down, correction form, JSON persistence | Complete | Submit correction and repeat lookup |
+| 9 | SME review workflow | Pending queue, accurate header count, approve/reject | Complete | Header badge equals `/admin/corrections` item count |
+| 10 | Governed definition priority | SME → user correction → glossary → RAG → AI | Complete | Automated priority test |
+| 11 | Optional AI/VLM | Explicitly gated and disabled safely when unconfigured | Complete boundary | Configure provider adapter for live inference |
+| 12 | No image persistence | Only bounded OCR results and feedback are saved | Complete | Inspect `data/` after scan |
+| 13 | Free CPU Space deployment | Docker Space metadata and Dockerfile | Complete | Deploy and run smoke tests |
+| 14 | Architecture diagram + explanation | Mermaid diagram and textual explanation in project documentation; intentionally excluded from the operational scanning UI | Complete | View README architecture section |
+| 15 | Mobile-first responsive design | Phone portrait baseline; touch targets, safe areas, bottom-sheet dialogs; tablet/desktop progressive layouts | Complete | Test 320, 390, 768, 900, and 1440px widths |
+| 16 | Contextual Scan Status panel | Closed before scanning, manually toggleable, automatically opened after scan, responsive drawer behavior | Complete | Load app, scan, close and reopen details |
+| 17 | Trust-building privacy note | Prominent note explains that frames are analyzed but captured images are not stored | Complete | View note above scanner and inspect storage behavior |
+| 18 | Polished product UI | Restrained Apple-inspired hierarchy, translucent surfaces, system typography, purposeful motion, and reduced visual noise | Complete | Visual QA on phone and desktop |
+| 19 | Document upload | Scan Details accepts JPG, PNG, WebP, PDF, and Word DOCX; renders a private preview and uses OCR or native text extraction | Complete | Upload each supported type under 15 MB |
+| 20 | Readable detection callouts | Dots expand into one rectangular insight containing dot, divider, term, confidence, definition, and full-meaning action | Complete | Tap several dots and inspect inline insight readability |
+| 21 | Adaptive detection dots | Page area and OCR complexity determine a readable marker budget; every matched term remains accessible in Scan Details | Complete | Upload simple and dense documents |
+| 22 | Select/highlight insight | Select OCR text, a phrase, or paragraph to receive Summary and Business Meaning with governed source/confidence | Complete | Highlight text on an uploaded document preview |
+
+## Newly fixed requirements
+
+### Accurate header counting
+
+- The SME review badge is sourced from `GET /admin/corrections`.
+- Zero is not presented as a pending notification; the badge is hidden.
+- Singular/plural accessible labels reflect the real count.
+- A failed count request hides the badge instead of showing stale data.
+
+### Mobile-first responsive behavior
+
+- Base CSS targets 320px+ phone portrait screens.
+- Camera content is ordered first and uses small-viewport height units.
+- Controls meet touch-friendly sizing and use device safe-area insets.
+- Definition/admin dialogs are mobile bottom sheets and centered dialogs on larger screens.
+- Tablet enhances spacing and actions; desktop switches to a two-column scanner workspace.
+- Technical architecture stays in the README so the scanning experience remains task-focused.
+
+### Scan Status disclosure
+
+- Scan Status starts closed so the camera remains the primary task surface.
+- Users can open or close details at any time.
+- A completed scan opens the details automatically and shows result count, quality, confidence, and actions.
+- On phones the panel expands below the camera; on desktop it reveals as a right-side panel.
+
+### Trust and visual polish
+
+- Privacy is presented as a concise trust note beside the core workflow rather than as marketing decoration.
+- Architecture remains in technical documentation and is not shown in the scanning UI.
+- The visual system uses native system typography, calm neutral surfaces, selective translucency, large radii, and subtle motion.
+
+### Upload and detection readability
+
+- Scan Details includes private upload for JPG, PNG, WebP, PDF, and Word DOCX files up to 15 MB. Legacy binary `.doc` is rejected with a clear message; save it as DOCX first.
+- PDFs use positioned page text when available and OCR for scanned first pages. DOCX paragraphs are rendered into a positioned preview. Images use PaddleOCR or the installed portable CPU fallback.
+- Uploaded documents are previewed in the scanner and analyzed without being persisted.
+- Expanded detection callouts contain the status dot, divider line, term, confidence, definition, and full-meaning action.
+- Markers are collision-adjusted. Dense documents show the highest-confidence dots on the image while keeping every matched term in the details list.
+- Dots now appear by default. Tapping one expands an inline term, confidence, and definition card; the full meaning remains one tap away.
+- OCR/PDF/DOCX text regions form a selectable layer. Highlighting a word or paragraph opens a live Summary and Business Meaning insight.
+
+## Current checkpoint
+
+- Completed: Header count fix, consecutively numbered walkthrough, architecture documentation, mobile-first layout, contextual Scan Status drawer, trust note, and polished product UI.
+- In progress: Representative-device validation with live camera permissions.
+- Next: Enable full PaddleOCR and run English/Arabic document acceptance tests on a phone over HTTPS.
+- Known external issue: The supplied screenshot is a proxy authentication prompt at `91.207.173.102:4433`; it is outside FalconScan. Use the localhost URL for local testing and do not enter credentials into an unknown proxy prompt.
+
+## Mandatory release-gate checklist
+
+Every item below must pass before FalconScan is marked ready for GitHub or Hugging Face deployment.
+
+### Detection and overlay
+
+- [x] A simple document with a known customs term shows at least one dot automatically.
+- [x] A dense document uses an adaptive marker budget based on page area and OCR complexity.
+- [x] Markers do not overlap; displaced or hidden terms remain available in Scan Details.
+- [x] Multiple known terms on the same OCR line create separate detections.
+- [x] Tapping a dot expands an inline card containing term, confidence, definition, dot, and divider.
+- [x] Only one expanded inline card is shown at a time to preserve readability.
+- [x] “Open full meaning” opens the complete bilingual definition and source information.
+- [x] Resizing the viewport clears stale overlay coordinates before the next render.
+- [x] When OCR succeeds but no governed glossary term matches, contextual dots appear with an explicit unverified label instead of a misleading empty result.
+- [x] No more than three highest-confidence dots are shown on the page at once.
+- [x] Dots use the reduced 18px control size and can be dragged to uncover document text.
+- [x] A readable single-word OCR region can receive a contextual dot when it is not already represented by a verified term.
+
+### Selection, highlight, and business insight
+
+- [x] OCR/PDF/DOCX text regions are selectable without blocking detection dots.
+- [x] Selecting a known word, phrase, or paragraph opens the Live Document Insight panel.
+- [x] The panel returns both a Summary and Business Meaning.
+- [x] Recognized concepts are shown as clickable term chips.
+- [x] Known selections display verified glossary provenance and confidence.
+- [x] Unknown selections are clearly labeled as needing expert verification.
+- [x] Empty or collapsed selections do not trigger requests.
+- [x] Selection supports multi-word phrases and paragraphs without maintaining a selection history in Scan Details.
+- [x] A post-scan Info control summarizes the full recognized page using the same sourced Summary and Business Meaning panel.
+
+### Supported documents
+
+- [x] JPG upload is accepted and analyzed with positioned OCR results.
+- [x] PNG upload is accepted and analyzed with positioned OCR results.
+- [x] WebP upload is accepted and analyzed with positioned OCR results.
+- [x] Text PDF first pages are rendered and analyzed using positioned PDF text.
+- [x] Scanned PDF first pages fall back to OCR.
+- [x] Word DOCX paragraphs are extracted, rendered, and mapped to positioned regions.
+- [x] Unsupported legacy `.doc` files return a clear instruction to save as DOCX.
+- [x] Files over 15 MB are rejected before analysis.
+- [x] Uploaded document images and files are not persisted by default.
+- [x] Uploaded document previews use a dedicated scroll container with visible native scrollbars.
+
+### Camera and performance
+
+- [x] Camera OCR runs only after a stable frame or explicit Scan now action.
+- [x] Blur, motion, and lighting checks run locally in the browser.
+- [x] Similar frames use the bounded OCR cache.
+- [x] CPU OCR fallback works when PaddleOCR is unavailable.
+- [x] VLM remains optional and does not block the glossary-first workflow.
+- [x] Large uploaded images are resized to a maximum 1600px edge in the browser before transfer.
+- [x] Small images avoid unnecessary recompression.
+- [x] Portable CPU OCR is warmed in the background to reduce first-scan latency.
+
+### Responsive UI and accessibility
+
+- [x] Scan Status starts closed and opens automatically after analysis.
+- [x] Scan Status can be opened and closed manually.
+- [x] Phone portrait is the primary layout at 320px and 390px widths.
+- [x] Tablet and desktop layouts adapt without removing functionality.
+- [x] Touch targets remain usable and safe-area insets are respected.
+- [x] Arabic definitions render RTL.
+- [x] Reduced-motion preferences are respected.
+- [x] Pending SME count is accurate and hidden when zero or unavailable.
+- [x] Scan Status uses concise state-specific instructions rather than exposing raw stability, lighting, OCR, or zero-count diagnostics.
+- [x] Term-count badges are omitted from Scan Status; the result list itself communicates available concepts.
+- [x] Scan Details does not retain or display a history of selected terms.
+
+### Governance and trust
+
+- [x] The privacy note states that frames are analyzed but captured images are not stored.
+- [x] Every definition includes source type and confidence.
+- [x] SME-approved definitions override pending user corrections.
+- [x] Feedback and review actions preserve an audit history.
+- [x] AI-generated or unmatched explanations are marked unverified.
+
+### Automated verification recorded
+
+- [x] Python/API suite: 12 tests passing.
+- [x] JavaScript syntax checks: camera, overlay, feedback, and insights scripts passing.
+- [x] DOM integration: two terms produced two dots.
+- [x] DOM integration: dot click expanded the inline definition.
+- [x] DOM integration: full-meaning action opened the governed definition.
+- [x] DOM integration: text selection triggered the insight flow.
+- [x] Live API: selection returned recognized terms, summary, business meaning, source, and confidence.
+- [ ] Physical iPhone Safari camera and selection acceptance test.
+- [ ] Physical Android Chrome camera and selection acceptance test.
+- [ ] Deployed Hugging Face Space smoke test after remote synchronization.
+- [ ] GitHub CI test run after repository push.

app.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import json
+import logging
+from threading import Thread
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+
+from backend.ai_definition_service import AIDefinitionService
+from backend.document_service import DocumentService
+from backend.feedback_service import FeedbackService
+from backend.glossary_service import GlossaryService
+from backend.image_utils import decode_data_url, image_fingerprint, image_quality
+from backend.insight_service import InsightService
+from backend.ocr_service import OCRService
+from backend.progress_service import ProgressService
+from backend.vlm_service import VLMService
+
+ROOT = Path(__file__).parent
+DATA = ROOT / "data"
+logging.basicConfig(level=logging.INFO)
+
+app = FastAPI(title="FalconScan", version="1.0.0", description="CPU-first customs terminology camera assistant")
+app.mount("/static", StaticFiles(directory=ROOT / "frontend"), name="static")
+
+ocr = OCRService()
+Thread(target=ocr.warmup, daemon=True, name="falconscan-ocr-warmup").start()
+glossary = GlossaryService(DATA / "glossary.json", DATA / "user_corrections.json", DATA / "sme_approved_definitions.json")
+feedback = FeedbackService(DATA / "user_corrections.json", DATA / "feedback_history.json", DATA / "sme_approved_definitions.json")
+ai = AIDefinitionService()
+vlm = VLMService()
+progress = ProgressService(DATA / "project_progress.json")
+documents = DocumentService(ocr, glossary)
+insights = InsightService(glossary)
+
+
+class FrameRequest(BaseModel):
+    image_base64: str
+    frame_width: int = Field(gt=0, le=10000)
+    frame_height: int = Field(gt=0, le=10000)
+    language_preference: str = Field(default="en", pattern="^(en|ar)$")
+
+
+class FeedbackRequest(BaseModel):
+    term: str = Field(min_length=1, max_length=200)
+    old_definition: str = Field(default="", max_length=2000)
+    corrected_definition: Optional[str] = Field(default=None, max_length=2000)
+    feedback_type: str = Field(pattern="^(thumbs_up|thumbs_down)$")
+    suggested_by: str = Field(default="anonymous", max_length=100)
+
+
+class ReviewRequest(BaseModel):
+    term: str
+    action: str = Field(pattern="^(approve|reject)$")
+    reviewer: str = "SME"
+
+
+class VLMRequest(BaseModel):
+    image_base64: Optional[str] = None
+    user_requested: bool = True
+
+
+class DocumentRequest(BaseModel):
+    file_base64: str
+    filename: str = Field(min_length=1, max_length=255)
+    language_preference: str = Field(default="en", pattern="^(en|ar)$")
+
+
+class SelectionRequest(BaseModel):
+    text: str = Field(min_length=1, max_length=5000)
+    language_preference: str = Field(default="en", pattern="^(en|ar)$")
+
+
+@app.get("/", include_in_schema=False)
+def index():
+    return FileResponse(ROOT / "frontend" / "index.html")
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "ocr": ocr.status(), "ai_enabled": ai.enabled,
+            "vlm_enabled": vlm.enabled, "storage": "local_json"}
+
+
+@app.post("/analyze-frame")
+def analyze_frame(request: FrameRequest):
+    try:
+        image = decode_data_url(request.image_base64)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    fingerprint = image_fingerprint(image)
+    cache_path = DATA / "ocr_cache.json"
+    cache = json.loads(cache_path.read_text(encoding="utf-8"))
+    cached = cache.get(fingerprint)
+    if cached:
+        return {**cached, "cached": True}
+    quality = image_quality(image)
+    try:
+        detections = ocr.extract(image, request.language_preference)
+    except RuntimeError as exc:
+        # Honest degraded mode: camera works and reports setup rather than fabricating OCR.
+        return {"detected_terms": [], "unknown_terms": [], "ocr_items": [], "cached": False,
+                "quality": quality, "ocr_available": False, "message": str(exc),
+                "suggest_vlm": False, "vlm_reasons": []}
+    terms = glossary.match_regions(detections)
+    if len(terms) < 3:
+        terms.extend(glossary.contextual_fallbacks(detections, 3 - len(terms), terms))
+    _, unknown = glossary.match_ocr(detections)
+    mean_confidence = sum(x["confidence"] for x in detections) / len(detections) if detections else 0.0
+    suggest_vlm, reasons = vlm.should_suggest(mean_confidence, len(unknown))
+    result = {"detected_terms": terms, "unknown_terms": unknown[:10], "ocr_items": detections,
+              "cached": False, "ocr_available": True, "quality": quality,
+              "mean_ocr_confidence": round(mean_confidence, 3), "suggest_vlm": suggest_vlm,
+              "vlm_reasons": reasons}
+    cache[fingerprint] = result
+    # Bounded local cache: images are never persisted.
+    if len(cache) > 100:
+        cache.pop(next(iter(cache)))
+    cache_path.write_text(json.dumps(cache, ensure_ascii=False, indent=2), encoding="utf-8")
+    return result
+
+
+@app.post("/analyze-document")
+def analyze_document(request: DocumentRequest):
+    try:
+        return documents.analyze(request.file_base64, request.filename, request.language_preference)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+
+
+@app.post("/explain-selection")
+def explain_selection(request: SelectionRequest):
+    try:
+        return insights.explain(request.text, request.language_preference)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@app.get("/definition/{term:path}")
+def get_definition(term: str, language: str = "en"):
+    result = glossary.definition(term)
+    return result or ai.define(term, language=language)
+
+
+@app.post("/submit-feedback")
+def submit_feedback(request: FeedbackRequest):
+    if request.feedback_type == "thumbs_down" and not request.corrected_definition:
+        raise HTTPException(status_code=400, detail="A corrected definition is required for thumbs down")
+    return feedback.submit(**request.model_dump())
+
+
+@app.get("/admin/corrections")
+def pending_corrections():
+    return {"items": feedback.pending()}
+
+
+@app.post("/admin/review")
+def review_correction(request: ReviewRequest):
+    try:
+        return feedback.review(request.term, request.action, request.reviewer)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail="Correction not found") from exc
+
+
+@app.post("/analyze-document-vlm")
+def analyze_document_vlm(request: VLMRequest):
+    return vlm.analyze(request.user_requested)
+
+
+@app.get("/progress")
+def project_progress():
+    return progress.get()

backend/__init__.py

@@ -0,0 +1 @@
+"""FalconScan backend services."""

backend/ai_definition_service.py

@@ -0,0 +1,27 @@
+import os
+
+
+class AIDefinitionService:
+    """Conservative optional text-model fallback; disabled unless explicitly configured."""
+
+    def __init__(self):
+        self.endpoint = os.getenv("FALCONSCAN_AI_ENDPOINT", "")
+        self.token = os.getenv("HF_TOKEN", "")
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.endpoint and self.token)
+
+    def define(self, term: str, nearby_text: str = "", language: str = "en") -> dict:
+        # A remote call is deliberately not implicit on free Spaces. Integrators may place a
+        # compatible inference endpoint behind this interface without changing API behavior.
+        if not self.enabled:
+            message = ("هذا المصطلح يحتاج إلى تحقق من خبير جمركي."
+                       if language == "ar" else "This term needs customs expert verification.")
+            return {"term": term, "definition": message, "source": "ai_generated_unverified",
+                    "source_label": "AI-generated · unverified", "confidence": 0.2,
+                    "ai_available": False}
+        # Keep a safe placeholder rather than guessing if an endpoint contract is unknown.
+        return {"term": term, "definition": "This term needs customs expert verification.",
+                "source": "ai_generated_unverified", "source_label": "AI-generated · unverified",
+                "confidence": 0.2, "ai_available": True}

backend/document_service.py

@@ -0,0 +1,148 @@
+import base64
+import io
+import textwrap
+import zipfile
+from pathlib import Path
+from xml.etree import ElementTree
+
+from PIL import Image, ImageDraw, ImageFont
+
+from backend.glossary_service import GlossaryService
+from backend.ocr_service import OCRService
+
+
+class DocumentService:
+    MAX_BYTES = 15 * 1024 * 1024
+
+    def __init__(self, ocr: OCRService, glossary: GlossaryService):
+        self.ocr = ocr
+        self.glossary = glossary
+
+    def analyze(self, encoded: str, filename: str, language: str) -> dict:
+        try:
+            raw = base64.b64decode(encoded, validate=True)
+        except Exception as exc:
+            raise ValueError("Invalid uploaded document") from exc
+        if not raw or len(raw) > self.MAX_BYTES:
+            raise ValueError("Document must be between 1 byte and 15 MB")
+        extension = Path(filename).suffix.lower()
+        if extension in {".jpg", ".jpeg", ".png", ".webp"}:
+            return self._image(raw, language)
+        if extension == ".pdf":
+            return self._pdf(raw)
+        if extension == ".docx":
+            return self._docx(raw)
+        raise ValueError("Supported formats are JPG, PNG, WebP, PDF, and DOCX")
+
+    def _image(self, raw: bytes, language: str) -> dict:
+        try:
+            image = Image.open(io.BytesIO(raw)).convert("RGB")
+            image.load()
+        except Exception as exc:
+            raise ValueError("The uploaded image could not be opened") from exc
+        detections = self.ocr.extract(image, language)
+        terms = self.glossary.match_regions(detections)
+        if len(terms) < 3:
+            terms.extend(self.glossary.contextual_fallbacks(detections, 3 - len(terms), terms))
+        _, unknown = self.glossary.match_ocr(detections)
+        return self._result(image, terms, detections, unknown, "image_ocr")
+
+    def _pdf(self, raw: bytes) -> dict:
+        try:
+            import fitz
+        except ImportError as exc:
+            raise RuntimeError("PDF support is not installed") from exc
+        try:
+            document = fitz.open(stream=raw, filetype="pdf")
+            if document.page_count < 1:
+                raise ValueError("The PDF has no pages")
+            page = document[0]
+            zoom = min(2.0, 1800 / max(page.rect.width, page.rect.height))
+            matrix = fitz.Matrix(zoom, zoom)
+            pixmap = page.get_pixmap(matrix=matrix, alpha=False)
+            image = Image.frombytes("RGB", [pixmap.width, pixmap.height], pixmap.samples)
+            regions = []
+            for block in page.get_text("blocks"):
+                x1, y1, x2, y2, text = block[:5]
+                if text.strip():
+                    regions.append({"text": text, "bbox": [x1 * zoom, y1 * zoom, x2 * zoom, y2 * zoom],
+                                    "confidence": 1.0, "language": self._language(text)})
+            terms = self.glossary.match_regions(regions)
+            if len(terms) < 3:
+                terms.extend(self.glossary.contextual_fallbacks(regions, 3 - len(terms), terms))
+            if not regions:
+                detections = self.ocr.extract(image, "en")
+                terms = self.glossary.match_regions(detections)
+                if len(terms) < 3:
+                    terms.extend(self.glossary.contextual_fallbacks(detections, 3 - len(terms), terms))
+                _, unknown = self.glossary.match_ocr(detections)
+                return self._result(image, terms, detections, unknown, "scanned_pdf_ocr")
+            return self._result(image, terms, regions, [], "pdf_text")
+        except (ValueError, RuntimeError):
+            raise
+        except Exception as exc:
+            raise ValueError("The PDF could not be processed") from exc
+
+    def _docx(self, raw: bytes) -> dict:
+        try:
+            with zipfile.ZipFile(io.BytesIO(raw)) as archive:
+                xml = archive.read("word/document.xml")
+        except Exception as exc:
+            raise ValueError("The Word document could not be opened") from exc
+        root = ElementTree.fromstring(xml)
+        paragraphs = []
+        for paragraph in root.iter("{http://schemas.openxmlformats.org/wordprocessingml/2006/main}p"):
+            text = "".join(node.text or "" for node in paragraph.iter("{http://schemas.openxmlformats.org/wordprocessingml/2006/main}t"))
+            if text.strip():
+                paragraphs.append(text.strip())
+        if not paragraphs:
+            raise ValueError("The Word document contains no readable text")
+        return self._render_text(paragraphs)
+
+    def _render_text(self, paragraphs: list[str]) -> dict:
+        width, margin, line_height = 1400, 100, 42
+        wrapped = []
+        for paragraph in paragraphs:
+            wrapped.extend(textwrap.wrap(paragraph, width=85, break_long_words=False) or [""])
+            wrapped.append("")
+        height = min(2200, max(900, margin * 2 + len(wrapped) * line_height))
+        image = Image.new("RGB", (width, height), "#ffffff")
+        draw = ImageDraw.Draw(image)
+        try:
+            font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 28)
+        except OSError:
+            font = ImageFont.load_default()
+        regions = []
+        y = margin
+        for line in wrapped:
+            if y + line_height > height - margin:
+                break
+            if line:
+                draw.text((margin, y), line, fill="#17211e", font=font)
+                regions.append({"text": line, "bbox": [margin, y, width - margin, y + line_height],
+                                "confidence": 1.0, "language": self._language(line)})
+            y += line_height
+        terms = self.glossary.match_regions(regions)
+        if len(terms) < 3:
+            terms.extend(self.glossary.contextual_fallbacks(regions, 3 - len(terms), terms))
+        return self._result(image, terms, regions, [], "docx_text")
+
+    @staticmethod
+    def _language(text: str) -> str:
+        return "ar" if any("\u0600" <= character <= "\u06ff" for character in text) else "en"
+
+    @staticmethod
+    def _result(image: Image.Image, terms: list, detections: list, unknown: list, method: str) -> dict:
+        output = io.BytesIO()
+        image.save(output, format="JPEG", quality=88, optimize=True)
+        return {
+            "detected_terms": terms,
+            "ocr_items": detections,
+            "unknown_terms": unknown[:10],
+            "frame_width": image.width,
+            "frame_height": image.height,
+            "preview_base64": "data:image/jpeg;base64," + base64.b64encode(output.getvalue()).decode(),
+            "ocr_available": True,
+            "analysis_method": method,
+            "mean_ocr_confidence": round(sum(float(item.get("confidence", 1)) for item in detections) / len(detections), 3) if detections else 0,
+        }

backend/feedback_service.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from threading import RLock
+from uuid import uuid4
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class FeedbackService:
+    def __init__(self, corrections_path: Path, history_path: Path, approved_path: Path):
+        self.corrections_path = corrections_path
+        self.history_path = history_path
+        self.approved_path = approved_path
+        self.lock = RLock()
+
+    @staticmethod
+    def _read(path: Path):
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    @staticmethod
+    def _write(path: Path, value):
+        path.write_text(json.dumps(value, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    def submit(self, term: str, old_definition: str, corrected_definition: str | None,
+               feedback_type: str, suggested_by: str = "anonymous") -> dict:
+        with self.lock:
+            event_id = str(uuid4())
+            event = {"id": event_id, "term": term, "old_definition": old_definition,
+                     "corrected_definition": corrected_definition, "feedback_type": feedback_type,
+                     "suggested_by": suggested_by, "status": "pending_sme_review" if corrected_definition else "recorded",
+                     "created_at": now()}
+            history = self._read(self.history_path)
+            history.append(event)
+            self._write(self.history_path, history)
+            if corrected_definition:
+                corrections = self._read(self.corrections_path)
+                corrections[term] = {**event, "source": "user_corrected",
+                                     "previous_definition": old_definition}
+                self._write(self.corrections_path, corrections)
+            return {"status": "saved", "message": "Correction saved and will be used next time." if corrected_definition else "Feedback recorded.",
+                    "source": "user_corrected" if corrected_definition else "feedback", "id": event_id}
+
+    def pending(self) -> list[dict]:
+        corrections = self._read(self.corrections_path)
+        return [value for value in corrections.values() if value.get("status") == "pending_sme_review"]
+
+    def review(self, term: str, action: str, reviewer: str = "SME") -> dict:
+        with self.lock:
+            corrections = self._read(self.corrections_path)
+            if term not in corrections:
+                raise KeyError(term)
+            correction = corrections[term]
+            correction.update({"status": "approved" if action == "approve" else "rejected",
+                               "reviewed_by": reviewer, "reviewed_at": now()})
+            corrections[term] = correction
+            self._write(self.corrections_path, corrections)
+            if action == "approve":
+                approved = self._read(self.approved_path)
+                approved[term] = {
+                    "term": term, "definition": correction["corrected_definition"],
+                    "previous_definition": correction.get("previous_definition"),
+                    "source": "sme_approved", "approved_by": reviewer,
+                    "approved_at": correction["reviewed_at"],
+                }
+                self._write(self.approved_path, approved)
+            return {"status": correction["status"], "term": term}

backend/glossary_service.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import json
+import re
+from difflib import SequenceMatcher
+from pathlib import Path
+from threading import RLock
+
+
+SOURCE_LABELS = {
+    "user_corrected": "User correction (pending SME review)",
+    "sme_approved": "SME-approved definition",
+    "verified_glossary": "Verified Customs Glossary",
+    "rag_retrieved": "Knowledge Base",
+    "ai_generated_unverified": "AI-generated · unverified",
+}
+
+
+def normalize(value: str) -> str:
+    return re.sub(r"[^\w\u0600-\u06ff]+", " ", value.casefold()).strip()
+
+
+class GlossaryService:
+    def __init__(self, glossary_path: Path, corrections_path: Path, approved_path: Path):
+        self.glossary_path = glossary_path
+        self.corrections_path = corrections_path
+        self.approved_path = approved_path
+        self.lock = RLock()
+
+    @staticmethod
+    def _read(path: Path) -> dict:
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def _index(self) -> tuple[dict, dict]:
+        glossary = self._read(self.glossary_path)
+        aliases: dict[str, str] = {}
+        for canonical, entry in glossary.items():
+            for alias in [canonical, *entry.get("aliases", [])]:
+                aliases[normalize(alias)] = canonical
+        return glossary, aliases
+
+    def find_match(self, text: str, threshold: float = 0.78) -> dict | None:
+        glossary, aliases = self._index()
+        target = normalize(text)
+        if not target:
+            return None
+        # Prefer longest contained phrases, then fuzzy matching for OCR errors.
+        contained = [(alias, canonical) for alias, canonical in aliases.items()
+                     if alias and re.search(rf"(?<!\w){re.escape(alias)}(?!\w)", target)]
+        match_type, score = "exact", 1.0
+        if contained:
+            alias, canonical = max(contained, key=lambda item: len(item[0]))
+            match_type = "exact" if alias == target else "phrase"
+        else:
+            alias, canonical, score = "", "", 0.0
+            for candidate, name in aliases.items():
+                candidate_score = SequenceMatcher(None, target, candidate).ratio()
+                if candidate_score > score:
+                    alias, canonical, score = candidate, name, candidate_score
+            if score < threshold:
+                return None
+            match_type = "fuzzy"
+        return {"canonical": canonical, "entry": glossary[canonical],
+                "match_type": match_type, "match_confidence": round(score, 3)}
+
+    def definition(self, term: str) -> dict | None:
+        with self.lock:
+            matched = self.find_match(term)
+            canonical = matched["canonical"] if matched else term
+            norm = normalize(canonical)
+            approved = self._read(self.approved_path)
+            corrections = self._read(self.corrections_path)
+            # SME approval is official and intentionally overrides pending user correction.
+            selected = next((v for k, v in approved.items() if normalize(k) == norm), None)
+            if selected:
+                return self._response(canonical, selected, "sme_approved", 1.0, matched)
+            selected = next((v for k, v in corrections.items()
+                             if normalize(k) == norm and v.get("status") == "pending_sme_review"), None)
+            if selected:
+                item = dict(selected)
+                item["definition"] = item.get("corrected_definition", item.get("definition", ""))
+                return self._response(canonical, item, "user_corrected", 0.9, matched)
+            if matched:
+                return self._response(canonical, matched["entry"],
+                                      matched["entry"].get("source", "verified_glossary"),
+                                      matched["match_confidence"], matched)
+            return None
+
+    @staticmethod
+    def _response(term: str, entry: dict, source: str, confidence: float, matched: dict | None) -> dict:
+        return {
+            "term": term,
+            "full_form": entry.get("full_form"),
+            "definition": entry.get("definition", ""),
+            "definition_ar": entry.get("definition_ar"),
+            "source": source,
+            "source_label": SOURCE_LABELS.get(source, source),
+            "confidence": round(float(confidence), 3),
+            "category": entry.get("category"),
+            "related_terms": entry.get("related_terms", []),
+            "document_types": entry.get("document_types", []),
+            "match_type": matched.get("match_type") if matched else "direct",
+        }
+
+    def match_ocr(self, detections: list[dict]) -> tuple[list[dict], list[dict]]:
+        found, unknown = [], []
+        for item in detections:
+            definition = self.definition(item["text"])
+            if definition:
+                definition.update({"bbox": item["bbox"], "ocr_text": item["text"],
+                                   "ocr_confidence": item["confidence"], "language": item["language"]})
+                definition["confidence"] = round(definition["confidence"] * item["confidence"], 3)
+                found.append(definition)
+            elif len(item["text"]) >= 3:
+                unknown.append(item)
+        return found, unknown
+
+    def match_regions(self, regions: list[dict]) -> list[dict]:
+        """Find every known canonical term inside positioned text regions."""
+        _, aliases = self._index()
+        found: list[dict] = []
+        seen: set[tuple[str, tuple[int, ...]]] = set()
+        for region in regions:
+            normalized_text = normalize(region.get("text", ""))
+            if not normalized_text:
+                continue
+            matches: dict[str, str] = {}
+            for alias, canonical in aliases.items():
+                if alias and re.search(rf"(?<!\w){re.escape(alias)}(?!\w)", normalized_text):
+                    previous = matches.get(canonical, "")
+                    if len(alias) > len(previous):
+                        matches[canonical] = alias
+            for canonical in matches:
+                bbox = [round(value) for value in region["bbox"]]
+                key = (canonical, tuple(bbox))
+                if key in seen:
+                    continue
+                seen.add(key)
+                definition = self.definition(canonical)
+                if definition:
+                    definition.update({
+                        "bbox": bbox,
+                        "ocr_text": region.get("text", canonical),
+                        "ocr_confidence": region.get("confidence", 1.0),
+                        "language": region.get("language", "en"),
+                    })
+                    definition["confidence"] = round(
+                        definition["confidence"] * float(region.get("confidence", 1.0)), 3
+                    )
+                    found.append(definition)
+        return found
+
+    def contextual_fallbacks(self, regions: list[dict], limit: int = 6,
+                             existing: list[dict] | None = None) -> list[dict]:
+        """Return clearly unverified markers when OCR succeeds but the governed glossary has no match."""
+        candidates = []
+        occupied = {tuple(item.get("bbox", [])) for item in (existing or [])}
+        seen = set()
+        for region in sorted(regions, key=lambda item: float(item.get("confidence", 0)), reverse=True):
+            text = " ".join(str(region.get("text", "")).split())
+            region_box = tuple(round(value) for value in region.get("bbox", []))
+            if region_box in occupied:
+                continue
+            if not 2 <= len(text) <= 120 or float(region.get("confidence", 1)) < 0.55:
+                continue
+            label = text if len(text) <= 58 else text[:55].rstrip() + "…"
+            key = normalize(label)
+            if not key or key in seen:
+                continue
+            seen.add(key)
+            confidence = round(min(0.62, float(region.get("confidence", 1)) * 0.62), 3)
+            candidates.append({
+                "term": label,
+                "full_form": None,
+                "definition": "This document phrase is not yet in the verified customs glossary. Select or highlight it for a contextual summary and business meaning.",
+                "definition_ar": None,
+                "source": "ai_generated_unverified",
+                "source_label": "Contextual marker · needs verification",
+                "confidence": confidence,
+                "category": "Document Context",
+                "related_terms": [],
+                "document_types": [],
+                "match_type": "contextual_fallback",
+                "bbox": list(region_box),
+                "ocr_text": text,
+                "ocr_confidence": region.get("confidence", 1.0),
+                "language": region.get("language", "en"),
+            })
+            if len(candidates) >= limit:
+                break
+        return candidates

backend/image_utils.py

@@ -0,0 +1,42 @@
+import base64
+import hashlib
+import io
+from typing import Tuple
+
+from PIL import Image, ImageStat
+
+
+def decode_data_url(value: str) -> Image.Image:
+    """Decode a base64 data URL (or raw base64) into a normalized RGB image."""
+    if not value:
+        raise ValueError("image_base64 is required")
+    payload = value.split(",", 1)[1] if "," in value else value
+    try:
+        raw = base64.b64decode(payload, validate=True)
+        image = Image.open(io.BytesIO(raw))
+        image.load()
+        return image.convert("RGB")
+    except Exception as exc:
+        raise ValueError("Invalid base64 image") from exc
+
+
+def image_fingerprint(image: Image.Image, size: Tuple[int, int] = (16, 16)) -> str:
+    """Perceptual-ish hash suitable for avoiding repeat OCR on nearly identical frames."""
+    thumb = image.convert("L").resize(size)
+    pixels = list(thumb.getdata())
+    mean = sum(pixels) / len(pixels)
+    bits = "".join("1" if pixel >= mean else "0" for pixel in pixels)
+    return hashlib.sha256(bits.encode()).hexdigest()[:24]
+
+
+def image_quality(image: Image.Image) -> dict:
+    gray = image.convert("L")
+    stat = ImageStat.Stat(gray)
+    brightness = stat.mean[0]
+    # Variance is a cheap CPU-only sharpness signal; browser performs the primary check.
+    variance = stat.var[0]
+    return {
+        "brightness": round(brightness, 2),
+        "contrast": round(variance ** 0.5, 2),
+        "acceptable": 35 <= brightness <= 225 and variance >= 20,
+    }

backend/insight_service.py

@@ -0,0 +1,62 @@
+from backend.glossary_service import GlossaryService
+
+
+CATEGORY_MEANING = {
+    "Air Cargo": "This affects how air cargo is documented, consolidated, tracked, and released.",
+    "Customs Classification": "This can affect duty rates, permits, restrictions, reporting, and customs clearance.",
+    "Customs Charges": "This can affect the landed cost and payment required before goods are released.",
+    "Shipping Documents": "This is part of the evidence customs and carriers use to identify and release a shipment.",
+    "Trade Documents": "This supports customs valuation, verification, and consistency checks across the shipment file.",
+    "Incoterms": "This defines which party carries transport cost, operational responsibility, and risk at each stage.",
+    "Shipment Parties": "This identifies who sends, receives, or takes responsibility for the shipment.",
+    "Cargo Release": "This can determine whether a carrier or terminal is authorized to release the cargo.",
+    "Customs Clearance": "This is used to trace the declaration and progress the shipment through customs controls.",
+}
+
+
+class InsightService:
+    def __init__(self, glossary: GlossaryService):
+        self.glossary = glossary
+
+    def explain(self, text: str, language: str = "en") -> dict:
+        clean = " ".join(text.split())[:5000]
+        if not clean:
+            raise ValueError("Select a word, phrase, or paragraph first")
+        terms = self.glossary.match_regions([{
+            "text": clean, "bbox": [0, 0, 1, 1], "confidence": 1.0, "language": language,
+        }])
+        unique = []
+        seen = set()
+        for term in terms:
+            if term["term"] not in seen:
+                seen.add(term["term"])
+                unique.append(term)
+        if unique:
+            names = ", ".join(item["term"] for item in unique[:4])
+            definitions = " ".join(item["definition"] for item in unique[:3])
+            summary = f"This selection contains {len(unique)} recognized trade concept{'s' if len(unique) != 1 else ''}: {names}. {definitions}"
+            meanings = []
+            for item in unique:
+                meaning = CATEGORY_MEANING.get(item.get("category"))
+                if meaning and meaning not in meanings:
+                    meanings.append(meaning)
+            business_meaning = " ".join(meanings[:3]) or "Use these terms to cross-check the shipment documents and confirm the responsible parties before clearance."
+            confidence = round(sum(item["confidence"] for item in unique) / len(unique), 3)
+            source = "verified_glossary"
+            source_label = "Verified Customs Glossary"
+        else:
+            excerpt = clean if len(clean) <= 220 else clean[:217] + "…"
+            summary = f"Selected document text: {excerpt}"
+            business_meaning = "No governed customs term was found in this selection. Review it in the surrounding document context or request customs-expert verification before acting on it."
+            confidence = 0.35
+            source = "ai_generated_unverified"
+            source_label = "Context summary · needs expert verification"
+        return {
+            "selected_text": clean,
+            "summary": summary,
+            "business_meaning": business_meaning,
+            "recognized_terms": unique,
+            "source": source,
+            "source_label": source_label,
+            "confidence": confidence,
+        }

backend/ocr_service.py

@@ -0,0 +1,136 @@
+import logging
+import os
+import re
+from typing import Any
+
+import numpy as np
+from PIL import Image
+
+logger = logging.getLogger(__name__)
+
+
+class OCRService:
+    """Lazy PaddleOCR adapter. Models load only on the first real scan."""
+
+    def __init__(self):
+        self.enabled = os.getenv("FALCONSCAN_OCR_ENABLED", "true").lower() == "true"
+        self._engines: dict[str, Any] = {}
+        self._rapid = None
+        self.warming = False
+        self.ready = False
+
+    def _engine(self, language: str):
+        key = "ar" if language == "ar" else "en"
+        if key not in self._engines:
+            if not self.enabled:
+                raise RuntimeError("OCR is disabled")
+            try:
+                from paddleocr import PaddleOCR
+            except ImportError as exc:
+                raise RuntimeError("PaddleOCR is not installed") from exc
+            # PaddleOCR uses Arabic model code 'ar'. Angle classification helps camera captures.
+            self._engines[key] = PaddleOCR(use_angle_cls=True, lang=key, show_log=False)
+        return self._engines[key]
+
+    @staticmethod
+    def _box(points: list) -> list[int]:
+        xs = [point[0] for point in points]
+        ys = [point[1] for point in points]
+        return [round(min(xs)), round(min(ys)), round(max(xs)), round(max(ys))]
+
+    @staticmethod
+    def _language(text: str) -> str:
+        return "ar" if re.search(r"[\u0600-\u06ff]", text) else "en"
+
+    def extract(self, image: Image.Image, language_preference: str = "en") -> list[dict]:
+        if not self.enabled:
+            raise RuntimeError("OCR is disabled")
+        try:
+            import paddleocr  # noqa: F401
+            paddle_available = True
+        except ImportError:
+            paddle_available = False
+        if not paddle_available:
+            return self._extract_rapid(image)
+
+        languages = ["ar", "en"] if language_preference == "ar" else ["en", "ar"]
+        detections: list[dict] = []
+        seen: set[tuple[str, tuple[int, ...]]] = set()
+        for language in languages:
+            try:
+                result = self._engine(language).ocr(np.asarray(image), cls=True) or []
+            except RuntimeError:
+                raise
+            except Exception as exc:
+                logger.warning("%s OCR failed: %s", language, exc)
+                continue
+            for page in result:
+                for line in page or []:
+                    points, value = line
+                    text, confidence = value
+                    box = self._box(points)
+                    key = (text.strip().casefold(), tuple(box))
+                    if text.strip() and key not in seen:
+                        seen.add(key)
+                        detections.append({
+                            "text": text.strip(), "bbox": box,
+                            "confidence": round(float(confidence), 4),
+                            "language": self._language(text),
+                        })
+        return detections
+
+    def _extract_rapid(self, image: Image.Image) -> list[dict]:
+        """Portable CPU fallback for environments where Paddle wheels are unavailable."""
+        try:
+            from rapidocr_onnxruntime import RapidOCR
+        except ImportError as exc:
+            raise RuntimeError("Neither PaddleOCR nor the CPU fallback is installed") from exc
+        if self._rapid is None:
+            self._rapid = RapidOCR()
+        result, _ = self._rapid(np.asarray(image))
+        self.ready = True
+        detections = []
+        for line in result or []:
+            points, text, confidence = line
+            if text and text.strip():
+                detections.append({
+                    "text": text.strip(),
+                    "bbox": self._box(points),
+                    "confidence": round(float(confidence), 4),
+                    "language": self._language(text),
+                })
+        return detections
+
+    def warmup(self) -> None:
+        """Load the portable OCR sessions before the user's first scan."""
+        if not self.enabled or self.ready or self.warming:
+            return
+        self.warming = True
+        try:
+            try:
+                import paddleocr  # noqa: F401
+                # Paddle remains lazy because two multilingual models are substantially larger.
+                return
+            except ImportError:
+                pass
+            self._extract_rapid(Image.new("RGB", (320, 128), "white"))
+        except Exception as exc:
+            logger.warning("OCR warm-up failed: %s", exc)
+        finally:
+            self.warming = False
+
+    def status(self) -> dict:
+        try:
+            import paddleocr  # noqa: F401
+            installed = True
+        except ImportError:
+            installed = False
+        try:
+            import rapidocr_onnxruntime  # noqa: F401
+            fallback_installed = True
+        except ImportError:
+            fallback_installed = False
+        return {"enabled": self.enabled, "installed": installed,
+                "fallback_installed": fallback_installed,
+                "loaded_languages": list(self._engines),
+                "warming": self.warming, "ready": self.ready}

backend/progress_service.py

@@ -0,0 +1,22 @@
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from threading import RLock
+
+
+class ProgressService:
+    def __init__(self, path: Path):
+        self.path = path
+        self.lock = RLock()
+
+    def get(self) -> dict:
+        with self.lock:
+            return json.loads(self.path.read_text(encoding="utf-8"))
+
+    def update(self, **changes) -> dict:
+        with self.lock:
+            data = self.get()
+            data.update(changes)
+            data["last_updated"] = datetime.now(timezone.utc).isoformat()
+            self.path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+            return data

backend/vlm_service.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import os
+
+
+class VLMService:
+    """Phase 3 gate. Never loads a VLM in the CPU process."""
+
+    def __init__(self):
+        self.endpoint = os.getenv("FALCONSCAN_VLM_ENDPOINT", "")
+        self.token = os.getenv("HF_TOKEN", "")
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.endpoint and self.token)
+
+    def should_suggest(self, ocr_confidence: float, unknown_count: int,
+                       user_requested: bool = False, complex_layout: bool = False) -> tuple[bool, list[str]]:
+        reasons = []
+        if ocr_confidence < 0.7:
+            reasons.append("low_ocr_confidence")
+        if unknown_count:
+            reasons.append("unknown_terms")
+        if user_requested:
+            reasons.append("user_requested")
+        if complex_layout:
+            reasons.append("complex_layout")
+        return bool(reasons), reasons
+
+    def analyze(self, user_requested: bool) -> dict:
+        if not user_requested:
+            return {"status": "not_run", "message": "VLM analysis requires an explicit trigger."}
+        if not self.enabled:
+            return {"status": "unavailable", "message": "Optional VLM endpoint is not configured. Glossary-first OCR remains available."}
+        return {"status": "configured", "message": "VLM endpoint is configured; provider adapter can be enabled for the selected model."}

data/feedback_history.json

@@ -0,0 +1 @@
+[]

data/glossary.json

@@ -0,0 +1,123 @@
+{
+  "B/L": {
+    "aliases": ["BL", "Bill of Lading", "بوليصة شحن"],
+    "full_form": "Bill of Lading",
+    "definition": "A carrier-issued document that records the goods shipped, transport terms, and who may receive the cargo.",
+    "definition_ar": "مستند يصدره الناقل يوضح البضائع المشحونة وشروط النقل والجهة التي يحق لها استلامها.",
+    "category": "Shipping Documents", "related_terms": ["Shipper", "Consignee", "Manifest"],
+    "document_types": ["Bill of Lading", "Manifest"], "source": "verified_glossary"
+  },
+  "MAWB": {
+    "aliases": ["Master Air Waybill", "Master AWB", "بوليصة الشحن الجوي الرئيسية"],
+    "full_form": "Master Air Waybill",
+    "definition": "The main air cargo transport document issued by an airline or carrier for a consolidated shipment.",
+    "definition_ar": "مستند النقل الجوي الرئيسي الذي تصدره شركة الطيران أو الناقل لشحنة مجمعة.",
+    "category": "Air Cargo", "related_terms": ["HAWB", "Carrier", "Consignee", "Shipper"],
+    "document_types": ["Air Waybill", "Manifest"], "source": "verified_glossary"
+  },
+  "HAWB": {
+    "aliases": ["House Air Waybill", "House AWB", "بوليصة شحن جوي فرعية"],
+    "full_form": "House Air Waybill",
+    "definition": "An air cargo document issued by a freight forwarder for an individual shipment within a consolidated load.",
+    "definition_ar": "مستند شحن جوي يصدره وكيل الشحن لشحنة فردية ضمن شحنة مجمعة.",
+    "category": "Air Cargo", "related_terms": ["MAWB", "Freight Forwarder"], "document_types": ["Air Waybill"], "source": "verified_glossary"
+  },
+  "HS Code": {
+    "aliases": ["HS", "Harmonized System Code", "Harmonised System Code", "رمز النظام المنسق", "الرمز المنسق"],
+    "full_form": "Harmonized System Code",
+    "definition": "A standard code used to classify traded goods for customs duty and import or export rules.",
+    "definition_ar": "رمز معياري لتصنيف السلع المتداولة وتحديد الرسوم الجمركية وقواعد الاستيراد أو التصدير.",
+    "category": "Customs Classification", "related_terms": ["Customs Duty", "Tariff", "Commodity"],
+    "document_types": ["Customs Declaration", "Commercial Invoice"], "source": "verified_glossary"
+  },
+  "CIF": {
+    "aliases": ["Cost Insurance and Freight", "التكلفة والتأمين وأجرة الشحن"], "full_form": "Cost, Insurance and Freight",
+    "definition": "An Incoterm where the seller pays cost, marine insurance, and freight to the named destination port.",
+    "definition_ar": "شرط تجاري يدفع فيه البائع التكلفة والتأمين البحري والشحن حتى ميناء الوجهة المحدد.",
+    "category": "Incoterms", "related_terms": ["FOB", "Incoterms"], "document_types": ["Commercial Invoice"], "source": "verified_glossary"
+  },
+  "FOB": {
+    "aliases": ["Free On Board", "التسليم على ظهر السفينة"], "full_form": "Free On Board",
+    "definition": "An Incoterm where risk transfers to the buyer once goods are loaded aboard the vessel at the named port.",
+    "definition_ar": "شرط تجاري تنتقل فيه المخاطر إلى المشتري بعد تحميل البضاعة على السفينة في الميناء المحدد.",
+    "category": "Incoterms", "related_terms": ["CIF", "Incoterms"], "document_types": ["Commercial Invoice"], "source": "verified_glossary"
+  },
+  "COO": {
+    "aliases": ["Certificate of Origin", "شهادة المنشأ"], "full_form": "Certificate of Origin",
+    "definition": "A document certifying the country where goods were produced or manufactured.",
+    "definition_ar": "مستند يثبت الدولة التي أُنتجت أو صُنعت فيها البضائع.",
+    "category": "Trade Documents", "related_terms": ["Commercial Invoice", "Exporter"], "document_types": ["Certificate of Origin"], "source": "verified_glossary"
+  },
+  "TIR": {
+    "aliases": ["Transports Internationaux Routiers", "النقل البري الدولي"], "full_form": "Transports Internationaux Routiers",
+    "definition": "An international customs transit system that lets sealed road cargo cross participating borders with simplified checks.",
+    "definition_ar": "نظام عبور جمركي دولي يتيح للبضائع البرية المختومة عبور حدود الدول المشاركة بإجراءات مبسطة.",
+    "category": "Customs Transit", "related_terms": ["Bonded Warehouse", "Manifest"], "document_types": ["TIR Carnet"], "source": "verified_glossary"
+  },
+  "FZE": {
+    "aliases": ["Free Zone Establishment", "مؤسسة منطقة حرة"], "full_form": "Free Zone Establishment",
+    "definition": "A legal entity registered in a UAE free zone, typically owned by one shareholder.",
+    "definition_ar": "كيان قانوني مسجل في منطقة حرة بدولة الإمارات ويكون عادةً مملوكاً لمساهم واحد.",
+    "category": "Free Zones", "related_terms": ["Free Zone", "Importer"], "document_types": ["Trade License"], "source": "verified_glossary"
+  },
+  "Bonded Warehouse": {
+    "aliases": ["Customs Bonded Warehouse", "مستودع جمركي", "مستودع مرخص"],
+    "definition": "An authorized facility where imported goods can be stored before customs duty is paid or the goods are re-exported.",
+    "definition_ar": "منشأة مرخصة تُخزن فيها البضائع المستوردة قبل دفع الرسوم الجمركية أو إعادة تصديرها.",
+    "category": "Customs Facilities", "related_terms": ["Customs Duty", "TIR"], "document_types": ["Warehouse Entry"], "source": "verified_glossary"
+  },
+  "Customs Duty": {
+    "aliases": ["Import Duty", "Duty", "الرسوم الجمركية"],
+    "definition": "A tax charged by customs on imported or, in some cases, exported goods.",
+    "definition_ar": "ضريبة تفرضها الجمارك على البضائع المستوردة، وفي بعض الحالات المصدرة.",
+    "category": "Customs Charges", "related_terms": ["HS Code", "CIF"], "document_types": ["Customs Declaration"], "source": "verified_glossary"
+  },
+  "Consignee": {
+    "aliases": ["Receiver", "المرسل إليه", "المستلم"],
+    "definition": "The person or company named to receive the shipped goods.",
+    "definition_ar": "الشخص أو الشركة المذكورة لاستلام البضائع المشحونة.",
+    "category": "Shipment Parties", "related_terms": ["Shipper", "Carrier"], "document_types": ["Bill of Lading", "Air Waybill"], "source": "verified_glossary"
+  },
+  "Shipper": {
+    "aliases": ["Consignor", "المرسل", "الشاحن"],
+    "definition": "The person or company that sends the goods and is named on the transport document.",
+    "definition_ar": "الشخص أو الشركة التي ترسل البضائع ويظهر اسمها في مستند النقل.",
+    "category": "Shipment Parties", "related_terms": ["Consignee", "Carrier"], "document_types": ["Bill of Lading", "Air Waybill"], "source": "verified_glossary"
+  },
+  "Manifest": {
+    "aliases": ["Cargo Manifest", "بيان الشحنة", "قائمة الشحن"],
+    "definition": "A consolidated list of cargo, passengers, or containers carried by a vessel, aircraft, or vehicle.",
+    "definition_ar": "قائمة مجمعة بالبضائع أو الركاب أو الحاويات التي تنقلها سفينة أو طائرة أو مركبة.",
+    "category": "Shipping Documents", "related_terms": ["B/L", "MAWB"], "document_types": ["Manifest"], "source": "verified_glossary"
+  },
+  "Declaration Number": {
+    "aliases": ["Customs Declaration Number", "رقم البيان", "رقم البيان الجمركي"],
+    "definition": "The unique reference assigned to a customs declaration for tracking and clearance.",
+    "definition_ar": "المرجع الفريد المخصص للبيان الجمركي لأغراض التتبع والتخليص.",
+    "category": "Customs Clearance", "related_terms": ["Customs Declaration"], "document_types": ["Customs Declaration"], "source": "verified_glossary"
+  },
+  "Incoterms": {
+    "aliases": ["International Commercial Terms", "شروط التجارة الدولية"],
+    "definition": "Standard trade rules defining how delivery costs, tasks, and risks are split between seller and buyer.",
+    "definition_ar": "قواعد تجارية معيارية تحدد توزيع تكاليف ومهام ومخاطر التسليم بين البائع والمشتري.",
+    "category": "Trade Terms", "related_terms": ["CIF", "FOB"], "document_types": ["Commercial Invoice", "Sales Contract"], "source": "verified_glossary"
+  },
+  "Delivery Order": {
+    "aliases": ["D/O", "DO", "أمر تسليم", "إذن التسليم"],
+    "definition": "An instruction authorizing a terminal or carrier to release cargo to the named recipient.",
+    "definition_ar": "تعليمات تجيز للمحطة أو الناقل الإفراج عن البضاعة للمستلم المحدد.",
+    "category": "Cargo Release", "related_terms": ["Consignee", "B/L"], "document_types": ["Delivery Order"], "source": "verified_glossary"
+  },
+  "Packing List": {
+    "aliases": ["قائمة التعبئة", "بيان التعبئة"],
+    "definition": "A detailed list of package contents, quantities, weights, and dimensions in a shipment.",
+    "definition_ar": "قائمة تفصيلية بمحتويات الطرود والكميات والأوزان والأبعاد في الشحنة.",
+    "category": "Trade Documents", "related_terms": ["Commercial Invoice"], "document_types": ["Packing List"], "source": "verified_glossary"
+  },
+  "Commercial Invoice": {
+    "aliases": ["Trade Invoice", "فاتورة تجارية"],
+    "definition": "The seller's bill showing the goods, parties, prices, currency, and trade terms used for customs valuation.",
+    "definition_ar": "فاتورة البائع التي توضح البضائع والأطراف والأسعار والعملة والشروط التجارية المستخدمة للتقييم الجمركي.",
+    "category": "Trade Documents", "related_terms": ["Packing List", "HS Code", "COO"], "document_types": ["Commercial Invoice"], "source": "verified_glossary"
+  }
+}

data/ocr_cache.json

@@ -0,0 +1 @@
+{}

data/project_progress.json

@@ -0,0 +1,11 @@
+{
+  "project": "FalconScan",
+  "current_phase": "Phases 1–3 designed; Phase 1 implemented",
+  "completed_modules": ["Problem Statement", "Requirements", "Architecture Documentation", "Glossary Design", "OCR Service", "Glossary Matching", "Mobile-first Camera UI", "Responsive Desktop Layout", "Collapsible Scan Status", "Document Image Upload", "Adaptive Dot Overlay", "Selectable OCR Text Layer", "Summary and Business Meaning Insights", "Privacy Trust Note", "Polished Product UI", "Stable Frame Capture", "Feedback Correction", "Accurate Header Count", "SME Review", "AI Fallback Gate", "VLM Enhancement Gate", "HF Deployment", "Automated Tests"],
+  "current_module": "Representative device validation",
+  "pending_modules": ["Install production OCR models", "Configure optional hosted AI endpoint", "Configure optional VLM endpoint", "Persistent production database"],
+  "open_issues": ["Local JSON storage is single-instance and ephemeral on default free Spaces", "PaddleOCR model download adds cold-start time", "Remote AI and VLM adapters require provider-specific endpoint contracts"],
+  "last_completed_step": "Added scrollable document stage, three small draggable dots, full-page Info summary, faster multi-word selection, and removed right-panel selection history",
+  "next_recommended_step": "Run the remaining physical iPhone/Android acceptance checks, then execute GitHub CI and Hugging Face smoke tests after remotes are configured",
+  "last_updated": "2026-06-20T12:00:00Z"
+}

data/sme_approved_definitions.json

@@ -0,0 +1 @@
+{}

data/user_corrections.json

@@ -0,0 +1 @@
+{}

examples/sample_documents/README.md

@@ -0,0 +1,3 @@
+# Sample documents
+
+Place synthetic or properly anonymized manifests, bills of lading, airway bills, invoices, packing lists, delivery orders, and customs declarations here for manual testing. Do not commit real customer documents or personal data.

frontend/camera.js

@@ -0,0 +1,310 @@
+(() => {
+  const $ = (selector) => document.querySelector(selector);
+  let stream = null;
+  let processing = false;
+  let lastAutoScan = 0;
+  let previous = null;
+  let stableFrames = 0;
+  let currentDocumentText = "";
+
+  const sample = document.createElement("canvas");
+  const context = sample.getContext("2d", { willReadFrequently: true });
+  sample.width = 96;
+  sample.height = 72;
+
+  function setDetails(open) {
+    const shell = $("#scannerShell");
+    shell.classList.toggle("details-open", open);
+    shell.classList.toggle("details-closed", !open);
+    $("#scanDetails").setAttribute("aria-hidden", String(!open));
+    $("#detailsToggle").setAttribute("aria-expanded", String(open));
+  }
+
+  async function start() {
+    try {
+      stream = await navigator.mediaDevices.getUserMedia({
+        video: {
+          facingMode: { ideal: "environment" },
+          width: { ideal: 1280 },
+          height: { ideal: 720 },
+        },
+        audio: false,
+      });
+      $("#video").srcObject = stream;
+      await $("#video").play();
+      $("#video").hidden = false;
+      $("#documentScroller").hidden = true;
+      $("#viewport").appendChild($("#overlay"));
+      $("#documentInfo").hidden = true;
+      $("#emptyState").classList.add("hidden");
+      $("#viewport").classList.add("active");
+      $("#statusPill").classList.add("live");
+      $("#statusPill span").textContent = "Live · private preview";
+      $("#captureButton").disabled = false;
+      setStatus("Camera ready", "Position the document inside the frame and hold still. Capture starts automatically when the page is clear.");
+      requestAnimationFrame(monitor);
+    } catch (error) {
+      setStatus(
+        "Camera unavailable",
+        error.name === "NotAllowedError"
+          ? "Camera permission was denied. Allow access and try again."
+          : "Use HTTPS or localhost and make sure a camera is connected.",
+      );
+      setDetails(true);
+    }
+  }
+
+  function monitor() {
+    if (!stream) return;
+    const video = $("#video");
+    if (video.readyState >= 2) {
+      context.drawImage(video, 0, 0, sample.width, sample.height);
+      const data = context.getImageData(0, 0, sample.width, sample.height).data;
+      let brightness = 0;
+      let motion = 0;
+      let edges = 0;
+      const gray = new Uint8Array(sample.width * sample.height);
+
+      for (let source = 0, target = 0; source < data.length; source += 4, target += 1) {
+        gray[target] = data[source] * 0.299 + data[source + 1] * 0.587 + data[source + 2] * 0.114;
+        brightness += gray[target];
+        if (previous) motion += Math.abs(gray[target] - previous[target]);
+        if (target > sample.width) edges += Math.abs(gray[target] - gray[target - sample.width]);
+      }
+
+      brightness /= gray.length;
+      motion = previous ? motion / gray.length : 99;
+      edges /= gray.length;
+      previous = gray;
+
+      const lightOkay = brightness > 42 && brightness < 220;
+      const sharp = edges > 5.2;
+      const still = motion < 3.8;
+      stableFrames = lightOkay && sharp && still ? stableFrames + 1 : 0;
+
+      $("#qualityPill").textContent = !lightOkay
+        ? brightness < 42 ? "More light needed" : "Reduce glare"
+        : !sharp ? "Move closer / focus"
+        : !still ? "Hold steady"
+        : stableFrames < 12 ? "Almost stable…" : "Frame stable";
+
+      if (stableFrames >= 12 && !processing && Date.now() - lastAutoScan > 8000) {
+        lastAutoScan = Date.now();
+        analyze();
+      }
+    }
+    requestAnimationFrame(monitor);
+  }
+
+  async function analyze() {
+    if (processing || !stream) return;
+    const video = $("#video");
+    const canvas = $("#captureCanvas");
+    canvas.width = video.videoWidth;
+    canvas.height = video.videoHeight;
+    canvas.getContext("2d").drawImage(video, 0, 0);
+    await analyzeCanvas(canvas, "camera");
+  }
+
+  async function analyzeCanvas(canvas, source) {
+    if (processing) return;
+    processing = true;
+    stableFrames = 0;
+    setStatus("Finding document terms", source === "upload" ? "Reading the uploaded page securely." : "Reading one clear camera frame.");
+    showProgress("Recognizing text and matching business terminology…");
+    const payload = {
+      image_base64: canvas.toDataURL("image/jpeg", 0.86),
+      frame_width: canvas.width,
+      frame_height: canvas.height,
+      language_preference: $("#language").value,
+    };
+
+    try {
+      const response = await fetch("/analyze-frame", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+      const data = await response.json();
+      if (!response.ok) throw new Error(data.detail || "Scan failed");
+
+      if (!data.ocr_available) {
+        setStatus("Recognition unavailable", `${data.message}. Install the full requirements to enable document recognition.`);
+        toast("The interface is ready. OCR needs the PaddleOCR dependency.");
+      } else {
+        renderAnalysis(data, canvas.width, canvas.height);
+      }
+    } catch (error) {
+      setStatus("Couldn’t scan this page", error.message);
+    } finally {
+      processing = false;
+      setDetails(true);
+    }
+  }
+
+  async function handleUpload(event) {
+    const file = event.target.files?.[0];
+    event.target.value = "";
+    if (!file) return;
+    const extension = file.name.split(".").pop()?.toLowerCase();
+    const supported = ["jpg", "jpeg", "png", "webp", "pdf", "docx"];
+    if (!supported.includes(extension)) {
+      toast("Please choose JPG, PNG, WebP, PDF, or Word DOCX.");
+      return;
+    }
+    if (file.size > 15 * 1024 * 1024) {
+      toast("Choose a document smaller than 15 MB.");
+      return;
+    }
+    processing = true;
+    setStatus("Preparing document", "Creating a private preview and finding useful business terms.");
+    showProgress("Opening and reading the document…");
+    setDetails(true);
+    try {
+      const prepared = await prepareUpload(file);
+      const response = await fetch("/analyze-document", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          file_base64: prepared.base64,
+          filename: prepared.filename,
+          language_preference: $("#language").value,
+        }),
+      });
+      const data = await response.json();
+      if (!response.ok) throw new Error(data.detail || "Document analysis failed");
+      const preview = $("#uploadedPreview");
+      await loadPreview(preview, data.preview_base64);
+      $("#documentStage").appendChild($("#overlay"));
+      $("#documentScroller").hidden = false;
+      $("#documentScroller").scrollTo({ top: 0, left: 0, behavior: "instant" });
+      $("#video").hidden = true;
+      $("#emptyState").classList.add("hidden");
+      $("#viewport").classList.remove("active");
+      $("#statusPill").classList.add("live");
+      $("#statusPill span").textContent = "Uploaded · not stored";
+      $("#qualityPill").textContent = file.name;
+      $("#captureButton").disabled = true;
+      renderAnalysis(data, data.frame_width, data.frame_height);
+    } catch (error) {
+      setStatus("Couldn’t read this document", error.message);
+      toast(error.message);
+    } finally {
+      processing = false;
+      setDetails(true);
+    }
+  }
+
+  function renderAnalysis(data, frameWidth, frameHeight) {
+    const terms = data.detected_terms || [];
+    $("#resultTitle").textContent = terms.length ? "Document ready" : "No useful terms found";
+    $("#statusMessage").textContent = terms.length
+      ? "Tap a dot on the document to open its live definition. Drag a dot if it covers important text."
+      : data.unknown_terms?.length
+        ? "Text was found, but no glossary terms matched. Try a clearer document."
+          : "Try a sharper image or a page containing customs, freight, or shipping terminology.";
+    window.FalconOverlay.render(terms, frameWidth, frameHeight, data.ocr_items || []);
+    currentDocumentText = (data.ocr_items || []).map((item) => item.text || "").filter(Boolean).join(" ").slice(0, 5000);
+    $("#documentInfo").hidden = !currentDocumentText;
+    $("#selectionHint").hidden = !(data.ocr_items || []).length;
+    $("#vlmButton").disabled = !data.suggest_vlm;
+    $("#vlmButton").title = data.vlm_reasons?.join(", ") || "";
+  }
+
+  async function prepareUpload(file) {
+    if (!file.type.startsWith("image/")) {
+      return { base64: await readBase64(file), filename: file.name };
+    }
+    const objectUrl = URL.createObjectURL(file);
+    try {
+      const image = await loadImage(objectUrl);
+      const maxEdge = 1600;
+      const scale = Math.min(1, maxEdge / Math.max(image.naturalWidth, image.naturalHeight));
+      if (scale === 1 && file.size < 2.5 * 1024 * 1024) {
+        return { base64: await readBase64(file), filename: file.name };
+      }
+      const canvas = document.createElement("canvas");
+      canvas.width = Math.max(1, Math.round(image.naturalWidth * scale));
+      canvas.height = Math.max(1, Math.round(image.naturalHeight * scale));
+      canvas.getContext("2d").drawImage(image, 0, 0, canvas.width, canvas.height);
+      const blob = await new Promise((resolve) => canvas.toBlob(resolve, "image/jpeg", 0.84));
+      return { base64: await readBase64(blob), filename: "optimized-upload.jpg" };
+    } finally {
+      URL.revokeObjectURL(objectUrl);
+    }
+  }
+
+  function readBase64(file) {
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onload = () => resolve(String(reader.result).split(",", 2)[1]);
+      reader.onerror = () => reject(new Error("The document could not be read"));
+      reader.readAsDataURL(file);
+    });
+  }
+
+  function loadImage(source) {
+    return new Promise((resolve, reject) => {
+      const image = new Image();
+      image.onload = () => resolve(image);
+      image.onerror = () => reject(new Error("The image could not be prepared"));
+      image.src = source;
+    });
+  }
+
+  function showProgress(message) {
+    $("#termsList").innerHTML = `<div class="analysis-progress"><i aria-hidden="true"></i><span>${message}</span></div>`;
+  }
+
+  function loadPreview(element, source) {
+    return new Promise((resolve, reject) => {
+      element.onload = resolve;
+      element.onerror = () => reject(new Error("The document preview could not be rendered"));
+      element.src = source;
+    });
+  }
+
+  async function analyzeVlm() {
+    $("#vlmButton").disabled = true;
+    const data = await fetch("/analyze-document-vlm", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ user_requested: true }),
+    }).then((response) => response.json());
+    toast(data.message);
+    setTimeout(() => { $("#vlmButton").disabled = false; }, 1200);
+  }
+
+  function setStatus(title, message) {
+    $("#resultTitle").textContent = title;
+    $("#statusMessage").textContent = message;
+  }
+
+  function toast(message) {
+    const element = $("#toast");
+    element.textContent = message;
+    element.classList.add("show");
+    setTimeout(() => element.classList.remove("show"), 3500);
+  }
+
+  document.addEventListener("DOMContentLoaded", () => {
+    window.FalconOverlay.init();
+    window.FalconFeedback.init();
+    window.FalconInsights.init();
+    setDetails(false);
+    $("#startCamera").onclick = start;
+    $("#captureButton").onclick = analyze;
+    $("#vlmButton").onclick = analyzeVlm;
+    $("#detailsToggle").onclick = () => setDetails(!$("#scannerShell").classList.contains("details-open"));
+    $("#detailsClose").onclick = () => setDetails(false);
+    $("#uploadButton").onclick = () => $("#documentUpload").click();
+    $("#documentUpload").onchange = handleUpload;
+    $("#documentInfo").onclick = () => {
+      if (currentDocumentText) window.FalconInsights.explain(currentDocumentText);
+    };
+    $("#language").onchange = () => { document.documentElement.lang = $("#language").value; };
+    window.addEventListener("resize", () => window.FalconOverlay.clear());
+  });
+
+  window.addEventListener("beforeunload", () => stream?.getTracks().forEach((track) => track.stop()));
+})();

frontend/feedback.js

@@ -0,0 +1 @@
+window.FalconFeedback=(()=>{let current=null;const $=s=>document.querySelector(s);function init(){document.querySelectorAll('[data-close]').forEach(b=>b.onclick=()=>close(b.dataset.close));$('#thumbUp').onclick=()=>submit('thumbs_up');$('#thumbDown').onclick=()=>{$('#correctionForm').hidden=false;$('#correctionText').focus()};$('#correctionForm').onsubmit=e=>{e.preventDefault();submit('thumbs_down',$('#correctionText').value)};$('#adminButton').onclick=openAdmin;loadCount()}function open(item){current=item;const lang=$('#language').value;const arabic=lang==='ar'&&item.definition_ar;$('#definitionModal').classList.add('open');$('#definitionModal').setAttribute('aria-hidden','false');$('.definition-card').dir=arabic?'rtl':'ltr';$('#definitionCategory').textContent=item.category||'CUSTOMS TERM';$('#definitionTerm').textContent=item.term;$('#definitionFullForm').textContent=item.full_form||'';$('#definitionText').textContent=arabic?item.definition_ar:item.definition;$('#definitionSource').textContent=item.source_label;$('#definitionConfidence').textContent=`${Math.round(item.confidence*100)}% confidence`;$('#relatedTerms').textContent=item.related_terms?.length?`Related: ${item.related_terms.join(' · ')}`:'';$('#correctionForm').hidden=true;$('#correctionText').value='';$('#feedbackMessage').textContent=''}function close(id){$('#'+id).classList.remove('open');$('#'+id).setAttribute('aria-hidden','true')}async function submit(type,correction=null){if(!current)return;const response=await fetch('/submit-feedback',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({term:current.term,old_definition:current.definition,corrected_definition:correction,feedback_type:type})});const data=await response.json();$('#feedbackMessage').textContent=response.ok?data.message:(data.detail||'Could not save feedback');if(response.ok&&correction){current.definition=correction;current.source='user_corrected';current.source_label='User correction (pending SME review)';loadCount();setTimeout(()=>close('definitionModal'),1000)}}async function loadCount(){const badge=$('#reviewCount'),button=$('#adminButton');try{const data=await fetch('/admin/corrections').then(r=>{if(!r.ok)throw new Error('Review queue unavailable');return r.json()});const count=Array.isArray(data.items)?data.items.length:0;badge.textContent=String(count);badge.hidden=count===0;button.setAttribute('aria-label',count?`Open SME review queue, ${count} pending ${count===1?'correction':'corrections'}`:'Open SME review queue')}catch{badge.hidden=true;button.setAttribute('aria-label','Open SME review queue; count unavailable')}}async function openAdmin(){$('#adminModal').classList.add('open');const list=$('#adminList');list.innerHTML='<p class="muted">Loading…</p>';const data=await fetch('/admin/corrections').then(r=>r.json());list.innerHTML=data.items.length?data.items.map(item=>`<article class="admin-item"><h3>${escapeHtml(item.term)}</h3><p class="muted">Current: ${escapeHtml(item.old_definition||item.previous_definition||'—')}</p><p><strong>Suggestion:</strong> ${escapeHtml(item.corrected_definition)}</p><small>Suggested by ${escapeHtml(item.suggested_by)} · ${new Date(item.created_at).toLocaleString()}</small><div class="admin-actions"><button class="approve" data-review="approve" data-term="${escapeHtml(item.term)}">Approve</button><button class="reject" data-review="reject" data-term="${escapeHtml(item.term)}">Reject</button></div></article>`).join(''):'<p class="muted">No corrections are waiting for review.</p>';list.querySelectorAll('[data-review]').forEach(b=>b.onclick=()=>review(b.dataset.term,b.dataset.review))}async function review(term,action){await fetch('/admin/review',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({term,action,reviewer:'FalconScan SME'})});openAdmin();loadCount()}function escapeHtml(s){return String(s||'').replace(/[&<>'"]/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;',"'":'&#39;','"':'&quot;'}[c]))}return{init,open}})();

frontend/index.html

@@ -0,0 +1,74 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+  <meta name="theme-color" content="#071a18">
+  <title>FalconScan — Customs terms, made clear</title>
+  <link rel="stylesheet" href="/static/styles.css">
+</head>
+<body>
+  <header>
+    <a class="brand" href="#"><span class="mark">F</span><span>FalconScan<small>Customs intelligence</small></span></a>
+    <div class="header-actions">
+      <select id="language" aria-label="Definition language"><option value="en">English</option><option value="ar">العربية</option></select>
+      <button class="ghost" id="adminButton" aria-label="Open SME review queue">SME review <span id="reviewCount" class="count" hidden>0</span></button>
+    </div>
+  </header>
+
+  <main>
+    <section class="intro">
+      <div><p class="eyebrow">LIVE DOCUMENT ASSISTANT</p><h1>Point. Pause. Understand.</h1>
+        <p>FalconScan finds customs and freight terminology on physical documents, then explains it without taking you away from the camera.</p></div>
+    </section>
+
+    <aside class="trust-note" aria-label="Privacy note">
+      <span class="trust-icon" aria-hidden="true">✓</span>
+      <div><strong>Private by design</strong><p>Document frames are analyzed only to identify terminology. FalconScan does not store the captured image.</p></div>
+      <span class="trust-label">ON-DEVICE FIRST</span>
+    </aside>
+
+    <section id="scannerShell" class="scanner-shell details-closed">
+      <div id="viewport" class="viewport">
+        <video id="video" autoplay muted playsinline></video>
+        <div id="documentScroller" class="document-scroller" hidden>
+          <div id="documentStage" class="document-stage">
+            <img id="uploadedPreview" class="uploaded-preview" alt="Uploaded customs document preview">
+          </div>
+        </div>
+        <canvas id="captureCanvas" hidden></canvas>
+        <div id="overlay" class="overlay"></div>
+        <div class="corner tl"></div><div class="corner tr"></div><div class="corner bl"></div><div class="corner br"></div>
+        <div id="emptyState" class="empty-state"><div class="lens">◎</div><strong>Camera is ready when you are</strong><span>Position a customs document inside the frame</span><button id="startCamera" class="primary">Start camera</button></div>
+        <div id="scanLine" class="scan-line"></div>
+        <div id="statusPill" class="status-pill"><i></i><span>Camera off</span></div>
+        <div id="qualityPill" class="quality-pill">Waiting for camera</div>
+        <div id="selectionHint" class="selection-hint" hidden>Select or highlight document text for a live business insight</div>
+        <button id="documentInfo" class="document-info" type="button" aria-label="Summarize this document" hidden><span aria-hidden="true">i</span><b>Document info</b></button>
+        <button id="detailsToggle" class="details-toggle" aria-expanded="false" aria-controls="scanDetails"><span>Scan details</span><i aria-hidden="true">⌃</i></button>
+      </div>
+      <aside id="scanDetails" class="control-panel" aria-hidden="true">
+        <button id="detailsClose" class="details-close" aria-label="Close scan details">×</button>
+        <div class="panel-heading"><div><p class="eyebrow">SCAN STATUS</p><h2 id="resultTitle">Ready when you are</h2></div></div>
+        <div id="statusMessage" class="status-message">Use the camera or upload a document. Hold camera documents steady for automatic capture.</div>
+        <div id="termsList" class="terms-list"><div class="instruction-card"><strong>How it works</strong><p>Scan or upload, then tap any dot on the document for a clear business explanation.</p></div></div>
+        <div class="upload-card">
+          <div><strong>Have a digital document?</strong><span>Upload JPG, PNG, WebP, PDF, or Word DOCX.</span></div>
+          <button id="uploadButton" type="button">Upload document</button>
+          <input id="documentUpload" type="file" accept="image/jpeg,image/png,image/webp,application/pdf,application/vnd.openxmlformats-officedocument.wordprocessingml.document,.docx" hidden>
+        </div>
+        <div class="panel-actions"><button id="captureButton" disabled>Scan now</button><button id="vlmButton" class="secondary" disabled>Analyze full document</button></div>
+      </aside>
+    </section>
+
+    <section class="trust-row"><div><b>EN + AR</b><span>Bilingual OCR</span></div><div><b>LOCAL FIRST</b><span>Glossary lookup</span></div><div><b>HUMAN LED</b><span>SME-approved knowledge</span></div><div><b>CPU READY</b><span>Built for free Spaces</span></div></section>
+  </main>
+
+  <div id="definitionModal" class="modal" aria-hidden="true"><div class="definition-card" role="dialog" aria-modal="true"><button class="close" data-close="definitionModal">×</button><p class="eyebrow" id="definitionCategory">CUSTOMS TERM</p><h2 id="definitionTerm"></h2><p id="definitionFullForm" class="full-form"></p><p id="definitionText" class="definition-text"></p><div class="definition-meta"><span id="definitionSource"></span><span id="definitionConfidence"></span></div><div class="related" id="relatedTerms"></div><div class="feedback-row"><span>Was this useful?</span><button id="thumbUp" aria-label="Helpful">↑</button><button id="thumbDown" aria-label="Incorrect">↓</button></div><form id="correctionForm" hidden><label>Suggest a clearer, correct definition<textarea id="correctionText" required maxlength="2000"></textarea></label><button class="primary" type="submit">Save for review</button></form><p id="feedbackMessage" class="feedback-message"></p></div></div>
+
+  <div id="adminModal" class="modal" aria-hidden="true"><div class="admin-card" role="dialog" aria-modal="true"><button class="close" data-close="adminModal">×</button><p class="eyebrow">KNOWLEDGE GOVERNANCE</p><h2>SME correction review</h2><p class="muted">Approve suggestions to make them the official definition.</p><div id="adminList" class="admin-list"></div></div></div>
+  <div id="insightModal" class="modal" aria-hidden="true"><div class="insight-card" role="dialog" aria-modal="true" aria-labelledby="insightTitle"><button id="insightClose" class="close" aria-label="Close insight">×</button><p class="eyebrow">LIVE DOCUMENT INSIGHT</p><h2 id="insightTitle">Selection insight</h2><blockquote id="insightSelection"></blockquote><section><small>SUMMARY</small><p id="insightSummary"></p></section><section><small>BUSINESS MEANING</small><p id="insightBusiness"></p></section><div id="insightTerms" class="insight-terms"></div><div class="definition-meta"><span id="insightSource"></span><span id="insightConfidence"></span></div></div></div>
+  <div id="toast" class="toast"></div>
+  <script src="/static/insights.js"></script><script src="/static/overlay.js"></script><script src="/static/feedback.js"></script><script src="/static/camera.js"></script>
+</body>
+</html>

frontend/insights.js

@@ -0,0 +1,67 @@
+window.FalconInsights = (() => {
+  const $ = (selector) => document.querySelector(selector);
+  let pending = false;
+
+  function init() {
+    $("#insightClose").onclick = close;
+    $("#insightModal").addEventListener("click", (event) => {
+      if (event.target === $("#insightModal")) close();
+    });
+  }
+
+  async function explain(text) {
+    const selected = String(text || "").trim();
+    if (!selected || pending) return;
+    pending = true;
+    openLoading(selected);
+    try {
+      const response = await fetch("/explain-selection", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text: selected, language_preference: $("#language").value }),
+      });
+      const data = await response.json();
+      if (!response.ok) throw new Error(data.detail || "Insight unavailable");
+      $("#insightSummary").textContent = data.summary;
+      $("#insightBusiness").textContent = data.business_meaning;
+      $("#insightSource").textContent = data.source_label;
+      $("#insightConfidence").textContent = `${Math.round(data.confidence * 100)}% confidence`;
+      $("#insightTerms").innerHTML = (data.recognized_terms || []).map((item) => `<button type="button" data-term="${escapeHtml(item.term)}">${escapeHtml(item.term)}</button>`).join("");
+      $("#insightTerms").querySelectorAll("button").forEach((button) => {
+        button.onclick = () => {
+          const item = data.recognized_terms.find((term) => term.term === button.dataset.term);
+          if (item) window.FalconFeedback.open(item);
+        };
+      });
+    } catch (error) {
+      $("#insightSummary").textContent = error.message;
+      $("#insightBusiness").textContent = "Try selecting a shorter phrase or a clearly recognized paragraph.";
+    } finally {
+      pending = false;
+    }
+  }
+
+  function openLoading(text) {
+    $("#insightSelection").textContent = text;
+    $("#insightSummary").textContent = "Understanding your selection…";
+    $("#insightBusiness").textContent = "Finding the relevant trade and clearance context.";
+    $("#insightTerms").innerHTML = "";
+    $("#insightSource").textContent = "Analyzing";
+    $("#insightConfidence").textContent = "";
+    $("#insightModal").classList.add("open");
+    $("#insightModal").setAttribute("aria-hidden", "false");
+  }
+
+  function close() {
+    $("#insightModal").classList.remove("open");
+    $("#insightModal").setAttribute("aria-hidden", "true");
+  }
+
+  function escapeHtml(value) {
+    return String(value).replace(/[&<>'"]/g, (character) => ({
+      "&": "&amp;", "<": "&lt;", ">": "&gt;", "'": "&#39;", '"': "&quot;",
+    })[character]);
+  }
+
+  return { init, explain };
+})();

frontend/overlay.js

@@ -0,0 +1,202 @@
+window.FalconOverlay = (() => {
+  let terms = [];
+  let viewport;
+  let overlay;
+  let video;
+  let uploadedPreview;
+  let documentScroller;
+  let activePopover = null;
+
+  function init() {
+    viewport = document.querySelector("#viewport");
+    overlay = document.querySelector("#overlay");
+    video = document.querySelector("#video");
+    uploadedPreview = document.querySelector("#uploadedPreview");
+    documentScroller = document.querySelector("#documentScroller");
+    document.addEventListener("pointerdown", (event) => {
+      if (activePopover && !activePopover.contains(event.target) && !event.target.closest(".term-marker")) closePopover();
+    });
+  }
+
+  function geometry(frameWidth, frameHeight) {
+    const documentMode = documentScroller && !documentScroller.hidden;
+    const media = documentMode ? uploadedPreview : video;
+    const mediaRect = media.getBoundingClientRect();
+    const viewRect = documentMode ? overlay.getBoundingClientRect() : viewport.getBoundingClientRect();
+    const scale = Math.min(mediaRect.width / frameWidth, mediaRect.height / frameHeight);
+    const drawnWidth = frameWidth * scale;
+    const drawnHeight = frameHeight * scale;
+    return {
+      viewRect,
+      scale,
+      offsetX: documentMode ? 0 : (viewRect.width - drawnWidth) / 2,
+      offsetY: documentMode ? 0 : (viewRect.height - drawnHeight) / 2,
+    };
+  }
+
+  function render(items, frameWidth, frameHeight, textRegions = []) {
+    terms = items;
+    overlay.innerHTML = "";
+    activePopover = null;
+    const layout = geometry(frameWidth, frameHeight);
+    renderSelectionLayer(textRegions, layout);
+    renderMarkers(items, layout);
+    renderList(items);
+  }
+
+  function renderMarkers(items, layout) {
+    if (!items.length) return;
+    const visible = [...items].sort((a, b) => b.confidence - a.confidence).slice(0, 3);
+    const occupied = [];
+
+    visible.forEach((item, index) => {
+      const [x1, y1, x2, y2] = item.bbox;
+      let left = layout.offsetX + x2 * layout.scale + 7;
+      let top = layout.offsetY + ((y1 + y2) / 2) * layout.scale - 12;
+      if (left > layout.viewRect.width - 34) left = layout.offsetX + x1 * layout.scale - 31;
+      left = clamp(left, 7, layout.viewRect.width - 31);
+      top = clamp(top, 46, layout.viewRect.height - 38);
+      let attempts = 0;
+      while (occupied.some((point) => Math.hypot(point.left - left, point.top - top) < 31) && attempts < 12) {
+        top = clamp(top + 32, 46, layout.viewRect.height - 38);
+        if (top >= layout.viewRect.height - 39) left = clamp(left - 34, 7, layout.viewRect.width - 31);
+        attempts += 1;
+      }
+      occupied.push({ left, top });
+
+      const marker = document.createElement("button");
+      marker.className = "term-marker";
+      marker.type = "button";
+      marker.style.left = `${left}px`;
+      marker.style.top = `${top}px`;
+      marker.style.setProperty("--marker-delay", `${Math.min(index * 35, 350)}ms`);
+      marker.setAttribute("aria-label", `Explain ${item.term}`);
+      marker.innerHTML = `<span></span>`;
+      let dragged = false;
+      enableDrag(marker, layout, () => { dragged = true; });
+      marker.onclick = (event) => {
+        event.stopPropagation();
+        if (dragged) {
+          dragged = false;
+          return;
+        }
+        openPopover(item, marker, layout);
+      };
+      overlay.appendChild(marker);
+    });
+  }
+
+  function enableDrag(marker, layout, onDrag) {
+    let start = null;
+    marker.addEventListener("pointerdown", (event) => {
+      start = {
+        x: event.clientX,
+        y: event.clientY,
+        left: parseFloat(marker.style.left),
+        top: parseFloat(marker.style.top),
+        moved: false,
+      };
+      marker.setPointerCapture?.(event.pointerId);
+    });
+    marker.addEventListener("pointermove", (event) => {
+      if (!start) return;
+      const dx = event.clientX - start.x;
+      const dy = event.clientY - start.y;
+      if (Math.hypot(dx, dy) > 3) {
+        start.moved = true;
+        onDrag();
+      }
+      marker.style.left = `${clamp(start.left + dx, 5, layout.viewRect.width - 23)}px`;
+      marker.style.top = `${clamp(start.top + dy, 5, layout.viewRect.height - 23)}px`;
+    });
+    const finish = () => { start = null; };
+    marker.addEventListener("pointerup", finish);
+    marker.addEventListener("pointercancel", finish);
+  }
+
+  function openPopover(item, marker, layout) {
+    closePopover();
+    marker.classList.add("active");
+    const popover = document.createElement("article");
+    popover.className = "term-popover";
+    const markerLeft = parseFloat(marker.style.left);
+    const markerTop = parseFloat(marker.style.top);
+    const width = Math.min(286, layout.viewRect.width - 24);
+    let left = markerLeft + 34;
+    if (left + width > layout.viewRect.width - 8) left = markerLeft - width - 8;
+    left = clamp(left, 8, layout.viewRect.width - width - 8);
+    const top = clamp(markerTop - 18, 50, layout.viewRect.height - 170);
+    popover.style.left = `${left}px`;
+    popover.style.top = `${top}px`;
+    popover.style.width = `${width}px`;
+    popover.innerHTML = `<div class="popover-heading"><span class="callout-dot"></span><span class="callout-line"></span><strong>${escapeHtml(item.term)}</strong><small>${Math.round(item.confidence * 100)}%</small></div><p>${escapeHtml(item.definition)}</p><button type="button">Open full meaning</button>`;
+    popover.querySelector("button").onclick = (event) => {
+      event.stopPropagation();
+      window.FalconFeedback.open(item);
+    };
+    popover.onclick = (event) => event.stopPropagation();
+    overlay.appendChild(popover);
+    activePopover = popover;
+  }
+
+  function closePopover() {
+    if (activePopover) activePopover.remove();
+    activePopover = null;
+    overlay?.querySelectorAll(".term-marker.active").forEach((marker) => marker.classList.remove("active"));
+  }
+
+  function renderSelectionLayer(regions, layout) {
+    if (!regions.length) return;
+    const layer = document.createElement("div");
+    layer.className = "selection-layer";
+    regions.slice(0, 80).forEach((region) => {
+      if (!region.text || !region.bbox) return;
+      const [x1, y1, x2, y2] = region.bbox;
+      const span = document.createElement("span");
+      span.className = "selectable-region";
+      span.textContent = region.text;
+      span.style.left = `${layout.offsetX + x1 * layout.scale}px`;
+      span.style.top = `${layout.offsetY + y1 * layout.scale}px`;
+      span.style.width = `${Math.max(8, (x2 - x1) * layout.scale)}px`;
+      span.style.height = `${Math.max(12, (y2 - y1) * layout.scale)}px`;
+      span.style.fontSize = `${clamp((y2 - y1) * layout.scale * 0.72, 8, 24)}px`;
+      layer.appendChild(span);
+    });
+    const explainSelection = () => {
+      requestAnimationFrame(() => {
+        const selection = window.getSelection();
+        if (!selection || selection.isCollapsed || !layer.contains(selection.anchorNode)) return;
+        const text = selection.toString().trim();
+        if (text) window.FalconInsights.explain(text);
+      });
+    };
+    layer.addEventListener("mouseup", explainSelection);
+    layer.addEventListener("touchend", explainSelection);
+    overlay.appendChild(layer);
+  }
+
+  function renderList(items) {
+    const list = document.querySelector("#termsList");
+    list.innerHTML = items.length
+      ? '<div class="instruction-card"><strong>Insights are on the document</strong><p>Tap a dot for meaning, drag it to reveal text, or select multiple words for business context.</p></div>'
+      : '<div class="empty-result">No readable text was detected. Try a sharper image or another page.</div>';
+  }
+
+  function clear() {
+    terms = [];
+    activePopover = null;
+    if (overlay) overlay.innerHTML = "";
+  }
+
+  function clamp(value, minimum, maximum) {
+    return Math.min(Math.max(value, minimum), Math.max(minimum, maximum));
+  }
+
+  function escapeHtml(value) {
+    return String(value).replace(/[&<>'"]/g, (character) => ({
+      "&": "&amp;", "<": "&lt;", ">": "&gt;", "'": "&#39;", '"': "&quot;",
+    })[character]);
+  }
+
+  return { init, render, clear };
+})();

frontend/styles.css

@@ -0,0 +1,228 @@
+:root {
+  --ink: #14201d;
+  --muted: #64706c;
+  --paper: #f5f5f2;
+  --white: #fff;
+  --green: #087a5b;
+  --lime: #c9f257;
+  --line: #dfe3df;
+  --dark: #081c18;
+  --glass: rgba(255, 255, 255, .78);
+  --shadow: 0 22px 70px rgba(20, 38, 33, .12);
+  --safe-bottom: env(safe-area-inset-bottom, 0px);
+}
+
+* { box-sizing: border-box; }
+html { scroll-behavior: smooth; }
+body { margin: 0; min-width: 320px; background: radial-gradient(circle at 50% -10%, #fff 0, var(--paper) 48%); color: var(--ink); font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", Inter, ui-sans-serif, system-ui, sans-serif; -webkit-font-smoothing: antialiased; }
+button, select, textarea { font: inherit; }
+button { cursor: pointer; }
+
+/* Mobile is the base layout. Larger screens progressively enhance it. */
+header {
+  position: sticky; top: 0; z-index: 10;
+  min-height: 64px; padding: 10px 14px;
+  display: flex; align-items: center; justify-content: space-between; gap: 10px;
+  border-bottom: 1px solid rgba(20, 35, 31, .08); background: rgba(247, 247, 244, .82);
+  backdrop-filter: saturate(180%) blur(20px);
+}
+.brand { display: flex; align-items: center; gap: 9px; min-width: 0; text-decoration: none; color: var(--ink); font-weight: 800; font-size: 16px; }
+.brand small { display: none; font-size: 9px; letter-spacing: .18em; text-transform: uppercase; color: var(--muted); margin-top: 2px; }
+.mark { display: grid; place-items: center; flex: 0 0 auto; width: 36px; height: 36px; background: var(--dark); color: var(--lime); border-radius: 10px; font-family: Georgia, serif; font-style: italic; font-size: 24px; }
+.header-actions { display: flex; align-items: center; gap: 6px; }
+.header-actions select, .ghost { min-height: 38px; border: 1px solid rgba(20, 35, 31, .1); background: rgba(255,255,255,.64); border-radius: 11px; padding: 7px 9px; color: var(--ink); }
+.ghost { width: 42px; overflow: hidden; white-space: nowrap; font-size: 0; }
+.ghost::before { content: "SME"; font-size: 10px; font-weight: 800; }
+.count { display: inline-grid; place-items: center; min-width: 18px; height: 18px; margin-left: 2px; padding: 0 5px; background: var(--lime); border-radius: 99px; font-size: 10px; color: var(--dark); }
+.count[hidden] { display: none; }
+
+main { width: 100%; max-width: 1320px; margin: auto; padding: 30px 14px calc(64px + var(--safe-bottom)); }
+.intro { margin-bottom: 18px; }
+.intro h1 { max-width: 10ch; margin: 2px 0 12px; font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", Inter, sans-serif; font-weight: 680; font-size: clamp(39px, 12vw, 64px); line-height: .98; letter-spacing: -.055em; }
+.intro > div > p:last-child { max-width: 680px; margin: 0; color: var(--muted); line-height: 1.55; font-size: 14px; }
+.eyebrow { margin: 0 0 8px; color: var(--green); font-size: 10px; letter-spacing: .18em; font-weight: 800; }
+.trust-note { display: grid; grid-template-columns: 34px 1fr; gap: 11px; align-items: center; margin: 18px 0; padding: 13px 14px; border: 1px solid rgba(8,122,91,.12); background: rgba(232,247,240,.66); border-radius: 15px; }
+.trust-icon { display: grid; place-items: center; width: 34px; height: 34px; background: #d7f4e8; color: var(--green); border-radius: 50%; font-weight: 800; }
+.trust-note strong { display: block; font-size: 13px; }
+.trust-note p { margin: 2px 0 0; color: #53645f; font-size: 11px; line-height: 1.45; }
+.trust-label { display: none; color: var(--green); font-size: 9px; font-weight: 800; letter-spacing: .13em; }
+
+.scanner-shell { display: flex; flex-direction: column; min-height: 0; overflow: hidden; background: var(--white); border: 1px solid rgba(20,35,31,.06); border-radius: 20px; box-shadow: var(--shadow); transition: grid-template-columns .42s cubic-bezier(.22,1,.36,1); }
+.viewport { position: relative; min-height: min(62svh, 560px); background: radial-gradient(circle at center, #23423a, #071a18 72%); overflow: hidden; }
+.viewport video { position: absolute; width: 100%; height: 100%; object-fit: contain; }
+.document-scroller { position: absolute; inset: 0; z-index: 1; overflow: auto; overscroll-behavior: contain; scrollbar-gutter: stable; scrollbar-color: #71827c #162a25; scrollbar-width: auto; background: #152622; }
+.document-scroller[hidden] { display: none; }
+.document-scroller::-webkit-scrollbar { width: 11px; height: 11px; }
+.document-scroller::-webkit-scrollbar-track { background: #162a25; }
+.document-scroller::-webkit-scrollbar-thumb { border: 3px solid #162a25; background: #71827c; border-radius: 99px; }
+.document-stage { position: relative; width: 100%; min-height: 100%; background: #fff; }
+.uploaded-preview { display: block; width: 100%; height: auto; min-height: 100%; object-fit: contain; object-position: top center; background: #fff; }
+.document-stage > .overlay { position: absolute; inset: 0; width: 100%; height: 100%; }
+.overlay { position: absolute; inset: 0; pointer-events: none; }
+.term-marker { position: absolute; z-index: 4; display: grid; place-items: center; width: 18px; height: 18px; border: 1.5px solid rgba(255,255,255,.9); padding: 0; background: rgba(8,28,24,.9); border-radius: 50%; box-shadow: 0 4px 12px rgba(0,0,0,.26); pointer-events: auto; cursor: grab; touch-action: none; animation: marker-in .35s var(--marker-delay, 0ms) both cubic-bezier(.22,1,.36,1); }
+.term-marker:active { cursor: grabbing; }
+.term-marker span { width: 6px; height: 6px; background: var(--lime); border-radius: 50%; box-shadow: 0 0 0 3px rgba(201,242,87,.16); }
+.term-marker:hover, .term-marker:focus-visible, .term-marker.active { border-color: var(--lime); transform: scale(1.1); }
+@keyframes marker-in { from { opacity: 0; transform: scale(.4); } }
+.term-popover { position: absolute; z-index: 6; border: 1px solid rgba(255,255,255,.16); padding: 13px; background: rgba(8,28,24,.94); color: white; border-radius: 14px; box-shadow: 0 18px 48px rgba(0,0,0,.38); backdrop-filter: saturate(160%) blur(18px); pointer-events: auto; animation: popover-in .22s cubic-bezier(.22,1,.36,1); }
+@keyframes popover-in { from { opacity: 0; transform: translateY(7px) scale(.97); } }
+.popover-heading { display: grid; grid-template-columns: 9px 1px minmax(0,1fr) auto; align-items: center; gap: 8px; }
+.callout-dot { width: 9px; height: 9px; background: var(--lime); border-radius: 50%; box-shadow: 0 0 0 3px rgba(201,242,87,.16); }
+.callout-line { align-self: stretch; width: 1px; min-height: 20px; background: rgba(255,255,255,.22); }
+.popover-heading strong { overflow: hidden; font-size: 12px; text-overflow: ellipsis; white-space: nowrap; }
+.popover-heading small { color: #c4cfcb; font-size: 9px; font-variant-numeric: tabular-nums; }
+.term-popover p { margin: 11px 0; color: #d8e1de; font-size: 11px; line-height: 1.5; }
+.term-popover button { width: 100%; min-height: 36px; border: 0; background: var(--lime); color: var(--dark); border-radius: 8px; font-size: 10px; font-weight: 750; }
+.selection-hint { position: absolute; z-index: 3; left: 50%; bottom: 66px; transform: translateX(-50%); max-width: calc(100% - 32px); padding: 7px 10px; background: rgba(255,255,255,.88); color: var(--dark); border-radius: 99px; backdrop-filter: blur(12px); font-size: 9px; font-weight: 650; text-align: center; white-space: nowrap; }
+.selection-hint[hidden] { display: none; }
+.document-info { position: absolute; z-index: 5; left: 14px; bottom: 14px; display: flex; align-items: center; gap: 7px; min-height: 40px; border: 1px solid #ffffff24; padding: 7px 11px 7px 7px; background: rgba(8,28,24,.82); color: white; border-radius: 99px; backdrop-filter: blur(16px); pointer-events: auto; }
+.document-info[hidden] { display: none; }
+.document-info span { display: grid; place-items: center; width: 25px; height: 25px; background: var(--lime); color: var(--dark); border-radius: 50%; font-family: Georgia, serif; font-weight: 800; }
+.document-info b { display: none; font-size: 10px; }
+.selection-layer { position: absolute; inset: 0; z-index: 2; pointer-events: none; }
+.selectable-region { position: absolute; display: block; overflow: hidden; color: transparent; line-height: 1; white-space: pre-wrap; user-select: text; -webkit-user-select: text; pointer-events: auto; cursor: text; }
+.selectable-region::selection { background: rgba(201,242,87,.72); color: rgba(8,28,24,.9); }
+@keyframes pop { from { scale: .2; opacity: 0; } }
+.corner { position: absolute; width: 34px; height: 34px; border-color: var(--lime); border-style: solid; opacity: .8; }
+.tl { top: 28px; left: 20px; border-width: 2px 0 0 2px; }
+.tr { top: 28px; right: 20px; border-width: 2px 2px 0 0; }
+.bl { bottom: 28px; left: 20px; border-width: 0 0 2px 2px; }
+.br { right: 20px; bottom: 28px; border-width: 0 2px 2px 0; }
+.empty-state { position: absolute; inset: 0; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 8px; padding: 24px; color: white; text-align: center; background: linear-gradient(130deg, #102c27dd, #071a18ee); }
+.empty-state.hidden { display: none; }
+.empty-state span { max-width: 250px; color: #a8b7b2; font-size: 14px; }
+.lens { margin-bottom: 8px; color: var(--lime); font-size: 50px; }
+.primary, .panel-actions button { min-height: 48px; border: 0; border-radius: 12px; padding: 12px 18px; background: var(--lime); color: var(--dark); font-weight: 720; box-shadow: 0 8px 20px #8aaa3030; transition: transform .18s ease, filter .18s ease; }
+.primary:hover, .panel-actions button:hover:not(:disabled) { filter: brightness(1.025); transform: translateY(-1px); }
+.empty-state .primary { margin-top: 14px; }
+.scan-line { display: none; position: absolute; left: 7%; right: 7%; top: 50%; height: 1px; background: var(--lime); box-shadow: 0 0 20px var(--lime); animation: scan 2.4s ease-in-out infinite; }
+.viewport.active .scan-line { display: block; }
+@keyframes scan { 0%, 100% { top: 12%; opacity: .1; } 50% { top: 88%; opacity: .9; } }
+.status-pill, .quality-pill { position: absolute; top: 14px; max-width: 46%; overflow: hidden; border: 1px solid #ffffff22; background: #071a18bb; color: #fff; backdrop-filter: blur(10px); border-radius: 99px; padding: 7px 10px; font-size: 10px; text-overflow: ellipsis; white-space: nowrap; }
+.status-pill { left: 12px; }
+.quality-pill { right: 12px; }
+.status-pill i { display: inline-block; width: 7px; height: 7px; margin-right: 5px; background: #80908b; border-radius: 50%; }
+.status-pill.live i { background: var(--lime); box-shadow: 0 0 8px var(--lime); }
+
+.details-toggle { position: absolute; z-index: 3; left: 50%; bottom: 14px; transform: translateX(-50%); display: flex; align-items: center; gap: 8px; min-height: 42px; border: 1px solid #ffffff24; padding: 8px 11px 8px 14px; background: rgba(8,28,24,.76); color: white; border-radius: 99px; backdrop-filter: saturate(160%) blur(16px); box-shadow: 0 8px 30px #0003; font-size: 11px; font-weight: 650; }
+.details-toggle i { font-style: normal; transition: transform .3s ease; }
+.details-open .details-toggle i { transform: rotate(180deg); }
+
+.control-panel { position: relative; display: flex; flex-direction: column; max-height: 0; overflow: hidden; padding: 0 18px; opacity: 0; transform: translateY(18px); transition: max-height .45s cubic-bezier(.22,1,.36,1), opacity .25s ease, transform .4s cubic-bezier(.22,1,.36,1), padding .4s ease; }
+.details-open .control-panel { max-height: 740px; padding: 26px 18px calc(20px + var(--safe-bottom)); opacity: 1; transform: translateY(0); }
+.details-close { position: absolute; top: 15px; right: 14px; z-index: 2; display: grid; place-items: center; width: 32px; height: 32px; border: 0; background: #f0f2ef; color: var(--muted); border-radius: 50%; font-size: 21px; line-height: 1; }
+.panel-heading { display: flex; align-items: start; justify-content: space-between; gap: 12px; border-bottom: 1px solid var(--line); padding: 0 38px 14px 0; }
+.panel-heading h2 { margin: 0; font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", Inter, sans-serif; font-size: 24px; font-weight: 680; letter-spacing: -.035em; }
+.panel-heading > span { flex: 0 0 auto; padding: 6px 9px; background: #eef0e8; border-radius: 99px; font-size: 11px; }
+.status-message { padding: 14px 0; color: var(--muted); font-size: 13px; line-height: 1.55; }
+.metrics { display: grid; grid-template-columns: repeat(3, 1fr); gap: 7px; }
+.metrics > div { min-width: 0; background: #f3f4ef; padding: 10px 8px; border-radius: 9px; }
+.metrics small, .metrics strong { display: block; overflow: hidden; text-overflow: ellipsis; }
+.metrics small { color: var(--muted); font-size: 8px; text-transform: uppercase; letter-spacing: .08em; }
+.metrics strong { margin-top: 5px; font-size: 11px; white-space: nowrap; }
+.terms-list { max-height: 230px; overflow: auto; padding: 14px 0; }
+.hint-card { display: flex; gap: 12px; align-items: center; color: var(--muted); font-size: 13px; }
+.hint-card span { color: var(--green); font-family: Georgia, serif; font-size: 22px; }
+.instruction-card { padding: 13px 14px; background: #f3f5f1; border-radius: 12px; }
+.instruction-card strong { font-size: 12px; }
+.instruction-card p { margin: 5px 0 0; color: var(--muted); font-size: 11px; line-height: 1.5; }
+.analysis-progress { display: flex; align-items: center; gap: 10px; padding: 14px; background: #f3f5f1; border-radius: 12px; color: var(--muted); font-size: 11px; }
+.analysis-progress i { width: 16px; height: 16px; border: 2px solid #d9dfdb; border-top-color: var(--green); border-radius: 50%; animation: progress-spin .8s linear infinite; }
+@keyframes progress-spin { to { transform: rotate(360deg); } }
+.empty-result { padding: 14px; border: 1px dashed #d5dbd7; color: var(--muted); border-radius: 12px; font-size: 11px; line-height: 1.5; }
+.upload-card { display: grid; gap: 10px; margin: 4px 0 14px; padding: 13px; border: 1px solid var(--line); background: #f6f7f4; border-radius: 12px; }
+.upload-card strong, .upload-card span { display: block; }
+.upload-card strong { font-size: 12px; }
+.upload-card span { margin-top: 3px; color: var(--muted); font-size: 10px; line-height: 1.4; }
+.upload-card button { min-height: 40px; border: 1px solid #ced5d1; background: white; color: var(--ink); border-radius: 9px; font-size: 11px; font-weight: 700; }
+.upload-card button:hover { border-color: var(--green); color: var(--green); }
+.panel-actions { display: grid; gap: 8px; }
+.panel-actions button:disabled { opacity: .4; cursor: not-allowed; }
+.panel-actions .secondary { background: var(--dark); color: white; }
+
+.trust-row { display: grid; grid-template-columns: 1fr 1fr; margin-top: 18px; overflow: hidden; border: 1px solid rgba(20,35,31,.08); background: var(--glass); border-radius: 16px; box-shadow: 0 12px 40px rgba(20,38,33,.05); }
+.trust-row div { display: flex; flex-direction: column; padding: 15px; border-right: 1px solid #d8d8cf; border-bottom: 1px solid #d8d8cf; }
+.trust-row div:nth-child(2n) { border-right: 0; }
+.trust-row div:nth-last-child(-n+2) { border-bottom: 0; }
+.trust-row b { color: var(--green); font-size: 9px; letter-spacing: .1em; }
+.trust-row span { margin-top: 4px; color: var(--muted); font-size: 11px; }
+
+.modal { position: fixed; inset: 0; z-index: 20; display: none; place-items: end center; padding: 12px 12px calc(12px + var(--safe-bottom)); background: #071a18aa; backdrop-filter: blur(5px); }
+.modal.open { display: grid; }
+.definition-card, .admin-card, .insight-card { position: relative; width: 100%; max-height: 88svh; overflow: auto; background: white; border-radius: 20px 20px 14px 14px; padding: 28px 20px; box-shadow: 0 30px 100px #0006; }
+.close { position: absolute; top: 10px; right: 14px; border: 0; background: transparent; color: var(--muted); font-size: 27px; }
+.definition-card h2, .admin-card h2, .insight-card h2 { margin: 0 0 2px; font-family: Georgia, serif; font-size: 32px; }
+.full-form { margin: 0; color: var(--green); font-weight: 700; }
+.definition-text { font-family: Georgia, serif; font-size: 20px; line-height: 1.45; }
+.definition-meta { display: grid; gap: 5px; padding: 10px; background: #f0f3ec; border-radius: 9px; font-size: 11px; }
+.related { padding: 12px 0; color: var(--muted); font-size: 11px; }
+.feedback-row { display: flex; align-items: center; gap: 7px; border-top: 1px solid var(--line); padding-top: 16px; }
+.feedback-row span { margin-right: auto; font-size: 12px; }
+.feedback-row button { width: 42px; height: 40px; border: 1px solid var(--line); border-radius: 8px; background: white; }
+textarea { width: 100%; min-height: 90px; margin: 7px 0 9px; padding: 10px; border: 1px solid var(--line); border-radius: 8px; }
+form label { font-size: 12px; font-weight: 700; }
+#correctionForm { margin-top: 15px; }
+.feedback-message { color: var(--green); font-size: 12px; }
+.insight-card blockquote { margin: 16px 0; padding: 12px 14px; background: #f2f4f0; color: var(--muted); border-left: 3px solid var(--lime); border-radius: 4px 10px 10px 4px; font-size: 12px; line-height: 1.45; }
+.insight-card section { padding: 13px 0; border-top: 1px solid var(--line); }
+.insight-card section small { color: var(--green); font-size: 9px; font-weight: 800; letter-spacing: .14em; }
+.insight-card section p { margin: 7px 0 0; color: var(--ink); font-size: 14px; line-height: 1.6; }
+.insight-terms { display: flex; flex-wrap: wrap; gap: 6px; margin: 5px 0 16px; }
+.insight-terms button { border: 1px solid #ced8d3; padding: 6px 9px; background: #f7faf7; color: var(--green); border-radius: 99px; font-size: 10px; font-weight: 700; }
+.admin-item { margin-top: 12px; padding: 16px; border: 1px solid var(--line); border-radius: 12px; }
+.admin-item h3 { margin: 0; }
+.admin-item p { font-size: 13px; }
+.admin-actions { display: flex; gap: 8px; margin-top: 12px; }
+.admin-actions button { min-height: 40px; border: 0; border-radius: 7px; padding: 8px 12px; }
+.approve { background: var(--lime); }
+.reject { background: #f1dddd; }
+.muted { color: var(--muted); }
+.toast { position: fixed; left: 14px; right: 14px; bottom: calc(16px + var(--safe-bottom)); z-index: 30; transform: translateY(20px); opacity: 0; background: var(--dark); color: white; padding: 11px 16px; border-radius: 9px; transition: .2s; text-align: center; }
+.toast.show { opacity: 1; transform: translateY(0); }
+[dir=rtl] .definition-card { text-align: right; }
+
+@media (min-width: 600px) {
+  header { min-height: 72px; padding: 10px 24px; }
+  .brand { font-size: 18px; }
+  .brand small { display: block; }
+  .ghost { width: auto; font-size: 12px; }
+  .ghost::before { content: none; }
+  main { padding: 36px 24px 72px; }
+  .viewport { min-height: 560px; }
+  .control-panel { padding: 26px; }
+  .panel-actions { grid-template-columns: 1fr 1fr; }
+  .modal { place-items: center; padding: 20px; }
+  .definition-card { width: min(500px, 100%); border-radius: 18px; padding: 30px; }
+  .admin-card { width: min(800px, 100%); border-radius: 18px; padding: 30px; }
+  .insight-card { width: min(600px, 100%); border-radius: 18px; padding: 30px; }
+  .definition-meta { display: flex; justify-content: space-between; }
+  .document-info b { display: block; }
+  .toast { left: 50%; right: auto; width: max-content; max-width: 90vw; transform: translate(-50%, 20px); }
+  .toast.show { transform: translate(-50%, 0); }
+}
+
+@media (min-width: 900px) {
+  header { position: static; height: 76px; padding-inline: max(24px, calc((100vw - 1320px) / 2)); }
+  .intro { display: flex; justify-content: space-between; align-items: end; margin-bottom: 26px; }
+  .intro h1 { max-width: none; }
+  .intro > div > p:last-child { font-size: 16px; }
+  .trust-note { grid-template-columns: 38px 1fr auto; padding: 14px 17px; }
+  .trust-label { display: block; }
+  .scanner-shell { display: grid; grid-template-columns: minmax(0, 1fr) 0; min-height: 590px; border-radius: 24px; }
+  .scanner-shell.details-open { grid-template-columns: minmax(0, 1.65fr) minmax(330px, .7fr); }
+  .viewport { min-height: 590px; }
+  .control-panel { max-height: none; min-width: 0; height: 590px; padding: 28px; opacity: 1; transform: translateX(24px); transition: opacity .22s ease, transform .42s cubic-bezier(.22,1,.36,1); }
+  .details-closed .control-panel { visibility: hidden; padding-inline: 0; opacity: 0; pointer-events: none; }
+  .details-open .control-panel { max-height: none; padding: 28px; opacity: 1; transform: translateX(0); }
+  .details-toggle { left: auto; right: 18px; bottom: 18px; transform: none; }
+  .details-open .details-toggle { right: 18px; }
+  .panel-actions { grid-template-columns: 1fr; }
+  .terms-list { flex: 1; max-height: 300px; }
+  .trust-row { grid-template-columns: repeat(4, 1fr); margin-top: 20px; }
+  .trust-row div, .trust-row div:nth-child(2n) { border-right: 1px solid #d8d8cf; border-bottom: 0; padding: 18px 24px; }
+  .trust-row div:last-child { border-right: 0; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { scroll-behavior: auto !important; animation-duration: .01ms !important; animation-iteration-count: 1 !important; transition-duration: .01ms !important; }
+}

pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+pythonpath = .
+testpaths = tests

requirements-dev.txt

@@ -0,0 +1,3 @@
+-r requirements-lite.txt
+pytest==8.4.0
+httpx==0.28.1

requirements-lite.txt

@@ -0,0 +1,8 @@
+fastapi==0.115.12
+uvicorn[standard]==0.34.3
+pydantic==2.11.7
+pillow==11.2.1
+numpy==1.26.4
+PyMuPDF==1.25.5
+opencv-python==4.10.0.84
+rapidocr-onnxruntime==1.4.4

requirements.txt

@@ -0,0 +1,11 @@
+fastapi==0.115.12
+uvicorn[standard]==0.34.3
+pydantic==2.11.7
+pillow==11.2.1
+numpy==1.26.4
+paddlepaddle==3.0.0
+paddleocr==2.10.0
+python-multipart==0.0.20
+PyMuPDF==1.25.5
+opencv-python==4.10.0.84
+rapidocr-onnxruntime==1.4.4

tests/test_services.py

@@ -0,0 +1,127 @@
+import json
+import base64
+import io
+import zipfile
+from pathlib import Path
+
+from fastapi.testclient import TestClient
+
+from app import app
+from backend.glossary_service import GlossaryService
+
+
+ROOT = Path(__file__).parents[1]
+client = TestClient(app)
+
+
+def test_health():
+    response = client.get("/health")
+    assert response.status_code == 200
+    assert response.json()["status"] == "ok"
+
+
+def test_definition_exact_and_arabic_alias():
+    response = client.get("/definition/MAWB")
+    assert response.status_code == 200
+    assert response.json()["source"] == "verified_glossary"
+    response = client.get("/definition/رمز النظام المنسق")
+    assert response.json()["term"] == "HS Code"
+
+
+def test_fuzzy_ocr_match():
+    service = GlossaryService(ROOT / "data/glossary.json", ROOT / "data/user_corrections.json", ROOT / "data/sme_approved_definitions.json")
+    match = service.find_match("Commercia1 Invoice")
+    assert match and match["canonical"] == "Commercial Invoice"
+
+
+def test_invalid_image_rejected():
+    response = client.post("/analyze-frame", json={"image_base64": "bad", "frame_width": 100, "frame_height": 100})
+    assert response.status_code == 400
+
+
+def test_vlm_disabled_is_graceful():
+    response = client.post("/analyze-document-vlm", json={"user_requested": True})
+    assert response.status_code == 200
+    assert response.json()["status"] in {"unavailable", "configured"}
+
+
+def test_feedback_and_sme_priority(tmp_path):
+    glossary_path = tmp_path / "glossary.json"
+    corrections_path = tmp_path / "corrections.json"
+    approved_path = tmp_path / "approved.json"
+    glossary_path.write_text(json.dumps({"MAWB": {"definition": "verified", "source": "verified_glossary"}}))
+    corrections_path.write_text(json.dumps({"MAWB": {"corrected_definition": "user", "status": "pending_sme_review"}}))
+    approved_path.write_text(json.dumps({"MAWB": {"definition": "approved"}}))
+    service = GlossaryService(glossary_path, corrections_path, approved_path)
+    result = service.definition("MAWB")
+    assert result["definition"] == "approved"
+    assert result["source"] == "sme_approved"
+
+
+def test_docx_upload_returns_clickable_term_data():
+    xml = '''<?xml version="1.0"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body><w:p><w:r><w:t>MAWB with Packing List</w:t></w:r></w:p></w:body></w:document>'''
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, "w") as archive:
+        archive.writestr("word/document.xml", xml)
+    response = client.post("/analyze-document", json={
+        "file_base64": base64.b64encode(buffer.getvalue()).decode(),
+        "filename": "air-cargo.docx",
+        "language_preference": "en",
+    })
+    assert response.status_code == 200
+    terms = response.json()["detected_terms"]
+    assert {item["term"] for item in terms} >= {"MAWB", "Packing List"}
+    assert all(item["bbox"] and item["definition"] for item in terms)
+
+
+def test_unsupported_legacy_word_is_clear():
+    response = client.post("/analyze-document", json={
+        "file_base64": base64.b64encode(b"legacy").decode(),
+        "filename": "legacy.doc",
+        "language_preference": "en",
+    })
+    assert response.status_code == 400
+    assert "DOCX" in response.json()["detail"]
+
+
+def test_selection_insight_has_summary_and_business_meaning():
+    response = client.post("/explain-selection", json={
+        "text": "Commercial Invoice with HS Code and Customs Duty",
+        "language_preference": "en",
+    })
+    assert response.status_code == 200
+    data = response.json()
+    assert data["summary"]
+    assert data["business_meaning"]
+    assert {item["term"] for item in data["recognized_terms"]} >= {
+        "Commercial Invoice", "HS Code", "Customs Duty"
+    }
+
+
+def test_unknown_selection_is_clearly_unverified():
+    response = client.post("/explain-selection", json={
+        "text": "Internal reference XYZ-998",
+        "language_preference": "en",
+    })
+    assert response.status_code == 200
+    assert response.json()["source"] == "ai_generated_unverified"
+
+
+def test_contextual_fallback_prevents_empty_dot_state():
+    service = GlossaryService(ROOT / "data/glossary.json", ROOT / "data/user_corrections.json", ROOT / "data/sme_approved_definitions.json")
+    terms = service.contextual_fallbacks([{
+        "text": "Port Reference ZX-2048", "bbox": [20, 30, 280, 60],
+        "confidence": 0.91, "language": "en",
+    }])
+    assert len(terms) == 1
+    assert terms[0]["bbox"] == [20, 30, 280, 60]
+    assert terms[0]["source"] == "ai_generated_unverified"
+
+
+def test_scanner_serves_scroll_info_and_clean_status_controls():
+    html = client.get("/").text
+    assert 'id="documentScroller"' in html
+    assert 'id="documentInfo"' in html
+    assert 'id="stabilityMetric"' not in html
+    assert 'id="lightMetric"' not in html
+    assert 'id="ocrMetric"' not in html