umbraco
diff --git a/‎CLAUDE.md‎
Lines changed: 59 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 59 additions & 0 deletions
diff --git a/‎src/Umbraco.Web.UI.Client/CLAUDE.md‎
Lines changed: 83 additions & 0 deletions b/‎src/Umbraco.Web.UI.Client/CLAUDE.md‎
Lines changed: 83 additions & 0 deletions
diff --git a/‎src/Umbraco.Web.UI.Client/devops/publish/cleanse-pkg.js‎
Lines changed: 47 additions & 8 deletions b/‎src/Umbraco.Web.UI.Client/devops/publish/cleanse-pkg.js‎
Lines changed: 47 additions & 8 deletions
@@ -313,6 +313,65 @@ APIs use `Asp.Versioning.Mvc`:
 - Delivery API: `/umbraco/delivery/api/v{version}/*`
 - OpenAPI/Swagger docs per version
 
+### Backoffice npm Package Structure
+
+The backoffice (`Umbraco.Web.UI.Client`) is published to npm as **`@umbraco-cms/backoffice`** with a plugin architecture:
+
+#### Architecture Overview
+
+- **Multi-workspace structure**: Subprojects in `src/libs/*`, `src/packages/*`, `src/external/*`
+- **Export model**: All exports defined in root `package.json` → `./exports` field
+- **Importmap-driven runtime**: Dependencies provided at runtime via importmap (single source of truth)
+- **Build-time types**: TypeScript types come from npm peerDependencies
+- **Plugin model**: Developers create plugins that import from `@umbraco-cms/backoffice/*` exports
+
+#### Dependency Hoisting Strategy
+
+When building for npm (`npm pack`), the `cleanse-pkg.js` script hoists subproject dependencies to root `peerDependencies` with intelligent version range conversion:
+
+**Version Range Logic** (uses `semver` package):
+
+1. **Pre-release (0.x.y)**: Convert to explicit range
+   - Input: `^0.85.0` or `0.85.0`
+   - Output: `>=0.85.0 <1.0.0`
+   - Rationale: Pre-release caret only allows patch updates, explicit range allows minor upgrades within 0.x.x
+   - Example: Plugin can use `@hey-api/openapi-ts@0.91.1` while backoffice uses `0.85.0`
+
+2. **Stable with caret (^X.Y.Z where X ≥ 1)**: Keep as-is
+   - Input: `^3.3.1`
+   - Output: `^3.3.1` (unchanged)
+   - Rationale: Caret already implements correct semantics for stable versions
+
+3. **Stable exact versions (X.Y.Z where X ≥ 1)**: Add caret
+   - Input: `3.16.0`
+   - Output: `^3.16.0`
+   - Rationale: Normalizes to conventional semver format
+
+#### Key Dependencies
+
+**Runtime via importmap** (types available from peerDependencies):
+- `lit`, `rxjs`, `@umbraco-ui/uui` - Core framework
+- `monaco-editor`, `@tiptap/*` - Feature-specific editors
+- `@hey-api/openapi-ts` - HTTP client type generation
+
+**Build-time only** (not hoisted):
+- `vite`, `typescript`, `eslint` - Dev tooling
+
+#### Plugin Development Implications
+
+Plugin developers should:
+- **Declare explicit dependencies** in their own `package.json` (avoid relying on transitive deps)
+- **Understand the version ranges**: `>=0.85.0 <1.0.0` means they can use newer pre-release versions
+- **Know that types match npm ranges**, but runtime comes from importmap (managed by backoffice)
+- **When `@hey-api` hits 1.0.0**: Published constraint will automatically become `^1.0.0`
+
+#### Implementation Details
+
+- Script location: `src/Umbraco.Web.UI.Client/devops/publish/cleanse-pkg.js`
+- Runs as `prepack` hook before npm pack
+- Uses `semver.minVersion()` for robust version range parsing
+- Generates single source of truth for importmap versions
+
 ### Known Limitations
 
 1. **Circular Dependencies**: Avoided via `Lazy<T>` or event notifications
 
@@ -92,4 +92,87 @@ See **[Commands](./docs/commands.md)** for all available commands.
 
 ---
 
+## npm Package Publishing
+
+### Overview
+
+The backoffice is published to npm as `@umbraco-cms/backoffice` with a plugin-first architecture. All dependencies are **peerDependencies** because:
+
+1. **Importmap provides runtime**: The actual code at runtime comes from importmap, not npm
+2. **Types are the primary need**: Plugin developers need types for development, but runtime is managed centrally
+3. **Version flexibility**: Allows plugins to use different versions of pre-release packages (e.g., `@hey-api/openapi-ts`)
+
+### Dependency Hoisting & Version Ranges
+
+The `npm pack` process (prepack hook) runs `devops/publish/cleanse-pkg.js` which:
+
+1. **Collects dependencies** from all workspace subpackages
+2. **Converts to peerDependencies** at the root level
+3. **Intelligently adjusts version ranges** based on stability
+
+#### Version Range Conversion Logic
+
+Uses the `semver` package (npm's own semver library) for robust parsing:
+
+**Pre-release packages (0.x.y)**
+```
+Input:  ^0.85.0    or    0.85.0
+Output: >=0.85.0 <1.0.0
+
+Why: Pre-release caret (^0.85.0) only allows patch updates (0.85.x).
+     Explicit range allows plugins to use 0.91.1 without conflicts.
+```
+
+**Stable packages with caret (major ≥ 1)**
+```
+Input:  ^3.3.1
+Output: ^3.3.1    (kept as-is)
+
+Why: Caret already implements the correct range: >=3.3.1 <4.0.0
+```
+
+**Stable exact versions (major ≥ 1)**
+```
+Input:  3.16.0    (from @tiptap/*)
+Output: ^3.16.0
+
+Why: Normalizes to conventional semver format
+```
+
+#### Example Published peerDependencies
+
+```json
+{
+  "peerDependencies": {
+    "lit": "^3.3.1",
+    "rxjs": "^7.8.2",
+    "@umbraco-ui/uui": "^1.17.0-rc.5",
+    "monaco-editor": "^0.55.1",
+    "@tiptap/core": "^3.16.0",
+    "@hey-api/openapi-ts": ">=0.85.0 <1.0.0"
+  }
+}
+```
+
+### Plugin Developer Guide
+
+When using `@umbraco-cms/backoffice`:
+
+- **Declare dependencies explicitly** in your `package.json` (don't rely on transitive deps from backoffice)
+- **Version ranges are flexible**: `>=0.85.0 <1.0.0` means you can use `0.85.0`, `0.91.1`, or `0.99.99`
+- **Types come from npm**: TypeScript gets types from your declared versions
+- **Runtime comes from importmap**: The actual code at runtime is managed by the backoffice (importmap)
+- **Future compatibility**: When `@hey-api` hits `1.0.0`, the published range will automatically become `^1.0.0`
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `package.json` | Root package with exports and workspace references |
+| `devops/publish/cleanse-pkg.js` | Script that runs during `npm pack` to hoist and convert versions |
+| `src/external/*` | Dependency wrapper packages |
+| `src/packages/core` | Contains `@hey-api/openapi-ts` and other utilities |
+
+---
+
 **This project follows a modular package architecture with strict TypeScript, Lit web components, and an extensible manifest system. Each package is independent but follows consistent patterns. For extension development, use the Context API for dependency injection, controllers for logic, and manifests for registration.**
@@ -1,6 +1,8 @@
+/* eslint-disable local-rules/enforce-umbraco-external-imports */
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
-import glob from 'tiny-glob'
+import glob from 'tiny-glob';
+import semver from 'semver';
 
 console.log('[Prepublish] Cleansing package.json');
 
@@ -10,18 +12,45 @@ const packageJson = JSON.parse(readFileSync(packageFile, 'utf8'));
 // Remove all DevDependencies
 delete packageJson.devDependencies;
 
-// Rename dependencies to peerDependencies
-packageJson.peerDependencies = { ...packageJson.dependencies };
+// Convert version to a looser range that allows plugin developers to use newer versions
+// while still enforcing a minimum version and safety ceiling
+const looseVersionRange = (version) => {
+	// Extract minimum version from a range (e.g., ^0.85.0 -> 0.85.0)
+	const minVersion = semver.minVersion(version);
+	if (!minVersion) {
+		console.warn('Could not parse version:', version, 'keeping original');
+		return version;
+	}
+
+	const major = minVersion.major;
+	const minor = minVersion.minor;
+	const patch = minVersion.patch;
+
+	// For pre-release (0.x.y), always use floor at current version and ceiling at 1.0.0
+	if (major === 0) {
+		return `>=${major}.${minor}.${patch} <1.0.0`;
+	}
+
+	// Exact version without caret, add caret (e.g., 3.16.0 -> ^3.16.0 and ^3.16.0 -> ^3.16.0 and ~3.16.0 -> ^3.16.0)
+	return `^${major}.${minor}.${patch}`;
+};
+
+// Rename dependencies to peerDependencies with looser version ranges
+packageJson.peerDependencies = {};
+Object.entries(packageJson.dependencies || {}).forEach(([key, value]) => {
+	packageJson.peerDependencies[key] = looseVersionRange(value);
+	console.log('Converting to peer dependency:', key, 'from', value, 'to', packageJson.peerDependencies[key]);
+});
 delete packageJson.dependencies;
 
 // Iterate all workspaces and hoist the dependencies to the root package.json
 const workspaces = packageJson.workspaces || [];
-const workspacePromises = workspaces.map(async workspaceGlob => {
+const workspacePromises = workspaces.map(async (workspaceGlob) => {
 	// Use glob to find the workspace path
 	const localWorkspace = workspaceGlob.replace(/\.\/src/, './dist-cms');
 	const workspacePaths = await glob(localWorkspace, { cwd: './', absolute: true });
 
-	workspacePaths.forEach(workspace => {
+	workspacePaths.forEach((workspace) => {
 		const workspacePackageFile = join(workspace, 'package.json');
 
 		// Ensure the workspace package.json exists
@@ -36,11 +65,21 @@ const workspacePromises = workspaces.map(async workspaceGlob => {
 		// Move dependencies from the workspace to the root package.json
 		if (workspacePackageJson.dependencies) {
 			Object.entries(workspacePackageJson.dependencies).forEach(([key, value]) => {
-				console.log('Hoisting dependency:', key, 'from workspace:', workspace, 'with version:', value);
-				packageJson.peerDependencies[key] = value;
+				const loosenedVersion = looseVersionRange(value);
+				console.log(
+					'Hoisting dependency:',
+					key,
+					'from workspace:',
+					workspace,
+					'with version:',
+					value,
+					'loosened to:',
+					loosenedVersion,
+				);
+				packageJson.peerDependencies[key] = loosenedVersion;
 			});
 		}
-	})
+	});
 });
 
 // Wait for all workspace processing to complete