@jskit-ai/agent-docs 0.1.177 → 0.1.179

package/guide/agent/app-setup/upgrading-jskit.md

@@ -38,6 +38,21 @@ updating. Declare the workspace paths at the root and depend on each local
 package by its exact manifest version. Do not retain legacy `file:` links; the
 updater does not infer or rewrite an application's local package topology.
 
+The shell and authentication packages use Pinia 4. Before upgrading an app
+that still declares Pinia 3, update its manifest without installing the old
+JSKIT graph:
+
+```bash
+npm pkg set 'dependencies.pinia=^4.0.3' 'dependencies.@vue/devtools-api=^8.2.1' 'dependencies.vue-router=^5.3.1' 'dependencies.vue=^3.5.43'
+```
+
+Update any workspace Pinia declarations too. Pinia 4 requires ESM and the
+separate `@vue/devtools-api` peer; the current application foundations include
+both, with Vue Router 5.3.1 and Vue 3.5.43. Vue Router 5.0.6 still requires
+Pinia 3. The JSKIT updater changes only JSKIT dependencies, so it does not make
+this application-owned dependency change for you. Do not bypass peer conflicts
+with `--force` or `--legacy-peer-deps`.
+
 Then let the published updater select and install its exact coordinated
 catalog:
 

package/guide/agent/framework/application-operations.md

@@ -7,15 +7,19 @@ description: Establish a JSKIT application, select capabilities, and realize pro
 
 # Application operations
 
-Use this for establishing an application foundation, selecting package
-capabilities, and realizing product features from JSKIT patterns.
+## Initial browser loading
+
+Adopt the foundation's accessible HTML skeleton, inline styles, Reload link and
+startup-error message; package updates do not rewrite existing app HTML. Follow
+its cold-browser proof at compact, medium and expanded widths: delay JavaScript,
+check loading feedback, then release it and check app mount, including production
+builds. Compression belongs to hosting, not Genesis.
 
 ## Establish a new application
 
-Start with an initialized Git repository and a clear product request. Use the
-request, current source, and ordinary project documentation. Ask the user for
-any material missing product decision before writing application source. Do
-not run a JSKIT questionnaire and do not create a temporary scaffold app.
+Start with Git and a clear product request. Consult current source and project
+docs; ask for missing product decisions before writing source. Do not run a
+JSKIT questionnaire or create a temporary scaffold app.
 
 Read the [source pattern library](/patterns/). When the optional standalone
 JSKIT Agent Skill is installed, its pattern index contains the same
@@ -41,14 +45,9 @@ receipts, generator provenance, completion ledgers, or hidden operation state.
 
 ## Install and compose capabilities
 
-Plan the complete capability set before changing dependencies. Use the package
-catalogue and package-owned patterns to identify the required runtime packages,
-configuration, resources, and public APIs. Add one coherent package closure,
-then run `npm install` once for that planned change.
-
-Install the explicitly selected top-level packages through npm. Use one
-installation for the planned closure so npm can resolve their ordinary package
-dependencies together:
+Plan capabilities using the catalogue and package-owned patterns: required
+packages, configuration, resources and APIs. Install one planned dependency
+closure of explicitly selected top-level packages in a single npm invocation:
 
 ```bash
 npm install --save-exact @jskit-ai/<selected-package>@latest [...]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.177",
+  "version": "0.1.179",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/feature-package/example/booking-engine/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.205",
+    "@jskit-ai/kernel": "0.1.207",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/patterns/minimal-foundation/PATTERN.md

@@ -101,6 +101,16 @@ the dependency scanner or JSKIT's installed-package optimization settings.
 
 ## Verification
 
+Keep the initial loading shell in `index.html`, with its critical inline styles
+and Reload link. It must not depend on JavaScript, external fonts, or framework
+components. Adapt its skeleton to the product without adding host branding.
+Vue replaces it on mount; the bootstrap failure handler retains an actionable
+error. A failed module download still leaves the static Reload link available.
+Preserve `tests/e2e/startup.spec.ts`: it holds JavaScript requests while proving
+visible loading feedback at three widths, then releases them and proves mounting.
+Run this check against the production build as part of the application's release
+verification, not only against Vite development mode.
+
 After adapting the example, install the declared packages once and run
 `npm run develop` for the live application. Then run the application's lint,
 server tests, client tests, production build, and focused browser smoke.

package/patterns/minimal-foundation/example/index.html

@@ -5,9 +5,23 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>Reading Room</title>
+    <style>
+      #startup-shell { position: fixed; inset: 0; padding: 24px; background: #faf9fc; color: #25232a; font: 16px system-ui, sans-serif; }
+      #startup-shell .placeholder { height: 20px; max-width: 480px; margin: 24px 0; border-radius: 4px; background: #e5e2eb; }
+      #startup-shell a { display: inline-flex; align-items: center; min-height: 48px; color: inherit; }
+      @media (prefers-color-scheme: dark) { #startup-shell { background: #19181d; color: #eeeaf3; } #startup-shell .placeholder { background: #35323d; } }
+    </style>
   </head>
   <body>
-    <div id="app"></div>
+    <div id="app">
+      <main id="startup-shell">
+        <p id="startup-status" role="status" aria-live="polite">Loading application…</p>
+        <div class="placeholder" aria-hidden="true"></div>
+        <div class="placeholder" aria-hidden="true"></div>
+        <noscript>JavaScript must be enabled to open this application.</noscript>
+        <a href="">Reload page</a>
+      </main>
+    </div>
     <script type="module" src="/src/main.js"></script>
   </body>
 </html>

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

@@ -34,20 +34,21 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.205",
+    "@jskit-ai/kernel": "0.1.207",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
-    "pinia": "^3.0.4",
-    "vue": "^3.5.38",
-    "vue-router": "^5.1.0",
+    "pinia": "^4.0.3",
+    "vue": "^3.5.43",
+    "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.203",
-    "@fastify/fast-json-stringify-compiler": "^5.1.0"
+    "@jskit-ai/http-runtime": "0.1.205",
+    "@fastify/fast-json-stringify-compiler": "^5.1.0",
+    "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.202",
-    "@jskit-ai/jskit-catalog": "0.1.230",
+    "@jskit-ai/config-eslint": "0.1.204",
+    "@jskit-ai/jskit-catalog": "0.1.232",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

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

@@ -82,4 +82,8 @@ void bootstrapClientShellApp({
   fallbackRoute
 }).catch((error) => {
   console.error("Failed to bootstrap client app.", error);
+  const status = document.getElementById("startup-status");
+  if (status) {
+    status.textContent = "The application could not open. Reload the page to try again.";
+  }
 });

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

@@ -0,0 +1,35 @@
+import { expect, test } from "@playwright/test";
+
+for (const width of [390, 768, 1280]) {
+  test(`startup remains visible before JavaScript at ${width}px`, async ({ page }) => {
+    await page.setViewportSize({ width, height: 900 });
+    let releaseScripts!: () => void;
+    const scriptsHeld = new Promise<void>(resolve => { releaseScripts = resolve; });
+    let scriptRequests = 0;
+    await page.route("**/*", async route => {
+      if (route.request().resourceType() === "script") {
+        scriptRequests += 1;
+        await scriptsHeld;
+      }
+      await route.continue();
+    });
+    try {
+      await page.goto("/home", { waitUntil: "commit" });
+      await expect(page.getByRole("status")).toHaveText("Loading application…");
+      await expect(page.getByRole("status")).toBeVisible();
+      await expect(page.getByRole("link", { name: "Reload page" })).toBeVisible();
+      await expect.poll(() => scriptRequests).toBeGreaterThan(0);
+      const geometry = await page.evaluate(() => ({
+        width: document.documentElement.clientWidth,
+        scrollWidth: document.documentElement.scrollWidth,
+        reloadHeight: document.querySelector("#startup-shell a")!.getBoundingClientRect().height
+      }));
+      expect(geometry.scrollWidth).toBeLessThanOrEqual(geometry.width + 1);
+      expect(geometry.reloadHeight).toBeGreaterThanOrEqual(48);
+    } finally {
+      releaseScripts();
+    }
+    await expect(page.locator("#app[data-v-app]")).toBeVisible();
+    await expect(page.locator("#startup-shell")).toHaveCount(0);
+  });
+}

package/patterns/shell-foundation/PATTERN.md

@@ -103,6 +103,16 @@ the dependency scanner or JSKIT's installed-package optimization settings.
 
 ## Verification
 
+Keep the initial loading shell in `index.html`, with its critical inline styles
+and Reload link. It must not depend on JavaScript, external fonts, or framework
+components. Adapt its skeleton to the product without adding host branding.
+Vue replaces it on mount; the bootstrap failure handler retains an actionable
+error. A failed module download still leaves the static Reload link available.
+Preserve `tests/e2e/startup.spec.ts`: it holds JavaScript requests while proving
+visible loading feedback at three widths, then releases them and proves mounting.
+Run this check against the production build as part of the application's release
+verification, not only against Vite development mode.
+
 Install the declared packages once, run `npm run develop` for the live
 application, then run lint, server tests, client tests, the production build,
 and the adaptive browser smoke at compact, medium, and expanded viewports.

package/patterns/shell-foundation/example/index.html

@@ -5,9 +5,23 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>Reading Room</title>
+    <style>
+      #startup-shell { position: fixed; inset: 0; padding: 24px; background: #faf9fc; color: #25232a; font: 16px system-ui, sans-serif; }
+      #startup-shell .placeholder { height: 20px; max-width: 480px; margin: 24px 0; border-radius: 4px; background: #e5e2eb; }
+      #startup-shell a { display: inline-flex; align-items: center; min-height: 48px; color: inherit; }
+      @media (prefers-color-scheme: dark) { #startup-shell { background: #19181d; color: #eeeaf3; } #startup-shell .placeholder { background: #35323d; } }
+    </style>
   </head>
   <body>
-    <div id="app"></div>
+    <div id="app">
+      <main id="startup-shell">
+        <p id="startup-status" role="status" aria-live="polite">Loading application…</p>
+        <div class="placeholder" aria-hidden="true"></div>
+        <div class="placeholder" aria-hidden="true"></div>
+        <noscript>JavaScript must be enabled to open this application.</noscript>
+        <a href="">Reload page</a>
+      </main>
+    </div>
     <script type="module" src="/src/main.js"></script>
   </body>
 </html>

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

@@ -34,22 +34,23 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.205",
+    "@jskit-ai/kernel": "0.1.207",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
-    "pinia": "^3.0.4",
-    "vue": "^3.5.38",
-    "vue-router": "^5.1.0",
+    "pinia": "^4.0.3",
+    "vue": "^3.5.43",
+    "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.203",
+    "@jskit-ai/http-runtime": "0.1.205",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.1.209",
-    "@fastify/fast-json-stringify-compiler": "^5.1.0"
+    "@jskit-ai/shell-web": "0.1.211",
+    "@fastify/fast-json-stringify-compiler": "^5.1.0",
+    "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.202",
-    "@jskit-ai/jskit-catalog": "0.1.230",
+    "@jskit-ai/config-eslint": "0.1.204",
+    "@jskit-ai/jskit-catalog": "0.1.232",
     "@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.1.205"
+    "@jskit-ai/kernel": "0.1.207"
   },
   "jskit": {
     "kind": "runtime",

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

@@ -82,4 +82,8 @@ void bootstrapClientShellApp({
   fallbackRoute
 }).catch((error) => {
   console.error("Failed to bootstrap client app.", error);
+  const status = document.getElementById("startup-status");
+  if (status) {
+    status.textContent = "The application could not open. Reload the page to try again.";
+  }
 });

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

@@ -0,0 +1,35 @@
+import { expect, test } from "@playwright/test";
+
+for (const width of [390, 768, 1280]) {
+  test(`startup remains visible before JavaScript at ${width}px`, async ({ page }) => {
+    await page.setViewportSize({ width, height: 900 });
+    let releaseScripts!: () => void;
+    const scriptsHeld = new Promise<void>(resolve => { releaseScripts = resolve; });
+    let scriptRequests = 0;
+    await page.route("**/*", async route => {
+      if (route.request().resourceType() === "script") {
+        scriptRequests += 1;
+        await scriptsHeld;
+      }
+      await route.continue();
+    });
+    try {
+      await page.goto("/home", { waitUntil: "commit" });
+      await expect(page.getByRole("status")).toHaveText("Loading application…");
+      await expect(page.getByRole("status")).toBeVisible();
+      await expect(page.getByRole("link", { name: "Reload page" })).toBeVisible();
+      await expect.poll(() => scriptRequests).toBeGreaterThan(0);
+      const geometry = await page.evaluate(() => ({
+        width: document.documentElement.clientWidth,
+        scrollWidth: document.documentElement.scrollWidth,
+        reloadHeight: document.querySelector("#startup-shell a")!.getBoundingClientRect().height
+      }));
+      expect(geometry.scrollWidth).toBeLessThanOrEqual(geometry.width + 1);
+      expect(geometry.reloadHeight).toBeGreaterThanOrEqual(48);
+    } finally {
+      releaseScripts();
+    }
+    await expect(page.locator("#app[data-v-app]")).toBeVisible();
+    await expect(page.locator("#startup-shell")).toHaveCount(0);
+  });
+}