@adaas/are-html 0.0.20 → 0.0.22

package/examples/signal-routing/src/components/SettingsPage.component.ts

@@ -30,6 +30,33 @@ export class SettingsPage extends Are {
                     </label>
                 </div>
 
+                <div class="settings-group">
+                    <h2>Directive demo · <code>$show</code> vs <code>$if</code></h2>
+                    <p class="hint">
+                        Type something into both boxes below, then toggle <strong>Compact layout</strong>
+                        twice. Both panels react to the same <code>compact</code> store flag, but:
+                    </p>
+
+                    <div class="demo-panel demo-show" $show="!compact">
+                        <span class="demo-tag">$show</span>
+                        <p>
+                            Toggled with <code>$show</code> — I stay <strong>mounted</strong> and only my
+                            inline <code>display</code> flips. Your text below <strong>survives</strong>
+                            the toggle because the DOM node is never destroyed.
+                        </p>
+                        <input type="text" placeholder="Scratch text (survives toggle)…" />
+                    </div>
+
+                    <div class="demo-panel demo-if" $if="!compact">
+                        <span class="demo-tag">$if</span>
+                        <p>
+                            Toggled with <code>$if</code> — I am <strong>unmounted</strong> and rebuilt
+                            each time I reappear. Your text below is <strong>wiped</strong> on every toggle.
+                        </p>
+                        <input type="text" placeholder="Scratch text (lost on toggle)…" />
+                    </div>
+                </div>
+
                 <div class="settings-group">
                     <h2>Display name</h2>
                     <div class="input-row">
@@ -75,6 +102,18 @@ export class SettingsPage extends Are {
             .preview strong { color: #a78bfa; }
             .hint { font-size: 13px; color: #71717a; line-height: 1.7; }
             .hint code { background: #27272a; padding: 1px 6px; border-radius: 4px; color: #a78bfa; font-size: 12px; }
+            .settings-group h2 code { background: #27272a; padding: 1px 6px; border-radius: 4px; color: #a78bfa; font-size: 12px; font-weight: 600; }
+            .demo-panel { position: relative; background: #1c1c1f; border: 1px solid #27272a; border-radius: 10px; padding: 18px 18px 18px 20px; margin-top: 14px; }
+            .demo-panel p { font-size: 13px; color: #a1a1aa; line-height: 1.7; margin: 0 0 12px; }
+            .demo-panel p code { background: #27272a; padding: 1px 5px; border-radius: 3px; color: #a78bfa; font-size: 12px; }
+            .demo-panel strong { color: #e4e4e7; }
+            .demo-panel input[type="text"] { background: #131316; border: 1px solid #3f3f46; border-radius: 8px; color: #f4f4f5; padding: 8px 14px; font-size: 13px; outline: none; width: 100%; box-sizing: border-box; }
+            .demo-panel input[type="text"]:focus { border-color: #a78bfa; }
+            .demo-tag { display: inline-block; font-family: monospace; font-size: 11px; font-weight: 700; padding: 2px 8px; border-radius: 6px; margin-bottom: 10px; }
+            .demo-show { border-left: 3px solid #34d399; }
+            .demo-show .demo-tag { background: rgba(52, 211, 153, 0.12); color: #34d399; }
+            .demo-if { border-left: 3px solid #f59e0b; }
+            .demo-if .demo-tag { background: rgba(245, 158, 11, 0.12); color: #f59e0b; }
         `);
     }
 

package/examples/signal-routing/src/concept.ts

@@ -14,6 +14,7 @@ import {
     AreHTMLEngineContext,
     AreDirectiveIf,
     AreDirectiveFor,
+    AreDirectiveShow,
     AreRouteWatcher,
 } from "src";
 
@@ -64,6 +65,7 @@ import { AreRoute as AreRouteSignal } from "src/signals/AreRoute.signal";
                 // ── Directives ───────────────────────────────────────────
                 AreDirectiveIf,
                 AreDirectiveFor,
+                AreDirectiveShow,
                 // ── Engine ───────────────────────────────────────────────
                 A_SignalBus,
                 AreRoot,

package/jest.config.ts

@@ -17,6 +17,7 @@ const config: Config.InitialOptions = {
         "@adaas/are-html/instructions/(.*)": "<rootDir>/src/instructions/$1",
         "@adaas/are-html/watchers/(.*)":     "<rootDir>/src/watchers/$1",
         "@adaas/are-html/signals/(.*)":      "<rootDir>/src/signals/$1",
+        "@adaas/are-html/helpers/(.*)":      "<rootDir>/src/helpers/$1",
         // Custom lib exports
         "@adaas/are-html/style/(.*)":        "<rootDir>/src/lib/AreStyle/$1",
         "@adaas/are-html/directive/(.*)":    "<rootDir>/src/lib/AreDirective/$1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/are-html",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "A-Concept Rendering Engine (ARE) is a powerful rendering engine designed to work seamlessly with the A-Concept framework. This library provides an HTML engine implementation of ARE, enabling developers to create dynamic and interactive user interfaces for web applications using standard HTML syntax.",
   "keywords": [
     "a-concept",
@@ -73,6 +73,7 @@
     "example:signal-routing": "nodemon ./examples/signal-routing/concept.ts",
     "example:component-styles": "nodemon ./examples/component-styles/concept.ts",
     "example:auxta": "nodemon ./examples/auxta/concept.ts",
+    "example:for-perf": "nodemon ./examples/for-perf/concept.ts",
     "test:test": "nodemon ./src/test/app.ts",
     "release": " npm run build && git add . && git commit -m \"new version created :: $(cat package.json | grep version | head -1  | awk -F: '{ print $2 }'  | sed 's/[\",]//g')\" && npm version patch && npm publish --access public",
     "preversion": "echo test",
@@ -82,16 +83,16 @@
     "build": "tsup --config tsup.config.ts"
   },
   "peerDependencies": {
-    "@adaas/a-concept": "^0.3.27",
-    "@adaas/a-frame": "^0.1.14",
-    "@adaas/a-utils": "^0.3.32",
-    "@adaas/are": "^0.0.20"
+    "@adaas/a-concept": "^0.3.29",
+    "@adaas/a-frame": "^0.1.17",
+    "@adaas/a-utils": "^0.3.34",
+    "@adaas/are": "^0.0.23"
   },
   "devDependencies": {
-    "@adaas/a-concept": "^0.3.27",
-    "@adaas/a-frame": "^0.1.14",
-    "@adaas/a-utils": "^0.3.32",
-    "@adaas/are": "^0.0.20",
+    "@adaas/a-concept": "^0.3.29",
+    "@adaas/a-frame": "^0.1.17",
+    "@adaas/a-utils": "^0.3.34",
+    "@adaas/are": "^0.0.23",
     "@types/chai": "^4.3.14",
     "@types/jest": "^29.5.12",
     "@types/mocha": "^10.0.6",

package/src/directives/AreDirectiveFor.directive.ts

@@ -7,6 +7,7 @@ import { AddCommentInstruction } from "@adaas/are-html/instructions/AddComment.i
 import { AreHTMLNode } from "@adaas/are-html/node";
 import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
 import { A_Frame } from "@adaas/a-frame/core";
+import { AreSchedulerHelper } from "@adaas/are-html/helpers/AreScheduler.helper";
 
 
 type AreForExpression = {
@@ -17,6 +18,12 @@ type AreForExpression = {
     trackExpr: string | undefined;
 };
 
+/**
+ * Per-`$for` reentrancy state used to serialize chunked (async) renders.
+ * Keyed by the directive attribute instance (one per `$for` in the template).
+ */
+type AreForRenderState = { running: boolean; pending: boolean };
+
 
 @A_Frame.Define({
     namespace: 'a-are-html',
@@ -25,6 +32,32 @@ type AreForExpression = {
 @AreDirective.Priority(1)
 export class AreDirectiveFor extends AreDirective {
 
+    /**
+     * Lists whose number of NEW item nodes is at or below this threshold render
+     * fully synchronously — byte-for-byte the previous behavior. Typical UIs
+     * (menus, small tables) are therefore completely unaffected; only genuinely
+     * large lists pay the (tiny) scheduling cost to keep the main thread responsive.
+     */
+    private static readonly SYNC_THRESHOLD = 100;
+
+    /**
+     * Per-chunk time budget (ms). During a large-list render we mount item nodes
+     * until this much time has elapsed, then yield to the browser so it can paint
+     * and process input before the next chunk. ~16ms targets one animation frame.
+     */
+    private static readonly CHUNK_BUDGET_MS = 16;
+
+    /**
+     * Per-attribute serialization state. A new update() that arrives while a
+     * chunked render of the SAME `$for` is still in flight does NOT start a second
+     * concurrent pass (which could interleave mutations on the shared children
+     * list); instead it marks `pending` and the in-flight run re-runs once more
+     * with the latest data when it finishes. This guarantees the children list is
+     * only ever mutated by one pass at a time and the final state always reflects
+     * the most recent store value.
+     */
+    private static readonly renderState = new WeakMap<object, AreForRenderState>();
+
 
     @AreDirective.Transform
     transform(
@@ -122,7 +155,40 @@ export class AreDirectiveFor extends AreDirective {
         @A_Inject(AreStore) store: AreStore,
         @A_Inject(AreScene) scene: AreScene,
         ...args: any[]
-    ): void {
+    ): void | Promise<void> {
+        /**
+         * Serialize chunked renders per `$for`. If a previous large-list render
+         * is still streaming item nodes across macrotasks, do NOT start a second
+         * concurrent pass — that would interleave two diffs over the same shared
+         * children list (and leave half-compiled item nodes that the next diff
+         * would wrongly "reuse"). Mark a pass as pending instead; the in-flight
+         * run re-diffs once more from the latest store value when it completes.
+         */
+        let state = AreDirectiveFor.renderState.get(attribute);
+        if (!state) {
+            state = { running: false, pending: false };
+            AreDirectiveFor.renderState.set(attribute, state);
+        }
+        if (state.running) {
+            state.pending = true;
+            return;
+        }
+
+        return this.performUpdate(attribute, store, scene, state);
+    }
+
+    /**
+     * Core of the `$for` update: re-diff the source array against the current
+     * children, reconcile reused/removed items, then mount the new ones (small
+     * lists synchronously, large lists time-sliced). Never called while another
+     * pass for the same `$for` is in flight (see `update`).
+     */
+    private performUpdate(
+        attribute: AreDirectiveAttribute,
+        store: AreStore,
+        scene: AreScene,
+        state: AreForRenderState,
+    ): void | Promise<void> {
         /**
          * Re-evaluate the source array.
          */
@@ -134,6 +200,25 @@ export class AreDirectiveFor extends AreDirective {
 
         attribute.value = newArray;
 
+        /**
+         * Is this `$for`'s subtree currently rendered into the DOM?
+         *
+         * A `$for` can update while its subtree is detached — e.g. it lives
+         * inside a `$if` whose condition is currently false (the documented
+         * `<div $if><x $for></div>` nesting). The directive still receives the
+         * store change and re-diffs, but it must NOT mount/unmount item nodes
+         * directly while detached: the `$for` anchor (and its ancestors) are
+         * not in the DOM, so the interpreter's mount-point walk would fall
+         * through to the nearest *mounted* ancestor (the `$if` comment in the
+         * grandparent) and HOIST the items out of their intended container.
+         * When the ancestor `$if` later activates, its mount cascade applies
+         * the already-compiled item instructions in the correct place.
+         *
+         * Detached === any ancestor scene is inactive (regular nodes default
+         * to an active scene; only structural directives deactivate one).
+         */
+        const attached = this.isAttached(owner);
+
         const computeKey = this.makeKeyFn(key, index, trackExpr);
 
         // ── 1. Index existing children by stable key ────────────────────────
@@ -148,9 +233,13 @@ export class AreDirectiveFor extends AreDirective {
             remaining.add(child);
         }
 
-        // ── 2. Walk desired list; reuse existing or spawn new ───────────────
-        const desired: AreHTMLNode[] = [];
-        const newOnes: AreHTMLNode[] = [];
+        // ── 2. Walk desired list; reuse existing or record items to create ──
+        // NOTE: new item nodes are NOT spawned here. Spawning (cloneWithScope +
+        // subtree init + scene activation) is the dominant cost of a large
+        // render, so it is deferred into the time-sliced loop below alongside
+        // transform/compile/mount. Existing (keyed) children are reconciled in
+        // place synchronously — that is cheap and keeps reused rows stable.
+        const toCreate: Array<{ item: any; idx: number }> = [];
 
         for (let i = 0; i < newArray.length; i++) {
             const item = newArray[i];
@@ -170,26 +259,110 @@ export class AreDirectiveFor extends AreDirective {
                     [key]: item,
                     [index || 'index']: i,
                 };
-                desired.push(existing);
             } else {
-                const itemNode = this.spawnItemNode(attribute.template!, owner, key, index, item, i);
-                desired.push(itemNode);
-                newOnes.push(itemNode);
+                toCreate.push({ item, idx: i });
             }
         }
 
         // ── 3. Unmount + detach removed children ─────────────────────────────
         for (const child of remaining) {
-            child.unmount();
+            // Only revert DOM if the subtree is live; a detached subtree's item
+            // nodes were never mounted (see `attached` rationale above), so
+            // unmounting them is a no-op at best and risks reverting stale state.
+            if (attached) child.unmount();
             owner.removeChild(child);
         }
 
-        // ── 4. Mount only the new ones (kept children stay where they are). ─
-        for (const child of newOnes) {
+        // ── 4. Create + mount the new item nodes. ───────────────────────────
+        // `spawnItemNode` appends to `owner.children` immediately, so iterating
+        // `toCreate` in source order preserves list order (reused children keep
+        // their positions, new rows are appended in order) — identical to the
+        // previous synchronous behavior.
+        const createItem = (desc: { item: any; idx: number }) => {
+            const child = this.spawnItemNode(attribute.template!, owner, key, index, desc.item, desc.idx);
             child.transform();
             child.compile();
-            child.mount();
+            // While detached, stop after compile: the item's instructions are
+            // planned and the ancestor `$if`'s mount cascade will apply them in
+            // the correct container once the condition becomes truthy. Mounting
+            // here would hoist the item to the nearest mounted ancestor.
+            if (attached) child.mount();
+        };
+
+        // Small lists → fully synchronous, identical to the previous behavior.
+        if (toCreate.length <= AreDirectiveFor.SYNC_THRESHOLD) {
+            for (const desc of toCreate) createItem(desc);
+            return this.finishUpdate(attribute, store, scene, state);
+        }
+
+        // Large lists → time-sliced render. Create item nodes until the frame
+        // budget elapses, then yield to the browser (zero-delay macrotask) so
+        // it can paint and stay responsive instead of blocking for the whole
+        // batch. The `state.running` flag (see `update`) prevents any other
+        // update() for this `$for` from interleaving while we stream.
+        state.running = true;
+        let cursor = 0;
+
+        const processChunk = (): void | Promise<void> => {
+            try {
+                const start = AreSchedulerHelper.now();
+                while (cursor < toCreate.length) {
+                    createItem(toCreate[cursor]);
+                    cursor++;
+                    if (AreSchedulerHelper.now() - start >= AreDirectiveFor.CHUNK_BUDGET_MS) break;
+                }
+            } catch (error) {
+                // Never leave the `$for` wedged in the running state on failure,
+                // or every future update would be silently deferred forever.
+                state.running = false;
+                state.pending = false;
+                throw error;
+            }
+
+            if (cursor < toCreate.length) {
+                return new Promise<void>(resolve => {
+                    AreSchedulerHelper.scheduleMacrotask(() => resolve(processChunk()));
+                });
+            }
+
+            return this.finishUpdate(attribute, store, scene, state);
+        };
+
+        return processChunk();
+    }
+
+    /**
+     * Completes an update pass. If another update() arrived while a chunked
+     * render was streaming, run exactly one more pass now from the latest store
+     * value so the final DOM always reflects the most recent data.
+     */
+    private finishUpdate(
+        attribute: AreDirectiveAttribute,
+        store: AreStore,
+        scene: AreScene,
+        state: AreForRenderState,
+    ): void | Promise<void> {
+        state.running = false;
+        if (state.pending) {
+            state.pending = false;
+            return this.performUpdate(attribute, store, scene, state);
+        }
+    }
+
+
+    /**
+     * Walks the node's ancestor chain (inclusive) and reports whether the
+     * whole path is currently active — i.e. the subtree is actually rendered
+     * into the DOM. A single inactive ancestor scene (e.g. a `$if` whose
+     * condition is false) means the subtree is detached.
+     */
+    private isAttached(node: AreHTMLNode): boolean {
+        let current: AreHTMLNode | undefined = node;
+        while (current) {
+            if (current.scene?.isInactive) return false;
+            current = current.parent as AreHTMLNode | undefined;
         }
+        return true;
     }
 
 

package/src/directives/AreDirectiveShow.directive.ts

@@ -0,0 +1,127 @@
+import { A_Caller, A_Inject } from "@adaas/a-concept";
+import { A_Logger } from "@adaas/a-utils/a-logger";
+import { AreDirectiveAttribute } from "@adaas/are-html/attributes/AreDirective.attribute";
+import { AreScene, AreStore, AreSyntax } from "@adaas/are";
+import { AreDirective } from "@adaas/are-html/directive/AreDirective.component";
+import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
+import { HideElementInstruction } from "@adaas/are-html/instructions/HideElement.instruction";
+import { A_Frame } from "@adaas/a-frame/core";
+
+
+
+/**
+ * `$show` directive — conditionally toggles an element's visibility.
+ *
+ * Unlike `$if`, `$show` keeps the element fully mounted at all times and only
+ * flips its inline `display` (Vue `v-show` semantics). The element's subtree,
+ * event listeners and scene state are preserved across toggles, which makes it
+ * far cheaper than `$if` for things that flip on/off frequently. Use `$if` when
+ * the hidden branch is expensive and rarely shown; use `$show` when it toggles
+ * often.
+ *
+ * ⚠️ Known limitations:
+ *  - Do NOT combine `$show` with `$if`/`$for` on the SAME element — they share
+ *    an owner node and would fight over its host instruction. Wrap one in a
+ *    parent element instead.
+ *  - `$show` forces inline `display:none`, which beats stylesheet rules but will
+ *    NOT override the element's own inline `:style="display:..."` binding.
+ */
+@A_Frame.Define({
+    namespace: 'a-are-html',
+    description: 'Built-in $show directive. Toggles an element\'s visibility by flipping its inline display value based on a store expression, keeping the element mounted (subtree, listeners and scene state preserved) instead of unmounting it like $if.'
+})
+@AreDirective.Priority(3)
+export class AreDirectiveShow extends AreDirective {
+
+
+    @AreDirective.Transform
+    transform(
+        @A_Inject(A_Caller) attribute: AreDirectiveAttribute,
+        @A_Inject(A_Logger) logger: A_Logger,
+        ...args: any[]
+    ) {
+        // $show makes no structural change to the tree — the element stays in
+        // place and is only hidden/shown at interpret time. Nothing to do here
+        // beyond overriding the base directive's default transform warning.
+        logger.debug(`[Transform] directive $SHOW for <${attribute.owner.aseid.toString()}> (no structural change)`)
+    }
+
+
+    @AreDirective.Compile
+    compile(
+        @A_Inject(A_Caller) attribute: AreDirectiveAttribute,
+        @A_Inject(AreStore) store: AreStore,
+        @A_Inject(AreScene) scene: AreScene,
+        @A_Inject(AreSyntax) syntax: AreSyntax,
+
+        @A_Inject(AreDirectiveContext) directiveContext?: AreDirectiveContext,
+        ...args: any[]
+    ): void {
+        /**
+         * 1. Evaluate the expression to determine the initial visibility.
+         */
+        const visible = !!syntax.evaluate(attribute.content, store, {
+            ...(directiveContext?.scope || {}),
+        });
+
+        attribute.value = visible;
+
+        /**
+         * 2. Create a single reusable HideElement mutation parented to the
+         *    element's host instruction, and cache it on the attribute so
+         *    update() can plan/unplan the exact same instance.
+         */
+        const hide = new HideElementInstruction(scene.host!, {});
+        attribute.cache = hide;
+
+        /**
+         * 3. When initially hidden, plan the mutation so the first interpret
+         *    applies `display:none`. When visible, leave it unplanned.
+         */
+        if (!visible)
+            scene.plan(hide);
+    }
+
+
+    @AreDirective.Update
+    update(
+        @A_Inject(A_Caller) attribute: AreDirectiveAttribute,
+        @A_Inject(AreStore) store: AreStore,
+        @A_Inject(AreScene) scene: AreScene,
+        @A_Inject(AreSyntax) syntax: AreSyntax,
+
+        @A_Inject(AreDirectiveContext) directiveContext?: AreDirectiveContext,
+        ...args: any[]
+    ): void {
+        /**
+         * 1. Re-evaluate the expression, forwarding the directive context scope
+         *    (e.g. a `$for` loop variable) so `$show` reacts correctly inside
+         *    loops.
+         */
+        const previous = !!attribute.value;
+        const next = !!syntax.evaluate(attribute.content, store, {
+            ...(directiveContext?.scope || {}),
+        });
+
+        attribute.value = next;
+
+        // Skip when visibility has not changed — avoids redundant DOM writes.
+        if (previous === next) return;
+
+        const hide = attribute.cache as HideElementInstruction | undefined;
+
+        if (!hide) return;
+
+        /**
+         * 2. Toggle the cached mutation: unplan to reveal, plan to hide. Then
+         *    re-interpret the owner so the scene diff applies/reverts it.
+         */
+        if (next)
+            scene.unPlan(hide);
+        else
+            scene.plan(hide);
+
+        attribute.owner.interpret();
+    }
+
+}

package/src/engine/AreHTML.engine.ts

@@ -14,6 +14,7 @@ import { AreHTMLLifecycle } from "@adaas/are-html/lifecycle";
 import { AreHTMLTransformer } from "@adaas/are-html/transformer";
 import { AreHTMLCompiler } from "./AreHTML.compiler";
 import { isVoidElement } from "./AreHTML.constants";
+import { AreRootCache } from "../lib/AreRoot/AreRootCache.context";
 
 
 
@@ -81,7 +82,8 @@ export class AreHTMLEngine extends AreEngine {
     })
     async init(
         @A_Inject(A_Scope) scope: A_Scope,
-        @A_Inject(AreSignalsContext) signalContext?: AreSignalsContext
+        @A_Inject(AreSignalsContext) signalContext?: AreSignalsContext,
+        @A_Inject(AreRootCache) rootCache?: AreRootCache
     ) {
         this.package(scope, {
             context: new AreHTMLEngineContext({}),
@@ -97,6 +99,14 @@ export class AreHTMLEngine extends AreEngine {
             signalContext = new AreSignalsContext();
             scope.register(signalContext);
         }
+
+        // Default per-root subtree cache used by AreRoot for fast route-back
+        // re-injection. Apps may register their own (e.g. with a custom limit)
+        // before load to override this.
+        if (!rootCache) {
+            rootCache = new AreRootCache();
+            scope.register(rootCache);
+        }
     }
 
 

package/src/engine/AreHTML.interpreter.ts

@@ -15,6 +15,7 @@ import { AddElementInstruction } from "@adaas/are-html/instructions/AddElement.i
 import { AddListenerInstruction } from "@adaas/are-html/instructions/AddListener.instruction";
 import { AddTextInstruction } from "@adaas/are-html/instructions/AddText.instruction";
 import { AddStyleInstruction } from "@adaas/are-html/instructions/AddStyle.instruction";
+import { HideElementInstruction } from "@adaas/are-html/instructions/HideElement.instruction";
 import { AreDirectiveContext } from "@adaas/are-html/directive/AreDirective.context";
 import { AreHTMLNode } from "../lib/AreHTMLNode/AreHTMLNode";
 import { AreHTMLEngineContext } from "./AreHTML.context";
@@ -302,6 +303,55 @@ export class AreHTMLInterpreter extends AreInterpreter {
     }
 
 
+    // ─────────────────────────────────────────────────────────────────────────────
+    // ── HideElement — Apply / Revert ─────────────────────────────────────────────
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Drives the `$show` directive. Apply hides the element by forcing its inline
+    // `display:none` (which beats stylesheet rules and, unlike rewriting the whole
+    // `style` attribute, does NOT clobber other inline styles or `:style`
+    // bindings). The element stays mounted — its subtree, listeners and scene
+    // state are preserved — so toggling visibility is far cheaper than $if's
+    // mount/unmount cycle. Revert restores the element's previous inline display.
+    @A_Frame.Define({
+        description: 'Hide an element by setting inline display:none, caching its previous inline display value for restoration on revert.'
+    })
+    @AreInterpreter.Apply(AreHTMLInstructions.HideElement)
+    hideElement(
+        @A_Inject(A_Caller) mutation: HideElementInstruction,
+        @A_Inject(AreHTMLEngineContext) context: AreHTMLEngineContext,
+    ): void {
+        const element = context.getElementByInstruction(mutation.parent!);
+
+        if (!element || element.nodeType !== Node.ELEMENT_NODE) return;
+
+        const el = element as HTMLElement;
+
+        // Remember the element's own inline display so it can be restored exactly.
+        mutation.cache = el.style.display;
+        el.style.display = 'none';
+    }
+
+    @A_Frame.Define({
+        description: 'Restore an element hidden by a HideElement instruction back to its previous inline display value.'
+    })
+    @AreInterpreter.Revert(AreHTMLInstructions.HideElement)
+    showElement(
+        @A_Inject(A_Caller) mutation: HideElementInstruction,
+        @A_Inject(AreHTMLEngineContext) context: AreHTMLEngineContext,
+    ): void {
+        const element = context.getElementByInstruction(mutation.parent!);
+
+        if (!element || element.nodeType !== Node.ELEMENT_NODE) return;
+
+        const el = element as HTMLElement;
+
+        // Restore the cached inline display. An explicit payload display, when
+        // provided, takes precedence; otherwise fall back to the cached value
+        // (empty string clears the inline rule and reverts to the CSS default).
+        el.style.display = mutation.payload?.display ?? mutation.cache ?? '';
+    }
+
+
     // ─────────────────────────────────────────────────────────────────────────────
     // ── addEventListener — Apply / Revert ────────────────────────────────────────
     // ─────────────────────────────────────────────────────────────────────────────