create-middag-ui 0.16.0 → 0.18.0

package/cli.js

@@ -29,6 +29,8 @@ import {
   scaffoldDemoFiles,
   scaffoldDevShell,
   scaffoldEslintConfig,
+  scaffoldGitignore,
+  scaffoldInjectPlaceholders,
   scaffoldFreeAdapters,
   scaffoldFreeApp,
   scaffoldFreeRegister,
@@ -38,6 +40,8 @@ import {
   scaffoldHostViteConfig,
   scaffoldIndexHtml,
   scaffoldMoodleAdapters,
+  scaffoldMoodleAdminShell,
+  scaffoldMoodlePageResolver,
   scaffoldMoodlePlugin,
   scaffoldMoodleTailwind,
   scaffoldPackageJson,
@@ -166,11 +170,13 @@ if (!dirCreated) {
 
 heading(5, TOTAL_STEPS, "Scaffolding config files");
 
+const isPro = registryPath === "github";
 scaffoldPackageJson(targetDir, host, cwd, registryPath, hostKey);
 scaffoldTsconfig(targetDir);
 scaffoldViteConfig(targetDir, host, registryPath);
-scaffoldEslintConfig(targetDir);
+scaffoldEslintConfig(targetDir, isPro);
 scaffoldPrettierConfig(targetDir);
+scaffoldGitignore(targetDir, isPro);
 scaffoldIndexHtml(targetDir);
 
 // ── Step 6: Scaffold ~/.npmrc (GitHub path only) ─────────────────────────
@@ -192,13 +198,16 @@ scaffoldDemoFiles(targetDir);
 
 // ── Step 8: Scaffold app + page examples (PRO vs FREE) ─────────────────
 
-const isPro = registryPath === "github";
 heading(8, TOTAL_STEPS, `Creating ${isPro ? "PRO" : "FREE"} UI module`);
 
 scaffoldPageExamples(targetDir);
 
-// Shared files (both PRO and FREE)
-scaffoldPageResolver(targetDir);
+// Page resolver — Moodle gets AMD version (RequireJS + extension globs)
+if (hostKey === "moodle") {
+  scaffoldMoodlePageResolver(targetDir);
+} else {
+  scaffoldPageResolver(targetDir);
+}
 scaffoldDemoDirectPage(targetDir);
 // Convert frankenstyle "local_middag" → Moodle path "local/middag"
 const moodlePath = moodleComponent ? moodleComponent.replace("_", "/") : null;
@@ -217,6 +226,7 @@ if (isPro) {
     // PRO Inertia adapters — re-export from @middag-io/react/mock so usePage()
     // shares the same React context as MockPageProvider (no context mismatch).
     scaffoldProAdapters(targetDir);
+    scaffoldInjectPlaceholders(targetDir);
     success("PRO: using MockProductShell from @middag-io/react/mock");
   } catch {
     // npm version — PRO file excluded, fall back to FREE
@@ -245,7 +255,8 @@ if (hostKey === "moodle" && moodleComponent) {
   scaffoldMoodlePlugin(targetDir, moodleComponent);
   scaffoldMoodleTailwind(targetDir);
   scaffoldMoodleAdapters(targetDir, moodleComponent);
-  success(`Moodle: AMD plugin + Tailwind + adapters for ${ moodleComponent }`);
+  scaffoldMoodleAdminShell(targetDir);
+  success(`Moodle: AMD plugin + Tailwind + adapters + AdminShell for ${ moodleComponent }`);
 }
 
 // ── Step 9: npm install ──────────────────────────────────────────────────

package/lib/scaffold.js

@@ -2,7 +2,7 @@
  * scaffold.js — File creation for all scaffolded files.
  *
  * Creates directory structure, config files, page examples, app entry,
- * and Inertia mock adapters. Everything lives under src/.
+ * and Inertia mock adapters. Dev-only adapters live under mock/.
  *
  * Every I/O operation is wrapped with error handling.
  */
@@ -127,17 +127,30 @@ export function scaffoldPackageJson(targetDir, host, cwd, registryPath, hostKey)
   if (hostKey === "wordpress") {
     scripts["build:wp"] = "vite build --config vite.config.wordpress.ts";
     scripts["watch:wp"] = "vite build --config vite.config.wordpress.ts --watch";
+    if (isPro) {
+      scripts["build:licensed"] =
+        "vite build --config vite.config.wordpress.ts && node scripts/inject-placeholders.mjs";
+    }
   } else if (hostKey === "moodle") {
     scripts["build:moodle"] = "vite build --config vite.config.moodle.ts";
     scripts["watch:moodle"] = "vite build --config vite.config.moodle.ts --watch";
+    if (isPro) {
+      scripts["build:licensed"] =
+        "vite build --config vite.config.moodle.ts && node scripts/inject-placeholders.mjs";
+    }
   } else if (hostKey === "custom") {
     scripts["build:host"] = "vite build --config vite.config.custom.ts";
     scripts["watch:host"] = "vite build --config vite.config.custom.ts --watch";
+    if (isPro) {
+      scripts["build:licensed"] =
+        "vite build --config vite.config.custom.ts && node scripts/inject-placeholders.mjs";
+    }
   }
 
   const pkg = {
     name: `${projectName}-ui`,
     private: true,
+    version: "0.1.0",
     type: "module",
     scripts,
     dependencies: deps,
@@ -190,6 +203,11 @@ export function scaffoldTsconfig(targetDir) {
   };
 
   writeFile(filePath, JSON.stringify(tsconfig, null, 2) + "\n", "tsconfig.json");
+
+  const envFilePath = join(targetDir, "src", "vite-env.d.ts");
+  if (!skipIfExists(envFilePath, "src/vite-env.d.ts")) {
+    writeFile(envFilePath, `/// <reference types="vite/client" />\n`, "src/vite-env.d.ts");
+  }
 }
 
 /**
@@ -226,9 +244,10 @@ export default defineConfig({
   resolve: {
     alias: {
       "@/": resolve(__dirname, "src") + "/",
+      "@mock/": resolve(__dirname, "mock") + "/",
       ${adapterComment}
-      "@inertiajs/react": resolve(__dirname, "src/adapters/inertia-react.ts"),
-      "@inertiajs/core": resolve(__dirname, "src/adapters/inertia-core.ts"),
+      "@inertiajs/react": resolve(__dirname, "mock/adapters/inertia-react.ts"),
+      "@inertiajs/core": resolve(__dirname, "mock/adapters/inertia-core.ts"),
     },
   },
 });
@@ -240,10 +259,13 @@ export default defineConfig({
 /**
  * Scaffold eslint.config.js.
  */
-export function scaffoldEslintConfig(targetDir) {
+export function scaffoldEslintConfig(targetDir, isPro = false) {
   const filePath = join(targetDir, "eslint.config.js");
   if (skipIfExists(filePath, "eslint.config.js")) return;
 
+  const ignores = ["dist/", "node_modules/", "scripts/", ...(isPro ? ["dist-licensed/"] : [])];
+  const ignoresStr = ignores.map((i) => `"${i}"`).join(", ");
+
   writeFile(
     filePath,
     `import js from "@eslint/js";
@@ -253,7 +275,7 @@ import reactRefresh from "eslint-plugin-react-refresh";
 import prettierConfig from "eslint-config-prettier";
 
 export default tseslint.config(
-  { ignores: ["dist/", "node_modules/"] },
+  { ignores: [${ignoresStr}] },
   js.configs.recommended,
   ...tseslint.configs.recommended,
   {
@@ -263,7 +285,8 @@ export default tseslint.config(
       "react-refresh": reactRefresh,
     },
     rules: {
-      ...reactHooks.configs.recommended.rules,
+      "react-hooks/rules-of-hooks": "error",
+      "react-hooks/exhaustive-deps": "warn",
       "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
       "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
       "@typescript-eslint/no-explicit-any": "warn",
@@ -293,6 +316,7 @@ export function scaffoldPrettierConfig(targetDir) {
         trailingComma: "all",
         printWidth: 100,
         plugins: ["prettier-plugin-tailwindcss"],
+        tailwindFunctions: ["cn", "cva"],
       },
       null,
       2,
@@ -301,6 +325,99 @@ export function scaffoldPrettierConfig(targetDir) {
   );
 }
 
+/**
+ * Scaffold .gitignore with UI-specific dist patterns.
+ */
+export function scaffoldGitignore(targetDir, isPro = false) {
+  const filePath = join(targetDir, ".gitignore");
+  if (skipIfExists(filePath, ".gitignore")) return;
+
+  const lines = [
+    "node_modules/",
+    "dist/",
+    ...(isPro ? ["dist-licensed/"] : []),
+    "dist-master/",
+    "dist-mock/",
+    "dist-lib/",
+    "*.log",
+    ".vite/",
+  ];
+  writeFile(filePath, lines.join("\n") + "\n", ".gitignore");
+}
+
+/**
+ * Scaffold scripts/inject-placeholders.mjs (PRO only).
+ * Injects opaque placeholder variables into middag-* bundles for CDN delivery.
+ * The Cloudflare Worker replaces placeholders with per-installation values.
+ */
+export function scaffoldInjectPlaceholders(targetDir) {
+  const scriptsDir = join(targetDir, "scripts");
+  mkdirSync(scriptsDir, { recursive: true });
+  const filePath = join(scriptsDir, "inject-placeholders.mjs");
+  if (skipIfExists(filePath, "scripts/inject-placeholders.mjs")) return;
+
+  writeFile(
+    filePath,
+    `/**
+ * inject-placeholders — generate licensed bundles for CDN delivery.
+ *
+ * Takes compiled Vite output from dist/ and produces dist-licensed/ with
+ * placeholder variables injected into middag-* bundles. The Cloudflare
+ * Worker replaces these placeholders with real values per installation.
+ *
+ * Usage: node scripts/inject-placeholders.mjs
+ * Called by: npm run build:licensed
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const DIST_DIR = path.resolve(import.meta.dirname, "../dist");
+const LICENSED_DIR = path.resolve(import.meta.dirname, "../dist-licensed");
+
+// Variable names are intentionally opaque to discourage reverse engineering.
+// The mapping is documented only here and in the Worker source:
+//   _0x7a3f → wwwroot        (replaced by Worker with installation URL)
+//   _0x9b1e → expiry         (replaced by Worker with unix timestamp)
+//   _0x4d2c → tier           (replaced by Worker with license tier)
+//   _0x6e8a → domain hash    (replaced by Worker with HMAC of wwwroot)
+const PLACEHOLDER_HEADER = [
+  'var _0x7a3f="__PH_0x7a3f__";',
+  "var _0x9b1e=0;",
+  'var _0x4d2c="__PH_0x4d2c__";',
+  'var _0x6e8a="__PH_0x6e8a__";',
+].join("") + "\\n";
+
+if (fs.existsSync(LICENSED_DIR)) fs.rmSync(LICENSED_DIR, { recursive: true });
+fs.mkdirSync(LICENSED_DIR, { recursive: true });
+
+const files = fs.readdirSync(DIST_DIR).filter((f) => f.endsWith(".js"));
+let injected = 0;
+let copied = 0;
+
+for (const file of files) {
+  const srcPath = path.join(DIST_DIR, file);
+  const destPath = path.join(LICENSED_DIR, file);
+  const content = fs.readFileSync(srcPath, "utf-8");
+
+  if (file.startsWith("middag-")) {
+    fs.writeFileSync(destPath, PLACEHOLDER_HEADER + content);
+    injected++;
+    console.log(\`[licensed] \${file} — placeholders injected\`);
+  } else {
+    fs.copyFileSync(srcPath, destPath);
+    copied++;
+    console.log(\`[licensed] \${file} — copied (vendor/shared)\`);
+  }
+}
+
+console.log(\`\\nLicensed bundles ready in \${LICENSED_DIR}/\`);
+console.log(\`  \${injected} bundle(s) with placeholders\`);
+console.log(\`  \${copied} bundle(s) copied as-is\`);
+`,
+    "scripts/inject-placeholders.mjs",
+  );
+}
+
 /**
  * Scaffold index.html at project root.
  */
@@ -934,12 +1051,12 @@ export const settingsContract: PageContract = {
  */
 export function scaffoldProApp(targetDir) {
   ensureDir(join(targetDir, "src"));
-  ensureDir(join(targetDir, "src", "adapters"));
+  ensureDir(join(targetDir, "mock", "adapters"));
 
   // Inertia adapter shims — re-export from pre-built mock bundle
   // so usePage() shares the same MockPageContext as MockPageProvider.
-  const adapterReactPath = join(targetDir, "src", "adapters", "inertia-react.ts");
-  if (!skipIfExists(adapterReactPath, "src/adapters/inertia-react.ts")) {
+  const adapterReactPath = join(targetDir, "mock", "adapters", "inertia-react.ts");
+  if (!skipIfExists(adapterReactPath, "mock/adapters/inertia-react.ts")) {
     writeFile(adapterReactPath, `/**
  * Mock @inertiajs/react — re-exports from pre-built @middag-io/react/mock.
  *
@@ -947,16 +1064,16 @@ export function scaffoldProApp(targetDir) {
  * MockPageProvider (both live in the pre-built ESM bundle).
  */
 export { usePage, Head, Link, router } from "@middag-io/react/mock";
-`, "src/adapters/inertia-react.ts");
+`, "mock/adapters/inertia-react.ts");
   }
 
-  const adapterCorePath = join(targetDir, "src", "adapters", "inertia-core.ts");
-  if (!skipIfExists(adapterCorePath, "src/adapters/inertia-core.ts")) {
+  const adapterCorePath = join(targetDir, "mock", "adapters", "inertia-core.ts");
+  if (!skipIfExists(adapterCorePath, "mock/adapters/inertia-core.ts")) {
     writeFile(adapterCorePath, `/**
  * Mock @inertiajs/core — re-exports from pre-built @middag-io/react/mock.
  */
 export { router, setMockNavigate } from "@middag-io/react/mock";
-`, "src/adapters/inertia-core.ts");
+`, "mock/adapters/inertia-core.ts");
   }
 
   const mainPath = join(targetDir, "src", "main.tsx");
@@ -1053,13 +1170,13 @@ export function App() {
 }
 
 /**
- * Scaffold FREE adapters: src/adapters/ with react-router.
+ * Scaffold FREE adapters: mock/adapters/ with react-router.
  */
 export function scaffoldFreeAdapters(targetDir) {
-  ensureDir(join(targetDir, "src", "adapters"));
+  ensureDir(join(targetDir, "mock", "adapters"));
 
-  const corePath = join(targetDir, "src", "adapters", "inertia-core.ts");
-  if (!skipIfExists(corePath, "src/adapters/inertia-core.ts")) {
+  const corePath = join(targetDir, "mock", "adapters", "inertia-core.ts");
+  if (!skipIfExists(corePath, "mock/adapters/inertia-core.ts")) {
     writeFile(corePath, `/**
  * Mock @inertiajs/core for standalone dev server.
  * Vite alias redirects @inertiajs/core here.
@@ -1078,11 +1195,11 @@ export const router = {
   visit: (url: string) => { _navigate ? _navigate(url) : console.log("[mock] VISIT", url); },
   on: () => () => {},
 };
-`, "src/adapters/inertia-core.ts");
+`, "mock/adapters/inertia-core.ts");
   }
 
-  const reactPath = join(targetDir, "src", "adapters", "inertia-react.ts");
-  if (!skipIfExists(reactPath, "src/adapters/inertia-react.ts")) {
+  const reactPath = join(targetDir, "mock", "adapters", "inertia-react.ts");
+  if (!skipIfExists(reactPath, "mock/adapters/inertia-react.ts")) {
     writeFile(reactPath, `/**
  * Mock @inertiajs/react for standalone dev server (FREE).
  * Context-based usePage + react-router Link.
@@ -1127,7 +1244,7 @@ export const Link = React.forwardRef<HTMLAnchorElement, MockLinkProps>(function
 });
 
 export { router };
-`, "src/adapters/inertia-react.ts");
+`, "mock/adapters/inertia-react.ts");
   }
 }
 
@@ -1139,20 +1256,20 @@ export { router };
  * defining their own context (which would cause context mismatch).
  */
 export function scaffoldProAdapters(targetDir) {
-  ensureDir(join(targetDir, "src", "adapters"));
+  ensureDir(join(targetDir, "mock", "adapters"));
 
-  const corePath = join(targetDir, "src", "adapters", "inertia-core.ts");
-  if (!skipIfExists(corePath, "src/adapters/inertia-core.ts")) {
+  const corePath = join(targetDir, "mock", "adapters", "inertia-core.ts");
+  if (!skipIfExists(corePath, "mock/adapters/inertia-core.ts")) {
     writeFile(corePath, `/**
  * Mock @inertiajs/core — PRO re-export from @middag-io/react/mock.
  * Shares the same navigate function as MockProductShell.
  */
 export { router, setMockNavigate } from "@middag-io/react/mock";
-`, "src/adapters/inertia-core.ts (PRO)");
+`, "mock/adapters/inertia-core.ts (PRO)");
   }
 
-  const reactPath = join(targetDir, "src", "adapters", "inertia-react.ts");
-  if (!skipIfExists(reactPath, "src/adapters/inertia-react.ts")) {
+  const reactPath = join(targetDir, "mock", "adapters", "inertia-react.ts");
+  if (!skipIfExists(reactPath, "mock/adapters/inertia-react.ts")) {
     writeFile(reactPath, `/**
  * Mock @inertiajs/react — PRO re-export from @middag-io/react/mock.
  * Shares the same React context as MockPageProvider so usePage()
@@ -1160,7 +1277,7 @@ export { router, setMockNavigate } from "@middag-io/react/mock";
  */
 export { usePage, Head, Link } from "@middag-io/react/mock";
 export { router } from "./inertia-core";
-`, "src/adapters/inertia-react.ts (PRO)");
+`, "mock/adapters/inertia-react.ts (PRO)");
   }
 }
 
@@ -1270,8 +1387,8 @@ createRoot(document.getElementById("root")!).render(
 import { BrowserRouter, Routes, Route, useNavigate } from "react-router";
 import { ContractPage, I18nProvider } from "@middag-io/react";
 import type { PageContract } from "@middag-io/react";
-import { PageProvider } from "./adapters/inertia-react";
-import { setMockNavigate } from "./adapters/inertia-core";
+import { PageProvider } from "@mock/adapters/inertia-react";
+import { setMockNavigate } from "@mock/adapters/inertia-core";
 import { dashboardContract } from "./pages/dashboard";
 import { connectorsContract } from "./pages/connectors";
 import { settingsContract } from "./pages/settings";
@@ -1374,26 +1491,91 @@ export function scaffoldHostEntry(targetDir, hostKey) {
     });
     observer.observe(document.body, { childList: true, subtree: true });`;
   } else if (hostKey === "moodle") {
-    extraImports = `import "./tailwind.css";
-import "@fontsource-variable/figtree";`;
-    setupCode = `    document.body.classList.add("middag-active");
+    // Moodle uses a dedicated content block — see below.
+  }
+
+  // Moodle: fully separate entry (asyncResolver, full provider stack, theme init, AdminShell)
+  if (hostKey === "moodle") {
+    const moodleContent = `/**
+ * Production entry point for Moodle.
+ *
+ * AMD module loaded by Moodle's RequireJS via js_call_amd().
+ * Uses real createInertiaApp — Moodle serves the HTML and page props.
+ * This is the build target for \`npm run build\`.
+ *
+ * NOT used by \`npm run dev\` — that uses src/main.tsx with mock adapters.
+ */
+import "./tailwind.css";
+import "@fontsource-variable/figtree";
+
+import { createRoot } from "react-dom/client";
+import { createInertiaApp } from "@inertiajs/react";
+import {
+  I18nProvider,
+  ProgressProvider,
+  AuthProvider,
+  FlashProvider,
+  ScopeProvider,
+  setAppearance,
+  getStoredAppearance,
+  getEffectiveTheme,
+  onSystemThemeChange,
+} from "@middag-io/react";
+import "@middag-io/react/style.css";
+import { getString } from "./lib/moodle/strings";
+import { registerDefaults } from "./app/register";
+import { resolvePageComponent } from "./app/page-resolver";
+
+registerDefaults();
+setAppearance(getStoredAppearance());
+onSystemThemeChange();
+
+createInertiaApp({
+  id: "middag-app",
+  resolve: (name) => resolvePageComponent(name),
+  setup({ el, App, props }) {
+    el.classList.add("middag-root");
+    el.classList.add("middag-active");
+    el.setAttribute("data-theme", getEffectiveTheme(getStoredAppearance()));
 
     // Portal container for Radix UI (modals, popovers, toasts).
     // Radix portals default to document.body which is outside .middag-root,
-    // meaning scoped Tailwind styles won't apply. This creates a sibling
-    // container with .middag-root so portal content inherits design tokens.
+    // so this sibling container ensures portal content inherits design tokens.
     if (!document.getElementById("middag-portals")) {
-      const portalContainer = document.createElement("div");
-      portalContainer.id = "middag-portals";
-      portalContainer.classList.add("middag-root");
-      document.body.appendChild(portalContainer);
-    }`;
+      const portals = document.createElement("div");
+      portals.id = "middag-portals";
+      portals.classList.add("middag-root");
+      document.body.appendChild(portals);
+    }
+
+    createRoot(el).render(
+      <ProgressProvider>
+        <App {...props}>
+          {({ Component, props: pageProps, key }) => (
+            <AuthProvider>
+              <ScopeProvider>
+                <FlashProvider>
+                  <I18nProvider asyncResolver={getString}>
+                    <Component key={key} {...pageProps} />
+                  </I18nProvider>
+                </FlashProvider>
+              </ScopeProvider>
+            </AuthProvider>
+          )}
+        </App>
+      </ProgressProvider>,
+    );
+  },
+});
+`;
+    writeFile(filePath, moodleContent, label);
+    return;
   }
 
   const content = `/**
- * Production entry point for ${hostKey === "wordpress" ? "WordPress" : hostKey === "moodle" ? "Moodle" : "custom host"}.
+ * Production entry point for ${hostKey === "wordpress" ? "WordPress" : "custom host"}.
  *
- * Uses real createInertiaApp — the host platform (${hostKey === "wordpress" ? "WP" : hostKey === "moodle" ? "Moodle" : "your backend"})
+ * Uses real createInertiaApp — the host platform (${hostKey === "wordpress" ? "WP" : "your backend"})
  * serves the HTML and Inertia page props. This file is the build target
  * for \`npm run build:${hostKey === "custom" ? "host" : hostKey}\`.
  *
@@ -1726,7 +1908,7 @@ body.middag-active [data-slot="sidebar-container"] {
 /** @deprecated Use scaffoldFreeApp + scaffoldFreeAdapters instead */
 export function scaffoldAppFiles(targetDir) {
   ensureDir(join(targetDir, "src"));
-  ensureDir(join(targetDir, "src", "adapters"));
+  ensureDir(join(targetDir, "mock", "adapters"));
 
   // src/main.tsx — entry point
   const mainPath = join(targetDir, "src", "main.tsx");
@@ -1821,9 +2003,9 @@ export function App() {
     );
   }
 
-  // src/adapters/inertia-react.ts
-  const inertiaReactPath = join(targetDir, "src", "adapters", "inertia-react.ts");
-  if (!skipIfExists(inertiaReactPath, "src/adapters/inertia-react.ts")) {
+  // mock/adapters/inertia-react.ts
+  const inertiaReactPath = join(targetDir, "mock", "adapters", "inertia-react.ts");
+  if (!skipIfExists(inertiaReactPath, "mock/adapters/inertia-react.ts")) {
     writeFile(
       inertiaReactPath,
       `/**
@@ -1934,13 +2116,13 @@ export const Link = React.forwardRef<HTMLAnchorElement, MockLinkProps>(function
 
 export { router };
 `,
-      "src/adapters/inertia-react.ts",
+      "mock/adapters/inertia-react.ts",
     );
   }
 
-  // src/adapters/inertia-core.ts
-  const inertiaCorePath = join(targetDir, "src", "adapters", "inertia-core.ts");
-  if (!skipIfExists(inertiaCorePath, "src/adapters/inertia-core.ts")) {
+  // mock/adapters/inertia-core.ts
+  const inertiaCorePath = join(targetDir, "mock", "adapters", "inertia-core.ts");
+  if (!skipIfExists(inertiaCorePath, "mock/adapters/inertia-core.ts")) {
     writeFile(
       inertiaCorePath,
       `/**
@@ -1960,7 +2142,7 @@ export const router = {
   on: () => () => {},
 };
 `,
-      "src/adapters/inertia-core.ts",
+      "mock/adapters/inertia-core.ts",
     );
   }
 }
@@ -1995,6 +2177,37 @@ export function scaffoldPageResolver(targetDir) {
   writeFile(filePath, readTemplate("templates/shared/page-resolver.tsx"), "src/app/page-resolver.tsx");
 }
 
+/**
+ * Scaffold Moodle AMD page resolver: src/app/page-resolver.tsx.
+ *
+ * Overwrites the generic resolver with a Moodle-specific version that supports:
+ * - Eager core pages (../extensions/core/pages/**)
+ * - Lazy non-core extension pages (separate AMD chunks)
+ * - External plugin pages via RequireJS (frankenstyle prefix)
+ *
+ * @param {string} targetDir - Absolute path to UI project root
+ */
+export function scaffoldMoodlePageResolver(targetDir) {
+  ensureDir(join(targetDir, "src", "app"));
+  const filePath = join(targetDir, "src", "app", "page-resolver.tsx");
+  writeFile(filePath, readTemplate("templates/shared/page-resolver-moodle.tsx"), "src/app/page-resolver.tsx (Moodle AMD)");
+}
+
+/**
+ * Scaffold Moodle admin shell: src/shells/AdminShell.tsx.
+ *
+ * Moodle-specific shell that supports the admin_tabs shared prop.
+ * Registered as 'admin' shell in src/entry-moodle.tsx.
+ *
+ * @param {string} targetDir - Absolute path to UI project root
+ */
+export function scaffoldMoodleAdminShell(targetDir) {
+  ensureDir(join(targetDir, "src", "shells"));
+  const filePath = join(targetDir, "src", "shells", "AdminShell.tsx");
+  if (skipIfExists(filePath, "src/shells/AdminShell.tsx")) return;
+  writeFile(filePath, readTemplate("templates/shared/moodle-admin-shell.tsx"), "src/shells/AdminShell.tsx");
+}
+
 /**
  * Scaffold route helper: src/lib/routes.ts.
  * Abstracts host admin URL vs dev mock path.

package/lib/templates/shared/moodle-admin-shell.tsx

@@ -0,0 +1,108 @@
+/**
+ * AdminShell — Moodle-specific admin shell.
+ *
+ * Extends ProductShell architecture with an optional admin tab bar
+ * rendered when the `admin_tabs` Inertia shared prop is present.
+ *
+ * Registered as 'admin' shell in src/entry-moodle.tsx.
+ * Edit this file to customise the admin sidebar header, tab bar, or layout.
+ */
+import { useCallback, type ReactElement } from "react";
+import { Link, usePage } from "@inertiajs/react";
+import {
+    Toaster,
+    Sidebar,
+    SidebarHeader,
+    SidebarProvider,
+    useSidebar,
+    SidebarNav,
+    PageHeader,
+    NavErrorBoundary,
+    type ShellProps,
+    type SharedProps,
+    type PageMeta,
+    type AdminTabsProps,
+} from "@middag-io/react";
+import { Tabs, TabsList, TabsTrigger } from "@middag-io/react/reui/tabs";
+
+// ── Inner shell (must be inside SidebarProvider) ──────────────────────────────
+
+function AdminShellInner({ children }: ShellProps): ReactElement {
+    const { setOpenMobile } = useSidebar();
+    const { props } = usePage<SharedProps>();
+
+    const page: PageMeta = (props as SharedProps & { contract?: { page?: PageMeta } }).contract
+        ?.page ?? { key: "unknown", title: "", breadcrumbs: [], actions: [] };
+
+    const adminTabs = (props as SharedProps & { admin_tabs?: AdminTabsProps }).admin_tabs;
+
+    const handleMobileMenuClick = useCallback(() => {
+        setOpenMobile(true);
+    }, [setOpenMobile]);
+
+    return (
+        <>
+            <Sidebar
+                aria-label="Navegação"
+                collapsible="icon"
+                className="border-sidebar-border bg-sidebar border-r"
+            >
+                <SidebarHeader className="border-sidebar-border border-b px-4 py-3">
+                    {/* Replace with your plugin name or logo */}
+                    <p className="text-sidebar-foreground text-sm font-semibold">Admin</p>
+                </SidebarHeader>
+
+                <NavErrorBoundary>
+                    <SidebarNav />
+                </NavErrorBoundary>
+            </Sidebar>
+
+            <div className="admin-shell__content flex min-h-screen flex-1 flex-col overflow-hidden">
+                <NavErrorBoundary>
+                    <PageHeader page={page} onMobileMenuClick={handleMobileMenuClick} />
+                </NavErrorBoundary>
+
+                {adminTabs && (
+                    <div className="border-b px-6">
+                        <Tabs value={adminTabs.active}>
+                            <TabsList variant="line" className="w-full justify-start">
+                                {adminTabs.items.map((tab) => (
+                                    <TabsTrigger key={tab.key} value={tab.key} asChild>
+                                        <Link href={tab.href} preserveState>
+                                            {tab.label}
+                                        </Link>
+                                    </TabsTrigger>
+                                ))}
+                            </TabsList>
+                        </Tabs>
+                    </div>
+                )}
+
+                <main className="flex-1 overflow-auto p-6" aria-live="polite" aria-busy="false">
+                    {children}
+                </main>
+            </div>
+
+            <Toaster position="bottom-right" richColors />
+        </>
+    );
+}
+
+// ── AdminShell — public export ──────────────────────────────────────────────
+
+export function AdminShell({ children }: ShellProps): ReactElement {
+    return (
+        <SidebarProvider
+            defaultOpen={true}
+            style={
+                {
+                    "--sidebar-width": "var(--sidebar-width)",
+                    "--sidebar-width-icon": "var(--sidebar-width-collapsed)",
+                } as React.CSSProperties
+            }
+            className="bg-background text-foreground flex min-h-screen"
+        >
+            <AdminShellInner>{children}</AdminShellInner>
+        </SidebarProvider>
+    );
+}

package/lib/templates/shared/page-resolver-moodle.tsx

@@ -0,0 +1,86 @@
+/**
+ * page-resolver — Moodle AMD page resolver.
+ *
+ * Three resolution modes:
+ *
+ * 1. Core pages (no prefix): "admin/Dashboard" resolves to
+ *    "../extensions/core/pages/admin/Dashboard.tsx" via eager glob.
+ *    Bundled into middag-app.js.
+ *
+ * 2. Extension pages (extension prefix): "ecommerce/pages/Index" resolves
+ *    to "../extensions/ecommerce/pages/Index.tsx" via lazy glob.
+ *    Each non-core extension gets its own AMD chunk.
+ *
+ * 3. External plugin pages (frankenstyle prefix): "local_yourplugin/admin/Index"
+ *    loads the AMD module via RequireJS. Any Moodle plugin can register
+ *    React pages in the MIDDAG shell using this mechanism.
+ */
+
+// Core pages — eager (bundled into middag-app.js)
+const corePages = import.meta.glob("../extensions/core/pages/**/*.tsx", { eager: true }) as Record<
+    string,
+    Record<string, unknown>
+>;
+
+// Non-core extension pages — lazy (separate AMD chunks)
+const extensionPages = import.meta.glob(
+    ["../extensions/*/pages/**/*.tsx", "!../extensions/core/**"],
+    { eager: false },
+) as Record<string, () => Promise<Record<string, unknown>>>;
+
+/**
+ * Frankenstyle pattern: type_name (e.g. local_yourplugin, mod_assign).
+ * A name like "local_yourplugin/admin/Index" is external.
+ * A name like "admin/Dashboard" is local (no underscore in first segment).
+ */
+function isExternalPage(name: string): boolean {
+    const firstSegment = name.split("/")[0];
+    return /^[a-z]+_[a-z]/.test(firstSegment);
+}
+
+/**
+ * Load an external plugin page via RequireJS (Moodle AMD).
+ *
+ * The plugin must build its page as an AMD module that exports a
+ * default React component. The module ID matches the page name directly
+ * (e.g. "local_yourplugin/admin/Index").
+ */
+function loadExternalPage(name: string): Promise<Record<string, unknown>> {
+    return new Promise((resolve, reject) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- RequireJS global
+        const req = (window as any).require;
+        if (!req) {
+            reject(new Error(`RequireJS not available. Cannot load external page: ${name}`));
+            return;
+        }
+        req(
+            [name],
+            (mod: Record<string, unknown>) => resolve(mod),
+            (err: Error) => reject(new Error(`Failed to load external page "${name}": ${err.message}`)),
+        );
+    });
+}
+
+export function resolvePageComponent(name: string) {
+    if (isExternalPage(name)) {
+        return loadExternalPage(name).then((mod) => mod.default ?? mod);
+    }
+
+    // Try core pages first (eager/sync)
+    const corePath = `../extensions/core/pages/${name}.tsx`;
+    const coreMod = corePages[corePath];
+    if (coreMod) {
+        return coreMod.default ?? coreMod;
+    }
+
+    // Try non-core extension pages (lazy/async)
+    const extPath = `../extensions/${name}.tsx`;
+    const extLoader = extensionPages[extPath];
+    if (extLoader) {
+        return extLoader().then((mod) => mod.default ?? mod);
+    }
+
+    throw new Error(
+        `Page not found: ${name}. Available: ${[...Object.keys(corePages), ...Object.keys(extensionPages)].join(", ")}`,
+    );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-middag-ui",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "type": "module",
   "description": "Bootstrap a MIDDAG React UI layer in your Moodle or WordPress plugin",
   "bin": {