@jskit-ai/agent-docs 0.1.274 → 0.1.276

package/skills/jskit/references/patterns/app/shell-foundation/example/src/pages/home/settings/general/index.vue

@@ -2,6 +2,15 @@
 import { computed } from "vue";
 import { useShellLayoutState } from "@jskit-ai/shell-web/client/composables/useShellLayoutState";
 
+definePage({
+  meta: {
+    jskit: {
+      title: "General",
+      parent: "/settings"
+    }
+  }
+});
+
 const { drawerDefaultOpen, setDrawerDefaultOpen } = useShellLayoutState();
 
 const drawerDefaultOpenModel = computed({
@@ -15,23 +24,19 @@ const drawerDefaultOpenModel = computed({
 </script>
 
 <template>
-  <section class="settings-general-screen d-flex flex-column ga-4">
-    <p class="text-body-2 text-medium-emphasis mb-0">
-      On wider screens, collapsed navigation remains available as a rail. Phone layouts close the drawer and keep primary navigation in the bottom bar.
-    </p>
-
-    <v-switch
-      v-model="drawerDefaultOpenModel"
-      color="primary"
-      inset
-      hide-details="auto"
-      label="Start with expanded navigation on wider screens"
-    />
-  </section>
+  <v-card>
+    <v-list lines="three">
+      <v-list-item
+        title="Start with expanded navigation on wider screens"
+        subtitle="On wider screens, collapsed navigation remains available as a rail. Phone layouts close the drawer and keep primary navigation in the bottom bar."
+      >
+        <template #append>
+          <v-switch
+            v-model="drawerDefaultOpenModel"
+            aria-label="Start with expanded navigation on wider screens"
+          />
+        </template>
+      </v-list-item>
+    </v-list>
+  </v-card>
 </template>
-
-<style scoped>
-.settings-general-screen :deep(.v-switch) {
-  min-height: 48px;
-}
-</style>

package/skills/jskit/references/patterns/app/shell-foundation/example/src/pages/home/settings.vue

@@ -1,90 +1,33 @@
 <script setup>
+import { computed } from "vue";
+import { RouterView, useRoute } from "vue-router";
+import ShellListDetail from "@jskit-ai/shell-web/client/components/ShellListDetail";
 import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
-import { RouterView } from "vue-router";
-</script>
-
-<template>
-  <section class="settings-shell d-flex flex-column ga-4">
-    <v-sheet rounded="lg" border class="settings-shell__panel">
-      <div class="settings-shell__body">
-        <nav class="settings-shell__nav" aria-label="Home settings sections">
-          <v-list nav density="compact" rounded="lg">
-            <ShellOutlet target="home-settings:primary-menu" />
-          </v-list>
-        </nav>
-
-        <main class="settings-shell__content">
-          <RouterView />
-        </main>
-      </div>
-    </v-sheet>
-  </section>
-</template>
-
-<style scoped>
-.settings-shell {
-  --settings-shell-panel-padding: 1rem;
-}
-
-.settings-shell__panel {
-  overflow: hidden;
-}
-
-.settings-shell__body {
-  display: grid;
-  gap: 1rem;
-  grid-template-columns: minmax(12rem, 16rem) minmax(0, 1fr);
-  padding: var(--settings-shell-panel-padding);
-}
-
-.settings-shell__content {
-  border-left: 1px solid rgba(var(--v-theme-on-surface), 0.18);
-  min-width: 0;
-  padding-left: 1rem;
-}
-
-.settings-shell__nav :deep(.v-list) {
-  padding: 0.35rem;
-}
-
-.settings-shell__nav :deep(.v-list-item) {
-  min-height: 48px;
-  padding-inline: 0.6rem 0.7rem;
-}
 
-.settings-shell__nav :deep(.v-list-item__prepend) {
-  margin-inline-end: 0;
-}
-
-.settings-shell__nav :deep(.v-list-item__spacer) {
-  min-width: 0.5rem;
-  width: 0.5rem;
-}
-
-.settings-shell__nav :deep(.v-list-item-title) {
-  line-height: 1.2;
-}
-
-@media (max-width: 960px) {
-  .settings-shell__body {
-    grid-template-columns: 1fr;
-  }
-
-  .settings-shell__nav :deep(.v-list) {
-    display: flex;
-    gap: 0.25rem;
-    overflow-x: auto;
-    scrollbar-width: thin;
+definePage({
+  meta: {
+    jskit: {
+      title: "Settings"
+    }
   }
+});
 
-  .settings-shell__nav :deep(.v-list-item) {
-    flex: 0 0 auto;
-    min-height: 48px;
-  }
+const route = useRoute();
+// The section list shows beside the open section on wide windows, and on its own at /home/settings.
+const detailOpen = computed(() => !/\/settings\/?$/u.test(route.path));
+</script>
 
-  .settings-shell__content {
-    border-left: 0;
-    padding-left: 0;
-  }
-}
-</style>
+<template>
+  <ShellListDetail :detail-open="detailOpen">
+    <template #list>
+      <nav aria-label="Home settings sections">
+        <v-list nav>
+          <ShellOutlet target="home-settings:primary-menu" />
+        </v-list>
+      </nav>
+    </template>
+    <template #detail>
+      <RouterView />
+    </template>
+  </ShellListDetail>
+</template>

package/skills/jskit/references/patterns/app/shell-foundation/example/src/theme/index.js

@@ -0,0 +1,9 @@
+// The app's only theme facts. Material 3's light and dark colour schemes are generated from this one seed colour and
+// follow the device's setting: change the seed to rebrand. A colour the app really owns goes in `colors` by camelCase
+// name (it gets its own container roles, harmonized to the seed), and an icon of its own goes in `icons` as
+// `{ name: "<24x24 SVG path>" }`, used as `$name`.
+export const theme = {
+  seed: "#6750A4",
+  colors: {},
+  icons: {}
+};

package/skills/jskit/references/patterns/app/shell-foundation/example/src/views/NotFound.vue

@@ -1,13 +1,15 @@
 <script setup>
-const title = "Not Found";
+import ShellLayout from "@/components/ShellLayout.vue";
+
 const message = "The page you requested does not exist.";
 </script>
 
 <template>
-  <v-container class="fill-height d-flex align-center justify-center">
-    <v-card class="pa-6 text-center" max-width="560" rounded="lg">
-      <v-card-title class="text-h4">{{ title }}</v-card-title>
-      <v-card-text class="text-medium-emphasis">{{ message }}</v-card-text>
-    </v-card>
-  </v-container>
+  <!-- The shell's top app bar carries the title, and its navigation leads back into the app. -->
+  <ShellLayout title="Not Found" subtitle="">
+    <section class="d-flex flex-column align-center text-center on-surface-variant py-16">
+      <v-icon icon="$searchOff" size="48" />
+      <p class="text-body-large mt-4 mb-0">{{ message }}</p>
+    </section>
+  </ShellLayout>
 </template>

package/skills/jskit/references/patterns/assistant/assistant-surface/example/src/placement.js

@@ -11,7 +11,7 @@ addPlacement({
   order: 140,
   props: {
     label: "Assistant",
-    icon: "mdi-creation-outline",
+    icon: "$smartToy",
     surface: "admin",
     scopedSuffix: "/assistant",
     unscopedSuffix: "/assistant"

package/skills/jskit/references/patterns/auth/accounts-hub/example/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/database-runtime-mysql": "0.1.256",
-    "@jskit-ai/oidc-issuer-core": "0.1.16"
+    "@jskit-ai/database-runtime-mysql": "0.1.257",
+    "@jskit-ai/oidc-issuer-core": "0.1.17"
   }
 }

package/skills/jskit/references/patterns/auth/oidc-sign-in/example/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/auth-provider-oidc-core": "0.2.14",
-    "@jskit-ai/auth-web": "0.2.12"
+    "@jskit-ai/auth-provider-oidc-core": "0.2.15",
+    "@jskit-ai/auth-web": "0.2.13"
   }
 }

package/skills/jskit/references/patterns/auth/supabase-auth/example/package.json

@@ -2,6 +2,6 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/auth-provider-supabase-core": "0.2.11"
+    "@jskit-ai/auth-provider-supabase-core": "0.2.12"
   }
 }

package/skills/jskit/references/patterns/connectors/calendar-cli/example/package.json

@@ -7,10 +7,10 @@
     "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
   },
   "dependencies": {
-    "@jskit-ai/connectors-core": "0.2.10",
-    "@jskit-ai/connector-google-calendar": "0.2.10",
-    "@jskit-ai/database-runtime": "0.1.258",
-    "@jskit-ai/database-runtime-mysql": "0.1.256",
+    "@jskit-ai/connectors-core": "0.2.11",
+    "@jskit-ai/connector-google-calendar": "0.2.11",
+    "@jskit-ai/database-runtime": "0.1.259",
+    "@jskit-ai/database-runtime-mysql": "0.1.257",
     "knex": "^3.1.0"
   }
 }

package/skills/jskit/references/patterns/console/console-surface/PATTERN.md

@@ -39,8 +39,10 @@ placement, and topology APIs for application composition.
 
 ## Example files
 
-`example/` contains concrete console root, landing, and settings routes. Adapt
-them together with the surface policy and placement examples described here.
+`example/` contains concrete console root, landing, and settings routes, and
+`src/placement.js` declares Settings as the console's main-navigation
+destination, so it starts a fresh trail and its sections' Up returns to it.
+Adapt them together with the surface policy described here.
 
 ## Variation points
 

package/skills/jskit/references/patterns/console/console-surface/example/src/pages/console/index.vue

@@ -1,43 +1,13 @@
 <template>
-  <section class="console-home-screen d-flex flex-column ga-4">
-    <div class="console-home-screen__actions">
-      <v-btn color="primary" variant="flat" to="/home">Back to home</v-btn>
-    </div>
-
-    <v-sheet rounded="lg" border class="console-home-screen__panel">
-      <div class="console-home-screen__status-row">
-        <v-chip color="secondary" variant="tonal" label>Route: /console</v-chip>
-        <v-chip color="info" variant="tonal" label>Surface status: enabled</v-chip>
-      </div>
-      <p class="text-body-2 text-medium-emphasis mb-0">
-        Use this surface for operator actions and technical insights that should stay out of the end-user app.
-      </p>
-    </v-sheet>
+  <section class="d-flex flex-column ga-4">
+    <v-card>
+      <v-list lines="two">
+        <v-list-item title="/console" subtitle="Route" />
+        <v-list-item title="Enabled" subtitle="Surface status" />
+      </v-list>
+    </v-card>
+    <p class="text-body-medium on-surface-variant mb-0">
+      Use this surface for operator actions and technical insights that should stay out of the end-user app.
+    </p>
   </section>
 </template>
-
-<style scoped>
-.console-home-screen__actions {
-  display: flex;
-  justify-content: flex-end;
-}
-
-.console-home-screen__panel {
-  display: grid;
-  gap: 1rem;
-  padding: 1rem;
-}
-
-.console-home-screen__status-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 0.5rem;
-}
-
-@media (max-width: 640px) {
-  .console-home-screen__actions :deep(.v-btn) {
-    min-height: 48px;
-    width: 100%;
-  }
-}
-</style>

package/skills/jskit/references/patterns/console/console-surface/example/src/pages/console/settings/index.vue

@@ -1,16 +1,8 @@
 <template>
-  <section class="console-settings-empty">
-    <p class="text-body-2 text-medium-emphasis mb-0">
+  <section class="on-surface-variant text-center py-12">
+    <v-icon icon="$settings" size="48" />
+    <p class="text-body-large mt-4 mb-0">
       Console settings sections will appear here when installed.
     </p>
   </section>
 </template>
-
-<style scoped>
-.console-settings-empty {
-  margin-inline: auto;
-  max-width: 34rem;
-  padding: 2rem 1.25rem;
-  text-align: center;
-}
-</style>

package/skills/jskit/references/patterns/console/console-surface/example/src/pages/console/settings.vue

@@ -1,81 +1,33 @@
 <script setup>
+import { computed } from "vue";
+import { RouterView, useRoute } from "vue-router";
+import ShellListDetail from "@jskit-ai/shell-web/client/components/ShellListDetail";
 import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
-import { RouterView } from "vue-router";
+
+definePage({
+  meta: {
+    jskit: {
+      title: "Settings"
+    }
+  }
+});
+
+const route = useRoute();
+// The section list shows beside the open section on wide windows, and on its own at the settings landing.
+const detailOpen = computed(() => !/\/settings\/?$/u.test(route.path));
 </script>
 
 <template>
-  <section class="settings-shell d-flex flex-column ga-4">
-    <v-sheet rounded="lg" border class="settings-shell__panel">
-      <nav class="settings-shell__nav" aria-label="Console settings sections">
-        <v-list nav density="compact" class="settings-shell__nav-list">
+  <ShellListDetail :detail-open="detailOpen">
+    <template #list>
+      <nav aria-label="Console settings sections">
+        <v-list nav>
           <ShellOutlet target="console-settings:primary-menu" />
         </v-list>
       </nav>
-      <main class="settings-shell__content">
-        <RouterView />
-      </main>
-    </v-sheet>
-  </section>
+    </template>
+    <template #detail>
+      <RouterView />
+    </template>
+  </ShellListDetail>
 </template>
-
-<style scoped>
-.settings-shell__panel {
-  display: grid;
-  gap: 1rem;
-  grid-template-columns: minmax(12rem, 16rem) minmax(0, 1fr);
-  padding: 1rem;
-}
-
-.settings-shell__nav-list {
-  padding: 0.35rem;
-}
-
-.settings-shell__nav-list :deep(.v-list-item) {
-  min-height: 48px;
-  padding-inline: 0.6rem 0.7rem;
-}
-
-.settings-shell__nav-list :deep(.v-list-item__prepend) {
-  margin-inline-end: 0;
-}
-
-.settings-shell__nav-list :deep(.v-list-item__spacer) {
-  min-width: 0.5rem;
-  width: 0.5rem;
-}
-
-.settings-shell__nav-list :deep(.v-list-item-title) {
-  line-height: 1.2;
-}
-
-.settings-shell__content {
-  border-left: 1px solid rgba(var(--v-theme-on-surface), 0.18);
-  min-width: 0;
-  padding-left: 1rem;
-}
-
-@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.25rem;
-    min-width: max-content;
-  }
-
-  .settings-shell__nav-list :deep(.v-list-item) {
-    min-height: 48px;
-  }
-
-  .settings-shell__content {
-    border-left: 0;
-    padding-left: 0;
-  }
-}
-</style>

package/skills/jskit/references/patterns/console/console-surface/example/src/placement.js

@@ -0,0 +1,28 @@
+import { createPlacementRegistry } from "@jskit-ai/shell-web/client/placement";
+
+const registry = createPlacementRegistry();
+const { addPlacement } = registry;
+
+export { addPlacement };
+
+// Keep the default export near the top so module installers can append addPlacement(...)
+// blocks at the bottom of this file without changing the export section.
+export default function getPlacements() {
+  return registry.build();
+}
+
+// Settings is a main destination of the console: choosing it starts a fresh trail, and its sections' Up returns to
+// the settings list.
+addPlacement({
+  id: "console.web.menu.settings",
+  target: "shell.primary-nav",
+  kind: "link",
+  surfaces: ["console"],
+  order: 100,
+  props: {
+    label: "Settings",
+    surface: "console",
+    scopedSuffix: "/settings",
+    unscopedSuffix: "/settings"
+  }
+});

package/skills/jskit/references/patterns/crud/crud-screen-set/PATTERN.md

@@ -35,7 +35,20 @@ questionnaire.
 
 - Route pages stay thin and use `useCrudListScreen()`, `useCrudViewScreen()`,
   or `useCrudAddEditScreen()`.
+- Each route page declares its app bar title and its parent with
+  `definePage({ meta: { jskit: { title, parent } } })`. The list is a main
+  menu destination with a title only; the view and new pages name the list as
+  their parent, and the edit page names the view. The shell's Up arrow follows
+  the parent, so screens and pages add no Back links.
 - Route pages do not add a page header or standalone heading by default.
+- The shared screens put their actions in the top app bar: Refresh on the list,
+  Edit and the `actions` slot (such as `CrudDeleteAction`) on the view, and
+  Cancel and Save on a form. The list's create action is an extended FAB on
+  compact and medium windows and the app bar's primary button on wider ones.
+- Save, Cancel and a completed delete replace the form's or the deleted record's
+  history entry, so neither Up nor Back reopens it.
+- View fields are two-line list items with the value first:
+  `<v-list-item :title="record.author" subtitle="Author" />`.
 - Transport and validators come from the shared resource contract.
 - Initial visible loading uses structure-matching skeletons; pending buttons use
   stable disabled labels, never spinners.

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookEditPage.vue

@@ -7,6 +7,8 @@ import { bookResource } from "@local/books/shared";
 import BookFormFields from "./BookFormFields.vue";
 import { bookFormFields } from "./formFields.js";
 
+definePage({ meta: { jskit: { title: "Edit book", parent: "/books/:bookId" } } });
+
 const route = useRoute();
 const routeRecordId = computed(() => String(route.params.bookId || "").trim());
 

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookFormFields.vue

@@ -20,8 +20,6 @@ defineProps({
     <v-text-field
       v-model="title"
       label="Title"
-      variant="outlined"
-      density="comfortable"
       maxlength="255"
       :readonly="readonly"
       :error-messages="resolveFieldErrors('title')"
@@ -31,8 +29,6 @@ defineProps({
     <v-text-field
       v-model="author"
       label="Author"
-      variant="outlined"
-      density="comfortable"
       maxlength="255"
       :readonly="readonly"
       :error-messages="resolveFieldErrors('author')"
@@ -42,8 +38,6 @@ defineProps({
     <v-textarea
       v-model="notes"
       label="Notes"
-      variant="outlined"
-      density="comfortable"
       auto-grow
       :readonly="readonly"
       :error-messages="resolveFieldErrors('notes')"

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookListPage.vue

@@ -4,6 +4,9 @@ import { useCrudListScreen } from "@jskit-ai/http-web/client/composables/useCrud
 import { bookResource } from "@local/books/shared";
 import { listBulkActions, listFilters, listRowActions } from "./listExtensions.js";
 
+// A main menu destination: the app bar shows its title and no Up arrow.
+definePage({ meta: { jskit: { title: "Books" } } });
+
 const screen = useCrudListScreen({
   resource: bookResource,
   resourceNamespace: "books",
@@ -31,8 +34,8 @@ const screen = useCrudListScreen({
     <template #card-fields="{ record, formatListCardValue }">
       <dl class="d-grid ga-2 mb-0">
         <div>
-          <dt class="text-caption text-medium-emphasis">Author</dt>
-          <dd class="text-body-2 mb-0">{{ formatListCardValue(record.author) }}</dd>
+          <dt class="text-body-small on-surface-variant">Author</dt>
+          <dd class="text-body-medium ma-0">{{ formatListCardValue(record.author) }}</dd>
         </div>
       </dl>
     </template>

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookNewPage.vue

@@ -5,6 +5,8 @@ import { bookResource } from "@local/books/shared";
 import BookFormFields from "./BookFormFields.vue";
 import { bookFormFields } from "./formFields.js";
 
+definePage({ meta: { jskit: { title: "New book", parent: "/books" } } });
+
 const screen = useCrudAddEditScreen({
   mode: "new",
   saveLabel: "Save book",

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookViewPage.vue

@@ -5,6 +5,9 @@ import { useCrudDeleteAction } from "@jskit-ai/http-web/client/composables/useCr
 import { useCrudViewScreen } from "@jskit-ai/http-web/client/composables/useCrudViewScreen";
 import { bookResource } from "@local/books/shared";
 
+// Up returns to the page the book was opened from, or else to the list.
+definePage({ meta: { jskit: { title: "Book", parent: "/books" } } });
+
 const screen = useCrudViewScreen({
   resource: bookResource,
   resourceNamespace: "books",
@@ -29,21 +32,14 @@ const deleteAction = useCrudDeleteAction({
   <CrudViewScreen
     :screen="screen"
     resource-singular-title="Book"
-    resource-plural-title="Books"
   >
     <template #actions>
       <CrudDeleteAction :action="deleteAction" resource-singular-title="Book" />
     </template>
 
     <template #fields="{ view }">
-      <v-col cols="12" md="6">
-        <div class="text-caption text-medium-emphasis">Author</div>
-        <div class="text-body-1">{{ view.record?.author }}</div>
-      </v-col>
-      <v-col cols="12">
-        <div class="text-caption text-medium-emphasis">Notes</div>
-        <div class="text-body-1 text-pre-wrap">{{ view.record?.notes || "No notes" }}</div>
-      </v-col>
+      <v-list-item :title="view.record?.author" subtitle="Author" />
+      <v-list-item :title="view.record?.notes || 'No notes'" subtitle="Notes" />
     </template>
   </CrudViewScreen>
 </template>

package/skills/jskit/references/patterns/crud/json-api-resource-package/example/packages/books/package.json

@@ -9,8 +9,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.2.10",
-    "@jskit-ai/resource-crud-core": "0.1.200"
+    "@jskit-ai/crud-core": "0.2.11",
+    "@jskit-ai/resource-crud-core": "0.1.201"
   },
   "jskit": {
     "kind": "runtime",

package/skills/jskit/references/patterns/database/mysql-application/example/package.json

@@ -8,6 +8,6 @@
     "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-mysql": "0.1.256"
+    "@jskit-ai/database-runtime-mysql": "0.1.257"
   }
 }

package/skills/jskit/references/patterns/database/postgres-application/example/package.json

@@ -8,6 +8,6 @@
     "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-postgres": "0.1.255"
+    "@jskit-ai/database-runtime-postgres": "0.1.256"
   }
 }

package/skills/jskit/references/patterns/realtime/realtime-application/example/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/realtime": "0.2.13",
-    "@jskit-ai/shell-web": "0.2.10"
+    "@jskit-ai/realtime": "0.2.14",
+    "@jskit-ai/shell-web": "0.2.11"
   }
 }