JsonCutDocs

Custom DOM, Canvas and WebGL blocks

Add expert visuals without turning the complete project into opaque JavaScript.

Use a custom block for a procedural background, data visualization or 3D visual that ordinary layers cannot express. Its geometry, timing, opacity and transitions still live on a normal custom layer, so Studio can position and animate the result.

Rendered output

Generative border study

A procedural visual remains one bounded layer inside an otherwise ordinary editable project.

Video1920 × 108010 secondsEditable V2 source

Layer and block

<div id="network-field" data-jc-clip data-jc-kind="custom"
  data-jc-name="Network field" data-jc-start="0" data-jc-duration="10"
  data-jc-track="1"
  style="left:0;top:0;width:1920px;height:1080px"></div>
{
  "customBlocks": [
    {
      "layerId": "network-field",
      "adapter": "canvas-2d",
      "html": "<canvas></canvas>",
      "css": "canvas{display:block;width:100%;height:100%}",
      "javascript": "const canvas=document.querySelector('canvas'); const context=canvas.getContext('2d'); const {width,height}=jsoncut; canvas.width=width; canvas.height=height; jsoncut.onFrame((milliseconds)=>{ const time=milliseconds/1000; context.clearRect(0,0,width,height); context.fillStyle=jsoncut.inputs.color; context.beginPath(); context.arc(width/2+Math.sin(time)*180,height/2,120,0,Math.PI*2); context.fill(); });",
      "inputs": { "color": "#ff9418" }
    }
  ]
}

Adapters are dom, svg, canvas-2d and webgl. The block receives project-controlled time, dimensions and declared inputs. Network access, storage, workers, navigation and parent-document access are blocked. Every custom layer needs exactly one customBlocks entry with a matching layerId, and inputs must hold plain JSON values.

javascript runs once to initialize the block. Register jsoncut.onFrame(callback) to draw directly at each requested time: its argument is clip-local milliseconds. jsoncut.time is clip-local seconds, jsoncut.frame is the local frame index at jsoncut.fps (the project frame rate). Calculate the complete visual state from time so scrubbing backwards produces the same result. Do not accumulate counters per callback.

The legacy source field instead runs a frame function with an api object. That object is not available in javascript; do not mix the two modes. A custom block stays one selectable layer: its internal drawing is not automatically split into editable Studio text or shape layers. Keep primary text in ordinary text layers.

Libraries

A block can use these self-hosted libraries. Use the global in javascript; the block records the library and its version (libraries: [{ "id": "d3", "version": "7.9.0" }]) and always loads exactly that version, so a block renders the same after later updates.

GlobalLibraryUse it for
THREEthree.js 0.186.1Real 3D: objects, cameras, lights, materials (adapter webgl)
d3D3 7.9.0Charts with many or exact values, custom chart types, map projections
topojsonTopoJSON client 3.1.0Turning TopoJSON into GeoJSON for D3 or three.js
worldAtlasWorld Atlas 2.0.2Natural Earth countries (countries110m) and land (land110m)
roughRough.js 4.6.6A hand-drawn look: sketchy lines, circles, arrows and hatching
katexKaTeX 0.19.0Formulas typeset from TeX, with KaTeX's fonts embedded
PIXIPixiJS 8.22.0Thousands of 2D sprites and particles (adapter webgl)
const svg = d3.select('#surface');
const x = d3.scaleLinear([0, jsoncut.inputs.values.length - 1], [40, jsoncut.width - 40]);
const y = d3.scaleLinear([0, d3.max(jsoncut.inputs.values)], [jsoncut.height - 40, 40]);
const path = svg.append('path').attr('fill', 'none').attr('stroke', jsoncut.inputs.color).attr('stroke-width', 6)
  .attr('d', d3.line((value, index) => x(index), y)(jsoncut.inputs.values));
const length = path.node().getTotalLength();
jsoncut.onFrame((ms) => {
  const t = jsoncut.ease('ease-out', Math.min(1, ms / 2500));
  path.attr('stroke-dasharray', `${length * t} ${length}`);
});

The script may use await while it sets up: the layer counts as ready when it is done (PixiJS: await app.init({ canvas: document.getElementById('surface'), autoStart: false, preserveDrawingBuffer: true }), then app.render() in onFrame). Draw from jsoncut.onFrame and never from a library's own clock or transitions: each frame is computed from time. jsoncut.ease(name, t) uses the same easings as keyframes (ease-out, back-out, cubic-bezier(…) …). For three.js, create the renderer with preserveDrawingBuffer: true and call renderer.render inside onFrame. MCP clients list versions and examples with jsoncut_get_primitive_catalog (kind: "libraries").

Timeline libraries such as GSAP, Anime.js or Motion are not available: native keyframes, motion programs and transitions do that work and stay editable. A Lottie animation is media, not code: see Lottie animations.

Keep ordinary concerns outside the code:

  • use layer CSS for position and size;
  • use data-jc-animation for editable motion;
  • use normal transitions for clip changes;
  • expose user-editable settings as block inputs;
  • prefer ordinary text, media, vector and group layers whenever possible.

Ready-made parametric graphics

Studio's shared Library and MCP expose the same recipes. Search for animated counter, draw a path or build the graph, then inspect the exact properties before inserting:

Library IDEditable controlsLayer model
component.animated-counterStart/end number, decimals, suffix, color and secondsNative title + Canvas number
component.path-draw-followerBend, stroke, marker, color and secondsNative title + Canvas path/follower
component.staggered-graphNode count, color and secondsNative title + Canvas graph

Select the graphic layer in Studio to adjust its custom inputs. The inner drawing is not a set of native shape layers. Repeated forward/backward seeks derive the same state directly from clip-local time.