Runtime Enhancement Contract

@skirbi/bolbe — Runtime Enhancement Contract

Purpose

Ensure components that require runtime behavior (e.g. fetch, interaction) can still function correctly after being processed by bolbe.

Core Principle

Artifact build and runtime enhancement are separate concerns.

• Artifact must always be built during connectedCallback()
• Runtime enhancement must be optional and re-triggerable in the browser

Component Contract

1. Static flag

Components that require runtime behavior must declare:

static runtimeEnhance = true;

Default:

static runtimeEnhance = false;

2. Artifact build (required)

connectedCallback() must always build the artifact:

connectedCallback() {
  this.buildArtifact();

  if (this.constructor.runtimeEnhance === true) {
    this.setAttribute('runtime-enhance', '');
  }

  if (this.shouldEnhance()) {
    this.enhanceRuntime();
  }
}

3. Runtime enhancement method (required if runtimeEnhance = true)

Components must implement:

enhanceRuntime()

Rules:

• Must be idempotent
• Must not rebuild the artifact
• Must safely run multiple times
• Must handle initial enhancement (e.g. initial fetch)

Example:

enhanceRuntime() {
  if (this.hasAttribute('data-runtime-enhanced')) return;
  this.setAttribute('data-runtime-enhanced', '');

  // attach listeners, fetch data, etc.
}

4. Enhancement gating

Enhancement must respect build context:

shouldEnhance() {
  return window.__SKIRBI_BUILD__ !== true;
}

bolbe Behavior

During build:

• window.__SKIRBI_BUILD__ = true
• connectedCallback() runs
• enhanceRuntime() is not executed
• Components with runtimeEnhance = true must leave:

<semtic-select runtime-enhance>

Browser Runtime Bootstrap

After page load, runtime enhancement must be triggered:

document.addEventListener('DOMContentLoaded', () => {
  document.querySelectorAll('[runtime-enhance]').forEach((el) => {
    el.enhanceRuntime?.();
  });
});

Prohibited Pattern

Do not manually call:

connectedCallback()

Reason:

• Breaks lifecycle semantics
• Causes double execution ambiguity
• Makes behavior unpredictable

Allowed Behavior Differences

After bolbe:

• Artifact is complete
• Runtime behavior is pending

After browser load:

• enhanceRuntime() upgrades the artifact

Summary

Components build the artifact in connectedCallback().

Components with runtime behavior:

• mark themselves with runtime-enhance
• expose enhanceRuntime()

The browser completes enhancement after load.

One-line Mental Model

bolbe builds it, the browser finishes it.