@es3d/es3d 1.0.1 → 1.0.2

package/README.md

@@ -1,5 +1,14 @@
 # ES3D
 
+<p align="center">
+  <a href="https://www.jsdelivr.com/package/npm/@es3d/es3d"><img src="https://img.shields.io/jsdelivr/npm/hm/@es3d/es3d?label=jsDelivr" alt="jsDelivr"></a>
+  <a href="https://www.npmjs.com/package/@es3d/es3d"><img src="https://img.shields.io/npm/v/@es3d/es3d" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@es3d/es3d"><img src="https://img.shields.io/npm/dm/@es3d/es3d" alt="npm downloads"></a>
+  <a href="https://github.com/bitilia/es3d/stargazers"><img src="https://img.shields.io/github/stars/bitilia/es3d" alt="GitHub stars"></a>
+  <a href="https://github.com/bitilia/es3d/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bitilia/es3d" alt="License"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/@es3d/es3d" alt="Node.js"></a>
+</p>
+
 **A file format for 3D scenes you can write by hand, the way people write SVG.** The file describes objects, not triangles: a rounded box, an outline extruded into a solid, two thousand trees placed by a rule. The viewer builds the triangles, at the detail the screen needs.
 
 This package is the reference implementation:
@@ -59,12 +68,12 @@ const { text } = await importFiles([{ name: 'logo.svg', bytes }]); // SVG, OBJ,
 const { files } = exportFormat(text, 'glb');                         // ES3D → glTF, OBJ, STL, STEP
 ```
 
-Every error has a line, a column, a code and, where it can, a "did you mean" suggestion.
+Every error has a line, a column, a code and, where it can, a "did you mean" suggestion. Repeated warnings that share a code, an element name and a message are printed once, with a count. `validate --json` still lists every warning.
 
 ## The command
 
 ```bash
-npx @es3d/es3d validate scene.es3d               # every diagnostic; exit code 1 on errors
+npx @es3d/es3d validate scene.es3d               # diagnostics, repeated warnings grouped; exit code 1 on errors
 npx @es3d/es3d compact scene.es3d                # convert to the compact syntax (also: markup, json, fmt, minify)
 npx @es3d/es3d glb scene.es3d -o scene.glb       # export (also: obj, stl, step)
 npx @es3d/es3d import logo.svg -o logo.es3d      # SVG, OBJ, STL, STEP or glTF to ES3D

package/docs/SPEC.md

@@ -403,11 +403,20 @@ The title names the phase (`Parse`, `Reference`, `Geometry`, `Render`, `File`) a
 
 Unknown names get a suggestion when a known name is within a small edit distance or shares a prefix (`raduis` → `radius`, `spotlight` → `spot`, `sphear` → `sphere`).
 
+The reference reader's human-readable report (`formatDiagnostics`, and the text from `validate`) shows a repeated warning once. Warnings group when they share a code, the element name written in the message (its first `<name>`), and the same message. The report keeps the first location and then says how many times that warning occurred:
+
+```
+Reported 906 times. Showing the first.
+```
+
+Every warning remains its own entry in the diagnostic list. `validate --json` prints that list. Errors are listed one by one.
+
 ## 16. Extensibility and versioning
 
 - Elements whose names start with `x-` (and their subtrees) are vendor extensions: readers that do not understand them skip them with `W_EXTENSION`. Unknown elements without the prefix are errors, so typos are never mistaken for extensions.
 - Unknown attributes are always errors. (A future version may reserve an `x-` attribute prefix as well.)
 - `version="1.x"` documents must remain readable by version-1 readers; incompatible changes require version 2, which version-1 readers reject with `E_VERSION`.
+- A processor that rewrites a document keeps `x-` elements, and keeps any element whose id is named by a token in an `x-` attribute. The reference optimizer treats a whitespace-separated token (an optional leading `#` is ignored) as a reference when that id exists, and updates the token when it merges a duplicate material.
 
 ## 17. File names and media types
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@es3d/es3d",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "ES3D (Extensible Scalable 3D): a declarative, SVG-inspired 3D scene format with a WebGPU/WebGL2 reference renderer, editor and converter.",
   "type": "module",
   "license": "Apache-2.0",

package/scripts/es3d-cli.mjs

@@ -4,7 +4,7 @@
 //   npm run es3d -- validate scene.es3d
 //   npm run es3d -- fmt scene.es3d -o pretty.es3d
 //   npm run es3d -- stats scene.es3d
-//   npm run es3d -- glb scene.es3d --instancing -o scene.glb
+//   npm run es3d -- glb scene.es3d -o scene.glb
 //   npm run es3d -- import drawing.svg -o drawing.es3d
 //
 // Run without arguments for the full command list. Input "-" reads stdin;
@@ -13,11 +13,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import zlib from 'node:zlib';
-import { parse, detectSyntax } from '../src/format/parse.js';
+import { parse, detectSyntax, formatDiagnostics } from '../src/format/parse.js';
 import { serialize } from '../src/format/serializer.js';
 import { compile } from '../src/pipeline.js';
 import { exportOBJ } from '../src/io/obj.js';
-import { exportGLB } from '../src/io/gltf.js';
 import { exportSTL } from '../src/io/stl.js';
 import { exportSTEP } from '../src/io/step.js';
 import { detectKind, importFiles } from '../src/io/convert.js';
@@ -27,7 +26,8 @@ import { optimize, expandProcedural } from '../src/optimize/optimizer.js';
 const HELP = `es3d <command> [options] <input>
 
 Commands
-  validate   parse, validate and build the scene; print every diagnostic (exit 1 on errors)
+  validate   parse, validate and build the scene; print diagnostics (exit 1 on errors).
+             Repeated warnings are grouped; --json lists every one
   fmt        pretty-print, keeping the syntax (markup or compact)
   minify     minified markup (short attribute aliases, no comments)
   compact    convert to the compact syntax           (--min for one line)
@@ -36,7 +36,7 @@ Commands
   optimize   run the optimizer and print its report to stderr
   expand     replace <repeat>/<scatter> with explicit elements
   obj        export Wavefront OBJ (+ .mtl next to -o) (--lod <0-3>)
-  glb        export glTF binary                      (--lod <0-3>, --instancing, --quantize 16)
+  glb        packed glTF binary                     (instances, LODs, lights, cameras, animation)
   stl        export STL for 3D printing, Z-up        (--lod <0-3>, --ascii)
   step       export tessellated STEP (AP242), Z-up  (--lod <0-3>)
   import     convert SVG, OBJ (+MTL), STL, STEP or glTF (.gltf + .bin, .glb) to ES3D:
@@ -48,9 +48,9 @@ Commands
 Options
   -o, --out <file>   output file (default: stdout for text)
   --precision <n>    round numbers to n decimals when writing text
-  --lod <n>          level of detail for mesh exports (default 0 = finest)
-  --instancing       GLB: use EXT_mesh_gpu_instancing
-  --quantize         GLB: KHR_mesh_quantization (int16 positions, int8 normals)
+  --lod <n>          level of detail for obj, stl and step (default 0 = finest)
+  --instancing       glb always writes EXT_mesh_gpu_instancing
+  --quantize         glb always writes KHR_mesh_quantization
   --min / --pretty   force minified / pretty output
   --json             validate/stats: machine readable output
   --ascii            STL: write ASCII instead of binary
@@ -132,9 +132,7 @@ function write(opts, data) {
 }
 
 function report(doc) {
-  const out = [];
-  for (const d of doc.diagnostics) out.push(d.format(doc.lineIndex));
-  return out.join('\n\n');
+  return formatDiagnostics(doc);
 }
 
 /** Parse and validate, or exit with the diagnostics. */
@@ -144,7 +142,8 @@ function parsed(input) {
     process.stderr.write(report(doc) + '\n');
     process.exit(1);
   }
-  for (const w of doc.warnings || []) process.stderr.write(w.format(doc.lineIndex) + '\n\n');
+  const warnings = formatDiagnostics(doc.warnings || [], doc.lineIndex);
+  if (warnings) process.stderr.write(warnings + '\n\n');
   return doc;
 }
 
@@ -152,7 +151,7 @@ function compiled(input) {
   const r = compile(input);
   const errors = r.diagnostics.filter((d) => d.severity === 'error');
   if (errors.length) {
-    process.stderr.write(r.diagnostics.map((d) => d.format(r.doc.lineIndex)).join('\n\n') + '\n');
+    process.stderr.write(formatDiagnostics(r) + '\n');
     process.exit(1);
   }
   return r;
@@ -264,7 +263,8 @@ async function main() {
       const warnings = r.diagnostics.length - errors;
       if (opts.json) console.log(JSON.stringify({ ok: errors === 0, diagnostics: r.diagnostics.map((d) => d.toJSON()) }, null, 2));
       else {
-        if (r.diagnostics.length) process.stderr.write(r.diagnostics.map((d) => d.format(r.doc.lineIndex)).join('\n\n') + '\n\n');
+        const text = formatDiagnostics(r);
+        if (text) process.stderr.write(text + '\n\n');
         console.log(`${opts.input}: ${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'}${errors ? '' : `, ${r.scene.count.toLocaleString('en-US')} instances`}`);
       }
       process.exit(errors ? 1 : 0);
@@ -312,8 +312,21 @@ async function main() {
       break;
     }
     case 'glb': {
-      const r = compiled(es3dInput(bytes));
-      write(opts, exportGLB(r.scene, (e, l) => r.cache.mesh(e, l), { lod: opts.lod, instancing: opts.instancing, quantize: opts.quantize > 0 }));
+      let exportPackedGLB;
+      try {
+        ({ exportPackedGLB } = await import('../src/io/gltf-pack.js'));
+      } catch (e) {
+        fail(`glb could not load the packer (${e.message})`, 1);
+      }
+      const baseDir = opts.input === '-' ? '' : path.dirname(path.resolve(opts.input));
+      const sourceName = opts.input === '-' ? 'stdin' : `${path.basename(path.dirname(opts.input))}/${path.basename(opts.input)}`;
+      let file;
+      try {
+        file = await exportPackedGLB(es3dInput(bytes), { baseDir, sourceName });
+      } catch (e) {
+        fail(e.message, 1);
+      }
+      write(opts, file);
       break;
     }
     case 'stl': {

package/src/format/parse.js

@@ -86,7 +86,47 @@ export function parseStrict(input, opts = {}) {
   return doc;
 }
 
-/** Human readable report of all diagnostics. */
-export function formatDiagnostics(doc) {
-  return doc.diagnostics.map((d) => d.format(doc.lineIndex)).join('\n\n');
+/** Element name written in a message, if it has one (`<x-anchors>`). */
+function mentionedElement(message) {
+  const m = /<([^<>\s]+)>/.exec(message || '');
+  return m ? m[1] : '';
+}
+
+/**
+ * Human-readable report of diagnostics.
+ * Repeated warnings that share a code, the element name in the message, and
+ * the same message are shown once, at the first location, with a count.
+ * Errors are listed one by one. The diagnostic objects are not changed.
+ * @param {object|Array} source a document, a compile result, or a diagnostic list
+ * @param {import('./errors.js').LineIndex} [lineIndex]
+ */
+export function formatDiagnostics(source, lineIndex) {
+  if (!source) return '';
+  const list = Array.isArray(source) ? source : source.diagnostics || [];
+  const index = lineIndex || source.lineIndex || (source.doc && source.doc.lineIndex) || null;
+  const seen = new Map();
+  const items = [];
+  for (const d of list) {
+    if (!d || d.severity !== 'warning') {
+      items.push(d);
+      continue;
+    }
+    const key = `${d.code}\0${mentionedElement(d.message)}\0${d.message}`;
+    const prev = seen.get(key);
+    if (prev) {
+      prev.count++;
+      continue;
+    }
+    const slot = { d, count: 1 };
+    seen.set(key, slot);
+    items.push(slot);
+  }
+  return items
+    .map((item) => {
+      if (!item || !item.d) return item.format(index);
+      const text = item.d.format(index);
+      if (item.count < 2) return text;
+      return `${text}\n\nReported ${item.count} times. Showing the first.`;
+    })
+    .join('\n\n');
 }

package/src/index.js

@@ -1,9 +1,9 @@
 // Public API of the ES3D reference implementation.
 //
-//   import { compile, createRenderer, Camera } from '@es3d/es3d';
+//   import { compile, createRenderer, Camera, formatDiagnostics } from '@es3d/es3d';
 //
 //   const result = compile(text);              // parse + validate + build + flatten
-//   if (!result.ok) console.error(result.diagnostics.map((d) => d.format()).join('\n\n'));
+//   if (!result.ok) console.error(formatDiagnostics(result));
 //   const renderer = await createRenderer(canvas);   // WebGPU, else WebGL2
 //   renderer.setScene(result.scene, (entry, lod) => result.cache.mesh(entry, lod));
 //   const camera = new Camera().frame(result.scene.bounds);