Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,17 +13,20 @@ jobs:
- name: Checkout
uses: actions/checkout@v6

- name: Setup pnpm
uses: pnpm/action-setup@v4

- name: Setup Node
uses: actions/setup-node@v6
with:
node-version: 22
cache: npm
cache: pnpm

- name: Install dependencies
run: npm ci
run: pnpm install --frozen-lockfile

- name: Install Playwright Chromium
run: npx playwright install --with-deps chromium
run: pnpm exec playwright install --with-deps chromium

- name: Run checks
run: xvfb-run -a npm run check
run: xvfb-run -a pnpm run check
11 changes: 7 additions & 4 deletions .github/workflows/release-please.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,16 +20,19 @@ jobs:
- uses: actions/checkout@v6
if: ${{ steps.release.outputs.release_created }}

- uses: pnpm/action-setup@v4
if: ${{ steps.release.outputs.release_created }}

- uses: actions/setup-node@v6
if: ${{ steps.release.outputs.release_created }}
with:
node-version: 22
cache: npm
cache: pnpm

- run: npm ci
- run: pnpm install --frozen-lockfile
if: ${{ steps.release.outputs.release_created }}

- run: npm run build
- run: pnpm run build
if: ${{ steps.release.outputs.release_created }}

- name: Package extension
Expand Down Expand Up @@ -59,4 +62,4 @@ jobs:
if: ${{ steps.release.outputs.release_created && steps.check_keys.outputs.present == 'true' }}
env:
SUBMIT_KEYS: ${{ secrets.SUBMIT_KEYS }}
run: npm run publish:chrome-web-store
run: pnpm run publish:chrome-web-store
2 changes: 1 addition & 1 deletion .prettierignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,5 @@ extension/content.js
extension/options.js
extension/chunks/
extension/manifest.json
package-lock.json
pnpm-lock.yaml
CHANGELOG.md
30 changes: 16 additions & 14 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,24 @@ This file provides guidance to coding agents when working with code in this repo

## Commands

This project uses **pnpm** (pinned via the `packageManager` field; run through Corepack). Do not use npm or yarn - the global pnpm config enforces a `minimumReleaseAge` supply-chain cooldown and pnpm blocks dependency build scripts by default (only the packages in `pnpm-workspace.yaml`'s `allowBuilds` are permitted, currently just `esbuild`).

```sh
npm ci # Install dependencies
npx playwright install --with-deps chromium # One-time: Playwright Chromium for e2e
npm run build # tsc --noEmit + esbuild bundle into extension/
npm test # Vitest (jsdom) - unit tests in test/
npx vitest run test/llm.test.ts # Run a single Vitest file
npx vitest run -t 'pattern' # Run tests matching a name
npm run test:e2e # Playwright (headed Chromium; needs a display)
npm run lint # ESLint
npm run format:check # Prettier check (use `npm run format` to write)
npm run check # format:check + lint + test + build + test:e2e
pnpm install # Install dependencies (use --frozen-lockfile in CI)
pnpm exec playwright install --with-deps chromium # One-time: Playwright Chromium for e2e
pnpm run build # tsc --noEmit + esbuild bundle into extension/
pnpm test # Vitest (jsdom) - unit tests in test/
pnpm exec vitest run test/llm.test.ts # Run a single Vitest file
pnpm exec vitest run -t 'pattern' # Run tests matching a name
pnpm run test:e2e # Playwright (headed Chromium; needs a display)
pnpm run lint # ESLint
pnpm run format:check # Prettier check (use `pnpm run format` to write)
pnpm run check # format:check + lint + test + build + test:e2e
```

`build:background` bundles `src/background.ts` as an ES module with code-splitting into `extension/` and `extension/chunks/`. `build:pages` bundles `src/content.ts` and `src/options.ts` as IIFE. All generated `extension/*.js` and `extension/chunks/` are git-ignored.

To load the unpacked extension: `npm run build`, then in `chrome://extensions` enable Developer mode and Load unpacked from `extension/`.
To load the unpacked extension: `pnpm run build`, then in `chrome://extensions` enable Developer mode and Load unpacked from `extension/`.

## Architecture

Expand All @@ -39,21 +41,21 @@ This is a Manifest V3 Chrome extension. There is no hosted backend - the browser

**Tests:** Vitest unit tests in `test/` use jsdom and cover each `src/` module by name. Playwright e2e in `e2e/extension.spec.ts` launches the built `extension/` directory in real Chromium.

**Releases:** release-please reads conventional commits on `main` and opens release PRs that bump `package.json`, `package-lock.json`, and `extension/manifest.json` together. `CHANGELOG.md` and `.release-please-manifest.json` are auto-generated - do not edit by hand. On release, CI zips `extension/` into `simplewords.zip`, attaches it to the GitHub Release, and (if the `SUBMIT_KEYS` secret is set) uploads via `scripts/chrome-web-store-publish.mjs`.
**Releases:** release-please reads conventional commits on `main` and opens release PRs that bump `package.json` and `extension/manifest.json` together (the version does not appear in `pnpm-lock.yaml`, so the lockfile is untouched). `CHANGELOG.md` and `.release-please-manifest.json` are auto-generated - do not edit by hand. On release, CI zips `extension/` into `simplewords.zip`, attaches it to the GitHub Release, and (if the `SUBMIT_KEYS` secret is set) uploads via `scripts/chrome-web-store-publish.mjs`.

## Marketing Video

The `marketing-video/` directory is a standalone HyperFrames project for the Simple Words marketing video.

From that directory, run `npm run dev` to preview, `npm run check` to lint, validate, and inspect, and `npm run render` to generate the MP4.
From that directory, run `pnpm run dev` to preview, `pnpm run check` to lint, validate, and inspect, and `pnpm run render` to generate the MP4.

The committed render is `marketing-video/simplewords-marketing.mp4`.

## Releases

Releases are managed by release-please from conventional commits on `main`.

Release PRs update `package.json`, `package-lock.json`, and `extension/manifest.json`.
Release PRs update `package.json` and `extension/manifest.json`.

When a release is created, GitHub Actions builds the extension, packages `extension/` as `simplewords.zip`, and attaches the zip to the GitHub Release.

Expand Down
25 changes: 14 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,11 +67,14 @@ https://chromewebstore.google.com/detail/simple-words/kmlhfcjpmhcoclpcghckibfkgp

**From Source**

This project uses [pnpm](https://pnpm.io) (enable it with `corepack enable`).
Do not use npm or yarn; pnpm keeps the release-age and dependency-build-script guardrails active for installs.

```sh
git clone https://github.com/kunchenguid/simplewords.git
cd simplewords
npm ci
npm run build
pnpm install
pnpm run build
```

Then open `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select the `extension/` directory.
Expand Down Expand Up @@ -148,17 +151,17 @@ There is no hosted Simple Words backend in the request path.
## Development

```sh
npm ci # Install dependencies
npx playwright install --with-deps chromium # Install Playwright Chromium
npm run build # Type-check and bundle the extension files
npm test # Run Vitest
npm run test:e2e # Run Playwright browser tests
npm run lint # Run ESLint
npm run format:check # Check formatting
npm run check # Run format, lint, Vitest, build, and browser tests
pnpm install # Install dependencies
pnpm exec playwright install --with-deps chromium # Install Playwright Chromium
pnpm run build # Type-check and bundle the extension files
pnpm test # Run Vitest
pnpm run test:e2e # Run Playwright browser tests
pnpm run lint # Run ESLint
pnpm run format:check # Check formatting
pnpm run check # Run format, lint, Vitest, build, and browser tests
```

`npm run test:e2e` launches the extension in headed Chromium, so it requires a graphical display.
`pnpm run test:e2e` launches the extension in headed Chromium, so it requires a graphical display.

The built files `extension/background.js`, `extension/content.js`, `extension/options.js`, and `extension/chunks/` are generated artifacts and are not tracked in Git.

Expand Down
2 changes: 1 addition & 1 deletion chrome-web-store-assets/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,4 +39,4 @@ ffmpeg -ss 21.100 -i ../marketing-video/simplewords-marketing.mp4 -frames:v 1 -v
From `chrome-web-store-assets/sources`, serve the files and open `render.html?file=<source-name>` with headless Chrome.
For example, `render.html?file=screenshot-01-reply-faster` renders `screenshot-01-reply-faster.svg`.

Export each upload PNG at its listed size with Chrome's `--screenshot` and `--window-size` flags, then run `npm test` to verify the dimensions and RGB color type.
Export each upload PNG at its listed size with Chrome's `--screenshot` and `--window-size` flags, then run `pnpm test` to verify the dimensions and RGB color type.
12 changes: 6 additions & 6 deletions marketing-video/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,18 @@ Skills encode patterns like `window.__timelines` registration, `data-*` attribut
## Commands

```bash
npm run dev # preview in browser (studio editor)
npm run check # lint + validate + inspect
npm run render # render to MP4
npm run publish # publish and get a shareable link
pnpm run dev # preview in browser (studio editor)
pnpm run check # lint + validate + inspect
pnpm run render # render to MP4
pnpm run publish # publish and get a shareable link
npx hyperframes docs <topic> # reference docs in terminal
```

## Project Structure

- `index.html` — main composition (root timeline)
- `assets/` — media files (video, audio, images)
- `simplewords-marketing.mp4` — rendered marketing video output from `npm run render`
- `simplewords-marketing.mp4` — rendered marketing video output from `pnpm run render`
- `meta.json` — project metadata (id, name)
- `transcript.json` — whisper word-level transcript (if generated)

Expand All @@ -33,7 +33,7 @@ npx hyperframes docs <topic> # reference docs in terminal
After creating or editing any `.html` composition, run the full check before considering the task complete:

```bash
npm run check
pnpm run check
```

Fix all errors before presenting the result.
Expand Down
12 changes: 6 additions & 6 deletions marketing-video/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,10 @@
## Commands

```bash
npm run dev # preview in browser (studio editor)
npm run check # lint + validate + inspect
npm run render # render to MP4
npm run publish # publish and get a shareable link
pnpm run dev # preview in browser (studio editor)
pnpm run check # lint + validate + inspect
pnpm run render # render to MP4
pnpm run publish # publish and get a shareable link
npx hyperframes lint --verbose # include info-level findings
npx hyperframes lint --json # machine-readable output for CI
npx hyperframes docs <topic> # reference docs in terminal
Expand All @@ -54,7 +54,7 @@ https://hyperframes.heygen.com/llms.txt

- `index.html` — main composition (root timeline)
- `assets/` - source media files used by the marketing video
- `simplewords-marketing.mp4` - rendered marketing video output from `npm run render`
- `simplewords-marketing.mp4` - rendered marketing video output from `pnpm run render`
- `meta.json` — project metadata (id, name)
- `transcript.json` — whisper word-level transcript (if generated)

Expand All @@ -63,7 +63,7 @@ https://hyperframes.heygen.com/llms.txt
After creating or editing any `.html` composition, **always** run the full check before considering the task complete:

```bash
npm run check
pnpm run check
```

Fix all errors before presenting the result. Inspect warnings should be reviewed before rendering.
Expand Down
Loading
Loading