kinescript 1.1.0__py3-none-any.whl

kinescript/docs.py

@@ -0,0 +1,345 @@
+"""The scene reference printed by `kine docs` and served to agents by the MCP server.
+
+Written for small models as well as large ones: rules first, one complete example, every default
+stated, then recipes to copy. Names of motions, eases, shaders and components are filled in from
+the code, so they cannot drift; tests/test_docs.py renders every JSON example in this text.
+"""
+from __future__ import annotations
+
+from .components import COMPONENT_DOCS
+from .ease import EASES
+from .presets import PRESETS
+from .shaders import PRESETS as SHADERS
+
+REFERENCE = """\
+KINESCRIPT SCENE REFERENCE
+A scene is one JSON object. Kinescript turns it into a video. Frame n depends only on the scene
+and n, so any frame can be rendered alone.
+
+RULES
+  1. Write strict JSON: double quotes, no comments, no trailing commas.
+  2. Every layer has a "type" and a unique "id".
+  3. Times are in seconds. Sizes are in pixels. Colours are "#rrggbb" or "#rrggbbaa".
+  4. x and y say where the layer's anchor goes. They default to 0, the TOP-LEFT corner of the
+     canvas. For the centre write "x": "50%", "y": "50%". The anchor defaults to "center".
+  5. Layers draw in list order: later layers are on top. Put backgrounds first.
+  6. A layer without "dur" or "until" stays until the scene ends. Nothing fades out unless you
+     give it an "exit", e.g. "exit": "fade".
+  7. Use only the keys listed here. `kine check` rejects unknown keys and names the right one.
+  8. After writing a scene, run `kine check scene.json` and fix every error before rendering.
+
+A COMPLETE SCENE (copy it and change it)
+{
+  "canvas": {"w": 1920, "h": 1080, "fps": 30, "bg": "#0a0c10"},
+  "layers": [
+    {"id": "bg", "type": "shader", "preset": "score", "opacity": 0.6},
+    {"id": "title", "type": "text", "text": "Launch **Day**", "x": "50%", "y": "45%", "size": 140,
+     "weight": 800, "fill": "#f2f0e8", "emph": "#ff633f", "at": 0.3, "dur": 3,
+     "split": "chars", "enter": {"name": "rise", "dur": 0.5, "stagger": 0.03}, "exit": "fade"},
+    {"id": "sub", "type": "text", "text": "October 2026", "x": "50%", "y": "60%", "size": 48,
+     "fill": "#9299a8", "at": "title.in+0.8", "until": "title.out", "enter": "fade", "exit": "fade"},
+    {"id": "bar", "type": "rect", "x": "50%", "y": "68%", "w": 320, "h": 6, "fill": "#ff633f",
+     "at": 1.2, "dur": 2, "enter": "wipe", "exit": "fade"}
+  ]
+}
+It is 3.3 s long: with canvas duration "auto", the scene ends when the last timed layer ends.
+
+SCENE (top level)
+  canvas      {"w": 1920, "h": 1080, "fps": 30, "bg": "#0a0c10", "duration": "auto"}
+              w and h 16..16384, fps 1..240. duration: seconds, or "auto" (the default: the
+              latest end of any layer). Vertical video: "w": 1080, "h": 1920.
+  layers      the list of layers.
+  theme       {"accent": "#ff633f"}: then "$accent" anywhere means that value.
+  markers     {"drop": 12.5}: named times, usable as "at": "drop".
+  grade       whole-frame look: {"contrast": 1.05, "saturate": 1.1, "vignette": 0.35, "grain": 0.05}
+  motionBlur  {"samples": 6, "shutter": 0.5}   (slower: renders 6 sub-frames per frame)
+  camera      moves and turns the view in depth (see DEPTH AND CAMERA).
+  light       how model layers are lit (see 3D MODELS).
+  audio       [{"src": "music.mp3", "at": 0, "gain": -8, "fadeIn": 1, "fadeOut": 2, "trim": [0, 30]}]
+              gain is in dB (0 = unchanged, -6 = about half as loud). fadeOut ends where the audio
+              ends: the scene end, unless trim makes the audio shorter.
+  components  your own reusable layer groups (see COMPONENTS).
+
+TIME: "at" (start), "dur" (length), "until" (end)
+  1.5               seconds
+  "45f"             frames
+  "0:02.5"          minutes:seconds
+  "title.in"        when layer "title" starts; "title.out" when it ends; "title.mid" its middle
+  "title.out+0.2"   0.2 s after title ends;  "title.in-10f" 10 frames before title starts
+  "prev.out"        when the layer listed just before this one ends
+  "drop"            a marker from "markers"
+  "until": "end"    runs to the scene end
+  "at" defaults to 0. Inside a group, times count from the group's start.
+  A video without dur lasts as long as its trimmed clip.
+
+KEYS EVERY LAYER HAS
+  id, type, at, dur, until
+  x, y          position of the anchor. A number (px), "50%" (of the canvas, or of the group's
+                w and h), "50%-120", "10vw", "5vh", or an expression.
+  anchor        center (default) | topleft | top | topright | left | right | bottomleft | bottom |
+                bottomright. Video, shader, and image without x default to topleft.
+  opacity       0..1 (default 1)
+  scale, scaleX, scaleY   1 = normal size
+  rotate        degrees, clockwise
+  z, rotateX, rotateY, backface, fixed   depth: see DEPTH AND CAMERA
+  blur          px
+  blend         normal | multiply | screen | overlay | add | lighten | darken | softLight |
+                difference | color
+  shadow        {"x": 0, "y": 6, "blur": 16, "color": "#00000099"}   (those are the defaults)
+  fx            {"brightness": 0, "contrast": 1, "saturate": 1, "hue": 0, "exposure": 0,
+                 "temperature": 0, "tint": 0, "gray": 0, "invert": 0}
+  enter, exit   a motion (see ENTER AND EXIT)
+  hidden        true skips the layer
+  allowOffscreen  true stops check warning when the layer leaves the canvas
+  note          free text, ignored
+
+LAYER TYPES (defaults in brackets)
+  rect      w [200] h [120] radius [0] fill [#f2f0e8 unless stroke is set] stroke strokeWidth [4]
+            dimOutside (0..1: darkens everything outside the rect, to highlight part of a video)
+  circle    r [50] fill stroke strokeWidth
+  ellipse   w h fill stroke strokeWidth
+  polygon   sides [6] r [80] inner (0..1 makes a star) fill stroke strokeWidth
+  line      points [[x, y], [x, y], ...] (measured from the layer's x, y) stroke strokeWidth
+            smooth closed
+  path      d (SVG path data, e.g. "M0 0 L100 0") or points; fill stroke strokeWidth
+  arrow     x1 y1 x2 y2 bend [0] head [22] stroke strokeWidth
+  text      text (centred on x, y: the anchor is center), size [64], weight [600] (100..900), font ["Space Grotesk"; also "IBM Plex Mono",
+            any installed family, or a .ttf path], italic, fill [#f2f0e8], emph (colour of
+            words written **like this**), align [center] (left|center|right), maxWidth (wraps
+            lines), lineHeight [1.18], letterSpacing [0], stroke, strokeWidth,
+            box {"fill": "#000000b0", "pad": [12, 20], "radius": 10} (a background behind the
+            text; pad is [vertical, horizontal]), case (upper|lower),
+            split (chars|words|lines: animate each unit, see ENTER AND EXIT),
+            caret (true shows a cursor while typing),
+            unitX unitY unitRotate unitScale unitOpacity (expressions per unit; i is its index)
+  counter   value (animate it, e.g. {"from": 0, "to": 1250, "dur": 2}), format ["{:,.0f}"; also
+            "${:,.2f}M" or "{:.0f}%"], and every text key
+  image     src (every src, for image, video, captions and audio, is relative to the scene
+            file), w, h (give one and the other keeps the
+            aspect), fit [cover] (cover|contain|stretch), zoom [1] (zooms inside the frame),
+            focus [[0.5, 0.5]] (the point zoom moves toward), radius, stroke, strokeWidth
+  video     src, trim [start, end] (seconds in the source file), speed [1], volume [1] (0 mutes),
+            loop, w, h [canvas size], fit, zoom, focus, radius. Its sound is mixed in.
+  captions  cues [[start, end, "text"], ...] (seconds from the layer start) or src (.srt/.vtt),
+            mode (karaoke|pop: highlight the current word), active (colour of that word), and
+            the text keys. Defaults: x "50%", y "86%", size 46, weight 700, a dark box behind.
+  shader    preset ({shaders}) with uniforms {"name": number or colour},
+            mesh and score are subtle; aurora and grid are strong, so use opacity 0.2-0.4.
+            Or sksl: your own SkSL "half4 main(float2 p) { ... return half4(r, g, b, a); }".
+            p is the pixel position (0..w, 0..h); p / iResolution is 0..1. The colour is
+            premultiplied: for a see-through colour return half4(rgb * a, a). iTime (seconds),
+            iResolution, iProgress (0..1) and your uniforms are declared for you.
+            Fills the canvas unless you give w and h.
+  model     a lit 3D solid, 3D text, an extruded SVG path or a model file: shape, src or parts
+            (see 3D MODELS).
+  group     children [layers], w, h, clip (true cuts children off at w x h), radius, fill.
+            Children are placed from the group's x, y and start at the group's "at".
+  sequence  clips [{"src": "a.mp4", "trim": [0, 4]}, ...] and transition {"type": "fade",
+            "dur": 0.4} (fade|wipe|slide|zoom|blur|cut). Becomes back-to-back video layers named
+            <id>-1, <id>-2, ... Each transition overlaps the clips it joins, so 3 s + 3 s with a
+            0.5 s fade lasts 5.5 s.
+
+DEPTH AND CAMERA (3D)
+  Any layer can move and turn in depth. x is right, y is down and z is toward the viewer, in px,
+  as in CSS. A scene that uses depth is seen through a camera; at z 0 everything keeps its size.
+  z           px toward the viewer. Near layers grow; far ones (negative z) shrink and drift less
+              when the camera moves.
+  rotateX     degrees: positive tips the top edge away.
+  rotateY     degrees: positive turns the right edge away. Past 90 you see the back, mirrored.
+  backface    visible (default) | hidden: hidden skips the layer while its back faces the camera.
+  fixed       true: a top-level layer ignores the camera's moves (captions are fixed).
+  sort        on a group: "depth" draws its children far to near each frame, not in list order.
+  camera      top level. Every key animates, and all default to 0 except fov:
+              {"x": 0, "y": 0, "z": 0, "rotateX": 0, "rotateY": 0, "rotate": 0, "fov": 40}
+              x and y pan (px). z moves the camera back; negative moves it in. rotateY orbits it
+              right around the canvas centre, rotateX up over it (looking down), rotate rolls it.
+              fov (5..150) sets how strong perspective looks; it does not change size at z 0.
+  Motions: flip turns in on the vertical axis (deg [90]), flip-up on the horizontal axis, tumble
+  spins in from depth, push comes forward from depth (dist [600]). With "split" each unit flips.
+  Layers still draw in list order, so put far layers first, or use a group with "sort": "depth".
+  A card that turns over: rotateY on the group, and each side hides its back:
+    {"id": "card", "type": "group", "x": "50%", "y": "50%", "rotateY": [[0.5, 0], [1.5, 180]], "children": [
+     {"id": "card-front", "type": "group", "anchor": "center", "w": 560, "h": 150, "radius": 28,
+      "fill": "#f2f0e8", "backface": "hidden", "children": [
+      {"id": "card-front-text", "type": "text", "text": "front", "size": 64, "fill": "#0a0c10"}]},
+     {"id": "card-back", "type": "group", "anchor": "center", "w": 560, "h": 150, "radius": 28,
+      "fill": "#ff633f", "rotateY": 180, "backface": "hidden", "children": [
+      {"id": "card-back-text", "type": "text", "text": "back", "size": 64, "fill": "#0a0c10"}]}]}
+  A whole scene: the camera pushes in and swings round layers at three depths; the note stays put:
+    {"canvas": {"w": 1920, "h": 1080, "fps": 30, "duration": 4},
+     "camera": {"z": [[0, 300], ["end", -100]], "rotateY": [[0, -12], ["end", 10]]},
+     "layers": [
+      {"id": "far", "type": "rect", "x": "50%", "y": "50%", "z": -600, "w": 1600, "h": 900, "radius": 40,
+       "fill": "#151922"},
+      {"id": "title", "type": "text", "text": "Depth", "x": "50%", "y": "45%", "size": 140, "weight": 800,
+       "split": "chars", "enter": {"name": "flip", "stagger": 0.05}},
+      {"id": "near", "type": "circle", "x": "78%", "y": "72%", "z": 250, "r": 60, "fill": "#ff633f"},
+      {"id": "note", "type": "text", "text": "fixed to the screen", "x": "50%", "y": "88%", "size": 40,
+       "fixed": true}]}
+
+3D MODELS
+  A model layer is a lit solid in the space of DEPTH AND CAMERA, so z, rotateX, rotateY, rotate,
+  scale and the camera apply to it. x and y place its centre.
+  shape     cube (w [200], h and depth [= w]) | sphere (r [100]) | cylinder (r [80], h [200]) |
+            cone (r [90], h [200], tip up) | torus (r [110], tube [r x 0.35], facing you) |
+            plane (w, h; both sides show) | text | path. Sizes are px and animate.
+  text      shape "text" pushes letters out in depth: text ("\n" breaks lines), size [120],
+            weight [600], font, italic, letterSpacing, lineHeight, depth [size x 0.2], bevel [0]
+            (px of 45-degree edge). Centred on x, y. Each new text, size, depth or bevel value
+            rebuilds the solid, so grow it with scale.
+  path      shape "path": d (SVG path data, filled nonzero), w and/or h (fits inside them, keeping
+            its shape), depth [a fifth of its larger side], bevel [0], strokeWidth (in d's units:
+            extrudes the stroke, with round ends, for line icons).
+  detail    low | medium (default) | high: how many triangles. A medium sphere has about 2,200.
+  fill      one colour [theme accent]   shine 0..1 [0.4]   metal 0..1 [0]   rim 0..1 [0.5] (edge
+            light)   bands [0] (2 or more: flat toon steps). These animate.
+  parts     [{"shape": "sphere", "r": 30, "x": 0, "y": -120, "z": 0, "rotateX": 0, "rotateY": 0,
+            "rotate": 0, "scale": 1, "fill": "#b9f45d", "shine": 0.9}, ...] placed from the
+            model's centre, in plain numbers (parts do not animate; the model does). A part takes
+            the model's material keys it does not set. A model may have shape (or src), parts, or both.
+  src       a model file: .glb or .gltf (glTF 2.0), or .obj with its .mtl. Colours, shine and metal
+            come from the file; a fill on the layer recolours all of it. It fits inside w and/or h
+            keeping its shape, else its longest side is 300 px. Node transforms apply; animation,
+            skins and textures do not (a texture gives its mean colour). Long triangles are cut to
+            1/24 of its size for the depth sort. Draco- or meshopt-compressed files are not read.
+  ground    true or {"opacity": 0.5, "blur": px, "y": px}: a soft shadow on a level floor under the
+            model, as if lit from above, fainter as the model rises. The floor sits at the model's
+            lowest point before it turns, or at y in the layer's parent space (canvas px at the top
+            level): give y when the model moves up and down.
+  explode   0..1: faces fly out along their normals.
+  draw      0..1, or "enter": "build": triangles appear from the bottom up.
+  light     top level, or on one model: studio (default) | soft | dramatic | flat (no shading),
+            or {"preset": "studio", "key": 0.85, "fill": 0.25, "ambient": 0.22, "rim": 0.35,
+            "from": "topleft", "color": "#fff4e6"}. from: topleft | top | topright | left | right |
+            front | bottomleft | bottom | bottomright. Lights move with the camera.
+  Triangles are sorted far to near within one model, so things that touch or pass through each
+  other go in one model as parts. Where two surfaces cut through each other the seam is stepped,
+  so let parts touch rather than cross. Separate layers draw in list order. check warns past
+  60,000 triangles in a frame.
+  A ring around a ball that builds in, turns, and flies apart:
+    {"id": "emblem", "type": "model", "x": "50%", "y": "45%", "detail": "high",
+     "rotateX": [[0, 64], ["end", 18]], "rotateY": [[0, -30], ["end", 70]],
+     "enter": {"name": "build", "dur": 1.6}, "explode": [[3, 0], ["end", 1]],
+     "parts": [{"shape": "torus", "r": 250, "tube": 70, "fill": "#ff633f", "metal": 0.45, "shine": 0.7},
+               {"shape": "sphere", "r": 100, "fill": "#b9f45d", "shine": 0.9}]}
+  A 3D title that builds in, turns, and settles:
+    {"id": "title3d", "type": "model", "shape": "text", "text": "LAUNCH", "x": "50%", "y": "50%",
+     "size": 240, "weight": 800, "depth": 70, "bevel": 5, "shine": 0.6,
+     "rotateY": [[0, -40], [2.4, 0, "outCubic"]], "rotateX": [[0, 18], [2.4, 0, "outCubic"]],
+     "enter": {"name": "build", "dur": 1.2}}
+  A product turntable from a model file, on a soft floor shadow:
+    {"id": "product", "type": "model", "src": "rocket.glb", "x": "50%", "y": "46%", "h": 600,
+     "rotateY": [[0, 0], ["end", 360]], "ground": true, "enter": {"name": "build", "dur": 1.6}}
+
+ANIMATING A VALUE (any number or colour key)
+  constant     "x": 960
+  tween        "opacity": {"from": 0, "to": 1, "dur": 0.6, "delay": 0, "ease": "outCubic"}
+               (those are the defaults; delay counts from the layer start)
+  keyframes    "x": [[0, 200], [0.8, 960, "outBack"], ["end", 1700]]
+               Each keyframe is [time, value] or [time, value, ease into it]. Time is seconds from
+               the layer start; a negative time counts back from its end; "40%" is a share of its
+               length; "end" is its end. Between keyframes the default ease is inOutCubic.
+               A flat list such as [0, 100] is NOT keyframes.
+  expression   "y": "=540 + sin(t * 3) * 40"   (a string starting with "=")
+               t = seconds since the layer started   d = the layer's length   p = t / d (0..1)
+               T = seconds since the scene started   i = unit index (split text)   W, H, fps
+               helpers: sin cos tan sqrt abs min max round floor ceil exp log atan2 hypot pi tau
+                        clamp(v, lo, hi)  lerp(a, b, p)  noise(x, seed)  wiggle(freq, amp, t, seed)
+                        ease("outCubic", p)
+  Colours animate too: "fill": {"from": "#ff633f", "to": "#b9f45d", "dur": 1}.
+  Gradient fill: "fill": {"linear": [[0, 0], [1, 1]], "stops": ["#ff633f", "#7b5cff"]}
+                 or {"radial": [0.5, 0.5, 0.6], "stops": [...]}; points are 0..1 of the layer box.
+
+ENTER AND EXIT
+  "enter": "rise"   or   {"name": "rise", "dur": 0.5, "ease": "outCubic", "stagger": 0.03}
+  Defaults: dur 0.5, ease outCubic (pop and spin: outBack; type: linear; draw: inOutCubic;
+  snap: outQuart). An exit plays during the LAST dur seconds of the layer and ends with it.
+  Combine with +: "rise+blur". Options: dist (px moved by rise, drop, left, right; default 48),
+  from (start scale of pop [0.4] and zoom [1.25]), amount (blur px [24], track px [40]).
+  With "split" on text, each unit enters in turn: unit k starts k x stagger seconds after the
+  layer starts, so the whole reveal takes dur + (units - 1) x stagger.
+  motions: {motions}
+  rise moves up into place, drop moves down, left moves left, right moves right. type is a
+  typewriter. draw draws a stroke or path on, and builds a model (build is the same). wipe reveals left to right. snap is a hard cut in
+  with a small settle. flip, flip-up, tumble and push move in depth (see DEPTH AND CAMERA).
+  none is no motion.
+
+EASES  {eases}, spring, spring(stiffness, damping), bezier(x1, y1, x2, y2), steps(n)
+  in* starts slow, out* ends slow (the most natural for entrances), inOut* does both.
+
+COMPONENTS  {"use": "<name>", "id": "...", "at": ..., "dur": ..., ...parameters}
+  Built in (parameters):
+{components}
+  x and y place the component as noted above. Components also accept enter, exit, opacity,
+  scale, rotate, hidden.
+  Your own: "components": {"badge": {"params": {"label": "NEW"}, "layers": [
+              {"type": "text", "text": "{{label}}", "size": 40}]}}
+  then a layer {"use": "badge", "label": "BETA", "x": 200, "y": 100}.
+
+RECIPES (layers to paste into "layers")
+  Title that types on:
+    {"id": "hello", "type": "text", "text": "Hello world", "x": "50%", "y": "50%", "size": 120,
+     "enter": {"name": "type", "dur": 1.2}, "caret": true}
+  Words one after another, each replacing the last, centred at x, y:
+    {"use": "kinetic", "id": "words", "words": ["Write", "Check", "Render"], "every": 0.6}
+  Pill label:
+    {"id": "pill", "type": "text", "text": "NEW", "x": "50%", "y": "50%", "size": 40,
+     "fill": "#0a0c10", "box": {"fill": "#b9f45d", "pad": [10, 24], "radius": 999}}
+  Bar of a bar chart growing up from a baseline at y 900, with its value riding on top and its
+  label under the baseline. The value's y uses the same tween as the bar's height (same dur,
+  same default ease), so it stays 40 px above the bar. The label is anchored at its top edge,
+  20 px below the baseline. Keep text off the bar: light text over the orange fails the
+  contrast check:
+    {"id": "bar1", "type": "rect", "x": 600, "y": 900, "anchor": "bottom", "w": 120,
+     "h": {"from": 0, "to": 400, "dur": 0.8}, "fill": "#ff633f", "at": 0.5}
+    {"id": "bar1-value", "type": "counter", "x": 600, "y": {"from": 860, "to": 460, "dur": 0.8},
+     "size": 48, "at": 0.5, "value": {"from": 0, "to": 80, "dur": 0.8}, "format": "{:.0f}"}
+    {"id": "bar1-label", "type": "text", "text": "Q1", "x": 600, "y": 920, "anchor": "top",
+     "size": 40, "at": 0.5}
+  Slow zoom on a photo (Ken Burns):
+    {"id": "photo", "type": "image", "src": "photo.jpg", "w": 1920, "h": 1080, "anchor": "topleft",
+     "zoom": [[0, 1], ["end", 1.15, "linear"]], "focus": [0.6, 0.4]}
+  Two clips with a crossfade:
+    {"id": "cut", "type": "sequence", "clips": [{"src": "a.mp4", "trim": [0, 4]},
+     {"src": "b.mp4", "trim": [2, 6]}], "transition": {"type": "fade", "dur": 0.5}}
+  Full-screen gradient background:
+    {"id": "bg", "type": "rect", "x": 0, "y": 0, "anchor": "topleft", "w": "100%", "h": "100%",
+     "fill": {"linear": [[0, 0], [1, 1]], "stops": ["#1e3a8a", "#6d28d9"]}}
+  Progress bar along the bottom for the whole video:
+    {"use": "progress", "id": "progress", "color": "#ff633f", "h": 8}
+  Music under everything: top-level "audio": [{"src": "music.mp3", "gain": -10, "fadeIn": 1, "fadeOut": 2}]
+
+COMMANDS
+  kine new scene.json             write a starter scene
+  kine check scene.json           JSON list of problems. error: must fix. warning: should fix:
+                                  text off the canvas or inside the outer 5% (safe-area),
+                                  overlapping text, contrast under 3:1, or text shown for less
+                                  than about 0.4 s + 0.3 s per word (read-time).
+                                  info: a name it read for you, e.g. "'color' read as 'fill'".
+  kine look scene.json --boxes    one PNG of 12 evenly spaced frames; --boxes outlines layers and
+                                  labels the top-level ones; -n 16 frames, --at 1 2.5 4 exact
+                                  times (use it to see a transition), --width 480, --cols 4, -o
+  kine still scene.json --at 2.5  one frame as PNG (-o to name it); --at -1 is 1 s before the
+                                  end; --at end is the last frame
+  kine probe scene.json --at 2    every layer's start and end, and screen boxes at 2 s
+  kine probe clip.mp4             a media file's duration, w, h, fps and whether it has audio
+  kine render scene.json -o out.mp4 -q draft|standard|high
+                                  standard is the default, draft the fastest, high the best.
+                                  Also .mov or .webm (with --transparent for no background),
+                                  .gif (longest side 720 px, 15 fps), or a folder/ for PNG frames.
+                                  --scale 0.5 halves the size; --from 2 --to 4 renders a part.
+  kine watch scene.json           re-makes the contact sheet on every save
+  kine doctor                     checks ffmpeg, the GPU and fonts
+  kine mcp                        the same tools for MCP clients
+
+WORKFLOW FOR AGENTS
+  1. Write the scene.   2. kine check: fix every error, read the warnings, run it again.
+  3. kine look --boxes, and look at the image.   4. kine render -q draft, then the final render.
+"""
+
+
+def reference() -> str:
+    comps = "\n".join(f"    {k:<11}{v}" for k, v in COMPONENT_DOCS.items())
+    eases = " ".join(sorted(k for k in EASES if k not in ("in", "out", "inOut")))
+    return (REFERENCE.replace("{motions}", " ".join(sorted(PRESETS)))
+            .replace("{shaders}", "|".join(SHADERS)).replace("{components}", comps).replace("{eases}", eases))

kinescript/ease.py

@@ -0,0 +1,143 @@
+"""Easing curves. Every curve maps [0,1] -> roughly [0,1] (back/elastic overshoot)."""
+from __future__ import annotations
+
+import math
+import re
+from functools import lru_cache
+from typing import Callable
+
+Ease = Callable[[float], float]
+
+
+def _out(f: Ease) -> Ease:
+    return lambda t: 1.0 - f(1.0 - t)
+
+
+def _inout(f: Ease) -> Ease:
+    return lambda t: f(2 * t) / 2 if t < 0.5 else 1 - f(2 - 2 * t) / 2
+
+
+def _back(t: float, s: float = 1.70158) -> float:
+    return t * t * ((s + 1) * t - s)
+
+
+def _elastic(t: float) -> float:
+    if t in (0.0, 1.0):
+        return t
+    return -(2 ** (10 * t - 10)) * math.sin((t * 10 - 10.75) * (2 * math.pi) / 3)
+
+
+def _bounce_out(t: float) -> float:
+    n, d = 7.5625, 2.75
+    if t < 1 / d:
+        return n * t * t
+    if t < 2 / d:
+        t -= 1.5 / d
+        return n * t * t + 0.75
+    if t < 2.5 / d:
+        t -= 2.25 / d
+        return n * t * t + 0.9375
+    t -= 2.625 / d
+    return n * t * t + 0.984375
+
+
+_BASE: dict[str, Ease] = {
+    "sine": lambda t: 1 - math.cos(t * math.pi / 2),
+    "quad": lambda t: t * t,
+    "cubic": lambda t: t ** 3,
+    "quart": lambda t: t ** 4,
+    "quint": lambda t: t ** 5,
+    "expo": lambda t: 0.0 if t == 0 else 2 ** (10 * t - 10),
+    "circ": lambda t: 1 - math.sqrt(max(0.0, 1 - t * t)),
+    "back": _back,
+    "elastic": _elastic,
+    "bounce": lambda t: 1 - _bounce_out(1 - t),
+}
+
+EASES: dict[str, Ease] = {"linear": lambda t: t, "hold": lambda t: 0.0 if t < 1 else 1.0}
+for _n, _f in _BASE.items():
+    _c = _n.capitalize()
+    EASES["in" + _c] = _f
+    EASES["out" + _c] = _out(_f)
+    EASES["inOut" + _c] = _inout(_f)
+# Short aliases agents reach for first.
+EASES.update({"in": EASES["inCubic"], "out": EASES["outCubic"], "inOut": EASES["inOutCubic"],
+              "smooth": lambda t: t * t * (3 - 2 * t)})
+
+
+def _bezier(x1: float, y1: float, x2: float, y2: float) -> Ease:
+    def sample(a1: float, a2: float, u: float) -> float:
+        return 3 * a1 * u * (1 - u) ** 2 + 3 * a2 * u * u * (1 - u) + u ** 3
+
+    def f(x: float) -> float:
+        lo, hi = 0.0, 1.0
+        for _ in range(24):
+            mid = (lo + hi) / 2
+            if sample(x1, x2, mid) < x:
+                lo = mid
+            else:
+                hi = mid
+        return sample(y1, y2, (lo + hi) / 2)
+    return f
+
+
+def _spring(stiffness: float = 170, damping: float = 26, mass: float = 1) -> Ease:
+    """Critically/under-damped spring normalised so it settles at t=1."""
+    w0 = math.sqrt(stiffness / mass)
+    zeta = damping / (2 * math.sqrt(stiffness * mass))
+    span = max(0.3, -math.log(0.001) / max(zeta * w0, 1e-3))
+
+    def raw(t: float) -> float:
+        s = t * span
+        if zeta < 1:
+            wd = w0 * math.sqrt(1 - zeta * zeta)
+            return 1 - math.exp(-zeta * w0 * s) * (math.cos(wd * s) + zeta * w0 / wd * math.sin(wd * s))
+        return 1 - math.exp(-w0 * s) * (1 + w0 * s)
+
+    end = raw(1.0)
+    # Spread the residual so the curve lands exactly on 1 and the last frame does not jump.
+    return lambda t: 1.0 if t >= 1 else raw(t) + (1 - end) * t
+
+
+@lru_cache(maxsize=256)
+def get(name: str | None) -> Ease:
+    """Resolve an ease by name: 'outCubic', 'spring', 'spring(120,12)', 'bezier(.2,.8,.2,1)', 'steps(4)'."""
+    if not name:
+        return EASES["outCubic"]
+    if name in EASES:
+        return EASES[name]
+    m = re.fullmatch(r"(\w+)\(([^)]*)\)", name.replace(" ", ""))
+    if m:
+        kind, args = m.group(1), [float(a) for a in m.group(2).split(",") if a]
+        if kind in ("bezier", "cubicBezier") and len(args) == 4:
+            return _bezier(*args)
+        if kind == "spring":
+            return _spring(*args)
+        if kind == "steps" and args:
+            n = max(1, int(args[0]))
+            return lambda t: min(1.0, math.floor(t * n) / n) if t < 1 else 1.0
+    if name == "spring":
+        return _spring()
+    c = canonical(name)
+    if c:
+        return get(c)
+    from .schema import unknown
+    raise ValueError(unknown("ease", name, list(EASES) + ["spring"]) + ", spring(k,d), bezier(a,b,c,d), steps(n)")
+
+
+CSS = {"ease": "inOutSine", "easein": "inCubic", "easeout": "outCubic", "easeinout": "inOutCubic",
+       "linear": "linear", "cubicbezier": "bezier"}
+
+
+def canonical(name: str) -> str | None:
+    """'easeOutCubic', 'ease-out-cubic', 'EaseInOut', CSS 'ease-in' -> Kinescript names; None when nothing fits."""
+    s = re.sub(r"[-_ ]", "", str(name)).lower()
+    m = re.fullmatch(r"(\w+?)(\(.*\))", s)
+    if m and m.group(1) in ("cubicbezier", "bezier", "spring", "steps"):
+        return ("bezier" if "bezier" in m.group(1) else m.group(1)) + m.group(2)
+    if s in CSS:
+        return CSS[s]
+    if s.startswith("ease"):
+        s = s[4:]
+    low = {k.lower(): k for k in EASES}
+    return low.get(s)

kinescript/fonts/IBMPlexMono-OFL.txt

@@ -0,0 +1,93 @@
+Copyright © 2017 IBM Corp. with Reserved Font Name "Plex"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.