@machineblocks/render-target 0.0.0-stage → 0.1.0

package/blocks/com/machineblocks/bml/target/render/documentation/LeafOptimization.bml

@@ -0,0 +1,44 @@
+<!--Render Target Documentation — LeafOptimization
+  FQN: com.machineblocks.bml.target.render.documentation.LeafOptimization-->
+<rdoc:LeafOptimization xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Direct mb_block call for single-NativeBlock types
+  </is>
+  <documentation>
+    Some block types are a single NativeBlock: every property maps 1:1 to
+    native settings, no sub-blocks, no multi-child composition. Example:
+    com.machineblocks.bml.bricks.Standard.
+
+    Standalone compile of such a block emits a direct mb_block() main call.
+    Customizer variables are the settings. There is no typed wrapper module and
+    no mb_param_* extraction layer:
+
+        mb_block(
+            config = mb_config,
+            settings = [
+                ["size", size],
+                ["studs", studs]
+            ]
+        );
+
+    This avoids the extra module call found in older hand-maintained SCAD
+    artifacts. Composite blocks with real inner structure (Wall, Calibrator)
+    still emit typed modules.
+
+    Exactly one NativeBlock child uses this direct call. Zero children returns
+    files: [] and diagnostic MB_EMPTY_BLOCK. Two or more children use the
+    composite module in CompositeRendering. A leaf parameter that is not a
+    property reference, or a default other than a boolean, number, string, or
+    SizeXYZ, returns files: [] and diagnostic BML_LEAF_VALUE_UNSUPPORTED.
+
+  </documentation>
+  <references>
+    <see type="rdoc:CompositeRendering" relation="ReadNext" />
+  </references>
+</rdoc:LeafOptimization>

package/blocks/com/machineblocks/bml/target/render/documentation/NativeMappings.bml

@@ -0,0 +1,58 @@
+<!--Render Target Documentation — NativeMappings
+  FQN: com.machineblocks.bml.target.render.documentation.NativeMappings-->
+<rdoc:NativeMappings xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Declarative map from built-in capabilities to native SCAD functions
+  </is>
+  <documentation>
+    ScadBlockProcessor reads a declarative JSON file, scad-native-mappings.json,
+    shipped with this package. It maps #built-in capability calls to native SCAD
+    functions when a 1:1 equivalent exists, so trivial calls do not import a
+    helper.
+
+    Location: package root of @machineblocks/render-target, file
+    scad-native-mappings.json.
+
+    Format: service FQN to function name to { native, arity }.
+    native null means no direct SCAD equivalent: emit the FQN-prefixed function
+    and add a use import. arity -1 means variadic.
+
+    Initial map:
+
+        org.blockml.bml.service.Math
+          min max floor ceil round abs pow sqrt — native of the same name, arity 1 or 2
+          round_n clamp — native null
+        org.blockml.bml.service.Strings
+          length — native len, arity 1
+          concat — native str, arity -1
+
+    Resolution for each #built-in in ${ } expressions or in embedded expressions
+    inside SCAD implementations:
+
+        #math.min(a, b)       -> min(a, b), no import
+        #math.round_n(x, 1)   -> bom__org__blockml__service__Math__round_n(x, 1)
+                                 plus use of Math.scad
+        #strings.length(s)    -> len(s), no import
+
+    Functions inside the service SCAD files use the bom__ prefix and __ separators:
+
+        function bom__org__blockml__service__Math__round_n(x, n) =
+          round(x * pow(10, n)) / pow(10, n);
+        function bom__org__blockml__service__Math__clamp(x, lo, hi) =
+          min(max(x, lo), hi);
+
+    The same prefix pattern applies to the other Math helpers (min, max, floor,
+    ceil, round, abs, pow, sqrt) even when the native map also emits the short
+    SCAD name. The service file remains the fallback implementation.
+
+  </documentation>
+  <references>
+    <see type="rdoc:FileStructure" relation="ReadNext" />
+  </references>
+</rdoc:NativeMappings>

package/blocks/com/machineblocks/bml/target/render/documentation/Presets.bml

@@ -0,0 +1,50 @@
+<!--Render Target Documentation — Presets
+  FQN: com.machineblocks.bml.target.render.documentation.Presets-->
+<rdoc:Presets xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Preset blocks to OpenSCAD customizer JSON
+  </is>
+  <documentation>
+    A preset block (for example com.machineblocks.bml.bricks.StandardPresets
+    with a _presets composition) may be rendered to an OpenSCAD customizer JSON
+    file. The compiler merges appliedPresets chains before serialization.
+
+    The JSON uses the preset name as the key (the label shown in the OpenSCAD UI):
+
+        {
+          "fileFormatVersion": "1",
+          "parameterSets": {
+            "Brick 2x4": {
+              "size": "[2, 4, 3]",
+              "baseColor": "#EAC645",
+              "studs": "true"
+            },
+            "Brick 1x1": {
+              "size": "[1, 1, 3]",
+              "baseColor": "#EAC645"
+            }
+          }
+        }
+
+    All parameter values are strings (OpenSCAD customizer requirement). Emit
+    only properties whose preset value differs from the block default. Omitted
+    properties fall back to those defaults when OpenSCAD loads the parameter
+    set.
+
+    A block whose only composition is presets is rendered to the manifestation
+    path with a .json suffix instead of a .scad file. basePresets chains are
+    merged left to right, then the instance's own values overlay them. The
+    parameter set key is the instance name. A basePresets cycle returns
+    files: [] and diagnostic BML_PRESET_CYCLE.
+
+  </documentation>
+  <references>
+    <see type="rdoc:SourceMaps" relation="ReadNext" />
+  </references>
+</rdoc:Presets>

package/blocks/com/machineblocks/bml/target/render/documentation/PropertyRenderer.bml

@@ -0,0 +1,50 @@
+<!--Render Target Documentation — PropertyRenderer
+  FQN: com.machineblocks.bml.target.render.documentation.PropertyRenderer-->
+<rdoc:PropertyRenderer xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    MBOM properties to settings entries
+  </is>
+  <documentation>
+    The property renderer fills a SettingsBundle. V1 emission is a pseudo-map
+    pair ["paramName", value] per entry.
+
+    Native parameter inventory and scad:value defaults come from NativeBlock.bml
+    in @machineblocks/core. There is no hardcoded parameter list in this
+    package. The old 09_mbom_properties.yml file is a pointer stub only.
+
+    Each property definition supplies:
+
+    - name — MBOM property name, camelCase
+    - scadName — SCAD parameter name, camelCase, usually identical
+    - type — MBOM type FQN
+    - serializer — rule from SerializationRules
+    - default — default value
+
+    V1 reads property values from memberValues and definition defaults, not via
+    accessor capabilities.
+
+    Native properties (those declared on the NativeBlock set) map to dedicated
+    getters in the generated module body:
+
+        size      = mb_param_size(config, settings, [1, 8, 9]);
+        baseColor = mb_param_baseColor(config, settings);
+
+    Custom properties map to the generic getter:
+
+        wallThickness  = mb_param(config, settings, "wallThickness", 1);
+        cornerRounding = mb_param(config, settings, "cornerRounding", 0.5);
+
+    Native versus custom is decided from the domain TypeRegistry (the
+    NativeBlock property set), not from a list in this package.
+
+  </documentation>
+  <references>
+    <see type="rdoc:ExpressionRenderer" relation="ReadNext" />
+  </references>
+</rdoc:PropertyRenderer>

package/blocks/com/machineblocks/bml/target/render/documentation/RendererPipeline.bml

@@ -0,0 +1,51 @@
+<!--Render Target Documentation — RendererPipeline
+  FQN: com.machineblocks.bml.target.render.documentation.RendererPipeline-->
+<rdoc:RendererPipeline xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Internal pipeline of each block renderer
+  </is>
+  <documentation>
+    These steps belong to this target. They are not a framework-wide pipeline.
+    Numbers 9-11 below match the historical SCAD reference notes in the compiler
+    handbook; the rest are internal to the processors.
+
+    MBOM Block
+      Module Name Resolver — FQN to SCAD module name
+      Import Resolver — FQN to use/include paths
+      Property Renderer — MBOM properties to settings entries
+      Expression Renderer — expression AST to SCAD expressions
+      Assembly Pattern Mapper — semantic values to SCAD assembly calls
+      Composition Renderer — compositions to nested mb_block() calls
+        (ScadBlockProcessor only)
+      Set Renderer — set to STEPS array plus view submodules
+        (ScadSetProcessor only)
+      Customizer Generator — properties to the OpenSCAD customizer section
+      Source Map Generator — BML positions to SCAD positions (Source Map V3)
+      ScadFile(s)
+
+    Before dispatch, on a working copy (canonical BOM unchanged):
+
+    9. Target Resolver — look up machineblocks-v3-scad. If the target cannot
+       support a block baseType, emit a diagnostic for that block.
+    10. expandDirectives() plus id resolution — expand bml:each, bml:if, and
+        bml:with on the composition tree. Then evaluate id expressions, assign
+        deterministic auto-ids to static unreferenced children that still lack
+        an id, and compose nested paths (parentPartId::childPartId) for output.
+        Auto-ids are not written back to the BomDocument.
+    11. Block renderer dispatch — exact FQN, then baseType chain, then delegates.
+
+    Renderers may call framework validation utilities during the pipeline.
+    They choose Urmodell, a pragmatic fork, or further forks. They do not mutate
+    the canonical document.
+
+  </documentation>
+  <references>
+    <see type="rdoc:FqnNaming" relation="ReadNext" />
+  </references>
+</rdoc:RendererPipeline>

package/blocks/com/machineblocks/bml/target/render/documentation/SerializationRules.bml

@@ -0,0 +1,84 @@
+<!--Render Target Documentation — SerializationRules
+  FQN: com.machineblocks.bml.target.render.documentation.SerializationRules-->
+<rdoc:SerializationRules xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    How MBOM values become SCAD settings expressions
+  </is>
+  <documentation>
+    Type shapes live on com.machineblocks.bml.type.* and native parameters on
+    NativeBlock.bml. This block is only the emit strategy (transferred from the
+    former types handbook, section 6).
+
+    Strategy:
+
+    1. Read the BOM member value in authored form.
+    2. Consult type metadata (field order, serialize capability, NativeBlock
+       scad:value).
+    3. Translate at render time.
+    4. Choose the shortest valid SCAD expression.
+    5. Add scadName to expression text on the SettingsBundle.
+    6. The SettingsEmitter writes the bundle (V1 pseudo-map pair, future object).
+
+    Default struct to SCAD array: element order is the type's property
+    declaration order — the same ordinal as BML positional array literals.
+    Do not invent a separate SCAD index convention.
+
+        FaceMapXY properties xNeg, xPos, yNeg, yPos
+        MBOM { xNeg: 1, xPos: 1, yNeg: 0, yPos: 0 }
+        SCAD [1, 1, 0, 0]
+
+    Exceptions must be defined on the type, the property, or an annotation
+    facet. Never implied:
+
+    - Compact forms (PerSide4 scalar or 2-element when faces are paired)
+    - Enum / catalog literals via scad:value
+    - A custom serialize capability on the type or property
+
+    Examples (settings entry shown as the V1 pair):
+
+    SizeXYZ { x:4, y:2, z:3 } -> ["size", [4, 2, 3]]
+
+    AxisXYZ holeXYZDiameter
+    - all auto -> ["holeXYZDiameter", "auto"]
+    - { x:3, y:3, z:4 } -> ["holeXYZDiameter", [3, 4]]
+    - { x:3, y:3.2, z:4 } -> ["holeXYZDiameter", [3, 3.2, 4]]
+
+    PerSide4 recessWallThickness
+    - all 0.333 -> ["recessWallThickness", 0.333]
+    - x faces 0.5, y faces 0.25 -> ["recessWallThickness", [0.5, 0.25]]
+    - 0.5, 0.4, 0.25, 0.2 -> ["recessWallThickness", [0.5, 0.4, 0.25, 0.2]]
+
+    FaceVector6 sizeMod
+    - { "x-":0, "x+":0.5, others 0 } -> ["sizeMod", [0, 0.5, 0, 0, 0, 0]]
+
+    FaceMap baseAdjustment
+    - { "x-": -0.1, "x+": -0.1, "z+": 0.05 }
+      -> ["baseAdjustment", [["x-", -0.1], ["x+", -0.1], ["z+", 0.05]]]
+    - namespaced keys pass through: "pbx.x+", "pty.z+"
+
+    SelectiveGrid studs
+    - studs true stays ["studs", true]
+    - studAreas become [["studAreas", [[[0,0],[1,1], false], [[2,0],[3,1], "hollow"]]]]
+
+    WallGapList recessWallGaps
+    - [{ face:"x+", position:0, length:"full" }, { face:"y-", position:2, length:3 }]
+      -> ["recessWallGaps", [["x+"], ["y-", 2, 3]]]
+
+    Direction.West -> ["direction", "west"]
+
+    Color { hex: "#EAC645" } -> ["baseColor", "#EAC645"]
+
+    Expressions stay ExpressionValue { raw } on the BOM. The renderer serializes
+    the parsed AST or a statically resolved value. See ExpressionRenderer.
+
+  </documentation>
+  <references>
+    <see type="rdoc:DomainBoundary" relation="ReadNext" />
+  </references>
+</rdoc:SerializationRules>

package/blocks/com/machineblocks/bml/target/render/documentation/SetRendering.bml

@@ -0,0 +1,77 @@
+<!--Render Target Documentation — SetRendering
+  FQN: com.machineblocks.bml.target.render.documentation.SetRendering-->
+<rdoc:SetRendering xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Set processor: STEPS, bounding box, and view submodules
+  </is>
+  <documentation>
+    A block whose baseType chain includes com.machineblocks.bml.core.Set is
+    rendered by ScadSetProcessor as a SCAD file with a STEPS array and four
+    view submodules.
+
+    A MachineBlocks set uses three aggregations. _presets and _parts are
+    inherited. _steps is declared on Set.
+
+    - _presets — palette; configurations referenced by appliedPresets on _parts
+    - _parts — placed instances (direction, offset, appliedPresets; id becomes
+      the SCAD instance id)
+    - _steps — assembly order; optional; default is _parts document order
+
+    STEPS is generated from the placement list. Each entry:
+
+        [instanceId, boundingBox, direction, offset]
+
+    - [0] instanceId — string from the placed instance id
+    - [1] boundingBox — [x, y, z] from merged preset/configuration size
+    - [2] direction — "west" | "north" | "east" | "south"
+    - [3] offset — [x, y, z]
+
+    Example:
+
+        STEPS = [
+            ["00001", [16, 16, 1], "west", [0, 0, 0]],
+            ["00002", [4, 4, 9], "west", [0, 0, 1]]
+        ];
+
+    The set bounding box is computed at SCAD render time, not by the compiler:
+
+        ["size", mb_set_bounding_box(STEPS)]
+
+    Four submodules, PascalCase suffixes of the set module:
+
+        ...DefaultEnclosure__Total
+        ...DefaultEnclosure__Print
+        ...DefaultEnclosure__Step
+        ...DefaultEnclosure__Instance
+
+    The Instance submodule dispatches with if / else if on instanceId to
+    per-instance modules named with the id appended by underscore
+    (...__Instance_00001). Each of those modules calls the manifestation
+    module of the placed part's type FQN.
+
+    Total and Print call every instance module in STEPS order. Step calls the
+    prefix of that list whose index is less than or equal to the customizer
+    variable step. When _steps is absent, STEPS follows _parts document order.
+    A missing direction defaults to "west". A missing offset defaults to
+    [0, 0, 0]. A missing id or size returns files: [] and diagnostic
+    BML_SET_PART_INCOMPLETE.
+
+    Set customizer variables:
+
+        mode       = "total"; // [total:Total, print:3D Print, step:Step, instance:Instance]
+        step       = 0;       // [0:9]
+        instanceId = "00001";
+        assembly   = "merged"; // [unassembled:Unassembled, assembled:Assembled, merged:Merged]
+        baseColor  = "#EAC645";
+
+  </documentation>
+  <references>
+    <see type="rdoc:Customizer" relation="ReadNext" />
+  </references>
+</rdoc:SetRendering>

package/blocks/com/machineblocks/bml/target/render/documentation/SettingsFormat.bml

@@ -0,0 +1,80 @@
+<!--Render Target Documentation — SettingsFormat
+  FQN: com.machineblocks.bml.target.render.documentation.SettingsFormat-->
+<rdoc:SettingsFormat xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    SettingsBundle plus emitter, pseudo-map in V1
+  </is>
+  <documentation>
+    The V3 library passes instance parameters via a settings argument on
+    mb_block and reads them with mb_param(config, settings, key, default) and
+    mb_param_size (and the other mb_param_* getters). The renderer supports two
+    emission formats. Only one is active at runtime.
+
+    V1 — pseudo-map (the only format the current library understands):
+
+        mb_block(
+            config = mb_config,
+            settings = [
+                ["size", size],
+                ["brick1SizeY", brick1SizeY]
+            ]
+        );
+
+    Future — OpenSCAD native object() when that type is stable:
+
+        settings = object(
+            size = size,
+            brick1SizeY = brick1SizeY
+        )
+
+    Nested composition settings would become nested objects. Today's equivalent
+    is separate mb_block() calls with a flat settings list per call, not nested
+    pair arrays.
+
+    Two layers, so composition logic never hardcodes pseudo-map syntax:
+
+    1. Resolve properties to a SettingsBundle (renderer-neutral).
+       Map of scadName to SCAD expression text.
+       Built from PropertyResolver: inline, then preset, then config, then default.
+    2. SettingsEmitter turns the bundle into the settings argument expression.
+       PseudoMapSettingsEmitter is the V1 default.
+       ObjectSettingsEmitter is future.
+
+        interface SettingsBundle {
+          entries: ReadonlyMap of string to string
+        }
+        interface SettingsEmitter {
+          emit(bundle: SettingsBundle): string
+        }
+
+    Rules:
+
+    - Property resolution is format-agnostic. The same bundle feeds both emitters.
+    - Only the emitter changes when the format changes.
+    - The composition renderer calls emitter.emit(childBundle) per mb_block().
+    - Nested mb_block() trees stay structurally identical.
+    - The switch is target-level config, not per property.
+
+        interface ScadRenderOptions {
+          settingsFormat?: "pseudo-map" | "object"
+        }
+
+    Wired from CompileOptions / targetOptions.machineblocks-v3-scad.
+    V1 rejects object with diagnostic BML_SETTINGS_FORMAT_UNSUPPORTED and
+    writes no file while the SCAD library cannot read it.
+
+    Migration when object() is stable: the SCAD library gains object-aware
+    getters; ObjectSettingsEmitter lands in this package; settingsFormat object
+    is opt-in, then default; PseudoMapSettingsEmitter stays for older OpenSCAD.
+
+  </documentation>
+  <references>
+    <see type="rdoc:PropertyRenderer" relation="ReadNext" />
+  </references>
+</rdoc:SettingsFormat>

package/blocks/com/machineblocks/bml/target/render/documentation/SourceMaps.bml

@@ -0,0 +1,33 @@
+<!--Render Target Documentation — SourceMaps
+  FQN: com.machineblocks.bml.target.render.documentation.SourceMaps-->
+<rdoc:SourceMaps xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Source Map V3 beside each SCAD file
+  </is>
+  <documentation>
+    The renderer writes a Source Map V3 file next to each SCAD output:
+
+        Wall.scad
+        Wall.scad.map
+
+    The map records BML source file, line, and column for every generated SCAD
+    line, so diagnostics can point at the BML position rather than the generated
+    SCAD.
+
+    Source Map V3 is the language-agnostic format (version 3, sources, mappings).
+    Each generated SCAD line is one mappings group. This implementation points
+    every line at the block definition's BML position. The map is the optional
+    sourceMap field on the RenderOutput file. The host writes Wall.scad.map
+    when that field is present.
+
+  </documentation>
+  <references>
+    <see type="rdoc:HelperFunctions" relation="ReadNext" />
+  </references>
+</rdoc:SourceMaps>

package/blocks/com/machineblocks/bml/target/render/documentation/TargetRegistration.bml

@@ -0,0 +1,61 @@
+<!--Render Target Documentation — TargetRegistration
+  FQN: com.machineblocks.bml.target.render.documentation.TargetRegistration-->
+<rdoc:TargetRegistration xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Registry name and how a host constructs the target
+  </is>
+  <documentation>
+    Registry / CLI target name: machineblocks-v3-scad
+    npm package: @machineblocks/render-target
+    TypeScript class (when implemented): MachineBlocksRenderTarget
+
+    Host wiring:
+
+        import { registerTarget } from "@blockml/compiler";
+        import { BlockRenderEngine } from "@blockml/block-render-engine";
+        import { MachineBlocksRenderTarget } from "@machineblocks/render-target";
+
+        registerTarget(new MachineBlocksRenderTarget(new BlockRenderEngine()));
+
+    Shape:
+
+        class MachineBlocksRenderTarget implements RenderTarget {
+          name = "machineblocks-v3-scad"
+          engine = new BlockRenderEngine()
+          processors = [
+            new ScadSetProcessor(),
+            new ScadBlockProcessor()
+          ]
+          delegates = []
+        }
+
+    Both V1 processors use the engine compile strategy.
+    delegates stays empty. Other domain targets may list this target as a
+    delegate and ship no processors of their own.
+
+    @blockml/cli does not register this name. @machineblocks/cli does.
+    Tests and browser callers call registerTarget directly.
+
+    Stage-3 RenderTarget also carries accepts scopes
+    (document, library, corpus, auto) and render(request, ctx). This product
+    target is a document target: one BML file in, one or more SCAD files out.
+    The host requires a file argument unless --all loops srcDir.
+
+    render finds the BomDocument whose source.filePath equals the session
+    sourceFilePath. No match returns files: [] and diagnostic
+    BML_RENDER_DOCUMENT_NOT_FOUND.
+
+    targetOptions.machineblocks-v3-scad carries mbLibPath and settingsFormat
+    (pseudo-map or object).
+
+  </documentation>
+  <references>
+    <see type="rdoc:RendererPipeline" relation="ReadNext" />
+  </references>
+</rdoc:TargetRegistration>

package/blocks/com/machineblocks/bml/target/render/documentation/V1Scope.bml

@@ -0,0 +1,44 @@
+<!--Render Target Documentation — V1Scope
+  FQN: com.machineblocks.bml.target.render.documentation.V1Scope-->
+<rdoc:V1Scope xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    V1 base types handled by this target
+  </is>
+  <documentation>
+    V1 supports exactly two base types:
+
+    - com.machineblocks.bml.core.Block — ScadBlockProcessor
+      Standard SCAD block module.
+    - com.machineblocks.bml.core.Set — ScadSetProcessor
+      STEPS-based set with view submodules.
+
+    User types that inherit either base type use the same processor.
+    ScadSetProcessor is registered first because it is more specific.
+    ScadBlockProcessor is the fallback for Block.
+
+    A block whose baseType chain does not include
+    com.machineblocks.bml.core.Block is not supported. The compiler emits
+    BML_NO_TARGET for that block.
+
+    isSubtypeOf walks the baseType chain in the BOM type registry.
+
+    Later processors (copy of built-in service files, capability implementation
+    transpilation) may be added. They are not required for V1 block and set emit.
+    The engine allows them to use a different strategy in the same target.
+
+    ScadBlockProcessor emits a leaf, a composite module, or a preset JSON file.
+    ScadSetProcessor emits a SCAD file with a STEPS array and four view
+    submodules. A composition that carries bml:each, bml:if, or bml:with
+    returns files: [] and diagnostic BML_DIRECTIVE_DEFERRED.
+
+  </documentation>
+  <references>
+    <see type="rdoc:TargetRegistration" relation="ReadNext" />
+  </references>
+</rdoc:V1Scope>

package/dist/composite.d.ts

@@ -0,0 +1,8 @@
+import type { BlockDefinition } from "@blockml/bom";
+import type { RenderContext, RenderOutput } from "@blockml/compiler";
+import { type ManifestationMapping } from "./naming.js";
+type Registry = RenderContext["session"]["typeRegistry"];
+export declare function renderCompositeFile(block: BlockDefinition, outputRelativePath: string, outputBasePath: string, mbLibPath: string, registry: Registry, mapping: ManifestationMapping): RenderOutput;
+export declare function nativePropertyNames(registry: Registry): Set<string>;
+export {};
+//# sourceMappingURL=composite.d.ts.map

package/dist/composite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../src/composite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAqC,MAAM,cAAc,CAAC;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAIrE,OAAO,EAAgD,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAKtG,KAAK,QAAQ,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC,cAAc,CAAC,CAAC;AAOzD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,EACtB,kBAAkB,EAAE,MAAM,EAC1B,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,oBAAoB,GAC5B,YAAY,CAiGd;AAsID,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,CAQnE"}