@machineblocks/render-target 0.0.0-stage → 0.1.0

package/blocks/com/machineblocks/bml/target/render/Library.bml

@@ -0,0 +1,55 @@
+<!--MachineBlocks Render Target Library
+  FQN: com.machineblocks.bml.target.render.Library-->
+<render:Library xmlns="http://blockml.org/bml"
+  xmlns:blockml="org.blockml.bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:mb="com.machineblocks.bml"
+  xmlns:engine="org.blockml.bml.engine.blockrender"
+  xmlns:render="com.machineblocks.bml.target.render">
+
+  <baseType>
+    core:BlockLibrary
+  </baseType>
+  <is>
+    The MachineBlocks SCAD render target library catalog
+  </is>
+  <version>
+    0.1.0
+  </version>
+  <documentation>
+    Publishable compiler-target library (com.machineblocks.bml.target.render.Library).
+    Registry name machineblocks-v3-scad. npm package @machineblocks/render-target.
+    Serializes MBOM blocks into MachineBlocks V3 OpenSCAD compatible with
+    @machineblocks/core.
+
+    Formerly @machineblocks/machineblocks-v3-scad-target. Registry name unchanged.
+    Engine dependency is @blockml/block-render-engine (formerly MakerEngine).
+
+    Membership is the file tree under this Library.bml.
+  </documentation>
+  <references>
+    <see type="render:README" relation="ReadFirst" />
+  </references>
+  <language>
+    <blockml:language.English />
+  </language>
+  <properties>
+    <description override="true">
+      <value>MachineBlocks BML to SCAD render target</value>
+    </description>
+  </properties>
+  <aggregations>
+    <readMe override="true">
+      <composition>
+        <render:README />
+      </composition>
+    </readMe>
+    <dependencies override="true">
+      <composition>
+        <blockml:Library />
+        <mb:Library />
+        <engine:Library />
+      </composition>
+    </dependencies>
+  </aggregations>
+</render:Library>

package/blocks/com/machineblocks/bml/target/render/README.bml

@@ -0,0 +1,37 @@
+<!--MachineBlocks Render Target — README
+  FQN: com.machineblocks.bml.target.render.README-->
+<render:README xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:render="com.machineblocks.bml.target.render"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation"
+  xmlns:scad="com.machineblocks.bml.documentation.scad">
+
+  <baseType>
+    core:ReadMe
+  </baseType>
+  <is>
+    Reading entry for the MachineBlocks SCAD render target library
+  </is>
+  <documentation>
+    @machineblocks/render-target compiles MachineBlocks BML to .scad files the
+    V3 library in @machineblocks/core can render. Registry name:
+    machineblocks-v3-scad.
+
+    This library is the SSOT for target registration, the two V1 processors,
+    FQN-to-module naming, imports, settings emission, assembly patterns, sets,
+    the customizer, source maps, and MBOM-to-SCAD serialization. Type shapes and
+    the mb_block runtime stay in @machineblocks/core.
+
+    The target calls @blockml/block-render-engine (compile strategy for both
+    V1 processors). It is browser and Node compatible.
+
+    Start at com.machineblocks.bml.target.render.documentation.Introduction.
+    For the runtime API, also read
+    com.machineblocks.bml.documentation.scad.ScadRenderTarget in @machineblocks/core.
+  </documentation>
+  <references>
+    <see type="rdoc:Introduction" relation="ReadFirst" />
+    <see type="scad:ScadRenderTarget" relation="SeeAlso" />
+    <see type="rdoc:V1Scope" relation="SeeAlso" />
+  </references>
+</render:README>

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

@@ -0,0 +1,47 @@
+<!--Render Target Documentation — AssemblyPatterns
+  FQN: com.machineblocks.bml.target.render.documentation.AssemblyPatterns-->
+<rdoc:AssemblyPatterns xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Semantic MBOM values to SCAD assembly helper calls
+  </is>
+  <documentation>
+    Assembly patterns exist in SCAD and have no BML equivalent. The renderer
+    inserts them from the semantic MBOM value and the composition structure.
+    The mapping table is declarative and configurable, not hardcoded in
+    processor control flow.
+
+    MBOM semantic value to SCAD output:
+
+    - baseCutoutType = "groove" on a top part
+      -> mb_assembly_groove(assembly, renderGroups, group_top)
+    - tongue = true on a bottom part
+      -> mb_assembly_tongue(assembly, renderGroups, group_bottom)
+    - offset on an assembly-dependent part
+      -> mb_assembly_offset([x, y, z], assembly, renderGroups, group_top)
+    - render per part
+      -> mb_group_render(renderGroups, group_bottom)
+    - id per part
+      -> mb_block_id(blockId, part_bottom)
+    - baseAdjustment, namespace-filtered
+      -> mb_params_filter(baseAdjustment, ns_bottom)
+
+    For each composition child the renderer emits part variables inside the
+    wrapper children block:
+
+        part_bottom  = "bottom";
+        group_bottom = part_bottom;
+        ns_bottom    = part_bottom;
+
+    The part name is the composition child id.
+
+  </documentation>
+  <references>
+    <see type="rdoc:LeafOptimization" relation="ReadNext" />
+  </references>
+</rdoc:AssemblyPatterns>

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

@@ -0,0 +1,60 @@
+<!--Render Target Documentation — CompositeRendering
+  FQN: com.machineblocks.bml.target.render.documentation.CompositeRendering-->
+<rdoc:CompositeRendering xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Wrapper mb_block and nested children
+  </is>
+  <documentation>
+    A composite block (non-empty composition) is a wrapper mb_block() with
+    nested child calls, inside a typed module named by FqnNaming.
+
+    Module body order:
+
+    1. Native parameters via mb_param_* getters.
+    2. Custom parameters via mb_param.
+    3. assembly = mb_assembly(config, settings, size, direction)
+       and renderGroups = mb_param_renderGroups(config, settings).
+    4. Wrapper mb_block with id, base false, studs false, size, align, offset,
+       direction.
+    5. One child region per composition child: part_/group_/ns_ locals, then
+       mb_block with id mb_block_id(...), render mb_group_render(...), size
+       expression, and assembly helpers from AssemblyPatterns.
+
+    Wrapper decision:
+
+    - 0 children and custom processor logic — that logic renders; no wrapper.
+    - 0 children and no custom processor — diagnostic MB_EMPTY_BLOCK.
+    - exactly 1 child — no wrapper; the child is rendered directly.
+    - 2 or more children — automatic wrapper. Children render inside it.
+
+    The wrapper always sets base false and studs false, ignoring the block's
+    own base and studs. The wrapper is a layout container. Geometry is the
+    children. The block's base and studs are passed to the NativeBlock children.
+
+        Cross.studs = true
+          wrapper: studs false (processor)
+          children: studs true (block property)
+
+    Composite blocks do not need to declare base false or studs false for the
+    wrapper. Those properties keep their meaning for the children.
+
+    The automatic wrapper is only the outermost container, once per processor
+    invocation. Nested blocks in the composition are real instances, not extra
+    wrappers.
+
+    Illustrative child settings (top part) include offset via
+    mb_assembly_offset and baseCutoutType via mb_assembly_groove. Bottom parts
+    include tongue via mb_assembly_tongue. Both forward baseAdjustment through
+    mb_params_filter with that part's namespace.
+
+  </documentation>
+  <references>
+    <see type="rdoc:SetRendering" relation="ReadNext" />
+  </references>
+</rdoc:CompositeRendering>

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

@@ -0,0 +1,62 @@
+<!--Render Target Documentation — Customizer
+  FQN: com.machineblocks.bml.target.render.documentation.Customizer-->
+<rdoc:Customizer xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    OpenSCAD customizer section
+  </is>
+  <documentation>
+    The customizer generator writes the OpenSCAD customizer section for block
+    and set files.
+
+    For each exposed property:
+
+    - Variable declaration with default value
+    - Inline comment with customizer dropdown syntax where it applies
+    - Group comment /* [Group Name] */ for property groups
+
+    The hidden section /* [Hidden] */ holds derived variables that combine
+    customizer inputs before they are passed to the module. Internal module
+    computations are never placed in the hidden section.
+
+    OpenSCAD customizer supports only flat primitives. The processor splits
+    complex properties into several customizer variables and recombines them in
+    [Hidden]. Splitting follows NativeBlock type metadata and annotations.
+
+    split [x, y, z] — a vector becomes named scalars:
+
+        baseRoundingRadiusX = 0.5; // [0:0.1:2]
+        baseRoundingRadiusY = 0.5;
+        baseRoundingRadiusZ = 0.5;
+        /* [Hidden] */
+        baseRoundingRadius = [baseRoundingRadiusX, baseRoundingRadiusY, baseRoundingRadiusZ];
+
+    auto_toggle true — a NoneOr value becomes a boolean plus a value:
+
+        recessDepthAuto = true;
+        recessDepth = 0.5;
+        /* [Hidden] */
+        recessDepthResolved = recessDepthAuto ? "auto" : recessDepth;
+
+    suggestions — a dropdown comment from the property suggestions. Each
+    suggestion instance is serialized to its SCAD literal:
+
+        textColor = "#303D4E"; // [#303D4E, #EAC645, #58B99D]
+
+    Optional labels may come from documentation on the suggestion instances.
+
+    constraints — Min and Max map to customizer range metadata
+    [min:step:max] when both bounds exist. See the BlockML constraints
+    documentation for the constraint instances. Individual constraints may also
+    inform editor range hints.
+
+  </documentation>
+  <references>
+    <see type="rdoc:Presets" relation="ReadNext" />
+  </references>
+</rdoc:Customizer>

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

@@ -0,0 +1,43 @@
+<!--Render Target Documentation — DomainBoundary
+  FQN: com.machineblocks.bml.target.render.documentation.DomainBoundary-->
+<rdoc:DomainBoundary xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    What this target reads from @machineblocks/core
+  </is>
+  <documentation>
+    This package depends on @machineblocks/core and does not copy its blocks.
+
+    Read there:
+
+    - com.machineblocks.bml.documentation.scad.ScadRenderTarget — orientation
+    - com.machineblocks.bml.documentation.scad.MbBlockApi — mb_block signature
+    - com.machineblocks.bml.documentation.scad.BlockFileStructure — file sections
+      as the library presents them
+    - com.machineblocks.bml.documentation.scad.TypesAndSerialization — short
+      serialization sketch; SerializationRules in this library is the compiler
+      emit contract when the two differ, and type BML wins for shapes
+    - com.machineblocks.bml.documentation.scad.ModulePatterns
+    - com.machineblocks.bml.documentation.scad.ScadDecisionRules
+    - com.machineblocks.bml.core.NativeBlock — parameter inventory
+    - com.machineblocks.bml.type.* — type shapes
+    - com.machineblocks.bml.examples.* — example BML
+    - blocks/com/machineblocks/scad/** — corresponding SCAD, including
+      examples/Cross.scad and examples/Connector.scad
+    - lib/block.scad and config/mb_config.scad — runtime imports
+
+    Do not move those files into this package. When an example .scad and this
+    target's emit rules diverge, the BML example plus this library are the
+    intended compiler output; hand-maintained SCAD may still show the older
+    wrapper style that LeafOptimization removes.
+
+  </documentation>
+  <references>
+    <see type="rdoc:Introduction" relation="SeeAlso" />
+  </references>
+</rdoc:DomainBoundary>

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

@@ -0,0 +1,58 @@
+<!--Render Target Documentation — ExpressionRenderer
+  FQN: com.machineblocks.bml.target.render.documentation.ExpressionRenderer-->
+<rdoc:ExpressionRenderer xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Expression values to SCAD expressions
+  </is>
+  <documentation>
+    Canonical BOM stores expressions as ExpressionValue { raw }. The expression
+    renderer obtains a typed AST via parseExpression() (a working-model utility,
+    not a canonical BOM field) and serializes it to SCAD.
+
+    Static: if the expression has no runtime-dependent roots, emit the resolved
+    value. ${ [1, 1, 1] } becomes [1, 1, 1].
+
+    Dynamic: if it references block properties or bml:with variables, emit a
+    SCAD expression. StructType members are addressed by name in BML. The
+    expression language rejects a numeric index on a StructType (size[0]).
+    A collection index (items[0]) stays an index.
+
+    When the property's SCAD form is a positional array, a named member becomes
+    the declaration-order index of that field. That is the default StructType
+    serialization and the V1 path. SizeXYZ declares x, y, z, so:
+
+        ${ [size.x, size.y, size.z - 1] }
+          -> [size[0], size[1], size[2] - 1]
+        ${ #math.max(size.z - 1, 0) }
+          -> max(size[2] - 1, 0)
+
+    When the property's SCAD form is an OpenSCAD object, the member stays
+    name.member. That form belongs to the future object() settings emitter.
+
+    Root mapping:
+
+    - myProperty -> SCAD local variable of that name
+    - myProperty.member on an array-form value -> name[declarationOrdinal]
+    - myProperty.member on an object-form value -> name.member
+    - items[i] on a collection -> items[i]
+    - withVariable -> SCAD local from the bml:with scope
+    - #math.min(a, b) / #math.max(a, b) -> min / max via the native map
+
+    V1 does not execute @bean calls or model bindings as SCAD. A TypeScript
+    implementation whose arguments are all literals is evaluated at compile
+    time and emitted as that literal. Any other @bean call is not emitted;
+    the diagnostic is BML_FUNCTION_NO_RUNTIME_IMPL. OpenSCAD capability
+    implementations (FQN-prefixed functions) are a later processor and are
+    not required for V1 block and set emit.
+
+  </documentation>
+  <references>
+    <see type="rdoc:AssemblyPatterns" relation="ReadNext" />
+  </references>
+</rdoc:ExpressionRenderer>

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

@@ -0,0 +1,42 @@
+<!--Render Target Documentation — FileStructure
+  FQN: com.machineblocks.bml.target.render.documentation.FileStructure-->
+<rdoc:FileStructure xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Required section order of a generated SCAD block file
+  </is>
+  <documentation>
+    Every generated SCAD file follows the MachineBlocks block file structure.
+    The header is mandatory. Section comments are mandatory even when the
+    section is empty.
+
+        /**
+         * MachineBlocks.com Block File
+         *
+         * Name: Wall
+         * Filename: Wall.scad
+         * Package: com.martianmicro.anyclosure.Wall
+         * Generated by: machineblocks-render-target (package version)
+         */
+
+        /* Imports */
+        /* Customization */
+        /* Main Module Call */
+        /* Main Module Definition */
+        /* Optional Sub Modules */
+        /* Optional Helper Modules */
+        /* Optional Global Functions */
+
+    The historical header said "Generated by: bom" plus a version token. New files say
+    machineblocks-render-target plus this package version.
+
+  </documentation>
+  <references>
+    <see type="rdoc:SettingsFormat" relation="ReadNext" />
+  </references>
+</rdoc:FileStructure>

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

@@ -0,0 +1,85 @@
+<!--Render Target Documentation — FqnNaming
+  FQN: com.machineblocks.bml.target.render.documentation.FqnNaming-->
+<rdoc:FqnNaming xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    FQN to SCAD module name and file path
+  </is>
+  <documentation>
+    Every MBOM block class is identified by its definition FQN. This target
+    maps that FQN to a manifestation FQN, then to a module name and a file path.
+    The mapping is a MachineBlocks convention, not a BlockML platform rule.
+    Other targets do not replace a bml segment and do not emit one file per block.
+
+    Automatic mapping applies when targetOptions omit sourcePackage and
+    targetPackage. Split the FQN on "." and replace the one segment whose text
+    is exactly bml with scad. The match is case-sensitive and segment-wide.
+    mybml and bmlmodels are not bml. The replacement is not a substring search
+    and does not prefer the first or last segment.
+
+        Definition FQN:    com.machineblocks.bml.examples.Cross
+        Manifestation FQN: com.machineblocks.scad.examples.Cross
+        SCAD module:       mb__com__machineblocks__scad__examples__Cross
+        Output file:       {srcDir}/com/machineblocks/scad/examples/Cross.scad
+
+    Zero bml segments: MB_TARGET_PACKAGE_UNDETERMINED. The message names the
+    source FQN and tells the caller to pass --target-package and, if needed,
+    --source-package. More than one bml segment: MB_TARGET_PACKAGE_AMBIGUOUS.
+    The message names the source FQN. Neither case writes a file.
+
+    Explicit mapping applies when both sourcePackage and targetPackage are set.
+    A definition FQN equal to the source package, or starting with that package
+    plus a dot, keeps the remainder and swaps the root:
+
+        sourcePackage com.example.models
+        targetPackage com.example.scad
+        com.example.models.bricks.MyBrick
+          -> com.example.scad.bricks.MyBrick
+
+    The bml-to-scad replacement is not applied on top. A selected block outside
+    the source package is MB_SOURCE_OUTSIDE_ROOT. A referenced FQN outside the
+    source package (an import or a child module) uses automatic mapping instead.
+    If that automatic mapping fails, the compile fails and the host writes nothing.
+
+    Preset JSON uses the same manifestation with extension .json.
+    The output root is the configured blocks directory (srcDir), not a guessed
+    dist, build, or scad directory.
+
+    Name rules:
+
+    - Segments separated by double underscore (__)
+    - Packages lowercase
+    - Class names PascalCase
+    - Subclasses: additional PascalCase segment
+    - Private helpers: __help__camelCase (not a block)
+    - Private functions: __func__camelCase (not a block)
+
+    Examples:
+
+        com.machineblocks.bml.bricks.Standard
+          -> mb__com__machineblocks__scad__bricks__Standard
+
+        subclass Bottom of a manifested Wall
+          -> mb__com__example__scad__Wall__Bottom
+
+        private helper
+          -> mb__com__example__scad__Wall__help__myHelper
+
+        private function
+          -> mb__com__example__scad__Wall__func__myFunc
+
+    The names help and func are reserved and cannot be subclass names.
+
+    Multiple block classes may share one SCAD file. The file is named after the
+    primary class. The output root is srcDir.
+
+  </documentation>
+  <references>
+    <see type="rdoc:Imports" relation="ReadNext" />
+  </references>
+</rdoc:FqnNaming>

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

@@ -0,0 +1,57 @@
+<!--Render Target Documentation — HelperFunctions
+  FQN: com.machineblocks.bml.target.render.documentation.HelperFunctions-->
+<rdoc:HelperFunctions xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Which values are computed in SCAD versus in the compiler
+  </is>
+  <documentation>
+    Some helpers run at SCAD render time instead of being precomputed.
+
+    Decided — SCAD runtime:
+    - mb_set_bounding_box(STEPS)
+    - mb_assembly(config, settings, size, direction)
+    - mb_assembly_tongue(assembly, renderGroups, group)
+    - mb_assembly_groove(assembly, renderGroups, group)
+    - mb_assembly_offset(offset, assembly, renderGroups, group)
+    - mb_group_render(renderGroups, group)
+    - mb_block_id(blockId, partId)
+    - mb_parts_total_size(parts)
+
+    The assembly helpers and mb_group_render read assembly mode or
+    renderGroups.
+
+    mb_block_id is str(blockId, "/", part). blockId comes from
+    mb_param_id(config, settings, fqn) and can be overridden from outside, so
+    the renderer emits the call. NativeBlock documents the part id as
+    "blockId/partName".
+
+    Decided — mb_params_filter(baseAdjustment, namespace, overrides?):
+    The parameter name is baseAdjustment. Core 3.0.0 renamed it from
+    baseSideAdjustment. When the map is the runtime parameter (config or
+    customizer), emit the call. When the map is a static literal, emit the
+    filtered pseudo-map. The optional third argument applies fixed overrides
+    after the namespace filter. Entries without a namespace and entries with
+    numeric keys are ignored.
+
+    mb_parts_total_size(parts) is the SCAD bounding box of the parts after
+    direction resolution. Each entry is [id, size, direction, offset], the
+    same layout as a STEPS row. id is required. size, direction, and offset
+    are indexes 1, 2, and 3. The renderer emits the call:
+
+        size = mb_parts_total_size(parts);
+
+    Rule: render-dependent values (assembly, renderGroups, overridable
+    blockId) resolve at SCAD runtime. Structural and static values are
+    precomputed in MBOM.
+
+  </documentation>
+  <references>
+    <see type="rdoc:SerializationRules" relation="ReadNext" />
+  </references>
+</rdoc:HelperFunctions>

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

@@ -0,0 +1,49 @@
+<!--Render Target Documentation — Imports
+  FQN: com.machineblocks.bml.target.render.documentation.Imports-->
+<rdoc:Imports xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    use and include paths emitted into each SCAD file
+  </is>
+  <documentation><![CDATA[
+    Every generated file imports the MachineBlocks V3 library and the project
+    config. Paths are relative to the output file, using mbLibPath from
+    targetOptions under the key machineblocks-v3-scad. The compiler
+    RenderSession has no mbLibPath field. When mbLibPath is absent this slice
+    returns files: [] and diagnostic BML_MB_LIB_PATH_MISSING.
+
+    Standard imports (angle brackets are SCAD include syntax):
+
+        use <{relative_path_to_scad_lib}/lib/block.scad>;
+        include <{relative_path_to_scad_lib}/config/mb_config.scad>;
+
+    Ordinary composite compositions render leaf instances as mb_block()
+    (NativeBlock). They do not use-import dependency block SCAD files.
+
+    Sets (com.machineblocks.bml.core.Set) reference typed block modules by the
+    placed part's type FQN. The set processor emits a use import for each
+    distinct type file, for example use <../wall/Wall.scad>, and each instance
+    module calls that type's manifestation module.
+
+    When expressions reference a #built-in call that is not a native SCAD
+    mapping, the processor adds a use import for that service file, and only
+    when the service is actually used:
+
+        use <{relative}/blocks/org/blockml/bml/service/Math.scad>;
+        use <{relative}/blocks/org/blockml/bml/service/Strings.scad>;
+
+    Service SCAD files live in @machineblocks/core at
+    blocks/org/blockml/bml/service/ (Math.scad, Strings.scad, Numbers.scad,
+    Lists.scad, Bools.scad). They are pre-rendered artifacts. BML service
+    definitions in @blockml/core are the SSOT. Import paths are always relative
+    to the output file directory.
+  ]]></documentation>
+  <references>
+    <see type="rdoc:NativeMappings" relation="ReadNext" />
+  </references>
+</rdoc:Imports>

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

@@ -0,0 +1,43 @@
+<!--Render Target Documentation — Introduction
+  FQN: com.machineblocks.bml.target.render.documentation.Introduction-->
+<rdoc:Introduction xmlns="http://blockml.org/bml"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:rdoc="com.machineblocks.bml.target.render.documentation">
+
+  <baseType>
+    core:Documentation
+  </baseType>
+  <is>
+    Purpose and place of the MachineBlocks SCAD render target
+  </is>
+  <documentation>
+    This target serializes MBOM blocks into MachineBlocks V3 SCAD files.
+    It is a product render target, separate from @machineblocks/core and from
+    the BlockML toolchain targets (blockdoc, xsd, fatblock).
+
+    @machineblocks/core holds the domain BML, documentation, the SCAD runtime
+    (lib/block.scad and related files), and example pairs such as
+    com.machineblocks.bml.examples.Cross with
+    blocks/com/machineblocks/scad/examples/Cross.scad. This package reads that
+    library; it does not vendor it.
+
+    Output is MachineBlocks World interpretation: SCAD mb_block() calls. That is
+    not a BlockML platform rule. Other targets may emit React, KiCad, or Python
+    with no block concept. Mapping used here:
+
+    - BML NativeBlock — mb_block() at the leaf (explicit 1:1)
+    - BML composition — nested mb_block() tree
+    - Domain types such as Wall — lowered to mb_block() settings
+    - BML Set — STEPS array plus view submodules
+
+    All MBOM-to-SCAD mappings are declarative. Processors do not hardcode
+    parameter inventories. Native parameters come from NativeBlock.bml.
+
+    The target is browser and Node compatible. No Node-only APIs.
+    Host entry for users is @machineblocks/cli.
+
+  </documentation>
+  <references>
+    <see type="rdoc:V1Scope" relation="ReadNext" />
+  </references>
+</rdoc:Introduction>