✦

StarStruck

User Guide — focus, made visible.

Version: 1.0
Last updated: May 2026

Tip: Once your screenshots are dropped into docs/screenshots/, open this file in your browser and use Ctrl+P → "Save as PDF" to generate StarStruck-User-Guide.pdf.

Welcome to StarStruck
Creating an account
Signing in & out
The dashboard
Studying — Timed Focus
Studying — Instant Study
Studying — QuizForge
The sound player
Wrapping up a session
Stats, Analytics & Reports
Settings
The referral program
Deleting your account
Mobile experience
For administrators
Frequently asked questions

Welcome to StarStruck

StarStruck is a focus-tracking app for students who study deliberately. You start a session, you do the work, you wrap up — and the app turns that into a streak, a heatmap, and a long-running picture of how you actually spend your study hours.

Who it's for

Students who want a quiet, distraction-free study timer.
Self-learners who want a long-term record of what they studied and when.
Anyone who wants to see their habits instead of guess at them.

What you get

Feature	What it does
Timed Focus	Fixed-duration countdown sessions.
Instant Study	Open-ended stopwatch sessions — end whenever.
Sound player	Loop your own upload list of focus sounds.
Heatmap & stats	Year-at-a-glance view of every studied day.
Analytics & report	Charts of when, how long, and how well you study.
Referrals	Invite friends; earn points when they're real users.

Creating an account

StarStruck doesn't require email verification. Pick a unique username, fill in the form, and you can sign in straight away.

Filling out the form

Username — 3–20 characters, letters/numbers/underscore. Permanent; choose carefully.
Display name — what we'll greet you with. Up to 40 characters.
Email — used for sign-in and password recovery.
Password — minimum 8 characters.
Study course — what you're studying (e.g. Computer Science, Medicine, Self-study). Optional but useful.
Avatar — pick an emoji or upload an image.
Referral code — paste a friend's code so they earn 10 points when you've studied 3+ hours. Optional.

Picking an avatar

The avatar picker has two tabs:

Insert screenshot: screenshots/03-avatar-emoji.png
The avatar picker with the emoji grid open.

Figure 3 — Emoji avatar grid.

Insert screenshot: screenshots/04-avatar-upload.png
The avatar picker with the upload tab open.

Figure 4 — Upload a PNG/JPG (max 500 KB).

What happens after sign-up? For your safety, you are not auto-signed-in. You'll be taken to the sign-in page with a confirmation toast — sign in with the credentials you just used to start studying.

Signing in & out

Sign in

You can sign in with either your email or your username.
If you stay on this device, the session is remembered until you sign out.

Forgot your password?

Click "Forgot password?" on the sign-in page. You'll be taken to a small form where you enter your email and we email you a reset link.

Sign out

Click your avatar in the top-right corner, scroll the Settings page to the bottom, and use the Sign out button. Or just close your browser — you'll stay signed in next time only if you used the same device.

The dashboard

The dashboard is your home screen. It shows what you've studied today, your streak, and a year-long heatmap of every studied day.

What you'll see

Today's totals — minutes studied, sessions started, interruptions.
Streak — consecutive days with at least one completed session.
Heatmap — each cell is one day; darker = more study time. Hover to see exact minutes.
Quick actions — jump straight into a Timed or Instant session.

If you don't have data yet: Empty analytics show the message "Need to study for more days to display stats." No fake numbers — your real data builds up as you use the app.

Studying — Timed Focus

Timed Focus is the classic study-block mode. You pick a duration, the timer counts down, and when it hits zero you're prompted to wrap up.

Starting a session

Open Timed Focus from the sidebar.
Pick a duration (or type in a custom value in minutes).
Optional: enter what you'll be studying in the topic field.
Click Start. The countdown begins immediately.

Figure 9 — A running Timed Focus session.

Pausing, resuming, and ending

Pause — stops the clock but keeps the session alive. Resume picks up exactly where you stopped.
End early — stops the session before the timer expires. You'll still be asked to wrap up.
Timer expires — the wrap-up form opens automatically. If you're on another page, it pops up there too.

One session at a time: Sessions are coordinated across browser tabs. If you try to start a second session in a different tab while one is running, the new tab will tell you a session is already in progress.

Studying — Instant Study

Instant Study is for open-ended work: no preset duration, no countdown. It runs as a stopwatch until you stop it.

When to use it

You don't know how long the work will take.
You're sitting down to study and don't want the pressure of a deadline.
You want a clean record of actual minutes spent.

How it counts

The timer uses real timestamps (the moment you start, the moment you end). It does not drift the way a tab-throttled JavaScript timer would — close your laptop for an hour, come back, and the elapsed time is still correct.

Studying — QuizForge

QuizForge is the third way to study inside StarStruck: a multiple-choice quiz engine over a shared bank of questions, organized by subject. Pick a subject, choose how many questions you want, and either get instant feedback as you go (practice mode) or hold all of it until the end (exam mode).

Picking a subject

Open QuizForge from the sidebar. Each card is a subject the admin has loaded into the bank. Click one to configure a quiz on it. If you don't see any subjects, the bank is empty — an admin needs to add a few from the admin panel (see For administrators).

Configuring a quiz

Number of questions — 5, 10, 15, or 20.
Mode — Practice reveals the correct answer and explanation as soon as you pick. Exam stays quiet until you submit, so you can change your mind on any question.
Timer — optional total countdown. When it hits zero the quiz auto-submits.
Shuffle answer choices — randomizes the A/B/C/D order per question. The correct option stays correct — only its label moves.
Hide already-correct — pulls only questions you have not yet answered correctly in any past attempt. Useful for drilling gaps.

Taking the quiz

The play view shows one question at a time with a side palette of every question's status: answered, skipped, bookmarked, or current. Click any palette cell to jump there. The ★ Bookmark button on every question saves it for later review under Bookmarks.

You can refresh. The quiz state survives an accidental page refresh — it's stored per tab, so closing the tab discards it but a refresh restores the exact question, your answers so far, and your bookmarks.

Submitting and reviewing

On the last question, Next → becomes Submit quiz. Submission writes your answers, score, and elapsed time, then drops you on a results page with:

Top-line score, accuracy, incorrect/skipped counts, and time taken.
A per-question review — your selection, the correct answer, the explanation, and a bookmark toggle.
Quick actions: take another quiz on the same subject, or jump to a different subject.

History and bookmarks

From the QuizForge home, the History shortcut shows every past attempt with date, subject, score, accuracy, and time. Each row links to the same per-question review. Bookmarks shows every question you starred, grouped by subject, with the correct answer highlighted — handy as a flashcard pile for revision.

Where quiz analytics live

Quiz analytics aren't a separate route — they live as the QuizForge tab inside Analytics on the sidebar. Switch tabs to see accuracy per subject, your strongest and weakest areas, and a short list of recent attempts.

Quizzes don't count toward your day streak. Streaks are a study-time metric, not a quiz-attempts metric. Taking a quiz on a day with zero timed/instant study time will not preserve the streak.

The sound player

Optional background sounds — rain, café noise, lo-fi, whatever you've uploaded — play in a loop while you study.

Opening the popup

On any timer view, click the small speaker icon to open the sound popup. From here you can:

Play / pause — toggles the currently selected track.
Previous / next — cycles through your uploaded sounds.
Volume slider — adjusts loudness.
Loop — when enabled, the current sound restarts automatically.

No sounds yet? Head to Settings → Sounds to upload an MP3 or WAV. The popup will show "No sounds available — upload one in Settings → Sounds" until you do.

Wrapping up a session

Every completed or ended-early session opens a wrap-up form. This is the one chore the app asks of you — answer it honestly and your analytics stay meaningful.

What you'll fill in

Field	Why it matters
Study topic	What you were working on. Shows up in your stats and history.
Satisfaction	Satisfactory, unsatisfactory, or interrupted. Drives the satisfaction analytics.
Special note	Optional. Use it to flag anything memorable about this session.

Tweet on save

When you click Save session, a new tab opens with a pre-filled tweet so you can share what you just studied. The tweet reads:

"Star Struck! I have just finished a (duration) study session on the StarStruck Study app @StarStruckStudy. Join me at https://www.starstruckstudy.xyz"

The duration is filled in based on the session you just wrapped up (e.g. 30-minute, 1-hour, 1.5-hour, or 75-minute). You're free to edit the tweet before posting, or simply close the tab if you don't want to share that particular session.

Figure 12.1 — The pre-filled tweet that opens on save.

Pop-up blocker: Modern browsers usually allow this tab because it opens directly from your click on "Save session." If your browser still blocks it, allow pop-ups for the site once and the tab will appear from the next save onwards. To turn the feature off entirely, see Settings → Sharing in the next chapter.

Stats, Analytics & Reports

Three views slice the same data different ways: Stats for the numbers, Analytics for the charts, and Report for a shareable summary.

Stats

Total minutes studied (lifetime, this week, today).
Total sessions and average length.
Longest session and current streak.
Interruptions count.

Analytics

Minutes studied per day — bar chart.
Sessions by satisfaction — pie / doughnut chart.
Time-of-day distribution — when do you actually focus best?

Report

The report view assembles a printable snapshot of your activity — useful to download, share with a study coach, or keep for your own records.

Settings

Open Settings by clicking your avatar in the top-right of any app page. Everything you can change about your account lives here.

Profile

Insert screenshot: screenshots/17-settings-profile.png
The Profile section of Settings.

Figure 16 — Edit profile.

Change display name, course, or avatar.
Update your email or password.
Note: username cannot be changed after registration.

Theme

Toggle between light and dark mode. Your choice is remembered per account and applied everywhere — including the admin panel.

Sounds

Upload MP3 or WAV files.
Name and reorder your sounds.
Mark one as the default (auto-loaded when you open a timer view).
Delete sounds you don't use anymore.

Sharing — Tweet on save

Inside the Profile tab of Settings you'll find a Sharing card with a single toggle: Tweet on save. It controls whether saving a session opens the pre-filled X/Twitter tab described in Chapter 8.

On (the default) — every saved session opens a new tab with the pre-filled tweet. You can still close the tab without posting.
Off — sessions save silently. Nothing opens, nothing posts.

The toggle saves the moment you flip it. A toast at the bottom of the screen confirms the change ("Will share saved sessions" or "Sharing turned off"). The preference is stored on your account, so it follows you to any device you sign in on.

Privacy: Turning the toggle off means StarStruck never opens X for you. Nothing is posted automatically — even with the toggle on, you always have to click "Post" inside the X tab yourself.

The referral program

Invite friends to StarStruck and earn points — but only when they actually use the app. No fake invites, no points for nothing.

Figure 18 — Your referral code and points.

How it works

You have a unique referral code (visible in Settings → Referrals).
Share it with friends. They paste it into the "Referral code" field on sign-up.
Once your referred friend accumulates 3 hours of total study time, you earn 10 points.

Anti-abuse: No reward is granted if the referred account is deleted, and no duplicate rewards can be earned for the same referral. The 3-hour threshold prevents one-and-done sign-ups from gaming the system.

Deleting your account

StarStruck supports a deliberate, recoverable account deletion. Nothing is hard-erased the moment you click — you have 30 days to change your mind by signing back in.

Figure 19 — Delete-my-account confirmation.

What we ask for

Your current password.
The exact phrase delete my account typed in lowercase.

What happens next

Your account is soft-deleted — you can no longer sign in, but the data isn't erased.
After 30 days, the account is permanently purged.
Within that window, contacting the team can restore your account.

Mobile experience

StarStruck is built to look right on a phone. The sidebar becomes a drawer, modals become bottom sheets, and tap targets are sized for fingers.

Differences on small screens

Sidebar — hidden by default; tap the menu icon (top-left) to open. Tap outside to dismiss.
Modals — anchored to the bottom of the screen for thumb-reach.
Tables — scroll horizontally inside their container so columns don't squash.
Sound popup — sized to fit any phone, with a dimmed backdrop.

For administrators

The admin panel is a separate page, gated by an is_admin flag on your profile, that lets you read and edit everything across all accounts.

Opening the panel

Press Ctrl+A (or ⌘+A on macOS) anywhere inside the app while signed in as an admin. The panel opens in a new tab. Non-admins do not have the shortcut bound.

Promoting an admin: Run the SQL update public.profiles set is_admin = true where id = '<uuid>'; once in the Supabase SQL editor. After a hard refresh of app.html, the shortcut activates.

Overview

Users

Search — by username, display name, or email.
Edit — change name, email, course, referral points.
Promote / Demote — toggle the is_admin flag.
Inspect — opens the app as that user (see below).
Delete / Restore — soft-delete or undo a soft-delete.

Sessions, Daily stats, Sounds, Referrals

Each of these tabs is a CRUD table for the matching database table.

QuizForge — Subjects, Questions, and Import

Three additional admin tabs manage the QuizForge content bank.

Subjects — create / edit / archive / delete the top-level categories that show up on the user-facing subject grid. Slugs are immutable after create so existing references stay valid.
Questions — full CRUD on the bank, with a per-subject filter and a 5-option modal (radio selects the correct answer).
Import — bulk-load questions from a plain-text format. Paste or upload a file, click Parse to preview, then Import valid rows. The expected block shape per question is:
```
QUESTION 1
Question: What is the powerhouse of the cell?
Options:
A. Nucleus
*B. Mitochondrion
C. Ribosome
D. Golgi apparatus
Explanation: Mitochondria produce ATP via oxidative phosphorylation.
```
A leading * marks the correct option. Blocks are separated by QUESTION N markers (or ===== QUESTION N ===== headers). Parser errors are listed in the preview so you can fix the source and re-parse without partial inserts.

Inspect-as-user mode

Click Inspect on any user row. A new tab opens at app.html?inspect=<uuid>, the dashboard and analytics are populated with that user's data, and a yellow banner reminds you you're in inspect mode. Close the tab to leave inspect mode.

Read-only by convention: The banner is your guard rail. Don't start sessions or change settings while inspecting — those actions would land on the inspected account.

Frequently asked questions

Why isn't there email verification?

By design — we want zero friction between sign-up and your first session. Password resets still use email so you can recover an account.

Will my timer drift if I close my laptop?

No. Sessions store the start timestamp and compute elapsed time on every tick from Date.now() — sleep, throttle, and tab inactivity have no effect on accuracy.

Can I have two sessions running in two tabs?

No. A BroadcastChannel coordinates tabs so only one session is active at a time per account. The second tab will tell you a session is already running.

I deleted my account — can I get it back?

Yes, within 30 days. Sign back in or contact the team. After 30 days the account is purged permanently.

My referred friend signed up but I didn't earn points.

Points are awarded only after the referred user accumulates at least 3 hours of total study time. If they hit that threshold and you still didn't see points, check that they used your referral code at sign-up (it cannot be added after the fact).

The sound popup says "No sounds available."

You haven't uploaded any yet. Open Settings → Sounds and upload an MP3 or WAV.

An X/Twitter tab opens every time I save a session — how do I stop it?

That's the Tweet on save feature. Go to Settings → Profile, scroll to the Sharing card, and switch Tweet on save off. The change applies from the next saved session onwards.

I had Tweet on save turned on, but no tab opens when I save.

Your browser is probably blocking pop-ups for the site. Look for a small blocked-pop-up indicator in the address bar, click it, and choose Always allow pop-ups from starstruckstudy.xyz. The next save will open the tweet tab normally. If you'd rather not whitelist the site, just turn the toggle off in Settings → Sharing.

Ctrl+A doesn't open the admin panel.

Either you're not signed in as an admin, or the page predates the promotion. Verify with select is_admin from profiles where id = '<your uuid>'; in Supabase; if it returns false, run the promotion SQL and hard-refresh.

Table of contents

Welcome to StarStruck

Who it's for

What you get

Creating an account

Filling out the form

Picking an avatar

Signing in & out

Sign in

Forgot your password?

Sign out

The dashboard

What you'll see

Studying — Timed Focus

Starting a session

Pausing, resuming, and ending

Studying — Instant Study

When to use it

How it counts

Studying — QuizForge

Picking a subject

Configuring a quiz

Taking the quiz

Submitting and reviewing

History and bookmarks

Where quiz analytics live

The sound player

Opening the popup

Wrapping up a session

What you'll fill in

Tweet on save

Stats, Analytics & Reports

Stats

Analytics

Report

Settings

Profile

Theme

Sounds

Sharing — Tweet on save

The referral program

How it works

Deleting your account

What we ask for

What happens next

Mobile experience

Differences on small screens

For administrators

Opening the panel

Overview

Users

Sessions, Daily stats, Sounds, Referrals

QuizForge — Subjects, Questions, and Import

Inspect-as-user mode

Frequently asked questions

Why isn't there email verification?

Will my timer drift if I close my laptop?

Can I have two sessions running in two tabs?

I deleted my account — can I get it back?

My referred friend signed up but I didn't earn points.

The sound popup says "No sounds available."

An X/Twitter tab opens every time I save a session — how do I stop it?

I had Tweet on save turned on, but no tab opens when I save.

Ctrl+A doesn't open the admin panel.