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
10 changes: 10 additions & 0 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,16 @@ jobs:

- run: npm ci

# Nothing is deployed that has not passed the same checks as CI.
- name: Lint
run: npm run lint

- name: Typecheck
run: npm run typecheck

- name: Test
run: npm test

- name: Build client
run: npm run build

Expand Down
39 changes: 39 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# GitFrame

On-device video frame extractor for a phone browser, served by a Cloudflare
Worker as static assets. Live at <https://gitframe.reloru.workers.dev>.

## Checks

Run all of these before pushing; CI runs the same ones.

```bash
npm run lint
npm run typecheck
npm run coverage # vitest with thresholds: 90% lines/statements/functions, 85% branches
npm run build
```

## Deploy

Pushing to `main` runs `.github/workflows/deploy.yml`: lint, typecheck, tests,
build, then `wrangler deploy`. `GET /healthz` returns `{"ok":true}` on the live
Worker.

## Conventions

- Nothing is uploaded and nothing is stored: no network calls from the page, no
localStorage / IndexedDB / cookies / service worker, every response
`Cache-Control: no-store`. The CSP in `worker/index.ts` enforces the first
part. Do not add persistence or third-party requests.
- Phone-first: every tap target is at least 48px, inputs are 16px or larger,
nothing scrolls sideways.
- `src/lib/` is pure logic with no DOM. `src/app/extractor.ts` takes every
browser API through a narrow interface and `src/app/ui.ts` takes its
capabilities by injection, so both run under test without a real decoder.
- `test/ui.test.ts` mounts the real `src/index.html`; an element id must change
in the markup and in `ui.ts` together.
- Times handed to the video are frame centres, not frame boundaries (see
`stepByFrames` and `buildPlan`).
- Behaviour on iOS Safari cannot be tested here. Chromium via Playwright is the
nearest check; say so when a change depends on Safari specifics.
37 changes: 30 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,14 +43,35 @@ The mobile requirements drove most of the design:

## Features

- Frame-accurate stepping (±1 frame, ±1 second) at a configurable frame rate
- Grab the current frame, or batch-extract every N seconds / N frames total
- Frame-accurate stepping (±1 frame, ±1 second or ±6 frames) at the frame rate
read from the file. Steps land on the centre of a frame, never on the
boundary between two, so no frame is skipped or shown twice
- Grab the current frame, or batch-extract every N seconds, N frames total, or
every frame in a range
- Duplicate grabs are flagged before they land: a frame already in the gallery
warns instead of capturing, and a second tap within the window keeps it anyway
- PNG, JPG, or WebP output with a quality slider and longest-edge downscaling
- Tap to select frames; download one as an image or many as a ZIP
- One-tap removal of letterbox and pillarbox bars
- A sharpness score on every frame, and a gallery order that puts the sharpest first
- A full-screen viewer: tap the arrows in a tile's corner to see the frame at
full size, page or swipe through the gallery, pinch to zoom, select, save or
delete it, or send the video back to the moment it came from
- Tap to select frames; save one as an image or many through the share sheet
(a ZIP where there is no share sheet)
- Runs offline once loaded — there is nothing to talk to

## Built for long runs on a phone

- The gallery shows small thumbnails and keeps each tile in place between
updates; the full-size image is only decoded in the viewer.
- Dragging the scrubber keeps one seek in flight and jumps to the latest
position when it lands, instead of queueing every position the thumb passed.
- A batch run holds a screen wake lock where the browser offers one, and if the
page is sent to the background it waits there and carries on when it is back,
rather than writing each stalled frame off as skipped.
- "Clear all" asks for a second tap when more than one frame is at stake —
frames exist nowhere but in the page.

## Development

```bash
Expand Down Expand Up @@ -80,14 +101,16 @@ controller's element ids ever drift apart.

## Deployment

Deployed to Cloudflare Workers with static assets. To deploy from CI, add two
repository secrets:
Deployed to Cloudflare Workers with static assets, at
<https://gitframe.reloru.workers.dev>. Every push to `main` runs
`.github/workflows/deploy.yml`: lint, typecheck, tests, build, then
`wrangler deploy`. It needs two repository secrets:

- `CLOUDFLARE_API_TOKEN` — needs the **Workers Scripts: Edit** permission
- `CLOUDFLARE_ACCOUNT_ID`

Until those exist, the deploy workflow skips with a notice rather than failing.
To deploy by hand:
Without them the workflow skips the deploy step with a notice rather than
failing. To deploy by hand:

```bash
npm run deploy
Expand Down
Loading
Loading