Save and open documents as .num (zipped JSON)

Datei › Speichern writes a .num file: a ZIP (fflate) laid out like
OpenDocument -- an uncompressed "mimetype" entry first
(application/x-numolus), meta.json (format version, ISO 8601 creation
time) and document.json, the same JSON the .json export writes. Opening a
.num (file dialog or drag & drop) unpacks it and offers the same
replace/append choice as a .json. Non-ZIPs, foreign ZIPs, a missing
document.json and a newer format version fail with a clear message.

The zip code is loaded on first use, like xlsx, so the main bundle does
not grow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -12,7 +12,7 @@ Eine browserbasierte Tabellenkalkulation nach dem Vorbild von **Apple Numbers**.
 ```bash
 npm install
 npm run dev        # Vite-Devserver
-npm run test       # Vitest-Suite (Engine + Store + IO), 566 Tests
+npm run test       # Vitest-Suite (Engine + Store + IO), 570 Tests
 npm run build      # Typecheck + Produktionsbuild
 npm run lint       # ESLint (flat config)
 ```
@@ -1088,15 +1088,16 @@ Alles clientseitig (`Blob` + `URL.createObjectURL` + `<a download>` + revoke).
 ### Export
 | Format | Inhalt |
 |--------|--------|
-| `.json` | **Natives Format**, verlustfreier Round-Trip: alle Blätter, alle Tabellen-/Diagramm-Objekte mit Position & Größe, Rohformeln, Spaltenbreiten, Tab-Reihenfolge, aktives Objekt, Zellauswahl. |
+| `.num`  | **Speicherformat** (Datei › Speichern): ZIP-Container mit demselben JSON wie `.json`, nur kleiner. Aufbau wie OpenDocument: zuerst `mimetype` (`application/x-numolus`, unkomprimiert), dann `meta.json` (Format-Version, Erstellzeit als ISO 8601) und `document.json`. Eine Datei aus einer neueren Format-Version wird mit klarer Meldung abgelehnt. |
+| `.json` | **Natives Format** (unkomprimiert), verlustfreier Round-Trip: alle Blätter, alle Tabellen-/Diagramm-Objekte mit Position & Größe, Rohformeln, Spaltenbreiten, Tab-Reihenfolge, aktives Objekt, Zellauswahl. |
 | `.csv`  | Aktive Tabelle, **berechnete Werte**, RFC-4180-Quoting, Trennzeichen `,`/`;` wählbar, `\r\n`, optional UTF-8-BOM. |
 | `.xlsx` | Arbeitsmappe via SheetJS, **ein Worksheet je Tabellen-Objekt**. Formeln als echte Excel-Formeln (`;`→`,`, `AVG`→`AVERAGE`), immer mit gecachtem Wert. |
 | `.png`  | Gewähltes Diagramm-Objekt über `chart.toBase64Image()`. |
 
 ### Import
-`<input type="file">` **und** Drag & Drop auf die Canvas; `.json` `.csv` `.xlsx`.
+`<input type="file">` **und** Drag & Drop auf die Canvas; `.num` `.json` `.csv` `.xlsx`.
 
-- **`.json`** → Dokument *ersetzen* (Rückfrage) oder Blätter *anhängen*.
+- **`.num`** / **`.json`** → Dokument *ersetzen* (Rückfrage) oder Blätter *anhängen*.
   **v1-Dokumente** (altes Ein-Raster-Format) werden automatisch nach v2
   migriert (je altes Blatt ein Blatt mit einer gleichnamigen Tabelle). Schema
   wird validiert; bei Fehler klare Meldung, **kein Teil-Import**.
@@ -1132,7 +1133,7 @@ Grundrechenarten: `Übersicht!B2 = =SUM(Umsatz!B2:E2)`, `D2 = =B2-C2`,
 
 ## Tests
 
-`npm run test` — Vitest, 566 Tests:
+`npm run test` — Vitest, 570 Tests:
 
 - **lexer / parser** — Präzedenz & Assoziativität (`^` vor `*/` vor `+-`, `^`
   rechts, `-2^2 = -(2^2)`), lokale/qualifizierte/quoted Bezüge, `!` **und** `::`,
@@ -1500,7 +1501,7 @@ Grundrechenarten: `Übersicht!B2 = =SUM(Umsatz!B2:E2)`, `D2 = =B2-C2`,
 src/
   engine/           # Formel-Engine (Eigenbau) + Unit-Tests
   store/            # reaktiver Dokument-Store (v2 Canvas-Modell), Formatierung
-  io/               # csv / json (Eigenbau, inkl. v1→v2), xlsx (SheetJS, lazy)
+  io/               # csv / json (Eigenbau, inkl. v1→v2), num (ZIP via fflate, lazy), xlsx (SheetJS, lazy)
   components/       # AppToolbar, SettingsPanel, FormulaBar, SheetCanvas, CanvasObject,
                     #   TableGrid, ChartView, TextBox, ButtonView, MacrosModal, SheetTabs,
                     #   StatusBar, TheLogo, …

package-lock.json

@@ -9,6 +9,7 @@
       "version": "1.0.0",
       "dependencies": {
         "chart.js": "^4.4.6",
+        "fflate": "^0.8.3",
         "vue": "^3.5.13",
         "xlsx": "^0.18.5"
       },
@@ -2952,6 +2953,12 @@
         "reusify": "^1.0.4"
       }
     },
+    "node_modules/fflate": {
+      "version": "0.8.3",
+      "resolved": "https://registry.npmjs.org/fflate/-/fflate-0.8.3.tgz",
+      "integrity": "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA==",
+      "license": "MIT"
+    },
     "node_modules/file-entry-cache": {
       "version": "8.0.0",
       "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-8.0.0.tgz",

package.json

@@ -16,6 +16,7 @@
   },
   "dependencies": {
     "chart.js": "^4.4.6",
+    "fflate": "^0.8.3",
     "vue": "^3.5.13",
     "xlsx": "^0.18.5"
   },

src/components/AppToolbar.vue

@@ -12,6 +12,8 @@ import ToolbarIcon, { type ToolbarIconName } from './ToolbarIcon.vue';
 import { WICOM, WICOM_SOCIAL } from '../config/brand';
 import {
   exportJson,
+  exportNum,
+  readNumFile,
   exportActiveTableCsv,
   exportXlsx,
   importJsonReplace,
@@ -107,6 +109,15 @@ function runCsvExport() {
     toasts.error((err as Error).message);
   }
 }
+async function runNumExport() {
+  try {
+    await exportNum(store);
+    toasts.success('Dokument als .num gespeichert.');
+  } catch (err) {
+    toasts.error(`Speichern fehlgeschlagen: ${(err as Error).message}`);
+  }
+}
+
 function runJsonExport() {
   exportJson(store);
   toasts.success('Dokument als JSON exportiert.');
@@ -159,6 +170,9 @@ async function handleFile(file: File) {
   try {
     if (ext === 'json') {
       importCtx.value = { kind: 'json', text: await readAsText(file), fileName: file.name };
+    } else if (ext === 'num') {
+      // a zipped JSON document -- unpacked, then the same replace/append choice
+      importCtx.value = { kind: 'json', text: await readNumFile(await readAsArrayBuffer(file)), fileName: file.name };
     } else if (ext === 'csv') {
       importCtx.value = {
         kind: 'csv',
@@ -324,7 +338,8 @@ function onSample() {
         <li><button @click="onNew">Neu</button></li>
         <li><button @click="onSample">Muster · Umsatzanalyse</button></li>
         <li class="sep" />
-        <li><button @click="pickFile">Importieren … (.json .csv .xlsx)</button></li>
+        <li><button @click="pickFile">Öffnen / Importieren … (.num .json .csv .xlsx)</button></li>
+        <li><button @click="runNumExport">Speichern · Dokument (.num)</button></li>
         <li class="sep" />
         <li><button @click="runJsonExport">Export · Dokument (.json)</button></li>
         <li><button @click="openCsvExport">Export · aktive Tabelle (.csv) …</button></li>
@@ -344,7 +359,7 @@ function onSample() {
       <ToolbarIcon :name="themeIcon" />
     </button>
 
-    <input ref="fileInput" type="file" accept=".json,.csv,.xlsx" hidden @change="onFileChosen" />
+    <input ref="fileInput" type="file" accept=".num,.json,.csv,.xlsx" hidden @change="onFileChosen" />
     <span v-if="busy" class="busy">Verarbeite …</span>
   </header>
 

src/components/SheetCanvas.vue

@@ -133,7 +133,7 @@ function selectObj(id: string) {
       </div>
     </div>
 
-    <div v-if="dropActive" class="drop">Datei ablegen (.json .csv .xlsx)</div>
+    <div v-if="dropActive" class="drop">Datei ablegen (.num .json .csv .xlsx)</div>
   </div>
 </template>
 

src/io/__tests__/num.spec.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate';
+import { useDocument } from '../../store/document';
+import { serializeDocument } from '../json';
+import { importJsonReplace, readNumFile } from '../operations';
+import { NUM_MIMETYPE, NumFileError, packNum, unpackNum } from '../num';
+
+describe('.num files', () => {
+  it('round-trip the document JSON exactly', async () => {
+    const s = useDocument();
+    s.resetToSeed();
+    const json = serializeDocument(s.snapshot());
+    const bytes = packNum(json);
+    expect(unpackNum(bytes)).toBe(json);
+    // and import back into the store like a .json file
+    s.newDocument();
+    importJsonReplace(s, await readNumFile(bytes.slice().buffer));
+    expect(serializeDocument(s.snapshot())).toBe(json);
+  });
+
+  it('are smaller than the JSON they carry', () => {
+    const s = useDocument();
+    s.resetToSeed();
+    const json = serializeDocument(s.snapshot());
+    expect(packNum(json).length).toBeLessThan(json.length);
+  });
+
+  it('start with an uncompressed mimetype entry, plus meta.json with an ISO timestamp', () => {
+    const bytes = packNum('{}', new Date('2026-09-28T10:00:00Z'));
+    // local file header (30 bytes) + "mimetype" (8) -> the stored content
+    expect(strFromU8(bytes.subarray(30, 38))).toBe('mimetype');
+    expect(strFromU8(bytes.subarray(38, 38 + NUM_MIMETYPE.length))).toBe(NUM_MIMETYPE);
+    const meta = JSON.parse(strFromU8(unzipSync(bytes)['meta.json']));
+    expect(meta).toEqual({ format: 'numolus', formatVersion: 1, created: '2026-09-28T10:00:00.000Z' });
+  });
+
+  it('reject what is not a numolus file', () => {
+    expect(() => unpackNum(strToU8('{"version":2}'))).toThrow(NumFileError);
+    expect(() => unpackNum(zipSync({ mimetype: strToU8('application/zip') }))).toThrow(/Keine numolus-Datei/);
+    expect(() => unpackNum(zipSync({ mimetype: strToU8(NUM_MIMETYPE) }))).toThrow(/kein document.json/);
+    const newer = zipSync({
+      mimetype: strToU8(NUM_MIMETYPE),
+      'meta.json': strToU8('{"formatVersion": 99}'),
+      'document.json': strToU8('{}'),
+    });
+    expect(() => unpackNum(newer)).toThrow(/neueren numolus-Version/);
+  });
+});

src/io/num.ts

@@ -0,0 +1,62 @@
+/**
+ * The native `.num` document file: a ZIP container around the same JSON the
+ * `.json` export writes (json.ts), so it's smaller on disk and leaves room
+ * for more parts later (images, attachments) without changing the format.
+ *
+ * Layout, modelled on OpenDocument:
+ *   mimetype        "application/x-numolus", stored uncompressed as the
+ *                   first entry, so a file sniffer can identify the format
+ *                   from a fixed offset
+ *   meta.json       { format, formatVersion, created (ISO 8601) }
+ *   document.json   the document, exactly as `serializeDocument()` writes it
+ *
+ * Reading only needs `document.json`; `mimetype` is checked when present so
+ * a random ZIP renamed to `.num` fails with a clear message.
+ */
+import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate';
+
+export const NUM_MIMETYPE = 'application/x-numolus';
+export const NUM_FORMAT_VERSION = 1;
+
+export class NumFileError extends Error {}
+
+export function packNum(documentJson: string, now: Date = new Date()): Uint8Array {
+  const meta = { format: 'numolus', formatVersion: NUM_FORMAT_VERSION, created: now.toISOString() };
+  return zipSync({
+    mimetype: [strToU8(NUM_MIMETYPE), { level: 0 }],
+    'meta.json': strToU8(JSON.stringify(meta, null, 2)),
+    'document.json': strToU8(documentJson),
+  });
+}
+
+/** The `document.json` text inside a `.num` file. */
+export function unpackNum(bytes: Uint8Array): string {
+  let files: Record<string, Uint8Array>;
+  try {
+    files = unzipSync(bytes);
+  } catch {
+    throw new NumFileError('Keine gültige .num-Datei (kein ZIP-Archiv).');
+  }
+  const mimetype = files.mimetype ? strFromU8(files.mimetype).trim() : null;
+  if (mimetype !== null && mimetype !== NUM_MIMETYPE) {
+    throw new NumFileError(`Keine numolus-Datei (Typ "${mimetype}").`);
+  }
+  const doc = files['document.json'];
+  if (!doc) throw new NumFileError('Die .num-Datei enthält kein document.json.');
+  const meta = files['meta.json'] ? safeJson(strFromU8(files['meta.json'])) : null;
+  const version = meta && typeof meta === 'object' ? (meta as { formatVersion?: unknown }).formatVersion : undefined;
+  if (typeof version === 'number' && version > NUM_FORMAT_VERSION) {
+    throw new NumFileError(
+      `Die Datei stammt aus einer neueren numolus-Version (Format ${version}); bitte die App aktualisieren.`,
+    );
+  }
+  return strFromU8(doc);
+}
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}

src/io/operations.ts

@@ -48,6 +48,20 @@ export function exportJson(store: DocumentStore): void {
   downloadText('dokument.json', serializeDocument(store.snapshot()), 'application/json');
 }
 
+/** Save as the native `.num` file (the JSON document, zipped -- see num.ts).
+ *  The zip code loads on first use, like the xlsx support. */
+export async function exportNum(store: DocumentStore): Promise<void> {
+  const { packNum, NUM_MIMETYPE } = await import('./num');
+  const bytes = packNum(serializeDocument(store.snapshot()));
+  downloadBlob('dokument.num', new Blob([bytes], { type: NUM_MIMETYPE }));
+}
+
+/** The document JSON inside a `.num` file -- then imported like a `.json`. */
+export async function readNumFile(buffer: ArrayBuffer): Promise<string> {
+  const { unpackNum } = await import('./num');
+  return unpackNum(new Uint8Array(buffer));
+}
+
 export function exportActiveTableCsv(store: DocumentStore, opts: CsvExportOptions): void {
   const table = store.activeTable.value;
   if (!table) throw new Error('Keine Tabelle ausgewählt.');