add documentation and readme

Author: p2r3

README.md

@@ -0,0 +1,99 @@
+# [Convert to it!](https://convert.to.it/)
+**Truly universal online file converter.**
+
+Many online file conversion tools are **boring** and **insecure**. They only allow conversion between two formats in the same medium (images to images, videos to videos, etc.), and they require that you _upload your files to some server_.
+
+This is not just terrible for privacy, it's also incredibly lame. What if you _really_ need to convert an AVI video to a PDF document? Try to find an online tool for that, I dare you.
+
+[Convert.to.it](https://convert.to.it/) aims to be a tool that "just works". You're almost _guaranteed_ to get an output - perhaps not always the one you expected, but it'll try its best to not leave you hanging.
+
+## Usage
+
+1. Go to [convert.to.it](https://convert.to.it/)
+2. Click the big blue box to add your file (or just drag it on to the window).
+3. An input format should have been automatically selected. If it wasn't, yikes! Try searching for it, or [open an issue](https://github.com/p2r3/convert/issues/new) if it's really not there.
+4. Select an output format from the second list. If you're on desktop, that's the one on the right side. If you're on mobile, it'll be somewhere lower down.
+5. Click **Convert**!
+6. Hopefully, after a bit (or a lot) of thinking, the program will spit out the file you wanted. If not, [open an issue](https://github.com/p2r3/convert/issues/new) or cope and seethe.
+
+## Deployment
+
+Here's how to deploy this project locally:
+
+1. Clone this repository.
+2. Install [Bun](https://bun.sh/).
+3. Run `bun install` to install dependencies.
+4. Run `bunx vite` to start the development server.
+
+When you first open the page, it'll take a while to generate the list of supported formats for each tool. If you open the console, you'll see it complaining a bunch about missing caches.
+
+After this is done (indicated by a `Built initial format list` message in the console), use `printSupportedFormatCache()` to get a JSON string with the cache data. You can then save this string to `cache.json` to skip that loading screen on startup.
+
+## Contributing
+
+The best way to contribute is by adding support for new file formats (duh). Here's how that works:
+
+### Creating a handler
+
+Each "tool" used for conversion has to be normalized to a standard form - effectively a "wrapper" that abstracts away the internal processes. These wrappers are available in [src/handlers](src/handlers/).
+
+Below is a super barebones handler that does absolutely nothing. You can use this as a starting point for adding a new format:
+
+```ts
+// file: dummy.ts
+
+import type { FileData, FileFormat, FormatHandler } from "../FormatHandler.ts";
+
+class dummyHandler implements FormatHandler {
+
+  public name: string = "dummy";
+  public supportedFormats: FileFormat[];
+  public ready: boolean = false;
+
+  async init () {
+    this.supportedFormats = [
+      {
+        name: "Portable Network Graphics",
+        format: "png",
+        extension: "png",
+        mime: "image/png",
+        from: false,
+        to: false,
+        internal: "png"
+      },
+    ];
+    this.ready = true;
+  }
+
+  async doConvert (
+    inputFiles: FileData[],
+    inputFormat: FileFormat,
+    outputFormat: FileFormat
+  ): Promise<FileData[]> {
+    const outputFiles: FileData[] = [];
+    return outputFiles;
+  }
+
+}
+
+export default dummyHandler;
+```
+
+For more details on how all of these components work, refer to the doc comments in [src/FormatHandler.ts](src/FormatHandler.ts). You can also take a look at existing handlers to get a more practical example.
+
+There are a few additional things that I want to point out in particular:
+
+- Pay attention to the naming system. If your tool is called `dummy`, then the class should be called `dummyHandler`, and the file should be called `dummy.ts`.
+- The handler is responsible for setting the output file's name. This is done to allow for flexibility in rare cases where the _full_ file name matters. Of course, in most cases, you'll only have to swap the file extension.
+- The handler is also responsible for ensuring that any byte buffers that enter or exit the handler _do not get mutated_. If necessary, clone the buffer by wrapping it in `new Uint8Array()`.
+
+### Adding dependencies
+
+If your tool requires an external dependency (which it likely does), there are currently two well-established ways of going about this:
+
+- If it's an `npm` package, just install it to the project like you normally would.
+- If it's a Git repository, add it as a submodule to [src/handlers](src/handlers).
+
+**Please try to avoid CDNs (Content Delivery Networks).** They're really cool on paper, but they don't work well with TypeScript, and each one introduces a tiny bit of instability. For a project that leans heavily on external dependencies, those bits of instability can add up fast.
+
+- If you need to load a WebAssembly binary (or similar), add its path to [vite.config.js](vite.config.js) and target it under `/convert/wasm/`. **Do not link to node_modules**.

src/FormatHandler.ts

@@ -1,23 +1,61 @@
 export interface FileFormat {
+  /** Format description (long name) for displaying to the user. */
   name: string;
+  /** Short, "formal" name for displaying to the user. */
   format: string;
+  /** File extension. */
   extension: string;
+  /** MIME type. */
   mime: string;
+  /** Whether conversion **from** this format is supported. */
   from: boolean;
+  /** Whether conversion **to** this format is supported. */
   to: boolean;
+  /** Format identifier for the handler's internal reference. */
   internal: string;
 }
 
 export interface FileData {
+  /** File name with extension. */
   name: string;
+  /**
+   * File contents in bytes.
+   *
+   * **Please note:** _handlers_ are responsible for ensuring the lifetime
+   * and consistency of this buffer. If you're not sure that your handler
+   * won't modify it, wrap it in `new Uint8Array()`.
+   */
   readonly bytes: Uint8Array;
 }
 
+/**
+ * Establishes a common interface for converting between file formats.
+ * Often a "wrapper" for existing tools.
+ */
 export interface FormatHandler {
+  /** Name of the tool being wrapped (e.g. "FFmpeg"). */
   name: string;
+  /** List of supported input/output {@link FileFormat}s. */
   supportedFormats?: FileFormat[];
+  /**
+   * Whether the handler is ready for use. Should be set in {@link init}.
+   * If true, {@link doConvert} is expected to work.
+   */
   ready: boolean;
+  /**
+   * Initializes the handler if necessary.
+   * Should set {@link ready} to true.
+   */
   init: () => Promise<void>;
+  /**
+   * Performs the actual file conversion.
+   * @param inputFiles Array of {@link FileData} entries, one per input file.
+   * @param inputFormat Input {@link FileFormat}, the same for all inputs.
+   * @param outputFormat Output {@link FileFormat}, the same for all outputs.
+   * @param args Optional arguments as a string array.
+   * Can be used to perform recursion with different settings.
+   * @returns Array of {@link FileData} entries, one per generated output file.
+   */
   doConvert: (
     inputFiles: FileData[],
     inputFormat: FileFormat,