@jskit-ai/ui-generator 0.1.48 → 0.1.50

package/test/addSubpagesSubcommand.test.js

@@ -39,6 +39,22 @@ export { addPlacement };
 export default function getPlacements() {
   return [];
 }
+`,
+    "utf8"
+  );
+  await writeFile(
+    path.join(appRoot, "src", "placementTopology.js"),
+    `const placements = [];
+
+function addPlacementTopology(value = {}) {
+  placements.push(value);
+}
+
+export { addPlacementTopology };
+
+export default function getPlacementTopology() {
+  return { placements };
+}
 `,
     "utf8"
   );
@@ -97,20 +113,28 @@ 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/pages/${targetFile}`,
+      "src/placementTopology.js"
     ]);
 
     const pageSource = await readPageFile(appRoot, targetFile);
     assert.match(
       pageSource,
-      /<ShellOutlet target="practice:sub-pages" default-link-component-token="local\.main\.ui\.surface-aware-menu-link-item" \/>/
+      /<ShellOutlet target="practice:sub-pages" \/>/
     );
+    const topologySource = await readFile(path.join(appRoot, "src", "placementTopology.js"), "utf8");
+    assert.match(topologySource, /id: "page\.section-nav"/);
+    assert.match(topologySource, /owner: "practice"/);
+    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")
     );
   });
 });
@@ -132,7 +156,7 @@ test("ui-generator add-subpages derives the default target from a dynamic file-r
     const pageSource = await readPageFile(appRoot, targetFile);
     assert.match(
       pageSource,
-      /<ShellOutlet target="contacts-contact-id:sub-pages" default-link-component-token="local\.main\.ui\.surface-aware-menu-link-item" \/>/
+      /<ShellOutlet target="contacts-contact-id:sub-pages" \/>/
     );
   });
 });
@@ -154,7 +178,7 @@ test("ui-generator add-subpages derives the default target from a nested route p
     const pageSource = await readPageFile(appRoot, targetFile);
     assert.match(
       pageSource,
-      /<ShellOutlet target="catalog-products:sub-pages" default-link-component-token="local\.main\.ui\.surface-aware-menu-link-item" \/>/
+      /<ShellOutlet target="catalog-products:sub-pages" \/>/
     );
   });
 });
@@ -199,11 +223,46 @@ test("ui-generator add-subpages supports explicit target host:position", async (
     const pageSource = await readPageFile(appRoot, targetFile);
     assert.match(
       pageSource,
-      /<ShellOutlet target="practice-hub:secondary-tabs" default-link-component-token="local\.main\.ui\.surface-aware-menu-link-item" \/>/
+      /<ShellOutlet target="practice-hub:secondary-tabs" \/>/
     );
   });
 });
 
+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);
@@ -211,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,
@@ -219,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"
     );
 
@@ -235,16 +294,105 @@ test("ui-generator add-subpages does not rewrite existing scaffold support compo
 
     assert.deepEqual(result.touchedFiles, [
       "packages/main/src/client/providers/MainClientProvider.js",
-      `src/pages/${targetFile}`
+      `src/pages/${targetFile}`,
+      "src/placementTopology.js"
     ]);
     assert.equal(
       await readFile(path.join(appRoot, "src", "components", "SectionContainerShell.vue"), "utf8"),
       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);
   });
 });
 
@@ -332,7 +480,7 @@ test("ui-generator add-subpages accepts target files with a src/pages prefix", a
     const pageSource = await readFile(path.join(appRoot, targetFile), "utf8");
     assert.match(
       pageSource,
-      /<ShellOutlet target="practice:sub-pages" default-link-component-token="local\.main\.ui\.surface-aware-menu-link-item" \/>/
+      /<ShellOutlet target="practice:sub-pages" \/>/
     );
     assert.match(pageSource, /<RouterView \/>/);
   });

package/test/buildTemplateContext.test.js

@@ -35,10 +35,77 @@ async function writeShellLayout(appRoot, source = "") {
     <ShellOutlet
       target="shell-layout:primary-menu"
       default
-      default-link-component-token="local.main.ui.surface-aware-menu-link-item"
     />
   </div>
 </template>
+`
+  );
+  await writePlacementTopology(appRoot);
+}
+
+function renderTopologyVariant(outlet, { linkRenderer = "" } = {}) {
+  const rendererLines = linkRenderer
+    ? `,
+      renderers: {
+        link: "${linkRenderer}"
+      }`
+    : "";
+  return `{
+      outlet: "${outlet}"${rendererLines}
+    }`;
+}
+
+function renderTopologyEntry({
+  id = "",
+  owner = "",
+  surfaces = ["*"],
+  defaultPlacement = false,
+  outlet = "",
+  linkRenderer = ""
+} = {}) {
+  const ownerLine = owner ? `    owner: "${owner}",\n` : "";
+  const defaultLine = defaultPlacement ? "    default: true,\n" : "";
+  return `  {
+    id: "${id}",
+${ownerLine}    surfaces: ${JSON.stringify(surfaces)},
+${defaultLine}    variants: {
+      compact: ${renderTopologyVariant(outlet, { linkRenderer })},
+      medium: ${renderTopologyVariant(outlet, { linkRenderer })},
+      expanded: ${renderTopologyVariant(outlet, { linkRenderer })}
+    }
+  }`;
+}
+
+async function writePlacementTopology(appRoot, entries = []) {
+  const defaultEntries = [
+    renderTopologyEntry({
+      id: "shell.primary-nav",
+      surfaces: ["*"],
+      defaultPlacement: true,
+      outlet: "shell-layout:primary-menu",
+      linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+    }),
+    renderTopologyEntry({
+      id: "shell.status",
+      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(
+    appRoot,
+    "src/placementTopology.js",
+    `export default {
+  placements: [
+${[...defaultEntries, ...entries].join(",\n")}
+  ]
+};
 `
   );
 }
@@ -61,8 +128,9 @@ test("buildUiPageTemplateContext resolves link placement from default app ShellO
       targetFile: "admin/reports/index.vue",
       options: {}
     });
-    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_PLACEMENT_TARGET__, "shell.primary-nav");
+    assert.equal(context.__JSKIT_UI_LINK_OWNER_LINE__, "");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "");
     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__, "");
@@ -116,15 +184,40 @@ test("buildUiPageTemplateContext supports explicit link placement override", asy
       appRoot,
       targetFile: "admin/reports/index.vue",
       options: {
-        "link-placement": "shell-layout:top-right"
+        "link-placement": "shell.status"
+      }
+    });
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "shell.status");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "");
+  });
+});
+
+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-layout:top-right");
-    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.surface-aware-menu-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "shell.global-actions");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "");
   });
 });
 
-test("buildUiPageTemplateContext supports explicit package outlet link placement", async () => {
+test("buildUiPageTemplateContext supports explicit package semantic link placement", async () => {
   await withTempApp(async (appRoot) => {
     await writeConfig(
       appRoot,
@@ -136,6 +229,22 @@ test("buildUiPageTemplateContext supports explicit package outlet link placement
 `
     );
     await writeShellLayout(appRoot);
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "catalog",
+        surfaces: ["admin"],
+        outlet: "catalog:sub-pages",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      }),
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "catalog-products",
+        surfaces: ["admin"],
+        outlet: "catalog-products:sub-pages",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
     await writeFileInApp(
       appRoot,
       ".jskit/lock.json",
@@ -164,13 +273,34 @@ test("buildUiPageTemplateContext supports explicit package outlet link placement
   metadata: {
     ui: {
       placements: {
-        outlets: [
+        topology: {
+          placements: [
           {
-            target: "admin-cog:primary-menu",
-            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
-            source: "src/client/components/UsersWorkspaceToolsWidget.vue"
+            id: "admin.tools-menu",
+            surfaces: ["admin"],
+            variants: {
+              compact: {
+                outlet: "admin-cog:primary-menu",
+                renderers: {
+                  link: "local.main.ui.surface-aware-menu-link-item"
+                }
+              },
+              medium: {
+                outlet: "admin-cog:primary-menu",
+                renderers: {
+                  link: "local.main.ui.surface-aware-menu-link-item"
+                }
+              },
+              expanded: {
+                outlet: "admin-cog:primary-menu",
+                renderers: {
+                  link: "local.main.ui.surface-aware-menu-link-item"
+                }
+              }
+            }
           }
         ]
+        }
       }
     }
   }
@@ -182,10 +312,10 @@ test("buildUiPageTemplateContext supports explicit package outlet link placement
       appRoot,
       targetFile: "admin/reports/index.vue",
       options: {
-        "link-placement": "admin-cog:primary-menu"
+        "link-placement": "admin.tools-menu"
       }
     });
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "admin-cog:primary-menu");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "admin.tools-menu");
   });
 });
 
@@ -200,15 +330,21 @@ test("buildUiPageTemplateContext suppresses inferred relative link-to for surfac
 };
 `
     );
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "home-settings",
+        surfaces: ["home"],
+        outlet: "home-settings:primary-menu",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
     await writeFileInApp(
       appRoot,
       "src/pages/home/settings.vue",
       `<template>
   <section>
-    <ShellOutlet
-      target="home-settings:primary-menu"
-      default-link-component-token="local.main.ui.surface-aware-menu-link-item"
-    />
+    <ShellOutlet target="home-settings:primary-menu" />
     <RouterView />
   </section>
 </template>
@@ -221,13 +357,14 @@ test("buildUiPageTemplateContext suppresses inferred relative link-to for surfac
       options: {}
     });
 
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "home-settings:primary-menu");
-    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.surface-aware-menu-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "page.section-nav");
+    assert.equal(context.__JSKIT_UI_LINK_OWNER_LINE__, "    owner: \"home-settings\",\n");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "");
     assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "");
   });
 });
 
-test("buildUiPageTemplateContext supports explicit link component token and link-to", async () => {
+test("buildUiPageTemplateContext supports explicit semantic placement and link-to", async () => {
   await withTempApp(async (appRoot) => {
     await writeConfig(
       appRoot,
@@ -244,12 +381,12 @@ test("buildUiPageTemplateContext supports explicit link component token and link
       appRoot,
       targetFile: "admin/contacts/[contactId]/index/notes/index.vue",
       options: {
-        "link-placement": "shell-layout:top-right",
-        "link-component-token": "local.main.ui.tab-link-item",
+        "link-placement": "shell.status",
         "link-to": "./notes"
       }
     });
-    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "shell.status");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "");
     assert.equal(context.__JSKIT_UI_LINK_ICON__, "mdi-view-list-outline");
     assert.equal(context.__JSKIT_UI_LINK_WORKSPACE_SUFFIX__, "/contacts/[contactId]/notes");
     assert.equal(context.__JSKIT_UI_LINK_NON_WORKSPACE_SUFFIX__, "/contacts/[contactId]/notes");
@@ -294,6 +431,15 @@ test("buildUiPageTemplateContext infers subpage link placement, tab token, and l
 `
     );
     await writeShellLayout(appRoot);
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "contact-view",
+        surfaces: ["admin"],
+        outlet: "contact-view:sub-pages",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
     await writeFileInApp(
       appRoot,
       "src/pages/admin/contacts/[contactId].vue",
@@ -314,8 +460,9 @@ test("buildUiPageTemplateContext infers subpage link placement, tab token, and l
       options: {}
     });
 
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "contact-view:sub-pages");
-    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.surface-aware-menu-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "page.section-nav");
+    assert.equal(context.__JSKIT_UI_LINK_OWNER_LINE__, "    owner: \"contact-view\",\n");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "");
     assert.equal(context.__JSKIT_UI_LINK_ICON__, "mdi-view-list-outline");
     assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./notes\",\n");
   });
@@ -333,6 +480,15 @@ test("buildUiPageTemplateContext inherits a file-route parent host for deeper de
 `
     );
     await writeShellLayout(appRoot);
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "contact-view",
+        surfaces: ["admin"],
+        outlet: "contact-view:sub-pages",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
     await writeFileInApp(
       appRoot,
       "src/pages/admin/contacts/[contactId].vue",
@@ -353,8 +509,8 @@ test("buildUiPageTemplateContext inherits a file-route parent host for deeper de
       options: {}
     });
 
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "contact-view:sub-pages");
-    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.surface-aware-menu-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "page.section-nav");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "");
     assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./notes/history\",\n");
   });
 });
@@ -371,6 +527,15 @@ test("buildUiPageTemplateContext infers subpage link placement from an index-rou
 `
     );
     await writeShellLayout(appRoot);
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "catalog",
+        surfaces: ["admin"],
+        outlet: "catalog:sub-pages",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
     await writeFileInApp(
       appRoot,
       "src/pages/admin/catalog/index.vue",
@@ -391,8 +556,9 @@ test("buildUiPageTemplateContext infers subpage link placement from an index-rou
       options: {}
     });
 
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "catalog:sub-pages");
-    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.surface-aware-menu-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "page.section-nav");
+    assert.equal(context.__JSKIT_UI_LINK_OWNER_LINE__, "    owner: \"catalog\",\n");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "");
     assert.equal(context.__JSKIT_UI_LINK_ICON__, "mdi-view-list-outline");
     assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./products\",\n");
   });
@@ -410,6 +576,22 @@ test("buildUiPageTemplateContext finds the nearest index-route parent host", asy
 `
     );
     await writeShellLayout(appRoot);
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "catalog",
+        surfaces: ["admin"],
+        outlet: "catalog:sub-pages",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      }),
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "catalog-products",
+        surfaces: ["admin"],
+        outlet: "catalog-products:sub-pages",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
     await writeFileInApp(
       appRoot,
       "src/pages/admin/catalog/index.vue",
@@ -443,8 +625,9 @@ test("buildUiPageTemplateContext finds the nearest index-route parent host", asy
       options: {}
     });
 
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "catalog-products:sub-pages");
-    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.surface-aware-menu-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "page.section-nav");
+    assert.equal(context.__JSKIT_UI_LINK_OWNER_LINE__, "    owner: \"catalog-products\",\n");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "");
     assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./variants\",\n");
   });
 });
@@ -461,6 +644,15 @@ test("buildUiPageTemplateContext infers subpage link placement from an index rou
 `
     );
     await writeShellLayout(appRoot);
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "customer-view",
+        surfaces: ["admin"],
+        outlet: "customer-view:sub-pages",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
     await writeFileInApp(
       appRoot,
       "src/pages/admin/customers/[customerId]/index.vue",
@@ -481,8 +673,9 @@ test("buildUiPageTemplateContext infers subpage link placement from an index rou
       options: {}
     });
 
-    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "customer-view:sub-pages");
-    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.surface-aware-menu-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_TARGET__, "page.section-nav");
+    assert.equal(context.__JSKIT_UI_LINK_OWNER_LINE__, "    owner: \"customer-view\",\n");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "");
     assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./pets\",\n");
     assert.equal(context.__JSKIT_UI_LINK_WORKSPACE_SUFFIX__, "/customers/[customerId]/pets");
   });
@@ -641,7 +834,7 @@ test("buildUiPageTemplateContext validates link placement format", async () => {
             "link-placement": "invalid-placement"
           }
         }),
-      /option "placement" must be a target in "host:position" format/
+      /option "placement" must be a semantic target in "area.slot" format/
     );
   });
 });