mm_tpl 2.7.0 → 2.7.2

package/README_EN.md

@@ -19,10 +19,15 @@ Super Meimei Template Engine Module, based on art-template engine, provides powe
 
 - 🚀 High-performance template engine based on art-template
 - 🔧 Support for multiple template syntax rules
-- 🎨 Theme switching and template file priority search
-- ⚡ Built-in caching mechanism for performance optimization
-- 🔌 Powerful hook system support
-- 📁 Flexible directory structure support
+- 🎨 Deployment-level themes with user-level style and language switching; templates live under the theme directory organised by feature, styles are layered by style inside the theme
+- 🧩 Components in a dedicated directory referenced by `$component`, keeping shared partials apart from feature pages, with theme fallback and diy override
+- 📜 Application-level + theme-level scripts in two tiers, not layered by style, with application-level shared scripts running first
+- 🌐 Multi-user support: each user picks its own style and language, and shares cache by that combination
+- 🗂️ JSON language packs at application level and theme level, merged by directory priority and reloadable at runtime
+- ⚡ Built-in caching with physical files or process memory, invalidated automatically when templates change
+- 🔌 Powerful hook system with both global and instance-level hooks
+- 🧩 Template function table: register with `setFunc` and call directly inside templates, inherited automatically by derived instances
+- 📁 Flexible directory structure; the `static/diy/` directory overrides same-named templates, styles and scripts of themes
 - 🛡️ Comprehensive error handling mechanism
 
 ## Installation
@@ -44,16 +49,57 @@ npm install mm_tpl
 ```javascript
 const {Tpl} = require('mm_tpl');
 
+// Directory layout under the application root (see doc/目录结构.md):
+// app/shop/
+//   config.js                      # { defaults: { theme, style, lang } }
+//   static/                        # static resource root: templates, styles, scripts, language packs and the override directory all live here
+//     diy/                         # user override directory, highest priority, may hold templates, components and scripts
+//       component/                 #   components overriding every theme
+//     js/                          # application-level scripts, shared by every theme
+//     lang/                        # application-level language packs, filename is the language code
+//     template/{theme}/            # templates sit directly under the theme directory, organised by feature
+//       index.html                 #   the home page template of the theme
+//       article/list.html          #   feature directory: one directory per feature, at any depth
+//       component/                 #   components: shared partials reusable by feature pages
+//         bar.html
+//       js/                        # theme-level scripts, overriding same-named application-level scripts
+//       lang/                      # theme-level language packs, overriding the application level
+//       style/{style}/             # styles only, no templates; styles are layered by style inside the theme
+//       style/base/                # base style: common styles shared by every style
+
 // Create template instance
 const tpl = new Tpl({
-    root: process.cwd(),           // Root directory
-    default_dir: "./template/",    // Default template directory
-    default_theme: 'default',      // Default theme
-    extname: ".html",             // Template file extension
-    cache_root: './cache',        // Cache directory
-    cache_extname: '.cache.html', // Cache file extension
-    rules: [nativeRule, artRule, htmlRule, jsRule, pyRule, pyRule2] // Template rules
+    root: process.cwd(),             // application root directory
+    theme_dir: './static/template/', // theme directory, relative to the application root
+    style_dir: './style/',           // style directory, relative to the theme directory
+    component_dir: './component/',   // component directory, relative to the theme directory, holds shared partials; empty disables components
+    diy_dir: './static/diy/',        // user override directory, relative to the application root, highest priority
+    lang_dir: './static/lang/',      // application-level language pack directory, filename is the language code, empty to disable
+    theme_lang_dir: './lang/',       // theme-level language pack directory, relative to the theme directory, overrides same keys
+    js_dir: './static/js/',          // application-level script directory, relative to the application root, holds shared scripts
+    theme_js_dir: './js/',           // theme-level script directory, relative to the theme directory; scripts are not layered by style
+    default_theme: 'default',        // default theme, a deployment-level setting users do not pick
+    default_style: 'light',          // default style, a variant inside a theme, user-selectable
+    base_style: 'base',              // base style directory holding styles shared by all styles; empty disables it
+    default_lang: 'zh_cn',           // default language, user-selectable
+    langs: {},                       // in-memory language packs, take precedence over files
+    cache_dims: ['style', 'lang'],   // cache layering dimensions; only user-selectable ones, users share cache by this
+    cache_type: 'file',              // cache type: file for physical files, memory for process memory
+    cache_max: 1000,                 // max entries of the in-memory cache
+    extname: ".html",                // template file extension, configurable (e.g. ".art"); appended automatically when omitted
+    cache_root: './cache',           // cache directory
+    cache_extname: '.cache.html',    // cache file extension
+    plural_rules: {                  // plural rules keyed by language code
+        'en_us': function (count) { return count === 1 ? 0 : 1; }
+    },
+    rules: [nativeRule, artRule, htmlRule, jsRule, pyRule, pyRule2] // template rules
 });
+
+// You can also read the application config file directly; defaults is expanded into default_theme / default_style / default_lang
+const app_config = require('./app/shop/config.js');
+const tpl_shop = new Tpl(Object.assign({ root: './app/shop/' }, app_config));
+// config.js content: module.exports = { defaults: { theme: 'default', style: 'light', lang: 'zh_cn' } }
+// An explicit default_* wins over defaults, and defaults is not kept in config, so fork() never expands it twice
 ```
 
 ### 3. Basic Template Rendering
@@ -137,8 +183,9 @@ tpl.set({
     keywords: "keywords"
 });
 
-// Render view file
-const html = tpl.view("./views/index.html", {
+// Render view file; the path is relative to the theme directory, e.g. static/template/{theme}/index.html,
+// and may include feature directories such as article/list.html
+const html = tpl.view("./index.html", {
     user: { name: "John" }
 });
 // Output: Rendering result <div>Hello World</div>
@@ -150,23 +197,166 @@ const title = tpl.get("title");
 tpl.del("keywords");
 ```
 
+#### Rendering Components
+
+Shared partials (headers, sidebars, ad slots and so on) reusable by several pages live in the theme's `component/` directory, and pages reference them with `$component` using just the component name, without any directory prefix or extension:
+
+```html
+<!-- A page references a component: the ./component/ prefix and the .html suffix are omitted -->
+<div>${@$component('bar')}</div>
+
+<!-- A component can reference other components, nesting is supported -->
+<!-- static/template/default/component/bar.html -->
+<div class="ad">${@$component('ad')}</div>
+
+<!-- Passing data to a component: the component reads the field directly -->
+${@$component('user-card', { user: item })}
+
+<!-- A component inside a sub-directory -->
+${@$component('article/card')}
+```
+
+The server-side equivalent:
+
+```javascript
+// Render a component, returns the rendered string
+tpl.component('bar', { message: 'hello' });
+
+// Return the full path of the hit component file without rendering
+tpl.getComponentFile('bar');
+```
+
+A component accepts a model, which is merged with the caller's data: the caller's data and template helpers such as `$view` / `$css` / `$t` are passed down to the component, and fields in the passed model override the caller's. The model may be an object literal or a variable, the two are equivalent:
+
+```html
+${@$component('user-card', { user: item })}
+${@$component('user-card', card_data)}
+```
+
+A component name is resolved relative to the component directories, **not relative to the file that calls it**, so the same name resolves to the same component everywhere. When a component is not found, an empty string is returned and `tpl.error` is set (`code: 10000`) instead of throwing. See [Advanced Features](#1-theme-style-and-directory-support) for the full directory chain.
+
 ### 6. Caching Mechanism
 
 ```javascript
-// Use cache for view rendering
-const html = tpl.view("./views/page", {
+// Use cache for view rendering: cache: true is enough, the cache filename is derived from the template path
+const html = tpl.view("./index.html", {
     data: someData
 }, {
-    cache: true,                // Whether to use cache
-    cache_filename: "./cache"   // Cache filename
+    cache: true
+});
+// Cache file: cache/{style}/{lang}/index.cache.html (cache_dims defaults to ['style', 'lang'])
+// e.g. cache/light/zh_cn/index.cache.html, cache/dark/en_us/index.cache.html
+
+// You can also pass an explicit cache filename
+tpl.view("./index.html", { data: someData }, {
+    cache: true,
+    cache_filename: "./index"      // Same as ./index.cache.html
+});
+
+// cache: false only writes the cache without reading it, useful for a forced refresh
+tpl.view("./index.html", { data: someData }, {
+    cache: false,
+    cache_filename: "./index"
+});
+
+// Clear cache: without arguments only the cache directory of the current instance is cleared
+tpl.clearCache();
+// Clear a specific directory, relative to cache_root
+tpl.clearCache('./game');
+// Clear all cache
+tpl.clearCache('./');
+
+// Use getCacheFile to inspect the cache path of the current instance; a string is accepted
+tpl.getCacheFile('./index');
+```
+
+#### Cache Count Is Driven by cache_dims
+
+`cache_dims` should only contain the dimensions **users can choose**. The division of responsibility in this module is:
+
+| Dimension | Level | User-selectable | In cache layering |
+| --- | --- | --- | --- |
+| Theme `theme` | Deployment | No | No, uniform across the site |
+| Style `style` | User | Yes | Yes |
+| Language `lang` | User | Yes | Yes |
+
+The default is therefore `['style', 'lang']`: users are grouped by "style + language", and users in the same combination share the same cache.
+
+The upper bound on the number of cache files is:
+
+```
+cache files ≤ (named styles + 1) × languages × cached templates
+```
+
+The `+ 1` stands for **no style selected** — it is a distinct combination, but the empty string does not occupy a directory level, so its cache sits directly under the language directory (that combination only appears when `default_style` is empty too):
+
+```
+cache/dark/zh_cn/test.cache.html   ← dark style selected, one extra style level
+cache/zh_cn/test.cache.html        ← no style, lang sits directly under the root
+```
+
+This is an **upper bound, not a fixed count**: only combinations and templates that are actually rendered produce a cache file, and a combination that is never requested has no file at all. With 2 named styles (dark, light, plus no style = 3 combinations), 2 languages and 20 templates:
+
+| `cache_dims` | Levels | Files (upper bound) |
+| --- | --- | --- |
+| `['style', 'lang']` (default) | 3 combinations × 2 languages × 20 templates | 120 |
+| `['lang']` | no style dimension, 2 languages × 20 templates | 40 |
+| `[]` | no layering, 20 templates | 20 |
+
+The dimensions only take **finite enumerations** such as style and language; a user merely falls into one of those combinations, so this count is **completely independent of the number of users**. With 5,000 users, 1 named style (dark, plus no style = 2 combinations), 2 languages and 2 templates, even when all 4 combinations are used only 8 cache files are produced:
+
+```
+cache/zh_cn/test.cache.html              ← no style + Chinese
+cache/en_us/test.cache.html              ← no style + English
+cache/dark/zh_cn/test.cache.html         ← dark style + Chinese
+cache/dark/en_us/test.cache.html         ← dark style + English
+```
+
+The module provides no per-user dimension: each entry would serve exactly one user and only hit when "the same user revisits the same page while the data stays unchanged", yet user data (balance, orders, messages) usually changes on every request, so the hit rate approaches zero and stale content may be served. **Pages that contain user data are not suitable for full-page caching**; fetch those regions asynchronously, or use the in-memory cache described below.
+
+#### Theme Does Not Participate in Cache Layering
+
+A theme is a deployment-level setting, uniform for every user on the site and not switched at runtime, so `theme` is not part of `cache_dims` by default. This comes with one constraint: **switching the theme at runtime reuses the previous theme's cache**. The module logs a warning from `setTheme`; when a switch really is needed, clear the cache or include `theme` in the dimensions:
+
+```javascript
+// Option 1: clear the cache after switching the theme
+tpl.setTheme('default');
+tpl.clearCache('./');
+
+// Option 2: include the theme when multiple themes coexist long term
+const tpl_multi = new Tpl({
+    default_theme: 'game',
+    cache_dims: ['theme', 'style', 'lang']
 });
+```
+
+#### Automatic Cache Invalidation
+
+After a template file or a language pack file is modified, the old cache is invalidated and rebuilt on the next render — **no manual clearing needed**. The check compares file modification times, not file contents:
 
-// Clear cache
-tpl.clearCache('./views/mall'); // Clear cache for specific directory
-// or
-tpl.clearCache(); // Clear all cache
+```javascript
+// Edit a template during development and it takes effect on refresh, no clearCache needed
+// Editing static/lang/zh_cn.json rebuilds the Chinese cache the same way
+```
+
+Language pack changes are only checked when the cache is layered by language (`cache_dims` contains `lang`); otherwise only the template file is checked.
+
+#### In-memory Cache
+
+When you want the cache to stay off disk and live only inside the process, use the in-memory cache:
+
+```javascript
+const tpl = new Tpl({
+    default_theme: 'game',
+    cache_type: 'memory',   // file (default) for physical files, memory for process memory
+    cache_max: 1000         // Max entries in memory; the earliest written entry is evicted beyond it, 0 means unlimited
+});
 ```
 
+In-memory entries live in `Tpl.cache_store` keyed by the full cache file path and use least-recently-used eviction: a hit moves the entry to the tail, and the earliest written entry is evicted beyond `cache_max`. The cache is cleared on process restart, which means each process keeps its own copy in a multi-instance deployment.
+
+`clearCache` clears both physical files and in-memory entries, and its scope is likewise limited by `cache_dims`.
+
 ### 7. Hook System
 
 #### Add Function Hook
@@ -223,17 +413,308 @@ $.hook.delFilter('content', 'contentFilter');
 $.hook.clear();
 ```
 
+### 8. Multi-user Styles and Languages
+
+The module works only on the parameters it receives and does not care where they come from. Configuration has two levels:
+
+- **Deployment-level**: theme, template directory, cache directory, language pack directory and so on — uniform across the site and held by the master instance
+- **User-level**: style and language, chosen by each user
+
+There are two ways to use them: **passing options** (a single instance, with `style` / `lang` passed in the `view` options, no derived instance needed) and **deriving instances** (`fork`). The former is recommended; the following uses `fork` so each option's effect is easy to see. See [Using Styles and Languages Across Users](#6-using-styles-and-languages-across-users) for the trade-offs.
+
+```javascript
+// Master instance: holds the deployment-level configuration
+const tpl = new Tpl({
+    root: './app/shop/',                            // application root directory
+    default_theme: 'game',                          // theme is fixed at deployment level, users do not pick it
+    default_style: '',                              // default style when the user picks none
+    default_lang: 'zh_cn',                          // default language when the user picks none
+    lang_dir: './static/lang/',                     // application-level language pack directory, filename is the language code
+    langs: {},                                      // optional in-memory language packs, take precedence over files
+    // cache is layered by the user-selectable dimensions: style + language
+    cache_dims: ['style', 'lang']
+});
+
+// User A: no style + Chinese
+const tpl_a = tpl.fork();
+// User B: dark style + English
+const tpl_b = tpl.fork({ style: 'dark', lang: 'en_us' });
+
+tpl_a.getTheme(); // "game", inherited from the master instance
+tpl_a.getStyle(); // ""
+tpl_a.getLang();  // "zh_cn"
+
+tpl_b.getTheme(); // "game"
+tpl_b.getStyle(); // "dark"
+tpl_b.getLang();  // "en_us"
+
+// Render separately; the language and the cache differ per configuration,
+// while template lookup stays identical because templates are not layered by style
+tpl_a.view('./index.html', { title: '首页' });
+tpl_b.view('./index.html', { title: 'Home' });
+```
+
+Template directories are resolved by priority — `static/diy/` → current theme → default theme — so both user A and user B resolve to `static/template/game/index.html`; the style takes no part in template lookup (see [Advanced Features](#1-theme-style-and-directory-support) for the full order). With `default_theme: 'game'` above, the current theme is also the site default theme, so the chain has just the first two levels; under another current theme the default theme is the third:
+
+```
+static/diy/index.html              ← user override directory, highest priority, shared by all instances
+static/template/game/index.html    ← current theme == default theme: user A and user B hit this very same file
+```
+
+Only the theme falls back, never the style. What the style changes is the stylesheet list (and the cache path, since `cache_dims` contains `style`), not the template:
+
+```
+user A (light style): static/template/game/style/light/light.css + the shared static/template/game/style/base/common.css
+user B (dark style):  static/template/game/style/dark/dark.css  + the shared static/template/game/style/base/common.css
+```
+
+Styles are layered by style and collect every css along their own chain, keeping only the highest-priority copy per filename, so dark and light each read their own directory while their shared styles live in the base style directory instead of being duplicated.
+
+`$t` is bound to the language of the current instance and can be used in both rendered strings and template files:
+
+```html
+<!-- Rendered string -->
+<p>${$t('hello', 'User')}</p>
+<!-- User A (zh_cn) output: <p>你好，User！</p> -->
+<!-- User B (en_us) output: <p>Hello, User!</p> -->
+
+<!-- Named interpolation: write {name} in the entry and pass an object -->
+<p>${$t('welcome', { name: user.name })}</p>
+```
+
+Templates can also use `$view` for sub-templates, `$component` for components, `$css` for stylesheets and `$js` for scripts; all of them resolve through their own directory priority chain. The `$css` / `$js` name supports `*` wildcards and returns an array when one is used:
+
+```html
+<div>${@$component('bar')}</div>
+<link rel="stylesheet" href="${$css('common.css')}">
+${each $css('*.css') value}
+<link rel="stylesheet" href="${value}">
+${/each}
+
+<!-- every script; app* or *promo* narrows by name, and the order is the execution order -->
+${each $js('*.js') value}
+<script src="${value}"></script>
+${/each}
+```
+
+In server-side code use `t` / `tc`, which are equivalent to `$t` in templates:
+
+```javascript
+tpl.t('hello', 'User');   // "你好，User！", replaces {0}, {1} ... placeholders in order
+tpl.t('welcome', { name: '张三' }); // "欢迎，张三！", an object argument fills {name} placeholders
+tpl.t('bar.nav');         // "游戏导航", supports a.b style nested keys
+tpl.tc('items', 1);       // Plural lookup, picks the form by language rule: "共 1 项" in Chinese
+tpl.tc('items', 5);       // "1 item" / "5 items" in English
+```
+
+Plural entries are arrays in the language pack, `{count}` is the count placeholder:
+
+```json
+// static/lang/en_us.json
+{ "items": ["{count} item", "{count} items"] }
+```
+
+The plural form is decided by the plural rule of the language, registered by language code in the `plural_rules` option. Language codes are lowercase with underscores; the `Lang` class of mm_expand already ships `zh_cn` and `en` rules, so those two work directly, while other codes such as `en_us` should be registered explicitly in `plural_rules`. When a code is not registered, `tc()` falls back to the built-in `en` rule. Codes match language-pack filenames and are easier to reference from the browser.
+
+#### Language Pack Files
+
+Keep copy in JSON language packs and let template files call `$t` only; do not hardcode copy in templates. The filename is the language code:
+
+```
+static/lang/zh_cn.json                         ← application-level Chinese
+static/lang/en_us.json                         ← application-level English
+static/template/game/lang/zh_cn.json           ← Chinese of the game theme, overrides the same keys
+static/template/game/lang/en_us.json           ← English of the game theme, overrides the same keys
+```
+
+```json
+// static/lang/zh_cn.json
+{
+    "hello": "你好，{0}！",
+    "theme": { "game": "游戏主题" },
+    "bar": { "nav": "导航栏", "user_id": "用户ID" }
+}
+```
+
+```json
+// static/template/game/lang/zh_cn.json: only the keys to override
+{
+    "bar": { "nav": "游戏导航" }
+}
+```
+
+```html
+<!-- static/template/game/test.html: templates only resolve entries -->
+<div>${$t('theme.game')}</div>
+<!-- zh_cn output: <div>游戏主题</div> -->
+<!-- en_us output: <div>Game Theme</div> -->
+```
+
+Language packs are merged in the following order, each overriding the previous one: application level `lang_dir/{lang}.json` → default theme `{theme_dir}/{default theme}/{theme_lang_dir}/{lang}.json` → current theme `{theme_dir}/{current theme}/{theme_lang_dir}/{lang}.json` → the `langs` option. Entries of the same language are merged by key, and higher priority overrides same-named keys, so the same template can produce different copy per theme.
+
+Entries are resolved in this order: current language → default language. When both miss, an error is logged and `undefined` is returned, rendering as an empty string. To get started quickly you may also write copy directly in templates and extract it into language packs later.
+
+Language pack files are read when an instance is created and then cached by a file fingerprint (path + mtime): while the files are unchanged, new instances and `fork` reuse the parsed result; after a file is added, edited or removed, the next read reloads automatically. Language packs of already created instances are not refreshed automatically — call `reloadLangs()` for that.
+
+```javascript
+tpl.getLangs();          // ['zh_cn', 'en_us']; languages without entries are filtered out
+tpl.reloadLangs();       // Reload by file fingerprint, keeping the current language; returns the language list
+tpl.reloadLangs(true);   // Skip the cache and force re-reading the language files
+tpl.loadLang('en_us');   // Reload and return the entries of one language
+```
+
+Switch at runtime (only affects the current instance). Style and language are user-selectable; the theme is a deployment-level setting that users should not switch at runtime:
+
+```javascript
+tpl_b.setStyle('light'); // Returns the applied style name
+tpl_b.setLang('zh_cn');  // Returns the applied language code
+```
+
+Theme and style setters validate that the directory exists. When it does not, a warning is logged and the **previous value is kept**, so a user never believes the switch succeeded while the default value is still in use:
+
+```javascript
+// There is no not_exist theme or style directory under static/template
+tpl_b.setStyle('not_exist');        // Returns the old style "dark" and logs a warning
+tpl_b.setTheme('not_exist');        // Returns the old theme "game" and logs a warning (theme validation works the same way)
+
+// Skip validation when the directory has not been created yet
+tpl_b.setStyle('not_exist', true);  // Returns "not_exist"
+
+// An empty string means no style is set; lookup and cache layering fall back to the default style
+tpl_b.setStyle('');
+```
+
+The cache is layered by the dimensions in `cache_dims`, and users are grouped by "style + language" so that users in the same combination share the cache:
+
+```
+cache/zh_cn/test.cache.html              ← user A (no style + Chinese)
+cache/en_us/test.cache.html              ← user A switched to English
+cache/dark/zh_cn/test.cache.html         ← user B (dark style + Chinese)
+```
+
+```javascript
+// Get the cache file path of the current instance
+tpl_a.getCacheFile({ cache_filename: './test' });
+```
+
+Cache files are grouped by "style + language", so users sharing a combination share the same cache file and the count is independent of the user count — see [Cache Count Is Driven by cache_dims](#cache-count-is-driven-by-cache_dims).
+
 ## Advanced Features
 
-### 1. Theme and Directory Support
+### 1. Theme, Style and Directory Support
 ```javascript
-// Set current theme
-tpl.current_theme = "dark";
+// Set current style (a variant inside a theme, user-selectable; keeps the old style and logs a warning when missing)
+tpl.setStyle("dark");
+// Clear the style
+tpl.setStyle("");
+
+// Set current theme (a deployment-level setting users should not switch at runtime)
+// Keeps the old theme and logs a warning when the directory is missing; clear the cache after switching,
+// see "Theme Does Not Participate in Cache Layering"
+tpl.setTheme("default");
+// Skip directory validation and set anyway
+tpl.setTheme("default", true);
+
+// Or assign directly (no validation)
+tpl.current_theme = "default";
+tpl.current_style = "dark";
+
+// Template directory search order (priority from high to low; {dir} is this.dir, the application root):
+// 1. {dir}/static/diy/                          user override directory
+// 2. {dir}/static/template/{current theme}/     templates organised by feature directly under the theme directory
+// 3. {dir}/static/template/{default theme}/
+//
+// Templates are layered by theme only, never by style: a style is a visual variant and must not change the HTML structure,
+// so switching styles keeps resolving the very same template file
+// The path is relative to the theme directory and may include any feature directory, e.g. ./index.html, ./article/list.html, ./article/detail.html
+// The extension is appended automatically when omitted (extname, '.html' by default), so
+// view('./article/list') and view('./article/list.html') are equivalent
+// Templates override by filename, and the highest-priority file wins (getFile); the style takes no part in this lookup
+// A style that needs a different look changes css; different copy or structure is handled with model variables
+
+// Component directory search order (priority from high to low; components use a chain of their own,
+// isomorphic to the template chain with one extra fixed component/ prefix on every level):
+// 1. {dir}/static/diy/component/                        user override directory
+// 2. {dir}/static/template/{current theme}/component/
+// 3. {dir}/static/template/{default theme}/component/
+//
+// A component name is resolved relative to the component directories, not relative to the calling file,
+// so the same name resolves identically wherever it is used
+// Names may include sub-directories such as article/card, and the extension is appended automatically (getComponentFile)
+// A component missing from the current theme falls back to the default theme's component directory,
+// and static/diy/component/ overrides every theme globally
+// Components are not cached by default; pass cache and cache_filename explicitly through the options when needed
+
+// Style directory search order (priority from high to low): styles are layered by theme and by style,
+// so they carry two more levels (the current style and the base style) than templates
+// 1. {dir}/static/diy/                                   user override directory
+// 2. {dir}/static/template/{current theme}/style/{current style}/
+// 3. {dir}/static/template/{current theme}/style/{base style}/
+// 4. {dir}/static/template/{default theme}/style/{current style}/
+// 5. {dir}/static/template/{default theme}/style/{base style}/
+//
+// Only the theme falls back, never the style: files of other style directories are not inherited
+// Shared styles belong in the base style directory (base_style, 'base' by default),
+// each style directory only holds its own differences
+// The style directory holds css only and never contains templates
+// Styles collect every css of the directories above, keeping only the highest-priority copy per filename (getCssFiles)
+// With no style set that level uses the default style; when the default style is empty too, the style directory of the theme itself is used
+
+// Script directory search order (priority from high to low): layered by theme only, no style or base style level
+// 1. {dir}/static/diy/                          user override directory
+// 2. {dir}/static/template/{current theme}/js/
+// 3. {dir}/static/template/{default theme}/js/
+// 4. {dir}/static/js/                           application-level shared scripts
+//
+// Scripts are not layered by style: a style is a visual variant, scripts do not change with colour or lightness,
+// so switching styles should not switch scripts
+// Shared scripts belong in the application-level static/js/, and keep being provided there when the theme changes
+
+// Style files are returned by ascending priority: the base style comes first as the foundation,
+// the current style overrides after it (a later-loaded rule is the one that takes effect)
+tpl.getCssFiles(); // ['.../static/template/default/style/base/common.css', '.../static/template/default/style/light/light.css', ...]
+
+// Scripts are ascending too: application-level shared scripts come first, theme scripts come after (dependency order then holds)
+tpl.getJsFiles();  // ['.../static/js/utils.js', '.../static/template/default/js/app.js', ...]
+
+// Single style file: resolved along the same chain, returns its full path or null
+tpl.getCssFile('common.css');                      // hits the base style common.css
+tpl.getCssFile('dark.css', 'default', 'dark');     // explicitly read another theme and style
+
+// Names support * wildcards: *suffix matches the end, prefix* the start, *infix* anywhere
+tpl.getCssFile('*.css');                           // returns an array, same as getCssFiles()
+tpl.matchCssFiles('light*');                       // array: only styles named light*
+tpl.matchCssFiles('*common*');                     // array: shared styles across directories
+// In templates:
+//   <link rel="stylesheet" href="${$css('common.css')}">            exact reference
+//   ${each $css('*.css') value}<link href="${value}">${/each}       wildcard batch
+// How many to include and in which order is up to the template; the engine only returns paths
+
+// Scripts work the same way as styles, just without the style argument; names also support * wildcards
+tpl.getJsFile('utils.js');                         // hits the application-level shared script
+tpl.getJsFile('app*');                             // an array when a wildcard is used, as above
+tpl.getJsFile('promo.js', 'festival');             // explicitly read a script of one theme, null when absent
+tpl.matchJsFiles('*.js');                          // every script, an array, the order is the execution order
+tpl.matchJsFiles('app*');                          // prefix match: only scripts starting with app
+tpl.matchJsFiles('*promo*');                       // infix match: same-name family across directories
+tpl.matchJsFiles('nope*');                         // no match: an empty array [], not null
+tpl.matchJsFiles('promo*', 'festival');            // specify a theme
+// In templates:
+//   <script src="${$js('utils.js')}"></script>                        exact reference
+//   ${each $js('*.js') value}<script src="${value}"></script>${/each}  wildcard batch
+//   ${each $js('app*') value}<script src="${value}"></script>${/each}  group by module prefix
+//   ${if $js('chart.js')}<script src="${$js('chart.js')}"></script>${/if}  skip when absent, avoiding a 404
+//
+// With the site default theme default and the current theme festival, the hit order of $js('*.js') mirrors the layering:
+//   ['utils.js' (application static/js/), 'app.js' (default theme, hit by fallback since festival has none), 'promo.js' (current theme static/template/festival/js/), 'patch.js' (static/diy/)]
 
-// Template file search order (priority from high to low):
-// 1. diy directory (custom directory)
-// 2. Current theme directory
-// 3. Default theme directory
+// Resolved theme, template, style and script directories
+tpl.getThemeDir('default');        // {dir}/static/template/default/
+tpl.getTemplateDirs();             // full paths of the template directories, high to low: static/diy/ → current theme → default theme
+tpl.getComponentDirs();            // full paths of the component directories, high to low: static/diy/component → current theme/component → default theme/component
+tpl.getStyleDir('default', 'dark');// {dir}/static/template/default/style/dark/
+tpl.getStyleDirs();                // full paths of the style directories above in priority order; styles only, not used for templates (duplicates are removed when the current and default theme match)
+tpl.getJsDirs();                   // full paths of the script directories, high to low: static/diy/ → current theme → default theme → application level
 ```
 
 ### 2. Template Rules
@@ -246,7 +727,7 @@ Built-in support for multiple template rules, including:
 
 ### 3. Error Handling
 ```javascript
-const html = tpl.view("./template.html", data);
+const html = tpl.view("./index.html", data);
 if (tpl.error) {
     console.error("Rendering error:", tpl.error);
 }
@@ -272,22 +753,348 @@ if (global.$ && !$.Tpl) {
 }
 ```
 
+### 6. Using Styles and Languages Across Users
+
+The theme is a deployment-level setting while the style and language are chosen by each user. There are two ways to use them, chosen by whether instance-level state is needed:
+
+| | Passing options | Deriving instances |
+| --- | --- | --- |
+| Usage | `tpl.view(file, model, { style, lang })` | `tpl.fork({ style, lang })` |
+| Instances | 1 | one per derived instance |
+| Fits | most cases, no instance management | needs instance-level state such as `viewBag` |
+
+#### Option 1: Pass It on Each Render (Recommended)
+
+A single instance can serve every user; each render receives the style and language through `options`, and the instance state is restored afterwards:
+
+```javascript
+const tpl = new Tpl({
+    root: './app/shop/',
+    default_theme: 'game',        // theme fixed at deployment level, users do not pick it
+    lang_dir: './static/lang/',
+    cache_dims: ['style', 'lang'] // users are grouped by style + language
+});
+
+// User A: dark style + English
+tpl.view('./index.html', { title: 'Home' }, { style: 'dark', lang: 'en_us', cache: true });
+
+// User B: no style + Chinese
+tpl.view('./index.html', { title: '首页' }, { lang: 'zh_cn', cache: true });
+
+tpl.getStyle(); // "", unaffected by the two renders above
+tpl.getLang();  // "zh_cn"
+```
+
+User preferences (a `user_id` → `{style, lang}` mapping) are kept by a store object, exposed on the instance as `store`. The module ships an in-memory store `Memory` and a SQLite store `Sqlite`:
+
+```javascript
+tpl.setUser(req.user_id, { style: 'dark', lang: 'en_us' });
+
+// A registered user renders with the mapped style and language;
+// an unregistered user falls back to the instance defaults
+tpl.view('./index.html', { title: 'Home' }, tpl.userOptions(req.user_id, { cache: true }));
+```
+
+See [User Preference Store](#user-preference-store) for the full API.
+
+Cache paths and language follow the passed options, and the cache path is layered by the combination too; template lookup follows the instance theme, since templates are not layered by style:
+
+```javascript
+// getCacheFile accepts the same options, handy for inspecting or pre-generating
+tpl.getCacheFile({ cache_filename: './index', style: 'dark', lang: 'en_us' });
+// cache/dark/en_us/index.cache.html
+```
+
+`view` renders synchronously: the options are applied on entry and restored on exit, so it is **safe under concurrent requests** and requests never mix.
+
+#### Option 2: Derive Instances
+
+When instance-level state is needed (for example a template reading `${viewBag.xxx}`), derive instances with `fork`. Deriving by "style + language" lets instances be reused, with the count equal to the number of combinations:
+
+```javascript
+const pool = new Map();
+
+/**
+ * Get the instance for a style and language
+ * @param {string} style - Style, an empty string means none selected
+ * @param {string} lang - Language
+ * @returns {Tpl} Template instance of that combination
+ */
+function getInstance(style, lang) {
+    const pool_key = [style || '', lang].join('|');
+    if (!pool.has(pool_key)) {
+        pool.set(pool_key, tpl.fork({ style: style, lang: lang }));
+    }
+    return pool.get(pool_key);
+}
+
+// user id → style+language mapping, kept in the built-in mapping table
+// (or maintained by the upper layer if you prefer)
+tpl.setUser(1001, { style: 'dark', lang: 'en_us' });
+const pref = tpl.getUser(1001);
+const instance = getInstance(pref.style, pref.lang);
+const html = instance.view('./index.html', { title: 'Home' }, { cache: true });
+```
+
+The instance count is decoupled from the user count and equals the number of combinations actually used; users in the same combination share one instance, so the template lookup result and the cache file are identical.
+
+When each user needs a private `viewBag`, derive per user instead (the instance count then equals the user count):
+
+```javascript
+const user_inst = tpl.fork({
+    user_id: req.user_id,
+    style: pref.style,
+    lang: pref.lang
+});
+```
+
+#### User Preference Store
+
+The store maps a `user_id` to the user's style and language. It is exposed on the instance as `store`, and the module exports two built-in implementations, `Memory` and `Sqlite`:
+
+```javascript
+const {Tpl, Memory, Sqlite} = require('mm_tpl');
+
+const tpl = new Tpl({ user_store: new Memory() });          // in-memory store (default)
+const tpl2 = new Tpl({ user_store: new Sqlite('tpl.db') }); // persisted to a SQLite file
+
+// Write: repeated writes for the same user merge by field, and a numeric and a
+// string form of the same user_id are treated as the same user
+tpl.setUser(1001, { style: 'dark', lang: 'en_us' });
+tpl.setUser(1001, { lang: 'zh_cn' });         // only the language changes, the style stays dark
+
+tpl.getUser(1001);           // { style: 'dark', lang: 'zh_cn' }, or null when not registered
+tpl.getUsers();              // ['1001'], the registered user ids
+tpl.removeUser(1001);        // remove, returns whether it existed
+
+// Render options: a registered user maps to its style and language,
+// an unregistered user falls back to the style and language of the current instance
+tpl.userOptions(1001);                  // { style: 'dark', lang: 'zh_cn' }
+tpl.userOptions(9999);                  // { style: <current style>, lang: <current language> }
+tpl.userOptions(1001, { cache: true }); // other render options can be merged in
+```
+
+A custom store can be injected as well; it only needs the six synchronous methods (the built-in `Memory` / `Sqlite` follow the same contract):
+
+```javascript
+const tpl3 = new Tpl({
+    user_store: {
+        data: {},
+        getUser(user_id) {
+            return this.data[user_id] || null;
+        },
+        setUser(user_id, prefs) {
+            this.data[user_id] = Object.assign({}, this.data[user_id], prefs);
+            return this.data[user_id];
+        },
+        delUser(user_id) {
+            delete this.data[user_id];
+            return true;
+        },
+        hasUser(user_id) {
+            return this.data[user_id] !== undefined;
+        },
+        listUsers() {
+            return Object.keys(this.data);
+        },
+        clear() {
+            this.data = {};
+            return this;
+        }
+    }
+});
+
+tpl3.setUser(2001, { style: 'light' }); // write
+tpl3.getStore();                        // the store object
+```
+
+`setUser` must merge by field itself and `clear` should return the store for chaining; normalising `user_id` is up to the implementation, while the built-in stores stringify it so that `1001` and `'1001'` are the same user.
+
+Conventions to keep in mind:
+
+- Only the `style` and `lang` fields are stored; anything else is ignored. The store performs no authorisation, so the caller must ensure `user_id` is trustworthy
+- Derived instances share the same store: preferences belong to users, not to an instance, so `fork` reads and writes the same data (`tpl.getStore()` returns the store object)
+- Storage is injected as an interface and defaults to the in-process `Memory`. Pass an object implementing the six synchronous methods `getUser` / `setUser` / `delUser` / `hasUser` / `listUsers` / `clear` via the `user_store` option to replace it with a file, a database or a cache service, or use the built-in `Memory` / `Sqlite` directly; an incomplete interface logs a warning and falls back to the in-memory store
+- The in-memory store dies with the process, so inject shared storage (such as `Sqlite`) for multi-process or multi-machine deployments, otherwise each process sees only its own data
+- `Sqlite` relies on the built-in `node:sqlite` (available since Node 22.5); on older versions the module simply does not export `Sqlite` and everything else keeps working
+
+#### viewBag Is Shared at Instance Level
+
+`viewBag` lives on the instance and is shared by every request that uses it, so **never write user-level data into `viewBag`**.
+
+**1. User data must be passed through `model`**
+
+Data written into `viewBag` is left behind for later requests using the same instance:
+
+```javascript
+// Wrong: the hook writes request data into viewBag, and later requests on the same instance read it
+$.hook.addFunc('login', async function (m, req) {
+    m.user_id = req.user_id;      // m is this.viewBag
+});
+
+// Right: pass it through model on each render
+tpl.view('./index.html', { user_id: req.user_id, title: 'Home' });
+```
+
+**2. Templates should read `${user_id}`, not `${viewBag.user_id}`**
+
+They read from different sources: `model` belongs to the current request while `viewBag` is instance-level and shared:
+
+```html
+<div>${user_id}</div>          <!-- the current request's model, safe -->
+<div>${viewBag.user_id}</div>  <!-- instance-level shared data, leaks across users -->
+```
+
+`viewBag` is only suitable for site-level data that is identical for every user (such as the system name). This holds both for passing options and for deriving instances by combination; only when one separate instance is derived per user is `viewBag` private to that user, and only then does the "hook writes into `viewBag`" data flow work.
+
+#### Why the Cache File Count Stays Bounded
+
+Styles and languages are finite enumerations and users simply fall into one combination, so the cache file count is independent of the number of users:
+
+```
+cache files ≤ (named styles + 1) × languages × cached templates
+```
+
+With 1 named style (dark, plus no style = 2 combinations), 2 languages and 20 templates, the upper bound is 80 files (80 = 2 combinations × 2 languages × 20 templates). Whether the site has 10 users or 10,000, that number does not change, because users merely fall into those combinations; combinations that are never requested produce no file.
+
+Conversely, a cache must **never hold data that varies per user**: caching data that changes means a user who tops up their balance and refreshes still sees the old value — **that is a correctness problem, not a performance one**.
+
+So the rule is simple: **when the rendered result depends on user data, full-page caching should not be done at all**. There are three directions instead:
+
+1. Let the front end fetch user-specific regions asynchronously, and cache the page body by style and language;
+2. If per-user separation is genuinely required, pass an explicit `cache_filename` (such as `'u_' + user_id + '_index'`), or switch to the in-memory cache (`cache_type: 'memory'`) with a small `cache_max` and a short lifetime;
+3. Do not cache at all.
+
+#### Dimension Order Determines Clearing Granularity
+
+The order of `cache_dims` is the directory order, which in turn determines which dimension you can clear in batch. With the default `['style', 'lang']` the directory is `cache/{style}/{lang}/`:
+
+```javascript
+// Clear by style: removes the cache of every language under the dark style at once
+tpl.clearCache('./dark');
+
+// Users with no style keep their cache under the language directory at the root
+tpl.clearCache('./zh_cn');
+```
+
+### 7. Template Function Table and Instance-level Hooks
+
+#### Template Function Table
+
+Register template functions with `setFunc`; they are injected into the model on every render and can be called by name inside templates. `removeFunc` deletes one and `getFuncs` returns them all:
+
+```javascript
+tpl.setFunc('$md', function (text) {
+    return text.replace(/\*\*(.+?)\*\*/g, '<b>$1</b>');
+});
+
+tpl.render('${$md(\'**bold**\')}');   // <b>bold</b>
+```
+
+Precedence: **a field of the same name in this call's `model` > built-in functions (`$view` / `$t` / `$css` / `$js` / `$component` / `hookAction` / `hookFilter`) > registered functions** — a registered function can neither override a built-in function nor shadow data passed in with the current request. `fork` copies the table to the derived instance.
+
+#### Instance-level Hooks
+
+`$.hook` is a **global singleton**, and hooks added to it affect every instance; `tpl.hook` is an **instance-level hook** affecting only the current instance and the instances derived from it. Both levels run during rendering, **global first, instance-level second**: for action hooks the global output comes first, and for filter hooks the global return value is passed on to the instance level.
+
+```javascript
+tpl.hook.addAction('header', function (m) { return '<header>instance-level</header>'; });
+```
+
 ## API Reference
 
 ### Tpl Class Methods
 
 - `constructor(config)` - Constructor, create template instance
-- `setConfig(config)` - Set configuration parameters
-- `render(body, model, options)` - Render template string
+- `setConfig(config)` - Set configuration parameters (rebuilds the language instance)
+- `render(body, model, options)` - Render a template string; `options.style` / `options.lang` apply to this render only
 - `compile(body, options)` - Compile template to function
-- `view(file, model, options)` - Render template file
+- `view(file, model, options)` - Render template file; `options.style` / `options.lang` apply to this render only and are restored afterwards; `options.dir` restricts the lookup to that directory (for templates outside the theme system such as mail or print templates)
+- `getFile(file, options)` - Find a template file by directory priority, returns the full path of the hit; `options.dir` restricts the lookup to that directory
+- `getComponentFile(name, options)` - Find a component file along the component directory chain, returns the full path of the hit; `name` is the component name and may include sub-directories such as `article/card`, with the extension appended from `extname` when omitted; `options.dir` restricts the lookup to that directory
+- `component(name, model, options)` - Render a component and return the rendered string; the component name is resolved relative to the component directories, not relative to the calling file; when the component is missing an empty string is returned and `error` is set (`code: 10000`), and when `component_dir` is empty `code: 10001` is set — neither throws. `$component(name, model?)` in templates is equivalent
+- `getCssFiles()` - Get the style files of the current style as an array of full paths in ascending priority order, keeping only the highest-priority copy per filename; the base style comes first as the foundation, the current style and `static/diy/` override after it
+- `matchCssFiles(pattern, theme, style)` - Match style files by wildcard and return an array of full paths; `pattern` supports `*.css`, `blue*`, `*common*`, and defaults to `*.css`
+- `getCssFile(name, theme, style)` - Find style files by directory priority; returns an array when `name` contains `*` (empty array when nothing matches), otherwise a single path or `null`. `theme` / `style` default to the current values, so styles of another theme or style can be referenced
+- `getJsFiles()` - Get the script files as an array of full paths in ascending priority order, keeping only the highest-priority copy per filename; the application level comes first, the theme level and `static/diy/` after it
+- `matchJsFiles(pattern, theme)` - Match script files by wildcard and return an array of full paths; `pattern` supports `*.js`, `app*`, `*promo*`, and defaults to `*.js`; an empty array when nothing matches
+- `getJsFile(name, theme)` - Find script files by directory priority, returning the full path; returns an array when `name` contains `*`, otherwise a single path or `null` when absent
 - `set(obj)` - Set view data
 - `get(key)` - Get view data
 - `del(keys)` - Delete view data
-- `clearCache(path, file)` - Clear cache
-- `runFunc(name, req, ...args)` - Execute function hook
-- `runHook(name, req, ...args)` - Execute action hook (alias of runFunc)
+- `clearCache(path, file)` - Clear cache; `path` is relative to `cache_root`, omit it to clear only the dimension directory of the current instance, pass `'./'` to clear everything
+- `getCacheFile(options)` - Get the layered cache file path; the argument may be a config object or a cache filename string, and `options.style` / `options.lang` make it compute for that combination
+- `runFunc(name, req, ...args)` - Execute function hooks; returns a Promise. Both global and instance-level hooks run, with the instance-level return value taking precedence
+- `runHook(name, req, ...args)` - Execute function hooks (alias of runFunc)
 - `escape(body, restore)` - Escape/restore characters
+- `setFunc(name, func)` - Register a template function injected into the model on every render for templates to call; built-in functions and fields of the same name in this call's `model` take precedence
+- `removeFunc(name)` - Delete a registered template function, returns whether it existed and was removed
+- `getFuncs()` - Get the template function table
+
+### Tpl Multi-user Methods
+
+- `fork(config)` - Derive an instance; the user-level parameters are `{style, lang}`, while deployment-level settings (theme, directories, language packs, etc.) are inherited from the master instance; when only style and language are needed, pass them in the `view` options instead of deriving an instance
+- `getTheme()` - Get the current theme
+- `setTheme(theme, force)` - Set the current theme (a deployment-level setting users should not switch at runtime); keeps the old value and logs a warning when the directory is missing, `force: true` skips validation; also warns when `cache_dims` excludes `theme`
+- `getStyle()` - Get the current style, returns an empty string when unset
+- `setStyle(style, force)` - Set the current style (user-selectable); an empty string means no style is set (lookup and cache fall back to the default style); keeps the old value and logs a warning when the directory is missing, `force: true` skips validation
+- `getThemeDir(theme)` - Get the full path of a theme directory
+- `getStyleDir(theme, style)` - Get the full path of a style directory under a theme; when `style` is empty the style directory of that theme is returned
+- `getTemplateDirs(theme)` - Get the template directory list (full paths) in priority order: `static/diy/` → the current theme → the default theme; `theme` defaults to the current value. Templates live directly under the theme directory organised by feature, and are not layered by style
+- `getComponentDirs(theme)` - Get the component directory list (full paths) in priority order: `static/diy/component/`, the current theme's `component/`, the default theme's `component/`; isomorphic to the template chain with one extra fixed `component/` prefix on every level; `theme` defaults to the current value, and an empty `component_dir` yields an empty array
+- `getStyleDirs(theme, style)` - Get the style directory list (full paths) in priority order; styles are layered by theme and by style, so this covers **styles only** (`static/template/{theme}/style/{style}/`, including the style and `base` levels) and is not used for templates; `theme` / `style` default to the current values
+- `getJsDirs(theme)` - Get the script directory list (full paths) in descending priority: `static/diy/`, the current theme, the default theme, the application level
+- `getLang()` - Get the current language code
+- `setLang(lang)` - Set the current language, returns the applied language code
+- `t(key, ...args)` - Get translated text, equivalent to `$t` in templates, supports `a.b` nested keys; a single object argument fills `{name}` placeholders, otherwise `{0}`, `{1}` ... are replaced in order
+- `tc(key, count, ...args)` - Get plural translated text, `{count}` is the count placeholder
+- `getLangs()` - Get the supported language list
+- `reloadLangs(force)` - Reload language packs, keeping the current language; returns the language list. Uses the file fingerprint by default, `force: true` re-reads the files
+- `loadLang(lang)` - Reload and return the entries of one language, `null` when absent
+- `setUser(user_id, prefs)` - Write user preferences; `prefs` is shaped like `{style, lang}` and only those two fields are stored; repeated writes for the same user merge by field and the saved preferences are returned
+- `getUser(user_id)` - Get the preferences of one user, `null` when not registered
+- `removeUser(user_id)` - Remove the preferences of one user, returns whether it existed
+- `getUsers()` - Get the list of registered user ids
+- `userOptions(user_id, options)` - Get render options for a user: a registered user yields the mapped `style` / `lang`, an unregistered user falls back to the style and language of the current instance; the result can be passed straight to `view` / `render`, and `options` may carry other render options
+- `setStore(store)` - Set the user preference store; an empty or incomplete one falls back to the built-in in-memory `Memory`; returns the current instance
+- `getStore()` - Get the user preference store (`Memory` / `Sqlite` or a custom store object)
+
+### Tpl Instance Properties
+
+- `config` - Configuration object
+- `viewBag` - View data
+- `current_theme` - Current theme
+- `current_style` - Current style
+- `lang` - Current language instance (`Lang`); the language pack dictionary is shared, while the current language is independent
+- `store` - User preference store (`Memory` or `Sqlite`) mapping a `user_id` to the user's style and language; derived instances share the same store
+- `funcs` - Instance-level template function table, written by `setFunc`
+- `hook` - Instance-level hooks (`Hook`) affecting only the current instance and the instances derived from it; they run together with the global `$.hook`, global first
+- `dir` - Application root directory, i.e. `config.root`
+- `error` - Error message
+
+### Configuration Options
+
+- `root` - Application root directory, defaults to `$.run_path`; themes, language packs and the override directory are resolved relative to it
+- `theme_dir` - Theme directory, relative to the application root, defaults to `'./static/template/'`
+- `style_dir` - Style directory, relative to the theme directory, defaults to `'./style/'`
+- `component_dir` - Component directory, relative to the theme directory (the sub-directory of the same name under `static/diy/`), defaults to `'./component/'`, holding shared partials reusable by feature pages; empty disables components, so `$component` in templates finds no file
+- `diy_dir` - User override directory, relative to the application root, defaults to `'./static/diy/'`, highest priority
+- `lang_dir` - Application-level language pack directory, relative to the application root, filename is the language code, defaults to `'./static/lang/'`; empty disables file language packs
+- `theme_lang_dir` - Theme-level language pack directory, relative to the theme directory, defaults to `'./lang/'`, overriding the same keys of the application level
+- `js_dir` - Application-level script directory, relative to the application root, defaults to `'./static/js/'`, holding the shared scripts used by every theme
+- `theme_js_dir` - Theme-level script directory, relative to the theme directory, defaults to `'./js/'`, overriding same-named scripts of the application-level directory. Scripts are not layered by style (a style is a visual variant and scripts do not change with colour or lightness), so there are no matching style levels
+- `default_theme` - Default theme, defaults to `'default'`
+- `default_style` - Default style (a variant inside a theme), defaults to `'light'`; empty means no style layering
+- `base_style` - Base style directory name, defaults to `'base'`, acting as the shared stylesheet layer for all styles: it ranks below the current style and above the default theme, so shared styles placed there are reused by every style; the layer is skipped when it equals the current style, and an empty value disables it
+- `default_lang` - Default language code, defaults to `'zh_cn'`
+- `defaults` - Shorthand for the `config.js` file, shaped as `{theme, style, lang}`, expanded into `default_theme` / `default_style` / `default_lang` when the instance is created; an explicit `default_*` wins, and `defaults` is not kept in `config`, so `fork()` never expands it twice
+- `extname` - Extension of template and component files, defaults to `'.html'` and is configurable (e.g. `'.art'`); `getFile`, `getComponentFile`, `view` and `component` append it automatically when the argument omits the extension, so `view('./article/list')` and `view('./article/list.html')` are equivalent
+- `plural_rules` - Plural rules keyed by language code, registering `'en_us'` by default; the `Lang` class of mm_expand already ships `zh_cn` and `en` rules, so other language codes are registered here
+- `langs` - In-memory language pack dictionary, e.g. `{'zh_cn': {...}, 'en_us': {...}}`, takes precedence over language files; when both it and `lang_dir` are empty, the global `$.lang.config` is used
+- `user_store` - User preference store, `null` by default (an in-process `Memory`); pass an object implementing the six synchronous methods `getUser` / `setUser` / `delUser` / `hasUser` / `listUsers` / `clear` to replace it with a file, a database or a cache service, or use the built-in `Memory` / `Sqlite` directly; derived instances reuse the same store
+- `cache_dims` - Cache layering dimensions, defaults to `['style', 'lang']`; values may be `theme`, `style`, `lang`. The order is the directory order, and it should only contain **user-selectable** dimensions
+- `cache_type` - Cache type, defaults to `'file'` (physical files); `'memory'` keeps the cache in process memory
+- `cache_max` - Max entries of the in-memory cache, defaults to `1000`; the earliest written entry is evicted beyond it, `0` means unlimited
 
 ### Hook Class Methods
 
@@ -300,20 +1107,56 @@ if (global.$ && !$.Tpl) {
 - `delFunc(name, alias)` - Delete function hook
 - `delAction(name, alias)` - Delete action hook
 - `delFilter(name, alias)` - Delete filter hook
-- `clear(name)` - Clear hooks
+- `clear(name)` - Clear hooks
+
+The methods above behave identically on the global `$.hook` singleton and on the instance-level `tpl.hook`. They differ in scope: `$.hook` affects every instance, while `tpl.hook` affects only the current instance and the instances derived from it; both levels run during rendering, global first and instance-level second.
 
 ## Notes
 
 1. **Dependencies**: Requires `art-template` and `mm_expand` dependency packages
 2. **Directory Permissions**: Ensure template directories have read/write permissions
-3. **Cache Management**: Clean expired cache promptly to avoid memory leaks
+3. **Cache Management**: The cache is layered by `cache_dims`, mind the directory levels when clearing; `clearCache` without a path clears only the cache directory of the current instance, pass `'./'` to clear everything. Template or language pack changes invalidate the cache automatically, so manual clearing is usually unnecessary
 4. **Hook Priority**: Lower numerical values indicate higher priority and earlier execution
 5. **Async Processing**: Hook functions support async operations, pay attention to error handling
-6. **File Search**: Template files are searched in priority order, ensure files exist
+6. **File Search and Output Order**: Each kind of resource has its own directory chain. Templates use **three** levels, `static/diy/` → current theme → default theme, and are **not layered by style**, so a style never changes which template is used; the path is relative to the theme directory and may include feature directories such as `article/list.html`. Components use **three** levels of their own, isomorphic to the template chain with one extra fixed `component/` prefix on every level: `static/diy/component/` → current theme `component/` → default theme `component/`; a component name is not resolved relative to the calling file, and a component missing from the current theme falls back to the default theme. Styles use **five** levels: `static/diy/` → current theme + current style → current theme + base style → default theme + current style → default theme + base style. Scripts use **four** levels: `static/diy/` → current theme → default theme → application-level `static/js/`. For templates the highest-priority same-named file wins, while styles and scripts keep only the highest-priority copy per filename. Styles and scripts are "reference many" resources, so `getCssFiles` / `getJsFiles` and the like return them in **ascending** priority order (lower priority first, higher priority after), because a later-loaded CSS rule is the one that takes effect and the order of JS decides execution; language packs are the opposite, merged in descending priority order
 7. **Character Escaping**: Automatic handling of template syntax characters to avoid conflicts
+8. **Multi-user Isolation**: The theme is a deployment-level setting, uniform for every user on the site and not user-selectable; style and language are user-level. Rendering can use **passing options** (a single instance, with `style` / `lang` in the `view` options, restored afterwards) or **deriving instances** (`fork`); see [Using Styles and Languages Across Users](#6-using-styles-and-languages-across-users). **`viewBag` is shared at instance level**: user-level data must be passed through `model` (templates read `${user_id}`) and never written into `viewBag` (templates read `${viewBag.user_id}`); only when one separate instance is derived per user is `viewBag` private to that user. Do not `set` user-level data into a shared instance's `viewBag`, and do not let multiple users share one instance and switch `current_style` / `lang` on it, otherwise they will pollute each other
+9. **Shared Language Packs**: Language objects already present in the `langs` option are shared across instances and are meant for "picking" only; writing custom entries via `lang.set()` on an instance may pollute other users — deep-copy `langs` after `fork` if you really need to write. Language pack files are re-read into new objects, so they are not affected; the global `$.lang.config` used as a fallback when both `lang_dir` and `langs` are empty is also copied deeply, so writing on an instance never pollutes the global one
+10. **Cache Count**: Cache files ≤ (named styles + 1) × languages × cached templates, **independent of the number of users**; "no style selected" counts as a distinct combination but occupies no directory level (it only appears when `default_style` is empty too), and combinations that are never requested produce no file. `cache_dims` should only contain **user-selectable** dimensions (style and language by default), since every extra dimension multiplies the count; the accepted values are `theme`, `style` and `lang`, and `user_id` is no longer supported — passing it logs a warning and the dimension is ignored
+11. **Correctness Risk of Per-user Caching**: When cached content depends on user data, such content is served stale for as long as the cache lives (a user who tops up still sees the old balance). Such pages are not suitable for full-page caching; fetch the user-specific regions asynchronously. When per-user separation is genuinely required, pass an explicit `cache_filename`, or use the in-memory cache with a small `cache_max`
+12. **Theme Not in Cache Layering**: The theme is a deployment-level setting and is excluded from `cache_dims` by default. Switching the theme at runtime reuses the previous theme's cache and `setTheme` logs a warning; call `clearCache()` after switching, or include `theme` in the dimensions
+13. **Theme and Style Validation**: `setTheme` / `setStyle` validate the directory by default, keeping the old value and logging a warning when it is missing; pass `force` to skip validation before the directory is created. An empty style string means no style is set, and lookup and cache fall back to the default style
+14. **Style and Theme Fallback**: `setStyle` only validates whether the style directory exists under the current or default theme, keeping the old value and logging a warning when it is missing; assigning `current_style` directly skips validation. Style lookup **only falls back across themes** (current theme + current style → current theme + base style → default theme + current style → default theme + base style) and **never across styles**, so files of other style directories are not inherited. Put shared styles in the base style directory (`base_style`, `base` by default) and keep only differences in each style directory; when one style needs its own version of a shared file, place a same-named file in that style directory to override the base style. This concerns stylesheets only: templates are not layered by style and always resolve along `static/diy/` → current theme → default theme
+15. **Translation Lookup**: Template files must call `$t('key')` to emit multilingual content; hard-coded text does not follow the language switch. Keep copy in JSON language packs under the language pack directories (the filename is the language code, e.g. `zh_cn.json`, `en_us.json`) and let templates only resolve entries
+16. **Language Cache Cost**: While `lang` stays in `cache_dims`, each language keeps its own copy of the cache for the same template. Drop the `lang` dimension if the templates are not actually multilingual
+17. **Language File Changes**: Language files are read only when an instance is created, and already created instances are not refreshed automatically; new instances and `fork` decide by file fingerprint whether to re-read. Call `reloadLangs()` or `loadLang(lang)` to apply changes to an existing instance. `setTheme` reloads automatically so theme language packs take effect
+18. **Language Pack Cache**: Language packs are cached in the static property `Tpl.lang_cache` keyed by "directory set + file fingerprint", so `fork` does not re-parse unchanged files. The cache is memory-only and is re-read after a process restart. The fingerprint relies on mtime, so a change within the same time granularity may go unnoticed — use `reloadLangs(true)` to force a refresh
+19. **Cache Filename**: `cache_filename` is always normalised to end with `cache_extname`, so `./index` and `./index.html` both become `index.cache.html`, which lets `clearCache` match by extension; when `view` receives `cache` without a `cache_filename`, the name is derived from the template path automatically
+20. **Automatic Invalidation**: The cache is rebuilt when the template file or a language pack file is newer than the cache, judged by modification time. Relying on timestamps means a change within the same time granularity may go unnoticed; language pack changes are not checked when `cache_dims` excludes `lang`
+21. **In-memory Cache**: With `cache_type: 'memory'` no physical files are produced and entries live in `Tpl.cache_store` with least-recently-used eviction. The cache is cleared on process restart, so in a multi-instance deployment each process keeps its own copy and they do not share invalidation state
+22. **In-memory and File Caches Are Separate**: The two modes read and write different locations, so switching `cache_type` leaves the old cache behind — call `clearCache()` as needed
+23. **Temporary Options of Passing-Render**: `options.style` and `options.lang` on `view` / `render` / `getCacheFile` apply to that call only and are restored afterwards without changing the instance state; `view` renders synchronously, so it is safe under concurrent requests. Keep them distinct from `setStyle` / `setLang`, which change the instance state persistently
+24. **User Preference Store**: `user_store` defaults to an in-process `Memory` and dies with the process; inject shared storage (the built-in `Sqlite`, or an object implementing the six synchronous methods `getUser` / `setUser` / `delUser` / `hasUser` / `listUsers` / `clear`) for multi-process or multi-machine deployments, otherwise each process sees only its own data. The store performs no authorisation, so the caller must ensure `user_id` is trustworthy
+25. **Hook Scope**: `$.hook` is a global singleton whose hooks affect every instance, while `tpl.hook` affects only the current instance and the instances derived from it; both levels run during rendering (global first, instance-level second). Template function precedence is "a same-named field in this call's `model` > built-in functions > registered functions"
+26. **Object Literals Inside Expressions**: An object literal inside `${ }` is parsed in full, so `${@$component('bar', { id: 1 })}` and `${$t('welcome', { name: 'Tom' })}` can be written directly without assigning to a variable first. Only **non-nested** literals are supported: nested forms such as `{a:{b:1}}` are not recognised as an expression and are emitted as plain text (no error is thrown) — use the comment-style `<!--{@ }-->` delimiter or assign to a variable instead
+27. **Component Model and Inheritance**: The `$component` model is merged with the caller's data (`Object.assign`); the caller's data and template helpers such as `$view` / `$css` / `$t` are all passed down to the component, and fields in the passed model override the caller's
 
 ## Development
 
+Module layout:
+
+- `index.js` - Module entry, defines the public main class `Tpl` and exports the store classes `Memory` / `Sqlite`
+- `lib/engine.js` - `Engine`, a single engine instance: rendering, caching, the theme/style/language orchestration and instance derivation (`fork`), plus `getThemeDir` / `getStyleDir` / `getTemplateDirs` / `getComponentDirs` / `getComponentFile` / `getStyleDirs` / `getJsDirs` / `getCssFiles` / `getJsFiles`
+- `lib/template.js` - `Template`, template file lookup: resolves a template under the theme directory by feature path (`static/diy/` → current theme → default theme), and also resolves components along their own directory chain (`getComponent`)
+- `lib/asset.js` - `Asset`, the asset loading base class for styles and scripts: collecting by directory priority, de-duplicating by filename and emitting in ascending priority order
+- `lib/css.js` - `Css`, style file collection (extends `Asset`)
+- `lib/js.js` - `Js`, script file collection (extends `Asset`)
+- `lib/lang.js` - `Lang`, language pack merging and caching
+- `lib/store.js` - `Memory`, the in-memory store: `user_id` → `{style, lang}`
+- `lib/sqlite.js` - `Sqlite`, the SQLite store: same contract as `Memory`, persisting to a file (relies on `node:sqlite`)
+- `lib/util.js` - `TplUtil`, pure static helper methods
+- `hook.js`, `tpl_rule.js` - hooks and template syntax rules
+
 ```bash
 # Run tests
 npm test