# Helper Tools

Helper Tools is a local-first browser workbench and the source of the
`@add-ideas/toolbox-helpers` TypeScript package. It provides small, explicit,
bounded building blocks for common developer calculations without network
requests, telemetry, persistence, or server processing.

The reusable package includes:

- strict Base64, Base64URL, hexadecimal, UTF-8, UTF-16 and Latin-1 conversion;
- URL component and form encoding, Unicode scalar/grapheme inspection, case,
  normalization and line-ending transforms;
- exact BigInt base conversion, SI/IEC data sizes, and common physical units;
- CRC-32, Adler-32, FNV-1a and Web Crypto SHA digests;
- strict IPv4/IPv6 parsing and exact CIDR ranges and containment;
- timestamp and bounded duration parsing and formatting;
- hardened JSON parsing, deterministic JSON and bounded CSV conversion; and
- secure random bytes/integers plus explicitly non-cryptographic seeded random
  primitives for repeatable tests and samples;
- checked offset arithmetic and a bounded typed byte cursor for binary parsers;
- deterministic byte-size formatting, collision-free multi-file download plans,
  and explicit Blob URL lease pools;
- cancellable disposable-worker jobs with progress and hard deadlines; and
- incremental CRC-32, Adler-32 and FNV-1a processing plus bounded,
  cancellable byte-source reads for Web Crypto digests.

## Browser app

```sh
npm ci
npm run dev
```

All workspaces are deep-linkable through URL hashes. Values live only in React
component state and disappear on refresh. Downloads use short-lived object URLs
that are revoked after use.

## Reusable package

The package is framework-free ESM with generated TypeScript declarations and no
install/runtime dependency. React and the Toolbox SDK are development-only app
build inputs and are not dependencies of package consumers. Every helper is
exported from one stable root:

```ts
import {
  ByteCursor,
  bytesToBase64Url,
  createIncrementalChecksum,
  digestHex,
  formatBytes,
  parseCidr,
  safeJsonParse,
} from "@add-ideas/toolbox-helpers";

const token = bytesToBase64Url(new Uint8Array([1, 2, 3]));
const hash = await digestHex(new TextEncoder().encode("local"));
const network = parseCidr("2001:db8::1/64");
const data = safeJsonParse('{"enabled":true}');
const size = formatBytes(1_572_864); // 1.50 MiB
const cursor = new ByteCursor(new Uint8Array([0, 1, 0, 2]));
const first = cursor.readUint16();
const checksum = createIncrementalChecksum("CRC-32").update(
  new Uint8Array([1, 2, 3]),
);
```

See [`docs/API.md`](docs/API.md) for the export groups and their security
boundaries. The browser app imports the same public root implementation; it does
not maintain a second calculator code path.

Build and inspect the package locally:

```sh
npm run build:library
npm pack --dry-run
```

## Verification and artifacts

```sh
npm run check
npm run test:browser
npm run package:release -- --force
npm run package:library -- --force
```

The application ZIP and npm-compatible `.tgz` are produced deterministically
with adjacent SHA-256 sidecars in `release/`. Neither artifact is published by
these commands.

## Licence

Helper Tools and `@add-ideas/toolbox-helpers` are licensed under
GPL-3.0-or-later. See [`LICENSE`](LICENSE). Shared Toolbox SDK and React notices
remain under their respective licences in `THIRD_PARTY_NOTICES.md` and the
generated release inventory.