RubyGems - vizcore - Versions diffs - 1.0.0 → 1.1.0 - Mend

vizcore 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

checksums.yaml +4 -4
data/README.md +66 -648
data/docs/assets/playground-worker.js +373 -0
data/docs/assets/playground.css +440 -0
data/docs/assets/playground.js +652 -0
data/docs/index.html +2 -1
data/docs/playground.html +81 -0
data/docs/shape_dsl.md +269 -0
data/frontend/index.html +26 -0
data/frontend/src/custom-shape-param-controls.js +106 -0
data/frontend/src/main.js +268 -0
data/frontend/src/mapping-target-selector.js +109 -0
data/frontend/src/renderer/engine.js +10 -1
data/frontend/src/renderer/layer-manager.js +18 -4
data/frontend/src/shape-editor-controls.js +157 -0
data/frontend/src/visuals/geometry.js +425 -27
data/frontend/src/visuals/shape-renderer.js +475 -0
data/frontend/src/visuals/svg-arc.js +104 -0
data/lib/vizcore/cli/dsl_reference.rb +1 -1
data/lib/vizcore/cli/scene_validator.rb +92 -0
data/lib/vizcore/dsl/layer_builder.rb +795 -7
data/lib/vizcore/dsl/mapping_resolver.rb +158 -4
data/lib/vizcore/layer_catalog.rb +4 -2
data/lib/vizcore/renderer/scene_frame_source.rb +14 -1
data/lib/vizcore/renderer/snapshot_renderer.rb +507 -15
data/lib/vizcore/server/frame_broadcaster.rb +53 -4
data/lib/vizcore/server/runner.rb +21 -0
data/lib/vizcore/shape.rb +719 -0
data/lib/vizcore/version.rb +1 -1
data/lib/vizcore.rb +1 -0
data/sig/vizcore.rbs +100 -1
metadata +12 -1

data/docs/playground.html ADDED Viewed

@@ -0,0 +1,81 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <meta name="description" content="Vizcore Ruby wasm playground for editing Ruby scene DSL and previewing audio-reactive visuals in the browser." />
+  <meta name="theme-color" content="#08110f" />
+  <link rel="canonical" href="https://ydah.github.io/vizcore/playground.html" />
+  <meta property="og:type" content="website" />
+  <meta property="og:title" content="Vizcore Playground" />
+  <meta property="og:description" content="Edit Vizcore Ruby DSL and preview audio-reactive scenes in the browser." />
+  <meta property="og:url" content="https://ydah.github.io/vizcore/playground.html" />
+  <meta property="og:image" content="https://ydah.github.io/vizcore/assets/vizcore-poster.png" />
+  <title>Vizcore Playground</title>
+  <link rel="stylesheet" href="assets/playground.css" />
+</head>
+<body>
+  <a class="skip-link" href="#editor">Skip to editor</a>
+  <header class="topbar" aria-label="Playground header">
+    <a class="brand" href="index.html">Vizcore</a>
+    <nav class="topbar-nav" aria-label="Playground navigation">
+      <a href="index.html">Home</a>
+      <a href="https://github.com/ydah/vizcore">GitHub</a>
+    </nav>
+  </header>
+  <main class="playground-shell">
+    <section class="editor-panel" aria-labelledby="editor-title">
+      <div class="panel-header">
+        <div>
+          <p class="eyebrow">Ruby wasm</p>
+          <h1 id="editor-title">Playground</h1>
+        </div>
+        <div class="toolbar">
+          <label class="preset-label" for="preset-select">Preset</label>
+          <select id="preset-select" class="preset-select"></select>
+          <button id="run-button" class="button primary" type="button">Run</button>
+          <button id="reset-button" class="button secondary" type="button">Reset</button>
+        </div>
+      </div>
+      <textarea id="editor" class="code-editor" spellcheck="false" autocomplete="off" autocapitalize="off"></textarea>
+      <div class="output-row">
+        <div class="status-line" aria-live="polite">
+          <span id="ruby-status">Ruby wasm idle</span>
+          <span id="compile-status">Waiting</span>
+        </div>
+        <details class="json-output">
+          <summary>Scene JSON</summary>
+          <pre id="json-output">{}</pre>
+        </details>
+      </div>
+    </section>
+    <section class="preview-panel" aria-labelledby="preview-title">
+      <div class="preview-header">
+        <div>
+          <p class="eyebrow">Canvas preview</p>
+          <h2 id="preview-title">Output</h2>
+        </div>
+        <div id="scene-tabs" class="scene-tabs" aria-label="Scenes"></div>
+      </div>
+      <div class="canvas-wrap">
+        <canvas id="preview-canvas" width="1280" height="720" aria-label="Vizcore visual preview"></canvas>
+        <div class="preview-meter" aria-live="polite">
+          <span id="scene-stat">Scene: --</span>
+          <span id="audio-stat">Amplitude: --</span>
+          <span id="beat-stat">Beat: --</span>
+        </div>
+      </div>
+      <div id="error-output" class="error-output" role="alert" hidden></div>
+    </section>
+  </main>
+  <script type="module" src="assets/playground.js"></script>
+</body>
+</html>

data/docs/shape_dsl.md ADDED Viewed

@@ -0,0 +1,269 @@
+# Vizcore Shape DSL
+Vizcore shape layers can declare 2D vector primitives directly in Ruby. Calling a
+shape primitive inside a layer automatically marks that layer as `type: :shape`.
+```ruby
+Vizcore.define do
+  scene :logo do
+    layer :badge do
+      rect :panel, width: 360, height: 160, radius: 24 do
+        fill "#111827"
+        stroke width: 2, color: "#38bdf8"
+        opacity 0.8
+      end
+      star :spark, points: 5, radius: 72, inner_radius: 28 do
+        translate x: 180, y: 0
+        map beat_pulse, to: :scale, range: 0.8..1.4
+      end
+    end
+  end
+end
+```
+## Primitives
+Supported primitives:
+- `circle id = nil, x: 0, y: 0, radius: 100, count: 1, segments: 96`
+- `line id = nil, x1: -100, y1: 0, x2: 100, y2: 0`
+- `rect id = nil, x: 0, y: 0, width:, height:, radius: 0`
+- `polygon id = nil, points: [[x, y], ...], closed: true`
+- `polyline id = nil, points: [[x, y], ...]`
+- `path id = nil, detail: 32, tolerance: nil, max_segments: 4096 do ... end`
+- `bezier id = nil, from:, control:, to:` for quadratic curves
+- `bezier id = nil, from:, c1:, c2:, to:` for cubic curves
+- `star id = nil, points: 5, radius: 100, inner_radius: 50`
+- `custom_shape name_or_class, **params`
+`draw do ... end` may be used to group declarations for readability.
+`group do ... end` applies shared style and transform to child primitives.
+## Path Commands
+Path blocks support an SVG-like command subset:
+```ruby
+path :blob, detail: 48 do
+  move_to 0, 120
+  line_to 120, 0
+  quad_to 80, -100, 0, -120
+  cubic_to -80, -100, -120, 80, 0, 120
+  close
+end
+```
+Commands are serialized as `M`, `L`, `Q`, `C`, `H`, `V`, `A`, and `Z`. The
+Canvas2D renderer draws `arc_to` as an SVG-style elliptical arc, and the line
+fallback/snapshot renderer flattens curves and arcs to line segments.
+`detail` controls the default curve/arc subdivision count. When `tolerance` is
+provided, quadratic and cubic curves use adaptive flattening instead. `max_segments`
+caps the number of flattened line segments per path; the DSL raises when the
+estimated flattened path would exceed that budget.
+## Style And Transform
+Inside a shape block, these methods target the shape rather than the layer:
+```ruby
+fill "#f472b6"
+stroke 2
+stroke width: 3, color: "#ffffff"
+blend :add
+opacity 0.75
+translate x: 100, y: 40
+translate 100, 40
+rotate 30
+scale 1.2
+scale x: 1.4, y: 0.8
+origin x: 0, y: 0
+```
+The transform order is origin adjustment, scale, rotate, then translate.
+## Groups
+Groups are flattened into child primitives during DSL evaluation. Child shapes
+inherit style values they do not set themselves, and group opacity is multiplied
+with child opacity.
+```ruby
+group :spinner do
+  translate x: 0, y: 80
+  rotate 15
+  scale 1.2
+  opacity 0.75
+  stroke width: 2, color: "#38bdf8"
+  12.times do |index|
+    rect width: 12, height: 80 do
+      translate x: 0, y: 160
+      rotate index * 30
+    end
+  end
+end
+```
+## Mapping
+Mappings declared inside a shape block are scoped to that shape:
+```ruby
+circle :ring, radius: 120 do
+  map bass, to: :radius, range: 80..240
+  map beat_pulse, to: :scale, range: 1.0..1.4
+  map high, to: :opacity, range: 0.2..1.0
+end
+```
+Transform aliases:
+- `:translate_x` -> `transform.translate.x`
+- `:translate_y` -> `transform.translate.y`
+- `:rotate` and `:rotation` -> `transform.rotate`
+- `:scale` -> `transform.scale`
+- `:scale_x` -> `transform.scale.x`
+- `:scale_y` -> `transform.scale.y`
+- `:origin_x` -> `transform.origin.x`
+- `:origin_y` -> `transform.origin.y`
+You can also map to a named shape from the layer scope:
+```ruby
+rect :panel, width: 360, height: 160
+map bass, to: shape(:panel).rotate, range: -12..12
+```
+Mappings inside a static `custom_shape` block are applied to each primitive
+generated by that custom shape:
+```ruby
+custom_shape :badge, radius: 120 do
+  fill "#22d3ee"
+  map beat_pulse, to: :scale, range: 0.8..1.2
+end
+```
+## Custom Shapes
+Custom shapes are registered in Ruby and expanded into regular shape
+primitives before the browser receives the scene.
+```ruby
+class DiamondShape
+  include Vizcore::Shape
+  param :radius, default: 100, min: 10, max: 400
+  def draw(ctx)
+    radius = ctx.param(:radius)
+    ctx.polygon points: [
+      [0, radius],
+      [radius, 0],
+      [0, -radius],
+      [-radius, 0]
+    ]
+  end
+end
+Vizcore.register_shape :diamond, DiamondShape
+```
+Use the registered shape from a layer:
+```ruby
+layer :generated_logo do
+  custom_shape :diamond, radius: 140 do
+    rotate 45
+    stroke width: 2, color: "#ffffff"
+  end
+end
+```
+Block registration is supported for small generators:
+```ruby
+Vizcore.register_shape :spark do |ctx|
+  ctx.star points: 5, radius: ctx.param(:radius, 80), inner_radius: 32
+end
+```
+`draw(ctx)` may return a primitive hash, an array of primitive hashes, or build
+primitives with `ctx.draw`, `ctx.circle`, `ctx.rect`, `ctx.path`, and the other
+shape methods. Values declared with `param` are validated against their
+`min`/`max` metadata before `draw(ctx)` runs, and dynamic custom shape
+descriptors include the same schema for editor tooling.
+By default, custom shapes are expanded when the DSL is evaluated. Use
+`dynamic: true` when the generator needs mapped params, `ctx.time`, `ctx.frame`,
+or `ctx.audio` at runtime:
+```ruby
+custom_shape :orbit, count: 32, radius: 260, dynamic: true do
+  fill "#22d3ee"
+  map bass, to: :radius, range: 120..280
+  map beat_pulse, to: :scale, range: 0.8..1.2
+end
+```
+Inside a dynamic custom shape block, mappings to custom params such as `:radius`
+are applied before `draw(ctx)` runs. Transform aliases such as `:scale` and
+`:rotate` are applied to the generated primitives after expansion.
+Use `static: true` for generators that are independent of runtime context. Static
+custom shapes with identical renderer, params, layer context, palette, and
+resolution reuse a cached expansion, while each call still receives its own copy
+of the generated primitives.
+## Coordinates
+New shape schema layers use center-origin logical coordinates by default:
+- `x` increases to the right.
+- `y` increases upward.
+- `x: 0, y: 0` is the center of the canvas.
+Legacy `circle` and `line` layers without `shape_schema_version: 2` keep the old
+coordinate heuristic for compatibility with existing examples.
+Set `units :ndc` on the layer to use normalized device coordinates directly.
+## Validation
+The DSL raises early for malformed primitives:
+- duplicate shape IDs within a layer
+- negative `radius`, `inner_radius`, `width`, `height`, or `stroke_width`
+- `polygon` with fewer than 3 points
+- `polyline` with fewer than 2 points
+- `path` without commands
+- `path` whose estimated flattened segment count exceeds `max_segments`
+- unknown `custom_shape`
+- custom shapes that return unsupported primitive kinds
+`vizcore validate` also emits warnings for shape payloads that are renderable but
+likely surprising: unsupported primitive kinds in raw `params[:shapes]`, fills
+that line fallback will ignore, opacity values outside `0..1`, and zero or very
+large scale values that will collapse or clamp.
+## Renderer Notes
+The browser renderer uses a Canvas2D shape backend composited through the
+existing WebGL layer pipeline. It supports fill, stroke color/width, opacity,
+dash, line caps/joins, transforms, and logical/ndc coordinates for the shape
+schema.
+If Canvas2D is unavailable, the browser falls back to the existing line renderer.
+That fallback ignores fill and only approximates stroke geometry. The software
+snapshot renderer also uses line flattening.
+The browser HUD includes local shape editor controls for resolved shape layers:
+primitive kind, translate, rotate, scale, opacity, fill, stroke color, and stroke
+width can be adjusted in the running view without mutating the source DSL file.
+Dynamic custom shape params with `param` metadata are also exposed as HUD
+controls; changing one sends a runtime override to the server so the Ruby custom
+shape is re-expanded on the next frame. The HUD also lists valid mapping target
+paths for layer params, primitive params/transforms, and custom shape params.

data/frontend/index.html CHANGED Viewed

@@ -409,6 +409,29 @@
       text-align: right;
     }
+    .shader-param-controls details {
+      margin-top: 0.35rem;
+      padding-top: 0.3rem;
+      border-top: 1px solid rgba(153, 195, 255, 0.12);
+    }
+    .shader-param-controls summary {
+      cursor: pointer;
+      color: #d9e8ff;
+      font-size: 0.78rem;
+      font-weight: 700;
+    }
+    .shader-param-controls select,
+    .shader-param-controls input[type="color"] {
+      width: 100%;
+      min-height: 1.65rem;
+      border: 1px solid rgba(153, 195, 255, 0.28);
+      border-radius: 0.35rem;
+      background: rgba(2, 6, 14, 0.72);
+      color: var(--fg);
+    }
     @media (max-width: 520px) {
       .hud {
         right: 1rem;
@@ -507,6 +530,9 @@
         </div>
       </div>
       <div id="shader-param-controls" class="shader-param-controls" hidden aria-label="Shader parameter controls"></div>
+      <div id="shape-editor-controls" class="shader-param-controls" hidden aria-label="Shape editor controls"></div>
+      <div id="custom-shape-param-controls" class="shader-param-controls" hidden aria-label="Custom shape parameter controls"></div>
+      <div id="mapping-target-selector" class="shader-param-controls" hidden aria-label="Mapping target selector"></div>
       <div id="scene-switcher" class="scene-switcher" hidden aria-label="Scene switcher"></div>
       <button id="audio-toggle" type="button" hidden>Play Audio</button>
     </section>

data/frontend/src/custom-shape-param-controls.js ADDED Viewed

@@ -0,0 +1,106 @@
+export const customShapeParamControlEntries = (layers, overrides = {}) => {
+  const entries = [];
+  const layerList = Array.isArray(layers) ? layers : [];
+  layerList.forEach((layer, layerIndex) => {
+    const controls = Array.isArray(layer?.params?.custom_shape_controls) ? layer.params.custom_shape_controls : [];
+    if (!controls.length) return;
+    const layerKey = layerControlKey(layer, layerIndex);
+    const layerName = String(layer?.name || `layer_${layerIndex + 1}`);
+    controls.forEach((control, controlIndex) => {
+      const customShapeIndex = finiteIndex(control?.index, controlIndex);
+      const customShapeName = String(control?.name || `custom_shape_${customShapeIndex + 1}`);
+      const params = control?.params && typeof control.params === "object" ? control.params : {};
+      const schemaByName = paramSchemaByName(control?.param_schema);
+      const paramNames = [...new Set([...Object.keys(schemaByName), ...Object.keys(params)])].sort();
+      paramNames.forEach((paramName) => {
+        const schema = schemaByName[paramName] || {};
+        const baseValue = finiteNumber(params[paramName], finiteNumber(schema.default, 0));
+        const min = finiteNumber(schema.min, Math.min(0, baseValue));
+        const fallbackMax = Math.max(min + 1, Math.abs(baseValue) * 2, 1);
+        const max = Math.max(min, finiteNumber(schema.max, fallbackMax));
+        const step = positiveNumber(schema.step, Math.max((max - min) / 100, 0.01));
+        const value = finiteNumber(overrides?.[layerKey]?.[customShapeIndex]?.[paramName], baseValue);
+        entries.push({
+          key: `${layerKey}:custom_shapes.${customShapeIndex}.params.${paramName}`,
+          layerKey,
+          layerName,
+          customShapeIndex,
+          customShapeName,
+          paramName,
+          label: `${layerName}.${customShapeName}.${paramName}`,
+          target: `custom_shapes.${customShapeIndex}.params.${paramName}`,
+          min,
+          max,
+          step,
+          value: clamp(value, min, max),
+        });
+      });
+    });
+  });
+  return entries;
+};
+export const pruneCustomShapeParamOverrides = (overrides = {}, entries = []) => {
+  const validKeys = new Set(entries.map((entry) => `${entry.layerKey}:${entry.customShapeIndex}:${entry.paramName}`));
+  const next = {};
+  Object.entries(overrides || {}).forEach(([layerKey, controls]) => {
+    if (!controls || typeof controls !== "object") return;
+    Object.entries(controls).forEach(([customShapeIndex, params]) => {
+      if (!params || typeof params !== "object") return;
+      Object.entries(params).forEach(([paramName, value]) => {
+        if (!validKeys.has(`${layerKey}:${customShapeIndex}:${paramName}`) || !Number.isFinite(Number(value))) return;
+        next[layerKey] ||= {};
+        next[layerKey][customShapeIndex] ||= {};
+        next[layerKey][customShapeIndex][paramName] = Number(value);
+      });
+    });
+  });
+  return next;
+};
+export const customShapeParamMessage = (entry, value) => ({
+  layer: entry.layerName,
+  custom_shape_index: entry.customShapeIndex,
+  param: entry.paramName,
+  value: clamp(finiteNumber(value, entry.value), entry.min, entry.max),
+});
+const layerControlKey = (layer, index) => `${index}:${String(layer?.name || "layer")}`;
+const paramSchemaByName = (schema) => {
+  const output = {};
+  (Array.isArray(schema) ? schema : []).forEach((entry) => {
+    const name = String(entry?.name || "").trim();
+    if (!name) return;
+    output[name] = entry;
+  });
+  return output;
+};
+const finiteIndex = (value, fallback) => {
+  const numeric = Number(value);
+  return Number.isInteger(numeric) && numeric >= 0 ? numeric : fallback;
+};
+const finiteNumber = (value, fallback) => {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+};
+const positiveNumber = (value, fallback) => {
+  const numeric = finiteNumber(value, fallback);
+  return numeric > 0 ? numeric : fallback;
+};
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);