@jskit-ai/agent-docs 0.1.279 → 0.1.281

package/patterns/minimal-foundation/example/package.json

@@ -24,7 +24,7 @@
     "build:home": "VITE_SURFACE=home vite build",
     "preview": "vite preview",
     "lint": "eslint .",
-    "test": "node --test --test-concurrency=1",
+    "test": "jskit test",
     "test:client": "vitest run tests/client",
     "test:e2e": "playwright test tests/e2e",
     "jskit:update": "npx --yes @jskit-ai/jskit-catalog@latest update",
@@ -34,8 +34,8 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.10",
-    "@jskit-ai/material-web": "0.1.2",
+    "@jskit-ai/kernel": "0.2.12",
+    "@jskit-ai/material-web": "0.1.3",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
@@ -44,13 +44,13 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.10",
+    "@jskit-ai/http-runtime": "0.2.12",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.31",
+    "@jskit-ai/config-eslint": "0.1.246",
+    "@jskit-ai/jskit-catalog": "0.2.33",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/minimal-foundation/example/playwright.config.mjs

@@ -1,32 +1,5 @@
 import { defineConfig } from "@playwright/test";
+import { browserTestConfig } from "@jskit-ai/jskit-catalog/browser-tests";
 
-const managedBaseUrl = String(process.env.PLAYWRIGHT_BASE_URL || "")
-  .trim()
-  .replace(/\/+$/u, "");
-const port = String(process.env.PLAYWRIGHT_PORT || "").trim() || "4173";
-const baseURL = managedBaseUrl || `http://127.0.0.1:${port}`;
-const storageState = String(process.env.PLAYWRIGHT_STORAGE_STATE || "").trim();
-
-export default defineConfig({
-  testDir: "./tests/e2e",
-  timeout: 60_000,
-  expect: {
-    timeout: 10_000
-  },
-  use: {
-    baseURL,
-    headless: true,
-    ...(storageState ? { storageState } : {})
-  },
-  ...(managedBaseUrl ? {} : {
-    webServer: {
-      command: "npm run develop",
-      env: {
-        PORT: port
-      },
-      url: `${baseURL}/api/health`,
-      reuseExistingServer: true,
-      timeout: 180_000
-    }
-  })
-});
+// Each Playwright worker gets its own server on the production build; with PLAYWRIGHT_BASE_URL, the managed target.
+export default defineConfig(browserTestConfig({ testDir: "./tests/e2e" }));

package/patterns/minimal-foundation/example/server.js

@@ -23,6 +23,10 @@ import { surfaceRuntime } from "./server/lib/surfaceRuntime.js";
 /** @typedef {import("@jskit-ai/kernel/server/types").RuntimeEnv} RuntimeEnv */
 
 const SPA_INDEX_FILE = "index.html";
+// Vite names each built file under assets/ after its content (`index-BxY3kz9a.js`), so a browser may keep one for good:
+// a new build references new names. index.html and unhashed files are revalidated on every load.
+const HASHED_ASSET = /^assets\/(?:.+\/)?[^/]+-[\w-]{8}\.[a-z0-9]+$/u;
+const HASHED_ASSET_CACHE = Object.freeze({ maxAge: 365 * 24 * 60 * 60 * 1000, immutable: true });
 const STATIC_GLOBAL_UI_PATHS = Object.freeze([
   "/assets",
   "/favicon.svg",
@@ -157,7 +161,9 @@ async function createServer({ runtimeEnv }) {
     if (hasFileExtension(pathname)) {
       const staticFilePath = toStaticFilePath(pathname);
       if (hasWebBuild && staticFilePath && canServeStaticFile(distRoot, staticFilePath)) {
-        return reply.sendFile(staticFilePath);
+        return HASHED_ASSET.test(staticFilePath)
+          ? reply.sendFile(staticFilePath, HASHED_ASSET_CACHE)
+          : reply.sendFile(staticFilePath);
       }
       return reply.code(404).send({
         message: `Route ${method}:${pathname} not found`,

package/patterns/minimal-foundation/example/src/main.js

@@ -1,10 +1,11 @@
+// Vuetify's styles first, so its stylesheet comes before any component chunk's.
+import "vuetify/styles";
+import "@jskit-ai/material-web/client/material.css";
 import { createApp } from "vue";
 import { createPinia } from "pinia";
 import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
 import { createRouter, createWebHistory } from "vue-router/auto";
 import { routes } from "vue-router/auto-routes";
-import "vuetify/styles";
-import "@jskit-ai/material-web/client/material.css";
 import { createVuetify } from "vuetify";
 import { createMaterialVuetifyOptions } from "@jskit-ai/material-web/client";
 import App from "./App.vue";

package/patterns/minimal-foundation/example/tests/e2e/startup.spec.ts

@@ -33,3 +33,16 @@ for (const width of [390, 768, 1280]) {
     await expect(page.locator("#startup-shell")).toHaveCount(0);
   });
 }
+
+test("built assets are kept for good and the page itself is revalidated", async ({ page }) => {
+  test.skip(Boolean(process.env.PLAYWRIGHT_BASE_URL), "A managed target's server and proxy set its own caching.");
+  const assets: string[] = [];
+  page.on("response", response => {
+    if (new URL(response.url()).pathname.startsWith("/assets/")) assets.push(response.headers()["cache-control"] ?? "");
+  });
+  const document = await page.goto("/home");
+  await page.waitForLoadState("load");
+  expect(document?.headers()["cache-control"] ?? "").not.toContain("immutable");
+  expect(assets.length).toBeGreaterThan(0);
+  expect(new Set(assets)).toEqual(new Set(["public, max-age=31536000, immutable"]));
+});

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

@@ -4,6 +4,7 @@ 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";
+import { testConcurrency } from "@jskit-ai/jskit-catalog/test-budget";
 
 const configuredDevPort = Number.parseInt(String(process.env.VITE_DEV_PORT || "").trim(), 10);
 const devPort = Number.isInteger(configuredDevPort) && configuredDevPort > 0 ? configuredDevPort : 5173;
@@ -52,7 +53,8 @@ export default defineConfig({
     }
   ],
   test: {
-    include: ["tests/client/**/*.vitest.js"]
+    include: ["tests/client/**/*.vitest.js"],
+    maxWorkers: testConcurrency()
   },
   optimizeDeps: {
     include: ["vuetify/components/**", "vuetify/directives/**"],

package/patterns/shell-foundation/PATTERN.md

@@ -118,7 +118,10 @@ Read these together before adapting the shell:
 
 ## Variation points
 
-Rename the example, replace the home content, add or remove settings routes,
+Rename the example (its name is spelt in `package.json`, `app.json` and
+`index.html`'s `<title>`, and, once the app adds sign-in, in the
+`auth/auth-surface` pattern's `src/components/AppBrand.vue`; rename them
+together), replace the home content, add or remove settings routes,
 and change placements through their public contracts. Use package-owned
 patterns for auth, users, databases, CRUD, realtime, and other capabilities.
 Do not preinstall capabilities solely because they appear in another app.

package/patterns/shell-foundation/example/AGENTS.md

@@ -29,11 +29,28 @@ Do not install an unrelated runtime package only to read documentation.
 Before adding or changing browser-test setup, read the browser verification
 guide at
 `https://mobily-enterprises.github.io/jskit-ai/guide/framework/ui-operations#browser-verification`.
-Routine tests reuse the isolated schema and prepare fixtures once per suite
-invocation. Keep `BROWSER_TEST_DB_NAME` distinct from disposable `TEST_DB_NAME`
-and prove that disposable cleanup preserves browser migrations. Require
-repeat-start regression proof; do not rebuild the database or production
-frontend for each focused browser check.
+`playwright.config.mjs` is `browserTestConfig()` from
+`@jskit-ai/jskit-catalog/browser-tests`: every Playwright worker gets its own
+server on the production build, its own port and, through the config's
+`prepare` module, its own copy of the browser database, restored from a schema
+snapshot and seeded. A local run never starts the development server; with
+`PLAYWRIGHT_BASE_URL`, the tests use that managed target as its host serves
+it. Keep `BROWSER_TEST_DB_NAME` distinct from disposable `TEST_DB_NAME`. The build and
+the snapshot are reused while their sources are unchanged; do not rebuild the
+database or production frontend for each focused browser check. Require
+repeat-start regression proof.
+
+Tests run in parallel within the machine's test budget: run node's test
+runner through `jskit test` (`npm test`), with `--databases` once the app has a
+database so each file running at once gets its own copy of `TEST_DB_NAME`,
+Playwright through `browserTestConfig()`, and take Vitest's `maxWorkers` from
+`testConcurrency()` of
+`@jskit-ai/jskit-catalog/test-budget`; never one file at a time or a fixed
+count. Isolate files that collide (their own port, temporary directory and
+database) instead of serialising them; a file that truly must run alone says
+why on its first line, `// jskit-test: alone - <reason>`. Plain `jskit check`
+fails anything else
+(`https://mobily-enterprises.github.io/jskit-ai/guide/framework/typed-features#test-files-run-in-parallel`).
 
 Keep verification output small. Run the relevant cases together, save complete
 stdout/stderr to local artifacts, and preserve the exit status. Report counts,

package/patterns/shell-foundation/example/package.json

@@ -24,7 +24,7 @@
     "build:home": "VITE_SURFACE=home vite build",
     "preview": "vite preview",
     "lint": "eslint .",
-    "test": "node --test --test-concurrency=1",
+    "test": "jskit test",
     "test:client": "vitest run tests/client",
     "test:e2e": "playwright test tests/e2e",
     "jskit:update": "npx --yes @jskit-ai/jskit-catalog@latest update",
@@ -34,8 +34,8 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.10",
-    "@jskit-ai/material-web": "0.1.2",
+    "@jskit-ai/kernel": "0.2.12",
+    "@jskit-ai/material-web": "0.1.3",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
@@ -44,14 +44,14 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.10",
-    "@jskit-ai/shell-web": "0.2.13",
+    "@jskit-ai/http-runtime": "0.2.12",
+    "@jskit-ai/shell-web": "0.2.15",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.245",
-    "@jskit-ai/jskit-catalog": "0.2.31",
+    "@jskit-ai/config-eslint": "0.1.246",
+    "@jskit-ai/jskit-catalog": "0.2.33",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/packages/main/package.json

@@ -9,7 +9,7 @@
   },
   "description": "App-local runtime composition and lightweight glue.",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.10"
+    "@jskit-ai/kernel": "0.2.12"
   },
   "jskit": {
     "kind": "runtime",

package/patterns/shell-foundation/example/packages/main/src/client/providers/MainClientProvider.js

@@ -1,5 +1,6 @@
 import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
 import MenuLinkItem from "/src/components/menus/MenuLinkItem.vue";
+import SectionTabLinkItem from "/src/components/menus/SectionTabLinkItem.vue";
 import SurfaceAwareMenuLinkItem from "/src/components/menus/SurfaceAwareMenuLinkItem.vue";
 import TabLinkItem from "/src/components/menus/TabLinkItem.vue";
 
@@ -13,6 +14,8 @@ const MainClientProvider = defineProvider({
     components.register("local.main.ui.menu-link-item", MenuLinkItem);
     components.register("local.main.ui.surface-aware-menu-link-item", SurfaceAwareMenuLinkItem);
     components.register("local.main.ui.tab-link-item", TabLinkItem);
+    // A page's section tabs (page.section-nav): Material 3 primary tabs, not navigation bar destinations.
+    components.register("local.main.ui.section-tab-link-item", SectionTabLinkItem);
   }
 });
 

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

@@ -1,32 +1,5 @@
 import { defineConfig } from "@playwright/test";
+import { browserTestConfig } from "@jskit-ai/jskit-catalog/browser-tests";
 
-const managedBaseUrl = String(process.env.PLAYWRIGHT_BASE_URL || "")
-  .trim()
-  .replace(/\/+$/u, "");
-const port = String(process.env.PLAYWRIGHT_PORT || "").trim() || "4173";
-const baseURL = managedBaseUrl || `http://127.0.0.1:${port}`;
-const storageState = String(process.env.PLAYWRIGHT_STORAGE_STATE || "").trim();
-
-export default defineConfig({
-  testDir: "./tests/e2e",
-  timeout: 60_000,
-  expect: {
-    timeout: 10_000
-  },
-  use: {
-    baseURL,
-    headless: true,
-    ...(storageState ? { storageState } : {})
-  },
-  ...(managedBaseUrl ? {} : {
-    webServer: {
-      command: "npm run develop",
-      env: {
-        PORT: port
-      },
-      url: `${baseURL}/api/health`,
-      reuseExistingServer: true,
-      timeout: 180_000
-    }
-  })
-});
+// Each Playwright worker gets its own server on the production build; with PLAYWRIGHT_BASE_URL, the managed target.
+export default defineConfig(browserTestConfig({ testDir: "./tests/e2e" }));

package/patterns/shell-foundation/example/server.js

@@ -23,6 +23,10 @@ import { surfaceRuntime } from "./server/lib/surfaceRuntime.js";
 /** @typedef {import("@jskit-ai/kernel/server/types").RuntimeEnv} RuntimeEnv */
 
 const SPA_INDEX_FILE = "index.html";
+// Vite names each built file under assets/ after its content (`index-BxY3kz9a.js`), so a browser may keep one for good:
+// a new build references new names. index.html and unhashed files are revalidated on every load.
+const HASHED_ASSET = /^assets\/(?:.+\/)?[^/]+-[\w-]{8}\.[a-z0-9]+$/u;
+const HASHED_ASSET_CACHE = Object.freeze({ maxAge: 365 * 24 * 60 * 60 * 1000, immutable: true });
 const STATIC_GLOBAL_UI_PATHS = Object.freeze([
   "/assets",
   "/favicon.svg",
@@ -157,7 +161,9 @@ async function createServer({ runtimeEnv }) {
     if (hasFileExtension(pathname)) {
       const staticFilePath = toStaticFilePath(pathname);
       if (hasWebBuild && staticFilePath && canServeStaticFile(distRoot, staticFilePath)) {
-        return reply.sendFile(staticFilePath);
+        return HASHED_ASSET.test(staticFilePath)
+          ? reply.sendFile(staticFilePath, HASHED_ASSET_CACHE)
+          : reply.sendFile(staticFilePath);
       }
       return reply.code(404).send({
         message: `Route ${method}:${pathname} not found`,

package/patterns/shell-foundation/example/src/components/menus/SectionTabLinkItem.vue

@@ -0,0 +1,42 @@
+<script setup>
+import ShellSectionTabLinkItem from "@jskit-ai/shell-web/client/components/ShellSectionTabLinkItem";
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ""
+  },
+  to: {
+    type: String,
+    default: ""
+  },
+  icon: {
+    type: String,
+    default: ""
+  },
+  surface: {
+    type: String,
+    default: ""
+  },
+  scopedSuffix: {
+    type: String,
+    default: "/"
+  },
+  unscopedSuffix: {
+    type: String,
+    default: "/"
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  },
+  exact: {
+    type: Boolean,
+    default: false
+  }
+});
+</script>
+
+<template>
+  <ShellSectionTabLinkItem v-bind="props" />
+</template>

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

@@ -1,10 +1,11 @@
+// Vuetify's styles first, so its stylesheet comes before any component chunk's.
+import "vuetify/styles";
+import "@jskit-ai/material-web/client/material.css";
 import { createApp } from "vue";
 import { createPinia } from "pinia";
 import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
 import { createRouter, createWebHistory } from "vue-router/auto";
 import { routes } from "vue-router/auto-routes";
-import "vuetify/styles";
-import "@jskit-ai/material-web/client/material.css";
 import { createVuetify } from "vuetify";
 import { createMaterialVuetifyOptions } from "@jskit-ai/material-web/client";
 import App from "./App.vue";

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

@@ -14,7 +14,7 @@ import { RouterView } from "vue-router";
 </script>
 
 <template>
-  <ShellLayout title="" subtitle="">
+  <ShellLayout>
     <RouterView />
   </ShellLayout>
 </template>

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

@@ -6,7 +6,7 @@ const message = "The page you requested does not exist.";
 
 <template>
   <!-- The shell's top app bar carries the title, and its navigation leads back into the app. -->
-  <ShellLayout title="Not Found" subtitle="">
+  <ShellLayout title="Not Found">
     <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>

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

@@ -33,3 +33,16 @@ for (const width of [390, 768, 1280]) {
     await expect(page.locator("#startup-shell")).toHaveCount(0);
   });
 }
+
+test("built assets are kept for good and the page itself is revalidated", async ({ page }) => {
+  test.skip(Boolean(process.env.PLAYWRIGHT_BASE_URL), "A managed target's server and proxy set its own caching.");
+  const assets: string[] = [];
+  page.on("response", response => {
+    if (new URL(response.url()).pathname.startsWith("/assets/")) assets.push(response.headers()["cache-control"] ?? "");
+  });
+  const document = await page.goto("/home");
+  await page.waitForLoadState("load");
+  expect(document?.headers()["cache-control"] ?? "").not.toContain("immutable");
+  expect(assets.length).toBeGreaterThan(0);
+  expect(new Set(assets)).toEqual(new Set(["public, max-age=31536000, immutable"]));
+});

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

@@ -4,6 +4,7 @@ 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";
+import { testConcurrency } from "@jskit-ai/jskit-catalog/test-budget";
 
 const configuredDevPort = Number.parseInt(String(process.env.VITE_DEV_PORT || "").trim(), 10);
 const devPort = Number.isInteger(configuredDevPort) && configuredDevPort > 0 ? configuredDevPort : 5173;
@@ -52,7 +53,8 @@ export default defineConfig({
     }
   ],
   test: {
-    include: ["tests/client/**/*.vitest.js"]
+    include: ["tests/client/**/*.vitest.js"],
+    maxWorkers: testConcurrency()
   },
   optimizeDeps: {
     include: ["vuetify/components/**", "vuetify/directives/**"],