mancha 0.24.0 → 0.24.2

package/README.md

@@ -40,13 +40,31 @@ Here's a small sample of the things that you can do with `mancha`:
 - **testing**, individual components can be rendered and tested outside the browser
 - **progressive enhancement**, from simple templating and basic reactivity to a full-blown app
 
-| Feature               | mancha | Svelte | React.js | Vue.js | petite-vue | Alpine.js |
-| --------------------- | ------ | ------ | -------- | ------ | ---------- | --------- |
-| Simple to learn       | ✔️     | ❌     | ❌       | ❌     | ✔️         | ✔️        |
-| < 18kb compressed     | ✔️     | ✔️     | ❌       | ❌     | ✔️         | ❌        |
-| Custom web components | ✔️     | ✔️     | ✔️       | ✔️     | ❌         | ❌        |
-| Client-side rendering | ✔️     | ❌     | ❌       | ✔️     | ✔️         | ✔️        |
-| Server-side rendering | ✔️     | ✔️     | ✔️       | ✔️     | ❌         | ❌        |
+`mancha` is not the smallest option. It is the one that does all of it in a
+single file: drop it in a script tag to prototype, then keep the same templates
+when you move to a bundler or render them on the server.
+
+| Library                | Size (brotli) | Script tag | Custom tags | Server rendering | CSS utilities |
+| ---------------------- | ------------: | ---------- | ----------- | ---------------- | ------------- |
+| [petite-vue][pv] 0.4.1 |       6,513 B | ✔️         | ❌          | ❌               | ❌            |
+| [htmx][hx] 2.0.10      |      14,996 B | ✔️         | ❌          | ❌               | ❌            |
+| [Svelte][sv] 5.56.9    |      15,106 B | ❌         | ✔️          | ✔️               | ❌            |
+| [Alpine.js][al] 3.16.1 |      15,400 B | ✔️         | ❌          | ❌               | ❌            |
+| **mancha 0.24.2**      |  **19,852 B** | ✔️         | ✔️          | ✔️               | ✔️            |
+| [React][re] 19.2.8     |      52,002 B | ❌         | ✔️          | ✔️               | ❌            |
+| [Vue][vu] 3.5.41       |      54,171 B | ✔️         | ✔️          | ✔️               | ❌            |
+
+Sizes are the brotli-compressed bytes of the file you download, at the version
+shown. Run `npm run compare:sizes` to re-measure them. Svelte and React ship no
+drop-in build — React 19 dropped its UMD build entirely — so their sizes come
+from bundling a minimal app instead.
+
+[al]: https://alpinejs.dev
+[hx]: https://htmx.org
+[pv]: https://github.com/vuejs/petite-vue
+[re]: https://react.dev
+[sv]: https://svelte.dev
+[vu]: https://vuejs.org
 
 ## Documentation
 
@@ -60,6 +78,7 @@ Here's a small sample of the things that you can do with `mancha`:
 - **[TypeScript](./docs/07_typescript.md)**: Type safety and checking.
 - **[Testing](./docs/08_testing.md)**: Testing your UI.
 - **[Performance](./docs/09_performance.md)**: Performance monitoring and optimization.
+- **[Security](./docs/10_security.md)**: What rendering a template grants it, and where the trust boundary is.
 
 ## AI Agents
 

package/dist/browser.d.ts

@@ -1,4 +1,3 @@
-import { a as StoreState, i as IRenderer, n as RenderParams, r as RendererPlugin, t as ParserParams } from "./interfaces-C8heJ6BZ.js";
 import { SafeStyleSheet } from "safevalues";
 
 //#region src/css_custom.d.ts
@@ -8,6 +7,457 @@ declare function scanAndInject(root?: Element | Document | DocumentFragment): vo
 /** For testing: reset module state. */
 declare function _resetForTesting(): void;
 //#endregion
+//#region src/store.d.ts
+/**
+ * Internal store properties that are always present. These are managed by the framework
+ * and should not be set directly by users.
+ */
+type InternalStoreState = {
+  /** Reference to the parent store in a hierarchy. */
+  $parent?: SignalStore;
+  /** Reference to the root renderer instance. */
+  $rootRenderer?: SignalStore;
+  /** Reference to the root DOM node. */
+  $rootNode?: Node;
+} & {
+  [key: `$$${string}`]: string | null;
+};
+/**
+ * Base type for user-defined store state. Uses `any` intentionally to allow flexible
+ * user-defined state types without requiring explicit index signatures.
+ */
+type StoreState = Record<string, any>;
+/** Type for expression evaluation function. */
+type EvalFunction = (thisArg: SignalStoreProxy, args: Record<string, unknown>) => unknown;
+/** Type for observer entries that include the store context for proper binding. */
+type ObserverEntry = {
+  observer: Observer<unknown>;
+  store: SignalStore;
+  computedKey?: string;
+};
+/**
+ * Internal proxy type used within the store implementation. Uses `any` for dynamic property access.
+ */
+type SignalStoreProxy = SignalStore & InternalStoreState & {
+  [key: string]: any;
+};
+/**
+ * The reactive context type exposed to effects and computed functions.
+ * Includes the store's typed state T, internal state, and an index signature for dynamic access.
+ */
+type ReactiveContext<T extends StoreState = StoreState> = SignalStore<T> & InternalStoreState & T & Record<string, unknown>;
+type Observer<T> = (this: SignalStoreProxy) => T;
+type KeyValueHandler = (this: SignalStoreProxy, key: string, value: unknown) => void;
+/** Symbol used to identify computed value markers. */
+
+/** Function type for computed value definitions. Receives reactive context as `$` parameter. */
+type ComputedFn<T extends StoreState, R> = (this: ReactiveContext<T>, $: ReactiveContext<T>) => R;
+declare class SignalStore<T extends StoreState = StoreState> {
+  protected readonly evalkeys: string[];
+  protected readonly expressionCache: Map<string, EvalFunction>;
+  protected readonly observers: Map<string, Set<ObserverEntry>>;
+  protected readonly keyHandlers: Map<RegExp, Set<KeyValueHandler>>;
+  readonly _store: Map<string, unknown>;
+  _lock: Promise<void>;
+  /** Keys with a scheduled observer run. */
+  private readonly _pending;
+  /** Keys whose observers are running right now. */
+  private readonly _executing;
+  /** Keys written while their own observers were running, to notify afterwards. */
+  private readonly _dirty;
+  /**
+   * Stores created from this one, disposed along with it. A subrenderer is only reachable
+   * through the store that created it and the node it renders, so without this nothing ever
+   * disposes a nested `:for` row or a `:render` subrenderer.
+   */
+  protected readonly _children: Set<SignalStore<StoreState>>;
+  /** Per-key deep-mutation subscribers, kept stable so they can be unsubscribed later. */
+  private readonly _mutationCallbacks;
+  /** Set by dispose(). Observers registered by a disposed store must no longer run. */
+  protected _disposed: boolean;
+  /**
+   * Tracks nested computed evaluation depth. When > 0, we're inside a computed
+   * function and writes to reactive properties should trigger a warning.
+   */
+  private _computedDepth;
+  constructor(data?: T);
+  private wrapObject;
+  watch<T>(key: string, observer: Observer<T>): void;
+  addKeyHandler(pattern: RegExp, handler: KeyValueHandler): void;
+  /**
+   * Tags all observer entries matching the given observer function with a computed key.
+   * Called after effect runs to mark which observers belong to which computed.
+   */
+  private tagObserversForComputed;
+  /**
+   * Synchronously marks all computeds that depend on this key as dirty.
+   * Uses the computedKey field on observer entries for O(1) key lookup.
+   * Cascades through computed chains (if A depends on B, and B is marked dirty,
+   * then A is also marked dirty).
+   */
+  private markDependentComputedsDirty;
+  /**
+   * Invokes `entries` and returns their pending tails. Stays synchronous from end to end:
+   * the caller relies on nothing being able to interleave until it returns.
+   */
+  private runObservers;
+  notify(key: string, debounceMillis?: number): Promise<void>;
+  get<T>(key: string, observer?: Observer<T>): unknown;
+  private setupComputed;
+  /**
+   * Returns this store's deep-mutation subscriber for `key`. The same key always yields the
+   * same function, so subscriptions can be matched and removed. Created on demand, so a key
+   * that never holds an object never retains a closure.
+   */
+  private mutationCallback;
+  /**
+   * Sets a value in the store.
+   * @param key - The key to set.
+   * @param value - The value to set (can be a computed marker).
+   * @param local - If true, sets directly on this store bypassing ancestor lookup.
+   *                Use for creating local scope variables that shadow ancestors.
+   */
+  set(key: string, value: unknown, local?: boolean): Promise<void>;
+  del(key: string): Promise<void>;
+  /**
+   * Releases this store and every store created from it, recording them in `disposed` for the
+   * single ancestor pass that follows. Observers registered on ancestors are deliberately left
+   * to the caller: every store here shares this store's ancestors, so removing them once for
+   * the whole subtree replaces a scan of every ancestor once per descendant.
+   */
+  private disposeSubtree;
+  /**
+   * Disposes this store by clearing all observers.
+   * Call this when the store is no longer needed to prevent memory leaks.
+   * Also removes any observers this store registered on ancestor stores, disposes the stores
+   * created from this one, and stops listening to deep mutations of the values it holds.
+   */
+  dispose(): void;
+  keys(): string[];
+  /**
+   * Checks if a key exists in THIS store only (not ancestors).
+   * Use `get(key) !== null` to check if a key exists anywhere in the chain.
+   */
+  has(key: string): boolean;
+  /**
+   * Returns observer statistics for performance reporting.
+   */
+  getObserverStats(): {
+    totalKeys: number;
+    totalObservers: number;
+    byKey: Record<string, number>;
+  };
+  effect<R>(observer: (this: ReactiveContext<T>) => R, _meta?: EffectMeta): R;
+  /**
+   * Creates a computed property that automatically updates when its dependencies change.
+   * The function is evaluated in a reactive effect, and the result is stored. When any
+   * reactive property accessed within the function changes, it re-evaluates and updates.
+   *
+   * **Important:** This method returns a marker object at runtime, but is typed as
+   * returning `R` to enable ergonomic property assignment without type casts. The return
+   * value must be assigned to a store property (via `set()` or `$.prop =`) - do not use
+   * it directly as a value.
+   *
+   * @example
+   * // Using function() to access reactive `this`:
+   * store.set('double', store.$computed(function() { return this.count * 2 }));
+   *
+   * // Using arrow function with $ parameter (for templates):
+   * store.set('double', store.$computed(($) => $.count * 2));
+   *
+   * // Direct property assignment (ergonomic typing):
+   * store.$.doubled = store.$computed(($) => $.count * 2);
+   */
+  $computed<R>(fn: ComputedFn<T, R>): R;
+  private proxify;
+  get $(): SignalStore<T> & InternalStoreState & T;
+  /**
+   * Creates an evaluation function for the provided expression.
+   * @param expr The expression to be evaluated.
+   * @returns The evaluation function.
+   */
+  private makeEvalFunction;
+  /**
+   * Retrieves or creates a cached expression function for the provided expression.
+   * @param expr - The expression to retrieve or create a cached function for.
+   * @returns The cached expression function.
+   */
+  private cachedExpressionFunction;
+  eval(expr: string, args?: Record<string, unknown>): unknown;
+  /**
+   * Executes an async function and returns a reactive state object that tracks the result.
+   *
+   * @param fn - The async function to execute.
+   * @param options - Optional arguments to pass to the function.
+   * @returns A reactive state object with $pending, $result, and $error properties.
+   *
+   * @example
+   * // In :data attribute - executes on mount
+   * :data="{ users: $resolve(api.listUsers) }"
+   *
+   * // With options
+   * :data="{ user: $resolve(api.getUser, { path: { id: userId } }) }"
+   *
+   * // In :on:click - executes on click
+   * :on:click="result = $resolve(api.deleteUser, { path: { id } })"
+   */
+  $resolve<T, O = unknown>(fn: (options?: O) => Promise<T>, options?: O): {
+    $pending: boolean;
+    $result: T | null;
+    $error: Error | null;
+  };
+}
+//#endregion
+//#region src/renderer.d.ts
+/**
+ * Represents an abstract class for rendering and manipulating HTML content.
+ * Extends the `ReactiveProxyStore` class.
+ *
+ * @template T - The type of the store state. Defaults to `StoreState`.
+ */
+declare abstract class IRenderer<T extends StoreState = StoreState> extends SignalStore<T> {
+  abstract readonly impl: string;
+  private _debugLevel;
+  protected readonly dirpath: string;
+  /** Performance data collected during rendering. Reset on each mount(). */
+  private _perfData;
+  /** Debug level ordering for comparison. */
+  private static readonly DEBUG_LEVELS;
+  readonly _skipNodes: Set<Node>;
+  readonly _customElements: Map<string, Node>;
+  /**
+   * Queue for retrying failed element.value assignments.
+   *
+   * Some DOM elements (notably <select>) silently fail when setting .value if
+   * the required child elements don't exist yet. For example, setting
+   * select.value = "banana" does nothing if no <option value="banana"> exists.
+   *
+   * This happens when :bind on a parent element runs before :for on child
+   * elements creates those children (due to BFS traversal order).
+   *
+   * The fix: after setting .value, check if it actually worked. If not, queue
+   * a retry callback. These callbacks are executed at the end of renderNode()
+   * after all child elements have been created.
+   */
+  readonly _pendingValueRetries: Array<() => void>;
+  abstract parseHTML(content: string, params?: ParserParams): Document | DocumentFragment;
+  abstract serializeHTML(root: DocumentFragment | Node): string;
+  abstract createElement(tag: string, owner?: Document | null): Element;
+  abstract createComment(content: string, owner?: Document | null): Node;
+  abstract textContent(node: Node, tag: string): void;
+  /** Hides an element without touching its application-owned styles. */
+  cloakElement(elem: Element): void;
+  /** Reveals a cloaked element by removing only Mancha's private marker. */
+  uncloakElement(elem: Element): void;
+  /**
+   * Sets the debug level for the current instance.
+   *
+   * @param flag - Boolean for backwards compat (true -> 'lifecycle') or a DebugLevel.
+   * @returns The current instance of the class.
+   */
+  debug(flag: boolean | DebugLevel): this;
+  /**
+   * Returns whether debugging is enabled (any level except 'off').
+   */
+  get debugging(): boolean;
+  /**
+   * Checks if the current debug level is at least the specified level.
+   */
+  private shouldLog;
+  /**
+   * Clears accumulated performance data. Called automatically at the start of `mount()`.
+   *
+   * Use this to reset performance tracking before measuring a specific user flow.
+   * After clearing, only effects and lifecycle events from subsequent operations
+   * will be included in the next `getPerformanceReport()` call.
+   *
+   * @example
+   * ```js
+   * // Setup phase
+   * $.debug('lifecycle');
+   * await $.mount(document.body);
+   *
+   * // Clear to start fresh measurement
+   * $.clearPerformanceReport();
+   *
+   * // Perform user flow to measure
+   * $.items = generateLargeList();
+   *
+   * // Get report for just this flow
+   * const report = $.getPerformanceReport();
+   * ```
+   */
+  clearPerformanceReport(): void;
+  /**
+   * Generates a DOM path for an element (e.g., "html>body>div>ul>li:nth-child(2)").
+   */
+  private getNodePath;
+  /**
+   * Builds an effect identifier from metadata.
+   */
+  buildObserverId(meta?: EffectMeta): string;
+  /**
+   * Records an effect execution for performance tracking.
+   */
+  recordObserverExecution(meta: EffectMeta | undefined, duration: number): void;
+  /**
+   * Returns a structured performance report.
+   */
+  getPerformanceReport(): PerformanceReport;
+  /**
+   * Override effect() to add performance tracking.
+   * Wraps the observer so re-executions via notify() are also tracked.
+   */
+  effect<T>(observer: () => T, meta?: EffectMeta): T;
+  /**
+   * Fetches the remote file at the specified path and returns its content as a string.
+   * @param fpath - The path of the remote file to fetch.
+   * @param params - Optional parameters for the fetch operation.
+   * @returns A promise that resolves to the content of the remote file as a string.
+   */
+  fetchRemote(fpath: string, params?: RenderParams): Promise<string>;
+  /**
+   * Fetches a local path and returns its content as a string.
+   *
+   * @param fpath - The file path of the resource.
+   * @param params - Optional render parameters.
+   * @returns A promise that resolves to the fetched resource as a string.
+   */
+  fetchLocal(fpath: string, params?: RenderParams): Promise<string>;
+  /**
+   * Preprocesses a string content with optional rendering and parsing parameters.
+   *
+   * @param content - The string content to preprocess.
+   * @param params - Optional rendering and parsing parameters.
+   * @returns A promise that resolves to a DocumentFragment representing the preprocessed content.
+   */
+  preprocessString(content: string, params?: RenderParams & ParserParams): Promise<Document | DocumentFragment>;
+  /**
+   * Preprocesses a remote file by fetching its content and applying preprocessing steps.
+   * @param fpath - The path to the remote file.
+   * @param params - Optional parameters for rendering and parsing.
+   * @returns A Promise that resolves to a DocumentFragment representing the preprocessed content.
+   */
+  preprocessRemote(fpath: string, params?: RenderParams & ParserParams): Promise<Document | DocumentFragment>;
+  /**
+   * Preprocesses a local file by fetching its content and applying preprocessing steps.
+   * @param fpath - The path to the local file.
+   * @param params - Optional parameters for rendering and parsing.
+   * @returns A promise that resolves to the preprocessed document fragment.
+   */
+  preprocessLocal(fpath: string, params?: RenderParams & ParserParams): Promise<Document | DocumentFragment>;
+  /**
+   * Creates a subrenderer from the current renderer instance.
+   * @returns A new instance of the renderer with the same state as the original.
+   */
+  subrenderer(): IRenderer;
+  /**
+   * Logs the provided arguments if verbose debugging is enabled.
+   * @param args - The arguments to be logged.
+   */
+  log(...args: unknown[]): void;
+  /**
+   * Preprocesses a node by applying all the registered preprocessing plugins.
+   *
+   * @template T - The type of the input node.
+   * @param {T} root - The root node to preprocess.
+   * @param {RenderParams} [params] - Optional parameters for preprocessing.
+   * @returns {Promise<T>} - A promise that resolves to the preprocessed node.
+   */
+  preprocessNode<T extends Document | DocumentFragment | Node>(root: T, params?: RenderParams): Promise<T>;
+  /**
+   * Renders the node and applies all the registered rendering plugins.
+   *
+   * @template T - The type of the root node (Document, DocumentFragment, or Node).
+   * @param {T} root - The root node to render.
+   * @param {RenderParams} [params] - Optional parameters for rendering.
+   * @returns {Promise<T>} - A promise that resolves to the fully rendered root node.
+   */
+  renderNode<T extends Document | DocumentFragment | Node>(root: T, params?: RenderParams): Promise<T>;
+  /**
+   * Mounts the Mancha application to a root element in the DOM.
+   *
+   * @param root - The root element to mount the application to.
+   * @param params - Optional parameters for rendering the application.
+   * @returns A promise that resolves when the mounting process is complete.
+   */
+  mount(root: Document | DocumentFragment | Node, params?: RenderParams): Promise<void>;
+}
+//#endregion
+//#region src/interfaces.d.ts
+interface ParserParams {
+  /** Whether the file parsed is a root document, or a document fragment. */
+  rootDocument?: boolean;
+  /** Encoding to use when processing local files. */
+  encoding?: "ascii" | "utf8";
+}
+/** The RendererParams interface defines the parameters that can be passed to the renderer. */
+interface RenderParams {
+  /** The current directory of the file being rendered. */
+  dirpath?: string;
+  /** Maximum level of recursion allowed when resolving includes. */
+  maxdepth?: number;
+  /** Cache policy used when resolving remote paths. */
+  cache?: RequestCache | null;
+  /** Whether the current node is the root used in Mancha.moun(...). */
+  rootNode?: Node;
+}
+type RendererPlugin = (this: IRenderer, node: ChildNode, params?: RenderParams) => void | Promise<void>;
+/** Debug level for controlling performance tracking and logging verbosity. */
+type DebugLevel = "off" | "lifecycle" | "effects" | "verbose";
+/** Metadata for identifying effects in performance tracking. */
+type EffectMeta = {
+  /** The directive that created this effect (e.g., 'class', 'bind', 'for'). */
+  directive: string;
+  /** The DOM element associated with this effect, if any. */
+  element?: Element;
+  /** The expression being evaluated by this effect. */
+  expression?: string;
+  /** Direct identifier for effects without a DOM element (e.g., computed property key). */
+  id?: string;
+};
+/** Statistics for a tracked effect. */
+type EffectStats = {
+  /** Effect identifier (e.g., "bind:my-input:user.name"). */
+  id: string;
+  /** Number of times this effect has executed. */
+  executionCount: number;
+  /** Total execution time in milliseconds. */
+  totalTime: number;
+  /** Average execution time per invocation in milliseconds. */
+  avgTime: number;
+};
+/** Structured performance report returned by getPerformanceReport(). */
+type PerformanceReport = {
+  /** Timing data for lifecycle methods. */
+  lifecycle: {
+    mountTime?: number;
+    preprocessTime?: number;
+    renderTime?: number;
+  };
+  /** Effect execution statistics. */
+  effects: {
+    /** Total number of unique effects tracked. */
+    total: number;
+    /** Aggregate stats grouped by directive type. */
+    byDirective: Record<string, {
+      count: number;
+      totalTime: number;
+    }>;
+    /** Top 10 slowest effects by total time. */
+    slowest: EffectStats[];
+  };
+  /** Observer registration statistics. */
+  observers: {
+    /** Number of keys with registered observers. */
+    totalKeys: number;
+    /** Total number of observer registrations. */
+    totalObservers: number;
+    /** Observer count per key. */
+    byKey: Record<string, number>;
+  };
+};
+//#endregion
 //#region src/css_gen_basic.d.ts
 declare function rules(): SafeStyleSheet;
 //#endregion
@@ -15,7 +465,6 @@ declare function rules(): SafeStyleSheet;
 declare function rules$1(): SafeStyleSheet;
 //#endregion
 //#region src/css_gen_utils.d.ts
-
 declare function rules$2(): string;
 //#endregion
 //#region src/browser.d.ts