docs: storage capacity investigation (PouchDB + GitHub + image size)

[kyuchia]

Investigate PouchDB and GitHub storage limits to answer the design doc's open questions about data capacity, sharing, and image size constraints. Document findings and implement an image upload size limit.

[kyuchia]

Summary

Investigate PouchDB and GitHub storage limits to answer the design doc's open questions about data capacity, sharing, and image size constraints. Implement an image upload size limit.

Design doc references:

• Rough Plan: "establish if PouchDB can be shared"
• Risks: "How flat is PouchDB?", "image size limits", "Git LFS limits"

1. PouchDB storage capacity

Browser	IndexedDB Limit
Chrome	Based on available disk space (typically several GB)
Firefox	No upper limit; prompts user once when an app wants to store more than 50 MB
Safari desktop	No upper limit; prompts in increments at 5 MB, 10 MB, 50 MB, 100 MB
Mobile Safari	IndexedDB available since iOS 10.3. Note: when iOS is low on storage, the OS may delete all app data without warning

Source: https://pouchdb.com/faq.html

Cress only uses 1 PouchDB instance (Cress-User-Storage in Storage.ts).

Even an extreme dataset (1000 neumes with 800 images) would be roughly 13 MB, well within all desktop browser limits.

2. PouchDB sharing

PouchDB stores data in the browser's IndexedDB, which is origin-bound and per-browser. It cannot be shared across devices, browsers, or browser profiles. Multiple tabs in the same browser on the same machine can access the same PouchDB instance, but that's it.

This is why we need GitHub-based storage (#132) for cross-device persistence.

3. GitHub storage limits

GitHub enforces these limits regardless of plan (Free / Pro / Team / Enterprise):

Limit	Value	Cress usage
Single file recommended	1 MB	Largest realistic CSV: a few MB
Single file warning	50 MB	Not approached
Single file hard limit	100 MB	Not approached
Push size hard limit	2 GB	Not approached
Repository size soft cap	~5 GB (Support may contact above this)	Hundreds of mapping files: well under 1 GB

Source: https://docs.github.com/en/repositories/creating-and-managing-repositories/repository-limits

4. Git LFS

Design doc Risks: "if the uploaded images are too large, we'll encounter Git LFS limits"

Git LFS does not apply to Cress. Images are base64-embedded inside CSV files, not stored as separate binary files, so Git treats them as regular text in the CSV. The 100 MB single-file hard limit above applies, and our measurements show CSVs stay well under that.

5. Image size

Measured from the two sample CSVs in assets/samples/:

File	Rows	Rows with real image data	Total file size
Neume shape-small.csv	20	16	255 KB
SQUAREnotation-NEUMElevel.csv	39	0 (12 rows contain "[]" placeholder strings, not actual images)	3.5 KB

Per-image stats from Neume shape-small.csv (16 base64-encoded JPEGs):

Metric	Base64 string size (as stored in CSV)	Decoded binary size
Min	1.1 KB	0.9 KB
Avg	15.8 KB	11.8 KB
Max	39.7 KB	29.8 KB

These are small black-and-white neume symbols, inherently tiny.

Scaling estimates (using base64 string size, since that's what gets stored):

Scenario	Estimated CSV size
20 neumes + 16 images (current sample)	~0.26 MB
130 neumes + 130 images (Old Hispanic scale)	~2 MB
500 neumes + 400 images (extreme)	~6.3 MB
1000 neumes + 800 images (worst case)	~13 MB

All scenarios fit comfortably under GitHub's 100 MB hard limit and the 1 MB-per-image recommendation below.

Remaining work

• Enforce image size limit on upload (recommended: 1 MB per image, base64-encoded)
  • Add size check in Storage.ts import flow
  • Show error message when limit is exceeded
  • 1 MB is roughly 60x larger than the average neume image, so no legitimate upload will be blocked