linejig 0.0.0-stage → 0.2.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.
@@ -0,0 +1,119 @@
1
+ # Motion rules
2
+
3
+ Built in three.js 0.160.0 with Line2 / LineSegments2 fat lines, pinned, with an import map (the line addons import
4
+ the bare name `three`). No AI image or video generation for the drawing or its motion.
5
+
6
+ ## Principles
7
+
8
+ - **Motion means something.** Each move is what the real object does (a needle settles, a lid lifts, a key turns,
9
+ an instrument swings) or what a camera does (push, pull, pan). One idea per move.
10
+ - **It lands once.** The illustration builds on entry, makes its move, and holds.
11
+ - **Two clocks,** after Hairline:
12
+ - *Tween* for discrete moves: 700 ms on `cubic-bezier(.32,.72,0,1)`. Retarget from where it is, never from the
13
+ start. Stagger related parts by 60 to 200 ms.
14
+ - *Spring* for physical settling: k 100, c 18, integrated per frame. Hairline's m 1 is critically damped
15
+ (overshoot about 0.1°, invisible); use m 2 for a visible overshoot of about 5° on a 60° swing. It overshoots a little and settles,
16
+ which suits needles, balances and swinging parts. Use it only where the real object would overshoot.
17
+ - **Camera zoom** interpolates scale logarithmically and the centre linearly.
18
+
19
+ ## Moves
20
+
21
+ | Move | How | Timing |
22
+ |---|---|---|
23
+ | Draw-on | each line's visible segment count grows from 0; order segments left to right on screen; dashed lines fade in instead | each line 700 ms on the tween curve, line starts spread 500 ms first to last, so about 1200 ms in all (the kernel's values) |
24
+ | Arrival | start at scale 0.96 and settle while fading up | 700 ms tween |
25
+ | Part move (lid lifts, key turns) | after draw-on reaches about 70% | 700 ms tween, parts staggered |
26
+ | Settle (needle, beam) | spring from an offset (e.g. −60°) to rest | spring; lands in about 1.2 to 1.6 s |
27
+ | Idle | a degree or two of drift over a minute | never noticeable as motion |
28
+ | Camera push or pan | lerp the view | 1250 to 1400 ms, cubic in-out |
29
+
30
+ ## Intro types (the user chooses)
31
+
32
+ The intro is selectable, not fixed. Ask the user which one they want, or offer two to compare. In code it is one
33
+ setting, `INTRO`, which a `?intro=` URL parameter overrides, so they can be compared side by side. Each one ends on
34
+ the same finished drawing, then the hero makes its move.
35
+
36
+ No dead time: drag, zoom and reset work from the first frame, and from the first frame a hover on the hero or a press
37
+ cuts the hero's own move short (a hero that has not arrived yet answers as soon as it is on screen). The figure goes
38
+ live at once (`onLive` runs then, once), the parts still in flight keep landing (the stack, or the draw-on, plays to its
39
+ end, with `K.stacking` true until it does), and its state eases from the intro's pose into the live one over 400 ms, so
40
+ `state()` need not match its intro and live branches. Untouched, the intro plays to `liveAt` as before.
41
+
42
+ | Intro | What happens | Status |
43
+ |---|---|---|
44
+ | `draw` | each line draws on, left to right across the screen | built (the compass, the starter) |
45
+ | `stack` | the object is assembled in ordered layers, and each part arrives along the axis it mounts on: parts on a top face drop from above, parts on a front face slide in from the front (a camera's windows and lens rings, ring after ring, back to front), parts on a side come from that side (a compass's pivot pins). Each layer carries a `from` vector, the outward normal of the face it attaches to, travels about 15 to 25% of the object's size on the 700 ms tween, already drawn, staggered about 120 to 180 ms; about 1.6 to 2 s in all; no bounce on parts, the spring is for the hero only; nothing passes through anything on its way in | built (the compass, the camera, the starter) |
46
+
47
+ ### Planning the stack for each illustration
48
+
49
+ The stack is not one generic animation. Work it out for each object from how that kind of object is really put
50
+ together, before you write any code, and write the plan down as an assembly table:
51
+
52
+ | Layer | Parts | Mounts on | `from` |
53
+ |---|---|---|---|
54
+
55
+ 1. **Name the object's type** and how such things are assembled. Use real assembly order, not screen order.
56
+ 2. **Find the base,** the part everything else is fixed to (a body, a foot, a floor, a chassis). It comes first,
57
+ from above or rising from its footprint.
58
+ 3. **Give every other part its mounting face** on a part that is already there, and its `from` vector, the outward
59
+ normal of that face. A part arrives only after the part it mounts on.
60
+ 4. **Stack along each axis in order.** Coaxial parts go innermost first (lens mount, then the focus ring, then the
61
+ front ring). Nested parts go outer frame first, then what it holds (a gimbal ring, then the bowl in it).
62
+ 5. **The hero comes last,** then makes its own move.
63
+
64
+ Patterns by type:
65
+
66
+ | Type | Base | Typical order and directions |
67
+ |---|---|---|
68
+ | Camera or front-facing device (camera, radio, phone) | body | body from above → top plate from above → front windows and panels from the front → the optics ring by ring along their axis, from the front → top controls from above |
69
+ | Instrument on a stand (compass, theodolite, telescope, globe) | foot or tripod | foot → uprights from above → pivots sideways along the pivot axis → the ring or cradle from above → the instrument from above → the hero (needle, telescope) |
70
+ | Container (safe, chest, box, drawer unit) | carcass | carcass → trays or drawers sliding in from the front → hinges from the side → lid from above → lock or key from the front |
71
+ | Building or stepped structure (stepwell, tower, stair) | ground slab | courses bottom to top, each from above; openings and doors from the front |
72
+ | Mechanism (balance, clock, gear train, lever) | frame | frame → axles along their own axis → parts threaded onto the axles from the axle's end → the beam, hands or pointer last |
73
+ | Vehicle or wheeled thing | chassis | chassis → wheels sideways along the axle → body from above → fittings from their faces |
74
+
75
+ If an object fits none of these, reason it out from steps 1 to 5. If the plan has a part arriving through
76
+ another part, or before what it mounts on, the plan is wrong. Fix the plan, not the timing.
77
+
78
+ More ideas to try later, each still one plain move:
79
+
80
+ - `extrude`: every footprint is drawn flat on the ground first, then all the solids rise to their heights together.
81
+ - `assemble`: the parts start pulled apart along their own axes (an exploded view) and slide together.
82
+ - `blueprint`: dashed construction lines and axes appear first, then the solids form on them, then the guides fade.
83
+ - `sweep`: a plane passes across the object and leaves the finished drawing behind it.
84
+
85
+ Before adding one, check it fits the object (stack suits things built in layers, like a stepwell or a chest of
86
+ trays; assemble suits mechanisms) and it doesn't compete with the hero's move.
87
+
88
+ ## Hand-overs (when several illustrations share a page or deck)
89
+
90
+ - Default: the outgoing drawing fades over about 450 ms while the incoming one arrives.
91
+ - Related objects can hand over in one move (a surveyor's theodolite pulls back and slides left while a map grows
92
+ from the point it was sighting).
93
+ - Only the outgoing and incoming drawings exist. Hide and stop every other one at once.
94
+ - Going backwards, the drawing is simply there in its final state.
95
+
96
+ ## Scrub (scroll stories)
97
+
98
+ A host can drive a figure's progress instead of its clock: one object that assembles, then opens, as the page
99
+ scrolls. `fig.scrub(t, { open, split })` (or embedded `{type: 'scrub', t, split?, open?}`, or `?intro=scrub` to start
100
+ at 0) maps t in [0, 1] onto the stack intro, parts arriving in ASSEMBLY order, for 0 to `split` (default 0.75), and
101
+ onto the hero's click, from rest to its `opened` state, for `split` to 1. While scrubbing the figure plays no intro
102
+ and no motion of its own and takes no hover; `scrub(null)` hands it back and replays. The figure needs nothing new:
103
+ a good ASSEMBLY order and an `opened` state are the whole story.
104
+
105
+ - One step of text per moment; give each step the t it shows when its text reaches the middle of the screen. The
106
+ last step is t = 1, the opened state.
107
+ - The host eases t toward the scroll (a fifth of the gap a frame); with reduced motion it sets t directly. The
108
+ figure's own reduced-motion rule does not apply: the reader is moving it.
109
+ - Examples: site/stories/espresso.html and suitcase.html, with site/stories/story.js.
110
+
111
+ ## Reduced motion
112
+
113
+ With `prefers-reduced-motion: reduce` or `?reduced=1`: no moves, no draw-on; the final state appears at once (a
114
+ 250 ms fade at most).
115
+
116
+ ## Capture hook
117
+
118
+ `?freeze=MS` stops the clock MS after the start. Under headless Chrome drive frames with `setTimeout` (about every
119
+ 50 ms) while frozen; virtual time runs timers more reliably than animation frames.
@@ -0,0 +1,33 @@
1
+ # Style: line art
2
+
3
+ Every figure from this skill is drawn in **line art**: white and black only, the grey ramp, `hi` for the hero, no
4
+ colour, no glow and no text. It is the kernel's default (`style: 'lineart'`; the old name `line` still works), so a
5
+ figure needs no setting for it.
6
+
7
+ The Brand style (the hero as a solid part in a brand colour, with a soft halo and short engraved labels) and the Dots
8
+ style (the drawing as a halftone dot matrix) come with Linejig Pro, a separate skill, `linejig-pro`
9
+ (https://linejig.com/pricing). If it is installed, read it for those styles; if not, draw in line art and do not
10
+ set `style`, `brand` or `dots` on a figure.
11
+
12
+ ## Which part is the hero
13
+
14
+ The hero is **the part the message is about**. Usually that is the control you act on, not the thing that responds,
15
+ when the two are different parts. But when the message is about the contents, the contents are the hero: the empty
16
+ inbox's letter, not the envelope's flap, even though you open the flap. On the camera the shutter button is the hero
17
+ and the lens answers it. Glass, openings and the centre of a part (a lens's glass, a magnifier's glass, a window)
18
+ stay the plate colour, so they read as clear. Most objects have one part that is both (a needle, a drawer, a key),
19
+ and then it is simply that part. The hero takes `hi`, the brightest tone; everything else steps down the ramp.
20
+
21
+ ## Floor grid
22
+
23
+ `grid: true` (or `?grid=1`, `{type: 'grid', value: true}`) lays a square grid on the ground (z 0) under the object,
24
+ about 2.2 times its footprint, cells about an eighth of it on a 1-2-5 step. Thin `lo` lines fade to nothing by
25
+ distance and before the plate's edges, and the grid turns with the object. It fades in over 400 ms before the intro.
26
+ Off by default.
27
+
28
+
29
+ ## Rules
30
+
31
+ - One hero (or one family), and the hero is where the eye goes: the brightest tone.
32
+ - No colour, no glow, no text, no logos, companies, products or people.
33
+ - Reduced motion: the final state at once.
@@ -0,0 +1,37 @@
1
+ # Verify
2
+
3
+ ## Capture frozen frames
4
+
5
+ ES modules from a CDN work from `file://`, but if the page loads other local files, serve it:
6
+
7
+ ```sh
8
+ python3 -m http.server 5391 --bind 127.0.0.1 & # from the folder holding the page
9
+ "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new --hide-scrollbars \
10
+ --window-size=1440,900 --virtual-time-budget=8000 --enable-logging=stderr --v=0 \
11
+ --screenshot=/ABS/PATH/f-0700.png \
12
+ "http://127.0.0.1:5391/index.html?freeze=700" 2>&1 | grep -i "CONSOLE"
13
+ kill %1
14
+ ```
15
+
16
+ - Capture the start, middle and end of each move (for example `freeze=300`, `900`, `1600`) and the settled state
17
+ (`freeze=4000`), plus `?reduced=1`.
18
+ - Capture at desktop width in both palettes (`--force-dark-mode`, or a `?theme=light|dark` hook on the page).
19
+ - Capture the click state with `?click=ID@MS` (the hero member's hit id, clicked at MS; it works under `?freeze`).
20
+ - Under the kernel, frames are driven by timers while `?freeze` is set and the hand never turns on, so drive hover
21
+ and drag checks in the browser pane, not headless.
22
+ - **Blank frozen frames** in headless Chrome: create the renderer with `preserveDrawingBuffer: true` when
23
+ `?freeze` is set, and render once more in a final `requestAnimationFrame`. The kernel does both. A frame PNG of
24
+ only a few KB is blank; check before judging it.
25
+ - Headless Chrome will not size a window below about 500 px wide. Check phone width (375 × 812) in the browser pane
26
+ with a viewport resize instead.
27
+ - Any `Uncaught` line in the console output is a failure. Ignore Chrome's own `cv_display_link` noise.
28
+
29
+ ## Look for
30
+
31
+ - Lines all the same width, including at phone size and on high-density screens.
32
+ - One `hi` part only, and the tone ramp reading clearly: `hi` > `edge` > `mid` > `lo` (measure on real pixels).
33
+ - No part smaller than about 4% of the drawing's width; no stray detail.
34
+ - Near parts hiding far ones cleanly, with no lines showing through fills and no z-fighting on edges.
35
+ - The object inside the plate at every frame of the move.
36
+ - No text anywhere in the illustration.
37
+ - No horizontal scroll at 375 px.
@@ -0,0 +1,65 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width,initial-scale=1">
6
+ <title>Linejig starter</title>
7
+ <!-- A minimal figure on the Linejig kernel: a plinth, a block and a lid (the hero). Hover the lid and it lifts a
8
+ little; click it and it opens, holds, and closes, posting the 'compose' action as it reaches open.
9
+ Copy this into site/<id>/index.html and replace the model, the ASSEMBLY table and HERO. The kernel
10
+ (linejig.js; its header documents the whole API) does the camera, fit, palette and styles, the
11
+ tween and spring, both intros, orbit, zoom, hit testing, reduced motion, ?freeze capture, the embed contract,
12
+ the action event and ?mode=turntable.
13
+ Paths: it imports the published kernel from https://linejig.com/kernel/ (keep the import map: the
14
+ kernel imports 'three' and 'three/addons/'). Inside the Linejig source repo, a figure in site/<id>/ may import
15
+ ../kernel/linejig.js instead. Brand and Dots (Linejig Pro) load from linejig-pro.js by themselves. -->
16
+ <script type="importmap">
17
+ { "imports": { "three": "https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.module.min.js",
18
+ "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/" } }
19
+ </script>
20
+ <link rel="stylesheet" href="https://linejig.com/kernel/linejig.css">
21
+ </head>
22
+ <body>
23
+ <main><div id="plate" role="img" aria-label="A placeholder figure: a block whose lid lifts"></div></main>
24
+ <script type="module">
25
+ import { createFigure } from 'https://linejig.com/kernel/linejig.js';
26
+
27
+ // ASSEMBLY: the stack intro's plan, one row per layer, in arrival order (motion.md, "Planning the stack"). Name the
28
+ // type, find the base, give every part the face it mounts on and that face's normal as from; the hero comes last and
29
+ // its row says hero: true. Placeholder type: a stepped structure on a plinth, so everything comes from above.
30
+ const UP = [0, 0, 1];
31
+ const ASSEMBLY = [
32
+ { name: 'plinth', parts: 'the plinth', mountsOn: null, from: UP },
33
+ { name: 'block', parts: 'the block', mountsOn: 'plinth', from: UP },
34
+ { name: 'lid', parts: 'the lid (the hero)', mountsOn: 'block', from: UP, hero: true },
35
+ ];
36
+ const LIFT = 14, HOVER = 0.2, OPEN = 1, HOLD = 600; // lid travel in world units; its rest, hover and open levels
37
+
38
+ let lid, openAt = -Infinity;
39
+ createFigure({
40
+ id: 'starter', ASSEMBLY, stack: { travel: 22 }, // travel: about 18% of the plinth's width
41
+ center: [0, 0, 15], release: 1200, liveAt: 2600,
42
+ fit: { width: 0.7, points: () => [[-60, -45, -10], [60, 45, -10], [60, -45, 0], [-60, 45, 0], [0, 0, 36 + LIFT]] }, // the most extreme pose
43
+ model(K) { // far parts first; K.layer files what follows under an ASSEMBLY row
44
+ K.layer('plinth'); K.solid(K.FZ, K.box(-60, -45, 60, 45, 12, 2.2), -10, 0);
45
+ K.layer('block'); K.solid(K.FZ, K.box(-36, -26, 36, 26, 8), 0, 30);
46
+ K.layer('lid', { bucket: 'lid' }); // its own bucket, so it moves by offset with no rebuild
47
+ K.hit('lid', K.solid(K.FZ, K.box(-38, -28, 38, 28, 9), 30, 36, 'hi')); // the one hi part; its silhouette is the hit area
48
+ },
49
+ state(K) { // the pose this frame; step springs here
50
+ lid = lid || K.spring(0);
51
+ if (K.live) { if (K.t - openAt > HOLD && lid.t === OPEN) lid.t = 0; K.step(lid, K.dt); }
52
+ return { lift: K.live ? lid.x : K.REDUCED ? 0 : K.springAt(0.6, 0, K.ht - 1200) }; // intro: it drops shut
53
+ },
54
+ key: () => '', // nothing in the model changes, so it never rebuilds for the pose
55
+ place: (K, bucket, st) => ({ off: [0, 0, LIFT * st.lift] }),
56
+ onReplay() { lid.x = lid.t = lid.v = 0; openAt = -Infinity; },
57
+ HERO: {
58
+ action: 'compose', opened: (st) => st.lift > 0.9 * OPEN, // hands off to the host page as the lid reaches open
59
+ onHover() { if (lid.t !== OPEN) lid.t = HOVER; }, onLeave() { if (lid.t !== OPEN) lid.t = 0; },
60
+ onClick(id, p, K) { lid.t = OPEN; openAt = K.t; },
61
+ },
62
+ });
63
+ </script>
64
+ </body>
65
+ </html>