Skip to main content

aster/engine/
content.rs

1//! Construction of Aster's Typst runtime protocol.
2
3use std::collections::BTreeMap;
4use std::sync::LazyLock;
5
6use typst::diag::{At, FileError, FileResult, SourceResult};
7use typst::ecow::{EcoString, eco_format};
8use typst::engine::Engine;
9use typst::foundations::{
10    Array, Bytes, Capturer, Closure, ClosureNode, Dict, Func, Module, Scope, Scopes, Str, Value,
11    dict, func,
12};
13use typst::syntax::ast::{self, AstNode};
14use typst::syntax::package::PackageSpec;
15use typst::syntax::{FileId, RootedPath, Span, SyntaxNode, VirtualPath, VirtualRoot, parse_code};
16use typst::utils::LazyHash;
17use typst::{Feature, Library, LibraryExt, World};
18use typst_eval::CapturesVisitor;
19
20use crate::engine::route::ParamSet;
21
22/// Runtime protocol version understood by this Aster release.
23pub const PROTOCOL_VERSION: i64 = 9;
24/// Version of Aster providing the runtime protocol.
25pub const ASTER_VERSION: &str = env!("CARGO_PKG_VERSION");
26/// Reserved `sys.inputs` key containing Aster's runtime protocol.
27pub const INPUT_NAME: &str = "_aster";
28
29/// The complete Aster-owned Typst runtime state for one build phase.
30pub struct Runtime {
31    inputs: Dict,
32    library: LazyHash<Library>,
33    page_routes: PageRoutes,
34}
35
36impl Runtime {
37    /// Construct the base runtime used for route planning.
38    pub fn new(entries: impl IntoIterator<Item = ContentEntry>, dev: bool) -> Self {
39        let mut collections: BTreeMap<EcoString, Vec<(EcoString, RootedPath)>> = BTreeMap::new();
40        for entry in entries {
41            collections
42                .entry(entry.collection)
43                .or_default()
44                .push((entry.id, entry.source));
45        }
46
47        let mut inputs = Dict::new();
48        inputs.insert(Str::from(INPUT_NAME), protocol_value(collections, dev));
49        let library = library(&inputs);
50        Self {
51            inputs,
52            library,
53            page_routes: PageRoutes::default(),
54        }
55    }
56
57    /// Supply the complete planned page URL set without changing the library.
58    pub fn with_page_routes(mut self, pages: Vec<EcoString>) -> Self {
59        self.page_routes = PageRoutes::new(pages);
60        self
61    }
62
63    /// Add the final rendered page snapshot available to generators.
64    pub fn with_site(mut self, pages: &[SitePage]) -> Self {
65        let pages = pages
66            .iter()
67            .map(|page| {
68                let content = page.content.as_ref().map_or(Value::None, |content| {
69                    Value::Dict(dict! {
70                        "html" => content.html.clone(),
71                        "text" => content.text.clone(),
72                    })
73                });
74                Value::Dict(dict! {
75                    "path" => page.path.clone(),
76                    "html" => page.html.clone(),
77                    "content" => content,
78                })
79            })
80            .collect::<Array>();
81        let Value::Dict(mut protocol) = self
82            .inputs
83            .get(INPUT_NAME)
84            .expect("Aster inputs must contain the runtime protocol")
85            .clone()
86        else {
87            unreachable!("Aster runtime protocol must be a dictionary");
88        };
89        protocol.insert("site".into(), Value::Dict(dict! { "pages" => pages }));
90        self.inputs.insert(INPUT_NAME.into(), Value::Dict(protocol));
91        self.library = library(&self.inputs);
92        self
93    }
94
95    /// Construct the context used to probe a dynamic template.
96    pub fn probe(&self) -> CompilationRuntime<'_> {
97        CompilationRuntime {
98            runtime: self,
99            route: RouteContext::default(),
100        }
101    }
102
103    /// Construct one route context that borrows this runtime's shared library.
104    pub fn for_route(&self, path: EcoString, params: &ParamSet) -> CompilationRuntime<'_> {
105        CompilationRuntime {
106            runtime: self,
107            route: RouteContext::new(path, params),
108        }
109    }
110}
111
112/// Dynamic Aster values supplied to one compilation over a shared [`Library`].
113pub struct CompilationRuntime<'a> {
114    runtime: &'a Runtime,
115    route: RouteContext,
116}
117
118impl CompilationRuntime<'_> {
119    pub fn library(&self) -> &LazyHash<Library> {
120        &self.runtime.library
121    }
122
123    /// Resolve an Aster-owned virtual file, or return `None` for other files.
124    pub fn resolve_file(&self, id: FileId) -> Option<FileResult<Bytes>> {
125        if !owns_runtime_file(id) {
126            return None;
127        }
128
129        let value = self
130            .route
131            .value(id)
132            .or_else(|| self.runtime.page_routes.value(id));
133        Some(
134            value
135                .cloned()
136                .map(Str::from)
137                .map(Bytes::from_string)
138                .ok_or_else(|| FileError::NotFound(id.vpath().get_with_slash().into())),
139        )
140    }
141}
142
143#[derive(Default)]
144struct RouteContext {
145    path: Option<EcoString>,
146    params: ParamSet,
147}
148
149impl RouteContext {
150    fn new(path: EcoString, params: &ParamSet) -> Self {
151        Self {
152            path: Some(path),
153            params: params.clone(),
154        }
155    }
156
157    fn path_id() -> FileId {
158        runtime_file_id("route/path")
159    }
160
161    fn param_id(name: &str) -> FileId {
162        runtime_file_id(&format!("route/params/{}", hex::encode(name)))
163    }
164
165    fn value(&self, id: FileId) -> Option<&EcoString> {
166        if id == Self::path_id() {
167            return self.path.as_ref();
168        }
169
170        let encoded = id
171            .vpath()
172            .get_without_slash()
173            .strip_prefix("route/params/")?;
174        let name = hex::decode(encoded).ok()?;
175        self.params.get(std::str::from_utf8(&name).ok()?)
176    }
177}
178
179#[derive(Default)]
180struct PageRoutes(Vec<EcoString>);
181
182impl PageRoutes {
183    fn new(pages: Vec<EcoString>) -> Self {
184        Self(pages)
185    }
186
187    fn id(index: usize) -> FileId {
188        runtime_file_id(&format!("routes/pages/{index}"))
189    }
190
191    fn value(&self, id: FileId) -> Option<&EcoString> {
192        let index = id
193            .vpath()
194            .get_without_slash()
195            .strip_prefix("routes/pages/")?
196            .parse::<usize>()
197            .ok()?;
198        self.0.get(index)
199    }
200}
201
202fn owns_runtime_file(id: FileId) -> bool {
203    matches!(id.root(), VirtualRoot::Package(package) if package == runtime_package())
204}
205
206fn runtime_file_id(path: &str) -> FileId {
207    RootedPath::new(
208        VirtualRoot::Package(runtime_package().clone()),
209        VirtualPath::new(path).expect("Aster runtime path must be valid"),
210    )
211    .intern()
212}
213
214fn runtime_package() -> &'static PackageSpec {
215    static PACKAGE: LazyLock<PackageSpec> = LazyLock::new(|| {
216        "@aster/runtime:0.1.0"
217            .parse()
218            .expect("Aster runtime package specification must be valid")
219    });
220    &PACKAGE
221}
222
223fn library(inputs: &Dict) -> LazyHash<Library> {
224    LazyHash::new(
225        Library::builder()
226            .with_inputs(inputs.clone())
227            .with_features([Feature::Html].into_iter().collect())
228            .build(),
229    )
230}
231
232/// One source entry exposed through Aster's lazy content protocol.
233pub struct ContentEntry {
234    /// Collection containing the entry.
235    pub collection: EcoString,
236    /// Entry identifier within its collection.
237    pub id: EcoString,
238    /// Typst source loaded by the entry's lazy accessors.
239    pub source: RootedPath,
240}
241
242/// One rendered page exposed to Typst generators.
243pub struct SitePage {
244    /// Browser-facing route of the page.
245    pub path: EcoString,
246    /// Complete final HTML document.
247    pub html: EcoString,
248    /// Optional labelled main-content fragment.
249    pub content: Option<SiteContent>,
250}
251
252/// The final HTML and plain text of a page's `<aster-content>` element.
253pub struct SiteContent {
254    pub html: EcoString,
255    pub text: EcoString,
256}
257
258fn protocol_value(
259    collections: BTreeMap<EcoString, Vec<(EcoString, RootedPath)>>,
260    dev: bool,
261) -> Value {
262    let mut packed_collections = Dict::new();
263    for (collection_name, entries) in collections {
264        let mut packed_entries = Dict::new();
265        for (id, source) in entries {
266            packed_entries.insert(
267                Str::from(id.as_str()),
268                Value::Module(entry_module(&collection_name, &id, source)),
269            );
270        }
271        packed_collections.insert(
272            Str::from(collection_name.as_str()),
273            Value::Dict(packed_entries),
274        );
275    }
276
277    Value::Dict(dict! {
278        "protocol" => PROTOCOL_VERSION,
279        "version" => ASTER_VERSION,
280        "dev" => dev,
281        "collections" => packed_collections,
282        "route" => route_module(),
283        "routes" => routes_module(),
284        "site" => dict! { "pages" => Array::new() },
285    })
286}
287
288fn route_module() -> Module {
289    let mut scope = Scope::new();
290    scope.define_func::<path>();
291    scope.define_func::<param>();
292    Module::new("route", scope)
293}
294
295fn routes_module() -> Module {
296    let mut scope = Scope::new();
297    scope.define_func::<pages>();
298    Module::new("routes", scope)
299}
300
301fn read(engine: &mut Engine, id: FileId, span: Span) -> SourceResult<Option<Str>> {
302    match engine.world.file(id) {
303        Ok(bytes) => bytes.to_str().map(Some).map_err(FileError::from).at(span),
304        Err(FileError::NotFound(_)) => Ok(None),
305        Err(error) => Err(error).at(span),
306    }
307}
308
309fn route_value(
310    engine: &mut Engine,
311    id: FileId,
312    default: Option<Value>,
313    span: Span,
314) -> SourceResult<Value> {
315    Ok(read(engine, id, span)?
316        .map(Value::Str)
317        .unwrap_or_else(|| default.unwrap_or(Value::None)))
318}
319
320/// Return the current browser-facing route path.
321#[func]
322fn path(
323    engine: &mut Engine,
324    span: Span,
325    /// A value returned while no concrete route is being compiled.
326    #[named]
327    default: Option<Value>,
328) -> SourceResult<Value> {
329    route_value(engine, RouteContext::path_id(), default, span)
330}
331
332/// Return one parameter of the current route.
333#[func]
334fn param(
335    engine: &mut Engine,
336    span: Span,
337    /// The route parameter name.
338    name: Str,
339    /// A value returned when the parameter is absent.
340    #[named]
341    default: Option<Value>,
342) -> SourceResult<Value> {
343    route_value(engine, RouteContext::param_id(name.as_str()), default, span)
344}
345
346/// Return all planned page browser paths in deterministic order.
347#[func]
348fn pages(engine: &mut Engine, span: Span) -> SourceResult<Array> {
349    let mut pages = Array::new();
350    for index in 0.. {
351        let Some(path) = read(engine, PageRoutes::id(index), span)? else {
352            break;
353        };
354        pages.push(Value::Str(path));
355    }
356    Ok(pages)
357}
358
359fn entry_module(collection: &EcoString, id: &EcoString, source: RootedPath) -> Module {
360    let mut scope = Scope::new();
361    scope.define("id", Str::from(id.as_str()));
362    scope.define("collection", Str::from(collection.as_str()));
363    scope.define("metadata", metadata_closure(source.clone()));
364    scope.define("render", render_closure(source));
365    Module::new(eco_format!("{collection}/{id}"), scope)
366}
367
368fn metadata_closure(source: RootedPath) -> Func {
369    const METADATA_CLOSURE_SOURCE: &str = r#"() => {
370  let find-frontmatter(node) = {
371    let fields = node.fields()
372    if fields.at("label", default: none) == <aster-frontmatter> {
373      let value = fields.at("value", default: (:))
374      return if type(value) == dictionary { value } else { (:) }
375    }
376
377    for value in fields.values() {
378      if type(value) == content {
379        let found = find-frontmatter(value)
380        if found != none { return found }
381      } else if type(value) == array {
382        for child in value {
383          if type(child) == content {
384            let found = find-frontmatter(child)
385            if found != none { return found }
386          }
387        }
388      }
389    }
390
391    none
392  }
393
394  import source as entry-module
395  let entry-content = include entry-module
396  let metadata = find-frontmatter(entry-content)
397  if metadata == none { (:) } else { metadata }
398}"#;
399
400    static METADATA_CLOSURE_NODE: LazyLock<SyntaxNode> =
401        LazyLock::new(|| parse_closure(METADATA_CLOSURE_SOURCE));
402
403    captured_closure(METADATA_CLOSURE_NODE.clone(), source)
404}
405
406fn render_closure(source: RootedPath) -> Func {
407    const RENDER_CLOSURE_SOURCE: &str = r#"() => {
408  import source as entry-module
409  include entry-module
410}"#;
411
412    static RENDER_CLOSURE_NODE: LazyLock<SyntaxNode> =
413        LazyLock::new(|| parse_closure(RENDER_CLOSURE_SOURCE));
414
415    captured_closure(RENDER_CLOSURE_NODE.clone(), source)
416}
417
418fn parse_closure(source: &str) -> SyntaxNode {
419    let root = parse_code(source);
420    let (errors, _) = root.errors_and_warnings();
421    assert!(errors.is_empty(), "Aster entry closure must parse");
422    let code = root
423        .cast::<ast::Code>()
424        .expect("entry closure must be code");
425    let mut expressions = code.exprs();
426    let ast::Expr::Closure(closure) = expressions.next().expect("entry closure must exist") else {
427        panic!("entry expression must be a closure");
428    };
429    assert!(
430        expressions.next().is_none(),
431        "entry closure must be the only expression"
432    );
433    closure.to_untyped().clone()
434}
435
436fn captured_closure(node: SyntaxNode, source: RootedPath) -> Func {
437    static CAPTURE_LIBRARY: LazyLock<Library> = LazyLock::new(Library::default);
438
439    let mut scopes = Scopes::new(Some(&CAPTURE_LIBRARY));
440    scopes.top.define("source", source);
441
442    let mut captures = CapturesVisitor::new(Some(&scopes), Capturer::Function);
443    captures.visit(&node);
444    Func::from(Closure {
445        node: ClosureNode::Closure(node),
446        defaults: Vec::new(),
447        captured: captures.finish(),
448        num_pos_params: 0,
449    })
450}
451
452#[cfg(test)]
453mod tests {
454    use super::*;
455    use typst::syntax::{VirtualPath, VirtualRoot};
456
457    fn empty() -> Runtime {
458        Runtime::new(std::iter::empty(), false)
459    }
460
461    #[test]
462    fn protocol_contains_lazy_entry_modules() {
463        let runtime = Runtime::new(
464            [ContentEntry {
465                collection: "blog".into(),
466                id: "nested/post".into(),
467                source: RootedPath::new(
468                    VirtualRoot::Project,
469                    VirtualPath::new("content/blog/nested/post.typ").unwrap(),
470                ),
471            }],
472            false,
473        );
474
475        let Value::Dict(protocol) = runtime.inputs.get(INPUT_NAME).unwrap() else {
476            panic!("protocol must be a dictionary");
477        };
478        let Value::Dict(collections) = protocol.get("collections").unwrap() else {
479            panic!("collections must be a dictionary");
480        };
481        let Value::Dict(blog) = collections.get("blog").unwrap() else {
482            panic!("collection must be a dictionary");
483        };
484        let Value::Module(entry) = blog.get("nested/post").unwrap() else {
485            panic!("entry must be a module");
486        };
487        assert_eq!(
488            entry.field("id", ()).unwrap(),
489            &Value::Str(Str::from("nested/post"))
490        );
491        assert_eq!(
492            entry.field("collection", ()).unwrap(),
493            &Value::Str(Str::from("blog"))
494        );
495        assert!(matches!(
496            entry.field("metadata", ()).unwrap(),
497            Value::Func(_)
498        ));
499        assert!(matches!(entry.field("render", ()).unwrap(), Value::Func(_)));
500        assert!(entry.field("file-path", ()).is_err());
501        assert!(entry.field("content", ()).is_err());
502    }
503
504    #[test]
505    fn empty_protocol_has_one_owner() {
506        let runtime = empty();
507        let Value::Dict(protocol) = runtime.inputs.get(INPUT_NAME).unwrap() else {
508            panic!("protocol must be a dictionary");
509        };
510        assert_eq!(
511            protocol.get("protocol").unwrap(),
512            &Value::Int(PROTOCOL_VERSION)
513        );
514        assert_eq!(
515            protocol.get("collections").unwrap(),
516            &Value::Dict(Dict::new())
517        );
518        assert_eq!(
519            protocol.get("version").unwrap(),
520            &Value::Str(Str::from(ASTER_VERSION))
521        );
522        assert_eq!(protocol.get("dev").unwrap(), &Value::Bool(false));
523        let Value::Module(route) = protocol.get("route").unwrap() else {
524            panic!("route protocol must be a module");
525        };
526        assert!(matches!(route.field("path", ()).unwrap(), Value::Func(_)));
527        assert!(matches!(route.field("param", ()).unwrap(), Value::Func(_)));
528    }
529
530    #[test]
531    fn protocol_exposes_development_mode() {
532        let runtime = Runtime::new(std::iter::empty(), true);
533        let Value::Dict(protocol) = runtime.inputs.get(INPUT_NAME).unwrap() else {
534            panic!("protocol must be a dictionary");
535        };
536
537        assert_eq!(protocol.get("dev").unwrap(), &Value::Bool(true));
538    }
539
540    #[test]
541    fn compilation_runtime_resolves_virtual_files_without_changing_the_protocol() {
542        let base = empty();
543        let library = base.library.clone();
544        let base = base.with_page_routes(vec!["/".into(), "/blog/post/".into()]);
545        assert!(base.library == library);
546        let params = crate::engine::route::ParamSet::from([
547            ("site".into(), "route".into()),
548            (INPUT_NAME.into(), "nested".into()),
549            ("..".into(), "parent".into()),
550        ]);
551        let runtime = base.for_route("/blog/post/".into(), &params);
552
553        assert_eq!(base.inputs.len(), 1);
554        let Value::Dict(protocol) = base.inputs.get(INPUT_NAME).unwrap() else {
555            panic!("runtime protocol must be a dictionary");
556        };
557        let Value::Module(route_module) = protocol.get("route").unwrap() else {
558            panic!("route protocol must be a module");
559        };
560        assert_eq!(
561            runtime
562                .resolve_file(RouteContext::path_id())
563                .unwrap()
564                .unwrap()
565                .to_str()
566                .unwrap(),
567            Str::from("/blog/post/")
568        );
569        assert_eq!(
570            runtime
571                .resolve_file(RouteContext::param_id("site"))
572                .unwrap()
573                .unwrap()
574                .to_str()
575                .unwrap(),
576            Str::from("route")
577        );
578        assert_eq!(
579            runtime
580                .resolve_file(RouteContext::param_id(INPUT_NAME))
581                .unwrap()
582                .unwrap()
583                .to_str()
584                .unwrap(),
585            Str::from("nested")
586        );
587        assert_eq!(
588            runtime
589                .resolve_file(RouteContext::param_id(".."))
590                .unwrap()
591                .unwrap()
592                .to_str()
593                .unwrap(),
594            Str::from("parent")
595        );
596        assert!(
597            runtime
598                .resolve_file(RouteContext::param_id("missing"))
599                .unwrap()
600                .is_err()
601        );
602        assert!(matches!(
603            route_module.field("path", ()).unwrap(),
604            Value::Func(_)
605        ));
606        let Value::Module(routes) = protocol.get("routes").unwrap() else {
607            panic!("planned routes must be a module");
608        };
609        assert!(matches!(routes.field("pages", ()).unwrap(), Value::Func(_)));
610        assert_eq!(
611            runtime
612                .resolve_file(PageRoutes::id(0))
613                .unwrap()
614                .unwrap()
615                .to_str()
616                .unwrap(),
617            Str::from("/")
618        );
619        assert_eq!(
620            runtime
621                .resolve_file(PageRoutes::id(1))
622                .unwrap()
623                .unwrap()
624                .to_str()
625                .unwrap(),
626            Str::from("/blog/post/")
627        );
628        assert!(runtime.resolve_file(PageRoutes::id(2)).unwrap().is_err());
629        assert!(routes.field("endpoints", ()).is_err());
630    }
631
632    #[test]
633    fn site_snapshot_exposes_final_page_content() {
634        let runtime = empty().with_site(&[SitePage {
635            path: "/post/".into(),
636            html: "<html>...</html>".into(),
637            content: Some(SiteContent {
638                html: "<article>Post</article>".into(),
639                text: "Post".into(),
640            }),
641        }]);
642        let Value::Dict(protocol) = runtime.inputs.get(INPUT_NAME).unwrap() else {
643            panic!("runtime protocol must be a dictionary");
644        };
645        let Value::Dict(site) = protocol.get("site").unwrap() else {
646            panic!("site snapshot must be a dictionary");
647        };
648        let Value::Array(pages) = site.get("pages").unwrap() else {
649            panic!("site pages must be an array");
650        };
651        assert_eq!(pages.len(), 1);
652    }
653}