@jskit-ai/ui-generator 0.1.16 → 0.1.18

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/ui-generator",
-  version: "0.1.16",
+  version: "0.1.18",
   kind: "generator",
   description: "Create non-CRUD pages, reusable UI elements, and subpage hosts.",
   options: {
@@ -40,14 +40,14 @@ export default Object.freeze({
       inputType: "text",
       defaultValue: "",
       promptLabel: "Placement target",
-      promptHint: "Optional host:position target for placed-element placement (defaults to shell-layout:top-right)."
+      promptHint: "Optional target for placed-element placement (format: host:position, default: shell-layout:top-right)."
     },
     "link-placement": {
       required: false,
       inputType: "text",
       defaultValue: "",
       promptLabel: "Link placement",
-      promptHint: "Optional host:position target for the generated page link placement."
+      promptHint: "Optional target for the generated page link placement (format: host:position)."
     },
     "link-component-token": {
       required: false,
@@ -63,15 +63,14 @@ export default Object.freeze({
       defaultValue: "",
       promptLabel: "Link to",
       promptHint:
-        "Optional explicit props.to value for the generated page link placement (example: ./notes). If omitted for pages under a detected parent subpages host, it is inferred from the page path."
+        "Optional explicit props.to value for the generated page link placement (example: ./notes). If omitted for pages under a detected parent subpages target, it is inferred from the page path."
     },
     target: {
       required: false,
       inputType: "text",
       defaultValue: "",
       promptLabel: "Outlet target",
-      promptHint:
-        "Used by add-subpages and outlet. Accepts host or host:position. If only host is given, position defaults to sub-pages."
+      promptHint: "Used by add-subpages and outlet. Must be a target in host:position format."
     },
     title: {
       required: false,
@@ -105,13 +104,14 @@ export default Object.freeze({
     generatorPrimarySubcommand: "page",
     generatorSubcommands: {
       page: {
+        requiresShellWeb: true,
         entrypoint: "src/server/subcommands/page.js",
         export: "runGeneratorSubcommand",
         description: "Create a route page at an explicit target file and add a link placement entry for it.",
         longDescription: [
           "This command always creates one route page file. By default, its page link is placed from the page path itself.",
-          "If an ancestor page has already been enhanced with sub-pages, JSKIT treats that ancestor as the real host. In that case the new page is linked into the nearest parent sub-pages outlet instead of the shell menu.",
-          "That means the generated link normally becomes a tab or child-page link under that ancestor host, and `props.to` is inferred relative to that host. If the host page is `index.vue`, child pages belong under `index/...` so the router keeps the parent page visible while the child route renders underneath it."
+          "If an ancestor page has already been enhanced with sub-pages, JSKIT treats that ancestor outlet as the real placement target. In that case the new page is linked into the nearest parent sub-pages outlet instead of the shell menu.",
+          "That means the generated link normally becomes a tab or child-page link under that ancestor target, and `props.to` is inferred relative to that target. If the outlet page is `index.vue`, child pages belong under `index/...` so the router keeps the parent page visible while the child route renders underneath it."
         ],
         positionalArgs: [
           {
@@ -122,8 +122,8 @@ export default Object.freeze({
         ],
         optionNames: ["name", "link-placement", "link-component-token", "link-to", "force"],
         notes: [
-          "If a nearest parent subpages host is found, placement, link component token, and props.to are inferred automatically.",
-          "If the parent host page is index.vue, child pages belong under index/...",
+          "If a nearest parent subpages target is found, placement, link component token, and props.to are inferred automatically.",
+          "If the parent target page is index.vue, child pages belong under index/...",
           "If the target page file already exists, rerun with --force to overwrite it."
         ],
         examples: [
@@ -147,6 +147,7 @@ export default Object.freeze({
         ]
       },
       "placed-element": {
+        requiresShellWeb: true,
         entrypoint: "src/server/subcommands/element.js",
         export: "runGeneratorSubcommand",
         description: "Create a Vue component file under the chosen component directory (default: src/components) and add a placement entry that renders it.",
@@ -179,6 +180,7 @@ export default Object.freeze({
         ]
       },
       "add-subpages": {
+        requiresShellWeb: true,
         entrypoint: "src/server/subcommands/addSubpages.js",
         export: "runGeneratorSubcommand",
         description: "Upgrade an existing page into a routed subpage host with SectionContainerShell, ShellOutlet, and RouterView.",
@@ -192,7 +194,7 @@ export default Object.freeze({
         optionNames: ["target", "path", "title", "subtitle"],
         notes: [
           "Use this when the page should render shared content plus child routes below it.",
-          "If the host page is index.vue, create child pages under index/..."
+          "If the outlet page is index.vue, create child pages under index/..."
         ],
         examples: [
           {
@@ -218,13 +220,14 @@ export default Object.freeze({
         ]
       },
       outlet: {
+        requiresShellWeb: true,
         entrypoint: "src/server/subcommands/outlet.js",
         export: "runGeneratorSubcommand",
         description: "Inject a generic ShellOutlet block into an existing Vue page/component.",
         longDescription: [
           "A ShellOutlet creates a named placement target inside a Vue file. That target is what other parts of JSKIT render into later.",
-          "After an outlet exists, `jskit list-placements` will discover it and show it as `host:position`. That makes the target visible to humans and to generators that need a placement destination.",
-          "Commands that create placed UI, such as `ui-generator placed-element`, and commands that add page links can then target that outlet by writing placement entries that point at the same `host:position`."
+          "After an outlet exists, `jskit list-placements` will discover it and show its `target`. That makes the outlet visible to humans and to generators that need a placement destination.",
+          "Commands that create placed UI, such as `ui-generator placed-element`, and commands that add page links can then target that outlet by writing placement entries that point at the same target."
         ],
         positionalArgs: [
           {
@@ -236,7 +239,7 @@ export default Object.freeze({
         optionNames: ["target"],
         requiredOptionNames: ["target"],
         notes: [
-          "Use --target host or --target host:position. If only host is given, position defaults to sub-pages."
+          "Use --target host:position."
         ],
         examples: [
           {
@@ -244,7 +247,7 @@ export default Object.freeze({
             lines: [
               "npx jskit generate ui-generator outlet \\",
               "  src/components/ContactSummaryCard.vue \\",
-              "  --target contact-view"
+              "  --target contact-view:sub-pages"
             ]
           },
           {
@@ -274,7 +277,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/users-web": "0.1.48"
+        "@jskit-ai/users-web": "0.1.50"
       },
       dev: {}
     },

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@jskit-ai/ui-generator",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.33"
+    "@jskit-ai/kernel": "0.1.35",
+    "@jskit-ai/shell-web": "0.1.34"
   },
   "exports": {
     "./server/buildTemplateContext": "./src/server/buildTemplateContext.js"

package/src/server/buildTemplateContext.js

@@ -32,11 +32,11 @@ async function buildUiPageTemplateContext({
 
   return {
     __JSKIT_UI_LINK_PLACEMENT_ID__: pageTarget.placementId,
-    __JSKIT_UI_LINK_PLACEMENT_HOST__: String(linkTarget.placementTarget?.host || ""),
-    __JSKIT_UI_LINK_PLACEMENT_POSITION__: String(linkTarget.placementTarget?.position || ""),
+    __JSKIT_UI_LINK_PLACEMENT_TARGET__: String(linkTarget.placementTarget?.id || ""),
     __JSKIT_UI_LINK_COMPONENT_TOKEN__: String(linkTarget.componentToken || ""),
     __JSKIT_UI_LINK_WORKSPACE_SUFFIX__: pageTarget.routeUrlSuffix,
     __JSKIT_UI_LINK_NON_WORKSPACE_SUFFIX__: pageTarget.routeUrlSuffix,
+    __JSKIT_UI_LINK_WHEN_LINE__: String(linkTarget.whenLine || ""),
     __JSKIT_UI_LINK_TO_PROP_LINE__: resolveLinkToPropLine(linkTarget.linkTo)
   };
 }

package/src/server/subcommands/addSubpages.js

@@ -14,10 +14,10 @@ import {
 
 function resolveSubpagesOutletTarget(options = {}, pageTarget = {}) {
   const rawTarget = normalizeText(options?.target);
-  return resolveOutletTargetId(rawTarget || deriveDefaultSubpagesHost(pageTarget), {
+  const defaultTarget = `${deriveDefaultSubpagesHost(pageTarget)}:${DEFAULT_SUBPAGES_POSITION}`;
+  return resolveOutletTargetId(rawTarget || defaultTarget, {
     context: "ui-generator add-subpages",
-    optionName: "target",
-    defaultPosition: DEFAULT_SUBPAGES_POSITION
+    optionName: "target"
   });
 }
 
@@ -52,8 +52,7 @@ async function runGeneratorSubcommand({
   const result = await upgradePageFileToSubpages({
     appRoot,
     targetFile,
-    host: outletTarget.host,
-    position: outletTarget.position,
+    target: outletTarget.id,
     title,
     subtitle,
     componentDirectory,

package/src/server/subcommands/element.js

@@ -135,8 +135,7 @@ async function runGeneratorSubcommand({
     "{\n" +
     "  addPlacement({\n" +
     `    id: "ui-generator.element.${elementNameKebab}",\n` +
-    `    host: "${placementTarget.host}",\n` +
-    `    position: "${placementTarget.position}",\n` +
+    `    target: "${placementTarget.id}",\n` +
     `    surfaces: ["${surface}"],\n` +
     "    order: 155,\n" +
     `    componentToken: "${componentToken}"\n` +

package/src/server/subcommands/outlet.js

@@ -12,25 +12,21 @@ import {
   indentBlock
 } from "./support.js";
 
-const DEFAULT_OUTLET_POSITION = "sub-pages";
-
 const ROUTE_TAG_PATTERN = /<route\b[^>]*>[\s\S]*?<\/route>\s*/gi;
 const TEMPLATE_CLOSE_TAG_PATTERN = /<\/template>/gi;
 const SHELL_OUTLET_TAG_PATTERN = /<ShellOutlet\b([^>]*)\/?>/gi;
 
-function hasShellOutletTarget(source = "", { host = "", position = "" } = {}) {
-  const normalizedHost = normalizeText(host);
-  const normalizedPosition = normalizeText(position);
-  if (!normalizedHost || !normalizedPosition) {
+function hasShellOutletTarget(source = "", { target = "" } = {}) {
+  const normalizedTarget = normalizeText(target);
+  if (!normalizedTarget) {
     return false;
   }
 
   const sourceText = String(source || "");
   for (const match of sourceText.matchAll(SHELL_OUTLET_TAG_PATTERN)) {
     const attributes = parseTagAttributes(match[1]);
-    const outletHost = normalizeText(attributes.host);
-    const outletPosition = normalizeText(attributes.position);
-    if (outletHost === normalizedHost && outletPosition === normalizedPosition) {
+    const outletTarget = normalizeText(attributes.target);
+    if (outletTarget === normalizedTarget) {
       return true;
     }
   }
@@ -75,8 +71,8 @@ function applyScriptImports(source = "") {
   };
 }
 
-function createOutletBlock({ host = "", position = "" } = {}) {
-  return `<ShellOutlet host=\"${host}\" position=\"${position}\" />`;
+function createOutletBlock({ target = "" } = {}) {
+  return `<ShellOutlet target="${target}" />`;
 }
 
 function findLastTemplateCloseTag(source = "") {
@@ -88,9 +84,9 @@ function findLastTemplateCloseTag(source = "") {
   return lastMatch;
 }
 
-function applyOutletTemplateBlock(source = "", { host = "", position = "" } = {}) {
+function applyOutletTemplateBlock(source = "", { target = "" } = {}) {
   const sourceText = String(source || "");
-  const outletBlock = createOutletBlock({ host, position });
+  const outletBlock = createOutletBlock({ target });
 
   const templateTagMatch = findLastTemplateCloseTag(sourceText);
   if (!templateTagMatch) {
@@ -133,10 +129,9 @@ async function runGeneratorSubcommand({
 
   const outletTarget = resolveOutletTargetId(options?.target, {
     context: "ui-generator outlet",
-    optionName: "target",
-    defaultPosition: DEFAULT_OUTLET_POSITION
+    optionName: "target"
   });
-  const { host, position } = outletTarget;
+  const targetId = outletTarget.id;
 
   const targetFilePath = resolvePathWithinApp(appRoot, targetFile, {
     context: "ui-generator outlet"
@@ -154,12 +149,11 @@ async function runGeneratorSubcommand({
     throw new Error(`ui-generator outlet target file not found: ${targetFilePath.relativePath}.`);
   }
 
-  const hasTargetOutlet = hasShellOutletTarget(source, { host, position });
+  const hasTargetOutlet = hasShellOutletTarget(source, { target: targetId });
   const templateApplied = hasTargetOutlet
     ? { changed: false, content: source }
     : applyOutletTemplateBlock(source, {
-      host,
-      position
+      target: targetId
     });
   const scriptApplied = applyScriptImports(templateApplied.content);
 
@@ -171,8 +165,8 @@ async function runGeneratorSubcommand({
   return {
     touchedFiles: changed ? [targetFilePath.relativePath] : [],
     summary: changed
-      ? `Injected outlet \"${host}:${position}\" into ${targetFilePath.relativePath}.`
-      : `Outlet \"${host}:${position}\" is already present in ${targetFilePath.relativePath}.`
+      ? `Injected outlet "${targetId}" into ${targetFilePath.relativePath}.`
+      : `Outlet "${targetId}" is already present in ${targetFilePath.relativePath}.`
   };
 }
 

package/src/server/subcommands/page.js

@@ -25,8 +25,7 @@ function renderPageLinkPlacementBlock({
     "{\n" +
     "  addPlacement({\n" +
     `    id: "${context.__JSKIT_UI_LINK_PLACEMENT_ID__}",\n` +
-    `    host: "${context.__JSKIT_UI_LINK_PLACEMENT_HOST__}",\n` +
-    `    position: "${context.__JSKIT_UI_LINK_PLACEMENT_POSITION__}",\n` +
+    `    target: "${context.__JSKIT_UI_LINK_PLACEMENT_TARGET__}",\n` +
     `    surfaces: ["${surface}"],\n` +
     "    order: 155,\n" +
     `    componentToken: "${context.__JSKIT_UI_LINK_COMPONENT_TOKEN__}",\n` +
@@ -36,7 +35,7 @@ function renderPageLinkPlacementBlock({
     `      workspaceSuffix: "${context.__JSKIT_UI_LINK_WORKSPACE_SUFFIX__}",\n` +
     `      nonWorkspaceSuffix: "${context.__JSKIT_UI_LINK_NON_WORKSPACE_SUFFIX__}",\n` +
     `${context.__JSKIT_UI_LINK_TO_PROP_LINE__}    },\n` +
-    "    when: ({ auth }) => Boolean(auth?.authenticated)\n" +
+    `${String(context.__JSKIT_UI_LINK_WHEN_LINE__ || "")}` +
     "  });\n" +
     "}\n"
   );
@@ -124,6 +123,7 @@ async function runGeneratorSubcommand({
 
   const touchedFileList = [...touchedFiles].sort((left, right) => left.localeCompare(right));
   return {
+    placementComponentTokens: [String(placementContext.__JSKIT_UI_LINK_COMPONENT_TOKEN__ || "").trim()].filter(Boolean),
     touchedFiles: touchedFileList,
     summary: !pageAlreadyExisted
       ? `Generated UI page "${pageTarget.routeUrlSuffix}" at ${pageRelativePath}.`

package/src/server/subcommands/pageSupport.js

@@ -7,6 +7,11 @@ import {
   resolveRequiredAppRoot,
   toPosixPath
 } from "@jskit-ai/kernel/server/support";
+import { normalizeShellOutletTargetId } from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
+import {
+  findLocalLinkItemDefinition,
+  readLocalLinkItemComponentSource
+} from "@jskit-ai/shell-web/server/support/localLinkItemScaffolds";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
   DEFAULT_COMPONENT_DIRECTORY,
@@ -20,8 +25,15 @@ import {
 
 const DEFAULT_SUBPAGES_POSITION = "sub-pages";
 const SECTION_CONTAINER_SHELL_COMPONENT = "SectionContainerShell";
-const TAB_LINK_COMPONENT = "TabLinkItem";
 const TAB_LINK_COMPONENT_TOKEN = "local.main.ui.tab-link-item";
+const DEFAULT_MENU_COMPONENT_DIRECTORY = path.join(DEFAULT_COMPONENT_DIRECTORY, "menus");
+const TAB_LINK_COMPONENT_DEFINITION = findLocalLinkItemDefinition(TAB_LINK_COMPONENT_TOKEN);
+
+if (!TAB_LINK_COMPONENT_DEFINITION) {
+  throw new Error(`ui-generator add-subpages could not resolve ${TAB_LINK_COMPONENT_TOKEN} scaffold definition.`);
+}
+
+const TAB_LINK_COMPONENT = TAB_LINK_COMPONENT_DEFINITION.componentName;
 
 const ROUTE_TAG_PATTERN = /<route\b[^>]*>[\s\S]*?<\/route>\s*/gi;
 const TEMPLATE_TOKEN_PATTERN = /<\/?template\b[^>]*>/gi;
@@ -110,89 +122,6 @@ const hasTabs = computed(() => Boolean(slots.tabs));
 `;
 }
 
-function renderTabLinkItemSource() {
-  return `<script setup>
-import { computed } from "vue";
-import { useRoute } from "vue-router";
-import { usePaths } from "@jskit-ai/users-web/client/composables/usePaths";
-import {
-  normalizeMenuLinkPathname,
-  resolveMenuLinkTarget
-} from "@jskit-ai/users-web/client/support/menuLinkTarget";
-
-const props = defineProps({
-  label: {
-    type: String,
-    default: ""
-  },
-  to: {
-    type: String,
-    default: ""
-  },
-  surface: {
-    type: String,
-    default: ""
-  },
-  workspaceSuffix: {
-    type: String,
-    default: "/"
-  },
-  nonWorkspaceSuffix: {
-    type: String,
-    default: "/"
-  },
-  disabled: {
-    type: Boolean,
-    default: false
-  }
-});
-
-const route = useRoute();
-const paths = usePaths();
-
-const resolvedTo = computed(() => {
-  return resolveMenuLinkTarget({
-    to: props.to,
-    surface: props.surface,
-    currentSurfaceId: paths.currentSurfaceId.value,
-    placementContext: paths.placementContext.value,
-    workspaceSuffix: props.workspaceSuffix,
-    nonWorkspaceSuffix: props.nonWorkspaceSuffix,
-    routeParams: route.params || {},
-    resolvePagePath(relativePath, options = {}) {
-      return paths.page(relativePath, options);
-    }
-  });
-});
-
-const isActive = computed(() => {
-  const targetPathname = normalizeMenuLinkPathname(resolvedTo.value);
-  const currentPathname = normalizeMenuLinkPathname(route.fullPath || route.path);
-  if (!targetPathname || !currentPathname) {
-    return false;
-  }
-  return currentPathname === targetPathname || currentPathname.startsWith(\`\${targetPathname}/\`);
-});
-</script>
-
-<template>
-  <v-btn
-    v-if="resolvedTo"
-    class="tab-link-item text-none"
-    :to="resolvedTo"
-    rounded="pill"
-    size="small"
-    :variant="isActive ? 'flat' : 'tonal'"
-    :color="isActive ? 'primary' : undefined"
-    :disabled="props.disabled"
-    :aria-current="isActive ? 'page' : undefined"
-  >
-    {{ props.label }}
-  </v-btn>
-</template>
-`;
-}
-
 async function ensureSubpagesSupportScaffold({
   appRoot,
   componentDirectory = DEFAULT_COMPONENT_DIRECTORY,
@@ -202,6 +131,10 @@ async function ensureSubpagesSupportScaffold({
     context: "ui-generator add-subpages"
   });
   const normalizedComponentDirectory = normalizeText(componentDirectory) || DEFAULT_COMPONENT_DIRECTORY;
+  const normalizedTabLinkComponentDirectory =
+    normalizedComponentDirectory === DEFAULT_COMPONENT_DIRECTORY
+      ? DEFAULT_MENU_COMPONENT_DIRECTORY
+      : normalizedComponentDirectory;
   const providerPath = resolvePathWithinApp(resolvedAppRoot, MAIN_CLIENT_PROVIDER_FILE, {
     context: "ui-generator add-subpages"
   });
@@ -212,21 +145,34 @@ async function ensureSubpagesSupportScaffold({
   );
   const tabLinkPath = resolvePathWithinApp(
     resolvedAppRoot,
-    path.join(normalizedComponentDirectory, `${TAB_LINK_COMPONENT}.vue`),
+    path.join(normalizedTabLinkComponentDirectory, `${TAB_LINK_COMPONENT}.vue`),
     { context: "ui-generator add-subpages" }
   );
 
+  const providerSource = await readFile(providerPath.absolutePath, "utf8");
+  if (!/\bregisterMainClientComponent\s*\(/.test(providerSource)) {
+    throw new Error(
+      `ui-generator add-subpages could not find registerMainClientComponent() contract in ${MAIN_CLIENT_PROVIDER_FILE}.`
+    );
+  }
+
+  const providerRegisterLine = `registerMainClientComponent("${TAB_LINK_COMPONENT_TOKEN}", () => ${TAB_LINK_COMPONENT});`;
+  const providerHasTabLinkRegistration = providerSource.includes(providerRegisterLine);
   const touchedFiles = new Set();
-  for (const supportFile of [
+  const supportFiles = [
     {
       path: sectionContainerShellPath,
       desiredSource: renderSectionContainerShellSource()
-    },
-    {
-      path: tabLinkPath,
-      desiredSource: renderTabLinkItemSource()
     }
-  ]) {
+  ];
+  if (!providerHasTabLinkRegistration) {
+    supportFiles.push({
+      path: tabLinkPath,
+      desiredSource: await readLocalLinkItemComponentSource(TAB_LINK_COMPONENT_DEFINITION)
+    });
+  }
+
+  for (const supportFile of supportFiles) {
     let alreadyExists = true;
     try {
       await readFile(supportFile.path.absolutePath, "utf8");
@@ -245,15 +191,13 @@ async function ensureSubpagesSupportScaffold({
     touchedFiles.add(supportFile.path.relativePath);
   }
 
-  const providerSource = await readFile(providerPath.absolutePath, "utf8");
-  if (!/\bregisterMainClientComponent\s*\(/.test(providerSource)) {
-    throw new Error(
-      `ui-generator add-subpages could not find registerMainClientComponent() contract in ${MAIN_CLIENT_PROVIDER_FILE}.`
-    );
+  const providerImportLine = `import ${TAB_LINK_COMPONENT} from "/${toPosixPath(path.join(normalizedTabLinkComponentDirectory, `${TAB_LINK_COMPONENT}.vue`))}";`;
+  if (providerHasTabLinkRegistration) {
+    return Object.freeze({
+      touchedFiles: [...touchedFiles].sort((left, right) => left.localeCompare(right)),
+      sectionContainerComponentImportPath: `/${toPosixPath(path.join(normalizedComponentDirectory, `${SECTION_CONTAINER_SHELL_COMPONENT}.vue`))}`
+    });
   }
-
-  const providerImportLine = `import ${TAB_LINK_COMPONENT} from "/${toPosixPath(path.join(normalizedComponentDirectory, `${TAB_LINK_COMPONENT}.vue`))}";`;
-  const providerRegisterLine = `registerMainClientComponent("${TAB_LINK_COMPONENT_TOKEN}", () => ${TAB_LINK_COMPONENT});`;
   const providerImportApplied = insertImportIfMissing(providerSource, providerImportLine);
   const providerRegisterApplied = insertBeforeClassDeclaration(
     providerImportApplied.content,
@@ -358,14 +302,18 @@ function renderSubpagesTemplate({
   bodyContent = "",
   title = "",
   subtitle = "",
-  host = "",
-  position = DEFAULT_SUBPAGES_POSITION
+  target = ""
 } = {}) {
+  const normalizedTarget = normalizeShellOutletTargetId(target);
+  if (!normalizedTarget) {
+    throw new Error("ui-generator add-subpages requires target in \"host:position\" format.");
+  }
+
   const lines = [
     "<template>",
     renderSectionContainerOpenTag({ title, subtitle }),
     "    <template #tabs>",
-    `      <ShellOutlet host="${host}" position="${position}" />`,
+    `      <ShellOutlet target="${normalizedTarget}" default-link-component-token="${TAB_LINK_COMPONENT_TOKEN}" />`,
     "    </template>"
   ];
 
@@ -430,18 +378,16 @@ function applySubpagesScriptImports(source = "", { sectionContainerComponentImpo
 function applySubpagesUpgradeToPageSource(
   source = "",
   {
-    host = "",
-    position = DEFAULT_SUBPAGES_POSITION,
+    target = "",
     title = "",
     subtitle = "",
     sectionContainerComponentImportPath = "/src/components/SectionContainerShell.vue",
     preserveExistingContent = true
   } = {}
 ) {
-  const normalizedHost = normalizeText(host);
-  const normalizedPosition = normalizeText(position) || DEFAULT_SUBPAGES_POSITION;
-  if (!normalizedHost) {
-    throw new Error("ui-generator add-subpages requires a valid host.");
+  const normalizedTarget = normalizeShellOutletTargetId(target);
+  if (!normalizedTarget) {
+    throw new Error('ui-generator add-subpages requires target in "host:position" format.');
   }
 
   const sourceText = String(source || "");
@@ -454,8 +400,7 @@ function applySubpagesUpgradeToPageSource(
     bodyContent,
     title,
     subtitle,
-    host: normalizedHost,
-    position: normalizedPosition
+    target: normalizedTarget
   });
 
   const nextSource = templateBlock
@@ -478,8 +423,7 @@ function hasExistingSubpagesRouting(source = "") {
 async function upgradePageFileToSubpages({
   appRoot,
   targetFile,
-  host = "",
-  position = DEFAULT_SUBPAGES_POSITION,
+  target = "",
   title = "",
   subtitle = "",
   componentDirectory = DEFAULT_COMPONENT_DIRECTORY,
@@ -512,8 +456,7 @@ async function upgradePageFileToSubpages({
   });
 
   const upgradeApplied = applySubpagesUpgradeToPageSource(source, {
-    host,
-    position,
+    target,
     title,
     subtitle,
     sectionContainerComponentImportPath: supportScaffold.sectionContainerComponentImportPath,

package/src/server/subcommands/support.js

@@ -3,6 +3,7 @@ import {
   resolveRequiredAppRoot,
   toPosixPath
 } from "@jskit-ai/kernel/server/support";
+import { 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";
 
@@ -44,32 +45,11 @@ function requireSinglePositionalTargetFile(args = [], { context = "ui-generator"
   return positionalArgs[0];
 }
 
-function normalizeExplicitOutletTargetId(value = "") {
-  const normalizedValue = normalizeText(value);
-  if (!normalizedValue) {
-    return "";
-  }
-
-  const separatorIndex = normalizedValue.indexOf(":");
-  if (separatorIndex <= 0 || separatorIndex >= normalizedValue.length - 1) {
-    return "";
-  }
-
-  const host = normalizeText(normalizedValue.slice(0, separatorIndex));
-  const position = normalizeText(normalizedValue.slice(separatorIndex + 1));
-  if (!host || !position) {
-    return "";
-  }
-
-  return `${host}:${position}`;
-}
-
 function resolveOutletTargetId(
   rawTarget = "",
   {
     context = "ui-generator",
-    optionName = "target",
-    defaultPosition = ""
+    optionName = "target"
   } = {}
 ) {
   const normalizedTarget = normalizeText(rawTarget);
@@ -77,18 +57,13 @@ function resolveOutletTargetId(
     throw new Error(`${context} requires --${optionName}.`);
   }
 
-  const targetId = normalizedTarget.includes(":")
-    ? normalizeExplicitOutletTargetId(normalizedTarget)
-    : normalizeExplicitOutletTargetId(`${normalizedTarget}:${normalizeText(defaultPosition)}`);
+  const targetId = normalizeShellOutletTargetId(normalizedTarget);
   if (!targetId) {
-    throw new Error(`${context} option "${optionName}" must be "host" or "host:position".`);
+    throw new Error(`${context} option "${optionName}" must be a target in "host:position" format.`);
   }
 
-  const separatorIndex = targetId.indexOf(":");
   return Object.freeze({
-    id: targetId,
-    host: targetId.slice(0, separatorIndex),
-    position: targetId.slice(separatorIndex + 1)
+    id: targetId
   });
 }
 
@@ -295,7 +270,6 @@ export {
   toPascalCase,
   requireOption,
   requireSinglePositionalTargetFile,
-  normalizeExplicitOutletTargetId,
   resolveOutletTargetId,
   rejectUnexpectedOptions,
   resolvePathWithinApp,