@jskit-ai/ui-generator 0.1.49 → 0.1.50

package/src/server/subcommands/pageSupport.js

@@ -13,21 +13,27 @@ import {
   readLocalLinkItemComponentSource
 } from "@jskit-ai/shell-web/server/support/localLinkItemScaffolds";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  buildGeneratedUiScreenClassName,
+  resolveGeneratedUiSurfaceProfile
+} from "@jskit-ai/kernel/shared/support/generatedUiContract";
 import {
   DEFAULT_COMPONENT_DIRECTORY,
   MAIN_CLIENT_PROVIDER_FILE,
   resolvePathWithinApp,
   insertImportIfMissing,
   insertBeforeClassDeclaration,
-  findScriptBlock,
+  findScriptSetupBlock,
+  insertScriptSetupBlock,
   indentBlock
 } from "./support.js";
 
 const DEFAULT_SUBPAGES_POSITION = "sub-pages";
 const SECTION_CONTAINER_SHELL_COMPONENT = "SectionContainerShell";
-const SUBPAGES_LINK_COMPONENT_TOKEN = "local.main.ui.surface-aware-menu-link-item";
+const SUBPAGES_LINK_COMPONENT_TOKEN = "local.main.ui.tab-link-item";
 const DEFAULT_MENU_COMPONENT_DIRECTORY = path.join(DEFAULT_COMPONENT_DIRECTORY, "menus");
 const SUBPAGES_LINK_COMPONENT_DEFINITION = findLocalLinkItemDefinition(SUBPAGES_LINK_COMPONENT_TOKEN);
+const OPERATOR_SURFACE_IDS = new Set(["admin", "console"]);
 
 if (!SUBPAGES_LINK_COMPONENT_DEFINITION) {
   throw new Error(`ui-generator add-subpages could not resolve ${SUBPAGES_LINK_COMPONENT_TOKEN} scaffold definition.`);
@@ -35,25 +41,97 @@ if (!SUBPAGES_LINK_COMPONENT_DEFINITION) {
 
 const SUBPAGES_LINK_COMPONENT = SUBPAGES_LINK_COMPONENT_DEFINITION.componentName;
 
-const ROUTE_TAG_PATTERN = /<route\b[^>]*>[\s\S]*?<\/route>\s*/gi;
 const TEMPLATE_TOKEN_PATTERN = /<\/?template\b[^>]*>/gi;
 const SHELL_OUTLET_TAG_PATTERN = /<ShellOutlet\b[^>]*\/?>\s*/gi;
 const ROUTER_VIEW_TAG_PATTERN = /<RouterView\b/i;
 const ROUTER_VIEW_LINE_PATTERN = /^\s*<RouterView(?:\s[^>]*)?\s*\/>\s*$/gm;
 
+function resolveGeneratedPageSurfaceProfile({
+  surfaceId = "",
+  routePath = ""
+} = {}) {
+  const routeSegments = normalizeText(routePath)
+    .replaceAll("\\", "/")
+    .split("/")
+    .map((entry) => normalizeText(entry).toLowerCase())
+    .filter(Boolean);
+  if (routeSegments.includes("settings")) {
+    return "settings";
+  }
+  if (OPERATOR_SURFACE_IDS.has(normalizeText(surfaceId).toLowerCase())) {
+    return "operator";
+  }
+  return "task";
+}
+
 function trimEdgeBlankLines(source = "") {
   return String(source || "")
     .replace(/^\s*\n/, "")
     .replace(/\n\s*$/, "");
 }
 
-function renderPlainPageSource(pageTitle = "") {
+function renderPlainPageSource(pageTitle = "", {
+  surfaceId = "",
+  routePath = ""
+} = {}) {
+  const surfaceProfileId = resolveGeneratedPageSurfaceProfile({ surfaceId, routePath });
+  const surfaceProfile = resolveGeneratedUiSurfaceProfile(surfaceProfileId);
+  const screenClass = buildGeneratedUiScreenClassName("generated-page-screen d-flex flex-column ga-4", {
+    surfaceProfile: surfaceProfileId
+  });
   return `<template>
-  <section class="pa-4">
-    <h1 class="text-h5 mb-2">${pageTitle}</h1>
-    <p class="text-body-2 text-medium-emphasis">Replace this scaffold with your page implementation.</p>
+  <section class="${screenClass}">
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">${surfaceProfile.titleLabel}</p>
+      <h1 class="generated-page-screen__title">${pageTitle}</h1>
+    </header>
+
+    <v-sheet rounded="lg" border class="generated-page-screen__empty-state">
+      <h2 class="text-h6 mb-2">No ${pageTitle} activity yet</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        ${surfaceProfile.emptyStateBody}
+      </p>
+    </v-sheet>
   </section>
 </template>
+
+<style scoped>
+.generated-ui-screen {
+  --generated-ui-screen-title-size: clamp(1.35rem, 2vw, 1.85rem);
+  --generated-ui-screen-panel-padding: 2rem 1.25rem;
+  --generated-ui-screen-panel-align: center;
+}
+
+.generated-ui-screen--operator {
+  --generated-ui-screen-panel-padding: 1.5rem 1rem;
+}
+
+.generated-ui-screen--settings {
+  --generated-ui-screen-panel-padding: 1.5rem 1rem;
+}
+
+.generated-page-screen__title {
+  font-size: var(--generated-ui-screen-title-size);
+  font-weight: 650;
+  letter-spacing: -0.02em;
+  line-height: 1.15;
+  margin: 0;
+}
+
+.generated-page-screen__empty-state {
+  margin-inline: auto;
+  max-width: 34rem;
+  padding: var(--generated-ui-screen-panel-padding);
+  text-align: var(--generated-ui-screen-panel-align);
+  width: 100%;
+}
+
+@media (max-width: 640px) {
+  .generated-ui-screen {
+    --generated-ui-screen-panel-padding: 1.25rem 1rem;
+  }
+}
+</style>
 `;
 }
 
@@ -81,41 +159,50 @@ const hasTabs = computed(() => Boolean(slots.tabs));
 
 <template>
   <section class="section-container-shell d-flex flex-column ga-4">
-    <v-card rounded="lg" elevation="1" border>
-      <v-card-item v-if="hasHeading">
-        <v-card-title v-if="resolvedTitle" class="px-0">{{ resolvedTitle }}</v-card-title>
-        <v-card-subtitle v-if="resolvedSubtitle" class="px-0">{{ resolvedSubtitle }}</v-card-subtitle>
-      </v-card-item>
-      <template v-if="hasTabs">
-        <v-divider v-if="hasHeading" />
-        <v-card-text class="section-container-shell__tabs">
-          <slot name="tabs" />
-        </v-card-text>
-      </template>
-    </v-card>
+    <header v-if="hasHeading" class="section-container-shell__heading">
+      <h1 v-if="resolvedTitle" class="section-container-shell__title">{{ resolvedTitle }}</h1>
+      <p v-if="resolvedSubtitle" class="text-body-2 text-medium-emphasis mb-0">{{ resolvedSubtitle }}</p>
+    </header>
+
+    <v-sheet v-if="hasTabs" rounded="lg" border class="section-container-shell__nav">
+      <slot name="tabs" />
+    </v-sheet>
 
     <slot />
   </section>
 </template>
 
 <style scoped>
-.section-container-shell__tabs {
-  display: flex;
+.section-container-shell__heading {
+  min-width: 0;
+}
+
+.section-container-shell__title {
+  font-size: clamp(1.35rem, 2vw, 1.85rem);
+  font-weight: 650;
+  letter-spacing: -0.02em;
+  line-height: 1.15;
+  margin: 0 0 0.35rem;
+}
+
+.section-container-shell__nav {
   align-items: center;
+  display: flex;
   gap: 0.5rem;
   overflow-x: auto;
-  padding: 0.75rem;
+  padding: 0.5rem;
   scrollbar-width: thin;
 }
 
-.section-container-shell__tabs :deep(.tab-link-item) {
+.section-container-shell__nav :deep(.tab-link-item) {
   flex: 0 0 auto;
+  min-height: 48px;
 }
 
 @media (max-width: 640px) {
-  .section-container-shell__tabs {
+  .section-container-shell__nav {
     gap: 0.375rem;
-    padding: 0.5rem;
+    margin-inline: -0.25rem;
   }
 }
 </style>
@@ -332,7 +419,7 @@ function renderSubpagesTemplate({
 
 function applySubpagesScriptImports(source = "", { sectionContainerComponentImportPath = "" } = {}) {
   const sourceText = String(source || "");
-  const scriptBlock = findScriptBlock(sourceText);
+  const scriptBlock = findScriptSetupBlock(sourceText);
 
   const importLines = [
     "import ShellOutlet from \"@jskit-ai/shell-web/client/components/ShellOutlet\";",
@@ -341,16 +428,7 @@ function applySubpagesScriptImports(source = "", { sectionContainerComponentImpo
   ];
 
   if (!scriptBlock) {
-    const scriptSetupBlock = `<script setup>\n${importLines.join("\n")}\n</script>\n`;
-    let insertionIndex = 0;
-    for (const match of sourceText.matchAll(ROUTE_TAG_PATTERN)) {
-      insertionIndex = match.index + String(match[0] || "").length;
-    }
-    const separator = insertionIndex > 0 ? "\n" : "";
-    return {
-      changed: true,
-      content: `${sourceText.slice(0, insertionIndex)}${separator}${scriptSetupBlock}\n${sourceText.slice(insertionIndex)}`
-    };
+    return insertScriptSetupBlock(sourceText, importLines.join("\n"));
   }
 
   let nextScriptContent = scriptBlock.content;

package/src/server/subcommands/support.js

@@ -1,9 +1,16 @@
 import path from "node:path";
 import {
+  importFreshModuleFromAbsolutePath,
   resolveRequiredAppRoot,
   toPosixPath
 } from "@jskit-ai/kernel/server/support";
-import { normalizeShellOutletTargetId } from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
+import {
+  PLACEMENT_LAYOUT_CLASSES,
+  normalizePlacementOwnerId,
+  normalizePlacementTopologyDefinition,
+  normalizeSemanticPlacementId,
+  normalizeShellOutletTargetId
+} from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { toCamelCase, toSnakeCase } from "@jskit-ai/kernel/shared/support/stringCase";
 
@@ -208,38 +215,132 @@ function insertBeforeClassDeclaration(source = "", line = "", { className = "",
   };
 }
 
-function findScriptBlock(source = "") {
+function findScriptSetupBlock(source = "") {
   const sourceText = String(source || "");
-  let firstMatch = null;
-
   for (const match of sourceText.matchAll(SCRIPT_TAG_PATTERN)) {
-    if (!firstMatch) {
-      firstMatch = match;
-    }
-
     const attributesSource = String(match[1] || "");
-    if (SCRIPT_SETUP_ATTRIBUTE_PATTERN.test(attributesSource)) {
-      return Object.freeze({
-        index: match.index,
-        source: String(match[0] || ""),
-        attributesSource,
-        content: String(match[2] || "")
-      });
+    if (!SCRIPT_SETUP_ATTRIBUTE_PATTERN.test(attributesSource)) {
+      continue;
     }
+
+    return Object.freeze({
+      index: match.index,
+      source: String(match[0] || ""),
+      attributesSource,
+      content: String(match[2] || "")
+    });
   }
 
-  if (!firstMatch) {
-    return null;
+  return null;
+}
+
+function insertScriptSetupBlock(source = "", content = "") {
+  const sourceText = String(source || "");
+  const normalizedContent = String(content || "").trim();
+  if (!normalizedContent) {
+    return {
+      changed: false,
+      content: sourceText
+    };
   }
 
-  return Object.freeze({
-    index: firstMatch.index,
-    source: String(firstMatch[0] || ""),
-    attributesSource: String(firstMatch[1] || ""),
-    content: String(firstMatch[2] || "")
+  const scriptSetupBlock = `<script setup>\n${normalizedContent}\n</script>\n`;
+  let insertionIndex = 0;
+  for (const match of sourceText.matchAll(/<route\b[^>]*>[\s\S]*?<\/route>\s*/gi)) {
+    insertionIndex = match.index + String(match[0] || "").length;
+  }
+  const separator = insertionIndex > 0 ? "\n" : "";
+  return {
+    changed: true,
+    content: `${sourceText.slice(0, insertionIndex)}${separator}${scriptSetupBlock}\n${sourceText.slice(insertionIndex)}`
+  };
+}
+
+async function loadPlacementTopologyDefinitionFromPath(topologyPath = {}, { context = "ui-generator topology" } = {}) {
+  const moduleNamespace = await importFreshModuleFromAbsolutePath(topologyPath.absolutePath);
+  const exported = moduleNamespace?.default;
+  const resolved = typeof exported === "function" ? exported() : exported;
+  return normalizePlacementTopologyDefinition(resolved, {
+    context
   });
 }
 
+function normalizeExpectedTopologyVariantTargets(variantTargets = null) {
+  if (!variantTargets || typeof variantTargets !== "object" || Array.isArray(variantTargets)) {
+    return null;
+  }
+
+  const targets = {};
+  for (const layoutClass of PLACEMENT_LAYOUT_CLASSES) {
+    const target = normalizeShellOutletTargetId(variantTargets[layoutClass]);
+    if (target) {
+      targets[layoutClass] = target;
+    }
+  }
+
+  return Object.keys(targets).length > 0 ? Object.freeze(targets) : null;
+}
+
+function describeTopologyVariantTargets(variantTargets = {}) {
+  return PLACEMENT_LAYOUT_CLASSES
+    .map((layoutClass) => {
+      const target = normalizeShellOutletTargetId(variantTargets?.[layoutClass]);
+      return target ? `${layoutClass}:${target}` : "";
+    })
+    .filter(Boolean)
+    .join(", ");
+}
+
+function placementMatchesExpectedVariantTargets(placement = {}, expectedVariantTargets = null) {
+  if (!expectedVariantTargets) {
+    return true;
+  }
+
+  const variants = placement?.variants && typeof placement.variants === "object" ? placement.variants : {};
+  return Object.entries(expectedVariantTargets).every(([layoutClass, expectedTarget]) =>
+    normalizeShellOutletTargetId(variants?.[layoutClass]?.outlet) === expectedTarget
+  );
+}
+
+async function appendTopologyBlockIfPlacementMissing({
+  topologyPath = {},
+  source = "",
+  marker = "",
+  block = "",
+  placementId = "",
+  owner = "",
+  variantTargets = null,
+  context = "ui-generator topology"
+} = {}) {
+  const normalizedPlacementId = normalizeSemanticPlacementId(placementId);
+  const normalizedOwner = normalizePlacementOwnerId(owner);
+  if (!normalizedPlacementId) {
+    throw new Error(`${context} requires semantic placement id in "area.slot" format.`);
+  }
+
+  const topology = await loadPlacementTopologyDefinitionFromPath(topologyPath, { context });
+  const existingPlacement = (Array.isArray(topology.placements) ? topology.placements : []).find(
+    (placement) => placement.id === normalizedPlacementId && (placement.owner || "") === normalizedOwner
+  );
+  if (existingPlacement) {
+    const expectedVariantTargets = normalizeExpectedTopologyVariantTargets(variantTargets);
+    if (!placementMatchesExpectedVariantTargets(existingPlacement, expectedVariantTargets)) {
+      const ownerLabel = normalizedOwner ? ` for owner "${normalizedOwner}"` : "";
+      throw new Error(
+        `${context} semantic placement "${normalizedPlacementId}"${ownerLabel} already exists with different outlet mapping. ` +
+        `Existing: ${describeTopologyVariantTargets(existingPlacement.variants)}. ` +
+        `Requested: ${describeTopologyVariantTargets(expectedVariantTargets)}.`
+      );
+    }
+    return {
+      changed: false,
+      content: String(source || "")
+    };
+  }
+
+  return appendBlockIfMarkerMissing(source, marker, block);
+}
+
 function parseTagAttributes(attributesSource = "") {
   const attributes = {};
   const source = String(attributesSource || "");
@@ -279,7 +380,9 @@ export {
   appendBlockIfMarkerMissing,
   insertImportIfMissing,
   insertBeforeClassDeclaration,
-  findScriptBlock,
+  findScriptSetupBlock,
+  insertScriptSetupBlock,
+  appendTopologyBlockIfPlacementMissing,
   parseTagAttributes,
   indentBlock
 };

package/test/addSubpagesSubcommand.test.js

@@ -113,7 +113,7 @@ test("ui-generator add-subpages derives the default target from an index-route p
 
     assert.deepEqual(result.touchedFiles, [
       "packages/main/src/client/providers/MainClientProvider.js",
-      "src/components/menus/SurfaceAwareMenuLinkItem.vue",
+      "src/components/menus/TabLinkItem.vue",
       "src/components/SectionContainerShell.vue",
       `src/pages/${targetFile}`,
       "src/placementTopology.js"
@@ -130,10 +130,11 @@ test("ui-generator add-subpages derives the default target from an index-route p
     assert.match(topologySource, /compact: \{/);
     assert.match(topologySource, /medium: \{/);
     assert.match(topologySource, /expanded: \{/);
+    assert.match(topologySource, /link: "local\.main\.ui\.tab-link-item"/);
     assert.match(pageSource, /<RouterView \/>/);
     assert.equal(
-      await readFile(path.join(appRoot, "src", "components", "menus", "SurfaceAwareMenuLinkItem.vue"), "utf8"),
-      await readLocalLinkItemComponentSource("local.main.ui.surface-aware-menu-link-item")
+      await readFile(path.join(appRoot, "src", "components", "menus", "TabLinkItem.vue"), "utf8"),
+      await readLocalLinkItemComponentSource("local.main.ui.tab-link-item")
     );
   });
 });
@@ -227,6 +228,41 @@ test("ui-generator add-subpages supports explicit target host:position", async (
   });
 });
 
+test("ui-generator add-subpages creates script setup instead of adding template imports to normal script", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    await writePageFile(
+      appRoot,
+      targetFile,
+      `<script>
+export default {
+  name: "PracticePage"
+};
+</script>
+
+<template>
+  <section>Practice</section>
+</template>
+`
+    );
+
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "add-subpages",
+      args: [targetFile],
+      options: {}
+    });
+
+    const pageSource = await readPageFile(appRoot, targetFile);
+    assert.match(pageSource, /<script setup>\nimport ShellOutlet from "@jskit-ai\/shell-web\/client\/components\/ShellOutlet";/);
+    assert.match(pageSource, /import \{ RouterView \} from "vue-router";/);
+    assert.match(pageSource, /import SectionContainerShell from "\/src\/components\/SectionContainerShell\.vue";/);
+    assert.match(pageSource, /<script>\nexport default/);
+  });
+});
+
 test("ui-generator add-subpages does not rewrite existing scaffold support components", async () => {
   await withTempApp(async (appRoot) => {
     await writeAppFixture(appRoot);
@@ -234,7 +270,7 @@ test("ui-generator add-subpages does not rewrite existing scaffold support compo
     const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
     await writePageFile(appRoot, targetFile);
     const customSectionShellSource = `<template><section class="custom-shell"><slot /></section></template>\n`;
-    const customSurfaceAwareLinkSource = `<template><button class="custom-surface-aware-link"><slot /></button></template>\n`;
+    const customTabLinkSource = `<template><button class="custom-tab-link"><slot /></button></template>\n`;
     await writeFile(
       path.join(appRoot, "src", "components", "SectionContainerShell.vue"),
       customSectionShellSource,
@@ -242,8 +278,8 @@ test("ui-generator add-subpages does not rewrite existing scaffold support compo
     );
     await mkdir(path.join(appRoot, "src", "components", "menus"), { recursive: true });
     await writeFile(
-      path.join(appRoot, "src", "components", "menus", "SurfaceAwareMenuLinkItem.vue"),
-      customSurfaceAwareLinkSource,
+      path.join(appRoot, "src", "components", "menus", "TabLinkItem.vue"),
+      customTabLinkSource,
       "utf8"
     );
 
@@ -266,9 +302,97 @@ test("ui-generator add-subpages does not rewrite existing scaffold support compo
       customSectionShellSource
     );
     assert.equal(
-      await readFile(path.join(appRoot, "src", "components", "menus", "SurfaceAwareMenuLinkItem.vue"), "utf8"),
-      customSurfaceAwareLinkSource
+      await readFile(path.join(appRoot, "src", "components", "menus", "TabLinkItem.vue"), "utf8"),
+      customTabLinkSource
+    );
+  });
+});
+
+test("ui-generator add-subpages validates topology before changing page or support files", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    const originalPageSource = "<template><section>Practice</section></template>\n";
+    await writePageFile(appRoot, targetFile, originalPageSource);
+    const providerPath = path.join(appRoot, "packages", "main", "src", "client", "providers", "MainClientProvider.js");
+    const originalProviderSource = await readFile(providerPath, "utf8");
+    await writeFile(
+      path.join(appRoot, "src", "placementTopology.js"),
+      `export default {
+  placements: [
+    {
+      id: "page.section-nav",
+      owner: "practice",
+      variants: {}
+    }
+  ]
+};
+`,
+      "utf8"
     );
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "add-subpages",
+        args: [targetFile],
+        options: {}
+      }),
+      /requires compact topology variant/
+    );
+
+    assert.equal(await readPageFile(appRoot, targetFile), originalPageSource);
+    assert.equal(await readFile(providerPath, "utf8"), originalProviderSource);
+    await assert.rejects(
+      readFile(path.join(appRoot, "src", "components", "SectionContainerShell.vue"), "utf8"),
+      /ENOENT/
+    );
+    await assert.rejects(
+      readFile(path.join(appRoot, "src", "components", "menus", "TabLinkItem.vue"), "utf8"),
+      /ENOENT/
+    );
+  });
+});
+
+test("ui-generator add-subpages rejects existing section-nav topology for a different outlet", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
+    const originalPageSource = "<template><section>Practice</section></template>\n";
+    await writePageFile(appRoot, targetFile, originalPageSource);
+    await writeFile(
+      path.join(appRoot, "src", "placementTopology.js"),
+      `export default {
+  placements: [
+    {
+      id: "page.section-nav",
+      owner: "practice",
+      surfaces: ["admin"],
+      variants: {
+        compact: { outlet: "practice:existing-tabs" },
+        medium: { outlet: "practice:existing-tabs" },
+        expanded: { outlet: "practice:existing-tabs" }
+      }
+    }
+  ]
+};
+`,
+      "utf8"
+    );
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "add-subpages",
+        args: [targetFile],
+        options: {}
+      }),
+      /semantic placement "page\.section-nav" for owner "practice" already exists with different outlet mapping/
+    );
+
+    assert.equal(await readPageFile(appRoot, targetFile), originalPageSource);
   });
 });
 

package/test/buildTemplateContext.test.js

@@ -90,6 +90,12 @@ async function writePlacementTopology(appRoot, entries = []) {
       surfaces: ["*"],
       outlet: "shell-layout:top-right",
       linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+    }),
+    renderTopologyEntry({
+      id: "shell.global-actions",
+      surfaces: ["*"],
+      outlet: "shell-layout:top-right",
+      linkRenderer: "local.main.ui.surface-aware-menu-link-item"
     })
   ];
   await writeFileInApp(
@@ -186,6 +192,31 @@ test("buildUiPageTemplateContext supports explicit link placement override", asy
   });
 });
 
+test("buildUiPageTemplateContext maps utility navigation role to global actions", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+
+    const context = await buildUiPageTemplateContext({
+      appRoot,
+      targetFile: "admin/help/index.vue",
+      options: {
+        "navigation-role": "utility"
+      }
+    });
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "shell.global-actions");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "");
+  });
+});
+
 test("buildUiPageTemplateContext supports explicit package semantic link placement", async () => {
   await withTempApp(async (appRoot) => {
     await writeConfig(

package/test/elementSubcommand.test.js

@@ -3,6 +3,7 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { tmpdir } from "node:os";
 import test from "node:test";
+import { assertGeneratedUiSourceContract } from "@jskit-ai/kernel/shared/support/generatedUiContract";
 import { runGeneratorSubcommand } from "../src/server/subcommands/element.js";
 
 async function withTempApp(run) {
@@ -175,6 +176,16 @@ test("ui-generator placed-element subcommand creates component and outlet placem
     assert.match(providerSource, /import OpsPanelElement from "\/src\/components\/OpsPanelElement\.vue";/);
     assert.match(providerSource, /registerMainClientComponent\("local\.main\.ui\.element\.ops-panel", \(\) => OpsPanelElement\);/);
 
+    const componentSource = await readFile(path.join(appRoot, "src", "components", "OpsPanelElement.vue"), "utf8");
+    assertGeneratedUiSourceContract(componentSource, {
+      profile: "placed-element",
+      sourceName: "OpsPanelElement.vue"
+    });
+    assert.match(componentSource, /class="generated-element-panel"/);
+    assert.match(componentSource, /<h2 class="text-subtitle-1 font-weight-medium mb-0">Ops Panel<\/h2>/);
+    assert.match(componentSource, /<v-chip color="primary" variant="tonal" size="small">Ready<\/v-chip>/);
+    assert.doesNotMatch(componentSource, /Replace this scaffold|Use this area|This is your page/);
+
     const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
     assert.match(placementSource, /id: "ui-generator\.element\.ops-panel"/);
     assert.match(placementSource, /target: "shell\.status"/);
@@ -350,7 +361,8 @@ test("ui-generator placed-element subcommand overwrites an existing component wh
     ]);
 
     const componentSource = await readFile(path.join(appRoot, "src", "components", "OpsPanelElement.vue"), "utf8");
-    assert.match(componentSource, /<h2 class="text-h6 mb-2">Ops Panel<\/h2>/);
+    assert.match(componentSource, /<h2 class="text-subtitle-1 font-weight-medium mb-0">Ops Panel<\/h2>/);
+    assert.doesNotMatch(componentSource, /custom/);
   });
 });