@lark.js/mvc 0.0.13 → 0.0.15

package/README.md

@@ -120,7 +120,7 @@ Both integrations share the same compilation pipeline: `extractGlobalVars` extra
 import { defineView, Router } from "@lark.js/mvc";
 
 export default defineView({
-  make() {
+  ctor() {
     this.updater.set({ appName: "My App" });
     this.on("destroy", () => console.log(`view destroyed: ${this.id}`));
   },
@@ -130,7 +130,7 @@ export default defineView({
 });
 ```
 
-`defineView` is a typed wrapper around `View.extend`: via `ThisType<P & ViewInterface>` it threads the literal's own fields into `this`, so writing `this.appName` in `make` requires no cast. Runtime behavior is equivalent to `View.extend({...})`.
+`defineView` is a typed wrapper around `View.extend`: via `ThisType<P & ViewInterface>` it threads the literal's own fields into `this`, so writing `this.appName` in `ctor` requires no cast. Runtime behavior is equivalent to `View.extend({...})`.
 
 ### View and Template
 
@@ -439,7 +439,7 @@ Both produce equivalent runtime artifacts; the difference is purely in TypeScrip
 ### Lifecycle
 
 - `init(params?)` — Called when the view is first instantiated. `params` comes from query strings on `v-lark`. Read stores and call `this.assign()` to prepare initial data here.
-- `make()` — Called by the merged makes pipeline; each mixin's `make` executes in order. Suitable for "run once per instance" initialization.
+- `ctor()` — Called by the merged ctors pipeline; each mixin's `ctor` executes in order. Suitable for "run once per instance" initialization.
 - `assign()` — Should be called when data may have changed. Pattern: `this.updater.snapshot()` at the top, `this.updater.set(...)` in the middle, `return this.updater.altered()` at the end. The framework uses `altered()` to determine whether re-render is needed.
 - `render()` — Default implementation is `this.updater.digest()`. Wrapped by `View.wrapMethod`: increments signature on entry, handles pending endUpdate cleanup on exit.
 - Destruction — The framework automatically calls `release(key, true)` to release all `capture`d resources, cleans up event delegation, and sets signature to 0.
@@ -735,7 +735,6 @@ Marking large static subtrees with `ldk` can completely skip rendering work. Thi
 | `Frame.getAll()`                                  | All Frames as `Map<string, Frame>`                                                                                             |
 | `Frame.getRoot()`                                 | Current root Frame; returns `undefined` if not created                                                                         |
 | `Frame.createRoot(id)`                            | Idempotent root creation (`Framework.boot` calls this)                                                                         |
-| `Frame.root(id)`                                  | `@deprecated` alias, forwards to `createRoot`                                                                                  |
 | `new Frame(containerId)`                          | Independent Frame instance for micro-frontend / embedded widget scenarios                                                      |
 | `frame.invoke(name, args?)`                       | Call the owning view's method; if view not mounted, pushes to `invokeList`, flushed by `View.runInvokes(frame)` after mounting |
 | `frame.children()`                                | Child Frame id array (order not guaranteed)                                                                                    |
@@ -945,7 +944,7 @@ Similarities: unidirectional data flow; immutable write-back style; async protec
 | --------------------- | ---------------------------------------- | ------------------------------------------------------------ |
 | Component abstraction | Function components + Hooks              | Class inheritance `View.extend` / `defineView`               |
 | State encapsulation   | `useState` / `useReducer`                | View instance fields, `create()` store, `State`              |
-| Side effects          | `useEffect` / `useLayoutEffect`          | `init` / `make` + `capture` / `release`                      |
+| Side effects          | `useEffect` / `useLayoutEffect`          | `init` / `ctor` + `capture` / `release`                      |
 | Render interruption   | Fiber time-slicing, Suspense, Transition | Synchronous digest, not interruptible                        |
 | Compile optimization  | React Compiler (auto-memo)               | Template compile-time only; no runtime auto-memo             |
 | Server rendering      | RSC, streaming SSR                       | Not supported (design trade-off)                             |

package/dist/apply-style.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Dynamically inject CSS styles into the document head.
+ * Returns a cleanup function to remove the injected styles.
+ *
+ * @param styleIdOrPairs - Style ID string or array of [id, content] pairs
+ * @param css - CSS content string (only used when first arg is string)
+ * @returns Cleanup function to remove the styles
+ */
+export declare function applyStyle(styleIdOrPairs: string | string[], css?: string): () => void;

package/dist/cache.d.ts

@@ -0,0 +1,69 @@
+import type { CacheInterface, CacheOptions } from "./types";
+/**
+ * Cache class with LFU-style eviction.
+ * Keys are prefixed with SPLITTER for namespace isolation.
+ *
+ * @example
+ * const cache = new Cache({ maxSize: 20, bufferSize: 5 });
+ * cache.set('user', { name: 'Alice' });
+ * const user = cache.get('user');
+ * cache.has('user'); // true
+ * cache.del('user');
+ */
+export declare class Cache<T = unknown> implements CacheInterface<T> {
+    /** Cache entries array */
+    private entries;
+    /** Fast lookup: prefixed key -> entry */
+    private lookup;
+    /** Buffer size for eviction */
+    private readonly bufferSize;
+    /** Maximum cache size */
+    private readonly maxSize;
+    /** Total capacity (maxSize + bufferSize) */
+    private readonly capacity;
+    /** Callback when entry is removed */
+    private readonly onRemove?;
+    /** Sort comparator */
+    private readonly comparator;
+    constructor(options?: CacheOptions<T>);
+    /** Prefix a key with SPLITTER for namespace isolation */
+    private prefixKey;
+    /**
+     * Get a cached value by key.
+     * Updates frequency and timestamp for cache sorting.
+     */
+    get(key: string): T | undefined;
+    /**
+     * Iterate all cached values.
+     */
+    forEach(callback: (value: T | undefined) => void): void;
+    /**
+     * Set or update a cached value.
+     * If key already exists, updates value and increments frequency.
+     * If cache exceeds capacity, triggers eviction.
+     */
+    set(key: string, value: T): void;
+    /**
+     * Delete a cached entry. Removes it immediately from both the lookup map
+     * and the entries array so the GC can reclaim the value without waiting
+     * for the next eviction sweep.
+     */
+    del(key: string): void;
+    /**
+     * Check if a key exists in cache.
+     */
+    has(key: string): boolean;
+    /** Get current cache size */
+    get size(): number;
+    /** Clear all entries */
+    clear(): void;
+    /**
+     * Evict the `bufferSize` worst entries from the cache.
+     *
+     * Uses single-pass partial selection (O(n·k)) instead of sorting the entire
+     * `entries` array (O(n log n)). For the typical `bufferSize = 5` this is
+     * effectively a linear scan with at most 5 in-bucket comparisons per
+     * iteration — and it avoids mutating the rest of `entries`.
+     */
+    private evictEntries;
+}

package/dist/common.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Lark framework constants.
+ */
+/** Internal splitter character (U+001E Record Separator, invisible, used as namespace separator).
+ * Uses String.fromCharCode to survive bundlers that strip control-char literals. */
+export declare const SPLITTER: string;
+export declare const RouterEvents: {
+    CHANGE: string;
+    CHANGED: string;
+    PAGE_UNLOAD: string;
+};
+/** Attribute name: v-lark */
+export declare const LARK_VIEW = "v-lark";
+/** View event method regex: e.g. "app\x1eclickHandler(click)" or "clickHandler()"
+ * Group 1: optional frame ID (before SPLITTER)
+ * Group 2: handler name
+ * Group 3: params string
+ */
+export declare const EVENT_METHOD_REGEXP: RegExp;
+/** View event method name regex: e.g. "name<click,mousedown>" or "$selector<click>" */
+export declare const VIEW_EVENT_METHOD_REGEXP: RegExp;
+/** URL query/hash trim regexp */
+export declare const URL_TRIM_HASH_REGEXP: RegExp;
+/** URL trim query regexp (before hash) */
+export declare const URL_TRIM_QUERY_REGEXP: RegExp;
+/** URL param key-value regexp */
+export declare const URL_PARAM_REGEXP: RegExp;
+/** URL params test regexp */
+export declare const IS_URL_PARAMS: RegExp;
+/** URL query/hash trim regexp for path extraction */
+export declare const URL_QUERY_HASH_REGEXP: RegExp;
+/** SVG namespace */
+export declare const SVG_NS = "http://www.w3.org/2000/svg";
+/** MathML namespace */
+export declare const MATH_NS = "http://www.w3.org/1998/Math/MathML";
+/** Tag name regexp for I_GetNode */
+export declare const TAG_NAME_REGEXP: RegExp;
+/** Async task break time (ms) */
+export declare const CALL_BREAK_TIME = 48;
+/** VDOM text node tag value (number 0, falsy, distinct from string tags) */
+export declare const V_TEXT_NODE = 0;
+/** Namespace map for SVG/MathML element creation in VDOM mode */
+export declare const VDOM_NS_MAP: Record<string, string>;
+/** Increment global counter and return new value */
+export declare function nextCounter(): number;
+/** Null-safe String conversion */
+export declare function strSafe(v: unknown): string;
+/** HTML entity encoding for safe output */
+export declare function encodeHTML(v: unknown): string;
+/** URI-encode with extra character encoding */
+export declare function encodeURIExtra(v: unknown): string;
+/** Quote-encode for attribute values */
+export declare function encodeQuote(v: unknown): string;
+/**
+ * Template reference function for creating stable keys for objects.
+ * Stores objects in refData with SPLITTER-prefixed keys.
+ */
+export declare function refFn(ref: Record<string, unknown>, value: unknown, key: string): string;
+/**
+ * Check if a string is a refData reference token: SPLITTER followed by
+ * one or more ASCII decimal digits. Used by utils.ts translateData and
+ * updater.ts translate.
+ */
+export declare function isRefToken(s: string): boolean;

package/dist/compiler/compile-template.d.ts

@@ -0,0 +1,16 @@
+import type { CompileOptions } from "@/types";
+/**
+ * Compile an HTML template string into a JS module string.
+ * This is the main entry point for both Vite and Webpack loaders.
+ *
+ * The output is an ES module that exports a function with the signature:
+ *   (data, viewId, refData) => string
+ *
+ * Internally it calls the compiled template function with the standard
+ * signature: ($data,$viewId,$refAlt,$encHtml,$strSafe,$encUri,$refFn,$encQuote)
+ *
+ * @param source - The raw HTML template content
+ * @param options - Compilation options
+ * @returns ES module source code exporting the compiled template function
+ */
+export declare function compileTemplate(source: string, options?: CompileOptions): Promise<string>;

package/dist/compiler/compile-to-vdom-function.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Compile the internal `<% %>` syntax to a VDOM template function string.
+ *
+ * Uses htmlparser2 for robust HTML parsing:
+ * 1. Extract `<% %>` blocks into a store, replace with `\x00N\x00` placeholders
+ * 2. Parse the protected source with `parseDocument`
+ * 3. Walk the DOM tree recursively, emitting `$c()` (vdomCreate) calls
+ *
+ * Output is an arrow function:
+ *   `($data,$viewId,$refAlt,$n,$refFn,$encUri,$encQuote)=>{...}`
+ * that returns the root VDomNode.
+ */
+export declare function compileToVDomFunction(source: string, debug: boolean, file?: string): string;

package/dist/compiler/extract-global-vars.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Extract global variable names from a template source using AST analysis.
+ *
+ * 1. Convert template commands (<% %> blocks) into a form parseable by an AST parser
+ * 2. Walk the AST to find all Identifier nodes
+ * 3. Track variable declarations (VariableDeclarator, FunctionDeclaration) as local vars
+ * 4. Track function parameters as local vars
+ * 5. Remaining identifiers that are not local and not in the exclusion list are "global" —
+ *    they must be passed in as part of the data context ($$)
+ *
+ * This replaces the old regex-based `extractVariables()` with proper scope analysis,
+ * eliminating false positives from local template variables and function parameters.
+ *
+ * @param source - The raw HTML template content (with {{ }} syntax)
+ * @returns Array of global variable names found in the template
+ */
+export declare function extractGlobalVars(source: string): Promise<string[]>;

package/dist/compiler/template-syntax.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @lark.js/mvc Template Compiler
+ *
+ *   convertArtSyntax()    ({{}} → <% %>)
+ *   processViewEvents()      (@event prefix + param encoding)
+ *   compileToFunction()  (<% %> → JS template function)
+ *   extractGlobalVars()   (AST-based global var analysis via @babel/parser)
+ *
+ * - All template operators: = (escape), ! (raw), @ (ref lookup), : (binding)
+ * - @event attribute processing with $splitter prefix + \x1e separator
+ * - $strSafe (null-safe toString), $encHtml (HTML entity encode), $encUri (URI encode), $encQuote (quote encode), $refFn (ref lookup)
+ * - Debug mode with line tracking ($dbgExpr/$dbgArt/$dbgLine) and try-catch error wrapper
+ * - View ID injection (\x1f → '+$viewId+')
+ * - Post-processing cleanup of empty concatenations
+ * - 0 configuration: auto-extract variables via AST analysis
+ *
+ * Template syntax:
+ *   {{=variable}}              → escaped output
+ *   {{:variable}}              → two-way binding (same as = for rendering)
+ *   {{!variable}}              → raw output (no HTML escaping)
+ *   {{@variable}}              → reference lookup for component data passing
+ *   {{forOf list as item}}      → loop
+ *   {{forOf list as item idx}}  → loop with index
+ *   {{forIn obj as val key}}   → object iteration
+ *   {{for(let i=0;i<n;i++)}}  → generic for loop
+ *   {{if condition}}           → conditional
+ *   {{else if condition}}      → else-if
+ *   {{else}}                   → else
+ *   {{/if}} / {{/forOf}} / {{/forIn}} / {{/for}} → close blocks
+ *   {{set a = b}}              → variable declaration
+ */
+/** Protected comment store — used internally by protectComments */
+/**
+ * Preserve HTML comments to prevent template syntax inside comments from being converted.
+ */
+export declare function protectComments(source: string): {
+    protectedSource: string;
+    comments: string[];
+};
+/**
+ * Restore previously protected HTML comments.
+ */
+export declare function restoreComments(source: string, comments: string[]): string;
+/**
+ * Process @event attributes.
+ *
+ * 1. Add \x1f (VIEW_ID_PLACEHOLDER, becomes $viewId at render time) prefix + \x1e separator
+ * 2. Convert JS object literal params to URL query params
+ *
+ * @click="handlerName({key: 'value'})" → @click="\x1f\x1ehandlerName(key=value)"
+ * @click="handlerName()"               → @click="\x1f\x1ehandlerName()"
+ * @click="goHome"                      → unchanged (no parens = not an event handler)
+ */
+export declare function processViewEvents(source: string): string;
+/**
+ * Convert {{=}}/{{:}}/{{!}}/{{@}} and control flow syntax to internal <% %> syntax.
+ *
+ * In debug mode, adds \x11-delimited line tracking markers:
+ *   <%'lineNo\x11code\x11'%> before forOf art expression
+ */
+export declare function convertArtSyntax(source: string, debug: boolean): string;