janhubicka · Oct 21, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026
diff --git a/.agents/qtgui.md b/.agents/qtgui.md
@@ -7,8 +7,9 @@ parameter files exist outside development. ZIP parameter archives and JSON-v2
 were temporary alpha experiments, not compatibility obligations. The first
 2.0 JSON `.cspar` format is the semantically grouped schema-3 design in
 [`doc/parameter-json-migration-tracking.md`](../doc/parameter-json-migration-tracking.md).
-Draft PR #556 switches the Qt GUI, CLI and recovery to native JSON schema 3,
-but it is **not yet merged or release-qualified**. The old JSON-v2 reader is
+The Qt GUI, CLI and recovery now use the native JSON schema-3 document;
+the project JSON schema and the legacy stitching reader are implemented in
+`libcolorscreen` independently of Qt. The old JSON-v2 reader is
 not a compatibility gate. Preserve historical `.par` reading and loss-checked
 export. MTF editors use immutable measurement IDs and capture-group IDs;
 source provenance must retain its physical interpretation through Save As,

diff --git a/NEWS b/NEWS
@@ -2,6 +2,8 @@ Changes planned for version 2.0 (development version 2.0alpha)
  - New features:
    - JSON based parameter file format .cspar.  Old .par files remains
      readable.
+   - Native JSON stitching projects (.csprj), with the original version-1
+     text-project reader retained for opening and converting older projects.
    - QT based graphical user interface
    - Support for new processes:
      - Dioptrichrome-B 

diff --git a/README.md b/README.md
@@ -126,6 +126,22 @@ from the Library of Congress webpages and produce color renderings.
 
 # Usage
 
+## Native files for the 2.0 development series
+
+- **`.cspar`** stores non-destructive image-processing parameters in UTF-8
+  JSON schema 3, with an optional linked source image. Historical `.par`
+  text files remain readable.
+- **`.csprj`** stores a multi-image stitching project in UTF-8 JSON schema 2.
+  Tiles refer to external source images and store only screen geometry and
+  stitching metadata; the original keyword-text version-1 project reader
+  remains supported for migration.
+
+The [2.0 user manual](https://github.com/janhubicka/Color-Screen/wiki/Color-Screen-2.0-User-Manual),
+[parameter reference](https://github.com/janhubicka/Color-Screen/wiki/Color-Screen-2.0-Parameter-Format),
+and [stitch-project format reference](https://github.com/janhubicka/Color-Screen/wiki/Color-Screen-2.0-Project-Format)
+describe the current workflows and schemas. Older Java GUI and CLI articles
+remain under [historical 1.0 documentation](https://github.com/janhubicka/Color-Screen/wiki/Color-Screen-1.0-Documentation).
+
 There are two programs installed. 
 
 `colorscreen` is a command line utility to render into tiff files. See

diff --git a/doc/parameter-archive-format.md b/doc/parameter-archive-format.md
@@ -1,6 +1,6 @@
 # Color-Screen parameter file format
 
-**Status: canonical pre-2.0 design, not yet the active writer.** This document
+**Status: implemented 2.0 schema-3 format.** This document
 replaces the historical ZIP-based alpha proposal, which was never used outside
 development. See [the current implementation tracker](parameter-json-migration-tracking.md),
 the [machine-readable schema](parameters-schema-v3.json), and the
@@ -14,15 +14,15 @@ available. Early ZIP-v1 and JSON-v2 `.cspar` implementations were unreleased
 experiments. There are **no JSON parameter files requiring a compatibility
 reader, format-preserving rewrite, or downgrade converter**.
 
-ZIP-based `.csprj` stitching projects are separate and remain supported.
+`.csprj` stitching projects are separate from `.cspar`: they now have a native JSON project schema with nested schema-3-compatible geometric mapping data only. The legacy project reader accepts version-1 keyword text.
 
 ## Physical representation
 
 A `.cspar` file is one UTF-8 JSON document; no ZIP wrapper, manifest,
 embedded CSP text, or binary side payload is required. JSON is also valid
 YAML 1.2 syntax, without importing YAML aliases/tags into our input language.
 
-The current semantic design uses the `org.colorscreen.parameters` format
+The implemented schema uses the `org.colorscreen.parameters` format
 identifier and integer `schema_version` 3. Structural required fields,
 mode-tagged values and nested types are defined by the checked-in draft-2020-12
 JSON Schema. The library's typed decoder additionally verifies capture-ID

diff --git a/doc/parameter-json-migration-tracking.md b/doc/parameter-json-migration-tracking.md
@@ -39,7 +39,8 @@ manifest, UI selection, recovery fallback, or compatibility fixture. The only
 supported input formats are historical plain-text `.par` and native JSON.
 Opening never rewrites a source file. Failed serialization, validation or
 file replacement preserves the original bytes and document target/dirty state.
-The ZIP-based `.csprj` stitching container is unrelated and remains supported.
+Stitching `.csprj` files are a separate format: the historical reader handles
+version-1 keyword text, and the new writer emits project JSON schema 2.
 
 Legacy `.par` export remains available with the existing loss-prevention
 checks. Unknown vendor/postamble metadata must never disappear in conversion:

diff --git a/doc/parameter-json-v3-reference.md b/doc/parameter-json-v3-reference.md
@@ -1,13 +1,13 @@
 # Canonical parameter JSON schema 3 — implementation contract
 
-**Status: draft implementation under CI, not yet merged or released.**
+**Status: implemented schema-3 parameter format for the 2.0 development series.**
 See the [implementation tracker](parameter-json-migration-tracking.md) and
 the [parameter-file specification](parameter-archive-format.md).
 
 Only old plain-text `.par` files exist outside development. There is no
 compatibility requirement for the discarded ZIP archive or unreleased JSON-v1
 or JSON-v2 experiments. The first supported `.cspar` is a single UTF-8
-JSON document. ZIP `.csprj` stitching projects are independent and unchanged.
+JSON document. Stitching `.csprj` projects are a separate format: the new project JSON schema embeds only the schema-3 geometric mapping and screen type per tile, while retaining the older version-1 keyword-text project reader.
 
 ## Structural ownership
 

diff --git a/doc/qtgui-workflow-roadmap.md b/doc/qtgui-workflow-roadmap.md
@@ -802,8 +802,9 @@ distinction remains ambiguous to operators.
 **15 October 2026 decision:** the only parameter files in circulation are old
 plain-text `.par` files. The ZIP-based parameter archive and both earlier
 JSON layouts were development experiments; there is no need to preserve or
-migrate from any of them. ZIP-based `.csprj` *stitching projects* remain
-supported and are unrelated to the parameter file format.
+migrate from any of them. Historical `.csprj` stitching projects use version-1 keyword text; the new
+JSON project writer retains the text reader. Project format is independent
+of `.cspar` parameter files.
 
 The first user-facing `.cspar` format for 2.0 is a single human-readable UTF-8
 JSON document with explicitly named, semantically grouped fields. The current

diff --git a/doc/wiki/Color-Screen-2.0-Parameter-Format.md b/doc/wiki/Color-Screen-2.0-Parameter-Format.md
@@ -6,7 +6,7 @@ The current native `.cspar` parameter file is **UTF-8 JSON (schema 3)**, not a Z
 
 ## Compatibility policy
 
-There are no distributed legacy ZIP-based `.cspar` files that need write compatibility. New saves use JSON schema 3. Do not describe legacy project ZIPs as JSON: `.csprj` is a separate format with a proposed migration.
+There are no distributed legacy ZIP-based `.cspar` files that need write compatibility. New saves use JSON schema 3. `.csprj` stitching projects are a separate format; the new schema-2 JSON project document contains a compact, schema-3-compatible `screen_geometry` object for each tile, not a complete copy of the parameter document. Its historical reader accepts version-1 keyword text.
 
 ## What the file describes
 

diff --git a/doc/wiki/Color-Screen-2.0-Project-Format.md b/doc/wiki/Color-Screen-2.0-Project-Format.md
@@ -1,18 +1,55 @@
-# Color-Screen 2.0 — stitching project format and JSON migration
+# Color-Screen 2.0 — stitching project JSON format
 
-## Status: proposed change, not yet implemented
+A `.csprj` file is a **plain UTF-8 JSON document**, with no ZIP wrapper or embedded image pixels. The native writer uses the project identifier `org.colorscreen.stitch-project` and project `schema_version` **2**. Each tile stores only its screen type and a **schema-3 geometric mapping subtree**, using the same typed codec as [`.cspar`](Color-Screen-2.0-Parameter-Format.md). It does not include irrelevant per-tile color, capture or MTF defaults.
 
-Stitching projects use the `.csprj` extension. The historical project representation is a ZIP archive. The planned 2.0 writer should instead emit **plain UTF-8 JSON** while preserving a reader for the original ZIP representation. No distributed legacy ZIP projects are known, so new writes need not retain the old container.
+This is the source-controlled format reference for the 2.0 migration in [PR #561](https://github.com/janhubicka/Color-Screen/pull/561); the published rolling build may precede that change until it is merged and packaged.
 
-## Migration requirements
+## Project JSON structure
 
-- Keep `.csprj` as the extension; detect legacy ZIP versus JSON by file signature/content, not filename alone.
-- Write new projects only as JSON once the migration lands.
-- Preserve project-wide settings, source-image references, per-image parameters, stitching geometry and relationships; do not embed large source images by default.
-- Support relative paths resolved from the project location; when an image has moved, allow reassociation without discarding the project.
-- Provide explicit schema/version identification and errors for unsupported versions or malformed data.
-- Retain the legacy ZIP reader, but do not silently reintroduce a ZIP writer.
+| Field | Type | Interpretation |
+|---|---|---|
+| `format` | string | Exactly `org.colorscreen.stitch-project` |
+| `schema_version` | integer | Exactly `2` |
+| `grid` | object | Required integer `columns` and `rows` (each 1–10) |
+| `pixel_size` | finite number | Pixel scale used by stitching/output |
+| `tiles` | array | Exactly `columns × rows` records, in row-major order |
 
-## Verification before documenting a normative schema
+Each entry of `tiles` contains precisely these fields:
 
-Test JSON save/load/save round trips, old ZIP load followed by JSON save, missing or moved images, relative and absolute paths, and representative multi-image stitching projects. Compare reconstructed project state, not merely text formatting. Only after implementation should this page list exact JSON keys and defaults as authoritative.
+| Field | Type | Interpretation |
+|---|---|---|
+| `filename` | UTF-8 string | Source-image filename or relative path |
+| `angle`, `ratio` | finite numbers | Detected screen angle and ratio |
+| `position` | array of 2 finite numbers | Tile's upper-left position in common screen coordinates |
+| `image_size` | array of 2 integers | Source image width and height in pixels |
+| `screen_size` | array of 2 integers | Tile width and height in screen coordinates |
+| `screen_shift` | array of 2 integers | Tile offset in screen coordinates; may be negative |
+| `screen_geometry` | JSON object | Exactly `screen_type` (string) and `geometry` (object); `geometry` uses the same keys and units as the `geometry` section of schema-3 `.cspar`, including any mesh |
+
+The `.cspar` schema-3 codec validates the `screen_geometry` contents against its native typed geometric mapping. A file containing extra capture, color, calibration, MTF or reconstruction settings is **rejected**, rather than accepting values that the stitching project would silently discard. No legacy `.par` text or processing-document defaults are embedded.
+
+File keys are validated strictly: unknown or missing fields, unsupported versions, incorrect grid dimensions and invalid geometry cause a load error. Parsing is bounded to prevent unexpectedly large projects. Known-screen bitmaps are allocated eagerly on load, so the reader imposes a **resource-safety ceiling of 128 Mi screen cells per tile and 512 Mi cells per project**, in addition to the 10×10 grid limit. These are enforced limits, not recommended physical dimensions; source-image pixel counts are independent. The file is serialized in a consistent order.
+
+## Paths and portability
+
+Source images remain external to the project. Relative filenames are resolved from the project file's directory, not the process's current working directory. Moving a project together with its relative-path images therefore preserves the references.
+
+The project file does not contain the source scan itself. Keep your scans when archiving a project.
+
+## Older projects and migration
+
+The **actual historical stitching-project format in `libcolorscreen` is text**, starting with:
+
+```text
+color_screen_stitch_project_version: 1
+num_images: 2 1
+pixel_size: 1.0
+```
+
+It then stores tile geometry with `stitch_image_...` keywords and a legacy CSP parameter block per tile. The original text reader remains available; opening an old project and saving it with the new writer produces JSON. The reader chooses between JSON and legacy text by the first non-whitespace character, not by the `.csprj` extension. The former ZIP archives mentioned in some alpha-era parameter documentation were *parameter-file* experiments, not this core stitching project format.
+
+New files are JSON only; there is no legacy project writer.
+
+## Tests
+
+The implementation includes native JSON encode/decode, deterministic save/load/save, malformed-field rejection, project `FILE*` saving/loading, version-1 text import and conversion, and bounds checks on legacy grid dimensions. Exact test results are tracked with PR #561.
diff --git a/doc/wiki/Color-Screen-2.0-User-Manual.md b/doc/wiki/Color-Screen-2.0-User-Manual.md
@@ -26,6 +26,6 @@ The image/cache subsystem is designed for very large scans. Preferences include
 
 - `.cspar`: current JSON processing parameters; see [format reference](Color-Screen-2.0-Parameter-Format.md).
 - `.par`: legacy parameter file, retained for reading.
-- `.csprj`: stitching project. The present ZIP-based representation is slated for JSON migration; see [project format](Color-Screen-2.0-Project-Format.md).
+- `.csprj`: stitching project. New projects use JSON; historical version-1 text files remain readable. See [project format](Color-Screen-2.0-Project-Format.md).
 
 This manual is a source-aligned development draft, not a guarantee that every GUI label is final. GUI testing and screenshots should be used to correct terminology before the 2.0 release.
diff --git a/src/colorscreen/colorscreen.C b/src/colorscreen/colorscreen.C
@@ -4168,20 +4168,17 @@ stitch (int argc, char **argv)
   }
   if (save_project_filename)
     {
-      FILE *f = fopen (save_project_filename, "wt");
-      if (!f)
+      /* A failed JSON encode or interrupted write must not destroy an
+         existing project. The shared text-file writer stages and atomically
+         replaces the destination on success. */
+      std::string json, error;
+      if (!prj->serialize_json (&json, &error)
+          || !write_parameter_text_file (save_project_filename, json, &error))
         {
-          fprintf (stderr, "Error opening project file: %s\n",
-                   save_project_filename);
+          fprintf (stderr, "Error saving project file %s: %s\n",
+                   save_project_filename, error.c_str ());
           return 1;
         }
-      if (!prj->save (f))
-        {
-          fprintf (stderr, "Error saving project file: %s\n",
-                   save_project_filename);
-          return 1;
-        }
-      fclose (f);
     }
   return 0;
 }

diff --git a/src/libcolorscreen/Makefile.am b/src/libcolorscreen/Makefile.am
@@ -1,7 +1,7 @@
 include_HEADERS = include/color.h include/colorscreen.h include/imagedata.h include/matrix.h include/scr-to-img.h  include/dllpublic.h include/scr-detect-parameters.h include/spectrum-to-xyz.h include/progress-info.h include/sensitivity.h include/precomputed-function.h include/mesh.h include/base.h include/tiff-writer.h include/stitch.h include/lens-correction.h include/tone-curve.h include/finetune.h include/focus-analysis.h include/histogram.h include/colorscreen-config.h include/dufaycolor.h  include/wratten.h include/screen-map.h  include/paget.h include/render-type-parameters.h include/render-parameters.h include/solver-parameters.h include/detect-regular-screen-parameters.h include/scr-to-img-parameters.h include/lens-warp-correction-parameters.h include/backlight-correction-parameters.h include/scanner-blur-correction-parameters.h include/strips.h include/mtf-parameters.h include/analyze-scanner-blur.h include/cow-vector.h include/cache-stats.h
 lib_LTLIBRARIES = libcolorscreen.la
 libcolorscreen_la_SOURCES = render.C render-to-scr.C render-fast.C render-interpolate.C screen.C scr-to-img.C imagedata.C loadsave.C parameter-archive.C render-tile.C scr-detect.C render-scr-detect.C spectrum-to-xyz.C patches.C progress-info.C render-to-file.C color.C sensitivity.C solver.C mesh.C scr-detect-geometry.C analyze-dufay.C analyze-paget.C analyze-strips.C screen-map.C analyze-base.C tiff-writer.C backlight-correction.C stitch-image.C stitch-project.C icc.C render-parameters.C mapalloc.C parse-captureone-lcc.C dufaycolor.C wratten.C spectrum.C spectrum-dyes.C spectrum-illuminants.C spectrum-responses.C tone-curve.C lens-warp-correction.C matrix-profile.C scr-detect-colors.C finetune.C focus-analysis.C homography.C gsl-utils.C scanner-blur-correction.C simulate.C has-regular-screen.C deconvolve.C mtf.C fft.C analyze-scanner-blur.C render-simulate.C out-color-adjustments.C slanted-edge.C denoise.C
-EXTRA_DIST = lru-cache.h analyze-base-worker.h gaussian-blur.h icc-srgb.h  render-diff.h render-tile.h sharpen.h gsl-utils.h gsl-solver.h loadsave.h parameter-archive.h parameter-json-budget.h mapalloc.h render-interpolate.h render-to-file.h spectrum-dyes.h icc.h nmsimplex.h render-superposeimg.h spectrum.h analyze-dufay.h analyze-paget.h analyze-strips.h analyze-base.h  bitmap.h render-fast.h spline.h screen.h render-scr-detect.h patches.h render-to-scr.h render.h solver.h scr-detect.h backlight-correction.h mem-luminosity.h homography.h simulate.h deconvolve.h mtf.h finetune-int.h fft.h render-screen.h render-simulate.h lanczos.h out-color-adjustments.h demosaic.h bspline.h cubic-interpolate.h denoise.h
+EXTRA_DIST = lru-cache.h analyze-base-worker.h gaussian-blur.h icc-srgb.h  render-diff.h render-tile.h sharpen.h gsl-utils.h gsl-solver.h loadsave.h parameter-archive.h parameter-json-budget.h stitch-project-json.h mapalloc.h render-interpolate.h render-to-file.h spectrum-dyes.h icc.h nmsimplex.h render-superposeimg.h spectrum.h analyze-dufay.h analyze-paget.h analyze-strips.h analyze-base.h  bitmap.h render-fast.h spline.h screen.h render-scr-detect.h patches.h render-to-scr.h render.h solver.h scr-detect.h backlight-correction.h mem-luminosity.h homography.h simulate.h deconvolve.h mtf.h finetune-int.h fft.h render-screen.h render-simulate.h lanczos.h out-color-adjustments.h demosaic.h bspline.h cubic-interpolate.h denoise.h
 
 if RENDER_EXTRA
 nodist_libcolorscreen_la_SOURCES = render-extra/render-extra.C