.claude/commands/analyze-docs.md

@@ -0,0 +1,155 @@
+# Documentation Analysis and Improvement
+
+This prompt helps analyze and improve Unhead documentation to create clean, approachable, and comprehensive documentation similar to anthropic.com, Vue.js, and Laravel.
+
+## Documentation Analysis
+
+When analyzing existing Unhead documentation, evaluate and provide recommendations for:
+
+1. **Structure clarity**: Assess logical flow and hierarchy of information
+2. **Completeness**: Identify missing concepts, edge cases, or examples
+3. **Code examples**: Evaluate quality, relevance, and clarity
+4. **Framework-specific guidance**: Check appropriate distinction between core and framework-specific features
+
+## Documentation Standards
+
+### Platform
+- **Nuxt Content v3**: Documentation is built with Nuxt Content v3
+- **MDC Format**: Content is authored in MDC (Markdown Components) format
+- **Nuxt Components**: Leverage built-in and custom components. Use `::caution`, `::tip`, `::warning` and `::note` where appropriate
+
+### MDC Syntax Guidelines
+- **Component Usage**: Use `::component{}` syntax for components
+- **Nested Components**: Structure complex components with proper nesting
+- **Props**: Pass props to components using curly braces `{prop: value}`
+- **Slots**: Use the slot syntax for component content
+- **Code Blocks**: Use language-specific code blocks with syntax highlighting
+- **Component Libraries**: Leverage built-in UI components from Nuxt Content
+
+### Code Blocks
+- **Language Tags**: All used hooks `useHead`, `useSeoMeta` should be imported from `@unhead/dynamic-import`
+- **Import statements**: Include complete import statements
+- **Framework-agnostic**: Unless explicitly in framework-specific section
+- **Progressive complexity**: Simple examples first, then complex ones
+- **Complete and minimal**: Include all necessary code, but no more
+- **TypeScript**: Prefer TypeScript in examples when appropriate
+
+### Structure
+- **Consistent Hierarchy**: Organize with clear numbered sections (0.introduction.md, 1.guides/...)
+- **Progressive Disclosure**: Basic concepts first, advanced topics later
+- **Separation of Concerns**: Keep guides, API references, and examples distinct
+
+### Content Guidelines
+- **Clear and concise**: Use direct, simple language with minimal jargon
+- **Conversational but professional**: Write as if explaining to a colleague
+- **Active voice**: Prefer "Configure the plugin by..." over "The plugin can be configured by..."
+- **Practical Examples**: Every feature should have real-world code examples
+- **Complete API References**: Document all parameters, return values, and types
+- **Starter Recipes**: Provide copy-paste solutions for common use cases
+- **Troubleshooting**: Include common issues and their solutions
+- **Framework Specifics**: Unless explicitly stated, examples should be framework-agnostic and code examples should import Unhead composables from `@unhead/dynamic-import`
+- **Common Use Cases**: Include a "Common Use Cases" section where applicable to demonstrate practical applications
+- **Best Practices**: Add guidance on recommended approaches and patterns
+- **API Caveats**: Clearly document any limitations, edge cases, or unexpected behaviors
+- **Internal Linking**: Add links to related sections within the documentation for easy navigation. We can find all links in the `src/content/docs/` folder as paths will map to the URL structure (without number prefixes)
+- **Deprecation Functions**: Any of the `useServer*` composables are deprecated, we should recommend using `useHead` instead with `import.meta.server` instead and link to docs/1.guides/7.client-only-tags.md
+
+### Page Structure
+- **Front Matter**: Include YAML front matter with title, description and navigation.title. These should be optimized for SEO without keyword stuffing, reference specific frameworks if applicable
+- **Title**: Not needed, this is generated from the front matter
+- **Introduction**: Brief overview of the concept/component with high-level navigation to major sections
+- **Core Concepts**: Breakdown of main functionality with clear section headings
+- **Usage Examples**: Code examples with explanations
+- **Advanced Usage**: More complex scenarios and advanced features when applicable
+- **API Reference**: When applicable, with props/events/slots
+- **Related Resources**: Links to relevant documentation to create a connected knowledge base
+
+### Formatting
+- **Alert Components**: Use specific alert components based on context:
+  - `::tip` - For best practices and recommendations
+  - `::note` - For additional information or context
+  - `::warning` or `::caution` - For potential issues or gotchas
+  - `::alert{type="info"}` - For general important notes
+- **Tabs**: Use tab components for multi-framework examples
+- **Code Groups**: Use code groups for related code examples
+- **Diagrams**: Use visual aids for complex concepts
+- **Consistency**: Maintain consistent terminology throughout
+- **Inline Code**: When rendering inline `code` tags, always postfix with the lang:
+  - HTML tags: `<head>`{lang="html"}
+  - CSS/properties: `color`{lang="css"}
+  - JS/TS variables and code: `tagPriority`{lang="bash"} or `function`{lang="ts"}
+- **Section Links**: Use anchor links to create navigation between sections of the document
+
+### Maintenance
+- **Version Specificity**: Indicate which version features were introduced
+- **Regular Reviews**: Schedule periodic reviews to ensure accuracy
+- **Deprecation Notices**: Clearly mark deprecated features
+- **Change Log**: Maintain detailed documentation changes
+
+## Section Templates
+
+### Marketing Section
+
+Some sections are more marketing-oriented, such as the introduction and overview. These should be written in a more engaging and less technical tone.
+They should use specific components to enhance the user experience.
+
+```md
+::UPageCard{title="Tailwind CSS" description="Nuxt UI v3 integrates with latest Tailwind CSS v4, bringing significant improvements." icon="i-simple-icons-tailwindcss" orientation="horizontal" spotlight spotlight-color="primary"}
+  :img{src="/tailwindcss-v4.svg" alt="Tailwind CSS" class="w-full"}
+::
+```
+
+### API Reference Section
+
+```md
+## API Reference
+
+### Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `param1` | `string` | `'default'` | Description of parameter |
+
+### Returns
+
+Description of return value and type
+
+### Examples
+
+```ts
+// Simple example
+```
+
+### Component Section
+
+```md
+## ComponentName
+
+Description of the component and when to use it.
+
+### Props
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `prop1` | `string` | `'default'` | Description of prop |
+
+### Example
+
+```vue
+<template>
+  <ComponentName prop1="value" />
+</template>
+```
+
+## Improvement Checklist
+
+- [ ] Ensure all headings and page titles are clear and descriptive
+- [ ] Confirm all code examples are complete and working
+- [ ] Check that all parameters and options are documented
+- [ ] Verify internal links are working correctly
+- [ ] Review for consistent terminology
+- [ ] Add practical examples for common use cases
+- [ ] Include troubleshooting sections for common issues
+- [ ] Provide migration paths from previous versions or other libraries
+
+Unhead is a framework-agnostic head management library for managing HTML head tags in both client and server environments.

.claude/commands/security-research.md

@@ -0,0 +1,157 @@
+# Unhead Security Research Report
+
+## Executive Summary
+
+This report documents an assessment of Unhead's security measures against Cross-Site Scripting (XSS) vulnerabilities. Unhead is a framework-agnostic head management library for managing HTML head tags, making it a critical component in the security posture of web applications that use it.
+
+## Methodology
+
+- Code analysis of XSS prevention mechanisms
+- Review of existing XSS test coverage
+- Identification of potential attack vectors
+
+## Findings
+
+### XSS Protection Mechanisms
+
+Unhead implements several security measures to prevent XSS:
+
+1. **HTML Escaping**: The library uses the `escapeHtml` function in `tagToString.ts` which properly escapes the following characters:
+   - `&` → `&`
+   - `<` → `&lt;`
+   - `>` → `&gt;`
+   - `"` → `&quot;`
+   - `'` → `&#x27;`
+   - `/` → `&#x2F;`
+
+2. **Attribute Encoding**: The `encodeAttribute` function in `propsToString.ts` escapes double quotes in attribute values using `&quot;`.
+
+3. **Content Type Handling**: Different encoding is applied based on content type:
+   - `textContent` is properly escaped to prevent XSS
+   - `innerHTML` is intentionally not escaped (dangerous but documented)
+
+### Potential Vulnerabilities
+
+1. **innerHTML Handling**: The code explicitly notes that innerHTML is "dangerously" used without encoding. This is a deliberate design choice to allow HTML in certain contexts, but creates a potential attack vector if user input is directly passed to innerHTML.
+
+2. **Script Content**: When using script tags, the code properly handles the potential injection of `</script>` tags by using the `devalue` library, which correctly escapes such content.
+
+3. **Attribute Escaping**: While double quotes are escaped in attribute values, the encoding is limited compared to the more comprehensive `escapeHtml` function. This might present edge cases in certain browser contexts.
+
+4. **JSON Content**: Special attention is given to JSON content in script tags, with proper escaping via the `devalue` library.
+
+## Attack Vectors to Explore
+
+1. **Contextual Bypasses**: Test if escaping works in all contexts (HTML, attributes, JavaScript, CSS, URL)
+2. **DOM-based XSS**: Examine client-side rendering for potential DOM XSS vectors
+3. **Template Injection**: Test handling of complex template variables and expressions
+4. **Script Execution**: Test script loading mechanisms and event handling
+5. **Sanitization Bypass**: Attempt to bypass the escaping mechanisms
+
+## Recommendations
+
+1. **innerHTML Usage**: Consider adding a sanitization option for innerHTML content
+2. **Attribute Encoding**: Enhance the attribute encoding to match the more comprehensive HTML encoding
+3. **Additional Test Coverage**: Expand test coverage for edge cases and exotic payloads
+4. **User Documentation**: Clearly document security best practices for users of the library
+5. **URL Sanitization**: Implement sanitization for potentially dangerous URL schemas like javascript:, data:, and vbscript:
+6. **Meta Tag Content**: Add proper content sanitization for meta tags to prevent SVG-based and other XSS payloads
+7. **CSS Protection**: Consider sanitizing style content to prevent CSS-based attacks
+
+## Comprehensive XSS Example
+
+```js
+// Example of a useHead() call that attempts to exploit multiple XSS vectors
+useHead({
+  // Title injection
+  title: '</title><script>alert("title XSS")</script>',
+  titleTemplate: '%s - <script>alert("template")</script>',
+
+  // Meta tag vectors
+  meta: [
+    // SVG-based XSS
+    { name: 'description', content: '<svg><script>alert("svg")</script></svg>' },
+    // Attribute injection
+    { name: 'keywords" onload="alert("attr")', content: 'SEO keywords' },
+    // Unicode escape sequence
+    { name: 'author', content: '\\u003Cscript\\u003Ealert("unicode")\\u003C/script\\u003E' },
+    // Character encoding attack
+    { 'http-equiv': 'content-type', content: 'text/html; charset=UTF-7; X-XSS-Protection: "0";' },
+    // Case variation bypass
+    { name: 'viewport', content: '<ScRiPt>alert("case")</ScRiPt>' },
+    // Emoji obfuscation
+    { name: 'robots', content: '📝➡️<script>alert("emoji")</script>' },
+    // innerHTML attempt (shouldn't work)
+    { name: 'generator', innerHTML: '<script>alert("meta-inner")</script>' }
+  ],
+
+  // Link attacks
+  link: [
+    // Javascript protocol
+    { rel: 'stylesheet', href: 'javascript:alert("js-protocol")' },
+    // Data URI 
+    { rel: 'icon', href: 'data:text/html;base64,PHNjcmlwdD5hbGVydCgieHNzIik8L3NjcmlwdD4=' },
+    // Protocol switching
+    { rel: 'dns-prefetch', href: '//evil.com/xss.js' },
+    // HTML-encoded colon
+    { rel: 'preconnect', href: 'javascript&#58;alert("encoded")' },
+    // Other protocol
+    { rel: 'prefetch', href: 'vbscript:alert("vbscript")' }
+  ],
+
+  // Script attacks
+  script: [
+    // Template literal with closing script
+    { innerHTML: `
+      const template = \`
+        </script>
+        <img src=x onerror="alert('template-literal')">
+        <script>
+      \`;
+      console.log(template);
+    ` },
+    // Null byte insertion
+    { innerHTML: `console.log("Null byte attack: \\0')</script><script>alert('null-byte')</script>")` },
+    // String concatenation bypass
+    { innerHTML: `console.log("</scr"+"ipt><script>alert('concat')</script>")` },
+    // mXSS payload
+    { innerHTML: `var xss = '<img src="1" onerror="alert(\\'mxss\\')" />';` },
+    // JSON with devalue (should be properly escaped)
+    { type: 'application/json', innerHTML: JSON.stringify({ payload: '</script><script>alert("json")</script>' }) }
+  ],
+
+  // Style attacks
+  style: [
+    // CSS expression
+    { innerHTML: `body { color: expression(alert('css-expression')) }` },
+    // CSS url injection
+    { innerHTML: `body { background: url('javascript:alert("css-url")') }` }
+  ],
+
+  // HTML attributes
+  htmlAttrs: {
+    'onload': 'alert("html-event")',
+    'data-attr': '"><script>alert("html-attr")</script>'
+  },
+
+  // Body attributes
+  bodyAttrs: {
+    'data-custom': `x" onmouseover="alert('body-attr')" data-x="`
+  },
+
+  // Base attack
+  base: { href: 'javascript:alert("base")' }
+})
+```
+
+## Next Steps
+
+Further testing required:
+- Dynamic content insertion
+- Framework-specific integration points
+- Client-side rendering security
+- Event handler sanitization
+
+---
+
+*This is an initial security assessment and should be followed by comprehensive penetration testing.*

README.md

@@ -3,7 +3,8 @@
 [![npm version](https://img.shields.io/npm/v/unhead?color=yellow)](https://npmjs.com/package/unhead)
 [![npm downloads](https://img.shields.io/npm/dm/unhead?color=yellow)](https://npm.chart.dev/unhead)
 
-Unhead wraps your document template, improving reactive SSR JavaScript framework SEO and performance.
+Unhead is a document head and template manager, improving reactive SSR JavaScript framework developer experience, SEO and performance.
+See the full [introduction to Unhead](https://unhead.unjs.io/docs/typescript/head/guides/get-started/intro-to-unhead).
 
 <p align="center">
 <table>
@@ -15,6 +16,10 @@ Unhead wraps your document template, improving reactive SSR JavaScript framework
 </table>
 </p>
 
+### Unhead v2 🎉
+
+The latest major is now stable! Check out the [v2 release notes](https://unhead.unjs.io/v2).
+
 ## Highlights
 
 - ✨ `useHead()`: Deduping, sorting, and tag merging

bench/bundle/last.json

@@ -1,7 +1,7 @@
 {
   "client": {
-    "size": 10978,
-    "gz": 4574
+    "size": 11001,
+    "gz": 4582
   },
   "server": {
     "size": 8179,

docs/0.angular/1.installation.md → docs/0.angular/head/guides/0.get-started/1.installation.md

@@ -5,18 +5,16 @@ navigation:
   title: 'Installation'
 ---
 
-# Installing Unhead with Angular
-
 Unhead provides first-class support for Angular, allowing you to manage your head tags using composables like `useHead()`, `useSeoMeta()`, and others within your Angular components.
-- [StackBlitz - Unhead - Angular SPA](https://stackblitz.com/edit/stackblitz-starters-e4x42yaz)
--
+- [StackBlitz - Unhead - Angular](https://stackblitz.com/edit/stackblitz-starters-e4x42yaz)
+
 ## Setup
 
 ### 1. Add Dependency
 
 Install the Angular-specific Unhead package:
 
-:ModuleInstall{name="@unhead/angular@next"}
+:ModuleInstall{name="@unhead/angular"}
 
 ### 2. Setup Client-Side Rendering
 
@@ -167,7 +165,7 @@ export class CounterComponent {
 }
 ```
 
-For more details on reactivity, check the [Angular Reactivity Guide](/docs/angular/guides/reactivity).
+For more details on reactivity, check the [Angular Reactivity Guide](/docs/angular/head/guides/core-concepts/reactivity).
 
 ## Default Tags
 
@@ -183,11 +181,11 @@ You can customize these defaults or add additional ones through the `init` optio
 Your Angular app is now ready for head management! 🎉
 
 Explore the available composables:
-- [`useHead()`](/docs/api/use-head)
-- [`useSeoMeta()`](/docs/api/use-seo-meta)
-- [`useScript()`](/docs/api/use-script)
+- [`useHead()`](/docs/head/api/composables/use-head)
+- [`useSeoMeta()`](/docs/head/api/composables/use-seo-meta)
+- [`useScript()`](/docs/head/api/composables/use-script)
 
 Or explore additional functionality:
-- Learn about [reactivity](/docs/angular/guides/reactivity) in Angular
-- Add structured data with [`useSchemaOrg()`](/docs/api/use-schema-org)
-- Explore [title templates](/docs/guides/titles) for consistent page titles
+- Learn about [reactivity](/docs/angular/head/guides/core-concepts/reactivity) in Angular
+- Add structured data with [`useSchemaOrg()`](/docs/head/api/composables/use-schema-org)
+- Explore [title templates](/docs/head/guides/core-concepts/titles) for consistent page titles