@juspay/svelte-ui-components 4.33.2 → 4.34.0

package/dist/ThinkingOrb/orb/modes/form.js

@@ -11,7 +11,7 @@
  * split keeps "the shape's own motion" and "the camera's fixed angle on it"
  * from tangling together in the per-dot math.
  */
-import { easeInOutCubic, hashUnit, modeSizing, project, rotateX, rotateY, rotateZ } from '../space';
+import { easeInOutCubic, hashUnit, modeSizing, project, rotateX, rotateY, rotateZ, sampleSphere } from '../space';
 const TWO_PI = Math.PI * 2;
 /** The shared "reads as a form inside a square" contract: radius as a share of `size`. */
 const FORM_RADIUS_RATIO = 0.4;
@@ -45,7 +45,11 @@ const EMPTY_STROKES = [];
 // --- composing ---------------------------------------------------------
 /** Dots along each thread at 64px; `countAlongPath` keeps their spacing as the canvas shrinks. */
 const RIBBON_PER_THREAD_BASE = 36;
-const RIBBON_BASE_DOT_RADIUS = 2.2;
+/** Reference parity (BZ-6466 follow-up): upstream thinking-orbs' `ribbon` mode resolves to a
+ * ~0.9-1.1px base dot radius at 64px (its BASE_PROFILES rBase 1.1, x0.85 for this preset's `size`
+ * multiplier). This used to carry 2.2px, exactly the radius that fused composing's dots into a
+ * solid corrugated band instead of the reference's fine, individually-visible beads. */
+const RIBBON_BASE_DOT_RADIUS = 1.2;
 /** Fewer, narrower threads than a full band: at 7 threads across 0.4 rad the 64px ribbon covered
  * most of the sphere and read as a filled ball rather than a strip of cloth. */
 const RIBBON_THREADS = { 64: 5, 32: 4, 20: 3 };
@@ -68,6 +72,16 @@ const RIBBON_CAMERA_TILT = 0.45;
  * combined ink/alpha/radius fade would collapse an edge row to a speck. */
 const RIBBON_EDGE_ALPHA_FLOOR = 0.5;
 const RIBBON_EDGE_INK_LIFT = 0.22;
+/** Reference parity (BZ-6466 follow-up): upstream's `ribbon` mode fills the sphere behind the band
+ * with a faint, fully static "ghost" texture (150 dots at 64px, this preset's `spin: 0` freezing
+ * even the shared camera precession that would otherwise turn it). Ours had no such backing layer,
+ * so the ribbon read as a thin strip floating in empty space rather than cloth wrapped on a solid
+ * form -- the ribbon's own turn was the only motion on screen, with nothing to anchor it against. */
+const RIBBON_GHOST_BASE_COUNT = 110;
+const RIBBON_GHOST_RADIUS_PX = 0.5;
+const RIBBON_GHOST_INK = 0.3;
+const RIBBON_GHOST_ALPHA_BASE = 0.16;
+const RIBBON_GHOST_ALPHA_DEPTH = 0.22;
 /**
  * A ribbon of dots looped once around the sphere on its own tilted great
  * circle -- distinct from the spin axis -- rippling along its length like a
@@ -80,7 +94,20 @@ export const composing = (t, ctx) => {
     const threads = RIBBON_THREADS[ctx.size];
     const perThread = sizing.countAlongPath(RIBBON_PER_THREAD_BASE);
     const total = threads * perThread;
-    const dots = [];
+    const ghostCount = Math.max(20, sizing.count(RIBBON_GHOST_BASE_COUNT));
+    const dots = Array.from({ length: ghostCount }, (_unused, i) => {
+        const point = sampleSphere(i, ghostCount, worldRadius);
+        const tilted = rotateX(point, RIBBON_CAMERA_TILT);
+        const projected = project(tilted, originPx, worldRadius);
+        return {
+            x: projected.x,
+            y: projected.y,
+            depth: projected.depth,
+            radius: sizing.radius(RIBBON_GHOST_RADIUS_PX),
+            ink: RIBBON_GHOST_INK,
+            alpha: clamp01(RIBBON_GHOST_ALPHA_BASE + RIBBON_GHOST_ALPHA_DEPTH * projected.depth)
+        };
+    });
     for (let index = 0; index < total; index += 1) {
         const thread = index % threads;
         const step = Math.floor(index / threads);

package/dist/ThinkingOrb/orb/modes/network.d.ts

@@ -6,7 +6,11 @@
  * projection setup below.
  */
 import type { ModeFn } from '../types';
+import type { ModeSizing } from '../space';
 /** A few nodes on a sphere; lines to near neighbours carry small travelling pulses. */
 export declare const connecting: ModeFn;
+/** Exported so tests that index `weaving`'s strand dots can reproduce and slice off this count,
+ * rather than duplicating the formula as a hardcoded literal. */
+export declare const weavingGhostCount: (sizing: ModeSizing) => number;
 /** Three closed strands wrapped around a sphere, crossing over and under each other as they turn. */
 export declare const weaving: ModeFn;

package/dist/ThinkingOrb/orb/modes/network.js

@@ -144,6 +144,21 @@ const STRAND_DOT_SIZE_FACTOR = { 64: 1, 32: 0.85, 20: 0.7 };
 const STRAND_DEPTH_INK = 0.45;
 /** A slight per-strand shade; the paths and their over/under crossings are what separate them. */
 const STRAND_SHADE_STEP = 0.1;
+/** Reference parity (BZ-6466 follow-up): upstream's `braid` mode fills the sphere behind the
+ * strands with a faint, static-in-object-space "ghost" texture (150 dots at 64px) that shares the
+ * strands' own turn, so the strands read as plaiting round a solid ball rather than floating loops
+ * in empty space. Ours had no such backing layer. Always appended after every strand's dots, so
+ * code and tests that index `dots` by strand can slice it off by a known, reproducible count. */
+const STRAND_GHOST_BASE_COUNT = 110;
+const STRAND_GHOST_RADIUS_PX = 0.5;
+const STRAND_GHOST_INK = 0.3;
+/** With STRAND_GHOST_INK 0.3, `inkAlpha` = (1-ink)*alpha = 0.7*alpha, so this needs to clear
+ * 0.1/0.7 for the "nothing paints below 10% opacity" contract even on a ghost dot's far side. */
+const STRAND_GHOST_ALPHA_BASE = 0.16;
+const STRAND_GHOST_ALPHA_DEPTH = 0.22;
+/** Exported so tests that index `weaving`'s strand dots can reproduce and slice off this count,
+ * rather than duplicating the formula as a hardcoded literal. */
+export const weavingGhostCount = (sizing) => Math.max(20, sizing.count(STRAND_GHOST_BASE_COUNT));
 const strandBaseAngle = (strand) => (strand / STRAND_COUNT) * Math.PI * 2;
 /**
  * The `pointIndex`-th of `pointsPerStrand` points around closed `strand`: a
@@ -192,5 +207,22 @@ export const weaving = (t, ctx) => {
             alpha: 0.6 + depth * 0.35
         };
     }));
-    return { dots, strokes };
+    // Shares the strands' own spin+tilt (not their per-strand inclination/phase, which is strand
+    // geometry, not camera) so the backdrop turns together with what it is behind.
+    const ghostCount = weavingGhostCount(sizing);
+    const ghosts = Array.from({ length: ghostCount }, (_unused, i) => {
+        const point = sampleSphere(i, ghostCount, sphereRadius);
+        const spun = rotateY(point, t * STRAND_ROTATE_SPEED);
+        const tilted = rotateX(spun, STRAND_TILT);
+        const projected = project(tilted, originPx, sphereRadius);
+        return {
+            x: projected.x,
+            y: projected.y,
+            depth: projected.depth,
+            radius: sizing.radius(STRAND_GHOST_RADIUS_PX),
+            ink: STRAND_GHOST_INK,
+            alpha: clamp01(STRAND_GHOST_ALPHA_BASE + STRAND_GHOST_ALPHA_DEPTH * projected.depth)
+        };
+    });
+    return { dots: [...dots, ...ghosts], strokes };
 };

package/dist/ThinkingOrb/orb/modes/sphere.js

@@ -44,19 +44,33 @@ const toStroke = (from, to, width, ink, alpha) => ({
 /** Particles travel in short trailing arcs ("trains") rather than scattering
  * independently around their orbit -- a lone random phase per particle reads
  * as noise once density thins the count out at 32/20px, while a handful of
- * particles held close together always reads as motion along a path. */
-const WORKING_TRAIN_BASE_COUNT = 22;
+ * particles held close together always reads as motion along a path.
+ *
+ * Reference parity (BZ-6466 follow-up): the upstream thinking-orbs `orbits`
+ * mode this was ported from draws 12 orbits x 3 particles = 36 marks at
+ * 64px, radius ~1.2px, and reads as a sparse field of distinct particles.
+ * The previous tuning here (22 trains x 5-long, radius 2.2px = 110 marks)
+ * packed 3x the marks at ~1.7x the radius into the same arcs, so consecutive
+ * dots overlapped their own diameter and the whole thing fused into a
+ * blurred scribble instead of scattered points. */
+const WORKING_TRAIN_BASE_COUNT = 12;
 /** Keeps at least this many short arcs on screen at 64px (32/20px use WORKING_SMALL_LAYOUT). The
  * area scaler alone already clears it at the default density; it only bites when density is low. */
 const WORKING_MIN_TRAINS_64 = 3;
-const WORKING_TRAIN_LENGTH = 5;
+const WORKING_TRAIN_LENGTH = 3;
 /** How far apart, in radians, a train's particles trail behind its lead --
  * wide enough to read as a short curved arc, short enough to stay a cluster
  * rather than smearing back into the full-orbit scatter this replaces. */
 const WORKING_TRAIN_ARC_SPAN = 0.5;
-/** At 1.6, with a +/-25% jitter, 20px dots came out 0.6-1px across and the arcs blurred into a
- * smudge; this and the narrower jitter below keep a train a visible stroke at every size. */
-const WORKING_BASE_RADIUS_PX = 2.2;
+/** Reference's `orbits` mode draws particles at ~1.2px on a 64px canvas but scales them back UP
+ * at smaller sizes (2.4x at 20px) rather than shrinking further, so they stay legible once there's
+ * less room for arc spacing to keep them apart. `sizing.radius`'s sub-linear shrink-with-a-floor
+ * goes the other way, so the two sizes need their own base rather than one shared constant. */
+const WORKING_BASE_RADIUS_PX = 1.3;
+/** 32/20px (WORKING_SMALL_LAYOUT): kept at this mode's original, pre-reference-parity radius --
+ * these sizes weren't the fused-blur regression 64px was, and shrinking to match 64px's new,
+ * smaller radius here would drop dots below a legible stroke width. */
+const WORKING_SMALL_BASE_RADIUS_PX = 2.2;
 const WORKING_ORBIT_COUNT = 6;
 const WORKING_ANGULAR_SPEED = 1.1;
 /** How far an orbit's `weight` can push its dots' ink away from the shared
@@ -68,6 +82,17 @@ const WORKING_ORBIT_ALPHA_FLOOR = 0.65;
 /** A train's trailing-most particle never fades past this floor, so the arc's
  * tail stays legible instead of thinning away to nothing. */
 const WORKING_TRAIL_ALPHA_FLOOR = 0.35;
+/** Reference parity (BZ-6466 follow-up): upstream's `orbits` mode traces each orbit's full circle
+ * as a faint, static "ghost" ring of many dots (40 per orbit at 64px) UNDER the few bright
+ * travelling particles -- about 13x as many ghost dots as particles, so the ring lattice anchors
+ * the silhouette and the particles read as a sparkle on top of it. Ours had no such layer: every
+ * visible dot was one of the sweeping particles, so with only 6-22 of them the whole silhouette
+ * reshaped every frame instead of holding a roughly stable shape -- the actual "fluidity" gap a
+ * static/moving frame comparison alone doesn't show. */
+const WORKING_GHOST_DOTS_PER_ORBIT = 40;
+const WORKING_GHOST_RADIUS_PX = 0.7;
+const WORKING_GHOST_INK = 0.4;
+const WORKING_GHOST_ALPHA = 0.5;
 /** Every particle's own orbital plane, radius, pace and shading weight, keyed by its orbit. */
 const workingOrbit = (orbit) => {
     const seed = orbit * 31 + 7;
@@ -84,8 +109,10 @@ const workingOrbit = (orbit) => {
  * the view axis (like an atom symbol) and give each train a long arc, so every train draws a
  * visible curve and the separate orbits stay readable. */
 const WORKING_SMALL_LAYOUT = {
-    32: { orbits: 4, trainLength: 6, arcSpan: 1 },
-    20: { orbits: 3, trainLength: 7, arcSpan: 1.25 }
+    // Shorter trains than before (was 6/7): at the smaller shared radius above, a longer train's
+    // dots sat closer together than their own diameter and fused the same way 64px did.
+    32: { orbits: 4, trainLength: 4, arcSpan: 0.75 },
+    20: { orbits: 3, trainLength: 4, arcSpan: 0.9 }
 };
 /** How far each small-size orbit tips out of edge-on. Its projection is an ellipse sin(tilt) as
  * tall as it is wide; near 1 rad every orbit projects to nearly the same circle and rolling it
@@ -147,10 +174,32 @@ export const working = (t, ctx) => {
                 (orbit.weight - 0.5) * WORKING_ORBIT_INK_SPREAD;
             const alpha = (WORKING_TRAIL_ALPHA_FLOOR + (1 - WORKING_TRAIL_ALPHA_FLOOR) * trail) *
                 (WORKING_ORBIT_ALPHA_FLOOR + (1 - WORKING_ORBIT_ALPHA_FLOOR) * orbit.weight);
-            const radius = sizing.radius(WORKING_BASE_RADIUS_PX) * (0.9 + 0.25 * hashUnit(seed + 3));
+            const radiusBase = small ? WORKING_SMALL_BASE_RADIUS_PX : WORKING_BASE_RADIUS_PX;
+            const radius = sizing.radius(radiusBase) * (0.9 + 0.25 * hashUnit(seed + 3));
             dots.push(toDot(projected, radius, ink, alpha));
         }
     }
+    // 64px only: 32/20px already anchor their orbits with the faint stroke path below, drawn for
+    // every size in WORKING_SMALL_LAYOUT.
+    if (!small) {
+        const ghostDotsPerOrbit = Math.max(8, sizing.countAlongPath(WORKING_GHOST_DOTS_PER_ORBIT));
+        for (let orbitIndex = 0; orbitIndex < WORKING_ORBIT_COUNT; orbitIndex += 1) {
+            const orbit = workingOrbit(orbitIndex);
+            const orbitRadius = worldRadius * orbit.orbitRadiusFactor;
+            for (let k = 0; k < ghostDotsPerOrbit; k += 1) {
+                const angle = (k / ghostDotsPerOrbit) * TWO_PI;
+                const planar = {
+                    x: Math.cos(angle) * orbitRadius,
+                    y: 0,
+                    z: Math.sin(angle) * orbitRadius
+                };
+                const tilted = rotateX(planar, orbit.tilt);
+                const point = rotateZ(tilted, orbit.roll);
+                const projected = project(point, origin, worldRadius);
+                dots.push(toDot(projected, sizing.radius(WORKING_GHOST_RADIUS_PX), WORKING_GHOST_INK, WORKING_GHOST_ALPHA * (0.4 + 0.6 * projected.depth)));
+            }
+        }
+    }
     const paths = small
         ? Array.from({ length: small.orbits }, (_unused, orbitIndex) => {
             const orbit = workingSmallOrbit(orbitIndex, small.orbits);
@@ -236,10 +285,16 @@ export const searching = (t, ctx) => {
 };
 // ---------------------------------------------------------------------------
 // solving -- tiers that snap a quarter turn out of alignment, hold scrambled,
-// then resolve back, on a loop. Landmark dots and fixed seam rings make the
-// misalignment legible: an otherwise-uniform, evenly-sampled dot texture
-// looks identical under any rotation about the spin axis, so turning a
-// "band" of it invisibly wouldn't read as scrambling at all.
+// then resolve back, on a loop. Each tier's own texture dots rotate with it
+// (reference parity, BZ-6466 follow-up: matching upstream thinking-orbs'
+// `rubik`, which reads solved-vs-scrambled off this same per-band rotation
+// alone), so the misalignment shows as a visible discontinuity in the dot
+// pattern itself; oversized landmark dots add a brighter set of accent
+// points per tier. An earlier tuning also drew fixed seam rings and
+// per-landmark meridian strokes to make the misalignment legible, but next
+// to the reference that wireframe read as a busy skeleton the upstream
+// version doesn't have, so it's gone -- the texture's own rotation already
+// carries the same information.
 // ---------------------------------------------------------------------------
 const SOLVING_BASE_COUNT = 130;
 const SOLVING_BASE_RADIUS_PX = 1.5;
@@ -260,23 +315,6 @@ const SOLVING_LANDMARK_PHASE = hashUnit(5) * TWO_PI;
 const SOLVING_LANDMARK_RADIUS_PX = 3.1;
 const SOLVING_LANDMARK_INK_BOOST = 0.45;
 const SOLVING_LANDMARK_ALPHA = 0.9;
-/** Each landmark also draws a short meridian stroke spanning its tier. Solved, the strokes of all
- * tiers join into three unbroken vertical lines; a turned tier's strokes jump sideways and break
- * the lines into a visible staircase. Held scrambled, loose landmark dots alone still formed tidy
- * columns of their own and read as just another solved pose. */
-const SOLVING_MERIDIAN_POINTS_PER_TIER = 3;
-const SOLVING_MERIDIAN_WIDTH_PX = 1.6;
-const SOLVING_MERIDIAN_INK_BOOST = 0.35;
-const SOLVING_MERIDIAN_ALPHA = 0.85;
-/** The meridians stop this far short of the poles, where all three would otherwise converge. */
-const SOLVING_MERIDIAN_Y_LIMIT = 0.9;
-/** A static ring of short strokes at each cut between tiers, unaffected by
- * any turn, so the "cut into bands" structure reads even while the puzzle
- * sits solved and nothing is moving. */
-const SOLVING_SEAM_SEGMENTS = 12;
-const SOLVING_SEAM_STROKE_RADIUS = 1.05;
-const SOLVING_SEAM_INK = 0.15;
-const SOLVING_SEAM_ALPHA = 0.5;
 const solvingTurnStart = (tier) => tier * SOLVING_TURN_GAP;
 const solvingTurnEnd = (tier) => solvingTurnStart(tier) + SOLVING_TURN_DURATION;
 const SOLVING_HOLD_START = solvingTurnEnd(SOLVING_TIER_COUNT - 1) + SOLVING_HOLD_GAP;
@@ -310,8 +348,6 @@ const solvingTierOf = (yUnit) => clamp(Math.floor(((1 - yUnit) / 2) * SOLVING_TI
 const solvingTierDirection = (tier) => (hashUnit(tier * 53 + 21) < 0.5 ? -1 : 1);
 /** The y-unit (-1..1) at the centre of a tier's latitude band. */
 const solvingTierCenterYUnit = (tier) => 1 - (2 * tier + 1) / SOLVING_TIER_COUNT;
-/** The y-unit (-1..1) of the fixed cut between one tier and the next. */
-const solvingSeamYUnit = (seam) => 1 - (2 * (seam + 1)) / SOLVING_TIER_COUNT;
 const solvingTurnAngle = (tier, cyclePos) => solvingTierTurn(tier, cyclePos) * solvingTierDirection(tier) * (Math.PI / 2);
 export const solving = (t, ctx) => {
     const sizing = modeSizing(ctx.size, ctx.density, ctx.dotScale);
@@ -349,47 +385,7 @@ export const solving = (t, ctx) => {
         const ink = shadeByDepth(projected.depth) - SOLVING_LANDMARK_INK_BOOST;
         return toDot(projected, sizing.radius(SOLVING_LANDMARK_RADIUS_PX), ink, SOLVING_LANDMARK_ALPHA);
     });
-    const seamWidth = sizing.radius(SOLVING_SEAM_STROKE_RADIUS);
-    const seams = Array.from({ length: SOLVING_TIER_COUNT - 1 }, (_unused, seam) => {
-        const yUnit = solvingSeamYUnit(seam);
-        const y = yUnit * worldRadius;
-        const ringRadius = Math.sqrt(Math.max(0, 1 - yUnit * yUnit)) * worldRadius;
-        const ringPoints = Array.from({ length: SOLVING_SEAM_SEGMENTS + 1 }, (_unusedPoint, j) => {
-            const angle = (j / SOLVING_SEAM_SEGMENTS) * TWO_PI;
-            const point = {
-                x: Math.cos(angle) * ringRadius,
-                y,
-                z: Math.sin(angle) * ringRadius
-            };
-            return project(rotateX(point, SOLVING_TILT), origin, worldRadius);
-        });
-        return Array.from({ length: SOLVING_SEAM_SEGMENTS }, (_unusedSegment, j) => toStroke(ringPoints[j], ringPoints[j + 1], seamWidth, SOLVING_SEAM_INK, SOLVING_SEAM_ALPHA));
-    }).flat();
-    const meridianWidth = sizing.radius(SOLVING_MERIDIAN_WIDTH_PX);
-    const meridians = Array.from({ length: SOLVING_TIER_COUNT * SOLVING_LANDMARKS_PER_TIER }, (_unused, i) => {
-        const tier = Math.floor(i / SOLVING_LANDMARKS_PER_TIER);
-        const slot = i % SOLVING_LANDMARKS_PER_TIER;
-        const longitude = SOLVING_LANDMARK_PHASE + (slot / SOLVING_LANDMARKS_PER_TIER) * TWO_PI;
-        const topYUnit = Math.min(SOLVING_MERIDIAN_Y_LIMIT, 1 - (2 * tier) / SOLVING_TIER_COUNT);
-        const bottomYUnit = Math.max(-SOLVING_MERIDIAN_Y_LIMIT, 1 - (2 * (tier + 1)) / SOLVING_TIER_COUNT);
-        const points = Array.from({ length: SOLVING_MERIDIAN_POINTS_PER_TIER }, (_unusedPoint, j) => {
-            const yUnit = topYUnit + ((bottomYUnit - topYUnit) * j) / (SOLVING_MERIDIAN_POINTS_PER_TIER - 1);
-            const ringRadius = Math.sqrt(Math.max(0, 1 - yUnit * yUnit)) * worldRadius;
-            const base = {
-                x: Math.cos(longitude) * ringRadius,
-                y: yUnit * worldRadius,
-                z: Math.sin(longitude) * ringRadius
-            };
-            const turned = rotateY(base, solvingTurnAngle(tier, cyclePos));
-            return project(rotateX(turned, SOLVING_TILT), origin, worldRadius);
-        });
-        return points.slice(1).map((to, j) => {
-            const from = points[j];
-            const depth = (from.depth + to.depth) / 2;
-            return toStroke(from, to, meridianWidth, shadeByDepth(depth) - SOLVING_MERIDIAN_INK_BOOST, SOLVING_MERIDIAN_ALPHA);
-        });
-    }).flat();
-    return { dots: [...texture, ...landmarks], strokes: [...seams, ...meridians] };
+    return { dots: [...texture, ...landmarks], strokes: [] };
 };
 // ---------------------------------------------------------------------------
 // listening -- stacked horizontal rings with a wave rolling through them

package/dist/Toolbar/Toolbar.svelte

@@ -4,6 +4,11 @@
   let {
     showBackButton = true,
     text,
+    title,
+    headingLevel,
+    subtitle,
+    rootTag,
+    variant = 'chrome',
     backIcon,
     backLabel = 'Back',
     backHref,
@@ -18,6 +23,19 @@
     headingTestId
   }: ToolbarProperties = $props();
 
+  // Same validation `Sheet`'s `headingLevel` already applies: through a web
+  // component, an untyped attribute reaches this as anything, and a getter
+  // can throw, so an unusable level degrades to the plain-tag fallback rather
+  // than emitting an invalid `<h7>`/`<h0>`/`<hNaN>`.
+  const headingTag = $derived(
+    typeof headingLevel === 'number' &&
+      Number.isInteger(headingLevel) &&
+      headingLevel >= 1 &&
+      headingLevel <= 6
+      ? `h${headingLevel}`
+      : null
+  );
+
   // `backIcon={null}` (or '') has always meant "render no back control at all", and consumers
   // rely on it; only the DEFAULT changes, from a CDN image to the inline icon.
   const showBackControl = $derived(showBackButton && backIcon !== null && backIcon !== '');
@@ -42,7 +60,13 @@
   };
 </script>
 
-<div class="toolbar {classes ?? ''}" data-pw={testId} testID={testId}>
+<svelte:element
+  this={rootTag ?? 'div'}
+  class="toolbar {classes ?? ''}"
+  data-variant={variant === 'page-header' ? 'page-header' : null}
+  data-pw={testId}
+  testID={testId}
+>
   <div
     class="content"
     data-pw={typeof testId === 'string' ? `${testId}-content` : null}
@@ -82,6 +106,17 @@
       <div class="center-content">
         {@render centerContent()}
       </div>
+    {:else if typeof title === 'string' && title.length > 0}
+      <div class="titles" data-pw={headingTestId} testID={headingTestId}>
+        {#if headingTag !== null}
+          <svelte:element this={headingTag}>{title}</svelte:element>
+        {:else}
+          <span>{title}</span>
+        {/if}
+        {#if typeof subtitle === 'string' && subtitle.length > 0}
+          <p class="subtitle">{subtitle}</p>
+        {/if}
+      </div>
     {:else if typeof text === 'string' && text.length > 0}
       <div class="text" data-pw={headingTestId} testID={headingTestId}>
         {text}
@@ -98,7 +133,7 @@
       {@render additionalContent()}
     {/if}
   </div>
-</div>
+</svelte:element>
 
 <style>
   .toolbar {
@@ -117,6 +152,25 @@
     border-radius: var(--toolbar-border-radius, 0px);
   }
 
+  /* In the page's flow rather than pinned over it: only the fallbacks change,
+     so a consumer's own --toolbar-* values still win. */
+  /* Literal values, not the chrome's variables with other fallbacks: an app
+     that themes its bars at :root (--toolbar-background: white,
+     --toolbar-position: fixed) would otherwise paint and pin every page
+     header too. These six properties ARE the variant; everything else still
+     reads the shared variables. */
+  .toolbar[data-variant='page-header'] {
+    position: static;
+    width: 100%;
+    background: transparent;
+    box-shadow: none;
+    z-index: auto;
+  }
+
+  .toolbar[data-variant='page-header'] > .content {
+    flex-wrap: wrap;
+  }
+
   .content {
     display: flex;
     flex-direction: row;
@@ -160,7 +214,7 @@
     /* A native button so Enter/Space and the accessible name come for free; the reset keeps
        the box identical to the div it replaces. */
     appearance: none;
-    background: none;
+    background: var(--toolbar-back-button-background, none);
     border: 0;
     margin: 0;
     box-sizing: content-box;
@@ -214,4 +268,28 @@
     color: var(--toolbar-text-color, inherit);
     flex: var(--toolbar-text-flex, 1);
   }
+
+  /* `title`/`subtitle`'s heading tag is deliberately unstyled here: a consumer's
+     own global heading rules (size, weight, tracking) already reach it the
+     same way they reach any other heading on the page, and a component-level
+     font-size/font-weight here — even with an `inherit` fallback — would
+     outrank a bare `h1`/`h2` element selector by specificity and silently
+     break that inheritance for every consumer that has one. Only layout and
+     the subtitle's own (independent) presentation get hooks. Both rules are written down the
+     structure they live in (.content > .titles > .subtitle), so a `titles` or `subtitle`
+     class a consumer passes through `classes`, which lands on the root, cannot match them,
+     and the variant is a data attribute rather than a class for the same reason: a class
+     directive would strip a consumer's own `page-header` class (the one the docs recipe
+     uses) from `classes`. */
+  .content > .titles {
+    display: grid;
+    gap: var(--toolbar-titles-gap, 2px);
+    min-width: var(--toolbar-titles-min-width, 0);
+    flex: var(--toolbar-titles-flex, 1);
+  }
+
+  .titles > .subtitle {
+    color: var(--toolbar-subtitle-color, inherit);
+    text-wrap: var(--toolbar-subtitle-text-wrap, pretty);
+  }
 </style>

package/dist/Toolbar/properties.d.ts

@@ -2,6 +2,42 @@ import type { Snippet } from 'svelte';
 export type ToolbarProperties = ToolbarEventProperties & {
     showBackButton?: boolean;
     text?: string | null;
+    /**
+     * A real heading, separate from `text` — which has always rendered a plain,
+     * non-heading div and keeps doing so for existing consumers. Renders as a
+     * heading only once `headingLevel` also resolves to a real level 1-6;
+     * otherwise renders in a plain, non-heading tag instead, same as `text`.
+     */
+    title?: string;
+    /**
+     * The tag `title` renders as (`<svelte:element this={`h${headingLevel}`}>`).
+     * Only 1-6 resolve to a real heading; anything else (including omitting it)
+     * renders `title` in a plain, non-heading tag instead — the same reasoning
+     * `Sheet`'s `headingLevel` already uses, so a stray "7"/"0"/`NaN` reaching
+     * through a web component's untyped attribute degrades the same way there
+     * too, rather than emitting an invalid `<h7>`/`<h0>`/`<hNaN>`.
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Rendered as `<p class="subtitle">` under `title`. Ignored without `title`. */
+    subtitle?: string;
+    /**
+     * The root element's tag, via `<svelte:element>`. Defaults to `div`, i.e.
+     * unconditionally unchanged from every version before this. Set it to give
+     * the toolbar its own landmark (`header`, `nav`, `aside`, `footer`) instead
+     * of a consumer wrapping it in one purely to supply that semantics.
+     */
+    rootTag?: 'div' | 'header' | 'nav' | 'aside' | 'footer';
+    /**
+     * `'chrome'` (the default) is the fixed, full-viewport-width app bar every
+     * version before this rendered. `'page-header'` is the same bar in the page's
+     * flow: position static, width 100%, transparent background, no shadow,
+     * z-index auto, and a content row that wraps (actions drop under the title
+     * when they don't fit). Those six are set directly, not through the chrome's
+     * `--toolbar-position`/`-width`/`-background`/`-box-shadow`/`-z-index`/
+     * `--toolbar-content-flex-wrap`, so a bar themed at :root never leaks into a
+     * page header. Every other `--toolbar-*` variable applies to both.
+     */
+    variant?: ToolbarVariant;
     backIcon?: string | null;
     backLabel?: string;
     /**
@@ -27,3 +63,4 @@ export type ToolbarEventProperties = {
     onbackclick?: () => void;
     onkeydown?: (event: KeyboardEvent) => void;
 };
+export type ToolbarVariant = 'chrome' | 'page-header';

package/dist/WindowedList/WindowedList.svelte

@@ -0,0 +1,129 @@
+<script lang="ts" generics="T">
+  import { tick } from 'svelte';
+  import Button from '../Button/Button.svelte';
+  import type { WindowedListProperties } from './properties';
+
+  let {
+    items,
+    getKey,
+    row,
+    initialCount = 200,
+    step = 200,
+    earlier,
+    earlierLabel = (next: number, hidden: number) => `Show ${next} earlier (${hidden} hidden)`,
+    classes,
+    testId
+  }: WindowedListProperties<T> = $props();
+
+  /* The window is anchored by KEY, not index. An index would slide with every
+     append (the newest N), pushing rows out from under a reader who scrolled up;
+     WebKit has no scroll anchoring to hide that jump. A key stays put while the
+     list grows at the end. If the anchor's key disappears (the list was replaced
+     or truncated), the window re-anchors to the newest `initialCount` -- whichever
+     anchor it was, so a reveal that has since been truncated away cannot fall back
+     to an older, stale one, and the new anchor then holds through later appends.
+
+     `anchorKey` and `appliedReveal` are plain latches, not $state: they are
+     written only inside the derived below, while it recomputes because `items` or
+     `reveal` changed, and nothing else reads them. `reveal` is state: only the
+     "show earlier" handler writes it, as a fresh object per click so a repeated
+     key still reads as a new request. */
+  let anchorKey: string | null = null;
+  let appliedReveal: { key: string | null } | null = null;
+  let reveal = $state.raw<{ key: string | null } | null>(null);
+
+  function indexOfKey(key: string | null): number {
+    return key === null ? -1 : items.findIndex((item) => getKey(item) === key);
+  }
+
+  function keyAt(index: number): string | null {
+    return items.slice(index, index + 1).map(getKey)[0] ?? null;
+  }
+
+  const start = $derived.by(() => {
+    if (reveal !== appliedReveal) {
+      appliedReveal = reveal;
+      anchorKey = reveal?.key ?? null;
+    }
+    const anchored = indexOfKey(anchorKey);
+    if (anchored >= 0) {
+      return anchored;
+    }
+    const fresh = Math.max(0, items.length - initialCount);
+    anchorKey = keyAt(fresh);
+    return fresh;
+  });
+  const shown = $derived(items.slice(start));
+  const next = $derived(Math.min(step, start));
+
+  let controlEl: HTMLElement | null = $state(null);
+
+  function scrollParent(node: HTMLElement): HTMLElement | null {
+    for (let el = node.parentElement; el !== null; el = el.parentElement) {
+      if (/(auto|scroll|overlay)/.test(getComputedStyle(el).overflowY)) {
+        return el;
+      }
+    }
+    return document.scrollingElement instanceof HTMLElement ? document.scrollingElement : null;
+  }
+
+  /* Reveals `next` more above the window. The first row that was already
+     rendered is measured before and after, and the scroller moves by the
+     difference, so what the reader was looking at stays where it was. Browser
+     scroll anchoring may already have done this (the difference is then ~0);
+     WebKit has none, and there it is the whole fix. */
+  async function showEarlier(): Promise<void> {
+    if (start === 0) {
+      return;
+    }
+    const firstRow = controlEl?.nextElementSibling ?? null;
+    const before = firstRow instanceof HTMLElement ? firstRow.getBoundingClientRect().top : null;
+    reveal = { key: keyAt(Math.max(0, start - step)) };
+    await tick();
+    if (firstRow instanceof HTMLElement && before !== null && firstRow.isConnected) {
+      const scroller = scrollParent(firstRow);
+      const delta = firstRow.getBoundingClientRect().top - before;
+      if (scroller !== null && delta !== 0) {
+        scroller.scrollTop += delta;
+      }
+    }
+  }
+</script>
+
+<div
+  class="windowed-list {classes ?? ''}"
+  data-pw={typeof testId === 'string' ? testId : null}
+  testID={typeof testId === 'string' ? testId : null}
+>
+  {#if start > 0}
+    <div class="windowed-list-earlier" bind:this={controlEl}>
+      {#if typeof earlier === 'function'}
+        {@render earlier({ hidden: start, next, showEarlier })}
+      {:else}
+        <Button text={earlierLabel(next, start)} onclick={() => void showEarlier()} />
+      {/if}
+    </div>
+  {/if}
+  {#each shown as item, i (getKey(item))}
+    {@render row({ item, index: start + i, isFirst: i === 0 })}
+  {/each}
+</div>
+
+<style>
+  /* `contents` by default: the rows stay children of the consumer's own layout
+     (a flex column's gap, a grid's tracks), exactly as if they were rendered
+     without this wrapper. Set `--windowed-list-display` to give the list a box
+     of its own. */
+  .windowed-list {
+    display: var(--windowed-list-display, contents);
+  }
+
+  .windowed-list-earlier {
+    display: flex;
+    justify-content: var(--windowed-list-earlier-justify, center);
+    padding: var(--windowed-list-earlier-padding, 8px 0);
+    /* The control must never be what the browser anchors on: it is about to
+       have rows inserted directly under it. */
+    overflow-anchor: none;
+  }
+</style>