From a7845054cca3e57c920fe5554d41d5fed0301b52 Mon Sep 17 00:00:00 2001
From: Connor Skees <39542938+connorskees@users.noreply.github.com>
Date: Thu, 5 Oct 2023 14:50:54 -0700
Subject: [PATCH 01/51] Add first class mixins to embedded sass protobuf and JS
 API (#3674)

---
 js-api-doc/index.d.ts           |  1 +
 js-api-doc/value/index.d.ts     | 10 +++++++++
 js-api-doc/value/mixin.d.ts     | 14 ++++++++++++
 spec/EMBEDDED_PROTOCOL_VERSION  |  2 +-
 spec/embedded_sass.proto        | 12 ++++++++++
 spec/js-api/index.d.ts.md       |  1 +
 spec/js-api/value/index.d.ts.md | 15 +++++++++++++
 spec/js-api/value/mixin.d.ts.md | 40 +++++++++++++++++++++++++++++++++
 8 files changed, 94 insertions(+), 1 deletion(-)
 create mode 100644 js-api-doc/value/mixin.d.ts
 create mode 100644 spec/js-api/value/mixin.d.ts.md

diff --git a/js-api-doc/index.d.ts b/js-api-doc/index.d.ts
index 395c5ced..2a41b586 100644
--- a/js-api-doc/index.d.ts
+++ b/js-api-doc/index.d.ts
@@ -40,6 +40,7 @@ export {
   SassFunction,
   SassList,
   SassMap,
+  SassMixin,
   SassNumber,
   SassString,
   Value,
diff --git a/js-api-doc/value/index.d.ts b/js-api-doc/value/index.d.ts
index c9711da1..38d28df8 100644
--- a/js-api-doc/value/index.d.ts
+++ b/js-api-doc/value/index.d.ts
@@ -6,6 +6,7 @@ import {SassColor} from './color';
 import {SassFunction} from './function';
 import {ListSeparator} from './list';
 import {SassMap} from './map';
+import {SassMixin} from './mixin';
 import {SassNumber} from './number';
 import {SassString} from './string';
 
@@ -22,6 +23,7 @@ export {SassColor} from './color';
 export {SassFunction} from './function';
 export {SassList, ListSeparator} from './list';
 export {SassMap} from './map';
+export {SassMixin} from './mixin';
 export {SassNumber} from './number';
 export {SassString} from './string';
 
@@ -156,6 +158,14 @@ export abstract class Value implements ValueObject {
    */
   assertMap(name?: string): SassMap;
 
+  /**
+   * Throws if `this` isn't a {@link SassMixin}.
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertMixin(name?: string): SassMixin;
+
   /**
    * Throws if `this` isn't a {@link SassNumber}.
    *
diff --git a/js-api-doc/value/mixin.d.ts b/js-api-doc/value/mixin.d.ts
new file mode 100644
index 00000000..44af9967
--- /dev/null
+++ b/js-api-doc/value/mixin.d.ts
@@ -0,0 +1,14 @@
+import {Value} from './index';
+
+/**
+ * Sass's [mixin type](https://sass-lang.com/documentation/values/mixins).
+ *
+ * @category Custom Function
+ */
+export class SassMixin extends Value {
+  /**
+   * It is not possible to construct a Sass mixin outside of Sass. Attempting to
+   * construct one will throw an exception.
+   */
+  constructor();
+}
diff --git a/spec/EMBEDDED_PROTOCOL_VERSION b/spec/EMBEDDED_PROTOCOL_VERSION
index ccbccc3d..276cbf9e 100644
--- a/spec/EMBEDDED_PROTOCOL_VERSION
+++ b/spec/EMBEDDED_PROTOCOL_VERSION
@@ -1 +1 @@
-2.2.0
+2.3.0
diff --git a/spec/embedded_sass.proto b/spec/embedded_sass.proto
index 7a931d69..b0307006 100644
--- a/spec/embedded_sass.proto
+++ b/spec/embedded_sass.proto
@@ -887,6 +887,17 @@ message Value {
     string signature = 2;
   }
 
+  // A first-class mixin defined in the compiler. New `CompilerMixin`s may
+  // only be created by the compiler, but the host may pass `CompilerMixin`s
+  // back to the compiler as long as their IDs match IDs of mixins received
+  // by the host during that same compilation.
+  message CompilerMixin {
+    // A unique ID for this mixin. The compiler is responsible for generating
+    // this ID and ensuring it's unique across all mixins passed to the host
+    // for this compilation. Mandatory.
+    uint32 id = 1;
+  }
+
   // A SassScript argument list value. This represents rest arguments passed to
   // a function's `$arg...` parameter. Unlike a normal `List`, an argument list
   // has an associated keywords map which tracks keyword arguments passed in
@@ -1000,6 +1011,7 @@ message Value {
     ArgumentList argument_list = 10;
     HwbColor hwb_color = 11;
     Calculation calculation = 12;
+    CompilerMixin compiler_mixin = 13;
   }
 }
 
diff --git a/spec/js-api/index.d.ts.md b/spec/js-api/index.d.ts.md
index 8d15838c..e57fd0dd 100644
--- a/spec/js-api/index.d.ts.md
+++ b/spec/js-api/index.d.ts.md
@@ -77,6 +77,7 @@ export {
   SassFunction,
   SassList,
   SassMap,
+  SassMixin,
   SassNumber,
   SassString,
   Value,
diff --git a/spec/js-api/value/index.d.ts.md b/spec/js-api/value/index.d.ts.md
index 48cc67ed..654f2f4c 100644
--- a/spec/js-api/value/index.d.ts.md
+++ b/spec/js-api/value/index.d.ts.md
@@ -9,6 +9,7 @@ import {SassColor} from './color';
 import {SassFunction} from './function';
 import {ListSeparator} from './list';
 import {SassMap} from './map';
+import {SassMixin} from './mixin';
 import {SassNumber} from './number';
 import {SassString} from './string';
 
@@ -25,6 +26,7 @@ export {SassColor} from './color';
 export {SassFunction} from './function';
 export {SassList, ListSeparator} from './list';
 export {SassMap} from './map';
+export {SassMixin} from './mixin';
 export {SassNumber} from './number';
 export {SassString} from './string';
 ```
@@ -48,6 +50,7 @@ export {SassString} from './string';
     * [`assertColor`](#assertcolor)
     * [`assertFunction`](#assertfunction)
     * [`assertMap`](#assertmap)
+    * [`assertMixin`](#assertmixin)
     * [`assertNumber`](#assertnumber)
     * [`assertString`](#assertstring)
     * [`tryMap`](#trymap)
@@ -231,6 +234,18 @@ Return `this.tryMap()` if it's not null, and throw an error otherwise.
 assertMap(name?: string): SassMap;
 ```
 
+#### `assertMixin`
+
+Returns `this` if it's a [`SassMixin`] and throws an error otherwise.
+
+[`SassMixin`]: mixin.d.ts.md
+
+> The `name` parameter may be used for error reporting.
+
+```ts
+assertMixin(name?: string): SassMixin;
+```
+
 #### `assertNumber`
 
 Returns `this` if it's a [`SassNumber`] and throws an error otherwise.
diff --git a/spec/js-api/value/mixin.d.ts.md b/spec/js-api/value/mixin.d.ts.md
new file mode 100644
index 00000000..3835e872
--- /dev/null
+++ b/spec/js-api/value/mixin.d.ts.md
@@ -0,0 +1,40 @@
+# Mixin API
+
+```ts
+import {Value} from './index';
+```
+
+## Table of Contents
+
+* [Types](#types)
+  * [`SassMixin`](#sassmixin)
+    * [`internal`](#internal)
+    * [Constructor](#constructor)
+
+## Types
+
+### `SassMixin`
+
+The JS API representation of a Sass mixin.
+
+```ts
+export class SassMixin extends Value {
+```
+
+#### `internal`
+
+The [private `internal` field] refers to a Sass mixin.
+
+[private `internal` field]: index.d.ts.md#internal
+
+#### Constructor
+
+Throws an error.
+
+```ts
+constructor();
+```
+
+```ts
+} // SassMixin
+```

From 1de725630ef99f7e3ed2c4d345f71acc36f31c07 Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <jamesnw@gmail.com>
Date: Fri, 6 Oct 2023 10:32:35 -0400
Subject: [PATCH 02/51] Remove generic change overload

---
 proposal/color-4-new-spaces-js.changes.md |  4 ++++
 proposal/color-4-new-spaces-js.d.ts.md    | 18 ++++++------------
 2 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/proposal/color-4-new-spaces-js.changes.md b/proposal/color-4-new-spaces-js.changes.md
index 703be397..ed4af5a7 100644
--- a/proposal/color-4-new-spaces-js.changes.md
+++ b/proposal/color-4-new-spaces-js.changes.md
@@ -1,3 +1,7 @@
+## Draft 1.2
+
+* Remove generic `change` overload, and make `space` optional on others.
+
 ## Draft 1.1
 
 * Clarify values in `channels` and `channelsOrNull`.
diff --git a/proposal/color-4-new-spaces-js.d.ts.md b/proposal/color-4-new-spaces-js.d.ts.md
index 9648876e..84fe1fe6 100644
--- a/proposal/color-4-new-spaces-js.d.ts.md
+++ b/proposal/color-4-new-spaces-js.d.ts.md
@@ -565,18 +565,12 @@ as the result of changing some of [`internal`]'s components.
 [`Changing a Component Value`]: #changing-a-component-value
 
 ```ts
-change(
-  options: {
-    [key in ChannelName]?: number | null;
-  } & {alpha?: number}
-): SassColor;
-
 change(
   options: {
     [key in ChannelNameHSL]?: number | null;
   } & {
     alpha?: number;
-    space: ColorSpaceHSL;
+    space?: ColorSpaceHSL;
   }
 ): SassColor;
 
@@ -585,7 +579,7 @@ change(
     [key in ChannelNameHWB]?: number | null;
   } & {
     alpha?: number;
-    space: ColorSpaceHWB;
+    space?: ColorSpaceHWB;
   }
 ): SassColor;
 
@@ -594,7 +588,7 @@ change(
     [key in ChannelNameLab]?: number | null;
   } & {
     alpha?: number | null;
-    space: ColorSpaceLab;
+    space?: ColorSpaceLab;
   }
 ): SassColor;
 
@@ -603,7 +597,7 @@ change(
     [key in ChannelNameLCH]?: number | null;
   } & {
     alpha?: number | null;
-    space: ColorSpaceLCH;
+    space?: ColorSpaceLCH;
   }
 ): SassColor;
 
@@ -612,7 +606,7 @@ change(
     [key in ChannelNameRGB]?: number | null;
   } & {
     alpha?: number | null;
-    space: ColorSpaceRGB;
+    space?: ColorSpaceRGB;
   }
 ): SassColor;
 
@@ -621,7 +615,7 @@ change(
     [key in ChannelNameXYZ]?: number | null;
   } & {
     alpha?: number | null;
-    space: ColorSpaceXYZ;
+    space?: ColorSpaceXYZ;
   }
 ): SassColor;
 ```

From f2c8291a0de1e0354f5c91bd3f777ff50a3f343a Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <jamesnw@gmail.com>
Date: Fri, 6 Oct 2023 10:45:36 -0400
Subject: [PATCH 03/51] Return immutable types

---
 proposal/color-4-new-spaces-js.changes.md | 3 +++
 proposal/color-4-new-spaces-js.d.ts.md    | 6 ++++--
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/proposal/color-4-new-spaces-js.changes.md b/proposal/color-4-new-spaces-js.changes.md
index ed4af5a7..b7271cfe 100644
--- a/proposal/color-4-new-spaces-js.changes.md
+++ b/proposal/color-4-new-spaces-js.changes.md
@@ -2,6 +2,9 @@
 
 * Remove generic `change` overload, and make `space` optional on others.
 
+* Return `immutable` types for `channels` and `channelsOrNull`, and remove
+  assumption of 3 channels.
+
 ## Draft 1.1
 
 * Clarify values in `channels` and `channelsOrNull`.
diff --git a/proposal/color-4-new-spaces-js.d.ts.md b/proposal/color-4-new-spaces-js.d.ts.md
index 84fe1fe6..a0c50b46 100644
--- a/proposal/color-4-new-spaces-js.d.ts.md
+++ b/proposal/color-4-new-spaces-js.d.ts.md
@@ -50,6 +50,8 @@ proposal].
 ## API
 
 ```ts
+import {List, ValueObject} from 'immutable';
+
 import {Value} from '../spec/js-api/value';
 ```
 
@@ -197,7 +199,7 @@ Returns an array of channel values (excluding alpha) for [`internal`], with
 * Return `channels`.
 
 ```ts
-get channelsOrNull(): [number | null, number | null, number | null];
+get channelsOrNull(): List<number | null>;
 ```
 
 [missing components]: ./color-4-new-spaces.md#missing-components
@@ -223,7 +225,7 @@ This algorithm returns an array of channel values (excluding alpha) for
 [`this.channelsOrNull`]: #channelsornull
 
 ```ts
-get channels(): [number, number, number];
+get channels(): List<number>;
 ```
 
 #### `channel`

From 0341873b96dd1575a9d757bb15faec2c90897c9d Mon Sep 17 00:00:00 2001
From: Christophe Coevoet <stof@notk.org>
Date: Fri, 6 Oct 2023 23:55:19 +0200
Subject: [PATCH 04/51] Fix typos in the deprecation APi proposal (#3708)

---
 accepted/deprecations-api.d.ts.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/accepted/deprecations-api.d.ts.md b/accepted/deprecations-api.d.ts.md
index e8a3b19a..4e8a5fbd 100644
--- a/accepted/deprecations-api.d.ts.md
+++ b/accepted/deprecations-api.d.ts.md
@@ -134,7 +134,7 @@ The situations we chose to warn for are:
   `futureDeprecations`.
 
   In this scenario, the future deprecation will still be treated as fatal,
-  but we want to warn users to prevent situtations where a user tries to
+  but we want to warn users to prevent situations where a user tries to
   make every deprecation fatal and ends up including future ones too.
 
 * an obsolete deprecation is passed to `fatalDeprecations`.
@@ -326,7 +326,7 @@ behavior of their global counterparts for compatibility reasons.
 
 #### `slash-div`
 
-Deprecation for treaing `/` as division.
+Deprecation for treating `/` as division.
 
 Update the proposal for forward slash as a separator to say that it emits
 deprecation warnings with ID 'slash-div'.

From 3bd90481d5d27bf140800adfeb4ef73920360477 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Fri, 6 Oct 2023 16:46:51 -0700
Subject: [PATCH 05/51] Move and restructure how we specify scopes

---
 accepted/module-system.md       |  2 +-
 accepted/more-math-functions.md |  2 +-
 spec/at-rules/for.md            | 19 +++++++++---------
 spec/at-rules/function.md       |  4 ++--
 spec/at-rules/import.md         |  4 ++--
 spec/at-rules/mixin.md          | 14 ++++++++------
 spec/modules.md                 |  7 +++----
 spec/spec.md                    | 34 +++++++++++++++++++++++++++++++++
 spec/variables.md               | 21 ++++----------------
 9 files changed, 65 insertions(+), 42 deletions(-)

diff --git a/accepted/module-system.md b/accepted/module-system.md
index 78df7541..4531a61c 100644
--- a/accepted/module-system.md
+++ b/accepted/module-system.md
@@ -1187,7 +1187,7 @@ Given a source file `file`, a [configuration](#configuration) `config`, and an
   * Otherwise, let `scope` be the scope of the innermost block such that `scope`
     already has a variable named `name`. Set `scope`'s variable `name` to `value`.
 
-  [scope]: ../spec/variables.md#scope
+  [scope]: ../spec/spec.md#scope
 
 * When a top-level mixin or function declaration `declaration` is encountered:
 
diff --git a/accepted/more-math-functions.md b/accepted/more-math-functions.md
index 88bad35e..99e49144 100644
--- a/accepted/more-math-functions.md
+++ b/accepted/more-math-functions.md
@@ -125,7 +125,7 @@ To execute a `VariableDeclaration` `declaration`:
   variable named `name`, set the innermost block's scope's variable `name` to
   `value`.~~
 
-[scope]: ../spec/variables.md#scope
+[scope]: ../spec/spec.md#scope
 
 * **Otherwise, if `resolved` is null, get the innermost block containing
   `declaration` and set its scope's variable `name` to `value`.**
diff --git a/spec/at-rules/for.md b/spec/at-rules/for.md
index 0c440062..99d168b7 100644
--- a/spec/at-rules/for.md
+++ b/spec/at-rules/for.md
@@ -53,15 +53,16 @@ To execute a `@for` rule `rule`:
 
 * While `i` is not equal to `to`:
 
-  * Let `scope` be a new [scope].
+  * [In a new scope]:
 
-  * Add a variable with `rule`'s `VariableName` as its name and `i` as its value
-    to `scope`.
+    * Add a variable with `rule`'s `VariableName` as its name and `i` as its value
+      to the [current scope].
 
-    > Note that this variable will have the same unit that `from`.
-  
-  * Execute the `ForBlock`'s statements in `scope`.
-  
-  * Set `i` to `i + direction`.
+      > Note that this variable will have the same unit that `from`.
 
-  [scope]: ../variables.md#scope
+    * Execute the `ForBlock`'s statements.
+
+    * Set `i` to `i + direction`.
+
+  [In a new scope]: ../spec.md#running-in-a-new-scope
+  [current scope]: ../spec.md#scope
diff --git a/spec/at-rules/function.md b/spec/at-rules/function.md
index 6011d6bc..5d118072 100644
--- a/spec/at-rules/function.md
+++ b/spec/at-rules/function.md
@@ -42,6 +42,6 @@ To execute a `@function` rule `rule`:
   [the current module]: ../spec.md#current-module
   [the current import context]: ../spec.md#current-import-context
 
-* Otherwise, set the innermost block's [scope][]'s function `name` to `value`.
+* Otherwise, set the [current scope]'s function `name` to `rule`.
 
-  [scope]: ../variables.md#scope
+  [current scope]: ../spec.md#scope
diff --git a/spec/at-rules/import.md b/spec/at-rules/import.md
index b5070b66..f4d1bffb 100644
--- a/spec/at-rules/import.md
+++ b/spec/at-rules/import.md
@@ -138,7 +138,7 @@ To execute an `@import` rule `rule`:
   * Add `imported`'s [extensions][] to the current module.
 
   * If the `@import` rule is nested within at-rules and/or style rules, add each
-     member in `imported` to the local [scope][].
+    member in `imported` to the [current scope].
 
   * Otherwise, add each member in `imported` to the current import context and
      the current module.
@@ -158,4 +158,4 @@ To execute an `@import` rule `rule`:
   [current import context]: ../spec.md#current-import-context
   [resolving `imported`'s extensions]: extend.md#resolving-a-modules-extensions
   [extensions]: extend.md#extension
-  [scope]: ../variables.md#scope
+  [current scope]: ../spec.md#scope
diff --git a/spec/at-rules/mixin.md b/spec/at-rules/mixin.md
index c5f7c2c3..a142f620 100644
--- a/spec/at-rules/mixin.md
+++ b/spec/at-rules/mixin.md
@@ -33,20 +33,22 @@ To execute a `@mixin` rule `rule`:
 
 * If `rule` is outside of any block of statements:
 
-  * If `name` *doesn't* begin with `-` or `_`, set [the current module][]'s
+  * If `name` *doesn't* begin with `-` or `_`, set [the current module]'s
     mixin `name` to `rule`.
 
     > This overrides the previous definition, if one exists.
 
-  * Set [the current import context][]'s mixin `name` to `rule`.
+  * Set [the current import context]'s mixin `name` to `rule`.
 
     > This happens regardless of whether or not it begins with `-` or `_`.
 
-* Otherwise, set the innermost block's [scope][]'s mixin `name` to `value`.
+* Otherwise, set the [current scope]'s mixin `name` to `rule`.
 
-  [scope]: ../variables.md#scope
-  [the current module]: ../spec.md#current-module
-  [the current import context]: ../spec.md#current-import-context
+  > This overrides the previous definition, if one exists.
+
+[the current module]: ../spec.md#current-module
+[the current import context]: ../spec.md#current-import-context
+[current scope]: ../spec.md#scope
 
 ## `@include`
 
diff --git a/spec/modules.md b/spec/modules.md
index 79b25eef..b2b5065b 100644
--- a/spec/modules.md
+++ b/spec/modules.md
@@ -426,13 +426,12 @@ and returns a member of type `type` or null.
 * If `name` is a plain `Identifier` or a `Variable` that's not a
   `NamespacedVariable`:
 
-  * Let `scope` be the [scope][] of the innermost block containing the current
-    statement such that `scope` has a member of type `type` named `name`, or
-    null if no such scope exists.
+  * Let `scope` be the [current scope] or its innermost parent such that `scope`
+    has a member of type `type` named `name`, or null if no such scope exists.
 
   * If `scope` is not null, return `scope`'s value of type `type` named `name`.
 
-  [scope]: variables.md#scope
+  [current scope]: spec.md#scope
 
 * If `name` is a [`NamespacedIdentifier`](#syntax) of the form
   `namespace.raw-name` or a [`Variable`][] of the form `namespace.$raw-name`:
diff --git a/spec/spec.md b/spec/spec.md
index 14a78b3c..b8d8b4f0 100644
--- a/spec/spec.md
+++ b/spec/spec.md
@@ -19,10 +19,14 @@ the language this way.
 ## Table of Contents
 
 * [Definitions](#definitions)
+  * [Scope](#scope)
+  * [Global Scope](#global-scope)
   * [Current Source File](#current-source-file)
   * [Current Configuration](#current-configuration)
   * [Current Import Context](#current-import-context)
   * [Current Module](#current-module)
+* [Procedures](#procedures)
+  * [Running in a New Scope](#running-in-a-new-scope)
 * [Semantics](#semantics)
   * [Compiling a Path](#compiling-a-path)
   * [Compiling a String](#compiling-a-string)
@@ -30,6 +34,23 @@ the language this way.
 
 ## Definitions
 
+### Scope
+
+A *scope* is a mutable structure that contains:
+
+* The scope's *variables*: a mapping from identifiers to SassScript values.
+* The scope's *mixins*: a mapping from identifiers to mixins.
+* The scope's *functions*: a mapping from identifiers to functions.
+* The scope's *parent*: a reference to another scope, which may be unset.
+
+One scope at a time is designated the *current scope*. By default, this is the
+[global scope](#global-scope).
+
+### Global Scope
+
+The *global scope* is the scope shared among the top level of all Sass files. It
+has no parent.
+
 ### Current Source File
 
 The *current source file* is the [source file][] that was passed to the
@@ -64,6 +85,19 @@ invocation of [Executing a File](#executing-a-file).
 > Because a module is only made immutable (other than its variables) when
 > execution has finished, the current module is always mutable.
 
+## Procedures
+
+### Running in a New Scope
+
+To run a set of steps *in a new scope*:
+
+* Let `parent` be the [current scope].
+
+  [current scope]: #scope
+
+* Return the result of running the given steps with the current scope set to an
+  empty scope with `parent` as its parent.
+
 ## Semantics
 
 ### Compiling a Path
diff --git a/spec/variables.md b/spec/variables.md
index c9fb7e39..c6801eff 100644
--- a/spec/variables.md
+++ b/spec/variables.md
@@ -3,9 +3,6 @@
 ## Table of Contents
 
 * [Syntax](#syntax)
-* [Definitions](#definitions)
-  * [Scope](#scope)
-  * [Global Scope](#global-scope)
 * [Semantics](#semantics)
   * [Executing a Variable Declaration](#executing-a-variable-declaration)
   * [Evaluating a Variable](#evaluating-a-variable)
@@ -27,18 +24,6 @@ the `.$` in `NamespacedVariable`. Each of `!global` and `!default` is allowed
 at most once in `VariableDeclaration`. As with all statements, a
 `VariableDeclaration` must be separated from other statements with a semicolon.
 
-## Definitions
-
-### Scope
-
-A *scope* is a mapping from variable names to values. Every block of statements
-delimited by `{` and `}` in SCSS or by indentation in the indented syntax has an
-associated scope.
-
-### Global Scope
-
-The *global scope* is the scope shared among the top level of all Sass files.
-
 ## Semantics
 
 ### Executing a Variable Declaration
@@ -107,8 +92,10 @@ To execute a `VariableDeclaration` `declaration`:
 
       > This also overrides the previous definition.
 
-* Otherwise, if `resolved` is null, get the innermost block containing
-  `declaration` and set its scope's variable `name` to `value`.
+* Otherwise, if `resolved` is null, set the [current scope]'s variable `name` to
+  `value`.
+
+  [current scope]: spec.md#scope
 
 * Otherwise, set `resolved`'s value to `value`.
 

From f4b191d16f4dfbe3e66700fd1f95cc6e911f5140 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Fri, 6 Oct 2023 18:03:51 -0700
Subject: [PATCH 06/51] [First-Class Mixins] Flush to spec

Closes #626
---
 spec/at-rules/function.md     | 28 ++++++++++--
 spec/at-rules/mixin.md        | 39 ++++++++++------
 spec/built-in-modules.md      | 38 ++++++++++++++++
 spec/built-in-modules/meta.md | 86 +++++++++++++++++++++++++++++++++--
 spec/types/functions.md       | 62 +++++++++++++++++++++++++
 spec/types/mixins.md          | 63 +++++++++++++++++++++++++
 6 files changed, 293 insertions(+), 23 deletions(-)
 create mode 100644 spec/built-in-modules.md
 create mode 100644 spec/types/functions.md
 create mode 100644 spec/types/mixins.md

diff --git a/spec/at-rules/function.md b/spec/at-rules/function.md
index 5d118072..aa3fd5c6 100644
--- a/spec/at-rules/function.md
+++ b/spec/at-rules/function.md
@@ -28,20 +28,38 @@ To execute a `@function` rule `rule`:
 
   [vendor prefix]: ../syntax.md#vendor-prefix
 
+* Let `parent` be the [current scope].
+
+  [current scope]: ../spec.md#scope
+
+* Let `function` be a [function] named `name` which does the following when
+  executed with `args`:
+
+  [function]: ../types/functions.md
+
+  * With the current scope set to an empty [scope] with `parent` as its parent:
+
+    * Evaluate `args` with `rule`'s `ArgumentDeclaration`.
+
+    * Execute each statement in `rule`.
+
+    * Return the value from the `@return` rule if one was executed, or throw an
+      error if no `@return` rule was executed.
+
+  [scope]: ../spec.md#scope
+
 * If `rule` is outside of any block of statements:
 
   * If `name` *doesn't* begin with `-` or `_`, set [the current module][]'s
-    function `name` to `rule`.
+    function `name` to `function`.
 
     > This overrides the previous definition, if one exists.
 
-  * Set [the current import context][]'s function `name` to `rule`.
+  * Set [the current import context][]'s function `name` to `function`.
 
     > This happens regardless of whether or not it begins with `-` or `_`.
 
   [the current module]: ../spec.md#current-module
   [the current import context]: ../spec.md#current-import-context
 
-* Otherwise, set the [current scope]'s function `name` to `rule`.
-
-  [current scope]: ../spec.md#scope
+* Otherwise, set the [current scope]'s function `name` to `function`.
diff --git a/spec/at-rules/mixin.md b/spec/at-rules/mixin.md
index a142f620..d154d199 100644
--- a/spec/at-rules/mixin.md
+++ b/spec/at-rules/mixin.md
@@ -31,25 +31,41 @@ To execute a `@mixin` rule `rule`:
 
 * Let `name` be the value of `rule`'s `Identifier`.
 
+* Let `parent` be the [current scope].
+
+  [current scope]: ../spec.md#scope
+
+* Let `mixin` be a [mixin] named `name` which accepts a content block if `rule`
+  contains a `@content` rule. To execute this mixin with `args`:
+
+  [mixin]: ../types/mixins.md
+
+  * With the current scope set to an empty [scope] with `parent` as its parent:
+
+    * Evaluate `args` with `rule`'s `ArgumentDeclaration`.
+
+    * Execute each statement in `rule`.
+
+  [scope]: ../spec.md#scope
+
 * If `rule` is outside of any block of statements:
 
   * If `name` *doesn't* begin with `-` or `_`, set [the current module]'s
-    mixin `name` to `rule`.
+    mixin `name` to `mixin`.
 
     > This overrides the previous definition, if one exists.
 
-  * Set [the current import context]'s mixin `name` to `rule`.
+  * Set [the current import context]'s mixin `name` to `mixin`.
 
     > This happens regardless of whether or not it begins with `-` or `_`.
 
-* Otherwise, set the [current scope]'s mixin `name` to `rule`.
+  [the current module]: ../spec.md#current-module
+  [the current import context]: ../spec.md#current-import-context
+
+* Otherwise, set the [current scope]'s mixin `name` to `mixin`.
 
   > This overrides the previous definition, if one exists.
 
-[the current module]: ../spec.md#current-module
-[the current import context]: ../spec.md#current-import-context
-[current scope]: ../spec.md#scope
-
 ## `@include`
 
 ### Syntax
@@ -72,15 +88,12 @@ To execute an `@include` rule `rule`:
 
 * Let `name` be `rule`'s `NamespacedIdentifier`.
 
-* Let `mixin` be the result of [resolving a mixin][] named `name`. If this
-  returns null, throw an error.
+* Let `mixin` be the result of [resolving a mixin] named `name`. If this returns
+  null, throw an error.
 
   [resolving a mixin]: ../modules.md#resolving-a-member
 
-* Execute `rule`'s `ArgumentInvocation` with `mixin`'s `ArgumentDeclaration` in
-  `mixin`'s scope.
-
-* Execute each statement in `mixin`.
+* Execute `mixin` with `rule`'s `ArgumentInvocation`.
 
 ## `@content`
 
diff --git a/spec/built-in-modules.md b/spec/built-in-modules.md
new file mode 100644
index 00000000..0fbe10e2
--- /dev/null
+++ b/spec/built-in-modules.md
@@ -0,0 +1,38 @@
+# Built-In Modules
+
+Sass provides a number of built-in [modules] that may be loaded from URLs with
+the scheme `sass`. These modules have no extensions, CSS trees, dependencies, or
+source files. Their canonical URLs are the same as the URLs used to load them.
+
+[modules]: modules.md#module
+
+## Built-In Functions and Mixins
+
+Each function and mixin defined in a built-in modules is specified with a
+signature of the form
+
+<x><pre>
+[\<ident-token>] ArgumentDeclaration
+</pre></x>
+
+[\<ident-token>]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram
+
+followed by a procedure. It's available as a member (either function or mixin)
+in the module whose name is the value of the `<ident-token>`. When it's executed
+with `args`:
+
+* With an empty scope with no parent as the [current scope]:
+
+  [current scope]: spec.md#scope
+
+  * Evaluate `args` with the signature's `ArgumentDeclaration`.
+
+  * Run the procedure, and return its result if this is a function.
+
+Built-in mixins don't accept content blocks unless explicitly specified
+otherwise.
+
+By convention, in these procedures `$var` is used as a shorthand for "the value
+of the variable `var` in the current scope".
+
+> In other words, `$var` is the value passed to the argument `$var`.
diff --git a/spec/built-in-modules/meta.md b/spec/built-in-modules/meta.md
index 06b495cf..57af84c0 100644
--- a/spec/built-in-modules/meta.md
+++ b/spec/built-in-modules/meta.md
@@ -5,6 +5,7 @@ This built-in module is available from the URL `sass:meta`.
 ## Table of Contents
 
 * [Functions](#functions)
+  * [`accepts-content()`](#accepts-content)
   * [`calc-name()`](#calc-name)
   * [`calc-args()`](#calc-args)
   * [`call()`](#call)
@@ -12,19 +13,36 @@ This built-in module is available from the URL `sass:meta`.
   * [`feature-exists()`](#feature-exists)
   * [`function-exists()`](#function-exists)
   * [`get-function()`](#get-function)
+  * [`get-mixin()`](#get-mixin)
   * [`global-variable-exists()`](#global-variable-exists)
   * [`inspect()`](#inspect)
   * [`keywords()`](#keywords)
   * [`mixin-exists()`](#mixin-exists)
   * [`module-functions()`](#module-functions)
+  * [`module-mixins()`](#module-mixins)
   * [`module-variables()`](#module-variables)
   * [`type-of()`](#type-of)
   * [`variable-exists()`](#variable-exists)
 * [Mixins](#mixins)
+  * [`apply()`](#apply)
   * [`load-css()`](#load-css)
 
 ## Functions
 
+### `accepts-content()`
+
+This is a new function in the `sass:meta` module.
+
+```
+accepts-content($mixin)
+```
+
+* If `$mixin` is not a [mixin], throw an error.
+
+  [mixin]: ../types/mixins.md
+
+* Return whether `$mixin` accepts a content block as a SassScript boolean.
+
 ### `calc-name()`
 
 ```
@@ -144,6 +162,31 @@ This function is also available as a global function named `get-function()`.
   * Return [`use`'s module][]'s function named `$name`, or throw an error if no
     such function exists.
 
+### `get-mixin()`
+
+```
+get-mixin($name, $module: null)
+```
+
+* If `$name` is not a string, throw an error.
+
+* If `$module` is null:
+
+  * Return the result of [resolving a mixin] named `$name`. If this returns
+    null, throw an error.
+
+  [resolving a mixin]: ../modules.md#resolving-a-member
+
+* Otherwise:
+
+  * If `$module` is not a string, throw an error.
+
+  * Let `use` be the `@use` rule in [the current source file] whose namespace is
+    equal to `$module`. If no such rule exists, throw an error.
+
+  * Return [`use`'s module]'s mixin named `$name`, or throw an error if no such
+    mixin exists.
+
 ### `global-variable-exists()`
 
 ```
@@ -198,16 +241,14 @@ This function is also available as a global function named `mixin-exists()`.
 
 * If `$module` is null:
 
-  * Return whether [resolving a mixin][] named `$name` returns null.
-  
-  [resolving a mixin]: ../modules.md#resolving-a-member
+  * Return whether [resolving a mixin] named `$name` returns null.
 
 * Otherwise, if `$module` isn't a string, throw an error.
 
-* Otherwise, let `use` be the `@use` rule in [the current source file][] whose
+* Otherwise, let `use` be the `@use` rule in [the current source file] whose
   namespace is equal to `$module`. If no such rule exists, throw an error.
 
-* Return whether [`use`'s module][] contains a mixin named `$name`.
+* Return whether [`use`'s module] contains a mixin named `$name`.
 
 ### `module-functions()`
 
@@ -225,6 +266,22 @@ This function is also available as a global function named `module-functions()`.
 * Return a map whose keys are the names of functions in [`use`'s module][] and
   whose values are the corresponding functions.
 
+### `module-mixins()`
+
+This is a new function in the `sass:meta` module.
+
+```
+module-mixins($module)
+```
+
+* If `$module` is not a string, throw an error.
+
+* Let `use` be the `@use` rule in [the current source file] whose namespace is
+  equal to `$module`. If no such rule exists, throw an error.
+
+* Return a map whose keys are the quoted string names of mixins in
+  [`use`'s module] and whose values are the corresponding mixins.
+
 ### `module-variables()`
 
 ```
@@ -261,6 +318,7 @@ This function is also available as a global function named `type-of()`.
   | Function      | `"function"`    |
   | List          | `"list"`        |
   | Map           | `"map"`         |
+  | Mixin         | `"mixin"`       |
   | Null          | `"null"`        |
   | Number        | `"number"`      |
   | String        | `"string"`      |
@@ -288,6 +346,24 @@ This function is also available as a global function named `variable-exists()`.
 
 ## Mixins
 
+### `apply()`
+
+```
+apply($mixin, $args...)
+```
+
+* If `$mixin` is not a [mixin], throw an error.
+
+* If the current `@include` rule has a `ContentBlock` and `$mixin` doesn't
+  accept a block, throw an error.
+
+* Execute `$mixin` with the `ArgumentInvocation` `(...$args)`. Treat the
+  `@include` rule that invoked `apply` as the `@include` rule that invoked
+  `$mixin`.
+
+  > This ensures that any `@content` rules in `$mixin` will use `apply()`'s
+  > `ContentBlock`.
+
 ### `load-css()`
 
 ```
diff --git a/spec/types/functions.md b/spec/types/functions.md
new file mode 100644
index 00000000..0d6c842e
--- /dev/null
+++ b/spec/types/functions.md
@@ -0,0 +1,62 @@
+# Functions
+
+## Table of Contents
+
+* [Types](#types)
+  * [Operations](#operations)
+    * [Equality](#equality)
+  * [Serialization](#serialization)
+
+## Types
+
+The value type known as a "function" is a procedure that takes an
+`ArgumentInvocation` `args` and returns a SassScript value. Each function has a
+string name.
+
+> The specific details of executing this procedure differ depending on where and
+> how the function is defined.
+
+### Operations
+
+A function follows the default behavior of all SassScript operations, except
+that equality is defined as below.
+
+#### Equality
+
+Functions use reference equality: two function values are equal only if they
+refer to the exact same instance of the same procedure.
+
+> If the same file were to be imported multiple times, Sass would create a new
+> function value for each `@function` rule each time the file is imported.
+> Because a new function value has been created, although the name, body, and
+> source span of a given function from the file would be the same between
+> imports, the values would not be equal because they refer to different
+> instances. Functions pre-defined by the Sass language are instatiated at most
+> once during the entire evaluation of a program.
+>
+> As an example, if we declare two functions:
+>
+> ```scss
+> @function foo() {
+>   @return red;
+> }
+>
+> $a: meta.get-function(foo);
+>
+> @mixin foo {
+>   @return red;
+> }
+>
+> $b: meta.get-mixin(foo);
+> ```
+>
+> Although every aspect of the two functions is the same, `$a != $b`, because
+> they refer to separate function values.
+
+### Serialization
+
+To serialize a function value:
+
+* If the value is not being inspected, throw an error.
+
+* Otherwise, emit `'get-function("'`, then the function's name, then `'")'`.
diff --git a/spec/types/mixins.md b/spec/types/mixins.md
new file mode 100644
index 00000000..b390c444
--- /dev/null
+++ b/spec/types/mixins.md
@@ -0,0 +1,63 @@
+# Mixins
+
+## Table of Contents
+
+* [Types](#types)
+  * [Operations](#operations)
+    * [Equality](#equality)
+  * [Serialization](#serialization)
+
+## Types
+
+The value type known as a "mixin" is a procedure that takes an
+`ArgumentInvocation` `args` and returns nothing. Each mixin has a string name
+and a boolean that indicates whether or not it accepts a content block.
+
+> The specific details of executing this procedure differ depending on where and
+> how the mixin is defined. A mixin will typically add nodes to the CSS
+> stylesheet.
+
+### Operations
+
+A mixin follows the default behavior of all SassScript operations, except that
+equality is defined as below.
+
+#### Equality
+
+Mixins use reference equality: two mixin values are equal only if they refer to
+the exact same instance of the same procedure.
+
+> If the same file were to be imported multiple times, Sass would create a new
+> mixin value for each `@mixin` rule each time the file is imported. Because a
+> new mixin value has been created, although the name, body, and source span of
+> a given mixin from the file would be the same between imports, the values
+> would not be equal because they refer to different instances. Mixins
+> pre-defined by the Sass language are instatiated at most once during the
+> entire evaluation of a program.
+>
+> As an example, if we declare two mixins:
+>
+> ```scss
+> @mixin foo {
+>   color: red;
+> }
+>
+> $a: meta.get-mixin(foo);
+>
+> @mixin foo {
+>   color: red;
+> }
+>
+> $b: meta.get-mixin(foo);
+> ```
+>
+> Although every aspect of the two mixins is the same, `$a != $b`, because they
+> refer to separate mixin values.
+
+### Serialization
+
+To serialize a mixin value:
+
+* If the value is not being inspected, throw an error.
+
+* Otherwise, emit `'get-mixin("'`, then the mixin's name, then `'")'`.

From 6a0c61cf2e4ee8844f0d7a79c1d62b53b2e46992 Mon Sep 17 00:00:00 2001
From: Jonny Gerig Meyer <jonny@oddbird.net>
Date: Sat, 7 Oct 2023 15:22:05 -0400
Subject: [PATCH 07/51] Remove unused ValueObject type

---
 proposal/color-4-new-spaces-js.d.ts.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/proposal/color-4-new-spaces-js.d.ts.md b/proposal/color-4-new-spaces-js.d.ts.md
index a0c50b46..c68e2180 100644
--- a/proposal/color-4-new-spaces-js.d.ts.md
+++ b/proposal/color-4-new-spaces-js.d.ts.md
@@ -50,7 +50,7 @@ proposal].
 ## API
 
 ```ts
-import {List, ValueObject} from 'immutable';
+import {List} from 'immutable';
 
 import {Value} from '../spec/js-api/value';
 ```

From ea1ec36c12da579ff99d9871951c6f44785be255 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Tue, 10 Oct 2023 14:36:50 -0700
Subject: [PATCH 08/51] Code review

---
 spec/at-rules/function.md     |  2 +-
 spec/built-in-modules/meta.md | 16 ++++++++++++++++
 spec/types/functions.md       |  4 ++--
 3 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/spec/at-rules/function.md b/spec/at-rules/function.md
index aa3fd5c6..c62189ed 100644
--- a/spec/at-rules/function.md
+++ b/spec/at-rules/function.md
@@ -55,7 +55,7 @@ To execute a `@function` rule `rule`:
 
     > This overrides the previous definition, if one exists.
 
-  * Set [the current import context][]'s function `name` to `function`.
+  * Set [the current import context]'s function `name` to `function`.
 
     > This happens regardless of whether or not it begins with `-` or `_`.
 
diff --git a/spec/built-in-modules/meta.md b/spec/built-in-modules/meta.md
index 57af84c0..4b488b6d 100644
--- a/spec/built-in-modules/meta.md
+++ b/spec/built-in-modules/meta.md
@@ -108,6 +108,10 @@ This function is also available as a global function named `function-exists()`.
 
 * If `$name` is not a string, throw an error.
 
+* If `$name` is not an [`<ident-token>`], return false.
+
+  [`<ident-token>`]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram
+
 * If `$module` is null:
 
   * Return whether [resolving a function][] named `$name` returns null.
@@ -135,6 +139,8 @@ This function is also available as a global function named `get-function()`.
 
 * If `$name` is not a string, throw an error.
 
+* If `$name` is not an [`<ident-token>`], throw an error.
+
 * If `$module` is null:
 
   * If `$css` is falsey:
@@ -170,6 +176,8 @@ get-mixin($name, $module: null)
 
 * If `$name` is not a string, throw an error.
 
+* If `$name` is not an [`<ident-token>`], throw an error.
+
 * If `$module` is null:
 
   * Return the result of [resolving a mixin] named `$name`. If this returns
@@ -197,6 +205,10 @@ This function is also available as a global function named `global-variable-exis
 
 * If `$name` is not a string, throw an error.
 
+* If `$name` is not a [`PlainVariable`], return false.
+
+  [`PlainVariable`]: ../variables.md#syntax
+
 * If `$module` is null:
 
   * Return whether [resolving a variable][] named `$name`, ignoring local
@@ -239,6 +251,8 @@ This function is also available as a global function named `mixin-exists()`.
 
 * If `$name` is not a string, throw an error.
 
+* If `$name` is not an [`<ident-token>`], return false.
+
 * If `$module` is null:
 
   * Return whether [resolving a mixin] named `$name` returns null.
@@ -333,6 +347,8 @@ This function is also available as a global function named `variable-exists()`.
 
 * If `$name` is not a string, throw an error.
 
+* If `$name` is not a [`PlainVariable`], return false.
+
 * If `$module` is null:
 
   * Return whether [resolving a variable][] named `$name` returns null.
diff --git a/spec/types/functions.md b/spec/types/functions.md
index 0d6c842e..0f0ba467 100644
--- a/spec/types/functions.md
+++ b/spec/types/functions.md
@@ -43,11 +43,11 @@ refer to the exact same instance of the same procedure.
 >
 > $a: meta.get-function(foo);
 >
-> @mixin foo {
+> @function foo {
 >   @return red;
 > }
 >
-> $b: meta.get-mixin(foo);
+> $b: meta.get-function(foo);
 > ```
 >
 > Although every aspect of the two functions is the same, `$a != $b`, because

From b7003fd5367611b19bc2fd562514a254fc0908d1 Mon Sep 17 00:00:00 2001
From: Jonny Gerig Meyer <jonny@oddbird.net>
Date: Tue, 10 Oct 2023 18:11:13 -0400
Subject: [PATCH 09/51] Tweak language around getters and arrays.

---
 proposal/color-4-new-spaces-js.d.ts.md | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/proposal/color-4-new-spaces-js.d.ts.md b/proposal/color-4-new-spaces-js.d.ts.md
index c68e2180..a89284f8 100644
--- a/proposal/color-4-new-spaces-js.d.ts.md
+++ b/proposal/color-4-new-spaces-js.d.ts.md
@@ -179,14 +179,14 @@ toGamut(space?: KnownColorSpace): SassColor;
 
 #### `channelsOrNull`
 
-Returns an array of channel values (excluding alpha) for [`internal`], with
+Returns a list of channel values (excluding alpha) for [`internal`], with
 [missing channels][missing components] converted to `null`.
 
-* Let `space` be the result of [`this.space`].
+* Let `space` be the value of [`this.space`].
 
 * Let `components` be the list of channels in `space`.
 
-* Let `channels` be an empty array.
+* Let `channels` be an empty list.
 
 * For each `component` in `components`:
 
@@ -207,12 +207,12 @@ get channelsOrNull(): List<number | null>;
 
 #### `channels`
 
-This algorithm returns an array of channel values (excluding alpha) for
+This algorithm returns a list of channel values (excluding alpha) for
 [`internal`], with [missing channels][missing components] converted to `0`.
 
-* Let `channelsOrNull` be the result of [`this.channelsOrNull`].
+* Let `channelsOrNull` be the value of [`this.channelsOrNull`].
 
-* Let `channels` be an empty array.
+* Let `channels` be an empty list.
 
 * For each `channel` in `channelsOrNull`:
 
@@ -230,7 +230,7 @@ get channels(): List<number>;
 
 #### `channel`
 
-* Let `initialSpace` be the value of [`this.space()`].
+* Let `initialSpace` be the value of [`this.space`].
 
 * Let `space` be `options.space` if it is defined, and the value of
   `initialSpace` otherwise.
@@ -340,7 +340,7 @@ isChannelPowerless(
 
 #### `interpolate`
 
-* Let `space` be the value of [`this.space()`].
+* Let `space` be the value of [`this.space`].
 
 * If `options.method` is set, let `interpolationMethod` be a space separated
   list containing the value of `space`, a space, and the value of
@@ -383,7 +383,7 @@ as the result of changing some of [`internal`]'s components.
 > If `space` is not a [legacy color space], a channel value of `null` will
 > result in a [missing component][missing components] value for that channel.
 
-* Let `initialSpace` be the value of [`this.space()`].
+* Let `initialSpace` be the value of [`this.space`].
 
 * Let `spaceSetExplicitly` be `true` if `options.space` is defined, and `false`
   otherwise.
@@ -561,7 +561,6 @@ as the result of changing some of [`internal`]'s components.
 
 * Return the result of [`changedColor.toSpace(initialSpace)`].
 
-[`this.space()`]: #space
 [`this.toSpace(space)`]: #tospace
 [`changedColor.toSpace(initialSpace)`]: #tospace
 [`Changing a Component Value`]: #changing-a-component-value
@@ -850,7 +849,7 @@ Create a new SassColor in the `rgb` color space.
 * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
   the result of [parsing a channel value] with value `options.alpha`.
 
-* Return the result of [`rgb(red green blue / alpha)`].
+* Set [`internal`] to the result of [`rgb(red green blue / alpha)`].
 
 [`rgb(red green blue / alpha)`]: ./color-4-new-spaces.md#rgb-and-rgba
 

From 7d50def4d120731ac3e6e7e8b372828565d36703 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E3=81=AA=E3=81=A4=E3=81=8D?= <i@ntk.me>
Date: Tue, 10 Oct 2023 17:17:28 -0700
Subject: [PATCH 10/51] Clarifying performance expectations about sass and
 sass-embedded (#3716)

---
 js-api-doc/compile.d.ts       | 23 +++++++++++++++++------
 js-api-doc/legacy/render.d.ts | 11 ++++++++---
 2 files changed, 25 insertions(+), 9 deletions(-)

diff --git a/js-api-doc/compile.d.ts b/js-api-doc/compile.d.ts
index 7dde5b74..e8a8ce65 100644
--- a/js-api-doc/compile.d.ts
+++ b/js-api-doc/compile.d.ts
@@ -44,6 +44,11 @@ export interface CompileResult {
  *
  * This only allows synchronous {@link Importer}s and {@link CustomFunction}s.
  *
+ * **Heads up!** When using the `sass-embedded` npm package,
+ * **{@link compileAsync} is almost always faster than {@link compile}**, due to
+ * the overhead of emulating synchronous messaging with worker threads and
+ * concurrent compilations being blocked on main thread.
+ *
  * @example
  *
  * ```js
@@ -66,9 +71,9 @@ export function compile(path: string, options?: Options<'sync'>): CompileResult;
  * This only allows synchronous or asynchronous {@link Importer}s and
  * {@link CustomFunction}s.
  *
- * **Heads up!** When using Dart Sass, **{@link compile} is almost twice as fast
- * as {@link compileAsync}**, due to the overhead of making the entire
- * evaluation process asynchronous.
+ * **Heads up!** When using the `sass` npm package, **{@link compile} is almost
+ * twice as fast as {@link compileAsync}**, due to the overhead of making the
+ * entire evaluation process asynchronous.
  *
  * @example
  *
@@ -94,6 +99,12 @@ export function compileAsync(
  *
  * This only allows synchronous {@link Importer}s and {@link CustomFunction}s.
  *
+ * **Heads up!** When using the `sass-embedded` npm package,
+ * **{@link compileStringAsync} is almost always faster than
+ * {@link compileString}**, due to the overhead of emulating synchronous
+ * messaging with worker threads and concurrent compilations being blocked on
+ * main thread.
+ *
  * @example
  *
  * ```js
@@ -125,9 +136,9 @@ export function compileString(
  * This only allows synchronous or asynchronous {@link Importer}s and {@link
  * CustomFunction}s.
  *
- * **Heads up!** When using Dart Sass, **{@link compile} is almost twice as fast
- * as {@link compileAsync}**, due to the overhead of making the entire
- * evaluation process asynchronous.
+ * **Heads up!** When using the `sass` npm package, **{@link compileString} is
+ * almost twice as fast as {@link compileStringAsync}**, due to the overhead
+ * of making the entire evaluation process asynchronous.
  *
  * @example
  *
diff --git a/js-api-doc/legacy/render.d.ts b/js-api-doc/legacy/render.d.ts
index b029c882..9f78816f 100644
--- a/js-api-doc/legacy/render.d.ts
+++ b/js-api-doc/legacy/render.d.ts
@@ -96,6 +96,11 @@ export interface LegacyResult {
  * This function synchronously compiles a Sass file to CSS. If it succeeds, it
  * returns the result, and if it fails it throws an error.
  *
+ * **Heads up!** When using the `sass-embedded` npm package, **{@link render}
+ * is almost always faster than {@link renderSync}**, due to the overhead of
+ * emulating synchronous messaging with worker threads and concurrent
+ * compilations being blocked on main thread.
+ *
  * @example
  *
  * ```js
@@ -116,9 +121,9 @@ export function renderSync(options: LegacyOptions<'sync'>): LegacyResult;
  * `callback` with a {@link LegacyResult} if compilation succeeds or {@link
  * LegacyException} if it fails.
  *
- * **Heads up!** When using Dart Sass, **{@link renderSync} is almost twice as
- * fast as {@link render}** by default, due to the overhead of making the entire
- * evaluation process asynchronous.
+ * **Heads up!** When using the `sass` npm package, **{@link renderSync} is
+ * almost twice as fast as {@link render}** by default, due to the overhead of
+ * making the entire evaluation process asynchronous.
  *
  * ```js
  * const sass = require('sass'); // or require('node-sass');

From 6998b4429ebc9530a3b414382aadeb948d00e118 Mon Sep 17 00:00:00 2001
From: Jonny Gerig Meyer <jonny@oddbird.net>
Date: Wed, 11 Oct 2023 08:48:16 -0400
Subject: [PATCH 11/51] Rename types using title-case for acronyms longer than
 two letters in camel-case identifiers.

---
 proposal/color-4-new-spaces-js.changes.md |   3 +
 proposal/color-4-new-spaces-js.d.ts.md    | 112 +++++++++++-----------
 2 files changed, 59 insertions(+), 56 deletions(-)

diff --git a/proposal/color-4-new-spaces-js.changes.md b/proposal/color-4-new-spaces-js.changes.md
index b7271cfe..3a0f578f 100644
--- a/proposal/color-4-new-spaces-js.changes.md
+++ b/proposal/color-4-new-spaces-js.changes.md
@@ -1,5 +1,8 @@
 ## Draft 1.2
 
+* Rename types using title-case for acronyms longer than two letters in
+  camel-case identifiers (e.g. `ColorSpaceHsl` instead of `ColorSpaceHSL`).
+
 * Remove generic `change` overload, and make `space` optional on others.
 
 * Return `immutable` types for `channels` and `channelsOrNull`, and remove
diff --git a/proposal/color-4-new-spaces-js.d.ts.md b/proposal/color-4-new-spaces-js.d.ts.md
index a89284f8..d9f99113 100644
--- a/proposal/color-4-new-spaces-js.d.ts.md
+++ b/proposal/color-4-new-spaces-js.d.ts.md
@@ -60,23 +60,23 @@ import {Value} from '../spec/js-api/value';
 ### Color Space Definitions
 
 ```ts
-export type ColorSpaceHSL = 'hsl';
+export type ColorSpaceHsl = 'hsl';
 
-export type ChannelNameHSL = 'hue' | 'saturation' | 'lightness';
+export type ChannelNameHsl = 'hue' | 'saturation' | 'lightness';
 
-export type ColorSpaceHWB = 'hwb';
+export type ColorSpaceHwb = 'hwb';
 
-export type ChannelNameHWB = 'hue' | 'whiteness' | 'blackness';
+export type ChannelNameHwb = 'hue' | 'whiteness' | 'blackness';
 
 export type ColorSpaceLab = 'lab' | 'oklab';
 
 export type ChannelNameLab = 'lightness' | 'a' | 'b';
 
-export type ColorSpaceLCH = 'lch' | 'oklch';
+export type ColorSpaceLch = 'lch' | 'oklch';
 
-export type ChannelNameLCH = 'lightness' | 'chroma' | 'hue';
+export type ChannelNameLch = 'lightness' | 'chroma' | 'hue';
 
-export type ColorSpaceRGB =
+export type ColorSpaceRgb =
   | 'a98-rgb'
   | 'display-p3'
   | 'prophoto-rgb'
@@ -84,29 +84,29 @@ export type ColorSpaceRGB =
   | 'srgb'
   | 'srgb-linear';
 
-export type ChannelNameRGB = 'red' | 'green' | 'blue';
+export type ChannelNameRgb = 'red' | 'green' | 'blue';
 
-export type ColorSpaceXYZ = 'xyz' | 'xyz-d50' | 'xyz-d65';
+export type ColorSpaceXyz = 'xyz' | 'xyz-d50' | 'xyz-d65';
 
-export type ChannelNameXYZ = 'x' | 'y' | 'z';
+export type ChannelNameXyz = 'x' | 'y' | 'z';
 
 export type ChannelName =
-  | ChannelNameHSL
-  | ChannelNameHWB
+  | ChannelNameHsl
+  | ChannelNameHwb
   | ChannelNameLab
-  | ChannelNameLCH
-  | ChannelNameRGB
-  | ChannelNameXYZ;
+  | ChannelNameLch
+  | ChannelNameRgb
+  | ChannelNameXyz;
 
 export type KnownColorSpace =
-  | ColorSpaceHSL
-  | ColorSpaceHWB
+  | ColorSpaceHsl
+  | ColorSpaceHwb
   | ColorSpaceLab
-  | ColorSpaceLCH
-  | ColorSpaceRGB
-  | ColorSpaceXYZ;
+  | ColorSpaceLch
+  | ColorSpaceRgb
+  | ColorSpaceXyz;
 
-export type PolarColorSpace = ColorSpaceHSL | ColorSpaceHWB | ColorSpaceLCH;
+export type PolarColorSpace = ColorSpaceHsl | ColorSpaceHwb | ColorSpaceLch;
 
 export type RectangularColorSpace = Exclude<KnownColorSpace, PolarColorSpace>;
 
@@ -248,28 +248,28 @@ get channels(): List<number>;
 ```ts
 channel(channel: ChannelName): number;
 channel(
-  channel: ChannelNameHSL | 'alpha',
-  options: {space: ColorSpaceHSL}
+  channel: ChannelNameHsl | 'alpha',
+  options: {space: ColorSpaceHsl}
 ): number;
 channel(
-  channel: ChannelNameHWB | 'alpha',
-  options: {space: ColorSpaceHWB}
+  channel: ChannelNameHwb | 'alpha',
+  options: {space: ColorSpaceHwb}
 ): number;
 channel(
   channel: ChannelNameLab | 'alpha',
   options: {space: ColorSpaceLab}
 ): number;
 channel(
-  channel: ChannelNameLCH | 'alpha',
-  options: {space: ColorSpaceLCH}
+  channel: ChannelNameLch | 'alpha',
+  options: {space: ColorSpaceLch}
 ): number;
 channel(
-  channel: ChannelNameRGB | 'alpha',
-  options: {space: ColorSpaceRGB}
+  channel: ChannelNameRgb | 'alpha',
+  options: {space: ColorSpaceRgb}
 ): number;
 channel(
-  channel: ChannelNameXYZ | 'alpha',
-  options: {space: ColorSpaceXYZ}
+  channel: ChannelNameXyz | 'alpha',
+  options: {space: ColorSpaceXyz}
 ): number;
 ```
 
@@ -313,28 +313,28 @@ JavaScript boolean.
 ```ts
 isChannelPowerless(channel: ChannelName): boolean;
 isChannelPowerless(
-  channel: ChannelNameHSL,
-  options?: {space: ColorSpaceHSL}
+  channel: ChannelNameHsl,
+  options?: {space: ColorSpaceHsl}
 ): boolean;
 isChannelPowerless(
-  channel: ChannelNameHWB,
-  options?: {space: ColorSpaceHWB}
+  channel: ChannelNameHwb,
+  options?: {space: ColorSpaceHwb}
 ): boolean;
 isChannelPowerless(
   channel: ChannelNameLab,
   options?: {space: ColorSpaceLab}
 ): boolean;
 isChannelPowerless(
-  channel: ChannelNameLCH,
-  options?: {space: ColorSpaceLCH}
+  channel: ChannelNameLch,
+  options?: {space: ColorSpaceLch}
 ): boolean;
 isChannelPowerless(
-  channel: ChannelNameRGB,
-  options?: {space: ColorSpaceRGB}
+  channel: ChannelNameRgb,
+  options?: {space: ColorSpaceRgb}
 ): boolean;
 isChannelPowerless(
-  channel: ChannelNameXYZ,
-  options?: {space: ColorSpaceXYZ}
+  channel: ChannelNameXyz,
+  options?: {space: ColorSpaceXyz}
 ): boolean;
 ```
 
@@ -568,19 +568,19 @@ as the result of changing some of [`internal`]'s components.
 ```ts
 change(
   options: {
-    [key in ChannelNameHSL]?: number | null;
+    [key in ChannelNameHsl]?: number | null;
   } & {
     alpha?: number;
-    space?: ColorSpaceHSL;
+    space?: ColorSpaceHsl;
   }
 ): SassColor;
 
 change(
   options: {
-    [key in ChannelNameHWB]?: number | null;
+    [key in ChannelNameHwb]?: number | null;
   } & {
     alpha?: number;
-    space?: ColorSpaceHWB;
+    space?: ColorSpaceHwb;
   }
 ): SassColor;
 
@@ -595,28 +595,28 @@ change(
 
 change(
   options: {
-    [key in ChannelNameLCH]?: number | null;
+    [key in ChannelNameLch]?: number | null;
   } & {
     alpha?: number | null;
-    space?: ColorSpaceLCH;
+    space?: ColorSpaceLch;
   }
 ): SassColor;
 
 change(
   options: {
-    [key in ChannelNameRGB]?: number | null;
+    [key in ChannelNameRgb]?: number | null;
   } & {
     alpha?: number | null;
-    space?: ColorSpaceRGB;
+    space?: ColorSpaceRgb;
   }
 ): SassColor;
 
 change(
   options: {
-    [key in ChannelNameXYZ]?: number | null;
+    [key in ChannelNameXyz]?: number | null;
   } & {
     alpha?: number | null;
-    space?: ColorSpaceXYZ;
+    space?: ColorSpaceXyz;
   }
 ): SassColor;
 ```
@@ -693,7 +693,7 @@ constructor(options: {
   chroma: number | null;
   hue: number | null;
   alpha?: number | null;
-  space: ColorSpaceLCH;
+  space: ColorSpaceLch;
 });
 ```
 
@@ -727,7 +727,7 @@ constructor(options: {
   green: number | null;
   blue: number | null;
   alpha?: number | null;
-  space: Exclude<ColorSpaceRGB, 'rgb'>;
+  space: Exclude<ColorSpaceRgb, 'rgb'>;
 });
 ```
 
@@ -757,7 +757,7 @@ constructor(options: {
   y: number | null;
   z: number | null;
   alpha?: number | null;
-  space: ColorSpaceXYZ;
+  space: ColorSpaceXyz;
 });
 ```
 
@@ -795,7 +795,7 @@ constructor(options: {
   saturation: number | null;
   lightness: number | null;
   alpha?: number | null;
-  space?: ColorSpaceHSL;
+  space?: ColorSpaceHsl;
 });
 ```
 
@@ -827,7 +827,7 @@ constructor(options: {
   whiteness: number | null;
   blackness: number | null;
   alpha?: number | null;
-  space?: ColorSpaceHWB;
+  space?: ColorSpaceHwb;
 });
 ```
 

From 219a1b5f4564780e26e3d1782a037ae82b32566b Mon Sep 17 00:00:00 2001
From: Jonny Gerig Meyer <jonny@oddbird.net>
Date: Wed, 11 Oct 2023 10:26:37 -0400
Subject: [PATCH 12/51] Remove `isAlphaMissing` and add "alpha" to channel name
 types.

---
 proposal/color-4-new-spaces-js.changes.md |  4 ++
 proposal/color-4-new-spaces-js.d.ts.md    | 60 +++++------------------
 2 files changed, 17 insertions(+), 47 deletions(-)

diff --git a/proposal/color-4-new-spaces-js.changes.md b/proposal/color-4-new-spaces-js.changes.md
index 3a0f578f..193f1cd5 100644
--- a/proposal/color-4-new-spaces-js.changes.md
+++ b/proposal/color-4-new-spaces-js.changes.md
@@ -1,5 +1,9 @@
 ## Draft 1.2
 
+* Add "alpha" to all channel name types.
+
+* Remove `isAlphaMissing` in favor of `isChannelMissing("alpha")`.
+
 * Rename types using title-case for acronyms longer than two letters in
   camel-case identifiers (e.g. `ColorSpaceHsl` instead of `ColorSpaceHSL`).
 
diff --git a/proposal/color-4-new-spaces-js.d.ts.md b/proposal/color-4-new-spaces-js.d.ts.md
index d9f99113..a0f4ec59 100644
--- a/proposal/color-4-new-spaces-js.d.ts.md
+++ b/proposal/color-4-new-spaces-js.d.ts.md
@@ -24,7 +24,6 @@ proposal].
     * [`channel`](#channel)
     * [`alpha`](#alpha)
     * [`isChannelMissing`](#ischannelmissing)
-    * [`isAlphaMissing`](#isalphamissing)
     * [`isChannelPowerless`](#ischannelpowerless)
     * [`interpolate`](#interpolate)
   * [Updated Color Functions](#updated-color-functions)
@@ -62,19 +61,19 @@ import {Value} from '../spec/js-api/value';
 ```ts
 export type ColorSpaceHsl = 'hsl';
 
-export type ChannelNameHsl = 'hue' | 'saturation' | 'lightness';
+export type ChannelNameHsl = 'hue' | 'saturation' | 'lightness' | 'alpha';
 
 export type ColorSpaceHwb = 'hwb';
 
-export type ChannelNameHwb = 'hue' | 'whiteness' | 'blackness';
+export type ChannelNameHwb = 'hue' | 'whiteness' | 'blackness' | 'alpha';
 
 export type ColorSpaceLab = 'lab' | 'oklab';
 
-export type ChannelNameLab = 'lightness' | 'a' | 'b';
+export type ChannelNameLab = 'lightness' | 'a' | 'b' | 'alpha';
 
 export type ColorSpaceLch = 'lch' | 'oklch';
 
-export type ChannelNameLch = 'lightness' | 'chroma' | 'hue';
+export type ChannelNameLch = 'lightness' | 'chroma' | 'hue' | 'alpha';
 
 export type ColorSpaceRgb =
   | 'a98-rgb'
@@ -84,11 +83,11 @@ export type ColorSpaceRgb =
   | 'srgb'
   | 'srgb-linear';
 
-export type ChannelNameRgb = 'red' | 'green' | 'blue';
+export type ChannelNameRgb = 'red' | 'green' | 'blue' | 'alpha';
 
 export type ColorSpaceXyz = 'xyz' | 'xyz-d50' | 'xyz-d65';
 
-export type ChannelNameXyz = 'x' | 'y' | 'z';
+export type ChannelNameXyz = 'x' | 'y' | 'z' | 'alpha';
 
 export type ChannelName =
   | ChannelNameHsl
@@ -247,30 +246,12 @@ get channels(): List<number>;
 
 ```ts
 channel(channel: ChannelName): number;
-channel(
-  channel: ChannelNameHsl | 'alpha',
-  options: {space: ColorSpaceHsl}
-): number;
-channel(
-  channel: ChannelNameHwb | 'alpha',
-  options: {space: ColorSpaceHwb}
-): number;
-channel(
-  channel: ChannelNameLab | 'alpha',
-  options: {space: ColorSpaceLab}
-): number;
-channel(
-  channel: ChannelNameLch | 'alpha',
-  options: {space: ColorSpaceLch}
-): number;
-channel(
-  channel: ChannelNameRgb | 'alpha',
-  options: {space: ColorSpaceRgb}
-): number;
-channel(
-  channel: ChannelNameXyz | 'alpha',
-  options: {space: ColorSpaceXyz}
-): number;
+channel(channel: ChannelNameHsl, options: {space: ColorSpaceHsl}): number;
+channel(channel: ChannelNameHwb, options: {space: ColorSpaceHwb}): number;
+channel(channel: ChannelNameLab, options: {space: ColorSpaceLab}): number;
+channel(channel: ChannelNameLch, options: {space: ColorSpaceLch}): number;
+channel(channel: ChannelNameRgb, options: {space: ColorSpaceRgb}): number;
+channel(channel: ChannelNameXyz, options: {space: ColorSpaceXyz}): number;
 ```
 
 #### `alpha`
@@ -289,20 +270,11 @@ Returns the result of [`color.is-missing(internal,
 channel)`][color.is-missing()] as a JavaScript boolean.
 
 ```ts
-isChannelMissing(channel: ChannelName | 'alpha'): boolean;
+isChannelMissing(channel: ChannelName): boolean;
 ```
 
 [color.is-missing()]: ./color-4-new-spaces.md#coloris-missing-1
 
-#### `isAlphaMissing`
-
-Returns the result of [`color.is-missing(internal,
-'alpha')`][color.is-missing()] as a JavaScript boolean.
-
-```ts
-get isAlphaMissing(): boolean;
-```
-
 #### `isChannelPowerless`
 
 Returns the result of [`color.is-powerless(internal, channel, space)`] as a
@@ -570,7 +542,6 @@ change(
   options: {
     [key in ChannelNameHsl]?: number | null;
   } & {
-    alpha?: number;
     space?: ColorSpaceHsl;
   }
 ): SassColor;
@@ -579,7 +550,6 @@ change(
   options: {
     [key in ChannelNameHwb]?: number | null;
   } & {
-    alpha?: number;
     space?: ColorSpaceHwb;
   }
 ): SassColor;
@@ -588,7 +558,6 @@ change(
   options: {
     [key in ChannelNameLab]?: number | null;
   } & {
-    alpha?: number | null;
     space?: ColorSpaceLab;
   }
 ): SassColor;
@@ -597,7 +566,6 @@ change(
   options: {
     [key in ChannelNameLch]?: number | null;
   } & {
-    alpha?: number | null;
     space?: ColorSpaceLch;
   }
 ): SassColor;
@@ -606,7 +574,6 @@ change(
   options: {
     [key in ChannelNameRgb]?: number | null;
   } & {
-    alpha?: number | null;
     space?: ColorSpaceRgb;
   }
 ): SassColor;
@@ -615,7 +582,6 @@ change(
   options: {
     [key in ChannelNameXyz]?: number | null;
   } & {
-    alpha?: number | null;
     space?: ColorSpaceXyz;
   }
 ): SassColor;

From 3eb7f2c5e1febf5ddd30ccef204ccc7b1aca1191 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 16 Oct 2023 13:52:15 -0700
Subject: [PATCH 13/51] Bump tj-actions/changed-files from 39.2.0 to 39.2.2
 (#3720)

Bumps [tj-actions/changed-files](https://github.com/tj-actions/changed-files) from 39.2.0 to 39.2.2.
- [Release notes](https://github.com/tj-actions/changed-files/releases)
- [Changelog](https://github.com/tj-actions/changed-files/blob/main/HISTORY.md)
- [Commits](https://github.com/tj-actions/changed-files/compare/8238a4103220c636f2dad328ead8a7c8dbe316a3...408093d9ff9c134c33b974e0722ce06b9d6e8263)

---
updated-dependencies:
- dependency-name: tj-actions/changed-files
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 262618b0..082f2f1b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -138,7 +138,7 @@ jobs:
 
     - name: Find changed files in js-api-doc
       id: changed-files
-      uses: tj-actions/changed-files@8238a4103220c636f2dad328ead8a7c8dbe316a3
+      uses: tj-actions/changed-files@408093d9ff9c134c33b974e0722ce06b9d6e8263
       with: {files: js-api-doc}
 
     - name: Deploy

From 44b060f66de4c01ad2304d2e28691f7160fa285d Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 16 Oct 2023 13:52:35 -0700
Subject: [PATCH 14/51] Bump bufbuild/buf-setup-action from 1.26.1 to 1.27.0
 (#3713)

Bumps [bufbuild/buf-setup-action](https://github.com/bufbuild/buf-setup-action) from 1.26.1 to 1.27.0.
- [Release notes](https://github.com/bufbuild/buf-setup-action/releases)
- [Commits](https://github.com/bufbuild/buf-setup-action/compare/v1.26.1...v1.27.0)

---
updated-dependencies:
- dependency-name: bufbuild/buf-setup-action
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 082f2f1b..f7bc8c1c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -72,7 +72,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: bufbuild/buf-setup-action@v1.26.1
+      - uses: bufbuild/buf-setup-action@v1.27.0
         with: {github_token: "${{ github.token }}"}
       - name: Generate protobuf code
         run: buf generate

From 75ced5c7196e374ba4e9ec76ad36028c6f6a1040 Mon Sep 17 00:00:00 2001
From: Jonny Gerig Meyer <jonny@oddbird.net>
Date: Tue, 17 Oct 2023 18:45:42 -0400
Subject: [PATCH 15/51] [Color 4] Draft 1.3 changes for Color spaces JS API
 (#3721)

---
 proposal/color-4-new-spaces-js.changes.md |  8 +++++
 proposal/color-4-new-spaces-js.d.ts.md    | 44 ++++++++++++-----------
 2 files changed, 31 insertions(+), 21 deletions(-)

diff --git a/proposal/color-4-new-spaces-js.changes.md b/proposal/color-4-new-spaces-js.changes.md
index 193f1cd5..17d9ccc8 100644
--- a/proposal/color-4-new-spaces-js.changes.md
+++ b/proposal/color-4-new-spaces-js.changes.md
@@ -1,3 +1,11 @@
+## Draft 1.3
+
+* Rename new Embedded Protocol message from `SassColor` to `Color`.
+
+* Make `color2` a positional parameter of `interpolate`, not an option.
+
+* Add `rec2020` color space.
+
 ## Draft 1.2
 
 * Add "alpha" to all channel name types.
diff --git a/proposal/color-4-new-spaces-js.d.ts.md b/proposal/color-4-new-spaces-js.d.ts.md
index a0f4ec59..999f82e2 100644
--- a/proposal/color-4-new-spaces-js.d.ts.md
+++ b/proposal/color-4-new-spaces-js.d.ts.md
@@ -1,4 +1,4 @@
-# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.1
+# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.3
 
 *([Issue](https://github.com/sass/sass/issues/2831),
 [Changelog](color-4-new-spaces-js.changes.md))*
@@ -43,7 +43,7 @@ proposal].
   * [Changing a Component Value](#changing-a-component-value)
   * [Determining Construction Space](#determining-construction-space)
 * [Embedded Protocol](#embedded-protocol)
-  * [SassColor](#sasscolor)
+  * [Color](#color)
   * [Removed SassScript values](#removed-sassscript-values)
 
 ## API
@@ -79,6 +79,7 @@ export type ColorSpaceRgb =
   | 'a98-rgb'
   | 'display-p3'
   | 'prophoto-rgb'
+  | 'rec2020'
   | 'rgb'
   | 'srgb'
   | 'srgb-linear';
@@ -324,16 +325,18 @@ isChannelPowerless(
 * Otherwise, let `interpolationMethod` be a space separated list containing the
   value of `space`, a space, and the string "shorter".
 
-* Return the result of [`color.mix(internal, options.color2, options.weight, interpolationMethod)`][`color.mix()`].
+* Return the result of [`color.mix(internal, color2, options.weight, interpolationMethod)`][`color.mix()`].
 
 ```ts
-interpolate(options: {color2: SassColor; weight?: number}): SassColor;
+interpolate(color2: SassColor, options: {weight?: number}): SassColor;
 
-interpolate(options: {
-  color2: SassColor;
-  weight?: number;
-  method?: HueInterpolationMethod;
-}): SassColor;
+interpolate(
+  color2: SassColor,
+  options: {
+    weight?: number;
+    method?: HueInterpolationMethod;
+  }
+): SassColor;
 ```
 
 [`color.mix()`]: ./color-4-new-spaces.md#colormix-1
@@ -505,8 +508,8 @@ as the result of changing some of [`internal`]'s components.
   })
   ```
 
-* If `space` equals `a98-rgb`, `display-p3`, `prophoto-rgb`, `srgb`, or
-  `srgb-linear`, let `changedColor` be the result of:
+* If `space` equals `a98-rgb`, `display-p3`, `prophoto-rgb`, `rec2020`, `srgb`,
+  or `srgb-linear`, let `changedColor` be the result of:
 
   ```js
   new SassColor({
@@ -598,7 +601,7 @@ change(
 
 #### Lab Channel Constructor
 
-Create a new SassColor in a color space with Lab channels -- `lab` and `oklab`.
+Create a new SassColor in a color space with Lab channels—`lab` and `oklab`.
 
 * Let `lightness` be the result of [parsing a channel value] with value
   `options.lightness`.
@@ -632,7 +635,7 @@ constructor(options: {
 
 #### LCH Channel Constructor
 
-Create a new SassColor in a color space with LCH channels -- `lch` and `oklch`.
+Create a new SassColor in a color space with LCH channels—`lch` and `oklch`.
 
 * Let `lightness` be the result of [parsing a channel value] with value
   `options.lightness`.
@@ -665,8 +668,8 @@ constructor(options: {
 
 #### Predefined RGB Channel Constructor
 
-Create a new SassColor in a color space with RGB channels -- `srgb`,
-`srgb-linear`, `display-p3`, `a98-rgb`, and `prophoto-rgb`. `rgb` is supported
+Create a new SassColor in a color space with RGB channels—`srgb`, `srgb-linear`,
+`display-p3`, `a98-rgb`, `prophoto-rgb`, and `rec2020`. `rgb` is supported
 through the modified [RGB Constructor].
 
 * Let `red` be the result of [parsing a channel value] with value `options.red`.
@@ -699,8 +702,8 @@ constructor(options: {
 
 #### XYZ Channel Constructor
 
-Create a new SassColor in a color space with XYZ channels -- `xyz`, `xyz-d50`,
-and `xyz-d65`.
+Create a new SassColor in a color space with XYZ channels—`xyz`, `xyz-d50`, and
+`xyz-d65`.
 
 * Let `x` be the result of [parsing a channel value] with value `options.x`.
 
@@ -894,10 +897,10 @@ space for construction.
 This introduces a breaking change in the Embedded Protocol, as it removes the
 legacy SassScript values.
 
-### SassColor
+### Color
 
 ```proto
-message SassColor {
+message Color {
   // The name of a known color space.
   string space = 1;
 
@@ -910,8 +913,7 @@ message SassColor {
   // The value of the third channel associated with `space`.
   double channel3 = 4;
 
-  // The color's alpha channel. Mandatory. Must be between 0 and 1,
-  // inclusive.
+  // The color's alpha channel. Mandatory. Must be between 0 and 1, inclusive.
   double alpha = 5;
 }
 ```

From 09f8a3a66d196e589e6a40f5557bfadefa2d4f6d Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <jamesnw@gmail.com>
Date: Wed, 18 Oct 2023 17:56:59 -0400
Subject: [PATCH 16/51] Proposal: Compiler interface for shared resources
 (#3719)

---
 proposal/shared-resources.d.ts.md | 228 ++++++++++++++++++++++++++++++
 1 file changed, 228 insertions(+)
 create mode 100644 proposal/shared-resources.d.ts.md

diff --git a/proposal/shared-resources.d.ts.md b/proposal/shared-resources.d.ts.md
new file mode 100644
index 00000000..b12cccc6
--- /dev/null
+++ b/proposal/shared-resources.d.ts.md
@@ -0,0 +1,228 @@
+# Shared Resources in JavaScript API
+
+*([Issue](https://github.com/sass/sass/issues/3296))*
+
+This proposal adds an API design that allows for sharing resources across
+multiple invocations of the Sass compiler's JavaScript API. This will provide
+Sass's users with a more efficient way of running Sass compilations across
+multiple files.
+
+## Table of Contents
+
+* [Summary](#summary)
+  * [Design Decisions](#design-decisions)
+    * [Splitting Sync and Async Compilers](#splitting-sync-and-async-compilers)
+    * [Limited API interface](#limited-api-interface)
+    * [Flexibility for interfaces on process management](#flexibility-for-interfaces-on-process-management)
+    * [No shared state](#no-shared-state)
+  * [Example](#example)
+    * [Sync Compiler](#sync-compiler)
+    * [Async Compiler](#async-compiler)
+* [API](#api)
+  * [Types](#types)
+    * [initCompiler()](#initcompiler)
+    * [initAsyncCompiler()](#initasynccompiler)
+    * [Compiler](#compiler)
+      * [`compile()` and `compileString()`](#compile-and-compilestring)
+      * [dispose()](#dispose)
+    * [Async Compiler](#async-compiler-1)
+      * [`compileAsync()` and `compileStringAsync()`](#compileasync-and-compilestringasync)
+      * [dispose()](#dispose-1)
+
+## Summary
+
+Currently, the JavaScript API for Sass only accommodates a single compilation
+per process. In practice, we have observed build tools are compiling multiple
+times in response to a single user action. For instance, Vue.js authors using
+Vite will see a Sass compilation for each `<style lang="scss">` tag that appears
+in their codebase.
+
+While processes can be spun up and down quickly, the combined time can add up to
+a noticeable impact on performance. The embedded client supports long running
+processes, and this proposal adds a method for the embedded host to manage the
+lifecycle of these processes through a Compiler interface.
+
+### Design Decisions
+
+#### Splitting Sync and Async Compilers
+
+When creating a Compiler, users will need to choose either a compiler that
+provides access to synchronous or asynchronous compilation. While providing both
+simultaneously from a single Compiler would offer more flexibility, it also adds
+significant complexity to the API. In practice, we expect most users will only
+want to use one mode, generally in the mode that is the fastest for the
+implementation. If synchronous and asynchronous compilations are both needed,
+users can create multiple Compilers.
+
+#### Limited API interface
+
+Many build tools allow passing the Sass module as a parameter, which offers
+flexibility to users on what implementation of Sass is used. Because users may
+still want to use portions of the JavaScript API unrelated to compilation, we
+considered having the Compiler interface mirror the top level Sass interface,
+which would allow users to replace instances of the imported `sass` class with
+an instance of the compiler. However, this adds an additional cost to ongoing
+Sass development. The proposed API does not eliminate this as a possibility in
+the future.
+
+#### Flexibility for interfaces on process management
+
+In environments without access to a long-running compiler—for instance, the Dart
+Sass implementation—the Compiler interface will continue to perform a single
+compilation per process.
+
+#### No shared state
+
+This proposal does not change how a single compilation is done, and no state is
+shared across compilations. Options and importers must be set for each
+compilation. Future enhancements may introduce [shared state], but this proposal
+only adds the ability to run multiple compilations on a single process.
+
+[shared state]: https://github.com/sass/sass/issues/3296
+
+This also means that the proposal makes no assertions about whether file content
+has changed. It is also up to the user to determine when to start and stop a
+long-running compiler process.
+
+### Example
+
+#### Sync Compiler
+
+```js
+import * as sass from 'sass';
+function setup() {
+  const compiler = sass.initCompiler();
+  const result1 = compiler.compileString('a {b: c}').css;
+  const result2 = compiler.compileString('a {b: c}').css;
+  compiler.dispose();
+
+  // throws error
+  const result3 = sass.compileString('a {b: c}').css;
+}
+```
+
+#### Async Compiler
+
+```js
+import * as sass from 'sass';
+async function setup() {
+  const compiler = await sass.initAsyncCompiler();
+  const result1 = await compiler.compileStringAsync('a {b: c}').css;
+  const result2 = await compiler.compileStringAsync('a {b: c}').css;
+  compiler.dispose();
+
+  // throws error
+  const result3 = sass.compileStringAsync('a {b: c}').css;
+}
+```
+
+## API
+
+### Types
+
+```ts
+import {CompileResult} from '../spec/js-api/compile';
+import {Options, StringOptions} from '../spec/js-api/options';
+```
+
+#### initCompiler()
+
+Returns a synchronous [Compiler].
+
+[Compiler]: #compiler
+
+```ts
+export function initCompiler(): Compiler;
+```
+
+#### initAsyncCompiler()
+
+Resolves with an [Async Compiler].
+
+[Async Compiler]: #async-compiler
+
+```ts
+export function initAsyncCompiler(): Promise<AsyncCompiler>;
+```
+
+#### Compiler
+
+An instance of the synchronous Compiler.
+
+```ts
+export interface Compiler {
+```
+
+##### `compile()` and `compileString()`
+
+Only synchronous compilation methods [`compile()`] and [`compileString()`] must be
+included, and must have with identical semantics to the [Sass interface].
+
+[`compile()`]: ../spec/js-api/compile.d.ts.md#compile
+[`compilestring()`]: ../spec/js-api/compile.d.ts.md#compilestring
+[Sass interface]: ../spec/js-api/index.d.ts.md
+
+```ts
+compile(path: string, options?: Options<'sync'>): CompileResult;
+compileString(source: string, options?: StringOptions<'sync'>): CompileResult;
+```
+
+##### dispose()
+
+When `dispose` is invoked on a Compiler:
+
+* Any subsequent invocations of `compile` and `compileString` must throw an
+  error.
+
+* Returns `true` when disposal is complete.
+
+```ts
+  dispose(): Boolean;
+}
+```
+
+#### Async Compiler
+
+An instance of the asynchronous Compiler.
+
+```ts
+export interface AsyncCompiler {
+```
+
+##### `compileAsync()` and `compileStringAsync()`
+
+Only asynchronous compilation methods [`compileAsync()`] and
+[`compileStringAsync()`] must be included, and must have with identical
+semantics to the [Sass interface].
+
+[`compileasync()`]: ../spec/js-api/compile.d.ts.md#compileasync
+[`compilestringasync()`]: ../spec/js-api/compile.d.ts.md#compilestringasync
+
+```ts
+compileAsync(
+  path: string,
+  options?: Options<'async'>
+): Promise<CompileResult>;
+compileStringAsync(
+  source: string,
+  options?: StringOptions<'async'>
+): Promise<CompileResult>;
+```
+
+##### dispose()
+
+When `dispose` is invoked on an Async Compiler:
+
+* Any subsequent invocations of `compileAsync` and `compileStringAsync` must
+  throw an error.
+
+* Any compilations that have not yet been settled must be allowed to settle, and
+  not be cancelled.
+
+* Resolves a Promise with `true` when all compilations have been settled, and
+  disposal is complete.
+
+```ts
+  dispose(): Promise<Boolean>;
+}
+```

From d111550260a7fbcde92485138501ca4dc239ec5d Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 23 Oct 2023 13:43:43 -0700
Subject: [PATCH 17/51] Bump tj-actions/changed-files from 39.2.2 to 39.2.3
 (#3727)

Bumps [tj-actions/changed-files](https://github.com/tj-actions/changed-files) from 39.2.2 to 39.2.3.
- [Release notes](https://github.com/tj-actions/changed-files/releases)
- [Changelog](https://github.com/tj-actions/changed-files/blob/main/HISTORY.md)
- [Commits](https://github.com/tj-actions/changed-files/compare/408093d9ff9c134c33b974e0722ce06b9d6e8263...95690f9ece77c1740f4a55b7f1de9023ed6b1f87)

---
updated-dependencies:
- dependency-name: tj-actions/changed-files
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f7bc8c1c..a9d9e922 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -138,7 +138,7 @@ jobs:
 
     - name: Find changed files in js-api-doc
       id: changed-files
-      uses: tj-actions/changed-files@408093d9ff9c134c33b974e0722ce06b9d6e8263
+      uses: tj-actions/changed-files@95690f9ece77c1740f4a55b7f1de9023ed6b1f87
       with: {files: js-api-doc}
 
     - name: Deploy

From b56ce3f6b3aef3ad7180a653e344ee63a1c85579 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 23 Oct 2023 13:44:09 -0700
Subject: [PATCH 18/51] Bump bufbuild/buf-setup-action from 1.27.0 to 1.27.1
 (#3726)

Bumps [bufbuild/buf-setup-action](https://github.com/bufbuild/buf-setup-action) from 1.27.0 to 1.27.1.
- [Release notes](https://github.com/bufbuild/buf-setup-action/releases)
- [Commits](https://github.com/bufbuild/buf-setup-action/compare/v1.27.0...v1.27.1)

---
updated-dependencies:
- dependency-name: bufbuild/buf-setup-action
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a9d9e922..380b5b3c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -72,7 +72,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: bufbuild/buf-setup-action@v1.27.0
+      - uses: bufbuild/buf-setup-action@v1.27.1
         with: {github_token: "${{ github.token }}"}
       - name: Generate protobuf code
         run: buf generate

From 9414124ddd2effbecae8bf5ff234782fd3dab7e0 Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <jamesnw@gmail.com>
Date: Mon, 23 Oct 2023 19:17:26 -0400
Subject: [PATCH 19/51] Remove return value from dispose (#3725)

---
 proposal/shared-resources.changes.md |  7 +++++++
 proposal/shared-resources.d.ts.md    | 12 +++++-------
 2 files changed, 12 insertions(+), 7 deletions(-)
 create mode 100644 proposal/shared-resources.changes.md

diff --git a/proposal/shared-resources.changes.md b/proposal/shared-resources.changes.md
new file mode 100644
index 00000000..47337e17
--- /dev/null
+++ b/proposal/shared-resources.changes.md
@@ -0,0 +1,7 @@
+## Draft 1.1
+
+* Remove unneeded returned/resolved value from `dispose`.
+
+## Draft 1
+
+* Initial draft
diff --git a/proposal/shared-resources.d.ts.md b/proposal/shared-resources.d.ts.md
index b12cccc6..256e58a8 100644
--- a/proposal/shared-resources.d.ts.md
+++ b/proposal/shared-resources.d.ts.md
@@ -1,4 +1,4 @@
-# Shared Resources in JavaScript API
+# Shared Resources in JavaScript API: Draft 1.1
 
 *([Issue](https://github.com/sass/sass/issues/3296))*
 
@@ -174,10 +174,8 @@ When `dispose` is invoked on a Compiler:
 * Any subsequent invocations of `compile` and `compileString` must throw an
   error.
 
-* Returns `true` when disposal is complete.
-
 ```ts
-  dispose(): Boolean;
+  dispose(): void;
 }
 ```
 
@@ -219,10 +217,10 @@ When `dispose` is invoked on an Async Compiler:
 * Any compilations that have not yet been settled must be allowed to settle, and
   not be cancelled.
 
-* Resolves a Promise with `true` when all compilations have been settled, and
-  disposal is complete.
+* Resolves a Promise when all compilations have been settled, and disposal is
+  complete.
 
 ```ts
-  dispose(): Promise<Boolean>;
+  dispose(): Promise<void>;
 }
 ```

From 364a88c535440dc38945acfd32c8f93999988a8d Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <jamesnw@gmail.com>
Date: Fri, 27 Oct 2023 20:00:44 -0400
Subject: [PATCH 20/51] [Color 4] Draft 1.4 changes for Color Spaces JS API
 (#3723)

Co-authored-by: Jonny Gerig Meyer <jonny@oddbird.net>
---
 proposal/color-4-new-spaces-js.changes.md | 17 ++++
 proposal/color-4-new-spaces-js.d.ts.md    | 98 +++++++++++++++++------
 2 files changed, 91 insertions(+), 24 deletions(-)

diff --git a/proposal/color-4-new-spaces-js.changes.md b/proposal/color-4-new-spaces-js.changes.md
index 17d9ccc8..25459801 100644
--- a/proposal/color-4-new-spaces-js.changes.md
+++ b/proposal/color-4-new-spaces-js.changes.md
@@ -1,3 +1,20 @@
+## Draft 1.4
+
+* In `change`, adjust algorithm for differentiating `hwb` from `hsl` when only
+  `hue` and no `space` is specified.
+
+* In `change` for legacy colors, emit a `color-4-api` warning if a non-alpha
+  channel is explicitly null and no space is set.
+
+* In procedure for Changing a Component Value, specify that `undefined` values
+  should return the `initialValue`.
+
+* `toSpace` uses `Converting a Color` algorithm instead of `color.to-space()` to
+  avoid removing missing channels when converting to a legacy space.
+
+* In `change` and constructors, throw an error for alpha and lightness values
+  that are out of range.
+
 ## Draft 1.3
 
 * Rename new Embedded Protocol message from `SassColor` to `Color`.
diff --git a/proposal/color-4-new-spaces-js.d.ts.md b/proposal/color-4-new-spaces-js.d.ts.md
index 999f82e2..94cbd02c 100644
--- a/proposal/color-4-new-spaces-js.d.ts.md
+++ b/proposal/color-4-new-spaces-js.d.ts.md
@@ -1,4 +1,4 @@
-# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.3
+# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.4
 
 *([Issue](https://github.com/sass/sass/issues/2831),
 [Changelog](color-4-new-spaces-js.changes.md))*
@@ -40,6 +40,7 @@ proposal].
   * [Deprecations](#deprecations)
 * [Procedures](#procedures)
   * [Parsing a Channel Value](#parsing-a-channel-value)
+  * [Parsing a Clamped Channel Value](#parsing-a-clamped-channel-value)
   * [Changing a Component Value](#changing-a-component-value)
   * [Determining Construction Space](#determining-construction-space)
 * [Embedded Protocol](#embedded-protocol)
@@ -137,13 +138,14 @@ get space(): KnownColorSpace;
 
 * If `this.space` is equal to `space`, return `this`.
 
-* Otherwise, return the result of [`color.to-space(internal, space)`].
+* Otherwise, return the result of [Converting a Color] with `this` as
+  `origin-color` and `space` as `target-space`.
 
 ```ts
 toSpace(space: KnownColorSpace): SassColor;
 ```
 
-[`color.to-space(internal, space)`]: ./color-4-new-spaces.md#colorto-space
+[Converting a Color]: ./color-4-new-spaces.md#converting-a-color
 
 #### `isLegacy`
 
@@ -241,7 +243,7 @@ get channels(): List<number>;
 
 * Let `value` be the channel value in `color` with name of `component`.
 
-* If `value` is null, return 0.
+* If `value` is `null`, return 0.
 
 * Otherwise, return `value`.
 
@@ -370,6 +372,9 @@ as the result of changing some of [`internal`]'s components.
 
   * If `options.whiteness` or `options.blackness` is set, let `space` be `hwb`.
 
+  * Otherwise, if `options.hue` is set and `initialSpace` is `hwb`, let space be
+    `hwb`.
+
   * Otherwise, if `options.hue`, `options.saturation`, or `options.lightness` is
     set, let `space` be `hsl`.
 
@@ -388,6 +393,12 @@ as the result of changing some of [`internal`]'s components.
 * If any key in `keys` is not the name of a channel in `components`, throw an
   error.
 
+* If `options.alpha` is set, and isn't either null or a number between 0 and 1
+  (inclusive and fuzzy), throw an error.
+
+* If `options.lightness` is set, and isn't either null or a number between 0 and
+  the maximum channel value for the space (inclusive and fuzzy), throw an error.
+
 * Let `color` be the result of [`this.toSpace(space)`].
 
 * Let `changedValue` be a function that takes a string argument for `channel`
@@ -396,8 +407,11 @@ as the result of changing some of [`internal`]'s components.
 
 * If `space` equals `hsl` and `spaceSetExplicitly` is `false`:
 
-  * If any of `options.hue`, `options.saturation`, `options.lightness` or
-    `options.alpha` equals null, emit a deprecation warning named `null-alpha`.
+  * If any of `options.hue`, `options.saturation` or `options.lightness` equals
+    `null`, emit a deprecation warning named `color-4-api`.
+
+  * If `options.alpha` equals `null`, emit a deprecation warning named
+    `null-alpha`.
 
   * Let `changedColor` be the result of:
 
@@ -426,8 +440,11 @@ as the result of changing some of [`internal`]'s components.
 
 * If `space` equals `hwb` and `spaceSetExplicitly` is `false`:
 
-  * If any of `options.hue`, `options.whiteness`, `options.blackness` or
-    `options.alpha` equals null, emit a deprecation warning named `null-alpha`.
+  * If any of `options.hue`, `options.whiteness` or `options.blackness` equals
+    `null`, emit a deprecation warning named `color-4-api`.
+
+  * If `options.alpha` equals `null`, emit a deprecation warning named
+    `null-alpha`.
 
   * Let `changedColor` be the result of:
 
@@ -456,8 +473,11 @@ as the result of changing some of [`internal`]'s components.
 
 * If `space` equals `rgb` and `spaceSetExplicitly` is `false`:
 
-  * If any of `options.red`, `options.green`, `options.blue` or `options.alpha`
-    equals null, emit a deprecation warning named `null-alpha`.
+  * If any of `options.red`, `options.green` or `options.blue` equals
+    `null`, emit a deprecation warning named `color-4-api`.
+
+  * If `options.alpha` equals `null`, emit a deprecation warning named
+    `null-alpha`.
 
   * Let `changedColor` be the result of:
 
@@ -603,15 +623,19 @@ change(
 
 Create a new SassColor in a color space with Lab channels—`lab` and `oklab`.
 
-* Let `lightness` be the result of [parsing a channel value] with value
-  `options.lightness`.
+* If `options.space` equals `lab`, let `maximum` be `100`. Otherwise, let
+  `maximum` be `1`.
+
+* Let `lightness` be the result of [parsing a clamped channel value] with
+  `value` of `options.lightness`, `minimum` of `0`, and `maximum` of `maximum`.
 
 * Let `a` be the result of [parsing a channel value] with value `options.a`.
 
 * Let `b` be the result of [parsing a channel value] with value `options.b`.
 
 * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
-  the result of [parsing a channel value] with value `options.alpha`.
+  the result of [parsing a clamped channel value] with value `options.alpha`,
+  `minimum` of 0, and `maximum` of 1.
 
 * If `options.space` equals `lab`, set [`internal`] to the result of
   [`lab(lightness a b / alpha)`].
@@ -622,6 +646,7 @@ Create a new SassColor in a color space with Lab channels—`lab` and `oklab`.
 [`lab(lightness a b / alpha)`]: ./color-4-new-spaces.md#lab
 [`oklab(lightness a b / alpha)`]: ./color-4-new-spaces.md#oklab
 [parsing a channel value]: #parsing-a-channel-value
+[parsing a clamped channel value]: #parsing-a-clamped-channel-value
 
 ```ts
 constructor(options: {
@@ -637,15 +662,19 @@ constructor(options: {
 
 Create a new SassColor in a color space with LCH channels—`lch` and `oklch`.
 
-* Let `lightness` be the result of [parsing a channel value] with value
-  `options.lightness`.
+* If `options.space` equals `lch`, let `maximum` be `100`. Otherwise, let
+  `maximum` be `1`.
+
+* Let `lightness` be the result of [parsing a clamped channel value] with
+  `value` of `options.lightness`, `minimum` of `0`, and `maximum` of `maximum`.
 
 * Let `c` be the result of [parsing a channel value] with value `options.c`.
 
 * Let `h` be the result of [parsing a channel value] with value `options.h`.
 
 * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
-  the result of [parsing a channel value] with value `options.alpha`.
+  the result of [parsing a clamped channel value] with value `options.alpha`,
+  `minimum` of 0, and `maximum` of 1.
 
 * If `options.space` equals `lch`, set [`internal`] to the result of
   [`lch(lightness a b / alpha)`].
@@ -681,7 +710,8 @@ through the modified [RGB Constructor].
   `options.blue`.
 
 * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
-  the result of [parsing a channel value] with value `options.alpha`.
+  the result of [parsing a clamped channel value] with value `options.alpha`,
+  `minimum` of 0, and `maximum` of 1.
 
 * Let `space` be the unquoted string value of `options.space`.
 
@@ -712,7 +742,8 @@ Create a new SassColor in a color space with XYZ channels—`xyz`, `xyz-d50`, an
 * Let `z` be the result of [parsing a channel value] with value `options.z`.
 
 * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
-  the result of [parsing a channel value] with value `options.alpha`.
+  the result of [parsing a clamped channel value] with value `options.alpha`,
+  `minimum` of 0, and `maximum` of 1.
 
 * Let `space` be the unquoted string value of `options.space`.
 
@@ -748,11 +779,12 @@ Create a new SassColor in the `hsl` color space.
 * Let `saturation` be the result of [parsing a channel value] with value
   `options.saturation`.
 
-* Let `lightness` be the result of [parsing a channel value] with value
-  `options.lightness`.
+* Let `lightness` be the result of [parsing a clamped channel value] with
+  `value` of `options.lightness`, `minimum` of `0`, and `maximum` of `100`.
 
 * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
-  the result of [parsing a channel value] with value `options.alpha`.
+  the result of [parsing a clamped channel value] with `value` of
+  `options.alpha`, `minimum` of `0`, and `maximum` of `1`.
 
 * Set [`internal`] to the result of [`hsl(hue saturation lightness / alpha)`].
 
@@ -784,7 +816,8 @@ Create a new SassColor in the `hwb` color space.
   `options.blackness`.
 
 * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
-  the result of [parsing a channel value] with value `options.alpha`.
+  the result of [parsing a clamped channel value] with `value` of
+  `options.alpha`, `minimum` of `0`, and `maximum` of `1`.
 
 * Set [`internal`] to the result of [`hwb(hue whiteness blackness / alpha)`].
 
@@ -816,7 +849,8 @@ Create a new SassColor in the `rgb` color space.
   `options.blue`.
 
 * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
-  the result of [parsing a channel value] with value `options.alpha`.
+  the result of [parsing a clamped channel value] with `value` of
+  `options.alpha`, `minimum` of `0`, and `maximum` of `1`.
 
 * Set [`internal`] to the result of [`rgb(red green blue / alpha)`].
 
@@ -865,6 +899,18 @@ This procedure takes a channel value `value`, and returns the special value
 * If `value` is the Javascript value `null`, return the unquoted Sass string
   `none`.
 
+### Parsing a Clamped Channel Value
+
+This procedure takes a channel value `value` and an inclusive range of `minimum`
+and `maximum`. It asserts the value is in the range, and returns the special
+value `none` if the value is `null`.
+
+* If `value` is fuzzy less-than `minimum`, throw an error.
+
+* If `value` is fuzzy greater-than `maximum`, throw an error.
+
+* Otherwise, return the result of [Parsing a Channel Value].
+
 ### Changing a Component Value
 
 This procedure takes a `channel` name, an object `changes` and a SassColor
@@ -875,7 +921,11 @@ This procedure takes a `channel` name, an object `changes` and a SassColor
 
 * If `channel` is not a key in `changes`, return `initialValue`.
 
-* Otherwise, return the value for `channel` in `changes`.
+* Let `changedValue` be the value for `channel` in `changes`.
+
+* If `changedValue` is `undefined` and not `null`, return `initialValue`.
+
+* Otherwise, return `changedValue`.
 
 ### Determining Construction Space
 

From 524f786f35f3c4fabc521846a99cff9ef22cdea6 Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <jamesnw@gmail.com>
Date: Fri, 27 Oct 2023 20:01:07 -0400
Subject: [PATCH 21/51] Package importer draft 1.2 (#3729)

---
 proposal/package-importer.changes.md | 5 +++++
 proposal/package-importer.d.ts.md    | 6 +++---
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/proposal/package-importer.changes.md b/proposal/package-importer.changes.md
index 5dcd7b43..6e005793 100644
--- a/proposal/package-importer.changes.md
+++ b/proposal/package-importer.changes.md
@@ -1,3 +1,8 @@
+## Draft 1.2
+
+* Export `NodePackageImporter` type, and set `_NodePackageImporterBrand` to
+  unknown.
+
 ## Draft 1.1
 
 * Throw an error if `nodePackageImporter` is used in the browser or other
diff --git a/proposal/package-importer.d.ts.md b/proposal/package-importer.d.ts.md
index e2d18dcc..d31b8a51 100644
--- a/proposal/package-importer.d.ts.md
+++ b/proposal/package-importer.d.ts.md
@@ -1,4 +1,4 @@
-# Package Importer
+# Package Importer: Draft 1.2
 
 *([Issue](https://github.com/sass/sass/issues/2739))*
 
@@ -225,8 +225,8 @@ import {FileImporter, Importer} from '../spec/js-api/importer';
 ### `nodePackageImporter`
 
 ```ts
-type NodePackageImporter = {
-  _NodePackageImporterBrand: any;
+export type NodePackageImporter = {
+  _NodePackageImporterBrand: unknown;
 };
 export declare const nodePackageImporter: NodePackageImporter;
 ```

From 72d2b16c89577d954fca8f6a9dc2eba219913363 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 30 Oct 2023 13:56:04 -0700
Subject: [PATCH 22/51] Bump bufbuild/buf-setup-action from 1.27.1 to 1.27.2
 (#3734)

Bumps [bufbuild/buf-setup-action](https://github.com/bufbuild/buf-setup-action) from 1.27.1 to 1.27.2.
- [Release notes](https://github.com/bufbuild/buf-setup-action/releases)
- [Commits](https://github.com/bufbuild/buf-setup-action/compare/v1.27.1...v1.27.2)

---
updated-dependencies:
- dependency-name: bufbuild/buf-setup-action
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 380b5b3c..576e08d2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -72,7 +72,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: bufbuild/buf-setup-action@v1.27.1
+      - uses: bufbuild/buf-setup-action@v1.27.2
         with: {github_token: "${{ github.token }}"}
       - name: Generate protobuf code
         run: buf generate

From 872e522d9584d27efcff458532b575d52a4fe0b4 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 30 Oct 2023 13:56:50 -0700
Subject: [PATCH 23/51] Bump tj-actions/changed-files from 39.2.3 to 40.0.0
 (#3733)

Bumps [tj-actions/changed-files](https://github.com/tj-actions/changed-files) from 39.2.3 to 40.0.0.
- [Release notes](https://github.com/tj-actions/changed-files/releases)
- [Changelog](https://github.com/tj-actions/changed-files/blob/main/HISTORY.md)
- [Commits](https://github.com/tj-actions/changed-files/compare/95690f9ece77c1740f4a55b7f1de9023ed6b1f87...af292f1e845a0377b596972698a8598734eb2796)

---
updated-dependencies:
- dependency-name: tj-actions/changed-files
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 576e08d2..bf553388 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -138,7 +138,7 @@ jobs:
 
     - name: Find changed files in js-api-doc
       id: changed-files
-      uses: tj-actions/changed-files@95690f9ece77c1740f4a55b7f1de9023ed6b1f87
+      uses: tj-actions/changed-files@af292f1e845a0377b596972698a8598734eb2796
       with: {files: js-api-doc}
 
     - name: Deploy

From 65cb1eef0a267482b09cd3721d2c02d4387d2ede Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 30 Oct 2023 13:57:01 -0700
Subject: [PATCH 24/51] Bump actions/setup-node from 3 to 4 (#3732)

Bumps [actions/setup-node](https://github.com/actions/setup-node) from 3 to 4.
- [Release notes](https://github.com/actions/setup-node/releases)
- [Commits](https://github.com/actions/setup-node/compare/v3...v4)

---
updated-dependencies:
- dependency-name: actions/setup-node
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/ci.yml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bf553388..d614da4f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -13,7 +13,7 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with: {node-version: '${{ env.NODE_VERSION }}'}
     - run: npm ci
     - run: >
@@ -28,7 +28,7 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with: {node-version: '${{ env.NODE_VERSION }}'}
     - run: npm ci
     - run: npm run toc-check
@@ -39,7 +39,7 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with: {node-version: '${{ env.NODE_VERSION }}'}
     - run: npm ci
     - run: npm run link-check
@@ -50,7 +50,7 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with: {node-version: '${{ env.NODE_VERSION }}'}
     - run: npm ci
     - run: npm run js-api-doc-check
@@ -61,7 +61,7 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with: {node-version: '${{ env.NODE_VERSION }}'}
     - run: npm ci
     - run: npm run typedoc

From 9931a5d84e453317ec77a5faff66666d13869c63 Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <jamesnw@gmail.com>
Date: Fri, 3 Nov 2023 17:41:45 -0400
Subject: [PATCH 25/51] Handle empty subpath in exports (#3735)

---
 proposal/package-importer.changes.md | 4 ++++
 proposal/package-importer.d.ts.md    | 6 ++++--
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/proposal/package-importer.changes.md b/proposal/package-importer.changes.md
index 6e005793..81e532b3 100644
--- a/proposal/package-importer.changes.md
+++ b/proposal/package-importer.changes.md
@@ -1,3 +1,7 @@
+## Draft 1.3
+
+* Handle empty subpath in "Resolving package exports" subprocedure.
+
 ## Draft 1.2
 
 * Export `NodePackageImporter` type, and set `_NodePackageImporterBrand` to
diff --git a/proposal/package-importer.d.ts.md b/proposal/package-importer.d.ts.md
index d31b8a51..96821425 100644
--- a/proposal/package-importer.d.ts.md
+++ b/proposal/package-importer.d.ts.md
@@ -1,4 +1,4 @@
-# Package Importer: Draft 1.2
+# Package Importer: Draft 1.3
 
 *([Issue](https://github.com/sass/sass/issues/2739))*
 
@@ -440,7 +440,9 @@ This algorithm takes a package.json value `packageManifest`, a directory URL
 
 * If `exports` is undefined, return null.
 
-* Let `subpathVariants` be the result of [Export load paths] with `subpath`.
+* If `subpath` is empty, let `subpathVariants` be an array with the string `.`.
+  Otherwise, let `subpathVariants` be the result of [Export load paths] with
+  `subpath`.
 
 * Let `resolvedPaths` be a list of the results of calling
   `PACKAGE_EXPORTS_RESOLVE(packageRoot, subpathVariant, exports, ["sass",

From 08072294149487345b4e6576ce661fe4f7026617 Mon Sep 17 00:00:00 2001
From: Jonny Gerig Meyer <jonny@oddbird.net>
Date: Fri, 3 Nov 2023 18:19:28 -0400
Subject: [PATCH 26/51] Clarify that deprecated getters convert color to a
 legacy space before returning channel value. (#3736)

---
 proposal/color-4-new-spaces-js.changes.md |  5 +++++
 proposal/color-4-new-spaces-js.d.ts.md    | 18 ++++++++++++++++--
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/proposal/color-4-new-spaces-js.changes.md b/proposal/color-4-new-spaces-js.changes.md
index 25459801..003f8d6a 100644
--- a/proposal/color-4-new-spaces-js.changes.md
+++ b/proposal/color-4-new-spaces-js.changes.md
@@ -1,3 +1,8 @@
+## Draft 1.5
+
+* Clarify that deprecated SassColor getters (e.g. `red`, `blue`, etc.) convert
+  color to a legacy space before returning channel value.
+
 ## Draft 1.4
 
 * In `change`, adjust algorithm for differentiating `hwb` from `hsl` when only
diff --git a/proposal/color-4-new-spaces-js.d.ts.md b/proposal/color-4-new-spaces-js.d.ts.md
index 94cbd02c..055b4223 100644
--- a/proposal/color-4-new-spaces-js.d.ts.md
+++ b/proposal/color-4-new-spaces-js.d.ts.md
@@ -1,4 +1,4 @@
-# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.4
+# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.5
 
 *([Issue](https://github.com/sass/sass/issues/2831),
 [Changelog](color-4-new-spaces-js.changes.md))*
@@ -876,17 +876,31 @@ A number of SassColor getters only make sense for [legacy color space], and so
 are being deprecated in favor of the new [`channel`] function. This deprecation
 is called `color-4-api`.
 
-[`channel`]: #channel
+The following deprecated getters return the result of
+[`this.channel(channelName, { space: "rgb" })`][`channel`] where `channelName`
+is the name of the respective getter.
 
 * `red`
 * `green`
 * `blue`
+
+The following deprecated getters return the result of
+[`this.channel(channelName, { space: "hsl" })`][`channel`] where `channelName`
+is the name of the respective getter.
+
 * `hue`
 * `saturation`
 * `lightness`
+
+The following deprecated getters return the result of
+[`this.channel(channelName, { space: "hwb" })`][`channel`] where `channelName`
+is the name of the respective getter.
+
 * `whiteness`
 * `blackness`
 
+[`channel`]: #channel
+
 ## Procedures
 
 ### Parsing a Channel Value

From 5073cdfe12781cc50fd33efba2747538baf472cb Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 6 Nov 2023 21:41:24 +0000
Subject: [PATCH 27/51] Bump tj-actions/changed-files from 40.0.0 to 40.1.0
 (#3739)

Bumps [tj-actions/changed-files](https://github.com/tj-actions/changed-files) from 40.0.0 to 40.1.0.
- [Release notes](https://github.com/tj-actions/changed-files/releases)
- [Changelog](https://github.com/tj-actions/changed-files/blob/main/HISTORY.md)
- [Commits](https://github.com/tj-actions/changed-files/compare/af292f1e845a0377b596972698a8598734eb2796...18c8a4ecebe93d32ed8a88e1d0c098f5f68c221b)

---
updated-dependencies:
- dependency-name: tj-actions/changed-files
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d614da4f..ec13200e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -138,7 +138,7 @@ jobs:
 
     - name: Find changed files in js-api-doc
       id: changed-files
-      uses: tj-actions/changed-files@af292f1e845a0377b596972698a8598734eb2796
+      uses: tj-actions/changed-files@18c8a4ecebe93d32ed8a88e1d0c098f5f68c221b
       with: {files: js-api-doc}
 
     - name: Deploy

From bd837938b5da4db7910a1903bbb180c887e14093 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 13 Nov 2023 13:45:46 -0800
Subject: [PATCH 28/51] Bump tj-actions/changed-files from 40.1.0 to 40.1.1
 (#3743)

Bumps [tj-actions/changed-files](https://github.com/tj-actions/changed-files) from 40.1.0 to 40.1.1.
- [Release notes](https://github.com/tj-actions/changed-files/releases)
- [Changelog](https://github.com/tj-actions/changed-files/blob/main/HISTORY.md)
- [Commits](https://github.com/tj-actions/changed-files/compare/18c8a4ecebe93d32ed8a88e1d0c098f5f68c221b...25ef3926d147cd02fc7e931c1ef50772bbb0d25d)

---
updated-dependencies:
- dependency-name: tj-actions/changed-files
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ec13200e..3f021644 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -138,7 +138,7 @@ jobs:
 
     - name: Find changed files in js-api-doc
       id: changed-files
-      uses: tj-actions/changed-files@18c8a4ecebe93d32ed8a88e1d0c098f5f68c221b
+      uses: tj-actions/changed-files@25ef3926d147cd02fc7e931c1ef50772bbb0d25d
       with: {files: js-api-doc}
 
     - name: Deploy

From c6fd2760146a57878b674b608e5bb05ae71dd3d7 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 13 Nov 2023 13:45:57 -0800
Subject: [PATCH 29/51] Bump bufbuild/buf-setup-action from 1.27.2 to 1.28.0
 (#3742)

Bumps [bufbuild/buf-setup-action](https://github.com/bufbuild/buf-setup-action) from 1.27.2 to 1.28.0.
- [Release notes](https://github.com/bufbuild/buf-setup-action/releases)
- [Commits](https://github.com/bufbuild/buf-setup-action/compare/v1.27.2...v1.28.0)

---
updated-dependencies:
- dependency-name: bufbuild/buf-setup-action
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3f021644..e9fd7472 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -72,7 +72,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: bufbuild/buf-setup-action@v1.27.2
+      - uses: bufbuild/buf-setup-action@v1.28.0
         with: {github_token: "${{ github.token }}"}
       - name: Generate protobuf code
         run: buf generate

From 18291df0e3878f5d56e09ada4c7de4816c9e9097 Mon Sep 17 00:00:00 2001
From: Jonny Gerig Meyer <jonny@oddbird.net>
Date: Tue, 14 Nov 2023 19:06:08 -0500
Subject: [PATCH 30/51] [Color 4] Draft 1.6 changes for Color Spaces JS API
 (#3740)

---
 proposal/color-4-new-spaces-js.changes.md | 7 +++++++
 proposal/color-4-new-spaces-js.d.ts.md    | 8 +++-----
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/proposal/color-4-new-spaces-js.changes.md b/proposal/color-4-new-spaces-js.changes.md
index 003f8d6a..f688665b 100644
--- a/proposal/color-4-new-spaces-js.changes.md
+++ b/proposal/color-4-new-spaces-js.changes.md
@@ -1,3 +1,10 @@
+## Draft 1.6
+
+* Simplify the type definition for `interpolate`, and make `options` argument
+  optional.
+
+* Fix typo in `changedValue` definition of `color.change`.
+
 ## Draft 1.5
 
 * Clarify that deprecated SassColor getters (e.g. `red`, `blue`, etc.) convert
diff --git a/proposal/color-4-new-spaces-js.d.ts.md b/proposal/color-4-new-spaces-js.d.ts.md
index 055b4223..4e4be355 100644
--- a/proposal/color-4-new-spaces-js.d.ts.md
+++ b/proposal/color-4-new-spaces-js.d.ts.md
@@ -1,4 +1,4 @@
-# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.5
+# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.6
 
 *([Issue](https://github.com/sass/sass/issues/2831),
 [Changelog](color-4-new-spaces-js.changes.md))*
@@ -330,11 +330,9 @@ isChannelPowerless(
 * Return the result of [`color.mix(internal, color2, options.weight, interpolationMethod)`][`color.mix()`].
 
 ```ts
-interpolate(color2: SassColor, options: {weight?: number}): SassColor;
-
 interpolate(
   color2: SassColor,
-  options: {
+  options?: {
     weight?: number;
     method?: HueInterpolationMethod;
   }
@@ -403,7 +401,7 @@ as the result of changing some of [`internal`]'s components.
 
 * Let `changedValue` be a function that takes a string argument for `channel`
   and calls the procedure [`Changing a Component Value`] with `changes` and
-  `this` as `initial`.
+  `color` as `initial`.
 
 * If `space` equals `hsl` and `spaceSetExplicitly` is `false`:
 

From 9328605f83b563cb9f186e7cbf4ec2b2c6e16ae2 Mon Sep 17 00:00:00 2001
From: Ed Rivas <ed@oddbird.net>
Date: Wed, 15 Nov 2023 20:02:11 -0600
Subject: [PATCH 31/51] [Shared Resources] Draft 1.2 (#3745)

---
 proposal/shared-resources.changes.md | 5 +++++
 proposal/shared-resources.d.ts.md    | 6 +++---
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/proposal/shared-resources.changes.md b/proposal/shared-resources.changes.md
index 47337e17..55e48ce9 100644
--- a/proposal/shared-resources.changes.md
+++ b/proposal/shared-resources.changes.md
@@ -1,3 +1,8 @@
+## Draft 1.2
+
+* Await method calls in example code.
+* Use `compiler.compile*()` methods in example code.
+
 ## Draft 1.1
 
 * Remove unneeded returned/resolved value from `dispose`.
diff --git a/proposal/shared-resources.d.ts.md b/proposal/shared-resources.d.ts.md
index 256e58a8..9e77d5d7 100644
--- a/proposal/shared-resources.d.ts.md
+++ b/proposal/shared-resources.d.ts.md
@@ -97,7 +97,7 @@ function setup() {
   compiler.dispose();
 
   // throws error
-  const result3 = sass.compileString('a {b: c}').css;
+  const result3 = compiler.compileString('a {b: c}').css;
 }
 ```
 
@@ -109,10 +109,10 @@ async function setup() {
   const compiler = await sass.initAsyncCompiler();
   const result1 = await compiler.compileStringAsync('a {b: c}').css;
   const result2 = await compiler.compileStringAsync('a {b: c}').css;
-  compiler.dispose();
+  await compiler.dispose();
 
   // throws error
-  const result3 = sass.compileStringAsync('a {b: c}').css;
+  const result3 = await compiler.compileStringAsync('a {b: c}').css;
 }
 ```
 

From 9dab1882b9b3f8f7d62b245f7293a73f5f15fe23 Mon Sep 17 00:00:00 2001
From: Jonny Gerig Meyer <jonny@oddbird.net>
Date: Fri, 17 Nov 2023 18:27:52 -0500
Subject: [PATCH 32/51] [Color 4] Add JS type definitions and docs for CSS
 Color Level 4. (#3718)

Co-authored-by: James Stuckey Weber <jamesnw@gmail.com>
---
 EMBEDDED_PROTOCOL_CHANGELOG.md  |    8 +-
 js-api-doc/index.d.ts           |   17 +
 js-api-doc/value/color.d.ts     |  568 ++++++++++++++--
 js-api-doc/value/index.d.ts     |   21 +-
 spec/EMBEDDED_PROTOCOL_VERSION  |    2 +-
 spec/embedded-protocol.md       |   27 +-
 spec/embedded_sass.proto        |   68 +-
 spec/js-api/index.d.ts.md       |   17 +
 spec/js-api/value/color.d.ts.md | 1121 +++++++++++++++++++++++++++----
 spec/js-api/value/index.d.ts.md |   21 +-
 10 files changed, 1597 insertions(+), 273 deletions(-)

diff --git a/EMBEDDED_PROTOCOL_CHANGELOG.md b/EMBEDDED_PROTOCOL_CHANGELOG.md
index 75f14b0b..452952fe 100644
--- a/EMBEDDED_PROTOCOL_CHANGELOG.md
+++ b/EMBEDDED_PROTOCOL_CHANGELOG.md
@@ -1,3 +1,9 @@
+## 3.0.0-dev
+
+* Add `Color` SassScript value.
+
+* Remove `RgbColor`, `HslColor` and `HwbColor` SassScript values.
+
 ## 2.1.0
 
 * Use the Java package `com.sass_lang.embedded_protocol` and generate multiple
@@ -18,7 +24,7 @@
   * The `CompileRequest.id`, `CompileResponse.id`, `LogEvent.compilation_id`,
     `CanonicalizeRequest.compilation_id`, `ImportRequest.compilation_id`,
     `FileImportRequest.compilation_id`, and `FunctionCallRequest.compilation_id`
-    fields  have been removed.
+    fields have been removed.
 
 * The following fields are now explicitly declared as proto3 `optional` fields:
   `ImportSuccess.source_map_url`, `LogEvent.span`, `SourceSpan.end`. These
diff --git a/js-api-doc/index.d.ts b/js-api-doc/index.d.ts
index 2a41b586..7967ae56 100644
--- a/js-api-doc/index.d.ts
+++ b/js-api-doc/index.d.ts
@@ -32,7 +32,24 @@ export {
   CalculationOperation,
   CalculationOperator,
   CalculationValue,
+  ChannelName,
+  ChannelNameHsl,
+  ChannelNameHwb,
+  ChannelNameLch,
+  ChannelNameLab,
+  ChannelNameRgb,
+  ChannelNameXyz,
+  ColorSpaceHsl,
+  ColorSpaceHwb,
+  ColorSpaceLch,
+  ColorSpaceLab,
+  ColorSpaceRgb,
+  ColorSpaceXyz,
+  HueInterpolationMethod,
+  KnownColorSpace,
   ListSeparator,
+  PolarColorSpace,
+  RectangularColorSpace,
   SassArgumentList,
   SassBoolean,
   SassCalculation,
diff --git a/js-api-doc/value/color.d.ts b/js-api-doc/value/color.d.ts
index d016baf0..4ba8909f 100644
--- a/js-api-doc/value/color.d.ts
+++ b/js-api-doc/value/color.d.ts
@@ -1,5 +1,84 @@
+import {List} from 'immutable';
+
 import {Value} from './index';
 
+/** The HSL color space name. */
+export type ColorSpaceHsl = 'hsl';
+
+/** The HSL color space channel names. */
+export type ChannelNameHsl = 'hue' | 'saturation' | 'lightness' | 'alpha';
+
+/** The HWB color space name. */
+export type ColorSpaceHwb = 'hwb';
+
+/** The HWB color space channel names. */
+export type ChannelNameHwb = 'hue' | 'whiteness' | 'blackness' | 'alpha';
+
+/** The Lab / Oklab color space names. */
+export type ColorSpaceLab = 'lab' | 'oklab';
+
+/** The Lab / Oklab color space channel names. */
+export type ChannelNameLab = 'lightness' | 'a' | 'b' | 'alpha';
+
+/** The LCH / Oklch color space names. */
+export type ColorSpaceLch = 'lch' | 'oklch';
+
+/** The LCH / Oklch color space channel names. */
+export type ChannelNameLch = 'lightness' | 'chroma' | 'hue' | 'alpha';
+
+/** Names of color spaces with RGB channels. */
+export type ColorSpaceRgb =
+  | 'a98-rgb'
+  | 'display-p3'
+  | 'prophoto-rgb'
+  | 'rec2020'
+  | 'rgb'
+  | 'srgb'
+  | 'srgb-linear';
+
+/** RGB channel names. */
+export type ChannelNameRgb = 'red' | 'green' | 'blue' | 'alpha';
+
+/** Names of color spaces with XYZ channels. */
+export type ColorSpaceXyz = 'xyz' | 'xyz-d50' | 'xyz-d65';
+
+/** XYZ channel names. */
+export type ChannelNameXyz = 'x' | 'y' | 'z' | 'alpha';
+
+/** All supported color space channel names. */
+export type ChannelName =
+  | ChannelNameHsl
+  | ChannelNameHwb
+  | ChannelNameLab
+  | ChannelNameLch
+  | ChannelNameRgb
+  | ChannelNameXyz;
+
+/** All supported color space names. */
+export type KnownColorSpace =
+  | ColorSpaceHsl
+  | ColorSpaceHwb
+  | ColorSpaceLab
+  | ColorSpaceLch
+  | ColorSpaceRgb
+  | ColorSpaceXyz;
+
+/** Polar color space names (HSL, HWB, LCH, and Oklch spaces). */
+export type PolarColorSpace = ColorSpaceHsl | ColorSpaceHwb | ColorSpaceLch;
+
+/** Rectangular color space names (Lab, Oklab, RGB, and XYZ spaces). */
+export type RectangularColorSpace = Exclude<KnownColorSpace, PolarColorSpace>;
+
+/**
+ * Methods by which two hues are adjusted when interpolating between polar
+ * colors.
+ */
+export type HueInterpolationMethod =
+  | 'decreasing'
+  | 'increasing'
+  | 'longer'
+  | 'shorter';
+
 /**
  * Sass's [color type](https://sass-lang.com/documentation/values/colors).
  *
@@ -10,119 +89,474 @@ import {Value} from './index';
  */
 export class SassColor extends Value {
   /**
-   * Creates an RGB color.
+   * Creates an [RGB color].
    *
-   * **Only** `undefined` should be passed to indicate a missing `alpha`. If
-   * `null` is passed instead, it will be treated as a [missing component] in
-   * future versions of Dart Sass. See [breaking changes] for details.
+   * If `space` is missing, **only** `undefined` should be used to indicate that
+   * `alpha` isn't passed. If `null` is used instead, it will be treated as a
+   * [missing component]. See [breaking changes] for details.
    *
+   * If `space` is defined and `null` is passed for any component, it will be
+   * treated as a [missing component].
+   *
+   * [RGB color]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb
    * [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
    * [breaking changes]: /documentation/breaking-changes/null-alpha
    *
-   * @throws `Error` if `red`, `green`, and `blue` aren't between `0` and
-   * `255`, or if `alpha` isn't between `0` and `1`.
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
    */
   constructor(options: {
-    red: number;
-    green: number;
-    blue: number;
-    alpha?: number;
+    red: number | null;
+    green: number | null;
+    blue: number | null;
+    alpha?: number | null;
+    space?: 'rgb';
   });
 
   /**
-   * Creates an HSL color.
+   * Creates an [HSL color].
    *
-   * **Only** `undefined` should be passed to indicate a missing `alpha`. If
-   * `null` is passed instead, it will be treated as a [missing component] in
-   * future versions of Dart Sass. See [breaking changes] for details.
+   * If `space` is missing, **only** `undefined` should be used to indicate that
+   * `alpha` isn't passed. If `null` is used instead, it will be treated as a
+   * [missing component]. See [breaking changes] for details.
    *
+   * If `space` is defined and `null` is passed for any component, it will be
+   * treated as a [missing component].
+   *
+   * [HSL color]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl
    * [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
    * [breaking changes]: /documentation/breaking-changes/null-alpha
    *
-   * @throws `Error` if `saturation` or `lightness` aren't between `0` and
-   * `100`, or if `alpha` isn't between `0` and `1`.
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
+   * @throws `Error` if `lightness` isn't `null` or a number between between `0`
+   * and `100`.
    */
   constructor(options: {
-    hue: number;
-    saturation: number;
-    lightness: number;
-    alpha?: number;
+    hue: number | null;
+    saturation: number | null;
+    lightness: number | null;
+    alpha?: number | null;
+    space?: ColorSpaceHsl;
   });
 
   /**
-   * Creates an HWB color.
+   * Creates an [HWB color].
    *
-   * **Only** `undefined` should be passed to indicate a missing `alpha`. If
-   * `null` is passed instead, it will be treated as a [missing component] in
-   * future versions of Dart Sass. See [breaking changes] for details.
+   * If `space` is missing, **only** `undefined` should be used to indicate that
+   * `alpha` isn't passed. If `null` is used instead, it will be treated as a
+   * [missing component]. See [breaking changes] for details.
    *
+   * If `space` is defined and `null` is passed for any component, it will be
+   * treated as a [missing component].
+   *
+   * [HWB color]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hwb
    * [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
    * [breaking changes]: /documentation/breaking-changes/null-alpha
    *
-   * @throws `Error` if `whiteness` or `blackness` aren't between `0` and `100`,
-   * or if `alpha` isn't between `0` and `1`.
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
    */
   constructor(options: {
-    hue: number;
-    whiteness: number;
-    blackness: number;
-    alpha?: number;
+    hue: number | null;
+    whiteness: number | null;
+    blackness: number | null;
+    alpha?: number | null;
+    space?: ColorSpaceHwb;
   });
 
-  /** This color's red channel, between `0` and `255`. */
-  get red(): number;
+  /**
+   * Creates a [Lab] or [Oklab] color.
+   *
+   * If `null` is passed for any component, it will be treated as a [missing
+   * component].
+   *
+   * [Lab]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/lab
+   * [Oklab]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklab
+   * [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
+   *
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
+   * @throws `Error` if `lightness` isn't `null` or a number between `0` and the
+   * maximum channel value for `space`—`100` for Lab or `1` for Oklab.
+   */
+  constructor(options: {
+    lightness: number | null;
+    a: number | null;
+    b: number | null;
+    alpha?: number | null;
+    space: ColorSpaceLab;
+  });
 
-  /** This color's green channel, between `0` and `255`. */
-  get green(): number;
+  /**
+   * Creates an [LCH] or [Oklch] color.
+   *
+   * If `null` is passed for any component, it will be treated as a [missing
+   * component].
+   *
+   * [LCH]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/lch
+   * [Oklch]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch
+   * [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
+   *
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
+   * @throws `Error` if `lightness` isn't `null` or a number between `0` and the
+   * maximum channel value for `space`—`100` for LCH or `1` for Oklch.
+   */
+  constructor(options: {
+    lightness: number | null;
+    chroma: number | null;
+    hue: number | null;
+    alpha?: number | null;
+    space: ColorSpaceLch;
+  });
 
-  /** This color's blue channel, between `0` and `255`. */
-  get blue(): number;
+  /**
+   * Creates a color in a predefined [RGB color space].
+   *
+   * If `null` is passed for any component, it will be treated as a [missing
+   * component].
+   *
+   * [RGB color space]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color#using_predefined_colorspaces_with_color
+   * [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
+   *
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
+   */
+  constructor(options: {
+    red: number | null;
+    green: number | null;
+    blue: number | null;
+    alpha?: number | null;
+    space: Exclude<ColorSpaceRgb, 'rgb'>;
+  });
 
-  /** This color's hue, between `0` and `360`. */
-  get hue(): number;
+  /**
+   * Creates a color in a predefined [XYZ color space].
+   *
+   * If `null` is passed for any component, it will be treated as a [missing
+   * component].
+   *
+   * [XYZ color space]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color#using_the_xyz_colorspace_with_color
+   * [missing component]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
+   *
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
+   */
+  constructor(options: {
+    x: number | null;
+    y: number | null;
+    z: number | null;
+    alpha?: number | null;
+    space: ColorSpaceXyz;
+  });
 
-  /** This color's saturation, between `0` and `100`. */
-  get saturation(): number;
+  /** The name of this color's space. */
+  get space(): KnownColorSpace;
 
-  /** This color's lightness, between `0` and `100`. */
-  get lightness(): number;
+  /**
+   * Returns a new color that's the result of converting this color to the
+   * specified `space`.
+   */
+  toSpace(space: KnownColorSpace): SassColor;
 
-  /** This color's whiteness, between `0` and `100`. */
-  get whiteness(): number;
+  /**
+   * A boolean indicating whether this color is in a legacy color space (`rgb`,
+   * `hsl`, or `hwb`).
+   */
+  get isLegacy(): boolean;
 
-  /** This color's blackness, between `0` and `100`. */
-  get blackness(): number;
+  /**
+   * Returns a boolean indicating whether this color is in-gamut (as opposed to
+   * having one or more of its channels out of bounds) for the specified
+   * `space`, or its current color space if `space` is not specified.
+   */
+  isInGamut(space?: KnownColorSpace): boolean;
+
+  /**
+   * Returns a copy of this color, modified so it is in-gamut for the specified
+   * `space`—or the current color space if `space` is not specified—using the
+   * recommended [CSS Gamut Mapping Algorithm][css-mapping] to map out-of-gamut
+   * colors into the desired gamut with as little perceptual change as possible.
+   *
+   * [css-mapping]:
+   * https://www.w3.org/TR/css-color-4/#css-gamut-mapping-algorithm
+   */
+  toGamut(space?: KnownColorSpace): SassColor;
+
+  /**
+   * A list of this color's channel values (excluding alpha), with [missing
+   * channels] converted to `null`.
+   *
+   * [missing channels]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
+   */
+  get channelsOrNull(): List<number | null>;
+
+  /**
+   * A list of this color's channel values (excluding alpha), with [missing
+   * channels] converted to `0`.
+   *
+   * [missing channels]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
+   */
+  get channels(): List<number>;
+
+  /**
+   * Returns the value of a single specified `channel` of this color, with
+   * [missing channels] converted to `0`.
+   *
+   * [missing channels]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
+   *
+   * @throws `Error` if `channel` is not `alpha` or a channel in this color's
+   * space.
+   */
+  channel(channel: ChannelName): number;
+
+  /**
+   * Returns the value of a single specified `channel` of this color after
+   * converting this color to the specified `space`, with [missing channels]
+   * converted to `0`.
+   *
+   * [missing channels]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
+   *
+   * @throws `Error` if `channel` is not `alpha` or a channel in `space`.
+   */
+  channel(channel: ChannelNameHsl, options: {space: ColorSpaceHsl}): number;
+  channel(channel: ChannelNameHwb, options: {space: ColorSpaceHwb}): number;
+  channel(channel: ChannelNameLab, options: {space: ColorSpaceLab}): number;
+  channel(channel: ChannelNameLch, options: {space: ColorSpaceLch}): number;
+  channel(channel: ChannelNameRgb, options: {space: ColorSpaceRgb}): number;
+  channel(channel: ChannelNameXyz, options: {space: ColorSpaceXyz}): number;
 
   /** This color's alpha channel, between `0` and `1`. */
   get alpha(): number;
 
   /**
-   * Changes one or more of this color's RGB channels and returns the result.
+   * Returns a boolean indicating whether a given channel value is a [missing
+   * channel].
+   *
+   * [missing channel]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#missing_color_components
    */
-  change(options: {
-    red?: number;
-    green?: number;
-    blue?: number;
-    alpha?: number;
-  }): SassColor;
+  isChannelMissing(channel: ChannelName): boolean;
 
   /**
-   * Changes one or more of this color's HSL channels and returns the result.
+   * Returns a boolean indicating whether a given `channel` is [powerless] in
+   * this color. This is a special state that's defined for individual color
+   * spaces, which indicates that a channel's value won't affect how a color is
+   * displayed.
+   *
+   * [powerless]: https://www.w3.org/TR/css-color-4/#powerless
    */
-  change(options: {
-    hue?: number;
-    saturation?: number;
-    lightness?: number;
-    alpha?: number;
-  }): SassColor;
+  isChannelPowerless(channel: ChannelName): boolean;
+  isChannelPowerless(
+    channel: ChannelNameHsl,
+    options?: {space: ColorSpaceHsl}
+  ): boolean;
+  isChannelPowerless(
+    channel: ChannelNameHwb,
+    options?: {space: ColorSpaceHwb}
+  ): boolean;
+  isChannelPowerless(
+    channel: ChannelNameLab,
+    options?: {space: ColorSpaceLab}
+  ): boolean;
+  isChannelPowerless(
+    channel: ChannelNameLch,
+    options?: {space: ColorSpaceLch}
+  ): boolean;
+  isChannelPowerless(
+    channel: ChannelNameRgb,
+    options?: {space: ColorSpaceRgb}
+  ): boolean;
+  isChannelPowerless(
+    channel: ChannelNameXyz,
+    options?: {space: ColorSpaceXyz}
+  ): boolean;
 
   /**
-   * Changes one or more of this color's HWB channels and returns the result.
+   * Returns a color partway between this color and `color2` according to
+   * `method`, as defined by the CSS Color 4 [color interpolation] procedure.
+   *
+   * [color interpolation]: https://www.w3.org/TR/css-color-4/#interpolation
+   *
+   * If `method` is missing and this color is in a rectangular color space (Lab,
+   * Oklab, RGB, and XYZ spaces), `method` defaults to the color space of this
+   * color. Otherwise, `method` defaults to a space separated list containing
+   * the color space of this color and the string "shorter".
+   *
+   * The `weight` is a number between 0 and 1 that indicates how much of this
+   * color should be in the resulting color. If omitted, it defaults to 0.5.
    */
-  change(options: {
-    hue?: number;
-    whiteness?: number;
-    blackness?: number;
-    alpha?: number;
-  }): SassColor;
+  interpolate(
+    color2: SassColor,
+    options?: {
+      weight?: number;
+      method?: HueInterpolationMethod;
+    }
+  ): SassColor;
+
+  /**
+   * Returns a new color that's the result of changing one or more of this
+   * color's HSL channels.
+   *
+   * @throws `Error` if `space` is missing and this color is not in a legacy
+   * color space (`rgb`, `hsl`, or `hwb`).
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
+   * @throws `Error` if `lightness` is set and isn't `null` or a number between
+   * `0` and `100`.
+   */
+  change(
+    options: {
+      [key in ChannelNameHsl]?: number | null;
+    } & {
+      space?: ColorSpaceHsl;
+    }
+  ): SassColor;
+
+  /**
+   * Returns a new color that's the result of changing one or more of this
+   * color's HWB channels.
+   *
+   * @throws `Error` if `space` is missing and this color is not in a legacy
+   * color space (`rgb`, `hsl`, or `hwb`).
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
+   */
+  change(
+    options: {
+      [key in ChannelNameHwb]?: number | null;
+    } & {
+      space?: ColorSpaceHwb;
+    }
+  ): SassColor;
+
+  /**
+   * Returns a new color that's the result of changing one or more of this
+   * color's Lab channels.
+   *
+   * @throws `Error` if `space` is missing and this color is not in the Lab or
+   * Oklab color spaces.
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
+   * @throws `Error` if `lightness` is set and isn't `null` or a number between
+   * `0` and the maximum channel value for `space` (or this color's color space,
+   * if `space` is missing)—`100` for Lab or `1` for Oklab.
+   */
+  change(
+    options: {
+      [key in ChannelNameLab]?: number | null;
+    } & {
+      space?: ColorSpaceLab;
+    }
+  ): SassColor;
+
+  /**
+   * Returns a new color that's the result of changing one or more of this
+   * color's LCH channels.
+   *
+   * @throws `Error` if `space` is missing and this color is not in the LCH or
+   * Oklch color spaces.
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
+   * @throws `Error` if `lightness` is set and isn't `null` or a number between
+   * `0` and the maximum channel value for `space` (or this color's color space,
+   * if `space` is missing)—`100` for LCH or `1` for Oklch.
+   */
+  change(
+    options: {
+      [key in ChannelNameLch]?: number | null;
+    } & {
+      space?: ColorSpaceLch;
+    }
+  ): SassColor;
+
+  /**
+   * Returns a new color that's the result of changing one or more of this
+   * color's RGB channels.
+   *
+   * @throws `Error` if `space` is missing and this color is not in a legacy
+   * color space (`rgb`, `hsl`, or `hwb`).
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
+   */
+  change(
+    options: {
+      [key in ChannelNameRgb]?: number | null;
+    } & {
+      space?: ColorSpaceRgb;
+    }
+  ): SassColor;
+
+  /**
+   * Returns a new color that's the result of changing one or more of this
+   * color's XYZ channels.
+   *
+   * @throws `Error` if `space` is missing and this color is not in an XYZ color
+   * space.
+   * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
+   * and `1`.
+   */
+  change(
+    options: {
+      [key in ChannelNameXyz]?: number | null;
+    } & {
+      space?: ColorSpaceXyz;
+    }
+  ): SassColor;
+
+  /**
+   * This color's red channel in the RGB color space, between `0` and `255`.
+   *
+   * @deprecated Use {@link channel} instead.
+   */
+  get red(): number;
+
+  /**
+   * This color's green channel in the RGB color space, between `0` and `255`.
+   *
+   * @deprecated Use {@link channel} instead.
+   */
+  get green(): number;
+
+  /**
+   * This color's blue channel in the RGB color space, between `0` and `255`.
+   *
+   * @deprecated Use {@link channel} instead.
+   */
+  get blue(): number;
+
+  /**
+   * This color's hue in the HSL color space, between `0` and `360`.
+   *
+   * @deprecated Use {@link channel} instead.
+   */
+  get hue(): number;
+
+  /**
+   * This color's saturation in the HSL color space, between `0` and `100`.
+   *
+   * @deprecated Use {@link channel} instead.
+   */
+  get saturation(): number;
+
+  /**
+   * This color's lightness in the HSL color space, between `0` and `100`.
+   *
+   * @deprecated Use {@link channel} instead.
+   */
+  get lightness(): number;
+
+  /**
+   * This color's whiteness in the HWB color space, between `0` and `100`.
+   *
+   * @deprecated Use {@link channel} instead.
+   */
+  get whiteness(): number;
+
+  /**
+   * This color's blackness in the HWB color space, between `0` and `100`.
+   *
+   * @deprecated Use {@link channel} instead.
+   */
+  get blackness(): number;
 }
diff --git a/js-api-doc/value/index.d.ts b/js-api-doc/value/index.d.ts
index 38d28df8..94628bca 100644
--- a/js-api-doc/value/index.d.ts
+++ b/js-api-doc/value/index.d.ts
@@ -19,7 +19,26 @@ export {
   CalculationOperation,
   CalculationInterpolation,
 } from './calculation';
-export {SassColor} from './color';
+export {
+  SassColor,
+  ColorSpaceHsl,
+  ChannelNameHsl,
+  ColorSpaceHwb,
+  ChannelNameHwb,
+  ColorSpaceLab,
+  ChannelNameLab,
+  ColorSpaceLch,
+  ChannelNameLch,
+  ColorSpaceRgb,
+  ChannelNameRgb,
+  ColorSpaceXyz,
+  ChannelNameXyz,
+  ChannelName,
+  KnownColorSpace,
+  PolarColorSpace,
+  RectangularColorSpace,
+  HueInterpolationMethod,
+} from './color';
 export {SassFunction} from './function';
 export {SassList, ListSeparator} from './list';
 export {SassMap} from './map';
diff --git a/spec/EMBEDDED_PROTOCOL_VERSION b/spec/EMBEDDED_PROTOCOL_VERSION
index 276cbf9e..2468aa9e 100644
--- a/spec/EMBEDDED_PROTOCOL_VERSION
+++ b/spec/EMBEDDED_PROTOCOL_VERSION
@@ -1 +1 @@
-2.3.0
+3.0.0-dev
diff --git a/spec/embedded-protocol.md b/spec/embedded-protocol.md
index a8978577..f4b2d12d 100644
--- a/spec/embedded-protocol.md
+++ b/spec/embedded-protocol.md
@@ -257,29 +257,16 @@ the same equality semantics can be generated for a number `x` by rounding
 
 ### Colors
 
-The protocol includes three distinct color value types, `RgbColor`, `HslColor`,
-and `HwbColor`. In Sass code and custom functions, colors may be represented or
-manipulated in either RGB, HSL, or HWB form, so having multiple types allows
-whichever form is currently in use to be sent between endpoints without having
-to eagerly normalize it.
+Colors are represented by the `Color` value type. The API should provide means
+of changing one or more channels of a color while leaving other channels as-is.
 
-However, users of the host language API should be able to transparently treat
-any color object as though it were either RGB, HSL, or HWB form. The API should
-provide access to the red, green, and blue, hue, saturation, lightness,
-whiteness, and blackness channels of *every* color object. It should use [this
-RGB-to-HSL algorithm], [this HSL-to-RGB algorithm], [this RGB-to-HWB algorithm],
-and [this HWB-to-RGB algorithm] to convert between representations as necessary.
+Two [legacy colors] are equal if their RGB forms have the same red, green, blue
+channels and alpha channels equal rounded to the nearest 1e-11.
 
-[this RGB-to-HSL algorithm]: https://en.wikipedia.org/wiki/HSL_and_HSV#RGB_to_HSL_and_HSV
-[this HSL-to-RGB algorithm]: https://www.w3.org/TR/css3-color/#hsl-color
-[this RGB-to-HWB algorithm]: https://www.w3.org/TR/css-color-4/#rgb-to-hwb
-[this HWB-to-RGB algorithm]: https://www.w3.org/TR/css-color-4/#hwb-to-rgb
+Two non-legacy colors are equal if they are in the same color space and their
+channel and alpha values are equal rounded to the nearest 1e-11.
 
-The API should also provide means of changing one or more channels of a color
-while leaving other channels as-is.
-
-Two colors are equal if their RGB forms have the same red, green, blue channels
-and alpha channels within 1e-11 of one another.
+[legacy colors]: ../proposal/color-4-new-spaces.md#legacy-color
 
 ### Lists
 
diff --git a/spec/embedded_sass.proto b/spec/embedded_sass.proto
index b0307006..b7c034c1 100644
--- a/spec/embedded_sass.proto
+++ b/spec/embedded_sass.proto
@@ -763,62 +763,22 @@ message Value {
     repeated string denominators = 3;
   }
 
-  // A SassScript color value, represented as red, green, and blue channels.
-  //
-  // All Sass color values can be equivalently represented as `RgbColor`,
-  // `HslColor`, and `HwbColor` messages without loss of color information that
-  // can affect CSS rendering. As such, either endpoint may choose to send any
-  // color value as any one of these three messages.
-  message RgbColor {
-    // The color's red channel. May not be above 255.
-    uint32 red = 1;
+  // A SassScript color value.
+  message Color {
+    // The name of a known color space.
+    string space = 1;
 
-    // The color's green channel. May not be above 255.
-    uint32 green = 2;
+    // The value of the first channel associated with `space`.
+    double channel1 = 2;
 
-    // The color's blue channel. May not be above 255.
-    uint32 blue = 3;
+    // The value of the second channel associated with `space`.
+    double channel2 = 3;
 
-    // The color's alpha channel. Must be between 0 and 1,
-    // inclusive.
-    double alpha = 4;
-  }
+    // The value of the third channel associated with `space`.
+    double channel3 = 4;
 
-  // A SassScript color value, represented as hue, saturation, and lightness channels.
-  message HslColor {
-    // The color's hue.
-    double hue = 1;
-
-    // The color's percent saturation. Must be between 0 and 100,
-    // inclusive.
-    double saturation = 2;
-
-    // The color's percent lightness. Must be between 0 and 100,
-    // inclusive.
-    double lightness = 3;
-
-    // The color's alpha channel. Must be between 0 and 1,
-    // inclusive.
-    double alpha = 4;
-  }
-
-  // A SassScript color value, represented as hue, whiteness, and blackness
-  // channels.
-  message HwbColor {
-    // The color's hue.
-    double hue = 1;
-
-    // The color's percent whiteness. Must be between 0 and 100,
-    // inclusive. The sum of `whiteness` and `blackness` must not exceed 100.
-    double whiteness = 2;
-
-    // The color's percent blackness. Must be between 0 and 100,
-    // inclusive. The sum of `whiteness` and `blackness` must not exceed 100.
-    double blackness = 3;
-
-    // The color's alpha channel. Mandatory. Must be between 0 and 1,
-    // inclusive.
-    double alpha = 4;
+    // The color's alpha channel. Mandatory. Must be between 0 and 1, inclusive.
+    double alpha = 5;
   }
 
   // A SassScript list value.
@@ -1001,17 +961,15 @@ message Value {
   oneof value {
     String string = 1;
     Number number = 2;
-    RgbColor rgb_color = 3;
-    HslColor hsl_color = 4;
     List list = 5;
     Map map = 6;
     SingletonValue singleton = 7;
     CompilerFunction compiler_function = 8;
     HostFunction host_function = 9;
     ArgumentList argument_list = 10;
-    HwbColor hwb_color = 11;
     Calculation calculation = 12;
     CompilerMixin compiler_mixin = 13;
+    Color color = 14;
   }
 }
 
diff --git a/spec/js-api/index.d.ts.md b/spec/js-api/index.d.ts.md
index e57fd0dd..17b40664 100644
--- a/spec/js-api/index.d.ts.md
+++ b/spec/js-api/index.d.ts.md
@@ -69,7 +69,24 @@ export {
   CalculationOperation,
   CalculationOperator,
   CalculationValue,
+  ChannelName,
+  ChannelNameHsl,
+  ChannelNameHwb,
+  ChannelNameLch,
+  ChannelNameLab,
+  ChannelNameRgb,
+  ChannelNameXyz,
+  ColorSpaceHsl,
+  ColorSpaceHwb,
+  ColorSpaceLch,
+  ColorSpaceLab,
+  ColorSpaceRgb,
+  ColorSpaceXyz,
+  HueInterpolationMethod,
+  KnownColorSpace,
   ListSeparator,
+  PolarColorSpace,
+  RectangularColorSpace,
   SassArgumentList,
   SassBoolean,
   SassCalculation,
diff --git a/spec/js-api/value/color.d.ts.md b/spec/js-api/value/color.d.ts.md
index 85885e6b..e2f7fa4b 100644
--- a/spec/js-api/value/color.d.ts.md
+++ b/spec/js-api/value/color.d.ts.md
@@ -1,15 +1,54 @@
 # Color API
 
 ```ts
+import {List} from 'immutable';
+
 import {Value} from './index';
 ```
 
 ## Table of Contents
 
 * [Types](#types)
+  * [`ColorSpaceHsl`](#colorspacehsl)
+  * [`ChannelNameHsl`](#channelnamehsl)
+  * [`ColorSpaceHwb`](#colorspacehwb)
+  * [`ChannelNameHwb`](#channelnamehwb)
+  * [`ColorSpaceLab`](#colorspacelab)
+  * [`ChannelNameLab`](#channelnamelab)
+  * [`ColorSpaceLch`](#colorspacelch)
+  * [`ChannelNameLch`](#channelnamelch)
+  * [`ColorSpaceRgb`](#colorspacergb)
+  * [`ChannelNameRgb`](#channelnamergb)
+  * [`ColorSpaceXyz`](#colorspacexyz)
+  * [`ChannelNameXyz`](#channelnamexyz)
+  * [`ChannelName`](#channelname)
+  * [`KnownColorSpace`](#knowncolorspace)
+  * [`PolarColorSpace`](#polarcolorspace)
+  * [`RectangularColorSpace`](#rectangularcolorspace)
+  * [`HueInterpolationMethod`](#hueinterpolationmethod)
   * [`SassColor`](#sasscolor)
     * [`internal`](#internal)
     * [Constructor](#constructor)
+      * [RGB](#rgb)
+      * [HSL](#hsl)
+      * [HWB](#hwb)
+      * [Lab](#lab)
+      * [LCH](#lch)
+      * [Predefined RGB](#predefined-rgb)
+      * [XYZ](#xyz)
+    * [`space`](#space)
+    * [`toSpace`](#tospace)
+    * [`isLegacy`](#islegacy)
+    * [`isInGamut`](#isingamut)
+    * [`toGamut`](#togamut)
+    * [`channelsOrNull`](#channelsornull)
+    * [`channels`](#channels)
+    * [`channel`](#channel)
+    * [`alpha`](#alpha)
+    * [`isChannelMissing`](#ischannelmissing)
+    * [`isChannelPowerless`](#ischannelpowerless)
+    * [`interpolate`](#interpolate)
+    * [`change`](#change)
     * [`red`](#red)
     * [`green`](#green)
     * [`blue`](#blue)
@@ -18,11 +57,173 @@ import {Value} from './index';
     * [`lightness`](#lightness)
     * [`whiteness`](#whiteness)
     * [`blackness`](#blackness)
-    * [`alpha`](#alpha)
-    * [`change`](#change)
+* [Procedures](#procedures)
+  * [Parsing a Channel Value](#parsing-a-channel-value)
+  * [Parsing a Clamped Channel Value](#parsing-a-clamped-channel-value)
+  * [Changing a Component Value](#changing-a-component-value)
 
 ## Types
 
+### `ColorSpaceHsl`
+
+The HSL color space name.
+
+```ts
+export type ColorSpaceHsl = 'hsl';
+```
+
+### `ChannelNameHsl`
+
+The HSL color space channel names.
+
+```ts
+export type ChannelNameHsl = 'hue' | 'saturation' | 'lightness' | 'alpha';
+```
+
+### `ColorSpaceHwb`
+
+The HWB color space name.
+
+```ts
+export type ColorSpaceHwb = 'hwb';
+```
+
+### `ChannelNameHwb`
+
+The HWB color space channel names.
+
+```ts
+export type ChannelNameHwb = 'hue' | 'whiteness' | 'blackness' | 'alpha';
+```
+
+### `ColorSpaceLab`
+
+The Lab and Oklab color space names.
+
+```ts
+export type ColorSpaceLab = 'lab' | 'oklab';
+```
+
+### `ChannelNameLab`
+
+The Lab and Oklab color space channel names.
+
+```ts
+export type ChannelNameLab = 'lightness' | 'a' | 'b' | 'alpha';
+```
+
+### `ColorSpaceLch`
+
+The LCH and Oklch color space names.
+
+```ts
+export type ColorSpaceLch = 'lch' | 'oklch';
+```
+
+### `ChannelNameLch`
+
+The LCH and Oklch color space channel names.
+
+```ts
+export type ChannelNameLch = 'lightness' | 'chroma' | 'hue' | 'alpha';
+```
+
+### `ColorSpaceRgb`
+
+Names of color spaces with RGB channels.
+
+```ts
+export type ColorSpaceRgb =
+  | 'a98-rgb'
+  | 'display-p3'
+  | 'prophoto-rgb'
+  | 'rec2020'
+  | 'rgb'
+  | 'srgb'
+  | 'srgb-linear';
+```
+
+### `ChannelNameRgb`
+
+RGB channel names.
+
+```ts
+export type ChannelNameRgb = 'red' | 'green' | 'blue' | 'alpha';
+```
+
+### `ColorSpaceXyz`
+
+Names of color spaces with XYZ channels.
+
+```ts
+export type ColorSpaceXyz = 'xyz' | 'xyz-d50' | 'xyz-d65';
+```
+
+### `ChannelNameXyz`
+
+XYZ channel names.
+
+```ts
+export type ChannelNameXyz = 'x' | 'y' | 'z' | 'alpha';
+```
+
+### `ChannelName`
+
+All supported channel names.
+
+```ts
+export type ChannelName =
+  | ChannelNameHsl
+  | ChannelNameHwb
+  | ChannelNameLab
+  | ChannelNameLch
+  | ChannelNameRgb
+  | ChannelNameXyz;
+```
+
+### `KnownColorSpace`
+
+All supported color space names.
+
+```ts
+export type KnownColorSpace =
+  | ColorSpaceHsl
+  | ColorSpaceHwb
+  | ColorSpaceLab
+  | ColorSpaceLch
+  | ColorSpaceRgb
+  | ColorSpaceXyz;
+```
+
+### `PolarColorSpace`
+
+Names of known color spaces which use a polar angle value for the `hue` channel.
+
+```ts
+export type PolarColorSpace = ColorSpaceHsl | ColorSpaceHwb | ColorSpaceLch;
+```
+
+### `RectangularColorSpace`
+
+Names of known color spaces which do not use a polar angle value for the `hue`
+channel.
+
+```ts
+export type RectangularColorSpace = Exclude<KnownColorSpace, PolarColorSpace>;
+```
+
+### `HueInterpolationMethod`
+
+Methods by which two hues are adjusted when interpolating between polar colors.
+
+```ts
+export type HueInterpolationMethod =
+  | 'decreasing'
+  | 'increasing'
+  | 'longer'
+  | 'shorter';
+```
+
 ### `SassColor`
 
 The JS API representation of a Sass color.
@@ -39,84 +240,760 @@ The [private `internal` field] refers to a Sass color.
 
 #### Constructor
 
-* If `options.red` is set:
+* If `options.space` is set, let `constructionSpace` be `options.space`.
 
-  * Let `red` be a Sass number with a value of `options.red` `fuzzyRound`ed
-    to the nearest integer.
+* Otherwise, if `options.red` is set, let `constructionSpace` be "rgb".
 
-  * Let `green` be a Sass number with a value of `options.green`
-    `fuzzyRound`ed to the nearest integer.
+* Otherwise, if `options.saturation` is set, let `constructionSpace` be "hsl".
 
-  * Let `blue` be a Sass number with a value of `options.blue`
-    `fuzzyRound`ed to the nearest integer.
+* Otherwise, if `options.whiteness` is set, let `constructionSpace` be "hwb".
 
-  * If `options.alpha` is set, let `alpha` be a Sass number with a value of
-    `options.alpha`. Otherwise, let `alpha` be `null`.
+* Otherwise, throw an error.
 
-  * Set [`internal`] to the result of [`rgb(red, green, blue, alpha)`].
+##### RGB
 
-  [`internal`]: #internal
-  [`rgb(red, green, blue, alpha)`]: ../../functions.md#rgb-and-rgba
+* If `constructionSpace` is "rgb":
 
-* Otherwise, if `options.saturation` is set:
+  * If `options.alpha` is `null` and `options.space` is not set, emit a
+    deprecation warning named `null-alpha`.
 
-  * Let `hue` be a Sass number with a value of `options.hue`.
+  * Let `red` be the result of [parsing a channel value] with value
+    `options.red`.
 
-  * Let `saturation` be a Sass number with a value of `options.saturation`.
+  * Let `green` be the result of [parsing a channel value] with value
+    `options.green`.
 
-  * Let `lightness` be a Sass number with a value of `options.lightness`.
+  * Let `blue` be the result of [parsing a channel value] with value
+    `options.blue`.
 
-  * If `options.alpha` is set, let `alpha` be a Sass number with a value of
-    `options.alpha`. Otherwise, let `alpha` be `null`.
+  * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
+    the result of [parsing a clamped channel value] with `value` of
+    `options.alpha`, `minimum` of `0`, and `maximum` of `1`.
 
-  * Set [`internal`] to the result of [`hsl(hue, saturation, lightness,
-    alpha)`].
+  * Set [`internal`] to the result of [`rgb(red green blue / alpha)`].
 
-  [`hsl(hue, saturation, lightness, alpha)`]: ../../functions.md#hsl-and-hsla
+  * Return `this`.
 
-* Otherwise, if `options.whiteness` is set:
-
-  * Let `hue` be a Sass number with a value of `options.hue`.
-
-  * Let `whiteness` be a Sass number with a value of `options.whiteness`.
-
-  * Let `blackness` be a Sass number with a value of `options.blackness`.
-
-  * If `options.alpha` is set, let `alpha` be a Sass number with a value of
-    `options.alpha`. Otherwise, let `alpha` be `null`.
-
-  * Set [`internal`] to the result of [`hwb(hue, whiteness, blackness, alpha)`].
-
-  [`hwb(hue, whiteness, blackness, alpha)`]: ../../built-in-modules/color.md#hwb
-
-* Return `this`.
+[parsing a channel value]: #parsing-a-channel-value
+[parsing a clamped channel value]: #parsing-a-clamped-channel-value
+[`internal`]: #internal
+[`rgb(red green blue / alpha)`]: ../../functions.md#rgb-and-rgba
 
 ```ts
 constructor(options: {
-  red: number;
-  green: number;
-  blue: number;
-  alpha?: number;
+  red: number | null;
+  green: number | null;
+  blue: number | null;
+  alpha?: number | null;
+  space?: 'rgb';
 });
+```
 
-constructor(options: {
-  hue: number;
-  saturation: number;
-  lightness: number;
-  alpha?: number;
-});
+##### HSL
 
+* Otherwise, if `constructionSpace` is "hsl":
+
+  * If `options.alpha` is `null` and `options.space` is not set, emit a
+    deprecation warning named `null-alpha`.
+
+  * Let `hue` be the result of [parsing a channel value] with value
+    `options.hue`.
+
+  * Let `saturation` be the result of [parsing a channel value] with value
+    `options.saturation`.
+
+  * Let `lightness` be the result of [parsing a clamped channel value] with
+    `value` of `options.lightness`, `minimum` of `0`, and `maximum` of `100`.
+
+  * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
+    the result of [parsing a clamped channel value] with `value` of
+    `options.alpha`, `minimum` of `0`, and `maximum` of `1`.
+
+  * Set [`internal`] to the result of [`hsl(hue saturation lightness / alpha)`].
+
+  * Return `this`.
+
+[`hsl(hue saturation lightness / alpha)`]: ../../functions.md#hsl-and-hsla
+
+```ts
 constructor(options: {
-  hue: number;
-  whiteness: number;
-  blackness: number;
-  alpha?: number;
+  hue: number | null;
+  saturation: number | null;
+  lightness: number | null;
+  alpha?: number | null;
+  space?: ColorSpaceHsl;
 });
 ```
 
+##### HWB
+
+* Otherwise, if `constructionSpace` is "hwb":
+
+  * If `options.alpha` is `null` and `options.space` is not set, emit a
+    deprecation warning named `null-alpha`.
+
+  * Let `hue` be the result of [parsing a channel value] with value
+    `options.hue`.
+
+  * Let `whiteness` be the result of [parsing a channel value] with value
+    `options.whiteness`.
+
+  * Let `blackness` be the result of [parsing a channel value] with value
+    `options.blackness`.
+
+  * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
+    the result of [parsing a clamped channel value] with `value` of
+    `options.alpha`, `minimum` of `0`, and `maximum` of `1`.
+
+  * Set [`internal`] to the result of [`hwb(hue whiteness blackness / alpha)`].
+
+  * Return `this`.
+
+[`hwb(hue whiteness blackness / alpha)`]: ../../../proposal/color-4-new-spaces.md#hwb-1
+
+```ts
+constructor(options: {
+  hue: number | null;
+  whiteness: number | null;
+  blackness: number | null;
+  alpha?: number | null;
+  space?: ColorSpaceHwb;
+});
+```
+
+##### Lab
+
+* Otherwise, if `constructionSpace` is "lab" or "oklab":
+
+  * If `options.space` equals `lab`, let `maximum` be `100`. Otherwise, let
+    `maximum` be `1`.
+
+  * Let `lightness` be the result of [parsing a clamped channel value] with
+    `value` of `options.lightness`, `minimum` of `0`, and `maximum` of
+    `maximum`.
+
+  * Let `a` be the result of [parsing a channel value] with value `options.a`.
+
+  * Let `b` be the result of [parsing a channel value] with value `options.b`.
+
+  * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
+    the result of [parsing a clamped channel value] with value `options.alpha`,
+    `minimum` of 0, and `maximum` of 1.
+
+  * If `options.space` equals `lab`, set [`internal`] to the result of
+    [`lab(lightness a b / alpha)`].
+
+  * Otherwise, if `options.space` equals `oklab`, set [`internal`] to the
+    result of [`oklab(lightness a b / alpha)`].
+
+  * Return `this`.
+
+[`lab(lightness a b / alpha)`]: ../../../proposal/color-4-new-spaces.md#lab
+[`oklab(lightness a b / alpha)`]: ../../../proposal/color-4-new-spaces.md#oklab
+
+```ts
+constructor(options: {
+  lightness: number | null;
+  a: number | null;
+  b: number | null;
+  alpha?: number | null;
+  space: ColorSpaceLab;
+});
+```
+
+##### LCH
+
+* Otherwise, if `constructionSpace` is "lch" or "oklch":
+
+  * If `options.space` equals `lch`, let `maximum` be `100`. Otherwise, let
+    `maximum` be `1`.
+
+  * Let `lightness` be the result of [parsing a clamped channel value] with
+    `value` of `options.lightness`, `minimum` of `0`, and `maximum` of
+    `maximum`.
+
+  * Let `c` be the result of [parsing a channel value] with value `options.c`.
+
+  * Let `h` be the result of [parsing a channel value] with value `options.h`.
+
+  * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
+    the result of [parsing a clamped channel value] with value `options.alpha`,
+    `minimum` of 0, and `maximum` of 1.
+
+  * If `options.space` equals `lch`, set [`internal`] to the result of
+    [`lch(lightness a b / alpha)`].
+
+  * Otherwise, if `options.space` equals `oklch`, set [`internal`] to the
+    result of [`oklch(lightness a b / alpha)`].
+
+  * Return `this`.
+
+[`lch(lightness a b / alpha)`]: ../../../proposal/color-4-new-spaces.md#lch
+[`oklch(lightness a b / alpha)`]: ../../../proposal/color-4-new-spaces.md#oklch
+
+```ts
+constructor(options: {
+  lightness: number | null;
+  chroma: number | null;
+  hue: number | null;
+  alpha?: number | null;
+  space: ColorSpaceLch;
+});
+```
+
+##### Predefined RGB
+
+* Otherwise, if `constructionSpace` is "srgb", "srgb-linear", "display-p3",
+  "a98-rgb", "prophoto-rgb", or "rec2020":
+
+  * Let `red` be the result of [parsing a channel value] with value
+    `options.red`.
+
+  * Let `green` be the result of [parsing a channel value] with value
+    `options.green`.
+
+  * Let `blue` be the result of [parsing a channel value] with value
+    `options.blue`.
+
+  * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
+    the result of [parsing a clamped channel value] with value `options.alpha`,
+    `minimum` of 0, and `maximum` of 1.
+
+  * Let `space` be the unquoted string value of `options.space`.
+
+  * Set [`internal`] to the result of [`color(space red green blue / alpha)`].
+
+  * Return `this`.
+
+[`color(space red green blue / alpha)`]: ../../../proposal/color-4-new-spaces.md#color-1
+
+```ts
+constructor(options: {
+  red: number | null;
+  green: number | null;
+  blue: number | null;
+  alpha?: number | null;
+  space: Exclude<ColorSpaceRgb, 'rgb'>;
+});
+```
+
+##### XYZ
+
+* Otherwise, if `constructionSpace` is "xyz", "xyz-d50", or "xyz-d65":
+
+  * Let `x` be the result of [parsing a channel value] with value `options.x`.
+
+  * Let `y` be the result of [parsing a channel value] with value `options.y`.
+
+  * Let `z` be the result of [parsing a channel value] with value `options.z`.
+
+  * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
+    the result of [parsing a clamped channel value] with value `options.alpha`,
+    `minimum` of 0, and `maximum` of 1.
+
+  * Let `space` be the unquoted string value of `options.space`.
+
+  * Set [`internal`] to the result of [`color(space x y z / alpha)`].
+
+  * Return `this`.
+
+[`color(space x y z / alpha)`]: ../../../proposal/color-4-new-spaces.md#color-1
+
+```ts
+constructor(options: {
+  x: number | null;
+  y: number | null;
+  z: number | null;
+  alpha?: number | null;
+  space: ColorSpaceXyz;
+});
+```
+
+#### `space`
+
+Returns the name of [`internal`]'s space.
+
+```ts
+get space(): KnownColorSpace;
+```
+
+#### `toSpace`
+
+* If `this.space` is equal to `space`, return `this`.
+
+* Otherwise, return the result of [Converting a Color] with `this` as
+  `origin-color` and `space` as `target-space`.
+
+```ts
+toSpace(space: KnownColorSpace): SassColor;
+```
+
+[Converting a Color]: ../../../proposal/color-4-new-spaces.md#converting-a-color
+
+#### `isLegacy`
+
+Returns whether [`internal`] is in a [legacy color space] (`rgb`, `hsl`, or
+`hwb`).
+
+```ts
+get isLegacy(): boolean;
+```
+
+[legacy color space]: ../../../proposal/color-4-new-spaces.md#legacy-color
+
+#### `isInGamut`
+
+Returns the result of [`color.is-in-gamut(internal, space)`] as a JavaScript
+boolean.
+
+```ts
+isInGamut(space?: KnownColorSpace): boolean;
+```
+
+[`color.is-in-gamut(internal, space)`]: ../../../proposal/color-4-new-spaces.md#coloris-in-gamut
+
+#### `toGamut`
+
+Returns the result of [`color.to-gamut(internal, space)`].
+
+```ts
+toGamut(space?: KnownColorSpace): SassColor;
+```
+
+[`color.to-gamut(internal, space)`]: ../../../proposal/color-4-new-spaces.md#colorto-gamut-1
+
+#### `channelsOrNull`
+
+Returns a list of channel values (excluding alpha) for [`internal`], with
+[missing channels][missing components] converted to `null`.
+
+* Let `space` be the value of [`this.space`].
+
+* Let `components` be the list of channels in `space`.
+
+* Let `channels` be an empty list.
+
+* For each `component` in `components`:
+
+  * Let `value` be the channel value in [`internal`] with name of `component`.
+
+  * If `value` is `none`, let `value` be `null`.
+
+  * Append `value` to `channels`.
+
+* Return `channels`.
+
+```ts
+get channelsOrNull(): List<number | null>;
+```
+
+[missing components]: ../../../proposal/color-4-new-spaces.md#missing-components
+[`this.space`]: #space
+
+#### `channels`
+
+This algorithm returns a list of channel values (excluding alpha) for
+[`internal`], with [missing channels][missing components] converted to `0`.
+
+* Let `channelsOrNull` be the result of [`this.channelsOrNull`].
+
+* Let `channels` be an empty list.
+
+* For each `channel` in `channelsOrNull`:
+
+  * If `channel` equals `null`, let `value` be 0.
+
+  * Append `value` to `channels`.
+
+* Return `channels`.
+
+[`this.channelsOrNull`]: #channelsornull
+
+```ts
+get channels(): List<number>;
+```
+
+#### `channel`
+
+* Let `initialSpace` be the value of [`this.space`].
+
+* Let `space` be `options.space` if it is defined, and the value of
+  `initialSpace` otherwise.
+
+* If `channel` is not "alpha" or a channel in `space`, throw an error.
+
+* Let `color` be the result of [`this.toSpace(space)`].
+
+* Let `value` be the channel value in `color` with name of `component`.
+
+* If `value` is `null`, return 0.
+
+* Otherwise, return `value`.
+
+[`this.toSpace(space)`]: #tospace
+
+```ts
+channel(channel: ChannelName): number;
+channel(channel: ChannelNameHsl, options: {space: ColorSpaceHsl}): number;
+channel(channel: ChannelNameHwb, options: {space: ColorSpaceHwb}): number;
+channel(channel: ChannelNameLab, options: {space: ColorSpaceLab}): number;
+channel(channel: ChannelNameLch, options: {space: ColorSpaceLch}): number;
+channel(channel: ChannelNameRgb, options: {space: ColorSpaceRgb}): number;
+channel(channel: ChannelNameXyz, options: {space: ColorSpaceXyz}): number;
+```
+
+#### `alpha`
+
+Returns the result of calling [`this.channel('alpha')`].
+
+[`this.channel('alpha')`]: #channel
+
+```ts
+get alpha(): number;
+```
+
+#### `isChannelMissing`
+
+Returns the result of [`color.is-missing(internal,
+channel)`][color.is-missing()] as a JavaScript boolean.
+
+```ts
+isChannelMissing(channel: ChannelName): boolean;
+```
+
+[color.is-missing()]: ../../../proposal/color-4-new-spaces.md#coloris-missing-1
+
+#### `isChannelPowerless`
+
+Returns the result of [`color.is-powerless(internal, channel, space)`] as a
+JavaScript boolean.
+
+[`color.is-powerless(internal, channel, space)`]: ../../../proposal/color-4-new-spaces.md#coloris-powerless-1
+
+```ts
+isChannelPowerless(channel: ChannelName): boolean;
+isChannelPowerless(
+  channel: ChannelNameHsl,
+  options?: {space: ColorSpaceHsl}
+): boolean;
+isChannelPowerless(
+  channel: ChannelNameHwb,
+  options?: {space: ColorSpaceHwb}
+): boolean;
+isChannelPowerless(
+  channel: ChannelNameLab,
+  options?: {space: ColorSpaceLab}
+): boolean;
+isChannelPowerless(
+  channel: ChannelNameLch,
+  options?: {space: ColorSpaceLch}
+): boolean;
+isChannelPowerless(
+  channel: ChannelNameRgb,
+  options?: {space: ColorSpaceRgb}
+): boolean;
+isChannelPowerless(
+  channel: ChannelNameXyz,
+  options?: {space: ColorSpaceXyz}
+): boolean;
+```
+
+#### `interpolate`
+
+* Let `space` be the value of [`this.space`].
+
+* If `options.method` is set, let `interpolationMethod` be a space separated
+  list containing the value of `space`, a space, and the value of
+  `options.method`.
+
+* Otherwise, if `space` is a rectangular color space, let `interpolationMethod`
+  be `space`.
+
+* Otherwise, let `interpolationMethod` be a space separated list containing the
+  value of `space`, a space, and the string "shorter".
+
+* Return the result of [`color.mix(internal, color2, options.weight, interpolationMethod)`][`color.mix()`].
+
+```ts
+interpolate(
+  color2: SassColor,
+  options?: {
+    weight?: number;
+    method?: HueInterpolationMethod;
+  }
+): SassColor;
+```
+
+[`color.mix()`]: ../../../proposal/color-4-new-spaces.md#colormix-1
+
+#### `change`
+
+This algorithm takes a JavaScript object `options` and returns a new SassColor
+as the result of changing some of [`internal`]'s components.
+
+> The `space` value defaults to the `space` of [`internal`], and the caller may
+> specify any combination of channels and alpha in that space to be changed.
+>
+> If `space` is not a [legacy color space], a channel value of `null` will
+> result in a [missing component][missing components] value for that channel.
+
+* Let `initialSpace` be the value of [`this.space`].
+
+* Let `spaceSetExplicitly` be `true` if `options.space` is defined, and `false`
+  otherwise.
+
+* Let `space` be `options.space` if `spaceSetExplicitly` is true, and the value
+  of `initialSpace` otherwise.
+
+* If `initialSpace` is a [legacy color space] and `spaceSetExplicitly` is false:
+
+  * If `options.whiteness` or `options.blackness` is set, let `space` be `hwb`.
+
+  * Otherwise, if `options.hue` is set and `initialSpace` is `hwb`, let space be
+    `hwb`.
+
+  * Otherwise, if `options.hue`, `options.saturation`, or `options.lightness` is
+    set, let `space` be `hsl`.
+
+  * Otherwise, if `options.red`, `options.green`, or `options.blue` is set, let
+    `space` be `rgb`.
+
+  * If `initialSpace` is not equal to `space`, emit a deprecation warning named
+    `color-4-api`.
+
+* Let `changes` be the object `options` without `space` and its value.
+
+* Let `keys` be a list of the keys in `changes`.
+
+* Let `components` be `"alpha"` and the names of the channels in `space`.
+
+* If any key in `keys` is not the name of a channel in `components`, throw an
+  error.
+
+* If `options.alpha` is set, and isn't either null or a number between 0 and 1
+  (inclusive and fuzzy), throw an error.
+
+* If `options.lightness` is set, and isn't either null or a number between 0 and
+  the maximum channel value for the space (inclusive and fuzzy), throw an error.
+
+* Let `color` be the result of [`this.toSpace(space)`].
+
+* Let `changedValue` be a function that takes a string argument for `channel`
+  and calls the procedure [`Changing a Component Value`] with `changes` and
+  `color` as `initial`.
+
+* If `space` equals `hsl` and `spaceSetExplicitly` is `false`:
+
+  * If any of `options.hue`, `options.saturation` or `options.lightness` equals
+    `null`, emit a deprecation warning named `color-4-api`.
+
+  * If `options.alpha` equals `null`, emit a deprecation warning named
+    `null-alpha`.
+
+  * Let `changedColor` be the result of:
+
+    ```js
+    new SassColor({
+      hue: options.hue ?? color.channel('hue'),
+      saturation: options.saturation ?? color.channel('saturation'),
+      lightness: options.lightness ?? color.channel('lightness'),
+      alpha: options.alpha ?? color.channel('alpha'),
+      space: space
+    })
+    ```
+
+* If `space` equals `hsl` and `spaceSetExplicitly` is `true`, let `changedColor`
+  be the result of:
+
+   ```js
+  new SassColor({
+    hue: changedValue('hue'),
+    saturation: changedValue('saturation'),
+    lightness: changedValue('lightness'),
+    alpha: changedValue('alpha'),
+    space: space
+  })
+  ```
+
+* If `space` equals `hwb` and `spaceSetExplicitly` is `false`:
+
+  * If any of `options.hue`, `options.whiteness` or `options.blackness` equals
+    `null`, emit a deprecation warning named `color-4-api`.
+
+  * If `options.alpha` equals `null`, emit a deprecation warning named
+    `null-alpha`.
+
+  * Let `changedColor` be the result of:
+
+    ```js
+    new SassColor({
+      hue: options.hue ?? color.channel('hue'),
+      whiteness: options.whiteness ?? color.channel('whiteness'),
+      blackness: options.blackness ?? color.channel('blackness'),
+      alpha: options.alpha ?? color.channel('alpha'),
+      space: space
+    })
+    ```
+
+* If `space` equals `hwb` and `spaceSetExplicitly` is `true`, let `changedColor`
+  be the result of:
+
+   ```js
+  new SassColor({
+    hue: changedValue('hue'),
+    whiteness: changedValue('whiteness'),
+    blackness: changedValue('blackness'),
+    alpha: changedValue('alpha'),
+    space: space
+  })
+  ```
+
+* If `space` equals `rgb` and `spaceSetExplicitly` is `false`:
+
+  * If any of `options.red`, `options.green` or `options.blue` equals `null`,
+    emit a deprecation warning named `color-4-api`.
+
+  * If `options.alpha` equals `null`, emit a deprecation warning named
+    `null-alpha`.
+
+  * Let `changedColor` be the result of:
+
+    ```js
+    new SassColor({
+      red: options.red ?? color.channel('red'),
+      green: options.green ?? color.channel('green'),
+      blue: options.blue ?? color.channel('blue'),
+      alpha: options.alpha ?? color.channel('alpha'),
+      space: space
+    })
+    ```
+
+* If `space` equals `rgb` and `spaceSetExplicitly` is `true`, let `changedColor`
+  be the result of:
+
+   ```js
+  new SassColor({
+    red: changedValue('red'),
+    green: changedValue('green'),
+    blue: changedValue('blue'),
+    alpha: changedValue('alpha'),
+    space: space
+  })
+  ```
+
+* If `space` equals `lab` or `oklab`, let `changedColor` be the result of:
+
+  ```js
+  new SassColor({
+    lightness: changedValue('lightness'),
+    a: changedValue('a'),
+    b: changedValue('b'),
+    alpha: changedValue('alpha'),
+    space: space
+  })
+  ```
+
+* If `space` equals `lch` or `oklch`, let `changedColor` be the result of:
+
+  ```js
+  new SassColor({
+    lightness: changedValue('lightness'),
+    chroma: changedValue('chroma'),
+    hue: changedValue('hue'),
+    alpha: changedValue('alpha'),
+    space: space
+  })
+  ```
+
+* If `space` equals `a98-rgb`, `display-p3`, `prophoto-rgb`, `rec2020`, `srgb`,
+  or `srgb-linear`, let `changedColor` be the result of:
+
+  ```js
+  new SassColor({
+    red: changedValue('red'),
+    green: changedValue('green'),
+    blue: changedValue('blue'),
+    alpha: changedValue('alpha'),
+    space: space
+  })
+  ```
+
+* If `space` equals `xyz`, `xyz-d50`, or `xyz-d65`, let `changedColor` be the
+  result of:
+
+  ```js
+  new SassColor({
+    y: changedValue('y'),
+    x: changedValue('x'),
+    z: changedValue('z'),
+    alpha: changedValue('alpha'),
+    space: space
+  })
+  ```
+
+* Return the result of [`changedColor.toSpace(initialSpace)`].
+
+[`changedColor.toSpace(initialSpace)`]: #tospace
+[`Changing a Component Value`]: #changing-a-component-value
+
+```ts
+change(
+  options: {
+    [key in ChannelNameHsl]?: number | null;
+  } & {
+    space?: ColorSpaceHsl;
+  }
+): SassColor;
+
+change(
+  options: {
+    [key in ChannelNameHwb]?: number | null;
+  } & {
+    space?: ColorSpaceHwb;
+  }
+): SassColor;
+
+change(
+  options: {
+    [key in ChannelNameLab]?: number | null;
+  } & {
+    space?: ColorSpaceLab;
+  }
+): SassColor;
+
+change(
+  options: {
+    [key in ChannelNameLch]?: number | null;
+  } & {
+    space?: ColorSpaceLch;
+  }
+): SassColor;
+
+change(
+  options: {
+    [key in ChannelNameRgb]?: number | null;
+  } & {
+    space?: ColorSpaceRgb;
+  }
+): SassColor;
+
+change(
+  options: {
+    [key in ChannelNameXyz]?: number | null;
+  } & {
+    space?: ColorSpaceXyz;
+  }
+): SassColor;
+```
+
 #### `red`
 
-Returns [`internal`]'s red channel.
+> This is deprecated in favor of the new [`channel`] function. This deprecation
+> is called `color-4-api`.
+
+[`channel`]: #channel
+
+Returns [`internal`]'s red channel in the RGB color space.
 
 ```ts
 get red(): number;
@@ -124,7 +1001,10 @@ get red(): number;
 
 #### `green`
 
-Returns [`internal`]'s green channel.
+> This is deprecated in favor of the new [`channel`] function. This deprecation
+> is called `color-4-api`.
+
+Returns [`internal`]'s green channel in the RGB color space.
 
 ```ts
 get green(): number;
@@ -132,7 +1012,10 @@ get green(): number;
 
 #### `blue`
 
-Returns [`internal`]'s blue channel.
+> This is deprecated in favor of the new [`channel`] function. This deprecation
+> is called `color-4-api`.
+
+Returns [`internal`]'s blue channel in the RGB color space.
 
 ```ts
 get blue(): number;
@@ -140,6 +1023,9 @@ get blue(): number;
 
 #### `hue`
 
+> This is deprecated in favor of the new [`channel`] function. This deprecation
+> is called `color-4-api`.
+
 Returns the value of the result of [`hue(internal)`].
 
 [`hue(internal)`]: ../../built-in-modules/color.md#hue
@@ -150,6 +1036,9 @@ get hue(): number;
 
 #### `saturation`
 
+> This is deprecated in favor of the new [`channel`] function. This deprecation
+> is called `color-4-api`.
+
 Returns the value of the result of [`saturation(internal)`].
 
 [`saturation(internal)`]: ../../built-in-modules/color.md#saturation
@@ -160,6 +1049,9 @@ get saturation(): number;
 
 #### `lightness`
 
+> This is deprecated in favor of the new [`channel`] function. This deprecation
+> is called `color-4-api`.
+
 Returns the value of the result of [`lightness(internal)`].
 
 [`lightness(internal)`]: ../../built-in-modules/color.md#lightness
@@ -170,6 +1062,9 @@ get lightness(): number;
 
 #### `whiteness`
 
+> This is deprecated in favor of the new [`channel`] function. This deprecation
+> is called `color-4-api`.
+
 Returns the value of the result of [`whiteness(internal)`].
 
 [`whiteness(internal)`]: ../../built-in-modules/color.md#whiteness
@@ -180,6 +1075,9 @@ get whiteness(): number;
 
 #### `blackness`
 
+> This is deprecated in favor of the new [`channel`] function. This deprecation
+> is called `color-4-api`.
+
 Returns the value of the result of [`blackness(internal)`].
 
 [`blackness(internal)`]: ../../built-in-modules/color.md#blackness
@@ -188,77 +1086,46 @@ Returns the value of the result of [`blackness(internal)`].
 get blackness(): number;
 ```
 
-#### `alpha`
-
-Returns the value of the result of [`alpha(internal)`].
-
-[`alpha(internal)`]: ../../built-in-modules/color.md#alpha
-
-```ts
-get alpha(): number;
-```
-
-#### `change`
-
-Returns a new color created by changing some of this color's channels:
-
-* If `options.whiteness` or `options.blackness` is set, return the result of:
-
-  ```js
-  SassColor({
-    hue: options.hue ?? this.hue,
-    whiteness: options.whiteness ?? this.whiteness,
-    blackness: options.blackness ?? this.blackness,
-    alpha: options.alpha ?? this.alpha
-  })
-  ```
-
-* Otherwise, if `options.hue`, `options.saturation`, or `options.lightness`
-  is set, return the result of:
-
-  ```js
-  SassColor({
-    hue: options.hue ?? this.hue,
-    saturation: options.saturation ?? this.saturation,
-    lightness: options.lightness ?? this.lightness,
-    alpha: options.alpha ?? this.alpha
-  })
-  ```
-
-* Otherwise, return the result of:
-
-  ```js
-  SassColor({
-    red: options.red ?? this.red,
-    green: options.green ?? this.gren,
-    blue: options.blue ?? this.blue,
-    alpha: options.alpha ?? this.alpha
-  })
-  ```
-
-```ts
-change(options: {
-  red?: number;
-  green?: number;
-  blue?: number;
-  alpha?: number;
-}): SassColor;
-
-change(options: {
-  hue?: number;
-  saturation?: number;
-  lightness?: number;
-  alpha?: number;
-}): SassColor;
-
-change(options: {
-  hue?: number;
-  whiteness?: number;
-  blackness?: number;
-  alpha?: number;
-}): SassColor;
-```
-
 ```ts
 } // SassColor
 ```
+
+## Procedures
+
+### Parsing a Channel Value
+
+This procedure takes a channel value `value`, and returns the special value
+`none` if the value is `null`.
+
+* If `value` is a number, return a Sass number with a value of `value`.
+
+* If `value` is the Javascript value `null`, return the unquoted Sass string
+  `none`.
+
+### Parsing a Clamped Channel Value
+
+This procedure takes a channel value `value` and an inclusive range of `minimum`
+and `maximum`. It asserts the value is in the range, and returns the special
+value `none` if the value is `null`.
+
+* If `value` is fuzzy less-than `minimum`, throw an error.
+
+* If `value` is fuzzy greater-than `maximum`, throw an error.
+
+* Otherwise, return the result of [Parsing a Channel Value].
+
+### Changing a Component Value
+
+This procedure takes a `channel` name, an object `changes` and a SassColor
+`initial` and returns the result of applying the change for `channel` to
+`initial`.
+
+* Let `initialValue` be the channel value in `initial` with name of `channel`.
+
+* If `channel` is not a key in `changes`, return `initialValue`.
+
+* Let `changedValue` be the value for `channel` in `changes`.
+
+* If `changedValue` is `undefined` and not `null`, return `initialValue`.
+
+* Otherwise, return `changedValue`.
diff --git a/spec/js-api/value/index.d.ts.md b/spec/js-api/value/index.d.ts.md
index 654f2f4c..a1079c20 100644
--- a/spec/js-api/value/index.d.ts.md
+++ b/spec/js-api/value/index.d.ts.md
@@ -22,7 +22,26 @@ export {
   CalculationOperation,
   CalculationInterpolation,
 } from './calculation';
-export {SassColor} from './color';
+export {
+  SassColor,
+  ColorSpaceHsl,
+  ChannelNameHsl,
+  ColorSpaceHwb,
+  ChannelNameHwb,
+  ColorSpaceLab,
+  ChannelNameLab,
+  ColorSpaceLch,
+  ChannelNameLch,
+  ColorSpaceRgb,
+  ChannelNameRgb,
+  ColorSpaceXyz,
+  ChannelNameXyz,
+  ChannelName,
+  KnownColorSpace,
+  PolarColorSpace,
+  RectangularColorSpace,
+  HueInterpolationMethod,
+} from './color';
 export {SassFunction} from './function';
 export {SassList, ListSeparator} from './list';
 export {SassMap} from './map';

From b4351f58af345fbe0e67c1037a27897985744217 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Thu, 28 Mar 2024 15:49:00 -0700
Subject: [PATCH 33/51] [Color 4] Update the powerless definition for HWB

---
 proposal/color-4-new-spaces.changes.md | 4 ++++
 proposal/color-4-new-spaces.md         | 6 +++---
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/proposal/color-4-new-spaces.changes.md b/proposal/color-4-new-spaces.changes.md
index 56aaec82..478375dc 100644
--- a/proposal/color-4-new-spaces.changes.md
+++ b/proposal/color-4-new-spaces.changes.md
@@ -1,3 +1,7 @@
+## Draft 1.14
+
+* Update the definition of powerless for HWB to match the latest CSS spec.
+
 ## Draft 1.13
 
 * Remove definitions of powerless channels that are no longer present in CSS
diff --git a/proposal/color-4-new-spaces.md b/proposal/color-4-new-spaces.md
index 22612ee6..39df6535 100644
--- a/proposal/color-4-new-spaces.md
+++ b/proposal/color-4-new-spaces.md
@@ -1,4 +1,4 @@
-# CSS Color Level 4, New Color Spaces: Draft 1.13
+# CSS Color Level 4, New Color Spaces: Draft 1.14
 
 *([Issue](https://github.com/sass/sass/issues/2831))*
 
@@ -799,8 +799,8 @@ in certain circumstances.
 
 * `hwb`:
 
-  * If the combined `whiteness` and `blackness` values (after normalization)
-    are equal to `100%`, then the `hue` channel is powerless.
+  * If `whiteness + blackness` is greater than or equal to `100%`, then the
+    `hue` channel is powerless.
 
 * `lch`/`oklch`:
 

From 4a8a9e77f5044df621725be450c441f7948b6766 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Fri, 29 Mar 2024 14:05:30 -0700
Subject: [PATCH 34/51] [Color 4 JS] Don't throw errors for out-of-gamut
 lightness

---
 js-api-doc/value/color.d.ts               | 30 ++++++-----------------
 proposal/color-4-new-spaces-js.changes.md |  4 +++
 proposal/color-4-new-spaces-js.d.ts.md    | 17 ++++++-------
 spec/js-api/value/color.d.ts.md           | 17 +++++--------
 4 files changed, 25 insertions(+), 43 deletions(-)

diff --git a/js-api-doc/value/color.d.ts b/js-api-doc/value/color.d.ts
index 4ba8909f..2ec9763e 100644
--- a/js-api-doc/value/color.d.ts
+++ b/js-api-doc/value/color.d.ts
@@ -129,8 +129,6 @@ export class SassColor extends Value {
    *
    * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
    * and `1`.
-   * @throws `Error` if `lightness` isn't `null` or a number between between `0`
-   * and `100`.
    */
   constructor(options: {
     hue: number | null;
@@ -177,8 +175,6 @@ export class SassColor extends Value {
    *
    * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
    * and `1`.
-   * @throws `Error` if `lightness` isn't `null` or a number between `0` and the
-   * maximum channel value for `space`—`100` for Lab or `1` for Oklab.
    */
   constructor(options: {
     lightness: number | null;
@@ -200,8 +196,6 @@ export class SassColor extends Value {
    *
    * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
    * and `1`.
-   * @throws `Error` if `lightness` isn't `null` or a number between `0` and the
-   * maximum channel value for `space`—`100` for LCH or `1` for Oklch.
    */
   constructor(options: {
     lightness: number | null;
@@ -402,8 +396,6 @@ export class SassColor extends Value {
    * color space (`rgb`, `hsl`, or `hwb`).
    * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
    * and `1`.
-   * @throws `Error` if `lightness` is set and isn't `null` or a number between
-   * `0` and `100`.
    */
   change(
     options: {
@@ -438,9 +430,6 @@ export class SassColor extends Value {
    * Oklab color spaces.
    * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
    * and `1`.
-   * @throws `Error` if `lightness` is set and isn't `null` or a number between
-   * `0` and the maximum channel value for `space` (or this color's color space,
-   * if `space` is missing)—`100` for Lab or `1` for Oklab.
    */
   change(
     options: {
@@ -458,9 +447,6 @@ export class SassColor extends Value {
    * Oklch color spaces.
    * @throws `Error` if `alpha` is set and isn't `null` or a number between `0`
    * and `1`.
-   * @throws `Error` if `lightness` is set and isn't `null` or a number between
-   * `0` and the maximum channel value for `space` (or this color's color space,
-   * if `space` is missing)—`100` for LCH or `1` for Oklch.
    */
   change(
     options: {
@@ -505,56 +491,56 @@ export class SassColor extends Value {
   ): SassColor;
 
   /**
-   * This color's red channel in the RGB color space, between `0` and `255`.
+   * This color's red channel in the RGB color space.
    *
    * @deprecated Use {@link channel} instead.
    */
   get red(): number;
 
   /**
-   * This color's green channel in the RGB color space, between `0` and `255`.
+   * This color's green channel in the RGB color space.
    *
    * @deprecated Use {@link channel} instead.
    */
   get green(): number;
 
   /**
-   * This color's blue channel in the RGB color space, between `0` and `255`.
+   * This color's blue channel in the RGB color space.
    *
    * @deprecated Use {@link channel} instead.
    */
   get blue(): number;
 
   /**
-   * This color's hue in the HSL color space, between `0` and `360`.
+   * This color's hue in the HSL color space.
    *
    * @deprecated Use {@link channel} instead.
    */
   get hue(): number;
 
   /**
-   * This color's saturation in the HSL color space, between `0` and `100`.
+   * This color's saturation in the HSL color space.
    *
    * @deprecated Use {@link channel} instead.
    */
   get saturation(): number;
 
   /**
-   * This color's lightness in the HSL color space, between `0` and `100`.
+   * This color's lightness in the HSL color space.
    *
    * @deprecated Use {@link channel} instead.
    */
   get lightness(): number;
 
   /**
-   * This color's whiteness in the HWB color space, between `0` and `100`.
+   * This color's whiteness in the HWB color space.
    *
    * @deprecated Use {@link channel} instead.
    */
   get whiteness(): number;
 
   /**
-   * This color's blackness in the HWB color space, between `0` and `100`.
+   * This color's blackness in the HWB color space.
    *
    * @deprecated Use {@link channel} instead.
    */
diff --git a/proposal/color-4-new-spaces-js.changes.md b/proposal/color-4-new-spaces-js.changes.md
index f688665b..9945d0e4 100644
--- a/proposal/color-4-new-spaces-js.changes.md
+++ b/proposal/color-4-new-spaces-js.changes.md
@@ -1,3 +1,7 @@
+## Draft 1.7
+
+* Don't throw errors for out-of-gamut lightness values.
+
 ## Draft 1.6
 
 * Simplify the type definition for `interpolate`, and make `options` argument
diff --git a/proposal/color-4-new-spaces-js.d.ts.md b/proposal/color-4-new-spaces-js.d.ts.md
index 4e4be355..8520ed80 100644
--- a/proposal/color-4-new-spaces-js.d.ts.md
+++ b/proposal/color-4-new-spaces-js.d.ts.md
@@ -1,4 +1,4 @@
-# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.6
+# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.7
 
 *([Issue](https://github.com/sass/sass/issues/2831),
 [Changelog](color-4-new-spaces-js.changes.md))*
@@ -394,9 +394,6 @@ as the result of changing some of [`internal`]'s components.
 * If `options.alpha` is set, and isn't either null or a number between 0 and 1
   (inclusive and fuzzy), throw an error.
 
-* If `options.lightness` is set, and isn't either null or a number between 0 and
-  the maximum channel value for the space (inclusive and fuzzy), throw an error.
-
 * Let `color` be the result of [`this.toSpace(space)`].
 
 * Let `changedValue` be a function that takes a string argument for `channel`
@@ -624,8 +621,8 @@ Create a new SassColor in a color space with Lab channels—`lab` and `oklab`.
 * If `options.space` equals `lab`, let `maximum` be `100`. Otherwise, let
   `maximum` be `1`.
 
-* Let `lightness` be the result of [parsing a clamped channel value] with
-  `value` of `options.lightness`, `minimum` of `0`, and `maximum` of `maximum`.
+* Let `lightness` be the result of [parsing a channel value] with `value` of
+  `options.lightness`, `minimum` of `0`, and `maximum` of `maximum`.
 
 * Let `a` be the result of [parsing a channel value] with value `options.a`.
 
@@ -663,8 +660,8 @@ Create a new SassColor in a color space with LCH channels—`lch` and `oklch`.
 * If `options.space` equals `lch`, let `maximum` be `100`. Otherwise, let
   `maximum` be `1`.
 
-* Let `lightness` be the result of [parsing a clamped channel value] with
-  `value` of `options.lightness`, `minimum` of `0`, and `maximum` of `maximum`.
+* Let `lightness` be the result of [parsing a channel value] with `value` of
+  `options.lightness`, `minimum` of `0`, and `maximum` of `maximum`.
 
 * Let `c` be the result of [parsing a channel value] with value `options.c`.
 
@@ -777,8 +774,8 @@ Create a new SassColor in the `hsl` color space.
 * Let `saturation` be the result of [parsing a channel value] with value
   `options.saturation`.
 
-* Let `lightness` be the result of [parsing a clamped channel value] with
-  `value` of `options.lightness`, `minimum` of `0`, and `maximum` of `100`.
+* Let `lightness` be the result of [parsing a channel value] with `value` of
+  `options.lightness`, `minimum` of `0`, and `maximum` of `100`.
 
 * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
   the result of [parsing a clamped channel value] with `value` of
diff --git a/spec/js-api/value/color.d.ts.md b/spec/js-api/value/color.d.ts.md
index e2f7fa4b..23f9d912 100644
--- a/spec/js-api/value/color.d.ts.md
+++ b/spec/js-api/value/color.d.ts.md
@@ -302,8 +302,8 @@ constructor(options: {
   * Let `saturation` be the result of [parsing a channel value] with value
     `options.saturation`.
 
-  * Let `lightness` be the result of [parsing a clamped channel value] with
-    `value` of `options.lightness`, `minimum` of `0`, and `maximum` of `100`.
+  * Let `lightness` be the result of [parsing a channel value] with `value` of
+    `options.lightness`, `minimum` of `0`, and `maximum` of `100`.
 
   * If `options.alpha` is not set, let `alpha` be `1`. Otherwise, let `alpha` be
     the result of [parsing a clamped channel value] with `value` of
@@ -368,9 +368,8 @@ constructor(options: {
   * If `options.space` equals `lab`, let `maximum` be `100`. Otherwise, let
     `maximum` be `1`.
 
-  * Let `lightness` be the result of [parsing a clamped channel value] with
-    `value` of `options.lightness`, `minimum` of `0`, and `maximum` of
-    `maximum`.
+  * Let `lightness` be the result of [parsing a channel value] with `value` of
+    `options.lightness`, `minimum` of `0`, and `maximum` of `maximum`.
 
   * Let `a` be the result of [parsing a channel value] with value `options.a`.
 
@@ -408,9 +407,8 @@ constructor(options: {
   * If `options.space` equals `lch`, let `maximum` be `100`. Otherwise, let
     `maximum` be `1`.
 
-  * Let `lightness` be the result of [parsing a clamped channel value] with
-    `value` of `options.lightness`, `minimum` of `0`, and `maximum` of
-    `maximum`.
+  * Let `lightness` be the result of [parsing a channel value] with `value` of
+    `options.lightness`, `minimum` of `0`, and `maximum` of `maximum`.
 
   * Let `c` be the result of [parsing a channel value] with value `options.c`.
 
@@ -773,9 +771,6 @@ as the result of changing some of [`internal`]'s components.
 * If `options.alpha` is set, and isn't either null or a number between 0 and 1
   (inclusive and fuzzy), throw an error.
 
-* If `options.lightness` is set, and isn't either null or a number between 0 and
-  the maximum channel value for the space (inclusive and fuzzy), throw an error.
-
 * Let `color` be the result of [`this.toSpace(space)`].
 
 * Let `changedValue` be a function that takes a string argument for `channel`

From 07546edf81922141b236bd3c2a8b12ca18a57ff2 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Mon, 1 Apr 2024 11:21:00 -0700
Subject: [PATCH 35/51] Link to color 4 changelog

---
 proposal/color-4-new-spaces.changes.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/proposal/color-4-new-spaces.changes.md b/proposal/color-4-new-spaces.changes.md
index 478375dc..7c15a18e 100644
--- a/proposal/color-4-new-spaces.changes.md
+++ b/proposal/color-4-new-spaces.changes.md
@@ -1,6 +1,9 @@
 ## Draft 1.14
 
-* Update the definition of powerless for HWB to match the latest CSS spec.
+* Update the definition of powerless for HWB to match [the latest CSS
+  spec][color-4-changes-20221101].
+
+[color-4-changes-20221101]: https://drafts.csswg.org/css-color-4/#changes-from-20221101
 
 ## Draft 1.13
 

From 170dbd4f8ec6a24a7504defe27804598c03b3d5e Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Thu, 11 Apr 2024 16:23:20 -0700
Subject: [PATCH 36/51] Add new deprecations

---
 js-api-doc/deprecations.d.ts     | 15 +++++++++++++++
 spec/js-api/deprecations.d.ts.md |  2 ++
 2 files changed, 17 insertions(+)

diff --git a/js-api-doc/deprecations.d.ts b/js-api-doc/deprecations.d.ts
index 5213f168..40d2a319 100644
--- a/js-api-doc/deprecations.d.ts
+++ b/js-api-doc/deprecations.d.ts
@@ -106,6 +106,21 @@ export interface Deprecations {
    */
   'fs-importer-cwd': Deprecation<'fs-importer-cwd'>;
 
+  /**
+   * Deprecation for certain uses of built-in `sass:color` functions.
+   *
+   * This deprecation became active in Dart Sass 1.76.0.
+   */
+  'color-4-api': Deprecation<'color-4-api'>;
+
+  /**
+   * Deprecation for using global color functions instead of loading them from
+   * `sass:color`.
+   *
+   * This deprecation became active in Dart Sass 1.76.0.
+   */
+  'color-functions': Deprecation<'color-functions'>;
+
   /**
    * Deprecation for `@import` rules.
    *
diff --git a/spec/js-api/deprecations.d.ts.md b/spec/js-api/deprecations.d.ts.md
index adbe3a23..6a68a9f5 100644
--- a/spec/js-api/deprecations.d.ts.md
+++ b/spec/js-api/deprecations.d.ts.md
@@ -44,6 +44,8 @@ export interface Deprecations {
   'null-alpha': Deprecation<'null-alpha'>;
   'abs-percent': Deprecation<'abs-percent'>;
   'fs-importer-cwd': Deprecation<'fs-importer-cwd'>;
+  'color-4-api': Deprecation<'color-4-api'>;
+  'color-functions': Deprecation<'color-functions'>;
   import: Deprecation<'import'>;
   'user-authored': Deprecation<'user-authored', 'user'>;
 }

From 465f0db7d1cea1a06daaa8d33115c5b746e93a1c Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Fri, 19 Apr 2024 16:18:25 -0700
Subject: [PATCH 37/51] [Color 4] Require an explicit gamut mapping method
 (#3836)

---
 accepted/color-4-new-spaces-js.changes.md |   6 ++
 accepted/color-4-new-spaces-js.d.ts.md    |  13 ++-
 accepted/color-4-new-spaces.changes.md    |   7 ++
 accepted/color-4-new-spaces.md            | 101 +++++++++++++++-------
 js-api-doc/index.d.ts                     |   1 +
 js-api-doc/value/color.d.ts               |  32 +++++--
 js-api-doc/value/index.d.ts               |   1 +
 spec/js-api/index.d.ts.md                 |   1 +
 spec/js-api/value/color.d.ts.md           |  18 +++-
 spec/js-api/value/index.d.ts.md           |   1 +
 10 files changed, 136 insertions(+), 45 deletions(-)

diff --git a/accepted/color-4-new-spaces-js.changes.md b/accepted/color-4-new-spaces-js.changes.md
index 9945d0e4..364c6efd 100644
--- a/accepted/color-4-new-spaces-js.changes.md
+++ b/accepted/color-4-new-spaces-js.changes.md
@@ -1,3 +1,9 @@
+## Draft 1.8
+
+* Change `SassColor.toGamut()` to take named parameters instead of positional.
+
+* Add a mandatory `method` parameter to `SassColor.toGamut()`.
+
 ## Draft 1.7
 
 * Don't throw errors for out-of-gamut lightness values.
diff --git a/accepted/color-4-new-spaces-js.d.ts.md b/accepted/color-4-new-spaces-js.d.ts.md
index 8520ed80..fe58ac05 100644
--- a/accepted/color-4-new-spaces-js.d.ts.md
+++ b/accepted/color-4-new-spaces-js.d.ts.md
@@ -1,4 +1,4 @@
-# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.7
+# CSS Color Level 4, New Color Spaces JavaScript API: Draft 1.8
 
 *([Issue](https://github.com/sass/sass/issues/2831),
 [Changelog](color-4-new-spaces-js.changes.md))*
@@ -116,6 +116,8 @@ export type HueInterpolationMethod =
   | 'increasing'
   | 'longer'
   | 'shorter';
+
+export type GamutMapMethod = 'clip' | 'local-minde';
 ```
 
 ### New Color Functions
@@ -171,13 +173,16 @@ isInGamut(space?: KnownColorSpace): boolean;
 
 #### `toGamut`
 
-Returns the result of [`color.to-gamut(internal, space)`].
+Returns the result of [`color.to-gamut(internal, space, method)`].
 
 ```ts
-toGamut(space?: KnownColorSpace): SassColor;
+toGamut(options: {
+  space?: KnownColorSpace;
+  method: 'clip' | 'local-minde';
+}): SassColor;
 ```
 
-[`color.to-gamut(internal, space)`]: ./color-4-new-spaces.md#colorto-gamut-1
+[`color.to-gamut(internal, space, method)`]: ./color-4-new-spaces.md#colorto-gamut-1
 
 #### `channelsOrNull`
 
diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index 7c15a18e..160f6857 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -1,3 +1,10 @@
+## Draft 1.15
+
+* Add a mandatory `$method` parameter to `color.to-gamut()` for
+  forwards-compatibility with better gamut-mapping algorithms.
+
+* Add `clip` as a gamut-mapping algorithm.
+
 ## Draft 1.14
 
 * Update the definition of powerless for HWB to match [the latest CSS
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index 39df6535..e95571a7 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -1,4 +1,4 @@
-# CSS Color Level 4, New Color Spaces: Draft 1.14
+# CSS Color Level 4, New Color Spaces: Draft 1.15
 
 *([Issue](https://github.com/sass/sass/issues/2831))*
 
@@ -54,6 +54,8 @@ colors outside the sRGB gamut.
   * [Converting a Color](#converting-a-color)
   * [CSS-Converting a Color Space](#css-converting-a-color-space)
   * [Gamut Mapping](#gamut-mapping-1)
+    * [`local-minde`](#local-minde)
+    * [`clip`](#clip)
   * [Parsing Color Components](#parsing-color-components)
   * [Percent-Converting a Number](#percent-converting-a-number)
   * [Validating a Color Channel](#validating-a-color-channel)
@@ -325,20 +327,21 @@ one or more of its channels out of bounds, like `rgb(300 0 0)`).
 
 #### `color.to-gamut()`
 
-This function returns a color that is in the given gamut, using the recommended
-[CSS Gamut Mapping Algorithm][css-mapping] to 'map' out-of-gamut colors into
-the desired gamut with as little perceptual change as possible. In many cases
-this can be more reliable for generating fallback values, rather than the
-'channel clipping' approach used by current browsers.
+This function returns a color that is in the given gamut, using the given
+mapping algorithm to convert out-of-gamut colors into the desired gamut with as
+little perceptual change as possible. The current recommended algorithm is
+`local-minde`, which is defined in the current candidate recommendation of CSS
+Color 4, which can in many cases be more reliable for generating fallback values
+than the "channel clipping" approach used by current browsers.
 
 ```scss
 $green: oklch(0.8 2 150);
 
 // oklch(0.91 0.14 164)
-$rgb: color.to-gamut($green, "srgb");
+$rgb: color.to-gamut($green, "srgb", $method: local-minde);
 
 // oklch(0.91 0.16 163)
-$p3: color.to-gamut($green, "display-p3");
+$p3: color.to-gamut($green, "display-p3", $method: local-minde);
 ```
 
 #### `color.is-powerless()`
@@ -508,14 +511,27 @@ and mapping in Sass color functions:
 
 #### Gamut Mapping
 
-Browsers currently use channel-clipping rather than the proposed
-[css gamut mapping algorithm][css-mapping] to handle colors that cannot be
-shown correctly on a given display. We've decided to provide `color.to-gamut()`
-as a way for authors to opt-into the proposed behavior, aware that browsers
-may eventually choose to provide a different algorithm. If that happens, we
-will consider adding an additional algorithm-selection argument. However, the
-primary goal of this function is not to match CSS behavior, but to provide a
-better mapping than the default channel-clipping.
+Browsers currently use channel-clipping rather than the proposed [css gamut
+mapping algorithm][css-mapping] to handle colors that cannot be shown correctly
+on a given display. Moreover, there is still active discussion among the CSS
+working group and browser vendors about what the best gamut mapping algorithm
+is, with the currently-specified algorithm widely considered to be sub-optimal.
+As such, we want to avoid baking it in as the default for Sass such that any
+change would require a deprecation period.
+
+At the same time, we expect gamut-mapping to be very useful for Sass authors
+working with wide-gamut color spaces, enough so that we want it to be available
+without needing to wait on the CSSWG to come to a consensus on the best
+algorithm. To that end, we've decided to provide `color.to-gamut()` but
+*require* a `$method` argument for forwards-compatibility with better gamut
+mapping algorithms.
+
+Initially, there will only be two available arguments for `$method`:
+`local-minde`, the gamut mapping algorithm specified in Color 4 at the time this
+spec is written, and `clip` which will just clip any channel values that are
+out-of-range for a given color space. However, we expect to expand this to
+additional algorithms in the future, and to eventually make it optional and have
+its default match the behavior of CSS.
 
 #### CSS Color 5
 
@@ -1016,28 +1032,48 @@ The individual conversion algorithms are:
 > available 'in-gamut' color. Gamut mapping is the process of finding an
 > in-gamut color with the least objectionable change in visual appearance.
 
-Gamut mapping in Sass follows the [CSS gamut mapping algorithm][css-mapping].
-This procedure accepts a color `origin`, and a [known color space]
-`destination`. It returns the result of a [CSS gamut map][css-map] procedure,
-converted back into the original color space.
+Gamut mapping color `origin`, a [known color space] `destination`, and an
+unquoted string `method`. It returns a color in `origin`'s color space.
 
 * Let `origin-space` be `origin`'s color space.
 
 * If either `origin-space` or `destination` is not a [known color space], throw
   an error.
 
-* Let `mapped` be the result of [CSS gamut mapping][css-mapping] `origin`
-  color, with an origin color space of `origin-space`, and destination of
-  `destination`.
+* Let `color` be the result of [converting] `origin` into `destination`.
+
+* If `method` is not one of the methods defined below, throw an error.
+
+* Let `mapped` be the result of running the method defined below whose name
+  matches `method`. If no such method matches, throw an error.
 
 * Return the result of [converting] `mapped` into `origin-space`.
 
-> This algorithm implements a relative colorimetric intent, and colors inside
-> the destination gamut are unchanged. Since the process is lossy, authors
-> should be encouraged to let the browser handle gamut mapping when possible.
+#### `local-minde`
 
-[css-mapping]: https://www.w3.org/TR/css-color-4/#css-gamut-mapping-algorithm
-[css-map]: https://www.w3.org/TR/css-color-4/#css-gamut-map
+The `local-minde` gamut mapping procedure in Sass follows the 13 February 2024
+draft of CSS Color Module Level 4. It returns the result of [CSS gamut
+mapping][css-mapping] `origin` with an origin color space of `origin-space` and
+destination of `destination`.
+
+[css-mapping]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#css-gamut-mapping-algorithm
+
+> This algorithm implements a relative colorimetric intent, and colors inside
+> the destination gamut are unchanged.
+
+#### `clip`
+
+The `clip` gamut mapping procedure is not expected to produce good-looking
+results, but it can be useful to match the current behavior of browsers.
+
+* Let `new-color` be a copy of `color`.
+
+* For each `channel` in `destination`:
+
+  * If `channel` is bounded, set `new-color`'s `channel` value to the result of
+    clamping the original value within `channel`'s minimum and maximum values.
+
+* Return `new-color`.
 
 ### Parsing Color Components
 
@@ -1626,11 +1662,14 @@ is-in-gamut($color, $space: null)
 ### `color.to-gamut()`
 
 ```
-to-gamut($color, $space: null)
+to-gamut($color, $space: null, $method: null)
 ```
 
 * If `$color` is not a color, throw an error.
 
+* If `$method` is not an unquoted string whose value is either `local-minde` or
+  `clip`, throw an error.
+
 * If `$space` is null:
 
   * Let `origin-space` be the result of calling `color.space($color)`.
@@ -1641,8 +1680,8 @@ to-gamut($color, $space: null)
 * Otherwise, let `target-space` be the result of [looking up a known color
   space] named `$space`.
 
-* Return the result of [gamut mapping] `$color` with a `target-space`
-  destination.
+* Return the result of [gamut mapping] `$color` with destination `target-space`
+  and method `$method`.
 
 [gamut mapping]: #gamut-mapping
 
diff --git a/js-api-doc/index.d.ts b/js-api-doc/index.d.ts
index 8c18b32e..e1d8fd62 100644
--- a/js-api-doc/index.d.ts
+++ b/js-api-doc/index.d.ts
@@ -58,6 +58,7 @@ export {
   ColorSpaceLab,
   ColorSpaceRgb,
   ColorSpaceXyz,
+  GamutMapMethod,
   HueInterpolationMethod,
   KnownColorSpace,
   ListSeparator,
diff --git a/js-api-doc/value/color.d.ts b/js-api-doc/value/color.d.ts
index 2ec9763e..643d692b 100644
--- a/js-api-doc/value/color.d.ts
+++ b/js-api-doc/value/color.d.ts
@@ -79,6 +79,25 @@ export type HueInterpolationMethod =
   | 'longer'
   | 'shorter';
 
+/**
+ * Methods by which colors in bounded spaces can be mapped to within their
+ * gamut.
+ *
+ * * `local-minde`: The algorithm specified in [the original Color Level 4
+ *   candidate recommendation]. This maps in the Oklch color space, using the
+ *   [deltaEOK] color difference formula and the [local-MINDE] improvement.
+ *
+ * * `clip`: Clamp each color channel that's outside the gamut to the minimum or
+ *   maximum value for that channel. This algorithm will produce poor visual
+ *   results, but it may be useful to match the behavior of other situations in
+ *   which a color can be clipped.
+ *
+ * [the original Color Level 4 candidate recommendation]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#css-gamut-mapping
+ * [deltaEOK]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#color-difference-OK
+ * [local-MINDE]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#GM-chroma-local-MINDE
+ */
+export type GamutMapMethod = 'clip' | 'local-minde';
+
 /**
  * Sass's [color type](https://sass-lang.com/documentation/values/colors).
  *
@@ -269,14 +288,13 @@ export class SassColor extends Value {
 
   /**
    * Returns a copy of this color, modified so it is in-gamut for the specified
-   * `space`—or the current color space if `space` is not specified—using the
-   * recommended [CSS Gamut Mapping Algorithm][css-mapping] to map out-of-gamut
-   * colors into the desired gamut with as little perceptual change as possible.
-   *
-   * [css-mapping]:
-   * https://www.w3.org/TR/css-color-4/#css-gamut-mapping-algorithm
+   * `space`—or the current color space if `space` is not specified—using
+   * `method` to map out-of-gamut colors into the desired gamut.
    */
-  toGamut(space?: KnownColorSpace): SassColor;
+  toGamut(options: {
+    space?: KnownColorSpace;
+    method: GamutMapMethod;
+  }): SassColor;
 
   /**
    * A list of this color's channel values (excluding alpha), with [missing
diff --git a/js-api-doc/value/index.d.ts b/js-api-doc/value/index.d.ts
index 94628bca..0877d5d6 100644
--- a/js-api-doc/value/index.d.ts
+++ b/js-api-doc/value/index.d.ts
@@ -34,6 +34,7 @@ export {
   ColorSpaceXyz,
   ChannelNameXyz,
   ChannelName,
+  GamutMapMethod,
   KnownColorSpace,
   PolarColorSpace,
   RectangularColorSpace,
diff --git a/spec/js-api/index.d.ts.md b/spec/js-api/index.d.ts.md
index e8dbc413..22b14ccb 100644
--- a/spec/js-api/index.d.ts.md
+++ b/spec/js-api/index.d.ts.md
@@ -95,6 +95,7 @@ export {
   ColorSpaceLab,
   ColorSpaceRgb,
   ColorSpaceXyz,
+  GamutMapMethod,
   HueInterpolationMethod,
   KnownColorSpace,
   ListSeparator,
diff --git a/spec/js-api/value/color.d.ts.md b/spec/js-api/value/color.d.ts.md
index 3db80372..a4c8e33f 100644
--- a/spec/js-api/value/color.d.ts.md
+++ b/spec/js-api/value/color.d.ts.md
@@ -26,6 +26,7 @@ import {Value} from './index';
   * [`PolarColorSpace`](#polarcolorspace)
   * [`RectangularColorSpace`](#rectangularcolorspace)
   * [`HueInterpolationMethod`](#hueinterpolationmethod)
+  * [`GamutMapMethod`](#gamutmapmethod)
   * [`SassColor`](#sasscolor)
     * [`internal`](#internal)
     * [Constructor](#constructor)
@@ -224,6 +225,14 @@ export type HueInterpolationMethod =
   | 'shorter';
 ```
 
+### `GamutMapMethod`
+
+Methods by which colors in bounded spaces can be mapped to within their gamut.
+
+```ts
+export type GamutMapMethod = 'clip' | 'local-minde';
+```
+
 ### `SassColor`
 
 The JS API representation of a Sass color.
@@ -552,13 +561,16 @@ isInGamut(space?: KnownColorSpace): boolean;
 
 #### `toGamut`
 
-Returns the result of [`color.to-gamut(internal, space)`].
+Returns the result of [`color.to-gamut(internal, space, method)`].
 
 ```ts
-toGamut(space?: KnownColorSpace): SassColor;
+toGamut(options: {
+  space?: KnownColorSpace;
+  method: GamutMapMethod;
+}): SassColor;
 ```
 
-[`color.to-gamut(internal, space)`]: ../../../accepted/color-4-new-spaces.md#colorto-gamut-1
+[`color.to-gamut(internal, space, method)`]: ../../../accepted/color-4-new-spaces.md#colorto-gamut-1
 
 #### `channelsOrNull`
 
diff --git a/spec/js-api/value/index.d.ts.md b/spec/js-api/value/index.d.ts.md
index a1079c20..d35f0cec 100644
--- a/spec/js-api/value/index.d.ts.md
+++ b/spec/js-api/value/index.d.ts.md
@@ -37,6 +37,7 @@ export {
   ColorSpaceXyz,
   ChannelNameXyz,
   ChannelName,
+  GamutMapMethod,
   KnownColorSpace,
   PolarColorSpace,
   RectangularColorSpace,

From baffce17082dccf0a503bba1ec2214b3abd86f0d Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Thu, 25 Apr 2024 13:14:50 -0700
Subject: [PATCH 38/51] [Color 4] Require case-sensitivity for all channel
 names (#3851)

This was already implicit in most cases, because all string
comparisons are case-sensitive by default, but a few alpha comparisons
were explicitly case-insensitive. This makes it more consistent as
well as more explicit, and adds a design decision section discussing
the reasoning.
---
 accepted/color-4-new-spaces.changes.md |  4 ++
 accepted/color-4-new-spaces.md         | 54 +++++++++++++++++++-------
 2 files changed, 45 insertions(+), 13 deletions(-)

diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index 160f6857..56fa668c 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -1,3 +1,7 @@
+## Draft 1.16
+
+* Explicitly require case-sensitivity for channel names in Sass functions.
+
 ## Draft 1.15
 
 * Add a mandatory `$method` parameter to `color.to-gamut()` for
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index e95571a7..32bdcce2 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -1,4 +1,4 @@
-# CSS Color Level 4, New Color Spaces: Draft 1.15
+# CSS Color Level 4, New Color Spaces: Draft 1.16
 
 *([Issue](https://github.com/sass/sass/issues/2831))*
 
@@ -33,6 +33,7 @@ colors outside the sRGB gamut.
   * [Design Decisions](#design-decisions)
     * [Unclamped Channels](#unclamped-channels)
     * [Clamped Channels](#clamped-channels)
+    * [Conventions for Channels and Space Names](#conventions-for-channels-and-space-names)
     * [Changing Color Spaces](#changing-color-spaces)
     * [Gamut Mapping](#gamut-mapping)
     * [CSS Color 5](#css-color-5)
@@ -488,6 +489,33 @@ out-of-gamut values:
   ..., color(xyz ...) 100%, black)` to preserve both the original color space
   and the unclamped value in conformant browsers.
 
+#### Conventions for Channels and Space Names
+
+This proposal uses different conventions for referring to the names of color
+spaces as it does for referring to the names of individual channels within those
+spaces. Specifically:
+
+* Color space names are required to be unquoted and matched case-insensitively.
+
+* Color channels are required to be matched case-sensitively, and to be quoted
+  unless they're used as keyword arguments.
+
+This is motivated by the fact that color space names are a CSS-native construct
+which are used in the `color()` and `color-mix()` functions, and in those
+contexts are unquoted and case-insensitive; while the channel names, although
+*informed* by CSS's color space definitions, are ultimately Sass-specific and
+follow the more common Sass API conventions. Even when CSS does refer to
+channels, such as in the [relative color syntax] of CSS Color 5, it universally
+refers to them as single characters rather than full names. We wish to avoid
+these single-character names both for readability and for
+backwards-compatibility with older Sass APIs.
+
+[relative color syntax]: https://drafts.csswg.org/css-color-5/#relative-colors
+
+In addition, requiring that channel names be quoted avoids the issue where
+unquoted `red`, `green`, and `blue` channels of many colors would be parsed by
+Sass as color values rather than unquoted strings.
+
 #### Changing Color Spaces
 
 Different color spaces often represent different color-gamuts, which can present
@@ -549,7 +577,6 @@ provides us with the most flexibility to change our behavior in the future.
 
 [open issue in CSS]: https://github.com/w3c/csswg-drafts/issues/7771
 [color-5]: https://www.w3.org/TR/css-color-5/
-[relative color syntax]: https://drafts.csswg.org/css-color-5/#relative-colors
 
 #### Special Thanks
 
@@ -1632,7 +1659,8 @@ is-powerless($color, $channel, $space: null)
 
 * Let `channels` be a list of the `color`'s channels.
 
-* If `$channel` is not the name of a channel in `channels`, throw an error.
+* If `$channel` is not the (case sensitive) name of a channel in `channels`,
+  throw an error.
 
 * Return `true` if the channel `$channel` is [powerless] in `color`,
   otherwise return `false`.
@@ -1699,16 +1727,15 @@ channel($color, $channel, $space: null)
 
 * If `$channel` is not a quoted string, throw an error.
 
-* If `$channel == 'alpha'` (ignoring case), let `value` be the alpha value of
-  `$color`.
+* If `$channel == 'alpha'`, let `value` be the alpha value of `$color`.
 
 * Otherwise:
 
   * Let `color` be `$color` if `$space` is null, and the result of calling
     `color.to-space($color, $space)` otherwise.
 
-  * Let `channel` be the channel in `color`'s space named `$channel`. Throw an
-    error if no such channel exists.
+  * Let `channel` be the channel in `color`'s space (case sensitively) named
+    `$channel`. Throw an error if no such channel exists.
 
   * Let `value` be `channel`'s value in `color`, or `0` if the channel's value
     is missing.
@@ -1733,12 +1760,12 @@ is-missing($color, $channel)
 
 * If `$channel` is not a quoted string, throw an error.
 
-* If `$channel == alpha` (ignoring case), let `value` be the alpha value of
-  `$color`.
+* If `$channel == alpha`, let `value` be the alpha value of `$color`.
 
 * Otherwise:
 
-  * If `channel` is not the name of a channel in `$color`, throw an error.
+  * If `$channel` is not the (case-sensitive) name of a channel in `$color`,
+    throw an error.
 
   * Let `value` be the channel value named `channel` in `color`.
 
@@ -1861,7 +1888,7 @@ This function is also available as a global function named `change-color()`.
     > This basic restriction can be applied to all spaces. Further channel
     > restrictions are enforced by the normalization step for known spaces.
 
-  * If `key` is not the name of a channel in `channels`:
+  * If `key` is not the (case-sensitive) name of a channel in `channels`:
 
     * If `$space` is specified, throw an error.
 
@@ -1939,7 +1966,7 @@ This function is also available as a global function named `adjust-color()`.
 
 * For each keyword `key` and value `adjust` in `channel-args`:
 
-  * If `key` is not the name of a channel in `channels`:
+  * If `key` is not the (case-sensitive) name of a channel in `channels`:
 
     * If `$space` is specified, throw an error.
 
@@ -2061,7 +2088,8 @@ This function is also available as a global function named `scale-color()`.
 
 * For each keyword `scale`, `factor` in `channel-args`:
 
-  * If `scale` is not the name of a [scalable] channel in `channels`:
+  * If `scale` is not the (case-sensitive) name of a [scalable] channel in
+    `channels`:
 
     * If `$space` is specified, throw an error.
 

From d6597814bca9f5d7be48619e1dbf417d4734a313 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Thu, 2 May 2024 13:30:06 -0700
Subject: [PATCH 39/51] [Color 4] Clean up the definition of `color.same()`
 (#3852)

This was still written with the expectation that unknown color spaces
existed. It also makes missing channels equivalent to 0s even if they
survive the conversion to `xyz`.
---
 accepted/color-4-new-spaces.changes.md |  4 ++++
 accepted/color-4-new-spaces.md         | 14 +++-----------
 2 files changed, 7 insertions(+), 11 deletions(-)

diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index 56fa668c..3a0fa1b4 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -1,3 +1,7 @@
+## Draft 1.17
+
+* Treat colors with missing channels as the same as 0 for `color.same()`.
+
 ## Draft 1.16
 
 * Explicitly require case-sensitivity for channel names in Sass functions.
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index 32bdcce2..c7fc9edf 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -1782,18 +1782,10 @@ is-missing($color, $channel)
 same($color1, $color2)
 ```
 
-* If either `$color1` or `$color2` is not a color in a [known color space]:
+* Let `color1` and `color2` be the result of [converting] `$color1` and
+  `$color2` into `xyz` color space, respectively.
 
-  * Let `color1` be `$color1`, and let `color2` be `$color2`.
-
-  > We can compare, but we can't do conversion. The color space remains
-  > relevant to equality. While this is technically the same as using `==`,
-  > it makes the function more robust to allow comparison of all colors.
-
-* Otherwise:
-
-  * Let `color1` and `color2` be the result of [converting] `$color1` and
-    `$color2` into `xyz` color space, respectively.
+* Replace any [missing] components in `color1` and `color2` with 0.
 
 * Return `color1 == color2`.
 

From 2cde27c85a08462161ffd051c79222bd1bb81f18 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Thu, 2 May 2024 15:03:09 -0700
Subject: [PATCH 40/51] [Color 4] Zero missing channels before conversion in
 `color.same()`

Otherwise, you get weird behavior when conversion to the XYZ space
preserves missing channels, which can cause colors to be considered
`same()` even when they're visually distinct.
---
 accepted/color-4-new-spaces.changes.md |  4 ++++
 accepted/color-4-new-spaces.md         | 18 +++++++++++++-----
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index 3a0fa1b4..cf21537c 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -1,3 +1,7 @@
+## Draft 1.18
+
+* Convert missing channels to 0 before color conversion for `color.same()`.
+
 ## Draft 1.17
 
 * Treat colors with missing channels as the same as 0 for `color.same()`.
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index c7fc9edf..8453e2f7 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -1,4 +1,4 @@
-# CSS Color Level 4, New Color Spaces: Draft 1.16
+# CSS Color Level 4, New Color Spaces: Draft 1.18
 
 *([Issue](https://github.com/sass/sass/issues/2831))*
 
@@ -1782,12 +1782,20 @@ is-missing($color, $channel)
 same($color1, $color2)
 ```
 
-* Let `color1` and `color2` be the result of [converting] `$color1` and
-  `$color2` into `xyz` color space, respectively.
+* Let `color1` and `color2` be `$color1` and `$color2`, respectively, with any
+  [missing] components replaced with 0.
 
-* Replace any [missing] components in `color1` and `color2` with 0.
+  > This is necessary to ensure that `same()` actually matches visual rendering.
+  > For example, `rgb(100 200 0)` and `rgb(100 200 none)` are rendered
+  > identically, but the former converts to `color(xyz 0.2590878471 0.4401656621
+  > 0.0713080481)` while the latter converts to `color(xyz 0.2590878471
+  > 0.4401656621 none)`, which are *not* equivalent if we convert missing
+  > channels to zero after XYZ conversion.
 
-* Return `color1 == color2`.
+* Let `xyz1` and `xyz2` be the result of [converting] `color1` and `color2` into
+  `xyz` color space, respectively.
+
+* Return `xyz1 == xyz2`.
 
 ## Modified Color Module Functions
 

From ca967a42a686a4fa331f479d796054cd9f7dcf82 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Thu, 2 May 2024 15:38:28 -0700
Subject: [PATCH 41/51] [Color 4] Treat missing channels as distinct from 0 for
 `==`

Now that `color.same()` explicitly treats missing channels as 0, it
makes more sense for `==` to fill the stricter role and treat them as
different. This is especially true because it already
requires (non-legacy) colors to be in the same space, so missing
channels are much more consistently meaningful than they would be in
cross-space comparisons.
---
 accepted/color-4-new-spaces.changes.md |  4 +++-
 accepted/color-4-new-spaces.md         | 20 +++++++++++---------
 2 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index cf21537c..6e4a3bb6 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -1,4 +1,6 @@
-## Draft 1.18
+## Draft 1.19
+
+* Treat missing channels as distinct from 0 for `==`-equality for colors.
 
 * Convert missing channels to 0 before color conversion for `color.same()`.
 
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index 8453e2f7..966801f6 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -631,20 +631,22 @@ Legacy colors that have [missing] components are
 
 ### Color Equality
 
-For determining *equality* between two colors:
+For determining *equality* between two colors `color1` and `color2`:
 
-* If both colors are [legacy colors](#legacy-color):
+* If both colors are [legacy colors](#legacy-color) in different spaces, return
+  `color.to-space(color1, rgb) == color.to-space(color2, rgb)`.
 
-  * Set each color to the result of [converting] the color into `rgb` space.
+* If the colors are not in the same color space, return false.
 
-  * Colors are only equal if their channel and alpha values are fuzzy-equal.
+* If either color has a channel (including alpha) marked as [missing] that the
+  other does not, return false.
 
-    > Since this definition no longer involves rounding channels, it is
-    > potentially a breaking change. Moving forward,
-    > `rgb(0 0 0.6) != rgb(0 0 1)`.
+* Return whether each matching pair of non-missing channel values (including
+  alpha) is fuzzy-equal.
 
-* Otherwise, colors are only equal when they're in the same color space and
-  their channel and alpha values are fuzzy-equal.
+  > Since this definition no longer involves rounding channels for the legacy
+  > RGB space, it is potentially a breaking change. Moving forward, `rgb(0 0
+  > 0.6) != rgb(0 0 1)`.
 
 ### Known Color Space
 

From c8fe2ed86f99a8a4aa91193a798228441a2df95d Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Fri, 3 May 2024 15:19:40 -0700
Subject: [PATCH 42/51] [Color 4] Improve specifications for missing alpha
 values

---
 accepted/color-4-new-spaces.changes.md |  8 ++-
 accepted/color-4-new-spaces.md         | 75 +++++++++++++++++---------
 2 files changed, 56 insertions(+), 27 deletions(-)

diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index 6e4a3bb6..78dbd3a3 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -1,9 +1,15 @@
-## Draft 1.19
+## Draft 1.18
 
 * Treat missing channels as distinct from 0 for `==`-equality for colors.
 
 * Convert missing channels to 0 before color conversion for `color.same()`.
 
+* Explicitly support `none` values for `alpha` in Parsing Color Components and
+  `color.change()`,
+
+* Clarify how to handle existing missing components in `color.adjust()` and
+  `color.scale()`.
+
 ## Draft 1.17
 
 * Treat colors with missing channels as the same as 0 for `color.same()`.
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index 966801f6..d6930d13 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -1212,13 +1212,13 @@ The procedure is:
 
 * If `alpha` is null, let `alpha` be `1`.
 
-* Otherwise, If `alpha` is not a [special number]:
+* Otherwise, If `alpha` is neither a [special number] nor an unquoted string
+  that's case-insensitively equal to 'none':
 
-  * If `alpha` is a number, set `alpha` to the result of
-    [percent-converting] `alpha` with a max of 1, and then clamping the value
-    between 0 and 1, inclusive.
+  * If `alpha` is not a number, throw an error.
 
-  * Otherwise, throw an error.
+  * Set `alpha` to the result of [percent-converting] `alpha` with a max of 1,
+    and then clamping the value between 0 and 1, inclusive.
 
 * If `channels` is a [special variable string], or if `alpha` is a [special
   number], return an unquoted string with the value of `input`.
@@ -1874,8 +1874,11 @@ This function is also available as a global function named `change-color()`.
 
 * If the keyword argument `$alpha` is specified in `$args`:
 
-  * Set `alpha` to the result of [percent-converting] `$alpha` with a `max` of
-    1, and clamping it between 0 and 1 (inclusive).
+  * If `alpha` isn't a number or an unquoted string that's case-insensitively
+    equal to 'none', throw an error.
+
+  * If `alpha` is a number, set `alpha` to the result of [percent-converting]
+    `$alpha` with a `max` of 1, and clamping it between 0 and 1 (inclusive).
 
 * Let `channel-args` be the remaining keyword arguments in `$args`, not
   including `$space` or `$alpha` arguments.
@@ -1916,7 +1919,7 @@ This function is also available as a global function named `change-color()`.
 * Set `channels` to the result of [normalizing] `channels` in `known-space`.
 
 * Let `new` be a color in color space `known-space`, with `channels` channels,
-  and an alpha of `alpha`.
+  and an alpha of `alpha`, or a missing alpha if `alpha` is a string.
 
 * Return the result of [converting] `new` into `origin-space`.
 
@@ -1950,14 +1953,20 @@ This function is also available as a global function named `adjust-color()`.
 
 * If the keyword argument `$alpha` is specified in `$args`:
 
-  * If `alpha == none`, throw an error.
+  * If `color`'s alpha channel is missing, throw an error.
 
-    > This is not the ideal solution for handling `none`, but we want to
-    > match CSS relative color syntax if possible. Throwing an error for now
-    > means we can adjust to match the CSS behavior once it is defined.
+    > This is not the ideal solution for handling `none`, but we want to match
+    > CSS relative color syntax if possible. Throwing an error for now means we
+    > can adjust to match the CSS behavior once it is defined. See the following
+    > issues for details:
+    >
+    > * [w3c/csswg-drafts#10151](https://github.com/w3c/csswg-drafts/issues/10151)
+    > * [w3c/csswg-drafts#10211](https://github.com/w3c/csswg-drafts/issues/10211)
 
-  * Let `new-alpha` be the result of [percent-converting] `$alpha` with a `max`
-    of 1.
+  * If `$alpha` isn't a number, throw an error.
+
+  * Let `new-alpha` be the result of [percent-converting] `$alpha` with a
+    `max` of 1.
 
   * Set `alpha` to the value of `new-alpha + alpha` clamped between 0 and 1.
 
@@ -1995,11 +2004,15 @@ This function is also available as a global function named `adjust-color()`.
 
   * Let `channel` be the channel named `key` in `known-space`.
 
-  * If `channel == none`, throw an error.
+  * If `channel` is missing in `color`, throw an error.
 
-    > This is not the ideal solution for handling `none`, but we want to
-    > match CSS relative color syntax if possible. Throwing an error for now
-    > means we can adjust to match the CSS behavior once it is defined.
+    > This is not the ideal solution for handling `none`, but we want to match
+    > CSS relative color syntax if possible. Throwing an error for now means we
+    > can adjust to match the CSS behavior once it is defined. See the following
+    > issues for details:
+    >
+    > * [w3c/csswg-drafts#10151](https://github.com/w3c/csswg-drafts/issues/10151)
+    > * [w3c/csswg-drafts#10211](https://github.com/w3c/csswg-drafts/issues/10211)
 
   * If `adjust` has the unit `%`:
 
@@ -2075,11 +2088,17 @@ This function is also available as a global function named `scale-color()`.
 
 * If the keyword argument `$alpha` is specified in `$args`:
 
-  * If `alpha == none`, throw an error.
+  * If `color`'s alpha channel is missing, throw an error.
 
-    > This is not the ideal solution for handling `none`, but we want to
-    > match CSS relative color syntax if possible. Throwing an error for now
-    > means we can adjust to match the CSS behavior once it is defined.
+    > This is not the ideal solution for handling `none`, but we want to match
+    > CSS relative color syntax if possible. Throwing an error for now means we
+    > can adjust to match the CSS behavior once it is defined. See the following
+    > issues for details:
+    >
+    > * [w3c/csswg-drafts#10151](https://github.com/w3c/csswg-drafts/issues/10151)
+    > * [w3c/csswg-drafts#10211](https://github.com/w3c/csswg-drafts/issues/10211)
+
+  * If `$alpha` isn't a number, throw an error.
 
   * Set `alpha` to the result of [scaling] `alpha` by `$alpha` with `max` 1.
 
@@ -2112,11 +2131,15 @@ This function is also available as a global function named `scale-color()`.
   * Let `channel` be the corresponding `channel` in `channels` with a name
     matching `scale`.
 
-  * If `channel == none`, throw an error.
+  * If `channel` is missing in `color`, throw an error.
 
-    > This is not the ideal solution for handling `none`, but we want to
-    > match CSS relative color syntax if possible. Throwing an error for now
-    > means we can adjust to match the CSS behavior once it is defined.
+    > This is not the ideal solution for handling `none`, but we want to match
+    > CSS relative color syntax if possible. Throwing an error for now means we
+    > can adjust to match the CSS behavior once it is defined. See the following
+    > issues for details:
+    >
+    > * [w3c/csswg-drafts#10151](https://github.com/w3c/csswg-drafts/issues/10151)
+    > * [w3c/csswg-drafts#10211](https://github.com/w3c/csswg-drafts/issues/10211)
 
   * Let `channel-max` be the upper boundary of `channel` in `space`.
 

From 6395fd848f8558bcf853dc292c2e1437c08f2ec6 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Tue, 7 May 2024 17:13:15 -0700
Subject: [PATCH 43/51] [Color 4] Remove contradictory langugae for scaling a
 number

---
 accepted/color-4-new-spaces.changes.md |  3 +++
 accepted/color-4-new-spaces.md         | 16 ++++++++--------
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index 78dbd3a3..8be8fc4d 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -10,6 +10,9 @@
 * Clarify how to handle existing missing components in `color.adjust()` and
   `color.scale()`.
 
+* Remove language misleadingly indicating that the scaling a number algorithm
+  was guaranteed to return an in-gamut number.
+
 ## Draft 1.17
 
 * Treat colors with missing channels as the same as 0 for `color.same()`.
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index d6930d13..baaa952a 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -1557,15 +1557,15 @@ in [CSS Color Level 4][color-4].
 
 ### Scaling a Number
 
-This algorithm takes a number `number`, a value `factor`, a number `max`, and
-an optional number `min`. It's written "scale `<number>` by `<factor>` with a
-`max` of `<max>` and a `min` of `<min>`". It returns a number with a value
-between `min` (or 0) and `max` and the same units as `number`.
+This algorithm takes a number `number`, a value `factor`, a number `max`, and an
+optional number `min`. It's written "scale `<number>` by `<factor>` with a `max`
+of `<max>` and a `min` of `<min>`". It returns a number with the same units as
+`number`.
 
-> Note that this no longer assumes the original `number` is in a range of
-> 0 to `max`. We now allow scaling up negative numbers, and scaling down
-> numbers above the `max` value. The inverse operations return the `number`
-> unchanged, since that's the asymptotic scale behavior approaching boundaries.
+> Note that this no longer assumes the original `number` is in a range of `min`
+> to `max`. We now allow scaling up negative numbers, and scaling down numbers
+> above the `max` value. The inverse operations return the `number` unchanged,
+> since that's the asymptotic scale behavior approaching boundaries.
 
 * If `factor` isn't a number with unit `%` between `-100%` and `100%`
   (inclusive), throw an error.

From 62478f8738eefb746309778fb3b6c15585cc2ee4 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Wed, 8 May 2024 14:42:08 -0700
Subject: [PATCH 44/51] [Color 4] Make `convert()` and `grayscale()` preserve
 space

---
 accepted/color-4-new-spaces.changes.md |  3 +++
 accepted/color-4-new-spaces.md         | 23 ++++++++++-------------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index 8be8fc4d..9ed5f449 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -13,6 +13,9 @@
 * Remove language misleadingly indicating that the scaling a number algorithm
   was guaranteed to return an in-gamut number.
 
+* Ensure that `color.invert()` and `color.grayscale()` always return colors in
+  the original color's space.
+
 ## Draft 1.17
 
 * Treat colors with missing channels as the same as 0 for `color.same()`.
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index baaa952a..cfad8397 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -2259,9 +2259,12 @@ This function is also available as a global function named `invert()`.
 
     * Set the corresponding channel of `invert` to be `new`.
 
-* If `$weight == 100%`, return the value of `invert`.
+* If `$weight == 100%`, let `result` be `invert`.
 
-* Return the result of calling `color.mix(invert, color, $weight, mix-space)`.
+* Otherwise, let `result` be the result of calling `color.mix(invert, color,
+  $weight, mix-space)`.
+
+* Return the result of [converting] `result` to `$color`'s space.
 
 ### `color.grayscale()`
 
@@ -2275,19 +2278,13 @@ This function is also available as a global function named `grayscale()`.
 
 * If `$color` is not a color, throw an error.
 
-* If `$color` is a legacy color:
+* If `$color` is a legacy color, let `result` be the result of [converting]
+  `$color` to `hsl`, and changing the 'saturation' channel to 0.
 
-  * Return the result of [converting] `$color` to `hsl`, and changing the
-    'saturation' channel to 0.
+* Otherwise, let `result` be the result of [converting] `$color` to `oklch`, and
+  setting the `chroma` channel to 0.
 
-* Otherwise:
-
-  * Let `origin` be `$color`'s color space.
-
-  * Let `color` be the result of [converting] `$color` to `oklch`, and
-    setting the `chroma` channel to 0.
-
-  * Return the result of [converting] `color` to `origin`.
+* Return the result of [converting] `color` to `$color`'s space.
 
 ### `color.ie-hex-str()`
 

From 65a0adec502a96124898a3f6c8e12a2d62c87961 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Wed, 8 May 2024 16:36:48 -0700
Subject: [PATCH 45/51] [Color 4] Make `invert()` throw an error for invalid
 weight

---
 accepted/color-4-new-spaces.changes.md | 2 ++
 accepted/color-4-new-spaces.md         | 4 ++--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index 9ed5f449..6be5def9 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -16,6 +16,8 @@
 * Ensure that `color.invert()` and `color.grayscale()` always return colors in
   the original color's space.
 
+* Make `color.invert()` throw an error for an invalid `$weight`.
+
 ## Draft 1.17
 
 * Treat colors with missing channels as the same as 0 for `color.same()`.
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index cfad8397..abf41880 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -2202,6 +2202,8 @@ This function is also available as a global function named `invert()`.
 
 * If `$color` is not a color, throw an error.
 
+* If `$weight` is neither null nor a number with unit `%`, throw an error.
+
 * If `$space` is null:
 
   * If `$color` is a legacy color, let `space` be `rgb`, and let `mix-space`
@@ -2216,8 +2218,6 @@ This function is also available as a global function named `invert()`.
   * Let `space` be the result of [looking up a known color space] named
     `$space`.
 
-  * If `space` is not a [known color space], throw an error.
-
   * Let `mix-space` be `space`.
 
 * If `$weight == 0%`, return the value of `$color`.

From ed13d3389deca69e05545bf71698c7f3c3491b50 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Wed, 8 May 2024 17:18:59 -0700
Subject: [PATCH 46/51] [Color 4] CSS compatibility for `invert()` and
 `grayscale()`

---
 accepted/color-4-new-spaces.changes.md | 3 +++
 accepted/color-4-new-spaces.md         | 9 +++++++++
 2 files changed, 12 insertions(+)

diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index 6be5def9..7916dcdb 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -18,6 +18,9 @@
 
 * Make `color.invert()` throw an error for an invalid `$weight`.
 
+* Include CSS-compatibility behavior for `color.invert()` and
+  `color.grayscale()`.
+
 ## Draft 1.17
 
 * Treat colors with missing channels as the same as 0 for `color.same()`.
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index abf41880..bca06517 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -2200,6 +2200,11 @@ invert($color,
 
 This function is also available as a global function named `invert()`.
 
+* If `invert()` was called as a global function, `$color` is either a number or
+  a [special number], `$weight == 100%`, and `$space` is null, return an
+  unquoted string representing a CSS function call with name "invert" and
+  argument `$color`.
+
 * If `$color` is not a color, throw an error.
 
 * If `$weight` is neither null nor a number with unit `%`, throw an error.
@@ -2276,6 +2281,10 @@ grayscale($color)
 
 This function is also available as a global function named `grayscale()`.
 
+* If `grayscale()` was called as a global function and `$color` is either a
+  number or a [special number], return an unquoted string representing a CSS
+  function call with name "invert" and argument `$color`.
+
 * If `$color` is not a color, throw an error.
 
 * If `$color` is a legacy color, let `result` be the result of [converting]

From 84f5188d94d473c9b7e5418ba2fab45d4330efb2 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Wed, 8 May 2024 17:30:16 -0700
Subject: [PATCH 47/51] [Color 4] Use local-minde gamut mapping for
 `ie-hex-string()`

---
 accepted/color-4-new-spaces.changes.md | 2 ++
 accepted/color-4-new-spaces.md         | 3 ++-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index 7916dcdb..2d26a35b 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -21,6 +21,8 @@
 * Include CSS-compatibility behavior for `color.invert()` and
   `color.grayscale()`.
 
+* Explicitly mandate `local-minde` gamut-mapping for `ie-hex-str()`.
+
 ## Draft 1.17
 
 * Treat colors with missing channels as the same as 0 for `color.same()`.
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index bca06517..4cb353a8 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -2306,7 +2306,8 @@ ie-hex-str($color)
 
 * If `$color` is not a color, throw an error.
 
-* Let `rgb` be the result of [converting] and [gamut mapping] `$color` to `rgb`.
+* Let `rgb` be the result of [converting] and [gamut mapping] `$color` to `rgb`
+  with method `local-minde`.
 
 * Let `hex-list` be an empty list.
 

From e778899743cb1e0f97eb327e644ffacb1e3ad1a5 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Fri, 10 May 2024 14:27:08 -0700
Subject: [PATCH 48/51] [Color 4] Be stricter about slash-separated strings
 (#3862)

Co-authored-by: Carlos (Goodwine) <2022649+Goodwine@users.noreply.github.com>
---
 accepted/color-4-new-spaces.changes.md |  5 +++++
 accepted/color-4-new-spaces.md         | 30 +++++++++++---------------
 2 files changed, 18 insertions(+), 17 deletions(-)

diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index 2d26a35b..1742d4d0 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -1,3 +1,8 @@
+## Draft 1.19
+
+* Be stricter about which colors are allowed with slash-separated strings at the
+  end.
+
 ## Draft 1.18
 
 * Treat missing channels as distinct from 0 for `==`-equality for colors.
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index 4cb353a8..12f1c0f4 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -1138,29 +1138,25 @@ The procedure is:
 
   * If the last element of `input` is an unquoted string that contains `/`:
 
+    > This solves for a legacy handling of `/` in Sass that would produce an
+    > unquoted string when the alpha value is a CSS function such as `var()`,
+    > when either value is `none`, or when using relative color syntax.
+
     * Let `split-last` be the result calling `string.split()` with the last
       element of `input` as the string to split, and `/` as the separator.
 
-    * If `split-last` has two items, and one or both items are an unquoted
-      string that's case-insensitively equal to 'none':
+    * If `split-last` doesn't have exactly two items, return an unquoted string
+      with the value of `input`.
 
-      > Special handling for `none/none`, `none/<number>`, and `<number>/none`.
+      > This ensures that `rgb(1 2 calc(var(--a) / var(--b)) / var(--c))` is
+      > handled correctly after the final expresssion is fully converted to a
+      > string due to legacy `/` behavior.
 
-      * If either item in `split-last` can be coerced to a number, replace
-        the current value of the item with the resulting number value.
+    * If either item in `split-last` can be coerced to a number, replace
+      the current value of the item with the resulting number value.
 
-      * If any item in `split-last` is not a number or an unquoted string
-        that's case-insensitively equal to 'none', return an unquoted string
-        with the value of `input`.
-
-      * Otherwise, let `alpha` be the second element in `split-last`, and
-        append the first element of `split-last` to `components`.
-
-    * Otherwise, return an unquoted string with the value of `input`.
-
-      > This solves for a legacy handling of `/` in Sass that would produce an
-      > unquoted string when the alpha value is a CSS function such as `var()`
-      > or when either value is `none`.
+    * Let `alpha` be the second element in `split-last`, and append the first
+      element of `split-last` to `components`.
 
   * Otherwise, if the last element of `input` has preserved its status as two
     slash-separated numbers:

From 4515cf6addbe317ecee04989d688e009797bcde9 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Wed, 17 Jul 2024 18:21:46 -0700
Subject: [PATCH 49/51] [Color 4] Do a full re-read and revision (#3869)

Co-authored-by: Jennifer Thakar <jathak@google.com>
---
 accepted/color-4-new-spaces.changes.md |   18 +
 accepted/color-4-new-spaces.md         | 1037 +++++++++++-------------
 2 files changed, 498 insertions(+), 557 deletions(-)

diff --git a/accepted/color-4-new-spaces.changes.md b/accepted/color-4-new-spaces.changes.md
index 1742d4d0..4924d4c5 100644
--- a/accepted/color-4-new-spaces.changes.md
+++ b/accepted/color-4-new-spaces.changes.md
@@ -1,3 +1,21 @@
+## Draft 1.20
+
+* Many small wording and consistency changes.
+
+* Remove outdated references to the possibility of unknown color spaces.
+
+* Remove an outdated reference to the `specified` hue interpolation method.
+
+* Make `color.complement()` and `color.invert()` produce errors when color
+  channels are missing, for forwards-compatibility.
+
+* When passing a legacy color to a color manipulation function that operates in
+  another space, ensure that channels aren't marked as `none` in the conversion
+  back to the legacy color.
+
+* Properly include alpha as the *first* channel in `color.ie-hex-str()` rather
+  than the last.
+
 ## Draft 1.19
 
 * Be stricter about which colors are allowed with slash-separated strings at the
diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md
index 12f1c0f4..47a7d7c6 100644
--- a/accepted/color-4-new-spaces.md
+++ b/accepted/color-4-new-spaces.md
@@ -1,4 +1,4 @@
-# CSS Color Level 4, New Color Spaces: Draft 1.18
+# CSS Color Level 4, New Color Spaces: Draft 1.20
 
 *([Issue](https://github.com/sass/sass/issues/2831))*
 
@@ -147,20 +147,20 @@ wider RGB gamuts.
   same underlying RGB color model, and differently-mapped cubic coordinates.
 
 These terms can get a bit confusing, since there is so much overlap. The term
-'RGB' can refer to a color model, a color space, a coordinate system, and also
-a color function. The 'RGB' color space is identical to the 'sRGB' space, and
-both describe the 'sRGB' gamut. But we have both `rgb()` and `color(srgb)`
+"RGB" can refer to a color model, a color space, a coordinate system, and also
+a color function. The "RGB" color space is identical to the "sRGB" space, and
+both describe the "sRGB" gamut. But we have both `rgb()` and `color(srgb)`
 syntax, in order to distinguish legacy from non-legacy variations. They also
-have different coordinate systems, `rgb()` accepts a range from 0-255, while
+have different coordinate systems: `rgb()` accepts a range from 0-255, while
 `color(srgb)` accept values from 0-1.
 
 The result is that authors can generally think of each color syntax as a unique
 space, and each space implies an associated gamut and coordinate system. Color
 spaces become a simple way to refer to all parts combined. We've used that same
-approach in Sass, such that the name of a color space can be used to reference
-the associated gamut. For example, `color.to-gamut($color, hsl)` and
-`color.to-gamut($color, srgb)` have the same meaning, both mapping a color into
-the sRGB gamut.
+approach in Sass, so that the name of a color space can be used to reference the
+associated gamut. For example, `color.to-gamut($color, hsl, $method:
+local-minde)` and `color.to-gamut($color, srgb, $method: local-minde)` have the
+same meaning, both mapping a color into the sRGB gamut.
 
 Since all CSS colors up until this point have been restricted to RGB math in
 the sRGB gamut, Sass has historically treated all color formats and spaces as
@@ -171,8 +171,9 @@ Sass to output the most browser-compatible CSS format for any given color.
 In order to support the color spaces in CSS, Sass will need to start tracking
 the space/gamut associated with any given color, and provide author tools for
 managing those color spaces/gamuts. In addition to supporting the new color
-space functions, we plan to update all functions in the color module, and
-provide some additional space and gamut management and inspection functions.
+space functions like `color()` and `lab()`, we will update all functions in the
+color module to support multiple spaces, and provide some additional space and
+gamut management and inspection functions.
 
 ## Summary
 
@@ -180,8 +181,8 @@ provide some additional space and gamut management and inspection functions.
 
 This proposal defines a Sass representation of colors with color spaces,
 Sassified versions of all the color functions in [CSS Color Level 4][color-4],
-updated definitions of existing Sass functions to accommodate color spaces, and
-several new Sass-specific color functions as well.
+updated definitions of existing Sass functions to accommodate color spaces, as
+well as several new Sass-specific color functions.
 
 ### Rules of Thumb
 
@@ -198,7 +199,7 @@ There are several rules of thumb for working with color spaces in Sass:
 
 * Authors can explicitly convert a color's space by using `color.to-space()`.
   This can be useful to enforce non-legacy behavior, by converting into a
-  non-legacy space, or to ensure the color output is compatible with older
+  non-legacy space; or to ensure the color output is compatible with older
   browsers by converting colors into a legacy space before emitting.
 
 * The `srgb` color space is equivalent to `rgb`, except that one is a legacy
@@ -214,12 +215,9 @@ There are several rules of thumb for working with color spaces in Sass:
 * All legacy and RGB-style spaces represent bounded gamuts of color. Since
   mapping colors into gamut is a lossy process, it should generally be left to
   browsers, which can map colors as-needed, based on the capabilities of a
-  display. For that reason, out-of-gamut channel values are maintained by Sass
-  whenever possible, even when converting into gamut-bounded color spaces. The
-  only exception is that `hsl` and `hwb` color spaces are not able to express
-  out-of-gamut color, so converting colors into those spaces will gamut-map the
-  colors as well. Authors can also perform explicit gamut mapping with the
-  `color.to-gamut()` function.
+  display. For that reason, out-of-gamut channel values are always maintained by
+  Sass, even when converting into gamut-bounded color spaces. Authors can also
+  perform explicit gamut mapping with the `color.to-gamut()` function.
 
 * Legacy browsers require colors in the `srgb` gamut. However, most modern
   displays support the wider `display-p3` gamut.
@@ -234,13 +232,13 @@ functions to define reliably uniform colors. For example, the following colors
 are perceptually similar in lightness and saturation:
 
 ```scss
-$pink: oklch(64% 0.196 353); // hsl(329.8 70.29% 58.75%)
-$blue: oklch(64% 0.196 253); // hsl(207.4 99.22% 50.69%)
+$pink: oklch(64% 0.196 353deg); // hsl(329.8 70.29% 58.75%)
+$blue: oklch(64% 0.196 253deg); // hsl(207.4 99.22% 50.69%)
 ```
 
 The `oklch()` format uses consistent "lightness" and "chroma" values, while the
 `hsl()` format shows dramatic changes in both "lightness" and "saturation". As
-such, `oklch` is often the best space for consistent transforms.
+such, `oklch` is often the best space for consistent transformations.
 
 #### `lab()` and `lch()`
 
@@ -251,15 +249,15 @@ and Oklch.
 #### `hwb()`
 
 Sass now supports a top-level `hwb()` function that uses the same syntax as
-CSS's built-in `hwb()` syntax.
+CSS's built-in `hwb()` function.
 
 #### `color()`
 
 The new `color()` function provides access to a number of specialty spaces. Most
 notably, `display-p3` is a common space for wide-gamut monitors, making it
-likely one of the more popular options for authors who simply want access to a
-wider range of colors. For example, P3 greens are significantly 'brighter' and
-more saturated than the greens available in sRGB:
+likely to be a popular option for authors who simply want access to a wider
+range of colors. For example, P3 greens are significantly "brighter" and more
+saturated than the greens available in sRGB:
 
 ```scss
 $fallback-green: rgb(0% 100% 0%);
@@ -290,10 +288,10 @@ $oklch-lightness: color.channel($brand, "lightness", $space: oklch);
 
 #### `color.is-missing()`
 
-This function returns if a given channel value is 'missing' (set to `none`).
-This is necessary, since `color.channel` returns `0` for missing channels.
-Since color-space conversion can change what channels are missing, this
-function only supports inspecting channels that are part of the color's own
+This function returns whether a given channel value is "missing" (set to
+`none`). This is necessary, since `color.channel` returns `0` for missing
+channels. Since color-space conversion can change which channels are missing,
+this function only supports inspecting channels that are part of the color's own
 space.
 
 ```scss
@@ -322,7 +320,7 @@ $oklch-space: color.space(oklch(37.7% 38.75% 29.23deg));
 
 These functions return various facts about the color. `color.is-in-gamut()`
 returns whether the color is in-gamut for its color space (as opposed to having
-one or more of its channels out of bounds, like `rgb(300 0 0)`).
+one or more of its channels out of bounds, like `color(display-pr 1.2 0 0)`).
 `color.is-legacy()` returns whether the color is a legacy color in the `rgb`,
 `hsl`, or `hwb` color space.
 
@@ -332,7 +330,7 @@ This function returns a color that is in the given gamut, using the given
 mapping algorithm to convert out-of-gamut colors into the desired gamut with as
 little perceptual change as possible. The current recommended algorithm is
 `local-minde`, which is defined in the current candidate recommendation of CSS
-Color 4, which can in many cases be more reliable for generating fallback values
+Color 4, and which will usually be more reliable for generating fallback values
 than the "channel clipping" approach used by current browsers.
 
 ```scss
@@ -358,18 +356,18 @@ $grey: hsl(0 0% 60%);
 $hue-powerless: color.is-powerless($grey, "hue");
 
 // result: false
-$hue-powerless: color.is-powerless($grey, "lightness");
+$lightness-powerless: color.is-powerless($grey, "lightness");
 ```
 
 #### `color.same()`
 
 This function returns whether two colors will be displayed the same way, even if
 this requires converting between spaces. This is unlike the `==` operator, which
-always considers colors in different non-legacy spaces to be inequal.
+always considers colors in different non-legacy spaces to be unequal.
 
 ```scss
 $orange-rgb: #ff5f00;
-$orange-oklch: oklch(68.72% 20.966858279% 41.4189852913deg);
+$orange-oklch: color.to-space($orange-rgb, oklch);
 
 // result: false
 $equal: $orange-rgb == $orange-oklch;
@@ -457,7 +455,8 @@ interpolation] for specific color functions:
 
 [but *not* in interpolation]: https://github.com/w3c/csswg-drafts/issues/9484
 
-* All channels of the `rgb()` and `rgba()` functions.
+* All channels of the `rgb()` function.
+* The lower bound of the saturation channel of the `hsl()` function.
 * The lightness channel of the `lab()`, `lch()`, `oklab()`, and `oklch()`
   functions.
 * The lower bound of the chroma channel of the `lch()` and `oklch()` functions.
@@ -474,21 +473,27 @@ allow the internal representation of these colors to go out-of-gamut.
 The question remains as to how to handle cases that don't directly correspond to
 CSS, such as the `color.change()` function. Because out-of-gamut clamped
 channels are meaningful in CSS, we've chosen the design principle of preserving
-them in all situations where clamping isn't specifically mandated by CSS. In
-addition, to ensure that that the colors represent the same values in CSS that
-they do in Sass, they'll be serialized to special formats that preserves their
-out-of-gamut values:
+them in all situations where clamping isn't specifically mandated by CSS, or in
+the `color.adjust()` function to preserve historical behavior.
+
+In addition, to ensure that that the colors represent the same values in CSS
+that they do in Sass, they'll be serialized to special formats that preserves
+their out-of-gamut values:
 
 * Out-of-gamut RGB colors are serialized to `hsl()`, the lightness channel and
   saturation upper bound of which per spec are not clamped at parse-time
   (although in practice browsers do clamp them at time of writing). This ensures
   that older browsers will still handle these colors somewhat correctly while
-  preserving the unclamped value for modern browsers (once they work per spec).
+  preserving the unclamped value for modern browsers (once they're
+  standard-compliant).
 
 * Out-of-gamut Lab, LCH, OKLab, and OKLCH colors are serialized to `color-mix(in
   ..., color(xyz ...) 100%, black)` to preserve both the original color space
   and the unclamped value in conformant browsers.
 
+The Sass specification is intentionally flexible to allow these output formats
+to change over time in response to evolving specification and browser behaviors.
+
 #### Conventions for Channels and Space Names
 
 This proposal uses different conventions for referring to the names of color
@@ -530,12 +535,12 @@ and mapping in Sass color functions:
 
 * Every color function returns a color in the same space as the original color,
   no matter what space was used for transformations. The only exception is
-  `color.to-space()`, which can be used for manual space conversion. Functions
-  that accept two colors (e.g. `color.mix()`) return a color in the same space
-  as the first color argument.
+  `color.to-space()`, which is used for explicit space conversion. Functions
+  that accept two colors (such as `color.mix()`) return a color in the same
+  space as the first color argument.
 
-* No color function performs gamut-mapping on out-of-gamut channels, except
-  `color.to-gamut()`, which can be used for manual gamut-mapping.
+* No color function performs gamut-mapping on out-of-gamut channels except
+  `color.to-gamut()`, which is used for explicit gamut-mapping.
 
 #### Gamut Mapping
 
@@ -545,7 +550,7 @@ on a given display. Moreover, there is still active discussion among the CSS
 working group and browser vendors about what the best gamut mapping algorithm
 is, with the currently-specified algorithm widely considered to be sub-optimal.
 As such, we want to avoid baking it in as the default for Sass such that any
-change would require a deprecation period.
+change would require a deprecation period followed by a breaking change.
 
 At the same time, we expect gamut-mapping to be very useful for Sass authors
 working with wide-gamut color spaces, enough so that we want it to be available
@@ -594,7 +599,7 @@ reference as we developed this proposal.
 
 A *color* is an object with several parts:
 
-* A *color space* that is either a [known color space] or an unquoted string.
+* A *color space* that is a [known color space].
 
 * An ordered list of *channel*s, each one containing a [double] or the special
   value `none`.
@@ -611,6 +616,7 @@ A *color* is an object with several parts:
 ### Legacy Color
 
 [legacy color]: #legacy-color
+[legacy colors]: #legacy-color
 
 > Both Sass and CSS have similar legacy behavior that relies on all colors
 > being interchangeable as part of a shared `srgb` color space. While the new
@@ -633,7 +639,7 @@ Legacy colors that have [missing] components are
 
 For determining *equality* between two colors `color1` and `color2`:
 
-* If both colors are [legacy colors](#legacy-color) in different spaces, return
+* If both colors are [legacy colors] in different spaces, return
   `color.to-space(color1, rgb) == color.to-space(color2, rgb)`.
 
 * If the colors are not in the same color space, return false.
@@ -651,134 +657,126 @@ For determining *equality* between two colors `color1` and `color2`:
 ### Known Color Space
 
 Each known color space has a name and an ordered list of associated channels.
-Each channel has a name, and an associated unit where allowed. Space and
-channel names match unquoted strings, ignoring case. They are always emitted as
-unquoted lowercase strings by inspection functions.
+Each channel has a name, and an optional associated unit. Color space names are
+matched case-insensitively and referred to using unquoted strings, and are
+always emitted as unquoted lowercase strings by inspection functions. Color
+channel names are matched case-sensitively and referred to using quoted strings.
 
 Values outside a *bounded gamut* range (including infinity or negative infinity)
 are valid but are considered *out of gamut* for the given color space. They
 remain un-clamped unless the gamut is specifically marked as "clamped", in which
 case they're clamped *only* when constructing the color from its global
-constructor function. If the channel is bounded, or has a percentage mapping,
-then the channel is considered *scalable*.
+constructor function or `color.adjust()`.
 
-Some color spaces use a *polar angle* value for the `hue` channel. Polar-angle
-hues represent an angle position around a given hue wheel, using a CSS `<angle>`
-dimension or number (interpreted as a `deg` value), and are serialized with
-`deg` units.
+Some color spaces include a *polar angle* channel (so far exclusively called
+`hue`). Polar-angle hues represent an angle position around a given hue wheel,
+using a CSS `<angle>` dimension or number (interpreted as a `deg` value when no
+units are passed), and are serialized with `deg` units. Polar angle channels are
+normalized using modulo to fall within their conventional range. Any channel
+that is not polar-angle is considered *scalable*.
 
-Colors specified using a CSS color keyword or the hex notation are converted
-to `rgb` and serialized as part of the `rgb` color space.
+All channels have a conventional range of values, whose bounds are referred to
+as the channel's *lower bound* and *upper bound* (although for unbounded
+channels these bounds aren't enforced anywhere). For scalable channels,
+percentages provided by the user are converted to match these bounds. `0%`
+always refers to the value 0, `100%` always refers to the upper bound of the
+range, and `-100%` always refers to the negative value of the upper bound of the
+range. (In many cases this is considered outside the conventional scope of the
+color space, but the `a` and `b` channels do conventionally cover negative
+values as well.)
+
+Colors specified using a CSS color keyword or the hex notation are treated as
+`rgb` colors.
 
 The known color spaces and their channels are:
 
 * `rgb` (RGB, legacy):
   * `red`, `green`, `blue`:
     * gamut: bounded, clamped
-    * number: `[0,255]`
+    * range: `[0,255]`
 
       > Percentages `[0%,100%]` map to the `[0,255]` range.
 
 * `hwb` (RGB, legacy):
-  * `hue`:
+  * `hue` (polar angle):
     * associated unit: `deg`
-    * degrees: polar angle
+    * range: `[0,360]`
   * `whiteness`, `blackness`:
     * associated unit: `%`
     * gamut: bounded
-    * percentage: `[0%,100%]`
+    * range: `[0,100]`
 
 * `hsl` (RGB, legacy):
-  * `hue`:
+  * `hue` (polar angle):
     * associated unit: `deg`
-    * degrees: polar angle
+    * range: `[0,360]`
   * `saturation`:
     * gamut: bounded, clamped (lower bound only)
     * associated unit: `%`
-    * percentage: `[0%,100%]`
+    * range: `[0,100]`
   * `lightness`:
     * gamut: bounded
     * associated unit: `%`
-    * percentage: `[0%,100%]`
+    * range: `[0,100]`
 
 * `srgb`, `srgb-linear`, `display-p3`, `a98-rgb`, `prophoto-rgb`,
   `rec2020` (RGB):
   * `red`, `green`, `blue`:
     * gamut: bounded
-    * number: `[0,1]`
-
-      > Percentages `[0%,100%]` map to the `[0,1]` range.
+    * range: `[0,1]`
 
 * `xyz`, `xyz-d50`, `xyz-d65`:
   * `x`, `y`, `z`:
     * gamut: un-bounded
-    * number: `[0,1]`
-
-      > Percentages `[0%,100%]` map to the `[0,1]` range.
+    * range: `[0,1]`
 
 * `lab`:
   * `lightness`:
     * gamut: un-bounded, clamped
     * associated unit: `%`
-    * number: `[0,100]`
-
-      > Percentages `[0%,100%]` map to the `[0,100]` range.
+    * range: `[0,100]`
 
   * `a`, `b`:
     * gamut: un-bounded
-    * number: `[-125,125]`
-
-      > Percentages `[-100%,100%]` map to the `[-125,125]` range.
+    * range: `[-125,125]`
 
 * `lch`:
   * `lightness`:
     * gamut: un-bounded, clamped
     * associated unit: `%`
-    * number: `[0,100]`
-
-      > Percentages `[0%,100%]` map to the `[0,100]` range.
+    * range: `[0,100]`
 
   * `chroma`:
     * gamut: un-bounded, clamped (lower bound only)
-    * number: `[0,150]`
+    * range: `[0,150]`
 
-      > Percentages `[0%,100%]` map to the `[0,150]` range.
-
-  * `hue`:
+  * `hue` (polar angle):
     * associated unit: `deg`
-    * degrees: polar angle
+    * range: `[0,360]`
 
 * `oklab`:
   * `lightness`:
     * gamut: un-bounded, clamped
     * associated unit: `%`
-    * number: `[0,1]`
-
-      > Percentages `[0%,100%]` map to the `[0,1]` range.
+    * range: `[0,1]`
 
   * `a`, `b`:
     * gamut: un-bounded
-    * number: `[-0.4,0.4]`
-
-      > Percentages `[-100%,100%]` map to the `[-0.4,0.4]` range.
+    * range: `[-0.4,0.4]`
 
 * `oklch`:
   * `lightness`:
     * gamut: un-bounded, clamped
     * associated unit: `%`
-    * number: `[0,1]`
-
-      > Percentages `[0%,100%]` map to the `[0,1]` range.
+    * range: `[0,1]`
 
   * `chroma`:
     * gamut: un-bounded, clamped (lower bound only)
-    * number: `[0,0.4]`
+    * range: `[0,0.4]`
 
-      > Percentages `[0%,100%]` map to the `[0,0.4]` range.
-
-  * `hue`:
+  * `hue` (polar angle):
     * associated unit: `deg`
-    * degrees: polar angle
+    * range: `[0,360]`
 
 If a color with negative saturation or chroma would be created in the `hsl`,
 `lch`, or `oklch` spaces by any means, instead create a color with the absolute
@@ -792,9 +790,12 @@ value of that saturation or chroma and the hue rotated by 180deg.
 > Note that this conversion happens *after* any clipping, so `hsl(0deg -50%
 > 50%)` returns `hsl(0deg 0% 50%)`, not `hsl(180deg 50% 50%)`.
 
+The `xyz-d65` space is an alias for `xyz`, and implementations should report the
+space name as `xyz` even if it was originally written as `xyz-d65`.
+
 ### Predefined Color Spaces
 
-> 'Predefined color spaces' can be described using the `color()` function.
+> "Predefined color spaces" can be described using the `color()` function.
 
 The *predefined RGB spaces* are:
 
@@ -813,11 +814,12 @@ The *predefined XYZ spaces* are:
 
 ### Missing Components
 
-In some cases, a color can have one or more missing components (channel or
-alpha values). Missing components are represented by the special value `none`.
-When interpolating between colors, the missing component is replaced by the
-value of that same component in the other color. In all other cases, the
-missing value is treated as `0`.
+In some cases, a color can have one or more missing components (channel or alpha
+values). Unless explicitly specified otherwise, missing components are treated
+as though they had the value `0`.
+
+> Some situations where missing components are treated specially include
+> interpolation, the `==` operator, and color space conversion.
 
 For the sake of [interpolating] between colors with missing components, the
 following *analogous components* are defined by [CSS Color Level 4][color-4]:
@@ -835,8 +837,8 @@ following *analogous components* are defined by [CSS Color Level 4][color-4]:
 
 ### Powerless Components
 
-In some color spaces, it is possible for a channel value to become 'powerless'
-in certain circumstances.
+In some color spaces, it is possible for a channel value to be considered
+*powerless* in certain circumstances.
 
 * `hsl`:
 
@@ -851,6 +853,9 @@ in certain circumstances.
 
   * If the `chroma` value is 0%, then the `hue` channel is powerless.
 
+> In some circumstances, conversion between color spaces will mark powerless
+> components in the output as missing.
+
 ### Color Interpolation Method
 
 A *color interpolation method* is a space-separated list of unquoted strings,
@@ -873,6 +878,8 @@ angle hue channel. A *RectangularColorSpace* is the name of any other
 is the result of [looking up a known color space] named by either the
 `PolarColorSpace` or `RectangularColorSpace` productions.
 
+`ColorInterpolationMethod` is case-insensitive.
+
 > Different color interpolation methods provide different advantages. For that
 > reason, individual color procedures and functions can establish their own
 > color interpolation defaults, or provide a syntax for authors to explicitly
@@ -889,8 +896,6 @@ is the result of [looking up a known color space] named by either the
 
 To serialize a non-legacy color `color`:
 
-* Let `space-name` be an unquoted lowercase string of `color`'s space name.
-
 * If `color` has a clamped channel whose value is out-of-bounds, emit a CSS
   [`<color>`] expression that evaluates to `color`'s value, then return.
 
@@ -914,39 +919,35 @@ To serialize a non-legacy color `color`:
   > implementations have enough flexibility within that to target the shifting
   > landscape of what browsers actually support.
 
-* Let `known-space` be the result of [looking up a known color space] with a
-  `name` of `space-name`.
-
-* Let `components` be an empty space-separated list.
+* Let `components` be an empty string.
 
 * For each `channel` in `color`'s channels:
 
-  * If `channel` is missing a value, set `channel` to the unquoted string "none".
+  * If `channel` contains the special value `none`, append the unquoted string
+    "none" to `components`.
 
   * Otherwise:
 
-    * Let `unit` be the unit associated with `channel` in `known-space`, if
-      defined, and `null` otherwise.
+    * Let `channel-number` be a number with the same value as `channel` and unit
+      given by `channel`'s associated unit, if it has one.
 
-    * If `unit` is not null, append `unit` units to the `channel` value.
+    * Append the result of serializing `channel-number` to `components`.
 
-  * Append `channel` as the last element of `components`.
+  * If `channel` isn't the last channel, append a space to `components`.
 
-* Let `alpha` be the alpha value of `color`.
+* If `color`'s alpha value isn't `1`, append the unquoted string " / " followed
+  by the result of serializing a unitless number whose value is `color`'s alpha
+  value to `components`.
 
-* If `alpha != 1`:
+* Let `space-name` be `color`'s space name as an unquoted lowercase string.
 
-  * Set `components` to the result of appending " / " and then the values of
-    `alpha` to the end of `components`.
-
-* If `color` has a [known color space] that is not a [predefined color space]:
+* If `color`'s space is not a [predefined color space], emit `space-name`
+  followed by "(", `components`, and then ")".
 
   > Since a [predefined color space] is defined as a [known color space] that
   > uses the `color()` syntax, this is a reliable way to get the remaining
   > known color spaces that provide their own function syntax.
 
-  * Emit `space-name` followed by "(", `components`, and then ")".
-
 * Otherwise, emit "color(", followed by `space-name`, " ", `components`, and
   then ")".
 
@@ -966,16 +967,13 @@ To serialize an out-of-gamut color `color` in the `rgb` space:
 ### Looking Up a Known Color Space
 
 This procedure accepts a `name`, and attempts to look up a [known color space]
-with a matching name. It throws an error if `name` is not a valid color space
-name, and either returns the known color space, or `null` if no color space is
-matched.
+with a matching name. It returns the color space named `name`, or throws an
+error if `name` is not the name of a known color space.
 
 * If `name` is not an unquoted string, throw an error.
 
-* Let `lower-name` be the result of calling `string.to-lower-case(name)`.
-
-* If `lower-name` is the name of a [known color space], return the matching
-  [known color space].
+* If `name`'s value is case-insensitively equal to the name of a [known color
+  space], return that color space.
 
 * Otherwise, throw an error.
 
@@ -987,16 +985,18 @@ matched.
 ### Converting a Color
 
 Colors can be converted from one [known color space] to another. This procedure
-accepts a color `origin-color`, and a [known color space] `target-space`, and
-returns a color `color`.
+accepts a color `origin-color`, and `target-space` which may be either a [known
+color space] or a SassScript value, and returns a color `color` in
+`target-space`.
 
 > Since the individual CSS color conversion algorithms don't explicitly handle
-> the process of 'carrying over' missing values on analogous channels, we have
+> the process of "carrying over" missing values on analogous channels, we have
 > to handle that here.
 
-* Let `origin-space` be `origin-color`'s color space.
+* If `target-space` is a SassScript value, set it to the result of [looking up a
+  known color space] named `target-space`.
 
-* If `origin-space == target-space` return `origin-color`.
+* If `origin-color`'s space is already `target-space`, return `origin-color`.
 
   > CSS doesn't perform conversions unless they are required.
 
@@ -1010,8 +1010,13 @@ returns a color `color`.
   * If `target-space` has an [analogous component][missing] to `channel`, set
     the analogous component in `color` to `none`.
 
-* If any `channel` of `color` is [powerless] and not already [missing], set
-  `channel` to the special value `none`.
+* If `target-space` is not a [legacy color] space and any `channel`s of `color`
+  are [powerless] and not already [missing], set those channels to the special
+  value `none`.
+
+  > Don't introduce missing colors to legacy spaces because if users are
+  > converting to legacy spaces they're likely targeting older browsers which
+  > will choke on `none`.
 
 * Return `color`.
 
@@ -1055,28 +1060,27 @@ The individual conversion algorithms are:
 
 ### Gamut Mapping
 
-> Some [known color space]s describe limited color gamuts. If a color is 'out of
-> gamut' for a particular space (most often because of conversion from a
-> larger-gamut color-space), it can be useful to 'map' that color to the nearest
-> available 'in-gamut' color. Gamut mapping is the process of finding an
-> in-gamut color with the least objectionable change in visual appearance.
+> Some [known color space]s describe limited color gamuts. If a color is "out of
+> gamut" for a particular space (most often because of conversion from a
+> larger-gamut color-space), it can be useful to "map" that color to the nearest
+> available "in-gamut" color. Gamut mapping is the process of finding an
+> in-gamut color with the least objectionable change in visual appearance, which
+> is to some degree inherently contextual and subjective.
 
-Gamut mapping color `origin`, a [known color space] `destination`, and an
-unquoted string `method`. It returns a color in `origin`'s color space.
-
-* Let `origin-space` be `origin`'s color space.
-
-* If either `origin-space` or `destination` is not a [known color space], throw
-  an error.
+Gamut mapping takes a color `origin`, a [known color space] `destination`, and
+an unquoted string `method`. It returns a color in `origin`'s color space.
 
 * Let `color` be the result of [converting] `origin` into `destination`.
 
-* If `method` is not one of the methods defined below, throw an error.
+* If `method` is not case-insensitively equal to one of the methods defined
+  below, throw an error.
+
+* If `color.is-in-gamut(color)`, return `origin`.
 
 * Let `mapped` be the result of running the method defined below whose name
-  matches `method`. If no such method matches, throw an error.
+  matches `method`.
 
-* Return the result of [converting] `mapped` into `origin-space`.
+* Return the result of [converting] `mapped` into `origin`'s space.
 
 #### `local-minde`
 
@@ -1097,9 +1101,9 @@ results, but it can be useful to match the current behavior of browsers.
 
 * Let `new-color` be a copy of `color`.
 
-* For each `channel` in `destination`:
+* For each `channel` in `new-color`'s channels:
 
-  * If `channel` is bounded, set `new-color`'s `channel` value to the result of
+  * If `channel` is bounded and not [missing], set its value to the result of
     clamping the original value within `channel`'s minimum and maximum values.
 
 * Return `new-color`.
@@ -1113,8 +1117,7 @@ three values: a color space, a list of channel values, and an alpha value.
 
 > This supports both the space-specific color formats like `hsl()` and `rgb()`,
 > where the space is determined by the function, as well as the syntax of
-> `color()`, where the space is included as one of the input arguments (and may
-> be a user-defined space).
+> `color()`, where the space is included as one of the input arguments.
 
 The procedure is:
 
@@ -1122,7 +1125,7 @@ The procedure is:
   the value of `input`.
 
 * If `input` is a bracketed list, or a list with a separator other than
-  'slash' or 'space', throw an error.
+  slash or space, throw an error.
 
 * If `input` is a slash-separated list:
 
@@ -1152,8 +1155,8 @@ The procedure is:
       > handled correctly after the final expresssion is fully converted to a
       > string due to legacy `/` behavior.
 
-    * If either item in `split-last` can be coerced to a number, replace
-      the current value of the item with the resulting number value.
+    * If either item in `split-last` can be parsed as a number, replace the
+      current value of the item with the resulting number value.
 
     * Let `alpha` be the second element in `split-last`, and append the first
       element of `split-last` to `components`.
@@ -1177,7 +1180,7 @@ The procedure is:
   * If `components` is not an unbracketed space-separated list, throw an error.
 
   * If the first element of `components` is an unquoted string which is
-    case-insensitively equal to `from`, return an unquoted string with the
+    case-insensitively equal to "from", return an unquoted string with the
     value of `input`.
 
   * If `space` is null:
@@ -1200,16 +1203,14 @@ The procedure is:
 
   * Otherwise, let `channels` be the value of `components`.
 
-  * Let `expected` be the number of channels in `space`.
-
   * If any element of `channels` is not either a number, a special variable
     string, a [special number], or an unquoted string that's
-    case-insensitively equal to 'none', throw an error.
+    case-insensitively equal to "none", throw an error.
 
 * If `alpha` is null, let `alpha` be `1`.
 
 * Otherwise, If `alpha` is neither a [special number] nor an unquoted string
-  that's case-insensitively equal to 'none':
+  that's case-insensitively equal to "none":
 
   * If `alpha` is not a number, throw an error.
 
@@ -1224,7 +1225,7 @@ The procedure is:
   * If `space` is a [legacy color] space:
 
     * Let `comma-list` be the result of calling
-      `list.append(channels, alpha, 'comma')`.
+      `list.append(channels, alpha, "comma")`.
 
     * Return an unquoted string with the value of `comma-list`.
 
@@ -1233,14 +1234,14 @@ The procedure is:
     > Doing this late in the process allows us to throw any obvious syntax
     > errors, even for colors that can't be fully resolved during compilation.
 
-* If the length of `channels` is not equal to `expected`, throw an error.
+* If the length of `channels` is not 3, throw an error.
 
-    > Once special values have been handled, any colors remaining should have
-    > exactly the expected number of channels.
+  > Once special values have been handled, any colors remaining should have
+  > exactly the expected number of channels.
 
 * Set `channels` to the result of [normalizing] `channels` in `space`.
 
-* Let `space-name` be a lowercase unquoted string of the `space` name.
+* Let `space-name` be a lowercase unquoted string of `space`'s name.
 
 * Return `space-name`, `channels` channels, and `alpha` alpha value.
 
@@ -1258,54 +1259,46 @@ a number relative to the range `[0,max]` without clamping.
 
 * If `number` has units other than `%`, throw an error.
 
-* If `number` has the unit `%`, set `number` to `number * max / 100%`.
+* Otherwise, if `number` has the unit `%`, return `number * max / 100%`.
 
-* Return `number`.
+* Otherwise, return `number`.
 
 ### Validating a Color Channel
 
 [validating]: #validating-a-color-channel
 
-This process accepts a SassScript value `channel` to validate, a [known color
-space] `space` to validate against, and the `key` name of the channel. It
+This process accepts a SassScript value `value` to validate, a [known color
+space] `space` to validate against, and `channel` a channel in `space`. It
 throws an error if the channel is invalid for the color space, or returns a
 normalized channel value otherwise.
 
-* If `channel` is not a number or an unquoted string that's case-insensitively
-  equal to 'none', throw an error.
+* If `value` is not a number or an unquoted string that's case-insensitively
+  equal to "none", throw an error.
 
-* If `channel == NaN`, throw an error.
-
-* If `channel` is an unquoted string that's case-insensitively equal to 'none',
-  return `channel`.
+* If `value` is an unquoted string that's case-insensitively equal to "none",
+  return `value`.
 
 * Otherwise:
 
-  * Let `valid` be the corresponding channel named `key` defined by the [known
-    color space] `space`.
+  * If `channel` is a polar angle:
 
-  * If `valid` is a polar-angle `hue`:
-
-    * Let `angle` be the result of [converting][number-to-unit] `channel` to
-      `deg` allowing unitless.
+    * Let `angle` be the result of [converting][number-to-unit] `value` to `deg`
+      allowing unitless.
 
     * Return the result of `angle % 360deg`.
 
-  * Otherwise, if `valid` requires a percentage:
-
-    * If `channel` is a number with units other than `%`, throw an error.
-
-    * Return `channel`.
+  * Let `min` and `max` be the upper and lower bounds of `channel`'s range,
+    respectively.
 
   * Otherwise, set `channel` to the result of [percent-converting] `channel`
-    with a `min` and `max` defined by the `valid` channel range.
+    with `min` and `max`.
 
   * If this was (transitively) invoked from the global [`rgb()`, `lab()`,
-    `lch()`, `oklab()`, `oklch()`, or `color()`] function and `valid` is a
-    clamped channel, return the result of clamping `channel` to its native
-    range.
+    `lch()`, `oklab()`, `oklch()`, or `color()`] functions and `valid` is a
+    clamped channel, return the result of clamping `value` within `min` and
+    `max`.
 
-  * Return `channel`.
+  * Return `value`.
 
 [number-to-unit]: https://github.com/sass/sass/blob/main/spec/types/number.md#converting-a-number-to-a-unit
 
@@ -1313,33 +1306,30 @@ normalized channel value otherwise.
 
 [normalizing]: #normalizing-color-channels
 
-This process accepts a list of `channels` to validate and a [known color space]
+This process accepts a list of `values` to validate and a [known color space]
 `space` to normalize against. It throws an error if any channel is invalid for
 the color space, or returns a normalized list of valid channels otherwise.
 
-* If `channels` is not a list, throw an error.
-
-* If `space` is not a [known color space], throw an error.
+* If `values` is not a list, throw an error.
 
 * Let `normal` be an empty list.
 
-* For each `channel` in `channels`:
+* For each `value` at position `i` in `values`:
 
-  * Let `key` be the name of `channel` in `space`.
+  * Let `channel` be the channel at position `i` in `space`'s channels.
 
-  * Let `valid` be the result of [validating] `channel` as `key` channel in
-    `space`.
+  * Let `valid` be the result of [validating] `value` as `channel` in `space`.
 
   * Append `valid` as the next item in `normal`.
 
 * Let `unitless` be an empty list.
 
-* For each `channel` in `normal`.
+* For each `value` in `normal`.
 
-  * If the value of `channel` is the special value `none`, append `none` as the
+  * If the value of `value` is the special value `none`, append `none` as the
     next item in `unitless`.
 
-  * Otherwise, append the value of `channel` as a [double] without units as the
+  * Otherwise, append the value of `value` as a [double] without units as the
     next item in `unitless`.
 
 * Return `unitless`.
@@ -1349,7 +1339,7 @@ the color space, or returns a normalized list of valid channels otherwise.
 > This procedure is based on the legacy behavior of the `color.mix()` function,
 > but returns a color in the original `color1` color space.
 
-This procedure accepts two legacy colors (`color1` and `color2`), and an
+This procedure accepts two [legacy colors] (`color1` and `color2`), and an
 optional percentage `weight` for `color1` in the mix. It returns a new color
 `mix` that represents the appropriate mix of input colors.
 
@@ -1400,8 +1390,8 @@ optional percentage `weight` for `color1` in the mix. It returns a new color
 
 * Let `alpha` be `alpha1 * weight-scale + alpha2 * (1 - weight-scale)`.
 
-* Let `mix` be a [legacy color] in the `rgb` space, with the given `red`,
-  `green`, and `blue` channels, and `alpha` value.
+* Let `mix` be an `rgb` color with the given `red`, `green`, and `blue`
+  channels, and `alpha` value.
 
 * Return the result of [converting] `mix` into `origin-space`.
 
@@ -1413,13 +1403,9 @@ optional percentage `weight` for `color1` in the mix. It returns a new color
 > [color interpolation](https://www.w3.org/TR/css-color-4/#interpolation)
 > procedures defined in [CSS Color Level 4][color-4].
 
-This procedure accepts two color arguments (`color1` and `color2`), a
-[color interpolation method] `method`, and a percentage `weight` for `color1`
-in the mix. It returns a new color `mix` that represents the appropriate mix of
-input colors.
-
-* If either `color1` or `color2` is not a color in a [known color space], throw
-  an error.
+This procedure accepts two color arguments (`color1` and `color2`), a [color
+interpolation method] `method`, and a percentage `weight` for `color1` in the
+mix. It returns a new color that represents the appropriate mix of input colors.
 
 * Let `origin-space` be `color1`'s color space.
 
@@ -1430,16 +1416,14 @@ input colors.
 
 * If `weight > 1` or `weight < 0`, throw an error.
 
-* If `weight == 0`, return `color2`.
+* If `weight == 0`, return the result of [converting] `color2` into
+  `origin-space`.
 
 * If `weight == 1`, return `color1`.
 
-* Let `space` be the *interpolation color space* specified by the `method`
-  [color interpolation method].
+* Let `space` be the *interpolation color space* specified by `method`.
 
-  > Only known color spaces are allowed as part of a color interpolation method.
-
-* If `space` is a [PolarColorSpace][color-method]:
+* If `space` is a [`PolarColorSpace`][color-method]:
 
   * Let `hue-arc` be the `HueInterpolationMethod` specified in `method`, or
     `shorter` if no hue interpolation is specified.
@@ -1449,34 +1433,35 @@ input colors.
 
 * For each `color` in `color1` and `color2`:
 
-  * If any non-`alpha` `component` of `color` is `none`, set that `component` to
-    the value of the corresponding component in the other color.
-
-    > If both values are `none`, the interpolation result for that component
-    > will also be `none`.
+  * If any non-`alpha` component of `color` is [missing], set that its value to
+    the value of the corresponding component in the other color unless it's
+    missing as well.
 
   * Set `color` to the result of [premultiplying] `color`.
 
-  * If `color`'s `alpha` component is `none`, set it to the value of the `alpha`
-    component in the other color.
+  * If `color`'s `alpha` component is [missing], set its value to the value of
+    the `alpha` component in the other color unless it's missing as well.
 
     > This is resolved after premultiplying, because premultiplying has special
     > handling for a missing `alpha` component.
 
-* Let `mix` be a new color in the color space `space`, with `none` for all
-  channel and alpha values.
+* Let `mix` be a new color in the color space `space`, with all channel and
+  alpha values initially [missing].
 
 * For each `channel` of `mix`:
 
-  * Let `channel1` and `channel2` be the corresponding channel values in
+  * If the corresponding channels of `color1` and `color2` are missing, continue
+    to the next channel.
+
+  * Let `value1` and `value2` be the corresponding channel values in
     `color1` and `color2` respectively.
 
-  * If `channel` has a polar angle value, set `channel1` and `channel2`
+  * If `channel` has a polar angle value, set `value1` and `value2`
     respectively to the results of [hue interpolation][hue-method] with
-    `channel1` as `hue1`, `channel2` as `hue2`, using the `hue-arc` method.
+    `value1` as `hue1`, `value2` as `hue2`, using the `hue-arc` method.
 
-  * Set `channel` to the result of calculating
-    `(channel1 * weight) + (channel2 * (1 - weight))`.
+  * Set `channel` to the result of calculating `(value1 * weight) + (value2 *
+    (1 - weight))`.
 
     > Channel rounding has been removed, since it is a lossy transform.
 
@@ -1504,13 +1489,11 @@ premultiplied channels.
 
 * Otherwise, for each `channel` in `color`:
 
-  * If the `channel` value is `none`, or if `channel` is a polar-angle `hue`,
-    keep the original value of `channel`.
+  * If the `channel` is not [missing] and `channel` is not a polar angle, set
+    `channel`'s value to the result of multiplying `channel`'s value by
+    `color`'s `alpha` value.
 
-  * Otherwise, set `channel` to the result of multiplying the `channel` value
-    by the `alpha` value.
-
-* Return the resulting `color` with premultiplied channels.
+* Return the resulting `color`.
 
 The same process can be run in reverse, to **un-premultiply** the channels of a
 given `color`:
@@ -1519,44 +1502,40 @@ given `color`:
 
 * Otherwise, for each `channel` in `color`:
 
-  * If the `channel` value is `none`, or if `channel` is a polar-angle `hue`,
-    keep the original value of `channel`.
+  * If the `channel` is not [missing] and `channel` is a polar angle, set
+    `channel`'s value to the result of dividing `channel`'s value by `color`'s
+    `alpha` value.
 
-  * Otherwise, set `channel` to the result of dividing the premultiplied
-    `channel` value by the `alpha` value.
-
-* Return the resulting `color` with un-premultiplied channels.
+* Return the resulting `color`.
 
 #### Hue Interpolation
 
-> When interpolating between polar-angle hue channels, there are multiple
-> 'directions' the interpolation could move, following different logical rules.
+> When interpolating between polar-angle channels, there are multiple
+> "directions" the interpolation could move, following different logical rules.
 
-This process accepts two hue angles (`hue1` and `hue2`), and returns both hues
-adjusted according to the given `method`. When no hue interpolation `method` is
-specified, the default is `shorter`.
+This process accepts two angles (`hue1` and `hue2`), and returns both angles
+adjusted according to an optional [hue interpolation method] `method`, which
+defaults to `shorter`.
 
-The process for each [hue interpolation method][hue-interpolation] is defined
-in [CSS Color Level 4][color-4].
+[hue interpolation method]: https://www.w3.org/TR/css-color-4/#hue-interpolation
 
-* [shorter](https://www.w3.org/TR/css-color-4/#shorter)
+The process for each hue interpolation method is defined in [CSS Color Level
+4][color-4] (matched case-insensitively):
 
-* [longer](https://www.w3.org/TR/css-color-4/#hue-longer)
+* [`shorter`](https://www.w3.org/TR/css-color-4/#shorter)
 
-* [increasing](https://www.w3.org/TR/css-color-4/#increasing)
+* [`longer`](https://www.w3.org/TR/css-color-4/#hue-longer)
 
-* [decreasing](https://www.w3.org/TR/css-color-4/#decreasing)
+* [`increasing`](https://www.w3.org/TR/css-color-4/#increasing)
 
-* [specified](https://www.w3.org/TR/css-color-4/#hue-specified)
-
-[hue-interpolation]: https://www.w3.org/TR/css-color-4/#hue-interpolation
+* [`decreasing`](https://www.w3.org/TR/css-color-4/#decreasing)
 
 ### Scaling a Number
 
 This algorithm takes a number `number`, a value `factor`, a number `max`, and an
-optional number `min`. It's written "scale `<number>` by `<factor>` with a `max`
-of `<max>` and a `min` of `<min>`". It returns a number with the same units as
-`number`.
+optional number `min` which defaults to 0. It's written "scale `<number>` by
+`<factor>` with a `max` of `<max>` and a `min` of `<min>`". It returns a number
+with the same units as `number`.
 
 > Note that this no longer assumes the original `number` is in a range of `min`
 > to `max`. We now allow scaling up negative numbers, and scaling down numbers
@@ -1566,8 +1545,6 @@ of `<max>` and a `min` of `<min>`". It returns a number with the same units as
 * If `factor` isn't a number with unit `%` between `-100%` and `100%`
   (inclusive), throw an error.
 
-* If `min` is not specified, set `min` to 0.
-
 * If `factor > 0%`:
 
   * If `number > max`, return `number`.
@@ -1576,7 +1553,7 @@ of `<max>` and a `min` of `<min>`". It returns a number with the same units as
 
 * Otherwise:
 
-  * If `number < 0`, return `number`.
+  * If `number < min`, return `number`.
 
   * Otherwise, return `number + (number - min) * factor / 100%`.
 
@@ -1592,7 +1569,7 @@ space($color)
 
 * If `$color` is not a color, throw an error.
 
-* Return an unquoted string with the name of `$color`s color space.
+* Return the name of `$color`s color space as an unquoted lowercase string.
 
 ### `color.to-space()`
 
@@ -1602,15 +1579,7 @@ to-space($color, $space)
 
 * If `$color` is not a color, throw an error.
 
-* Let `known-space` be the result of [looking up a known color space] named
-  `$space`.
-
-* Let `known-origin` be `$color`'s space.
-
-* If `known-origin == known-space`, return `$color`.
-
-* Let `converted` be the result of [converting] the `origin-color` `$color` to
-  the `target-space` `known-space`.
+* Let `converted` be the result of [converting] `$color` to `$space`.
 
 * If `converted` is a [legacy color]:
 
@@ -1639,29 +1608,13 @@ is-powerless($color, $channel, $space: null)
 
 * If `$channel` is not a quoted string, throw an error.
 
-* If `$space` is null:
+* Let `color` be `$color` if `$space` is null, and the result of [converting]
+  `$color` to `$space` otherwise.
 
-  * Let `color` be `$color`
+* Let `channel` be the channel in `color` (case sensitively) named `$channel`.
+  Throw an error if no such channel exists.
 
-  * Let `origin-space` be the result of calling `color.space($color)`.
-
-  * Let `space` be the result of [looking up a known color space] named
-    `origin-space`.
-
-* Otherwise:
-
-  * Let `color` be the result of calling `color.to-space($color, $space)`.
-
-  * Let `space` be the result of [looking up a known color space] named
-    `$space`.
-
-* Let `channels` be a list of the `color`'s channels.
-
-* If `$channel` is not the (case sensitive) name of a channel in `channels`,
-  throw an error.
-
-* Return `true` if the channel `$channel` is [powerless] in `color`,
-  otherwise return `false`.
+* Return `true` if `channel` is [powerless] in `color`, or `false` otherwise.
 
 ### `color.is-in-gamut()`
 
@@ -1671,16 +1624,11 @@ is-in-gamut($color, $space: null)
 
 * If `$color` is not a color, throw an error.
 
-* Let `space-name` be the result of calling `color.space($color)` if `$space`
-  is null, and the value of `$space` otherwise.
+* Let `color` be `$color` if `$space` is null, and the result of [converting]
+  `$color` to `$space` otherwise.
 
-* Let `space` be the result of [looking up a known color space] named
-  `space-name`.
-
-* Let `color` be the result of calling `color.to-space($color, space)`.
-
-* For all bounded channels in `space`, if the associated channel value in
-  `$color` is fuzzy greater-than the bounded maximum, or fuzzy less-than the
+* For all bounded channels in `color`'s space, if the associated channel value
+  in `$color` is fuzzy greater-than the bounded maximum or fuzzy less-than the
   bounded minimum, return `false`.
 
 * Otherwise, return `true`.
@@ -1693,20 +1641,13 @@ to-gamut($color, $space: null, $method: null)
 
 * If `$color` is not a color, throw an error.
 
-* If `$method` is not an unquoted string whose value is either `local-minde` or
-  `clip`, throw an error.
+* If `$method` is not an unquoted string whose value is (case sensitively)
+  either `local-minde` or `clip`, throw an error.
 
-* If `$space` is null:
+* Otherwise, let `destination` be the result of [looking up a known color space]
+  named `$space` if it's not null, or `$color`'s space otherwise.
 
-  * Let `origin-space` be the result of calling `color.space($color)`.
-
-  * Let `target-space` be the result of [looking up a known color space] named
-    `origin-space`.
-
-* Otherwise, let `target-space` be the result of [looking up a known color
-  space] named `$space`.
-
-* Return the result of [gamut mapping] `$color` with destination `target-space`
+* Return the result of [gamut mapping] `$color` with destination `destination`
   and method `$method`.
 
 [gamut mapping]: #gamut-mapping
@@ -1725,26 +1666,21 @@ channel($color, $channel, $space: null)
 
 * If `$channel` is not a quoted string, throw an error.
 
-* If `$channel == 'alpha'`, let `value` be the alpha value of `$color`.
+* If `$channel == "alpha"`, return `$color`'s `alpha` value.
 
-* Otherwise:
+* Let `color` be `$color` if `$space` is null, and the result of [converting]
+  `$color` to `$space` otherwise.
 
-  * Let `color` be `$color` if `$space` is null, and the result of calling
-    `color.to-space($color, $space)` otherwise.
+* Let `channel` be the channel in `color` (case sensitively) named `$channel`.
+  Throw an error if no such channel exists.
 
-  * Let `channel` be the channel in `color`'s space (case sensitively) named
-    `$channel`. Throw an error if no such channel exists.
+* Let `value` be `channel`'s value in `color`, or `0` if the channel's value
+  is [missing].
 
-  * Let `value` be `channel`'s value in `color`, or `0` if the channel's value
-    is missing.
+* If `channel`'s associated unit is `%`, return `value * 100` divided by the
+  maximum of `channel`'s gamut range with unit `%`.
 
-  * Let `unit` be the unit associated with `channel` in `color`'s space, if
-    defined, and `null` otherwise.
-
-* If `unit` is `%`, return `value * 100` divided by the maximum of
-  `channel`'s gamut range with unit `%`.
-
-* Otherwise, if `unit` is not null, return `value` with unit `unit`.
+* Otherwise, if `channel` has an associated unit, return `value` with that unit.
 
 * Otherwise, return `value` as a unitless number.
 
@@ -1758,16 +1694,13 @@ is-missing($color, $channel)
 
 * If `$channel` is not a quoted string, throw an error.
 
-* If `$channel == alpha`, let `value` be the alpha value of `$color`.
+* If `$channel == "alpha"`, return `true` if `$color`'s alpha value is missing
+  and `false` otherwise.
 
-* Otherwise:
+* Let `channel` be the channel in `$color` (case sensitively) named `$channel`.
+  Throw an error if no such channel exists.
 
-  * If `$channel` is not the (case-sensitive) name of a channel in `$color`,
-    throw an error.
-
-  * Let `value` be the channel value named `channel` in `color`.
-
-* Return `true` if `value == null`, and `false` otherwise.
+* Return `true` if `channel` is missing in `$color`, and `false` otherwise.
 
 ### `color.same()`
 
@@ -1790,8 +1723,8 @@ same($color1, $color2)
   > 0.4401656621 none)`, which are *not* equivalent if we convert missing
   > channels to zero after XYZ conversion.
 
-* Let `xyz1` and `xyz2` be the result of [converting] `color1` and `color2` into
-  `xyz` color space, respectively.
+* Let `xyz1` and `xyz2` be the result of [converting] `color1` and `color2` to
+  `xyz`, respectively.
 
 * Return `xyz1 == xyz2`.
 
@@ -1799,7 +1732,7 @@ same($color1, $color2)
 
 ### `color.hwb()`
 
-These functions are now deprecated. Authors should use global `hwb()` instead.
+This function is now deprecated. Authors should use global `hwb()` instead.
 
 * ```
   hwb($channels)
@@ -1850,28 +1783,20 @@ This function is also available as a global function named `change-color()`.
 
 * If `$color` is not a color, throw an error.
 
-* If any item in `$args` is not a keyword argument, throw an error.
+* If `$args` contains any positional arguments, throw an error.
 
-* Let `color` be the value of `$color`.
+* Let `space` be the argument named `$space` in `$args`, or null if it doesn't
+  have one.
 
-* Let `origin-space` be `color`'s space.
-
-* If the keyword argument `$space` is specified in `$args`:
-
-  * Let `known-space` be the result [looking up a known color space] named
-    `$space`.
-
-  * If `space != origin-space`, set `color` to the result of calling
-    `color.to-space(color, space)`.
-
-* Otherwise, let `known-space` be `origin-space`.
+* Let `color` be `$color` if `space` is null, and the result of [converting]
+  `color` to `space` otherwise.
 
 * Let `alpha` be `color`'s alpha property.
 
 * If the keyword argument `$alpha` is specified in `$args`:
 
   * If `alpha` isn't a number or an unquoted string that's case-insensitively
-    equal to 'none', throw an error.
+    equal to "none", throw an error.
 
   * If `alpha` is a number, set `alpha` to the result of [percent-converting]
     `$alpha` with a `max` of 1, and clamping it between 0 and 1 (inclusive).
@@ -1879,19 +1804,19 @@ This function is also available as a global function named `change-color()`.
 * Let `channel-args` be the remaining keyword arguments in `$args`, not
   including `$space` or `$alpha` arguments.
 
-* Let `channels` be a list of the `color`'s channels.
+* Let `channels` be a list of `color`'s channels.
 
 * For each keyword `key` and value `new` in `channel-args`:
 
   * If `new` is not a number or an unquoted string that's case-insensitively
-    equal to 'none', throw an error.
+    equal to "none", throw an error.
 
     > This basic restriction can be applied to all spaces. Further channel
     > restrictions are enforced by the normalization step for known spaces.
 
   * If `key` is not the (case-sensitive) name of a channel in `channels`:
 
-    * If `$space` is specified, throw an error.
+    * If `space` isn't null, throw an error.
 
     * If `color` is not a [legacy color], throw an error.
 
@@ -1901,6 +1826,8 @@ This function is also available as a global function named `change-color()`.
       `hue` and the only other keywords in `channel-args` are `saturation` or
       `lightness`, set `space` to `hsl`.
 
+      > This includes the case where `hue` is the only keyword.
+
     * Otherwise, if `key` is one of `whiteness` or `blackness`, or if `key` is
       `hue` and the only other keywords in `channel-args` are `whiteness` or
       `blackness`, set `space` to `hwb`.
@@ -1912,12 +1839,16 @@ This function is also available as a global function named `change-color()`.
 
   * Set the corresponding `key` value in `channels` to `new`.
 
-* Set `channels` to the result of [normalizing] `channels` in `known-space`.
+* Set `channels` to the result of [normalizing] `channels` in `space`.
 
-* Let `new` be a color in color space `known-space`, with `channels` channels,
-  and an alpha of `alpha`, or a missing alpha if `alpha` is a string.
+* Let `new-color` be a color in `space` with channels `channels` and alpha
+  `alpha`, or a missing alpha if `alpha` is a string.
 
-* Return the result of [converting] `new` into `origin-space`.
+* Return `color.to-space(new-color, color.space($color))`.
+
+  > Call `color.to-space()` rather than [converting] `$color` directly so that
+  > this won't cause powerless channels to become unexpectedly missing in legacy
+  > color spaces, thereby unexpectedly reducing their browser compatibility.
 
 ### `color.adjust()`
 
@@ -1929,23 +1860,16 @@ This function is also available as a global function named `adjust-color()`.
 
 * If `$color` is not a color, throw an error.
 
-* If any item in `$args` is not a keyword argument, throw an error.
+* If `$args` contains any positional arguments, throw an error.
 
-* Let `color` be the value of `$color`.
+* Let `space` be the argument named `$space` in `$args`, or null if it doesn't
+  have one.
 
-* Let `origin-space` be `color`'s space.
+* Let `color` be `$color` if `space` is null, and the result of [converting]
+  `$color` to `space` otherwise.
 
-* If the keyword argument `$space` is specified in `$args`:
-
-  * Let `known-space` be the result [looking up a known color space] named
-    `$space`.
-
-  * If `space != origin-space`, set `color` to the result of calling
-    `color.to-space(color, space)`.
-
-* Otherwise, let `known-space` be `origin-space`.
-
-* Let `alpha` be `color`'s alpha property.
+* Let `alpha` be the value of `color`'s alpha channel, or the unquoted string
+  `none` if it's missing.
 
 * If the keyword argument `$alpha` is specified in `$args`:
 
@@ -1969,13 +1893,15 @@ This function is also available as a global function named `adjust-color()`.
 * Let `channel-args` be the remaining keyword arguments in `$args`, not
   including `$space` or `$alpha` arguments.
 
-* Let `channels` be a list of the `color`'s channels.
+* Let `channels` be a list of `color`'s channels.
 
 * For each keyword `key` and value `adjust` in `channel-args`:
 
+  * If `adjust` is not a number, throw an error.
+
   * If `key` is not the (case-sensitive) name of a channel in `channels`:
 
-    * If `$space` is specified, throw an error.
+    * If `space` isn't null, throw an error.
 
     * If `color` is not a [legacy color], throw an error.
 
@@ -1985,22 +1911,25 @@ This function is also available as a global function named `adjust-color()`.
       `hue` and the only other keywords in `channel-args` are `saturation` or
       `lightness`, set `space` to `hsl`.
 
+      > This includes the case where `hue` is the only keyword.
+
     * Otherwise, if `key` is one of `whiteness` or `blackness`, or if `key` is
       `hue` and the only other keywords in `channel-args` are `whiteness` or
       `blackness`, set `space` to `hwb`.
 
     * Otherwise, throw an error.
 
-    * Set `channels` to be a list of the channels in `color` [converted] to
+    * Set `channels` to a list of the channels in `color` [converted] to
       `space`.
 
-  * Let `value` be the value of the channel named `key` in `channels`.
+  * Let `channel` be the channel named `key` in `channels`.
 
-  * Let `original` be `value`.
+  * If `channel` is [missing] and `space` isn't null, throw an error.
 
-  * Let `channel` be the channel named `key` in `known-space`.
+    > We leave an exemption for null spaces for backwards-compatibility with
+    > Sass's behavior before powerless channel support was introduced.
 
-  * If `channel` is missing in `color`, throw an error.
+  * Let `original` be `channel`'s value, or 0 if `channel` is missing.
 
     > This is not the ideal solution for handling `none`, but we want to match
     > CSS relative color syntax if possible. Throwing an error for now means we
@@ -2012,31 +1941,27 @@ This function is also available as a global function named `adjust-color()`.
 
   * If `adjust` has the unit `%`:
 
-    * If `channel` requires a percentage, set `value` to the result of appending
-      `%` units to `value`.
+    * If `channel` is not [scalable], throw an error.
 
-    * Otherwise, if `channel` allows percentage mapping, set `adjust` to the
-      result of [percent-converting] `adjust` with a `max` given by the maximum
-      of `channel`'s gamut range.
+    * Set `adjust` to the result of [percent-converting] `adjust` with
+      `channel`'s upper bound as `max`.
 
     * Otherwise, throw an error.
 
-  * Set `value` to `value + adjust`.
+  * Let `value` to `original + adjust`.
 
     > Once percentage/number conversions have been normalized, this will throw
     > an error if `adjust` and `value` are not compatible.
 
   * If `channel`'s upper bound `bound` is clamped and `value > bound`:
 
-    * If `original > bound`, set `value` to `math.min(original, value)`.
-
-    * Otherwise, set `value` to `bound`.
+    * Set `value` to `math.min(original, value)` if `original > bound` and
+      `bound` otherwise.
 
   * Otherwise, if `channel`'s lower bound `bound` is clamped and `value < bound`:
 
-    * If `original < bound`, set `value` to `math.max(original, value)`.
-
-    * Otherwise, set `value` to `bound`.
+    * Set `value` to `math.max(original, value)` if `original < bound` and
+      `bound` otherwise.
 
   > This ensures that adjustment won't ever make a color go out-of-bounds, which
   > preserves the historical clamping behavior (which is particularly important
@@ -2044,14 +1969,19 @@ This function is also available as a global function named `adjust-color()`.
   > that adjustment works rationally for channels that are already
   > out-of-bounds.
 
-* Set `channels` to the result of [normalizing] `channels` in `known-space`.
+* Set `channels` to the result of [normalizing] `channels` in `space`.
 
-* Let `new` be a color in color space `known-space`, with `channels` channels,
-  and an alpha of `alpha`.
+* Let `new-color` be a color in `space` with channels `channels` and alpha
+  `alpha`, or a missing alpha if `alpha` is a string.
 
-* Return the result of [converting] `new` into `origin-space`.
+* Return `color.to-space(new-color, color.space($color))`.
+
+  > Call `color.to-space()` rather than [converting] `$color` directly so that
+  > this won't cause powerless channels to become unexpectedly missing in legacy
+  > color spaces, thereby unexpectedly reducing their browser compatibility.
 
 [converted]: #converting-a-color
+[scalable]: #known-color-space
 
 ### `color.scale()`
 
@@ -2063,24 +1993,16 @@ This function is also available as a global function named `scale-color()`.
 
 * If `$color` is not a color, throw an error.
 
-* If any item in `$args` is not a keyword argument, throw an error.
+* If `$args` contains any positional arguments, throw an error.
 
-* Let `origin-space` be `$color`'s color space.
+* Let `space` be the argument named `$space` in `$args`, or null if it doesn't
+  have one.
 
-* If the keyword argument `$space` is specified in `$args`:
+* Let `color` be `$color` if `space` is null, and the result of [converting]
+  `$color` to `space` otherwise.
 
-  * Let `space` be the result of [looking up a known color space] named
-    `$space`.
-
-  * Let `color` be the result of [converting] `$color` to `space`.
-
-* Otherwise:
-
-  * Let `space` be `origin-space`.
-
-  * Let `color` be the value of `$color`.
-
-* Let `alpha` be `color`'s alpha property.
+* Let `alpha` be the value of `color`'s alpha channel, or the unquoted string
+  `none` if it's missing.
 
 * If the keyword argument `$alpha` is specified in `$args`:
 
@@ -2101,31 +2023,31 @@ This function is also available as a global function named `scale-color()`.
 * Let `channel-args` be the remaining keyword arguments in `$args`, not
   including `$space` or `$alpha` arguments.
 
-* Let `channels` be a list of the `color`'s channels.
+* Let `channels` be a list of `color`'s channels.
 
-* For each keyword `scale`, `factor` in `channel-args`:
+* For each keyword `key` and value `factor` in `channel-args`:
 
-  * If `scale` is not the (case-sensitive) name of a [scalable] channel in
+  * If `key` is not the (case-sensitive) name of a [scalable] channel in
     `channels`:
 
-    * If `$space` is specified, throw an error.
+    * If `space` isn't null, throw an error.
 
     * If `color` is not a [legacy color], throw an error.
 
-    * If `scale` is one of `red`, `green`, or `blue`, set `space` to `rgb`.
+    * If `key` is one of `red`, `green`, or `blue`, set `space` to `rgb`.
 
-    * Otherwise, if `scale` is one of `saturation`, or `lightness`, set `space`
-      to `hsl`.
+    * Otherwise, if `key` is one of `saturation` or `lightness`, set `space` to
+      `hsl`.
 
-    * Otherwise, if `scale` is one of `whiteness`, or `blackness`, set `space`
-      to `hwb`.
+    * Otherwise, if `key` is one of `whiteness` or `blackness`, set `space` to
+      `hwb`.
 
     * Otherwise, throw an error.
 
-    * Set `channels` to be a list of `legacy-color`'s channels.
+    * Set `channels` to a list of the channels in `color` [converted] to
+      `space`.
 
-  * Let `channel` be the corresponding `channel` in `channels` with a name
-    matching `scale`.
+  * Let `channel` be the channel named `key` in `channels`.
 
   * If `channel` is missing in `color`, throw an error.
 
@@ -2137,22 +2059,23 @@ This function is also available as a global function named `scale-color()`.
     > * [w3c/csswg-drafts#10151](https://github.com/w3c/csswg-drafts/issues/10151)
     > * [w3c/csswg-drafts#10211](https://github.com/w3c/csswg-drafts/issues/10211)
 
-  * Let `channel-max` be the upper boundary of `channel` in `space`.
-
-  * Let `channel-min` be the lower boundary of `channel` in `space`.
+  * Let `min` and `max` be the lower and upper bounds of `channel`,
+    respectively.
 
   * Set the corresponding `channel` in `channels` to the result of [scaling]
-    `channel` by `factor` with a `max` of `channel-max` and a `min` of
-    `channel-min`.
+    `channel` by `factor` with min `min` and max `max`.
 
 * Set `channels` be the result of [normalizing] `channels` in `space`.
 
-* Let `new` be a color in color space `space`, with `channels` channels, and an
-  alpha of `alpha`.
+* Let `new-color` be a color in `space` with channels `channels` and alpha
+  `alpha`, or a missing alpha if `alpha` is a string.
 
-* Return the result of [converting] `new` into `origin-space`.
+* Return `color.to-space(new-color, color.space($color))`.
+
+  > Call `color.to-space()` rather than [converting] `$color` directly so that
+  > this won't cause powerless channels to become unexpectedly missing in legacy
+  > color spaces, thereby unexpectedly reducing their browser compatibility.
 
-[scalable]: #known-color-space
 [scaling]: #scaling-a-number
 
 ### `color.complement()`
@@ -2163,28 +2086,12 @@ complement($color, $space: null)
 
 This function is also available as a global function named `complement()`.
 
-* If `$color` is not a color, throw an error.
+* Return the result of calling `color.adjust($color, $hue: 180deg, $space:
+  space)`.
 
-* If `$space` is null:
-
-  * If `$color` is a legacy color, let `space` be the [known color space]
-    named `hsl`.
-
-  * Otherwise, throw an error.
-
-* Otherwise:
-
-  * Let `space` be the result of [looking up a known color space] named
-    `$space`.
-
-  * If `space` is not a [known color space] with a polar-angle hue channel,
-    throw an error.
-
-    > This currently allows `hsl`, `hwb`, `lch`, and `oklch`. We may decide to
-    > provide additional options in the future.
-
-* Return the result of calling
-  `color.adjust($color, $hue: 180deg, $space: space)`.
+  > This will throw an error if `$color` is not a color, if `space` doesn't have
+  > a polar-angle hue channel, or if `$color`'s hue is missing (for a non-legacy
+  > color or an explicit space).
 
 ### `color.invert()`
 
@@ -2207,8 +2114,10 @@ This function is also available as a global function named `invert()`.
 
 * If `$space` is null:
 
-  * If `$color` is a legacy color, let `space` be `rgb`, and let `mix-space`
-    be null.
+  * If `$color` is a [legacy color], let `color` be the result of [converting]
+    `$color` to `rgb`.
+
+  * Let `mix-space` be null.
 
     > This allows us to also enforce legacy behavior in the final weighted mix.
 
@@ -2216,36 +2125,41 @@ This function is also available as a global function named `invert()`.
 
 * Otherwise:
 
-  * Let `space` be the result of [looking up a known color space] named
-    `$space`.
+  * Let `color` be the result of [converting] `$color` to `$space`.
 
-  * Let `mix-space` be `space`.
+  * Let `mix-space` be the name of `color`'s space.
 
-* If `$weight == 0%`, return the value of `$color`.
+* If `$weight == 0%`, return `$color`.
 
-* If `space` is not a valid [color interpolation method] *interpolation color
-  space*, and `$weight != 100%`, throw an error.
+* If `color`'s space is `hwb`:
 
-* Let `color` be the result of [converting] `$color` into `space`.
+  * Let `white` and `black` be the values of `color`'s channels of those names,
+    or the unquoted string "none" if the respective channels are [missing].
 
-* If `space` is the [known color space] named `hwb`:
-
-  * Let `hue`, `white`, and `black` be the three elements of `color`'s channels.
-
-  * Let `hue-out` be the result of `(hue + 180deg) % 360deg`.
-
-  * Let `invert` be the result of calling
-    `color.change(color, $hue: hue-out, $white: black, $black: white)`.
+  * Let `invert` be the result of calling `color.change(color.complement(color,
+    $space: hwb), $white: black, $black: white)`.
 
 * Otherwise:
 
   * Let `invert` be the value of `color`.
 
-  * For each `channel` element in `color`'s channels:
+  * For each `channel` in `color`'s channels:
+
+    * Let `value` be `channel`'s value.
 
     * If `channel` is a polar-angle `hue`:
 
-      * Let `new` be `(channel + 180deg) % 360deg`.
+      * If `channel` is [missing], throw an error.
+
+        > This is not the ideal solution for handling `none`, but we want to
+        > match CSS relative color syntax if possible. Throwing an error for now
+        > means we can adjust to match the CSS behavior once it is defined. See
+        > the following issues for details:
+        >
+        > * [w3c/csswg-drafts#10151](https://github.com/w3c/csswg-drafts/issues/10151)
+        > * [w3c/csswg-drafts#10211](https://github.com/w3c/csswg-drafts/issues/10211)
+
+      * Let `new` be `(value + 180deg) % 360deg`.
 
     * Otherwise, if `channel`'s name is either `chroma` or `saturation`:
 
@@ -2253,19 +2167,32 @@ This function is also available as a global function named `invert()`.
 
     * Otherwise:
 
-      * Let `min` and `max` be the minimum and maximum values defined for
-        `channel` in `space`.
+      * If `channel` is [missing], throw an error.
 
-      * Let `new` be `max - channel` if `min == 0`, and `channel * -1` otherwise.
+        > This is not the ideal solution for handling `none`, but we want to
+        > match CSS relative color syntax if possible. Throwing an error for now
+        > means we can adjust to match the CSS behavior once it is defined. See
+        > the following issues for details:
+        >
+        > * [w3c/csswg-drafts#10151](https://github.com/w3c/csswg-drafts/issues/10151)
+        > * [w3c/csswg-drafts#10211](https://github.com/w3c/csswg-drafts/issues/10211)
 
-    * Set the corresponding channel of `invert` to be `new`.
+      * Let `min` and `max` be the lower and upper bounds of `channel`'s range.
+
+      * Let `new` be `max - value` if `min == 0`, and `value * -1` otherwise.
+
+    * Set the corresponding channel of `invert` to `new`.
 
 * If `$weight == 100%`, let `result` be `invert`.
 
 * Otherwise, let `result` be the result of calling `color.mix(invert, color,
   $weight, mix-space)`.
 
-* Return the result of [converting] `result` to `$color`'s space.
+* Return `color.to-space(result, color.space($color))`.
+
+  > Call `color.to-space()` rather than [converting] `$color` directly so that
+  > this won't cause powerless channels to become unexpectedly missing in legacy
+  > color spaces, thereby unexpectedly reducing their browser compatibility.
 
 ### `color.grayscale()`
 
@@ -2281,15 +2208,11 @@ This function is also available as a global function named `grayscale()`.
   number or a [special number], return an unquoted string representing a CSS
   function call with name "invert" and argument `$color`.
 
-* If `$color` is not a color, throw an error.
+* If `$color` is a [legacy color], return the result of `color.change($color,
+  $saturation: 0, $space: hsl)`.
 
-* If `$color` is a legacy color, let `result` be the result of [converting]
-  `$color` to `hsl`, and changing the 'saturation' channel to 0.
-
-* Otherwise, let `result` be the result of [converting] `$color` to `oklch`, and
-  setting the `chroma` channel to 0.
-
-* Return the result of [converting] `color` to `$color`'s space.
+* Otherwise, return the result of `color.change($color, $chroma: 0, $space:
+  oklch)`.
 
 ### `color.ie-hex-str()`
 
@@ -2305,19 +2228,19 @@ ie-hex-str($color)
 * Let `rgb` be the result of [converting] and [gamut mapping] `$color` to `rgb`
   with method `local-minde`.
 
+* Let `alpha` be `rgb`'s alpha value.
+
+* Let `hex-alpha` be the hexadecimal representation of `alpha * 255`.
+
+* Append `hex-alpha` to `hex-list`.
+
 * Let `hex-list` be an empty list.
 
 * For each `channel` in `rgba`'s channels, as numbers:
 
   * Let `hex-channel` be the hexadecimal representation of `channel`'s value.
 
-  * Append `hex-channel` as the next item in `hex-list`.
-
-* Let `alpha` be `rgb`'s alpha value.
-
-* Let `hex-alpha` be the hexadecimal representation of `alpha * 255`.
-
-* Append `hex-alpha` as the next item in `hex-list`.
+  * Append `hex-channel` to `hex-list`.
 
 * Return the result of concatenating `hex-list` into a string.
 
@@ -2336,14 +2259,14 @@ These new CSS functions are provided globally.
     > Normalization and clamping is handled as part of the [parsing] process.
 
   * If `parsed` is a string, return a plain CSS function string with the name
-    `"hwb"` and the argument `parsed`.
+    "hwb" and the argument `parsed`.
 
   * Let `channels` be the channel list, and `alpha` the alpha value of `parsed`.
 
   * Let `hue`, `whiteness`, and `blackness` be the three elements of `channels`.
 
-  * Return a [legacy color] in the `hwb` space, with the given `hue`,
-    `whiteness`, and `blackness` channels, and `alpha` value.
+  * Return an `hwb` color with the given `hue`, `whiteness`, and `blackness`
+    channels, and `alpha` value.
 
 [parsing]: #parsing-color-components
 
@@ -2356,14 +2279,14 @@ These new CSS functions are provided globally.
   * Let `parsed` be the result of [parsing] `$channels` in `lab` space.
 
   * If `parsed` is a string, return a plain CSS function string with the name
-    `"lab"` and the argument `parsed`.
+    "lab" and the argument `parsed`.
 
   * Let `channels` be the channel list, and `alpha` the alpha value of `parsed`.
 
   * Let `lightness`, `a`, and `b` be the three elements of `channels`.
 
-  * Return a color in the `lab` [known color space], with the given `lightness`,
-    `a`, and `b` channels, and `alpha` value.
+  * Return a `lab` color with the given `lightness`, `a`, and `b` channels, and
+    `alpha` value.
 
 ### `lch()`
 
@@ -2374,14 +2297,14 @@ These new CSS functions are provided globally.
   * Let `parsed` be the result of [parsing] `$channels` in `lch` space.
 
   * If `parsed` is a string, return a plain CSS function string with the name
-    `"lch"` and the argument `parsed`.
+    "lch" and the argument `parsed`.
 
   * Let `channels` be the channel list, and `alpha` the alpha value of `parsed`.
 
   * Let `lightness`, `chroma`, and `hue` be the three elements of `channels`.
 
-  * Return a color in the `lch` [known color space], with the given `lightness`,
-    `chroma`, and `hue` channels, and `alpha` value.
+  * Return an `lch` color with the given `lightness`, `chroma`, and `hue`
+    channels, and `alpha` value.
 
 ### `oklab()`
 
@@ -2392,14 +2315,14 @@ These new CSS functions are provided globally.
   * Let `parsed` be the result of [parsing] `$channels` in `oklab` space.
 
   * If `parsed` is a string, return a plain CSS function string with the name
-    `"oklab"` and the argument `parsed`.
+    "oklab" and the argument `parsed`.
 
   * Let `channels` be the channel list, and `alpha` the alpha value of `parsed`.
 
   * Let `lightness`, `a`, and `b` be the three elements of `channels`.
 
-  * Return a color in the `oklab` [known color space], with the given `lightness`,
-    `a`, and `b` channels, and `alpha` value.
+  * Return an `oklab` color with the given `lightness`, `a`, and `b` channels,
+    and `alpha` value.
 
 ### `oklch()`
 
@@ -2410,14 +2333,14 @@ These new CSS functions are provided globally.
   * Let `parsed` be the result of [parsing] `$channels` in `oklch` space.
 
   * If `parsed` is a string, return a plain CSS function string with the name
-    `"oklch"` and the argument `parsed`.
+    "oklch" and the argument `parsed`.
 
   * Let `channels` be the channel list, and `alpha` the alpha value of `parsed`.
 
   * Let `lightness`, `chroma`, and `hue` be the three elements of `channels`.
 
-  * Return a color in the `oklch` [known color space], with the given `lightness`,
-    `chroma`, and `hue` channels, and `alpha` value.
+  * Return an `oklch` color with the given `lightness`, `chroma`, and `hue`
+    channels, and `alpha` value.
 
 ### `color()`
 
@@ -2428,7 +2351,7 @@ These new CSS functions are provided globally.
   * Let `parsed` be the result of [parsing] `$description` without a space.
 
   * If `parsed` is a string, return a plain CSS function string with the name
-    `"color"` and the argument `parsed`.
+    "color" and the argument `parsed`.
 
   * Let `space` be the color space, `channels` the channel list, and `alpha`
     the alpha value of `parsed`.
@@ -2440,25 +2363,25 @@ These new CSS functions are provided globally.
 Any legacy global functions that are not explicitly updated here should continue
 to behave as alias functions for their appropriately updated counterparts.
 
-> Note that the new logic preserves decimal values in color channels, as well
-> as preserving the initial color-space used in defining a color.
+> Note that the new logic preserves decimal values in RGB color channels, as
+> well as preserving the initial color space used when defining a color.
 
 ### `rgb()` and `rgba()`
 
 The `rgba()` function is identical to `rgb()`, except that if it would return a
-plain CSS function named `"rgb"` that function is named `"rgba"` instead.
+plain CSS function named "rgb" that function is named "rgba" instead.
 
 * ```
   rgb($red, $green, $blue, $alpha: 1)
   ```
 
   * If any argument is an unquoted string that's case-insensitively equal to
-    'none', throw an error.
+    "none", throw an error.
 
     > Missing channels are not allowed in legacy syntax.
 
   * If any argument is a [special number], return a plain CSS function
-    string with the name `"rgb"` and the arguments `$red`, `$green`, `$blue`,
+    string with the name "rgb" and the arguments `$red`, `$green`, `$blue`,
     and `$alpha`.
 
   * If `$alpha` is not a number, throw an error.
@@ -2467,17 +2390,17 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead.
     and then clamping the value between 0 and 1, inclusive.
 
   * Let `red`, `green`, and `blue` be the three elements returned by
-    [normalizing] `($red, $green, $blue)` in the [known color space] named `rgb`.
+    [normalizing] `($red, $green, $blue)` in `rgb` space.
 
-  * Return a [legacy color] in the `rgb` space, with the given `red`,
-    `green`, and `blue` channels, and `alpha` value.
+  * Return an `rgb` color with the given `red`, `green`, and `blue` channels,
+    and `alpha` value.
 
 * ```
   rgb($red, $green, $blue)
   ```
 
   * If any argument is a [special number], return a plain CSS function string
-    with the name `"rgb"` and the arguments `$red`, `$green`, and `$blue`.
+    with the name "rgb" and the arguments `$red`, `$green`, and `$blue`.
 
   * Otherwise, return the result of calling `rgb($red, $green, $blue, 1)`.
 
@@ -2488,7 +2411,7 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead.
   * Let `parsed` be the result of [parsing] `$channels` in `rgb` space.
 
   * If `parsed` is a string, return a plain CSS function string with the name
-    `"rgb"` and the argument `parsed`.
+    "rgb" and the argument `parsed`.
 
   * Let `channels` be the channel list, and `alpha` the alpha value of `parsed`.
 
@@ -2501,7 +2424,7 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead.
   ```
 
   * If either argument is a [special variable string], return a plain CSS
-    function string with the name `"rgb"` and the same arguments.
+    function string with the name "rgb" and the same arguments.
 
   * If `$color` is not a [legacy color], throw an error.
 
@@ -2511,20 +2434,20 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead.
 ### `hsl()` and `hsla()`
 
 The `hsla()` function is identical to `hsl()`, except that if it would return a
-plain CSS function named `"hsl"` that function is named `"hsla"` instead.
+plain CSS function named "hsl" that function is named "hsla" instead.
 
 * ```
   hsl($hue, $saturation, $lightness, $alpha: 1)
   ```
 
   * If any argument is an unquoted string that's case-insensitively equal to
-    'none', throw an error.
+    "none", throw an error.
 
     > Missing channels are not allowed in legacy syntax.
 
-  * If any argument is a [special number], return a plain CSS function
-    string with the name `"hsl"` and the arguments `$hue`, `$saturation`,
-    `$lightness`, and `$alpha`.
+  * If any argument is a [special number], return a plain CSS function string
+    with the name "hsl" and the arguments `$hue`, `$saturation`, `$lightness`,
+    and `$alpha`.
 
   * If `$alpha` is not a number, throw an error.
 
@@ -2537,26 +2460,26 @@ plain CSS function named `"hsl"` that function is named `"hsla"` instead.
 
   > Conversion to rgb has been removed.
 
-  * Return a [legacy color] in the `hsl` space, with the given `hue`,
-    `saturation`, and `lightness` channels, and `alpha` value.
+  * Return an `hsl` color with the given `hue`, `saturation`, and `lightness`
+    channels, and `alpha` value.
 
 * ```
   hsl($hue, $saturation, $lightness)
   ```
 
   * If any argument is a [special number], return a plain CSS function string
-    with the name `"hsl"` and the arguments `$hue`, `$saturation`, and
+    with the name "hsl" and the arguments `$hue`, `$saturation`, and
     `$lightness`.
 
-  * Otherwise, return the result of calling
-    `hsl($hue, $saturation, $lightness, 1)`.
+  * Otherwise, return the result of calling `hsl($hue, $saturation, $lightness,
+    1)`.
 
 * ```
   hsl($hue, $saturation)
   ```
 
   * If either argument is a [special variable string], return a plain CSS
-    function string with the name `"hsl"` and the same arguments.
+    function string with the name "hsl" and the same arguments.
 
   * Otherwise, throw an error.
 
@@ -2569,14 +2492,14 @@ plain CSS function named `"hsl"` that function is named `"hsla"` instead.
     > Normalization and clamping is handled as part of the [parsing] process.
 
   * If `parsed` is a string, return a plain CSS function string with the name
-    `"hsl"` and the argument `parsed`.
+    "hsl" and the argument `parsed`.
 
   * Let `channels` be the channel list, and `alpha` the alpha value of `parsed`.
 
   * Let `hue`, `saturation`, and `lightness` be the three elements of `channels`.
 
-  * Return a [legacy color] in the `hsl` space, with the given `hue`,
-    `saturation`, and `lightness` channels, and `alpha` value.
+  * Return an `hsl` color with the given `hue`, `saturation`, and `lightness`
+    channels, and `alpha` value.
 
 ## Deprecated Functions
 
@@ -2593,7 +2516,7 @@ the deprecation process, they act as alias functions described below.
 
   * If `$color` is not a [legacy color], throw an error.
 
-  * Return the result of calling `color.channel($color, 'red', rgb)`.
+  * Return the result of calling `color.channel($color, "red", rgb)`.
 
 This function is also available as a global function named `red()`.
 
@@ -2605,7 +2528,7 @@ This function is also available as a global function named `red()`.
 
   * If `$color` is not a [legacy color], throw an error.
 
-  * Return the result of calling `color.channel($color, 'green', rgb)`.
+  * Return the result of calling `color.channel($color, "green", rgb)`.
 
 This function is also available as a global function named `green()`.
 
@@ -2617,7 +2540,7 @@ This function is also available as a global function named `green()`.
 
   * If `$color` is not a [legacy color], throw an error.
 
-  * Return the result of calling `color.channel($color, 'blue', rgb)`.
+  * Return the result of calling `color.channel($color, "blue", rgb)`.
 
 This function is also available as a global function named `blue()`.
 
@@ -2629,7 +2552,7 @@ This function is also available as a global function named `blue()`.
 
   * If `$color` is not a [legacy color], throw an error.
 
-  * Return the result of calling `color.channel($color, 'hue', hsl)`.
+  * Return the result of calling `color.channel($color, "hue", hsl)`.
 
 This function is also available as a global function named `hue()`.
 
@@ -2641,7 +2564,7 @@ This function is also available as a global function named `hue()`.
 
   * If `$color` is not a [legacy color], throw an error.
 
-  * Return the result of calling `color.channel($color, 'saturation', hsl)`.
+  * Return the result of calling `color.channel($color, "saturation", hsl)`.
 
 This function is also available as a global function named `saturation()`.
 
@@ -2653,7 +2576,7 @@ This function is also available as a global function named `saturation()`.
 
   * If `$color` is not a [legacy color], throw an error.
 
-  * Return the result of calling `color.channel($color, 'lightness', hsl)`.
+  * Return the result of calling `color.channel($color, "lightness", hsl)`.
 
 This function is also available as a global function named `lightness()`.
 
@@ -2665,7 +2588,7 @@ This function is also available as a global function named `lightness()`.
 
   * If `$color` is not a [legacy color], throw an error.
 
-  * Return the result of calling `color.channel($color, 'whiteness', hwb)`.
+  * Return the result of calling `color.channel($color, "whiteness", hwb)`.
 
 ### `color.blackness()`
 
@@ -2675,7 +2598,7 @@ This function is also available as a global function named `lightness()`.
 
   * If `$color` is not a [legacy color], throw an error.
 
-  * Return the result of calling `color.channel($color, 'blackness', hwb)`.
+  * Return the result of calling `color.channel($color, "blackness", hwb)`.
 
 ### `color.alpha()`
 
@@ -2685,7 +2608,7 @@ This function is also available as a global function named `lightness()`.
 
   * If `$color` is not a [legacy color], throw an error.
 
-  * Return the result of calling `color.channel($color, 'alpha')`.
+  * Return the result of calling `color.channel($color, "alpha")`.
 
 ### `adjust-hue()`
 

From 4d946dd44594f40d335a0cce46eeebab52473670 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Thu, 12 Sep 2024 15:06:50 -0700
Subject: [PATCH 50/51] Fix a duplicated file from a merge error

---
 proposal/shared-resources.changes.md |  12 --
 proposal/shared-resources.d.ts.md    | 226 ---------------------------
 2 files changed, 238 deletions(-)
 delete mode 100644 proposal/shared-resources.changes.md
 delete mode 100644 proposal/shared-resources.d.ts.md

diff --git a/proposal/shared-resources.changes.md b/proposal/shared-resources.changes.md
deleted file mode 100644
index 55e48ce9..00000000
--- a/proposal/shared-resources.changes.md
+++ /dev/null
@@ -1,12 +0,0 @@
-## Draft 1.2
-
-* Await method calls in example code.
-* Use `compiler.compile*()` methods in example code.
-
-## Draft 1.1
-
-* Remove unneeded returned/resolved value from `dispose`.
-
-## Draft 1
-
-* Initial draft
diff --git a/proposal/shared-resources.d.ts.md b/proposal/shared-resources.d.ts.md
deleted file mode 100644
index 9e77d5d7..00000000
--- a/proposal/shared-resources.d.ts.md
+++ /dev/null
@@ -1,226 +0,0 @@
-# Shared Resources in JavaScript API: Draft 1.1
-
-*([Issue](https://github.com/sass/sass/issues/3296))*
-
-This proposal adds an API design that allows for sharing resources across
-multiple invocations of the Sass compiler's JavaScript API. This will provide
-Sass's users with a more efficient way of running Sass compilations across
-multiple files.
-
-## Table of Contents
-
-* [Summary](#summary)
-  * [Design Decisions](#design-decisions)
-    * [Splitting Sync and Async Compilers](#splitting-sync-and-async-compilers)
-    * [Limited API interface](#limited-api-interface)
-    * [Flexibility for interfaces on process management](#flexibility-for-interfaces-on-process-management)
-    * [No shared state](#no-shared-state)
-  * [Example](#example)
-    * [Sync Compiler](#sync-compiler)
-    * [Async Compiler](#async-compiler)
-* [API](#api)
-  * [Types](#types)
-    * [initCompiler()](#initcompiler)
-    * [initAsyncCompiler()](#initasynccompiler)
-    * [Compiler](#compiler)
-      * [`compile()` and `compileString()`](#compile-and-compilestring)
-      * [dispose()](#dispose)
-    * [Async Compiler](#async-compiler-1)
-      * [`compileAsync()` and `compileStringAsync()`](#compileasync-and-compilestringasync)
-      * [dispose()](#dispose-1)
-
-## Summary
-
-Currently, the JavaScript API for Sass only accommodates a single compilation
-per process. In practice, we have observed build tools are compiling multiple
-times in response to a single user action. For instance, Vue.js authors using
-Vite will see a Sass compilation for each `<style lang="scss">` tag that appears
-in their codebase.
-
-While processes can be spun up and down quickly, the combined time can add up to
-a noticeable impact on performance. The embedded client supports long running
-processes, and this proposal adds a method for the embedded host to manage the
-lifecycle of these processes through a Compiler interface.
-
-### Design Decisions
-
-#### Splitting Sync and Async Compilers
-
-When creating a Compiler, users will need to choose either a compiler that
-provides access to synchronous or asynchronous compilation. While providing both
-simultaneously from a single Compiler would offer more flexibility, it also adds
-significant complexity to the API. In practice, we expect most users will only
-want to use one mode, generally in the mode that is the fastest for the
-implementation. If synchronous and asynchronous compilations are both needed,
-users can create multiple Compilers.
-
-#### Limited API interface
-
-Many build tools allow passing the Sass module as a parameter, which offers
-flexibility to users on what implementation of Sass is used. Because users may
-still want to use portions of the JavaScript API unrelated to compilation, we
-considered having the Compiler interface mirror the top level Sass interface,
-which would allow users to replace instances of the imported `sass` class with
-an instance of the compiler. However, this adds an additional cost to ongoing
-Sass development. The proposed API does not eliminate this as a possibility in
-the future.
-
-#### Flexibility for interfaces on process management
-
-In environments without access to a long-running compiler—for instance, the Dart
-Sass implementation—the Compiler interface will continue to perform a single
-compilation per process.
-
-#### No shared state
-
-This proposal does not change how a single compilation is done, and no state is
-shared across compilations. Options and importers must be set for each
-compilation. Future enhancements may introduce [shared state], but this proposal
-only adds the ability to run multiple compilations on a single process.
-
-[shared state]: https://github.com/sass/sass/issues/3296
-
-This also means that the proposal makes no assertions about whether file content
-has changed. It is also up to the user to determine when to start and stop a
-long-running compiler process.
-
-### Example
-
-#### Sync Compiler
-
-```js
-import * as sass from 'sass';
-function setup() {
-  const compiler = sass.initCompiler();
-  const result1 = compiler.compileString('a {b: c}').css;
-  const result2 = compiler.compileString('a {b: c}').css;
-  compiler.dispose();
-
-  // throws error
-  const result3 = compiler.compileString('a {b: c}').css;
-}
-```
-
-#### Async Compiler
-
-```js
-import * as sass from 'sass';
-async function setup() {
-  const compiler = await sass.initAsyncCompiler();
-  const result1 = await compiler.compileStringAsync('a {b: c}').css;
-  const result2 = await compiler.compileStringAsync('a {b: c}').css;
-  await compiler.dispose();
-
-  // throws error
-  const result3 = await compiler.compileStringAsync('a {b: c}').css;
-}
-```
-
-## API
-
-### Types
-
-```ts
-import {CompileResult} from '../spec/js-api/compile';
-import {Options, StringOptions} from '../spec/js-api/options';
-```
-
-#### initCompiler()
-
-Returns a synchronous [Compiler].
-
-[Compiler]: #compiler
-
-```ts
-export function initCompiler(): Compiler;
-```
-
-#### initAsyncCompiler()
-
-Resolves with an [Async Compiler].
-
-[Async Compiler]: #async-compiler
-
-```ts
-export function initAsyncCompiler(): Promise<AsyncCompiler>;
-```
-
-#### Compiler
-
-An instance of the synchronous Compiler.
-
-```ts
-export interface Compiler {
-```
-
-##### `compile()` and `compileString()`
-
-Only synchronous compilation methods [`compile()`] and [`compileString()`] must be
-included, and must have with identical semantics to the [Sass interface].
-
-[`compile()`]: ../spec/js-api/compile.d.ts.md#compile
-[`compilestring()`]: ../spec/js-api/compile.d.ts.md#compilestring
-[Sass interface]: ../spec/js-api/index.d.ts.md
-
-```ts
-compile(path: string, options?: Options<'sync'>): CompileResult;
-compileString(source: string, options?: StringOptions<'sync'>): CompileResult;
-```
-
-##### dispose()
-
-When `dispose` is invoked on a Compiler:
-
-* Any subsequent invocations of `compile` and `compileString` must throw an
-  error.
-
-```ts
-  dispose(): void;
-}
-```
-
-#### Async Compiler
-
-An instance of the asynchronous Compiler.
-
-```ts
-export interface AsyncCompiler {
-```
-
-##### `compileAsync()` and `compileStringAsync()`
-
-Only asynchronous compilation methods [`compileAsync()`] and
-[`compileStringAsync()`] must be included, and must have with identical
-semantics to the [Sass interface].
-
-[`compileasync()`]: ../spec/js-api/compile.d.ts.md#compileasync
-[`compilestringasync()`]: ../spec/js-api/compile.d.ts.md#compilestringasync
-
-```ts
-compileAsync(
-  path: string,
-  options?: Options<'async'>
-): Promise<CompileResult>;
-compileStringAsync(
-  source: string,
-  options?: StringOptions<'async'>
-): Promise<CompileResult>;
-```
-
-##### dispose()
-
-When `dispose` is invoked on an Async Compiler:
-
-* Any subsequent invocations of `compileAsync` and `compileStringAsync` must
-  throw an error.
-
-* Any compilations that have not yet been settled must be allowed to settle, and
-  not be cancelled.
-
-* Resolves a Promise when all compilations have been settled, and disposal is
-  complete.
-
-```ts
-  dispose(): Promise<void>;
-}
-```

From dd882bb8d299ba521b1b1c31bbdd145f1647ac76 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Thu, 12 Sep 2024 15:07:19 -0700
Subject: [PATCH 51/51] Mark embedded protocol 3.0.0 as stable

---
 EMBEDDED_PROTOCOL_CHANGELOG.md | 2 +-
 spec/EMBEDDED_PROTOCOL_VERSION | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/EMBEDDED_PROTOCOL_CHANGELOG.md b/EMBEDDED_PROTOCOL_CHANGELOG.md
index ee8498ba..c6edce2d 100644
--- a/EMBEDDED_PROTOCOL_CHANGELOG.md
+++ b/EMBEDDED_PROTOCOL_CHANGELOG.md
@@ -1,4 +1,4 @@
-## 3.0.0-dev
+## 3.0.0
 
 * Add `Color` SassScript value.
 
diff --git a/spec/EMBEDDED_PROTOCOL_VERSION b/spec/EMBEDDED_PROTOCOL_VERSION
index 2468aa9e..4a36342f 100644
--- a/spec/EMBEDDED_PROTOCOL_VERSION
+++ b/spec/EMBEDDED_PROTOCOL_VERSION
@@ -1 +1 @@
-3.0.0-dev
+3.0.0