System Requirements Document for bitshield-3

1. Introduction

BITSHIELD (project name bitshield-3) is a Bitcoin Scam Risk Detector: a single-file, fully offline web application that lets a person paste a suspicious Bitcoin message or offer and receive a transparent, rule-based risk analysis. The product is deliberately not a simple scam/not-scam verdict. Instead it lays the message out like evidence on a desk and reports a Risk Score (0–100), a Risk Level (LOW / MEDIUM / HIGH / CRITICAL), the warning signs detected, the suspicious phrases highlighted inside the original message, beginner-friendly reasons, next steps, a scam stage tracker, a scam type classification, a mathematical reality check on return claims, and the rules that were checked but did not match.

The intended audience is ordinary people who have just received a suspicious Bitcoin message and need a calm, forensic, procedural reading of it, plus a student presenting this as a college cybersecurity project demo who needs a polished, working, offline artefact that visibly proves the analyzer's logic. The app must feel like a finished college cybersecurity project demo, not a mockup.

The product uses sample/test data only. It never handles real Bitcoin, keys, or payments, and it makes no external requests of any kind.

2. System Overview

BITSHIELD is delivered as one self-contained HTML file. All markup is HTML, all styling lives in a single <style> block, and all behaviour is vanilla JavaScript inside a single <script> block. There are no frameworks, libraries, backends, APIs, databases, wallets, blockchains, or external requests. The application works fully offline.

The current delivery is a single-page, single-document application whose working areas are presented as numbered, ruled sections of one filed document — a "Cybersecurity Evidence Desk". The user submits a message, the local rule engine scores it, and the results are rendered as evidence sheets, taped labels, a stamped verdict, and coded status rules.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. The entire product is first-party and self-contained. There is no server, no provider surface, and no external destination that owns any part of the analysis. The only outbound link in the product is the India Cyber Crime Portal (https://cybercrime.gov.in/), which is a reporting reference the user may choose to open in a new tab; it is not a dependency of the app and the app functions completely without it.

Access ownership. BITSHIELD has no accounts, no sign-in, no sessions, and no stored user identity. Every working area is anonymously reachable. There is no protected destination, because there is no durable actor-specific state that must be privately owned or resumed: the pasted message is analyzed in the browser and the results are shown immediately. localStorage use is optional and, if used at all, must be wrapped in try/catch and must not create an identity or an account.

Current vs. future boundary. Everything described in this document is current. There are no future-horizon features in the authoritative requirement thread. The product explicitly excludes real Bitcoin handling, key handling, payments, network calls, and any backend.

Safety boundary. The app is educational and pattern-based. It never claims to prove that a message is a scam or that a message is legitimate, and it never handles real Bitcoin or money.

2b. Source Content Inventory

The reference directive for the India Cyber Crime Portal is declared with uses: ["domain_context"] and authority: "supplemental", with the instruction to include it as a link in the "What to do now" checklist, opening in a new tab with rel="noopener noreferrer". Because this directive does not declare content_source, no Source Content Inventory is produced. The only fact carried into the product is the link itself and its required link behaviour, which is preserved in the Next Steps coverage and in the Functional Requirements.

2c. Page Content and Component Coverage

The following pages are the closed, ordered page contract for this generation. Each is represented exactly once.

Landing

• Information / state: The BITSHIELD wordmark in all-caps with wide tracking; the subtitle "Bitcoin Scam Risk Detector"; the three status labels OFFLINE DEMO, NO REAL CRYPTO, NO DATA SENT; the one-sentence description "Analyze suspicious Bitcoin messages using transparent warning patterns and understand why a message may be risky."; the simple CSS shield mark (a flat polygon with a notched bottom and a small red notch, no emoji); a full-width 1px hairline beneath the header.
• Primary actions: Scroll/continue into the evidence desk to begin analysis; open the pre-loaded Guaranteed Profit sample result that is already visible.
• Supporting actions: Read the status labels and the safety description.
• Domain entities: Application identity (BITSHIELD), status labels, safety statement.
• Component responsibilities: Header block (wordmark, subtitle, status chips, description), shield mark, hairline rule, and the immediately visible verdict artefact described below.
• States:
  • Loading: none — the page is static and renders immediately.
  • Empty: not applicable; the page always shows the header and the pre-loaded Guaranteed Profit verdict.
  • Success: the header, status labels, description, and the pre-loaded Guaranteed Profit evidence sheet with its stamped verdict are all visible without scrolling on desktop, and stacked directly beneath the header on mobile.
  • Error: none — no network or data dependency exists on this page.
  • Recovery: not applicable.

Analyzer

• Information / state: Section "Submit the Evidence"; label "Suspicious message or offer"; a large textarea with a maximum of 5000 characters; a live character counter rendered as "0 / 5000"; the five sample buttons (Fake Giveaway, Guaranteed Profit, Fake Support, Withdrawal Fee, Normal Question); friendly validation messaging for empty, whitespace-only, emoji, Unicode, non-English, long, and pasted input.
• Primary actions: CHECK MESSAGE (runs the analyzer on the current textarea contents); each of the five sample buttons (fills the textarea, updates the counter, and auto-analyzes).
• Supporting actions: CLEAR (empties the textarea and resets the counter); typing or pasting into the textarea (updates the counter live).
• Domain entities: Submitted message text, character count, sample scenario definitions.
• Component responsibilities: Textarea with associated label, live counter, CHECK MESSAGE button, CLEAR button, sample button group, validation message region.
• States:
  • Loading: none — analysis is synchronous and local.
  • Empty: the counter reads "0 / 5000"; pressing CHECK MESSAGE on empty or whitespace-only input produces a friendly message rather than an analysis.
  • Success: the textarea holds the message, the counter reflects the true character count, and analysis results are produced.
  • Error: any internal failure during analysis is caught and surfaced as a friendly message; raw errors are never shown.
  • Recovery: the user can edit the text, press CLEAR, or load a sample and analyze again.

Results

• Information / state: The prominent stamp-style risk level; the score rendered in the "86 / 100" form; a text progress bar; the "Why this score?" breakdown listing matched patterns, their weights, the urgency+payment bonus when applied, the formula, and the final score; the scam type card showing the strongest matched family and its "How it works" description plus the note that this is an educational classification and not a legal determination; the stage tracker HOOK > TRUST > PRESSURE > PAYMENT > EXIT with active stages derived from matched rules; the "Checked and Clear" list of rules that did not match, each with a check mark, and the note "No matched rule is not proof that a message is legitimate."
• Primary actions: Read the verdict and score; read the calculation; read the scam type; read the stage tracker; read the unmatched-rule list.
• Supporting actions: Follow a highlight from the Evidence page into the corresponding finding.
• Domain entities: Risk score, risk level, matched rule weights, bonus, formula, scam family, stage set, unmatched rule list.
• Component responsibilities: Stamp verdict block, score line, text progress bar, calculation list, scam type card, stage tracker, checked-and-clear list, aria-live result region.
• States:
  • Loading: none — results are computed synchronously.
  • Empty: before any analysis, the region shows the pre-loaded Guaranteed Profit result on first load.
  • Success: level, score, progress bar, calculation, scam type, stage tracker, and unmatched list are all populated and consistent with each other.
  • Error: a friendly message replaces the result region; no raw error text is displayed.
  • Recovery: the user returns to the Analyzer, edits or replaces the message, and re-runs the analysis.

Evidence

• Information / state: The original message rendered as a monospace evidence sheet, with every matched phrase wrapped in evidence-tape styling (a 1px deep-red box, 2px radius, a small red tick on the left edge, monospace phrase text). Each tape label carries the rule id and label (for example "R-03 GIVEAWAY") in a small all-caps label above the phrase.
• Primary actions: Click or keyboard-activate a highlighted phrase to scroll to and focus the matching finding card.
• Supporting actions: Select and read the message text; hover or focus a tape label to reveal its rule id label.
• Domain entities: Original message text, matched phrase spans, rule ids and labels.
• Component responsibilities: Evidence sheet container, safe text nodes, tape-wrapped phrase elements, focusable highlight controls.
• States:
  • Loading: none.
  • Empty: when no message has been analyzed, the sheet shows the pre-loaded Guaranteed Profit message.
  • Success: the message is displayed in full with matched phrases taped and focusable.
  • Error: if highlighting cannot be produced, the message is still displayed as plain safe text; no raw error is shown.
  • Recovery: the user can re-run analysis from the Analyzer to regenerate the sheet.

Findings

• Information / state: Section "Warning Signs Detected". Each matched rule appears as its own finding with severity, rule name, the matched evidence, a plain-language "why risky" explanation, and a plain-language "what to check" tip. Only matched rules appear here.
• Primary actions: Read each finding; arrive at a finding by activating its highlight in the Evidence sheet.
• Supporting actions: Move between findings with the keyboard; read the severity label alongside its word.
• Domain entities: Rule id, rule label, severity, matched evidence text, explanation, tip, family, stage.
• Component responsibilities: Finding card list, severity label, evidence excerpt, explanation block, tip block, focus target for highlight navigation.
• States:
  • Loading: none.
  • Empty: when no rules match, the section states that no warning signs were detected and directs the user to the Checked and Clear list.
  • Success: every matched rule has exactly one finding with all five required fields.
  • Error: a friendly message replaces the section; no raw error is shown.
  • Recovery: re-run analysis from the Analyzer.

Reality Check

• Information / state: Any detected "X% daily", "X% weekly", or "X% monthly" return claim, together with the compounded yearly return computed from it (for example (1.08^365 - 1) x 100), and the note: "This is a mathematical reality check, not proof that the sender's claim is true. Extremely large repeated returns are a reason to stop and independently verify the offer."
• Primary actions: Read the detected claim and the computed yearly figure.
• Supporting actions: Compare the computed figure against the claim in the message.
• Domain entities: Claimed percentage, claim period (daily/weekly/monthly), compounded yearly return.
• Component responsibilities: Claim display, computation display, limitation note.
• States:
  • Loading: none.
  • Empty: when no percentage-return claim is present, the section states that no repeated-return claim was found in this message.
  • Success: the detected claim and its compounded yearly figure are both shown with the limitation note.
  • Error: a friendly message replaces the section; no raw error is shown.
  • Recovery: re-run analysis from the Analyzer.

Next Steps

• Information / state: A dynamic checklist that adapts to the risk level. For high risk (HIGH or CRITICAL): do not send Bitcoin, do not pay upfront fees, verify independently, never share seed phrase / private key / passwords / OTP, no remote-access software, do not click suspicious links, ignore deadlines. For low risk (LOW): keep verifying, do not share credentials, verify payment requests independently. The section also includes the India Cyber Crime Portal link https://cybercrime.gov.in/ opening in a new tab with rel="noopener noreferrer", and Helpline 1930.
• Primary actions: Read and act on the checklist items; open the India Cyber Crime Portal link in a new tab.
• Supporting actions: Note the helpline number.
• Domain entities: Checklist items, risk-level branch, reporting link, helpline number.
• Component responsibilities: Checklist list, risk-level branch logic, external link with correct target and rel attributes, helpline display.
• States:
  • Loading: none.
  • Empty: before any analysis, the checklist reflects the pre-loaded Guaranteed Profit result.
  • Success: the checklist matches the current risk level and the reporting link and helpline are present.
  • Error: a friendly message replaces the section; no raw error is shown.
  • Recovery: re-run analysis from the Analyzer.

Practice

• Information / state: Exactly six scenarios, each with a SCAM button and a SAFE button, and after answering, correct/incorrect feedback plus a plain-English explanation. The six scenarios cover: send BTC get more back; a simple Bitcoin price question; a seed phrase request; a recovery fee; the phrase "Never share your seed phrase"; and an independent verification prompt.
• Primary actions: Choose SCAM or SAFE for each scenario; read the feedback and explanation.
• Supporting actions: Re-answer a scenario; move between scenarios with the keyboard.
• Domain entities: Scenario text, correct answer, feedback state, explanation.
• Component responsibilities: Scenario list, answer buttons, feedback region, explanation block.
• States:
  • Loading: none.
  • Empty: all six scenarios are shown unanswered with both buttons available.
  • Success: each answered scenario shows correct or incorrect feedback plus its explanation.
  • Error: a friendly message replaces the section; no raw error is shown.
  • Recovery: the user can answer or re-answer any scenario at any time.

Self-Test

• Information / state: A RUN SELF-TEST button; per-sample result lines in the "Fake Giveaway ..... PASS" form; and a summary line reading "5/5 SELF-TESTS PASSED" or "X/5 SELF-TESTS PASSED".
• Primary actions: Press RUN SELF-TEST to run the real analyzer against all five samples and compare each detected level to its expected level.
• Supporting actions: Read the per-sample lines and the summary.
• Domain entities: Sample name, expected level, detected level, pass/fail, summary count.
• Component responsibilities: Run button, result line list, summary line, aria-live region for the self-test output.
• States:
  • Loading: none — the self-test runs synchronously.
  • Empty: before the button is pressed, the section shows the button and no result lines.
  • Success: five result lines and a summary line are shown, computed from real detection rather than hardcoded values.
  • Error: a friendly message replaces the output; no raw error is shown.
  • Recovery: the button can be pressed again to re-run the self-test.

3. Functional Requirements

Each requirement below is a distinct story point with provenance, lifecycle facts, and observable acceptance.

FR-01 — Single self-contained offline file (explicit) As a Cybersecurity Student Demonstrator, I should receive the entire BITSHIELD application as one self-contained HTML file with HTML, CSS inside a single <style> block, and vanilla JavaScript inside a single <script> block, so that I can open it and demonstrate it with no setup.

• Trigger/input: The file is opened in a browser.
• Observable result: The full application renders and functions with no frameworks, libraries, backend, API, database, wallet, blockchain, or external requests, and works fully offline.
• Access state: Anonymous; no sign-in.
• Failure/recovery: Not applicable — the file either loads or the browser reports a load failure outside the app's control.
• Continuation: The user proceeds to submit or load a message.

FR-02 — Font fallback stacks (explicit) As a Suspicious Message Recipient, I should see headings in "Bricolage Grotesque", Arial, system-ui, body text in "IBM Plex Sans", system-ui, and evidence text in "IBM Plex Mono", ui-monospace, monospace, so that the document reads as a filed report even when the preferred fonts are unavailable.

• Trigger/input: Any page render.
• Observable result: The three font stacks are applied to their respective roles.
• Access state: Anonymous.
• Failure/recovery: If a preferred font is unavailable, the declared fallback renders.
• Continuation: None.

FR-03 — Header identity and status labels (explicit) As a Suspicious Message Recipient, I should see the header "BITSHIELD / Bitcoin Scam Risk Detector" with the status labels OFFLINE DEMO, NO REAL CRYPTO, and NO DATA SENT, and the text "Analyze suspicious Bitcoin messages using transparent warning patterns and understand why a message may be risky.", so that I immediately understand what the tool is and what it does not do.

• Trigger/input: Page load.
• Observable result: The wordmark, subtitle, three status labels, and the description are visible.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: The user reads the description and moves to the evidence desk.

FR-04 — Submit the Evidence input (explicit) As a Suspicious Message Recipient, I should be able to paste a suspicious message into a large textarea labelled "Suspicious message or offer" inside the section "Submit the Evidence", with a maximum of 5000 characters and a live counter reading "0 / 5000", so that I can submit the exact message I received.

• Trigger/input: Typing or pasting into the textarea.
• Observable result: The textarea holds the text and the counter updates live to reflect the true character count against the 5000 limit.
• Access state: Anonymous.
• Failure/recovery: Input beyond 5000 characters is constrained by the maximum; the counter continues to reflect the true count.
• Continuation: The user presses CHECK MESSAGE or loads a sample.

FR-05 — Check Message and Clear controls (explicit) As a Suspicious Message Recipient, I should have a CHECK MESSAGE button that runs the analysis and a CLEAR button that empties the textarea, so that I can control when analysis happens and reset the desk.

• Trigger/input: Activating CHECK MESSAGE or CLEAR.
• Observable result: CHECK MESSAGE produces an analysis of the current textarea contents; CLEAR empties the textarea and resets the counter.
• Access state: Anonymous.
• Failure/recovery: If analysis fails internally, a friendly message is shown and the textarea contents are preserved so the user can retry.
• Continuation: After CHECK MESSAGE, the user reads the results; after CLEAR, the user can paste a new message.

FR-06 — Robust input handling with friendly messages (explicit) As a Suspicious Message Recipient, I should receive friendly messages when I submit empty, whitespace-only, emoji, Unicode, non-English, long, or pasted text, so that I am never confronted with a raw error or a silent failure.

• Trigger/input: Submitting any of those input forms.
• Observable result: A friendly, human-readable message is shown; the analysis is wrapped in try/catch and raw errors are never displayed.
• Access state: Anonymous.
• Failure/recovery: The user edits the text or loads a sample and tries again.
• Continuation: The user proceeds to a successful analysis.

FR-07 — Five preset samples (explicit) As a Suspicious Message Recipient, I should have five sample buttons — Fake Giveaway, Guaranteed Profit, Fake Support, Withdrawal Fee, and Normal Question — where clicking fills the textarea, updates the counter, and auto-analyzes, so that I can see the analyzer work on known cases.

• Trigger/input: Activating a sample button.
• Observable result: The textarea is filled with that sample's exact text, the counter updates, and analysis runs automatically.
• Access state: Anonymous.
• Failure/recovery: If analysis fails, a friendly message is shown and the sample text remains in the textarea.
• Continuation: The user reads the results for that sample.

FR-08 — Exact sample texts (explicit) As a Suspicious Message Recipient, I should see these exact sample texts when I load each sample:

• Fake Giveaway: "Congratulations! You have been selected for an exclusive Bitcoin giveaway. Send 0.01 BTC to the address below and we will send 0.1 BTC back. Act now, this offer expires in 10 minutes!"
• Guaranteed Profit: "Our private Bitcoin investment program guarantees 8% daily profit with zero risk. Deposit BTC today and your returns are guaranteed. Pay a small upfront activation fee before withdrawal."
• Fake Support: "URGENT SECURITY ALERT: Your Bitcoin exchange account will be suspended today. I am from exchange support. Verify your wallet immediately by sending your seed phrase or private key to our support agent."
• Withdrawal Fee: "Your Bitcoin withdrawal is ready, but a refundable 0.02 BTC compliance fee must be paid first. Send the fee to unlock your funds. If you do not pay today, your account may face legal action."
• Normal: "Hi, I am learning about Bitcoin. What is the difference between a Bitcoin wallet address and a private key? I will never share my seed phrase."
• Trigger/input: Activating the corresponding sample button.
• Observable result: The exact text above appears in the textarea.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: Analysis runs automatically.

FR-09 — Auto-load Guaranteed Profit on page load (explicit) As a Suspicious Message Recipient, I should see the Guaranteed Profit sample auto-loaded and analyzed when the page loads, so that the desk is never empty and the tool demonstrates itself immediately.

• Trigger/input: Page load.
• Observable result: The Guaranteed Profit text is in the textarea, the counter reflects it, and its analysis is displayed.
• Access state: Anonymous.
• Failure/recovery: If the initial analysis fails, a friendly message is shown and the sample text remains available.
• Continuation: The user reads the pre-loaded result or submits their own message.

FR-10 — Local rule engine of 18–20 rules (explicit) As a Suspicious Message Recipient, I should have my message evaluated by a local JavaScript array of 18–20 rules, each with id, label, weight, regex, explanation, tip, family, and stage, so that every result is traceable to a named, inspectable rule.

• Trigger/input: Running the analyzer on a message.
• Observable result: Each rule is evaluated against the message and matched rules carry all eight fields.
• Access state: Anonymous.
• Failure/recovery: A rule that cannot be evaluated is skipped without breaking the analysis; a friendly message is shown if the analysis as a whole fails.
• Continuation: Matched rules feed the score, findings, highlights, scam type, and stage tracker.

FR-11 — Required rule coverage (explicit) As a Suspicious Message Recipient, I should have the rule engine cover guaranteed profit, unrealistic returns, Bitcoin giveaway, send BTC to get more back, urgency, seed phrase request, private key request, fake exchange support, fake security alert, gift card payment, crypto ATM payment, wallet address, short links, look-alike domains, secrecy, upfront fees, recovery scam, remote-access software, legal threats, password/OTP request, and unexpected crypto payment demand, so that the common Bitcoin scam patterns are all represented.

• Trigger/input: Running the analyzer on a message containing any of these patterns.
• Observable result: The corresponding rule is present in the engine and can match.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: Matched rules contribute to the score and findings.

FR-12 — Negation handling (explicit) As a Suspicious Message Recipient, I should have "Never share your seed phrase" and "Do not send Bitcoin" NOT trigger rules, so that safe, cautionary language is not flagged as a warning sign.

• Trigger/input: A message containing those phrases.
• Observable result: No rule matches on those phrases and no highlight is produced for them.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: The message is scored on its remaining content.

FR-13 — Safe regex only (explicit) As a Cybersecurity Student Demonstrator, I should have every rule use safe regex only — no nested quantifiers, with bounded wildcards such as [\s\S]{0,60} — so that the analyzer cannot hang or catastrophically backtrack during a live demo.

• Trigger/input: Running the analyzer on any input, including long pasted text.
• Observable result: Every rule evaluates promptly and the analysis completes.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: The analysis proceeds to scoring.

FR-14 — Exponential scoring formula (explicit) As a Suspicious Message Recipient, I should have my score computed as sum = total matched weights, then score = round(100 x (1 - e^(-sum/45))), capped at 100, so that the score reflects accumulated evidence rather than a simple count.

• Trigger/input: Running the analyzer.
• Observable result: The score is computed by that exact formula and never exceeds 100.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: The score is mapped to a risk level.

FR-15 — Urgency and payment bonus (explicit) As a Suspicious Message Recipient, I should have a +12 bonus added to the sum when urgency AND payment rules both match, applied before the formula, so that messages that combine time pressure with a payment demand are scored more severely.

• Trigger/input: A message in which both an urgency rule and a payment rule match.
• Observable result: The sum used in the formula includes the +12 bonus, and the bonus is shown in the calculation.
• Access state: Anonymous.
• Failure/recovery: If only one of the two families matches, no bonus is applied.
• Continuation: The score is computed from the bonused sum.

FR-16 — Risk level bands (explicit) As a Suspicious Message Recipient, I should have my score mapped to LOW (0–24), MEDIUM (25–47), HIGH (48–71), or CRITICAL (72–100), so that the verdict is expressed in a small, legible ladder.

• Trigger/input: A computed score.
• Observable result: Exactly one level is assigned according to those bands.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: The level drives the stamp, the coded colour, and the Next Steps branch.

FR-17 — Full calculation display (explicit) As a Suspicious Message Recipient, I should see the full calculation — the matched weights, the bonus when applied, the formula, and the final score — so that I can verify how the verdict was reached.

• Trigger/input: A completed analysis.
• Observable result: The "Why this score?" breakdown lists each matched pattern with its weight, states the bonus if applied, shows the formula, and shows the final score.
• Access state: Anonymous.
• Failure/recovery: If no rules match, the breakdown states that no weights were accumulated and shows the resulting score.
• Continuation: The user reads the findings.

FR-18 — Target sample levels (explicit) As a Cybersecurity Student Demonstrator, I should have the weights tuned so that Fake Giveaway, Guaranteed Profit, and Fake Support score CRITICAL, Withdrawal Fee scores HIGH, and Normal Question scores LOW, so that the demo proves the engine behaves as designed.

• Trigger/input: Running the analyzer on each of the five samples.
• Observable result: Each sample produces its target level.
• Access state: Anonymous.
• Failure/recovery: The self-test surfaces any sample that does not meet its target.
• Continuation: The demonstrator proceeds to the self-test.

FR-19 — Stamp-style verdict with score and progress bar (explicit) As a Suspicious Message Recipient, I should see a prominent stamp-style risk level, the score in the "86 / 100" form, and a text progress bar, so that the verdict is the loudest element on the desk.

• Trigger/input: A completed analysis.
• Observable result: The stamp, the score line, and the text progress bar are all rendered and consistent with the computed level and score.
• Access state: Anonymous.
• Failure/recovery: If the result cannot be rendered, a friendly message is shown.
• Continuation: The user reads the calculation and findings.

FR-20 — aria-live result updates (explicit) As a Suspicious Message Recipient using a screen reader, I should have result updates wrapped in aria-live, so that a new verdict is announced without moving focus.

• Trigger/input: Any analysis that changes the result region.
• Observable result: The updated result content is announced.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: The user navigates to the findings.

FR-21 — Safe evidence highlighting (explicit) As a Suspicious Message Recipient, I should see the original message displayed with matched phrases in evidence-tape styling, rendered without ever using innerHTML with user text, using textContent, createElement, and appendChild instead, so that pasted content can never be interpreted as markup.

• Trigger/input: A completed analysis with at least one matched phrase.
• Observable result: The message is displayed in full with matched phrases taped; no user text is ever passed through innerHTML.
• Access state: Anonymous.
• Failure/recovery: If highlighting cannot be produced, the message is still displayed as plain safe text.
• Continuation: The user can activate a highlight.

FR-22 — No eval or Function (explicit) As a Cybersecurity Student Demonstrator, I should have the application use no eval and no Function constructor anywhere, so that the demo is defensible as a safe, self-contained artefact.

• Trigger/input: Any code path.
• Observable result: Neither eval nor Function appears in the implementation.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: None.

FR-23 — Clickable highlights that focus their finding (explicit) As a Suspicious Message Recipient, I should be able to click a highlighted phrase and have the page scroll to and focus its corresponding finding, so that I can move directly from evidence to explanation.

• Trigger/input: Clicking or keyboard-activating a highlight.
• Observable result: The matching finding card is scrolled into view and focused.
• Access state: Anonymous.
• Failure/recovery: If the matching finding is not present, the highlight remains readable and no error is shown.
• Continuation: The user reads the finding.

FR-24 — Warning Signs Detected findings (explicit) As a Suspicious Message Recipient, I should see a "Warning Signs Detected" section where each matched rule shows its severity, rule name, matched evidence, why it is risky, and what to check, in plain beginner language, so that I understand the risk without technical background.

• Trigger/input: A completed analysis with matched rules.
• Observable result: One finding per matched rule, each with all five fields.
• Access state: Anonymous.
• Failure/recovery: If no rules match, the section states that no warning signs were detected.
• Continuation: The user reads the scam type and stage tracker.

FR-25 — Scam type card (explicit) As a Suspicious Message Recipient, I should see a scam type card showing the strongest matched family from Investment, Giveaway, Impersonation, Credential Theft, Phishing, Pressure, Advance Fee, Recovery, Device Takeover, and Payment, with the family name and a "How it works" description, plus the note that this is an educational classification and not a legal determination, so that I understand the shape of the scam.

• Trigger/input: A completed analysis with matched rules.
• Observable result: The strongest family is named with its "How it works" text and the educational-classification note.
• Access state: Anonymous.
• Failure/recovery: If no rules match, the card states that no scam family was identified.
• Continuation: The user reads the stage tracker.

FR-26 — Stage tracker (explicit) As a Suspicious Message Recipient, I should see a stage tracker HOOK > TRUST > PRESSURE > PAYMENT > EXIT with the active stages derived from matched rules, laid out horizontally on desktop and stacked on mobile, so that I can see where in the scam's arc this message sits.

• Trigger/input: A completed analysis with matched rules.
• Observable result: The five stages are shown in order with the active ones marked, and the layout is horizontal on desktop and stacked on mobile.
• Access state: Anonymous.
• Failure/recovery: If no rules match, no stage is marked active.
• Continuation: The user reads the reality check.

FR-27 — Reality check on percentage claims (explicit) As a Suspicious Message Recipient, I should have any "X% daily", "X% weekly", or "X% monthly" claim detected and its compounded yearly return computed and displayed (for example (1.08^365 - 1) x 100), together with the note "This is a mathematical reality check, not proof that the sender's claim is true. Extremely large repeated returns are a reason to stop and independently verify the offer.", so that I can see the arithmetic consequence of the promise.

• Trigger/input: A message containing a percentage-return claim with a daily, weekly, or monthly period.
• Observable result: The claim and its compounded yearly figure are displayed with the limitation note.
• Access state: Anonymous.
• Failure/recovery: If no such claim is present, the section states that none was found.
• Continuation: The user reads the next steps.

FR-28 — Dynamic What to Do Now checklist (explicit) As a Suspicious Message Recipient, I should see a dynamic checklist that adapts to the risk level — for high risk: do not send Bitcoin, do not pay upfront fees, verify independently, never share seed phrase / private key / passwords / OTP, no remote-access software, do not click suspicious links, ignore deadlines; for low risk: keep verifying, do not share credentials, verify payment requests independently — so that my next actions match the verdict.

• Trigger/input: A completed analysis with a risk level.
• Observable result: The checklist shown matches the current risk level.
• Access state: Anonymous.
• Failure/recovery: If the level cannot be determined, the checklist defaults to the cautious set and a friendly message is shown.
• Continuation: The user reads the reporting contacts.

FR-29 — Reporting contacts (explicit) As a Suspicious Message Recipient, I should see the India Cyber Crime Portal link https://cybercrime.gov.in/ opening in a new tab with rel="noopener noreferrer", and Helpline 1930, so that I know where to report.

• Trigger/input: Reading the Next Steps section.
• Observable result: The link is present with target="_blank" and rel="noopener noreferrer", and the helpline number 1930 is displayed.
• Access state: Anonymous.
• Failure/recovery: The app functions fully offline; the link is a reference the user may choose to open.
• Continuation: The user reads the checked-and-clear list.

FR-30 — Checked and Clear list (explicit) As a Suspicious Message Recipient, I should see a list of the rules that did not match, each with a check mark, together with the note "No matched rule is not proof that a message is legitimate.", so that I understand what was checked and why a clean result is not a guarantee.

• Trigger/input: A completed analysis.
• Observable result: Every unmatched rule is listed with a check mark and the note is displayed.
• Access state: Anonymous.
• Failure/recovery: If every rule matched, the list states that no rules were left unchecked.
• Continuation: The user moves to practice mode or the self-test.

FR-31 — Practice mode with exactly six scenarios (explicit) As a Suspicious Message Recipient, I should have exactly six practice scenarios, each with a SCAM button and a SAFE button, followed by correct/incorrect feedback and an explanation, covering send BTC get more back, a simple Bitcoin price question, a seed phrase request, a recovery fee, "Never share your seed phrase", and independent verification, so that I can rehearse my judgement.

• Trigger/input: Choosing SCAM or SAFE for a scenario.
• Observable result: The scenario shows correct or incorrect feedback plus a plain-English explanation.
• Access state: Anonymous.
• Failure/recovery: The user can re-answer any scenario.
• Continuation: The user moves to the self-test.

FR-32 — Self-test that really runs the analyzer (explicit) As a Cybersecurity Student Demonstrator, I should have a RUN SELF-TEST button that really runs the analyzer on all five samples, compares each detected level to its expected level, and shows "Fake Giveaway ..... PASS" style lines and "5/5 SELF-TESTS PASSED" (or "X/5 SELF-TESTS PASSED"), so that I can prove the engine works during the demo.

• Trigger/input: Pressing RUN SELF-TEST.
• Observable result: Five per-sample result lines and a summary count are displayed, computed from real detection rather than hardcoded values.
• Access state: Anonymous.
• Failure/recovery: A sample that does not meet its expected level is reported as a failure and the summary count reflects it.
• Continuation: The demonstrator can re-run the self-test or return to the analyzer.

FR-33 — Accessibility (explicit) As a Suspicious Message Recipient, I should have proper labels, keyboard navigation, visible focus, aria-live regions, WCAG AA contrast, meaning never carried by colour alone, and touch-friendly buttons, so that the tool is usable regardless of input method or vision.

• Trigger/input: Any interaction.
• Observable result: Every control is labelled and keyboard reachable with visible focus; every coded colour is accompanied by a word; contrast meets WCAG AA; buttons are touch-friendly.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: None.

FR-34 — Responsive layout (explicit) As a Suspicious Message Recipient, I should have the app work at 320px, 360px, 390px, tablet, and desktop with no horizontal scroll, with a single column and full-width buttons on mobile and two columns on desktop — LEFT: input, highlighted message, and findings; RIGHT: scam type, reality check, what to do, checked and clear, practice, and self-test — so that the desk is readable on any device.

• Trigger/input: Resizing the viewport.
• Observable result: The layout reflows as described and no horizontal scrollbar appears at any of those widths.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: None.

FR-35 — Light and dark theme via CSS variables (explicit) As a Suspicious Message Recipient, I should have light and dark themes driven by CSS variables following prefers-color-scheme, with dark mode using dark blue-grey paper, light ink, muted borders, and the deep red stamp, and not a cyberpunk look, so that the desk is comfortable in either environment.

• Trigger/input: The operating system colour-scheme preference.
• Observable result: The theme switches accordingly and the dark theme matches the described character.
• Access state: Anonymous.
• Failure/recovery: If the preference is unavailable, the light theme renders.
• Continuation: None.

FR-36 — Single entrance animation and static stamp rotation (explicit) As a Suspicious Message Recipient, I should see only one subtle entrance fade/slide and a static slight stamp rotation, with all motion disabled under prefers-reduced-motion, so that the desk feels still and forensic.

• Trigger/input: Page load and the reduced-motion preference.
• Observable result: One entrance animation plays; the stamp sits at a static slight rotation; under prefers-reduced-motion all motion is removed.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: None.

FR-37 — Optional localStorage in try/catch (explicit) As a Suspicious Message Recipient, I should have any localStorage use be optional and wrapped in try/catch, so that the app never breaks when storage is unavailable or blocked.

• Trigger/input: Any code path that touches localStorage.
• Observable result: If storage is unavailable, the app continues to function normally.
• Access state: Anonymous; no identity is created or stored.
• Failure/recovery: The failure is swallowed and the app proceeds without persistence.
• Continuation: None.

FR-38 — Visual hierarchy (explicit) As a Suspicious Message Recipient, I should have the risk level and score as the loudest elements, then warning signs, highlighted evidence, why risky, and what to do, with secondary cards quieter, so that my eye lands on the verdict first.

• Trigger/input: A completed analysis.
• Observable result: The visual weight ordering matches that sequence.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: None.

FR-39 — Footer disclaimer (explicit) As a Suspicious Message Recipient, I should see the footer text "BitShield provides pattern-based educational guidance, not proof that a message is a scam or legitimate. Always verify important claims independently. This demo uses sample/test data only and never handles real Bitcoin or money.", so that the limits of the tool are always stated.

• Trigger/input: Page load.
• Observable result: The footer text is displayed verbatim.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: None.

FR-40 — Sample/test data only; no real crypto (explicit) As a Suspicious Message Recipient, I should have the app use sample/test data only and never handle real Bitcoin, keys, or payments, so that using the tool carries no financial risk.

• Trigger/input: Any interaction.
• Observable result: No wallet, key, address, or payment handling exists anywhere in the app.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: None.

FR-41 — No console errors (explicit) As a Cybersecurity Student Demonstrator, I should have the app produce no console errors, so that the demo is clean when the console is visible.

• Trigger/input: Loading the page and exercising every control.
• Observable result: The console remains free of errors.
• Access state: Anonymous.
• Failure/recovery: Any internal failure is caught and surfaced as a friendly message rather than an uncaught error.
• Continuation: None.

FR-42 — Complete finished file output (explicit) As a Cybersecurity Student Demonstrator, I should receive the complete finished file, so that I can open it and present it without further assembly.

• Trigger/input: Delivery of the artefact.
• Observable result: One complete, working, self-contained HTML file.
• Access state: Anonymous.
• Failure/recovery: Not applicable.
• Continuation: The demonstrator opens the file and runs the self-test.

4. User Personas

Suspicious Message Recipient

Product context. This person has just received a message or offer involving Bitcoin — a giveaway, an investment pitch, a support alert, a withdrawal demand — and is uneasy about it. They are not a security professional. They may be reading on a phone at 360px or on a laptop, and they need an answer they can trust and understand.

Primary goal. To understand, in plain language, why the message they received may be risky, and what to check or do next — without being handed a bare scam/not-scam verdict they cannot interrogate.

Distinct accepted responsibilities. They paste the message into "Submit the Evidence", or load one of the five samples to see how the tool behaves. They press CHECK MESSAGE or CLEAR. They read the stamped risk level and score, then the "Why this score?" calculation, then the warning signs, then the highlighted evidence in their own message, then the scam type, the stage tracker, the reality check, and the next steps. They click a highlighted phrase to jump to its finding. They read the checked-and-clear list and understand that a clean result is not a guarantee. They may rehearse their judgement in practice mode.

Relevant inputs and decisions. The message text itself; the decision of whether to trust the offer; the decision of which next step to take; the decision of whether to open the India Cyber Crime Portal link or call Helpline 1930.

Interactions with other accepted participants. This persona is the sole human actor in the analysis lifecycle. The other accepted persona, the Cybersecurity Student Demonstrator, may be the same person in a different context, but the Recipient's work is private and self-directed: they submit, read, and act. No other human participant receives or responds to their submission.

Observable success. The Recipient sees a risk level and score that match the message's character, reads at least one finding that explains a phrase they can see highlighted in their own message, understands the arithmetic behind any return claim, and leaves with a concrete next step — including the reporting link and helpline when the risk is high.

Cybersecurity Student Demonstrator

Product context. This person is presenting BITSHIELD as a college cybersecurity project. They need the app to be visibly working, not a mockup, and they need to be able to prove the engine's logic in front of an audience — often with the browser console open and the network tab showing no requests.

Primary goal. To demonstrate a polished, fully offline tool whose rule engine, scoring formula, and evidence handling can be inspected and verified live.

Distinct accepted responsibilities. They load the app and let the Guaranteed Profit sample auto-analyze. They step through all five samples and show that Fake Giveaway, Guaranteed Profit, and Fake Support reach CRITICAL, Withdrawal Fee reaches HIGH, and Normal Question reaches LOW. They open the "Why this score?" breakdown to show the matched weights, the urgency+payment bonus, the formula, and the final score. They point at the highlighted evidence and click a tape label to jump to its finding. They demonstrate that "Never share your seed phrase" does not trigger a rule. They press RUN SELF-TEST and show the five PASS lines and the "5/5 SELF-TESTS PASSED" summary. They may resize the window to 320px to show the responsive layout, and toggle the OS colour scheme to show the dark theme.

Relevant inputs and decisions. Which sample to load next; whether to show the calculation or the findings first; whether to run the self-test before or after the manual walkthrough.

Interactions with other accepted participants. The Demonstrator's work is presentational and does not change the Recipient's analysis. The Demonstrator may narrate the Recipient's experience, but the two roles have different success criteria: the Recipient needs understanding, the Demonstrator needs verifiable proof.

Observable success. The self-test reports "5/5 SELF-TESTS PASSED", every sample lands on its expected level, the calculation is visible on screen, the highlights are safe and clickable, the console shows no errors, and the app works with the network disconnected.

5. Core User Flows

Flow 1 — Recipient analyzes a suspicious message they received

1. The Recipient opens the BITSHIELD file. The Landing area renders: the wordmark, the three status labels, the description, and the pre-loaded Guaranteed Profit evidence sheet with its stamped verdict already visible.
2. The Recipient moves to the Analyzer section "Submit the Evidence" and pastes the message they received into the textarea labelled "Suspicious message or offer". The live counter updates to show the true character count against 5000.
3. The Recipient presses CHECK MESSAGE. The analyzer runs locally.
4. The Results area updates inside its aria-live region: the stamp shows the risk level, the score appears in the "86 / 100" form, and the text progress bar fills to match.
5. The Recipient reads "Why this score?" and sees each matched pattern with its weight, the +12 urgency+payment bonus if it applied, the formula round(100 x (1 - e^(-sum/45))), and the final score.
6. The Recipient moves to the Evidence sheet and sees their own message in monospace with the matched phrases taped in deep red, each carrying its rule id label.
7. The Recipient clicks a taped phrase. The page scrolls to and focuses the matching card in Findings.
8. In Findings ("Warning Signs Detected") the Recipient reads, for that rule, the severity, the rule name, the matched evidence, the plain-language "why risky" explanation, and the plain-language "what to check" tip.
9. The Recipient reads the Results scam type card, which names the strongest matched family and explains "How it works", with the note that this is an educational classification and not a legal determination.
10. The Recipient reads the stage tracker HOOK > TRUST > PRESSURE > PAYMENT > EXIT and sees which stages are active for this message.
11. The Recipient reads the Reality Check. If the message claimed a percentage return, the claim and its compounded yearly figure are shown with the note that this is a mathematical reality check, not proof that the sender's claim is true.
12. The Recipient reads Next Steps. Because the level is high, the checklist tells them not to send Bitcoin, not to pay upfront fees, to verify independently, never to share seed phrase / private key / passwords / OTP, to avoid remote-access software, not to click suspicious links, and to ignore deadlines. The India Cyber Crime Portal link and Helpline 1930 are shown.
13. The Recipient reads the Results checked-and-clear list, sees which rules did not match, and reads the note "No matched rule is not proof that a message is legitimate."
14. Failure and recovery: If the Recipient pastes an empty or whitespace-only message, or text containing emoji, Unicode, or non-English characters, a friendly message is shown instead of an analysis, and the textarea contents are preserved. If the analysis fails internally, the failure is caught and a friendly message replaces the result region; the Recipient edits the text or presses CLEAR and tries again.
15. Continuation: The Recipient presses CLEAR, pastes a second message, and repeats the flow, or moves to Practice to rehearse.

Flow 2 — Recipient loads a sample to see how the tool behaves

1. From the Analyzer, the Recipient activates one of the five sample buttons: Fake Giveaway, Guaranteed Profit, Fake Support, Withdrawal Fee, or Normal Question.
2. The textarea fills with that sample's exact text, the counter updates, and the analysis runs automatically.
3. The Results, Evidence, Findings, Reality Check, and Next Steps areas all update to reflect that sample.
4. The Recipient compares the verdict across samples — for example, noticing that Normal Question returns LOW while the others return HIGH or CRITICAL — and reads the checked-and-clear list to see which rules the Normal Question message left unmatched.
5. Failure and recovery: If the analysis fails, a friendly message is shown and the sample text remains in the textarea so the Recipient can retry.
6. Continuation: The Recipient loads another sample or pastes their own message.

Flow 3 — Recipient rehearses judgement in practice mode

1. The Recipient moves to Practice and sees exactly six scenarios, each with a SCAM button and a SAFE button.
2. The Recipient reads the first scenario — send BTC get more back — and chooses SCAM.
3. The scenario shows correct feedback and a plain-English explanation of why that pattern is a scam.
4. The Recipient works through the remaining scenarios: a simple Bitcoin price question, a seed phrase request, a recovery fee, "Never share your seed phrase", and an independent verification prompt.
5. On the "Never share your seed phrase" scenario, the Recipient chooses SAFE and the feedback confirms that cautionary language is not itself a warning sign.
6. Failure and recovery: If the Recipient answers incorrectly, the feedback says so and the explanation clarifies the reasoning; the Recipient can re-answer.
7. Continuation: The Recipient returns to the Analyzer with a better sense of what to look for.

Flow 4 — Demonstrator proves the engine works

1. The Demonstrator opens the file. The Landing area shows the header, the status labels, and the pre-loaded Guaranteed Profit verdict.
2. The Demonstrator steps through the five samples in the Analyzer, showing that Fake Giveaway, Guaranteed Profit, and Fake Support reach CRITICAL, Withdrawal Fee reaches HIGH, and Normal Question reaches LOW.
3. The Demonstrator opens the "Why this score?" breakdown in Results and walks the audience through the matched weights, the +12 urgency+payment bonus, the formula, and the final score.
4. The Demonstrator points at the Evidence sheet, shows the taped phrases, and clicks one to jump to its Findings card.
5. The Demonstrator loads the Normal Question sample and shows that "Never share my seed phrase" produces no highlight and no finding, demonstrating negation handling.
6. The Demonstrator moves to Self-Test and presses RUN SELF-TEST.
7. The self-test really runs the analyzer on all five samples, compares each detected level to its expected level, and displays lines in the "Fake Giveaway ..... PASS" form followed by "5/5 SELF-TESTS PASSED".
8. Failure and recovery: If any sample fails to meet its expected level, the corresponding line reports the failure and the summary reads "X/5 SELF-TESTS PASSED"; the Demonstrator can press the button again to re-run.
9. Continuation: The Demonstrator resizes the window to 320px to show the single-column layout with full-width buttons, toggles the OS colour scheme to show the dark theme, and confirms the console shows no errors and the network tab shows no requests.

6. Visuals, Colors and Theme

The creative direction is authoritative for this section. The muse is Peter Saville: a single borrowed artefact carrying the whole identity, coded colour, precise small metadata type, and a great deal of silence. The headline idea is "one pasted message becomes the artefact; the rule engine becomes the colour code; the risk verdict becomes the one exact spot colour stamped on the sheet." The register is cold, forensic, and procedural — institutional and quiet, with one decisive colour statement. It is not playful, not corporate-friendly, and not neon-cyberpunk.

Colour tokens — light mode

Colour tokens — dark mode

The risk ladder is a coded colour alphabet, not a gradient: LOW is a green rule, MEDIUM amber, HIGH deep red, CRITICAL deep red with a doubled rule and the word set twice in the stamp. Every coded colour is always accompanied by a word, so meaning never rests on colour alone.

Typography

• Headings: Bricolage Grotesque at 600–700 for the wordmark and section titles, set tight with letter-spacing: -0.02em and in sentence case. The BITSHIELD wordmark is all-caps with wide 0.14em tracking at small size, like a stamped file reference. The risk level itself is set enormous — 800 weight, all-caps, tight leading — so it reads as a printed verdict rather than a headline.
• Body: IBM Plex Sans.
• Evidence text and all matched phrases: IBM Plex Mono at 0.95rem with 0.02em tracking.
• Type scale: 1.333 modular — display clamp(44px, 9vw, 72px), section title 28/34, card title 20/22, body 16/17, evidence mono 15/16, metadata 12/13 with 0.08em tracking.

Shape language

Hard edges everywhere: 2px radius maximum on cards and buttons, 0px on the stamp and the evidence tape. Rules and dividers are 1px hairlines in a slightly darker blue-grey. The only curves in the whole interface are the CSS shield mark (a single filled polygon with a notched bottom) and the circular risk gauge behind the score. No pills, no soft shadows — depth comes from a 1px border plus a single 2px offset hairline on the sheet edge, like a paper stack.

Layout

Desktop at 1280px: a fixed 12-column grid with a 1180px max width. LEFT column (7 cols) holds Submit the Evidence, the highlighted original message rendered as a monospace evidence sheet, and Warning Signs Detected. RIGHT column (5 cols, sticky from the top) holds the stamp verdict, Scam Type, Stage Tracker, Reality Check, What To Do Now, Checked and Clear, Practice Mode, and Self-Test. A thin horizontal rule with a small all-caps label separates every section, and each section is numbered 01–09 in the left margin like a lab report. Mobile at 320–390px: single column in the same numbered order, all buttons full width, and the stamp verdict moved directly under the header so it is seen first.

Imagery

No photography, no illustration, no icons except the CSS shield. Imagery is the interface itself: the monospace evidence sheet, the ruled data rows, the taped labels, the coded colour bars, the numbered sections. The one graphic gesture is the shield mark — a flat navy polygon at 26px with a 2px inner hairline and a small red notch, drawn entirely in CSS clip-path.

7. Signature Design Concept

The first screen is a desk, not a hero.

A full-width pale blue-grey ground (#E7EBEF) with a 1px hairline running the entire width beneath the header. On the left: the BITSHIELD wordmark in all-caps Bricolage with 0.14em tracking; the three status labels — OFFLINE DEMO, NO REAL CRYPTO, NO DATA SENT — as small outlined chips in muted grey monospace; and the one-sentence description set at 17px in IBM Plex Sans at a 62-character measure.

To the right of the header block, immediately visible without scrolling on desktop and stacked directly beneath on mobile, sits the verdict artefact: a near-white evidence sheet (#FBFCFD) with the sample message already loaded in monospace on the left half and, rotated -3.2deg on the right half, a deep-red double-ruled rubber stamp reading CRITICAL with 86 / 100 beneath it in the same red. A 1px red progress rule runs the full width of the sheet under the stamp.

No gradient, no blob, no floating panel — one sheet, one stamp, one exact red.

Signature moves carried through the whole app:

• The verdict is a real rubber stamp. A deep-red double-ruled rectangle rotated -3.2deg, with the risk level set in 800-weight all-caps Bricolage at clamp(44px, 9vw, 72px) and the score beneath it as "86 / 100" in IBM Plex Mono, printed over the corner of the evidence sheet so it slightly overlaps the sheet's hairline border.
• Matched phrases are evidence tape. A 1px deep-red box with 2px radius, a small red tick on the left edge, and the phrase in IBM Plex Mono at 0.95rem. Hovering or focusing lifts a tiny all-caps label above it reading the rule id (for example "R-03 GIVEAWAY"), and clicking focuses the matching finding card, which then gets a 1px red left border.
• Every section is numbered like a lab report — 01 SUBMIT THE EVIDENCE, 02 WARNING SIGNS DETECTED, 03 WHY THIS SCORE — with the number in muted monospace sitting in the left margin above a full-width 1px hairline rule, so the whole app reads as a filed document rather than a dashboard.
• The risk ladder is a coded colour alphabet, not a gradient. LOW is a green rule, MEDIUM amber, HIGH deep red, CRITICAL deep red with a doubled rule and the word set twice in the stamp. The text progress bar is a 1px-ruled track with a solid coded fill and the numeric score printed at the end in monospace.
• The stage tracker is drawn as a transit line. A single 1px horizontal rule with five small square stops; active stops are filled in deep red with the stage name in all-caps mono beneath, inactive stops are hollow with muted labels. On mobile the line stacks into five ruled rows.

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: still Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject: The verdict artefact — the near-white evidence sheet carrying the pre-loaded Guaranteed Profit message in monospace and the deep-red rubber stamp reading CRITICAL with 86 / 100, rotated -3.2deg, with the 1px red progress rule beneath it.
• Input → transformation → outcome thesis: The user's pasted message is the input; the local rule engine is the transformation; the stamped verdict on the sheet is the outcome. The hero shows this thesis in its resting state — one message already laid out, already coded, already stamped — so the first frame is the product's defining moment rather than a promise of one.
• Motion vocabulary: Still. One entrance only: the stamped verdict card fades in and slides up 8px over 320ms with a plain ease-out, then never moves again. The stamp sits at a static -3.2deg rotation. The progress bar fills with a 260ms width transition. Highlight hover raises the tape label by 1px.
• Composed first frame: Full-width pale blue-grey ground; a 1px hairline beneath the header; the wordmark, status chips, and description on the left; the evidence sheet with its stamped verdict on the right, already visible without scrolling on desktop and stacked directly beneath the header on mobile.
• Reduced-motion state: Under prefers-reduced-motion, the fade, the slide, the rotation transition, and the bar fill are all removed. The verdict card, the stamp at its static rotation, and the progress bar at its final width are shown immediately and whole.

9. Non-Functional Requirements

NFR-01 — Offline operation (explicit) The application must work fully offline, with no network requests of any kind. Rationale: the authoritative requirement states "Must work fully offline" and forbids external requests; the demo must run with the network disconnected.

NFR-02 — Single-file delivery (explicit) The application must be delivered as one self-contained HTML file with HTML, a single <style> block, and a single <script> block. Rationale: explicit technology constraint.

NFR-03 — No frameworks, libraries, backend, API, database, wallet, blockchain, or external requests (explicit) None of these may be used or contacted. Rationale: explicit technology constraint.

NFR-04 — Safe DOM rendering (explicit) User text must never be passed through innerHTML; rendering must use textContent, createElement, and appendChild. Rationale: explicit security constraint; pasted content must never be interpreted as markup.

NFR-05 — No dynamic code execution (explicit) eval and the Function constructor must not appear anywhere in the implementation. Rationale: explicit security constraint.

NFR-06 — Safe regular expressions (explicit) Every rule regex must avoid nested quantifiers and use bounded wildcards such as [\s\S]{0,60}. Rationale: explicit constraint; the analyzer must not hang or catastrophically backtrack during a live demo.

NFR-07 — No raw error exposure (explicit) Analysis must be wrapped in try/catch and raw errors must never be shown to the user. Rationale: explicit constraint; the user must always see a friendly message.

NFR-08 — No console errors (explicit) The application must produce no console errors during load or during any interaction. Rationale: explicit final-check requirement; the console is visible during the demo.

NFR-09 — Accessibility (explicit) Proper labels, keyboard navigation, visible focus, aria-live regions, WCAG AA contrast, meaning never carried by colour alone, and touch-friendly buttons. Rationale: explicit accessibility requirement.

NFR-10 — Responsive with no horizontal scroll (explicit) The layout must work at 320px, 360px, 390px, tablet, and desktop with no horizontal scroll. Rationale: explicit responsive requirement.

NFR-11 — Theme following system preference (explicit) Light and dark themes must be driven by CSS variables following prefers-color-scheme. Rationale: explicit theme requirement.

NFR-12 — Reduced-motion support (explicit) All motion must be disabled under prefers-reduced-motion. Rationale: explicit animation constraint.

NFR-13 — Safe optional storage (explicit) Any localStorage use must be optional and wrapped in try/catch. Rationale: explicit constraint; the app must not break when storage is blocked.

NFR-14 — Sample/test data only (explicit) The app must never handle real Bitcoin, keys, or payments. Rationale: explicit safety constraint.

NFR-15 — Correct sample classification (explicit) Fake Giveaway, Guaranteed Profit, and Fake Support must classify as CRITICAL; Withdrawal Fee as HIGH; Normal Question as LOW. Rationale: explicit acceptance target; the self-test verifies it.

NFR-16 — Negation correctness (explicit) "Never share your seed phrase" and "Do not send Bitcoin" must not trigger any rule. Rationale: explicit correctness constraint.

NFR-17 — Bonus correctness (explicit) The +12 bonus must be applied to the sum when urgency AND payment rules both match, before the formula is evaluated. Rationale: explicit scoring constraint.

NFR-18 — Formula always shown (explicit) The full calculation must always be shown to the user. Rationale: explicit transparency requirement.

NFR-19 — Highlight safety and interactivity (explicit) Highlighting must always be produced through the DOM and must support click and focus navigation to the matching finding. Rationale: explicit requirement.

NFR-20 — Practice completeness (explicit) All six practice scenarios must display, accept an answer, and give a rationale. Rationale: explicit requirement.

NFR-21 — Self-test authenticity (explicit) The self-test must run real analysis on all five samples and output correct pass/fail lines. Rationale: explicit requirement; hardcoded results would defeat the demo.

NFR-22 — External link safety (explicit) The India Cyber Crime Portal link must open in a new tab with rel="noopener noreferrer". Rationale: explicit constraint and reference directive.

10. Tech Stack

• Markup: HTML5, in one self-contained file.
• Styling: CSS inside a single <style> block, using CSS custom properties for the light and dark themes and prefers-color-scheme for the switch. No CSS frameworks.
• Behaviour: Vanilla JavaScript inside a single <script> block. No frameworks, no libraries, no build step.
• Fonts: System font fallback stacks only — headings "Bricolage Grotesque", Arial, system-ui; body "IBM Plex Sans", system-ui; evidence text "IBM Plex Mono", ui-monospace, monospace. No font files are fetched.
• Storage: localStorage is optional and, if used, wrapped in try/catch. No database.
• Network: None. No backend, API, wallet, blockchain, or external request. The only outbound link is the India Cyber Crime Portal reference in the Next Steps checklist, which the user may choose to open.
• Deployment: None required. The file is opened directly in a browser.

11. Assumptions and Constraints

Assumptions

• A-01 (required_inference) — The user has a modern browser capable of running vanilla JavaScript and CSS custom properties. No specific browser is mandated by the source.
• A-02 (required_inference) — The five sample texts are the canonical demonstration inputs and are used verbatim by both the sample buttons and the self-test.
• A-03 (required_inference) — The rule weights are tuned by the implementer so that the five samples land on their target levels; the exact per-rule weights are an implementation detail constrained only by the 2–15 range and the target outcomes.
• A-04 (required_inference) — The "strongest family" for the scam type card is determined from the matched rules' families, with the highest-weight matched family taking precedence.
• A-05 (required_inference) — The compounded yearly figure is computed from the detected percentage and its stated period, using the standard compounding formula for that period.

Constraints

• C-01 (explicit) — ONE self-contained HTML file; HTML + CSS in <style> + vanilla JS in <script>.
• C-02 (explicit) — No frameworks, libraries, backend, API, database, wallet, blockchain, or external requests.
• C-03 (explicit) — Must work fully offline.
• C-04 (explicit) — Sample/test data only; never handle real Bitcoin, keys, or payments.
• C-05 (explicit) — Never use innerHTML with user text; use textContent / createElement / appendChild.
• C-06 (explicit) — No eval or Function.
• C-07 (explicit) — Safe regex only: no nested quantifiers; bounded wildcards like [\s\S]{0,60}.
• C-08 (explicit) — Ignore negations: "Never share your seed phrase" and "Do not send Bitcoin" must NOT trigger rules.
• C-09 (explicit) — No neon, glow gradients, glassmorphism, emoji icons, or generic SaaS/crypto-dashboard look.
• C-10 (explicit) — Simple CSS shield mark, no emoji logo.
• C-11 (explicit) — No horizontal scroll at 320/360/390px, tablet, or desktop.
• C-12 (explicit) — Disable all motion for prefers-reduced-motion.
• C-13 (explicit) — Never show raw errors; wrap analysis in try/catch.
• C-14 (explicit) — Practice mode must have exactly 6 scenarios.
• C-15 (explicit) — Rule engine must contain 18–20 rules.
• C-16 (explicit) — Textarea max 5000 characters.
• C-17 (explicit) — India Cyber Crime Portal link must open in a new tab with rel="noopener noreferrer".
• C-18 (explicit) — No console errors.
• C-19 (explicit) — The generic indigo/blue-on-white SaaS template is forbidden for this project; the only saturated colour is the deep red #B0121F (light) / #C4162A (dark).
• C-20 (explicit) — Cards are flat, hairline-bordered evidence sheets with no hover lift; corners stay at 2px or less; no pills or large soft radii.
• C-21 (explicit) — No bouncy, springy, or decorative motion beyond the single 320ms verdict entrance; the stamp is never animated or rotated after load; no parallax, marquee, or scroll-linked effect.
• C-22 (explicit) — Readable text and controls stay whole at every viewport; nothing covers or crops them.

12. Glossary

• BITSHIELD — The product name for this Bitcoin Scam Risk Detector, delivered as the project bitshield-3.
• Evidence desk — The overall visual and structural metaphor: a pale blue-grey workspace on which the pasted message is laid out as a filed document with numbered sections, ruled hairlines, taped labels, and a stamped verdict.
• Evidence sheet — The near-white card on which the original message is rendered in monospace, with matched phrases taped.
• Evidence tape — The 1px deep-red box with a 2px radius and a small red tick on the left edge that wraps a matched phrase in the evidence sheet, carrying a small all-caps label with the rule id.
• Rule — One entry in the local JavaScript rule array, carrying id, label, weight, regex, explanation, tip, family, and stage.
• Rule engine — The local, offline evaluator that applies all 18–20 rules to the submitted message and returns the matched set.
• Weight — The integer contribution (2–15) a matched rule adds to the sum.
• Sum — The total of all matched rule weights, plus the +12 urgency+payment bonus when it applies.
• Score — round(100 x (1 - e^(-sum/45))), capped at 100.
• Risk level — One of LOW (0–24), MEDIUM (25–47), HIGH (48–71), or CRITICAL (72–100).
• Urgency+payment bonus — The +12 addition to the sum applied when both an urgency rule and a payment rule match.
• Finding — One entry in "Warning Signs Detected", carrying severity, rule name, matched evidence, why risky, and what to check.
• Family — The scam category a rule belongs to: Investment, Giveaway, Impersonation, Credential Theft, Phishing, Pressure, Advance Fee, Recovery, Device Takeover, or Payment.
• Scam type card — The card naming the strongest matched family with its "How it works" description and the educational-classification note.
• Stage — One of HOOK, TRUST, PRESSURE, PAYMENT, EXIT; each rule carries a stage, and the stage tracker marks the stages present in the matched set.
• Stage tracker — The transit-line rendering of HOOK > TRUST > PRESSURE > PAYMENT > EXIT with active stops filled.
• Reality check — The detection of an "X% daily/weekly/monthly" claim and the computation of its compounded yearly return, with the limitation note.
• Checked and clear — The list of rules that did not match, each with a check mark, accompanied by the note that no matched rule is not proof that a message is legitimate.
• Stamp — The deep-red double-ruled rectangle rotated -3.2deg carrying the risk level and the score, printed over the corner of the evidence sheet.
• Self-test — The RUN SELF-TEST control that really runs the analyzer on all five samples and reports per-sample PASS/FAIL lines and a summary count.
• Practice mode — The six-scenario exercise with SCAM and SAFE buttons, feedback, and explanations.
• Negation handling — The rule-engine behaviour that prevents "Never share your seed phrase" and "Do not send Bitcoin" from triggering any rule.