@blockml/parser 0.9.4 → 0.9.5

package/blocks/org/blockml/bml/compiler/parser/capability/SplitQName.bml

@@ -1,12 +1,6 @@
-<!--
-  Parser Capability — SplitQName
-  FQN: org.blockml.bml.compiler.parser.capability.SplitQName
--->
-<block
-  xmlns="http://blockml.org/bml"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
-                      "
+<!--Parser Capability — SplitQName
+  FQN: org.blockml.bml.compiler.parser.capability.SplitQName-->
+<parcap:SplitQName xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -29,20 +23,25 @@
   xmlns:serdocumentation="org.blockml.bml.compiler.serializer.documentation"
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
 
-  <name>SplitQName</name>
-  <type>parcap:SplitQName</type>
-  <baseType>core:Capability</baseType>
-  <is>Split prefixed QName into prefix and local name</is>
-
-  <documentation>Split prefixed QName into prefix and local name</documentation>
-
+  <baseType>
+    core:Capability
+  </baseType>
+  <is>
+    Split prefixed QName into prefix and local name
+  </is>
+  <documentation>
+    Split prefixed QName into prefix and local name
+  </documentation>
   <properties>
     <qname type="type:Text">
-      <documentation>qname. TS type: type:Text. (required)</documentation>
+      <documentation>
+        qname. TS type: type:Text. (required)
+      </documentation>
     </qname>
     <parts type="parmap:QNameParts">
-      <documentation>parts. TS type: parmap:QNameParts. (required)</documentation>
+      <documentation>
+        parts. TS type: parmap:QNameParts. (required)
+      </documentation>
     </parts>
   </properties>
-
-</block>
+</parcap:SplitQName>

package/blocks/org/blockml/bml/compiler/parser/capability/TrimText.bml

@@ -1,12 +1,6 @@
-<!--
-  Parser Capability — TrimText
-  FQN: org.blockml.bml.compiler.parser.capability.TrimText
--->
-<block
-  xmlns="http://blockml.org/bml"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
-                      "
+<!--Parser Capability — TrimText
+  FQN: org.blockml.bml.compiler.parser.capability.TrimText-->
+<parcap:TrimText xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -29,26 +23,29 @@
   xmlns:serdocumentation="org.blockml.bml.compiler.serializer.documentation"
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
 
-  <name>TrimText</name>
-  <type>parcap:TrimText</type>
-  <baseType>core:Capability</baseType>
-  <is>Strip common leading indent, then trim, from text node value</is>
-
+  <baseType>
+    core:Capability
+  </baseType>
+  <is>
+    Strip common leading indent, then trim, from text node value
+  </is>
   <documentation>
     Strip the longest leading whitespace prefix shared by non-empty lines (pretty-print indent), then trim surrounding whitespace. Relative extra indent on individual lines is kept.
-
+    
     If the first line has non-whitespace and no leading space or tab (text glued to the opening tag), that line is excluded from the prefix calculation. One or more leading spaces or tabs on that same line mean the first line counts. A whitespace-only first line is ignored like any blank line.
-
+    
     Used by GetCharacterData for documentation prose and other character-data hosts (B13).
   </documentation>
-
   <properties>
     <value type="type:Text">
-      <documentation>value. TS type: type:Text. (required)</documentation>
+      <documentation>
+        value. TS type: type:Text. (required)
+      </documentation>
     </value>
     <trimmed type="type:Text">
-      <documentation>trimmed. TS type: type:Text. (required)</documentation>
+      <documentation>
+        trimmed. TS type: type:Text. (required)
+      </documentation>
     </trimmed>
   </properties>
-
-</block>
+</parcap:TrimText>

package/blocks/org/blockml/bml/compiler/parser/capability/TypeExpressionToString.bml

@@ -1,12 +1,6 @@
-<!--
-  Parser Capability — TypeExpressionToString
-  FQN: org.blockml.bml.compiler.parser.capability.TypeExpressionToString
--->
-<block
-  xmlns="http://blockml.org/bml"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
-                      "
+<!--Parser Capability — TypeExpressionToString
+  FQN: org.blockml.bml.compiler.parser.capability.TypeExpressionToString-->
+<parcap:TypeExpressionToString xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -29,20 +23,25 @@
   xmlns:serdocumentation="org.blockml.bml.compiler.serializer.documentation"
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
 
-  <name>TypeExpressionToString</name>
-  <type>parcap:TypeExpressionToString</type>
-  <baseType>core:Capability</baseType>
-  <is>Serialize TypeExpression back to attribute string (internal/debug)</is>
-
-  <documentation>Serialize TypeExpression back to attribute string (internal/debug)</documentation>
-
+  <baseType>
+    core:Capability
+  </baseType>
+  <is>
+    Serialize TypeExpression back to attribute string (internal/debug)
+  </is>
+  <documentation>
+    Serialize TypeExpression back to attribute string (internal/debug)
+  </documentation>
   <properties>
     <type type="bomtype:TypeExpression">
-      <documentation>type. TS type: bomtype:TypeExpression. (required)</documentation>
+      <documentation>
+        type. TS type: bomtype:TypeExpression. (required)
+      </documentation>
     </type>
     <text type="type:Text">
-      <documentation>text. TS type: type:Text. (required)</documentation>
+      <documentation>
+        text. TS type: type:Text. (required)
+      </documentation>
     </text>
   </properties>
-
-</block>
+</parcap:TypeExpressionToString>

package/blocks/org/blockml/bml/compiler/parser/capability/VisibilityPrefix.bml

@@ -1,12 +1,6 @@
-<!--
-  Parser Capability — VisibilityPrefix
-  FQN: org.blockml.bml.compiler.parser.capability.VisibilityPrefix
--->
-<block
-  xmlns="http://blockml.org/bml"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
-                      "
+<!--Parser Capability — VisibilityPrefix
+  FQN: org.blockml.bml.compiler.parser.capability.VisibilityPrefix-->
+<parcap:VisibilityPrefix xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -29,20 +23,25 @@
   xmlns:serdocumentation="org.blockml.bml.compiler.serializer.documentation"
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
 
-  <name>VisibilityPrefix</name>
-  <type>parcap:VisibilityPrefix</type>
-  <baseType>core:Capability</baseType>
-  <is>Map visibility enum to XML prefix (shared with serializer util)</is>
-
-  <documentation>Map visibility enum to XML prefix (shared with serializer util)</documentation>
-
+  <baseType>
+    core:Capability
+  </baseType>
+  <is>
+    Map visibility enum to XML prefix (shared with serializer util)
+  </is>
+  <documentation>
+    Map visibility enum to XML prefix (shared with serializer util)
+  </documentation>
   <properties>
     <visibility type="type:Text">
-      <documentation>visibility. TS type: type:Text. (optional)</documentation>
+      <documentation>
+        visibility. TS type: type:Text. (optional)
+      </documentation>
     </visibility>
     <prefix type="type:Text">
-      <documentation>prefix. TS type: type:Text. (required)</documentation>
+      <documentation>
+        prefix. TS type: type:Text. (required)
+      </documentation>
     </prefix>
   </properties>
-
-</block>
+</parcap:VisibilityPrefix>

package/blocks/org/blockml/bml/compiler/parser/capability/XmlTriviaFromElement.bml

@@ -1,12 +1,6 @@
-<!--
-  Parser Capability — XmlTriviaFromElement
-  FQN: org.blockml.bml.compiler.parser.capability.XmlTriviaFromElement
--->
-<block
-  xmlns="http://blockml.org/bml"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
-                      "
+<!--Parser Capability — XmlTriviaFromElement
+  FQN: org.blockml.bml.compiler.parser.capability.XmlTriviaFromElement-->
+<parcap:XmlTriviaFromElement xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -29,24 +23,28 @@
   xmlns:serdocumentation="org.blockml.bml.compiler.serializer.documentation"
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
 
-  <name>XmlTriviaFromElement</name>
-  <type>parcap:XmlTriviaFromElement</type>
-  <baseType>core:Capability</baseType>
-  <is>Build XmlTrivia from element comment context</is>
-
-  <documentation>Build XmlTrivia from element comment context</documentation>
-
+  <baseType>
+    core:Capability
+  </baseType>
+  <is>
+    Build XmlTrivia from element comment context
+  </is>
+  <documentation>
+    Build XmlTrivia from element comment context
+  </documentation>
   <references>
     <see type="pardocumentation:XmlCommentsParse" relation="SeeAlso" />
   </references>
-
   <properties>
     <element type="parmap:XmlDomNode">
-      <documentation>element. TS type: parmap:XmlDomNode. (required)</documentation>
+      <documentation>
+        element. TS type: parmap:XmlDomNode. (required)
+      </documentation>
     </element>
     <trivia type="bomcommon:XmlTrivia">
-      <documentation>trivia. TS type: bomcommon:XmlTrivia. (optional)</documentation>
+      <documentation>
+        trivia. TS type: bomcommon:XmlTrivia. (optional)
+      </documentation>
     </trivia>
   </properties>
-
-</block>
+</parcap:XmlTriviaFromElement>

package/blocks/org/blockml/bml/compiler/parser/config/MapTimeDiagnosticCodes.bml

@@ -1,12 +1,6 @@
-<!--
-  Parser — MapTimeDiagnosticCodes
-  FQN: org.blockml.bml.compiler.parser.config.MapTimeDiagnosticCodes
--->
-<block
-  xmlns="http://blockml.org/bml"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
-                      "
+<!--Parser — MapTimeDiagnosticCodes
+  FQN: org.blockml.bml.compiler.parser.config.MapTimeDiagnosticCodes-->
+<parconfig:MapTimeDiagnosticCodes xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -29,17 +23,20 @@
   xmlns:serdocumentation="org.blockml.bml.compiler.serializer.documentation"
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
 
-  <name>MapTimeDiagnosticCodes</name>
-  <type>parconfig:MapTimeDiagnosticCodes</type>
-  <baseType>parser:ParserType</baseType>
-  <is>Diagnostic codes emitted during parse pipeline and mapping</is>
-
-  <documentation>Hard-fail codes return document: null. Map-time codes may attach to ParseResult with continueOnError.</documentation>
-
+  <baseType>
+    parser:ParserType
+  </baseType>
+  <is>
+    Diagnostic codes emitted during parse pipeline and mapping
+  </is>
+  <documentation>
+    Hard-fail codes return document: null. Map-time codes may attach to ParseResult with continueOnError.
+  </documentation>
   <properties>
     <codes type="type:Text[]">
-      <documentation>Ordered: BML_UNSUPPORTED_FORMAT, BML_MALFORMED_XML, BML_MISSING_ROOT, BML_INVALID_ROOT, BML_MAP_ERROR, BML_UNKNOWN_NAMESPACE_PREFIX, BML_UNQUALIFIED_BLOCK_REFERENCE, BML_UNKNOWN_TYPE, BML_INVALID_TYPE_REFERENCE, BML_UNKNOWN_ELEMENT, BML_UNKNOWN_ATTRIBUTE, BML_UNKNOWN_DIRECTIVE, BML_STANDALONE_COMPOSITION, BML_NESTED_COMPOSITION, BML_DUPLICATE_COMPOSITION, BML_DUPLICATE_PROPERTY_VALUE, BML_UNEXPECTED_TEXT, BML_INVALID_VALUE (required)</documentation>
+      <documentation>
+        Ordered: BML_UNSUPPORTED_FORMAT, BML_MALFORMED_XML, BML_MISSING_ROOT, BML_INVALID_ROOT, BML_MISSING_BLOCK_TYPE, BML_MISSING_EMBEDDED_BLOCK_TYPE, BML_MISSING_SUBBLOCK_NAME, BML_MAP_ERROR, BML_UNKNOWN_NAMESPACE_PREFIX, BML_UNQUALIFIED_BLOCK_REFERENCE, BML_UNKNOWN_TYPE, BML_INVALID_TYPE_REFERENCE, BML_UNKNOWN_ELEMENT, BML_UNKNOWN_ATTRIBUTE, BML_UNKNOWN_DIRECTIVE, BML_STANDALONE_COMPOSITION, BML_NESTED_COMPOSITION, BML_DUPLICATE_COMPOSITION, BML_DUPLICATE_PROPERTY_VALUE, BML_UNEXPECTED_TEXT, BML_INVALID_VALUE (required)
+      </documentation>
     </codes>
   </properties>
-
-</block>
+</parconfig:MapTimeDiagnosticCodes>

package/blocks/org/blockml/bml/compiler/parser/config/ParserConstants.bml

@@ -1,12 +1,6 @@
-<!--
-  Parser — ParserConstants
-  FQN: org.blockml.bml.compiler.parser.config.ParserConstants
--->
-<block
-  xmlns="http://blockml.org/bml"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
-                      "
+<!--Parser — ParserConstants
+  FQN: org.blockml.bml.compiler.parser.config.ParserConstants-->
+<parconfig:ParserConstants xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -29,26 +23,35 @@
   xmlns:serdocumentation="org.blockml.bml.compiler.serializer.documentation"
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation">
 
-  <name>ParserConstants</name>
-  <type>parconfig:ParserConstants</type>
-  <baseType>parser:ParserType</baseType>
-  <is>Well-known URIs and V1 root element name</is>
-
-  <documentation>Shared across pipeline, qname resolution, and namespace extraction.</documentation>
-
+  <baseType>
+    parser:ParserType
+  </baseType>
+  <is>
+    Well-known URIs and V1 root element name
+  </is>
+  <documentation>
+    Shared across pipeline, qname resolution, and namespace extraction.
+  </documentation>
   <properties>
     <XSI_NS type="type:Text">
-      <documentation>XSI_NS. TS type: type:Text. (required)</documentation>
+      <documentation>
+        XSI_NS. TS type: type:Text. (required)
+      </documentation>
     </XSI_NS>
     <BML_XMLNS type="type:Text">
-      <documentation>BML_XMLNS. TS type: type:Text. (required)</documentation>
+      <documentation>
+        BML_XMLNS. TS type: type:Text. (required)
+      </documentation>
     </BML_XMLNS>
     <TYPE_REFERENCE_ENTITY type="type:Text">
-      <documentation>TYPE_REFERENCE_ENTITY. TS type: type:Text. (required)</documentation>
+      <documentation>
+        TYPE_REFERENCE_ENTITY. TS type: type:Text. (required)
+      </documentation>
     </TYPE_REFERENCE_ENTITY>
     <V1_ROOT_ELEMENT type="type:Text">
-      <documentation>V1_ROOT_ELEMENT. TS type: type:Text. (required)</documentation>
+      <documentation>
+        V1_ROOT_ELEMENT. TS type: type:Text. (required)
+      </documentation>
     </V1_ROOT_ELEMENT>
   </properties>
-
-</block>
+</parconfig:ParserConstants>

package/blocks/org/blockml/bml/compiler/parser/documentation/ArchitectureOverview.bml

@@ -1,12 +1,6 @@
-<!--
-  Parser Documentation — ArchitectureOverview
-  FQN: org.blockml.bml.compiler.parser.documentation.ArchitectureOverview
--->
-<block
-  xmlns="http://blockml.org/bml"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
-                      "
+<!--Parser Documentation — ArchitectureOverview
+  FQN: org.blockml.bml.compiler.parser.documentation.ArchitectureOverview-->
+<pardocumentation:ArchitectureOverview xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,20 +24,23 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>ArchitectureOverview</name>
-  <type>pardocumentation:ArchitectureOverview</type>
-  <baseType>core:Documentation</baseType>
-  <is>Parse pipeline [1]–[5] and module decomposition</is>
-
-  <documentation><![CDATA[Entry point: parse(source, options?) → ParseResult (B26).
-
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Parse pipeline [1]–[5] and module decomposition
+  </is>
+  <documentation>
+    <![CDATA[
+    Entry point: parse(source, options?) → ParseResult (B26).
+    
     Stage 1 pipeline:
     [1] Format detect (B24) — detectFormat(); strip UTF-8 BOM; first '<' → xml
     [2] XML DOM (B18) — parseXmlDom() via @xmldom/xmldom
-    [3] Root type resolver — assertBlockRoot(); V1: <block> only
-    [4] Namespace resolver — extractNamespaceBindings(), mergeSourceInfo(); FQN resolution
+    [3] Root type resolver — assertBlockRoot(); <block> or type-or-name tag (doc:DocumentFormat)
+    [4] Namespace resolver — extractNamespaceBindings(), mergeSourceInfo(); FQN resolution; rootForm
     [5] BML → BOM mapper — mapDocumentBlock() → BomDocument
-
+    
     Module decomposition (packages/parser/src/):
     • parse.ts → parcap:Parse orchestrates [1]–[5]
     • pipeline/format-detect.ts → parcap:DetectFormat
@@ -56,11 +53,12 @@
     • map/type-expression.ts → parcap:ParseTypeExpression
     • map/member-value.ts → parcap:ParseMemberValue, ContainsUnescapedInterpolation, ExpressionFromRaw
     • map/directives.ts → parcap:ParseDirectives, ParseBmlMeta
-    • util/* → visibility, boolean, qname, xml helpers]]></documentation>
-
+    • util/* → visibility, boolean, qname, xml helpers
+    ]]>
+  </documentation>
   <references>
     <see type="pardocumentation:V1Scope" relation="ReadNext" />
     <see type="parcap:Parse" relation="Defines" />
+    <see type="doc:DocumentFormat" relation="SeeAlso" />
   </references>
-
-</block>
+</pardocumentation:ArchitectureOverview>

package/blocks/org/blockml/bml/compiler/parser/documentation/AttributeClassification.bml

@@ -1,12 +1,6 @@
-<!--
-  Parser Documentation — AttributeClassification
-  FQN: org.blockml.bml.compiler.parser.documentation.AttributeClassification
--->
-<block
-  xmlns="http://blockml.org/bml"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
-                      "
+<!--Parser Documentation — AttributeClassification
+  FQN: org.blockml.bml.compiler.parser.documentation.AttributeClassification-->
+<pardocumentation:AttributeClassification xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,32 +24,33 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>AttributeClassification</name>
-  <type>pardocumentation:AttributeClassification</type>
-  <baseType>core:Documentation</baseType>
-  <is>Fixed priority chain for XML attributes (Rules 1–3)</is>
-
-  <documentation>When mapping an XML element, every attribute is classified — first matching rule wins:
-
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Fixed priority chain for XML attributes (Rules 1–3)
+  </is>
+  <documentation>
+    When mapping an XML element, every attribute is classified — first matching rule wins:
+    
     Rule 1 — XML infrastructure:
     • xmlns* → SourceInfo.namespaceBindings (incl. xmlns:xsi — B25)
     • xsi:schemaLocation / xsi:noNamespaceSchemaLocation → SourceInfo (B25)
     • other xsi:* → ignore (not memberValues)
-
+    
     Rule 2 — bml:* attributes:
     • Composition meta (bml:id, bml:version, bml:generics, …) → BlockInstance fields
     • Directives (bml:each, bml:if, …) → directives[]
     • Unknown bml:* → BML_UNKNOWN_DIRECTIVE (error at map time — B2)
-
+    
     Rule 3 — Grammar vs instance:
     • On definition/grammar nodes, remaining attributes are closed. Unknown → BML_UNKNOWN_ATTRIBUTE (structural error); preserved as unknownAttributes.
     • On block instances, remaining attributes → memberValues[name] (camelCase); ${ expr } → ExpressionValue { raw } (B4). Unknown members are a validator error.
-
-    Serialize side of Rule 1 (B25 re-emit) → @blockml/serializer.</documentation>
-
+    
+    Serialize side of Rule 1 (B25 re-emit) → @blockml/serializer.
+  </documentation>
   <references>
     <see type="pardocumentation:StructuralGrammar" relation="ReadNext" />
     <see type="parcap:ParseDirectives" relation="SeeAlso" />
   </references>
-
-</block>
+</pardocumentation:AttributeClassification>

package/blocks/org/blockml/bml/compiler/parser/documentation/BlockMetadataMapping.bml

@@ -1,12 +1,6 @@
-<!--
-  Parser Documentation — BlockMetadataMapping
-  FQN: org.blockml.bml.compiler.parser.documentation.BlockMetadataMapping
--->
-<block
-  xmlns="http://blockml.org/bml"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
-                      "
+<!--Parser Documentation — BlockMetadataMapping
+  FQN: org.blockml.bml.compiler.parser.documentation.BlockMetadataMapping-->
+<pardocumentation:BlockMetadataMapping xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,28 +24,36 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>BlockMetadataMapping</name>
-  <type>pardocumentation:BlockMetadataMapping</type>
-  <baseType>core:Documentation</baseType>
-  <is>Block definition metadata field mapping</is>
-
-  <documentation><![CDATA[Map <block> child elements to BlockDefinition fields:
-
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Block definition metadata field mapping
+  </is>
+  <documentation>
+    <![CDATA[
+    Map definition-wrapper child elements to BlockDefinition fields.
+    The wrapper may be legacy <block> or a type-or-name tag (doc:DocumentFormat) on the
+    document root, each Sub-Block, and each embed. A type tag supplies type; a Sub-Block
+    tag supplies name (type stays derived). Child <type>/<name> are omitted unless they
+    repeat the same identity.
+    
     Identity: name, type, baseType, is, isNot, version, definition
     Structural: since, status, summary, documentation, abstract, final
     Aggregations: keywords, changelog, examples, references, constraints, aliases,
     language, genericTypes, contracts, properties, aggregations, associations,
     capabilities, subBlocks, embeddedBlocks
-
+    
     • xmlRendering (bml:xml metadata) stored on BlockDefinition — NOT in directives[] (B23/D3)
     • authoredPlacement stored for dual element|attribute forms (D9)
     • authoredCharacterDataForm for text vs CDATA (D8)
+    • authoredNameChild / authoredTypeChild when child name / type elements are present
     • TrimText on character data: common leading indent stripped, then trim; a first line glued to the opening tag (no leading whitespace) is excluded from the prefix (B13)
-    • Visibility prefixes stripped → logical name + visibility (B14 parse half)]]></documentation>
-
+    • Visibility prefixes stripped → logical name + visibility (B14 parse half)
+    ]]>
+  </documentation>
   <references>
     <see type="pardocumentation:MemberMapping" relation="ReadNext" />
     <see type="def:BlockDefinition" relation="SeeAlso" />
   </references>
-
-</block>
+</pardocumentation:BlockMetadataMapping>

package/blocks/org/blockml/bml/compiler/parser/documentation/DesignDecisions.bml

@@ -1,12 +1,6 @@
-<!--
-  Parser Documentation — DesignDecisions
-  FQN: org.blockml.bml.compiler.parser.documentation.DesignDecisions
--->
-<block
-  xmlns="http://blockml.org/bml"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
-                      "
+<!--Parser Documentation — DesignDecisions
+  FQN: org.blockml.bml.compiler.parser.documentation.DesignDecisions-->
+<pardocumentation:DesignDecisions xmlns="http://blockml.org/bml"
   xmlns:blockml="org.blockml.bml"
   xmlns:bom="org.blockml.bml.bom"
   xmlns:bomapi="org.blockml.bml.bom.api"
@@ -30,14 +24,16 @@
   xmlns:valdocumentation="org.blockml.bml.compiler.validator.documentation"
   xmlns:doc="org.blockml.bml.documentation">
 
-  <name>DesignDecisions</name>
-  <type>pardocumentation:DesignDecisions</type>
-  <baseType>core:Documentation</baseType>
-  <is>Normative parser design decisions</is>
-
-  <documentation><![CDATA[
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Normative parser design decisions
+  </is>
+  <documentation>
+    <![CDATA[
     # Normative parser design decisions
-
+    
     - B2: unknown bml:* → error at map (BML_UNKNOWN_DIRECTIVE); unknown instance members → validator error (BML_UNKNOWN_PROPERTY).
     - B3: inputType/outputType → TypeExpression at map time.
     - B4: ExpressionValue.raw only; AST via core utility.
@@ -51,12 +47,11 @@
     - B19: redundant aggregation type — map must not apply.
     - B23: preserve xmlRendering + D6 recipe at Stage 1.
     - B24: format detector (BOM strip, first '<').
-    - B25: store xmlns:xsi + schemaLocation on SourceInfo.
+    - B25: store xmlns:xsi + schemaLocation on SourceInfo; record rootForm (block vs type-as-root).
     - B26: parse() entry; types in @blockml/bom.
-  ]]></documentation>
-
+    ]]>
+  </documentation>
   <references>
     <see type="pardocumentation:RoundtripContract" relation="ReadNext" />
   </references>
-
-</block>
+</pardocumentation:DesignDecisions>