@jskit-ai/shell-web 0.1.4

package/src/client/placement/runtime.js

@@ -0,0 +1,435 @@
+import {
+  WEB_PLACEMENT_CONTEXT_CONTRIBUTOR_TAG,
+  WEB_PLACEMENT_SURFACE_ANY
+} from "./tokens.js";
+import { DEFAULT_DEBUG_DEPTH, explodePayload } from "./debug.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  isRenderableComponent,
+  normalizePlacementDefinition,
+  normalizePlacementHost,
+  normalizePlacementPosition,
+  normalizeSurface
+} from "./validators.js";
+
+function ensureArray(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (value === undefined || value === null) {
+    return [];
+  }
+  return [value];
+}
+
+const PLACEMENT_DEBUG_PREFIX = "[placement-debug]";
+const PLACEMENT_DEBUG_FLAG = "__JSKIT_PLACEMENT_DEBUG__";
+const NOOP = () => {};
+
+function isPlacementDebugEnabled() {
+  if (typeof globalThis !== "object" || !globalThis) {
+    return false;
+  }
+
+  return globalThis[PLACEMENT_DEBUG_FLAG] === true;
+}
+
+function debugLog(message, payload = null) {
+  if (!isPlacementDebugEnabled()) {
+    return;
+  }
+
+  if (payload === null || payload === undefined) {
+    console.log(`${PLACEMENT_DEBUG_PREFIX} ${message}`);
+    return;
+  }
+  const terminalPayload = explodePayload(payload, DEFAULT_DEBUG_DEPTH);
+  const rendered = JSON.stringify(terminalPayload, null, 2);
+  console.log(`${PLACEMENT_DEBUG_PREFIX} ${message}\n${rendered}`);
+}
+
+function createRuntimeLogger(logger) {
+  const runtimeLogger = isRecord(logger) ? logger : {};
+  let warn = NOOP;
+  let error = NOOP;
+
+  if (typeof runtimeLogger.warn === "function") {
+    warn = runtimeLogger.warn.bind(runtimeLogger);
+  }
+  if (typeof runtimeLogger.error === "function") {
+    error = runtimeLogger.error.bind(runtimeLogger);
+  }
+
+  return Object.freeze({
+    warn,
+    error
+  });
+}
+
+function normalizePlacementList(placements, context = {}) {
+  const normalized = [];
+
+  for (const candidate of ensureArray(placements)) {
+    const placement = normalizePlacementDefinition(candidate, {
+      strict: false,
+      source: "app placement"
+    });
+    if (!placement || placement.enabled === false) {
+      continue;
+    }
+    normalized.push(placement);
+  }
+
+  const byId = new Map();
+  for (const placement of normalized) {
+    if (byId.has(placement.id)) {
+      throw new Error(`Duplicate placement id "${placement.id}" in ${context.source || "placement list"}.`);
+    }
+    byId.set(placement.id, placement);
+  }
+
+  return [...byId.values()].sort((left, right) => {
+    const orderCompare = left.order - right.order;
+    if (orderCompare !== 0) {
+      return orderCompare;
+    }
+    return left.id.localeCompare(right.id);
+  });
+}
+
+function matchesSurface(placementSurfaces, requestedSurface) {
+  if (requestedSurface === WEB_PLACEMENT_SURFACE_ANY) {
+    return true;
+  }
+  const surfaces = Array.isArray(placementSurfaces) ? placementSurfaces : [WEB_PLACEMENT_SURFACE_ANY];
+  return surfaces.includes(WEB_PLACEMENT_SURFACE_ANY) || surfaces.includes(requestedSurface);
+}
+
+function resolveContextContributors(app, baseContext = {}, logger) {
+  const contributors = app.resolveTag(WEB_PLACEMENT_CONTEXT_CONTRIBUTOR_TAG);
+  let merged = {};
+
+  for (const contributor of ensureArray(contributors)) {
+    try {
+      const resolved = typeof contributor === "function" ? contributor(Object.freeze({ ...baseContext })) : contributor;
+      if (isRecord(resolved)) {
+        merged = {
+          ...merged,
+          ...resolved
+        };
+      }
+    } catch (error) {
+      logger.warn(
+        {
+          contributor,
+          error: String(error?.message || error || "unknown error")
+        },
+        "Failed to evaluate web placement context contributor."
+      );
+    }
+  }
+
+  return merged;
+}
+
+function resolvePlacementComponent(
+  app,
+  placement,
+  logger,
+  missingTokens,
+  invalidComponentTokens,
+  failedTokens
+) {
+  const componentToken = String(placement.componentToken || "").trim();
+  if (!componentToken) {
+    return null;
+  }
+
+  if (invalidComponentTokens.has(componentToken) || failedTokens.has(componentToken)) {
+    return null;
+  }
+
+  if (!app.has(componentToken)) {
+    if (!missingTokens.has(componentToken)) {
+      missingTokens.add(componentToken);
+      logger.warn(
+        {
+          placementId: placement.id,
+          componentToken
+        },
+        "Skipping placement because component token is not bound."
+      );
+    }
+    return null;
+  }
+
+  let component = null;
+  try {
+    component = app.make(componentToken);
+  } catch (error) {
+    if (!failedTokens.has(componentToken)) {
+      failedTokens.add(componentToken);
+      logger.error(
+        {
+          placementId: placement.id,
+          componentToken,
+          error: String(error?.message || error || "unknown error")
+        },
+        "Skipping placement because component token resolution threw."
+      );
+    }
+    return null;
+  }
+
+  if (!isRenderableComponent(component)) {
+    if (!invalidComponentTokens.has(componentToken)) {
+      invalidComponentTokens.add(componentToken);
+      logger.warn(
+        {
+          placementId: placement.id,
+          componentToken
+        },
+        "Skipping placement because component token did not resolve to a Vue component."
+      );
+    }
+    return null;
+  }
+
+  return component;
+}
+
+function shouldIncludePlacement(placement, placementContext, logger) {
+  if (typeof placement.when !== "function") {
+    return true;
+  }
+
+  try {
+    return placement.when(Object.freeze({ ...placementContext })) === true;
+  } catch (error) {
+    logger.warn(
+      {
+        placementId: placement.id,
+        error: String(error?.message || error || "unknown error")
+      },
+      "Placement when() predicate failed; placement was skipped."
+    );
+    return false;
+  }
+}
+
+function createWebPlacementRuntime({ app, logger = null } = {}) {
+  if (!app || typeof app.resolveTag !== "function" || typeof app.make !== "function" || typeof app.has !== "function") {
+    throw new Error("createWebPlacementRuntime requires app.resolveTag(), app.has(), and app.make().");
+  }
+
+  const runtimeLogger = createRuntimeLogger(logger);
+  const missingTokens = new Set();
+  const invalidComponentTokens = new Set();
+  const failedTokens = new Set();
+  const listeners = new Set();
+  let placementDefinitions = Object.freeze([]);
+  let sharedContext = Object.freeze({});
+  let revision = 0;
+
+  function notify(event = {}) {
+    revision += 1;
+    debugLog("notify", {
+      revision,
+      event
+    });
+    for (const listener of listeners) {
+      try {
+        listener(
+          Object.freeze({
+            revision,
+            ...event
+          })
+        );
+      } catch (error) {
+        runtimeLogger.warn(
+          {
+            error: String(error?.message || error || "unknown error")
+          },
+          "Web placement runtime listener threw during notification."
+        );
+      }
+    }
+  }
+
+  function replacePlacements(entries = [], { source = "app placement registry" } = {}) {
+    missingTokens.clear();
+    invalidComponentTokens.clear();
+    failedTokens.clear();
+    placementDefinitions = Object.freeze(normalizePlacementList(entries, { source }));
+    debugLog("replacePlacements", {
+      source,
+      count: placementDefinitions.length,
+      ids: placementDefinitions.map((entry) => entry.id)
+    });
+    notify({
+      type: "placements.replaced",
+      source
+    });
+  }
+
+  function getContext() {
+    return sharedContext;
+  }
+
+  function setContext(value = {}, { replace = false, source = "placement-context" } = {}) {
+    const next = isRecord(value) ? { ...value } : {};
+
+    let nextContext = next;
+    if (!replace) {
+      nextContext = {
+        ...sharedContext,
+        ...next
+      };
+    }
+
+    sharedContext = Object.freeze(nextContext);
+    debugLog("setContext", {
+      replace,
+      source,
+      keys: Object.keys(sharedContext)
+    });
+    notify({
+      type: "context.updated",
+      source
+    });
+    return sharedContext;
+  }
+
+  function subscribe(listener) {
+    if (typeof listener !== "function") {
+      return () => {};
+    }
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+
+  function getRevision() {
+    return revision;
+  }
+
+  function getPlacements({ surface = WEB_PLACEMENT_SURFACE_ANY, host = "", position = "", context = {} } = {}) {
+    const normalizedHost = normalizePlacementHost(host, { strict: false });
+    const normalizedPosition = normalizePlacementPosition(position, { strict: false });
+    if (!normalizedHost || !normalizedPosition) {
+      return Object.freeze([]);
+    }
+
+    const normalizedSurface = normalizeSurface(surface);
+    const baseContext = isRecord(context) ? { ...context } : {};
+    const contextFromRuntime = isRecord(sharedContext) ? sharedContext : {};
+    const contextFromContributors = resolveContextContributors(
+      app,
+      {
+        app,
+        surface: normalizedSurface,
+        host: normalizedHost,
+        position: normalizedPosition,
+        context: {
+          ...contextFromRuntime,
+          ...baseContext
+        }
+      },
+      runtimeLogger
+    );
+    const placementContext = {
+      ...contextFromContributors,
+      ...contextFromRuntime,
+      ...baseContext,
+      app,
+      surface: normalizedSurface,
+      host: normalizedHost,
+      position: normalizedPosition
+    };
+
+    debugLog("getPlacements:start", {
+      surface: normalizedSurface,
+      host: normalizedHost,
+      position: normalizedPosition,
+      contextKeys: Object.keys(baseContext),
+      sharedContextKeys: Object.keys(contextFromRuntime),
+      placementCount: placementDefinitions.length
+    });
+
+    const matches = [];
+    for (const placement of placementDefinitions) {
+      if (placement.host !== normalizedHost || placement.position !== normalizedPosition) {
+        continue;
+      }
+      const placementSurfaces = Array.isArray(placement.surfaces)
+        ? placement.surfaces
+        : [WEB_PLACEMENT_SURFACE_ANY];
+
+      if (!matchesSurface(placementSurfaces, normalizedSurface)) {
+        debugLog("getPlacements:skip-surfaces", {
+          placementId: placement.id,
+          placementSurfaces,
+          requestedSurface: normalizedSurface
+        });
+        continue;
+      }
+      if (!shouldIncludePlacement(placement, placementContext, runtimeLogger)) {
+        debugLog("getPlacements:skip-when", {
+          placementId: placement.id
+        });
+        continue;
+      }
+
+      const component = resolvePlacementComponent(
+        app,
+        placement,
+        runtimeLogger,
+        missingTokens,
+        invalidComponentTokens,
+        failedTokens
+      );
+      if (!component) {
+        debugLog("getPlacements:skip-component", {
+          placementId: placement.id,
+          componentToken: placement.componentToken
+        });
+        continue;
+      }
+
+      debugLog("getPlacements:include", {
+        placementId: placement.id,
+        componentToken: placement.componentToken,
+        placementSurfaces,
+        order: placement.order
+      });
+
+      matches.push(
+        Object.freeze({
+          ...placement,
+          component
+        })
+      );
+    }
+
+    debugLog("getPlacements:done", {
+      surface: normalizedSurface,
+      host: normalizedHost,
+      position: normalizedPosition,
+      resultIds: matches.map((entry) => entry.id)
+    });
+
+    return Object.freeze(matches);
+  }
+
+  return Object.freeze({
+    replacePlacements,
+    getPlacements,
+    getContext,
+    setContext,
+    subscribe,
+    getRevision
+  });
+}
+
+export { createWebPlacementRuntime };

package/src/client/placement/surfaceContext.js

@@ -0,0 +1,290 @@
+import {
+  createSurfacePathHelpers,
+  deriveSurfaceRouteBaseFromPagesRoot,
+  normalizeSurfaceId,
+  normalizeSurfacePagesRoot
+} from "@jskit-ai/kernel/shared/surface";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizePathname } from "@jskit-ai/kernel/shared/surface/paths";
+import { isExternalLinkTarget, splitPathQueryHash } from "@jskit-ai/kernel/shared/support/linkPath";
+
+const EMPTY_SURFACE_CONFIG = Object.freeze({
+  tenancyMode: "",
+  defaultSurfaceId: "",
+  enabledSurfaceIds: Object.freeze([]),
+  surfacesById: Object.freeze({})
+});
+
+function normalizeSurfaceIdList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const seen = new Set();
+  const normalized = [];
+  for (const candidate of value) {
+    const surfaceId = normalizeSurfaceId(candidate);
+    if (!surfaceId || seen.has(surfaceId)) {
+      continue;
+    }
+    seen.add(surfaceId);
+    normalized.push(surfaceId);
+  }
+  return normalized;
+}
+
+function normalizeSurfaceConfig(surfaceConfig = {}) {
+  const source = isRecord(surfaceConfig) ? surfaceConfig : {};
+  const enabledSurfaceIds = normalizeSurfaceIdList(source.enabledSurfaceIds);
+  const enabledSet = new Set(enabledSurfaceIds);
+  const rawSurfacesById = isRecord(source.surfacesById) ? source.surfacesById : {};
+  const normalizedSurfacesById = {};
+
+  for (const [rawSurfaceId, rawDefinition] of Object.entries(rawSurfacesById)) {
+    const definition = isRecord(rawDefinition) ? rawDefinition : {};
+    const surfaceId = normalizeSurfaceId(definition.id || rawSurfaceId);
+    if (!surfaceId) {
+      continue;
+    }
+
+    const pagesRoot = normalizeSurfacePagesRoot(definition.pagesRoot);
+    const routeBase = String(
+      definition.routeBase || deriveSurfaceRouteBaseFromPagesRoot(pagesRoot)
+    ).trim() || "/";
+    const enabled = enabledSet.size > 0 ? enabledSet.has(surfaceId) : definition.enabled !== false;
+    normalizedSurfacesById[surfaceId] = Object.freeze({
+      ...definition,
+      id: surfaceId,
+      pagesRoot,
+      routeBase,
+      enabled
+    });
+  }
+
+  const derivedEnabledSurfaceIds =
+    enabledSurfaceIds.length > 0
+      ? enabledSurfaceIds.filter((surfaceId) => Boolean(normalizedSurfacesById[surfaceId]))
+      : Object.values(normalizedSurfacesById)
+          .filter((definition) => definition.enabled)
+          .map((definition) => definition.id);
+  const defaultSurfaceId = normalizeSurfaceId(source.defaultSurfaceId);
+  const resolvedDefaultSurfaceId = normalizedSurfacesById[defaultSurfaceId]
+    ? defaultSurfaceId
+    : derivedEnabledSurfaceIds[0] || Object.keys(normalizedSurfacesById)[0] || "";
+
+  return Object.freeze({
+    tenancyMode: String(source.tenancyMode || "").trim().toLowerCase(),
+    defaultSurfaceId: resolvedDefaultSurfaceId,
+    enabledSurfaceIds: Object.freeze([...derivedEnabledSurfaceIds]),
+    surfacesById: Object.freeze({
+      ...normalizedSurfacesById
+    })
+  });
+}
+
+function buildSurfaceConfigContext(surfaceRuntime = null, { tenancyMode = "" } = {}) {
+  const normalizedTenancyMode = String(tenancyMode || "").trim().toLowerCase();
+  if (!isRecord(surfaceRuntime)) {
+    return normalizeSurfaceConfig({
+      tenancyMode: normalizedTenancyMode
+    });
+  }
+
+  const surfaceDefinitions =
+    typeof surfaceRuntime.listSurfaceDefinitions === "function" ? surfaceRuntime.listSurfaceDefinitions() : [];
+  const surfacesById = {};
+  for (const definition of Array.isArray(surfaceDefinitions) ? surfaceDefinitions : []) {
+    if (!isRecord(definition)) {
+      continue;
+    }
+
+    const surfaceId = normalizeSurfaceId(definition.id);
+    if (!surfaceId) {
+      continue;
+    }
+    surfacesById[surfaceId] = definition;
+  }
+
+  return normalizeSurfaceConfig({
+    tenancyMode: normalizedTenancyMode,
+    defaultSurfaceId: surfaceRuntime.DEFAULT_SURFACE_ID,
+    enabledSurfaceIds:
+      typeof surfaceRuntime.listEnabledSurfaceIds === "function" ? surfaceRuntime.listEnabledSurfaceIds() : [],
+    surfacesById
+  });
+}
+
+function readPlacementSurfaceConfig(contextValue = null) {
+  const contextRecord = isRecord(contextValue) ? contextValue : {};
+  return normalizeSurfaceConfig(contextRecord.surfaceConfig);
+}
+
+function resolveSurfaceDefinitionFromPlacementContext(contextValue = null, surfaceId = "") {
+  const surfaceConfig = readPlacementSurfaceConfig(contextValue);
+  const normalizedSurfaceId = normalizeSurfaceId(surfaceId);
+  if (!normalizedSurfaceId) {
+    return null;
+  }
+  return surfaceConfig.surfacesById[normalizedSurfaceId] || null;
+}
+
+function joinSurfacePath(surfacePrefix = "", pathname = "") {
+  const normalizedPrefix = normalizePathname(surfacePrefix || "/");
+  const rawPathname = String(pathname || "").trim();
+  if (!rawPathname) {
+    return normalizedPrefix;
+  }
+
+  const withLeadingSlash = rawPathname.startsWith("/") ? rawPathname : `/${rawPathname}`;
+  const normalizedPathname = withLeadingSlash.replace(/\/{2,}/g, "/");
+  const joined = normalizedPrefix === "/" ? normalizedPathname : `${normalizedPrefix}${normalizedPathname}`;
+  const compacted = joined.replace(/\/{2,}/g, "/");
+  if (!compacted) {
+    return "/";
+  }
+  return compacted === "/" ? compacted : compacted.replace(/\/+$/, "") || "/";
+}
+
+function resolveSurfaceRootPathFromPlacementContext(contextValue = null, surfaceId = "") {
+  const surfaceDefinition = resolveSurfaceDefinitionFromPlacementContext(contextValue, surfaceId);
+  return joinSurfacePath(surfaceDefinition?.routeBase, "");
+}
+
+function resolveSurfacePathFromPlacementContext(contextValue = null, surfaceId = "", pathname = "") {
+  const surfaceDefinition = resolveSurfaceDefinitionFromPlacementContext(contextValue, surfaceId);
+  return joinSurfacePath(surfaceDefinition?.routeBase, pathname);
+}
+
+function normalizeSurfaceOrigin(originValue = "") {
+  const rawOrigin = String(originValue || "").trim();
+  if (!rawOrigin) {
+    return "";
+  }
+
+  try {
+    const parsed = new URL(rawOrigin);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return "";
+    }
+    return parsed.origin;
+  } catch {
+    return "";
+  }
+}
+
+function resolveRuntimeOrigin(currentOrigin = "") {
+  const normalizedCurrentOrigin = normalizeSurfaceOrigin(currentOrigin);
+  if (normalizedCurrentOrigin) {
+    return normalizedCurrentOrigin;
+  }
+
+  if (typeof window === "object" && window?.location?.origin) {
+    return normalizeSurfaceOrigin(window.location.origin);
+  }
+
+  return "";
+}
+
+function resolveSurfaceNavigationTargetFromPlacementContext(
+  contextValue = null,
+  {
+    path = "/",
+    surfaceId = "",
+    currentOrigin = ""
+  } = {}
+) {
+  const rawPath = String(path || "").trim() || "/";
+  if (isExternalLinkTarget(rawPath)) {
+    return Object.freeze({
+      href: rawPath,
+      sameOrigin: false,
+      surfaceId: normalizeSurfaceId(surfaceId),
+      external: true
+    });
+  }
+
+  const { pathname, search, hash } = splitPathQueryHash(rawPath);
+  const normalizedPathname = normalizePathname(pathname || "/");
+  const normalizedPath = `${normalizedPathname}${search}${hash}`;
+  const resolvedSurfaceId =
+    normalizeSurfaceId(surfaceId) ||
+    resolveSurfaceIdFromPlacementPathname(contextValue, normalizedPathname) ||
+    "";
+  const surfaceDefinition = resolvedSurfaceId
+    ? resolveSurfaceDefinitionFromPlacementContext(contextValue, resolvedSurfaceId)
+    : null;
+  const targetOrigin = normalizeSurfaceOrigin(surfaceDefinition?.origin || "");
+  const runtimeOrigin = resolveRuntimeOrigin(currentOrigin);
+
+  if (!targetOrigin) {
+    return Object.freeze({
+      href: normalizedPath,
+      sameOrigin: true,
+      surfaceId: resolvedSurfaceId,
+      external: false
+    });
+  }
+
+  if (runtimeOrigin && targetOrigin === runtimeOrigin) {
+    return Object.freeze({
+      href: normalizedPath,
+      sameOrigin: true,
+      surfaceId: resolvedSurfaceId,
+      external: false
+    });
+  }
+
+  return Object.freeze({
+    href: `${targetOrigin}${normalizedPath}`,
+    sameOrigin: false,
+    surfaceId: resolvedSurfaceId,
+    external: false
+  });
+}
+
+function createPlacementSurfacePathHelpers(surfaceConfig = EMPTY_SURFACE_CONFIG) {
+  const surfacesById = isRecord(surfaceConfig.surfacesById) ? surfaceConfig.surfacesById : {};
+  const defaultSurfaceId = normalizeSurfaceId(surfaceConfig.defaultSurfaceId);
+  const fallbackSurfaceId = Object.keys(surfacesById)[0] || "";
+  const resolvedDefaultSurfaceId = defaultSurfaceId && surfacesById[defaultSurfaceId] ? defaultSurfaceId : fallbackSurfaceId;
+  if (!resolvedDefaultSurfaceId) {
+    return null;
+  }
+
+  return createSurfacePathHelpers({
+    defaultSurfaceId: resolvedDefaultSurfaceId,
+    normalizeSurfaceId,
+    resolveSurfaceRouteBase(surfaceId) {
+      const normalizedSurfaceId = normalizeSurfaceId(surfaceId);
+      return String(surfacesById[normalizedSurfaceId]?.routeBase || "/").trim() || "/";
+    },
+    listSurfaceDefinitions() {
+      return Object.values(surfacesById);
+    }
+  });
+}
+
+function resolveSurfaceIdFromPlacementPathname(contextValue = null, pathname = "") {
+  const surfaceConfig = readPlacementSurfaceConfig(contextValue);
+  const normalizedPathname =
+    normalizePathname(pathname) ||
+    (typeof window === "object" && window?.location?.pathname ? normalizePathname(window.location.pathname) : "/");
+  const pathHelpers = createPlacementSurfacePathHelpers(surfaceConfig);
+  if (!pathHelpers) {
+    return "";
+  }
+  return pathHelpers.resolveSurfaceFromPathname(normalizedPathname);
+}
+
+export {
+  EMPTY_SURFACE_CONFIG,
+  buildSurfaceConfigContext,
+  readPlacementSurfaceConfig,
+  resolveSurfaceDefinitionFromPlacementContext,
+  joinSurfacePath,
+  resolveSurfaceIdFromPlacementPathname,
+  resolveSurfaceRootPathFromPlacementContext,
+  resolveSurfacePathFromPlacementContext,
+  normalizeSurfaceOrigin,
+  resolveSurfaceNavigationTargetFromPlacementContext
+};