@jskit-ai/shell-web 0.1.64 → 0.1.66

package/src/client/placement/index.js

@@ -2,6 +2,11 @@ export {
   createPlacementRegistry
 } from "./registry.js";
 
+export {
+  definePlacement,
+  definePlacementTopology
+} from "./validators.js";
+
 export {
   useWebPlacementContext
 } from "./inject.js";

package/src/client/placement/runtime.js

@@ -1,6 +1,10 @@
 import { DEFAULT_DEBUG_DEPTH, explodePayload } from "./debug.js";
 import { createListenerSubscription } from "@jskit-ai/kernel/shared/support/listenerSet";
 import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  normalizePlacementLayoutClass,
+  normalizePlacementTopologyDefinition
+} from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
 import {
   isRenderableComponent,
   normalizePlacementDefinition,
@@ -100,6 +104,40 @@ function normalizePlacementList(placements, context = {}) {
     .map((entry) => entry.placement);
 }
 
+function normalizeTopologyList(topology, context = {}) {
+  if (Array.isArray(topology)) {
+    const normalized = normalizePlacementTopologyDefinition(
+      { placements: topology },
+      {
+        context: context.source || "placement topology"
+      }
+    );
+    return normalizeTopologyList(normalized, context);
+  }
+
+  const candidates = ensureArray(topology);
+  const entries = [];
+  for (const candidate of candidates) {
+    const normalized = normalizePlacementTopologyDefinition(candidate, {
+      context: context.source || "placement topology"
+    });
+    entries.push(...normalized.placements);
+  }
+
+  const byKey = new Map();
+  for (const entry of entries) {
+    const key = `${entry.id}::${entry.owner || ""}`;
+    if (byKey.has(key)) {
+      throw new Error(
+        `Duplicate semantic placement "${entry.id}"${entry.owner ? ` for owner "${entry.owner}"` : ""} in ${context.source || "placement topology"}.`
+      );
+    }
+    byKey.set(key, entry);
+  }
+
+  return Object.freeze([...byKey.values()]);
+}
+
 function matchesSurface(placementSurfaces, requestedSurface) {
   if (requestedSurface === WEB_PLACEMENT_SURFACE_ANY) {
     return true;
@@ -108,6 +146,67 @@ function matchesSurface(placementSurfaces, requestedSurface) {
   return surfaces.includes(WEB_PLACEMENT_SURFACE_ANY) || surfaces.includes(requestedSurface);
 }
 
+function resolveTopologyPlacement(topologyEntries = [], placement = {}, requestedSurface = WEB_PLACEMENT_SURFACE_ANY) {
+  const semanticTarget = String(placement.target || "").trim();
+  const owner = String(placement.owner || "").trim();
+  const matches = topologyEntries.filter((entry) => {
+    if (entry.id !== semanticTarget) {
+      return false;
+    }
+    if (owner && entry.owner !== owner) {
+      return false;
+    }
+    if (!owner && entry.owner) {
+      return false;
+    }
+    return matchesSurface(entry.surfaces, requestedSurface);
+  });
+
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  return null;
+}
+
+function resolveRenderablePlacement({
+  placement = {},
+  topologyEntries = [],
+  requestedSurface = WEB_PLACEMENT_SURFACE_ANY,
+  requestedTarget = "",
+  requestedLayoutClass = "compact"
+} = {}) {
+  if (placement.targetType === "concrete") {
+    if (placement.target !== requestedTarget) {
+      return null;
+    }
+    return placement;
+  }
+
+  const topologyPlacement = resolveTopologyPlacement(topologyEntries, placement, requestedSurface);
+  if (!topologyPlacement) {
+    return null;
+  }
+
+  const variant = topologyPlacement.variants?.[requestedLayoutClass] || null;
+  if (!variant || variant.outlet !== requestedTarget) {
+    return null;
+  }
+
+  const componentToken = String(placement.componentToken || variant.renderers?.[placement.kind] || "").trim();
+  if (!componentToken) {
+    return null;
+  }
+
+  return Object.freeze({
+    ...placement,
+    target: requestedTarget,
+    semanticTarget: placement.target,
+    topologyOwner: topologyPlacement.owner || "",
+    layoutClass: requestedLayoutClass,
+    componentToken
+  });
+}
+
 function resolveContextContributors(app, baseContext = {}, logger) {
   const contributors = app.resolveTag("web-placement.context.client");
   let merged = {};
@@ -232,6 +331,7 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
   const listeners = new Set();
   const subscribe = createListenerSubscription(listeners);
   let placementDefinitions = Object.freeze([]);
+  let placementTopology = Object.freeze([]);
   let sharedContext = Object.freeze({});
   let revision = 0;
 
@@ -276,6 +376,22 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
     });
   }
 
+  function replacePlacementTopology(topology = [], { source = "app placement topology" } = {}) {
+    missingTokens.clear();
+    invalidComponentTokens.clear();
+    failedTokens.clear();
+    placementTopology = normalizeTopologyList(topology, { source });
+    debugLog("replacePlacementTopology", {
+      source,
+      count: placementTopology.length,
+      ids: placementTopology.map((entry) => entry.owner ? `${entry.id}#${entry.owner}` : entry.id)
+    });
+    notify({
+      type: "placement-topology.replaced",
+      source
+    });
+  }
+
   function getContext() {
     return sharedContext;
   }
@@ -308,13 +424,17 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
     return revision;
   }
 
-  function getPlacements({ surface = WEB_PLACEMENT_SURFACE_ANY, target = "", context = {} } = {}) {
+  function getPlacements({ surface = WEB_PLACEMENT_SURFACE_ANY, target = "", layoutClass = "", context = {} } = {}) {
     const normalizedTarget = normalizePlacementTarget(target, { strict: false });
     if (!normalizedTarget) {
       return Object.freeze([]);
     }
 
     const normalizedSurface = normalizeSurface(surface);
+    const normalizedLayoutClass =
+      normalizePlacementLayoutClass(layoutClass) ||
+      normalizePlacementLayoutClass(sharedContext?.layoutClass) ||
+      "compact";
     const baseContext = isRecord(context) ? { ...context } : {};
     const contextFromRuntime = isRecord(sharedContext) ? sharedContext : {};
     const contextFromContributors = resolveContextContributors(
@@ -323,6 +443,7 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
         app,
         surface: normalizedSurface,
         target: normalizedTarget,
+        layoutClass: normalizedLayoutClass,
         context: {
           ...contextFromRuntime,
           ...baseContext
@@ -336,44 +457,54 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
       ...baseContext,
       app,
       surface: normalizedSurface,
-      target: normalizedTarget
+      target: normalizedTarget,
+      layoutClass: normalizedLayoutClass
     };
 
     debugLog("getPlacements:start", {
       surface: normalizedSurface,
       target: normalizedTarget,
+      layoutClass: normalizedLayoutClass,
       contextKeys: Object.keys(baseContext),
       sharedContextKeys: Object.keys(contextFromRuntime),
-      placementCount: placementDefinitions.length
+      placementCount: placementDefinitions.length,
+      topologyCount: placementTopology.length
     });
 
     const matches = [];
     for (const placement of placementDefinitions) {
-      if (placement.target !== normalizedTarget) {
+      const renderablePlacement = resolveRenderablePlacement({
+        placement,
+        topologyEntries: placementTopology,
+        requestedSurface: normalizedSurface,
+        requestedTarget: normalizedTarget,
+        requestedLayoutClass: normalizedLayoutClass
+      });
+      if (!renderablePlacement) {
         continue;
       }
-      const placementSurfaces = Array.isArray(placement.surfaces)
-        ? placement.surfaces
+      const placementSurfaces = Array.isArray(renderablePlacement.surfaces)
+        ? renderablePlacement.surfaces
         : [WEB_PLACEMENT_SURFACE_ANY];
 
       if (!matchesSurface(placementSurfaces, normalizedSurface)) {
         debugLog("getPlacements:skip-surfaces", {
-          placementId: placement.id,
+          placementId: renderablePlacement.id,
           placementSurfaces,
           requestedSurface: normalizedSurface
         });
         continue;
       }
-      if (!shouldIncludePlacement(placement, placementContext, runtimeLogger)) {
+      if (!shouldIncludePlacement(renderablePlacement, placementContext, runtimeLogger)) {
         debugLog("getPlacements:skip-when", {
-          placementId: placement.id
+          placementId: renderablePlacement.id
         });
         continue;
       }
 
       const component = resolvePlacementComponent(
         app,
-        placement,
+        renderablePlacement,
         runtimeLogger,
         missingTokens,
         invalidComponentTokens,
@@ -381,22 +512,22 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
       );
       if (!component) {
         debugLog("getPlacements:skip-component", {
-          placementId: placement.id,
-          componentToken: placement.componentToken
+          placementId: renderablePlacement.id,
+          componentToken: renderablePlacement.componentToken
         });
         continue;
       }
 
       debugLog("getPlacements:include", {
-        placementId: placement.id,
-        componentToken: placement.componentToken,
+        placementId: renderablePlacement.id,
+        componentToken: renderablePlacement.componentToken,
         placementSurfaces,
-        order: placement.order
+        order: renderablePlacement.order
       });
 
       matches.push(
         Object.freeze({
-          ...placement,
+          ...renderablePlacement,
           component
         })
       );
@@ -405,6 +536,7 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
     debugLog("getPlacements:done", {
       surface: normalizedSurface,
       target: normalizedTarget,
+      layoutClass: normalizedLayoutClass,
       resultIds: matches.map((entry) => entry.id)
     });
 
@@ -413,6 +545,7 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
 
   return Object.freeze({
     replacePlacements,
+    replacePlacementTopology,
     getPlacements,
     getContext,
     setContext,

package/src/client/placement/validators.js

@@ -1,5 +1,10 @@
 import { isRecord, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import { normalizeShellOutletTargetId } from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
+import {
+  normalizePlacementKind,
+  normalizePlacementTopologyDefinition,
+  normalizeSemanticPlacementId,
+  resolvePlacementTargetReference
+} from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
 
 const WEB_PLACEMENT_SURFACE_ANY = "*";
 
@@ -57,13 +62,13 @@ function toInteger(value, fallback = 1000) {
 }
 
 function normalizePlacementTarget(value, { strict = false, source = "placement" } = {}) {
-  const normalized = normalizeShellOutletTargetId(String(value || "").toLowerCase());
-  if (normalized) {
-    return normalized;
+  const reference = resolvePlacementTargetReference(String(value || "").toLowerCase());
+  if (reference?.id) {
+    return reference.id;
   }
 
   if (strict) {
-    throw new TypeError(`${source} requires target in "host:position" format.`);
+    throw new TypeError(`${source} requires semantic target in "area.slot" format or internal concrete target in "host:position" format.`);
   }
   return "";
 }
@@ -132,8 +137,19 @@ function normalizePlacementDefinition(value, { strict = false, source = "placeme
     return null;
   }
 
+  const targetReference = resolvePlacementTargetReference(target);
+  const internal = value.internal === true;
+  if (targetReference?.type === "concrete" && internal !== true) {
+    if (strict) {
+      throw new TypeError(`${source} "${id}" targets concrete outlet "${target}" without internal: true.`);
+    }
+    return null;
+  }
+
+  const owner = normalizeText(value.owner).toLowerCase();
+  const kind = normalizePlacementKind(value.kind) || (normalizeText(value.componentToken) ? "component" : "link");
   const componentToken = normalizeText(value.componentToken);
-  if (!componentToken) {
+  if (kind === "component" && !componentToken) {
     if (strict) {
       throw new TypeError(`${source} "${id}" requires componentToken.`);
     }
@@ -150,12 +166,16 @@ function normalizePlacementDefinition(value, { strict = false, source = "placeme
   return Object.freeze({
     id,
     target,
+    targetType: targetReference?.type || "",
+    owner,
+    kind,
     surfaces,
     order: toInteger(value.order, 1000),
     componentToken,
     props,
     when,
-    enabled: value.enabled !== false
+    enabled: value.enabled !== false,
+    internal
   });
 }
 
@@ -166,6 +186,12 @@ function definePlacement(value = {}) {
   });
 }
 
+function definePlacementTopology(value = {}) {
+  return normalizePlacementTopologyDefinition(value, {
+    context: "placement topology"
+  });
+}
+
 export {
   isRecord,
   isRenderableComponent,
@@ -174,5 +200,7 @@ export {
   normalizePlacementTarget,
   normalizePlacementSurfaces,
   normalizePlacementDefinition,
-  definePlacement
+  definePlacement,
+  definePlacementTopology,
+  normalizeSemanticPlacementId
 };

package/src/client/providers/ShellWebClientProvider.js

@@ -1,11 +1,8 @@
 import { getClientAppConfig } from "@jskit-ai/kernel/client";
 import {
-  isRecord,
-  shouldRetryTransientQueryFailure,
-  transientQueryRetryDelay
+  isRecord
 } from "@jskit-ai/kernel/shared/support";
 import { createProviderLogger as createSharedProviderLogger } from "@jskit-ai/kernel/shared/support/providerLogger";
-import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
 import {
   createDefaultErrorPolicy
 } from "../error/policy.js";
@@ -30,21 +27,9 @@ import { resolveBootstrapErrorStatusCode } from "../bootstrap/bootstrapErrorStat
 
 // Keep this constant for diagnostics, but keep import() below as a literal string so Vite can statically analyze it.
 const APP_PLACEMENT_MODULE_SPECIFIER = "/src/placement.js";
+const APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER = "/src/placementTopology.js";
 const APP_ERROR_MODULE_SPECIFIER = "/src/error.js";
 
-function createShellWebQueryClient() {
-  return new QueryClient({
-    defaultOptions: {
-      queries: {
-        refetchOnWindowFocus: false,
-        refetchOnReconnect: true,
-        retry: shouldRetryTransientQueryFailure,
-        retryDelay: transientQueryRetryDelay
-      }
-    }
-  });
-}
-
 function isMissingDynamicModule(error, moduleSpecifier) {
   const message = String(error?.message || error || "");
   return (
@@ -88,6 +73,47 @@ async function loadAppPlacementDefinitions(logger) {
   return [];
 }
 
+async function loadAppPlacementTopology(logger) {
+  try {
+    const moduleNamespace = await import("/src/placementTopology.js");
+    const exported = moduleNamespace?.default;
+    return resolveAppPlacementTopologyExport(exported, logger);
+  } catch (error) {
+    if (isMissingDynamicModule(error, APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER)) {
+      return [];
+    }
+
+    logger.warn(
+      {
+        module: APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER,
+        error: String(error?.message || error || "unknown error")
+      },
+      "Failed to load app placement topology module; using empty topology."
+    );
+  }
+
+  return [];
+}
+
+function resolveAppPlacementTopologyExport(exported, logger) {
+  const resolved = typeof exported === "function" ? exported() : exported;
+  if (Array.isArray(resolved)) {
+    return resolved;
+  }
+  if (resolved && typeof resolved === "object") {
+    return resolved;
+  }
+
+  logger.warn(
+    {
+      module: APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER,
+      exportedType: typeof exported
+    },
+    "App placement topology module default export did not resolve to an object or array; using empty topology."
+  );
+  return [];
+}
+
 function createErrorConfigToolkit(errorRuntime) {
   return Object.freeze({
     createDefaultErrorPolicy,
@@ -160,6 +186,136 @@ function applyAppErrorConfig(errorRuntime, errorConfig = {}) {
   errorRuntime.assertBootReady();
 }
 
+function isPullRefreshQuery(query = null) {
+  const meta = isRecord(query?.meta) ? query.meta : {};
+  if (meta.jskitRefresh === "pull") {
+    return true;
+  }
+  if (meta.jskitRefresh === false) {
+    return false;
+  }
+
+  const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
+  return jskitMeta.refreshOnPull !== false;
+}
+
+function createShellRefreshRuntime({
+  app,
+  logger = null
+} = {}) {
+  if (!app || typeof app.has !== "function" || typeof app.make !== "function") {
+    throw new Error("createShellRefreshRuntime requires application has()/make().");
+  }
+
+  const runtimeLogger = logger || createSharedProviderLogger(app);
+  let refreshQueue = Promise.resolve(null);
+
+  async function refreshBootstrap(reason) {
+    if (!app.has("runtime.web-bootstrap.client")) {
+      return false;
+    }
+
+    const bootstrapRuntime = app.make("runtime.web-bootstrap.client");
+    if (!bootstrapRuntime || typeof bootstrapRuntime.refresh !== "function") {
+      return false;
+    }
+
+    await bootstrapRuntime.refresh(reason);
+    return true;
+  }
+
+  async function refetchPullQueries() {
+    if (!app.has("jskit.client.query-client")) {
+      return false;
+    }
+
+    const queryClient = app.make("jskit.client.query-client");
+    if (!queryClient || typeof queryClient.refetchQueries !== "function") {
+      return false;
+    }
+
+    await queryClient.refetchQueries(
+      {
+        type: "active",
+        predicate: isPullRefreshQuery
+      },
+      {
+        throwOnError: false
+      }
+    );
+    return true;
+  }
+
+  function reportRefreshFailure(error) {
+    runtimeLogger.warn(
+      {
+        error: String(error?.message || error || "unknown error")
+      },
+      "Shell refresh failed."
+    );
+
+    if (!app.has("runtime.web-error.client")) {
+      return;
+    }
+
+    const errorRuntime = app.make("runtime.web-error.client");
+    if (!errorRuntime || typeof errorRuntime.report !== "function") {
+      return;
+    }
+
+    errorRuntime.report({
+      source: "shell-web.refresh",
+      message: "Unable to refresh. Check the connection and try again.",
+      intent: "app-recoverable",
+      severity: "error",
+      dedupeKey: "shell-web.refresh.failed",
+      dedupeWindowMs: 2000,
+      action: {
+        label: "Retry",
+        dismissOnRun: true,
+        handler() {
+          void refresh("retry");
+        }
+      }
+    });
+  }
+
+  async function performRefresh(reason = "manual") {
+    const normalizedReason = String(reason || "manual").trim() || "manual";
+    try {
+      const [bootstrapRefreshed, queriesRefetched] = await Promise.all([
+        refreshBootstrap(normalizedReason),
+        refetchPullQueries()
+      ]);
+
+      return Object.freeze({
+        reason: normalizedReason,
+        bootstrapRefreshed,
+        queriesRefetched
+      });
+    } catch (error) {
+      reportRefreshFailure(error);
+      return Object.freeze({
+        reason: normalizedReason,
+        bootstrapRefreshed: false,
+        queriesRefetched: false,
+        error
+      });
+    }
+  }
+
+  function refresh(reason = "manual") {
+    refreshQueue = refreshQueue
+      .catch(() => null)
+      .then(() => performRefresh(reason));
+    return refreshQueue;
+  }
+
+  return Object.freeze({
+    refresh
+  });
+}
+
 function installVueErrorBridge(vueApp, errorRuntime, logger) {
   if (!vueApp || !isRecord(vueApp.config)) {
     return;
@@ -173,8 +329,8 @@ function installVueErrorBridge(vueApp, errorRuntime, logger) {
         source: "shell-web.vue.error-handler",
         message: String(error?.message || "Unexpected UI error."),
         cause: error,
+        intent: "blocking",
         severity: "error",
-        channel: "dialog",
         details: {
           info: String(info || "")
         }
@@ -211,8 +367,8 @@ function installRouterErrorBridge(app, errorRuntime, logger) {
         source: "shell-web.router.on-error",
         message: String(error?.message || "Navigation failed."),
         cause: error,
+        intent: "app-recoverable",
         severity: "error",
-        channel: "banner",
         dedupeKey: String(error?.message || "navigation-failed"),
         dedupeWindowMs: 2000
       });
@@ -275,7 +431,12 @@ class ShellWebClientProvider {
         logger
       })
     );
-    app.singleton("shell.web.query-client", () => createShellWebQueryClient());
+    app.singleton("runtime.web-refresh.client", (scope) =>
+      createShellRefreshRuntime({
+        app: scope,
+        logger
+      })
+    );
     app.singleton("runtime.web-error.presentation-store.client", () => createErrorPresentationStore());
     app.singleton("runtime.web-error.client", (scope) =>
       createErrorRuntime({
@@ -297,6 +458,10 @@ class ShellWebClientProvider {
     const logger = createSharedProviderLogger(isRecord(app) ? app : null);
     const placementRuntime = app.make("runtime.web-placement.client");
     if (placementRuntime && typeof placementRuntime.replacePlacements === "function") {
+      const placementTopology = await loadAppPlacementTopology(logger);
+      if (typeof placementRuntime.replacePlacementTopology === "function") {
+        placementRuntime.replacePlacementTopology(placementTopology, { source: APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER });
+      }
       const placements = await loadAppPlacementDefinitions(logger);
       placementRuntime.replacePlacements(placements, { source: APP_PLACEMENT_MODULE_SPECIFIER });
       const appConfig = getClientAppConfig();
@@ -343,12 +508,11 @@ class ShellWebClientProvider {
       throw new Error("ShellWebClientProvider requires Pinia installed in the client app.");
     }
     const errorPresentationStore = app.make("runtime.web-error.presentation-store.client");
+    const refreshRuntime = app.make("runtime.web-refresh.client");
     useShellErrorPresentationStore(pinia).attachRuntimeStore(errorPresentationStore);
 
-    vueApp.use(VueQueryPlugin, {
-      queryClient: app.make("shell.web.query-client")
-    });
     vueApp.provide("jskit.shell-web.runtime.web-placement.client", placementRuntime);
+    vueApp.provide("jskit.shell-web.runtime.web-refresh.client", refreshRuntime);
     vueApp.provide("jskit.shell-web.runtime.web-error.client", errorRuntime);
     vueApp.provide(
       "jskit.shell-web.runtime.web-error.presentation-store.client",
@@ -361,5 +525,6 @@ class ShellWebClientProvider {
 }
 
 export {
-  ShellWebClientProvider
+  ShellWebClientProvider,
+  resolveAppPlacementTopologyExport
 };