@m0saic/templates 0.2.0

package/dist/m0saic/web/page-skeleton/v1/layout.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_DEPTH_BUCKETS = exports.DEFAULT_MAX_RECTS = void 0;
+exports.capCaptureRects = capCaptureRects;
+exports.findContainingBlockIds = findContainingBlockIds;
+exports.pruneContainingRects = pruneContainingRects;
+exports.quantizeDepthBuckets = quantizeDepthBuckets;
+exports.computeScaleTransform = computeScaleTransform;
+exports.scaleRectToCanvas = scaleRectToCanvas;
+exports.layoutCapture = layoutCapture;
+exports.projectOverlayLayerCount = projectOverlayLayerCount;
+exports.DEFAULT_MAX_RECTS = 220;
+exports.MAX_DEPTH_BUCKETS = 6;
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+const area = (rect) => rect.w * rect.h;
+function kindEnabled(kind, options) {
+    if (kind === "text")
+        return options.showTextLines !== false;
+    if (kind === "image")
+        return options.showImages !== false;
+    if (kind === "control")
+        return options.showControls !== false;
+    if (kind === "divider")
+        return options.showDividers !== false;
+    return true;
+}
+/**
+ * Apply the renderer-side deterministic cap. Ranking matches the browser
+ * collector, with the capture index as the final stable tie-break.
+ */
+function capCaptureRects(rects, maxRects = exports.DEFAULT_MAX_RECTS) {
+    const cap = Math.max(0, Math.floor(Number.isFinite(maxRects) ? maxRects : exports.DEFAULT_MAX_RECTS));
+    return [...rects]
+        .sort((a, b) => a.d - b.d ||
+        area(b) - area(a) ||
+        a.y - b.y ||
+        a.x - b.x ||
+        b.w - a.w ||
+        b.h - a.h ||
+        a.i - b.i)
+        .slice(0, cap);
+}
+function contains(outer, inner) {
+    return (outer.i !== inner.i &&
+        outer.x <= inner.x &&
+        outer.y <= inner.y &&
+        outer.x + outer.w >= inner.x + inner.w &&
+        outer.y + outer.h >= inner.y + inner.h);
+}
+/** Capture indices of genuinely large wrappers containing several descendants. */
+function findContainingBlockIds(rects, viewport) {
+    const ids = new Set();
+    const viewportArea = viewport.w * viewport.h;
+    for (const candidate of rects) {
+        if (candidate.k !== "block" || area(candidate) < viewportArea * 0.35)
+            continue;
+        let containedCount = 0;
+        for (const other of rects) {
+            if (contains(candidate, other))
+                containedCount++;
+            if (containedCount >= 2) {
+                ids.add(candidate.i);
+                break;
+            }
+        }
+    }
+    return ids;
+}
+/**
+ * Drop only genuinely large painted wrappers: block rects covering at least
+ * 35% of the viewport and containing two or more retained descendants.
+ * Header/sidebar bands and leaf cards therefore survive the pruning knob.
+ */
+function pruneContainingRects(rects, viewport, mode) {
+    if (mode !== "drop")
+        return rects;
+    const containerIds = findContainingBlockIds(rects, viewport);
+    return rects.filter((candidate) => !containerIds.has(candidate.i));
+}
+function viewportBackdropId(rects, viewport) {
+    var _a, _b;
+    const candidates = rects
+        .filter((rect) => rect.k === "block" &&
+        rect.x <= 0 &&
+        rect.y <= 0 &&
+        rect.x + rect.w >= viewport.w &&
+        rect.y + rect.h >= viewport.h)
+        .sort((a, b) => a.d - b.d ||
+        area(b) - area(a) ||
+        a.i - b.i);
+    return (_b = (_a = candidates[0]) === null || _a === void 0 ? void 0 : _a.i) !== null && _b !== void 0 ? _b : null;
+}
+/** Map arbitrary captured depths into at most `maxBuckets` stable z buckets. */
+function quantizeDepthBuckets(rects, maxBuckets = exports.MAX_DEPTH_BUCKETS) {
+    if (rects.length === 0)
+        return [];
+    const bucketCount = Math.max(1, Math.floor(maxBuckets));
+    const depths = [...new Set(rects.map((rect) => rect.d))].sort((a, b) => a - b);
+    const rank = new Map(depths.map((depth, index) => [depth, index]));
+    return rects.map((rect) => {
+        var _a;
+        return ({
+            ...rect,
+            zBucket: Math.min(bucketCount - 1, Math.floor((((_a = rank.get(rect.d)) !== null && _a !== void 0 ? _a : 0) * bucketCount) / depths.length)),
+        });
+    });
+}
+/** Compute capture-viewport → target-canvas scaling and centering. */
+function computeScaleTransform(viewport, canvas, mode) {
+    const scaleX = canvas.w / viewport.w;
+    const scaleY = canvas.h / viewport.h;
+    if (mode === "stretch") {
+        return { scaleX, scaleY, offsetX: 0, offsetY: 0 };
+    }
+    const scale = mode === "fill" ? Math.max(scaleX, scaleY) : Math.min(scaleX, scaleY);
+    return {
+        scaleX: scale,
+        scaleY: scale,
+        offsetX: (canvas.w - viewport.w * scale) / 2,
+        offsetY: (canvas.h - viewport.h * scale) / 2,
+    };
+}
+function forceOnePixel(start, end, rawStart, rawEnd, axisLength) {
+    if (end > start)
+        return [start, end];
+    const center = clamp(Math.round((rawStart + rawEnd) / 2), 0, axisLength - 1);
+    return [center, center + 1];
+}
+/**
+ * Scale with independently-rounded edges, then clip to the canvas. Dividers
+ * alone may recover a collapsed thin axis to one pixel; every other
+ * degenerate rect is dropped.
+ */
+function scaleRectToCanvas(rect, transform, canvas) {
+    const rawX0 = transform.offsetX + rect.x * transform.scaleX;
+    const rawY0 = transform.offsetY + rect.y * transform.scaleY;
+    const rawX1 = transform.offsetX + (rect.x + rect.w) * transform.scaleX;
+    const rawY1 = transform.offsetY + (rect.y + rect.h) * transform.scaleY;
+    if (rawX1 <= 0 || rawY1 <= 0 || rawX0 >= canvas.w || rawY0 >= canvas.h) {
+        return null;
+    }
+    let x0 = clamp(Math.round(rawX0), 0, canvas.w);
+    let y0 = clamp(Math.round(rawY0), 0, canvas.h);
+    let x1 = clamp(Math.round(rawX1), 0, canvas.w);
+    let y1 = clamp(Math.round(rawY1), 0, canvas.h);
+    if (rect.k === "divider") {
+        const horizontal = rect.w >= rect.h;
+        if (horizontal && x1 > x0) {
+            [y0, y1] = forceOnePixel(y0, y1, rawY0, rawY1, canvas.h);
+        }
+        else if (!horizontal && y1 > y0) {
+            [x0, x1] = forceOnePixel(x0, x1, rawX0, rawX1, canvas.w);
+        }
+    }
+    if (x1 <= x0 || y1 <= y0)
+        return null;
+    const scaledRadius = Math.round(rect.r * Math.min(transform.scaleX, transform.scaleY));
+    return {
+        ...rect,
+        x: x0,
+        y: y0,
+        w: x1 - x0,
+        h: y1 - y0,
+        r: clamp(scaledRadius, 0, Math.floor(Math.min(x1 - x0, y1 - y0) / 2)),
+    };
+}
+/** Full pure layout pipeline used by the renderer. */
+function layoutCapture(capture, options) {
+    var _a, _b, _c, _d;
+    const canvasW = Math.max(1, Math.round(options.canvasW));
+    const canvasH = Math.max(1, Math.round(options.canvasH));
+    const indexed = capture.rects.map((rect, i) => ({ ...rect, i }));
+    const visible = indexed.filter((rect) => {
+        var _a;
+        return !((_a = options.hiddenIndices) === null || _a === void 0 ? void 0 : _a.has(rect.i)) &&
+            kindEnabled(rect.k, options);
+    });
+    const capped = capCaptureRects(visible, (_a = options.maxRects) !== null && _a !== void 0 ? _a : exports.DEFAULT_MAX_RECTS);
+    const containerIds = findContainingBlockIds(capped, capture.viewport);
+    const pruned = pruneContainingRects(capped, capture.viewport, (_b = options.containerMode) !== null && _b !== void 0 ? _b : "keep");
+    const backdropId = viewportBackdropId(pruned, capture.viewport);
+    const bucketed = quantizeDepthBuckets(pruned, (_c = options.maxDepthBuckets) !== null && _c !== void 0 ? _c : exports.MAX_DEPTH_BUCKETS).map((rect) => ({
+        ...rect,
+        ...(containerIds.has(rect.i) ? { isSoftContainer: true } : {}),
+        ...(rect.i === backdropId ? { isViewportBackdrop: true } : {}),
+    }));
+    const transform = computeScaleTransform(capture.viewport, { w: canvasW, h: canvasH }, (_d = options.scaleMode) !== null && _d !== void 0 ? _d : "fit");
+    const scaled = bucketed
+        .map((rect) => scaleRectToCanvas(rect, transform, { w: canvasW, h: canvasH }))
+        .filter((rect) => rect !== null);
+    return {
+        rects: scaled,
+        transform,
+        stats: {
+            input: indexed.length,
+            filtered: indexed.length - visible.length,
+            capped: visible.length - capped.length,
+            pruned: capped.length - pruned.length,
+            degenerate: bucketed.length - scaled.length,
+            output: scaled.length,
+        },
+    };
+}
+const projectionOverlaps = (a, b) => a.x < b.x + b.w &&
+    b.x < a.x + a.w &&
+    a.y < b.y + b.h &&
+    b.y < a.y + a.h;
+const yBoundarySubdivides = (divider, divided) => {
+    const top = divider.y;
+    const bottom = divider.y + divider.h;
+    const dividedTop = divided.y;
+    const dividedBottom = divided.y + divided.h;
+    return ((top > dividedTop && top < dividedBottom) ||
+        (bottom > dividedTop && bottom < dividedBottom));
+};
+const projectionConflicts = (a, b) => projectionOverlaps(a, b) ||
+    yBoundarySubdivides(a, b) ||
+    yBoundarySubdivides(b, a);
+/**
+ * Mirror placeRects' importance-bucket + greedy first-fit layer packing.
+ * This is a conservative pre-placement signal; the final composed m0 remains
+ * the source of truth in render tests because inset quantization can add a
+ * collision at a cell boundary.
+ */
+function projectOverlayLayerCount(rects) {
+    var _a, _b;
+    const buckets = new Map();
+    for (const rect of rects) {
+        const bucket = (_a = buckets.get(rect.zBucket)) !== null && _a !== void 0 ? _a : [];
+        bucket.push(rect);
+        buckets.set(rect.zBucket, bucket);
+    }
+    let count = 0;
+    for (const zBucket of [...buckets.keys()].sort((a, b) => a - b)) {
+        const layers = [];
+        for (const rect of (_b = buckets.get(zBucket)) !== null && _b !== void 0 ? _b : []) {
+            const layer = layers.find((candidate) => candidate.every((other) => !projectionConflicts(rect, other)));
+            if (layer)
+                layer.push(rect);
+            else
+                layers.push([rect]);
+        }
+        count += layers.length;
+    }
+    return count;
+}

package/dist/m0saic/web/page-skeleton/v1/page-skeleton.d.ts

@@ -0,0 +1,148 @@
+import type { MosaicCodeValue, MosaicColor, MosaicEffectProps, MosaicSource, MosaicTemplate } from "@m0saic/types";
+import { placeRects } from "@m0saic/dsl-stdlib";
+import { type GeometryExpectation, type InsetPiece } from "@m0saic/template-utils";
+import { type CanvasSkeletonRect, type PageSkeletonContainerMode, type PageSkeletonScaleMode } from "./layout";
+import { type PageSkeletonRectKind } from "./schema";
+export type PageSkeletonAppearance = {
+    /** Page/canvas background. */
+    bg?: string;
+    /** Structural skeleton fill. */
+    fill?: string;
+    /** Text-bar fill. */
+    textFill?: string;
+    /** Image/control fill. */
+    imageFill?: string;
+    /** Shape handling. */
+    radiusMode?: "none" | "captured" | "uniform";
+    /** Uniform radius used when radiusMode is "uniform". */
+    uniformRadiusPx?: number;
+};
+export type PageSkeletonBehavior = {
+    maxRects?: number;
+    showTextLines?: boolean;
+    showImages?: boolean;
+    showControls?: boolean;
+    showDividers?: boolean;
+    scaleMode?: PageSkeletonScaleMode;
+    containerMode?: PageSkeletonContainerMode;
+    /** Emit exact DSL cells instead of quantized cells with recovery insets. */
+    pureRects?: boolean;
+};
+export type PageSkeletonMotionMode = "shimmer" | "pulse";
+export type PageSkeletonMotionDirection = "horizontal" | "diagonal" | "vertical";
+export type PageSkeletonMotion = {
+    /** Loading motion applied when outputFormat is mp4. */
+    mode?: PageSkeletonMotionMode;
+    /** Direction of the travelling shimmer band. */
+    direction?: PageSkeletonMotionDirection;
+    /** Shimmer-band width as a fraction of the canvas axis. */
+    bandWidth?: number;
+    /** Resting opacity of animated skeleton rectangles. */
+    minOpacity?: number;
+};
+export type PageSkeletonV1Props = {
+    /** Exact browser-console script handed from the template to the user. */
+    captureSnippet?: MosaicCodeValue;
+    /** Browser-capture schema v1, provided as parsed JSON or a raw JSON string. */
+    capture: unknown;
+    /** Static PNG or animated MP4. */
+    outputFormat?: "png" | "mp4";
+    motion?: PageSkeletonMotion;
+    appearance?: PageSkeletonAppearance;
+    behavior?: PageSkeletonBehavior;
+    /** P4 customization handshake; declared now so the public prop shape is stable. */
+    overrides?: unknown;
+    /** Run the zero-drift geometry contract and surface drop counts. */
+    debug?: boolean;
+    /** P4 index-label overlay; declared now so the public prop shape is stable. */
+    debugIndices?: boolean;
+};
+export type PageSkeletonRectOverride = {
+    i: number;
+    hide?: boolean;
+    fill?: string;
+    shape?: "rect" | "rounded" | "pill" | "circle";
+    radiusPx?: number;
+};
+/** Parse the jsonModal's object-or-string value and validate capture indices. */
+export declare function parseRectOverrides(value: unknown, rectCount: number): Map<number, PageSkeletonRectOverride>;
+/** Blend two hex colors; non-hex editor values safely retain the base fill. */
+export declare function blendHexColors(base: string, toward: string, towardWeight: number): MosaicColor;
+/**
+ * Keep the skeleton monochrome while making its paint order legible:
+ * containers sit close to the page background; deeper rects step from a
+ * light gray toward the authored fill, with the top bucket darkened slightly.
+ */
+export declare function shadedRectangleFill(rect: Pick<CanvasSkeletonRect, "zBucket" | "isSoftContainer">, fill: MosaicColor, bg: MosaicColor): MosaicColor;
+type ResolvedAppearance = Required<PageSkeletonAppearance>;
+export type PageSkeletonCompositionStats = {
+    independentRects: number;
+    debugLabels: number;
+    projectedLayers: number;
+};
+export type PageSkeletonComposition = {
+    pieces: InsetPiece[];
+    stats: PageSkeletonCompositionStats;
+};
+export type ResolvedPageSkeletonMotion = Required<PageSkeletonMotion>;
+export declare function resolvePageSkeletonMotion(value: PageSkeletonMotion | undefined): ResolvedPageSkeletonMotion;
+/** Canvas-space rank used by the travelling shimmer band. */
+export declare function motionRankForRect(rect: Pick<CanvasSkeletonRect, "x" | "y" | "w" | "h">, canvas: {
+    w: number;
+    h: number;
+}, direction: PageSkeletonMotionDirection): number;
+/**
+ * A one-cycle native-fade color source. The output clip itself is the seamless
+ * cycle: shimmer begins and ends at the resting color; pulse does the same.
+ * Keeping motion inside the tile stream preserves grid lowering, avoiding the
+ * deep per-cell overlay chain that animated `overlay.alpha` would create.
+ */
+export declare function buildPageSkeletonMotionLavfi(fill: MosaicColor, bg: MosaicColor, rank: number, motion: ResolvedPageSkeletonMotion, durationSec: number): string | null;
+/** Resolve the authored per-kind base fill before deterministic depth shading. */
+export declare function baseFillForKind(kind: PageSkeletonRectKind, appearance: ResolvedAppearance): MosaicColor;
+/** Radius in final canvas pixels for the selected appearance mode. */
+export declare function effectiveRadiusPx(rect: Pick<CanvasSkeletonRect, "w" | "h" | "r">, appearance: Pick<ResolvedAppearance, "radiusMode" | "uniformRadiusPx">): number;
+/** Apply the only override that changes geometry: an inscribed centered circle. */
+export declare function overriddenRectGeometry(rect: CanvasSkeletonRect, override: PageSkeletonRectOverride | undefined): CanvasSkeletonRect;
+/** Resolve explicit override shape/radius on top of the appearance default. */
+export declare function overriddenRadiusPx(rect: Pick<CanvasSkeletonRect, "w" | "h" | "r">, appearance: Pick<ResolvedAppearance, "radiusMode" | "uniformRadiusPx">, override: PageSkeletonRectOverride | undefined): number;
+/**
+ * Map a pixel radius to the engine's normalized rounding contract. Near-half
+ * radii become true pills/circles; every real structural tile carries an SVG
+ * rounding effect, including radius zero, so Make can expose its radius knob.
+ */
+export declare function roundingForRect(rect: Pick<CanvasSkeletonRect, "w" | "h">, radiusPx: number): NonNullable<MosaicEffectProps["rounding"]>;
+/**
+ * One retained capture rectangle becomes one real, independently selectable
+ * source and one placement piece. `maxRects` is therefore a literal source
+ * cap; normal skeleton output never hides multiple painted rects in an atlas.
+ */
+export declare function planSkeletonComposition(rects: CanvasSkeletonRect[], appearance: ResolvedAppearance, bg: MosaicColor, canvas: {
+    w: number;
+    h: number;
+}, customization?: {
+    overrides?: ReadonlyMap<number, PageSkeletonRectOverride>;
+    debugIndices?: boolean;
+    motion?: {
+        config: ResolvedPageSkeletonMotion;
+        durationSec: number;
+    };
+}): PageSkeletonComposition;
+export type PageSkeletonPlacementResult = {
+    m0: ReturnType<typeof placeRects>["m0"];
+    sources: MosaicSource[];
+    expectations: GeometryExpectation[];
+};
+/**
+ * Place the composed skeleton through either the efficient inset-recovery
+ * path or exact pure DSL frames. Pure mode intentionally spends more m0 bytes
+ * so source-local custom masks can treat the cell itself as their bounds.
+ */
+export declare function placeSkeletonPieces(options: {
+    rootW: number;
+    rootH: number;
+    pieces: InsetPiece[];
+    pureRects: boolean;
+}): PageSkeletonPlacementResult;
+export declare const PageSkeleton: MosaicTemplate<PageSkeletonV1Props>;
+export default PageSkeleton;