Refactor generators to produce proper fromArray implementations

src/Generator/ClassGenerator.php

···
 
 use SocialDept\Schema\Data\LexiconDocument;
 use SocialDept\Schema\Exceptions\GenerationException;
+use SocialDept\Schema\Support\ExtensionManager;
 
 class ClassGenerator
 {
···
     protected DocBlockGenerator $docBlockGenerator;
 
     /**
+     * Extension manager instance.
+     */
+    protected ExtensionManager $extensions;
+
+    /**
      * Create a new ClassGenerator.
      */
     public function __construct(
···
         ?TypeMapper $typeMapper = null,
         ?StubRenderer $renderer = null,
         ?MethodGenerator $methodGenerator = null,
-        ?DocBlockGenerator $docBlockGenerator = null
+        ?DocBlockGenerator $docBlockGenerator = null,
+        ?ExtensionManager $extensions = null
     ) {
-        $this->naming = $naming ?? new NamingConverter();
+        $this->naming = $naming ?? new NamingConverter;
         $this->typeMapper = $typeMapper ?? new TypeMapper($this->naming);
-        $this->renderer = $renderer ?? new StubRenderer();
+        $this->renderer = $renderer ?? new StubRenderer;
         $this->methodGenerator = $methodGenerator ?? new MethodGenerator($this->naming, $this->typeMapper, $this->renderer);
         $this->docBlockGenerator = $docBlockGenerator ?? new DocBlockGenerator($this->typeMapper);
+        $this->extensions = $extensions ?? new ExtensionManager;
     }
 
     /**
···
                 ['nsid' => $nsid, 'type' => $type]
             );
         }
+
+        // For record types, extract the actual record definition
+        $recordDef = $type === 'record' ? ($mainDef['record'] ?? []) : $mainDef;
+
+        // Build local definition map for type resolution
+        $localDefinitions = $this->buildLocalDefinitionMap($document);
+        $this->typeMapper->setLocalDefinitions($localDefinitions);
 
         // Get class components
-        $namespace = $this->naming->nsidToNamespace($nsid);
-        $className = $this->naming->toClassName($document->id->getName());
-        $useStatements = $this->collectUseStatements($mainDef);
-        $properties = $this->generateProperties($mainDef);
-        $constructor = $this->generateConstructor($mainDef);
-        $methods = $this->generateMethods($document);
-        $docBlock = $this->generateClassDocBlock($document, $mainDef);
+        $namespace = $this->extensions->filter('filter:class:namespace', $this->naming->nsidToNamespace($nsid), $document);
+        $className = $this->extensions->filter('filter:class:className', $this->naming->toClassName($document->id->getName()), $document);
+        $useStatements = $this->extensions->filter('filter:class:useStatements', $this->collectUseStatements($recordDef, $namespace), $document, $recordDef);
+        $properties = $this->extensions->filter('filter:class:properties', $this->generateProperties($recordDef), $document, $recordDef);
+        $constructor = $this->extensions->filter('filter:class:constructor', $this->generateConstructor($recordDef), $document, $recordDef);
+        $methods = $this->extensions->filter('filter:class:methods', $this->generateMethods($document), $document);
+        $docBlock = $this->extensions->filter('filter:class:docBlock', $this->generateClassDocBlock($document, $mainDef), $document, $mainDef);
 
         // Render the class
-        return $this->renderer->render('class', [
+        $rendered = $this->renderer->render('class', [
             'namespace' => $namespace,
             'imports' => $this->formatUseStatements($useStatements),
             'docBlock' => $docBlock,
             'className' => $className,
-            'extends' => ' extends \\SocialDept\\Schema\\Data\\Data',
+            'extends' => ' extends Data',
             'implements' => '',
             'properties' => $properties,
             'constructor' => $constructor,
             'methods' => $methods,
         ]);
+
+        // Execute post-generation hooks
+        $this->extensions->execute('action:class:generated', $rendered, $document);
+
+        return $rendered;
     }
 
     /**
      * Generate class properties.
+     *
+     * Since we use constructor property promotion, we don't need separate property declarations.
+     * This method returns empty string but is kept for compatibility.
      *
      * @param  array<string, mixed>  $definition
      */
     protected function generateProperties(array $definition): string
     {
-        $properties = $definition['properties'] ?? [];
-        $required = $definition['required'] ?? [];
-
-        if (empty($properties)) {
-            return '';
-        }
-
-        $lines = [];
-
-        foreach ($properties as $name => $propDef) {
-            $isRequired = in_array($name, $required);
-            $phpType = $this->typeMapper->toPhpType($propDef, ! $isRequired);
-            $docType = $this->typeMapper->toPhpDocType($propDef, ! $isRequired);
-            $description = $propDef['description'] ?? null;
-
-            // Build property doc comment
-            $docLines = ['    /**'];
-            if ($description) {
-                $docLines[] = '     * '.$description;
-                $docLines[] = '     *';
-            }
-            $docLines[] = '     * @var '.$docType;
-            $docLines[] = '     */';
-
-            $lines[] = implode("\n", $docLines);
-            $lines[] = '    public readonly '.$phpType.' $'.$name.';';
-            $lines[] = '';
-        }
-
-        return rtrim(implode("\n", $lines));
+        // Properties are defined via constructor promotion
+        return '';
     }
 
     /**
···
             return '';
         }
 
-        $params = [];
+        // Build constructor parameters - required first, then optional
+        $requiredParams = [];
+        $optionalParams = [];
+        $requiredDocParams = [];
+        $optionalDocParams = [];
 
         foreach ($properties as $name => $propDef) {
             $isRequired = in_array($name, $required);
             $phpType = $this->typeMapper->toPhpType($propDef, ! $isRequired);
-            $default = ! $isRequired ? ' = null' : '';
+            $phpDocType = $this->typeMapper->toPhpDocType($propDef, ! $isRequired);
+            $description = $propDef['description'] ?? '';
+            $param = '        public readonly '.$phpType.' $'.$name;
 
-            $params[] = '        public readonly '.$phpType.' $'.$name.$default.',';
+            if ($isRequired) {
+                $requiredParams[] = $param.',';
+                if ($description) {
+                    $requiredDocParams[] = '     * @param  '.$phpDocType.'  $'.$name.'  '.$description;
+                }
+            } else {
+                $optionalParams[] = $param.' = null,';
+                if ($description) {
+                    $optionalDocParams[] = '     * @param  '.$phpDocType.'  $'.$name.'  '.$description;
+                }
+            }
         }
 
+        // Combine required and optional parameters
+        $params = array_merge($requiredParams, $optionalParams);
+
         // Remove trailing comma from last parameter
         if (! empty($params)) {
             $params[count($params) - 1] = rtrim($params[count($params) - 1], ',');
         }
 
-        return "    public function __construct(\n".implode("\n", $params)."\n    ) {\n    }";
+        // Build constructor DocBlock with parameter descriptions in the correct order
+        $docParams = array_merge($requiredDocParams, $optionalDocParams);
+        $docLines = ['    /**'];
+        if (! empty($docParams)) {
+            $docLines = array_merge($docLines, $docParams);
+        }
+        $docLines[] = '     */';
+        $docBlock = implode("\n", $docLines);
+
+        return "\n".$docBlock."\n    public function __construct(\n".implode("\n", $params)."\n    ) {}";
     }
 
     /**
···
      * @param  array<string, mixed>  $definition
      * @return array<string>
      */
-    protected function collectUseStatements(array $definition): array
+    protected function collectUseStatements(array $definition, string $currentNamespace = ''): array
     {
         $uses = ['SocialDept\\Schema\\Data\\Data'];
         $properties = $definition['properties'] ?? [];
···
 
         // Remove duplicates and sort
         $uses = array_unique($uses);
+
+        // Filter out classes from the same namespace
+        if ($currentNamespace) {
+            $uses = array_filter($uses, function ($use) use ($currentNamespace) {
+                // Get namespace from FQCN by removing class name
+                $parts = explode('\\', ltrim($use, '\\'));
+                array_pop($parts); // Remove class name
+                $useNamespace = implode('\\', $parts);
+
+                return $useNamespace !== $currentNamespace;
+            });
+        }
+
         sort($uses);
 
         return $uses;
···
     }
 
     /**
+     * Build a map of local definitions for type resolution.
+     *
+     * Maps local references (#defName) to their generated class names.
+     *
+     * @return array<string, string> Map of local ref => class name
+     */
+    protected function buildLocalDefinitionMap(LexiconDocument $document): array
+    {
+        $localDefs = [];
+        $allDefs = $document->defs ?? [];
+
+        foreach ($allDefs as $defName => $definition) {
+            // Skip the main definition
+            if ($defName === 'main') {
+                continue;
+            }
+
+            // Convert definition name to class name
+            $className = $this->naming->toClassName($defName);
+            $localDefs["#{$defName}"] = $className;
+        }
+
+        return $localDefs;
+    }
+
+    /**
      * Get the naming converter.
      */
     public function getNaming(): NamingConverter
···
     public function getDocBlockGenerator(): DocBlockGenerator
     {
         return $this->docBlockGenerator;
+    }
+
+    /**
+     * Get the extension manager.
+     */
+    public function getExtensions(): ExtensionManager
+    {
+        return $this->extensions;
     }
 }

src/Generator/ConstructorGenerator.php

···
         ?PropertyGenerator $propertyGenerator = null,
         ?StubRenderer $renderer = null
     ) {
-        $this->propertyGenerator = $propertyGenerator ?? new PropertyGenerator();
-        $this->renderer = $renderer ?? new StubRenderer();
+        $this->propertyGenerator = $propertyGenerator ?? new PropertyGenerator;
+        $this->renderer = $renderer ?? new StubRenderer;
     }
 
     /**
···
                $params."\n".
                "    ) {\n".
                $body."\n".
-               "    }";
+               '    }';
     }
 
     /**

src/Generator/DTOGenerator.php

···
     protected FileWriter $fileWriter;
 
     /**
+     * Class generator for generating PHP classes.
+     */
+    protected ClassGenerator $classGenerator;
+
+    /**
      * Base namespace for generated classes.
      */
     protected string $baseNamespace;
···
         ?TypeParser $typeParser = null,
         ?NamespaceResolver $namespaceResolver = null,
         ?TemplateRenderer $templateRenderer = null,
-        ?FileWriter $fileWriter = null
+        ?FileWriter $fileWriter = null,
+        ?ClassGenerator $classGenerator = null
     ) {
         $this->schemaLoader = $schemaLoader;
         $this->baseNamespace = rtrim($baseNamespace, '\\');
         $this->outputDirectory = rtrim($outputDirectory, '/');
         $this->typeParser = $typeParser ?? new TypeParser(schemaLoader: $schemaLoader);
         $this->namespaceResolver = $namespaceResolver ?? new NamespaceResolver($baseNamespace);
-        $this->templateRenderer = $templateRenderer ?? new TemplateRenderer();
-        $this->fileWriter = $fileWriter ?? new FileWriter();
+        $this->templateRenderer = $templateRenderer ?? new TemplateRenderer;
+        $this->fileWriter = $fileWriter ?? new FileWriter;
+
+        // Initialize ClassGenerator with proper naming converter
+        $naming = new NamingConverter($this->baseNamespace);
+        $this->classGenerator = $classGenerator ?? new ClassGenerator($naming);
     }
 
     /**
···
      */
     public function generate(LexiconDocument $schema): string
     {
-        return $this->generateRecordCode($schema);
+        return $this->classGenerator->generate($schema);
     }
 
     /**
···
      */
     public function generateByNsid(string $nsid, array $options = []): array
     {
-        $schema = $this->schemaLoader->load($nsid);
-        $document = LexiconDocument::fromArray($schema);
+        $document = $this->schemaLoader->load($nsid);
 
         return $this->generateFromDocument($document, $options);
     }
···
      */
     protected function generateRecordClass(LexiconDocument $document, array $options = []): string
     {
-        $namespace = $this->namespaceResolver->resolveNamespace($document->getNsid());
-        $className = $this->namespaceResolver->resolveClassName($document->getNsid());
-
-        $mainDef = $document->getMainDefinition();
-        $recordSchema = $mainDef['record'] ?? [];
-
-        $properties = $this->extractProperties($recordSchema, $document);
-
-        $code = $this->templateRenderer->render('record', [
-            'namespace' => $namespace,
-            'className' => $className,
-            'nsid' => $document->getNsid(),
-            'description' => $document->description,
-            'properties' => $properties,
-        ]);
+        // Use ClassGenerator for proper code generation
+        $code = $this->classGenerator->generate($document);
 
+        $naming = $this->classGenerator->getNaming();
+        $namespace = $naming->nsidToNamespace($document->getNsid());
+        $className = $naming->toClassName($document->id->getName());
         $filePath = $this->getFilePath($namespace, $className);
 
         if (! ($options['dryRun'] ?? false)) {
···
      */
     protected function generateDefinitionClass(LexiconDocument $document, string $defName, array $options = []): string
     {
-        $namespace = $this->namespaceResolver->resolveNamespace($document->getNsid());
-        $className = $this->namespaceResolver->resolveClassName($document->getNsid(), $defName);
-
+        // Create a temporary document for this specific definition
         $definition = $document->getDefinition($defName);
-        $properties = $this->extractProperties($definition, $document);
 
-        $code = $this->templateRenderer->render('object', [
-            'namespace' => $namespace,
-            'className' => $className,
+        // Build a temporary lexicon document for the object definition
+        $objectNsid = $document->getNsid().'.'.$defName;
+        $tempSchema = [
+            'id' => $objectNsid,
+            'lexicon' => 1,
             'description' => $definition['description'] ?? null,
-            'properties' => $properties,
-        ]);
+            'defs' => [
+                'main' => [
+                    'type' => 'object',
+                    'properties' => $definition['properties'] ?? [],
+                    'required' => $definition['required'] ?? [],
+                    'description' => $definition['description'] ?? null,
+                ],
+            ],
+        ];
+
+        $tempDocument = \SocialDept\Schema\Data\LexiconDocument::fromArray($tempSchema);
 
+        // Use ClassGenerator for proper code generation
+        $code = $this->classGenerator->generate($tempDocument);
+
+        $naming = $this->classGenerator->getNaming();
+        $namespace = $naming->nsidToNamespace($objectNsid);
+        $className = $naming->toClassName($defName);
         $filePath = $this->getFilePath($namespace, $className);
 
         if (! ($options['dryRun'] ?? false)) {
···
      */
     public function getMetadata(string $nsid): array
     {
-        $schema = $this->schemaLoader->load($nsid);
-        $document = LexiconDocument::fromArray($schema);
+        $document = $this->schemaLoader->load($nsid);
 
         $namespace = $this->namespaceResolver->resolveNamespace($document->getNsid());
         $className = $this->namespaceResolver->resolveClassName($document->getNsid());

src/Generator/DocBlockGenerator.php

···
      */
     public function __construct(?TypeMapper $typeMapper = null)
     {
-        $this->typeMapper = $typeMapper ?? new TypeMapper();
+        $this->typeMapper = $typeMapper ?? new TypeMapper;
     }
 
     /**

src/Generator/MethodGenerator.php

···
 namespace SocialDept\Schema\Generator;
 
 use SocialDept\Schema\Data\LexiconDocument;
+use SocialDept\Schema\Support\ExtensionManager;
 
 class MethodGenerator
 {
···
     protected ModelMapper $modelMapper;
 
     /**
+     * Extension manager instance.
+     */
+    protected ExtensionManager $extensions;
+
+    /**
      * Create a new MethodGenerator.
      */
     public function __construct(
         ?NamingConverter $naming = null,
         ?TypeMapper $typeMapper = null,
         ?StubRenderer $renderer = null,
-        ?ModelMapper $modelMapper = null
+        ?ModelMapper $modelMapper = null,
+        ?ExtensionManager $extensions = null
     ) {
-        $this->naming = $naming ?? new NamingConverter();
+        $this->naming = $naming ?? new NamingConverter;
         $this->typeMapper = $typeMapper ?? new TypeMapper($this->naming);
-        $this->renderer = $renderer ?? new StubRenderer();
+        $this->renderer = $renderer ?? new StubRenderer;
         $this->modelMapper = $modelMapper ?? new ModelMapper($this->naming, $this->typeMapper);
+        $this->extensions = $extensions ?? new ExtensionManager;
     }
 
     /**
···
     {
         $nsid = $document->getNsid();
 
-        return $this->renderer->render('method', [
+        $method = $this->renderer->render('method', [
             'docBlock' => $this->generateDocBlock('Get the lexicon NSID for this data type.', 'string'),
             'visibility' => 'public ',
             'static' => 'static ',
···
             'returnType' => ': string',
             'body' => "        return '{$nsid}';",
         ]);
+
+        return $this->extensions->filter('filter:method:getLexicon', $method, $document);
     }
 
     /**
···
     public function generateFromArray(LexiconDocument $document): string
     {
         $mainDef = $document->getMainDefinition();
-        $properties = $mainDef['properties'] ?? [];
-        $required = $mainDef['required'] ?? [];
+
+        // For record types, properties are nested under 'record'
+        $type = $mainDef['type'] ?? null;
+        if ($type === 'record') {
+            $recordDef = $mainDef['record'] ?? [];
+            $properties = $recordDef['properties'] ?? [];
+            $required = $recordDef['required'] ?? [];
+        } else {
+            // For object types, properties are at the top level
+            $properties = $mainDef['properties'] ?? [];
+            $required = $mainDef['required'] ?? [];
+        }
 
         if (empty($properties)) {
             return $this->generateEmptyFromArray();
···
         $assignments = $this->generateFromArrayAssignments($properties, $required);
         $body = "        return new static(\n".$assignments."\n        );";
 
-        return $this->renderer->render('method', [
+        $method = $this->renderer->render('method', [
             'docBlock' => $this->generateDocBlock('Create an instance from an array.', 'static', [
                 ['name' => 'data', 'type' => 'array', 'description' => 'The data array'],
             ]),
···
             'returnType' => ': static',
             'body' => $body,
         ]);
+
+        return $this->extensions->filter('filter:method:fromArray', $method, $document, $properties, $required);
     }
 
     /**
···
     {
         $lines = [];
 
+        // Generate required parameters first
         foreach ($properties as $name => $definition) {
-            $type = $definition['type'] ?? 'unknown';
-            $assignment = $this->generatePropertyAssignment($name, $definition, $type, $required);
-            $lines[] = '            '.$name.': '.$assignment.',';
+            if (in_array($name, $required)) {
+                $type = $definition['type'] ?? 'unknown';
+                $assignment = $this->generatePropertyAssignment($name, $definition, $type, $required);
+                $lines[] = '            '.$name.': '.$assignment.',';
+            }
+        }
+
+        // Then generate optional parameters
+        foreach ($properties as $name => $definition) {
+            if (! in_array($name, $required)) {
+                $type = $definition['type'] ?? 'unknown';
+                $assignment = $this->generatePropertyAssignment($name, $definition, $type, $required);
+                $lines[] = '            '.$name.': '.$assignment.',';
+            }
         }
 
         // Remove trailing comma from last line
···
     protected function generatePropertyAssignment(string $name, array $definition, string $type, array $required): string
     {
         $isRequired = in_array($name, $required);
+        $assignment = $this->generatePropertyAssignmentInternal($name, $definition, $type, $required);
+
+        return $this->extensions->filter('filter:method:propertyAssignment', $assignment, $name, $definition, $type, $required);
+    }
+
+    /**
+     * Internal property assignment generation logic.
+     *
+     * @param  array<string, mixed>  $definition
+     * @param  array<string>  $required
+     */
+    protected function generatePropertyAssignmentInternal(string $name, array $definition, string $type, array $required): string
+    {
+        $isRequired = in_array($name, $required);
 
         // Handle reference types
         if ($type === 'ref' && isset($definition['ref'])) {
-            $refClass = $this->naming->nsidToClassName($definition['ref']);
+            $ref = $definition['ref'];
+
+            // Skip local references (starting with #) - treat as mixed
+            if (str_starts_with($ref, '#')) {
+                // Local references don't need conversion, just return the data
+                if ($isRequired) {
+                    return "\$data['{$name}']";
+                }
+
+                return "\$data['{$name}'] ?? null";
+            }
+
+            // Handle NSID fragments - extract just the NSID part
+            if (str_contains($ref, '#')) {
+                $ref = explode('#', $ref)[0];
+            }
+
+            $refClass = $this->naming->nsidToClassName($ref);
             $className = basename(str_replace('\\', '/', $refClass));
 
             if ($isRequired) {
···
 
         // Handle arrays of references
         if ($type === 'array' && isset($definition['items']['type']) && $definition['items']['type'] === 'ref') {
-            $refClass = $this->naming->nsidToClassName($definition['items']['ref']);
+            $ref = $definition['items']['ref'];
+
+            // Skip local references - treat array as mixed
+            if (str_starts_with($ref, '#')) {
+                return "\$data['{$name}'] ?? []";
+            }
+
+            // Handle NSID fragments
+            if (str_contains($ref, '#')) {
+                $ref = explode('#', $ref)[0];
+            }
+
+            $refClass = $this->naming->nsidToClassName($ref);
             $className = basename(str_replace('\\', '/', $refClass));
 
             return "isset(\$data['{$name}']) ? array_map(fn (\$item) => {$className}::fromArray(\$item), \$data['{$name}']) : []";
···
         // Handle DateTime types (if string format matches ISO8601)
         if ($type === 'string' && isset($definition['format']) && $definition['format'] === 'datetime') {
             if ($isRequired) {
-                return "new \\DateTime(\$data['{$name}'])";
+                return "Carbon::parse(\$data['{$name}'])";
+            }
+
+            return "isset(\$data['{$name}']) ? Carbon::parse(\$data['{$name}']) : null";
+        }
+
+        // Handle union types with refs
+        if ($type === 'union' && isset($definition['refs']) && is_array($definition['refs'])) {
+            $refs = $definition['refs'];
+            $isClosed = $definition['closed'] ?? false;
+
+            // Filter out local references
+            $externalRefs = array_values(array_filter($refs, fn ($ref) => ! str_starts_with($ref, '#')));
+
+            // Handle closed unions - use UnionHelper for discrimination
+            if ($isClosed && ! empty($externalRefs)) {
+                // Build array of variant class names
+                $variantClasses = [];
+                foreach ($externalRefs as $ref) {
+                    // Handle NSID fragments
+                    if (str_contains($ref, '#')) {
+                        $ref = explode('#', $ref)[0];
+                    }
+
+                    $refClass = $this->naming->nsidToClassName($ref);
+                    $className = basename(str_replace('\\', '/', $refClass));
+                    $variantClasses[] = "{$className}::class";
+                }
+
+                $variantsArray = '['.implode(', ', $variantClasses).']';
+
+                if ($isRequired) {
+                    return "\\SocialDept\\Schema\\Support\\UnionHelper::resolveClosedUnion(\$data['{$name}'], {$variantsArray})";
+                }
+
+                return "isset(\$data['{$name}']) ? \\SocialDept\\Schema\\Support\\UnionHelper::resolveClosedUnion(\$data['{$name}'], {$variantsArray}) : null";
             }
 
-            return "isset(\$data['{$name}']) ? new \\DateTime(\$data['{$name}']) : null";
+            // Open unions - validate $type presence using UnionHelper
+            if (! $isClosed) {
+                if ($isRequired) {
+                    return "\\SocialDept\\Schema\\Support\\UnionHelper::validateOpenUnion(\$data['{$name}'])";
+                }
+
+                return "isset(\$data['{$name}']) ? \\SocialDept\\Schema\\Support\\UnionHelper::validateOpenUnion(\$data['{$name}']) : null";
+            }
+
+            // Fallback for unions with only local refs
+            if ($isRequired) {
+                return "\$data['{$name}']";
+            }
+
+            return "\$data['{$name}'] ?? null";
+        }
+
+        // Handle blob types (already converted to BlobReference by the protocol)
+        if ($type === 'blob') {
+            if ($isRequired) {
+                return "\$data['{$name}']";
+            }
+
+            return "\$data['{$name}'] ?? null";
         }
 
         // Default: simple property access
···
     public function getModelMapper(): ModelMapper
     {
         return $this->modelMapper;
+    }
+
+    /**
+     * Get the extension manager.
+     */
+    public function getExtensions(): ExtensionManager
+    {
+        return $this->extensions;
     }
 }

src/Generator/ModelMapper.php

···
      */
     public function __construct(?NamingConverter $naming = null, ?TypeMapper $typeMapper = null)
     {
-        $this->naming = $naming ?? new NamingConverter();
+        $this->naming = $naming ?? new NamingConverter;
         $this->typeMapper = $typeMapper ?? new TypeMapper($this->naming);
     }
 
···
      * Generate toModel method body.
      *
      * @param  array<string, array<string, mixed>>  $properties
-     * @param  string  $modelClass
      */
     public function generateToModelBody(array $properties, string $modelClass = 'Model'): string
     {

src/Generator/NamingConverter.php

···
     {
         $nsid = Nsid::parse($nsidString);
 
-        // Split authority into parts (e.g., "app.bsky" -> ["app", "bsky"])
-        $authorityParts = array_reverse(explode('.', $nsid->getAuthority()));
+        // Split authority into parts (e.g., "blog.pckt" -> ["blog", "pckt"])
+        $authorityParts = explode('.', $nsid->getAuthority());
 
         // Convert each part to PascalCase
         $namespaceParts = array_map(

src/Generator/PropertyGenerator.php

···
      */
     public function __construct(?TypeMapper $typeMapper = null, ?StubRenderer $renderer = null)
     {
-        $this->typeMapper = $typeMapper ?? new TypeMapper();
-        $this->renderer = $renderer ?? new StubRenderer();
+        $this->typeMapper = $typeMapper ?? new TypeMapper;
+        $this->renderer = $renderer ?? new StubRenderer;
     }
 
     /**

src/Generator/TemplateRenderer.php

···
             }
 
             $propertiesCode[] = sprintf(
-                "%s    public readonly %s $%s;",
+                '%s    public readonly %s $%s;',
                 $docComment,
                 $typeHint,
                 $prop['name']

src/Generator/TypeMapper.php

···
 
 namespace SocialDept\Schema\Generator;
 
+use SocialDept\Schema\Support\ExtensionManager;
+
 class TypeMapper
 {
     /**
      * Naming converter instance.
      */
     protected NamingConverter $naming;
+
+    /**
+     * Local definition map for resolving #refs.
+     *
+     * @var array<string, string>
+     */
+    protected array $localDefinitions = [];
+
+    /**
+     * Extension manager instance.
+     */
+    protected ExtensionManager $extensions;
 
     /**
      * Create a new TypeMapper.
      */
-    public function __construct(?NamingConverter $naming = null)
+    public function __construct(?NamingConverter $naming = null, ?ExtensionManager $extensions = null)
     {
-        $this->naming = $naming ?? new NamingConverter();
+        $this->naming = $naming ?? new NamingConverter;
+        $this->extensions = $extensions ?? new ExtensionManager;
+    }
+
+    /**
+     * Set local definitions for resolving local references.
+     *
+     * @param  array<string, string>  $localDefinitions  Map of #ref => class name
+     */
+    public function setLocalDefinitions(array $localDefinitions): void
+    {
+        $this->localDefinitions = $localDefinitions;
     }
 
     /**
···
         $type = $definition['type'] ?? 'unknown';
 
         $phpType = match ($type) {
-            'string' => 'string',
+            'string' => $this->mapStringType($definition),
             'integer' => 'int',
             'boolean' => 'bool',
             'number' => 'float',
             'array' => $this->mapArrayType($definition),
             'object' => $this->mapObjectType($definition),
-            'blob' => '\\SocialDept\\Schema\\Data\\BlobReference',
+            'blob' => 'BlobReference',
             'bytes' => 'string',
             'cid-link' => 'string',
             'unknown' => 'mixed',
···
         };
 
         if ($nullable && $phpType !== 'mixed') {
-            return '?'.$phpType;
+            $phpType = '?'.$phpType;
         }
 
-        return $phpType;
+        return $this->extensions->filter('filter:type:phpType', $phpType, $definition, $nullable);
     }
 
     /**
···
         $type = $definition['type'] ?? 'unknown';
 
         $docType = match ($type) {
-            'string' => 'string',
+            'string' => $this->mapStringType($definition),
             'integer' => 'int',
             'boolean' => 'bool',
             'number' => 'float',
             'array' => $this->mapArrayDocType($definition),
             'object' => $this->mapObjectDocType($definition),
-            'blob' => '\\SocialDept\\Schema\\Data\\BlobReference',
+            'blob' => 'BlobReference',
             'bytes' => 'string',
             'cid-link' => 'string',
             'unknown' => 'mixed',
···
         };
 
         if ($nullable && $docType !== 'mixed') {
-            return $docType.'|null';
+            $docType = $docType.'|null';
+        }
+
+        return $this->extensions->filter('filter:type:phpDocType', $docType, $definition, $nullable);
+    }
+
+    /**
+     * Map string type.
+     *
+     * @param  array<string, mixed>  $definition
+     */
+    protected function mapStringType(array $definition): string
+    {
+        // Check for datetime format
+        if (isset($definition['format']) && $definition['format'] === 'datetime') {
+            return 'Carbon';
         }
 
-        return $docType;
+        return 'string';
     }
 
     /**
···
         }
 
         $itemType = $this->toPhpDocType($definition['items']);
+
+        // array<mixed> is redundant, just use array
+        if ($itemType === 'mixed') {
+            return 'array';
+        }
 
         return "array<{$itemType}>";
     }
···
             return 'mixed';
         }
 
-        // Convert NSID reference to class name
-        return '\\'.$this->naming->nsidToClassName($definition['ref']);
+        $ref = $definition['ref'];
+
+        // Resolve local references using the local definitions map
+        if (str_starts_with($ref, '#')) {
+            return $this->localDefinitions[$ref] ?? 'mixed';
+        }
+
+        // Handle NSID fragments (e.g., com.atproto.label.defs#selfLabels)
+        // Extract just the NSID part for class resolution
+        if (str_contains($ref, '#')) {
+            $ref = explode('#', $ref)[0];
+        }
+
+        // Convert NSID reference to fully qualified class name
+        $fqcn = $this->naming->nsidToClassName($ref);
+
+        // Extract short class name (last part after final backslash)
+        $parts = explode('\\', $fqcn);
+
+        return end($parts);
     }
 
     /**
···
      */
     protected function mapUnionType(array $definition): string
     {
-        // For runtime type hints, unions of different types must be 'mixed'
-        return 'mixed';
+        // Open unions (closed=false or not set) should always be mixed
+        // because future schema versions could add more types
+        $isClosed = $definition['closed'] ?? false;
+
+        if (! $isClosed) {
+            return 'mixed';
+        }
+
+        // For closed unions, extract external refs
+        $refs = $definition['refs'] ?? [];
+        $externalRefs = array_values(array_filter($refs, fn ($ref) => ! str_starts_with($ref, '#')));
+
+        if (empty($externalRefs)) {
+            return 'mixed';
+        }
+
+        // Build union type with all variants
+        $types = [];
+        foreach ($externalRefs as $ref) {
+            // Handle NSID fragments - extract just the NSID part
+            if (str_contains($ref, '#')) {
+                $ref = explode('#', $ref)[0];
+            }
+
+            // Convert to fully qualified class name, then extract short name
+            $fqcn = $this->naming->nsidToClassName($ref);
+            $parts = explode('\\', $fqcn);
+            $types[] = end($parts);
+        }
+
+        // Return union type (e.g., "Theme|ThemeV2" or just "Theme" for single ref)
+        return implode('|', $types);
     }
 
     /**
···
             return 'mixed';
         }
 
-        $types = array_map(
-            fn ($ref) => '\\'.$this->naming->nsidToClassName($ref),
-            $definition['refs']
-        );
+        // Open unions should be typed as mixed since future types could be added
+        $isClosed = $definition['closed'] ?? false;
+        if (! $isClosed) {
+            return 'mixed';
+        }
+
+        // For closed unions, list all the specific types
+        $types = [];
+        foreach ($definition['refs'] as $ref) {
+            // Resolve local references using the local definitions map
+            if (str_starts_with($ref, '#')) {
+                $types[] = $this->localDefinitions[$ref] ?? 'mixed';
+
+                continue;
+            }
+
+            // Handle NSID fragments - extract just the NSID part
+            if (str_contains($ref, '#')) {
+                $ref = explode('#', $ref)[0];
+            }
+
+            // Convert to fully qualified class name, then extract short name
+            $fqcn = $this->naming->nsidToClassName($ref);
+            $parts = explode('\\', $fqcn);
+            $types[] = end($parts);
+        }
 
         return implode('|', $types);
     }
···
     {
         $type = $definition['type'] ?? 'unknown';
 
+        // Check for datetime format on strings
+        if ($type === 'string' && isset($definition['format']) && $definition['format'] === 'datetime') {
+            return true;
+        }
+
         return in_array($type, ['ref', 'blob']);
     }
 
···
     {
         $type = $definition['type'] ?? 'unknown';
 
+        if ($type === 'string' && isset($definition['format']) && $definition['format'] === 'datetime') {
+            return ['Carbon\\Carbon'];
+        }
+
         if ($type === 'blob') {
             return ['SocialDept\\Schema\\Data\\BlobReference'];
         }
 
         if ($type === 'ref' && isset($definition['ref'])) {
-            return [$this->naming->nsidToClassName($definition['ref'])];
+            $ref = $definition['ref'];
+
+            // Skip local references (starting with #)
+            if (str_starts_with($ref, '#')) {
+                return [];
+            }
+
+            // Handle NSID fragments - extract just the NSID part
+            if (str_contains($ref, '#')) {
+                $ref = explode('#', $ref)[0];
+            }
+
+            return [$this->naming->nsidToClassName($ref)];
         }
 
         if ($type === 'union' && isset($definition['refs'])) {
-            return array_map(
-                fn ($ref) => $this->naming->nsidToClassName($ref),
-                $definition['refs']
-            );
+            // Open unions don't need use statements since they're typed as mixed
+            $isClosed = $definition['closed'] ?? false;
+            if (! $isClosed) {
+                return [];
+            }
+
+            // For closed unions, import the referenced classes
+            $classes = [];
+
+            foreach ($definition['refs'] as $ref) {
+                // Skip local references
+                if (str_starts_with($ref, '#')) {
+                    continue;
+                }
+
+                // Handle NSID fragments - extract just the NSID part
+                if (str_contains($ref, '#')) {
+                    $ref = explode('#', $ref)[0];
+                }
+
+                $classes[] = $this->naming->nsidToClassName($ref);
+            }
+
+            return $classes;
         }
 
-        return [];
+        $uses = [];
+
+        return $this->extensions->filter('filter:type:useStatements', $uses, $definition);
+    }
+
+    /**
+     * Get the extension manager.
+     */
+    public function getExtensions(): ExtensionManager
+    {
+        return $this->extensions;
     }
 }

stubs/class.stub

···
 {{ docBlock }}
 class {{ className }}{{ extends }}{{ implements }}
 {
-{{ properties }}
-
-{{ constructor }}
+{{ properties }}{{ constructor }}
 
 {{ methods }}
 }

stubs/method.stub

···
 {{ docBlock }}
-{{ visibility }}{{ static }}function {{ name }}({{ parameters }}){{ returnType }}
-{
+    {{ visibility }}{{ static }}function {{ name }}({{ parameters }}){{ returnType }}
+    {
 {{ body }}
-}
+    }