@equinor/fusion-framework-module-app 8.0.3 → 8.1.0-next.0

package/dist/types/AppConfigurator.d.ts

@@ -43,6 +43,7 @@ export interface IAppConfigurator {
  * via service discovery. The default `assetUri` is `'/apps-proxy'`.
  */
 export declare class AppConfigurator extends BaseConfigBuilder<AppModuleConfig> implements IAppConfigurator {
+    /** Default cache expiration time, in milliseconds, for the app service client. */
     defaultExpireTime: number;
     /**
      * Creates the default HTTP client for the app service, preferring a pre-configured

package/dist/types/__tests__/AppModuleProvider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/__tests__/MockAppClient.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/app/App.d.ts

@@ -289,6 +289,7 @@ export declare class App<TEnv extends ConfigEnvironment = ConfigEnvironment, TMo
     getAppModule(force_refresh?: boolean): Observable<AppScriptModule>;
     /** @inheritdoc */
     getAppModuleAsync(allow_cache?: boolean): Promise<AppScriptModule>;
+    /** Releases resources held by this app instance. */
     dispose: VoidFunction;
 }
 export default App;

package/dist/types/index.d.ts

@@ -18,6 +18,7 @@
  */
 export { AppModuleConfig, AppConfigurator, IAppConfigurator, type AppModuleConfig as IAppModuleConfig, } from './AppConfigurator';
 export { AppClient, type IAppClient } from './AppClient';
+export { AppConfig } from './AppConfig';
 export { AppModuleProvider } from './AppModuleProvider';
 export { IApp } from './app/App';
 export * from './events';

package/dist/types/mock/MockAppClient.d.ts

@@ -0,0 +1,56 @@
+import type { Observable } from 'rxjs';
+import type { IHttpClient } from '@equinor/fusion-framework-module-http';
+import { AppClient } from '../AppClient.js';
+import type { AppConfig, AppManifest, ConfigEnvironment } from '../types.js';
+/**
+ * An {@link AppClient} that answers `getAppManifest` and `getAppConfig` for one
+ * known app locally, delegating everything else — other app keys, tagged
+ * requests, builds, settings — to the real client it wraps.
+ *
+ * @remarks
+ * Whatever `client` was resolved to (a pre-configured http client, or one created
+ * through service discovery) still backs every method this class doesn't
+ * override, so pointing service discovery at a different registry or a real
+ * local mock server keeps working unchanged.
+ *
+ * @example
+ * ```ts
+ * builder.setClient(async ({ requireInstance }) => {
+ *   const http = await requireInstance('http');
+ *   return new MockAppClient(http.createClient('apps'), manifest, config);
+ * });
+ * ```
+ */
+export declare class MockAppClient extends AppClient {
+    #private;
+    /**
+     * @param client - The real {@link IHttpClient} to delegate all other requests to.
+     * @param manifest - The manifest to return for `getAppManifest({ appKey: manifest.appKey })`.
+     * @param config - The config to return for `getAppConfig({ appKey: manifest.appKey })`, if any.
+     */
+    constructor(client: IHttpClient, manifest: AppManifest, config?: AppConfig);
+    /**
+     * Answers with the manifest passed to the constructor when `args` matches
+     * this client's own app key and no tag; otherwise delegates to the real client.
+     *
+     * @param args - The app key and optional tag to resolve a manifest for.
+     * @returns An observable of the resolved {@link AppManifest}.
+     */
+    getAppManifest(args: {
+        appKey: string;
+        tag?: string;
+    }): Observable<AppManifest>;
+    /**
+     * Answers with the config passed to the constructor when `args` matches this
+     * client's own app key and tag; otherwise delegates to the real client.
+     *
+     * @template TType - The shape of the config's `environment` data.
+     * @param args - The app key and optional tag to resolve config for.
+     * @returns An observable of the resolved {@link AppConfig}.
+     */
+    getAppConfig<TType extends ConfigEnvironment = ConfigEnvironment>(args: {
+        appKey: string;
+        tag?: string;
+    }): Observable<AppConfig<TType>>;
+}
+export default MockAppClient;

package/dist/types/mock/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Test doubles for the app module.
+ *
+ * @remarks
+ * Imported from `@equinor/fusion-framework-module-app/mock`, so the mock ships
+ * and versions with the implementation it stands in for.
+ *
+ * This entry point has no dependency on any test runner.
+ *
+ * @packageDocumentation
+ */
+export { MockAppClient } from './MockAppClient.js';

package/dist/types/schemas.d.ts

@@ -18,6 +18,22 @@ export declare const ApiAppConfigSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ApiAppConfig = z.infer<typeof ApiAppConfigSchema>;
+/**
+ * Schema for validating the options object on application builds.
+ *
+ * Known properties:
+ * - `contextRouting` (optional): Routing strategy for context — `'path'` or `'query'`.
+ *
+ * The schema uses `.catchall(z.unknown())` to permit additional properties
+ * at runtime without requiring them to be declared here. Add known properties
+ * to this schema as they are introduced.
+ */
+export declare const FrameworkOptionsSchema: z.ZodObject<{
+    contextRouting: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        path: "path";
+        query: "query";
+    }>>>;
+}, z.core.$catchall<z.ZodUnknown>>;
 /**
  * Schema for validating the structure of an API application build.
  *
@@ -33,6 +49,7 @@ export type ApiAppConfig = z.infer<typeof ApiAppConfigSchema>;
  * - `githubRepo`: An optional GitHub repository associated with the build.
  * - `projectPage`: An optional project page URL.
  * - `allowedExtensions`: An optional array of allowed extensions for the build.
+ * - `options`: An optional record of additional build options, where the key is a string and the value can be of any type.
  * - `uploadedBy`: An optional schema for the person who uploaded the build.
  */
 export declare const ApiApplicationBuildSchema: z.ZodObject<{
@@ -46,6 +63,12 @@ export declare const ApiApplicationBuildSchema: z.ZodObject<{
     commitSha: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     githubRepo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     projectPage: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    options: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        contextRouting: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            path: "path";
+            query: "query";
+        }>>>;
+    }, z.core.$catchall<z.ZodUnknown>>>>>;
     allowedExtensions: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
     uploadedBy: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         azureUniqueId: z.ZodString;
@@ -133,6 +156,12 @@ export declare const ApiApplicationSchema: z.ZodObject<{
         commitSha: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         githubRepo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         projectPage: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        options: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            contextRouting: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                path: "path";
+                query: "query";
+            }>>>;
+        }, z.core.$catchall<z.ZodUnknown>>>>>;
         allowedExtensions: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
         uploadedBy: z.ZodOptional<z.ZodNullable<z.ZodObject<{
             azureUniqueId: z.ZodString;

package/dist/types/types.d.ts

@@ -93,6 +93,36 @@ export type RouteSchemaEntry = [
         search?: Record<string, string>;
     }
 ];
+/**
+ * Typed representation of the options object.
+ *
+ * Only known keys are declared in the type — additional properties are
+ * handled by the Zod schema at runtime. Keeping the type narrow avoids
+ * structural incompatibilities with `RecursivePartial<AppManifest>`.
+ */
+export type FrameworkOptions = {
+    /**
+     * Declares how the portal should encode this app's active context into the URL.
+     *
+     * Read by the `@equinor/fusion-framework-plugin-context-navigation` plugin
+     * to select the correct adapter at runtime.
+     *
+     * - `'path'`  — context id as a path segment: `/apps/{appKey}/{contextId}/...`
+     * - `'query'` — context id as a query parameter: `/apps/{appKey}/...?$contextId={id}`
+     * - `null`    — explicitly opt out of automatic context-to-URL encoding
+     * - `undefined` (omitted) — falls back to `'path'` (the default adapter)
+     *
+     * Apps with custom URL shapes should omit this field and register
+     * `setContextPathExtractor` / `setContextPathGenerator` hooks instead —
+     * the custom adapter picks those up automatically.
+     *
+     * Set this in the app manifest's `build.options.contextRouting` field,
+     * either in `app.manifest.config.ts` or via the app service manifest.
+     *
+     * @default undefined (falls back to path adapter)
+     */
+    contextRouting?: 'path' | 'query' | null;
+};
 /**
  * Build metadata returned by the app service for a specific application version.
  * Contains the script entry point, asset path, tags, and optional CI metadata.
@@ -109,6 +139,7 @@ export type AppBuildManifest = {
     githubRepo?: Nullable<string>;
     projectPage?: Nullable<string>;
     annotations?: Nullable<Record<string, string>>;
+    options?: Nullable<FrameworkOptions>;
     allowedExtensions?: Nullable<string[]>;
     uploadedBy?: Nullable<AppOwner>;
 };

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "8.0.3";
+export declare const version = "8.1.0-next.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-app",
-  "version": "8.0.3",
+  "version": "8.1.0-next.0",
   "description": "",
   "main": "dist/esm/index.js",
   "exports": {
@@ -22,6 +22,10 @@
     },
     "./app/*.js": {
       "import": "./dist/esm/app/*.js"
+    },
+    "./mock": {
+      "import": "./dist/esm/mock/index.js",
+      "types": "./dist/types/mock/index.d.ts"
     }
   },
   "types": "dist/types/index.d.ts",
@@ -41,6 +45,9 @@
       ],
       "app/*.js": [
         "dist/types/app/*.d.ts"
+      ],
+      "mock": [
+        "dist/types/mock/index.d.ts"
       ]
     }
   },
@@ -61,18 +68,21 @@
     "rxjs": "^7.8.1",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@equinor/fusion-observable": "^9.1.1",
-    "@equinor/fusion-query": "^7.0.2"
+    "@equinor/fusion-query": "^7.0.4-next.0",
+    "@equinor/fusion-observable": "^9.1.2-next.0"
   },
   "devDependencies": {
     "typescript": "^7.0.2",
-    "@equinor/fusion-framework-module": "^6.1.1",
-    "@equinor/fusion-framework-module-event": "^6.0.1",
-    "@equinor/fusion-framework-module-http": "^8.0.4",
-    "@equinor/fusion-framework-module-msal": "^10.0.2",
-    "@equinor/fusion-framework-module-service-discovery": "^10.0.2"
+    "vitest": "^4.1.10",
+    "@equinor/fusion-framework-module": "^6.1.3-next.0",
+    "@equinor/fusion-framework": "^8.1.0-next.0",
+    "@equinor/fusion-framework-module-event": "^6.1.0-next.0",
+    "@equinor/fusion-framework-module-http": "^8.1.0-next.0",
+    "@equinor/fusion-framework-module-msal": "^11.0.0-next.0",
+    "@equinor/fusion-framework-module-service-discovery": "^10.1.0-next.0"
   },
   "scripts": {
-    "build": "tsc -b"
+    "build": "tsc -b",
+    "test": "vitest run"
   }
 }

package/src/AppConfigurator.ts

@@ -59,6 +59,7 @@ export class AppConfigurator
   extends BaseConfigBuilder<AppModuleConfig>
   implements IAppConfigurator
 {
+  /** Default cache expiration time, in milliseconds, for the app service client. */
   defaultExpireTime = 1 * 60 * 1000;
 
   /**

package/src/__tests__/AppModuleProvider.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+
+import { mockFramework } from '@equinor/fusion-framework/mock';
+import { createRouterMiddleware } from '@equinor/fusion-framework-module-http/mock';
+
+import { enableAppModule } from '../enable-app-module';
+import type { AppModule } from '../module';
+
+/**
+ * Boots a full portal-shaped framework instance the same way `packages/dev-portal`'s
+ * `configure.ts` does — `enableAppModule` registered directly on the portal's own
+ * configurator, alongside its real `http`, `event`, `msal`, etc. — rather than a
+ * standalone module graph assembled just for this test. Only the network call
+ * itself is faked; the app module creates its client eagerly during its own
+ * `requireInstance('http')` in the SAME configure→initialize pipeline, so this also
+ * verifies middleware registered before `initialize()` reaches that client.
+ */
+const initializePortalWith = () =>
+  mockFramework<[AppModule]>((configurator) => {
+    configurator.http.configureClient('apps', { baseUri: 'https://apps.example.com' });
+    configurator.http.addMiddleware(
+      createRouterMiddleware('https://apps.example.com', (router) => {
+        router.get('/persons/me/apps/:appKey', ({ params }) =>
+          Response.json({
+            appKey: params.appKey,
+            displayName: 'Test App',
+            description: 'A test application',
+            type: 'standalone',
+          }),
+        );
+      }),
+    );
+    enableAppModule(configurator);
+  });
+
+describe('AppModuleProvider', () => {
+  it("fetches the manifest through the portal's own http client once a current app is set", async () => {
+    const fusion = await initializePortalWith();
+
+    fusion.modules.app.setCurrentApp('test-app');
+
+    await expect(fusion.modules.app.current?.getManifestAsync()).resolves.toMatchObject({
+      appKey: 'test-app',
+      displayName: 'Test App',
+    });
+  });
+});

package/src/__tests__/MockAppClient.test.ts

@@ -0,0 +1,97 @@
+import { firstValueFrom, of } from 'rxjs';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { IHttpClient } from '@equinor/fusion-framework-module-http';
+
+import { AppClient } from '../AppClient.js';
+import { AppConfig } from '../AppConfig.js';
+import { MockAppClient } from '../mock/MockAppClient.js';
+import type { AppManifest } from '../types.js';
+
+const manifest: AppManifest = {
+  appKey: 'my-app',
+  displayName: 'My App',
+  description: 'My app',
+  type: 'standalone',
+  build: { version: '1.2.3', entryPoint: 'index.js' },
+};
+
+const config = new AppConfig({ environment: { key: 'value' } });
+
+// never invoked directly -- both overrides either answer locally or delegate through
+// the spied `AppClient.prototype` methods below, so the real client is never called
+const client = {} as IHttpClient;
+
+describe('MockAppClient', () => {
+  describe('getAppManifest', () => {
+    it('answers locally for its own app key with no tag', async () => {
+      const mockClient = new MockAppClient(client, manifest);
+
+      const result = mockClient.getAppManifest({ appKey: 'my-app' });
+
+      await expect(firstValueFrom(result)).resolves.toBe(manifest);
+    });
+
+    it('delegates for its own app key with an explicit empty-string tag', () => {
+      const delegate = vi
+        .spyOn(AppClient.prototype, 'getAppManifest')
+        .mockReturnValue(of(manifest));
+      const mockClient = new MockAppClient(client, manifest);
+
+      mockClient.getAppManifest({ appKey: 'my-app', tag: '' });
+
+      expect(delegate).toHaveBeenCalledWith({ appKey: 'my-app', tag: '' });
+      delegate.mockRestore();
+    });
+
+    it('delegates for a different app key', () => {
+      const delegate = vi
+        .spyOn(AppClient.prototype, 'getAppManifest')
+        .mockReturnValue(of(manifest));
+      const mockClient = new MockAppClient(client, manifest);
+
+      mockClient.getAppManifest({ appKey: 'other-app' });
+
+      expect(delegate).toHaveBeenCalledWith({ appKey: 'other-app' });
+      delegate.mockRestore();
+    });
+  });
+
+  describe('getAppConfig', () => {
+    it('answers locally for its own app key with no tag', async () => {
+      const mockClient = new MockAppClient(client, manifest, config);
+
+      const result = mockClient.getAppConfig({ appKey: 'my-app' });
+
+      await expect(firstValueFrom(result)).resolves.toBe(config);
+    });
+
+    it("answers locally for its own app key with a tag matching the manifest's build version", async () => {
+      const mockClient = new MockAppClient(client, manifest, config);
+
+      const result = mockClient.getAppConfig({ appKey: 'my-app', tag: '1.2.3' });
+
+      await expect(firstValueFrom(result)).resolves.toBe(config);
+    });
+
+    it('delegates for its own app key with an explicit empty-string tag', () => {
+      const delegate = vi.spyOn(AppClient.prototype, 'getAppConfig').mockReturnValue(of(config));
+      const mockClient = new MockAppClient(client, manifest, config);
+
+      mockClient.getAppConfig({ appKey: 'my-app', tag: '' });
+
+      expect(delegate).toHaveBeenCalledWith({ appKey: 'my-app', tag: '' });
+      delegate.mockRestore();
+    });
+
+    it('delegates for its own app key with a tag not matching the manifest build version', () => {
+      const delegate = vi.spyOn(AppClient.prototype, 'getAppConfig').mockReturnValue(of(config));
+      const mockClient = new MockAppClient(client, manifest, config);
+
+      mockClient.getAppConfig({ appKey: 'my-app', tag: '9.9.9' });
+
+      expect(delegate).toHaveBeenCalledWith({ appKey: 'my-app', tag: '9.9.9' });
+      delegate.mockRestore();
+    });
+  });
+});

package/src/app/App.ts

@@ -977,6 +977,7 @@ export class App<
     return operator(this.getAppModule(!allow_cache));
   }
 
+  /** Releases resources held by this app instance. */
   public dispose: VoidFunction;
 }
 

package/src/index.ts

@@ -26,6 +26,8 @@ export {
 
 export { AppClient, type IAppClient } from './AppClient';
 
+export { AppConfig } from './AppConfig';
+
 export { AppModuleProvider } from './AppModuleProvider';
 
 export { IApp } from './app/App';

package/src/mock/MockAppClient.ts

@@ -0,0 +1,77 @@
+import type { Observable } from 'rxjs';
+import { of } from 'rxjs';
+
+import type { IHttpClient } from '@equinor/fusion-framework-module-http';
+
+import { AppClient } from '../AppClient.js';
+import type { AppConfig, AppManifest, ConfigEnvironment } from '../types.js';
+
+/**
+ * An {@link AppClient} that answers `getAppManifest` and `getAppConfig` for one
+ * known app locally, delegating everything else — other app keys, tagged
+ * requests, builds, settings — to the real client it wraps.
+ *
+ * @remarks
+ * Whatever `client` was resolved to (a pre-configured http client, or one created
+ * through service discovery) still backs every method this class doesn't
+ * override, so pointing service discovery at a different registry or a real
+ * local mock server keeps working unchanged.
+ *
+ * @example
+ * ```ts
+ * builder.setClient(async ({ requireInstance }) => {
+ *   const http = await requireInstance('http');
+ *   return new MockAppClient(http.createClient('apps'), manifest, config);
+ * });
+ * ```
+ */
+export class MockAppClient extends AppClient {
+  #manifest: AppManifest;
+  #config?: AppConfig;
+
+  /**
+   * @param client - The real {@link IHttpClient} to delegate all other requests to.
+   * @param manifest - The manifest to return for `getAppManifest({ appKey: manifest.appKey })`.
+   * @param config - The config to return for `getAppConfig({ appKey: manifest.appKey })`, if any.
+   */
+  constructor(client: IHttpClient, manifest: AppManifest, config?: AppConfig) {
+    super(client);
+    this.#manifest = manifest;
+    this.#config = config;
+  }
+
+  /**
+   * Answers with the manifest passed to the constructor when `args` matches
+   * this client's own app key and no tag; otherwise delegates to the real client.
+   *
+   * @param args - The app key and optional tag to resolve a manifest for.
+   * @returns An observable of the resolved {@link AppManifest}.
+   */
+  override getAppManifest(args: { appKey: string; tag?: string }): Observable<AppManifest> {
+    return args.appKey === this.#manifest.appKey && args.tag === undefined
+      ? of(this.#manifest)
+      : super.getAppManifest(args);
+  }
+
+  /**
+   * Answers with the config passed to the constructor when `args` matches this
+   * client's own app key and tag; otherwise delegates to the real client.
+   *
+   * @template TType - The shape of the config's `environment` data.
+   * @param args - The app key and optional tag to resolve config for.
+   * @returns An observable of the resolved {@link AppConfig}.
+   */
+  override getAppConfig<TType extends ConfigEnvironment = ConfigEnvironment>(args: {
+    appKey: string;
+    tag?: string;
+  }): Observable<AppConfig<TType>> {
+    // config is fetched against the manifest's own build version, not an explicit override tag,
+    // so a matching tag is treated the same as an absent one -- an explicit empty string is not
+    const isOwnTag = args.tag === undefined || args.tag === this.#manifest.build?.version;
+    return args.appKey === this.#manifest.appKey && isOwnTag && this.#config
+      ? of(this.#config as AppConfig<TType>)
+      : super.getAppConfig(args);
+  }
+}
+
+export default MockAppClient;

package/src/mock/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Test doubles for the app module.
+ *
+ * @remarks
+ * Imported from `@equinor/fusion-framework-module-app/mock`, so the mock ships
+ * and versions with the implementation it stands in for.
+ *
+ * This entry point has no dependency on any test runner.
+ *
+ * @packageDocumentation
+ */
+
+export { MockAppClient } from './MockAppClient.js';

package/src/schemas.ts

@@ -60,6 +60,26 @@ const ApiApplicationPersonSchema = z.object({
     .nullish(),
 });
 
+/**
+ * Schema for validating the options object on application builds.
+ *
+ * Known properties:
+ * - `contextRouting` (optional): Routing strategy for context — `'path'` or `'query'`.
+ *
+ * The schema uses `.catchall(z.unknown())` to permit additional properties
+ * at runtime without requiring them to be declared here. Add known properties
+ * to this schema as they are introduced.
+ */
+export const FrameworkOptionsSchema = z
+  .object({
+    contextRouting: z
+      .enum(['path', 'query'], {
+        message: "The routing strategy for context, which can be either 'path' or 'query'.",
+      })
+      .nullish(),
+  })
+  .catchall(z.unknown());
+
 /**
  * Schema for validating the structure of an API application build.
  *
@@ -75,6 +95,7 @@ const ApiApplicationPersonSchema = z.object({
  * - `githubRepo`: An optional GitHub repository associated with the build.
  * - `projectPage`: An optional project page URL.
  * - `allowedExtensions`: An optional array of allowed extensions for the build.
+ * - `options`: An optional record of additional build options, where the key is a string and the value can be of any type.
  * - `uploadedBy`: An optional schema for the person who uploaded the build.
  */
 // Deliberately co-located with ApiApplicationPersonSchema, which it depends on
@@ -90,6 +111,9 @@ export const ApiApplicationBuildSchema = z.object({
   commitSha: z.string().nullish(),
   githubRepo: z.string().nullish(),
   projectPage: z.string().nullish(),
+  options: FrameworkOptionsSchema.nullish().default({
+    contextRouting: 'path',
+  }),
   allowedExtensions: z.array(z.string()).nullish(),
   uploadedBy: ApiApplicationPersonSchema.nullish(),
 });

package/src/types.ts

@@ -117,6 +117,37 @@ export type RouteSchemaEntry = [
   },
 ];
 
+/**
+ * Typed representation of the options object.
+ *
+ * Only known keys are declared in the type — additional properties are
+ * handled by the Zod schema at runtime. Keeping the type narrow avoids
+ * structural incompatibilities with `RecursivePartial<AppManifest>`.
+ */
+export type FrameworkOptions = {
+  /**
+   * Declares how the portal should encode this app's active context into the URL.
+   *
+   * Read by the `@equinor/fusion-framework-plugin-context-navigation` plugin
+   * to select the correct adapter at runtime.
+   *
+   * - `'path'`  — context id as a path segment: `/apps/{appKey}/{contextId}/...`
+   * - `'query'` — context id as a query parameter: `/apps/{appKey}/...?$contextId={id}`
+   * - `null`    — explicitly opt out of automatic context-to-URL encoding
+   * - `undefined` (omitted) — falls back to `'path'` (the default adapter)
+   *
+   * Apps with custom URL shapes should omit this field and register
+   * `setContextPathExtractor` / `setContextPathGenerator` hooks instead —
+   * the custom adapter picks those up automatically.
+   *
+   * Set this in the app manifest's `build.options.contextRouting` field,
+   * either in `app.manifest.config.ts` or via the app service manifest.
+   *
+   * @default undefined (falls back to path adapter)
+   */
+  contextRouting?: 'path' | 'query' | null;
+};
+
 /**
  * Build metadata returned by the app service for a specific application version.
  * Contains the script entry point, asset path, tags, and optional CI metadata.
@@ -133,6 +164,7 @@ export type AppBuildManifest = {
   githubRepo?: Nullable<string>;
   projectPage?: Nullable<string>;
   annotations?: Nullable<Record<string, string>>;
+  options?: Nullable<FrameworkOptions>;
   allowedExtensions?: Nullable<string[]>;
   uploadedBy?: Nullable<AppOwner>;
 };

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '8.0.3';
+export const version = '8.1.0-next.0';

package/tsconfig.json

@@ -9,6 +9,9 @@
     {
       "path": "../../utils/query"
     },
+    {
+      "path": "../../framework"
+    },
     {
       "path": "../module"
     },

package/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineProject } from 'vitest/config';
+
+import { name, version } from './package.json' with { type: 'json' };
+
+export default defineProject({
+  test: {
+    environment: 'node',
+    include: ['src/__tests__/**/*.test.ts'],
+    name: `${name}@${version}`,
+  },
+});