The .focale project format

Archive layout

A .focale file is a standard ZIP archive, without encryption or obfuscation. manifest.json is required; preview.png is an optional thumbnail with a longest edge of at most 512 pixels.

Raster assets, masks, custom channels, embedded ICC profiles, placed sources, nested documents and imported patterns use distinct archive directories. Filenames encode opaque identifiers rather than interpreting them as paths.

project.focale
├── manifest.json
├── preview.png
├── profiles/document.icc
├── profiles/raster/….icc
├── raster/….png | .fcraster | .fctiles
├── masks/….png | .fctiles
├── channels/….png | .fctiles
├── objects/raster/N.fcraster
├── placed/….bin
├── placed_documents/….focale
└── patterns/….fptile

The versioned manifest

The root format tag is focale and the current writer uses version 1. The reader refuses a newer unsupported version rather than guessing its meaning.

The manifest stores document geometry, colour mode, bit depth, profiles and a layer tree, with optional paths, guides, channels, slices, layer compositions, animation and variables. The example below is a manifest excerpt, not a complete loadable project.

{
  "format": "focale",
  "version": 1,
  "document": {
    "width": 1920,
    "height": 1080,
    "dpi": 96,
    "colorMode": "rgb",
    "bitsPerChannel": 8
  }
}

PNG and exact .fcraster entries

sRGB RGB8 process assets can use PNG. Profiled RGB8 and other native modes or depths use .fcraster to retain their device samples and precision. Pixels are premultiplied; fully transparent pixels have zero process samples.

.fcraster version 1 starts with a 32-byte header. Integers are little-endian; the payload is interleaved samples followed by alpha, compressed with zlib by the current writer.

Independent raster tiles

Multi-tile assets can use a .fctiles JSON descriptor instead of one PNG or .fcraster entry. It lists image dimensions, native format, tile rectangles and object references.

Tiles partition the image in row-major order without gaps or overlaps. Their axes are at most 4096 pixels. Exact tile payloads are deduplicated under objects/raster/N.fcraster; user projects keep their referenced objects inside the ZIP.

Colour-mode contract

Validation and portability

Current readers and writers bound the ZIP to 1 GiB, 10,000 entries, a 16 MiB manifest and 512 MiB per entry. Decoded rasters also have separate geometry and memory limits. Duplicate owned names, missing required data and incompatible samples are rejected.

Embedded sources travel with the project; linked external sources can still require their original paths. Fonts are not embedded. Work on a copy when inspecting an archive, and use the complete reference before implementing a reader.

What the project does not contain

The full Undo command history, interface layout, keyboard shortcuts and local preset catalogues are application state. They are not embedded as an editing session in the portable project.

Crash-recovery checkpoints may use an adjacent shared object store. They are managed application data and must not be confused with a self-contained user .focale archive.

Complete format references

Download the full Markdown specifications in English, including schemas, validation rules and compatibility details.

• Download focale-format.md