The Asunder Knit .knit File Format

Last updated: September 22, 2026

This is a technical reference for the Asunder Knit .knit file format, intended for anyone reading, generating, or reverse-engineering a saved file. It describes what the current release of Asunder Knit writes and reads.

1. Container format

A newly saved .knit file is a ZIP archive containing manifest.json and document.json. The filename takes the form knit_2026-09-22T14-32-05.knit — an ISO 8601 timestamp with colons and periods replaced by hyphens.

The manifest identifies the archive format (1.0.0) and its serialized plugins. document.json maps each plugin name to an envelope containing pluginName, version, and data. The current sections are:

• KNIT_CHART_STATE@1 — the V5 chart payload described below.
• KNIT_SIM_STATE@1 — V1 simulation settings, including both pin-corner options, backside view, subdivision, and yarn fullness overrides.
• SYSTEM_CONFIG@1 — document identity and the shared serialized configuration.
• @mm/store-layout-manager — saved UI layout.

Legacy files are plain UTF-8 JSON charts. The loader detects ZIP versus JSON from the contents, accepts legacy V1–V5 charts, and upgrades them on load. Legacy charts receive fixed simulation defaults and a new document identity. The file picker accepts .knit and .json; the suffix does not determine the format.

2. The version field

The chart payload's version is a number from 1 through 5. It is separate from the archive and plugin envelope versions, which are 1.0.0. Simulation settings have their own numeric version, currently 1. These are versions of different schemas, not one file-wide counter.

• Version 1 — legacy. A flat cell array plus an explicit dimensions object. Read-only: the current release loads it but never writes it.
• Version 2 — legacy flat format. Introduced the jagged rows array described below.
• Version 3 — legacy round format. It added knittingMode: "round" and optional topClosure.
• Version 4 — legacy all-mode format. It introduced turn symbols for short rows.
• Version 5 — the current chart format. It replaces the independent round topClosure setting with the complete roundForm construction.

The chart serializer always writes version 5 inside the archive. Legacy versions 1–5 remain readable; saving them produces an archive with a V5 chart. Unsupported chart versions are rejected. A legacy round topClosure: "cinch" migrates to roundForm: "hat"; an absent or "bind-off" closure migrates to "tube". No legacy file is inferred to be the planar "flat" round form.

3. Document shape

The V5 chart section’s data has these keys for a flat chart:

{
  "version": 5,
  "meta": { "title": "Untitled", "createdAt": "...", "updatedAt": "..." },
  "castOnWidth": 24,
  "knittingMode": "flat-rs-start",
  "gauge": { "stitchesPerUnit": 5, "rowsPerUnit": 7, "unit": "inch" },
  "rows": [ [ ... ], [ ... ] ],
  "yarns": [ ... ],
  "repeatGroups": [ ... ]
}

A round V5 chart payload adds the required roundForm discriminator:

{
  "version": 5,
  "meta": { "title": "Untitled", "createdAt": "...", "updatedAt": "..." },
  "castOnWidth": 60,
  "knittingMode": "round",
  "roundForm": "hat",
  "gauge": { "stitchesPerUnit": 5, "rowsPerUnit": 7, "unit": "inch" },
  "rows": [ ... ],
  "yarns": [ ... ],
  "repeatGroups": [ ... ]
}

• version — 5 for every chart payload written by the current release.
• meta — title and timestamps; see section 4.
• castOnWidth — the cast-on stitch count. See section 9.
• knittingMode — "flat-rs-start", "flat-ws-start", or "round".
• roundForm — required when knittingMode is "round" and forbidden otherwise; "tube", "hat", or "flat".
• gauge — stitches and rows per unit, and the unit.
• rows — the stitch grid.
• yarns — the yarn palette.
• repeatGroups — repeat regions.
• customStitches — optional document-scoped stitch definitions.
• thumbnail — optional preview payload preserved when present.

4. meta

meta is { title, createdAt, updatedAt }. The loader retains the document's title and creation timestamp. Saving preserves those two values and stamps only updatedAt with the current time. A missing title defaults to "Untitled", and a missing creation timestamp defaults to the load time.

5. The stitch grid

rows is a jagged, row-major array of arrays: rows[row][col]. Each row may be a different length. Row 0 is the bottom of the chart — the first row knitted — and rows count upward from there.

The chart's working width is derived from stitch content, not from array length. Trailing empty cells carry no width, so a row's array length is not a reliable measure of its stitch count. The effective cast-on width is derived from the stitches the first worked row consumes; the stored castOnWidth is a creation-time value retained for reference.

6. Cell encoding

Each cell is encoded compactly with up to three optional keys, and takes one of three forms:

• No stitch (empty / erased) — the empty object {}.
• A worked stitch — { "s": stitchId, "y": yarnId }.
• A cable continuation — { "c": [anchorCol, anchorRow] }, pointing back to the anchor cell of a multi-column stitch.

[
  {},
  { "s": "knit", "y": "id_0" },
  { "s": "2/2 RC", "y": "id_1" },
  { "c": [2, 5] }
]

The three keys are: s (stitch id), y (yarn id), and c (the [column, row] anchor coordinate for a continuation). A wide stitch such as a cable occupies one anchor cell carrying s and y, followed by c continuation cells whose coordinates point back to that anchor. If a stitch cell omits y, the loader falls back to the first yarn in the palette.

7. Stitch ids and the library

A cell stores only a stitch id string in s. Ids normally resolve against Asunder Knit's built-in stitch library of 38 stitches — knits and purls, slips, twisted stitches, and a large family of decreases and increases (for example knit, purl, k2tog, ssk, yo, m1l, cdd).

A file may additionally carry customStitches. Those definitions are available only while that document is open and are preserved verbatim when it is saved. A custom definition cannot replace a built-in with the same id; built-in semantics win.

Cables use structured span ids as the s string, in the form "2/2 RC", "1/1 LC", or "2/1 LPC" (columns held front/back, then lean and purl markers). There are 20 preset cable spans, and arbitrary custom spans resolve directly from their id without a library entry.

8. Yarns and the physical yarn model

yarns is the palette. Cells reference a yarn by its id. Each entry is { id, name, color, model }, where color is a 6-digit hex string and is treated as the yarn's unique key — no two palette entries share a color.

{
  "id": "id_0",
  "name": "Worsted Wool",
  "color": "#9d5821",
  "model": {
    "id": "id_0",
    "name": "Worsted Wool",
    "fibers": [ { "fiber": "wool", "percentage": 100 } ],
    "wpiThickness": 9,
    "plyCount": 3,
    "twistDirection": "Z",
    "tpi": 4,
    "convention": "knitting",
    "color": "#9d5821",
    "gristTex": 98,
    "elasticityMPa": 12,
    "frictionMu": 0.3,
    "stiffnessEI": 0.0004,
    "compressibilityKPa": 40,
    "sheen": 0.2
  }
}

model is the full physical yarn model (shared with Asunder's weaving app, Bower). It captures fiber content as a blend that sums to 100%, thickness in wraps-per-inch, ply count and twist (S or Z direction, turns-per-inch), spinning convention, and the physical constants the 3D yarn simulation needs — grist (linear density), elasticity, friction, bending stiffness, compressibility, and sheen. The current release always writes model; it is optional in the schema only so that files predating the physical model still load.

9. Gauge, cast-on, and mode

10. Repeat groups

repeatGroups is an array of repeat regions. Each carries an id, a repeatCount, an optional label, and a rows map from row index to a { startCol, endCol } span.

{
  "id": "id_7",
  "repeatCount": 4,
  "label": "Cable panel",
  "rows": {
    "0": { "startCol": 2, "endCol": 9 },
    "1": { "startCol": 2, "endCol": 9 }
  }
}

11. What is not in the file

Simulation settings are saved, but the 3D yarn simulation’s baked geometry, running state, progress, and device/backend selection are not. Restoring a document leaves simulation stopped. PNG, SVG, and PDF outputs are separate one-way exports, not part of the chart document.

Two optional compatibility payloads may appear: thumbnail and customStitches. The current UI does not create them, but the loader reads them and the serializer writes them back unchanged, so opening and saving a file does not discard schema-supported data.

12. Load validation and recovery

Loading does more than parse JSON. The loader enforces several consistency rules and repairs a few classes of damage rather than failing outright:

• Version gate — only chart versions 1 through 5 load; anything else is rejected.
• Mode matches version — a version 1 or 2 file must be flat, and a version 3 file must be round. Versions 4 and 5 accept every supported knitting mode. A mismatch is rejected.
• Yarn models are validated — fiber percentages must sum to 100, colors must be hex, twist must be S or Z, and physical constants must be positive.
• Duplicate colors are folded — palette entries sharing a color are merged and the affected cells repointed, upholding the one-color-per-yarn rule.
• Missing yarns are recovered — a cell that names a yarn absent from the palette is repointed onto a single grey "Recovered" yarn instead of crashing.
• Cable anchors are repaired — continuation cells naming a stale anchor row are re-anchored on load.

Loading is transactional: the loader snapshots the current document, attempts the load, and on any error rolls back to the snapshot, so a corrupt file cannot leave a half-loaded chart. The same archive serialization backs browser autosave in IndexedDB, including chart, simulation settings, shared configuration, and layout. Legacy localStorage recovery is migrated and removed only after the archive write commits. If recovery cannot be read, it is retained and autosave is paused until a successful explicit Open or New Chart.

13. Compatibility and versioning

• Files use the .knit suffix, and .json is also accepted on load.
• The app writes ZIP archives containing a V5 chart, whether flat-knitted or round.
• Legacy JSON versions 1–5 still load; saving produces the new archive format.
• Older app builds cannot open the new archives. Keep an original legacy file if you need it in an older build.

Open Asunder Knit and save a chart to inspect the format directly →