@jskit-ai/agent-docs 0.1.149 → 0.1.150

package/skills/jskit/references/patterns/app/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/skills/jskit/references/patterns/app/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/skills/jskit/references/patterns/app/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/skills/jskit/references/patterns/app/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/skills/jskit/references/patterns/app/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/skills/jskit/references/patterns/app/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/skills/jskit/references/patterns/app/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/skills/jskit/references/patterns/app/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/skills/jskit/references/patterns/app/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/skills/jskit/references/patterns/app/shell-foundation/example/vite.config.mjs

@@ -0,0 +1,80 @@
+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: {
+    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/skills/jskit/references/patterns/assistant/assistant-surface/PATTERN.md

@@ -0,0 +1,77 @@
+---
+id: assistant/assistant-surface
+title: Assistant surface and settings
+summary: Configure an assistant runtime for one application surface and expose its chat and settings elements through ordinary pages and placements.
+keywords: ai, assistant, chat, config, environment, page, placement, settings, surface
+requires: @jskit-ai/assistant-runtime, @jskit-ai/shell-web
+---
+
+# Assistant surface and settings
+
+## Use when
+
+Use this pattern when an application should expose JSKIT's assistant runtime on
+an enabled surface and provide a settings page for that assistant.
+
+## Do not use when
+
+Do not use this pattern for an application that only needs a single
+server-to-model call, or when the product has no conversational surface. Do not
+copy the assistant runtime's repositories or transport into application code.
+
+## Product decisions
+
+Choose the runtime surface, settings surface, global or workspace configuration
+scope, page routes, placement roles, AI provider, model policy, and whether the
+assistant begins disabled until credentials are supplied. Never put an API key
+in source or a questionnaire transcript.
+
+## Invariants
+
+- Both configured surfaces exist and are enabled.
+- Workspace configuration is used only when both surfaces require a workspace.
+- Each runtime surface appears once in `assistantSurfaces` and
+  `assistantServer`.
+- The server config contains an environment prefix, never a credential value.
+- Runtime and settings pages use the public assistant elements.
+- Environment values are supplied through the application's normal secret
+  environment boundary.
+- No generator markers, setup receipts, or overwrite state remain.
+
+## Framework APIs
+
+Use `AssistantSurfaceClientElement` and `AssistantSettingsClientElement` from
+`@jskit-ai/assistant-runtime/client`. Install the runtime package through the
+normal package-capability path. Configure `assistantSurfaces` in public config
+and `assistantServer` in server config.
+
+## Example files
+
+`example/` contains concrete public/server config, assistant and settings pages,
+and semantic placements for an `admin` surface. Adapt the complete files to the
+application's existing config and placement registries.
+
+## Variation points
+
+Change surface ids, settings location, config scope, environment prefix, routes,
+labels, icons, and placement targets. A workspace-scoped application must retain
+the current workspace in both routes and assistant requests through the runtime's
+public workspace support.
+
+## Verification
+
+- load both pages through their normal navigation
+- verify the configured surface and settings target agree
+- verify missing credentials disable assistant calls without exposing secrets
+- exercise one successful and one provider-error conversation
+- verify global or cross-workspace isolation, whichever applies
+- run migrations, server/client tests, and focused browser coverage
+
+## Avoid
+
+- API keys or provider secrets in source
+- a second model client beside the assistant runtime
+- implicit surface selection
+- workspace scope on a non-workspace surface
+- copied runtime repositories, actions, or routes
+- generator commands, question metadata, receipts, or provenance

package/skills/jskit/references/patterns/assistant/assistant-surface/example/config/public.js

@@ -0,0 +1,19 @@
+const config = {
+  surfaceDefaultId: "admin",
+  surfaceDefinitions: {
+    admin: {
+      id: "admin",
+      enabled: true,
+      requiresAuth: true,
+      requiresWorkspace: false
+    }
+  },
+  assistantSurfaces: {
+    admin: {
+      settingsSurfaceId: "admin",
+      configScope: "global"
+    }
+  }
+};
+
+export default config;

package/skills/jskit/references/patterns/assistant/assistant-surface/example/config/server.js

@@ -0,0 +1,9 @@
+const config = {
+  assistantServer: {
+    admin: {
+      aiConfigPrefix: "ADMIN_ASSISTANT"
+    }
+  }
+};
+
+export default config;

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

@@ -0,0 +1,7 @@
+<script setup>
+import { AssistantSurfaceClientElement } from "@jskit-ai/assistant-runtime/client";
+</script>
+
+<template>
+  <AssistantSurfaceClientElement surface-id="admin" />
+</template>

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

@@ -0,0 +1,7 @@
+<script setup>
+import { AssistantSettingsClientElement } from "@jskit-ai/assistant-runtime/client";
+</script>
+
+<template>
+  <AssistantSettingsClientElement target-surface-id="admin" />
+</template>

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

@@ -0,0 +1,38 @@
+import { createPlacementRegistry } from "@jskit-ai/shell-web/client/placement";
+
+const registry = createPlacementRegistry();
+const { addPlacement } = registry;
+
+addPlacement({
+  id: "assistant.admin.chat.link",
+  target: "shell.primary-nav",
+  kind: "link",
+  surfaces: ["admin"],
+  order: 140,
+  props: {
+    label: "Assistant",
+    icon: "mdi-creation-outline",
+    surface: "admin",
+    scopedSuffix: "/assistant",
+    unscopedSuffix: "/assistant"
+  }
+});
+
+addPlacement({
+  id: "assistant.admin.settings.link",
+  target: "page.section-nav",
+  owner: "admin-settings",
+  kind: "link",
+  surfaces: ["admin"],
+  order: 160,
+  props: {
+    label: "Assistant",
+    surface: "admin",
+    scopedSuffix: "/settings/assistant",
+    unscopedSuffix: "/settings/assistant"
+  }
+});
+
+export default function getPlacements() {
+  return registry.build();
+}