@jskit-ai/shell-web 0.1.4

package/test/linkResolver.test.js

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { resolveShellLinkPath } from "../src/client/navigation/linkResolver.js";
+
+function createPlacementContext() {
+  return {
+    surfaceConfig: {
+      tenancyMode: "workspace",
+      defaultSurfaceId: "app",
+      enabledSurfaceIds: ["app", "admin", "console"],
+      surfacesById: {
+        app: {
+          id: "app",
+          pagesRoot: "w/[workspaceSlug]",
+          routeBase: "/w/:workspaceSlug",
+          enabled: true,
+          requiresWorkspace: true
+        },
+        admin: {
+          id: "admin",
+          pagesRoot: "admin",
+          routeBase: "/admin",
+          enabled: true,
+          requiresWorkspace: true
+        },
+        console: {
+          id: "console",
+          pagesRoot: "console",
+          routeBase: "/console",
+          enabled: true,
+          requiresWorkspace: false
+        }
+      }
+    }
+  };
+}
+
+test("resolveShellLinkPath composes surface path for workspace-labeled surfaces", () => {
+  const to = resolveShellLinkPath({
+    context: createPlacementContext(),
+    surface: "admin",
+    relativePath: "/contacts/2"
+  });
+
+  assert.equal(to, "/admin/contacts/2");
+});
+
+test("resolveShellLinkPath materializes dynamic route params from params map", () => {
+  const to = resolveShellLinkPath({
+    context: createPlacementContext(),
+    surface: "app",
+    params: {
+      workspaceSlug: "acme"
+    },
+    relativePath: "/projects/2"
+  });
+
+  assert.equal(to, "/w/acme/projects/2");
+});
+
+test("resolveShellLinkPath fails when required route params are missing", () => {
+  assert.throws(
+    () =>
+      resolveShellLinkPath({
+        context: createPlacementContext(),
+        surface: "app",
+        relativePath: "/projects/2"
+      }),
+    /Missing required surface route params/
+  );
+});
+
+test("resolveShellLinkPath composes non-workspace path for non-workspace surface", () => {
+  const to = resolveShellLinkPath({
+    context: createPlacementContext(),
+    surface: "console",
+    relativePath: "/contacts"
+  });
+
+  assert.equal(to, "/console/contacts");
+});
+
+test("resolveShellLinkPath keeps explicit target unchanged", () => {
+  const to = resolveShellLinkPath({
+    context: createPlacementContext(),
+    surface: "admin",
+    explicitTo: "/custom/path"
+  });
+
+  assert.equal(to, "/custom/path");
+});
+
+test("resolveShellLinkPath prefers surfaceRelativePath when provided", () => {
+  const to = resolveShellLinkPath({
+    context: createPlacementContext(),
+    surface: "admin",
+    relativePath: "/ignored",
+    surfaceRelativePath: "/contacts"
+  });
+
+  assert.equal(to, "/admin/contacts");
+});
+
+test("resolveShellLinkPath uses deterministic surface fallback when context is missing", () => {
+  const to = resolveShellLinkPath({
+    context: null,
+    surface: "admin",
+    relativePath: "/contacts/5"
+  });
+
+  assert.equal(to, "/admin/contacts/5");
+});

package/test/placementRegistry.test.js

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createPlacementRegistry } from "../src/client/placement/registry.js";
+
+test("placement registry stores unique entries and builds immutable array", () => {
+  const registry = createPlacementRegistry();
+
+  const firstAdded = registry.addPlacement({
+    id: "example.profile",
+    host: "shell-layout",
+    position: "top-right",
+    surfaces: ["*"],
+    componentToken: "example.profile.component"
+  });
+  const duplicateAdded = registry.addPlacement({
+    id: "example.profile",
+    host: "shell-layout",
+    position: "top-right",
+    surfaces: ["*"],
+    componentToken: "example.profile.component.duplicate"
+  });
+
+  assert.equal(firstAdded, true);
+  assert.equal(duplicateAdded, false);
+  assert.equal(registry.hasPlacement("example.profile"), true);
+
+  const placements = registry.build();
+  assert.equal(Array.isArray(placements), true);
+  assert.equal(placements.length, 1);
+  assert.equal(placements[0].componentToken, "example.profile.component");
+});
+
+test("placement registry accepts explicit non-global surface ids", () => {
+  const registry = createPlacementRegistry();
+
+  const added = registry.addPlacement({
+    id: "example.admin",
+    host: "shell-layout",
+    position: "top-right",
+    surfaces: ["admin"],
+    componentToken: "example.admin.component"
+  });
+
+  assert.equal(added, true);
+});

package/test/placementRuntime.test.js

@@ -0,0 +1,374 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { definePlacement } from "../src/client/placement/validators.js";
+import { createWebPlacementRuntime } from "../src/client/placement/runtime.js";
+
+function createAppStub({ tokens = {}, contextContributors = [] } = {}) {
+  return {
+    has(token) {
+      return Object.prototype.hasOwnProperty.call(tokens, token);
+    },
+    make(token) {
+      if (!this.has(token)) {
+        throw new Error(`Unknown token: ${String(token)}`);
+      }
+      return tokens[token];
+    },
+    resolveTag(tagName) {
+      if (tagName === "web-placement.context.client") {
+        return contextContributors;
+      }
+      return [];
+    }
+  };
+}
+
+function createPlacementContext() {
+  return {
+    surfaceConfig: {
+      defaultSurfaceId: "app",
+      enabledSurfaceIds: ["app", "admin", "console"]
+    }
+  };
+}
+
+test("web placement runtime filters by surface/host/position, resolves component tokens, and sorts by order", () => {
+  const app = createAppStub({
+    tokens: {
+      "component.alerts": () => null,
+      "component.profile": () => null,
+      "component.menu": () => null
+    }
+  });
+
+  const runtime = createWebPlacementRuntime({ app });
+  runtime.replacePlacements([
+    definePlacement({
+      id: "test.menu",
+      host: "shell-layout",
+      position: "primary-menu",
+      surfaces: ["app"],
+      order: 30,
+      componentToken: "component.menu"
+    }),
+    definePlacement({
+      id: "test.profile",
+      host: "shell-layout",
+      position: "top-right",
+      surfaces: ["*"],
+      order: 20,
+      componentToken: "component.profile"
+    }),
+    definePlacement({
+      id: "test.alerts",
+      host: "shell-layout",
+      position: "top-right",
+      surfaces: ["app"],
+      order: 10,
+      componentToken: "component.alerts"
+    })
+  ]);
+  runtime.setContext(createPlacementContext());
+
+  const topRight = runtime.getPlacements({ surface: "app", host: "shell-layout", position: "top-right" });
+  assert.deepEqual(topRight.map((entry) => entry.id), ["test.alerts", "test.profile"]);
+  assert.equal(typeof topRight[0].component, "function");
+
+  const primaryMenu = runtime.getPlacements({ surface: "app", host: "shell-layout", position: "primary-menu" });
+  assert.deepEqual(primaryMenu.map((entry) => entry.id), ["test.menu"]);
+
+  const adminTopRight = runtime.getPlacements({ surface: "admin", host: "shell-layout", position: "top-right" });
+  assert.deepEqual(adminTopRight.map((entry) => entry.id), ["test.profile"]);
+});
+
+test("web placement runtime applies context contributors and placement when() predicates", () => {
+  const app = createAppStub({
+    tokens: {
+      "component.guest": () => null,
+      "component.authenticated": () => null
+    },
+    contextContributors: [
+      () => ({
+        auth: { authenticated: true }
+      })
+    ]
+  });
+
+  const runtime = createWebPlacementRuntime({ app });
+  runtime.replacePlacements([
+    definePlacement({
+      id: "guest.item",
+      host: "auth-profile-menu",
+      position: "primary-menu",
+      surfaces: ["*"],
+      componentToken: "component.guest",
+      when: ({ auth }) => !Boolean(auth?.authenticated)
+    }),
+    definePlacement({
+      id: "auth.item",
+      host: "auth-profile-menu",
+      position: "primary-menu",
+      surfaces: ["*"],
+      componentToken: "component.authenticated",
+      when: ({ auth }) => Boolean(auth?.authenticated)
+    })
+  ]);
+
+  const menu = runtime.getPlacements({ surface: "app", host: "auth-profile-menu", position: "primary-menu" });
+  assert.deepEqual(menu.map((entry) => entry.id), ["auth.item"]);
+});
+
+test("web placement runtime uses runtime context and local context overrides contributor values", () => {
+  const app = createAppStub({
+    tokens: {
+      "component.allowed": () => null
+    },
+    contextContributors: [
+      () => ({
+        auth: {
+          authenticated: false
+        }
+      })
+    ]
+  });
+
+  const runtime = createWebPlacementRuntime({ app });
+  runtime.replacePlacements([
+    definePlacement({
+      id: "allowed",
+      host: "auth-profile-menu",
+      position: "primary-menu",
+      surfaces: ["*"],
+      componentToken: "component.allowed",
+      when: ({ auth }) => Boolean(auth?.authenticated)
+    })
+  ]);
+
+  runtime.setContext({
+    auth: {
+      authenticated: true
+    }
+  });
+  const fromRuntime = runtime.getPlacements({ surface: "app", host: "auth-profile-menu", position: "primary-menu" });
+  assert.deepEqual(fromRuntime.map((entry) => entry.id), ["allowed"]);
+
+  const fromLocalOverride = runtime.getPlacements({
+    surface: "app",
+    host: "auth-profile-menu",
+    position: "primary-menu",
+    context: {
+      auth: {
+        authenticated: false
+      }
+    }
+  });
+  assert.deepEqual(fromLocalOverride.map((entry) => entry.id), []);
+});
+
+test("web placement runtime notifies subscribers on placement and context updates", () => {
+  const app = createAppStub();
+  const runtime = createWebPlacementRuntime({ app });
+  const events = [];
+  const unsubscribe = runtime.subscribe((event) => {
+    events.push(event.type);
+  });
+
+  runtime.replacePlacements([]);
+  runtime.setContext({
+    auth: {
+      authenticated: true
+    }
+  });
+
+  unsubscribe();
+  runtime.setContext({
+    auth: {
+      authenticated: false
+    }
+  });
+
+  assert.deepEqual(events, ["placements.replaced", "context.updated"]);
+});
+
+test("web placement runtime rejects duplicate placement ids", () => {
+  const app = createAppStub();
+  const runtime = createWebPlacementRuntime({ app });
+
+  assert.throws(() => {
+    runtime.replacePlacements([
+      definePlacement({
+        id: "dup.entry",
+        host: "shell-layout",
+        position: "top-right",
+        surfaces: ["*"],
+        componentToken: "component.a"
+      }),
+      definePlacement({
+        id: "dup.entry",
+        host: "shell-layout",
+        position: "primary-menu",
+        surfaces: ["*"],
+        componentToken: "component.b"
+      })
+    ]);
+  }, /Duplicate placement id/);
+});
+
+test("web placement runtime skips throwing component tokens and logs resolution errors once", () => {
+  const app = {
+    has(token) {
+      return token === "component.bad" || token === "component.good";
+    },
+    make(token) {
+      if (token === "component.bad") {
+        throw new Error("bad component token");
+      }
+      if (token === "component.good") {
+        return () => null;
+      }
+      throw new Error(`Unknown token: ${String(token)}`);
+    },
+    resolveTag() {
+      return [];
+    }
+  };
+
+  const errors = [];
+  const runtime = createWebPlacementRuntime({
+    app,
+    logger: {
+      warn() {},
+      error(payload, message) {
+        errors.push({ payload, message });
+      }
+    }
+  });
+
+  runtime.replacePlacements([
+    definePlacement({
+      id: "bad",
+      host: "shell-layout",
+      position: "top-right",
+      surfaces: ["*"],
+      componentToken: "component.bad"
+    }),
+    definePlacement({
+      id: "good",
+      host: "shell-layout",
+      position: "top-right",
+      surfaces: ["*"],
+      componentToken: "component.good"
+    })
+  ]);
+
+  const first = runtime.getPlacements({ surface: "app", host: "shell-layout", position: "top-right" });
+  assert.deepEqual(first.map((entry) => entry.id), ["good"]);
+  assert.equal(errors.length, 1);
+
+  const second = runtime.getPlacements({ surface: "app", host: "shell-layout", position: "top-right" });
+  assert.deepEqual(second.map((entry) => entry.id), ["good"]);
+  assert.equal(errors.length, 1);
+});
+
+test("web placement runtime clears failed token cache when placements are replaced", () => {
+  let shouldThrow = true;
+  const app = {
+    has(token) {
+      return token === "component.toggle";
+    },
+    make(token) {
+      if (token !== "component.toggle") {
+        throw new Error(`Unknown token: ${String(token)}`);
+      }
+      if (shouldThrow) {
+        throw new Error("toggle failure");
+      }
+      return () => null;
+    },
+    resolveTag() {
+      return [];
+    }
+  };
+
+  const runtime = createWebPlacementRuntime({
+    app,
+    logger: {
+      warn() {},
+      error() {}
+    }
+  });
+
+  runtime.replacePlacements([
+    definePlacement({
+      id: "toggle",
+      host: "shell-layout",
+      position: "top-right",
+      surfaces: ["*"],
+      componentToken: "component.toggle"
+    })
+  ]);
+
+  const initial = runtime.getPlacements({ surface: "app", host: "shell-layout", position: "top-right" });
+  assert.equal(initial.length, 0);
+
+  shouldThrow = false;
+  const stillSkipped = runtime.getPlacements({ surface: "app", host: "shell-layout", position: "top-right" });
+  assert.equal(stillSkipped.length, 0);
+
+  runtime.replacePlacements([
+    definePlacement({
+      id: "toggle",
+      host: "shell-layout",
+      position: "top-right",
+      surfaces: ["*"],
+      componentToken: "component.toggle"
+    })
+  ]);
+
+  const recovered = runtime.getPlacements({ surface: "app", host: "shell-layout", position: "top-right" });
+  assert.equal(recovered.length, 1);
+});
+
+test("web placement runtime follows explicit surface targeting without role indirection", () => {
+  const app = createAppStub({
+    tokens: {
+      "component.global": () => null,
+      "component.app": () => null,
+      "component.admin": () => null
+    }
+  });
+  const runtime = createWebPlacementRuntime({ app });
+  runtime.replacePlacements([
+    definePlacement({
+      id: "global.banner",
+      host: "shell-layout",
+      position: "top-right",
+      surfaces: ["*"],
+      order: 10,
+      componentToken: "component.global"
+    }),
+    definePlacement({
+      id: "app.link",
+      host: "shell-layout",
+      position: "top-right",
+      surfaces: ["app"],
+      order: 20,
+      componentToken: "component.app"
+    }),
+    definePlacement({
+      id: "admin.link",
+      host: "shell-layout",
+      position: "top-right",
+      surfaces: ["admin"],
+      order: 30,
+      componentToken: "component.admin"
+    })
+  ]);
+  runtime.setContext(createPlacementContext());
+
+  const appEntries = runtime.getPlacements({ surface: "app", host: "shell-layout", position: "top-right" });
+  assert.deepEqual(appEntries.map((placement) => placement.id), ["global.banner", "app.link"]);
+
+  const adminEntries = runtime.getPlacements({ surface: "admin", host: "shell-layout", position: "top-right" });
+  assert.deepEqual(adminEntries.map((placement) => placement.id), ["global.banner", "admin.link"]);
+});

package/test/provider.test.js

@@ -0,0 +1,163 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { ShellWebClientProvider } from "../src/client/providers/ShellWebClientProvider.js";
+import {
+  WEB_PLACEMENT_RUNTIME_CLIENT_TOKEN,
+  WEB_PLACEMENT_RUNTIME_INJECTION_KEY
+} from "../src/client/placement/tokens.js";
+import {
+  SHELL_WEB_ERROR_PRESENTATION_STORE_CLIENT_TOKEN,
+  SHELL_WEB_ERROR_PRESENTATION_STORE_INJECTION_KEY,
+  SHELL_WEB_ERROR_RUNTIME_CLIENT_TOKEN,
+  SHELL_WEB_ERROR_RUNTIME_INJECTION_KEY
+} from "../src/client/error/tokens.js";
+import {
+  CLIENT_MODULE_SURFACE_RUNTIME_TOKEN,
+  CLIENT_MODULE_VUE_APP_TOKEN
+} from "@jskit-ai/kernel/client/moduleBootstrap";
+
+const CLIENT_APP_CONFIG_GLOBAL_KEY = "__JSKIT_CLIENT_APP_CONFIG__";
+
+function setClientAppConfig(source = {}) {
+  const normalized =
+    source && typeof source === "object" && !Array.isArray(source) ? Object.freeze({ ...source }) : Object.freeze({});
+  if (typeof globalThis === "object" && globalThis) {
+    globalThis[CLIENT_APP_CONFIG_GLOBAL_KEY] = normalized;
+  }
+  return normalized;
+}
+
+function createAppDouble({ surfaceRuntime = null } = {}) {
+  const singletons = new Map();
+  const singletonInstances = new Map();
+  const provided = [];
+  const plugins = [];
+
+  const vueApp = {
+    config: {},
+    use(plugin, options) {
+      plugins.push({ plugin, options });
+      return this;
+    },
+    provide(key, value) {
+      provided.push({ key, value });
+    }
+  };
+
+  return {
+    singletons,
+    provided,
+    plugins,
+    vueApp,
+    singleton(token, factory) {
+      singletons.set(token, factory);
+    },
+    has(token) {
+      if (token === CLIENT_MODULE_VUE_APP_TOKEN) {
+        return true;
+      }
+      if (token === CLIENT_MODULE_SURFACE_RUNTIME_TOKEN) {
+        return Boolean(surfaceRuntime);
+      }
+      return singletons.has(token) || singletonInstances.has(token);
+    },
+    make(token) {
+      if (token === CLIENT_MODULE_VUE_APP_TOKEN) {
+        return vueApp;
+      }
+      if (token === CLIENT_MODULE_SURFACE_RUNTIME_TOKEN && surfaceRuntime) {
+        return surfaceRuntime;
+      }
+      if (singletonInstances.has(token)) {
+        return singletonInstances.get(token);
+      }
+      const factory = singletons.get(token);
+      if (!factory) {
+        throw new Error(`Unknown token ${String(token)}`);
+      }
+      const instance = factory(this);
+      singletonInstances.set(token, instance);
+      return instance;
+    },
+    resolveTag() {
+      return [];
+    }
+  };
+}
+
+test("shell web client provider binds runtime and injects it into Vue app", async () => {
+  const app = createAppDouble();
+  const provider = new ShellWebClientProvider();
+
+  provider.register(app);
+  assert.equal(app.singletons.has(WEB_PLACEMENT_RUNTIME_CLIENT_TOKEN), true);
+  assert.equal(app.singletons.has(SHELL_WEB_ERROR_RUNTIME_CLIENT_TOKEN), true);
+  assert.equal(app.singletons.has(SHELL_WEB_ERROR_PRESENTATION_STORE_CLIENT_TOKEN), true);
+
+  await provider.boot(app);
+  assert.equal(app.plugins.length, 1);
+  assert.equal(typeof app.plugins[0].plugin.install, "function");
+  assert.equal(typeof app.plugins[0].options?.queryClient, "object");
+
+  const providedByKey = new Map(app.provided.map((entry) => [entry.key, entry.value]));
+
+  assert.equal(providedByKey.has(WEB_PLACEMENT_RUNTIME_INJECTION_KEY), true);
+  assert.equal(providedByKey.has(SHELL_WEB_ERROR_RUNTIME_INJECTION_KEY), true);
+  assert.equal(providedByKey.has(SHELL_WEB_ERROR_PRESENTATION_STORE_INJECTION_KEY), true);
+
+  const placementRuntime = providedByKey.get(WEB_PLACEMENT_RUNTIME_INJECTION_KEY);
+  assert.equal(typeof placementRuntime.getPlacements, "function");
+  assert.equal(typeof placementRuntime.getContext, "function");
+  assert.equal(typeof placementRuntime.setContext, "function");
+  assert.equal(typeof placementRuntime.getContext().surfaceConfig, "object");
+
+  const errorRuntime = providedByKey.get(SHELL_WEB_ERROR_RUNTIME_INJECTION_KEY);
+  assert.equal(typeof errorRuntime.report, "function");
+  assert.equal(typeof errorRuntime.configure, "function");
+
+  const errorStore = providedByKey.get(SHELL_WEB_ERROR_PRESENTATION_STORE_INJECTION_KEY);
+  assert.equal(typeof errorStore.getState, "function");
+  assert.equal(typeof errorStore.present, "function");
+});
+
+test("shell web client provider resolves surface config from client app config", async () => {
+  setClientAppConfig({
+    tenancyMode: "workspace",
+    surfaceAccessPolicies: {
+      public: {}
+    }
+  });
+
+  try {
+    const app = createAppDouble({
+      surfaceRuntime: {
+        DEFAULT_SURFACE_ID: "app",
+        listEnabledSurfaceIds() {
+          return ["app", "admin", "console"];
+        },
+        listSurfaceDefinitions() {
+          return [
+            { id: "app", pagesRoot: "w/[workspaceSlug]", requiresWorkspace: true, enabled: true },
+            { id: "admin", pagesRoot: "w/[workspaceSlug]/admin", requiresWorkspace: true, enabled: true },
+            { id: "console", pagesRoot: "console", requiresWorkspace: false, enabled: true }
+          ];
+        }
+      }
+    });
+    const provider = new ShellWebClientProvider();
+    provider.register(app);
+
+    await provider.boot(app);
+
+    const placementRuntime = app.make(WEB_PLACEMENT_RUNTIME_CLIENT_TOKEN);
+    const context = placementRuntime.getContext();
+    assert.equal(context.surfaceConfig.tenancyMode, "workspace");
+    assert.equal(context.surfaceConfig.defaultSurfaceId, "app");
+    assert.deepEqual(context.surfaceConfig.enabledSurfaceIds, ["app", "admin", "console"]);
+    assert.deepEqual(context.surfaceAccessPolicies, {
+      public: {}
+    });
+  } finally {
+    setClientAppConfig({});
+  }
+});