Skip to content

armgit / viz3d

Public Imported from GitHub
0

An AI agent skill that turns any subject into a 3D film or app

Add action shorts, asset sources and the self-review loop

Nguyen Xuan An7025efbf0a28
diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/examples/agent-office.md b/plugins/visualize-in-3d/skills/visualize-in-3d/examples/agent-office.md
index 4738905..26a15ac 100644
--- a/plugins/visualize-in-3d/skills/visualize-in-3d/examples/agent-office.md
+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/examples/agent-office.md
@@ -1,2 +1,2 @@
Your folder: {{WORK_DIR}}/viz-agent-office (create it). Port 5422.
-Subject: an AI agents office, the "workers" of a desktop app called Orglet (by CodePawl), shown as a little isometric office where each AI agent is a character. Before designing, read what Orglet really does from its public repository, https://github.com/codepawl/orglet (read only: its README files and docs), and show only real features and concepts from it (for example agents, tasks, tools, approvals, if that is what the docs say). Sites are teams or workspaces. The world: desks, rooms such as a research corner, a coding room, a review room and a mailroom; agent characters walk between rooms carrying task cards; a manager desk where tasks arrive; approval stations where a human signs off. Data: agents (name, role, current task, tool in use, tokens spent), tasks with stages, approvals waiting. Stages, each with its own camera: task arrives at the manager desk, an agent picks it up, research, coding, review, approval signed by a human. KPIs that fit the real product. Characters are original simple chunky low-poly figures, not any existing character. If something you would like to show is not in Orglet's docs, leave it out and list it in your report.
+Subject: an AI agents office, a team of AI agents working through tasks, shown as a little isometric office where each AI agent is a character. Show only features and concepts an agent platform really has (agents, tasks, tools, approvals). Sites are teams or workspaces. The world: desks, rooms such as a research corner, a coding room, a review room and a mailroom; agent characters walk between rooms carrying task cards; a manager desk where tasks arrive; approval stations where a human signs off. Data: agents (name, role, current task, tool in use, tokens spent), tasks with stages, approvals waiting. Stages, each with its own camera: task arrives at the manager desk, an agent picks it up, research, coding, review, approval signed by a human. KPIs that fit such a platform (tasks done, approvals waiting, tokens spent). Characters are original simple chunky low-poly figures, not any existing character.
diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/action.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/action.md
new file mode 100644
index 0000000..b265a80
--- /dev/null
+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/action.md
@@ -0,0 +1,115 @@
+# Action film mode
+
+Use this mode for a short film where characters, creatures, vehicles or machines act. Examples: a fight, a chase,
+a race, a match, a rescue, a launch, a crash, an animal hunting. It works in any look from `looks.md`. The rules
+below came from a duel between two original creatures in the pixel diorama look and hold for any cast and action.
+
+Reading map: Action sheet, Pass 1 (cast, rig, stage), Pass 2 (beats, effects, camera), Faults seen, Sound. Pass 2
+ends with the loop in `self-review.md`.
+
+## Action sheet
+
+Write `notes/actions.md` before any code. It is the action version of the topic file.
+
+- For each actor, list the 4 to 6 actions the audience knows it by. Name each action and say what it looks like:
+ what comes out of where, its colour and shape, the pose and the sound. Take them from the real source:
+ - footage and rules for real sports, animals and vehicles
+ - incident reports for real events
+ - the source material, when the user asks for a known character.
+- Viewers want the real moves at full strength. Generic punches, puffs and balls of colour read as fake.
+- Give each beat an action and an answer. Each beat changes who has the upper hand.
+
+## Pass 1: cast, rig, stage
+
+- Models: follow the order in `asset-sources.md`. A ready model with its own animation clips beats a hand-built
+ one for a character people know.
+- List every clip with its duration in `notes/models.md`. Render a grid of poses per clip and choose clips by
+ looking, not by name. A model with a skeleton and no clips is posed bone by bone on a keyframe table. A vehicle
+ or machine gets its moving parts as separate nodes.
+- Set every clip from the film clock with `AnimationMixer.setTime`, never by a delta. Then any frame renders the
+ same in any order.
+- Change a model's colours in the shader or a copy of its material made once. Never tint a shared material at
+ runtime (see Faults seen).
+- Stage: relief and props that fit the place, and real light from a key light with shadows plus a fill. Every
+ surface has the same detail level as the actors. In the pixel look that means the same pixel scale.
+- Pass 1 report: stills from the film's camera angles, the clip grid, each actor at film scale. Each actor is at
+ least 40 pixels tall (low-res pixels in the pixel look) in the main framing.
+
+## Pass 2: beats, effects, camera
+
+A shape that worked for a duel:
+
+1. Entrance with each actor's signature intro.
+2. An opening attack and a dodge.
+3. A defence that answers it.
+4. A counter, then an aerial or fast strike, then the special move.
+5. A climax where both forces meet and push back and forth.
+6. The outcome in clear view, then the camera pushing in on the winner.
+
+A chase, a race or a launch keeps the same idea: a setup, rising exchanges, one peak, and an ending you can see.
+
+Choreography:
+
+- Each side shows off before anyone attacks. In a duel both actors get a display beat (a roar, a stomp, a
+ flourish), then a short pause, then the first attack.
+- A display aims forward and up at about 45 degrees, braced. A straight-up 90 degree blast looks odd. Aim it away
+ from the opponent so it reads as a display.
+- Opponents face each other. Each frame, every actor eases its body toward the other's current position. The
+ exceptions are a move that aims elsewhere and an exit.
+- Every landed physical hit moves the target: knockback, a stagger or a fall, then a heavy recovery. A target that
+ stands still under a hit looks fake.
+- Reactions never repeat. Give a long move on one target a sequence: brace, defend, push back, break free. Never
+ play one shake loop again.
+- The world reacts to every contact. A rock breaks under a landing and a pillar chips when hit. A skid pushes
+ pebbles aside, and water splashes. List every contact with its time before the review; a heavy body landing on a
+ rock that does nothing is the commonest miss.
+- Only the target reacts to a hit. A flash or tint on the attacker is a bug.
+- Every special move gets its own cast. It has a wind-up pose and a charge that builds. Then the effect grows
+ from its source to the target. An effect that pops into place at full size reads as cheap.
+
+Effects must look heavy and dangerous:
+
+- Beams, jets, flames and exhaust have an opaque core with a white-hot centre and saturated outer layers. Fire
+ goes white, yellow, orange, red. Water goes white, cyan, deep blue. Make them thick at the film's scale with a
+ soft or dithered edge. Sparse speckle and chains of balls read weak.
+- Anticipation: a charge glow or wind-up for 0.2 to 0.4 s. Then the source recoils.
+- Every hit or impact gets all of these:
+ - 2 to 4 frames of hit-stop and a screen shake scaled to the hit
+ - a one-frame flash that never whites out an actor
+ - a ring of debris or spray, and a scorch, wet or skid mark that stays
+ - the effect's warm or cool light pulsing on the ground and the target
+- Smoke, dust and steam stay thin and move outward and up. They never cover an actor for more than 0.3 s.
+
+Camera: one continuous move, with a slight push-in on each big hit and on the climax. Both sides of an exchange
+stay in frame. The winner or the result fills at least a third of the frame height at the end.
+
+## Faults seen
+
+`self-review.md` checks these on every render.
+
+- Effects too thin and sparse. Water and fire looked limp.
+- An action hidden in dust or steam (a charge inside a dust cloud, steam over both actors for 2 s).
+- An actor turning one flat colour during a hit, from a hit tint written into a shared material.
+- An actor cut by the frame edge during knockback.
+- The knockout and the exit hidden, and the winner small and far away at the end.
+- A messy pose from a clip played out of context, such as an attack clip started half-way for a dive.
+- Flat, smooth, badly lit ground at a different detail level from the actors.
+- The whole frame smeared into ghost copies on every big hit. The screen shake changed between the motion-blur
+ subframes of one output frame. Evaluate shake and flash once per output frame.
+- Crack and scorch decals piled up as black ink. Keep about 3 at once, tint them a darker shade of the floor and
+ fade old ones out.
+- Dust puffs over the winner during the victory.
+- The victory pan starting late, with the winner still in a corner.
+
+## Sound
+
+Hero cues need professional-sounding SFX, never plain or under-processed ones:
+
+- Build each hero cue from 3 or more layers: a transient, a real CC0 recording, a code-made sub.
+ Add a tail of debris, spray or crackle. Process each layer with EQ and saturation. Add a reverb send
+ and compression on the cue bus, and pan each cue by its place on screen.
+- Sustained beams loop with crossfades. They have a start, a sustain and a release, and their pitch follows the
+ effect's growth.
+- Build creature voices from layered, pitch-shifted animal recordings. Never use official cries or game audio.
+- Keep hit-stop frames near silent, so the impact lands on the first frame after.
+- Show previews without sound. Build the sound only after the user approves the cut.
diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/asset-sources.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/asset-sources.md
new file mode 100644
index 0000000..2c59319
--- /dev/null
+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/asset-sources.md
@@ -0,0 +1,22 @@
+# Where models come from
+
+Look for a ready model before building one. Check the sources in this order, and record each import in the
+project's `CREDITS.md` with the source, author, licence and link. Name the source and rough size and get the
+user's OK before downloading.
+
+1. **Ready models of the exact thing**, with animation clips when it moves. Search Sketchfab filtered to
+ downloadable CC0 or CC BY. Use fan models of known characters or real brands only when the user asks for them,
+ and put a credit line in the report. A site that needs a sign-in gets one from the user. Downloads go to their
+ own folder and are never executed.
+2. **Scans and real materials**: Poly Haven and ambientCG (CC0), NVIDIA SimReady props (CC BY 4.0), NASA 3D
+ Resources, Smithsonian Open Access (CC0 items).
+3. **Stylized and low-poly packs**: Kenney and Quaternius (CC0), Poly Pizza (CC0 or CC BY per model).
+4. **AI-generated models**: the Scenario 3D Collection, a public dataset of about 1,300 GLB models (CC BY 4.0,
+ credit "Scenario"). It holds props, characters, creatures, mechs, vehicles and buildings made by image-to-3D and
+ text-to-3D generators. Search it by hand and pick by eye from previews. Meshes are static with no skeleton. Use
+ them for props and set dressing, or as a base to restyle.
+5. **Build it** in Blender (or three.js, see `no-blender.md`) from a reference sheet (`real-objects.md`).
+
+Every main asset still gets the reference-sheet check from `real-objects.md`, whichever source it came from.
+Restyle imports to the film's look and scale. Skip anything marked non-commercial (NC) or no-derivatives (ND).
+Check each model's licence on its own page, not the collection's.
diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/brief.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/brief.md
index 9487556..d853830 100644
--- a/plugins/visualize-in-3d/skills/visualize-in-3d/references/brief.md
+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/brief.md
@@ -167,7 +167,7 @@ footprint, an ellipse for long things, at most about 1.3x); bare white or grey g
material: asphalt, lane paint, verges, floors); a last shot where the site is small in a sea of empty ground. Use the stage presets for the film's beats instead of
free camera moves when a beat shows one stage, and show a speed change (2x or 5x) once with the control on screen.
-Record the film as {{SKILL_DIR}}/references/film.md "Live app films" says. Run the dev server as a background
+Before reporting, run the loop in {{SKILL_DIR}}/references/self-review.md (up to three rounds) on the app and the film. Record the film as {{SKILL_DIR}}/references/film.md "Live app films" says. Run the dev server as a background
job and stop it when done. Write README.md, pass2_started_at.txt and pass2_finished_at.txt (UTC). Budget about 100 tool calls. Report: what was
built, how to run it, screenshot and film paths, checks with numbers, honest gaps, and a one-line caption suggestion
("Claude built a live <place>, every <main assets> modeled in Blender and running in three.js").
diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/film.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/film.md
index cf203bd..22dc996 100644
--- a/plugins/visualize-in-3d/skills/visualize-in-3d/references/film.md
+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/film.md
@@ -1,7 +1,7 @@
# Film craft
Rules learned from fixing real films made with this skill. They apply to every look; the dark documentary look
-leans on them most. Reading map: Pacing and text, Camera, Figures and places, Maps, Sound, Live app films, Checks.
+leans on them most. Reading map: Pacing and text, Camera, Motion, Figures and places, Maps, Sound, Live app films, Checks.
## Pacing and text
@@ -18,6 +18,18 @@ leans on them most. Reading map: Pacing and text, Camera, Figures and places, Ma
- A rack focus must resolve: pull to the subject within about a second and hold it sharp. A shot that stays soft
reads as a rendering bug.
- Keep figures and key objects clear of the caption area in both layouts (16:9 and 9:16 frame differently).
+- Move each camera on a smooth spline through three or more points, never a straight lerp between two. It is already
+ moving at the cut (cut on motion, no ease from rest), carries a slight handheld drift, and looks from a hero angle:
+ a low macro that tracks the action, an orbit, a crane that rises with what grows, a reveal that cranes down.
+
+## Motion
+
+- Nothing stops dead. A tool eases in, follows through and leaves the frame in an arc before the cut, and a held
+ object keeps moving a little. A finished plant or figure keeps a slow sway, and each action overlaps the next.
+- Growth starts tiny and swells. A plant is born as a small sprout on its line and grows over 1.5 to 4 s on an
+ ease-in-out curve with a soft settle. Small plants lead and big ones follow. An easeOutBack over half a second
+ makes things appear at full size at once, which reads as a pop.
+- Check motion in a moving clip at full frame rate, not on a contact sheet. Stills hide pops and dead stops.
## Figures and places
@@ -88,8 +100,10 @@ leans on them most. Reading map: Pacing and text, Camera, Figures and places, Ma
## Checks
-- Make contact sheets of the final encode at 1 fps (`scripts/contact-sheet.sh`) and look at every sheet. Check the
- sheet files are newer than the video before trusting them; stale sheets hide regressions.
+- Make contact sheets of the final encode at a stated fps (`scripts/contact-sheet.sh <video> <folder> <fps>`: 1 for
+ a slow film, 4 for action) and look at every sheet. Check the sheet files are newer than the video before
+ trusting them; stale sheets hide regressions.
+- Before reporting, run the full loop in `self-review.md`.
- Look for: captions cut early, figures under captions, clipped labels, empty map areas, soft shots, floating or
sunken figures, doors that open onto walls, vehicles backing along their route, black frames at cuts. In a live app
film also look for: the cursor hidden or off target, UI over the action, selection rings wider than the object, a
diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/live-embed.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/live-embed.md
index 68a2d0b..fc79667 100644
--- a/plugins/visualize-in-3d/skills/visualize-in-3d/references/live-embed.md
+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/live-embed.md
@@ -138,3 +138,19 @@ data (driver names, patient names) is shown only when the feed already sends it
Trap from the first build: React StrictMode mounts effects twice, so movers and pins registered in an effect were
registered twice and the pins hid. Make every registry idempotent (keyed by unit id) or leave StrictMode off in the
component entry.
+
+## Publishing as a claude.ai Artifact
+
+Measured on a real walk-through page:
+
+- Artifacts refuse `.glb`, `.gltf` and `.bin` files under any content type. Ship each model as glTF JSON, named
+ `<name>.gltf.json`, with the buffer embedded as base64.
+- The page's CSP blocks `fetch()` of `data:` URIs. GLTFLoader cannot read that embedded buffer by itself, and the page
+ shows "could not load" with no console error you can see. In the page, fetch the JSON, decode the buffer, rebuild a
+ GLB in memory and call `gltfLoader.parseAsync`.
+- Each text file may be 16 MB at most after base64, which adds about a third. Split big scenes and load the rest on
+ first use. Textures go as `.webp` files and audio as `.mp3`. Skip Draco and KTX2, because their decoders fetch wasm
+ from other hosts.
+- Check the published page in a signed-in Chrome, because a built-in browser may not be signed in. When the Chrome
+ window is hidden behind another app, `requestAnimationFrame` drops to about 1 fps. Judge motion from local
+ Playwright runs, not from that tab.
diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/self-review.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/self-review.md
new file mode 100644
index 0000000..45f4a23
--- /dev/null
+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/self-review.md
@@ -0,0 +1,59 @@
+# Self-review loop
+
+Every pass that produces something to watch (an app, a film, a documentary, an action short) runs this loop
+itself before it reports. Run up to three rounds. The goal is that the main session and the user find nothing a
+measurement or a look at the frames could have found.
+
+## Each round
+
+1. **Measure.** Copy `{{SKILL_DIR}}/scripts/frame-guard.js` into the project. In the frame function, log
+ `measureSubjects` for each thing the viewer must follow. Examples: actors, the selected unit, a moving vehicle,
+ a figure. List smoke, steam, beams, captions and panels that can cover them as occluders. After a fast draft
+ render, run `findFaults` and fix every fault outside an `allowed` window (a planned exit, a cut to another place).
+2. **Look.** Render a fast preview (half size, 30 fps, no motion-blur subframes) and make timestamped frame sheets:
+ `bash {{SKILL_DIR}}/scripts/contact-sheet.sh <film> <sheet folder> 4` (the last argument is frames per second;
+ use 4 for action, 1 for a slow documentary). Look at every sheet in order, then at full-size stills of each peak
+ moment (a hit, a reveal, a click result, the last shot), cut with `ffmpeg -ss <time> -i <film> -frames:v 1
+ <png>`. An app also gets screenshots at the real window size.
+3. **Judge.** Check the film against:
+ - the plan file: a viewer reads every beat or feature it promises at phone size, without a caption
+ - the fault list of the mode (`film.md` Checks, `action.md` Faults seen, `brief.md` checks)
+ - the generic faults below.
+4. **Write and fix.** Write the round's findings to `notes/review-<n>.md` with times, fix them, and render again.
+ Stop when a round finds nothing new. Report the remaining gaps honestly.
+
+## Generic faults
+
+- The subject the viewer follows leaves the frame or shrinks under about 40 pixels tall.
+- An effect or a panel covers that subject for more than 0.3 s.
+- A colour, material or texture breaks for a few frames (a flat tint, a missing texture, z-fighting flicker).
+- An action or change happens off camera, or too fast to read at the playback speed.
+- Weak motion: effects, impacts and camera moves too small to read on a phone.
+- The ending is small, far away, cut early or covered.
+- Programmer art: a placeholder box, a default material or a model from memory where a real one belongs.
+- Stale outputs: sheets or stills older than the film they claim to show.
+- Ghost copies of the whole frame: a camera shake or jump that differs between the motion-blur subframes of one
+ frame. Camera offsets are set once per output frame.
+- A colour cast added by the encode grade: compare one raw render frame with the same frame of the encoded film. Run
+ `eq` and `vignette` on YUV and the blend on gbrp. An `eq` on gbrp frames before a screen blend turned a whole film
+ purple.
+- A cut that leaves part of the scene standing: a custom ShaderMaterial ignores `clippingPlanes` unless its shaders
+ include the clipping_planes chunks. Shoot every cut view and look for water, sky domes or effects left in front of
+ the section.
+- A surface that looks right headless and wrong in a real browser (a moat gone white from sky reflection). Check the
+ published page in Chrome at the default hour before reporting.
+- Too many controls on an interactive page: panels in several corners, labels on every object at once, controls over
+ the subject. Use one dock at the bottom, one menu open at a time, and labels only for the current step. A phone card
+ must leave the subject in view.
+- A symbol in the frame centre: an emblem at the vanishing point, or wall parts that line up into a cross. A statue's
+ raised arm can also read as a salute. Check every documentary shot about a regime for these.
+
+## Growing the lists
+
+When the user or the main session finds a fault this loop missed, add it to the matching mode's fault list in the
+same turn, with the case. Add it to the generic list above when it can happen in any mode.
+
+## Previews and the final render
+
+Show the user fast previews while the cut is still changing: half size, 30 fps, no motion-blur subframes. Run the
+full final render (full size, subframes, master and web copy) only after the user approves the cut.
diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/frame-guard.js b/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/frame-guard.js
new file mode 100644
index 0000000..a935c9a
--- /dev/null
+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/frame-guard.js
@@ -0,0 +1,130 @@
+// Dependencies: none beyond "three" (tested with 0.186). Copy this file into the app next to your render code.
+// Frame guard: measures where the film's subjects land on screen, every frame, so a render
+// fails on the faults a viewer sees first (a creature cut by the frame edge, shrunk to a few
+// pixels, or buried under smoke) instead of being caught by eye after a 20 minute render.
+//
+// Usage inside renderAt(time):
+// const report = measureSubjects(camera, subjects, { width: 384, height: 216, margin: 6 });
+// frameLog.push({ time, report });
+// Then at the end of a render: const faults = findFaults(frameLog, { minHeightPixels: 24 });
+// `subjects` is a list of { name, object, occluders? } where occluders are meshes (smoke, steam,
+// beams) whose screen boxes count against the subject's visible share.
+import * as THREE from 'three';
+
+const corner = new THREE.Vector3();
+const box = new THREE.Box3();
+
+export function screenBox(camera, object, width, height) {
+ box.setFromObject(object, true);
+ if (box.isEmpty()) {
+ return null;
+ }
+ let left = Infinity;
+ let right = -Infinity;
+ let top = Infinity;
+ let bottom = -Infinity;
+ for (let index = 0; index < 8; index += 1) {
+ corner.set(
+ index & 1 ? box.max.x : box.min.x,
+ index & 2 ? box.max.y : box.min.y,
+ index & 4 ? box.max.z : box.min.z,
+ );
+ corner.project(camera);
+ const pixelX = (corner.x * 0.5 + 0.5) * width;
+ const pixelY = (1 - (corner.y * 0.5 + 0.5)) * height;
+ left = Math.min(left, pixelX);
+ right = Math.max(right, pixelX);
+ top = Math.min(top, pixelY);
+ bottom = Math.max(bottom, pixelY);
+ }
+ return { left, right, top, bottom };
+}
+
+function overlapArea(first, second) {
+ const overlapWidth = Math.max(0, Math.min(first.right, second.right) - Math.max(first.left, second.left));
+ const overlapHeight = Math.max(0, Math.min(first.bottom, second.bottom) - Math.max(first.top, second.top));
+ return overlapWidth * overlapHeight;
+}
+
+function boxArea(rectangle) {
+ return Math.max(0, rectangle.right - rectangle.left) * Math.max(0, rectangle.bottom - rectangle.top);
+}
+
+// Visible share is approximate: occluder boxes are rectangles and may overlap each other, so the
+// share is a floor. Only count occluders that are actually opaque this frame (dissolve below 0.5).
+export function measureSubjects(camera, subjects, { width, height, margin = 4 }) {
+ camera.updateMatrixWorld();
+ return subjects.map(({ name, object, occluders = [] }) => {
+ if (!object.visible) {
+ return { name, hidden: true };
+ }
+ const rectangle = screenBox(camera, object, width, height);
+ if (!rectangle) {
+ return { name, hidden: true };
+ }
+ const outside =
+ rectangle.left < margin ||
+ rectangle.top < margin ||
+ rectangle.right > width - margin ||
+ rectangle.bottom > height - margin;
+ let coveredArea = 0;
+ for (const occluder of occluders) {
+ if (!occluder.visible) {
+ continue;
+ }
+ const occluderBox = screenBox(camera, occluder, width, height);
+ if (occluderBox) {
+ coveredArea += overlapArea(rectangle, occluderBox);
+ }
+ }
+ const area = boxArea(rectangle);
+ const visibleShare = area > 0 ? Math.max(0, 1 - coveredArea / area) : 0;
+ return {
+ name,
+ rectangle,
+ heightPixels: rectangle.bottom - rectangle.top,
+ outside,
+ visibleShare,
+ };
+ });
+}
+
+// Faults that last longer than `graceSeconds` in a row. A subject meant to leave the frame
+// (an exit, a recall) is listed in `allowed` as { name, from, to }.
+export function findFaults(frameLog, { minHeightPixels = 24, minVisibleShare = 0.5, graceSeconds = 0.3, allowed = [] } = {}) {
+ const faults = [];
+ const openRuns = new Map();
+ const isAllowed = (name, time) => allowed.some((entry) => entry.name === name && time >= entry.from && time <= entry.to);
+ const closeRun = (key, endTime) => {
+ const run = openRuns.get(key);
+ if (run && endTime - run.start > graceSeconds) {
+ faults.push({ ...run, end: endTime });
+ }
+ openRuns.delete(key);
+ };
+ for (const { time, report } of frameLog) {
+ for (const subject of report) {
+ if (subject.hidden || isAllowed(subject.name, time)) {
+ continue;
+ }
+ const problems = {
+ outside: subject.outside,
+ tiny: subject.heightPixels < minHeightPixels,
+ covered: subject.visibleShare < minVisibleShare,
+ };
+ for (const [kind, present] of Object.entries(problems)) {
+ const key = `${subject.name}:${kind}`;
+ if (present && !openRuns.has(key)) {
+ openRuns.set(key, { name: subject.name, kind, start: time });
+ } else if (!present) {
+ closeRun(key, time);
+ }
+ }
+ }
+ }
+ const lastTime = frameLog.length ? frameLog[frameLog.length - 1].time : 0;
+ for (const key of [...openRuns.keys()]) {
+ closeRun(key, lastTime);
+ }
+ return faults;
+}