@jskit-ai/ui-generator 0.1.14 → 0.1.15

package/test/buildTemplateContext.test.js

@@ -14,11 +14,20 @@ async function withTempApp(run) {
   }
 }
 
-async function writeVueFile(appRoot, relativePath, source = "") {
+async function writeFileInApp(appRoot, relativePath, source) {
   const absoluteFile = path.join(appRoot, relativePath);
   await mkdir(path.dirname(absoluteFile), { recursive: true });
-  await writeFile(
-    absoluteFile,
+  await writeFile(absoluteFile, source, "utf8");
+}
+
+async function writeConfig(appRoot, source) {
+  await writeFileInApp(appRoot, "config/public.js", source);
+}
+
+async function writeShellLayout(appRoot, source = "") {
+  await writeFileInApp(
+    appRoot,
+    "src/components/ShellLayout.vue",
     source ||
       `<template>
   <div>
@@ -26,67 +35,76 @@ async function writeVueFile(appRoot, relativePath, source = "") {
     <ShellOutlet host="shell-layout" position="primary-menu" default />
   </div>
 </template>
-`,
-    "utf8"
+`
   );
 }
 
-test("buildUiPageTemplateContext resolves placement from default app ShellOutlet target", async () => {
+test("buildUiPageTemplateContext resolves link placement from default app ShellOutlet target", async () => {
   await withTempApp(async (appRoot) => {
-    await writeVueFile(
-      appRoot,
-      "src/components/ShellLayout.vue",
-      `<template>
-  <div>
-    <ShellOutlet host="shell-layout" position="top-right" />
-    <ShellOutlet host="shell-layout" position="primary-menu" />
-  </div>
-</template>
-`
-    );
-    await writeVueFile(
+    await writeConfig(
       appRoot,
-      "src/pages/admin/workspace/settings/index.vue",
-      `<template>
-  <section>
-    <ShellOutlet host="admin-settings" position="forms" default />
-  </section>
-</template>
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
 `
     );
+    await writeShellLayout(appRoot);
 
     const context = await buildUiPageTemplateContext({
       appRoot,
+      targetFile: "admin/reports/index.vue",
       options: {}
     });
-    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_HOST__, "admin-settings");
-    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_POSITION__, "forms");
-    assert.equal(context.__JSKIT_UI_MENU_COMPONENT_TOKEN__, "users.web.shell.surface-aware-menu-link-item");
-    assert.equal(context.__JSKIT_UI_MENU_WORKSPACE_SUFFIX__, "/");
-    assert.equal(context.__JSKIT_UI_MENU_NON_WORKSPACE_SUFFIX__, "/");
-    assert.equal(context.__JSKIT_UI_MENU_TO_PROP_LINE__, "");
+    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_WORKSPACE_SUFFIX__, "/reports");
+    assert.equal(context.__JSKIT_UI_LINK_NON_WORKSPACE_SUFFIX__, "/reports");
+    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 supports explicit placement override", async () => {
+test("buildUiPageTemplateContext supports explicit link placement override", async () => {
   await withTempApp(async (appRoot) => {
-    await writeVueFile(appRoot, "src/components/ShellLayout.vue");
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
 
     const context = await buildUiPageTemplateContext({
       appRoot,
+      targetFile: "admin/reports/index.vue",
       options: {
-        placement: "shell-layout:top-right"
+        "link-placement": "shell-layout:top-right"
       }
     });
-    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_POSITION__, "top-right");
-    assert.equal(context.__JSKIT_UI_MENU_COMPONENT_TOKEN__, "users.web.shell.surface-aware-menu-link-item");
+    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");
   });
 });
 
-test("buildUiPageTemplateContext supports explicit package outlet placement", async () => {
+test("buildUiPageTemplateContext supports explicit package outlet link placement", async () => {
   await withTempApp(async (appRoot) => {
-    await writeVueFile(appRoot, "src/components/ShellLayout.vue");
-    await writeVueFile(
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+    await writeFileInApp(
       appRoot,
       ".jskit/lock.json",
       `${JSON.stringify(
@@ -106,7 +124,7 @@ test("buildUiPageTemplateContext supports explicit package outlet placement", as
         2
       )}\n`
     );
-    await writeVueFile(
+    await writeFileInApp(
       appRoot,
       "node_modules/@example/users-web/package.descriptor.mjs",
       `export default {
@@ -126,63 +144,406 @@ test("buildUiPageTemplateContext supports explicit package outlet placement", as
 
     const context = await buildUiPageTemplateContext({
       appRoot,
+      targetFile: "admin/reports/index.vue",
       options: {
-        placement: "workspace-tools:primary-menu"
+        "link-placement": "workspace-tools:primary-menu"
       }
     });
-    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_HOST__, "workspace-tools");
-    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_POSITION__, "primary-menu");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_HOST__, "workspace-tools");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_POSITION__, "primary-menu");
   });
 });
 
-test("buildUiPageTemplateContext supports explicit placement token and placement to", async () => {
+test("buildUiPageTemplateContext supports explicit link component token and link-to", async () => {
   await withTempApp(async (appRoot) => {
-    await writeVueFile(appRoot, "src/components/ShellLayout.vue");
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
 
     const context = await buildUiPageTemplateContext({
       appRoot,
+      targetFile: "admin/contacts/[contactId]/index/notes/index.vue",
       options: {
-        name: "Notes",
-        "directory-prefix": "contacts/[contactId]/(nestedChildren)",
-        placement: "shell-layout:top-right",
-        "placement-component-token": "local.main.ui.tab-link-item",
-        "placement-to": "./notes"
+        "link-placement": "shell-layout:top-right",
+        "link-component-token": "local.main.ui.tab-link-item",
+        "link-to": "./notes"
       }
     });
-    assert.equal(context.__JSKIT_UI_MENU_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
-    assert.equal(context.__JSKIT_UI_MENU_WORKSPACE_SUFFIX__, "/contacts/[contactId]/notes");
-    assert.equal(context.__JSKIT_UI_MENU_NON_WORKSPACE_SUFFIX__, "/contacts/[contactId]/notes");
-    assert.equal(context.__JSKIT_UI_MENU_TO_PROP_LINE__, "      to: \"./notes\",\n");
+    assert.equal(context.__JSKIT_UI_LINK_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_WORKSPACE_SUFFIX__, "/contacts/[contactId]/notes");
+    assert.equal(context.__JSKIT_UI_LINK_NON_WORKSPACE_SUFFIX__, "/contacts/[contactId]/notes");
+    assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./notes\",\n");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_ID__, "ui-generator.page.admin.contacts.contact-id.notes.link");
   });
 });
 
-test("buildUiPageTemplateContext auto sets relative placement to for nestedChildren prefixes", async () => {
+test("buildUiPageTemplateContext derives native route suffixes for index-owned child pages", async () => {
   await withTempApp(async (appRoot) => {
-    await writeVueFile(appRoot, "src/components/ShellLayout.vue");
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
 
     const context = await buildUiPageTemplateContext({
       appRoot,
-      options: {
-        name: "Notes",
-        "directory-prefix": "contacts/[contactId]/(nestedChildren)",
-        placement: "shell-layout:top-right"
-      }
+      targetFile: "admin/contacts/[contactId]/index/notes/index.vue",
+      options: {}
+    });
+    assert.equal(context.__JSKIT_UI_LINK_WORKSPACE_SUFFIX__, "/contacts/[contactId]/notes");
+    assert.equal(context.__JSKIT_UI_LINK_NON_WORKSPACE_SUFFIX__, "/contacts/[contactId]/notes");
+    assert.equal(context.__JSKIT_UI_LINK_PLACEMENT_ID__, "ui-generator.page.admin.contacts.contact-id.notes.link");
+  });
+});
+
+test("buildUiPageTemplateContext infers subpage link placement, tab token, and link-to from a file-route parent host", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/contacts/[contactId].vue",
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="contact-view" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`
+    );
+
+    const context = await buildUiPageTemplateContext({
+      appRoot,
+      targetFile: "admin/contacts/[contactId]/notes/index.vue",
+      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_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./notes\",\n");
+  });
+});
+
+test("buildUiPageTemplateContext inherits a file-route parent host for deeper descendants", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/contacts/[contactId].vue",
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="contact-view" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`
+    );
+
+    const context = await buildUiPageTemplateContext({
+      appRoot,
+      targetFile: "admin/contacts/[contactId]/notes/history/index.vue",
+      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_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./notes/history\",\n");
+  });
+});
+
+test("buildUiPageTemplateContext infers subpage link placement from an index-route parent host", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/catalog/index.vue",
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="catalog" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`
+    );
+
+    const context = await buildUiPageTemplateContext({
+      appRoot,
+      targetFile: "admin/catalog/index/products/index.vue",
+      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_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./products\",\n");
+  });
+});
+
+test("buildUiPageTemplateContext finds the nearest index-route parent host", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/catalog/index.vue",
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="catalog" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`
+    );
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/catalog/index/products/index.vue",
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="catalog-products" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`
+    );
+
+    const context = await buildUiPageTemplateContext({
+      appRoot,
+      targetFile: "admin/catalog/index/products/index/variants/index.vue",
+      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_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
+    assert.equal(context.__JSKIT_UI_LINK_TO_PROP_LINE__, "      to: \"./variants\",\n");
+  });
+});
+
+test("buildUiPageTemplateContext infers subpage link placement from an index route hosted record page", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/customers/[customerId]/index.vue",
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="customer-view" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`
+    );
+
+    const context = await buildUiPageTemplateContext({
+      appRoot,
+      targetFile: "admin/customers/[customerId]/index/pets/index.vue",
+      options: {}
     });
-    assert.equal(context.__JSKIT_UI_MENU_TO_PROP_LINE__, "      to: \"./notes\",\n");
-    assert.equal(context.__JSKIT_UI_MENU_WORKSPACE_SUFFIX__, "/contacts/[contactId]/notes");
+
+    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_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");
   });
 });
 
-test("buildUiPageTemplateContext validates placement format", async () => {
+test("buildUiPageTemplateContext derives the same visible route from file and index page shapes", async () => {
   await withTempApp(async (appRoot) => {
-    await writeVueFile(appRoot, "src/components/ShellLayout.vue");
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+
+    const fileContext = await buildUiPageTemplateContext({
+      appRoot,
+      targetFile: "admin/catalog.vue",
+      options: {}
+    });
+    const indexContext = await buildUiPageTemplateContext({
+      appRoot,
+      targetFile: "admin/catalog/index.vue",
+      options: {}
+    });
+
+    assert.equal(fileContext.__JSKIT_UI_LINK_WORKSPACE_SUFFIX__, "/catalog");
+    assert.equal(indexContext.__JSKIT_UI_LINK_WORKSPACE_SUFFIX__, "/catalog");
+    assert.equal(fileContext.__JSKIT_UI_LINK_PLACEMENT_ID__, "ui-generator.page.admin.catalog.link");
+    assert.equal(indexContext.__JSKIT_UI_LINK_PLACEMENT_ID__, "ui-generator.page.admin.catalog.link");
+  });
+});
+
+test("buildUiPageTemplateContext rejects target files with a leading src segment", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+
+    await assert.rejects(
+      () =>
+        buildUiPageTemplateContext({
+          appRoot,
+          targetFile: "src/components/ReportsPanel.vue",
+          options: {}
+        }),
+      /must be relative to src\/pages\/, without a leading src\/ segment/
+    );
+  });
+});
+
+test("buildUiPageTemplateContext fails when the target file matches no surface", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+
+    await assert.rejects(
+      () =>
+        buildUiPageTemplateContext({
+          appRoot,
+          targetFile: "reports/index.vue",
+          options: {}
+        }),
+      /must be relative to src\/pages\/ and resolve to a configured surface/
+    );
+  });
+});
+
+test("buildUiPageTemplateContext chooses the most specific matching surface pagesRoot", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    app: { id: "app", pagesRoot: "", enabled: true },
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+
+    const context = await buildUiPageTemplateContext({
+      appRoot,
+      targetFile: "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");
+    assert.equal(context.__JSKIT_UI_LINK_NON_WORKSPACE_SUFFIX__, "/reports");
+  });
+});
+
+test("buildUiPageTemplateContext validates link placement format", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
 
     await assert.rejects(
       () =>
         buildUiPageTemplateContext({
           appRoot,
+          targetFile: "admin/reports/index.vue",
           options: {
-            placement: "invalid-placement"
+            "link-placement": "invalid-placement"
           }
         }),
       /option "placement" must be in "host:position" format/

package/test/elementSubcommand.test.js

@@ -76,17 +76,16 @@ export { MainClientProvider, registerMainClientComponent };
   );
 }
 
-test("ui-generator element subcommand creates component and outlet placement", async () => {
+test("ui-generator placed-element subcommand creates component and outlet placement", async () => {
   await withTempApp(async (appRoot) => {
     await writeAppFixture(appRoot);
 
     const result = await runGeneratorSubcommand({
       appRoot,
-      subcommand: "element",
+      subcommand: "placed-element",
       options: {
         name: "Ops Panel",
-        surface: "admin",
-        placement: "shell-layout:top-right"
+        surface: "admin"
       }
     });
 
@@ -111,12 +110,86 @@ test("ui-generator element subcommand creates component and outlet placement", a
   });
 });
 
-test("ui-generator element subcommand requires appRoot", async () => {
+test("ui-generator placed-element subcommand supports explicit placement override", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "placed-element",
+      options: {
+        name: "Ops Panel",
+        surface: "admin",
+        placement: "shell-layout:primary-menu"
+      }
+    });
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /host: "shell-layout"/);
+    assert.match(placementSource, /position: "primary-menu"/);
+  });
+});
+
+test("ui-generator placed-element subcommand refuses to overwrite an existing component without force", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+    await writeFile(
+      path.join(appRoot, "src", "components", "OpsPanelElement.vue"),
+      "<template><div>custom</div></template>\n",
+      "utf8"
+    );
+
+    await assert.rejects(
+      () =>
+        runGeneratorSubcommand({
+          appRoot,
+          subcommand: "placed-element",
+          options: {
+            name: "Ops Panel",
+            surface: "admin"
+          }
+        }),
+      /ui-generator placed-element will not overwrite existing component file src\/components\/OpsPanelElement\.vue\. Re-run with --force to overwrite it\./
+    );
+  });
+});
+
+test("ui-generator placed-element subcommand overwrites an existing component when force is enabled", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+    await writeFile(
+      path.join(appRoot, "src", "components", "OpsPanelElement.vue"),
+      "<template><div>custom</div></template>\n",
+      "utf8"
+    );
+
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "placed-element",
+      options: {
+        name: "Ops Panel",
+        surface: "admin",
+        force: "true"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [
+      "packages/main/src/client/providers/MainClientProvider.js",
+      "src/components/OpsPanelElement.vue",
+      "src/placement.js"
+    ]);
+
+    const componentSource = await readFile(path.join(appRoot, "src", "components", "OpsPanelElement.vue"), "utf8");
+    assert.match(componentSource, /<h2 class="text-h6 mb-2">Ops Panel<\/h2>/);
+  });
+});
+
+test("ui-generator placed-element subcommand requires appRoot", async () => {
   await assert.rejects(
     () =>
       runGeneratorSubcommand({
         appRoot: "",
-        subcommand: "element",
+        subcommand: "placed-element",
         options: {
           name: "Ops Panel",
           surface: "admin"