From d12bde213355f10e43ae2218b6d4e4b2966044ef Mon Sep 17 00:00:00 2001 From: Anthony Hou Date: Sat, 29 Aug 2026 21:49:05 +0800 Subject: [PATCH 1/5] docs: add UST.space ratings extension guide --- .../ust-space-ratings-extension.mdx | 121 ++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx diff --git a/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx b/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx new file mode 100644 index 0000000..eb78582 --- /dev/null +++ b/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx @@ -0,0 +1,121 @@ +--- +sidebar_position: 4 +title: UST.space ratings extension +description: Install the Chrome extension that retrieves, displays, filters, and saves UST.space course ratings in Timetable Planner. +--- + +# UST.space ratings extension + +The **UST.space Ratings for USThing** Chrome extension retrieves aggregate course ratings from [UST.space](https://ust.space/) and sends them to [Timetable Planner](https://app.usthing.xyz/timetable-planner). Timetable Planner displays the ratings beside matching courses and saves successful results to your USThing account. + +The extension currently installs from source as an unpacked Chrome extension. It requires Chrome 102 or later. + +## Set up the extension + +### 1. Build the extension + +Install [Git](https://git-scm.com/) and [Bun](https://bun.sh/docs/installation), then run: + +```bash +git clone https://github.com/USThing/web-dashboard.git +cd web-dashboard +bun install +bun run extension:build +``` + +The build creates `background.js` and `content.js` under `extension/ustspace-ratings/dist`. + +If you already have the repository, update it before rebuilding: + +```bash +git pull +bun install +bun run extension:build +``` + +### 2. Load it in Chrome + +1. Open `chrome://extensions`. +2. Turn on **Developer mode**. +3. Select **Load unpacked**. +4. Choose the `web-dashboard/extension/ustspace-ratings` folder. Select the folder that contains `manifest.json`, not its `dist` subfolder. +5. Confirm that **UST.space Ratings for USThing** is enabled. + + + +After rebuilding or pulling an update, return to `chrome://extensions`, select **Reload** on the extension card, and reload Timetable Planner. + +### 3. Sign in and verify the connection + +1. Sign in to [UST.space](https://ust.space/login). +2. Sign in to USThing and open [Timetable Planner](https://app.usthing.xyz/timetable-planner). +3. Reload the planner if it was already open when you enabled the extension. +4. Search for a course. Rating badges appear beside a course after its rating is retrieved. + + + +## Understand the rating badges + +A rated course shows four letter-grade badges in this order: + +| Position | Metric | +| --- | --- | +| 1 | Content | +| 2 | Teaching | +| 3 | Grading | +| 4 | Workload | + +Hover over a badge to see the metric name, numeric aggregate score, and letter grade. A course that exists on UST.space but has no reviews shows **No reviews** instead. + +Ratings can appear in collapsed search results, expanded section-combination results, and Course Details. Select **View on UST.Space** in Course Details to open the source review page. + +## How retrieval and saving work + +The extension runs only on supported USThing Timetable Planner pages. It retrieves ratings automatically for course results that are currently shown and when you open Course Details. + +- **Search results:** after a result has been retrieved and acknowledged by the planner, the extension waits seven days before requesting that course again for the same USThing site. +- **Course Details:** each distinct opening requests the course rating and bypasses the seven-day search interval. +- **Saving:** rated and confirmed no-review results appear immediately, then Timetable Planner saves them to your authenticated USThing account. +- **Fallback:** saved ratings remain visible when the extension is disabled, UST.space cannot be reached, or its session is unavailable. + +The seven-day record is scoped to the USThing site and course, and is shared by USThing users in the same Chrome profile. + +## Filter courses by rating + +1. Search for courses in Timetable Planner. +2. Select **Filter by rating** above the results. +3. Choose a minimum letter grade for any combination of **Content**, **Teaching**, **Grading**, and **Workload**. +4. Select **Include unrated courses** if courses confirmed to have no reviews should remain visible. +5. Select **Apply**. + +A rated course must meet every enabled minimum. Courses whose rating has not been retrieved remain visible so a temporary extension or network problem does not hide possible results. + + + +## Data and permissions + +The extension requests access to `https://ust.space/*` so its background worker can retrieve course reviews using the UST.space session already active in Chrome. It does not request Chrome cookie permission. + +Chrome extension storage contains only the last acknowledged search-fetch time for each USThing site and course. It does not retain rating payloads. Timetable Planner saves usable rating summaries and their source responses in user-scoped USThing storage. + +## Troubleshooting + +### UST.space Access Required appears + +Select **Sign in** in the planner warning, complete the UST.space sign-in, then return focus to the Timetable Planner tab. The extension retries after the tab regains focus. + + + +If the warning remains, check whether Chrome is blocking the extension's access to UST.space or preventing the UST.space session from being sent with cross-site requests. + +### No rating badges appear + +- Confirm that the extension is enabled at `chrome://extensions`. +- Select **Reload** on its extension card, then reload Timetable Planner. +- Rebuild with `bun run extension:build` and confirm that `extension/ustspace-ratings/dist` contains both generated JavaScript files. +- Confirm that you loaded the `extension/ustspace-ratings` folder rather than `dist`. +- Sign in to UST.space and return to the planner tab. + +### A search result shows an older saved rating + +Search retrieval is limited to once every seven days after a successful acknowledgment. Open the course's Course Details to request a fresh result without waiting for that interval. From d190029ba9b007be85d9e37dabd6271d6f173de3 Mon Sep 17 00:00:00 2001 From: Anthony Hou Date: Sat, 29 Aug 2026 21:49:23 +0800 Subject: [PATCH 2/5] docs: link UST.space ratings extension guide --- docs/dashboard/timetable-planner/overview.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/dashboard/timetable-planner/overview.mdx b/docs/dashboard/timetable-planner/overview.mdx index b9430f4..3b67e05 100644 --- a/docs/dashboard/timetable-planner/overview.mdx +++ b/docs/dashboard/timetable-planner/overview.mdx @@ -66,3 +66,4 @@ The unit total is calculated once per course, even when the course has multiple - [Search and filtering](/docs/dashboard/timetable-planner/search-and-filtering) - [Study Planner integration](/docs/dashboard/timetable-planner/study-planner-integration) +- [UST.space ratings extension](/docs/dashboard/timetable-planner/ust-space-ratings-extension) From 6c7824ea552c92dc24ecd0a27abd9c64935f6924 Mon Sep 17 00:00:00 2001 From: Anthony Hou Date: Sat, 29 Aug 2026 21:49:53 +0800 Subject: [PATCH 3/5] docs: use MDX-compatible screenshot placeholders --- .../timetable-planner/ust-space-ratings-extension.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx b/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx index eb78582..6203746 100644 --- a/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx +++ b/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx @@ -41,7 +41,7 @@ bun run extension:build 4. Choose the `web-dashboard/extension/ustspace-ratings` folder. Select the folder that contains `manifest.json`, not its `dist` subfolder. 5. Confirm that **UST.space Ratings for USThing** is enabled. - +{/* Screenshot placeholder: Chrome Extensions page with Developer mode, Load unpacked, and the enabled extension. Suggested file: ./img/ust-space-ratings-load-unpacked.png */} After rebuilding or pulling an update, return to `chrome://extensions`, select **Reload** on the extension card, and reload Timetable Planner. @@ -52,7 +52,7 @@ After rebuilding or pulling an update, return to `chrome://extensions`, select * 3. Reload the planner if it was already open when you enabled the extension. 4. Search for a course. Rating badges appear beside a course after its rating is retrieved. - +{/* Screenshot placeholder: Timetable Planner search results showing UST.space rating badges. Suggested file: ./img/ust-space-ratings-course-badges.png */} ## Understand the rating badges @@ -90,7 +90,7 @@ The seven-day record is scoped to the USThing site and course, and is shared by A rated course must meet every enabled minimum. Courses whose rating has not been retrieved remain visible so a temporary extension or network problem does not hide possible results. - +{/* Screenshot placeholder: Filter by UST.space rating dialog with metric minima and Include unrated courses. Suggested file: ./img/ust-space-ratings-filter.png */} ## Data and permissions @@ -104,7 +104,7 @@ Chrome extension storage contains only the last acknowledged search-fetch time f Select **Sign in** in the planner warning, complete the UST.space sign-in, then return focus to the Timetable Planner tab. The extension retries after the tab regains focus. - +{/* Screenshot placeholder: Timetable Planner UST.space Access Required warning and Sign in link. Suggested file: ./img/ust-space-ratings-access-required.png */} If the warning remains, check whether Chrome is blocking the extension's access to UST.space or preventing the UST.space session from being sent with cross-site requests. From 25f0a5e149b11e406ce874b6d92ae4b71c6eab8f Mon Sep 17 00:00:00 2001 From: Anthony Hou Date: Sat, 29 Aug 2026 21:54:33 +0800 Subject: [PATCH 4/5] docs: switch extension setup to ZIP download --- .../ust-space-ratings-extension.mdx | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx b/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx index 6203746..98ebc82 100644 --- a/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx +++ b/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx @@ -8,42 +8,39 @@ description: Install the Chrome extension that retrieves, displays, filters, and The **UST.space Ratings for USThing** Chrome extension retrieves aggregate course ratings from [UST.space](https://ust.space/) and sends them to [Timetable Planner](https://app.usthing.xyz/timetable-planner). Timetable Planner displays the ratings beside matching courses and saves successful results to your USThing account. -The extension currently installs from source as an unpacked Chrome extension. It requires Chrome 102 or later. +:::warning Unsupported extension +No official support is provided for this extension. Install and use it at your own risk. Changes to Chrome, USThing, or UST.space may cause it to stop working without notice. +::: + +The extension requires Chrome 102 or later and installs from a downloadable ZIP file as an unpacked extension. ## Set up the extension -### 1. Build the extension +### 1. Download and extract the ZIP -Install [Git](https://git-scm.com/) and [Bun](https://bun.sh/docs/installation), then run: +[Download the UST.space Ratings extension ZIP](#) -```bash -git clone https://github.com/USThing/web-dashboard.git -cd web-dashboard -bun install -bun run extension:build -``` +{/* Download placeholder: Replace # with the published extension ZIP URL. */} -The build creates `background.js` and `content.js` under `extension/ustspace-ratings/dist`. +After downloading: -If you already have the repository, update it before rebuilding: +1. Extract the ZIP file. +2. Move the extracted extension folder to a permanent location on your computer. +3. Open the folder and confirm that it contains `manifest.json` and a `dist` folder. -```bash -git pull -bun install -bun run extension:build -``` +Do not delete or move this folder after loading it in Chrome. Chrome uses the extracted files to run the unpacked extension. ### 2. Load it in Chrome 1. Open `chrome://extensions`. 2. Turn on **Developer mode**. 3. Select **Load unpacked**. -4. Choose the `web-dashboard/extension/ustspace-ratings` folder. Select the folder that contains `manifest.json`, not its `dist` subfolder. +4. Choose the extracted folder that contains `manifest.json`. Do not choose the ZIP file or the `dist` subfolder. 5. Confirm that **UST.space Ratings for USThing** is enabled. {/* Screenshot placeholder: Chrome Extensions page with Developer mode, Load unpacked, and the enabled extension. Suggested file: ./img/ust-space-ratings-load-unpacked.png */} -After rebuilding or pulling an update, return to `chrome://extensions`, select **Reload** on the extension card, and reload Timetable Planner. +When a new extension build is available, download and extract the new ZIP, replace the files in your existing extension folder, select **Reload** on the extension card, and reload Timetable Planner. ### 3. Sign in and verify the connection @@ -100,6 +97,8 @@ Chrome extension storage contains only the last acknowledged search-fetch time f ## Troubleshooting +Remember that this extension is provided without official support. The following checks may help, but assistance and fixes are not guaranteed. + ### UST.space Access Required appears Select **Sign in** in the planner warning, complete the UST.space sign-in, then return focus to the Timetable Planner tab. The extension retries after the tab regains focus. @@ -112,8 +111,9 @@ If the warning remains, check whether Chrome is blocking the extension's access - Confirm that the extension is enabled at `chrome://extensions`. - Select **Reload** on its extension card, then reload Timetable Planner. -- Rebuild with `bun run extension:build` and confirm that `extension/ustspace-ratings/dist` contains both generated JavaScript files. -- Confirm that you loaded the `extension/ustspace-ratings` folder rather than `dist`. +- Confirm that the downloaded ZIP was fully extracted. +- Confirm that the loaded folder contains `manifest.json` and generated files under `dist`. +- Confirm that you loaded the extracted extension folder rather than the ZIP file or `dist`. - Sign in to UST.space and return to the planner tab. ### A search result shows an older saved rating From a233bf09e1e9bc7d6d9ee1f8fe7623720d602e3f Mon Sep 17 00:00:00 2001 From: Anthony Hou Date: Sat, 29 Aug 2026 21:58:02 +0800 Subject: [PATCH 5/5] docs: explain cross-device rating sync --- .../timetable-planner/ust-space-ratings-extension.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx b/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx index 98ebc82..a82121e 100644 --- a/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx +++ b/docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx @@ -70,6 +70,10 @@ Ratings can appear in collapsed search results, expanded section-combination res The extension runs only on supported USThing Timetable Planner pages. It retrieves ratings automatically for course results that are currently shown and when you open Course Details. +:::info Synced across your devices +Fetched ratings are stored by Timetable Planner in your USThing account. They are synchronized to other devices where you sign in with the same account. The extension is only required on a device that needs to retrieve new or refreshed ratings. +::: + - **Search results:** after a result has been retrieved and acknowledged by the planner, the extension waits seven days before requesting that course again for the same USThing site. - **Course Details:** each distinct opening requests the course rating and bypasses the seven-day search interval. - **Saving:** rated and confirmed no-review results appear immediately, then Timetable Planner saves them to your authenticated USThing account.