@tishlang/tish-format 2.39.0 → 3.0.0

package/crates/tish_compile/src/resolve.rs

@@ -22,6 +22,11 @@ pub struct ResolvedNativeModule {
     pub export_fn: String,
     /// When false, omit `path = …` in the generated Cargo.toml (crate comes from `tish.rustDependencies` only).
     pub use_path_dependency: bool,
+    /// The crate's own SOURCE directory (where its `Cargo.toml`/`src` live), when known — distinct from
+    /// `crate_path` (the importing project root). Used to find a `tish.d.tish` the crate ships (typed
+    /// externs). For a `cargo:` dep it's the resolved `rustDependencies` path; for a `tish.module`
+    /// package it's the package dir; `None` for registry deps with no local path.
+    pub source_dir: Option<PathBuf>,
 }
 
 /// How codegen links a native import to Rust (`generateNativeWrapper` for `tish:*`; `cargo:*` always generated).
@@ -39,6 +44,18 @@ pub enum NativeModuleInit {
     },
 }
 
+impl NativeModuleInit {
+    /// The Rust crate name whose functions back this module — the path for a direct typed call
+    /// (`<crate_name>::name_typed(..)`). Both variants carry it (Legacy directly, Generated as the
+    /// shim crate the generated namespace forwards to).
+    pub fn crate_name(&self) -> &str {
+        match self {
+            NativeModuleInit::Legacy { crate_name, .. } => crate_name,
+            NativeModuleInit::Generated { shim_crate, .. } => shim_crate,
+        }
+    }
+}
+
 /// Extra native build inputs produced alongside Rust source (Cargo merge + optional wrapper).
 #[derive(Debug, Clone)]
 pub struct NativeBuildArtifacts {
@@ -122,6 +139,11 @@ pub fn resolve_native_modules(
             if is_builtin_native_spec(&s) {
                 continue;
             }
+            // `asset:` loads are baked into the ROM by the GBA codegen, not linked as native
+            // modules — they have no crate to resolve and no Value wrapper to generate.
+            if crate::schemes::is_scheme_import(&s) {
+                continue;
+            }
             if !seen.insert(s.clone()) {
                 continue;
             }
@@ -378,6 +400,17 @@ fn resolve_cargo_native_module(
     let crate_path = project_root
         .canonicalize()
         .unwrap_or_else(|_| project_root.to_path_buf());
+    // The crate's own source dir, from a `rustDependencies` `path` (so we can find its `tish.d.tish`).
+    let source_dir = rust_deps
+        .get(&dep_key)
+        .and_then(|v| v.as_object())
+        .and_then(|o| o.get("path"))
+        .and_then(|p| p.as_str())
+        .map(|raw| {
+            let p = Path::new(raw);
+            let resolved = if p.is_absolute() { p.to_path_buf() } else { project_root.join(p) };
+            resolved.canonicalize().unwrap_or(resolved)
+        });
     Ok(ResolvedNativeModule {
         spec: spec.to_string(),
         package_name: dep_key.clone(),
@@ -385,6 +418,7 @@ fn resolve_cargo_native_module(
         crate_path,
         export_fn,
         use_path_dependency: false,
+        source_dir,
     })
 }
 
@@ -437,9 +471,11 @@ fn resolve_native_module(spec: &str, project_root: &Path) -> Result<ResolvedNati
         spec: spec.to_string(),
         package_name: raw_crate.clone(),
         crate_name: raw_crate.replace('-', "_"),
-        crate_path,
+        crate_path: crate_path.clone(),
         export_fn,
         use_path_dependency: true,
+        // A tish.module package IS its own source dir — that's where any `tish.d.tish` lives.
+        source_dir: Some(crate_path),
     })
 }
 
@@ -561,7 +597,7 @@ pub fn infer_native_module_exports(program: &Program) -> HashMap<String, HashSet
                 ..
             } => {
                 let s = spec.as_ref();
-                if is_builtin_native_spec(s) {
+                if is_builtin_native_spec(s) || crate::schemes::is_scheme_import(s) {
                     continue;
                 }
                 map.entry(s.to_string())
@@ -709,6 +745,13 @@ fn find_package_dir(package_name: &str, project_root: &Path) -> Result<PathBuf,
         {
             return Ok(node_mod);
         }
+        let apple_crate = search.join("tish-apple").join("crates").join(package_name);
+        if apple_crate.join("package.json").exists()
+            && read_package_name(&apple_crate.join("package.json"))
+                == Some(package_name.to_string())
+        {
+            return Ok(apple_crate);
+        }
         let sibling = search.join(package_name);
         if sibling.join("package.json").exists()
             && read_package_name(&sibling.join("package.json")) == Some(package_name.to_string())
@@ -876,7 +919,7 @@ pub fn resolve_project_from_stdin(
 
     for stmt in &program.statements {
         if let Some(from) = stmt_module_dep(stmt) {
-            if is_native_import(from.as_ref()) {
+            if is_native_import(from.as_ref()) || is_scoped_native_import(from.as_ref(), from_dir) || crate::schemes::is_scheme_import(from.as_ref()) {
                 continue;
             }
             let dep_path = resolve_import_path(from.as_ref(), from_dir, &root_canon)?;
@@ -944,7 +987,7 @@ fn load_module_recursive(
     let dir = canonical.parent().unwrap_or(Path::new("."));
     for stmt in &program.statements {
         if let Some(from) = stmt_module_dep(stmt) {
-            if is_native_import(from.as_ref()) {
+            if is_native_import(from.as_ref()) || is_scoped_native_import(from.as_ref(), dir) || crate::schemes::is_scheme_import(from.as_ref()) {
                 continue; // Native imports don't load files
             }
             let dep_path = resolve_import_path(from.as_ref(), dir, project_root)?;
@@ -971,7 +1014,13 @@ fn load_module_recursive(
 /// - cargo:… (Cargo `rustDependencies` + generated wrapper; Rust native backend)
 /// - ffi:… (a C-ABI cdylib loaded via `tish_ffi::load_module` — portable across backends)
 ///
-/// Scoped npm packages (`@scope/pkg`) are merged as Tish source unless imported via `tish:…`.
+/// Scoped npm packages (`@scope/pkg`) are **merged as Tish source** by default — they are NOT
+/// native imports and fall through to the module-merge resolver (`exports.tish` / `tish.module`
+/// path / `tish.source` / `index.tish`). A scoped package is only treated as a native Rust crate
+/// when it opts in via `tish.crate` / `tish.rustDependencies` in its package.json (the tish-apple
+/// crates). This split is why `@scope` is intentionally absent below (#38): matching the ecosystem's
+/// resolution for `import … from "@scope/pkg"` is interop, and the native-vs-merged axis is the one
+/// piece tish adds on top, keyed off the native markers rather than mere presence of `tish.module`.
 pub fn is_native_import(spec: &str) -> bool {
     // A leading `node:` (node:fs, node:fs/promises) resolves the same as the bare form.
     let spec = spec.strip_prefix("node:").unwrap_or(spec);
@@ -984,6 +1033,39 @@ pub fn is_native_import(spec: &str) -> bool {
         )
 }
 
+// Import schemes (`asset:` and any project-declared prefix) are recognized via the active
+// [`crate::schemes`] registry — `crate::schemes::is_scheme_import(spec)`. Like native imports, a
+// scheme spec is NOT resolved as a `.tish` module or npm package; unlike them it links no crate and
+// generates no Value wrapper — the codegen injects the scheme's include macro and binds each name to
+// an i32 handle. See [`resolve_scheme_spec`] for the file-resolution half.
+
+/// The `@scope/pkg` native opt-in described above (#38): true only when the package resolves and
+/// its package.json carries the native markers — `tish.module == true` (the native-module flag, a
+/// bool; a string is a merged-source entry path) AND `tish.crate` / `tish.rustDependencies` (the
+/// Rust-crate opt-in). Anything else — unresolvable, plain `tish.module: true` with no crate
+/// (#38), or a `.tish` source package like `@tishlang/pg` — falls through to the module-merge
+/// resolver. Package resolution walks up from `from_dir` (the importing module's directory), the
+/// same walk [`resolve_native_module`] later repeats from the project root.
+pub fn is_scoped_native_import(spec: &str, from_dir: &Path) -> bool {
+    if !spec.starts_with('@') {
+        return false;
+    }
+    let Ok(pkg_dir) = find_package_dir(spec, from_dir) else {
+        return false;
+    };
+    let Ok(content) = std::fs::read_to_string(pkg_dir.join("package.json")) else {
+        return false;
+    };
+    let Ok(json) = serde_json::from_str::<serde_json::Value>(&content) else {
+        return false;
+    };
+    let Some(tish) = json.get("tish") else {
+        return false;
+    };
+    tish.get("module").and_then(|v| v.as_bool()).unwrap_or(false)
+        && (tish.get("crate").is_some() || tish.get("rustDependencies").is_some())
+}
+
 /// True for `ffi:…` specs (portable C-ABI cdylib extensions, loadable on every backend). The
 /// path after `ffi:` is resolved relative to the importing program and loaded with
 /// `tish_ffi::load_module`. Unlike `cargo:` (rust-AOT only), `ffi:` is allowed everywhere.
@@ -1070,6 +1152,63 @@ pub fn resolve_bare_spec(spec: &str, from_dir: &Path, _project_root: &Path) -> O
     None
 }
 
+/// Resolve a scheme import (`asset:relpath`, or any project-declared scheme) to a canonical spec.
+/// For a `resolve_file` scheme, the part after the colon is resolved against the importing module's
+/// directory (`from_dir`) to an absolute path that must exist — a missing file is a compile-time
+/// error, not a device panic — and the spec becomes `prefix:/abs/path` (the codegen feeds that
+/// absolute path to the scheme's include macro; agb's `resolve_path` takes absolute paths as-is, so
+/// no asset-copy step is needed). A trailing `@N` on the path (e.g. `font:face.ttf@7`) is stripped
+/// before canonicalize and reattached on the canonical spec so `{size}` is available at emit. A
+/// bare `font:path` (no `@N`) defaults to [`crate::schemes::FONT_DEFAULT_SIZE`]. A non-`resolve_file`
+/// scheme passes through unchanged.
+fn resolve_scheme_spec(spec: &str, from_dir: &Path) -> Result<String, String> {
+    let (scheme_name, prefix, resolve_file) = crate::schemes::with_active(|reg| {
+        reg.matches(spec)
+            .map(|s| (s.name.clone(), s.prefix(), s.resolve_file))
+    })
+    .ok_or_else(|| format!("import '{}' is not a registered scheme", spec))?;
+    let rest = spec.strip_prefix(&prefix).unwrap_or(spec);
+    if !resolve_file {
+        return Ok(spec.to_string());
+    }
+    if rest.is_empty() {
+        return Err(format!(
+            "{} import needs a path, e.g. import {{ player }} from '{}gfx/player.png'",
+            prefix.trim_end_matches(':'),
+            prefix
+        ));
+    }
+    let (file_rest, size_opt) = crate::schemes::split_path_size(rest);
+    let path = Path::new(file_rest);
+    let joined = if path.is_absolute() {
+        path.to_path_buf()
+    } else {
+        from_dir.join(path)
+    };
+    let abs = joined.canonicalize().map_err(|e| {
+        format!(
+            "{} import '{}': cannot find '{}' (resolved from {}): {}",
+            prefix.trim_end_matches(':'),
+            spec,
+            file_rest,
+            from_dir.display(),
+            e
+        )
+    })?;
+    let mut out = format!("{}{}", prefix, abs.to_string_lossy());
+    // `font:` always carries an explicit size in the canonical spec (explicit @N, or default 16).
+    if scheme_name == "font" {
+        let size = size_opt.unwrap_or(crate::schemes::FONT_DEFAULT_SIZE);
+        out.push('@');
+        out.push_str(&size.to_string());
+    } else if let Some(size) = size_opt {
+        // Other schemes may use `@N` + `{size}` later; preserve when present.
+        out.push('@');
+        out.push_str(&size.to_string());
+    }
+    Ok(out)
+}
+
 /// Resolve an import specifier (e.g. "./foo.tish", "../lib/utils", "lattish") to an absolute path.
 fn resolve_import_path(
     spec: &str,
@@ -1091,8 +1230,12 @@ fn resolve_import_path(
             spec, spec
         ));
     }
+    let ctx = crate::platform_resolve::resolve_context();
+    if let Some(path) = crate::platform_resolve::resolve_with_platform(spec, from_dir, ctx) {
+        return Ok(path);
+    }
     let base = from_dir.join(spec);
-    // Try with .tish extension if the path has no extension
+    // Fallback: legacy single .tish probe when platform context is empty / file missing
     let path = if base.extension().is_none() {
         let with_ext = base.with_extension("tish");
         if with_ext.exists() {
@@ -1155,7 +1298,7 @@ fn has_cycle_from(
 ) -> Result<bool, String> {
     for stmt in &program.statements {
         if let Some(from) = stmt_module_dep(stmt) {
-            if is_native_import(from.as_ref()) {
+            if is_native_import(from.as_ref()) || is_scoped_native_import(from.as_ref(), from_dir) || crate::schemes::is_scheme_import(from.as_ref()) {
                 continue;
             }
             let dep_path = resolve_import_path(from.as_ref(), from_dir, Path::new("."))?;
@@ -1837,10 +1980,20 @@ pub fn merge_modules(mut modules: Vec<ResolvedModule>) -> Result<MergedProgram,
                     from,
                     span,
                 } => {
-                    if is_native_import(from.as_ref()) {
-                        // Normalize fs/http/process -> tish:fs etc. for Node compatibility
-                        let canonical_spec = normalize_builtin_spec(from.as_ref())
-                            .unwrap_or_else(|| from.to_string());
+                    if is_native_import(from.as_ref())
+                        || is_scoped_native_import(from.as_ref(), dir)
+                        || crate::schemes::is_scheme_import(from.as_ref())
+                    {
+                        // Normalize fs/http/process -> tish:fs etc. for Node compatibility.
+                        // For `asset:` imports, resolve the (relative) file path to an absolute
+                        // one now, while we still know the importing module's directory — the GBA
+                        // codegen emits `include_aseprite_inner!("<abspath>")` from that spec.
+                        let canonical_spec = if crate::schemes::is_scheme_import(from.as_ref()) {
+                            resolve_scheme_spec(from.as_ref(), dir)?
+                        } else {
+                            normalize_builtin_spec(from.as_ref())
+                                .unwrap_or_else(|| from.to_string())
+                        };
                         // Emit VarDecl with NativeModuleLoad for each specifier
                         for spec in specifiers {
                             match spec {
@@ -2090,3 +2243,34 @@ mod cargo_spec_tests {
         );
     }
 }
+
+#[cfg(test)]
+mod find_package_dir_tests {
+    use super::find_package_dir;
+
+    #[test]
+    fn prefers_tish_apple_crates_over_sibling() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let root = dir.path();
+        // sibling decoy
+        let sibling = root.join("tish-macos");
+        std::fs::create_dir_all(&sibling).unwrap();
+        std::fs::write(
+            sibling.join("package.json"),
+            r#"{"name":"tish-macos","tish":{"module":true,"crate":"tishlang_macos","export":"macos_object"}}"#,
+        )
+        .unwrap();
+        // preferred apple path
+        let apple = root.join("tish-apple").join("crates").join("tish-macos");
+        std::fs::create_dir_all(&apple).unwrap();
+        std::fs::write(
+            apple.join("package.json"),
+            r#"{"name":"tish-macos","tish":{"module":true,"crate":"tish-macos","export":"macos_object"}}"#,
+        )
+        .unwrap();
+        let project = root.join("app");
+        std::fs::create_dir_all(&project).unwrap();
+        let hit = find_package_dir("tish-macos", &project).expect("resolve");
+        assert_eq!(hit.canonicalize().unwrap(), apple.canonicalize().unwrap());
+    }
+}

package/crates/tish_compile/src/schemes.rs

@@ -0,0 +1,333 @@
+//! Import-scheme registry — the extension seam for custom import prefixes.
+//!
+//! An *import scheme* is a prefix like `asset:` that means "don't resolve this as a `.tish` module
+//! or npm package; instead resolve it my way and inject my code." tish core ships **no** built-in
+//! schemes — it is target-agnostic (see [`SchemeRegistry::builtin`]). Schemes are contributed by
+//! cargo path-dependencies that ship a `tish.schemes.json` (this is how `tish-agb` provides
+//! `asset:`/`sheet:`/`background:`/`wav:`/`map:` for free to any game that depends on it) and by a
+//! project's own `package.json` → `tish.schemes`, with no changes to the compiler. This is the same
+//! philosophy as `cargo:` imports (config-declared, zero core edits per crate), generalized.
+//!
+//! A scheme is described declaratively:
+//! * `prefix` — the scheme name (`asset` → matches `asset:...`).
+//! * `resolve_file` — resolve the rest as a project-relative file and validate it exists.
+//! * `targets` — per emit-target ("gba", …) code templates: the `use`s + body of a generated
+//!   `mod`, an accessor, and a registration call. Templates substitute `{path}` (the resolved
+//!   absolute path, as a Rust string literal), `{mod}` (the generated module's identifier),
+//!   `{charset}` (used non-ASCII chars), and optionally `{size}` (from a trailing `@N` on the path).
+//!
+//! Only *file-baking* schemes are expressible this way today — the family `asset:` belongs to
+//! (resolve a file → emit a macro + a registration + bind an i32 handle). Schemes needing
+//! compile-time logic (e.g. parsing aseprite tags) will want a code-plugin surface later.
+//!
+//! The active registry is compile-scoped: [`set_active`] installs it at the start of a build and
+//! the resolve/codegen predicates read it via [`with_active`]. It defaults to [`builtin`] so any
+//! path that doesn't install one still sees the built-in schemes (matching prior behaviour).
+
+use std::cell::RefCell;
+use std::collections::HashMap;
+use std::path::Path;
+
+/// What an imported name binds to. Only `Handle` (an `i32` index into a runtime arena) exists
+/// today; kept as an enum so richer bindings (typed structs, const data) can be added later.
+#[derive(Clone, Debug, PartialEq)]
+pub enum BindKind {
+    /// The imported name is an `i32` handle — its index among the scheme's registered files.
+    Handle,
+}
+
+/// One emit target's code templates for a scheme (e.g. the `gba` recipe for `asset:`).
+#[derive(Clone, Debug)]
+pub struct TargetEmit {
+    /// `use` lines placed at the top of the generated `mod`.
+    pub uses: Vec<String>,
+    /// The module body — typically the include macro. `{path}` → the file as a Rust string literal.
+    pub module_body: String,
+    /// A public accessor emitted inside the same `mod` (so it can see the macro's private statics).
+    pub accessor: String,
+    /// Registration call emitted in the entry before `run()`. `{mod}` → the generated module ident.
+    pub register: String,
+    /// What each imported name binds to.
+    pub bind: BindKind,
+}
+
+/// A declaratively-described import scheme.
+#[derive(Clone, Debug)]
+pub struct SchemeDef {
+    /// The prefix WITHOUT the trailing colon (`asset`); matches specs starting `asset:`.
+    pub name: String,
+    /// Resolve the part after the colon as a project-relative file (canonicalize + validate exists).
+    pub resolve_file: bool,
+    /// Per emit-target code templates.
+    pub targets: HashMap<String, TargetEmit>,
+}
+
+impl SchemeDef {
+    /// The spec prefix including the colon (`asset:`).
+    pub fn prefix(&self) -> String {
+        format!("{}:", self.name)
+    }
+}
+
+/// The set of active import schemes for a build.
+#[derive(Clone, Debug, Default)]
+pub struct SchemeRegistry {
+    pub schemes: Vec<SchemeDef>,
+}
+
+impl SchemeRegistry {
+    /// The schemes tish core ships with — **none**. tish core is target-agnostic and knows nothing
+    /// about agb/GBA; concrete schemes (like `asset:`) are contributed by the crates that implement
+    /// their runtime (see [`from_project`](Self::from_project)). Kept as the seam for any future
+    /// genuinely-generic built-in scheme.
+    pub fn builtin() -> Self {
+        SchemeRegistry {
+            schemes: Vec::new(),
+        }
+    }
+
+    /// The active registry for a build: schemes contributed by cargo dependencies, then the
+    /// project's own, merged in that order (project overrides a dependency of the same name).
+    ///
+    /// * **Dependency-contributed** — each `tish.rustDependencies` entry with a `path` may ship a
+    ///   `tish.schemes.json` (`{ "schemes": { … } }`) in its crate dir. This is how tish-agb
+    ///   provides `asset:` without any tish-core edits: a game that depends on tish-agb (as every
+    ///   sprite game already does) gets the scheme for free, no per-game config.
+    /// * **Project-local** — `package.json` → `tish.schemes`, for one-off or overriding schemes.
+    ///
+    /// A malformed entry is skipped, not fatal.
+    pub fn from_project(project_root: &Path) -> Self {
+        let mut reg = Self::builtin();
+        let tish = crate::resolve::read_project_tish_config(project_root);
+        // 1. Schemes contributed by cargo path-dependencies.
+        if let Some(deps) = tish.get("rustDependencies").and_then(|v| v.as_object()) {
+            for val in deps.values() {
+                let Some(path) = val
+                    .as_object()
+                    .and_then(|o| o.get("path"))
+                    .and_then(|p| p.as_str())
+                else {
+                    continue;
+                };
+                let p = Path::new(path);
+                let dep_dir = if p.is_absolute() {
+                    p.to_path_buf()
+                } else {
+                    project_root.join(p)
+                };
+                let manifest = dep_dir.join("tish.schemes.json");
+                if let Ok(content) = std::fs::read_to_string(&manifest) {
+                    if let Ok(json) = serde_json::from_str::<serde_json::Value>(&content) {
+                        reg.merge_schemes(json.get("schemes"));
+                    }
+                }
+            }
+        }
+        // 2. Project-local schemes (override dependency-contributed ones of the same name).
+        reg.merge_schemes(tish.get("schemes"));
+        reg
+    }
+
+    /// Merge a JSON `{ name: def, … }` schemes object into the registry; a same-named scheme
+    /// replaces the existing one.
+    fn merge_schemes(&mut self, schemes: Option<&serde_json::Value>) {
+        let Some(obj) = schemes.and_then(|v| v.as_object()) else {
+            return;
+        };
+        for (name, def) in obj {
+            if let Some(parsed) = parse_scheme_def(name, def) {
+                self.schemes.retain(|s| s.name != parsed.name);
+                self.schemes.push(parsed);
+            }
+        }
+    }
+
+    /// The scheme whose prefix `spec` starts with, if any.
+    pub fn matches(&self, spec: &str) -> Option<&SchemeDef> {
+        self.schemes.iter().find(|s| spec.starts_with(&s.prefix()))
+    }
+}
+
+/// Parse one `tish.schemes["name"]` JSON entry into a [`SchemeDef`]. Returns `None` (skip) on a
+/// shape that doesn't describe a valid scheme.
+fn parse_scheme_def(name: &str, def: &serde_json::Value) -> Option<SchemeDef> {
+    // The name is interpolated into a generated module identifier (`mod __scheme_<name>_<j>`) and
+    // used as the `<name>:` import prefix, so it must be a valid Rust identifier. A name like
+    // `sprite-sheet` would emit un-compilable Rust (a raw rustc error far from its cause); skip it
+    // instead, consistent with "a malformed entry is skipped, not fatal".
+    if !is_valid_scheme_name(name) {
+        return None;
+    }
+    let obj = def.as_object()?;
+    let resolve_file = obj.get("file").and_then(|v| v.as_bool()).unwrap_or(true);
+    let mut targets = HashMap::new();
+    if let Some(target_map) = obj.get("targets").and_then(|v| v.as_object()) {
+        for (target, spec) in target_map {
+            let s = spec.as_object()?;
+            let uses = s
+                .get("uses")
+                .and_then(|v| v.as_array())
+                .map(|a| {
+                    a.iter()
+                        .filter_map(|x| x.as_str().map(|s| s.to_string()))
+                        .collect()
+                })
+                .unwrap_or_default();
+            let module_body = s.get("module").and_then(|v| v.as_str())?.to_string();
+            let accessor = s
+                .get("accessor")
+                .and_then(|v| v.as_str())
+                .unwrap_or("")
+                .to_string();
+            let register = s
+                .get("register")
+                .and_then(|v| v.as_str())
+                .unwrap_or("")
+                .to_string();
+            targets.insert(
+                target.clone(),
+                TargetEmit {
+                    uses,
+                    module_body,
+                    accessor,
+                    register,
+                    bind: BindKind::Handle,
+                },
+            );
+        }
+    }
+    Some(SchemeDef {
+        name: name.to_string(),
+        resolve_file,
+        targets,
+    })
+}
+
+/// A scheme name must be a valid Rust identifier: it becomes part of a generated module ident
+/// (`__scheme_<name>_<j>`) and the `<name>:` import prefix. ASCII letter/underscore, then
+/// letters/digits/underscores. (The same shape `types::is_struct_field_safe` enforces for native
+/// struct field keys, kept local so `schemes` stays self-contained.)
+fn is_valid_scheme_name(name: &str) -> bool {
+    let mut chars = name.chars();
+    match chars.next() {
+        Some(c) if c == '_' || c.is_ascii_alphabetic() => {}
+        _ => return false,
+    }
+    chars.all(|c| c == '_' || c.is_ascii_alphanumeric())
+}
+
+thread_local! {
+    static ACTIVE: RefCell<SchemeRegistry> = RefCell::new(SchemeRegistry::builtin());
+}
+
+/// Install the registry for the current build. Call once at the start of a compile, before
+/// resolution — every scheme predicate reads whatever is installed here.
+pub fn set_active(registry: SchemeRegistry) {
+    ACTIVE.with(|c| *c.borrow_mut() = registry);
+}
+
+/// Read from the active registry.
+pub fn with_active<R>(f: impl FnOnce(&SchemeRegistry) -> R) -> R {
+    ACTIVE.with(|c| f(&c.borrow()))
+}
+
+/// True if `spec` is a registered import scheme (built-in or project-declared).
+pub fn is_scheme_import(spec: &str) -> bool {
+    with_active(|r| r.matches(spec).is_some())
+}
+
+/// Default bake size when `font:path` omits `@N` (most common native grid: monogram/alagard/m3x6).
+pub const FONT_DEFAULT_SIZE: u32 = 16;
+
+/// Split a scheme path rest into `(file_path, size)` when it ends with `@` + digits
+/// (`face.ttf@7` → `("face.ttf", Some(7))`). Non-digit suffixes after `@` are left intact
+/// (`foo@2x.png` is not a size).
+pub fn split_path_size(rest: &str) -> (&str, Option<u32>) {
+    let Some((path, size_str)) = rest.rsplit_once('@') else {
+        return (rest, None);
+    };
+    if path.is_empty() || size_str.is_empty() || !size_str.bytes().all(|b| b.is_ascii_digit()) {
+        return (rest, None);
+    }
+    match size_str.parse::<u32>() {
+        Ok(n) if n > 0 => (path, Some(n)),
+        _ => (rest, None),
+    }
+}
+
+/// Substitute `{path}` (the file as a Rust string literal), `{mod}` (the generated module ident),
+/// `{charset}` (used non-ASCII chars as a Rust string literal), and `{size}` (plain integer from a
+/// trailing `@N` on the path, e.g. `font:face.ttf@7`) in a template. `{path}` never includes `@N`.
+pub fn render_template(template: &str, abspath: &str, module_ident: &str, charset: &str) -> String {
+    let (path, size) = split_path_size(abspath);
+    let size_str = size
+        .map(|n| n.to_string())
+        .unwrap_or_else(|| FONT_DEFAULT_SIZE.to_string());
+    template
+        .replace("{path}", &format!("{:?}", path))
+        .replace("{mod}", module_ident)
+        .replace("{charset}", &format!("{:?}", charset))
+        .replace("{size}", &size_str)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn scheme_name_must_be_a_rust_identifier() {
+        // Valid identifiers pass.
+        assert!(is_valid_scheme_name("asset"));
+        assert!(is_valid_scheme_name("sprite_sheet"));
+        assert!(is_valid_scheme_name("_x"));
+        assert!(is_valid_scheme_name("bg2"));
+        // Anything that would break the generated `mod __scheme_<name>_<j>` is rejected.
+        assert!(!is_valid_scheme_name("sprite-sheet")); // hyphen
+        assert!(!is_valid_scheme_name("")); // empty
+        assert!(!is_valid_scheme_name("2d")); // leading digit
+        assert!(!is_valid_scheme_name("a:b")); // colon
+        assert!(!is_valid_scheme_name("a b")); // space
+    }
+
+    #[test]
+    fn parse_scheme_def_skips_invalid_name() {
+        let def = serde_json::json!({
+            "file": true,
+            "targets": { "gba": { "module": "// x", "register": "" } }
+        });
+        // A hyphenated name is skipped (returns None) rather than emitting un-compilable Rust.
+        assert!(parse_scheme_def("sprite-sheet", &def).is_none());
+        // The same def under a valid name parses.
+        assert!(parse_scheme_def("sheet", &def).is_some());
+    }
+
+    #[test]
+    fn split_path_size_parses_trailing_at_digits() {
+        assert_eq!(split_path_size("face.ttf@7"), ("face.ttf", Some(7)));
+        assert_eq!(split_path_size("/abs/face.ttf@16"), ("/abs/face.ttf", Some(16)));
+        assert_eq!(split_path_size("face.ttf"), ("face.ttf", None));
+        // Not a size — non-digit suffix after @.
+        assert_eq!(split_path_size("foo@2x.png"), ("foo@2x.png", None));
+        assert_eq!(split_path_size("@7"), ("@7", None));
+        assert_eq!(split_path_size("face.ttf@0"), ("face.ttf@0", None));
+    }
+
+    #[test]
+    fn render_template_substitutes_size_and_strips_at_from_path() {
+        let out = render_template(
+            "pack!({path}, {size}, {charset}); //{mod}",
+            "/abs/face.ttf@7",
+            "__scheme_font_0",
+            "你好",
+        );
+        assert!(out.contains("pack!(\"/abs/face.ttf\", 7, \"你好\")"), "got: {out}");
+        assert!(out.contains("//__scheme_font_0"));
+        assert!(!out.contains("face.ttf@7"));
+    }
+
+    #[test]
+    fn render_template_defaults_size_when_missing() {
+        let out = render_template("x({size})", "/abs/face.ttf", "m", "");
+        assert_eq!(out, format!("x({})", FONT_DEFAULT_SIZE));
+    }
+}