ExaDev · pull · Nov 26, 2025 · Nov 26, 2025 · Nov 26, 2025 · Nov 26, 2025
diff --git a/packages/api/index.ts b/packages/api/index.ts
@@ -1257,7 +1257,7 @@ export type WishTag = `/${string}` | `#${string}`;
 export type DID = `did:${string}:${string}`;
 
 export type WishParams = {
-  tag?: WishTag;
+  query: WishTag | string;
   path?: string[];
   context?: Record<string, any>;
   schema?: JSONSchema;

diff --git a/packages/background-charm-service/cast-admin.ts b/packages/background-charm-service/cast-admin.ts
@@ -3,7 +3,7 @@ import { CharmManager, compileRecipe } from "@commontools/charm";
 import { Runtime } from "@commontools/runner";
 import { StorageManager } from "@commontools/runner/storage/cache.deno";
 import { type DID } from "@commontools/identity";
-import { createSessionFromDid } from "@commontools/identity";
+import { createSession } from "@commontools/identity";
 import {
   BG_CELL_CAUSE,
   BG_SYSTEM_SPACE_ID,
@@ -87,10 +87,9 @@ async function castRecipe() {
     console.log("Casting recipe...");
 
     // Create session and charm manager (matching main.ts pattern)
-    const session = await createSessionFromDid({
+    const session = await createSession({
       identity,
-      spaceName: "recipe-caster",
-      space: spaceId as DID,
+      spaceDid: spaceId as DID,
     });
 
     // Create charm manager for the specified space

diff --git a/packages/background-charm-service/integration/counter.test.ts b/packages/background-charm-service/integration/counter.test.ts
@@ -54,8 +54,10 @@ describe("background charm counter tests", () => {
 
     await shell.goto({
       frontendUrl: FRONTEND_URL,
-      spaceName: SPACE_NAME,
-      charmId,
+      view: {
+        spaceName: SPACE_NAME,
+        charmId,
+      },
       identity,
     });
 

diff --git a/packages/background-charm-service/src/worker.ts b/packages/background-charm-service/src/worker.ts
@@ -12,7 +12,7 @@ import {
 import { StorageManager } from "@commontools/runner/storage/cache.deno";
 
 import {
-  createSessionFromDid,
+  createSession,
   type DID,
   Identity,
   Session,
@@ -93,10 +93,9 @@ async function initialize(
 
   // Initialize session
   spaceId = did as DID;
-  currentSession = await createSessionFromDid({
+  currentSession = await createSession({
     identity,
-    spaceName: "~background-service-worker",
-    space: spaceId,
+    spaceDid: spaceId,
   });
 
   // Initialize runtime and charm manager

diff --git a/packages/charm/src/manager.ts b/packages/charm/src/manager.ts
@@ -217,7 +217,7 @@ export class CharmManager {
     return this.space;
   }
 
-  getSpaceName(): string {
+  getSpaceName(): string | undefined {
     return this.session.spaceName;
   }
 

diff --git a/packages/identity/src/index.ts b/packages/identity/src/index.ts
@@ -6,8 +6,4 @@ export {
 } from "./identity.ts";
 export { KeyStore } from "./key-store.ts";
 export * from "./interface.ts";
-export {
-  createSession,
-  createSessionFromDid,
-  type Session,
-} from "./session.ts";
+export { createSession, type Session } from "./session.ts";
diff --git a/packages/identity/src/session.ts b/packages/identity/src/session.ts
@@ -2,39 +2,39 @@ import { Identity } from "./identity.ts";
 import { type DID } from "./interface.ts";
 
 export type Session = {
-  spaceName: string;
+  spaceName?: string;
   spaceIdentity?: Identity;
   space: DID;
   as: Identity;
 };
 
-// Create a session where `Identity` is used directly and not derived.
-export const createSessionFromDid = (
-  { identity, space, spaceName }: {
-    identity: Identity;
-    space: DID;
-    spaceName: string;
-  },
-): Promise<Session> => {
-  return Promise.resolve({
-    spaceName,
-    space,
-    as: identity,
-  });
+export type SessionCreateOptions = {
+  identity: Identity;
+  spaceName: string;
+} | {
+  identity: Identity;
+  spaceDid: DID;
 };
 
-// Create a session where `Identity` is used to derive a space key.
+// Create a session with DID and identity provided, or where
+// a key is reproducibly derived via the provided space name.
 export const createSession = async (
-  { identity, spaceName }: { identity: Identity; spaceName: string },
+  options: SessionCreateOptions,
 ): Promise<Session> => {
-  const spaceIdentity = await (await Identity.fromPassphrase("common user"))
-    .derive(
-      spaceName,
-    );
+  if ("spaceName" in options) {
+    const spaceIdentity = await (await Identity.fromPassphrase("common user"))
+      .derive(
+        options.spaceName,
+      );
+    return {
+      spaceName: options.spaceName,
+      spaceIdentity,
+      space: spaceIdentity.did(),
+      as: options.identity,
+    };
+  }
   return {
-    spaceName,
-    spaceIdentity,
-    space: spaceIdentity.did(),
-    as: identity,
+    as: options.identity,
+    space: options.spaceDid,
   };
 };
diff --git a/packages/integration/shell-utils.ts b/packages/integration/shell-utils.ts
@@ -12,7 +12,13 @@ import {
   TransferrableInsecureCryptoKeyPair,
 } from "@commontools/identity";
 import { afterAll, afterEach, beforeAll, beforeEach } from "@std/testing/bdd";
-import { AppState, deserialize } from "../shell/src/lib/app/mod.ts";
+import {
+  AppState,
+  AppView,
+  appViewToUrlPath,
+  deserialize,
+  isAppViewEqual,
+} from "../shell/src/lib/app/mod.ts";
 import { waitFor } from "./utils.ts";
 import { ConsoleEvent, PageErrorEvent } from "@astral/astral";
 
@@ -88,8 +94,7 @@ export class ShellIntegration {
   // has a matching `spaceName`, ignoring all other properties.
   async waitForState(
     params: {
-      spaceName?: string;
-      charmId?: string;
+      view: AppView;
       identity?: Identity;
     },
   ): Promise<AppState> {
@@ -99,8 +104,7 @@ export class ShellIntegration {
     ): boolean {
       return !!(
         state &&
-        (params.spaceName ? state.spaceName === params.spaceName : true) &&
-        (params.charmId ? state.activeCharmId === params.charmId : true) &&
+        isAppViewEqual(state.view, params.view) &&
         (params.identity
           ? state.identity?.did() === params.identity.did()
           : true)
@@ -128,22 +132,25 @@ export class ShellIntegration {
   // If `identity` provided, logs in with the identity
   // after navigation.
   async goto(
-    { frontendUrl, spaceName, charmId, identity }: {
+    { frontendUrl, view, identity }: {
       frontendUrl: string;
-      spaceName: string;
-      charmId?: string;
+      view: AppView;
       identity?: Identity;
     },
   ): Promise<void> {
     this.checkIsOk();
-    const url = `${frontendUrl}${spaceName}${charmId ? `/${charmId}` : ""}`;
+
+    // Strip the proceeding "/" in the url path
+    const path = appViewToUrlPath(view).substring(1);
+
+    const url = `${frontendUrl}${path}`;
     const page = this.page();
     await page.goto(url);
     await page.applyConsoleFormatter();
-    await this.waitForState({ spaceName, charmId });
+    await this.waitForState({ view });
     if (identity) {
       await this.login(identity);
-      await this.waitForState({ identity, spaceName, charmId });
+      await this.waitForState({ identity, view });
     }
   }
 

diff --git a/packages/patterns/favorites-manager.tsx b/packages/patterns/favorites-manager.tsx
@@ -13,7 +13,7 @@ const onRemoveFavorite = handler<
 });
 
 export default pattern<Record<string, never>>((_) => {
-  const wishResult = wish<Array<Favorite>>({ tag: "#favorites" });
+  const wishResult = wish<Array<Favorite>>({ query: "#favorites" });
 
   return {
     [NAME]: "Favorites Manager",

diff --git a/packages/patterns/home.tsx b/packages/patterns/home.tsx
@@ -0,0 +1,13 @@
+/// <cts-enable />
+import { NAME, pattern, UI } from "commontools";
+
+export default pattern((_) => {
+  return {
+    [NAME]: `Home`,
+    [UI]: (
+      <h1>
+        home<strong>space</strong>
+      </h1>
+    ),
+  };
+});
diff --git a/packages/patterns/integration/chatbot.test.ts b/packages/patterns/integration/chatbot.test.ts
@@ -56,8 +56,10 @@ describe("Chat pattern test", () => {
       const page = shell.page();
       await shell.goto({
         frontendUrl: FRONTEND_URL,
-        spaceName: SPACE_NAME,
-        charmId,
+        view: {
+          spaceName: SPACE_NAME,
+          charmId,
+        },
         identity,
       });
 

diff --git a/packages/patterns/integration/counter.test.ts b/packages/patterns/integration/counter.test.ts
@@ -43,8 +43,10 @@ describe("counter direct operations test", () => {
     const page = shell.page();
     await shell.goto({
       frontendUrl: FRONTEND_URL,
-      spaceName: SPACE_NAME,
-      charmId: charm.id,
+      view: {
+        spaceName: SPACE_NAME,
+        charmId: charm.id,
+      },
       identity,
     });
 
@@ -95,8 +97,10 @@ describe("counter direct operations test", () => {
     console.log("Refreshing the page...");
     await shell.goto({
       frontendUrl: FRONTEND_URL,
-      spaceName: SPACE_NAME,
-      charmId: charm.id,
+      view: {
+        spaceName: SPACE_NAME,
+        charmId: charm.id,
+      },
       identity,
     });
 

diff --git a/packages/patterns/integration/ct-checkbox.test.ts b/packages/patterns/integration/ct-checkbox.test.ts
@@ -55,8 +55,10 @@ testComponents.forEach(({ name, file }) => {
       const page = shell.page();
       await shell.goto({
         frontendUrl: FRONTEND_URL,
-        spaceName: SPACE_NAME,
-        charmId,
+        view: {
+          spaceName: SPACE_NAME,
+          charmId,
+        },
         identity,
       });
       await page.waitForSelector("ct-checkbox", { strategy: "pierce" });

diff --git a/packages/patterns/integration/ct-list.test.ts b/packages/patterns/integration/ct-list.test.ts
@@ -45,8 +45,10 @@ describe("ct-list integration test", () => {
     const page = shell.page();
     await shell.goto({
       frontendUrl: FRONTEND_URL,
-      spaceName: SPACE_NAME,
-      charmId,
+      view: {
+        spaceName: SPACE_NAME,
+        charmId,
+      },
       identity,
     });
     await page.waitForSelector("ct-list", { strategy: "pierce" });

diff --git a/packages/patterns/integration/ct-render.test.ts b/packages/patterns/integration/ct-render.test.ts
@@ -44,8 +44,10 @@ describe("ct-render integration test", () => {
     const page = shell.page();
     await shell.goto({
       frontendUrl: FRONTEND_URL,
-      spaceName: SPACE_NAME,
-      charmId: charm.id,
+      view: {
+        spaceName: SPACE_NAME,
+        charmId: charm.id,
+      },
       identity,
     });
 
@@ -98,8 +100,10 @@ describe("ct-render integration test", () => {
     // Navigate to the charm to see if UI reflects the change
     await shell.goto({
       frontendUrl: FRONTEND_URL,
-      spaceName: SPACE_NAME,
-      charmId: charm.id,
+      view: {
+        spaceName: SPACE_NAME,
+        charmId: charm.id,
+      },
       identity,
     });
 

diff --git a/packages/patterns/integration/ct-tags.test.ts b/packages/patterns/integration/ct-tags.test.ts
@@ -45,8 +45,10 @@ describe("ct-tags integration test", () => {
     const page = shell.page();
     await shell.goto({
       frontendUrl: FRONTEND_URL,
-      spaceName: SPACE_NAME,
-      charmId,
+      view: {
+        spaceName: SPACE_NAME,
+        charmId,
+      },
       identity,
     });
     await page.waitForSelector("ct-tags", { strategy: "pierce" });

diff --git a/packages/patterns/integration/fetch-data.test.ts b/packages/patterns/integration/fetch-data.test.ts
@@ -55,8 +55,10 @@ describe("fetch data integration test", () => {
       const page = shell.page();
       await shell.goto({
         frontendUrl: FRONTEND_URL,
-        spaceName: SPACE_NAME,
-        charmId: charm.id,
+        view: {
+          spaceName: SPACE_NAME,
+          charmId: charm.id,
+        },
         identity,
       });
 
@@ -85,8 +87,10 @@ describe("fetch data integration test", () => {
       // Navigate to the charm to see updated data
       await shell.goto({
         frontendUrl: FRONTEND_URL,
-        spaceName: SPACE_NAME,
-        charmId: charm.id,
+        view: {
+          spaceName: SPACE_NAME,
+          charmId: charm.id,
+        },
         identity,
       });
 

diff --git a/packages/patterns/integration/instantiate-recipe.test.ts b/packages/patterns/integration/instantiate-recipe.test.ts
@@ -46,8 +46,10 @@ describe("instantiate-recipe integration test", () => {
 
     await shell.goto({
       frontendUrl: FRONTEND_URL,
-      spaceName: SPACE_NAME,
-      charmId,
+      view: {
+        spaceName: SPACE_NAME,
+        charmId,
+      },
       identity,
     });
 

diff --git a/packages/patterns/integration/list-operations.test.ts b/packages/patterns/integration/list-operations.test.ts
@@ -43,8 +43,10 @@ describe("list-operations simple test", () => {
     const page = shell.page();
     await shell.goto({
       frontendUrl: FRONTEND_URL,
-      spaceName: SPACE_NAME,
-      charmId: charm.id,
+      view: {
+        spaceName: SPACE_NAME,
+        charmId: charm.id,
+      },
       identity,
     });