chore(markdown): Working on v3 docs

markdown/dev/guides/v3/en.md

@@ -0,0 +1,6 @@
+---
+title: Migration guide
+---
+
+- named exports
+- ESM only

markdown/dev/reference/api/design/en.md

@@ -3,42 +3,55 @@ title: Design
 order: 10
 ---
 
-The `Design` object in FreeSewing's core library serves a single purpose:
+The `Design` named export in FreeSewing's core library serves a single purpose:
-To instantiate new pattern designs.
+To create new pattern designs.
 
 ## Design constructor
 
 ```js
-function freesewing.Design(
+import { Design } from "@freesewing/core"
-  object config, 
+
-  object|array plugins, // optional
+const Sorcha = new Design({ 
-  object|array conditionalPlugins // optional
+  // design configuration here
-) 
+})
 ```
 
 This constructor creates a new pattern design.
-It takes the following arguments:
+It takes a single argument, an object holding the design's configuration.
 
-- `config` : The pattern configuration
+## Design configuration
-- `plugins` : Either a [plugin object](/guides/plugins/), or an array of plugin objects
+
-- `conditionalPlugins` : Either a [conditional plugin object](/guides/plugins/conditionally-loading-build-time-plugins/), or an array
+
-  of conditional plugin objects to (conditionally) load in your pattern
+Since a design's configuration is managed at the part level,
+the Design constructor only expects a `parts` attribute that should
+hold an array of parts to include in the Design.
 
 ```js
-import freesewing from "@freesewing/core"
+const Sorcha = new Design({ 
-import plugins from "@freesewing/plugin-bundle"
+  parts: [ front, back, sleeve ],
-import config from "../config"
+})
+```
 
-// Create new design
+<Tip>A Design in FreeSewing is little more than a container for various Parts</Tip>
-const Sorcha = new freesewing.Design(config, plugins)
+
+Optionally, you can also pass it a `data` attrbute 
+to hold any custom data you'd like to add to your Design.
+
+Any `data` you add to the Design constructor will be added
+to [the Store](/reference/api/store).
+
+```js
+const Sorcha = new Design({ 
+  parts: [ front, back, sleeve ],
+  data: {
+    // Your custom data here
+  }
+})
 ```
 
 <Tip>
 
-This method is a _super-constructor_. It will return a constructor
+This Design constructor is a _super-constructor_. 
-method that will become the default export of your design and
+It will return a constructor method that will a pattern based on your design.
-should be called to instantiate your pattern.
-
-See [creating a new pattern design](/howtos/code/create-new-design) for a complete example.
 
 </Tip>

markdown/dev/reference/api/en.md

@@ -6,37 +6,80 @@ This is the documentation for FreeSewing's core library, published as `@freesewi
 It's a complete toolbox for parametric design with a primary focus on
 sewing patterns, but can be utilized for a variety of similar 2D design tasks.
 
-## Getting started
-
-To get started, import the library:
-
-```js
-import freesewing from '@freesewing/core'
-```
-
 <Tip>
 
-This is the reference documentation. For a more hands-on walkthrough,
+##### Looking to get started?
-please refer to our [pattern design tutorial](/tutorials/pattern-design/)
+
+You are currently browsing the reference documentation. 
+Please refer to [the quick start guide](/guides/quick) to get started.
 
 </Tip>
 
-## Properties
+## Named exports
 
-The `@freesewing/core` default export is a single object with the following properties:
+<Note>
 
-- `Design`: The [Design constructor](/reference/api/design/) to create a new design
+Ever since version 3 of FreeSewing, we use only named exports, and no default exports.
+
+Refer to [the migration guide](/guides/v3) for more details.
+
+</Note>
+
+The `@freesewing/core` package provides the following named exports:
+
+
+| Named export | Description |
+| ------------ | ------------|
+| version      | The version of `@freesewing/core` |
+| Bezier       | A re-export of [the bezier-js dependency](https://www.npmjs.com/package/bezier-js) |
+
+The following named exports are **constructors**:
 
 <Note>
 
 You will typically use the `Design()` constructor.  
-The other constructors and utilities below are exported to facilitate unit testing.
+The other constructors and utilities below are exported to 
+facilitate unit testing and other specific use cases.
 
 </Note>
 
-- `Path`: The [Path constructor](/reference/api/path) to create a new path
+| Named export | Description |
-- `Pattern`: The [Pattern constructor](/reference/api/pattern) to create a new pattern
+| ------------ | ------------|
-- `Point`: The [Point constructor](/reference/api/point) to create a new point
+| `Design`     | The [Design](/reference/api/design) constructor |
-- `Snippet`: The [Snippet constructor](/reference/api/snippet) to create a new snippet
+| `Attributes` | The [Attributes](/reference/api/attributes) constructor |
-- `utils`: A collection of [utilities](/reference/api/utils)
+| `Pattern`    | The [Pattern](/reference/api/pattern) constructor |
-- `version`: A string containing the `@freesewing/core` version number
+| `Point`      | The [Point](/reference/api/point) constructor |
+| `Path`       | The [Path](/reference/api/path) constructor |
+| `Part`       | The [Part](/reference/api/part) constructor |
+| `Snippet`    | The [Snippet](/reference/api/snippet) constructor |
+| `Store`      | The [Store](/reference/api/store) constructor |
+
+
+The following named exports are **uitility methods**:
+
+| Named export | Description |
+| ------------ | ------------|
+| `beamIntersectsCircle`    | See the [beamIntersectsCircle](/reference/api/utils/beamintersectsCircle) documentation |
+| `beamIntersectsX`         | See the [beamIntersectsX](/reference/api/utils/beamintersectsX) documentation |
+| `beamIntersectsY`         | See the [beamIntersectsY](/reference/api/utils/) documentation |
+| `beamsIntersect`          | See the [beamsIntersect](/reference/api/utils/beamsintersect) documentation |
+| `capitalize`              | See the [capitalize](/reference/api/utils/capitalize) documentation |
+| `circlesIntersect`        | See the [circlesIntersect](/reference/api/utils/circlesintersect) documentation |
+| `curveEdge`               | See the [curveEdge](/reference/api/utils/curveedge) documentation |
+| `curveIntersectsX`        | See the [curveIntersectsX](/reference/api/utils/curveintersectsX) documentation |
+| `curveIntersectsY`        | See the [curveIntersectsY](/reference/api/utils/curveintersectsY) documentation |
+| `curvesIntersect`         | See the [curvesIntersect](/reference/api/utils/curvesintersect) documentation |
+| `deg2rad`                 | See the [deg2rad](/reference/api/utils/deg2rad) documentation |
+| `generateStackTransform`  | see the [generateStackTransform](/reference/api/utils/generateStackTransform) documentation |
+| `lineIntersectsCircle`    | See the [lineIntersectsCircle](/reference/api/utils/lineintersectsCircle) documentation |
+| `lineIntersectsCurve`     | See the [lineIntersectsCurve](/reference/api/utils/lineintersectsCurve) documentation |
+| `linesIntersect`          | See the [linesIntersect](/reference/api/utils/linesintersect) documentation |
+| `pctBasedOn`              | See the [pctBasedOn](/reference/api/utils/pctbasedon) documentation |
+| `pointOnBeam`             | See the [pointOnBeam](/reference/api/utils/pointonbeam) documentation |
+| `pointOnCurve`            | See the [pointOnCurve](/reference/api/utils/pointoncurve) documentation |
+| `pointOnLine`             | See the [pointOnLine](/reference/api/utils/pointonline) documentation |
+| `rad2deg`                 | See the [rad2deg](/reference/api/utils/rad2deg) documentation |
+| `splitCurve`              | See the [splitCurve](/reference/api/utils/splitcurve) documentation |
+| `stretchToScale`          | See the [stretchToScale](/reference/api/utils/stretchtoscale) documentation |
+| `units`                   | See the [units](/reference/api/utils/units) documentation |
+

markdown/dev/reference/api/part/en.md

@@ -1,22 +1,111 @@
 ---
 title: Part
-order: 20
+order: 15
 ---
 
-The `Part` object in FreeSewing's core library holds all data and logic of a pattern part.
+A `Part` in FreeSewing holds all data, logic, and configuration of a Design.
-A pattern part is what holds the actual information about points and paths,
+Parts truly are the building blocks of FreeSewing as they not only provide
-and multiple parts together typically make up a pattern.
+the configurarion, but also a `draft()` method that does the actual work
+of drafting a parametric design.
 
-## Part properties
+## Part structure
+
+A part is an object with the following properties:
+
+| Property | Description | 
+| -------- | ----------- |
+| `draft`  | The method that will draft the part (__required__) |
+| `measurements` | An array of required measurements |
+| `optionalMeasurements` | An array of optional measurements |
+| `options` | An object of options |
+| `plugins` | A plugin or array of plugins |
+
+## A part's `draft()` method
+
+Each part **must** have a `draft` property that holds a method that will draft the part.
+The method's signature is as follows:
+
+```js
+function draft({
+  Path,
+  Point,
+  Snippet,
+  absoluteOptions,
+  complete,
+  hide,
+  log,
+  macro,
+  measurements,
+  paperless,
+  part,
+  paths,
+  points,
+  scale,
+  snippets,
+  options,
+  sa,
+  store,
+  units,
+  unhide,
+  utils,
+})
+```
+
+The method received a single parameter, an object which you can _destructure_ to 
+access the following properties:
+
+### Provided constructors
 
 | Property | Description |
 | --------:| ----------- |
-| `attributes` | An [Attributes](/reference/api/attributes) instance holding the part's attributes |
+| `Path` | A [Path constructor](/reference/api/path) |
-| `paths` | A plain object to store your paths in |
+| `Point` | A [Point constructor](/reference/api/point) |
-| `points` |  A plain object to store your points in |
+| `Snippet` | A [Snippet constructor](/reference/api/snippet) |
-| `render` |  A flag that controls whether to include the part in the render output |
-| `snippets` | A plain object to store your snippets in |
 
-## Part methods
+### Provided settings
 
-<ReadMore list />
+| Property | Description |
+| --------:| ----------- |
+| `absoluteOptions` | FIXME |
+| `complete` | Holds `settings.complete` |
+| `measurements` | Holds `settings.measurements` |
+| `paperless` | Holds `settings.paperless` |
+| `scale` | Holds `settings.scale` |
+| `options` | Holds `settings.options` |
+| `sa` | Holds `settings.sa` |
+
+### Provided containers
+
+| Property | Description |
+| --------:| ----------- |
+| `paths` | The part's paths container |
+| `points` | The part's points container |
+| `snippets` | The part's snippets container |
+| `store` | Holds the [Store](/reference/api/store) instance that is shared across parts |
+| `utils` | A [Utils](/reference/api/utils) instance with utility methods |
+
+
+### Provided methods
+
+| Property | Description |
+| --------:| ----------- |
+| `hide` | Call `hide()` to hide this part |
+| `units` | A context-aware version of `utils.units` |
+| `unhide` | A context-aware version of `utils.units` |
+
+
+### Other provided properties
+
+| Property | Description |
+| --------:| ----------- |
+| `log` | The default logging object from the store (FIXME) |
+| `macro` | The macro runner. See [the macros documentation](/reference/macros/) |
+| `part` | The part container itself. **You must return this** |
+| `store` | Holds the [Store](/reference/api/store) instance that is shared across parts |
+| `utils` | A [Utils](/reference/api/utils) instance with utility methods |
+
+
+## A part's  `measurements` list
+## A part's  `optionalMeasurements` list
+## A part's  `options` list
+## A part's  `plugin` list

markdown/dev/reference/api/pattern/addpart/en.md

@@ -0,0 +1,44 @@
+---
+title: Pattern.addPart()
+---
+
+The `Pattern.addPart()` method allows you to add a part to a pattern.
+It has the same effect as passing a part to the Design constructor.
+
+<Note>This method is chainable as it returns the Pattern object</Note>
+
+## Pattern.addPart() signature
+
+```js
+Pattern pattern.addPart(object part)
+```
+
+## Pattern.addPart() example
+
+```js
+import { Aaron } from "@freesewing/aaron"
+import { cisFemaleAdult34 } from "@freesewing/models"
+
+const extra = {
+  name: 'aaron.extra',
+  draft: ({ points, Point, paths, Path, part }) => {
+    points.msg = new Point(50,15)
+      .attr('data-text', "I am an extra part")
+    paths.box = new Path()
+      .move(new Point(0,0))
+      .line(new Point(0,30))
+      .line(new Point(100,30))
+      .line(new Point(100,0))
+      .close(new Point(100,0))
+      .addClass('note')
+
+    return part
+  }
+}
+
+const pattern = new Aaron({
+  measurements: cisFemaleAdult34
+}).addPart(extra)
+
+const svg = pattern.draft().render()
+```

markdown/dev/reference/api/pattern/draft/en.md

@@ -2,7 +2,7 @@
 title: Pattern.draft()
 ---
 
-A pattern's `draft()` method will draft all the different pattern parts
+A pattern's `draft()` method will draft the different pattern parts
 making sure to do so in the right order, handle dependencies, resolve
 options to their absolute values and a number of other housekeeping things
 that are required for the pattern to be drafted.
@@ -18,14 +18,11 @@ Pattern pattern.draft()
 ## Pattern.draft() example
 
 ```js
-import Aaron from "@freesewing/aaron"
+import { Aaron } from "@freesewing/aaron"
-import models from "@freesewing/models"
+import { cisFemaleAdult34 } from "@freesewing/models"
 
 const pattern = new Aaron({
-  settings: {
+  measurements: cisFemaleAdult34
-    embed: true,
-  },
-  measurements: models.manSize38
 })
 
 const svg = pattern.draft().render()

markdown/dev/reference/api/pattern/en.md

@@ -1,33 +1,72 @@
 ---
 title: Pattern
-order: 15
+order: 20
 ---
 
 The `Pattern` object in FreeSewing's core library holds all data and logic of a pattern.
-It is the parametric blueprint that when instantiated with a user's measurements and
+It is the parametric blueprint that when instantiated with a user's settings
-objects will generate a made-to-measure pattern.
+can draft a made-to-measure sewing pattern.
 
-## Pattern constructor
+## Creating a Pattern
+
+A Pattern in FreeSewing is an instantiated Design:
 
 ```js
-function freesewing.Pattern(object settings) 
+import { Florence } from "@freesewing/florence"
+
+const pattern = new Florence()
 ```
 
-A pattern is instantiated by passing a [settings object](/reference/api/settings/) to the pattern constructor.
+You probably want to create a pattern using your own [settings](/reference/api/settings):
 
-This settings objects holds, amongst other things, the measurements and options chosen by the user.
+```js
-Refer to the [settings documentation](/reference/api/settings/) for an exhaustive list.
+import { Florence } from "@freesewing/florence"
 
-## Pattern properties
+const pattern = new Florence({
+  paperless: true,
+  measurements: {
+    head: 390,
+  }
+})
+```
 
-- `settings` : The settings as set by the user
+## Multisets in FreeSewing
-- `options` : the options as set by the user
+
-- `config` : The pattern configuration
+You can pass the Pattern constructor an array of multiple settings objects:
-- `parts` : A plain object to hold your parts
+
-- `Part` : The [Part](/reference/api/part) constructor
+```js
-- `store` : A [Store](/reference/api/store) instance
+import { Florence } from "@freesewing/florence"
-- `svg` : An [Svg](/reference/api/svg) instance
+
-- `is` : A string that will be set to `draft` or `sample` when you respectively draft or sample a pattern. This allows plugins that hook into your pattern to determine what to do in a given scenario.
+const pattern = new Florence([
+  {
+    measurements: {
+      head: 390,
+    }
+  },
+  {
+    measurements: {
+      head: 420,
+    }
+  },
+])
+```
+
+We refer to these *multiple sets of settings* as **multisets**.
+It is what powers FreeSewing's [sampling capabilities](/reference/api/pattern/sample) but
+it also allows you to draft some pattern parts with one set of measurements, and other parts
+with another set. For example if you have an asymetric model to fit.
+
+<Note>
+
+##### Core always keeps a set of settings
+
+Multisets is an advanced feature of FreeSewing, and for the most part you can forget about it
+until the day you want to use it.
+
+However, it's good to keep in mind that under the hood, FreeSewing will always use a set of settings.
+It just so happens that in most cases, there will be only one settings object in the set.
+
+</Note>
 
 ## Pattern methods
 

markdown/dev/reference/api/pattern/getconfig/en.md

@@ -0,0 +1,32 @@
+---
+title: Pattern.getConfig()
+---
+
+You can call `Pattern.getConfig()` to retrieve a pattern's runtime configuration.
+
+Doing so will resolve all dependencies, load all the plugins, and do all other
+housekeeping tasks that are typically done behind the scenes when you call
+`Pattern.draft()`. But it will stop short of drafting the pattern, and instead
+return a Pattern's internal configuration.
+
+You can use this to see what options a pattern provides, what
+measurments it requires, and so on.
+
+## Pattern.getConfig() signature
+
+```js
+object pattern.getConfig()
+```
+
+## Pattern.getConfig() example
+
+```js
+import { Aaron } from "@freesewing/aaron"
+import { cisFemaleAdult34 } from "@freesewing/models"
+
+const pattern = new Aaron({
+  measurements: cisFemaleAdult34
+})
+
+const config = pattern.getConfig()
+```

markdown/dev/reference/api/pattern/getcutlist/en.md

@@ -1,47 +0,0 @@
----
-title: Pattern.getCutList()
----
-
-This method will return the cut list, which means the `cut` property of
-all parts that were included in the most recent call to `Pattern.draft()`.
-
-This relies on the pattern designers properly setting the cut property
-in each part.
-
-<Note>This method is chainable as it returns the Pattern object</Note>
-
-## Pattern.getCutList() signature
-
-```js
-Object pattern.getCutList()
-```
-
-## Pattern.getCutList() example
-
-```js
-import Aaron from "@freesewing/aaron"
-import models from "@freesewing/models"
-
-const pattern = new Aaron({
-  settings: {
-    embed: true,
-  },
-  measurements: models.manSize38
-})
-
-const cutList = pattern.draft().getCutList()
-```
-## Cut list format
-
-The object returned by `Pattern.getCutList()` is a plain object
-with a property for each part that will be included in the pattern's output.
-
-The value of these properties is the `cut` property of the part in question.
-
-<Tip>
-Refer to [part.addCut()](/reference/api/part/addcut) for details on the 
-format of a part's `cut` property
-</Tip>
-
-
-

markdown/dev/reference/api/pattern/getrenderprops/en.md

@@ -2,8 +2,8 @@
 title: Pattern.getRenderProps()
 ---
 
-A pattern's `getRenderProps()` method will return a set of properties
+The `Pattern.getRenderProps()` method will return an object that
-that allow the pattern to be rendered be an external renderer such as
+facilitates rendered the pattern by an external renderer such as
 a React component. It should only be called after calling `Pattern.draft()`.
 
 ## Pattern.getRenderProps() signature
@@ -12,35 +12,31 @@ a React component. It should only be called after calling `Pattern.draft()`.
 Object pattern.getRenderProps()
 ```
 
-The object returned by this method contains the following properties:
+## Pattern.getRenderProps() example
+
+```js
+import { Aaron } from "@freesewing/aaron"
+import { cisFemaleAdult34 } from "@freesewing/models"
+
+const pattern = new Aaron({
+  measurements: cisFemaleAdult34
+})
+
+const props = pattern.draft().getRenderProps()
+```
+
+## Pattern.getRenderProps() returned object
+
+The `Pattern.getRenderProps()` method returns an object with 
+the following properties:
 
 | Property | Description |
 | --------:| ----------- |
+| `autoLayout` | An object describing the (automated) pattern layout |
+| `height` | Height of the drafted pattern in `mm` |
+| `logs` | The logs generated by the pattern |
+| `parts` | A plain object holding the drafted parts |
+| `settings` | The (sets of) settings used to draft the pattern |
+| `stacks` | A plain object holding the drafted stacks |
 | `svg` | An [Svg Object](/reference/api/svg/) object with the `preRender` hook applied |
 | `width` | Widht of the drafted pattern in `mm` |
-| `height` | Height of the drafted pattern in `mm` |
-| `settings` | The settings used to draft the pattern |
-| `events` | An object with properties `debug`, `info`, `warning`, and `error` holding events of that type that were generated during the draft of the pattern |
-| `parts` | A plain object holding the drafted parts |
-
-<Tip>
-
-See [the Draft React component](/reference/packages/components/draft/) for more info.
-
-</Tip>
-
-## Pattern.getRenderProps() example
-
-```jsx
-import React from 'react
-import Aaron from "@freesewing/aaron"
-import Draft from "@freesewing/components/Draft"
-
-const MyReactComponent = ({ measurements }) => {
-  const pattern = new Aaron({ measurements })
-
-  return <Draft {...pattern.draft().getRenderProps()} />
-}
-
-export default MyReactComponent
-```

markdown/dev/reference/api/pattern/on/en.md

@@ -2,12 +2,12 @@
 title: Pattern.on()
 ---
 
-A pattern's `on()` method allows you to attach a function to one of the
+The `Pattern.on()` method allows you to attach a function to one of the
 pattern's [lifecycle hooks](/reference/hooks/). It takes the
 lifecycle hook's name as the first argument and the function as the second.
 This method will then be triggered by the lifecycle hook.
 
-<Note>Since FreeSewing v2.19, this method is chainable as it returns the Pattern object</Note>
+<Note>This method is chainable as it returns the Pattern object</Note>
 
 ## Pattern.on() signature
 

markdown/dev/reference/api/pattern/render/en.md

@@ -2,27 +2,24 @@
 title: Pattern.render()
 ---
 
-A pattern's `render()` method will render the pattern to SVG and return
+The `Pattern.render()` method will render the pattern to SVG and return
-the SVG as a string. It should only ever be called after calling
+that SVG as a string. It should only be called after calling
 [Pattern.draft()](/reference/api/pattern/draft/) first.
 
-# Pattern.render() signature
+## Pattern.render() signature
 
 ```js
 string pattern.render()
 ```
 
-# Pattern.render() example
+## Pattern.render() example
 
 ```js
-import Aaron from "@freesewing/aaron"
+import { Aaron } from "@freesewing/aaron"
-import models from "@freesewing/models"
+import { cisFemaleAdult34 } from "@freesewing/models"
 
 const pattern = new Aaron({
-  settings: {
+  measurements: cisFemaleAdult34
-    embed: true,
-  },
-  measurements: models.manSize38
 })
 
 const svg = pattern.draft().render()

markdown/dev/reference/api/pattern/sample/en.md

@@ -2,24 +2,28 @@
 title: Pattern.sample()
 ---
 
-A pattern's `sample()` method will _sample_ the pattern which means
+The `Pattern.sample()` method will _sample_ the pattern which means
-to draft it in different iterations while adjusting the input settings.
+to draft multiple variants of the same pattern, and stack them on
+top of each other.
+
+<Note>This method is chainable as it returns the Pattern object</Note>
+
 Under the hood, this method will call one of
 [Pattern.sampleOption()](/reference/apu/pattern/sampleoption),
 [Pattern.sampleMeasurement()](/reference/apu/pattern/sampleoption), or
 [Pattern.sampleModels()](/reference/apu/pattern/sampleoption) to sample
-an option, a measurement, or a set of measurements respectively.
+an option, a measurement, or different models respectively.
 
 Unlike those three methods where you pass the relevant info to to the method,
-this `Pattern.sample()` will instead read the `pattern.settings.sample`
+this `Pattern.sample()` method will instead read the `settings.sample`
-object to determine what to do.
+object to determine what needs to be done.
 
-The possiblities are:
+The `settings.sample` object can hold the following properties:
 
 - **type**: One of `option`, `measurement`, or `models`
 - **option**: An option name as defined in the pattern config file (only used when `type` is option).
 - **measurement**: A measurement name as defined in the pattern config file (only used when `type` is measurement).
-- **models**: An array of models with the required measurements for this pattern (only used when `type` is models).
+- **models**: A plain object of different models where the key is the model name and the value an object with the required measurements.
 
 See the specific sample methods below for more details:
 
@@ -27,35 +31,6 @@ See the specific sample methods below for more details:
 - [Pattern.sampleMeasurement()](/reference/apu/pattern/sampleoption)
 - [Pattern.sampleModels()](/reference/apu/pattern/sampleoption)
 
-From a lifecycle point of view, the `Pattern.sample()` method is a substitute for
-`Pattern.draft()`. So you call it after instantiating the pattern, prior to
-calling `Pattern.render()`.
-
-<Tip>
-
-###### Anchor your samples
-
-If you add a point named `anchor` to your pattern part, the different samples
-will be anchored on this point.
-
-In other words, for each sample, the anchor point will be kept in the same location.
-
-</Tip>
-
-<Note>This method is chainable as it returns the Pattern object</Note>
-
-<Warning>
-
-##### FreeSewing v3 breaking changes
-
-This method does some juggling under the hood, essentially cramming
-different versions of a pattern into a single Pattern object.
-
-This behavior is likely to change in FreeSewing v3. Refer to [the
-roadmap](https://github.com/freesewing/freesewing/discussions/1278) for details.
-
-</Warning>
-
 ## Pattern.sample() signature
 
 ```js
@@ -65,14 +40,13 @@ Pattern pattern.sample()
 ## Pattern.sample() example
 
 ```js
-import Aaron from "@freesewing/aaron"
+import { Aaron } from "@freesewing/aaron"
-import models from "@freesewing/models"
+import { cisFemaleAdult } from "@freesewing/models"
 
 const pattern = new Aaron({
-  settings: {
+  sample: {
-    embed: true,
+    models: cisFemaleAdult
-  },
+  }
-  measurements: models.manSize38
 })
 
 const svg = pattern.sample().render()

markdown/dev/reference/api/pattern/samplemeasurement/en.md

@@ -2,11 +2,12 @@
 title: Pattern.sampleMeasurement()
 ---
 
-A pattern's `sampleMeasurement()` method will _sample_ a given measurement,
+The `Pattern.sampleMeasurement()` method will _sample_ the pattern which means
-which means to draft it in different iterations while adjusting the input value
+to draft multiple variants of the same pattern, and stack them on
-of the given measurement.
+top of each other.
-In practice, it will draft 10 iterations of the pattern
+
-while adapting the measurement between 90% and 110% of its original value.
+In this particular case, it will draft 10 variants of the pattern that vary
+the measurement of your choice between 90% and 110% if the value in the settings.
 
 <Tip>
 The goal of measurement sampling is to understand the impact of a given measurement on a pattern.
@@ -14,11 +15,6 @@ The goal of measurement sampling is to understand the impact of a given measurem
 
 <Note>This method is chainable as it returns the Pattern object</Note>
 
-<Tip>
-The goal of option sampling is to verify the impact of an option on the pattern, and verify that
-its min and max boundaries are correct and its default value is sensible.
-</Tip>
-
 ## Pattern.sampleMeasurement() signature
 
 ```js
@@ -28,10 +24,12 @@ Pattern pattern.sampleMeasurement(string measurement)
 ## Pattern.sampleMeasurement() example
 
 ```js
-import Aaron from "@freesewing/aaron"
+import { Aaron } from "@freesewing/aaron"
-import models from "@freesewing/models"
+import { cisFemaleAdult34 } from "@freesewing/models"
 
-const pattern = new Aaron({ measurements: models.manSize38 })
+const pattern = new Aaron({
+  measurements: cisFemaleAdult34
+})
 
-const svg = pattern.sampleMeasurement("chest").render()
+const svg = pattern.draft().sampleMeasurement('chest')
 ```

markdown/dev/reference/api/pattern/samplemodels/en.md

@@ -2,9 +2,11 @@
 title: Pattern.sampleModels()
 ---
 
-A pattern's `sampleModels()` method will _sample_ a pattern for a list of
+The `Pattern.sampleModels()` method will _sample_ the pattern which means
-models you pass to it. It will draft different iterations of the pattern,
+to draft multiple variants of the same pattern, and stack them on
-using the measurements for each model you pass to it.
+top of each other.
+
+In this particular case, it will draft a variants for each of the models you pass it.
 
 <Tip>
 The goal of model sampling is to verify that a pattern grades correctly up and down as sizes change.
@@ -12,24 +14,13 @@ The goal of model sampling is to verify that a pattern grades correctly up and d
 
 <Note>This method is chainable as it returns the Pattern object</Note>
 
-<Tip>
-
-###### Anchor your samples
-
-If you add a point named `anchor` to your pattern part, the different samples
-will be anchored on this point.
-
-In other words, for each sample, the anchor point will be kept in the same location.
-
-</Tip>
-
 ## Pattern.sampleModels() signature
 
 ```js
 Pattern pattern.sampleModels(object models, string focus)
 ```
 
-The models object you pass as the first parameter should be structured as such:
+The `models` object you pass as the first parameter should be structured as such:
 
 ```js
 {
@@ -61,10 +52,10 @@ identifying your model in the models object.
 ## Pattern.sampleModels() example
 
 ```js
-import Aaron from "@freesewing/aaron"
+import { Aaron } from "@freesewing/aaron"
-import models from "@freesewing/models"
+import { cisFemaleAdult } from "@freesewing/models"
 
 const Aaron = new Aaron()
 
-const svg = aaron.sampleModels(models, "manSize38").render()
+const svg = aaron.sampleModels(cisFemaleAdult, "34').render()
 ```

markdown/dev/reference/api/pattern/sampleoption/en.md

@@ -2,15 +2,19 @@
 title: Pattern.sampleOption()
 ---
 
-A pattern's `sampleOption()` method will _sample_ a given option,
+The `Pattern.sampleOption()` method will _sample_ the pattern which means
-which means to draft it in different iterations while adjusting the input value
+to draft multiple variants of the same pattern, and stack them on
-of the given option.
+top of each other.
-The practical implementation varies based on [the type of option](/config/options/):
+
+In this particular case, the variants it drafts depend
+ on [the type of option](/config/options/):
 
 - For options that are an object with a **min** and **max** property, 10 steps will be sampled, between min and max
 - For options that are a numeric value (**constants**), 10 steps will be sampled between 90% and 110% of the value
 - For options with a **list** of options, each option in the list will be sampled
 
+<Fixme>Handle other option types</Fixme>
+
 <Tip>
 The goal of option sampling is to verify the impact of an option on the pattern, and verify that
 its min and max boundaries are correct and its default value is sensible.
@@ -18,17 +22,6 @@ its min and max boundaries are correct and its default value is sensible.
 
 <Note>This method is chainable as it returns the Pattern object</Note>
 
-<Tip>
-
-###### Anchor your samples
-
-If you add a point named `anchor` to your pattern part, the different samples
-will be anchored on this point.
-
-In other words, for each sample, the anchor point will be kept in the same location.
-
-</Tip>
-
 ## Pattern.sampleOption() signature
 
 ```js
@@ -38,12 +31,12 @@ Pattern pattern.sampleOption(string option)
 ## Pattern.sampleOption() example
 
 ```js
-import Aaron from "@freesewing/aaron"
+import { Aaron } from "@freesewing/aaron"
-import models from "@freesewing/models"
+import { cisFemaleAdult34 } from "@freesewing/models"
 
-const pattern = new aaron({
+const pattern = new Aaron({
-  measurements: models.manSize38
+  measurements: cisFemaleAdult34
 })
 
-const svg = pattern.sampleOption("necklineDrop").render()
+const svg = pattern.draft().sampleMeasurement('chest')
 ```

markdown/dev/reference/api/pattern/use/en.md

@@ -2,10 +2,9 @@
 title: Pattern.use()
 ---
 
-A pattern's `use()` method will load a FreeSewing plugin.
+The `Pattern.use()` method will load a FreeSewing plugin.
-Plugins are a way to extend a pattern's functionality, and can be
+Plugins are a way to extend a pattern's functionality.
-loaded both at build-time and at run-time. This method only applies
+For more details, refer to [the plugin guide](/guides/plugins/).
-to run-time plugins. For more details, refer to [the plugin guide](/guides/plugins/).
 
 <Note>This method is chainable as it returns the Pattern object</Note>
 
@@ -21,16 +20,13 @@ you plugin object.
 ## Pattern.use() example
 
 ```js
-import Aaron from "@freesewing/aaron"
+import { Aaron } from "@freesewing/aaron"
-import models from "@freesewing/models"
+import { cisFemaleAdult34 } from "@freesewing/models"
-import theme from "@freesewing/theme"
+import { pluginTheme } from "@freesewing/plugin-theme"
 
 const pattern = new Aaron({
-  settings: {
+  measurements: cisFemaleAdult34
-    embed: true,
+}).use(pluginTheme)
-  },
-  measurements: models.manSize38
-}).use(theme)
 
 const svg = pattern.draft().render()
 ```