XZBT-NGN/test-fixtures/reference-exhibits/scifi/js/surface-mode.js

/**
 * XZBT Surface Mode — SciFi-XZBT (Step 6.7B)
 *
 * Pure, testable seam for resolving which boot mode this document load is in
 * (Contract 5.3 §31.4 query-string surface form) and for describing the
 * exhibit's two-entry surface catalog. No DOM access, no imports, no
 * side effects — safe to load and exercise under Node's `vm` module.
 *
 * Two surfaces only:
 *   - surface.console      the full operator console (index.html, primary)
 *   - surface.observation  the same document, rendering only the
 *                          Observation viewscreen, addressed by
 *                          ?surface=observation&xi=<instanceId>
 */
(function (root) {
  'use strict';

  var CHANNEL_PREFIX = 'xzbt-scifi-surface-v1:';

  /**
   * Resolve the boot mode + instance id for a location-like object.
   * @param {object} locationLike anything with a `.search` (or `.href`)
   *   string, e.g. `window.location`.
   * @returns {{mode: 'console'|'observation', instanceId: string|null}}
   */
  function resolve(locationLike) {
    var search = '';
    if (locationLike && typeof locationLike.search === 'string') {
      search = locationLike.search;
    } else if (locationLike && typeof locationLike.href === 'string') {
      var qIdx = locationLike.href.indexOf('?');
      search = qIdx >= 0 ? locationLike.href.slice(qIdx) : '';
    }

    var params;
    try {
      params = new URLSearchParams(search);
    } catch (err) {
      params = null;
    }

    var surfaceParam = params ? params.get('surface') : null;
    var instanceId = params ? params.get('xi') : null;

    if (surfaceParam === 'observation') {
      return { mode: 'observation', instanceId: instanceId || null };
    }

    // Unknown/absent `?surface=` values resolve to console. `xi` is
    // meaningless in console mode.
    return { mode: 'console', instanceId: null };
  }

  /** Mint a fresh per-document-load instance id. */
  function newInstanceId() {
    return 'xi-' + Math.random().toString(16).slice(2) + Date.now().toString(16);
  }

  /**
   * The exhibit's two-entry surface catalog (Contract 5.3 §31.2/§31.3).
   * @param {string} instanceId the live console instance id.
   */
  function SURFACES(instanceId) {
    return [
      {
        id: 'surface.console',
        label: 'Main Console',
        kind: 'surface',
        primary: true,
        url: 'index.html',
        role: 'control',
        category: 'console',
        description: 'The full SciFi-XZBT operator console.'
      },
      {
        id: 'surface.observation',
        label: 'Observation',
        kind: 'surface',
        primary: false,
        url: '?surface=observation&xi=' + encodeURIComponent(instanceId),
        role: 'ambient',
        category: 'observation',
        aspectRatio: '16:9',
        requires: ['observation'],
        description: 'Full-screen procedural viewscreen mirroring the console.'
      }
    ];
  }

  /** The instance-scoped BroadcastChannel name for a console instance id. */
  function channelName(instanceId) {
    return CHANNEL_PREFIX + instanceId;
  }

  var XZBTSurfaceMode = {
    resolve: resolve,
    newInstanceId: newInstanceId,
    SURFACES: SURFACES,
    channelName: channelName
  };

  if (typeof module !== 'undefined' && module.exports) {
    module.exports = XZBTSurfaceMode;
  }
  if (root) {
    root.XZBTSurfaceMode = XZBTSurfaceMode;
  }
})(typeof window !== 'undefined' ? window : (typeof globalThis !== 'undefined' ? globalThis : this));