@jskit-ai/workspaces-web 0.1.1

package/package.descriptor.mjs

@@ -0,0 +1,303 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/workspaces-web",
+  version: "0.1.1",
+  kind: "runtime",
+  description: "Workspace web module: workspace selector, tools widget, workspace surfaces, and members/settings UI.",
+  dependsOn: [
+    "@jskit-ai/workspaces-core",
+    "@jskit-ai/users-web"
+  ],
+  capabilities: {
+    provides: [
+      "workspaces.web"
+    ],
+    requires: [
+      "users.web",
+      "workspaces.core"
+    ]
+  },
+  runtime: {
+    server: {
+      providers: []
+    },
+    client: {
+      providers: [
+        {
+          entrypoint: "src/client/providers/WorkspacesWebClientProvider.js",
+          export: "WorkspacesWebClientProvider"
+        }
+      ]
+    }
+  },
+  metadata: {
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./client/providers/WorkspacesWebClientProvider",
+          summary: "Exports workspaces-web client provider class."
+        }
+      ],
+      containerTokens: {
+        server: [],
+        client: [
+          "users.web.workspace.selector",
+          "users.web.workspace.tools.widget",
+          "users.web.workspace-settings.menu-item",
+          "users.web.workspace-members.menu-item",
+          "users.web.members-admin.element",
+          "users.web.workspace-settings.element"
+        ]
+      }
+    },
+    ui: {
+      placements: {
+        outlets: [
+          {
+            host: "admin-settings",
+            position: "primary-menu",
+            surfaces: ["admin"],
+            source: "templates/src/pages/admin/workspace/settings/index.vue"
+          },
+          {
+            host: "admin-settings",
+            position: "forms",
+            surfaces: ["admin"],
+            source: "templates/src/pages/admin/workspace/settings/index.vue"
+          }
+        ],
+        contributions: [
+          {
+            id: "users.workspace.selector",
+            host: "shell-layout",
+            position: "top-left",
+            surfaces: ["*"],
+            order: 200,
+            componentToken: "users.web.workspace.selector",
+            when: "auth.authenticated === true",
+            source: "mutations.text#users-web-placement-block"
+          },
+          {
+            id: "users.account.invites.cue",
+            host: "shell-layout",
+            position: "top-right",
+            surfaces: ["*"],
+            order: 850,
+            componentToken: "local.main.account.pending-invites.cue",
+            when: "auth.authenticated === true",
+            source: "mutations.text#users-web-placement-block"
+          },
+          {
+            id: "users.workspace.tools.widget",
+            host: "shell-layout",
+            position: "top-right",
+            surfaces: ["admin"],
+            order: 900,
+            componentToken: "users.web.workspace.tools.widget",
+            source: "mutations.text#users-web-placement-block"
+          },
+          {
+            id: "users.workspace.menu.workspace-settings",
+            host: "workspace-tools",
+            position: "primary-menu",
+            surfaces: ["admin"],
+            order: 100,
+            componentToken: "users.web.workspace-settings.menu-item",
+            source: "mutations.text#users-web-placement-block"
+          },
+          {
+            id: "users.workspace.menu.members",
+            host: "workspace-tools",
+            position: "primary-menu",
+            surfaces: ["admin"],
+            order: 200,
+            componentToken: "users.web.workspace-members.menu-item",
+            source: "mutations.text#users-web-placement-block"
+          },
+          {
+            id: "users.workspace.settings.form",
+            host: "admin-settings",
+            position: "forms",
+            surfaces: ["admin"],
+            order: 100,
+            componentToken: "users.web.workspace-settings.element",
+            source: "mutations.text#users-web-workspace-settings-form-placement"
+          }
+        ]
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@jskit-ai/workspaces-core": "0.1.1",
+        "@jskit-ai/users-web": "0.1.40"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {
+        "dev:app": "VITE_SURFACE=app vite",
+        "dev:admin": "VITE_SURFACE=admin vite",
+        "build:app": "VITE_SURFACE=app vite build",
+        "build:admin": "VITE_SURFACE=admin vite build"
+      }
+    },
+    procfile: {},
+    files: [
+      {
+        from: "templates/packages/main/src/client/components/AccountPendingInvitesCue.vue",
+        to: "packages/main/src/client/components/AccountPendingInvitesCue.vue",
+        reason: "Install app-owned account pending invites cue component scaffold.",
+        category: "workspaces-web",
+        id: "users-web-main-component-account-pending-invites-cue"
+      },
+      {
+        from: "templates/src/components/WorkspaceNotFoundCard.vue",
+        to: "src/components/WorkspaceNotFoundCard.vue",
+        reason: "Install app-owned workspace not-found card component used by workspace-dependent surfaces.",
+        category: "workspaces-web",
+        id: "users-web-component-workspace-not-found-card",
+        when: {
+          config: "tenancyMode",
+          in: ["personal", "workspaces"]
+        }
+      },
+      {
+        from: "templates/src/composables/useWorkspaceNotFoundState.js",
+        to: "src/composables/useWorkspaceNotFoundState.js",
+        reason: "Install app-owned workspace bootstrap status composable for workspace-dependent surfaces.",
+        category: "workspaces-web",
+        id: "users-web-composable-workspace-not-found-state",
+        when: {
+          config: "tenancyMode",
+          in: ["personal", "workspaces"]
+        }
+      },
+      {
+        from: "templates/src/surfaces/app/root.vue",
+        toSurface: "app",
+        toSurfaceRoot: true,
+        reason: "Install workspace app surface wrapper shell for workspaces-web.",
+        category: "workspaces-web",
+        id: "users-web-page-app-wrapper",
+        when: {
+          config: "tenancyMode",
+          in: ["personal", "workspaces"]
+        }
+      },
+      {
+        from: "templates/src/surfaces/app/index.vue",
+        toSurface: "app",
+        toSurfacePath: "index.vue",
+        reason: "Install workspace app surface starter page scaffold for workspaces-web.",
+        category: "workspaces-web",
+        id: "users-web-page-app-index",
+        when: {
+          config: "tenancyMode",
+          in: ["personal", "workspaces"]
+        }
+      },
+      {
+        from: "templates/src/surfaces/admin/root.vue",
+        toSurface: "admin",
+        toSurfaceRoot: true,
+        reason: "Install workspace admin surface wrapper shell for workspaces-web.",
+        category: "workspaces-web",
+        id: "users-web-page-admin-wrapper",
+        when: {
+          config: "tenancyMode",
+          in: ["personal", "workspaces"]
+        }
+      },
+      {
+        from: "templates/src/surfaces/admin/index.vue",
+        toSurface: "admin",
+        toSurfacePath: "index.vue",
+        reason: "Install workspace admin surface starter page scaffold for workspaces-web.",
+        category: "workspaces-web",
+        id: "users-web-page-admin-index",
+        when: {
+          config: "tenancyMode",
+          in: ["personal", "workspaces"]
+        }
+      },
+      {
+        from: "templates/src/pages/admin/members/index.vue",
+        toSurface: "admin",
+        toSurfacePath: "members/index.vue",
+        reason: "Install admin members starter page scaffold for workspaces-web members UI.",
+        category: "workspaces-web",
+        id: "users-web-page-admin-members",
+        when: {
+          config: "tenancyMode",
+          in: ["personal", "workspaces"]
+        }
+      },
+      {
+        from: "templates/src/pages/admin/workspace/settings/index.vue",
+        toSurface: "admin",
+        toSurfacePath: "workspace/settings/index.vue",
+        reason: "Install workspace settings page scaffold for workspaces-web workspace admin UI.",
+        category: "workspaces-web",
+        id: "users-web-page-admin-workspace-settings",
+        when: {
+          config: "tenancyMode",
+          in: ["personal", "workspaces"]
+        }
+      }
+    ],
+    text: [
+      {
+        op: "append-text",
+        file: "src/placement.js",
+        position: "bottom",
+        skipIfContains: "id: \"users.workspace.selector\"",
+        value: "\naddPlacement({\n  id: \"users.workspace.selector\",\n  host: \"shell-layout\",\n  position: \"top-left\",\n  surfaces: [\"*\"],\n  order: 200,\n  componentToken: \"users.web.workspace.selector\",\n  props: {\n    allowOnNonWorkspaceSurface: true,\n    targetSurfaceId: \"app\"\n  },\n  when: ({ auth }) => {\n    return Boolean(auth?.authenticated);\n  }\n});\n\naddPlacement({\n  id: \"users.account.invites.cue\",\n  host: \"shell-layout\",\n  position: \"top-right\",\n  surfaces: [\"*\"],\n  order: 850,\n  componentToken: \"local.main.account.pending-invites.cue\",\n  when: ({ auth }) => Boolean(auth?.authenticated)\n});\n\naddPlacement({\n  id: \"users.workspace.tools.widget\",\n  host: \"shell-layout\",\n  position: \"top-right\",\n  surfaces: [\"admin\"],\n  order: 900,\n  componentToken: \"users.web.workspace.tools.widget\"\n});\n\naddPlacement({\n  id: \"users.workspace.menu.workspace-settings\",\n  host: \"workspace-tools\",\n  position: \"primary-menu\",\n  surfaces: [\"admin\"],\n  order: 100,\n  componentToken: \"users.web.workspace-settings.menu-item\"\n});\n\naddPlacement({\n  id: \"users.workspace.menu.members\",\n  host: \"workspace-tools\",\n  position: \"primary-menu\",\n  surfaces: [\"admin\"],\n  order: 200,\n  componentToken: \"users.web.workspace-members.menu-item\"\n});\n",
+        reason: "Append workspace placement entries into app-owned placement registry.",
+        category: "workspaces-web",
+        id: "users-web-placement-block",
+        when: {
+          config: "tenancyMode",
+          in: ["personal", "workspaces"]
+        }
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "top",
+        skipIfContains: "import AccountPendingInvitesCue from \"../components/AccountPendingInvitesCue.vue\";",
+        value: "import AccountPendingInvitesCue from \"../components/AccountPendingInvitesCue.vue\";\n",
+        reason: "Bind app-owned account pending invites cue component into local main client provider imports.",
+        category: "workspaces-web",
+        id: "users-web-main-client-provider-account-invites-import"
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "bottom",
+        skipIfContains: "registerMainClientComponent(\"local.main.account.pending-invites.cue\", () => AccountPendingInvitesCue);",
+        value:
+          "\nregisterMainClientComponent(\"local.main.account.pending-invites.cue\", () => AccountPendingInvitesCue);\n",
+        reason: "Bind app-owned account pending invites cue component token into local main client provider registry.",
+        category: "workspaces-web",
+        id: "users-web-main-client-provider-account-invites-register"
+      },
+      {
+        op: "append-text",
+        file: "src/placement.js",
+        position: "bottom",
+        skipIfContains: "id: \"users.workspace.settings.form\"",
+        value:
+          "\naddPlacement({\n  id: \"users.workspace.settings.form\",\n  host: \"admin-settings\",\n  position: \"forms\",\n  surfaces: [\"admin\"],\n  order: 100,\n  componentToken: \"users.web.workspace-settings.element\"\n});\n",
+        reason: "Append workspace settings form placement into app-owned placement registry.",
+        category: "workspaces-web",
+        id: "users-web-workspace-settings-form-placement",
+        when: {
+          config: "tenancyMode",
+          in: ["personal", "workspaces"]
+        }
+      }
+    ]
+  }
+});

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@jskit-ai/workspaces-web",
+  "version": "0.1.1",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    "./client": "./src/client/index.js",
+    "./client/providers/WorkspacesWebClientProvider": "./src/client/providers/WorkspacesWebClientProvider.js"
+  },
+  "dependencies": {
+    "@jskit-ai/users-web": "0.1.40"
+  }
+}

package/src/client/index.js

@@ -0,0 +1,6 @@
+import { WorkspacesWebClientProvider } from "./providers/WorkspacesWebClientProvider.js";
+
+const clientProviders = Object.freeze([WorkspacesWebClientProvider]);
+
+export { WorkspacesWebClientProvider } from "./providers/WorkspacesWebClientProvider.js";
+export { clientProviders };

package/src/client/providers/WorkspacesWebClientProvider.js

@@ -0,0 +1,5 @@
+import { UsersWorkspacesClientProvider } from "@jskit-ai/users-web/client/providers/UsersWorkspacesClientProvider";
+
+const WorkspacesWebClientProvider = UsersWorkspacesClientProvider;
+
+export { WorkspacesWebClientProvider };

package/templates/packages/main/src/client/components/AccountPendingInvitesCue.vue

@@ -0,0 +1,162 @@
+<script setup>
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import { useQuery } from "@tanstack/vue-query";
+import { mdiEmailAlertOutline } from "@mdi/js";
+import { appendQueryString } from "@jskit-ai/kernel/shared/support";
+import {
+  useWebPlacementContext,
+  resolveSurfaceDefinitionFromPlacementContext,
+  resolveSurfacePathFromPlacementContext,
+  resolveSurfaceNavigationTargetFromPlacementContext
+} from "@jskit-ai/shell-web/client/placement";
+
+const { context: placementContext } = useWebPlacementContext();
+const route = useRoute();
+
+function normalizePendingInvitesCount(value) {
+  const numeric = Number(value);
+  if (!Number.isInteger(numeric) || numeric < 1) {
+    return 0;
+  }
+  return numeric;
+}
+
+function resolveReturnTo() {
+  const fullPath = String(route?.fullPath || "").trim();
+  if (fullPath.startsWith("/") && !fullPath.startsWith("//")) {
+    return fullPath;
+  }
+  const path = String(route?.path || "").trim();
+  if (path.startsWith("/") && !path.startsWith("//")) {
+    return path;
+  }
+  return "/";
+}
+
+function resolveReturnToHref() {
+  if (typeof window === "object" && window?.location?.href) {
+    return String(window.location.href || "").trim() || resolveReturnTo();
+  }
+  return resolveReturnTo();
+}
+
+function countPendingInvites(entries = []) {
+  if (!Array.isArray(entries)) {
+    return 0;
+  }
+
+  let total = 0;
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") {
+      continue;
+    }
+    total += 1;
+  }
+  return total;
+}
+
+const authenticated = computed(() => placementContext.value?.auth?.authenticated === true);
+
+const bootstrapSummaryQuery = useQuery({
+  queryKey: ["local-main", "account", "invites-cue", "bootstrap"],
+  enabled: authenticated,
+  staleTime: 5_000,
+  refetchInterval: 15_000,
+  queryFn: async () => {
+    const response = await fetch("/api/bootstrap", {
+      method: "GET",
+      credentials: "include",
+      headers: {
+        accept: "application/json"
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`Bootstrap request failed with status ${response.status}.`);
+    }
+
+    return response.json();
+  }
+});
+
+const placementPendingInvitesCount = computed(() =>
+  normalizePendingInvitesCount(placementContext.value?.pendingInvitesCount)
+);
+const bootstrapPendingInvitesCount = computed(() => {
+  const payload = bootstrapSummaryQuery.data.value;
+  const invitesEnabled = payload?.app?.features?.workspaceInvites === true;
+  if (!invitesEnabled) {
+    return 0;
+  }
+
+  return countPendingInvites(payload?.pendingInvites);
+});
+const pendingInvitesCount = computed(() =>
+  Math.max(placementPendingInvitesCount.value, bootstrapPendingInvitesCount.value)
+);
+
+const placementWorkspaceInvitesEnabled = computed(() => placementContext.value?.workspaceInvitesEnabled === true);
+const bootstrapWorkspaceInvitesEnabled = computed(() => {
+  const payload = bootstrapSummaryQuery.data.value;
+  return payload?.app?.features?.workspaceInvites === true;
+});
+const workspaceInvitesEnabled = computed(
+  () => placementWorkspaceInvitesEnabled.value || bootstrapWorkspaceInvitesEnabled.value
+);
+
+const isVisible = computed(() => {
+  return (
+    authenticated.value &&
+    workspaceInvitesEnabled.value &&
+    pendingInvitesCount.value > 0
+  );
+});
+
+const resolvedTo = computed(() => {
+  const hasAccountSurface = Boolean(resolveSurfaceDefinitionFromPlacementContext(placementContext.value, "account"));
+  const accountSettingsPath = hasAccountSurface
+    ? resolveSurfacePathFromPlacementContext(placementContext.value, "account", "/")
+    : "/account";
+  const accountSettingsNavigation = resolveSurfaceNavigationTargetFromPlacementContext(placementContext.value, {
+    path: accountSettingsPath,
+    surfaceId: "account"
+  });
+
+  const query = new URLSearchParams({
+    section: "invites",
+    returnTo: accountSettingsNavigation.sameOrigin ? resolveReturnTo() : resolveReturnToHref()
+  });
+  return appendQueryString(accountSettingsPath, query.toString());
+});
+
+const resolvedNavigationTarget = computed(() =>
+  resolveSurfaceNavigationTargetFromPlacementContext(placementContext.value, {
+    path: resolvedTo.value,
+    surfaceId: "account"
+  })
+);
+</script>
+
+<template>
+  <v-badge
+    v-if="isVisible"
+    color="error"
+    :content="pendingInvitesCount"
+    :model-value="pendingInvitesCount > 0"
+    bordered
+    offset-x="6"
+    offset-y="8"
+  >
+    <v-btn
+      :to="resolvedNavigationTarget.sameOrigin ? resolvedNavigationTarget.href : undefined"
+      :href="resolvedNavigationTarget.sameOrigin ? undefined : resolvedNavigationTarget.href"
+      variant="tonal"
+      color="warning"
+      :prepend-icon="mdiEmailAlertOutline"
+      size="small"
+      class="text-none"
+    >
+      Invites
+    </v-btn>
+  </v-badge>
+</template>

package/templates/src/components/WorkspaceNotFoundCard.vue

@@ -0,0 +1,34 @@
+<script setup>
+import { mdiAlertCircleOutline } from "@mdi/js";
+import { computed } from "vue";
+
+const props = defineProps({
+  surfaceLabel: {
+    type: String,
+    default: "Workspace"
+  },
+  message: {
+    type: String,
+    default: "Workspace is currently unavailable."
+  }
+});
+
+const normalizedSurfaceLabel = computed(() => String(props.surfaceLabel || "").trim() || "Workspace");
+const normalizedMessage = computed(() => String(props.message || "").trim() || "Workspace is currently unavailable.");
+</script>
+
+<template>
+  <v-card rounded="lg" elevation="1" border>
+    <v-card-item>
+      <template #prepend>
+        <v-icon :icon="mdiAlertCircleOutline" color="error" />
+      </template>
+      <v-card-title class="text-h5">Unavailable</v-card-title>
+      <v-card-subtitle>{{ normalizedSurfaceLabel }} surface.</v-card-subtitle>
+    </v-card-item>
+    <v-divider />
+    <v-card-text class="d-flex flex-column ga-4">
+      <p class="text-medium-emphasis mb-0">{{ normalizedMessage }}</p>
+    </v-card-text>
+  </v-card>
+</template>

package/templates/src/composables/useWorkspaceNotFoundState.js

@@ -0,0 +1,41 @@
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import { normalizeLowerText, normalizeObject } from "@jskit-ai/kernel/shared/support/normalize";
+import { useWebPlacementContext } from "@jskit-ai/shell-web/client/placement";
+
+const STATUS_MESSAGES = {
+  not_found: "The requested workspace was not found.",
+  forbidden: "You do not have access to this workspace.",
+  unauthenticated: "You need to sign in to access this workspace.",
+  error: "Workspace data could not be loaded right now."
+};
+const DEFAULT_WORKSPACE_UNAVAILABLE_MESSAGE = "Workspace is currently unavailable.";
+const RESOLVED_WORKSPACE_STATUS = "resolved";
+
+function useWorkspaceNotFoundState() {
+  const route = useRoute();
+  const { context: placementContext } = useWebPlacementContext();
+
+  const routeWorkspaceSlug = computed(() => normalizeLowerText(route?.params?.workspaceSlug));
+
+  const workspaceBootstrapStatus = computed(() => {
+    const statuses = normalizeObject(placementContext.value?.workspaceBootstrapStatuses);
+    return normalizeLowerText(statuses[routeWorkspaceSlug.value]);
+  });
+
+  const workspaceUnavailable = computed(
+    () => Boolean(workspaceBootstrapStatus.value) && workspaceBootstrapStatus.value !== RESOLVED_WORKSPACE_STATUS
+  );
+  const workspaceUnavailableMessage = computed(
+    () => STATUS_MESSAGES[workspaceBootstrapStatus.value] || DEFAULT_WORKSPACE_UNAVAILABLE_MESSAGE
+  );
+
+  return Object.freeze({
+    routeWorkspaceSlug,
+    workspaceBootstrapStatus,
+    workspaceUnavailable,
+    workspaceUnavailableMessage
+  });
+}
+
+export { useWorkspaceNotFoundState };

package/templates/src/pages/admin/members/index.vue

@@ -0,0 +1,7 @@
+<template>
+  <WorkspaceMembersClientElement />
+</template>
+
+<script setup>
+import WorkspaceMembersClientElement from "@jskit-ai/users-web/client/components/WorkspaceMembersClientElement";
+</script>

package/templates/src/pages/admin/workspace/settings/index.vue

@@ -0,0 +1,17 @@
+<template>
+  <section class="settings-page">
+    <ShellOutlet host="admin-settings" position="primary-menu" />
+    <ShellOutlet host="admin-settings" position="forms" />
+  </section>
+</template>
+
+<script setup>
+import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
+</script>
+
+<style scoped>
+.settings-page {
+  display: grid;
+  gap: 1rem;
+}
+</style>

package/templates/src/surfaces/admin/index.vue

@@ -0,0 +1,29 @@
+<script setup>
+import WorkspaceNotFoundCard from "@/components/WorkspaceNotFoundCard.vue";
+import { useWorkspaceNotFoundState } from "@/composables/useWorkspaceNotFoundState";
+
+const { workspaceUnavailable, workspaceUnavailableMessage } = useWorkspaceNotFoundState();
+</script>
+
+<template>
+  <WorkspaceNotFoundCard
+    v-if="workspaceUnavailable"
+    :message="workspaceUnavailableMessage"
+    surface-label="Admin"
+  />
+  <v-card v-else rounded="lg" elevation="1" border>
+    <v-card-item>
+      <template #prepend>
+        <v-chip color="primary" size="small" label>Admin</v-chip>
+      </template>
+      <v-card-title class="text-h5">Workspace Admin</v-card-title>
+      <v-card-subtitle>Privileged workspace workflows.</v-card-subtitle>
+    </v-card-item>
+    <v-divider />
+    <v-card-text class="d-flex flex-column ga-4">
+      <p class="text-medium-emphasis mb-0">
+        Use this area for workspace administration modules.
+      </p>
+    </v-card-text>
+  </v-card>
+</template>

package/templates/src/surfaces/admin/root.vue

@@ -0,0 +1,20 @@
+<route lang="json">
+{
+  "meta": {
+    "jskit": {
+      "surface": "admin"
+    }
+  }
+}
+</route>
+
+<script setup>
+import ShellLayout from "@/components/ShellLayout.vue";
+import { RouterView } from "vue-router";
+</script>
+
+<template>
+  <ShellLayout title="" subtitle="">
+    <RouterView />
+  </ShellLayout>
+</template>

package/templates/src/surfaces/app/index.vue

@@ -0,0 +1,27 @@
+<script setup>
+import WorkspaceNotFoundCard from "@/components/WorkspaceNotFoundCard.vue";
+import { useWorkspaceNotFoundState } from "@/composables/useWorkspaceNotFoundState";
+
+const { workspaceUnavailable, workspaceUnavailableMessage } = useWorkspaceNotFoundState();
+</script>
+
+<template>
+  <WorkspaceNotFoundCard
+    v-if="workspaceUnavailable"
+    :message="workspaceUnavailableMessage"
+    surface-label="App"
+  />
+  <v-card v-else rounded="lg" elevation="1" border>
+    <v-card-item>
+      <template #prepend>
+        <v-chip color="primary" size="small" label>App</v-chip>
+      </template>
+      <v-card-title class="text-h5">Workspace Home</v-card-title>
+      <v-card-subtitle>Primary in-workspace surface.</v-card-subtitle>
+    </v-card-item>
+    <v-divider />
+    <v-card-text class="d-flex flex-column ga-4">
+      <p class="text-medium-emphasis mb-0">Replace this page with your workspace dashboard modules.</p>
+    </v-card-text>
+  </v-card>
+</template>

package/templates/src/surfaces/app/root.vue

@@ -0,0 +1,20 @@
+<route lang="json">
+{
+  "meta": {
+    "jskit": {
+      "surface": "app"
+    }
+  }
+}
+</route>
+
+<script setup>
+import ShellLayout from "@/components/ShellLayout.vue";
+import { RouterView } from "vue-router";
+</script>
+
+<template>
+  <ShellLayout title="" subtitle="">
+    <RouterView />
+  </ShellLayout>
+</template>

package/test/exportsContract.test.js

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { evaluatePackageExportsContract } from "../../../tooling/test-support/exportsContract.mjs";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
+const PACKAGE_DIR = path.join(REPO_ROOT, "packages", "workspaces-web");
+
+test("workspaces-web exports are explicit and aligned with production usage", () => {
+  const result = evaluatePackageExportsContract({
+    repoRoot: REPO_ROOT,
+    packageDir: PACKAGE_DIR,
+    packageId: "@jskit-ai/workspaces-web",
+    requiredExports: [
+      "./client",
+      "./client/providers/WorkspacesWebClientProvider"
+    ]
+  });
+
+  assert.deepEqual(
+    result.wildcardExports,
+    [],
+    `workspaces-web exports must be explicit. Remove wildcard keys: ${result.wildcardExports.join(", ")}`
+  );
+  assert.deepEqual(
+    result.missingRequiredExports,
+    [],
+    `workspaces-web required exports missing: ${result.missingRequiredExports.join(", ")}`
+  );
+  assert.deepEqual(
+    result.missingExports,
+    [],
+    `workspaces-web imports missing from package exports:\n${result.missingExports.join("\n")}`
+  );
+  assert.deepEqual(
+    result.staleExports,
+    [],
+    `Stale workspaces-web exports found. Remove stale keys: ${result.staleExports.join(", ")}`
+  );
+});

package/test/settingsPlacementContract.test.js

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import descriptor from "../package.descriptor.mjs";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
+
+function readSettingsOutlets() {
+  const outlets = descriptor?.metadata?.ui?.placements?.outlets;
+  return Array.isArray(outlets)
+    ? outlets.filter((entry) => String(entry?.host || "").trim() === "admin-settings")
+    : [];
+}
+
+function findContribution(id) {
+  const contributions = descriptor?.metadata?.ui?.placements?.contributions;
+  return Array.isArray(contributions)
+    ? contributions.find((entry) => String(entry?.id || "").trim() === id) || null
+    : null;
+}
+
+test("workspaces-web admin settings template exposes surface-derived settings outlets", async () => {
+  const source = await readFile(
+    path.join(PACKAGE_DIR, "templates", "src", "pages", "admin", "workspace", "settings", "index.vue"),
+    "utf8"
+  );
+
+  assert.match(source, /<ShellOutlet host="admin-settings" position="primary-menu" \/>/);
+  assert.match(source, /<ShellOutlet host="admin-settings" position="forms" \/>/);
+});
+
+test("workspaces-web descriptor metadata advertises admin settings outlets and form placement on the derived host", () => {
+  assert.deepEqual(
+    readSettingsOutlets(),
+    [
+      {
+        host: "admin-settings",
+        position: "primary-menu",
+        surfaces: ["admin"],
+        source: "templates/src/pages/admin/workspace/settings/index.vue"
+      },
+      {
+        host: "admin-settings",
+        position: "forms",
+        surfaces: ["admin"],
+        source: "templates/src/pages/admin/workspace/settings/index.vue"
+      }
+    ]
+  );
+
+  assert.deepEqual(findContribution("users.workspace.settings.form"), {
+    id: "users.workspace.settings.form",
+    host: "admin-settings",
+    position: "forms",
+    surfaces: ["admin"],
+    order: 100,
+    componentToken: "users.web.workspace-settings.element",
+    source: "mutations.text#users-web-workspace-settings-form-placement"
+  });
+});