feat: more convenient way to integrate projects

.gitmodules

@@ -6,3 +6,18 @@
 	path = assets/files
 	url = https://github.com/Myriad-Dreamin/typst.git
 	branch = assets-files
+
+[submodule "projects/typst-preview"]
+	path = projects/typst-preview
+	url = https://github.com/Enter-tainer/typst-preview.git
+	branch = main
+	fetchRecurseSubmodules = false
+	update=none
+	ignore=all
+[submodule "projects/typst-book"]
+	path = projects/typst-book
+	url = https://github.com/Myriad-Dreamin/typst-book.git
+	branch = main
+	fetchRecurseSubmodules = false
+	update=none
+	ignore=all

Cargo.toml

@@ -37,6 +37,7 @@ members = [
     "tests/integration",
     "tests/std",
 ]
+exclude = ["projects"]
 
 [profile.release]
 opt-level = 3

README.md

@@ -48,7 +48,7 @@ So with _Form2_, you can continue rendeing the document in different ways:
 
 ##### Static but <ins>responsive</ins> rendering
 
-Example Application: [single-file](https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/index.html), [typst-book](https://github.com/Myriad-Dreamin/typst-book) and [hexo-renderer-typst](https://github.com/Myriad-Dreamin/typst.ts/tree/main/packages/hexo-renderer-typst)
+Example Application: [single-file](https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/index.html), [typst-book](https://github.com/Myriad-Dreamin/typst-book) and [hexo-renderer-typst](https://github.com/Myriad-Dreamin/typst.ts/tree/main/projects/hexo-renderer-typst)
 
 A compressed artifact containing data for different theme and screen settings. The bundle size of artifacts is optimized for typst documents.
 
@@ -115,6 +115,46 @@ it has the git dependency on [typst](https://github.com/typst/typst).
 
 See [Documentation](https://myriad-dreamin.github.io/typst.ts/cookery).
 
+### Develop projects along with a local built typst.ts
+
+You can put your owned projects under the `projects` folder, and that yarn workspace will
+automatically identify your project. We recommend you to use [git](https://git-scm.com/), [Yarn](https://yarnpkg.com/), and
+[turbo](https://turbo.build/) to manage your projects.
+
+##### Example: link a project by git submodule
+
+To develop core external projects, e.g. `typst-preview`, you could initialize them
+by command:
+
+```shell
+git submodule update --init --checkout projects/typst-preview
+```
+
+##### Example: build and run
+
+Ensured that you have [built typst.ts from
+source](#build-from-source-and-check), you can build and run the project by
+(typst-preview as an example):
+
+```shell
+# install dependencies for project
+yarn install --pure-lockfile
+# build typst-preview and its dependencies
+turbo build --filter=typst-preview
+@myriaddreamin/typst-ts-renderer:build: cache hit, replaying logs bc0a0b151bd8eb6d
+@myriaddreamin/typst.ts:build: cache hit, replaying logs 729cb43a3242b80
+typst-preview-frontend:build: cache miss, executing 5ae30471e8957877
+typst-preview-frontend:build: ...
+typst-preview-frontend:build: ✓ built in 1.25s
+typst-preview-frontend:build: Done in 4.57s.
+typst-preview:build: cache miss, executing a1bd8ca8233f8a0c
+typst-preview:build: ...
+typst-preview:build: ✓ built in 1.01s
+typst-preview:build: Done in 3.73s.
+```
+
+The project (typst-preview as an example) will cache and use the local built packages.
+
 ### Build from source and check
 
 Note: you could build from source with/without wasm-pack.
@@ -127,7 +167,7 @@ Note: Since we use turborepo for `>=v0.4.0` development, if you are the earlier
 # Optional: download the font assets if you haven't done so.
 $ git submodule update --init --recursive .
 # build all of typescript packages
-$ yarn install && npx turbo run build
+$ yarn install && yarn run build:pkg
 # compile typst document for demo
 $ cargo run --bin typst-ts-dev-server -- compile --compiler debug corpus --cat skyzh-cv
 # start a local server
@@ -136,7 +176,7 @@ $ cargo run --bin typst-ts-dev-server -- run http --corpus ./fuzzers/corpora/
 
 And open your browser to `http://localhost:20810/`.
 
-You can also run `yarn run build:core` instead of `npx turbo run build` to build
+You can also run `yarn run build:core` instead of `yarn run build:pkg` to build
 core library (`@myriaddreamin/typst.ts`) and avoid building the WASM modules from source.
 
 <!-- ### Example: generate documentation site for packages developers.

core/src/error.rs

@@ -1,13 +1,87 @@
 use core::fmt;
 
 use ecow::EcoString;
-use typst::diag::FileError;
+use typst::{diag::FileError, syntax::Source};
+
+use crate::ImmutStr;
+
+pub use typst::diag::SourceDiagnostic as TypstSourceDiagnostic;
+
+#[derive(Debug, Clone)]
+pub struct DiagMessage {
+    pub resource: ImmutStr,
+    pub message: String,
+    pub code: u32,
+    pub severity: u32,
+    pub start_line_number: u32,
+    pub start_column: u32,
+    pub end_line_number: u32,
+    pub end_column: u32,
+    // These field could be added to ErrorImpl::arguments
+    // owner: Option<ImmutStr>,
+    // source: ImmutStr,
+}
+
+pub trait ErrorConverter {
+    // todo: file_id to path
+    /// Convert typst.ts diagnostic to error
+    /// It has a simple implementation.
+    /// If you want to customize it, you can implement it yourself.
+    fn convert_typst(&self, world: &dyn typst::World, diag: TypstSourceDiagnostic) -> Error {
+        let mut arguments = Vec::new();
+        arguments.push((
+            "severity",
+            match diag.severity {
+                typst::diag::Severity::Error => "error".to_string(),
+                typst::diag::Severity::Warning => "warning".to_string(),
+            },
+        ));
+
+        if let Some(id) = diag.span.id() {
+            if let Some(pkg) = id.package() {
+                arguments.push(("package", pkg.to_string()));
+            };
+            arguments.push(("path", format!("{:?}", id.vpath())));
+
+            if let Some((rng, src)) = world
+                .source(id)
+                .ok()
+                .and_then(|src| Some((src.find(diag.span)?.range(), src)))
+            {
+                let resolve_off =
+                    |src: &Source, off: usize| src.byte_to_line(off).zip(src.byte_to_column(off));
+                if let Some((l, c)) = resolve_off(&src, rng.start) {
+                    arguments.push(("start_line", l.to_string()));
+                    arguments.push(("start_column", c.to_string()));
+                }
+                if let Some((l, c)) = resolve_off(&src, rng.start) {
+                    arguments.push(("end_line", l.to_string()));
+                    arguments.push(("end_column", c.to_string()));
+                }
+            }
+        }
+
+        Error::new(
+            "typst",
+            ErrKind::Msg(format!(
+                "{msg}, hints: {hints:?}, traces: {traces:?}",
+                msg = diag.message,
+                hints = diag.hints,
+                traces = diag.trace
+            )),
+            arguments.into_boxed_slice(),
+        )
+    }
+}
+
+impl DiagMessage {}
 
 #[derive(Debug, Clone)]
 #[non_exhaustive]
 pub enum ErrKind {
     None,
     Msg(String),
+    Diag(DiagMessage),
     File(FileError),
     Inner(Error),
 }
@@ -110,6 +184,9 @@ impl fmt::Display for Error {
         match &err.kind {
             ErrKind::File(e) => write!(f, "{}: {} with {:?}", err.loc, e, err.arguments),
             ErrKind::Msg(msg) => write!(f, "{}: {} with {:?}", err.loc, msg, err.arguments),
+            ErrKind::Diag(diag) => {
+                write!(f, "{}: {} with {:?}", err.loc, diag.message, err.arguments)
+            }
             ErrKind::Inner(e) => write!(f, "{}: {} with {:?}", err.loc, e, err.arguments),
             ErrKind::None => write!(f, "{}: with {:?}", err.loc, err.arguments),
         }

package.json

@@ -14,23 +14,29 @@
   "workspaces": [
     "packages/compiler",
     "packages/renderer",
-    "packages/hexo-renderer-typst",
     "packages/typst.ts",
     "packages/typst.react",
     "packages/typst.vue3",
     "packages/typst.angular",
-    "packages/templates/*"
+    "packages/templates/*",
+    "projects/**/*"
   ],
   "scripts": {
     "dev": "cargo run --bin typst-ts-dev-server -- run http --corpus ./fuzzers/corpora/",
+    "install:pure": "yarn install --pure-lockfile",
     "build:core": "yarn workspace @myriaddreamin/typst.ts build",
+    "build:pkg": "turbo build --filter=./packages/*",
+    "build:proj": "turbo build --filter=./projects/*",
     "start:react": "yarn workspace @myriaddreamin/typst.react start",
     "start:angular": "yarn workspace typst.angular start",
     "book": "typst-book serve --font-path assets/fonts -w . docs/cookery",
     "bump-packages": "python scripts/bump_version.py",
-    "prepublish-packages": "turbo run prepublish",
-    "publish:dry": "turbo run prepublish publish:dry",
-    "publish:lib": "turbo run prepublish publish:lib",
+    "prepublish-packages": "turbo run prepublish --filter=./packages/*",
+    "publish:dry": "turbo run prepublish publish:dry --filter=./packages/*",
+    "publish:lib": "turbo run prepublish publish:lib --filter=./packages/*",
+    "notes:clone-proj": "assets/fonts is the dummy project for cmd, and you should specify a project for cloning",
+    "example:clone-proj": "yarn run clone-proj projects/typst-book",
+    "clone-proj": "git submodule update --init --checkout assets/fonts",
     "md": "yarn run md0 && yarn run md1 && yarn run md2 && yarn run md3",
     "md0": "cargo run --bin typst-ts-cli -- compile --workspace . --entry ./github-pages/docs/ir-features.typ --format=svg",
     "md1": "cargo run --bin typst-ts-cli -- compile --workspace . --entry ./github-pages/docs/ir-features.dark.typ --format=svg",

scripts/bump_version.py

@@ -41,7 +41,7 @@ def main(old_version: str, new_version: str):
       "package.json",
       "packages/compiler/package.json",
       "packages/renderer/package.json",
-      "packages/hexo-renderer-typst/package.json",
+      "projects/hexo-renderer-typst/package.json",
       "packages/typst.ts/package.json",
       "packages/typst.react/package.json",
       "packages/typst.angular/projects/typst.angular/package.json",