@scrollframe/core 0.1.1 → 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.
package/dist/index.cjs CHANGED
@@ -21,7 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
21
21
  var index_exports = {};
22
22
  __export(index_exports, {
23
23
  ManifestError: () => ManifestError,
24
+ POSTER_FILL_STYLE: () => POSTER_FILL_STYLE,
24
25
  PROGRESS_CSS_VAR: () => PROGRESS_CSS_VAR,
26
+ STAGE_STYLE: () => STAGE_STYLE,
25
27
  ScrollSequence: () => ScrollSequence,
26
28
  clamp: () => clamp,
27
29
  coarseToFineOrder: () => coarseToFineOrder,
@@ -29,8 +31,11 @@ __export(index_exports, {
29
31
  frameUrl: () => frameUrl,
30
32
  nearestLoaded: () => nearestLoaded,
31
33
  parseManifest: () => parseManifest,
34
+ posterImage: () => posterImage,
32
35
  posterUrl: () => posterUrl,
33
36
  progressFromRect: () => progressFromRect,
37
+ renderPosterMarkup: () => renderPosterMarkup,
38
+ renderStageMarkup: () => renderStageMarkup,
34
39
  selectFrameSet: () => selectFrameSet,
35
40
  sortSets: () => sortSets
36
41
  });
@@ -99,6 +104,57 @@ function posterUrl(manifest, set, baseUrl = manifest.baseUrl) {
99
104
  return joinUrl(baseUrl, set.dir, manifest.poster);
100
105
  }
101
106
 
107
+ // src/poster.ts
108
+ var POSTER_FILL_STYLE = "position:absolute;inset:0;width:100%;height:100%;object-fit:cover";
109
+ function posterImage(manifest, baseUrl) {
110
+ const largest = manifest.sets[manifest.sets.length - 1];
111
+ return {
112
+ sources: manifest.sets.filter((set) => set.maxViewportWidth !== null).map((set) => ({
113
+ media: `(max-width: ${set.maxViewportWidth}px)`,
114
+ srcset: posterUrl(manifest, set, baseUrl),
115
+ width: set.width,
116
+ height: set.height,
117
+ type: "image/webp"
118
+ })),
119
+ img: { src: posterUrl(manifest, largest, baseUrl), width: largest.width, height: largest.height }
120
+ };
121
+ }
122
+ var ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
123
+ function escapeAttr(value) {
124
+ return String(value).replace(/[&<>"']/g, (char) => ESCAPES[char]);
125
+ }
126
+ function attrs(entries) {
127
+ return entries.map(([name, value]) => `${name}="${escapeAttr(value)}"`).join(" ");
128
+ }
129
+ function renderPosterMarkup(manifest, options) {
130
+ const { sources, img } = posterImage(manifest, options.baseUrl);
131
+ const priority = options.priority ?? true;
132
+ const sourceTags = sources.map(
133
+ (s) => `<source ${attrs([
134
+ ["media", s.media],
135
+ ["srcset", s.srcset],
136
+ ["width", s.width],
137
+ ["height", s.height],
138
+ ["type", s.type]
139
+ ])}>`
140
+ );
141
+ const imgTag = `<img ${attrs([
142
+ ["src", img.src],
143
+ ["alt", options.alt],
144
+ ["width", img.width],
145
+ ["height", img.height],
146
+ ["loading", priority ? "eager" : "lazy"],
147
+ ["fetchpriority", priority ? "high" : "auto"],
148
+ ["decoding", "async"],
149
+ ["style", POSTER_FILL_STYLE]
150
+ ])}>`;
151
+ return `<picture>${sourceTags.join("")}${imgTag}</picture>`;
152
+ }
153
+ var STAGE_STYLE = "position:sticky;top:0;height:100svh;overflow:hidden";
154
+ function renderStageMarkup(manifest, options) {
155
+ return `<div data-sf-stage="" style="${STAGE_STYLE}">${renderPosterMarkup(manifest, options)}</div>`;
156
+ }
157
+
102
158
  // src/math.ts
103
159
  function clamp(value, min = 0, max = 1) {
104
160
  return Math.min(max, Math.max(min, value));
@@ -304,7 +360,9 @@ async function loadFrame(url) {
304
360
  // Annotate the CommonJS export names for ESM import in node:
305
361
  0 && (module.exports = {
306
362
  ManifestError,
363
+ POSTER_FILL_STYLE,
307
364
  PROGRESS_CSS_VAR,
365
+ STAGE_STYLE,
308
366
  ScrollSequence,
309
367
  clamp,
310
368
  coarseToFineOrder,
@@ -312,8 +370,11 @@ async function loadFrame(url) {
312
370
  frameUrl,
313
371
  nearestLoaded,
314
372
  parseManifest,
373
+ posterImage,
315
374
  posterUrl,
316
375
  progressFromRect,
376
+ renderPosterMarkup,
377
+ renderStageMarkup,
317
378
  selectFrameSet,
318
379
  sortSets
319
380
  });
package/dist/index.d.cts CHANGED
@@ -32,6 +32,51 @@ declare function selectFrameSet(manifest: SequenceManifest, viewportWidth: numbe
32
32
  declare function frameUrl(manifest: SequenceManifest, set: FrameSet, index: number, baseUrl?: string): string;
33
33
  declare function posterUrl(manifest: SequenceManifest, set: FrameSet, baseUrl?: string): string;
34
34
 
35
+ /** One `<source>` of the poster `<picture>`, for a set with a viewport limit. */
36
+ interface PosterSource {
37
+ media: string;
38
+ srcset: string;
39
+ width: number;
40
+ height: number;
41
+ type: "image/webp";
42
+ }
43
+ /** Everything needed to render the poster `<picture>`: the LCP image search engines index. */
44
+ interface PosterImage {
45
+ /** Smallest viewport first, so the browser picks the first matching media query. */
46
+ sources: PosterSource[];
47
+ /** The largest set, used when no `<source>` matches. */
48
+ img: {
49
+ src: string;
50
+ width: number;
51
+ height: number;
52
+ };
53
+ }
54
+ interface PosterMarkupOptions {
55
+ /** Describes the scene; the poster's alt text. */
56
+ alt: string;
57
+ /** Above-the-fold hero: load eagerly with high priority. Default true. */
58
+ priority?: boolean;
59
+ /** Overrides `manifest.baseUrl` (e.g. a CDN). */
60
+ baseUrl?: string;
61
+ }
62
+ /** Fills the sticky frame; matches the canvas painted on top of it. */
63
+ declare const POSTER_FILL_STYLE = "position:absolute;inset:0;width:100%;height:100%;object-fit:cover";
64
+ /** Poster data shared by every renderer (React, the custom element, generated snippets). */
65
+ declare function posterImage(manifest: SequenceManifest, baseUrl?: string): PosterImage;
66
+ /**
67
+ * The poster `<picture>` as an HTML string, for server templates and plain HTML pages.
68
+ * Self-contained: it carries its own fill style, so no stylesheet is needed.
69
+ */
70
+ declare function renderPosterMarkup(manifest: SequenceManifest, options: PosterMarkupOptions): string;
71
+ /** Pins the poster to the viewport while the section scrolls; inline so it works before any script runs. */
72
+ declare const STAGE_STYLE = "position:sticky;top:0;height:100svh;overflow:hidden";
73
+ /**
74
+ * The stage (sticky frame + poster) as an HTML string. Server templates and generated snippets put it
75
+ * inside `<scroll-sequence>` so the poster is painted before the element's script loads; the element
76
+ * adopts it instead of rendering its own.
77
+ */
78
+ declare function renderStageMarkup(manifest: SequenceManifest, options: PosterMarkupOptions): string;
79
+
35
80
  declare function clamp(value: number, min?: number, max?: number): number;
36
81
  /**
37
82
  * Scroll progress (0..1) of a tall section whose content is sticky.
@@ -101,4 +146,4 @@ declare class ScrollSequence {
101
146
  private preload;
102
147
  }
103
148
 
104
- export { type FrameSet, ManifestError, PROGRESS_CSS_VAR, ScrollSequence, type ScrollSequenceOptions, type SequenceManifest, clamp, coarseToFineOrder, frameIndexFromProgress, frameUrl, nearestLoaded, parseManifest, posterUrl, progressFromRect, selectFrameSet, sortSets };
149
+ export { type FrameSet, ManifestError, POSTER_FILL_STYLE, PROGRESS_CSS_VAR, type PosterImage, type PosterMarkupOptions, type PosterSource, STAGE_STYLE, ScrollSequence, type ScrollSequenceOptions, type SequenceManifest, clamp, coarseToFineOrder, frameIndexFromProgress, frameUrl, nearestLoaded, parseManifest, posterImage, posterUrl, progressFromRect, renderPosterMarkup, renderStageMarkup, selectFrameSet, sortSets };
package/dist/index.d.ts CHANGED
@@ -32,6 +32,51 @@ declare function selectFrameSet(manifest: SequenceManifest, viewportWidth: numbe
32
32
  declare function frameUrl(manifest: SequenceManifest, set: FrameSet, index: number, baseUrl?: string): string;
33
33
  declare function posterUrl(manifest: SequenceManifest, set: FrameSet, baseUrl?: string): string;
34
34
 
35
+ /** One `<source>` of the poster `<picture>`, for a set with a viewport limit. */
36
+ interface PosterSource {
37
+ media: string;
38
+ srcset: string;
39
+ width: number;
40
+ height: number;
41
+ type: "image/webp";
42
+ }
43
+ /** Everything needed to render the poster `<picture>`: the LCP image search engines index. */
44
+ interface PosterImage {
45
+ /** Smallest viewport first, so the browser picks the first matching media query. */
46
+ sources: PosterSource[];
47
+ /** The largest set, used when no `<source>` matches. */
48
+ img: {
49
+ src: string;
50
+ width: number;
51
+ height: number;
52
+ };
53
+ }
54
+ interface PosterMarkupOptions {
55
+ /** Describes the scene; the poster's alt text. */
56
+ alt: string;
57
+ /** Above-the-fold hero: load eagerly with high priority. Default true. */
58
+ priority?: boolean;
59
+ /** Overrides `manifest.baseUrl` (e.g. a CDN). */
60
+ baseUrl?: string;
61
+ }
62
+ /** Fills the sticky frame; matches the canvas painted on top of it. */
63
+ declare const POSTER_FILL_STYLE = "position:absolute;inset:0;width:100%;height:100%;object-fit:cover";
64
+ /** Poster data shared by every renderer (React, the custom element, generated snippets). */
65
+ declare function posterImage(manifest: SequenceManifest, baseUrl?: string): PosterImage;
66
+ /**
67
+ * The poster `<picture>` as an HTML string, for server templates and plain HTML pages.
68
+ * Self-contained: it carries its own fill style, so no stylesheet is needed.
69
+ */
70
+ declare function renderPosterMarkup(manifest: SequenceManifest, options: PosterMarkupOptions): string;
71
+ /** Pins the poster to the viewport while the section scrolls; inline so it works before any script runs. */
72
+ declare const STAGE_STYLE = "position:sticky;top:0;height:100svh;overflow:hidden";
73
+ /**
74
+ * The stage (sticky frame + poster) as an HTML string. Server templates and generated snippets put it
75
+ * inside `<scroll-sequence>` so the poster is painted before the element's script loads; the element
76
+ * adopts it instead of rendering its own.
77
+ */
78
+ declare function renderStageMarkup(manifest: SequenceManifest, options: PosterMarkupOptions): string;
79
+
35
80
  declare function clamp(value: number, min?: number, max?: number): number;
36
81
  /**
37
82
  * Scroll progress (0..1) of a tall section whose content is sticky.
@@ -101,4 +146,4 @@ declare class ScrollSequence {
101
146
  private preload;
102
147
  }
103
148
 
104
- export { type FrameSet, ManifestError, PROGRESS_CSS_VAR, ScrollSequence, type ScrollSequenceOptions, type SequenceManifest, clamp, coarseToFineOrder, frameIndexFromProgress, frameUrl, nearestLoaded, parseManifest, posterUrl, progressFromRect, selectFrameSet, sortSets };
149
+ export { type FrameSet, ManifestError, POSTER_FILL_STYLE, PROGRESS_CSS_VAR, type PosterImage, type PosterMarkupOptions, type PosterSource, STAGE_STYLE, ScrollSequence, type ScrollSequenceOptions, type SequenceManifest, clamp, coarseToFineOrder, frameIndexFromProgress, frameUrl, nearestLoaded, parseManifest, posterImage, posterUrl, progressFromRect, renderPosterMarkup, renderStageMarkup, selectFrameSet, sortSets };
package/dist/index.js CHANGED
@@ -61,6 +61,57 @@ function posterUrl(manifest, set, baseUrl = manifest.baseUrl) {
61
61
  return joinUrl(baseUrl, set.dir, manifest.poster);
62
62
  }
63
63
 
64
+ // src/poster.ts
65
+ var POSTER_FILL_STYLE = "position:absolute;inset:0;width:100%;height:100%;object-fit:cover";
66
+ function posterImage(manifest, baseUrl) {
67
+ const largest = manifest.sets[manifest.sets.length - 1];
68
+ return {
69
+ sources: manifest.sets.filter((set) => set.maxViewportWidth !== null).map((set) => ({
70
+ media: `(max-width: ${set.maxViewportWidth}px)`,
71
+ srcset: posterUrl(manifest, set, baseUrl),
72
+ width: set.width,
73
+ height: set.height,
74
+ type: "image/webp"
75
+ })),
76
+ img: { src: posterUrl(manifest, largest, baseUrl), width: largest.width, height: largest.height }
77
+ };
78
+ }
79
+ var ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
80
+ function escapeAttr(value) {
81
+ return String(value).replace(/[&<>"']/g, (char) => ESCAPES[char]);
82
+ }
83
+ function attrs(entries) {
84
+ return entries.map(([name, value]) => `${name}="${escapeAttr(value)}"`).join(" ");
85
+ }
86
+ function renderPosterMarkup(manifest, options) {
87
+ const { sources, img } = posterImage(manifest, options.baseUrl);
88
+ const priority = options.priority ?? true;
89
+ const sourceTags = sources.map(
90
+ (s) => `<source ${attrs([
91
+ ["media", s.media],
92
+ ["srcset", s.srcset],
93
+ ["width", s.width],
94
+ ["height", s.height],
95
+ ["type", s.type]
96
+ ])}>`
97
+ );
98
+ const imgTag = `<img ${attrs([
99
+ ["src", img.src],
100
+ ["alt", options.alt],
101
+ ["width", img.width],
102
+ ["height", img.height],
103
+ ["loading", priority ? "eager" : "lazy"],
104
+ ["fetchpriority", priority ? "high" : "auto"],
105
+ ["decoding", "async"],
106
+ ["style", POSTER_FILL_STYLE]
107
+ ])}>`;
108
+ return `<picture>${sourceTags.join("")}${imgTag}</picture>`;
109
+ }
110
+ var STAGE_STYLE = "position:sticky;top:0;height:100svh;overflow:hidden";
111
+ function renderStageMarkup(manifest, options) {
112
+ return `<div data-sf-stage="" style="${STAGE_STYLE}">${renderPosterMarkup(manifest, options)}</div>`;
113
+ }
114
+
64
115
  // src/math.ts
65
116
  function clamp(value, min = 0, max = 1) {
66
117
  return Math.min(max, Math.max(min, value));
@@ -265,7 +316,9 @@ async function loadFrame(url) {
265
316
  }
266
317
  export {
267
318
  ManifestError,
319
+ POSTER_FILL_STYLE,
268
320
  PROGRESS_CSS_VAR,
321
+ STAGE_STYLE,
269
322
  ScrollSequence,
270
323
  clamp,
271
324
  coarseToFineOrder,
@@ -273,8 +326,11 @@ export {
273
326
  frameUrl,
274
327
  nearestLoaded,
275
328
  parseManifest,
329
+ posterImage,
276
330
  posterUrl,
277
331
  progressFromRect,
332
+ renderPosterMarkup,
333
+ renderStageMarkup,
278
334
  selectFrameSet,
279
335
  sortSets
280
336
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scrollframe/core",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "Framework-agnostic scroll-driven image sequence engine (canvas, lazy loading, Core Web Vitals friendly).",
5
5
  "license": "MIT",
6
6
  "repository": {