@lucasvu/scope-ui 0.1.0 → 0.1.1

package/bin/scope-ui-init.mjs

@@ -391,13 +391,14 @@ function createAgentsTemplate({ themeFile, layoutFile, themePreset, layoutPreset
   return `# Agent Rules
 
 This repo uses \`${PACKAGE_NAME}\` as the default UI library.
+Use \`${PACKAGE_NAME}\` for React components and \`${PACKAGE_NAME}/core\` for framework-agnostic theme/runtime contracts.
 This repo is locked to the \`${themePreset.label}\` theme preset (\`${themePreset.id}\`).
 This repo uses the \`${layoutPreset.label}\` shell preset (\`${layoutPreset.id}\`) as the shared layout baseline.
 
 Primary references:
 - \`node_modules/${PACKAGE_NAME}/README.md\`
 - \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`
-- \`uiScreenBlueprint\` and \`uiAiManifest\` from \`${PACKAGE_NAME}\`
+- \`uiScreenBlueprint\`, \`uiAiManifest\`, and \`uiThemeLayerAssets\` from \`${PACKAGE_NAME}/core\`
 - \`${themeFile}\`
 - \`${layoutFile}\`
 
@@ -408,20 +409,47 @@ Theme preset summary:
 Layout preset summary:
 ${renderMarkdownList(layoutPreset.shellRecipe)}
 
+## Workspace Base
+
+For Vite + micro frontend repos, keep this structure stable:
+
+- \`${PACKAGE_NAME}\` owns the React component surface
+- \`${PACKAGE_NAME}/core\` owns theme contracts, bundled theme layers, color-mode runtime, and framework-agnostic contracts
+- \`apps/shell\` owns the shared app shell, top-level routing, remote mounts, and theme imports
+- \`apps/*-mfe\` owns page-level business screens and feature routes
+
+If the repo still has a \`packages/shared\` folder, keep it for business utils or internal loaders, not for the primary theme runtime.
+
+Recommended folders:
+
+- shell: \`src/app\`, \`src/layouts\`, \`src/routes\`, \`src/remotes\`, \`src/styles/ui-theme.css\`
+- remote: \`src/features\`, \`src/pages\`, \`src/routes\`, \`src/services\`, \`src/styles/index.css\`
+
+Theme layers:
+
+1. Import \`${PACKAGE_NAME}/styles.css\` first.
+2. If the repo wants a bundled shell/theme layer, import one from \`${PACKAGE_NAME}/themes/*\` next.
+3. Import \`${themeFile}\` after the bundled theme layer.
+4. Keep app-specific overrides thin and token-based.
+
+If the bundled theme layer is client-theme-scoped, set \`data-client-theme\` with \`applyDocumentClientTheme(...)\`.
+
 ## Required Flow
 
 When asked to build or edit a screen, follow these steps in order:
 
 1. Read \`${themeFile}\`, \`${layoutFile}\`, \`node_modules/${PACKAGE_NAME}/README.md\`, \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`, and the exported \`uiScreenBlueprint\` contract before generating UI.
-2. Fill the shell brief and screen brief first. If a required field is missing, stop and ask for that exact value before writing JSX. Only leave TODO placeholders when the user explicitly asks for an incomplete scaffold.
-3. Verify the app entry imports \`${PACKAGE_NAME}/styles.css\` first and the project theme file right after it.
-4. Treat \`${layoutFile}\` as the source of truth for the app shell. Keep the dark sidebar, gradient topbar, intro card, and card-based body structure aligned with that preset unless the user explicitly asks for a different shell.
-5. Identify the page kind (\`list | form | detail | dashboard\`), then map each block to canonical components from \`uiAiManifest\` before writing JSX.
-6. Build the shell in this exact order: \`Sidebar\` -> workspace topbar -> intro card (\`Breadcrumb\` + \`PageTitle\`) -> optional segmented tabs -> toolbar card -> page body cards/grids.
-7. For list pages, build the toolbar card first and then the \`DataTable\`. For form pages, keep the same shell and swap the body into section cards and a bottom action row. For detail pages, keep the shell and render summary/detail cards plus related tables. For dashboard pages, keep the shell and render stat cards plus supporting cards/tables.
-8. If \`${layoutFile}\` says a slot is optional, omit it cleanly when the brief does not request it. Do not invent tabs, workspace labels, filters, or toolbar actions.
-9. Keep all colors, radius, surface, and shadow decisions inside \`${themeFile}\`. If the preset is insufficient, update tokens there instead of styling one page ad hoc.
-10. Before finishing, run the output checklist in this file.
+2. If the task touches app bootstrap, shell setup, or micro frontend structure, scaffold the repo around the workspace base above before writing page JSX.
+3. Fill the shell brief and screen brief first. If a required field is missing, stop and ask for that exact value before writing JSX. Only leave TODO placeholders when the user explicitly asks for an incomplete scaffold.
+4. Verify the app entry imports \`${PACKAGE_NAME}/styles.css\` first, then any bundled theme layer from \`${PACKAGE_NAME}/themes/*\`, then \`${themeFile}\`.
+5. Treat \`${layoutFile}\` as the source of truth for the app shell. Keep the dark sidebar, gradient topbar, intro card, and card-based body structure aligned with that preset unless the user explicitly asks for a different shell.
+6. Keep the shell in the host app. Do not let a remote rebuild its own global shell unless the task explicitly asks for a standalone shell.
+7. Identify the page kind (\`list | form | detail | dashboard\`), then map each block to canonical components from \`uiAiManifest\` before writing JSX.
+8. Build the shell in this exact order: \`Sidebar\` -> workspace topbar -> intro card (\`Breadcrumb\` + \`PageTitle\`) -> optional segmented tabs -> toolbar card -> page body cards/grids.
+9. For list pages, build the toolbar card first and then the \`DataTable\`. For form pages, keep the same shell and swap the body into section cards and a bottom action row. For detail pages, keep the shell and render summary/detail cards plus related tables. For dashboard pages, keep the shell and render stat cards plus supporting cards/tables.
+10. If \`${layoutFile}\` says a slot is optional, omit it cleanly when the brief does not request it. Do not invent tabs, workspace labels, filters, or toolbar actions.
+11. Keep all colors, radius, surface, and shadow decisions inside \`${themeFile}\`. If the preset is insufficient, update tokens there instead of styling one page ad hoc.
+12. Before finishing, run the output checklist in this file.
 
 ## Ask For Missing Input
 
@@ -522,12 +550,18 @@ ${renderMarkdownList(layoutPreset.shellRecipe)}
 ## Hard Rules
 
 - import \`${PACKAGE_NAME}/styles.css\` once at the app entry
-- import the project theme override file after the package stylesheet
-- use root exports from \`${PACKAGE_NAME}\`
+- import a bundled theme layer from \`${PACKAGE_NAME}/themes/*\` after the package stylesheet when the repo chooses one
+- import the project theme override file after the bundled theme layer
+- use \`applyDocumentClientTheme\` when the chosen bundled theme layer is client-theme-scoped
+- use root exports from \`${PACKAGE_NAME}\` for React components
+- use \`${PACKAGE_NAME}/core\` for theme/runtime utilities in non-React or mixed-framework setup
 - use \`${themeFile}\` as the only source of truth for colors, radius, surfaces, and shadows
 - use \`${layoutFile}\` as the source of truth for the shell layout and shared page frame
 - keep layouts and component choices aligned with the shared preset-driven UI used across projects
+- keep the host shell responsible for sidebar, topbar, remote mount, and theme mode
+- keep remotes focused on feature routes and page business content
 - read \`uiAiManifest\` before choosing components
+- read \`uiThemeLayerAssets\` before choosing a bundled theme layer
 - read \`uiThemeContract\` before changing colors, surfaces, borders, radius, or shadows
 - keep UI token-driven and theme-driven
 
@@ -537,6 +571,7 @@ Do not:
 - replace the shared dark-sidebar + gradient-topbar shell with a flat blank layout unless the user explicitly requests it
 - restyle individual pages if the preset tokens can solve it globally
 - create duplicate Button/Input/Select wrappers unless a project-specific behavior is required
+- let each remote define a different shell or a different palette
 
 ## Component Choice
 
@@ -561,6 +596,8 @@ Before finishing, confirm all of these are true:
 - No \`MainFe\` imports were used.
 - No hardcoded brand colors were added in page components.
 - Theme decisions live in \`${themeFile}\`, not in ad hoc JSX styling.
+- The app entry import order is package stylesheet -> bundled theme layer if present -> project theme override.
+- The shell still lives in the host app and remotes only own business screens.
 - Spacing, card structure, and actions are consistent with the shared preset.
 - The layout shell stayed stable even if the page body changed.
 `
@@ -605,6 +642,24 @@ ${layoutPreset.requiredFields.map((item) => `    '${item}',`).join('\n')}
   askBeforeCoding: [
 ${layoutPreset.askBeforeCoding.map((item) => `    '${item}',`).join('\n')}
   ],
+  workspaceStructure: {
+    packageUi: ['components', 'theme contracts', 'bundled theme layers', 'color-mode runtime'],
+    shellApp: ['src/app', 'src/layouts', 'src/routes', 'src/remotes', 'src/styles/ui-theme.css'],
+    remoteApp: ['src/features', 'src/pages', 'src/routes', 'src/services', 'src/styles/index.css'],
+  },
+  themeLayers: [
+    '${PACKAGE_NAME}/styles.css',
+    '${PACKAGE_NAME}/themes/theme-ui-new-main-fe.css (optional bundled package layer)',
+    '${themeFile}',
+  ],
+  setupSteps: [
+    'Import the package stylesheet once at the host app entry.',
+    'If the app wants a bundled package theme layer, import it after the package stylesheet.',
+    'Import the project themeSource after the bundled theme layer.',
+    'If the chosen theme layer is client-theme-scoped, set data-client-theme at the document root.',
+    'Initialize color mode at the host app entry and let the host own shell/theme concerns.',
+    'Keep remotes focused on feature routes and business screens instead of rebuilding the global shell.',
+  ],
   shell: {
     sidebar: {
       tone: 'dark',
@@ -641,6 +696,8 @@ ${layoutPreset.askBeforeCoding.map((item) => `    '${item}',`).join('\n')}
     'Keep the dark sidebar and gradient topbar shell stable across screens.',
     'Do not replace the intro card with a bare page title row.',
     'Use the shared theme tokens from the themeSource file for color, border, surface, and shadow decisions.',
+    'Import theme layers in this order: package stylesheet, bundled package theme layer when present, then themeSource.',
+    'Keep the host app responsible for the global shell and keep remotes page-scoped.',
     'Only omit tabs or toolbar sections when the brief explicitly leaves them out.',
     'Ask for missing required fields before generating JSX instead of guessing from the screenshot.',
   ],
@@ -720,6 +777,8 @@ console.log(`- ${layoutResult.path}: ${layoutResult.status}`)
 console.log('')
 console.log('Next steps:')
 console.log(`1. Import \`${PACKAGE_NAME}/styles.css\` once at your app entry.`)
-console.log(`2. Import \`${options.themeFile}\` right after the package stylesheet.`)
-console.log(`3. Let your agent read \`${options.agentsFile}\` and \`${options.layoutFile}\` before generating UI.`)
-console.log(`4. Re-run this command with \`--theme <preset> --force\` if you want another approved preset.`)
+console.log(`2. If you want a bundled package theme layer, import one from \`${PACKAGE_NAME}/themes/*\` right after the package stylesheet.`)
+console.log(`3. Import \`${options.themeFile}\` after the bundled theme layer.`)
+console.log(`4. Let your agent read \`${options.agentsFile}\` and \`${options.layoutFile}\` before generating UI.`)
+console.log('5. Keep the host app responsible for the global shell and keep remotes page-scoped.')
+console.log(`6. Re-run this command with \`--theme <preset> --force\` if you want another approved preset.`)