camox 0.44.0 → 0.45.0

package/dist/features/canvas/canvasCamera.js

@@ -0,0 +1,229 @@
+//#region src/features/canvas/canvasCamera.ts
+/** Require 80% horizontal visibility; stable input order breaks center-distance ties. */
+function findCanvasSnapTarget(camera, viewport, targets) {
+	let closest;
+	let distance = Infinity;
+	for (const target of targets) {
+		const left = camera.x + target.left * camera.scale;
+		const right = left + target.width * camera.scale;
+		if (Math.max(0, Math.min(right, viewport.width) - Math.max(left, 0)) + 1e-8 < (right - left) * .8) continue;
+		const nextDistance = Math.abs((left + right - viewport.width) / 2);
+		if (nextDistance >= distance) continue;
+		closest = target;
+		distance = nextDistance;
+	}
+	return closest;
+}
+const CANVAS_PADDING = 64;
+/** Screen-space inset of a Page snapped to fit the viewport's width. */
+const CANVAS_PAGE_FIT_PADDING = 24;
+const MAX_CANVAS_ZOOM = 2;
+/**
+* Below this, Pages are too small to read while every frame comes near the
+* camera, so painting and panning slow down with the size of the site.
+*/
+const MIN_CANVAS_ZOOM = .1;
+/** Log-scale zoom per pixel of Ctrl/⌘ + wheel, including trackpad pinches. */
+const CANVAS_WHEEL_ZOOM_RATE = .01056;
+/** Relative (log-scale) bands make the detent feel the same at every page width. */
+const ZOOM_SNAP_CAPTURE = .14;
+const ZOOM_SNAP_RELEASE = .18;
+/** Fractions of viewport width: acquire near center, then hold a wider detent. */
+const PAN_SNAP_CAPTURE = .12;
+const PAN_SNAP_RELEASE = .18;
+function isCanvasPageScale(scale, pageScale) {
+	return pageScale !== void 0 && Math.abs(Math.log(scale / pageScale)) < 1e-8;
+}
+/** Snapped to a target: at its page fit, centered on it. */
+function isCanvasCameraSnapped(camera, viewport, target) {
+	const fit = fitCanvasPage(viewport, target);
+	return isCanvasPageScale(camera.scale, fit.scale) && Math.abs(camera.x - fit.x) < .5;
+}
+/**
+* The most zoomed-in view: the page fit, where the camera snaps to its targets.
+* Without targets, the zoom ceiling is MAX_CANVAS_ZOOM.
+*/
+function canvasMaximumScale(viewport, targets, minimumScale) {
+	if (!targets.length) return 2;
+	const width = Math.min(...targets.map((target) => target.width));
+	return Math.max(minimumScale, fitCanvasPage(viewport, {
+		left: 0,
+		width
+	}).scale);
+}
+/**
+* intendedScale is accumulated independently of the displayed scale, so gentle
+* input can escape the detent. Large steps outside the band pass straight through.
+* The page fit is also the zoom ceiling, so only zooming out leaves the detent.
+*/
+function snapCanvasZoom(scale, intendedScale, pageScale) {
+	if (pageScale === void 0) return intendedScale;
+	const band = isCanvasPageScale(scale, pageScale) ? ZOOM_SNAP_RELEASE : ZOOM_SNAP_CAPTURE;
+	return Math.abs(Math.log(intendedScale / pageScale)) <= band ? pageScale : intendedScale;
+}
+/** At most, the camera stretches this far past a zoom limit (log scale). */
+const ZOOM_STRETCH = Math.log(1.2);
+/** How much the first input past a limit still zooms, as in iOS overscroll. */
+const ZOOM_STRETCH_RESISTANCE = .55;
+/**
+* Past a zoom limit, intent stretches the view with growing resistance and
+* never beyond ZOOM_STRETCH. Within the limits it is the intended scale.
+*/
+function stretchCanvasZoom(intendedScale, minimumScale, maximumScale) {
+	const limit = Math.min(maximumScale, Math.max(minimumScale, intendedScale));
+	const overshoot = Math.log(intendedScale / limit);
+	const distance = Math.abs(overshoot) * ZOOM_STRETCH_RESISTANCE;
+	return limit * Math.exp(Math.sign(overshoot) * (ZOOM_STRETCH * distance / (ZOOM_STRETCH + distance)));
+}
+/** The intended scale that stretches to a displayed scale: the inverse of stretchCanvasZoom. */
+function unstretchCanvasZoom(scale, minimumScale, maximumScale) {
+	const limit = Math.min(maximumScale, Math.max(minimumScale, scale));
+	const stretch = Math.min(Math.abs(Math.log(scale / limit)), ZOOM_STRETCH * (1 - 1e-9));
+	const overshoot = ZOOM_STRETCH * stretch / ((ZOOM_STRETCH - stretch) * ZOOM_STRETCH_RESISTANCE);
+	return limit * Math.exp(Math.sign(Math.log(scale / limit)) * overshoot);
+}
+const RAIL_EVIDENCE_MS = 80;
+const RAIL_INTENT_PX = 16;
+const RAIL_CAPTURE_RATIO = .65;
+const RAIL_RELEASE_RATIO = .9;
+/**
+* Small startup deltas are evidence, not a permanent rejection of vertical intent.
+* Sum magnitudes in a short window so sign-changing jitter cannot cancel out.
+* Once deliberate two-axis intent wins, never reacquire on its momentum tail.
+*/
+function canvasVerticalRail(delta, time, previous) {
+	if (previous?.mode === "free") return previous;
+	const mode = previous?.mode ?? "pending";
+	const x = Math.abs(delta.x);
+	const y = Math.abs(delta.y);
+	if (mode === "vertical" && x <= y * RAIL_RELEASE_RATIO) return {
+		mode,
+		samples: []
+	};
+	const samples = [...(previous?.samples ?? []).filter((sample) => time - sample.time < RAIL_EVIDENCE_MS), {
+		x,
+		y,
+		time
+	}];
+	const evidence = samples.reduce((sum, sample) => ({
+		x: sum.x + sample.x,
+		y: sum.y + sample.y
+	}), {
+		x: 0,
+		y: 0
+	});
+	if (Math.max(evidence.x, evidence.y) < RAIL_INTENT_PX) return {
+		mode,
+		samples
+	};
+	if (mode === "vertical") return {
+		mode: "free",
+		samples: []
+	};
+	return {
+		mode: evidence.x <= evidence.y * RAIL_CAPTURE_RATIO ? "vertical" : "free",
+		samples: []
+	};
+}
+/** Start at the selected page's top, fitting its width rather than the whole site. */
+function fitCanvasPage(viewport, page) {
+	const padding = Math.min(24, viewport.width / 4);
+	const scale = Math.max(Number.EPSILON, Math.min(2, (viewport.width - padding * 2) / Math.max(1, page.width)));
+	return {
+		x: (viewport.width - page.width * scale) / 2 - page.left * scale,
+		y: Math.min(108, viewport.height / 3),
+		scale
+	};
+}
+/** Place the same document reading point at the canvas viewport's top edge. */
+function placeCanvasPageAnchor(viewport, page, documentY, scale, frameOffsetY = 0) {
+	return {
+		x: viewport.width / 2 - (page.left + page.width / 2) * scale,
+		y: documentY > 0 ? -(documentY + frameOffsetY) * scale : fitCanvasPage(viewport, page).y,
+		scale
+	};
+}
+/** Reserve readable padding, unscaled Shelf Markers and page headers in the fitted overview. */
+function canvasInsets(viewport) {
+	return {
+		x: Math.min(64, viewport.width / 4),
+		top: Math.min(148, viewport.height / 3),
+		bottom: Math.min(64, viewport.height / 4)
+	};
+}
+function zoomCanvasAt(camera, point, scale, minimumScale = Number.EPSILON, maximumScale = 2) {
+	const nextScale = Math.min(maximumScale, Math.max(minimumScale, scale));
+	if (nextScale === camera.scale) return camera;
+	const ratio = nextScale / camera.scale;
+	return {
+		x: point.x - (point.x - camera.x) * ratio,
+		y: point.y - (point.y - camera.y) * ratio,
+		scale: nextScale
+	};
+}
+function fitCanvas(viewport, content) {
+	const padding = canvasInsets(viewport);
+	const scale = Math.max(Number.EPSILON, Math.min(1, (viewport.width - padding.x * 2) / Math.max(1, content.width), (viewport.height - padding.top - padding.bottom) / Math.max(1, content.height)));
+	return {
+		x: (viewport.width - content.width * scale) / 2,
+		y: (viewport.height + padding.top - padding.bottom - content.height * scale) / 2,
+		scale
+	};
+}
+/** The zoom floor: the complete overview, unless the site is too large to fit above MIN_CANVAS_ZOOM. */
+function canvasMinimumScale(viewport, content) {
+	return Math.max(MIN_CANVAS_ZOOM, fitCanvas(viewport, content).scale);
+}
+/** The most zoomed-out view: the complete overview, or its start at the zoom floor. */
+function canvasOverview(viewport, content) {
+	const fit = fitCanvas(viewport, content);
+	if (fit.scale >= .1) return fit;
+	const padding = canvasInsets(viewport);
+	return constrainCanvasCamera({
+		x: padding.x,
+		y: padding.top,
+		scale: MIN_CANVAS_ZOOM
+	}, viewport, content);
+}
+/**
+* How much of the viewport may be empty canvas beside the content, per side.
+* At half, the content's edges can pan up to the viewport's center and no
+* further, so it never leaves the view at any zoom.
+*/
+const CANVAS_OVERSCROLL = .5;
+/**
+* The limit is in screen space, not world space: zooming out leaves as much
+* empty canvas around the content as zooming in, so it never pulls the view.
+* Content smaller than the empty canvas may also sit anywhere fully in view.
+*/
+function constrainAxis(position, viewport, size, scale) {
+	const length = size * scale;
+	const gap = viewport * CANVAS_OVERSCROLL;
+	return Math.min(Math.max(gap, viewport - length), Math.max(Math.min(viewport - gap - length, 0), position));
+}
+/**
+* Keep the zoom between its limits, and the content in view with bounded empty
+* canvas around it. A stretched camera may zoom up to ZOOM_STRETCH past them.
+*/
+function constrainCanvasCamera(camera, viewport, content, maximumScale = 2, stretched = false) {
+	const minimumScale = canvasMinimumScale(viewport, content);
+	const stretch = stretched ? Math.exp(ZOOM_STRETCH) : 1;
+	const next = zoomCanvasAt(camera, {
+		x: viewport.width / 2,
+		y: viewport.height / 2
+	}, camera.scale, minimumScale / stretch, Math.max(minimumScale, maximumScale) * stretch);
+	return {
+		x: constrainAxis(next.x, viewport.width, content.width, next.scale),
+		y: constrainAxis(next.y, viewport.height, content.height, next.scale),
+		scale: next.scale
+	};
+}
+/** Wheel deltas can be pixels, lines, or pages depending on the input device. */
+function canvasWheelDelta(delta, mode, viewportSize) {
+	if (mode === 1) return delta * 16;
+	if (mode === 2) return delta * viewportSize;
+	return delta;
+}
+
+//#endregion
+export { CANVAS_OVERSCROLL, CANVAS_WHEEL_ZOOM_RATE, MIN_CANVAS_ZOOM, PAN_SNAP_CAPTURE, PAN_SNAP_RELEASE, ZOOM_SNAP_CAPTURE, ZOOM_SNAP_RELEASE, ZOOM_STRETCH, canvasInsets, canvasMaximumScale, canvasMinimumScale, canvasOverview, canvasVerticalRail, canvasWheelDelta, constrainCanvasCamera, findCanvasSnapTarget, fitCanvas, fitCanvasPage, isCanvasCameraSnapped, isCanvasPageScale, placeCanvasPageAnchor, snapCanvasZoom, stretchCanvasZoom, unstretchCanvasZoom, zoomCanvasAt };

package/dist/features/canvas/canvasFlight.js

@@ -0,0 +1,104 @@
+import { canvasMinimumScale, constrainCanvasCamera } from "./canvasCamera.js";
+
+//#region src/features/canvas/canvasFlight.ts
+const MIN_DURATION = 1e3;
+const MAX_DURATION = 2500;
+const ROUTE_VIEW_FRACTION = .5;
+function easeInOut(progress) {
+	if (progress <= .5) return progress ** 3 * (20 + progress * (-45 + progress * (36 - 10 * progress)));
+	const remaining = 1 - progress;
+	return 1 - remaining ** 4 * (15 + remaining * (-24 + 10 * remaining));
+}
+/** Symmetric: speeds up and slows down alike, unlike a flight's long landing. */
+function easeInOutCubic(progress) {
+	return progress < .5 ? 4 * progress ** 3 : 1 - (2 - 2 * progress) ** 3 / 2;
+}
+function interpolate(start, end, progress) {
+	return start * (1 - progress) + end * progress;
+}
+function bezier(start, control, end, progress) {
+	return interpolate(interpolate(start, control, progress), interpolate(control, end, progress), progress);
+}
+/**
+* One quadratic Bezier in world-center/inverse-scale space, with one ease-in-out
+* clock for all coordinates. Inverse scale acts like camera altitude: distant
+* trips arc up and back down continuously, without zoom/travel phases or a
+* cruising plateau. Nearby trips use a straight path.
+*
+* Valid cameras form a convex volume in these coordinates. Constraining the
+* control point (not just each frame) keeps the whole curve in bounds without
+* clipping its motion into hard corners. Callers supply constrained endpoints.
+*/
+/** A pan takes longer the further it goes, in viewport heights, but stays brief. */
+const PAN_MIN_DURATION = 450;
+const PAN_MAX_DURATION = 900;
+const PAN_DURATION_PER_LOG_VIEWPORT = 300;
+/**
+* A straight, eased pan at a constant zoom, such as one that brings a selected
+* block into view. Unlike a flight, it never zooms out on the way.
+*/
+function createCanvasPan(start, end, viewport) {
+	const distance = Math.hypot((end.x - start.x) / Math.max(1, viewport.width), (end.y - start.y) / Math.max(1, viewport.height));
+	if (!distance && start.scale === end.scale) return {
+		duration: 0,
+		at: () => ({ ...start })
+	};
+	return {
+		duration: Math.min(PAN_MAX_DURATION, PAN_MIN_DURATION + PAN_DURATION_PER_LOG_VIEWPORT * Math.log1p(distance)),
+		at(progress) {
+			if (progress <= 0) return { ...start };
+			if (progress >= 1) return { ...end };
+			const motion = easeInOutCubic(progress);
+			return {
+				x: interpolate(start.x, end.x, motion),
+				y: interpolate(start.y, end.y, motion),
+				scale: interpolate(start.scale, end.scale, motion)
+			};
+		}
+	};
+}
+function createCanvasFlight(start, end, viewport, content) {
+	if (start.x === end.x && start.y === end.y && start.scale === end.scale) return {
+		duration: 0,
+		at: () => ({ ...start })
+	};
+	const center = (camera) => ({
+		x: (viewport.width / 2 - camera.x) / camera.scale,
+		y: (viewport.height / 2 - camera.y) / camera.scale,
+		altitude: 1 / camera.scale
+	});
+	const from = center(start);
+	const to = center(end);
+	const dx = Math.abs(to.x - from.x);
+	const dy = Math.abs(to.y - from.y);
+	const endpointScale = Math.min(start.scale, end.scale);
+	const routeScale = Math.min(dx > 0 ? Math.max(1, viewport.width) * ROUTE_VIEW_FRACTION / dx : Infinity, dy > 0 ? Math.max(1, viewport.height) * ROUTE_VIEW_FRACTION / dy : Infinity);
+	const travelScale = Math.max(canvasMinimumScale(viewport, content), Math.min(endpointScale, routeScale));
+	const retreat = travelScale < endpointScale;
+	const startLog = Math.log(start.scale);
+	const endLog = Math.log(end.scale);
+	const controlScale = retreat ? travelScale : 2 / (from.altitude + to.altitude);
+	const control = center(constrainCanvasCamera({
+		x: viewport.width / 2 - interpolate(from.x, to.x, .5) * controlScale,
+		y: viewport.height / 2 - interpolate(from.y, to.y, .5) * controlScale,
+		scale: controlScale
+	}, viewport, content));
+	const distance = Math.hypot(dx * endpointScale / Math.max(1, viewport.width), dy * endpointScale / Math.max(1, viewport.height));
+	return {
+		duration: Math.min(MAX_DURATION, MIN_DURATION + 375 * (Math.log1p(distance) + Math.abs(startLog - endLog))),
+		at(progress) {
+			if (progress <= 0) return { ...start };
+			if (progress >= 1) return { ...end };
+			const motion = easeInOut(progress);
+			const scale = 1 / bezier(from.altitude, control.altitude, to.altitude, motion);
+			return constrainCanvasCamera({
+				x: viewport.width / 2 - bezier(from.x, control.x, to.x, motion) * scale,
+				y: viewport.height / 2 - bezier(from.y, control.y, to.y, motion) * scale,
+				scale
+			}, viewport, content);
+		}
+	};
+}
+
+//#endregion
+export { createCanvasFlight, createCanvasPan };