dsh-pf-stream 0.0.0-stage → 0.1.2

package/lib/stage4/canvasPacker.js

@@ -0,0 +1,161 @@
+/**
+ * Stage 4 —— 画布打包（FORM_1..4 拼合 + PNG 字节锁定）。
+ *
+ * 排版规则（《二、双尺度视觉单元与画布形态规范》§3）：
+ * - FORM_1 1344×672：左半区 2×2 排列 4P（P1 左上/P2 右上/P3 左下/P4 右下），右半区 1F；
+ * - FORM_2 672×672：2×2 排列 4P；
+ * - FORM_3 672×672：1F 充满画布；
+ * - FORM_4 1344×672：1~3P 按象限顺序填入，空象限中性灰，右半区 1F。
+ *
+ * 单元视觉标记绘制在单元图像自身（含标记的 F 像素在双载体间逐位一致）。
+ */
+import { createHash } from 'node:crypto';
+import { composeCanvas, encodePng } from '../utils/image.js';
+import { contentHashOfRgb } from '../utils/hash.js';
+import { drawIdBadge, drawSeparators } from './markers.js';
+/** 画布尺寸（宽, 高）。 */
+export function canvasSizeOf(form) {
+    return form === 'FORM_1_STANDARD_STRIP' || form === 'FORM_4_PARTIAL_STRIP' ? [1344, 672] : [672, 672];
+}
+/** 计费序列长度：r×(c+1)+2（画布尺寸为 42 倍数，整除精确）。 */
+export function billTokens(width, height) {
+    const r = height / 42;
+    const c = width / 42;
+    return r * (c + 1) + 2;
+}
+function descriptor(unit, x, y) {
+    const w = unit.image.width;
+    const h = unit.image.height;
+    return {
+        globalId: unit.globalId,
+        timestampMs: unit.ptsMs,
+        scale: unit.scale,
+        eventType: unit.eventType,
+        tokenGridBbox: [y / 42, x / 42, (y + h) / 42, (x + w) / 42],
+        contentPixelBbox: [x, y, x + w, y + h],
+        sourceCropBbox: unit.sourceCropBbox,
+    };
+}
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/**
+ * 打包一个画布包。调用方保证单元数量与形态匹配：
+ * FORM_1=4P+1F，FORM_2=4P，FORM_3=1F，FORM_4=1~3P+1F。
+ */
+export function packCanvas(form, units, options) {
+    const [canvasW, canvasH] = canvasSizeOf(form);
+    const placements = [];
+    const descriptors = [];
+    let anchorBytes = null;
+    let anchorFId = null;
+    let anchorSha = null;
+    let anchorContentHash = null;
+    const pUnits = units.filter((u) => u.scale === '1x1_P');
+    const fUnits = units.filter((u) => u.scale === '2x2_F');
+    const fUnit = fUnits[0] ?? null;
+    // 单元标记：隔离线 + 反色角标（绘制在单元图像副本上）
+    const marked = units.map((u) => {
+        const image = { width: u.image.width, height: u.image.height, data: Buffer.from(u.image.data) };
+        drawSeparators(image, [{ x: 0, y: 0, w: image.width, h: image.height }]);
+        if (options.renderVisualId)
+            drawIdBadge(image, 0, 0, u.globalId);
+        return { ...u, image };
+    });
+    if (form === 'FORM_1_STANDARD_STRIP') {
+        if (pUnits.length !== 4 || !fUnit)
+            throw new Error('FORM_1 需要 4P+1F');
+        for (let i = 0; i < 4; i++) {
+            const u = marked[i];
+            const { x, y } = { x: (i % 2) * 336, y: Math.floor(i / 2) * 336 };
+            placements.push({ x, y, image: u.image });
+            descriptors.push(descriptor(u, x, y));
+        }
+        const f = marked[4];
+        placements.push({ x: 672, y: 0, image: f.image });
+        descriptors.push(descriptor(f, 672, 0));
+    }
+    else if (form === 'FORM_2_COMPACT_4P') {
+        if (pUnits.length !== 4)
+            throw new Error('FORM_2 需要 4P');
+        for (let i = 0; i < 4; i++) {
+            const u = marked[i];
+            const x = (i % 2) * 336;
+            const y = Math.floor(i / 2) * 336;
+            placements.push({ x, y, image: u.image });
+            descriptors.push(descriptor(u, x, y));
+        }
+    }
+    else if (form === 'FORM_3_COMPACT_1F') {
+        if (!fUnit)
+            throw new Error('FORM_3 需要 1F');
+        const f = marked[0];
+        placements.push({ x: 0, y: 0, image: f.image });
+        descriptors.push(descriptor(f, 0, 0));
+    }
+    else {
+        // FORM_4_PARTIAL_STRIP：1~3P + 1F
+        if (pUnits.length < 1 || pUnits.length > 3 || !fUnit)
+            throw new Error('FORM_4 需要 1~3P+1F');
+        for (let i = 0; i < pUnits.length; i++) {
+            const u = marked[i];
+            const x = (i % 2) * 336;
+            const y = Math.floor(i / 2) * 336;
+            placements.push({ x, y, image: u.image });
+            descriptors.push(descriptor(u, x, y));
+        }
+        const f = marked[marked.length - 1];
+        placements.push({ x: 672, y: 0, image: f.image });
+        descriptors.push(descriptor(f, 672, 0));
+    }
+    const canvas = composeCanvas(canvasW, canvasH, placements);
+    const imageBytes = encodePng(canvas);
+    if (fUnit) {
+        anchorFId = fUnit.globalId;
+        const fMarked = marked.find((u) => u.scale === '2x2_F');
+        anchorBytes = encodePng(fMarked.image);
+        anchorSha = sha256(anchorBytes);
+        anchorContentHash = contentHashOfRgb(fMarked.image.width, fMarked.image.height, fMarked.image.data);
+    }
+    const stripSha = form === 'FORM_3_COMPACT_1F' ? null : sha256(imageBytes);
+    const packet = {
+        packetId: options.packetId,
+        canvasSize: [canvasW, canvasH],
+        layoutForm: form,
+        triggerPath: options.triggerPath,
+        historyMode: 'initial',
+        anchorOnlyRefPacketId: null,
+        spatialRemap: null,
+        anchorFId,
+        anchorFSha256: anchorSha,
+        stripSha256: stripSha,
+        appliedIntentId: options.appliedIntentId,
+        appliedCtrlId: options.appliedCtrlId ?? [],
+        units: descriptors,
+    };
+    return { packet, imageBytes, anchorBytes, anchorFContentHash: anchorContentHash };
+}
+/** 时序提示行位置标签。 */
+export function slotLabel(form, index, isF) {
+    if (isF)
+        return form === 'FORM_3_COMPACT_1F' ? 'Full-Canvas' : 'Right-Half';
+    const labels = ['Left-Top', 'Right-Top', 'Left-Bottom', 'Right-Bottom'];
+    return labels[index] ?? 'Left-Top';
+}
+/** 生成结构化时序映射提示行（首次发包 / 确定性格式）。 */
+export function timelineHintLine(packet, roi) {
+    const parts = packet.units.map((u, i) => {
+        const t = `${(u.timestampMs / 1000).toFixed(1)}s`;
+        const isF = u.scale === '2x2_F';
+        const slot = slotLabel(packet.layoutForm, i, isF);
+        const roiPart = isF && packet.triggerPath === 'DETERMINISTIC' && roi
+            ? `, ROI:[${roi.x},${roi.y},${roi.w},${roi.h}]`
+            : '';
+        return `#${u.globalId}(${isF ? 'F' : 'P'}, ${t}${roiPart}, ${slot})`;
+    });
+    const body = parts.join(' -> ');
+    const anchor = packet.anchorFId != null ? `Anchor: #${packet.anchorFId} | ` : '';
+    const mode = packet.triggerPath === 'DETERMINISTIC' ? 'Mode: DETERMINISTIC | ' : '';
+    return `[Packet #${packet.packetId} | ${mode}${anchor}${body}]`;
+}
+//# sourceMappingURL=canvasPacker.js.map

package/lib/stage4/canvasPacker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvasPacker.js","sourceRoot":"","sources":["../../src/stage4/canvasPacker.ts"],"names":[],"mappings":"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"}

package/lib/stage4/markers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 消费端视觉标记（《六、发包控制…》§4）：
+ * - 双色高对比内缩隔离线：单元边缘向内侧 2px（外层 1px 深色 RGB(32,32,32) + 内层 1px 亮色 RGB(224,224,224)）；
+ * - 左上角超像素微型反色角标：每单元首个 42×42 超像素内反色胶囊渲染 #global_id（renderVisualId 开关）。
+ */
+import type { RgbImage } from '../utils/image.js';
+export interface UnitBbox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** 在画布上为指定单元区域绘制双色内缩隔离线。 */
+export declare function drawSeparators(canvas: RgbImage, boxes: UnitBbox[]): void;
+/**
+ * 反色胶囊角标：在 (originX, originY) 起始的 42×42 超像素内，
+ * 对胶囊区域逐像素反色，字型位保持原色（双重反色，高对比）。
+ */
+export declare function drawIdBadge(canvas: RgbImage, originX: number, originY: number, globalId: number): void;

package/lib/stage4/markers.js

@@ -0,0 +1,98 @@
+/**
+ * 消费端视觉标记（《六、发包控制…》§4）：
+ * - 双色高对比内缩隔离线：单元边缘向内侧 2px（外层 1px 深色 RGB(32,32,32) + 内层 1px 亮色 RGB(224,224,224)）；
+ * - 左上角超像素微型反色角标：每单元首个 42×42 超像素内反色胶囊渲染 #global_id（renderVisualId 开关）。
+ */
+const SEPARATOR_DARK = 32;
+const SEPARATOR_LIGHT = 224;
+/** 在画布上为指定单元区域绘制双色内缩隔离线。 */
+export function drawSeparators(canvas, boxes) {
+    const { width: cw, height: ch, data } = canvas;
+    for (const b of boxes) {
+        // 外层 1px 深色（单元边缘内侧）
+        fillRect(data, cw, ch, b.x, b.y, b.w, 1, SEPARATOR_DARK);
+        fillRect(data, cw, ch, b.x, b.y + b.h - 1, b.w, 1, SEPARATOR_DARK);
+        fillRect(data, cw, ch, b.x, b.y, 1, b.h, SEPARATOR_DARK);
+        fillRect(data, cw, ch, b.x + b.w - 1, b.y, 1, b.h, SEPARATOR_DARK);
+        // 内层 1px 亮色
+        fillRect(data, cw, ch, b.x + 1, b.y + 1, b.w - 2, 1, SEPARATOR_LIGHT);
+        fillRect(data, cw, ch, b.x + 1, b.y + b.h - 2, b.w - 2, 1, SEPARATOR_LIGHT);
+        fillRect(data, cw, ch, b.x + 1, b.y + 1, 1, b.h - 2, SEPARATOR_LIGHT);
+        fillRect(data, cw, ch, b.x + b.w - 2, b.y + 1, 1, b.h - 2, SEPARATOR_LIGHT);
+    }
+}
+function fillRect(data, cw, ch, x, y, w, h, value) {
+    for (let dy = 0; dy < h; dy++) {
+        const py = y + dy;
+        if (py < 0 || py >= ch)
+            continue;
+        for (let dx = 0; dx < w; dx++) {
+            const px = x + dx;
+            if (px < 0 || px >= cw)
+                continue;
+            const i = (py * cw + px) * 3;
+            data[i] = value;
+            data[i + 1] = value;
+            data[i + 2] = value;
+        }
+    }
+}
+/** 3×5 位图字型（# 与数字）。 */
+const GLYPHS = {
+    '#': ['101', '111', '101', '111', '101'],
+    '0': ['111', '101', '101', '101', '111'],
+    '1': ['010', '110', '010', '010', '111'],
+    '2': ['111', '001', '111', '100', '111'],
+    '3': ['111', '001', '111', '001', '111'],
+    '4': ['101', '101', '111', '001', '001'],
+    '5': ['111', '100', '111', '001', '111'],
+    '6': ['111', '100', '111', '101', '111'],
+    '7': ['111', '001', '001', '001', '001'],
+    '8': ['111', '101', '111', '101', '111'],
+    '9': ['111', '101', '111', '001', '111'],
+};
+/**
+ * 反色胶囊角标：在 (originX, originY) 起始的 42×42 超像素内，
+ * 对胶囊区域逐像素反色，字型位保持原色（双重反色，高对比）。
+ */
+export function drawIdBadge(canvas, originX, originY, globalId) {
+    const text = `#${globalId}`;
+    const { width: cw, height: ch, data } = canvas;
+    const boxX = originX + 4;
+    const boxY = originY + 4;
+    const boxW = 34;
+    const boxH = 34;
+    const glyphW = 3;
+    const glyphH = 5;
+    const totalW = text.length * glyphW + (text.length - 1);
+    const startX = boxX + Math.floor((boxW - totalW) / 2);
+    const startY = boxY + Math.floor((boxH - glyphH) / 2);
+    for (let dy = 0; dy < boxH; dy++) {
+        for (let dx = 0; dx < boxW; dx++) {
+            const px = boxX + dx;
+            const py = boxY + dy;
+            if (px < 0 || px >= cw || py < 0 || py >= ch)
+                continue;
+            // 角落切角（近似圆角胶囊）
+            const corner = Math.min(dx, dy, boxW - 1 - dx, boxH - 1 - dy);
+            if (corner < 3 && (dx < 3 || dx > boxW - 4) && (dy < 3 || dy > boxH - 4))
+                continue;
+            const gx = dx - (startX - boxX);
+            const gy = dy - (startY - boxY);
+            const cell = gx % (glyphW + 1);
+            const charIdx = Math.floor(gx / (glyphW + 1));
+            const glyph = charIdx >= 0 && charIdx < text.length ? GLYPHS[text[charIdx]] : undefined;
+            const glyphOn = glyph !== undefined && gy >= 0 && gy < glyphH && cell < glyphW && glyph[gy][cell] === '1';
+            const i = (py * cw + px) * 3;
+            if (glyphOn)
+                continue; // 字型位保持原色
+            const r = data[i];
+            const g = data[i + 1];
+            const b = data[i + 2];
+            data[i] = 255 - r;
+            data[i + 1] = 255 - g;
+            data[i + 2] = 255 - b;
+        }
+    }
+}
+//# sourceMappingURL=markers.js.map

package/lib/stage4/markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.js","sourceRoot":"","sources":["../../src/stage4/markers.ts"],"names":[],"mappings":"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"}

package/lib/stage4/viewport.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 契约 1/2/4 —— 视窗归一化（显示坐标系）。
+ *
+ * 规则（《四、采样逻辑…》§3 与契约 4 四步归一化）：
+ * - roi_hint 或运动质心 → 1:1 正方形视窗（边长 = min(源短边, 包络目标区) 向下取整到 42 倍数，硬下限 84），
+ *   缩放后 100% 填满槽位，零灰边；
+ * - 全局/ full_frame → 等比内接 + 内容宽高量化到 42 倍数，居中灰补边（偏置对齐 42 网格）；
+ * - 短边 ≥84 为硬约束（面积预算为软约束）；
+ * - 源域外扩优先；外扩受物理边界限制仍不足 → 内容级中性灰补边并置 pad_overflow。
+ */
+import type { RoiHint } from '../types.js';
+import { type RgbImage } from '../utils/image.js';
+/** 超像素模数。 */
+export declare const SUPERPIXEL = 42;
+/** 有效短边硬下限（2 个超像素步长）。 */
+export declare const MIN_SHORT_SIDE = 84;
+export type SlotKind = 'P' | 'F';
+export interface ViewportPlan {
+    /** 源视频显示坐标系采样区域 [x, y, w, h]（w/h 亦为 42 倍数）。 */
+    sourceCropBbox: [number, number, number, number];
+    /** 目标内容宽高（42 倍数；RoI 路径等于槽位边长）。 */
+    targetW: number;
+    targetH: number;
+    /** 画布槽位内内容偏移（42 倍数）。 */
+    offsetX: number;
+    offsetY: number;
+    /** 源域不足时内容级补边像素数（上/下/左/右）。 */
+    pad: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    /** 内容区出现源域补边时为 true。 */
+    padOverflow: boolean;
+}
+export declare function quant42Floor(v: number): number;
+export declare function quant42Round(v: number): number;
+export declare function slotSize(slot: SlotKind): number;
+export interface ViewportInput {
+    displayWidth: number;
+    displayHeight: number;
+    roi?: RoiHint | undefined;
+    fullFrame: boolean;
+    slot: SlotKind;
+}
+/**
+ * 生成视窗计划。调用方保证 displayWidth/Height > 0。
+ */
+export declare function planViewport(input: ViewportInput): ViewportPlan;
+/** 规格化 roi 到显示像素矩形并钳制到 [0,1]。 */
+export declare function roiToPixels(roi: RoiHint, displayWidth: number, displayHeight: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * 按视窗计划把源帧变换为槽位内容图（槽位尺寸，含内容级补边与居中灰）。
+ */
+export declare function applyViewport(src: RgbImage, plan: ViewportPlan, slot: SlotKind): RgbImage;

package/lib/stage4/viewport.js

@@ -0,0 +1,151 @@
+/**
+ * 契约 1/2/4 —— 视窗归一化（显示坐标系）。
+ *
+ * 规则（《四、采样逻辑…》§3 与契约 4 四步归一化）：
+ * - roi_hint 或运动质心 → 1:1 正方形视窗（边长 = min(源短边, 包络目标区) 向下取整到 42 倍数，硬下限 84），
+ *   缩放后 100% 填满槽位，零灰边；
+ * - 全局/ full_frame → 等比内接 + 内容宽高量化到 42 倍数，居中灰补边（偏置对齐 42 网格）；
+ * - 短边 ≥84 为硬约束（面积预算为软约束）；
+ * - 源域外扩优先；外扩受物理边界限制仍不足 → 内容级中性灰补边并置 pad_overflow。
+ */
+import { PAD_GRAY, bilinearResize, cropWithGrayFallback } from '../utils/image.js';
+/** 超像素模数。 */
+export const SUPERPIXEL = 42;
+/** 有效短边硬下限（2 个超像素步长）。 */
+export const MIN_SHORT_SIDE = 84;
+export function quant42Floor(v) {
+    return Math.floor(v / SUPERPIXEL) * SUPERPIXEL;
+}
+export function quant42Round(v) {
+    return Math.floor(v / SUPERPIXEL + 0.5) * SUPERPIXEL;
+}
+export function slotSize(slot) {
+    return slot === 'P' ? 336 : 672;
+}
+/**
+ * 生成视窗计划。调用方保证 displayWidth/Height > 0。
+ */
+export function planViewport(input) {
+    const slot = slotSize(input.slot);
+    const shortSide = Math.min(input.displayWidth, input.displayHeight);
+    if (!input.fullFrame && input.roi) {
+        return planSquareViewport(input, slot, shortSide);
+    }
+    return planInscribeViewport(input, slot);
+}
+function clamp01(v) {
+    return Math.min(Math.max(v, 0), 1);
+}
+/** 规格化 roi 到显示像素矩形并钳制到 [0,1]。 */
+export function roiToPixels(roi, displayWidth, displayHeight) {
+    const x0 = clamp01(Math.min(roi.x, roi.x + roi.w));
+    const y0 = clamp01(Math.min(roi.y, roi.y + roi.h));
+    const x1 = clamp01(Math.max(roi.x, roi.x + roi.w));
+    const y1 = clamp01(Math.max(roi.y, roi.y + roi.h));
+    return {
+        x: Math.round(x0 * displayWidth),
+        y: Math.round(y0 * displayHeight),
+        w: Math.max(1, Math.round((x1 - x0) * displayWidth)),
+        h: Math.max(1, Math.round((y1 - y0) * displayHeight)),
+    };
+}
+function planSquareViewport(input, slot, shortSide) {
+    const roi = roiToPixels(input.roi, input.displayWidth, input.displayHeight);
+    const envelope = Math.max(roi.w, roi.h);
+    // 边长：min(源短边, 包络目标区)，向下取整 42 倍数；硬下限 84（源域外扩优先）。
+    let side = quant42Floor(Math.min(shortSide, envelope));
+    let padOverflow = false;
+    let pad = { top: 0, bottom: 0, left: 0, right: 0 };
+    if (side < MIN_SHORT_SIDE) {
+        side = MIN_SHORT_SIDE;
+        if (side > quant42Floor(shortSide)) {
+            // 源短边物理上不足 84：内容级补边（源域外扩到物理边界仍不足）
+            padOverflow = true;
+        }
+    }
+    // 视窗中心 = RoI 中心，钳制到源内；起始坐标对齐 42 网格
+    const cx = roi.x + roi.w / 2;
+    const cy = roi.y + roi.h / 2;
+    let x = quant42Floor(Math.round(cx - side / 2));
+    let y = quant42Floor(Math.round(cy - side / 2));
+    x = Math.min(Math.max(x, 0), Math.max(0, input.displayWidth - side));
+    y = Math.min(Math.max(y, 0), Math.max(0, input.displayHeight - side));
+    x = quant42Floor(x);
+    y = quant42Floor(y);
+    // 越界侧记录内容级补边（源域不足的方向）
+    const overRight = x + side - input.displayWidth;
+    const overBottom = y + side - input.displayHeight;
+    if (overRight > 0) {
+        pad = { ...pad, right: overRight };
+        padOverflow = true;
+    }
+    if (overBottom > 0) {
+        pad = { ...pad, bottom: overBottom };
+        padOverflow = true;
+    }
+    return {
+        sourceCropBbox: [x, y, side, side],
+        targetW: slot,
+        targetH: slot,
+        offsetX: 0,
+        offsetY: 0,
+        pad,
+        padOverflow,
+    };
+}
+function planInscribeViewport(input, slot) {
+    const { displayWidth: w, displayHeight: h } = input;
+    const budget = slot * slot;
+    const k = Math.min(slot / w, slot / h, Math.sqrt(budget / (w * h)));
+    let targetW = Math.min(quant42Round(w * k), slot);
+    let targetH = Math.min(quant42Round(h * k), slot);
+    // 短边硬约束（软面积预算让位）
+    if (targetW < MIN_SHORT_SIDE)
+        targetW = Math.min(MIN_SHORT_SIDE, quant42Floor(slot));
+    if (targetH < MIN_SHORT_SIDE)
+        targetH = Math.min(MIN_SHORT_SIDE, quant42Floor(slot));
+    // 内接居中，偏置对齐 42 网格
+    const offsetX = quant42Floor((slot - targetW) / 2);
+    const offsetY = quant42Floor((slot - targetH) / 2);
+    return {
+        sourceCropBbox: [0, 0, w, h],
+        targetW,
+        targetH,
+        offsetX,
+        offsetY,
+        pad: {
+            top: offsetY,
+            bottom: slot - targetH - offsetY,
+            left: offsetX,
+            right: slot - targetW - offsetX,
+        },
+        padOverflow: false,
+    };
+}
+/**
+ * 按视窗计划把源帧变换为槽位内容图（槽位尺寸，含内容级补边与居中灰）。
+ */
+export function applyViewport(src, plan, slot) {
+    const slotSide = slotSize(slot);
+    const [cx, cy, cw, ch] = plan.sourceCropBbox;
+    const cropped = cropWithGrayFallback(src, cx, cy, cw, ch);
+    const scaled = bilinearResize(cropped, plan.targetW, plan.targetH);
+    if (plan.targetW === slotSide && plan.targetH === slotSide)
+        return scaled;
+    // 非满槽（全画幅内接）：居中放置，四周中性灰
+    const canvas = { width: slotSide, height: slotSide, data: Buffer.alloc(slotSide * slotSide * 3, PAD_GRAY) };
+    for (let dy = 0; dy < plan.targetH; dy++) {
+        for (let dx = 0; dx < plan.targetW; dx++) {
+            const si = (dy * plan.targetW + dx) * 3;
+            const di = ((plan.offsetY + dy) * slotSide + plan.offsetX + dx) * 3;
+            const r = scaled.data[si];
+            const g = scaled.data[si + 1];
+            const b = scaled.data[si + 2];
+            canvas.data[di] = r;
+            canvas.data[di + 1] = g;
+            canvas.data[di + 2] = b;
+        }
+    }
+    return canvas;
+}
+//# sourceMappingURL=viewport.js.map

package/lib/stage4/viewport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport.js","sourceRoot":"","sources":["../../src/stage4/viewport.ts"],"names":[],"mappings":"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"}

package/lib/stage5/controller.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Stage 5（内容自闭环层）—— R1-R4 规则与 500ms PTS 节拍平滑（规格《五》§2）。
+ *
+ * 优先级 R3 > R1 > R2 > R4：R3 频闪抑制激活期间冻结 R1/R2 的新触发；
+ * R1/R2/R3 以 ΔPTS ≥ 500ms 为更新节拍，执行一阶平滑 θ_new = clamp(0.6·target + 0.4·curr)；
+ * R4 在 SWITCH 触发时刻零延迟直写 T_settle_eff = 80ms，恢复走双路径
+ * （① 首个 MOTION；② STATIC 稳定满 T_settle_base），独立于节拍。
+ *
+ * 生效值写入 live（StreamBaselines 可变引用），streamSampler 每步直接读取；
+ * 基准值 base 保持不变，供遥测与恢复使用。
+ */
+import { type StreamBaselines } from './intent.js';
+import type { ControllerSnapshot, CtrlTickLogEntry } from '../types.js';
+export declare const CTRL_TICK_MS = 500;
+export declare const R3_FLIP_TRIGGER_FRAMES = 5;
+export declare const R3_FLIP_RECOVER_FRAMES = 10;
+export declare const R4_SETTLE_MS = 80;
+export declare class StreamController {
+    /** 当前生效参数（原地变更，采样器直接读取）。 */
+    readonly live: StreamBaselines;
+    private readonly base;
+    private r1Active;
+    private r2Active;
+    private r3Active;
+    private r4Active;
+    private sTarget;
+    private tCoolTarget;
+    private hHighTarget;
+    private readonly ctrlId;
+    private readonly seq;
+    private lastTickPtsMs;
+    private readonly dHist;
+    private rFlipRun;
+    private rFlipCalmRun;
+    private r1CondSincePtsMs;
+    private r2CondSincePtsMs;
+    private lastState;
+    private stateSincePtsMs;
+    /** 每 500ms 节拍的生效值轨迹（遥测断言用）。 */
+    readonly tickLog: CtrlTickLogEntry[];
+    constructor(baselines: StreamBaselines, initialPtsMs?: number, snapshot?: ControllerSnapshot);
+    /** SWITCH 效果：R4 零延迟直写（规格《三》§3 原子步骤 5）。 */
+    onSwitch(ptsMs: number): void;
+    /**
+     * 每个步进帧调用：r_flip 连续计数、状态迁移（R4 恢复路径与 R1/R2 退场）、
+     * 500ms 节拍上的 R3→R1→R2 求值与一阶平滑。
+     */
+    onFrameStepped(ptsMs: number, d: number, rFlip: number, machineState: 'STATIC' | 'MOTION' | 'SETTLE' | 'SWITCH'): void;
+    /** R3 激活期间 α 锁定 0.1（规格 R3 调节动作）。 */
+    alphaFor(signalAlpha: number): number;
+    /** 当前激活规则的 ctrl_id 列表（发包回填 applied_ctrl_id）。 */
+    activeCtrlIds(): string[];
+    activeSlugs(): string[];
+    snapshot(): ControllerSnapshot;
+    private restore;
+    private isActive;
+    private deactivateR1;
+    private deactivateR2;
+    private recoverR4;
+    private nextId;
+}