Versioning

RigWorks uses Semantic Versioning (MAJOR.MINOR.PATCH). One source of truth: VERSION. Document envelopes carry the same value as the root "rig" field.

Range	Meaning
0.x.y	Draft. Grammar floor (entity/component POD + schemas) holds. Live-host conventions (SUDE + runtime ECS) hold. Schemas may grow or tighten.
1.0.0	First stable release. Breaking schema or core-rule changes need a major bump.

Until 1.0.0, prefer additive schema fields - and do not keep dual-field legacy aliases for renamed keys. Tag releases v0.1.0, v0.2.0, ... then v1.0.0.

When you bump VERSION, add a History row below (release notes, not a second source of truth). Do not copy the number into README or elsewhere. npm run check:version checks SemVer + site badges; full CI is npm run check (pre-push after npm run hooks:install).

History

Version	Notes
0.31.0	Additive. `rig.paint.brush` gains contact-patch lag (`lagTipMm` / `lagMaxMm` / `lagP1` / `lagP2`) and tip-to-patch gap (`gapMaxMm`) so a host can warp the tool center ahead of the mark. Example `paint-brush.json`. `rig.layout.paragraph_style` gains `hyphenate` (dictionary hyphenation per style; authored soft hyphens always break) and `alignToBaselineGrid` / `baselineGridFirstLineOnly`; new `rig.layout.grid` - the document baseline grid the flags snap to. A 0.30.0 document is a valid 0.31.0 document.
0.30.0	Additive, plus one breaking (pre-1) rename. Pixel: `rig.pixel.region` / `mask_path` / `composite`; `rig.pixel.raster` `rgba` is optional (`derived` / `rebake` mark size-only buffers); `rig.pixel.source` gains `cast-receive` and replaces `webcam` with `video-device` (`videoDeviceRef` / `videoDeviceName` / `videoWidth` / `videoHeight` - a live video input, not a generic device; no aliases); `rig.pixel.effect_chain` defines branch blend-back for hosts honoring `parentStep`. Paint: `rig.paint.brush` - measured tip facts for a physical brush in a holder; machine mounting, feeds, leads, and dip stations stay host-only. Example `paint-brush.json`. Layout: `rig.layout.table_style` - visual map for `rig.story.table` (cell type, fills, inks; story tables stay content-only); `rig.layout.section` - numbering section start (`numberingStyle` / `startAt` / `prefix` / `startSide`; hosts honour `startSide` by padding with a chrome-free blank); `rig.layout.applied_master` `master` is now optional - the component present with no `master` is an explicit no-master opt-out for true blanks and section pads; `rig.layout.paragraph_style` gains the keep family: `keepFirstLines` (orphans), `keepLastLines` (widows), `keepLastWords` (runts - the paragraph's last line never carries fewer words; the manual NBSP-before-the-last-word trick as a style rule). `rig.story.paragraph_style` gains `keepWithNext` / `keepWithPrevious`; `rig.story.table` gains `columnWidths` (fractional weights; absent = equal columns) and `style` (a specific table_style when one table must differ). `rig.spatial.transform` gains optional `shear` (vec3), composed TRShS. `document.language` (BCP 47, `en-GB`) joins the envelope - hosts pick region-correct hyphenation / spelling from it, which a two-letter code cannot say. Hosts that wrote `x.rigkit.` spellings of these ids migrate to the accepted ids. A 0.29.0 document is a valid 0.30.0 document except `rig.pixel.source` `webcam` / `webcam*` fields.
0.29.0	Additive. FGF / pellet: `rig.print.machine` / `material` / `process` / `compression` / `job`. Machine is the bed and screw; grade temps and density live on material; sag is extra Z, not a second density. Job `input` / `output` are asset entities - not host paths or last-run status. Not envelope `pdfX`, not `rig.dev.machine`, not a layout page - print.md. Example `print-fgf.json`. A 0.28.0 document is a valid 0.29.0 document.
0.28.0	Additive. `rig.layout.frame` - text-frame box (`width` / `height` / `insets` / `columnCount` / `columnGutter` / `firstBaseline` / `firstBaselineMin`). Thread via `rig.layout.frame_chain`; pose on transform; parent is a page. IDML files stay a host mapping - idml.md. Do not invent graphic frames, object styles, wrap, or `rig.idml.*`. Example `story-frames.json`. A 0.27.0 document is a valid 0.28.0 document.
0.27.0	Additive. Reference geometry: `rig.cad.reference_line` (`origin` / `direction` / `a` / `b`) and `rig.cad.reference_plane` (`origin` / `normal` / `a`) - unbounded datums to build against. Both are datums like `rig.cad.dimension`: never solids, never `boolean.operands`. Coordinates place the datum; `a` / `b` anchor it to entities so it follows its parts on rebuild. An axis is a named reference line, not its own id. A 0.26.0 document is a valid 0.27.0 document.
0.26.0	Additive. `rig.layout.page` `margins` / `bleed` / `slug` accept a number or array length 1-6 (CSS-like XY shorthand + optional Z face pair `floor`/`ceiling` on the same local AABB as `rig.spatial.anchor`). Margins inset inward; bleed/slug extend outward. Length 5 sets both Z faces equal. A 0.25.0 document is a valid 0.26.0 document.
0.25.0	Additive. `rig.cad.dimension` - datum between entities (`kind` / `a` / `b` / `value` / `measurement` / `offset`). Driving vs label is `measurement`. Layout emit map: `rig.layout.master` / `applied_master` / `facing` / `paragraph_style` / `character_style` / `frame_chain`. Visual typography stays off `rig.story.*`. A 0.24.0 document is a valid 0.25.0 document.
0.24.0	Additive. Variable font design space: `rig.font.axis` / `rig.font.avar` (child of face) and live lattice `rig.font.cell` on the glyph. Default outline stays `rig.geometry.path`. Example `font-var.json`. A 0.23.0 document is a valid 0.24.0 document.
0.23.0	Breaking (pre-1). Dropped `rig.install.av_bus` - house mute is `rig.audio.bus` `mute`; visuals blackout is fulfillment. Renamed `rig.install.trigger` to `rig.mod.trigger` (discrete sibling of binding). No aliases. Additive: Dev environments - `rig.dev.machine` / `rig.dev.op` (`kind` / `provider` / `base` / `requiresAuth` / `snapshotRef` / `memoryBytes` / `diskBytes` / `cpus` and named ops). Cache fingerprints and credentials stay host-only - dev.md.
0.22.0	Additive. `rig.spatial.vertex` - locator marker; pose on transform. A scene is a root (unparented) vertex, not a second schema. Mesh corners stay packed `positions`. Not `rig.spatial.anchor` (bounds cell) and not `rig.font.anchor`. A 0.21.0 document is a valid 0.22.0 document.
0.21.0	Breaking (pre-1). Enum literals are kebab-case (`top-left`, `color-dodge`, `ease-in-out`) - user-facing choice labels, not field names. Field names stay lowerCamelCase; schema ids stay snake_case. `rig.render.blend` `blendMode` is no longer an exception. No aliases for the old camelCase tokens.
0.20.0	Additive. `rig.render.blend` `blendMode` widens to the W3C Compositing and Blending Level 1 tokens plus `add`, `subtract`, and `disabled`. Hosts may implement a subset; unknown or unimplemented modes treat as `normal`. Literals stay kebab-case (`color-dodge`) as an exception to the lowerCamelCase enum rule. A 0.19.0 document is a valid 0.20.0 document.
0.19.0	Breaking (pre-1). `blendMode` / `opacity` leave `rig.pixel.layer` for new `rig.render.blend` - compose on any drawable (same move as `visible` in 0.13.0). Additive: `rig.paint.stroke_style` (`cap` / `join` / `miterLimit` / `dash` / `dashOffset`; omit when all absent defaults); `rig.render.light` gains `spot`, `range`, `innerConeDegrees`, `outerConeDegrees`; `rig.spatial.anchor` optional `offset` (vec2, after the named cell); path `fillRule` and polygon `fillRule` (clockwise outer in 2D page space is point order, not a `winding` field; holes are opposite-winding path subpaths). Envelope names 2D Y-down / 3D Y-up right-handed −Z-forward - document.md Axes.
0.18.0	Additive. Commerce: `rig.commerce.price` / `offer` / `discount` - ISO 4217 amounts and schema.org Offer / PriceSpecification. Price is a number plus currency, not a formatted string; a sale is another offer or a discount on the offer; the window is `rig.calendar.span`. Legal: `rig.legal.agreement` / `party` - schema.org Contract and ISO 20022 AgreementIdentification. Parties are person / organisation entities; the signed file is `rig.media.asset_ref`; copyright of a work stays on `rig.rights.statement`. Calendar: `rig.calendar.event` / `recurrence` / `attendee`; `exception` gained optional special-hour minutes. Recurrence is `frequency` / `interval` / `count` / `untilDate` / `byWeekday` - not an iCalendar `RRULE` string. A 0.17.0 document is a valid 0.18.0 document.
0.17.0	Additive. `rig.place.address` - structured civic / postal fields whose meanings follow UPU S42 and ISO 20022 `PostalAddress` (the shared type inside financial MX, not the MX message catalog). `rig.place.geo` - WGS84 pin. Person / party: `rig.person.name` / `vital` / `contact` / `employment` / `portrait`, `rig.organisation.identity`, `rig.party.account` - ISO 20022 `PersonName`, `DateAndPlaceOfBirth`, `ContactDetails`, `OrganisationIdentification`, `CashAccount`. Recorded sex is ISO/IEC 5218; `gender` is a separate self-described identity. Plant / botanica: `rig.plant.taxon` / `cultivar` / `habit` / `occurrence` / `portrait` - Darwin Core Taxon / Occurrence, ICNafp, and ICNCP. Book: `rig.book.identifier` / `title` / `publication` / `contribution` / `cover` / `subject` - ISO 2108 ISBN and ONIX for Books `ProductIdentifier`, `TitleDetail`, `PublishingDetail`, `Contributor`, `Subject`. Distinctive title is `rig.meta.named`; authors are person entities. Paper: `rig.paper.identifier` / `article` / `issue` / `citation` - JATS / Crossref article ids and CSL / ISO 690 cite links; authors reuse `rig.book.contribution`. Rights: `rig.rights.statement` - Dublin Core / CC / RightsStatements.org, composed onto any work. Art: `rig.art.object` / `creation` / `attribution` / `dimensions` / `material` / `location` / `subject` / `image` - CDWA core, VRA Core, Object ID. `asset_ref.kind` gained `document`. Photo is an `asset_ref` entity. Compose; do not dual-author unstructured `AdrLine`, `Nm`, or `scientificName`. A 0.16.0 document is a valid 0.17.0 document.
0.16.0	Additive. Font source: `rig.font.*` - `face`, `glyph`, `component`, `anchor`, `layer`, `kern`, `group`. Outlines compose `rig.geometry.path`; AFDKO features compose `rig.media.code` (`language` `fea`) via `face.features`. Glyph / group names live on `rig.meta.named` `stableId`. `.ufo` / `.ufoz` remain host encodings - ufo.md. Do not invent `rig.font.ttf` or grow `rig.media.text` with outlines. A 0.15.0 document is a valid 0.16.0 document.
0.15.0	Additive. OpenBIM: thin `rig.bim.*` layer - `classify`, `type`, `occurrence`, `pset`, `site`, `building`, `storey`, `space`, `relation` (IFC model + bSDD codes); `topic`, `comment`, `viewpoint` (BCF); `spec`, `facet` (IDS). IFC class is a string on `classify` - do not invent `rig.bim.wall`. Optional envelope `ifcSchema` (`ifc2x3` / `ifc4` / `ifc4x3`). `.ifc` / `.bcfzip` / `.ids` remain host encodings - openbim.md. A 0.14.0 document is a valid 0.15.0 document.
0.14.0	Additive. Print: `rig.paint.solid` gained optional `ink` (Separation colorant; empty/absent = process) plus `overprintFill` / `overprintStroke`; envelope gained optional `pdfX`, `outputCondition`, `trapped`. Mesh: optional `loops` / `loopSizes` for authored n-gons. CAD: `rig.geometry.nurbs_surface` and `rig.cad.` solids (`cuboid`, `cylinder`, `sphere`, `extrude`, `revolve`, `boolean`, `fillet`, `chamfer`); mesh on a CAD entity is an optional bake. Story: `rig.story.` editorial flow (`flow`, `paragraph`, `paragraph_style`, `character_style`, `table`) - semantic copy only. Anchor: optional `height` (`min` / `center` / `max`) for a 3×3×3 cuboid cell. Show hosts: `rig.dmx.fixture` patches a `rig.render.light`; `rig.light.look`; `rig.io.dmx`; `rig.audio.bus`; `rig.calendar.weekly` / `span` / `exception`; `rig.install.av_bus` / `trigger`; `rig.sensor.presence`. `rig.io.sacn` gained optional `direction` and `universeCount`; envelope gained optional `timeZone`. A 0.13.0 document is a valid 0.14.0 document.
0.13.0	Breaking (pre-1). New `rig.spatial.anchor` - 3×3 `point`; compose on pages and sized entities; removed `originAnchor` from `rig.layout.page`. Transform stays TRS only. Absent anchor = no remap (centre-authored geometry keeps its centre; pages default trim top-left). Also: `visible` only on `rig.render.visibility` (dropped from `rig.spatial.layer`); text colour via paint (dropped `rgba` on `rig.media.text`); mesh arrays packed `float[]` only; `faceColors` XOR `facePalette`; mesh composes `rig.render.material`; `pixel.layer` chrome uses `order` not `index`.
0.12.0	Additive. `rig.layout.page` gained optional `originAnchor` (`topLeft` / `topRight` / `bottomLeft` / `bottomRight` / `center`; absent = `topLeft`). New `rig.geometry.path3d` and `rig.geometry.spline3d` - 3D siblings of path and spline (`vec3` commands / control points). Cubic Bézier is `cubicTo` on path3d; NURBS stays on spline3d. Do not convert-only through NURBS. A 0.11.0 document is a valid 0.12.0 document.
0.11.0	Breaking field-name sweep: geometry centres / radii are `centerX`/`centerY`/`radiusX`/`radiusY` (no SVG `cx`/`rx`, no dual `radius` on arc). Path commands use `point`/`control1`/`control2`; gradient axes use `start`/`end`; node canvas `position`; curve `interpolation`. Field-naming rules live under `schemas/README.md`. New `rig.geometry.spline`. No dual-field legacy aliases until 1.0.
0.10.0	Additive. `rig.anim.curve` - editable 1D transfer curve (points + interp + named presets). Property datatype table gains `curve`. A 0.9.0 document is a valid 0.10.0 document.
0.9.0	Additive. Portable tool surfaces: `rig.ui.panel` gained `role` and advisory `preferredWidth` / `preferredHeight`; new `rig.ui.group` for nested sections; controls and actions may parent to a `group`. Cross-app / cross-lib tool documents are first-class - see ui.md. A 0.8.0 document is a valid 0.9.0 document.
0.8.0	Additive. The required-field audit: every schema was revisited and genuinely optional fields are now optional with documented defaults, so hosts ship what they measured instead of inventing values (gaps.md had carried this since 0.4.0). Named `colorSpace` on the document envelope (default `srgb`). `rig.music.pattern` gained optional `stepsPerBeat`, `loopStartStep`, `loopEndStep`; `rig.music.step.waveform` widened to 0-255 (8+ are host instrument slots); `rig.pixel.tile_map` gained optional `originX` / `originY`; `rig.sim.rigidbody.gravity` became an optional per-body override; MIDI ports may be identified by `portIndex` as well as `portName`. A 0.7.0 document is a valid 0.8.0 document.
0.7.0	Additive. Completed the shared-paint story: `rig.paint.fill` and `rig.paint.stroke` reference a paint entity from a drawable (the counterpart to inline `rig.paint.fill_stroke`), and `rig.paint.library` records which paint entities are the document's swatches and in what order. Added `rig.layout.page` - pages, artboards, and frames with trim size, margins, bleed, and slug. `rig.media.asset_ref.loop` is now optional - it only means something for time-based media. A 0.6.0 document is a valid 0.7.0 document.
0.6.0	Additive. Component keys may now be `x.<vendor>.<name>` as well as `rig.<domain>.<name>`. Validators pass extension payloads through unchecked and report them as notes, including under `--strict`. Lets a host adopt `.rig` as its native format without dropping components the Contract has not named - see `rig.document`. A 0.5.0 document is a valid 0.6.0 document.
0.5.0	Breaking. Retired `rig.geometry.shape` - the tagged union made every shape carry every other shape's fields. Replaced by eight primitives: `rectangle`, `ellipse`, `line`, `polygon`, `regular_polygon`, `star`, `arc`, `ring`. Circles are ellipses with equal radii, triangles are three-sided regular polygons, and `star.innerRadius` is now an absolute distance rather than a 0-1 ratio. Added `rig.render.visibility`, `rig.meta.tags`, `rig.music.midi_input`, `rig.audio.analysis`, `rig.io.sacn`, `rig.sim.rigidbody`, `rig.sim.particle_emitter`. Added optional `order` to `rig.spatial.relationship` and optional `lane` to `rig.music.pattern`.
0.4.0	Renamed the project from Stitch to RigWorks (Rig for short), under the rigkid org. Schema ids are now `rig.<domain>.<name>`; the document root key is `rig`; the `$id` base is `https://rig.works/schemas/`. Clean break - no aliases for the old `stitch.*` ids.
0.3.0	Last release under the Stitch name.