run
Run JavaScript inside the user's SVG Lab editor, in one call. One run can build a whole screen or illustration. The code is the body of an async function: use await, loops, helper functions and data, and return a JSON value. It gets sl: await sl.op(name, args) runs one SVG Lab operation and returns its result, and throws on failure with the reason, so the script stops like normal code; await sl.try(name, args) is the same but returns {ok:false, message} instead of throwing; sl.log(...) and console.log are returned in logs; sl.ids(receipt) reads editable ids; creators return shape_ids and handle while retaining old fields. Pass a receipt or group id as shape_ids/target_ids; explicit ids take precedence over ambient artboard. sl.define(name, source) stores your function with the project for later sl.helpers[name](args) calls; its source closes over sl in the same sandbox. sl.batch(items) chunks creations. sl.glow, terrain, stars, crescent and reflection return editable assemblies with your style; sl.chartScale(domain, range) maps custom data. docs {recipe:'helpers'} gives their contracts. sl.artboard is the artboard passed to run ({id, name, x, y, width, height}) or null. With artboard, operations that take an artboard use it when you leave it out, and their coordinates are local to it (0,0 is its top-left). Operations: create_shape, create_shapes, create_text, create_path, pencil, edit_path, simplify_path, smooth_path, boolean_op, offset_path, transform, align, distribute, align_to_artboard, set_style, set_stroke, set_gradient, set_filter, set_pattern, clip_shapes, clip_to_artboard, text_on_path, set_text, duplicate, group, ungroup, name_group, reorder, resize, fit_to_box, fit_to_children, repeat, mirror, flip, scatter, add_texture, create_icon, create_layout, update_layout, design_tokens, define_styles, list_design_styles, measure_text, list_fonts, list_components, list_layouts, list_shapes, describe_document, inspect_path, inspect_layout, check_contrast, check_contacts, optical_center, snap_to_grid, normalize_spacing, normalize_radii, resolve_overflow, create_figure, create_limb, create_hand, create_line_of_action, create_organic, form_lines, add_artboard, set_artboard, list_artboards, set_active_artboard, fit_artboard, delete_shapes, make_symbol, place_symbol, list_symbols, detach_symbol, set_locked, define_helper, list_helpers, bind_slot. docs {op} gives any operation's arguments; docs {ops:[...]} reads several together; docs {query} searches operations and guides. The script has no network, DOM or storage: photos go in with place_image, the user's files with upload_asset. Limits: 40 seconds, 2,000 operations, 60,000 characters. Reply: result (your return value), ops, created_ids, changed_ids, warnings from the engine, logs, duration_ms. If it fails: error {message, op, line}; everything done before the error stays on the canvas and created_ids lists what this run made, so delete_shapes them or carry on. Quick arguments (? = optional; artboard defaults to run.artboard): create_shapes {shapes:[], artboard?}; set_gradient {shape_ids:[], type:linear|radial, stops:[]}; transform {shape_ids:[], dx?, dy?, scale?, rotate?}; set_style {shape_ids:[], fill?, stroke?, opacity?}; set_text {shape_ids:[], content?, font_size?, font_family?, font_weight?}; update_layout {layout_id, patches?:[], root?, x?, y?, width?, height?}; create_layout {artboard?, x?, y?, width?, height?, root}; scatter {region, count, item, seed?, artboard?, name?}; reorder {shape_ids:[], mode:front|back|forward|backward|behind|in_front_of}; group {shape_ids?:[], artboard?, name?}; create_icon {icon, x, y, size?, artboard?, name?}; repeat {shape_ids:[], mode?:linear|grid|radial, count, gap?, columns?, artboard?, radius?, rotate?}; design_tokens {preset?:light|dark, set?:{}}; clip_shapes {target_ids:[], clip_id}; list_shapes {artboard?}; duplicate {shape_ids:[]}; set_filter {shape_ids:[]}; boolean_op {op:union|subtract|intersect|exclude, shape_ids:[]}; create_figure {view:side|front|three_quarter, joints:{}, name?, artboard?}; create_path {name?, style?:{}, opacity?, artboard?, points:[], closed?}; measure_text {opacity?, content, font_size?, font_family?, font_weight?}; add_artboard {width?, height?, x?, y?, name?}; create_text {name?, style?:{}, opacity?, artboard?, content, x, y, font_size?, font_family?, font_weight?}; set_artboard {artboard?, width?, height?, x?, y?, name?}; clip_to_artboard {artboard?, shape_ids?:[]}. create_shapes items: {type:"shape",kind:"rect",x,y,width,height,style} or {type:"text",content,x,y,font_family,font_size,style}; style uses fill, stroke, stroke_width, opacity. create_path points: {x,y,hin?:{x,y},hout?:{x,y}}. Gradient stops: {offset:0..1,color}. docs {ops:[...]} has full schemas.
