@jskit-ai/shell-web 0.1.4

package/templates/src/components/ShellLayout.vue

@@ -0,0 +1,247 @@
+<script setup>
+import { computed, ref } from "vue";
+import { useRoute } from "vue-router";
+import { normalizeObject } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface";
+import {
+  useWebPlacementContext,
+  readPlacementSurfaceConfig,
+  resolveSurfaceDefinitionFromPlacementContext,
+  resolveSurfaceIdFromPlacementPathname
+} from "@jskit-ai/shell-web/client/placement";
+import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
+
+const DEFAULT_ACTION_FALLBACK = Object.freeze({
+  label: "",
+  to: "",
+  variant: "text",
+  color: "secondary"
+});
+
+const DEFAULT_MENU_FALLBACK = Object.freeze({
+  label: "",
+  to: "/",
+  icon: "$menu"
+});
+
+const props = defineProps({
+  surface: {
+    type: String,
+    default: ""
+  },
+  surfaceLabel: {
+    type: String,
+    default: ""
+  },
+  title: {
+    type: String,
+    default: ""
+  },
+  subtitle: {
+    type: String,
+    default: ""
+  },
+  topLeftActions: {
+    type: Array,
+    default: () => []
+  },
+  topRightActions: {
+    type: Array,
+    default: () => []
+  },
+  menuItems: {
+    type: Array,
+    default: () => []
+  }
+});
+
+const route = useRoute();
+const { context: placementContext } = useWebPlacementContext();
+const drawerOpen = ref(true);
+
+function normalizeAction(action, fallback) {
+  const source = normalizeObject(action);
+  const fallbackSource = normalizeObject(fallback);
+  const label = String(source.label || fallbackSource.label || "").trim();
+  if (!label) {
+    return null;
+  }
+
+  return {
+    label,
+    to: String(source.to || fallbackSource.to || "").trim(),
+    variant: String(source.variant || fallbackSource.variant || "text").trim(),
+    color: String(source.color || fallbackSource.color || "secondary").trim()
+  };
+}
+
+function normalizeMenuItem(item, fallback) {
+  const source = normalizeObject(item);
+  const fallbackSource = normalizeObject(fallback);
+  const label = String(source.label || fallbackSource.label || "").trim();
+  if (!label) {
+    return null;
+  }
+
+  return {
+    label,
+    to: String(source.to || fallbackSource.to || "").trim() || "/",
+    icon: String(source.icon || fallbackSource.icon || "$menu").trim() || "$menu"
+  };
+}
+
+function normalizeActionList(actions) {
+  const source = Array.isArray(actions) ? actions : [];
+  return source
+    .map((item) => normalizeAction(item, DEFAULT_ACTION_FALLBACK))
+    .filter(Boolean);
+}
+
+function normalizeMenuList(items) {
+  const source = Array.isArray(items) ? items : [];
+  return source
+    .map((item) => normalizeMenuItem(item, DEFAULT_MENU_FALLBACK))
+    .filter(Boolean);
+}
+
+function toSurfaceLabel(surfaceId = "") {
+  const normalizedSurfaceId = String(surfaceId || "").trim().toLowerCase();
+  if (!normalizedSurfaceId) {
+    return "Surface";
+  }
+
+  return normalizedSurfaceId
+    .split(/[^a-z0-9]+/g)
+    .filter(Boolean)
+    .map((segment) => `${segment.slice(0, 1).toUpperCase()}${segment.slice(1)}`)
+    .join(" ");
+}
+
+function toggleDrawer() {
+  drawerOpen.value = !drawerOpen.value;
+}
+
+const resolvedSurface = computed(() => {
+  const explicitSurface = normalizeSurfaceId(props.surface);
+  if (explicitSurface) {
+    return explicitSurface;
+  }
+
+  const pathname =
+    String(route?.path || "").trim() ||
+    (typeof window === "object" && window?.location?.pathname ? String(window.location.pathname).trim() : "/");
+  const contextValue = placementContext?.value || null;
+  const resolvedSurfaceFromPath = resolveSurfaceIdFromPlacementPathname(contextValue, pathname);
+  if (resolvedSurfaceFromPath) {
+    return resolvedSurfaceFromPath;
+  }
+
+  const surfaceConfig = readPlacementSurfaceConfig(contextValue);
+  if (surfaceConfig.defaultSurfaceId) {
+    return surfaceConfig.defaultSurfaceId;
+  }
+
+  return "surface";
+});
+
+const resolvedSurfaceLabel = computed(() => {
+  const explicitLabel = String(props.surfaceLabel || "").trim();
+  if (explicitLabel) {
+    return explicitLabel;
+  }
+
+  const surfaceDefinition = resolveSurfaceDefinitionFromPlacementContext(
+    placementContext?.value || null,
+    resolvedSurface.value
+  );
+  const configuredLabel = String(surfaceDefinition?.label || "").trim();
+  if (configuredLabel) {
+    return configuredLabel;
+  }
+
+  return toSurfaceLabel(resolvedSurface.value);
+});
+
+const resolvedTopLeftActions = computed(() => normalizeActionList(props.topLeftActions));
+const resolvedTopRightActions = computed(() => normalizeActionList(props.topRightActions));
+const resolvedMenuItems = computed(() => normalizeMenuList(props.menuItems));
+</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" :actions="resolvedTopLeftActions" :surface="resolvedSurface">
+        <div class="d-flex align-center ga-2">
+          <v-btn
+            v-for="action in resolvedTopLeftActions"
+            :key="`top-left-${action.label}`"
+            :to="action.to || undefined"
+            :variant="action.variant"
+            :color="action.color"
+            size="small"
+            class="text-none"
+          >
+            {{ action.label }}
+          </v-btn>
+          <v-chip color="primary" size="small" label>{{ resolvedSurfaceLabel }}</v-chip>
+          <ShellOutlet host="shell-layout" position="top-left" />
+        </div>
+      </slot>
+
+      <v-spacer />
+
+      <slot name="top-right" :actions="resolvedTopRightActions" :surface="resolvedSurface">
+        <div class="d-flex align-center ga-2">
+          <v-btn
+            v-for="action in resolvedTopRightActions"
+            :key="`top-right-${action.label}`"
+            :to="action.to || undefined"
+            :variant="action.variant"
+            :color="action.color"
+            size="small"
+            class="text-none"
+          >
+            {{ action.label }}
+          </v-btn>
+          <ShellOutlet host="shell-layout" position="top-right" />
+        </div>
+      </slot>
+    </v-app-bar>
+
+    <v-navigation-drawer v-model="drawerOpen" border class="bg-surface" :width="248">
+      <slot name="menu" :items="resolvedMenuItems" :surface="resolvedSurface">
+        <v-list nav density="comfortable" class="pt-2">
+          <v-list-subheader class="text-uppercase text-caption">{{ resolvedSurfaceLabel }}</v-list-subheader>
+          <v-list-item
+            v-for="item in resolvedMenuItems"
+            :key="`menu-${item.label}`"
+            :title="item.label"
+            :to="item.to"
+            :prepend-icon="item.icon"
+            rounded="lg"
+            class="mb-1"
+          />
+          <ShellOutlet host="shell-layout" position="primary-menu" />
+          <v-divider class="my-2" />
+          <ShellOutlet host="shell-layout" position="secondary-menu" />
+        </v-list>
+      </slot>
+    </v-navigation-drawer>
+
+    <v-main class="bg-background">
+      <v-container fluid class="pa-4">
+        <h1 class="text-h5 mb-2">{{ title }}</h1>
+        <p class="text-body-2 text-medium-emphasis mb-4">{{ subtitle }}</p>
+        <slot />
+      </v-container>
+    </v-main>
+  </v-layout>
+</template>
+
+<style scoped>
+.shell-layout {
+  min-height: 72vh;
+}
+</style>

package/templates/src/error.js

@@ -0,0 +1,13 @@
+import { createDefaultErrorPolicy } from "@jskit-ai/shell-web/client/error";
+
+/**
+ * App-owned error handling contract.
+ * - 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(),
+  presenters: []
+});

package/templates/src/pages/console/index.vue

@@ -0,0 +1,24 @@
+<template>
+  <v-card rounded="lg" elevation="1" border>
+    <v-card-item>
+      <template #prepend>
+        <v-chip color="primary" size="small" label>Console</v-chip>
+      </template>
+      <v-card-title class="text-h5">Operations Console</v-card-title>
+      <v-card-subtitle>Operator tools, scripts, and diagnostics.</v-card-subtitle>
+    </v-card-item>
+    <v-divider />
+    <v-card-text class="d-flex flex-column ga-4">
+      <div class="d-flex flex-wrap ga-3">
+        <v-chip color="secondary" variant="tonal" label>Route: /console</v-chip>
+        <v-chip color="info" variant="tonal" label>Surface status: enabled</v-chip>
+      </div>
+      <p class="text-medium-emphasis mb-0">
+        Ideal for operator actions, scripts, and technical insights not meant for end users.
+      </p>
+      <div>
+        <v-btn color="primary" variant="flat" to="/home">Back to home</v-btn>
+      </div>
+    </v-card-text>
+  </v-card>
+</template>

package/templates/src/pages/console.vue

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

package/templates/src/pages/home/index.vue

@@ -0,0 +1,54 @@
+<script setup>
+import { computed } from "vue";
+import { useQuery } from "@tanstack/vue-query";
+
+const healthQuery = useQuery({
+  queryKey: ["shell-web", "health"],
+  queryFn: async () => {
+    const response = await fetch("/api/health");
+    if (!response.ok) {
+      throw new Error("Health request failed.");
+    }
+    return response.json();
+  },
+  refetchOnWindowFocus: false
+});
+
+const health = computed(() => {
+  if (healthQuery.isPending.value || healthQuery.isFetching.value) {
+    return "loading...";
+  }
+
+  if (healthQuery.error.value) {
+    return "unreachable";
+  }
+
+  return healthQuery.data.value?.ok ? "ok" : "unhealthy";
+});
+</script>
+
+<template>
+  <v-card rounded="lg" elevation="1" border>
+    <v-card-item>
+      <template #prepend>
+        <v-chip color="primary" size="small" label>Home</v-chip>
+      </template>
+      <v-card-title class="text-h5">welcome</v-card-title>
+      <v-card-subtitle>Main public surface</v-card-subtitle>
+    </v-card-item>
+    <v-divider />
+    <v-card-text class="d-flex flex-column ga-4">
+      <div class="d-flex flex-wrap ga-3">
+        <v-chip color="secondary" variant="tonal" label>Route: /home</v-chip>
+        <v-chip color="info" variant="tonal" label>Health: {{ health }}</v-chip>
+      </div>
+      <p class="text-medium-emphasis mb-0">
+        This is your primary landing page. Replace this content with your actual product home.
+      </p>
+      <div class="d-flex flex-wrap ga-3">
+        <v-btn color="primary" variant="flat" to="/console">Open console surface</v-btn>
+        <v-btn color="secondary" variant="outlined" to="/auth/signout">Sign out</v-btn>
+      </div>
+    </v-card-text>
+  </v-card>
+</template>

package/templates/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/templates/src/placement.js

@@ -0,0 +1,12 @@
+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();
+}

package/test/errorRuntime.test.js

@@ -0,0 +1,191 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createErrorRuntime } from "../src/client/error/runtime.js";
+
+function createPresenter(id, {
+  channels = ["snackbar", "banner", "dialog"],
+  calls = []
+} = {}) {
+  const supported = new Set(channels);
+  return Object.freeze({
+    id,
+    supports(channel = "") {
+      return supported.has(String(channel || "").trim().toLowerCase());
+    },
+    present(payload = {}) {
+      calls.push({
+        presenterId: id,
+        payload
+      });
+      return `${id}-${calls.length}`;
+    },
+    dismiss() {
+      return 0;
+    }
+  });
+}
+
+test("error runtime prefers policy presenter over app and module defaults", () => {
+  const calls = [];
+  const runtime = createErrorRuntime({
+    presenters: [
+      createPresenter("module.presenter", { calls }),
+      createPresenter("app.presenter", { calls }),
+      createPresenter("policy.presenter", { calls })
+    ],
+    moduleDefaultPresenterId: "module.presenter"
+  });
+
+  runtime.configure({
+    defaultPresenterId: "app.presenter",
+    policy: () => ({
+      channel: "dialog",
+      presenterId: "policy.presenter",
+      message: "Policy override"
+    })
+  });
+
+  const result = runtime.report({
+    source: "test.runtime",
+    message: "failure"
+  });
+
+  assert.equal(result.decision.presenterId, "policy.presenter");
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].presenterId, "policy.presenter");
+});
+
+test("error runtime uses app default presenter when policy omits presenter", () => {
+  const calls = [];
+  const runtime = createErrorRuntime({
+    presenters: [
+      createPresenter("module.presenter", { calls }),
+      createPresenter("app.presenter", { calls })
+    ],
+    moduleDefaultPresenterId: "module.presenter"
+  });
+
+  runtime.configure({
+    defaultPresenterId: "app.presenter",
+    policy: () => ({
+      channel: "banner",
+      message: "App default"
+    })
+  });
+
+  const result = runtime.report({
+    source: "test.runtime",
+    message: "failure"
+  });
+
+  assert.equal(result.decision.presenterId, "app.presenter");
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].presenterId, "app.presenter");
+});
+
+test("error runtime falls back to module default presenter", () => {
+  const calls = [];
+  const runtime = createErrorRuntime({
+    presenters: [
+      createPresenter("module.presenter", { calls })
+    ],
+    moduleDefaultPresenterId: "module.presenter",
+    policy: () => ({
+      channel: "snackbar",
+      message: "Module default"
+    })
+  });
+
+  const result = runtime.report({
+    source: "test.runtime",
+    message: "failure"
+  });
+
+  assert.equal(result.decision.presenterId, "module.presenter");
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].presenterId, "module.presenter");
+});
+
+test("error runtime fails fast when module default presenter is unresolved", () => {
+  assert.throws(
+    () =>
+      createErrorRuntime({
+        presenters: [createPresenter("registered.presenter")],
+        moduleDefaultPresenterId: "missing.presenter"
+      }),
+    /Module default error presenter "missing.presenter" is not registered/,
+  );
+});
+
+test("error runtime fails fast when app default presenter is unresolved", () => {
+  const runtime = createErrorRuntime({
+    presenters: [createPresenter("module.presenter")],
+    moduleDefaultPresenterId: "module.presenter"
+  });
+
+  assert.throws(
+    () => runtime.setAppDefaultPresenterId("missing.presenter"),
+    /App default error presenter "missing.presenter" is not registered/,
+  );
+});
+
+test("error runtime throws when policy presenter is unknown", () => {
+  const runtime = createErrorRuntime({
+    presenters: [createPresenter("module.presenter")],
+    moduleDefaultPresenterId: "module.presenter",
+    policy: () => ({
+      channel: "dialog",
+      presenterId: "missing.presenter",
+      message: "failure"
+    })
+  });
+
+  assert.throws(
+    () => runtime.report({ source: "test.runtime", message: "failure" }),
+    /Policy-selected error presenter "missing.presenter" is not registered/,
+  );
+});
+
+test("error runtime falls back to a channel-compatible presenter when default presenter does not support channel", () => {
+  const runtime = createErrorRuntime({
+    presenters: [
+      createPresenter("module.presenter"),
+      createPresenter("app.presenter", { channels: ["banner"] })
+    ],
+    moduleDefaultPresenterId: "module.presenter"
+  });
+
+  runtime.configure({
+    defaultPresenterId: "app.presenter",
+    policy: () => ({
+      channel: "dialog",
+      message: "unsupported channel"
+    })
+  });
+
+  const result = runtime.report({ source: "test.runtime", message: "failure" });
+  assert.equal(result.decision.presenterId, "module.presenter");
+});
+
+test("error runtime throws when no presenter supports channel", () => {
+  const runtime = createErrorRuntime({
+    presenters: [
+      createPresenter("module.presenter", { channels: ["snackbar"] }),
+      createPresenter("app.presenter", { channels: ["banner"] })
+    ],
+    moduleDefaultPresenterId: "module.presenter"
+  });
+
+  runtime.configure({
+    defaultPresenterId: "app.presenter",
+    policy: () => ({
+      channel: "dialog",
+      message: "unsupported channel"
+    })
+  });
+
+  assert.throws(
+    () => runtime.report({ source: "test.runtime", message: "failure" }),
+    /No error presenter supports channel "dialog"/,
+  );
+});

package/test/errorStore.test.js

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createErrorPresentationStore } from "../src/client/error/store.js";
+
+test("error presentation store keeps banner channel singleton", () => {
+  const store = createErrorPresentationStore({ now: () => 1000 });
+  const firstId = store.present("banner", { message: "First banner" });
+  const secondId = store.present("banner", { message: "Second banner" });
+
+  const state = store.getState();
+  assert.equal(state.channels.banner.length, 1);
+  assert.equal(state.channels.banner[0].id, secondId);
+  assert.equal(state.channels.banner[0].message, "Second banner");
+  assert.notEqual(firstId, secondId);
+});
+
+test("error presentation store still queues snackbar channel entries", () => {
+  const store = createErrorPresentationStore({ now: () => 1000 });
+  store.present("snackbar", { message: "One" });
+  store.present("snackbar", { message: "Two" });
+
+  const state = store.getState();
+  assert.equal(state.channels.snackbar.length, 2);
+  assert.equal(state.channels.snackbar[0].message, "One");
+  assert.equal(state.channels.snackbar[1].message, "Two");
+});