@jskit-ai/shell-web 0.1.4

package/package.descriptor.mjs

@@ -0,0 +1,165 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/shell-web",
+  version: "0.1.4",
+  description: "Web shell layout runtime with outlet-based placement contributions.",
+  dependsOn: [],
+  capabilities: {
+    provides: [
+      "runtime.web-placement",
+      "runtime.web-error"
+    ],
+    requires: []
+  },
+  runtime: {
+    server: {
+      providers: []
+    },
+    client: {
+      providers: [
+        {
+          entrypoint: "src/client/providers/ShellWebClientProvider.js",
+          export: "ShellWebClientProvider"
+        }
+      ]
+    }
+  },
+  metadata: {
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./client",
+          summary: "Exports shell layout/outlet/error-host components and ShellWebClientProvider."
+        },
+        {
+          subpath: "./client/placement",
+          summary: "Exports placement registry, placement context access, runtime token, and surface path helpers."
+        },
+        {
+          subpath: "./client/error",
+          summary: "Exports default error policy and runtime error reporter hook."
+        }
+      ],
+      containerTokens: {
+        server: [],
+        client: [
+          "runtime.web-placement.client",
+          "runtime.web-error.client",
+          "runtime.web-error.presentation-store.client"
+        ]
+      }
+    },
+    ui: {
+      placements: {
+        outlets: [
+          {
+            host: "shell-layout",
+            position: "top-left",
+            surfaces: ["*"],
+            source: "src/client/components/ShellLayout.vue"
+          },
+          {
+            host: "shell-layout",
+            position: "top-right",
+            surfaces: ["*"],
+            source: "src/client/components/ShellLayout.vue"
+          },
+          {
+            host: "shell-layout",
+            position: "primary-menu",
+            surfaces: ["*"],
+            source: "src/client/components/ShellLayout.vue"
+          },
+          {
+            host: "shell-layout",
+            position: "secondary-menu",
+            surfaces: ["*"],
+            source: "src/client/components/ShellLayout.vue"
+          }
+        ],
+        contributions: []
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@tanstack/vue-query": "^5.90.5",
+        "@jskit-ai/kernel": "0.1.4",
+        "vuetify": "^4.0.0"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {
+        "dev:all": "vite",
+        "dev:home": "VITE_SURFACE=home vite",
+        "dev:console": "VITE_SURFACE=console vite"
+      }
+    },
+    procfile: {},
+    text: [],
+    files: [
+      {
+        from: "templates/src/App.vue",
+        to: "src/App.vue",
+        reason: "Install full-width shell app root with shell-web error host and edge-to-edge layout.",
+        category: "shell-web",
+        id: "shell-web-app-root"
+      },
+      {
+        from: "templates/src/components/ShellLayout.vue",
+        to: "src/components/ShellLayout.vue",
+        reason: "Install app-owned shell layout component so apps can customize structure and slots.",
+        category: "shell-web",
+        id: "shell-web-component-shell-layout"
+      },
+      {
+        from: "templates/src/error.js",
+        to: "src/error.js",
+        reason: "Install app-owned error runtime policy and presenter config scaffold.",
+        category: "shell-web",
+        id: "shell-web-error-config"
+      },
+      {
+        from: "templates/src/placement.js",
+        to: "src/placement.js",
+        reason: "Install app-owned placement registry scaffold used by shell-web placement runtime.",
+        category: "shell-web",
+        id: "shell-web-placement-registry"
+      },
+      {
+        from: "templates/src/pages/home.vue",
+        toSurface: "home",
+        toSurfaceRoot: true,
+        reason: "Install shell-driven home wrapper page.",
+        category: "shell-web",
+        id: "shell-web-page-home-wrapper"
+      },
+      {
+        from: "templates/src/pages/home/index.vue",
+        toSurface: "home",
+        toSurfacePath: "index.vue",
+        reason: "Install shell-driven home surface starter page.",
+        category: "shell-web",
+        id: "shell-web-page-home"
+      },
+      {
+        from: "templates/src/pages/console.vue",
+        toSurface: "console",
+        toSurfaceRoot: true,
+        reason: "Install shell-driven console wrapper page.",
+        category: "shell-web",
+        id: "shell-web-page-console-wrapper"
+      },
+      {
+        from: "templates/src/pages/console/index.vue",
+        toSurface: "console",
+        toSurfacePath: "index.vue",
+        reason: "Install shell-driven console page starter.",
+        category: "shell-web",
+        id: "shell-web-page-console"
+      }
+    ]
+  }
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@jskit-ai/shell-web",
+  "version": "0.1.4",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    "./client": "./src/client/index.js",
+    "./client/error": "./src/client/error/index.js",
+    "./client/placement": "./src/client/placement/index.js",
+    "./client/navigation/linkResolver": "./src/client/navigation/linkResolver.js",
+    "./client/components/ShellLayout": "./src/client/components/ShellLayout.vue",
+    "./client/components/ShellOutlet": "./src/client/components/ShellOutlet.vue",
+    "./client/components/ShellErrorHost": "./src/client/components/ShellErrorHost.vue",
+    "./client/providers/ShellWebClientProvider": "./src/client/providers/ShellWebClientProvider.js"
+  },
+  "dependencies": {
+    "@tanstack/vue-query": "^5.90.5",
+    "@jskit-ai/kernel": "0.1.4",
+    "vuetify": "^4.0.0"
+  }
+}

package/src/client/components/ShellErrorHost.vue

@@ -0,0 +1,208 @@
+<script setup>
+import { computed } from "vue";
+import {
+  useShellWebErrorPresentationState,
+  useShellWebErrorRuntime
+} from "../error/inject.js";
+
+const runtime = useShellWebErrorRuntime();
+const {
+  state,
+  store
+} = useShellWebErrorPresentationState();
+
+const snackbarEntry = computed(() => state.value.channels.snackbar[0] || null);
+const bannerEntries = computed(() => state.value.channels.banner || []);
+const dialogEntry = computed(() => state.value.channels.dialog[0] || null);
+
+function resolveSeverityColor(severity = "error") {
+  const normalized = String(severity || "error").trim().toLowerCase();
+  if (normalized === "info") {
+    return "info";
+  }
+  if (normalized === "success") {
+    return "success";
+  }
+  if (normalized === "warning") {
+    return "warning";
+  }
+  return "error";
+}
+
+function resolveTimeout(entry) {
+  if (!entry) {
+    return -1;
+  }
+  if (entry.persist) {
+    return -1;
+  }
+  return 5000;
+}
+
+function dismiss(entry) {
+  if (!entry || !entry.channel || !entry.id) {
+    return;
+  }
+
+  store.dismiss(entry.channel, entry.id);
+}
+
+function runAction(entry) {
+  if (!entry || !entry.action || typeof entry.action.handler !== "function") {
+    return;
+  }
+
+  try {
+    entry.action.handler(entry);
+  } catch (error) {
+    runtime.report({
+      source: "shell-web.error-host.action",
+      message: "Error action failed.",
+      cause: error,
+      severity: "error",
+      channel: "dialog"
+    });
+  }
+
+  if (entry.action.dismissOnRun !== false) {
+    dismiss(entry);
+  }
+}
+
+function onSnackbarModelValue(nextValue) {
+  if (nextValue === false && snackbarEntry.value) {
+    dismiss(snackbarEntry.value);
+  }
+}
+
+function onDialogModelValue(nextValue) {
+  if (nextValue === false && dialogEntry.value && dialogEntry.value.persist !== true) {
+    dismiss(dialogEntry.value);
+  }
+}
+</script>
+
+<template>
+  <div class="shell-error-host" aria-live="polite">
+    <div v-if="bannerEntries.length > 0" class="shell-error-host__banners">
+      <div class="shell-error-host__banner-stack">
+        <v-alert
+          v-for="entry in bannerEntries"
+          :key="entry.id"
+          :type="resolveSeverityColor(entry.severity)"
+          variant="elevated"
+          density="comfortable"
+          rounded="lg"
+          border="start"
+          class="shell-error-host__banner"
+          closable
+          @click:close="dismiss(entry)"
+        >
+          <div class="d-flex align-center ga-3 flex-wrap">
+            <span>{{ entry.message }}</span>
+            <v-spacer />
+            <v-btn
+              v-if="entry.action"
+              variant="text"
+              size="small"
+              class="text-none"
+              @click="runAction(entry)"
+            >
+              {{ entry.action.label }}
+            </v-btn>
+          </div>
+        </v-alert>
+      </div>
+    </div>
+
+    <v-snackbar
+      :model-value="Boolean(snackbarEntry)"
+      location="bottom end"
+      :timeout="resolveTimeout(snackbarEntry)"
+      :color="resolveSeverityColor(snackbarEntry?.severity)"
+      @update:model-value="onSnackbarModelValue"
+    >
+      <span v-if="snackbarEntry">{{ snackbarEntry.message }}</span>
+
+      <template #actions>
+        <v-btn
+          v-if="snackbarEntry?.action"
+          variant="text"
+          size="small"
+          @click="runAction(snackbarEntry)"
+        >
+          {{ snackbarEntry.action.label }}
+        </v-btn>
+        <v-btn
+          v-if="snackbarEntry"
+          variant="text"
+          size="small"
+          @click="dismiss(snackbarEntry)"
+        >
+          Dismiss
+        </v-btn>
+      </template>
+    </v-snackbar>
+
+    <v-dialog
+      :model-value="Boolean(dialogEntry)"
+      max-width="560"
+      :persistent="Boolean(dialogEntry?.persist)"
+      @update:model-value="onDialogModelValue"
+    >
+      <v-card v-if="dialogEntry">
+        <v-card-title class="text-subtitle-1">Attention required</v-card-title>
+        <v-card-text>{{ dialogEntry.message }}</v-card-text>
+        <v-card-actions>
+          <v-spacer />
+          <v-btn
+            v-if="dialogEntry.action"
+            variant="text"
+            @click="runAction(dialogEntry)"
+          >
+            {{ dialogEntry.action.label }}
+          </v-btn>
+          <v-btn
+            color="primary"
+            variant="tonal"
+            @click="dismiss(dialogEntry)"
+          >
+            Close
+          </v-btn>
+        </v-card-actions>
+      </v-card>
+    </v-dialog>
+  </div>
+</template>
+
+<style scoped>
+.shell-error-host__banners {
+  position: fixed;
+  top: calc(env(safe-area-inset-top, 0px) + var(--shell-error-banner-offset, 64px));
+  left: 0;
+  right: 0;
+  z-index: 2600;
+  pointer-events: none;
+  padding: 10px 12px;
+}
+
+.shell-error-host__banner-stack {
+  margin: 0 auto;
+  width: min(1120px, 100%);
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.shell-error-host__banner {
+  pointer-events: auto;
+  box-shadow: var(--v-shadow-4);
+}
+
+@media (max-width: 600px) {
+  .shell-error-host__banners {
+    top: calc(env(safe-area-inset-top, 0px) + var(--shell-error-banner-offset-mobile, 56px));
+    padding: 8px;
+  }
+}
+</style>

package/src/client/components/ShellLayout.vue

@@ -0,0 +1,191 @@
+<script setup>
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface";
+import { useWebPlacementContext } from "../placement/inject.js";
+import {
+  readPlacementSurfaceConfig,
+  resolveSurfaceDefinitionFromPlacementContext,
+  resolveSurfaceIdFromPlacementPathname
+} from "../placement/surfaceContext.js";
+import { useShellLayout } from "./useShellLayout.js";
+import ShellOutlet from "./ShellOutlet.vue";
+
+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: () => []
+  }
+});
+
+let route = null;
+try {
+  route = useRoute();
+} catch {
+  route = null;
+}
+const { context: placementContext } = useWebPlacementContext();
+
+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(" ");
+}
+
+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 { drawerOpen, resolvedTopLeftActions, resolvedTopRightActions, resolvedMenuItems, toggleDrawer } = useShellLayout({
+  topLeftActions: computed(() => props.topLeftActions),
+  topRightActions: computed(() => props.topRightActions),
+  menuItems: computed(() => 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/src/client/components/ShellOutlet.vue

@@ -0,0 +1,95 @@
+<script setup>
+import {
+  computed,
+  onBeforeUnmount,
+  onMounted,
+  ref
+} from "vue";
+import { useRoute } from "vue-router";
+import { useWebPlacementContext, useWebPlacementRuntime } from "../placement/inject.js";
+import { resolveRuntimePathname } from "../placement/pathname.js";
+import {
+  readPlacementSurfaceConfig,
+  resolveSurfaceIdFromPlacementPathname
+} from "../placement/surfaceContext.js";
+
+const props = defineProps({
+  host: {
+    type: String,
+    default: ""
+  },
+  position: {
+    type: String,
+    default: ""
+  },
+  context: {
+    type: Object,
+    default: () => ({})
+  }
+});
+
+let route = null;
+try {
+  route = useRoute();
+} catch {
+  route = null;
+}
+
+const placementRuntime = useWebPlacementRuntime();
+const { context: placementContext } = useWebPlacementContext();
+const revision = ref(
+  typeof placementRuntime.getRevision === "function" ? placementRuntime.getRevision() : 0
+);
+let unsubscribe = null;
+
+onMounted(() => {
+  if (typeof placementRuntime.subscribe !== "function") {
+    return;
+  }
+  unsubscribe = placementRuntime.subscribe((event) => {
+    const next = Number(event?.revision);
+    revision.value = Number.isInteger(next) ? next : revision.value + 1;
+  });
+});
+
+onBeforeUnmount(() => {
+  if (typeof unsubscribe === "function") {
+    unsubscribe();
+    unsubscribe = null;
+  }
+});
+
+const resolvedSurface = computed(() => {
+  const contextValue = placementContext?.value || null;
+  const pathname = resolveRuntimePathname(route?.path);
+  const surfaceFromPathname = resolveSurfaceIdFromPlacementPathname(contextValue, pathname);
+  if (surfaceFromPathname) {
+    return surfaceFromPathname;
+  }
+
+  const surfaceConfig = readPlacementSurfaceConfig(contextValue);
+  if (surfaceConfig.defaultSurfaceId) {
+    return surfaceConfig.defaultSurfaceId;
+  }
+  return "*";
+});
+
+const placements = computed(() => {
+  void revision.value;
+  return placementRuntime.getPlacements({
+    surface: resolvedSurface.value,
+    host: props.host,
+    position: props.position,
+    context: props.context
+  });
+});
+</script>
+
+<template>
+  <component
+    :is="entry.component"
+    v-for="entry in placements"
+    :key="entry.id"
+    v-bind="entry.props"
+  />
+</template>