> For the complete documentation index, see [llms.txt](https://docs.tempoweave.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tempoweave.com/special-topics/tempoweave-wif-and-twa-file-format-specification.md).

# TempoWeave WIF & TWA File Format Specification

## TempoWeave WIF & TWA File Format Specification

**Version:** 2.5 **Effective:** 2026-11-14 **Author:** LoftyFiber LLC (TempoWeave Studio)

This document describes the WIF (Weaving Information File) and TWA (TempoWeave Archive) file formats as produced and consumed by TempoWeave Studio and TempoWeave Mobile. It is intended as an integration reference for partners implementing read/write support for these files.

The base WIF format follows the **WIF 1.1 specification** (an INI-style weaving interchange standard maintained by the weaving community since 1997). TempoWeave Studio is fully WIF-1.1 compliant and adds a set of optional **WIF 1.1 private sections**, named `[PRIVATE TempoWeave <name>]`, that carry application-specific metadata. As the WIF spec intends, any compliant WIF reader can ignore them safely.

The TWA format is a ZIP-archive container that holds a primary WIF plus optional companion files (section assemblies, writeup HTML, attachments, snapshots). Readers that don't understand TWA can simply extract `twamain.waf` from the archive and treat it as a normal WIF.

***

### 1. WIF File (`.wif`)

A WIF is a UTF-8 plain-text file in classic Windows INI format — case-insensitive section headers in square brackets, `key=value` pairs, semicolon comments. TempoWeave reads and writes WIF 1.1.

#### 1.1 Header sections

**`[WIF]`**

Identifies the file format and producer.

| Key              | Type   | Value                                              |
| ---------------- | ------ | -------------------------------------------------- |
| `Version`        | string | Always `1.1`.                                      |
| `Date`           | string | Long-form local date when the file was written.    |
| `Developers`     | string | Always `LoftyFiber` for TempoWeave-produced files. |
| `Source Program` | string | Always `TempoWeave Studio`.                        |
| `Source Version` | string | Producing version, e.g. `26.520.1`.                |

**`[CONTENTS]`**

Manifest of the standard WIF sections in the file. Each key is the name of a section, value is `true`. TempoWeave builds this list from the sections it actually writes, so it always matches the file: `WEAVING`, `WARP`, `WEFT`, `COLOR PALETTE`, `COLOR TABLE`, `WARP COLORS`, `WEFT COLORS`, `WARP SPACING`, `WEFT SPACING`, `THREADING`, `TEXT`, `NOTES`, and either (`TIEUP` + `TREADLING`) or `LIFTPLAN`, plus any other standard section present. `PRIVATE` sections are never listed.

Before November 2026, `TEXT` and `NOTES` were written but not listed here. A reader that relies on `[CONTENTS]` should still look for those two sections in older TempoWeave files.

**`[WEAVING]`**

Loom geometry.

| Key           | Type    | Notes                                                                                  |
| ------------- | ------- | -------------------------------------------------------------------------------------- |
| `Shafts`      | integer | Number of shafts shown in the draft.                                                   |
| `Treadles`    | integer | Number of treadles shown. Always present even for liftplan WIFs.                       |
| `Rising Shed` | bool    | TempoWeave always writes `true`. Readers should accept `false` for sinking-shed looms. |

**`[TEXT]`**

| Key      | Type   | Notes                     |
| -------- | ------ | ------------------------- |
| `Title`  | string | Pattern title, free-form. |
| `Author` | string | Designer name, free-form. |

**`[NOTES]`**

Up to 5 lines of free-form notes. Keys are `1` through `5`, values are the line text. Empty lines are written as empty values, not omitted.

**`[WARP]`, `[WEFT]`**

Per-axis defaults. TempoWeave writes the following keys:

| Key         | Type    | Notes                                                              |
| ----------- | ------- | ------------------------------------------------------------------ |
| `Units`     | string  | Always `centimeters` in TempoWeave-produced files.                 |
| `Color`     | integer | Index into `[COLOR TABLE]` for the default warp/weft color.        |
| `Threads`   | integer | Total warp ends (for `[WARP]`) or total weft picks (for `[WEFT]`). |
| `Spacing`   | decimal | Default thread spacing in `Units`.                                 |
| `Thickness` | decimal | Default thread thickness in `Units`.                               |

#### 1.2 Color sections

**`[COLOR PALETTE]`**

| Key       | Type    | Notes                                       |
| --------- | ------- | ------------------------------------------- |
| `Range`   | string  | Always `0,255` (8-bit per channel).         |
| `Entries` | integer | Total number of entries in `[COLOR TABLE]`. |

**`[COLOR TABLE]`**

Numbered palette entries (1-based). TempoWeave compacts the saved palette so keys are always sequential `1..N` with no gaps. Each value is `R,G,B` (three decimal integers 0-255).

```ini
[COLOR TABLE]
1=0,0,0
2=255,255,255
3=178,34,34
```

**`[WARP COLORS]`, `[WEFT COLORS]`**

Per-thread color index. Keys are 1-based thread positions; values are 1-based indices into `[COLOR TABLE]`.

```ini
[WARP COLORS]
1=2
2=3
3=2
```

**`[WARP SPACING]`, `[WEFT SPACING]`**

Per-thread spacing override in `Units` from `[WARP]` / `[WEFT]`. Allows variable-thickness yarns within a single warp or weft. Values are decimal, formatted with three decimal places (e.g. `0.212`).

#### 1.3 Structure sections

**`[THREADING]`**

Maps each warp end (1-based) to a shaft number (1-based).

```ini
[THREADING]
1=1
2=2
3=3
4=4
```

**`[TIEUP]` (when `IsLiftplan = false`)**

Maps each treadle (1-based) to a comma-separated list of shafts it raises (1-based).

```ini
[TIEUP]
1=1,4
2=1,2
3=2,3
4=3,4
```

**`[TREADLING]` (when `IsLiftplan = false`)**

Maps each pick (1-based) to a treadle (single-treadle) or comma-separated list of treadles (multi-treadle pickup).

```ini
[TREADLING]
1=1
2=2
3=3
4=1,3      ; multi-treadle pick
```

**`[LIFTPLAN]` (when `IsLiftplan = true`)**

Replaces `[TIEUP]` + `[TREADLING]` with a direct per-pick list of raised shafts. Common for table looms and computer dobby looms. Keys are 1-based pick numbers, values are comma-separated 1-based shafts.

```ini
[LIFTPLAN]
1=1,4
2=1,2
3=2,3
```

A WIF will contain **either** `[TIEUP]+[TREADLING]` **or** `[LIFTPLAN]`, never both. Readers should inspect `[CONTENTS]` to determine which.

***

### 2. TempoWeave-specific WIF extensions

All TempoWeave-added sections follow the WIF 1.1 rule for private sections: `[PRIVATE <SourceID> <SectionName>]`, with `TempoWeave` as the SourceID, for example `[PRIVATE TempoWeave PROJECT]`. Standards-conformant WIF readers should ignore unknown sections; these are safe to skip, and they are not listed in `[CONTENTS]`.

**Older files.** Before version 26.525.1 (May 25, 2026), TempoWeave wrote these sections under bare names: `[TW <name>]` (for example `[TW PROJECT]`) and `[TEMPOWEAVE]` for the grid overlay. Files written since then use only the `PRIVATE` names. TempoWeave still reads both, and also accepts `[PRIVATE <any SourceID> <name>]` for files that passed through another program that re-stamped the SourceID.

| Section                                                            | Before May 2026                                         |
| ------------------------------------------------------------------ | ------------------------------------------------------- |
| `[PRIVATE TempoWeave COLOR NAMES]`                                 | `[TW COLOR NAMES]`                                      |
| `[PRIVATE TempoWeave VARIEGATION]`                                 | `[TW VARIEGATION]`                                      |
| `[PRIVATE TempoWeave PROJECT]`                                     | `[TW PROJECT]`                                          |
| `[PRIVATE TempoWeave OVERLAY]`                                     | `[TEMPOWEAVE]`                                          |
| `[PRIVATE TempoWeave WARP SECTIONMARKERS]` / `WEFT SECTIONMARKERS` | `[TW WARP SECTIONMARKERS]` / `[TW WEFT SECTIONMARKERS]` |
| `[PRIVATE TempoWeave CLOTH CONSTRUCTION]`                          | `[TW CLOTH CONSTRUCTION]`                               |
| `[PRIVATE TempoWeave LOCK]`                                        | `[TW LOCK]`                                             |
| `[PRIVATE TempoWeave DOBBY]`                                       | `[TW DOBBY]`                                            |
| `[PRIVATE TempoWeave THREAD ASSISTANT]`                            | `[TW THREAD ASSISTANT]`                                 |
| `[PRIVATE TempoWeave VIEW]`                                        | `[TW VIEW]`                                             |

Sections added after May 2026 have only the `PRIVATE` name: `[PRIVATE TempoWeave YARN MATERIAL]` (§2.11), `[PRIVATE TempoWeave DRAWLOOM]` (§2.12), `[PRIVATE TempoWeave BLOCKSUB]` (§2.13) and the section gaps (§2.5a). The desktop app also writes `[PRIVATE TempoWeave PRINT OPTIONS]` and `[PRIVATE TempoWeave WARP SECTIONNOTES]` / `WEFT SECTIONNOTES` when used.

#### 2.1 `[PRIVATE TempoWeave COLOR NAMES]`

Optional palette metadata. Present when at least one color has a name, yarn line, or sett record. Keys mirror `[COLOR TABLE]` entries (1-based). Values are CSV: `colorName,yarnLine,yarnThickness[,settWide,settMedium,settClose]`.

```ini
[PRIVATE TempoWeave COLOR NAMES]
3=Cardinal Red,UKI 8/2 Cotton,8,30,24,18
```

| Field           | Type    | Notes                                                     |
| --------------- | ------- | --------------------------------------------------------- |
| `colorName`     | string  | Free-form display name.                                   |
| `yarnLine`      | string  | Yarn line key (e.g. UKI 8/2 Cotton). Maps to the catalog. |
| `yarnThickness` | integer | Thickness code (1=hairline ... 7=very thick).             |
| `settWide`      | decimal | Optional. Wide-sett EPI/PPI.                              |
| `settMedium`    | decimal | Optional. Medium-sett EPI/PPI.                            |
| `settClose`     | decimal | Optional. Close-sett EPI/PPI.                             |

The optional sett triplet appears only when the user has filled it in; absent values may be parsed as zero.

#### 2.2 `[PRIVATE TempoWeave VARIEGATION]`

Optional. Encodes a variegation profile for a palette entry — a color-stop list that interpolates across positions, creating space-dyed yarn effects. Keys mirror `[COLOR TABLE]` entries. Values are a serialized profile (opaque format — see `VariegationProfile.Serialize()` in source).

This section is only present when the user has explicitly defined variegation; standard WIF readers can safely ignore it.

#### 2.3 `[PRIVATE TempoWeave PROJECT]`

Project-level planning metadata. Always present in TempoWeave-produced files. Fields control the Project Info / Cloth Construction tools and do not affect the underlying draft structure.

| Key                      | Type    | Notes                                                           |
| ------------------------ | ------- | --------------------------------------------------------------- |
| `Units`                  | string  | `inches`, `centimeters`, etc. Display unit for project metrics. |
| `Sett`                   | decimal | Target EPI (or per-Units equivalent).                           |
| `Beat`                   | decimal | Target PPI (or per-Units equivalent).                           |
| `DefaultYarnThickness`   | integer | Default thickness for new yarns (1-7).                          |
| `ReedUnits`              | string  | Unit for reed dent measurements.                                |
| `ReedDents`              | integer | Reed dents per `ReedUnits` (e.g. dents per inch).               |
| `ReedSleyPattern`        | string  | Sley pattern, e.g. `1,1,1,2` (free-form CSV).                   |
| `RaddleUnits`            | string  | Unit for raddle dent measurements.                              |
| `RaddleDents`            | integer | Raddle dents per `RaddleUnits`.                                 |
| `RaddleSleyPattern`      | string  | Raddle sley pattern (free-form CSV).                            |
| `OverrideWidthInReed`    | decimal | Manual override (in `Units`). 0 = auto.                         |
| `PlannedWarpLength`      | decimal | Planned warp length in `Units`.                                 |
| `OverrideWovenLength`    | decimal | Manual override. 0 = auto.                                      |
| `FinishLength`           | decimal | Planned finished length in `Units`.                             |
| `TotalFringe`            | decimal | Fringe allowance per piece in `Units`.                          |
| `Sampling`               | decimal | Sampling allowance in `Units`.                                  |
| `FinishedWidth`          | decimal | Target finished width in `Units`.                               |
| `WovenPieces`            | integer | Number of pieces planned from this warp.                        |
| `LoomWaste`              | decimal | Loom waste per warp in `Units`.                                 |
| `WeftTakeup`             | decimal | Weft take-up percentage (e.g. `5.0` = 5%).                      |
| `WarpTakeup`             | decimal | Warp take-up percentage.                                        |
| `DrawIn`                 | decimal | Width draw-in percentage.                                       |
| `LengthShrinkage`        | decimal | Length shrinkage percentage.                                    |
| `WidthShrinkage`         | decimal | Width shrinkage percentage.                                     |
| `Tags`                   | string  | Optional CSV of free-form pattern tags. Omitted if empty.       |
| `FloatingSelvedgeRight`  | bool    | Optional. Only written when `true`.                             |
| `FloatingSelvedgeLeft`   | bool    | Optional. Only written when `true`.                             |
| `FloatingSelvedgeDouble` | bool    | Optional. Only written when `true`.                             |

Decimals use `InvariantCulture` formatting (period as decimal separator).

#### 2.4 `[PRIVATE TempoWeave OVERLAY]`

Grid overlay display preferences. Per-document UI state; safe to ignore for purely structural integrations.

| Key                   | Type    | Notes                                                      |
| --------------------- | ------- | ---------------------------------------------------------- |
| `GridOverlayDrawdown` | bool    | Show grid lines on the drawdown. Lowercase `true`/`false`. |
| `GridOverlayWarp`     | bool    | Show grid on the warp/threading area.                      |
| `GridOverlayTieup`    | bool    | Show grid on the tieup.                                    |
| `GridOverlayWeft`     | bool    | Show grid on the weft/treadling area.                      |
| `GridOverlayShaft`    | integer | Major-grid stride for shafts (e.g. every 4th shaft).       |
| `GridOverlayThread`   | integer | Major-grid stride for warp ends.                           |
| `GridOverlayColor`    | string  | RGB hex without leading `#`, e.g. `505050`.                |

#### 2.5 `[PRIVATE TempoWeave WARP SECTIONMARKERS]`, `[PRIVATE TempoWeave WEFT SECTIONMARKERS]`

Optional. Named segments along the warp or weft axis, used for the Sections tool (visual labels marking pattern repeats, hems, etc.). Keys are 1-based section indices. Values are CSV: `startEnd,name[,localEpi]`.

| Field                      | Type    | Notes                                                                             |
| -------------------------- | ------- | --------------------------------------------------------------------------------- |
| `startEnd`                 | integer | 1-based thread (warp) or pick (weft) where the section begins.                    |
| `name`                     | string  | Section label, may be empty.                                                      |
| `localEpi` (or `localPpi`) | decimal | Optional. Local sett override for this section, formatted with one decimal place. |

Each section runs from its `startEnd` until the start of the next section (or end of axis).

#### 2.5a `[PRIVATE TempoWeave WARP SECTIONGAPS]`, `[PRIVATE TempoWeave WEFT SECTIONGAPS]`

Optional. Per-section reed gap — a deliberate empty space in the reed after the section, used for cram-and-dent designs (#265). Keys are 1-based section indices matching the corresponding SECTIONMARKERS block. Values are decimal measurements in the project's unit at save time (inches when `[PRIVATE TempoWeave PROJECT]` `Units=inches`, centimeters when `Units=centimeters`), formatted with two decimal places.

| Field | Type    | Notes                                 |
| ----- | ------- | ------------------------------------- |
| value | decimal | Gap measurement. 0 / absent = no gap. |

A weaver who wants to leave 0.5" empty after a section enters `0.50`; the Sleying Guide report converts that to a dent count using the project's reed and includes it in the width-in-reed total. Only emitted when at least one section has a non-zero gap.

#### 2.6 `[PRIVATE TempoWeave CLOTH CONSTRUCTION]`

Optional. Cloth-structure metadata for layered fabrics (double cloth, beiderwand, etc.). Present only when the user has set non-default cloth construction parameters.

| Key                   | Type   | Notes                                             |
| --------------------- | ------ | ------------------------------------------------- |
| `ClothFace`           | string | Face-side selector (encoded as a numeric code).   |
| `ClothConstruction`   | string | Construction type identifier.                     |
| `ClothFold`           | string | Fold style (for Folded Cloth).                    |
| `ClothTopLayerShafts` | string | CSV of shaft numbers in the top layer.            |
| `ClothCustomPattern`  | string | Free-form custom double-cloth pattern definition. |

#### 2.7 `[PRIVATE TempoWeave LOCK]`

Optional. Present only when the draft is marked read-only by the author.

| Key           | Type   | Notes                                                    |
| ------------- | ------ | -------------------------------------------------------- |
| `DraftLocked` | string | `1` = locked. Section is omitted entirely when unlocked. |

A locked draft asks any TempoWeave reader to prompt before allowing edits. The lock is advisory — it has no cryptographic enforcement.

#### 2.8 `[PRIVATE TempoWeave DOBBY]`

Optional. Current pick position for the Weave Assistant. Lets a draft resume at the same row after close/reopen.

| Key           | Type    | Notes                                         |
| ------------- | ------- | --------------------------------------------- |
| `CurrentPick` | integer | 1-based current pick. Omitted when at pick 1. |

#### 2.9 `[PRIVATE TempoWeave THREAD ASSISTANT]`

Optional. State of the Thread Assistant feature (tracks which warp ends the weaver has already threaded). Present only when the weaver has actively used Thread Assistant.

| Key            | Type    | Notes                                                                                      |
| -------------- | ------- | ------------------------------------------------------------------------------------------ |
| `ThreadedEnds` | string  | Run-length-encoded threaded-ends list, e.g. `1-8,17-24,41`. Empty if nothing threaded yet. |
| `GroupSize`    | integer | Number of ends per visual group in the threading display. Default `4`.                     |
| `Direction`    | string  | `RightToLeft` (default) or `LeftToRight`.                                                  |
| `StartingEnd`  | integer | 1-based starting end. Default `1`.                                                         |

The `ThreadedEnds` RLE format uses comma-separated ranges and singles: `1-8` = ends 1 through 8 inclusive, `41` = single end 41.

#### 2.10 `[PRIVATE TempoWeave VIEW]`

Optional. View / rendering preferences. Per-document UI state. Safe to ignore for structural integrations.

| Key                 | Type    | Notes                                          |
| ------------------- | ------- | ---------------------------------------------- |
| `BackView`          | string  | `1`/`0`. Show fabric back-side.                |
| `TieupStyle`        | string  | Tieup visual style identifier.                 |
| `GrayscaleDrawdown` | string  | `1`/`0`. Render drawdown in grayscale.         |
| `ShowThickness`     | string  | `1`/`0`. Render variable thread thickness.     |
| `ShowVariegated`    | string  | `1`/`0`. Render variegation profiles.          |
| `ShowInterlacement` | string  | `1`/`0`. Apply interlacement shading.          |
| `GrayscalePalette`  | string  | `1`/`0`. Render palette swatches in grayscale. |
| `YarnBloom`         | integer | Bloom intensity (0 = off).                     |
| `WarpStyle`         | string  | Warp render style identifier.                  |
| `WarpVisible`       | string  | `1`/`0`.                                       |
| `WeftStyle`         | string  | Weft render style identifier.                  |

#### 2.11 `[PRIVATE TempoWeave YARN MATERIAL]`

Optional. What each palette slot's yarn is made of, used by the cloth renderers. Keys are color-table indices (1-based, matching `[COLOR TABLE]`); each value is one line of JSON. Only slots that carry yarn information are written. Kept out of `[PRIVATE TempoWeave COLOR NAMES]` because fiber text can contain commas.

```ini
[PRIVATE TempoWeave YARN MATERIAL]
3={"Fiber":"Wool Merino 50% Tussah Silk 50%","Ply":"2","TwistDir":"S"}
```

| Field                                           | Type        | Notes                                                                              |
| ----------------------------------------------- | ----------- | ---------------------------------------------------------------------------------- |
| `Fiber`                                         | string      | Fiber content as the yarn catalog writes it, or a plain class name such as `Silk`. |
| `Prep`                                          | string      | Finish or preparation, e.g. `Mercerized`, `Superwash`, `slub`.                     |
| `Ply`                                           | string      | Ply count.                                                                         |
| `TwistDir`                                      | string      | `S` or `Z`.                                                                        |
| `CatalogId`                                     | string      | Catalog identifier of the yarn line, when linked.                                  |
| `Drape`, `Elasticity`                           | string      | The catalog line's own notes, free text.                                           |
| `Sheen`, `Fuzz`, `Slub`, `Stiffness`, `Stretch` | decimal 0–1 | Optional overrides. Absent = use the fiber's preset.                               |

Empty fields are omitted. Unknown fields should be ignored.

#### 2.12 `[PRIVATE TempoWeave DRAWLOOM]`

Present only in Pattern & Ground (drawloom) drafts. The rest of the file is a complete standard WIF of the pattern layer as a liftplan draft, so any weaving program can open it. This section carries the full Pattern & Ground draft for TempoWeave: UTF-8 JSON, Base64-encoded and split into chunks of 120 characters.

| Key               | Type    | Notes                           |
| ----------------- | ------- | ------------------------------- |
| `Version`         | integer | `1`.                            |
| `Chunks`          | integer | Number of `Data` keys.          |
| `Data1` … `DataN` | string  | Base64 chunks, joined in order. |

#### 2.13 `[PRIVATE TempoWeave BLOCKSUB]`

Used only in Block Substitution template files.

| Key                     | Type    | Notes                                                                                                               |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `AdjustableBlockLength` | boolean | `true` lets the weaver choose block lengths when applying the template. See the Block Substitution Authoring Guide. |

***

### 3. TWA File (`.twa`)

A TWA is a **standard ZIP archive** with a `.twa` extension. It bundles the primary WIF with optional companion files. Standard ZIP tools can inspect and extract a TWA; the file is not encrypted or proprietary.

#### 3.1 Required entry

| Entry         | Content type | Notes                                                                                                                                           |
| ------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `twamain.waf` | WIF text     | The primary WIF (as specified in §1–§2). The only mandatory entry; readers that don't understand TWA can extract this and treat as a plain WIF. |

#### 3.2 Section Assembly entries (optional)

Section Assembly trees are TempoWeave's hierarchical pattern composition tool (warp/weft built up from named building blocks, color blocks, etc.). These entries store the tree structure as XML. The format is opaque to non-TempoWeave readers — DevExpress TreeList serialization — and need not be preserved if you don't render this view.

| Entry       | Notes                             |
| ----------- | --------------------------------- |
| `twa1.waf`  | Warp Section Assembly tree (XML). |
| `twa1c.waf` | Warp Color Assembly tree (XML).   |
| `twa2.waf`  | Weft Section Assembly tree (XML). |
| `twa2c.waf` | Weft Color Assembly tree (XML).   |

When the underlying draft is regenerated from the assembly tree, the results are persisted to `[THREADING]`, `[TREADLING]`/`[LIFTPLAN]`, `[WARP COLORS]`, `[WEFT COLORS]`, etc. So the WIF is always self-consistent even if the assembly XML is dropped.

#### 3.3 Writeup entries (optional)

The Weaver's Writeup is a rich-text per-pattern note (cover image, "materials", "warping", "weaving" sections, etc.) used for project documentation and PDF export.

| Entry                    | Content type | Notes                                                                                  |
| ------------------------ | ------------ | -------------------------------------------------------------------------------------- |
| `writeup.html`           | HTML         | Free-form HTML body. TempoWeave parses a subset (headings, paragraphs, lists, images). |
| `attachments.json`       | JSON         | Array of attachment records `{fileName, displayName, kind}`.                           |
| `attachments/<filename>` | binary       | Image/file attachments referenced from `writeup.html` by name.                         |

#### 3.4 Snapshot entries (optional)

Snapshots capture named versions of the draft inside the TWA file (teaching workflow). Each snapshot is a full WIF and a thumbnail.

| Entry                | Content type | Notes                                                               |
| -------------------- | ------------ | ------------------------------------------------------------------- |
| `snapshots.json`     | JSON         | Array `{id, name, createdAt, ...}`. `id` is a GUID-like identifier. |
| `snapshots/<id>.wif` | WIF text     | Full draft state at the moment of snapshot.                         |
| `snapshots/<id>.png` | PNG          | Thumbnail (typically \~300×300).                                    |

A `.twa` consumer that doesn't render snapshots should leave these entries intact through any read/modify/write cycle — TempoWeave's mobile writer preserves unknown entries by default.

#### 3.5 Metadata entry (optional)

| Entry           | Content type | Notes                                                                                      |
| --------------- | ------------ | ------------------------------------------------------------------------------------------ |
| `twa-meta.json` | JSON         | TWA-level metadata: format version, app version, last modified. Not strictly required.     |
| `thumbnail.png` | PNG          | Small drawdown picture (256 px) used for file icons and previews. Rewritten on every save. |

#### 3.5a Design entries (optional)

| Entry              | Content type | Notes                                                                                                     |
| ------------------ | ------------ | --------------------------------------------------------------------------------------------------------- |
| `krokbragd.json`   | JSON         | Krokbragd Designer source, so the design stays editable.                                                  |
| `repdesign.json`   | JSON         | Rep Weave Designer source.                                                                                |
| `drawloom.json`    | JSON         | Pattern & Ground (drawloom) draft. `twamain.waf` then holds the pattern-layer liftplan draft (see §2.12). |
| `treadle-map.json` | JSON         | The draft's own treadle mapping for TempoTreadle, when it has one.                                        |

The draft itself is always fully described by `twamain.waf`; these entries only keep the designer tools' own settings.

#### 3.6 Round-trip preservation rule

Producers that don't understand a particular entry should **preserve it verbatim** through any save cycle. This is how TempoWeave Mobile is able to edit drafts originally authored on desktop (with section assemblies, writeup HTML, etc.) without losing those features: the mobile WIF write rebuilds `twamain.waf` but copies all other entries through unchanged.

***

### 4. Integration notes

#### 4.1 WIF compliance

A WIF reader that only implements the standard sections (§1) will work correctly with TempoWeave-produced files. All `[PRIVATE TempoWeave …]` sections (and the older `[TW …]` / `[TEMPOWEAVE]` names) are additive and ignorable.

#### 4.2 Multi-treadle treadling

TempoWeave supports multi-treadle pickup (multiple treadles pressed for a single pick). When `[TREADLING]` values contain commas (e.g. `5=1,3`), the WIF requires multi-treadle support. Readers that expect a single treadle per pick should reject or warn on such files. This is signaled by the presence of comma-separated values; there is no explicit flag in `[CONTENTS]`.

#### 4.3 Liftplan vs. tieup

Standard WIF allows either a `[TIEUP]+[TREADLING]` pair OR a `[LIFTPLAN]` section. TempoWeave writes exactly one of these. Determine which by checking `[CONTENTS]`:

* `LIFTPLAN=true` → use `[LIFTPLAN]`
* `TIEUP=true` and `TREADLING=true` → use the pair

#### 4.4 Color palette compaction

When TempoWeave writes a WIF, it **renumbers** the palette so entries are sequential `1..N` with no gaps, regardless of how the palette was indexed in memory. Per-thread `[WARP COLORS]` / `[WEFT COLORS]` references are remapped to the new indices. Readers should treat the in-file indices as canonical and not assume preservation of original slot numbers.

#### 4.5 Spacing and thickness

Per-thread `[WARP SPACING]` / `[WEFT SPACING]` values are decimal distances in the units declared in `[WARP]` / `[WEFT]`. They override the section-level `Spacing` default. The thickness shown to the user is derived from the spacing relative to a baseline (`SpacingUnit` constant in TempoWeave = `0.0212` cm).

#### 4.6 Character encoding

WIF files are UTF-8 text. Section headers and keys are ASCII. Values may contain non-ASCII (titles, author names, color names, etc.). Avoid the BOM at file start — TempoWeave does not write one.

#### 4.7 Line endings

TempoWeave writes platform-native line endings on save (CR/LF on Windows, LF on macOS/Linux). Readers should be tolerant of either.

#### 4.8 Identifying TempoWeave-produced files

Check `[WIF].Source Program = TempoWeave Studio`. The `Source Version` key gives the producing version (`YY.MMDD.Rev` format). Files with this identifier are guaranteed to follow the conventions described above. Files from other producers may follow standard WIF 1.1 but omit the `[PRIVATE TempoWeave …]` extensions.

***

### 5. Reference

* **WIF 1.1 specification**: <https://www.mhsoft.com/wif/wif1-1.txt>
* **TempoWeave Studio product site**: <https://tempoweave.com>
* **TempoWeave docs**: <https://docs.tempoweave.com>
* **Contact for integration support**: <support@loftyfiber.com>

***

### Appendix A: Minimal example WIF

The smallest valid TempoWeave-produced WIF for a 4-shaft tabby on a 4-treadle floor loom with 4 warp ends and 4 weft picks:

```ini
[WIF]
Version=1.1
Date=March 12, 2026
Developers=LoftyFiber
Source Program=TempoWeave Studio
Source Version=26.312.2

[WEAVING]
Treadles=4
Shafts=4
Rising Shed=true

[CONTENTS]
COLOR PALETTE=true
COLOR TABLE=true
WEAVING=true
WARP=true
WEFT=true
THREADING=true
TIEUP=true
TREADLING=true
WARP COLORS=true
WEFT COLORS=true
WARP SPACING=true
WEFT SPACING=true

[WARP]
Units=centimeters
Color=1
Threads=4
Spacing=0.212
Thickness=0.212

[WEFT]
Units=centimeters
Color=2
Threads=4
Spacing=0.212
Thickness=0.212

[COLOR TABLE]
1=0,0,0
2=255,255,255

[COLOR PALETTE]
Range=0,255
Entries=2

[WARP COLORS]
1=1
2=1
3=1
4=1

[WEFT COLORS]
1=2
2=2
3=2
4=2

[WARP SPACING]
1=0.212
2=0.212
3=0.212
4=0.212

[WEFT SPACING]
1=0.212
2=0.212
3=0.212
4=0.212

[THREADING]
1=1
2=2
3=3
4=4

[TIEUP]
1=1,3
2=2,4

[TREADLING]
1=1
2=2
3=1
4=2

[TEXT]
Title=Tabby Sample
Author=

[NOTES]
1=
2=
3=
4=
5=

[PRIVATE TempoWeave PROJECT]
Units=inches
Sett=24.0
Beat=24.0
DefaultYarnThickness=4
ReedUnits=inches
ReedDents=12
ReedSleyPattern=2
RaddleUnits=inches
RaddleDents=4
RaddleSleyPattern=6
OverrideWidthInReed=0
PlannedWarpLength=0
OverrideWovenLength=0
FinishLength=0
TotalFringe=0
Sampling=0
FinishedWidth=0
WovenPieces=1
LoomWaste=0
WeftTakeup=0
WarpTakeup=0
DrawIn=0
LengthShrinkage=0
WidthShrinkage=0

[PRIVATE TempoWeave OVERLAY]
GridOverlayDrawdown=false
GridOverlayWarp=false
GridOverlayTieup=false
GridOverlayWeft=false
GridOverlayShaft=4
GridOverlayThread=4
GridOverlayColor=505050

[PRIVATE TempoWeave VIEW]
BackView=0
TieupStyle=Default
GrayscaleDrawdown=0
ShowThickness=0
ShowVariegated=0
ShowInterlacement=0
GrayscalePalette=0
YarnBloom=0
WarpStyle=Default
WarpVisible=1
WeftStyle=Default
```
