@jskit-ai/ui-generator 0.1.15 → 0.1.17

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,

package/test/addSubpagesSubcommand.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 { readLocalLinkItemComponentSource } from "@jskit-ai/shell-web/server/support/localLinkItemScaffolds";
 import { runGeneratorSubcommand } from "../src/server/subcommands/addSubpages.js";
 
 async function withTempApp(run) {
@@ -105,14 +106,21 @@ 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/TabLinkItem.vue",
       "src/components/SectionContainerShell.vue",
-      "src/components/TabLinkItem.vue",
       `src/pages/${targetFile}`
     ]);
 
     const pageSource = await readPageFile(appRoot, targetFile);
-    assert.match(pageSource, /<ShellOutlet host="practice" position="sub-pages" \/>/);
+    assert.match(
+      pageSource,
+      /<ShellOutlet target="practice:sub-pages" default-link-component-token="local\.main\.ui\.tab-link-item" \/>/
+    );
     assert.match(pageSource, /<RouterView \/>/);
+    assert.equal(
+      await readFile(path.join(appRoot, "src", "components", "menus", "TabLinkItem.vue"), "utf8"),
+      await readLocalLinkItemComponentSource("local.main.ui.tab-link-item")
+    );
   });
 });
 
@@ -131,7 +139,10 @@ test("ui-generator add-subpages derives the default target from a dynamic file-r
     });
 
     const pageSource = await readPageFile(appRoot, targetFile);
-    assert.match(pageSource, /<ShellOutlet host="contacts-contact-id" position="sub-pages" \/>/);
+    assert.match(
+      pageSource,
+      /<ShellOutlet target="contacts-contact-id:sub-pages" default-link-component-token="local\.main\.ui\.tab-link-item" \/>/
+    );
   });
 });
 
@@ -150,28 +161,31 @@ test("ui-generator add-subpages derives the default target from a nested route p
     });
 
     const pageSource = await readPageFile(appRoot, targetFile);
-    assert.match(pageSource, /<ShellOutlet host="catalog-products" position="sub-pages" \/>/);
+    assert.match(
+      pageSource,
+      /<ShellOutlet target="catalog-products:sub-pages" default-link-component-token="local\.main\.ui\.tab-link-item" \/>/
+    );
   });
 });
 
-test("ui-generator add-subpages supports explicit target host shorthand", async () => {
+test("ui-generator add-subpages rejects explicit target shorthand without a position", async () => {
   await withTempApp(async (appRoot) => {
     await writeAppFixture(appRoot);
 
     const targetFile = "w/[workspaceSlug]/admin/practice/index.vue";
     await writePageFile(appRoot, targetFile);
 
-    await runGeneratorSubcommand({
-      appRoot,
-      subcommand: "add-subpages",
-      args: [targetFile],
-      options: {
-        target: "practice-hub"
-      }
-    });
-
-    const pageSource = await readPageFile(appRoot, targetFile);
-    assert.match(pageSource, /<ShellOutlet host="practice-hub" position="sub-pages" \/>/);
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "add-subpages",
+        args: [targetFile],
+        options: {
+          target: "practice-hub"
+        }
+      }),
+      /option "target" must be a target in "host:position" format/
+    );
   });
 });
 
@@ -192,7 +206,10 @@ test("ui-generator add-subpages supports explicit target host:position", async (
     });
 
     const pageSource = await readPageFile(appRoot, targetFile);
-    assert.match(pageSource, /<ShellOutlet host="practice-hub" position="secondary-tabs" \/>/);
+    assert.match(
+      pageSource,
+      /<ShellOutlet target="practice-hub:secondary-tabs" default-link-component-token="local\.main\.ui\.tab-link-item" \/>/
+    );
   });
 });
 
@@ -209,8 +226,9 @@ test("ui-generator add-subpages does not rewrite existing scaffold support compo
       customSectionShellSource,
       "utf8"
     );
+    await mkdir(path.join(appRoot, "src", "components", "menus"), { recursive: true });
     await writeFile(
-      path.join(appRoot, "src", "components", "TabLinkItem.vue"),
+      path.join(appRoot, "src", "components", "menus", "TabLinkItem.vue"),
       customTabLinkSource,
       "utf8"
     );
@@ -233,7 +251,7 @@ test("ui-generator add-subpages does not rewrite existing scaffold support compo
       customSectionShellSource
     );
     assert.equal(
-      await readFile(path.join(appRoot, "src", "components", "TabLinkItem.vue"), "utf8"),
+      await readFile(path.join(appRoot, "src", "components", "menus", "TabLinkItem.vue"), "utf8"),
       customTabLinkSource
     );
   });
@@ -299,7 +317,7 @@ test("ui-generator add-subpages validates target format", async () => {
           target: "practice:"
         }
       }),
-      /option "target" must be "host" or "host:position"/
+      /option "target" must be a target in "host:position" format/
     );
   });
 });

package/test/buildTemplateContext.test.js

@@ -31,8 +31,12 @@ async function writeShellLayout(appRoot, source = "") {
     source ||
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="top-right" />
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
+    <ShellOutlet target="shell-layout:top-right" />
+    <ShellOutlet
+      target="shell-layout:primary-menu"
+      default
+      default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+    />
   </div>
 </template>
 `
@@ -57,16 +61,44 @@ test("buildUiPageTemplateContext resolves link placement from default app ShellO
       targetFile: "admin/reports/index.vue",
       options: {}
     });
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_HOST__, "shell-layout");
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_POSITION__, "primary-menu");
-    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "users.web.shell.surface-aware-menu-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "shell-layout:primary-menu");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.surface-aware-menu-link-item");
     assert.equal(context.__JSKIT_UI_LINK_WORKSPACE_SUFFIX__, "/reports");
     assert.equal(context.__JSKIT_UI_LINK_NON_WORKSPACE_SUFFIX__, "/reports");
+    assert.equal(context.__JSKIT_UI_LINK_WHEN_LINE__, "");
     assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "");
     assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_ID__, "ui-generator.page.admin.reports.link");
   });
 });
 
+test("buildUiPageTemplateContext derives an auth guard from an authenticated surface policy", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceAccessPolicies: {
+    authenticated: {
+      requireAuth: true
+    }
+  },
+  surfaceDefinitions: {
+    app: { id: "app", pagesRoot: "app", enabled: true, accessPolicyId: "authenticated" }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+
+    const context = await buildUiPageTemplateContext({
+      appRoot,
+      targetFile: "app/reports/index.vue",
+      options: {}
+    });
+
+    assert.equal(context.__JSKIT_UI_LINK_WHEN_LINE__, "    when: ({ auth }) => Boolean(auth?.authenticated)\n");
+  });
+});
+
 test("buildUiPageTemplateContext supports explicit link placement override", async () => {
   await withTempApp(async (appRoot) => {
     await writeConfig(
@@ -87,8 +119,8 @@ test("buildUiPageTemplateContext supports explicit link placement override", asy
         "link-placement": "shell-layout:top-right"
       }
     });
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_POSITION__, "top-right");
-    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "users.web.shell.surface-aware-menu-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "shell-layout:top-right");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.surface-aware-menu-link-item");
   });
 });
 
@@ -133,7 +165,11 @@ test("buildUiPageTemplateContext supports explicit package outlet link placement
     ui: {
       placements: {
         outlets: [
-          { host: "workspace-tools", position: "primary-menu", source: "src/client/components/UsersWorkspaceToolsWidget.vue" }
+          {
+            target: "workspace-tools:primary-menu",
+            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
+            source: "src/client/components/UsersWorkspaceToolsWidget.vue"
+          }
         ]
       }
     }
@@ -149,8 +185,7 @@ test("buildUiPageTemplateContext supports explicit package outlet link placement
         "link-placement": "workspace-tools:primary-menu"
       }
     });
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_HOST__, "workspace-tools");
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_POSITION__, "primary-menu");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "workspace-tools:primary-menu");
   });
 });
 
@@ -226,7 +261,7 @@ test("buildUiPageTemplateContext infers subpage link placement, tab token, and l
       `<template>
   <SectionContainerShell>
     <template #tabs>
-      <ShellOutlet host="contact-view" position="sub-pages" />
+      <ShellOutlet target="contact-view:sub-pages" />
     </template>
     <RouterView />
   </SectionContainerShell>
@@ -240,8 +275,7 @@ test("buildUiPageTemplateContext infers subpage link placement, tab token, and l
       options: {}
     });
 
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_HOST__, "contact-view");
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_POSITION__, "sub-pages");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "contact-view:sub-pages");
     assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
     assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./notes\",\n");
   });
@@ -265,7 +299,7 @@ test("buildUiPageTemplateContext inherits a file-route parent host for deeper de
       `<template>
   <SectionContainerShell>
     <template #tabs>
-      <ShellOutlet host="contact-view" position="sub-pages" />
+      <ShellOutlet target="contact-view:sub-pages" />
     </template>
     <RouterView />
   </SectionContainerShell>
@@ -279,8 +313,7 @@ test("buildUiPageTemplateContext inherits a file-route parent host for deeper de
       options: {}
     });
 
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_HOST__, "contact-view");
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_POSITION__, "sub-pages");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "contact-view:sub-pages");
     assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
     assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./notes/history\",\n");
   });
@@ -304,7 +337,7 @@ test("buildUiPageTemplateContext infers subpage link placement from an index-rou
       `<template>
   <SectionContainerShell>
     <template #tabs>
-      <ShellOutlet host="catalog" position="sub-pages" />
+      <ShellOutlet target="catalog:sub-pages" />
     </template>
     <RouterView />
   </SectionContainerShell>
@@ -318,8 +351,7 @@ test("buildUiPageTemplateContext infers subpage link placement from an index-rou
       options: {}
     });
 
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_HOST__, "catalog");
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_POSITION__, "sub-pages");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "catalog:sub-pages");
     assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
     assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./products\",\n");
   });
@@ -343,7 +375,7 @@ test("buildUiPageTemplateContext finds the nearest index-route parent host", asy
       `<template>
   <SectionContainerShell>
     <template #tabs>
-      <ShellOutlet host="catalog" position="sub-pages" />
+      <ShellOutlet target="catalog:sub-pages" />
     </template>
     <RouterView />
   </SectionContainerShell>
@@ -356,7 +388,7 @@ test("buildUiPageTemplateContext finds the nearest index-route parent host", asy
       `<template>
   <SectionContainerShell>
     <template #tabs>
-      <ShellOutlet host="catalog-products" position="sub-pages" />
+      <ShellOutlet target="catalog-products:sub-pages" />
     </template>
     <RouterView />
   </SectionContainerShell>
@@ -370,8 +402,7 @@ test("buildUiPageTemplateContext finds the nearest index-route parent host", asy
       options: {}
     });
 
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_HOST__, "catalog-products");
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_POSITION__, "sub-pages");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "catalog-products:sub-pages");
     assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
     assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./variants\",\n");
   });
@@ -395,7 +426,7 @@ test("buildUiPageTemplateContext infers subpage link placement from an index rou
       `<template>
   <SectionContainerShell>
     <template #tabs>
-      <ShellOutlet host="customer-view" position="sub-pages" />
+      <ShellOutlet target="customer-view:sub-pages" />
     </template>
     <RouterView />
   </SectionContainerShell>
@@ -409,8 +440,7 @@ test("buildUiPageTemplateContext infers subpage link placement from an index rou
       options: {}
     });
 
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_HOST__, "customer-view");
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_POSITION__, "sub-pages");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "customer-view:sub-pages");
     assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
     assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./pets\",\n");
     assert.equal(context.__JSKIT_UI_LINK_WORKSPACE_SUFFIX__, "/customers/[customerId]/pets");
@@ -468,11 +498,35 @@ test("buildUiPageTemplateContext rejects target files with a leading src segment
           targetFile: "src/components/ReportsPanel.vue",
           options: {}
         }),
-      /must be relative to src\/pages\/, without a leading src\/ segment/
+      /must be relative to src\/pages\/ or start with src\/pages\/:/
     );
   });
 });
 
+test("buildUiPageTemplateContext accepts target files with a src/pages prefix", 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: "src/pages/admin/reports/index.vue",
+      options: {}
+    });
+
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_ID__, "ui-generator.page.admin.reports.link");
+    assert.equal(context.__JSKIT_UI_LINK_WORKSPACE_SUFFIX__, "/reports");
+  });
+});
+
 test("buildUiPageTemplateContext fails when the target file matches no surface", async () => {
   await withTempApp(async (appRoot) => {
     await writeConfig(
@@ -546,7 +600,7 @@ test("buildUiPageTemplateContext validates link placement format", async () => {
             "link-placement": "invalid-placement"
           }
         }),
-      /option "placement" must be in "host:position" format/
+      /option "placement" must be a target in "host:position" format/
     );
   });
 });

package/test/elementSubcommand.test.js

@@ -23,8 +23,12 @@ async function writeAppFixture(appRoot) {
     path.join(appRoot, "src", "components", "ShellLayout.vue"),
     `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
-    <ShellOutlet host="shell-layout" position="top-right" />
+    <ShellOutlet
+      target="shell-layout:primary-menu"
+      default
+      default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+    />
+    <ShellOutlet target="shell-layout:top-right" />
   </div>
 </template>
 `,
@@ -34,7 +38,7 @@ async function writeAppFixture(appRoot) {
     path.join(appRoot, "src", "pages", "admin", "workspace", "settings", "index.vue"),
     `<template>
   <section>
-    <ShellOutlet host="admin-settings" position="forms" />
+    <ShellOutlet target="admin-settings:forms" />
   </section>
 </template>
 `,
@@ -104,8 +108,7 @@ test("ui-generator placed-element subcommand creates component and outlet placem
 
     const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
     assert.match(placementSource, /id: "ui-generator\.element\.ops-panel"/);
-    assert.match(placementSource, /host: "shell-layout"/);
-    assert.match(placementSource, /position: "top-right"/);
+    assert.match(placementSource, /target: "shell-layout:top-right"/);
     assert.match(placementSource, /componentToken: "local\.main\.ui\.element\.ops-panel"/);
   });
 });
@@ -125,8 +128,7 @@ test("ui-generator placed-element subcommand supports explicit placement overrid
     });
 
     const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
-    assert.match(placementSource, /host: "shell-layout"/);
-    assert.match(placementSource, /position: "primary-menu"/);
+    assert.match(placementSource, /target: "shell-layout:primary-menu"/);
   });
 });
 

package/test/outletSubcommand.test.js

@@ -40,7 +40,7 @@ import { computed } from "vue";
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "contact-view"
+        target: "contact-view:sub-pages"
       }
     });
 
@@ -48,7 +48,7 @@ import { computed } from "vue";
 
     const output = await readFile(targetPath, "utf8");
     assert.match(output, /import ShellOutlet from "@jskit-ai\/shell-web\/client\/components\/ShellOutlet";/);
-    assert.match(output, /<ShellOutlet host="contact-view" position="sub-pages" \/>/);
+    assert.match(output, /<ShellOutlet target="contact-view:sub-pages" \/>/);
     assert.doesNotMatch(output, /RouterView/);
     assert.doesNotMatch(output, /jskit:ui-generator\.outlet:/);
 
@@ -57,7 +57,7 @@ import { computed } from "vue";
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "contact-view"
+        target: "contact-view:sub-pages"
       }
     });
 
@@ -79,7 +79,7 @@ import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
 
 <template>
   <section>
-    <ShellOutlet host="contact-view" position="sub-pages" />
+    <ShellOutlet target="contact-view:sub-pages" />
   </section>
 </template>
 `,
@@ -91,12 +91,12 @@ import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "contact-view"
+        target: "contact-view:sub-pages"
       }
     });
 
     const output = await readFile(targetPath, "utf8");
-    assert.equal((output.match(/<ShellOutlet host="contact-view" position="sub-pages" \/>/g) || []).length, 1);
+    assert.equal((output.match(/<ShellOutlet target="contact-view:sub-pages" \/>/g) || []).length, 1);
     assert.equal(
       (output.match(/import ShellOutlet from "@jskit-ai\/shell-web\/client\/components\/ShellOutlet";/g) || []).length,
       1
@@ -124,7 +124,7 @@ test("ui-generator outlet creates script setup when missing", async () => {
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "contact-view"
+        target: "contact-view:sub-pages"
       }
     });
 
@@ -161,7 +161,7 @@ test("ui-generator outlet inserts generated script after existing route block",
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "contact-view"
+        target: "contact-view:sub-pages"
       }
     });
 
@@ -203,12 +203,12 @@ test("ui-generator outlet keeps indentation when injected into nested template b
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "contact-view"
+        target: "contact-view:sub-pages"
       }
     });
 
     const output = await readFile(targetPath, "utf8");
-    assert.match(output, /\n\s{2}<\/section>\n\s{2}<ShellOutlet host="contact-view" position="sub-pages" \/>\n<\/template>/);
+    assert.match(output, /\n\s{2}<\/section>\n\s{2}<ShellOutlet target="contact-view:sub-pages" \/>\n<\/template>/);
     assert.match(output, /<template v-else-if="view\.isLoading">\n\s*<v-skeleton-loader type="heading, text@2, article" \/>\n\s*<\/template>/);
     assert.doesNotMatch(output, /jskit:ui-generator\.outlet:/);
   });
@@ -226,11 +226,11 @@ test("ui-generator outlet rejects unsupported options", async () => {
       runGeneratorSubcommand({
         appRoot,
         subcommand: "outlet",
-        args: [targetFile],
-        options: {
-          target: "contact-view",
-          bogus: "routed"
-        }
+      args: [targetFile],
+      options: {
+        target: "contact-view:sub-pages",
+        bogus: "routed"
+      }
       }),
       /ui-generator outlet received unsupported option: --bogus\./
     );
@@ -255,7 +255,33 @@ test("ui-generator outlet supports explicit target host:position", async () => {
     });
 
     const output = await readFile(targetPath, "utf8");
-    assert.match(output, /<ShellOutlet host="customer-view" position="summary-actions" \/>/);
+    assert.match(output, /<ShellOutlet target="customer-view:summary-actions" \/>/);
+  });
+});
+
+test("ui-generator outlet rejects non-vue target files without changing them", async () => {
+  await withTempApp(async (appRoot) => {
+    const targetFile = "src/pages/w/[workspaceSlug]/admin/practice/vets/_components/VetAddEditFormFields.js";
+    const targetPath = path.join(appRoot, targetFile);
+    const originalSource = "export const fields = [];\n";
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, originalSource, "utf8");
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "outlet",
+        args: [targetFile],
+        options: {
+          target: "vet-view:sub-pages"
+        }
+      }),
+      /ui-generator outlet target file must be an existing Vue SFC \(\.vue\): src\/pages\/w\/\[workspaceSlug\]\/admin\/practice\/vets\/_components\/VetAddEditFormFields\.js\./
+    );
+
+    const output = await readFile(targetPath, "utf8");
+    assert.equal(output, originalSource);
   });
 });
 
@@ -276,7 +302,7 @@ test("ui-generator outlet validates target format", async () => {
           target: "customer-view:"
         }
       }),
-      /ui-generator outlet option "target" must be "host" or "host:position"\./
+      /ui-generator outlet option "target" must be a target in "host:position" format\./
     );
   });
 });