WIP: New experimental scrollytelling workload

suites-experimental/scrollytelling/DESIGN.md

@@ -0,0 +1,41 @@
+# Scrollytelling Workload: Layout & Design Decision Document
+
+This document records the concise design decisions and architectural rules for the **Project A-101: The Homestead Dossier** scrollytelling benchmark workload in Speedometer.
+
+## Executive Design Decision
+
+The workload models a 1950s/1960s mid-century architectural journal, technical drafting blueprint, and precision print instruction manual (such as the classic 1968 Canon Autozoom 518 instruction manual). To maintain visual harmony and benchmark performance consistency, all layout components, CSS styles, Canvas procedural renderings, and SVG overlays must follow these foundational rules:
+
+### Aesthetic Reference: Inverted 1968 Canon Autozoom 518 Graphic & Layout Style
+
+Our visual identity adapts the utilitarian yet refined late-1960s Japanese industrial technical print design of the Canon Autozoom 518 manual, inverted for a negative dark-mode drafting void (`#000000` pure black background, `#111111` drafting canvas, `#ffffff` primary white text and linework). The typography establishes a strict hierarchy combining bold, condensed mid-century display lettering with clean, airy geometric sans-serifs (resembling Futura/Helvetica) and typewriter monospace engineering tables. Section headers and step sequences (`1`, `2`, `3`) leap from the dark canvas in high-contrast **crimson-ruby accent red** (`#D12B3E`), paired with crisp red leader-line callouts (`---→`) targeting mechanical and structural components. The layout balances technical precision and human warmth through asymmetric grids, slanted geometric shapes, rounded rectangular diagram frames, and high-contrast duotone architectural line art.
+
+### 1. 1950s Black & White Blueprint / Planning Design with Organic Watercolor Accents
+
+-   **Pure Black Background & B&W UI**: The UI theme is negative blueprint drafting (light on dark void). Body background is `#000000`. Inactive cards and drafting canvas are `#111111`, active cards are `#0a0a0a`. Primary drafting ink and typography is `#ffffff`. Secondary lines are `#cccccc` and `#777777`.
+-   **Organic Watercolor Accents**: Watercolor brush assets (`bw_watercolor_texture.webp`, `watercolor_stroke_*.webp`) are allowed exclusively as gradual animation coloring elements (revealed via circular focus, slide wipe, or fade wash as scroll progress advances).
+-   **Allowed Backgrounds**: Only B&W topographic maps (`topo_map_*.webp`) and planning paper dot grids (`planning_paper_dot_grid.webp`) blended with `screen` / `color-dodge` / `overlay` (and inverted where necessary) to render as white linework on black.
+
+### 2. Slightly Slanted Borders & Geometric Shapes
+
+-   Containers, headers, step cards, title blocks, and callout badges must be enclosed in slightly slanted geometric shapes (-2.0° to +2.0° tilt) with asymmetric polygon borders or trapezoidal outlines. (Note: Paragraph text is explicitly exempt from slanting and must remain vertical).
+
+### 3. Irregular & Independent Drop Shadows (Shadow Angle ≠ Box Angle)
+
+-   **Irregularity**: Every section, card, title block, and text badge must cast a drop shadow at an irregular distance and angle (varying between bottom-right, bottom-left, top-right, and top-left across stages).
+-   **Independent Shadow Tilt**: A drop shadow must NEVER have the same rotation angle as the box casting it.
+    -   In DOM/CSS, drop shadows are constructed as separate `::before` or `::after` pseudo-elements (`background: var(--shadow-solid, #222222)`) with an independent rotation variable (`--shadow-tilt`) that differs from the box rotation (`--graphic-tilt` or `--step-tilt`).
+    -   In Canvas and SVG, drop shadows are rendered as distinct underlying geometry rotated independently from the foreground box.
+
+### 4. Vertical Standard Paragraph Text (No Separate Boxes or Animations)
+
+-   **Standard Text Styling & Vertical Alignment**: Paragraph text (`.step-paragraph-item`, `.step-description`) must NEVER be broken into visually separate boxes, cards, or tabs. Whether a stage has a single paragraph or multiple paragraphs, all paragraph text must use standard text styling with clean vertical alignment (0° rotation, straight vertical layout).
+-   **Zero Layout Animations**: Paragraph text must have 0 layout animations and 0 transforms (no translating on hover/active, no scaling, no rotating, and no drop shadows or background boxes).
+
+### 5. Three-Tier Typography Hierarchy
+
+1. **Display / Titles / Badges**: Bold mid-century industrial display fonts (`Impact`, `Arial Black`, `Futura`).
+2. **Narrative Body Text / Paragraphs**: Clean, effortlessly readable standard sans-serif / system fonts (`system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif`) with comfortable line height (`1.65`) and normal weight (`400`) for all paragraph text (`.step-description`).
+3. **Technical Specifications & Metadata**: Typewriter monospace fonts (`Courier New`, `Courier`, monospace) exclusively for engineering specifications (`.step-specs`), title blocks, leader callouts, diorama tab headers (`.paragraph-mech-tab`), and table of contents items.
+
+-   All procedural line art features hand-drafted jitter and cross-hatching in white/cream/light gray tones.

suites-experimental/scrollytelling/README.md

@@ -0,0 +1,23 @@
+# Scrollytelling Workload (Project A-101: The Homestead Dossier)
+
+An experimental scrollytelling benchmark workload for Speedometer that evaluates browser performance during interactive scroll-driven visual storytelling.
+
+## Overview
+
+This workload models a 1950s/1960s mid-century architectural dossier and technical blueprint (`#000000` pure black background with high-contrast B&W geometry and procedural line art). As the user scrolls through 17 narrative stages covering American homestead evolution and geotechnical engineering analysis, the benchmark measures layout, Canvas 2D rendering, SVG overlay positioning, and DOM interaction performance.
+
+## Architecture & Mechanics
+
+- **Scroll Engine**: Uses `scrollama` to track stage progression and trigger deterministic scroll animations (`src/engine-scrollama.js`).
+- **Graphics & Rendering**: Procedural Canvas 2D linework, monochrome cross-hatching, and organic watercolor animation reveals (`src/graphics.js`).
+- **Layout & DOM**: 17 stages with 5 narrative phases each, featuring sticky SVG leader callouts, slanted borders, and upright body typography (`src/content.js`, `src/main.js`, `src/styles.css`).
+- **Benchmark Determinism**: Intercepts `window.requestAnimationFrame` to synchronously flush visual states before `page.layout()` measurements (`index.html`).
+
+## Building the Workload
+
+To build the bundle using Rollup:
+
+```bash
+npm install
+npm run build
+```

suites-experimental/scrollytelling/STYLE.md

@@ -0,0 +1,79 @@
+# Speedometer Scrollytelling Workload — Style & Architectural Requirements
+
+When modifying or extending the `suites-experimental/scrollytelling` workload, all engineers, agents, and subagents must strictly adhere to the following 9 architectural and graphic design rules to maintain visual harmony and benchmark timing precision.
+
+---
+
+## 1. Core Aesthetic & Palette: 1950s Black & White Blueprint / Planning Design
+
+-   **Background Texture**: Pure black drafting background (`#000000` body background, `#111111` drafting canvas/inactive cards, `#0a0a0a` active panels).
+-   **Allowed Background Assets**: Only use B&W topographic maps (`topo_map_*.webp`) and our standalone tiling SVG drafting grid (`drafting_grid_tiling.svg`) blended with `screen` / `color-dodge` / `overlay` (and inverted where necessary) so linework appears crisp white/light gray on black.
+
+---
+
+## 2. Strict Black & White Geometry & Ink Palette (Zero Dark-on-Dark Text)
+
+-   All structural wireframes, text, cards, borders, badges, and procedural line art remain strictly high-contrast black and white.
+-   **Primary Text & Drawing Ink**: `#ffffff` (pure white) or `var(--ink-primary)`.
+-   **Secondary Lines & Hatching**: `#cccccc` and `#777777` or `var(--ink-secondary)`.
+-   **Active Highlights & Cards**: `#0a0a0a` (deep black/slate) or `#000000` (pure black) backgrounds with `#ffffff` text and borders.
+-   **NEVER** use dark or muted text over dark gray/dark backgrounds. Every label, subtitle, specification, and TOC link must remain bright and legible at all times.
+
+---
+
+## 3. Slightly Slanted Borders & Geometric Shapes
+
+-   Every layout container, header, step card (`.step`), drawing frame (`.graphic-sticky-wrapper`), timeline point (`.timeline-point`), and SVG/Canvas title block or callout badge must feature intentional, slightly slanted geometric angles (`-2.0°` to `+2.0°`) and asymmetric outlines.
+-   **Exemption**: Standard paragraph body text (`.step-paragraph-item`, `.step-description`) is explicitly exempt from slanting and must remain vertical.
+
+---
+
+## 4. Independent & Irregular Drop Shadow Angles (The "Collage / Diorama" Rule)
+
+-   **Irregularity per Element**: Drop shadow distances and offset angles must vary irregularly per text block, per animation stage, and per card.
+-   **Angle Independence (`Shadow Angle != Box Angle`)**: A drop shadow must **never** share the exact same rotation angle as the box casting it.
+    -   **In CSS**: Implement shadows using positioned pseudo-elements (`::before` or `::after` with `background: var(--shadow-solid, #222222); z-index: -1;`) rotated at a slightly different angle (`--shadow-tilt`) than the box itself (`--step-tilt`, `--tab-tilt`).
+    -   **In Canvas & SVG**: Draw drop shadows as separate underlying polygons or rectangles with an independent rotation transformation before drawing the foreground element.
+
+---
+
+## 5. Three-Tier Typography Hierarchy
+
+1. **Display / Titles / Badges**: Bold mid-century industrial display fonts (`Impact`, `Arial Black`, `Futura`).
+2. **Narrative Body Text / Paragraphs**: Clean, effortlessly readable standard sans-serif / system fonts (`system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif`) with comfortable line height (`1.65`) and normal weight (`400`).
+3. **Technical Specifications & Metadata**: Typewriter monospace fonts (`Courier New`, `Courier`, monospace) exclusively for engineering specifications (`.step-specs`), title blocks, leader callouts, Table of Contents items, and bottom timeline year markers.
+
+---
+
+## 6. Vertical Standard Paragraph Text & 100% Full Opacity at All Times
+
+-   **Standard Text Styling & Vertical Alignment**: Paragraph text must never be broken into visually separate boxes, cards, or tabs. All paragraph text must use standard text styling with clean vertical alignment (`0°` rotation, straight vertical layout).
+-   **100% Full Opacity Guarantee**: Section cards (`.step`) and all text elements (`.step-meta`, `.step-title`, `.step-paragraph-item`, `.step-specs`, `.spec-label`, `.toc-item`, `.toc-num`, `.timeline-point`) must **never be grayed out or dimmed** when inactive. Section text must maintain `opacity: 1 !important;` and bright white/light-gray text colors at all times.
+
+---
+
+## 7. Zero CSS Transitions / Layout Animations (Speedometer Benchmark Accuracy)
+
+-   In the Speedometer synchronous test harness, `window.requestAnimationFrame` is intercepted and flushed synchronously before measuring `page.layout()`.
+-   When CSS transitions or animations are present, DOM elements get trapped in asynchronous intermediate states, corrupting benchmark frame timing and layout snapshots.
+-   **Rule**: All CSS transitions and inline JS animations must remain disabled globally (`transition: none !important; animation: none !important;`). All state updates (active card highlighting, TOC collapsing, timeline visibility) must occur instantaneously and synchronously.
+
+---
+
+## 8. Dynamic Animation-Specific Procedural Color Highlights (Zero Permanent Brush Backgrounds)
+
+-   **No Static Bitmap Brush Backgrounds**: Permanent watercolor brush background textures (`bw_watercolor_texture.webp`, `wcWash`, `wc1`, `wc2`, `wc3`) must never be rendered over stage backgrounds or animations.
+-   **Dynamic Procedural Highlights**: Color accents are permitted exclusively as dynamic, animation-specific HTML5 Canvas 2D fills and gradients that animate from `0.0` as scroll progress advances (e.g., foliage emerald canopies, oak log carpentry, aquifer sapphire water tables, kiln-fired red brick terracotta walls, golden sunlight rays, hydraulic sluice cyan water, laser transit neon beams, and geothermal radiant convection loops).
+
+---
+
+## 9. Tiling Drafting Grid Asset & Interactive Navigation Overlays
+
+-   **Tiling Grid Asset**: Use our standalone SVG grid asset (`drafting_grid_tiling.svg` with large ~1cm intersection dots and fine ~1mm dotted connecting lines) tiled via CSS `background-repeat: repeat` and Canvas 2D `IMAGE_SOURCES.grid`.
+-   **Collapsible TOC & Bottom Timeline Overlays**: Both navigation overlays must remain hidden at the top of the page (`.is-hidden`) and appear synchronously without CSS transitions after scrolling past the header title threshold (~300px).
+
+---
+
+## Onboarding & Best Practices: The `/learn` Command
+
+When onboarding to or modifying this scrollytelling benchmark workload, we strongly recommend that all engineers, agents, and subagents use the `/learn` slash command to familiarize themselves with these 9 architectural rules, benchmark constraints, and styling guardrails before making code changes or submitting pull requests.

suites-experimental/scrollytelling/dist/index.html

@@ -0,0 +1,104 @@
+<!DOCTYPE html>
+<!--
+  Copyright (C) 2024 Apple Inc. All rights reserved.
+  Copyright (C) 2024 Google Inc. All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions
+  are met:
+  1. Redistributions of source code must retain the above copyright
+     notice, this list of conditions and the following disclaimer.
+  2. Redistributions in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+
+  THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
+  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
+  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+  THE POSSIBILITY OF SUCH DAMAGE.
+-->
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Project A-101: The Homestead Dossier - Speedometer Scrollytelling Workload</title>
+        <link rel="stylesheet" href="./styles.css" />
+        <script>
+            // Speedometer rAF interception and servicing pattern
+            // Intercepts requestAnimationFrame so that Speedometer can synchronously flush
+            // any pending animation/scroll callbacks before invoking page.layout().
+            const rAFCallbacks = new Map();
+            let rAFId = 1;
+
+            window.requestAnimationFrame = function (callback) {
+                const id = rAFId++;
+                rAFCallbacks.set(id, callback);
+                return id;
+            };
+
+            window.cancelAnimationFrame = function (id) {
+                rAFCallbacks.delete(id);
+            };
+
+            window.serviceRAF = function () {
+                // 1. Synchronously execute any queued rAF callbacks (e.g. from scrollama or scroll listeners)
+                let iterations = 0;
+                while (rAFCallbacks.size > 0 && iterations < 10) {
+                    iterations++;
+                    const callbacks = Array.from(rAFCallbacks.values());
+                    rAFCallbacks.clear();
+                    const now = performance.now();
+                    for (const callback of callbacks) {
+                        try {
+                            callback(now);
+                        } catch (e) {
+                            console.error("Error in rAF callback:", e);
+                        }
+                    }
+                }
+                // 2. Synchronously settle all visual mutations and scrollytelling state before page.layout()
+                if (typeof window.forceScrollytellingUpdate === "function") {
+                    window.forceScrollytellingUpdate();
+                }
+            };
+        </script>
+    </head>
+    <body>
+        <div id="app">
+            <header class="page-header">
+                <h1>Project A-101: The Homestead Dossier</h1>
+                <p class="subtitle">246 Years of Residential Anatomy & Engineering</p>
+                <div class="header-status">
+                    <span id="active-stage-label" class="status-tag">STAGE 1: EARLY SETTLEMENT</span>
+                </div>
+            </header>
+            <nav id="floating-toc" class="floating-toc is-hidden" aria-label="Table of Contents">
+                <div class="toc-header">
+                    <button id="toc-toggle-btn" class="toc-toggle-btn" type="button" aria-expanded="true" aria-controls="toc-list" aria-label="Toggle Table of Contents">
+                        <span class="toc-title">INDEX</span>
+                        <span id="toc-toggle-symbol" class="toc-toggle-symbol">[ - ]</span>
+                    </button>
+                </div>
+                <ul class="toc-list" id="toc-list"></ul>
+            </nav>
+            <main class="scrolly-container" id="scrolly-container">
+                <!-- Stage sections rendered dynamically by app.js from content.js -->
+            </main>
+            <footer class="page-footer">
+                <p>Speedometer Experimental Scrollytelling Benchmark Workload</p>
+            </footer>
+        </div>
+        <script type="module" src="./app.js"></script>
+        <nav id="bottom-timeline-overlay" class="bottom-timeline-overlay is-visible" aria-label="Timeline Navigation">
+            <div class="timeline-track"></div>
+            <ul class="timeline-points" id="timeline-points"></ul>
+        </nav>
+    </body>
+</html>