[meta.load] Add support for first-class modules

Author: nex3

lib/src/protofier.ts

@@ -26,6 +26,7 @@ import {
   SassCalculation,
 } from './value/calculations';
 import {SassMixin} from './value/mixin';
+import {SassModule} from './value/module';
 
 /**
  * A class that converts [Value] objects into protobufs.
@@ -132,6 +133,14 @@ export class Protofier {
       }
       const mixin = create(proto.Value_CompilerMixinSchema, value);
       result.value = {case: 'compilerMixin', value: mixin};
+    } else if (value instanceof SassModule) {
+      if (value.compileContext !== this.functions.compileContext) {
+        throw utils.compilerError(
+          `Value ${value} does not belong to this compilation`,
+        );
+      }
+      const module = create(proto.Value_CompilerModuleSchema, value);
+      result.value = {case: 'compilerModule', value: module};
     } else if (value instanceof SassCalculation) {
       result.value = {
         case: 'calculation',
@@ -403,6 +412,12 @@ export class Protofier {
           this.functions.compileContext,
         );
 
+      case 'compilerModule':
+        return new SassModule(
+          value.value.value.id,
+          this.functions.compileContext,
+        );
+
       case 'calculation':
         return this.deprotofyCalculation(value.value.value);
 

lib/src/value/index.ts

@@ -13,6 +13,7 @@ import {SassString} from './string';
 import {valueError} from '../utils';
 import {SassCalculation} from './calculations';
 import {SassMixin} from './mixin';
+import {SassModule} from './module';
 
 /**
  * A SassScript value.
@@ -151,6 +152,17 @@ export abstract class Value implements ValueObject {
     throw valueError(`${this} is not a mixin reference`, name);
   }
 
+  /**
+   * Casts `this` to `SassModule`; throws if `this` isn't a module
+   * reference.
+   *
+   * If `this` came from a function argument, `name` is the argument name
+   * (without the `$`) and is used for error reporting.
+   */
+  assertModule(name?: string): SassModule {
+    throw valueError(`${this} is not a module reference`, name);
+  }
+
   /**
    * Casts `this` to `SassMap`; throws if `this` isn't a map.
    *

lib/src/value/module.ts

@@ -0,0 +1,56 @@
+// Copyright 2026 Google LLC. Use of this source code is governed by an
+// MIT-style license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
+import {hash} from 'immutable';
+
+import {Value} from './index';
+
+/** A first-class SassScript module. */
+export class SassModule extends Value {
+  /**
+   * This is the unique ID that the compiler uses to determine which module it
+   * refers to.
+   *
+   * This is marked as public so that the protofier can access it, but it's not
+   * part of the package's public API and should not be accessed by user code.
+   * It may be renamed or removed without warning in the future.
+   */
+  readonly id: number;
+
+  /**
+   * This is the unique context that the host uses to determine which
+   * compilation this module belongs to.
+   *
+   * This is marked as public so that the protofier can access it, but it's not
+   * part of the package's public API and should not be accessed by user code.
+   * It may be renamed or removed without warning in the future.
+   */
+  readonly compileContext: symbol;
+
+  constructor(id: number, compileContext: symbol) {
+    super();
+    this.id = id;
+    this.compileContext = compileContext;
+  }
+
+  equals(other: Value): boolean {
+    return (
+      other instanceof SassModule &&
+      other.compileContext === this.compileContext &&
+      other.id === this.id
+    );
+  }
+
+  hashCode(): number {
+    return hash(this.id);
+  }
+
+  toString(): string {
+    return `<compiler module ${this.id}>`;
+  }
+
+  assertModule(): SassModule {
+    return this;
+  }
+}