feat(registry): torn-paper-rip transition

Agents often search for "torn paper" or "paper rip" and find nothing built
for it in the catalog. Adds a component transition where a jagged, seeded
paper tear travels across the frame with an exposed cream/kraft/white
cross-section, splitting one slotted scene into the next.
This commit is contained in:
Miguel Angel Simon Sierra
2026-09-23 09:50:21 -04:00
committed by Miguel Ángel
parent 29378b6c7f
commit e040f26b07
11 changed files with 1114 additions and 5 deletions
+476
View File
@@ -0,0 +1,476 @@
---
title: "Torn Paper Rip"
description: "A jagged, fibrous paper tear travels across the frame, taking one scene with it and leaving the next standing. The exposed cross-section rides just behind the cut edge, on a token paper tone."
mode: "frame"
---
import { CatalogDetail, CatalogSlot } from "/snippets/catalog-detail.jsx";
import { InstallCommand } from "/snippets/install-command.jsx";
<CatalogDetail
previewSrc="/public/catalog/components/torn-paper-rip.json"
compositionId="torn-paper-rip"
compositionSrc="compositions/components/torn-paper-rip.html"
title="Torn Paper Rip"
description="A jagged, fibrous paper tear travels across the frame, taking one scene with it and leaving the next standing. The exposed cross-section rides just behind the cut edge, on a token paper tone."
variables={[{"id":"direction","type":"enum","role":"motion","label":"Direction","description":"Which way the tear travels across the frame.","default":"left-to-right","options":[{"value":"left-to-right","label":"Left to right"},{"value":"right-to-left","label":"Right to left"}]},{"id":"tone","type":"enum","role":"style","label":"Paper tone","description":"Color of the exposed paper cross-section riding the tear.","default":"cream","options":[{"value":"cream","label":"Cream"},{"value":"kraft","label":"Kraft"},{"value":"white","label":"White"}]},{"id":"roughness","type":"number","role":"style","label":"Roughness","description":"How jagged and fibrous the tear edge is. Low is a clean deckle edge, high is roughly torn.","default":55,"min":20,"max":90,"step":1}]}
meta={{"category":"Effects","badge":"Stable","codeLines":395}}
attribution={{"path":"registry/components/torn-paper-rip","tags":["torn paper","paper rip","paper tear","transition","texture","motion-primitive"]}}
hasCode
rawUrl="https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/components/torn-paper-rip/torn-paper-rip.html"
>
<CatalogSlot slot="code">
```html torn-paper-rip.html
<!doctype html>
<!--
torn-paper-rip: HyperFrames video primitive (transitions / texture).
A jagged, fibrous paper tear travels across the frame and splits one scene
into the next. The "from" layer sits on top; a thin paper-cream rim (the
exposed cross-section of the tear) rides just behind its cut edge; the "to"
layer fills the whole stage underneath. As the tear travels, it takes the
"from" layer with it and leaves the "to" layer standing.
Both scenes are SLOTS. Callers supply content by placing inert templates
anywhere in the HOST page (templates never render, and the runtime wipes
the host clip's own children on mount, so slots live at document level):
<template data-slot="torn-paper-rip-from"> ... </template>
<template data-slot="torn-paper-rip-to"> ... </template>
Slot content may be an <img>, a muted <video>, or arbitrary HTML; direct
img/video children are stretched to cover the stage (packages/producer
drives a slotted <video>'s own data-start/data-duration exactly like any
other clip -- this primitive never reads or sets currentTime itself). With
no slot, each side renders a token paper card so the tear reads on its own.
Variables (declared in data-composition-variables below):
- direction ("left-to-right" | "right-to-left", default "left-to-right"):
which way the tear travels.
- tone ("cream" | "kraft" | "white", default "cream"): color of the
exposed paper cross-section riding the tear.
- roughness (number 20-90, default 55): how jagged and fibrous the tear
edge is. Low reads as a clean deckle edge, high reads as roughly torn.
Envelope, fixed IN with elastic HOLD only (never timeScale):
IN_BASE = 1.0s the tear sweeps fully across, taking the "from" layer
HOLD = max(0, D - IN); "to" stands alone, truly still
If D < IN_BASE, IN compresses to D (no hold).
Determinism (closed-form field law): there is NO physics state. One
per-row jitter table (16 rows) is computed exactly once during synchronous
timeline construction from a fixed LCG seed 0x7a9e11cf. Every painted frame
derives the tear's clip-path as a pure function of (table, timeline time)
inside a single tween's onUpdate -- a fresh clip-path string, never an
incremental mutation. No Math.random, no wall clock, no requestAnimationFrame.
Eventful seeks land identical frames in any order and either direction.
Mount contract: the runtime clones only this template. #root fills the
host box (no data-width/data-height, container-type: size, cqmin units),
is styled via #root only, and registers one paused timeline under the
LITERAL "torn-paper-rip" key.
-->
<html
lang="en"
data-composition-id="torn-paper-rip"
data-composition-duration="2.4"
data-composition-variables='[
{ "id": "direction", "type": "enum", "role": "motion", "label": "Direction", "description": "Which way the tear travels across the frame.", "default": "left-to-right", "options": [{ "value": "left-to-right", "label": "Left to right" }, { "value": "right-to-left", "label": "Right to left" }] },
{ "id": "tone", "type": "enum", "role": "style", "label": "Paper tone", "description": "Color of the exposed paper cross-section riding the tear.", "default": "cream", "options": [{ "value": "cream", "label": "Cream" }, { "value": "kraft", "label": "Kraft" }, { "value": "white", "label": "White" }] },
{ "id": "roughness", "type": "number", "role": "style", "label": "Roughness", "description": "How jagged and fibrous the tear edge is. Low is a clean deckle edge, high is roughly torn.", "default": 55, "min": 20, "max": 90, "step": 1 }
]'
>
<head>
<meta charset="UTF-8" />
<title>Torn Paper Rip</title>
</head>
<body>
<template>
<div id="root" data-composition-id="torn-paper-rip" data-duration="2.4" data-fps="30">
<style>
*,
*::before,
*::after {
box-sizing: border-box;
}
#root {
position: absolute;
inset: 0;
overflow: hidden;
container-type: size;
isolation: isolate;
color: var(--fg, #1d1b16);
font-family: var(--font-display, "Inter", system-ui, sans-serif);
}
.tpr-clip {
position: absolute;
inset: 0;
overflow: hidden;
background: var(--bg, transparent);
}
.tpr-stage {
position: absolute;
inset: 0;
}
.tpr-layer {
position: absolute;
inset: 0;
overflow: hidden;
}
.tpr-layer > img,
.tpr-layer > video {
display: block;
width: 100%;
height: 100%;
object-fit: cover;
}
.tpr-from {
/* Physical lift along the clipped silhouette: drop-shadow follows
alpha, so it traces the jagged edge for free. Filter and
clip-path never share an element -- CSS applies filter first,
so a clip on the same node would clip the shadow away too. */
filter: drop-shadow(var(--tpr-shadow-x, -3cqmin) 4cqmin 3.5cqmin rgba(10, 8, 4, 0.4));
}
.tpr-from-clip {
position: absolute;
inset: 0;
overflow: hidden;
}
.tpr-from-clip > img,
.tpr-from-clip > video {
display: block;
width: 100%;
height: 100%;
object-fit: cover;
}
.tpr-rim {
background: var(--tpr-rim-color, #f3ecda);
}
.tpr-rim-grain {
position: absolute;
inset: 0;
filter: url(#tpr-grain-filter);
opacity: 0.5;
mix-blend-mode: multiply;
}
.tpr-default {
position: absolute;
inset: 0;
display: grid;
place-items: center;
}
.tpr-default-mark {
font-size: 5cqmin;
font-weight: 700;
letter-spacing: 0.3em;
text-transform: uppercase;
opacity: 0.5;
}
.tpr-from .tpr-default {
background: radial-gradient(
120% 120% at 30% 20%,
color-mix(in srgb, var(--accent, #2f6fed) 32%, var(--bg, #14161c)) 0%,
var(--bg, #14161c) 70%
);
}
.tpr-from .tpr-default-mark {
color: var(--surface, #fff);
}
.tpr-to .tpr-default {
background: radial-gradient(
120% 120% at 70% 80%,
color-mix(in srgb, var(--accent-2, #7a5cd6) 32%, var(--fg, #1d1b16)) 0%,
var(--fg, #1d1b16) 70%
);
}
.tpr-to .tpr-default-mark {
color: var(--surface, #fff);
}
</style>
<div
id="torn-paper-rip-clip"
class="tpr-clip clip"
data-start="0"
data-duration="2.4"
data-track-index="0"
>
<svg aria-hidden="true" width="0" height="0" style="position: absolute">
<defs>
<!-- Seeded static paper grain: fixed seed, never animated, so
it adds tooth to the exposed rim without touching
determinism (same recipe as ink-bleed-reveal). -->
<filter
id="tpr-grain-filter"
x="0%"
y="0%"
width="100%"
height="100%"
color-interpolation-filters="sRGB"
>
<feTurbulence
type="fractalNoise"
baseFrequency="0.9"
numOctaves="2"
seed="27"
stitchTiles="stitch"
result="noise"
/>
<feColorMatrix
in="noise"
type="matrix"
values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.18 0.18 0.18 0 0"
/>
</filter>
</defs>
</svg>
<div class="tpr-stage">
<div class="tpr-layer tpr-to" id="tpr-to">
<div class="tpr-default">
<span class="tpr-default-mark" aria-hidden="true">Scene B</span>
</div>
</div>
<div class="tpr-layer tpr-rim" id="tpr-rim">
<div class="tpr-rim-grain"></div>
</div>
<div class="tpr-layer tpr-from" id="tpr-from">
<div class="tpr-from-clip" id="tpr-from-clip">
<div class="tpr-default">
<span class="tpr-default-mark" aria-hidden="true">Scene A</span>
</div>
</div>
</div>
</div>
</div>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
<script>
(function () {
"use strict";
var root = document.getElementById("root");
var fromClip = document.getElementById("tpr-from-clip");
var toLayer = document.getElementById("tpr-to");
var rimLayer = document.getElementById("tpr-rim");
var vars =
window.__hyperframes && window.__hyperframes.getVariables
? window.__hyperframes.getVariables()
: {};
var direction = vars.direction === "right-to-left" ? "right-to-left" : "left-to-right";
var rimColors = {
cream: "color-mix(in srgb, var(--surface, #fffdf8) 72%, #e8d9ae)",
kraft: "color-mix(in srgb, var(--accent-2, #b98a4e) 55%, #7d5a34)",
white: "var(--surface, #f7f5f0)",
};
var tone = Object.prototype.hasOwnProperty.call(rimColors, vars.tone)
? vars.tone
: "cream";
root.style.setProperty("--tpr-rim-color", rimColors[tone]);
var roughnessValue = parseFloat(vars.roughness);
var roughness = Number.isFinite(roughnessValue)
? Math.min(90, Math.max(20, roughnessValue))
: 55;
var roughnessNorm = (roughness - 20) / 70;
// Slots. Caller templates live at the host document level (the
// mount wipes host-clip children, and templates never render),
// so the lookup deliberately goes through ownerDocument.
var hostDoc = root.ownerDocument;
function mountSlot(slotName, layer) {
var tpl = null;
try {
tpl = hostDoc.querySelector('template[data-slot="' + slotName + '"]');
} catch (error) {
tpl = null;
}
if (!tpl) return;
var defaultMark = layer.querySelector(".tpr-default");
if (defaultMark) defaultMark.remove();
layer.appendChild(hostDoc.importNode(tpl.content, true));
}
mountSlot("torn-paper-rip-from", fromClip);
mountSlot("torn-paper-rip-to", toLayer);
// Envelope: fixed IN, elastic HOLD, never time-scaled.
var IN_BASE = 1.0;
var duration = Math.max(0.001, parseFloat(root.dataset.duration || "2.4"));
var IN = Math.min(IN_BASE, duration);
// The tear geometry lives entirely in this table, computed once
// during synchronous timeline construction. ROWS segments give
// the jagged edge its resolution; a few get an amplified spike
// so they read as individual paper fibers, not smooth noise.
var ROWS = 16;
var JITTER_PCT = 1.5 + roughnessNorm * 6.5;
var DIAGONAL_PCT = 3 + roughnessNorm * 9;
var SPIKE_MULT = 2.6;
var RIM_PCT = 2.2 + roughnessNorm * 1.6;
var jitterTable = (function () {
var state = 0x7a9e11cf;
function next() {
state = (Math.imul(1664525, state) + 1013904223) >>> 0;
return state / 4294967296;
}
var rows = [];
for (var i = 0; i <= ROWS; i += 1) {
var yPct = (i / ROWS) * 100;
var diagonal = (yPct / 100 - 0.5) * DIAGONAL_PCT;
var noise = (next() * 2 - 1) * JITTER_PCT;
rows.push({ yStr: yPct.toFixed(2) + "%", offset: diagonal + noise });
}
// Pick a handful of interior rows for an isolated fiber spike,
// dampening their immediate neighbours so the spike reads as a
// single thread rather than widening the whole notch. idx is
// bounded to [2, ROWS-3], so both neighbours always exist.
var spikeCount = 3;
for (var s = 0; s < spikeCount; s += 1) {
var idx = 2 + Math.floor(next() * (ROWS - 4));
var sign = rows[idx].offset >= 0 ? 1 : -1;
rows[idx].offset += sign * JITTER_PCT * SPIKE_MULT;
rows[idx - 1].offset *= 0.4;
rows[idx + 1].offset *= 0.4;
}
return rows;
})();
// side: which side of the boundary shows "from" (ltr eats it
// from the left, so "from" lives on the right; rtl is the
// mirror). rimOffset pushes the rim past "from"'s own edge, into
// the torn-away side. Both are fixed, so computed once here.
var maxRowOffset = jitterTable.reduce(function (m, row) {
return Math.max(m, Math.abs(row.offset));
}, 0);
// Margin must clear the worst-case row (including spike rows,
// whose offset can exceed the base jitter-plus-diagonal swing)
// plus the rim's own extra push, so neither layer's boundary
// ever lands on-screen at p=0 or p=1.
var MARGIN = maxRowOffset + RIM_PCT;
var side = direction === "left-to-right" ? "right" : "left";
var START = side === "right" ? -MARGIN : 100 + MARGIN;
var END = side === "right" ? 100 + MARGIN : -MARGIN;
var CORNER_X = side === "right" ? "100%" : "0%";
var rimOffset = (side === "right" ? -1 : 1) * RIM_PCT;
// The lift shadow points onto the revealed layer, same mirror as rimOffset.
root.style.setProperty("--tpr-shadow-x", (side === "right" ? -3 : 3) + "cqmin");
function easeInOutCubic(v) {
return v < 0.5 ? 4 * v * v * v : 1 - Math.pow(-2 * v + 2, 3) / 2;
}
// Paints both clip-paths for a given progress in one pass over
// the row table -- one walk builds the "from" boundary string,
// the other the rim boundary (offset by rimOffset), with no
// intermediate arrays.
function paint(p) {
var eased = easeInOutCubic(Math.max(0, Math.min(1, p)));
var bx = START + (END - START) * eased;
var fromPts = CORNER_X + " 0%, " + CORNER_X + " 100%";
var rimPts = fromPts;
for (var i = ROWS; i >= 0; i -= 1) {
var row = jitterTable[i];
var x = bx + row.offset;
fromPts += ", " + x.toFixed(2) + "% " + row.yStr;
rimPts += ", " + (x + rimOffset).toFixed(2) + "% " + row.yStr;
}
fromClip.style.clipPath = "polygon(" + fromPts + ")";
rimLayer.style.clipPath = "polygon(" + rimPts + ")";
}
paint(0);
var tl = gsap.timeline({
paused: true,
onUpdate: function () {
paint(this.progress());
},
});
tl.to({}, { duration: IN, ease: "none" }, 0);
tl.seek(0);
window.__timelines = window.__timelines || {};
window.__timelines["torn-paper-rip"] = tl;
})();
</script>
</div>
</template>
</body>
</html>
```
</CatalogSlot>
<CatalogSlot slot="install">
<InstallCommand command="npx hyperframes add torn-paper-rip" item="torn-paper-rip" />
That writes one file: `compositions/components/torn-paper-rip.html`.
</CatalogSlot>
<CatalogSlot slot="docs">
## Paste it into your composition
Open `compositions/components/torn-paper-rip.html` and copy what is inside into your own composition.
A component has no size or duration of its own. It takes both from the composition
you paste it into.
## Variables
Every one of these has a default, so the piece works untouched. Set the ones you
want to change on the element:
| Variable | Default | Accepts | What it does |
| --- | --- | --- | --- |
| `direction` | `left-to-right` | `left-to-right`, `right-to-left` | Which way the tear travels across the frame. |
| `tone` | `cream` | `cream`, `kraft`, `white` | Color of the exposed paper cross-section riding the tear. |
| `roughness` | `55` | 20 to 90, step 1 | How jagged and fibrous the tear edge is. Low is a clean deckle edge, high is roughly torn. |
Set them with `data-variable-values` on the element that mounts it. These are the
defaults, so this behaves exactly like the preview above until you change one:
```html wrap
<div
data-composition-id="torn-paper-rip"
data-composition-src="compositions/components/torn-paper-rip.html"
data-variable-values='{"direction":"left-to-right","tone":"cream","roughness":55}'
></div>
```
{/* hf:generated-footer */}
Tagged `torn paper` `paper rip` `paper tear` `transition` `texture` `motion-primitive`.
## Related topics
- [Browse the complete Catalog](/catalog)
- [Add assets and Catalog items in Studio](/studio/assets-and-blocks)
- [Build a richer composition](/go-further)
</CatalogSlot>
</CatalogDetail>
+3 -2
View File
@@ -652,7 +652,7 @@
},
{
"group": "Motion & effects",
"tag": "94",
"tag": "95",
"expanded": false,
"pages": [
{
@@ -694,7 +694,7 @@
},
{
"group": "Effects",
"tag": "53",
"tag": "54",
"expanded": false,
"pages": [
"catalog/components/avatar-cloud",
@@ -743,6 +743,7 @@
"catalog/components/svg-mask-reveal",
"catalog/components/tabs-slide-indicator",
"catalog/components/testimonial-card",
"catalog/components/torn-paper-rip",
"catalog/components/type-match-cut",
"catalog/components/vignette",
"catalog/components/whip-pan-cut",
+16
View File
@@ -4812,6 +4812,22 @@
"href": "/catalog/components/top-down-letters",
"preview": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/components/top-down-letters.png"
},
{
"name": "torn-paper-rip",
"type": "component",
"title": "Torn Paper Rip",
"description": "A jagged, fibrous paper tear travels across the frame, taking one scene with it and leaving the next standing. The exposed cross-section rides just behind the cut edge, on a token paper tone.",
"tags": [
"torn paper",
"paper rip",
"paper tear",
"transition",
"texture",
"motion-primitive"
],
"href": "/catalog/components/torn-paper-rip",
"preview": "https://static.heygen.ai/hyperframes-oss/docs/images/catalog/components/torn-paper-rip.png"
},
{
"name": "touch-indicator",
"type": "component",
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long