iwa-inspector/README.md

# iwa-inspector

source for <https://sheetjs.com/tools/iwa-inspector>

`iwa-inspector` is a tool for inspecting iWork archives.

<https://oss.sheetjs.com/notes/iwa/> covers the high-level structure of files.
This inspector performs the top-level extraction of messages and parses using
extracted Protocol Buffer definitions.

## Usage

The sections are separated by a light gray horizontal line and a light gray
vertical line. Panels can be resized by click-dragging the line.

### Selecting a File

The file input element in the top-left corner of the page is limited to the IWA
file types: `.numbers`, `.key`, and `.pages`.

The site automatically fetches a sample file on load.

### Message Table

The message table is shown just below the header bar. The column headers are:

| name      | description           |
|:----------|:----------------------|
| `id`      | Message ID            |
| `type`    | Numeric Message Type  |
| `message` | Absolute Message Type |
| `path`    | Location of Message   |

The table can be sorted by clicking on the column headers.

### Searching for Messages

The search text box in the top-right corner of the page is a plaintext search
over the parsed messages. Searches will match field names, string values and
UUID fields of message type `.TSP.UUID`.

### Selecting a Message

When a row in the table is selected, the bottom-left panel will display the
Protocol Buffers definition for the message and the bottom-right panel will
display the parsed contents.

### Message Structure

The bottom-right panel shows the following information:

- "Message": parsed information following the message definition
- "Metadata": parsed information from the message metadata
- "Dependents": list of messages that list the current message as a dependency.

Clicking on a message name in the inspector will show the message definition in
the left pane. A "Return" link returns to the base message definition.

Clicking on a `.TSP.Reference` ID will jump to the referenced message.

### Exporting Data

Right-clicking a custom message type will show a context menu with options to
copy the raw byte representation (array of numbers) or parsed object (JSON).

## Development

`make dev` starts the dev server.

`make build` generates the static site.

## Refreshing Protos and Messages

`make deps` requires a SIP-disabled Intel Mac with Keynote + Numbers + Pages.

The last run was on 2023-09-24 against version 13.2 (7038.0.87)

Each app should be run at least once before refreshing artifacts.

#### Developer Tools error

Note: Runs may fail with an error like

```
error: Uncaught (in promise) "Could not find map!"
```

Developer tools permissions must be granted. Running the command a second time
typically shows a popup asking for Touch ID or password. After authorization,
the build should run successfully.


## Protocol Buffer Details

Note that the `message` field is absolute. For example, `TSTArchives.proto`
specifies the `.TST.TileStorage` as follows:

```proto
package TST;

message TileStorage {
  message Tile {
    required uint32 tileid = 1;
    required .TSP.Reference tile = 2;
  }
  repeated .TST.TileStorage.Tile tiles = 1;
  optional uint32 tile_size = 2;
  optional bool should_use_wide_rows = 3;
}
```

The protobuf extractor rewrites the message names using the absolute form:

```proto
message .TST.TileStorage {
  message Tile {
    required uint32 tileid = 1;
    required .TSP.Reference tile = 2;
  }
  repeated .TST.TileStorage.Tile tiles = 1;
  optional uint32 tile_size = 2;
  optional bool should_use_wide_rows = 3;
}
```