@jskit-ai/shell-web 0.1.65 → 0.1.66

package/src/client/providers/ShellWebClientProvider.js

@@ -1,11 +1,8 @@
 import { getClientAppConfig } from "@jskit-ai/kernel/client";
 import {
-  isRecord,
-  shouldRetryTransientQueryFailure,
-  transientQueryRetryDelay
+  isRecord
 } from "@jskit-ai/kernel/shared/support";
 import { createProviderLogger as createSharedProviderLogger } from "@jskit-ai/kernel/shared/support/providerLogger";
-import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
 import {
   createDefaultErrorPolicy
 } from "../error/policy.js";
@@ -33,19 +30,6 @@ const APP_PLACEMENT_MODULE_SPECIFIER = "/src/placement.js";
 const APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER = "/src/placementTopology.js";
 const APP_ERROR_MODULE_SPECIFIER = "/src/error.js";
 
-function createShellWebQueryClient() {
-  return new QueryClient({
-    defaultOptions: {
-      queries: {
-        refetchOnWindowFocus: false,
-        refetchOnReconnect: true,
-        retry: shouldRetryTransientQueryFailure,
-        retryDelay: transientQueryRetryDelay
-      }
-    }
-  });
-}
-
 function isMissingDynamicModule(error, moduleSpecifier) {
   const message = String(error?.message || error || "");
   return (
@@ -93,21 +77,7 @@ async function loadAppPlacementTopology(logger) {
   try {
     const moduleNamespace = await import("/src/placementTopology.js");
     const exported = moduleNamespace?.default;
-    const resolved = typeof exported === "function" ? exported() : exported;
-    if (Array.isArray(resolved)) {
-      return resolved;
-    }
-    if (resolved && typeof resolved === "object") {
-      return [resolved];
-    }
-
-    logger.warn(
-      {
-        module: APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER,
-        exportedType: typeof exported
-      },
-      "App placement topology module default export did not resolve to an object or array; using empty topology."
-    );
+    return resolveAppPlacementTopologyExport(exported, logger);
   } catch (error) {
     if (isMissingDynamicModule(error, APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER)) {
       return [];
@@ -125,6 +95,25 @@ async function loadAppPlacementTopology(logger) {
   return [];
 }
 
+function resolveAppPlacementTopologyExport(exported, logger) {
+  const resolved = typeof exported === "function" ? exported() : exported;
+  if (Array.isArray(resolved)) {
+    return resolved;
+  }
+  if (resolved && typeof resolved === "object") {
+    return resolved;
+  }
+
+  logger.warn(
+    {
+      module: APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER,
+      exportedType: typeof exported
+    },
+    "App placement topology module default export did not resolve to an object or array; using empty topology."
+  );
+  return [];
+}
+
 function createErrorConfigToolkit(errorRuntime) {
   return Object.freeze({
     createDefaultErrorPolicy,
@@ -197,6 +186,136 @@ function applyAppErrorConfig(errorRuntime, errorConfig = {}) {
   errorRuntime.assertBootReady();
 }
 
+function isPullRefreshQuery(query = null) {
+  const meta = isRecord(query?.meta) ? query.meta : {};
+  if (meta.jskitRefresh === "pull") {
+    return true;
+  }
+  if (meta.jskitRefresh === false) {
+    return false;
+  }
+
+  const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
+  return jskitMeta.refreshOnPull !== false;
+}
+
+function createShellRefreshRuntime({
+  app,
+  logger = null
+} = {}) {
+  if (!app || typeof app.has !== "function" || typeof app.make !== "function") {
+    throw new Error("createShellRefreshRuntime requires application has()/make().");
+  }
+
+  const runtimeLogger = logger || createSharedProviderLogger(app);
+  let refreshQueue = Promise.resolve(null);
+
+  async function refreshBootstrap(reason) {
+    if (!app.has("runtime.web-bootstrap.client")) {
+      return false;
+    }
+
+    const bootstrapRuntime = app.make("runtime.web-bootstrap.client");
+    if (!bootstrapRuntime || typeof bootstrapRuntime.refresh !== "function") {
+      return false;
+    }
+
+    await bootstrapRuntime.refresh(reason);
+    return true;
+  }
+
+  async function refetchPullQueries() {
+    if (!app.has("jskit.client.query-client")) {
+      return false;
+    }
+
+    const queryClient = app.make("jskit.client.query-client");
+    if (!queryClient || typeof queryClient.refetchQueries !== "function") {
+      return false;
+    }
+
+    await queryClient.refetchQueries(
+      {
+        type: "active",
+        predicate: isPullRefreshQuery
+      },
+      {
+        throwOnError: false
+      }
+    );
+    return true;
+  }
+
+  function reportRefreshFailure(error) {
+    runtimeLogger.warn(
+      {
+        error: String(error?.message || error || "unknown error")
+      },
+      "Shell refresh failed."
+    );
+
+    if (!app.has("runtime.web-error.client")) {
+      return;
+    }
+
+    const errorRuntime = app.make("runtime.web-error.client");
+    if (!errorRuntime || typeof errorRuntime.report !== "function") {
+      return;
+    }
+
+    errorRuntime.report({
+      source: "shell-web.refresh",
+      message: "Unable to refresh. Check the connection and try again.",
+      intent: "app-recoverable",
+      severity: "error",
+      dedupeKey: "shell-web.refresh.failed",
+      dedupeWindowMs: 2000,
+      action: {
+        label: "Retry",
+        dismissOnRun: true,
+        handler() {
+          void refresh("retry");
+        }
+      }
+    });
+  }
+
+  async function performRefresh(reason = "manual") {
+    const normalizedReason = String(reason || "manual").trim() || "manual";
+    try {
+      const [bootstrapRefreshed, queriesRefetched] = await Promise.all([
+        refreshBootstrap(normalizedReason),
+        refetchPullQueries()
+      ]);
+
+      return Object.freeze({
+        reason: normalizedReason,
+        bootstrapRefreshed,
+        queriesRefetched
+      });
+    } catch (error) {
+      reportRefreshFailure(error);
+      return Object.freeze({
+        reason: normalizedReason,
+        bootstrapRefreshed: false,
+        queriesRefetched: false,
+        error
+      });
+    }
+  }
+
+  function refresh(reason = "manual") {
+    refreshQueue = refreshQueue
+      .catch(() => null)
+      .then(() => performRefresh(reason));
+    return refreshQueue;
+  }
+
+  return Object.freeze({
+    refresh
+  });
+}
+
 function installVueErrorBridge(vueApp, errorRuntime, logger) {
   if (!vueApp || !isRecord(vueApp.config)) {
     return;
@@ -210,8 +329,8 @@ function installVueErrorBridge(vueApp, errorRuntime, logger) {
         source: "shell-web.vue.error-handler",
         message: String(error?.message || "Unexpected UI error."),
         cause: error,
+        intent: "blocking",
         severity: "error",
-        channel: "dialog",
         details: {
           info: String(info || "")
         }
@@ -248,8 +367,8 @@ function installRouterErrorBridge(app, errorRuntime, logger) {
         source: "shell-web.router.on-error",
         message: String(error?.message || "Navigation failed."),
         cause: error,
+        intent: "app-recoverable",
         severity: "error",
-        channel: "banner",
         dedupeKey: String(error?.message || "navigation-failed"),
         dedupeWindowMs: 2000
       });
@@ -312,7 +431,12 @@ class ShellWebClientProvider {
         logger
       })
     );
-    app.singleton("shell.web.query-client", () => createShellWebQueryClient());
+    app.singleton("runtime.web-refresh.client", (scope) =>
+      createShellRefreshRuntime({
+        app: scope,
+        logger
+      })
+    );
     app.singleton("runtime.web-error.presentation-store.client", () => createErrorPresentationStore());
     app.singleton("runtime.web-error.client", (scope) =>
       createErrorRuntime({
@@ -384,12 +508,11 @@ class ShellWebClientProvider {
       throw new Error("ShellWebClientProvider requires Pinia installed in the client app.");
     }
     const errorPresentationStore = app.make("runtime.web-error.presentation-store.client");
+    const refreshRuntime = app.make("runtime.web-refresh.client");
     useShellErrorPresentationStore(pinia).attachRuntimeStore(errorPresentationStore);
 
-    vueApp.use(VueQueryPlugin, {
-      queryClient: app.make("shell.web.query-client")
-    });
     vueApp.provide("jskit.shell-web.runtime.web-placement.client", placementRuntime);
+    vueApp.provide("jskit.shell-web.runtime.web-refresh.client", refreshRuntime);
     vueApp.provide("jskit.shell-web.runtime.web-error.client", errorRuntime);
     vueApp.provide(
       "jskit.shell-web.runtime.web-error.presentation-store.client",
@@ -402,5 +525,6 @@ class ShellWebClientProvider {
 }
 
 export {
-  ShellWebClientProvider
+  ShellWebClientProvider,
+  resolveAppPlacementTopologyExport
 };

package/src/client/stores/useShellLayoutStore.js

@@ -8,6 +8,8 @@ import {
 export const useShellLayoutStore = defineStore("jskit.shell-web.layout", () => {
   const drawerDefaultOpen = ref(readDrawerDefaultOpenPreference());
   const drawerOpen = ref(drawerDefaultOpen.value);
+  const supportingContentOpen = ref(false);
+  const supportingContentTitle = ref("");
 
   function setDrawerDefaultOpen(open) {
     const normalized = Boolean(open);
@@ -24,11 +26,29 @@ export const useShellLayoutStore = defineStore("jskit.shell-web.layout", () => {
     drawerOpen.value = !drawerOpen.value;
   }
 
+  function openSupportingContent({ title = "" } = {}) {
+    supportingContentTitle.value = String(title || "").trim();
+    supportingContentOpen.value = true;
+  }
+
+  function closeSupportingContent() {
+    supportingContentOpen.value = false;
+  }
+
+  function setSupportingContentOpen(open) {
+    supportingContentOpen.value = Boolean(open);
+  }
+
   return {
     drawerDefaultOpen,
     drawerOpen,
+    supportingContentOpen,
+    supportingContentTitle,
     setDrawerDefaultOpen,
     setDrawerOpen,
-    toggleDrawer
+    toggleDrawer,
+    openSupportingContent,
+    closeSupportingContent,
+    setSupportingContentOpen
   };
 });

package/src/test/adaptiveShellSmoke.js

@@ -0,0 +1,121 @@
+const DEFAULT_BASE_URL = String(process.env.PLAYWRIGHT_BASE_URL || "http://127.0.0.1:5173").replace(/\/+$/u, "");
+const DEFAULT_SMOKE_PATH = String(process.env.JSKIT_PLAYWRIGHT_SMOKE_PATH || "/home");
+const DEFAULT_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 })
+]);
+
+async function expectNoHorizontalOverflow(page, expect) {
+  const metrics = await page.evaluate(() => ({
+    clientWidth: document.documentElement.clientWidth,
+    scrollWidth: document.documentElement.scrollWidth
+  }));
+
+  expect(metrics.scrollWidth).toBeLessThanOrEqual(metrics.clientWidth + 1);
+}
+
+async function expectGeneratedScreenContract(page, expect) {
+  const screen = page.locator(".generated-ui-screen").first();
+
+  await expect(screen).toBeVisible();
+}
+
+async function pullToRefresh(page, expect) {
+  await page.evaluate(() => {
+    window.scrollTo(0, 0);
+  });
+  await page.dispatchEvent("body", "pointerdown", {
+    pointerId: 41,
+    pointerType: "touch",
+    isPrimary: true,
+    button: 0,
+    clientX: 180,
+    clientY: 90
+  });
+  await page.dispatchEvent("body", "pointermove", {
+    pointerId: 41,
+    pointerType: "touch",
+    isPrimary: true,
+    button: 0,
+    clientX: 184,
+    clientY: 250
+  });
+  await expect(page.getByTestId("jskit-shell-pull-refresh")).toBeVisible();
+  await page.dispatchEvent("body", "pointerup", {
+    pointerId: 41,
+    pointerType: "touch",
+    isPrimary: true,
+    button: 0,
+    clientX: 184,
+    clientY: 250
+  });
+}
+
+async function isElementVisibleInViewport(page, testId) {
+  return page.getByTestId(testId).evaluate((element) => {
+    const rect = element.getBoundingClientRect();
+    const style = window.getComputedStyle(element);
+    return (
+      style.display !== "none" &&
+      style.visibility !== "hidden" &&
+      rect.width > 0 &&
+      rect.height > 0 &&
+      rect.right > 0 &&
+      rect.left < window.innerWidth &&
+      rect.bottom > 0 &&
+      rect.top < window.innerHeight
+    );
+  });
+}
+
+function runAdaptiveShellSmoke({
+  test,
+  expect,
+  baseUrl = DEFAULT_BASE_URL,
+  smokePath = DEFAULT_SMOKE_PATH,
+  viewports = DEFAULT_VIEWPORTS
+} = {}) {
+  if (!test || !expect) {
+    throw new Error("runAdaptiveShellSmoke requires Playwright test and expect.");
+  }
+
+  test.describe("generated adaptive shell smoke", () => {
+    for (const viewport of viewports) {
+      test(`${viewport.name} layout has reachable navigation and no horizontal overflow`, async ({ page }) => {
+        await page.setViewportSize({ width: viewport.width, height: viewport.height });
+        await page.goto(`${baseUrl}${smokePath}`);
+        await expect(page.locator("body")).toBeVisible();
+        await expectGeneratedScreenContract(page, expect);
+        await expectNoHorizontalOverflow(page, expect);
+
+        if (viewport.name === "compact") {
+          let bootstrapRequests = 0;
+          await page.route("**/api/bootstrap**", async (route) => {
+            bootstrapRequests += 1;
+            await route.continue();
+          });
+          const bootstrapRequestsBeforePull = bootstrapRequests;
+
+          await expect(page.getByTestId("jskit-shell-bottom-nav")).toBeVisible();
+          expect(await isElementVisibleInViewport(page, "jskit-shell-drawer")).toBe(false);
+
+          const navButtonHeights = await page.getByTestId("jskit-shell-bottom-nav").locator(".v-btn").evaluateAll((buttons) =>
+            buttons.map((button) => button.getBoundingClientRect().height)
+          );
+          expect(navButtonHeights.length).toBeGreaterThan(0);
+          for (const height of navButtonHeights) {
+            expect(height).toBeGreaterThanOrEqual(48);
+          }
+
+          await pullToRefresh(page, expect);
+          await expect.poll(() => bootstrapRequests).toBeGreaterThan(bootstrapRequestsBeforePull);
+        } else {
+          await expect(page.getByTestId("jskit-shell-drawer")).toBeVisible();
+        }
+      });
+    }
+  });
+}
+
+export { DEFAULT_VIEWPORTS, runAdaptiveShellSmoke };

package/templates/expected-existing/src/pages/home/index.vue

@@ -1,12 +1,42 @@
 <template>
-  <v-card class="mx-auto" max-width="960" rounded="xl" border elevation="1">
-    <v-card-item class="px-6 py-5 px-md-8 py-md-7">
-      <v-card-title class="text-h4">welcome</v-card-title>
-      <v-card-subtitle class="text-subtitle-1 mt-2">starter app</v-card-subtitle>
-    </v-card-item>
-    <v-divider />
-    <v-card-text class="px-6 py-5 px-md-8 py-md-7 text-body-1 text-medium-emphasis">
-      Start by adding packages and pages to this app.
-    </v-card-text>
-  </v-card>
+  <section class="generated-ui-screen generated-ui-screen--app home-start-screen d-flex flex-column ga-4">
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">Home</p>
+      <h1 class="home-start-screen__title">Home base</h1>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        The app runtime is online and ready for the first real workflow.
+      </p>
+    </header>
+
+    <v-sheet rounded="lg" border class="home-start-screen__panel">
+      <h2 class="text-h6 mb-2">No activity yet</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        Recent work, saved records, and next actions will appear here once this app has data.
+      </p>
+    </v-sheet>
+  </section>
 </template>
+
+<style scoped>
+.generated-ui-screen {
+  --generated-ui-screen-title-size: clamp(1.5rem, 3vw, 2.5rem);
+  --generated-ui-screen-panel-padding: 1rem;
+}
+
+.home-start-screen {
+  margin-inline: auto;
+  max-width: 48rem;
+}
+
+.home-start-screen__title {
+  font-size: var(--generated-ui-screen-title-size);
+  font-weight: 700;
+  letter-spacing: -0.03em;
+  line-height: 1.08;
+  margin: 0 0 0.45rem;
+}
+
+.home-start-screen__panel {
+  padding: var(--generated-ui-screen-panel-padding);
+}
+</style>

package/templates/src/components/ShellLayout.vue

@@ -1,88 +1,12 @@
-<script setup>
-import { useShellLayoutState } from "@jskit-ai/shell-web/client/composables/useShellLayoutState";
-import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
-
-const props = defineProps({
-  surface: {
-    type: String,
-    default: ""
-  },
-  surfaceLabel: {
-    type: String,
-    default: ""
-  },
-  title: {
-    type: String,
-    default: ""
-  },
-  subtitle: {
-    type: String,
-    default: ""
+<script>
+import { h } from "vue";
+import PackageShellLayout from "@jskit-ai/shell-web/client/components/ShellLayout";
+
+export default {
+  name: "ShellLayout",
+  inheritAttrs: false,
+  setup(_, { attrs, slots }) {
+    return () => h(PackageShellLayout, attrs, slots);
   }
-});
-
-const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useShellLayoutState(props);
+};
 </script>
-
-<template>
-  <v-layout class="shell-layout border rounded-lg overflow-hidden">
-    <v-app-bar border density="comfortable" elevation="0" class="bg-surface">
-      <v-app-bar-nav-icon aria-label="Toggle navigation menu" @click="toggleDrawer" />
-
-      <slot name="top-left" :surface="resolvedSurface">
-        <div class="d-flex align-center ga-2">
-          <v-chip color="primary" size="small" label>{{ resolvedSurfaceLabel }}</v-chip>
-          <ShellOutlet target="shell-layout:top-left" />
-        </div>
-      </slot>
-
-      <v-spacer />
-
-      <slot name="top-right" :surface="resolvedSurface">
-        <div class="d-flex align-center ga-2">
-          <ShellOutlet target="shell-layout:top-right" />
-        </div>
-      </slot>
-    </v-app-bar>
-
-    <v-navigation-drawer v-model="drawerOpen" border class="bg-surface" :width="248">
-      <slot name="menu" :surface="resolvedSurface">
-        <v-list nav density="comfortable" class="pt-2">
-          <v-list-subheader class="text-uppercase text-caption">Navigation</v-list-subheader>
-          <ShellOutlet
-            target="shell-layout:primary-menu"
-            default
-          />
-          <v-divider class="my-2" />
-          <ShellOutlet target="shell-layout:secondary-menu" />
-        </v-list>
-      </slot>
-    </v-navigation-drawer>
-
-    <v-main class="bg-background">
-      <v-container fluid class="shell-layout__content">
-        <h1 v-if="title" class="shell-layout__title text-h5">{{ title }}</h1>
-        <p v-if="subtitle" class="shell-layout__subtitle text-body-2 text-medium-emphasis">{{ subtitle }}</p>
-        <slot />
-      </v-container>
-    </v-main>
-  </v-layout>
-</template>
-
-<style scoped>
-.shell-layout {
-  min-height: 72vh;
-}
-
-.shell-layout__content {
-  padding: 0.75rem 1rem 1rem;
-}
-
-.shell-layout__title {
-  margin-bottom: 0.25rem;
-}
-
-.shell-layout__subtitle {
-  margin-bottom: 0.75rem;
-}
-</style>

package/templates/src/components/menus/TabLinkItem.vue

@@ -29,6 +29,10 @@ const props = defineProps({
   disabled: {
     type: Boolean,
     default: false
+  },
+  exact: {
+    type: Boolean,
+    default: false
   }
 });
 </script>

package/templates/src/error.js

@@ -2,12 +2,18 @@ import { createDefaultErrorPolicy } from "@jskit-ai/shell-web/client/error";
 
 /**
  * App-owned error handling contract.
+ * - intent chooses default presentation: resource-load, action-feedback, app-recoverable, blocking.
  * - policy(event, ctx): decide channel + presenter + message.
  * - defaultPresenterId: used when policy does not set presenterId.
  * - presenters: optional custom presenters registered at boot.
  */
 export default Object.freeze({
   defaultPresenterId: "material.snackbar",
-  policy: createDefaultErrorPolicy(),
+  policy: createDefaultErrorPolicy({
+    resourceLoadChannel: "silent",
+    actionFeedbackChannel: "snackbar",
+    appRecoverableChannel: "banner",
+    blockingChannel: "dialog"
+  }),
   presenters: []
 });