hivecast-sdk/packages/browser-host/src/MatrixDSLHost.ts

// src/browser/MatrixDSLHost.ts
//
// FP-36: Declarative DSL Host — Zero-Ceremony Browser Bootstrap
//
// <matrix-dsl-host> creates its own NATS transport,
// MatrixRuntime, and context hierarchy from HTML attributes — so each
// browser app can compose Matrix actors and CQRS views with zero init.ts.
//
// Two modes:
//   LOCAL:      <matrix-dsl-host root="myapp">
//   FEDERATED:  <matrix-dsl-host root="myapp" backbone="ws://localhost:4223">
//
// Children receive contexts via explicit mounting (not AUTO-PULL,
// because this element is not a MatrixActorHtmlElement).

import { MatrixRuntime } from '@open-matrix/core';
import { BrowserDomStrategy } from '@open-matrix/core';
import { TopicRouter } from '@open-matrix/core';
import { RequestReply } from '@open-matrix/core';
import { createBrowserNatsTransport } from '@open-matrix/core/transport/createBrowserNatsTransport';
import {
  ACTOR_CALL_CLIENT,
  ACTOR_SERVICES,
  ActorCallClient,
  ActorServices,
  RUNTIME_ADDRESS_CONTEXT,
  SCOPED_INTENT_RESOLVER,
  ScopedIntentResolver,
  WELL_KNOWN_SERVICE_BINDINGS,
} from '@open-matrix/core';
import type { IMatrixContext } from '@open-matrix/core';
import type { IMatrixRuntime } from '@open-matrix/core';
import type { MatrixAuthorityContext } from '@open-matrix/core';
import type { RuntimeAddressContext } from '@open-matrix/core';
import type { ITransportAdapter } from '@open-matrix/core';
import type { MxEnvelope } from '@open-matrix/core';
import { SESSION_INFO_KEY, FEDERATION_PEER_KEY, type ISessionInfo } from '@open-matrix/core/services/SessionInfoService';
import {
  HOSTED_RUNTIME_TARGET_CHANGED_EVENT,
  hostedRuntimeTargetInfoEquals,
  resolveHostedRuntimeTargetInfo,
  type IHostedRuntimeTargetInfo,
} from './HostedRuntimeTarget.js';
import { resolveHostedRuntimeRecoveryPlan } from './HostedRuntimeRecovery.js';
import {
  createBrowserProfileSpan,
  logBrowserProfile,
  profileBrowserSpan,
} from './BrowserProfileTrace.js';
import {
  mountBrowserRuntimeControl,
  type BrowserRuntimeLifecycleState,
} from './BrowserRuntimeControlActor.js';
import {
  getOrCreateTabRealm,
  getOrCreateIdentityTabRoot,
  isValidRealm,
  getBrowserRouter,
  type FederationPeer,
  type BrowserRouterResult,
} from '@open-matrix/federation';
import type { RootContext, FederationMode } from '@open-matrix/core/core/context/RealmContext';
import { createRootContext } from '@open-matrix/core/core/context/RealmContext';
import {
  COMPONENT_RUNTIME_METADATA,
  type ComponentRegistrationSource,
  type ComponentSourceKind,
  type IComponentRuntimeMetadata,
} from '@open-matrix/core';
import type { ComponentArtifactFreshness } from '@open-matrix/core/core/composite/IComponentRuntimeMetadata';
import type {
  ServiceRegistryEntryKindV1,
  ServiceRegistryEntryV1,
} from '@open-matrix/contracts/service-registry';
import type {
  RuntimeInventoryEntryV1,
  RuntimePresenceEventV1,
  RuntimePresenceRecordV1,
} from '@open-matrix/contracts/runtime-presence';

interface IBootstrapTransportPlan {
  readonly protocolVersion?: 1;
  readonly kind?: 'nats';
  readonly wsMode?: 'same-origin-proxy';
  readonly wsPath?: string | null;
  readonly authMode?: 'jwt' | 'static' | 'anonymous' | 'login-required';
  readonly authEndpoint?: string | null;
  readonly busAuthMode?: 'bus-token' | 'none';
  readonly sessionMode?: 'session-cookie' | 'local-client' | 'anonymous' | 'device-login-required' | 'device-session';
}

interface IBootstrapValueSources {
  readonly root?: string;
  readonly authorityRoot?: string;
  readonly assetHostRoot?: string;
  readonly platformServiceRoot?: string;
  readonly sessionAuthorityRoot?: string;
  readonly selectedAuthorityRoot?: string;
  readonly runtimeInstanceRoot?: string;
  readonly platformRoot?: string;
  readonly addressRoot?: string;
  readonly routeKey?: string;
  readonly publicNamespace?: string;
  readonly workspaceRealm?: string;
  readonly browserWsPath?: string;
  readonly transportAuthMode?: string;
  readonly busToken?: string;
  readonly sessionIdentity?: string;
  readonly federation?: string;
}

interface IBootstrapFailureDiagnostics {
  readonly classification: string;
  readonly hint: string;
  readonly lines: string[];
}

interface INatsWsBootstrapPayload {
  readonly natsWsUrl?: string;
  readonly authenticated?: boolean;
  readonly busToken?: string;
  readonly authorityContext?: unknown;
}

function readBootstrapRecord(value: unknown, label: string): Record<string, unknown> {
  if (!value || typeof value !== 'object' || Array.isArray(value)) {
    throw new Error(`MatrixDSLHost: /api/bootstrap missing ${label}`);
  }
  return value as Record<string, unknown>;
}

function readBootstrapString(value: unknown, field: string): string {
  if (typeof value !== 'string') {
    throw new Error(`MatrixDSLHost: /api/bootstrap authorityContext.${field} must be a string`);
  }
  const trimmed = value.trim();
  if (!trimmed) {
    throw new Error(`MatrixDSLHost: /api/bootstrap authorityContext.${field} must not be empty`);
  }
  return trimmed;
}

function readBootstrapNullableString(value: unknown, field: string): string | null {
  if (value === null || value === undefined) {
    return null;
  }
  if (typeof value !== 'string') {
    throw new Error(`MatrixDSLHost: /api/bootstrap authorityContext.${field} must be a string or null`);
  }
  const trimmed = value.trim();
  return trimmed.length > 0 ? trimmed : null;
}

function readBootstrapBoolean(value: unknown, field: string): boolean {
  if (typeof value !== 'boolean') {
    throw new Error(`MatrixDSLHost: /api/bootstrap authorityContext.${field} must be a boolean`);
  }
  return value;
}

function readBootstrapStringArray(value: unknown, field: string): readonly string[] {
  if (!Array.isArray(value)) {
    throw new Error(`MatrixDSLHost: /api/bootstrap authorityContext.${field} must be a string array`);
  }
  return value.map((item) => {
    if (typeof item !== 'string') {
      throw new Error(`MatrixDSLHost: /api/bootstrap authorityContext.${field} must contain only strings`);
    }
    return item.trim();
  }).filter((item) => item.length > 0);
}

function parseBootstrapAuthorityContext(value: unknown): MatrixAuthorityContext {
  const record = readBootstrapRecord(value, 'authorityContext');
  return {
    assetHostRoot: readBootstrapString(record.assetHostRoot, 'assetHostRoot'),
    platformServiceRoot: readBootstrapString(record.platformServiceRoot, 'platformServiceRoot'),
    sessionAuthorityRoot: readBootstrapNullableString(record.sessionAuthorityRoot, 'sessionAuthorityRoot'),
    selectedAuthorityRoot: readBootstrapNullableString(record.selectedAuthorityRoot, 'selectedAuthorityRoot'),
    runtimeInstanceRoot: readBootstrapNullableString(record.runtimeInstanceRoot, 'runtimeInstanceRoot'),
    isAuthenticated: readBootstrapBoolean(record.isAuthenticated, 'isAuthenticated'),
    isPlatformAdmin: readBootstrapBoolean(record.isPlatformAdmin, 'isPlatformAdmin'),
    selectableAuthorityRoots: readBootstrapStringArray(record.selectableAuthorityRoots, 'selectableAuthorityRoots'),
  };
}

interface IRegistryQueryResponse {
  readonly entries?: unknown;
}

interface IRouteKeyWebappRoute {
  readonly appName: string;
  readonly routeKey: string;
}

interface IBrowserRuntimeInventoryEntry {
  mount: string;
  type: string;
  surface: string;
  runtimeId: string;
  claimKind: string;
  description?: string;
  hasChildren?: boolean;
}

interface IBrowserRuntimeRegistryState {
  readonly registryTarget: string;
  readonly namespaceRoot: string;
  readonly runtimeId: string;
  readonly runtimeRoot: string;
  readonly app: string;
  readonly contextMount: string;
  readonly hostBootstrapMode: boolean;
  readonly sessionMount: string;
  readonly relativeMount: string;
  readonly runtimeMount: string;
  readonly controlMount: string;
  readonly authorityRoot: string;
  readonly sessionAuthorityRoot: string;
  readonly selectedAuthorityRoot: string;
  readonly runtimeInstanceRoot: string;
  readonly runtimeHref: string;
  readonly registeredAt: number;
}

interface IRuntimeSummaryPayload {
  readonly authority?: {
    readonly addressRoot?: string | null;
  } | null;
  readonly attachedLeafRoots?: {
    readonly items?: Array<{
      readonly root?: string;
      readonly connectionKind?: string | null;
    }>;
  } | null;
}

interface IDevicesListResponse {
  readonly ok?: unknown;
  readonly devices?: unknown;
}

interface IDeviceInventoryRecord {
  readonly authorityRoot?: unknown;
  readonly status?: unknown;
  readonly updatedAt?: unknown;
  readonly lastHeartbeatAt?: unknown;
}

const HOSTED_SELECTED_LEAF_STORAGE_KEY = 'matrix-web.selected-leaf-root';
const HOSTED_RUNTIME_RECOVERY_NOTICE_ATTR = 'data-hosted-runtime-recovery';
const BROWSER_RUNTIME_ID_PREFIX = 'RUNTIME-BROWSER-';
const HOST_PROFILE_SCOPE = 'host';

type HostedRuntimeTargetSource = 'explicit' | 'auto' | 'none';
type HostedRuntimeTargetKind = 'leaf' | 'authority' | 'unknown';

interface IHostedRuntimeTarget {
  readonly root: string | null;
  readonly source: HostedRuntimeTargetSource;
  readonly kind: HostedRuntimeTargetKind;
  readonly requestedRoot: string | null;
  readonly unavailableReason: 'missing' | 'not-live' | 'unauthorized' | 'none';
}

interface IHostedRuntimeSummaryState {
  readonly authorityRoot: string | null;
  readonly liveLeafRoots: string[];
  readonly knownLeafRoots: string[];
}

const HOSTED_RUNTIME_TARGET_REFRESH_INTERVAL_MS = 3_000;

interface IHostRoutingPeer {
  readonly hasBackbone: boolean;
  readonly localRoot: string;
  readonly localRealm?: string;
  invoke<T>(
    target: string,
    opOrRequest: string | { op: string; payload?: unknown },
    payloadOrTimeout?: unknown,
    timeoutMs?: number,
  ): Promise<T>;
  route(topic: string, payload: unknown): Promise<void>;
}

interface IMatrixChildElementHooks {
  _receiveContext?: (ctx: IMatrixContext) => Promise<void>;
  mount?: (ctx: IMatrixContext) => Promise<void>;
  setContext?: (ctx: IMatrixContext) => void;
}

interface IMatrixRootContextReceiver {
  _receiveContext?: (ctx: { rootContext: RootContext; realmContext: RootContext }) => void;
}

interface IMatrixActorElementVersionSource {
  _actor?: {
    children?: {
      version?: number;
    };
  };
}

/**
 * Options for programmatic bootstrap via `host.bootstrap()`.
 */
export interface BootstrapOptions {
  /** Wrap the transport after creation but before runtime/children. */
  wrapTransport?: (transport: ITransportAdapter) => ITransportAdapter;
  /** Override bus root (alternative to setting attribute). */
  busRoot?: string;
  /** Override backbone URL. */
  backbone?: string;
  /** Override mount path. */
  mount?: string;
}

/**
 * <matrix-dsl-host> - Self-contained declarative browser bootstrap.
 *
 * Creates MatrixRuntime, FederationPeer, and context hierarchy from
 * HTML attributes. Children (MatrixActorHtmlElement instances) receive
 * derived contexts and can communicate immediately.
 *
 * @example Local-only (in-memory transport, no NATS)
 * ```html
 * <matrix-dsl-host root="myapp" mount="dashboard">
 *   <my-counter id="c1"></my-counter>
 *   <my-chart id="chart" tracks="c1"></my-chart>
 * </matrix-dsl-host>
 * ```
 *
 * @example Federated (NATS backbone for cross-root)
 * ```html
 * <matrix-dsl-host root="flowpad" backbone="ws://localhost:4223">
 *   <ralph-supervisor-view tracks="matrix-3/ralph" autoview>
 *   </ralph-supervisor-view>
 * </matrix-dsl-host>
 * ```
 *
 * @example Existing init.ts auto-init control
 * ```html
 * <matrix-dsl-host auto-init="false">
 *   <my-app></my-app>
 * </matrix-dsl-host>
 * <script>
 *   const host = document.querySelector('matrix-dsl-host');
 *   host.initialize(existingRuntime, existingContext);
 * </script>
 * ```
 */
export class MatrixDSLHost extends HTMLElement {
  /** Matrix context for this host's children */
  private _context: IMatrixContext | null = null;

  /** Runtime instance (created internally or injected) */
  private _runtime: IMatrixRuntime | null = null;

  /** FederationPeer (only in federated mode) */
  private _peer: FederationPeer | null = null;

  /** Wall-clock time the splash was first shown; used to enforce a minimum
   *  visible duration before fade-out so the brand frame is perceivable
   *  even when bootstrap is sub-100ms (warm cache). */
  private _splashShownAt: number | null = null;
  private _splashHideScheduled = false;

  /** Router-shaped service exposed to app code. */
  private _routingPeer: IHostRoutingPeer | null = null;

  /** Transport adapter used by the runtime */
  private _transport: ITransportAdapter | null = null;

  /** Initialization flag */
  private _initialized = false;

  /** Mutation observer for light DOM changes */
  private _observer: MutationObserver | null = null;

  /** Root context for federation metadata */
  private _rootContext: RootContext | null = null;

  /** $join subscription cleanup */
  private _joinUnsub: (() => void) | null = null;

  /** Transport wrapper callback (set via bootstrap() or public property) */
  private _wrapTransport: ((t: ITransportAdapter) => ITransportAdapter) | null = null;

  /** Bus token refresh timer (INV-ID-7: 4-min interval, token has 5-min TTL) */
  private _busTokenRefreshTimer: ReturnType<typeof setInterval> | null = null;

  /** Background runtime registry discovery retry timer after initial discovery timeouts. */
  private _daemonDiscoveryRetryTimer: ReturnType<typeof setTimeout> | null = null;

  /** Exponential backoff for background runtime registry rediscovery. */
  private _daemonDiscoveryRetryDelayMs = 1_000;

  /** Prevent overlapping runtime registry discovery loops. */
  private _daemonDiscoveryInFlight = false;

  /** Background refresh loop for hosted runtime liveness metadata. */
  private _hostedRuntimeTargetRefreshTimer: ReturnType<typeof setInterval> | null = null;

  /** Prevent overlapping hosted runtime summary polls. */
  private _hostedRuntimeTargetRefreshInFlight = false;

  /** Service Registry lease renewal timer for this browser runtime. */
  private _browserRuntimeRenewTimer: ReturnType<typeof setInterval> | null = null;

  /** Bound beforeunload handler for releasing this browser runtime claim. */
  private _browserRuntimeReleaseHandler: (() => void) | null = null;

  /** Current Service Registry claim state for this browser runtime. */
  private _browserRuntimeRegistryState: IBrowserRuntimeRegistryState | null = null;

  /** Component IDs currently claimed for this browser runtime in system.registry. */
  private _browserRuntimeClaimedComponentIds = new Set<string>();

  /** Current browser runtime id, used to refresh inventory after dynamic child changes. */
  private _runtimeRegistryId = '';

  /** Browser runtime control actor start time for stable runtime status. */
  private _runtimeControlStartedAt = '';

  /** Debounce timer for child-driven registry claim refreshes. */
  private _runtimeInventoryClaimRefreshTimer: ReturnType<typeof setTimeout> | null = null;

  /** Increments whenever cleanup invalidates async registration continuations. */
  private _lifecycleGeneration = 0;

  /** Last reported host child version for runtime inventory refreshes. */
  private _runtimeInventoryVersion = -1;

  /** URL param keys to read (when url-params attribute is present) */
  private static readonly URL_PARAM_MAP: Record<string, string> = {
    root: 'root',
    realm: 'root', // ?realm= maps to root attr
    backbone: 'backbone',
    backboneUrl: 'backbone',
    mount: 'mount',
    daemonRoot: 'daemon-root',
    daemonRealm: 'daemon-root',
    addressRoot: 'data-address-root',
  };

  /** Raw adapter before wrapping (for getWireTopicInfo etc.) */
  private _rawAdapter: ITransportAdapter | null = null;

  /** Identity state from bootstrap */
  private _principal: { principalId: string; displayName?: string; email?: string; tier?: string } | null = null;
  private _activeOrg: { orgId: string; displayName: string; role: string } | null = null;
  private _isAuthenticated = false;

  /** Promise that resolves when initialization is complete */
  readonly ready: Promise<void>;
  private _resolveReady!: () => void;

  private _bootstrapTransportPlan: IBootstrapTransportPlan | null = null;

  static get observedAttributes(): string[] {
    return ['mount', 'auto-init', 'root', 'realm', 'federation', 'backbone', 'identity-provider', 'client-id', 'auto-attach'];
  }

  constructor() {
    super();
    this.ready = new Promise(resolve => {
      this._resolveReady = resolve;
    });
  }

  private _deriveNatsWsTransportPlan(bootstrap: INatsWsBootstrapPayload): IBootstrapTransportPlan | null {
    const rawWsUrl = typeof bootstrap.natsWsUrl === 'string' ? bootstrap.natsWsUrl.trim() : '';
    if (!rawWsUrl) {
      return null;
    }

    let wsPath = '/nats-ws';
    try {
      const parsed = new URL(rawWsUrl, window.location.href);
      if (parsed.pathname && parsed.pathname !== '/') {
        wsPath = parsed.pathname;
      }
    } catch {
      const match = rawWsUrl.match(/^wss?:\/\/[^/]+(\/.*)$/i);
      if (match?.[1]) {
        wsPath = match[1];
      }
    }

    return {
      kind: 'nats',
      wsMode: 'same-origin-proxy',
      wsPath,
      busAuthMode: bootstrap.busToken ? 'bus-token' : 'none',
      sessionMode: bootstrap.authenticated ? 'session-cookie' : 'anonymous',
    };
  }

  // ═══════════════════════════════════════════════════════════════════════════
  // DOM Lifecycle
  // ═══════════════════════════════════════════════════════════════════════════

  connectedCallback(): void {
    const autoInit = this.getAttribute('auto-init');
    if (autoInit !== 'false') {
      this._bootstrapAsync();
    }
  }

  disconnectedCallback(): void {
    this._cleanup();
  }

  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void {
    if (oldValue === newValue) return;
    if (name === 'mount' && this._initialized) {
      this._cleanup();
      this._bootstrapAsync();
    }
  }

  // ═══════════════════════════════════════════════════════════════════════════
  // Public API
  // ═══════════════════════════════════════════════════════════════════════════

  /** The FederationPeer (null in local-only mode). */
  get peer(): FederationPeer | null {
    return this._peer;
  }

  /** The MatrixRuntime instance. */
  get runtime(): IMatrixRuntime | null {
    return this._runtime;
  }

  /** The host's Matrix context (children derive from this). */
  get context(): IMatrixContext | null {
    return this._context;
  }

  /** The root context for federation metadata. */
  get rootContext(): RootContext | null {
    return this._rootContext;
  }

  get realmContext(): RootContext | null {
    return this._rootContext;
  }

  /** The transport adapter (possibly wrapped). */
  get transport(): ITransportAdapter | null {
    return this._transport;
  }

  /** The raw (unwrapped) transport adapter (for getWireTopicInfo etc.). */
  get rawAdapter(): ITransportAdapter | null {
    return this._rawAdapter;
  }

  /** Whether backbone is connected (false in local-only or before bootstrap). */
  get hasBackbone(): boolean {
    return this._routingPeer?.hasBackbone ?? false;
  }

  /** Authenticated principal from bootstrap (null if anonymous). */
  get principal(): { principalId: string; displayName?: string; email?: string; tier?: string } | null {
    return this._principal;
  }

  /** Active org context (null if not in an org). */
  get activeOrg(): { orgId: string; displayName: string; role: string } | null {
    return this._activeOrg;
  }

  /** Subscription tier (from principal or 'anonymous'). */
  get tier(): string {
    return this._principal?.tier ?? 'anonymous';
  }

  /** Whether the session is authenticated. */
  get isAuthenticated(): boolean {
    return this._isAuthenticated;
  }

  /**
   * Set a transport wrapper BEFORE bootstrap.
   * The wrapper is applied after transport creation but before runtime/children.
   * This is how apps intercept all pub/sub (e.g., for logging panels).
   */
  set wrapTransport(fn: ((t: ITransportAdapter) => ITransportAdapter) | null) {
    this._wrapTransport = fn;
  }

  /**
   * Programmatic bootstrap with options.
   * Use when auto-init="false" and you need to configure before bootstrap.
   */
  async bootstrap(options?: BootstrapOptions): Promise<void> {
    if (this._initialized) {
      // eslint-disable-next-line no-console -- browser bootstrap, not an actor
      console.warn('[MatrixDSLHost] Already initialized');
      return;
    }

    // Apply option overrides to attributes.
    if (options?.busRoot) this.setAttribute('bus-root', options.busRoot);
    if (options?.backbone) this.setAttribute('backbone', options.backbone);
    if (options?.mount !== undefined) this.setAttribute('mount', options.mount);

    // Store transport wrapper (option overrides property setter)
    if (options?.wrapTransport) {
      this._wrapTransport = options.wrapTransport;
    }

    await this._bootstrapAsync();
  }

  /**
   * Initialize with an externally-created runtime.
   * Use this when auto-init="false" and you have an existing runtime.
   */
  async initialize(runtime: IMatrixRuntime, context?: IMatrixContext): Promise<void> {
    if (this._initialized) {
      // eslint-disable-next-line no-console -- browser bootstrap, not an actor
      console.warn('[MatrixDSLHost] Already initialized');
      return;
    }

    this._runtime = runtime;

    const mountPath = this.getAttribute('mount') ?? this.id ?? '';
    const rootContext = runtime.getRootContext?.();
    if (!rootContext && !context) {
      throw new Error('[MatrixDSLHost] Runtime has no getRootContext() and no context provided');
    }

    this._context = context ?? (mountPath
      ? rootContext!.derive(mountPath)
      : rootContext!);

    // Install $join responder and mount children
    this._installJoinResponder();
    await this._mountChildren();
    this._setupMutationObserver();
    this._parseRootAttributes();
    this._propagateRootToChildren();

    this._initialized = true;
    this._resolveReady();
    this._fireReadyEvent();
  }

  // ═══════════════════════════════════════════════════════════════════════════
  // Self-Bootstrap (FP-36 Phase 1)
  // ═══════════════════════════════════════════════════════════════════════════

  /**
   * Async self-bootstrap: creates runtime + transport from attributes.
   */
  private async _bootstrapAsync(): Promise<void> {
    const explicitBusRootAttr = this.getAttribute('bus-root');
    let hostBootstrapMode = this._isHostBootstrapMode();
    const routeKeyRoute = this._parseRouteKeyWebappRouteFromLocation();
    const requireDaemonBootstrap = this._shouldRequireDaemonBootstrap()
      || routeKeyRoute !== null;
    delete this.dataset.explicitAuthorityRoot;
    const hadExplicitDaemonTarget = this.hasAttribute('daemon-root')
      || this.hasAttribute('daemon-realm')
      || routeKeyRoute !== null;
    const initialUrlParams = this.hasAttribute('url-params')
      ? new URLSearchParams(window.location.search)
      : null;
    const hasExplicitDaemonTargetParam = initialUrlParams?.has('daemonRoot') || initialUrlParams?.has('daemonRealm') || false;
    const hostedAppName = this._deriveHostedAppName();
    const finishBootstrapProfile = createBrowserProfileSpan(HOST_PROFILE_SCOPE, 'bootstrapAsync', {
      hostedApp: hostedAppName ?? '',
      requireDaemonBootstrap,
      hasExplicitDaemonTarget: hadExplicitDaemonTarget || hasExplicitDaemonTargetParam,
    });

    try {
      this.dataset.status = 'initializing';
      this._manageLoadingElement('initializing');
      let discoveredNats = false;
      let bootstrapAuthorityRoot = '';
      let bootstrapPublicNamespace = '';
      let bootstrapRouteKey = '';
      let renderNamespaceSetupLocally = false;
      let loginRequiredBootstrap = false;

      // Phase A: Transport coordinate discovery.
      // Daemon-served apps must declare their path through /api/bootstrap.
      let usedBootstrap = false;
      try {
        const bootstrapEndpoint = this._bootstrapEndpointForRoute(routeKeyRoute, hostedAppName);
        const bootstrapResp = await profileBrowserSpan(
          HOST_PROFILE_SCOPE,
          'api.bootstrap',
          async () => fetch(bootstrapEndpoint, { credentials: 'same-origin' }),
          {
            hostedApp: hostedAppName ?? '',
            required: requireDaemonBootstrap,
          },
        );
        if (!bootstrapResp.ok) {
          if (requireDaemonBootstrap) {
            throw new Error(`Hosted app requires /api/bootstrap (HTTP ${bootstrapResp.status})`);
          }
        } else {
          const bootstrap = await profileBrowserSpan(
            HOST_PROFILE_SCOPE,
            'api.bootstrap.parse',
            async () => bootstrapResp.json() as Promise<{
              natsWsUrl?: string; root?: string; natsToken?: string; busToken?: string;
              authenticated?: boolean; principal?: { principalId: string; displayName?: string; email?: string; tier?: string };
              activeOrg?: { orgId: string; displayName: string; role: string };
              addressRoot?: string;
              authorityRoot?: string;
              assetHostRoot?: string;
              platformServiceRoot?: string;
              sessionAuthorityRoot?: string;
              selectedAuthorityRoot?: string;
              runtimeInstanceRoot?: string;
              authorityContext?: unknown;
              selectableAuthorityRoots?: string[];
              isPlatformAdmin?: boolean;
              routeKey?: string;
              publicNamespace?: string;
              spaceId?: string;
              platformRoot?: string;
              busRoot?: string;
              appName?: string;
              role?: string;
              workspaceRealm?: string;
              routeKind?: string;
              login?: { provider?: string; startUrl?: string };
              sources?: IBootstrapValueSources;
              transportPlan?: IBootstrapTransportPlan;
              topologyKind?: string;
              nodeRoles?: unknown;
              federation?: {
                attached?: unknown;
                hubUrl?: unknown;
                hubKind?: unknown;
              };
              shellAccessMode?: string;
              appLinkMode?: string;
            }>,
            {
              hostedApp: hostedAppName ?? '',
            },
          );
          const authorityContext = parseBootstrapAuthorityContext(bootstrap.authorityContext);
          // eslint-disable-next-line no-console -- browser bootstrap, not an actor
          console.info(`[MatrixDSLHost] /api/bootstrap → selectedAuthorityRoot="${authorityContext.selectedAuthorityRoot ?? ''}", runtimeInstanceRoot="${authorityContext.runtimeInstanceRoot ?? ''}", wsUrl="${bootstrap.natsWsUrl}", authenticated=${authorityContext.isAuthenticated}`);

          // Store identity state from bootstrap
          this._isAuthenticated = authorityContext.isAuthenticated;
          this.dataset.authenticated = String(this._isAuthenticated);
          if (bootstrap.principal) {
            this._principal = bootstrap.principal;
            this.dataset.principalId = bootstrap.principal.principalId;
            if (bootstrap.principal.displayName) {
              this.dataset.displayName = bootstrap.principal.displayName;
            }
          }
          if (bootstrap.activeOrg) {
            this._activeOrg = bootstrap.activeOrg;
          }
          const platformServiceRoot = authorityContext.platformServiceRoot;
          const assetHostRoot = authorityContext.assetHostRoot;
          const sessionAuthorityRoot = authorityContext.sessionAuthorityRoot ?? '';
          const selectedAuthorityRoot = authorityContext.selectedAuthorityRoot ?? '';
          const runtimeInstanceRoot = authorityContext.runtimeInstanceRoot ?? '';
          this._setOptionalDatasetValue('assetHostRoot', assetHostRoot);
          this._setOptionalDatasetValue('platformServiceRoot', platformServiceRoot);
          this._setOptionalDatasetValue('sessionAuthorityRoot', sessionAuthorityRoot);
          this._setOptionalDatasetValue('selectedAuthorityRoot', selectedAuthorityRoot);
          this._setOptionalDatasetValue('runtimeInstanceRoot', runtimeInstanceRoot);
          delete this.dataset.addressRoot;
          const selectableAuthorityRoots = authorityContext.selectableAuthorityRoots;
          this._setOptionalDatasetValue('selectableAuthorityRoots', selectableAuthorityRoots.join(','));
          this.dataset.isPlatformAdmin = authorityContext.isPlatformAdmin ? 'true' : 'false';
          if (authorityContext.isAuthenticated && sessionAuthorityRoot) {
            this.dataset.principalAuthorityRoot = sessionAuthorityRoot;
          } else {
            delete this.dataset.principalAuthorityRoot;
          }
          bootstrapAuthorityRoot = selectedAuthorityRoot;
          bootstrapPublicNamespace = (bootstrap.publicNamespace || '').trim();
          bootstrapRouteKey = (bootstrap.routeKey || routeKeyFromPublicNamespace(bootstrapPublicNamespace) || '').trim();
          const bootstrapSpaceId = (bootstrap.spaceId || '').trim();
          this._setOptionalDatasetValue('routeKey', bootstrapRouteKey);
          this._setOptionalDatasetValue('publicNamespace', bootstrapPublicNamespace);
          this._setOptionalDatasetValue('spaceId', bootstrapSpaceId);
          const bootstrapAppName = typeof bootstrap.appName === 'string'
            ? bootstrap.appName.trim()
            : '';
          if (bootstrapAppName) {
            this.setAttribute('app-name', bootstrapAppName);
          }
          const bootstrapAttributeAuthorityRoot = sessionAuthorityRoot || selectedAuthorityRoot;
          if (bootstrapAttributeAuthorityRoot) {
            this.setAttribute('authority-root', bootstrapAttributeAuthorityRoot);
          }
          const bootstrapPlatformRoot = platformServiceRoot;
          renderNamespaceSetupLocally = hostedAppName === 'web'
            && authorityContext.isAuthenticated
            && !bootstrapPublicNamespace
            && !bootstrapRouteKey
            && bootstrapAuthorityRoot === bootstrapPlatformRoot;
          if (renderNamespaceSetupLocally) {
            this.dataset.namespaceSetupMode = 'local';
          } else {
            delete this.dataset.namespaceSetupMode;
          }
          if (bootstrap.workspaceRealm) {
            this.dataset.workspaceRealm = bootstrap.workspaceRealm;
          }
          this._setOptionalDatasetValue('routeKind', typeof bootstrap.routeKind === 'string' ? bootstrap.routeKind : '');
          this._setOptionalDatasetValue('topologyKind', typeof bootstrap.topologyKind === 'string' ? bootstrap.topologyKind : '');
          const authorityCoordinatorActive = bootstrapNodeRoleActive(bootstrap.nodeRoles, 'authorityCoordinator');
          if (typeof authorityCoordinatorActive === 'boolean') {
            this.dataset.authorityCoordinatorActive = String(authorityCoordinatorActive);
          } else {
            delete this.dataset.authorityCoordinatorActive;
          }
          this._setOptionalDatasetValue('shellAccessMode', typeof bootstrap.shellAccessMode === 'string' ? bootstrap.shellAccessMode : '');
          this._setOptionalDatasetValue('appLinkMode', typeof bootstrap.appLinkMode === 'string' ? bootstrap.appLinkMode : '');
          if (bootstrap.federation && typeof bootstrap.federation === 'object') {
            this.dataset.federationAttached = bootstrap.federation.attached === true ? 'true' : 'false';
            this._setOptionalDatasetValue(
              'federationHubUrl',
              typeof bootstrap.federation.hubUrl === 'string' ? bootstrap.federation.hubUrl : '',
            );
            this._setOptionalDatasetValue(
              'federationHubKind',
              typeof bootstrap.federation.hubKind === 'string' ? bootstrap.federation.hubKind : '',
            );
          } else {
            delete this.dataset.federationAttached;
            delete this.dataset.federationHubUrl;
            delete this.dataset.federationHubKind;
          }
          this._setOptionalDatasetValue('loginProvider', bootstrap.login?.provider ?? '');
          this._setOptionalDatasetValue('loginStartUrl', bootstrap.login?.startUrl ?? '');
          const transportPlan = bootstrap.transportPlan ?? this._deriveNatsWsTransportPlan(bootstrap);
          this._bootstrapTransportPlan = transportPlan ?? null;
          loginRequiredBootstrap = transportPlan?.authMode === 'login-required';
          if (loginRequiredBootstrap) {
            this.dataset.status = 'login-required';
            this.dataset.daemonStatus = 'skipped';
          }
          usedBootstrap = true;
          const bootstrapRole = typeof bootstrap.role === 'string' ? bootstrap.role.trim().toLowerCase() : '';
          const isLocalClientSession = transportPlan?.sessionMode === 'local-client'
            || bootstrap.sources?.sessionIdentity === 'local-client';
          if (isLocalClientSession && !hostBootstrapMode) {
            hostBootstrapMode = true;
            this.setAttribute('bootstrap-mode', 'host');
          }
          if (hostBootstrapMode && bootstrapRole === 'platform' && hostedAppName && hostedAppName !== 'web') {
            hostBootstrapMode = false;
            this.setAttribute('bootstrap-mode', 'hosted');
          }
          // NATS subject scope = busRoot (Host's transport.root).
          // Ambiguous bootstrap fields are intentionally not read here.
          const busRoot = (bootstrap.busRoot || platformServiceRoot).trim();
          if (busRoot) {
            this.setAttribute('bus-root', busRoot);
            if (renderNamespaceSetupLocally) {
              this.removeAttribute('daemon-root');
              this.removeAttribute('daemon-realm');
            } else {
              this.setAttribute('daemon-realm', busRoot);
            }
            if (hostBootstrapMode) {
              this._ensureHostRuntimeMount(busRoot, hostedAppName);
            }
            if (!renderNamespaceSetupLocally && !hadExplicitDaemonTarget && !hasExplicitDaemonTargetParam) {
              this.setAttribute('daemon-root', busRoot);
            }
            this.dataset.platformRoot = platformServiceRoot || busRoot;
          }
          discoveredNats = true;
          this.setAttribute('transport', 'nats');
          if (transportPlan) {
            const wsPath = transportPlan.wsPath ?? '/nats-ws';
            const localOnlyAnonymousSession = transportPlan.authMode === 'anonymous'
              && transportPlan.sessionMode === 'anonymous';
            if (transportPlan.authMode === 'login-required' || localOnlyAnonymousSession) {
              this.removeAttribute('nats-ws-url');
              this.removeAttribute('backbone');
              delete this.dataset.natsWsUrl;
              delete this.dataset.natsAuthEndpoint;
              delete this.dataset.busToken;
            } else {
              const sameOriginWsUrl = `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}${wsPath}`;
              this.setAttribute('nats-ws-url', sameOriginWsUrl);
              this.setAttribute('backbone', sameOriginWsUrl);
            }
            if (transportPlan.authMode) {
              this.dataset.natsAuthMode = transportPlan.authMode;
            }
            if (transportPlan.authEndpoint && transportPlan.authMode !== 'login-required') {
              this.dataset.natsAuthEndpoint = transportPlan.authEndpoint;
            } else {
              delete this.dataset.natsAuthEndpoint;
            }
            if (transportPlan.busAuthMode) {
              this.dataset.busAuthMode = transportPlan.busAuthMode;
            }
            if (transportPlan.sessionMode) {
              this.dataset.sessionMode = transportPlan.sessionMode;
            }
            // eslint-disable-next-line no-console -- browser bootstrap, not an actor
            console.info(
              `[MatrixDSLHost] transport plan → wsMode="${transportPlan.wsMode ?? 'same-origin-proxy'}", wsPath="${wsPath ?? 'none'}", authMode="${transportPlan.authMode ?? 'unknown'}", busAuthMode="${transportPlan.busAuthMode ?? 'unknown'}", sessionMode="${transportPlan.sessionMode ?? 'unknown'}"`,
            );
          } else {
            throw new Error('Hosted bootstrap did not declare transportPlan');
          }
          if (bootstrap.sources) {
            this.dataset.rootSource = bootstrap.sources.root ?? '';
            this.dataset.addressRootSource = bootstrap.sources.addressRoot ?? '';
            this.dataset.selectedAuthorityRootSource = bootstrap.sources.selectedAuthorityRoot ?? '';
            this.dataset.runtimeInstanceRootSource = bootstrap.sources.runtimeInstanceRoot ?? '';
            this.dataset.transportAuthSource = bootstrap.sources.transportAuthMode ?? '';
            this.dataset.busTokenSource = bootstrap.sources.busToken ?? '';
            // eslint-disable-next-line no-console -- browser bootstrap, not an actor
            console.info(
              `[MatrixDSLHost] bootstrap sources → root="${bootstrap.sources.root ?? 'unknown'}", addressRoot="${bootstrap.sources.addressRoot ?? 'unknown'}", wsPath="${bootstrap.sources.browserWsPath ?? 'unknown'}", auth="${bootstrap.sources.transportAuthMode ?? 'unknown'}", busToken="${bootstrap.sources.busToken ?? 'unknown'}", identity="${bootstrap.sources.sessionIdentity ?? 'unknown'}"`,
            );
          }
          if (bootstrap.natsToken) {
            this.dataset.natsToken = bootstrap.natsToken;
          }
          // Store bus token in memory only (INV-ID-7: never localStorage/cookies)
          if (bootstrap.busToken && !renderNamespaceSetupLocally) {
            this.dataset.busToken = bootstrap.busToken;
          }
        }
      } catch (error) {
        if (requireDaemonBootstrap) {
          throw error;
        }
      }

      // 0b. URL param overrides (when url-params attribute is present)
      //     URL params take highest priority, overriding even Host bootstrap config.
      if (this.hasAttribute('url-params')) {
        const urlParams = new URLSearchParams(window.location.search);
        for (const [paramKey, attrName] of Object.entries(MatrixDSLHost.URL_PARAM_MAP)) {
          const value = urlParams.get(paramKey);
          if (value) this.setAttribute(attrName, value);
        }
      }
      if (
        usedBootstrap
        && hostedAppName
        && hostedAppName !== 'web'
        && routeKeyRoute !== null
        && !this._isAuthenticated
        && !loginRequiredBootstrap
      ) {
        this._redirectHostedAppToLogin();
        return;
      }

      if (
        usedBootstrap
        && hostedAppName
        && hostedAppName !== 'web'
        && !hostBootstrapMode
        && hasExplicitDaemonTargetParam
      ) {
        await this._applyExplicitHostedRuntimeTarget('bootstrap-explicit');
      }

      if (routeKeyRoute && !hasExplicitDaemonTargetParam) {
        const routeKeyMatchesBootstrap = !bootstrapRouteKey
          || bootstrapRouteKey === routeKeyRoute.routeKey;
        const authorityRoot = routeKeyMatchesBootstrap
          ? bootstrapAuthorityRoot || (this.dataset.selectedAuthorityRoot ?? '').trim()
          : '';
        if (authorityRoot) {
          this.setAttribute('daemon-root', authorityRoot);
          this.setAttribute('daemon-realm', authorityRoot);
          this.dataset.selectedAuthorityRoot = authorityRoot;
          this.dataset.explicitAuthorityRoot = authorityRoot;
          this._applyHostedRuntimeTargetMetadata(
            authorityRoot,
            'explicit',
            'authority',
            authorityRoot,
          );
        }
      }

      if (
        usedBootstrap
        && hostedAppName
        && hostedAppName !== 'web'
        && !hostBootstrapMode
        && routeKeyRoute === null
      ) {
        if (!this._isAuthenticated && !loginRequiredBootstrap) {
          this._redirectHostedAppToLogin();
          return;
        }

        if (hadExplicitDaemonTarget && !hasExplicitDaemonTargetParam) {
          await this._applyExplicitHostedRuntimeTarget('bootstrap-explicit');
        }
      }

      if (
        usedBootstrap
        && hostedAppName
        && hostedAppName !== 'web'
        && !hostBootstrapMode
        && !hadExplicitDaemonTarget
        && !hasExplicitDaemonTargetParam
      ) {
        const runtimeTarget = await profileBrowserSpan(
          HOST_PROFILE_SCOPE,
          'runtimeTarget.auto',
          async () => this._resolveHostedUserRuntimeTarget(),
          {
            hostedApp: hostedAppName ?? '',
          },
        );
        this._applyHostedRuntimeTargetMetadata(
          runtimeTarget.root,
          runtimeTarget.source,
          runtimeTarget.kind,
          runtimeTarget.requestedRoot,
          runtimeTarget.unavailableReason,
        );
        // eslint-disable-next-line no-console -- browser bootstrap, not an actor
        console.info(
          `[MatrixDSLHost] hosted app runtime target → ${runtimeTarget.root || '(none)'} ` +
          `(source=${runtimeTarget.source}, kind=${runtimeTarget.kind}, unavailable=${runtimeTarget.unavailableReason})`,
        );
      }

      // 1. Determine mode from explicit four-roots attributes.
      const busRootAttr = this.getAttribute('bus-root');
      const backboneUrl = this.getAttribute('backbone');
      const natsWsAttr = this.getAttribute('nats-ws-url');
      const natsWsUrl = natsWsAttr ?? (!discoveredNats ? backboneUrl : null);
      const mountPath = this.getAttribute('mount') ?? this.id ?? '';
      const hasNatsBackbone = Boolean(busRootAttr && natsWsUrl);
      const anonymousLocalBootstrap = this._bootstrapTransportPlan?.authMode === 'anonymous'
        && this._bootstrapTransportPlan.sessionMode === 'anonymous';
      if (requireDaemonBootstrap
        && !renderNamespaceSetupLocally
        && !loginRequiredBootstrap
        && !anonymousLocalBootstrap
        && (!usedBootstrap || !hasNatsBackbone)) {
        throw new Error('Hosted app bootstrap did not provide complete transport coordinates');
      }
      let selectedBackboneUrl: string | undefined;

      // 2. Create transport + optional peer
      if (busRootAttr && natsWsUrl) {
        // FEDERATED MODE: Connect to the NATS backbone when transport coordinates exist.
        // _bootstrapFederated() already handles both authenticated JWT flows and
        // unauthenticated direct websocket connections.
        await profileBrowserSpan(
          HOST_PROFILE_SCOPE,
          'bootstrapFederated',
          async () => this._bootstrapFederated(busRootAttr, natsWsUrl, mountPath),
          {
            root: busRootAttr,
            mountPath,
          },
        );
        selectedBackboneUrl = natsWsUrl;
      } else if (busRootAttr) {
        // ROOT-LOCAL MODE: Anonymous users or no backbone URL.
        // Uses in-memory transport — actor lifecycle works normally,
        // onReady fires, pages render. No NATS permission errors.
        this._bootstrapRootLocal(busRootAttr, mountPath);
      } else {
        // LOCAL MODE: plain InMemoryBroker, no federation
        this._bootstrapLocal(mountPath);
      }

      const rootCtx = this._runtime!.getRootContext!();

      // 2b. Register context services for child components
      const routingPeer = this._routingPeer;
      const sessionRoot = (this._transport?.root ?? this._transport?.realm) ?? busRootAttr ?? '';
      const hasBackbone = routingPeer?.hasBackbone ?? false;
      this.dataset.sessionRoot = sessionRoot;
      this.dataset.runtimeRoot = sessionRoot;
      this.dataset.runtimeInstanceRoot = sessionRoot;
      rootCtx.setService('runtime-instance-root', sessionRoot);

      if (routingPeer) {
        rootCtx.setService(SESSION_INFO_KEY, {
          mode: 'router',
          root: sessionRoot,
          realm: sessionRoot,
          hasBackbone,
          backboneUrl: selectedBackboneUrl,
          backboneError: hasBackbone ? null : 'Connection failed or not attempted',
        } as ISessionInfo);
        rootCtx.setService(FEDERATION_PEER_KEY, routingPeer);
      } else {
        rootCtx.setService(SESSION_INFO_KEY, {
          mode: 'local',
          root: sessionRoot,
          realm: sessionRoot,
          hasBackbone: false,
        } as ISessionInfo);
      }

      // 2c. Register identity services on root context for child actors
      const daemonRoot = this.getAttribute('daemon-root') ?? this.getAttribute('daemon-realm');
      if (daemonRoot) {
        rootCtx.setService('daemon-root', daemonRoot);
      }
      if (this.dataset.platformRoot) {
        rootCtx.setService('platform-root', this.dataset.platformRoot);
      }
      if (this.dataset.assetHostRoot) {
        rootCtx.setService('asset-host-root', this.dataset.assetHostRoot);
      }
      if (this.dataset.platformServiceRoot) {
        rootCtx.setService('platform-service-root', this.dataset.platformServiceRoot);
      }
      if (this.dataset.sessionAuthorityRoot) {
        rootCtx.setService('session-authority-root', this.dataset.sessionAuthorityRoot);
      }
      if (this.dataset.selectedAuthorityRoot) {
        rootCtx.setService('selected-authority-root', this.dataset.selectedAuthorityRoot);
      }
      rootCtx.setService('is-platform-admin', this.dataset.isPlatformAdmin === 'true');
      const authorityRootService = this.dataset.selectedAuthorityRoot
        || this.dataset.sessionAuthorityRoot;
      if (authorityRootService) {
        rootCtx.setService('authority-root', authorityRootService);
      }
      if (this.dataset.principalId) {
        rootCtx.setService('principal-id', this.dataset.principalId);
      }
      if (this.dataset.busToken) {
        rootCtx.setService('bus-token', this.dataset.busToken);
      }
      this._installScopedActorServices(rootCtx, sessionRoot);
      if (this.dataset.orgId) {
        rootCtx.setService('org-id', this.dataset.orgId);
      }
      if (this.dataset.workspaceId) {
        rootCtx.setService('workspace-id', this.dataset.workspaceId);
      }

      // 3. Install $join responder so children can join
      this._installJoinResponder();

      // 4. Mount all light DOM children with derived contexts
      await profileBrowserSpan(
        HOST_PROFILE_SCOPE,
        'mountChildren',
        async () => this._mountChildren(),
        {
          childCount: this.children.length,
        },
      );

      // 5. Set up mutation observer for dynamic children
      this._setupMutationObserver();

      // 6. Parse root attributes for RootContext propagation
      this._parseRootAttributes();
      this._propagateRootToChildren();

      // 7. Done
      this._initialized = true;
      const status = loginRequiredBootstrap
        ? 'login-required'
        : (routingPeer?.hasBackbone || hasNatsBackbone) ? 'connected' : 'local';
      this.dataset.status = status;
      this.dataset.daemonStatus = loginRequiredBootstrap
        ? 'skipped'
        : this.getAttribute('daemon-root') ? 'discovering' : 'skipped';
      this._manageLoadingElement(status);
      this._resolveReady();
      this._fireReadyEvent();
      const skipHostedShellDaemonDiscovery = this._shouldSkipHostedShellDaemonDiscovery(
        hadExplicitDaemonTarget || hasExplicitDaemonTargetParam,
      );

      // Dispatch auth state event for app-level code
      this.dispatchEvent(new CustomEvent(
        this._isAuthenticated ? 'matrix-dsl-authenticated' : 'matrix-dsl-anonymous',
        { bubbles: true, detail: { principal: this._principal, activeOrg: this._activeOrg } },
      ));

      if (loginRequiredBootstrap) {
        this.dispatchEvent(new CustomEvent('matrix-host-login-required', {
          bubbles: true,
          composed: true,
          detail: {
            routeKind: this.dataset.routeKind ?? '',
            sessionMode: this.dataset.sessionMode ?? '',
            provider: this.dataset.loginProvider ?? '',
            startUrl: this.dataset.loginStartUrl ?? '',
          },
        }));
        if (this._shouldRedirectToDeviceLogin(hostedAppName)) {
          this._redirectToDeviceLogin();
        } else if (hostedAppName !== 'web') {
          this._redirectToPlatformLogin();
        }
        return;
      }

      // Non-blocking — children are already mounted and can observe late identity resolution.
      logBrowserProfile(HOST_PROFILE_SCOPE, 'phaseB.scheduled', {
        usedBootstrap,
        skipped: renderNamespaceSetupLocally,
      });
      if (!renderNamespaceSetupLocally) {
        void this._runPhaseBBusDiscovery(usedBootstrap);
      } else {
        console.info('[MatrixDSLHost] Phase B service probe skipped for namespace setup — awaiting route-key claim');
      }

      // Non-blocking — must run after _fireReadyEvent() so child app subscriptions are live
      logBrowserProfile(HOST_PROFILE_SCOPE, 'daemonDiscovery.scheduled', {
        daemonRoot: this.getAttribute('daemon-root') ?? '',
        skipped: renderNamespaceSetupLocally || skipHostedShellDaemonDiscovery,
      });
      if (!renderNamespaceSetupLocally && !skipHostedShellDaemonDiscovery) {
        void this._discoverDaemon();
      } else {
        this.dataset.daemonStatus = 'skipped';
        const skippedDaemonRoot = this.getAttribute('daemon-root') ?? this.getAttribute('daemon-realm') ?? '';
        rootCtx.transport.publish(TopicRouter.events(''), {
          op: 'daemonReady',
          payload: {
            root: skippedDaemonRoot,
            realm: skippedDaemonRoot,
            skipped: true,
            namespaceSetup: renderNamespaceSetupLocally,
            platformShell: skipHostedShellDaemonDiscovery,
          },
        });
      }

      if (this._shouldRefreshHostedRuntimeTarget()) {
        this._startHostedRuntimeTargetRefresh();
        void this._refreshHostedRuntimeTargetMetadata();
      }
    } catch (err) {
      const diagnostics = await this._diagnoseBootstrapFailure(err);
      const error = err instanceof Error ? err : new Error(String(err));
      error.message = [error.message, '', ...diagnostics.lines].join('\n');
      // eslint-disable-next-line no-console -- browser bootstrap, not an actor
      console.error(
        requireDaemonBootstrap
          ? '[MatrixDSLHost] Hosted bootstrap failed — refusing local substitution:'
          : '[MatrixDSLHost] Bootstrap failed — offline local substitution disabled:',
        error,
      );
      this.dataset.errorClass = diagnostics.classification;
      this.dataset.status = 'disconnected';
      this.dataset.daemonStatus = 'error';

      this.dataset.status = 'error';
      this._manageLoadingElement('error', error);

      this.dispatchEvent(new CustomEvent('matrix-dsl-error', {
        bubbles: true,
        detail: { error, classification: diagnostics.classification, hint: diagnostics.hint },
      }));
    } finally {
      finishBootstrapProfile({
        status: this.dataset.status ?? '',
        daemonStatus: this.dataset.daemonStatus ?? '',
      });
    }
  }

  private _readHostedSelectedLeafRoot(): string | null {
    if (typeof window === 'undefined') {
      return null;
    }
    const stores: Array<Storage | undefined> = [window.sessionStorage, window.localStorage];
    for (const store of stores) {
      const raw = store?.getItem(HOSTED_SELECTED_LEAF_STORAGE_KEY);
      if (typeof raw !== 'string') {
        continue;
      }
      const normalized = raw.trim();
      if (normalized.length > 0) {
        return normalized;
      }
    }
    return null;
  }

  private _sortRuntimeRootsForDefault(authorityRoot: string | null, roots: string[]): string[] {
    const normalizedAuthority = typeof authorityRoot === 'string' && authorityRoot.trim().length > 0
      ? authorityRoot.trim()
      : null;
    const filtered = normalizedAuthority
      ? roots.filter((root) => root === normalizedAuthority || root.startsWith(`${normalizedAuthority}.`))
      : roots.slice();
    const candidates = normalizedAuthority ? filtered : roots.slice();
    return candidates.sort((left, right) => {
      const leftSegments = left.split('.').length;
      const rightSegments = right.split('.').length;
      if (leftSegments !== rightSegments) {
        return leftSegments - rightSegments;
      }
      return left.localeCompare(right);
    });
  }

  private _classifyHostedRuntimeTarget(
    root: string | null,
    authorityRoot: string | null,
    attachedLeafRoots: string[],
  ): HostedRuntimeTargetKind {
    if (!root) {
      return 'unknown';
    }
    if (authorityRoot && root === authorityRoot) {
      return 'authority';
    }
    if (attachedLeafRoots.includes(root)) {
      return 'leaf';
    }
    if (authorityRoot && root.startsWith(`${authorityRoot}.`)) {
      return 'leaf';
    }
    return 'unknown';
  }

  private _authenticatedPrincipalAuthorityRoot(): string | null {
    if (!this._isAuthenticated) {
      return null;
    }
    const principalRoot = (this.dataset.principalAuthorityRoot ?? '').trim();
    if (principalRoot) {
      return principalRoot;
    }
    const sessionRoot = (this.dataset.sessionAuthorityRoot ?? '').trim();
    return sessionRoot || null;
  }

  private _hostedAuthorityRootFromBootstrap(): string {
    const selectedRoot = (this.dataset.selectedAuthorityRoot ?? '').trim();
    const principalRoot = this._authenticatedPrincipalAuthorityRoot();
    return selectedRoot || principalRoot || '';
  }

  private _parseHostedRuntimeSummary(summary: IRuntimeSummaryPayload): IHostedRuntimeSummaryState {
    const authorityRoot = this._hostedAuthorityRootFromBootstrap();

    const items = Array.isArray(summary.attachedLeafRoots?.items)
      ? summary.attachedLeafRoots.items
      : [];
    const knownLeafRoots = [...new Set(
      items
        .map((item) => typeof item?.root === 'string' ? item.root.trim() : '')
        .filter((root) => root.length > 0),
    )];
    const liveLeafRoots = [...new Set(
      items
        .filter((item) => {
          const connectionKind = typeof item?.connectionKind === 'string' ? item.connectionKind.trim() : '';
          return connectionKind.length === 0 || connectionKind !== 'registered';
        })
        .map((item) => typeof item?.root === 'string' ? item.root.trim() : '')
        .filter((root) => root.length > 0),
    )];

    return {
      authorityRoot: authorityRoot || null,
      liveLeafRoots,
      knownLeafRoots,
    };
  }

  private _readHostedRuntimeTargetInfo(): IHostedRuntimeTargetInfo {
    return resolveHostedRuntimeTargetInfo(this);
  }

  private _setOptionalDatasetValue(name: string, value: string): void {
    if (value) {
      this.dataset[name] = value;
    } else {
      delete this.dataset[name];
    }
  }

  private _initialRuntimeSummaryState(): IHostedRuntimeSummaryState {
    return {
      authorityRoot: typeof this.dataset.selectedAuthorityRoot === 'string'
        ? this.dataset.selectedAuthorityRoot.trim() || null
        : null,
      liveLeafRoots: [],
      knownLeafRoots: [],
    };
  }

  private async _applyExplicitHostedRuntimeTarget(reason: string): Promise<void> {
    const explicitRuntimeTarget = (
      this.getAttribute('daemon-root')
      ?? this.getAttribute('daemon-realm')
      ?? ''
    ).trim();
    if (!explicitRuntimeTarget) {
      return;
    }

    if (!this._context) {
      const summaryState = this._initialRuntimeSummaryState();
      const runtimeTarget = this._resolveHostedRequestedRuntimeTarget(
        explicitRuntimeTarget,
        summaryState,
        'explicit',
      );
      const authorizedInitialRoot = runtimeTarget.root
        ?? this._authorizedExplicitRootBeforeRuntimeSummary(
          explicitRuntimeTarget,
          summaryState.authorityRoot,
          runtimeTarget.unavailableReason,
        );
      this._applyHostedRuntimeTargetMetadata(
        authorizedInitialRoot,
        runtimeTarget.source,
        authorizedInitialRoot
          ? this._classifyHostedRuntimeTarget(
            authorizedInitialRoot,
            summaryState.authorityRoot,
            summaryState.liveLeafRoots,
          )
          : runtimeTarget.kind,
        runtimeTarget.requestedRoot,
        authorizedInitialRoot ? 'none' : runtimeTarget.unavailableReason,
      );
      return;
    }

    let summaryState = this._initialRuntimeSummaryState();
    try {
      const summary = await this._loadHostedRuntimeSummaryFromBus(reason);
      if (summary) {
        summaryState = this._parseHostedRuntimeSummary(summary);
      }
    } catch {
      // Preserve the explicit requested target in metadata, but do not promote
      // it to the actual runtime root when live runtime inventory is missing.
    }

    const runtimeTarget = this._resolveHostedRequestedRuntimeTarget(
      explicitRuntimeTarget,
      summaryState,
      'explicit',
    );
    this._applyHostedRuntimeTargetMetadata(
      runtimeTarget.root,
      runtimeTarget.source,
      runtimeTarget.kind,
      runtimeTarget.requestedRoot,
      runtimeTarget.unavailableReason,
    );
  }

  private _applyHostedRuntimeTargetMetadata(
    root: string | null,
    source: HostedRuntimeTargetSource,
    kind: HostedRuntimeTargetKind,
    requestedRoot: string | null = null,
    unavailableReason: 'missing' | 'not-live' | 'unauthorized' | 'none' = 'none',
  ): void {
    if (root) {
      this.setAttribute('daemon-root', root);
      this.setAttribute('daemon-realm', root);
    } else {
      this.removeAttribute('daemon-root');
      this.removeAttribute('daemon-realm');
    }

    if (root) {
      this.dataset.runtimeTargetRoot = root;
      this.dataset.runtimeTargetSource = source;
      this.dataset.runtimeTargetKind = kind;
    } else {
      delete this.dataset.runtimeTargetRoot;
      this.dataset.runtimeTargetSource = source;
      this.dataset.runtimeTargetKind = kind;
    }
    if (requestedRoot) {
      this.dataset.runtimeTargetRequestedRoot = requestedRoot;
    } else {
      delete this.dataset.runtimeTargetRequestedRoot;
    }
    if (unavailableReason !== 'none') {
      this.dataset.runtimeTargetUnavailableReason = unavailableReason;
    } else {
      delete this.dataset.runtimeTargetUnavailableReason;
    }
    this._renderHostedRuntimeRecoveryNotice(root, requestedRoot, unavailableReason);
  }

  private _renderHostedRuntimeRecoveryNotice(
    root: string | null,
    requestedRoot: string | null,
    unavailableReason: 'missing' | 'not-live' | 'unauthorized' | 'none',
  ): void {
    const existing = this._hostedRuntimeRecoveryNotice();
    const plan = resolveHostedRuntimeRecoveryPlan({
      runtimeRoot: root,
      authorityRoot: this._initialRuntimeSummaryState().authorityRoot,
      requestedRoot,
      unavailableReason,
      currentHref: typeof window !== 'undefined' ? window.location.href : null,
    });
    if (!plan) {
      existing?.remove();
      return;
    }

    const notice = existing ?? document.createElement('div');
    notice.setAttribute(HOSTED_RUNTIME_RECOVERY_NOTICE_ATTR, 'true');
    notice.setAttribute('role', 'status');
    notice.style.display = 'flex';
    notice.style.gap = '8px';
    notice.style.alignItems = 'center';
    notice.style.padding = '8px 12px';
    notice.style.background = '#fff4e5';
    notice.style.color = '#4a2a00';
    notice.style.border = '1px solid #ffcc80';
    notice.style.font = '13px system-ui, sans-serif';
    notice.textContent = '';

    const summary = document.createElement('span');
    summary.textContent = plan.summary;
    notice.appendChild(summary);

    for (const action of plan.actions) {
      const link = document.createElement('a');
      link.href = action.href;
      link.textContent = action.label;
      link.title = action.title;
      link.style.color = '#6b3900';
      link.style.fontWeight = '600';
      notice.appendChild(link);
    }

    if (!existing) {
      this.insertBefore(notice, this.firstChild);
    }
  }

  private _hostedRuntimeRecoveryNotice(): HTMLElement | null {
    for (const child of Array.from(this.children)) {
      if (
        child instanceof HTMLElement
        && child.getAttribute(HOSTED_RUNTIME_RECOVERY_NOTICE_ATTR) === 'true'
      ) {
        return child;
      }
    }
    return null;
  }

  private _resolveHostedRequestedRuntimeTarget(
    requestedRoot: string | null,
    summary: IHostedRuntimeSummaryState,
    preferredSource: HostedRuntimeTargetSource,
  ): IHostedRuntimeTarget {
    const target = typeof requestedRoot === 'string' && requestedRoot.trim().length > 0
      ? requestedRoot.trim()
      : null;
    const authorityRoot = summary.authorityRoot;
    const liveLeafRoots = summary.liveLeafRoots;
    const knownLeafRoots = summary.knownLeafRoots;
    const chooseDefault = (): string | null => {
      const candidates = this._sortRuntimeRootsForDefault(authorityRoot, liveLeafRoots);
      return candidates[0] ?? null;
    };

    if (target && liveLeafRoots.includes(target)) {
      return {
        root: target,
        source: preferredSource,
        kind: this._classifyHostedRuntimeTarget(target, authorityRoot, liveLeafRoots),
        requestedRoot: target,
        unavailableReason: 'none',
      };
    }

    if (target && authorityRoot && target === authorityRoot) {
      return {
        root: authorityRoot,
        source: preferredSource,
        kind: this._classifyHostedRuntimeTarget(authorityRoot, authorityRoot, liveLeafRoots),
        requestedRoot: target,
        unavailableReason: 'none',
      };
    }

    if (target) {
      if (this._isUnauthorizedHostedRuntimeTarget(target, authorityRoot, liveLeafRoots, knownLeafRoots)) {
        return {
          root: null,
          source: preferredSource,
          kind: 'unknown',
          requestedRoot: target,
          unavailableReason: 'unauthorized',
        };
      }
      const unavailableReason = knownLeafRoots.includes(target) ? 'not-live' : 'missing';
      return {
        root: null,
        source: preferredSource,
        kind: this._classifyHostedRuntimeTarget(target, authorityRoot, liveLeafRoots),
        requestedRoot: target,
        unavailableReason,
      };
    }

    const automaticRoot = chooseDefault();
    if (automaticRoot) {
      return {
        root: automaticRoot,
        source: 'auto',
        kind: this._classifyHostedRuntimeTarget(automaticRoot, authorityRoot, liveLeafRoots),
        requestedRoot: null,
        unavailableReason: 'none',
      };
    }

    if (authorityRoot) {
      return {
        root: authorityRoot,
        source: 'auto',
        kind: 'authority',
        requestedRoot: null,
        unavailableReason: 'none',
      };
    }

    return {
      root: null,
      source: 'none',
      kind: 'unknown',
      requestedRoot: target,
      unavailableReason: 'none',
    };
  }

  private _isUnauthorizedHostedRuntimeTarget(
    target: string,
    authorityRoot: string | null,
    liveLeafRoots: readonly string[],
    knownLeafRoots: readonly string[],
  ): boolean {
    if (!authorityRoot || target === authorityRoot) {
      return false;
    }
    if (liveLeafRoots.includes(target) || knownLeafRoots.includes(target)) {
      return false;
    }
    if (target.startsWith(`${authorityRoot}.`)) {
      return false;
    }
    return this._looksLikeHostedAuthorityRoot(target);
  }

  private _authorizedExplicitRootBeforeRuntimeSummary(
    target: string,
    authorityRoot: string | null,
    unavailableReason: 'missing' | 'not-live' | 'unauthorized' | 'none',
  ): string | null {
    if (unavailableReason === 'unauthorized' || !authorityRoot) {
      return null;
    }
    if (target === authorityRoot || target.startsWith(`${authorityRoot}.`)) {
      return target;
    }
    return null;
  }

  private _looksLikeHostedAuthorityRoot(root: string): boolean {
    return /^SPACE-[A-Z0-9][A-Z0-9_-]*$/.test(root)
      || /^[A-Z][A-Z0-9_-]*(?:\.[A-Z0-9_-]+)+$/.test(root);
  }

  private _shouldRefreshHostedRuntimeTarget(): boolean {
    if (!this._isAuthenticated) {
      return false;
    }
    const pathname = typeof window !== 'undefined' && typeof window.location?.pathname === 'string'
      ? window.location.pathname
      : '';
    if (!pathname.startsWith('/apps/') && this._parseRouteKeyWebappRouteFromLocation() === null) {
      return false;
    }
    const hostedAppName = this._deriveHostedAppName()?.trim().toLowerCase();
    return Boolean(hostedAppName && hostedAppName !== 'web');
  }

  private _resolveHostedRuntimeTargetForActiveSession(
    summary: IHostedRuntimeSummaryState,
  ): IHostedRuntimeTarget {
    const current = this._readHostedRuntimeTargetInfo();
    const preferredSource = current.targetSource === 'explicit' ? 'explicit' : 'auto';
    const requestedRoot = preferredSource === 'explicit'
      ? current.requestedRoot || current.runtimeRoot || null
      : null;
    return this._resolveHostedRequestedRuntimeTarget(requestedRoot, {
      authorityRoot: summary.authorityRoot ?? (current.authorityRoot || null),
      liveLeafRoots: summary.liveLeafRoots,
      knownLeafRoots: summary.knownLeafRoots,
    }, preferredSource);
  }

  private async _refreshHostedRuntimeTargetMetadata(): Promise<void> {
    if (!this._shouldRefreshHostedRuntimeTarget() || this._hostedRuntimeTargetRefreshInFlight) {
      return;
    }
    this._hostedRuntimeTargetRefreshInFlight = true;
    const previous = this._readHostedRuntimeTargetInfo();
    try {
      const summary = await this._loadHostedRuntimeSummaryFromBus('refresh');
      if (!summary) {
        return;
      }
      const parsed = this._parseHostedRuntimeSummary(summary);
      const current = this._resolveHostedRuntimeTargetForActiveSession(parsed);
      this._applyHostedRuntimeTargetMetadata(
        current.root,
        current.source,
        current.kind,
        current.requestedRoot,
        current.unavailableReason,
      );
      const next = this._readHostedRuntimeTargetInfo();
      if (!hostedRuntimeTargetInfoEquals(previous, next)) {
        this.dispatchEvent(new CustomEvent<IHostedRuntimeTargetInfo>(
          HOSTED_RUNTIME_TARGET_CHANGED_EVENT,
          {
            bubbles: true,
            detail: next,
          },
        ));
      }
    } catch {
      // Keep current metadata when runtime summary is temporarily unavailable.
    } finally {
      this._hostedRuntimeTargetRefreshInFlight = false;
    }
  }

  private async _resolveHostedUserRuntimeTarget(): Promise<IHostedRuntimeTarget> {
    const selectedLeafRoot = this._readHostedSelectedLeafRoot();

    if (!this._isAuthenticated) {
      return {
        root: null,
        source: 'none',
        kind: 'unknown',
        requestedRoot: selectedLeafRoot,
        unavailableReason: 'none',
      };
    }

    if (!this._context) {
      const summaryState = this._initialRuntimeSummaryState();
      if (selectedLeafRoot) {
        return {
          root: selectedLeafRoot,
          source: 'explicit',
          kind: this._classifyHostedRuntimeTarget(
            selectedLeafRoot,
            summaryState.authorityRoot,
            summaryState.liveLeafRoots,
          ),
          requestedRoot: selectedLeafRoot,
          unavailableReason: 'none',
        };
      }
      const authorityRoot = summaryState.authorityRoot;
      return {
        root: authorityRoot,
        source: authorityRoot ? 'auto' : 'none',
        kind: authorityRoot ? 'authority' : 'unknown',
        requestedRoot: selectedLeafRoot,
        unavailableReason: 'none',
      };
    }

    try {
      const summary = await this._loadHostedRuntimeSummaryFromBus('bootstrap-auto');
      if (!summary) {
        return {
          root: null,
          source: 'none',
          kind: 'unknown',
          requestedRoot: selectedLeafRoot,
          unavailableReason: 'none',
        };
      }

      const parsed = this._parseHostedRuntimeSummary(summary);
      return this._resolveHostedRequestedRuntimeTarget(selectedLeafRoot, parsed, 'explicit');
    } catch {
      return {
        root: null,
        source: 'none',
        kind: 'unknown',
        requestedRoot: selectedLeafRoot,
        unavailableReason: 'none',
      };
    }
  }

  private async _loadHostedRuntimeSummaryFromBus(reason: string): Promise<IRuntimeSummaryPayload | null> {
    if (!this._context) {
      return null;
    }
    const authorityRoot = this._authenticatedPrincipalAuthorityRoot()
      ?? this._initialRuntimeSummaryState().authorityRoot;
    if (!authorityRoot) {
      return null;
    }
    const principalId = typeof this._principal?.principalId === 'string'
      ? this._principal.principalId.trim()
      : '';
    const busToken = typeof this.dataset.busToken === 'string' ? this.dataset.busToken.trim() : '';
    if (!busToken) {
      return null;
    }
    const payload: Record<string, unknown> = {
      busToken,
      ...(principalId ? { principalId } : {}),
      authorityRoot,
      includeOffline: true,
    };
    const controlPlaneRoot = this._controlPlaneRootForSingletons(authorityRoot);
    const response = await profileBrowserSpan(
      HOST_PROFILE_SCOPE,
      'runtimeSummary.devices.list',
      async () => RequestReply.execute<Record<string, unknown>, IDevicesListResponse>(
        this._context!,
        `${controlPlaneRoot}/system.devices`,
        'devices.list',
        payload,
        { timeoutMs: 5000 },
      ),
      { reason },
    );
    if (response.ok !== true) {
      return null;
    }
    return this._runtimeSummaryFromDeviceInventory(authorityRoot, response.devices);
  }

  private _runtimeSummaryFromDeviceInventory(authorityRoot: string, value: unknown): IRuntimeSummaryPayload {
    const devices = Array.isArray(value)
      ? value
          .map((entry) => this._deviceInventoryRecord(entry))
          .filter((entry): entry is IDeviceInventoryRecord => entry !== null)
      : [];
    return {
      authority: {
        addressRoot: authorityRoot,
      },
      attachedLeafRoots: {
        items: devices
          .map((device) => {
            const root = typeof device.authorityRoot === 'string'
              ? device.authorityRoot.trim()
              : '';
            if (!root) {
              return null;
            }
            const status = typeof device.status === 'string'
              ? device.status.trim().toLowerCase()
              : '';
            return {
              root,
              connectionKind: status === 'online' ? 'Leafnode' : 'registered',
            };
          })
          .filter((entry): entry is { readonly root: string; readonly connectionKind: string } => entry !== null),
      },
    };
  }

  private _deviceInventoryRecord(value: unknown): IDeviceInventoryRecord | null {
    return value && typeof value === 'object' && !Array.isArray(value)
      ? value as IDeviceInventoryRecord
      : null;
  }

  private _shouldRequireDaemonBootstrap(): boolean {
    const bootstrapMode = this.getAttribute('bootstrap-mode')?.trim().toLowerCase();
    const pathname = typeof window !== 'undefined' && typeof window.location?.pathname === 'string'
      ? window.location.pathname
      : '';
    if (bootstrapMode === 'local' || bootstrapMode === 'standalone') {
      return false;
    }
    if (pathname.startsWith('/apps/')) {
      return true;
    }
    if (this._isHostBootstrapMode() || this._isHostServiceBootstrap()) {
      return true;
    }
    if (bootstrapMode === 'daemon' || bootstrapMode === 'hosted') {
      return true;
    }
    return false;
  }

  private _redirectHostedAppToLogin(): void {
    const redirectTarget = this._currentRelativeLocation();
    const location = window.location;
    const nextUrl = `/login?redirect=${encodeURIComponent(redirectTarget)}`;
    this.dataset.status = 'redirecting-auth';
    this._manageLoadingElement('redirecting-auth');
    if (typeof location.assign === 'function') {
      location.assign(nextUrl);
      return;
    }
    if (typeof location.replace === 'function') {
      location.replace(nextUrl);
      return;
    }
    try {
      location.href = nextUrl;
    } catch {
      // no-op: test doubles may expose a read-only href
    }
  }

  private _currentRelativeLocation(): string {
    const pathname = typeof window !== 'undefined' && typeof window.location?.pathname === 'string'
      ? window.location.pathname
      : '/';
    const search = typeof window !== 'undefined' && typeof window.location?.search === 'string'
      ? window.location.search
      : '';
    const hash = typeof window !== 'undefined' && typeof window.location?.hash === 'string'
      ? window.location.hash
      : '';
    return `${pathname || '/'}${search}${hash}`;
  }

  private _bootstrapEndpointForRoute(routeKeyRoute: IRouteKeyWebappRoute | null, appName: string | null): string {
    const params = new URLSearchParams();
    if (routeKeyRoute) {
      params.set('routeKey', routeKeyRoute.routeKey);
    }
    if (appName) {
      params.set('appName', appName);
    }
    const query = params.toString();
    return query ? `/api/bootstrap?${query}` : '/api/bootstrap';
  }

  private _isHostBootstrapMode(): boolean {
    const mode = this.getAttribute('bootstrap-mode')?.trim().toLowerCase();
    return mode === 'host' || mode === 'host-service' || mode === 'matrix-host';
  }

  private _isHostServiceBootstrap(): boolean {
    return this.dataset.rootSource === 'host-service:transport.root';
  }

  private _isAuthoritativeBootstrapIdentitySource(source: string): boolean {
    return source === 'system-auth:principal.addressRoots'
      || source === 'system-auth:publicNamespaces';
  }

  private _shouldUseRuntimeRegistryDiscovery(authorityRoot: string): boolean {
    const root = authorityRoot.trim();
    if (!root) {
      return false;
    }

    const hostedAppName = this._deriveHostedAppName();
    if (!hostedAppName) {
      return false;
    }

    const runtimeTargetKind = this.dataset.runtimeTargetKind ?? '';
    const runtimeTargetRoot = this.dataset.runtimeTargetRoot ?? '';
    if (runtimeTargetKind === 'authority' && runtimeTargetRoot === root) {
      return true;
    }

    const selectedAuthorityRoot = (this.dataset.selectedAuthorityRoot ?? '').trim();
    const rootSource = this.dataset.rootSource ?? '';
    const selectedAuthorityRootSource = this.dataset.selectedAuthorityRootSource ?? '';
    const rootCameFromAuthoritativeBootstrap = this._isAuthoritativeBootstrapIdentitySource(rootSource)
      || this._isAuthoritativeBootstrapIdentitySource(selectedAuthorityRootSource);
    const authenticated = this.dataset.authenticated === 'true' || this._isAuthenticated === true;

    // Host Service deployments discover authority runtime state through
    // system.runtimes. Retired actor paths are not a product path.
    return authenticated && rootCameFromAuthoritativeBootstrap && selectedAuthorityRoot === root;
  }

  private _shouldSkipHostedShellDaemonDiscovery(hasExplicitDaemonTarget: boolean): boolean {
    if (hasExplicitDaemonTarget || this._isHostBootstrapMode() || this._isHostServiceBootstrap()) {
      return false;
    }

    return this._deriveHostedAppName() === 'web';
  }

  private _shouldRetainBootstrapIdentity(authorityRoot: string): boolean {
    const root = authorityRoot.trim();
    const selectedAuthorityRoot = (this.dataset.selectedAuthorityRoot ?? '').trim();
    const rootSource = this.dataset.rootSource ?? '';
    const selectedAuthorityRootSource = this.dataset.selectedAuthorityRootSource ?? '';
    const rootCameFromAuthoritativeBootstrap = this._isAuthoritativeBootstrapIdentitySource(rootSource)
      || this._isAuthoritativeBootstrapIdentitySource(selectedAuthorityRootSource);
    const authenticated = this.dataset.authenticated === 'true' || this._isAuthenticated === true;

    return authenticated
      && root.length > 0
      && rootCameFromAuthoritativeBootstrap
      && (!selectedAuthorityRoot || selectedAuthorityRoot === root);
  }

  private _ensureHostRuntimeMount(authorityRoot: string, appName: string | null): void {
    const existingMount = this.getAttribute('mount')?.trim() ?? '';
    if (existingMount.length > 0) {
      return;
    }
    const runtimeId = this._getOrCreateBrowserRuntimeId(authorityRoot, appName);
    this.dataset.hostRuntimeId = runtimeId;
    this.setAttribute('mount', `system.runtimes.${runtimeId}`);
  }

  private _getOrCreateBrowserRuntimeId(authorityRoot: string, appName: string | null): string {
    const normalizedAuthority = authorityRoot.trim() || 'LOCAL';
    const normalizedApp = (appName ?? 'browser').trim().toUpperCase().replace(/[^A-Z0-9_-]/g, '-');
    const storageKey = `matrix-browser-runtime-id:${normalizedAuthority}:${normalizedApp}`;
    const existing = typeof sessionStorage !== 'undefined' ? sessionStorage.getItem(storageKey) : null;
    if (existing && /^RUNTIME-BROWSER-[A-Z0-9_-]+$/.test(existing)) {
      return existing;
    }

    const randomId = this._randomRuntimeSuffix();
    const runtimeId = `${BROWSER_RUNTIME_ID_PREFIX}${randomId}`;
    if (typeof sessionStorage !== 'undefined') {
      sessionStorage.setItem(storageKey, runtimeId);
    }
    return runtimeId;
  }

  private _randomRuntimeSuffix(): string {
    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
      return crypto.randomUUID().replace(/-/g, '').slice(0, 8).toUpperCase();
    }
    return Math.random().toString(36).slice(2, 10).toUpperCase();
  }

  private async _diagnoseBootstrapFailure(err: unknown): Promise<IBootstrapFailureDiagnostics> {
    const rawMessage = err instanceof Error ? err.message : String(err);
    const lines = [`Cause: ${rawMessage}`];

    const classify = (classification: string, hint: string): IBootstrapFailureDiagnostics => ({
      classification,
      hint,
      lines: [...lines, `Classification: ${classification}`, `Hint: ${hint}`],
    });

    if (/NATS JWT bootstrap failed/i.test(rawMessage)) {
      let healthLine = 'HTTP /healthz: not checked';
      let bootstrapLine = 'HTTP /api/bootstrap: not checked';

      try {
        const healthResp = await fetch('/healthz', { credentials: 'same-origin' });
        healthLine = `HTTP /healthz: ${healthResp.status} ${healthResp.ok ? 'ok' : 'not ok'}`;
      } catch (error) {
        healthLine = `HTTP /healthz: unreachable (${error instanceof Error ? error.message : String(error)})`;
      }

      try {
        const bootstrapResp = await fetch('/api/bootstrap', { credentials: 'same-origin' });
        bootstrapLine = `HTTP /api/bootstrap: ${bootstrapResp.status} ${bootstrapResp.ok ? 'ok' : 'not ok'}`;
      } catch (error) {
        bootstrapLine = `HTTP /api/bootstrap: unreachable (${error instanceof Error ? error.message : String(error)})`;
      }

      lines.push(healthLine, bootstrapLine);
      return classify(
        'nats-jwt-bootstrap',
        'The HiveCast HTTP surface may still be up. This usually means session-to-bus auth or first-boot provisioning failed, not that the whole Host is down.',
      );
    }

    if (/Failed to fetch|NetworkError|fetch/i.test(rawMessage)) {
      try {
        const healthResp = await fetch('/healthz', { credentials: 'same-origin' });
        lines.push(`HTTP /healthz: ${healthResp.status} ${healthResp.ok ? 'ok' : 'not ok'}`);
        return classify(
          'http-bootstrap',
          'The browser reached the HiveCast origin but a bootstrap HTTP request failed. Check /api/bootstrap and auth/session routes before assuming the Host is down.',
        );
      } catch (error) {
        lines.push(`HTTP /healthz: unreachable (${error instanceof Error ? error.message : String(error)})`);
        return classify(
          'host-gateway-unreachable',
          'The browser cannot reach the HiveCast HTTP gateway at all. This is the closest thing to “Host is down” in the bootstrap path.',
        );
      }
    }

    if (/websocket|nats|backbone|ECONNREFUSED|timeout/i.test(rawMessage)) {
      return classify(
        'backbone-connect',
        'HTTP bootstrap likely succeeded, but the browser failed while connecting to the NATS/websocket backbone or the routed Host path.',
      );
    }

    return classify(
      'bootstrap-runtime',
      'The Host may still be running. This failure happened inside browser bootstrap logic after initial HTTP discovery.',
    );
  }

  /**
   * FEDERATED MODE: Browser NATS WebSocket transport.
   */
  private async _bootstrapFederated(
    busRootInput: string,
    wsUrl: string,
    mountPath: string,
  ): Promise<void> {
    const hostBootstrapMode = this._isHostBootstrapMode();
    const busRoot = hostBootstrapMode ? busRootInput.trim() : busRootInput.toLowerCase().trim();
    const runtimeInstanceRoot = (this.dataset.runtimeInstanceRoot ?? '').trim();
    const sessionAuthorityRoot = (this.dataset.sessionAuthorityRoot ?? '').trim();
    const selectedAuthorityRoot = (this.dataset.selectedAuthorityRoot ?? '').trim();
    const identityRoot = sessionAuthorityRoot || selectedAuthorityRoot;
    const appName = this.getAttribute('app-name')?.trim() ?? '';
    if (!hostBootstrapMode && !runtimeInstanceRoot && identityRoot && !appName) {
      throw new Error(
        'MatrixDSLHost: bootstrap did not provide app-name. '
        + 'Identity tab root requires appName; see four-roots.md.',
      );
    }
    const tabRoot = hostBootstrapMode
      ? busRoot
      : runtimeInstanceRoot
      ? runtimeInstanceRoot
      : identityRoot
      ? getOrCreateIdentityTabRoot(appName, identityRoot)
      : getOrCreateTabRealm(busRoot);
    this._setOptionalDatasetValue('runtimeInstanceRoot', tabRoot);
    const declaredAuthMode = this._bootstrapTransportPlan?.authMode;

    // Prefer the explicit transport plan from /api/bootstrap.
    // If absent, probe the NATS auth endpoint to identify the configured mode.
    let jwtProvider: (() => Promise<{ jwt: string; seed: string }>) | undefined;
    let cachedJwt: { jwt: string; seed: string } | null = null;

    const buildNatsAuthEndpoint = (): string => {
      const base = this.dataset.natsAuthEndpoint || '/api/nats-jwt';
      const url = new URL(base, window.location.origin);
      const platformRoot = (this.dataset.platformRoot ?? '').trim();
      const requestedDaemonRoot = (this.getAttribute('daemon-root') ?? this.getAttribute('daemon-realm') ?? '').trim();
      const selectedAuthorityRoot = (this.dataset.selectedAuthorityRoot ?? '').trim();
      const anonymousSession = !this._isAuthenticated
        && (this._bootstrapTransportPlan?.sessionMode === 'anonymous' || this.dataset.sessionMode === 'anonymous');
      const daemonRoot = anonymousSession
        ? (platformRoot && requestedDaemonRoot === platformRoot ? platformRoot : '')
        : (selectedAuthorityRoot || requestedDaemonRoot);
      if (daemonRoot) {
        url.searchParams.set('daemonRoot', daemonRoot);
      } else if (anonymousSession) {
        url.searchParams.delete('daemonRoot');
        url.searchParams.delete('root');
      }
      if (tabRoot) {
        url.searchParams.set('clientRoot', tabRoot);
      }
      return url.pathname + url.search;
    };

    const fetchNatsAuthPayload = async (): Promise<{ jwt?: string; seed?: string; user?: string; pass?: string; mode?: string }> => {
      const endpoint = buildNatsAuthEndpoint();
      const response = await profileBrowserSpan(
        HOST_PROFILE_SCOPE,
        'natsAuth.fetch',
        async () => fetch(endpoint, { method: 'POST', credentials: 'same-origin' }),
        {
          authMode: declaredAuthMode ?? 'auto',
          endpoint,
        },
      );
      const payload = await profileBrowserSpan(
        HOST_PROFILE_SCOPE,
        'natsAuth.parse',
        async () => response.json().catch(() => ({})) as Promise<{ jwt?: string; seed?: string; user?: string; pass?: string; mode?: string; error?: string }>,
        {
          authMode: declaredAuthMode ?? 'auto',
          endpoint,
        },
      );
      if (!response.ok) {
        const detail = typeof payload.error === 'string' && payload.error.length > 0
          ? payload.error
          : `HTTP ${response.status}`;
        throw new Error(`NATS auth request failed (${response.status}): ${detail}`);
      }
      return payload;
    };

    const fetchJwtCredentials = async (): Promise<{ jwt: string; seed: string } | null> => {
      if (!this._isAuthenticated) {
        return null;
      }

      let lastError: Error | null = null;

      for (let attempt = 0; attempt < 8; attempt++) {
        const endpoint = buildNatsAuthEndpoint();
        const response = await profileBrowserSpan(
          HOST_PROFILE_SCOPE,
          'natsJwt.fetch',
          async () => fetch(endpoint, { method: 'POST', credentials: 'same-origin' }),
          {
            attempt: attempt + 1,
            authMode: declaredAuthMode ?? 'auto',
          },
        );
        if (response.ok) {
          const payload = await profileBrowserSpan(
            HOST_PROFILE_SCOPE,
            'natsJwt.parse',
            async () => response.json() as Promise<{ jwt?: string; seed?: string; user?: string; pass?: string; mode?: string }>,
            {
              attempt: attempt + 1,
              authMode: declaredAuthMode ?? 'auto',
            },
          );
          if (payload.jwt && payload.seed) {
            return { jwt: payload.jwt, seed: payload.seed };
          }
          // Static NATS mode — store user/pass for transport auth
          if (payload.mode === 'static' && payload.user && payload.pass) {
            this.dataset.natsUser = payload.user;
            this.dataset.natsPass = payload.pass;
            return null; // No JWT, use user/pass auth instead
          }
          // Anonymous mode — no credentials needed
          if (payload.mode === 'anonymous') {
            return null;
          }
          lastError = new Error('NATS JWT response missing jwt or seed');
        } else {
          const bodyText = await response.text().catch(() => '');
          const detail = bodyText.trim();

          // This deployment does not expose operator/JWT auth, so plain WS token mode is expected.
          if (
            response.status === 401
            || response.status === 403
            || response.status === 404
            || (response.status === 503 && /not configured|no operatorseed|no account selected|failed to create nats jwt/i.test(detail))
          ) {
            return null;
          }

          // Provisioning and rate-limit windows are transient immediately after login/startup.
          if (response.status === 429 || response.status >= 500 || /provisioning operation is in progress/i.test(detail)) {
            lastError = new Error(`NATS JWT temporary failure (${response.status}): ${detail || 'no body'}`);
            await new Promise((resolve) => setTimeout(resolve, Math.min(250 * (attempt + 1), 1000)));
            continue;
          }

          throw new Error(`NATS JWT request failed (${response.status}): ${detail || 'no body'}`);
        }
      }

      if (lastError) {
        throw lastError;
      }
      throw new Error('NATS JWT request failed without a response');
    };

    if (declaredAuthMode === 'jwt') {
      const payload = await profileBrowserSpan(
        HOST_PROFILE_SCOPE,
        'natsAuth.declared',
        async () => fetchNatsAuthPayload(),
        { authMode: declaredAuthMode },
      );
      if (!payload.jwt || !payload.seed) {
        throw new Error('Declared NATS authMode "jwt" but /api/nats-jwt did not return jwt+seed');
      }
      cachedJwt = { jwt: payload.jwt, seed: payload.seed };
      jwtProvider = async () => {
        if (cachedJwt) {
          const next = cachedJwt;
          cachedJwt = null;
          return next;
        }
        const refreshed = await fetchNatsAuthPayload();
        if (!refreshed.jwt || !refreshed.seed) {
          throw new Error('Declared NATS authMode "jwt" but refresh did not return jwt+seed');
        }
        return { jwt: refreshed.jwt, seed: refreshed.seed };
      };
    } else if (declaredAuthMode === 'static') {
      const payload = await profileBrowserSpan(
        HOST_PROFILE_SCOPE,
        'natsAuth.declared',
        async () => fetchNatsAuthPayload(),
        { authMode: declaredAuthMode },
      );
      if (payload.mode !== 'static' || !payload.user || !payload.pass) {
        throw new Error('Declared NATS authMode "static" but /api/nats-jwt did not return user/pass');
      }
      this.dataset.natsUser = payload.user;
      this.dataset.natsPass = payload.pass;
    } else if (declaredAuthMode === 'anonymous') {
      // No extra auth bootstrap required.
    } else {
      try {
        const initial = await profileBrowserSpan(
          HOST_PROFILE_SCOPE,
          'natsJwt.bootstrap',
          async () => fetchJwtCredentials(),
          { authMode: declaredAuthMode ?? 'auto' },
        );
        if (initial) {
          cachedJwt = initial;
          jwtProvider = async () => {
            if (cachedJwt) {
              const next = cachedJwt;
              cachedJwt = null;
              return next;
            }
            const refreshed = await fetchJwtCredentials();
            if (!refreshed) {
              throw new Error('NATS JWT refresh unavailable: operator mode no longer configured');
            }
            return refreshed;
          };
        }
      } catch (error) {
        throw new Error(`NATS JWT bootstrap failed: ${error instanceof Error ? error.message : String(error)}`);
      }
      if (!jwtProvider) {
        // eslint-disable-next-line no-console -- browser bootstrap, not an actor
        console.info('[MatrixDSLHost] NATS JWT unavailable — connecting with configured non-JWT transport');
      }
    }

    if (declaredAuthMode === 'anonymous') {
      // eslint-disable-next-line no-console -- browser bootstrap, not an actor
      console.info('[MatrixDSLHost] NATS auth plan → anonymous');
    } else if (declaredAuthMode === 'static') {
      // eslint-disable-next-line no-console -- browser bootstrap, not an actor
      console.info('[MatrixDSLHost] NATS auth plan → static credentials via /api/nats-jwt');
    } else if (declaredAuthMode === 'jwt') {
      // eslint-disable-next-line no-console -- browser bootstrap, not an actor
      console.info('[MatrixDSLHost] NATS auth plan → JWT via /api/nats-jwt');
    } else if (!jwtProvider) {
      // eslint-disable-next-line no-console -- browser bootstrap, not an actor
      console.info('[MatrixDSLHost] NATS operator mode not available — connecting without JWT auth');
    }

    const connectBackbone = async () => createBrowserNatsTransport({
      root: tabRoot,
      wsUrl,
      token: this.dataset.natsToken,
      user: this.dataset.natsUser,
      pass: this.dataset.natsPass,
      jwtProvider,
    });

    const shouldRetryJwtReadiness = (error: unknown): boolean => {
      const message = error instanceof Error ? error.message : String(error);
      return declaredAuthMode === 'jwt'
        && Boolean(jwtProvider)
        && /Authorization Violation|authentication violation/i.test(message);
    };

    let rawAdapter: Awaited<ReturnType<typeof connectBackbone>> | null = null;
    let lastConnectError: unknown = null;
    for (let attempt = 0; attempt < 4; attempt++) {
      try {
        rawAdapter = await profileBrowserSpan(
          HOST_PROFILE_SCOPE,
          'nats.connect',
          async () => connectBackbone(),
          {
            root: tabRoot,
            authMode: declaredAuthMode ?? 'auto',
            attempt: attempt + 1,
          },
        );
        lastConnectError = null;
        break;
      } catch (error) {
        lastConnectError = error;
        if (!shouldRetryJwtReadiness(error) || attempt === 3) {
          throw error;
        }
        // eslint-disable-next-line no-console -- browser bootstrap, not an actor
        console.warn(`[MatrixDSLHost] NATS JWT account not ready yet; retrying backbone connect (${attempt + 2}/4)...`);
        await new Promise((resolve) => setTimeout(resolve, 250 * (attempt + 1)));
      }
    }
    if (!this._rawAdapter && lastConnectError) {
      throw lastConnectError;
    }
    if (!rawAdapter) {
      throw new Error('NATS backbone connection failed before an adapter was created');
    }
    this._rawAdapter = rawAdapter;
    this._transport = this._rawAdapter;
    this.dataset.status = 'connected';
    // eslint-disable-next-line no-console -- browser bootstrap, not an actor
    console.info(`[MatrixDSLHost] NATS backbone connected: ${wsUrl} (${tabRoot})`);

    if (this._wrapTransport && this._transport) {
      this._transport = this._wrapTransport(this._transport);
    }

    this._runtime = new MatrixRuntime({
      transport: this._transport ?? undefined,
      domStrategy: new BrowserDomStrategy(),
    });
    const rootCtx = this._runtime.getRootContext!();
    this._context = mountPath ? rootCtx.derive(mountPath) : rootCtx;
    await this._applyHostedWebappMetadata();
    this._routingPeer = this._createTransportRoutingPeer(tabRoot);
  }

  private _deriveHostedAppName(): string | null {
    const routeKeyRoute = this._parseRouteKeyWebappRouteFromLocation();
    if (routeKeyRoute) {
      return routeKeyRoute.appName;
    }
    const pathname = typeof window !== 'undefined' && typeof window.location?.pathname === 'string'
      ? window.location.pathname
      : '';
    const match = /^\/apps\/([^/]+)/.exec(pathname);
    const rawAppName = match?.[1];
    if (!rawAppName) return null;
    try {
      const decoded = decodeURIComponent(rawAppName).trim();
      return decoded.length > 0 ? decoded : null;
    } catch {
      return null;
    }
  }

  private _parseRouteKeyWebappRouteFromLocation(): IRouteKeyWebappRoute | null {
    const pathname = typeof window !== 'undefined' && typeof window.location?.pathname === 'string'
      ? window.location.pathname
      : '';
    if (!pathname.startsWith('/')) {
      return null;
    }
    const withoutLeadingSlash = pathname.slice(1);
    const firstSlash = withoutLeadingSlash.indexOf('/');
    if (firstSlash <= 0) {
      return null;
    }
    let routeKey: string;
    try {
      routeKey = decodeURIComponent(withoutLeadingSlash.slice(0, firstSlash)).trim().toLowerCase();
    } catch {
      return null;
    }
    if (!isValidRouteKey(routeKey)) {
      return null;
    }
    const afterRouteKey = withoutLeadingSlash.slice(firstSlash + 1);
    const appPath = afterRouteKey.startsWith('apps/')
      ? afterRouteKey.slice('apps/'.length)
      : afterRouteKey;
    const appSlash = appPath.indexOf('/');
    const rawAppName = appSlash === -1 ? appPath : appPath.slice(0, appSlash);
    let appName: string;
    try {
      appName = decodeURIComponent(rawAppName).trim();
    } catch {
      return null;
    }
    if (!/^[A-Za-z0-9._-]+$/.test(appName) || appName === 'web') {
      return null;
    }
    return {
      appName,
      routeKey,
    };
  }

  private async _applyHostedWebappMetadata(): Promise<void> {
    if (!this._context) return;

    const appName = this._deriveHostedAppName();
    if (!appName) return;
    if (appName === 'web') return;
    if (this._parseRouteKeyWebappRouteFromLocation()) {
      return;
    }
    const assetHostRoot = (this.dataset.assetHostRoot ?? '').trim();
    const selectedAuthorityRoot = (this.dataset.selectedAuthorityRoot ?? '').trim();
    const platformServiceRoot = (this.dataset.platformServiceRoot ?? '').trim();
    const isPlatformAdmin = this.dataset.isPlatformAdmin === 'true';
    if (platformServiceRoot && selectedAuthorityRoot === platformServiceRoot && !isPlatformAdmin) {
      return;
    }
    if (assetHostRoot && selectedAuthorityRoot && assetHostRoot !== selectedAuthorityRoot && !isPlatformAdmin) {
      return;
    }

    const entry = await this._loadHostedWebappRegistryEntry(appName);
    const metadataRecord = registryRecord(entry.metadata);
    const artifact = registryArtifact(metadataRecord.artifact);
    const packageName = registryString(entry.placement.packageRef) ?? registryString(entry.placement.packageId);
    const packageVersion = registryString(metadataRecord.packageVersion);
    const sourceKind = registrySourceKind(metadataRecord.sourceKind)
      ?? (registryString(metadataRecord.origin) ? 'external-webapp' : 'installed-webapp');
    const registrationSource = registryRegistrationSource(metadataRecord.registrationSource);
    const deploymentInstanceId = registryString(entry.placement.deploymentInstanceId) ?? registryString(entry.placement.runtimeId);
    const distPath = registryString(metadataRecord.distPath);
    const entryFile = registryString(metadataRecord.entryFile);
    const buildGitSha = registryString(artifact.gitSha);
    const artifactBuiltAt = registryString(artifact.builtAt);
    const artifactSignature = registryString(artifact.signature);
    const artifactFreshness = registryArtifactFreshness(artifact.freshness);
    const artifactFreshnessReason = registryString(artifact.reason);
    const metadata: IComponentRuntimeMetadata = {
      versionSource: packageVersion ? 'webapp-registry' : 'undeclared',
      sourceKind,
      appName,
      ...(packageName ? { packageName } : {}),
      ...(packageVersion ? { version: packageVersion } : {}),
      ...(registrationSource ? { registrationSource } : {}),
      ...(deploymentInstanceId ? { deploymentInstanceId } : {}),
      ...(distPath ? { distPath } : {}),
      ...(entryFile ? { entryFile } : {}),
      ...(buildGitSha ? { buildGitSha } : {}),
      ...(artifactBuiltAt ? { artifactBuiltAt } : {}),
      ...(artifactSignature ? { artifactSignature } : {}),
      ...(artifactFreshness ? { artifactFreshness } : {}),
      ...(artifactFreshnessReason ? { artifactFreshnessReason } : {}),
    };

    if (metadata.artifactFreshness && metadata.artifactFreshness !== 'current') {
      // eslint-disable-next-line no-console -- browser bootstrap visibility
      console.warn(
        `[MatrixDSLHost] Hosted webapp artifact for "${appName}" is ${metadata.artifactFreshness}: ${metadata.artifactFreshnessReason ?? 'no reason provided'}`
      );
    }

    const contextual = this._context as IMatrixContext & {
      setService?: (key: string | symbol, service: unknown) => void;
    };
    contextual.setService?.(COMPONENT_RUNTIME_METADATA, metadata);
  }

  private async _loadHostedWebappRegistryEntry(appName: string): Promise<ServiceRegistryEntryV1> {
    if (!this._context) {
      throw new Error(`system.registry lookup for hosted app '${appName}' requires a Matrix context`);
    }
    const namespaceRoot = this._hostedWebappRegistryNamespaceRoot();
    const response = await RequestReply.execute<Record<string, unknown>, IRegistryQueryResponse>(
      this._context,
      `${namespaceRoot}/system.registry`,
      'registry.query',
      {
        namespaceRoot,
        mount: appName,
        kind: 'app',
        openable: true,
      },
      { timeoutMs: 5000 },
    );
    const entries = Array.isArray(response.entries) ? response.entries : [];
    const entry = entries
      .map((candidate) => serviceRegistryEntry(candidate))
      .find((candidate) => candidate !== null
        && candidate.kind === 'app'
        && candidate.app?.openable === true
        && candidate.mount === appName);
    if (!entry) {
      throw new Error(`app '${appName}' not registered by ${namespaceRoot}/system.registry`);
    }
    return entry;
  }

  private _hostedWebappRegistryNamespaceRoot(): string {
    const assetHostRoot = (this.dataset.assetHostRoot ?? '').trim();
    if (assetHostRoot) {
      return assetHostRoot;
    }
    const busRoot = (this.getAttribute('bus-root') ?? '').trim();
    if (!busRoot) {
      throw new Error('Hosted webapp registry lookup requires assetHostRoot from /api/bootstrap');
    }
    return busRoot;
  }

  /**
   * ROOT LOCAL MODE: FederationPeer without backbone (local pub/sub only).
   */
  private _bootstrapRootLocal(busRootInput: string, mountPath: string): void {
    const baseRoot = busRootInput.toLowerCase().trim();

    // Create browser router (FederationPeer in local-only mode)
    const result: BrowserRouterResult = getBrowserRouter({ baseRealm: baseRoot });
    this._peer = result.router;
    this._routingPeer = result.router;
    this._rawAdapter = browserRouterTransportAdapter(result.adapter, result.router);
    this._transport = this._rawAdapter;

    // Apply transport wrapper if provided
    if (this._wrapTransport) {
      this._transport = this._wrapTransport(this._transport);
    }

    // Create runtime with federation adapter
    this._runtime = new MatrixRuntime({
      transport: this._transport,
      domStrategy: new BrowserDomStrategy(),
    });
    const rootCtx = this._runtime.getRootContext!();
    this._context = mountPath ? rootCtx.derive(mountPath) : rootCtx;
  }

  private _createTransportRoutingPeer(localRoot: string): IHostRoutingPeer {
    return {
      hasBackbone: true,
      localRoot,
      localRealm: localRoot,
      invoke: async <T>(
        target: string,
        opOrRequest: string | { op: string; payload?: unknown },
        payloadOrTimeout?: unknown,
        timeoutMs?: number,
      ): Promise<T> => {
        if (!this._context) {
          throw new Error('MatrixDSLHost transport router is not initialized');
        }

        if (typeof opOrRequest === 'string') {
          const op = opOrRequest;
          const payload = payloadOrTimeout;
          return await RequestReply.execute<unknown, T>(this._context, target, op, payload, {
            timeoutMs,
          });
        }

        const op = opOrRequest.op;
        const payload = opOrRequest.payload;
        const resolvedTimeoutMs = typeof payloadOrTimeout === 'number' ? payloadOrTimeout : timeoutMs;
        return await RequestReply.execute<unknown, T>(this._context, target, op, payload, {
          timeoutMs: resolvedTimeoutMs,
        });
      },
      route: async (topic: string, payload: unknown): Promise<void> => {
        if (!this._transport) {
          throw new Error('MatrixDSLHost transport router is not initialized');
        }
        this._transport.publish(topic, payload);
      },
    };
  }

  /**
   * LOCAL MODE: Plain in-memory transport, no federation overhead.
   */
  private _bootstrapLocal(mountPath: string): void {
    // No federation — just in-memory broker + transport
    this._runtime = new MatrixRuntime({
      domStrategy: new BrowserDomStrategy(),
    });
    const rootCtx = this._runtime.getRootContext!();
    this._context = mountPath ? rootCtx.derive(mountPath) : rootCtx;
  }

  // ═══════════════════════════════════════════════════════════════════════════
  // $join Responder
  // ═══════════════════════════════════════════════════════════════════════════

  /**
   * Subscribe to this host's $inbox to respond to $join from children.
   *
   * When children call _receiveContext(derivedCtx), they send $join to
   * parent.mount/$inbox. This responder acks them so they don't timeout.
   */
  private _installJoinResponder(): void {
    if (!this._context) return;

    const hostMount = this._context.mount;
    const hostInbox = TopicRouter.inbox(hostMount);

    this._joinUnsub = this._context.transport.subscribe(
      hostInbox,
      (rawPayload: unknown) => {
        const envelope = rawPayload as MxEnvelope;
        if (!envelope || envelope.op !== '$join') return;

        const joinPayload = envelope.payload as { id?: string; mount?: string } | undefined;
        const childMount = joinPayload?.mount;
        if (!childMount) return;

        const childInbox = TopicRouter.inbox(childMount);
        this._context!.transport.publish(childInbox, {
          op: '$join_ack',
          payload: { status: 'ok', supervisor: hostMount },
        });
      },
    );
  }

  // ═══════════════════════════════════════════════════════════════════════════
  // Child Mounting
  // ═══════════════════════════════════════════════════════════════════════════

  /**
   * Mount all light DOM children that are custom elements.
   * Uses explicit _receiveContext() — NOT AUTO-PULL (because this host
   * is not a MatrixActorHtmlElement and won't be found by _findParentShell).
   */
  private async _mountChildren(): Promise<void> {
    if (!this._context) return;

    const mountPromises: Promise<void>[] = [];
    for (const child of Array.from(this.children)) {
      if (!(child instanceof HTMLElement)) continue;
      mountPromises.push(this._mountChild(child));
    }
    await Promise.all(mountPromises);
  }

  /**
   * Mount a single child element with a derived context.
   */
  private async _mountChild(element: HTMLElement): Promise<void> {
    if (!this._context) return;

    const tagName = element.tagName.toLowerCase();

    // Skip non-custom elements (no hyphen = not a CE)
    if (!tagName.includes('-')) return;
    // Skip script/style
    if (tagName === 'script' || tagName === 'style') return;

    // Wait for custom element definition (handles script loading order)
    await customElements.whenDefined(tagName);

    // Derive child ID from name, id, or tag
    const childId = (
      element.getAttribute('name') ||
      element.id ||
      tagName
    ).toLowerCase();

    const childContext = this._context.derive(childId);

    const shell = matrixChildElementHooks(element);

    if (typeof shell._receiveContext === 'function') {
      await shell._receiveContext(childContext);
    } else if (typeof shell.mount === 'function') {
      await shell.mount(childContext);
    } else if (typeof shell.setContext === 'function') {
      shell.setContext(childContext);
    }
    // Plain HTML elements without Matrix interface are silently skipped
  }

  private _browserRuntimeInventory(runtimeId: string, contextMount: string, hostBootstrapMode: boolean): IBrowserRuntimeInventoryEntry[] {
    const inventory: IBrowserRuntimeInventoryEntry[] = [];
    const runtimeMount = `system.runtimes.${runtimeId}`;
    inventory.push({
      mount: runtimeMount,
      type: 'BrowserRuntimeControlActor',
      surface: 'runtime',
      runtimeId,
      claimKind: 'local-only',
      description: 'Browser runtime actor for this tab.',
      hasChildren: true,
    });
    for (const child of Array.from(this.children)) {
      if (!(child instanceof HTMLElement)) continue;
      const tag = child.tagName.toLowerCase();
      if (!tag.includes('-')) continue;
      const name = child.getAttribute('name') || child.getAttribute('id') || tag;
      const localMount = hostBootstrapMode && contextMount
        ? `${contextMount}.${name}`
        : name;
      inventory.push({
        mount: localMount,
        type: child.constructor.name !== 'HTMLElement' ? child.constructor.name : tag,
        surface: 'dom',
        runtimeId,
        claimKind: 'local-only',
        hasChildren: true,
      });
    }
    return inventory;
  }

  private async _ensureBrowserRuntimeControl(
    runtimeId: string,
    runtimeMount: string,
    controlMount: string,
  ): Promise<void> {
    if (!(this._runtime instanceof MatrixRuntime)) {
      return;
    }
    if (!this._runtimeControlStartedAt) {
      this._runtimeControlStartedAt = new Date().toISOString();
    }
    await mountBrowserRuntimeControl({
      runtime: this._runtime,
      runtimeId,
      runtimeMount,
      controlMount,
      startedAt: this._runtimeControlStartedAt,
      getState: (): BrowserRuntimeLifecycleState => this._initialized ? 'live' : 'closing',
      getInventory: () => this._browserRuntimeInventory(
        runtimeId,
        this._context?.mount ?? '',
        this._isHostBootstrapMode(),
      ),
    });
  }

  private _runtimeInventoryVersionForHost(): number {
    let version = 0;
    for (const child of Array.from(this.children)) {
      if (!(child instanceof HTMLElement)) continue;
      const shell = matrixActorElementVersionSource(child);
      const childVersion = shell._actor?.children?.version;
      if (typeof childVersion === 'number' && Number.isFinite(childVersion)) {
        version += childVersion;
      }
    }
    return version;
  }

  private _scheduleRuntimeInventoryRefresh(): void {
    if (!this._browserRuntimeRegistryState) {
      return;
    }
    if (this._runtimeInventoryClaimRefreshTimer) {
      clearTimeout(this._runtimeInventoryClaimRefreshTimer);
    }
    this._runtimeInventoryClaimRefreshTimer = setTimeout(() => {
      this._runtimeInventoryClaimRefreshTimer = null;
      void this._refreshRuntimeInventory();
    }, 250);
  }

  private async _refreshRuntimeInventory(): Promise<void> {
    const state = this._browserRuntimeRegistryState;
    if (!this._context || !state) {
      return;
    }
    const inventory = this._browserRuntimeInventory(
      state.runtimeId,
      state.contextMount,
      state.hostBootstrapMode,
    );
    const inventoryVersion = this._runtimeInventoryVersionForHost();
    try {
      this._runtimeInventoryVersion = inventoryVersion;
      await this._replaceBrowserRuntimeClaims(state, inventory, inventoryVersion);
    } catch {
      // Registry lease renewal keeps liveness; the next DOM mutation retries inventory claims.
    }
  }

  // ═══════════════════════════════════════════════════════════════════════════
  // Root Context
  // ═══════════════════════════════════════════════════════════════════════════

  /**
   * Parse root and federation attributes into RootContext.
   */
  private _parseRootAttributes(): void {
    const rawRoot = this.getAttribute('bus-root');
    if (!rawRoot) return;

    const baseRoot = rawRoot.toLowerCase().trim();
    if (!isValidRealm(baseRoot)) {
      // eslint-disable-next-line no-console -- browser bootstrap, not an actor
      console.error(`[MatrixDSLHost] Invalid root: "${rawRoot}"`);
      return;
    }

    const rawFederation = this.getAttribute('federation') || 'auto';
    const federation = rawFederation.toLowerCase().trim() as FederationMode;
    const validModes: FederationMode[] = ['auto', 'local', 'public', 'disabled'];
    if (!validModes.includes(federation)) {
      // eslint-disable-next-line no-console -- browser bootstrap, not an actor
      console.error(`[MatrixDSLHost] Invalid federation mode: "${rawFederation}"`);
      return;
    }

    let tabRoot: string | undefined;
    if (federation !== 'disabled') {
      tabRoot = getOrCreateTabRealm(baseRoot);
    }

    this._rootContext = createRootContext(baseRoot, federation, tabRoot);
  }

  /**
   * Propagate RootContext to child elements that support it.
   */
  private _propagateRootToChildren(): void {
    const rootContext = this._rootContext;
    if (!rootContext) return;

    const children = this.querySelectorAll('*');
    children.forEach((child: Element) => {
      const contextReceiver = matrixRootContextReceiver(child);
      if (typeof contextReceiver._receiveContext === 'function') {
        // Only propagate root context (not a full IMatrixContext)
        // MatrixActorHtmlElement._receiveContext handles this special case
        contextReceiver._receiveContext({ rootContext, realmContext: rootContext });
      }
    });
  }

  // ═══════════════════════════════════════════════════════════════════════════
  // Mutation Observation
  // ═══════════════════════════════════════════════════════════════════════════

  private _setupMutationObserver(): void {
    this._observer = new MutationObserver(mutations => {
      for (const mutation of mutations) {
        if (mutation.type === 'childList') {
          for (const node of Array.from(mutation.addedNodes)) {
            if (node instanceof HTMLElement) {
              void this._mountChild(node).then(() => this._scheduleRuntimeInventoryRefresh());
            }
          }
          if (mutation.removedNodes.length > 0) {
            this._scheduleRuntimeInventoryRefresh();
          }
        }
      }
    });
    this._observer.observe(this, { childList: true });
  }

  // ═══════════════════════════════════════════════════════════════════════════
  // Loading Element Management
  // ═══════════════════════════════════════════════════════════════════════════

  /**
   * Manage a sibling loading element and this host's visibility.
   * Looks for element with id from `loading-el` attribute, or `#loading`.
   */
  private _manageLoadingElement(status: string, error?: unknown): void {
    const loadingId = this.getAttribute('loading-el') || 'loading';
    const loadingEl = document.getElementById(loadingId);

    if (status === 'initializing') {
      if (loadingEl) loadingEl.style.display = '';
      if (this._splashShownAt === null) {
        this._splashShownAt = performance.now();
      }
      this.style.display = 'none';
    } else if (status === 'connected' || status === 'local' || status === 'login-required') {
      this._scheduleSplashHide(loadingEl);
      this.style.display = '';
    } else if (status === 'disconnected') {
      // Show app in offline mode — UI loads, just no backbone
      this._scheduleSplashHide(loadingEl);
      this.style.display = '';
    } else if (status === 'error') {
      this.style.display = 'none';
      if (loadingEl) {
        const root = this.getAttribute('bus-root') ?? '(not set)';
        const backbone = this.getAttribute('backbone') || '(none)';
        const errMsg = error instanceof Error ? error.message : String(error);
        const esc = (s: string) => s.replace(/</g, '&lt;').replace(/>/g, '&gt;');
        loadingEl.outerHTML = `
          <div style="max-width: 700px; margin: 40px auto; padding: 20px; background: #ffebee; border: 1px solid #f44336; border-radius: 8px; font-family: monospace; color: #c62828;">
            <strong style="font-size: 16px;">Bootstrap Failed</strong>
            <pre style="background: #fff0f0; padding: 12px; border-radius: 4px; overflow-x: auto; margin: 12px 0;">${esc(errMsg)}</pre>
            <table style="width: 100%; border-collapse: collapse; font-size: 13px;">
              <tr><td style="padding: 4px 8px; color: #666;">Root</td><td style="padding: 4px 8px;">${esc(root)}</td></tr>
              <tr><td style="padding: 4px 8px; color: #666;">Backbone</td><td style="padding: 4px 8px;">${esc(backbone)}</td></tr>
              <tr><td style="padding: 4px 8px; color: #666;">Status</td><td style="padding: 4px 8px;">${this._peer?.hasBackbone ? 'connected' : 'not connected'}</td></tr>
            </table>
          </div>`;
      }
    }
  }

  /**
   * Hide the splash with a minimum-visible-time guard and a fade-out.
   *
   * Bootstrap can complete in <100ms on a warm cache, which makes the splash
   * appear and disappear in a single frame — users perceive a flash rather
   * than a brand frame. We enforce a 700ms minimum visible time and fade the
   * last 200ms via opacity so the dismissal reads as intentional. The
   * `splash-min-ms` attribute on `<matrix-dsl-host>` overrides the default;
   * `splash-min-ms="0"` restores the original instant-hide behavior.
   */
  private _scheduleSplashHide(loadingEl: HTMLElement | null): void {
    if (!loadingEl || this._splashHideScheduled) return;
    this._splashHideScheduled = true;

    const minMs = (() => {
      const raw = this.getAttribute('splash-min-ms');
      if (raw === null) return 700;
      const n = Number.parseInt(raw, 10);
      return Number.isFinite(n) && n >= 0 ? n : 700;
    })();
    const fadeMs = Math.min(200, Math.floor(minMs / 3));
    const shownAt = this._splashShownAt ?? performance.now();
    const elapsed = performance.now() - shownAt;
    const remaining = Math.max(0, minMs - elapsed - fadeMs);

    const startFade = () => {
      loadingEl.style.transition = `opacity ${fadeMs}ms ease-out`;
      loadingEl.style.opacity = '0';
      window.setTimeout(() => {
        loadingEl.style.display = 'none';
        loadingEl.style.opacity = '';
        loadingEl.style.transition = '';
      }, fadeMs);
    };

    if (remaining > 0) {
      window.setTimeout(startFade, remaining);
    } else {
      startFade();
    }
  }

  private _redirectToDeviceLogin(): void {
    if (this.dataset.loginRedirectStarted === 'true') {
      return;
    }
    this.dataset.loginRedirectStarted = 'true';
    const startUrl = this.dataset.loginStartUrl || '/_auth/device-session/start';
    const loginUrl = new URL(startUrl, window.location.origin);
    loginUrl.searchParams.set('returnTo', `${window.location.pathname}${window.location.search}${window.location.hash}`);
    window.location.assign(loginUrl.toString());
  }

  private _shouldRedirectToDeviceLogin(hostedAppName: string | null): boolean {
    const normalizedAppName = hostedAppName?.trim().toLowerCase() ?? '';
    return normalizedAppName === 'edge';
  }

  private _redirectToPlatformLogin(): void {
    if (this.dataset.loginRedirectStarted === 'true') {
      return;
    }
    this.dataset.loginRedirectStarted = 'true';
    const returnTo = `${window.location.pathname}${window.location.search}${window.location.hash}`;
    const loginUrl = new URL('/apps/web/', window.location.origin);
    loginUrl.hash = `login?redirect=${encodeURIComponent(returnTo)}`;
    window.location.assign(loginUrl.toString());
  }

  // ═══════════════════════════════════════════════════════════════════════════
  // Events
  // ═══════════════════════════════════════════════════════════════════════════

  private _fireReadyEvent(): void {
    this.dispatchEvent(new CustomEvent('matrix-dsl-ready', {
      bubbles: true,
      detail: {
        peer: this._peer,
        runtime: this._runtime,
        context: this._context,
        root: this.getAttribute('bus-root'),
        realm: this.getAttribute('bus-root'),
        backbone: this.getAttribute('backbone'),
        hasBackbone: this._peer?.hasBackbone ?? false,
        status: this.dataset.status,
      },
    }));
  }

  /**
   * Async runtime registry discovery — fires after full bootstrap (children already mounted).
   *
   * Confirms the runtime registry actor is reachable, then publishes readiness on the root
   * $events topic so child apps receive it through their transport subscriptions.
   * No DOM events — pure transport pub/sub so timing is deterministic.
   *
   * Publishes:
   *   { op: 'daemonReady', payload: { root } }            — on success
   *   { op: 'daemonError', payload: { root, error } }    — on failure
   *   { op: 'daemonReady', payload: { root: '', skipped: true } } — no explicit runtime target set
   */
  private async _discoverDaemon(): Promise<void> {
    if (!this._context || !this._runtime) return;
    const rootCtx = this._runtime.getRootContext!();
    const rootEventsTopic = TopicRouter.events('');
    const daemonRoot = this.getAttribute('daemon-root') ?? this.getAttribute('daemon-realm');

    if (this._isHostBootstrapMode() || this._isHostServiceBootstrap()) {
      const hostRoot = daemonRoot || this.getAttribute('bus-root') || '';
      if (!hostRoot) {
        this.dataset.daemonStatus = 'skipped';
        rootCtx.transport.publish(rootEventsTopic, {
          op: 'daemonReady',
          payload: { root: '', realm: '', skipped: true, hostMode: true },
        });
        return;
      }

      this.dataset.daemonStatus = 'connected';
      rootCtx.transport.publish(rootEventsTopic, {
        op: 'daemonReady',
        payload: { root: hostRoot, realm: hostRoot, hostMode: true },
      });
      rootCtx.transport.publish(rootEventsTopic, {
        op: 'hostReady',
        payload: { root: hostRoot },
      });
      void this._registerWithRuntimeRegistry(hostRoot);
      return;
    }

    if (!daemonRoot) {
      // No explicit runtime target configured — signal immediately so children enable without waiting
      this.dataset.daemonStatus = 'skipped';
      rootCtx.transport.publish(rootEventsTopic, {
        op: 'daemonReady',
        payload: { root: '', realm: '', skipped: true },
      });
      return;
    }

    if (this._daemonDiscoveryInFlight) {
      return;
    }

    const controlPlaneRoot = this._controlPlaneRootForSingletons(daemonRoot);
    const runtimeRoot = transportRootForContext(this._context) ?? '(unknown)';
    const natsWsUrl = this.getAttribute('nats-ws-url') ?? this.getAttribute('backbone') ?? '(none)';
    // First attempt uses a shorter timeout (500ms) — if the registry is ready,
    // it responds in <10ms. If it's still loading, we fail fast and retry
    // rather than wasting 2.5s on the first attempt.
    const firstAttemptTimeoutMs = 500;
    const attemptTimeoutMs = 2_500;
    const retryDelaysMs = [100, 250, 500, 1_000, 2_000] as const;
    const finishDiscoveryProfile = createBrowserProfileSpan(HOST_PROFILE_SCOPE, 'daemonDiscovery', {
      daemonRoot: daemonRoot ?? '',
      controlPlaneRoot,
      runtimeRoot,
    });
    // eslint-disable-next-line no-console -- browser bootstrap, not an actor
    console.info(`[MatrixDSLHost] runtime registry discovery: targetRoot="${controlPlaneRoot}", authorityRoot="${daemonRoot}", runtimeRoot="${runtimeRoot}", natsWsUrl="${natsWsUrl}"`);

    const runtimeRegistryTarget = this._runtimeRegistryTargetForRoot(controlPlaneRoot);
    const discoveryTargets: Array<{
      readonly target: string;
      readonly kind: 'runtime-registry';
    }> = [{ target: runtimeRegistryTarget, kind: 'runtime-registry' }];
    const discoveryOp = '$ping';
    let lastError = 'Unknown error';
    this._daemonDiscoveryInFlight = true;
    this._stopDaemonDiscoveryRetry();

    try {
      for (let attempt = 0; attempt <= retryDelaysMs.length; attempt += 1) {
        let attemptSucceeded = false;
        for (const discoveryTarget of discoveryTargets) {
          try {
            // eslint-disable-next-line no-console -- browser bootstrap, not an actor
            console.info(
              `[MatrixDSLHost] Sending ${discoveryOp} to "${discoveryTarget.target}" ` +
              `(attempt ${attempt + 1}/${retryDelaysMs.length + 1}, timeout ${attemptTimeoutMs}ms)...`,
            );
            await RequestReply.execute<Record<string, unknown>, unknown>(
              this._context,
              discoveryTarget.target,
              discoveryOp,
              {},
              { timeoutMs: attempt === 0 ? firstAttemptTimeoutMs : attemptTimeoutMs },
            );

            this.dataset.daemonStatus = 'connected';
            this._daemonDiscoveryRetryDelayMs = 1_000;
            // eslint-disable-next-line no-console -- browser bootstrap, not an actor
            console.info(
              `[MatrixDSLHost] ${discoveryOp} success — system.runtimes at "${controlPlaneRoot}" is reachable`,
            );

            rootCtx.transport.publish(rootEventsTopic, {
              op: 'daemonReady',
              payload: {
                root: daemonRoot,
                realm: daemonRoot,
                authorityRuntime: true,
                registryTarget: runtimeRegistryTarget,
              },
            });

            // Register this browser tab as a runtime in the namespace registry.
            void this._registerWithRuntimeRegistry(controlPlaneRoot);
            finishDiscoveryProfile({
              result: 'connected',
              attempts: attempt + 1,
              targetKind: discoveryTarget.kind,
            });
            attemptSucceeded = true;
            return;
          } catch (err) {
            lastError = err instanceof Error ? err.message : String(err);
            // eslint-disable-next-line no-console -- browser bootstrap, not an actor
            console.warn(
              `[MatrixDSLHost] Host Service runtime discovery failed at "${discoveryTarget.target}": ${lastError}.`,
            );
          }
        }

        if (!attemptSucceeded) {
          const retryDelayMs = retryDelaysMs[attempt];
          if (retryDelayMs === undefined) break;
          // eslint-disable-next-line no-console -- browser bootstrap, not an actor
          console.warn(
            `[MatrixDSLHost] Runtime registry discovery attempt ${attempt + 1}/${retryDelaysMs.length + 1} failed: ` +
            `${lastError}. Retrying in ${retryDelayMs}ms...`,
          );
          await new Promise<void>((resolve) => setTimeout(resolve, retryDelayMs));
        }
      }

      const backgroundRetryDelayMs = this._daemonDiscoveryRetryDelayMs;
      this._daemonDiscoveryRetryDelayMs = Math.min(this._daemonDiscoveryRetryDelayMs * 2, 10_000);
      this.dataset.daemonStatus = 'retrying';
      // eslint-disable-next-line no-console -- browser bootstrap, not an actor
      console.warn(
        `[MatrixDSLHost] Runtime registry discovery failed: root="${controlPlaneRoot}", authorityRoot="${daemonRoot}", runtimeRoot="${runtimeRoot}", ` +
        `natsWsUrl="${natsWsUrl}", error="${lastError}". Background retry in ${backgroundRetryDelayMs}ms.`,
      );
      rootCtx.transport.publish(rootEventsTopic, {
        op: 'daemonError',
        payload: {
          root: daemonRoot,
          realm: daemonRoot,
          error: lastError,
          retryInMs: backgroundRetryDelayMs,
        },
      });
      this._scheduleDaemonDiscoveryRetry(backgroundRetryDelayMs);
      finishDiscoveryProfile({
        result: 'retrying',
        retryInMs: backgroundRetryDelayMs,
      });
    } finally {
      this._daemonDiscoveryInFlight = false;
    }
  }

  /**
   * Claim this browser tab's runtime and mounted child actors in system.registry.
   */
  private async _registerWithRuntimeRegistry(controlPlaneRoot: string): Promise<void> {
    if (!this._context || !this._runtime) return;
    const registrationGeneration = this._lifecycleGeneration;
    const finishRegistrationProfile = createBrowserProfileSpan(HOST_PROFILE_SCOPE, 'runtimeRegistry.claim', {
      controlPlaneRoot,
    });

    if (!this.hasBackbone) {
      finishRegistrationProfile({
        result: 'skipped-no-backbone',
        controlPlaneRoot,
      });
      return;
    }

    if (this._shouldSkipBrowserRuntimeRegistryClaim(controlPlaneRoot)) {
      finishRegistrationProfile({
        result: 'skipped-no-registry-authority',
        controlPlaneRoot,
      });
      return;
    }

    const rootCtx = this._runtime.getRootContext?.();
    if (!rootCtx) {
      finishRegistrationProfile({ result: 'skipped-no-root-context' });
      return;
    }
    const hostBootstrapMode = this._isHostBootstrapMode();
    const contextMount = this._context.mount ?? '';
    const runtimeRoot = transportRootForContext(rootCtx) ?? '';
    const app = this.getAttribute('app-name') || document.title.split(/\s*[—–-]\s*/)[0]?.trim() || 'browser';
    const registryTarget = this._serviceRegistryTargetForRoot(controlPlaneRoot);
    const selectedAuthorityRoot = (this.dataset.selectedAuthorityRoot ?? '').trim();
    const sessionAuthorityRoot = (this.dataset.sessionAuthorityRoot ?? '').trim();
    const authorityRoot = selectedAuthorityRoot || sessionAuthorityRoot;
    const runtimeInstanceRoot = (this.dataset.runtimeInstanceRoot ?? '').trim() || runtimeRoot;
    const runtimeId = this.dataset.hostRuntimeId
      || this._runtimeIdFromMount(contextMount)
      || this._getOrCreateBrowserRuntimeId(authorityRoot || controlPlaneRoot || runtimeRoot, app);
    this.dataset.hostRuntimeId = runtimeId;
    const runtimeWireRoot = runtimeRoot || controlPlaneRoot;
    const runtimeMount = `system.runtimes.${runtimeId}`;
    const controlMount = runtimeMount;
    const contextIsRuntimeMount = contextMount === runtimeMount || contextMount.startsWith(`${runtimeMount}.`);
    const sessionMount = hostBootstrapMode
      ? contextIsRuntimeMount
        ? runtimeWireRoot || rootCtx.mount || 'unknown'
        : [runtimeWireRoot || controlPlaneRoot, contextMount].filter(Boolean).join('.')
      : runtimeRoot || rootCtx.mount || 'unknown';

    await this._ensureBrowserRuntimeControl(runtimeId, runtimeMount, controlMount);
    const inventory = this._browserRuntimeInventory(runtimeId, contextMount, hostBootstrapMode);

    // Strip namespace root from sessionMount to get relative prefix for claims
    const relativeMount = hostBootstrapMode && contextMount
      ? contextMount
      : sessionMount.startsWith(controlPlaneRoot + '.')
      ? sessionMount.slice(controlPlaneRoot.length + 1)
      : sessionMount;
    const runtimeHref = typeof globalThis.location?.href === 'string'
      ? globalThis.location.href
      : (typeof document !== 'undefined' && typeof document.baseURI === 'string' ? document.baseURI : '');
    const state: IBrowserRuntimeRegistryState = {
      registryTarget,
      namespaceRoot: controlPlaneRoot,
      runtimeId,
      runtimeRoot: runtimeWireRoot,
      app,
      contextMount,
      hostBootstrapMode,
      sessionMount,
      relativeMount,
      runtimeMount,
      controlMount,
      authorityRoot,
      sessionAuthorityRoot,
      selectedAuthorityRoot,
      runtimeInstanceRoot,
      runtimeHref,
      registeredAt: Date.now(),
    };

    try {
      this._runtimeInventoryVersion = this._runtimeInventoryVersionForHost();
      await this._replaceBrowserRuntimeClaims(state, inventory, this._runtimeInventoryVersion);
      // eslint-disable-next-line no-console -- browser bootstrap
      console.info(`[MatrixDSLHost] Claimed browser runtime "${runtimeId}" in system.registry`);
      if (registrationGeneration !== this._lifecycleGeneration || !this._context || !this._runtime) {
        finishRegistrationProfile({
          result: 'skipped-after-cleanup',
          runtimeId,
        });
        return;
      }
      this._browserRuntimeRegistryState = state;
      this._runtimeRegistryId = runtimeId;
      this._publishBrowserRuntimePresence(state, inventory, 'announce');
      finishRegistrationProfile({
        result: 'ok',
        runtimeId,
      });
    } catch (err) {
      // eslint-disable-next-line no-console -- browser bootstrap
      console.warn(`[MatrixDSLHost] Browser runtime registry claim failed (non-fatal):`, err);
      finishRegistrationProfile({
        result: 'error',
        error: err instanceof Error ? err.message : String(err),
      });
      return;
    }

    this._browserRuntimeRenewTimer = setInterval(() => {
      const currentState = this._browserRuntimeRegistryState;
      if (!currentState || !this._context) {
        return;
      }
      RequestReply.execute(
        this._context,
        currentState.registryTarget,
        'registry.claim.renew',
        {
          providerRuntimeId: currentState.runtimeId,
          ttlMs: 45_000,
          health: { status: 'ok' },
        },
        { timeoutMs: 5000 },
      ).catch(() => { /* lease renewal failure is non-fatal */ });
      this._publishBrowserRuntimePresence(
        currentState,
        this._browserRuntimeInventory(
          currentState.runtimeId,
          currentState.contextMount,
          currentState.hostBootstrapMode,
        ),
        'heartbeat',
      );
    }, 15_000);

    this._browserRuntimeReleaseHandler = () => {
      const context = this._context;
      const currentState = this._browserRuntimeRegistryState;
      if (!context || !currentState) return;
      try {
        RequestReply.sendToInbox(context, currentState.registryTarget, 'registry.release', {
          providerRuntimeId: currentState.runtimeId,
        });
      } catch {
        // Best-effort unload cleanup; the registry lease expires missed releases.
      }
      this._publishBrowserRuntimePresence(
        currentState,
        this._browserRuntimeInventory(
          currentState.runtimeId,
          currentState.contextMount,
          currentState.hostBootstrapMode,
        ),
        'departed',
      );
    };
    window.addEventListener('beforeunload', this._browserRuntimeReleaseHandler);
  }

  /**
   * Publish browser runtime presence to the runtime-directory authority
   * (`system.runtimes`). Browser tabs claim child actors in `system.registry`
   * via `registry.claim`, but `system.runtimes.runtimes.list` is fed by
   * runtime presence — without this call, browser tabs are invisible to
   * Director Topology, Host Ops Workloads, and any other consumer of the
   * runtime directory.
   *
   * We route through the explicit `runtimes.presence.update` op via
   * `RequestReply.execute("${controlPlaneRoot}/system.runtimes", ...)`, NOT through
   * `publishRuntimePresence(ctx, record, event)`. The pub/sub path uses bare
   * `$runtime.*` topics on the local transport — in federated HiveCast mode
   * the tab realm is a synthetic per-tab root (`s-b-root-*`) so the publish
   * lands on a NATS subject prefix the `RuntimeManagerActor` at the
   * authority root never subscribes to. Routed RequestReply.execute uses
   * the same federation-peer cross-routing that `registry.claim` already
   * relies on.
   *
   * Best-effort: presence publication failures are non-fatal because the
   * registry claim already carries the authoritative liveness of the tab.
   */
  private _publishBrowserRuntimePresence(
    state: IBrowserRuntimeRegistryState,
    inventory: readonly IBrowserRuntimeInventoryEntry[],
    event: RuntimePresenceEventV1,
  ): void {
    const context = this._context;
    if (!context) return;
    try {
      const presenceInventory = mapBrowserInventoryToPresence(inventory);
      const now = Date.now();
      const record: RuntimePresenceRecordV1 = {
        version: '1',
        namespaceRoot: state.namespaceRoot,
        runtimeId: state.runtimeId,
        runtimeType: 'browser',
        runtimeRoot: state.runtimeRoot,
        ...(state.authorityRoot.length > 0 ? { authorityRoot: state.authorityRoot } : {}),
        app: state.app,
        claims: [{ prefix: state.runtimeMount, kind: 'local-only' }],
        inventoryMode: 'embedded',
        ...(presenceInventory.length > 0 ? { inventory: presenceInventory } : {}),
        controlMount: state.controlMount,
        heartbeatTtlMs: 45_000,
        registeredAt: state.registeredAt,
        lastHeartbeat: now,
        health: { status: 'ok', updatedAt: now },
        metadata: {
          source: 'browser-runtime',
          surface: 'webapp',
          ownerKind: 'client-session',
          packageRef: state.app,
          runtimeInstanceRoot: state.runtimeInstanceRoot,
          // Render as "<App Name> (browser)" so it's distinguishable from
          // the server-side runtime sharing the same packageRef.
          displayName: `${state.app} (browser)`,
          ...(state.sessionAuthorityRoot.length > 0 ? { sessionAuthorityRoot: state.sessionAuthorityRoot } : {}),
          ...(state.selectedAuthorityRoot.length > 0 ? { selectedAuthorityRoot: state.selectedAuthorityRoot } : {}),
          ...(state.runtimeHref.length > 0 ? { href: state.runtimeHref.slice(0, 200) } : {}),
          ...(typeof navigator !== 'undefined' ? { userAgent: navigator.userAgent.slice(0, 120) } : {}),
        },
      };
      const target = this._runtimeRegistryTargetForRoot(state.namespaceRoot);
      RequestReply.execute(
        context,
        target,
        'runtimes.presence.update',
        { record, event },
        { timeoutMs: 5000 },
      ).catch((err) => {
        // eslint-disable-next-line no-console -- browser bootstrap
        console.warn(`[MatrixDSLHost] Browser runtime presence (${event}) failed (non-fatal):`, err);
      });
    } catch (err) {
      // eslint-disable-next-line no-console -- browser bootstrap
      console.warn(`[MatrixDSLHost] Browser runtime presence publish (${event}) failed (non-fatal):`, err);
    }
  }

  private async _replaceBrowserRuntimeClaims(
    state: IBrowserRuntimeRegistryState,
    inventory: readonly IBrowserRuntimeInventoryEntry[],
    inventoryVersion: number,
  ): Promise<void> {
    if (!this._context) {
      return;
    }
    const nextComponentIds = new Set(inventory.map((entry) => browserInventoryComponentId(state, entry)));
    for (const entry of inventory) {
      await this._claimBrowserRuntimeEntry(state, entry, inventory.length, inventoryVersion);
    }
    for (const componentId of this._browserRuntimeClaimedComponentIds) {
      if (nextComponentIds.has(componentId)) {
        continue;
      }
      await RequestReply.execute(
        this._context,
        state.registryTarget,
        'registry.release',
        {
          componentId,
          providerRuntimeId: state.runtimeId,
        },
        { timeoutMs: 5000 },
      );
    }
    this._browserRuntimeClaimedComponentIds = nextComponentIds;
  }

  private async _claimBrowserRuntimeEntry(
    state: IBrowserRuntimeRegistryState,
    entry: IBrowserRuntimeInventoryEntry,
    actorCount: number,
    inventoryVersion: number,
  ): Promise<void> {
    if (!this._context) {
      return;
    }
    const kind = browserInventoryRegistryKind(entry);
    await RequestReply.execute(
      this._context,
      state.registryTarget,
      'registry.claim',
      {
        namespaceRoot: state.namespaceRoot,
        mount: entry.mount,
        kind,
        componentId: browserInventoryComponentId(state, entry),
        componentType: entry.type,
        providerRuntimeId: state.runtimeId,
        runtimeWireRoot: state.runtimeRoot,
        localMount: entry.mount,
        packageName: state.app,
        runtimeId: state.runtimeId,
        packageId: state.app,
        mode: 'local-only',
        ttlMs: 45_000,
        health: { status: 'ok' },
        metadata: {
          source: 'browser-runtime-registry-claim',
          runtimeType: 'browser',
          ownerKind: 'client-session',
          runtimeRoot: state.runtimeRoot,
          runtimeInstanceRoot: state.runtimeInstanceRoot,
          sessionMount: state.sessionMount,
          relativeMount: state.relativeMount,
          controlMount: state.controlMount,
          actorCount,
          inventoryVersion,
          surface: entry.surface,
          ...(entry.description ? { description: entry.description } : {}),
          ...(state.authorityRoot.length > 0 ? {
            addressRoot: state.authorityRoot,
            authorityRoot: state.authorityRoot,
          } : {}),
          ...(state.sessionAuthorityRoot.length > 0 ? { sessionAuthorityRoot: state.sessionAuthorityRoot } : {}),
          ...(state.selectedAuthorityRoot.length > 0 ? { selectedAuthorityRoot: state.selectedAuthorityRoot } : {}),
          ...(state.runtimeHref.length > 0 ? { href: state.runtimeHref.slice(0, 200) } : {}),
          ...(typeof navigator !== 'undefined' ? { userAgent: navigator.userAgent.slice(0, 120) } : {}),
        },
      },
      { timeoutMs: 5000 },
    );
  }

  private _runtimeRegistryTargetForRoot(root: string): string {
    const trimmed = root.trim();
    return trimmed ? `${trimmed}/system.runtimes` : 'system.runtimes';
  }

  private _serviceRegistryTargetForRoot(root: string): string {
    const trimmed = root.trim();
    return trimmed ? `${trimmed}/system.registry` : 'system.registry';
  }

  private _shouldSkipBrowserRuntimeRegistryClaim(controlPlaneRoot: string): boolean {
    if (this.dataset.authorityCoordinatorActive === 'false') {
      return true;
    }

    const targetRoot = controlPlaneRoot.trim();
    const platformRoot = (
      this.dataset.platformServiceRoot
      ?? this.dataset.platformRoot
      ?? ''
    ).trim();
    if (!targetRoot || !platformRoot || targetRoot !== platformRoot) {
      return false;
    }
    if (this.dataset.isPlatformAdmin === 'true') {
      return false;
    }
    if (this.dataset.authenticated !== 'true' && this._isAuthenticated !== true) {
      return false;
    }
    const candidateAuthorityRoots = [
      this.dataset.selectedAuthorityRoot,
      this.dataset.sessionAuthorityRoot,
      this.dataset.principalAuthorityRoot,
    ].map((root) => (root ?? '').trim());
    return !candidateAuthorityRoots.some((root) => root.length > 0 && root !== platformRoot);
  }

  private _controlPlaneRootForSingletons(authorityRoot: string | null | undefined): string {
    const selectedRoot = typeof this.dataset.selectedAuthorityRoot === 'string'
      ? this.dataset.selectedAuthorityRoot.trim()
      : '';
    if (selectedRoot) {
      return selectedRoot;
    }
    const principalRoot = typeof this.dataset.principalAuthorityRoot === 'string'
      ? this.dataset.principalAuthorityRoot.trim()
      : '';
    if (principalRoot) {
      return principalRoot;
    }
    return typeof authorityRoot === 'string' ? authorityRoot.trim() : '';
  }

  private _runtimeIdFromMount(mount: string): string {
    const parts = mount.split('.').filter(Boolean);
    return parts.find((part) => part.startsWith(BROWSER_RUNTIME_ID_PREFIX)) ?? '';
  }

  /**
   * Phase B bus discovery resolves identity and service metadata after first render.
   *
   * This must not block child mounting. Apps already tolerate late identity
   * attributes on the host and should render while the bus discovery completes.
   */
  private async _runPhaseBBusDiscovery(usedBootstrap: boolean): Promise<void> {
    if (!usedBootstrap || !this._context || !this._transport || !this._runtime) return;
    const finishPhaseBProfile = createBrowserProfileSpan(HOST_PROFILE_SCOPE, 'phaseB.discovery', {
      usedBootstrap,
    });

    const daemonRoot = this.getAttribute('daemon-root') ?? '';
    const serviceRoot = this.dataset.platformServiceRoot ?? this.dataset.platformRoot ?? daemonRoot;
    const explicitAuthorityRoot = this.dataset.explicitAuthorityRoot;
    if (explicitAuthorityRoot) {
      // Explicit authority URLs already declare the target identity in the
      // path. Do not probe platform-local actors such as system.auth or
      // system.directory here; that turns a shareable user URL into a hidden
      // HiveCast-local lookup and can wait on unrelated platform timeouts.
      console.info('[MatrixDSLHost] Phase B platform probe skipped for explicit authority URL - retaining explicit authority root');
      finishPhaseBProfile({
        result: 'skipped-explicit-authority',
        daemonRoot,
        serviceRoot,
        authorityRoot: explicitAuthorityRoot,
      });
      return;
    }
    const authTarget = serviceRoot ? `${serviceRoot}/system.auth` : 'system.auth';
    const dirTarget = serviceRoot ? `${serviceRoot}/system.directory` : 'system.directory';
    const busTokenPayload = this.dataset.busToken ? { busToken: this.dataset.busToken } : {};
    const rootCtx = this._runtime.getRootContext!();
    const bootstrapAuthenticated = (this.dataset.authenticated === 'true') || this._isAuthenticated === true;
    if (!bootstrapAuthenticated && !this.dataset.busToken) {
      console.info('[MatrixDSLHost] Phase B platform probe skipped for anonymous bootstrap');
      finishPhaseBProfile({
        result: 'skipped-anonymous',
        daemonRoot,
        serviceRoot,
      });
      return;
    }
    const isHostedLeafTarget = this.dataset.runtimeTargetKind === 'leaf'
      && daemonRoot.length > 0
      && serviceRoot.length > 0
      && daemonRoot !== serviceRoot;
    const selectedAuthorityRoot = (this.dataset.selectedAuthorityRoot ?? '').trim();
    const userAuthorityRoot = selectedAuthorityRoot
      || (this.dataset.principalAuthorityRoot ?? '').trim();
    const isPlatformAdmin = this.dataset.isPlatformAdmin === 'true';
    const isNormalUserAuthoritySession = bootstrapAuthenticated
      && userAuthorityRoot.length > 0
      && serviceRoot.length > 0
      && userAuthorityRoot !== serviceRoot
      && !isPlatformAdmin;

    if (isNormalUserAuthoritySession) {
      console.info('[MatrixDSLHost] Phase B platform probe skipped for user authority session — retaining bootstrap identity');
      finishPhaseBProfile({
        result: 'skipped-user-authority',
        daemonRoot,
        serviceRoot,
        authorityRoot: userAuthorityRoot,
      });
      return;
    }

    if (
      bootstrapAuthenticated
      && (
        this._isHostBootstrapMode()
        || this._isHostServiceBootstrap()
        || this._shouldRetainBootstrapIdentity(daemonRoot)
        || this._shouldUseRuntimeRegistryDiscovery(daemonRoot)
      )
    ) {
      console.info('[MatrixDSLHost] Phase B service probe skipped for Host bootstrap — retaining bootstrap identity');
      finishPhaseBProfile({
        result: 'skipped-host-bootstrap',
        daemonRoot,
        serviceRoot,
      });
      return;
    }

    if (bootstrapAuthenticated && isHostedLeafTarget) {
      // Leaf-targeted hosted apps already have HTTP-session identity from
      // bootstrap. The browser transport is scoped to the leaf account, so a
      // platform Phase B RR would require a cross-account reply path and only
      // produces a non-fatal timeout.
      console.info('[MatrixDSLHost] Phase B platform probe skipped for hosted leaf runtime — retaining bootstrap identity');
      finishPhaseBProfile({
        result: 'skipped-leaf-runtime',
        daemonRoot,
        serviceRoot,
      });
      return;
    }

    // Phase B: auth + directory in PARALLEL (saves ~400ms vs sequential)
    const authPromise = this._executePhaseBRequest<Record<string, unknown>, {
      ok: boolean; principalId?: string; displayName?: string; root?: string; tier?: string; authenticated?: boolean;
    }>(authTarget, 'auth.whoami', busTokenPayload).catch((err) => {
      if (bootstrapAuthenticated) {
        console.info('[MatrixDSLHost] Phase B auth probe deferred — retaining bootstrap identity:', err);
      } else {
        console.warn('[MatrixDSLHost] Phase B auth probe failed:', err);
      }
      return null;
    });

    const dirPromise = this._executePhaseBRequest<Record<string, unknown>, {
      ok: boolean; root?: string; services?: Array<{ name: string; mount: string }>;
      parentRoots?: unknown[];
    }>(dirTarget, 'directory.whoami', busTokenPayload).catch((err) => {
      console.info('[MatrixDSLHost] Phase B directory probe deferred (non-fatal):', err);
      return null;
    });

    const [authResult, dirResult] = await Promise.all([authPromise, dirPromise]);

    if (authResult?.ok) {
      console.info(`[MatrixDSLHost] Phase B: ${authTarget} → principalId="${authResult.principalId}", authenticated=${authResult.authenticated}, root="${authResult.root}"`);
      if (authResult.principalId) {
        this.dataset.principalId = authResult.principalId;
        rootCtx.setService('principal-id', authResult.principalId);
      }
      const orgRoot = this.dataset.platformRoot || serviceRoot || authResult.root || '';
      if (orgRoot) {
        this.dataset.orgId = orgRoot;
        rootCtx.setService('org-id', orgRoot);
      }
      if (authResult.root) {
        this.dataset.workspaceId = authResult.root;
        rootCtx.setService('workspace-id', authResult.root);
      }
      if (authResult.displayName) this.dataset.displayName = authResult.displayName;
      this.dataset.authenticated = String(authResult.authenticated ?? false);
    }

    if (dirResult?.ok) {
      console.info(`[MatrixDSLHost] Phase B: ${dirTarget} → root="${dirResult.root}", services=${dirResult.services?.length ?? 0}`);
      if (dirResult.parentRoots) {
        this.setAttribute('parent-roots', JSON.stringify(dirResult.parentRoots));
        this.setAttribute('parent-realms', JSON.stringify(dirResult.parentRoots));
      }
    }

    if (this.dataset.busToken) {
      this._startBusTokenRefresh(authTarget);
    }
    finishPhaseBProfile({
      authOk: authResult?.ok === true,
      dirOk: dirResult?.ok === true,
      daemonRoot,
      serviceRoot,
    });
  }

  private async _executePhaseBRequest<TPayload extends Record<string, unknown>, TResult>(
    target: string,
    op: string,
    payload: TPayload,
  ): Promise<TResult> {
    const retryDelaysMs = [0, 200, 500] as const;
    let lastError: unknown;

    for (const delayMs of retryDelaysMs) {
      if (delayMs > 0) {
        await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
      }
      try {
        return await RequestReply.execute<TPayload, TResult>(
          this._context!,
          target,
          op,
          payload,
          { timeoutMs: 5000 },
        );
      } catch (error) {
        lastError = error;
      }
    }

    throw lastError instanceof Error ? lastError : new Error(`Phase B request failed: ${String(lastError)}`);
  }

  // ═══════════════════════════════════════════════════════════════════════════
  // Cleanup
  // ═══════════════════════════════════════════════════════════════════════════

  /**
   * Start a 4-minute interval to refresh the bus token before its 5-min expiry.
   * Calls system.auth auth.refresh on the bus with the current token.
   */
  private _startBusTokenRefresh(authTarget: string): void {
    this._stopBusTokenRefresh();
    if (this._shouldSkipBusTokenRefreshForTarget(authTarget)) {
      console.info('[MatrixDSLHost] Bus token refresh skipped for platform auth target in user authority session');
      return;
    }
    const REFRESH_INTERVAL_MS = 4 * 60 * 1000; // 4 minutes
    this._busTokenRefreshTimer = setInterval(async () => {
      const currentToken = this.dataset.busToken;
      if (!currentToken || !this._context) {
        this._stopBusTokenRefresh();
        return;
      }
      try {
        const result = await RequestReply.execute<Record<string, unknown>, {
          ok: boolean; busToken?: string; expiresAt?: number; principalId?: string;
        }>(this._context, authTarget, 'auth.refresh', { busToken: currentToken }, { timeoutMs: 5000 });
        if (result?.ok && result.busToken) {
          this.dataset.busToken = result.busToken;
          this._context.setService('bus-token', result.busToken);
          this._installScopedActorServices(this._context, this.dataset.runtimeRoot ?? this.dataset.sessionRoot ?? null);
          // eslint-disable-next-line no-console -- browser bootstrap, not an actor
          console.debug(`[MatrixDSLHost] Bus token refreshed for ${result.principalId}`);
        } else {
          // eslint-disable-next-line no-console -- browser bootstrap, not an actor
          console.warn('[MatrixDSLHost] Bus token refresh failed — clearing token');
          delete this.dataset.busToken;
          this.dataset.authenticated = 'false';
          this._stopBusTokenRefresh();
        }
      } catch (err) {
        // eslint-disable-next-line no-console -- browser bootstrap, not an actor
        console.warn('[MatrixDSLHost] Bus token refresh error:', err);
      }
    }, REFRESH_INTERVAL_MS);
  }

  private _shouldSkipBusTokenRefreshForTarget(authTarget: string): boolean {
    const targetRoot = authTarget.includes('/')
      ? authTarget.slice(0, authTarget.indexOf('/')).trim()
      : '';
    if (!targetRoot) {
      return false;
    }
    const userAuthorityRoot = (this.dataset.selectedAuthorityRoot ?? '').trim()
      || (this.dataset.principalAuthorityRoot ?? '').trim();
    return (this.dataset.authenticated === 'true' || this._isAuthenticated === true)
      && this.dataset.isPlatformAdmin !== 'true'
      && userAuthorityRoot.length > 0
      && targetRoot !== userAuthorityRoot;
  }

  private _installScopedActorServices(context: IMatrixContext, runtimeInstanceRoot: string | null): void {
    const platformRoot = (
      this.dataset.platformServiceRoot
      ?? this.dataset.platformRoot
      ?? ''
    ).trim();
    const userSpaceRoot = (
      this.dataset.selectedAuthorityRoot
      ?? this.dataset.sessionAuthorityRoot
      ?? this.dataset.principalAuthorityRoot
      ?? ''
    ).trim();
    const accountRoot = (
      this.dataset.sessionAuthorityRoot
      ?? this.dataset.principalAuthorityRoot
      ?? this.dataset.selectedAuthorityRoot
      ?? ''
    ).trim();
    const addressContext: RuntimeAddressContext = {
      runtimeInstanceRoot: runtimeInstanceRoot && runtimeInstanceRoot.trim().length > 0
        ? runtimeInstanceRoot.trim()
        : null,
      accountRoot: accountRoot.length > 0 ? accountRoot : null,
      userSpaceRoot: userSpaceRoot.length > 0 ? userSpaceRoot : null,
      platformRoot,
      isPlatformAdmin: this.dataset.isPlatformAdmin === 'true',
      principalId: this.dataset.principalId ?? null,
      busToken: this.dataset.busToken ?? null,
    };
    const callClient = new ActorCallClient(context, addressContext);
    const resolver = new ScopedIntentResolver(callClient, WELL_KNOWN_SERVICE_BINDINGS);
    const services = new ActorServices(resolver, addressContext);
    context.setService(RUNTIME_ADDRESS_CONTEXT, addressContext);
    context.setService(ACTOR_CALL_CLIENT, callClient);
    context.setService(SCOPED_INTENT_RESOLVER, resolver);
    context.setService(ACTOR_SERVICES, services);
  }

  private _stopBusTokenRefresh(): void {
    if (this._busTokenRefreshTimer) {
      clearInterval(this._busTokenRefreshTimer);
      this._busTokenRefreshTimer = null;
    }
  }

  private _startHostedRuntimeTargetRefresh(): void {
    this._stopHostedRuntimeTargetRefresh();
    this._hostedRuntimeTargetRefreshTimer = setInterval(() => {
      void this._refreshHostedRuntimeTargetMetadata();
    }, HOSTED_RUNTIME_TARGET_REFRESH_INTERVAL_MS);
  }

  private _stopHostedRuntimeTargetRefresh(): void {
    if (this._hostedRuntimeTargetRefreshTimer) {
      clearInterval(this._hostedRuntimeTargetRefreshTimer);
      this._hostedRuntimeTargetRefreshTimer = null;
    }
    this._hostedRuntimeTargetRefreshInFlight = false;
  }

  private _scheduleDaemonDiscoveryRetry(delayMs: number): void {
    if (this._daemonDiscoveryRetryTimer || !this._context || !this._runtime) {
      return;
    }
    const retryTimer = setTimeout(() => {
      this._daemonDiscoveryRetryTimer = null;
      void this._discoverDaemon();
    }, delayMs);
    if (typeof retryTimer === 'object' && retryTimer !== null && 'unref' in retryTimer) {
      const unref = retryTimer.unref;
      if (typeof unref === 'function') {
        unref.call(retryTimer);
      }
    }
    this._daemonDiscoveryRetryTimer = retryTimer;
  }

  private _stopDaemonDiscoveryRetry(): void {
    if (this._daemonDiscoveryRetryTimer) {
      clearTimeout(this._daemonDiscoveryRetryTimer);
      this._daemonDiscoveryRetryTimer = null;
    }
    this._daemonDiscoveryRetryDelayMs = 1_000;
  }

  private _cleanup(): void {
    this._lifecycleGeneration += 1;
    const transportToDisconnect = this._transport;
    this._stopBusTokenRefresh();
    this._stopHostedRuntimeTargetRefresh();
    this._stopDaemonDiscoveryRetry();
    delete this.dataset.sessionRoot;
    delete this.dataset.runtimeRoot;
    delete this.dataset.daemonStatus;
    if (this._observer) {
      this._observer.disconnect();
      this._observer = null;
    }
    if (transportToDisconnect) {
      void transportToDisconnect.disconnect().catch((error) => {
        // eslint-disable-next-line no-console -- browser host teardown has no actor context
        console.warn('[MatrixDSLHost] Transport disconnect during cleanup failed:', error);
      });
    }
    if (this._joinUnsub) {
      this._joinUnsub();
      this._joinUnsub = null;
    }
    if (this._browserRuntimeRenewTimer) {
      clearInterval(this._browserRuntimeRenewTimer);
      this._browserRuntimeRenewTimer = null;
    }
    if (this._runtimeInventoryClaimRefreshTimer) {
      clearTimeout(this._runtimeInventoryClaimRefreshTimer);
      this._runtimeInventoryClaimRefreshTimer = null;
    }
    if (this._browserRuntimeRegistryState && this._runtime) {
      this._publishBrowserRuntimePresence(
        this._browserRuntimeRegistryState,
        this._browserRuntimeInventory(
          this._browserRuntimeRegistryState.runtimeId,
          this._browserRuntimeRegistryState.contextMount,
          this._browserRuntimeRegistryState.hostBootstrapMode,
        ),
        'departed',
      );
    }
    this._browserRuntimeRegistryState = null;
    this._browserRuntimeClaimedComponentIds.clear();
    this._runtimeRegistryId = '';
    this._runtimeControlStartedAt = '';
    if (this._browserRuntimeReleaseHandler) {
      if (typeof window !== 'undefined') {
        window.removeEventListener('beforeunload', this._browserRuntimeReleaseHandler);
      }
      this._browserRuntimeReleaseHandler = null;
    }
    if (this._peer) {
      this._peer.stop();
      this._peer = null;
    }
    this._context = null;
    this._runtime = null;
    this._transport = null;
    this._rawAdapter = null;
    this._routingPeer = null;
    this._wrapTransport = null;
    this._initialized = false;
  }
}

const ROUTE_KEY_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
const RESERVED_ROUTE_KEYS = new Set([
  'api',
  'auth',
  'login',
  'logout',
  'signup',
  'setup',
  'settings',
  'apps',
  'app',
  'assets',
  'static',
  'branding',
  'nats-ws',
  'matrix',
  'system',
  'admin',
  'root',
  'support',
  'docs',
  'help',
  'billing',
  'status',
  'healthz',
  'well-known',
  'favicon.ico',
  'manifest.json',
  'hivecast',
  'open-matrix',
  'me',
]);

function isValidRouteKey(routeKey: string): boolean {
  return ROUTE_KEY_PATTERN.test(routeKey)
    && !RESERVED_ROUTE_KEYS.has(routeKey);
}

function routeKeyFromPublicNamespace(publicNamespace: string): string | null {
  const normalized = publicNamespace.trim().toLowerCase();
  if (!normalized.startsWith('space.')) {
    return null;
  }
  const routeKey = normalized.slice('space.'.length);
  return isValidRouteKey(routeKey) ? routeKey : null;
}

function matrixChildElementHooks(element: HTMLElement): IMatrixChildElementHooks {
  return element as IMatrixChildElementHooks;
}

function matrixActorElementVersionSource(element: HTMLElement): IMatrixActorElementVersionSource {
  return element as IMatrixActorElementVersionSource;
}

function matrixRootContextReceiver(element: Element): IMatrixRootContextReceiver {
  return element as IMatrixRootContextReceiver;
}

function transportRootForContext(context: IMatrixContext): string | undefined {
  return context.transport.root || context.transport.realm;
}

function browserInventoryRegistryKind(entry: IBrowserRuntimeInventoryEntry): ServiceRegistryEntryKindV1 {
  return entry.surface === 'runtime' ? 'runtime' : 'actor';
}

function browserInventoryComponentId(
  state: IBrowserRuntimeRegistryState,
  entry: IBrowserRuntimeInventoryEntry,
): string {
  return browserInventoryRegistryKind(entry) === 'runtime'
    ? `runtime:${state.runtimeId}`
    : `runtime:${state.runtimeId}:actor:${entry.mount}`;
}

function mapBrowserInventoryToPresence(
  inventory: readonly IBrowserRuntimeInventoryEntry[],
): RuntimeInventoryEntryV1[] {
  return inventory.map((entry) => ({
    mount: entry.mount,
    type: entry.type,
    surface: entry.surface === 'dom' ? 'dom' : 'webapp',
    runtimeId: entry.runtimeId,
    claimKind: 'local-only',
    ...(entry.description ? { description: entry.description } : {}),
  }));
}

function browserRouterTransportAdapter(
  adapter: BrowserRouterResult['adapter'],
  peer: FederationPeer,
): ITransportAdapter {
  return {
    get root() {
      return adapter.root ?? peer.localRoot;
    },
    get realm() {
      return adapter.realm ?? peer.localRoot;
    },
    publish: adapter.publish,
    subscribe: adapter.subscribe,
    getWireTopicInfo: adapter.getWireTopicInfo,
    getUnderlyingClient: () => adapter.getUnderlyingClient?.() ?? peer,
    disconnect: async () => {
      peer.stop();
    },
  };
}

function serviceRegistryEntry(value: unknown): ServiceRegistryEntryV1 | null {
  const record = registryRecord(value);
  const kind = serviceRegistryEntryKind(record.kind);
  const placement = registryPlacement(record.placement);
  const claim = registryClaim(record.claim);
  const health = registryHealth(record.health);
  if (
    record.version !== '1'
    || typeof record.namespaceRoot !== 'string'
    || typeof record.mount !== 'string'
    || kind === null
    || placement === null
    || claim === null
    || health === null
    || typeof record.ttlMs !== 'number'
  ) {
    return null;
  }
  return {
    version: '1',
    namespaceRoot: record.namespaceRoot,
    mount: record.mount,
    kind,
    ...(registryService(record.service) ? { service: registryService(record.service) } : {}),
    ...(registryApp(record.app) ? { app: registryApp(record.app) } : {}),
    placement,
    claim,
    health,
    ttlMs: record.ttlMs,
    ...(isRegistryRecord(record.metadata) ? { metadata: record.metadata } : {}),
  };
}

function serviceRegistryEntryKind(value: unknown): ServiceRegistryEntryKindV1 | null {
  return value === 'actor'
    || value === 'service'
    || value === 'app'
    || value === 'feed'
    || value === 'runtime'
    || value === 'gateway'
    || value === 'connector'
    || value === 'resource'
    ? value
    : null;
}

function registryService(value: unknown): ServiceRegistryEntryV1['service'] | undefined {
  const record = registryRecord(value);
  if (Object.keys(record).length === 0) {
    return undefined;
  }
  return {
    accepts: registryStringArray(record.accepts),
    emits: registryStringArray(record.emits),
    streams: registryStringArray(record.streams),
    capabilities: [],
    intents: [],
  };
}

function registryApp(value: unknown): ServiceRegistryEntryV1['app'] | undefined {
  const record = registryRecord(value);
  const route = registryString(record.route);
  const title = registryString(record.title);
  if (!route || !title) {
    return undefined;
  }
  return {
    route,
    title,
    ...(registryString(record.icon) ? { icon: registryString(record.icon) } : {}),
    surface: registryAppSurface(record.surface),
    openable: record.openable !== false,
    ...(registryString(record.appName) ? { appName: registryString(record.appName) } : {}),
  };
}

function registryPlacement(value: unknown): ServiceRegistryEntryV1['placement'] | null {
  if (!isRegistryRecord(value)) {
    return null;
  }
  return {
    ...(registryString(value.deviceId) ? { deviceId: registryString(value.deviceId) } : {}),
    ...(registryString(value.hostId) ? { hostId: registryString(value.hostId) } : {}),
    ...(registryString(value.runtimeId) ? { runtimeId: registryString(value.runtimeId) } : {}),
    ...(registryString(value.packageId) ? { packageId: registryString(value.packageId) } : {}),
    ...(registryString(value.actorId) ? { actorId: registryString(value.actorId) } : {}),
    ...(registryString(value.deploymentInstanceId) ? { deploymentInstanceId: registryString(value.deploymentInstanceId) } : {}),
    ...(registryString(value.instanceName) ? { instanceName: registryString(value.instanceName) } : {}),
    ...(registryString(value.packageRef) ? { packageRef: registryString(value.packageRef) } : {}),
  };
}

function registryClaim(value: unknown): ServiceRegistryEntryV1['claim'] | null {
  if (!isRegistryRecord(value)) {
    return null;
  }
  const mode = registryClaimMode(value.mode);
  const result = registryClaimResult(value.result);
  const ownerComponentId = registryString(value.ownerComponentId);
  const loadBalancing = registryLoadBalancing(value.loadBalancing);
  if (
    mode === null
    || result === null
    || !ownerComponentId
    || loadBalancing === null
    || typeof value.claimedAt !== 'number'
    || typeof value.renewedAt !== 'number'
    || typeof value.expiresAt !== 'number'
  ) {
    return null;
  }
  return {
    mode,
    result,
    ownerComponentId,
    ...(registryString(value.electionGroup) ? { electionGroup: registryString(value.electionGroup) } : {}),
    ...(registryString(value.leaderId) ? { leaderId: registryString(value.leaderId) } : {}),
    loadBalancing,
    claimedAt: value.claimedAt,
    renewedAt: value.renewedAt,
    expiresAt: value.expiresAt,
  };
}

function registryHealth(value: unknown): ServiceRegistryEntryV1['health'] | null {
  if (!isRegistryRecord(value)) {
    return null;
  }
  const status = registryHealthStatus(value.status);
  if (status === null || typeof value.updatedAt !== 'number') {
    return null;
  }
  return {
    status,
    ...(registryString(value.reason) ? { reason: registryString(value.reason) } : {}),
    updatedAt: value.updatedAt,
  };
}

function registryRecord(value: unknown): Record<string, unknown> {
  return value && typeof value === 'object' && !Array.isArray(value)
    ? value as Record<string, unknown>
    : {};
}

function bootstrapNodeRoleActive(value: unknown, roleName: string): boolean | undefined {
  if (!value || typeof value !== 'object' || Array.isArray(value)) {
    return undefined;
  }
  const role = (value as Record<string, unknown>)[roleName];
  if (!role || typeof role !== 'object' || Array.isArray(role)) {
    return undefined;
  }
  const active = (role as Record<string, unknown>).active;
  return typeof active === 'boolean' ? active : undefined;
}

function isRegistryRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

function registryArtifact(value: unknown): Record<string, unknown> {
  return registryRecord(value);
}

function registryString(value: unknown): string | undefined {
  return typeof value === 'string' && value.trim().length > 0
    ? value.trim()
    : undefined;
}

function registryStringArray(value: unknown): string[] {
  return Array.isArray(value)
    ? value.filter((item): item is string => typeof item === 'string')
      .map((item) => item.trim())
      .filter(Boolean)
    : [];
}

function registryAppSurface(value: unknown): NonNullable<ServiceRegistryEntryV1['app']>['surface'] {
  return value === 'panel' || value === 'modal' || value === 'widget'
    ? value
    : 'page';
}

function registryClaimMode(value: unknown): ServiceRegistryEntryV1['claim']['mode'] | null {
  return value === 'authoritative'
    || value === 'proxy'
    || value === 'mirror'
    || value === 'local-only'
    || value === 'pool-member'
    ? value
    : null;
}

function registryClaimResult(value: unknown): ServiceRegistryEntryV1['claim']['result'] | null {
  return value === 'accepted'
    || value === 'rejected'
    || value === 'collision'
    || value === 'joined-pool'
    || value === 'standby'
    || value === 'leader'
    || value === 'mirror'
    || value === 'local-only'
    ? value
    : null;
}

function registryLoadBalancing(value: unknown): ServiceRegistryEntryV1['claim']['loadBalancing'] | null {
  return value === 'none'
    || value === 'round-robin'
    || value === 'least-loaded'
    || value === 'broadcast'
    ? value
    : null;
}

function registryHealthStatus(value: unknown): ServiceRegistryEntryV1['health']['status'] | null {
  return value === 'ok'
    || value === 'degraded'
    || value === 'error'
    || value === 'unknown'
    || value === 'starting'
    || value === 'stopped'
    ? value
    : null;
}

function registrySourceKind(value: unknown): ComponentSourceKind | undefined {
  const sourceKind = registryString(value);
  return sourceKind === 'installed-webapp' || sourceKind === 'external-webapp'
    ? sourceKind
    : undefined;
}

function registryRegistrationSource(value: unknown): ComponentRegistrationSource | undefined {
  const registrationSource = registryString(value);
  return registrationSource === 'package-manifest'
    || registrationSource === 'daemon-config'
    || registrationSource === 'deployment-spec'
    ? registrationSource
    : undefined;
}

function registryArtifactFreshness(value: unknown): ComponentArtifactFreshness | undefined {
  const freshness = registryString(value);
  return freshness === 'current'
    || freshness === 'stale'
    || freshness === 'incomplete'
    || freshness === 'missing-manifest'
    || freshness === 'invalid-manifest'
    || freshness === 'unverifiable'
    || freshness === 'missing-output'
    ? freshness
    : undefined;
}

// ═══════════════════════════════════════════════════════════════════════════
// Custom Element Registration
// ═══════════════════════════════════════════════════════════════════════════

if (typeof customElements !== 'undefined' && !customElements.get('matrix-dsl-host')) {
  customElements.define('matrix-dsl-host', MatrixDSLHost);
}