Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Expose retained Concept guides in display meshes

Yuechen Li945ae32ff2b6
diff --git a/Aetheris.Kernel.Firmament.Tests/ConceptDisplayProjectionTests.cs b/Aetheris.Kernel.Firmament.Tests/ConceptDisplayProjectionTests.cs
new file mode 100644
index 00000000..21e8005c
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/ConceptDisplayProjectionTests.cs
@@ -0,0 +1,50 @@
+using Aetheris.Kernel.Firmament.Assembly;
+using Aetheris.Kernel.Firmament.Visualization;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class ConceptDisplayProjectionTests
+{
+ [Fact]
+ public void RealPartRetainsExactConceptGuidesWithoutAddingMaterial()
+ {
+ var path = FirmamentCorpusHarness.ResolveFixtureFullPath("fixtures/Regression/Visualization/concept-structs.firmament");
+ var source = File.ReadAllText(path);
+ var compiled = FirmamentBuildAndExport.CompileSource(source);
+ Assert.True(compiled.IsSuccess, string.Join("\n", compiled.Diagnostics.Select(d => d.Message)));
+ var before = compiled.Value.StepText;
+ var wires = ConceptDisplayProjection.Project(compiled.Value);
+ var bounds = wires.Where(w => w.Kind == "Box3").ToArray();
+ Assert.Equal(12, bounds.Length);
+ var corners = bounds.SelectMany(w => w.Points.Chunk(3)).DistinctBy(p => (p[0], p[1], p[2])).ToArray();
+ Assert.Equal(8, corners.Length);
+ Assert.Equal(80, corners.Max(p => p[0]) - corners.Min(p => p[0]));
+ Assert.Equal(50, corners.Max(p => p[1]) - corners.Min(p => p[1]));
+ Assert.Equal(25, corners.Max(p => p[2]) - corners.Min(p => p[2]));
+ Assert.Contains(wires, w => w.Kind == "Plane");
+ Assert.Contains(wires, w => w.Kind == "Axis");
+ Assert.Contains(wires, w => w.Kind == "Point");
+ Assert.All(wires, w => { Assert.NotEmpty(w.Provenance); Assert.All(w.Points, n => Assert.True(double.IsFinite(n))); });
+ Assert.Equal(before, compiled.Value.StepText);
+ Assert.Equal(before, FirmamentBuildAndExport.CompileSource(source).Value.StepText);
+ }
+
+ [Fact]
+ public void AssemblyPacketsRetainPrivateConceptsAndOccurrenceFrames()
+ {
+ var fixture = FirmamentCorpusHarness.ResolveFixtureFullPath("fixtures/Canonical/Assembly/annular-pair.firmament");
+ var source = File.ReadAllText(fixture).Replace("Template < R: Length > Struct Sleeve {", """
+ Template < R: Length > Struct Sleeve {
+ Concept Struct Design { Bounds: Box3 { size: [40mm, 40mm, 20mm] } }
+ """, StringComparison.Ordinal);
+ var compilation = new AssemblyM1Pipeline().Compile(source, fixture);
+ Assert.True(compilation.IsSuccess, string.Join("\n", compilation.Diagnostics.Select(d => d.Message)));
+ var mesh = AssemblyDisplayMeshExporter.Export(compilation);
+ var retained = Assert.Single(compilation.Geometry!.DefinitionConcepts).Value;
+ Assert.NotEmpty(retained);
+ Assert.Equal(12, Assert.Single(mesh.Definitions).Concepts.Count(w => w.Kind == "Box3"));
+ Assert.Equal(60, mesh.Occurrences.Single(o => o.Path == "AnnularPair.Second").Transform[12]);
+ Assert.Equal(2, mesh.Occurrences.Count(o => o.DefinitionId == mesh.Definitions[0].Id));
+ Assert.Equal(2, compilation.Geometry!.Artifact.Instances.Count);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Assembly/AssemblyDisplayMeshExporter.cs b/Aetheris.Kernel.Firmament/Assembly/AssemblyDisplayMeshExporter.cs
index d87d90a1..0156d12d 100644
--- a/Aetheris.Kernel.Firmament/Assembly/AssemblyDisplayMeshExporter.cs
+++ b/Aetheris.Kernel.Firmament/Assembly/AssemblyDisplayMeshExporter.cs
@@ -10,6 +10,7 @@ public sealed record DisplayProjectionEdge(string EdgeId, double[][] Points, boo
public sealed record AssemblyDisplayMeshDefinition(string Id, string Identity, double[] Positions, double[] Normals, int[] Indices,
string MeshPipeline = "LegacyTessellator", IReadOnlyList<AssemblyDisplayMeshRange>? Ranges = null)
{
+ public IReadOnlyList<Visualization.ConceptDisplayWire> Concepts { get; init; } = [];
public FirmamentCirRetention? Cir { get; init; }
public string? GeometryRevision { get; init; }
public CirShaderBinding? Shader { get; init; }
@@ -21,6 +22,7 @@ public sealed record AssemblyDisplayMeshDefinition(string Id, string Identity, d
public sealed record AssemblyDisplayMeshOccurrence(string Id, string Path, string? ParentId, string? DefinitionId, double[] Transform,
string? SemanticEntityId = null)
{
+ public IReadOnlyList<Visualization.ConceptDisplayWire> Concepts { get; init; } = [];
public ResolvedDisplayMaterial? Material { get; init; }
public string? Kind { get; init; }
}
@@ -78,7 +80,8 @@ public static class AssemblyDisplayMeshExporter
var artifact = geometry.Artifact.Definitions.Single(d => d.DefinitionIdentity == identity);
var externalStep = artifact.Provenance.Any(p => p.Stage == "imported-step-definition");
definitions.Add(definition(() => PrepareDefinition(ids[identity], identity, body, options, externalStep) with
- { Cir = geometry.DefinitionCir.GetValueOrDefault(identity), Shader = CirShaderArtifactProvider.Resolve(geometry.DefinitionCir.GetValueOrDefault(identity)), GeometryRevision = artifact.StepSha256 }, identity));
+ { Cir = geometry.DefinitionCir.GetValueOrDefault(identity), Shader = CirShaderArtifactProvider.Resolve(geometry.DefinitionCir.GetValueOrDefault(identity)), GeometryRevision = artifact.StepSha256,
+ Concepts = Visualization.ConceptDisplayProjection.Project(geometry.DefinitionConcepts.GetValueOrDefault(identity) ?? []) }, identity));
}
var occurrences = (pose?.Instances ?? compilation.Ir.Instances).OrderBy(i => i.Path.ToString(), StringComparer.Ordinal).Select(instance =>
{
@@ -87,7 +90,8 @@ public static class AssemblyDisplayMeshExporter
if (instance.ResolvedTransform is null || instance.ResolvedTransform.Matrix.Length != 16 || instance.ResolvedTransform.Matrix.Any(v => !double.IsFinite(v)))
throw new InvalidOperationException($"assembly-mesh-unresolved-transform:{instance.Path}");
return new AssemblyDisplayMeshOccurrence(instance.StableId, instance.Path.ToString(), instance.ParentStableId, id, instance.ResolvedTransform.Matrix.ToArray(), instance.StableId)
- { Material = DisplayProjection.Material(instance.Appearance), Kind = instance.Kind.ToString() };
+ { Material = DisplayProjection.Material(instance.Appearance), Kind = instance.Kind.ToString(),
+ Concepts = Visualization.ConceptDisplayProjection.Project(instance.SemanticRoot) };
}).ToArray();
return new("aetheris/assembly-display-mesh/1", compilation.Ir.Name, "mm", definitions, occurrences);
}
diff --git a/Aetheris.Kernel.Firmament/Assembly/AssemblyM1Execution.cs b/Aetheris.Kernel.Firmament/Assembly/AssemblyM1Execution.cs
index c37f701e..cd11d3f1 100644
--- a/Aetheris.Kernel.Firmament/Assembly/AssemblyM1Execution.cs
+++ b/Aetheris.Kernel.Firmament/Assembly/AssemblyM1Execution.cs
@@ -22,6 +22,7 @@ public sealed record AssemblyExecutedGeometry(
IReadOnlyDictionary<string, BrepBody> InstanceBodies)
{
public IReadOnlyDictionary<string, FirmamentCirRetention> DefinitionCir { get; init; } = new Dictionary<string, FirmamentCirRetention>();
+ public IReadOnlyDictionary<string, IReadOnlyList<ConceptIrStructInstance>> DefinitionConcepts { get; init; } = new Dictionary<string, IReadOnlyList<ConceptIrStructInstance>>();
}
public sealed record AssemblyM1CompilationResult(
@@ -64,7 +65,10 @@ internal sealed record MaterializedAssemblyDefinition(
string? CanonicalStep = null,
FirmamentCirRetention? Cir = null,
string? InputKey = null,
- string? DeclarationScope = null);
+ string? DeclarationScope = null)
+{
+ public IReadOnlyList<ConceptIrStructInstance> Concepts { get; init; } = [];
+}
/// <summary>
/// M1's definition seam: specialize through the ordinary Firmament compiler, then
@@ -317,7 +321,8 @@ internal static partial class AssemblyDefinitionMaterializer
var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(build.Value.StepText)));
var stableId = "assembly-definition:" + Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(definitionIdentity)))[..16];
var artifact = new AssemblyDefinitionArtifactIr(stableId, definitionIdentity, specialization, hash, Metrics(import.Value), provenance);
- return new(definitionIdentity, specialization, import.Value, semantics, artifact, build.Value.StepText, build.Value.Cir);
+ return new(definitionIdentity, specialization, import.Value, semantics, artifact, build.Value.StepText, build.Value.Cir)
+ { Concepts = build.Value.ConceptDisplayValues };
}
private static IEnumerable<SemanticValue> WindingSemantics(FirmamentWireFormReport? wire,
@@ -566,6 +571,7 @@ public sealed class AssemblyM1Pipeline
var artifact = new AssemblyGeometryArtifactIr("aetheris/assembly-geometry/m1", definitionsIr, instanceArtifacts, residuals, hash, datumSeats);
return new(artifact, definitions.ToDictionary(pair => pair.Key, pair => pair.Value.Body, StringComparer.Ordinal), instances)
{
+ DefinitionConcepts = definitions.Where(p => p.Value.Concepts.Count > 0).ToDictionary(p => p.Key, p => p.Value.Concepts, StringComparer.Ordinal),
DefinitionCir = definitions.Where(p => p.Value.Cir is not null)
.ToDictionary(p => p.Key, p => p.Value.Cir! with { DefinitionId = p.Value.Artifact.StableId }, StringComparer.Ordinal)
};
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index ef7ca0f4..716efa7e 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -169,7 +169,9 @@ public static class FirmamentBuildAndExport
{
var parsed = ParseSemanticSource(source, sourceDirectory);
if (!parsed.IsSuccess || parsed.Document is null) return export;
- export = export with { DocumentName = parsed.Document.ModelName, RuntimeAdmissionDocument = parsed.Document };
+ export = export with { DocumentName = parsed.Document.ModelName, RuntimeAdmissionDocument = parsed.Document,
+ ConceptDisplayValues = parsed.Document.ConceptIr?.Structs
+ ?? ConceptIrResolver.RetainSpatialStructs(parsed.DiagnosticSource ?? parsed.BoundSource ?? source) };
var edgeFinishes = (parsed.Document.ModifyBlocks ?? [])
.SelectMany(modification => (modification.EdgeFinishes ?? []).Select(finish => new FirmamentEngineeringFeatureReport(
diff --git a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
index 093d3aab..40ff10ee 100644
--- a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
@@ -46,6 +46,7 @@ public sealed record FirmamentStepExportResult(
// from diagnostic feature ids such as "gear:Name" and primitive bridge names.
[JsonIgnore] public string? RuntimeBodySourceName { get; init; }
[JsonIgnore] internal Aetheris.Kernel.Firmament.FirmamentV2.FirmamentV2Document? RuntimeAdmissionDocument { get; init; }
+ [JsonIgnore] internal IReadOnlyList<Aetheris.Kernel.Firmament.FirmamentV2.ConceptIrStructInstance> ConceptDisplayValues { get; init; } = [];
public FirmamentCirRetention? Cir { get; init; }
public FirmamentMakerMarkReport? MakerMark { get; init; }
public ProfileEdgeFinishEvidence? EdgeFinishPlanning { get; init; }
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/ConceptIr.cs b/Aetheris.Kernel.Firmament/FirmamentV2/ConceptIr.cs
index c00e47f4..615a1c57 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/ConceptIr.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/ConceptIr.cs
@@ -206,6 +206,31 @@ internal static class ConceptIrResolver
public static ConceptPhase3Resolution? Resolve(string source, List<string> diagnostics) => Resolve(source, diagnostics, null);
+ /// <summary>Presentation retention uses the same value evaluator without imposing the
+ /// Phase3 Box/Modify materialization shape on other admitted construction families.</summary>
+ internal static IReadOnlyList<ConceptIrStructInstance> RetainSpatialStructs(string source)
+ {
+ var declarations = FirmamentSyntaxTraversal.Declarations(FirmamentSyntaxParser.Parse(source).Document)
+ .Where(d => d.Type.Name.Text == "Struct" && d.Modifiers.Any(m => m.Name.Text == "Concept") && d.Body is not null && d.Name is not null).ToArray();
+ if (declarations.Length == 0) return [];
+ var scalars = new FirmamentCompileTimeValues(source);
+ var initialization = new List<string>();
+ scalars.Initialize(new Dictionary<string, TemplateRecordTypeIr>(), initialization);
+ var instances = new List<ConceptIrStructInstance>();
+ foreach (var declaration in declarations)
+ {
+ var span = declaration.Body!.ContentSpan;
+ var diagnostics = new List<string>();
+ var members = ResolveMembers(declaration.Name!.Text, source.Substring(span.Start, span.Length), span.Start,
+ "", [], [], diagnostics, scalars);
+ // Nonspatial requirements remain compile-time values, not invented geometry.
+ // Retain only values the existing resolver actually produced.
+ instances.Add(new(declaration.Name.Text, [], members, false, "CompileTimeOnlyErased",
+ new(declaration.Span.Start, declaration.Span.Length)));
+ }
+ return instances;
+ }
+
internal static ConceptPhase3Resolution? Resolve(string source, List<string> diagnostics, FirmamentCompileTimeValues? scalars)
{
// Match roles are compile-time conformance metadata. They deliberately do not lower to AIR,
diff --git a/Aetheris.Kernel.Firmament/Visualization/ConceptDisplayProjection.cs b/Aetheris.Kernel.Firmament/Visualization/ConceptDisplayProjection.cs
new file mode 100644
index 00000000..a5096103
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Visualization/ConceptDisplayProjection.cs
@@ -0,0 +1,98 @@
+using Aetheris.Kernel.Firmament.FirmamentV2;
+using Aetheris.Semantics;
+
+namespace Aetheris.Kernel.Firmament.Visualization;
+
+/// <summary>Definition-local millimetre guides, separate from material and exported topology.</summary>
+public sealed record ConceptDisplayWire(string Id, string Owner, string Kind, double[] Points, string Provenance);
+
+/// <summary>Projects bound values only. Infinite planes/axes use a finite 40 mm display guide.</summary>
+public static class ConceptDisplayProjection
+{
+ public static IReadOnlyList<ConceptDisplayWire> Project(FirmamentStepExportResult export) =>
+ Project(export.ConceptDisplayValues);
+
+ public static IReadOnlyList<ConceptDisplayWire> Project(ConceptIrDocument? document)
+ => Project(document?.Structs ?? []);
+
+ public static IReadOnlyList<ConceptDisplayWire> Project(IReadOnlyList<ConceptIrStructInstance> structs)
+ {
+ var wires = new List<ConceptDisplayWire>();
+ foreach (var instance in structs)
+ foreach (var (name, value) in instance.Members.OrderBy(p => p.Key, StringComparer.Ordinal))
+ Add(value, instance.Name + "." + name, wires);
+ return wires;
+ }
+
+ public static IReadOnlyList<ConceptDisplayWire> Project(SemanticValue root)
+ {
+ var wires = new List<ConceptDisplayWire>();
+ var visited = new HashSet<string>(StringComparer.Ordinal);
+ void Visit(SemanticValue value)
+ {
+ if (!visited.Add(value.StableIdentity)) return;
+ var owner = value.StableIdentity;
+ foreach (var binding in value.Bindings)
+ switch (binding)
+ {
+ case ExactPointBinding p: Point(owner, [p.X, p.Y, p.Z], "Bound semantic point", wires); break;
+ case ExactAxisBinding a: Axis(owner, [a.OriginX, a.OriginY, a.OriginZ], [a.DirectionX, a.DirectionY, a.DirectionZ], "Bound semantic axis", wires); break;
+ case ExactPlaneBinding p: Plane(owner, [p.OriginX, p.OriginY, p.OriginZ], [p.NormalX, p.NormalY, p.NormalZ], null, "Bound semantic plane", wires); break;
+ case ExactDatumFrameBinding f:
+ var o = new[] { f.OriginX, f.OriginY, f.OriginZ };
+ foreach (var (name, direction) in new[] { ("X", new[] { f.XAxisX, f.XAxisY, f.XAxisZ }), ("Y", new[] { f.YAxisX, f.YAxisY, f.YAxisZ }), ("Z", new[] { f.ZAxisX, f.ZAxisY, f.ZAxisZ }) })
+ Line(owner + ":" + name, owner, "Frame", [o, Offset(o, direction, 20)], "Bound semantic frame; 20 mm display axes", wires);
+ break;
+ }
+ foreach (var member in value.ExposedMembers.OrderBy(p => p.Key, StringComparer.Ordinal)) Visit(member.Value);
+ }
+ Visit(root);
+ return wires;
+ }
+
+ private static double[] P(ConceptIrPoint3 p) => [p.X, p.Y, p.Z];
+ private static double[] V(ConceptIrVector3 p) => [p.X, p.Y, p.Z];
+ private static double[] Offset(double[] o, double[] d, double t) => [o[0] + d[0] * t, o[1] + d[1] * t, o[2] + d[2] * t];
+ private static double[] Cross(double[] a, double[] b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+ private static double[] Unit(double[] v) { var length = Math.Sqrt(v.Sum(x => x * x)); return v.Select(x => x / length).ToArray(); }
+ private static void Line(string id, string owner, string kind, double[][] points, string provenance, List<ConceptDisplayWire> wires)
+ {
+ var coordinates = points.SelectMany(p => p).ToArray();
+ if (coordinates.Length >= 6 && coordinates.All(double.IsFinite)) wires.Add(new(id, owner, kind, coordinates, provenance));
+ }
+ private static void Point(string owner, double[] point, string provenance, List<ConceptDisplayWire> wires)
+ {
+ for (var axis = 0; axis < 3; axis++) { var d = new double[3]; d[axis] = 1; Line(owner + ":" + axis, owner, "Point", [Offset(point, d, -1), Offset(point, d, 1)], provenance, wires); }
+ }
+ private static void Axis(string owner, double[] origin, double[] direction, string provenance, List<ConceptDisplayWire> wires) =>
+ Line(owner, owner, "Axis", [Offset(origin, Unit(direction), -20), Offset(origin, Unit(direction), 20)], provenance, wires);
+ private static void Plane(string owner, double[] origin, double[] normal, double[]? hint, string provenance, List<ConceptDisplayWire> wires)
+ {
+ var n = Unit(normal);
+ var u = Unit(Cross(hint ?? (Math.Abs(n[2]) < .9 ? [0, 0, 1] : [0, 1, 0]), n));
+ var v = Cross(n, u);
+ Line(owner, owner, "Plane", new[] { (-1, -1), (1, -1), (1, 1), (-1, 1), (-1, -1) }
+ .Select(p => Offset(Offset(origin, u, p.Item1 * 20), v, p.Item2 * 20)).ToArray(), provenance + "; finite display guide", wires);
+ }
+ private static void Add(ConceptIrValue value, string owner, List<ConceptDisplayWire> wires)
+ {
+ switch (value)
+ {
+ case ConceptIrBox3Value b:
+ var corners = Enumerable.Range(0, 8).Select(i => new[] { (i & 1) == 0 ? b.Min.X : b.Max.X, (i & 2) == 0 ? b.Min.Y : b.Max.Y, (i & 4) == 0 ? b.Min.Z : b.Max.Z }).ToArray();
+ for (var i = 0; i < 8; i++) foreach (var bit in new[] { 1, 2, 4 }) if ((i & bit) == 0)
+ Line(owner + $":{i}:{bit}", owner, "Box3", [corners[i], corners[i | bit]], value.Provenance, wires);
+ break;
+ case ConceptIrPlaneValue p: Plane(owner, P(p.Origin), V(p.Normal), p.OrientationHint is null ? null : V(p.OrientationHint), value.Provenance, wires); break;
+ case ConceptIrAxisValue a: Axis(owner, P(a.Origin), V(a.Direction), value.Provenance, wires); break;
+ case ConceptIrRegion2Value r:
+ Line(owner, owner, "Region2", new[] { (r.MinU, r.MinV), (r.MaxU, r.MinV), (r.MaxU, r.MaxV), (r.MinU, r.MaxV), (r.MinU, r.MinV) }
+ .Select(p => Offset(Offset(P(r.Center), V(r.U), p.Item1), V(r.V), p.Item2)).ToArray(), value.Provenance, wires); break;
+ case ConceptIrPoint3Value p: Point(owner, P(p.Point), value.Provenance, wires); break;
+ case ConceptIrPointSetValue set: foreach (var p in set.Points) Point(owner + ":" + p.StableId, P(p.Point), p.Provenance, wires); break;
+ case ConceptIrKeyedPointSetValue set:
+ foreach (var p in set.Points.Where(p => p.Coordinates.Count == 3)) Point(owner + ":" + p.Key, p.Coordinates.ToArray(), p.Provenance, wires);
+ break;
+ }
+ }
+}
diff --git a/Aetheris.Server/Api/AssemblyDisplayService.cs b/Aetheris.Server/Api/AssemblyDisplayService.cs
index 9fa42973..7dbed9f7 100644
--- a/Aetheris.Server/Api/AssemblyDisplayService.cs
+++ b/Aetheris.Server/Api/AssemblyDisplayService.cs
@@ -103,7 +103,8 @@ public static class AssemblyDisplayService
}
if (body is null) { error = "display-part-brep-unavailable"; return false; }
var id = part.Value.Cir?.DefinitionId ?? "part-definition:"+part.Value.ExportedFeatureId;
- var definition = AssemblyDisplayMeshExporter.PrepareDefinition(id, part.Value.ExportedFeatureId, body) with { Cir = part.Value.Cir, Shader = CirShaderArtifactProvider.Resolve(part.Value.Cir), GeometryRevision = part.Value.Cir?.DefinitionId };
+ var definition = AssemblyDisplayMeshExporter.PrepareDefinition(id, part.Value.ExportedFeatureId, body) with { Cir = part.Value.Cir, Shader = CirShaderArtifactProvider.Resolve(part.Value.Cir), GeometryRevision = part.Value.Cir?.DefinitionId,
+ Concepts = Aetheris.Kernel.Firmament.Visualization.ConceptDisplayProjection.Project(part.Value) };
packet = FromDisplay(new("aetheris/display-mesh/1", Path.GetFileNameWithoutExtension(path), "mm", [definition],
[new("part", Path.GetFileNameWithoutExtension(path), null, id, Transform3D.Identity.ToRowMajor(), part.Value.ExportedFeatureId)]));
return true;
diff --git a/Aetheris.Web.Runtime/Program.cs b/Aetheris.Web.Runtime/Program.cs
index b89f98a4..9d6c61d0 100644
--- a/Aetheris.Web.Runtime/Program.cs
+++ b/Aetheris.Web.Runtime/Program.cs
@@ -526,7 +526,7 @@ public static partial class Program
mappingPhase.Dispose();
var meshPhase = BuildPerfTrace.Phase("web.mesh-build");
var mesh = WebMeshBuilder.Build(Name, definitionId, entityId, displayBody,
- build.Value.RuntimeCorrespondence, boxSource, Revision + 1, featureSources, build.Value.Cir);
+ build.Value.RuntimeCorrespondence, boxSource, Revision + 1, featureSources, build.Value.Cir, Aetheris.Kernel.Firmament.Visualization.ConceptDisplayProjection.Project(build.Value));
meshPhase.Dispose();
var meshMs = watch.Elapsed.TotalMilliseconds;
var featureNodes = (build.Value.EngineeringFeatures ?? []).Select(feature => new WebTreeNode(feature.FeatureId, feature.Kind, feature.Name, entityId, [], true,
@@ -725,7 +725,7 @@ internal static class WebMeshBuilder
public static object Build(string name, string definitionId, string entityId, BrepBody body,
Aetheris.Kernel.Firmament.Materializer.SemanticTopologyCorrespondence? correspondence = null,
WebSourceRef? source = null, int buildRevision = 0, IReadOnlyDictionary<string, WebSourceRef?>? featureSources = null,
- FirmamentCirRetention? cir = null)
+ FirmamentCirRetention? cir = null, IReadOnlyList<Aetheris.Kernel.Firmament.Visualization.ConceptDisplayWire>? concepts = null)
{
// Browser WASM has no blocking monitor wait. Use the existing synchronous
// tessellator authority; the Worker transport supplies UI responsiveness.
@@ -767,6 +767,7 @@ internal static class WebMeshBuilder
units = "mm",
definitions = new[] { new { id = definitionId, identity = entityId, positions = positions.ToArray(), normals = normals.ToArray(), indices = indices.ToArray(), ranges,
cir, shader, geometryRevision = definitionId, displayPath = shader.Artifact is not null ? "cir" : "mesh", fallbackReason = shader.Reason,
+ concepts = concepts ?? [],
edges = tessellation.Value.EdgePolylines.Select(edge =>
{
Aetheris.Kernel.Firmament.Materializer.SemanticTopologyDescendant? semanticEdge = null;
diff --git a/Aetheris.Web.Runtime/sdk/src/index.d.ts b/Aetheris.Web.Runtime/sdk/src/index.d.ts
index d7a7ce49..225787f2 100644
--- a/Aetheris.Web.Runtime/sdk/src/index.d.ts
+++ b/Aetheris.Web.Runtime/sdk/src/index.d.ts
@@ -14,8 +14,9 @@ export interface CirRetention { readonly schema: 'aetheris/cir-retention/1'; rea
export interface ResolvedDisplayMaterial { readonly baseColor: readonly number[]; readonly roughness: number; readonly metallic: number; readonly opacity: number; readonly emissive: readonly number[] }
export interface DisplayShaderArtifact { readonly schema: 'aetheris/display-shader/1'; readonly shaderId: string; readonly wgsl: string; readonly vertexEntryPoint: string; readonly fragmentEntryPoint: string; readonly bindings: readonly { readonly group: number; readonly binding: number; readonly kind: 'uniform'; readonly byteSize: number }[]; readonly capabilities: readonly string[]; readonly sourceIdentity: string; readonly compilerVersion: string }
export interface DisplayCamera { readonly name: string; readonly transform: readonly number[]; readonly lookAtMm?: readonly number[]; readonly fovDegrees: number }
-export interface DisplayMeshDefinition { readonly id: string; readonly identity: string; readonly positions: Float64Array; readonly normals: Float64Array; readonly indices: Uint32Array; readonly ranges: readonly MeshRange[]; readonly edges?: readonly DisplayEdgePolyline[]; readonly cir?: CirRetention | null; readonly displayPath?: 'mesh' | 'cir'; readonly fallbackReason?: string | null; readonly shader?: { readonly artifact: DisplayShaderArtifact | null; readonly status: string; readonly reason: string | null; readonly cacheHit: boolean; readonly generationMilliseconds: number }; readonly geometryRevision?: string | null; readonly diagnostics?: readonly { readonly code: string; readonly message: string; readonly faceId?: string | null }[] }
-export interface DisplayMeshOccurrence { readonly id: string; readonly path: string; readonly parentId?: string; readonly definitionId?: string; readonly semanticEntityId: string; readonly transform: readonly number[]; readonly material?: ResolvedDisplayMaterial | null; readonly kind?: string }
+export interface ConceptDisplayWire { readonly id: string; readonly owner: string; readonly kind: string; readonly points: readonly number[]; readonly provenance: string }
+export interface DisplayMeshDefinition { readonly concepts?: readonly ConceptDisplayWire[]; readonly id: string; readonly identity: string; readonly positions: Float64Array; readonly normals: Float64Array; readonly indices: Uint32Array; readonly ranges: readonly MeshRange[]; readonly edges?: readonly DisplayEdgePolyline[]; readonly cir?: CirRetention | null; readonly displayPath?: 'mesh' | 'cir'; readonly fallbackReason?: string | null; readonly shader?: { readonly artifact: DisplayShaderArtifact | null; readonly status: string; readonly reason: string | null; readonly cacheHit: boolean; readonly generationMilliseconds: number }; readonly geometryRevision?: string | null; readonly diagnostics?: readonly { readonly code: string; readonly message: string; readonly faceId?: string | null }[] }
+export interface DisplayMeshOccurrence { readonly concepts?: readonly ConceptDisplayWire[]; readonly id: string; readonly path: string; readonly parentId?: string; readonly definitionId?: string; readonly semanticEntityId: string; readonly transform: readonly number[]; readonly material?: ResolvedDisplayMaterial | null; readonly kind?: string }
export interface DisplayBoundary { readonly path: string; readonly room: string; readonly kind: string; readonly frame: readonly number[]; readonly widthMm: number; readonly heightMm: number; readonly openings: readonly string[] }
export interface DisplayMesh { readonly schema: 'aetheris/display-mesh/1' | 'aetheris/assembly-display-mesh/1' | 'aetheris/scene-display-mesh/1'; readonly name: string; readonly units: 'mm'; readonly definitions: readonly DisplayMeshDefinition[]; readonly occurrences: readonly DisplayMeshOccurrence[]; readonly cameras?: readonly DisplayCamera[]; readonly minimumMm?: readonly number[]; readonly maximumMm?: readonly number[]; readonly boundaries?: readonly DisplayBoundary[] }
export interface ChangeSet { readonly changedEntityIds: readonly string[]; readonly addedEntityIds: readonly string[]; readonly removedEntityIds: readonly string[]; readonly meshChanged: boolean; readonly diagnosticsChanged: boolean }
diff --git a/Aetheris.Web.Runtime/telos/src/concepts.ts b/Aetheris.Web.Runtime/telos/src/concepts.ts
new file mode 100644
index 00000000..4f699281
--- /dev/null
+++ b/Aetheris.Web.Runtime/telos/src/concepts.ts
@@ -0,0 +1,43 @@
+import { BufferGeometry, Float32BufferAttribute, Group, Line, LineBasicMaterial, Matrix4 } from "three";
+import type { DisplayPacket, TelosLine } from "./contracts.js";
+
+/** Gold construction guides share the material occurrence's local-to-world transform.
+ * A low-opacity wide stroke is a static halo, not an extra bloom/render pipeline. */
+export function conceptWireframe(packet: DisplayPacket): TelosLine[] {
+ const definitions = new Map(packet.definitions.map(d => [d.id, d]));
+ return packet.occurrences.flatMap(occurrence =>
+ [...(definitions.get(occurrence.definitionId ?? "")?.concepts ?? []), ...(occurrence.concepts ?? [])]
+ .flatMap((wire, index): TelosLine[] => {
+ if (wire.points.length < 6 || wire.points.length % 3 || !wire.points.every(Number.isFinite)) return [];
+ const line: TelosLine = {
+ id: `concept:${occurrence.id}:${index}:${wire.id}`, points: wire.points,
+ transform: occurrence.transform, identity: { occurrenceId: occurrence.id, overlayId: `concept:${wire.owner}` },
+ overlay: true, pickable: false, depthMode: "always-on-top", widthPixels: 1.6, color: [1, .68, .12, 1],
+ };
+ return [{ ...line, id: line.id + ":halo", widthPixels: 7, color: [1, .62, .05, .12] }, line];
+ }));
+}
+
+/** Transitional WebGL consumes the same projected wires; no independent parsing. */
+export function conceptWireframeGroup(packet: DisplayPacket): Group {
+ const group = new Group();
+ group.name = "Concept Structs";
+ for (const wire of conceptWireframe(packet).filter(w => !w.id.endsWith(":halo"))) {
+ const geometry = new BufferGeometry().setAttribute("position", new Float32BufferAttribute(Array.from(wire.points), 3));
+ const material = new LineBasicMaterial({ color: "#ffcb45", depthTest: false, depthWrite: false, toneMapped: false });
+ const line = new Line(geometry, material);
+ line.name = wire.id;
+ line.matrix.copy(new Matrix4().fromArray(wire.transform!));
+ line.matrixAutoUpdate = false;
+ line.renderOrder = 20;
+ line.raycast = () => undefined;
+ group.add(line);
+ }
+ return group;
+}
+
+export function disposeConceptWireframe(group: Group): void {
+ group.traverse(object => { if (object instanceof Line) { object.geometry.dispose(); (object.material as LineBasicMaterial).dispose(); } });
+ group.removeFromParent();
+ group.clear();
+}
diff --git a/Aetheris.Web.Runtime/telos/src/contracts.ts b/Aetheris.Web.Runtime/telos/src/contracts.ts
index 7a9808b5..29684c49 100644
--- a/Aetheris.Web.Runtime/telos/src/contracts.ts
+++ b/Aetheris.Web.Runtime/telos/src/contracts.ts
@@ -46,6 +46,8 @@ export interface TelosMesh {
triangleRange?: { startTriangle: number; triangleCount: number };
}
export interface TelosLine {
+ /** Presentation-only guides must not intercept engineering picks. */
+ pickable?: boolean;
/** Fade finite reference-grid endpoints without changing engineering edge coverage. */
fadeEnds?: boolean;
id: string;
@@ -105,8 +107,16 @@ export interface TelosHit extends TelosIdentity {
worldNormal: number[] | null;
distance: number;
}
+export interface ConceptDisplayWire {
+ readonly id: string;
+ readonly owner: string;
+ readonly kind: string;
+ readonly points: readonly number[];
+ readonly provenance: string;
+}
export interface DisplayPacket {
definitions: readonly (TelosGeometry & {
+ concepts?: readonly ConceptDisplayWire[];
edges?: readonly {
edgeId: string;
points: readonly (readonly number[])[];
@@ -125,6 +135,7 @@ export interface DisplayPacket {
} | null;
})[];
occurrences: readonly {
+ concepts?: readonly ConceptDisplayWire[];
id: string;
definitionId?: string;
semanticEntityId: string;
diff --git a/Aetheris.Web.Runtime/telos/src/index.ts b/Aetheris.Web.Runtime/telos/src/index.ts
index 6524c464..a8922ed7 100644
--- a/Aetheris.Web.Runtime/telos/src/index.ts
+++ b/Aetheris.Web.Runtime/telos/src/index.ts
@@ -9,3 +9,4 @@ export * from "./inspection.js";
export * from "./presentation.js";
export * from "./temporal.js";
+export * from "./concepts.js";
diff --git a/Aetheris.Web.Runtime/telos/src/pick.ts b/Aetheris.Web.Runtime/telos/src/pick.ts
index b5dab232..47e27a54 100644
--- a/Aetheris.Web.Runtime/telos/src/pick.ts
+++ b/Aetheris.Web.Runtime/telos/src/pick.ts
@@ -126,7 +126,7 @@ export class TelosPick {
priority = -1;
for (const line of [...this.dynamicLines, ...this.lines]) {
if (
- line.visible === false ||
+ line.visible === false || line.pickable === false ||
(mode !== "edge" && !line.identity.overlayId)
)
continue;
diff --git a/Aetheris.Web.Runtime/telos/tests/concepts.test.ts b/Aetheris.Web.Runtime/telos/tests/concepts.test.ts
new file mode 100644
index 00000000..fbdfc97e
--- /dev/null
+++ b/Aetheris.Web.Runtime/telos/tests/concepts.test.ts
@@ -0,0 +1,32 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Matrix4, Vector3 } from "three";
+import { conceptWireframe, conceptWireframeGroup, disposeConceptWireframe } from "../dist/concepts.js";
+import { TelosPick } from "../dist/pick.js";
+import { TelosCamera } from "../dist/camera.js";
+import type { DisplayPacket } from "../dist/contracts.js";
+
+test("gold guides follow occurrences, remain separate from material and never steal a pick", () => {
+ const wire = { id: "Design.Axis", owner: "Design", kind: "Axis", points: [-1, 0, 0, 1, 0, 0], provenance: "compiler" };
+ const packet: DisplayPacket = {
+ definitions: [{ id: "part", positions: [], normals: [], indices: [], concepts: [wire] }],
+ occurrences: [{ id: "first", definitionId: "part", semanticEntityId: "part", transform: new Matrix4().elements },
+ { id: "second", definitionId: "part", semanticEntityId: "part", transform: new Matrix4().makeTranslation(60, 0, 0).elements }],
+ };
+ const lines = conceptWireframe(packet);
+ assert.equal(lines.length, 4);
+ assert.ok(lines.every(l => l.overlay && l.pickable === false && l.depthMode === "always-on-top"));
+ assert.equal(new Vector3(-1, 0, 0).applyMatrix4(new Matrix4().fromArray(lines[2].transform!)).x, 59);
+ assert.equal(lines[0].points, lines[2].points);
+ const camera = new TelosCamera();
+ camera.resize(200, 200); camera.position.set(0, 0, 10); camera.target.set(0, 0, 0);
+ const picker = new TelosPick(camera);
+ picker.setScene({ meshes: [], fields: [], lines });
+ assert.equal(picker.pick([100, 100], "edge"), null);
+ const group = conceptWireframeGroup(packet);
+ assert.equal(group.children.length, 2);
+ assert.equal(group.children[1].matrix.elements[12], 60);
+ disposeConceptWireframe(group);
+ assert.equal(group.children.length, 0);
+ assert.equal(packet.definitions[0].indices.length, 0);
+});
diff --git a/aetheris.client/src/App.tsx b/aetheris.client/src/App.tsx
index bc067cee..87798f13 100644
--- a/aetheris.client/src/App.tsx
+++ b/aetheris.client/src/App.tsx
@@ -232,6 +232,7 @@ function App() {
const [isResetting, setIsResetting] = useState(false);
const [isGridVisible, setIsGridVisible] = useState(true);
const [isCoordVisible, setIsCoordVisible] = useState(true);
+ const [showConcepts, setShowConcepts] = useState(false);
const [cadmataArtifact, setCadmataArtifact] = useState<CadmataVisualizationArtifact | null>(null);
const [cadmataLayers, setCadmataLayers] =
useState<CadmataLayerVisibility>(DEFAULT_CADMATA_LAYERS);
@@ -1067,6 +1068,9 @@ function App() {
<section className="viewport-column" {...machinaRegion("viewport")}>
<div className="viewport-frame">
<div className="viewport-controls" role="group" aria-label="Viewport display controls">
+ <button type="button" className={`viewport-segmented__button${showConcepts ? " is-active" : ""}`} aria-pressed={showConcepts}
+ disabled={!assemblyPacket?.display?.definitions.some(d => d.concepts?.length) && !assemblyPacket?.display?.occurrences.some(o => o.concepts?.length)}
+ title="Show Concept Structs as gold construction wireframes" onClick={() => setShowConcepts(value => !value)}>Concepts</button>
<button
type="button"
className={
@@ -1172,6 +1176,7 @@ function App() {
</label>
</div>
<AetherisViewport
+ showConcepts={showConcepts}
busyMessage={status === "loading" ? statusMessage : null}
errorMessage={status === "error" ? statusMessage : null}
displayScene={displayScene.displayScene}
diff --git a/aetheris.client/src/__tests__/cadmataTelos.test.ts b/aetheris.client/src/__tests__/cadmataTelos.test.ts
index 9a43cbdd..28a08a77 100644
--- a/aetheris.client/src/__tests__/cadmataTelos.test.ts
+++ b/aetheris.client/src/__tests__/cadmataTelos.test.ts
@@ -4,6 +4,24 @@ import type { DisplayScene } from "../viewer/displayRenderables";
import type { AssemblyDisplayPacketDto } from "../api/aetherisApi";
describe("Cadmata Telos packet adapter", () => {
+ it("adds gold guides only when Concepts is enabled, preserving material and transforms", () => {
+ const transform = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 60, 0, 0, 1];
+ const packet: AssemblyDisplayPacketDto = {
+ schema: "test", name: "Concepts", rootOccurrenceStableId: "root", definitions: [], occurrences: [],
+ mates: [], toleranceStackups: [], bounds: { minimum: [0, 0, 0], maximum: [80, 50, 25] }, diagnostics: [], performance: {},
+ display: {
+ definitions: [{ id: "part", positions: [], normals: [], indices: [], concepts: [
+ { id: "Design.Axis", owner: "Design", kind: "Axis", points: [0, 0, 0, 0, 0, 20], provenance: "compiler" },
+ ] }], occurrences: [{ id: "second", definitionId: "part", semanticEntityId: "part", transform }],
+ },
+ };
+ const before = cadmataTelosScene({ assemblyPacket: packet });
+ const after = cadmataTelosScene({ assemblyPacket: packet, showConcepts: true });
+ expect(before.lines).toHaveLength(0); expect(after.lines).toHaveLength(2);
+ expect(after.meshes).toEqual(before.meshes);
+ expect(after.lines[0].transform).toBe(transform);
+ expect(after.lines.every(l => l.overlay && l.pickable === false)).toBe(true);
+ });
it("shares kernel edge buffers across occurrence transforms and selection changes", () => {
const first = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 5, 0, 0, 1];
const second = [...first]; second[12] = 9;
diff --git a/aetheris.client/src/viewer/AetherisViewport.tsx b/aetheris.client/src/viewer/AetherisViewport.tsx
index dbe65a2c..603c910f 100644
--- a/aetheris.client/src/viewer/AetherisViewport.tsx
+++ b/aetheris.client/src/viewer/AetherisViewport.tsx
@@ -95,6 +95,7 @@ function TelosViewport(props: AetherisViewportProps & { onRetry(): void }) {
current.setAA(value.aaMode ?? "SpatialOnly", value.aaDebug ?? "color");
current.setPresentation(telosPresentation(theme));
current.setScene(inspectSurfaces(cadmataTelosScene(value), inspection.current.mode, inspection.current.face));
+ canvas.current?.setAttribute("data-concept-wires", String(current.scene.lines.filter(line => line.id.startsWith("concept:") && !line.id.endsWith(":halo")).length));
current.background = clearColor(theme.sceneBackground);
current.grid = value.showGrid !== false && theme.gridStyle.enabled;
const model = value.assemblyPacket ?? value.displayScene;
diff --git a/aetheris.client/src/viewer/LegacyAetherisViewport.tsx b/aetheris.client/src/viewer/LegacyAetherisViewport.tsx
index 0753df21..73ce343d 100644
--- a/aetheris.client/src/viewer/LegacyAetherisViewport.tsx
+++ b/aetheris.client/src/viewer/LegacyAetherisViewport.tsx
@@ -28,6 +28,7 @@ import type { AssemblyDisplayPacketDto } from "../api/aetherisApi";
import { mapFacePatchToRenderFacePatch } from "./tessellationMapper";
import { buildAdaptiveGridPlan, type GridBounds } from "./logarithmicGrid";
import { CadmataOverlay } from "./LegacyCadmataOverlay";
+import { conceptWireframeGroup, disposeConceptWireframe, type DisplayPacket } from "@aetheris/three-telos";
import { ATELIER_VIEWPORT_THEME, type ViewportTheme } from "./viewportTheme";
import { PmiAnnotationLayer } from "./LegacyPmiAnnotationLayer";
@@ -541,7 +542,18 @@ function RendererConfiguration({ theme }: { theme: ViewportTheme }) {
return null;
}
+function ConceptWires({ packet }: { packet: DisplayPacket }) {
+ const parent = useRef<import("three").Group>(null);
+ useEffect(() => {
+ const group = conceptWireframeGroup(packet);
+ parent.current?.add(group);
+ return () => disposeConceptWireframe(group);
+ }, [packet]);
+ return <group ref={parent} />;
+}
+
export function LegacyAetherisViewport({
+ showConcepts = false,
displayScene = null,
highlightedFaceId = null,
highlightedEdgeId = null,
@@ -668,6 +680,7 @@ export function LegacyAetherisViewport({
theme={theme}
/>
) : null}
+ {showConcepts && assemblyPacket?.display ? <ConceptWires packet={assemblyPacket.display} /> : null}
{cadmataLayers ? (
<CadmataOverlay
artifact={cadmataArtifact}
diff --git a/aetheris.client/src/viewer/cadmataTelos.ts b/aetheris.client/src/viewer/cadmataTelos.ts
index ce77a521..086dbe72 100644
--- a/aetheris.client/src/viewer/cadmataTelos.ts
+++ b/aetheris.client/src/viewer/cadmataTelos.ts
@@ -2,6 +2,7 @@ import {
materialFromAppearance,
fromDisplayMesh,
identityTransform,
+ conceptWireframe,
type TelosScene,
type TelosMesh,
type TelosLine,
@@ -43,7 +44,7 @@ export function cadmataTelosScene(props: AetherisViewportProps): TelosScene {
})),
...overlays.meshes,
],
- lines: [...scene.lines, ...overlays.lines],
+ lines: [...scene.lines, ...overlays.lines, ...(props.showConcepts ? conceptWireframe(props.assemblyPacket.display) : [])],
};
}
const theme = props.theme ?? ATELIER_VIEWPORT_THEME;
diff --git a/aetheris.client/src/viewer/viewportProps.ts b/aetheris.client/src/viewer/viewportProps.ts
index 87e6ec84..cbeaac78 100644
--- a/aetheris.client/src/viewer/viewportProps.ts
+++ b/aetheris.client/src/viewer/viewportProps.ts
@@ -5,6 +5,7 @@ import type { CadmataLayerVisibility } from "./cadmataLayers";
import type { PmiVisibility } from "./pmiPresentation";
import type { ViewportTheme } from "./viewportTheme";
export interface AetherisViewportProps {
+ showConcepts?: boolean;
busyMessage?: string | null;
errorMessage?: string | null;
/** Bounded shared Telos developer comparison controls; spatial AA remains the default. */
diff --git a/docs/development/CONCEPT-STRUCT-VISUALIZATION.md b/docs/development/CONCEPT-STRUCT-VISUALIZATION.md
new file mode 100644
index 00000000..8063a272
--- /dev/null
+++ b/docs/development/CONCEPT-STRUCT-VISUALIZATION.md
@@ -0,0 +1,75 @@
+# Concept Struct visualization qualification — 2026-10-19
+
+## Result
+
+**Success for retained geometric Concepts.** Helios and Cadmata have an opt-in
+**Concepts** button. It draws gold construction wires through the material, with
+a faint static halo in WebGPU and crisp wires in the WebGL fallback. The toggle
+does not compile, change topology or intercept engineering selection.
+
+The source witness is
+`fixtures/Regression/Visualization/concept-structs.firmament`: an 80 × 50 × 25 mm
+chamfered box with a Concept Box3, top plane, center axis and two mount points.
+Its 20 guides are separate from material meshes and STEP output.
+
+## Ownership and compatibility
+
+- The compiler projects resolved Box3, Plane, Axis, Region2 and 3D point/set values.
+ Assembly occurrences also publish guides from exact semantic frame/plane/axis/
+ point bindings. No browser source parser or mesh-edge inference is involved.
+- A focused test exposed unused Concept Structs disappearing from Template
+ display metadata outside the older Box/Modify route. The existing AST and
+ spatial value resolver now retain those values for presentation before erasure.
+ This does not change source admission, materialization or public port binding.
+- Display definitions share immutable local guides; occurrences provide placement
+ and sampled motion transforms. Existing compilation-session input keys retain
+ the same cache ownership. The SDK carries additive `concepts` metadata.
+- Shared Three Telos code owns gold styling and WebGL projection. Guides are
+ explicitly non-pickable. WebGL resources are disposed when hidden/replaced.
+- Scalar and predicate requirements have no invented geometry. Unsupported spatial
+ value kinds and unframed local 2D points are not synthesized. Infinite planes/
+ axes use finite 40 mm guides, frame axes 20 mm and point marks 2 mm.
+- STEP-only input cannot recover erased Concept Structs. Open Firmament source;
+ the button is disabled when supported retained guides are unavailable.
+
+## Evidence
+
+Generated evidence is under `artifacts/local/concept-wireframes/`.
+
+| Check | Result |
+| --- | --- |
+| Complete Release solution build | Passed; zero errors |
+| Complete .NET regression | 5,663 passed, zero failures/skips; FrictionLab discovers no tests |
+| Core fast lane | 1,087 passed |
+| Focused compiler projection | 2 passed: exact bounds/value types, private Template retention, shared definition and translated occurrences |
+| Three Telos tests | 15 passed, including gold transform/picking/disposal coverage |
+| Cadmata frontend | TypeScript and bundle passed; 19 files / 92 tests passed |
+| Helios frontend | TypeScript and development bundle passed; 20 files / 96 tests passed; final shell test rerun passed |
+| CLI source admission/build | `validate.json` and `build-part.json` succeed |
+| Existing FrontendX4 geometry corpus | 32/32 passed without recording baselines |
+| Real application browser checks | Both products pass WebGPU and WebGL toggle checks; each reports exactly 20 guides |
+| Failed build retention | Helios keeps all 20 guides after the same source receives unknown `distnace` |
+| Independent image checks | Gold pixels increase by thousands when enabled in both renderer paths and return to baseline when hidden |
+
+The failed-draft check reopens an invalid revision of the same source through the
+normal project build path, independent of Monaco keyboard timing. Helios's WebGL
+check starts a fresh application because its
+adapter probe is intentionally cached per startup; capability mutation after
+startup is not a renderer-selection contract.
+
+`cadmata-application.png` and `helios-application.png` were visually inspected.
+The four renderer images and `pixel-qualification.json` verify visible output,
+not just debug counters. `cadmata-browser.json` / `helios-browser.json` record no
+page errors. Browser scripts close their isolated browser profiles.
+
+The native desktop host builds with the updated Cadmata frontend. Qualification
+exercised its application view through the real server; a separate WPF/WebView2
+launch and a new production AOT release were not part of this pass.
+
+The code-quality pass found no new diagnostic allowlists, regex dispatch, source
+rewrites, rendering engine or geometry planner. Public usage and guide limits are
+documented in `docs/public/three-telos.md` and the Helios README.
+
+Temporary application servers were stopped after qualification. No dotnet,
+testhost, aetheris, MSBuild or VBCSCompiler hosts remain; the test browser profiles
+are closed. `git diff --check` passes in both repositories.
diff --git a/docs/public/three-telos.md b/docs/public/three-telos.md
index 38c9c9f8..22263568 100644
--- a/docs/public/three-telos.md
+++ b/docs/public/three-telos.md
@@ -1,5 +1,31 @@
# Three Telos display
+## Concept Struct wireframes
+
+The **Concepts** button in Helios and Cadmata toggles gold construction wireframes.
+It starts off and is disabled when the built model has no retained geometric
+Concept values. In Cadmata, open the Firmament source rather than only its STEP:
+compile-time scaffolds are erased from manufacturing output.
+
+Box3 bounds, planes, axes, Region2 boundaries and resolved 3D points/point sets are
+projected from the compiler's typed values. Assembly datum frames and published
+geometric semantics also provide guides. They follow occurrence placement and
+sampled motion, independently of shaded/wireframe material display. Plain Boolean
+requirements, scalar members and types without a retained spatial value have no
+wireframe. A local 2D point without a spatial frame is not silently lifted to XY.
+
+The overlay is visible through material so interior layout remains legible.
+WebGPU adds a subtle static gold halo; WebGL fallback draws the same crisp gold
+guides. Infinite planes and axes use finite 40 mm guides, frames use 20 mm axes,
+and point marks span 2 mm; these are display sizes, not dimensions of a part.
+The guides do not intercept engineering picks, add bodies, alter STEP/STL output
+or recompile when toggled. Failed builds retain the last valid model's guides.
+
+The admitted example is
+`fixtures/Regression/Visualization/concept-structs.firmament`.
+
+## Shared renderer
+
Cadmata's model, assembly, authoring overlays and PMI presentation share the Three Telos WebGPU host with Helios. It owns the camera, grid, mesh drawing, semantic topology lines, GPU leaders, selection projection and GPU resources. A supported browser/GPU is required for that path.
The shared mesh and line shaders live in standalone `.wgsl` files, loaded through TypeScript during host initialization. Builds carry the shader assets with the package; WebGPU validates their code. CIR field shaders continue through Copeland's typed Visual TypeScript compiler.
diff --git a/fixtures/Regression/Visualization/concept-structs.firmament b/fixtures/Regression/Visualization/concept-structs.firmament
new file mode 100644
index 00000000..865accdd
--- /dev/null
+++ b/fixtures/Regression/Visualization/concept-structs.firmament
@@ -0,0 +1,22 @@
+// Gold construction guides are compile-time intent, not additional material.
+Struct GoldenScaffold {
+ Concept Struct Design {
+ Bounds: Box3 { size: [80mm, 50mm, 25mm] }
+ TopPlane: Bounds.Face(+Z)
+ CenterAxis: Bounds.Center.Axis(+Z)
+ MountPoints: Grid {
+ within: Bounds.Face(+Z).Inset(10mm)
+ columns: 2
+ rows: 1
+ }
+ }
+ Box Stock { bounds: Design.Bounds }
+ Modify Stock {
+ EdgeFinish TopBreak {
+ face: Design.TopPlane
+ target: Boundary
+ kind: Chamfer
+ distance: 1.5mm
+ }
+ }
+}
diff --git a/scripts/qualify-concept-wireframe-images.py b/scripts/qualify-concept-wireframe-images.py
new file mode 100644
index 00000000..1e1b00fb
--- /dev/null
+++ b/scripts/qualify-concept-wireframe-images.py
@@ -0,0 +1,19 @@
+"""Check rendered canvas pixels independently of DOM/debug counters (requires Pillow)."""
+import json
+from pathlib import Path
+from PIL import Image
+
+output = Path('artifacts/local/concept-wireframes')
+report = {}
+for product in ('cadmata', 'helios'):
+ counts = {}
+ for state in ('off', 'gold', 'off-again', 'webgl-gold', 'webgl-off'):
+ image = Image.open(output / f'{product}-{state}.png').convert('RGB')
+ pixels = getattr(image, 'get_flattened_data', image.getdata)()
+ counts[state] = sum(r > 180 and 95 < g < 235 and b < 150 for r, g, b in pixels)
+ assert counts['gold'] > counts['off'] + 200, counts
+ assert counts['webgl-gold'] > counts['webgl-off'] + 200, counts
+ assert abs(counts['off-again'] - counts['off']) < 100, counts
+ report[product] = counts
+(output / 'pixel-qualification.json').write_text(json.dumps(report, indent=2), encoding='utf-8')
+print(json.dumps(report, indent=2))
diff --git a/scripts/qualify-concept-wireframes.mts b/scripts/qualify-concept-wireframes.mts
new file mode 100644
index 00000000..d97fedfd
--- /dev/null
+++ b/scripts/qualify-concept-wireframes.mts
@@ -0,0 +1,84 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+// Run against the real Cadmata/Helios applications, using the installed browser-test dependency.
+const { chromium } = await import(pathToFileURL(resolve(process.argv[2])).href);
+const product = process.argv[3] ?? "cadmata";
+if (!["cadmata", "helios"].includes(product)) throw new Error("Expected cadmata or helios");
+const output = resolve("artifacts/local/concept-wireframes");
+await mkdir(output, { recursive: true });
+const browser = await chromium.launch({ executablePath: "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe", headless: true });
+try {
+ const page = await browser.newPage({ viewport: { width: 1440, height: 960 } });
+ page.setDefaultTimeout(180000);
+ const errors: string[] = [];
+ page.on("pageerror", (error: Error) => errors.push(error.message));
+ await page.goto(product === "cadmata" ? "http://127.0.0.1:5173" : "http://127.0.0.1:4173/local");
+ console.log(product + ": application opened");
+ if (product === "helios") {
+ await page.locator(".status-ready").waitFor();
+ await page.locator('input[type="file"]').setInputFiles(resolve("fixtures/Regression/Visualization/concept-structs.firmament"));
+ }
+ const toggle = page.getByRole("button", { name: "Concepts", exact: true });
+ await toggle.waitFor();
+ await page.waitForFunction(() => !document.querySelector<HTMLButtonElement>('button[title*="Concept Struct"]')?.disabled);
+ const canvas = page.locator('[data-display-host="three-telos"] canvas[data-concept-wires]');
+ await canvas.waitFor();
+ if (await canvas.getAttribute("data-concept-wires") !== "0") throw new Error("Concepts must start hidden");
+ await canvas.screenshot({ path: resolve(output, product + "-off.png") });
+ await toggle.click();
+ await page.waitForFunction(() => Number(document.querySelector('canvas[data-concept-wires]')?.getAttribute("data-concept-wires")) > 0);
+ await page.waitForTimeout(300);
+ const count = Number(await canvas.getAttribute("data-concept-wires"));
+ if (count !== 20) throw new Error("Expected exact Box3/Plane/Axis/two-point guides, got " + count);
+ await canvas.screenshot({ path: resolve(output, product + "-gold.png") });
+ console.log(product + ": gold wires rendered");
+ await page.screenshot({ path: resolve(output, product + "-application.png") });
+ await toggle.click();
+ await page.waitForFunction(() => document.querySelector('canvas[data-concept-wires]')?.getAttribute("data-concept-wires") === "0");
+ await page.waitForTimeout(200);
+ await canvas.screenshot({ path: resolve(output, product + "-off-again.png") });
+ await toggle.click();
+ let retainedAfterFailure = false;
+ if (product === "helios") {
+ // Reopen a bad revision of this same part through the normal project build path.
+ // This avoids making the test depend on Monaco keyboard/event timing.
+ const source = await readFile(resolve("fixtures/Regression/Visualization/concept-structs.firmament"), "utf8");
+ await page.locator('input[type="file"]').setInputFiles({ name: "concept-structs.firmament", mimeType: "text/plain",
+ buffer: Buffer.from(source.replace("distance: 1.5mm", "distnace: 1.5mm")) });
+ console.log(product + ": invalid same-part revision submitted");
+ await page.waitForFunction(() => document.querySelector(".viewport-caption")?.textContent?.includes("Last good model"), null, { timeout: 30000 });
+ await page.screenshot({ path: resolve(output, product + "-failed-draft.png") });
+ retainedAfterFailure = Number(await canvas.getAttribute("data-concept-wires")) === count;
+ if (!retainedAfterFailure) throw new Error("Failed draft lost the last-valid Concept guides");
+ console.log(product + ": failed revision retained its guides");
+ }
+ if (product === "helios") {
+ // Helios probes the adapter once per application startup, including adapter-unavailable browsers.
+ await page.addInitScript(() => Object.defineProperty(navigator, "gpu", { value: undefined, configurable: true }));
+ await page.reload();
+ await page.locator(".status-ready").waitFor();
+ await page.locator('input[type="file"]').setInputFiles(resolve("fixtures/Regression/Visualization/concept-structs.firmament"));
+ await page.waitForFunction(() => !document.querySelector<HTMLButtonElement>('button[title*="Concept Struct"]')?.disabled);
+ await toggle.click();
+ } else {
+ await page.evaluate(() => Object.defineProperty(navigator, "gpu", { value: undefined, configurable: true }));
+ await toggle.click();
+ await toggle.click();
+ }
+ const fallback = page.locator('[data-display-host="transitional-webgl"] canvas').first();
+ await fallback.waitFor();
+ await page.waitForTimeout(1000);
+ await fallback.screenshot({ path: resolve(output, product + "-webgl-gold.png") });
+ await toggle.click();
+ await page.waitForTimeout(200);
+ await fallback.screenshot({ path: resolve(output, product + "-webgl-off.png") });
+ if (errors.length) throw new Error(JSON.stringify(errors));
+ await writeFile(resolve(output, product + "-browser.json"), JSON.stringify({ success: true, product,
+ conceptWires: count, webgpuAndWebgl: true, retainedAfterFailure: product === "helios" ? retainedAfterFailure : null, errors }, null, 2));
+ console.log(product + " real application: Concept toggle, GPU/fallback and retention checks passed");
+} catch (error) {
+ console.error(error);
+ throw error;
+} finally { await browser.close(); }