PawaElement

The PawaElement is the core interface that extends the native HTMLElement. It acts as the bridge between your raw HTML and the PawaJS reactive runtime.

The Reactive Bridge

When PawaJS initializes or mounts a component, it upgrades standard DOM nodes into PawaElement instances. This adds internal tracking properties (prefixed with _) that handle state scoping, lifecycle events, and component-specific logic.

ts 

                 
// In TypeScript, any element retrieved via ref is a PawaElement
import { PawaElement } from 'pawajs';

const myRef = useRef<pawaelement>();
                </pawaelement>

Internal Properties

While most of these properties are internal, understanding them is essential for building PawaJS plugins, debugging complex interactions, or working with SSR.

_context

The local reactive scope available to the element. This contains all variables injected via useInsert or parent state.

_props

An object containing the getter functions for all props passed to this element if it's a component.

_avoidPawaRender

(Client-side) A boolean flag toggled by the pawa-avoid directive. When true, PawaJS skips processing this element's children.

_avoidPawaRender

(SSR-side) A boolean flag toggled by the s-pawa-avoid directive. When true, PawaJS skips processing this element's children on the server.

_asChild

Indicates if the as-child pattern is active, merging component behavior into the first native child. This is also handled during SSR.

_client

A boolean flag set by the only-client directive, indicating the element should only be rendered on the client-side.

_pawaAlready

A boolean flag indicating if the element has already been processed by PawaJS's SSR engine (i.e., has the p:c attribute).

_hydrateProps

An object containing props that need to be serialized and passed to the client for hydration.

_resumeAttr

A string representing the concatenated list of PawaJS attributes (directives and reactive props) that need to be resumed on the client. This forms the value of the p:c attribute.

_error

An array of error objects encountered during server-side processing, used for debugging and error reporting.

_lazy

A boolean flag indicating if the element is a lazy-loaded component.

Lifecycle & Methods

The PawaElement interface exposes methods to manually trigger lifecycles or perform safe evaluations within the element's specific context.

remove(callback?: Function): Promise<any>

PawaJS's smart removal method. It automatically checks for is-exit animations, runs unmount hooks, and terminates reactive effects before pulling the element from the DOM.

safeEval(context, expression, directive, resolve?)

Evaluates a string expression within the element's context. It includes built-in error reporting to the PawaDev tools and ensures the evaluation doesn't crash the runtime.

createError({message, stack}): void

Records an error encountered during the element's processing, typically used internally for SSR error reporting.

terminateEffects()

Manually destroys all reactive observers (effects) tied specifically to this element. Useful for manual DOM management.

setError(): void

Sets the ssr-error attribute on the element if errors were recorded, making them visible for client-side debugging.

Accessing the Instance

You typically access the PawaElement instance using a ref or within a Plugin.

js 

                 
const MyComponent = () => {
    const containerRef = useRef();

    runEffect(() => {
        // containerRef.value is now a PawaElement
        console.log('Scoped Context:', containerRef.value._context);
        
        // You can manually trigger mount functions if needed
        containerRef.value.mount();
    }, null);

    return html`<div ref="containerRef">...</div>`;
};

Continuity Rendering Model (CRM) Markers

PawaJS uses special attributes, prefixed with c- and a main p:c attribute, to mark elements for client-side hydration (resumption) after Server-Side Rendering (SSR). These markers allow the client-side runtime to efficiently "pick up" where the server left off, attaching reactivity without re-rendering the entire DOM.

p:c Attribute
The primary marker for resumable elements.

The p:c attribute is added to elements that have PawaJS directives or reactive content. Its value is a semicolon-separated list of all PawaJS-specific attributes present on the element, indicating which parts need client-side processing.

html 

                 
<div p:c="if;c-t" if="isActive.value">
    <!-- Content --> @{message.value}
</div>
c- Prefixed Attributes
Specific markers for directives and state.

These attributes (e.g., c-if-, c-for-, c-$-, c-c-) are generated during SSR to provide context for specific directives, state, or components. They contain serialized data or IDs that help the client-side resumer re-establish reactivity.

html 

                 
<div p:c="if;c-if-12345" c-if-12345="true">...</div>
<my-component p:c="c-c-my-component-67890" c-c-my-component-67890="serialized_data"></my-component>
Performance: _staticContext

The _staticContext property tracks variables that are known to be non-reactive. PawaJS uses this list to bypass reactive tracking entirely for certain nodes, reducing the number of active observers and keeping the runtime extremely fast.