Four Pure-TypeScript First Issues in OpenTools

Most web repositories require hours of environment setup: configuring cloud accounts, seeding local databases, mocking microservices, and untangling complex state management layers. OpenTools takes a radically different architectural stance: every tool engine is a pure TypeScript function over bytes. - No network calls: Tools run in browser tabs with connect-src 'none'. - No databases or servers: Inputs are Uint8Array buffers or strings; outputs are transformed buffers or strings. - Zero mocking required: Tests feed real file fixtures into pure functions and inspect the results. - Instant feedback: Run npm test, change one function, and watch your tests pass. Here is the codebase reality by the numbers: - lib/tools/subtitles/core.ts — 561 lines, 59 unit tests. - lib/tools/archive/zip-reader.ts — 413 lines, 21 unit tests. - lib/tools/audio/mp3-frames.ts — 354 lines, 14 unit tests. Below are four genuinely open, bite-sized tasks ready for contributors.

### 1. ZIP64 Archive Reader Support - Where it starts: lib/tools/archive/zip-reader.ts:214 - Current behavior: Throws an explicit error: "This is a ZIP64 archive — over 4 GB or over 65,535 files. This page reads standard ZIP archives only." - The task: Parse the ZIP64 End of Central Directory locator and record, and read extra field 0x0001 for 64-bit offsets and uncompressed lengths. - Why it is a great starter: Pure binary parsing from the public PKWARE specification. The refusal error is already written and tested; making it return valid entries turns the refusal into capability. --- ### 2. TTML / DFXP Subtitle Format Parser - Where it starts: lib/tools/subtitles/core.ts:11 - Current behavior: SubtitleFormat supports 'srt' | 'vtt' | 'sbv' | 'lrc' | 'ass'. - The task: Add TTML (Timed Text Markup Language / DFXP XML) to the format union. Parse XML timing cues and text into standard Cue objects. - Why it is approachable: TTML is XML, making it straightforward to parse in TypeScript. Adding it automatically lights up all 14 subtitle workbench operations (sync, retiming, conversion) for TTML files simultaneously. --- ### 3. SCC Closed Caption Decoder - Where it starts: lib/tools/subtitles/core.ts:11 - The task: Implement an SCC (Scenarist Closed Caption) parser. - Difficulty: Stretch item. SCC uses hex-encoded CEA-608 words and requires drop-frame timecode arithmetic. A rewarding challenge for developers interested in broadcast video standards. --- ### 4. iPhone Safari Dropzone File Handoff - Where it starts: docs/DROPZONE_FILE_HANDOFF.md - Current behavior: Dropping a file on the homepage carries it to the destination tool on Chromium (Chrome/Edge/Android), but WebKit (Safari/iOS) fails to hydrate the target input. - The task: Solve the WebKit file transfer issue documented in docs/DROPZONE_FILE_HANDOFF.md. - Why it is outstanding: The failing tests are already written and committed, marked test.skip on WebKit in e2e/dropzone-handoff.spec.ts. A contributor does not have to guess what success means: you unskip the tests and make them green. All dead ends and hypotheses are already documented.

Getting up and running takes two commands: ``bash git clone https://github.com/mgbuilderos/opentools.git cd opentools npm install npm test ` Our rule is simple: **the tests are the specification.** If you pick an item, implement the parser, add unit tests for valid and malformed files, and npm run qc` passes 8/8 gates, your contribution is technically sound. Explore our repository CONTRIBUTING.md guide and issue templates to claim an item!

The most common first-contribution failure is not technical. It is picking work that was never going to be accepted.

Signals that an issue is a good first target:

• It is labelled good first issue or help wanted, and no one has commented claiming it.
• The desired behaviour is stated, not just the problem. An issue saying "this is confusing" requires a design decision; one saying "this should return 400 instead of 500" does not.
• It is small enough to describe in a sentence. A first pull request touching fifteen files will not be reviewed quickly, and a slow review is what kills most first contributions.
• A test can prove it. Work that cannot be demonstrated is hard to accept.

Signals to avoid, at least initially: issues open for a long time with active discussion, which usually means an unresolved disagreement; anything touching build tooling or CI, where the maintainer's context is hard to acquire; and large refactors, which maintainers are right to be cautious about from an unfamiliar contributor.

Before writing code, comment on the issue saying what you intend to do and how. Two sentences. This surfaces a mismatch in expectations before you have spent an evening, and it is the single habit that most improves the odds of a merge.

Understanding the review order tells you where to spend effort.

Does it build and do the tests pass? A pull request with a red CI status is usually not read at all until it is green. Run the full local check before opening it, not only the tests for the file you changed.

Is there a test for the change? A bug fix without a regression test invites the question of how anyone will know if it breaks again. The test matters more than the fix being elegant.

Does it match the surrounding code? Not the project's style guide in the abstract — the style of the file being edited. A contribution that introduces a different naming convention or a new utility where an existing one would do creates review work.

Is the scope contained? Fixing the bug and also reformatting the file makes the diff unreviewable. Keep unrelated changes out, however tempting.

Does the description explain why? What was wrong, what changed, how it was verified. A maintainer reading twenty pull requests is choosing which to engage with, and a clear description moves yours up the queue.

One further point of etiquette that matters more than it should: if a maintainer requests changes, make them or say why not. A pull request abandoned after review consumed the scarcest resource the project has, which is maintainer attention.

Every task listed here is pure TypeScript with no framework knowledge required. The engines live beside the tools they power — the ZIP archive toolkit, the subtitle workbench and the MP3 toolkit are the three most approachable places to start reading.