# HyperView 3.2

A Java desktop hypermedia viewer (AWT/Swing application frame built on HyperView's Orange framework). HyperView hosts interactive views, gadgets, networking, and optional serial-port I/O in a single desktop window. The packaged entry point is `com.multiversesocial.hyperview.ViewMain`.

**By Stunt Grok Jockey Tony (@tswain555 on X)**

## License

MIT License -- see [LICENSE](LICENSE).
Copyright (c) 1997-2026 Tony Swain (Stunt Grok Jockey Tony, @tswain555 on X).

The MIT license covers **Tony's code** in this tree. Third-party source and media
are **excepted** and keep their own notices/terms (see [Third-party code](#third-party-code)
and [Third-party media](#third-party-media) below).

`README_3.2.txt` is kept as a short historical packaging note from the 3.2 clean-tree cut; this README is the primary public documentation.

## Requirements

- **JDK 26** (build scripts were written against JDK 26.0.1).
- The bundled scripts assume the JDK at:
  - MSYS2/bash: `/e/java/jdk-26.0.1`
  - Windows cmd: `E:\java\jdk-26.0.1`
- To use another JDK, edit the `PATH=` / `export PATH=` line at the top of `compile26` / `compile26.bat` and `run26` / `run26.bat`, or put your `javac`/`java`/`jar` on `PATH` first.
- Optional for the serial-port feature only: Sun's old **Java Communications API 2.0** (`comm.jar`). See [comm.jar](#commjar-not-included) below. **Compile still needs `lib/comm.jar` on the classpath** because `SerialHandler.java` imports `javax.comm`.

## Build

From an MSYS2 shell at the project root:

```bash
./compile26
```

Or on Windows cmd:

```bat
compile26.bat
```

### Exact commands `compile26` runs

With JDK 26 `bin` on `PATH`, from the project root (same steps as `compile26`):

```bash
mkdir -p build/classes dist/lib
rm -rf build/classes
mkdir -p build/classes

find src -name '*.java' > build/sources.txt
javac -encoding US-ASCII -Xmaxerrs 5 -g -d build/classes -cp "lib/comm.jar" -sourcepath src @build/sources.txt

mkdir -p build/classes/com/multiversesocial/hyperview/res
cp -f src/com/multiversesocial/hyperview/res/* build/classes/com/multiversesocial/hyperview/res/

printf '%s\n' \
  'Manifest-Version: 1.0' \
  'Main-Class: com.multiversesocial.hyperview.ViewMain' \
  'Class-Path: lib/comm.jar' \
  'Implementation-Title: HyperView' \
  'Implementation-Version: 3.2' \
  'Implementation-Vendor: MultiverseSocial' \
  '' > build/MANIFEST.MF

jar --create --file dist/hyperview-3.2.jar --manifest build/MANIFEST.MF -C build/classes .
cp -f lib/comm.jar dist/lib/comm.jar
```

Windows `compile26.bat` is the same idea with `dir /s /b`, `copy`, and `lib\comm.jar` path separators.

Output: `dist/hyperview-3.2.jar` (and, when `lib/comm.jar` is present, a copy at `dist/lib/comm.jar`).

See [BUILD.md](BUILD.md) for layout notes.

## Run

**Do not expect this release tarball to include `comm.jar`.** The jar still lists `Class-Path: lib/comm.jar`; a missing Class-Path jar is ignored by the JVM.

From the project root (so prefs / `.dat` files land in the working directory):

```bash
./run26
```

```bat
run26.bat
```

Or:

```bash
java -Dsun.net.useExclusiveBind=false -Xms1000m -Xmx1000m -jar dist/hyperview-3.2.jar
```

## Application-level applets

HyperView 3.2 can host **application-level Java applets** (programs written against `java.applet.Applet` that use the lifecycle, drawing, images, sound, parameters, mouse and keyboard) **with some modifications**. JDK 26 removed the Applet API ([JEP 504](https://openjdk.org/jeps/504)), so an old applet has to be ported: it extends `ViewMain` (the application class HyperView starts; `HyperView` is the abstract base), overrides `main()` in place of `init()`, draws in a `ViewPane` (as the bundled Asteroids port does), gets HyperView's normal mouse and keyboard handling, and uses HyperView's `AudioClip`/`SoundClip` and `res/` resources.

Step-by-step instructions, the API mapping table, before/after code and the real Asteroids changes are in the **Applet Migration Guide**: [`dev/java/AppletMigration.html`](dev/java/AppletMigration.html) (online: <https://multiversesocial.com/dev/java/AppletMigration.html>).

## Does HyperView need `comm.jar` to start?

**No -- it runs without `comm.jar` except for the serial-port feature.**

Static analysis:

- Only `SerialHandler.java` imports `javax.comm` / uses `com.sun.comm.Win32Driver`.
- `HyperView` holds a `SerialHandler serialPortHandler` field and sets boolean `serialEnabled` flags during init; it does **not** construct `SerialHandler` on the normal application path.
- `SerialHandler` is constructed from `SerialPane` (and related serial UI) when that feature is opened.
- `ViewMain.main()` creates UI gadgets (including `Enfora2218WhackButton`) that only *check* `serialEnabled`; they do not load `SerialHandler` until the serial UI path runs.
- Entry: `HyperView.main` -> `new ViewMain()` -> `new HyperFrame(...)`.

A headless class-load check (no GUI) confirmed `ViewMain` / `HyperView` load with `comm.jar` absent from the classpath; loading/initializing `SerialHandler` fails without `javax.comm` as expected.

If serial support is disabled or `comm.jar` / native bits are missing, HyperView still starts; serial UI shows a "serial port is disabled" style message instead.

## `comm.jar` (not included)

`comm.jar` is **Sun's Java Communications API 2.0 for Windows** (`javax.comm`, driver `com.sun.comm.Win32Driver`). It is **not redistributable** with this MIT release, so it is **excluded** from the public package.

Historically it shipped as `javacomm20-win32.zip` (contents typically `commapi/comm.jar`, `win32com.dll`, `javax.comm.properties`). Oracle's old product page and the original Sun download URLs are gone or unreliable. Third-party mirrors and Maven metadata for `javax.comm:comm:2.0.3` exist, but there is **no single authoritative, reliably available official download** today -- search the web for `javacomm20-win32` / `javax.comm` archives, verify the bits yourself, and prefer a maintained alternative (e.g. RXTX / jSerialComm) if you are extending the code.

If you obtain a compatible `comm.jar`:

1. Place it at `lib/comm.jar` (required to compile this tree as-is).
2. For runtime next to the jar, also place a copy at `dist/lib/comm.jar` (matches the jar manifest `Class-Path`).
3. On Windows you typically also need `win32com.dll` on the JRE/JDK `bin` path and `javax.comm.properties` installed per the old Comm API instructions.

See `lib/README.txt` in the release package.

## Third-party code

- **`Asteroids.java`** (`src/com/multiversesocial/hyperview/Asteroids.java`) is by **Mike Hall**, Copyright **1998** (widely known from his brainjar.com Asteroids applet). It keeps its original header notice and in-game credit strings, and is **not covered by the MIT license**. Tony's HyperView porting work around it does not relicense Mike Hall's original code. Treat `Asteroids.java` under Mike Hall's original notice and terms.
- No other third-party *source files* were identified in this tree. Runtime-only dependency **`comm.jar`** (Sun Java Communications API / `javax.comm`) is excluded from the package entirely (see above). Contributor thank-yous in `About.java` (Mark Collette; Kevin "Huntter" Kinsella) and a code comment crediting Mark Collette in `HyperView.java` are acknowledgements, not separate third-party modules.

## Third-party media

The bundled images and sounds under `src/com/multiversesocial/hyperview/res/` may come from other sources. Examples: Hubble/NASA-style backgrounds such as `hdf.gif` and `ngc2440.gif`; `lgn.gif` was newly generated for this tree. The MIT license covers Tony's code only; media may have separate provenance -- treat redistributed artwork accordingly. Media is likewise **excepted** from the MIT claim where it originates elsewhere.

## Package layout

```
hyperview3.2/
  LICENSE
  README.md
  README_3.2.txt
  BUILD.md
  compile26 / compile26.bat
  run26 / run26.bat
  src/com/multiversesocial/hyperview/   # Java sources
  src/com/multiversesocial/hyperview/res/  # bundled gif/jpg/au
  lib/                  # put comm.jar here (not shipped)
  dist/hyperview-3.2.jar
  dist/lib/             # optional runtime copy of comm.jar
  dev/java/             # HTML class docs + Applet Migration Guide
```