From e7bc6809cd292eccd5467ab218d46edc013f2429 Mon Sep 17 00:00:00 2001
From: SheetJS <dev@sheetjs.com>
Date: Tue, 5 Jul 2022 02:29:47 -0400
Subject: [PATCH] icloud

---
 iwa/README.md | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/iwa/README.md b/iwa/README.md
index 1bedd91..ed49f2a 100644
--- a/iwa/README.md
+++ b/iwa/README.md
@@ -1,7 +1,19 @@
 # iWork 2013+
 
-This covers the standalone ZIP-based format.  iCloud uses a different format to
-support differential sync between devices.
+There are three different styles of iWork files:
+
+1) The macOS applications generate ZIP files which contain the metadata and
+special `.iwa` files which hold the file data.
+
+2) iCloud persistence on macOS is a folder based structure containing an
+`Index.zip` file which is "similar" to the macOS standalone file structure.
+
+3) [The web iCloud editors](https://icloud.com) export ZIP files which contain
+an `Index.zip` file similar to iCloud persistence.  Note that this is literally
+a ZIP file within a ZIP file
+
+The `Index.zip` file has an identical structure to an actual file generated by
+the macOS applications, so the discussion is applicable to all file styles.
 
 The ZIP container holds a number of Mac binary "property list" files (`.plist`)
 which can be safely ignored or blanked.  It also can hold preview images that
@@ -9,8 +21,8 @@ can be safely ignored.
 
 ## File Structure
 
-The `.numbers` file is a ZIP file containing a number of `.iwa` entries.  The
-primary entrypoint is `/Index/Document.iwa`.
+The iWork file (`.KEY`, `.NUMBERS`, `.PAGES`) is a ZIP file containing a number
+of `.iwa` entries.  The primary entrypoint is `/Index/Document.iwa`.
 
 `TSPersistence.framework` handles the byte-level operations for the files.
 
@@ -242,7 +254,7 @@ The cell type is stored at byte offset 2:
 All three file types use the same message tag (1) for the root `DocumentArchive`
 message.  However, the required fields vary between formats.
 
-In the 11.2 apps, the required fields are:
+In the 12.1 apps, the required fields are:
 
 ```proto
 // Keynote optional fields 4
@@ -251,7 +263,7 @@ message .KN.DocumentArchive {
   required .TSP.Reference show = 2;
 }
 
-// Numbers optional fields 1, 3, 7, 9, 10, 11, 12
+// Numbers optional fields 1, 3, 7, 9, 10 - 12
 message .TN.DocumentArchive {
   required .TSA.DocumentArchive super = 8;
   required .TSP.Reference stylesheet = 4;
@@ -259,7 +271,7 @@ message .TN.DocumentArchive {
   required .TSP.Reference theme = 6;
 }
 
-// Pages optional fields 2 - 7, 11 - 14, 16, 17, 20, 21, 30 - 49
+// Pages optional fields 2 - 7, 11 - 14, 16, 17, 20, 21, 30 - 50
 message .TP.DocumentArchive {
   required .TSA.DocumentArchive super = 15;
 }