@jskit-ai/agent-docs 0.1.131 → 0.1.133

package/patterns/shell-foundation/example/src/pages/home/settings.vue

@@ -0,0 +1,109 @@
+<script setup>
+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">
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">Settings</p>
+      <h1 class="settings-shell__title">Home settings</h1>
+      <p class="text-body-2 text-medium-emphasis mb-0">Configure shell behavior for this surface.</p>
+    </header>
+
+    <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-title-size: 1.85rem;
+  --settings-panel-padding: 1rem;
+}
+
+.settings-shell__title {
+  font-size: var(--settings-title-size);
+  font-weight: 650;
+  letter-spacing: 0;
+  line-height: 1.15;
+  margin: 0 0 0.35rem;
+}
+
+.settings-shell__panel {
+  overflow: hidden;
+}
+
+.settings-shell__body {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: minmax(12rem, 16rem) minmax(0, 1fr);
+  padding: var(--settings-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 {
+    --settings-title-size: 1.35rem;
+  }
+
+  .settings-shell__body {
+    grid-template-columns: 1fr;
+  }
+
+  .settings-shell__nav :deep(.v-list) {
+    display: flex;
+    gap: 0.25rem;
+    overflow-x: auto;
+    scrollbar-width: thin;
+  }
+
+  .settings-shell__nav :deep(.v-list-item) {
+    flex: 0 0 auto;
+    min-height: 48px;
+  }
+
+  .settings-shell__content {
+    border-left: 0;
+    padding-left: 0;
+  }
+}
+</style>

package/patterns/shell-foundation/example/src/pages/home.vue

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

package/patterns/shell-foundation/example/src/placement.js

@@ -0,0 +1,56 @@
+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();
+}
+
+addPlacement({
+  id: "shell-web.home.menu.home",
+  target: "shell.primary-nav",
+  kind: "link",
+  surfaces: ["home"],
+  order: 50,
+  props: {
+    label: "Home",
+    surface: "home",
+    scopedSuffix: "/",
+    unscopedSuffix: "/",
+    exact: true
+  }
+});
+
+addPlacement({
+  id: "shell-web.home.menu.settings",
+  target: "shell.primary-nav",
+  kind: "link",
+  surfaces: ["home"],
+  order: 100,
+  props: {
+    label: "Settings",
+    surface: "home",
+    scopedSuffix: "/settings",
+    unscopedSuffix: "/settings"
+  }
+});
+
+addPlacement({
+  id: "shell-web.home.settings.general",
+  target: "page.section-nav",
+  owner: "home-settings",
+  kind: "link",
+  surfaces: ["home"],
+  order: 100,
+  props: {
+    label: "General",
+    surface: "home",
+    scopedSuffix: "/settings/general",
+    unscopedSuffix: "/settings/general"
+  }
+});

package/patterns/shell-foundation/example/src/placementTopology.js

@@ -0,0 +1,149 @@
+const placements = [];
+
+function addPlacementTopology(value = {}) {
+  placements.push(value);
+}
+
+export { addPlacementTopology };
+export default { placements };
+
+const menuLinkRenderers = Object.freeze({
+  link: "local.main.ui.surface-aware-menu-link-item"
+});
+
+const bottomNavLinkRenderers = Object.freeze({
+  link: "local.main.ui.tab-link-item"
+});
+
+addPlacementTopology({
+  id: "shell.primary-nav",
+  description: "Primary top-level navigation for the current surface.",
+  surfaces: ["*"],
+  default: true,
+  variants: {
+    compact: {
+      outlet: "shell-layout:primary-bottom-nav",
+      renderers: bottomNavLinkRenderers
+    },
+    medium: {
+      outlet: "shell-layout:primary-menu",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "shell-layout:primary-menu",
+      renderers: menuLinkRenderers
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.secondary-nav",
+  description: "Secondary navigation for the current surface.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:secondary-menu",
+      renderers: menuLinkRenderers
+    },
+    medium: {
+      outlet: "shell-layout:secondary-menu",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "shell-layout:secondary-menu",
+      renderers: menuLinkRenderers
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.identity",
+  description: "Current surface identity and switcher controls.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:top-left"
+    },
+    medium: {
+      outlet: "shell-layout:top-left"
+    },
+    expanded: {
+      outlet: "shell-layout:top-left"
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.status",
+  description: "Surface status, connection, and utility indicators.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:top-right"
+    },
+    medium: {
+      outlet: "shell-layout:top-right"
+    },
+    expanded: {
+      outlet: "shell-layout:top-right"
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.global-actions",
+  description: "Global surface actions that should stay outside primary navigation.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:top-right",
+      renderers: menuLinkRenderers
+    },
+    medium: {
+      outlet: "shell-layout:top-right",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "shell-layout:top-right",
+      renderers: menuLinkRenderers
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "page.supporting-content",
+  description: "Supporting page content that opens as a bottom sheet on compact layouts and a side panel on wider layouts.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:supporting-bottom-sheet"
+    },
+    medium: {
+      outlet: "shell-layout:supporting-side-panel"
+    },
+    expanded: {
+      outlet: "shell-layout:supporting-side-panel"
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "page.section-nav",
+  owner: "home-settings",
+  description: "Navigation between child pages in the home settings section.",
+  surfaces: ["home"],
+  variants: {
+    compact: {
+      outlet: "home-settings:primary-menu",
+      renderers: menuLinkRenderers
+    },
+    medium: {
+      outlet: "home-settings:primary-menu",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "home-settings:primary-menu",
+      renderers: menuLinkRenderers
+    }
+  }
+});

package/patterns/shell-foundation/example/src/views/NotFound.vue

@@ -0,0 +1,13 @@
+<script setup>
+const title = "Not Found";
+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>
+</template>

package/patterns/shell-foundation/example/tests/client/smoke.vitest.js

@@ -0,0 +1,7 @@
+import { describe, expect, it } from "vitest";
+
+describe("reading-room client smoke", () => {
+  it("runs vitest in reading-room", () => {
+    expect(true).toBe(true);
+  });
+});

package/patterns/shell-foundation/example/tests/e2e/adaptive-shell.spec.ts

@@ -0,0 +1,10 @@
+import { expect, test } from "@playwright/test";
+import { DEFAULT_VIEWPORTS, runAdaptiveShellSmokeCase } from "@jskit-ai/shell-web/test/adaptiveShellSmoke";
+
+test.describe("adaptive shell smoke", () => {
+  for (const viewport of DEFAULT_VIEWPORTS) {
+    test(`${viewport.name} layout has reachable navigation and no horizontal overflow`, async ({ page }) => {
+      await runAdaptiveShellSmokeCase({ page, expect, viewport });
+    });
+  }
+});

package/patterns/shell-foundation/example/tests/e2e/base-shell.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "@playwright/test";
+
+const VIEWPORTS = Object.freeze([
+  Object.freeze({ name: "compact", width: 390, height: 844 }),
+  Object.freeze({ name: "medium", width: 768, height: 1024 }),
+  Object.freeze({ name: "expanded", width: 1280, height: 900 })
+]);
+
+test.describe("application responsive smoke", () => {
+  for (const viewport of VIEWPORTS) {
+    test(`${viewport.name} home route renders without horizontal overflow`, async ({ page }) => {
+      await page.setViewportSize(viewport);
+      await page.goto("/home");
+      await expect(page.getByRole("heading", { name: "Ready" })).toBeVisible();
+
+      const dimensions = await page.evaluate(() => ({
+        clientWidth: document.documentElement.clientWidth,
+        scrollWidth: document.documentElement.scrollWidth
+      }));
+      expect(dimensions.scrollWidth).toBeLessThanOrEqual(dimensions.clientWidth + 1);
+    });
+  }
+});

package/patterns/shell-foundation/example/tests/server/smoke.test.js

@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createServer } from "../../server.js";
+
+test("GET /api/health returns built-in health response", async () => {
+  const app = await createServer();
+  const response = await app.inject({
+    method: "GET",
+    url: "/api/health"
+  });
+
+  assert.equal(response.statusCode, 200);
+  assert.equal(response.json().ok, true);
+
+  await app.close();
+});

package/patterns/shell-foundation/example/vite.config.mjs

@@ -0,0 +1,81 @@
+import { fileURLToPath, URL } from "node:url";
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import vuetify from "vite-plugin-vuetify";
+import VueRouter from "vue-router/vite";
+import { createJskitClientBootstrapPlugin } from "@jskit-ai/kernel/client/vite";
+
+const configuredDevPort = Number.parseInt(String(process.env.VITE_DEV_PORT || "").trim(), 10);
+const devPort = Number.isInteger(configuredDevPort) && configuredDevPort > 0 ? configuredDevPort : 5173;
+const apiProxyTarget = String(process.env.VITE_API_PROXY_TARGET || "").trim() || "http://localhost:3000";
+const clientEntry = (() => {
+  const normalized = String(process.env.VITE_CLIENT_ENTRY || "").trim();
+  if (!normalized) {
+    return "/src/main.js";
+  }
+  if (normalized.startsWith("/")) {
+    return normalized;
+  }
+  if (normalized.startsWith("src/")) {
+    return `/${normalized}`;
+  }
+  return `/src/${normalized}`;
+})();
+
+export default defineConfig({
+  resolve: {
+    preserveSymlinks: true,
+    alias: {
+      "@": fileURLToPath(new URL("./src", import.meta.url))
+    }
+  },
+  plugins: [
+    createJskitClientBootstrapPlugin({
+      proxyTarget: apiProxyTarget
+    }),
+    VueRouter({
+      routesFolder: "src/pages",
+      // Generated on the first Vite dev/build scan and intentionally gitignored.
+      dts: "src/typed-router.d.ts",
+      nestedChildren: false
+    }),
+    vue(),
+    vuetify({
+      autoImport: true
+    }),
+    {
+      name: "jskit-client-entry",
+      transformIndexHtml(source) {
+        return String(source || "")
+          .replace(/\/src\/%VITE_CLIENT_ENTRY%/g, clientEntry)
+          .replace(/\/src\/main\.js/g, clientEntry);
+      }
+    }
+  ],
+  test: {
+    include: ["tests/client/**/*.vitest.js"]
+  },
+  optimizeDeps: {
+    entries: [
+      "index.html",
+      "src/**/*.{js,ts,vue}"
+    ]
+  },
+  server: {
+    port: devPort,
+    warmup: {
+      clientFiles: [
+        "src/main.{js,ts}",
+        "src/router/**/*.{js,ts}",
+        "src/pages/**/*.{js,ts,vue}",
+        "src/components/**/*.{js,ts,vue}"
+      ]
+    },
+    proxy: {
+      "/api": {
+        target: apiProxyTarget,
+        changeOrigin: true
+      }
+    }
+  }
+});

package/patterns/ui-contract.md

@@ -0,0 +1,56 @@
+# JSKIT UI contract
+
+Use this contract when creating or reviewing JSKIT shell, page, CRUD, settings,
+and action UI.
+
+## Product-quality defaults
+
+- Live pages contain product language, not framework instructions or placeholder
+  copy.
+- Layouts adapt at compact, medium, and expanded widths without horizontal
+  overflow.
+- Compact interactive targets are at least 48 CSS pixels.
+- Navigation uses semantic placements and explicit navigation roles.
+- Pages do not stack decorative cards inside structural cards.
+- Shared screens own repeated chrome; app pages own product fields and domain
+  sections.
+
+## Loading and feedback
+
+- Initial and structural loading uses shape-matching skeletons.
+- Never use circular progress, indeterminate spinners, or loading icons.
+- Pending buttons keep their position and use stable disabled labels.
+- Resource-load failures stay in the affected region with retry.
+- Command and mutation failures use the shared toast/snackbar feedback path;
+  they do not insert banners that push page content down.
+- Cached query/resource data and route state may already exist at component
+  creation. Prefer computed truth; when writable state is necessary, hydrate it
+  synchronously or with an immediate watcher.
+
+## Shared CRUD screens
+
+Use `CrudListScreen`, `CrudViewScreen`, and `CrudAddEditScreen` with their
+matching composables. Use the public filter, bulk-action, row-action, synthetic
+row, and detail-slot seams before replacing shared chrome.
+
+Filters derive query parameters through the shared screen runtime. Server-side
+filters use `createCrudListFilterContract()` so route/action validation, JSON
+REST search schema, and repository normalization remain one contract.
+
+## Shell and placements
+
+Keep placement identities semantic and surface-aware. `primary`, `secondary`,
+`utility`, `detail`, `workflow`, and `none` describe product navigation intent.
+`page.supporting-content` is a semantic secondary region: compact layouts expose
+it as a closed sheet and wider layouts as a closed side panel.
+
+## Verification
+
+- test skeleton, empty, loaded, local error, retry, and mutation feedback states
+- navigate away and back with warm query cache, including browser back/forward
+- exercise compact, medium, and expanded viewports
+- verify accessible names, keyboard operation, target size, and no overflow
+- assert that no spinner or layout-shifting transient error banner appears
+
+Framework source contracts and package tests enforce the reusable parts of this
+policy. Application browser tests prove product-specific behavior.

package/patterns/ui-testing.md

@@ -10,11 +10,13 @@ Use when:
 Rules:
 
 - Any chunk that adds or changes user-facing UI must include a Playwright flow that exercises the changed behavior before the chunk is done.
-- Generator or package template UI changes must be checked at compact phone, tablet-ish medium, and expanded desktop widths.
-- For generated UI, check horizontal overflow, clipped or invisible text, duplicate navigation, and broken route placement at every standard viewport. On compact screens, also check generated-screen tap targets under 48 px; medium and expanded layouts may use their documented denser controls.
+- Pattern and framework UI changes must be checked at compact phone, tablet-ish medium, and expanded desktop widths.
+- Check horizontal overflow, clipped or invisible text, duplicate navigation, and broken route placement at every standard viewport. On compact screens, also check screen tap targets under 48 px; medium and expanded layouts may use their documented denser controls.
 - Apps with `shell-web` installed should start from `tests/e2e/adaptive-shell.spec.ts` and extend it with feature-specific assertions.
 - The package helper reads the shell's rendered `data-layout` contract, waits for drawer transitions without fixed sleeps, verifies compact Escape/outside dismissal, checks content-aware drawer fit, and measures rail icon centring against the configured width. Do not replace it with viewport-name assumptions or immediate animation-time geometry reads.
-- Generated `playwright.config.mjs` delegates to `@jskit-ai/jskit-cli/test/playwright`. Do not copy base-URL, web-server, or storage-state logic into app tests.
+- Start from the application-foundation Playwright configuration and keep it
+  app-owned. Do not duplicate base-URL, web-server, or storage-state logic in
+  individual tests.
 - Use relative paths such as `page.goto("/home")`. The shared config owns the browser base URL.
 - A managed runner supplies `PLAYWRIGHT_BASE_URL`. When it is set, JSKIT does not start another app server.
 - Vibe64 supplies an authenticated context through `VIBE64_PLAYWRIGHT_STORAGE_STATE`. Treat that file as a temporary secret: do not commit it, print it, or retain it after the run.
@@ -22,15 +24,14 @@ Rules:
 
 ## Preserve baseline tests
 
-Generated baseline tests are app-owned and customizable. Adapt infrastructure
+Foundation-pattern baseline tests are app-owned and customizable. Adapt infrastructure
 tests in place when routes or behavior change so the baseline coverage remains
 truthful.
 
 When the starter product route is replaced, update the scaffold smoke test to
 visit and assert the new canonical route. Do not delete baseline browser
 coverage such as `tests/e2e/base-shell.spec.ts` or
-`tests/e2e/adaptive-shell.spec.ts`. JSKIT Doctor must continue to flag a
-managed test that is missing.
+`tests/e2e/adaptive-shell.spec.ts`.
 
 ## Direct local authentication
 
@@ -78,7 +79,7 @@ VIBE64_PLAYWRIGHT_STORAGE_STATE=/secure/temp/playwright-state.json \
 playwright test tests/e2e/contacts.spec.ts
 ```
 
-The generated config applies that state to Playwright contexts and omits its local `webServer`. Tests then navigate with relative paths and begin with the runner-provided identity already authenticated.
+The app-owned config applies that state to Playwright contexts and omits its local `webServer`. Tests then navigate with relative paths and begin with the runner-provided identity already authenticated.
 
 Do not call `loginAsExistingUser()` against a managed preview. It is deliberately localhost-only. An ordinary request to `/api/dev-auth/login-as` without the private exchange header must return `403`.
 
@@ -90,11 +91,8 @@ Run the focused Playwright command directly:
 npx playwright test tests/e2e/contacts.spec.ts -g filters
 ```
 
-For local pre-merge review, follow the focused run with:
-
-```bash
-npx jskit doctor --against origin/main
-```
+For local pre-merge review, follow the focused run with the application's
+ordinary lint, package, build, and test scripts.
 
 Do not mark the chunk done if: