@jskit-ai/workspaces-web 0.1.42 → 0.1.43

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/workspaces-web",
-  version: "0.1.42",
+  version: "0.1.43",
   kind: "runtime",
   description: "Workspace web module: workspace selector, tools widget, workspace surfaces, and members/settings UI.",
   dependsOn: [
@@ -41,6 +41,10 @@ export default Object.freeze({
           subpath: "./client/components/AccountSettingsInvitesSection",
           summary: "Exports the default account invites section component used by multihoming installs."
         },
+        {
+          subpath: "./client/components/WorkspaceSettingsClientElement",
+          summary: "Exports the workspace settings client element used by the workspace admin settings starter page."
+        },
         {
           subpath: "./client/providers/WorkspacesWebClientProvider",
           summary: "Exports workspaces-web client provider class."
@@ -227,9 +231,8 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/workspaces-core": "0.1.42",
-        "@jskit-ai/users-web": "0.1.81",
-        "vuetify": "^4.0.0"
+        "@jskit-ai/workspaces-core": "0.1.43",
+        "@jskit-ai/users-web": "0.1.82"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/workspaces-web",
-  "version": "0.1.42",
+  "version": "0.1.43",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -10,21 +10,22 @@
     "./client/components/AccountSettingsInvitesSection": "./src/client/components/AccountSettingsInvitesSection.vue",
     "./client/providers/WorkspacesWebClientProvider": "./src/client/providers/WorkspacesWebClientProvider.js",
     "./client/components/WorkspaceMembersClientElement": "./src/client/components/WorkspaceMembersClientElement.vue",
+    "./client/components/WorkspaceSettingsClientElement": "./src/client/components/WorkspaceSettingsClientElement.vue",
     "./client/composables/useWorkspaceRouteContext": "./src/client/composables/useWorkspaceRouteContext.js"
   },
   "dependencies": {
-    "@tanstack/vue-query": "5.92.12",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/http-runtime": "0.1.65",
-    "@jskit-ai/kernel": "0.1.66",
-    "@jskit-ai/shell-web": "0.1.65",
-    "@jskit-ai/users-core": "0.1.76",
-    "@jskit-ai/users-web": "0.1.81",
-    "@jskit-ai/workspaces-core": "0.1.42",
-    "vuetify": "^4.0.0"
+    "@jskit-ai/http-runtime": "0.1.66",
+    "@jskit-ai/kernel": "0.1.67",
+    "@jskit-ai/shell-web": "0.1.66",
+    "@jskit-ai/users-core": "0.1.77",
+    "@jskit-ai/users-web": "0.1.82",
+    "@jskit-ai/workspaces-core": "0.1.43"
   },
   "peerDependencies": {
+    "@tanstack/vue-query": "^5.90.5",
     "vue": "^3.5.13",
-    "vue-router": "^5.0.4"
+    "vue-router": "^5.0.4",
+    "vuetify": "^4.0.0"
   }
 }

package/src/client/components/AccountSettingsInvitesSection.vue

@@ -5,13 +5,13 @@ const invites = useAccountSettingsInvitesSectionRuntime();
 </script>
 
 <template>
-  <v-card rounded="lg" elevation="0" border>
-    <v-card-item>
-      <v-card-title class="text-subtitle-1">Invitations</v-card-title>
-      <v-card-subtitle>Accept or refuse workspace invitations.</v-card-subtitle>
-    </v-card-item>
-    <v-divider />
-    <v-card-text>
+  <v-sheet rounded="lg" border class="account-invites-section">
+    <header class="account-invites-section__header">
+      <h2 class="account-invites-section__title">Invitations</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">Accept or refuse workspace invitations.</p>
+    </header>
+
+    <div class="account-invites-section__body">
       <template v-if="invites.isLoading.value">
         <v-skeleton-loader type="text@2, list-item-two-line@3" />
       </template>
@@ -67,6 +67,33 @@ const invites = useAccountSettingsInvitesSectionRuntime();
           </v-list-item>
         </v-list>
       </template>
-    </v-card-text>
-  </v-card>
+    </div>
+  </v-sheet>
 </template>
+
+<style scoped>
+.account-invites-section {
+  overflow: hidden;
+}
+
+.account-invites-section__header {
+  padding: 1rem 1rem 0;
+}
+
+.account-invites-section__title {
+  font-size: 1rem;
+  font-weight: 650;
+  line-height: 1.2;
+  margin: 0 0 0.25rem;
+}
+
+.account-invites-section__body {
+  padding: 1rem;
+}
+
+@media (max-width: 640px) {
+  .account-invites-section__body :deep(.v-btn) {
+    min-height: 48px;
+  }
+}
+</style>

package/src/client/components/WorkspaceMembersClientElement.vue

@@ -1,8 +1,17 @@
 <template>
   <section class="workspace-members-page">
-    <p v-if="loadError" class="text-body-2 text-medium-emphasis mb-4">
-      {{ loadError }}
-    </p>
+    <div v-if="loadError" class="workspace-members-page__state">
+      <p class="text-body-2 text-medium-emphasis mb-4">{{ loadError }}</p>
+      <v-btn
+        v-if="canRetryLoad"
+        color="primary"
+        variant="tonal"
+        :loading="isRetryingLoad"
+        @click="refreshLoad"
+      >
+        Retry
+      </v-btn>
+    </div>
 
     <MembersAdminClientElement
       v-else
@@ -38,7 +47,6 @@ import { useView } from "@jskit-ai/users-web/client/composables/useView";
 import { usePaths } from "@jskit-ai/users-web/client/composables/usePaths";
 import { useAccess } from "@jskit-ai/users-web/client/composables/useAccess";
 import { useUiFeedback } from "@jskit-ai/users-web/client/composables/runtime/useUiFeedback";
-import { useShellWebErrorRuntime } from "@jskit-ai/shell-web/client/error";
 import { useWorkspaceRouteContext } from "../composables/useWorkspaceRouteContext.js";
 import { createWorkspaceRealtimeMatcher } from "../support/realtimeWorkspace.js";
 import { buildWorkspaceQueryKey } from "../support/workspaceQueryKeys.js";
@@ -75,7 +83,6 @@ const removeMemberUserId = ref("");
 
 const { route, currentSurfaceId, workspaceSlugFromRoute } = useWorkspaceRouteContext();
 const usersPaths = usePaths();
-const errorRuntime = useShellWebErrorRuntime();
 const OWNERSHIP_WORKSPACE = ROUTE_VISIBILITY_WORKSPACE;
 
 const hasRouteWorkspaceSlug = computed(() => Boolean(workspaceSlugFromRoute.value));
@@ -423,27 +430,44 @@ const loadError = computed(() => {
     return "Workspace slug is required in the URL.";
   }
 
-  return access.bootstrapError.value;
+  return (
+    access.bootstrapError.value ||
+    workspaceSettingsView.loadError ||
+    workspaceRolesView.loadError ||
+    workspaceMembersList.loadError ||
+    workspaceInvitesList.loadError ||
+    ""
+  );
 });
-
-watch(
-  loadError,
-  (nextLoadError) => {
-    if (!nextLoadError) {
-      return;
-    }
-    errorRuntime.report({
-      source: "users-web.workspace-members-view",
-      severity: "error",
-      channel: "banner",
-      message: String(nextLoadError || "Unable to load workspace members."),
-      dedupeKey: `users-web.workspace-members-view:bootstrap:${nextLoadError}`,
-      dedupeWindowMs: 3000
-    });
-  },
-  { immediate: true }
+const canRetryLoad = computed(() => Boolean(hasRouteWorkspaceSlug.value && !access.bootstrapError.value));
+const isRetryingLoad = computed(() =>
+  Boolean(
+    workspaceSettingsView.isFetching ||
+    workspaceRolesView.isFetching ||
+    workspaceMembersList.isFetching ||
+    workspaceInvitesList.isFetching
+  )
 );
 
+async function refreshLoad() {
+  if (!canRetryLoad.value) {
+    return;
+  }
+
+  const jobs = [];
+  if (canInviteMembers.value) {
+    jobs.push(workspaceSettingsView.refresh());
+  }
+  if (canInviteMembers.value || canViewMembers.value) {
+    jobs.push(workspaceRolesView.refresh());
+  }
+  if (canViewMembers.value) {
+    jobs.push(workspaceMembersList.reload());
+    jobs.push(workspaceInvitesList.reload());
+  }
+  await Promise.all(jobs);
+}
+
 const actions = Object.freeze({
   submitInvite,
   submitRevokeInvite,
@@ -522,17 +546,6 @@ watch(
   { immediate: true }
 );
 
-watch(
-  () => workspaceMembersList.loadError,
-  (nextLoadError) => {
-    if (!nextLoadError) {
-      membersFeedback.clear();
-      return;
-    }
-    membersFeedback.error(null, nextLoadError);
-  }
-);
-
 watch(
   () => workspaceInvitesList.items,
   (nextInvites) => {
@@ -553,17 +566,6 @@ watch(
   { immediate: true }
 );
 
-watch(
-  () => workspaceInvitesList.loadError,
-  (nextLoadError) => {
-    if (!nextLoadError) {
-      teamFeedback.clear();
-      return;
-    }
-    teamFeedback.error(null, nextLoadError);
-  }
-);
-
 watch(
   () => route.fullPath,
   () => {
@@ -671,3 +673,18 @@ async function submitRemoveMember(member) {
   }
 }
 </script>
+
+<style scoped>
+.workspace-members-page__state {
+  margin-inline: auto;
+  max-width: 30rem;
+  padding: 2rem 1rem;
+  text-align: center;
+}
+
+@media (max-width: 640px) {
+  .workspace-members-page__state :deep(.v-btn) {
+    min-height: 48px;
+  }
+}
+</style>

package/src/client/components/WorkspaceProfileClientElement.vue

@@ -1,18 +1,27 @@
 <template>
-  <v-card class="mb-4" rounded="lg" elevation="1" border>
-    <v-card-item>
-      <v-card-title class="text-h6">Workspace profile</v-card-title>
-      <v-card-subtitle>Name and avatar used across the workspace.</v-card-subtitle>
-    </v-card-item>
-    <v-divider />
-    <v-card-text class="pt-4">
+  <v-sheet rounded="lg" border class="workspace-profile-panel">
+    <header class="workspace-profile-panel__header">
+      <h2 class="workspace-profile-panel__title">Workspace profile</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">Name and avatar used across the workspace.</p>
+    </header>
+
+    <div class="workspace-profile-panel__body">
       <template v-if="showSkeleton">
         <v-skeleton-loader type="text@2, list-item-two-line@3, button" />
       </template>
 
-      <p v-else-if="addEdit.loadError" class="text-body-2 text-medium-emphasis mb-4">
-        {{ addEdit.loadError }}
-      </p>
+      <div v-else-if="addEdit.loadError" class="workspace-profile-panel__state">
+        <p class="text-body-2 text-medium-emphasis mb-4">{{ addEdit.loadError }}</p>
+        <v-btn
+          v-if="addEdit.canRetryLoad"
+          color="primary"
+          variant="tonal"
+          :loading="addEdit.isFetching"
+          @click="addEdit.refresh"
+        >
+          Retry
+        </v-btn>
+      </div>
 
       <p v-else-if="!addEdit.canView" class="text-body-2 text-medium-emphasis mb-4">
         You do not have permission to view workspace profile.
@@ -62,8 +71,8 @@
           </v-row>
         </v-form>
       </template>
-    </v-card-text>
-  </v-card>
+    </div>
+  </v-sheet>
 </template>
 
 <script setup>
@@ -110,3 +119,37 @@ const addEdit = useAddEdit({
 
 const showSkeleton = computed(() => Boolean(addEdit.isInitialLoading));
 </script>
+
+<style scoped>
+.workspace-profile-panel {
+  overflow: hidden;
+}
+
+.workspace-profile-panel__header {
+  padding: 1rem 1rem 0;
+}
+
+.workspace-profile-panel__title {
+  font-size: 1rem;
+  font-weight: 650;
+  line-height: 1.2;
+  margin: 0 0 0.25rem;
+}
+
+.workspace-profile-panel__body {
+  padding: 1rem;
+}
+
+.workspace-profile-panel__state {
+  margin-inline: auto;
+  max-width: 30rem;
+  padding: 1.5rem 1rem;
+  text-align: center;
+}
+
+@media (max-width: 640px) {
+  .workspace-profile-panel__body :deep(.v-btn) {
+    min-height: 48px;
+  }
+}
+</style>

package/src/client/components/WorkspaceSettingsClientElement.vue

@@ -1,5 +1,5 @@
 <template>
-  <section class="workspace-settings-client-element">
+  <section class="workspace-settings-client-element d-flex flex-column ga-4">
     <WorkspaceProfileClientElement @saved="handleFormSaved" />
     <WorkspaceSettingsFieldsClientElement @saved="handleFormSaved" />
   </section>

package/src/client/components/WorkspaceSettingsFieldsClientElement.vue

@@ -1,18 +1,27 @@
 <template>
-  <v-card rounded="lg" elevation="1" border>
-    <v-card-item>
-      <v-card-title class="text-h6">Workspace settings</v-card-title>
-      <v-card-subtitle>These values apply to everyone in this workspace.</v-card-subtitle>
-    </v-card-item>
-    <v-divider />
-    <v-card-text class="pt-4">
+  <v-sheet rounded="lg" border class="workspace-settings-panel">
+    <header class="workspace-settings-panel__header">
+      <h2 class="workspace-settings-panel__title">Workspace settings</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">These values apply to everyone in this workspace.</p>
+    </header>
+
+    <div class="workspace-settings-panel__body">
       <template v-if="showSkeleton">
         <v-skeleton-loader type="text@2, list-item-two-line@4, button" />
       </template>
 
-      <p v-else-if="addEdit.loadError" class="text-body-2 text-medium-emphasis mb-4">
-        {{ addEdit.loadError }}
-      </p>
+      <div v-else-if="addEdit.loadError" class="workspace-settings-panel__state">
+        <p class="text-body-2 text-medium-emphasis mb-4">{{ addEdit.loadError }}</p>
+        <v-btn
+          v-if="addEdit.canRetryLoad"
+          color="primary"
+          variant="tonal"
+          :loading="addEdit.isFetching"
+          @click="addEdit.refresh"
+        >
+          Retry
+        </v-btn>
+      </div>
 
       <p v-else-if="!addEdit.canView" class="text-body-2 text-medium-emphasis mb-4">
         You do not have permission to view workspace settings.
@@ -162,8 +171,8 @@
           </v-row>
         </v-form>
       </template>
-    </v-card-text>
-  </v-card>
+    </div>
+  </v-sheet>
 </template>
 
 <script setup>
@@ -259,3 +268,37 @@ const addEdit = useAddEdit({
 
 const showSkeleton = computed(() => Boolean(addEdit.isInitialLoading));
 </script>
+
+<style scoped>
+.workspace-settings-panel {
+  overflow: hidden;
+}
+
+.workspace-settings-panel__header {
+  padding: 1rem 1rem 0;
+}
+
+.workspace-settings-panel__title {
+  font-size: 1rem;
+  font-weight: 650;
+  line-height: 1.2;
+  margin: 0 0 0.25rem;
+}
+
+.workspace-settings-panel__body {
+  padding: 1rem;
+}
+
+.workspace-settings-panel__state {
+  margin-inline: auto;
+  max-width: 30rem;
+  padding: 1.5rem 1rem;
+  text-align: center;
+}
+
+@media (max-width: 640px) {
+  .workspace-settings-panel__body :deep(.v-btn) {
+    min-height: 48px;
+  }
+}
+</style>

package/src/client/components/WorkspacesClientElement.vue

@@ -163,13 +163,14 @@ const workspaceInvitesEnabled = computed(() => bootstrapModel.workspaceInvitesEn
 
 const isBootstrapping = computed(() => Boolean(bootstrapView.isLoading));
 const isRefreshingBootstrap = computed(() => Boolean(bootstrapView.isRefetching));
+const bootstrapLoadError = computed(() => String(bootstrapView.loadError || "").trim());
 const canCreateWorkspace = computed(() => bootstrapModel.workspaceAllowSelfCreate === true);
 const isCreatingWorkspace = computed(() => Boolean(createWorkspaceCommand.isRunning.value));
 
 function reportFeedback({
   message,
   severity = "error",
-  channel = "banner",
+  channel = "",
   dedupeKey = ""
 } = {}) {
   const normalizedMessage = String(message || "").trim();
@@ -180,6 +181,7 @@ function reportFeedback({
   errorRuntime.report({
     source: "users-web.workspaces-view",
     message: normalizedMessage,
+    intent: "action-feedback",
     severity,
     channel,
     dedupeKey: dedupeKey || `users-web.workspaces-view:${severity}:${normalizedMessage}`,
@@ -233,7 +235,6 @@ async function openWorkspace(workspaceSlug) {
     reportFeedback({
       message: "Workspace surface is not configured.",
       severity: "error",
-      channel: "banner",
       dedupeKey: "users-web.workspaces-view:workspace-surface-missing"
     });
     return;
@@ -258,7 +259,6 @@ async function openWorkspace(workspaceSlug) {
     reportFeedback({
       message: String(error?.message || "Unable to open workspace."),
       severity: "error",
-      channel: "banner",
       dedupeKey: `users-web.workspaces-view:open-workspace:${normalizedSlug}`
     });
   } finally {
@@ -301,7 +301,6 @@ async function respondToInvite(invite, decision) {
     reportFeedback({
       message: "Invitation refused.",
       severity: "success",
-      channel: "snackbar",
       dedupeKey: `users-web.workspaces-view:invite-refused:${token}`
     });
   } catch (error) {
@@ -310,7 +309,6 @@ async function respondToInvite(invite, decision) {
         error?.message || (normalizedDecision === "accept" ? "Unable to accept invite." : "Unable to refuse invite.")
       ),
       severity: "error",
-      channel: "banner",
       dedupeKey: `users-web.workspaces-view:invite-${normalizedDecision}:${token}`
     });
   } finally {
@@ -341,7 +339,6 @@ async function createWorkspace() {
     reportFeedback({
       message: "Workspace name is required.",
       severity: "error",
-      channel: "banner",
       dedupeKey: "users-web.workspaces-view:create-workspace-name-required"
     });
     return;
@@ -361,12 +358,15 @@ async function createWorkspace() {
     reportFeedback({
       message: String(error?.message || "Unable to create workspace."),
       severity: "error",
-      channel: "banner",
       dedupeKey: "users-web.workspaces-view:create-workspace-error"
     });
   }
 }
 
+async function refreshBootstrap() {
+  return bootstrapView.refresh();
+}
+
 watch(
   () => bootstrapView.resource.data.value,
   async (payload) => {
@@ -401,20 +401,31 @@ watch(
 <template>
   <section class="workspaces-view py-6">
     <v-container class="mx-auto" max-width="860">
-      <v-card rounded="lg" border elevation="1">
-        <v-card-item>
-          <v-card-title class="text-h6">You are logged in</v-card-title>
-          <v-card-subtitle>Select a workspace or respond to invitations.</v-card-subtitle>
-        </v-card-item>
-        <v-divider />
-
-        <v-card-text class="pt-4">
+      <v-sheet rounded="lg" border class="workspaces-view__panel">
+        <header class="workspaces-view__header">
+          <h1 class="workspaces-view__title">You are logged in</h1>
+          <p class="text-body-2 text-medium-emphasis mb-0">Select a workspace or respond to invitations.</p>
+        </header>
+
+        <div class="workspaces-view__body">
           <v-progress-linear v-if="!isBootstrapping && isRefreshingBootstrap" indeterminate class="mb-4" />
           <v-row>
             <v-col cols="12" :md="workspaceInvitesEnabled ? 6 : 12">
               <template v-if="isBootstrapping">
                 <v-skeleton-loader type="text, list-item-avatar-two-line@3" />
               </template>
+              <div v-else-if="bootstrapLoadError" class="workspaces-view__state">
+                <h2 class="text-h6 mb-2">Unable to load workspaces</h2>
+                <p class="text-body-2 text-medium-emphasis mb-4">{{ bootstrapLoadError }}</p>
+                <v-btn
+                  color="primary"
+                  variant="tonal"
+                  :loading="isRefreshingBootstrap"
+                  @click="refreshBootstrap"
+                >
+                  Retry
+                </v-btn>
+              </div>
               <template v-else>
                 <div class="text-subtitle-2 mb-2">Your workspaces</div>
                 <template v-if="workspaceItems.length === 0">
@@ -539,8 +550,47 @@ watch(
               </template>
             </v-col>
           </v-row>
-        </v-card-text>
-      </v-card>
+        </div>
+      </v-sheet>
     </v-container>
   </section>
 </template>
+
+<style scoped>
+.workspaces-view__panel {
+  overflow: hidden;
+}
+
+.workspaces-view__header {
+  padding: 1rem 1rem 0;
+}
+
+.workspaces-view__title {
+  font-size: clamp(1.35rem, 2vw, 1.85rem);
+  font-weight: 650;
+  letter-spacing: -0.02em;
+  line-height: 1.15;
+  margin: 0 0 0.35rem;
+}
+
+.workspaces-view__body {
+  padding: 1rem;
+}
+
+.workspaces-view__state {
+  margin-inline: auto;
+  max-width: 30rem;
+  padding: 2rem 1rem;
+  text-align: center;
+}
+
+@media (max-width: 640px) {
+  .workspaces-view {
+    padding-block: 0.75rem !important;
+  }
+
+  .workspaces-view__body :deep(.v-btn) {
+    min-height: 48px;
+  }
+}
+</style>

package/templates/src/components/WorkspaceNotFoundCard.vue

@@ -18,17 +18,36 @@ const normalizedMessage = computed(() => String(props.message || "").trim() || "
 </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>
+  <v-sheet rounded="lg" border class="workspace-unavailable-panel">
+    <div class="workspace-unavailable-panel__header">
+      <v-icon :icon="mdiAlertCircleOutline" color="error" />
+      <div>
+        <h1 class="workspace-unavailable-panel__title">Unavailable</h1>
+        <p class="text-body-2 text-medium-emphasis mb-0">{{ normalizedSurfaceLabel }} surface.</p>
+      </div>
+    </div>
+    <p class="text-body-2 text-medium-emphasis mb-0">{{ normalizedMessage }}</p>
+  </v-sheet>
 </template>
+
+<style scoped>
+.workspace-unavailable-panel {
+  display: grid;
+  gap: 1rem;
+  padding: 1rem;
+}
+
+.workspace-unavailable-panel__header {
+  align-items: flex-start;
+  display: flex;
+  gap: 0.75rem;
+}
+
+.workspace-unavailable-panel__title {
+  font-size: clamp(1.35rem, 2vw, 1.85rem);
+  font-weight: 650;
+  letter-spacing: -0.02em;
+  line-height: 1.15;
+  margin: 0 0 0.25rem;
+}
+</style>

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

@@ -1,11 +1,7 @@
 <script setup>
-// To redirect this settings shell to a child page, uncomment and edit the example below.
-// import { redirectToChild } from "@jskit-ai/kernel/client/pageRedirects";
-// definePage({
-//   redirect: redirectToChild("your_child_segment")
-// });
+import WorkspaceSettingsClientElement from "@jskit-ai/workspaces-web/client/components/WorkspaceSettingsClientElement";
 </script>
 
 <template>
-  <div />
+  <WorkspaceSettingsClientElement />
 </template>

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

@@ -5,25 +5,66 @@ import { RouterView } from "vue-router";
 
 <template>
   <section class="settings-shell d-flex flex-column ga-4">
-    <v-card rounded="lg" elevation="1" border>
-      <v-card-item>
-        <v-card-title>Workspace settings</v-card-title>
-        <v-card-subtitle>Configure the current workspace and its members.</v-card-subtitle>
-      </v-card-item>
-      <v-divider />
-      <v-card-text class="pt-4">
-        <v-row no-gutters>
-          <v-col cols="12" md="3" lg="2" class="pr-md-4 mb-4 mb-md-0">
-            <v-list nav density="comfortable" rounded="lg" border>
-              <ShellOutlet target="admin-settings:primary-menu" />
-            </v-list>
-          </v-col>
-
-          <v-col cols="12" md="9" lg="10">
-            <RouterView />
-          </v-col>
-        </v-row>
-      </v-card-text>
-    </v-card>
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">Settings</p>
+      <h1 class="settings-shell__title">Workspace settings</h1>
+      <p class="text-body-2 text-medium-emphasis mb-0">Configure the current workspace and its members.</p>
+    </header>
+
+    <v-sheet rounded="lg" border class="settings-shell__panel">
+      <nav class="settings-shell__nav" aria-label="Workspace settings sections">
+        <v-list nav density="comfortable" class="settings-shell__nav-list">
+          <ShellOutlet target="admin-settings:primary-menu" />
+        </v-list>
+      </nav>
+      <main class="settings-shell__content">
+        <RouterView />
+      </main>
+    </v-sheet>
   </section>
 </template>
+
+<style scoped>
+.settings-shell__title {
+  font-size: clamp(1.35rem, 2vw, 1.85rem);
+  font-weight: 650;
+  letter-spacing: -0.02em;
+  line-height: 1.15;
+  margin: 0 0 0.35rem;
+}
+
+.settings-shell__panel {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: minmax(12rem, 16rem) minmax(0, 1fr);
+  padding: 1rem;
+}
+
+.settings-shell__nav-list {
+  padding: 0;
+}
+
+.settings-shell__content {
+  min-width: 0;
+}
+
+@media (max-width: 960px) {
+  .settings-shell__panel {
+    grid-template-columns: 1fr;
+  }
+
+  .settings-shell__nav {
+    overflow-x: auto;
+  }
+
+  .settings-shell__nav-list {
+    display: flex;
+    gap: 0.5rem;
+    min-width: max-content;
+  }
+
+  .settings-shell__nav-list :deep(.v-list-item) {
+    min-height: 48px;
+  }
+}
+</style>

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

@@ -11,19 +11,67 @@ const { workspaceUnavailable, workspaceUnavailableMessage } = useWorkspaceNotFou
     :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.
+  <section v-else class="workspace-admin-screen d-flex flex-column ga-4">
+    <header class="workspace-admin-screen__header">
+      <div>
+        <p class="text-overline text-medium-emphasis mb-1">Admin</p>
+        <h1 class="workspace-admin-screen__title">Workspace Admin</h1>
+        <p class="text-body-2 text-medium-emphasis mb-0">Manage members and workspace settings.</p>
+      </div>
+      <div class="workspace-admin-screen__actions">
+        <v-btn color="primary" variant="flat" to="./members">Members</v-btn>
+        <v-btn color="primary" variant="tonal" to="./workspace/settings">Settings</v-btn>
+      </div>
+    </header>
+
+    <v-sheet rounded="lg" border class="workspace-admin-screen__panel">
+      <h2 class="text-h6 mb-2">Admin tasks</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        Review workspace access, members, and operational settings from this surface.
       </p>
-    </v-card-text>
-  </v-card>
+    </v-sheet>
+  </section>
 </template>
+
+<style scoped>
+.workspace-admin-screen__header {
+  align-items: flex-start;
+  display: flex;
+  gap: 1rem;
+  justify-content: space-between;
+}
+
+.workspace-admin-screen__title {
+  font-size: clamp(1.5rem, 2.5vw, 2.25rem);
+  font-weight: 700;
+  letter-spacing: -0.03em;
+  line-height: 1.1;
+  margin: 0 0 0.4rem;
+}
+
+.workspace-admin-screen__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  justify-content: flex-end;
+}
+
+.workspace-admin-screen__panel {
+  padding: 1rem;
+}
+
+@media (max-width: 640px) {
+  .workspace-admin-screen__header {
+    flex-direction: column;
+  }
+
+  .workspace-admin-screen__actions {
+    width: 100%;
+  }
+
+  .workspace-admin-screen__actions :deep(.v-btn) {
+    min-height: 48px;
+    flex: 1 1 10rem;
+  }
+}
+</style>

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

@@ -11,17 +11,36 @@ const { workspaceUnavailable, workspaceUnavailableMessage } = useWorkspaceNotFou
     :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>
+  <section v-else class="workspace-home-screen d-flex flex-column ga-4">
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">Workspace</p>
+      <h1 class="workspace-home-screen__title">Workspace Home</h1>
+      <p class="text-body-2 text-medium-emphasis mb-0">The current workspace is active.</p>
+    </header>
+
+    <v-sheet rounded="lg" border class="workspace-home-screen__panel">
+      <h2 class="text-h6 mb-2">No workspace activity yet</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        Activity from workspace workflows will appear here.
+      </p>
+    </v-sheet>
+  </section>
 </template>
+
+<style scoped>
+.workspace-home-screen__title {
+  font-size: clamp(1.5rem, 2.5vw, 2.25rem);
+  font-weight: 700;
+  letter-spacing: -0.03em;
+  line-height: 1.1;
+  margin: 0 0 0.4rem;
+}
+
+.workspace-home-screen__panel {
+  margin-inline: auto;
+  max-width: 34rem;
+  padding: 2rem 1.25rem;
+  text-align: center;
+  width: 100%;
+}
+</style>

package/test/exportsContract.test.js

@@ -16,6 +16,7 @@ test("workspaces-web exports are explicit and aligned with production usage", ()
     requiredExports: [
       "./client",
       "./client/components/AccountSettingsInvitesSection",
+      "./client/components/WorkspaceSettingsClientElement",
       "./client/providers/WorkspacesWebClientProvider",
       "./client/composables/useWorkspaceRouteContext"
     ]

package/test/settingsPlacementContract.test.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import test from "node:test";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
+import { assertGeneratedUiSourceContract } from "@jskit-ai/kernel/shared/support/generatedUiContract";
 import descriptor from "../package.descriptor.mjs";
 
 const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
@@ -56,8 +57,25 @@ test("workspaces-web admin settings template exposes surface-derived settings ou
     "utf8"
   );
 
+  assertGeneratedUiSourceContract(source, {
+    forbidCardShell: true,
+    sourceName: "admin/workspace/settings.vue",
+    requiredPatterns: [
+      {
+        id: "admin-settings-outlet",
+        pattern: /target="admin-settings:primary-menu"/,
+        message: "Admin settings shell needs the semantic settings outlet host."
+      },
+      {
+        id: "admin-settings-router-view",
+        pattern: /<RouterView \/>/,
+        message: "Admin settings shell needs to host child settings routes."
+      }
+    ]
+  });
   assert.match(source, /target="admin-settings:primary-menu"/);
   assert.doesNotMatch(source, /default-link-component-token/);
+  assert.doesNotMatch(source, /<v-card\b/);
   assert.match(source, /<RouterView \/>/);
 });
 
@@ -80,6 +98,38 @@ test("workspaces-web installs an app-owned account invites section wrapper", asy
   });
 });
 
+test("workspaces-web settings components use direct panels instead of card scaffolds", async () => {
+  for (const relativePath of [
+    path.join("templates", "src", "components", "WorkspaceNotFoundCard.vue"),
+    path.join("src", "client", "components", "WorkspaceProfileClientElement.vue"),
+    path.join("src", "client", "components", "WorkspaceSettingsFieldsClientElement.vue"),
+    path.join("src", "client", "components", "WorkspacesClientElement.vue"),
+    path.join("src", "client", "components", "AccountSettingsInvitesSection.vue")
+  ]) {
+    const source = await readFile(path.join(PACKAGE_DIR, relativePath), "utf8");
+
+    assertGeneratedUiSourceContract(source, {
+      forbidCardShell: true,
+      sourceName: relativePath
+    });
+    assert.doesNotMatch(source, /<v-card\b|v-card-title|v-card-subtitle/);
+  }
+});
+
+test("workspaces-web resource load states expose local retry actions", async () => {
+  const expectations = new Map([
+    ["src/client/components/WorkspaceProfileClientElement.vue", /addEdit\.canRetryLoad[\s\S]*@click="addEdit\.refresh"/],
+    ["src/client/components/WorkspaceSettingsFieldsClientElement.vue", /addEdit\.canRetryLoad[\s\S]*@click="addEdit\.refresh"/],
+    ["src/client/components/WorkspacesClientElement.vue", /bootstrapLoadError[\s\S]*@click="refreshBootstrap"/],
+    ["src/client/components/WorkspaceMembersClientElement.vue", /canRetryLoad[\s\S]*@click="refreshLoad"/]
+  ]);
+
+  for (const [relativePath, pattern] of expectations) {
+    const source = await readFile(path.join(PACKAGE_DIR, relativePath), "utf8");
+    assert.match(source, pattern, `${relativePath} must expose a local retry action for load errors.`);
+  }
+});
+
 test("workspaces-web installs an account invites cue scaffold that reads placement runtime state", async () => {
   const source = await readFile(
     path.join(PACKAGE_DIR, "templates", "packages", "main", "src", "client", "components", "AccountPendingInvitesCue.vue"),
@@ -99,14 +149,60 @@ test("workspaces-web installs an account invites cue scaffold that reads placeme
   });
 });
 
-test("workspaces-web admin settings index template is a simple developer-owned stub", async () => {
+test("workspaces-web admin settings index template renders real workspace settings controls", async () => {
   const source = await readFile(
     path.join(PACKAGE_DIR, "templates", "src", "pages", "admin", "workspace", "settings", "index.vue"),
     "utf8"
   );
 
-  assert.match(source, /definePage/);
-  assert.match(source, /your_child_segment/);
+  assert.match(source, /@jskit-ai\/workspaces-web\/client\/components\/WorkspaceSettingsClientElement/);
+  assert.match(source, /<WorkspaceSettingsClientElement \/>/);
+  assert.doesNotMatch(source, /your_child_segment|To redirect this settings shell/);
+});
+
+test("workspaces-web starter surfaces avoid instructional placeholder copy", async () => {
+  const appSource = await readFile(
+    path.join(PACKAGE_DIR, "templates", "src", "surfaces", "app", "index.vue"),
+    "utf8"
+  );
+  const adminSource = await readFile(
+    path.join(PACKAGE_DIR, "templates", "src", "surfaces", "admin", "index.vue"),
+    "utf8"
+  );
+
+  assertGeneratedUiSourceContract(appSource, {
+    forbidCardShell: true,
+    sourceName: "workspaces app surface",
+    requiredPatterns: [
+      {
+        id: "workspace-app-empty-state",
+        pattern: /No workspace activity yet/,
+        message: "Workspace app surface needs a product-shaped empty state."
+      }
+    ]
+  });
+  assertGeneratedUiSourceContract(adminSource, {
+    forbidCardShell: true,
+    sourceName: "workspaces admin surface",
+    requiredPatterns: [
+      {
+        id: "workspace-admin-member-link",
+        pattern: /to="\.\/members"/,
+        message: "Workspace admin surface needs a direct members action."
+      },
+      {
+        id: "workspace-admin-settings-link",
+        pattern: /to="\.\/workspace\/settings"/,
+        message: "Workspace admin surface needs a direct settings action."
+      }
+    ]
+  });
+  assert.match(appSource, /No workspace activity yet/);
+  assert.match(adminSource, /Manage members and workspace settings/);
+  assert.match(adminSource, /to="\.\/members"/);
+  assert.match(adminSource, /to="\.\/workspace\/settings"/);
+  assert.doesNotMatch(appSource, /Replace this page|Primary in-workspace surface/);
+  assert.doesNotMatch(adminSource, /Use this area|Privileged workspace workflows/);
 });
 
 test("workspaces-web descriptor metadata advertises admin settings outlets", () => {