5 files changed, 49 insertions, 15 deletions
diff --git a/crates/typst-library/src/foundations/func.rs b/crates/typst-library/src/foundations/func.rs
index 741b6633..3ed1562f 100644
--- a/crates/typst-library/src/foundations/func.rs
+++ b/crates/typst-library/src/foundations/func.rs
@@ -9,7 +9,7 @@ use ecow::{eco_format, EcoString};
 use typst_syntax::{ast, Span, SyntaxNode};
 use typst_utils::{singleton, LazyHash, Static};
 
-use crate::diag::{bail, At, SourceResult, StrResult};
+use crate::diag::{bail, At, DeprecationSink, SourceResult, StrResult};
 use crate::engine::Engine;
 use crate::foundations::{
     cast, repr, scope, ty, Args, Bytes, CastInfo, Content, Context, Element, IntoArgs,
@@ -255,11 +255,15 @@ impl Func {
     }
 
     /// Get a field from this function's scope, if possible.
-    pub fn field(&self, field: &str) -> StrResult<&'static Value> {
+    pub fn field(
+        &self,
+        field: &str,
+        sink: impl DeprecationSink,
+    ) -> StrResult<&'static Value> {
         let scope =
             self.scope().ok_or("cannot access fields on user-defined functions")?;
         match scope.get(field) {
-            Some(binding) => Ok(binding.read()),
+            Some(binding) => Ok(binding.read_checked(sink)),
             None => match self.name() {
                 Some(name) => bail!("function `{name}` does not contain field `{field}`"),
                 None => bail!("function does not contain field `{field}`"),
diff --git a/crates/typst-library/src/foundations/module.rs b/crates/typst-library/src/foundations/module.rs
index 3259c17e..8d9626a1 100644
--- a/crates/typst-library/src/foundations/module.rs
+++ b/crates/typst-library/src/foundations/module.rs
@@ -4,7 +4,7 @@ use std::sync::Arc;
 use ecow::{eco_format, EcoString};
 use typst_syntax::FileId;
 
-use crate::diag::{bail, StrResult};
+use crate::diag::{bail, DeprecationSink, StrResult};
 use crate::foundations::{repr, ty, Content, Scope, Value};
 
 /// An module of definitions.
@@ -118,9 +118,9 @@ impl Module {
     }
 
     /// Try to access a definition in the module.
-    pub fn field(&self, field: &str) -> StrResult<&Value> {
+    pub fn field(&self, field: &str, sink: impl DeprecationSink) -> StrResult<&Value> {
         match self.scope().get(field) {
-            Some(binding) => Ok(binding.read()),
+            Some(binding) => Ok(binding.read_checked(sink)),
             None => match &self.name {
                 Some(name) => bail!("module `{name}` does not contain `{field}`"),
                 None => bail!("module does not contain `{field}`"),
diff --git a/crates/typst-library/src/foundations/scope.rs b/crates/typst-library/src/foundations/scope.rs
index e73afeac..d6c5a8d0 100644
--- a/crates/typst-library/src/foundations/scope.rs
+++ b/crates/typst-library/src/foundations/scope.rs
@@ -10,7 +10,7 @@ use indexmap::IndexMap;
 use typst_syntax::Span;
 use typst_utils::Static;
 
-use crate::diag::{bail, HintedStrResult, HintedString, StrResult};
+use crate::diag::{bail, DeprecationSink, HintedStrResult, HintedString, StrResult};
 use crate::foundations::{
     Element, Func, IntoValue, NativeElement, NativeFunc, NativeFuncData, NativeType,
     Type, Value,
@@ -258,6 +258,8 @@ pub struct Binding {
     span: Span,
     /// The category of the binding.
     category: Option<Category>,
+    /// A deprecation message for the definition.
+    deprecation: Option<&'static str>,
 }
 
 /// The different kinds of slots.
@@ -277,6 +279,7 @@ impl Binding {
             span,
             kind: BindingKind::Normal,
             category: None,
+            deprecation: None,
         }
     }
 
@@ -285,11 +288,29 @@ impl Binding {
         Self::new(value, Span::detached())
     }
 
+    /// Marks this binding as deprecated, with the given `message`.
+    pub fn deprecated(&mut self, message: &'static str) -> &mut Self {
+        self.deprecation = Some(message);
+        self
+    }
+
     /// Read the value.
     pub fn read(&self) -> &Value {
         &self.value
     }
 
+    /// Read the value, checking for deprecation.
+    ///
+    /// As the `sink`
+    /// - pass `()` to ignore the message.
+    /// - pass `(&mut engine, span)` to emit a warning into the engine.
+    pub fn read_checked(&self, sink: impl DeprecationSink) -> &Value {
+        if let Some(message) = self.deprecation {
+            sink.emit(message);
+        }
+        &self.value
+    }
+
     /// Try to write to the value.
     ///
     /// This fails if the value is a read-only closure capture.
@@ -320,6 +341,11 @@ impl Binding {
         self.span
     }
 
+    /// A deprecation message for the value, if any.
+    pub fn deprecation(&self) -> Option<&'static str> {
+        self.deprecation
+    }
+
     /// The category of the value, if any.
     pub fn category(&self) -> Option<Category> {
         self.category
diff --git a/crates/typst-library/src/foundations/ty.rs b/crates/typst-library/src/foundations/ty.rs
index 09f5efa1..40f7003c 100644
--- a/crates/typst-library/src/foundations/ty.rs
+++ b/crates/typst-library/src/foundations/ty.rs
@@ -8,7 +8,7 @@ use std::sync::LazyLock;
 use ecow::{eco_format, EcoString};
 use typst_utils::Static;
 
-use crate::diag::{bail, StrResult};
+use crate::diag::{bail, DeprecationSink, StrResult};
 use crate::foundations::{
     cast, func, AutoValue, Func, NativeFuncData, NoneValue, Repr, Scope, Value,
 };
@@ -94,9 +94,13 @@ impl Type {
     }
 
     /// Get a field from this type's scope, if possible.
-    pub fn field(&self, field: &str) -> StrResult<&'static Value> {
+    pub fn field(
+        &self,
+        field: &str,
+        sink: impl DeprecationSink,
+    ) -> StrResult<&'static Value> {
         match self.scope().get(field) {
-            Some(binding) => Ok(binding.read()),
+            Some(binding) => Ok(binding.read_checked(sink)),
             None => bail!("type {self} does not contain field `{field}`"),
         }
     }
diff --git a/crates/typst-library/src/foundations/value.rs b/crates/typst-library/src/foundations/value.rs
index 4fa380b4..854c2486 100644
--- a/crates/typst-library/src/foundations/value.rs
+++ b/crates/typst-library/src/foundations/value.rs
@@ -11,7 +11,7 @@ use serde::{Deserialize, Deserializer, Serialize, Serializer};
 use typst_syntax::{ast, Span};
 use typst_utils::ArcExt;
 
-use crate::diag::{HintedStrResult, HintedString, StrResult};
+use crate::diag::{DeprecationSink, HintedStrResult, HintedString, StrResult};
 use crate::foundations::{
     fields, ops, repr, Args, Array, AutoValue, Bytes, CastInfo, Content, Datetime,
     Decimal, Dict, Duration, Fold, FromValue, Func, IntoValue, Label, Module,
@@ -155,15 +155,15 @@ impl Value {
     }
 
     /// Try to access a field on the value.
-    pub fn field(&self, field: &str) -> StrResult<Value> {
+    pub fn field(&self, field: &str, sink: impl DeprecationSink) -> StrResult<Value> {
         match self {
             Self::Symbol(symbol) => symbol.clone().modified(field).map(Self::Symbol),
             Self::Version(version) => version.component(field).map(Self::Int),
             Self::Dict(dict) => dict.get(field).cloned(),
             Self::Content(content) => content.field_by_name(field),
-            Self::Type(ty) => ty.field(field).cloned(),
-            Self::Func(func) => func.field(field).cloned(),
-            Self::Module(module) => module.field(field).cloned(),
+            Self::Type(ty) => ty.field(field, sink).cloned(),
+            Self::Func(func) => func.field(field, sink).cloned(),
+            Self::Module(module) => module.field(field, sink).cloned(),
             _ => fields::field(self, field),
         }
     }